From cd6bd5c1882b455df0574f2d3dc260f3cdd67419 Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Tue, 4 Aug 2026 11:48:34 +0800
Subject: [PATCH 001/262] fix(llm): honor DeepSeek SSE keep-alives

---
 ...-21-bounded-llm-request-recovery.i18n.yaml |  4 +--
 ...2026-06-21-bounded-llm-request-recovery.md |  4 +--
 ...6-06-21-bounded-llm-request-recovery.zh.md |  4 +--
 .../fixtures/deepseek-defaults.cordis.yml     |  1 +
 .../headless-agent/tests/headless.snapshot.ts | 23 +++++++++----
 packages/llm/llm-deepseek/README.i18n.yaml    |  4 +--
 packages/llm/llm-deepseek/README.md           |  2 +-
 packages/llm/llm-deepseek/README.zh.md        |  2 +-
 packages/llm/llm-deepseek/src/adapter.ts      | 11 ++++--
 packages/llm/llm-deepseek/src/sse.ts          | 19 +++++++----
 .../llm/llm-deepseek/tests/adapter.spec.ts    | 34 +++++++++++++++++++
 packages/llm/llm-deepseek/tests/sse.spec.ts   | 10 ++++++
 packages/util/timeout/README.i18n.yaml        |  4 +--
 packages/util/timeout/README.md               |  4 +--
 packages/util/timeout/README.zh.md            |  4 +--
 packages/util/timeout/src/index.ts            | 17 ++++++++--
 packages/util/timeout/tests/timeout.spec.ts   | 22 ++++++++++++
 17 files changed, 134 insertions(+), 35 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index bf6f030683..d527bb9e7b 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
-2026-06-21-bounded-llm-request-recovery.md: 24725dcf300cf69e9cc72580d0c8afe937d4e2b9
-2026-06-21-bounded-llm-request-recovery.zh.md: 5f03a65b00be8d3349addce82e4f3faa2af1fe7e
+2026-06-21-bounded-llm-request-recovery.md: 122f30118ebe3f213a887e56a9d3505e78b23070
+2026-06-21-bounded-llm-request-recovery.zh.md: 8af62cef952eba929dd770df15fdc0666f575666
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
index 24725dcf30..122f30118e 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
@@ -74,9 +74,9 @@ Adapters perform one provider request per `stream()` call. The pi-ai adapter rem
 
 ### Bound stalled streams where they can be stopped
 
-Each adapter exposes a validated `streamIdleTimeoutMs` configuration field with the five-minute prior-art default cited above. The interval is capped at Node's maximum timer delay so it cannot be clamped to one millisecond. It covers each outstanding iterator `next()` from demand to the next valid `StreamChunk`; time a consumer spends between `next()` calls is not provider idle time.
+Each adapter exposes a validated `streamIdleTimeoutMs` configuration field with the five-minute prior-art default cited above. The interval is capped at Node's maximum timer delay so it cannot be clamped to one millisecond. It covers each outstanding iterator `next()` from demand to adapter-recognized provider activity; time a consumer spends between `next()` calls is not provider idle time. DeepSeek SSE comments count as transport activity but never become `StreamChunk` values or session-log events.
 
-`@deepseek-ai/dsh-timeout` exposes a rearmable idle-watchdog primitive. One stable local `AbortController` is fused with the caller signal and passed to the transport for the whole adapter call; each outstanding `next()` arms the watchdog, resolution disarms it, and the next demand rearms it. Timeout aborts that stable controller with a capability-owned `TimeoutReason`, and `finally` clears the timer. The adapter classifies its watchdog as `TIMEOUT` and an earlier upstream abort as `ABORTED`. The existing one-shot `deadline()` is not presented as a sliding timer.
+`@deepseek-ai/dsh-timeout` exposes a rearmable idle-watchdog primitive. One stable local `AbortController` is fused with the caller signal and passed to the transport for the whole adapter call; each outstanding `next()` arms the watchdog, resolution disarms it, and the next demand rearms it. Out-of-band transport activity calls `pulse()` to rearm an outstanding demand without yielding a value. Timeout aborts that stable controller with a capability-owned `TimeoutReason`, and `finally` clears the timer. The adapter classifies its watchdog as `TIMEOUT` and an earlier upstream abort as `ABORTED`. The existing one-shot `deadline()` is not presented as a sliding timer.
 
 Boundary tests prove termination at both actual transports. The hand-written adapter aborts its fetch/reader, and the pi-ai adapter maps the stable signal through the SDK and proves the SDK closes the response. A timer that merely rejects a consumer promise while leaving the request running does not satisfy the contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index 5f03a65b00..8af62cef95 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -74,9 +74,9 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 
 ### 在能够终止停滞流的位置施加边界
 
-每个适配器都公开一个经过验证的 `streamIdleTimeoutMs` 配置字段，默认值采用上文引用的五分钟先例。该间隔不超过 Node 的最大定时器延迟，因此不会被钳制为 1 毫秒。它覆盖每个尚未完成的迭代器 `next()`：从消费方请求下一项开始，到下一条有效 `StreamChunk` 到达为止；消费方在两次 `next()` 调用之间花费的时间不属于提供方空闲时间。
+每个适配器都公开一个经过验证的 `streamIdleTimeoutMs` 配置字段，默认值采用上文引用的五分钟先例。该间隔不超过 Node 的最大定时器延迟，因此不会被钳制为 1 毫秒。它覆盖每个尚未完成的迭代器 `next()`：从消费方请求下一项开始，到适配器识别到提供方活动为止；消费方在两次 `next()` 调用之间花费的时间不属于提供方空闲时间。DeepSeek SSE（Server-Sent Events）注释计为传输活动，但绝不会成为 `StreamChunk` 值或会话日志事件。
 
-`@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。
+`@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。带外传输活动会调用 `pulse()`，在不产生值的情况下为尚未完成的需求重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。
 
 边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此契约。
 
diff --git a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
index cd472f737d..829af9f813 100644
--- a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
@@ -8,6 +8,7 @@
           apiKey: snapshot-key
           baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
           thinking: disabled
+          streamIdleTimeoutMs: 100
       - id: cli-agent
         config:
           provider: deepseek-official
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 8b48165a83..fd1bbd3086 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -66,12 +66,21 @@ async function deepseekDefaultsServer(): Promise<DeepSeekDefaultsServer> {
     request.on('end', () => {
       requests.push(JSON.parse(body) as JsonObject)
       response.writeHead(200, { 'content-type': 'text/event-stream' })
-      response.end([
-        'data: {"choices":[{"delta":{"content":"DEFAULTS_OK"}}]}',
-        'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
-        'data: [DONE]',
-        '',
-      ].join('\n\n'))
+      let keepAlives = 3
+      const write = (): void => {
+        if (keepAlives-- > 0) {
+          response.write(': keep-alive\n\n')
+          setTimeout(write, 60)
+          return
+        }
+        response.end([
+          'data: {"choices":[{"delta":{"content":"DEFAULTS_OK"}}]}',
+          'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
+          'data: [DONE]',
+          '',
+        ].join('\n\n'))
+      }
+      setTimeout(write, 60)
     })
   })
   await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
@@ -297,7 +306,7 @@ describe('headless stream-json snapshots', () => {
     `)
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('logs and sends the DeepSeek adapter maxTokens default through the one-shot app', async () => {
+  it('keeps provider comments alive and sends DeepSeek defaults through the one-shot app', async () => {
     const server = await deepseekDefaultsServer()
     try {
       const result = await runLoaderSmoke({
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 45d9cee054..cb18c83eff 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: 020aa65073495526be3f32912b7cd06667c52a2e
-README.zh.md: 4c655e90ba00340c056f6ac16159621f7a8c1ddb
+README.md: 2ecdb4330e5871bbaf0da6fc583083a06c935486
+README.zh.md: 63eb7be330806b668e12867ed906d0d88acaff1f
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 020aa65073..2ecdb4330e 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -46,7 +46,7 @@ The same exact-model result exposes ordered `off`, `high`, and `max` efforts und
 
 `thinking: disabled` is a deployment lock that publishes only `off` with `off` as its default. Omitting `reasoningEffort` or configuring it as `off` is valid; configuring `high` or `max` fails plugin loading, and a direct per-request attempt to enable thinking fails before network I/O. A request with `GenerateOptions.purpose: 'session-title'` also forces thinking disabled and omits the already-resolved effort, reserving its bounded output for visible title text without changing conversation or compaction defaults.
 
-`streamIdleTimeoutMs` bounds each outstanding provider read, including the initial `fetch`, without counting time the consumer spends between chunks. One stable abort signal reaches the request and body reader for the whole call; expiry stops the transport and throws `LlmError('TIMEOUT')`, while an earlier caller abort throws `LlmError('ABORTED')`. The adapter makes exactly one provider request per `stream()` call; it registers the configured policy as provider metadata, and `dsh-llm-retry` separately executes it at durable agent-step boundaries.
+`streamIdleTimeoutMs` bounds each outstanding provider read, including the initial `fetch`, without counting time the consumer spends between chunks. DeepSeek SSE comments rearm an outstanding read as transport activity but never become `StreamChunk` values or session-log events. One stable abort signal reaches the request and body reader for the whole call; expiry stops the transport and throws `LlmError('TIMEOUT')`, while an earlier caller abort throws `LlmError('ABORTED')`. The adapter makes exactly one provider request per `stream()` call; it registers the configured policy as provider metadata, and `dsh-llm-retry` separately executes it at durable agent-step boundaries.
 
 ## Dynamic configuration (settings + credentials)
 
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 4c655e90ba..63eb7be330 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -46,7 +46,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 `thinking: disabled` 是部署锁定：它只公布 `off`，并以 `off` 为默认值。省略 `reasoningEffort` 或将其配置为 `off` 均有效；配置 `high` 或 `max` 会使插件加载失败，直接按请求启用思考也会在网络 I/O 前失败。携带 `GenerateOptions.purpose: 'session-title'` 的请求也会强制禁用思考并省略已解析的推理强度，将有界输出保留给可见标题文本，不改变会话或压缩（compaction）默认值。
 
-`streamIdleTimeoutMs` 会限制每次未完成提供方读取，包括初始 `fetch`，但不计入消费方在分片间花费的时间。同一个稳定的 abort 信号会在整个调用期间传递给请求与 body reader；过期会停止传输并抛出 `LlmError('TIMEOUT')`，较早的调用方 abort 则抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用恰好发起一次提供方请求；它把已配置策略注册为提供方元数据，再由 `dsh-llm-retry` 在持久化的 agent（智能体）步骤边界单独执行该策略。
+`streamIdleTimeoutMs` 会限制每次未完成提供方读取，包括初始 `fetch`，但不计入消费方在分片间花费的时间。DeepSeek SSE 注释会作为传输活动使尚未完成的读取重新布防，但绝不会成为 `StreamChunk` 值或会话日志事件。同一个稳定的 abort 信号会在整个调用期间传递给请求与 body reader；过期会停止传输并抛出 `LlmError('TIMEOUT')`，较早的调用方 abort 则抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用恰好发起一次提供方请求；它把已配置策略注册为提供方元数据，再由 `dsh-llm-retry` 在持久化的 agent（智能体）步骤边界单独执行该策略。
 
 ## 动态配置（settings + credentials）
 
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 85985c41d8..c5f9655fa1 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -215,7 +215,13 @@ export class DeepSeekAdapter extends LlmAdapter {
       ? consumer.signal
       : AbortSignal.any([options.signal, consumer.signal])
     using watchdog = idleWatchdog(upstream, connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
-    const iterator = this.request(options, watchdog.signal, connection, apiKey)[Symbol.asyncIterator]()
+    const iterator = this.request(
+      options,
+      watchdog.signal,
+      connection,
+      apiKey,
+      () => { watchdog.pulse() },
+    )[Symbol.asyncIterator]()
     let exhausted = false
     try {
       while (true) {
@@ -256,6 +262,7 @@ export class DeepSeekAdapter extends LlmAdapter {
     signal: AbortSignal,
     connection: DeepSeekConnectionOptions,
     apiKey: string,
+    onComment: () => void,
   ): AsyncIterable<StreamChunk> {
     const body = serializeRequest(options, connection.defaults)
     // Prepared outside the try so the TRANSPORT label below covers exactly the
@@ -321,6 +328,6 @@ export class DeepSeekAdapter extends LlmAdapter {
       throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')
     }
 
-    yield* translate(parseSse(response.body))
+    yield* translate(parseSse(response.body, onComment))
   }
 }
diff --git a/packages/llm/llm-deepseek/src/sse.ts b/packages/llm/llm-deepseek/src/sse.ts
index a8807a857c..9126a18940 100644
--- a/packages/llm/llm-deepseek/src/sse.ts
+++ b/packages/llm/llm-deepseek/src/sse.ts
@@ -1,11 +1,12 @@
 /**
  * Decode an SSE byte stream into event `data` payloads. Framing — chunk
  * reassembly, UTF-8/CRLF/BOM handling, comment and non-data field skipping,
- * multi-`data:` joining — is `eventsource-parser`'s; this module keeps only
- * the DeepSeek protocol: the literal `[DONE]` is yielded so the caller owns
- * final flushing, and EOF before it raises {@link LlmError}. Framing is
- * spec-strict: an event dispatches only on its blank-line terminator, so an
- * unterminated tail at EOF is truncation, not a flushable payload.
+ * multi-`data:` joining — is `eventsource-parser`'s. Comments are reported
+ * only through an optional transport-activity callback. This module keeps the
+ * DeepSeek protocol: the literal `[DONE]` is yielded so the caller owns final
+ * flushing, and EOF before it raises {@link LlmError}. Framing is spec-strict:
+ * an event dispatches only on its blank-line terminator, so an unterminated
+ * tail at EOF is truncation, not a flushable payload.
  *
  * @module dsh-llm-deepseek/sse
  */
@@ -21,12 +22,16 @@ export const DONE = '[DONE]'
  * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
  * without it (truncated response — the model call cannot be trusted).
  * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onComment - optional transport-activity callback; comments never enter the yielded payload stream.
  * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
  */
-export async function* parseSse(stream: ReadableStream<BufferSource>): AsyncGenerator<string> {
+export async function* parseSse(
+  stream: ReadableStream<BufferSource>,
+  onComment?: (comment: string) => void,
+): AsyncGenerator<string> {
   const events = stream
     .pipeThrough(new TextDecoderStream())
-    .pipeThrough(new EventSourceParserStream())
+    .pipeThrough(new EventSourceParserStream({ onComment }))
   for await (const { data } of events) {
     yield data
     if (data === DONE) return
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index ec4a271f15..8240dea7e6 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -545,6 +545,40 @@ describe('DeepSeekAdapter against a mock server', () => {
       fetchSpy.mockRestore()
     }
   })
+
+  it('keeps an idle provider read alive through SSE comments', async () => {
+    vi.useFakeTimers()
+    const encoder = new TextEncoder()
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 75)
+          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 150)
+          setTimeout(() => {
+            controller.enqueue(encoder.encode(textEvents.map(event => `data: ${event}\n\n`).join('')))
+            controller.close()
+          }, 225)
+        },
+      })
+      return Promise.resolve(new Response(body, { status: 200 }))
+    })
+    const adapter = adapterOf({ baseURL: 'https://example.invalid', streamIdleTimeoutMs: 100 })
+    try {
+      const chunks: string[] = []
+      const drain = (async () => {
+        for await (const chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) {
+          chunks.push(chunk.type)
+        }
+      })()
+      await vi.advanceTimersByTimeAsync(75)
+      await vi.advanceTimersByTimeAsync(75)
+      await vi.advanceTimersByTimeAsync(75)
+      await expect(drain).resolves.toBeUndefined()
+      expect(chunks).toEqual(['block-start', 'text-delta', 'block-end', 'usage', 'finish'])
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
 })
 
 describe('plugin registration and config', () => {
diff --git a/packages/llm/llm-deepseek/tests/sse.spec.ts b/packages/llm/llm-deepseek/tests/sse.spec.ts
index 7ebb494a4d..67160d8079 100644
--- a/packages/llm/llm-deepseek/tests/sse.spec.ts
+++ b/packages/llm/llm-deepseek/tests/sse.spec.ts
@@ -31,6 +31,16 @@ describe('parseSse', () => {
     expect(events).toEqual(['{"a":1}', DONE])
   })
 
+  it('reports comments out of band without yielding them', async () => {
+    const comments: string[] = []
+    const events = await collect(parseSse(
+      bytes(': keep-alive\n\ndata: {"a":1}\n\ndata: [DONE]\n\n'),
+      (comment) => { comments.push(comment) },
+    ))
+    expect(comments).toEqual(['keep-alive'])
+    expect(events).toEqual(['{"a":1}', DONE])
+  })
+
   it('stops yielding after DONE even when more data follows', async () => {
     const events = await collect(parseSse(bytes('data: [DONE]\n\ndata: {"late":1}\n\n')))
     expect(events).toEqual([DONE])
diff --git a/packages/util/timeout/README.i18n.yaml b/packages/util/timeout/README.i18n.yaml
index 0436cc4d34..a578a0ac4f 100644
--- a/packages/util/timeout/README.i18n.yaml
+++ b/packages/util/timeout/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/util/timeout/README.md
-README.md: 11c55a45a1255e14fb551e42ba3965453dbd94ae
-README.zh.md: 8b63f00595139f9af2e9a31e8ab3c3494088e0ff
+README.md: 8892b2dce53b5c315c088430ed3fcf386a0f3101
+README.zh.md: ec99f38ff92890c854a1f902e56b2278a42318b6
diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md
index 11c55a45a1..8892b2dce5 100644
--- a/packages/util/timeout/README.md
+++ b/packages/util/timeout/README.md
@@ -18,7 +18,7 @@ import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, Ti
 |---|---|
 | `clampTimeout(requested, def, max, name?)` | Validate the caller's optional positive-finite hint, fill from `def`, cap at `max`. Throws (with `name`) on a non-positive/non-finite hint. |
 | `deadline(upstream, timeoutMs, code)` | Fuse `upstream` cancellation with a timeout into one `AbortSignal` (`AbortSignal.any`); the timeout carries a `TimeoutReason`. `[Symbol.dispose]` clears the timer. |
-| `idleWatchdog(upstream, timeoutMs, code)` | Keep one stable fused signal and arm only while its guarded async-iterator `next()` is outstanding. Resolution disarms; later demand rearms; disposal clears; concurrent demand rejects. |
+| `idleWatchdog(upstream, timeoutMs, code)` | Keep one stable fused signal and arm only while its guarded async-iterator `next()` is outstanding. Resolution disarms; later demand or `pulse()` activity rearms; disposal clears; concurrent demand rejects. |
 | `MAX_TIMER_DELAY_MS` | Largest delay Node schedules without clamping it to one millisecond (`2_147_483_647`). Timer-owning config must not exceed it. |
 | `timeoutOf(signal \| { reason }, code?)` | Recover the `TimeoutReason` from an aborted signal/error, else `undefined` — the timeout-vs-cancel classifier. Pass `code` to match only THIS deadline's timer (see nesting below). |
 | `TimeoutReason` | The internal reason (`code` + `timeoutMs`) stamped on a timeout abort. Not a public error — providers translate it into their own error/field. |
@@ -48,7 +48,7 @@ The signal only *notifies* — the caller MUST attach its own termination (`d.si
 
 Pass your own `code` to `timeoutOf` so classification composes under nesting: when the `upstream` you were handed is *itself* a deadline signal (a future `tools/execute` middleware arming a per-call deadline), `AbortSignal.any` preserves the outer `TimeoutReason` if the outer timer fires first. Scoping to your `code` makes a foreign timeout read as an ordinary upstream cancel — the correct classification from your capability's view — instead of your own timeout firing when your local timer never expired.
 
-For a streamed transport, create one `idleWatchdog`, pass its stable `signal` into the transport, and call `watchdog.next(iterator)` for each provider read. The interval must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS`; Node otherwise clamps it to one millisecond. It measures only outstanding demand, so no timer runs while downstream code renders or otherwise waits before asking for the next chunk. The primitive still only notifies, so the transport must observe the stable signal; the DeepSeek and pi-ai adapters prove that timeout closes their real response body or SDK request.
+For a streamed transport, create one `idleWatchdog`, pass its stable `signal` into the transport, and call `watchdog.next(iterator)` for each provider read. Call `watchdog.pulse()` when transport activity does not yield an iterator value. The interval must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS`; Node otherwise clamps it to one millisecond. It measures only outstanding demand, so no timer runs while downstream code renders or otherwise waits before asking for the next chunk. The primitive still only notifies, so the transport must observe the stable signal; the DeepSeek and pi-ai adapters prove that timeout closes their real response body or SDK request.
 
 ## What does NOT get a timeout
 
diff --git a/packages/util/timeout/README.zh.md b/packages/util/timeout/README.zh.md
index 8b63f00595..ec99f38ff9 100644
--- a/packages/util/timeout/README.zh.md
+++ b/packages/util/timeout/README.zh.md
@@ -18,7 +18,7 @@ import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, Ti
 |---|---|
 | `clampTimeout(requested, def, max, name?)` | 验证调用方可选的、值为正且有限的提示，从 `def` 填充，并限制在 `max` 以内。如果提示为非正数或非有限数，则抛出错误（包含 `name`）。 |
 | `deadline(upstream, timeoutMs, code)` | 将 `upstream` 取消与超时融合为一个 `AbortSignal`（`AbortSignal.any`）；超时携带 `TimeoutReason`。`[Symbol.dispose]` 清除 timer。 |
-| `idleWatchdog(upstream, timeoutMs, code)` | 保持一个稳定的融合信号，并且只在受保护的异步迭代器 `next()` 尚未完成时启动 timer。完成后停止 timer；后续需求重新启动 timer；dispose（资源释放）时清除；并发需求被拒绝。 |
+| `idleWatchdog(upstream, timeoutMs, code)` | 保持一个稳定的融合信号，并且只在受保护的异步迭代器 `next()` 尚未完成时启动 timer。完成后停止 timer；后续需求或 `pulse()` 活动会重新启动 timer；dispose（资源释放）时清除；并发需求被拒绝。 |
 | `MAX_TIMER_DELAY_MS` | Node 在不将延迟限制为 1 毫秒时可调度的最大延迟（`2_147_483_647`）。负责 timer 的配置不得超过该值。 |
 | `timeoutOf(signal \| { reason }, code?)` | 从已中止的信号/错误中恢复 `TimeoutReason`，否则返回 `undefined`，即超时与取消的分类器。传入 `code` 可仅匹配这个 deadline 的 timer（见下文的嵌套）。 |
 | `TimeoutReason` | 标记在超时中止上的内部原因（`code` + `timeoutMs`）。它不是公开错误；提供方将其转换为自己的错误/字段。 |
@@ -48,7 +48,7 @@ export async function runWithDeadline(upstream: AbortSignal | undefined, timeout
 
 将你自己的 `code` 传给 `timeoutOf`，以便分类可在嵌套中组合：当你收到的 `upstream` *本身*就是 deadline 信号时（未来启动每次调用 deadline 的 `tools/execute` 中间件），如果外层 timer 首先触发，`AbortSignal.any` 会保留外层 `TimeoutReason`。将范围限定为你的 `code`，可将外部超时视为普通 upstream 取消，这才是你所属功能视角下的正确分类，而不会在本地 timer 尚未到期时就声称自己超时。
 
-对于流式传输，创建一个 `idleWatchdog`，将其稳定的 `signal` 传给传输层，并为提供方的每次读取调用 `watchdog.next(iterator)`。间隔必须为正有限数，且不得超过 `MAX_TIMER_DELAY_MS`；否则 Node 会将其限制为 1 毫秒。它只对尚未完成的读取请求计时，因此当下游代码进行渲染或在请求下一个分片前以其他方式等待时，timer 不会运行。该原语仍然只会通知，因此传输层必须观察稳定信号；DeepSeek 和 pi-ai 适配器证明，超时会关闭它们的真实响应正文或 SDK 请求。
+对于流式传输，创建一个 `idleWatchdog`，将其稳定的 `signal` 传给传输层，并为提供方的每次读取调用 `watchdog.next(iterator)`。当传输活动不产生迭代器值时，调用 `watchdog.pulse()`。间隔必须为正有限数，且不得超过 `MAX_TIMER_DELAY_MS`；否则 Node 会将其限制为 1 毫秒。它只对尚未完成的读取请求计时，因此当下游代码进行渲染或在请求下一个分片前以其他方式等待时，timer 不会运行。该原语仍然只会通知，因此传输层必须观察稳定信号；DeepSeek 和 pi-ai 适配器证明，超时会关闭它们的真实响应正文或 SDK 请求。
 
 ## 哪些操作不设置超时
 
diff --git a/packages/util/timeout/src/index.ts b/packages/util/timeout/src/index.ts
index a9bd47eb08..3fc4d2387b 100644
--- a/packages/util/timeout/src/index.ts
+++ b/packages/util/timeout/src/index.ts
@@ -72,6 +72,8 @@ export interface IdleWatchdog {
    * @returns the iterator's next result.
    */
   next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  /** Rearm an outstanding demand after transport activity that yields no iterator value; otherwise a no-op. */
+  pulse(): void
   /** Clear an armed timer; safe to call once at the owning stream's exit. */
   [Symbol.dispose](): void
 }
@@ -135,15 +137,20 @@ export function idleWatchdog(
   let outstanding = false
   let disposed = false
 
+  const arm = (): void => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timeout.abort(new TimeoutReason(code, timeoutMs))
+    }, timeoutMs)
+  }
+
   return {
     signal,
     async next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>> {
       if (disposed) throw new Error('idleWatchdog is disposed')
       if (outstanding) throw new Error('idleWatchdog next is already outstanding')
       outstanding = true
-      timer = setTimeout(() => {
-        timeout.abort(new TimeoutReason(code, timeoutMs))
-      }, timeoutMs)
+      arm()
       try {
         return await iterator.next()
       } finally {
@@ -152,6 +159,10 @@ export function idleWatchdog(
         outstanding = false
       }
     },
+    pulse(): void {
+      if (disposed || !outstanding) return
+      arm()
+    },
     [Symbol.dispose](): void {
       if (disposed) return
       disposed = true
diff --git a/packages/util/timeout/tests/timeout.spec.ts b/packages/util/timeout/tests/timeout.spec.ts
index 11779c915f..af0389d3d7 100644
--- a/packages/util/timeout/tests/timeout.spec.ts
+++ b/packages/util/timeout/tests/timeout.spec.ts
@@ -229,6 +229,28 @@ describe('idleWatchdog', () => {
     await expect(secondNext).rejects.toBe(stableSignal.reason)
   })
 
+  it('rearms outstanding demand on an out-of-band activity pulse', async () => {
+    vi.useFakeTimers()
+    const pending = Promise.withResolvers<IteratorResult<number>>()
+    const watchdog = idleWatchdog(undefined, 100, 'LLM_STREAM_IDLE_TIMEOUT')
+    watchdog.pulse()
+    await vi.advanceTimersByTimeAsync(1_000)
+    expect(watchdog.signal.aborted).toBe(false)
+
+    const next = watchdog.next({ next: () => pending.promise })
+    await vi.advanceTimersByTimeAsync(99)
+    watchdog.pulse()
+    await vi.advanceTimersByTimeAsync(99)
+    expect(watchdog.signal.aborted).toBe(false)
+    await vi.advanceTimersByTimeAsync(1)
+    expect(timeoutOf(watchdog.signal, 'LLM_STREAM_IDLE_TIMEOUT')).toMatchObject({ timeoutMs: 100 })
+    pending.reject(watchdog.signal.reason)
+    await expect(next).rejects.toBe(watchdog.signal.reason)
+
+    watchdog[Symbol.dispose]()
+    watchdog.pulse()
+  })
+
   it('keeps an earlier upstream abort distinct from its own timeout', async () => {
     vi.useFakeTimers()
     const upstream = new AbortController()

From bf70345d81a35c1e821aa88a96b1dac7e3f38bb2 Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Tue, 4 Aug 2026 12:00:14 +0800
Subject: [PATCH 002/262] test(snapshot): widen keep-alive timing margin

---
 .../headless-agent/tests/fixtures/deepseek-defaults.cordis.yml  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
index 829af9f813..8a1ca177f4 100644
--- a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
@@ -8,7 +8,7 @@
           apiKey: snapshot-key
           baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
           thinking: disabled
-          streamIdleTimeoutMs: 100
+          streamIdleTimeoutMs: 150
       - id: cli-agent
         config:
           provider: deepseek-official

From 6cd0eea52d92dc3596851316623674e4ec502fb9 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Tue, 4 Aug 2026 22:37:19 -0700
Subject: [PATCH 003/262] docs: propose Task Surface protocol

---
 .../feature/2026-08-04-task-surface.i18n.yaml |   6 +
 .../feature/2026-08-04-task-surface.md        | 232 ++++++++++++++++++
 .../feature/2026-08-04-task-surface.zh.md     | 232 ++++++++++++++++++
 3 files changed, 470 insertions(+)
 create mode 100644 .agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
 create mode 100644 .agents/notes/proposed/feature/2026-08-04-task-surface.md
 create mode 100644 .agents/notes/proposed/feature/2026-08-04-task-surface.zh.md

diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
new file mode 100644
index 0000000000..36e7d8c5d6
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.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 .agents/notes/proposed/feature/2026-08-04-task-surface.md
+2026-08-04-task-surface.md: 780d5d884c83ab47535fff95efcd80b0b7f0181f
+2026-08-04-task-surface.zh.md: 38e6787ee5a4d86261e79c66d99f81614bdb5871
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
new file mode 100644
index 0000000000..780d5d884c
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
@@ -0,0 +1,232 @@
+# Agent Note: Task Surface for structured session interaction
+
+Status: proposed
+
+English | [中文](2026-08-04-task-surface.zh.md)
+
+## Problem
+
+Some tasks are awkward to finish through alternating prose messages. Comparing several options, reordering a plan, reviewing a table, or filling a small set of related fields all work better as one structured interaction. Today an agent can describe such an interaction, but it cannot ask the Web client to render one without adding a permanent product component or generating executable Client Plugin code.
+
+Those two workarounds put ownership in the wrong place. Product-specific components require a new trigger and release for every task shape. Generated code has far more authority and lifecycle cost than a one-turn form needs. It also makes the presentation, rather than the user's conclusion, the durable artifact.
+
+The missing contract is a bounded, replayable description of a temporary UI that belongs to one Session and one tool occurrence. The product should own validation, placement, interaction mechanics, and submission. The agent should own the task-specific copy, data, and choice of supported components.
+
+## Proposal
+
+Add **Task Surface**, a versioned declarative model rendered by a normal Web Client Plugin. One stable model-facing tool, `show_task_surface`, publishes the model. A successful call ends the current turn. The user edits and submits the rendered panel; the Host records the submission as one ordinary visible user message and starts the next turn.
+
+Task Surface is the default structured-UI path when all of the following hold:
+
+- the interaction belongs to the current Session and current task;
+- its behavior fits the declared component set;
+- it needs no background execution or new runtime authority; and
+- the useful durable result is the user's submitted conclusion, not the panel itself.
+
+This is one trigger, not a family of product heuristics. The agent calls `show_task_surface` explicitly. A user may ask the agent to use a Task Surface in ordinary language. Products do not inspect tool names or task topics to open bespoke panels, and repeated use does not automatically turn a Task Surface into a Plugin.
+
+Short blocking questions remain with [`ask_user_question`](../../implemented/feature/2026-07-29-ask-question-web-presentation.md). Plain explanation remains chat. Cross-Session navigation, background behavior, new services, or durable custom UI belongs to the Generated Client Plugin workflow.
+
+## Declarative model
+
+`TaskSurfaceModelV1` is JSON. It contains content blocks, input fields, and one submit label; it contains no code, callbacks, selectors, HTML, CSS, URLs to executable assets, or expression language. This type is unrelated to core Session's existing `SurfaceManager`/`SurfaceOp` message-reduction types; Task Surface is a product interaction protocol.
+
+```ts ignore-check
+interface TaskSurfaceModelV1 {
+  version: 1
+  title: string
+  description?: string
+  sections: TaskSurfaceSection[]
+  fields?: TaskSurfaceField[]
+  submit: { label: string }
+}
+
+interface TaskSurfaceSection {
+  id: string
+  title?: string
+  layout?: 'stack' | 'grid'
+  columns?: 2 | 3
+  blocks: TaskSurfaceBlock[]
+}
+
+type TaskSurfaceBlock =
+  | { kind: 'markdown'; text: string }
+  | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
+  | { kind: 'table'; columns: { id: string; label: string }[]; rows: Record<string, string | number | boolean | null>[] }
+  | { kind: 'diff'; path?: string; before: string | null; after: string; language?: string }
+  | { kind: 'notice'; tone: 'neutral' | 'info' | 'warning'; text: string }
+
+type TaskSurfaceField =
+  | { kind: 'text'; id: string; label: string; multiline?: boolean; required?: boolean; initial?: string }
+  | { kind: 'choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string }
+  | { kind: 'multi-choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+  | { kind: 'toggle'; id: string; label: string; initial?: boolean }
+  | { kind: 'order'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+
+interface TaskSurfaceOption { id: string; label: string; detail?: string }
+```
+
+The renderer controls typography, spacing, responsive layout, focus order, keyboard behavior, and theme tokens. `grid` is a layout hint: it collapses when the available width cannot support the requested columns. Markdown uses the product's supported Markdown subset. Unknown versions or union arms use the generic tool-result fallback instead of partial interpretation.
+
+Version 1 deliberately omits conditional fields, client-side data fetching, charts, file uploads, and arbitrary event handlers. A new block or field kind is a protocol change with a parser, renderer, accessibility behavior, fallback, and replay fixture in the same change.
+
+Limits are schema-backed configuration on the Task Surface service. The initial defaults are 64 KiB for the normalized model, 64 blocks, 32 fields, 200 table rows, and 32 KiB for a submission. IDs are unique within the model; field values must match their declarations; unknown fields are rejected. The limits bound log, DOM, and prompt costs without changing the protocol.
+
+## Tool and presentation contract
+
+`show_task_surface` accepts `{ model: TaskSurfaceModelV1 }`. The Host parses and normalizes the complete model, rejects the call when that Session already has an open Task Surface, mints `surfaceId`, and returns canonical `{ surfaceId, model }` with the normalized model. `presentationMeta` persists `value.model`, so the projector and executor cannot disagree about normalization. The Native result names the Surface and explains that an ordinary message bypasses it when the client cannot render the panel. The tool then calls `exec.concludeTurn()` so the agent does not continue past the requested human checkpoint.
+
+The tool definition sets `exclusive: true`, and the tool is composed only in Web profiles that mount both the Host service and Web renderer. Version 1 supports `native` and `both` tool modes; a `code`-only profile does not advertise it because Code Mode dispatch is nested and cannot carry its presentation metadata to the outer result.
+
+The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
+
+```ts ignore-check
+interface TaskSurfacePresentationMeta {
+  kind: 'dsh/task-surface'
+  version: 1
+  surfaceId: string
+  model: TaskSurfaceModelV1
+}
+```
+
+The tool keeps a generic [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md). The keyed Web row reads the tagged metadata already retained on `ToolResultNode`; no new render-intent arm or presentation registry is required. Clients without Task Surface support render the ordinary result content.
+
+The Web plugin statically registers one keyed `conversation.chat.toolview` entry for `show_task_surface`, following the [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) and [slot registration](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md) contracts. The row renders a compact summary when settled and expands the declarative panel inline. The model does not choose a conversation tab, details column, modal, pixel position, or z-index. A later placement change remains a renderer decision and does not alter logged models.
+
+## Submission contract
+
+The Task Surface domain exposes three operations through the Host transport. `submit` is the only one that admits a user message:
+
+```ts ignore-check
+type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
+type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+
+interface TaskSurfaceService {
+  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
+  dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
+}
+
+interface SubmitTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  submissionId: TaskSurfaceSubmissionId
+  values: Record<string, JsonValue>
+  note?: string
+}
+
+type SubmitTaskSurfaceResult =
+  | { accepted: true; messageId: MessageId }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+
+type GetActiveTaskSurfaceResult =
+  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | { active: false; reason: 'not-open' }
+
+interface DismissTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  dismissalId: TaskSurfaceDismissalId
+}
+
+type DismissTaskSurfaceResult =
+  | { dismissed: true; eventSeq: number }
+  | { dismissed: false; reason: 'not-open' | 'stale' }
+```
+
+The Host resolves the exact successful `show_task_surface` occurrence, revalidates the submitted values against its persisted model, and admits the response through the normal Session queue. The response becomes a user-role message with a merge-extensible source:
+
+```ts ignore-check
+interface TaskSurfaceCorrelation {
+  version: 1
+  submissionId: TaskSurfaceSubmissionId
+  callId: CallId
+  surfaceId: string
+  values: Record<string, JsonValue>
+}
+
+interface TaskSurfaceUserMessageSource {
+  kind: 'user'
+  rpcId: RpcId
+  taskSurface: TaskSurfaceCorrelation
+}
+```
+
+The browser-safe domain package owns `TaskSurfaceCorrelation` and its branded `submissionId`. ApiProxy owns the transport augmentation that combines it with `rpcId`. Keeping `kind: 'user'` preserves the ordinary user bubble and prompt semantics while the extra field provides durable correlation. The message content is a product-formatted readable summary: panel title, labels and submitted values, plus the optional note. The model receives that same text. The structured source is not a second hidden instruction.
+
+The product shell owns collapse and dismiss. Collapse is local view state and sends nothing. `taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` appends one `task-surface/dismissed` Session event and does not start a turn; the exact event closes the projection and updates the transcript row. Retries reuse `dismissalId` and return the original result without appending another event.
+
+Submission is transactional at the client boundary. The panel disables submit while admission is in flight and clears the persisted draft only after the matching user message becomes durable. A rejection keeps the values editable and shows the returned reason. Double clicks and transport retries reuse `submissionId`; the Host admits one user message for one accepted Surface.
+
+There is a short interval between queue admission and the durable `user/message`. The generic queued-message DTO therefore retains `Message.source`. A queued message with matching Task Surface correlation keeps the panel disabled; if that queue item is discarded, the pending state clears and the draft becomes editable again. The Host holds a process-local single-flight claim for the same interval, then releases it on commit, rejection, or discard. The queue is coordination state, not a second durable lifecycle record.
+
+## Lifecycle and recovery
+
+The Session log is the authority. A small `taskSurface` unit in the existing [Session projection system](../architecture/2026-07-27-session-projection-and-command-log.md) folds successful surface result metadata and later user-message sources into this state:
+
+```ts ignore-check
+interface TaskSurfaceProjection {
+  active: { callId: CallId; surfaceId: string } | null
+}
+```
+
+One Session has at most one open Task Surface. A successful result opens it. A matching Task Surface user message or dismissal event closes it. A later ordinary user message also closes it as an explicit bypass; another `show_task_surface` call fails until one of those events closes the active occurrence. Rewind and fork derive their active occurrence by folding the resulting log; no separate Surface database participates.
+
+The full model remains on its `tool/result.meta`; the projection carries only the active identity. When that result is outside the loaded history window, `taskSurface.getActive({ sessionId, surfaceId })` reads the exact occurrence from the Session log and returns `{ callId, surfaceId, model }` after revalidating the metadata. A missing or closed occurrence returns `not-open`. Refresh and reconnect therefore do not depend on the active result fitting in the history tail and do not duplicate the model into every projection baseline.
+
+The Web plugin keeps unsubmitted values in a bounded, per-Session persisted slot store keyed by `surfaceId`; they never enter the Session log, prompt, or long-term memory. Submitted values live in the accepted user message, so losing a browser draft cannot erase a conclusion.
+
+## Package boundaries and dependencies
+
+The capability is split where ownership changes:
+
+| Package | Responsibility |
+|---|---|
+| `packages/task-surface/task-surface` | Browser-safe model/types and correlation, parser, limits, submission validator/formatter, Session event extension, projection unit, and Host service contract |
+| `packages/task-surface/tool-task-surface` | `show_task_surface`, canonical output, presentation metadata, generic render intent, active-Surface check, and `concludeTurn()` behavior |
+| `packages/client/ui-task-surface` | Static keyed tool row, declarative Web renderer, per-Session draft store, and submit client |
+| `packages/host/apiproxy` | Typed active-read/submit/dismiss transport, user-source augmentation, and queued-source carriage; delegates validation and admission to the Task Surface service |
+
+The implementation depends on the existing message log, canonical tool output, tagged render intents, Session projection, per-Session declared slot stores, and slot lifecycle. It does not depend on runtime Client Plugin creation. The generated Client Plugin workflow may use Task Surface to present a review form, but neither protocol owns or activates the other.
+
+## Delivery stages
+
+1. Land the model/parser, projection unit, `show_task_surface`, presentation metadata, static Web row, and generic fallback with read-only blocks.
+2. Add fields, persisted drafts, Host-validated submit/dismiss, queued-source carriage, and visible user-message admission.
+3. Add only component kinds justified by real tasks and two consumers or a clear generic fallback. A separate explicit user action may start the generated Plugin authoring workflow, but it creates a candidate; it never promotes code directly.
+
+## Alternatives considered
+
+**Add product-specific triggers and panels.** Rejected because every new task shape would couple agent behavior to a shipped product component. Product code should define one admitted component vocabulary and placement policy; the agent chooses among it explicitly.
+
+**Render arbitrary HTML, CSS, or JavaScript from the tool call.** Rejected because it turns a temporary interaction into executable Client Plugin code without the build, preview, evaluation, approval, or rollback lifecycle that code requires.
+
+**Extend `userInteraction.ask()` with a large form.** Rejected for this contract. `ask()` is a blocking request/response operation used when a running tool cannot continue without a short answer. A Task Surface ends the turn, may remain open across refreshes, and submits its result as the next visible user turn.
+
+**Register one dynamic `conversation.view` per call.** Rejected because the view ledger is global while its render scope is per Session, and because transient task identity would become registration identity. One static keyed toolview keeps occurrence data in the logged call where it belongs.
+
+**Keep the model only in the canonical tool value.** Rejected because canonical values are not persisted. Replay requires the normalized model in `presentationMeta`.
+
+**Store the panel in long-term memory.** Rejected because layout and draft state are not the reusable fact. Memory may retain the submitted user conclusion under existing memory policy.
+
+## Acceptance criteria
+
+- A real model in `native` or `both` mode can call one stable `show_task_surface` schema, the call ends its turn, and a capable Web client renders the same normalized model live and after replay; `code`-only mode does not advertise it.
+- Submitting produces exactly one visible user message per `submissionId`, starts the next turn through normal queue admission, and retains exact occurrence correlation while keeping `source.kind: 'user'`; dismissing records one log event and starts no turn.
+- Refresh, reconnect, Session switching, fork, and rewind produce the lifecycle state implied by the log; `getActive` recovers a model outside the history tail, and no panel leaks across Sessions.
+- Unsupported versions, malformed metadata, and absent client capability fall back to readable tool-result content with the ordinary-message bypass; nested calls and calls made while another Surface is active fail without opening a Surface.
+- The parser enforces IDs, union shapes, field values, and configured byte/count limits before the panel becomes actionable.
+- Keyboard-only operation, focus restoration, accessible names, narrow layouts, both themes, and zh/en product chrome are covered by component tests.
+- Keyless browser composition covers show, edit, retry after rejected admission, queued/discarded submission, durable submit, dismiss, refresh recovery, and double-submit idempotency.
+- Prefix snapshots show one stable tool definition regardless of the task-specific model; only the call arguments and later user conclusion vary.
+- Unloading the Web plugin disposes its row and draft stores through the owning Fiber without changing the durable transcript.
+
+## Risks
+
+The first component set may be either too small for useful tasks or broad enough to become a weak application framework. Usage evidence should decide additions; v1 has no expression language or network behavior.
+
+Large tables and Markdown can still create expensive DOM even inside byte limits. The renderer must virtualize or truncate where needed while preserving a readable fallback and explicit counts.
+
+A product-formatted submission can become verbose when many fields are filled. The formatter needs a deterministic compact form and must preserve every submitted value without repeating the complete display model.
+
+Browser-local draft persistence can retain sensitive unsubmitted text. The store needs the stated byte bound, per-Session keys, explicit clearing after acceptance, and the same storage posture as the existing conversation draft.
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
new file mode 100644
index 0000000000..38e6787ee5
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -0,0 +1,232 @@
+# Agent Note: 用于结构化会话交互的 Task Surface
+
+Status: proposed
+
+[English](2026-08-04-task-surface.md) | 中文
+
+## 问题
+
+有些任务很难通过交替发送文本消息来完成。比较多个选项、调整计划顺序、审阅表格，或填写一小组关联字段，都更适合在一次结构化交互中处理。目前，agent（智能体）可以描述这类交互，但若不增加永久的产品组件或生成可执行的客户端插件代码，就无法要求 Web 客户端渲染这类交互。
+
+这两种变通方案的职责归属都不合理。产品专用组件要求每种任务形态都新增触发方式并发布新版本。对于只需一个轮次的表单，生成代码所拥有的权限和生命周期成本都远超实际需要。这样做还会把展示界面而非用户结论变成持久产物。
+
+目前缺少这样一份契约：用有界、可回放的描述来定义临时 UI，并让它只属于一个会话和一次工具调用实例。产品应当负责校验、放置、交互机制和提交；agent 应当负责特定任务的文案、数据，以及从受支持组件中作出选择。
+
+## 提案
+
+新增 **Task Surface**：一种由普通 Web 客户端插件渲染、带版本的声明式模型。面向模型提供一个稳定工具 `show_task_surface`，用于发布该模型。调用成功后，当前轮次结束。用户编辑并提交渲染出的面板；Host 将提交内容记录为一条普通的可见用户消息，并开始下一轮。
+
+同时满足以下条件时，Task Surface 是默认的结构化 UI 路径：
+
+- 交互属于当前会话和当前任务；
+- 行为可以由已声明的组件集合表达；
+- 不需要后台执行或新增运行时权限；
+- 有价值的持久结果是用户提交的结论，而不是面板本身。
+
+这里定义的是一个触发方式，不是一组产品启发式规则。agent 会显式调用 `show_task_surface`。用户可以通过普通语言要求 agent 使用 Task Surface。产品不会根据工具名称或任务主题打开专用面板；重复使用也不会自动把 Task Surface 转为插件。
+
+简短的阻塞式问题仍由 [`ask_user_question`](../../implemented/feature/2026-07-29-ask-question-web-presentation.md) 处理。纯文本说明仍留在聊天中。跨会话导航、后台行为、新服务或持久自定义 UI 则属于 Generated Client Plugin 工作流。
+
+## 声明式模型
+
+`TaskSurfaceModelV1` 使用 JSON。它包含内容块、输入字段和一个提交标签；不包含代码、回调、选择器、HTML、CSS、可执行产物的 URL，也不包含表达式语言。该类型与核心会话中现有的 `SurfaceManager`/`SurfaceOp` 消息归约类型无关；Task Surface 是一套产品交互协议。
+
+```ts ignore-check
+interface TaskSurfaceModelV1 {
+  version: 1
+  title: string
+  description?: string
+  sections: TaskSurfaceSection[]
+  fields?: TaskSurfaceField[]
+  submit: { label: string }
+}
+
+interface TaskSurfaceSection {
+  id: string
+  title?: string
+  layout?: 'stack' | 'grid'
+  columns?: 2 | 3
+  blocks: TaskSurfaceBlock[]
+}
+
+type TaskSurfaceBlock =
+  | { kind: 'markdown'; text: string }
+  | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
+  | { kind: 'table'; columns: { id: string; label: string }[]; rows: Record<string, string | number | boolean | null>[] }
+  | { kind: 'diff'; path?: string; before: string | null; after: string; language?: string }
+  | { kind: 'notice'; tone: 'neutral' | 'info' | 'warning'; text: string }
+
+type TaskSurfaceField =
+  | { kind: 'text'; id: string; label: string; multiline?: boolean; required?: boolean; initial?: string }
+  | { kind: 'choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string }
+  | { kind: 'multi-choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+  | { kind: 'toggle'; id: string; label: string; initial?: boolean }
+  | { kind: 'order'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+
+interface TaskSurfaceOption { id: string; label: string; detail?: string }
+```
+
+渲染器控制字体排印、间距、响应式布局、焦点顺序、键盘行为和主题 token。`grid` 是布局提示：可用宽度无法容纳所要求的列数时，渲染器会将其折叠。Markdown 使用产品支持的 Markdown 子集。遇到未知版本或联合类型分支时，系统使用通用工具结果回退，而不是只解释其中一部分。
+
+版本 1 有意不支持条件字段、客户端数据获取、图表、文件上传和任意事件处理器。新增任何块或字段类型都属于协议变更，必须在同一变更中加入解析器、渲染器、无障碍行为、回退方式和回放 fixture（测试前置数据）。
+
+Task Surface 服务通过受 schema 校验的配置定义限制。初始默认值为：规范化模型不超过 64 KiB、块不超过 64 个、字段不超过 32 个、表格行不超过 200 行、提交内容不超过 32 KiB。模型内的 ID 必须唯一；字段值必须符合其声明；未知字段会被拒绝。这些限制约束日志、DOM 和提示词成本，但不改变协议。
+
+## 工具与呈现契约
+
+`show_task_surface` 接收 `{ model: TaskSurfaceModelV1 }`。Host 解析并规范化完整模型；若该会话已有一个打开的 Task Surface，则拒绝调用；否则生成 `surfaceId`，并返回带规范化模型的规范值 `{ surfaceId, model }`。`presentationMeta` 持久化 `value.model`，使投影器和执行器不会对规范化结果产生分歧。Native 结果会指明该 Surface，并说明客户端无法渲染面板时，可以通过普通消息绕过它。随后工具调用 `exec.concludeTurn()`，防止 agent 越过所要求的人工检查点继续执行。
+
+工具定义设置 `exclusive: true`，并且只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
+
+根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
+
+```ts ignore-check
+interface TaskSurfacePresentationMeta {
+  kind: 'dsh/task-surface'
+  version: 1
+  surfaceId: string
+  model: TaskSurfaceModelV1
+}
+```
+
+该工具保留通用 [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)。带 key 的 Web 行读取 `ToolResultNode` 上已经保留的带标签元数据，无需新增 render-intent 分支或呈现注册表。不支持 Task Surface 的客户端会渲染普通结果内容。
+
+Web 插件遵循 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，为 `show_task_surface` 静态注册一个带 key 的 `conversation.chat.toolview` 条目。结算后，该行显示简洁摘要，并在行内展开声明式面板。模型不能选择会话标签页、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。
+
+## 提交契约
+
+Task Surface 领域通过 Host 传输层公开三个操作。只有 `submit` 会接纳用户消息：
+
+```ts ignore-check
+type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
+type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+
+interface TaskSurfaceService {
+  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
+  dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
+}
+
+interface SubmitTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  submissionId: TaskSurfaceSubmissionId
+  values: Record<string, JsonValue>
+  note?: string
+}
+
+type SubmitTaskSurfaceResult =
+  | { accepted: true; messageId: MessageId }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+
+type GetActiveTaskSurfaceResult =
+  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | { active: false; reason: 'not-open' }
+
+interface DismissTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  dismissalId: TaskSurfaceDismissalId
+}
+
+type DismissTaskSurfaceResult =
+  | { dismissed: true; eventSeq: number }
+  | { dismissed: false; reason: 'not-open' | 'stale' }
+```
+
+Host 解析出 `show_task_surface` 的确切成功调用实例，依据其已持久化模型重新校验提交值，并通过普通会话队列接纳响应。该响应成为一条用户角色消息，并使用可合并扩展的消息来源：
+
+```ts ignore-check
+interface TaskSurfaceCorrelation {
+  version: 1
+  submissionId: TaskSurfaceSubmissionId
+  callId: CallId
+  surfaceId: string
+  values: Record<string, JsonValue>
+}
+
+interface TaskSurfaceUserMessageSource {
+  kind: 'user'
+  rpcId: RpcId
+  taskSurface: TaskSurfaceCorrelation
+}
+```
+
+浏览器安全的领域包拥有 `TaskSurfaceCorrelation` 及其带品牌类型的 `submissionId`。ApiProxy 拥有传输扩展，负责将其与 `rpcId` 组合。保留 `kind: 'user'` 可维持普通用户消息气泡和提示词语义，额外字段则提供持久关联信息。消息内容是由产品格式化的可读摘要，包括面板标题、标签和提交值，以及可选备注。模型接收相同的文本。结构化来源不是第二条隐藏指令。
+
+产品外壳负责收起和关闭。收起属于本地视图状态，不会发送任何内容。`taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` 追加一个 `task-surface/dismissed` 会话事件，但不启动轮次；该精确事件会关闭投影并更新 transcript（文本记录）中的对应行。重试会复用 `dismissalId` 并返回原始结果，不会再追加一个事件。
+
+客户端边界上的提交具有事务性。接纳进行期间，面板会禁用提交；只有匹配的用户消息持久化后，才会清除已持久化的草稿。若请求被拒绝，则保留值供用户继续编辑，并显示返回的原因。双击和传输重试会复用 `submissionId`；对于一个已接受的 Surface，Host 只会接纳一条用户消息。
+
+队列接纳与 `user/message` 持久化之间存在一个短暂区间。因此，通用排队消息 DTO 会保留 `Message.source`。带有匹配 Task Surface 关联信息的排队消息会使面板维持禁用状态；如果该队列项被丢弃，待处理状态会清除，草稿恢复为可编辑状态。在同一区间，Host 会持有一个进程内 single-flight 占用，并在消息提交持久化、接纳被拒或队列项被丢弃时释放。队列属于协调状态，并不是第二份持久生命周期记录。
+
+## 生命周期与恢复
+
+会话日志是真源。现有[会话投影系统](../architecture/2026-07-27-session-projection-and-command-log.md)中的一个小型 `taskSurface` 单元会折叠成功调用的 Surface 结果元数据和后续用户消息来源，得到以下状态：
+
+```ts ignore-check
+interface TaskSurfaceProjection {
+  active: { callId: CallId; surfaceId: string } | null
+}
+```
+
+一个会话最多只能有一个打开的 Task Surface。成功的结果会打开它；匹配的 Task Surface 用户消息或关闭事件会将其关闭。后续的普通用户消息也会将其关闭，这是一条显式的绕过路径；在以上任一事件关闭活动调用实例前，再次调用 `show_task_surface` 都会失败。回退和 fork 会通过折叠相应日志推导出活动调用实例，不会使用独立的 Surface 数据库。
+
+完整模型仍存放在对应的 `tool/result.meta` 中；投影只携带活动身份。当该结果超出已加载的历史窗口时，`taskSurface.getActive({ sessionId, surfaceId })` 会从会话日志中读取确切调用实例，重新校验元数据后返回 `{ callId, surfaceId, model }`。调用实例不存在或已经关闭时返回 `not-open`。因此，刷新和重新连接不要求活动结果位于历史尾段，也无需把模型复制到每一个投影基线中。
+
+Web 插件将未提交值保存在一个有界、按会话持久化的 slot store 中，并以 `surfaceId` 为 key；这些值永远不会进入会话日志、提示词或长期记忆。已提交值存放在接纳的用户消息中，因此即使浏览器草稿丢失，也不会抹去结论。
+
+## 包边界与依赖
+
+该能力按职责变化处分包：
+
+| 包 | 职责 |
+|---|---|
+| `packages/task-surface/task-surface` | 浏览器安全的模型／类型和关联信息、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
+| `packages/task-surface/tool-task-surface` | `show_task_surface`、规范输出、呈现元数据、通用 render intent、活动 Surface 检查和 `concludeTurn()` 行为 |
+| `packages/client/ui-task-surface` | 静态带 key 的工具行、声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
+| `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展和排队来源传递；将校验与接纳委托给 Task Surface 服务 |
+
+该实现依赖现有的消息日志、规范工具输出、带标签的 render intent、会话投影、按会话作用域声明的 slot store 和 slot 生命周期，不依赖在运行时创建客户端插件。Generated Client Plugin 工作流可以使用 Task Surface 展示审阅表单，但两个协议都不拥有或激活另一个协议。
+
+## 交付阶段
+
+1. 实现模型／解析器、投影单元、`show_task_surface`、呈现元数据、静态 Web 行，以及带只读块的通用回退。
+2. 增加字段、持久化草稿、经 Host 校验的提交／关闭、排队来源传递，以及可见用户消息接纳。
+3. 只增加有实际任务依据，并且拥有至少两个消费方或明确通用回退的组件类型。一个单独的显式用户操作可以启动生成式插件编写工作流，但只会创建候选项，绝不会直接推广代码。
+
+## 考虑过的替代方案
+
+**增加产品专用触发方式和面板。**不予采用，因为每种新任务形态都会把 agent 行为与已发布的产品组件耦合。产品代码应当定义一套接纳的组件词汇和放置策略；agent 则显式地从中选择。
+
+**从工具调用中渲染任意 HTML、CSS 或 JavaScript。**不予采用，因为这会把临时交互变成可执行的客户端插件代码，却不具备代码所需的构建、预览、评估、批准或回滚生命周期。
+
+**使用大型表单扩展 `userInteraction.ask()`。**本契约不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
+
+**每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。单个静态带 key 的 toolview 会将调用实例数据保留在归属它的已记录调用中。
+
+**只在规范工具值中保留模型。**不予采用，因为规范值不会持久化。回放要求将规范化模型写入 `presentationMeta`。
+
+**将面板存入长期记忆。**不予采用，因为布局和草稿状态不是可复用事实。现有记忆策略可以保留用户提交的结论。
+
+## 验收标准
+
+- 在 `native` 或 `both` 工具模式下，真实模型可以调用一个稳定的 `show_task_surface` schema；调用结束当前轮次；具备相应能力的 Web 客户端在实时运行和回放后都能渲染同一份规范化模型；仅支持 `code` 的模式不会向模型公布该工具。
+- 每个 `submissionId` 的提交操作恰好生成一条可见用户消息，通过普通队列接纳开始下一轮，并在保留 `source.kind: 'user'` 的同时维持对确切调用实例的关联；关闭操作记录一条日志事件，且不启动轮次。
+- 刷新、重新连接、会话切换、fork 和回退都生成日志所决定的生命周期状态；`getActive` 可以恢复历史尾段之外的模型，任何面板都不会泄漏到其他会话。
+- 不受支持的版本、格式错误的元数据以及客户端能力缺失时，系统回退到带普通消息绕过路径的可读工具结果内容；嵌套调用以及已有另一个活动 Surface 时发起的调用都无法打开 Surface，并以失败结束。
+- 解析器会在面板可交互前强制校验 ID、联合类型形态、字段值以及配置的字节数和数量限制。
+- 组件测试覆盖纯键盘操作、焦点恢复、无障碍名称、窄屏布局、两种主题，以及中英文产品界面。
+- 无密钥浏览器组合测试覆盖显示、编辑、接纳被拒后的重试、排队／丢弃提交、持久提交、关闭、刷新恢复和双重提交幂等性。
+- 前缀快照表明：无论任务特定模型如何变化，都只存在一个稳定的工具定义；只有调用参数和后续用户结论发生变化。
+- 卸载 Web 插件时，其所属 Fiber 会对工具行和草稿 store 执行 dispose（资源释放），但不会改变持久 transcript。
+
+## 风险
+
+第一批组件可能小到无法满足实际任务，也可能大到足以演变成一个粗糙的应用框架。是否新增组件应由使用证据决定；v1 不提供表达式语言或网络行为。
+
+即使设置了字节限制，大型表格和 Markdown 仍可能生成开销较高的 DOM。渲染器必须按需虚拟化或截断内容，同时保留可读回退和明确计数。
+
+填写字段较多时，由产品格式化的提交消息可能过长。格式化器需要使用确定性的紧凑格式，保留每一个提交值，同时避免重复完整显示模型。
+
+浏览器本地持久化的草稿可能保留敏感的未提交文本。store 需要遵守规定的字节上限、使用按会话划分的 key、在提交成功后显式清除，并采用与现有会话草稿相同的存储策略。

From 652f3b61bfa8124f3115a4827624ee8936f3c8a7 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Wed, 5 Aug 2026 00:56:18 -0700
Subject: [PATCH 004/262] docs: tighten Task Surface lifecycle contract

---
 .../feature/2026-08-04-task-surface.i18n.yaml |   4 +-
 .../feature/2026-08-04-task-surface.md        | 127 ++++++++++++-----
 .../feature/2026-08-04-task-surface.zh.md     | 129 +++++++++++++-----
 3 files changed, 187 insertions(+), 73 deletions(-)

diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
index 36e7d8c5d6..fec93e2c36 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.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 .agents/notes/proposed/feature/2026-08-04-task-surface.md
-2026-08-04-task-surface.md: 780d5d884c83ab47535fff95efcd80b0b7f0181f
-2026-08-04-task-surface.zh.md: 38e6787ee5a4d86261e79c66d99f81614bdb5871
+2026-08-04-task-surface.md: 0d79d7b830689a269d1aede937fba6aa647ea483
+2026-08-04-task-surface.zh.md: 7960c02dc3c112a8cd1ff626274dfac1f01f1bdb
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
index 780d5d884c..0d79d7b830 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
@@ -44,11 +44,14 @@ interface TaskSurfaceModelV1 {
 interface TaskSurfaceSection {
   id: string
   title?: string
-  layout?: 'stack' | 'grid'
-  columns?: 2 | 3
+  layout?: TaskSurfaceLayout
   blocks: TaskSurfaceBlock[]
 }
 
+type TaskSurfaceLayout =
+  | { kind: 'stack' }
+  | { kind: 'grid'; columns: 2 | 3 }
+
 type TaskSurfaceBlock =
   | { kind: 'markdown'; text: string }
   | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
@@ -66,7 +69,9 @@ type TaskSurfaceField =
 interface TaskSurfaceOption { id: string; label: string; detail?: string }
 ```
 
-The renderer controls typography, spacing, responsive layout, focus order, keyboard behavior, and theme tokens. `grid` is a layout hint: it collapses when the available width cannot support the requested columns. Markdown uses the product's supported Markdown subset. Unknown versions or union arms use the generic tool-result fallback instead of partial interpretation.
+The renderer controls typography, spacing, responsive layout, focus order, keyboard behavior, and theme tokens. An absent layout means `stack`; a `grid` layout owns its column count and collapses when the available width cannot support it. Unknown versions or union arms use the generic tool-result fallback instead of partial interpretation.
+
+The `markdown` block reuses `MarkdownText` with an explicit model-URL policy. `MarkdownText` gains `remoteImages: 'render' | 'alt-only'`, preserving `render` as its ordinary default; Task Surface always passes `alt-only`, so image syntax renders only its alt text. Raw HTML and embedded media remain omitted, automatic link previews are absent, and no model-supplied URL is dereferenced without explicit user activation. Ordinary HTTP(S) links may still navigate when the user chooses them. Fixed application assets such as syntax-highlighting chunks remain under the product's normal loading policy.
 
 Version 1 deliberately omits conditional fields, client-side data fetching, charts, file uploads, and arbitrary event handlers. A new block or field kind is a protocol change with a parser, renderer, accessibility behavior, fallback, and replay fixture in the same change.
 
@@ -76,62 +81,83 @@ Limits are schema-backed configuration on the Task Surface service. The initial
 
 `show_task_surface` accepts `{ model: TaskSurfaceModelV1 }`. The Host parses and normalizes the complete model, rejects the call when that Session already has an open Task Surface, mints `surfaceId`, and returns canonical `{ surfaceId, model }` with the normalized model. `presentationMeta` persists `value.model`, so the projector and executor cannot disagree about normalization. The Native result names the Surface and explains that an ordinary message bypasses it when the client cannot render the panel. The tool then calls `exec.concludeTurn()` so the agent does not continue past the requested human checkpoint.
 
-The tool definition sets `exclusive: true`, and the tool is composed only in Web profiles that mount both the Host service and Web renderer. Version 1 supports `native` and `both` tool modes; a `code`-only profile does not advertise it because Code Mode dispatch is nested and cannot carry its presentation metadata to the outer result.
+The tool definition omits `isConcurrencySafe`. Under the existing tool-registry contract, omission classifies every call as an exclusive ordering barrier; no new `ToolDefinition` field is introduced. The tool is composed only in Web profiles that mount both the Host service and Web renderer. Version 1 supports `native` and `both` tool modes; a `code`-only profile does not advertise it because Code Mode dispatch is nested and cannot carry its presentation metadata to the outer result.
 
-The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
+The browser-safe domain package imports the type-only `Branded` primitive from `@deepseek-ai/dsh-brand` and owns all three Task Surface IDs. The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
 
 ```ts ignore-check
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+type TaskSurfaceId = Branded<'TaskSurfaceId'>
+type TaskSurfaceSubmissionId = Branded<'TaskSurfaceSubmissionId'>
+type TaskSurfaceDismissalId = Branded<'TaskSurfaceDismissalId'>
+
 interface TaskSurfacePresentationMeta {
   kind: 'dsh/task-surface'
   version: 1
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   model: TaskSurfaceModelV1
 }
 ```
 
 The tool keeps a generic [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md). The keyed Web row reads the tagged metadata already retained on `ToolResultNode`; no new render-intent arm or presentation registry is required. Clients without Task Surface support render the ordinary result content.
 
-The Web plugin statically registers one keyed `conversation.chat.toolview` entry for `show_task_surface`, following the [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) and [slot registration](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md) contracts. The row renders a compact summary when settled and expands the declarative panel inline. The model does not choose a conversation tab, details column, modal, pixel position, or z-index. A later placement change remains a renderer decision and does not alter logged models.
+The Web plugin has two static Session-scoped registrations under the [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) and [slot registration](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md) contracts. A keyed `conversation.chat.toolview` entry for `show_task_surface` renders the durable transcript occurrence as a compact summary and read-only replay. One `TaskSurfaceDock` entry in the existing `conversation.input.dock` is the only actionable mount: it reads the active projection, calls `getActive` for the exact identity, and owns fields, drafts, submit, and dismiss. Because the Dock is independent of transcript pagination, an active Surface remains actionable when its `ToolResultNode` is outside the loaded history window.
+
+The Dock follows the existing composer-chain fallback semantics. Any `conversation.composer` takeover hides the fallback composer stack, including `TaskSurfaceDock`, without unmounting it; the same draft owner reappears when the takeover resolves. A takeover does not receive Task Surface actions or create another editor.
+
+The model does not choose a conversation tab, dock order, details column, modal, pixel position, or z-index. A later placement change remains a renderer decision and does not alter logged models. The transcript row never becomes a second editor, so one Surface cannot acquire competing draft or submission owners.
 
 ## Submission contract
 
 The Task Surface domain exposes three operations through the Host transport. `submit` is the only one that admits a user message:
 
 ```ts ignore-check
-type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
-type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+type TaskSurfaceSubmissionPhase = 'queued' | 'claiming'
+
+interface TaskSurfacePendingSubmission {
+  submissionId: TaskSurfaceSubmissionId
+  messageId: MessageId
+  phase: TaskSurfaceSubmissionPhase
+}
 
 interface TaskSurfaceService {
-  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  getActive(input: { sessionId: SessionId; surfaceId: TaskSurfaceId }): Promise<GetActiveTaskSurfaceResult>
   submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
   dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
 }
 
 interface SubmitTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   submissionId: TaskSurfaceSubmissionId
   values: Record<string, JsonValue>
   note?: string
 }
 
 type SubmitTaskSurfaceResult =
-  | { accepted: true; messageId: MessageId }
-  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+  | { accepted: true; messageId: MessageId; phase: 'queued' }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' | 'submission-pending' }
 
 type GetActiveTaskSurfaceResult =
-  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | {
+      active: true
+      callId: CallId
+      surfaceId: TaskSurfaceId
+      model: TaskSurfaceModelV1
+      pending: TaskSurfacePendingSubmission | null
+    }
   | { active: false; reason: 'not-open' }
 
 interface DismissTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   dismissalId: TaskSurfaceDismissalId
 }
 
 type DismissTaskSurfaceResult =
   | { dismissed: true; eventSeq: number }
-  | { dismissed: false; reason: 'not-open' | 'stale' }
+  | { dismissed: false; reason: 'not-open' | 'stale' | 'submission-pending' }
 ```
 
 The Host resolves the exact successful `show_task_surface` occurrence, revalidates the submitted values against its persisted model, and admits the response through the normal Session queue. The response becomes a user-role message with a merge-extensible source:
@@ -141,7 +167,7 @@ interface TaskSurfaceCorrelation {
   version: 1
   submissionId: TaskSurfaceSubmissionId
   callId: CallId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   values: Record<string, JsonValue>
 }
 
@@ -152,13 +178,31 @@ interface TaskSurfaceUserMessageSource {
 }
 ```
 
-The browser-safe domain package owns `TaskSurfaceCorrelation` and its branded `submissionId`. ApiProxy owns the transport augmentation that combines it with `rpcId`. Keeping `kind: 'user'` preserves the ordinary user bubble and prompt semantics while the extra field provides durable correlation. The message content is a product-formatted readable summary: panel title, labels and submitted values, plus the optional note. The model receives that same text. The structured source is not a second hidden instruction.
+The `session/queue` wire item already carries the complete `Message`. The client projection is explicitly extended to retain its source instead of dropping the correlation:
 
-The product shell owns collapse and dismiss. Collapse is local view state and sends nothing. `taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` appends one `task-surface/dismissed` Session event and does not start a turn; the exact event closes the projection and updates the transcript row. Retries reuse `dismissalId` and return the original result without appending another event.
+```ts ignore-check
+interface QueuedMessage {
+  id: InboxItemId
+  messageId: MessageId
+  placement: 'queued' | 'steering'
+  source: MessageSource
+  content: readonly ContentBlock[]
+  preview: string
+  text: string | null
+}
+```
 
-Submission is transactional at the client boundary. The panel disables submit while admission is in flight and clears the persisted draft only after the matching user message becomes durable. A rejection keeps the values editable and shows the returned reason. Double clicks and transport retries reuse `submissionId`; the Host admits one user message for one accepted Surface.
+The browser-safe domain package owns `TaskSurfaceId`, the submission and dismissal IDs, `TaskSurfaceCorrelation`, and the pending-submission shape. ApiProxy owns the transport augmentation that combines the correlation with `rpcId`. Keeping `kind: 'user'` preserves the ordinary user bubble and prompt semantics while the extra field provides durable correlation. The message content is a product-formatted readable summary: panel title, labels and submitted values, plus the optional note. The model receives that same text. The structured source is not a second hidden instruction.
 
-There is a short interval between queue admission and the durable `user/message`. The generic queued-message DTO therefore retains `Message.source`. A queued message with matching Task Surface correlation keeps the panel disabled; if that queue item is discarded, the pending state clears and the draft becomes editable again. The Host holds a process-local single-flight claim for the same interval, then releases it on commit, rejection, or discard. The queue is coordination state, not a second durable lifecycle record.
+The product shell owns collapse and dismiss. Collapse is local view state and sends nothing. When no submission is pending, `taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` appends one `task-surface/dismissed` Session event and does not start a turn; the exact event closes the projection and updates the Dock and transcript row. Retries reuse `dismissalId` and return the original result without appending another event. Dismiss is disabled while a submission is `queued` or `claiming`, and the Host rejects such a request with `submission-pending`.
+
+Submission is transactional at the client boundary. Acceptance returns the exact `messageId` in phase `queued`; the Dock disables every mutation through both `queued` and `claiming` and clears the persisted draft only after the matching user message becomes durable. A rejection keeps the values editable and shows the returned reason. Double clicks and transport retries reuse `submissionId` and return the first result; another submission ID receives `submission-pending` while the first is live. The Host admits one user message for one accepted Surface.
+
+The Task Surface service records accepted submission coordination as `pending.phase: 'queued'`, while the client can correlate the still-present queue row through its retained `source`. When the Agent dequeues that occurrence for ordinary prompt admission, the service synchronously changes the same pending record to `claiming` before ApiProxy publishes the ordinary queue snapshot without the claimed row. The service keeps that process-local claim across asynchronous admission and reconnect until a matching durable `user/message` is published or the Agent reports a terminal discard.
+
+The matching `user/message` closes the durable projection and clears the claim. Rejection, cancellation, or disposal before durability reports the discard, clears the claim, and leaves the Surface open. The Dock never interprets queue-row disappearance as either outcome: it re-reads `getActive`; `pending.phase: 'claiming'` stays disabled, `pending: null` restores the draft, and `not-open` closes the Dock. `getActive` joins the log-derived active occurrence with this one process-local pending record. The record is coordination state, not a second durable authority; after a Host restart, an uncommitted claim is absent and the still-open logged Surface becomes editable again.
+
+`session.updateQueue` rejects `edit` and `steer` for a Task Surface-correlated row. Editing would separate formatted content from its source-carried structured values, and steering would persist a `steering/message` that does not satisfy the submission lifecycle. `remove` is allowed while the row is queued; it reports the discard and restores the open Surface. Once claimed, the row has left the generic queue and queue mutations return `queue-item-not-found`. The Task Surface service holds one single-flight pending record until commit or discard.
 
 ## Lifecycle and recovery
 
@@ -166,13 +210,13 @@ The Session log is the authority. A small `taskSurface` unit in the existing [Se
 
 ```ts ignore-check
 interface TaskSurfaceProjection {
-  active: { callId: CallId; surfaceId: string } | null
+  active: { callId: CallId; surfaceId: TaskSurfaceId } | null
 }
 ```
 
-One Session has at most one open Task Surface. A successful result opens it. A matching Task Surface user message or dismissal event closes it. A later ordinary user message also closes it as an explicit bypass; another `show_task_surface` call fails until one of those events closes the active occurrence. Rewind and fork derive their active occurrence by folding the resulting log; no separate Surface database participates.
+One Session has at most one open Task Surface. A successful result opens it. A matching Task Surface user message or dismissal event closes it. A later ordinary user message also closes it as an explicit bypass; another `show_task_surface` call fails until one of those events closes the active occurrence. Rewind and fork derive their active occurrence by folding the resulting log; transient queue phase is not copied, and no separate Surface database participates.
 
-The full model remains on its `tool/result.meta`; the projection carries only the active identity. When that result is outside the loaded history window, `taskSurface.getActive({ sessionId, surfaceId })` reads the exact occurrence from the Session log and returns `{ callId, surfaceId, model }` after revalidating the metadata. A missing or closed occurrence returns `not-open`. Refresh and reconnect therefore do not depend on the active result fitting in the history tail and do not duplicate the model into every projection baseline.
+The full model remains on its `tool/result.meta`; the projection carries only the active identity. `TaskSurfaceDock` exists independently of history rows and reacts to that identity. `taskSurface.getActive({ sessionId, surfaceId })` reads the exact occurrence from the Session log, revalidates its metadata, joins the Task Surface service's pending coordination record, and returns `{ callId, surfaceId, model, pending }`. A missing or closed occurrence returns `not-open`. Refresh and reconnect therefore recover an actionable Surface and its same-process pending phase even when the result is outside the history tail, without copying the model into every projection baseline.
 
 The Web plugin keeps unsubmitted values in a bounded, per-Session persisted slot store keyed by `surfaceId`; they never enter the Session log, prompt, or long-term memory. Submitted values live in the accepted user message, so losing a browser draft cannot erase a conclusion.
 
@@ -182,17 +226,22 @@ The capability is split where ownership changes:
 
 | Package | Responsibility |
 |---|---|
-| `packages/task-surface/task-surface` | Browser-safe model/types and correlation, parser, limits, submission validator/formatter, Session event extension, projection unit, and Host service contract |
+| `packages/core/agent` and `packages/core/agent-loop` | Generic terminal outcome for a claimed next-turn inbox occurrence, allowing a Host observer to distinguish durable admission from discard without Task Surface-specific types |
+| `packages/task-surface/task-surface` | Browser-safe model, branded IDs, correlation and pending types, parser, limits, submission validator/formatter, Session event extension, projection unit, and Host service contract |
 | `packages/task-surface/tool-task-surface` | `show_task_surface`, canonical output, presentation metadata, generic render intent, active-Surface check, and `concludeTurn()` behavior |
-| `packages/client/ui-task-surface` | Static keyed tool row, declarative Web renderer, per-Session draft store, and submit client |
-| `packages/host/apiproxy` | Typed active-read/submit/dismiss transport, user-source augmentation, and queued-source carriage; delegates validation and admission to the Task Surface service |
+| `packages/client/runtime` | Generic queued-message `source` projection and Session-scoped active-projection access |
+| `packages/client/ui-primitives` | Task Surface-agnostic `MarkdownText.remoteImages` policy, including the `alt-only` image branch and URL-policy tests |
+| `packages/client/ui-task-surface` | Static actionable `TaskSurfaceDock`, read-only keyed transcript row, declarative Web renderer that consumes the Task Surface model and `MarkdownText` in `alt-only` mode, per-Session draft store, and submit client |
+| `packages/host/apiproxy` | Typed active-read/submit/dismiss transport, user-source augmentation and carriage, queue-action restrictions, and routing of claim and terminal outcomes; delegates validation, pending coordination, and admission to the Task Surface service |
+
+`ui-task-surface` depends on the browser-safe Task Surface domain, client connection and runtime, locale, `ui-conversation` for the declared slot contracts, `ui-slots` for registration, and `ui-primitives`; `ui-primitives` does not depend on Task Surface. ApiProxy depends on the Task Surface service contract and the generic AgentLoop terminal outcome. Core Agent packages do not import Task Surface types.
 
 The implementation depends on the existing message log, canonical tool output, tagged render intents, Session projection, per-Session declared slot stores, and slot lifecycle. It does not depend on runtime Client Plugin creation. The generated Client Plugin workflow may use Task Surface to present a review form, but neither protocol owns or activates the other.
 
 ## Delivery stages
 
-1. Land the model/parser, projection unit, `show_task_surface`, presentation metadata, static Web row, and generic fallback with read-only blocks.
-2. Add fields, persisted drafts, Host-validated submit/dismiss, queued-source carriage, and visible user-message admission.
+1. Land the model/parser, `MarkdownText` model-URL policy, projection unit, `show_task_surface`, presentation metadata, read-only Web row, static `TaskSurfaceDock`, active retrieval, and generic fallback with read-only blocks.
+2. Add fields, persisted drafts, Host-validated submit/dismiss, branded correlation, client queued-source carriage, Task Surface `queued`/`claiming` coordination, claimed-occurrence terminal reporting, queue-action restrictions, and visible user-message admission.
 3. Add only component kinds justified by real tasks and two consumers or a clear generic fallback. A separate explicit user action may start the generated Plugin authoring workflow, but it creates a candidate; it never promotes code directly.
 
 ## Alternatives considered
@@ -203,7 +252,7 @@ The implementation depends on the existing message log, canonical tool output, t
 
 **Extend `userInteraction.ask()` with a large form.** Rejected for this contract. `ask()` is a blocking request/response operation used when a running tool cannot continue without a short answer. A Task Surface ends the turn, may remain open across refreshes, and submits its result as the next visible user turn.
 
-**Register one dynamic `conversation.view` per call.** Rejected because the view ledger is global while its render scope is per Session, and because transient task identity would become registration identity. One static keyed toolview keeps occurrence data in the logged call where it belongs.
+**Register one dynamic `conversation.view` per call.** Rejected because the view ledger is global while its render scope is per Session, and because transient task identity would become registration identity. One static Session-scoped Dock owns interaction, and one static keyed row summarizes the logged occurrence; neither registration uses occurrence identity.
 
 **Keep the model only in the canonical tool value.** Rejected because canonical values are not persisted. Replay requires the normalized model in `presentationMeta`.
 
@@ -212,21 +261,29 @@ The implementation depends on the existing message log, canonical tool output, t
 ## Acceptance criteria
 
 - A real model in `native` or `both` mode can call one stable `show_task_surface` schema, the call ends its turn, and a capable Web client renders the same normalized model live and after replay; `code`-only mode does not advertise it.
-- Submitting produces exactly one visible user message per `submissionId`, starts the next turn through normal queue admission, and retains exact occurrence correlation while keeping `source.kind: 'user'`; dismissing records one log event and starts no turn.
-- Refresh, reconnect, Session switching, fork, and rewind produce the lifecycle state implied by the log; `getActive` recovers a model outside the history tail, and no panel leaks across Sessions.
+- The static `TaskSurfaceDock` is the only editor and remains actionable for an active result outside the loaded history window; the keyed toolview remains a read-only transcript summary and replay. A composer takeover hides the still-mounted Dock, preserves its draft, and reveals the same owner after release.
+- Submitting produces exactly one visible user message per `submissionId`, starts the next turn through normal queue admission, and retains exact branded occurrence correlation while keeping `source.kind: 'user'`; dismissing records one log event and starts no turn.
+- The queued client row retains the correlated message source. `getActive` exposes `queued` or `claiming` across same-process reconnect; commit closes the projection, while explicit discard clears pending state and leaves the Surface open. Queue-row disappearance alone changes no UI state. Edit and steer are rejected, and remove succeeds only before claim.
+- Refresh, reconnect, Session switching, fork, and rewind produce the lifecycle state implied by the log; `getActive` recovers the model and pending phase outside the history tail, and no panel, pending state, or draft leaks across Sessions.
 - Unsupported versions, malformed metadata, and absent client capability fall back to readable tool-result content with the ordinary-message bypass; nested calls and calls made while another Surface is active fail without opening a Surface.
-- The parser enforces IDs, union shapes, field values, and configured byte/count limits before the panel becomes actionable.
+- Wire schemas validate ID strings and domain APIs expose the branded ID types throughout. The model parser enforces tagged layout shapes, field values, and configured byte/count limits before the panel becomes actionable. Browser tests show image syntax becomes alt text, raw HTML and embedded media do not render, and no model-supplied URL is requested before explicit user activation.
 - Keyboard-only operation, focus restoration, accessible names, narrow layouts, both themes, and zh/en product chrome are covered by component tests.
-- Keyless browser composition covers show, edit, retry after rejected admission, queued/discarded submission, durable submit, dismiss, refresh recovery, and double-submit idempotency.
+- Keyless browser composition covers show, Dock and read-only-row ownership, off-window recovery, edit, retry after rejected admission, queued-to-claiming transition, discard, durable handoff without an editable gap, forbidden queue actions, dismiss, reconnect, and double-submit idempotency.
 - Prefix snapshots show one stable tool definition regardless of the task-specific model; only the call arguments and later user conclusion vary.
-- Unloading the Web plugin disposes its row and draft stores through the owning Fiber without changing the durable transcript.
+- Unloading the Web plugin disposes its Dock, row, and draft stores through the owning Fiber without changing the durable transcript.
 
 ## Risks
 
 The first component set may be either too small for useful tasks or broad enough to become a weak application framework. Usage evidence should decide additions; v1 has no expression language or network behavior.
 
+The Task Surface Markdown policy gives up inline images, media, and automatic link previews. Ordinary links remain useful, but only an explicit user activation may navigate or start a request.
+
 Large tables and Markdown can still create expensive DOM even inside byte limits. The renderer must virtualize or truncate where needed while preserving a readable fallback and explicit counts.
 
 A product-formatted submission can become verbose when many fields are filled. The formatter needs a deterministic compact form and must preserve every submitted value without repeating the complete display model.
 
+Holding a process-local claim until durable handoff adds a terminal-state invariant. Every admission exit must produce either the matching `user/message` or an explicit discard; otherwise a reconnect could retain a disabled Dock indefinitely.
+
 Browser-local draft persistence can retain sensitive unsubmitted text. The store needs the stated byte bound, per-Session keys, explicit clearing after acceptance, and the same storage posture as the existing conversation draft.
+
+The Dock and transcript row show the same occurrence in different roles. Keeping the row read-only and the Dock as the sole mutation owner prevents conflicting drafts at the cost of a second compact representation while the Surface is active.
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
index 38e6787ee5..7960c02dc3 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -44,11 +44,14 @@ interface TaskSurfaceModelV1 {
 interface TaskSurfaceSection {
   id: string
   title?: string
-  layout?: 'stack' | 'grid'
-  columns?: 2 | 3
+  layout?: TaskSurfaceLayout
   blocks: TaskSurfaceBlock[]
 }
 
+type TaskSurfaceLayout =
+  | { kind: 'stack' }
+  | { kind: 'grid'; columns: 2 | 3 }
+
 type TaskSurfaceBlock =
   | { kind: 'markdown'; text: string }
   | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
@@ -66,7 +69,9 @@ type TaskSurfaceField =
 interface TaskSurfaceOption { id: string; label: string; detail?: string }
 ```
 
-渲染器控制字体排印、间距、响应式布局、焦点顺序、键盘行为和主题 token。`grid` 是布局提示：可用宽度无法容纳所要求的列数时，渲染器会将其折叠。Markdown 使用产品支持的 Markdown 子集。遇到未知版本或联合类型分支时，系统使用通用工具结果回退，而不是只解释其中一部分。
+渲染器控制字体排印、间距、响应式布局、焦点顺序、键盘行为和主题 token。未指定布局时使用 `stack`；`grid` 布局自带列数，可用宽度无法容纳时会折叠。遇到未知版本或联合类型分支时，系统使用通用工具结果回退，而不是只解释其中一部分。
+
+`markdown` 块复用 `MarkdownText`，并显式指定模型 URL 策略。`MarkdownText` 新增 `remoteImages: 'render' | 'alt-only'`，普通场景仍默认使用 `render`；Task Surface 始终传入 `alt-only`，因此图片语法只渲染替代文本。原始 HTML 和嵌入式媒体仍会被省略，不生成自动链接预览；未经用户显式操作，不会解引用模型提供的任何 URL。普通 HTTP(S) 链接仍可在用户选择后导航。语法高亮分片等固定应用资源继续遵循产品的常规加载策略。
 
 版本 1 有意不支持条件字段、客户端数据获取、图表、文件上传和任意事件处理器。新增任何块或字段类型都属于协议变更，必须在同一变更中加入解析器、渲染器、无障碍行为、回退方式和回放 fixture（测试前置数据）。
 
@@ -76,62 +81,83 @@ Task Surface 服务通过受 schema 校验的配置定义限制。初始默认
 
 `show_task_surface` 接收 `{ model: TaskSurfaceModelV1 }`。Host 解析并规范化完整模型；若该会话已有一个打开的 Task Surface，则拒绝调用；否则生成 `surfaceId`，并返回带规范化模型的规范值 `{ surfaceId, model }`。`presentationMeta` 持久化 `value.model`，使投影器和执行器不会对规范化结果产生分歧。Native 结果会指明该 Surface，并说明客户端无法渲染面板时，可以通过普通消息绕过它。随后工具调用 `exec.concludeTurn()`，防止 agent 越过所要求的人工检查点继续执行。
 
-工具定义设置 `exclusive: true`，并且只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
+工具定义省略 `isConcurrencySafe`。根据现有工具注册表契约，省略该字段会将每次调用归类为独占排序屏障，无需新增 `ToolDefinition` 字段。该工具只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
 
-根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
+浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
 
 ```ts ignore-check
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+type TaskSurfaceId = Branded<'TaskSurfaceId'>
+type TaskSurfaceSubmissionId = Branded<'TaskSurfaceSubmissionId'>
+type TaskSurfaceDismissalId = Branded<'TaskSurfaceDismissalId'>
+
 interface TaskSurfacePresentationMeta {
   kind: 'dsh/task-surface'
   version: 1
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   model: TaskSurfaceModelV1
 }
 ```
 
 该工具保留通用 [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)。带 key 的 Web 行读取 `ToolResultNode` 上已经保留的带标签元数据，无需新增 render-intent 分支或呈现注册表。不支持 Task Surface 的客户端会渲染普通结果内容。
 
-Web 插件遵循 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，为 `show_task_surface` 静态注册一个带 key 的 `conversation.chat.toolview` 条目。结算后，该行显示简洁摘要，并在行内展开声明式面板。模型不能选择会话标签页、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。
+Web 插件按照 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，提供两个静态的会话作用域注册项。一个以 `show_task_surface` 为 key 的 `conversation.chat.toolview` 条目将持久 transcript（文本记录）调用实例渲染为简洁摘要和只读回放。现有 `conversation.input.dock` 中的一个 `TaskSurfaceDock` 条目是唯一可操作的挂载点：它读取活动投影，针对确切身份调用 `getActive`，并拥有字段、草稿、提交和关闭操作。Dock 与 transcript 分页相互独立，因此即使 `ToolResultNode` 位于已加载历史窗口之外，活动 Surface 仍可操作。
+
+Dock 遵循现有 composer chain 的回退语义。任何 `conversation.composer` 接管都会隐藏包括 `TaskSurfaceDock` 在内的回退 composer 栈，但不会将其卸载；接管结束后，同一个草稿所有者会重新出现。接管方不会获得 Task Surface 操作，也不会创建另一个编辑器。
+
+模型不能选择会话标签页、Dock 顺序、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。transcript 行绝不会成为第二个编辑器，因此同一个 Surface 不会出现相互竞争的草稿或提交所有者。
 
 ## 提交契约
 
 Task Surface 领域通过 Host 传输层公开三个操作。只有 `submit` 会接纳用户消息：
 
 ```ts ignore-check
-type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
-type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+type TaskSurfaceSubmissionPhase = 'queued' | 'claiming'
+
+interface TaskSurfacePendingSubmission {
+  submissionId: TaskSurfaceSubmissionId
+  messageId: MessageId
+  phase: TaskSurfaceSubmissionPhase
+}
 
 interface TaskSurfaceService {
-  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  getActive(input: { sessionId: SessionId; surfaceId: TaskSurfaceId }): Promise<GetActiveTaskSurfaceResult>
   submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
   dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
 }
 
 interface SubmitTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   submissionId: TaskSurfaceSubmissionId
   values: Record<string, JsonValue>
   note?: string
 }
 
 type SubmitTaskSurfaceResult =
-  | { accepted: true; messageId: MessageId }
-  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+  | { accepted: true; messageId: MessageId; phase: 'queued' }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' | 'submission-pending' }
 
 type GetActiveTaskSurfaceResult =
-  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | {
+      active: true
+      callId: CallId
+      surfaceId: TaskSurfaceId
+      model: TaskSurfaceModelV1
+      pending: TaskSurfacePendingSubmission | null
+    }
   | { active: false; reason: 'not-open' }
 
 interface DismissTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   dismissalId: TaskSurfaceDismissalId
 }
 
 type DismissTaskSurfaceResult =
   | { dismissed: true; eventSeq: number }
-  | { dismissed: false; reason: 'not-open' | 'stale' }
+  | { dismissed: false; reason: 'not-open' | 'stale' | 'submission-pending' }
 ```
 
 Host 解析出 `show_task_surface` 的确切成功调用实例，依据其已持久化模型重新校验提交值，并通过普通会话队列接纳响应。该响应成为一条用户角色消息，并使用可合并扩展的消息来源：
@@ -141,7 +167,7 @@ interface TaskSurfaceCorrelation {
   version: 1
   submissionId: TaskSurfaceSubmissionId
   callId: CallId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   values: Record<string, JsonValue>
 }
 
@@ -152,13 +178,31 @@ interface TaskSurfaceUserMessageSource {
 }
 ```
 
-浏览器安全的领域包拥有 `TaskSurfaceCorrelation` 及其带品牌类型的 `submissionId`。ApiProxy 拥有传输扩展，负责将其与 `rpcId` 组合。保留 `kind: 'user'` 可维持普通用户消息气泡和提示词语义，额外字段则提供持久关联信息。消息内容是由产品格式化的可读摘要，包括面板标题、标签和提交值，以及可选备注。模型接收相同的文本。结构化来源不是第二条隐藏指令。
+`session/queue` 线上的条目已经携带完整 `Message`。客户端投影会显式扩展以保留其来源，不再丢失关联信息：
 
-产品外壳负责收起和关闭。收起属于本地视图状态，不会发送任何内容。`taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` 追加一个 `task-surface/dismissed` 会话事件，但不启动轮次；该精确事件会关闭投影并更新 transcript（文本记录）中的对应行。重试会复用 `dismissalId` 并返回原始结果，不会再追加一个事件。
+```ts ignore-check
+interface QueuedMessage {
+  id: InboxItemId
+  messageId: MessageId
+  placement: 'queued' | 'steering'
+  source: MessageSource
+  content: readonly ContentBlock[]
+  preview: string
+  text: string | null
+}
+```
 
-客户端边界上的提交具有事务性。接纳进行期间，面板会禁用提交；只有匹配的用户消息持久化后，才会清除已持久化的草稿。若请求被拒绝，则保留值供用户继续编辑，并显示返回的原因。双击和传输重试会复用 `submissionId`；对于一个已接受的 Surface，Host 只会接纳一条用户消息。
+浏览器安全的领域包拥有 `TaskSurfaceId`、提交和关闭 ID、`TaskSurfaceCorrelation`，以及待处理提交的形态。ApiProxy 拥有传输扩展，负责将关联信息与 `rpcId` 组合。保留 `kind: 'user'` 可维持普通用户消息气泡和提示词语义，额外字段则提供持久关联信息。消息内容是由产品格式化的可读摘要，包括面板标题、标签和提交值，以及可选备注。模型接收相同的文本。结构化来源不是第二条隐藏指令。
 
-队列接纳与 `user/message` 持久化之间存在一个短暂区间。因此，通用排队消息 DTO 会保留 `Message.source`。带有匹配 Task Surface 关联信息的排队消息会使面板维持禁用状态；如果该队列项被丢弃，待处理状态会清除，草稿恢复为可编辑状态。在同一区间，Host 会持有一个进程内 single-flight 占用，并在消息提交持久化、接纳被拒或队列项被丢弃时释放。队列属于协调状态，并不是第二份持久生命周期记录。
+产品外壳负责收起和关闭。收起属于本地视图状态，不会发送任何内容。没有待处理提交时，`taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` 会追加一个 `task-surface/dismissed` 会话事件，但不启动轮次；该精确事件会关闭投影，并更新 Dock 和 transcript 行。重试会复用 `dismissalId` 并返回原始结果，不会再追加事件。提交处于 `queued` 或 `claiming` 阶段时，关闭操作会被禁用，Host 也会以 `submission-pending` 拒绝这类请求。
+
+客户端边界上的提交具有事务性。接纳成功会返回处于 `queued` 阶段的确切 `messageId`；在 `queued` 和 `claiming` 两个阶段中，Dock 会禁用所有变更，并且只有匹配的用户消息持久化后，才会清除已持久化的草稿。若请求被拒绝，则保留值供用户继续编辑，并显示返回的原因。双击和传输重试会复用 `submissionId` 并返回第一次调用的结果；只要第一次提交仍在处理中，另一个提交 ID 就会收到 `submission-pending`。对于一个已接受的 Surface，Host 只会接纳一条用户消息。
+
+Task Surface 服务将已接受提交的协调状态记录为 `pending.phase: 'queued'`，客户端则可通过仍在队列中的行所保留的 `source` 关联它。当 Agent 从队列取出该调用实例进行普通提示词接纳时，服务会先同步把同一份待处理记录改为 `claiming`，然后 ApiProxy 才发布不再包含已认领行的普通队列快照。服务会在异步接纳和重新连接期间一直保留这份进程内认领状态，直到匹配的持久 `user/message` 发布，或 Agent 报告终态丢弃。
+
+匹配的 `user/message` 会关闭持久投影并清除认领状态。在持久化之前发生拒绝、取消或 dispose（资源释放）时，系统会报告丢弃、清除认领状态，并让 Surface 保持打开。Dock 绝不会把队列行消失解读为其中任一结果，而会重新读取 `getActive`：`pending.phase: 'claiming'` 会维持禁用状态，`pending: null` 会恢复草稿，`not-open` 会关闭 Dock。`getActive` 会把由日志推导的活动调用实例与这唯一一份进程内待处理记录合并。该记录属于协调状态，不是第二个持久权威来源；Host 重启后，未提交的认领状态不复存在，日志中仍然打开的 Surface 会恢复为可编辑状态。
+
+对于带有 Task Surface 关联信息的行，`session.updateQueue` 会拒绝 `edit` 和 `steer`。编辑会让格式化内容与消息来源所携带的结构化值脱节，而 steering（中途引导）会持久化一条不符合提交生命周期的 `steering/message`。该行仍在队列中时允许 `remove`；它会报告丢弃并恢复为打开的 Surface。行被认领后即已离开通用队列，队列变更会返回 `queue-item-not-found`。Task Surface 服务会持有一份 single-flight 待处理记录，直至提交或丢弃。
 
 ## 生命周期与恢复
 
@@ -166,33 +210,38 @@ interface TaskSurfaceUserMessageSource {
 
 ```ts ignore-check
 interface TaskSurfaceProjection {
-  active: { callId: CallId; surfaceId: string } | null
+  active: { callId: CallId; surfaceId: TaskSurfaceId } | null
 }
 ```
 
-一个会话最多只能有一个打开的 Task Surface。成功的结果会打开它；匹配的 Task Surface 用户消息或关闭事件会将其关闭。后续的普通用户消息也会将其关闭，这是一条显式的绕过路径；在以上任一事件关闭活动调用实例前，再次调用 `show_task_surface` 都会失败。回退和 fork 会通过折叠相应日志推导出活动调用实例，不会使用独立的 Surface 数据库。
+一个会话最多只能有一个打开的 Task Surface。成功的结果会打开它；匹配的 Task Surface 用户消息或关闭事件会将其关闭。后续的普通用户消息也会将其关闭，这是一条显式的绕过路径；在以上任一事件关闭活动调用实例前，再次调用 `show_task_surface` 都会失败。回退和 fork 会通过折叠相应日志推导出活动调用实例；瞬态队列阶段不会被复制，也不会有独立的 Surface 数据库参与其中。
 
-完整模型仍存放在对应的 `tool/result.meta` 中；投影只携带活动身份。当该结果超出已加载的历史窗口时，`taskSurface.getActive({ sessionId, surfaceId })` 会从会话日志中读取确切调用实例，重新校验元数据后返回 `{ callId, surfaceId, model }`。调用实例不存在或已经关闭时返回 `not-open`。因此，刷新和重新连接不要求活动结果位于历史尾段，也无需把模型复制到每一个投影基线中。
+完整模型仍存放在对应的 `tool/result.meta` 中；投影只携带活动身份。`TaskSurfaceDock` 独立于历史行存在，并会响应该身份。`taskSurface.getActive({ sessionId, surfaceId })` 会从会话日志中读取确切调用实例，重新校验其元数据，合并 Task Surface 服务的待处理协调记录，并返回 `{ callId, surfaceId, model, pending }`。调用实例不存在或已经关闭时返回 `not-open`。因此，即使结果位于历史尾段之外，刷新和重新连接仍能恢复可操作的 Surface 及其同进程待处理阶段，而无需把模型复制到每一个投影基线中。
 
 Web 插件将未提交值保存在一个有界、按会话持久化的 slot store 中，并以 `surfaceId` 为 key；这些值永远不会进入会话日志、提示词或长期记忆。已提交值存放在接纳的用户消息中，因此即使浏览器草稿丢失，也不会抹去结论。
 
 ## 包边界与依赖
 
-该能力按职责变化处分包：
+该能力在职责变化处拆分为多个包：
 
 | 包 | 职责 |
 |---|---|
-| `packages/task-surface/task-surface` | 浏览器安全的模型／类型和关联信息、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
+| `packages/core/agent` 和 `packages/core/agent-loop` | 为已认领的下一轮 inbox 调用实例提供通用终态结果，让 Host 观察方无需使用 Task Surface 专用类型，即可区分持久接纳和丢弃 |
+| `packages/task-surface/task-surface` | 浏览器安全的模型、带品牌类型的 ID、关联和待处理类型、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
 | `packages/task-surface/tool-task-surface` | `show_task_surface`、规范输出、呈现元数据、通用 render intent、活动 Surface 检查和 `concludeTurn()` 行为 |
-| `packages/client/ui-task-surface` | 静态带 key 的工具行、声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
-| `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展和排队来源传递；将校验与接纳委托给 Task Surface 服务 |
+| `packages/client/runtime` | 通用排队消息 `source` 投影和会话作用域的活动投影访问 |
+| `packages/client/ui-primitives` | 与 Task Surface 无关的 `MarkdownText.remoteImages` 策略，包括 `alt-only` 图片分支和 URL 策略测试 |
+| `packages/client/ui-task-surface` | 静态且可操作的 `TaskSurfaceDock`、带 key 的只读 transcript 行、消费 Task Surface 模型并以 `alt-only` 模式使用 `MarkdownText` 的声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
+| `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展与传递、队列操作限制，以及认领和终态结果的路由；将校验、待处理协调和接纳委托给 Task Surface 服务 |
+
+`ui-task-surface` 依赖浏览器安全的 Task Surface 领域包、客户端连接与运行时、locale、`ui-conversation` 所声明的 slot 契约、用于注册的 `ui-slots`，以及 `ui-primitives`；`ui-primitives` 不反向依赖 Task Surface。ApiProxy 依赖 Task Surface 服务契约和通用 AgentLoop 终态结果。核心 Agent 包不导入 Task Surface 类型。
 
 该实现依赖现有的消息日志、规范工具输出、带标签的 render intent、会话投影、按会话作用域声明的 slot store 和 slot 生命周期，不依赖在运行时创建客户端插件。Generated Client Plugin 工作流可以使用 Task Surface 展示审阅表单，但两个协议都不拥有或激活另一个协议。
 
 ## 交付阶段
 
-1. 实现模型／解析器、投影单元、`show_task_surface`、呈现元数据、静态 Web 行，以及带只读块的通用回退。
-2. 增加字段、持久化草稿、经 Host 校验的提交／关闭、排队来源传递，以及可见用户消息接纳。
+1. 实现模型／解析器、`MarkdownText` 模型 URL 策略、投影单元、`show_task_surface`、呈现元数据、只读 Web 行、静态 `TaskSurfaceDock`、活动 Surface 读取，以及带只读块的通用回退。
+2. 增加字段、持久化草稿、经 Host 校验的提交／关闭、带品牌类型的关联信息、客户端排队来源传递、Task Surface `queued`/`claiming` 协调、已认领调用实例的终态报告、队列操作限制，以及可见用户消息接纳。
 3. 只增加有实际任务依据，并且拥有至少两个消费方或明确通用回退的组件类型。一个单独的显式用户操作可以启动生成式插件编写工作流，但只会创建候选项，绝不会直接推广代码。
 
 ## 考虑过的替代方案
@@ -203,7 +252,7 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 
 **使用大型表单扩展 `userInteraction.ask()`。**本契约不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
 
-**每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。单个静态带 key 的 toolview 会将调用实例数据保留在归属它的已记录调用中。
+**每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。一个静态的会话作用域 Dock 负责交互，一个静态带 key 的行概述已记录的调用实例；两个注册项都不使用调用实例身份。
 
 **只在规范工具值中保留模型。**不予采用，因为规范值不会持久化。回放要求将规范化模型写入 `presentationMeta`。
 
@@ -212,21 +261,29 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 ## 验收标准
 
 - 在 `native` 或 `both` 工具模式下，真实模型可以调用一个稳定的 `show_task_surface` schema；调用结束当前轮次；具备相应能力的 Web 客户端在实时运行和回放后都能渲染同一份规范化模型；仅支持 `code` 的模式不会向模型公布该工具。
-- 每个 `submissionId` 的提交操作恰好生成一条可见用户消息，通过普通队列接纳开始下一轮，并在保留 `source.kind: 'user'` 的同时维持对确切调用实例的关联；关闭操作记录一条日志事件，且不启动轮次。
-- 刷新、重新连接、会话切换、fork 和回退都生成日志所决定的生命周期状态；`getActive` 可以恢复历史尾段之外的模型，任何面板都不会泄漏到其他会话。
+- 静态 `TaskSurfaceDock` 是唯一的编辑器，即使活动结果位于已加载历史窗口之外也仍可操作；带 key 的 toolview 始终是 transcript 的只读摘要和回放。composer 接管会隐藏仍处于挂载状态的 Dock、保留其草稿，并在接管释放后重新显示同一个所有者。
+- 每个 `submissionId` 的提交操作恰好生成一条可见用户消息，通过普通队列接纳开始下一轮，并在保留 `source.kind: 'user'` 的同时维持带品牌类型的确切调用实例关联；关闭操作记录一条日志事件，且不启动轮次。
+- 客户端排队行保留已关联的消息来源。`getActive` 可在同一进程的重新连接前后公开 `queued` 或 `claiming`；提交会关闭投影，显式丢弃则会清除待处理状态并让 Surface 保持打开。队列行消失本身不会改变任何 UI 状态。系统会拒绝编辑和 steering，且移除操作只能在认领前成功。
+- 刷新、重新连接、会话切换、fork 和回退都生成日志所决定的生命周期状态；`getActive` 可以恢复历史尾段之外的模型和待处理阶段，任何面板、待处理状态或草稿都不会泄漏到其他会话。
 - 不受支持的版本、格式错误的元数据以及客户端能力缺失时，系统回退到带普通消息绕过路径的可读工具结果内容；嵌套调用以及已有另一个活动 Surface 时发起的调用都无法打开 Surface，并以失败结束。
-- 解析器会在面板可交互前强制校验 ID、联合类型形态、字段值以及配置的字节数和数量限制。
+- 线上的 schema 会校验 ID 字符串，领域 API 始终公开带品牌类型的 ID。模型解析器会在面板可交互前强制校验带标签的布局形态、字段值，以及配置的字节数和数量限制。浏览器测试证明：图片语法会变成替代文本，原始 HTML 和嵌入式媒体不会渲染，而且在用户显式操作前不会请求模型提供的 URL。
 - 组件测试覆盖纯键盘操作、焦点恢复、无障碍名称、窄屏布局、两种主题，以及中英文产品界面。
-- 无密钥浏览器组合测试覆盖显示、编辑、接纳被拒后的重试、排队／丢弃提交、持久提交、关闭、刷新恢复和双重提交幂等性。
+- 无密钥浏览器组合测试覆盖显示、Dock 与只读行的职责归属、窗口外恢复、编辑、接纳被拒后的重试、从 `queued` 到 `claiming` 的转换、丢弃、没有可编辑空档的持久交接、禁止的队列操作、关闭、重新连接和双重提交幂等性。
 - 前缀快照表明：无论任务特定模型如何变化，都只存在一个稳定的工具定义；只有调用参数和后续用户结论发生变化。
-- 卸载 Web 插件时，其所属 Fiber 会对工具行和草稿 store 执行 dispose（资源释放），但不会改变持久 transcript。
+- 卸载 Web 插件时，其所属 Fiber 会对 Dock、工具行和草稿 store 执行 dispose，但不会改变持久 transcript。
 
 ## 风险
 
 第一批组件可能小到无法满足实际任务，也可能大到足以演变成一个粗糙的应用框架。是否新增组件应由使用证据决定；v1 不提供表达式语言或网络行为。
 
+Task Surface 的 Markdown 策略舍弃行内图片、媒体和自动链接预览。普通链接仍有用，但只有用户显式操作后，才可以导航或发起请求。
+
 即使设置了字节限制，大型表格和 Markdown 仍可能生成开销较高的 DOM。渲染器必须按需虚拟化或截断内容，同时保留可读回退和明确计数。
 
 填写字段较多时，由产品格式化的提交消息可能过长。格式化器需要使用确定性的紧凑格式，保留每一个提交值，同时避免重复完整显示模型。
 
+在完成持久交接之前一直持有进程内认领状态，会新增一项终态不变量。每条接纳退出路径都必须产生匹配的 `user/message` 或显式丢弃，否则重新连接可能会让 Dock 永久处于禁用状态。
+
 浏览器本地持久化的草稿可能保留敏感的未提交文本。store 需要遵守规定的字节上限、使用按会话划分的 key、在提交成功后显式清除，并采用与现有会话草稿相同的存储策略。
+
+Dock 和 transcript 行以不同角色展示同一个调用实例。将工具行保持为只读，并让 Dock 成为唯一的变更所有者，可以避免草稿冲突，但代价是 Surface 活动期间会出现第二份简洁表示。

From fe505e1e91ce7dcd2fda1c3c3a45eaa92abb2b60 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 7 Aug 2026 03:02:10 -0700
Subject: [PATCH 005/262] feat(web): a prose mention of a produced file opens
 it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chatFileMentions service (provided by ui-deliverables beside its
turn-tail entry, reached via ctx.get) resolves inline-code tokens in the
closing message against the turn's produced locations: exact path or
unique basename links, ambiguity and unknowns stay inert. MarkdownText
gains the optional fileMentions seam — settled renders only, never
inside anchors.
---
 ...6-08-07-web-inline-file-mentions.i18n.yaml |   6 +
 .../2026-08-07-web-inline-file-mentions.md    |  28 +++
 .../2026-08-07-web-inline-file-mentions.zh.md |  28 +++
 apps/web/tests/produced-file-mentions.e2e.ts  | 162 ++++++++++++++++++
 apps/web/tsconfig.json                        |   1 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../ui-conversation/src/client/apply.ts       |   1 +
 .../src/client/chat/AssistantMarkdown.tsx     |  29 +++-
 .../src/client/chat/ChatView.tsx              |   4 +-
 .../src/client/contract/slots.ts              |  32 ++++
 .../ui-conversation/src/client/index.ts       |   1 +
 .../ui-conversation/tests/chat-view.spec.tsx  |  41 +++++
 .../client/ui-deliverables/README.i18n.yaml   |   4 +-
 packages/client/ui-deliverables/README.md     |   4 +-
 packages/client/ui-deliverables/README.zh.md  |   4 +-
 .../src/client/ProducedFiles.tsx              |   7 +-
 .../ui-deliverables/src/client/index.ts       |  25 ++-
 .../src/client/turn-deliverables.ts           |  43 +++++
 .../tests/produced-files.spec.tsx             |  47 ++++-
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   2 +-
 packages/client/ui-primitives/README.zh.md    |   2 +-
 packages/client/ui-primitives/src/index.ts    |   2 +-
 .../src/markdown/MarkdownText.module.css      |  20 +++
 .../src/markdown/MarkdownText.tsx             |  26 ++-
 .../ui-primitives/src/markdown/render.tsx     |  51 +++++-
 .../tests/markdown-render-units.spec.tsx      |   1 +
 .../ui-primitives/tests/markdown.spec.tsx     |  43 +++++
 tsconfig.host.json                            |   1 +
 31 files changed, 584 insertions(+), 43 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
 create mode 100644 apps/web/tests/produced-file-mentions.e2e.ts

diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
new file mode 100644
index 0000000000..e8fe387234
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.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 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
+2026-08-07-web-inline-file-mentions.md: 79c6bddd500dc0b68bf64f3c4bea114ca41b4b62
+2026-08-07-web-inline-file-mentions.zh.md: ddc54d3b43570b19fb23c1c9c8079ef4ca65f8fa
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
new file mode 100644
index 0000000000..79c6bddd50
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
@@ -0,0 +1,28 @@
+# Agent Note: inline-code file mentions open the file they name
+
+Status: implemented
+
+English | [中文](2026-08-07-web-inline-file-mentions.zh.md)
+
+> Scope: linking inline-code tokens in the closing message's prose to the files the turn produced. Not in scope: recognizing paths in plain prose, linking files the turn did not produce, and mentions in streaming or mid-turn messages.
+
+## Problem
+
+The produced-files row lists a turn's output, but the closing message usually also *names* the file in prose — as inline code, like `` `deepseek-homepage.html` `` — and that mention was inert text. The reader's eye lands on the sentence first; the affordance sat one row below it.
+
+## Decision
+
+**A prose mention links only when it matches a produced file.** The [produced-files decision](2026-07-31-web-workspace-file-links.md) rejected linkifying the closing message because rendering must not depend on the model spelling a path recognizably; that holds. The row remains the authoritative, prose-independent account. This feature adds a second consumer of the same `locations` vocabulary: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path. A basename two paths share stays inert rather than guessing, and a token naming nothing the turn wrote stays inert — a mention link can never 404.
+
+**The renderer owns no vocabulary, and the provider is the deliverables plugin.** `MarkdownText` takes an optional `MarkdownFileMentions` resolver and consults it for inline-code tokens — after URL promotion, which wins, and never inside an anchor, where a button cannot nest. What names a file is decided behind the optional `chatFileMentions` service ui-conversation reaches via `ctx.get`: ui-deliverables provides it beside its turn-tail chain entry, so one cordis.yml line composes the row and the prose links in or out together, and ui-primitives gains no session concepts. Mentions apply to settled renders only — the streaming cache must not bake in handlers that could go stale, and the vocabulary is not final until the turn closes. The consumer memoizes the resolver on the closing seq rather than the growing transcript, so a settled message's cached parse survives stream appends.
+
+## Alternatives considered
+
+- **Path-shaped regex over all prose** — links `package.json` mentioned abstractly and examples that were never written; every false positive is a click that opens nothing or the wrong file. The vocabulary approach cannot produce a dead link.
+- **Linking suffix matches (`out/index.html` mentioned as `index.html` in a subdirectory listing)** — deferred; exact path and unique basename cover the observed closing-message shapes, and a wider matcher can loosen later without breaking the seam.
+- **Resolving in ui-primitives against a passed path list** — puts matching policy in the generic renderer, where other consumers would inherit it unasked. The resolver seam keeps policy with the owner.
+- **Threading the vocabulary through the turn-tail chain** — the chain is a render dispatch below the message; mentions decorate markdown inside it, which only data reaching MarkdownText can do. The optional service is that data path, and its absence is the off state.
+
+## Consequences
+
+The mention and the row are two affordances for one fact, styled alike (underlined at rest, full path as `title`). `apps/web/tests/produced-file-mentions.e2e.ts` pins the assembled behavior with a built write-turn seed: unique basename links, ambiguous and unknown tokens stay inert; it does not click, for the produced-files restraint (the opener launches a real application). Mentions in mid-turn narration stay inert even for files the turn later produces, because the vocabulary attaches to the closing message only. The window-prepend edge — a window that starts mid-turn later gaining earlier same-turn writes — leaves a mention unlinked until remount, never wrongly linked.
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
new file mode 100644
index 0000000000..ddc54d3b43
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
@@ -0,0 +1,28 @@
+# Agent Note：行内代码文件提及可打开其命名的文件
+
+Status: implemented
+
+[English](2026-08-07-web-inline-file-mentions.md) | 中文
+
+> 范围：把收尾消息正文中的行内代码 token 链接到本轮产出的文件。不在范围内：识别普通正文中的路径、链接本轮未产出的文件，以及流式或轮次中途消息里的提及。
+
+## 问题
+
+产物行列出了一轮的输出，但收尾消息通常也会在正文里*点名*文件——以行内代码形式，如 `` `deepseek-homepage.html` ``——而这个提及是死文本。读者的视线先落在句子上；可点击的交互却在下面一行。
+
+## 决定
+
+**正文提及只在与产出文件对得上时才成为链接。**[产物行的决定](2026-07-31-web-workspace-file-links.md)否决过"把收尾消息链接化"，理由是渲染不能依赖模型把路径写得可识别；这一点不变。产物行仍是权威的、不依赖正文的记录。本特性只是给同一份 `locations` 词表增加第二个消费者：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析。两条路径共享的 basename 保持死文本而不猜测，命名了本轮没写过的文件的 token 同样保持死文本——提及链接永远不会 404。
+
+**渲染器不持有词表，提供方是 deliverables 插件。**`MarkdownText` 接受可选的 `MarkdownFileMentions` 解析器，对行内代码 token 询问它——URL 提升优先于解析器，且绝不在锚点内部（按钮不能嵌套在链接里）。什么算文件名的决定藏在 ui-conversation 经 `ctx.get` 触达的可选 `chatFileMentions` service 背后：ui-deliverables 在其 turn-tail chain 注册项旁提供该 service，因此 cordis.yml 中的一行同时把产物行和正文链接组合进来或去掉，ui-primitives 不引入任何会话概念。提及只作用于已定稿的渲染——流式缓存不能烘进可能过期的 handler，而且词表在轮次收尾前并不最终。消费方按收尾 seq 而非不断增长的 transcript 记忆化解析器，因此已定稿消息的缓存解析在流式追加中得以保留。
+
+## 考虑过的替代方案
+
+- **对全部正文跑路径形状的正则**——会把随口提到的 `package.json` 和从未写过的示例都链接上；每个误报都是一次打开空无或错误文件的点击。词表方案不可能产生死链。
+- **链接后缀匹配（子目录列表里把 `out/index.html` 写作 `index.html`）**——暂缓；精确路径加唯一 basename 已覆盖观察到的收尾消息形态，之后放宽匹配器不会破坏这道 seam。
+- **在 ui-primitives 里对传入的路径列表做解析**——把匹配策略放进通用渲染器，其他消费方会被动继承。解析器 seam 让策略留在持有者手里。
+- **经由 turn-tail chain 传递词表**——chain 是消息下方的渲染派发；提及要装饰的是消息内部的 markdown，只有抵达 MarkdownText 的数据才做得到。可选 service 就是那条数据通路，它的缺席即关闭态。
+
+## 后果
+
+提及与产物行是同一事实的两个交互面，样式一致（静止即下划线，完整路径作为 `title`）。`apps/web/tests/produced-file-mentions.e2e.ts` 用构造的写入轮 seed 钉住组装后的行为：唯一 basename 成链，歧义与未知 token 保持死文本；它不驱动点击，沿用产物行的克制（opener 会启动真实应用）。轮次中途叙述里的提及即使命名了本轮后来产出的文件也保持死文本，因为词表只挂在收尾消息上。窗口前插的边界——从轮次中途开始的窗口后来补入了同轮更早的写入——只会让提及在重挂载前暂不成链，绝不会错链。
diff --git a/apps/web/tests/produced-file-mentions.e2e.ts b/apps/web/tests/produced-file-mentions.e2e.ts
new file mode 100644
index 0000000000..badd9b845e
--- /dev/null
+++ b/apps/web/tests/produced-file-mentions.e2e.ts
@@ -0,0 +1,162 @@
+// Web e2e scenario: inline-code file mentions in the closing prose. Cold-seeds
+// a built write turn (zero model calls) whose closing message names the written
+// file three ways: by unique basename (links), ambiguously (stays inert), and
+// as a file the turn never touched (stays inert). Package tests cover the
+// resolver in isolation; only the assembled application shows a real write's
+// locations reaching the prose as an opener. The click itself is not driven
+// here: it hands the path to the Host's opener, which would launch a real
+// application on the machine running the suite (the produced-files restraint).
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { CallId, createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
+import {
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const MODE = webSnapshotMode()
+const SEED_ID = 'produced-file-mentions-web-e2e'
+const DONE = 'FILE_MENTION_DONE'
+
+/** One-part text content for a built message. */
+function text(value: string): { type: 'text'; text: string }[] {
+  return [{ type: 'text', text: value }]
+}
+
+/** The files the built turn writes; `notes.md` is named in prose but never written. */
+const WRITES = ['site/report.html', 'a/style.css', 'b/style.css']
+
+/** Build a settled write turn whose closing prose mentions files in inline code. */
+function mentionFixture(): string {
+  const session = Session.create(SessionId('produced-file-mentions-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
+  session.append('turn/start', { turn: 1 })
+  const user = session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text: 'Write the report page and both stylesheets.' }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+  session.append('session/title', {
+    title: 'Produced file mentions',
+    messageSeqs: [user.seq],
+    source: { kind: 'fallback' },
+  })
+  session.append('step/start', { turn: 1, step: 1 })
+  const calls = WRITES.map((path, index) => ({
+    path,
+    callId: CallId(`file-mention-${String(index)}`),
+    args: JSON.stringify({ file_path: path, content: `content of ${path}\n` }),
+  }))
+  session.append('assistant/message', {
+    turn: 1,
+    step: 1,
+    message: createAssistantMessage({
+      content: calls.map(call => ({
+        type: 'tool-call' as const,
+        id: call.callId,
+        name: 'write',
+        arguments: call.args,
+      })),
+      source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+    }),
+  }, { surfaceOp: 'append' })
+  for (const call of calls) {
+    const source = session.append('tool/call', {
+      turn: 1,
+      step: 1,
+      callId: call.callId,
+      name: 'write',
+      arguments: call.args,
+    })
+    session.append('tool/result', {
+      turn: 1,
+      step: 1,
+      message: createToolResultMessage({
+        callId: call.callId,
+        content: text(`Created ${call.path}`),
+        isError: false,
+      }),
+    }, { surfaceOp: 'append', sourceEventSeqs: [source.seq] })
+  }
+  session.append('step/start', { turn: 1, step: 2 })
+  session.append('assistant/message', {
+    turn: 1,
+    step: 2,
+    message: createAssistantMessage({
+      content: [{
+        type: 'text',
+        text: [
+          'Wrote `report.html` plus two `style.css` copies; `notes.md` untouched.',
+          '',
+          DONE,
+        ].join('\n'),
+      }],
+      source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+    }),
+  }, { surfaceOp: 'append' })
+  session.append('step/end', { turn: 1, step: 2 })
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+  return [
+    JSON.stringify({
+      type: 'session',
+      version: SESSION_FORMAT_VERSION,
+      id: '{{sessionId}}',
+      createdAt: 0,
+      cwd: '{{cwd}}',
+    }),
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
+    '',
+  ].join('\n')
+}
+
+describe('web e2e: inline-code mentions of produced files', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, mentionFixture(), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it.skipIf(MODE === 'record')('links the unique mention and leaves ambiguous and unknown code inert', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-produced-file-mentions'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await expect.poll(() => page.getByText(DONE, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+
+    // Exactly one prose mention links: `report.html` resolves to the written
+    // path; the shared `style.css` basename and unwritten `notes.md` stay code.
+    const mentions = page.locator('[class*="markdown"] code button')
+    await expect.poll(() => mentions.count(), { timeout: 10_000 }).toBe(1)
+    expect(await mentions.first().innerText()).toBe('report.html')
+    expect(await mentions.first().getAttribute('aria-label')).toBe('Open site/report.html')
+    expect(await mentions.first().getAttribute('title')).toBe('site/report.html')
+    // The turn still ends with its produced-files row (all three writes).
+    expect(await page.getByText('Produced', { exact: true }).count()).toBe(1)
+
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 90_000)
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 1418cf2aa6..a147ddbcb8 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -61,6 +61,7 @@
     "tests/shipped-composition.e2e.ts",
     "tests/startup-auto-selection.e2e.ts",
     "tests/produced-files.e2e.ts",
+    "tests/produced-file-mentions.e2e.ts",
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index fdd1c41b80..2518ef28c8 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: d708621dbeb99615b0864e6977c8d2f387ae5265
-README.zh.md: e2cf9c3b32c86c2da39f09e4804c2ac69a3569f7
+README.md: 6182fa1281eec50f8898634cb466291b6ef1f5ff
+README.zh.md: 8b110ec7713dcda5972d0ea0d9a8042301906d99
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index d708621dbe..6182fa1281 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -50,7 +50,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations and composed props, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` directories import contract files and never each other. `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components and the store factory stay internal and reach the page through apply's slot registrations.
 
-A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost.
+A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index e2cf9c3b32..8b110ec771 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -50,7 +50,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明与组合后的 props、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/` 目录只导入 contract 文件，彼此之间从不互相导入。`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件与 store factory 保持内部，经 apply 的 slot 注册抵达页面。
 
-完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。
+完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` seam——service 缺席时正文保持死文本。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 24325c714e..48a0558f34 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -313,6 +313,7 @@ export function apply(ctx: Context): void {
           actions.select(target)
           layout.openDetails()
         },
+        fileMentions: owner => ctx.get('chatFileMentions')?.forClosing(owner),
         openFile: (path) => {
           const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
           void workspaces.openPath(resolveToolPath(cwd, path)).catch(() => {
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index bc1c6c7e32..8bb7f8aea4 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -15,7 +15,8 @@ import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import {
   IconThinkOutline14, JsonBlock, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatViewSlotProps, ChatViewInjected, TurnTailOwnerProps } from '../contract/slots.ts'
 import { hasContentText } from './chat-flow.ts'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import { ToolRow } from './ToolRow.tsx'
@@ -43,6 +44,8 @@ export interface AssistantMarkdownProps {
   onFork?: ((seq: number) => void) | undefined
   /** Turn-tail slot dispatch share and owner currency; omitted for a mid-turn assistant. */
   turnTail?: (Pick<PropsRenderSlots<'conversation.chat.turnTail'>, 'renderSlotChain'> & { owner: TurnTailOwnerProps }) | undefined
+  /** Prose file-mention factory (the injected face); omitted wherever `turnTail` is. */
+  fileMentions?: ChatViewInjected['fileMentions'] | undefined
   /** The message is not the transcript tail of a completed turn. */
   forkUnavailable?: boolean | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
@@ -86,11 +89,25 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail, t,
+  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail,
+  fileMentions, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
   const codeLabels = useMemo(() => ({ copyLabel: t('copy'), copiedLabel: t('copied') }), [t])
+  // Mention vocabulary for the closing prose. Keyed on the anchor seq, not the
+  // growing transcript: a settled turn's produced files are final, and a
+  // fresh identity per append would discard MarkdownText's cached parse for
+  // every settled closing message on every stream chunk. The window-prepend
+  // edge (a mid-turn window start later gaining earlier same-turn writes)
+  // leaves a mention unlinked until remount — never a wrong link.
+  const owner = turnTail?.owner
+  const mentions: MarkdownFileMentions | undefined = useMemo(
+    () => (owner === undefined ? undefined : fileMentions?.(owner)),
+    // Deliberately not `owner`: its identity changes per append while the
+    // seq-addressed vocabulary it yields does not.
+    [fileMentions, owner?.seq],
+  )
   const last = blocks.length - 1
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
   // a node that is only those heads (or empty) would paint an empty root
@@ -107,7 +124,13 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         {blocks.map((block, i) => {
           switch (block.kind) {
             case 'text': return (
-              <MarkdownText key={i} text={block.text} streaming={streaming} codeLabels={codeLabels} />
+              <MarkdownText
+                key={i}
+                text={block.text}
+                streaming={streaming}
+                codeLabels={codeLabels}
+                fileMentions={mentions}
+              />
             )
             case 'reasoning': return <ThinkRow key={i} text={block.text} running={streaming && i === last} t={t} />
             // Grouped into tool rows by ChatView; hasVisible above skips an empty shell.
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index b0907f5a80..c8ad485013 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -335,7 +335,8 @@ function StreamingTail({ useSession, t }: {
  * render through the declared keyed hole's renderSlot share).
  */
 export function ChatView({
-  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
+  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt,
+  fileMentions, t,
 }: ChatViewSlotProps) {
   const nodes = useSession(s => s.nodes)
   const turnTimings = useSession(s => s.turnTimings)
@@ -603,6 +604,7 @@ export function ChatView({
           turnTail={actionSeqs.has(node.seq)
             ? { renderSlotChain, owner: { nodes, seq: node.seq, openFile } }
             : undefined}
+          fileMentions={actionSeqs.has(node.seq) ? fileMentions : undefined}
           t={t}
         />
       )
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 89f7986dba..7e811da7a1 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -4,6 +4,7 @@ import type {
   InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { CommandNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
@@ -158,6 +159,30 @@ export interface ConvViewOwnerProps {
   onInspectDone?: () => void
 }
 
+/**
+ * Optional prose file-mention provider, consumed via `ctx.get('chatFileMentions')`
+ * (optional-service convention): the chat view asks it for a closing message's
+ * inline-code vocabulary and threads the result into MarkdownText. Absent
+ * service — the providing plugin composed out of cordis.yml — turns the
+ * surface off; the prose renders inert code.
+ */
+export interface ChatFileMentions {
+  /**
+   * Mention vocabulary for the closing message the owner currency names.
+   * @param owner - Turn-tail owner currency (nodes, closing seq, opener).
+   * @returns The resolver MarkdownText consumes, or undefined when the turn
+   * produced nothing worth linking.
+   */
+  forClosing(owner: TurnTailOwnerProps): MarkdownFileMentions | undefined
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Prose file-mention provider (ui-deliverables); reach via ctx.get — optional. */
+    chatFileMentions: ChatFileMentions
+  }
+}
+
 /**
  * Owner currency of the chat view's turn-tail hole: the finalized snapshot
  * and the closing assistant's anchor. Registrants derive their own facts
@@ -502,6 +527,13 @@ export interface ChatViewInjected {
   }
   /** Fork through the completed turn ending at the eligible message `seq`, then open the child. */
   forkAt: (seq: number) => void
+  /**
+   * Prose file-mention vocabulary for one closing message, from the optional
+   * {@link ChatFileMentions} service (resolved lazily per call, so composing
+   * the provider in or out takes effect live). Undefined when the service is
+   * absent or the turn produced nothing worth linking.
+   */
+  fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined
 }
 
 /** Full chat-view component props: runtime & the declared toolview/commandview holes' render share & store & injected & locale seat. */
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index 725868d57a..3ce8b64053 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -13,6 +13,7 @@ export type {
 export type { ToolCallBlock } from './contract/tool-call-model.ts'
 export type { ConversationKey } from './locales.ts'
 export type {
+  ChatFileMentions,
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
   ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index b8cd94de52..cb11a1a5fd 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -154,6 +154,8 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     inspectCall,
     chatScroll,
     forkAt,
+    // Absent-service default; mention tests override with a real resolver.
+    fileMentions: () => undefined,
     // Mirrors the real lookup chain (conversation namespace, then common).
     t: makeTranslate(zh, commonZh),
   }
@@ -248,6 +250,45 @@ describe('chat-flow derivation', () => {
     expect([...assistantActionsSeqs(nodes, new Map([[1, 5]]))]).toEqual([5])
   })
 
+  it('threads the injected file-mention vocabulary into the closing prose only', () => {
+    const wrote = (seq: number, callId: string, path: string): ToolResultNode => ({
+      ...toolResult(seq, callId, 'write'),
+      callView: {
+        card: 'diff', title: 'Write', diffs: [{ path, oldText: null, newText: 'x' }], locations: [{ path }],
+      },
+    })
+    const h = makeHarness({
+      nodes: [
+        user(1, 'build it'),
+        assistant(2, 'writing `report.html` now', 1),
+        wrote(3, 'w', 'site/report.html'),
+        assistant(4, 'Wrote `report.html`; `notes.md` untouched.', 1),
+      ],
+      turnEnds: new Map([[1, 4]]),
+    })
+    // Stub provider mirroring the real service: only produced files resolve.
+    h.props.fileMentions = owner => ({
+      resolve: (value) => {
+        if (value !== 'report.html') return undefined
+        return {
+          open: () => { h.openFile(`for-seq-${String(owner.seq)}/site/report.html`) },
+          label: '打开 site/report.html',
+          title: 'site/report.html',
+        }
+      },
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    // Exactly one live mention: the closing message links, the mid-turn
+    // narration stays inert code, and the unknown file resolves to nothing.
+    const mentions = view.container.querySelectorAll('code button')
+    expect(mentions).toHaveLength(1)
+    const mention = view.getByRole('button', { name: '打开 site/report.html' })
+    expect(mention.getAttribute('title')).toBe('site/report.html')
+    fireEvent.click(mention)
+    // The vocabulary was built from the closing message's own owner currency.
+    expect(h.openFile).toHaveBeenCalledWith('for-seq-4/site/report.html')
+  })
+
   it('runningTurnStartTime selects the latest turn/start without a turn/end', () => {
     expect(runningTurnStartTime(new Map([
       [1, { startTime: 1_000, endTime: 5_000 }],
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index ee4c23c18c..3d25f13e1a 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/ui-deliverables/README.md
-README.md: b8b0ea2ef1cbc9b18b905fc08b41278f403ef043
-README.zh.md: a16535b8a8d3625ca1cf90e88c6d9dca742d916b
+README.md: d6695f155907e7d92b35556588687b3f95e55b88
+README.zh.md: be360a5a1fbe8d904cedf104b28f64f1b0567d6b
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index b8b0ea2ef1..d6695f1559 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -8,6 +8,8 @@ Produced-files feature owner: registers the deliverables row a finished turn end
 
 `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
 
+The closing prose carries the same vocabulary. This plugin provides the `chatFileMentions` service the chat view consults per closing message: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path — a basename two paths share stays inert rather than guessing, so a mention link can never open the wrong file or 404. A resolved mention renders as the same underlined opener the row's chips are, with the full path as its `title`, and mentions never render inside anchors or streaming text. Decision record: the [inline file mentions Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md).
+
 ## Model Experience
 
 None, as the row is a pure client derivation over already-logged tool metadata and nothing here reaches a model request.
@@ -18,4 +20,4 @@ None; this package neither assembles nor sends provider requests.
 
 ## Known Limitations and Deferred Work
 
-- **Prose mentions stay inert.** An inline-code file name in the closing message does not open the file yet; linking it to the same `locations` vocabulary is the stacked follow-up.
+- **Mention matching is exact path or unique basename only.** A suffix mention (`out/index.html` written as `index.html` resolves; `deep/out/index.html` written as `out/index.html` does not) stays inert; widening the matcher is deferred until a real closing-message shape needs it.
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index a16535b8a8..be360a5a1f 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -8,6 +8,8 @@
 
 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
+收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及渲染为与产物行 chip 相同的下划线 opener，完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
+
 ## 模型体验
 
 无。该行是对已记录工具元数据的纯客户端派生，这里没有任何内容进入模型请求。
@@ -18,4 +20,4 @@
 
 ## 已知限制与暂缓事项
 
-- **正文提及仍是死文本。**收尾消息里以行内代码写出的文件名尚不能点击打开；把它接到同一份 `locations` 词表是 stacked 的后续工作。
+- **提及匹配只认精确路径或唯一 basename。**后缀式提及（`out/index.html` 写作 `index.html` 可解析；`deep/out/index.html` 写作 `out/index.html` 则不行）保持死文本；放宽匹配器等真实的收尾消息形态需要时再做。
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
index ab85869de2..0baff2872a 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -6,18 +6,13 @@
 
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { basename } from './turn-deliverables.ts'
 import type { NS } from './locales.ts'
 import css from './ProducedFiles.module.css'
 
 /** Files past this stay counted but unlisted: a refactor turn must not bury the answer. */
 const SHOWN = 6
 
-/** Trailing path segment, the part that identifies the file at a glance. */
-function basename(path: string): string {
-  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
-  return at === -1 ? path : path.slice(at + 1)
-}
-
 /** Matched paths plus the opener and locale seats needed to present them. */
 export type ProducedFilesProps = Pick<TurnTailOwnerProps, 'openFile'> & {
   matched: readonly string[]
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 6dc7bc4b84..816cdff520 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -1,16 +1,18 @@
 /**
  * Deliverables plugin, browser half: registers the produced-files row into
- * the chat view's turn-tail hole. All policy lives here — the derivation
- * from the mutation tools' `locations`, the chip cap, and the copy — so
- * composing this plugin out of cordis.yml removes the surface entirely; the
- * owning view renders an empty hole at zero cost.
+ * the chat view's turn-tail chain, and provides the `chatFileMentions`
+ * service that links inline-code mentions of produced files in the closing
+ * prose. All policy lives here — the derivation from the mutation tools'
+ * `locations`, the mention matching, the chip cap, and the copy — so
+ * composing this plugin out of cordis.yml removes both surfaces entirely;
+ * the owning view renders an empty chain and inert prose at zero cost.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
-import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
-import { selectProducedFiles } from './turn-deliverables.ts'
+import { producedFileMentions, producedForClosing, selectProducedFiles } from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -39,4 +41,15 @@ export function apply(ctx: ClientContext): void {
       locale: NS,
     }, ProducedFiles),
   )
+  // The prose side of the same vocabulary: the chat view reaches this face
+  // via ctx.get, so its absence — this plugin composed out — is the off state.
+  const t = ctx.locale.bind(NS)
+  const mentions: ChatFileMentions = {
+    forClosing(owner) {
+      const paths = producedForClosing(owner.nodes, owner.seq)
+      if (paths.length === 0) return undefined
+      return producedFileMentions(paths, owner.openFile, path => t('produced.open', { name: path }))
+    },
+  }
+  ctx.provide('chatFileMentions', mentions)
 }
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index c9754d1da4..4316ddf8e6 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -4,6 +4,7 @@
  * own follow-along `locations`, never the closing prose.
  */
 import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 /**
@@ -88,3 +89,45 @@ export function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[
   const paths = producedForClosing(nodes, seq)
   return paths.length === 0 ? null : paths
 }
+
+/**
+ * Trailing path segment, the part that identifies the file at a glance.
+ * @param path - Slash- or backslash-separated path.
+ * @returns The final segment, or the whole string when separator-free.
+ */
+export function basename(path: string): string {
+  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  return at === -1 ? path : path.slice(at + 1)
+}
+
+/**
+ * File-mention vocabulary over one turn's produced paths, for the closing
+ * message's prose: an inline-code token opens the file it names. A token
+ * resolves by exact path, or by being exactly the basename of exactly one
+ * produced path — a basename two paths share stays inert rather than
+ * guessing, so a mention link can never open the wrong file or 404.
+ * @param paths - The turn's produced paths (tool order, already deduped).
+ * @param openFile - The chat view's file opener.
+ * @param label - Localizes the accessible open-label for a resolved path.
+ * @returns The resolver MarkdownText consumes; the full path rides `title`,
+ * the same disambiguator the row's chips carry.
+ */
+export function producedFileMentions(
+  paths: readonly string[],
+  openFile: (path: string) => void,
+  label: (path: string) => string,
+): MarkdownFileMentions {
+  return {
+    resolve(value) {
+      const path = paths.includes(value) ? value : onlyPathWithBasename(paths, value)
+      if (path === undefined) return undefined
+      return { open: () => { openFile(path) }, label: label(path), title: path }
+    },
+  }
+}
+
+/** The single produced path whose basename is exactly `value`, else undefined. */
+function onlyPathWithBasename(paths: readonly string[], value: string): string | undefined {
+  const matches = paths.filter(path => basename(path) === value)
+  return matches.length === 1 ? matches[0] : undefined
+}
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 49e41ebd86..65af40d642 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -13,9 +13,10 @@ import type {
   AssistantMessageNode, ConversationNode, ToolResultNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
+import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
-import { producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
+import { basename, producedFileMentions, producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
 import { apply, inject } from '../src/client/index.ts'
 import { apply as applyNode } from '../src/index.ts'
 import { apply as applyInvariant } from '../src/invariant.ts'
@@ -141,6 +142,33 @@ describe('ProducedFiles row', () => {
   })
 })
 
+describe('producedFileMentions resolver', () => {
+  const label = (path: string) => `打开 ${path}`
+
+  it('resolves exact paths and unique basenames; ambiguity and unknowns stay unresolved', () => {
+    const opened: string[] = []
+    const resolver = producedFileMentions(
+      ['out/index.html', 'a/style.css', 'b/style.css'],
+      (path) => { opened.push(path) },
+      label,
+    )
+    // Unique basename resolves to its full path; the full path rides title.
+    const byBasename = resolver.resolve('index.html')
+    expect(byBasename?.label).toBe('打开 out/index.html')
+    expect(byBasename?.title).toBe('out/index.html')
+    byBasename?.open()
+    expect(opened).toEqual(['out/index.html'])
+    // An exact path resolves even when its basename is ambiguous.
+    const exact = resolver.resolve('a/style.css')
+    expect(exact?.title).toBe('a/style.css')
+    // A basename two paths share stays unresolved rather than guessing,
+    // and so does a token naming nothing the turn wrote.
+    expect(resolver.resolve('style.css')).toBeUndefined()
+    expect(resolver.resolve('notes.md')).toBeUndefined()
+    expect(basename('a\\b\\c.txt')).toBe('c.txt')
+  })
+})
+
 describe('package shells', () => {
   it('the node half mounts inert and the invariant companion registers ownership', async () => {
     // The node half is deliberately inert; mounting it must simply not throw.
@@ -172,7 +200,24 @@ describe('plugin registration', () => {
     await fiber.await()
     expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(1)
 
+    // The prose face is live while the plugin is: a produced turn yields a
+    // resolver whose matches open through the owner-supplied opener.
+    const opened: string[] = []
+    const owner = {
+      nodes: [user(1, 'go'), wrote(2, 'w', 'site/report.html'), assistant(3, 'done', 1)],
+      seq: 3,
+      openFile: (path: string) => { opened.push(path) },
+    }
+    const service = (ctx as unknown as { get(name: string): ChatFileMentions | undefined }).get('chatFileMentions')
+    const mentions = service?.forClosing(owner)
+    mentions?.resolve('report.html')?.open()
+    expect(opened).toEqual(['site/report.html'])
+    // A turn that produced nothing yields no vocabulary at all.
+    expect(service?.forClosing({ ...owner, nodes: [user(1, 'hi'), assistant(2, 'ok', 1)], seq: 2 })).toBeUndefined()
+
     await fiber.dispose()
     expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(0)
+    // Fiber teardown retracts the service: the consumer's ctx.get sees the off state.
+    expect((ctx as unknown as { get(name: string): unknown }).get('chatFileMentions')).toBeUndefined()
   })
 })
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 47cebf796f..f7598d7a90 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/ui-primitives/README.md
-README.md: 7571cb48424b650a1aaa5222b33a3ee14faa69b4
-README.zh.md: fa0c3f24023ec8c1eb77553bfe191801b6698687
+README.md: a5f35c9a41008921c6a1e3a4de3fd3f38af926c0
+README.zh.md: 54c70ed29e73e196a9be60ddb794c12187dbe0c5
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 7571cb4842..a5f35c9a41 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -10,7 +10,7 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/
 
 ## Markdown rendering
 
-`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
+`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
 
 ## Terminal output
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index fa0c3f2402..54c70ed29e 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -10,7 +10,7 @@
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有视图把命名真实文件的行内代码变成链接：token 保留代码样式并获得接到所解析 opener 的按钮，带解析器给出的无障碍标签与完整路径 `title`。渲染器绝不猜测什么长得像路径——未解析的 token 保持原样，提及只作用于已定稿的渲染（流式缓存不能烘进可能过期的 handler），锚点内部的 token 也保持原样，因为按钮不能嵌套在链接里。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index fe0235c496..30a1dae402 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -40,7 +40,7 @@ export { CodeBlock } from './markdown/CodeBlock.tsx'
 export type { CodeBlockProps } from './markdown/CodeBlock.tsx'
 export { JsonBlock } from './markdown/JsonBlock.tsx'
 export { MarkdownText } from './markdown/MarkdownText.tsx'
-export type { MarkdownCodeLabels } from './markdown/MarkdownText.tsx'
+export type { MarkdownCodeLabels, MarkdownFileMentions } from './markdown/MarkdownText.tsx'
 export { MessageText } from './markdown/MessageText.tsx'
 export { extractMarkdownPlainText } from './markdown/plain-text.ts'
 export type { MarkdownPlainTextMode, MarkdownPlainTextOptions } from './markdown/plain-text.ts'
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index 7e31857053..19375be18e 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -241,3 +241,23 @@
   background: var(--dsw-alias-bg-base);
   object-fit: contain;
 }
+
+/* Inline file mention: a real file named in prose is the same affordance as a
+   tool row's path link, so it reads the same — underlined at rest. */
+.fileMention {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  color: var(--dsw-alias-label-secondary);
+  text-decoration: underline;
+  text-decoration-color: var(--dsw-alias-label-quaternary);
+  text-underline-offset: 3px;
+  cursor: pointer;
+}
+
+.fileMention:hover {
+  color: var(--dsw-alias-label-primary);
+  text-decoration-color: currentColor;
+}
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
index bb4b62514c..4dff78d784 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
@@ -19,20 +19,25 @@ import {
   collectReferenceTargets, createReferenceTargets, renderBlocks, renderFootnoteSection,
   wrapBlockChildren,
 } from './render.tsx'
-import type { MarkdownCodeLabels, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
+import type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
 import 'katex/dist/katex.min.css'
 import css from './MarkdownText.module.css'
 
-export type { MarkdownCodeLabels } from './render.tsx'
+export type { MarkdownCodeLabels, MarkdownFileMentions } from './render.tsx'
 
 /** One settled full render: parse with math, resolve references, append the footnote section. */
-function renderSettled(text: string, codeLabels: MarkdownCodeLabels | undefined): ReactNode[] {
+function renderSettled(
+  text: string,
+  codeLabels: MarkdownCodeLabels | undefined,
+  fileMentions: MarkdownFileMentions | undefined,
+): ReactNode[] {
   const root = parseGfmWithMath(text)
   const targets = createReferenceTargets()
   collectReferenceTargets(root.children, targets)
   const context: MarkdownRenderContext = {
     streaming: false,
     codeLabels,
+    fileMentions,
     targets,
     footnoteOrder: [],
     footnoteCounts: new Map(),
@@ -96,6 +101,7 @@ class StreamingRenderer {
       const frozenContext: MarkdownRenderContext = {
         streaming: true,
         codeLabels: this.codeLabels,
+        fileMentions: undefined,
         targets: frameTargets,
         footnoteOrder: this.frozenFootnoteOrder,
         footnoteCounts: this.frozenFootnoteCounts,
@@ -113,6 +119,7 @@ class StreamingRenderer {
     const tailContext: MarkdownRenderContext = {
       streaming: true,
       codeLabels: this.codeLabels,
+      fileMentions: undefined,
       targets: frameTargets,
       footnoteOrder: [...this.frozenFootnoteOrder],
       footnoteCounts: new Map(this.frozenFootnoteCounts),
@@ -137,28 +144,33 @@ class StreamingRenderer {
  * the finalize swap) and parses incrementally across chunks; `codeLabels`
  * forwards localized copy-button labels to fence CodeBlocks — pass a
  * reference-stable object (memoized per locale revision), because a new
- * identity discards the streaming render cache mid-message.
+ * identity discards the streaming render cache mid-message. `fileMentions`
+ * links inline-code tokens its resolver recognizes as real files; this is
+ * the single streaming gate — it applies to settled renders only, because a
+ * streaming message's vocabulary is not final and frozen cached elements
+ * must not bake in handlers that could go stale.
  * @returns A GFM document with TeX math rendered through KaTeX; raw HTML,
  * relative links, and unsafe protocols are disabled, while absolute HTTP(S)
  * images render directly.
  */
-export const MarkdownText = memo(function MarkdownText({ text, streaming = false, codeLabels }: {
+export const MarkdownText = memo(function MarkdownText({ text, streaming = false, codeLabels, fileMentions }: {
   text: string
   streaming?: boolean
   codeLabels?: MarkdownCodeLabels | undefined
+  fileMentions?: MarkdownFileMentions | undefined
 }) {
   const streamRef = useRef<StreamingRenderer | null>(null)
   const streamLabelsRef = useRef<MarkdownCodeLabels | undefined>(codeLabels)
   const children = useMemo(() => {
     if (!streaming) {
       streamRef.current = null
-      return renderSettled(text, codeLabels)
+      return renderSettled(text, codeLabels, fileMentions)
     }
     if (streamRef.current === null || streamLabelsRef.current !== codeLabels) {
       streamRef.current = new StreamingRenderer(codeLabels)
       streamLabelsRef.current = codeLabels
     }
     return streamRef.current.render(text)
-  }, [text, streaming, codeLabels])
+  }, [text, streaming, codeLabels, fileMentions])
   return <div className={css.markdown}>{children}</div>
 })
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 4ac8b4dbc1..452e0fc475 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -99,6 +99,21 @@ export function collectReferenceTargets(
   }
 }
 
+/**
+ * File-mention affordance for inline code: the owner resolves an authored
+ * token to the file it names, using its own vocabulary of real files — the
+ * renderer never guesses at what looks like a path.
+ */
+export interface MarkdownFileMentions {
+  /**
+   * Resolve one inline-code token.
+   * @param value - The authored token, exactly as written.
+   * @returns The opener with its accessible label and full-path title, or
+   * undefined when the token names no known file — it then stays inert code.
+   */
+  resolve(value: string): { open: () => void; label: string; title: string } | undefined
+}
+
 /**
  * One render pass's state: immutable options and targets plus the footnote
  * numbering accumulated in document order while references render.
@@ -108,6 +123,10 @@ export interface MarkdownRenderContext {
   readonly streaming: boolean
   /** Localized fence copy-button labels. */
   readonly codeLabels: MarkdownCodeLabels | undefined
+  /** Inline-code file mentions; absent wherever no opener vocabulary exists. */
+  readonly fileMentions: MarkdownFileMentions | undefined
+  /** Inside an anchor's children: interactive mentions must not nest there. */
+  readonly inLink?: boolean
   /** Reference targets visible to this pass. */
   readonly targets: ReferenceTargets
   /** Footnote identifiers in first-reference order; a footnote's number is its 1-based index here. */
@@ -217,7 +236,27 @@ function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderConte
       // authored text, not a parsed destination, so no normalizeUri: port,
       // path, and query render unchanged.
       const href = inlineCodeHttpUrl(value)
-      return <code key={key}>{href === undefined ? value : renderSafeLink(href, [value], 'link')}</code>
+      if (href !== undefined) return <code key={key}>{renderSafeLink(href, [value], 'link')}</code>
+      // A token the owner's file-mention vocabulary recognizes opens that
+      // file; the resolver, not this renderer, decides what names a file.
+      // Inside an anchor the token stays inert — a button cannot nest there.
+      const mention = context.inLink === true ? undefined : context.fileMentions?.resolve(value)
+      if (mention !== undefined) {
+        return (
+          <code key={key}>
+            <button
+              type="button"
+              className={css.fileMention}
+              title={mention.title}
+              aria-label={mention.label}
+              onClick={mention.open}
+            >
+              {value}
+            </button>
+          </code>
+        )
+      }
+      return <code key={key}>{value}</code>
     }
     case 'html':
       // No HTML parser enters the pipeline: raw HTML stays literal text.
@@ -236,7 +275,7 @@ function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderConte
     case 'table':
       return renderTable(node, key, context)
     case 'link':
-      return renderAnchor(node.url, renderChildren(node.children, context), key)
+      return renderAnchor(node.url, renderChildren(node.children, { ...context, inLink: true }), key)
     case 'linkReference':
       return renderLinkReference(node, key, context)
     case 'image':
@@ -460,14 +499,14 @@ function renderLinkReference(
   context: MarkdownRenderContext,
 ): ReactNode {
   const definition = context.targets.definitions.get(node.identifier.toUpperCase())
-  const children = renderChildren(node.children, context)
   if (definition === undefined) {
     // The grammar only emits references whose definitions exist somewhere in
     // the same parse, but incremental segments and hand-built trees may still
-    // present unresolved ones: revert to the bracketed source text.
-    return <Fragment key={key}>{'['}{children}{referenceSuffix(node)}</Fragment>
+    // present unresolved ones: revert to the bracketed source text — which is
+    // not an anchor, so mentions inside it stay live.
+    return <Fragment key={key}>{'['}{renderChildren(node.children, context)}{referenceSuffix(node)}</Fragment>
   }
-  return renderAnchor(definition.url, children, key)
+  return renderAnchor(definition.url, renderChildren(node.children, { ...context, inLink: true }), key)
 }
 
 function renderImageReference(
diff --git a/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx b/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx
index 48dd03f5c5..48f59c7479 100644
--- a/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx
@@ -20,6 +20,7 @@ function makeContext(): MarkdownRenderContext {
   return {
     streaming: false,
     codeLabels: undefined,
+    fileMentions: undefined,
     targets: createReferenceTargets(),
     footnoteOrder: [],
     footnoteCounts: new Map(),
diff --git a/packages/client/ui-primitives/tests/markdown.spec.tsx b/packages/client/ui-primitives/tests/markdown.spec.tsx
index 5066e32cd2..89ffd32346 100644
--- a/packages/client/ui-primitives/tests/markdown.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown.spec.tsx
@@ -148,6 +148,49 @@ describe('MarkdownText', () => {
     expect(container.querySelector('pre code a')).toBeNull()
   })
 
+  it('links inline code through the file-mention resolver: URL first, settled only, never inside links', () => {
+    const opened: string[] = []
+    const fileMentions = {
+      resolve: (value: string) => value === 'index.html' || value === 'out/index.html'
+        ? { open: () => { opened.push(value) }, label: 'Open out/index.html', title: 'out/index.html' }
+        : undefined,
+    }
+    const source = [
+      '`index.html`',
+      '`other.css`',
+      '`https://example.com/`',
+      // Inside an anchor the mention stays inert code: a button cannot nest there.
+      '[see `out/index.html`](https://example.com/doc)',
+      '[ref `out/index.html`][target]',
+      '[target]: https://example.com/ref',
+      '```',
+      'index.html',
+      '```',
+    ].join('\n\n')
+    const { container } = render(<MarkdownText text={source} fileMentions={fileMentions} />)
+
+    const mention = screen.getByRole('button', { name: 'Open out/index.html' })
+    expect(mention.closest('code')).not.toBeNull()
+    // The full path rides title, the same disambiguator the row's chips carry.
+    expect(mention.getAttribute('title')).toBe('out/index.html')
+    fireEvent.click(mention)
+    expect(opened).toEqual(['index.html'])
+    // Exactly one live mention: the two inside anchors declined, and an
+    // unresolved token plus fenced code stay inert.
+    expect(container.querySelectorAll('code button')).toHaveLength(1)
+    expect(container.querySelectorAll('a code button, a button')).toHaveLength(0)
+    expect(screen.getByText('other.css').closest('button')).toBeNull()
+    // URL promotion wins before the resolver sees a token.
+    expect(screen.getByText('https://example.com/').closest('a')).not.toBeNull()
+
+    // Streaming renders keep mentions off — the one gate lives here: cached
+    // frozen elements must not bake in handlers that could go stale.
+    const streamed = render(
+      <MarkdownText text={'`index.html`\n\nmore\n\n'} streaming fileMentions={fileMentions} />,
+    )
+    expect(streamed.container.querySelector('button')).toBeNull()
+  })
+
   it('exposes the CJK strong syntax as a micromark extension needing CommonMark attention markers', () => {
     const extension = cjkFriendlyStrong()
     expect(cjkFriendlyStrong()).toBe(extension)
diff --git a/tsconfig.host.json b/tsconfig.host.json
index ad2b5e32f1..d4f7eb8650 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -49,6 +49,7 @@
     "apps/web/tests/goal-bar.e2e.ts",
     "apps/web/tests/startup-auto-selection.e2e.ts",
     "apps/web/tests/produced-files.e2e.ts",
+    "apps/web/tests/produced-file-mentions.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",

From 7ef39dc4b02795260c483c449b632303f95f6634 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 7 Aug 2026 05:00:47 -0700
Subject: [PATCH 006/262] refactor(deliverables): reuse the chain claim test
 for the mention vocabulary

---
 packages/client/ui-deliverables/src/client/index.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 816cdff520..81b2f61b79 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -12,7 +12,7 @@ import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/c
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
-import { producedFileMentions, producedForClosing, selectProducedFiles } from './turn-deliverables.ts'
+import { producedFileMentions, selectProducedFiles } from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -46,8 +46,10 @@ export function apply(ctx: ClientContext): void {
   const t = ctx.locale.bind(NS)
   const mentions: ChatFileMentions = {
     forClosing(owner) {
-      const paths = producedForClosing(owner.nodes, owner.seq)
-      if (paths.length === 0) return undefined
+      // Same claim test the turn-tail chain entry runs: no produced files,
+      // no vocabulary — the two surfaces agree by construction.
+      const paths = selectProducedFiles(owner)
+      if (paths === null) return undefined
       return producedFileMentions(paths, owner.openFile, path => t('produced.open', { name: path }))
     },
   }

From 4c45355012bdc0d86d0fb8abe7e37c56b1e7c351 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 7 Aug 2026 05:06:21 -0700
Subject: [PATCH 007/262] style(web): mention chips take the markdown anchor
 language

Link-blue at rest with hover underline, matching URL-promoted inline
code; an at-rest underline collides with monospace descenders inside
the code chip.
---
 ...6-08-07-web-inline-file-mentions.i18n.yaml |  4 ++--
 .../2026-08-07-web-inline-file-mentions.md    |  2 +-
 .../2026-08-07-web-inline-file-mentions.zh.md |  2 +-
 .../client/ui-deliverables/README.i18n.yaml   |  4 ++--
 packages/client/ui-deliverables/README.md     |  2 +-
 packages/client/ui-deliverables/README.zh.md  |  2 +-
 .../src/markdown/MarkdownText.module.css      | 20 ++++++++++---------
 7 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
index e8fe387234..8153420c3d 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.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 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
-2026-08-07-web-inline-file-mentions.md: 79c6bddd500dc0b68bf64f3c4bea114ca41b4b62
-2026-08-07-web-inline-file-mentions.zh.md: ddc54d3b43570b19fb23c1c9c8079ef4ca65f8fa
+2026-08-07-web-inline-file-mentions.md: 581efb5a9eb497e030d19118d52d003b37118108
+2026-08-07-web-inline-file-mentions.zh.md: 25c8ca6e106cd877a4d46a7b1338728e96771fc1
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
index 79c6bddd50..581efb5a9e 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
@@ -25,4 +25,4 @@ The produced-files row lists a turn's output, but the closing message usually al
 
 ## Consequences
 
-The mention and the row are two affordances for one fact, styled alike (underlined at rest, full path as `title`). `apps/web/tests/produced-file-mentions.e2e.ts` pins the assembled behavior with a built write-turn seed: unique basename links, ambiguous and unknown tokens stay inert; it does not click, for the produced-files restraint (the opener launches a real application). Mentions in mid-turn narration stay inert even for files the turn later produces, because the vocabulary attaches to the closing message only. The window-prepend edge — a window that starts mid-turn later gaining earlier same-turn writes — leaves a mention unlinked until remount, never wrongly linked.
+The mention and the row are two affordances for one fact (full path as `title` on both); the mention itself wears the markdown sheet's anchor language — link-blue at rest, hover underline — because an at-rest underline collides with monospace descenders inside the code chip. `apps/web/tests/produced-file-mentions.e2e.ts` pins the assembled behavior with a built write-turn seed: unique basename links, ambiguous and unknown tokens stay inert; it does not click, for the produced-files restraint (the opener launches a real application). Mentions in mid-turn narration stay inert even for files the turn later produces, because the vocabulary attaches to the closing message only. The window-prepend edge — a window that starts mid-turn later gaining earlier same-turn writes — leaves a mention unlinked until remount, never wrongly linked.
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
index ddc54d3b43..25c8ca6e10 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
@@ -25,4 +25,4 @@ Status: implemented
 
 ## 后果
 
-提及与产物行是同一事实的两个交互面，样式一致（静止即下划线，完整路径作为 `title`）。`apps/web/tests/produced-file-mentions.e2e.ts` 用构造的写入轮 seed 钉住组装后的行为：唯一 basename 成链，歧义与未知 token 保持死文本；它不驱动点击，沿用产物行的克制（opener 会启动真实应用）。轮次中途叙述里的提及即使命名了本轮后来产出的文件也保持死文本，因为词表只挂在收尾消息上。窗口前插的边界——从轮次中途开始的窗口后来补入了同轮更早的写入——只会让提及在重挂载前暂不成链，绝不会错链。
+提及与产物行是同一事实的两个交互面（两者都以完整路径作 `title`）；提及本身采用 markdown 样式表的锚点语言——静止为链接蓝、悬停出下划线——因为静止下划线在 code 胶囊里会压住等宽字的下伸部。`apps/web/tests/produced-file-mentions.e2e.ts` 用构造的写入轮 seed 钉住组装后的行为：唯一 basename 成链，歧义与未知 token 保持死文本；它不驱动点击，沿用产物行的克制（opener 会启动真实应用）。轮次中途叙述里的提及即使命名了本轮后来产出的文件也保持死文本，因为词表只挂在收尾消息上。窗口前插的边界——从轮次中途开始的窗口后来补入了同轮更早的写入——只会让提及在重挂载前暂不成链，绝不会错链。
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index 3d25f13e1a..7c2cb356ec 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/ui-deliverables/README.md
-README.md: d6695f155907e7d92b35556588687b3f95e55b88
-README.zh.md: be360a5a1fbe8d904cedf104b28f64f1b0567d6b
+README.md: 189dedd88fed6914012204118ccdf9bdd0cd3bb2
+README.zh.md: bfcec3c54602533028942ed167b9526eaf3ca959
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index d6695f1559..189dedd88f 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -8,7 +8,7 @@ Produced-files feature owner: registers the deliverables row a finished turn end
 
 `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
 
-The closing prose carries the same vocabulary. This plugin provides the `chatFileMentions` service the chat view consults per closing message: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path — a basename two paths share stays inert rather than guessing, so a mention link can never open the wrong file or 404. A resolved mention renders as the same underlined opener the row's chips are, with the full path as its `title`, and mentions never render inside anchors or streaming text. Decision record: the [inline file mentions Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md).
+The closing prose carries the same vocabulary. This plugin provides the `chatFileMentions` service the chat view consults per closing message: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path — a basename two paths share stays inert rather than guessing, so a mention link can never open the wrong file or 404. A resolved mention keeps its code chip and takes the markdown sheet's link language — link-blue at rest, underlined on hover, exactly like URL-promoted inline code — with the full path as its `title`; mentions never render inside anchors or streaming text. Decision record: the [inline file mentions Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md).
 
 ## Model Experience
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index be360a5a1f..bfcec3c546 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -8,7 +8,7 @@
 
 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
-收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及渲染为与产物行 chip 相同的下划线 opener，完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
+收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及保留 code 胶囊并采用 markdown 样式表的链接语言——静止为链接蓝、悬停出下划线，与 URL 提升的行内代码完全一致——完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
 
 ## 模型体验
 
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index 19375be18e..b62e66e86e 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -242,22 +242,24 @@
   object-fit: contain;
 }
 
-/* Inline file mention: a real file named in prose is the same affordance as a
-   tool row's path link, so it reads the same — underlined at rest. */
+/* Inline file mention: the same link language this sheet gives anchors (and
+   thereby URL-promoted inline code) — link-blue at rest, underline only on
+   hover/focus. An underline at rest reads badly inside the code chip, where
+   it collides with monospace descenders and the pill background. */
 .fileMention {
   margin: 0;
   padding: 0;
   border: none;
   background: none;
   font: inherit;
-  color: var(--dsw-alias-label-secondary);
-  text-decoration: underline;
-  text-decoration-color: var(--dsw-alias-label-quaternary);
-  text-underline-offset: 3px;
+  color: var(--dsw-alias-state-business-primary);
+  text-decoration: none;
   cursor: pointer;
 }
 
-.fileMention:hover {
-  color: var(--dsw-alias-label-primary);
-  text-decoration-color: currentColor;
+.fileMention:hover,
+.fileMention:focus {
+  outline: none;
+  text-decoration: underline var(--dsw-alias-state-business-primary);
+  text-underline-offset: 3px;
 }

From 9ed33dfe4f8e784536e0741ed447af638e8e26d4 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:08:22 +0800
Subject: [PATCH 008/262] refactor(client): localize nested Tool call trees

---
 ...ient-tool-presentation-ownership.i18n.yaml |   4 +-
 ...8-08-client-tool-presentation-ownership.md |  26 +--
 ...8-client-tool-presentation-ownership.zh.md |  26 +--
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   4 +-
 packages/client/runtime/README.zh.md          |   4 +-
 packages/client/runtime/src/client/index.ts   |  13 +-
 .../client/session-history/history-fold.ts    |  92 +++-------
 .../src/client/sessions/conversation.ts       |  28 +--
 .../runtime/src/client/sessions/history.ts    |   6 +-
 .../runtime/src/client/sessions/session.ts    |  87 ++-------
 .../src/client/sessions/tool-call-tree.ts     | 171 ++++++++++++++++++
 .../src/client/sessions/transcript-adapter.ts |   1 +
 packages/client/runtime/tests/session.spec.ts |  81 +++++++--
 packages/client/test-runtime/src/fixtures.ts  |   1 -
 .../src/client/chat/ChatView.tsx              |  11 +-
 .../src/client/skeleton/DetailsPanel.tsx      |  28 ++-
 .../ui-conversation/tests/chat-stats.spec.tsx |   6 +-
 .../ui-conversation/tests/chat-view.spec.tsx  |   6 +-
 .../tests/gate-branch-tails.spec.tsx          |  26 ++-
 .../ui-conversation/tests/input-bar.spec.tsx  |   2 +-
 .../tests/input-matrix.spec.tsx               |   2 +-
 .../tests/input-scenarios.spec.tsx            |   2 +-
 .../ui-conversation/tests/queue-dock.spec.tsx |   2 +-
 .../ui-conversation/tests/skeleton.spec.tsx   |   2 +-
 .../tests/produced-files.spec.tsx             |   2 +-
 .../client/ui-skill/tests/skill-row.spec.tsx  |   3 +-
 packages/client/ui-tool/README.i18n.yaml      |   4 +-
 packages/client/ui-tool/README.md             |   5 +-
 packages/client/ui-tool/README.zh.md          |   5 +-
 .../ui-tool/src/client/tool/ToolCallTree.tsx  |  65 ++++---
 .../ui-tool/tests/ask-question-row.spec.tsx   |   4 +-
 .../ui-tool/tests/assembly-surfaces.spec.tsx  |   3 +-
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  59 +++---
 .../ui-tool/tests/coverage-tails.spec.tsx     |   8 +-
 .../client/ui-tool/tests/diff-card.spec.tsx   |   6 +-
 .../client/ui-tool/tests/read-card.spec.tsx   |   6 +-
 .../client/ui-tool/tests/search-card.spec.tsx |   8 +-
 .../ui-tool/tests/terminal-card.spec.tsx      |  17 +-
 .../client/ui-tool/tests/todo-row.spec.tsx    |   4 +-
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  35 ++--
 .../client/ui-tool/tests/tool-row.spec.tsx    |   4 +-
 .../ui-tool/tests/toolview-slot.spec.tsx      |   2 +-
 .../client/ui-tool/tests/web-card.spec.tsx    |   8 +-
 .../src/client/TrajectoryView.tsx             |   4 +-
 .../client/ui-trajectory/src/client/layout.ts |  48 +++--
 .../ui-trajectory/tests/layout.spec.tsx       |  59 ++++--
 .../client/ui-trajectory/tests/views.spec.tsx |   5 +-
 48 files changed, 586 insertions(+), 413 deletions(-)
 create mode 100644 packages/client/runtime/src/client/sessions/tool-call-tree.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 5097b9e8a9..e1beb13c2c 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: e61c2030457cc9f0fda214e896b76afb37d0d2bc
-2026-08-08-client-tool-presentation-ownership.zh.md: 5c56b8c17ef5ca6695f3b28f6b93218dade356c7
+2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
+2026-08-08-client-tool-presentation-ownership.zh.md: 11a42ad69e4374afa6dccd3af74b8bd1b5e5c6f1
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index e61c203045..9ea7d7dfc5 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -12,19 +12,19 @@ That ownership made `ui-conversation` interpret business Tool names and made sub
 
 ## Decision
 
-Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Session Event, projection, fold, `ConversationSnapshot` construction and caching, historical paging, and Code Dispatch indexing remain unchanged.
+Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Runtime normalizes Code Dispatch into recursive `ToolCallBlock` values: every root or child owns its next level through `subCalls`, and `ConversationSnapshot` exposes no separate parent-to-children map.
 
 “First-class concept” describes UI ownership only; it adds no Runtime data kind. `ConversationNode` remains the transcript projection, `ChatFlowItem` remains the render unit produced when conversation sorts and groups nodes, `ToolCallBlock` remains the standard data for one call, and `ToolCallTree` only composes root/subcall presentation within Tool. Command continues to render through the separate `'conversation.chat.commandview'` seat and does not become Tool.
 
 `ui-conversation` owns ordered placement. `deriveChatFlow()` still decides where a settled Tool group appears, and `ChatView` still appends running calls, maintains scroll anchors and selection, and supplies host actions. For each root call it renders the single/session `'conversation.chat.tool'` seat with the root block, selected call id, session cwd, and open-file/inspect callbacks. It does not read Code Dispatch children, branch on Tool names, or import Tool-specific views and card models.
 
-`ui-tool` occupies that whole-Tool seat. Through its standard session slot props, `ToolCallTree` selects the Runtime-projected `codeDispatches[rootCallId]` array, renders the root followed by that one currently supported child level, and routes both forms through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. This is deliberately one-level composition, not a claim that the Runtime supports an arbitrary recursive call graph.
+`ui-tool` occupies that whole-Tool seat. `ToolCallTree` recursively walks the root block's `subCalls` and routes every level through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. It neither reads Session nor maintains a second call topology.
 
 Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this seam. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
 
 The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
 
-The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch stays a top-level official concept because it changes `codeDispatches` and parent/child identity; ordinary Tool business differences stay at the keyed presentation seam. This package boundary does not add a Tool projector/fold registry.
+The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation seam, and this package boundary adds no Tool projector/fold registry.
 
 ## Runtime and render path
 
@@ -39,22 +39,22 @@ ConversationSnapshot.runningCalls     |
   -> ChatView flow tail ---------------+-> ToolSeat
                                            -> conversation.chat.tool
                                            -> ToolCallTree
-ConversationSnapshot.codeDispatches[rootCallId] -+
-                                                  +-> root ToolCall + one-level child ToolCall
-                                                      -> tool.call.toolview(entryKey = toolName)
-                                                           |- registered atomic view
-                                                           `- GenericToolCard fallback
+                                                -> root ToolCallBlock
+                                                     `- subCalls[] (recursive)
+                                                          -> tool.call.toolview(entryKey = toolName)
+                                                               |- registered atomic view
+                                                               `- GenericToolCard fallback
 ```
 
-The live Session's [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) caches arrays or maps such as `nodes`, `runningCalls`, and `codeDispatches` against independent revisions. Their references stay stable when the corresponding business state has not changed, allowing React selectors and memoization to skip unrelated updates. The historical projection's [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) reconstructs the same running-call and Code Dispatch shapes from entries in its window. Tool UI consumes the snapshot shapes already unified by those paths; presentation packages do not repeat call/result pairing, historical replay, or cache indexing.
+Runtime's [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) privately indexes child lifecycles by parent callId and is shared by the live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) and historical [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) paths. It recursively projects children onto root `ToolCallBlock` values and copies only the owning ancestor path when a child changes. Unchanged siblings, other roots, and snapshot references with no Tool-topology change stay stable so React selectors and memoization can skip unrelated updates. Tool UI consumes this unified tree without repeating call/result pairing, historical replay, or cache indexing.
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. `ToolCallTree` selects only the current root's `codeDispatches[rootCallId]`; it does not introduce a business projector for presentation of other roots.
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. Selection is passed only to the root containing that call, and `ToolCallTree` then renders recursively within that local tree.
 
 ## Code and responsibility boundaries
 
 | Owner | Primary code | Owns | Explicitly does not own |
 |---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, Code Dispatch parent/child index, snapshot reference stability | Business views selected by Tool name |
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, recursive parent/child tree, snapshot structural sharing | Business views selected by Tool name |
 | `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts), [`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx), [`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow order, settled groups, running tail, scroll anchors, selection and host actions, whole-Tool seat declaration | subcall composition, `toolName` dispatch, Generic fallback, Tool card models |
 | `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts), [`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx), [`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall composition, atomic keyed dispatch, Generic fallback, Tool card models and built-in Tool views | ChatFlow ordering, Session Event fold |
 | Business Tool plugins | [`ui-skill` registration example](../../../../packages/client/ui-skill/src/client/index.ts) | Atomic views for one or more wire Tool names | root/subcall placement and lifecycle pairing |
@@ -82,7 +82,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Details path
 
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) still locates the selected call in `nodes`, `runningCalls`, and `codeDispatches`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
+[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) locates the selected call recursively in `nodes` and `runningCalls` through their `subCalls`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
 
 ## Verification
 
@@ -96,7 +96,7 @@ Test ownership follows production ownership. `ui-conversation` tests install a l
 
 **Add business-specific Session projectors or folds.** Rejected: ordinary Tool views consume the standard call block already reconstructed by Runtime. A second registry would create two authorities for call identity and historical replay. Only a feature that changes logged topology or lifecycle earns a Runtime-level extension.
 
-**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Root/child composition belongs to `ui-tool`, and the current wire/runtime shape only supports one Code Dispatch child level.
+**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Recursive root/child composition belongs centrally to `ui-tool`'s `ToolCallTree`.
 
 **Import `ui-tool` components directly from `ui-conversation`.** Rejected: it would reverse the intended feature direction and make Tool presentation mandatory. Declared slots retain lifecycle ownership, fallback behavior, and independent plugin loading.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 5c56b8c17e..11a42ad69e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -12,19 +12,19 @@ Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `cal
 
 ## Decision
 
-Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Session Event、projection、fold、`ConversationSnapshot` 构建与缓存、历史分页及 Code Dispatch 索引保持不变。
+Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Runtime 将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
 
 这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
 
 `ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
 
-`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，先渲染 root，再渲染当前支持的一层 child；两种调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。这里刻意只编排一层，并不声称 Runtime 已支持任意递归调用图。
+`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
 
 业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
 
 details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
 
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 会改变 `codeDispatches` 与 parent/child identity，因此继续作为官方顶级概念；普通 Tool 业务差异停留在 keyed 展示 seam。这个包边界不会增加 Tool projector/fold registry。
+Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
 
 ## Runtime 与渲染链路
 
@@ -39,22 +39,22 @@ ConversationSnapshot.runningCalls     |
   -> ChatView flow tail ---------------+-> ToolSeat
                                            -> conversation.chat.tool
                                            -> ToolCallTree
-ConversationSnapshot.codeDispatches[rootCallId] -+
-                                                  +-> root ToolCall + one-level child ToolCall
-                                                      -> tool.call.toolview(entryKey = toolName)
-                                                           |- registered atomic view
-                                                           `- GenericToolCard fallback
+                                                -> root ToolCallBlock
+                                                     `- subCalls[] (recursive)
+                                                          -> tool.call.toolview(entryKey = toolName)
+                                                               |- registered atomic view
+                                                               `- GenericToolCard fallback
 ```
 
-Live Session 的 [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 按独立 revision 缓存 `nodes`、`runningCalls`、`codeDispatches` 等数组或 map；没有对应业务变化时，它们保持引用稳定，供 React selector 与 memo 跳过无关更新。历史 projection 的 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 从窗口内 entry 重建相同的 running call 与 Code Dispatch 形态。Tool UI 直接消费这两个路径已经统一的 snapshot，不在展示包中重复 call/result 配对、历史 replay 或缓存索引。
+Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供 Live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。`ToolCallTree` 只选择当前 root 的 `codeDispatches[rootCallId]`，不会因其他 root 的展示逻辑引入业务 projector。
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。selection 只传给包含该 call 的 root，`ToolCallTree` 再沿该 root 的局部树递归渲染。
 
 ## 代码与职责边界
 
 | 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
 |---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、Code Dispatch parent/child 索引、snapshot 引用稳定性 | Tool 名称对应的业务视图 |
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、snapshot 结构共享 | Tool 名称对应的业务视图 |
 | `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
 | `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
 | 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
@@ -82,7 +82,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Details 路径
 
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 仍从 `nodes`、`runningCalls` 与 `codeDispatches` 中定位选中的 call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
+[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 在 `nodes` 与 `runningCalls` 的递归 `subCalls` 中定位 selected call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
 
 ## Verification
 
@@ -96,7 +96,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 **增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
 
-**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。root/child 编排归 `ui-tool`，且当前 wire/runtime 形态只支持一层 Code Dispatch child。
+**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。递归 root/child 编排统一归 `ui-tool` 的 `ToolCallTree`。
 
 **让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转预期的 feature 依赖方向，并把 Tool 展示变成必选能力。声明式 slot 能保留生命周期所有权、fallback 行为与独立插件装载。
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index f45ceb712d..bb64a12d4e 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: bb85d3c7b45eb0d82d789a9133bba787f1d6c5e9
-README.zh.md: 18aedbb487a490c85ce68ccc460fd82218157843
+README.md: fad0f6e4f948ebf412b2bd837a4f68e6dc805ec8
+README.zh.md: 4ede12a320082a5023ec121306650fce72a12663
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index bb85d3c7b4..fad0f6e4f9 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -44,9 +44,9 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr
 
 `SessionHistoryInspection.requests` is one chronological, purpose-discriminated provider-request stream. Assistant requests always carry their numeric `turn` and `step`; compaction requests carry `step: 0` and a `turn` owner that may be `null`. That null owner means a manual compaction ran standalone between turns, not that it belongs to either adjacent turn. A `session/end-seed` boundary closes an unmatched compaction request as an error at the boundary time with `Compaction was interrupted before completion.`; a later start projects as an independent request instead of overwriting the orphan.
 
-## Code Mode sub-dispatch index
+## Code Mode child-call tree
 
-`ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in start order, using the native call-block shapes: a `tool/code-dispatch-start` event lands the `RunningToolCall` form (rows derive the running ring from the shape) and its `tool/code-dispatch` settlement replaces it in place with the `ToolResultNode` form, `callTime` carrying the paired start's time. A settle whose start fell outside the replay window appends directly with `callTime: null` (duration unknown — never a fabricated zero). Live mux frames and history replay build the identical index; sub-calls never join the transcript `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity.
 
 ## Session title projection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 18aedbb487..4ede12a320 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -44,9 +44,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `SessionHistoryInspection.requests` 是一条按时间顺序排列、以用途为判别字段的提供方请求流。助手请求始终携带数值型 `turn` 与 `step`；压缩请求携带 `step: 0`，其 `turn` 所有者可以是 `null`。这个 null 所有者表示手动压缩独立运行在两个轮次之间，并不表示它属于任一相邻轮次。`session/end-seed` 边界会在边界时刻将未匹配的压缩请求以错误状态结束，错误固定为 `Compaction was interrupted before completion.`；后续 start 会投影为独立请求，而不会覆盖这项遗留的未匹配请求。
 
-## Code Mode 子调用索引
+## Code Mode 子调用树
 
-`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 transcript 的 `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。
 
 ## Session 标题投影
 
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 3c4e8e0bf4..b7226c0085 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -8,7 +8,7 @@ import { SessionsService } from './sessions/service.ts'
 import type { SessionListState } from './sessions/service.ts'
 import { SessionHistoryService } from './session-history/service.ts'
 import { WorkspacesService } from './workspaces/service.ts'
-import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './sessions/conversation.ts'
+import type { ConversationSnapshot } from './sessions/conversation.ts'
 import type { UseProjection } from './sessions/projection-store.ts'
 
 export { SlotsService } from './slots.ts'
@@ -49,10 +49,10 @@ export type {
 } from './contract/store.ts'
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
+  AssistantTiming, CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
   RunningToolCall,
-  SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
   ConversationContext, ConversationContextOriginKind,
@@ -89,13 +89,6 @@ declare module '@deepseek-ai/dsh-type-meta' {
 /** The conversation-snapshot selector hook supplied to session-scoped UI entries. */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
-/**
- * One tool call as the chat flow renders it: still-running (spinner card) or
- * settled (result node). The fold produces both shapes; toolview components
- * narrow on the discriminant fields.
- */
-export type ToolCallBlock = RunningToolCall | ToolResultNode
-
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   /**
    * Session standard kit, real members (ui-slots declares the empty seat;
diff --git a/packages/client/runtime/src/client/session-history/history-fold.ts b/packages/client/runtime/src/client/session-history/history-fold.ts
index d792fd2b76..42aaa37027 100644
--- a/packages/client/runtime/src/client/session-history/history-fold.ts
+++ b/packages/client/runtime/src/client/session-history/history-fold.ts
@@ -1,4 +1,3 @@
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import {
   SurfaceManager, isSurfaceEligibleType, isSurfaceEvent,
@@ -7,7 +6,7 @@ import type {
   HistoryEntry, ToolCallView, ToolResultView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type {
-  AssistantRequestConfig, AssistantTiming, CodeSubCall, ConversationNode,
+  AssistantRequestConfig, AssistantTiming, ConversationNode,
   PartialAssistant, RunningToolCall,
 } from '../sessions/conversation.ts'
 import { toAssistantBlocks } from '../sessions/conversation.ts'
@@ -20,6 +19,7 @@ import type { ConversationPromptSnapshot } from '../sessions/request-inspection.
 import { PartialAccumulator } from '../sessions/partial.ts'
 import type { AssistantStepMetadata } from '../sessions/assistant-timing.ts'
 import { indexAssistantStepTiming, settledAssistantTiming } from '../sessions/assistant-timing.ts'
+import { ToolCallTree } from '../sessions/tool-call-tree.ts'
 
 interface CallIndexEntry {
   name: string
@@ -41,7 +41,6 @@ export interface ConversationHistoryProjection {
   interruptedNodes: readonly ConversationNode[]
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }
 
 function replacementCrossesWindowHead(event: SessionEvent, baseSeq: number): boolean {
@@ -177,6 +176,7 @@ function materializeNode(
         meta: event.data.meta,
         callView: call?.callView ?? null,
         resultView,
+        subCalls: [],
       }
     }
     default:
@@ -188,74 +188,22 @@ function materializeNode(
 }
 /* jscpd:ignore-end */
 
-function projectTransient(entries: readonly HistoryEntry[]): Pick<
+interface TransientProjection extends Pick<
   ConversationHistoryProjection,
-  'interruptedNodes' | 'partial' | 'runningCalls' | 'codeDispatches'
+  'interruptedNodes' | 'partial' | 'runningCalls'
 > {
+  toolCallTree: ToolCallTree
+}
+
+function projectTransient(entries: readonly HistoryEntry[]): TransientProjection {
   let partial: PartialAccumulator | null = null
   const openCalls = new Map<string, RunningToolCall>()
   const interruptedNodes: ConversationNode[] = []
-  const codeDispatches = new Map<string, readonly CodeSubCall[]>()
+  const toolCallTree = new ToolCallTree()
 
   for (const entry of entries) {
     const { event } = entry
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
-      const siblings = codeDispatches.get(data.parentCallId) ?? []
-      // The independent replay emits the same public running-call shape as
-      // Chat without reading or mutating Session's live index.
-      /* jscpd:ignore-start */
-      codeDispatches.set(data.parentCallId, [...siblings, {
-        callId: data.subCallId,
-        name: data.name,
-        argsRaw: JSON.stringify(data.arguments),
-        turn: 0,
-        step: 0,
-        time: event.time,
-        callView: null,
-      }])
-      /* jscpd:ignore-end */
-      continue
-    }
-    if ((event.type as string) === 'tool/code-dispatch') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-        isError: boolean
-        content: ContentBlock[]
-      }
-      const siblings = codeDispatches.get(data.parentCallId) ?? []
-      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-      const started = at === -1 ? undefined : siblings[at]
-      // History independently reproduces the public settled-call shape instead
-      // of consuming Session's live code-dispatch projection.
-      /* jscpd:ignore-start */
-      const settled: CodeSubCall = {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId: data.subCallId,
-        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
-        callTime: started?.time ?? null,
-        content: data.content,
-        isError: data.isError,
-        callView: null,
-        resultView: null,
-      }
-      codeDispatches.set(
-        data.parentCallId,
-        at === -1
-          ? [...siblings, settled]
-          : siblings.map((sub, index) => index === at ? settled : sub),
-      )
-      /* jscpd:ignore-end */
-      continue
-    }
+    if (toolCallTree.apply(event)) continue
     switch (event.type) {
       case 'assistant/chunk': {
         const { turn, step, chunk } = event.data
@@ -280,6 +228,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
           step: event.data.step,
           time: event.time,
           callView: entry.view?.for === 'call' ? entry.view.view : null,
+          subCalls: [],
         })
         /* jscpd:ignore-end */
         break
@@ -317,6 +266,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
             error: { name: 'Interrupted', code: 'interrupted' },
             callView: call.callView,
             resultView: null,
+            subCalls: [],
           })
           /* jscpd:ignore-end */
         }
@@ -331,7 +281,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
     interruptedNodes,
     partial: partial?.toPartial() ?? null,
     runningCalls: [...openCalls.values()],
-    codeDispatches,
+    toolCallTree,
   }
 }
 
@@ -462,9 +412,17 @@ export function projectConversationHistory(
     }
   }
 
+  const transient = projectTransient(entries)
+  const projectedEventNodes = transient.toolCallTree.projectNodes(eventNodes)
+  const projectedContexts = contexts.map((context): ConversationContext => {
+    const nodes = transient.toolCallTree.projectNodes(context.nodes)
+    return nodes === context.nodes ? context : { ...context, nodes }
+  })
   return {
-    eventNodes,
-    contexts,
-    ...projectTransient(entries),
+    eventNodes: projectedEventNodes,
+    contexts: projectedContexts,
+    interruptedNodes: transient.toolCallTree.projectNodes(transient.interruptedNodes),
+    partial: transient.partial,
+    runningCalls: transient.toolCallTree.projectRunningCalls(transient.runningCalls),
   }
 }
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index a881158525..dba9ec9513 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -174,6 +174,8 @@ export interface ToolResultNode {
   callView: ToolCallView | null
   /** Host-computed render intent from this tool/result's wire view; null = same default. */
   resultView: ToolResultView | null
+  /** Child calls owned by this call, in dispatch order. */
+  subCalls: readonly ToolCallBlock[]
 }
 
 /**
@@ -263,21 +265,6 @@ export type ConversationNode =
   | CompactionSummaryNode
   | UnknownSurfaceNode
 
-/**
- * One `run_code` sub-dispatch materialized in the native call-block shapes so
- * every consumer (tool rows, details panel) renders it through the exact
- * components that render a native call: a started-but-unsettled sub-call is a
- * {@link RunningToolCall} (rows derive the running state from the shape,
- * exactly as for native calls) and its `tool/code-dispatch` settlement
- * replaces it in place with the {@link ToolResultNode} form. Never part of
- * the transcript `nodes` flow — sub-calls live under their parent via
- * {@link ConversationSnapshot.codeDispatches}. `callId` is the deterministic
- * sub-call id (`<parent>:code:<n>`); the call side carries the sub-tool name
- * and its JSON-stringified logged arguments; `content`/`isError` are the
- * settled sub-call's complete logged outcome.
- */
-export type CodeSubCall = RunningToolCall | ToolResultNode
-
 /** In-flight tool card material: tool/call seen, tool/result not yet. */
 export interface RunningToolCall {
   callId: string
@@ -289,8 +276,12 @@ export interface RunningToolCall {
   time: number
   /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
   callView: ToolCallView | null
+  /** Child calls owned by this call, in dispatch order. */
+  subCalls: readonly ToolCallBlock[]
 }
 
+/** One running or settled call, recursively owning its child calls. */
+export type ToolCallBlock = RunningToolCall | ToolResultNode
 
 /** One transient inbox occurrence from the authoritative `session/queue` snapshot. */
 export interface QueuedMessage {
@@ -355,13 +346,6 @@ export interface ConversationSnapshot {
   turnEnds: ReadonlyMap<number, number>
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
-  /**
-   * `run_code` sub-dispatches grouped under their parent callId, in dispatch
-   * order. Populated from in-window `tool/code-dispatch` events (live and
-   * replay identically); the per-parent array reference is stable across
-   * unrelated snapshot swaps (memo premise, same regime as `nodes`).
-   */
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
   pending: readonly PendingInteraction[]
   /** Authoritative transient inbox snapshot, including queued and steering placements. */
   queue: readonly QueuedMessage[]
diff --git a/packages/client/runtime/src/client/sessions/history.ts b/packages/client/runtime/src/client/sessions/history.ts
index fbf7b08f3d..8609481d33 100644
--- a/packages/client/runtime/src/client/sessions/history.ts
+++ b/packages/client/runtime/src/client/sessions/history.ts
@@ -1,7 +1,7 @@
 import type { ToolSchema } from '@deepseek-ai/dsh-llm/types'
 import type { HistoryEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type {
-  CodeSubCall, ConversationNode, PartialAssistant, RunningToolCall,
+  ConversationNode, PartialAssistant, RunningToolCall,
 } from './conversation.ts'
 import type { ConversationContext } from './conversation-context.ts'
 import { projectConversationHistory } from '../session-history/history-fold.ts'
@@ -34,7 +34,6 @@ export interface SessionHistoryInspection {
   interruptedNodes: readonly ConversationNode[]
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }
 
 /**
@@ -112,9 +111,6 @@ export function createHistoryInspection(
     get runningCalls() {
       return conversationProjection().runningCalls
     },
-    get codeDispatches() {
-      return conversationProjection().codeDispatches
-    },
     get requests() {
       return requestProjection().requests
     },
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 776f4494fd..075fd686ea 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -13,7 +13,7 @@ import type {
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SessionFace } from '../contract/session.ts'
 import type {
-  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
+  ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
   OpenState, PromptError, QueuedMessage, RunningToolCall,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
@@ -24,6 +24,7 @@ import { Notifier } from './notifier.ts'
 import { isVisibleAssistantChunk, PartialAccumulator } from './partial.ts'
 import { ProjectionValueStore } from './projection-store.ts'
 import type { ProjectionsBaseline } from './projection-store.ts'
+import { ToolCallTree } from './tool-call-tree.ts'
 
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
@@ -129,11 +130,8 @@ export class Session implements SessionFace {
   private queued: QueuedMessage[] = []
   private queueRev = 0
   private queueCache: { rev: number; value: QueuedMessage[] } | null = null
-  /** `run_code` sub-dispatches by parent callId (window-derived, like openCalls). Appends
-   *  copy-on-write the per-parent array so published snapshot references never mutate. */
-  private codeDispatches = new Map<string, readonly CodeSubCall[]>()
-  private dispatchesRev = 0
-  private dispatchesCache: { rev: number; value: ReadonlyMap<string, readonly CodeSubCall[]> } | null = null
+  /** Window-derived child-call lifecycle and immutable tree projection. */
+  private readonly toolCallTree = new ToolCallTree()
   private running = false
   private address: SubagentAddress | undefined
   private parentAvailable = false
@@ -746,65 +744,10 @@ export class Session implements SessionFace {
       this.derivedRev++
       return
     }
-    // The `tool/code-dispatch-start`/`tool/code-dispatch` pair is declared by
-    // the host-side dsh-tools plugin whose types cannot enter the client
-    // program (its host Context merges collide with the client's), so this
-    // wire consumer narrows them structurally — the same posture as every
-    // other cross-wire event payload.
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      // A started sub-dispatch enters the index as a RunningToolCall — the
-      // exact shape a native in-flight call renders from — under its parent
-      // run_code callId; it never joins the surface flow.
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
-      const running: CodeSubCall = {
-        callId: data.subCallId, name: data.name,
-        argsRaw: JSON.stringify(data.arguments),
-        turn: 0, step: 0, time: event.time, callView: null,
-      }
-      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
-      this.codeDispatches.set(data.parentCallId, [...siblings, running])
-      this.dispatchesRev++
-      return
-    }
-    if ((event.type as string) === 'tool/code-dispatch') {
-      // Settlement replaces the running entry in place (same array position,
-      // so parallel sub-calls keep their start order) with the
-      // ToolResultNode form; a settle with no observed start (history window
-      // cut mid-pair, or a pre-start-event log) appends directly.
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-        isError: boolean
-        content: ContentBlock[]
-      }
-      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
-      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-      const started = at === -1 ? undefined : siblings[at]
-      const settled: CodeSubCall = {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId: data.subCallId,
-        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
-        // Duration source: the paired start's time when observed; null =
-        // unknown (settle-only window), matching the native tool-result
-        // contract so views never present a fabricated zero duration.
-        callTime: started === undefined ? null : started.time,
-        content: data.content, isError: data.isError,
-        callView: null, resultView: null,
-      }
-      this.codeDispatches.set(
-        data.parentCallId,
-        at === -1 ? [...siblings, settled] : siblings.map((sub, index) => (index === at ? settled : sub)),
-      )
-      this.dispatchesRev++
-      return
-    }
+    // These lifecycle events are declared by a host-only plugin whose Context
+    // types cannot enter the client program. ToolCallTree owns their structural
+    // wire narrowing, pairing, and nested snapshot projection.
+    if (this.toolCallTree.apply(event)) return
     switch (event.type) {
       case 'turn/start':
         this.lastStepByTurn.set(event.data.turn, 0)
@@ -834,6 +777,7 @@ export class Session implements SessionFace {
           callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
           turn: event.data.turn, step: event.data.step, time: event.time,
           callView: view?.for === 'call' ? view.view : null,
+          subCalls: [],
         })
         this.callsRev++
         return
@@ -901,7 +845,7 @@ export class Session implements SessionFace {
             call: { name: call.name, argsRaw: call.argsRaw },
             callTime: call.time,
             content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
-            callView: call.callView, resultView: null,
+            callView: call.callView, resultView: null, subCalls: [],
           })
           this.derivedRev++
         }
@@ -948,8 +892,7 @@ export class Session implements SessionFace {
     this.turnTimingsRev++
     this.turnEnds = new Map()
     this.turnEndsRev++
-    this.codeDispatches = new Map()
-    this.dispatchesRev++
+    this.toolCallTree.reset()
     for (let i = 0; i < this.events.length; i++) {
       const event = this.events[i]
       /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
@@ -988,22 +931,18 @@ export class Session implements SessionFace {
     if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
       this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
     }
-    if (this.dispatchesCache === null || this.dispatchesCache.rev !== this.dispatchesRev) {
-      this.dispatchesCache = { rev: this.dispatchesRev, value: new Map(this.codeDispatches) }
-    }
     if (this.queueCache === null || this.queueCache.rev !== this.queueRev) {
       this.queueCache = { rev: this.queueRev, value: this.queued }
     }
     const partial = this.partial?.toPartial() ?? null
     return {
       sessionId: this.sessionId,
-      nodes,
+      nodes: this.toolCallTree.projectNodes(nodes),
       turnTimings: this.turnTimingsCache.value,
       turnEnds: this.turnEndsCache.value,
       partial,
-      runningCalls: this.callsCache.value,
+      runningCalls: this.toolCallTree.projectRunningCalls(this.callsCache.value),
       pending: this.pendingCache.value,
-      codeDispatches: this.dispatchesCache.value,
       queue: this.queueCache.value,
       running: this.running,
       subagent: this.address === undefined
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
new file mode 100644
index 0000000000..ef25ba3da2
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -0,0 +1,171 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {
+  ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode,
+} from './conversation.ts'
+
+interface ProjectedBlock {
+  source: ToolCallBlock
+  children: readonly ToolCallBlock[]
+  value: ToolCallBlock
+}
+
+function sameBlocks(
+  left: readonly ToolCallBlock[],
+  right: readonly ToolCallBlock[],
+): boolean {
+  return left.length === right.length
+    && left.every((block, index) => block === right[index])
+}
+
+/**
+ * Owns Code Dispatch pairing and projects its private parent index into the
+ * recursive Tool call contract exposed by conversation snapshots.
+ */
+export class ToolCallTree {
+  private readonly childrenByParent = new Map<string, readonly ToolCallBlock[]>()
+  private readonly projectedByCall = new Map<string, ProjectedBlock>()
+  private revision = 0
+  private nodesCache: {
+    source: readonly ConversationNode[]
+    revision: number
+    value: readonly ConversationNode[]
+  } | null = null
+  private runningCache: {
+    source: readonly RunningToolCall[]
+    revision: number
+    value: readonly RunningToolCall[]
+  } | null = null
+
+  /** Forget all event-derived child calls before replaying a new window. */
+  reset(): void {
+    this.childrenByParent.clear()
+    this.projectedByCall.clear()
+    this.revision++
+  }
+
+  /**
+   * Fold one event when it belongs to the Code Dispatch lifecycle.
+   * @param event - Session event from the current live or history window.
+   * @returns Whether the event was consumed as a child-call lifecycle event.
+   */
+  apply(event: SessionEvent): boolean {
+    if ((event.type as string) === 'tool/code-dispatch-start') {
+      const data = event.data as unknown as {
+        parentCallId: string
+        subCallId: string
+        name: string
+        arguments: unknown
+      }
+      const running: RunningToolCall = {
+        callId: data.subCallId,
+        name: data.name,
+        argsRaw: JSON.stringify(data.arguments),
+        turn: 0,
+        step: 0,
+        time: event.time,
+        callView: null,
+        subCalls: [],
+      }
+      const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+      this.childrenByParent.set(data.parentCallId, [...siblings, running])
+      this.revision++
+      return true
+    }
+    if ((event.type as string) !== 'tool/code-dispatch') return false
+    const data = event.data as unknown as {
+      parentCallId: string
+      subCallId: string
+      name: string
+      arguments: unknown
+      isError: boolean
+      content: ContentBlock[]
+    }
+    const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+    const at = siblings.findIndex(sub => sub.callId === data.subCallId)
+    const started = at === -1 ? undefined : siblings[at]
+    const settled: ToolResultNode = {
+      kind: 'tool-result',
+      seq: event.seq,
+      time: event.time,
+      callId: data.subCallId,
+      call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
+      callTime: started?.time ?? null,
+      content: data.content,
+      isError: data.isError,
+      callView: null,
+      resultView: null,
+      subCalls: [],
+    }
+    this.childrenByParent.set(
+      data.parentCallId,
+      at === -1
+        ? [...siblings, settled]
+        : siblings.map((sub, index) => index === at ? settled : sub),
+    )
+    this.revision++
+    return true
+  }
+
+  /**
+   * Attach recursively projected children to all settled roots in a node list.
+   * @param nodes - Cache-stable base conversation nodes.
+   * @returns The original list when no root changed, otherwise a structurally shared list.
+   */
+  projectNodes(nodes: readonly ConversationNode[]): readonly ConversationNode[] {
+    if (this.nodesCache?.source === nodes && this.nodesCache.revision === this.revision) {
+      return this.nodesCache.value
+    }
+    let changed = false
+    const projected = nodes.map((node): ConversationNode => {
+      if (node.kind !== 'tool-result') return node
+      const value = this.projectBlock(node) as ToolResultNode
+      changed ||= value !== node
+      return value
+    })
+    const value = changed ? projected : nodes
+    this.nodesCache = { source: nodes, revision: this.revision, value }
+    return value
+  }
+
+  /**
+   * Attach recursively projected children to all running root calls.
+   * @param calls - Cache-stable base running calls.
+   * @returns The original list when no root changed, otherwise a structurally shared list.
+   */
+  projectRunningCalls(calls: readonly RunningToolCall[]): readonly RunningToolCall[] {
+    if (this.runningCache?.source === calls && this.runningCache.revision === this.revision) {
+      return this.runningCache.value
+    }
+    let changed = false
+    const projected = calls.map((call): RunningToolCall => {
+      const value = this.projectBlock(call) as RunningToolCall
+      changed ||= value !== call
+      return value
+    })
+    const value = changed ? projected : calls
+    this.runningCache = { source: calls, revision: this.revision, value }
+    return value
+  }
+
+  private projectBlock(block: ToolCallBlock): ToolCallBlock {
+    const children = this.childrenByParent.get(block.callId) ?? block.subCalls
+    const projectedChildren = children.map(child => this.projectBlock(child))
+    const childValue = sameBlocks(children, projectedChildren)
+      ? children
+      : projectedChildren
+    const cached = this.projectedByCall.get(block.callId)
+    if (cached?.source === block && sameBlocks(cached.children, childValue)) {
+      return cached.value
+    }
+    const value: ToolCallBlock = block.subCalls === childValue
+      ? block
+      : { ...block, subCalls: childValue }
+    this.projectedByCall.set(block.callId, {
+      source: block,
+      children: childValue,
+      value,
+    })
+    return value
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index ae7643f0de..25fade8633 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -103,6 +103,7 @@ function materializeNode(
         meta: event.data.meta,
         callView: call?.callView ?? null,
         resultView,
+        subCalls: [],
       }
     }
     /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index c288c044ee..b5400ecff9 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -1151,7 +1151,17 @@ describe('resync', () => {
 
 })
 
-describe('run_code sub-dispatch indexing', () => {
+describe('nested run_code sub-dispatches', () => {
+  const subCallsOf = (session: Session, callId: string) => {
+    const snapshot = session.getSnapshot()
+    const running = snapshot.runningCalls.find(call => call.callId === callId)
+    if (running !== undefined) return running.subCalls
+    for (const node of snapshot.nodes) {
+      if (node.kind === 'tool-result' && node.callId === callId) return node.subCalls
+    }
+    return undefined
+  }
+
   it('a start event lands as a running-shaped sub-call and its settle replaces it in place', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
@@ -1161,19 +1171,19 @@ describe('run_code sub-dispatch indexing', () => {
     feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
     feed(ev.codeDispatchStart(8, 'p1', 1, 'bash', { command: 'sleep' }))
     feed(ev.codeDispatchStart(9, 'p1', 2, 'read', { path: 'a.txt' }))
-    const live = session.getSnapshot().codeDispatches.get('p1')
+    const live = subCallsOf(session, 'p1')
     expect(live).toHaveLength(2)
     // Running shape (no 'kind'): the exact RunningToolCall form native rows use.
     expect(live?.[0]).toMatchObject({ callId: 'p1:code:1', name: 'bash', argsRaw: '{"command":"sleep"}' })
     expect(live?.[0] !== undefined && 'kind' in live[0]).toBe(false)
     // Settle out of order (parallel run): #2 first — replaces in place, keeping start order.
     feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'a.txt' }, 'alpha'))
-    const mixed = session.getSnapshot().codeDispatches.get('p1')
+    const mixed = subCallsOf(session, 'p1')
     expect(mixed?.map(sub => 'kind' in sub)).toEqual([false, true])
     expect(mixed?.[1]).toMatchObject({ callId: 'p1:code:2', content: [{ type: 'text', text: 'alpha' }] })
     // The settle carries the paired start's time as callTime (duration source).
     feed(ev.codeDispatch(11, 'p1', 1, 'bash', { command: 'sleep' }, 'done'))
-    const settled = session.getSnapshot().codeDispatches.get('p1')
+    const settled = subCallsOf(session, 'p1')
     expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
     expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
   })
@@ -1187,7 +1197,7 @@ describe('run_code sub-dispatch indexing', () => {
     feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'))
     feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls', description: '列目录' }, 'demo.txt'))
     feed(ev.codeDispatch(9, 'p1', 2, 'read', { path: 'a.txt' }, 'Error: ENOENT', true))
-    const subs = session.getSnapshot().codeDispatches.get('p1')
+    const subs = subCallsOf(session, 'p1')
     expect(subs).toHaveLength(2)
     expect(subs?.[0]).toMatchObject({
       kind: 'tool-result', callId: 'p1:code:1',
@@ -1205,23 +1215,29 @@ describe('run_code sub-dispatch indexing', () => {
     expect(session.getSnapshot().nodes.some(n => n.kind === 'tool-result' && n.callId.includes(':code:'))).toBe(false)
   })
 
-  it('rebuilds the same index from a history window (replay parity)', async () => {
+  it('rebuilds the same nested tree from a history window (replay parity)', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse([
       ...plainTurn(0, 0, '问', '答'),
       ev.turnStart(6, 1),
       ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'),
-      ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'demo.txt'),
-      ev.toolResult(9, 1, 'p1', '{"done":true}'),
-      ev.turnEnd(10, 1),
+      ev.codeDispatchStart(8, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }),
+      ev.codeDispatch(9, 'p1:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
+      ev.codeDispatch(10, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }, 'alpha'),
+      ev.toolResult(11, 1, 'p1', '{"done":true}'),
+      ev.turnEnd(12, 1),
     ])
     await session.open()
-    const subs = session.getSnapshot().codeDispatches.get('p1')
+    const subs = subCallsOf(session, 'p1')
     expect(subs).toHaveLength(1)
-    expect(subs?.[0]).toMatchObject({ callId: 'p1:code:1', call: { name: 'bash' } })
+    expect(subs?.[0]).toMatchObject({
+      callId: 'p1:code:1',
+      call: { name: 'run_code' },
+      subCalls: [{ callId: 'p1:code:1:code:1', call: { name: 'read' } }],
+    })
   })
 
-  it('keeps the dispatch map reference across unrelated changes and swaps it on a new dispatch', async () => {
+  it('keeps an unaffected root reference and path-copies it on a new child', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
     await session.open()
@@ -1230,13 +1246,48 @@ describe('run_code sub-dispatch indexing', () => {
     feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
     feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'x'))
     const before = session.getSnapshot()
+    const beforeRoot = before.runningCalls.find(call => call.callId === 'p1')!
     feed(ev.chunkStart(9, 1))
     feed(ev.chunkText(10, 1, '流式'))
     const after = session.getSnapshot()
-    expect(after.codeDispatches).toBe(before.codeDispatches)
+    const afterRoot = after.runningCalls.find(call => call.callId === 'p1')!
+    expect(afterRoot).toBe(beforeRoot)
     feed(ev.codeDispatch(11, 'p1', 2, 'read', { path: 'a' }, 'y'))
-    expect(session.getSnapshot().codeDispatches).not.toBe(after.codeDispatches)
-    expect(session.getSnapshot().codeDispatches.get('p1')).toHaveLength(2)
+    const changedRoot = session.getSnapshot().runningCalls.find(call => call.callId === 'p1')!
+    expect(changedRoot).not.toBe(afterRoot)
+    expect(changedRoot.subCalls[0]).toBe(afterRoot.subCalls[0])
+    expect(changedRoot.subCalls).toHaveLength(2)
+  })
+
+  it('path-copies only the owning branch when a nested child changes', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '树', '结构'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"first"}'))
+    feed(ev.toolCall(8, 1, 'p2', 'run_code', '{"code":"2","description":"second"}'))
+    feed(ev.codeDispatch(9, 'p1', 1, 'run_code', { code: 'nested' }, 'child'))
+    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'sibling' }, 'sibling'))
+    feed(ev.codeDispatch(11, 'p2', 1, 'bash', { command: 'pwd' }, 'root two'))
+    const before = session.getSnapshot()
+    const beforeFirst = before.runningCalls.find(call => call.callId === 'p1')!
+    const beforeSecond = before.runningCalls.find(call => call.callId === 'p2')!
+    const beforeChild = beforeFirst.subCalls[0]!
+    const beforeSibling = beforeFirst.subCalls[1]!
+
+    feed(ev.codeDispatch(12, 'p1:code:1', 1, 'read', { path: 'nested' }, 'leaf'))
+    const after = session.getSnapshot()
+    const afterFirst = after.runningCalls.find(call => call.callId === 'p1')!
+    const afterSecond = after.runningCalls.find(call => call.callId === 'p2')!
+
+    expect(afterFirst).not.toBe(beforeFirst)
+    expect(afterSecond).toBe(beforeSecond)
+    expect(afterFirst.subCalls[0]).not.toBe(beforeChild)
+    expect(afterFirst.subCalls[1]).toBe(beforeSibling)
+    expect(afterFirst.subCalls[0]?.subCalls).toMatchObject([
+      { callId: 'p1:code:1:code:1', call: { name: 'read' } },
+    ])
   })
 })
 
diff --git a/packages/client/test-runtime/src/fixtures.ts b/packages/client/test-runtime/src/fixtures.ts
index 9cf025192c..ea01893346 100644
--- a/packages/client/test-runtime/src/fixtures.ts
+++ b/packages/client/test-runtime/src/fixtures.ts
@@ -50,7 +50,6 @@ export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot
     turnEnds: new Map(),
     partial: null,
     runningCalls: [],
-    codeDispatches: new Map(),
     pending: [],
     queue: [],
     running: false,
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index c52a4623be..d021e2f388 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -24,7 +24,7 @@ import {
   memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
 import type {
-  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
+  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -111,6 +111,11 @@ type ChatScrollPosition = NonNullable<ReturnType<ChatViewSlotProps['chatScroll']
  *  chat view narrows once to the runtime snapshot the binding actually feeds. */
 type UseConversation = SnapshotSelectorHook<ConversationSnapshot>
 
+function treeContainsCall(block: ToolCallBlock, callId: string | undefined): boolean {
+  return callId !== undefined
+    && (block.callId === callId || block.subCalls.some(child => treeContainsCall(child, callId)))
+}
+
 function activeRetrySeq(nodes: readonly ConversationNode[], running: boolean): number | null {
   if (!running) return null
   for (let index = nodes.length - 1; index >= 0; index -= 1) {
@@ -174,7 +179,7 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selec
           toolName={node.call?.name ?? ''}
           block={node}
           openFile={openFile}
-          selectedCallId={selectedCallId}
+          selectedCallId={treeContainsCall(node, selectedCallId) ? selectedCallId : undefined}
           cwd={cwd}
           inspectCall={inspectCall}
         />
@@ -595,7 +600,7 @@ export function ChatView({
                   toolName={call.name}
                   block={call}
                   openFile={openFile}
-                  selectedCallId={selectedCallId}
+                  selectedCallId={treeContainsCall(call, selectedCallId) ? selectedCallId : undefined}
                   cwd={cwd}
                   inspectCall={inspectCall}
                 />
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index c2104c23c7..a04e9ba9e8 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -40,19 +40,27 @@ function runningMaterial(call: RunningToolCall): CallMaterial {
   return { name: call.name, argsRaw: call.argsRaw, block: call }
 }
 
+function findCall(block: ToolCallBlock, callId: string): ToolCallBlock | undefined {
+  if (block.callId === callId) return block
+  for (const child of block.subCalls) {
+    const found = findCall(child, callId)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
 function materialFor(s: ConversationSnapshot, callId: string): CallMaterial | null {
   for (const node of s.nodes) {
-    if (node.kind === 'tool-result' && node.callId === callId) return settledMaterial(node, callId)
+    if (node.kind !== 'tool-result') continue
+    const found = findCall(node, callId)
+    if (found !== undefined) {
+      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
+    }
   }
-  const open = s.runningCalls.find(c => c.callId === callId)
-  if (open !== undefined) return runningMaterial(open)
-  // run_code sub-dispatches: the native call-block shapes, so a selected
-  // sub-row resolves through the same material as a native call — the
-  // settled ToolResultNode form, or the RunningToolCall form mid-flight.
-  for (const subs of s.codeDispatches.values()) {
-    for (const sub of subs) {
-      if (sub.callId !== callId) continue
-      return 'kind' in sub ? settledMaterial(sub, callId) : runningMaterial(sub)
+  for (const root of s.runningCalls) {
+    const found = findCall(root, callId)
+    if (found !== undefined) {
+      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
     }
   }
   return null
diff --git a/packages/client/ui-conversation/tests/chat-stats.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
index cdb0ffa8c9..78fbf43c5e 100644
--- a/packages/client/ui-conversation/tests/chat-stats.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
@@ -42,7 +42,7 @@ const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessage
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -86,7 +86,7 @@ describe('deriveStats', () => {
   it('ignores tool results with no call time', () => {
     const tool: ToolResultNode = {
       kind: 'tool-result', seq: 5, time: 5_000, callId: 'c', call: null, callTime: null, content: [],
-      isError: false, callView: null, resultView: null,
+      isError: false, callView: null, resultView: null, subCalls: [],
     }
     const stats = deriveStats([tool, assistant(1, 1)])
     expect(stats.steps).toBe(1)
@@ -104,7 +104,7 @@ describe('deriveStats', () => {
     }
     const tool: ToolResultNode = {
       kind: 'tool-result', seq: 5, time: 7_000, callId: 'c', call: null, callTime: 4_000, content: [],
-      isError: false, callView: null, resultView: null,
+      isError: false, callView: null, resultView: null, subCalls: [],
     }
     const stats = deriveStats([timed, untimed, tool])
     expect(stats.llmMs).toBe(2_500)
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index c828eeaeb8..38d643292e 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -37,7 +37,7 @@ const SID = 's1' as SessionId
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -88,10 +88,10 @@ const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode
   kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 const runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
-  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null,
+  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null, subCalls: [],
 })
 const command = (over: Partial<CommandNode> = {}): CommandNode => ({
   kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index eacd2a754a..a89f724dd4 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -47,7 +47,7 @@ function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotPr
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -126,18 +126,28 @@ describe('render branch tails', () => {
     expect(view.getByText('该调用不在当前窗口内')).toBeTruthy()
   })
 
-  it('DetailsPanel resolves a run_code sub-callId to its full logged args and output', () => {
+  it('DetailsPanel resolves a nested run_code leaf to its full logged args and output', () => {
     localStorage.clear()
     const snap = snapshotBase()
     const longText = 'x'.repeat(1_000)
-    snap.codeDispatches = new Map([['p1', [{
+    snap.runningCalls = [{
+      callId: 'p1', name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
+      time: 7_000, callView: null, subCalls: [{
       kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
-      call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+      call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
       callTime: 8_000,
-      content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
-    }]]])
+      content: [], isError: false, callView: null, resultView: null,
+      subCalls: [{
+        kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
+        call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+        callTime: 8_500,
+        content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
+        subCalls: [],
+      }],
+    }],
+    }]
     const chat = createChatStore().create()
-    chat.actions.select({ turnSeq: 8, callId: 'p1:code:1', toolName: 'read' } satisfies SelectionTarget)
+    chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
     const emptyList = createSnapshotStore<SessionListState>(
       { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined })
     const emptyWorkspaces = createSnapshotStore<WorkspaceListState>({
@@ -168,7 +178,7 @@ describe('render branch tails', () => {
     expect(view.getByTestId('tool-details-seat')).toBeTruthy()
     expect(owners).toHaveLength(1)
     expect(owners[0]?.block).toMatchObject({
-      callId: 'p1:code:1',
+      callId: 'p1:code:1:code:1',
       call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
       content: [{ type: 'text', text: longText }],
     })
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index bc276174a3..47791a6090 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -35,7 +35,7 @@ const SID = 's1' as SessionId
 
 function snapshotOf(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index be385d41d5..f197528a2b 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -26,7 +26,7 @@ const SID = 's1' as SessionId
 /** Standard-props InputBar mount over a real shell (the composer-bar entry shape). */
 function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled?: boolean }) {
   const session = createSnapshotStore<ConversationSnapshot>({
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: over?.running ?? false, composerPhase: 'active',
     removed: over?.disabled ?? false, openState: 'open', openError: null, hasMore: false,
     loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index 58acf3a863..c47b726b66 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -112,7 +112,7 @@ async function scopedBench(register?: (slash: SlashService) => void) {
   actx.on('slash/input-consume-token', req => shell.consumeToken(req.guard) ? true : undefined)
   const wiring = shell
   const sessionStore = createSnapshotStore<ConversationSnapshot>({
-    sessionId, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
index 8c04651e77..826abaf846 100644
--- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx
+++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
@@ -32,7 +32,7 @@ function row(id: string, text: string | null, preview = text ?? '[image]'): Queu
 
 function snapshotWith(queue: QueuedMessage[]): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue, running: true, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index ea35284ad8..70b6d96710 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -70,7 +70,7 @@ const workspaceState = (items: readonly WorkspaceView[]): WorkspaceListState =>
 
 function conversationSnapshot(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 845e6099c8..8a7514d644 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -37,7 +37,7 @@ const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode
   kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
   ...toolResult(seq, callId, 'write'),
diff --git a/packages/client/ui-skill/tests/skill-row.spec.tsx b/packages/client/ui-skill/tests/skill-row.spec.tsx
index 05b84ceda5..431055101c 100644
--- a/packages/client/ui-skill/tests/skill-row.spec.tsx
+++ b/packages/client/ui-skill/tests/skill-row.spec.tsx
@@ -28,13 +28,14 @@ function settled(over: Partial<ToolResultNode> = {}): ToolResultNode {
     isError: false,
     callView: null,
     resultView: null,
+    subCalls: [],
     ...over,
   }
 }
 
 function running(argsRaw = '{"name":"dsh-manage-issues"}'): RunningToolCall {
   return {
-    callId: 'call-skill', name: 'skill', argsRaw, turn: 1, step: 1, time: 2_000, callView: null,
+    callId: 'call-skill', name: 'skill', argsRaw, turn: 1, step: 1, time: 2_000, callView: null, subCalls: [],
   }
 }
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 79a4eef640..5407a43717 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/ui-tool/README.md
-README.md: bf6213ebfacd8f7963463b2c443524c631c28bcd
-README.zh.md: 06a46a525eead005375bcf67794a1ceecde678bc
+README.md: bab3f92e4f6780b041cee2e682cb8ece3386ef15
+README.zh.md: 9187510fa354ba072835271d4b1153c8ee1105c0
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index bf6213ebfa..bab3f92e4f 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -4,11 +4,11 @@ English | [中文](README.zh.md)
 
 Client Tool presentation plugin. `ui-conversation` supplies one ordered root call through `conversation.chat.tool`; this package renders that root and its Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
 
-Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and `codeDispatches`; the conversation view remains authoritative for ChatFlow placement.
+Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and recursive `subCalls` projection; the conversation view remains authoritative for ChatFlow placement.
 
 ## Rendering contract
 
-`ToolCallTree` receives one root `ToolCallBlock`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. Through its standard session slot props it selects the Runtime-projected `codeDispatches[rootCallId]` array, then sends the root and every child through the same atomic dispatch path. The Runtime currently exposes only one Code Dispatch child level, so the renderer preserves that shape instead of inventing recursive data.
+`ToolCallTree` receives one root `ToolCallBlock` that already contains recursive `subCalls`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. It recursively walks the standard call blocks and sends the root and children at every depth through the same atomic dispatch path, without subscribing to a separate parent-to-children map.
 
 Each root and child wrapper preserves the `conversation.chat.tool` call-anchor DOM contract used for paging and selection.
 
@@ -44,6 +44,5 @@ None. The package is client-only presentation.
 
 ## Known Limitations and Deferred Work
 
-- The Runtime currently exposes one level of Code Dispatch children. The renderer sends roots and children through the same atomic path, but it does not claim an arbitrary recursive wire topology.
 - Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
 - Tool copy temporarily reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 06a46a525e..9187510fa3 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -4,11 +4,11 @@
 
 Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
 
-业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和 `codeDispatches`；conversation view 继续负责 ChatFlow 位置。
+业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
 
 ## 渲染契约
 
-`ToolCallTree` 接收一个 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，再让 root 与每个 child 经过同一条原子分发路径。Runtime 当前只暴露一层 Code Dispatch child，因此 renderer 保留该形状，不自行发明递归数据。
+`ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
 
 每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
 
@@ -44,6 +44,5 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
-- Runtime 当前只暴露一层 Code Dispatch 子调用。renderer 会让 root 和 child 经过同一个原子分发路径，但不宣称 wire 拓扑已经支持任意递归。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index 3c71e2f4d4..278be7dacf 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -1,12 +1,12 @@
 /** Root/subcall Tool composition with one keyed atomic dispatch path. */
 import { memo, useMemo, type ReactNode } from 'react'
-import type { CodeSubCall, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolCallOwnerProps, ToolTreeProps } from '../contract/slots.ts'
 import { GenericToolCard } from './toolviews/GenericToolCard.tsx'
 import css from './ToolCallTree.module.css'
 
-/** Resolve a Code Dispatch child's wire Tool name from either lifecycle form. */
-function subCallName(node: CodeSubCall): string {
+/** Resolve a Tool call's wire name from either lifecycle form. */
+function callName(node: ToolCallBlock): string {
   return 'kind' in node ? node.call?.name ?? '' : node.name
 }
 
@@ -44,40 +44,33 @@ const ToolCall = memo(function ToolCall({
   )
 })
 
-/**
- * Render one root Tool call and its currently supported one-level Code
- * Dispatch children. Root and children use the same atomic keyed dispatch.
- * @param props - whole-Tool owner data and the Tool-owned child-slot share.
- * @returns the Tool call tree.
- */
-export function ToolCallTree({
-  useSession, renderSlot, callId, toolName, block, selectedCallId, cwd, openFile, inspectCall, t,
-}: ToolTreeProps) {
-  const subCalls = useSession(snapshot => snapshot.codeDispatches.get(callId))
+const ToolCallBranch = memo(function ToolCallBranch({
+  renderSlot, block, selectedCallId, cwd, openFile, inspectCall, t,
+}: Pick<ToolTreeProps, 'renderSlot' | 'selectedCallId' | 'cwd' | 'openFile' | 'inspectCall' | 't'> & {
+  block: ToolCallBlock
+}) {
   return (
     <ToolCall
       renderSlot={renderSlot}
-      callId={callId}
-      toolName={toolName}
+      callId={block.callId}
+      toolName={callName(block)}
       block={block}
       openFile={openFile}
-      selected={callId === selectedCallId}
+      selected={block.callId === selectedCallId}
       cwd={cwd}
       inspectCall={inspectCall}
       t={t}
     >
-      {subCalls !== undefined && subCalls.length > 0 ? (
+      {block.subCalls.length > 0 ? (
         <div className={css.subCalls} data-subcalls>
-          {subCalls.map(node => (
-            <ToolCall
-              key={node.callId}
+          {block.subCalls.map(child => (
+            <ToolCallBranch
+              key={child.callId}
               renderSlot={renderSlot}
-              callId={node.callId}
-              toolName={subCallName(node)}
-              block={node}
-              openFile={openFile}
-              selected={node.callId === selectedCallId}
+              block={child}
+              selectedCallId={selectedCallId}
               cwd={cwd}
+              openFile={openFile}
               inspectCall={inspectCall}
               t={t}
             />
@@ -86,4 +79,26 @@ export function ToolCallTree({
       ) : null}
     </ToolCall>
   )
+})
+
+/**
+ * Render one root Tool call and its recursive children through the same
+ * atomic keyed dispatch.
+ * @param props - whole-Tool owner data and the Tool-owned child-slot share.
+ * @returns the Tool call tree.
+ */
+export function ToolCallTree({
+  renderSlot, block, selectedCallId, cwd, openFile, inspectCall, t,
+}: ToolTreeProps) {
+  return (
+    <ToolCallBranch
+      renderSlot={renderSlot}
+      block={block}
+      selectedCallId={selectedCallId}
+      cwd={cwd}
+      openFile={openFile}
+      inspectCall={inspectCall}
+      t={t}
+    />
+  )
 }
diff --git a/packages/client/ui-tool/tests/ask-question-row.spec.tsx b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
index f3ab8fd3fd..e6b91823c5 100644
--- a/packages/client/ui-tool/tests/ask-question-row.spec.tsx
+++ b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
@@ -24,11 +24,11 @@ const resultNode = (argsRaw: string, resultText: string | null, over?: Partial<T
   kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
   call: { name: 'ask_user_question', argsRaw },
   content: resultText === null ? [] : [{ type: 'text', text: resultText }],
-  isError: false, callView: null, resultView: null, ...over,
+  isError: false, callView: null, resultView: null, subCalls: [], ...over,
 })
 
 const runningCall = (argsRaw: string) =>
-  ({ callId: 'c1', name: 'ask_user_question', argsRaw, turn: 1, step: 1, time: 1_000, callView: null })
+  ({ callId: 'c1', name: 'ask_user_question', argsRaw, turn: 1, step: 1, time: 1_000, callView: null, subCalls: [] })
 
 // Standard locale seat stub mirroring the real ns → common → key chain.
 const t = makeTranslate(zh, commonZh)
diff --git a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
index dd733ba323..9cbdfe3f1d 100644
--- a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
@@ -40,7 +40,7 @@ const todoResult = (seq: number): ToolResultNode => ({
   kind: 'tool-result', seq, time: seq * 1_000, callId: `todo-${seq}`,
   call: { name: 'todo_write', argsRaw: JSON.stringify({ todos: TODOS }) },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 
 const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -50,6 +50,7 @@ const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>)
   content: [{ type: 'text', text: 'total 2\ndemo.txt\n' }], isError: false,
   callView: { card: 'terminal', title: 'ls -la', description: 'List files' },
   resultView: { card: 'terminal', output: 'total 2\ndemo.txt\n', exitCode: 0 },
+  subCalls: [],
   ...over,
 })
 
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 8a1df2fd7b..2bc97425e2 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -13,8 +13,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  CodeSubCall, ConversationSnapshot, RunningToolCall, SessionId, SessionListState,
-  ToolResultNode, WorkspaceListState,
+  ConversationSnapshot, RunningToolCall, SessionId, SessionListState,
+  ToolCallBlock, ToolResultNode, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
@@ -48,27 +48,33 @@ const codeResult = (seq: number, callId: string): ToolResultNode => ({
   call: { name: 'run_code', argsRaw: RUN_CODE_ARGS },
   callTime: seq * 1_000 - 500,
   content: [{ type: 'text', text: 'demo.txt' }], isError: false, callView: null, resultView: null,
+  subCalls: [],
 })
 
 const runningCode = (callId: string): RunningToolCall => ({
   callId, name: 'run_code', argsRaw: RUN_CODE_ARGS, turn: 9, step: 0, time: 9_000, callView: null,
+  subCalls: [],
 })
 
-const subCall = (seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false): CodeSubCall => ({
+const subCall = (seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false): ToolCallBlock => ({
   kind: 'tool-result', seq, time: seq * 1_000,
   callId: `${parent}:code:${n}`,
   call: { name, argsRaw: JSON.stringify(args) },
   callTime: seq * 1_000,
   content: [{ type: 'text', text: resultText }], isError, callView: null, resultView: null,
+  subCalls: [],
 })
 
 function snapshotWith(
   nodes: ToolResultNode[],
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>,
+  subCalls: readonly ToolCallBlock[],
   runningCalls: RunningToolCall[] = [],
 ): ConversationSnapshot {
+  const nestedNodes = nodes.map(node => ({ ...node, subCalls }))
+  const nestedRunningCalls = runningCalls.map(call => ({ ...call, subCalls }))
   return {
-    sessionId: SID, nodes, turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls, codeDispatches,
+    sessionId: SID, nodes: nestedNodes, turnTimings: new Map(), turnEnds: new Map(), partial: null,
+    runningCalls: nestedRunningCalls,
     pending: [], queue: [], running: runningCalls.length > 0, composerPhase: 'active', removed: false,
     openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
@@ -165,11 +171,11 @@ function mountApp(slots: SlotsService) {
 describe('run_code sub-calls through the real chat machinery', () => {
   it('renders the code-variant parent row with the description summary and nested sub-rows', async () => {
     const parent = 'call-64'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
       subCall(12, parent, 2, 'mystery', { n: 1 }, 'ok'),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
 
     // Parent row: the code variant with the model-authored description.
@@ -193,12 +199,12 @@ describe('run_code sub-calls through the real chat machinery', () => {
   it('renders Cordis sub-calls with lifecycle titles over the generic variants', async () => {
     const parent = 'call-cordis'
     const code = 'return { name: "audit", apply(ctx) {} }'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'cordis_inspect', { what: 'temporary' }, '## Temporary Plugins'),
       subCall(12, parent, 2, 'cordis_mount', { code }, 'Temporary Plugin dyn-2 is running'),
       subCall(13, parent, 3, 'cordis_unmount', { id: 'dyn-2' }, 'Temporary Plugin dyn-2 was unmounted and removed.'),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
     const nest = view.container.querySelector('[data-subcalls]')!
 
@@ -214,7 +220,7 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('expanding the code row reveals the program body verbatim (shiki-tokenized)', async () => {
     const parent = 'call-64'
-    const b = await bench(snapshotWith([codeResult(10, parent)], new Map()))
+    const b = await bench(snapshotWith([codeResult(10, parent)], []))
     const view = mountApp(b.slots)
     // The code row is expandable via the whole summary row (body = the program).
     const toggle = view.container.querySelector('[data-variant="code"] [data-expandable]')
@@ -230,10 +236,10 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('an isError sub-call renders the error state dot exactly like a failed native row', async () => {
     const parent = 'call-64'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'mystery', { n: 1 }, 'Error: boom', true),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
     const nested = view.container.querySelector('[data-subcalls] [data-variant][data-state="error"]')
     expect(nested).not.toBeNull()
@@ -241,11 +247,11 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('a file sub-row click opens the host path; bash sub-rows do not open details', async () => {
     const parent = 'call-64'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'read', { path: 'notes/demo.txt' }, 'ok'),
       subCall(12, parent, 2, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
     view.getByText('notes/demo.txt').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
@@ -258,10 +264,10 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('a RUNNING run_code call nests its so-far dispatches under the spinner row', async () => {
     const parent = 'call-live'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(21, parent, 1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
-    ]]])
-    const b = await bench(snapshotWith([], dispatches, [runningCode(parent)]))
+    ]
+    const b = await bench(snapshotWith([], subCalls, [runningCode(parent)]))
     const view = mountApp(b.slots)
     const running = view.container.querySelector('[data-variant="code"][data-state="running"]')
     expect(running).not.toBeNull()
@@ -272,12 +278,11 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('a started-but-unsettled sub-call renders the running state exactly like a native in-flight row', async () => {
     const parent = 'call-live'
-    const runningSub: CodeSubCall = {
+    const runningSub: ToolCallBlock = {
       callId: `${parent}:code:1`, name: 'grep', argsRaw: '{"pattern":"todo"}',
-      turn: 0, step: 0, time: 21_000, callView: null,
+      turn: 0, step: 0, time: 21_000, callView: null, subCalls: [],
     }
-    const dispatches = new Map([[parent, [runningSub]]])
-    const b = await bench(snapshotWith([], dispatches, [runningCode(parent)]))
+    const b = await bench(snapshotWith([], [runningSub], [runningCode(parent)]))
     const view = mountApp(b.slots)
     // The nested row derives 'running' from the RunningToolCall shape — the
     // same data-state chrome (row sweep) a native in-flight row wears.
@@ -291,9 +296,9 @@ describe('run_code sub-calls through the real chat machinery', () => {
       kind: 'tool-result', seq: 10, time: 10_000, callId: parent,
       call: { name: 'mystery', argsRaw: '{"n":1}' },
       callTime: 9_500,
-      content: [], isError: false, callView: null, resultView: null,
+      content: [], isError: false, callView: null, resultView: null, subCalls: [],
     }
-    const b = await bench(snapshotWith([plain], new Map()))
+    const b = await bench(snapshotWith([plain], []))
     const view = mountApp(b.slots)
     expect(view.container.querySelector('[data-subcalls]')).toBeNull()
   })
diff --git a/packages/client/ui-tool/tests/coverage-tails.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
index 024f97ce76..ab1a0a9632 100644
--- a/packages/client/ui-tool/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
@@ -57,7 +57,7 @@ describe('Tool presentation tails', () => {
       kind: 'tool-result', seq: 2, time: 2_000, callId: 'c5',
       call: { name: 'todo_write', argsRaw: '{"note":"x"}' },
       callTime: 1_000,
-      content: [], isError: false, callView: null, resultView: null,
+      content: [], isError: false, callView: null, resultView: null, subCalls: [],
     }
     const props: GenericToolCardProps = {
       callId: 'c5', toolName: 'todo_write', block: settled, openFile: vi.fn(), t,
@@ -72,7 +72,7 @@ describe('Tool presentation tails', () => {
       kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1',
       call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' },
       callTime: 2_000,
-      content: [], isError: false, callView: null, resultView: null,
+      content: [], isError: false, callView: null, resultView: null, subCalls: [],
     }
     const view = render(<BashRow {...bashProps(settled)} />)
     const row = view.container.querySelector('[data-sample="bash"]')!
@@ -84,13 +84,13 @@ describe('Tool presentation tails', () => {
   it('BashRow carries data-state for running and StateDots for error/stopped', () => {
     const running: RunningToolCall = {
       callId: 'c1', name: 'bash', argsRaw: '{"command":"ls","description":"List"}',
-      turn: 1, step: 1, time: 1_000, callView: null,
+      turn: 1, step: 1, time: 1_000, callView: null, subCalls: [],
     }
     const errorResult: ToolResultNode = {
       kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
       call: { name: 'bash', argsRaw: '{"command":"boom"}' },
       callTime: 500,
-      content: [], isError: true, callView: null, resultView: null,
+      content: [], isError: true, callView: null, resultView: null, subCalls: [],
     }
     const stoppedResult: ToolResultNode = {
       ...errorResult,
diff --git a/packages/client/ui-tool/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
index a0dee040c1..7713bedaec 100644
--- a/packages/client/ui-tool/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -48,7 +48,7 @@ const resultDiff = (over?: Partial<Extract<ToolResultView, { card: 'diff' }>>):
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'edit', argsRaw: ARGS,
-  turn: 1, step: 1, time: 1_000, callView: callDiff(), ...over,
+  turn: 1, step: 1, time: 1_000, callView: callDiff(), subCalls: [], ...over,
 })
 
 const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -56,7 +56,7 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'edit', argsRaw: ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'The file notes/demo.txt has been updated successfully.' }], isError: false,
-  callView: callDiff(), resultView: resultDiff(), ...over,
+  callView: callDiff(), resultView: resultDiff(), subCalls: [], ...over,
 })
 
 describe('diffCardModel', () => {
@@ -343,7 +343,7 @@ describe('DetailsPanel diff Output section', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
index 826bd72892..739a787a03 100644
--- a/packages/client/ui-tool/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -59,7 +59,7 @@ const resultRead = (over?: Partial<Extract<ToolResultView, { card: 'read' }>>):
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'read', argsRaw: ARGS,
-  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, ...over,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, subCalls: [], ...over,
 })
 
 const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -67,7 +67,7 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'read', argsRaw: ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: '41: export const a = 1' }], isError: false,
-  callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, resultView: resultRead(), ...over,
+  callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, resultView: resultRead(), subCalls: [], ...over,
 })
 
 describe('readCardModel', () => {
@@ -289,7 +289,7 @@ describe('DetailsPanel Output section (read)', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
index 72e25ac32b..51cab2d440 100644
--- a/packages/client/ui-tool/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -65,7 +65,7 @@ const resultPaths = (over?: Partial<Extract<ToolResultView, { card: 'search'; sh
 
 const runningGrep = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'grep', argsRaw: GREP_ARGS,
-  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, ...over,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, subCalls: [], ...over,
 })
 
 const settledGrep = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -73,7 +73,7 @@ const settledGrep = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'grep', argsRaw: GREP_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'a.ts\n  Line 12: const foo = 1' }], isError: false,
-  callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, resultView: resultMatches(), ...over,
+  callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, resultView: resultMatches(), subCalls: [], ...over,
 })
 
 const settledGlob = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -81,7 +81,7 @@ const settledGlob = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'glob', argsRaw: GLOB_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'src/a.ts\nsrc/b.ts' }], isError: false,
-  callView: { card: 'generic', title: 'Glob **/*.ts', kind: 'search' }, resultView: resultPaths(), ...over,
+  callView: { card: 'generic', title: 'Glob **/*.ts', kind: 'search' }, resultView: resultPaths(), subCalls: [], ...over,
 })
 
 describe('searchCardModel', () => {
@@ -405,7 +405,7 @@ describe('DetailsPanel Output section (search)', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
index 93a538c5c0..c9e2875a34 100644
--- a/packages/client/ui-tool/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -58,7 +58,7 @@ const resultTerminal = (over?: Partial<Extract<ToolResultView, { card: 'terminal
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'bash', argsRaw: ARGS,
-  turn: 1, step: 1, time: 1_000, callView: callTerminal(), ...over,
+  turn: 1, step: 1, time: 1_000, callView: callTerminal(), subCalls: [], ...over,
 })
 
 const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -66,7 +66,7 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'bash', argsRaw: ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'a.ts  b.ts\nc.ts  d.ts\n' }], isError: false,
-  callView: callTerminal(), resultView: resultTerminal(), ...over,
+  callView: callTerminal(), resultView: resultTerminal(), subCalls: [], ...over,
 })
 
 describe('terminalCardModel', () => {
@@ -480,7 +480,7 @@ describe('DetailsPanel Output section', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
@@ -568,15 +568,17 @@ describe('DetailsPanel Output section', () => {
   // pins the resolution path with views injected directly, and the arm below
   // pins what the shipped path actually shows today.
   it('a run_code sub-dispatch resolves to its own terminal card once views reach it', () => {
+    const child = settled({ callId: 'c1' })
     const view = mount(snapshot({
-      codeDispatches: new Map([['p1', [settled({ callId: 'c1' })]]]),
+      runningCalls: [running({ callId: 'p1', subCalls: [child] })],
     }), target)
     expect(view.getByText('a.ts  b.ts', RAW)).toBeTruthy()
   })
 
   it('a sub-dispatch as the wire actually delivers it (no views) keeps the flattened form', () => {
+    const child = settled({ callId: 'c1', callView: null, resultView: null })
     const view = mount(snapshot({
-      codeDispatches: new Map([['p1', [settled({ callId: 'c1', callView: null, resultView: null })]]]),
+      runningCalls: [running({ callId: 'p1', subCalls: [child] })],
     }), target)
     // No terminal card: the generic path renders the result text in the Output
     // section's <pre> (the Input section has its own, hence the scoping).
@@ -588,7 +590,10 @@ describe('DetailsPanel Output section', () => {
   it('a running run_code sub-dispatch resolves through the running material', () => {
     const view = mount(snapshot({
       // The leading non-matching sub-call exercises the scan's skip.
-      codeDispatches: new Map([['p1', [running({ callId: 'other' }), running()]]]),
+      runningCalls: [running({
+        callId: 'p1',
+        subCalls: [running({ callId: 'other' }), running()],
+      })],
     }), target)
     expect(view.getByText('ls -la')).toBeTruthy()
   })
diff --git a/packages/client/ui-tool/tests/todo-row.spec.tsx b/packages/client/ui-tool/tests/todo-row.spec.tsx
index ef3253a947..db720ed056 100644
--- a/packages/client/ui-tool/tests/todo-row.spec.tsx
+++ b/packages/client/ui-tool/tests/todo-row.spec.tsx
@@ -61,7 +61,7 @@ describe('planSummary', () => {
 const resultNode = (argsRaw: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
   kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
   call: { name: 'todo_write', argsRaw },
-  content: [], isError: false, callView: null, resultView: null, ...over,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [], ...over,
 })
 
 function rowProps(block: unknown): TodoRowProps {
@@ -106,7 +106,7 @@ describe('TodoRow', () => {
 
   it('keeps non-ok execution states visible through the shared row states', () => {
     const args = JSON.stringify({ todos: LIST })
-    const running = render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
+    const running = render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null, subCalls: [] })} />)
     expect(running.container.querySelector('[data-state="running"]')).not.toBeNull()
     expect(running.container.querySelector('[data-state="running"] svg')).not.toBeNull()
     running.unmount()
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index c8c31ad365..393b9f8f46 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -2,7 +2,7 @@
 /** ToolCallTree-owned root/subcall markers and selection projection. */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
-import type { CodeSubCall, ConversationSnapshot, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationSnapshot, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { ToolTreeProps } from '../src/client/contract/slots.ts'
@@ -15,15 +15,14 @@ const t: ToolTreeProps['t'] = makeTranslate(zh, commonZh)
 
 const root = (callId: string, call: ToolResultNode['call']): ToolResultNode => ({
   kind: 'tool-result', seq: 3, time: 3_000, callId, call, callTime: 2_000,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 
 function props(
   block: ToolResultNode,
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]> = new Map(),
   selectedCallId?: string,
 ): ToolTreeProps {
-  const snapshot = { codeDispatches } as ConversationSnapshot
+  const snapshot = {} as ConversationSnapshot
   const useSession = ((selector: (value: ConversationSnapshot) => unknown) => selector(snapshot)) as ToolTreeProps['useSession']
   const renderSlot = ((_key: string, _owner: object, options?: { fallback?: React.ReactNode }) =>
     options?.fallback ?? null) as unknown as ToolTreeProps['renderSlot']
@@ -43,7 +42,7 @@ function props(
 describe('ToolCallTree', () => {
   it('owns the root marker, generic fallback, and selected state for a window-truncated call', () => {
     const block = root('w1', null)
-    const view = render(<ToolCallTree {...props(block, new Map(), 'w1')} />)
+    const view = render(<ToolCallTree {...props(block, 'w1')} />)
     const row = view.container.querySelector('[data-chat-call-id="w1"]')
     expect(row?.getAttribute('data-chat-anchor-key')).toBe('call:w1')
     expect(row?.getAttribute('data-selected')).toBe('true')
@@ -51,15 +50,23 @@ describe('ToolCallTree', () => {
     expect(view.getByText('w1')).toBeTruthy()
   })
 
-  it('marks a selected subcall without selecting its root', () => {
-    const block = root('parent', { name: 'run_code', argsRaw: '{"code":"return 1"}' })
-    const child: CodeSubCall = root('parent:code:1', { name: 'read', argsRaw: '{"path":"a.ts"}' })
-    const view = render(
-      <ToolCallTree {...props(block, new Map([['parent', [child]]]), child.callId)} />,
-    )
-    expect(view.container.querySelector('[data-subcalls]')?.parentElement)
-      .toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
+  it('recursively renders a selected leaf without selecting its ancestors', () => {
+    const leaf = root('parent:code:1:code:1', { name: 'read', argsRaw: '{"path":"a.ts"}' })
+    const child = {
+      ...root('parent:code:1', { name: 'run_code', argsRaw: '{"code":"return 1"}' }),
+      subCalls: [leaf],
+    }
+    const block = {
+      ...root('parent', { name: 'run_code', argsRaw: '{"code":"return 1"}' }),
+      subCalls: [child],
+    }
+    const view = render(<ToolCallTree {...props(block, leaf.callId)} />)
+    const nests = view.container.querySelectorAll('[data-subcalls]')
+    expect(nests[0]?.parentElement).toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
+    expect(nests[1]?.parentElement).toBe(view.container.querySelector('[data-chat-call-id="parent:code:1"]'))
     expect(view.container.querySelector('[data-chat-call-id="parent"]')?.hasAttribute('data-selected')).toBe(false)
-    expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.getAttribute('data-selected')).toBe('true')
+    expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.hasAttribute('data-selected')).toBe(false)
+    expect(view.container.querySelector('[data-chat-call-id="parent:code:1:code:1"]')?.getAttribute('data-selected')).toBe('true')
+    expect(nests).toHaveLength(2)
   })
 })
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index 02189e3634..9fed8e3720 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -20,14 +20,14 @@ const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}',
-  turn: 1, step: 1, time: 1_000, callView: null, ...over,
+  turn: 1, step: 1, time: 1_000, callView: null, subCalls: [], ...over,
 })
 
 const result = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
   call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' },
   callTime: 1_000,
-  content: [], isError: false, callView: null, resultView: null, ...over,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [], ...over,
 })
 
 describe('tool-call-model', () => {
diff --git a/packages/client/ui-tool/tests/toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
index 846f81cc45..e96c460576 100644
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -42,7 +42,7 @@ const toolResult = (seq: number, callId: string, name: string, args = '{"command
   kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: args },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 
 /** Test-owned AppFrame role: declares and renders the resident conversation area. */
diff --git a/packages/client/ui-tool/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
index b8a5a4e06c..7856ae9d6f 100644
--- a/packages/client/ui-tool/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -56,7 +56,7 @@ const resultFetch = (over?: Partial<Extract<ToolResultView, { card: 'web'; kind:
 
 const runningSearch = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'web_search', argsRaw: SEARCH_ARGS,
-  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Search', kind: 'search' }, ...over,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Search', kind: 'search' }, subCalls: [], ...over,
 })
 
 const settledSearch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -64,7 +64,7 @@ const settledSearch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'web_search', argsRaw: SEARCH_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'search text' }], isError: false,
-  callView: { card: 'generic', title: 'Search', kind: 'search' }, resultView: resultSearch(), ...over,
+  callView: { card: 'generic', title: 'Search', kind: 'search' }, resultView: resultSearch(), subCalls: [], ...over,
 })
 
 const settledFetch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -72,7 +72,7 @@ const settledFetch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'web_fetch', argsRaw: FETCH_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'fetch body' }], isError: false,
-  callView: { card: 'generic', title: 'Fetch', kind: 'fetch' }, resultView: resultFetch(), ...over,
+  callView: { card: 'generic', title: 'Fetch', kind: 'fetch' }, resultView: resultFetch(), subCalls: [], ...over,
 })
 
 describe('webCardModel', () => {
@@ -235,7 +235,7 @@ describe('DetailsPanel web Output section', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
index 81b4f9d7f0..ff63b860b9 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
+++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
@@ -211,7 +211,6 @@ export function TrajectoryView({
   const nodes = inspection.eventNodes
   const partial = inspection.partial
   const runningCalls = inspection.runningCalls
-  const codeDispatches = inspection.codeDispatches
   const loadHistoryTailRef = useRef(loadHistoryTail)
   loadHistoryTailRef.current = loadHistoryTail
   const historyControllerRef = useRef<AbortController | null>(null)
@@ -366,12 +365,11 @@ export function TrajectoryView({
       runningCalls,
       requests: selectedRequests,
       callSchemas,
-      codeDispatches,
     })
     return { turns, lastIndex: lastCellIndex(turns) }
   }, [
     selectedNodes, partialTurn, partialStep,
-    runningCalls, selectedRequests, callSchemas, codeDispatches,
+    runningCalls, selectedRequests, callSchemas,
   ])
   const timelinePartialSignature = partialStructureSignature(partial)
   const timelinePartial = useMemo<ConversationSnapshot['partial']>(() => partial === null
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
index 273b4fc32a..6853199aa1 100644
--- a/packages/client/ui-trajectory/src/client/layout.ts
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -5,11 +5,11 @@
 import type {
   AssistantBlock,
   AssistantMessageNode,
-  CodeSubCall,
   ConversationSnapshot,
   RequestInspectionSnapshot,
   RequestPromptChange,
   RequestView,
+  ToolCallBlock,
   ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { extractMarkdownPlainText } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -39,8 +39,6 @@ export interface TrajectoryLayoutInput {
   runningCalls: ConversationSnapshot['runningCalls']
   requests?: readonly RequestView[]
   callSchemas?: RequestInspectionSnapshot['callSchemas']
-  /** run_code sub-dispatches by parent callId (sub-cells nest under the parent Tool cell). */
-  codeDispatches: ConversationSnapshot['codeDispatches']
 }
 
 interface UsageLike {
@@ -57,6 +55,7 @@ interface LaidCell {
   absTime: number | null
   toolName?: string
   callId?: string
+  subCalls?: readonly ToolCallBlock[]
 }
 
 interface LaidGroup {
@@ -131,9 +130,11 @@ function inputCellDetail(node: InputNode): Pick<
  */
 export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly TrajectoryTurnModel[] {
   const {
-    nodes, partial, runningCalls, requests = [], callSchemas, codeDispatches,
+    nodes, partial, runningCalls, requests = [], callSchemas,
   } = input
   const resultByCall = indexResults(nodes)
+  const callById = new Map<string, ToolCallBlock>(resultByCall)
+  for (const call of runningCalls) callById.set(call.callId, call)
   const emittedCallIds = indexAssistantCallIds(nodes)
   const callStartById = new Map<string, number>()
   for (const result of resultByCall.values()) {
@@ -344,8 +345,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
     }
     if (node.kind === 'assistant') {
       const laidList = withSubCalls(
-        expandAssistant(node, index + 1, prevAbsTime, resultByCall, callStartById),
-        codeDispatches,
+        expandAssistant(node, index + 1, prevAbsTime, resultByCall, callStartById, callById),
       )
       if (node.step > 0) pushStep(node.turn, node.step, laidList)
       else for (const laid of laidList) pushMessage(node.turn, laid)
@@ -381,6 +381,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
           absTime: finiteTime(node.callTime ?? node.time),
           ...(toolName !== undefined ? { toolName } : {}),
           callId: node.callId,
+          subCalls: node.subCalls,
           cell: {
             index: ++index,
             kind: 'tool',
@@ -398,7 +399,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
             startedAt: finiteTime(node.callTime),
           },
         }]
-        for (const laid of expandSubCalls(codeDispatches.get(node.callId), index)) {
+        for (const laid of expandSubCalls(node.subCalls, index)) {
           laidList.push(laid)
           index = laid.cell.index
         }
@@ -413,14 +414,15 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
       kind: 'assistant', seq: Number.MAX_SAFE_INTEGER, time: 0,
       turn: partial.turn, step: partial.step, blocks: partial.blocks,
     }
-    const laidList = expandAssistant(
+    const laidList = withSubCalls(expandAssistant(
       fake,
       index + 1,
       prevAbsTime,
       resultByCall,
       callStartById,
+      callById,
       { streaming: true },
-    )
+    ))
     if (partial.step > 0) pushStep(partial.turn, partial.step, laidList)
     else for (const laid of laidList) pushMessage(partial.turn, laid)
     const last = laidList[laidList.length - 1]
@@ -434,6 +436,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
       absTime: null,
       toolName: call.name,
       callId: call.callId,
+      subCalls: call.subCalls,
       cell: {
         index: ++index,
         kind: 'tool',
@@ -444,7 +447,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
         startedAt: finiteTime(call.time),
       },
     }]
-    for (const laid of expandSubCalls(codeDispatches.get(call.callId), index)) {
+    for (const laid of expandSubCalls(call.subCalls, index)) {
       laidList.push(laid)
       index = laid.cell.index
     }
@@ -491,7 +494,6 @@ export function appendTrajectoryPartialLayout(
     nodes: [],
     partial,
     runningCalls: [],
-    codeDispatches: new Map(),
   }).at(0)
   if (partialTurn === undefined) return turns
   const streamed: TrajectoryTurnModel = {
@@ -622,6 +624,7 @@ function expandAssistant(
   prevAbsTime: number | null,
   results: Map<string, ToolResultNode>,
   callStarts: ReadonlyMap<string, number>,
+  calls: ReadonlyMap<string, ToolCallBlock>,
   opts?: { streaming?: boolean },
 ): LaidCell[] {
   if (opts?.streaming === true && node.blocks.length === 0) return []
@@ -677,10 +680,12 @@ function expandAssistant(
       ? null
       : durationSeconds(result.time, result.callTime)
     const callAbs = finiteTime(callStarts.get(block.callId))
+    const call = calls.get(block.callId)
     out.push({
       absTime: callAbs,
       toolName: block.name,
       callId: block.callId,
+      ...(call === undefined ? {} : { subCalls: call.subCalls }),
       cell: {
         index: ++index, kind: 'tool',
         text: summarizeCall(block.name, block.argsRaw),
@@ -883,15 +888,14 @@ function collectCallIds(
 
 
 
-/** Interleave each tool cell's run_code sub-dispatch cells right after it, reindexing followers. */
-function withSubCalls(laidList: LaidCell[], codeDispatches: ConversationSnapshot['codeDispatches']): LaidCell[] {
-  if (codeDispatches.size === 0) return laidList
+/** Interleave each tool cell's nested child calls right after it, reindexing followers. */
+function withSubCalls(laidList: LaidCell[]): LaidCell[] {
+  if (!laidList.some(laid => laid.subCalls !== undefined && laid.subCalls.length > 0)) return laidList
   const out: LaidCell[] = []
   let index = laidList[0] !== undefined ? laidList[0].cell.index - 1 : 0
   for (const laid of laidList) {
     out.push({ ...laid, cell: { ...laid.cell, index: ++index } })
-    if (laid.callId === undefined) continue
-    for (const sub of expandSubCalls(codeDispatches.get(laid.callId), index)) {
+    for (const sub of expandSubCalls(laid.subCalls, index)) {
       out.push(sub)
       index = sub.cell.index
     }
@@ -901,7 +905,7 @@ function withSubCalls(laidList: LaidCell[], codeDispatches: ConversationSnapshot
 
 /** Sub-dispatch cells for one run_code parent, in start order (running = null duration). */
 function expandSubCalls(
-  subs: readonly CodeSubCall[] | undefined,
+  subs: readonly ToolCallBlock[] | undefined,
   startIndex: number,
 ): LaidCell[] {
   if (subs === undefined || subs.length === 0) return []
@@ -909,10 +913,11 @@ function expandSubCalls(
   let index = startIndex
   for (const sub of subs) {
     const settled = 'kind' in sub
-    out.push({
+    const laid: LaidCell = {
       absTime: settled ? finiteTime(sub.callTime ?? sub.time) : finiteTime(sub.time),
       toolName: settled ? sub.call?.name ?? sub.callId : sub.name,
       callId: sub.callId,
+      subCalls: sub.subCalls,
       cell: {
         index: ++index,
         kind: 'subtool',
@@ -938,7 +943,12 @@ function expandSubCalls(
           ? finiteTime(sub.callTime)
           : finiteTime(sub.time),
       },
-    })
+    }
+    out.push(laid)
+    for (const child of expandSubCalls(sub.subCalls, index)) {
+      out.push(child)
+      index = child.cell.index
+    }
   }
   return out
 }
diff --git a/packages/client/ui-trajectory/tests/layout.spec.tsx b/packages/client/ui-trajectory/tests/layout.spec.tsx
index 544199e345..4c49b07907 100644
--- a/packages/client/ui-trajectory/tests/layout.spec.tsx
+++ b/packages/client/ui-trajectory/tests/layout.spec.tsx
@@ -74,7 +74,7 @@ describe('deriveTrajectoryLayout', () => {
         content: [{ type: 'text', text: 'a.txt' }], isError: false, callView: null, resultView: null,
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     expect(turns).toHaveLength(1)
     expect(turns[0]?.turn).toBe(1)
     const kinds = turns[0]?.groups.flatMap(g => g.cells.map(c => c.kind))
@@ -90,12 +90,11 @@ describe('deriveTrajectoryLayout', () => {
 
   it('adds runningCalls not already present and leaves their time blank', () => {
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes: [],
       partial: null,
       runningCalls: [{
         callId: 'r1', name: 'bash', argsRaw: '{"command":"pwd"}',
-        turn: 1, step: 2, time: 9_000, callView: null,
+        turn: 1, step: 2, time: 9_000, callView: null, subCalls: [],
       }],
     })
     expect(turns[0]?.groups.map(g => g.title)).toEqual(['Step 2'])
@@ -119,7 +118,6 @@ describe('deriveTrajectoryLayout', () => {
       startedAt: 3_000, completedAt: null, status: 'running',
     } as unknown as RequestView
     const base = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes,
       partial: { ...partial, blocks: [] },
       requests: [request],
@@ -152,12 +150,11 @@ describe('deriveTrajectoryLayout', () => {
       }],
     }
     const base = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes: [],
       partial: { ...partial, blocks: [] },
       runningCalls: [{
         callId: 'c1', name: 'bash', argsRaw: '{"command":"pwd"}',
-        turn: 1, step: 1, time: 9_000, callView: null,
+        turn: 1, step: 1, time: 9_000, callView: null, subCalls: [],
       }],
     })
 
@@ -180,7 +177,7 @@ describe('deriveTrajectoryLayout', () => {
         usage: { inputTokens: 1, outputTokens: 2, reasoningTokens: 3 },
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     const cells = turns[0]?.groups.flatMap(g => g.cells) ?? []
     expect(cells.find(c => c.kind === 'message')?.timeSeconds).toBeNull()
     expect(turns[0]?.groups.find(g => g.title === 'Step 1')?.description).toBeUndefined()
@@ -206,7 +203,7 @@ describe('deriveTrajectoryLayout', () => {
         content: [], isError: false, callView: null, resultView: null,
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     expect(turns[0]?.groups[0]?.description).toBe('3,000 ms bash×2')
   })
 
@@ -223,7 +220,7 @@ describe('deriveTrajectoryLayout', () => {
         blocks: [{ kind: 'text', text: 'ok2' }],
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     expect(turns.map(t => t.turn)).toEqual([1, 2])
     expect(turns[0]?.groups.flatMap(g => g.cells.map(c => c.text))).toEqual(['first', 'ok1'])
     expect(turns[1]?.groups.flatMap(g => g.cells.map(c => c.text))).toEqual(['second', 'ok2'])
@@ -254,7 +251,6 @@ describe('deriveTrajectoryLayout', () => {
     }
 
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes,
       partial: null,
       runningCalls: [],
@@ -280,7 +276,7 @@ describe('deriveTrajectoryLayout', () => {
         usage: { inputTokens: 11, outputTokens: 22, reasoningTokens: 3 },
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     const message = turns[0]?.groups.flatMap(g => g.cells).find(c => c.kind === 'message')
     expect(message).toMatchObject({
       text: '…', input: 11, output: 22, think: 3,
@@ -295,7 +291,7 @@ describe('deriveTrajectoryLayout', () => {
     }] as unknown as ConversationSnapshot['nodes']
 
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(), nodes, partial: null, runningCalls: [],
+      nodes, partial: null, runningCalls: [],
     })
     const message = turns[0]?.groups.flatMap(group => group.cells)
       .find(cell => cell.kind === 'message')
@@ -333,7 +329,7 @@ describe('deriveTrajectoryLayout', () => {
         blocks: [{ kind: 'text', text: 'done' }],
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     const cells = turns[0]?.groups.flatMap(g => g.cells) ?? []
     const message = cells.find(c => c.kind === 'message' && c.text === 'done')
     // From the compaction marker at 9.5s, not from context at 9s or the earlier surfaces.
@@ -352,7 +348,7 @@ describe('deriveTrajectoryLayout', () => {
       },
     ] as unknown as ConversationSnapshot['nodes']
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(), nodes, partial: null, runningCalls: [],
+      nodes, partial: null, runningCalls: [],
     })
     const message = turns[0]?.groups.flatMap(group => group.cells)
       .find(cell => cell.kind === 'message')
@@ -372,6 +368,7 @@ describe('run_code sub-dispatch cells', () => {
       kind: 'tool-result', seq: 3, time: 9_000, callId: 'p1',
       call: { name: 'run_code', argsRaw: '{"code":"…","description":"批量读取"}' }, callTime: 6_200,
       content: [{ type: 'text', text: 'done' }], isError: false, callView: null, resultView: null,
+      subCalls: [],
     },
   ] as unknown as ConversationSnapshot['nodes']
 
@@ -380,14 +377,18 @@ describe('run_code sub-dispatch cells', () => {
     callId: `p1:code:${n}`,
     call: { name, argsRaw: '{"x":1}' }, callTime: start,
     content: [{ type: 'text' as const, text: 'ok' }], isError: false, callView: null, resultView: null,
+    subCalls: [],
   })
 
+  const withSubCalls = (subCalls: readonly ReturnType<typeof settledSub>[] | readonly object[]) =>
+    runCodeNodes.map(node => node.kind === 'tool-result' ? { ...node, subCalls } : node) as ConversationSnapshot['nodes']
+
   it('nests settled sub-cells after their parent Tool cell with real durations', () => {
-    const codeDispatches = new Map([['p1', [
+    const subCalls = [
       settledSub(1, 'bash', 6_300, 7_300),
       settledSub(2, 'read', 7_300, 7_800),
-    ]]]) as unknown as ConversationSnapshot['codeDispatches']
-    const turns = deriveTrajectoryLayout({ codeDispatches, nodes: runCodeNodes, partial: null, runningCalls: [] })
+    ]
+    const turns = deriveTrajectoryLayout({ nodes: withSubCalls(subCalls), partial: null, runningCalls: [] })
     const cells = turns[0]!.groups.flatMap(g => g.cells)
     expect(cells.map(c => c.kind)).toEqual(['message', 'tool', 'subtool', 'subtool'])
     expect(cells[0]?.text).toBe('Tool call only')
@@ -400,11 +401,29 @@ describe('run_code sub-dispatch cells', () => {
   it('a running (unsettled) sub-call renders a subtool cell with blank time', () => {
     const running = {
       callId: 'p1:code:1', name: 'grep', argsRaw: '{"pattern":"x"}',
-      turn: 0, step: 0, time: 6_400, callView: null,
+      turn: 0, step: 0, time: 6_400, callView: null, subCalls: [],
     }
-    const codeDispatches = new Map([['p1', [running]]]) as unknown as ConversationSnapshot['codeDispatches']
-    const turns = deriveTrajectoryLayout({ codeDispatches, nodes: runCodeNodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes: withSubCalls([running]), partial: null, runningCalls: [] })
     const sub = turns[0]!.groups.flatMap(g => g.cells).find(c => c.kind === 'subtool')
     expect(sub).toMatchObject({ text: 'grep · {"pattern":"x"}', timeSeconds: null })
   })
+
+  it('recursively flattens nested child calls immediately after their parent', () => {
+    const leaf = {
+      ...settledSub(2, 'read', 7_300, 7_800),
+      callId: 'p1:code:1:code:1',
+    }
+    const child = {
+      ...settledSub(1, 'run_code', 6_300, 8_000),
+      subCalls: [leaf],
+    }
+    const turns = deriveTrajectoryLayout({ nodes: withSubCalls([child]), partial: null, runningCalls: [] })
+    const cells = turns[0]!.groups.flatMap(group => group.cells)
+    expect(cells.map(cell => cell.kind)).toEqual(['message', 'tool', 'subtool', 'subtool'])
+    expect(cells.slice(2).map(cell => cell.callId)).toEqual([
+      'p1:code:1',
+      'p1:code:1:code:1',
+    ])
+    expect(cells.map(cell => cell.index)).toEqual([1, 2, 3, 4])
+  })
 })
diff --git a/packages/client/ui-trajectory/tests/views.spec.tsx b/packages/client/ui-trajectory/tests/views.spec.tsx
index 56a9ee90cf..2a0ec68ec0 100644
--- a/packages/client/ui-trajectory/tests/views.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.spec.tsx
@@ -82,7 +82,6 @@ function historySnapshot(
       interruptedNodes: [],
       partial: null,
       runningCalls: [],
-      codeDispatches: new Map(),
       ...inspection,
     },
   }
@@ -115,7 +114,7 @@ function standaloneDuration(): Pick<
 function fakeSession(nodes: ConversationSnapshot['nodes']) {
   const store = createSnapshotStore({
     nodes, pending: [], partial: null,
-    runningCalls: [] as ConversationSnapshot['runningCalls'], codeDispatches: new Map(),
+    runningCalls: [] as ConversationSnapshot['runningCalls'],
   })
   return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession<ConversationSnapshot> }
 }
@@ -186,7 +185,7 @@ function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES
     running: false, removed: false, promptError: null, nodes,
     pending: [],
     openState: 'open' as const, hasMore: true, loadingOlder: false,
-    partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'], codeDispatches: new Map(),
+    partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'],
   })
   const useSession = bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>
   const chat = createChatStore().create()

From 091b9931984581278e2b8f28547dd912026b68cd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:46:50 +0800
Subject: [PATCH 009/262] fix(client): harden nested Tool call projection

---
 ...7-19-gui-web-client-architecture.i18n.yaml |  4 +-
 .../2026-07-19-gui-web-client-architecture.md |  2 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  2 +-
 ...7-26-code-mode-chat-subcall-rows.i18n.yaml |  4 +-
 .../2026-07-26-code-mode-chat-subcall-rows.md | 10 +--
 ...26-07-26-code-mode-chat-subcall-rows.zh.md | 10 +--
 ...code-mode-live-parallel-dispatch.i18n.yaml |  4 +-
 ...-07-26-code-mode-live-parallel-dispatch.md |  2 +-
 ...-26-code-mode-live-parallel-dispatch.zh.md |  2 +-
 .../src/client/sessions/tool-call-tree.ts     | 43 +++++++-----
 .../client/runtime/tests/history-fold.spec.ts | 31 +++++++++
 .../runtime/tests/tool-call-tree.spec.ts      | 65 +++++++++++++++++++
 .../tests/gate-branch-tails.spec.tsx          | 22 +++----
 packages/client/ui-tool/README.i18n.yaml      |  4 +-
 packages/client/ui-tool/README.md             |  1 +
 packages/client/ui-tool/README.zh.md          |  1 +
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  4 +-
 .../client/ui-trajectory/src/client/layout.ts |  1 -
 18 files changed, 160 insertions(+), 52 deletions(-)
 create mode 100644 packages/client/runtime/tests/tool-call-tree.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 2357aa30f2..d3bbc7da9d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: cba029ea74e89b277f9079ebb3765deeeb105b47
-2026-07-19-gui-web-client-architecture.zh.md: f700cc04fe1479d43957456c14b3abb4014d99c5
+2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
+2026-07-19-gui-web-client-architecture.zh.md: cf31220aad61e4845f7fe90b73bf5da4432e53de
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index cba029ea74..e25d002b92 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat without interpreting Tool names or Code Dispatch topology; ui-tool selects `codeDispatches[rootCallId]` from the Runtime snapshot, renders that root/child shape, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
+There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: Runtime projects Code Dispatch topology into each root's recursive `subCalls`; ui-conversation places that ordered root into the single `'conversation.chat.tool'` seat without interpreting Tool names or topology; ui-tool renders the supplied tree and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index f700cc04fe..cf31220aad 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,7 +44,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或 Code Dispatch 拓扑；ui-tool 从 Runtime snapshot 选择 `codeDispatches[rootCallId]`、渲染 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
index d550ad1fb6..390144b4bd 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.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 .agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
-2026-07-26-code-mode-chat-subcall-rows.md: dc09e8fda9dbfb156b6218dec67584ee7bfead75
-2026-07-26-code-mode-chat-subcall-rows.zh.md: d445ddac4704fb940550d27ef7400e79d859393b
+2026-07-26-code-mode-chat-subcall-rows.md: 40b4b8fd8c5cea8e9aea01731d7eceff692db188
+2026-07-26-code-mode-chat-subcall-rows.zh.md: 9981fded054f663dd539660ed2a2eca68a9d3138
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
index dc09e8fda9..40b4b8fd8c 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
@@ -12,12 +12,12 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 
 ## Decision
 
-**Sub-calls are `ToolResultNode`s indexed off the surface flow, rendered through the same keyed slot as native rows, nested always-visible under their parent.**
+**Sub-calls are standard Tool call blocks attached recursively to their parent outside the surface flow, rendered through the same keyed slot as native rows, and always visible under their parent.**
 
-- **Data layer**: `Session.applyEventSideEffects` folds each in-window `tool/code-dispatch` into `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`, where `CodeSubCall` IS `ToolResultNode` (the sub-call id as `callId`, the logged args JSON-stringified into `call.argsRaw`, the full logged `content`/`isError`). Live mux frames and history replay build the identical index (`rebuildDerivedFromWindow` clears and re-derives; copy-on-write per-parent arrays keep snapshot references memo-stable). Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The event is narrowed structurally at the wire-consumer boundary (dsh-tools' host types cannot enter the client program — the host/client `Context` merges collide), the same posture as every cross-wire payload.
-- **Render layer**: `ChatView` passes each parent and its indexed children through the whole-Tool `'conversation.chat.tool'` seat. ui-tool's `ToolCallTree` renders the parent followed by a `[data-subcalls]` nest, and every atomic call dispatches through the same `'tool.call.toolview'` keyed slot with `entryKey = Tool name` and the same `GenericToolCard` fallback. A keyed registration therefore takes over child and top-level calls without registration changes. Running parents (`runningCalls`) receive their accumulated dispatches through the same owner payload, so child rows stream in during the run.
+- **Data layer**: Runtime's `ToolCallTree` folds in-window `tool/code-dispatch-start` and `tool/code-dispatch` events into a private per-parent index, then projects running and settled children onto recursive `ToolCallBlock.subCalls`. Live Session projection and `projectConversationHistory` share that fold; copy-on-write parent arrays and path-copy projection keep unrelated roots and siblings reference-stable. Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The events are narrowed structurally at the wire-consumer boundary, which also rejects cyclic parent relationships (dsh-tools' host types cannot enter the client program because the host/client `Context` merges collide).
+- **Render layer**: `ChatView` passes each parent with its recursive children through the whole-Tool `'conversation.chat.tool'` seat. ui-tool's `ToolCallTree` renders the parent followed by `[data-subcalls]` nests, and every atomic call dispatches through the same `'tool.call.toolview'` keyed slot with `entryKey = Tool name` and the same `GenericToolCard` fallback. A keyed registration therefore takes over descendant and top-level calls without registration changes. Running parents (`runningCalls`) receive accumulated dispatches in the same recursive block, so child rows stream in during the run.
 - **`run_code` presentation**: a new `code` row variant (classifier `run_code → code`, `Code` title, `IconCodeOutline16`) summarizes with the model-authored `description` and expands to the program itself (monospace on the markdown code-block fill) rather than the args JSON envelope.
-- **Details panel**: `materialFor` falls through nodes → runningCalls → the dispatch index, so a selected sub-callId resolves to full args and complete output through the identical rendering path as a native settled call.
+- **Details panel**: `materialFor` recursively searches `nodes` and `runningCalls`, so a selected descendant callId resolves to full args and complete output through the identical rendering path as a native settled call.
 
 ## Alternatives considered
 
@@ -29,4 +29,4 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 
 ## Consequences
 
-Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership tests both levels). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom suites pin the slot dispatch, error states, details resolution, and index reference stability.
+Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership searches the whole tree). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom and Runtime suites pin slot dispatch, error states, recursive details resolution, history projection, and reference-stable path copying.
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
index d445ddac47..9981fded05 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
@@ -12,12 +12,12 @@ Status: implemented
 
 ## 决策
 
-**子调用在界面流之外单独索引为 `ToolResultNode`，经由与原生行相同的 keyed slot 渲染，以始终可见的方式嵌套在父行之下。**
+**子调用是在 surface 流之外递归附着到父级的标准 Tool 调用块，经由与原生行相同的 keyed slot 渲染，并始终显示在父级之下。**
 
-- **数据层**：`Session.applyEventSideEffects` 把窗口内的每条 `tool/code-dispatch` 折入 `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`，其中 `CodeSubCall` 本身就是 `ToolResultNode`（子调用 id 充当 `callId`，已记录的参数经 JSON 字符串化写入 `call.argsRaw`，完整记录的 `content`/`isError` 原样携带）。实时多路复用帧与历史回放构建出同一份索引（`rebuildDerivedFromWindow` 先清空再重新推导；逐父级的写时复制（copy-on-write）数组保持快照引用稳定，便于 memo 化）。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。该事件在 wire 消费方边界作结构性收窄（dsh-tools 的宿主类型无法进入客户端程序——宿主端/客户端两侧的 `Context` 声明合并会冲突），姿态与所有跨 wire 载荷一致。
-- **渲染层**：`ChatView` 通过整体 Tool seat `'conversation.chat.tool'` 传递每个 parent 及其已索引的 child。ui-tool 的 `ToolCallTree` 先渲染 parent，再渲染一组 `[data-subcalls]` 嵌套；每个原子调用都通过同一个 `'tool.call.toolview'` keyed slot，以 Tool 名称作为 `entryKey`，并共用 `GenericToolCard` fallback。一个 keyed 注册因此无需变化即可同时接管 child 与顶层调用。运行中的 parent（`runningCalls`）通过同一 owner 载荷接收已累积的 dispatch，使 child 行在运行期间实时流入。
+- **数据层**：运行时的 `ToolCallTree` 把窗口内的 `tool/code-dispatch-start` 与 `tool/code-dispatch` 事件折入私有的逐父级索引，再把运行中和已结算的子级投影到递归的 `ToolCallBlock.subCalls` 上。实时 Session 投影与 `projectConversationHistory` 共享这一折叠过程；逐父级的写时复制数组和路径复制投影让无关 root 与 sibling 保持引用稳定。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。这些事件在 wire 消费方边界作结构性收窄，该边界也会拒绝成环的父子关系（dsh-tools 的宿主类型无法进入客户端程序，因为宿主端与客户端两侧的 `Context` 声明合并会冲突）。
+- **渲染层**：`ChatView` 通过整体 Tool seat `'conversation.chat.tool'` 传递每个 parent 及其递归 child。ui-tool 的 `ToolCallTree` 先渲染 parent，再渲染 `[data-subcalls]` 嵌套；每个原子调用都通过同一个 `'tool.call.toolview'` keyed slot，以 Tool 名称作为 `entryKey`，并共用 `GenericToolCard` fallback。一个 keyed 注册因此无需变化即可同时接管任意后代与顶层调用。运行中的 parent（`runningCalls`）在同一个递归块中接收已累积的 dispatch，使 child 行在运行期间实时流入。
 - **`run_code` 的呈现**：新增一种 `code` 行变体（分类器映射 `run_code → code`、标题 `Code`、图标 `IconCodeOutline16`），以模型撰写的 `description` 作摘要，展开后显示程序本身（在 markdown 代码块的填充底色上以等宽字体呈现），而非参数的 JSON 封装。
-- **详情面板**：`materialFor` 按 nodes → runningCalls → 分发索引的顺序逐级回落，因此被选中的子调用 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。
+- **详情面板**：`materialFor` 递归搜索 `nodes` 与 `runningCalls`，因此被选中的后代 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。
 
 ## 曾考虑的替代方案
 
@@ -29,4 +29,4 @@ Status: implemented
 
 ## 后果
 
-自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属判断会同时检验两个层级）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 测试套件则锁定 slot 分发、错误状态、详情解析与索引引用稳定性。
+自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属会搜索整棵树）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 与运行时测试套件则锁定 slot 分发、错误状态、递归详情解析、历史投影与引用稳定的路径复制。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
index 2d3d73f65d..ed15fd5c36 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.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 .agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
-2026-07-26-code-mode-live-parallel-dispatch.md: b4afc21be902d8ed3e5bee2ad1a540413a864f25
-2026-07-26-code-mode-live-parallel-dispatch.zh.md: b6169e6d243163f8444ffc7b87b741ade7631198
+2026-07-26-code-mode-live-parallel-dispatch.md: e85d1f99f58f1aae28091cd8875ee87a6df5a1e7
+2026-07-26-code-mode-live-parallel-dispatch.zh.md: 39da98d9c3630d549f13df0ea555687614f3065a
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
index b4afc21be9..e85d1f99f5 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
@@ -16,7 +16,7 @@ Two gaps remained after the first two PRs. Sub-call rows appeared only when each
 
 - **Event pair**: `tool/code-dispatch-start` (parent/sub ids, name, normalized args) is appended when the scheduler actually starts a call — not at submission, so a queued call abandoned by run settlement logs nothing. The existing `tool/code-dispatch` settles the pair (same `subCallId`); every started call settles exactly once (aborts settle as `isError` outcomes through the pipeline). Timing = the two events' `time` fields. Both stay log-only; model context is untouched; format stays v0.
 - **Bridge scheduler**: submitted calls are classified at start time via `registry.executionMode` (the SAME fail-closed `isConcurrencySafe` contract the loop uses) and start strictly in submission order. One single-lane driver owns every ORDERED stage — the start append, `prepare` (pre-execute/guards), the head-of-line `finalize`/`finish` commit (post-execute + context deferral + settle append) — so ordered policy stages never overlap each other and only the around-dispatch/body stage runs concurrently, exactly the native loop's sequencing (`fillPool` awaits `startCall` then `commitReady`). Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (a `Config` field validated by the Loader schema AND re-validated at direct construction, default 10 — the loop scheduler's own default; `1` restores serial dispatch); an exclusive call drains the pool, runs alone, and holds its barrier until its COMMIT completes (post-execute included), like a native exclusive group. Run settlement aborts in-flight dispatches and abandons queued-unstarted ones (binding rejection, no events), then drains to quiescence — including a commit already mid-flight when the program returned — before the outer result closes the turn.
-- **Client**: `CodeSubCall` widens to `RunningToolCall | ToolResultNode` — a start event lands the running shape in the dispatch index (rows derive the running ring from the shape, exactly as for native in-flight calls), and its settle replaces the entry in place, preserving start order under parallel completion and carrying the start's `time` as `callTime` (duration source). A settle with no observed start (window cut mid-pair, or a pre-start-event log) appends directly, so old logs keep rendering.
+- **Client**: Runtime's `ToolCallTree` stores a start event as a `RunningToolCall` child and projects it through the parent's recursive `subCalls` (rows derive the running ring from that shape, exactly as for native in-flight calls). Its settle replaces the private-index entry in place, preserving start order under parallel completion and carrying the start's `time` as `callTime` (duration source). A settle with no observed start (window cut mid-pair, or a pre-start-event log) appends directly, so old logs keep rendering.
 - **SDK prompt**: the model-facing "calls execute sequentially" sentence is replaced with the true contract (independent safe calls may overlap under `Promise.all`; dependent work sequences with `await`) — a model-visible change, re-recorded across every code-mode snapshot.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
index b6169e6d24..39da98d9c3 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 - **事件对**：`tool/code-dispatch-start`（父/子 id、名称、规范化参数）在调度器真正启动某个调用时才追加，而非在提交时，因此因 run 结算而被放弃的排队调用不会留下任何日志。既有的 `tool/code-dispatch` 结算该事件对（`subCallId` 相同）；每个已启动的调用恰好结算一次（中止也会作为 `isError` 结果经由流水线结算）。计时即这两个事件的 `time` 字段。两个事件都保持仅日志；模型上下文不受影响；格式保持 v0。
 - **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同、故障时默认判为不安全的 `isConcurrencySafe` 契约），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单通道驱动器独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
-- **客户端侧**：`CodeSubCall` 拓宽为 `RunningToolCall | ToolResultNode`：start 事件把运行中形状写入分发索引（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致），其结算事件则原位替换该条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
+- **客户端侧**：运行时的 `ToolCallTree` 把 start 事件存为 `RunningToolCall` 子级，并通过父级递归的 `subCalls` 投影出来（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致）。其结算事件会原位替换私有索引中的条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
 - **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实契约（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 Code Mode 快照都已重新录制。
 
 ## 曾考虑的替代方案
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
index ef25ba3da2..574a10dd92 100644
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -10,9 +10,9 @@ interface ProjectedBlock {
   value: ToolCallBlock
 }
 
-function sameBlocks(
-  left: readonly ToolCallBlock[],
-  right: readonly ToolCallBlock[],
+function sameReferences<T>(
+  left: readonly T[],
+  right: readonly T[],
 ): boolean {
   return left.length === right.length
     && left.every((block, index) => block === right[index])
@@ -68,6 +68,7 @@ export class ToolCallTree {
         subCalls: [],
       }
       const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+      if (this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
       this.childrenByParent.set(data.parentCallId, [...siblings, running])
       this.revision++
       return true
@@ -83,6 +84,7 @@ export class ToolCallTree {
     }
     const siblings = this.childrenByParent.get(data.parentCallId) ?? []
     const at = siblings.findIndex(sub => sub.callId === data.subCallId)
+    if (at === -1 && this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
     const started = at === -1 ? undefined : siblings[at]
     const settled: ToolResultNode = {
       kind: 'tool-result',
@@ -116,14 +118,11 @@ export class ToolCallTree {
     if (this.nodesCache?.source === nodes && this.nodesCache.revision === this.revision) {
       return this.nodesCache.value
     }
-    let changed = false
     const projected = nodes.map((node): ConversationNode => {
       if (node.kind !== 'tool-result') return node
-      const value = this.projectBlock(node) as ToolResultNode
-      changed ||= value !== node
-      return value
+      return this.projectBlock(node) as ToolResultNode
     })
-    const value = changed ? projected : nodes
+    const value = sameReferences(nodes, projected) ? nodes : projected
     this.nodesCache = { source: nodes, revision: this.revision, value }
     return value
   }
@@ -137,13 +136,8 @@ export class ToolCallTree {
     if (this.runningCache?.source === calls && this.runningCache.revision === this.revision) {
       return this.runningCache.value
     }
-    let changed = false
-    const projected = calls.map((call): RunningToolCall => {
-      const value = this.projectBlock(call) as RunningToolCall
-      changed ||= value !== call
-      return value
-    })
-    const value = changed ? projected : calls
+    const projected = calls.map(call => this.projectBlock(call) as RunningToolCall)
+    const value = sameReferences(calls, projected) ? calls : projected
     this.runningCache = { source: calls, revision: this.revision, value }
     return value
   }
@@ -151,11 +145,11 @@ export class ToolCallTree {
   private projectBlock(block: ToolCallBlock): ToolCallBlock {
     const children = this.childrenByParent.get(block.callId) ?? block.subCalls
     const projectedChildren = children.map(child => this.projectBlock(child))
-    const childValue = sameBlocks(children, projectedChildren)
+    const childValue = sameReferences(children, projectedChildren)
       ? children
       : projectedChildren
     const cached = this.projectedByCall.get(block.callId)
-    if (cached?.source === block && sameBlocks(cached.children, childValue)) {
+    if (cached?.source === block && sameReferences(cached.children, childValue)) {
       return cached.value
     }
     const value: ToolCallBlock = block.subCalls === childValue
@@ -168,4 +162,19 @@ export class ToolCallTree {
     })
     return value
   }
+
+  private wouldCreateCycle(parentCallId: string, subCallId: string): boolean {
+    if (parentCallId === subCallId) return true
+    const pending = [subCallId]
+    const visited = new Set(pending)
+    for (const callId of pending) {
+      for (const child of this.childrenByParent.get(callId) ?? []) {
+        if (child.callId === parentCallId) return true
+        if (visited.has(child.callId)) continue
+        visited.add(child.callId)
+        pending.push(child.callId)
+      }
+    }
+    return false
+  }
 }
diff --git a/packages/client/runtime/tests/history-fold.spec.ts b/packages/client/runtime/tests/history-fold.spec.ts
index 083bdc3566..37a1060fec 100644
--- a/packages/client/runtime/tests/history-fold.spec.ts
+++ b/packages/client/runtime/tests/history-fold.spec.ts
@@ -168,6 +168,37 @@ describe('projectConversationHistory', () => {
     })
   })
 
+  it('projects nested dispatches onto settled and interrupted history calls', () => {
+    const projection = projectConversationHistory([
+      ev.turnStart(0, 1),
+      ev.toolCall(1, 1, 'settled', 'run_code', '{}'),
+      ev.codeDispatchStart(2, 'settled', 1, 'run_code', { code: 'nested' }),
+      ev.codeDispatchStart(3, 'settled:code:1', 1, 'read', { path: 'a.txt' }),
+      ev.codeDispatch(4, 'settled:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
+      ev.codeDispatch(5, 'settled', 1, 'run_code', { code: 'nested' }, 'alpha'),
+      ev.toolResult(6, 1, 'settled', 'done'),
+      ev.turnEnd(7, 1),
+      ev.turnStart(8, 2),
+      ev.toolCall(9, 2, 'interrupted', 'run_code', '{}'),
+      ev.codeDispatchStart(10, 'interrupted', 1, 'bash', { command: 'sleep 1' }),
+      ev.turnEnd(11, 2, 'aborted'),
+    ].map(event => ({ event })))
+
+    const settled = {
+      callId: 'settled',
+      subCalls: [{
+        callId: 'settled:code:1',
+        subCalls: [{ callId: 'settled:code:1:code:1', call: { name: 'read' } }],
+      }],
+    }
+    expect(projection.eventNodes).toMatchObject([settled])
+    expect(projection.contexts[0]?.nodes).toMatchObject([settled])
+    expect(projection.interruptedNodes).toMatchObject([{
+      callId: 'interrupted',
+      subCalls: [{ callId: 'interrupted:code:1', name: 'bash' }],
+    }])
+  })
+
   it('drops completed token payloads without changing inspection projections', () => {
     const events = [
       ev.user(0, 'before'),
diff --git a/packages/client/runtime/tests/tool-call-tree.spec.ts b/packages/client/runtime/tests/tool-call-tree.spec.ts
new file mode 100644
index 0000000000..56e7f96694
--- /dev/null
+++ b/packages/client/runtime/tests/tool-call-tree.spec.ts
@@ -0,0 +1,65 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { describe, expect, it } from 'vitest'
+import type { RunningToolCall } from '../src/client/sessions/conversation.ts'
+import { ToolCallTree } from '../src/client/sessions/tool-call-tree.ts'
+
+const at = (seq: number, type: string, data: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, type, data }) as unknown as SessionEvent
+
+const start = (seq: number, parentCallId: string, subCallId: string): SessionEvent =>
+  at(seq, 'tool/code-dispatch-start', {
+    parentCallId, subCallId, name: 'run_code', arguments: {},
+  })
+
+const settle = (seq: number, parentCallId: string, subCallId: string): SessionEvent =>
+  at(seq, 'tool/code-dispatch', {
+    parentCallId, subCallId, name: 'run_code', arguments: {},
+    isError: false, content: [],
+  })
+
+const root = (callId: string): RunningToolCall => ({
+  callId, name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
+  time: 1_700_000_000_000, callView: null, subCalls: [],
+})
+
+describe('ToolCallTree', () => {
+  it('rejects a self-parenting dispatch edge', () => {
+    const tree = new ToolCallTree()
+    const roots = [root('root')]
+
+    expect(tree.apply(start(0, 'root', 'root'))).toBe(true)
+    expect(tree.projectRunningCalls(roots)).toBe(roots)
+  })
+
+  it('rejects a settling edge that would close a multi-call cycle', () => {
+    const tree = new ToolCallTree()
+    tree.apply(start(0, 'a', 'b'))
+    tree.apply(start(1, 'b', 'c'))
+
+    expect(tree.apply(settle(2, 'c', 'a'))).toBe(true)
+    expect(tree.projectRunningCalls([root('a')])).toMatchObject([{
+      callId: 'a',
+      subCalls: [{
+        callId: 'b',
+        subCalls: [{ callId: 'c', subCalls: [] }],
+      }],
+    }])
+  })
+
+  it('accepts an acyclic graph with a shared descendant', () => {
+    const tree = new ToolCallTree()
+    tree.apply(start(0, 'a', 'b'))
+    tree.apply(start(1, 'a', 'c'))
+    tree.apply(start(2, 'b', 'd'))
+    tree.apply(start(3, 'c', 'd'))
+
+    expect(tree.apply(start(4, 'root', 'a'))).toBe(true)
+    expect(tree.projectRunningCalls([root('root')])).toMatchObject([{
+      callId: 'root',
+      subCalls: [{
+        callId: 'a',
+        subCalls: [{ callId: 'b' }, { callId: 'c' }],
+      }],
+    }])
+  })
+})
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index a89f724dd4..3afe471d50 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -133,18 +133,18 @@ describe('render branch tails', () => {
     snap.runningCalls = [{
       callId: 'p1', name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
       time: 7_000, callView: null, subCalls: [{
-      kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
-      call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
-      callTime: 8_000,
-      content: [], isError: false, callView: null, resultView: null,
-      subCalls: [{
-        kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
-        call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
-        callTime: 8_500,
-        content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
-        subCalls: [],
+        kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
+        call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
+        callTime: 8_000,
+        content: [], isError: false, callView: null, resultView: null,
+        subCalls: [{
+          kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
+          call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+          callTime: 8_500,
+          content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
+          subCalls: [],
+        }],
       }],
-    }],
     }]
     const chat = createChatStore().create()
     chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 5407a43717..97008e3e0c 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/ui-tool/README.md
-README.md: bab3f92e4f6780b041cee2e682cb8ece3386ef15
-README.zh.md: 9187510fa354ba072835271d4b1153c8ee1105c0
+README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
+README.zh.md: f4e8044fe6e10e1fbdfb70987efe07c884fa9ac8
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index bab3f92e4f..d6bc0f248c 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -44,5 +44,6 @@ None. The package is client-only presentation.
 
 ## Known Limitations and Deferred Work
 
+- The Host excludes `run_code` from Code Mode program bindings, so production events currently produce one dispatch level; the recursive Runtime/UI contract is ready for future nested producers.
 - Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
 - Tool copy temporarily reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 9187510fa3..f4e8044fe6 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -44,5 +44,6 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 契约已为未来的嵌套生产者做好准备。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 2bc97425e2..2f5efae420 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -56,7 +56,9 @@ const runningCode = (callId: string): RunningToolCall => ({
   subCalls: [],
 })
 
-const subCall = (seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false): ToolCallBlock => ({
+const subCall = (
+  seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false,
+): ToolCallBlock => ({
   kind: 'tool-result', seq, time: seq * 1_000,
   callId: `${parent}:code:${n}`,
   call: { name, argsRaw: JSON.stringify(args) },
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
index 6853199aa1..4e110a5888 100644
--- a/packages/client/ui-trajectory/src/client/layout.ts
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -917,7 +917,6 @@ function expandSubCalls(
       absTime: settled ? finiteTime(sub.callTime ?? sub.time) : finiteTime(sub.time),
       toolName: settled ? sub.call?.name ?? sub.callId : sub.name,
       callId: sub.callId,
-      subCalls: sub.subCalls,
       cell: {
         index: ++index,
         kind: 'subtool',

From 4de2de98e49517733a2fa57530ce2d73a8a649b5 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:15:34 +0800
Subject: [PATCH 010/262] fix(client): bound nested Tool call depth

---
 packages/client/runtime/README.i18n.yaml      |  4 +--
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../src/client/sessions/tool-call-tree.ts     | 36 +++++++++++++++++--
 .../runtime/tests/tool-call-tree.spec.ts      | 28 +++++++++++++--
 5 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index bb64a12d4e..1edac07d5e 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: fad0f6e4f948ebf412b2bd837a4f68e6dc805ec8
-README.zh.md: 4ede12a320082a5023ec121306650fce72a12663
+README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
+README.zh.md: 6eee14bdbe7a9fb86b0a12355e7d0a45cd500774
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index fad0f6e4f9..a9b6049745 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -46,7 +46,7 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr
 
 ## Code Mode child-call tree
 
-Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity. Wire or history edges that would introduce a cycle or exceed the fixed 256-call recursive-depth safety limit are consumed without mutating the tree, so the rest of the session remains renderable.
 
 ## Session title projection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 4ede12a320..6eee14bdbe 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -46,7 +46,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## Code Mode 子调用树
 
-每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。会引入环，或使递归深度超过 256 个调用这一固定安全上限的协议或历史记录边会被视为已消费，但不会修改树，因此会话其余部分仍可渲染。
 
 ## Session 标题投影
 
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
index 574a10dd92..fbc32e0cef 100644
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -10,6 +10,9 @@ interface ProjectedBlock {
   value: ToolCallBlock
 }
 
+/** Fixed wire-safety ceiling for every recursive Tool call consumer. */
+export const MAX_TOOL_CALL_TREE_DEPTH = 256
+
 function sameReferences<T>(
   left: readonly T[],
   right: readonly T[],
@@ -24,6 +27,7 @@ function sameReferences<T>(
  */
 export class ToolCallTree {
   private readonly childrenByParent = new Map<string, readonly ToolCallBlock[]>()
+  private readonly depthByCall = new Map<string, number>()
   private readonly projectedByCall = new Map<string, ProjectedBlock>()
   private revision = 0
   private nodesCache: {
@@ -40,6 +44,7 @@ export class ToolCallTree {
   /** Forget all event-derived child calls before replaying a new window. */
   reset(): void {
     this.childrenByParent.clear()
+    this.depthByCall.clear()
     this.projectedByCall.clear()
     this.revision++
   }
@@ -68,7 +73,7 @@ export class ToolCallTree {
         subCalls: [],
       }
       const siblings = this.childrenByParent.get(data.parentCallId) ?? []
-      if (this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
+      if (!this.acceptEdge(data.parentCallId, data.subCallId)) return true
       this.childrenByParent.set(data.parentCallId, [...siblings, running])
       this.revision++
       return true
@@ -84,7 +89,7 @@ export class ToolCallTree {
     }
     const siblings = this.childrenByParent.get(data.parentCallId) ?? []
     const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-    if (at === -1 && this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
+    if (at === -1 && !this.acceptEdge(data.parentCallId, data.subCallId)) return true
     const started = at === -1 ? undefined : siblings[at]
     const settled: ToolResultNode = {
       kind: 'tool-result',
@@ -163,6 +168,33 @@ export class ToolCallTree {
     return value
   }
 
+  /**
+   * Accept an edge only when every recursive consumer can traverse it safely.
+   * Host-minted ids exclude cycles and current bindings emit one level; a
+   * malformed wire/history edge is consumed without hiding the rest of the session.
+   */
+  private acceptEdge(parentCallId: string, subCallId: string): boolean {
+    if (this.wouldCreateCycle(parentCallId, subCallId)) return false
+    const pending = [{
+      callId: subCallId,
+      depth: (this.depthByCall.get(parentCallId) ?? 1) + 1,
+    }]
+    const updates = new Map<string, number>()
+    for (const candidate of pending) {
+      const knownDepth = updates.get(candidate.callId)
+        ?? this.depthByCall.get(candidate.callId)
+        ?? 1
+      if (candidate.depth <= knownDepth) continue
+      if (candidate.depth > MAX_TOOL_CALL_TREE_DEPTH) return false
+      updates.set(candidate.callId, candidate.depth)
+      for (const child of this.childrenByParent.get(candidate.callId) ?? []) {
+        pending.push({ callId: child.callId, depth: candidate.depth + 1 })
+      }
+    }
+    for (const [callId, depth] of updates) this.depthByCall.set(callId, depth)
+    return true
+  }
+
   private wouldCreateCycle(parentCallId: string, subCallId: string): boolean {
     if (parentCallId === subCallId) return true
     const pending = [subCallId]
diff --git a/packages/client/runtime/tests/tool-call-tree.spec.ts b/packages/client/runtime/tests/tool-call-tree.spec.ts
index 56e7f96694..541e6b2e19 100644
--- a/packages/client/runtime/tests/tool-call-tree.spec.ts
+++ b/packages/client/runtime/tests/tool-call-tree.spec.ts
@@ -1,7 +1,9 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { describe, expect, it } from 'vitest'
-import type { RunningToolCall } from '../src/client/sessions/conversation.ts'
-import { ToolCallTree } from '../src/client/sessions/tool-call-tree.ts'
+import type { RunningToolCall, ToolCallBlock } from '../src/client/sessions/conversation.ts'
+import {
+  MAX_TOOL_CALL_TREE_DEPTH, ToolCallTree,
+} from '../src/client/sessions/tool-call-tree.ts'
 
 const at = (seq: number, type: string, data: Record<string, unknown>): SessionEvent =>
   ({ seq, time: 1_700_000_000_000 + seq, type, data }) as unknown as SessionEvent
@@ -62,4 +64,26 @@ describe('ToolCallTree', () => {
       }],
     }])
   })
+
+  it('rejects an edge beyond the recursive depth safety limit', () => {
+    const tree = new ToolCallTree()
+    for (let depth = 1; depth < MAX_TOOL_CALL_TREE_DEPTH; depth++) {
+      tree.apply(start(depth, `call-${depth - 1}`, `call-${depth}`))
+    }
+
+    expect(tree.apply(start(
+      MAX_TOOL_CALL_TREE_DEPTH,
+      `call-${MAX_TOOL_CALL_TREE_DEPTH - 1}`,
+      `call-${MAX_TOOL_CALL_TREE_DEPTH}`,
+    ))).toBe(true)
+
+    let current: ToolCallBlock = tree.projectRunningCalls([root('call-0')])[0]!
+    let depth = 1
+    while (current.subCalls.length > 0) {
+      current = current.subCalls[0]!
+      depth++
+    }
+    expect(depth).toBe(MAX_TOOL_CALL_TREE_DEPTH)
+    expect(current.callId).toBe(`call-${MAX_TOOL_CALL_TREE_DEPTH - 1}`)
+  })
 })

From 9b169f7555433ee762b39ab385072265e284aa64 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:37:32 +0800
Subject: [PATCH 011/262] ci: run required checks on native Windows

---
 .agents/notes/archived/manifest.json          |   3 +
 ...27-wine-windows-gates-experiment.i18n.yaml |   4 +-
 ...026-07-27-wine-windows-gates-experiment.md |   1 +
 ...-07-27-wine-windows-gates-experiment.zh.md |   1 +
 ...rial-cross-platform-ci-reference.i18n.yaml |   4 +-
 ...7-21-serial-cross-platform-ci-reference.md |   2 +-
 ...1-serial-cross-platform-ci-reference.zh.md |   2 +-
 ...ortable-required-pull-request-ci.i18n.yaml |   4 +-
 ...07-23-portable-required-pull-request-ci.md |   6 +-
 ...23-portable-required-pull-request-ci.zh.md |   6 +-
 ...n-setup-for-symmetric-ci-caching.i18n.yaml |   4 +-
 ...m-action-setup-for-symmetric-ci-caching.md |   4 +-
 ...ction-setup-for-symmetric-ci-caching.zh.md |   4 +-
 ...8-native-windows-pull-request-ci.i18n.yaml |   6 +
 ...26-08-08-native-windows-pull-request-ci.md |  33 +++
 ...08-08-native-windows-pull-request-ci.zh.md |  33 +++
 .github/AGENTS.md                             |   2 +-
 .github/workflows/ci.yml                      | 117 ++-------
 AGENTS.md                                     |   1 -
 package.json                                  |   1 -
 scripts/ci-workflow.spec.ts                   |  22 ++
 scripts/wine-windows-gates.sh                 | 247 ------------------
 22 files changed, 144 insertions(+), 363 deletions(-)
 rename .agents/notes/{implemented => archived}/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml (67%)
 rename .agents/notes/{implemented => archived}/process/2026-07-27-wine-windows-gates-experiment.md (99%)
 rename .agents/notes/{implemented => archived}/process/2026-07-27-wine-windows-gates-experiment.zh.md (99%)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
 delete mode 100755 scripts/wine-windows-gates.sh

diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index 1adde54c7b..638d87373d 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -298,6 +298,9 @@
     "process/2026-07-26-gui-pr-gif-evidence-and-assets-branch.i18n.yaml": "sha256:89b6dc255cb0dd9d97ae6f34f37d185412d4260d7bf2f87d6b25e340f01dc26e",
     "process/2026-07-26-gui-pr-gif-evidence-and-assets-branch.md": "sha256:1742e09435ade4a09349c8843eb381e870a2be2d51b74449f08260422c8096b3",
     "process/2026-07-26-gui-pr-gif-evidence-and-assets-branch.zh.md": "sha256:220bd53a88617b09ee8970627c46540fa8951724b102acfe296a7ed7d0f7b5fe",
+    "process/2026-07-27-wine-windows-gates-experiment.i18n.yaml": "sha256:6f4cbc12ee9cddbb297bf7e138ccabcd204f66898a0f7411b1633f03d5a9eab5",
+    "process/2026-07-27-wine-windows-gates-experiment.md": "sha256:8d37dcdab058098c7de3da1de00ce61bef92bbc8d6ee71add959474c6fb3e936",
+    "process/2026-07-27-wine-windows-gates-experiment.zh.md": "sha256:77fbf04df36af09e55007a93bd6b22d08ff99869efe8de3e97dac5b4701e0a9e",
     "simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.i18n.yaml": "sha256:ad3d1263cb0051b885173bf064de62065e2c646ccaae2d7250723da3b4eab90c",
     "simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md": "sha256:8fb061d51c8c23b47d2367814bab3623c6d5b972f38d207a273caa9030b579bd",
     "simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md": "sha256:2ffeaca91f82844a5616d6dcce6b4af514bb8a7c46f78e47f668b204ac6edc04",
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
similarity index 67%
rename from .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
rename to .agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index 19945a6580..f7995fd9cf 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.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 .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
-2026-07-27-wine-windows-gates-experiment.zh.md: b50739f5b63c5836248c94927037e38900abc84f
+2026-07-27-wine-windows-gates-experiment.md: ce2ad1ad4506f59083de5731677d052161849e3d
+2026-07-27-wine-windows-gates-experiment.zh.md: a0a5e8e7cce078adf2c961fe4d8cc50edc28355c
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
rename to .agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.md
index 1b01fe00dc..ce2ad1ad45 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+++ b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.md
@@ -1,6 +1,7 @@
 # Agent Note: Wine-run Windows blocking gates on Linux runners
 
 Status: implemented
+Archived: 2026-08-08
 
 English | [中文](2026-07-27-wine-windows-gates-experiment.zh.md)
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.zh.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
rename to .agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.zh.md
index b50739f5b6..a0a5e8e7cc 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 在 Linux runner 上用 Wine 运行 Windows 阻断门禁
 
 Status: implemented
+Archived: 2026-08-08
 
 [English](2026-07-27-wine-windows-gates-experiment.md) | 中文
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index a1c49fdcae..dcb6e18e88 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.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 .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
-2026-07-21-serial-cross-platform-ci-reference.md: 71b364f72a094f7899a0929eec29f3a16ccc8a93
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 4f5920ffc150ce16d5567ca05128f7524c2a2b21
+2026-07-21-serial-cross-platform-ci-reference.md: dfd762ad4d4eec61bc3a17d96865ccc4ac936ab3
+2026-07-21-serial-cross-platform-ci-reference.zh.md: 580340db2fbfc14458a4bbfbfa157db75e74e027
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index 71b364f72a..dfd762ad4d 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -28,7 +28,7 @@ The standalone [Sandbox](../../../../.github/workflows/sandbox.yml) workflow bel
 
 Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. The CI and Sandbox workflows keep their cross-platform references on master pushes. Performance is evaluated from completed hosted-job timestamps and reported as a measurement; it is not encoded as a `timeout-minutes` value.
 
-The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels; `serial / windows` is the one remaining native-Windows job, the complete-kernel oracle behind the Wine-hosted pull-request lane ([Wine lane decision](2026-07-27-wine-windows-gates-experiment.md)). Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
+The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. The required pull-request Windows job also runs on standard `windows-2025` under the [native Windows decision](2026-08-08-native-windows-pull-request-ci.md); when enabled, `serial / windows` remains a second complete, unsharded native-kernel oracle. Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 4f5920ffc1..580340db2f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -28,7 +28,7 @@ macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上
 
 master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。CI 与 Sandbox 工作流把跨平台参考流程保留在 master 推送上。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。
 
-可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签；`serial / windows` 是仅存的原生 Windows 作业，是 Wine 托管拉取请求通道背后的完整内核标尺（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)）。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
+可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。依据[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)，拉取请求必需的 Windows 作业也在标准 `windows-2025` 上运行；`serial / windows` 启用时，仍作为第二个完整且未分片的原生内核标尺。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
index 440691d218..768e4298c7 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.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 .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
-2026-07-23-portable-required-pull-request-ci.md: 1a6939e8386e381cba114a7be71993a644457a45
-2026-07-23-portable-required-pull-request-ci.zh.md: f7a95ced2353ca7aaee9a586cc4f0bb297cbf7d4
+2026-07-23-portable-required-pull-request-ci.md: 11de2b1dcbbdbdd7f9423131cd84c2940ac9218d
+2026-07-23-portable-required-pull-request-ci.zh.md: 02f5d758e1259d6a8e7cba70e439775bd1df2b28
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
index 1a6939e838..11de2b1dcb 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
@@ -12,9 +12,9 @@ Billing health, a runner definition's `Ready` state, and a large autoscaling cei
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs Windows Node under Wine on standard `ubuntu-latest` for the blocking surfaces ([Wine lane decision](2026-07-27-wine-windows-gates-experiment.md)), keeping the pull-request Windows contract independent of any Windows runner allocation; the complete native-kernel Windows inventory lives in the master serial reference. Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and `master` runs complete serial Linux, macOS, and Windows references. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
+[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs on standard `windows-2025` under native Windows for the blocking surfaces and broader observational inventory ([native Windows decision](2026-08-08-native-windows-pull-request-ci.md)). Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and the serial references remain the complete unsharded cross-platform definitions. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
 
-The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / wine blocking` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
+The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / native complete` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
 
 The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md) owns the current primary topology and its measurements. The [serial cross-platform reference](2026-07-21-serial-cross-platform-ci-reference.md) remains the independent standard-hosted completeness check, and the manual larger-runner suites retain size comparisons without expanding the ordinary required matrix.
 
@@ -30,6 +30,6 @@ The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md)
 
 ## Consequences
 
-Ordinary pull requests spend enterprise capacity on the Linux critical path while the Wine-hosted Windows job keeps its verdict on standard Linux allocation. A live exact-head run proves the same commands that branch protection consumes; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
+Ordinary pull requests spend enterprise capacity on the Linux critical path while the native Windows job uses standard Windows allocation. A live exact-head run proves the same commands that branch protection consumes; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
 
 Standard compatibility and required Windows jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required Linux job or aggregate green. Recovering Linux availability may require restoring the complete standard-hosted topology; changing a pool definition's status alone is insufficient evidence that it can receive work.
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
index f7a95ced23..02f5d758e1 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node 以覆盖阻断性检查范围（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)），使拉取请求的 Windows 契约不依赖任何 Windows 运行器分配；完整的原生内核 Windows 清单位于 master 串行参考流程中。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `windows-2025` 上以原生 Windows 环境运行，覆盖阻断性检查范围和更广泛的观测性清单（[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)）。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，串行参考流程仍是完整且未分片的跨平台定义。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / native complete` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
 
 当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而 Wine 托管的 Windows 作业让其判定保持在标准 Linux 运行器分配上。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
+普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而原生 Windows 作业使用标准 Windows 运行器容量。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
 
 企业级运行器分配能力下降时，标准兼容性作业和必需的 Windows 作业仍能提供有用证据，但无法让受阻的必需 Linux 作业或聚合流程变绿。恢复 Linux 可用性时，可能需要恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
index 7005f08ce0..224544c058 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.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 .agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 006360cedfd4d1e2c2b67ede98062a375e316f47
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 2258a1fe5f91b27b8a3b636c7f3ad26f502a98df
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 6fba2ce3b508d9d6fc879460a63c0e12673bd866
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: d9da8a4abe13772f3cc282392c03cdea54726c01
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
index 006360cedf..6fba2ce3b5 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
@@ -13,8 +13,8 @@ Outside `landlock-run.yml`, each workflow that installed pnpm hand-provisioned i
 `pnpm/action-setup@v4` is the only pnpm provisioning mechanism in CI: no workflow runs `corepack enable`. The root dev dependency on `@yarnpkg/cli-dist` separately supplies the modern Yarn CLI exercised by the generated-project e2e; package-manager coverage therefore does not inherit the runner image's Yarn Classic. Caching remains per-job policy on top of pnpm provisioning, in three deliberate shapes:
 
 - **Symmetric cache** (restore and save): `actions/setup-node` with `cache: pnpm` — `e2e.yml`, `docs-pages.yml`, `pi-ai-provider-e2e.yml`, `build-exe-for-python-sdk.yml`, and the node-compat and two benchmark jobs of `ci.yml`. The larger-runner benchmark keeps its store cache Linux-only through a conditional `cache:` input; the consolidated benchmark caches on both platforms.
-- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs and the Wine-based pull-request Windows job restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
-- **Cache-less or persistent** (no store-cache action): native serial-windows and serial-macos plus `sandbox.yml` install from a cold or runner-local store. The self-hosted standby and failover jobs reuse their VM's persistent pnpm store without transferring a hosted cache archive.
+- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
+- **Cache-less or persistent** (no store-cache action): the required native Windows job, native serial-windows and serial-macos, plus `sandbox.yml` install from a cold or runner-local store. Extracting the many-file pnpm store costs more than a clean Windows install; the self-hosted standby and failover jobs instead reuse their VM's persistent pnpm store without transferring a hosted cache archive.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
index 2258a1fe5f..d9da8a4abe 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
@@ -13,8 +13,8 @@ Status: implemented
 `pnpm/action-setup@v4` 是 CI 中提供 pnpm 的唯一机制：没有任何工作流运行 `corepack enable`。根目录的 `@yarnpkg/cli-dist` 开发依赖另行提供 generated-project e2e 所运行的现代 Yarn CLI（命令行界面）；因此，用于包管理器覆盖率的 Yarn 不会沿用 runner 镜像里的 Yarn Classic。缓存仍是叠加在 pnpm 提供机制上的按作业政策，保持三种刻意的形态：
 
 - **对称缓存**（既恢复也保存）：带 `cache: pnpm` 的 `actions/setup-node`——`e2e.yml`、`docs-pages.yml`、`pi-ai-provider-e2e.yml`、`build-exe-for-python-sdk.yml`，以及 `ci.yml` 的 node-compat 与两个 benchmark 作业。larger-runner benchmark 通过条件化的 `cache:` 输入让 store 缓存仅限 Linux；consolidated benchmark 在两个平台上都启用缓存。
-- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业与基于 Wine 的拉取请求 Windows 作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
-- **无缓存或持久化**（不使用 store 缓存 action）：原生 serial-windows 和 serial-macos 加上 `sandbox.yml` 从冷 store 或 runner 本地 store 安装。自托管热备与故障切换作业复用其 VM 的持久 pnpm store，不传输托管缓存归档。
+- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
+- **无缓存或持久化**（不使用 store 缓存 action）：必需的原生 Windows 作业、原生 serial-windows 和 serial-macos，以及 `sandbox.yml` 均从冷 store 或 runner 本地 store 安装。解压含有大量文件的 pnpm store，成本高于在 Windows 上进行一次全新安装；自托管热备与故障切换作业则复用其 VM 的持久 pnpm store，不传输托管缓存归档。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
new file mode 100644
index 0000000000..3b3d2dc1dd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+2026-08-08-native-windows-pull-request-ci.md: 926eec04cff63aaf25d1e85b3dcbc41464f25660
+2026-08-08-native-windows-pull-request-ci.zh.md: 8728f0eb08adcb1501f036bb19ff523ded406ccc
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
new file mode 100644
index 0000000000..926eec04cf
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -0,0 +1,33 @@
+# Agent Note: Native Windows pull-request CI
+
+Status: implemented
+
+English | [中文](2026-08-08-native-windows-pull-request-ci.zh.md)
+
+## Problem
+
+The required pull-request Windows verdict must protect behavior that depends on the operating system, not only toolchain branches selected by `process.platform`. The Wine lane executed Windows Node and PE binaries over a Linux kernel and case-sensitive ext4, required a hoisted dependency layout and host-created symlinks, and omitted NTFS, DACL, ConPTY, crash-durability, and the broader observational Windows inventory. With the native serial references disabled, ordinary CI had no real Windows-kernel signal.
+
+## Decision
+
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) runs on GitHub's standard `windows-2025` image under native PowerShell. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete`. The stable `windows` job id remains a dependency of `all checks passed`; its display name is `windows node 24 / native complete`.
+
+The aggregate keeps workspace build and production-site failures blocking while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
+
+Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
+
+## Alternatives considered
+
+**Keep Wine on the required path.** Its warm wall clock was close to Linux CI and it selected win32 toolchain branches, but the compatibility-specific layout and kernel gaps could report green while supported native behavior was broken. Latency no longer outweighs that missing signal.
+
+**Restore the pre-Wine workflow verbatim.** The old definition captured the right runner boundary but also carried then-current provisioning and topology assumptions. Reconstructing the native job against the current actions, pnpm setup, gate graph, and aggregate dependency avoids reviving obsolete machinery.
+
+**Run native Windows only after merge.** A post-merge reference diagnoses portability regressions after they enter `master`; it cannot protect a pull request while those references are disabled or delayed.
+
+**Use an organization-owned larger Windows runner.** Larger images can reduce wall clock, but a required correctness path would then depend on repository-external labels and allocation. Standard `windows-2025` is the portable recovery boundary; larger runners remain benchmark targets.
+
+## Consequences
+
+Pull requests receive a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal before the aggregate can pass. The job is slower than the Wine compatibility lane and can queue on Windows capacity, but its green result now describes the supported host rather than an approximation.
+
+Removing the Wine cache producer and local script deletes a separate install topology and its recurring compatibility failures. Native coverage and snapshots remain a named gap rather than being implied by the job name; they require their own tested contract before becoming part of this required lane.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
new file mode 100644
index 0000000000..8728f0eb08
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 原生 Windows 拉取请求 CI
+
+Status: implemented
+
+[English](2026-08-08-native-windows-pull-request-ci.md) | 中文
+
+## 问题
+
+拉取请求必需的 Windows 判定必须为依赖操作系统的行为提供保障，而不能只覆盖由 `process.platform` 选择的工具链分支。Wine 通道在 Linux 内核与区分大小写的 ext4 之上执行 Windows Node 和 PE 二进制文件，要求采用 hoisted 依赖布局和由宿主侧创建的符号链接，也没有覆盖 NTFS、DACL、ConPTY、崩溃持久性与更广泛的观测性 Windows 清单。原生串行参考流程停用期间，常规 CI 没有任何真实的 Windows 内核信号。
+
+## 决策
+
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业在 GitHub 标准 `windows-2025` 镜像上使用原生 PowerShell 运行。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并运行 `pnpm run check:ci:windows-complete`。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项；其显示名称为 `windows node 24 / native complete`。
+
+聚合作业继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
+
+受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
+
+## 曾考虑的替代方案
+
+**在必需路径上保留 Wine。** 其热运行墙钟时间接近 Linux CI，也会选择 win32 工具链分支；但兼容性专属布局和内核缺口可能在受支持的原生行为已经损坏时仍报告绿灯。这项延迟收益不足以抵消该信号缺失的代价。
+
+**逐字恢复 Wine 之前的工作流。** 旧定义确实捕获了正确的运行器边界，但也携带了当时的供应方式与拓扑假设。按照当前 action、pnpm 设置、门禁图和聚合依赖关系重新构建原生作业，可以避免重新引入过时机制。
+
+**只在合并后运行原生 Windows。** 合并后的参考流程只能在可移植性回归进入 `master` 后进行诊断；当这些参考流程被停用或延迟时，无法在拉取请求阶段提供保护。
+
+**使用组织自有的大型 Windows 运行器。** 更大规格的运行器镜像可以缩短墙钟时间，但必需的正确性路径将因此依赖仓库外部的运行器标签与分配能力。标准 `windows-2025` 是可移植恢复边界；大型运行器仍作为基准测试目标。
+
+## 后果
+
+在聚合作业通过之前，拉取请求会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。该作业比 Wine 兼容性通道更慢，也可能因 Windows 容量而排队，但其绿灯结果描述的是受支持的宿主，而非近似环境。
+
+移除 Wine 缓存生产者和本地脚本后，独立的安装拓扑及其反复出现的兼容性故障也随之消失。原生 Windows 覆盖率与快照仍是明确列出的缺口，不会仅由作业名称暗示已经纳入；二者都必须先建立各自经过测试的契约，才能成为该必需通道的一部分。
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index ff4fd4e6b2..c95b85e8e2 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — GitHub Actions
 
-Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. The pull-request `windows` job is not one of them: it runs Windows Node under Wine on hosted Linux, so its steps are bash — see the [Wine lane Agent Note](../.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md).
+Run jobs on Windows runners (`windows-*` labels) under native `pwsh`.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 46ab8e892f..0e96d50e50 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -300,27 +300,29 @@ jobs:
       - name: Run complete keyless Python suite
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
-  # The required pull-request Windows signal: the two blocking win32 surfaces
-  # (workspace build, production site) execute with real, checksum-verified
-  # Windows Node under Wine on standard hosted Linux. The master
-  # serial-windows job below normally keeps the complete native-kernel
-  # inventory — including the observational portability gates this lane does
-  # not run —
-  # on real windows-2025. This job only provisions runner state (caches,
-  # apt); scripts/wine-windows-gates.sh owns the gate logic and is the same
-  # script the optional local gate `pnpm run check:windows-wine` runs.
-  # Layout, fidelity limits, and measured timings live in
-  # .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+  # One standard Windows box shares setup across the required build/site checks
+  # and the observational portability inventory. Serial worker bounds keep this
+  # recovery path portable; Linux owns duplicate lint, coverage, and snapshots.
+  # See the native-Windows pull-request CI decision:
+  # .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
   windows:
     if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    name: windows node 24 / wine blocking
-    timeout-minutes: 15
+    runs-on: windows-2025
+    name: windows node 24 / native complete
+    env:
+      DSH_GATE_CONCURRENCY: '1'
+      DSH_PUBLINT_CONCURRENCY: '1'
     steps:
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
 
+      - name: Enable Developer Mode (symlink support)
+        shell: pwsh
+        run: >-
+          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+          /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+
       - uses: pnpm/action-setup@v4
         with:
           dest: ${{ runner.temp }}/setup-pnpm
@@ -329,86 +331,15 @@ jobs:
         with:
           node-version: ${{ env.PRIMARY_NODE_VERSION }}
 
-      - name: Configure pnpm store path
-        id: pnpm-store
-        run: |
-          store_root="$HOME/.local/share/pnpm/store"
-          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
-          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
-          echo "path=$store_path" >> "$GITHUB_OUTPUT"
+      # Extracting the many-file pnpm store cache is slower than a clean install,
+      # and saving it adds more latency after the gates.
+      - name: Install (immutable)
+        shell: pwsh
+        run: pnpm install --frozen-lockfile
 
-      - uses: actions/cache/restore@v4
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
-
-      # Master's wine-apt-cache job seeds the default-branch scope every pull
-      # request can read; a save from this job only reaches reruns of the
-      # same merge ref.
-      - name: Compose Wine apt cache key
-        id: wine-cache-key
-        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
-
-      - uses: actions/cache@v4
-        with:
-          path: ~/wine-debs
-          key: ${{ steps.wine-cache-key.outputs.key }}
-
-      # Runner provisioning only — a developer machine installs Wine through
-      # its own package manager; the gate script assumes a wine binary and
-      # fails loud without one. Wine from the apt cache when present; else
-      # download the full dependency closure once and keep it for the next
-      # run. The `wine` dispatcher package (not bare `wine64`) is what puts a
-      # binary on PATH.
-      - name: Install Wine
-        run: |
-          if compgen -G "$HOME/wine-debs/*.deb" > /dev/null; then
-            sudo apt-get install -y --no-install-recommends "$HOME"/wine-debs/*.deb
-          else
-            sudo apt-get update
-            sudo apt-get install -y --no-install-recommends --download-only wine
-            mkdir -p "$HOME/wine-debs"
-            cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" 2>/dev/null || true
-            sudo apt-get install -y --no-install-recommends wine
-          fi
-
-      - name: Run the Wine Windows gates
-        run: bash scripts/wine-windows-gates.sh
-
-      - name: Shut down wineserver
-        if: always()
-        run: wineserver -k 2>/dev/null || true
-
-  # Master seeds the Wine apt-archive cache in the default-branch scope,
-  # which every pull request's windows job can restore; saves from
-  # pull-request runs are scoped to their own merge ref and help nobody
-  # else. Runs in seconds when the image version already has a cache.
-  wine-apt-cache:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
-    name: wine apt cache
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Compose Wine apt cache key
-        id: wine-cache-key
-        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
-
-      - uses: actions/cache@v4
-        id: wine-cache
-        with:
-          path: ~/wine-debs
-          key: ${{ steps.wine-cache-key.outputs.key }}
-
-      - name: Download the Wine dependency closure
-        if: steps.wine-cache.outputs.cache-hit != 'true'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends --download-only wine
-          mkdir -p "$HOME/wine-debs"
-          cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/"
-          du -sh "$HOME/wine-debs"
+      - name: Run blocking and observational Windows gates concurrently
+        shell: pwsh
+        run: pnpm run check:ci:windows-complete
 
   # The hosted reference jobs below are temporarily disabled; the self-hosted
   # standby remains active. Each enabled host executes the complete, unsharded
diff --git a/AGENTS.md b/AGENTS.md
index 64f2e944a8..575538bca7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -65,7 +65,6 @@ pnpm run typecheck
 pnpm run lint
 pnpm run duplication    # cross-file TypeScript clone detection
 pnpm run build          # tsc emits lib/types, tsdown bundles runtime
-pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
 pnpm run hygiene        # knip + publint + workspace constraints + NodeNext consumer check
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
diff --git a/package.json b/package.json
index 423cbf813c..193e83dc1c 100644
--- a/package.json
+++ b/package.json
@@ -57,7 +57,6 @@
     "check:ci:windows-blocking": "tsx scripts/run-gates.ts ci-windows-blocking",
     "check:ci:windows-complete": "tsx scripts/run-gates.ts ci-windows-complete",
     "check:ci:windows-observational": "tsx scripts/run-gates.ts ci-windows-observational",
-    "check:windows-wine": "bash scripts/wine-windows-gates.sh",
     "check:node-compat": "tsx scripts/run-gates.ts node-compat",
     "knip": "knip --treat-config-hints-as-errors",
     "publint": "tsx scripts/publint-all.ts",
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index baeac7a8c0..b5d161dae7 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -26,6 +26,28 @@ describe('CI workflow', () => {
       })
     }
   })
+
+  it('runs the required Windows contract on a native hosted runner', () => {
+    const workflow = loadWorkflow('.github/workflows/ci.yml')
+    if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.windows)) {
+      throw new TypeError('CI workflow must define the windows job')
+    }
+
+    const windows = workflow.jobs.windows
+    if (!Array.isArray(windows.steps)) throw new TypeError('windows job must define steps')
+    const steps: unknown[] = windows.steps
+    const commandSteps = steps.filter((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && typeof step.run === 'string'
+    ))
+
+    expect(windows['runs-on']).toBe('windows-2025')
+    expect(windows.name).toBe('windows node 24 / native complete')
+    expect(commandSteps).toHaveLength(3)
+    expect(commandSteps.every(step => step.shell === 'pwsh')).toBe(true)
+    expect(commandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
+    expect(JSON.stringify(windows)).not.toMatch(/wine/i)
+    expect(workflow.jobs).not.toHaveProperty('wine-apt-cache')
+  })
 })
 
 describe('Issue lifecycle workflow', () => {
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
deleted file mode 100755
index b6d8ffffb0..0000000000
--- a/scripts/wine-windows-gates.sh
+++ /dev/null
@@ -1,247 +0,0 @@
-#!/usr/bin/env bash
-# Run the blocking Windows gates (workspace build, production site) with real
-# win-x64 Node.js under Wine — the same script the pull-request `windows` job
-# in ci.yml executes and the optional local gate `pnpm run check:windows-wine`
-# wraps. Owning rationale, fidelity limits, and measured timings:
-# .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-#
-# The working tree is never mutated: tracked plus untracked-unignored files
-# are snapshotted into a scratch directory, the Wine-specific pnpm overrides
-# (hoisted layout, win32-x64 platform packages) are appended to the SNAPSHOT's
-# pnpm-workspace.yaml, and the install and gates run there against the shared
-# pnpm store. The Wine prefix and the checksum-verified Windows Node zip
-# persist in .cache/wine-windows/ so reruns skip provisioning.
-#
-# Environment: DSH_WINE_NODE_MAJOR (default $PRIMARY_NODE_VERSION, then 24)
-# picks the Windows Node line; DSH_WINE_GATE_CACHE_DIR relocates the cache;
-# DSH_WINE_GATE_KEEP=1 preserves the scratch tree for inspection.
-
-set -euo pipefail
-
-repo_root="$(git rev-parse --show-toplevel)"
-node_major="${DSH_WINE_NODE_MAJOR:-${PRIMARY_NODE_VERSION:-24}}"
-cache_dir="${DSH_WINE_GATE_CACHE_DIR:-$repo_root/.cache/wine-windows}"
-
-export WINEDEBUG='-all'
-export WINEARCH=win64
-# Skip Wine Mono / Gecko installers: Node needs neither.
-export WINEDLLOVERRIDES='mscoree,mshtml='
-export WINEPREFIX="$cache_dir/prefix"
-
-# ---- preflight: fail loud before any expensive work --------------------
-wine_bin=''
-for candidate in "$(command -v wine || true)" "$(command -v wine64 || true)" /usr/lib/wine/wine64; do
-  if [ -n "$candidate" ] && [ -x "$candidate" ]; then wine_bin="$candidate"; break; fi
-done
-# GNU coreutils sha256sum on Linux; perl shasum ships with macOS. Both
-# accept the same "<hash>  <file>" --check input.
-checksum_tool=''
-if command -v sha256sum > /dev/null; then
-  checksum_tool='sha256sum'
-elif command -v shasum > /dev/null; then
-  checksum_tool='shasum'
-fi
-missing=()
-[ -n "$wine_bin" ] || missing+=('wine (apt: wine | brew: wine-stable)')
-command -v curl > /dev/null || missing+=('curl')
-command -v unzip > /dev/null || missing+=('unzip')
-[ -n "$checksum_tool" ] || missing+=('sha256sum or shasum (apt: coreutils | macOS ships shasum)')
-if ! command -v pnpm > /dev/null; then corepack enable > /dev/null 2>&1 || true; fi
-command -v pnpm > /dev/null || missing+=('pnpm (corepack enable)')
-if (( ${#missing[@]} > 0 )); then
-  printf 'wine-windows-gates: missing required tool: %s\n' "${missing[@]}" >&2
-  exit 1
-fi
-
-# Verify file $2 against SHA-256 hex $1 with whichever tool preflight found.
-verify_sha256() {
-  case "$checksum_tool" in
-    sha256sum) printf '%s  %s\n' "$1" "$2" | sha256sum --check - > /dev/null ;;
-    shasum) printf '%s  %s\n' "$1" "$2" | shasum -a 256 --check - > /dev/null ;;
-  esac
-}
-
-scratch="$(mktemp -d "${TMPDIR:-/tmp}/dsh-wine-gates.XXXXXX")"
-cleanup() {
-  wineserver -k > /dev/null 2>&1 || true
-  if [ "${DSH_WINE_GATE_KEEP:-0}" = '1' ]; then
-    echo "wine-windows-gates: scratch tree kept at $scratch"
-  else
-    rm -rf "$scratch"
-  fi
-}
-trap cleanup EXIT
-mkdir -p "$cache_dir" "$scratch/logs"
-
-# ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
-provision_node() {
-  # Latest release of the primary line, checksum-verified against the same
-  # dist directory. Offline runs fall back to the newest cached zip, loudly.
-  local version zip
-  version="$(curl -fsSL --max-time 30 https://nodejs.org/dist/index.json 2> /dev/null \
-    | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
-    || true)"
-  if [ -n "$version" ]; then
-    zip="$cache_dir/node-$version-win-x64.zip"
-    if [ ! -f "$zip" ]; then
-      curl -fsSL -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
-      local expected
-      expected="$(curl -fsSL "https://nodejs.org/dist/$version/SHASUMS256.txt" \
-        | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
-      [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
-      verify_sha256 "$expected" "$zip.tmp"
-      mv "$zip.tmp" "$zip"
-    fi
-  else
-    zip="$(ls -t "$cache_dir"/node-v"$node_major".*-win-x64.zip 2> /dev/null | head -1 || true)"
-    [ -n "$zip" ] || { echo "wine-windows-gates: nodejs.org unreachable and no cached Windows Node v$node_major zip in $cache_dir" >&2; exit 1; }
-    echo "wine-windows-gates: nodejs.org unreachable; using cached $(basename "$zip")" >&2
-  fi
-  unzip -q -o "$zip" -d "$scratch/node-win"
-  echo "$scratch/node-win/$(basename "$zip" .zip)/node.exe" > "$scratch/node-win-path"
-}
-
-boot_wine() {
-  "$wine_bin" wineboot --init > /dev/null 2>&1 || true
-  wineserver -w || true
-}
-
-snapshot_and_install() {
-  # Tracked + untracked-unignored files, minus agent-session litter; the
-  # existence filter drops paths staged as deleted. Then the Wine-specific
-  # install-time overrides go on the SNAPSHOT only: hoisted because Windows
-  # Node under Wine does not realpath pnpm's isolated-layout symlinks, and
-  # win32-x64 so the Windows esbuild/rolldown/rollup binaries materialize.
-  # Neither is recorded in the lockfile, so --frozen-lockfile stays valid;
-  # --ignore-scripts skips host lifecycle scripts no gate loads.
-  git -C "$repo_root" ls-files -z --cached --others --exclude-standard -- . ':!:.claude' ':!:.codex' \
-    | while IFS= read -r -d '' file; do [ -e "$repo_root/$file" ] && printf '%s\0' "$file"; done \
-    | tar -C "$repo_root" --null --files-from=- -cf - \
-    | tar -C "$scratch/tree" -xf -
-  cat >> "$scratch/tree/pnpm-workspace.yaml" << 'EOF'
-
-nodeLinker: hoisted
-supportedArchitectures:
-  os: [current, win32]
-  cpu: [current, x64]
-EOF
-  # The hoisted linker — used only by this lane — has an upstream rename
-  # race (pnpm/pnpm#12880): parallel linkers staging a nested package copy
-  # (observed on the tree's nested esbuild versions) rename their _tmp_*
-  # directory onto a path another racer already claimed, and the loser
-  # exits ERR_PNPM_ENOENT although an identical re-install succeeds.
-  # Exactly that signature earns up to two retries on a clean tree — the
-  # snapshot contains no node_modules, so wiping them restores the
-  # pre-install state; any other failure, or the race still standing after
-  # the final attempt, fails loud with the log tail.
-  local attempt
-  for attempt in 1 2 3; do
-    (cd "$scratch/tree" && pnpm install --frozen-lockfile --ignore-scripts > "$scratch/logs/install.log" 2>&1) \
-      && return 0
-    grep -q 'ERR_PNPM_ENOENT.*rename.*_tmp_' "$scratch/logs/install.log" || break
-    (( attempt < 3 )) || break
-    echo "wine-windows-gates: pnpm hoisted-linker rename race (pnpm/pnpm#12880) on install attempt $attempt; retrying on a clean tree" >&2
-    find "$scratch/tree" -name node_modules -type d -prune -exec rm -rf {} +
-  done
-  tail -40 "$scratch/logs/install.log" >&2
-  return 1
-}
-
-mkdir "$scratch/tree"
-start=$SECONDS
-provision_node & node_pid=$!
-boot_wine & wine_pid=$!
-snapshot_and_install & install_pid=$!
-# Wait for EVERY child before judging any: a bare `wait` under set -e would
-# exit on the first failure and let the EXIT trap delete $scratch while the
-# other children still run inside it. Named statuses also make the report
-# point at the root cause instead of a downstream symptom.
-node_status=0; wait "$node_pid" || node_status=$?
-wine_status=0; wait "$wine_pid" || wine_status=$?
-install_status=0; wait "$install_pid" || install_status=$?
-provision_failed=0
-report_provision() {
-  if (( $2 != 0 )); then
-    echo "wine-windows-gates: FAILED $1 (exit $2)" >&2
-    provision_failed=$2
-  fi
-}
-report_provision 'Windows Node provisioning' "$node_status"
-report_provision 'wineboot' "$wine_status"
-report_provision 'workspace snapshot + pnpm install' "$install_status"
-if (( provision_failed != 0 )); then exit "$provision_failed"; fi
-node_win="$(cat "$scratch/node-win-path")"
-echo "wine-windows-gates: provisioned in $((SECONDS - start))s (wine $("$wine_bin" --version 2> /dev/null), node $(basename "$(dirname "$node_win")"))"
-
-# ---- resolve entrypoints, lay the vue link, smoke ------------------------
-# Node under Wine cannot attach stdio to pipes the caller owns (Socket open
-# EBADF at bootstrap), so every invocation routes stdio through a file.
-wine_node() {
-  local log="$1"
-  shift
-  local status=0
-  "$wine_bin" "$node_win" "$@" < /dev/null > "$log" 2>&1 || status=$?
-  return "$status"
-}
-
-cd "$scratch/tree"
-tsc_js='node_modules/typescript/bin/tsc'
-tsdown_js='node_modules/tsdown/dist/run.mjs'
-vitepress_js='node_modules/vitepress/bin/vitepress.js'
-[ -f "$vitepress_js" ] || vitepress_js='website/node_modules/vitepress/bin/vitepress.js'
-for entry in "$tsc_js" "$tsdown_js" "$vitepress_js"; do
-  [ -f "$entry" ] || { echo "wine-windows-gates: expected entrypoint missing after hoisted install: $entry" >&2; exit 1; }
-done
-# VitePress links vue into the site's node_modules at build time; Wine cannot
-# CREATE Windows symlinks (ENOTSUP) but follows pre-existing Unix ones.
-if [ -d node_modules/vue ] && [ ! -e website/node_modules/vue ]; then
-  mkdir -p website/node_modules
-  ln -s ../../node_modules/vue website/node_modules/vue
-fi
-
-wine_node "$scratch/logs/smoke.log" -p "'smoke: ' + process.platform + ' ' + process.arch + ' ' + process.version"
-cat "$scratch/logs/smoke.log"
-grep -q '^smoke: win32 x64' "$scratch/logs/smoke.log" || { echo 'wine-windows-gates: Windows Node smoke did not report win32 x64' >&2; exit 1; }
-
-# ---- the two blocking surfaces, concurrently ------------------------------
-# The build preserves the face order from package.json: compile and bundle the
-# Host face before compiling and bundling the Client face.
-# Both statuses are captured so one failure cannot hide the other's result.
-build_gate() {
-  wine_node "$scratch/logs/host-tsc.log" "$tsc_js" -b tsconfig.host.json --pretty false || return $?
-  wine_node "$scratch/logs/host-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE host || return $?
-  wine_node "$scratch/logs/client-tsc.log" "$tsc_js" -b tsconfig.client.json --pretty false || return $?
-  wine_node "$scratch/logs/client-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE client
-}
-site_gate() {
-  cd website
-  wine_node "$scratch/logs/site.log" "../$vitepress_js" build .
-}
-
-start=$SECONDS
-build_gate & build_pid=$!
-site_gate & site_pid=$!
-build_status=0
-wait "$build_pid" || build_status=$?
-site_status=0
-wait "$site_pid" || site_status=$?
-elapsed=$((SECONDS - start))
-
-report() {
-  local label="$1" status="$2"
-  shift 2
-  if (( status == 0 )); then
-    echo "wine-windows-gates: PASS $label (${elapsed}s window)"
-  else
-    echo "== FAILED $label (exit $status) ==" >&2
-    for log in "$@"; do tail -n 200 "$log" >&2 || true; done
-  fi
-}
-report 'build (Host tsc/tsdown, Client tsc/tsdown)' "$build_status" \
-  "$scratch/logs/host-tsc.log" \
-  "$scratch/logs/host-tsdown.log" \
-  "$scratch/logs/client-tsc.log" \
-  "$scratch/logs/client-tsdown.log"
-report 'production site (vitepress build)' "$site_status" "$scratch/logs/site.log"
-if (( build_status != 0 )); then exit "$build_status"; fi
-exit "$site_status"

From b0eb7f8f35e385ad32b0a8af6e407de8f859c65f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:23:26 +0800
Subject: [PATCH 012/262] docs: define unified GitHub label taxonomy

---
 ...07-25-semantic-pr-label-taxonomy.i18n.yaml |  4 +-
 .../2026-07-25-semantic-pr-label-taxonomy.md  | 65 +++++++------------
 ...026-07-25-semantic-pr-label-taxonomy.zh.md | 65 +++++++------------
 AGENTS.md                                     |  2 +-
 4 files changed, 53 insertions(+), 83 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
index 1aaa9f992b..a83236521c 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.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 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
-2026-07-25-semantic-pr-label-taxonomy.md: 3217b405e968d4d2c1eba1f1a5a08008b18ba514
-2026-07-25-semantic-pr-label-taxonomy.zh.md: 978f11af9402f248679e2087ff7fb513321b69b9
+2026-07-25-semantic-pr-label-taxonomy.md: 6aef5ecbb80005d1fcd90b4ee673bbbebb92cba6
+2026-07-25-semantic-pr-label-taxonomy.zh.md: 0bd3fbcaeca37fa894e92ce5a4e78c4125056ac9
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
index 3217b405e9..6aef5ecbb8 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
+++ b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
@@ -6,66 +6,51 @@ English | [中文](2026-07-25-semantic-pr-label-taxonomy.zh.md)
 
 ## Problem
 
-Pull requests need two different signals: what kind of change they make and which repository domains they affect. A flat or broadly named label set conflates those questions, hides work in distinct areas such as `session` and `llm`, and gives reviewers and automation weak inputs.
+Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or keeping synonymous labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
 
-The repository also gains new domains over time. Treating today's area labels as a closed set would force future work into inaccurate labels or a generic catch-all.
+Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each label family.
 
 ## Decision
 
-Every open or merged pull request carries exactly one kind and every materially affected area. Closed pull requests that were never merged are outside the maintained historical corpus. Other operational labels may coexist, but they do not satisfy either dimension.
+Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
 
 ### Kinds
 
+The kind set is closed and mutually exclusive:
+
 | Kind | Meaning |
 |---|---|
-| `feature` | Adds or intentionally changes behavior. |
-| `bug-fix` | Corrects incorrect behavior. |
-| `doc` | Makes documentation the dominant intent. |
-| `testing` | Changes tests or testing infrastructure without changing product behavior. |
-| `cleanup` | Preserves behavior while maintaining or simplifying the implementation or repository process. |
+| `kind/feature` | Adds or intentionally changes behavior. |
+| `kind/bug-fix` | Corrects incorrect behavior. |
+| `kind/doc` | Makes documentation the dominant intent. |
+| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
+| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
+| `kind/dependency` | Updates dependencies without another dominant intent. |
 
-The kind records the change's dominant intent: accompanying tests and documentation do not turn a feature or bug fix into a testing or documentation change.
+The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix.
 
-Areas record semantic repository domains rather than temporary initiatives, ownership, or every path touched incidentally. Area labels are not a hierarchy: a pull request may carry several when it changes distinct contracts, but an umbrella and a narrower label do not both describe the same work.
+### Areas
 
-### Current areas
+Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory.
 
-The 46 current areas are listed below. The group names organize the list for readability; they are not labels or another taxonomy level.
+The area set is intentionally extensible. When no existing description honestly covers a durable and reusable repository domain, an agent is empowered to create a concise `area/<lowercase-kebab-case>` label without separate approval. The agent must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and must report the new label after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
 
-| Group | Areas |
-|---|---|
-| Agent and model | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
-| Orchestration | `subagent`, `workflow`, `planning`, `tasks`, `schedule`, `telemetry`, `storage`, `workspace` |
-| Capabilities | `bash`, `subprocess`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `artifact`, `attachment`, `sandbox`, `mcp`, `hooks`, `cordis` |
-| Interfaces | `ui`, `gui`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `vscode`, `website` |
-| Repository and release | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
+Kinds are not extended this way. A new kind changes the mutually exclusive classification contract and requires an explicit taxonomy change with corresponding policy enforcement.
 
-`gui` covers browser and Electron graphical applications, including standalone graphical developer tools; `vscode` remains the editor extension integration. `ui` covers shared cross-interface commands, approval interaction, presentation, and app boot; it coexists with `gui`, `tui`, or a protocol area only when the pull request also changes that shared contract.
+### Issues and operational labels
 
-`tasks` owns background work tied to a running process, while `schedule` owns durable time-triggered jobs. `tools` owns generic registry, schema, and execution contracts; a concrete capability receives `tools` only when it changes one of those contracts. `attachment` owns durable media references and multimodal input delivery, while `artifact` owns model-declared deliverable identity and preview lifecycle; neither borrows `tools` or `ui` for its implementation parts.
+Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
 
-Names follow semantic ownership rather than lexical resemblance. `hooks` means the Claude Code and Codex agent bridges, not local Git hooks; `platform` means product portability, not CI runner selection; and `build` means compilation, bundling, and built package artifacts, not documentation generators.
-
-### Extensibility
-
-The area set is intentionally extensible. Add an area when a recurring, meaningful repository domain is missing; do not add a label for one pull request, a temporary project, a status, or a person or team. Rename, split, or retire an area when the domain model changes, and update this list and the affected open and merged pull requests together.
-
-The kind set stays narrow because kinds are mutually exclusive. A new kind requires a distinct change intent that cannot be represented by the current five; it is not a substitute for an area.
+Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
 
 ## Alternatives considered
 
-- **One undifferentiated label set.** Rejected because kind and area answer different questions; mixing them makes the presence of one label say nothing about whether the other dimension was considered.
-- **A fixed, closed area set.** Rejected because repository domains evolve. A closed set would preserve spelling at the cost of semantic accuracy.
-- **One broad `core` area or package-derived labels.** Rejected because domains such as `session`, `llm`, and `agent` remain independently meaningful across package boundaries, while incidental file paths are not the scope reviewers or automation need.
-- **Separate browser and desktop areas.** Rejected because browser delivery and Electron packaging expose one graphical client domain; splitting them classifies the delivery shell rather than the semantic work.
-- **Broad implementation areas in place of a domain.** Rejected because a durable scheduled job is not a background task, an attachment is not merely its source interface or filesystem implementation, and an artifact is not merely its declaring tool or preview interface.
-- **Umbrella and leaf areas for the same contract.** Rejected because duplicate labels inflate scope without adding information. Multiple areas remain correct when a pull request changes genuinely distinct contracts.
-- **Exactly one area per pull request.** Rejected because coherent changes can legitimately span several domains, and dropping secondary areas hides affected contracts.
+- **Unprefixed labels.** Rejected because a flat name does not identify whether it classifies intent, domain, source, priority, or automation, and synonymous plain and prefixed labels caused ambiguous queries.
+- **A fixed area allowlist in repository policy.** Rejected because durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
+- **Kinds on Issues.** Rejected because native Issue Type already owns that classification; duplicating it as a label creates drift.
+- **Automatic areas from paths.** Rejected because areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
+- **Exactly one area per pull request.** Rejected because coherent changes can materially affect several independent contracts.
 
 ## Consequences
 
-- Reviewers and automation receive one stable intent signal plus a complete semantic scope.
-- `gui` queries cover browser and desktop delivery together, while `ui` queries retain only shared cross-interface contracts.
-- `schedule`, `attachment`, and `artifact` queries identify those domains directly instead of approximating them through implementation dependencies.
-- Selecting labels remains a judgment call: paths and title prefixes can suggest areas, but they cannot replace reading the change.
-- Taxonomy changes carry maintenance work. Area additions, renames, splits, and removals update this decision record and backfill open and merged pull requests so historical queries keep their meaning.
+Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and live label descriptions rather than infer classification from title prefixes or paths, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
index 978f11af94..0bd3fbcaec 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
+++ b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
@@ -6,66 +6,51 @@ Status: implemented
 
 ## 问题
 
-PR（Pull Request）需要传达两个不同的信号：它带来哪一类变更，以及会影响仓库中的哪些领域。一套扁平或命名宽泛的标签会混淆这两个问题，掩盖 `session`、`llm` 等不同领域的工作，也让评审人和自动化流程得到的输入缺乏有效信息。
+PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度或保留同义标签会使查询含义模糊，而封闭的领域清单会迫使新领域被归入不准确的类别。
 
-仓库还会随时间发展出新的领域。如果把当前的领域标签视为封闭集合，未来的工作就只能归入不准确的标签或通用兜底标签。
+Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
 
 ## 决策
 
-每项开放或已合并的 PR 都带有恰好一个类型标签，以及所有受到实质影响的领域标签。未合并即关闭的 PR 不属于持续维护的历史记录集合。其他管理用途的标签可以并存，但都不能满足这两个维度中的任一个。
+每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个受到实质影响的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
 
 ### 类型
 
+类型集合封闭且互斥：
+
 | 类型 | 含义 |
 |---|---|
-| `feature` | 新增行为或有意改变行为。 |
-| `bug-fix` | 修正错误行为。 |
-| `doc` | 以文档变更为主要意图。 |
-| `testing` | 修改测试或测试基础设施，但不改变产品行为。 |
-| `cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
+| `kind/feature` | 新增行为或有意改变行为。 |
+| `kind/bug-fix` | 修正错误行为。 |
+| `kind/doc` | 以文档变更为主要意图。 |
+| `kind/testing` | 修改测试或测试基础设施，但不改变产品行为。 |
+| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
+| `kind/dependency` | 在没有其他主要意图时更新依赖。 |
 
-类型记录变更的主要意图：配套测试与文档并不会把一项功能或缺陷修复变成测试或文档变更。
+类型记录主要意图。配套测试、文档、清理或依赖调整不会覆盖一项功能或缺陷修复的主要意图。
 
-领域记录仓库中的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。领域标签不构成层级：一项 PR 修改不同契约时可以带有多个领域标签，但不能用一个总括标签和一个较窄标签重复描述同一项工作。
+### 领域
 
-### 当前领域
+领域表示持久的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。当前分类清单以 GitHub 上实时的 `area/*` 名称和描述为准。
 
-当前的 46 个领域如下。分组名称仅用于提高列表的可读性；它们既不是标签，也不是分类体系中的另一个层级。
+领域集合有意保持可扩展。当现有描述都无法准确涵盖一个持久且可复用的仓库领域时，agent（智能体）有权无须另行批准，直接创建简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后报告。仅为避免新增一个确有必要的标签而复用不准确的领域，不可接受。
 
-| 分组 | 领域 |
-|---|---|
-| agent（智能体）与模型 | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
-| 编排 | `subagent`, `workflow`, `planning`, `tasks`, `schedule`, `telemetry`, `storage`, `workspace` |
-| 能力 | `bash`, `subprocess`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `artifact`, `attachment`, `sandbox`, `mcp`, `hooks`, `cordis` |
-| 接口 | `ui`, `gui`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `vscode`, `website` |
-| 仓库与发布 | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
+类型不以这种方式扩展。新增类型会改变互斥的分类契约，必须明确修改分类体系并同步调整策略强制校验。
 
-`gui` 涵盖浏览器和 Electron 图形应用，包括独立的图形化开发者工具；`vscode` 仍表示编辑器扩展集成。`ui` 涵盖共享的跨接口命令、审批交互、呈现和应用启动；只有当 PR 还修改这项共享契约时，它才与 `gui`、`tui` 或某个协议领域并用。
+### Issue 与管理用途标签
 
-`tasks` 负责与运行中进程绑定的后台工作，`schedule` 则负责持久化的定时作业。`tools` 负责通用的注册表契约、schema 契约和执行契约；具体能力只有在修改其中一项契约时才带有 `tools`。`attachment` 负责持久化的媒体引用和多模态输入传递，`artifact` 则负责模型声明的交付物标识和预览生命周期；二者都不会因实现包含工具或界面部分而借用 `tools` 或 `ui`。
+Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍为可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
 
-标签名称以语义归属为准，而不是词面相似性。`hooks` 指 Claude Code 和 Codex 的 agent 桥接，而不是本地 Git 钩子；`platform` 指产品可移植性，而不是 CI 运行器选择；`build` 指编译、打包和已构建的包产物，而不是文档生成器。
-
-### 可扩展性
-
-领域集合有意保持可扩展。当分类体系缺少一个会反复涉及且具有实际意义的仓库领域时，就新增领域；不要仅为一项 PR、临时项目、状态、个人或团队新增标签。当领域模型发生变化时，重命名、拆分或退役相应领域，同时更新本列表以及所有受影响的开放和已合并 PR。
-
-类型集合保持精简，因为各类型互斥。新增类型的前提是存在一种当前五类无法表达的独立变更意图；类型不能用来替代领域。
+迁移标签时，须先保留语义，再移除别名：先添加规范替代标签并验证对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
 
 ## 曾考虑的替代方案
 
-- **一套不区分维度的标签。** 不予采纳，因为类型与领域回答的是不同问题；两者混在一起时，存在一个维度的标签并不表示另一个维度也经过了考虑。
-- **一套固定、封闭的领域集合。** 不予采纳，因为仓库领域会持续演变。封闭集合会以牺牲语义准确性为代价来维持拼写不变。
-- **一个宽泛的 `core` 领域，或从包结构派生的标签。** 不予采纳，因为 `session`、`llm` 和 `agent` 等领域在跨越包边界时仍各自具有意义，而偶然涉及的文件路径并不是评审人或自动化流程所需的范围信息。
-- **为浏览器和桌面端分别设置领域。** 不予采纳，因为浏览器交付和 Electron 打包共同呈现同一个图形客户端领域；拆开二者将按交付形态而非工作的语义进行分类。
-- **以宽泛的实现领域替代语义领域。** 不予采纳，因为持久化的定时作业不是后台任务，附件不只是其来源接口或文件系统实现，产物也不只是声明它的工具或预览接口。
-- **同一项契约同时使用总括领域与细分领域。** 不予采纳，因为重复标签只会虚增范围，不会增加信息。一项 PR 确实修改不同契约时，多个领域标签仍然合理。
-- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以合理地跨越多个领域；省略次要领域会隐藏受影响的契约。
+- **无前缀标签。** 不予采纳，因为扁平名称无法表明其表示的是意图、领域、来源、优先级还是自动化用途，而同义的无前缀和带前缀标签会使查询含义模糊。
+- **在仓库策略中使用固定的领域允许列表。** 不予采纳，因为持久的仓库领域会持续演变。`area/*` 命名空间仍可由机制识别，而实时描述负责承载可扩展的分类清单。
+- **在 Issue 上使用类型标签。** 不予采纳，因为原生 Issue Type 已负责这项分类；再用标签重复表示会产生漂移。
+- **从路径自动生成领域。** 不予采纳，因为领域描述跨越包边界的语义影响，而变更路径还会包含偶然涉及的测试、文档和支持文件。
+- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以对多个独立契约产生实质影响。
 
 ## 后果
 
-- 评审人和自动化流程获得一个稳定的意图信号，以及完整的语义范围。
-- `gui` 查询会同时覆盖浏览器与桌面端交付，`ui` 查询则只涵盖共享的跨接口契约。
-- `schedule`、`attachment` 与 `artifact` 查询直接对应各自领域，无需通过实现依赖近似归类。
-- 选择标签仍然需要判断：路径和标题前缀可以提示领域，但不能替代阅读变更内容。
-- 变更分类体系会产生维护工作。新增、重命名、拆分或移除领域时，需要更新本决策记录，并回填开放和已合并的 PR，使历史查询保持原有含义。
+评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发器。维护者必须阅读变更内容和实时标签描述，而不能根据标题前缀或路径推断分类；迁移分类体系还会产生明确的历史回填与验证成本。
diff --git a/AGENTS.md b/AGENTS.md
index 64f2e944a8..90b2ab4a67 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
-- **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([workflow](.agents/skills/dsh-labeling/SKILL.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

From a9abb62195f438c61b163fa2e9b8133b1523e4a9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:23:36 +0800
Subject: [PATCH 013/262] chore: enforce unified GitHub labels

---
 .github/dependabot.yml                   |   6 +-
 .github/issue-management/policy.mjs      |  43 +++++++++-
 .github/issue-management/policy.test.mjs | 100 ++++++++++++++++++++---
 AGENTS.md                                |   2 +-
 4 files changed, 132 insertions(+), 19 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 524d7912e2..dd91db8bf1 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -13,7 +13,7 @@ updates:
     cooldown:
       default-days: 30
     labels:
-      - "cleanup"
+      - "kind/dependency"
       - "area/infra"
 
   - package-ecosystem: "uv"
@@ -25,7 +25,7 @@ updates:
     cooldown:
       default-days: 30
     labels:
-      - "cleanup"
+      - "kind/dependency"
       - "area/infra"
 
   - package-ecosystem: "github-actions"
@@ -37,5 +37,5 @@ updates:
     cooldown:
       default-days: 30
     labels:
-      - "cleanup"
+      - "kind/dependency"
       - "area/infra"
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 608291c4f8..18a9b03628 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -12,6 +12,27 @@ const AUDIT_MARKER = '<!-- dsh-issue-policy -->'
 const OWNER_LINE = /^Owner: @([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)$/
 const TYPES = new Set(['Idea', 'Feature', 'Bug', 'Research', 'Task'])
 const PRIORITIES = ['p0', 'p1', 'p2', 'p3']
+const PR_KINDS = new Set([
+  'kind/feature',
+  'kind/bug-fix',
+  'kind/doc',
+  'kind/testing',
+  'kind/cleanup',
+  'kind/dependency',
+])
+const LEGACY_LABELS = new Set([
+  'kind/bug',
+  'kind/documentation',
+  'bug-fix',
+  'doc',
+  'cleanup',
+  'testing',
+  'dependencies',
+  'ci',
+  'cli',
+  'llm',
+  'web-search',
+])
 const TERMINAL_STATUSES = new Set(['Done', 'No action'])
 const ACTIVE_STATUS_ORDER = config.statuses.filter((status) => !TERMINAL_STATUSES.has(status))
 
@@ -224,8 +245,14 @@ export function retainIssueReferences(references, issues) {
 export function validateIssue(issue) {
   const errors = validateBody(issue)
   const status = issue.status
+  const invalidLabels = issue.labels.filter(
+    (label) => label.startsWith('kind/') || LEGACY_LABELS.has(label),
+  )
 
   if (!/\p{Script=Han}/u.test(issue.title)) errors.push('Issue 标题必须包含中文')
+  if (invalidLabels.length > 0) {
+    errors.push(`Issue 不得使用 PR kind 或旧版标签：${invalidLabels.join(', ')}`)
+  }
   if (
     /^\s*(?:\[(?:Idea|Feature|Bug|Research|Task|P[0-3]|Inbox|Backlog|Ready|In progress|In review|Done|No action|Owner|area\/[^\]]+)[^\]]*\]|(?:Idea|Feature|Bug|Research|Task|P[0-3]|Inbox|Backlog|Ready|In progress|In review|Done|No action|Owner|area\/[^:： ]+)\s*[:：-])/iu.test(
       issue.title,
@@ -261,12 +288,24 @@ export function validateIssue(issue) {
 export function validatePullRequest(input) {
   if (!requiresPullRequestPolicy(input)) return []
   const errors = []
-  const kinds = input.labels.filter((label) => label.startsWith('kind/'))
+  const kinds = input.labels.filter((label) => PR_KINDS.has(label))
+  const unknownKinds = input.labels.filter(
+    (label) => label.startsWith('kind/') && !PR_KINDS.has(label) && !LEGACY_LABELS.has(label),
+  )
+  const legacyLabels = input.labels.filter((label) => LEGACY_LABELS.has(label))
+  const sourceLabels = input.labels.filter((label) => label.startsWith('source/'))
   const priorities = input.labels.filter((label) => PRIORITIES.includes(label))
   const areas = input.labels.filter((label) => label.startsWith('area/'))
 
   if (input.references.all.length === 0) errors.push('PR 正文必须引用至少一个同仓库 Issue')
-  if (kinds.length !== 1) errors.push(`PR 必须恰好有一个 kind/*，当前为 ${kinds.length}`)
+  if (kinds.length !== 1) {
+    errors.push(`PR 必须恰好有一个允许的 kind/*，当前为 ${kinds.length}`)
+  }
+  if (unknownKinds.length > 0) {
+    errors.push(`PR 含不支持的 kind/*：${unknownKinds.join(', ')}`)
+  }
+  if (legacyLabels.length > 0) errors.push(`PR 含旧版标签：${legacyLabels.join(', ')}`)
+  if (sourceLabels.length > 0) errors.push(`source/* 仅用于 Issue：${sourceLabels.join(', ')}`)
   if (priorities.length > 1) errors.push(`PR 最多有一个 p0–p3，当前为 ${priorities.length}`)
   if (areas.length === 0) errors.push('PR 必须至少有一个 area/*')
   for (const number of input.references.all) {
diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs
index 86750127a7..bcaf450afa 100644
--- a/.github/issue-management/policy.test.mjs
+++ b/.github/issue-management/policy.test.mjs
@@ -27,6 +27,25 @@ const legalIssue = {
   stateReason: null,
 }
 
+const canonicalKinds = [
+  'kind/feature',
+  'kind/bug-fix',
+  'kind/doc',
+  'kind/testing',
+  'kind/cleanup',
+  'kind/dependency',
+]
+
+const reviewedPull = (labels) => ({
+  isDraft: false,
+  authorType: 'User',
+  reviewRequestCount: 1,
+  reviewCount: 0,
+  labels,
+  references: { all: [2], resolving: [], related: [2] },
+  issues: new Map([[2, { priority: null }]]),
+})
+
 test('counts only text outside details', () => {
   assert.deepEqual(countVisibleUnits('支持 GitHub Project。<details>隐藏文字</details>'), {
     units: 4,
@@ -92,6 +111,32 @@ test('rejects metadata prefixes in an Issue title', () => {
   assert.ok(errors.includes('Issue 标题不得带 Type、Priority、Status、area 或 Owner 前缀'))
 })
 
+test('reserves PR kind and legacy labels for pull requests', () => {
+  for (const label of [
+    ...canonicalKinds,
+    'kind/experimental',
+    'kind/bug',
+    'kind/documentation',
+    'bug-fix',
+    'doc',
+    'cleanup',
+    'testing',
+    'dependencies',
+    'ci',
+    'cli',
+    'llm',
+    'web-search',
+  ]) {
+    assert.ok(
+      validateIssue({ ...legalIssue, labels: [label] }).some((error) =>
+        error.startsWith('Issue 不得使用 PR kind 或旧版标签：'),
+      ),
+      label,
+    )
+  }
+  assert.deepEqual(validateIssue({ ...legalIssue, labels: ['area/web', 'source/member'] }), [])
+})
+
 test('keeps terminal Status aligned with the native close reason', () => {
   assert.deepEqual(
     validateIssue({ ...legalIssue, status: 'Done', state: 'closed', stateReason: 'completed' }),
@@ -260,22 +305,51 @@ test('requires repository PR labels in the enforcement scope', () => {
     references: { all: [2], resolving: [], related: [2] },
     issues: new Map([[2, { priority: null }]]),
   })
-  assert.ok(errors.includes('PR 必须恰好有一个 kind/*，当前为 0'))
+  assert.ok(errors.includes('PR 必须恰好有一个允许的 kind/*，当前为 0'))
   assert.ok(errors.includes('PR 必须至少有一个 area/*'))
 })
 
-test('accepts repository-extensible kind labels', () => {
-  assert.deepEqual(
-    validatePullRequest({
-      isDraft: false,
-      authorType: 'User',
-      reviewRequestCount: 1,
-      reviewCount: 0,
-      labels: ['kind/dependency', 'area/infra'],
-      references: { all: [2], resolving: [], related: [2] },
-      issues: new Map([[2, { priority: null }]]),
-    }),
-    [],
+test('accepts exactly the canonical kinds with extensible areas', () => {
+  for (const kind of canonicalKinds) {
+    assert.deepEqual(validatePullRequest(reviewedPull([kind, 'area/future-domain'])), [], kind)
+  }
+})
+
+test('rejects multiple, unknown, legacy, and Issue-source PR labels', () => {
+  assert.ok(
+    validatePullRequest(
+      reviewedPull(['kind/feature', 'kind/doc', 'area/web']),
+    ).includes('PR 必须恰好有一个允许的 kind/*，当前为 2'),
+  )
+  assert.ok(
+    validatePullRequest(reviewedPull(['kind/experimental', 'area/web'])).includes(
+      'PR 含不支持的 kind/*：kind/experimental',
+    ),
+  )
+  for (const label of [
+    'kind/bug',
+    'kind/documentation',
+    'bug-fix',
+    'doc',
+    'cleanup',
+    'testing',
+    'dependencies',
+    'ci',
+    'cli',
+    'llm',
+    'web-search',
+  ]) {
+    assert.ok(
+      validatePullRequest(reviewedPull(['kind/feature', 'area/web', label])).some((error) =>
+        error.startsWith('PR 含旧版标签：'),
+      ),
+      label,
+    )
+  }
+  assert.ok(
+    validatePullRequest(
+      reviewedPull(['kind/feature', 'area/web', 'source/internal-pr']),
+    ).includes('source/* 仅用于 Issue：source/internal-pr'),
   )
 })
 
diff --git a/AGENTS.md b/AGENTS.md
index 90b2ab4a67..9344e2e6e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
-- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([workflow](.agents/skills/dsh-labeling/SKILL.md)).
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

From 07ac5e6d4cbf06e5078e73844e38e97684788a75 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:00:10 +0800
Subject: [PATCH 014/262] fix(labels): address taxonomy review findings

---
 .../2026-07-25-semantic-pr-label-taxonomy.md  | 56 ---------------
 ...026-07-25-semantic-pr-label-taxonomy.zh.md | 56 ---------------
 ...07-27-dependabot-version-updates.i18n.yaml |  4 +-
 .../2026-07-27-dependabot-version-updates.md  |  2 +-
 ...026-07-27-dependabot-version-updates.zh.md |  2 +-
 ...8-unified-github-label-taxonomy.i18n.yaml} |  6 +-
 ...026-08-08-unified-github-label-taxonomy.md | 72 +++++++++++++++++++
 ...-08-08-unified-github-label-taxonomy.zh.md | 72 +++++++++++++++++++
 .github/issue-management/policy.mjs           |  2 +
 .github/issue-management/policy.test.mjs      | 42 +++++------
 AGENTS.md                                     |  2 +-
 11 files changed, 172 insertions(+), 144 deletions(-)
 delete mode 100644 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
 delete mode 100644 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
 rename .agents/notes/implemented/process/{2026-07-25-semantic-pr-label-taxonomy.i18n.yaml => 2026-08-08-unified-github-label-taxonomy.i18n.yaml} (56%)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md

diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
deleted file mode 100644
index 6aef5ecbb8..0000000000
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Agent Note: Semantic pull request label taxonomy
-
-Status: implemented
-
-English | [中文](2026-07-25-semantic-pr-label-taxonomy.zh.md)
-
-## Problem
-
-Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or keeping synonymous labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
-
-Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each label family.
-
-## Decision
-
-Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
-
-### Kinds
-
-The kind set is closed and mutually exclusive:
-
-| Kind | Meaning |
-|---|---|
-| `kind/feature` | Adds or intentionally changes behavior. |
-| `kind/bug-fix` | Corrects incorrect behavior. |
-| `kind/doc` | Makes documentation the dominant intent. |
-| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
-| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
-| `kind/dependency` | Updates dependencies without another dominant intent. |
-
-The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix.
-
-### Areas
-
-Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory.
-
-The area set is intentionally extensible. When no existing description honestly covers a durable and reusable repository domain, an agent is empowered to create a concise `area/<lowercase-kebab-case>` label without separate approval. The agent must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and must report the new label after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
-
-Kinds are not extended this way. A new kind changes the mutually exclusive classification contract and requires an explicit taxonomy change with corresponding policy enforcement.
-
-### Issues and operational labels
-
-Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
-
-Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
-
-## Alternatives considered
-
-- **Unprefixed labels.** Rejected because a flat name does not identify whether it classifies intent, domain, source, priority, or automation, and synonymous plain and prefixed labels caused ambiguous queries.
-- **A fixed area allowlist in repository policy.** Rejected because durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
-- **Kinds on Issues.** Rejected because native Issue Type already owns that classification; duplicating it as a label creates drift.
-- **Automatic areas from paths.** Rejected because areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
-- **Exactly one area per pull request.** Rejected because coherent changes can materially affect several independent contracts.
-
-## Consequences
-
-Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and live label descriptions rather than infer classification from title prefixes or paths, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
deleted file mode 100644
index 0bd3fbcaec..0000000000
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Agent Note: 语义化 PR 标签分类体系
-
-Status: implemented
-
-[English](2026-07-25-semantic-pr-label-taxonomy.md) | 中文
-
-## 问题
-
-PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度或保留同义标签会使查询含义模糊，而封闭的领域清单会迫使新领域被归入不准确的类别。
-
-Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
-
-## 决策
-
-每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个受到实质影响的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
-
-### 类型
-
-类型集合封闭且互斥：
-
-| 类型 | 含义 |
-|---|---|
-| `kind/feature` | 新增行为或有意改变行为。 |
-| `kind/bug-fix` | 修正错误行为。 |
-| `kind/doc` | 以文档变更为主要意图。 |
-| `kind/testing` | 修改测试或测试基础设施，但不改变产品行为。 |
-| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
-| `kind/dependency` | 在没有其他主要意图时更新依赖。 |
-
-类型记录主要意图。配套测试、文档、清理或依赖调整不会覆盖一项功能或缺陷修复的主要意图。
-
-### 领域
-
-领域表示持久的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。当前分类清单以 GitHub 上实时的 `area/*` 名称和描述为准。
-
-领域集合有意保持可扩展。当现有描述都无法准确涵盖一个持久且可复用的仓库领域时，agent（智能体）有权无须另行批准，直接创建简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后报告。仅为避免新增一个确有必要的标签而复用不准确的领域，不可接受。
-
-类型不以这种方式扩展。新增类型会改变互斥的分类契约，必须明确修改分类体系并同步调整策略强制校验。
-
-### Issue 与管理用途标签
-
-Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍为可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
-
-迁移标签时，须先保留语义，再移除别名：先添加规范替代标签并验证对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
-
-## 曾考虑的替代方案
-
-- **无前缀标签。** 不予采纳，因为扁平名称无法表明其表示的是意图、领域、来源、优先级还是自动化用途，而同义的无前缀和带前缀标签会使查询含义模糊。
-- **在仓库策略中使用固定的领域允许列表。** 不予采纳，因为持久的仓库领域会持续演变。`area/*` 命名空间仍可由机制识别，而实时描述负责承载可扩展的分类清单。
-- **在 Issue 上使用类型标签。** 不予采纳，因为原生 Issue Type 已负责这项分类；再用标签重复表示会产生漂移。
-- **从路径自动生成领域。** 不予采纳，因为领域描述跨越包边界的语义影响，而变更路径还会包含偶然涉及的测试、文档和支持文件。
-- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以对多个独立契约产生实质影响。
-
-## 后果
-
-评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发器。维护者必须阅读变更内容和实时标签描述，而不能根据标题前缀或路径推断分类；迁移分类体系还会产生明确的历史回填与验证成本。
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml
index 316c31771e..dea250de53 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.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 .agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
-2026-07-27-dependabot-version-updates.md: 5d42563788d9f1e72da65c8e9750d6b1ecba06a5
-2026-07-27-dependabot-version-updates.zh.md: 4847059944e7e35de5719a6cbfd3d5b133467ccb
+2026-07-27-dependabot-version-updates.md: bba83c9e720cf87f91638131d7f9580422ea7f76
+2026-07-27-dependabot-version-updates.zh.md: 74b399778fdd06cbbe38234f7bddc5c28c4fd600
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
index 5d42563788..bba83c9e72 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
@@ -12,7 +12,7 @@ Maintained registry and GitHub Actions dependencies need a regular update path.
 
 The default branch carries [`.github/dependabot.yml`](../../../../.github/dependabot.yml) with weekly version-update checks for the root pnpm workspace, including `native/landlock-run`, the `python/sdk` uv project, and GitHub Actions. Every entry sets `cooldown.default-days` to `30`, so a version release becomes eligible only after it is at least 30 days old and is proposed on the next weekly check. The [in-repository Landlock release decision](2026-08-06-in-repository-landlock-release.md) owns the shared-workspace boundary.
 
-The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `cleanup` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
+The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `kind/dependency` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
 
 Repository settings enable dependency vulnerability alerts and Dependabot security updates. GitHub does not apply version-update cooldowns to those security updates, so security fixes remain eligible immediately. A generated pnpm security pull request can still fail the repository's lockfile release-age verification when dependency resolution selects unrelated fresh transitive versions; that pull request waits or is narrowed instead of weakening the policy. The repository's coordinated fresh-release exceptions are not copied into Dependabot's cooldown exclusions: automated version updates use the uniform 30-day wait, while an explicitly reviewed manual update can still follow its owning release procedure.
 
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
index 4847059944..74b399778f 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 默认分支包含 [`.github/dependabot.yml`](../../../../.github/dependabot.yml)，其中为包含 `native/landlock-run` 的根 pnpm 工作区、`python/sdk` uv 项目和 GitHub Actions 配置了每周一次的版本更新检查。每个更新项都将 `cooldown.default-days` 设为 `30`，因此某个版本只有在发布至少 30 天后才符合更新条件，并会在下一次每周检查时生成更新提案。[仓库内 Landlock 发布决策](2026-08-06-in-repository-landlock-release.md)负责共享工作区边界。
 
-根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `cleanup` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
+根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `kind/dependency` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
 
 仓库设置已启用依赖项漏洞警报和 Dependabot 安全更新。GitHub 不会对这些安全更新应用版本更新冷却期，因此安全修复仍可立即进入更新流程。如果依赖解析还选中了其他刚发布的传递依赖，pnpm 安全更新 PR 仍可能无法通过仓库的锁文件发布时长校验；此类 PR 应等待隔离期结束或缩小更新范围，不得因此放宽政策。仓库为协调刚发布版本而设置的例外，不会纳入 Dependabot 的冷却期排除项：自动版本更新统一等待 30 天；经过明确评审的手动更新仍可遵循相应的发布流程。
 
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
similarity index 56%
rename from .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
rename to .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
index a83236521c..5ee57b914f 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
@@ -1,6 +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 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
-2026-07-25-semantic-pr-label-taxonomy.md: 6aef5ecbb80005d1fcd90b4ee673bbbebb92cba6
-2026-07-25-semantic-pr-label-taxonomy.zh.md: 0bd3fbcaeca37fa894e92ce5a4e78c4125056ac9
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
+2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
+2026-08-08-unified-github-label-taxonomy.zh.md: c8d727c9a56d6c7c25f73eacde42e0bef1c779b7
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
new file mode 100644
index 0000000000..fddda6c990
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
@@ -0,0 +1,72 @@
+# Agent Note: Unified GitHub label taxonomy
+
+Status: implemented
+
+English | [中文](2026-08-08-unified-github-label-taxonomy.zh.md)
+
+## Problem
+
+Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or retaining synonymous plain and namespaced labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
+
+Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each family.
+
+## Decision
+
+Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
+
+### Kinds
+
+The kind set is closed and mutually exclusive:
+
+| Kind | Meaning |
+|---|---|
+| `kind/feature` | Adds or intentionally changes behavior. |
+| `kind/bug-fix` | Corrects incorrect behavior. |
+| `kind/doc` | Makes documentation the dominant intent. |
+| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
+| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
+| `kind/dependency` | Updates dependencies without another dominant intent. |
+
+The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix. A new kind changes this classification contract and requires an explicit taxonomy and policy change.
+
+Repository policy rejects unsupported `kind/*` values and reserves every alias removed by the unification: `kind/bug`, `kind/documentation`, `feature`, `bug-fix`, `doc`, `cleanup`, `testing`, `dependencies`, `ci`, `cli`, `llm`, and `web-search`. Reserving the exact migrated set prevents an obsolete synonym from being recreated as an apparently unrelated operational label.
+
+### Areas
+
+Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory; this record owns the selection rule and the non-obvious boundaries that cannot fit reliably in short label descriptions.
+
+- `area/web` covers browser and Electron graphical interfaces, `area/vscode` covers the editor extension, and `area/api` covers cross-interface protocols and language SDKs.
+- `area/planning` covers goals, plans, todos, and scheduling, while `area/workflow` covers executable workflows and background task runtimes.
+- `area/artifact` deliberately combines artifacts, attachments, and multimodal delivery. Split labels become justified only when those concerns again need independent review or queries.
+- `area/tools` applies to generic registry, schema, and execution contracts. A concrete capability uses its own area unless it also changes that generic contract.
+- `area/hooks` means the Claude Code and Codex bridges, `area/infra` covers build, release, CI, repository gates, generators, dependencies, and developer tooling, and `area/windows` covers native Windows product support rather than CI runner selection.
+
+The area set is intentionally extensible. When no existing description honestly covers a durable and reusable domain, an agent may create a concise `area/<lowercase-kebab-case>` label without separate approval. It must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and it reports the new label and rationale to the requester after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
+
+### Issues and migrations
+
+Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
+
+Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
+
+## Alternatives considered
+
+**Unprefixed labels.** Plain names reduce visual noise, but they do not identify whether a label classifies intent, domain, source, priority, or automation. Retaining both plain and namespaced synonyms also makes queries and policy enforcement ambiguous.
+
+**One undifferentiated label set.** A label's presence would not prove that both intent and semantic scope were considered.
+
+**A fixed area allowlist in repository policy.** Durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
+
+**Package- or path-derived areas.** Areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
+
+**Separate labels for every delivery shell or media lifecycle.** Browser and Electron delivery share one graphical domain, and artifact, attachment, and multimodal delivery currently share one review/query domain. A split belongs in a later taxonomy change only when it restores useful independent classification.
+
+**Broad implementation labels in place of semantic domains.** A concrete capability is not merely its tool, interface, filesystem, or process implementation. Generic implementation areas apply only when their own contracts change.
+
+**Kinds on Issues.** Native Issue Type already owns that classification; duplicating it as a label creates drift.
+
+**Exactly one area per pull request.** Coherent changes can materially affect several independent contracts, and dropping secondary areas hides affected scope.
+
+## Consequences
+
+Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
new file mode 100644
index 0000000000..c8d727c9a5
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
@@ -0,0 +1,72 @@
+# Agent Note: 统一 GitHub 标签分类体系
+
+Status: implemented
+
+[English](2026-08-08-unified-github-label-taxonomy.md) | 中文
+
+## 问题
+
+PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度，或同时保留同义的无前缀标签与带命名空间的标签，都会使查询含义模糊；封闭的领域清单则会迫使新领域归入不准确的类别。
+
+Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
+
+## 决策
+
+每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个表示实质受影响领域的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
+
+### 变更类型
+
+类型集合封闭且互斥：
+
+| 变更类型 | 含义 |
+|---|---|
+| `kind/feature` | 新增行为或有意改变行为。 |
+| `kind/bug-fix` | 修正错误行为。 |
+| `kind/doc` | 以文档变更为主导意图。 |
+| `kind/testing` | 在不改变产品行为的前提下修改测试或测试基础设施。 |
+| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
+| `kind/dependency` | 在没有其他主导意图时更新依赖。 |
+
+类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类契约，因此必须明确修改分类体系和政策。
+
+仓库政策会拒绝不支持的 `kind/*` 值，并将统一过程中移除的所有别名列为保留名称：`kind/bug`、`kind/documentation`、`feature`、`bug-fix`、`doc`、`cleanup`、`testing`、`dependencies`、`ci`、`cli`、`llm` 和 `web-search`。精确保留这组已迁移的名称，可以防止过时的同义名称被重新创建成看似无关的管理用途标签。
+
+### 领域
+
+领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
+
+- `area/web` 覆盖浏览器与 Electron 图形界面，`area/vscode` 覆盖编辑器扩展，`area/api` 覆盖跨界面协议与各语言 SDK。
+- `area/planning` 覆盖目标、计划、待办和调度，`area/workflow` 则覆盖可执行工作流与后台任务运行时。
+- `area/artifact` 有意合并产物、附件与多模态交付。只有当这些关注点再次需要独立评审或查询时，才有理由拆分标签。
+- `area/tools` 适用于通用注册表、schema 与执行契约。具体能力使用自身的领域标签，除非它还修改了这项通用契约。
+- `area/hooks` 表示 Claude Code 与 Codex 桥接，`area/infra` 覆盖构建、发布、CI、仓库门禁、生成器、依赖与开发者工具，`area/windows` 覆盖原生 Windows 产品支持，而不是 CI runner 的选型。
+
+领域集合有意保持可扩展。当现有说明都无法如实涵盖一个持久且可复用的领域时，agent（智能体）无需另行批准，即可创建一个简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后向请求者报告该标签及理由。仅为避免新增一个确有必要的领域标签而复用不准确的领域，不可接受。
+
+### Issue 与迁移
+
+Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
+
+迁移标签时，须先保留语义，再移除别名：先添加规范替代标签，核验可加标签对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
+
+## 考虑过的替代方案
+
+**无前缀标签。** 无前缀名称可以减少视觉噪声，但无法表明标签分类的是意图、领域、来源、优先级还是自动化用途。同时保留无前缀和带命名空间的同义标签，也会使查询和政策执行含义模糊。
+
+**不区分维度的单一标签集合。** 某个标签存在，并不能证明意图和语义范围都经过了考虑。
+
+**仓库政策中的固定领域允许清单。** 持久的仓库领域会演进。`area/*` 命名空间仍可机械识别，而现行说明承载可扩展清单。
+
+**按包或路径派生的领域。** 领域描述跨越包边界的语义影响，而变更路径会包含偶然涉及的测试、文档和支持文件。
+
+**为每种交付载体或媒体生命周期单设标签。** 浏览器与 Electron 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
+
+**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身契约变化时适用。
+
+**在 Issue 上使用类型标签。** 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
+
+**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立契约产生实质影响，丢弃次要领域会隐藏受影响范围。
+
+## 后果
+
+评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 18a9b03628..09e1bbe7fd 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -20,9 +20,11 @@ const PR_KINDS = new Set([
   'kind/cleanup',
   'kind/dependency',
 ])
+// Aliases removed by the unified taxonomy migration remain reserved so they cannot be recreated.
 const LEGACY_LABELS = new Set([
   'kind/bug',
   'kind/documentation',
+  'feature',
   'bug-fix',
   'doc',
   'cleanup',
diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs
index bcaf450afa..8a9b0f91e6 100644
--- a/.github/issue-management/policy.test.mjs
+++ b/.github/issue-management/policy.test.mjs
@@ -36,6 +36,22 @@ const canonicalKinds = [
   'kind/dependency',
 ]
 
+// Keep an independent oracle rather than importing the implementation's reserved set.
+const legacyLabels = [
+  'kind/bug',
+  'kind/documentation',
+  'feature',
+  'bug-fix',
+  'doc',
+  'cleanup',
+  'testing',
+  'dependencies',
+  'ci',
+  'cli',
+  'llm',
+  'web-search',
+]
+
 const reviewedPull = (labels) => ({
   isDraft: false,
   authorType: 'User',
@@ -115,17 +131,7 @@ test('reserves PR kind and legacy labels for pull requests', () => {
   for (const label of [
     ...canonicalKinds,
     'kind/experimental',
-    'kind/bug',
-    'kind/documentation',
-    'bug-fix',
-    'doc',
-    'cleanup',
-    'testing',
-    'dependencies',
-    'ci',
-    'cli',
-    'llm',
-    'web-search',
+    ...legacyLabels,
   ]) {
     assert.ok(
       validateIssue({ ...legalIssue, labels: [label] }).some((error) =>
@@ -326,19 +332,7 @@ test('rejects multiple, unknown, legacy, and Issue-source PR labels', () => {
       'PR 含不支持的 kind/*：kind/experimental',
     ),
   )
-  for (const label of [
-    'kind/bug',
-    'kind/documentation',
-    'bug-fix',
-    'doc',
-    'cleanup',
-    'testing',
-    'dependencies',
-    'ci',
-    'cli',
-    'llm',
-    'web-search',
-  ]) {
+  for (const label of legacyLabels) {
     assert.ok(
       validatePullRequest(reviewedPull(['kind/feature', 'area/web', label])).some((error) =>
         error.startsWith('PR 含旧版标签：'),
diff --git a/AGENTS.md b/AGENTS.md
index 9344e2e6e2..928a118868 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
-- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md)).
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

From 702e2d024a0f6957c785b6f597a28ee53da458aa Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:29:43 +0800
Subject: [PATCH 015/262] fix(windows): canonicalize native watch paths

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  4 ++
 ...08-08-native-windows-pull-request-ci.zh.md |  4 ++
 .../credentials-local/README.i18n.yaml        |  4 +-
 .../credentials/credentials-local/README.md   |  2 +-
 .../credentials-local/README.zh.md            |  2 +-
 .../credentials-local/src/index.ts            |  4 +-
 .../settings/settings-local/README.i18n.yaml  |  4 +-
 packages/settings/settings-local/README.md    |  1 +
 packages/settings/settings-local/README.zh.md |  1 +
 packages/settings/settings-local/src/index.ts |  4 +-
 packages/ui/app-boot/tests/hmr-config.spec.ts | 46 +++++++++++++++++--
 packages/util/paths/README.i18n.yaml          |  4 +-
 packages/util/paths/README.md                 |  6 ++-
 packages/util/paths/README.zh.md              |  6 ++-
 packages/util/paths/src/index.ts              | 30 +++++++++++-
 packages/util/paths/tests/paths.spec.ts       | 22 ++++++++-
 scripts/project-doc-site.spec.ts              |  6 +--
 vendor/README.md                              |  2 +-
 vendor/hmr/README.md                          |  6 +++
 vendor/hmr/src/index.ts                       | 31 ++++++++-----
 21 files changed, 157 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 3b3d2dc1dd..c9d06abacf 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 926eec04cff63aaf25d1e85b3dcbc41464f25660
-2026-08-08-native-windows-pull-request-ci.zh.md: 8728f0eb08adcb1501f036bb19ff523ded406ccc
+2026-08-08-native-windows-pull-request-ci.md: 8b6766cfa8df48c6c61410c06a410340a0c9bb21
+2026-08-08-native-windows-pull-request-ci.zh.md: 29cb1f725f4212c13974d642388edaf1df16b759
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 926eec04cf..8b6766cfa8 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -14,6 +14,8 @@ The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) run
 
 The aggregate keeps workspace build and production-site failures blocking while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
+The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
+
 Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
 
 ## Alternatives considered
@@ -30,4 +32,6 @@ Wine-only infrastructure is absent from the supported workflow: there is no apt-
 
 Pull requests receive a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal before the aggregate can pass. The job is slower than the Wine compatibility lane and can queue on Windows capacity, but its green result now describes the supported host rather than an approximation.
 
+The native lane is also a portability inventory: its exact-head acceptance requires every blocking gate to pass and the final summary to contain no non-blocking failure. That distinction caught path contracts which a successful wrapper conclusion alone would have concealed.
+
 Removing the Wine cache producer and local script deletes a separate install topology and its recurring compatibility failures. Native coverage and snapshots remain a named gap rather than being implied by the job name; they require their own tested contract before becoming part of this required lane.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 8728f0eb08..29cb1f725f 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -14,6 +14,8 @@ Status: implemented
 
 聚合作业继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
+首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
+
 受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
 
 ## 曾考虑的替代方案
@@ -30,4 +32,6 @@ Status: implemented
 
 在聚合作业通过之前，拉取请求会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。该作业比 Wine 兼容性通道更慢，也可能因 Windows 容量而排队，但其绿灯结果描述的是受支持的宿主，而非近似环境。
 
+原生通道也是一份可移植性清单：其分支头精确验收要求每个阻断门禁都通过，且最终汇总中不包含任何非阻断失败。这一区分发现了路径契约问题；若只看包装层的成功结论，这些问题本会被掩盖。
+
 移除 Wine 缓存生产者和本地脚本后，独立的安装拓扑及其反复出现的兼容性故障也随之消失。原生 Windows 覆盖率与快照仍是明确列出的缺口，不会仅由作业名称暗示已经纳入；二者都必须先建立各自经过测试的契约，才能成为该必需通道的一部分。
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 07a3efd5c3..66ad77f648 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-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/credentials/credentials-local/README.md
-README.md: 8e95a890a8e38172cf8984653a01c59570f0061a
-README.zh.md: 04ad07ae4e703ab0416d1d8f1bb6a6ff90adf337
+README.md: 035d558d8cbd51ce46af72d7bd9cd56bed85ebcd
+README.zh.md: 11c772951dab3ce0cea3a13e739198d41028d598
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 8e95a890a8..035d558d8c 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -47,7 +47,7 @@ The provider creates the directory `0700` and creates or atomically replaces the
 
 ## Hot reload
 
-External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
+External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix; file access and diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form libuv events. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
 
 ## Security boundary
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 04ad07ae4e..11c772951d 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -47,7 +47,7 @@ OPENAI_API_KEY: sk-…
 
 ## 热重载
 
-外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀；文件访问和诊断仍使用配置路径，从而避免 Windows 混用 8.3 别名与 libuv 的长格式事件路径。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
 
 ## 安全边界
 
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index e781c10f3e..67b598d7e0 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -41,7 +41,7 @@ import { mkdir, readFile, stat } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { Document, parseDocument, type YAMLError } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
 import { Credentials, credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
@@ -270,7 +270,7 @@ export class CredentialsLocal extends Credentials {
     /* jscpd:ignore-start -- same watcher discipline as settings-local by design:
        the serialized-refresh and quiesce-on-dispose shape is the reviewed
        lifecycle contract, not accidental repetition. */
-    const watcher = chokidarWatch(this.spec.filename, {
+    const watcher = chokidarWatch(await canonicalizeWatchPath(this.spec.filename), {
       ignoreInitial: true,
       awaitWriteFinish: {
         stabilityThreshold: this.spec.debounceMs,
diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml
index ec26e4241f..188e4361bb 100644
--- a/packages/settings/settings-local/README.i18n.yaml
+++ b/packages/settings/settings-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/settings/settings-local/README.md
-README.md: d1f3d755f9073acdf6fcfc5d1de883d74cc023c4
-README.zh.md: 03c7ef7c35312d9e1e4a86b0df71412875af7d6c
+README.md: a0bc94630f78aa7c101e3eb0795a7d07e585e347
+README.zh.md: 2d2d0828f2eadde9867ab91fe8fbd4c61dea4c11
diff --git a/packages/settings/settings-local/README.md b/packages/settings/settings-local/README.md
index d1f3d755f9..a0bc94630f 100644
--- a/packages/settings/settings-local/README.md
+++ b/packages/settings/settings-local/README.md
@@ -24,6 +24,7 @@ Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension
 - **YAML edits are leaf-level diffs.** A write sets only the values that changed and deletes only the keys that were removed, so comments, anchors, and formatting survive on every untouched node and on the key of every changed pair; a changed array (or other non-map value) replaces wholesale, taking comments inside it along. JSON re-serializes without comments.
 - **Reloads and writes share one operation chain.** Watcher refreshes and persists from every namespace queue run one at a time in queue order; each render sees the text the previous operation committed.
 - **The watcher's ready signal reconciles once.** The initial load races the watcher's own setup, so a change written in between never fires an event; the reconcile at ready closes that startup gap.
+- **The native watcher receives a canonical path.** Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix. File access and user-facing diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form event paths inside libuv.
 - **Dispose quiesces in every watch mode.** Teardown marks the provider closed, closes the watcher when present, then waits out every queued or in-flight document operation, so nothing publishes after disposal.
 - **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op.
 - **Host configuration adapters receive the resolved path.** `ctx.settings.documentPath` is the absolute `resolveSpec()` filename, including a custom YAML/JSON path; `prepareDocument()` preserves an existing file or exclusively creates an absent empty file with owner-only permissions before the Host opens it. The browser receives only an availability flag, never reconstructs `$DSH_HOME`, and never submits a filesystem target.
diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md
index 03c7ef7c35..2d2d0828f2 100644
--- a/packages/settings/settings-local/README.zh.md
+++ b/packages/settings/settings-local/README.zh.md
@@ -24,6 +24,7 @@
 - **YAML 编辑是叶子级 diff。** 写入只设置发生变化的值、只删除被移除的键，因此注释、锚点与排版在每个未触碰的节点上以及每个被改键值对的键上都得以保留；被改的数组（或其他非 map 值）整体替换，其中的注释随之一同被换掉。JSON 重新序列化，无注释。
 - **重载与写入共享一条操作链。** watcher 刷新与来自各 namespace 队列的 persist 按队列顺序逐个执行；每次渲染都基于上一次操作提交后的文本。
 - **watcher 的 ready 信号做一次对账。** 初始加载与 watcher 自身的建立存在竞态，因此其间写入的变更绝不会触发事件；ready 时的对账补上这个启动缺口。
+- **原生 watcher 接收规范化路径。** 在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀。文件访问和面向用户的诊断仍使用配置路径，从而避免 Windows 在 libuv 内部混用 8.3 别名与长格式事件路径。
 - **Dispose 在每种 watch 模式下都保证静止。** 卸载先把提供方标记为已关闭，在 watcher 存在时将其关闭，再等待所有已排队或进行中的文档操作完成，之后不再有任何发布。
 - **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
 - **Host 配置适配器会收到解析后的路径。** `ctx.settings.documentPath` 是 `resolveSpec()` 得出的绝对文件名，包括自定义 YAML/JSON 路径；`prepareDocument()` 会保留现有文件，或在 Host 打开文档前，以仅属主可访问的权限独占创建缺失的空文件。浏览器只收到可用性标志，绝不重建 `$DSH_HOME`，也绝不提交文件系统目标。
diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts
index 0ce07af40c..16bc641f05 100644
--- a/packages/settings/settings-local/src/index.ts
+++ b/packages/settings/settings-local/src/index.ts
@@ -14,7 +14,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, extname, join, resolve } from 'node:path'
 import { Document, parseDocument } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { Settings, deepEqualJson, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 
 /** Plugin config: file location and hot-reload behavior. */
@@ -235,7 +235,7 @@ export class SettingsLocal extends Settings {
     // silently ignored or overwritten.
     yield* super[Service.init]()
     const watcher = this.spec.watch
-      ? chokidarWatch(this.spec.filename, {
+      ? chokidarWatch(await canonicalizeWatchPath(this.spec.filename), {
         ignoreInitial: true,
         awaitWriteFinish: {
           stabilityThreshold: this.spec.debounceMs,
diff --git a/packages/ui/app-boot/tests/hmr-config.spec.ts b/packages/ui/app-boot/tests/hmr-config.spec.ts
index 1892a6e73a..fe6bb556b4 100644
--- a/packages/ui/app-boot/tests/hmr-config.spec.ts
+++ b/packages/ui/app-boot/tests/hmr-config.spec.ts
@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -8,12 +8,12 @@ import Loader from '@cordisjs/plugin-loader'
 import Timer from '@cordisjs/plugin-timer'
 import { describe, expect, it } from 'vitest'
 
-async function bootHmr(dir: string): Promise<Context> {
+async function bootHmr(dir: string, root: string[] = []): Promise<Context> {
   const ctx = new Context()
   ctx.baseUrl = pathToFileURL(dir).href + '/'
   await ctx.plugin(Loader)
   await ctx.plugin(Timer)
-  await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0 })
   return ctx
 }
 
@@ -26,6 +26,46 @@ async function eventually(test: () => boolean, message: string): Promise<void> {
 }
 
 describe('HMR exact config paths', () => {
+  it('observes module changes when its watch base is a filesystem alias', { timeout: 20_000 }, async () => {
+    const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-module-canonical-'))
+    const alias = `${target}-alias`
+    const filename = join(alias, 'module.ts')
+    symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    writeFileSync(filename, 'export const generation = 0\n')
+    const ctx = await bootHmr(alias, ['.'])
+    const expected = pathToFileURL(filename).href
+    const observed: string[] = []
+    ctx.on('hmr/change', (url) => { observed.push(url) })
+    try {
+      const deadline = Date.now() + 10_000
+      for (let generation = 1; !observed.includes(expected); generation += 1) {
+        if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        writeFileSync(filename, `export const generation = ${generation}\n`)
+        await new Promise(resolve => setTimeout(resolve, 20))
+      }
+    } finally {
+      await ctx.fiber.dispose()
+      rmSync(alias, { force: true })
+      rmSync(target, { recursive: true, force: true })
+    }
+  })
+
+  it('collapses filesystem aliases before registering an exact watch', async () => {
+    const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-canonical-'))
+    const alias = `${target}-alias`
+    symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    const ctx = await bootHmr(alias)
+    try {
+      await ctx.hmr.registerConfig('plugins.yml', () => {})
+      await expect(ctx.hmr.registerConfig(join(realpathSync(target), 'plugins.yml'), () => {}))
+        .rejects.toThrow('config path already registered')
+    } finally {
+      await ctx.fiber.dispose()
+      rmSync(alias, { force: true })
+      rmSync(target, { recursive: true, force: true })
+    }
+  })
+
   it('observes add, change, and unlink outside its module roots', { timeout: 20_000 }, async () => {
     const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
     const filename = join(dir, 'plugins.yml')
diff --git a/packages/util/paths/README.i18n.yaml b/packages/util/paths/README.i18n.yaml
index f79f6b2d73..6bed54f5c3 100644
--- a/packages/util/paths/README.i18n.yaml
+++ b/packages/util/paths/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/util/paths/README.md
-README.md: 2b3272e019ef2f37386da9156b06a5c151836d8c
-README.zh.md: 7fe0ec04117ae439ade653cefd1c8f5da094d8fd
+README.md: 8d10ed855a37f1205f87420b3f36f45b10e65bd3
+README.zh.md: ed3ca377bd48252fe0ef3f95186dc6eb1fb6e6a0
diff --git a/packages/util/paths/README.md b/packages/util/paths/README.md
index 2b3272e019..8d10ed855a 100644
--- a/packages/util/paths/README.md
+++ b/packages/util/paths/README.md
@@ -18,9 +18,13 @@ Shared filesystem path helpers for DeepSeek Harness user data.
 
 `expandHomePath()` expands `~`, `~/...`, and Windows-style `~\...` prefixes against the operating-system home directory. It leaves non-tilde paths and `~user/...` untouched.
 
+## Watch paths
+
+`canonicalizeWatchPath()` gives a native filesystem watcher one stable spelling of its target. It resolves the deepest existing ancestor through `fs.realpath()` and restores any missing suffix, so a file or directory may still be watched before it is created. In particular, Windows 8.3 aliases cannot be mixed with the long paths emitted by the native watcher backend.
+
 This package is intentionally small and harness-dep-free so product packages can share user-data path conventions without depending on one another.
 
 ## Known Limitations and Deferred Work
 
 - **Expansion is deliberately narrow** — only bare `~`, `~/...`, and `~\...` use the current operating-system home; named-user forms such as `~alice/...`, environment variables, and shell expressions remain unchanged.
-- **Helpers do not touch the filesystem** — callers still own directory creation, existence checks, permissions, and trust policy for the resulting path.
+- **Canonicalization reads but never mutates** — `canonicalizeWatchPath()` performs `realpath` probes and propagates errors other than absence; callers still own directory creation, permissions, and trust policy for the resulting path.
diff --git a/packages/util/paths/README.zh.md b/packages/util/paths/README.zh.md
index 7fe0ec0411..ed3ca377bd 100644
--- a/packages/util/paths/README.zh.md
+++ b/packages/util/paths/README.zh.md
@@ -18,9 +18,13 @@ DeepSeek Harness 用户数据的共享文件系统路径辅助工具。
 
 `expandHomePath()` 使用操作系统主目录展开 `~`、`~/...` 和 Windows 风格的 `~\...` 前缀。它会保留非波浪号路径和 `~user/...` 原样不变。
 
+## 监听路径
+
+`canonicalizeWatchPath()` 为原生文件系统 watcher 提供一种稳定的目标路径表示。它通过 `fs.realpath()` 解析层级最深的现有祖先路径，再拼回缺失的后缀，因此即使文件或目录尚未创建也仍可监听。尤其是，Windows 8.3 别名不能与原生 watcher 后端发出的长路径混用。
+
 该包刻意保持规模小且不依赖 harness，以便产品包共享用户数据路径约定，而不必彼此依赖。
 
 ## 已知限制与暂缓事项
 
 - **展开范围刻意保持狭窄**：只有单独的 `~`、`~/...` 和 `~\...` 使用当前操作系统主目录；`~alice/...` 等指定用户的形式、环境变量和 shell 表达式保持不变。
-- **辅助工具不会操作文件系统**：调用方仍负责目录创建、存在性检查、权限，以及对结果路径应用信任策略。
+- **规范化会读取，但绝不修改**：`canonicalizeWatchPath()` 会执行 `realpath` 探测，并传播除路径不存在以外的错误；调用方仍负责目录创建、权限，以及对结果路径应用信任策略。
diff --git a/packages/util/paths/src/index.ts b/packages/util/paths/src/index.ts
index a8f9245c72..591158d7c0 100644
--- a/packages/util/paths/src/index.ts
+++ b/packages/util/paths/src/index.ts
@@ -4,8 +4,9 @@
  * @module @deepseek-ai/dsh-paths
  */
 
+import { realpath } from 'node:fs/promises'
 import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 
 /** Directory name for the default DeepSeek Harness home under the OS home. */
 export const DSH_HOME_DIR_NAME = '.dsh'
@@ -16,6 +17,33 @@ export const DEFAULT_DSH_HOME_DISPLAY = `~/${DSH_HOME_DIR_NAME}`
 /** Environment variable that overrides the default DeepSeek Harness home. */
 export const DSH_HOME_ENV = 'DSH_HOME'
 
+/**
+ * Give a native filesystem watcher one canonical spelling of a path, even
+ * when its final components do not exist yet. The deepest existing ancestor
+ * is resolved through {@link realpath}; the missing suffix is then restored.
+ * This prevents Windows short-name aliases from being mixed with long paths
+ * emitted by the native watcher backend.
+ * @param path - Watch target or root, resolved against the current directory.
+ * @returns the target with its existing ancestor canonicalized.
+ * @throws when ancestor traversal encounters an error other than absence.
+ */
+export async function canonicalizeWatchPath(path: string): Promise<string> {
+  let current = resolve(path)
+  const missing: string[] = []
+  while (true) {
+    try {
+      return join(await realpath(current), ...missing.reverse())
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      const parent = dirname(current)
+      /* v8 ignore next -- a filesystem root exists, so traversal resolves before this guard */
+      if (parent === current) throw error
+      missing.push(basename(current))
+      current = parent
+    }
+  }
+}
+
 /**
  * Resolve the default DeepSeek Harness home using Node's platform path rules.
  * @returns the absolute default harness home path.
diff --git a/packages/util/paths/tests/paths.spec.ts b/packages/util/paths/tests/paths.spec.ts
index 08336bbcce..df5555f910 100644
--- a/packages/util/paths/tests/paths.spec.ts
+++ b/packages/util/paths/tests/paths.spec.ts
@@ -1,9 +1,11 @@
-import { homedir } from 'node:os'
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
   DEFAULT_DSH_HOME_DISPLAY,
   DSH_HOME_DIR_NAME,
+  canonicalizeWatchPath,
   defaultDshHome,
   dshHomeDisplay,
   dshHomePath,
@@ -53,4 +55,22 @@ describe('dsh path helpers', () => {
     expect(dshHomeDisplay(resolve(defaultDshHome()))).toBe('~/.dsh')
     expect(dshHomeDisplay('/some/other/root')).toBe('$DSH_HOME')
   })
+
+  it('canonicalizes a watcher ancestor while preserving a missing suffix', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-watch-path-'))
+    const target = join(root, 'target')
+    const alias = join(root, 'alias')
+    try {
+      await mkdir(target)
+      await symlink(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+      await expect(canonicalizeWatchPath(join(alias, 'later', 'config.yml'))).resolves.toBe(
+        join(await realpath(target), 'later', 'config.yml'),
+      )
+      const file = join(root, 'file')
+      await writeFile(file, 'not a directory')
+      await expect(canonicalizeWatchPath(join(file, 'child'))).rejects.toMatchObject({ code: 'ENOTDIR' })
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
 })
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 89e417558c..3b39b83897 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -3,7 +3,7 @@
 import { execFileSync } from 'node:child_process'
 import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { docsPages, type DocsPage } from '../website/docs.ts'
 import {
@@ -148,7 +148,7 @@ describe('rewriteMarkdown', () => {
       repoRoot: root,
       repositoryRef: 'abc123',
       placeImage: (absPath) => {
-        const name = absPath.split('/').pop() ?? ''
+        const name = basename(absPath)
         placed.push(name)
         return `./${name}`
       },
@@ -167,7 +167,7 @@ describe('rewriteMarkdown', () => {
       pages,
       repoRoot: root,
       repositoryRef: 'abc123',
-      placeImage: absPath => `./${absPath.split('/').pop() ?? ''}`,
+      placeImage: absPath => `./${basename(absPath)}`,
     })).toBe('![logo](./logo.svg#view)\n')
   })
 
diff --git a/vendor/README.md b/vendor/README.md
index 4bf1d43f46..0a434605ae 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -38,7 +38,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/ui/app-boot/tests/hmr-config.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/ui/app-boot/tests/hmr-config.spec.ts`.
 10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/ui/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
diff --git a/vendor/hmr/README.md b/vendor/hmr/README.md
index db5ac1a49a..eec6ff940f 100644
--- a/vendor/hmr/README.md
+++ b/vendor/hmr/README.md
@@ -7,6 +7,12 @@ module caches, and reloads only the plugin entries that depend on changed
 application files. Changes to framework-level dependencies fall back to
 `loader.exit()`, letting the host process restart.
 
+Module watches canonicalize their existing base directory before opening
+Chokidar. Exact config watches likewise canonicalize the deepest existing
+ancestor, then restore any missing suffix. Callbacks and diagnostics retain the
+requested absolute filename, while the native backend receives one filesystem
+spelling even when Windows supplied an 8.3 alias.
+
 ## Requirements
 
 - `@cordisjs/plugin-loader`
diff --git a/vendor/hmr/src/index.ts b/vendor/hmr/src/index.ts
index 00864cd865..c1d379e36c 100644
--- a/vendor/hmr/src/index.ts
+++ b/vendor/hmr/src/index.ts
@@ -4,7 +4,7 @@ import { ModuleLoader, type ModuleJob, type ResolveResult } from '@cordisjs/plug
 import type { Include } from '@cordisjs/plugin-include'
 import { FSWatcher, watch, type ChokidarOptions } from 'chokidar'
 import { dirname, relative, resolve } from 'node:path'
-import { stat } from 'node:fs/promises'
+import { realpath, stat } from 'node:fs/promises'
 import { handleError } from './error.ts'
 import type {} from '@cordisjs/plugin-timer'
 import { fileURLToPath, pathToFileURL } from 'node:url'
@@ -61,13 +61,18 @@ interface ConfigRegistration {
   watcher: FSWatcher
 }
 
-async function findWatchRoot(filename: string): Promise<{ root: string; depth: number }> {
+async function findWatchRoot(filename: string): Promise<{ filename: string; root: string; depth: number }> {
   let root = dirname(filename)
   let depth = 0
   while (true) {
     try {
       if (!(await stat(root)).isDirectory()) throw new Error(`config watch parent is not a directory: ${root}`)
-      return { root, depth }
+      const canonicalRoot = await realpath(root)
+      return {
+        filename: resolve(canonicalRoot, relative(root, filename)),
+        root: canonicalRoot,
+        depth,
+      }
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
       const parent = dirname(root)
@@ -129,9 +134,11 @@ class Hmr extends Service {
   async registerConfig(filename: string, refresh: () => Promise<void> | void): Promise<() => Promise<void>> {
     if (!this.watcher) throw new Error('HMR is not active')
     filename = resolve(this.baseDir, filename)
-    if (this.configs.has(filename)) throw new Error(`config path already registered: ${filename}`)
+    const target = await findWatchRoot(filename)
+    const watchFilename = target.filename
+    if (this.configs.has(watchFilename)) throw new Error(`config path already registered: ${filename}`)
 
-    const { root, depth } = await findWatchRoot(filename)
+    const { root, depth } = target
     const watcher = watch(root, {
       ...this.config,
       cwd: undefined,
@@ -140,9 +147,10 @@ class Hmr extends Service {
       ignoreInitial: false,
     })
     const registration = { watcher }
-    this.configs.set(filename, registration)
+    this.configs.set(watchFilename, registration)
     const onChange = (path: string) => {
-      if (resolve(path) !== filename) return
+      const observed = resolve(path)
+      if (observed !== filename && observed !== watchFilename) return
       this.refreshConfig(registration, filename, refresh)
     }
     watcher.on('add', onChange)
@@ -167,12 +175,12 @@ class Hmr extends Service {
     try {
       await ready.promise
       return this.ctx.effect(() => async () => {
-        if (this.configs.get(filename) === registration) this.configs.delete(filename)
+        if (this.configs.get(watchFilename) === registration) this.configs.delete(watchFilename)
         await watcher.close()
         await this.configRefreshes.get(registration)?.running
       }, 'hmr.registerConfig()')
     } catch (error) {
-      this.configs.delete(filename)
+      this.configs.delete(watchFilename)
       await watcher.close()
       throw error
     }
@@ -205,10 +213,11 @@ class Hmr extends Service {
     }
 
     const match = picomatch(ignored)
+    const watchBaseDir = await realpath(this.baseDir)
     this.watcher = watch(root, {
       ...this.config,
-      cwd: this.baseDir,
-      ignored: path => match(relative(this.baseDir, path)),
+      cwd: watchBaseDir,
+      ignored: path => match(relative(watchBaseDir, path)),
       // The initial scan re-announces files the boot just consumed: an `add`
       // for a config file refreshes an include whose initial apply may still
       // be in flight, and a failing apply then rolls this plugin back while

From df30c62e2b062da14fa0366728d821f416d72e57 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Fri, 7 Aug 2026 14:54:31 +0800
Subject: [PATCH 016/262] fix(agent-loop): latch wakes landing in the
 cancel-convergence window

---
 ...07-16-explicit-turn-cancellation.i18n.yaml |   4 +-
 .../2026-07-16-explicit-turn-cancellation.md  |   2 +-
 ...026-07-16-explicit-turn-cancellation.zh.md |   2 +-
 ...07-cancel-convergence-wake-latch.i18n.yaml |   6 +
 ...026-08-07-cancel-convergence-wake-latch.md |  29 ++++
 ...-08-07-cancel-convergence-wake-latch.zh.md |  29 ++++
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   2 +-
 docs/architecture.zh.md                       |   2 +-
 docs/cordis-catalog/events.md                 |  24 +--
 docs/core-data-structures/core.i18n.yaml      |   4 +-
 docs/core-data-structures/core.md             |   6 +-
 docs/core-data-structures/core.zh.md          |   6 +-
 docs/event-producer-consumer.md               |  24 +--
 docs/persistence-catalog.md                   |   2 +-
 packages/core/agent-loop/README.i18n.yaml     |   4 +-
 packages/core/agent-loop/README.md            |   2 +-
 packages/core/agent-loop/README.zh.md         |   2 +-
 packages/core/agent-loop/src/agent.ts         |  51 ++++--
 packages/core/agent-loop/tests/cancel.spec.ts | 154 ++++++++++++++++--
 packages/core/agent-loop/tests/loop.spec.ts   |  73 ++++++++-
 .../core/agent-loop/tests/mock-adapter.ts     |  18 +-
 packages/core/agent/src/types.ts              |   6 +-
 23 files changed, 379 insertions(+), 77 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index 820299cf2e..2f7893a09f 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.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 .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
-2026-07-16-explicit-turn-cancellation.md: ca56c77a097e3008a50c2aec24040a4f4b6f0ba3
-2026-07-16-explicit-turn-cancellation.zh.md: bf410e5c7284a9c9914edbd14445074e71dd6943
+2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
+2026-07-16-explicit-turn-cancellation.zh.md: 68089e2c48d239afbff4c10cba5a202b4b6ff262
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
index ca56c77a09..2b7cb8cc77 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
@@ -18,7 +18,7 @@ An interrupted live turn ends with the coarse durable `{ kind: 'aborted' }` outc
 
 AgentLoop privately owns one `TurnCancellation` per prospective turn. It installs the holder before notifying `agent/status = running`, retains its single `AbortController` through inbox claim, `agent/pre-step`, prompt assembly, every step, model and tool execution, and `agent/turn-stopping`, then clears the exact holder immediately before publishing `turn/end`. Terminal event observers and the following durability flush therefore cannot cancel already-completed turn work even though driver status may remain `running` until the flush settles. Every participating method, event, and request value receives that same explicit signal; the next turn receives a fresh signal.
 
-The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer belongs to the next turn. If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
+The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer is latched and runs when the aborted activity converges to idle — a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
 
 The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining seams keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index bf410e5c72..68089e2c48 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -18,7 +18,7 @@ Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user
 
 AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它在通知 `agent/status = running` 前安装该持有者，使其中唯一的 `AbortController` 持续覆盖 inbox 领取、`agent/pre-step`、提示词组装、每个步骤、模型与工具执行以及 `agent/turn-stopping`；随后在发布 `turn/end` 前立即清除所安装的那个持有者。因此，即使驱动器状态可能在持久化刷新结算前保持 `running`，终态事件观察者及其后的持久化刷新也无法取消已完成的轮次工作。所有参与的方法、事件和请求值都会收到同一个显式 signal；下一个轮次会收到全新的 signal。
 
-对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作属于下一个轮次。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
+对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
 显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
new file mode 100644
index 0000000000..d31f344c27
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.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 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
+2026-08-07-cancel-convergence-wake-latch.md: fe00c78bdfadac0cc6c9c173fd04256f77a22051
+2026-08-07-cancel-convergence-wake-latch.zh.md: f76ad360e2d8b70f76c6baf53e2fde963a80b6c4
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
new file mode 100644
index 0000000000..fe00c78bdf
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
@@ -0,0 +1,29 @@
+# Agent Note: Latch wake-ups that land in the cancel-convergence window
+
+Status: implemented
+
+English | [中文](2026-08-07-cancel-convergence-wake-latch.zh.md)
+
+## Problem
+
+`Agent.cancel(cause, { keepInbox: true })` returns immediately after firing the abort signal, but the active driver may not have converged to `idle` yet: LLM stream teardown, tool cancellation, and the `turn/end` append all unwind asynchronously after `abort()` returns. A waking send arriving in that window was placed into `next-turn` while `wakeDriver()` returned early on the still-`running` phase, and the exiting driver never replayed the wake — the message stayed parked until another waking send arrived. The same dropped-wake window existed around aborted `runMaintenance` activities. Several tests enshrined the parked behavior ("waits for another wakeup"); the bug broke both `session.cancel` and the `subagent.interrupt` composition path (issue #1838). The owning cancellation and send contracts are the [explicit turn cancellation](../architecture/2026-07-16-explicit-turn-cancellation.md) and [unified send](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) decisions; the production `keepInbox` consumer is [web stop preserves queue](2026-07-31-web-stop-preserves-queue.md).
+
+## Decision
+
+The `running` phase carries a `wakeRequested` latch, mirroring the existing `maintenance` phase field. `wakeDriver()` latches whenever the current activity cannot deliver the wake — a maintenance task never reads the queue, and an aborted activity converges without restarting — while a live driver needs no latch because it claims queued work itself. The exiting activity replays the latch at its own convergence boundary (`kick`'s `finally` and `runMaintenance`'s `finally`): this placement guarantees `turn/end N` lands before the replayed driver opens `turn/start N+1`, and that `whenIdle()` sees the replayed driver through its `activityDone` loop. The replay sites run only while `inbox.hasPending`, so a latched wake removed from the inbox before convergence does not start an empty driver. A wake sent while the agent is already idle keeps its turn boundary even when its message is cleared before the driver claims — that `idle → running → idle` transition is an observable contract: the goal-session driver's pause/disarm fallback fires on the `idle` transition after a cancelled reservation (CI caught this when the guard was moved into `wakeDriver()` and suppressed the boundary). `cancel()` without `keepInbox` clears the latch together with the inbox.
+
+The `signal.aborted` discriminator is load-bearing: it separates pre-abort queued work — which `keepInbox` parks for a later wake (acceptance criterion 1) — from post-abort explicit wakes, which must run after convergence.
+
+## Alternatives considered
+
+**Have `cancel()` set the phase to `idle` immediately.** Rejected: the driver is still unwinding, so this overlaps two drivers. The replay lives in the old driver's `finally`, which then never runs — 14 of 83 tests failed, several deadlocked. Repairing it requires identity-based phase ownership plus a turn-open quiescence barrier, which is strictly more machinery and is the latch in disguise.
+
+**Latch unconditionally for every non-idle wake.** Rejected: pre-abort wakes would auto-start after a `keepInbox` cancel, violating acceptance criterion 1; the "parks queued work" test and the error-window steering test both failed.
+
+**Replay through a chained promise (`activityDone.then(...)`).** Rejected: the replay would run outside the activity's own settlement, so `whenIdle()`'s loop can resolve before the replayed driver starts; fixing that requires replacing `activityDone` at send time and depends on microtask reaction ordering — more fragile than a synchronous flag.
+
+**Wait for quiescence in the subagent adapter.** Rejected by the issue scope: the cancel/wake state machine owns the fix, not a consumer.
+
+## Consequences
+
+The `running` phase gains a `wakeRequested` field; `cancel()` without `keepInbox` clears it alongside the inbox, and a `disposed` cancel never latches, so a wake landing after disposal begins stays parked and `whenIdle()` does not wait on a full model turn over the session being torn down. A wake arriving in the sub-microtask gap between the driver's final `hasPending` check and its exit still parks — no latch fires because the phase is `running` and not aborted; closing that gap requires the unconditional latch and is deliberately out of scope. Between the aborted turn and the replayed driver, status transitions emit a transient `idle → running` pair. A waking send whose message is cleared before any driver claims it still opens an empty completed turn, preserving the observable wake boundary.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
new file mode 100644
index 0000000000..f76ad360e2
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 锁存取消收敛窗口内到达的唤醒请求
+
+Status: implemented
+
+[English](2026-08-07-cancel-convergence-wake-latch.md) | 中文
+
+## 问题
+
+`Agent.cancel(cause, { keepInbox: true })` 在触发 abort 信号后立即返回，但活动 driver 可能尚未收敛到 `idle`：LLM 流拆除、工具取消与 `turn/end` 落盘都会在 `abort()` 返回后异步展开。在该窗口内到达的唤醒 send 被放入 `next-turn`，而 `wakeDriver()` 对仍处于 `running` 的 phase 直接返回，退出的 driver 也从不重放这次唤醒——消息会一直停放到下一条唤醒 send 到达。被中止的 `runMaintenance` 活动周围也存在同样的唤醒丢失窗口。多个测试固化了停放行为（「等待下一次唤醒」）；该缺陷同时破坏了 `session.cancel` 与 `subagent.interrupt` 组合路径（issue #1838）。拥有取消与发送契约的既有决策是[显式轮次取消](../architecture/2026-07-16-explicit-turn-cancellation.md)与[统一发送](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)；生产环境中的 `keepInbox` 消费方是[Web 停止保留队列](2026-07-31-web-stop-preserves-queue.md)。
+
+## 决策
+
+`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察契约：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
+
+`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（验收条件 1）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
+
+## 备选方案
+
+**让 `cancel()` 立即把 phase 置为 `idle`。** 不予采用：driver 仍在展开收尾，这会重叠两个 driver。重放逻辑位于旧 driver 的 `finally`，而该 `finally` 此后不再执行——83 个测试中有 14 个失败，多个死锁。修复它需要基于身份的 phase 所有权外加 turn 打开时的 quiescence 屏障，机制上严格更重，而且该屏障就是换了个形态的锁存。
+
+**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反验收条件 1；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
+
+**通过链式 promise（`activityDone.then(...)`）重放。** 不予采用：重放会运行在活动自身结算之外，`whenIdle()` 的循环可能在重放 driver 启动前就 resolve；修复它需要在 send 时同步替换 `activityDone`，并依赖微任务反应顺序——比同步 flag 更脆弱。
+
+**在 subagent adapter 中等待 quiescence。** 被 issue 范围否决：修复由取消/唤醒状态机拥有，而不是消费方。
+
+## 影响
+
+`running` phase 新增 `wakeRequested` 字段；不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除它，且 `disposed` 取消从不锁存——dispose 开始后到达的唤醒保持停放，`whenIdle()` 不会在拆除中的会话上等待一个完整模型 turn。落在 driver 最后一次 `hasPending` 检查与退出之间微任务间隙的唤醒仍会停放——没有锁存触发，因为 phase 是 `running` 且未 abort；关闭该间隙需要无条件锁存，刻意留作范围外。在被中止的 turn 与重放 driver 之间，状态转换会发出一次瞬态 `idle → running` 对。唤醒 send 的消息在任何 driver 认领前被清除时，仍会打开一个空的 completed turn，保留可观察的唤醒边界。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index ca91a80b7e..de15631197 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 3080d21a24310cc8851d64719d862ec719150ab6
-architecture.zh.md: 6e2bf0c155c68e84580aecc6b7783eeffa25c640
+architecture.md: ea78faa62773a6b8ac98e5baab6e181ad6a3b7f0
+architecture.zh.md: 5a46dfaf84276de5f4dc0352a529bdd4e5d8c267
diff --git a/docs/architecture.md b/docs/architecture.md
index 3080d21a24..ea78faa627 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -121,7 +121,7 @@ Pruning precedes summaries; overflow retries require durable progress. `agent/re
 
 Adapter selection, dispatch, and iteration failures become terminal error or aborted `finish` chunks. `agent/request-error` receives request coordinates, normalized `LlmFailure`, available retry policy, and signal; middleware and consumer errors remain outside recovery. Failed chunks commit neither messages nor tool calls.
 
-Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
+Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Waking input that lands after the abort fires but before convergence runs at the driver's convergence boundary, while a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
 
 Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 6e2bf0c155..5a46dfaf84 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -121,7 +121,7 @@ idle inject:
 
 适配器选择、分发与迭代失败会成为 error 或 aborted 类型的终止 `finish` 分片。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用的重试策略和信号；middleware 与消费方错误仍在恢复之外。失败分片既不提交消息，也不提交工具调用。
 
-其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
+其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
 轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 92c2fade12..ae16d10f07 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -33,7 +33,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:154`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -53,7 +53,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:163`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -75,7 +75,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/claimed` — emit
 
@@ -97,7 +97,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:192`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/discarded` — emit
 
@@ -116,7 +116,7 @@ One message was discarded from the live inbox.
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:200`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/inserted` — emit
 
@@ -135,7 +135,7 @@ One message entered the live inbox.
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:181`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — waterfall
 
@@ -158,7 +158,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 
 Types: [Agent](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:226`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -182,7 +182,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request-error` — waterfall
 
@@ -209,7 +209,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 
 Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:255`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -231,7 +231,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:212`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
@@ -252,7 +252,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 
 Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:173`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-stopping` — serial
 
@@ -281,7 +281,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:273`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
 
 ## `agent-loop/*`
 
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml
index e79d5dac2f..ee870f9334 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md
-core.md: dbd584f10b3daf873bc14210472efb6cd315717e
-core.zh.md: 1fe1616a0c96abb4e8b91417cc4eae292416e42a
+core.md: 8f413a7a064ad6f63e0caec31354869e51139020
+core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index dbd584f10b..8f413a7a06 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -685,7 +685,11 @@ interface Agent {
 
   /**
    * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next turn.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
    * @param message - identified content and its producer provenance.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md
index 1fe1616a0c..d0f02f0cfc 100644
--- a/docs/core-data-structures/core.zh.md
+++ b/docs/core-data-structures/core.zh.md
@@ -693,7 +693,11 @@ interface Agent {
 
   /**
    * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next turn.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
    * @param message - identified content and its producer provenance.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 5c60be95e1..940d89eae0 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -8,18 +8,18 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:154`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:163`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
-| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:192`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:200`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:181`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:226`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:255`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:212`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:173`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:273`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 533ebd3a97..3845c2cb1a 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -100,7 +100,7 @@ Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src
 }
 ```
 
-Source: [`packages/core/agent/src/types.ts:296`](../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
 
 ### `approval/*`
 
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index b25a0f18f1..2f165e76e4 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: ec1948506bbaf7a3416c2031fb472a9b513b500f
-README.zh.md: 5828da301b35c95719286fb942ac239769539b67
+README.md: 2fdc60086bebc924089b5b8bd12f4b4456b1ead5
+README.zh.md: df0ba44ec5b010666737c0568bc5eeb220ff0d96
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index ec1948506b..2fdc60086b 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -67,7 +67,7 @@ Every provider call that reaches a successful finish appends exactly one `assist
 
 After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance applies the same provenance rule when resuming.
 
-Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract.
+Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Waking input that lands after the abort fires but before the activity converges to idle is latched (`wakeRequested`) and replayed at the driver's own convergence boundary, so it runs without a further waking send; a `disposed` cancel never latches, and a wake submitted while already idle always opens its turn boundary (status shows a transient `idle → running → idle` pair even when the message was cleared). Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) and the [cancel-convergence wake latch](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md) own the lifecycle and race contract.
 
 Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, and retains their finalized result context without distinguishing the cancellation cause. An internal scheduler failure stops new dispatches, waits for already-started dispatches, and reaches the turn error boundary without fabricating tool results.
 
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index 5828da301b..df0ba44ec5 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -67,7 +67,7 @@ interface Config {
 
 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。
 
-插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。
+插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态契约。
 
 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。内部调度器故障会停止新的分发，等待已启动的分发，然后在不虚构工具结果的情况下到达轮次错误边界。
 
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index cfac8262c2..6701777a0f 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -43,7 +43,7 @@ type Phase =
     lastTurn: number
     wakeRequested: boolean
   }
-  | { kind: 'running'; abort: AbortController; turn: number; step: number }
+  | { kind: 'running'; abort: AbortController; turn: number; step: number; wakeRequested: boolean }
 
 type StepEndReason = Extract<TurnEndReason, { kind: 'completed' | 'max-tokens' }>
 
@@ -112,10 +112,12 @@ export class ReactLoopAgent implements Agent {
 
   send(message: UserMessage, target: InboxTarget, wakeup: boolean): void {
     // Waking input cannot join an aborted activity, so it starts the next turn.
+    // The classification is captured BEFORE the insertion: a reentrant cancel
+    // from a synchronous splice observer must not reclassify this wake.
     const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted
     const resolvedTarget = wakingAfterAbort ? 'next-turn' : target
     this.inbox.splice(resolvedTarget, Infinity, 0, [message])
-    if (wakeup) this.wakeDriver()
+    if (wakeup) this.wakeDriver(wakingAfterAbort)
   }
 
   followup(input: UserMessage): void {
@@ -133,7 +135,7 @@ export class ReactLoopAgent implements Agent {
   cancel(cause: AgentCancelCause, options: CancelOptions = {}): void {
     if (!options.keepInbox) {
       this.inbox.clear()
-      if (this.phase.kind === 'maintenance') this.phase.wakeRequested = false
+      if (this.phase.kind !== 'idle') this.phase.wakeRequested = false
     }
     if (this.phase.kind !== 'idle') this.phase.abort.abort(cause)
   }
@@ -154,22 +156,44 @@ export class ReactLoopAgent implements Agent {
         return await task(maintenance.abort.signal)
       } finally {
         this.setPhase({ kind: 'idle', lastTurn: maintenance.lastTurn })
-        if (maintenance.wakeRequested) this.wakeDriver()
+        if (maintenance.wakeRequested && this.inbox.hasPending) this.wakeDriver()
         done.resolve()
       }
     })()
   }
 
-  /** Start one driver, or remember its wake behind maintenance. */
-  private wakeDriver(): void {
-    if (this.phase.kind === 'maintenance') {
-      if (!this.phase.abort.signal.aborted) this.phase.wakeRequested = true
+  /**
+   * Start one driver, or latch its wake behind maintenance or an aborted
+   * activity. A wake sent while idle always opens its turn boundary, even
+   * when its message is cleared before the driver claims; only a latched
+   * replay is suppressed when the queue no longer holds the wake.
+   * @param wakeAfterAbort - the send-time classification from {@link send}:
+   *   the wake landed after the abort fired. Captured before the inbox
+   *   insertion so a reentrant cancel cannot reclassify it.
+   */
+  private wakeDriver(wakeAfterAbort = false): void {
+    if (this.phase.kind !== 'idle') {
+      // The current activity cannot deliver this wake: a maintenance task
+      // never reads the queue, and an aborted activity converges without
+      // restarting — both latch for the exiting activity to replay. A live
+      // driver claims queued work itself, so it needs no latch. A disposal
+      // cancel never latches: replaying would make `whenIdle()` wait on a
+      // full model turn over a session being torn down.
+      const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
+      if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
+        this.phase.wakeRequested = true
+      }
       return
     }
-    if (this.phase.kind !== 'idle') return
     const driver = Promise.withResolvers<void>()
     this.activityDone = driver.promise
-    this.setPhase({ kind: 'running', abort: new AbortController(), turn: this.phase.lastTurn, step: 0 })
+    this.setPhase({
+      kind: 'running',
+      abort: new AbortController(),
+      turn: this.phase.lastTurn,
+      step: 0,
+      wakeRequested: false,
+    })
     this.loopCtx.agents.withInitiator(this, () => this.kick()).then(driver.resolve, driver.reject)
   }
 
@@ -196,7 +220,9 @@ export class ReactLoopAgent implements Agent {
     } finally {
       /* v8 ignore next -- kick owns a running phase until this driver boundary */
       if (this.phase.kind === 'running') {
-        this.setPhase({ kind: 'idle', lastTurn: this.phase.turn })
+        const { turn, wakeRequested } = this.phase
+        this.setPhase({ kind: 'idle', lastTurn: turn })
+        if (wakeRequested && this.inbox.hasPending) this.wakeDriver()
       }
     }
   }
@@ -302,6 +328,9 @@ export class ReactLoopAgent implements Agent {
     }
     if (!this.inbox.hasPending) return false
     phase.abort = new AbortController()
+    // The driver keeps running with a fresh controller: any latch set on the
+    // old one is stale, and the live driver claims the queue itself.
+    phase.wakeRequested = false
     phase.step = 0
     return true
   }
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 5c0deed621..79bc65a105 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -126,6 +126,121 @@ describe('Agent.cancel()', () => {
     expect(adapter.requests).toHaveLength(3)
   })
 
+  it('cancel({ keepInbox: true }) latches a waking send landing in the abort-to-idle window', async () => {
+    const adapter = new MockAdapter(['hang', textResponse('B reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('latch-window'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    // The abort signal is set but the driver has not converged to idle yet:
+    // the waking send must be latched, not parked until another wake.
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    send(agent, 'B')
+
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['active', 'B'])
+    expect(adapter.requests).toHaveLength(2)
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(agent.session.events.filter(e => e.type === 'turn/end').map(e =>
+      e.type === 'turn/end' ? e.data.reason : null)).toEqual([
+      { kind: 'aborted', reason: { kind: 'user' } },
+      { kind: 'completed' },
+    ])
+  })
+
+  it('cancel() without keepInbox clears a latched wake alongside the inbox', async () => {
+    const adapter = new MockAdapter(['hang', textResponse('C reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('latch-cleared'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    send(agent, 'B') // latched behind the aborted activity
+    agent.cancel({ kind: 'user' }) // drops the inbox and the latch with it
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['active'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
+
+    send(agent, 'C')
+    await agent.whenIdle()
+    expect(userTexts(agent)).toEqual(['active', 'C'])
+    expect(adapter.requests).toHaveLength(2)
+  })
+
+  it('removing the latched wake before convergence suppresses the replay', async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('removed-latched-wake'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    const steer = createUserMessage({ content: [{ type: 'text', text: 'steer me' }], source: { kind: 'user' } })
+    agent.steer(steer) // latched behind the aborted activity
+    agent.inbox.remove(steer.id) // the wake is retracted before convergence
+
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['active'])
+    expect(adapter.requests).toHaveLength(1)
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(agent.status).toBe('idle')
+    // No replay with nothing to run: the latched message is gone, so no
+    // empty follow-up turn is recorded.
+    expect(agent.session.events.filter(e => e.type === 'turn/start')).toHaveLength(1)
+  })
+
+  it('latches a wake arriving deep into a slow abort convergence', async () => {
+    // The stream notices the abort only after 50ms, so the driver stays in
+    // the abort-to-idle window long after `cancel()` returned: the wake must
+    // be latched across the whole window, not just the same-tick case.
+    const adapter = new MockAdapter(['hang-slow', textResponse('B reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('slow-convergence'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'A')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    send(agent, 'B')
+
+    await agent.whenIdle()
+    expect(userTexts(agent)).toEqual(['A', 'B'])
+    expect(adapter.requests).toHaveLength(2)
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+  })
+
+  it('does not latch a wake landing after disposal begins', async () => {
+    const adapter = new MockAdapter(['hang-slow', textResponse('late reply')])
+    const ctx = await harness(adapter)
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('dispose-window-wake'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const agent = handle.agent
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    // Dispose cancels with `{ kind: 'disposed' }`; a wake landing in the
+    // abort-to-idle window must not latch, so `whenIdle()` does not wait on
+    // a model turn over the session being torn down.
+    const disposal = handle.dispose()
+    setTimeout(() => { send(agent, 'late wake') }, 10)
+    await disposal
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(userTexts(agent)).toEqual(['active'])
+  })
+
   it('cancel after waking send closes its synchronously opened turn without a step', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
@@ -228,7 +343,7 @@ describe('Agent.cancel()', () => {
     expect(userTexts(agent)).toEqual(['first', 'later'])
   })
 
-  it('replacement work queued after idle-listener cancellation waits for another wakeup', async () => {
+  it('replacement work queued after idle-listener cancellation replays at convergence', async () => {
     const adapter = new MockAdapter([
       textResponse('first reply'),
       textResponse('replacement reply'),
@@ -253,9 +368,11 @@ describe('Agent.cancel()', () => {
     if (replacementIdle === undefined) throw new Error('idle listener did not register replacement work')
     await replacementIdle
 
-    expect(adapter.requests).toHaveLength(1)
-    expect(userTexts(agent)).toEqual(['first'])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    // The wake sent after the cancel fired is latched: the surviving
+    // replacement runs at convergence without a third message.
+    expect(adapter.requests).toHaveLength(2)
+    expect(userTexts(agent)).toEqual(['first', 'surviving replacement'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
 
     const idle = waitForIdle(ctx, agent)
     send(agent, 'wake it')
@@ -479,7 +596,7 @@ describe('Agent.cancel()', () => {
     expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
   })
 
-  it('a running-listener cancellation parks replacement work until another wakeup', async () => {
+  it('a running-listener cancellation replays replacement work at convergence', async () => {
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -497,17 +614,20 @@ describe('Agent.cancel()', () => {
     await idle
     dispose()
 
-    expect(userTexts(agent)).toEqual([])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    // B's wake was latched behind the cancelled driver: it runs on its own.
+    expect(userTexts(agent)).toEqual(['B'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
 
     const replacementIdle = waitForIdle(ctx, agent)
     send(agent, 'C')
     await replacementIdle
     expect(userTexts(agent)).toEqual(['B', 'C'])
+    expect(adapter.requests).toHaveLength(2)
     expect(agent.session.events.filter(event => event.type === 'turn/end')).toHaveLength(2)
   })
 
-  it('a prompt queued during pre-step cancellation waits for another wakeup', async () => {
+  it('a prompt queued during pre-step cancellation replays at convergence', async () => {
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -518,13 +638,15 @@ describe('Agent.cancel()', () => {
     send(agent, 'B')
 
     await idle
-    expect(userTexts(agent)).toEqual([])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    expect(userTexts(agent)).toEqual(['B'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
 
     const replacementIdle = waitForIdle(ctx, agent)
     send(agent, 'C')
     await replacementIdle
     expect(userTexts(agent)).toEqual(['B', 'C'])
+    expect(adapter.requests).toHaveLength(2)
     expect(agent.session.events.filter(event => event.type === 'turn/end')).toHaveLength(3)
   })
 
@@ -556,7 +678,7 @@ describe('Agent.cancel()', () => {
     expect(flat).not.toContain('steer text')
   })
 
-  it('parks replacement work queued synchronously by an abort observer', async () => {
+  it('replays replacement work queued synchronously by an abort observer', async () => {
     const adapter = new MockAdapter([
       'hang',
       textResponse('replacement reply'),
@@ -586,13 +708,15 @@ describe('Agent.cancel()', () => {
       }),
     ])
 
-    expect(adapter.requests).toHaveLength(1)
-    expect(userTexts(agent)).toEqual(['original'])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    // The abort-observer wake was latched: replacement runs at convergence,
+    // so the original turn is followed by a completed replacement turn.
+    expect(adapter.requests).toHaveLength(2)
+    expect(userTexts(agent)).toEqual(['original', 'replacement'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
     const reasons = agent.session.events
       .filter(event => event.type === 'turn/end')
       .map(event => event.type === 'turn/end' ? event.data.reason : undefined)
-    expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }])
+    expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }])
 
     const replacementIdle = waitForIdle(ctx, agent)
     send(agent, 'wake it')
diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts
index c8d048ca47..1173607ae9 100644
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -41,6 +41,14 @@ function send(agent: Agent, text: string) {
   agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }))
 }
 
+/** All user-message texts recorded in the log (to assert what actually ran). */
+function userTexts(agent: Agent): string[] {
+  return agent.session.events
+    .filter(e => e.type === 'user/message')
+    .flatMap(e => e.type === 'user/message' ? e.data.content : [])
+    .flatMap(b => b.type === 'text' ? [b.text] : [])
+}
+
 describe('agent loop', () => {
   it.each([0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1])(
     'rejects invalid AgentOptions.maxTokens %s before publication',
@@ -70,7 +78,7 @@ describe('agent loop', () => {
   })
 
   it('cancels queued wakeup work together with an active maintenance task', async () => {
-    const adapter = new MockAdapter([textResponse('unused')])
+    const adapter = new MockAdapter([textResponse('park reply')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('cancel-maintenance-wakeup'), {
       provider: 'mock',
@@ -87,15 +95,68 @@ describe('agent loop', () => {
     })
     await started.promise
 
-    send(agent, 'discard this wakeup')
-    agent.cancel({ kind: 'user' })
-    send(agent, 'park after cancellation')
+    send(agent, 'discard this wakeup') // latched behind the live maintenance task
+    agent.cancel({ kind: 'user' }) // drops the queue and the latch, aborts maintenance
+    send(agent, 'park after cancellation') // newer intent: re-latched, replays at convergence
 
     await expect(maintenance).rejects.toThrow('maintenance aborted')
     await agent.whenIdle()
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+
+    // The pre-cancel wakeup is gone; the post-cancel wake replays at convergence.
+    expect(userTexts(agent)).toEqual(['park after cancellation'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('replays a wake latched behind maintenance at convergence', async () => {
+    const adapter = new MockAdapter([textResponse('wake reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('maintenance-wake-replay'), {
+      provider: 'mock',
+      model: 'mock',
+    })
+    const started = Promise.withResolvers<undefined>()
+    const finish = Promise.withResolvers<undefined>()
+    const maintenance = agent.runMaintenance(async () => {
+      started.resolve(undefined)
+      await finish.promise
+    })
+    await started.promise
+
+    send(agent, 'wake behind maintenance')
+    finish.resolve(undefined)
+    await maintenance
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['wake behind maintenance'])
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('suppresses the replay when a latched maintenance wake is removed', async () => {
+    const adapter = new MockAdapter([])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('maintenance-wake-removed'), {
+      provider: 'mock',
+      model: 'mock',
+    })
+    const started = Promise.withResolvers<undefined>()
+    const finish = Promise.withResolvers<undefined>()
+    const maintenance = agent.runMaintenance(async () => {
+      started.resolve(undefined)
+      await finish.promise
+    })
+    await started.promise
+
+    const wake = createUserMessage({ content: [{ type: 'text', text: 'removed wake' }], source: { kind: 'user' } })
+    agent.followup(wake)
+    agent.inbox.remove(wake.id)
+    finish.resolve(undefined)
+    await maintenance
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual([])
     expect(adapter.requests).toEqual([])
-    agent.cancel({ kind: 'user' })
+    expect(agent.session.events.filter(e => e.type === 'turn/start')).toHaveLength(0)
   })
 
   it('runs a simple turn: queued message → model → idle, with ordered events', async () => {
diff --git a/packages/core/agent-loop/tests/mock-adapter.ts b/packages/core/agent-loop/tests/mock-adapter.ts
index 6e592d9311..69dc78990c 100644
--- a/packages/core/agent-loop/tests/mock-adapter.ts
+++ b/packages/core/agent-loop/tests/mock-adapter.ts
@@ -58,14 +58,16 @@ export function toolCallResponse(rawCallId: string, name: string, args: object,
 /**
  * Mock adapter driven by a script: each model call consumes the next entry.
  * Records every request it receives for assertions. An entry may be a
- * function to compute chunks from the request, or a 'hang' marker that
- * streams one chunk then waits until aborted.
+ * function to compute chunks from the request, a 'hang' marker that
+ * streams one chunk then waits until aborted, or 'hang-slow' which takes
+ * 50ms to notice the abort — a stand-in for slow real-world teardown
+ * (LLM stream cancellation, tool unwinding).
  */
 export class MockAdapter extends LlmAdapter {
   requests: GenerateOptions[] = []
 
   constructor(
-    private script: (StreamChunk[] | ((options: GenerateOptions) => StreamChunk[]) | 'hang')[],
+    private script: (StreamChunk[] | ((options: GenerateOptions) => StreamChunk[]) | 'hang' | 'hang-slow')[],
     private readonly reasoning?: LlmModelReasoningInfo,
     private readonly defaultMaxTokens?: number,
   ) {
@@ -98,6 +100,16 @@ export class MockAdapter extends LlmAdapter {
       })
       return
     }
+    if (entry === 'hang-slow') {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'text-delta', index: 0, text: 'partial' }
+      await new Promise<void>((_resolve, reject) => {
+        const fail = (): void => { reject(new Error('aborted')) }
+        if (options.signal?.aborted) { setTimeout(fail, 50); return }
+        options.signal?.addEventListener('abort', () => { setTimeout(fail, 50) }, { once: true })
+      })
+      return
+    }
     const chunks = typeof entry === 'function' ? entry(options) : entry
     for (const chunk of chunks) {
       if (options.signal?.aborted) throw new Error('aborted')
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index fae9267347..d8cb5c4114 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -104,7 +104,11 @@ export interface Agent {
 
   /**
    * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next turn.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
    * @param message - identified content and its producer provenance.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.

From 853f929704222cf5ce186cbce277c6fa298c7f59 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Fri, 7 Aug 2026 16:25:23 +0800
Subject: [PATCH 017/262] refactor(agent-loop): tighten wake-latch comments

---
 packages/core/agent-loop/src/agent.ts | 24 +++++++++---------------
 1 file changed, 9 insertions(+), 15 deletions(-)

diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index 6701777a0f..6ef965e59e 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -112,8 +112,7 @@ export class ReactLoopAgent implements Agent {
 
   send(message: UserMessage, target: InboxTarget, wakeup: boolean): void {
     // Waking input cannot join an aborted activity, so it starts the next turn.
-    // The classification is captured BEFORE the insertion: a reentrant cancel
-    // from a synchronous splice observer must not reclassify this wake.
+    // Captured before the insertion so a reentrant cancel from a splice observer cannot reclassify it.
     const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted
     const resolvedTarget = wakingAfterAbort ? 'next-turn' : target
     this.inbox.splice(resolvedTarget, Infinity, 0, [message])
@@ -165,20 +164,16 @@ export class ReactLoopAgent implements Agent {
   /**
    * Start one driver, or latch its wake behind maintenance or an aborted
    * activity. A wake sent while idle always opens its turn boundary, even
-   * when its message is cleared before the driver claims; only a latched
-   * replay is suppressed when the queue no longer holds the wake.
-   * @param wakeAfterAbort - the send-time classification from {@link send}:
-   *   the wake landed after the abort fired. Captured before the inbox
-   *   insertion so a reentrant cancel cannot reclassify it.
+   * when its message was cleared; only a latched replay is suppressed when
+   * the queue no longer holds the wake.
+   * @param wakeAfterAbort - the {@link send} classification, captured before
+   *   the inbox insertion so a reentrant cancel cannot reclassify it.
    */
   private wakeDriver(wakeAfterAbort = false): void {
     if (this.phase.kind !== 'idle') {
-      // The current activity cannot deliver this wake: a maintenance task
-      // never reads the queue, and an aborted activity converges without
-      // restarting — both latch for the exiting activity to replay. A live
-      // driver claims queued work itself, so it needs no latch. A disposal
-      // cancel never latches: replaying would make `whenIdle()` wait on a
-      // full model turn over a session being torn down.
+      // Maintenance and aborted drivers cannot deliver the wake: latch it for
+      // replay at convergence. Live drivers claim queued work themselves;
+      // disposal never latches, so teardown waits on no model turn.
       const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
       if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
         this.phase.wakeRequested = true
@@ -328,8 +323,7 @@ export class ReactLoopAgent implements Agent {
     }
     if (!this.inbox.hasPending) return false
     phase.abort = new AbortController()
-    // The driver keeps running with a fresh controller: any latch set on the
-    // old one is stale, and the live driver claims the queue itself.
+    // A fresh controller makes a latch set on the old one stale: the live driver claims the queue itself.
     phase.wakeRequested = false
     phase.step = 0
     return true

From bdbc6c3da4b2579973574a0bea54a4d851b32a8e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:57:31 +0800
Subject: [PATCH 018/262] fix(windows): preserve graceful CLI shutdown

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  2 +
 ...08-08-native-windows-pull-request-ci.zh.md |  2 +
 apps/cli/src/profile-boot.ts                  | 69 +++++++++++--------
 apps/cli/tests/built-bin.e2e.ts               | 37 +++++++---
 5 files changed, 76 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index c9d06abacf..b1b0079115 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 8b6766cfa8df48c6c61410c06a410340a0c9bb21
-2026-08-08-native-windows-pull-request-ci.zh.md: 29cb1f725f4212c13974d642388edaf1df16b759
+2026-08-08-native-windows-pull-request-ci.md: 80fccabdc9ddebba2204732677da31363b74a184
+2026-08-08-native-windows-pull-request-ci.zh.md: 9d00f4fad6eb817968609c3af1f278cc6794e7c7
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 8b6766cfa8..80fccabdc9 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -16,6 +16,8 @@ The aggregate keeps workspace build and production-site failures blocking while
 
 The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
 
+The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
+
 Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 29cb1f725f..9d00f4fad6 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -16,6 +16,8 @@ Status: implemented
 
 首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
 
+下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
+
 受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
 
 ## 曾考虑的替代方案
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 4730ec7073..b49bd37535 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -10,7 +10,7 @@
 import { writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Context } from 'cordis'
+import { FiberState, type Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import {
   boot,
@@ -168,6 +168,10 @@ export interface RunProfileOptions {
   environment: EnvironmentSnapshot
 }
 
+function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void {
+  if (!signal.aborted) throw error
+}
+
 /**
  * Boot one profile invocation end to end and leave process lifetime to the
  * mounted plugins (or to the one-shot runner when `task` is present).
@@ -196,11 +200,16 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
 
   const app: { current?: Context } = {}
   const shutdown = createProcessShutdown(async () => { await app.current?.fiber.dispose() })
+  const signalShutdown = new AbortController()
+  const interrupt = (code: number): void => {
+    signalShutdown.abort()
+    shutdown.interrupt(code)
+  }
   // Signals own teardown throughout the startup window, not only after boot()
   // settles: an inserted front door can publish readiness before sibling rows
   // finish mounting.
-  process.on('SIGTERM', () => { shutdown.interrupt(options.task === undefined ? 0 : 143) })
-  process.on('SIGINT', () => { shutdown.interrupt(130) })
+  process.on('SIGTERM', () => { interrupt(options.task === undefined ? 0 : 143) })
+  process.on('SIGINT', () => { interrupt(130) })
   installFailLoud(NAME, process, async () => {
     await app.current?.fiber.dispose()
   })
@@ -243,33 +252,37 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     await options.prepare?.(hostCtx, composed.rows)
   })
   app.current = ctx
-  // A surface can dispose the whole tree while startup was still in flight
-  // (early SIGTERM); the Loader service goes with it and there is nothing to
-  // keep live.
-  if (watchProfilePatch && ctx.get('loader') !== undefined) {
-    // Config-only HMR for the live profile patch layer: the web bundle
-    // disables the shared module-reload `hmr` row (its reload lifecycle is
-    // untested), so when the composition leaves no HMR service, mount a
-    // watch-only instance with no module roots — cordis.patch.yml edits stay
-    // live on every long-lived surface. A silent skip would break the
-    // documented hot-reload contract. HMR injects the timer service, which a
-    // bare custom profile may not mount either.
-    if (ctx.get('hmr') === undefined) {
-      if (ctx.get('timer') === undefined) {
-        await ctx.loader.create({ name: '@cordisjs/plugin-timer' })
+  // A surface can dispose the whole tree while startup or this post-boot
+  // watcher setup is still in flight. Fiber state owns liveness; the local
+  // signal fact distinguishes that expected exit race from a real HMR error.
+  if (watchProfilePatch && !signalShutdown.signal.aborted && ctx.fiber.state === FiberState.ACTIVE) {
+    try {
+      // Config-only HMR for the live profile patch layer: the web bundle
+      // disables the shared module-reload `hmr` row (its reload lifecycle is
+      // untested), so when the composition leaves no HMR service, mount a
+      // watch-only instance with no module roots — cordis.patch.yml edits stay
+      // live on every long-lived surface. A silent skip would break the
+      // documented hot-reload contract. HMR injects the timer service, which a
+      // bare custom profile may not mount either.
+      if (ctx.get('hmr') === undefined) {
+        if (ctx.get('timer') === undefined) {
+          await ctx.loader.create({ name: '@cordisjs/plugin-timer' })
+        }
+        await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
       }
-      await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
+      await watchUserPatches(ctx, {
+        binName: NAME,
+        filename: composed.profile.patchPath,
+        compose: composeLive,
+      })
+      await watchUserPatches(ctx, {
+        binName: NAME,
+        filename: homePatchPath(),
+        compose: composeLive,
+      })
+    } catch (error) {
+      suppressSignalShutdownError(signalShutdown.signal, error)
     }
-    await watchUserPatches(ctx, {
-      binName: NAME,
-      filename: composed.profile.patchPath,
-      compose: composeLive,
-    })
-    await watchUserPatches(ctx, {
-      binName: NAME,
-      filename: homePatchPath(),
-      compose: composeLive,
-    })
   }
   return { ctx, shutdown }
 }
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index a42780581f..05e248a8f6 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -49,6 +49,7 @@ interface ProfileLifecycleFixture {
   ready: string
   settled: string
   disposed: string
+  interrupt: string
 }
 
 /**
@@ -61,16 +62,23 @@ function createProfileLifecycleFixture(): ProfileLifecycleFixture {
   const ready = join(home, 'ready')
   const settled = join(home, 'settled')
   const disposed = join(home, 'disposed')
+  const interrupt = join(home, 'interrupt')
   const bundleDir = join(home, 'lifecycle-bundle')
   mkdirSync(bundleDir, { recursive: true })
   writeFileSync(join(bundleDir, 'plugin.mjs'), [
-    "import { writeFileSync } from 'node:fs'",
+    "import { existsSync, writeFileSync } from 'node:fs'",
     "import { join } from 'node:path'",
     "export const name = 'profile-lifecycle-fixture'",
     'export function apply(ctx, config = {}) {',
     '  let active = true',
     '  // Keep the event loop alive so process lifetime is signal-owned, like a real surface.',
-    '  const heartbeat = setInterval(() => {}, 1000)',
+    '  // Windows has no deliverable SIGTERM; the marker emits the same process event there.',
+    '  let interrupted = false',
+    '  const heartbeat = setInterval(() => {',
+    '    if (interrupted || !existsSync(process.env.RAW_INTERRUPT_FILE)) return',
+    '    interrupted = true',
+    "    process.emit('SIGTERM')",
+    '  }, 20)',
     '  // Echo the mounted generation so the hot-reload e2e can assert both an',
     '  // applied override and its removal reverting to this bundle default.',
     "  writeFileSync(join(process.env.DSH_HOME, 'config-echo'), String(config.generation ?? 'bundle-default'))",
@@ -118,7 +126,7 @@ function createProfileLifecycleFixture(): ProfileLifecycleFixture {
   for (const file of ['package.json', 'cordis.patch.yml', 'plugin.mjs']) {
     writeFileSync(join(linkTarget, file), readFileSync(join(bundleDir, file)))
   }
-  return { home, ready, settled, disposed }
+  return { home, ready, settled, disposed, interrupt }
 }
 
 function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
@@ -131,10 +139,22 @@ function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
       RAW_READY_FILE: fixture.ready,
       RAW_SETTLED_FILE: fixture.settled,
       RAW_DISPOSED_FILE: fixture.disposed,
+      RAW_INTERRUPT_FILE: fixture.interrupt,
     },
   })
 }
 
+function requestProfileShutdown(
+  child: ReturnType<typeof startProfileLifecycle>,
+  fixture: ProfileLifecycleFixture,
+): void {
+  if (process.platform === 'win32') {
+    writeFileSync(fixture.interrupt, 'interrupt')
+    return
+  }
+  child.kill('SIGTERM')
+}
+
 function createEnvironmentProbeProfile(home: string, project: string): void {
   const pluginFile = join(project, 'environment-probe.mjs')
   writeFileSync(pluginFile, [
@@ -152,7 +172,8 @@ function createEnvironmentProbeProfile(home: string, project: string): void {
     "      if (chunk.type === 'text-delta') text += chunk.text",
     '    }',
     '    process.stdout.write(`${text}\\n`)',
-    "    process.kill(process.pid, 'SIGTERM')",
+    "    if (process.platform === 'win32') process.emit('SIGTERM')",
+    "    else process.kill(process.pid, 'SIGTERM')",
     '  })',
     '}',
     '',
@@ -321,9 +342,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     const child = startProfileLifecycle(fixture)
     try {
       await waitForFile(fixture.ready)
-      child.kill('SIGTERM')
+      requestProfileShutdown(child, fixture)
       const result = await child
-      expect(result.exitCode).toBe(0)
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}\nsignal: ${String(result.signal)}`).toBe(0)
       expect(result.signal).toBeUndefined()
       expect(existsSync(fixture.disposed)).toBe(true)
     } finally {
@@ -373,9 +394,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       ].join('\n'))
       await waitForFile(fixture.ready)
       expect(readFileSync(configFile, 'utf8')).toBe('home')
-      child.kill('SIGTERM')
+      requestProfileShutdown(child, fixture)
       const result = await child
-      expect(result.exitCode).toBe(0)
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}\nsignal: ${String(result.signal)}`).toBe(0)
       expect(result.signal).toBeUndefined()
       expect(existsSync(fixture.disposed)).toBe(true)
     } finally {

From 66a21a38b13a051af3d856cde2033e84af5a3aba Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 11:59:19 +0800
Subject: [PATCH 019/262] feat(subagent): add current-turn interrupt RPC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ctx.subagents.interrupt() stops one live continuable child's current turn
via Agent.cancel(cause, { keepInbox: true }) under either a human durable
parent address or an exact live ancestor Agent. Fire-and-return: admission
is synchronous, quiescence is not awaited. Pending inbox work, the
Activation, and published descendants are preserved; only a later waking
send resumes the parked FIFO queue. Absent, one-shot, and disposing
targets are accepted no-ops.

The new Host RPC subagent.interrupt calls only that primitive with user
authority — no catalog, history, persistence, or parent-registry lookup —
so a live child stays stoppable while its parent Agent is offline.

Refs #1535
---
 ...6-continuable-subagent-interrupt.i18n.yaml |   6 +
 ...26-08-06-continuable-subagent-interrupt.md |  42 ++++
 ...08-06-continuable-subagent-interrupt.zh.md |  42 ++++
 docs/cordis-catalog/events.md                 |   8 +-
 docs/cordis-catalog/services.md               |  20 +-
 .../client/connection/src/client/fixture.ts   |   2 +
 packages/client/connection/tests/fake-api.ts  |   3 +
 packages/client/runtime/tests/fake-api.ts     |   4 +
 .../cordis/tool-cordis/src/api-catalog.ts     |   8 +
 packages/host/apiproxy/src/api-proxy.ts       |  25 ++
 packages/host/apiproxy/src/api/index.ts       |   3 +-
 packages/host/apiproxy/src/api/rpc-map.ts     |   1 +
 .../host/apiproxy/src/api/subagents.schema.ts |  12 +
 packages/host/apiproxy/src/api/subagents.ts   |  18 ++
 packages/host/apiproxy/src/fetch/client.ts    |   4 +
 packages/host/apiproxy/src/fetch/handler.ts   |   2 +
 .../tests/api-proxy-subagents.spec.ts         |  55 ++++-
 .../apiproxy/tests/client-handler.spec.ts     |  27 +++
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   8 +
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   7 +-
 packages/subagent/subagent/README.zh.md       |   7 +-
 .../subagent/subagent/src/continuation.ts     |  71 ++++++
 packages/subagent/subagent/src/index.ts       |  20 ++
 .../subagent/tests/continuation.spec.ts       | 220 ++++++++++++++++++
 .../subagent/subagent/tests/service.spec.ts   |  10 +
 scripts/gen-cordis-catalog.ts                 |   1 +
 27 files changed, 613 insertions(+), 17 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
new file mode 100644
index 0000000000..fe6e8870f5
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+2026-08-06-continuable-subagent-interrupt.md: 729f1eb8259aa28aa771ed71872ebce9cadd4ed8
+2026-08-06-continuable-subagent-interrupt.zh.md: 15fe34d8b5e1d67623aabfe08710f341739e92e1
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
new file mode 100644
index 0000000000..729f1eb825
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -0,0 +1,42 @@
+# Agent Note: Continuable subagent current-turn interrupt
+
+Status: implemented
+
+English | [中文](2026-08-06-continuable-subagent-interrupt.zh.md)
+
+## Problem
+
+A running continuable subagent could not be stopped without destroying it. The continuation manager cancels child Agents only inside whole-Activation teardown (settlement, drain, scoped drain), `send_message`/`subagent.prompt` only add work, and the Web composer's Stop button was deliberately limited to ordinary sessions. A human watching a continuable child burn tokens on a wrong path had no lever short of killing the parent tree, and when the direct parent Agent was offline the child was entirely untouchable even though its Activation stayed live. One-shot runs have holder-owned disposal and task-kill; continuable children had no analogous current-turn control.
+
+## Decision
+
+`ctx.subagents.interrupt(targetSessionId, authority)` stops only the live target's current turn. The manager primitive authorizes synchronously, calls the existing `Agent.cancel(cause, { keepInbox: true })`, and returns `void` — fire-and-return: the cancel signal is guaranteed issued, target quiescence is not awaited. Nothing else changes: no Activation disposal, no handle release, no descendant cascade, no inbox clearing, and no `AgentLoop` or `CancelOptions` change. Because `keepInbox` parks the pending queue at idle, an interrupt never auto-starts the next queued follow-up; only a later explicit waking send resumes the preserved FIFO order.
+
+Authority is a closed two-variant union, deliberately wider than delivery authority because stopping a turn is idempotent and delivers no content:
+
+- `{ kind: 'user', parentSessionId }` — a human presents the durable direct-parent address. The live target's `session.header.parentSession` must match; no live parent Agent, catalog read, or persistence access is involved, which is exactly what keeps a live child stoppable while its parent Agent is offline. Cancel cause `user`.
+- `{ kind: 'ancestor', agent }` — an exact live ancestor Agent (direct parent or deeper). The caller must be the registry's current entry for its id (stale callers are rejected even for absent targets), must not be the target itself, and must appear in the Activation's materialization-time `ancestry` WeakSet. Cancel cause `parent`.
+
+Targets are resolved only in the manager's process-local Activation map. An absent id — unknown, one-shot, or naturally settled — is an accepted no-op, which uniformly covers completion races and repeat requests without leaking durable-catalog information; a target whose disposal transaction is already open is likewise an accepted no-op after authorization. One-shot lifecycle (holder `dispose()`, task-kill) is untouched. `SubagentService.interrupt()` treats a manager-less composition as an accepted no-op rather than `CONTINUATION_UNAVAILABLE`, because without a manager no manager-owned live Activation can exist.
+
+The Host RPC `subagent.interrupt` takes the continuable `SubagentAddress` and returns `{ accepted: true }`. Its implementation calls only the core primitive with `user` authority — deliberately no `catalogChild()`, `listChildren()`, `sessionQuery`, or parent-registry lookup. A live target with a mismatched parent address maps to `subagent-unauthorized`; unexpected failures map to `internal` without leaking error text onto the wire.
+
+## Alternatives considered
+
+**Route human interrupts through `session.cancel`.** The generic session cancel requires an attached ordinary session and rejects subagent-owned sessions; widening it would entangle subagent authority rules with ordinary session routing. A subagent-domain RPC keeps the address-based authorization and the parent-offline guarantee explicit.
+
+**Await target quiescence and return the turn outcome.** Cancellation is cooperative, so quiescence is unbounded; holding the RPC (and a `ChildLock` slot) open invites timeouts and convoying against delivery and disposal. Acceptance-of-signal is the only fact the caller needs, and races (natural completion, disposal) already settle idempotently.
+
+**Reuse whole-Activation disposal for interrupt.** Disposal cancels without `keepInbox`, flushes, captures, and releases the handle — it destroys queued work and the child's residency. Interrupt is a control operation on one turn, not a lifecycle operation on the Activation.
+
+**Extend `send_message`/`followup` authority to ancestors while at it.** Delivery injects content into a conversation and is not idempotent; its exact-direct-parent authority stays unchanged. Only interrupt gets the wider ancestor and address-based user authority.
+
+**Auto-resume the parked queue after an interrupt.** Immediately starting queued follow-up B after aborting A would make the interrupt look ignored and steal the human's window to redirect the child. Parking until an explicit waking send keeps the stop observable and the FIFO order intact.
+
+## Consequences
+
+A human or ancestor can now stop a runaway continuable turn without losing the child, its queued work, or its running descendants; the cost is a deliberately weak postcondition (`accepted` means "signal issued", so a target may remain visibly `running` until it observes the signal) that clients must render honestly. The parked-queue rule means an interrupted child sits idle with retained work until someone sends a waking message — an intentional human-in-the-loop pause, not a scheduler defect. The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
+
+## Testing
+
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
new file mode 100644
index 0000000000..15fe34d8b5
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: Continuable subagent 当前轮次中断
+
+Status: implemented
+
+[English](2026-08-06-continuable-subagent-interrupt.md) | 中文
+
+## Problem
+
+一个正在运行的 continuable subagent 无法在不销毁它的前提下被停止。继续执行管理器只在整个 Activation 拆除（结算、drain、scoped drain）内部取消子 Agent，`send_message`／`subagent.prompt` 只能增加工作，而 Web composer 的 Stop 按钮被刻意限制在普通会话。人类眼看着一个 continuable child 在错误路径上烧 token，除了干掉整个 parent 树没有任何手段；当直接 parent Agent 离线时，即使 child 的 Activation 仍然在线，它也完全不可触及。一次性运行有持有方拥有的 disposal 和 task-kill；continuable child 没有对应的当前轮次控制。
+
+## Decision
+
+`ctx.subagents.interrupt(targetSessionId, authority)` 只停止在线目标的当前轮次。管理器原语同步完成鉴权，调用现有的 `Agent.cancel(cause, { keepInbox: true })`，然后返回 `void`——fire-and-return：保证取消信号已发出，但不等待目标静止。其余一切不变：不 dispose Activation、不释放 handle、不级联后代、不清空 inbox，也不改动 `AgentLoop` 或 `CancelOptions`。由于 `keepInbox` 让待处理队列停在 idle，中断绝不会自动启动下一个排队的 follow-up；只有之后一次显式唤醒发送才按保留的 FIFO 顺序恢复。
+
+授权是一个封闭的双变体 union，刻意比投递权限更宽，因为停止一个轮次是幂等的且不投递任何内容：
+
+- `{ kind: 'user', parentSessionId }`——人类出示持久化直接 parent 地址。在线目标的 `session.header.parentSession` 必须匹配；不涉及在线 parent Agent、目录读取或持久化访问，这正是 parent Agent 离线时在线 child 仍可被停止的原因。取消 cause 为 `user`。
+- `{ kind: 'ancestor', agent }`——一个确切在线的 ancestor Agent（直接 parent 或更深）。调用方必须是注册表中其 id 的当前条目（过期调用方即使目标不存在也被拒绝），不得是目标本身，并且必须出现在 Activation 物化时记录的 `ancestry` WeakSet 中。取消 cause 为 `parent`。
+
+目标只在管理器进程本地的 Activation map 中解析。不存在的 id——未知、一次性或已自然结算——是被接受的 no-op，统一覆盖完成竞态和重复请求而不泄露持久化目录信息；disposal 事务已打开的目标在鉴权后同样是被接受的 no-op。一次性生命周期（持有方 `dispose()`、task-kill）不受影响。`SubagentService.interrupt()` 把未绑定管理器的组合视为被接受的 no-op 而不是 `CONTINUATION_UNAVAILABLE`，因为没有管理器就不可能存在管理器拥有的在线 Activation。
+
+Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回 `{ accepted: true }`。它的实现只以 `user` 授权调用核心原语——刻意不调用 `catalogChild()`、`listChildren()`、`sessionQuery` 或 parent 注册表查找。parent 地址不匹配的在线目标映射为 `subagent-unauthorized`；意外失败映射为 `internal`，不把错误文本泄漏到 wire。
+
+## Alternatives considered
+
+**让人类中断走 `session.cancel`。** 通用会话取消要求附着的普通会话并拒绝 subagent 拥有的会话；放宽它会把 subagent 权限规则缠进普通会话路由。subagent 域的 RPC 让基于地址的鉴权和 parent 离线保证保持显式。
+
+**等待目标静止并返回轮次结果。** 取消是协作式的，静止时间无上界；让 RPC（以及一个 `ChildLock` 槽位）保持打开会招致超时并与投递、disposal 形成排队。调用方需要的唯一事实是信号已被接受，而竞态（自然完成、disposal）本就幂等收敛。
+
+**复用整个 Activation 的 disposal 来做中断。** disposal 的取消不带 `keepInbox`，还会 flush、capture 并释放 handle——它销毁排队工作和 child 的驻留。中断是针对一个轮次的控制操作，不是针对 Activation 的生命周期操作。
+
+**顺手把 `send_message`／`followup` 权限扩展到 ancestor。** 投递向对话注入内容且不幂等；其确切直接 parent 权限保持不变。只有中断获得更宽的 ancestor 与基于地址的用户授权。
+
+**中断后自动恢复被暂停的队列。** 在中止 A 后立即启动排队的 follow-up B 会让中断看起来被忽略，并夺走人类重新引导 child 的窗口。暂停到显式唤醒发送为止，让停止可观察且 FIFO 顺序完整。
+
+## Consequences
+
+人类或 ancestor 现在可以停止一个失控的 continuable 轮次，而不丢失 child、其排队工作或正在运行的后代；代价是一个刻意保持弱的后置条件（`accepted` 表示"信号已发出"，目标在观察到信号前可能仍显示 `running`），客户端必须如实呈现。暂停队列规则意味着被中断的 child 会带着保留的工作停在 idle，直到有人发送唤醒消息——这是有意的 human-in-the-loop 暂停，不是调度器缺陷。Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+
+## Testing
+
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index ae16d10f07..edfd046430 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -699,7 +699,7 @@ A published child settled. Scope-filtered dispatch uses the same delegating pare
 
 Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:160`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-added` — emit
 
@@ -716,7 +716,7 @@ A provider became resolvable in the registry.
 
 Types: [SubagentProvider](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:134`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-removed` — emit
 
@@ -731,7 +731,7 @@ A provider left the registry. Accepted runs remain holder-owned.
 'subagent/provider-removed'(name: string): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:140`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/start` — emit
 
@@ -753,7 +753,7 @@ A provider established a published child. For in-process providers, `ctx.agents.
 
 Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:151`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
 
 ## `system-prompt/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a22c3464eb..caf081b5a6 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2071,6 +2071,22 @@ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
  */
 async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
 
+/**
+ * Interrupt one live continuable child's current turn under a human parent
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
+ * signal is issued before this returns, but the target may keep running
+ * until it observes the signal. Pending inbox work, the Activation, and
+ * published descendants are preserved; only a later waking send resumes the
+ * parked FIFO queue. An absent target — including a one-shot or unknown id —
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
+ * live Activation.
+ * @param targetSessionId - the durable child session id to interrupt.
+ * @param authority - the human parent address or exact live ancestor Agent.
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+ *   live target.
+ */
+interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
+
 /**
  * Deliver selected content from one live continuable child to its durable
  * direct parent. The child is the authority credential; callers cannot name a
@@ -2171,9 +2187,9 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:165`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
 ## `ctx.subprocess` — `SubprocessService` (abstract seam)
 
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index ec3199ee02..2a081284b2 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2203,6 +2203,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
       prompt: request => Promise.resolve(ok(request, {
         messageId: `fixture-message-${request.payload.childSessionId}` as never,
       })),
+      interrupt: request => Promise.resolve(ok(request, { accepted: true as const })),
     },
     host: {
       describe: request => ok(request, { version: '0.0.0-fixture', cwd: '/tmp/fixture', attachedSessions }),
@@ -2748,6 +2749,7 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'subagent.list': return this.api.subagents.list(request)
       case 'subagent.history': return this.api.subagents.history(request)
       case 'subagent.prompt': return this.api.subagents.prompt(request, signal)
+      case 'subagent.interrupt': return this.api.subagents.interrupt(request)
       case 'host.describe': return this.api.host.describe(request)
       case 'host.pickDirectory': return this.api.host.pickDirectory(request, new AbortController().signal)
       case 'host.listDirectory': return this.api.host.listDirectory(request, new AbortController().signal)
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index cc4504e538..ef5071316e 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -126,6 +126,9 @@ export class FakeApiClient implements IApiClient {
     prompt: (payload: unknown) => this.record('subagent.prompt', payload, Promise.resolve(ok({
       messageId: 'fake-message' as never,
     }))),
+    interrupt: (payload: unknown) => this.record('subagent.interrupt', payload, Promise.resolve(ok({
+      accepted: true as const,
+    }))),
   }
 
   readonly host: IApiClient['host'] = {
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index 2f4299ce6c..5e510c0012 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -140,10 +140,14 @@ export class FakeApiClient implements IApiClient {
   onSubagentPrompt: (payload: unknown) => Promise<RpcResponse<{ messageId: never }>>
     = () => Promise.resolve(ok({ messageId: 'fake-message' as never }))
 
+  onSubagentInterrupt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>>
+    = () => Promise.resolve(ok({ accepted: true as const }))
+
   readonly subagents: IApiClient['subagents'] = {
     list: (payload: unknown) => this.record('subagent.list', payload, this.onSubagentList(payload)),
     history: (payload: unknown) => this.record('subagent.history', payload, this.onSubagentHistory(payload)),
     prompt: (payload: unknown) => this.record('subagent.prompt', payload, this.onSubagentPrompt(payload)),
+    interrupt: (payload: unknown) => this.record('subagent.interrupt', payload, this.onSubagentInterrupt(payload)),
   }
 
   readonly host: IApiClient['host'] = {
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index dec95f3b5f..acaefa5d5f 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -928,6 +928,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>',
         jsDoc: '/**\n * Deliver one later message to a continuable child as its next FIFO turn. A\n * resident child\'s Agent inbox accepts it directly (waking a `waiting`\n * Activation), while an absent one is cold-resumed from its persisted\n * Session. The Agent inbox is the only queue, so every accepted message has\n * one observable order.\n * @param parent - the exact live direct parent authorizing this delivery.\n * @param childId - durable child session id.\n * @param content - user-role content to deliver.\n * @param options - durable provenance and caller cancellation, which stops the\n *   operation only before inbox acceptance.\n * @returns the accepted message\'s inbox id.\n * @throws when continuation services are unavailable, parent authority is\n *   rejected, or the message was not admitted.\n */',
       },
+      {
+        signature: 'interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void',
+        jsDoc: '/**\n * Interrupt one live continuable child\'s current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Pending inbox work, the Activation, and\n * published descendants are preserved; only a later waking send resumes the\n * parked FIFO queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */',
+      },
       {
         signature: 'async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>',
         jsDoc: '/**\n * Deliver selected content from one live continuable child to its durable\n * direct parent. The child is the authority credential; callers cannot name a\n * recipient. Reporting does not conclude the child\'s turn or Activation.\n * @param child - exact live reporting child.\n * @param content - selected model-facing content.\n * @param options - parent scheduling and pre-acceptance cancellation.\n * @returns the stable identity of the parent-accepted message.\n * @throws when continuation services are unavailable, sender authorization\n *   fails, or the direct parent is not live.\n */',
@@ -2787,6 +2791,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubagentFollowupOptions',
     declaration: 'export interface SubagentFollowupOptions {\n    readonly source: MessageSource;\n    readonly signal: AbortSignal;\n}',
   },
+  {
+    name: 'SubagentInterruptAuthority',
+    declaration: 'export type SubagentInterruptAuthority = {\n    readonly kind: \'user\';\n    readonly parentSessionId: SessionId;\n} | {\n    readonly kind: \'ancestor\';\n    readonly agent: Agent;\n};',
+  },
   {
     name: 'SubagentListEntry',
     declaration: 'export type SubagentListEntry = {\n    readonly kind: \'child\';\n    readonly id: SessionId;\n    readonly activity: \'running\' | \'inactive\';\n    readonly hasChildren: boolean;\n} & ({\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n} | {\n    readonly mode: \'continuable\';\n    readonly label: string;\n}) | {\n    readonly kind: \'diagnostic\';\n    readonly id: SessionId;\n    readonly reason: \'corrupt\' | \'unsupported\' | \'unavailable\';\n};',
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index cfcae423bc..52236b0f29 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -2013,6 +2013,31 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return subagentPromptError(request, error, signal)
         }
       },
+
+      // Deliberately no catalog, history, persistence, or parent Agent lookup:
+      // the core primitive alone authorizes the durable address against the
+      // live Activation, which is what keeps a live child interruptible while
+      // its parent Agent is offline. Absent targets are accepted no-ops there.
+      interrupt(request) {
+        const { parentSessionId, childSessionId } = request.payload
+        try {
+          ctx.subagents.interrupt(childSessionId, { kind: 'user', parentSessionId })
+        } catch (error: unknown) {
+          if (error instanceof SubagentError && error.code === 'UNAUTHORIZED') {
+            return Promise.resolve(err(request, {
+              code: 'subagent-unauthorized',
+              message: 'subagent does not belong to this parent',
+              details: { childSessionId },
+            }))
+          }
+          return Promise.resolve(err(request, {
+            code: 'internal',
+            message: 'subagent interrupt failed',
+            details: {},
+          }))
+        }
+        return Promise.resolve(ok(request, { accepted: true as const }))
+      },
     },
 
     workspace: {
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index cb83c5328d..5537a0e382 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -42,7 +42,8 @@ export type {
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
 export type {
-  SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, SubagentsApi,
+  SubagentAddress, SubagentCatalog, SubagentInterruptReceipt, SubagentListEntry,
+  SubagentPromptReceipt, SubagentsApi,
 } from './subagents.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
diff --git a/packages/host/apiproxy/src/api/rpc-map.ts b/packages/host/apiproxy/src/api/rpc-map.ts
index 9a8750c722..deb963db07 100644
--- a/packages/host/apiproxy/src/api/rpc-map.ts
+++ b/packages/host/apiproxy/src/api/rpc-map.ts
@@ -36,6 +36,7 @@ export interface RpcMethodMap {
   'subagent.list': SubagentsApi['list']
   'subagent.history': SubagentsApi['history']
   'subagent.prompt': SubagentsApi['prompt']
+  'subagent.interrupt': SubagentsApi['interrupt']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
   'host.listDirectory': HostApi['listDirectory']
diff --git a/packages/host/apiproxy/src/api/subagents.schema.ts b/packages/host/apiproxy/src/api/subagents.schema.ts
index 1987d568d3..6ed8bd3263 100644
--- a/packages/host/apiproxy/src/api/subagents.schema.ts
+++ b/packages/host/apiproxy/src/api/subagents.schema.ts
@@ -69,6 +69,18 @@ export const subagentPromptRequestSchema = z.object({
   content: z.array(contentBlockSchema),
 }) as unknown as z.ZodType<RequestPayload<'subagent.prompt'>>
 
+/** subagent.interrupt request payload. */
+export const subagentInterruptRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  mode: z.literal('continuable'),
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.interrupt'>>>
+
+/** subagent.interrupt response value. */
+export const subagentInterruptValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.interrupt'>>>
+
 const messageIdSchema = z.string() as unknown as z.ZodType<MessageId>
 
 /** subagent.prompt response value. */
diff --git a/packages/host/apiproxy/src/api/subagents.ts b/packages/host/apiproxy/src/api/subagents.ts
index 4c251dca7c..8efb452c2e 100644
--- a/packages/host/apiproxy/src/api/subagents.ts
+++ b/packages/host/apiproxy/src/api/subagents.ts
@@ -40,6 +40,11 @@ export interface SubagentPromptReceipt {
   messageId: MessageId
 }
 
+/** Uniform acknowledgement that one interrupt request was admitted. */
+export interface SubagentInterruptReceipt {
+  accepted: true
+}
+
 /** Durable parent/child address that selects subagent transport in the client. */
 export type SubagentAddress =
   & {
@@ -94,4 +99,17 @@ export interface SubagentsApi {
     >,
     signal: AbortSignal,
   ): Promise<RpcResponse<SubagentPromptReceipt>>
+
+  /**
+   * Interrupts a live continuable child's current turn under the address's
+   * durable direct-parent authority, without requiring a live parent Agent,
+   * consulting the catalog, or resuming anything. Fire-and-return: `accepted`
+   * acknowledges the admitted cancel signal, not target quiescence, so the
+   * child may remain visibly running briefly. Queued follow-ups are kept and
+   * parked; an absent, idle, or already-completed target is likewise
+   * `accepted`.
+   */
+  interrupt(
+    request: RpcRequest<Extract<SubagentAddress, { mode: 'continuable' }>>,
+  ): Promise<RpcResponse<SubagentInterruptReceipt>>
 }
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
index 0f54d76dbc..0ce935809f 100644
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -58,6 +58,7 @@ import {
 import { llmDiscoverModelsValueSchema, llmModelsValueSchema, llmProvidersValueSchema } from '../api/llm.schema.ts'
 import {
   subagentHistoryValueSchema,
+  subagentInterruptValueSchema,
   subagentListValueSchema,
   subagentPromptValueSchema,
 } from '../api/subagents.schema.ts'
@@ -96,6 +97,7 @@ export interface IApiClient {
     list(payload: RequestPayload<'subagent.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.list'>>>
     history(payload: RequestPayload<'subagent.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.history'>>>
     prompt(payload: RequestPayload<'subagent.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.prompt'>>>
+    interrupt(payload: RequestPayload<'subagent.interrupt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.interrupt'>>>
   }
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
@@ -171,6 +173,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'subagent.list': subagentListValueSchema,
   'subagent.history': subagentHistoryValueSchema,
   'subagent.prompt': subagentPromptValueSchema,
+  'subagent.interrupt': subagentInterruptValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
   'host.listDirectory': hostListDirectoryValueSchema,
@@ -407,6 +410,7 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('subagent.list', payload, signal),
     history: (payload, signal) => this.callUnary('subagent.history', payload, signal),
     prompt: (payload, signal) => this.callUnary('subagent.prompt', payload, signal),
+    interrupt: (payload, signal) => this.callUnary('subagent.interrupt', payload, signal),
   }
 
   readonly host: IApiClient['host'] = {
diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts
index d41b51ad6d..bd3bc3827a 100644
--- a/packages/host/apiproxy/src/fetch/handler.ts
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -60,6 +60,7 @@ import {
 import { llmDiscoverModelsRequestSchema, llmModelsRequestSchema, llmProvidersRequestSchema } from '../api/llm.schema.ts'
 import {
   subagentHistoryRequestSchema,
+  subagentInterruptRequestSchema,
   subagentListRequestSchema,
   subagentPromptRequestSchema,
 } from '../api/subagents.schema.ts'
@@ -95,6 +96,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'subagent.list': { schema: subagentListRequestSchema, invoke: (api, r, signal) => api.subagents.list(r, signal) },
   'subagent.history': { schema: subagentHistoryRequestSchema, invoke: (api, r, signal) => api.subagents.history(r, signal) },
   'subagent.prompt': { schema: subagentPromptRequestSchema, invoke: (api, r, signal) => api.subagents.prompt(r, signal) },
+  'subagent.interrupt': { schema: subagentInterruptRequestSchema, invoke: (api, r) => api.subagents.interrupt(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
   'host.listDirectory': { schema: hostListDirectoryRequestSchema, invoke: (api, r, signal) => api.host.listDirectory(r, signal) },
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index feb9ecb073..62c7e653e0 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -19,6 +19,7 @@ function bench(options: {
   childStatus?: 'idle' | 'running'
   entries?: object[]
   followupError?: Error
+  interruptError?: Error
   listError?: Error
   /** Persistence forgets the child entirely (the vanished-mid-read race). */
   storedChild?: false
@@ -53,6 +54,12 @@ function bench(options: {
   ) => options.followupError === undefined
     ? Promise.resolve('message-1')
     : Promise.reject(options.followupError))
+  const interrupt = vi.fn((
+    _targetSessionId: SessionId,
+    _authority: { kind: 'user'; parentSessionId: SessionId },
+  ) => {
+    if (options.interruptError !== undefined) throw options.interruptError
+  })
   const childHeader = {
     version: 0, id: CHILD, createdAt: 1, cwd: '/proj', parentSession: options.historyParent ?? PARENT,
   } satisfies SessionHeader
@@ -72,7 +79,7 @@ function bench(options: {
   })
   const ctx = new Context()
   ctx.provide('agents', { get: getAgent })
-  ctx.provide('subagents', { listChildren, followup })
+  ctx.provide('subagents', { listChildren, followup, interrupt })
   ctx.provide('sessions', {
     get: (id: SessionId) => options.liveChild === true && id === CHILD
       ? { id: CHILD, header: childHeader, events: childEvents }
@@ -90,7 +97,7 @@ function bench(options: {
   const api = createApiProxy(ctx, {
     defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
   })
-  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, parent }
+  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, interrupt, parent }
 }
 
 describe('subagent gateway', () => {
@@ -309,4 +316,48 @@ describe('subagent gateway', () => {
       error: { code: 'internal', message: 'subagent prompt failed' },
     })
   })
+
+  it('interrupts through the core primitive alone while the parent Agent is offline', async () => {
+    const { api, interrupt, getAgent, listChildren, inspect } = bench({ parentLive: false })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.rpcId).toBe('subagent-rpc')
+    expect(response.result).toEqual({ ok: true, value: { accepted: true } })
+    expect(interrupt).toHaveBeenCalledExactlyOnceWith(CHILD, { kind: 'user', parentSessionId: PARENT })
+    // No parent-registry, catalog, or history dependency: this is what keeps a
+    // live child interruptible after its parent Agent went offline.
+    expect(getAgent).not.toHaveBeenCalled()
+    expect(listChildren).not.toHaveBeenCalled()
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('maps interrupt authorization rejection without touching other services', async () => {
+    const { api, listChildren } = bench({
+      interruptError: new SubagentError('secret lineage', 'UNAUTHORIZED'),
+    })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.result).toEqual({
+      ok: false,
+      error: {
+        code: 'subagent-unauthorized',
+        message: 'subagent does not belong to this parent',
+        details: { childSessionId: CHILD },
+      },
+    })
+    expect(listChildren).not.toHaveBeenCalled()
+  })
+
+  it('hides unexpected interrupt failures behind the internal code', async () => {
+    const { api } = bench({ interruptError: new Error('secret activation state') })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.result).toEqual({
+      ok: false,
+      error: { code: 'internal', message: 'subagent interrupt failed', details: {} },
+    })
+  })
 })
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index ebd56ee551..476ebf344f 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -63,6 +63,7 @@ function scriptedApi(overrides: {
       list: r => ok(r, { entries: [], parentAvailable: false }),
       history: r => ok(r, { events: [], hasMore: false }),
       prompt: r => ok(r, { messageId: 'message-1' as never }),
+      interrupt: r => ok(r, { accepted: true as const }),
       ...overrides.subagents,
     },
     host: {
@@ -248,6 +249,32 @@ describe('unary round trip', () => {
     }
   })
 
+  it('round-trips subagent.interrupt and rejects a one-shot or incomplete address', async () => {
+    const interrupt = vi.fn((r: RpcRequest<unknown>) => ok(r, { accepted: true as const }))
+    const api = scriptedApi({ subagents: { interrupt } })
+    const c = client(api)
+
+    const accepted = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'continuable',
+    })
+    expect(accepted.result).toEqual({ ok: true, value: { accepted: true } })
+    expect(interrupt).toHaveBeenCalledTimes(1)
+
+    // The wire schema owns the mode fence: a one-shot address never reaches the impl.
+    const oneShot = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'one-shot',
+    } as never)
+    expect(oneShot.result.ok).toBe(false)
+    if (!oneShot.result.ok) expect(oneShot.result.error.code).toBe('bad-request')
+
+    const incomplete = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), mode: 'continuable',
+    } as never)
+    expect(incomplete.result.ok).toBe(false)
+    if (!incomplete.result.ok) expect(incomplete.result.error.code).toBe('bad-request')
+    expect(interrupt).toHaveBeenCalledTimes(1)
+  })
+
   it('rejects a method/path mismatch as bad-request', async () => {
     const handler = toFetchHandler(scriptedApi())
     const body = { type: 'client-request', rpcId: 'r1', method: 'session.create', payload: {} }
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index 6481d75837..83ada22644 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -128,6 +128,9 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           result: { ok: true, value: { messageId: 'message-1' as never } },
         }
       },
+      async interrupt(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
     },
     host: {
       async describe(request) {
@@ -433,6 +436,11 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
       mode: 'continuable',
       content: [],
     })).result).toEqual({ ok: true, value: { messageId: 'message-1' } })
+    expect((await c.subagents.interrupt({
+      parentSessionId: 'parent' as never,
+      childSessionId: 'child' as never,
+      mode: 'continuable',
+    })).result).toEqual({ ok: true, value: { accepted: true } })
   })
 
   it('keeps caller and connection aborts on command.execute', async () => {
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index f5ceedc743..250fd1a078 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: 9d2e38c8730f7b7f26e690aa878a4466fa7c2829
-README.zh.md: 341c18617af4d040ec44814fac1ec4502d9b8902
+README.md: 7de3a5563b274e925fba931a6d5de17e68cc397c
+README.zh.md: 6067555544ec0c32729beb2b4e3f773e31b747a1
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 9d2e38c873..7de3a5563b 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,6 +18,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `start(name, request)` | Validate an ordinary caller request, resolve its detached `one-shot` descriptor, then await the provider until a real one-shot child is published. Fulfillment returns a holder-owned `SubagentRun`; rejection means the provider has already cleaned every unpublished startup resource, while post-publication turn or infrastructure faults settle through the run. Continuable children never enter through this operation. |
 | `startContinuable(spec)` | Establish one durable continuable child and deliver its initial prompt. Resolves with `{ childId, messageId }` when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls the child back entirely. Requires `ctx.agents`, session persistence, and a provider with the `prepareContinuable` capability. |
 | `followup(parent, childId, content, { source, signal })` | Deliver one later message from the exact live direct parent as the child's next FIFO turn, matching `Agent.followup()` terminology, and return the accepted `MessageId`. A resident child's inbox accepts it directly (waking a waiting Activation); an absent one cold-resumes from its persisted Session. Requires `ctx.agents`; cold resume also requires session persistence. |
+| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Pending inbox work, the Activation, and published descendants are preserved; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`. |
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
@@ -76,7 +77,7 @@ Run events are scoped to the delegating parent. Every listener is independently
 
 Provider additions and removals also emit `subagent/provider-added` and `subagent/provider-removed`. Consumers such as the model-facing tool use those events because Cordis may load sibling plugins concurrently; configuration order does not prove registration order.
 
-Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority.
+Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority. Interrupt authority is deliberately wider than delivery authority: a human presents the durable direct-parent address so a live child stays stoppable while its parent Agent is offline, and any exact live ancestor recorded in the Activation's materialization lineage may stop its descendant, because stopping a turn is idempotent and delivers no content.
 
 When `ctx.sessionProjections` is available, the service registers two projection units. `subagentTiming` resets at each descriptor so a fork seed's ancestor work cannot enter the child's total, then accumulates `turn/start` → `turn/end` active time and retains same-cut `active.since` and `active.through` bounds for an open turn; while that turn remains open, `active.through` follows the latest folded event, giving an inactive consumer a conservative crash bound without mixing in newer session metadata. `subagent` folds the durable identity — mode plus creation label — from `subagent/descriptor` events with the same last-wins reset discipline, so a fork seed's ancestor descriptor stands only until the child's own overrides it; a malformed or unrecognized-version payload folds to the serializable `null` sentinel — indistinguishable from a log with no descriptor, and surviving every JSON push frame so a consumer replaces a stale identity instead of keeping it — and never throws.
 
@@ -84,7 +85,7 @@ When `ctx.sessionProjections` is available, the service registers two projection
 
 ## Collection model
 
-The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task, no result promise, and no public subagent cancellation — a caller sends later work with the `send_message` follow-up tool, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
+The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task or result promise — a caller sends later work with the `send_message` follow-up tool, while `interrupt()` stops only the current turn without disposing the child. The durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
 
 Continuable Activations await a best-effort final session flush without treating listener participation as durability confirmation. One-shot runs retain best-effort session checkpointing, so a completed one-shot child is discoverable after disposal only when its session actually reached persistence; the service does not invent a catalog entry from Task history when that checkpoint is absent.
 
@@ -99,7 +100,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **ACP children remain one-shot and are not trace-enumerable** — an ACP run has no local child session in the parent's session corpus. An ACP `prepareContinuable` requires persisting the remote session id in provider-specific descriptor data and a per-child continuation advertisement, since ACP `loadSession` support is negotiated per child rather than established by the method's presence. Remote providers also require a separate Activation ownership contract with equivalent authenticated control and child-first quiescence before they support continuable children.
-- **No host-user continuation** — `followup()` requires the exact live direct parent. A future host adapter needs a concrete authenticated interaction before the seam gains a separate user capability.
+- **No host-user continuation** — `followup()` requires the exact live direct parent. Only `interrupt()` accepts a durable parent-address user authority, because stopping a turn is idempotent and delivers no content; a future host adapter needs a concrete authenticated interaction before the seam gains a user delivery capability.
 - **No current-turn steering** — continuable messages and waking reports enqueue later turns; neither redirects an open turn.
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
 - **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with their admitted provenance. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 341c18617a..6067555544 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -18,6 +18,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
 | `startContinuable(spec)` | 建立一个持久化可继续子 agent，并投递其初始提示词。子 agent 的 inbox 接受该提示词时，兑现为 `{ childId, messageId }`，无需等待轮次开始或消息写入 Session 日志；此前任何失败都会以无 id 拒绝，并完全回滚该子 agent。要求 `ctx.agents`、会话持久化以及具备 `prepareContinuable` 能力的提供方。 |
 | `followup(parent, childId, content, { source, signal })` | 将来自确切在线直接父级的一条后续消息作为子 agent 的下一个 FIFO 轮次投递，术语与 `Agent.followup()` 一致，并返回被接受的 `MessageId`。驻留中的子 agent 由其 inbox 直接接受（唤醒处于 waiting 的 Activation）；不驻留的则从其持久化 Session 冷恢复。要求 `ctx.agents`；冷恢复还要求会话持久化。 |
+| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。待处理的 inbox 工作、Activation 与已发布的后代均保持不变；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。 |
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
@@ -76,7 +77,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
 
-可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代——因为停止一个轮次是幂等的，且不投递任何内容。
 
 当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
@@ -84,7 +85,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、没有结果 promise，也没有公开的子 agent 取消操作——调用方通过 `send_message` 后续操作工具发送后续工作，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task 或结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，而 `interrupt()` 只停止当前轮次，不 dispose 子 agent。持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
@@ -99,7 +100,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 ## 已知限制与暂缓事项
 
 - **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
-- **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。未来 host 适配器需要具体的经认证交互，才能让该 seam 获得单独的用户能力。
+- **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。只有 `interrupt()` 接受持久化 parent 地址形式的用户授权，因为停止一个轮次是幂等的且不投递任何内容；未来 host 适配器需要具体的经认证交互，才能让该 seam 获得用户投递能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
 - **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同其被接受时的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index 212536e713..ebac0a1296 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -103,6 +103,15 @@ export interface ContinuableStart {
   readonly messageId: MessageId
 }
 
+/**
+ * Authority under which one interrupt request is admitted. `user` carries the
+ * durable direct-parent address a human client presented; `ancestor` carries
+ * the exact live Agent object whose recorded lineage must contain the caller.
+ */
+export type SubagentInterruptAuthority =
+  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
+  | { readonly kind: 'ancestor'; readonly agent: Agent }
+
 /** Options for following up with one continuable child. */
 export interface SubagentFollowupOptions {
   /** Durable attribution retained on the delivered message; it grants no authority. */
@@ -412,6 +421,68 @@ export class SubagentContinuationManager {
     }
   }
 
+  /**
+   * Interrupt one live continuable child's current turn. Admission is
+   * synchronous and the effect is asynchronous: this authorizes the caller,
+   * requests `Agent.cancel(cause, { keepInbox: true })` on the target, and
+   * returns without waiting for the target to observe the signal or reach
+   * quiescence. The Activation, its handle, accepted pending inbox work, and
+   * already-published descendants are untouched; the parked queue resumes only
+   * on a later waking send.
+   *
+   * An absent target is an accepted no-op, which uniformly covers natural
+   * completion races, repeated requests, one-shot ids, and unknown ids without
+   * consulting the durable catalog. A target whose disposal transaction is
+   * already open is likewise an accepted no-op after authorization.
+   * @param targetSessionId - the durable child session id to interrupt.
+   * @param authority - the human parent address or exact live ancestor Agent.
+   * @throws {SubagentError} `UNAUTHORIZED` when the presented authority does
+   *   not own the live target: a stale or self-targeting ancestor caller, a
+   *   parent address that is not the live target's durable direct parent, or
+   *   an ancestor outside the target's recorded live lineage.
+   */
+  interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void {
+    if (authority.kind === 'ancestor') {
+      const caller = authority.agent
+      // A stale caller is rejected even when the target is absent, so a
+      // replaced same-id Agent can never probe this manager's state.
+      if (this.ctx.agents.get(caller.id) !== caller) {
+        throw new SubagentError(
+          `interrupting "${targetSessionId}" requires the exact live ancestor agent`,
+          'UNAUTHORIZED',
+        )
+      }
+      if (caller.id === targetSessionId) {
+        throw new SubagentError(
+          `agent "${caller.id}" cannot interrupt itself`,
+          'UNAUTHORIZED',
+        )
+      }
+    }
+    const activation = this.activations.get(targetSessionId)
+    if (activation === undefined) return
+    if (authority.kind === 'user') {
+      if (activation.handle.agent.session.header.parentSession !== authority.parentSessionId) {
+        throw new SubagentError(
+          `subagent "${targetSessionId}" belongs to another parent session`,
+          'UNAUTHORIZED',
+        )
+      }
+    } else if (!activation.ancestry.has(authority.agent)) {
+      throw new SubagentError(
+        `subagent "${targetSessionId}" is not a live descendant of agent "${authority.agent.id}"`,
+        'UNAUTHORIZED',
+      )
+    }
+    // Disposal already stopped the target with a whole-Activation teardown;
+    // a second cancel would be a redundant signal on a closing handle.
+    if (activation.disposal !== undefined) return
+    activation.handle.agent.cancel(
+      authority.kind === 'user' ? { kind: 'user' } : { kind: 'parent' },
+      { keepInbox: true },
+    )
+  }
+
   /**
    * Deliver explicitly selected content from one resident continuable child to
    * its durable direct parent. Sender authorization, parent resolution, and
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 5bcd53d6a5..e179bfd8b4 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -58,6 +58,7 @@ import type {
   ContinuableStart,
   ContinuableStartSpec,
   SubagentFollowupOptions,
+  SubagentInterruptAuthority,
   SubagentReportOptions,
 } from './continuation.ts'
 import SubagentActivationSetupRegistry from './activation-setup-registry.ts'
@@ -111,6 +112,7 @@ export type {
   ContinuableStartSpec,
   CoordinatorMessageSource,
   SubagentFollowupOptions,
+  SubagentInterruptAuthority,
   SubagentReportDelivery,
   SubagentReportMessageSource,
   SubagentReportOptions,
@@ -231,6 +233,24 @@ export class SubagentService extends Service {
     return this.requireContinuations().followup(parent, childId, content, options)
   }
 
+  /**
+   * Interrupt one live continuable child's current turn under a human parent
+   * address or an exact live ancestor Agent. Fire-and-return: the cancel
+   * signal is issued before this returns, but the target may keep running
+   * until it observes the signal. Pending inbox work, the Activation, and
+   * published descendants are preserved; only a later waking send resumes the
+   * parked FIFO queue. An absent target — including a one-shot or unknown id —
+   * is an accepted no-op, as is a manager-less composition, which cannot own a
+   * live Activation.
+   * @param targetSessionId - the durable child session id to interrupt.
+   * @param authority - the human parent address or exact live ancestor Agent.
+   * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+   *   live target.
+   */
+  interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void {
+    this.continuations?.interrupt(targetSessionId, authority)
+  }
+
   /**
    * Deliver selected content from one live continuable child to its durable
    * direct parent. The child is the authority credential; callers cannot name a
diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts
index dca06add38..9370676f76 100644
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -1717,3 +1717,223 @@ describe('continuable errors', () => {
     expect(ctx.agents.get(started.childId)).toBeUndefined()
   })
 })
+
+describe('SubagentService.interrupt', () => {
+  it('aborts the current turn durably, parks accepted follow-ups, and resumes them only on a waking send', async () => {
+    const releaseFirst = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('first'), gate: releaseFirst.promise },
+      { chunks: textResponse('second') },
+      { chunks: textResponse('third') },
+      { chunks: textResponse('fourth') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    await followup(ctx, parent, started.childId, message('parked B'))
+    await followup(ctx, parent, started.childId, message('parked C'))
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+
+    expect(cancelSpy).toHaveBeenCalledTimes(1)
+    expect(cancelSpy).toHaveBeenCalledWith({ kind: 'user' }, { keepInbox: true })
+    // Cancellation is cooperative: the held model call observes it on release.
+    releaseFirst.resolve(undefined)
+    await child.whenIdle()
+    // Parked, not resumed: no second model request follows the abort, the
+    // accepted follow-ups stay pending, and the same Activation stays resident.
+    expect(adapter.requests).toHaveLength(1)
+    expect(child.inbox.nextTurn).toHaveLength(2)
+    expect(child.status).toBe('idle')
+    expect(ctx.agents.get(started.childId)).toBe(child)
+
+    // Only an explicit waking send restores the driver; the parked items then
+    // run before it in the existing FIFO order.
+    await followup(ctx, parent, started.childId, message('waking D'))
+    await waitNoActivation(ctx, started.childId)
+    const loaded = await ctx.sessionPersistence.load(started.childId)
+    expect(userTexts(loaded.events)).toEqual(['child task', 'parked B', 'parked C', 'waking D'])
+    const turnEnds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => (event).data.reason.kind)
+    expect(turnEnds).toEqual(['aborted', 'completed', 'completed', 'completed'])
+  })
+
+  it('interrupts only the target while its resident descendant keeps running', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    const childCancel = vi.spyOn(child, 'cancel')
+    const grandchildCancel = vi.spyOn(grandchildAgent, 'cancel')
+
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+
+    expect(childCancel).toHaveBeenCalledTimes(1)
+    releaseChild.resolve(undefined)
+    await child.whenIdle()
+    // The target parks as a waiting owner; the published descendant was never
+    // signalled and keeps its own turn open.
+    expect(grandchildCancel).not.toHaveBeenCalled()
+    expect(ctx.agents.get(started.childId)).toBe(child)
+    expect(ctx.agents.get(grandchild.childId)).toBe(grandchildAgent)
+
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+    const loaded = await ctx.sessionPersistence.load(grandchild.childId)
+    const turnEnds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => (event).data.reason.kind)
+    expect(turnEnds).toEqual(['completed'])
+  })
+
+  it('authorizes the human address against the live target\'s durable direct parent', async () => {
+    const hold = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: hold.promise }])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    expect(() => { ctx.subagents.interrupt(started.childId, {
+      kind: 'user',
+      parentSessionId: SessionId('stranger'),
+    }) }).toThrow(/belongs to another parent session/)
+    expect(cancelSpy).not.toHaveBeenCalled()
+
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+    expect(cancelSpy).toHaveBeenCalledWith({ kind: 'user' }, { keepInbox: true })
+    hold.resolve(undefined)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('lets a deep exact live ancestor interrupt its descendant with the parent cause', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    const childCancel = vi.spyOn(child, 'cancel')
+    const grandchildCancel = vi.spyOn(grandchildAgent, 'cancel')
+
+    // Deep ancestor: the top-level parent interrupts the grandchild.
+    ctx.subagents.interrupt(grandchild.childId, { kind: 'ancestor', agent: parent })
+    expect(grandchildCancel).toHaveBeenCalledWith({ kind: 'parent' }, { keepInbox: true })
+    // Direct ancestor: the same authority kind covers the immediate parent.
+    ctx.subagents.interrupt(started.childId, { kind: 'ancestor', agent: parent })
+    expect(childCancel).toHaveBeenCalledWith({ kind: 'parent' }, { keepInbox: true })
+
+    releaseChild.resolve(undefined)
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('rejects self, sibling, stale, and unrelated ancestor callers without touching the target', async () => {
+    const releaseA = Promise.withResolvers<undefined>()
+    const releaseB = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('a'), gate: releaseA.promise },
+      { chunks: textResponse('b'), gate: releaseB.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const targetStart = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const target = ctx.agents.get(targetStart.childId)!
+    const siblingStart = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const sibling = ctx.agents.get(siblingStart.childId)!
+    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const stale = { ...parent, id: parent.id } as unknown as Agent
+    const cancelSpy = vi.spyOn(target, 'cancel')
+
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: target }) })
+      .toThrow(/cannot interrupt itself/)
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: sibling }) })
+      .toThrow(/not a live descendant/)
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: stranger }) })
+      .toThrow(/not a live descendant/)
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: stale }) })
+      .toThrow(/exact live ancestor/)
+    // A stale caller is rejected before target lookup, even for an absent id.
+    expect(() => { ctx.subagents.interrupt(SessionId('missing'), { kind: 'ancestor', agent: stale }) })
+      .toThrow(/exact live ancestor/)
+    expect(cancelSpy).not.toHaveBeenCalled()
+
+    releaseA.resolve(undefined)
+    releaseB.resolve(undefined)
+    await waitNoActivation(ctx, targetStart.childId)
+    await waitNoActivation(ctx, siblingStart.childId)
+  })
+
+  it('accepts absent and one-shot ids as no-ops without touching the one-shot Agent', async () => {
+    const { ctx, parent } = await setup([textResponse('one shot')])
+    ctx.subagents.interrupt(SessionId('missing'), { kind: 'user', parentSessionId: parent.id })
+    ctx.subagents.interrupt(SessionId('missing'), { kind: 'ancestor', agent: parent })
+
+    const run = await ctx.subagents.start('spawn', {
+      label: 'one-shot work',
+      prompt: message('one-shot work'),
+      parent,
+      signal: testSignal,
+    })
+    const oneShot = run.localAgent!
+    const cancelSpy = vi.spyOn(oneShot, 'cancel')
+    ctx.subagents.interrupt(run.id, { kind: 'user', parentSessionId: parent.id })
+    ctx.subagents.interrupt(run.id, { kind: 'ancestor', agent: parent })
+    expect(cancelSpy).not.toHaveBeenCalled()
+    await run.result
+    await run.dispose()
+  })
+
+  it('accepts an interrupt after natural completion', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await waitNoActivation(ctx, started.childId)
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+    ctx.subagents.interrupt(started.childId, { kind: 'ancestor', agent: parent })
+  })
+
+  it('accepts an interrupt that lost the race with disposal without signalling twice', async () => {
+    const hold = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: hold.promise }])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    // Scoped teardown opens the disposal transaction synchronously and issues
+    // its own whole-Activation cancel before this call returns.
+    const drained = ctx.subagents.drainContinuableDescendants([parent])
+    expect(cancelSpy).toHaveBeenCalledTimes(1)
+
+    // Interrupt after the cutoff: accepted no-op, no second signal, no waiting.
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+    expect(cancelSpy).toHaveBeenCalledTimes(1)
+
+    hold.resolve(undefined)
+    await drained
+  })
+})
diff --git a/packages/subagent/subagent/tests/service.spec.ts b/packages/subagent/subagent/tests/service.spec.ts
index 8b90719227..a50696cf2a 100644
--- a/packages/subagent/subagent/tests/service.spec.ts
+++ b/packages/subagent/subagent/tests/service.spec.ts
@@ -133,6 +133,16 @@ describe('SubagentService', () => {
     await expect(subagents.drainContinuableDescendants([])).resolves.toBeUndefined()
   })
 
+  it('treats interrupt as an accepted no-op when no manager was bound', async () => {
+    const { subagents } = await service()
+    // Without a continuation manager no live Activation can exist, so there is
+    // nothing to stop and nothing to authorize against.
+    expect(() => { subagents.interrupt(SessionId('child'), {
+      kind: 'user',
+      parentSessionId: SessionId('parent-1'),
+    }) }).not.toThrow()
+  })
+
   it('rejects continuable operations when their runtime services are absent', async () => {
     const { subagents } = await service()
     await expect(subagents.startContinuable({
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 54581a8605..c8ddb487ef 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -173,6 +173,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuableStartSpec: 'subagent.md',
   CoordinatorMessageSource: 'subagent.md',
   SubagentFollowupOptions: 'subagent.md',
+  SubagentInterruptAuthority: 'subagent.md',
   SubagentListEntry: 'subagent.md',
   SubagentProvider: 'subagent.md',
   SubagentReportDelivery: 'subagent.md',

From 82019134b1c3ff0cdcb7b4edf7d1f6a031b4ad7c Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 12:09:09 +0800
Subject: [PATCH 020/262] test(web): verify subagent.interrupt over the real
 composition

A browserless keyless-replay e2e boots the shipped web composition, holds
a continuable child's turn open with a replay hang entry, queues a
follow-up and interrupts over plain HTTP, and proves from the real
session state that the turn aborted, the follow-up parked without a new
turn, and a waking send resumed the preserved FIFO order.

Refs #1535
---
 apps/web/tests/subagent-interrupt.e2e.ts | 176 +++++++++++++++++++++++
 apps/web/tsconfig.json                   |   1 +
 tsconfig.host.json                       |   1 +
 3 files changed, 178 insertions(+)
 create mode 100644 apps/web/tests/subagent-interrupt.e2e.ts

diff --git a/apps/web/tests/subagent-interrupt.e2e.ts b/apps/web/tests/subagent-interrupt.e2e.ts
new file mode 100644
index 0000000000..e1e35e7981
--- /dev/null
+++ b/apps/web/tests/subagent-interrupt.e2e.ts
@@ -0,0 +1,176 @@
+// Web e2e scenario (browserless): the subagent.interrupt RPC against the real
+// composition. A live continuable child holds its model turn open through a
+// replay hang entry; plain HTTP queues a follow-up, interrupts the turn, and
+// proves from the real session state that the turn aborted, the follow-up
+// parked without auto-starting a new turn, and a later waking send resumed the
+// preserved FIFO order. No browser: the RPC surface is the product surface
+// under test, and PR-stacked UI coverage owns the composer interaction.
+import { existsSync } from 'node:fs'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { SessionId as sessionId, type SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-agent'
+import { launchWebScaffold, webSnapshotMode, type WebScaffold } from './scaffold.ts'
+
+const MODE = webSnapshotMode()
+const INITIAL = 'Explain event sourcing in one sentence.'
+const FOLLOWUP = 'Now give the same explanation to a human reader.'
+const WAKING = 'And add one concrete example.'
+
+type RpcResult<T> = { ok: true; value: T } | { ok: false; error: { code: string; message: string } }
+
+/** POST one unary RPC through the real HTTP carrier and unwrap its result. */
+async function rpc<T>(baseUrl: string, method: string, payload: unknown): Promise<RpcResult<T>> {
+  const response = await fetch(`${baseUrl}/api/${method}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      type: 'client-request',
+      rpcId: `interrupt-e2e-${method}-${crypto.randomUUID()}`,
+      method,
+      payload,
+    }),
+  })
+  if (!response.ok) throw new Error(`${method} failed over HTTP ${response.status}: ${await response.text()}`)
+  return (await response.json() as { result: RpcResult<T> }).result
+}
+
+/** Poll a synchronous condition (hook-safe; expect.poll is test-body only). */
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${what}`)
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}
+
+/** One text-only scripted model completion (no tool calls: real tools are mounted). */
+function textCompletion(text: string): object {
+  return {
+    kind: 'chunks',
+    chunks: [
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'text-delta', index: 0, text },
+      { type: 'block-end', index: 0, block: { type: 'text', text } },
+      { type: 'usage', usage: { inputTokens: 20, outputTokens: 8 } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ],
+  }
+}
+
+describe.skipIf(MODE === 'record')('web e2e: subagent.interrupt over the real composition', () => {
+  let scaffold: WebScaffold
+  let sidecarRoot: string
+  let readyFile: string
+  let parentId: SessionId
+  let childId: SessionId
+
+  beforeAll(async () => {
+    sidecarRoot = await mkdtemp(join(tmpdir(), 'dsh-web-subagent-interrupt-'))
+    readyFile = join(sidecarRoot, 'hang-ready')
+    // Whole-script replacement: the child's three model calls are the hang
+    // (turn 1, interrupted), the parked follow-up's turn, and the waking turn.
+    // The parent never runs a turn, so the child claims this primary script.
+    await writeFile(join(sidecarRoot, 'replay.override.json'), JSON.stringify([
+      { kind: 'hang', readyFile },
+      textCompletion('resumed response one'),
+      textCompletion('resumed response two'),
+    ]))
+    // Header-only primary fixture: the bare-array override replaces the
+    // derived script entirely; the path only anchors replay installation.
+    await writeFile(
+      join(sidecarRoot, 'session.jsonl'),
+      '{"type":"session","version":0,"id":"primary","createdAt":0}\n',
+    )
+    scaffold = await launchWebScaffold({
+      replayFixture: join(sidecarRoot, 'session.jsonl'),
+      replayOverride: join(sidecarRoot, 'replay.override.json'),
+    })
+
+    // A live parent Agent through the real API; no workspace or browser.
+    const created = await rpc<{ sessionId: string }>(scaffold.baseUrl, 'session.create', {
+      cwd: scaffold.workspaceCwd,
+    })
+    if (!created.ok) throw new Error(`session.create failed: ${created.error.code}`)
+    parentId = sessionId(created.value.sessionId)
+    const parent = scaffold.ctx.agents.get(parentId)
+    if (parent === undefined) throw new Error('created parent session did not publish a live Agent')
+
+    const started = await scaffold.ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'event-sourcing researcher',
+      signal: new AbortController().signal,
+      request: { prompt: [{ type: 'text', text: INITIAL }], parent },
+    })
+    childId = started.childId
+    // The hang entry writes readyFile after its prefix chunks, immediately
+    // before waiting for cancellation: the deterministic "turn is open" gate.
+    await waitFor(() => existsSync(readyFile), 'the held child turn to open')
+  }, 120_000)
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    await rm(sidecarRoot, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt teardown failed')
+  })
+
+  it('parks a queued follow-up on interrupt and resumes it FIFO on a waking send', async () => {
+    // Queue the follow-up while the turn is still open, then interrupt.
+    const queued = await rpc<{ messageId: string }>(scaffold.baseUrl, 'subagent.prompt', {
+      parentSessionId: parentId,
+      childSessionId: childId,
+      mode: 'continuable',
+      content: [{ type: 'text', text: FOLLOWUP }],
+    })
+    expect(queued).toMatchObject({ ok: true })
+
+    const settled = scaffold.whenTurnSettled()
+    const interrupted = await rpc<{ accepted: true }>(scaffold.baseUrl, 'subagent.interrupt', {
+      parentSessionId: parentId,
+      childSessionId: childId,
+      mode: 'continuable',
+    })
+    expect(interrupted).toMatchObject({ ok: true, value: { accepted: true } })
+    // accepted acknowledges the admitted cancel, not quiescence: wait for the
+    // aborted turn/end (the composition's first turn/end) before asserting.
+    expect(await settled).toBe(childId)
+
+    // Parked, not resumed: the Activation stays resident with an idle driver,
+    // the follow-up is retained, and no second turn opened.
+    const child = scaffold.ctx.agents.get(childId)
+    expect(child).toBeDefined()
+    expect(child!.status).toBe('idle')
+    expect(child!.inbox.nextTurn).toHaveLength(1)
+    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    const lastEnd = child!.session.events.filter(event => event.type === 'turn/end').at(-1)
+    expect((lastEnd)?.data.reason.kind).toBe('aborted')
+
+    // Only an explicit waking send resumes the parked queue, FIFO, then the
+    // child runs both turns to completion and settles.
+    const waking = await rpc<{ messageId: string }>(scaffold.baseUrl, 'subagent.prompt', {
+      parentSessionId: parentId,
+      childSessionId: childId,
+      mode: 'continuable',
+      content: [{ type: 'text', text: WAKING }],
+    })
+    expect(waking).toMatchObject({ ok: true })
+    await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
+
+    const loaded = await scaffold.ctx.sessionPersistence.load(childId)
+    // Human-origin messages only: the real composition also injects
+    // runtime-context snapshots as non-user-source messages.
+    const userTexts = loaded.events.flatMap(event => event.type === 'user/message'
+      && event.data.source.kind === 'user'
+      ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
+      : [])
+    expect(userTexts).toEqual([INITIAL, FOLLOWUP, WAKING])
+    const turnEndKinds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => (event).data.reason.kind)
+    expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
+  }, 120_000)
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 7fb84f1507..3fa6ba8905 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -67,6 +67,7 @@
     "tests/produced-file-mentions.e2e.ts",
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
+    "tests/subagent-interrupt.e2e.ts",
     "tests/sidebar-subagent-activity.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
     "tests/skill-tool-row.e2e.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 81f660c317..1997f0ea47 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -54,6 +54,7 @@
     "apps/web/tests/produced-files.e2e.ts",
     "apps/web/tests/produced-file-mentions.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
+    "apps/web/tests/subagent-interrupt.e2e.ts",
     "apps/web/tests/sidebar-subagent-activity.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",

From 57e9e6977c3065c461d3c5da38a2b841d6bb1ea1 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 12:50:44 +0800
Subject: [PATCH 021/262] docs(subagent): record the public interrupt in the
 continuation contract docs

The continuable-subagent core-data page and the continuation lifecycle
Agent Note claimed no public subagent cancellation existed; interrupt()
is now that one public stop. Both pages and their Chinese counterparts
state the shipped contract and link the owning interrupt note.

Refs #1535
---
 ...8-continuable-subagent-conversations.i18n.yaml |  4 ++--
 ...26-07-28-continuable-subagent-conversations.md |  6 +++---
 ...07-28-continuable-subagent-conversations.zh.md |  6 +++---
 docs/core-data-structures/subagent.i18n.yaml      |  4 ++--
 docs/core-data-structures/subagent.md             | 15 ++++++++++++++-
 docs/core-data-structures/subagent.zh.md          | 15 ++++++++++++++-
 scripts/type-equiv.manifest.json                  |  5 +++++
 7 files changed, 43 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 99629a74c0..82639d4aa8 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: a5a900c3bb30a8d965aabc0bf498f8399ee70e7a
-2026-07-28-continuable-subagent-conversations.zh.md: bde8e874ba27950dc0fab8449c6ba2ee49737d41
+2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
+2026-07-28-continuable-subagent-conversations.zh.md: 77f497ceeef35dcc519242dca30c81759cc3b907
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index a5a900c3bb..56d9abb2b0 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -131,7 +131,7 @@ Parent-originated delivery requires the parent to be live when admitted and keep
 
 ### Durability, disposal, and recovery
 
-Without Tasks there is no `task_output`, `task_kill`, Task status, per-message result promise, or public subagent cancellation operation. The caller signal can abort start or follow-up only before inbox acceptance. After acceptance, the parent cannot cancel the message, turn, or Activation through `ctx.subagents`; `Agent.cancel()` remains a lower-level Agent capability that this version does not expose through the subagent service.
+Without Tasks there is no `task_output`, `task_kill`, Task status, or per-message result promise. The caller signal can abort start or follow-up only before inbox acceptance. After acceptance, the parent cannot cancel the accepted message or dispose the Activation through `ctx.subagents`; the only public stop is the later [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md), which cancels the live target's current turn with `keepInbox` and leaves residency, pending work, and descendants intact.
 
 Host and manager teardown remains the lifecycle stop path. Manager unload applies it globally; a host applies it only below the exact top-level Agents it owns. Each form closes the applicable admission scope, stops the selected visible Activations, awaits admitted materializations in that scope, releases child-first, and preserves the durable Sessions.
 
@@ -145,7 +145,7 @@ Session and descriptor persistence survive restart. Activation state, Agent inbo
 
 This version covers continuable in-process children and leaves one-shot delegation unchanged. Remote providers require a separate Activation handle with equivalent authenticated control and child-first quiescence contracts before they can support the same behavior.
 
-It adds no host-user continuation, subagent steering operation, durable mailbox, cross-process lease, automatic replay of interrupted inbox work, team authority, workflow authority, public subagent cancellation operation, public residency query, new live-Activation or descendant limit, or runtime cache. Existing delegation-depth policy remains unchanged. Optional child-to-parent reporting is a later consumer of this lifecycle rather than part of the base continuable capability.
+It adds no host-user continuation, subagent steering operation, durable mailbox, cross-process lease, automatic replay of interrupted inbox work, team authority, workflow authority, public residency query, new live-Activation or descendant limit, or runtime cache; the later [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md) added the one public stop operation on top of this lifecycle. Existing delegation-depth policy remains unchanged. Optional child-to-parent reporting is a later consumer of this lifecycle rather than part of the base continuable capability.
 
 ## Alternatives considered
 
@@ -186,7 +186,7 @@ The implementation pins these behaviors:
 - `followup()` accepts only the exact live direct parent and rechecks that identity at the final no-await inbox-admission boundary after any materialization; durable message provenance cannot authorize delivery.
 - Continuation messages always use `Agent.followup()` and share its inbox FIFO, including when the child already has an open turn.
 - `ctx.subagents.followup()` and its `send_message` adapter return only the accepted `MessageId`; the continuation layer accepts no delivery target and defines no subagent-specific route result.
-- This version exposes no public subagent cancellation operation; caller signals stop start and follow-up only before inbox acceptance, while host-scoped and manager-global teardown retain child-first cleanup.
+- Caller signals stop start and follow-up only before inbox acceptance, while host-scoped and manager-global teardown retain child-first cleanup; the [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md) is the one public stop and does not enter teardown.
 - This version exposes no subagent steering operation or current-turn controller state.
 - An idle Agent with live owned children yields a `waiting` Activation whose `AgentHandle` remains retained.
 - A `next-turn` delivered to `waiting` wakes the same Activation; delivery after completed disposal cold-resumes a new Activation.
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index bde8e874ba..77f497ceee 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -131,7 +131,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 持久性、dispose 与恢复
 
-没有 Task 后，系统不再提供 `task_output`、`task_kill`、Task 状态、逐消息结果 promise 或公开 subagent 取消操作。调用方 signal 只能在 inbox 接受消息前中止 start 或 follow-up。消息被接受后，parent 不能通过 `ctx.subagents` 取消该消息、轮次或激活；`Agent.cancel()` 仍是底层 Agent 能力，但本版本不通过 subagent 服务暴露它。
+没有 Task 后，系统不再提供 `task_output`、`task_kill`、Task 状态或逐消息结果 promise。调用方 signal 只能在 inbox 接受消息前中止 start 或 follow-up。消息被接受后，parent 不能通过 `ctx.subagents` 取消已接受的消息或 dispose 激活；唯一的公开停止操作是后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)，它以 `keepInbox` 取消在线目标的当前轮次，驻留、待处理工作与后代均保持不变。
 
 宿主和管理器拆卸仍是生命周期停止路径。管理器卸载会全局应用它；宿主只会在自己确切拥有的顶层 Agent 之下应用它。两种形式都会关闭适用的准入作用域，停止选中的可见 Activation，等待该作用域中已获准的物化过程，按 child-first 顺序释放，并保留持久化 Session。
 
@@ -145,7 +145,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳契约，才能支持同样的行为。
 
-它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开 subagent 取消操作、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
+它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存；后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)在此生命周期之上补充了唯一的公开停止操作。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
 
 ## 曾考虑的替代方案
 
@@ -186,7 +186,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - `followup()` 只接受确切的在线直接 parent，并在任何物化之后的最终无 await 的 inbox 准入边界再次检查该身份；持久化消息来源信息不能授权投递。
 - 继续执行消息始终使用 `Agent.followup()` 并共享其 inbox FIFO，包括 child 已有开放轮次的情况。
 - `ctx.subagents.followup()` 及其 `send_message` 适配器只返回已接受的 `MessageId`；继续执行层不接受投递 target，也不定义 subagent 专属路由结果。
-- 本版本不暴露公开 subagent 取消操作；调用方 signal 只能在 inbox 接受消息前停止 start 和 follow-up，限定到宿主的拆卸与管理器全局拆卸则保留 child-first 清理。
+- 调用方 signal 只能在 inbox 接受消息前停止 start 和 follow-up，限定到宿主的拆卸与管理器全局拆卸则保留 child-first 清理；[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)是唯一的公开停止操作，且不进入拆卸流程。
 - 本版本不暴露 subagent steering 操作或当前轮次控制方状态。
 - 带有在线所持 child 的空闲 Agent 会产生 `waiting` 激活，其 `AgentHandle` 继续保留。
 - 向 `waiting` 投递 `next-turn` 会唤醒同一个激活；完成 dispose 后投递消息会冷恢复新激活。
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index eb708f33da..8c3aa46364 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: 4d7552eb5749284d90e31e62d8ac02e3d7a21b1d
-subagent.zh.md: ebcb1ce445c164352109d6613028c7a36c10d6d4
+subagent.md: fba934233fb7e890d6a68bd4cc7d37f90ab913ed
+subagent.zh.md: 70651397f82e2cf4c0fe18aa26ff8247484ca0aa
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 4d7552eb57..fba934233f 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -139,7 +139,20 @@ The Agent inbox is the only queue. Every continuation message becomes one `Agent
 
 Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` are durable provenance after admission and grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
 
-For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no public subagent cancellation or steering operation.
+For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no steering operation.
+
+`SubagentService.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its pending inbox work, and published descendants are untouched; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`.
+
+```ts type-equiv
+/**
+ * Authority under which one interrupt request is admitted. `user` carries the
+ * durable direct-parent address a human client presented; `ancestor` carries
+ * the exact live Agent object whose recorded lineage must contain the caller.
+ */
+type SubagentInterruptAuthority =
+  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
+  | { readonly kind: 'ancestor'; readonly agent: Agent }
+```
 
 Every Activation owns its `AgentHandle` and an `ownedChildren: Set<SessionId>`; because one Session has at most one live Activation, the child Session id identifies the live child without another runtime-incarnation reference. Starting a child or submitting parent-originated work registers the child in a continuation-managed parent's set before the child can run, and that parent cannot settle while the set is non-empty. A top-level or other non-continuation Agent has no Activation and stays outside the waiting graph. Child release happens only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal.
 
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index ebcb1ce445..70651397f8 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -139,7 +139,20 @@ Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `
 
 后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 在准入之后是持久的来源凭据，不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
 
-对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 subagent 取消或 steering（中途引导）操作。
+对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
+
+`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其待处理的 inbox 工作与已发布的后代均不受影响；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。
+
+```ts type-equiv
+/**
+ * Authority under which one interrupt request is admitted. `user` carries the
+ * durable direct-parent address a human client presented; `ancestor` carries
+ * the exact live Agent object whose recorded lineage must contain the caller.
+ */
+type SubagentInterruptAuthority =
+  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
+  | { readonly kind: 'ancestor'; readonly agent: Agent }
+```
 
 每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
 
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 095fa25b4f..5c2f3eb454 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1150,6 +1150,11 @@
       "symbol": "SubagentFollowupOptions",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentInterruptAuthority",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
     {
       "doc": "docs/core-data-structures/subagent.md",
       "symbol": "ContinuableStart",

From 336c84baf0ead4e5fefbd7d40725de982e05c1ae Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 10:27:43 +0800
Subject: [PATCH 022/262] docs(subagent): clarify interrupt edge cases

---
 .../2026-08-06-continuable-subagent-interrupt.i18n.yaml   | 4 ++--
 .../feature/2026-08-06-continuable-subagent-interrupt.md  | 8 ++++++--
 .../2026-08-06-continuable-subagent-interrupt.zh.md       | 8 ++++++--
 docs/cordis-catalog/services.md                           | 7 ++++---
 docs/core-data-structures/subagent.i18n.yaml              | 4 ++--
 docs/core-data-structures/subagent.md                     | 2 +-
 docs/core-data-structures/subagent.zh.md                  | 2 +-
 docs/event-producer-consumer.md                           | 8 ++++----
 packages/cordis/tool-cordis/src/api-catalog.ts            | 2 +-
 packages/host/apiproxy/src/api/subagents.ts               | 4 ++--
 packages/subagent/subagent/README.i18n.yaml               | 4 ++--
 packages/subagent/subagent/README.md                      | 3 ++-
 packages/subagent/subagent/README.zh.md                   | 3 ++-
 packages/subagent/subagent/src/continuation.ts            | 7 ++++---
 packages/subagent/subagent/src/index.ts                   | 7 ++++---
 15 files changed, 43 insertions(+), 30 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index fe6e8870f5..643bb9f9ac 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 729f1eb8259aa28aa771ed71872ebce9cadd4ed8
-2026-08-06-continuable-subagent-interrupt.zh.md: 15fe34d8b5e1d67623aabfe08710f341739e92e1
+2026-08-06-continuable-subagent-interrupt.md: 7bbc6ecf6736e9e34924113be984a3bf7436b9b9
+2026-08-06-continuable-subagent-interrupt.zh.md: 22a71bf4cd3d9b949ae8cf458a3c83b65739d396
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 729f1eb825..7bbc6ecf67 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -10,7 +10,7 @@ A running continuable subagent could not be stopped without destroying it. The c
 
 ## Decision
 
-`ctx.subagents.interrupt(targetSessionId, authority)` stops only the live target's current turn. The manager primitive authorizes synchronously, calls the existing `Agent.cancel(cause, { keepInbox: true })`, and returns `void` — fire-and-return: the cancel signal is guaranteed issued, target quiescence is not awaited. Nothing else changes: no Activation disposal, no handle release, no descendant cascade, no inbox clearing, and no `AgentLoop` or `CancelOptions` change. Because `keepInbox` parks the pending queue at idle, an interrupt never auto-starts the next queued follow-up; only a later explicit waking send resumes the preserved FIFO order.
+`ctx.subagents.interrupt(targetSessionId, authority)` stops only the live target's current turn. The manager primitive authorizes synchronously, calls the existing `Agent.cancel(cause, { keepInbox: true })`, and returns `void` — fire-and-return: the cancel signal is guaranteed issued, target quiescence is not awaited. Nothing else changes: no Activation disposal, no handle release, no descendant cascade, no inbox clearing, and no `AgentLoop` or `CancelOptions` change. Because `keepInbox` parks the unclaimed pending queue at idle, an interrupt never auto-starts the next queued follow-up; work already claimed into the interrupted turn belongs to that turn and is not requeued. Once the interrupted driver is idle, an explicit waking send resumes the preserved FIFO order.
 
 Authority is a closed two-variant union, deliberately wider than delivery authority because stopping a turn is idempotent and delivers no content:
 
@@ -35,7 +35,11 @@ The Host RPC `subagent.interrupt` takes the continuable `SubagentAddress` and re
 
 ## Consequences
 
-A human or ancestor can now stop a runaway continuable turn without losing the child, its queued work, or its running descendants; the cost is a deliberately weak postcondition (`accepted` means "signal issued", so a target may remain visibly `running` until it observes the signal) that clients must render honestly. The parked-queue rule means an interrupted child sits idle with retained work until someone sends a waking message — an intentional human-in-the-loop pause, not a scheduler defect. The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
+A human or ancestor can stop a runaway continuable turn without losing the child, its unclaimed queued work, or its running descendants; the cost is a deliberately weak postcondition (`accepted` means "signal issued", so a target may remain visibly `running` until it observes the signal) that clients must render honestly. The parked-queue rule means an interrupted child sits idle with retained work until a waking message arrives after the driver is idle — an intentional human-in-the-loop pause, not a scheduler defect. A waking send accepted during abort convergence currently remains queued without latching wake; Issue #1838 tracks the shared agent-loop correction.
+
+The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
+
+The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index 15fe34d8b5..22a71bf4cd 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`ctx.subagents.interrupt(targetSessionId, authority)` 只停止在线目标的当前轮次。管理器原语同步完成鉴权，调用现有的 `Agent.cancel(cause, { keepInbox: true })`，然后返回 `void`——fire-and-return：保证取消信号已发出，但不等待目标静止。其余一切不变：不 dispose Activation、不释放 handle、不级联后代、不清空 inbox，也不改动 `AgentLoop` 或 `CancelOptions`。由于 `keepInbox` 让待处理队列停在 idle，中断绝不会自动启动下一个排队的 follow-up；只有之后一次显式唤醒发送才按保留的 FIFO 顺序恢复。
+`ctx.subagents.interrupt(targetSessionId, authority)` 只停止在线目标的当前轮次。管理器原语同步完成鉴权，调用现有的 `Agent.cancel(cause, { keepInbox: true })`，然后返回 `void`——fire-and-return：保证取消信号已发出，但不等待目标静止。其余一切不变：不 dispose Activation、不释放 handle、不级联后代、不清空 inbox，也不改动 `AgentLoop` 或 `CancelOptions`。由于 `keepInbox` 让尚未领取的待处理队列停在 idle，中断绝不会自动启动下一个排队的 follow-up；已被领取进入中断轮次的工作属于该轮次，不会重新入队。被中断的 driver 进入 idle 后，一次显式唤醒发送会按保留的 FIFO 顺序恢复。
 
 授权是一个封闭的双变体 union，刻意比投递权限更宽，因为停止一个轮次是幂等的且不投递任何内容：
 
@@ -35,7 +35,11 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 ## Consequences
 
-人类或 ancestor 现在可以停止一个失控的 continuable 轮次，而不丢失 child、其排队工作或正在运行的后代；代价是一个刻意保持弱的后置条件（`accepted` 表示"信号已发出"，目标在观察到信号前可能仍显示 `running`），客户端必须如实呈现。暂停队列规则意味着被中断的 child 会带着保留的工作停在 idle，直到有人发送唤醒消息——这是有意的 human-in-the-loop 暂停，不是调度器缺陷。Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+人类或 ancestor 可以停止一个失控的 continuable 轮次，而不丢失 child、其尚未领取的排队工作或正在运行的后代；代价是一个刻意保持弱的后置条件（`accepted` 表示“信号已发出”，目标在观察到信号前可能仍显示 `running`），客户端必须如实呈现。暂停队列规则意味着被中断的 child 会带着保留的工作停在 idle，直到 driver 进入 idle 后收到唤醒消息——这是有意的 human-in-the-loop 暂停，不是调度器缺陷。在 abort 收敛期间被接受的唤醒发送目前会保持排队而不锁存 wake；Issue #1838 跟踪共享的 agent-loop 修正。
+
+仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
+
+Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
 
 ## Testing
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index caf081b5a6..59a9cf527d 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2075,9 +2075,10 @@ async followup( parent: Agent, childId: SessionId, content: ContentBlock[], opti
  * Interrupt one live continuable child's current turn under a human parent
  * address or an exact live ancestor Agent. Fire-and-return: the cancel
  * signal is issued before this returns, but the target may keep running
- * until it observes the signal. Pending inbox work, the Activation, and
- * published descendants are preserved; only a later waking send resumes the
- * parked FIFO queue. An absent target — including a one-shot or unknown id —
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
+ * and published descendants are preserved; claimed work is not requeued.
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+ * queue. An absent target — including a one-shot or unknown id —
  * is an accepted no-op, as is a manager-less composition, which cannot own a
  * live Activation.
  * @param targetSessionId - the durable child session id to interrupt.
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index 8c3aa46364..15d5e19578 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: fba934233fb7e890d6a68bd4cc7d37f90ab913ed
-subagent.zh.md: 70651397f82e2cf4c0fe18aa26ff8247484ca0aa
+subagent.md: 4de77c6232d73d4b4e9dd87e9afc7a077e61f1a0
+subagent.zh.md: 3310bb4bf8cad1314ec26eef9042955959aba5fe
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index fba934233f..4de77c6232 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -141,7 +141,7 @@ Follow-up authority comes from an exact live Agent tool context. The authenticat
 
 For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no steering operation.
 
-`SubagentService.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its pending inbox work, and published descendants are untouched; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`.
+`SubagentService.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its unclaimed pending inbox work, and published descendants are untouched; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup.
 
 ```ts type-equiv
 /**
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index 70651397f8..3310bb4bf8 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -141,7 +141,7 @@ Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `
 
 对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
 
-`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其待处理的 inbox 工作与已发布的后代均不受影响；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。
+`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。
 
 ```ts type-equiv
 /**
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 940d89eae0..acd2bc5e91 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -37,10 +37,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:160`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
-| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:134`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:151`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:43`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index acaefa5d5f..1fd08a5c95 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -930,7 +930,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void',
-        jsDoc: '/**\n * Interrupt one live continuable child\'s current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Pending inbox work, the Activation, and\n * published descendants are preserved; only a later waking send resumes the\n * parked FIFO queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */',
+        jsDoc: '/**\n * Interrupt one live continuable child\'s current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Unclaimed pending inbox work, the Activation,\n * and published descendants are preserved; claimed work is not requeued.\n * Once the interrupted driver is idle, a waking send resumes the parked FIFO\n * queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */',
       },
       {
         signature: 'async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>',
diff --git a/packages/host/apiproxy/src/api/subagents.ts b/packages/host/apiproxy/src/api/subagents.ts
index 8efb452c2e..a85f4bc750 100644
--- a/packages/host/apiproxy/src/api/subagents.ts
+++ b/packages/host/apiproxy/src/api/subagents.ts
@@ -105,8 +105,8 @@ export interface SubagentsApi {
    * durable direct-parent authority, without requiring a live parent Agent,
    * consulting the catalog, or resuming anything. Fire-and-return: `accepted`
    * acknowledges the admitted cancel signal, not target quiescence, so the
-   * child may remain visibly running briefly. Queued follow-ups are kept and
-   * parked; an absent, idle, or already-completed target is likewise
+   * child may remain visibly running briefly. Unclaimed queued follow-ups are
+   * kept and parked; an absent, idle, or already-completed target is likewise
    * `accepted`.
    */
   interrupt(
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 250fd1a078..9b9843af87 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: 7de3a5563b274e925fba931a6d5de17e68cc397c
-README.zh.md: 6067555544ec0c32729beb2b4e3f773e31b747a1
+README.md: eb1baa39231a2c058b3ada1a23b7b87e2bb2e384
+README.zh.md: 8402df3e4ff2559898dfd4dd512ab1601c9ec61d
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7de3a5563b..eb1baa3923 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,7 +18,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `start(name, request)` | Validate an ordinary caller request, resolve its detached `one-shot` descriptor, then await the provider until a real one-shot child is published. Fulfillment returns a holder-owned `SubagentRun`; rejection means the provider has already cleaned every unpublished startup resource, while post-publication turn or infrastructure faults settle through the run. Continuable children never enter through this operation. |
 | `startContinuable(spec)` | Establish one durable continuable child and deliver its initial prompt. Resolves with `{ childId, messageId }` when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls the child back entirely. Requires `ctx.agents`, session persistence, and a provider with the `prepareContinuable` capability. |
 | `followup(parent, childId, content, { source, signal })` | Deliver one later message from the exact live direct parent as the child's next FIFO turn, matching `Agent.followup()` terminology, and return the accepted `MessageId`. A resident child's inbox accepts it directly (waking a waiting Activation); an absent one cold-resumes from its persisted Session. Requires `ctx.agents`; cold resume also requires session persistence. |
-| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Pending inbox work, the Activation, and published descendants are preserved; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`. |
+| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup. |
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
@@ -102,6 +102,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **ACP children remain one-shot and are not trace-enumerable** — an ACP run has no local child session in the parent's session corpus. An ACP `prepareContinuable` requires persisting the remote session id in provider-specific descriptor data and a per-child continuation advertisement, since ACP `loadSession` support is negotiated per child rather than established by the method's presence. Remote providers also require a separate Activation ownership contract with equivalent authenticated control and child-first quiescence before they support continuable children.
 - **No host-user continuation** — `followup()` requires the exact live direct parent. Only `interrupt()` accepts a durable parent-address user authority, because stopping a turn is idempotent and delivers no content; a future host adapter needs a concrete authenticated interaction before the seam gains a user delivery capability.
 - **No current-turn steering** — continuable messages and waking reports enqueue later turns; neither redirects an open turn.
+- **Wake gap during cancellation convergence** — a waking follow-up accepted after the interrupt signal is issued but before the active driver becomes idle remains queued until another waking send. Issue #1838 owns the agent-loop wake latch, which also affects ordinary session cancellation.
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
 - **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with their admitted provenance. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
 - **No durable report mailbox** — reports require a live direct parent and provide acceptance identity rather than exactly-once delivery or a read receipt.
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 6067555544..8402df3e4f 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -18,7 +18,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
 | `startContinuable(spec)` | 建立一个持久化可继续子 agent，并投递其初始提示词。子 agent 的 inbox 接受该提示词时，兑现为 `{ childId, messageId }`，无需等待轮次开始或消息写入 Session 日志；此前任何失败都会以无 id 拒绝，并完全回滚该子 agent。要求 `ctx.agents`、会话持久化以及具备 `prepareContinuable` 能力的提供方。 |
 | `followup(parent, childId, content, { source, signal })` | 将来自确切在线直接父级的一条后续消息作为子 agent 的下一个 FIFO 轮次投递，术语与 `Agent.followup()` 一致，并返回被接受的 `MessageId`。驻留中的子 agent 由其 inbox 直接接受（唤醒处于 waiting 的 Activation）；不驻留的则从其持久化 Session 冷恢复。要求 `ctx.agents`；冷恢复还要求会话持久化。 |
-| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。待处理的 inbox 工作、Activation 与已发布的后代均保持不变；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。 |
+| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。尚未领取的待处理 inbox 工作、Activation 与已发布的后代均保持不变；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。 |
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
@@ -102,6 +102,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 - **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
 - **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。只有 `interrupt()` 接受持久化 parent 地址形式的用户授权，因为停止一个轮次是幂等的且不投递任何内容；未来 host 适配器需要具体的经认证交互，才能让该 seam 获得用户投递能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
+- **取消收敛期间存在唤醒缺口**：中断信号发出后、活动 driver 进入 idle 前被接受的唤醒型 follow-up 会保持排队，直到另一条唤醒发送到达。Issue #1838 负责 agent-loop 的唤醒锁存；普通会话取消也受此影响。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
 - **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同其被接受时的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
 - **没有持久化的上报 mailbox**：上报需要实时直接父级，提供的是接受标识，不保证恰好一次投递，也不提供已读回执。
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index ebac0a1296..67cc177fe1 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -426,9 +426,10 @@ export class SubagentContinuationManager {
    * synchronous and the effect is asynchronous: this authorizes the caller,
    * requests `Agent.cancel(cause, { keepInbox: true })` on the target, and
    * returns without waiting for the target to observe the signal or reach
-   * quiescence. The Activation, its handle, accepted pending inbox work, and
-   * already-published descendants are untouched; the parked queue resumes only
-   * on a later waking send.
+   * quiescence. The Activation, its handle, accepted unclaimed inbox work, and
+   * already-published descendants are untouched; work already claimed into the
+   * interrupted turn is not requeued. Once the interrupted driver is idle, a
+   * waking send resumes the parked queue.
    *
    * An absent target is an accepted no-op, which uniformly covers natural
    * completion races, repeated requests, one-shot ids, and unknown ids without
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index e179bfd8b4..8bf4efb5d0 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -237,9 +237,10 @@ export class SubagentService extends Service {
    * Interrupt one live continuable child's current turn under a human parent
    * address or an exact live ancestor Agent. Fire-and-return: the cancel
    * signal is issued before this returns, but the target may keep running
-   * until it observes the signal. Pending inbox work, the Activation, and
-   * published descendants are preserved; only a later waking send resumes the
-   * parked FIFO queue. An absent target — including a one-shot or unknown id —
+   * until it observes the signal. Unclaimed pending inbox work, the Activation,
+   * and published descendants are preserved; claimed work is not requeued.
+   * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+   * queue. An absent target — including a one-shot or unknown id —
    * is an accepted no-op, as is a manager-less composition, which cannot own a
    * live Activation.
    * @param targetSessionId - the durable child session id to interrupt.

From 5793614b866de1e7af82a9627728d8b733da6c1b Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 12:45:37 +0800
Subject: [PATCH 023/262] feat(web): expose continuable subagent interrupt

The composer's single primary action now stops a running continuable
child: Session.cancel() routes a continuable address through
subagent.interrupt (ordinary sessions keep session.cancel; one-shot
addresses stay uncancellable), and InputBar switches the same Send button
to Stop while a continuable child runs. A running parent-offline child
keeps the default composer with disabled input so that Stop stays
reachable; the read-only takeover returns once it stops.

Refs #1535
---
 ...07-27-web-subagent-conversations.i18n.yaml |   4 +-
 .../2026-07-27-web-subagent-conversations.md  |  12 +-
 ...026-07-27-web-subagent-conversations.zh.md |  12 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |   4 +-
 ...26-08-06-continuable-subagent-interrupt.md |   4 +-
 ...08-06-continuable-subagent-interrupt.zh.md |   4 +-
 .../offline-composer.expected.md              |  25 ++
 apps/web/tests/subagent-interrupt-ui.e2e.ts   | 271 ++++++++++++++++++
 apps/web/tsconfig.json                        |   1 +
 .../runtime/src/client/sessions/session.ts    |  15 +-
 packages/client/runtime/tests/session.spec.ts |  30 +-
 .../ui-conversation/src/client/locales.ts     |   2 +
 .../src/client/skeleton/InputBar.tsx          |  25 +-
 .../ui-conversation/tests/input-bar.spec.tsx  |  46 ++-
 packages/client/ui-subagent/README.i18n.yaml  |   4 +-
 packages/client/ui-subagent/README.md         |   4 +-
 packages/client/ui-subagent/README.zh.md      |   4 +-
 .../client/ui-subagent/src/client/index.ts    |   6 +-
 .../ui-subagent/tests/browser-plugin.spec.ts  |   9 +-
 tsconfig.host.json                            |   1 +
 20 files changed, 433 insertions(+), 50 deletions(-)
 create mode 100644 apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
 create mode 100644 apps/web/tests/subagent-interrupt-ui.e2e.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 56952f8b69..4ec9a77d72 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: edaaa97bbfcf0ce1751db84d8fc2d3ab07af8b03
-2026-07-27-web-subagent-conversations.zh.md: 4c5e670cc46621b889d8463daa90afbf43bde30f
+2026-07-27-web-subagent-conversations.md: da4de7d4bcd23f61459eba3fee8108b0af1c95f9
+2026-07-27-web-subagent-conversations.zh.md: 43d9710ec2b63a09bd3db029f172746d63d91cfe
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index edaaa97bbf..da4de7d4bc 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -20,7 +20,7 @@ Every opened child carries a catalog-derived address `{ parentSessionId, childSe
 
 The generic Host domain preserves the same ownership boundary. `session.history` and the source side of `session.fork` read an attached Session or inspect persistence without acquiring an Agent; history folds cold projection values from that exact inspected prefix, while a fork publishes an ordinary independent session. Generic Agent-bound session, command, and goal routes return `agent-busy` for session-backed subagents, as do explicit-id `session.create` adoption and attached-only queue controls. The denial classifier accepts the coarse `origin` marker, a `subagent/descriptor` in the session's own suffix, or exact live runtime ownership by the parent; these signals only prevent generic ownership and never replace catalog mode or direct-parent authorization.
 
-The ordinary Stop action is absent from addressed child conversations. `SubagentService.followup()` owns admission only until inbox acceptance and intentionally exposes no public child cancellation operation. A later cancellation design needs an explicit authority and lifecycle contract rather than falling through to `session.cancel`.
+Stopping an addressed child never falls through to `session.cancel`. `SubagentService.followup()` owns admission only until inbox acceptance and grants no cancellation handle; a running continuable child is stopped through the dedicated `subagent.interrupt` route under the [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md), which parks pending work instead of discarding it. One-shot children remain uncancellable from the Web.
 
 This decision covers Web discovery, transcript viewing, and parent-authorized human continuation. It does not make a subagent independently user-owned; that product remains [interactive side sessions](../../proposed/feature/2026-07-08-interactive-side-sessions.md).
 
@@ -45,7 +45,7 @@ Healthy rows reuse the standard session projections retained in the list mirror.
 
 Selecting a row records its exact address before opening the resident client `Session`. History pagination, event folding, tool render intents, titles, and live mux reconciliation reuse the ordinary conversation machinery. Breadcrumbs use catalog labels, follow parent links only through `origin: 'subagent'` rows, include the first ordinary owner, and keep ordinary forks single-level. Forking an addressed subagent creates an ordinary fork with direct source lineage and attaches it to the nearest workspace-owning ancestor. The catalog is an ARIA tree with lazy ArrowRight/ArrowLeft disclosure, linear ArrowUp/ArrowDown navigation, Home/End, Escape, and focus restoration.
 
-A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false. When enabled, its Send action admits another FIFO turn even if the child is currently running; it never becomes Stop. Prompt failures retain the draft through the ordinary error behavior.
+A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input disabled so the same primary Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter admits another FIFO turn even while the child runs, and the single primary action follows the ordinary running convention: Send while idle, Stop while running, routed through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
 
 Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation seam.
 
@@ -89,7 +89,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 
 **Auto-resume an absent parent.** Rejected because continuation requires the exact live direct parent. Child navigation must not mutate the parent lifecycle.
 
-**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and the continuation seam exposes no authority-safe cancellation handle.
+**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and, at this decision's time, the continuation seam exposed no authority-safe cancellation handle. The later [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md) added that explicit authority as a dedicated subagent route; falling through to `session.cancel` remains rejected.
 
 **Show only continuable children.** Rejected because the durable catalog deliberately describes both session-backed modes. One-shot transcripts remain useful even though they never accept follow-ups.
 
@@ -103,9 +103,9 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 
 - Host protocol tests pin schemas including required boolean expandability, id echoing, mode verification, non-activating history, exact-parent enforcement, FIFO admission receipts, cancellation, and sanitized failure mapping.
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
-- Client object tests pin retained and restored addresses, one-shot read-only rejection, history routing, continuable prompt routing, no addressed cancellation, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
+- Client object tests pin retained and restored addresses, one-shot read-only and cancel rejection, history routing, continuable prompt and interrupt routing, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
 - jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, and adaptive long-duration presentation, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
@@ -114,4 +114,4 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Parent availability, child activity, and `hasChildren` are snapshots. Publication, disposal, another sender, or another process may win after listing; typed prompt failure remains expected.
 - A child may publish between history fetch and mux subscription, so the existing sequence reconciliation also covers the cold-to-live addressed path.
 - Persisted origin adds one deliberately weak product-classification field to child headers and list projections; it cannot become an authorization shortcut.
-- The UI has no child cancellation, durable outcome, Activation identity, deletion, or independently interactive offline mode, and its text must not imply those capabilities. Active-turn duration measures logged work rather than Activation residency.
+- Beyond the current-turn Stop of a running continuable child ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)), the UI has no child cancellation, durable outcome, Activation identity, deletion, or independently interactive offline mode, and its text must not imply those capabilities. Active-turn duration measures logged work rather than Activation residency.
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 4c5e670cc4..43d9710ec2 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -20,7 +20,7 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。
 
-已寻址 child 对话不提供普通 Stop 操作。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，并有意不公开任何 child 取消操作。后续取消设计需要显式的授权与生命周期契约，而不能回退到 `session.cancel`。
+停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)，该契约会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
 
 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)。
 
@@ -45,7 +45,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 时如此。启用后，即使 child 正在运行，其 Send 操作也会准入另一个 FIFO 轮次，绝不会变成 Stop。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，只禁用其输入区，让同一个 primary Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 也会准入另一个 FIFO 轮次，而唯一的 primary 操作遵循普通运行约定：空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
@@ -89,7 +89,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，而继续执行 seam 不会公开具备安全授权的取消句柄。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
@@ -103,9 +103,9 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 - 宿主协议测试固定 schema（包括必需的布尔可展开性）、id 回显、mode 校验、非激活式历史、确切 parent 强制要求、FIFO 准入回执、取消与脱敏后的失败映射。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
-- 客户端对象测试固定已保留与已恢复的地址、one-shot 只读拒绝、历史路由、可继续提示词路由、已寻址对话不提供取消、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
+- 客户端对象测试固定已保留与已恢复的地址、one-shot 只读与取消拒绝、历史路由、可继续提示词与中断路由、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
 - jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行及自适应长耗时呈现，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
@@ -114,4 +114,4 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
 - child 可能在历史获取与 mux 订阅之间发布，因此现有序号归并也涵盖从冷态转为存活的已寻址路径。
 - 持久化 origin 会为 child header 与列表投影添加一个有意保持弱约束的产品分类字段；它不能变成授权捷径。
-- UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
+- 除对正在运行的可继续 child 的当前轮次 Stop（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 643bb9f9ac..5cf5601fc0 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 7bbc6ecf6736e9e34924113be984a3bf7436b9b9
-2026-08-06-continuable-subagent-interrupt.zh.md: 22a71bf4cd3d9b949ae8cf458a3c83b65739d396
+2026-08-06-continuable-subagent-interrupt.md: 1792d4c6d25858c861be0ff920206d0d4e684f41
+2026-08-06-continuable-subagent-interrupt.zh.md: ff9887481d1ded2743c7c8f9f162413fb6581d70
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 7bbc6ecf67..1792d4c6d2 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,8 +39,8 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
+The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract). The model-facing `interrupt_agent` tool builds on this primitive in the stacked follow-up PR for issue #1535.
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index 22a71bf4cd..ff9887481d 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,8 +39,8 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。
diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
new file mode 100644
index 0000000000..6ea7b83bff
--- /dev/null
+++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
@@ -0,0 +1,25 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "Ask a research subagent to"
+    - text: /
+    - button "event-sourcing researcher" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Explain event sourcing in one sentence. {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation" [disabled]:
+  - img
+- text: Available only on the last message of a completed turn
+- button "Context injection @deepseek-ai/dsh-system-prompt":
+  - img
+  - img
+  - text: Context injection @deepseek-ai/dsh-system-prompt
+- paragraph: partial
+- status: Deep diving...
+- textbox "Parent session offline; sending is unavailable but you can still stop the run" [disabled]
+- button "Commands" [disabled]:
+  - img
+- 'button "Access mode, current: Workspace Write" [disabled]': Workspace Write
+- button "Stop generating"
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
new file mode 100644
index 0000000000..be72f6546b
--- /dev/null
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -0,0 +1,271 @@
+// Web e2e scenario: the composer's primary action interrupts a running
+// continuable child. The child holds its model turn open through a replay
+// hang entry; the browser proves the single primary Send/Stop toggle, the
+// parent-offline disabled-input-with-Stop composer, the subagent.interrupt
+// (never session.cancel) transport, the parked follow-up, and the FIFO resume
+// on a waking send.
+//
+// Replay-binding note: only the PRIMARY script can hang, and scripts bind by
+// first-call order, so the child issues the composition's first model call
+// (claiming the overridden primary) and the parent's one UI prompt — needed
+// so the non-blank parent renders its header catalog — binds to a derived
+// child fixture afterwards.
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-agent'
+import {
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
+
+const BASE_FIXTURE = fileURLToPath(new URL('./snapshots/live-interactions/session.jsonl', import.meta.url))
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/subagent-interrupt', import.meta.url))
+const OFFLINE_COMPOSER_EXPECTED = join(SNAPSHOT_DIR, 'offline-composer.expected.md')
+const MODE = webSnapshotMode()
+const LABEL = 'event-sourcing researcher'
+const INITIAL = 'Explain event sourcing in one sentence.'
+const FOLLOWUP = 'Now give the same explanation to a human reader.'
+const WAKING = 'And add one concrete example.'
+const PARKED_ANSWER = 'parked follow-up answer'
+const WAKING_ANSWER = 'waking answer'
+
+/** Poll a synchronous condition (hook-safe; expect.poll is test-body only). */
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${what}`)
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}
+
+/** One text-only scripted model completion (no tool calls: real tools are mounted). */
+function textCompletion(text: string): object {
+  return {
+    kind: 'chunks',
+    chunks: [
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'text-delta', index: 0, text },
+      { type: 'block-end', index: 0, block: { type: 'text', text } },
+      { type: 'usage', usage: { inputTokens: 20, outputTokens: 8 } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ],
+  }
+}
+
+describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running continuable child', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let sidecarRoot: string
+  let childId: SessionId
+  let tripwire: ReturnType<typeof watchConsole>
+  const apiCalls: string[] = []
+
+  beforeAll(async () => {
+    sidecarRoot = await mkdtemp(join(tmpdir(), 'dsh-web-subagent-interrupt-ui-'))
+    const readyFile = join(sidecarRoot, 'hang-ready')
+    // The child claims this whole-script replacement: held turn 1, then the
+    // parked follow-up and waking turns.
+    await writeFile(join(sidecarRoot, 'replay.override.json'), JSON.stringify([
+      { kind: 'hang', readyFile },
+      textCompletion(PARKED_ANSWER),
+      textCompletion(WAKING_ANSWER),
+    ]))
+    await writeFile(
+      join(sidecarRoot, 'session.jsonl'),
+      '{"type":"session","version":0,"id":"primary","createdAt":0}\n',
+    )
+    // The parent's one prompted turn replays this recorded single text-only
+    // call (binding is positional, not lineage-aware).
+    const parentTurnPath = join(sidecarRoot, 'parent-turn.jsonl')
+    const base = await readFile(BASE_FIXTURE, 'utf8')
+    const [header, ...events] = base.trimEnd().split('\n')
+    if (header === undefined) throw new Error('base replay fixture has no header')
+    await writeFile(parentTurnPath, [
+      header
+        .replace('"id":"{{sessionId}}"', '"id":"recorded-parent-turn"')
+        .replace(/"createdAt":\d+/, '"createdAt":1784998084442'),
+      ...events,
+      '',
+    ].join('\n'))
+    scaffold = await launchWebScaffold({
+      replayFixture: join(sidecarRoot, 'session.jsonl'),
+      replayOverride: join(sidecarRoot, 'replay.override.json'),
+      replayChildFixtures: [parentTurnPath],
+    })
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    page.on('request', (request) => {
+      const path = new URL(request.url()).pathname
+      if (path.startsWith('/api/')) apiCalls.push(path)
+    })
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspace(page, scaffold.workspaceCwd)
+
+    const parent = scaffold.ctx.agents.roots()[0]
+    if (parent === undefined) throw new Error('fresh workspace did not publish its parent Agent')
+    // The child's first model call claims the primary override and holds.
+    const started = await scaffold.ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: LABEL,
+      signal: new AbortController().signal,
+      request: { prompt: [{ type: 'text', text: INITIAL }], parent },
+    })
+    childId = started.childId
+    await waitFor(() => existsSync(readyFile), 'the held child turn to open')
+
+    // One prompted parent turn makes the parent non-blank so the session
+    // header (and its subagent catalog action) renders.
+    const parentSettled = scaffold.whenTurnSettled()
+    const parentInput = page.locator('textarea:enabled').first()
+    await parentInput.fill('Ask a research subagent to explain event sourcing.')
+    await parentInput.press('Enter')
+    expect(await parentSettled).toBe(parent.id)
+
+    // Reload onto the restart baseline (the proven route to a freshly
+    // discovered catalog), with the child still live and running host-side.
+    const warningStart = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await page.getByRole('button', { name: /1 subagent/ }).waitFor({ timeout: 15_000 })
+    acknowledgeReloadConnectionLoss(tripwire, warningStart)
+    expect(scaffold.ctx.agents.get(childId)?.status).toBe('running')
+  }, 120_000)
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    await browser?.close().catch((error: unknown) => failures.push(error))
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    if (sidecarRoot !== undefined) {
+      await rm(sidecarRoot, { recursive: true, force: true })
+        .catch((error: unknown) => failures.push(error))
+    }
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt UI teardown failed')
+  })
+
+  it('locks input but keeps the same primary Stop when the parent is offline', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
+    // Simulate a parent that went offline: the catalog delivers
+    // parentAvailable: false while the child Activation stays live (the
+    // interrupt RPC itself needs no live parent — PR 1's host coverage).
+    const pattern = '**/api/subagent.list'
+    await page.route(pattern, async (route) => {
+      const response = await route.fetch()
+      const body = await response.json() as {
+        result: { ok: true; value: { parentAvailable: boolean } } | { ok: false }
+      }
+      if (body.result.ok) body.result.value.parentAvailable = false
+      await route.fulfill({ response, json: body })
+    })
+    try {
+      await page.getByRole('button', { name: /1 subagent/ }).click()
+      await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click()
+      const input = page.getByRole('textbox', {
+        name: 'Parent session offline; sending is unavailable but you can still stop the run',
+      })
+      await input.waitFor({ timeout: 15_000 })
+      expect(await input.isDisabled()).toBe(true)
+      // Still exactly one primary action, and it is an enabled Stop.
+      const stop = page.getByRole('button', { name: 'Stop generating' })
+      expect(await stop.count()).toBe(1)
+      expect(await stop.isEnabled()).toBe(true)
+      expect(await page.getByRole('button', { name: 'Send message' }).count()).toBe(0)
+      await compareOrRefreshGolden(
+        OFFLINE_COMPOSER_EXPECTED,
+        await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd),
+        MODE,
+      )
+    } finally {
+      await page.unroute(pattern)
+    }
+  }, 60_000)
+
+  it('interrupts through subagent.interrupt, parks the follow-up, and resumes it FIFO', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-flow'))
+    // Reselect the child with the truthful catalog: parent available again.
+    await page.getByRole('navigation', { name: 'Session hierarchy' })
+      .getByRole('button').first().click()
+    await page.getByRole('button', { name: /1 subagent/ }).click()
+    await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click()
+    const input = page.getByRole('textbox', { name: 'Message the agent' })
+    await input.waitFor({ timeout: 15_000 })
+    expect(await input.isDisabled()).toBe(false)
+
+    // Queue a follow-up while the turn is open; the primary stays Stop.
+    const promptResponse = page.waitForResponse(response =>
+      new URL(response.url()).pathname === '/api/subagent.prompt')
+    await input.fill(FOLLOWUP)
+    await input.press('Enter')
+    expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
+      .toMatchObject({ ok: true })
+
+    const aborted = new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off()
+        reject(new Error('interrupt did not reach an aborted turn/end'))
+      }, 30_000)
+      const off = scaffold.ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => {
+        if (session.id !== childId || event.type !== 'turn/end') return
+        clearTimeout(timer)
+        off()
+        if (event.data.reason.kind === 'aborted') resolve()
+        else reject(new Error(`expected an aborted turn/end, got ${event.data.reason.kind}`))
+      })
+    })
+    const stop = page.getByRole('button', { name: 'Stop generating' })
+    expect(await stop.count()).toBe(1)
+    const interruptResponse = page.waitForResponse(response =>
+      new URL(response.url()).pathname === '/api/subagent.interrupt')
+    await stop.click()
+    expect(((await (await interruptResponse).json()) as {
+      result: { ok: boolean; value?: { accepted: boolean } }
+    }).result).toMatchObject({ ok: true, value: { accepted: true } })
+    // The addressed child stops through its own RPC, never the generic one.
+    expect(apiCalls.filter(path => path === '/api/session.cancel')).toEqual([])
+    await aborted
+
+    // Parked: the Activation stays resident and idle with the retained
+    // follow-up; the primary returns to Send without a new turn starting.
+    await expect.poll(() => scaffold.ctx.agents.get(childId)?.status, { timeout: 15_000 }).toBe('idle')
+    const child = scaffold.ctx.agents.get(childId)
+    expect(child).toBeDefined()
+    expect(child!.inbox.nextTurn).toHaveLength(1)
+    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    await page.getByRole('button', { name: 'Send message' }).waitFor({ timeout: 15_000 })
+
+    // Only the waking send resumes the parked queue, FIFO, to settlement.
+    await input.fill(WAKING)
+    await input.press('Enter')
+    await expect.poll(() => page.getByText(PARKED_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
+    await expect.poll(() => page.getByText(WAKING_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
+    await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
+
+    const loaded = await scaffold.ctx.sessionPersistence.load(childId)
+    const userTexts = loaded.events.flatMap(event => event.type === 'user/message'
+      && event.data.source.kind === 'user'
+      ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
+      : [])
+    expect(userTexts).toEqual([INITIAL, FOLLOWUP, WAKING])
+    const turnEndKinds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => event.data.reason.kind)
+    expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('keeps its snapshot inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['offline-composer.expected.md'])
+  })
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 3fa6ba8905..606f257e56 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -68,6 +68,7 @@
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
     "tests/subagent-interrupt.e2e.ts",
+    "tests/subagent-interrupt-ui.e2e.ts",
     "tests/sidebar-subagent-activity.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
     "tests/skill-tool-row.e2e.ts",
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 075fd686ea..659afcac4a 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -281,17 +281,22 @@ export class Session implements SessionFace {
 
   /**
    * Stop the active turn while the Host preserves pending inbox work; failures
-   * land in promptError (same error-strip display slot).
+   * land in promptError (same error-strip display slot). A continuable
+   * subagent address routes through `subagent.interrupt`, whose durable
+   * parent-address authority works without a live parent Agent; a one-shot
+   * address stays uncancellable (the UI offers no stop action, so this arm is
+   * defensive).
    * @returns the cancel result.
    */
   async cancel(): Promise<RpcResult<{ accepted: true }>> {
-    if (this.address !== undefined) {
+    const address = this.address
+    if (address !== undefined && address.mode === 'one-shot') {
       const result: RpcResult<{ accepted: true }> = {
         ok: false,
         error: {
           code: 'subagent-delivery-unavailable',
           message: 'subagent activation cancellation is unavailable',
-          details: { childSessionId: this.address.childSessionId },
+          details: { childSessionId: address.childSessionId },
         },
       }
       this.promptError = { op: 'stop', error: result.error }
@@ -300,7 +305,9 @@ export class Session implements SessionFace {
     }
     let result: RpcResult<{ accepted: true }>
     try {
-      result = (await this.api.sessions.cancel({ sessionId: this.sessionId })).result
+      result = address !== undefined
+        ? (await this.api.subagents.interrupt(address)).result
+        : (await this.api.sessions.cancel({ sessionId: this.sessionId })).result
     } catch (error) {
       result = transportError(error)
     }
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index b5400ecff9..5d5f292f92 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -639,7 +639,7 @@ describe('paging', () => {
 })
 
 describe('prompt and cancel errors', () => {
-  it('routes an addressed child through non-activating history and continuation prompt only', async () => {
+  it('routes an addressed child through non-activating history, continuation prompt, and interrupt only', async () => {
     const api = new FakeApiClient()
     const session = new Session(SID, api, {
       address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
@@ -650,7 +650,7 @@ describe('prompt and cancel errors', () => {
     const cancelled = await session.cancel()
 
     expect(prompted).toEqual({ ok: true, value: { accepted: true } })
-    expect(cancelled).toMatchObject({ ok: false, error: { code: 'subagent-delivery-unavailable' } })
+    expect(cancelled).toEqual({ ok: true, value: { accepted: true } })
     expect(api.callsOf('subagent.history')).toEqual([
       { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable', maxMessages: 50 },
     ])
@@ -660,15 +660,37 @@ describe('prompt and cancel errors', () => {
         content: [{ type: 'text', text: '继续' }],
       },
     ])
+    expect(api.callsOf('subagent.interrupt')).toEqual([
+      { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
+    ])
     expect(api.callsOf('session.history')).toEqual([])
     expect(api.callsOf('session.prompt')).toEqual([])
     expect(api.callsOf('session.cancel')).toEqual([])
+    // A successful interrupt leaves no stop error behind.
+    expect(session.getSnapshot().promptError).toBeNull()
     expect(session.getSnapshot().subagent).toEqual({
       address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
       parentAvailable: true,
     })
   })
 
+  it('lands an interrupt business failure in promptError with op=stop', async () => {
+    const api = new FakeApiClient()
+    api.onSubagentInterrupt = () => Promise.resolve(err({
+      code: 'subagent-unauthorized', message: 'nope', details: { childSessionId: SID },
+    }) as never)
+    const session = new Session(SID, api, {
+      address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
+      parentAvailable: true,
+    })
+    await session.open()
+    const cancelled = await session.cancel()
+    expect(cancelled).toMatchObject({ ok: false, error: { code: 'subagent-unauthorized' } })
+    expect(session.getSnapshot().promptError).toMatchObject({
+      op: 'stop', error: { code: 'subagent-unauthorized' },
+    })
+  })
+
   it('keeps one-shot history readable without exposing prompt or cancel transport', async () => {
     const api = new FakeApiClient()
     const session = new Session(SID, api, {
@@ -676,12 +698,16 @@ describe('prompt and cancel errors', () => {
     })
     await session.open()
     const prompted = await session.prompt([{ type: 'text', text: '继续' }], 'queue')
+    const cancelled = await session.cancel()
 
     expect(prompted).toMatchObject({ ok: false, error: { code: 'subagent-not-resumable' } })
+    expect(cancelled).toMatchObject({ ok: false, error: { code: 'subagent-delivery-unavailable' } })
     expect(api.callsOf('subagent.history')).toEqual([
       { parentSessionId: PARENT, childSessionId: SID, mode: 'one-shot', maxMessages: 50 },
     ])
     expect(api.callsOf('subagent.prompt')).toEqual([])
+    expect(api.callsOf('subagent.interrupt')).toEqual([])
+    expect(api.callsOf('session.cancel')).toEqual([])
   })
 
   it('sends content through session.prompt; composerPhase steps blank → engaging synchronously at send entry', async () => {
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index 11e852a8b6..a67b816012 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -17,6 +17,7 @@ export const zh = {
   'placeholder.plan': PLAN_NEXT_ACTION_ZH,
   'placeholder.default': '给智能体发消息',
   'placeholder.unavailable': '会话不可用',
+  'placeholder.parentOffline': '父会话已离线，无法继续发送；仍可停止当前运行',
   'placeholder.hero': '描述你想要构建的内容',
   'placeholder.workspace': '选择一个工作区开始',
   'input.commands': '命令',
@@ -159,6 +160,7 @@ export const en = {
   'placeholder.plan': PLAN_NEXT_ACTION_EN,
   'placeholder.default': 'Message the agent',
   'placeholder.unavailable': 'Session unavailable',
+  'placeholder.parentOffline': 'Parent session offline; sending is unavailable but you can still stop the run',
   'placeholder.hero': 'Describe what you want to build',
   'placeholder.workspace': 'Choose a workspace to start',
   'input.commands': 'Commands',
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 7b24c09684..21abce0e38 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -83,11 +83,15 @@ export function InputBar({
   // (undefined = capability absent → the chip renders nothing).
   const permissions = useProjection('permissions')
 
+  // A continuable child without its live parent cannot accept human input,
+  // but its primary Stop below stays available while it runs.
+  const continuable = subagent?.address.mode === 'continuable'
+  const parentOffline = continuable && !subagent.parentAvailable
   // Queue cut 1: running input stays free; locked = session removed, the
-  // inert no-workspace state, or the machine faces absent (no session). The
-  // transient machine locks (adjudicating pending / submitting) render
-  // read-only — the draft stays visible and focused, keystrokes drop.
-  const disabled = removed || inert || !live || blocked !== undefined
+  // inert no-workspace state, the machine faces absent (no session), or a
+  // parent-offline continuable child. An owner block also disables input;
+  // adjudicating and submitting render read-only so the draft stays visible.
+  const disabled = removed || inert || !live || blocked !== undefined || parentOffline
   const locked = disabled
   // The model seat is the ONE control a block leaves live: every block this
   // contract has is cleared by choosing a model, so locking it too would leave
@@ -350,8 +354,9 @@ export function InputBar({
     if (el !== null) toggleCommandMenu?.(selectionOf(el))
   }
 
-  const ordinary = subagent === null
-  const stopping = running && ordinary
+  // Ordinary sessions and continuable children stop through the same primary
+  // action; one-shot children stay send-and-stop-free (read-only takeover).
+  const stopping = running && (subagent === null || continuable)
   const primaryLabel = stopping ? t('input.stop') : t('input.send')
   const onPrimary = (): void => {
     if (stopping) {
@@ -478,9 +483,11 @@ export function InputBar({
               disabled={locked}
               readOnly={machineBusy}
               data-phase={input?.phase ?? 'inert'}
-              placeholder={placeholder ?? (disabled
-                ? t('placeholder.unavailable')
-                : planActive ? t('placeholder.plan') : t('placeholder.default'))}
+              placeholder={placeholder ?? (parentOffline
+                ? t('placeholder.parentOffline')
+                : disabled
+                  ? t('placeholder.unavailable')
+                  : planActive ? t('placeholder.plan') : t('placeholder.default'))}
               rows={2}
               onChange={onChange}
               onKeyDown={onKeyDown}
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 47791a6090..89f0d0a5f4 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -143,7 +143,8 @@ function bench(over?: BenchOptions) {
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector('textarea')!
-  const stopping = over?.running === true && over.subagent === undefined
+  const stopping = over?.running === true
+    && (over.subagent === undefined || over.subagent.address.mode === 'continuable')
   const button = view.container.querySelector<HTMLButtonElement>(
     `button[aria-label="${stopping ? '停止生成' : '发送消息'}"]`,
   )!
@@ -250,8 +251,8 @@ describe('running and lock semantics (queue cut 1)', () => {
     expect(ctrl.sink).toHaveBeenCalledWith('also queue', 'queue')
   })
 
-  it('running subagent primary admits a follow-up instead of exposing Stop', () => {
-    const { button, sink, stop } = bench({
+  it('running continuable subagent turns the same primary into Stop while typing stays free', () => {
+    const { button, textarea, sink, stop } = bench({
       running: true,
       draft: '后续消息',
       subagent: {
@@ -263,23 +264,54 @@ describe('running and lock semantics (queue cut 1)', () => {
         parentAvailable: true,
       },
     })
-    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    // One primary action only: Send switched to Stop, no side-by-side interrupt.
+    expect(button.getAttribute('aria-label')).toBe('停止生成')
+    expect(textarea.disabled).toBe(false)
     fireEvent.click(button)
+    expect(stop).toHaveBeenCalledTimes(1)
+    expect(sink).not.toHaveBeenCalled()
+    // Enter still queues the follow-up while the primary offers Stop.
+    fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(sink).toHaveBeenCalledWith('后续消息', 'queue')
-    expect(stop).not.toHaveBeenCalled()
+  })
 
-    const empty = bench({
+  it('parent-offline running continuable locks the input but keeps the same primary Stop usable', () => {
+    const { button, textarea, stop, view } = bench({
       running: true,
+      draft: '',
       subagent: {
         address: {
           parentSessionId: 'parent' as SessionId,
           childSessionId: SID,
           mode: 'continuable',
         },
+        parentAvailable: false,
+      },
+    })
+    expect(textarea.disabled).toBe(true)
+    expect(textarea.placeholder).toBe('父会话已离线，无法继续发送；仍可停止当前运行')
+    expect((view.getByLabelText('命令') as HTMLButtonElement).disabled).toBe(true)
+    expect(button.getAttribute('aria-label')).toBe('停止生成')
+    expect(button.disabled).toBe(false)
+    fireEvent.click(button)
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('running one-shot subagent never exposes Stop', () => {
+    const { button, stop } = bench({
+      running: true,
+      draft: '不可停止',
+      subagent: {
+        address: {
+          parentSessionId: 'parent' as SessionId,
+          childSessionId: SID,
+          mode: 'one-shot',
+        },
         parentAvailable: true,
       },
     })
-    expect(empty.button.disabled).toBe(true)
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(stop).not.toHaveBeenCalled()
   })
 
   it('keeps both running subagent Enter gestures on Queue transport', () => {
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 8bb19b2ba2..d1b0852953 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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/ui-subagent/README.md
-README.md: cb210b219a8c66985eb4e1370468372eed9614b4
-README.zh.md: 857e92d05a7ed2d0df9398acc9698db13b0c6eb2
+README.md: de55963bbe356e18a4e2b653be823cc5015c1bb7
+README.zh.md: ce4244db094bb8b602b854289ec000477bf45f0b
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index cb210b219a..de55963bbe 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -6,7 +6,7 @@ Web subagent feature owner: contributes the lazily expandable catalog tree to `c
 
 The header action reads `subagentsByParent` and session summaries through the standard `useSessions` hook. After a non-empty direct catalog arrives, its trigger counts the complete subagent-only descendant lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. The compact tree remains direct-catalog authoritative: continuable and one-shot rows display mode plus `running`/`inactive` activity and an optional log-backed title, while the trailing column stacks total durable provider usage above active-turn duration. Token totals sum the four disjoint `tokenUsage` buckets. Visual duration stays exact to the second below one day, then uses at most two adjacent units—days/hours, approximate months/days, or approximate years/months—while hover and the accessible name retain the exact day/hour/minute/second value. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. An unlabeled one-shot row falls back to its session id, while corrupt, unsupported, or unavailable rows remain readable but disabled. Each healthy row's `hasChildren` hint determines disclosure before interaction, so known leaves never show an arrow; a catalog level reserves the disclosure column only when at least one healthy row is a branch, allowing branchless levels to start at the leading status marker. Expanding a branch immediately reserves one disabled loading row per known direct descendant, then lazily replaces them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. Selecting any depth calls `SessionsService.openSubagent()` with the row's exact `{parentSessionId, childSessionId, mode}` address. Component-local state owns tree visibility, expanded branches, keyboard focus, and the running-duration clock. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree; closing returns focus to the trigger. Styling uses tokens only.
 
-A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable, with copy explaining the recovery path. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes through `subagent.prompt`; running input remains Send because every follow-up joins the child's FIFO inbox, and addressed sessions never expose Stop. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md).
+A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input is disabled but whose primary Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing stays free while the child runs because every follow-up joins the child's FIFO inbox, and the single primary action follows the ordinary convention — Send while idle, Stop while running, routed through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md).
 
 Subagent-origin Session rows are omitted from the ordinary sidebar, so the parent header catalog is their navigation entry point. Ordinary forks remain in the sidebar.
 
@@ -30,5 +30,5 @@ Append-only. This package never edits earlier request tokens.
 
 ## Known Limitations and Deferred Work
 
-- **The catalog has no durable outcome** — activity and timing do not distinguish completion, failure, or cancellation, and the UI exposes neither Activation identity nor an authority-safe cancel button.
+- **The catalog has no durable outcome** — activity and timing do not distinguish completion, failure, or cancellation, and the UI exposes no Activation identity; stopping is limited to the composer's current-turn Stop for a running continuable child.
 - **`@` references remain display-title text** — duplicate or renamed labels are ambiguous, so they intentionally do not acquire continuation semantics.
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 857e92d05a..ce4244db09 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -6,7 +6,7 @@ Web subagent 功能 owner：向 `conversation.session.header.actions` 贡献可
 
 页头操作通过标准 `useSessions` 钩子读取 `subagentsByParent` 与会话摘要。非空直接目录到达后，其触发器会统计仅含 subagent 的完整后代谱系，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。紧凑树仍以直接目录为权威依据：可继续和 one-shot 行会显示 mode、`running`／`inactive` 活动状态和由日志支撑的可选 title，尾随列则在上行显示提供方的持久化 token 用量总计，在下行显示活跃轮次耗时。token 用量总计为四个互不重叠的 `tokenUsage` 桶之和。视觉耗时在不足一天时精确到秒，达到一天后则最多使用两个相邻单位——天／小时、近似月份／天或近似年份／月份——而悬停信息与无障碍名称会保留精确的天／小时／分钟／秒数值。耗时会累加已完成的 `subagentTiming` 轮次，仅在运行中 child 存在未结束轮次时每秒递增一次，并在 child 变为 inactive 后冻结；被中断的未结束轮次以其同一切面的 `active.through` 为上界，绝不使用更新的会话元数据。没有 label 的 one-shot 行会回退到其会话 id，而损坏、不受支持或不可用的行仍保持可读但禁用。每个健康行的 `hasChildren` 提示会在交互前决定是否显示展开控件，因此已知叶子节点从不显示箭头；每层目录仅在其中至少一个健康行是分支时才预留展开列，使完全不含分支的层级能从最前面的状态标记开始。展开分支时，会立即为每个已知直接后代预留一行禁用的加载行，随后再用该 child 的权威目录懒加载结果替换这些占位行。每个可见分支都会上报给运行时，使成员帧只在树正被消费的位置触发去抖动刷新。选择任意深度的条目都会使用该行的确切地址 `{parentSessionId, childSessionId, mode}` 调用 `SessionsService.openSubagent()`。组件局部状态负责树的可见性、已展开分支、键盘焦点与运行中耗时时钟。ArrowRight／ArrowLeft 展开和折叠分支；ArrowUp／ArrowDown、Home、End 与 Escape 用于导航或关闭树；关闭后焦点返回触发器。样式只使用 token。
 
-one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用时选用只读编辑器，并以文案说明恢复路径。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话会通过 `subagent.prompt` 路由；child 运行期间，输入操作仍为 Send，因为每条后续消息都会进入 child 的 FIFO inbox，且已寻址会话绝不公开 Stop。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 规定。
+one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器，并以文案说明恢复路径；此类 child 仍在运行期间，selector 会让位给普通编辑器——其输入区被禁用，但 primary Stop 保持可用，停止后只读替代恢复。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话通过 `subagent.prompt` 路由提示词：child 运行期间输入保持自由，因为每条后续消息都会进入 child 的 FIFO inbox，而唯一的 primary 操作遵循普通约定——空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md) 规定。
 
 普通侧边栏会省略带 subagent origin 的会话行，因此 parent 页头目录是它们的导航入口。普通 fork 仍保留在侧边栏中。
 
@@ -30,5 +30,5 @@ one-shot child 始终选用只读编辑器，并将 transcript（文本记录）
 
 ## 已知限制与暂缓事项
 
-- **目录没有持久化结果**：活动状态与计时无法区分完成、失败或取消，且 UI 既不公开 Activation 身份，也不公开符合授权边界的取消按钮。
+- **目录没有持久化结果**：活动状态与计时无法区分完成、失败或取消，且 UI 不公开 Activation 身份；停止能力仅限编辑器上针对运行中可继续 child 的当前轮次 Stop。
 - **`@` 引用仍是显示标题文本**：重复或改名后的 label 会有歧义，因此它们刻意不获得继续执行语义。
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 95626cbaf1..73c7f9a6cc 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -43,7 +43,11 @@ function selectReadOnlySubagent(owner: ComposerChainProps): SubagentReadOnlyMatc
   const subagent = owner.session?.subagent
   if (subagent === undefined || subagent === null) return null
   if (subagent.address.mode === 'one-shot') return { reason: 'one-shot' }
-  return subagent.parentAvailable ? null : { reason: 'parent-unavailable' }
+  if (subagent.parentAvailable) return null
+  // A RUNNING parent-offline continuable child keeps the default composer:
+  // its input is disabled there, but the same primary Stop stays available so
+  // the child can be interrupted. Once it stops, this takeover returns.
+  return owner.session?.running === true ? null : { reason: 'parent-unavailable' }
 }
 
 /**
diff --git a/packages/client/ui-subagent/tests/browser-plugin.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
index 09221e1e94..861546c19c 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
@@ -161,19 +161,26 @@ describe('apply', () => {
     const select = composerEntry.select as (owner: ComposerChainProps) => SubagentReadOnlyMatch | null
     const owner = (
       subagent: ConversationSnapshot['subagent'] | undefined,
+      running = false,
     ): ComposerChainProps => ({
       interactions: [],
       session: subagent === undefined
         ? undefined
-        : ({ subagent } as unknown as ConversationSnapshot),
+        : ({ subagent, running } as unknown as ConversationSnapshot),
     })
     expect(select(owner(undefined))).toBeNull()
     expect(select(owner(null))).toBeNull()
     expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true })))
       .toEqual({ reason: 'one-shot' })
+    // One-shot stays read-only even while running: it has no stop action.
+    expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true }, true)))
+      .toEqual({ reason: 'one-shot' })
     expect(select(owner({ address, parentAvailable: true }))).toBeNull()
     expect(select(owner({ address, parentAvailable: false })))
       .toEqual({ reason: 'parent-unavailable' })
+    // A RUNNING parent-offline continuable yields the default composer, whose
+    // disabled input still carries the primary Stop; stopped, it takes back over.
+    expect(select(owner({ address, parentAvailable: false }, true))).toBeNull()
   })
 })
 
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1997f0ea47..1a8ef6508a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -55,6 +55,7 @@
     "apps/web/tests/produced-file-mentions.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
     "apps/web/tests/subagent-interrupt.e2e.ts",
+    "apps/web/tests/subagent-interrupt-ui.e2e.ts",
     "apps/web/tests/sidebar-subagent-activity.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",

From 4b29f9ca7a7a72f1f6289717d5460ffff8b690cb Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 16:13:54 +0800
Subject: [PATCH 024/262] test(web): refresh interrupt UI golden after master
 merge

---
 .../snapshots/subagent-interrupt/offline-composer.expected.md  | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
index 6ea7b83bff..a0baa9a44f 100644
--- a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
+++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
@@ -9,9 +9,6 @@
 - text: Explain event sourcing in one sentence. {{clock}}
 - button "Copy":
   - img
-- button "Branch into a new conversation" [disabled]:
-  - img
-- text: Available only on the last message of a completed turn
 - button "Context injection @deepseek-ai/dsh-system-prompt":
   - img
   - img

From d769d3cbb7c32cc4f1a4ff32cf5b30af96ea9f34 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 13:46:55 +0800
Subject: [PATCH 025/262] feat(subagent): let ancestors interrupt descendants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

interrupt_agent(agent_id) passes the calling agent as the ancestor
authority for ctx.subagents.interrupt(); the service verifies live
registry identity and recorded lineage, so a direct child or deeper
descendant stops with the same generic parameter while send_message keeps
its exact-direct-parent authority.

Discovery: list_agents gains an optional scope. descendants walks the new
SubagentService.listDescendants() — one lineage trace flattened in stable
pre-order across ordinary and one-shot intermediates, each entry carrying
its verified parentId and depth — and every status now comes from the
live Agent registry (running/idle/complete).

Refs #1535
---
 ...subagent-catalog-and-list-agents.i18n.yaml |   4 +-
 ...urable-subagent-catalog-and-list-agents.md |   8 +-
 ...ble-subagent-catalog-and-list-agents.zh.md |   8 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |   4 +-
 ...26-08-06-continuable-subagent-interrupt.md |   6 +-
 ...08-06-continuable-subagent-interrupt.zh.md |   6 +-
 apps/web/tests/shipped-composition.e2e.ts     |   1 +
 docs/cordis-catalog/services.md               |  19 +-
 docs/core-data-structures/subagent.i18n.yaml  |   4 +-
 docs/core-data-structures/subagent.md         |  23 +-
 docs/core-data-structures/subagent.zh.md      |  23 +-
 .../system-prompt.expected.md                 |  21 +-
 .../tool-schemas.expected.json                |  31 ++-
 .../both-mode-turn/tool-schemas.expected.json |  31 ++-
 .../code-mode-turn/system-prompt.expected.md  |  21 +-
 .../lsp-definition/tool-schemas.expected.json |  31 ++-
 .../pty-tools/tool-schemas.expected.json      |  31 ++-
 .../tool-schemas.expected.json                |  31 ++-
 .../tool-schemas.1.expected.json              |  31 ++-
 .../tool-schemas.1.expected.json              |  31 ++-
 .../tool-schemas.1.expected.json              |  31 ++-
 .../text-turn/tool-schemas.expected.json      |  31 ++-
 .../web-fetch/tool-schemas.expected.json      |  31 ++-
 .../cordis/tool-cordis/src/api-catalog.ts     |   8 +
 .../core/tools/tests/gen-tool-catalog.spec.ts |   3 +-
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   5 +-
 packages/subagent/subagent/README.zh.md       |   7 +-
 packages/subagent/subagent/src/index.ts       |  31 ++-
 .../subagent/subagent/src/list-children.ts    | 159 ++++++++++++--
 .../subagent/tests/list-children.spec.ts      | 194 +++++++++++++++++
 .../tool-subagent-control/README.i18n.yaml    |   4 +-
 .../subagent/tool-subagent-control/README.md  |  28 ++-
 .../tool-subagent-control/README.zh.md        |  28 ++-
 .../tool-subagent-control/src/index.ts        |  56 ++++-
 .../tool-subagent-control/src/list-agents.ts  | 124 ++++++++---
 .../tests/list-agents.spec.ts                 | 165 +++++++++++++-
 .../tests/tool-subagent-control.spec.ts       | 202 +++++++++++++++++-
 scripts/gen-cordis-catalog.ts                 |   1 +
 scripts/gen-tool-catalog.ts                   |   5 +-
 scripts/type-equiv.manifest.json              |   5 +
 41 files changed, 1325 insertions(+), 162 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index 2acc3dd5b5..c525cc8f43 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.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 .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
-2026-07-22-durable-subagent-catalog-and-list-agents.md: b96d6e1dd36c58af67c8e93e62515672790ad009
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: 856bac615db84bfe2898ec0838094c6bc29f77b2
+2026-07-22-durable-subagent-catalog-and-list-agents.md: 8337a926238bf7fc4395896fcd4ca180c9c1ac1c
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: bcf2895a9a69c8cff949788c78158bfccd198c5c
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
index b96d6e1dd3..8337a92623 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
@@ -23,7 +23,7 @@ Parent-to-child enumeration is a service capability with consumer-specific proje
 - report corpus activity separately as `running` or `inactive`, without implying completion or resumability;
 - return every resulting child in stable `createdAt` ascending, child-id ascending order.
 
-Every ordinary local start receives a `one-shot` descriptor with an optional caller-owned display label, while the continuation manager persists a labeled `continuable` descriptor containing its additional reconstruction fields. The model-facing delegation tool already owns a short `description` and supplies it for one-shot display; lower-level callers such as workflows need not invent presentation metadata. The model-facing `list_agents` adapter filters the service result to continuable children and maps `inactive` to its existing `complete` presentation; a UI can consume both modes and choose an id-based fallback for unlabeled one-shot history. Descriptor persistence, by-id lookup, direct-parent authorization, and provider-independent cold resume remain owned by the implemented Activation contract. Listing consumes those facts but cannot weaken them or invent a second descriptor representation.
+Every ordinary local start receives a `one-shot` descriptor with an optional caller-owned display label, while the continuation manager persists a labeled `continuable` descriptor containing its additional reconstruction fields. The model-facing delegation tool already owns a short `description` and supplies it for one-shot display; lower-level callers such as workflows need not invent presentation metadata. The model-facing `list_agents` adapter filters the service result to continuable children and refines status through the live Agent registry (`running`/`idle`/`complete`); a UI can consume both modes and choose an id-based fallback for unlabeled one-shot history. Descriptor persistence, by-id lookup, direct-parent authorization, and provider-independent cold resume remain owned by the implemented Activation contract. Listing consumes those facts but cannot weaken them or invent a second descriptor representation.
 
 ### Enumeration decision
 
@@ -52,7 +52,7 @@ If measured scale later requires an index, that index is derived state: session
 
 A valid descriptor produces one child entry, a per-child inspection failure produces one diagnostic entry, and a candidate without a descriptor produces no entry. `mode` is durable creation policy; `activity` is a process-local corpus snapshot. Activity is neither `AgentStatus`, the manager's internal Activation state, nor a durable outcome, and the result does not expose the internal `createdAt` sorting key. Exact Activation states and durable outcomes such as successful completion, failure, cancellation, and stop reason require a separate durable activation record and are outside this feature.
 
-The model-facing `list_agents` tool takes no arguments, derives `parentSessionId` from the current execution Agent, and is a thin adapter in `@deepseek-ai/dsh-tool-subagent-control`. It keeps diagnostics, drops `one-shot` child entries, maps a continuable child's `running` activity to `running` and `inactive` activity to `complete`, then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in the surviving trace order. An empty projection renders `(no subagents)`.
+The model-facing `list_agents` tool takes one optional `scope: 'children' | 'descendants'` argument, derives the root id from the current execution Agent, and is a thin adapter in `@deepseek-ai/dsh-tool-subagent-control`. It keeps diagnostics, drops `one-shot` child entries, derives status from the live Agent registry — `running` for an active driver, `idle` for a resident Agent between turns, and `complete` when no live Agent remains — then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in stable catalog order. The `descendants` scope reads `SubagentService.listDescendants(rootSessionId)`, which flattens the complete tree from one live-preferred corpus in stable pre-order, traverses ordinary and one-shot intermediates so deeper continuable agents are discovered, revalidates each cold candidate against its enumerated lifecycle, and adds `parentId`/`depth` to every entry. The tool inserts ` parent=<id> depth=<n>` before the label; `parent` is the durable direct-parent session id and may name an omitted ordinary session. For the current caller, only depth-1 child rows are `send_message` candidates, while deeper child rows may be selected for `interrupt_agent` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Discovery is a hint only — follow-up authority stays exact-direct-parent, and interrupt authority stays with the service's live-lineage check. An empty projection renders `(no subagents)`.
 
 Diagnostics use three fixed reasons. Malformed event surfaces, conflicting headers discovered during an exact child load, a read result whose immutable header differs from the traced candidate or no longer names the requested direct parent, a target that is no longer the located descriptor event, malformed descriptor content, and multiple descriptor events map to `corrupt`. An unknown descriptor version maps to `unsupported`. `SESSION_QUERY_SESSION_NOT_FOUND`, `SESSION_QUERY_EVENT_NOT_FOUND`, and `SESSION_QUERY_PERSISTENCE_FAILED` from a per-child read map to `unavailable`. This phase boundary is intentional: a persistence outage during the initial trace fails the operation, while the same outage beginning during candidate reads may produce one identical `unavailable` diagnostic per affected child; the first version neither coalesces those diagnostics nor promotes them to a global failure. A missing descriptor is instead a non-subagent exclusion without a diagnostic. Configuration/window errors and unrecognized failures are not child diagnostics and propagate as operation failures. Each diagnostic identifies the child id and reason without exposing model-hidden descriptor content; the candidate is omitted while healthy siblings remain visible. Sessions outside the trace's direct descendants are never read and produce no diagnostic.
 
@@ -93,8 +93,8 @@ The first version has no child deletion operation. If later product behavior del
 ## Testing
 
 - `packages/subagent/subagent/tests/service.spec.ts` pins descriptor v2 parsing for both modes and proves an unlabeled raw start resolves a one-shot descriptor before provider dispatch. `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` proves the local driver appends that descriptor inside the initial turn, returns the published id when cancellation lands in the factory-to-run handoff, and keeps result and handle-disposal failures on separate channels. Delegation-tool tests pin propagation of their existing display description and preserve independent result and disposal diagnostics.
-- `packages/subagent/subagent/tests/list-children.spec.ts` pins the current read path against a real composition of the session store, JSONL persistence, spawn/fork providers, the subagent service, and the projection registry — no query service — keylessly: live-only listing without persistence; loud `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` even with zero children; the three-rung ladder (a live child never inspected, a cold child inspected exactly once, and the cache-hit, absent-key, absent-service, and poisoned-row second-rung cases); last-wins over multiple descriptors; malformed payloads and unknown versions diagnosed as `corrupt`; a failed cold inspection as one `unavailable` diagnostic retried on the next listing; a fork seed's ancestor descriptor listed under that identity; foreign-unit fold failures contained per child as `corrupt` on both the live and cold paths; `createdAt`-then-id ordering without ordinary forks; provider absence without child omission; compacted/uncompacted twins listing identically; a persisted-listing failure failing the whole enumeration; cancellation normalized to stable `CANCELLED`; and typed stable error codes. A companion spec (retired together with the query-backed read path) rejected eager evaluation of the optional session-query runtime while importing the ordinary subagent surface.
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` pins the `list_agents` schema (no parameters), the continuable-only projection that omits a healthy one-shot sibling while preserving diagnostics, the fixed child/diagnostic/empty text forms, an end-to-end settled-child listing with its durable label, forwarding of the tool cancellation signal, the no-agent rejection, the narrowed load requirement without `sessionQuery`, and HMR disposal.
+- `packages/subagent/subagent/tests/list-children.spec.ts` pins the current read path against a real composition of the session store, JSONL persistence, spawn/fork providers, the subagent service, and the projection registry — no query service — keylessly: live-only listing without persistence; loud `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` even with zero children; the three-rung ladder (a live child never inspected, a cold child inspected exactly once, and the cache-hit, absent-key, absent-service, and poisoned-row second-rung cases); last-wins over multiple descriptors; malformed payloads and unknown versions diagnosed as `corrupt`; a failed cold inspection as one `unavailable` diagnostic retried on the next listing; a fork seed's ancestor descriptor listed under that identity; foreign-unit fold failures contained per child as `corrupt` on both the live and cold paths; `createdAt`-then-id ordering without ordinary forks; provider absence without child omission; compacted/uncompacted twins listing identically; a persisted-listing failure failing the whole enumeration; cancellation normalized to stable `CANCELLED`; typed stable error codes; and descendant listing's iterative stable pre-order, traversal through ordinary and one-shot intermediates, positioned diagnostics, lifecycle revalidation, and cancellation. A companion spec (retired together with the query-backed read path) rejected eager evaluation of the optional session-query runtime while importing the ordinary subagent surface.
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` pins the `list_agents` schema (one optional `scope` enum), the continuable-only projection that omits a healthy one-shot sibling while preserving diagnostics, registry-derived child/diagnostic/empty text forms, an end-to-end settled-child listing with its durable label, the descendants scope's pre-order parent/depth annotations across a live waiting branch, cancellation forwarding to both scopes, the no-agent rejection, the `agents` load requirement without `sessionQuery`, and HMR disposal.
 - The keyless ACP snapshot scenario `subagent-list-agents` (examples/acp-agent) fences its second parent turn on a snapshot-only `subagent/end` marker, then executes `list_agents` for real against the subagent service, the projection registry, and JSONL persistence, rendering `<id> [complete] — <label>`.
 - The keyless snapshot scenario `subagent-diagnostic` (examples/headless-agent) pins the current listing's model-visible diagnostic classification, including a descriptor-less settled child surfacing as a `corrupt` diagnostic.
 - The keyless ACP snapshot scenario `subagent-published-run-failure` publishes a real one-shot child, injects independent run-result and handle-disposal failures, and preserves both diagnostics in the parent tool result.
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index 856bac615d..bcf2895a9a 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -23,7 +23,7 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 - 将语料活动状态单独报告为 `running` 或 `inactive`，但不暗示已完成或可恢复；
 - 按 `createdAt` 升序、再按 child id 升序稳定返回所有结果 child。
 
-每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并将 `inactive` 映射为其现有的 `complete` 表示；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
+每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
 
 ### 枚举决策
 
@@ -52,7 +52,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具不接受参数，从当前正在执行的 Agent 推导 `parentSessionId`，并作为 `@deepseek-ai/dsh-tool-subagent-control` 中的轻量适配器。它保留 diagnostic，丢弃 `one-shot` child 条目，将可继续 child 的 `running` 活动状态映射为 `running`、`inactive` 活动状态映射为 `complete`，然后按剩余的追踪顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并作为 `@deepseek-ai/dsh-tool-subagent-control` 中的轻量适配器。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 读取 `SubagentService.listDescendants(rootSessionId)`：它从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
 diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
@@ -93,8 +93,8 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 ## 测试
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
-- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；以及带类型的稳定错误码。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（无参数）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、child／diagnostic／空结果的固定文本形式、带持久化 label 的已结束 child 端到端列表、工具取消信号的转发、无调用 agent 时的拒绝、收窄后的加载要求（不再注入 `sessionQuery`），以及 HMR dispose。
+- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载契约，以及 HMR dispose。
 - 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
 - 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 5cf5601fc0..dfdc2338ae 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 1792d4c6d25858c861be0ff920206d0d4e684f41
-2026-08-06-continuable-subagent-interrupt.zh.md: ff9887481d1ded2743c7c8f9f162413fb6581d70
+2026-08-06-continuable-subagent-interrupt.md: 0f663ac6a58b9c3d658aa572ca2fea18dbef6449
+2026-08-06-continuable-subagent-interrupt.zh.md: b8a5b557b73b2845e3c0b1dabdec0163f56eca48
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 1792d4c6d2..0f663ac6a5 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,8 +39,10 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract). The model-facing `interrupt_agent` tool builds on this primitive in the stacked follow-up PR for issue #1535.
+The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
+
+The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control` passes `exec.agent` as the `ancestor` authority and adds none of its own: the core primitive verifies live registry identity and recorded lineage, so the tool can name a direct child or a deeper descendant with the same generic `agent_id` parameter — deliberately not `subagent_id`, which would imply direct children only. Discovery rides `list_agents({ scope: 'descendants' })` over the new `SubagentService.listDescendants()` one-trace pre-order walk with verified `parentId`/`depth` per entry ([durable catalog note](2026-07-22-durable-subagent-catalog-and-list-agents.md) owns the listing contract); discovery is a hint, never authority. `send_message` keeps its exact-direct-parent authority — only interrupt is ancestor-wide.
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index ff9887481d..b8a5b557b7 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,8 +39,10 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
+
+`dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表契约由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
diff --git a/apps/web/tests/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts
index 447f14ae44..11bbdcfd82 100644
--- a/apps/web/tests/shipped-composition.e2e.ts
+++ b/apps/web/tests/shipped-composition.e2e.ts
@@ -30,6 +30,7 @@ const EXPECTED_TOOLS = [
   'edit',
   'exit_plan_mode',
   'get_goal',
+  'interrupt_agent',
   'list_agents',
   'ralph',
   'read',
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 59a9cf527d..f4eead6f8e 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2153,6 +2153,23 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
  */
 listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
 
+/**
+ * Enumerate the root's complete session-backed subagent tree in stable
+ * pre-order from one lineage trace, without loading or resuming an Agent.
+ * Ordinary sessions and one-shot children are traversed so continuable
+ * descendants below them are discovered; each returned entry adds its
+ * verified `parentId` and root-relative `depth`. Cancellation follows the
+ * same contract as {@link listChildren}.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation forwarded where supported and
+ *   observed around every query await.
+ * @returns children and per-candidate diagnostics with tree position, in
+ *   stable pre-order.
+ * @throws {@link SubagentError} when session query is unavailable or the
+ *   caller cancels the scan.
+ */
+listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
+
 /**
  * Register a provider under its name. Registration is effect-scoped and HMR
  * safe; removing a provider blocks new starts but does not revoke runs that
@@ -2188,7 +2205,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentDescendantListEntry](../core-data-structures/subagent.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index 15d5e19578..57b960da91 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: 4de77c6232d73d4b4e9dd87e9afc7a077e61f1a0
-subagent.zh.md: 3310bb4bf8cad1314ec26eef9042955959aba5fe
+subagent.md: b26a12d1d50305d86d7ada29cac83474009d81ce
+subagent.zh.md: 6c4c64ff22050b73699a97093acd0032668fde3d
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 4de77c6232..b26a12d1d5 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -4,7 +4,7 @@ English | [中文](subagent.zh.md)
 
 The subagent seam — an agent delegating work to a child agent. Like [bash](bash.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). But it differs from every other seam on one axis: **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), where bash allows only one executor. The registry shape mirrors the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
 
-Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message` and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only direct-child discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
@@ -263,9 +263,26 @@ The descriptor (`SubagentDescriptorData` in [descriptor.ts](../../packages/subag
 
 A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `header.seedLength` remains the fork-lineage boundary: resume-time descriptor authority reads the child's own suffix, while the list-serving identity projection folds `subagent/descriptor` last-wins so the child's own descriptor overrides a fork-seeded ancestor's. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
 
-## Durable enumeration: `listChildren()` and `SubagentListEntry`
+## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
+
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+
+`SubagentService.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
+
+```ts type-equiv
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Durable direct parent of this candidate in the enumerated tree. */
+  readonly parentId: SessionId
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number
+}
+```
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and maps activity to its existing `running`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 ## The terminal result: `SubagentResult`
 
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index 3310bb4bf8..6c4c64ff22 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的直接 child 发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
@@ -263,9 +263,26 @@ interface ContinuableCreateSpec {
 
 本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
-## 持久化枚举：`listChildren()` 与 `SubagentListEntry`
+## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
+
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+
+`SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
+
+```ts type-equiv
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Durable direct parent of this candidate in the enumerated tree. */
+  readonly parentId: SessionId
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number
+}
+```
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时只要求 `ctx.subagents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并将活动状态映射到现有的 `running`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 ## 终态结果：`SubagentResult`
 
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index e63807db59..2f33c0c6a5 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -94,8 +94,16 @@ interface ToolArgsMap {
   } & Record<string, JsonValue>;
   /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */
   get_goal: Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. */
-  list_agents: Record<string, JsonValue>;
+  /** Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op. */
+  interrupt_agent: {
+    /** The agent id of the running agent to interrupt. */
+    agent_id: string;
+  } & Record<string, JsonValue>;
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  list_agents: {
+    /** children (default) lists direct children only; descendants walks the complete tree below you. */
+    scope?: "children" | "descendants";
+  } & Record<string, JsonValue>;
   /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */
   ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
@@ -304,15 +312,22 @@ interface ToolOutputMap {
     };
     activation: "armed" | "disarmed";
   };
+  interrupt_agent: {
+    accepted: boolean;
+  };
   list_agents: ({
     kind: "child";
     id: string;
     label: string;
-    status: "running" | "complete";
+    status: "running" | "idle" | "complete";
+    parent?: string;
+    depth?: number;
   } | {
     kind: "diagnostic";
     id: string;
     reason: "corrupt" | "unsupported" | "unavailable";
+    parent?: string;
+    depth?: number;
   })[];
   ralph: {
     runId: string;
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index 98b866f841..d1e5b75e45 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -173,11 +173,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
index 7588c353cc..890f3ee000 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
index 70a71c3673..5b74a88512 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
@@ -77,8 +77,16 @@ interface ToolArgsMap {
   } & Record<string, JsonValue>;
   /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */
   get_goal: Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. */
-  list_agents: Record<string, JsonValue>;
+  /** Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op. */
+  interrupt_agent: {
+    /** The agent id of the running agent to interrupt. */
+    agent_id: string;
+  } & Record<string, JsonValue>;
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  list_agents: {
+    /** children (default) lists direct children only; descendants walks the complete tree below you. */
+    scope?: "children" | "descendants";
+  } & Record<string, JsonValue>;
   /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */
   ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
@@ -275,15 +283,22 @@ interface ToolOutputMap {
     };
     activation: "armed" | "disarmed";
   };
+  interrupt_agent: {
+    accepted: boolean;
+  };
   list_agents: ({
     kind: "child";
     id: string;
     label: string;
-    status: "running" | "complete";
+    status: "running" | "idle" | "complete";
+    parent?: string;
+    depth?: number;
   } | {
     kind: "diagnostic";
     id: string;
     reason: "corrupt" | "unsupported" | "unavailable";
+    parent?: string;
+    depth?: number;
   })[];
   ralph: {
     runId: string;
diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
index 1fba9e71d5..e41987451b 100644
--- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
index 48b72040a0..713353b91c 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 41fb8718c9..09c637f077 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
index 519e8eac8c..3283d98600 100644
--- a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
index 519e8eac8c..3283d98600 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
index 519e8eac8c..3283d98600 100644
--- a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
index 08c1451f60..6cea6864cd 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
index c242366100..f11131eb87 100644
--- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 1fd08a5c95..f942e6650e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -948,6 +948,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>',
         jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query seam: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
       },
+      {
+        signature: 'listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>',
+        jsDoc: '/**\n * Enumerate the root\'s complete session-backed subagent tree in stable\n * pre-order from one lineage trace, without loading or resuming an Agent.\n * Ordinary sessions and one-shot children are traversed so continuable\n * descendants below them are discovered; each returned entry adds its\n * verified `parentId` and root-relative `depth`. Cancellation follows the\n * same contract as {@link listChildren}.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded where supported and\n *   observed around every query await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} when session query is unavailable or the\n *   caller cancels the scan.\n */',
+      },
       {
         signature: 'registerProvider(provider: SubagentProvider): () => void',
         jsDoc: '/**\n * Register a provider under its name. Registration is effect-scoped and HMR\n * safe; removing a provider blocks new starts but does not revoke runs that\n * were already returned to their holders.\n * @param provider - the trusted provider implementation.\n * @returns the exact Cordis effect disposer.\n */',
@@ -2783,6 +2787,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubagentCapabilities',
     declaration: 'export interface SubagentCapabilities {\n    readonly outputSchema: boolean;\n    readonly depthLimit: boolean;\n    readonly toolFilter: boolean;\n    readonly persona: boolean;\n}',
   },
+  {
+    name: 'SubagentDescendantListEntry',
+    declaration: 'export type SubagentDescendantListEntry = SubagentListEntry & {\n    readonly parentId: SessionId;\n    readonly depth: number;\n};',
+  },
   {
     name: 'SubagentDescriptorData',
     declaration: 'export type SubagentDescriptorData = OneShotSubagentDescriptorData | ContinuableSubagentDescriptorData;',
diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts
index dae09f0591..2e59ffe32e 100644
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'list_agents', 'lsp', 'pwsh', 'ralph', 'read', 'report', 'run_code', 'send_message', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'str_replace_editor', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'interrupt_agent', 'list_agents', 'lsp', 'pwsh', 'ralph', 'read', 'report', 'run_code', 'send_message', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'str_replace_editor', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {
@@ -49,6 +49,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
     expect(bash?.sources.bash).toBe('packages/bash/tool-bash/src/index.ts')
     const control = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-subagent-control')
     expect(control?.sources).toEqual({
+      interrupt_agent: 'packages/subagent/tool-subagent-control/src/index.ts',
       list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
       send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
     })
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 9b9843af87..1025b0e342 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: eb1baa39231a2c058b3ada1a23b7b87e2bb2e384
-README.zh.md: 8402df3e4ff2559898dfd4dd512ab1601c9ec61d
+README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
+README.zh.md: 05b1e4dd4c74b6d62df8b0a310534fc9476f3ade
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index eb1baa3923..cd25bace16 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,11 +18,12 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `start(name, request)` | Validate an ordinary caller request, resolve its detached `one-shot` descriptor, then await the provider until a real one-shot child is published. Fulfillment returns a holder-owned `SubagentRun`; rejection means the provider has already cleaned every unpublished startup resource, while post-publication turn or infrastructure faults settle through the run. Continuable children never enter through this operation. |
 | `startContinuable(spec)` | Establish one durable continuable child and deliver its initial prompt. Resolves with `{ childId, messageId }` when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls the child back entirely. Requires `ctx.agents`, session persistence, and a provider with the `prepareContinuable` capability. |
 | `followup(parent, childId, content, { source, signal })` | Deliver one later message from the exact live direct parent as the child's next FIFO turn, matching `Agent.followup()` terminology, and return the accepted `MessageId`. A resident child's inbox accepts it directly (waking a waiting Activation); an absent one cold-resumes from its persisted Session. Requires `ctx.agents`; cold resume also requires session persistence. |
-| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup. |
+| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; work already claimed into the interrupted turn is not requeued. An absent target is an accepted no-op; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`. |
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
 | `listChildren(parentSessionId, signal?)` | List direct session-backed subagents with their `one-shot`/`continuable` mode, `running`/`inactive` activity, origin-classified one-level `hasChildren` hint, and per-child diagnostics, ordered by `createdAt` then id, without loading or resuming them. Reads the live session store and optional session persistence directly (live-only enumeration when persistence is absent) and requires the mounted `sessionProjections` registry; it does not require `ctx.agents`, the continuation manager, or any query service. |
+| `listDescendants(rootSessionId, signal?)` | Flatten the root's complete session tree in stable pre-order from the same live-preferred corpus, adding each subagent entry's durable `parentId` and root-relative `depth`. Ordinary sessions and one-shot children remain traversal nodes so continuable descendants below them are discovered. Identity, diagnostics, dependencies, and cancellation follow `listChildren()`. |
 
 `SubagentStartRequest.label` is an optional short durable display label for a session-backed one-shot child. Model-facing delegation supplies its existing `description`; lower-level callers need not invent presentation metadata. Continuable starts always carry their own required label. `signal` is required and is the canonical cancellation channel for a one-shot `start`. An abort before publication makes `start()` reject after rollback; an abort after publication cancels the returned run's remaining turn work without hiding its id. The request may also select a model, require structured output, cap delegation depth, restrict child tools, or set a child persona. For a continuable start or follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance; afterward the manager owns the Activation independently, so later caller cancellation neither cancels the accepted turn nor disposes the child.
 
@@ -85,7 +86,7 @@ When `ctx.sessionProjections` is available, the service registers two projection
 
 ## Collection model
 
-The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task or result promise — a caller sends later work with the `send_message` follow-up tool, while `interrupt()` stops only the current turn without disposing the child. The durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
+The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task and no result promise — a caller sends later work with the `send_message` follow-up tool, and `interrupt()` stops only the current turn without disposing the child, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and refines status through the live Agent registry (`running`/`idle`/`complete`) and walks `listDescendants()` for its `descendants` scope. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
 
 Continuable Activations await a best-effort final session flush without treating listener participation as durability confirmation. One-shot runs retain best-effort session checkpointing, so a completed one-shot child is discoverable after disposal only when its session actually reached persistence; the service does not invent a catalog entry from Task history when that checkpoint is absent.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 8402df3e4f..05b1e4dd4c 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -18,11 +18,12 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
 | `startContinuable(spec)` | 建立一个持久化可继续子 agent，并投递其初始提示词。子 agent 的 inbox 接受该提示词时，兑现为 `{ childId, messageId }`，无需等待轮次开始或消息写入 Session 日志；此前任何失败都会以无 id 拒绝，并完全回滚该子 agent。要求 `ctx.agents`、会话持久化以及具备 `prepareContinuable` 能力的提供方。 |
 | `followup(parent, childId, content, { source, signal })` | 将来自确切在线直接父级的一条后续消息作为子 agent 的下一个 FIFO 轮次投递，术语与 `Agent.followup()` 一致，并返回被接受的 `MessageId`。驻留中的子 agent 由其 inbox 直接接受（唤醒处于 waiting 的 Activation）；不驻留的则从其持久化 Session 冷恢复。要求 `ctx.agents`；冷恢复还要求会话持久化。 |
-| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。尚未领取的待处理 inbox 工作、Activation 与已发布的后代均保持不变；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。 |
+| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入同步完成、生效异步进行：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。尚未领取的待处理 inbox 工作、Activation 与已发布的后代均保持不变；已被领取进入中断轮次的工作不会重新入队。目标不存在时接受为 no-op；错误的 parent 地址以及过期、指向自身或非祖先调用方以 `UNAUTHORIZED` 拒绝。 |
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
+| `listDescendants(rootSessionId, signal?)` | 从同一份实时优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消契约均沿用 `listChildren()`。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -77,7 +78,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
 
-可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代——因为停止一个轮次是幂等的，且不投递任何内容。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
 当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
@@ -85,7 +86,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task 或结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，而 `interrupt()` 只停止当前轮次，不 dispose 子 agent。持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 8bf4efb5d0..2a118565fa 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -19,9 +19,9 @@
  * resident. Continuable children never become a {@link SubagentRun}: the
  * continuation manager holds their `AgentHandle` directly and orders every turn
  * through the child's own inbox, so providers contribute only the detached
- * creation spec and see no handle, turn, or teardown. Direct-child discovery
- * reads the live session store and optional session persistence directly and
- * does not require that continuation runtime.
+ * creation spec and see no handle, turn, or teardown. Child and descendant
+ * discovery read the live session store and optional session persistence
+ * directly and do not require that continuation runtime.
  *
  * Same-process providers are trusted typed collaborators. Requests, provider
  * descriptors, results, and lifecycle payloads are borrowed immutable values;
@@ -63,8 +63,8 @@ import type {
 } from './continuation.ts'
 import SubagentActivationSetupRegistry from './activation-setup-registry.ts'
 import type { ContinuableSetupContribution } from './activation-setup-registry.ts'
-import { listChildren as listSubagentChildren } from './list-children.ts'
-import type { SubagentListEntry } from './list-children.ts'
+import { listChildren as listSubagentChildren, listDescendants as listSubagentDescendants } from './list-children.ts'
+import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts'
 import { snapshotSubagentDescriptor } from './descriptor.ts'
 import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts'
 
@@ -118,7 +118,7 @@ export type {
   SubagentReportOptions,
 } from './continuation.ts'
 export type { ContinuableSetupContribution } from './activation-setup-registry.ts'
-export type { SubagentListEntry } from './list-children.ts'
+export type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts'
 export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts'
 export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts'
 
@@ -336,6 +336,25 @@ export class SubagentService extends Service {
     return listSubagentChildren(this.ctx, parentSessionId, signal)
   }
 
+  /**
+   * Enumerate the root's complete session-backed subagent tree in stable
+   * pre-order from one live-preferred corpus, without loading or resuming an
+   * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+   * continuable descendants below them are discovered; each returned entry
+   * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+   * diagnostics, optional persistence, and cancellation follow the same
+   * projection-backed contract as {@link listChildren}.
+   * @param rootSessionId - session whose complete descendant tree is listed.
+   * @param signal - caller-owned cancellation forwarded to persistence reads
+   *   and observed around every read await.
+   * @returns children and per-candidate diagnostics with tree position, in
+   *   stable pre-order.
+   * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+   */
+  listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]> {
+    return listSubagentDescendants(this.ctx, rootSessionId, signal)
+  }
+
   /**
    * Register a provider under its name. Registration is effect-scoped and HMR
    * safe; removing a provider blocks new starts but does not revoke runs that
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index fef098f90f..db3339e197 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,18 +1,16 @@
 /**
- * Read-only enumeration of one parent's durable subagent children straight
- * from the live session store and optional session persistence — no query
- * seam. Candidates are the live-preferred merge of both listings filtered to
- * durable `origin: 'subagent'` under the parent; each child's mode/label is
- * the registered `subagent` projection unit's value, resolved down a
- * three-rung ladder: the registry's watermark cache for a live child, a
- * durable projection-cache row when it serves an own-suffix identity (the
+ * Read-only enumeration of durable subagent children and descendant trees
+ * straight from the live session store and optional session persistence — no
+ * query seam. Candidates come from one live-preferred corpus; each child's
+ * mode/label is the registered `subagent` projection unit's value, resolved
+ * down a three-rung ladder: the registry's watermark cache for a live child,
+ * a durable projection-cache row when it serves an own-suffix identity (the
  * seq gate), and one persistence inspection folded through the registry
- * otherwise, validated against the enumerated lifecycle. The projection
- * fold is the single
- * classification authority — this module parses no descriptor itself. Absent
- * persistence, enumeration is live-only: a cold child is unreachable for
- * resume anyway, so its absence is capability absence, not an error. The
- * module owns no catalog state and does not consult Activation,
+ * otherwise, validated against the enumerated lifecycle. The projection fold
+ * is the single classification authority — this module parses no descriptor
+ * itself. Absent persistence, enumeration is live-only: a cold child is
+ * unreachable for resume anyway, so its absence is capability absence, not an
+ * error. The module owns no catalog state and does not consult Activation,
  * Agent-registry, continuation-manager, or provider state.
  *
  * @module @deepseek-ai/dsh-subagent
@@ -88,6 +86,34 @@ export type SubagentListEntry =
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+export type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Durable direct parent of this candidate in the enumerated tree. */
+  readonly parentId: SessionId
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number
+}
+
+type CorpusRecord = { readonly header: SessionHeader; readonly live: Session | undefined }
+
+interface ListingRuntime {
+  readonly projections: SessionProjectionRegistry
+  readonly persistence: SessionPersistence | undefined
+  readonly cache: SessionProjectionCache | undefined
+  readonly corpus: ReadonlyMap<SessionId, CorpusRecord>
+  readonly subagentParents: ReadonlySet<SessionId>
+}
+
+interface PositionedCandidate {
+  readonly record: CorpusRecord
+  readonly parentId: SessionId
+  readonly depth: number
+}
+
 /**
  * Enumerate one parent's origin-classified direct children from the
  * live-preferred merge of `ctx.sessions` and optional session persistence,
@@ -110,6 +136,55 @@ export async function listChildren(
   parentSessionId: SessionId,
   signal?: AbortSignal,
 ): Promise<SubagentListEntry[]> {
+  const listing = await prepareListing(ctx, signal)
+  const candidates = [...listing.corpus.values()]
+    .filter(record => record.header.parentSession === parentSessionId
+      && record.header.origin === 'subagent')
+    .sort(compareCorpusRecords)
+  const rows = await resolveCandidateRows(candidates, listing, signal)
+  return rows.filter((row): row is SubagentListEntry => row !== undefined)
+}
+
+/**
+ * Enumerate every session-backed subagent below one root in stable pre-order.
+ * Ordinary sessions and one-shot children remain traversal nodes, so a
+ * continuable child below either is still discovered. Classification uses the
+ * same projection-backed runtime as {@link listChildren}; no Agent is loaded or
+ * resumed.
+ * @see SubagentService.listDescendants for the public cancellation and failure contract.
+ * @param ctx - context carrying the session store, projection registry, and optional persistence/cache.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns interpreted subagents with durable direct-parent and root-relative depth.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+export async function listDescendants(
+  ctx: Context,
+  rootSessionId: SessionId,
+  signal?: AbortSignal,
+): Promise<SubagentDescendantListEntry[]> {
+  const listing = await prepareListing(ctx, signal)
+  const positioned = descendantCandidates(listing.corpus, rootSessionId)
+  const rows = await resolveCandidateRows(
+    positioned.map(candidate => candidate.record),
+    listing,
+    signal,
+  )
+  const entries: SubagentDescendantListEntry[] = []
+  positioned.forEach((position, index) => {
+    const row = rows[index]
+    if (row !== undefined) {
+      entries.push({ ...row, parentId: position.parentId, depth: position.depth })
+    }
+  })
+  return entries
+}
+
+/** Resolve listing services once and build one live-preferred session corpus. */
+async function prepareListing(
+  ctx: Context,
+  signal: AbortSignal | undefined,
+): Promise<ListingRuntime> {
   const projections = ctx.get('sessionProjections')
   // Checked before any read, even with zero candidates: mode/label are the
   // row's strong contract, so a missing fold capability is a deterministic
@@ -150,7 +225,7 @@ export async function listChildren(
   }
   // Live-preferred merge without header reconciliation: a live record wins
   // its id wholesale, exactly as a live-preferred corpus would serve it.
-  const corpus = new Map<SessionId, { header: SessionHeader; live: Session | undefined }>()
+  const corpus = new Map<SessionId, CorpusRecord>()
   for (const header of persistedHeaders) corpus.set(header.id, { header, live: undefined })
   for (const session of sessions.list()) {
     corpus.set(session.header.id, { header: session.header, live: session })
@@ -161,12 +236,16 @@ export async function listChildren(
       subagentParents.add(record.header.parentSession)
     }
   }
-  const candidates = [...corpus.values()]
-    .filter(record => record.header.parentSession === parentSessionId
-      && record.header.origin === 'subagent')
-    .sort((a, b) => a.header.createdAt - b.header.createdAt
-      || a.header.id.localeCompare(b.header.id))
+  return { projections, persistence, cache, corpus, subagentParents }
+}
 
+/** Resolve projection-backed rows for aligned candidates with bounded cold reads. */
+async function resolveCandidateRows(
+  candidates: readonly CorpusRecord[],
+  listing: ListingRuntime,
+  signal: AbortSignal | undefined,
+): Promise<(SubagentListEntry | undefined)[]> {
+  const { projections, persistence, cache, subagentParents } = listing
   const rows: (SubagentListEntry | undefined)[] = Array.from({ length: candidates.length })
   const coldReads: { index: number; header: SessionHeader }[] = []
   candidates.forEach((candidate, index) => {
@@ -212,7 +291,47 @@ export async function listChildren(
     ))
   }
   assertListingNotCancelled(signal)
-  return rows.filter((row): row is SubagentListEntry => row !== undefined)
+  return rows
+}
+
+/** Build origin-classified candidates from the complete tree without recursion. */
+function descendantCandidates(
+  corpus: ReadonlyMap<SessionId, CorpusRecord>,
+  rootSessionId: SessionId,
+): PositionedCandidate[] {
+  const children = new Map<SessionId, CorpusRecord[]>()
+  for (const record of corpus.values()) {
+    const parentId = record.header.parentSession
+    if (parentId === undefined) continue
+    const siblings = children.get(parentId)
+    if (siblings === undefined) children.set(parentId, [record])
+    else siblings.push(record)
+  }
+  for (const siblings of children.values()) siblings.sort(compareCorpusRecords)
+
+  const positioned: PositionedCandidate[] = []
+  const stack: PositionedCandidate[] = (children.get(rootSessionId) ?? [])
+    .map(record => ({ record, parentId: rootSessionId, depth: 1 }))
+    .reverse()
+  const visited = new Set<SessionId>([rootSessionId])
+  while (stack.length > 0) {
+    const position = stack.pop()
+    if (position === undefined) break
+    const id = position.record.header.id
+    if (visited.has(id)) continue
+    visited.add(id)
+    if (position.record.header.origin === 'subagent') positioned.push(position)
+    const descendants = children.get(id) ?? []
+    for (const record of [...descendants].reverse()) {
+      stack.push({ record, parentId: id, depth: position.depth + 1 })
+    }
+  }
+  return positioned
+}
+
+/** Compare siblings by durable creation time, then id. */
+function compareCorpusRecords(a: CorpusRecord, b: CorpusRecord): number {
+  return a.header.createdAt - b.header.createdAt || a.header.id.localeCompare(b.header.id)
 }
 
 /**
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index ef52883db2..31c8f1c6aa 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -972,3 +972,197 @@ describe('SubagentService.listChildren', () => {
     expect((caught as SubagentError).code).toBe('SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE')
   })
 })
+
+describe('SubagentService.listDescendants', () => {
+  it('flattens the complete tree in stable pre-order with verified parent and depth', async () => {
+    const { ctx, parent } = await setup([])
+    const childA = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaa1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('branch a')))
+    const grandchild = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaa2', {
+      parentSession: childA,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('under a')))
+    const childB = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaa3', {
+      parentSession: parent.id,
+      createdAt: 3,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('branch b')))
+
+    const entries = await ctx.subagents.listDescendants(parent.id)
+    expect(entries).toEqual([
+      {
+        kind: 'child', id: childA, label: 'branch a', mode: 'continuable',
+        activity: 'inactive', hasChildren: true, parentId: parent.id, depth: 1,
+      },
+      {
+        kind: 'child', id: grandchild, label: 'under a', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: childA, depth: 2,
+      },
+      {
+        kind: 'child', id: childB, label: 'branch b', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: parent.id, depth: 1,
+      },
+    ])
+  })
+
+  it('walks a deeply nested ordinary-session chain without consuming the call stack', async () => {
+    const { ctx, parent } = await setup([])
+    const depth = 10_000
+    let parentId = parent.id
+    for (let level = 1; level < depth; level += 1) {
+      const session = ctx.sessions.create(SessionId(`deep-ordinary-${level}`), {
+        meta: { createdAt: level, parentSession: parentId },
+      })
+      parentId = session.id
+    }
+    const leafId = SessionId('deep-subagent-leaf')
+    const leaf = ctx.sessions.create(leafId, {
+      meta: { createdAt: depth, parentSession: parentId, origin: 'subagent' },
+    })
+    leaf.append('turn/start', { turn: 1 })
+    leaf.append('subagent/descriptor', descriptorPayload('deep leaf'))
+
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([{
+      kind: 'child', id: leafId, label: 'deep leaf', mode: 'continuable',
+      activity: 'running', hasChildren: false, parentId, depth,
+    }])
+  })
+
+  it('discovers continuable descendants below ordinary and one-shot intermediates', async () => {
+    const { ctx, parent } = await setup([textResponse('one shot')])
+    // An ordinary fork has no descriptor: omitted itself, subtree still walked.
+    const fork = ctx.sessions.fork(parent.session, undefined, SessionId('plain-fork'))
+    await ctx.sessions.flush(fork)
+    const underFork = await authorChild(ctx, '00000000-0000-4000-8000-00000000bbb1', {
+      parentSession: fork.header.id,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('under the fork')))
+    // A real one-shot child, then a continuable authored below it.
+    const oneShot = await ctx.subagents.start('spawn', {
+      label: 'one-shot intermediate',
+      prompt: [{ type: 'text', text: 'one-shot task' }],
+      parent,
+      signal: testSignal,
+    })
+    await oneShot.result
+    await ctx.sessions.flush(oneShot.localAgent!.session)
+    const oneShotId = oneShot.id
+    await oneShot.dispose()
+    const underOneShot = await authorChild(ctx, '00000000-0000-4000-8000-00000000bbb2', {
+      parentSession: oneShotId,
+      createdAt: 9_999_999_999_999,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('under the one-shot')))
+
+    const entries = await ctx.subagents.listDescendants(parent.id)
+    // The fork is absent (descriptor-less); the one-shot is present with its
+    // mode so a caller can see the lineage it walked through.
+    expect(entries.map(entry => entry.id)).not.toContain(fork.header.id)
+    expect(entries).toContainEqual({
+      kind: 'child', id: underFork, label: 'under the fork', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: fork.header.id, depth: 2,
+    })
+    expect(entries).toContainEqual(expect.objectContaining({
+      kind: 'child', id: oneShotId, mode: 'one-shot', parentId: parent.id, depth: 1,
+    }))
+    expect(entries).toContainEqual({
+      kind: 'child', id: underOneShot, label: 'under the one-shot', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: oneShotId, depth: 2,
+    })
+    // Pre-order: every child appears after its own parent entry.
+    const position = new Map(entries.map((entry, index) => [entry.id, index]))
+    expect(position.get(underOneShot)!).toBeGreaterThan(position.get(oneShotId)!)
+  })
+
+  it('diagnoses a settled descriptor-less node while walking its subtree', async () => {
+    const { ctx, parent } = await setup([])
+    // A settled origin-marked candidate without an identity is corrupt under
+    // the projection contract, but its subtree remains independently visible.
+    const bare = await authorChild(ctx, '00000000-0000-4000-8000-00000000eee1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] as SessionEvent[])
+    const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000eee2', {
+      parentSession: bare,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('below the bare node')))
+
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([
+      { kind: 'diagnostic', id: bare, reason: 'corrupt', parentId: parent.id, depth: 1 },
+      {
+        kind: 'child', id: below, label: 'below the bare node', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: bare, depth: 2,
+      },
+    ])
+  })
+
+  it('keeps traversing below a corrupt intermediate and positions its diagnostic', async () => {
+    const { ctx, parent } = await setup([])
+    const corrupt = await authorChild(ctx, '00000000-0000-4000-8000-00000000ccc1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('unsupported descriptor', 999)))
+    const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000ccc2', {
+      parentSession: corrupt,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('below the corrupt node')))
+
+    const entries = await ctx.subagents.listDescendants(parent.id)
+    expect(entries).toEqual([
+      { kind: 'diagnostic', id: corrupt, reason: 'corrupt', parentId: parent.id, depth: 1 },
+      {
+        kind: 'child', id: below, label: 'below the corrupt node', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: corrupt, depth: 2,
+      },
+    ])
+  })
+
+  it('verifies a cold candidate still belongs to its enumerated lifecycle', async () => {
+    const { ctx, parent } = await setup([])
+    const childId = await authorChild(ctx, '00000000-0000-4000-8000-00000000ddd1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('lineage checked')))
+    const realInspect = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = async (sessionId, signal) => {
+      const inspected = await realInspect(sessionId, signal)
+      // The exact read reports a different durable parent than enumeration did.
+      return { ...inspected, meta: { ...inspected.meta, parentSession: SessionId('someone-else') } }
+    }
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([
+      { kind: 'diagnostic', id: childId, reason: 'corrupt', parentId: parent.id, depth: 1 },
+    ])
+  })
+
+  it('a pre-aborted signal stops the descendant scan before persistence reads', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    await startChild(ctx, parent, 'never read')
+    const list = vi.spyOn(ctx.sessionPersistence, 'list')
+    const controller = new AbortController()
+    controller.abort()
+    await expect(ctx.subagents.listDescendants(parent.id, controller.signal)).rejects.toThrow(
+      expect.objectContaining({ code: 'CANCELLED' }) as Error,
+    )
+    expect(list).not.toHaveBeenCalled()
+  })
+
+  it('fails loud when the projection registry is not mounted', async () => {
+    const { ctx, parent } = await setup([], { sessionProjections: false })
+    await expect(ctx.subagents.listDescendants(parent.id)).rejects.toThrow(
+      expect.objectContaining({ code: 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE' }) as Error,
+    )
+  })
+})
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index f26a290f5e..367a73fd1f 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
-README.md: ea95a45b85e01d1f5f1c478a35c80c65151724ac
-README.zh.md: 2cc876c8b39caa19fdf30eae7c8def0ba81fe7b1
+README.md: 4d9991b720bbbff8862e693b6aaed332f414af0e
+README.zh.md: dc1c81fc3313a8dfa277f33ae745702ed5b9d34b
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index ea95a45b85..4d9991b720 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -2,11 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The optional, globally named `send_message` and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and the separately loadable `./list-agents` plugin registers `list_agents`; both require only `subagents`, so a deployment can keep `send_message` while omitting the list tool. Neither tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
+The optional, globally named `send_message`, `interrupt_agent`, and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and `interrupt_agent` and requires only `subagents`; the separately loadable `./list-agents` plugin registers `list_agents` and declares `subagents` plus `agents` as load-time dependencies. Its catalog reads additionally require the session store and projection registry at call time, but no query service. A deployment can keep the root tools while omitting the list tool. No tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
 
 The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and attributes every message as durable provenance `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
 
-`list_agents` takes no arguments, derives the parent id from the calling agent, and projects `ctx.subagents.listChildren()` to continuable children without a cursor. The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain `send_message`'s.
+`interrupt_agent(agent_id)` passes `exec.agent` as the exact live ancestor authority for `ctx.subagents.interrupt()`: the target may be a direct child or a deeper descendant, and the service — never this tool — verifies the caller against the target Activation's recorded lineage. Only the target's current turn stops (`keepInbox`): queued messages stay parked until a later `send_message`, published descendants keep running, and the child stays available for follow-ups. The call returns as soon as the stop request is accepted, without waiting for target quiescence; an absent or already-settled target is an accepted no-op, while self, sibling, stale, and non-ancestor callers become errored results.
+
+`list_agents` takes one optional `scope` argument, derives the root id from the calling agent, and projects the service catalog to continuable children without a cursor. The default `children` scope reads `ctx.subagents.listChildren()`; `descendants` reads `ctx.subagents.listDescendants()`, whose one-corpus walk crosses ordinary sessions and one-shot children and renders surviving rows in stable pre-order with `parent=<id> depth=<n>`. The `parent` annotation is the durable direct-parent session id and may name an ordinary session omitted from the output. For the calling agent, only depth-1 child entries are `send_message` candidates; deeper child entries are `interrupt_agent` candidates only. Status comes from the live Agent registry: `running` (active driver), `idle` (resident between turns, possibly waiting on agents it started), `complete` (storage only). The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible, with positions in the descendants scope. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain the service's.
 
 ## Model Experience
 
@@ -14,7 +16,7 @@ The tool performs no lifecycle routing — residency and cold resume belong to t
 
 #### What the model sees
 
-The generated [`send_message` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control): `subagent_id` and `message`, describing that the message becomes the subagent's next turn, that this call returns no answer from the subagent, and that a failure means the message was not delivered.
+The generated [schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control): `send_message` takes `subagent_id` and `message`, describing that the message becomes the subagent's next turn, that this call returns no answer from the subagent, and that a failure means the message was not delivered; `interrupt_agent` takes `agent_id`, describing that only the current turn stops, queued messages park, descendants keep running, and acceptance precedes the actual stop; `list_agents` takes the optional `scope` enum.
 
 #### Token effect
 
@@ -24,6 +26,20 @@ Fixed schema cost per parent request.
 
 Prefix-stable; the schema does not change at runtime.
 
+### Interrupt result
+
+#### What the model sees
+
+`interrupt requested for agent <agent_id>` on acceptance. An unauthorized caller — self, sibling, stale, or non-ancestor — is an errored result naming the rejection; an absent or settled target still renders the acceptance line.
+
+#### Token effect
+
+One short acknowledgement per call; the interrupted turn's abort is visible only in the child's own transcript.
+
+#### KV Cache effect
+
+Append-only; each result follows the reusable request prefix.
+
 ### Delivery result
 
 #### What the model sees
@@ -42,11 +58,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-One line per continuable child in the trace's stable order: `<id> [<status>] — <label>` (`running` = the logical session is live, `complete` = persisted only and resumable by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection. Diagnostics never expose descriptor contents.
+One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = active driver, `idle` = resident between turns, `complete` = storage only; a direct child in that state can be resumed by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection. Diagnostics never expose descriptor contents.
 
 #### Token effect
 
-Grows linearly with the parent's direct continuable children; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
+Grows linearly with the listed continuable children — the whole tree under the `descendants` scope; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
 
 #### KV Cache effect
 
@@ -56,5 +72,5 @@ Append-only; each result follows the reusable request prefix.
 
 - **A queued message has no independent result** — acceptance returns only its inbox `messageId`; the child's work lands in the durable child Session and is never collected through this tool. A child granted `report` may send selected content back separately, but that message is not this call's result.
 - **No steering of the current turn** — every message opens a later FIFO turn, so a message sent while the child is working runs only after its current turn finishes and cannot redirect it.
-- **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `complete`; cross-process accuracy requires a shared lease.
+- **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `complete`; cross-process accuracy requires a shared lease. `interrupt_agent` performs the authoritative live-lineage check itself, so discovery staleness cannot grant authority.
 - **No pagination or deletion** — the complete stably ordered set is returned, and persisted children remain listed for as long as their sessions remain in persistence; a service-level bound or delete operation is a later product decision.
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index 2cc876c8b3..dc1c81fc33 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -2,11 +2,13 @@
 
 [English](README.md) | 中文
 
-可选的全局具名 `send_message` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message`，可单独加载的 `./list-agents` 插件注册 `list_agents`；两者都只要求 `subagents`，部署可保留 `send_message` 而省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
+可选的全局具名 `send_message`、`interrupt_agent` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message` 与 `interrupt_agent`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，并将 `subagents` 与 `agents` 声明为加载时依赖。其目录读取在调用时还要求会话存储与投影注册表，但不要求任何查询服务。部署可保留根插件工具并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
 
 本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
-`list_agents` 不接受参数，会从调用它的 agent 推导 parent id，并且不使用 cursor，将 `ctx.subagents.listChildren()` 的结果投影为可继续 child。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归 `send_message` 负责。
+`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标静止；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
+
+`list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）、`complete`（仅存于存储）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
 
 ## 模型体验
 
@@ -14,7 +16,7 @@
 
 #### 模型看到的内容
 
-已生成的 [`send_message` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control)：包含 `subagent_id` 和 `message`，说明消息会成为子 agent 的下一个轮次、本次调用不会返回子 agent 的回答，以及失败即表示消息未送达。
+已生成的 [schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control)：`send_message` 包含 `subagent_id` 和 `message`，说明消息会成为子 agent 的下一个轮次、本次调用不会返回子 agent 的回答，以及失败即表示消息未送达；`interrupt_agent` 包含 `agent_id`，说明只有当前轮次会停止、已排队消息保持暂停、后代继续运行，以及接受先于实际停止；`list_agents` 包含可选的 `scope` 枚举。
 
 #### Token 影响
 
@@ -24,6 +26,20 @@
 
 前缀保持稳定；schema 不会在运行时改变。
 
+### 中断结果
+
+#### 模型看到的内容
+
+接受时返回 `interrupt requested for agent <agent_id>`。未授权的调用方——self、sibling、过期或非 ancestor——会成为指明拒绝原因的出错结果；目标不存在或已结算仍渲染接受行。
+
+#### Token 影响
+
+每次调用产生一条简短确认消息；被中断轮次的中止只在 child 自己的 transcript 中可见。
+
+#### KV Cache 影响
+
+仅追加；每个结果都位于可复用请求前缀之后。
+
 ### 投递结果
 
 #### 模型看到的内容
@@ -42,11 +58,11 @@
 
 #### 模型看到的内容
 
-按追踪结果的稳定顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示逻辑会话存活，`complete` 表示仅存在于持久化存储中，可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
+按稳定目录顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示 driver 活跃，`idle` 表示驻留但处于轮次之间，`complete` 表示仅存于存储；处于该状态的直接 child 可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。`descendants` scope 会在每行 label 破折号之前插入 ` parent=<id> depth=<n>`，按 pre-order 排列。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
 
 #### Token 影响
 
-随 parent 的直接可继续 child 数量线性增长；没有 cursor 或上限，因此长期存活且有许多持久化 child 的 parent 每次调用都会承担完整列表成本。
+随所列可继续 child 数量线性增长——`descendants` scope 下为整棵树；没有 cursor 或上限，因此长期存活且有许多持久化 child 的 parent 每次调用都会承担完整列表成本。
 
 #### KV Cache 影响
 
@@ -56,5 +72,5 @@
 
 - **已排队的消息没有独立结果**：接受时只返回其 inbox `messageId`；子 agent 的工作会落入持久化子 agent 会话，绝不会通过本工具收集。获得 `report` 的子 agent 可以单独发回选定内容，但该消息不是本次调用的结果。
 - **不对当前轮次进行 steering（中途引导）**：每条消息都会开启后续 FIFO 轮次，因此在子 agent 工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。
-- **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。
+- **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
 - **没有分页或删除**：系统返回完整且稳定排序的集合；只要 child 会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。
diff --git a/packages/subagent/tool-subagent-control/src/index.ts b/packages/subagent/tool-subagent-control/src/index.ts
index 95cf4e4183..43e3f52b4e 100644
--- a/packages/subagent/tool-subagent-control/src/index.ts
+++ b/packages/subagent/tool-subagent-control/src/index.ts
@@ -1,9 +1,11 @@
 /**
- * The globally named `send_message` tool: a thin model-facing adapter over
- * `ctx.subagents.followup()`. It performs no lifecycle routing of its own —
- * residency and cold resume belong to the subagent service — and it lives apart
- * from the provider-bound `@deepseek-ai/dsh-tool-subagent` instances so multiple
- * delegation tools share one control tool.
+ * The globally named `send_message` and `interrupt_agent` tools: thin
+ * model-facing adapters over `ctx.subagents.followup()` and
+ * `ctx.subagents.interrupt()`. They perform no lifecycle routing of their own —
+ * residency, cold resume, and interrupt authorization belong to the subagent
+ * service — and they live apart from the provider-bound
+ * `@deepseek-ai/dsh-tool-subagent` instances so multiple delegation tools share
+ * one control surface.
  * @module @deepseek-ai/dsh-tool-subagent-control
  */
 
@@ -17,7 +19,7 @@ export const name = 'tool-subagent-control'
 export const inject = ['tools', 'subagents']
 
 /**
- * Register the `send_message` tool.
+ * Register the `send_message` and `interrupt_agent` tools.
  * @param ctx - context carrying the tool registry and subagent service.
  */
 export function apply(ctx: Context): void {
@@ -73,4 +75,46 @@ export function apply(ctx: Context): void {
       return { messageId }
     },
   }))
+
+  ctx.tools.register(defineTool({
+    name: 'interrupt_agent',
+    description:
+      'Request cancellation of a background agent\'s current turn by its agent id. The target may be your '
+      + 'direct child or a deeper agent created under you. Only the current turn stops: messages already '
+      + 'queued for the agent stay parked until a later send_message, agents it started keep running, and '
+      + 'the agent itself stays available for follow-ups. This call returns as soon as the stop request is '
+      + 'accepted, so the target may keep running briefly; interrupting an agent that already finished is '
+      + 'an accepted no-op.',
+    parameters: {
+      agent_id: {
+        type: 'string',
+        required: true,
+        description: 'The agent id of the running agent to interrupt.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          accepted: { type: 'boolean', required: true },
+        },
+      },
+      render: (args, _value) => [{
+        type: 'text',
+        text: `interrupt requested for agent ${args.agent_id}`,
+      }],
+    },
+    execute(args, exec) {
+      const caller = exec.agent
+      if (!caller) {
+        // Ancestor authority requires an exact live calling agent.
+        throw new Error('interrupt_agent requires a calling agent (exec.agent was undefined)')
+      }
+      // The service authorizes the exact live caller against the target's
+      // recorded lineage; the tool adds no authority of its own.
+      ctx.subagents.interrupt(SessionId(args.agent_id), { kind: 'ancestor', agent: caller })
+      return Promise.resolve({ accepted: true })
+    },
+  }))
 }
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index bab3fb6f40..c39ebbc648 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -1,46 +1,95 @@
 /**
  * The globally named `list_agents` tool: a thin model-facing adapter over
- * the continuable projection of `ctx.subagents.listChildren()`. It stays
- * separately loadable from the root `send_message` plugin so a deployment
- * can register `send_message` without exposing the list tool.
+ * the continuable projection of `ctx.subagents.listChildren()` and, for the
+ * `descendants` scope, `ctx.subagents.listDescendants()`. It stays separately
+ * loadable from the root `send_message` plugin so a deployment can register
+ * continuation delivery without exposing discovery.
  * @module @deepseek-ai/dsh-tool-subagent-control/list-agents
  */
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-subagent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SubagentDescendantListEntry, SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 
 export const name = 'tool-subagent-list-agents'
-export const inject = ['tools', 'subagents']
+export const inject = ['tools', 'subagents', 'agents']
 
 type ListAgentsEntry =
   | {
     readonly kind: 'child'
     readonly id: string
     readonly label: string
-    readonly status: 'running' | 'complete'
+    readonly status: 'running' | 'idle' | 'complete'
+    readonly parent?: string
+    readonly depth?: number
   }
   | {
     readonly kind: 'diagnostic'
     readonly id: string
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
+    readonly parent?: string
+    readonly depth?: number
   }
 
+/**
+ * Refine one candidate's status through the live Agent registry: `running`
+ * for an active driver, `idle` for a resident Agent between turns (possibly
+ * waiting on agents it started), and `complete` when no live Agent remains.
+ */
+function statusOf(agents: { get(id: SessionId): Agent | undefined }, id: SessionId): 'running' | 'idle' | 'complete' {
+  const agent = agents.get(id)
+  if (agent === undefined) return 'complete'
+  return agent.status === 'running' ? 'running' : 'idle'
+}
+
+/** Project one service row into the model-facing entry, or omit a one-shot child. */
+function project(
+  agents: { get(id: SessionId): Agent | undefined },
+  entry: SubagentListEntry,
+  position?: Pick<SubagentDescendantListEntry, 'parentId' | 'depth'>,
+): ListAgentsEntry | undefined {
+  const at = position === undefined ? {} : { parent: position.parentId as string, depth: position.depth }
+  if (entry.kind === 'diagnostic') {
+    return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
+  }
+  // One-shot children cannot be continued by send_message, so the model
+  // never selects them; discovery still traversed them for descendants.
+  if (entry.mode !== 'continuable') return undefined
+  return {
+    kind: 'child',
+    id: entry.id,
+    label: entry.label,
+    status: statusOf(agents, entry.id),
+    ...at,
+  }
+}
+
 /**
  * Register the `list_agents` tool.
- * @param ctx - context carrying the tool registry and subagent service.
+ * @param ctx - context carrying the tool registry, subagent service, and live Agent registry.
  */
 export function apply(ctx: Context): void {
   ctx.tools.register(defineTool({
     name: 'list_agents',
     description:
-      'List your continuable background subagents by durable id and label. Status is a snapshot of the stored '
-      + 'record: running means the subagent session is currently live in this process, complete means '
-      + 'it exists only in storage and a `send_message` starts a new turn on the same conversation. '
-      + 'The snapshot is not a delivery promise — `send_message` performs the authoritative check and '
-      + 'may still fail. Children that could not be read are reported as diagnostics instead of being '
-      + 'silently dropped.',
-    parameters: {},
+      'List your continuable background subagents by durable id and label. Status comes from the live '
+      + 'registry: running means the agent is working right now, idle means it is loaded but between turns '
+      + '(it may be waiting on agents it started), and complete means it exists only in storage — a '
+      + 'direct child remains a `send_message` candidate in every status. The snapshot is not a delivery '
+      + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
+      + 'not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` '
+      + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
+      + 'session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are '
+      + 'candidates for `interrupt_agent` only.',
+    parameters: {
+      scope: {
+        type: 'string',
+        enum: ['children', 'descendants'],
+        description: 'children (default) lists direct children only; descendants walks the complete tree below you.',
+      },
+    },
     output: {
       schema: {
         type: 'array',
@@ -53,7 +102,9 @@ export function apply(ctx: Context): void {
                 kind: { type: 'string', required: true, enum: ['child'] },
                 id: { type: 'string', required: true },
                 label: { type: 'string', required: true },
-                status: { type: 'string', required: true, enum: ['running', 'complete'] },
+                status: { type: 'string', required: true, enum: ['running', 'idle', 'complete'] },
+                parent: { type: 'string' },
+                depth: { type: 'number' },
               },
             },
             {
@@ -63,21 +114,31 @@ export function apply(ctx: Context): void {
                 kind: { type: 'string', required: true, enum: ['diagnostic'] },
                 id: { type: 'string', required: true },
                 reason: { type: 'string', required: true, enum: ['corrupt', 'unsupported', 'unavailable'] },
+                parent: { type: 'string' },
+                depth: { type: 'number' },
               },
             },
           ],
         },
       },
-      render: (_args, entries) => [{
+      render: (args, entries) => [{
         type: 'text',
         text: entries.length === 0
           ? '(no subagents)'
-          : entries.map(entry => entry.kind === 'child'
-            ? `${entry.id} [${entry.status}] — ${entry.label}`
-            : `${entry.id} [diagnostic: ${entry.reason}]`).join('\n'),
+          : entries.map((entry) => {
+            // A descendants row always carries its position; children rows
+            // never render it. String() spans the schema-optional shape
+            // without a dead fallback branch.
+            const at = args.scope === 'descendants'
+              ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
+              : ''
+            return entry.kind === 'child'
+              ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
+              : `${entry.id} [diagnostic: ${entry.reason}]${at}`
+          }).join('\n'),
       }],
     },
-    async execute(_args, exec) {
+    async execute(args, exec) {
       const parent = exec.agent
       if (!parent) {
         // Non-agent callers have no session whose children could be listed.
@@ -85,21 +146,16 @@ export function apply(ctx: Context): void {
       }
       // The registry drains started tool bodies, so the scan must observe the
       // call's signal rather than finish a slow catalog after cancellation.
-      const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
-      const visible: ListAgentsEntry[] = []
-      for (const entry of entries) {
-        if (entry.kind === 'diagnostic') {
-          visible.push(entry)
-        } else if (entry.mode === 'continuable') {
-          visible.push({
-            kind: 'child',
-            id: entry.id,
-            label: entry.label,
-            status: entry.activity === 'running' ? 'running' : 'complete',
-          })
-        }
+      if (args.scope === 'descendants') {
+        const entries = await ctx.subagents.listDescendants(parent.id, exec.signal)
+        return entries
+          .map(entry => project(ctx.agents, entry, entry))
+          .filter(entry => entry !== undefined)
       }
-      return visible
+      const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
+      return entries
+        .map(entry => project(ctx.agents, entry))
+        .filter(entry => entry !== undefined)
     },
   }))
 }
diff --git a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
index e734ae8222..3131809d37 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -12,9 +12,37 @@ import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import * as tool from '../src/list-agents.ts'
 
+/** One scripted response that may wait on a caller-released gate before streaming. */
+interface GatedEntry {
+  chunks: StreamChunk[]
+  gate?: Promise<undefined>
+}
+
+/** Adapter whose entries can hold a model call open until the test releases it. */
+class GatedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+
+  constructor(private script: GatedEntry[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.script.shift()
+    if (!entry) throw new Error('GatedAdapter: script exhausted')
+    if (entry.gate) await entry.gate
+    for (const chunk of entry.chunks) {
+      if (options.signal?.aborted) throw new Error('aborted')
+      yield chunk
+    }
+  }
+}
+
 const testToolSignal = new AbortController().signal
 
 const roots: string[] = []
@@ -22,7 +50,7 @@ afterEach(() => {
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
-async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+async function setupWith(adapter: MockAdapter | GatedAdapter) {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   const root = mkdtempSync(join(tmpdir(), 'dsh-tool-list-agents-'))
@@ -33,9 +61,13 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(tool)
-  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
+  ctx.llm.registerAdapter(['mock'], adapter)
   const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
-  return { ctx, parent }
+  return { ctx, parent, adapter }
+}
+
+async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+  return setupWith(new MockAdapter(script))
 }
 
 function text(result: { content: { type: string; text?: string }[] }): string {
@@ -67,13 +99,19 @@ async function waitNoActivation(ctx: Context, childId: SessionId): Promise<void>
 }
 
 describe('dsh-tool-subagent-control/list-agents', () => {
-  it('registers list_agents once, globally, with no parameters', async () => {
+  it('registers list_agents once, globally, with only the optional scope parameter', async () => {
     const { ctx } = await setup([])
     const schemas = ctx.tools.schemas().filter(schema => schema.name === 'list_agents')
     expect(schemas).toHaveLength(1)
-    const props = (schemas[0]!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
-    expect(Object.keys(props)).toEqual([])
+    const parameters = schemas[0]!.parameters as {
+      properties?: Record<string, { enum?: string[] }>
+      required?: string[]
+    }
+    expect(Object.keys(parameters.properties ?? {})).toEqual(['scope'])
+    expect(parameters.properties?.scope?.enum).toEqual(['children', 'descendants'])
+    expect(parameters.required ?? []).toEqual([])
     expect(schemas[0]!.description).toContain('send_message')
+    expect(schemas[0]!.description).toContain('interrupt_agent')
   })
 
   it('renders the empty result as (no subagents)', async () => {
@@ -84,7 +122,7 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     expect(text(result)).toBe('(no subagents)')
   })
 
-  it('renders children and diagnostics in array order with the fixed text forms', async () => {
+  it('renders children and diagnostics in array order with registry-derived statuses', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const started = await ctx.subagents.startContinuable({
       provider: 'spawn',
@@ -94,7 +132,8 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     })
     await waitNoActivation(ctx, started.childId)
     // Pin the render deterministically past the service: the tool is a thin
-    // adapter, so its fixed text forms are what this test pins.
+    // adapter, so its fixed text forms are what this test pins. Status comes
+    // from the live Agent registry, stubbed per candidate id.
     const entries: SubagentListEntry[] = [
       {
         kind: 'child',
@@ -120,14 +159,28 @@ describe('dsh-tool-subagent-control/list-agents', () => {
         activity: 'running',
         hasChildren: true,
       },
+      {
+        kind: 'child',
+        id: SessionId('waiting-child'),
+        label: 'waiting on descendants',
+        mode: 'continuable',
+        activity: 'running',
+        hasChildren: true,
+      },
       { kind: 'diagnostic', id: SessionId('broken-child'), reason: 'corrupt' },
     ]
     ctx.subagents.listChildren = () => Promise.resolve(entries)
+    const agents = new Map<string, { status: 'running' | 'idle' }>([
+      ['running-child', { status: 'running' }],
+      ['waiting-child', { status: 'idle' }],
+    ])
+    vi.spyOn(ctx.agents, 'get').mockImplementation(id => agents.get(id) as never)
     const result = await callTool(ctx, 'list_agents', {}, parent)
     expect(result.isError).toBe(false)
     expect(text(result)).toBe(
       `${started.childId} [complete] — real child\n`
       + 'running-child [running] — still working\n'
+      + 'waiting-child [idle] — waiting on descendants\n'
       + 'broken-child [diagnostic: corrupt]',
     )
   })
@@ -186,7 +239,101 @@ describe('dsh-tool-subagent-control/list-agents', () => {
   it('has the namespace-plugin export shape', () => {
     expect('default' in tool).toBe(false)
     expect(tool.name).toBe('tool-subagent-list-agents')
-    expect(tool.inject).toEqual(['tools', 'subagents'])
+    expect(tool.inject).toEqual(['tools', 'subagents', 'agents'])
     expect(typeof tool.apply).toBe('function')
   })
+
+  it('walks the complete descendant tree in pre-order with parent and depth annotations', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'waiting branch',
+      request: { prompt: [{ type: 'text', text: 'branch work' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'nested leaf',
+      request: { prompt: [{ type: 'text', text: 'leaf work' }], parent: child },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    // The branch finishes its own turn but stays resident waiting on the
+    // grandchild it owns: the live-registry `idle` status.
+    releaseChild.resolve(undefined)
+    await vi.waitFor(() => {
+      expect(ctx.agents.get(started.childId)?.status).toBe('idle')
+    }, { timeout: 5_000 })
+
+    const result = await callTool(ctx, 'list_agents', { scope: 'descendants' }, parent)
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe(
+      `${started.childId} [idle] parent=${parent.id} depth=1 — waiting branch\n`
+      + `${grandchild.childId} [running] parent=${started.childId} depth=2 — nested leaf`,
+    )
+
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('omits one-shot intermediates from descendants output while surfacing what they own', async () => {
+    const { ctx, parent } = await setup([])
+    // Deterministic service rows: a one-shot intermediate owning a continuable
+    // leaf, plus a positioned diagnostic. The tool filters only the one-shot.
+    ctx.subagents.listDescendants = () => Promise.resolve([
+      {
+        kind: 'child',
+        id: SessionId('one-shot-mid'),
+        label: 'one-shot intermediate',
+        mode: 'one-shot',
+        activity: 'inactive',
+        hasChildren: true,
+        parentId: parent.id,
+        depth: 1,
+      },
+      {
+        kind: 'child',
+        id: SessionId('deep-leaf'),
+        label: 'deep leaf',
+        mode: 'continuable',
+        activity: 'inactive',
+        hasChildren: false,
+        parentId: SessionId('one-shot-mid'),
+        depth: 2,
+      },
+      {
+        kind: 'diagnostic',
+        id: SessionId('broken-node'),
+        reason: 'unavailable',
+        parentId: parent.id,
+        depth: 1,
+      },
+    ])
+    const result = await callTool(ctx, 'list_agents', { scope: 'descendants' }, parent)
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe(
+      'deep-leaf [complete] parent=one-shot-mid depth=2 — deep leaf\n'
+      + `broken-node [diagnostic: unavailable] parent=${parent.id} depth=1`,
+    )
+  })
+
+  it('forwards the tool cancellation signal to descendant enumeration', async () => {
+    const { ctx, parent } = await setup([])
+    const signal = new AbortController().signal
+    const listDescendants = vi.spyOn(ctx.subagents, 'listDescendants').mockResolvedValue([])
+
+    const result = await callTool(ctx, 'list_agents', { scope: 'descendants' }, parent, signal)
+
+    expect(result.isError).toBe(false)
+    expect(listDescendants).toHaveBeenCalledWith(parent.id, signal)
+  })
 })
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index db674b0599..9b5f98dd7e 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -11,9 +11,37 @@ import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import * as tool from '../src/index.ts'
 
+/** One scripted response that may wait on a caller-released gate before streaming. */
+interface GatedEntry {
+  chunks: StreamChunk[]
+  gate?: Promise<undefined>
+}
+
+/** Adapter whose entries can hold a model call open until the test releases it. */
+class GatedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+
+  constructor(private script: GatedEntry[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.script.shift()
+    if (!entry) throw new Error('GatedAdapter: script exhausted')
+    if (entry.gate) await entry.gate
+    for (const chunk of entry.chunks) {
+      if (options.signal?.aborted) throw new Error('aborted')
+      yield chunk
+    }
+  }
+}
+
 const testToolSignal = new AbortController().signal
 
 const roots: string[] = []
@@ -21,7 +49,7 @@ afterEach(() => {
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
-async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+async function setupWith(adapter: MockAdapter | GatedAdapter) {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   const root = mkdtempSync(join(tmpdir(), 'dsh-tool-subagent-control-'))
@@ -32,12 +60,15 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(tool)
-  const adapter = new MockAdapter(script)
   ctx.llm.registerAdapter(['mock'], adapter)
   const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, adapter }
 }
 
+async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+  return setupWith(new MockAdapter(script))
+}
+
 function text(result: { content: { type: string; text?: string }[] }): string {
   return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
 }
@@ -177,8 +208,10 @@ describe('dsh-tool-subagent-control', () => {
     await ctx.plugin(SubagentService)
     const fiber = await ctx.plugin(tool)
     expect(ctx.tools.schemas().some(schema => schema.name === 'send_message')).toBe(true)
+    expect(ctx.tools.schemas().some(schema => schema.name === 'interrupt_agent')).toBe(true)
     await fiber.dispose()
     expect(ctx.tools.schemas().some(schema => schema.name === 'send_message')).toBe(false)
+    expect(ctx.tools.schemas().some(schema => schema.name === 'interrupt_agent')).toBe(false)
   })
 
   it('has the namespace-plugin export shape (no stray default)', () => {
@@ -188,3 +221,168 @@ describe('dsh-tool-subagent-control', () => {
     expect(typeof tool.apply).toBe('function')
   })
 })
+
+describe('dsh-tool-subagent-control interrupt_agent', () => {
+  it('registers interrupt_agent with the single agent_id parameter and current-turn wording', async () => {
+    const { ctx } = await setup([])
+    const schemas = ctx.tools.schemas().filter(schema => schema.name === 'interrupt_agent')
+    expect(schemas).toHaveLength(1)
+    const props = (schemas[0]!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
+    expect(Object.keys(props)).toEqual(['agent_id'])
+    expect(schemas[0]!.description).toContain('current turn')
+    expect(schemas[0]!.description).toContain('send_message')
+  })
+
+  it('interrupts a running direct child with the parent cause, parking its queue', async () => {
+    const releaseFirst = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('held'), gate: releaseFirst.promise },
+      { chunks: textResponse('parked answer') },
+      { chunks: textResponse('waking answer') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'long work',
+      request: { prompt: [{ type: 'text', text: 'long work' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const queued = await callTool(ctx, 'send_message', {
+      subagent_id: started.childId,
+      message: 'parked follow-up',
+    }, parent)
+    expect(queued.isError).toBe(false)
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    const result = await callTool(ctx, 'interrupt_agent', { agent_id: started.childId }, parent)
+
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe(`interrupt requested for agent ${started.childId}`)
+    expect(cancelSpy).toHaveBeenCalledExactlyOnceWith({ kind: 'parent' }, { keepInbox: true })
+    releaseFirst.resolve(undefined)
+    await child.whenIdle()
+    // Parked, not resumed: the queued follow-up waits for a waking send.
+    expect(adapter.requests).toHaveLength(1)
+    expect(child.inbox.nextTurn).toHaveLength(1)
+
+    const waking = await callTool(ctx, 'send_message', {
+      subagent_id: started.childId,
+      message: 'wake up',
+    }, parent)
+    expect(waking.isError).toBe(false)
+    await waitNoActivation(ctx, started.childId)
+    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const prompts = loaded.events.flatMap(event => event.type === 'user/message'
+      ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
+      : [])
+    expect(prompts).toEqual(['long work', 'parked follow-up', 'wake up'])
+  })
+
+  it('lets a deep live ancestor interrupt a descendant it did not directly create', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'child',
+      request: { prompt: [{ type: 'text', text: 'child work' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'grandchild',
+      request: { prompt: [{ type: 'text', text: 'grandchild work' }], parent: child },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    const cancelSpy = vi.spyOn(grandchildAgent, 'cancel')
+
+    const result = await callTool(ctx, 'interrupt_agent', { agent_id: grandchild.childId }, parent)
+
+    expect(result.isError).toBe(false)
+    expect(cancelSpy).toHaveBeenCalledExactlyOnceWith({ kind: 'parent' }, { keepInbox: true })
+    releaseChild.resolve(undefined)
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('rejects self, sibling, and unrelated callers without touching the target', async () => {
+    const releaseA = Promise.withResolvers<undefined>()
+    const releaseB = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('a'), gate: releaseA.promise },
+      { chunks: textResponse('b'), gate: releaseB.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const target = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'target',
+      request: { prompt: [{ type: 'text', text: 'a' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const sibling = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'sibling',
+      request: { prompt: [{ type: 'text', text: 'b' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const targetAgent = ctx.agents.get(target.childId)!
+    const siblingAgent = ctx.agents.get(sibling.childId)!
+    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const cancelSpy = vi.spyOn(targetAgent, 'cancel')
+
+    const self = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, targetAgent)
+    expect(self.isError).toBe(true)
+    expect(text(self)).toContain('cannot interrupt itself')
+    const fromSibling = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, siblingAgent)
+    expect(fromSibling.isError).toBe(true)
+    expect(text(fromSibling)).toContain('not a live descendant')
+    const fromStranger = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, stranger)
+    expect(fromStranger.isError).toBe(true)
+    expect(text(fromStranger)).toContain('not a live descendant')
+    expect(cancelSpy).not.toHaveBeenCalled()
+
+    releaseA.resolve(undefined)
+    releaseB.resolve(undefined)
+    await waitNoActivation(ctx, target.childId)
+    await waitNoActivation(ctx, sibling.childId)
+  })
+
+  it('accepts an absent target as a no-op without cold-resuming it', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'settled child',
+      request: { prompt: [{ type: 'text', text: 'child work' }], parent },
+      signal: testToolSignal,
+    })
+    await waitNoActivation(ctx, started.childId)
+
+    const settled = await callTool(ctx, 'interrupt_agent', { agent_id: started.childId }, parent)
+    expect(settled.isError).toBe(false)
+    expect(text(settled)).toBe(`interrupt requested for agent ${started.childId}`)
+    const unknown = await callTool(ctx, 'interrupt_agent', { agent_id: 'no-such-agent' }, parent)
+    expect(unknown.isError).toBe(false)
+    // No cold resume: the settled target never rematerialized.
+    expect(ctx.agents.get(started.childId)).toBeUndefined()
+  })
+
+  it('fails loud when invoked without a calling agent', async () => {
+    const { ctx } = await setup([])
+    const result = await callTool(ctx, 'interrupt_agent', { agent_id: 'x' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('requires a calling agent')
+  })
+})
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index c8ddb487ef..6d9665236a 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -172,6 +172,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuableStart: 'subagent.md',
   ContinuableStartSpec: 'subagent.md',
   CoordinatorMessageSource: 'subagent.md',
+  SubagentDescendantListEntry: 'subagent.md',
   SubagentFollowupOptions: 'subagent.md',
   SubagentInterruptAuthority: 'subagent.md',
   SubagentListEntry: 'subagent.md',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 74042fdf12..50419e416f 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -399,10 +399,11 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-subagent-control',
     dir: 'tool-subagent-control',
     source: {
+      interrupt_agent: 'packages/subagent/tool-subagent-control/src/index.ts',
       list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
       send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
     },
-    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionProjections (list_agents catalog rows)'],
+    requires: ['ctx.tools', 'ctx.subagents', 'ctx.agents and ctx.sessionProjections (list_agents only)'],
     writes: ['tool/call', 'tool/result', 'child session events through ctx.subagents'],
     async mount(ctx) {
       await ctx.plugin(SubagentService)
@@ -414,7 +415,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolSubagentListAgents)
     },
     note:
-      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry).',
+      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries).',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-subagent-report',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 5c2f3eb454..9c99ed4632 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1155,6 +1155,11 @@
       "symbol": "SubagentInterruptAuthority",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentDescendantListEntry",
+      "source": "packages/subagent/subagent/src/list-children.ts"
+    },
     {
       "doc": "docs/core-data-structures/subagent.md",
       "symbol": "ContinuableStart",

From 5e1ec10d5a4f5a80bbf7c8a1c84aeef044e282de Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 15:00:35 +0800
Subject: [PATCH 026/262] fix(subagent): address descendant listing review

---
 .../snapshots/advanced-toolchain/system-prompt.expected.md      | 2 +-
 .../snapshots/advanced-toolchain/tool-schemas.expected.json     | 2 +-
 .../tests/snapshots/both-mode-turn/tool-schemas.expected.json   | 2 +-
 .../tests/snapshots/code-mode-turn/system-prompt.expected.md    | 2 +-
 .../tests/snapshots/lsp-definition/tool-schemas.expected.json   | 2 +-
 .../tests/snapshots/pty-tools/tool-schemas.expected.json        | 2 +-
 .../snapshots/session-query-spill/tool-schemas.expected.json    | 2 +-
 .../snapshots/subagent-continuable/tool-schemas.1.expected.json | 2 +-
 .../snapshots/subagent-list-agents/tool-schemas.1.expected.json | 2 +-
 .../snapshots/subagent-report/tool-schemas.1.expected.json      | 2 +-
 .../tests/snapshots/text-turn/tool-schemas.expected.json        | 2 +-
 .../tests/snapshots/web-fetch/tool-schemas.expected.json        | 2 +-
 packages/subagent/tool-subagent-control/package.json            | 2 +-
 13 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index 2f33c0c6a5..b9fc8ec9d9 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -99,7 +99,7 @@ interface ToolArgsMap {
     /** The agent id of the running agent to interrupt. */
     agent_id: string;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index d1e5b75e45..70ab4e61f6 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -190,7 +190,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
index 890f3ee000..d5cbdc2ccc 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
index 5b74a88512..cb1b047e93 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
@@ -82,7 +82,7 @@ interface ToolArgsMap {
     /** The agent id of the running agent to interrupt. */
     agent_id: string;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
index e41987451b..335be3672b 100644
--- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
index 713353b91c..37d7d467be 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 09c637f077..7719bd3193 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
index 3283d98600..7dd791cf27 100644
--- a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
index 3283d98600..7dd791cf27 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
index 3283d98600..7dd791cf27 100644
--- a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
index 6cea6864cd..e0b7a41bcf 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
index f11131eb87..97c51af14b 100644
--- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/packages/subagent/tool-subagent-control/package.json b/packages/subagent/tool-subagent-control/package.json
index 8c7841ef63..2848a7d14d 100644
--- a/packages/subagent/tool-subagent-control/package.json
+++ b/packages/subagent/tool-subagent-control/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-tool-subagent-control",
-  "description": "Globally named send_message and list_agents tools over ctx.subagents continuations",
+  "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
   "version": "0.0.1",
   "private": true,
   "type": "module",

From 656dbadbadda690c4aaf501a66d398287cc92bf5 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 16:36:49 +0800
Subject: [PATCH 027/262] test(subagent): close descendant listing coverage

---
 .../subagent/subagent/src/list-children.ts    |  5 +-
 .../subagent/tests/list-children.spec.ts      | 46 +++++++++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index db3339e197..bf259212bb 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -315,8 +315,9 @@ function descendantCandidates(
     .reverse()
   const visited = new Set<SessionId>([rootSessionId])
   while (stack.length > 0) {
-    const position = stack.pop()
-    if (position === undefined) break
+    // The length guard proves one frame exists.
+    // oxlint-disable-next-line typescript/no-non-null-assertion
+    const position = stack.pop()!
     const id = position.record.header.id
     if (visited.has(id)) continue
     visited.add(id)
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index 31c8f1c6aa..af37aba5f4 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -1009,6 +1009,52 @@ describe('SubagentService.listDescendants', () => {
     ])
   })
 
+  it('returns an empty result when the root has no descendants', async () => {
+    const { ctx, parent } = await setup([])
+    await ctx.sessions.flush(parent.session)
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([])
+  })
+
+  it('omits a live creation-window candidate while continuing through its subtree', async () => {
+    const { ctx, parent } = await setup([])
+    const bareId = SessionId('live-creation-window')
+    const bare = ctx.sessions.create(bareId, {
+      meta: { createdAt: 1, parentSession: parent.id, origin: 'subagent' },
+    })
+    bare.append('turn/start', { turn: 1 })
+    const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaaf', {
+      parentSession: bareId,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('below the creation window')))
+
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([{
+      kind: 'child', id: below, label: 'below the creation window', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: bareId, depth: 2,
+    }])
+  })
+
+  it('contains a corrupt parent cycle without revisiting the requested root', async () => {
+    const { ctx } = await setup([])
+    const rootId = SessionId('cycle-root')
+    const nodeId = SessionId('cycle-node')
+    await authorChild(ctx, rootId, {
+      parentSession: nodeId,
+      createdAt: 2,
+    }, childEvents(descriptorPayload('ordinary cycle root')))
+    await authorChild(ctx, nodeId, {
+      parentSession: rootId,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('cycle child')))
+
+    await expect(ctx.subagents.listDescendants(rootId)).resolves.toEqual([{
+      kind: 'child', id: nodeId, label: 'cycle child', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: rootId, depth: 1,
+    }])
+  })
+
+
   it('walks a deeply nested ordinary-session chain without consuming the call stack', async () => {
     const { ctx, parent } = await setup([])
     const depth = 10_000

From 33c4d5a1641ecb09a4191cf1a7082024f6df263d Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 16:53:58 +0800
Subject: [PATCH 028/262] chore(docs): report the first stale catalog line

---
 scripts/gen-tool-catalog.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 50419e416f..b59aafe5f0 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -655,6 +655,16 @@ async function main(): Promise<void> {
       process.exit(0)
     }
     console.error(`gen-tool-catalog: ${OUT} is stale. Run \`pnpm run gen-tool-catalog\` and commit ${OUT}.`)
+    const committedLines = committed?.split('\n') ?? []
+    const generatedLines = content.split('\n')
+    const lineCount = Math.max(committedLines.length, generatedLines.length)
+    for (let index = 0; index < lineCount; index += 1) {
+      if (committedLines[index] === generatedLines[index]) continue
+      console.error(`gen-tool-catalog: first difference at line ${index + 1}`)
+      console.error(`  committed: ${JSON.stringify(committedLines[index])}`)
+      console.error(`  generated: ${JSON.stringify(generatedLines[index])}`)
+      break
+    }
     process.exit(1)
   }
 

From ddea7b398ebce42020924b95df46e6d6af2e78bc Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 17:04:10 +0800
Subject: [PATCH 029/262] docs: refresh tool catalog after stack merge

---
 docs/cordis-catalog/services.md               | 18 ++++-----
 docs/tool-catalog.md                          | 40 ++++++++++++++++---
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 3 files changed, 45 insertions(+), 15 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index f4eead6f8e..a9077ae139 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2155,18 +2155,18 @@ listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<Subagent
 
 /**
  * Enumerate the root's complete session-backed subagent tree in stable
- * pre-order from one lineage trace, without loading or resuming an Agent.
- * Ordinary sessions and one-shot children are traversed so continuable
- * descendants below them are discovered; each returned entry adds its
- * verified `parentId` and root-relative `depth`. Cancellation follows the
- * same contract as {@link listChildren}.
+ * pre-order from one live-preferred corpus, without loading or resuming an
+ * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+ * continuable descendants below them are discovered; each returned entry
+ * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+ * diagnostics, optional persistence, and cancellation follow the same
+ * projection-backed contract as {@link listChildren}.
  * @param rootSessionId - session whose complete descendant tree is listed.
- * @param signal - caller-owned cancellation forwarded where supported and
- *   observed around every query await.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
  * @returns children and per-candidate diagnostics with tree position, in
  *   stable pre-order.
- * @throws {@link SubagentError} when session query is unavailable or the
- *   caller cancels the scan.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
  */
 listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 42b68bb6e8..adb73f104d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -32,7 +32,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.agents`, `ctx.skills` | `tool/call`, `tool/result`, `user/message replacement catalogs via agent.inject()` | - | - |
 | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`, `session_event_search`, `session_event_trace`, `session_search`, `session_trace` | `ctx.tools`, `ctx.systemPrompt`, `ctx.sessionQuery`, `a calling Agent for workspace authority` | `tool/call`, `tool/result` | - | The five read-only tools hide provider cursors and authorize every result from the immutable calling agent session. The package is opt-in; compositions that need enforced deadlines or bounded inline output also mount the generic timeout or spill policies. |
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`. |
-| `@deepseek-ai/dsh-tool-subagent-control` | `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.sessionProjections (list_agents catalog rows)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry). |
+| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`, `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries). |
 | `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`, `a live continuable in-process child Agent` | `tool/call`, `tool/result`, `a user-role message in the direct parent session` | - | Registered per continuable in-process child rather than globally, so this schema is visible only inside such a child and survives its global `toolFilter`. The parent-facing `send_message` tool is installed independently. |
 | `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task. |
@@ -1193,14 +1193,44 @@ The registered tool name is the load-time `toolName` config (default `subagent`)
 
 ## `@deepseek-ai/dsh-tool-subagent-control`
 
-### `list_agents`
+### `interrupt_agent`
 
-List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.
+Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.
 
 ```json
 {
   "type": "object",
-  "properties": {}
+  "properties": {
+    "agent_id": {
+      "type": "string",
+      "description": "The agent id of the running agent to interrupt."
+    }
+  },
+  "required": [
+    "agent_id"
+  ]
+}
+```
+
+Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
+
+### `list_agents`
+
+List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "scope": {
+      "type": "string",
+      "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+      "enum": [
+        "children",
+        "descendants"
+      ]
+    }
+  }
 }
 ```
 
@@ -1232,7 +1262,7 @@ Send a message to a background subagent by its subagent id, continuing the same
 
 Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
 
-The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry).
+The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries).
 
 ## `@deepseek-ai/dsh-tool-subagent-report`
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index f942e6650e..bf179462ee 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -950,7 +950,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>',
-        jsDoc: '/**\n * Enumerate the root\'s complete session-backed subagent tree in stable\n * pre-order from one lineage trace, without loading or resuming an Agent.\n * Ordinary sessions and one-shot children are traversed so continuable\n * descendants below them are discovered; each returned entry adds its\n * verified `parentId` and root-relative `depth`. Cancellation follows the\n * same contract as {@link listChildren}.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded where supported and\n *   observed around every query await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} when session query is unavailable or the\n *   caller cancels the scan.\n */',
+        jsDoc: '/**\n * Enumerate the root\'s complete session-backed subagent tree in stable\n * pre-order from one live-preferred corpus, without loading or resuming an\n * Agent. Ordinary sessions and one-shot children remain traversal nodes so\n * continuable descendants below them are discovered; each returned entry\n * adds its durable `parentId` and root-relative `depth`. Identity resolution,\n * diagnostics, optional persistence, and cancellation follow the same\n * projection-backed contract as {@link listChildren}.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} under the same conditions as {@link listChildren}.\n */',
       },
       {
         signature: 'registerProvider(provider: SubagentProvider): () => void',

From 582fafee5a38ba16fe3440d7e1893c74a1ac49ef Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:25:41 +0800
Subject: [PATCH 030/262] test(snapshot): refresh subagent control schema pin

---
 .../tool-schemas.expected.json                | 31 +++++++++++++++++--
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
index 81f30ee5ec..dc07c990aa 100644
--- a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
@@ -179,11 +179,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {

From 3a05ddec7903c9562c13c350122f0dbac10a7b9b Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Sat, 8 Aug 2026 05:28:14 -0700
Subject: [PATCH 031/262] docs: compile the self-contained Task Surface model
 sketches

The doc-typecheck opt-out ratio gate now fails at 74/146 after merging
master. The model and branded-ID blocks are self-contained, so check
them as ordinary ts fences (72/146 remain opted out); re-record the
pairing sidecar.
---
 .../notes/proposed/feature/2026-08-04-task-surface.i18n.yaml  | 4 ++--
 .agents/notes/proposed/feature/2026-08-04-task-surface.md     | 4 ++--
 .agents/notes/proposed/feature/2026-08-04-task-surface.zh.md  | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
index fec93e2c36..7dc26f8fb7 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.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 .agents/notes/proposed/feature/2026-08-04-task-surface.md
-2026-08-04-task-surface.md: 0d79d7b830689a269d1aede937fba6aa647ea483
-2026-08-04-task-surface.zh.md: 7960c02dc3c112a8cd1ff626274dfac1f01f1bdb
+2026-08-04-task-surface.md: 72fc9e12f1a02f66a02d3335ad2e8d0d4c1c3dc2
+2026-08-04-task-surface.zh.md: 087c80195f75e145da93c5557afb43a421e1050d
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
index 0d79d7b830..72fc9e12f1 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
@@ -31,7 +31,7 @@ Short blocking questions remain with [`ask_user_question`](../../implemented/fea
 
 `TaskSurfaceModelV1` is JSON. It contains content blocks, input fields, and one submit label; it contains no code, callbacks, selectors, HTML, CSS, URLs to executable assets, or expression language. This type is unrelated to core Session's existing `SurfaceManager`/`SurfaceOp` message-reduction types; Task Surface is a product interaction protocol.
 
-```ts ignore-check
+```ts
 interface TaskSurfaceModelV1 {
   version: 1
   title: string
@@ -85,7 +85,7 @@ The tool definition omits `isConcurrencySafe`. Under the existing tool-registry
 
 The browser-safe domain package imports the type-only `Branded` primitive from `@deepseek-ai/dsh-brand` and owns all three Task Surface IDs. The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
 
-```ts ignore-check
+```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 type TaskSurfaceId = Branded<'TaskSurfaceId'>
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
index 7960c02dc3..087c80195f 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -31,7 +31,7 @@ Status: proposed
 
 `TaskSurfaceModelV1` 使用 JSON。它包含内容块、输入字段和一个提交标签；不包含代码、回调、选择器、HTML、CSS、可执行产物的 URL，也不包含表达式语言。该类型与核心会话中现有的 `SurfaceManager`/`SurfaceOp` 消息归约类型无关；Task Surface 是一套产品交互协议。
 
-```ts ignore-check
+```ts
 interface TaskSurfaceModelV1 {
   version: 1
   title: string
@@ -85,7 +85,7 @@ Task Surface 服务通过受 schema 校验的配置定义限制。初始默认
 
 浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
 
-```ts ignore-check
+```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 type TaskSurfaceId = Branded<'TaskSurfaceId'>

From 5f755d57179f5a8386976a95835196c2ac195f9f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:16:37 +0800
Subject: [PATCH 032/262] fix(web): keep Send beside subagent Stop

---
 ...07-27-web-subagent-conversations.i18n.yaml |  4 +-
 .../2026-07-27-web-subagent-conversations.md  |  2 +-
 ...026-07-27-web-subagent-conversations.zh.md |  2 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |  4 +-
 ...26-08-06-continuable-subagent-interrupt.md |  4 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  4 +-
 .../offline-composer.expected.md              |  1 +
 apps/web/tests/subagent-interrupt-ui.e2e.ts   | 17 ++++----
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../src/client/skeleton/InputBar.module.css   |  2 +-
 .../src/client/skeleton/InputBar.tsx          | 34 ++++++++++++----
 .../ui-conversation/tests/input-bar.spec.tsx  | 40 ++++++++++---------
 packages/client/ui-subagent/README.i18n.yaml  |  4 +-
 packages/client/ui-subagent/README.md         |  2 +-
 packages/client/ui-subagent/README.zh.md      |  2 +-
 17 files changed, 76 insertions(+), 54 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 4ec9a77d72..4453cca8eb 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: da4de7d4bcd23f61459eba3fee8108b0af1c95f9
-2026-07-27-web-subagent-conversations.zh.md: 43d9710ec2b63a09bd3db029f172746d63d91cfe
+2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
+2026-07-27-web-subagent-conversations.zh.md: 6b2d7bbec1133cdeb2d0cd31a6f9a43b068d21f5
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index da4de7d4bc..46c4949c56 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -45,7 +45,7 @@ Healthy rows reuse the standard session projections retained in the list mirror.
 
 Selecting a row records its exact address before opening the resident client `Session`. History pagination, event folding, tool render intents, titles, and live mux reconciliation reuse the ordinary conversation machinery. Breadcrumbs use catalog labels, follow parent links only through `origin: 'subagent'` rows, include the first ordinary owner, and keep ordinary forks single-level. Forking an addressed subagent creates an ordinary fork with direct source lineage and attaches it to the nearest workspace-owning ancestor. The catalog is an ARIA tree with lazy ArrowRight/ArrowLeft disclosure, linear ArrowUp/ArrowDown navigation, Home/End, Escape, and focus restoration.
 
-A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input disabled so the same primary Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter admits another FIFO turn even while the child runs, and the single primary action follows the ordinary running convention: Send while idle, Stop while running, routed through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
+A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input and Send action disabled so independent Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter and Send admit another FIFO turn even while the child runs, while independent Stop routes through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
 
 Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation seam.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 43d9710ec2..6b2d7bbec1 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -45,7 +45,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，只禁用其输入区，让同一个 primary Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 也会准入另一个 FIFO 轮次，而唯一的 primary 操作遵循普通运行约定：空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index dfdc2338ae..237d9fe4e4 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 0f663ac6a58b9c3d658aa572ca2fea18dbef6449
-2026-08-06-continuable-subagent-interrupt.zh.md: b8a5b557b73b2845e3c0b1dabdec0163f56eca48
+2026-08-06-continuable-subagent-interrupt.md: 5727d43526842b492633cc198f2a3bd01add126a
+2026-08-06-continuable-subagent-interrupt.zh.md: de1556acbc182e79e2afa8b7f587bb9fcc0d08e0
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 0f663ac6a5..5727d43526 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,10 +39,10 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
+The Web surface keeps Send and Stop as independent actions for a running continuable child: the client `Session.cancel()` routes Stop through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep their existing primary Send/Stop toggle through `session.cancel`), while Send continues to queue follow-ups. A running parent-offline continuable child keeps the default composer with input and Send disabled but Stop reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
 
 The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control` passes `exec.agent` as the `ancestor` authority and adds none of its own: the core primitive verifies live registry identity and recorded lineage, so the tool can name a direct child or a deeper descendant with the same generic `agent_id` parameter — deliberately not `subagent_id`, which would imply direct children only. Discovery rides `list_agents({ scope: 'descendants' })` over the new `SubagentService.listDescendants()` one-trace pre-order walk with verified `parentId`/`depth` per entry ([durable catalog note](2026-07-22-durable-subagent-catalog-and-list-agents.md) owns the listing contract); discovery is a hint, never authority. `send_message` keeps its exact-direct-parent authority — only interrupt is ancestor-wide.
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove queued Send, the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index b8a5b557b7..de1556acbc 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,10 +39,10 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
+在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
 
 `dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表契约由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明 Send 入队、中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
index a0baa9a44f..a977afbbea 100644
--- a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
+++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
@@ -20,3 +20,4 @@
   - img
 - 'button "Access mode, current: Workspace Write" [disabled]': Workspace Write
 - button "Stop generating"
+- button "Send message" [disabled]
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index be72f6546b..265462bdf7 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -1,7 +1,7 @@
-// Web e2e scenario: the composer's primary action interrupts a running
+// Web e2e scenario: the composer's independent Stop interrupts a running
 // continuable child. The child holds its model turn open through a replay
-// hang entry; the browser proves the single primary Send/Stop toggle, the
-// parent-offline disabled-input-with-Stop composer, the subagent.interrupt
+// hang entry; the browser proves Send and Stop coexist, the parent-offline
+// disabled-Send-with-Stop composer, the subagent.interrupt
 // (never session.cancel) transport, the parked follow-up, and the FIFO resume
 // on a waking send.
 //
@@ -155,7 +155,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt UI teardown failed')
   })
 
-  it('locks input but keeps the same primary Stop when the parent is offline', async () => {
+  it('locks Send but keeps independent Stop when the parent is offline', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
@@ -177,11 +177,12 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
       })
       await input.waitFor({ timeout: 15_000 })
       expect(await input.isDisabled()).toBe(true)
-      // Still exactly one primary action, and it is an enabled Stop.
       const stop = page.getByRole('button', { name: 'Stop generating' })
       expect(await stop.count()).toBe(1)
       expect(await stop.isEnabled()).toBe(true)
-      expect(await page.getByRole('button', { name: 'Send message' }).count()).toBe(0)
+      const send = page.getByRole('button', { name: 'Send message' })
+      expect(await send.count()).toBe(1)
+      expect(await send.isDisabled()).toBe(true)
       await compareOrRefreshGolden(
         OFFLINE_COMPOSER_EXPECTED,
         await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd),
@@ -203,11 +204,11 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await input.waitFor({ timeout: 15_000 })
     expect(await input.isDisabled()).toBe(false)
 
-    // Queue a follow-up while the turn is open; the primary stays Stop.
+    // Queue a follow-up through Send while independent Stop remains available.
     const promptResponse = page.waitForResponse(response =>
       new URL(response.url()).pathname === '/api/subagent.prompt')
     await input.fill(FOLLOWUP)
-    await input.press('Enter')
+    await page.getByRole('button', { name: 'Send message' }).click()
     expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
       .toMatchObject({ ok: true })
 
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 35cc21ba04..822a02d321 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: 3e3a6b1a09cbed77700fb656882178efd3744a80
-README.zh.md: f3f25426156b3778859ec8f64e8d947362b967ab
+README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
+README.zh.md: 90c4dc4cc169b2cbcd7e94275a692e3d062cfe98
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 3e3a6b1a09..f5cf9b72b4 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -34,7 +34,7 @@ Keyboard message submission resolves delivery from the addressed session's runni
 
 Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks.
 
-The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
+The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop controls), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
 
 The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index f3f2542615..90c4dc4cc1 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -34,7 +34,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
-输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
+输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止控件之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
 聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 6ab387c3eb..3bbba68dd8 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -10,7 +10,7 @@
 
 /* Floating capsule input (figma Input_Bottom 75:8208): card floats above the
    viewport bottom inside the centered message column; textarea on top, action
-   row below, one primary circle button bottom-right. Input width rides the
+   row below, primary action controls bottom-right. Input width rides the
    column (--dsh-composer-card-max-width = chat content + 32px, 16px per side,
    is a cap, not a fixed size — layout rule: the box shrinks with the center
    column keeping its clearance). Hero variant = the same card centered in the
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 21abce0e38..78db735f61 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -84,7 +84,7 @@ export function InputBar({
   const permissions = useProjection('permissions')
 
   // A continuable child without its live parent cannot accept human input,
-  // but its primary Stop below stays available while it runs.
+  // but its independent Stop below stays available while it runs.
   const continuable = subagent?.address.mode === 'continuable'
   const parentOffline = continuable && !subagent.parentAvailable
   // Queue cut 1: running input stays free; locked = session removed, the
@@ -354,12 +354,14 @@ export function InputBar({
     if (el !== null) toggleCommandMenu?.(selectionOf(el))
   }
 
-  // Ordinary sessions and continuable children stop through the same primary
-  // action; one-shot children stay send-and-stop-free (read-only takeover).
-  const stopping = running && (subagent === null || continuable)
-  const primaryLabel = stopping ? t('input.stop') : t('input.send')
+  // Ordinary sessions retain their primary Send/Stop toggle. A continuable
+  // child keeps Send as the primary action and exposes Stop independently so
+  // pointer users can queue follow-ups while its current turn is running.
+  const primaryStops = running && subagent === null
+  const interruptible = running && continuable
+  const primaryLabel = primaryStops ? t('input.stop') : t('input.send')
   const onPrimary = (): void => {
-    if (stopping) {
+    if (primaryStops) {
       stop?.()
       return
     }
@@ -528,16 +530,32 @@ export function InputBar({
             {renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
             {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
+            {interruptible && (
+              <Tooltip label={t('input.stop')} side="top" delayMs={500}>
+                <button
+                  type="button"
+                  className={css.primary}
+                  aria-label={t('input.stop')}
+                  disabled={stop === undefined}
+                  onMouseDown={keepFocus}
+                  onClick={stop}
+                >
+                  <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
+                    <rect x="3" y="3" width="10" height="10" rx="3" fill="currentColor" />
+                  </svg>
+                </button>
+              </Tooltip>
+            )}
             <Tooltip label={primaryLabel} side="top" delayMs={500}>
               <button
                 type="button"
                 className={css.primary}
                 aria-label={primaryLabel}
-                disabled={stopping ? stop === undefined : empty || disabled || machineBusy}
+                disabled={primaryStops ? stop === undefined : empty || disabled || machineBusy}
                 onMouseDown={keepFocus}
                 onClick={onPrimary}
               >
-                {stopping ? (
+                {primaryStops ? (
                   <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
                     <rect x="3" y="3" width="10" height="10" rx="3" fill="currentColor" />
                   </svg>
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 89f0d0a5f4..1e7c3a1ba1 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 // InputBar behavior over the machine wiring: Enter-send semantics (IME guard,
 // Shift newline, busy Enter policy, Ctrl/Meta steering, repeat suppression), running
-// semantics (input stays free; primary turns stop), the machine pending lock,
+// semantics (input stays free; continuable children keep Send beside Stop), the machine pending lock,
 // decoration backdrop, error/notice strips, and the focus-keeping mousedown.
 
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
@@ -143,12 +143,14 @@ function bench(over?: BenchOptions) {
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector('textarea')!
-  const stopping = over?.running === true
-    && (over.subagent === undefined || over.subagent.address.mode === 'continuable')
+  const primaryStops = over?.running === true && over.subagent === undefined
   const button = view.container.querySelector<HTMLButtonElement>(
-    `button[aria-label="${stopping ? '停止生成' : '发送消息'}"]`,
+    `button[aria-label="${primaryStops ? '停止生成' : '发送消息'}"]`,
   )!
-  return { view, textarea, button, props, sink, shell, wiring: shell, session, stop, slotCalls, menuLauncher }
+  const interruptButton = view.container.querySelector<HTMLButtonElement>('button[aria-label="停止生成"]')
+  return {
+    view, textarea, button, interruptButton, props, sink, shell, wiring: shell, session, stop, slotCalls, menuLauncher,
+  }
 }
 
 describe('Enter semantics', () => {
@@ -251,8 +253,8 @@ describe('running and lock semantics (queue cut 1)', () => {
     expect(ctrl.sink).toHaveBeenCalledWith('also queue', 'queue')
   })
 
-  it('running continuable subagent turns the same primary into Stop while typing stays free', () => {
-    const { button, textarea, sink, stop } = bench({
+  it('running continuable subagent keeps Send beside an independent Stop', () => {
+    const { button, interruptButton, textarea, sink, stop } = bench({
       running: true,
       draft: '后续消息',
       subagent: {
@@ -264,19 +266,17 @@ describe('running and lock semantics (queue cut 1)', () => {
         parentAvailable: true,
       },
     })
-    // One primary action only: Send switched to Stop, no side-by-side interrupt.
-    expect(button.getAttribute('aria-label')).toBe('停止生成')
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(interruptButton).not.toBeNull()
     expect(textarea.disabled).toBe(false)
     fireEvent.click(button)
-    expect(stop).toHaveBeenCalledTimes(1)
-    expect(sink).not.toHaveBeenCalled()
-    // Enter still queues the follow-up while the primary offers Stop.
-    fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(sink).toHaveBeenCalledWith('后续消息', 'queue')
+    fireEvent.click(interruptButton!)
+    expect(stop).toHaveBeenCalledTimes(1)
   })
 
-  it('parent-offline running continuable locks the input but keeps the same primary Stop usable', () => {
-    const { button, textarea, stop, view } = bench({
+  it('parent-offline running continuable locks Send but keeps independent Stop usable', () => {
+    const { button, interruptButton, textarea, stop, view } = bench({
       running: true,
       draft: '',
       subagent: {
@@ -291,14 +291,15 @@ describe('running and lock semantics (queue cut 1)', () => {
     expect(textarea.disabled).toBe(true)
     expect(textarea.placeholder).toBe('父会话已离线，无法继续发送；仍可停止当前运行')
     expect((view.getByLabelText('命令') as HTMLButtonElement).disabled).toBe(true)
-    expect(button.getAttribute('aria-label')).toBe('停止生成')
-    expect(button.disabled).toBe(false)
-    fireEvent.click(button)
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(button.disabled).toBe(true)
+    expect(interruptButton?.disabled).toBe(false)
+    fireEvent.click(interruptButton!)
     expect(stop).toHaveBeenCalledTimes(1)
   })
 
   it('running one-shot subagent never exposes Stop', () => {
-    const { button, stop } = bench({
+    const { button, interruptButton, stop } = bench({
       running: true,
       draft: '不可停止',
       subagent: {
@@ -311,6 +312,7 @@ describe('running and lock semantics (queue cut 1)', () => {
       },
     })
     expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(interruptButton).toBeNull()
     expect(stop).not.toHaveBeenCalled()
   })
 
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index d1b0852953..992fac46f8 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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/ui-subagent/README.md
-README.md: de55963bbe356e18a4e2b653be823cc5015c1bb7
-README.zh.md: ce4244db094bb8b602b854289ec000477bf45f0b
+README.md: abd94eb7a3b5e7c4d6d79f7a2ed5f95d471e64e2
+README.zh.md: 8686902819918c9637a8aa87d5135135a8dd4996
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index de55963bbe..abd94eb7a3 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -6,7 +6,7 @@ Web subagent feature owner: contributes the lazily expandable catalog tree to `c
 
 The header action reads `subagentsByParent` and session summaries through the standard `useSessions` hook. After a non-empty direct catalog arrives, its trigger counts the complete subagent-only descendant lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. The compact tree remains direct-catalog authoritative: continuable and one-shot rows display mode plus `running`/`inactive` activity and an optional log-backed title, while the trailing column stacks total durable provider usage above active-turn duration. Token totals sum the four disjoint `tokenUsage` buckets. Visual duration stays exact to the second below one day, then uses at most two adjacent units—days/hours, approximate months/days, or approximate years/months—while hover and the accessible name retain the exact day/hour/minute/second value. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. An unlabeled one-shot row falls back to its session id, while corrupt, unsupported, or unavailable rows remain readable but disabled. Each healthy row's `hasChildren` hint determines disclosure before interaction, so known leaves never show an arrow; a catalog level reserves the disclosure column only when at least one healthy row is a branch, allowing branchless levels to start at the leading status marker. Expanding a branch immediately reserves one disabled loading row per known direct descendant, then lazily replaces them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. Selecting any depth calls `SessionsService.openSubagent()` with the row's exact `{parentSessionId, childSessionId, mode}` address. Component-local state owns tree visibility, expanded branches, keyboard focus, and the running-duration clock. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree; closing returns focus to the trigger. Styling uses tokens only.
 
-A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input is disabled but whose primary Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing stays free while the child runs because every follow-up joins the child's FIFO inbox, and the single primary action follows the ordinary convention — Send while idle, Stop while running, routed through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md).
+A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input and Send action are disabled but whose independent Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing and Send stay available while the child runs because every follow-up joins the child's FIFO inbox, while an independent Stop routes through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md).
 
 Subagent-origin Session rows are omitted from the ordinary sidebar, so the parent header catalog is their navigation entry point. Ordinary forks remain in the sidebar.
 
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index ce4244db09..8686902819 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -6,7 +6,7 @@ Web subagent 功能 owner：向 `conversation.session.header.actions` 贡献可
 
 页头操作通过标准 `useSessions` 钩子读取 `subagentsByParent` 与会话摘要。非空直接目录到达后，其触发器会统计仅含 subagent 的完整后代谱系，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。紧凑树仍以直接目录为权威依据：可继续和 one-shot 行会显示 mode、`running`／`inactive` 活动状态和由日志支撑的可选 title，尾随列则在上行显示提供方的持久化 token 用量总计，在下行显示活跃轮次耗时。token 用量总计为四个互不重叠的 `tokenUsage` 桶之和。视觉耗时在不足一天时精确到秒，达到一天后则最多使用两个相邻单位——天／小时、近似月份／天或近似年份／月份——而悬停信息与无障碍名称会保留精确的天／小时／分钟／秒数值。耗时会累加已完成的 `subagentTiming` 轮次，仅在运行中 child 存在未结束轮次时每秒递增一次，并在 child 变为 inactive 后冻结；被中断的未结束轮次以其同一切面的 `active.through` 为上界，绝不使用更新的会话元数据。没有 label 的 one-shot 行会回退到其会话 id，而损坏、不受支持或不可用的行仍保持可读但禁用。每个健康行的 `hasChildren` 提示会在交互前决定是否显示展开控件，因此已知叶子节点从不显示箭头；每层目录仅在其中至少一个健康行是分支时才预留展开列，使完全不含分支的层级能从最前面的状态标记开始。展开分支时，会立即为每个已知直接后代预留一行禁用的加载行，随后再用该 child 的权威目录懒加载结果替换这些占位行。每个可见分支都会上报给运行时，使成员帧只在树正被消费的位置触发去抖动刷新。选择任意深度的条目都会使用该行的确切地址 `{parentSessionId, childSessionId, mode}` 调用 `SessionsService.openSubagent()`。组件局部状态负责树的可见性、已展开分支、键盘焦点与运行中耗时时钟。ArrowRight／ArrowLeft 展开和折叠分支；ArrowUp／ArrowDown、Home、End 与 Escape 用于导航或关闭树；关闭后焦点返回触发器。样式只使用 token。
 
-one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器，并以文案说明恢复路径；此类 child 仍在运行期间，selector 会让位给普通编辑器——其输入区被禁用，但 primary Stop 保持可用，停止后只读替代恢复。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话通过 `subagent.prompt` 路由提示词：child 运行期间输入保持自由，因为每条后续消息都会进入 child 的 FIFO inbox，而唯一的 primary 操作遵循普通约定——空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md) 规定。
+one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器，并以文案说明恢复路径；此类 child 仍在运行期间，selector 会让位给普通编辑器——其输入区与 Send 操作被禁用，但独立的 Stop 保持可用，停止后只读替代恢复。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话通过 `subagent.prompt` 路由提示词：child 运行期间输入和 Send 保持可用，因为每条后续消息都会进入 child 的 FIFO inbox，而独立的 Stop 经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md) 规定。
 
 普通侧边栏会省略带 subagent origin 的会话行，因此 parent 页头目录是它们的导航入口。普通 fork 仍保留在侧边栏中。
 

From ce16cf1b3bd943ac53c89a74d4a7602b06d217a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:25:20 +0800
Subject: [PATCH 033/262] test(web): exercise interrupt with parent offline

---
 ...6-continuable-subagent-interrupt.i18n.yaml |  4 +-
 ...26-08-06-continuable-subagent-interrupt.md |  2 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  2 +-
 apps/web/tests/subagent-interrupt-ui.e2e.ts   | 92 ++++++++++++++-----
 4 files changed, 73 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 237d9fe4e4..6a415c2516 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 5727d43526842b492633cc198f2a3bd01add126a
-2026-08-06-continuable-subagent-interrupt.zh.md: de1556acbc182e79e2afa8b7f587bb9fcc0d08e0
+2026-08-06-continuable-subagent-interrupt.md: 79397ac58d9bc1a117053f05f1a5b7971c48cfbb
+2026-08-06-continuable-subagent-interrupt.zh.md: 2b29895c21bf2290b750bdce6979dbe2d76635a7
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 5727d43526..79397ac58d 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -45,4 +45,4 @@ The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control`
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove queued Send, the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold real child turns open with replay hang entries and prove the parent-offline UI-to-RPC abort path, queued Send, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index de1556acbc..2b29895c21 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -45,4 +45,4 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明 Send 入队、中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）通过多条 replay hang 条目保持多个真实 child 轮次打开，端到端证明 parent 离线时从 UI 到 RPC 的中止路径、Send 入队、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index 265462bdf7..f289b062e3 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -19,7 +19,7 @@ import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import {
   acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
   launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
@@ -33,8 +33,11 @@ const OFFLINE_COMPOSER_EXPECTED = join(SNAPSHOT_DIR, 'offline-composer.expected.
 const MODE = webSnapshotMode()
 const LABEL = 'event-sourcing researcher'
 const INITIAL = 'Explain event sourcing in one sentence.'
+const REARM = 'Keep working until I stop you again.'
+const REARM_WAKE = 'Start that queued work now.'
 const FOLLOWUP = 'Now give the same explanation to a human reader.'
 const WAKING = 'And add one concrete example.'
+const REARMED_ANSWER = 're-armed setup answer'
 const PARKED_ANSWER = 'parked follow-up answer'
 const WAKING_ANSWER = 'waking answer'
 
@@ -47,6 +50,23 @@ async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_00
   }
 }
 
+/** Resolve on one exact child's next aborted turn end. */
+function waitForAbortedTurn(scaffold: WebScaffold, childId: SessionId): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      off()
+      reject(new Error('interrupt did not reach an aborted turn/end'))
+    }, 30_000)
+    const off = scaffold.ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => {
+      if (session.id !== childId || event.type !== 'turn/end') return
+      clearTimeout(timer)
+      off()
+      if (event.data.reason.kind === 'aborted') resolve()
+      else reject(new Error(`expected an aborted turn/end, got ${event.data.reason.kind}`))
+    })
+  })
+}
+
 /** One text-only scripted model completion (no tool calls: real tools are mounted). */
 function textCompletion(text: string): object {
   return {
@@ -66,6 +86,8 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
   let browser: Browser
   let page: Page
   let sidecarRoot: string
+  let rearmedReadyFile: string
+  let parent: Agent
   let childId: SessionId
   let tripwire: ReturnType<typeof watchConsole>
   const apiCalls: string[] = []
@@ -73,10 +95,13 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
   beforeAll(async () => {
     sidecarRoot = await mkdtemp(join(tmpdir(), 'dsh-web-subagent-interrupt-ui-'))
     const readyFile = join(sidecarRoot, 'hang-ready')
-    // The child claims this whole-script replacement: held turn 1, then the
-    // parked follow-up and waking turns.
+    rearmedReadyFile = join(sidecarRoot, 'hang-rearmed-ready')
+    // The child claims this whole-script replacement: the offline and online
+    // interrupt paths each hold one turn, then the parked and waking turns settle.
     await writeFile(join(sidecarRoot, 'replay.override.json'), JSON.stringify([
       { kind: 'hang', readyFile },
+      { kind: 'hang', readyFile: rearmedReadyFile },
+      textCompletion(REARMED_ANSWER),
       textCompletion(PARKED_ANSWER),
       textCompletion(WAKING_ANSWER),
     ]))
@@ -113,8 +138,9 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
     await connectFreshWorkspace(page, scaffold.workspaceCwd)
 
-    const parent = scaffold.ctx.agents.roots()[0]
-    if (parent === undefined) throw new Error('fresh workspace did not publish its parent Agent')
+    const root = scaffold.ctx.agents.roots()[0]
+    if (root === undefined) throw new Error('fresh workspace did not publish its parent Agent')
+    parent = root
     // The child's first model call claims the primary override and holds.
     const started = await scaffold.ctx.subagents.startContinuable({
       provider: 'spawn',
@@ -155,7 +181,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt UI teardown failed')
   })
 
-  it('locks Send but keeps independent Stop when the parent is offline', async () => {
+  it('interrupts the live child through the parent-offline composer', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
@@ -188,6 +214,37 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
         await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd),
         MODE,
       )
+
+      // Keep the continuable Activation resident after this first abort. The
+      // direct setup queue does not change the parent-offline UI contract: its
+      // input and Send remain disabled throughout the exercised browser path.
+      await scaffold.ctx.subagents.followup(
+        parent,
+        childId,
+        [{ type: 'text', text: REARM }],
+        { source: { kind: 'user' }, signal: new AbortController().signal },
+      )
+      const aborted = waitForAbortedTurn(scaffold, childId)
+      const interruptResponse = page.waitForResponse(response =>
+        new URL(response.url()).pathname === '/api/subagent.interrupt')
+      await stop.click()
+      expect(((await (await interruptResponse).json()) as {
+        result: { ok: boolean; value?: { accepted: boolean } }
+      }).result).toMatchObject({ ok: true, value: { accepted: true } })
+      expect(apiCalls.filter(path => path === '/api/session.cancel')).toEqual([])
+      await aborted
+      await expect.poll(() => scaffold.ctx.agents.get(childId)?.status, { timeout: 15_000 }).toBe('idle')
+
+      // Wake the parked setup message only after cancellation converges. A
+      // second hang keeps the parent-available case independent from this stop.
+      await scaffold.ctx.subagents.followup(
+        parent,
+        childId,
+        [{ type: 'text', text: REARM_WAKE }],
+        { source: { kind: 'user' }, signal: new AbortController().signal },
+      )
+      await waitFor(() => existsSync(rearmedReadyFile), 'the re-armed child turn to open')
+      expect(scaffold.ctx.agents.get(childId)?.status).toBe('running')
     } finally {
       await page.unroute(pattern)
     }
@@ -212,19 +269,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
       .toMatchObject({ ok: true })
 
-    const aborted = new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        off()
-        reject(new Error('interrupt did not reach an aborted turn/end'))
-      }, 30_000)
-      const off = scaffold.ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => {
-        if (session.id !== childId || event.type !== 'turn/end') return
-        clearTimeout(timer)
-        off()
-        if (event.data.reason.kind === 'aborted') resolve()
-        else reject(new Error(`expected an aborted turn/end, got ${event.data.reason.kind}`))
-      })
-    })
+    const aborted = waitForAbortedTurn(scaffold, childId)
     const stop = page.getByRole('button', { name: 'Stop generating' })
     expect(await stop.count()).toBe(1)
     const interruptResponse = page.waitForResponse(response =>
@@ -242,13 +287,14 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await expect.poll(() => scaffold.ctx.agents.get(childId)?.status, { timeout: 15_000 }).toBe('idle')
     const child = scaffold.ctx.agents.get(childId)
     expect(child).toBeDefined()
-    expect(child!.inbox.nextTurn).toHaveLength(1)
-    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    expect(child!.inbox.nextTurn).toHaveLength(2)
+    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
     await page.getByRole('button', { name: 'Send message' }).waitFor({ timeout: 15_000 })
 
     // Only the waking send resumes the parked queue, FIFO, to settlement.
     await input.fill(WAKING)
     await input.press('Enter')
+    await expect.poll(() => page.getByText(REARMED_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => page.getByText(PARKED_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => page.getByText(WAKING_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
@@ -258,11 +304,11 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
       && event.data.source.kind === 'user'
       ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
       : [])
-    expect(userTexts).toEqual([INITIAL, FOLLOWUP, WAKING])
+    expect(userTexts).toEqual([INITIAL, REARM, REARM_WAKE, FOLLOWUP, WAKING])
     const turnEndKinds = loaded.events
       .filter(event => event.type === 'turn/end')
       .map(event => event.data.reason.kind)
-    expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
+    expect(turnEndKinds).toEqual(['aborted', 'aborted', 'completed', 'completed', 'completed'])
     expect(tripwire.pageErrors).toEqual([])
   }, 120_000)
 

From 07fbc2cda8132e4b68a5a8f9ce05a0ad7d6ac645 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:30:03 +0800
Subject: [PATCH 034/262] test(subagent): execute control tools in ACP replay

---
 ...6-continuable-subagent-interrupt.i18n.yaml |  4 +-
 ...26-08-06-continuable-subagent-interrupt.md |  2 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  2 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  7 ++--
 .../snapshots/subagent-list-agents/input.json |  2 +-
 .../subagent-list-agents/session.jsonl        | 40 ++++++++++++-------
 6 files changed, 34 insertions(+), 23 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 6a415c2516..3fccf77cc4 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 79397ac58d9bc1a117053f05f1a5b7971c48cfbb
-2026-08-06-continuable-subagent-interrupt.zh.md: 2b29895c21bf2290b750bdce6979dbe2d76635a7
+2026-08-06-continuable-subagent-interrupt.md: cb97a77434b43ee71fa30deee9811f7a45c53f1a
+2026-08-06-continuable-subagent-interrupt.zh.md: ee05afd963584331def8c7d6acfa26830b7c1d0f
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 79397ac58d..cb97a77434 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -45,4 +45,4 @@ The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control`
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold real child turns open with replay hang entries and prove the parent-offline UI-to-RPC abort path, queued Send, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold real child turns open with replay hang entries and prove the parent-offline UI-to-RPC abort path, queued Send, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshot executes `list_agents({ scope: 'descendants' })` and `interrupt_agent` through the assembled application against one settled child, while recorded request headers continue to pin both schemas.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index 2b29895c21..ee05afd963 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -45,4 +45,4 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）通过多条 replay hang 条目保持多个真实 child 轮次打开，端到端证明 parent 离线时从 UI 到 RPC 的中止路径、Send 入队、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）通过多条 replay hang 条目保持多个真实 child 轮次打开，端到端证明 parent 离线时从 UI 到 RPC 的中止路径、Send 入队、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照通过组装应用，针对一个已结算的 child 执行 `list_agents({ scope: 'descendants' })` 与 `interrupt_agent`，同时已录制的请求 header 仍固定这两个 schema。
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index c09dd7d2ed..62a1a674d5 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -336,9 +336,10 @@ const SCENARIOS: Scenario[] = [
   },
   // Authored durable-catalog transcript: the snapshot-only lifecycle marker
   // fences the second parent turn behind the child's Activation end, so
-  // `list_agents` deterministically reads the persisted child as complete.
-  // The tool itself executes for real against the control service, session
-  // query, and JSONL persistence; the marker is not model-visible.
+  // `list_agents({ scope: 'descendants' })` deterministically reads the
+  // persisted child as complete, then `interrupt_agent` executes its accepted
+  // no-op against that settled id. Both tools run through the assembled control
+  // service; the marker is not model-visible.
   {
     name: 'subagent-list-agents',
     hasModelTurn: true,
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json
index ff7832f3b9..b3b1d8e170 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json
@@ -16,7 +16,7 @@
     },
     {
       "op": "prompt",
-      "text": "Call list_agents once and observe the subagent you started. Then reply with the single word DONE. Do not call any other tool."
+      "text": "Call list_agents once with scope set to descendants and observe the subagent you started. Then call interrupt_agent once with agent_id set to 33333333-3333-4333-8333-333333333333. Then reply with the single word DONE. Do not call any other tool."
     }
   ]
 }
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl
index 1a0113e440..f1deec5af9 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl
@@ -26,26 +26,36 @@
 {"type":"assistant/message","seq":24,"time":1785730454820,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"STARTED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"2ee459fa-21f9-48c6-a42e-3c38eca1e4c9"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
 {"type":"step/end","seq":25,"time":1785730454821,"data":{"turn":1,"step":2}}
 {"type":"turn/end","seq":26,"time":1785730454821,"data":{"turn":1,"reason":{"kind":"completed"}}}
-{"type":"agent/inbox/spliced","seq":27,"time":1785730454857,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call list_agents once and observe the subagent you started. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"}]}}
+{"type":"agent/inbox/spliced","seq":27,"time":1785730454857,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call list_agents once with scope set to descendants and observe the subagent you started. Then call interrupt_agent once with agent_id set to 33333333-3333-4333-8333-333333333333. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"}]}}
 {"type":"turn/start","seq":28,"time":1785821412840,"data":{"turn":2}}
 {"type":"agent/inbox/spliced","seq":29,"time":1785821412840,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":30,"time":1785730454863,"data":{"turn":2,"step":1}}
-{"type":"user/message","seq":31,"time":1785730454863,"data":{"content":[{"type":"text","text":"Call list_agents once and observe the subagent you started. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"},"surfaceOp":"append"}
+{"type":"user/message","seq":31,"time":1785730454863,"data":{"content":[{"type":"text","text":"Call list_agents once with scope set to descendants and observe the subagent you started. Then call interrupt_agent once with agent_id set to 33333333-3333-4333-8333-333333333333. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"},"surfaceOp":"append"}
 {"type":"assistant/chunk","seq":32,"time":1785531795686,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":33,"time":1785536135065,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_list","name":"list_agents","argumentsDelta":"{}"}}}
-{"type":"assistant/chunk","seq":34,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{}"}}}}
+{"type":"assistant/chunk","seq":33,"time":1785536135065,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_list","name":"list_agents","argumentsDelta":"{\"scope\":\"descendants\"}"}}}
+{"type":"assistant/chunk","seq":34,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{\"scope\":\"descendants\"}"}}}}
 {"type":"assistant/chunk","seq":35,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
 {"type":"assistant/chunk","seq":36,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":37,"time":1785730454867,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"199c7794-d782-4957-b7ed-69d094b9c0ef"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[32,33,34,35,36],"surfaceOp":"append"}
-{"type":"tool/call","seq":38,"time":1785730454867,"data":{"turn":2,"step":1,"callId":"call_list","name":"list_agents","arguments":"{}"}}
-{"type":"tool/result","seq":39,"time":1785730454893,"data":{"turn":2,"step":1,"message":{"source":{"kind":"tool","callId":"call_list"},"content":[{"type":"tool-result","toolCallId":"call_list","content":[{"type":"text","text":"33333333-3333-4333-8333-333333333333 [complete] — Reply with CHILD_OK"}],"isError":false}],"role":"user","id":"61ceb650-3e32-413e-9d7e-b6ec8a351858"}},"sourceEventSeqs":[38],"surfaceOp":"append"}
+{"type":"assistant/message","seq":37,"time":1785730454867,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{\"scope\":\"descendants\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"199c7794-d782-4957-b7ed-69d094b9c0ef"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[32,33,34,35,36],"surfaceOp":"append"}
+{"type":"tool/call","seq":38,"time":1785730454867,"data":{"turn":2,"step":1,"callId":"call_list","name":"list_agents","arguments":"{\"scope\":\"descendants\"}"}}
+{"type":"tool/result","seq":39,"time":1785730454893,"data":{"turn":2,"step":1,"message":{"source":{"kind":"tool","callId":"call_list"},"content":[{"type":"tool-result","toolCallId":"call_list","content":[{"type":"text","text":"33333333-3333-4333-8333-333333333333 [complete] parent=11111111-1111-4111-8111-111111111111 depth=1 — Reply with CHILD_OK"}],"isError":false}],"role":"user","id":"61ceb650-3e32-413e-9d7e-b6ec8a351858"}},"sourceEventSeqs":[38],"surfaceOp":"append"}
 {"type":"step/end","seq":40,"time":1785730454893,"data":{"turn":2,"step":1}}
 {"type":"step/start","seq":41,"time":1785730454903,"data":{"turn":2,"step":2}}
-{"type":"assistant/chunk","seq":42,"time":1785531795715,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":43,"time":1785536135106,"data":{"turn":2,"step":2,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
-{"type":"assistant/chunk","seq":44,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
-{"type":"assistant/chunk","seq":45,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
-{"type":"assistant/chunk","seq":46,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":47,"time":1785730454907,"data":{"turn":2,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"17c1a7c5-84f5-493e-adb5-6a65219e6ad6"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[42,43,44,45,46],"surfaceOp":"append"}
-{"type":"step/end","seq":48,"time":1785730454908,"data":{"turn":2,"step":2}}
-{"type":"turn/end","seq":49,"time":1785730454908,"data":{"turn":2,"reason":{"kind":"completed"}}}
+{"type":"assistant/chunk","seq":42,"time":1785531795715,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":43,"time":1785536135106,"data":{"turn":2,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_interrupt","name":"interrupt_agent","argumentsDelta":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}}}
+{"type":"assistant/chunk","seq":44,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_interrupt","name":"interrupt_agent","arguments":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}}}}
+{"type":"assistant/chunk","seq":45,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":46,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":47,"time":1785730454907,"data":{"turn":2,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_interrupt","name":"interrupt_agent","arguments":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"17c1a7c5-84f5-493e-adb5-6a65219e6ad6"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[42,43,44,45,46],"surfaceOp":"append"}
+{"type":"tool/call","seq":48,"time":1785730454907,"data":{"turn":2,"step":2,"callId":"call_interrupt","name":"interrupt_agent","arguments":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}}
+{"type":"tool/result","seq":49,"time":1785730454917,"data":{"turn":2,"step":2,"message":{"source":{"kind":"tool","callId":"call_interrupt"},"content":[{"type":"tool-result","toolCallId":"call_interrupt","content":[{"type":"text","text":"interrupt requested for agent 33333333-3333-4333-8333-333333333333"}],"isError":false}],"role":"user","id":"bf93cbe0-1946-4aef-a4ce-431790026c6f"}},"sourceEventSeqs":[48],"surfaceOp":"append"}
+{"type":"step/end","seq":50,"time":1785730454917,"data":{"turn":2,"step":2}}
+{"type":"step/start","seq":51,"time":1785730454927,"data":{"turn":2,"step":3}}
+{"type":"assistant/chunk","seq":52,"time":1785531795715,"data":{"turn":2,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":53,"time":1785536135106,"data":{"turn":2,"step":3,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
+{"type":"assistant/chunk","seq":54,"time":1785730454907,"data":{"turn":2,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":55,"time":1785730454907,"data":{"turn":2,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
+{"type":"assistant/chunk","seq":56,"time":1785730454907,"data":{"turn":2,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":57,"time":1785730454907,"data":{"turn":2,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e4c04cd6-9c23-4c99-a5f7-bac6fc141e95"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[52,53,54,55,56],"surfaceOp":"append"}
+{"type":"step/end","seq":58,"time":1785730454938,"data":{"turn":2,"step":3}}
+{"type":"turn/end","seq":59,"time":1785730454938,"data":{"turn":2,"reason":{"kind":"completed"}}}

From d21917f4cf44f0a6394efb76546f4aa211963599 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:53:33 +0800
Subject: [PATCH 035/262] refactor(subagent): resolve list tool inputs
 explicitly

---
 ...subagent-catalog-and-list-agents.i18n.yaml |  4 +-
 ...urable-subagent-catalog-and-list-agents.md |  4 +-
 ...ble-subagent-catalog-and-list-agents.zh.md |  4 +-
 .../tool-subagent-control/src/list-agents.ts  | 87 ++++++++++++-------
 .../tests/list-agents.spec.ts                 |  4 +-
 5 files changed, 65 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index c525cc8f43..e4df6863da 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.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 .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
-2026-07-22-durable-subagent-catalog-and-list-agents.md: 8337a926238bf7fc4395896fcd4ca180c9c1ac1c
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: bcf2895a9a69c8cff949788c78158bfccd198c5c
+2026-07-22-durable-subagent-catalog-and-list-agents.md: 61bda2a52f2ea5db0a582fe668643a13b967f091
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a2bc36200d8c67b8da9dd3d55ea4179baa72e691
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
index 8337a92623..61bda2a52f 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
@@ -52,9 +52,9 @@ If measured scale later requires an index, that index is derived state: session
 
 A valid descriptor produces one child entry, a per-child inspection failure produces one diagnostic entry, and a candidate without a descriptor produces no entry. `mode` is durable creation policy; `activity` is a process-local corpus snapshot. Activity is neither `AgentStatus`, the manager's internal Activation state, nor a durable outcome, and the result does not expose the internal `createdAt` sorting key. Exact Activation states and durable outcomes such as successful completion, failure, cancellation, and stop reason require a separate durable activation record and are outside this feature.
 
-The model-facing `list_agents` tool takes one optional `scope: 'children' | 'descendants'` argument, derives the root id from the current execution Agent, and is a thin adapter in `@deepseek-ai/dsh-tool-subagent-control`. It keeps diagnostics, drops `one-shot` child entries, derives status from the live Agent registry — `running` for an active driver, `idle` for a resident Agent between turns, and `complete` when no live Agent remains — then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in stable catalog order. The `descendants` scope reads `SubagentService.listDescendants(rootSessionId)`, which flattens the complete tree from one live-preferred corpus in stable pre-order, traverses ordinary and one-shot intermediates so deeper continuable agents are discovered, revalidates each cold candidate against its enumerated lifecycle, and adds `parentId`/`depth` to every entry. The tool inserts ` parent=<id> depth=<n>` before the label; `parent` is the durable direct-parent session id and may name an omitted ordinary session. For the current caller, only depth-1 child rows are `send_message` candidates, while deeper child rows may be selected for `interrupt_agent` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Discovery is a hint only — follow-up authority stays exact-direct-parent, and interrupt authority stays with the service's live-lineage check. An empty projection renders `(no subagents)`.
+The model-facing `list_agents` tool takes one optional `scope: 'children' | 'descendants'` argument, derives the root id from the current execution Agent, and resolves the request through an explicit request-to-spec step (`undefined` → `children`) before either execution or rendering. The resolved `children` scope calls `SubagentService.listChildren(rootSessionId)`, while `descendants` calls `SubagentService.listDescendants(rootSessionId)`. Its internal output projection keeps `id` and `parent` as branded `SessionId` values until the tool JSON boundary. It keeps diagnostics, drops `one-shot` child entries, derives status from the live Agent registry — `running` for an active driver, `idle` for a resident Agent between turns, and `complete` when no live Agent remains — then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in stable catalog order. The `descendants` scope flattens the complete tree from one live-preferred corpus in stable pre-order, traverses ordinary and one-shot intermediates so deeper continuable agents are discovered, revalidates each cold candidate against its enumerated lifecycle, and adds `parentId`/`depth` to every entry. The tool inserts ` parent=<id> depth=<n>` before the label; `parent` is the durable direct-parent session id and may name an omitted ordinary session. For the current caller, only depth-1 child rows are `send_message` candidates, while deeper child rows may be selected for `interrupt_agent` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Discovery is a hint only — follow-up authority stays exact-direct-parent, and interrupt authority stays with the service's live-lineage check. An empty projection renders `(no subagents)`.
 
-Diagnostics use three fixed reasons. Malformed event surfaces, conflicting headers discovered during an exact child load, a read result whose immutable header differs from the traced candidate or no longer names the requested direct parent, a target that is no longer the located descriptor event, malformed descriptor content, and multiple descriptor events map to `corrupt`. An unknown descriptor version maps to `unsupported`. `SESSION_QUERY_SESSION_NOT_FOUND`, `SESSION_QUERY_EVENT_NOT_FOUND`, and `SESSION_QUERY_PERSISTENCE_FAILED` from a per-child read map to `unavailable`. This phase boundary is intentional: a persistence outage during the initial trace fails the operation, while the same outage beginning during candidate reads may produce one identical `unavailable` diagnostic per affected child; the first version neither coalesces those diagnostics nor promotes them to a global failure. A missing descriptor is instead a non-subagent exclusion without a diagnostic. Configuration/window errors and unrecognized failures are not child diagnostics and propagate as operation failures. Each diagnostic identifies the child id and reason without exposing model-hidden descriptor content; the candidate is omitted while healthy siblings remain visible. Sessions outside the trace's direct descendants are never read and produce no diagnostic.
+In the superseded trace-based path, diagnostics used three fixed reasons. Malformed event surfaces, conflicting headers discovered during an exact child load, a read result whose immutable header differs from the traced candidate or no longer names the requested direct parent, a target that is no longer the located descriptor event, malformed descriptor content, and multiple descriptor events mapped to `corrupt`. An unknown descriptor version mapped to `unsupported`. `SESSION_QUERY_SESSION_NOT_FOUND`, `SESSION_QUERY_EVENT_NOT_FOUND`, and `SESSION_QUERY_PERSISTENCE_FAILED` from a per-child read mapped to `unavailable`. This phase boundary was intentional: a persistence outage during the initial trace failed the operation, while the same outage beginning during candidate reads could produce one identical `unavailable` diagnostic per affected child; the first version neither coalesced those diagnostics nor promoted them to a global failure. A missing descriptor was instead a non-subagent exclusion without a diagnostic. Configuration/window errors and unrecognized failures were not child diagnostics and propagated as operation failures. Each diagnostic identified the child id and reason without exposing model-hidden descriptor content; the candidate was omitted while healthy siblings remained visible. Sessions outside the trace's direct descendants were never read and produced no diagnostic.
 
 Diagnostics are transient query results, not session events or catalog state. Deriving a diagnostic performs no additional load beyond the `listEvents()` or conditional `readEvent()` operation whose result produced it.
 
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index bcf2895a9a..a2bc36200d 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -52,9 +52,9 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并作为 `@deepseek-ai/dsh-tool-subagent-control` 中的轻量适配器。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 读取 `SubagentService.listDescendants(rootSessionId)`：它从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
-diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
+在已被取代的追踪读路径中，diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
 diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导 diagnostic 时，除了产生该结果的 `listEvents()` 或条件性 `readEvent()` 操作外，不会执行额外加载。
 
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index c39ebbc648..d47232b3cc 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -11,28 +11,44 @@ import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
+import { assertNever } from '@deepseek-ai/dsh-llm'
 import type { SubagentDescendantListEntry, SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 
 export const name = 'tool-subagent-list-agents'
 export const inject = ['tools', 'subagents', 'agents']
 
+type ListAgentsScope = 'children' | 'descendants'
+
+interface ListAgentsRequest {
+  readonly scope?: ListAgentsScope
+}
+
+interface ListAgentsSpec {
+  readonly scope: ListAgentsScope
+}
+
 type ListAgentsEntry =
   | {
     readonly kind: 'child'
-    readonly id: string
+    readonly id: SessionId
     readonly label: string
     readonly status: 'running' | 'idle' | 'complete'
-    readonly parent?: string
+    readonly parent?: SessionId
     readonly depth?: number
   }
   | {
     readonly kind: 'diagnostic'
-    readonly id: string
+    readonly id: SessionId
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
-    readonly parent?: string
+    readonly parent?: SessionId
     readonly depth?: number
   }
 
+/** Resolve the optional model request into an internal required-scope spec. */
+function resolveListAgentsRequest(request: ListAgentsRequest): ListAgentsSpec {
+  return { scope: request.scope ?? 'children' }
+}
+
 /**
  * Refine one candidate's status through the live Agent registry: `running`
  * for an active driver, `idle` for a resident Agent between turns (possibly
@@ -50,7 +66,7 @@ function project(
   entry: SubagentListEntry,
   position?: Pick<SubagentDescendantListEntry, 'parentId' | 'depth'>,
 ): ListAgentsEntry | undefined {
-  const at = position === undefined ? {} : { parent: position.parentId as string, depth: position.depth }
+  const at = position === undefined ? {} : { parent: position.parentId, depth: position.depth }
   if (entry.kind === 'diagnostic') {
     return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
   }
@@ -121,22 +137,25 @@ export function apply(ctx: Context): void {
           ],
         },
       },
-      render: (args, entries) => [{
-        type: 'text',
-        text: entries.length === 0
-          ? '(no subagents)'
-          : entries.map((entry) => {
-            // A descendants row always carries its position; children rows
-            // never render it. String() spans the schema-optional shape
-            // without a dead fallback branch.
-            const at = args.scope === 'descendants'
-              ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
-              : ''
-            return entry.kind === 'child'
-              ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
-              : `${entry.id} [diagnostic: ${entry.reason}]${at}`
-          }).join('\n'),
-      }],
+      render: (args, entries) => {
+        const request = resolveListAgentsRequest(args)
+        return [{
+          type: 'text',
+          text: entries.length === 0
+            ? '(no subagents)'
+            : entries.map((entry) => {
+              // A descendants row always carries its position; children rows
+              // never render it. String() spans the schema-optional shape
+              // without a dead fallback branch.
+              const at = request.scope === 'descendants'
+                ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
+                : ''
+              return entry.kind === 'child'
+                ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
+                : `${entry.id} [diagnostic: ${entry.reason}]${at}`
+            }).join('\n'),
+        }]
+      },
     },
     async execute(args, exec) {
       const parent = exec.agent
@@ -144,18 +163,26 @@ export function apply(ctx: Context): void {
         // Non-agent callers have no session whose children could be listed.
         throw new Error('list_agents requires a calling agent (exec.agent was undefined)')
       }
+      const request = resolveListAgentsRequest(args)
       // The registry drains started tool bodies, so the scan must observe the
       // call's signal rather than finish a slow catalog after cancellation.
-      if (args.scope === 'descendants') {
-        const entries = await ctx.subagents.listDescendants(parent.id, exec.signal)
-        return entries
-          .map(entry => project(ctx.agents, entry, entry))
-          .filter(entry => entry !== undefined)
+      switch (request.scope) {
+        case 'children': {
+          const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
+          return entries
+            .map(entry => project(ctx.agents, entry))
+            .filter(entry => entry !== undefined)
+        }
+        case 'descendants': {
+          const entries = await ctx.subagents.listDescendants(parent.id, exec.signal)
+          return entries
+            .map(entry => project(ctx.agents, entry, entry))
+            .filter(entry => entry !== undefined)
+        }
+        /* v8 ignore next 2 -- the resolver normalizes the schema-validated closed scope before dispatch. */
+        default:
+          return assertNever(request.scope, 'list_agents scope')
       }
-      const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
-      return entries
-        .map(entry => project(ctx.agents, entry))
-        .filter(entry => entry !== undefined)
     },
   }))
 }
diff --git a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
index 3131809d37..0361471031 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -185,7 +185,7 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     )
   })
 
-  it('forwards the tool cancellation signal to child enumeration', async () => {
+  it('resolves omitted scope to children and forwards the tool cancellation signal', async () => {
     const { ctx, parent } = await setup([])
     const signal = new AbortController().signal
     const listChildren = vi.spyOn(ctx.subagents, 'listChildren').mockResolvedValue([])
@@ -326,7 +326,7 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     )
   })
 
-  it('forwards the tool cancellation signal to descendant enumeration', async () => {
+  it('preserves explicit descendants scope and forwards the tool cancellation signal', async () => {
     const { ctx, parent } = await setup([])
     const signal = new AbortController().signal
     const listDescendants = vi.spyOn(ctx.subagents, 'listDescendants').mockResolvedValue([])

From 542c029c804a71ba45e52158ec645c5eb7898a0d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:11:19 +0800
Subject: [PATCH 036/262] feat(i18n): compose pairing records during merges

---
 .gitattributes                            |   4 +
 lefthook.yml                              |  10 +
 package.json                              |   1 +
 scripts/install-lefthook.mjs              | 104 ++++++++-
 scripts/install-lefthook.spec.ts          |  64 +++++-
 scripts/merge-translation-pairing.ts      |  42 ++++
 scripts/translation-pairing-git.ts        |  33 +++
 scripts/translation-pairing-merge.spec.ts | 255 +++++++++++++++++++++
 scripts/translation-pairing-merge.ts      | 267 ++++++++++++++++++++++
 scripts/translation-pairing-record.ts     |  99 ++++++++
 scripts/translation-pairing.spec.ts       |  91 +++++++-
 scripts/translation-pairing.ts            |  20 +-
 scripts/verify-translation-pairing.ts     | 136 ++++++-----
 13 files changed, 1049 insertions(+), 77 deletions(-)
 create mode 100644 scripts/merge-translation-pairing.ts
 create mode 100644 scripts/translation-pairing-merge.spec.ts
 create mode 100644 scripts/translation-pairing-merge.ts
 create mode 100644 scripts/translation-pairing-record.ts

diff --git a/.gitattributes b/.gitattributes
index 2efafac8b8..e0a432111d 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -7,3 +7,7 @@
 * text=auto eol=lf
 
 *.pdf binary
+
+# Pairing records are generated from the three confirmed owner-blob pairs.
+# The worktree-local installer registers the fail-closed driver command.
+*.i18n.yaml merge=dsh-translation-pairing
diff --git a/lefthook.yml b/lefthook.yml
index c2249adbde..0e78d16252 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -4,6 +4,10 @@
 
 pre-commit:
   jobs:
+    - name: translation pairing (staged records)
+      glob: '*.i18n.yaml'
+      run: node_modules/.bin/tsx scripts/verify-translation-pairing.ts --cached {staged_files}
+
     - name: format (staged)
       glob: '*.{ts,tsx,mts,cts,mjs}'
       exclude:
@@ -34,6 +38,12 @@ pre-commit:
     - name: vendor manifest guard
       run: scripts/check-vendor-manifest.sh
 
+pre-merge-commit:
+  jobs:
+    - name: translation pairing (staged records)
+      glob: '*.i18n.yaml'
+      run: node_modules/.bin/tsx scripts/verify-translation-pairing.ts --cached {staged_files}
+
 pre-push:
   jobs:
     - name: typecheck
diff --git a/package.json b/package.json
index 423cbf813c..864814ffe6 100644
--- a/package.json
+++ b/package.json
@@ -79,6 +79,7 @@
     "verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
     "verify-translation-prompt": "tsx scripts/verify-translation-prompt.ts",
     "verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
+    "resolve-translation-pairing-conflicts": "tsx scripts/merge-translation-pairing.ts --resolve",
     "gen-translation-brief": "tsx scripts/gen-translation-brief.ts",
     "verify-doc-budgets": "tsx scripts/verify-doc-budgets.ts",
     "docs:dev": "pnpm --filter @deepseek-ai/website run dev",
diff --git a/scripts/install-lefthook.mjs b/scripts/install-lefthook.mjs
index 0f840de9c8..b928582a8a 100644
--- a/scripts/install-lefthook.mjs
+++ b/scripts/install-lefthook.mjs
@@ -27,6 +27,13 @@ const INSTALL_LOCK_INITIALIZATION_TIMEOUT_MS = 1_000
 const INSTALL_LOCK_POLL_MS = 50
 const ALLOW_HOOKS_PATH_OVERRIDE = 'DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE'
 const REPOSITORY_EXTENSION_PATTERN = '^extensions\\.'
+const PAIRING_MERGE_DRIVER_CONFIG = [
+  ['merge.dsh-translation-pairing.name', 'DeepSeek Harness bilingual pairing records'],
+  [
+    'merge.dsh-translation-pairing.driver',
+    'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P',
+  ],
+]
 
 function errorCode(error) {
   return typeof error === 'object' && error !== null && 'code' in error
@@ -595,6 +602,82 @@ function refuseScopedHooksPath(entry) {
   )
 }
 
+function installPairingMergeDriver(root, worktreeConfigPath) {
+  const added = []
+  try {
+    for (const [key, expected] of PAIRING_MERGE_DRIVER_CONFIG) {
+      const entries = includedFileConfigEntries(root, worktreeConfigPath, key)
+      const includedEntry = entries.find(entry => !originIsFile(entry.origin, root, worktreeConfigPath))
+      if (includedEntry !== undefined) {
+        throw new Error(
+          `refusing pairing merge-driver config from an included worktree file (${configSource(includedEntry)})`,
+        )
+      }
+      const existing = assertSingle(entries.map(entry => entry.value), `worktree ${key}`)
+      const effectiveBefore = effectiveConfigEntry(root, key)
+      if (effectiveBefore?.scope === 'command') {
+        throw new Error(
+          `refusing command-scoped ${key} (${configSource(effectiveBefore)}); `
+          + 'transient configuration cannot be replaced by the worktree installer',
+        )
+      }
+      if (existing === undefined && effectiveBefore !== undefined && effectiveBefore.value !== expected) {
+        throw new Error(
+          `refusing to mask inherited ${key} (${configSource(effectiveBefore)}); `
+          + 'remove or integrate the custom pairing merge driver explicitly',
+        )
+      }
+      if (existing !== undefined && existing !== expected) {
+        throw new Error(
+          `refusing to replace worktree ${key} value ${JSON.stringify(existing)}; `
+          + 'remove or integrate the custom pairing merge driver explicitly',
+        )
+      }
+      if (existing === undefined) {
+        git(['config', '--worktree', key, expected], root)
+        added.push(key)
+      }
+      const installed = includedFileConfigEntries(root, worktreeConfigPath, key)
+      if (
+        installed.length !== 1
+        || installed[0]?.value !== expected
+        || !originIsFile(installed[0].origin, root, worktreeConfigPath)
+      ) {
+        throw new Error(`new worktree-local ${key} did not become the direct worktree value`)
+      }
+      const effectiveAfter = effectiveConfigEntry(root, key)
+      if (
+        effectiveAfter === undefined
+        || effectiveAfter.scope !== 'worktree'
+        || effectiveAfter.value !== expected
+        || !originIsFile(effectiveAfter.origin, root, worktreeConfigPath)
+      ) {
+        throw new Error(`new worktree-local ${key} did not become the effective direct worktree value`)
+      }
+    }
+  } catch (error) {
+    const rollbackErrors = []
+    for (const key of added.reverse()) {
+      try {
+        git(['config', '--worktree', '--unset-all', key], root)
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError)
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        `Pairing merge-driver configuration failed: ${String(error)}; `
+        + `rollback also failed: ${rollbackErrors.map(String).join('; ')}`,
+      )
+    }
+    throw error
+  }
+  return () => {
+    for (const key of added.reverse()) git(['config', '--worktree', '--unset-all', key], root)
+  }
+}
+
 async function main() {
   if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') return
   if (typeof lefthookPackage.bin?.lefthook !== 'string') return
@@ -682,7 +765,9 @@ async function main() {
     applyWorktreeConfigMigration(root, commonConfigPath, migration)
 
     let pathChanged = false
+    let rollbackPairingMergeDriver = () => {}
     try {
+      rollbackPairingMergeDriver = installPairingMergeDriver(root, worktreeConfigPath)
       git(['config', '--worktree', 'core.hooksPath', hooksPath], root)
       pathChanged = worktreePath !== hooksPath
       const installedEntry = effectiveConfigEntry(root, 'core.hooksPath')
@@ -697,6 +782,7 @@ async function main() {
       runLefthook(root, lefthook)
       updateOwnershipMarker(ownedHooksDirectory.markerPath, hooksPath)
     } catch (error) {
+      const rollbackErrors = []
       if (pathChanged) {
         try {
           if (worktreePath === undefined) {
@@ -705,13 +791,21 @@ async function main() {
             git(['config', '--worktree', 'core.hooksPath', worktreePath], root)
           }
         } catch (rollbackError) {
-          throw new AggregateError(
-            [error, rollbackError],
-            `Lefthook installation failed: ${String(error)}; `
-            + `worktree hook rollback also failed: ${String(rollbackError)}`,
-          )
+          rollbackErrors.push(rollbackError)
         }
       }
+      try {
+        rollbackPairingMergeDriver()
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError)
+      }
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError(
+          [error, ...rollbackErrors],
+          `Lefthook installation failed: ${String(error)}; `
+          + `worktree integration rollback also failed: ${rollbackErrors.map(String).join('; ')}`,
+        )
+      }
       throw error
     }
   } catch (error) {
diff --git a/scripts/install-lefthook.spec.ts b/scripts/install-lefthook.spec.ts
index ca74b91404..df9f1cd6d8 100644
--- a/scripts/install-lefthook.spec.ts
+++ b/scripts/install-lefthook.spec.ts
@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 
 const installer = fileURLToPath(new URL('./install-lefthook.mjs', import.meta.url))
+const pairingMergeDriver = 'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P'
 const fixtures: string[] = []
 // Multi-worktree cases spawn several Git and Node subprocesses; coverage concurrency can
 // legitimately exceed Vitest's default deadline without changing the installer behavior.
@@ -95,7 +96,7 @@ if (!shouldFail) {
   const binary = join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'lefthook.cmd' : 'lefthook')
   const config = readFileSync(join(root, 'lefthook.yml'), 'utf8').trim()
   const hook = \`#!/bin/sh\\n# root=\${root}\\n# binary=\${binary}\\n# config=\${config}\\nexit 0\\n\`
-  for (const name of ['pre-commit', 'pre-push']) writeFileSync(join(hooksPath, name), hook, { mode: 0o755 })
+  for (const name of ['pre-commit', 'pre-merge-commit', 'pre-push']) writeFileSync(join(hooksPath, name), hook, { mode: 0o755 })
 }
 if (existsSync(running)) unlinkSync(running)
 if (process.env.DSH_TEST_LEFTHOOK_BREAK_WORKTREE_CONFIG === '1') {
@@ -222,6 +223,9 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
       expect(git(fixture, fixture.main, ['config', '--get', 'core.repositoryFormatVersion'])).toBe('0')
       expect(existsSync(hooksPath(fixture, fixture.main))).toBe(false)
       expect(existsSync(join(common, 'config.worktree'))).toBe(false)
+      expect(gitResult(fixture, fixture.main, [
+        'config', '--get', 'merge.dsh-translation-pairing.driver',
+      ]).status).toBe(1)
     })
   }
 
@@ -241,6 +245,12 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(mainHooks).not.toBe(linkedHooks)
     expect(git(fixture, fixture.main, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(mainHooks)
     expect(git(fixture, fixture.linked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(linkedHooks)
+    expect(git(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe(pairingMergeDriver)
+    expect(git(fixture, fixture.linked, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe(pairingMergeDriver)
 
     const mainHook = readFileSync(join(mainHooks, 'pre-commit'), 'utf8')
     const linkedHook = readFileSync(join(linkedHooks, 'pre-commit'), 'utf8')
@@ -252,6 +262,8 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(linkedHook).toContain(`# root=${canonicalLinked}`)
     expect(linkedHook).toContain('# config=linked-worktree-config')
     expect(linkedHook).not.toContain(canonicalMain)
+    expect(existsSync(join(mainHooks, 'pre-merge-commit'))).toBe(true)
+    expect(existsSync(join(linkedHooks, 'pre-merge-commit'))).toBe(true)
     expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy hook\n')
 
     const commonConfig = join(common, 'config')
@@ -677,9 +689,50 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(result.stderr).toContain('command-scoped core.hooksPath')
     expect(readFileSync(sentinel, 'utf8')).toBe('#!/bin/sh\n# command-scope sentinel\n')
     expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
     expect(existsSync(hooksPath(fixture, fixture.main))).toBe(false)
   })
 
+  it('never replaces a custom worktree pairing merge driver', async () => {
+    const fixture = createFixture()
+    const commonConfig = join(commonDirectory(fixture), 'config')
+    git(fixture, fixture.main, ['config', '--file', commonConfig, 'core.repositoryFormatVersion', '1'])
+    git(fixture, fixture.main, ['config', '--file', commonConfig, 'extensions.worktreeConfig', 'true'])
+    git(fixture, fixture.main, [
+      'config', '--worktree', 'merge.dsh-translation-pairing.driver', 'custom-driver %A',
+    ])
+
+    const result = await runInstaller(fixture, fixture.main)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('refusing to replace worktree merge.dsh-translation-pairing.driver')
+    expect(git(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe('custom-driver %A')
+    expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+  })
+
+  it('never masks an inherited custom pairing merge driver', async () => {
+    const fixture = createFixture()
+    git(fixture, fixture.main, [
+      'config', '--local', 'merge.dsh-translation-pairing.driver', 'inherited-driver %A',
+    ])
+
+    const result = await runInstaller(fixture, fixture.main)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('refusing to mask inherited merge.dsh-translation-pairing.driver')
+    expect(git(fixture, fixture.main, [
+      'config', '--local', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe('inherited-driver %A')
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+  })
+
   it('does not pass unrelated command-scoped Git config to Lefthook', async () => {
     const fixture = createFixture()
 
@@ -729,6 +782,12 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(result.stderr).toContain('exit status 77')
     expect(gitResult(fixture, fixture.main, ['config', '--worktree', '--get', 'core.hooksPath']).status).toBe(1)
     expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.name',
+    ]).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
     expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy pre-push\n')
   })
 
@@ -743,8 +802,9 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('Lefthook installation failed')
     expect(result.stderr).toContain('exit status 77')
-    expect(result.stderr).toContain('worktree hook rollback also failed')
+    expect(result.stderr).toContain('worktree integration rollback also failed')
     expect(result.stderr).toContain('git config --worktree --unset-all core.hooksPath failed')
+    expect(result.stderr).toContain('git config --worktree --unset-all merge.dsh-translation-pairing.driver failed')
   })
 
   it('refuses an unowned directory at the reserved worktree hook path', async () => {
diff --git a/scripts/merge-translation-pairing.ts b/scripts/merge-translation-pairing.ts
new file mode 100644
index 0000000000..8d193ab9f9
--- /dev/null
+++ b/scripts/merge-translation-pairing.ts
@@ -0,0 +1,42 @@
+/** Git merge-driver and explicit conflict-resolver entrypoint for pairing records. */
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  mergeTranslationPairingRecords,
+  resolveTranslationPairingConflicts,
+} from './translation-pairing-merge.ts'
+
+const args = process.argv.slice(2)
+
+try {
+  const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
+  if (args[0] === '--resolve') {
+    if (args.length !== 1) throw new Error('--resolve takes no paths; it inspects the unmerged index')
+    const resolved = resolveTranslationPairingConflicts(root)
+    if (resolved.length === 0) {
+      console.log('merge-translation-pairing: no unresolved pairing records')
+    } else {
+      for (const path of resolved) console.log(`merge-translation-pairing: resolved ${path}`)
+    }
+  } else {
+    if (args.length !== 4) {
+      throw new Error('merge-driver mode requires <ancestor> <current> <other> <repository-path>')
+    }
+    const [ancestorPath, currentPath, otherPath, metaPath] = args
+    if (ancestorPath === undefined || currentPath === undefined || otherPath === undefined || metaPath === undefined) {
+      throw new Error('merge-driver arguments are incomplete')
+    }
+    const result = mergeTranslationPairingRecords(
+      root,
+      metaPath,
+      readFileSync(ancestorPath, 'utf8'),
+      readFileSync(currentPath, 'utf8'),
+      readFileSync(otherPath, 'utf8'),
+    )
+    writeFileSync(currentPath, result.record)
+  }
+} catch (error) {
+  console.error(`merge-translation-pairing: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}
diff --git a/scripts/translation-pairing-git.ts b/scripts/translation-pairing-git.ts
index 992f0abbb9..b18b2d5778 100644
--- a/scripts/translation-pairing-git.ts
+++ b/scripts/translation-pairing-git.ts
@@ -27,6 +27,39 @@ function runGit(root: string, args: string[], operation: string, input?: Buffer)
   return result.stdout
 }
 
+/** One regular stage-zero Git index entry and its exact blob bytes. */
+export interface GitIndexBlob {
+  /** Object ID recorded in the index. */
+  objectId: string
+  /** Blob bytes stored under that object ID. */
+  content: Buffer
+}
+
+/**
+ * Read one path from the Git index without consulting working-tree bytes.
+ *
+ * @param root - Repository root.
+ * @param path - Repository-relative path.
+ * @returns The stage-zero blob, or `undefined` when the path is absent.
+ * @throws Error when the path is unmerged or has an invalid index shape.
+ */
+export function readGitIndexBlob(root: string, path: string): GitIndexBlob | undefined {
+  const output = runGit(
+    root,
+    ['ls-files', '--stage', '-z', '--', path],
+    `git ls-files --stage for ${path}`,
+  ).toString('utf8')
+  const entries = output.split('\0').filter(Boolean)
+  if (entries.length === 0) return undefined
+  if (entries.length !== 1) throw new Error(`${path} does not have exactly one resolved index entry`)
+  const match = /^(?:\d+) ([0-9a-f]+) 0\t[\s\S]+$/.exec(entries[0] ?? '')
+  if (!match?.[1]) throw new Error(`${path} remains unmerged or has an invalid index entry`)
+  return {
+    objectId: match[1],
+    content: runGit(root, ['cat-file', 'blob', match[1]], `reading staged ${path}`),
+  }
+}
+
 /**
  * Persist exact working-tree bytes so a pairing record can later recover them
  * with `git cat-file`, even when they have never appeared in the index or a
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
new file mode 100644
index 0000000000..c6a9a5bbb7
--- /dev/null
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -0,0 +1,255 @@
+/** Integration coverage for automatic and explicit pairing-record conflict resolution. */
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  mergeTranslationPairingRecords,
+  resolveTranslationPairingConflicts,
+} from './translation-pairing-merge.ts'
+import {
+  renderTranslationPairingRecord,
+  translationPairPaths,
+} from './translation-pairing-record.ts'
+
+const driver = fileURLToPath(new URL('./merge-translation-pairing.ts', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx/esm'))
+const fixtures: string[] = []
+
+interface Fixture {
+  env: NodeJS.ProcessEnv
+  root: string
+}
+
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) rmSync(fixture, { recursive: true, force: true })
+})
+
+function git(fixture: Fixture, args: string[]): string {
+  return execFileSync('git', ['-C', fixture.root, ...args], {
+    encoding: 'utf8',
+    env: fixture.env,
+  }).trim()
+}
+
+function write(root: string, path: string, content: string): void {
+  const absolute = join(root, path)
+  mkdirSync(dirname(absolute), { recursive: true })
+  writeFileSync(absolute, content)
+}
+
+function shellQuote(value: string): string {
+  return `"${value.replace(/["\\$`]/g, '\\$&')}"`
+}
+
+function createFixture(attributes = true): Fixture {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
+  fixtures.push(root)
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    GIT_AUTHOR_EMAIL: 'pairing@example.test',
+    GIT_AUTHOR_NAME: 'Pairing Test',
+    GIT_COMMITTER_EMAIL: 'pairing@example.test',
+    GIT_COMMITTER_NAME: 'Pairing Test',
+    GIT_CONFIG_GLOBAL: join(root, 'global.gitconfig'),
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_DEFAULT_HASH: 'sha1',
+  }
+  const fixture = { env, root }
+  execFileSync('git', ['init', '--quiet', '--initial-branch=master', root], { env })
+  if (attributes) write(root, '.gitattributes', '*.i18n.yaml merge=dsh-translation-pairing\n')
+  return fixture
+}
+
+function record(root: string, path: string, source: string, zh: string): string {
+  const paths = translationPairPaths(path)
+  write(root, paths.source, source)
+  write(root, paths.zh, zh)
+  const content = renderTranslationPairingRecord(paths, {
+    sourceHash: storeGitBlob(root, Buffer.from(source)),
+    zhHash: storeGitBlob(root, Buffer.from(zh)),
+  })
+  write(root, paths.meta, content)
+  return content
+}
+
+const baseSource = '# Guide\n\nEnglish | [中文](guide.zh.md)\n\nAlpha base.\n\nBeta base.\n'
+const baseZh = '# 指南\n\n[English](guide.md) | 中文\n\n甲基础。\n\n乙基础。\n'
+const currentSource = baseSource.replace('Alpha base.', 'Alpha current.')
+const currentZh = baseZh.replace('甲基础。', '甲当前。')
+const otherSource = baseSource.replace('Beta base.', 'Beta other.')
+const otherZh = baseZh.replace('乙基础。', '乙对侧。')
+const mergedSource = currentSource.replace('Beta base.', 'Beta other.')
+const mergedZh = currentZh.replace('乙基础。', '乙对侧。')
+
+function commitPair(fixture: Fixture, source: string, zh: string, message: string): string {
+  const sidecar = record(fixture.root, 'docs/guide.md', source, zh)
+  git(fixture, ['add', '.'])
+  git(fixture, ['commit', '-m', message])
+  return sidecar
+}
+
+function createDivergedPair(fixture: Fixture): { ancestor: string; current: string; other: string } {
+  const ancestor = commitPair(fixture, baseSource, baseZh, 'base')
+  git(fixture, ['switch', '-c', 'current'])
+  const current = commitPair(fixture, currentSource, currentZh, 'current')
+  git(fixture, ['switch', 'master'])
+  const other = commitPair(fixture, otherSource, otherZh, 'other')
+  git(fixture, ['switch', 'current'])
+  return { ancestor, current, other }
+}
+
+function expectMergedPair(fixture: Fixture): void {
+  expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(mergedSource)
+  expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(mergedZh)
+  expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe(
+    renderTranslationPairingRecord(translationPairPaths('docs/guide.md'), {
+      sourceHash: gitBlobHash(Buffer.from(mergedSource)),
+      zhHash: gitBlobHash(Buffer.from(mergedZh)),
+    }),
+  )
+}
+
+describe('translation pairing merge composition', () => {
+  it('rejects a pairing-record path outside the repository', () => {
+    const fixture = createFixture(false)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      '../guide.i18n.yaml',
+      '',
+      '',
+      '',
+    )).toThrow('pairing record escapes the repository')
+  })
+
+  it('merges the owner blobs named by three valid records', () => {
+    const fixture = createFixture(false)
+    const records = createDivergedPair(fixture)
+
+    const result = mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      records.ancestor,
+      records.current,
+      records.other,
+    )
+
+    expect(result.sourceContent.toString('utf8')).toBe(mergedSource)
+    expect(result.zhContent.toString('utf8')).toBe(mergedZh)
+    expect(result.sourceHash).toBe(gitBlobHash(Buffer.from(mergedSource)))
+    expect(result.zhHash).toBe(gitBlobHash(Buffer.from(mergedZh)))
+  })
+
+  it('leaves owner-content conflicts for a human', () => {
+    const fixture = createFixture(false)
+    const ancestor = record(fixture.root, 'docs/guide.md', baseSource, baseZh)
+    const current = record(
+      fixture.root,
+      'docs/guide.md',
+      baseSource.replace('Alpha base.', 'Alpha current.'),
+      baseZh.replace('甲基础。', '甲当前。'),
+    )
+    const other = record(
+      fixture.root,
+      'docs/guide.md',
+      baseSource.replace('Alpha base.', 'Alpha other.'),
+      baseZh.replace('甲基础。', '甲对侧。'),
+    )
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow('docs/guide.md has content conflicts')
+  })
+
+  it('rejects structurally divergent clean owner merges', () => {
+    const fixture = createFixture(false)
+    const ancestor = record(fixture.root, 'docs/guide.md', baseSource, baseZh)
+    const current = record(fixture.root, 'docs/guide.md', currentSource, currentZh)
+    const other = record(
+      fixture.root,
+      'docs/guide.md',
+      `${otherSource}\n## Extra\n`,
+      otherZh,
+    )
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow('clean merges diverge structurally')
+  })
+
+  it('refuses owners assigned to another merge strategy', () => {
+    const fixture = createFixture(false)
+    write(fixture.root, '.gitattributes', 'docs/*.md merge=custom-owner\n')
+    const records = createDivergedPair(fixture)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      records.ancestor,
+      records.current,
+      records.other,
+    )).toThrow('docs/guide.md uses merge=custom-owner')
+  })
+
+  it('runs as Git\'s custom driver and commits a clean composed record', () => {
+    const fixture = createFixture()
+    createDivergedPair(fixture)
+    const command = [
+      shellQuote(process.execPath),
+      '--import', shellQuote(tsxLoader),
+      shellQuote(driver),
+      '%O', '%A', '%B', '%P',
+    ].join(' ')
+    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
+
+    git(fixture, ['merge', '--no-edit', 'master'])
+
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('')
+    expectMergedPair(fixture)
+  })
+
+  it('resolves an already-stopped generated-only conflict from index stages', () => {
+    const fixture = createFixture(false)
+    createDivergedPair(fixture)
+    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+    expect(merge.status).toBe(1)
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+
+    expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
+
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('')
+    expectMergedPair(fixture)
+  })
+
+  it('refuses to confirm unstaged owner bytes after a stopped merge', () => {
+    const fixture = createFixture(false)
+    createDivergedPair(fixture)
+    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+    expect(merge.status).toBe(1)
+    write(fixture.root, 'docs/guide.md', `${mergedSource}\nunstaged\n`)
+
+    expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(
+      'docs/guide.md has unstaged content',
+    )
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+  })
+})
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
new file mode 100644
index 0000000000..3297e30ea2
--- /dev/null
+++ b/scripts/translation-pairing-merge.ts
@@ -0,0 +1,267 @@
+/** Fail-closed composition of bilingual pairing records during Git merges. */
+
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  linksTo,
+  isTranslationScopeFile,
+  parseTranslationMarkdown,
+  translationStructureDiff,
+  translationStructureSignature,
+} from './translation-pairing.ts'
+import {
+  parseTranslationPairingRecord,
+  renderTranslationPairingRecord,
+  translationPairPathsFromMeta,
+  type TranslationPairPaths,
+  type TranslationPairingRecord,
+} from './translation-pairing-record.ts'
+
+const MAX_GIT_OUTPUT = 1 << 26
+const UNMERGED_ENTRY = /^(\d+) ([0-9a-f]+) ([123])\t([\s\S]+)$/
+
+/** A mechanically composed record and the exact merged owner contents it names. */
+export interface TranslationPairingMergeResult extends TranslationPairingRecord {
+  /** Canonical generated sidecar text. */
+  record: string
+  /** Clean three-way merge of the English owner. */
+  sourceContent: Buffer
+  /** Clean three-way merge of the Simplified Chinese owner. */
+  zhContent: Buffer
+}
+
+interface UnmergedStages {
+  ancestor?: string
+  current?: string
+  other?: string
+}
+
+function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    input,
+    maxBuffer: MAX_GIT_OUTPUT,
+  })
+  if (result.error) throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`)
+  }
+  return result.stdout
+}
+
+function readGitBlob(root: string, objectId: string, owner: string): Buffer {
+  const content = runGit(root, ['cat-file', 'blob', objectId], `reading ${owner} blob ${objectId}`)
+  if (gitBlobHash(content) !== objectId) {
+    throw new Error(`${owner} record names ${objectId}, which is not its SHA-1 git blob hash`)
+  }
+  return content
+}
+
+function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void {
+  const output = runGit(
+    root,
+    ['check-attr', '-z', 'merge', '--', paths.source, paths.zh],
+    'checking bilingual owner merge attributes',
+  ).toString('utf8')
+  const fields = output.split('\0')
+  fields.pop()
+  for (let index = 0; index < fields.length; index += 3) {
+    const path = fields[index]
+    const value = fields[index + 2]
+    if (path === undefined || value === undefined) {
+      throw new Error('git check-attr returned a malformed result')
+    }
+    if (!['unspecified', 'set', 'text'].includes(value)) {
+      throw new Error(`${path} uses merge=${value}; the pairing driver only composes Git's default text merge`)
+    }
+  }
+}
+
+function mergeBlobTriplet(
+  root: string,
+  owner: string,
+  ancestor: Buffer,
+  current: Buffer,
+  other: Buffer,
+): Buffer {
+  const temporary = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
+  try {
+    const ancestorPath = join(temporary, 'ancestor')
+    const currentPath = join(temporary, 'current')
+    const otherPath = join(temporary, 'other')
+    writeFileSync(ancestorPath, ancestor)
+    writeFileSync(currentPath, current)
+    writeFileSync(otherPath, other)
+    const result = spawnSync('git', [
+      '-C', root,
+      'merge-file', '-p',
+      '-L', `${owner}:current`,
+      '-L', `${owner}:ancestor`,
+      '-L', `${owner}:other`,
+      currentPath, ancestorPath, otherPath,
+    ], { maxBuffer: MAX_GIT_OUTPUT })
+    if (result.error) {
+      throw new Error(`merging ${owner} failed: ${result.error.message}`, { cause: result.error })
+    }
+    if (result.status !== 0) {
+      const kind = result.status !== null && result.status > 0 && result.status <= 127
+        ? 'has content conflicts'
+        : `failed with status ${String(result.status)}`
+      throw new Error(`${owner} ${kind}`)
+    }
+    return result.stdout
+  } finally {
+    rmSync(temporary, { recursive: true, force: true })
+  }
+}
+
+function loadRecordOwners(
+  root: string,
+  label: string,
+  content: string,
+  paths: TranslationPairPaths,
+): { source: Buffer; zh: Buffer } {
+  const record = parseTranslationPairingRecord(content, paths)
+  if (record === undefined) throw new Error(`${label} ${paths.meta} is not a valid two-hash pairing record`)
+  return {
+    source: readGitBlob(root, record.sourceHash, `${label} ${paths.source}`),
+    zh: readGitBlob(root, record.zhHash, `${label} ${paths.zh}`),
+  }
+}
+
+function assertMergedPairStructure(paths: TranslationPairPaths, source: Buffer, zh: Buffer): void {
+  const sourceTree = parseTranslationMarkdown(source.toString('utf8'))
+  const zhTree = parseTranslationMarkdown(zh.toString('utf8'))
+  if (!linksTo(sourceTree, basename(paths.zh))) {
+    throw new Error(`${paths.source} clean merge lost its language-switcher link to ${basename(paths.zh)}`)
+  }
+  if (!linksTo(zhTree, basename(paths.source))) {
+    throw new Error(`${paths.zh} clean merge lost its language-switcher link to ${basename(paths.source)}`)
+  }
+  const divergences = translationStructureDiff(
+    translationStructureSignature(sourceTree, basename(paths.zh)),
+    translationStructureSignature(zhTree, basename(paths.source)),
+  )
+  if (divergences.length > 0) {
+    throw new Error(`${paths.source} and ${paths.zh} clean merges diverge structurally: ${divergences.join('; ')}`)
+  }
+}
+
+function normalizeMetaPath(root: string, meta: string): string {
+  if (isAbsolute(meta)) throw new Error(`pairing record must be repository-relative: ${JSON.stringify(meta)}`)
+  const repositoryRelative = relative(resolve(root), resolve(root, meta))
+  if (repositoryRelative === '' || repositoryRelative === '..' || repositoryRelative.startsWith(`..${sep}`)) {
+    throw new Error(`pairing record escapes the repository: ${JSON.stringify(meta)}`)
+  }
+  return repositoryRelative.split(sep).join('/')
+}
+
+/**
+ * Compose one generated sidecar from the ancestor, current, and other records.
+ *
+ * Each input record is already a confirmation of its two owner blobs. The
+ * result exists only when Git's default text merge succeeds independently for
+ * both languages and the composed documents retain the pairing structure.
+ *
+ * @param root - Repository root containing the referenced Git objects.
+ * @param metaPath - Repository-relative sidecar path.
+ * @param ancestorRecord - Common-ancestor sidecar text.
+ * @param currentRecord - Current-side sidecar text.
+ * @param otherRecord - Other-side sidecar text.
+ * @returns The canonical record and exact merged owner contents.
+ * @throws Error when the input is not mechanically composable.
+ */
+export function mergeTranslationPairingRecords(
+  root: string,
+  metaPath: string,
+  ancestorRecord: string,
+  currentRecord: string,
+  otherRecord: string,
+): TranslationPairingMergeResult {
+  const normalizedMeta = normalizeMetaPath(root, metaPath)
+  if (!isTranslationScopeFile(normalizedMeta)) {
+    throw new Error(`${normalizedMeta} is outside the active bilingual documentation corpus`)
+  }
+  const paths = translationPairPathsFromMeta(normalizedMeta)
+  assertDefaultTextMerge(root, paths)
+  const ancestor = loadRecordOwners(root, 'ancestor', ancestorRecord, paths)
+  const current = loadRecordOwners(root, 'current', currentRecord, paths)
+  const other = loadRecordOwners(root, 'other', otherRecord, paths)
+  const sourceContent = mergeBlobTriplet(root, paths.source, ancestor.source, current.source, other.source)
+  const zhContent = mergeBlobTriplet(root, paths.zh, ancestor.zh, current.zh, other.zh)
+  assertMergedPairStructure(paths, sourceContent, zhContent)
+  const sourceHash = storeGitBlob(root, sourceContent)
+  const zhHash = storeGitBlob(root, zhContent)
+  return {
+    record: renderTranslationPairingRecord(paths, { sourceHash, zhHash }),
+    sourceContent,
+    sourceHash,
+    zhContent,
+    zhHash,
+  }
+}
+
+function unmergedSidecars(root: string): Map<string, UnmergedStages> {
+  const output = runGit(root, ['ls-files', '--unmerged', '-z'], 'listing unresolved merge entries').toString('utf8')
+  const records = new Map<string, UnmergedStages>()
+  for (const entry of output.split('\0')) {
+    if (entry === '') continue
+    const match = UNMERGED_ENTRY.exec(entry)
+    if (!match?.[2] || !match[3] || match[4] === undefined) {
+      throw new Error(`git ls-files returned a malformed unmerged entry: ${JSON.stringify(entry)}`)
+    }
+    const path = match[4]
+    if (!path.endsWith('.i18n.yaml')) continue
+    const stages = records.get(path) ?? {}
+    const field = match[3] === '1' ? 'ancestor' : match[3] === '2' ? 'current' : 'other'
+    stages[field] = match[2]
+    records.set(path, stages)
+  }
+  return records
+}
+
+/**
+ * Resolve every mechanically composable `.i18n.yaml` conflict in the index.
+ *
+ * The command first proves that Git's already-staged owner merges match the
+ * independently composed contents, then writes and stages all sidecars as one
+ * batch. Other conflicts remain untouched.
+ *
+ * @param root - Repository root with an in-progress merge-like operation.
+ * @returns Repository-relative sidecar paths resolved and staged.
+ */
+export function resolveTranslationPairingConflicts(root: string): string[] {
+  const resolutions: { path: string; record: string }[] = []
+  for (const [metaPath, stages] of [...unmergedSidecars(root)].sort(([left], [right]) => left.localeCompare(right))) {
+    if (stages.ancestor === undefined || stages.current === undefined || stages.other === undefined) {
+      throw new Error(`${metaPath} is an add/delete or incomplete-stage conflict and requires manual resolution`)
+    }
+    const result = mergeTranslationPairingRecords(
+      root,
+      metaPath,
+      readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8'),
+      readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8'),
+      readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8'),
+    )
+    const paths = translationPairPathsFromMeta(metaPath)
+    if (readGitIndexBlob(root, paths.source)?.objectId !== result.sourceHash) {
+      throw new Error(`${paths.source} staged merge does not match the pairing driver's clean merge`)
+    }
+    if (readGitIndexBlob(root, paths.zh)?.objectId !== result.zhHash) {
+      throw new Error(`${paths.zh} staged merge does not match the pairing driver's clean merge`)
+    }
+    for (const [path, expected] of [[paths.source, result.sourceHash], [paths.zh, result.zhHash]] as const) {
+      if (gitBlobHash(readFileSync(join(root, path))) !== expected) {
+        throw new Error(`${path} has unstaged content; refusing to confirm bytes outside the merge result`)
+      }
+    }
+    resolutions.push({ path: metaPath, record: result.record })
+  }
+  for (const resolution of resolutions) writeFileSync(join(root, resolution.path), resolution.record)
+  if (resolutions.length > 0) {
+    runGit(root, ['add', '--', ...resolutions.map(resolution => resolution.path)], 'staging resolved pairing records')
+  }
+  return resolutions.map(resolution => resolution.path)
+}
diff --git a/scripts/translation-pairing-record.ts b/scripts/translation-pairing-record.ts
new file mode 100644
index 0000000000..d4481ea5b4
--- /dev/null
+++ b/scripts/translation-pairing-record.ts
@@ -0,0 +1,99 @@
+/** Canonical paths, parsing, and rendering for bilingual pairing records. */
+
+import { basename } from 'node:path'
+
+/** The three repository-relative paths that form one bilingual pair. */
+export interface TranslationPairPaths {
+  /** English document path. */
+  source: string
+  /** Simplified Chinese document path. */
+  zh: string
+  /** Generated consistency-record path. */
+  meta: string
+}
+
+/** The two content hashes recorded for a bilingual pair. */
+export interface TranslationPairingRecord {
+  /** Git blob hash of the English document. */
+  sourceHash: string
+  /** Git blob hash of the Simplified Chinese document. */
+  zhHash: string
+}
+
+const META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
+
+/**
+ * Derive the counterpart and consistency-record paths from an English document.
+ *
+ * @param source - Repository-relative English Markdown path.
+ * @returns The complete three-path pair.
+ */
+export function translationPairPaths(source: string): TranslationPairPaths {
+  if (!source.endsWith('.md') || source.endsWith('.zh.md')) {
+    throw new Error(`expected an English Markdown path, received ${JSON.stringify(source)}`)
+  }
+  return {
+    source,
+    zh: source.replace(/\.md$/, '.zh.md'),
+    meta: source.replace(/\.md$/, '.i18n.yaml'),
+  }
+}
+
+/**
+ * Derive one pair from its consistency-record path.
+ *
+ * @param meta - Repository-relative `foo.i18n.yaml` path.
+ * @returns The complete three-path pair.
+ */
+export function translationPairPathsFromMeta(meta: string): TranslationPairPaths {
+  if (!meta.endsWith('.i18n.yaml')) {
+    throw new Error(`expected a bilingual consistency-record path, received ${JSON.stringify(meta)}`)
+  }
+  return translationPairPaths(meta.replace(/\.i18n\.yaml$/, '.md'))
+}
+
+/**
+ * Parse a consistency record for its expected sibling names.
+ *
+ * @param content - Complete sidecar text.
+ * @param paths - Expected sibling paths.
+ * @returns The two hashes, or `undefined` for malformed, duplicate, or unexpected keys.
+ */
+export function parseTranslationPairingRecord(
+  content: string,
+  paths: TranslationPairPaths,
+): TranslationPairingRecord | undefined {
+  const hashes = new Map<string, string>()
+  for (const line of content.split('\n')) {
+    if (line === '' || line.startsWith('#')) continue
+    const match = META_LINE.exec(line)
+    if (!match?.[1] || !match[2] || hashes.has(match[1])) return undefined
+    hashes.set(match[1], match[2])
+  }
+  const sourceHash = hashes.get(basename(paths.source))
+  const zhHash = hashes.get(basename(paths.zh))
+  if (hashes.size !== 2 || sourceHash === undefined || zhHash === undefined) return undefined
+  return { sourceHash, zhHash }
+}
+
+/**
+ * Render the canonical consistency record for a pair.
+ *
+ * @param paths - Pair paths written into the record and its recovery command.
+ * @param record - Confirmed content hashes.
+ * @returns Canonical YAML text with exactly one trailing newline.
+ */
+export function renderTranslationPairingRecord(
+  paths: TranslationPairPaths,
+  record: TranslationPairingRecord,
+): string {
+  return [
+    '# 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 ${paths.source}`,
+    `${basename(paths.source)}: ${record.sourceHash}`,
+    `${basename(paths.zh)}: ${record.zhHash}`,
+    '',
+  ].join('\n')
+}
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index 4d44266887..1073495d08 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -1,11 +1,16 @@
 /** Regression tests for bilingual snapshots, corpus scope, and structure. */
 
 import { execFileSync, spawnSync } from 'node:child_process'
-import { mkdtempSync, rmSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
-import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
+import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  parseTranslationPairingRecord,
+  renderTranslationPairingRecord,
+  translationPairPaths,
+} from './translation-pairing-record.ts'
 import {
   isTranslationScopeFile,
   pairAnchorOfArgument,
@@ -74,6 +79,28 @@ describe('translation pairing snapshots', () => {
     }
   })
 
+  it('reads staged bytes independently of the working tree', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-index-'))
+    try {
+      execFileSync('git', ['init', '--quiet', root], {
+        env: { ...process.env, GIT_DEFAULT_HASH: 'sha1' },
+      })
+      execFileSync('git', ['-C', root, 'config', 'user.email', 'pairing@example.test'])
+      execFileSync('git', ['-C', root, 'config', 'user.name', 'Pairing Test'])
+      writeFileSync(join(root, 'owner.md'), 'staged')
+      execFileSync('git', ['-C', root, 'add', 'owner.md'])
+      writeFileSync(join(root, 'owner.md'), 'unstaged')
+
+      const indexed = readGitIndexBlob(root, 'owner.md')
+
+      expect(indexed?.content.toString('utf8')).toBe('staged')
+      expect(indexed?.objectId).toBe(gitBlobHash(Buffer.from('staged')))
+      expect(readGitIndexBlob(root, 'absent.md')).toBeUndefined()
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
   it.skipIf(!supportsSha256ObjectFormat)('rejects an object format that pairing records cannot represent', () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-'))
     try {
@@ -113,6 +140,32 @@ describe('translation pairing manifest', () => {
   })
 })
 
+describe('translation pairing records', () => {
+  const paths = translationPairPaths('docs/foo.md')
+  const record = {
+    sourceHash: '1'.repeat(40),
+    zhHash: '2'.repeat(40),
+  }
+
+  it('round-trips the canonical two-hash record', () => {
+    expect(parseTranslationPairingRecord(renderTranslationPairingRecord(paths, record), paths)).toEqual(record)
+  })
+
+  it('rejects duplicate or unexpected keys', () => {
+    expect(parseTranslationPairingRecord([
+      `foo.md: ${'1'.repeat(40)}`,
+      `foo.md: ${'3'.repeat(40)}`,
+      `foo.zh.md: ${'2'.repeat(40)}`,
+      '',
+    ].join('\n'), paths)).toBeUndefined()
+    expect(parseTranslationPairingRecord([
+      `foo.md: ${'1'.repeat(40)}`,
+      `bar.zh.md: ${'2'.repeat(40)}`,
+      '',
+    ].join('\n'), paths)).toBeUndefined()
+  })
+})
+
 describe('translation scope discovery', () => {
   it.each([
     'README.md',
@@ -186,28 +239,56 @@ describe('pair CLI arguments', () => {
 
   it('scopes a check to named pairs and dedupes the three spellings', () => {
     expect(parseTranslationPairingCliArgs(['docs/foo.zh.md', 'docs/foo.i18n.yaml', 'docs/bar.md'])).toEqual({
+      input: 'worktree',
       mode: 'check',
       scope: 'pairs',
       anchors: ['docs/bar.md', 'docs/foo.md'],
     })
-    expect(parseTranslationPairingCliArgs([])).toEqual({ mode: 'check', scope: 'corpus', anchors: [] })
+    expect(parseTranslationPairingCliArgs([])).toEqual({
+      input: 'worktree',
+      mode: 'check',
+      scope: 'corpus',
+      anchors: [],
+    })
   })
 
   it('requires --write to name confirmed pairs or opt into --all', () => {
     expect(() => parseTranslationPairingCliArgs(['--write'])).toThrow('requires the pair(s) you confirmed')
     expect(parseTranslationPairingCliArgs(['--write', 'docs/foo.md'])).toEqual({
+      input: 'worktree',
       mode: 'write',
       scope: 'pairs',
       anchors: ['docs/foo.md'],
     })
-    expect(parseTranslationPairingCliArgs(['--write', '--all'])).toEqual({ mode: 'write', scope: 'corpus', anchors: [] })
+    expect(parseTranslationPairingCliArgs(['--write', '--all'])).toEqual({
+      input: 'worktree',
+      mode: 'write',
+      scope: 'corpus',
+      anchors: [],
+    })
     expect(() => parseTranslationPairingCliArgs(['--write', '--all', 'docs/foo.md'])).toThrow('not both')
   })
 
   it('keeps --list corpus-only and rejects unknown flags', () => {
-    expect(parseTranslationPairingCliArgs(['--list'])).toEqual({ mode: 'list', scope: 'corpus', anchors: [] })
+    expect(parseTranslationPairingCliArgs(['--list'])).toEqual({
+      input: 'worktree',
+      mode: 'list',
+      scope: 'corpus',
+      anchors: [],
+    })
     expect(() => parseTranslationPairingCliArgs(['--list', 'docs/foo.md'])).toThrow('takes no other flags or paths')
     expect(() => parseTranslationPairingCliArgs(['--all'])).toThrow('--all only applies to --write')
     expect(() => parseTranslationPairingCliArgs(['--frobnicate'])).toThrow('unknown flag(s): --frobnicate')
   })
+
+  it('makes cached verification a named, read-only index check', () => {
+    expect(parseTranslationPairingCliArgs(['--cached', 'docs/foo.i18n.yaml'])).toEqual({
+      input: 'index',
+      mode: 'check',
+      scope: 'pairs',
+      anchors: ['docs/foo.md'],
+    })
+    expect(() => parseTranslationPairingCliArgs(['--cached'])).toThrow('requires the staged pair paths')
+    expect(() => parseTranslationPairingCliArgs(['--cached', '--write', 'docs/foo.md'])).toThrow('read-only')
+  })
 })
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 7f24d9bce7..6d6893f843 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -120,6 +120,8 @@ export function pairAnchorOfArgument(argument: string): string {
 
 /** A parsed `verify-translation-pairing` invocation. */
 export interface TranslationPairingCliRequest {
+  /** Content plane read by the check. Writes and corpus checks use the working tree. */
+  input: 'worktree' | 'index'
   mode: 'check' | 'list' | 'write'
   /** `corpus` runs discovery over the whole tree; `pairs` touches only the named anchors. */
   scope: 'corpus' | 'pairs'
@@ -142,24 +144,32 @@ export interface TranslationPairingCliRequest {
 export function parseTranslationPairingCliArgs(argv: string[]): TranslationPairingCliRequest {
   const flags = argv.filter(argument => argument.startsWith('--'))
   const anchors = [...new Set(argv.filter(argument => !argument.startsWith('--')).map(pairAnchorOfArgument))].sort()
-  const unknown = flags.filter(flag => !['--list', '--write', '--all'].includes(flag))
+  const unknown = flags.filter(flag => !['--list', '--write', '--all', '--cached'].includes(flag))
   if (unknown.length > 0) throw new Error(`unknown flag(s): ${unknown.join(', ')}`)
   const listMode = flags.includes('--list')
   const writeMode = flags.includes('--write')
   const allMode = flags.includes('--all')
-  if (listMode && (writeMode || allMode || anchors.length > 0)) {
+  const cachedMode = flags.includes('--cached')
+  if (listMode && (writeMode || allMode || cachedMode || anchors.length > 0)) {
     throw new Error('--list reports the whole corpus and takes no other flags or paths')
   }
   if (allMode && !writeMode) throw new Error('--all only applies to --write')
+  if (cachedMode && writeMode) throw new Error('--cached is a read-only index check and cannot be combined with --write')
+  if (cachedMode && anchors.length === 0) throw new Error('--cached requires the staged pair paths to check')
   if (writeMode) {
     if (anchors.length > 0 && allMode) throw new Error('--write takes either pair paths or --all, not both')
     if (anchors.length === 0 && !allMode) {
       throw new Error('--write requires the pair(s) you confirmed (any file of a pair), or --all to re-record every complete pair; recording pairs you did not review blesses unconfirmed content')
     }
-    return { mode: 'write', scope: allMode ? 'corpus' : 'pairs', anchors }
+    return { input: 'worktree', mode: 'write', scope: allMode ? 'corpus' : 'pairs', anchors }
+  }
+  if (listMode) return { input: 'worktree', mode: 'list', scope: 'corpus', anchors: [] }
+  return {
+    input: cachedMode ? 'index' : 'worktree',
+    mode: 'check',
+    scope: anchors.length > 0 ? 'pairs' : 'corpus',
+    anchors,
   }
-  if (listMode) return { mode: 'list', scope: 'corpus', anchors: [] }
-  return { mode: 'check', scope: anchors.length > 0 ? 'pairs' : 'corpus', anchors }
 }
 
 /** The structural surface compared between the two sides of a pair. */
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index 4ebd664cb7..59818183e3 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -3,15 +3,21 @@
  * blob hashes for every in-scope document. The manifest contains only explicit
  * exclusions, which may have neither a counterpart nor a sidecar.
  * `--list` reports state; `--write <pairs...>` records the named confirmed
- * pairs (`--write --all` records every complete pair); a check or write named
- * with pair paths touches only those pairs, so update iteration does not pay
- * for a corpus scan. Translation quality remains a review responsibility.
+ * pairs (`--write --all` records every complete pair); `--cached <pairs...>`
+ * checks exact index bytes for hooks. A check or write named with pair paths
+ * touches only those pairs, so update iteration does not pay for a corpus
+ * scan. Translation quality remains a review responsibility.
  * See `docs/i18n/README.md` for the owning contract.
  */
 
 import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, join, resolve, sep } from 'node:path'
-import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
+import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  parseTranslationPairingRecord,
+  renderTranslationPairingRecord,
+  translationPairPaths,
+} from './translation-pairing-record.ts'
 import {
   linksTo,
   parseTranslationMarkdown,
@@ -33,6 +39,24 @@ try {
 }
 const listMode = request.mode === 'list'
 const writeMode = request.mode === 'write'
+const indexMode = request.input === 'index'
+
+const contentCache = new Map<string, Buffer | undefined>()
+
+/** Read one repository path from the selected worktree or index plane. */
+function readRepositoryFile(file: string): Buffer | undefined {
+  if (contentCache.has(file)) return contentCache.get(file)
+  const content = indexMode
+    ? readGitIndexBlob(root, file)?.content
+    : existsSync(join(root, file)) ? readFileSync(join(root, file)) : undefined
+  contentCache.set(file, content)
+  return content
+}
+
+/** Whether one path exists in the selected content plane. */
+function repositoryFileExists(file: string): boolean {
+  return readRepositoryFile(file) !== undefined
+}
 
 /** Discover source Markdown and pairing sidecars before applying the corpus predicate. */
 const SCOPE_PATTERNS = [
@@ -42,7 +66,11 @@ const SCOPE_PATTERNS = [
   '.agents/notes/**/*.i18n.yaml',
 ]
 
-const manifest = parseTranslationPairingManifest(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8'))
+const manifestContent = readRepositoryFile('scripts/translation-pairing.manifest.json')
+if (manifestContent === undefined) {
+  throw new Error('scripts/translation-pairing.manifest.json is missing from the selected content plane')
+}
+const manifest = parseTranslationPairingManifest(manifestContent.toString('utf8'))
 
 /**
  * An excluded entry ending in `/` excludes the whole directory. The trailing
@@ -54,50 +82,20 @@ function isExcluded(file: string): boolean {
   return manifest.excluded.some(entry => (entry.endsWith('/') ? file.startsWith(entry) : file === entry))
 }
 
-/** The three paths of a pair, derived from the English-file path. */
-function pairPaths(source: string): { zh: string; meta: string } {
-  return { zh: source.replace(/\.md$/, '.zh.md'), meta: source.replace(/\.md$/, '.i18n.yaml') }
-}
-
-const META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
-
-/** Parse a `foo.i18n.yaml` consistency record: basename → recorded blob hash. */
-function parseMeta(content: string): Map<string, string> | undefined {
-  const out = new Map<string, string>()
-  for (const line of content.split('\n')) {
-    if (line === '' || line.startsWith('#')) continue
-    const match = META_LINE.exec(line)
-    if (!match?.[1] || !match[2]) return undefined
-    out.set(match[1], match[2])
-  }
-  return out
-}
-
-/** Render a `foo.i18n.yaml` consistency record. */
-function renderMeta(source: string, sourceHash: string, zh: string, zhHash: string): string {
-  return [
-    '# 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 ${source}`,
-    `${basename(source)}: ${sourceHash}`,
-    `${basename(zh)}: ${zhHash}`,
-    '',
-  ].join('\n')
-}
-
 // Enumerate the scope once: the whole corpus, or exactly the named pairs'
 // three files (a named pair whose files are absent is caught by the same
 // completeness rules that cover discovered remnants).
 const files = new Set<string>()
 if (request.scope === 'pairs') {
   for (const anchor of request.anchors) {
-    for (const file of [anchor, ...Object.values(pairPaths(anchor))]) {
-      if (existsSync(join(root, file))) files.add(file)
+    const { source, zh, meta } = translationPairPaths(anchor)
+    for (const file of [source, zh, meta]) {
+      if (repositoryFileExists(file)) files.add(file)
     }
-    // A named anchor with no files on disk still enters the source list so
-    // the check reports it instead of silently passing an empty scope.
-    if (!existsSync(join(root, anchor))) files.add(anchor)
+    // A named worktree anchor with no files still enters the source list so
+    // an interactive check reports it. An index check accepts a complete
+    // three-file deletion and still rejects every partial deletion below.
+    if (!indexMode && !repositoryFileExists(anchor)) files.add(anchor)
   }
 } else {
   for (const pattern of SCOPE_PATTERNS) {
@@ -113,8 +111,11 @@ const sources = [...files].filter(f => f.endsWith('.md') && !f.endsWith('.zh.md'
 
 if (request.scope === 'pairs') {
   const rejected = request.anchors.filter(anchor => !isTranslationScopeFile(anchor) || isExcluded(anchor))
-  const absent = request.anchors.filter(anchor => ![anchor, ...Object.values(pairPaths(anchor))].some(file => existsSync(join(root, file))))
-  if (rejected.length > 0 || absent.length > 0) {
+  const absent = request.anchors.filter((anchor) => {
+    const { source, zh, meta } = translationPairPaths(anchor)
+    return ![source, zh, meta].some(repositoryFileExists)
+  })
+  if (rejected.length > 0 || (!indexMode && absent.length > 0)) {
     for (const anchor of rejected) {
       console.error(`verify-translation-pairing: ${anchor} is not an in-scope pair (excluded or outside the documentation corpus; see docs/i18n/README.md)`)
     }
@@ -132,20 +133,25 @@ if (writeMode) {
   let written = 0
   for (const source of sources) {
     if (isExcluded(source)) continue
-    const { zh, meta } = pairPaths(source)
-    if (!existsSync(join(root, source)) || !existsSync(join(root, zh))) {
+    const paths = translationPairPaths(source)
+    const { zh, meta } = paths
+    if (!repositoryFileExists(source) || !repositoryFileExists(zh)) {
       if (request.scope === 'pairs') {
-        console.error(`verify-translation-pairing: cannot record ${source}: missing ${existsSync(join(root, source)) ? zh : source}`)
+        console.error(`verify-translation-pairing: cannot record ${source}: missing ${repositoryFileExists(source) ? zh : source}`)
         process.exit(2)
       }
       continue
     }
-    const sourceContent = readFileSync(join(root, source))
-    const zhContent = readFileSync(join(root, zh))
+    const sourceContent = readRepositoryFile(source)
+    const zhContent = readRepositoryFile(zh)
+    if (sourceContent === undefined || zhContent === undefined) throw new Error(`${source}: complete pair became unreadable`)
     // A consistency record is also a recovery pointer for the briefing
     // generator. Persist both snapshots even when the sidecar text is already
     // current, because the bytes may exist only in this working tree.
-    const record = renderMeta(source, storeGitBlob(root, sourceContent), zh, storeGitBlob(root, zhContent))
+    const record = renderTranslationPairingRecord(paths, {
+      sourceHash: storeGitBlob(root, sourceContent),
+      zhHash: storeGitBlob(root, zhContent),
+    })
     if (existsSync(join(root, meta)) && readFileSync(join(root, meta), 'utf8') === record) continue
     writeFileSync(join(root, meta), record)
     console.log(`verify-translation-pairing: recorded ${meta}`)
@@ -161,8 +167,8 @@ const state = new Map<string, 'ok' | 'out-of-sync' | 'missing'>()
 // 1. Every discovered, non-excluded source merges bilingual.
 for (const source of sources) {
   if (isExcluded(source)) continue
-  const { zh } = pairPaths(source)
-  if (!existsSync(join(root, zh))) {
+  const { zh } = translationPairPaths(source)
+  if (!repositoryFileExists(zh)) {
     errors.push(`${source}: in-scope documentation must merge bilingual (docs/i18n/README.md); add the counterpart and record the pair`)
     state.set(source, 'missing')
   }
@@ -176,8 +182,13 @@ for (const zh of translations) pairAnchors.add(zh.replace(/\.zh\.md$/, '.md'))
 for (const meta of metas) pairAnchors.add(meta.replace(/\.i18n\.yaml$/, '.md'))
 
 for (const source of [...pairAnchors].sort()) {
-  const { zh, meta } = pairPaths(source)
-  const have = { source: existsSync(join(root, source)), zh: existsSync(join(root, zh)), meta: existsSync(join(root, meta)) }
+  const paths = translationPairPaths(source)
+  const { zh, meta } = paths
+  const have = {
+    source: repositoryFileExists(source),
+    zh: repositoryFileExists(zh),
+    meta: repositoryFileExists(meta),
+  }
 
   if (isExcluded(source)) {
     if (have.zh) errors.push(`${zh}: ${source} is excluded from pairing (generated or bilingual-by-construction); this translation must not exist`)
@@ -190,10 +201,14 @@ for (const source of [...pairAnchors].sort()) {
     continue
   }
 
-  const sourceContent = readFileSync(join(root, source))
-  const zhContent = readFileSync(join(root, zh))
-  const record = parseMeta(readFileSync(join(root, meta), 'utf8'))
-  if (!record || record.size !== 2 || !record.has(basename(source)) || !record.has(basename(zh))) {
+  const sourceContent = readRepositoryFile(source)
+  const zhContent = readRepositoryFile(zh)
+  const metaContent = readRepositoryFile(meta)
+  if (sourceContent === undefined || zhContent === undefined || metaContent === undefined) {
+    throw new Error(`${source}: complete pair became unreadable`)
+  }
+  const record = parseTranslationPairingRecord(metaContent.toString('utf8'), paths)
+  if (record === undefined) {
     errors.push(`${meta}: malformed consistency record (expected exactly \`${basename(source)}: <40-hex>\` and \`${basename(zh)}: <40-hex>\`)`)
     continue
   }
@@ -201,7 +216,8 @@ for (const source of [...pairAnchors].sort()) {
   let consistent = true
   for (const [file, content] of [[source, sourceContent], [zh, zhContent]] as const) {
     const current = gitBlobHash(content)
-    if (record.get(basename(file)) !== current) {
+    const recorded = file === source ? record.sourceHash : record.zhHash
+    if (recorded !== current) {
       errors.push(`${file}: out of sync — content no longer matches the pair's last confirmed-consistent state in ${meta} (bring the other side along, then re-record with --write)`)
       consistent = false
     }
@@ -247,7 +263,7 @@ if (listMode) {
 
 if (errors.length === 0) {
   console.log(request.scope === 'pairs'
-    ? `verify-translation-pairing: ${pairAnchors.size} named pair(s) consistent; the corpus-wide check still runs in doc-sync.`
+    ? `verify-translation-pairing: ${pairAnchors.size} named ${indexMode ? 'staged ' : ''}pair(s) consistent; the corpus-wide check still runs in doc-sync.`
     : `verify-translation-pairing: ${pairAnchors.size} pair(s) checked across all in-scope documentation, all consistent.`)
   process.exit(0)
 }

From 3abe813fd36103c22aed5e3ce37cb9020cd8683c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:11:48 +0800
Subject: [PATCH 037/262] docs(i18n): document automatic pairing merges

---
 ...matic-translation-pairing-merges.i18n.yaml |  6 +++
 ...08-automatic-translation-pairing-merges.md | 41 +++++++++++++++++++
 ...automatic-translation-pairing-merges.zh.md | 41 +++++++++++++++++++
 docs/development.i18n.yaml                    |  4 +-
 docs/development.md                           | 15 ++++---
 docs/development.zh.md                        | 15 ++++---
 docs/i18n/README.i18n.yaml                    |  4 +-
 docs/i18n/README.md                           |  2 +
 docs/i18n/README.zh.md                        |  2 +
 .../request-response.expected.json            |  8 ++--
 10 files changed, 118 insertions(+), 20 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
new file mode 100644
index 0000000000..bbd7870d69
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.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 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
+2026-08-08-automatic-translation-pairing-merges.md: a1b92c97240e2019b188b606dc079b2211a89238
+2026-08-08-automatic-translation-pairing-merges.zh.md: 5c7249dc436d24aa955d9c042c8d1bdc84655868
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
new file mode 100644
index 0000000000..a1b92c9724
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
@@ -0,0 +1,41 @@
+# Agent Note: Automatically compose translation pairing records
+
+Status: implemented
+
+English | [中文](2026-08-08-automatic-translation-pairing-merges.zh.md)
+
+## Problem
+
+A bilingual consistency record contains the two owner files' exact blob hashes. Two branches that independently update different parts of the same confirmed pair therefore conflict on both hash lines even when Git cleanly composes both Markdown owners. Selecting either side leaves stale hashes, while regenerating the record by hand repeats a deterministic operation and prevents an otherwise automatic merge.
+
+## Decision
+
+`*.i18n.yaml` uses the repository-owned `dsh-translation-pairing` merge driver. The worktree-local Git installer registers its command alongside Lefthook setup; Git configuration remains local because a tracked attribute can name a driver but cannot carry its executable command.
+
+The driver parses the ancestor, current, and other records and loads the six owner blobs named by their hashes. It independently runs Git's default three-way text merge for the English and Chinese triplets, requires both merges to be clean, verifies language switchers and the pairing structural signature, stores the two merged blobs, and writes their hashes as the canonical record. This composes confirmations already present in both parents; it never records an ordinary one-sided documentation edit.
+
+The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy, either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
+
+`pnpm run resolve-translation-pairing-conflicts` applies the same algorithm after a merge has already stopped. Before writing any sidecar, it proves that the staged owner blob IDs and working-tree bytes equal its independent merges; then it writes and stages every safe record as one batch while leaving unrelated conflicts untouched.
+
+`pre-merge-commit` and `pre-commit` verify staged `.i18n.yaml` files against the exact index bytes of their owners. They validate driver output but do not regenerate records, so bypassing a hook cannot silently bless translation drift; the corpus-wide `doc-sync` check remains authoritative in CI.
+
+## Verification
+
+Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, owner-content conflicts, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
+
+## Alternatives considered
+
+**Take ours or use Git's union driver.** Either parent record names pre-merge content, while union produces duplicate or unordered hash keys. Neither represents the merged owners.
+
+**Regenerate in `post-merge` or only in a commit hook.** `post-merge` does not run after a conflicted merge and cannot affect its outcome. Commit hooks are reached only after the index has no unresolved entries, so a hook alone cannot clear the generated conflict.
+
+**Wrap every merge in a repository command.** A wrapper can resolve the conflict from the populated index, and the explicit resolver retains that recovery path, but raw Git, stack tooling, rebases, and cherry-picks would still stop before it. The merge driver is the file-level extension point shared by those operations.
+
+**Resolve on GitHub through Actions or an app.** Hosted automation could update PR branches, but it adds credentials, concurrency control, and branch mutation. Local and agent-driven merge-forward workflows already have a checkout and push authority; the repository keeps remote automation out of this mechanism.
+
+## Consequences
+
+Installed worktrees automatically remove pairing-record-only conflicts while preserving human judgment for owner conflicts and translation quality. GitHub's hosted mergeability calculation does not run the worktree-local executable, so a contributor or agent must still merge the base and push the resulting commit before the remote conflict badge clears.
+
+The installer reserves `merge.dsh-translation-pairing.*` in worktree configuration and refuses a conflicting custom value. Merge execution depends on the installed Node dependencies, like the repository's contributor hooks; missing setup fails rather than selecting stale metadata.
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
new file mode 100644
index 0000000000..5c7249dc43
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 自动组合翻译配对记录
+
+Status: implemented
+
+[English](2026-08-08-automatic-translation-pairing-merges.md) | 中文
+
+## 问题
+
+一份双语一致性记录包含两侧 Markdown 文件的精确 blob hash。因此，当两个分支分别更新同一已确认配对的不同部分时，即使 Git 能干净合并两侧 Markdown 文件，记录中的两行 hash 仍会发生冲突。选择任一侧都会留下陈旧 hash；手工重新生成记录则会重复执行一项确定性操作，并阻止本可自动完成的合并。
+
+## 决策
+
+`*.i18n.yaml` 使用由仓库维护的 `dsh-translation-pairing` 合并驱动。worktree 本地的 Git 安装脚本在设置 Lefthook 的同时注册该驱动命令；Git 配置仍限定于当前 worktree，因为受跟踪的属性可以指定驱动，却无法携带其可执行命令。
+
+驱动会解析祖先、当前和另一侧的记录，并加载其中 hash 指向的六个 Markdown blob。它分别对英文文档的三个 blob 与中文文档的三个 blob 运行 Git 默认的三方文本合并，要求两次合并都干净完成，校验语言切换行与配对结构签名，存储两个合并后的 blob，再将其 hash 写入规范记录。这一过程组合两个父提交中已经存在的确认；它绝不会为普通的单侧文档编辑写入记录。
+
+记录格式错误、对象缺失、配对文档采用其他合并策略、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
+
+`pnpm run resolve-translation-pairing-conflicts` 会在合并已经停止后应用同一算法。写入任何伴随文件之前，它会先验证暂存区中配对文档的 blob ID 以及工作树中的文件字节，都与工具独立完成的合并结果一致；随后它会将所有可安全生成的记录作为一个批次写入并暂存，同时不改动无关冲突。
+
+`pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
+
+## 验证
+
+脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、配对文档内容冲突、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
+
+## 考虑过的替代方案
+
+**选择 ours 或使用 Git 的 union 驱动。** 任一父提交的记录都指向合并前的内容，而 union 会产生重复或乱序的 hash 键。两者都无法表示合并后的配对文档。
+
+**在 `post-merge` 中或仅通过提交钩子重新生成。** 发生冲突的合并不会运行 `post-merge`，而且该钩子无法改变合并结果。只有暂存区不含未解决条目后才会触发提交钩子，因此仅用钩子无法清除生成文件冲突。
+
+**用仓库命令包装每次合并。** 包装命令可以根据已由合并填充的索引解决冲突，显式冲突解决命令也保留这条恢复路径，但直接运行 Git、stack 工具、rebase 和 cherry-pick 时仍会在此前停止。合并驱动才是这些操作共用的文件级扩展点。
+
+**通过 GitHub Actions 或应用解决。** 托管自动化可以更新 PR（Pull Request）分支，却会引入凭据、并发控制与分支修改。本地执行或由 agent（智能体）驱动的 merge-forward 工作流已经具有检出目录与推送权限，因此仓库不把远程自动化纳入该机制。
+
+## 后果
+
+完成安装的 worktree 会自动消除仅由配对记录引起的冲突，同时仍由人工处理配对文档冲突并评判翻译质量。GitHub 托管的可合并性计算不会运行 worktree 本地的可执行命令，因此仍须由贡献者或 agent 将 base 分支合入当前分支并推送结果提交，远端冲突标记才会消失。
+
+安装脚本会在 worktree 配置中预留 `merge.dsh-translation-pairing.*`，并拒绝与之冲突的自定义值。与仓库贡献者钩子一样，合并过程依赖已安装的 Node 依赖；安装未完成时，合并会失败，而不是选择陈旧元数据。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 676c78bb90..3c57bb057c 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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 docs/development.md
-development.md: a9edd80abfbd53c9fc0495b4b495fa495207ca95
-development.zh.md: 405942c26ef3600209bc14a300c94a98d4f2b9f3
+development.md: 1b0a412cd55224740a074a88734bc5663a14effc
+development.zh.md: 3c01f680dd8107fe6b3369415a979cea69cd19a0
diff --git a/docs/development.md b/docs/development.md
index a9edd80abf..1b0a412cd5 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -21,9 +21,9 @@ Install dependencies from the repo root:
 pnpm install
 ```
 
-The install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.
+The install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.
 
-If hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:
+If either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:
 
 ```sh
 node scripts/install-lefthook.mjs
@@ -98,18 +98,21 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 `DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.
 
-### Git hooks
+### Git integrations
+
+The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
-- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.
 - `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.
 
 The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.
 
-The hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.
+Apart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.
 
-Contributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.
+Contributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.
 
 ### CI gates
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 405942c26e..3c01f680dd 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -21,9 +21,9 @@
 pnpm install
 ```
 
-安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。
+安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
 
-如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：
+如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：
 
 ```sh
 node scripts/install-lefthook.mjs
@@ -98,18 +98,21 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 `DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。
 
-### Git 钩子
+### Git 集成
+
+当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
-- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
 - `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
-这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。
+除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。
 
-贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。
+贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。
 
 ### CI 门禁
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 464a3c8df0..48d27cbb41 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: 2bac578034441bbe786ce54c051cc622bf9275c0
-README.zh.md: b7566bf6f88e03eb06227b63011f78252b4dcd07
+README.md: 2f9d7d1112492545e4e82d8d99c3d11df383e42d
+README.zh.md: 65ac3552aa4b66cbd43e6b55b98f0e1d9491feea
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 2bac578034..2f9d7d1112 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -16,6 +16,8 @@ This repo's documentation is read by people and agents both inside and outside t
   ```
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).
+
+  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
 - **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
 - **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index b7566bf6f8..65ac3552aa 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -16,6 +16,8 @@
   ```
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。
+
+  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
 - **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
 - **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index baa648925d..b45ffe01e0 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,19 +16,19 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",

From 75570ba31e79bd5b75c1268de23e34d97d72d7a5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:26:31 +0800
Subject: [PATCH 038/262] test(i18n): deduplicate merge conflict setup

---
 scripts/translation-pairing-merge.spec.ts | 25 +++++++++++------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index c6a9a5bbb7..bd6d2a632b 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -103,6 +103,16 @@ function createDivergedPair(fixture: Fixture): { ancestor: string; current: stri
   return { ancestor, current, other }
 }
 
+function startStoppedPairingMerge(fixture: Fixture): void {
+  createDivergedPair(fixture)
+  const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+    encoding: 'utf8',
+    env: fixture.env,
+  })
+  expect(merge.status).toBe(1)
+  expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+}
+
 function expectMergedPair(fixture: Fixture): void {
   expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(mergedSource)
   expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(mergedZh)
@@ -223,13 +233,7 @@ describe('translation pairing merge composition', () => {
 
   it('resolves an already-stopped generated-only conflict from index stages', () => {
     const fixture = createFixture(false)
-    createDivergedPair(fixture)
-    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: fixture.env,
-    })
-    expect(merge.status).toBe(1)
-    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+    startStoppedPairingMerge(fixture)
 
     expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
 
@@ -239,12 +243,7 @@ describe('translation pairing merge composition', () => {
 
   it('refuses to confirm unstaged owner bytes after a stopped merge', () => {
     const fixture = createFixture(false)
-    createDivergedPair(fixture)
-    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: fixture.env,
-    })
-    expect(merge.status).toBe(1)
+    startStoppedPairingMerge(fixture)
     write(fixture.root, 'docs/guide.md', `${mergedSource}\nunstaged\n`)
 
     expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(

From 8917ff8ef4a6f8c79d9d0f66429ab10734ca3b23 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 23:00:00 +0800
Subject: [PATCH 039/262] refactor(runtime): compose consumers over fs and
 subprocess

---
 ...06-17-filesystem-capability-seam.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-capability-seam.md  |   7 +-
 ...026-06-17-filesystem-capability-seam.zh.md |  19 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   4 +-
 .../2026-07-15-lsp-capability-seam.md         |  20 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  32 +-
 ...26-subprocess-consumer-migration.i18n.yaml |   4 +-
 ...026-07-26-subprocess-consumer-migration.md |  16 +-
 ...-07-26-subprocess-consumer-migration.zh.md |  18 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |   4 +-
 .../2026-07-26-subprocess-seam.md             |   8 +-
 .../2026-07-26-subprocess-seam.zh.md          |  18 +-
 ...rtable-execution-world-consumers.i18n.yaml |   6 +
 ...7-28-portable-execution-world-consumers.md |  48 ++
 ...8-portable-execution-world-consumers.zh.md |  48 ++
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |  28 +-
 .../feature/2026-06-15-code-mode.zh.md        |  48 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |   4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  25 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  39 +-
 docs/config-catalog.md                        |  34 +-
 docs/cordis-catalog/events.md                 |   6 +-
 .../core-data-structures/filesystem.i18n.yaml |   4 +-
 docs/core-data-structures/filesystem.md       |   6 +-
 docs/core-data-structures/filesystem.zh.md    |   6 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.md       |  16 +-
 docs/core-data-structures/subprocess.zh.md    |  46 +-
 knip.json                                     |  10 +
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   2 +-
 packages/README.zh.md                         |   2 +-
 .../code-runtime-worker/README.md             |   2 +-
 .../code-runtime-worker/src/runtime-host.ts   | 222 +++++++++
 .../code-runtime-worker/tsconfig.json         |   3 -
 .../code-runtime-worker/tsdown.config.ts      |  17 +-
 packages/code-runtime/code-runtime/README.md  |   4 +-
 .../tests/workspace-context.spec.ts           |  14 +
 .../cordis/tool-cordis/src/api-catalog.ts     |  40 ++
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |  21 +-
 packages/fs/README.zh.md                      |  25 +-
 packages/fs/fs-local/README.i18n.yaml         |   4 +-
 packages/fs/fs-local/README.md                |   7 +-
 packages/fs/fs-local/README.zh.md             |  19 +-
 packages/fs/fs-local/src/fsio.ts              |  73 ++-
 packages/fs/fs-local/src/index.ts             |  21 +-
 packages/fs/fs-local/tests/filesystem.spec.ts |  24 +
 packages/fs/fs-local/tests/fsio.spec.ts       |  63 ++-
 packages/fs/fs/README.i18n.yaml               |   4 +-
 packages/fs/fs/README.md                      |  27 +-
 packages/fs/fs/README.zh.md                   |  45 +-
 packages/fs/fs/src/index.ts                   |  52 +-
 packages/fs/fs/tests/service.spec.ts          |  13 +-
 packages/fs/tool-fs/tests/tools.spec.ts       |  10 +
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |  10 +-
 packages/lsp/README.zh.md                     |  12 +-
 packages/lsp/lsp-local/README.i18n.yaml       |   4 +-
 packages/lsp/lsp-local/README.md              |  18 +-
 packages/lsp/lsp-local/README.zh.md           |  26 +-
 packages/lsp/lsp-local/package.json           |   3 +
 packages/lsp/lsp-local/src/connection.ts      |   7 +-
 packages/lsp/lsp-local/src/host.ts            | 182 +++----
 packages/lsp/lsp-local/src/index.ts           | 115 ++---
 packages/lsp/lsp-local/src/instance.ts        |  13 +-
 packages/lsp/lsp-local/tests/built-lib.e2e.ts |   5 +-
 packages/lsp/lsp-local/tests/host.spec.ts     |  68 ++-
 packages/lsp/lsp-local/tests/instance.spec.ts |  17 +-
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |   4 +
 packages/lsp/lsp-local/tests/provider.spec.ts |  13 +
 .../lsp-local/tests/typescript-server.e2e.ts  |   2 +
 packages/lsp/lsp-local/tsconfig.json          |   3 +
 packages/lsp/tool-lsp/package.json            |   2 +
 .../lsp/tool-lsp/tests/integration.spec.ts    |   2 +
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |  11 +-
 packages/pty/README.zh.md                     |  11 +-
 packages/pty/pty-local/README.i18n.yaml       |   4 +-
 packages/pty/pty-local/README.md              |  20 +-
 packages/pty/pty-local/README.zh.md           |  24 +-
 packages/pty/pty-local/package.json           |   8 +-
 packages/pty/pty-local/src/index.ts           |  69 ++-
 packages/pty/pty-local/src/session.ts         | 341 ++++++-------
 packages/pty/pty-local/tests/index.spec.ts    | 173 +++----
 packages/pty/pty-local/tests/local.spec.ts    |   2 +
 packages/pty/pty-local/tests/session.spec.ts  | 471 +++++++++++-------
 packages/pty/tool-pty/package.json            |   1 +
 .../tool-pty/tests/loader-composition.spec.ts |   3 +
 .../skill-local/tests/skill-local.spec.ts     |  14 +
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |  10 +-
 packages/subprocess/README.zh.md              |  12 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |  14 +-
 .../subprocess/subprocess-local/README.zh.md  |  22 +-
 .../subprocess/subprocess-local/package.json  |   7 +
 .../scripts/ensure-spawn-helper.mjs           |   0
 .../subprocess/subprocess-local/src/index.ts  | 104 +++-
 .../src/process-inspector.ts                  |  10 +-
 .../subprocess-local/src/terminal.ts          | 226 +++++++++
 .../subprocess-local/tests/local.spec.ts      | 134 ++++-
 .../tests/process-inspector.spec.ts           |   6 +-
 .../subprocess-local/tests/terminal.spec.ts   | 275 ++++++++++
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |  10 +-
 packages/subprocess/subprocess/README.zh.md   |  22 +-
 packages/subprocess/subprocess/src/index.ts   |  52 +-
 packages/subprocess/subprocess/src/types.ts   |  68 +++
 .../subprocess/tests/service.spec.ts          |  29 +-
 scripts/check-workspace-constraints.ts        |   1 +
 scripts/gen-cordis-catalog.ts                 |   3 +
 scripts/run-gates.ts                          |   7 +-
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.host.json                            |   1 +
 116 files changed, 2828 insertions(+), 1122 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
 create mode 100644 packages/code-runtime/code-runtime-worker/src/runtime-host.ts
 rename packages/{pty/pty-local => subprocess/subprocess-local}/scripts/ensure-spawn-helper.mjs (100%)
 rename packages/{pty/pty-local => subprocess/subprocess-local}/src/process-inspector.ts (96%)
 create mode 100644 packages/subprocess/subprocess-local/src/terminal.ts
 rename packages/{pty/pty-local => subprocess/subprocess-local}/tests/process-inspector.spec.ts (98%)
 create mode 100644 packages/subprocess/subprocess-local/tests/terminal.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index efdb14ea94..dc9b924f54 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: fee0161e5e8397ac1d1c0e2850efad840c65d971
-2026-06-17-filesystem-capability-seam.zh.md: 46e3ad22c530319d0d1b6ba23a8aba8ffc2fdb8c
+2026-06-17-filesystem-capability-seam.md: 2fb360e5ad3c972f4a8de50c602a79af158dfc22
+2026-06-17-filesystem-capability-seam.zh.md: 1f70113b1583d890047ee4a17161f76b6390d8e8
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index fee0161e5e..2fb360e5ad 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -62,8 +62,9 @@ The root `tool-fs` plugin registers the full filesystem tool suite (`read`, `wri
 The interface covers these semantic operations:
 
 - Resolve a model/plugin-supplied path into a backend-defined target.
+- Convert a resolved target to the canonical process path or `file:` URI for the same execution world, and test containment without parsing its opaque key.
 - Stat target metadata without reading file contents.
-- Read a bounded UTF-8 text page from a target.
+- Read complete or streamed UTF-8 text, including one stable-handle byte-bounded whole-file operation.
 - Create or replace a UTF-8 text file.
 - Edit an existing UTF-8 text file by literal replacement.
 
@@ -83,9 +84,11 @@ Resolved targets must expose at least three concepts:
 - An opaque `targetKey`, used for stale guards and file-state lookup. The local backend might use a realpath-like key; a remote backend might use a workspace URI or file id. Consumers must not parse or assume this is a local absolute path.
 - A `displayPath`, used for model/UI-facing output. It may be a local absolute path, workspace-relative path, or remote URI depending on the backend.
 
+`targetKey` remains opaque even when another capability shares the provider's execution world. Such consumers ask the provider for `processPath(target)`, `fileUrl(target)`, or `contains(parent, child)`; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns why these facts sit on the filesystem seam.
+
 Read and mutation results must include an opaque file `version`. The local backend derives its token from bigint stat metadata (`dev`, `ino`, `size`, `mtimeNs`, and `ctimeNs`) so same-size rewrites and inode replacement invalidate consumers reliably; a remote backend can use a revision id or hash-like token. The `dsh-fs-policy` plugin records versions for stale checks; consumers may display related metadata but must not interpret the version token.
 
-The provider hands back decoded text: `readText` returns a whole regular text file, `streamText` streams the same text semantics for large files. Both own regular-file checks, bounded line/output handling is NOT theirs — line windowing, numbered-line rendering, and total-line accounting live in the executor (`dsh-tool-fs`), which reads through `ctx.fs` and renders the model-facing window. The provider owns UTF-8 decoding and binary/NUL rejection; it does not know about line windows or views.
+The provider hands back decoded text: `readText` returns a whole regular text file, `streamText` streams the same text semantics for large files, and `readTextBounded` holds one backend-owned stable handle while rejecting a complete file above its byte ceiling. Line windowing, numbered-line rendering, and total-line accounting live in the executor (`dsh-tool-fs`). The provider owns regular-file checks, UTF-8 decoding, binary/NUL rejection, and the bounded read's replacement/growth race; it does not know about line windows or views.
 
 Observed-state recording is not on `ctx.fs`: after a successful read the executor emits `fs/observed`, and the `dsh-fs-policy` plugin records `{ version }` for the deriving owner. There is no `full`/`partial` view — a read at any window records the version, and freshness (not view completeness) authorizes a later write/edit.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index 46e3ad22c5..1f70113b15 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -16,7 +16,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的契约应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
 
-我们需要文件系统工具在成为公开包接口之前，以与 bash 相同的能力 seam 形态落地。
+我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
 
 ## 决策
 
@@ -51,7 +51,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 `@deepseek-ai/dsh-fs-local` 依赖 `@deepseek-ai/dsh-fs` 和 `cordis`。它继承 `FileSystem`，将自身注册为 `ctx.fs`，拥有本地后端配置（如基目录），并包含所有直接的 `node:fs` / `node:path` 访问。它不持有观测状态存储——新鲜度是后端铸造、策略插件记录的版本令牌。
 
-`@deepseek-ai/dsh-tool-fs` 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 `cordis`。它注册面向模型的工具和提示词段落。它禁止导入 `node:fs`、`node:path` 或 `@deepseek-ai/dsh-fs-local`；文件系统执行始终通过 `ctx.fs`。如果实现需要具体的 agent（智能体）或会话辅助类型，这些依赖属于 `tool-fs`；它们禁止回漏到 `dsh-fs` 中。
+`@deepseek-ai/dsh-tool-fs` 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 `cordis`。它注册面向模型的工具和提示词段落。它禁止导入 `node:fs`、`node:path` 或 `@deepseek-ai/dsh-fs-local`；文件系统执行始终通过 `ctx.fs`。如果实现需要具体的 agent 或会话辅助类型，这些依赖属于 `tool-fs`；它们禁止回漏到 `dsh-fs` 中。
 
 根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
 
@@ -62,8 +62,9 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 该接口涵盖以下语义操作：
 
 - 将模型/插件提供的路径解析为后端定义的目标。
+- 将解析后的目标转换为同一执行环境的规范进程路径或 `file:` URI，并在不解析其不透明键的情况下检查包含关系。
 - 获取目标元数据而不读取文件内容。
-- 从目标读取有界的 UTF-8 文本页。
+- 读取完整或流式 UTF-8 文本，其中包括一项持有稳定句柄、以字节为上限的全文件读取操作。
 - 创建或替换一个 UTF-8 文本文件。
 - 通过字面替换编辑一个已有的 UTF-8 文本文件。
 
@@ -83,13 +84,15 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 - 不透明的 `targetKey`，用于陈旧守护和文件状态查找。本地后端可能使用类似 realpath 的键；远程后端可能使用工作区 URI 或文件 id。消费方禁止解析或假设它是本地绝对路径。
 - `displayPath`，用于面向模型/UI 的输出。根据后端不同，它可能是本地绝对路径、工作区相对路径或远程 URI。
 
-读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方持有的版本失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
+即使另一项能力共享提供方的执行环境，`targetKey` 仍保持不透明。这类消费方通过提供方的 `processPath(target)`、`fileUrl(target)` 或 `contains(parent, child)` 获取所需事实；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)说明这些事实为何属于文件系统 seam。
 
-提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式输出相同的文本语义。两者负责常规文件检查；有界的行/输出处理不是它们的职责——行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中，执行器通过 `ctx.fs` 读取并渲染面向模型的窗口。提供方负责 UTF-8 解码和二进制/NUL 拒绝；它不知道行窗口或视图。
+读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
+
+提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式传输相同的文本语义，`readTextBounded` 则持有一个归后端所有的稳定句柄，并在完整文件超过字节上限时拒绝。行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中。提供方负责普通文件检查、UTF-8 解码、二进制/NUL 拒绝，以及有界读取期间的路径替换／增长竞态；它不知道行窗口或视图。
 
 观测状态记录不在 `ctx.fs` 上：成功读取后，执行器发出 `fs/observed`，`dsh-fs-policy` 插件为推导出的 owner 记录 `{ version }`。没有 `full`/`partial` 视图——任何窗口的读取都记录版本，新鲜度（而非视图完整性）授权后续的写入/编辑。
 
-全文件写入创建或替换 UTF-8 文本文件。后端在支持且有文档说明时可以创建父目录。已有的非常规目标被拒绝。`writeText` 接受一个可选期望：`createIfAbsent` 创建缺失的目标并拒绝已存在的（报 `FS_NOT_OBSERVED`，这是策略处理未观测 owner 时采用的分支）；`replaceIfVersion` 仅在目标处于观测版本时替换，否则报 `FS_STALE_VERSION`；省略期望则为无条件的裸提供方创建或覆盖。策略插件根据 owner 的观测状态选择提供哪个期望。
+全文件写入创建或替换 UTF-8 文本文件。后端在支持且有文档说明时可以创建父目录。已有的非常规目标被拒绝。`writeText` 接受一个可选期望：`createIfAbsent` 创建缺失的目标并拒绝已存在的（报 `FS_NOT_OBSERVED`，这是策略为未观测 owner 使用的路径）；`replaceIfVersion` 仅在目标处于观测版本时替换，否则报 `FS_STALE_VERSION`；省略期望则为无条件的裸提供方创建或覆盖。策略插件根据 owner 的观测状态选择提供哪个期望。
 
 字面编辑是提供方原语（`editText`），而非在 `tool-fs` 中由读取加写入组合而成。字面匹配、重复匹配拒绝、CRLF 保留、二进制拒绝、可选的陈旧版本检查和原子读-改-写必须一起留在后端的变更临界区内。`editText` 接受相同的可选版本期望；陈旧检查在字面匹配之前运行，因此基于旧读取的编辑会报 `FS_STALE_VERSION`。远程后端可以将编辑实现为原生的 compare-and-edit 操作；消费方不强制本地风格的组合。
 
@@ -124,11 +127,11 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 ## 测试
 
-测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式输出、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
+测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
 
 本仓库曾踩过的防御性模式类别被直接固定：
 
-- **原子写入临时文件安全。** 写入/编辑通过目标旁边一个私有随机 `0700` 目录中独占且仅所有者可访问（`'wx'`、`0o600`）的临时文件暂存，失败时清理，最后原子 rename——与 bash spill 文件规则一致，因为可预测的全局可读临时路径会招致符号链接竞争和信息泄露。测试断言权限，并断言已存在的临时路径不会被覆盖；此原语是 seam 的常设要求。
+- **原子写入临时文件安全。** 写入/编辑通过目标旁边一个私有随机 `0700` 目录中的独占 owner-only（`'wx'`、`0o600`）临时文件暂存，失败时清理，最后原子 rename——与 bash 溢出文件规则一致，因为可预测的 world-readable 临时路径招致符号链接竞争和信息泄露。测试断言权限，并断言已存在的临时路径不会被覆盖；此原语是 seam 的常设要求。
 - **通过符号链接的 `targetKey` 同一性。** 两个输入路径解析到同一 realpath 时共享一个观测状态条目：通过路径 A 的 `read` 满足通过符号链接路径 B 的 `edit` 的读后编辑守护，通过一个路径的陈旧写入可通过另一个路径检测到。
 - **并发/陈旧竞争。** 对同一目标的两个并发写入/编辑操作确定性地收敛——一个成功，另一个被 `FS_STALE_VERSION` 拒绝——成功的编辑刷新记录状态，使同一 owner 的下一次编辑可以继续。
 - **HMR（热模块替换）安全与 dispose（资源释放）。** dispose 后端的 fiber 会撤回 `ctx.fs` 提供方；后续的提供方以无继承状态启动。
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index 11073946ea..afb9251d33 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: d96b3a9c5139c1455a51f4fff793293d7b5a11c0
-2026-07-15-lsp-capability-seam.zh.md: 256b293f213acb06588f3ef6c655242b1c8fd5b9
+2026-07-15-lsp-capability-seam.md: a9dab45ebf034f6d5218b25a0868a7e86803719b
+2026-07-15-lsp-capability-seam.zh.md: b411a2456ea2a3838e56422f58954473da51ae23
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index d96b3a9c51..a9dab45ebf 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -79,7 +79,7 @@ interface LspService {
 
 Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's resolved workspace root so consumers relativize file URIs in the same canonical namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
 
-`dsh-lsp-local` owns host files, server configuration, JSON-RPC, process and transient-document state, and protocol translation; it depends on `dsh-lsp` and Node APIs, not `dsh-fs`. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
+`dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their interface packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
 
 ## Model-facing contract
 
@@ -112,26 +112,26 @@ Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutd
 
 ## Workspace, filesystem, and document synchronization
 
-`dsh-lsp-local` canonicalizes and reads through Node APIs in the subprocess's host namespace. It rejects missing, non-regular, non-UTF-8, oversized, or canonical out-of-workspace sources and keeps one `O_NOFOLLOW | O_NONBLOCK` handle through validation and reading, so a FIFO with no writer cannot block before the regular-file check. It observes caller cancellation around each filesystem operation. It does not consume `ctx.fs` or emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
+`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It observes caller cancellation around each provider operation. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
 
 The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers.
 
 The local provider uses a compatibility-first transient-open sequence for every query. It accepts legacy `textDocumentSync` `Full` or `Incremental`, or options with `openClose: true`; omitted, `None`, or explicitly incompatible synchronization fails as unsupported before `didOpen`.
 
-1. Canonicalize and validate the host path, then read the current source with Node filesystem APIs.
+1. Resolve and contain the source through `ctx.fs`, then read its current bounded text through the same provider.
 2. Send `textDocument/didOpen` with version `1`, full text, and the configured language id. Its write remains abortable; failure or cancellation invalidates the instance and awaits bounded process termination before the pool can reuse it.
 3. Send the requested `textDocument/definition`, `textDocument/references`, `textDocument/implementation`, or `textDocument/hover` request.
 4. If `didOpen` succeeded, attempt `textDocument/didClose` in `finally` after the request settles or aborts. A close-write failure does not replace the settled result or error, but invalidates the instance and awaits bounded process termination.
 
 Documents close after each call, so the first version needs no `didChange`, `didSave`, content cache, mutation listener, or document LRU. One abortable per-workspace provider queue serializes source-read/open/query/close lifecycles, so a waiting query reads current bytes only when its turn starts; the instance also keeps protocol lifecycles serialized. Distinct workspaces may run in parallel. The server's workspace index remains responsible for closed files reached from the source.
 
-The canonical workspace `realpath` must be a directory and supplies process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity; symlink aliases therefore share an instance. Result locations may be external, but an external path cannot become a query source. Remote, virtual, or independently sandboxed filesystems require another provider.
+The canonical workspace target must be a directory. Its target key supplies pool identity, its process path supplies cwd, and its provider-owned `file:` URI supplies `rootUri` and the sole `workspaceFolders` entry; aliases share an instance when the filesystem provider resolves them to one key. Result locations may be external, but an external path cannot become a query source. A filesystem that cannot share paths with the mounted subprocess provider is a composition error, not a reason for another LSP package.
 
 ## Local server lifecycle and protocol behavior
 
-`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace realpath)`. At load it resolves the executable after credential scrubbing and environment overrides, failing before registration if unavailable; server process launch stays lazy (first query spawns it) and uses no shell. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter.
+`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace target)`. At load it calls `ctx.subprocess.resolveExecutable()` with the configured environment, failing before registration if unavailable; first query launches through raw protocol pipes with no shell and a bounded collected stderr tail. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter.
 
-Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. Returned operation and synchronization capabilities are authoritative. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. Configuration may supply initialization options and `workspace/configuration` responses, but the client rejects `workspace/applyEdit` and never executes commands or edits.
+Initialization uses `processId: null` because the client and server may inhabit different process namespaces. It advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. Returned operation and synchronization capabilities are authoritative. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. Configuration may supply initialization options and `workspace/configuration` responses, but the client rejects `workspace/applyEdit` and never executes commands or edits.
 
 Navigation maps `Location` directly and `LocationLink` from `targetUri` plus `targetSelectionRange`. Positions must be nonnegative integers. Hover normalization accepts only valid `MarkupContent` and `MarkedString` shapes, preserves string values, renders language-tagged values as fenced code, and joins arrays with one blank line. The model-facing tool applies `maxResultChars` after rendering.
 
@@ -143,7 +143,7 @@ Symbols are deferred because they need different schemas and overlap read/search
 
 Diagnostics need separate freshness, accumulation, and transcript rules. Mutations such as rename, code actions, and formatting require separate tools with preview, permission, and write-policy integration.
 
-The local provider trusts its configured server and claims no sandbox confinement. Supporting untrusted binaries requires a later process/filesystem contract for workspace reads plus private cache and temporary writes; restricted, remote, or virtual workspaces require another provider.
+The provider trusts its configured server. Its filesystem visibility and process confinement are exactly those of the mounted execution world; LSP adds no independent sandbox policy.
 
 ## Alternatives considered
 
@@ -157,7 +157,7 @@ The local provider trusts its configured server and claims no sandbox confinemen
 
 **Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
 
-**Read through `ctx.fs` or the `read` tool.** This could mix the document with a server index from another filesystem namespace; tool output is also windowed, numbered, and observed. The host-local provider reads unobserved full text beside its subprocess.
+**Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider reads bounded full text directly through the same `ctx.fs` execution world used by its subprocess.
 
 **Keep documents open.** Mirroring edits requires version ownership, all-path `didChange`, HMR recovery, eviction, and stale-state rules. Transient opens avoid that MVP state machine.
 
@@ -180,7 +180,7 @@ The local provider trusts its configured server and claims no sandbox confinemen
 - Synchronization tests pin UTF-16 negotiation and conversion, supported and rejected `textDocumentSync` forms, blocked and failed open writes, balanced transient open/close, close-write failure, and malformed-response rejection.
 - Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden seam deadline, and bounded awaited teardown.
 - Lifecycle tests pin startup single-flight, complete-lifecycle serialization with fresh queued source reads, cross-workspace parallelism, abortable queues, crash replacement without replay, failed-stdin teardown, and quiescent disposal.
-- Host-filesystem tests pin session-cwd requirements, relative and absolute source containment through symlinks, document validation, file/non-file URI rendering, unformatted source, and no `fs/observed` event.
+- Filesystem-host tests pin session-cwd requirements, provider-owned containment and URI rendering, bounded document reads, unformatted source, and no `fs/observed` event.
 - A keyless pinned TypeScript real-server e2e exercises all four operations; runnable configuration uses the same explicit provider mapping.
 - Snapshots cover model-visible schema, prompt, results, and omissions; a built-artifact smoke test covers framing and cleanup.
 - Package and architecture docs cover configuration, security boundaries, and search/read guidance; the new `packages/lsp/` group is added to the AGENTS.md repository-layout block, the packages/README.md group table, and architecture.md in the same change.
@@ -195,4 +195,4 @@ Extension ownership is exclusive within one runtime. Two providers cannot both c
 
 UTF-16 cursor columns are exact for the protocol but difficult for a model to count around non-BMP characters. Invalid or off-symbol positions may produce empty results, so error text and prompt examples must explain the coordinate convention without encouraging broad LSP use.
 
-Direct Node access aligns the query snapshot with the server index but bypasses `ctx.fs` and its policy. Canonical containment rejects source files outside the workspace; a trusted server may still read the workspace and use caches. The first implementation therefore requires trusted host-local deployment and provides no sandbox guarantee.
+The paired filesystem/subprocess providers align the query snapshot with the server index but do not make a trusted language server safe. Canonical containment rejects query sources outside the workspace; the server itself receives the execution world's configured authority and may read other paths or use caches.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index 256b293f21..b411a2456e 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: LSP 能力 seam 与面向模型的查询工具
+# Agent Note: LSP 能力服务边界与面向模型的查询工具
 
 Status: implemented
 
@@ -14,7 +14,7 @@ harness 已具备文本搜索与文件读取能力，但二者都无法识别程
 
 ## 决策
 
-将 LSP 建成由三个包组成的能力 seam，其中包含一个只读模型工具和一个通用本地提供方实现：
+将 LSP 建成由三个包（package）组成的能力服务边界，其中包含一个只读模型工具和一个通用本地提供方实现：
 
 1. `packages/lsp/lsp` 下的 `@deepseek-ai/dsh-lsp` 负责 `ctx.lsp`、提供方注册与选择、标准化请求与结果、执行控制，以及结构化 LSP 错误。
 2. `packages/lsp/lsp-local` 下的 `@deepseek-ai/dsh-lsp-local` 将配置的 stdio 语言服务器适配到该服务边界。一个插件实例接收具名服务器表，并为每组命令及扩展名到语言 id 的映射注册一个隔离的提供方。
@@ -79,7 +79,7 @@ interface LspService {
 
 映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方解析后的工作区根目录，使消费方依据同一规范化根目录相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
 
-`dsh-lsp-local` 负责主机文件、服务器配置、JSON-RPC、进程与临时文档状态和协议转换；它依赖 `dsh-lsp` 与 Node API，不依赖 `dsh-fs`。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
+`dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
 ## 面向模型的契约
 
@@ -98,9 +98,9 @@ interface LspToolInput {
 
 工具必须从会话 `header.cwd` 取得 `workspaceRoot`，没有后备值；缺失时在查询或启动前以 `LSP_WORKSPACE_REQUIRED` 失败。本地提供方基于根目录解析相对路径并直接接受绝对路径；两种路径都会进行规范化，如果目标位于规范工作区外，则在启动前拒绝。
 
-位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径，在工作区外转换为绝对路径；其他 URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并将每个完整渲染结果（包括截断元数据）限制在该字符数内。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
+位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径，在工作区外转换为绝对路径；其他 URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并限制每个完整渲染结果，其中包括截断元数据。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
 
-与传输方式无关的展示器使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`，`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character，跟随位置聚焦输入行，标题保留完整光标；展示器仍为纯函数。
+与传输方式无关的展示器使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`，`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character，跟随位置聚焦输入行，标题保留完整光标；展示保持纯函数。
 
 ## 超时归属
 
@@ -112,26 +112,26 @@ interface LspToolInput {
 
 ## 工作区、文件系统与文档同步
 
-`dsh-lsp-local` 通过 Node API 在子进程所在的主机命名空间中规范化并读取文件。它拒绝缺失、非普通、非 UTF-8、超大或规范路径越出工作区的源文件，并在校验与读取期间保持同一个 `O_NOFOLLOW | O_NONBLOCK` 句柄，因此没有写入方的 FIFO 不会在普通文件校验前造成阻塞。它在每项文件系统操作前后检查调用方是否取消。它不使用 `ctx.fs` 或发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
+`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它在每项提供方操作前后检查调用方是否取消。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
 
 `read` 工具的输出带窗口与行号，进入 transcript（文本记录）且已被观察，不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方，并排除非本地提供方。
 
 本地提供方对每次查询都采用兼容优先的临时打开流程。它接受旧式 `textDocumentSync` 的 `Full` 或 `Incremental`，也接受设置了 `openClose: true` 的选项；同步能力缺失、为 `None` 或明确不兼容时，在 `didOpen` 前以不支持错误失败。
 
-1. 规范化并校验主机路径，再使用 Node 文件系统 API 读取当前源文件。
+1. 通过 `ctx.fs` 解析源文件并检查其位于工作区内，再通过同一提供方对当前文本进行有界读取。
 2. 发送 `textDocument/didOpen`，其中包含版本 `1`、完整文本和配置的语言 id。该写入仍可取消；写入失败或遭取消会使实例失效，并等待有界进程终止完成，池才能复用它。
 3. 发送所请求的 `textDocument/definition`、`textDocument/references`、`textDocument/implementation` 或 `textDocument/hover` 请求。
 4. 如果 `didOpen` 成功，则在请求完成或取消后于 `finally` 中尝试发送 `textDocument/didClose`。关闭写入失败不会覆盖已经确定的结果或错误，但会使实例失效，并等待有界进程终止完成。
 
 每次调用后都关闭文档，因此第一版不需要 `didChange`、`didSave`、内容缓存、变更监听器或文档 LRU。每个工作区的提供方队列可取消，并串行执行源文件读取、打开、查询和关闭的完整生命周期，因此等待中的查询只在轮到它时才读取当前字节；实例也会串行执行协议生命周期。不同工作区可以并行。服务器工作区索引仍负责从源文件跳转到的已关闭文件。
 
-规范工作区 `realpath` 必须是目录，并用于进程 cwd、`rootUri`、唯一的 `workspaceFolders` 条目和进程池 identity；符号链接别名因此共享实例。结果位置可以在工作区外，但外部路径不能成为查询源。远程、虚拟或独立沙箱化文件系统需要另一种提供方。
+规范工作区目标必须是目录。其目标键提供进程池 identity，进程路径提供 cwd，归提供方所有的 `file:` URI 则提供 `rootUri` 和唯一的 `workspaceFolders` 条目；文件系统提供方将别名解析为同一键时，它们共享实例。结果位置可以在工作区外，但外部路径不能成为查询源。无法与挂载的子进程提供方共享路径的文件系统属于组合错误，不是另建 LSP 包的理由。
 
 ## 本地服务器生命周期与协议行为
 
-`dsh-lsp-local` 按 `(provider id, canonical workspace realpath)` 懒启动一个服务器，并通过 single-flight 合并启动。插件加载时，它在清除凭据并应用环境变量覆盖后解析可执行文件；命令不可用时在注册前失败。服务器进程的启动保持懒执行（首次查询时才拉起），且不经过 shell。`maxMessageBytes` 默认值为 `16_000_000`，`maxStderrBytes` 默认值为 `1_000_000`，`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放；后续查询可以替换进程。每次查询最多启动一个进程，因此 MVP 不设置跨请求重启计数器。
+`dsh-lsp-local` 按 `(provider id, canonical workspace target)` 懒启动一个服务器，并通过 single-flight 合并启动。插件加载时，它使用已配置的环境调用 `ctx.subprocess.resolveExecutable()`；命令不可用时在注册前失败。首次查询通过原始协议管道启动服务器，不经过 shell，并收集有界的 stderr 尾部。`maxMessageBytes` 默认值为 `16_000_000`，`maxStderrBytes` 默认值为 `1_000_000`，`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放；后续查询可以替换进程。每次查询最多启动一个进程，因此 MVP 不设置跨请求重启计数器。
 
-初始化声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及 definition 与 implementation 的 `linkSupport: true`，但不支持动态注册。服务器返回的操作能力与同步能力均为真源。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值均属于协议错误。配置可以提供初始化选项和 `workspace/configuration` 响应，但客户端拒绝 `workspace/applyEdit`，绝不执行命令或编辑。
+初始化使用 `processId: null`，因为客户端与服务器可能位于不同的进程命名空间。它声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及 definition 与 implementation 的 `linkSupport: true`，但不支持动态注册。服务器返回的操作与同步能力均为真源。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值均属于协议错误。配置可以提供初始化选项和 `workspace/configuration` 响应，但客户端拒绝 `workspace/applyEdit`，绝不执行命令或编辑。
 
 导航结果直接映射 `Location`，并将 `LocationLink` 的 `targetUri` 与 `targetSelectionRange` 映射为统一位置。位置必须是非负整数。`hover` 归一化只接受有效的 `MarkupContent` 和 `MarkedString` 结构，保留字符串值，把带语言标签的值渲染为围栏代码块，并以一个空行连接数组。面向模型的工具在渲染后应用 `maxResultChars`。
 
@@ -143,7 +143,7 @@ interface LspToolInput {
 
 诊断需要独立的新鲜度、累积与 transcript 规则。重命名、代码操作和格式化等变更能力需要单独工具，并集成预览、权限和写入策略。
 
-本地提供方信任配置的服务器，不声称具备沙箱隔离。支持不受信任的二进制文件需要后续补充允许读取工作区，并执行私有缓存写入与临时写入的进程／文件系统契约；受限、远程或虚拟工作区需要另一种提供方。
+提供方信任配置的服务器。其文件系统可见性与进程隔离完全取决于挂载的执行环境；LSP 不增加独立的沙箱策略。
 
 ## 备选方案
 
@@ -155,9 +155,9 @@ interface LspToolInput {
 
 **公开 `resolve(request)` / `query(spec)`。** 没有需要填充默认值的字段时，resolve 只会暴露提供方选择，而公开 spec 可能活过提供方释放或替换。单一操作让选择与调用共用注册生命周期。
 
-**将信号包装为服务边界专用的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
+**将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
 
-**通过 `ctx.fs` 或 `read` 工具读取。** 这可能把文档与另一文件系统命名空间中的服务器索引混合；工具输出还带窗口、行号且已被观察。host-local 提供方在子进程旁读取未观察的完整文本。
+**通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境读取有界的完整文本。
 
 **保持文档打开。** 镜像编辑需要版本归属、覆盖所有路径的 `didChange`、HMR 恢复、淘汰和陈旧状态规则。临时打开避免在 MVP 引入这套状态机。
 
@@ -180,14 +180,14 @@ interface LspToolInput {
 - 同步测试固定 UTF-16 协商与转换、受支持和被拒绝的 `textDocumentSync` 形式、打开写入阻塞与失败、配对的临时打开/关闭、关闭写入失败和错误响应拒绝。
 - 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、服务边界无隐藏截止时间，以及受限且等待完成的清理。
 - 生命周期测试固定启动 single-flight、完整生命周期串行化及排队查询读取最新源文件、跨工作区并行、可取消队列、崩溃后不重放的替换、stdin 失败后的进程拆除，以及释放后完全停稳。
-- 主机文件系统测试固定 session cwd 要求、符号链接下相对与绝对源路径的规范 containment、文档校验、file/non-file URI 渲染、无格式源文本和不发送 `fs/observed`。
+- 文件系统宿主测试固定 session cwd 要求、提供方自有的 containment 与 URI 渲染、有界文档读取、无格式源文本和不发送 `fs/observed`。
 - 无密钥且固定版本的 TypeScript 真实服务器 e2e 覆盖四种操作；可运行配置使用同一项显式提供方映射。
 - 快照覆盖模型可见 schema、提示词、结果和省略提示；构建产物冒烟测试覆盖分帧与清理。
 - 包与架构文档覆盖配置、安全边界和搜索/读取指导；同一改动中，新的 `packages/lsp/` 包组要加入 AGENTS.md 的仓库布局块、packages/README.md 的分组表和 architecture.md。
 
 ## 影响
 
-各语言服务器对方法支持、能力解释和索引就绪时机的处理不同；LSP 没有统一的「索引完成」信号。不具备兼容临时打开同步能力的服务器不受支持，即使它能查询已关闭文档。受支持的服务器仍可能返回空结果或不完整结果，因此工具不承诺跨服务器完整性。固定的 TypeScript e2e 只建立一条兼容性基线，不代表跨语言承诺。
+各语言服务器对方法支持、能力解释和索引就绪时机的处理不同；LSP 没有统一的“索引完成”信号。无法声明兼容临时打开同步能力的服务器不受支持，即使它能查询已关闭文档。受支持的服务器仍可能返回空结果或不完整结果，因此工具不承诺跨服务器完整性。固定的 TypeScript e2e 只建立一条兼容性基线，不代表跨语言承诺。
 
 临时打开会重复解析并产生通知。实例内串行会增加并发 agent 的延迟，长期运行的工作区进程则持续占用内存直到释放。
 
@@ -195,4 +195,4 @@ interface LspToolInput {
 
 UTF-16 光标列与协议完全一致，但模型难以在包含非 BMP 字符的文本中准确计数。无效位置或不在符号上的位置可能返回空结果，因此错误文本和提示词示例必须说明坐标约定，同时避免鼓励模型广泛使用 LSP。
 
-直接访问 Node 文件系统会对齐查询快照与服务器索引，但绕过 `ctx.fs` 及其策略。规范路径 containment 会拒绝工作区外的源文件；受信任的服务器仍可读取工作区并使用缓存。因此，第一版要求受信任的 host-local 部署，不提供沙箱保证。
+配对的文件系统／子进程提供方会对齐查询快照与服务器索引，但不会因此使受信任的语言服务器变得安全。规范 containment 会拒绝工作区外的查询源；服务器本身获得执行环境所配置的权限，仍可读取其他路径或使用缓存。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
index daa727ccb0..469c3f9a24 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
-2026-07-26-subprocess-consumer-migration.md: 477dffc2271db08b8986b34645067b247ad7ace7
-2026-07-26-subprocess-consumer-migration.zh.md: 8e0e377fc3fe00ff452803fe7fe5f4115003f937
+2026-07-26-subprocess-consumer-migration.md: abc7c8504595641b2b821df5ddbd4645c3a15336
+2026-07-26-subprocess-consumer-migration.zh.md: 500dcfe36f63315156b1a3cc48670eaf1c204b20
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
index 477dffc227..abc7c85045 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-26-subprocess-consumer-migration.zh.md)
 
 ## Problem
 
-The [subprocess seam](2026-07-26-subprocess-seam.md) shipped shaped for exactly one consumer family: batch-collected stdout/stderr, batch stdin, a single escalating `kill()`. That was deliberate scope control, and its own note records "migrate the other spawn sites" as rejected-for-now. Review on the introducing PR reversed that deferral: the stacked follow-up should reshape the interface toward Node's API and move the remaining process-running places onto the service. The remaining spawners each carried a private copy of some slice of the same mechanics — lsp-local had its own detached-tree signalling (POSIX group + Windows taskkill + liveness polling), subagent-subprocess had the dispose ladder and its own scrub, and mcp-client, pty-local, the SDK helper, and the TUI Git probe each carried another credential scrub — and none of it was swappable or centrally testable.
+The [subprocess seam](2026-07-26-subprocess-seam.md) shipped shaped for exactly one consumer family: batch-collected stdout/stderr, batch stdin, a single escalating `kill()`. That was deliberate scope control, and its own note records "migrate the other spawn sites" as rejected-for-now. Review on the introducing PR reversed that deferral: the stacked follow-up should reshape the interface toward Node's API and move the remaining process-running places onto the service. The remaining spawners each carried a private copy of some slice of the same mechanics — lsp-local had its own detached-tree signalling (POSIX group + Windows taskkill + liveness polling), subagent-subprocess had the dispose ladder and its own scrub, mcp-client and pty-local and the SDK helper each had a third/fourth/fifth copy of the credential scrub — and none of it was swappable or centrally testable.
 
 ## Decision
 
@@ -15,24 +15,24 @@ The seam's vocabulary is now Node-shaped, and every spawner that can ride the se
 - **Per-stream stdio dispositions** on `SubprocessSpawnSpec`: `'pipe'` (the raw `Readable`/`Writable`, for consumer-owned protocol framing), `'inherit'` (diagnostics to the parent's stream), and collect mode `{ maxBytes, spill? }` — the original bounded tail-keep shape, with the spill file now optional so a diagnostic tail (a language server's stderr) buffers without touching disk. stdin is `'ignore'`, `'pipe'`, or `{ data }` (write-and-close batch).
 - **`SubprocessOutcome` carries exit facts only** (Node's close-event vocabulary); collected output stays readable through `handle.collected` after settlement (spill fds seal at the settle boundary), so batch and streaming callers share one access path and nothing is copied into the outcome.
 - **Tree-scoped termination behind one verb**: `terminate()` owns the SIGTERM→grace→SIGKILL escalation (serves the spec's abort signal too, and is a no-op once the tree is gone) — the handle exposes no single-signal `kill(signal?)`, so a consumer cannot skip the grace window; `waitForExit()` polls tree liveness (POSIX group probe; direct-child boundary on Windows); Windows tree termination (`taskkill /T`, injectable) moved in from lsp-local, so tree semantics are platform-correct for every consumer. (The stdin-EOF-first dispose ladder initially absorbed from `subagent-subprocess` later moved back out to its one consumer — see the [ladder-ownership Agent Note](2026-07-27-dispose-ladder-to-consumer.md).)
-- **One scrub definition**: `scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` live on the seam, and credential-shaped names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, case-insensitively. Spawners that cannot route the spawn itself through the service — pty-local (node-pty owns the fork), mcp-client (the MCP SDK owns the transport spawn), and the TUI's synchronous Git branch probe — import the function, so environment policy is single-sourced even where process ownership is not. The SDK helper's `scrubEnvironment()` defaults through the function and applies the exported pattern when its caller supplies an explicit environment; the pattern remains public for this production consumer.
+- **One scrub definition**: `scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` live on the seam. Ordinary and terminal local spawns apply it inside `dsh-subprocess-local`; mcp-client still imports it because the MCP SDK owns that transport spawn, and the SDK helper's `scrubEnvironment()` defaults through it as well.
 
-Migrations landed with the reshape: **bash-local/bash-sandbox** (collect modes + batch stdin; the bash `kill()` maps to `terminate()` so `task_kill` keeps escalation semantics), **lsp-local** (piped protocol streams + a no-spill collected stderr tail; `LspConnection` takes the seam's spawn function; its private tree-op helpers deleted), **subagent-acp** (piped ndjson streams + inherited stderr; spawn failure surfaces through `done` rejection into the same startup race; disposal is the backend-owned `disposeAcpChild` ladder over the seam's verbs, with the plugin's configured graces). **`dsh-subagent-subprocess` is deleted** — the dispose ladder and scrub are the seam's; the unused isolated-config-dir helper died with it (no consumer existed).
+Migrations landed with the reshape: **bash-local/bash-sandbox** (collect modes + batch stdin; the bash `kill()` maps to `terminate()` so `task_kill` keeps escalation semantics), **lsp-local** (piped protocol streams + a no-spill collected stderr tail; `LspConnection` takes the seam's spawn function; its private tree-op helpers deleted), **subagent-acp** (piped ndjson streams + inherited stderr; spawn failure surfaces through `done` rejection into the same startup race; disposal is the backend-owned `disposeAcpChild` ladder over the seam's verbs, with the plugin's configured graces), and **pty-local** through the later [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) (`node-pty` allocation and process inspection sit behind `spawnTerminal()`, while readiness and terminal policy remain in the consumer). **`dsh-subagent-subprocess` is deleted** — the dispose ladder and scrub are the seam's; the unused isolated-config-dir helper died with it (no consumer existed).
 
 Compositions mounting lsp-local or subagent-acp now load `dsh-subprocess-local` (the plugins inject `'subprocess'`); the acp/lsp test fixtures gained the row.
 
 ## Alternatives considered
 
-**Keep the batch-only seam and let stream consumers stay bespoke.** The introducing note's position, rejected by review: it leaves three private copies of tree signalling and six of the scrub, and any future runner (containerized executor, remote process host) would have to pick which private copy to fork. The Node-shaped dispositions cover all three observed stream shapes without widening the outcome type or buffering piped streams.
+**Keep the batch-only seam and let stream consumers stay bespoke.** The introducing note's position, rejected by review: it leaves three private copies of tree signalling and five of the scrub, and any future runner (containerized executor, remote process host) would have to pick which private copy to fork. The Node-shaped dispositions cover all three observed stream shapes without widening the outcome type or buffering piped streams.
 
 **A single `stdio: 'pipe' | 'inherit' | 'collect'` mode for all three streams at once.** Rejected: real consumers mix modes per stream (lsp: pipe/pipe/collect; acp: pipe/pipe/inherit; bash: data/collect/collect). Per-stream dispositions are exactly Node's shape and avoid a second spawn call for the mixed cases.
 
-**Migrate pty-local and mcp-client spawns too.** Rejected on ownership grounds, not scope: node-pty's `fork()` allocates the terminal itself, and the MCP SDK's `StdioClientTransport` spawns internally — neither call site is ours to route. They adopt the shared scrub (the part that is policy), and their READMEs say why the spawn stays put.
+**Keep pty-local and mcp-client spawns outside the service.** The MCP SDK still owns its transport spawn. PTY allocation is different: the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) moves `node-pty` behind one deep terminal primitive, resolving the ownership objection without pretending an ordinary piped spawn can provide terminal semantics.
 
-**Migrate the test-support launchers (acp-snapshot, loader-smoke), the SDK package-manager runner, and the TUI Git probe.** Rejected: the support packages are deliberately dependency-light test infrastructure that must not depend on product seams; the SDK wizard's `stdio: 'inherit'`-with-redirect semantics plus its out-of-composition lifecycle (no cordis context at all) make the service a poor fit; and the TUI probe is synchronous. The production callers share the scrub instead.
+**Migrate the test-support launchers (acp-snapshot, loader-smoke) and the SDK package-manager runner.** Rejected: the support packages are deliberately dependency-light test infrastructure that must not depend on product seams, and the SDK wizard's `stdio: 'inherit'`-with-redirect semantics plus its out-of-composition lifecycle (no cordis context at all) make the service a poor fit; it shares the scrub instead.
 
 ## Consequences
 
-Bought: one implementation of tree signalling, escalation, bounded collection, and the scrub, tested once in `dsh-subprocess-local`'s suites (including injected-platform Windows coverage that lsp-local's private copy never had); lsp-local and subagent-acp shed their process plumbing and their children now survive plugin reloads and die with composition teardown like bash's; a whole package (`dsh-subagent-subprocess`) is gone. The seam README's "one consumer family" limitation is retired.
+Bought: one implementation of tree signalling, escalation, bounded collection, terminal process mechanics, and the scrub, tested once in `dsh-subprocess-local`'s suites (including injected-platform Windows coverage that lsp-local's private copy never had); lsp-local, pty-local, and subagent-acp shed provider-specific process plumbing and their children die with composition teardown like bash's; a whole package (`dsh-subagent-subprocess`) is gone. The seam README's "one consumer family" limitation is retired.
 
-Cost: the seam is wider — three stdio modes and the terminate/waitForExit/dispose lifecycle surface instead of one mode and one verb — so a future backend implements more surface; the compositions for lsp-local/subagent-acp each carry the subprocess row now; and `SubprocessOutcome` no longer carries output, a breaking shape change inside the still-unreleased stack (the PR2 layer was updated in place rather than shimmed, per the pre-release stance). pty-local/mcp-client/SDK/TUI/test-support spawns remain outside the service by ownership or execution shape, with the scrub as the shared floor and its pattern intentionally exported for explicit-environment consumers.
+Cost: the seam is wider — execution-world coordinates, executable lookup, three stdio modes, process-tree lifecycle, and one terminal primitive — so a future backend implements more surface; the compositions for lsp-local, pty-local, and subagent-acp each carry the subprocess row; and `SubprocessOutcome` no longer carries output, a breaking shape change inside the still-unreleased stack. MCP/SDK/test-support spawns remain outside the service by ownership, with the scrub as the shared floor.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
index 8e0e377fc3..500dcfe36f 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 子进程 seam 转向 Node 形状，所有具备条件的 spawn 调用点一并迁入
+# Agent Note: 进程 seam 转向 Node 形状，所有具备条件的 spawn 调用点一并迁入
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[子进程 seam](2026-07-26-subprocess-seam.md) 交付时恰好只为一个消费方家族塑形：批量收集的 stdout/stderr、批量 stdin、单一的升级式 `kill()`。那是有意的范围控制，其自身的 Agent Note 也把「迁移其余 spawn 调用点」记为暂缓否决项。引入该 seam 的 PR（Pull Request）上的评审推翻了这一暂缓决定：堆叠其上的后续变更应当把接口向 Node 的 API 方向重塑，并把其余运行进程之处迁到该服务上。其余各 spawn 调用点此前各自持有同一套机制中某个切片的私有副本——lsp-local 自带 detached 进程树信号发送（POSIX 进程组 + Windows taskkill + 存活轮询），subagent-subprocess 自带 dispose（资源释放）阶梯和自己的凭据清除，mcp-client、pty-local、SDK helper 与 TUI Git 探测则各自持有另一份凭据清除——而这一切既不可替换，也无法集中测试。
+[进程 seam](2026-07-26-subprocess-seam.md) 交付时恰好只为一个消费方家族塑形：批量收集的 stdout/stderr、批量 stdin、单一的升级式 `kill()`。那是有意的范围控制，其自身的 Agent Note 也把「迁移其余 spawn 调用点」记为暂缓否决项。引入该 seam 的 PR（Pull Request）上的评审推翻了这一暂缓决定：堆叠其上的后续变更应当把接口向 Node 的 API 方向重塑，并把其余运行进程之处迁到该服务上。其余各 spawn 调用点此前各自持有同一套机制中某个切片的私有副本——lsp-local 自带 detached 进程树信号发送（POSIX 进程组 + Windows taskkill + 存活轮询），subagent-subprocess 自带 dispose（资源释放）阶梯和自己的凭据清除，mcp-client、pty-local 与 SDK helper 则各自持有凭据清除的第三、第四、第五份副本——而这一切既不可替换，也无法集中测试。
 
 ## 决策
 
@@ -15,24 +15,24 @@ Status: implemented
 - **按流划分的 stdio 处置方式（disposition）**，位于 `SubprocessSpawnSpec` 上：`'pipe'`（原始的 `Readable`/`Writable`，供消费方自有的协议分帧使用）、`'inherit'`（诊断输出直通父进程的流），以及收集模式（collect）`{ maxBytes, spill? }`——即最初的有界尾部保留形状，只是 spill 文件改为可选，使诊断尾部（例如语言服务器的 stderr）无需落盘即可缓冲。stdin 则为 `'ignore'`、`'pipe'` 或 `{ data }`（写完即关闭的批量形式）。
 - **`SubprocessOutcome` 只承载退出事实**（Node close 事件的词汇）；收集到的输出在结算后仍可经 `handle.collected` 读取（spill 文件描述符在结算边界封存），因此批量与流式调用方共用一条访问路径，也没有任何内容被复制进这份结果。
 - **以进程树为范围的终止，集中在一个动词后面**：`terminate()` 拥有 SIGTERM→宽限期→SIGKILL 升级（也承接 spec 的 abort 信号，进程树消亡后为空操作）——句柄不暴露单信号的 `kill(signal?)`，因此消费方无法跳过宽限窗口；`waitForExit()` 轮询进程树存活状态（POSIX 进程组探测；Windows 上以直接子进程为界）。Windows 进程树终止（`taskkill /T`，可注入）自 lsp-local 迁入，因此每个消费方拿到的进程树语义在各平台上都正确。（最初从 `subagent-subprocess` 吸收的以 stdin EOF 打头的 dispose 阶梯，后来又移回其唯一消费方——见[阶梯归属 Agent Note](2026-07-27-dispose-ladder-to-consumer.md)。）
-- **凭据清除只有一份定义**：`scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` 定义在 seam 上，且凭据形状的名称不区分大小写地包含 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN`。无法把 spawn 本身路由到该服务的调用点——pty-local（node-pty 拥有 fork）、mcp-client（MCP SDK 拥有传输层的 spawn）与 TUI 的同步 Git 分支探测——改为导入该函数，因此即便进程所有权无法统一，环境策略仍是单一来源。SDK helper 的 `scrubEnvironment()` 默认委托给该函数，并在调用方显式传入环境时应用导出的正则；该正则因此生产消费方而保持公开。
+- **凭据清除只有一份定义**：`scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` 定义在 seam 上。普通本地 spawn 与终端本地 spawn 都在 `dsh-subprocess-local` 内部应用该定义；mcp-client 仍需导入它，因为 MCP SDK 拥有该传输层 spawn，SDK helper 的 `scrubEnvironment()` 默认同样委托给它。
 
-各项迁移随这次重塑一并落地：**bash-local/bash-sandbox**（收集模式 + 批量 stdin；bash 的 `kill()` 映射到 `terminate()`，因此 `task_kill` 保有升级语义），**lsp-local**（管道化的协议流 + 无 spill 的 stderr 收集尾部；`LspConnection` 改为接收 seam 的 spawn 函数；其私有的进程树操作辅助函数已删除），**subagent-acp**（管道化的 ndjson 流 + inherit 的 stderr；spawn 失败经 `done` 的 reject 汇入同一个启动竞态；dispose 是后端自有的 `disposeAcpChild` 阶梯，经由 seam 的动词运行，携带插件所配置的宽限期）。**`dsh-subagent-subprocess` 已删除**——dispose 阶梯与凭据清除归 seam 所有；无人使用的隔离配置目录辅助函数随之消亡（其消费方本就不存在）。
+各项迁移随这次重塑一并落地：**bash-local/bash-sandbox**（收集模式 + 批量 stdin；bash 的 `kill()` 映射到 `terminate()`，因此 `task_kill` 保有升级语义），**lsp-local**（管道化的协议流 + 无 spill 的 stderr 收集尾部；`LspConnection` 改为接收 seam 的 spawn 函数；其私有的进程树操作辅助函数已删除），**subagent-acp**（管道化的 ndjson 流 + inherit 的 stderr；spawn 失败经 `done` 的 reject 汇入同一个启动竞态；dispose 是后端自有的 `disposeAcpChild` 阶梯，经由 seam 的动词运行，携带插件所配置的宽限期），以及后来通过[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)迁移的 **pty-local**（`node-pty` 分配与进程检查位于 `spawnTerminal()` 之后，就绪状态和终端策略仍归消费方所有）。**`dsh-subagent-subprocess` 已删除**——dispose 阶梯与凭据清除归 seam 所有；无人使用的隔离配置目录辅助函数随之消亡（其消费方本就不存在）。
 
 挂载 lsp-local 或 subagent-acp 的组合如今都加载 `dsh-subprocess-local`（这两个插件注入 `'subprocess'`）；acp/lsp 测试 fixture（测试前置数据）补上了这一行组合配置。
 
 ## 曾考虑的替代方案
 
-**保持只支持批量的 seam，让流式消费方继续各自为政。**这正是引入该 seam 的 Agent Note 当初的立场，评审将其否决：这样会留下三份进程树信号发送的私有副本和六份凭据清除的私有副本，而未来任何运行器（容器化执行器、远程进程宿主）都得挑选去 fork 哪一份私有副本。Node 形状的处置方式覆盖已观察到的全部三种流形状，既不拓宽结果类型，也不缓冲管道化的流。
+**保持只支持批量的 seam，让流式消费方继续各自为政。**这正是引入该 seam 的 Agent Note 当初的立场，评审将其否决：这样会留下三份进程树信号发送的私有副本和五份凭据清除的私有副本，而未来任何运行器（容器化执行器、远程进程宿主）都得挑选去 fork 哪一份私有副本。Node 形状的处置方式覆盖已观察到的全部三种流形状，既不拓宽结果类型，也不缓冲管道化的流。
 
 **用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式一次性统辖全部三条流。**否决：真实消费方按流混用模式（lsp：pipe/pipe/collect；acp：pipe/pipe/inherit；bash：data/collect/collect）。按流划分的处置方式恰好就是 Node 的形状，也免去了混用场景的第二个 spawn 调用。
 
-**把 pty-local 与 mcp-client 的 spawn 也一并迁移。**基于所有权而非范围否决：node-pty 的 `fork()` 自行分配终端，MCP SDK 的 `StdioClientTransport` 在内部完成 spawn——这两处调用点都不归我们路由。它们采纳共享的凭据清除（那正是属于策略的部分），并在各自的 README 中说明 spawn 为何留在原地。
+**让 pty-local 与 mcp-client 的 spawn 留在服务之外。**MCP SDK 仍拥有其传输层 spawn。PTY 分配则不同：[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)把 `node-pty` 放到一个深层终端原语之后，既解决所有权异议，也不假装普通管道化 spawn 能够提供终端语义。
 
-**迁移 test-support 启动器（acp-snapshot、loader-smoke）、SDK package-manager 运行器与 TUI Git 探测。**否决：support 各包是刻意保持轻依赖的测试基础设施，不得依赖产品 seam；SDK 向导那套附带重定向的 `stdio: 'inherit'` 语义，加上其完全脱离组合的生命周期（根本没有 cordis 上下文），使该服务并不合用；TUI 探测则是同步调用。这些生产调用点改为共享凭据清除。
+**迁移 test-support 启动器（acp-snapshot、loader-smoke）与 SDK package-manager 运行器。**否决：support 各包（package）是刻意保持轻依赖的测试基础设施，不得依赖产品 seam；而 SDK 向导那套附带重定向的 `stdio: 'inherit'` 语义，加上其完全脱离组合的生命周期（根本没有 cordis 上下文），使该服务并不合用；它改为共享凭据清除。
 
 ## 后果
 
-换来的是：进程树信号发送、升级、有界收集与凭据清除各自只剩一份实现，且只在 `dsh-subprocess-local` 的测试套件中测试一次（其中包括 lsp-local 的私有副本从未有过的、以注入平台方式实现的 Windows 覆盖）；lsp-local 与 subagent-acp 卸下了自己的进程管道，其子进程如今像 bash 的一样，在插件重载后存活、随组合拆除而终止；一个完整的包（`dsh-subagent-subprocess`）就此消失。seam README 中「只有一个消费方家族」的限制说明也随之退役。
+换来的是：进程树信号发送、升级、有界收集、终端进程机制与凭据清除各自只剩一份实现，且只在 `dsh-subprocess-local` 的测试套件中测试一次（其中包括 lsp-local 的私有副本从未有过的、以注入平台方式实现的 Windows 覆盖）；lsp-local、pty-local 与 subagent-acp 卸下了提供方专用的进程管道，其子进程如今像 bash 的一样随组合拆除而终止；一个完整的包（`dsh-subagent-subprocess`）就此消失。seam README 中「只有一个消费方家族」的限制说明也随之退役。
 
-代价是：这道 seam 变宽了（stdio 模式从一种变为三种、生命周期接口面从一个动词扩展为 terminate/waitForExit/dispose 这一组），未来的后端因此要实现更宽的接口面；lsp-local/subagent-acp 的各组合如今都多出 subprocess 这一行组合配置；`SubprocessOutcome` 也不再承载输出，这是仍未发布的堆叠变更内部的一次破坏性形状变更（依照预发布立场，PR2 那一层被就地更新，而非加 shim）。pty-local/mcp-client/SDK/TUI/test-support 的 spawn 因所有权归属或执行形状留在该服务之外，以凭据清除作为共底线，且为显式环境的生产消费方有意保持该正则导出。
+代价是：这道 seam 变宽了，涵盖执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语，未来的后端因此要实现更宽的表面；lsp-local、pty-local 与 subagent-acp 的各组合如今都多出 subprocess 这一行组合配置；`SubprocessOutcome` 也不再承载输出，这是仍未发布的堆叠变更内部的一次破坏性形状变更。MCP／SDK／test-support 的 spawn 因所有权归属留在该服务之外，以凭据清除作为共享底线。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 1a918fc62c..94711572d6 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: ad2f8522be51ba16b0df155aeb334a88f493890f
-2026-07-26-subprocess-seam.zh.md: 575c02e346531824ef409ddc6155aa2b59ce4e63
+2026-07-26-subprocess-seam.md: d5dee7361e48f18f3147444b2db74da3dd1c1161
+2026-07-26-subprocess-seam.zh.md: 884c572dc65c0fbf240f7e4e3b0387038e21f5ad
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index ad2f8522be..d5dee7361e 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess` with one method, `spawn(spec): SubprocessHandle`, and the shared vocabulary: the fully-explicit `SubprocessSpawnSpec` (argv, cwd, per-stream stdio dispositions, grace — no defaults; deployment-varying knobs stay with the calling seam's config, per the `dsh-bash` request/spec template and the no-hidden-defaults rule), `SubprocessHandle` with non-consuming offset-based readers, `SubprocessOutcome` with deliberately no timeout/cancel classification, and the shared scrub plus `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` types. `argv` is never shell-interpreted. (The [consumer-migration Agent Note](2026-07-26-subprocess-consumer-migration.md) later widened the stdio and termination vocabulary Node-ward.)
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`): detached groups, tail-keep truncation with private bounded spill files, credential scrub with the explicit-env merge after it, group kill escalation, and disposal that kills and joins every still-running managed process. It has no config; every limit arrives on the spec. The terminal `ENV_OVERRIDES` (`TERM=dumb` etc.) did NOT move — that is bash-tool presentation policy and stays in `dsh-bash-local`, merged through the ordinary env channel.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Its vocabulary includes per-stream stdio dispositions, process and terminal handles, exit facts with deliberately no timeout/cancel classification, and the shared scrub plus `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` types. `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, credential scrub with explicit env merged after it, tree cleanup, and disposal that terminates and joins every managed process. It has no config; every limit arrives on the spec. Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
@@ -25,7 +25,7 @@ Background-process lifetime moved from the executor to the subprocess service: t
 
 **Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
 
-**Migrate the repo's other spawn sites (lsp-local, pty-local, subagent-subprocess, sdk package-manager, test-support launchers) onto `ctx.subprocess` in the same change.** Rejected as scope creep with real design risk at this PR's scale: those sites have materially different stream and lifecycle needs — node-pty ownership (pty), LSP framing over long-lived stdio with tree-kill fallbacks (lsp), stdin-EOF-first disposal ladders and no output buffering (subagent transports) — and forcing them under a handle shaped for bounded batch output would either bloat the seam or misfit the consumers. The seam shipped proven against its one real consumer family, per the shape-interfaces-around-current-consumers rule. Review then asked for exactly that follow-up as a stacked PR; the [consumer-migration Agent Note](2026-07-26-subprocess-consumer-migration.md) records the Node-ward reshape and which sites moved (and which stayed, by ownership).
+**Migrate the repo's other spawn sites in the introducing change.** Rejected as scope creep with real design risk at that scale. The later [consumer-migration](2026-07-26-subprocess-consumer-migration.md) and [portable execution-world](2026-07-28-portable-execution-world-consumers.md) decisions reshape the interface around the observed LSP, subagent, PTY, and Code Runtime consumers; SDK and test-support launchers remain outside by ownership.
 
 **Put `run_in_background`/task semantics into the process seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The process seam sits *below* the bash executor, not beside the task registry.
 
@@ -33,6 +33,6 @@ Background-process lifetime moved from the executor to the subprocess service: t
 
 ## Consequences
 
-Bought: "run and manage a process" is a swappable capability with the standard three-package shape (consumer count starts at two: `bash-local`, `bash-sandbox`); a containerized or remote process backend slots in without touching bash semantics; the shared `DSH_*`/output vocabulary has a non-shell home; and background processes survive executor reloads, matching the task registry's lifetime model. The spawn plumbing suite moved wholesale to `dsh-subprocess-local` (argv-based, plus argv-validation and service lifecycle/disposal suites); the executor suite now pins the bash-owned layers (classification, merge, spawn-failure note, service-owned lifetime) against the real service.
+Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; the shared `DSH_*`/output vocabulary has a non-shell home; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
 
 Cost: one more package pair and one more composition row everywhere a bash executor loads — a boot that loads an executor without the subprocess service leaves `ctx.bash` pending on `ctx.subprocess` (standard missing-service behavior). The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages now name the same types; the subprocess seam is the owner and the bash seam documents the re-export. The spawn-failure note became single-delivery through the read path where the old plumbing retained it in the stderr buffer for repeated `readFrom(0)` reads — acceptable because the bash background read path was already a consuming cursor, and the note reaches the one reader that exists.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 575c02e346..884c572dc6 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 子进程服务是 bash 执行器之下的独立 seam（`dsh-subprocess` / `dsh-subprocess-local`）
+# Agent Note: 进程管理器是 bash 执行器之下的独立 seam（`dsh-subprocess` / `dsh-subprocess-local`）
 
 Status: implemented
 
@@ -6,33 +6,33 @@ Status: implemented
 
 ## 问题
 
-`dsh-bash-local` 原先把两项因不同原因而变化的能力捆绑在一起：*运行一条 bash 命令*（命令默认值补全、超时分类、对模型友好的终端环境、bash 工具所渲染的 stdout/stderr 合并）与*运行并管理一个子进程*（detached 进程组、附带 spill 文件的有界尾部保留输出、凭据清除与 `DSH_*` 合并次序、SIGTERM→宽限期→SIGKILL 升级、先终止再等待退出的 dispose（资源释放））。进程这一半（`run.ts`）约占整个包的一半，却没有属于自己的 seam：未来的非 shell 运行器（直接执行 argv 的执行器、worker supervisor）将不得不重新实现这套机制，或者探入 bash 内部；而共享的 `DSH_*`/`CollectedOutput` 词汇则存放在一个名字承诺 shell 语义的包里。这种捆绑还把后台进程的存续期系在执行器的 fiber 上：重载 bash 执行器会杀死每一个存活的后台进程。这一点不同于同级的[任务注册表](2026-07-26-task-registry-seam.md)：后者的注册存续期刻意长于生产方 fiber。
+`dsh-bash-local` 原先把两项因不同原因而变化的能力捆绑在一起：*运行一条 bash 命令*（命令默认值补全、超时分类、对模型友好的终端环境、bash 工具所渲染的 stdout/stderr 合并）与*运行并管理一个子进程*（detached 进程组、附带 spill 文件的有界尾部保留输出、凭据清除与 `DSH_*` 合并次序、SIGTERM→宽限期→SIGKILL 升级、先终止再等待退出的 dispose（资源释放））。进程这一半（`run.ts`）约占整个包（package）的一半，却没有属于自己的 seam：未来的非 shell 运行器（直接执行 argv 的执行器、worker supervisor）将不得不重新实现这套机制，或者探入 bash 内部；而共享的 `DSH_*`/`CollectedOutput` 词汇则存放在一个名字承诺 shell 语义的包里。这种捆绑还把后台进程的存续期系在执行器的 fiber 上：重载 bash 执行器会杀死每一个存活的后台进程。这一点不同于兄弟的[任务注册表](2026-07-26-task-registry-seam.md)：后者的注册存续期刻意长于生产方 fiber。
 
 ## 决策
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`（仅一个方法：`spawn(spec): SubprocessHandle`），以及共享词汇：完全显式的 `SubprocessSpawnSpec`（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期，一律不设默认值；随部署变化的旋钮依照 `dsh-bash` 的 request/spec 模板与无隐藏默认值规则，留在调用方 seam 的配置里）、携带基于偏移量的非消费式读取器的 `SubprocessHandle`、刻意不含超时/取消分类的 `SubprocessOutcome`，以及共享的凭据清除与 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` 类型。`argv` 绝不经过 shell 解释。（[消费方迁移 Agent Note](2026-07-26-subprocess-consumer-migration.md) 其后将 stdio 与终止词汇拓宽为 Node 形状。）
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService`，构建在原 `run.ts` 管道（现为 `spawn.ts`）之上：detached 进程组、带私有有界 spill 文件的尾部保留截断、清除之后合并显式 env 的凭据清除、进程组 kill 升级，以及会终止每个仍在运行的受管进程并等待其退出的 dispose。该实现没有任何配置；每项限制都随 spec 到达。终端相关的 `ENV_OVERRIDES`（`TERM=dumb` 等）并未迁移：那是 bash 工具的呈现策略，留在 `dsh-bash-local` 里，经普通 env 通道合并。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。其词汇包括按流划分的 stdio 处置方式（disposition）、进程与终端句柄、刻意不含超时／取消分类的退出事实，以及共享的凭据清除与 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` 类型。`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查、清除之后合并显式 env 的凭据清除、进程树清理，以及终止每个受管进程并等待其退出的 dispose。该实现没有任何配置；每项限制都随 spec 到达。Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
 如今，每个加载 bash 执行器的组合都同时加载 `@deepseek-ai/dsh-subprocess-local`：CLI（命令行界面）、各示例、Python 捆绑运行时、create-sdk 的 bash 功能资源，以及各内联测试配置。
 
-后台进程的存续期从执行器移到了子进程服务：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（服务的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，服务会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
+后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
 ## 曾考虑的替代方案
 
 **把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
 
-**在同一变更中把仓库其余 spawn 调用点（lsp-local、pty-local、subagent-subprocess、sdk package-manager、test-support 各启动器）迁到 `ctx.subprocess` 上。**在本 PR（Pull Request）的规模下，作为带有真实设计风险的范围蔓延否决。这些调用点在流与生命周期上的需求存在实质差异：node-pty 所有权（pty）、长生命周期 stdio 上的 LSP 分帧加进程树终止回退（lsp）、以 stdin EOF 打头的 dispose 阶梯和完全不缓冲输出（subagent 传输层）。把它们强行纳入一个按有界批量输出塑形的句柄之下，要么会让这道 seam 膨胀，要么会让句柄与消费方错配。依照「接口围绕当前消费方塑形」的规则，该 seam 当时在其唯一真实的消费方家族上得到验证后交付。评审随后恰恰要求以堆叠 PR 的形式完成这项后续工作；[消费方迁移 Agent Note](2026-07-26-subprocess-consumer-migration.md) 记录了向 Node 形状的重塑，以及哪些调用点迁入（哪些因所有权归属而留在原地）。
+**在引入 seam 的同一变更中迁移仓库其余 spawn 调用点。**否决，因为在当时的规模下属于带有真实设计风险的范围蔓延。后续的[消费方迁移](2026-07-26-subprocess-consumer-migration.md)与[可移植执行环境](2026-07-28-portable-execution-world-consumers.md)决策围绕已观察到的 LSP、subagent、PTY 与 Code Runtime 消费方重塑接口；SDK 与 test-support 启动器因所有权归属仍留在服务之外。
 
 **改把 `run_in_background`/任务语义放进进程 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。进程 seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
-**把 `ENV_OVERRIDES`（TERM=dumb、PAGER=cat 等）移入子进程服务。**否决：通用子进程服务不得把终端呈现策略强加给非终端消费方；对环境中凭据形态名称与 `DSH_*` 名称的清除是安全与身份不变式，予以保留，但终端友好性是 bash 工具自己的选择，经 spec 的显式 env 表达，而调用方自己的条目依旧优先。
+**把 `ENV_OVERRIDES`（TERM=dumb、PAGER=cat 等）移入管理器。**否决：通用进程管理器不得把终端呈现策略强加给非终端消费方；对环境中凭据形态名称与 `DSH_*` 名称的清除是安全与身份不变式，予以保留，但终端友好性是 bash 工具自己的选择，经 spec 的显式 env 表达，而调用方自己的条目依旧优先。
 
 ## 后果
 
-换来的是：「运行并管理一个进程」成为一项具备标准三包形态的可替换能力（消费方起步就有两个：`bash-local`、`bash-sandbox`）；容器化或远程进程后端可以直接接入，而不触碰 bash 语义；共享的 `DSH_*`/输出词汇有了一个不带 shell 含义的归属；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。spawn 管道测试套件整体迁至 `dsh-subprocess-local`（现以 argv 为基础，外加 argv 校验与服务生命周期/dispose 套件）；执行器测试套件如今以真实服务为基准，固定 bash 自有的各层行为（分类、合并、spawn 失败提示、归服务所有的存续期）。
+换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP（Agent Client Protocol）消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；共享的 `DSH_*`/输出词汇有了一个不带 shell 含义的归属；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
 
-代价是：多出一对包，而且凡加载 bash 执行器之处都多一行组合配置。若某次启动加载了执行器却没有加载子进程服务，`ctx.bash` 会因等待 `ctx.subprocess` 而保持挂起（标准的服务缺失行为）。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包如今命名同一批类型；进程 seam 是所有者，bash seam 则记录这层重导出。spawn 失败提示经由读取路径变为单次交付，而旧管道曾把它保留在 stderr 缓冲区里，供重复的 `readFrom(0)` 读取；这一点可以接受，因为 bash 的后台读取路径本就是消费游标，该提示能到达唯一存在的那个读取方。
+代价是：多出一对包，而且凡加载 bash 执行器之处都多一行组合配置。若某次启动加载了执行器却没有加载管理器，`ctx.bash` 会因等待 `ctx.subprocess` 而保持挂起（标准的服务缺失行为）。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包如今命名同一批类型；进程 seam 是所有者，bash seam 则记录这层重导出。spawn 失败提示经由读取路径变为单次交付，而旧管道曾把它保留在 stderr 缓冲区里，供重复的 `readFrom(0)` 读取；这一点可以接受，因为 bash 的后台读取路径本就是消费游标，该提示能到达唯一存在的那个读取方。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
new file mode 100644
index 0000000000..8b4288edb4
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+2026-07-28-portable-execution-world-consumers.md: 000fa1b98964eb85550d0c607281937f8d7932c6
+2026-07-28-portable-execution-world-consumers.zh.md: 94e6bfcf94e450fafea2b33e152384da400e4b63
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
new file mode 100644
index 0000000000..000fa1b989
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -0,0 +1,48 @@
+# Agent Note: Portable consumers over filesystem and subprocess execution worlds
+
+Status: implemented
+
+English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
+
+## Problem
+
+The filesystem and subprocess seams made file and ordinary process access replaceable, but several higher capabilities still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY, LSP, and Code Runtime packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
+
+Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
+
+## Decision
+
+`ctx.fs` and `ctx.subprocess` together define one execution world. Providers mounted together must describe the same path namespace, executables, processes, and terminal sessions; higher capabilities consume those two interfaces rather than name the provider.
+
+The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, containment, and a bounded stable-handle text read. The existing text and mutation operations remain filesystem-owned.
+
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+
+Generic consumers use that execution world:
+
+- `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
+- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them.
+
+`dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
+
+## Alternatives considered
+
+**Keep one PTY, LSP, and Code Runtime package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
+
+**Model a terminal as an ordinary piped subprocess.** Rejected because pipes cannot allocate a controlling terminal, resolve the current foreground process group, or prove complete terminal-session cleanup. One terminal primitive is smaller and more honest than exposing substrate-specific escape hatches.
+
+**Move PTY readiness and session policy into the subprocess service.** Rejected because those are persistent-terminal consumer semantics, not OS process mechanics. A subprocess provider owns what only its substrate can do; `dsh-pty-local` owns what a Harness terminal means.
+
+**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable and filesystem materialization; the worker backend has neither requirement and remains the supported single-process path.
+
+**Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
+
+## Consequences
+
+A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, LSP, and subprocess Code Runtime compose above them, so fixes to those capabilities remain provider-neutral.
+
+The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
+
+The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal still waits for exact PID-identity-fenced descendants and the top-level terminal process to reach quiescence.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
new file mode 100644
index 0000000000..94e6bfcf94
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: 基于文件系统与进程管理执行世界的可移植消费方
+
+Status: implemented
+
+[English](2026-07-28-portable-execution-world-consumers.md) | 中文
+
+## 问题
+
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+
+普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
+
+## 决策
+
+`ctx.fs` 与 `ctx.subprocess` 共同定义一个执行世界。共同挂载的提供方必须描述相同的路径命名空间、可执行文件、进程和终端会话；上层能力消费这两个接口，而不引用具体提供方。
+
+文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI、包含关系，以及通过稳定句柄执行的有界文本读取。现有文本与变更操作仍归文件系统负责。
+
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+
+通用消费方使用该执行世界：
+
+- `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
+- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。
+
+`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
+
+## 考虑过的替代方案
+
+**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+
+**把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
+
+**把 PTY 就绪判断与会话策略移入进程管理服务。** 不予采纳，因为这些属于持久终端消费方的语义，而非 OS 进程机制。进程管理提供方负责只有其执行基底才能完成的操作；`dsh-pty-local` 负责 Harness 终端的语义。
+
+**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
+
+**在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
+
+## 后果
+
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+
+基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
+
+本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）仍会等待受精确 PID 身份校验保护的后代进程和顶层终端进程完全停稳。
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index bc05e497c5..a878942993 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: ca1bbe9ed3e412186763d1ed4fca9ed06669d4c3
+2026-06-15-code-mode.md: 7e51b9fa726afe4c34b87457b562b4092ee6c93c
+2026-06-15-code-mode.zh.md: 4ba098d87d8c944e88c4cbe11ff78ac4383d3ac5
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 99bbed3eda..7e51b9fa72 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-15-code-mode.zh.md)
 
 ## Problem
 
-In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and at the time of this note the loop dispatched each call through `ctx.tools.execute()` **sequentially** (parallel tool execution was an open TODO then; bounded parallel dispatch has since shipped — the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md), the rolling pool in [docs/architecture.md](../../../../docs/architecture.md)) — with **every** intermediate `tool-result` re-entering the model's context on the next request.
+In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and the loop dispatches each call through `ctx.tools.execute()` **sequentially** (parallel tool execution is an explicit open TODO in `dsh-tools` and [docs/architecture.md](../../../../docs/architecture.md)), with **every** intermediate `tool-result` re-entering the model's context on the next request.
 
 For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each round-trip drags the entire intermediate result back into context whether the model needs it or not.
 
@@ -20,7 +20,7 @@ Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
 2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
-3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
+3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` materializes a runner through `ctx.fs` and launches it through `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
 
@@ -32,7 +32,7 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
 
 **Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
 
-**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md) added Python and the `ctx.codeRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
+**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders TypeScript declarations plus fixed usage instructions for the scope's visible capabilities. It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
 
 **Assembly ownership.** `run_code` and `tools:sdk` enter the trusted `system-prompt/assemble` waterfall as normal assembly inputs. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace either contribution. The waterfall's returned assembly is final, so whoever changes these inputs owns preserving a viable Code Mode protocol when the deployment expects Code Mode to remain usable; no restoration pass overrides deliberate composition.
 
@@ -48,7 +48,7 @@ Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentat
 
 **Sub-call contexts are deferred through the parent.** Injecting inside `run_code` would break parent call/result adjacency, so `ToolRunContext.deferContext()` collects every sub-result `additionalContexts` entry in dispatch order. The registry carries that array even when the program later throws, and the loop appends each entry only after the outer result and every sibling result in the step. An outer post-execute block discards tool-deferred entries and exposes only contexts explicitly attached by the blocking decision.
 
-**Concurrency is bounded, not serialized.** Each run owns a dispatch queue that starts calls strictly in submission order and classifies each one through `registry.executionMode`, the same fail-closed `isConcurrencySafe` contract the native loop uses. Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (default 10; `1` restores serial dispatch); an exclusive call drains the pool and runs alone. Settlement abandons queued calls that have not started. This note shipped the serialized placeholder; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler that replaced it.
+**Concurrency is serialized.** Each run owns a dispatch queue, so even `Promise.all` executes tool calls in submission order. Settlement abandons queued calls that have not started. Parallelism requires per-tool concurrency-safety metadata.
 
 **Presentation.** `run_code`'s render intent is decided here per the [render-intent Agent Note](../architecture/2026-07-02-tool-render-intent-union.md): `presentCall` creates a `generic` card with `kind: 'execute'`, the program text as its title, and the same program text as `rawInput`; `run_code` intentionally declares no `presentResult`, so the TUI and host/client runtime (Web) complete that card through their generic raw-content fallback using the final durable `tool/result.content`, including captured logs plus the returned value, failure, or post-policy spill preview. This is not a `terminal` card: that card's semantics are "a shell command in a working directory", which a program is not. See the [result-card completeness note](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md).
 
@@ -64,7 +64,7 @@ Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool en
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }` — the runtime exposes each namespace as a global object of async functions inside the program; the optional descriptor asks the runtime to inject a real program-visible rejection class without teaching the seam consumer-specific names. `CodeJsonValue` is this dependency-light seam's structural lossless-JSON type, so binding arguments and resolutions cross the implementation's serialization boundary whole.
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }` — program execution outcomes resolve as the `error` field. `run()` may reject only for caller/seam misuse (for example a duplicate binding namespace); consumers still contain a non-conforming backend rejection at their own error boundary.
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../../docs/defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout, a lossy completion is not an overflow, and a substrate exit is none of them.
-- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the first backend; a Python backend says `'python'` and pairs with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` accepts any `language` with a registered SDK renderer and `run_code` flavor (TypeScript and Python ship; see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)) and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for both shipped backends; a Python backend would pair with its own SDK generator) and `isolation` (`'worker-thread'` for both shipped backends; the subprocess provider may add a container boundary). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
 
 Requests contain every runtime input; implementations own validated timeout and cap defaults. The registry looks up the optional runtime only when Code Mode is assembled, so native mode does not depend on one. Missing or language-incompatible runtimes fail loudly. Alternate substrates or languages can replace the implementation behind the same seam, paired with the appropriate SDK generator.
 
@@ -79,21 +79,23 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+
 ### Trust posture
 
-The worker runtime provides containment, not a security boundary: model code can reach Node APIs and has authority comparable to the bash tool. `worker.terminate()` stops the thread but not OS processes it spawned. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary need a container-class backend for both code and bash; the runtime's isolation descriptor lets them distinguish that backend.
+The runtimes provide containment, not an independent security boundary: model code can reach Node APIs and has the authority of its mounted execution world. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty worker environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary mount container-class filesystem/subprocess providers for both code and bash.
 
 ### What the model sees
 
-The SDK instructs the model to write an async body in the loaded runtime's language (an erasable-TypeScript body by default; a Python `async` body under a Python runtime — see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)), call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Both flavors state the same contract in their own primitive: independent read-only calls MAY overlap under `Promise.all` (TypeScript) or `asyncio.gather` (Python), mutating calls run alone in submission order, and dependent work sequences with `await`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
+The SDK instructs the model to write an async erasable-TypeScript body, call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Calls remain sequential even under `Promise.all`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
 
 ## Consequences
 
-Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch starts in submission order under a bounded overlap pool, while per-call contexts retain their source, envelope, and metadata through the outer result.
+Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch remains serialized, while per-call contexts retain their source, envelope, and metadata through the outer result.
 
 ## Testing
 
-- **Worker runtime:** Real-worker tests cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. A built-package test runs the worker entry under plain Node.
+- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
@@ -106,7 +108,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s is cheap to add as a logged surface replacement under reconstructable requests, but still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
 
-**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and that is how it played out: the metadata landed as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch and per-tool binding parallelism unlocked on the same classifier.
+**Parallel native dispatch in the loop.** The other answer to round-trip cost; still valid future work (the open TODO), still blocked on concurrency-safety metadata, and still no composition — it parallelizes calls the model already decided on in one step. Code Mode's serialized-queue decision keeps the two compatible: when the metadata lands, both native parallel dispatch and per-tool binding parallelism unlock together.
 
 **Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
 
@@ -118,7 +120,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Risks
 
-**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
+**A worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool and gating uses the same seams. The subprocess implementation can run inside a container-class execution world, but its worker descriptor does not itself claim that boundary.
 
 **`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
 
@@ -126,8 +128,8 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Registry scope growth.** `dsh-tools` absorbs codegen, a tool, a bridge, and an event. Contained by module boundaries inside the package (`ts-types.ts`, `code-mode.ts` beside `schema.ts`/`json-schema.ts`/`presentation.ts`) and by the seam: everything substrate-shaped lives behind `ctx.codeRuntime`.
 
-**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The runtime validates both sides of the worker port and applies no per-binding byte cap; structured-clone cost and process or worker memory are the practical bounds. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is the only byte-capped boundary.
+**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The direct worker runtime applies no per-binding byte cap; the subprocess runtime bounds each transport frame with `maxFrameBytes`, but repeated or concurrent calls can still consume process or worker memory. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is separately bounded by `maxOutputBytes`.
 
-**Sub-dispatch overlap is bounded by tool safety claims, not by the caller.** A program's `Promise.all` or `asyncio.gather` buys wall-clock parallelism only across calls the tool itself classifies concurrency-safe; a run of exclusive calls still costs its round-trips in sequence, and models may over-expect. Both flavors' SDK instructions state the real contract. This note shipped the serialized placeholder that made the risk absolute; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler and its overlap cap.
+**Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
 
 **Budget metering reads the event loop, not a flag.** Busy-time polling (`eventLoopUtilization()`) is coarser than an exact CPU meter — a budget expires up to one poll interval late — and its correctness claim ("a pending dispatch cannot pause it") is load-bearing against a hostile program. Both sides are unit-tested (hot loop with a pending decoy dispatch dies at `computeMs`; idle-on-slow-binding survives to `maxWallMs`), and the poll interval is an internal constant, not config — nothing a deployment could mis-tune into a bypass. `maxWallMs` is config, and it reaches `setTimeout`, which clamps a delay above `MAX_TIMER_DELAY_MS` (2^31-1 ms) to 1 ms; a positivity check alone therefore accepts a 25-day ceiling that expires on the first tick and times out every run. The worker runtime range-checks the field at load for that reason. `computeMs` needs no upper bound because it is compared against measured utilization instead of being handed to a timer.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index ca1bbe9ed3..4ba098d87d 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，而在本 note 写作时，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行当时还是 open TODO；此后有界的并行分发已经交付——见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)，以及 [docs/architecture.md](../../../../docs/architecture.md) 中的 rolling pool）——且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
+在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行是 `dsh-tools` 和 [docs/architecture.md](../../../../docs/architecture.md) 中明确标注的 open TODO），且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
 
 对于多步工具操作，这种方式 token 开销大且串行。模型无法组合工具——遍历结果集、根据中间值分支、扇出、后处理——每次调用都需要一次完整的模型往返，而每次往返都会把完整的中间结果拖回上下文，不管模型是否需要。
 
@@ -19,8 +19,8 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 三项决策，各自在下方独立小节中展开：
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
-2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包`@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
-3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
+2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
+3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 在另一执行环境中启动。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
 
@@ -32,7 +32,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
 
-**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](2026-07-31-code-mode-language-dispatch.md) 加入了 Python 与按 `ctx.codeRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
+**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染 TypeScript 声明加固定的使用说明。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
 
 **组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 Code Mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
 
@@ -40,7 +40,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 ### run_code 工具与分发桥
 
-在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调性守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
+在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
 
 1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
@@ -48,7 +48,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
 
-**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 契约相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**并发被序列化。** 每次 run 拥有一个分发队列，因此即使 `Promise.all` 也按提交顺序执行工具调用。结算时放弃尚未开始的排队调用。并行化需要每个工具的并发安全元数据。
 
 **呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
 
@@ -61,39 +61,41 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 `packages/code-runtime/code-runtime/`——`@deepseek-ai/dsh-code-runtime`，仅依赖 `cordis`。一个抽象的 `CodeRuntime extends Service`（`super(ctx, 'codeRuntime')`）加上词汇：
 
 - `CodeRunRequest = { program: string; bindings: CodeBindingNamespace[]; signal?: AbortSignal }`
-- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与返回值可以完整跨越实现的序列化边界。
+- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }`——程序执行失败时，执行 promise 仍会 fulfill，并通过 `error` 字段返回失败结果。只有调用方/seam 误用（例如重复的绑定命名空间）时，`run()` 才会 reject；消费方仍在自己的错误边界处理不合规后端的拒绝。
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }`——按[防御性模式](../../../../docs/defensive-patterns.md)独立报告的正交结果；超时的 run 不是异常，abort 不是超时，有损完成值不是溢出，基底退出也与上述情况相互独立。
-- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——首个后端为 `'typescript'`；Python 后端声明 `'python'`，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 接受任何注册了 SDK 渲染器与 `run_code` flavor 的 `language`（TypeScript 与 Python 已交付；见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
+- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——两种已交付后端均为 `'typescript'`；Python 后端会配对自己的 SDK 生成器）和 `isolation`（两种已交付后端均为 `'worker-thread'`；子进程提供方可以增加容器边界）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
 
 请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
 
 ### worker-thread 运行时
 
-`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包。每次 `run()`：
+`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包（package）。每次 `run()`：
 
-1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且会保留源码位置，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
+1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且保持位置不变，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
 2. **每次 run spawn 一个全新 `Worker`**，来自包自身的 bootstrap 模块：`env: {}`（真正为空——比 spawn 命令的 scrubbed-env 规则更严格），`resourceLimits` 来自配置，`stdout`/`stderr` 捕获到 `logs` 而非继承。不做池化，不跨 run 保留状态：程序的世界随 worker 消亡，这使得 run 仅从日志即可重建，状态泄漏不可表达。
 3. **在 bootstrap 中执行**：剥离后的程序成为一个 `AsyncFunction` 的函数体，其参数是绑定全局变量、消费方声明的 reject 类和一个捕获式 `console` shim，因此顶层 `await` 和 `return` 可用。Code Mode 声明 `ToolCallError`，成员属性为 `toolName`；运行时无需硬编码工具即可实体化真正的构造函数。无损 JSON 完成值会精确跨越边界；`undefined` 仍表示缺席，有损值产生 `invalid-output`，过大的外层结果产生 `output-limit`，而不会退化为检查格式化后的字符串替代品。
 4. **通过消息端口桥接绑定**：worker 中的每个绑定函数发送 `{ id, global, name, args }` 并等待回复；宿主根据请求的绑定校验名称、调用、并回复 `{ id, ok, value }` 或 `{ id, ok: false, message }`（宿主侧绑定拒绝变为程序侧 rejection）。worker 侧的命名空间对象通过 `defineProperty` 构建为 null-prototype，因此名为 `__proto__`、`constructor` 或 `toString` 的绑定是普通自有属性，而非原型链碰撞。未知名称、重复 id 和结算后消息被拒绝或忽略——端口协议假设对端是恶意的，因为对端运行的是模型代码。
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
-6. **dispose（资源释放）至完全停稳**：服务自身的 dispose 终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
+6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
+
+`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
-worker 运行时只能约束程序的运行，而不构成安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
+这些运行时提供的是隔离，而非独立安全边界：模型代码可以访问 Node API，并拥有挂载的执行环境所授予的权限。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空 worker 环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署应当为代码和 bash 都挂载容器级文件系统／子进程提供方。
 
 ### 模型看到的内容
 
-SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一契约：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
+SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。即使在 `Promise.all` 下调用仍保持顺序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
 
 ## 后果
 
-切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发在有界的重叠池下按提交顺序启动，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
+切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发保持序列化，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
 
 ## 测试
 
-- **Worker 运行时：** 真实 worker 测试覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。一个构建后包测试在纯 Node 下运行 worker 入口。
+- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
@@ -104,9 +106,9 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **`node:vm` 作为参考运行时，加固推迟。** 否决：`node:vm` 不是隔离（原型链逃逸可达宿主 realm）且无法中断热循环。worker 线程提供独立 isolate、空环境、`resourceLimits` 和可靠的 `terminate()`，信任等级等同于 bash，因此参考实现和生产实现是同一个包，无需 unsafe-acknowledgement 仪式。
 
-**在原生工具调用上做结果省略/摘要。** 仅解决问题中上下文膨胀这一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
+**在原生工具调用上做结果省略/摘要。** 仅解决问题的上下文膨胀一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
 
-**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，后续也正是这样落地的：元数据以 `isConcurrencySafe` 的形式就绪（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发与每工具绑定并行化基于同一个分类器一起解锁。
+**循环中的并行原生分发。** 往返成本的另一个答案；仍是有效的未来工作（open TODO），仍被并发安全元数据阻塞，且仍无组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的序列化队列决策保持两者兼容：当元数据就绪时，原生并行分发和每工具绑定并行化一起解锁。
 
 **始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
 
@@ -114,20 +116,20 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **SDK 中的清洁化标识符别名**（`my-tool` → `my_tool`，Cloudflare 的做法）。否决：`declare const` 上的带引号键使每个名称可达，零别名碰撞逻辑；模型能正常处理 `tools["my-tool"](…)`。
 
-**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 均使用全新实例则维持了这一保证。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
+**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 全新保持了这一点。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
 
 ## 风险
 
-**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
+**worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，门禁使用相同的 seam。子进程实现可以在容器级执行环境中运行，但其 worker 描述符本身不声称具备该边界。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
 
 **SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
 
-**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 共同约束了这一增长：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
+**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
 
-**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 返回值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。直接 worker 运行时不对单次绑定设置字节数上限；子进程运行时使用 `maxFrameBytes` 限制每个传输帧，但重复或并发调用仍可能消耗进程或 worker 内存。包含日志、完成值和失败诊断的组合外层输出账本另由 `maxOutputBytes` 限制。
 
-**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实契约。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
 
-**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）是抵御恶意程序的关键。两种情况均有单元测试（带 pending 诱饵分发的热循环会在耗尽 `computeMs` 预算时终止；等待慢速绑定的空闲程序则会持续运行至 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
+**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）对恶意程序是承重的。两侧都有单元测试（带 pending 诱饵分发的热循环在 `computeMs` 处死亡；在慢绑定上空闲的程序存活到 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 451a4ea0d3..6a801df865 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: d7d06dc8517780a37889e4f94dd0b99475dc5432
-2026-07-16-persistent-pty-sessions.zh.md: 84ef8988ba657a87137f904df38e45808d32b483
+2026-07-16-persistent-pty-sessions.md: 65d265b83ab5ad89c2b919364043eb28e75977c7
+2026-07-16-persistent-pty-sessions.zh.md: 6ea92da9a1b2870f3773d84e7f5629bec220dd1c
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index d7d06dc851..65d265b83a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -23,10 +23,10 @@ The implementation supports interactive shells and line-oriented REPLs on Linux
 | Package | Role | ctx key |
 |---|---|---|
 | `dsh-pty` | `PtyService`, branded `PtySessionId`, backend registry, owner-scoped session contract, and result types | `ctx.pty` |
-| `dsh-pty-local` | [`node-pty`](https://github.com/microsoft/node-pty)-based local backend, platform process inspection, bounded terminal buffer, sandbox resolution, and process-tree supervision | registers a backend on `ctx.pty` |
+| `dsh-pty-local` | Persistent-shell backend over `ctx.subprocess.spawnTerminal()`: readiness, bounded terminal buffers, sandbox resolution, and owner-aware session lifecycle | registers a backend on `ctx.pty` |
 | `dsh-tool-pty` | Six model-facing tools, task-runtime integration for background sends, guidance, and UI render intents | registers on `ctx.tools` |
 
-Idle detection is backend behavior, not a second public seam. A remote or container backend may have authoritative readiness signals that do not resemble local `/proc` inspection; every `PtyBackend` therefore returns the common send result while owning its detection mechanism internally.
+Readiness remains PTY-backend behavior, not a second public seam. The terminal-process provider supplies only substrate facts such as the foreground process group and whether it can prove that group is waiting on input; `dsh-pty-local` combines those facts with prompt and silence evidence into the common send result.
 
 ### Agent ownership and identity
 
@@ -40,12 +40,12 @@ Agent-scope disposal closes registrations first, then awaits quiescent teardown
 
 A registered `shell` backend constrains how a terminal starts; it does not constrain commands typed after startup. `dsh-pty-local` therefore applies two protections before spawning:
 
-- It builds a scrubbed child environment using the same credential-shaped-name policy as `bash-local`, removing ambient `*KEY*`, `*PASSWORD*`, `*SECRET*`, `*TOKEN*`, and harness-managed variables unless an explicit trusted mapping supplies them.
+- It supplies only terminal-specific environment overrides; the mounted subprocess provider applies the shared credential-shaped-name scrub before merging them.
 - It requires `ctx.sandbox` and the shared `ctx.sandboxPolicy`. At spawn, the backend resolves the owner's effective session mode over the deployment default and wraps the shell argv once; that mode and workspace root remain the process boundary for the PTY lifetime. A write that would change the effective `sandbox/mode` is rejected before commit while the owner has any open PTY or unpublished spawn, with an instruction to wait for creation to settle and close those sessions first; same-effective-mode writes remain valid. The pending reservation spans backend setup through publication, so there is no race in which a wider terminal appears after a downgrade. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
 
 Sandboxing confines local process effects but does not make arbitrary shell input safe: network calls and other external side effects remain governed by deployment policy. Tool descriptions state that PTY sessions are less auditable than one-shot tools and should be used only when persistence or interactive stdin is necessary.
 
-The implementation uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, `resize`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. Platform process inspectors derive foreground process groups and parent/child identity from `/proc` on Linux and `ps` on macOS.
+The local subprocess terminal primitive uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. Platform process inspectors below that primitive derive foreground process groups and parent/child identity from `/proc` on Linux and `ps` on macOS. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns this process/consumer split.
 
 ### Six model-facing tools
 
@@ -92,9 +92,9 @@ Background sends use the existing task completion notice and `task_output` resul
 
 ### Process-tree teardown
 
-The top-level `node-pty` child is the ownership anchor. On close, the backend stops callbacks, snapshots its transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the remaining descendant tree, and verifies that every non-zombie descendant left the process table while the shell is still alive. A matching Linux zombie has no executable work and therefore counts as quiescent, allowing shell shutdown to reap or reparent it. Only then does the backend stop the shell with its own TERM/grace/KILL sequence. Every captured PID includes process-start identity so reuse cannot redirect escalation.
+The subprocess terminal handle owns the top-level terminal process and its session. On close it snapshots transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the union, and verifies every non-zombie descendant left the process table before stopping the top-level process. A matching Linux zombie has no executable work and therefore counts as quiescent. Every captured PID includes process-start identity so reuse cannot redirect escalation.
 
-Teardown reports root exit and survivor cleanup independently. It does not claim success merely because the shell exited; disposal resolves only after no captured non-quiescent tree member remains or returns a cleanup failure naming the survivors. A failed close is not cached forever: the registry and local session each clear the fence only when it still names that failed attempt, so a later explicit or lifecycle close retries after the external survivor condition changes without disturbing a newer concurrent attempt. Service disposal still clears its backend, reservation, and owner-detacher registries when a close fails. It never broadens ownership to every member of the root PID's POSIX session.
+Teardown reports top-level exit and survivor cleanup independently. The PTY session does not claim success merely because the shell exited: it calls `SubprocessTerminalHandle.terminate()` and awaits whole-session quiescence, propagating a cleanup failure that names survivors. A failed close is not cached forever: the registry and local session clear the fence only when it still names that failed attempt, so a later explicit or lifecycle close retries without disturbing a newer concurrent attempt. Service disposal still clears its backend, reservation, and owner-detacher registries when a close fails.
 
 ### Composition and rollout
 
@@ -108,6 +108,7 @@ plugins:
       mode: workspace-write
       workspaceRoot: .
   '@deepseek-ai/dsh-pty':
+  '@deepseek-ai/dsh-subprocess-local':
   '@deepseek-ai/dsh-pty-local':
     config:
       scrollbackLines: 10000
@@ -141,11 +142,11 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 **Add persistent mode to `bash`.** Rejected. Returning on readiness rather than process exit, retaining a process tree across calls, and exposing interactive stdin create a different ownership and failure contract.
 
-**Require native master-fd access from `node-pty`.** Rejected. Its public API exposes no master fd. The local backend instead derives foreground groups and descendants from supported OS process metadata and treats unreadable metadata as a detector miss.
+**Require native master-fd access from `node-pty`.** Rejected. Its public API exposes no master fd. The local subprocess terminal adapter derives foreground groups and descendants from supported OS process metadata and treats unreadable metadata as a detector miss.
 
 **Signal every member of the root PID's POSIX session.** Rejected. `node-pty` may expose a helper PID whose session belongs to the launcher, so SID-wide teardown can signal unrelated harness or desktop processes. A PID-identity-fenced descendant tree is narrower and safe by construction.
 
-**Publish `PtyIdleDetector` as a replaceable registry.** Rejected. Only the local backend needs these platform probes, while remote backends may receive readiness over their own protocol. Backend replacement already provides the necessary extension point.
+**Publish `PtyIdleDetector` as a replaceable registry.** Rejected. Substrate-specific foreground facts come from the mounted terminal-process primitive, while prompt/silence readiness remains one private policy in `dsh-pty-local`. The filesystem/subprocess execution-world replacement is the necessary extension point.
 
 **Add a PTY-specific `sleep` tool.** Rejected. `ctx.tasks` already owns bounded waiting, cancellation, completion notices, and model-facing collection. A second general wake mechanism would cross the agent-loop boundary and duplicate that contract.
 
@@ -156,8 +157,8 @@ The package ships concise tool guidance explaining persistent state, owner isola
 ## Verification
 
 - Per-file coverage pins owner fencing, concurrent reservations, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents.
-- Linux process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
-- Real `node-pty` tests exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT` after deliberately delayed child readiness under scenario-owned timing bounds, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
+- Subprocess process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
+- Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
 - Package contracts, the architecture map, core data structures, generated catalogs, and the website API describe the same shipped surface.
 - The repository CI-equivalent sequence owns type, lint, coverage, snapshot, documentation, build, hygiene, demo, and built-entry verification.
@@ -172,10 +173,10 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 **Persistent state can drift from the model's belief.** The model may forget its cwd or active REPL. Session summaries and retained output help recovery, but no prompt can make state persistence deterministic.
 
-**A daemonized descendant can leave the captured tree.** A process that reparents before teardown is no longer discoverable from the `node-pty` root. The implementation accepts that cleanup gap instead of risking SID-wide signals to unrelated processes.
+**A daemonized descendant can leave the local provider's captured tree.** A process that reparents before teardown is no longer discoverable from the `node-pty` root. The local terminal primitive accepts that cleanup gap instead of risking SID-wide signals to unrelated processes.
 
 **A shell can cause external side effects.** Session sandboxing and environment scrubbing reduce local exposure but do not undo pushes, API calls, or messages. Deployments that cannot tolerate those effects must omit PTY or add network policy.
 
 **Process loss destroys terminal state.** In-process sessions do not survive a harness crash or restart, and raw scrollback is not durable. Important work must be committed to files or another durable system.
 
-**`node-pty` is a native dependency.** Installation, supported Node versions, prebuild availability, and platform behavior require built-artifact smokes on every supported OS.
+**`node-pty` is a native dependency of `dsh-subprocess-local`.** Installation, supported Node versions, prebuild availability, and platform behavior require built-artifact smokes on every supported OS.
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 84ef8988ba..6ea92da9a1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -14,7 +14,7 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 
 ## 决策
 
-可选的 `packages/pty/` 能力家族提供由 agent 拥有、持久化且面向行式交互的 PTY 会话。它遵循仓库的 [capability pattern](../../implemented/architecture/2026-06-13-capability-seams.md)，与现有命令和文件系统工具并存，并且不修改 `agent-loop`。
+可选的 `packages/pty/` 功能家族提供由 agent 拥有、持久化且面向行式交互的 PTY 会话。它遵循仓库的 [capability pattern](../../implemented/architecture/2026-06-13-capability-seams.md)，与现有命令和文件系统工具并存，并且不修改 `agent-loop`。
 
 当前实现在 Linux 和 macOS 上支持交互式 shell 与行式 REPL。全屏终端应用、按键序列、BEL 触发的控制流、进程丢失后的会话恢复以及跨 agent 共享会话都明确推迟。
 
@@ -23,10 +23,10 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 | 包 | 角色 | ctx key |
 |---|---|---|
 | `dsh-pty` | `PtyService`、branded `PtySessionId`、后端注册表、按 owner 隔离的会话契约和结果类型 | `ctx.pty` |
-| `dsh-pty-local` | 基于 [`node-pty`](https://github.com/microsoft/node-pty) 的本地后端、平台进程检查、有界终端缓冲、沙箱解析和进程树监管 | 在 `ctx.pty` 上注册后端 |
+| `dsh-pty-local` | 基于 `ctx.subprocess.spawnTerminal()` 的持久 shell 后端：就绪状态、有界终端缓冲、沙箱解析和感知 owner 的会话生命周期 | 在 `ctx.pty` 上注册后端 |
 | `dsh-tool-pty` | 6 个面向模型的工具、后台发送的 task 运行时集成、使用指引和 UI 渲染意图 | 注册到 `ctx.tools` |
 
-idle 检测属于后端行为，不是第二条公共 seam。远程或容器后端可能拥有完全不同于本地 `/proc` 检查的权威就绪信号；因此每个 `PtyBackend` 都返回统一的发送结果，同时在内部拥有自己的检测机制。
+就绪判定仍属于 PTY 后端行为，不是第二条公共 seam。终端进程提供方只提供基底事实，例如前台进程组，以及能否证明该组正在等待输入；`dsh-pty-local` 将这些事实与提示符和静默证据组合成统一的发送结果。
 
 ### agent 所有权与身份
 
@@ -34,18 +34,18 @@ idle 检测属于后端行为，不是第二条公共 seam。远程或容器后
 
 实现不提供插件加载期 auto-start 会话。`terminal_open` 只在 agent 工具调用期间创建会话，此时所有权和所属的事件溯源会话都已确定。未来的声明式启动功能必须通过尚未发布的 agent setup 组合，而不能创建全局共享终端。
 
-agent scope dispose（资源释放）时先关闭注册，再等待全部所属 PTY 完全停稳。未发布的后端 setup 同样是受追踪的生命周期操作：owner 或服务 dispose 会中止服务自有的 signal，等待后端结算与回滚完成后才返回。即使后端 reject，或返回的会话在回滚 close 时失败，调用方取消仍会原样保留其 `AbortSignal.reason`；该清理失败不会替换调用方原因，而会继续受追踪，留待后续 owner 或服务 dispose 处理。由 lifecycle dispose 触发的回滚 close 失败会使 spawn 与该 lifecycle dispose 都 reject，而 `PtyBackendCleanupError` 让后端在不替换调用方取消的前提下，为该 lifecycle dispose 保留自身的启动清理失败。若调用方取消已完成结算，而 dispose 尚未发生，该清理失败会继续作为受追踪的 owner activity 保留，直到后续 owner 或服务 dispose 消费并报告它，因此沙箱模式策略不会把清理失败误判为完全停稳。后端或工具插件 reload 不会遗留会话：所有权持续存放在 `PtyService` 中，直到 agent 结束，与 [`ctx.tasks`](../../../../packages/tasks/tasks/README.md) 的服务持有记录模式一致。服务会先同步把会话预留给一次活跃发送，再返回该操作；后台发送同样会在 task id 对外可见前完成预留。第二次发送会以 `SEND_ACTIVE` 失败，因此输出与取消无法跨越操作所有权。
+agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出。未发布的后端 setup 同样是受追踪的生命周期操作：owner 或服务 dispose 会中止服务自有的 signal，等待后端结算与回滚完成后才返回。即使后端 reject，或返回的会话在回滚 close 时失败，调用方取消仍会原样保留其 `AbortSignal.reason`；该清理失败不会替换调用方原因，而会继续受追踪，留待后续 owner 或服务 dispose 处理。由 lifecycle dispose 触发的回滚 close 失败会使 spawn 与该 lifecycle dispose 都 reject，而 `PtyBackendCleanupError` 让后端在不替换调用方取消的前提下，为该 lifecycle dispose 保留自身的启动清理失败。若调用方取消先于 dispose 完成结算，该清理失败会继续作为受追踪的 owner activity 保留，直到后续 owner 或服务 dispose 消费并报告它，因此沙箱模式策略不会把清理失败误判为静默。后端或工具插件 reload 不会遗留会话：所有权持续存放在 `PtyService` 中，直到 agent 结束，与 [`ctx.tasks`](../../../../packages/tasks/tasks/README.md) 的服务持有记录模式一致。服务会先同步把会话预留给一次活跃发送，再返回该操作；后台发送同样会在 task id 对外可见前完成预留。第二次发送会以 `SEND_ACTIVE` 失败，因此输出与取消无法跨越操作所有权。
 
 ### 安全与进程边界
 
 注册的 `shell` 后端只约束终端如何启动，不约束启动后输入的命令。因此 `dsh-pty-local` 在 spawn 前应用两层保护：
 
-- 它使用与 `bash-local` 相同的凭证形态名称策略构建清洗后的子进程环境，移除环境中的 `*KEY*`、`*PASSWORD*`、`*SECRET*`、`*TOKEN*` 和 harness 管理的变量，除非显式的可信映射提供这些值。
+- 它只提供终端专用的环境覆盖；挂载的子进程提供方先清除名称形似凭据的环境变量，再合并这些覆盖。
 - 它要求 `ctx.sandbox` 和共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode，并只包装一次 shell argv；该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。只要 owner 有任何已打开的 PTY 或尚未发布的 spawn，任何会改变生效 `sandbox/mode` 的写入都会在提交前被拒绝，并提示先等待创建操作结算，再关闭这些会话；不会改变生效模式的写入仍然有效。这项进行中的预留从后端 setup 持续到发布完成，因此不存在降级后又出现权限更宽的终端这一竞态。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
 
 沙箱限制本地进程副作用，但不会让任意 shell 输入自动安全：网络调用和其他外部副作用仍由部署策略治理。工具描述会说明 PTY 会话比一次性工具更难审计，只应在确实需要持久状态或交互式 stdin 时使用。
 
-实现只使用 `node-pty` 的公共功能：子进程 PID、`data` 与 `exit` 通知、`write`、`resize` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。平台进程检查器在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和父子进程身份。
+本地子进程终端原语只使用 `node-pty` 的公共功能：子进程 PID、`data` 与 `exit` 通知、`write` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。该原语下的平台进程检查器在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和父子进程身份。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)负责定义这种进程／消费方拆分。
 
 ### 6 个面向模型的工具
 
@@ -55,7 +55,7 @@ agent scope dispose（资源释放）时先关闭注册，再等待全部所属
 | `terminal_send` | 发送文本、可选提交 Enter，并等待就绪或注册一个后台任务 | 有界 viewport、等待状态和会话状态；后台模式还返回 `taskId` |
 | `terminal_read` | 从保留的 scrollback 读取一个有界页 | `{ text, totalLines, lineBegin, lineEnd, truncated }` |
 | `terminal_signal` | 向当前前台进程组发送一种允许的信号 | `{ delivered, targetPgid }` |
-| `terminal_close` | 关闭一个会话并等待进程树完全停稳 | `{ killed }` |
+| `terminal_close` | 关闭一个会话并等待进程树静默退出 | `{ killed }` |
 | `terminal_list` | 列出调用方的活会话 | 按 owner 隔离的会话摘要 |
 
 UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
@@ -66,7 +66,7 @@ UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发
 
 当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。生产方把 `maxResultBytes` 写入 task 快照，使 `task_output`、kill 返回的终态状态和完成通知在加上通用元数据后，仍对完整结果执行同一上限。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 会解析当前前台 PGID 并发送真正的 `SIGINT`，即使应用已禁用终端 `ISIG` 也同样如此，且后续升级仍只通过 PTY 后端拥有的 teardown 路径进行。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 seam。
 
-`terminal_read` 从最新保留行起，朝更早的行分页。后端同时对保留的 scrollback 和返回页载荷执行行数与 UTF-8 字节上限，因此单个超长行无法绕过后端上限；工具随后再限制包含分页与截断元数据的完整渲染页。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
+`terminal_read` 从最新保留行向后分页。后端同时对保留的 scrollback 和返回页载荷执行行数与 UTF-8 字节上限，因此单个超长行无法绕过后端上限；工具随后再限制包含分页与截断元数据的完整渲染页。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
 
 `terminal_signal` 接受闭合集 `SIGINT | SIGTERM | SIGKILL | SIGTSTP | SIGHUP`。后端在执行时解析终端前台进程组。当目标组是顶层 shell 时拒绝 `SIGKILL`，并指引调用方使用 `terminal_close`；进程组解析失败时操作直接失败，而不是向猜测的 PID 发送信号。
 
@@ -76,7 +76,7 @@ UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发
 
 在 Linux 上，检查器从 `/proc/<shellPid>/stat` 读取 shell 的终端前台 PGID，枚举该进程组中的每个进程与线程，并检查它们当前的 syscall。Tier 1 只有观察到 stdin 等待才返回正结果：直接 `read(0)`、获准读取且含 fd 0 的 `select`/`pselect6` 或 `poll`/`ppoll` 参数，或者含 fd 0 的 epoll interest list。终端输入前就已存在的等待并不代表写入后就绪：必须先观察到同一 PGID 脱离该等待，之后再次进入等待才能使该次 send 完成；前台 PGID 发生变化则构成新的证据。无法读取的进程内存和未识别的 syscall 都是 miss，绝不作为正向猜测。架构表只包含对应 Linux UAPI 定义的 syscall number；不支持的架构跳过 Tier 1。
 
-macOS 没有精确 syscall 层。任何前台进程组输出静默都会返回 `inferred_idle`，包括 Python 和 `gdb`；从 `ps` 推导的终端 PGID 只用于发送信号，不作为「只有 shell 才能 idle」的证明。纯进程检查逻辑可注入，并在 Linux 上进行单元测试，同时由 macOS CI job 驱动真实 PTY 和进程表路径。
+macOS 没有精确 syscall 层。任何前台进程组输出静默都会返回 `inferred_idle`，包括 Python 和 `gdb`；从 `ps` 推导的终端 PGID 只用于发送信号，不作为「只有 shell 才能 idle」的证明。纯进程检查逻辑可注入并在 Linux 上完成 unit 覆盖率，同时由 macOS CI job 驱动真实 PTY 和进程表路径。
 
 Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 sleep 或网络阻塞的命令可能看似 ready。如果此前已经见过 prompt marker，Tier 2 会再等待 `handoffGraceMs`，使恰好落在静默边界上的 bash 前台交接仍然以精确的 `stdin_read` 归因结束，而不是退到较弱的推断；该宽限是由部署方拥有的配置字段，并被校验为至少覆盖一个 `pollIntervalMs`——短于轮询周期的宽限装不下一次就绪轮询，因此不可能改变任何结果。它只约束见过 marker 的 send，代价是这一种情况的交互返回延迟，而不是每一次 send。Tier 3 在 `timeoutMs` 后返回 `timeout`，避免前台工具调用无限占住 agent。结果保留这些区别；调用方可以通过 `ctx.tasks` 等待、向前台组发信号，或从另一个会话排查。
 
@@ -88,13 +88,13 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此
 
 现有持久化 `tool/call` 与 `tool/result` 事件是模型发送文本和返回给模型的渲染输出的真源。`terminal_open` 通过已记录的工具结果返回 MOTD；前台 `send`/`read`/`list`/`signal`/`close` 结果走同一路径记录。PTY 包不会把原始字节流重复写入自定义会话事件。
 
-后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript（文本记录）sink 必须拥有独立的保留、凭证和隐私契约。
+后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript sink 必须拥有独立的保留、凭证和隐私契约。
 
 ### 进程树 teardown
 
-顶层 `node-pty` 子进程是所有权锚点。关闭时，后端先停止 callback，再按父 PID 以子进程优先顺序捕获其传递子进程、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向剩余子孙进程树发送 `SIGKILL`，并在 shell 仍存活时验证每个非僵尸子孙进程都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳；shell 关闭时会回收它或将其重新挂接给负责回收的父进程。完成这些步骤后，后端才用 shell 自身的 TERM、宽限等待、KILL 序列停止 shell。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。
+子进程终端句柄拥有顶层终端进程及其会话。关闭时，它按父 PID 以子进程优先顺序捕获传递后代、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向二者并集发送 `SIGKILL`，并在停止顶层进程前验证每个非僵尸后代都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。
 
-teardown 独立报告根进程退出与存活进程清理。它不会只因 shell 退出就声称成功；dispose 只有在已捕获的进程树中不再存在尚未完全停稳的成员后才完成，否则返回清理失败并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此外部存活进程状态改变后，后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。所有权绝不会扩大到根 PID 所属 POSIX 会话的全部成员。
+teardown 独立报告顶层进程退出与存活进程清理。PTY 会话不会只因 shell 退出就声称成功：它会调用 `SubprocessTerminalHandle.terminate()` 并等待整个会话完全停稳，若清理失败则向外传播并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。
 
 ### 组合与推行
 
@@ -108,6 +108,7 @@ plugins:
       mode: workspace-write
       workspaceRoot: .
   '@deepseek-ai/dsh-pty':
+  '@deepseek-ai/dsh-subprocess-local':
   '@deepseek-ai/dsh-pty-local':
     config:
       scrollbackLines: 10000
@@ -141,11 +142,11 @@ plugins:
 
 **给 `bash` 增加持久模式。**拒绝。按就绪而不是进程退出返回、跨调用保留进程树、暴露交互式 stdin 会形成不同的所有权和失败契约。
 
-**要求从 `node-pty` 获取原生 master fd。**拒绝。它的公共 API 不暴露 master fd。本地后端改为从受支持的 OS 进程元数据推导前台组与子孙进程，并把不可读元数据视为 detector miss。
+**要求从 `node-pty` 获取原生 master fd。**拒绝。它的公共 API 不暴露 master fd。本地子进程终端适配器改为从受支持的 OS 进程元数据推导前台组与子孙进程，并把不可读元数据视为 detector miss。
 
 **向根 PID 所属 POSIX 会话的全部成员发送信号。**拒绝。`node-pty` 可能暴露属于启动器会话的 helper PID，因此按 SID 清理可能向无关的 harness 或桌面进程发送信号。带 PID 启动身份校验的子孙进程树范围更窄，其安全边界由结构保证。
 
-**发布可替换注册表 `PtyIdleDetector`。**拒绝。只有本地后端需要这些平台 probe，远程后端可能通过自己的协议接收就绪状态。替换后端已经提供所需扩展点。
+**发布可替换注册表 `PtyIdleDetector`。**拒绝。基底专用的前台事实来自挂载的终端进程原语，提示符／静默就绪判定则仍是 `dsh-pty-local` 内部的一项私有策略。替换文件系统／子进程执行环境就是所需扩展点。
 
 **新增 PTY 专用 `sleep` 工具。**拒绝。`ctx.tasks` 已经拥有有界等待、取消、完成通知和面向模型的收集。第二套通用唤醒机制会跨越 agent loop（智能体循环）边界并重复该契约。
 
@@ -155,9 +156,9 @@ plugins:
 
 ## 验证
 
-- 逐文件测试覆盖并固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
-- Linux 进程 fixture（测试前置数据）覆盖非 leader 与非主线程的 stdin 等待、僵尸进程的完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
-- 真实 `node-pty` 测试在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、在由场景掌控的时间界限内先有意延迟子进程就绪，再对 raw mode 前台进程发送 `SIGINT`、忽略 `SIGTERM` 的子进程，以及 dispose 返回后立即完全停稳。
+- 每文件覆盖率固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
+- 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
+- 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
 - 包契约、架构图、核心数据结构、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
@@ -172,10 +173,10 @@ plugins:
 
 **持久状态可能偏离模型认知。**模型可能忘记 cwd 或活跃 REPL。会话摘要和保留输出有助恢复，但任何 prompt 都无法让状态持久化变成确定行为。
 
-**daemonized 子进程可能离开捕获树。**在 teardown 前 reparent 的进程无法再从 `node-pty` 根进程发现。实现接受这个清理缺口，不冒险按 SID 向无关进程发送信号。
+**daemonized 后代进程可能离开本地提供方捕获的进程树。**在 teardown 前 reparent 的进程无法再从 `node-pty` 根进程发现。本地终端原语接受这个清理缺口，不冒险按 SID 向无关进程发送信号。
 
 **Shell 可以造成外部副作用。**会话沙箱和环境清洗降低本地暴露，但无法撤销 push、API 调用或消息发送。无法容忍这些副作用的部署必须省略 PTY 或增加网络策略。
 
 **进程丢失会销毁终端状态。**进程内会话无法跨 harness crash 或 restart 存活，原始 scrollback 也不持久化。重要工作必须提交到文件或其他持久系统。
 
-**`node-pty` 是原生依赖。**安装、支持的 Node 版本、prebuild 可用性和平台行为都需要在每个支持 OS 上运行构建产物冒烟测试。
+**`node-pty` 是 `dsh-subprocess-local` 的原生依赖。**安装、支持的 Node 版本、prebuild 可用性和平台行为都需要在每个支持 OS 上运行 built-artifact smoke。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 1f81974b21..c07e81089c 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -284,6 +284,30 @@ export interface Config {
 
 Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
 
+## `@deepseek-ai/dsh-code-runtime-subprocess`
+
+Requires: `fs` · `subprocess`
+
+```ts config-catalog
+/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
+export interface Config {
+  /** Worker measured event-loop busy-time budget. */
+  computeMs?: number
+  /** Host-observed wall-clock ceiling. */
+  maxWallMs?: number
+  /** Combined serialized outer logs/value/diagnostic cap. */
+  maxOutputBytes?: number
+  /** Worker old-generation heap cap in MiB. */
+  maxOldGenerationSizeMb?: number
+  /** Largest decoded bridge frame, including binding traffic. */
+  maxFrameBytes?: number
+  /** Process-tree TERM-to-KILL grace. */
+  killGraceMs?: number
+}
+```
+
+Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:28`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
+
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
 ```ts config-catalog
@@ -317,7 +341,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:30`](../packages/code-runtime/code-runtime-worker/src/index.ts)
 
 ## `@deepseek-ai/dsh-compact-basic`
 
@@ -423,7 +447,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/fs-local/src/index.ts:38`](../packages/fs/fs-local/src/index.ts)
+Source: [`packages/fs/fs-local/src/index.ts:40`](../packages/fs/fs-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-sandbox`
 
@@ -906,7 +930,7 @@ Source: [`packages/llm/llm-retry/src/index.ts:46`](../packages/llm/llm-retry/src
 
 ## `@deepseek-ai/dsh-lsp-local`
 
-Requires: `lsp` · `subprocess`
+Requires: `fs` · `lsp` · `subprocess`
 
 ```ts config-catalog
 /** Plugin configuration: provider id → local language-server configuration. */
@@ -942,7 +966,7 @@ export interface LspLocalServerConfig {
 }
 ```
 
-Source: [`packages/lsp/lsp-local/src/index.ts:87`](../packages/lsp/lsp-local/src/index.ts)
+Source: [`packages/lsp/lsp-local/src/index.ts:82`](../packages/lsp/lsp-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-mcp-client`
 
@@ -1048,7 +1072,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:69`](../packages/plan/plan-mode/s
 
 ## `@deepseek-ai/dsh-pty-local`
 
-Requires: `pty` · `sandbox` · `sandboxPolicy`
+Requires: `pty` · `sandbox` · `sandboxPolicy` · `subprocess`
 
 ```ts config-catalog
 /** Public plugin configuration. */
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index edfd046430..7015d39bc8 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -410,7 +410,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 
 Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
 
-Source: [`packages/fs/fs/src/index.ts:62`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
 
 ### `fs/observed` — emit
 
@@ -430,7 +430,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 
 Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
 
-Source: [`packages/fs/fs/src/index.ts:71`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
 
 ### `fs/write-intent` — waterfall
 
@@ -450,7 +450,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 
 Types: [FsTarget](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md)
 
-Source: [`packages/fs/fs/src/index.ts:54`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
 
 ## `goal/*`
 
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
index 91ac0ed81d..129c5569b9 100644
--- a/docs/core-data-structures/filesystem.i18n.yaml
+++ b/docs/core-data-structures/filesystem.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 docs/core-data-structures/filesystem.md
-filesystem.md: 110c1fd428b15c5094f9dcc94050cad61c324373
-filesystem.zh.md: 010ec22a5d4a29555425c3deede08b317cba7004
+filesystem.md: 50b936bdef7535769f19d6cc0a75eb11eea9a869
+filesystem.zh.md: 61a885203b0718b34b0fd936c318b03c65ce4770
diff --git a/docs/core-data-structures/filesystem.md b/docs/core-data-structures/filesystem.md
index 110c1fd428..50b936bdef 100644
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -12,6 +12,8 @@ Provider source: [`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.
 
 Every operation resolves a user-supplied path to an opaque backend target first. Consumers may display `displayPath`, but must not parse `targetKey` (a branded opaque id) or assume it is a local absolute path.
 
+Consumers that share the filesystem's execution world obtain cross-capability coordinates through the provider instead of interpreting that identity: `processPath(target)` returns the canonical absolute path a subprocess can open, `fileUrl(target)` returns its provider-platform `file:` URI, and `contains(parent, child)` tests canonical identity or descendant containment.
+
 ```ts type-equiv
 /**
  * A path resolved by a backend into a stable identity. `resolve()` produces
@@ -50,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure.
+`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure. Protocol consumers use `readTextBounded(target, maxBytes)` when size validation and the complete UTF-8 read must remain one backend-owned stable operation; composing `stat` with `readText` would admit growth and replacement races.
 
 ```ts type-equiv
 /**
@@ -256,4 +258,4 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `readTextBounded`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/core-data-structures/filesystem.zh.md
index 010ec22a5d..6b7642b3f7 100644
--- a/docs/core-data-structures/filesystem.zh.md
+++ b/docs/core-data-structures/filesystem.zh.md
@@ -12,6 +12,8 @@
 
 每个操作首先将用户提供的路径解析为不透明的后端目标。消费方可以显示 `displayPath`，但禁止解析 `targetKey`（一个品牌化的不透明 id），也不得假设它是本地绝对路径。
 
+与文件系统共享执行世界的消费方通过提供方获取跨能力坐标，而不是解释该身份：`processPath(target)` 返回子进程可以打开的规范化绝对路径，`fileUrl(target)` 返回采用提供方平台语法的 `file:` URI，`contains(parent, child)` 则检查规范化身份相等或后代包含关系。
+
 ```ts type-equiv
 /**
  * A path resolved by a backend into a stable identity. `resolve()` produces
@@ -50,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。
+`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。当大小校验与完整 UTF-8 读取必须保持为一个由后端负责的稳定操作时，协议消费方使用 `readTextBounded(target, maxBytes)`；组合 `stat` 与 `readText` 会容许文件增长与替换竞态。
 
 ```ts type-equiv
 /**
@@ -256,4 +258,4 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`readTextBounded`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 5d59f6fd16..fca7947aae 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 8189795c5acf2fc1882d9e5bc1c006f49c327e2f
-subprocess.zh.md: 370a1a05807eefbe09a896ea8bcca1e4ab0a6b83
+subprocess.md: eae497530ff54a7a259c23a2d0f665f3313488f5
+subprocess.zh.md: c3504ef7cd42448a15341f7f92d0f309a6216de1
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 8189795c5a..c866276b8e 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -2,9 +2,13 @@
 
 English | [中文](subprocess.zh.md)
 
-The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends — the [bash executor family](bash.md) (collect-mode batch output), the LSP host (piped protocol streams + a collected stderr tail), and the ACP subagent backend (piped protocol streams + inherited stderr). This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
+The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, the LSP and Code Runtime hosts use raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
 
-Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts)
+Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
+
+## Execution-world coordinates
+
+One provider's `cwd`, `runtimeRoot`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides. Consumers use `runtimeRoot` for private materialized helpers and never assume a host path exists in that world.
 
 ## Managed environment namespace and captured output
 
@@ -234,6 +238,12 @@ interface SubprocessOutcome {
 }
 ```
 
+## Terminal-process primitive
+
+`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns raw UTF-8 byte transport, foreground-process-group inspection and signalling, TERM-to-KILL cleanup, and whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
+
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, `terminate`, and `waitForExit`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
+
 ## Service behavior
 
-The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines `spawn` only; [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) is the local implementation (detached trees, per-disposition wiring, credential scrub, terminate-and-join disposal). See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the seam contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for the mechanics.
+The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with temporary runtime storage, detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 370a1a0580..c3504ef7cd 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -1,14 +1,18 @@
-# 子进程
+# 进程管理器
 
 [English](subprocess.md) | 中文
 
-子进程 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式（collect）的批量输出，LSP 主机使用管道化的协议流 + 收集的 stderr 尾部，ACP（Agent Client Protocol）subagent 后端则使用管道化的协议流 + inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 与 Code Runtime 主机使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
-源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts)
+源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
+
+## 执行世界坐标
+
+一个提供方的 `cwd`、`runtimeRoot`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。消费方使用 `runtimeRoot` 存放私有物化辅助程序，绝不假设该执行世界中存在某条宿主路径。
 
 ## 受管环境命名空间与捕获的输出
 
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的字符串条目形式到达，而显式的 `undefined` tombstone 会删除普通环境中已有的值。每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
+`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的条目形式到达，每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -32,7 +36,7 @@ interface CollectedOutput {
 }
 ```
 
-## Node 风格的 stdio 处置方式（disposition）
+## Node 形状的 stdio 处置方式（disposition）
 
 每条流的处置方式都显式给出，由各消费方自行选择：原始管道用于协议分帧（LSP JSON-RPC、ACP ndjson），inherit 用于直通的诊断输出，收集模式用于有界的批量输出；其中 spill 文件是可选的，因此诊断尾部（语言服务器的 stderr）可以只在内存中缓冲，不留下任何文件。
 
@@ -84,7 +88,7 @@ interface SubprocessStdio {
 
 ## 完全显式的 spawn spec
 
-该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的子进程服务默认值决定。`argv` 绝不经过 shell 解释。
+该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的进程管理器默认值决定。`argv` 绝不经过 shell 解释。
 
 ```ts type-equiv
 /**
@@ -101,11 +105,10 @@ interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Positive finite grace period in milliseconds, no greater than
-   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
-   * and for draining still-open collected pipes after the process exits (an
-   * inherited descriptor held by a surviving descendant cannot hold the
-   * outcome open indefinitely).
+   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
+   * escalation and for draining still-open collected pipes after the process
+   * exits (an inherited descriptor held by a surviving descendant cannot hold
+   * the outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -116,18 +119,19 @@ interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
-   * string is a deliberate caller opt-in, so a forwarded credential-shaped
-   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
-   * tombstone that removes an ordinary ambient entry from the child.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation:
+   * every entry is a deliberate caller opt-in, so a forwarded
+   * credential-shaped entry or a current `DSH_*` fact survives precisely
+   * because this layer merges after the scrub that drops its ambient
+   * namesake.
    */
-  env?: NodeJS.ProcessEnv | undefined
+  env?: Record<string, string> | undefined
 }
 ```
 
 ## 句柄：流、读取器与以进程树为范围的终止
 
-spawn 会立即返回一个活动句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树。这足以让消费方构建自己的拆卸阶梯；ACP 后端的 `disposeAcpChild` 以 stdin EOF 开始，即为仓库内模板。
+spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树——这足以让消费方构建自己的拆卸阶梯（ACP 后端以 stdin EOF 打头的 `disposeAcpChild` 即是模板）。
 
 ```ts type-equiv
 /**
@@ -234,6 +238,12 @@ interface SubprocessOutcome {
 }
 ```
 
+## 终端进程原语
+
+`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责原始 UTF-8 字节传输、前台进程组检查与信号发送、TERM→KILL 清理，以及整个会话的完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
+
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground`、`terminate` 和 `waitForExit`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
+
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 只定义 `spawn`；[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 是本地实现（detached 进程树、按处置方式接线的流、凭据清除、先终止再等待退出的 dispose（资源释放））。seam 契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，具体机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以临时运行时存储、detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
diff --git a/knip.json b/knip.json
index ede8b2c738..20bcb5ff2d 100644
--- a/knip.json
+++ b/knip.json
@@ -383,6 +383,16 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/code-runtime/code-runtime-subprocess": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
     "packages/llm/llm-deepseek": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 8aa9b92b91..c5be7e67d6 100644
--- 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: 229feae568ba6e40a9c633696097eff46fd5bc95
-README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
+README.md: 7fcd98bd19ca3291f0472af57841f2f763bb346f
+README.zh.md: 7c4aed9b343ec57001883e094ea3dd0d73e2a920
diff --git a/packages/README.md b/packages/README.md
index 229feae568..a711e4d303 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -19,7 +19,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and filesystem/subprocess backends | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index b84aef020a..41380317f8 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及文件系统／进程管理后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 590b79dcd1..3de3bc622e 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -34,7 +34,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
-The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
+The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The `./runtime-host` subpath shares type stripping, binding validation/dispatch, lossless JSON transport, and output accounting with sibling worker-based implementations; it is implementation support, not a plugin. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers remain source-private.
 
 ## Model Experience
 
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
new file mode 100644
index 0000000000..334bd82e38
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -0,0 +1,222 @@
+/** Shared host mechanics for local and subprocess-hosted TypeScript worker runtimes. */
+
+import { stripTypeScriptTypes } from 'node:module'
+import type {
+  CodeBindingNamespace,
+  CodeJsonValue,
+  CodeRunFailure,
+  CodeRunRequest,
+  CodeRunResult,
+} from '@deepseek-ai/dsh-code-runtime'
+import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
+import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+import type { WorkerJsonWire } from './worker-json.ts'
+
+/** Smallest cap that can represent an empty log array and failure message. */
+export const MIN_RUNTIME_OUTPUT_BYTES = 4
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+const RESERVED_WORDS = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
+  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
+  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
+  'private', 'protected', 'public', 'arguments', 'eval',
+])
+const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
+const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
+
+/** One validated binding call received from an isolated worker. */
+export interface RuntimeBindingCall {
+  /** Correlation id supplied by the isolated worker. */
+  readonly id: number
+  /** Injected namespace global. */
+  readonly global: string
+  /** Declared namespace function. */
+  readonly name: string
+  /** Untrusted lossless-JSON wire payload. */
+  readonly args: unknown
+}
+
+/** One host reply to an isolated worker binding call. */
+export type RuntimeBindingReply =
+  | { readonly type: 'reply'; readonly id: number; readonly ok: true; readonly value: WorkerJsonWire }
+  | { readonly type: 'reply'; readonly id: number; readonly ok: false; readonly message: string }
+
+/**
+ * Render an unknown thrown value without assuming it is an Error.
+ * @param error - thrown or rejected value.
+ * @returns the caller-facing diagnostic text.
+ */
+export function runtimeErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Strip erasable TypeScript while preserving the program's body coordinates.
+ * @param program - model-written async-function body.
+ * @returns JavaScript source with the wrapper removed.
+ */
+export function stripRuntimeProgram(program: string): string {
+  const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + program + STRIP_WRAP.suffix)
+  return stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
+}
+
+/**
+ * Validate binding globals and typed-error declarations shared by worker runtimes.
+ * @param request - code-runtime request carrying the namespaces.
+ * @param implementationName - package name used in seam-misuse diagnostics.
+ * @returns namespaces indexed by their injected global.
+ */
+export function validateRuntimeBindings(
+  request: CodeRunRequest,
+  implementationName: string,
+): Map<string, CodeBindingNamespace> {
+  const bindings = new Map<string, CodeBindingNamespace>()
+  for (const namespace of request.bindings) {
+    if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
+      throw new Error(`${implementationName}: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
+    }
+    if (namespace.global === 'console' || bindings.has(namespace.global)) {
+      throw new Error(`${implementationName}: duplicate binding global ${JSON.stringify(namespace.global)}`)
+    }
+    bindings.set(namespace.global, namespace)
+  }
+
+  const errorClassNames = new Set<string>()
+  for (const namespace of request.bindings) {
+    const descriptor = namespace.errorClass
+    if (descriptor === undefined) continue
+    if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
+      throw new Error(`${implementationName}: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
+    }
+    if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
+      throw new Error(`${implementationName}: duplicate injected global ${JSON.stringify(descriptor.name)}`)
+    }
+    if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
+      throw new Error(`${implementationName}: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
+    }
+    errorClassNames.add(descriptor.name)
+  }
+  return bindings
+}
+
+/**
+ * Resolve one untrusted worker call through a declared host binding.
+ * @param call - parsed call envelope from the isolated worker.
+ * @param bindings - namespaces returned by {@link validateRuntimeBindings}.
+ * @returns a lossless-JSON success or stable rejection reply.
+ */
+export async function invokeRuntimeBinding(
+  call: RuntimeBindingCall,
+  bindings: ReadonlyMap<string, CodeBindingNamespace>,
+): Promise<RuntimeBindingReply> {
+  const functions = bindings.get(call.global)?.functions
+  const fn = functions !== undefined && Object.hasOwn(functions, call.name) ? functions[call.name] : undefined
+  if (typeof fn !== 'function') {
+    return { type: 'reply', id: call.id, ok: false, message: `unknown binding ${JSON.stringify(`${call.global}.${call.name}`)}` }
+  }
+  const args = decodeWorkerJson(call.args)
+  if (args === undefined) {
+    return { type: 'reply', id: call.id, ok: false, message: 'binding arguments must be lossless JSON' }
+  }
+  try {
+    const resolved = await fn(args)
+    let value: CodeJsonValue | undefined
+    try {
+      value = snapshotCodeJsonValue(resolved)
+    } catch {
+      value = undefined
+    }
+    if (value === undefined) {
+      return { type: 'reply', id: call.id, ok: false, message: 'binding resolution must be lossless JSON' }
+    }
+    return { type: 'reply', id: call.id, ok: true, value: encodeWorkerJson(value) }
+  } catch (error: unknown) {
+    return { type: 'reply', id: call.id, ok: false, message: runtimeErrorMessage(error) }
+  }
+}
+
+/** One run's combined outer-output ledger; binding values never enter it. */
+export class RuntimeOutputLedger {
+  private bytes = 2
+  private entries = 0
+
+  /** @param maxBytes - hard cap for logs plus completion or failure payload. */
+  constructor(private readonly maxBytes: number) {}
+
+  /**
+   * Admit one exact log entry.
+   * @param text - candidate log entry.
+   * @param sink - ordered retained log list.
+   * @returns false when the hard cap was crossed.
+   */
+  admit(text: string, sink: string[]): boolean {
+    const separatorBytes = this.entries > 0 ? 1 : 0
+    const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
+    if (stringBytes === undefined) return false
+    this.bytes += stringBytes + separatorBytes
+    this.entries += 1
+    sink.push(text)
+    return true
+  }
+
+  /**
+   * Finalize a successful completion against the combined cap.
+   * @param logs - retained ordered logs.
+   * @param value - optional lossless-JSON completion.
+   * @returns the completion or output-limit result.
+   */
+  success(logs: string[], value?: CodeJsonValue): CodeRunResult {
+    if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
+    return { logs, ...value !== undefined ? { value } : {} }
+  }
+
+  /**
+   * Finalize one failure diagnostic against the combined cap.
+   * @param logs - retained ordered logs.
+   * @param error - structured runtime failure.
+   * @returns the failure or output-limit result.
+   */
+  failure(logs: string[], error: CodeRunFailure): CodeRunResult {
+    if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
+    return { logs, error }
+  }
+
+  /**
+   * Build an explicit output-limit failure with a fitting log prefix.
+   * @param logs - ordered logs observed before the limit.
+   * @returns bounded output-limit result.
+   */
+  limit(logs: string[]): CodeRunResult {
+    const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
+    const messageBytes = fullMessage.length + 2
+    const retained: string[] = []
+    let retainedBytes = 2
+    const logBudget = this.maxBytes - messageBytes
+    for (const text of logs) {
+      const separatorBytes = retained.length > 0 ? 1 : 0
+      const availableBytes = logBudget - retainedBytes - separatorBytes
+      const stringBytes = jsonStringBytesUpTo(text, availableBytes)
+      if (stringBytes !== undefined) {
+        retained.push(text)
+        retainedBytes += stringBytes + separatorBytes
+        continue
+      }
+      const prefix = truncateJsonStringBytes(text, availableBytes)
+      if (prefix.length > 0) {
+        const prefixBytes = jsonStringBytesUpTo(prefix, availableBytes)
+        /* v8 ignore next -- truncateJsonStringBytes guarantees the same bound. */
+        if (prefixBytes === undefined) throw new Error('output ledger produced an oversized log prefix')
+        retained.push(prefix)
+        retainedBytes += prefixBytes + separatorBytes
+      }
+      break
+    }
+    const message = truncateJsonStringBytes(fullMessage, this.maxBytes - retainedBytes)
+    return { logs: retained, error: { kind: 'output-limit', message } }
+  }
+}
+
+export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json
index 555b3d161e..340e68e848 100644
--- a/packages/code-runtime/code-runtime-worker/tsconfig.json
+++ b/packages/code-runtime/code-runtime-worker/tsconfig.json
@@ -8,9 +8,6 @@
     "src"
   ],
   "references": [
-    {
-      "path": "../../core/session"
-    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
index 1c40637722..dac6f12a65 100644
--- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts
+++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
@@ -1,9 +1,10 @@
 import { defineConfig } from 'tsdown'
 
 /**
- * Build the index and worker as separate single-entry bundles. The sibling `worker.cjs` is loaded
- * by file and must be CommonJS for pkg's VFS Worker hook. A multi-entry build emits an unlisted
- * shared chunk omitted by the package's exact `files` whitelist; separate builds inline it.
+ * Build the plugin, reusable runtime host, and worker as separate bundles. The
+ * sibling `worker.cjs` is loaded by file and must be CommonJS for pkg's VFS
+ * Worker hook. Separate builds inline shared implementation instead of
+ * emitting an unlisted chunk outside the exact `files` whitelist.
  */
 export default defineConfig([
   {
@@ -16,6 +17,16 @@ export default defineConfig([
     dts: false,
     clean: false,
   },
+  {
+    entry: ['lib/types/runtime-host.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
   {
     entry: ['lib/types/worker.js'],
     outDir: 'lib',
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index bb1c20d00a..7014bf517a 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
-- **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
+- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the filesystem/subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
+- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the filesystem/subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 0af12596cc..8620c38981 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -75,6 +75,14 @@ class RecordingFileSystem extends FileSystem {
     return { targetKey: FsTargetKey(absolute), displayPath: absolute }
   }
 
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
@@ -109,6 +117,12 @@ class RecordingFileSystem extends FileSystem {
     return this.entries.get(target.targetKey)?.content ?? ''
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    const text = await this.readText(target, signal)
+    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
+    return text
+  }
+
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index bf179462ee..c7b6df254e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -312,6 +312,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
         jsDoc: '/**\n * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a\n * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence\n * async even though the local backend only normalizes + realpaths.\n *\n * @param path - the path to resolve; relative paths resolve against `opts.cwd`.\n * @param opts - optional cwd override and cancellation signal.\n * @returns the stable target; the same file yields the same `targetKey`.\n */',
       },
+      {
+        signature: 'abstract processPath(target: FsTarget): string',
+        jsDoc: '/**\n * Return the canonical absolute path a subprocess in this filesystem\'s\n * execution world can open. The path is deliberately separate from\n * {@link FsTarget.targetKey}: consumers may pass this value to another OS\n * capability, but must continue treating the target key as opaque.\n * @param target - the resolved target whose process path is required.\n * @returns an absolute path in the backend\'s execution world.\n */',
+      },
+      {
+        signature: 'abstract fileUrl(target: FsTarget): string',
+        jsDoc: '/**\n * Return the canonical `file:` URI for a target in this filesystem\'s\n * execution world. Backends own URI encoding because the host platform may\n * differ from the execution platform.\n * @param target - the resolved target to encode.\n * @returns the target\'s canonical file URI.\n */',
+      },
+      {
+        signature: 'abstract contains(parent: FsTarget, child: FsTarget): boolean',
+        jsDoc: '/**\n * Test canonical containment without exposing or parsing backend target\n * keys. Both targets must come from this provider.\n * @param parent - canonical directory target.\n * @param child - canonical candidate target.\n * @returns true when `child` is `parent` or a descendant of it.\n */',
+      },
       {
         signature: 'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
         jsDoc: '/**\n * Return target metadata, or `undefined` when the target does not exist.\n * @param target - the resolved target to stat.\n * @param signal - aborts the metadata round-trip.\n * @returns metadata only, never content; undefined for an absent target.\n */',
@@ -324,6 +336,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
         jsDoc: '/**\n * Read the whole regular text file as a single decoded string.\n * @param target - the resolved target to read.\n * @param signal - aborts the read.\n * @returns the full decoded UTF-8 content.\n */',
       },
+      {
+        signature: 'abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>',
+        jsDoc: '/**\n * Read one regular UTF-8 text file through a backend-owned stable handle,\n * rejecting before more than `maxBytes` are retained. The size check and\n * bytes read are one operation: a caller must not emulate this with\n * {@link stat} followed by {@link readText}, which admits growth and path\n * replacement races between the two calls.\n * @param target - the resolved target to read.\n * @param maxBytes - positive safe-integer byte ceiling.\n * @param signal - aborts the open/read operation.\n * @returns the complete decoded text when it fits.\n */',
+      },
       {
         signature: 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
         jsDoc: '/**\n * Stream the whole regular text file as decoded text chunks (same text\n * semantics as {@link readText}, for large files). The backend owns\n * cross-chunk UTF-8 decoding and binary rejection so the policy layer never\n * touches raw bytes.\n * @param target - the resolved target to read.\n * @param signal - aborts the stream, including between chunks.\n * @returns the chunk iterable, decoded and validated like {@link readText}.\n */',
@@ -974,10 +990,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'subprocess',
     summary: 'Abstract subprocess service.',
     methods: [
+      {
+        signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+      },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
         jsDoc: '/**\n * Start one managed child process from a fully-specified spec; this seam\n * applies no defaults.\n * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.\n * @returns the live process handle (streams/readers, signalling, outcome promise).\n */',
       },
+      {
+        signature: 'abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>',
+        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
+      },
     ],
   },
   {
@@ -2879,6 +2903,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubprocessStdio',
     declaration: 'export interface SubprocessStdio {\n    stdin: SubprocessStdinMode;\n    stdout: SubprocessOutputMode;\n    stderr: SubprocessOutputMode;\n}',
   },
+  {
+    name: 'SubprocessTerminalForeground',
+    declaration: 'export interface SubprocessTerminalForeground {\n    processGroupId: number;\n    inputWaiting: boolean;\n}',
+  },
+  {
+    name: 'SubprocessTerminalHandle',
+    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: Uint8Array): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): void;\n    waitForExit(signal?: AbortSignal): Promise<boolean>;\n}',
+  },
+  {
+    name: 'SubprocessTerminalSignal',
+    declaration: 'export type SubprocessTerminalSignal = \'SIGINT\' | \'SIGTERM\' | \'SIGKILL\' | \'SIGTSTP\' | \'SIGHUP\';',
+  },
+  {
+    name: 'SubprocessTerminalSpawnSpec',
+    declaration: 'export interface SubprocessTerminalSpawnSpec {\n    argv: readonly string[];\n    cwd: string;\n    env?: Record<string, string> | undefined;\n    rows: number;\n    cols: number;\n    graceMs: number;\n    signal?: AbortSignal | undefined;\n}',
+  },
   {
     name: 'SurfaceEvent',
     declaration: 'export type SurfaceEvent = SessionEvent<SurfaceEventType> & {\n    surfaceOp: SurfaceOp;\n};',
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index e435f166ad..c1a381cb81 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 108d7d862a1dc6307268e2a93fa00789c952e440
-README.zh.md: 8b037cc3192bf6ceb0f0671d62911a8e035db24c
+README.md: b6adabd5744cb2b3dcee78b71815f8e95ba780f1
+README.zh.md: 0841f538932452921d2b0d7d9534f023672f241d
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 108d7d862a..b6adabd574 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -2,16 +2,19 @@
 
 English | [中文](README.zh.md)
 
-The filesystem capability family: provider seam, interchangeable backends, policy, and model-facing tools. All **product** packages.
+The filesystem stack: a provider seam (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`fs/`](fs/README.md) | Filesystem provider seam and policy-event vocabulary | `ctx.fs` |
-| [`fs-local/`](fs-local/README.md) | Local-filesystem backend | registers `ctx.fs` |
-| [`fs-sandbox/`](fs-sandbox/README.md) | Sandbox-enforcing backend | registers `ctx.fs` |
-| [`fs-policy/`](fs-policy/README.md) | Observed-state and mutation policy | `fs/*` listeners |
-| [`tool-fs/`](tool-fs/README.md) | Model-facing file tools | registers on `ctx.tools` |
-| [`tool-fs-search/`](tool-fs-search/README.md) | Process-backed discovery tools | registers on `ctx.tools` |
-| [`tool-str-replace-editor/`](tool-str-replace-editor/README.md) | Model-facing string-replacement editor | registers on `ctx.tools` |
+| `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
+| `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
+| `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
+| `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
+| `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
+| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-Backends replace one another behind `ctx.fs`; policy and tools consume the seam independently. Discovery remains process-backed instead of expanding the provider contract. Child READMEs own containment, mutation, schema, and timeout details.
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas — `fs-sandbox` is the first such replacement (an in-process path fence over the shared sandbox mode; see [the cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+
+## No timeouts on file IO
+
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 8b037cc319..0841f53893 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -1,17 +1,20 @@
-# fs/ - 文件系统能力家族
+# fs/：文件系统能力族
 
 [English](README.md) | 中文
 
-文件系统能力家族：提供方 seam、可互换后端、策略和面向模型工具。这些全是**产品**包。
+文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
 
-| 包 | 职责 | ctx key |
+| 包 | 角色 | ctx 键 |
 |---|---|---|
-| [`fs/`](fs/README.md) | 文件系统提供方 seam 和策略事件词汇 | `ctx.fs` |
-| [`fs-local/`](fs-local/README.md) | 本地文件系统后端 | 注册 `ctx.fs` |
-| [`fs-sandbox/`](fs-sandbox/README.md) | 强制执行沙箱的后端 | 注册 `ctx.fs` |
-| [`fs-policy/`](fs-policy/README.md) | 已观察状态和修改策略 | `fs/*` 监听器 |
-| [`tool-fs/`](tool-fs/README.md) | 面向模型的文件工具 | 注册到 `ctx.tools` |
-| [`tool-fs-search/`](tool-fs-search/README.md) | 基于进程的发现工具 | 注册到 `ctx.tools` |
-| [`tool-str-replace-editor/`](tool-str-replace-editor/README.md) | 面向模型的字符串替换编辑器 | 注册到 `ctx.tools` |
+| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
+| `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
+| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
+| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-后端可在 `ctx.fs` 后互相替换；策略和工具独立消费该 seam。发现功能仍由进程提供，不扩展提供方契约。子 README 负责围堵、修改、schema 和超时细节。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema；`fs-sandbox` 是第一个这样的替代实现（基于共享沙箱模式的进程内路径围栏；见[跨能力族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+
+## 文件 I/O 不设超时
+
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index cc14be584f..57d2a32f97 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-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/fs/fs-local/README.md
-README.md: 6d344fa3fef7f6bda6c0daa50184661156a925a7
-README.zh.md: 4c94de64561d805684f91f02d5b0dfc375f0d04f
+README.md: f5cf2441adcd62e55c6169ceb766f88382e314f5
+README.zh.md: 40f5a83626780bae8f335c80662721bae6cc0b0b
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 6d344fa3fe..f5cf2441ad 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eight `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the twelve `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,8 +15,9 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 ## Behavior
 
 - **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
+- **Execution-world coordinates** — `processPath` exposes the target's canonical host path, `fileUrl` encodes that path through Node's platform-aware URL conversion, and `contains` uses platform path semantics to test identity or descendant containment without consumers parsing `targetKey`.
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
-- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
+- **`readText` / `readTextBounded` / `streamText`** — UTF-8 only. `readText` reads the whole file; `readTextBounded` opens one no-follow, nonblocking handle, verifies it is regular, and retains at most `maxBytes + 1` bytes so growth cannot bypass the cap; `streamText` decodes chunks so a huge file need not be held whole in memory. All reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing; protocol consumers such as the LSP host use the stable bounded operation.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
@@ -35,7 +36,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`config.cwd` is not a sandbox** — it is a resolution default, not containment: absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall ([capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)).
 - **An overwrite reads the whole prior file into memory** — solely as the UI diff basis; bounding that pre-read above a size threshold is deferred (`TODO(overwrite-diff-bound)`).
-- **Version tokens are `mtimeMs:size`** — an external change that preserves both within the filesystem's timestamp granularity defeats the stale guard.
+- **Version tokens depend on filesystem metadata** — they combine device, inode, size, nanosecond mtime, and nanosecond ctime; a storage layer that cannot update any of those facts for a rewrite can still defeat the stale guard.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
 - **The per-target mutation lock is in-process only** — a writer in another process is caught only by the optional version guard, never serialized.
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 4c94de6456..40f5a83626 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持八个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十二个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,27 +15,28 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 ## 行为
 
 - **`resolve(path, opts?)`**：相对 `path` 在调用方提供 `opts.cwd` 时以该值为基准解析（面向模型的工具会传入调用 agent（智能体）的会话 cwd；见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)），否则以 `config.cwd` 为基准（默认 `process.cwd()`）；绝对 `path` 会忽略两者。`opts.signal` 会在本地解析前后检查，远程同级后端则可以用它中止往返。`targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径会共享一个身份，写入/编辑落在链接目标上，同时保留链接。尚不存在的路径在父目录存在时使用 realpath 后的父目录加 basename；只有父目录无法解析时才回退到绝对路径。`displayPath` 是绝对但未经解析的路径。
-- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此异步探测进行期间发生的中止会报告 `FS_ABORTED`，而非已失效的「不存在」结果。
-- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片流式读取（跨分片解码），因此超大文件无需整体保存在内存中。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）按大小决定调用哪个方法，并负责行窗口逻辑。
+- **执行世界坐标**：`processPath` 公开目标的规范化宿主路径，`fileUrl` 通过 Node 的平台感知 URL 转换对该路径编码，`contains` 则使用平台路径语义检查身份相等或后代包含关系，消费方无需解析 `targetKey`。
+- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
+- **`readText` / `readTextBounded` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`readTextBounded` 打开一个不跟随符号链接的非阻塞句柄，确认其为普通文件，并最多保留 `maxBytes + 1` 字节，使文件增长无法绕过上限；`streamText` 按分片解码，因此超大文件无需整体保存在内存中。三者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑；LSP 主机等协议消费方使用稳定的有界操作。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问策略得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选（OPTIONAL）的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
-- **`editText`**：在同一原语之上执行原子式的字面量读取-修改-写入，并通过变更锁按目标串行化。`expected` 防护是可选（OPTIONAL）的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
-包根目录的 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
+包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
 
 ## 模型体验
 
-通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方在有上限的保留结果中渲染本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息，而版本、原子写入机制和目录元数据仍属内部实现。
+通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方把本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息渲染为有上限且保留的结果，而版本、原子写入机制和目录元数据保持内部可见。
 
 #### KV Cache 影响
 
 不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **`config.cwd` 不是沙箱**：它是解析默认值，而非约束；绝对路径和 `..` 可以逃逸。请使用更严格的 `ctx.fs` 后端或 `tools/execute` waterfall（瀑布式事件）上的权限插件实施约束（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)）。
 - **覆盖会把整个旧文件读入内存**：只用于 UI diff；在大小阈值之上限制这次预读取的工作延期处理（`TODO(overwrite-diff-bound)`）。
-- **版本 token 是 `mtimeMs:size`**：如果外部变更在文件系统时间戳粒度内保持两者不变，就能绕过陈旧防护。
+- **版本 token 依赖文件系统元数据**：它们组合设备、inode、大小、纳秒级 mtime 和纳秒级 ctime；如果存储层在重写时无法更新其中任何一项事实，仍可能绕过陈旧防护。
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
 - **每目标变更锁仅限进程内**：其他进程中的写入方只会被可选版本防护发现，绝不会被串行化。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index c93e4ddaeb..e95cb14cca 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -6,7 +6,7 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { createReadStream } from 'node:fs'
+import { constants, createReadStream } from 'node:fs'
 import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
 import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
@@ -369,6 +369,77 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
   return decodeUtf8(raw, 'read', target.displayPath)
 }
 
+/**
+ * Read one regular UTF-8 file through a single no-follow handle, retaining at
+ * most `maxBytes + 1` bytes so a concurrent grow cannot bypass the bound.
+ * @param target - the resolved file to read.
+ * @param maxBytes - positive safe-integer byte ceiling.
+ * @param signal - aborts between handle operations.
+ * @returns the complete decoded text when it fits.
+ */
+export async function readWholeTextBounded(
+  target: LocalTarget,
+  maxBytes: number,
+  signal?: AbortSignal,
+): Promise<string> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('bounded read maxBytes must be a positive safe integer')
+  }
+  throwIfAborted(signal, 'read')
+  let handle: Awaited<ReturnType<typeof open>>
+  try {
+    handle = await open(
+      target.targetKey,
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+    )
+  } catch (error: unknown) {
+    if (isENOENT(error)) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+    if (isPermissionError(error)) throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
+    throw new FsError(`cannot read "${target.displayPath}" safely: ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
+  }
+  try {
+    throwIfAborted(signal, 'read')
+    const info = await handle.stat()
+    if (!info.isFile()) {
+      throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+    }
+    if (info.size > maxBytes) {
+      throw new FsError(
+        `cannot read "${target.displayPath}": ${info.size} bytes exceeds the ${maxBytes}-byte limit`,
+        'FS_IO_ERROR',
+      )
+    }
+    const chunks: Buffer[] = []
+    let total = 0
+    for (;;) {
+      throwIfAborted(signal, 'read')
+      // Allocate in fixed internal chunks so a permissive deployment cap does
+      // not reserve that entire cap for a small file. Once exactly at the
+      // bound, one final byte detects concurrent growth without retaining it.
+      const remaining = total === maxBytes ? 1 : Math.min(64 * 1024, maxBytes - total)
+      const chunk = Buffer.allocUnsafe(remaining)
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, total)
+      if (bytesRead === 0) break
+      total += bytesRead
+      if (total > maxBytes) {
+        throw new FsError(
+          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
+          'FS_IO_ERROR',
+        )
+      }
+      chunks.push(chunk.subarray(0, bytesRead))
+    }
+    throwIfAborted(signal, 'read')
+    const bytes = chunks.length === 1 ? chunks[0] as Buffer : Buffer.concat(chunks, total)
+    if (bytes.subarray(0, BINARY_SAMPLE_BYTES).includes(0)) {
+      throw new FsError(`cannot read "${target.displayPath}": binary file`, 'FS_NOT_TEXT')
+    }
+    return decodeUtf8(bytes, 'read', target.displayPath)
+  } finally {
+    await handle.close()
+  }
+}
+
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 18433f3f7c..1a266301db 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -5,7 +5,8 @@
  */
 
 import { Context } from 'cordis'
-import { resolve } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import z from 'schemastery'
 import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -27,6 +28,7 @@ import {
   readForEdit,
   readTextForDiff,
   readWholeText,
+  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -90,6 +92,19 @@ export class LocalFileSystem extends FileSystem {
     return { targetKey: local.targetKey, displayPath: local.displayPath }
   }
 
+  override processPath(target: FsTarget): string {
+    return String(target.targetKey)
+  }
+
+  override fileUrl(target: FsTarget): string {
+    return pathToFileURL(this.processPath(target)).href
+  }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    const path = relative(this.processPath(parent), this.processPath(child))
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
     const info = await probe(target.targetKey)
@@ -111,6 +126,10 @@ export class LocalFileSystem extends FileSystem {
     return readWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal)
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    return readWholeTextBounded({ displayPath: target.displayPath, targetKey: target.targetKey }, maxBytes, signal)
+  }
+
   override streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     return Promise.resolve(streamWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal))
   }
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 61e2c0e999..02beab7323 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -10,6 +10,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, unlink, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 import { FsVersion } from '@deepseek-ai/dsh-fs'
@@ -85,6 +86,20 @@ describe('resolve', () => {
 
     await expect(pending).rejects.toMatchObject({ code: 'FS_ABORTED' })
   })
+
+  it('projects process paths, file URLs, and canonical containment', async () => {
+    await mkdir(join(dir, 'nested'))
+    await writeFile(join(dir, 'nested', 'file.txt'), 'text')
+    const root = await fs.resolve('.')
+    const child = await fs.resolve('nested/file.txt')
+    const outside = await fs.resolve('..')
+
+    expect(fs.processPath(child)).toBe(await realpath(join(dir, 'nested', 'file.txt')))
+    expect(fs.fileUrl(child)).toBe(pathToFileURL(await realpath(join(dir, 'nested', 'file.txt'))).href)
+    expect(fs.contains(root, root)).toBe(true)
+    expect(fs.contains(root, child)).toBe(true)
+    expect(fs.contains(root, outside)).toBe(false)
+  })
 })
 
 describe('stat', () => {
@@ -203,6 +218,15 @@ describe('readText / streamText', () => {
     expect(await fs.readText(await fs.resolve('a.txt'))).toBe('one\ntwo\nthree')
   })
 
+  it('reads complete text through the stable byte bound', async () => {
+    await writeFile(join(dir, 'bounded.txt'), '€abc')
+    const target = await fs.resolve('bounded.txt')
+    expect(await fs.readTextBounded(target, 6)).toBe('€abc')
+    await expect(fs.readTextBounded(target, 5)).rejects.toThrow('exceeds the 5-byte limit')
+    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
+    await expect(fs.readTextBounded(target, 6, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+
   it('streams the same text', async () => {
     await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 15588e40b9..2c5fd7a8f4 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -5,7 +5,7 @@
  * policy and lives in `dsh-fs-policy`, so it is not tested here.
  */
 
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { chmod, mkdtemp, readFile, rename, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -17,6 +17,7 @@ import {
   probeNoFollow,
   readForEdit,
   readWholeText,
+  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -316,6 +317,66 @@ describe('readWholeText', () => {
   })
 })
 
+describe('readWholeTextBounded', () => {
+  it('rejects non-files, binary text, and initial oversize without a full read', async () => {
+    await expect(readWholeTextBounded(localTarget(dir), 10)).rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    await writeFile(join(dir, 'large'), '12345')
+    await expect(readWholeTextBounded(localTarget(join(dir, 'large')), 4)).rejects.toThrow('exceeds the 4-byte limit')
+    await writeFile(join(dir, 'binary'), Buffer.from([0x61, 0x00, 0x62]))
+    await expect(readWholeTextBounded(localTarget(join(dir, 'binary')), 3)).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+  })
+
+  it('detects growth past the bound on the same open handle', async () => {
+    const close = vi.fn(async () => {})
+    const read = vi.fn(async (buffer: Buffer, offset: number, length: number, position: number) => {
+      const bytes = position === 0 ? Buffer.from('abc') : Buffer.from('d')
+      bytes.copy(buffer, offset, 0, Math.min(length, bytes.length))
+      return { bytesRead: Math.min(length, bytes.length), buffer }
+    })
+    vi.resetModules()
+    vi.doMock('node:fs/promises', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('node:fs/promises')>()
+      return {
+        ...actual,
+        open: async () => ({
+          stat: async () => ({ isFile: () => true, size: 3 }),
+          read,
+          close,
+        }),
+      }
+    })
+    try {
+      const isolated = await import('../src/fsio.ts')
+      await expect(isolated.readWholeTextBounded(localTarget('/virtual/growing'), 3))
+        .rejects.toThrow('grew past the 3-byte limit')
+      expect(close).toHaveBeenCalledOnce()
+    } finally {
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+    }
+  })
+
+  it('translates permission and generic open failures', async () => {
+    const failure: { current: Error & { code?: string } } = { current: Object.assign(new Error('denied'), { code: 'EACCES' }) }
+    vi.resetModules()
+    vi.doMock('node:fs/promises', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('node:fs/promises')>()
+      return { ...actual, open: async () => { throw failure.current } }
+    })
+    try {
+      const isolated = await import('../src/fsio.ts')
+      await expect(isolated.readWholeTextBounded(localTarget('/virtual/denied'), 3))
+        .rejects.toMatchObject({ code: 'FS_PERMISSION_DENIED' })
+      failure.current = new Error('open broke')
+      await expect(isolated.readWholeTextBounded(localTarget('/virtual/broken'), 3))
+        .rejects.toMatchObject({ code: 'FS_IO_ERROR' })
+    } finally {
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+    }
+  })
+})
+
 describe('streamWholeText', () => {
   it('streams the whole file as decoded text', async () => {
     const file = join(dir, 'a.txt')
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index ddf57a98d0..4a0e675c0c 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 6c80cc22f6f28e792c3458df3390b241b51d8202
-README.zh.md: 4772d799221efbfff9667cbc8b9e1df6af07dcff
+README.md: 67079f795c705ab4c9cfa476e0458be04a48c6c8
+README.zh.md: d812a94fab9f4b7e9d15ff78bd1fea3bcc00c0d9
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 6c80cc22f6..67079f795c 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -2,20 +2,33 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, no-follow path metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read bounded or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
-This package is the provider-seam layer of the [filesystem family](../README.md). The [tool](../tool-fs/README.md), [policy](../fs-policy/README.md), and [local](../fs-local/README.md) and [sandboxed](../fs-sandbox/README.md) backends remain separate consumers and implementations; the capability-seam decisions own the split ([foundation](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [filesystem seam](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [provider split](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), [event gate](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)).
+This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
+
+| Layer | Package | Role |
+|---|---|---|
+| tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing `read`/`write`/`edit` schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
+| policy | `@deepseek-ai/dsh-fs-policy` | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
+| provider seam | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
+
+A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements eight primitives.
+A backend subclasses `FileSystem` and implements twelve primitives.
 
 | Member | Semantics |
 |---|---|
 | `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default), while `opts.signal` aborts a backend round-trip. Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
+| `processPath(target)` | Return the canonical absolute path that a subprocess in this provider's execution world can open. This is intentionally distinct from opaque `targetKey`. |
+| `fileUrl(target)` | Return the canonical `file:` URI in the execution world's platform syntax. The backend, not the host process, owns encoding. |
+| `contains(parent, child)` | Test canonical identity/descendant containment without exposing or parsing target keys. Both targets come from this provider. |
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
 | `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
+| `readTextBounded(target, maxBytes, signal?)` | Read one complete regular UTF-8 file through a backend-owned stable operation, rejecting before retaining more than `maxBytes`. Consumers must not emulate this with `stat` then `readText`, which admits growth and replacement races. |
 | `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
 | `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
@@ -37,10 +50,6 @@ This package declares three events (see the generated [events catalog](../../../
 
 `FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
-## No IO deadline
-
-Filesystem primitives accept an optional `AbortSignal` but arm no deadline. Local IO is only best-effort abortable: a timeout cannot force an in-progress `fsync` or `rename` to stop, so a fixed deadline would promise control the backend cannot provide. Process-backed discovery owns its separate timeout contract.
-
 ## Model Experience
 
 Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
@@ -52,6 +61,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
-- **Eight primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
-- **No IO deadline** — cancellation is best-effort at primitive boundaries.
+- **Twelve primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 4772d79922..d812a94fab 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,56 +2,65 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义后端提供的存储原语，包括路径解析、stat 元数据、不跟随链接的路径元数据、读取/流式读取文本、列出目录、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、有界或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
-本包是[文件系统家族](../README.md)中的提供方 seam 层。[工具](../tool-fs/README.md)、[策略](../fs-policy/README.md)、[本地](../fs-local/README.md)与[沙箱化](../fs-sandbox/README.md)后端分别作为消费方与实现保持独立；能力 seam 决策负责该拆分（[基础](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统 seam](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[提供方拆分](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)、[事件门禁](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）。
+本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
+
+| 层 | 包 | 角色 |
+|---|---|---|
+| 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
+| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
+
+未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
-后端继承 `FileSystem` 并实现八个原语。
+后端继承 `FileSystem` 并实现十二个原语。
 
 | 成员 | 语义 |
 |---|---|
 | `resolve(path, opts?)` | 把路径解析为稳定的 `FsTarget`（不透明 `targetKey`、`displayPath`）。`opts.cwd` 是相对 `path` 解析所依据的基准（调用方提供其会话工作区；绝对路径忽略该值；省略时使用后端默认值），`opts.signal` 则中止后端往返。该方法是异步的，因为远程后端可能需要 I/O。经不同路径到达的同一文件必须产生相同 `targetKey`。 |
+| `processPath(target)` | 返回该提供方执行世界中的子进程可以打开的规范化绝对路径。该路径有意与不透明的 `targetKey` 分离。 |
+| `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
+| `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
+| `readTextBounded(target, maxBytes, signal?)` | 通过后端自有的稳定操作读取一个完整的普通 UTF-8 文件，在保留超过 `maxBytes` 前拒绝。消费方不得以先 `stat` 再 `readText` 模拟此操作，因为那会容许文件增长与替换竞态。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）。 |
-| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列出操作失败。 |
+| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
 | `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 策略事件
+## `fs/*` 政策事件
 
-本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（瀑布式事件）（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是策略层
+## 提供方 seam，不是政策层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
 `FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整契约见 `src/types.ts`。
 
-## 无 I/O deadline
-
-文件系统原语接受可选 `AbortSignal`，但不会启动 deadline。本地 I/O 只能尽力取消：超时无法强制进行中的 `fsync` 或 `rename` 停止，因此固定 deadline 会承诺后端无法提供的控制能力。基于进程的发现功能拥有独立的超时契约。
-
 ## 模型体验
 
 通过 `dsh-tool-fs` 间接产生影响；该消费方把提供方文本和错误渲染为有界且保留的文件系统工具结果。
 
 #### KV Cache 影响
 
-不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
-- **只有八个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
-- **没有 I/O deadline**：取消只能在原语边界尽力执行。
+- **只有十二个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
+- **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index b43fa48c4b..8bb20ece18 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -1,8 +1,10 @@
 /**
- * Filesystem text-storage provider seam. Backends own stable target identity,
- * text decoding, binary rejection, and atomic mutations. Read windows and
- * observed-state policy stay in consumer and policy plugins; `editText` remains
- * here so version check, literal match, and rewrite share one critical section.
+ * Filesystem provider seam for one execution world. Backends own stable target
+ * identity, process paths and file URIs, containment, stable bounded text
+ * reads, decoding, binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText`
+ * remains here so version check, literal match, and rewrite share one critical
+ * section.
  * @module @deepseek-ai/dsh-fs
  */
 
@@ -83,7 +85,6 @@ export abstract class FileSystem extends Service {
     super(ctx, 'fs')
   }
 
-  /**
   /**
    * The sandbox mode this backend enforces on mutations BY DEFAULT, or
    * `undefined` when it does not confine at all — the capability fact the tool
@@ -111,6 +112,34 @@ export abstract class FileSystem extends Service {
    */
   abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
+  /**
+   * Return the canonical absolute path a subprocess in this filesystem's
+   * execution world can open. The path is deliberately separate from
+   * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+   * capability, but must continue treating the target key as opaque.
+   * @param target - the resolved target whose process path is required.
+   * @returns an absolute path in the backend's execution world.
+   */
+  abstract processPath(target: FsTarget): string
+
+  /**
+   * Return the canonical `file:` URI for a target in this filesystem's
+   * execution world. Backends own URI encoding because the host platform may
+   * differ from the execution platform.
+   * @param target - the resolved target to encode.
+   * @returns the target's canonical file URI.
+   */
+  abstract fileUrl(target: FsTarget): string
+
+  /**
+   * Test canonical containment without exposing or parsing backend target
+   * keys. Both targets must come from this provider.
+   * @param parent - canonical directory target.
+   * @param child - canonical candidate target.
+   * @returns true when `child` is `parent` or a descendant of it.
+   */
+  abstract contains(parent: FsTarget, child: FsTarget): boolean
+
   /**
    * Return target metadata, or `undefined` when the target does not exist.
    * @param target - the resolved target to stat.
@@ -143,6 +172,19 @@ export abstract class FileSystem extends Service {
    */
   abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
 
+  /**
+   * Read one regular UTF-8 text file through a backend-owned stable handle,
+   * rejecting before more than `maxBytes` are retained. The size check and
+   * bytes read are one operation: a caller must not emulate this with
+   * {@link stat} followed by {@link readText}, which admits growth and path
+   * replacement races between the two calls.
+   * @param target - the resolved target to read.
+   * @param maxBytes - positive safe-integer byte ceiling.
+   * @param signal - aborts the open/read operation.
+   * @returns the complete decoded text when it fits.
+   */
+  abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>
+
   /**
    * Stream the whole regular text file as decoded text chunks (same text
    * semantics as {@link readText}, for large files). The backend owns
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index 19ee033cce..92f1cfc37f 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -19,13 +19,18 @@ import type {
   FsWriteOutcome,
 } from '@deepseek-ai/dsh-fs'
 
-/** A minimal in-memory fake implementing the eight provider primitives. */
+/** A minimal in-memory fake implementing the provider primitives. */
 class FakeFileSystem extends FileSystem {
   files = new Map<string, string>()
 
   override async resolve(path: string): Promise<FsTarget> {
     return { targetKey: FsTargetKey(path), displayPath: path }
   }
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+  override fileUrl(target: FsTarget): string { return `file:///${encodeURIComponent(String(target.targetKey))}` }
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
   override async stat(target: FsTarget): Promise<FsInfo | undefined> {
     const content = this.files.get(target.targetKey)
     if (content === undefined) return undefined
@@ -41,6 +46,11 @@ class FakeFileSystem extends FileSystem {
     if (content === undefined) throw new FsError(`not found: ${target.displayPath}`, 'FS_NOT_FOUND')
     return content
   }
+  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
+    const content = await this.readText(target)
+    if (Buffer.byteLength(content) > maxBytes) throw new FsError('too large', 'FS_IO_ERROR')
+    return content
+  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = await this.readText(target)
     return (async function* () { yield content })()
@@ -75,6 +85,7 @@ describe('FileSystem provider seam', () => {
     const ctx = new Context()
     await ctx.plugin(FakeFileSystem)
     const fs = ctx.fs as FakeFileSystem
+    expect(fs.sandboxMode).toBeUndefined()
     fs.files.set('a.txt', 'hi')
     const target = await fs.resolve('a.txt')
     expect((await fs.stat(target))?.type).toBe('file')
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index ad01237c2b..f54701246a 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -48,6 +48,11 @@ class FakeFs extends FileSystem {
   override async resolve(path: string): Promise<FsTarget> {
     return { targetKey: FsTargetKey(`key:${path}`), displayPath: `/abs/${path}` }
   }
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
   override async stat(target: FsTarget): Promise<FsInfo | undefined> {
     this.throwIfArmed()
     const content = this.files.get(target.targetKey)
@@ -62,6 +67,11 @@ class FakeFs extends FileSystem {
   override async readText(target: FsTarget): Promise<string> {
     return this.files.get(target.targetKey) ?? ''
   }
+  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
+    const content = await this.readText(target)
+    if (Buffer.byteLength(content) > maxBytes) throw new Error('too large')
+    return content
+  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = this.files.get(target.targetKey) ?? ''
     return (async function* () { yield content })()
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index a41b05f148..9919cdaba5 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 4964d78f1096d1a4bc78fa80c6b5febaf24a5661
-README.zh.md: 93b872002cf1f53cdbb96ff42402bfeb9557575f
+README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
+README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 4964d78f10..7fbdf07173 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -6,8 +6,10 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`lsp/`](lsp/README.md) | LSP provider seam and shared vocabulary | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | Local stdio language-server backend | registers providers on `ctx.lsp` |
-| [`tool-lsp/`](tool-lsp/README.md) | Model-facing semantic-navigation tool | registers on `ctx.tools` |
+| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
+| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
-Providers register semantic capabilities; the tool owns the model-facing contract. The child READMEs document operation, protocol, and presentation details, while the [LSP capability-seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) owns the rationale.
+The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
+
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index 93b872002c..e059dbd80b 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -2,12 +2,14 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方和面向模型的 `lsp` 工具。这些全是**产品**包。
+语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`lsp/`](lsp/README.md) | LSP 提供方 seam 和共享词汇 | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | 本地 stdio 语言服务器后端 | 在 `ctx.lsp` 上注册提供方 |
-| [`tool-lsp/`](tool-lsp/README.md) | 面向模型的语义导航工具 | 注册到 `ctx.tools` |
+| `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
+| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-提供方注册语义能力；工具负责面向模型的契约。子 README 记录操作、协议和呈现细节，[LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)负责设计原理。
+接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+
+设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index b786ec1a60..1504e6f726 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-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/lsp/lsp-local/README.md
-README.md: 37676a82fb5d45b40ca86507259aca9509d25a43
-README.zh.md: 9e8b7f4f4395985bdbc29c1d911520b3559d7e0c
+README.md: 2c5ab309f3557ad77696a881b41d164e65bd24fe
+README.zh.md: d4493832964a5ac0d804602c18774bb106ddcbd9
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 37676a82fb..2c5ab309f3 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -2,18 +2,19 @@
 
 English | [中文](README.zh.md)
 
-A **generic local stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
+A **generic stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. It reads through `ctx.fs` and launches through `ctx.subprocess`, so the server and source always inhabit the mounted execution world. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
 
 Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 
 ## What it does
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
-- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
-- Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
+- Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
+- Uses a compatibility-first **transient-open** sequence per query: resolve and boundedly read the source through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
 - Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
-- Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
+- Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
+- Uses `ctx.fs` canonical containment, file URIs, and stable bounded reads, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
 
@@ -23,7 +24,7 @@ The `servers` record key is the stable provider id reserved on `ctx.lsp`; each v
 |---|---|---|
 | `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. |
 | `args` | `[]` | Arguments passed to the executable. |
-| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`PASSWORD`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
+| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
 | `extensionToLanguage` | (required) | Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). |
 | `initializationOptions` | `null` | Static `initialize` options forwarded to the server. |
 | `configuration` | `null` | Static answer to every `workspace/configuration` item. |
@@ -41,7 +42,7 @@ Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: {
 
 ## Security boundary
 
-The provider trusts its configured server and claims no sandbox confinement. It canonicalizes and reads source through Node APIs, rejecting a source that is missing, non-regular, non-UTF-8, oversized, or whose canonical path resolves outside the canonical workspace (symlink aliases share one instance). Result locations may be external, but an external path cannot become a query source. The first implementation therefore requires trusted host-local deployment; restricted, remote, or virtual workspaces require another provider.
+The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, no-follow/stable bounded reads, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
 
 ## Model Experience
 
@@ -53,6 +54,7 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)). Containment resolves `realpath`, then opens the source through one handle with `O_NOFOLLOW | O_NONBLOCK` (final-component symlink guard plus nonblocking rejection of FIFOs) and a bounded read; a concurrent mutator that swaps an *ancestor* directory for a symlink between the resolve and the open is an accepted residual TOCTOU under this trusted-deployment model, not closed with non-portable `openat` segment walks.
-- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; compatibility with one TypeScript server does not imply cross-language support.
+- **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
+- **Execution-world URI rendering** — the stdio host produces provider-owned `file:` URIs. The current model tool renders them with the harness host's path library, so a Windows harness paired with a POSIX remote execution world may show remote locations as URIs or non-native paths; protocol queries remain correct.
+- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 9e8b7f4f43..d449383296 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -2,18 +2,19 @@
 
 [English](README.md) | 中文
 
-`ctx.lsp` 的**通用本地 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，预设应放在 `cordis.yml` overlay 中。
+`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于所挂载的同一执行环境。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，preset 应放在 `cordis.yml` overlay 中。
 
 Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）。
 
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace realpath)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开**序列：通过 Node API 规范化并读取源文件、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
+- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析源文件并进行有界读取、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。
-- 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
-- 通过子进程 host namespace 中的 Node 文件系统 API 读取源文件，绝不使用 `ctx.fs`，也不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
+- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
+- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与稳定有界读取，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -23,13 +24,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 |---|---|---|
 | `command` | （必填） | 要 spawn 的可执行文件：绝对路径，或在加载时从子进程 PATH 解析。不使用 shell 启动。 |
 | `args` | `[]` | 传给可执行文件的参数。 |
-| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`PASSWORD`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
+| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
 | `extensionToLanguage` | （必填） | 小写、以点开头的扩展名 → LSP language id（例如 `{ '.ts': 'typescript' }`）。 |
 | `initializationOptions` | `null` | 转发给服务器的静态 `initialize` 选项。 |
 | `configuration` | `null` | 每个 `workspace/configuration` 配置项的静态答案。 |
 | `maxMessageBytes` | `16000000` | 从服务器接受的单条 framed 消息最大大小。 |
 | `maxStderrBytes` | `1000000` | 为诊断保留的 stderr 尾部最大大小。 |
-| `maxDocumentBytes` | `4000000` | 该主机可打开的源文件大小上限。 |
+| `maxDocumentBytes` | `4000000` | 该主机可打开的最大源文件。 |
 | `shutdownTimeoutMs` | `5000` | 升级前用于优雅 `shutdown`／`exit` 的预算。 |
 | `killGraceMs` | `2000` | 请求取消及 SIGTERM→SIGKILL 升级的宽限期。 |
 
@@ -37,11 +38,11 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 协议行为
 
-初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会以结构化 `LSP_MALFORMED_RESPONSE` 错误的形式失败。
+初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会作为结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
 
 ## 安全边界
 
-提供方信任其配置的服务器，不提供任何沙箱隔离。它通过 Node API 规范化并读取源文件，拒绝缺失、非普通文件、非 UTF-8、过大，或规范路径位于规范 Workspace 外部的源文件（符号链接别名共享一个实例）。结果位置可以在外部，但外部路径不能成为查询源。因此，第一版要求可信的主机本地部署；受限、远程或虚拟 Workspace 需要另一个提供方。
+提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、不跟随符号链接的稳定有界读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
 
 ## 模型体验
 
@@ -53,6 +54,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 已知限制与暂缓事项
 
-- **仅限可信主机本地环境**：没有沙箱隔离，也没有私有 cache／temp 写入契约；支持不受信任 binary 或受限／远程／虚拟 Workspace，需要后续的进程／文件系统契约及不同提供方（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。限制逻辑先解析 `realpath`，再通过一个带 `O_NOFOLLOW | O_NONBLOCK` 的 handle 打开源文件（最终组件符号链接防护，并以非阻塞方式拒绝 FIFO），同时进行有界读取；并发修改方如果在解析与打开之间把*祖先*目录替换为符号链接，会造成残余 TOCTOU。在该可信部署模型下接受此风险，不使用不可移植的 `openat` 逐 segment 遍历来封闭。
-- **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；与一个 TypeScript 服务器兼容，并不表示支持其他语言。
-- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent（智能体）会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到 dispose。
+- **不提供隔离策略**：这个包（package）信任配置的服务器，不会对其进程执行沙箱化；受限部署必须提供适当的进程／文件系统提供方，或包装同一执行环境的沙箱。
+- **执行环境 URI 渲染**：stdio 主机生成归提供方所有的 `file:` URI。当前面向模型的工具使用 harness 宿主的路径库渲染这些 URI，因此 Windows harness 与 POSIX 远程执行环境配对时，可能把远程位置显示为 URI 或非本机路径；协议查询仍然正确。
+- **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
+- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent 会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到释放。
diff --git a/packages/lsp/lsp-local/package.json b/packages/lsp/lsp-local/package.json
index b68745d617..a5411bab55 100644
--- a/packages/lsp/lsp-local/package.json
+++ b/packages/lsp/lsp-local/package.json
@@ -26,6 +26,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-lsp": "^0.0.1",
@@ -38,6 +39,8 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-lsp": "workspace:^",
diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index e19718eed6..4be75cbd33 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -22,7 +22,7 @@ export interface ConnectionSpec {
   readonly args: readonly string[]
   /** The child's working directory (the canonical workspace). */
   readonly cwd: string
-  /** The child's environment (credential-scrubbed, with overrides applied). */
+  /** Explicit child environment overrides; the subprocess provider owns its ambient scrub. */
   readonly env: Record<string, string>
   /** Largest single framed message accepted from the server. */
   readonly maxMessageBytes: number
@@ -98,9 +98,8 @@ export class LspConnection {
         stderr: { maxBytes: spec.maxStderrBytes },
       },
       graceMs: spec.killGraceMs,
-      // spec.env mixes the scrubbed base with explicit config entries; the
-      // seam merges the whole map after its own ambient scrub, so a
-      // configured DSH_* fact reaches the child.
+      // The seam merges explicit config entries after its ambient scrub, so a
+      // configured credential or DSH_* fact reaches the child deliberately.
       env: spec.env,
     })
     /* v8 ignore start -- 'pipe' dispositions expose both streams by the seam contract; defensive. */
diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index 11996908ac..3a2b9fbd7b 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -1,154 +1,106 @@
-/**
- * Host-filesystem source access for the local provider, using Node APIs directly in the
- * subprocess's namespace (never `ctx.fs`): only the LSP result is model-visible, so a query does not
- * satisfy read-before-write policy and emits no `fs/observed`. Canonicalization derives target
- * identity from `realpath`, so symlink aliases share a workspace; a source is rejected before server
- * startup when it is missing, non-regular, non-UTF-8, oversized, or canonically outside the
- * workspace. External result locations are allowed, but an external path can never become a query
- * source.
- * @module @deepseek-ai/dsh-lsp-local/host
- */
+/** Filesystem-seam source access for the generic stdio LSP provider. */
 
-import { constants } from 'node:fs'
-import { open, realpath, stat } from 'node:fs/promises'
-import type { FileHandle } from 'node:fs/promises'
-import { isAbsolute, resolve as resolvePath, sep } from 'node:path'
+import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs'
 import { throwIfAborted } from './abort.ts'
 
-/** A validated source: its canonical absolute path and current UTF-8 text. */
-export interface HostSource {
-  /** The canonical (realpath-resolved) absolute path, inside the canonical workspace. */
+/** A canonical workspace in the filesystem/subprocess execution world. */
+export interface HostWorkspace {
+  /** Stable filesystem identity used for provider pooling. */
+  readonly target: FsTarget
+  /** Canonical absolute path accepted as a subprocess cwd. */
   readonly canonicalPath: string
-  /** The file's current text, read as UTF-8. */
+  /** Canonical file URI sent during LSP initialization. */
+  readonly fileUrl: string
+}
+
+/** A validated source and the exact URI sent to the language server. */
+export interface HostSource {
+  /** Canonical file URI in the execution world's platform syntax. */
+  readonly fileUrl: string
+  /** Current complete UTF-8 text. */
   readonly text: string
 }
 
 /**
- * Canonicalize a workspace root: it must exist and be a directory. The returned realpath supplies
- * process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity, so symlinked roots
- * collapse to one instance.
- * @param workspaceRoot - the caller's workspace root (absolute).
- * @param signal - optional cancellation observed around each filesystem operation.
- * @returns the canonical directory path.
- * @throws Error when the path is missing or not a directory.
+ * Resolve and validate one workspace through `ctx.fs`.
+ * @param fs - filesystem provider sharing the language server's execution world.
+ * @param workspaceRoot - caller-supplied workspace path.
+ * @param signal - optional cancellation around provider operations.
+ * @returns stable identity plus process path and file URI.
  */
-export async function canonicalizeWorkspace(workspaceRoot: string, signal?: AbortSignal): Promise<string> {
+export async function canonicalizeWorkspace(
+  fs: FileSystem,
+  workspaceRoot: string,
+  signal?: AbortSignal,
+): Promise<HostWorkspace> {
   throwIfAborted(signal)
-  let canonical: string
+  let target: FsTarget
   try {
-    canonical = await realpath(workspaceRoot)
-  } catch (error) {
-    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`)
+    target = await fs.resolve(workspaceRoot, signal === undefined ? {} : { signal })
+  } catch (error: unknown) {
+    throwIfAborted(signal)
+    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  const info = await stat(canonical)
+  const info = await fs.stat(target, signal)
   throwIfAborted(signal)
-  if (!info.isDirectory()) {
+  if (info?.type !== 'directory') {
     throw new Error(`workspace root "${workspaceRoot}" is not a directory`)
   }
-  return canonical
+  return {
+    target,
+    canonicalPath: fs.processPath(target),
+    fileUrl: fs.fileUrl(target),
+  }
 }
 
 /**
- * Resolve, canonicalize, validate, and read a query source in one pass. A relative `filePath`
- * resolves against `canonicalWorkspace`; an absolute one is taken directly. The canonical target
- * must be a regular UTF-8 file no larger than `maxDocumentBytes`, and must lie inside the canonical
- * workspace.
- * @param filePath - the model-supplied source path (relative or absolute).
- * @param canonicalWorkspace - the already-canonicalized workspace root.
- * @param maxDocumentBytes - the largest source this host will open.
- * @param signal - optional cancellation observed throughout resolution, validation, and reading.
- * @returns the canonical path and current UTF-8 text.
- * @throws Error when the source is missing, non-regular, oversized, non-UTF-8, or out of workspace.
+ * Resolve, contain, and atomically read one bounded query source through
+ * `ctx.fs`. The provider's bounded read owns stable-handle and no-follow
+ * mechanics; this layer owns only LSP-facing validation and messages.
+ * @param fs - filesystem provider sharing the server's execution world.
+ * @param filePath - absolute source path or path relative to `workspace`.
+ * @param workspace - already-canonical workspace.
+ * @param maxDocumentBytes - largest complete source accepted by this host.
+ * @param signal - optional cancellation.
+ * @returns canonical file URI and current text.
  */
 export async function readHostSource(
+  fs: FileSystem,
   filePath: string,
-  canonicalWorkspace: string,
+  workspace: HostWorkspace,
   maxDocumentBytes: number,
   signal?: AbortSignal,
 ): Promise<HostSource> {
   throwIfAborted(signal)
-  const requested = isAbsolute(filePath) ? filePath : resolvePath(canonicalWorkspace, filePath)
-  let canonicalPath: string
+  let target: FsTarget
   try {
-    canonicalPath = await realpath(requested)
-  } catch (error) {
-    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`)
+    target = await fs.resolve(filePath, {
+      cwd: workspace.canonicalPath,
+      ...signal === undefined ? {} : { signal },
+    })
+  } catch (error: unknown) {
+    throwIfAborted(signal)
+    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  if (!isInside(canonicalWorkspace, canonicalPath)) {
+  if (!fs.contains(workspace.target, target)) {
     throw new Error(`source "${filePath}" resolves outside the workspace`)
   }
-  // Open ONE handle after containment, then stat and read through it: a concurrent replace between
-  // realpath and read cannot swap the target, so the regular-file and size checks bind the bytes we
-  // actually read (no path-based TOCTOU). O_NOFOLLOW rejects the final component being swapped for a
-  // symlink between realpath and open (which would otherwise escape the workspace).
-  // O_NONBLOCK prevents a FIFO with no writer from hanging before fstat can reject it as nonregular.
-  const handle = await open(canonicalPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  let text: string
   try {
+    text = await fs.readTextBounded(target, maxDocumentBytes, signal)
+  } catch (error: unknown) {
     throwIfAborted(signal)
-    const info = await handle.stat()
-    throwIfAborted(signal)
-    if (!info.isFile()) {
-      throw new Error(`source "${filePath}" is not a regular file`)
-    }
-    if (info.size > maxDocumentBytes) {
-      throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-    }
-    // Bound the read to the cap even if the file grew after stat: read one extra byte and reject on
-    // overflow, so a concurrent grow cannot defeat the memory bound.
-    const buffer = await readCapped(handle, maxDocumentBytes, filePath, signal)
-    const text = decodeUtf8Strict(buffer, filePath)
-    throwIfAborted(signal)
-    return { canonicalPath, text }
-  } finally {
-    await handle.close()
+    throw new Error(`source "${filePath}" could not be opened safely: ${messageOf(error)}`, { cause: error })
+  }
+  throwIfAborted(signal)
+  return {
+    fileUrl: fs.fileUrl(target),
+    text,
   }
 }
 
-/** Read at most `maxBytes` from the handle, rejecting when the source overflows the cap. */
-async function readCapped(
-  handle: FileHandle,
-  maxBytes: number,
-  filePath: string,
-  signal?: AbortSignal,
-): Promise<Buffer> {
-  const limit = maxBytes + 1
-  const chunk = Buffer.allocUnsafe(limit)
-  let total = 0
-  for (;;) {
-    throwIfAborted(signal)
-    const { bytesRead } = await handle.read(chunk, total, limit - total, total)
-    throwIfAborted(signal)
-    if (bytesRead === 0) break
-    total += bytesRead
-    /* v8 ignore next 3 -- overflow requires the file to grow past the cap between stat and read (a concurrent mutation); defensive. */
-    if (total > maxBytes) {
-      throw new Error(`source "${filePath}" grew past the ${maxBytes}-byte limit while reading`)
-    }
-  }
-  return chunk.subarray(0, total)
-}
-
-/** Whether `child` is the workspace itself or a descendant of it (both already canonical). */
-function isInside(workspace: string, child: string): boolean {
-  if (child === workspace) return true
-  /* v8 ignore next -- a canonical non-root workspace never ends with a separator; the guard covers the filesystem root. */
-  const base = workspace.endsWith(sep) ? workspace : workspace + sep
-  return child.startsWith(base)
-}
-
-/** Decode strictly as UTF-8: a fatal decoder rejects only malformed bytes, keeping a legitimate U+FFFD. */
-function decodeUtf8Strict(buffer: Buffer, filePath: string): string {
-  try {
-    return new TextDecoder('utf-8', { fatal: true }).decode(buffer)
-  } catch {
-    throw new Error(`source "${filePath}" is not valid UTF-8 text`)
-  }
-}
-
-/** Extract a message from an unknown thrown value without leaking `any`. */
 function messageOf(error: unknown): string {
-  /* v8 ignore next -- Node fs rejections are always Error instances; the String() fallback is defensive. */
   return error instanceof Error ? error.message : String(error)
 }
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index d926ae9428..d12e8986fc 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -1,18 +1,16 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace realpath, serves transient-open queries
+ * single-flights one server process per canonical workspace target, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
- * and trust their configured servers — no sandbox confinement.
+ * query. Providers read sources through `ctx.fs` and launch servers through
+ * `ctx.subprocess`, so both local and remote implementations share one host.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
-import { accessSync, constants, statSync } from 'node:fs'
-import { delimiter, isAbsolute, join } from 'node:path'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -24,9 +22,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
+import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -46,10 +44,7 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['lsp', 'subprocess']
-
-/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
-
+export const inject = ['fs', 'lsp', 'subprocess']
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -91,6 +86,7 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
+type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -114,23 +110,28 @@ export const Config: z<Config> = z.object({
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context (must inject `lsp`).
+ * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export function apply(ctx: Context, config: Config): void {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = entries.map(([providerId, rawConfig]) => {
+  const providers = await Promise.all(entries.map(async ([providerId, rawConfig]) => {
     if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
     const resolved = rawConfig as ResolvedServerConfig
     validateServerConfig(providerId, resolved)
-    const childEnv = buildChildEnv(resolved.env)
-    const executable = resolveExecutable(resolved.command, childEnv)
-    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
-  })
+    const executable = await ctx.subprocess.resolveExecutable(resolved.command, resolved.env)
+    return new LocalLspProvider(
+      providerId,
+      ctx.fs,
+      resolved,
+      executable,
+      spec => ctx.subprocess.spawn(spec),
+    )
+  }))
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -180,16 +181,16 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per canonical workspace realpath. */
-  private readonly instances = new Map<string, LspInstance>()
+  /** One live instance per stable canonical workspace identity. */
+  private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<string, Promise<void>>()
+  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
   private disposed = false
 
   constructor(
     providerId: string,
+    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
-    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -211,19 +212,20 @@ class LocalLspProvider implements LspProvider {
   }
 
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
+    const workspace = await canonicalizeWorkspace(this.fs, request.workspaceRoot, signal)
     this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
+    const workspaceKey = workspace.target.targetKey
+    return this.enqueue(workspaceKey, signal, async () => {
       this.assertActive(signal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, signal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
       this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
+      let instance = this.instanceFor(workspaceKey, workspace)
       try {
         return await instance.query(request, source, signal)
       } catch (error) {
@@ -231,22 +233,22 @@ class LocalLspProvider implements LspProvider {
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspace, instance)
+        this.evictIfCurrent(workspaceKey, instance)
         this.assertActive(signal)
-        instance = this.instanceFor(workspace)
+        instance = this.instanceFor(workspaceKey, workspace)
         return await instance.query(request, source, signal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspace, instance)
+          this.evictIfCurrent(workspaceKey, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -260,27 +262,28 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspace: string): LspInstance {
+  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspace)
+    const existing = this.instances.get(workspaceKey)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
+    this.instances.set(workspaceKey, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: string, instance: LspInstance): void {
+  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: string): LspInstance {
+  private createInstance(workspace: HostWorkspace): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace,
-      env: this.childEnv,
+      cwd: workspace.canonicalPath,
+      workspaceUri: workspace.fileUrl,
+      env: this.config.env,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
@@ -304,41 +307,3 @@ class LocalLspProvider implements LspProvider {
     this.queues.clear()
   }
 }
-
-/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
-function buildChildEnv(extra: Record<string, string>): Record<string, string> {
-  return { ...scrubbedParentEnv(), ...extra }
-}
-
-/**
- * Resolve the server executable to an absolute path: an absolute command is verified directly; a
- * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
- */
-function resolveExecutable(command: string, childEnv: Record<string, string>): string {
-  if (isAbsolute(command)) {
-    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
-    if (!isExecutableFileSync(command)) {
-      throw new Error(`lsp-local: command "${command}" is not an executable file`)
-    }
-    return command
-  }
-  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
-  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
-  for (const dir of pathValue.split(delimiter)) {
-    if (dir === '') continue
-    const candidate = join(dir, command)
-    if (isExecutableFileSync(candidate)) return candidate
-  }
-  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
-}
-
-/** Synchronous regular-file and executable check used only at load-time resolution. */
-function isExecutableFileSync(path: string): boolean {
-  try {
-    if (!statSync(path).isFile()) return false
-    accessSync(path, constants.X_OK)
-    return true
-  } catch {
-    return false
-  }
-}
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index c1f78eaa38..8584f64f48 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -7,7 +7,6 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
-import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -31,6 +30,8 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
+  /** Canonical workspace file URI supplied by the filesystem provider. */
+  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
@@ -108,9 +109,11 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      processId: process.pid,
-      rootUri: pathToFileURL(this.spec.cwd).href,
-      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
+      // A subprocess provider may run in another PID namespace or machine;
+      // the host PID would let the server monitor an unrelated process.
+      processId: null,
+      rootUri: this.spec.workspaceUri,
+      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -147,7 +150,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = pathToFileURL(source.canonicalPath).href
+    const uri = source.fileUrl
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
diff --git a/packages/lsp/lsp-local/tests/built-lib.e2e.ts b/packages/lsp/lsp-local/tests/built-lib.e2e.ts
index bdd0ec1067..75f9f227c3 100644
--- a/packages/lsp/lsp-local/tests/built-lib.e2e.ts
+++ b/packages/lsp/lsp-local/tests/built-lib.e2e.ts
@@ -16,8 +16,9 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 
 const pkgDir = fileURLToPath(new URL('..', import.meta.url))
 const seamLib = join(pkgDir, '../lsp/lib/index.js')
+const fsLib = join(pkgDir, '../../fs/fs-local/lib/index.js')
 const subprocessLib = join(pkgDir, '../../subprocess/subprocess-local/lib/index.js')
-const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) && existsSync(subprocessLib)
+const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) && existsSync(fsLib) && existsSync(subprocessLib)
 
 const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
 
@@ -42,10 +43,12 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {
       const { Context } = await import('cordis')
       const { default: Lsp } = await import('@deepseek-ai/dsh-lsp')
       const LspLocal = await import('@deepseek-ai/dsh-lsp-local')
+      const { default: LocalFileSystem } = await import('@deepseek-ai/dsh-fs-local')
       const { default: LocalSubprocessService } = await import('@deepseek-ai/dsh-subprocess-local')
       const ctx = new Context()
       await ctx.plugin(Lsp)
       await ctx.plugin(LocalSubprocessService)
+      await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
       await ctx.plugin(LspLocal, {
         servers: {
           fake: {
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index 26aacdc1f4..cd7ed87e17 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -4,7 +4,10 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { realpath } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
+import { Context } from 'cordis'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import { canonicalizeWorkspace, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 
@@ -12,84 +15,105 @@ const execFileAsync = promisify(execFile)
 
 let root: string
 let ws: string
+let ctx: Context
+let fs: LocalFileSystem
 
 beforeEach(async () => {
   root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-host-')))
   ws = join(root, 'ws')
   await mkdir(ws)
+  ctx = new Context()
+  await ctx.plugin(LocalFileSystem, { cwd: root })
+  fs = ctx.fs as LocalFileSystem
 })
 
 afterEach(async () => {
+  await ctx.fiber.dispose()
   await rm(root, { recursive: true, force: true })
 })
 
 const BIG = 1_000_000
 
+async function workspace() {
+  return await canonicalizeWorkspace(fs, ws)
+}
+
+async function readSource(filePath: string, maxBytes = BIG, signal?: AbortSignal) {
+  return await readHostSource(fs, filePath, await workspace(), maxBytes, signal)
+}
+
 describe('canonicalizeWorkspace', () => {
   it('returns the realpath of a directory', async () => {
-    expect(await canonicalizeWorkspace(ws)).toBe(ws)
+    expect((await workspace()).canonicalPath).toBe(ws)
   })
 
   it('resolves a symlinked workspace to its target so aliases share identity', async () => {
     const link = join(root, 'ws-link')
     await symlink(ws, link)
-    expect(await canonicalizeWorkspace(link)).toBe(ws)
+    expect((await canonicalizeWorkspace(fs, link)).canonicalPath).toBe(ws)
   })
 
   it('rejects a missing workspace', async () => {
-    await expect(canonicalizeWorkspace(join(root, 'nope'))).rejects.toThrow(/cannot be resolved/)
+    await expect(canonicalizeWorkspace(fs, join(root, 'nope'))).rejects.toThrow(/not a directory/)
   })
 
   it('rejects a non-directory workspace', async () => {
     const file = join(root, 'file.txt')
     await writeFile(file, 'x')
-    await expect(canonicalizeWorkspace(file)).rejects.toThrow(/not a directory/)
+    await expect(canonicalizeWorkspace(fs, file)).rejects.toThrow(/not a directory/)
   })
 })
 
 describe('readHostSource', () => {
   it('reads a relative path against the workspace', async () => {
     await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
-    const source = await readHostSource('a.ts', ws, BIG)
-    expect(source.canonicalPath).toBe(join(ws, 'a.ts'))
+    const source = await readSource('a.ts')
+    expect(source.fileUrl).toBe(pathToFileURL(join(ws, 'a.ts')).href)
     expect(source.text).toBe('const x = 1\n')
   })
 
   it('reads an absolute path inside the workspace', async () => {
     const abs = join(ws, 'b.ts')
     await writeFile(abs, 'b')
-    const source = await readHostSource(abs, ws, BIG)
-    expect(source.canonicalPath).toBe(abs)
+    const source = await readSource(abs)
+    expect(source.fileUrl).toBe(pathToFileURL(abs).href)
   })
 
   it('accepts a source reached through a symlink that stays inside the workspace', async () => {
     await mkdir(join(ws, 'real'))
     await writeFile(join(ws, 'real', 'c.ts'), 'c')
     await symlink(join(ws, 'real'), join(ws, 'linked'))
-    const source = await readHostSource('linked/c.ts', ws, BIG)
-    expect(source.canonicalPath).toBe(join(ws, 'real', 'c.ts'))
+    const source = await readSource('linked/c.ts')
+    expect(source.fileUrl).toBe(pathToFileURL(join(ws, 'real', 'c.ts')).href)
   })
 
   it('rejects a source whose canonical path escapes the workspace via symlink', async () => {
     const outside = join(root, 'outside.ts')
     await writeFile(outside, 'secret')
     await symlink(outside, join(ws, 'escape.ts'))
-    await expect(readHostSource('escape.ts', ws, BIG)).rejects.toThrow(/outside the workspace/)
+    await expect(readSource('escape.ts')).rejects.toThrow(/outside the workspace/)
   })
 
   it('rejects an absolute source outside the workspace', async () => {
     const outside = join(root, 'out.ts')
     await writeFile(outside, 'x')
-    await expect(readHostSource(outside, ws, BIG)).rejects.toThrow(/outside the workspace/)
+    await expect(readSource(outside)).rejects.toThrow(/outside the workspace/)
   })
 
   it('rejects a missing source', async () => {
-    await expect(readHostSource('nope.ts', ws, BIG)).rejects.toThrow(/cannot be resolved/)
+    await expect(readSource('nope.ts')).rejects.toThrow(/not found/)
+  })
+
+  it('wraps a provider failure while resolving the source', async () => {
+    const canonical = await workspace()
+    fs.resolve = async () => { throw 'raw resolve failure' }
+    await expect(readHostSource(fs, 'broken.ts', canonical, BIG))
+      .rejects.toThrow('source "broken.ts" cannot be resolved: raw resolve failure')
   })
 
   it('rejects a non-regular source (directory)', async () => {
     await mkdir(join(ws, 'dir'))
-    await expect(readHostSource('dir', ws, BIG)).rejects.toThrow(/not a regular file/)
+    await expect(readSource('dir')).rejects.toThrow(/not a regular file/)
   })
 
   // Windows has no filesystem FIFO; the directory case above pins non-regular rejection there.
@@ -97,36 +121,36 @@ describe('readHostSource', () => {
     const fifo = join(ws, 'pipe.ts')
     await execFileAsync('mkfifo', [fifo])
     using d = deadline(undefined, 1000, 'FIFO_READ_TIMEOUT')
-    await expect(readHostSource('pipe.ts', ws, BIG, d.signal)).rejects.toThrow(/not a regular file/)
+    await expect(readSource('pipe.ts', BIG, d.signal)).rejects.toThrow(/not a regular file/)
   })
 
   it('honors a pre-aborted source read before filesystem work', async () => {
     const controller = new AbortController()
     controller.abort(new Error('source read cancelled'))
-    await expect(readHostSource('missing.ts', ws, BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
+    await expect(readSource('missing.ts', BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
   })
 
   it('treats the workspace root itself as inside, then rejects it as non-regular', async () => {
-    // filePath '.' canonicalizes to the workspace dir: isInside's identity branch is taken, and the
-    // directory then fails the regular-file check.
-    await expect(readHostSource('.', ws, BIG)).rejects.toThrow(/not a regular file/)
+    // The filesystem containment primitive accepts the workspace itself; the
+    // bounded read then rejects the directory as non-regular.
+    await expect(readSource('.')).rejects.toThrow(/not a regular file/)
   })
 
   it('rejects an oversized source', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
-    await expect(readHostSource('big.ts', ws, 10)).rejects.toThrow(/over the 10-byte limit/)
+    await expect(readSource('big.ts', 10)).rejects.toThrow(/10-byte limit/)
   })
 
   it('rejects a non-UTF-8 source', async () => {
     await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00]))
-    await expect(readHostSource('bin.ts', ws, BIG)).rejects.toThrow(/not valid UTF-8/)
+    await expect(readSource('bin.ts')).rejects.toThrow(/invalid UTF-8|binary file/)
   })
 
   it('keeps a valid U+FFFD replacement character in otherwise-valid UTF-8', async () => {
     // The literal replacement char is valid UTF-8; a fatal decoder must accept it (only malformed
     // byte sequences are rejected).
     await writeFile(join(ws, 'repl.ts'), 'const s = "�"\n')
-    const source = await readHostSource('repl.ts', ws, BIG)
+    const source = await readSource('repl.ts')
     expect(source.text).toBe('const s = "�"\n')
   })
 })
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 75b9e541fc..3027cbbd29 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -3,6 +3,8 @@ import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promi
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL, fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 import { encodeMessage } from '@deepseek-ai/dsh-lsp-local'
 import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
@@ -15,6 +17,8 @@ const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.u
 
 let root: string
 let ws: string
+let ctx: Context
+let fs: LocalFileSystem
 let live: LspInstance[] = []
 
 beforeEach(async () => {
@@ -22,11 +26,15 @@ beforeEach(async () => {
   ws = join(root, 'ws')
   await mkdir(ws)
   await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+  ctx = new Context()
+  await ctx.plugin(LocalFileSystem, { cwd: root })
+  fs = ctx.fs as LocalFileSystem
 })
 
 afterEach(async () => {
   for (const instance of live) await instance.dispose()
   live = []
+  await ctx.fiber.dispose()
   await rm(root, { recursive: true, force: true })
 })
 
@@ -39,6 +47,7 @@ function makeInstance(
     command: process.execPath,
     args: [fixtureServer],
     cwd: ws,
+    workspaceUri: pathToFileURL(ws).href,
     env: { ...scrubbedParentEnv(), ...env },
     configuration: { setting: 42 },
     initializationOptions: { init: true },
@@ -58,7 +67,12 @@ function query(operation: LspProviderQuery['operation'] = 'goToDefinition'): Lsp
 
 /** Run a query against an instance, reading the source first the way the provider does. */
 async function run(instance: LspInstance, operation: LspProviderQuery['operation'] = 'goToDefinition', signal?: AbortSignal): Promise<LspQueryResult> {
-  const source = await readHostSource('a.ts', ws, 4_000_000)
+  const workspace = {
+    target: await fs.resolve(ws),
+    canonicalPath: ws,
+    fileUrl: pathToFileURL(ws).href,
+  }
+  const source = await readHostSource(fs, 'a.ts', workspace, 4_000_000)
   return instance.query(query(operation), source, signal)
 }
 
@@ -68,6 +82,7 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     command: process.execPath,
     args: ['-e', script],
     cwd: ws,
+    workspaceUri: pathToFileURL(ws).href,
     env: scrubbedParentEnv(),
     configuration: null,
     initializationOptions: null,
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index ccd85a1e14..a7a006c06e 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -8,6 +8,7 @@ import { Context } from 'cordis'
 import Lsp, { type LspProvider, type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
 
@@ -47,6 +48,7 @@ async function mount(
   const ctx = new Context()
   await ctx.plugin(Lsp)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   const register = ctx.lsp.registerProvider.bind(ctx.lsp)
   const registrationSpy = captureProvider === undefined
     ? undefined
@@ -79,6 +81,7 @@ describe('lsp-local end to end over a fake server', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await ctx.plugin(LspLocal, {
       servers: {
         typescript: fakeServer({ LSP_FAKE_HOVER: JSON.stringify({ contents: 'ts' }) }),
@@ -322,6 +325,7 @@ describe('lsp-local end to end over a fake server', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         missing: {
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index 77fcbe7851..b0209e09b8 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { Config, LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
@@ -44,6 +45,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('onpath', {
       command: 'fake-lsp',
       args: [],
@@ -57,6 +59,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('nope', {
       command: 'fake-lsp',
       args: [],
@@ -71,6 +74,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     // Grab the provider instance by registering, then dispose the whole plugin fiber.
     const lsp = ctx.lsp
     const fiber = await ctx.plugin(LspLocal, config('disp', {
@@ -88,6 +92,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-budget', {
       command: process.execPath,
       args: ['-e', ''],
@@ -101,6 +106,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-cap', {
       command: process.execPath,
       args: ['-e', ''],
@@ -114,6 +120,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-timer', {
       command: process.execPath,
       args: ['-e', ''],
@@ -130,6 +137,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('abs-bad', {
       command: notExe,
       args: [],
@@ -142,6 +150,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('abs-directory', {
       command: ws,
       args: [],
@@ -154,6 +163,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, { servers: {} })).rejects.toThrow(/servers must contain at least one server/)
     await ctx.fiber.dispose()
   })
@@ -162,6 +172,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('', {
       command: process.execPath,
       extensionToLanguage: { '.ts': 'typescript' },
@@ -173,6 +184,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         valid: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
@@ -187,6 +199,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         first: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
diff --git a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts
index fe9230ce14..9bdb7d1fd4 100644
--- a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts
+++ b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts
@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 
@@ -54,6 +55,7 @@ beforeAll(async () => {
   ctx = new Context()
   await ctx.plugin(Lsp)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   await ctx.plugin(LspLocal, {
     servers: {
       typescript: {
diff --git a/packages/lsp/lsp-local/tsconfig.json b/packages/lsp/lsp-local/tsconfig.json
index 2b106ddc81..04fdeb9a84 100644
--- a/packages/lsp/lsp-local/tsconfig.json
+++ b/packages/lsp/lsp-local/tsconfig.json
@@ -26,6 +26,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../fs/fs"
+    },
     {
       "path": "../lsp"
     },
diff --git a/packages/lsp/tool-lsp/package.json b/packages/lsp/tool-lsp/package.json
index 28b5a34bdb..f757df35fd 100644
--- a/packages/lsp/tool-lsp/package.json
+++ b/packages/lsp/tool-lsp/package.json
@@ -38,11 +38,13 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-lsp": "workspace:^",
     "@deepseek-ai/dsh-lsp-local": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-timeout-policy": "workspace:^",
diff --git a/packages/lsp/tool-lsp/tests/integration.spec.ts b/packages/lsp/tool-lsp/tests/integration.spec.ts
index 4d790cbd6b..8312a6e3ab 100644
--- a/packages/lsp/tool-lsp/tests/integration.spec.ts
+++ b/packages/lsp/tool-lsp/tests/integration.spec.ts
@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import Lsp from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
@@ -50,6 +51,7 @@ async function mount(hang: boolean, timeoutMs?: number): Promise<Context> {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(Lsp)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(LspLocal, {
     servers: {
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 083a144b55..65d541a7c1 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: 9c8206464d45b1be1d6ee3861c57c128e77686c5
-README.zh.md: 70d081e60a7db61443ed616b64586a93c119a640
+README.md: a4f743056b4a524be9623b0f700f37e0534b463f
+README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
diff --git a/packages/pty/README.md b/packages/pty/README.md
index 9c8206464d..a4f743056b 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -2,13 +2,12 @@
 
 English | [中文](README.zh.md)
 
-This family provides persistent, owner-scoped pseudo-terminal sessions for interactive or stateful terminal work. It complements one-shot bash execution.
+`PTY` stands for **Pseudo-Terminal**（伪终端）. This capability provides persistent, owner-scoped terminal sessions for workflows that require state across tool calls or interactive stdin. PTY complements the one-shot bash and filesystem tools; it does not replace their stronger per-operation contracts.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`pty/`](pty/README.md) | Defines the PTY service and session lifecycle | `ctx.pty` |
-| [`pty-local/`](pty-local/README.md) | Provides local persistent terminal sessions | registers on `ctx.pty` |
-| [`tool-pty/`](tool-pty/README.md) | Exposes PTY session operations to the model | registers on `ctx.tools` |
-| [`tool-bash-persistent/`](tool-bash-persistent/README.md) | Exposes a reusable PTY-backed bash tool | registers on `ctx.tools` |
+| [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
+| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
+| `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The [persistent PTY decision](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) records the family boundary.
+The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index 70d081e60a..c84ad3f1b5 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -2,13 +2,12 @@
 
 [English](README.md) | 中文
 
-本家族为交互式或有状态的终端工作提供持久且限定所有者范围的伪终端会话，是单次 bash 执行的补充。
+`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作契约。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`pty/`](pty/README.md) | 定义 PTY 服务和会话生命周期 | `ctx.pty` |
-| [`pty-local/`](pty-local/README.md) | 提供本地持久终端会话 | 注册到 `ctx.pty` |
-| [`tool-pty/`](tool-pty/README.md) | 向模型公开 PTY 会话操作 | 注册到 `ctx.tools` |
-| [`tool-bash-persistent/`](tool-bash-persistent/README.md) | 公开可复用的 PTY 后端 bash 工具 | 注册到 `ctx.tools` |
+| [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
+| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
+| `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-[持久 PTY 决策](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)记录了该家族的边界。
+设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 48ae675425..d8f5c2e2d0 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: ba05495318127b63b3d2a6a60ec743e1ff1c5821
-README.zh.md: 81987ea0685d761507b535b7ed6eefa0888fbd54
+README.md: 8a0a60139e27d98c4f506245a204723da997cd4a
+README.zh.md: 3df845931dac33abecbcd5030a1b204c68acc638
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index ba05495318..8a0a60139e 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -2,35 +2,35 @@
 
 English | [中文](README.zh.md)
 
-Local Linux/macOS `node-pty` backend for `ctx.pty`; loading it on another platform fails as unsupported. It starts an interactive shell under the shared `ctx.sandboxPolicy`, strips credential-shaped ambient environment variables, retains bounded line-oriented output, detects readiness, and tears down the captured process tree rooted at the `node-pty` child.
+Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It starts an interactive shell under the shared `ctx.sandboxPolicy`, retains bounded line-oriented output, and detects readiness while the subprocess provider owns PTY allocation, environment scrubbing, foreground process groups, signalling, and complete terminal-session cleanup. The same PTY backend therefore composes with local or remote execution-world providers.
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandbox`, and `sandboxPolicy`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a local-provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Linux readiness combines a foreground-verified private bash prompt marker, foreground-process-group syscall inspection, silence fallback, and absolute timeout. macOS uses the verified prompt marker plus silence/timeout because it has no `/proc` syscall surface. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the kernel publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win; that grace must cover at least one `pollIntervalMs` and is rejected at load otherwise. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unrecognized or unreadable process state is never a positive exact-idle signal. A foreground group's stdin wait that already existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason even when its foreground process group is not observable yet; if that close fails, `PtyBackendCleanupError` separately preserves the cleanup failure for registry disposal. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation resolves the current foreground process group and delivers a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close sends `SIGTERM` to descendants, waits, then sends `SIGKILL` to the union of captured survivors and newly scanned descendants so reparenting cannot hide a process from teardown. It verifies that every retained identity is gone or, on Linux, a non-executing zombie before stopping the shell; zombie entries are quiescent and are reaped as the shell exits. A survivor failure does not cache a permanently rejected close; a later close retries the teardown.
+Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
-### Current file policy and indirect consumer
+### Indirect consumer
 
 #### What the model sees
 
-The policy owner contributes capability-neutral `sandbox:policy` context. Through `@deepseek-ai/dsh-tool-pty` or another PTY consumer, the model may also receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
 
 #### Token effect
 
-The current-policy clause is present while this backend is mounted. Retained PTY scrollback is not placed in model history until a consumer returns bounded output.
+None until a consumer returns bounded backend output. Retained PTY scrollback is not placed in model history by this package.
 
 #### KV Cache effect
 
-A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; consumer results remain append-only.
+No direct invalidation; the consumer owns prompts, schemas, and appended results.
 
 ## Known Limitations and Deferred Work
 
 - Line-oriented output is normalized; full-screen alternate-buffer interaction is unsupported.
-- Linux exact probes support x64 and arm64 UAPI tables; other architectures use prompt-marker and silence/timeout readiness.
-- A descendant that daemonizes and reparents before teardown leaves the captured tree; cleanup never broadens to the launcher PID's POSIX session because that can include unrelated processes.
+- Exact stdin-wait detection depends on the mounted subprocess provider; providers that cannot prove it use prompt-marker and silence/timeout readiness.
+- Cleanup guarantees are those of `SubprocessTerminalHandle`; provider-specific gaps belong to that implementation's contract rather than this PTY consumer.
 - Sessions do not survive harness process exit.
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 81987ea068..3df845931d 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -2,35 +2,35 @@
 
 [English](README.md) | 中文
 
-这个本地 Linux／macOS `node-pty` 后端实现 `ctx.pty`；在其他平台加载时会以不支持为由失败。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，移除形似凭据的环境变量，保留有界的逐行输出，检测就绪状态，并清理以 `node-pty` 子进程为根的已捕获进程树。
+这是基于 `ctx.subprocess.spawnTerminal` 的 `ctx.pty` 持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandbox` 和 `sandboxPolicy`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使本地提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-Linux 的就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、前台进程组 syscall 检查、静默回退和绝对超时。macOS 没有 `/proc` syscall 接口，因此使用经过验证的提示符标记以及静默／超时。当可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在内核发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出；该宽限至少要覆盖一个 `pollIntervalMs`，否则加载时即被拒绝。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。无法识别或读取的进程状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝，即使当时还无法观察其前台进程组。如果关闭失败，`PtyBackendCleanupError` 会单独保留清理失败，供注册表 dispose（资源释放）时处理。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会解析当前前台进程组并发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作先向后代发送 `SIGTERM` 并等待，再向已捕获的存活进程与新扫描到的后代之并集发送 `SIGKILL`，防止进程通过重新设定父进程而逃避清理。在停止 shell 前，系统会确认每个保留的进程身份都已消失，或者在 Linux 上已成为不再执行的僵尸进程；僵尸进程条目视为完全停稳，并会随 shell 退出而回收。如果仍有进程存活，失败结果不会缓存成永久拒绝的关闭操作；后续关闭仍会重试清理。
+取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
-### 当前文件策略与间接消费方
+### 间接消费方
 
 #### 模型看到的内容
 
-策略归属方会贡献与具体能力无关的 `sandbox:policy` 上下文。模型通过 `@deepseek-ai/dsh-tool-pty` 或其他 PTY 消费方还可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
+没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
 
 #### Token 影响
 
-装载该后端期间，当前策略子句会一直存在。消费方返回有界输出前，保留的 PTY scrollback 不会进入模型历史。
+消费方返回有界的后端输出前没有影响。此包不会把保留的 PTY scrollback 放入模型历史。
 
 #### KV Cache 影响
 
-常驻策略发生变化时，会在保留的历史之后追加一份由归属方渲染、取代先前状态的运行时上下文快照；消费方结果保持仅追加。
+不会直接失效；提示词、schema 与追加结果由消费方负责。
 
-## 已知限制与暂缓事项
+## 已知限制与暂缓工作
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
-- Linux 精确探针支持 x64 与 arm64 UAPI 表；其他架构使用提示符标记和静默／超时就绪机制。
-- 如果后代进程在清理前守护化并重新设定父进程，它会脱离已捕获的进程树；清理绝不会扩大到启动器 PID 所属的整个 POSIX 会话，因为其中可能包含无关进程。
-- harness 进程退出后，会话无法继续存在。
+- 精确 stdin 等待检测取决于挂载的进程管理提供方；无法证明该事实的提供方使用提示符标记和静默／超时就绪机制。
+- 清理保证遵循 `SubprocessTerminalHandle`；提供方特有缺口属于该实现的契约，而非此 PTY 消费方。
+- 会话无法跨 harness 进程退出保留。
diff --git a/packages/pty/pty-local/package.json b/packages/pty/pty-local/package.json
index a859f482fa..94f98c02d5 100644
--- a/packages/pty/pty-local/package.json
+++ b/packages/pty/pty-local/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-pty-local",
-  "description": "Local node-pty backend for persistent DeepSeek Harness PTY sessions",
+  "description": "Persistent shell PTY backend over the DeepSeek Harness subprocess terminal primitive",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -21,12 +21,8 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
-  "scripts": {
-    "postinstall": "node scripts/ensure-spawn-helper.mjs"
-  },
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
@@ -39,7 +35,6 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "node-pty": "^1.1.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
@@ -50,6 +45,7 @@
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index e59d53446a..0a54a0b804 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -1,22 +1,18 @@
 /**
- * Local persistent PTY backend using public `node-pty` APIs, shared sandbox
- * policy, bounded output, platform readiness probes, and process-session cleanup.
+ * Persistent shell PTY backend over the subprocess terminal primitive, shared
+ * sandbox policy, bounded output, and provider-owned session cleanup.
  * @module @deepseek-ai/dsh-pty-local
  */
 
 import { Context } from 'cordis'
-import * as nodePty from 'node-pty'
-import type { IPtyForkOptions } from 'node-pty'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
-import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
-import { createProcessInspector } from './process-inspector.ts'
-import type { ProcessInspector } from './process-inspector.ts'
 import { LocalPtySession } from './session.ts'
 
 export { Config } from './config.ts'
@@ -24,8 +20,8 @@ export type { Config as PtyLocalConfig } from './config.ts'
 
 /** Cordis plugin name. */
 export const name = 'pty-local'
-/** Required services: PTY registry plus the one shared confinement policy. */
-export const inject = ['pty', 'sandbox', 'sandboxPolicy']
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+export const inject = ['pty', 'sandbox', 'sandboxPolicy', 'subprocess']
 
 interface SandboxModeFenceState {
   pty: Context['pty']
@@ -55,10 +51,10 @@ function ensureSandboxModeFence(ctx: Context, owner: Agent): void {
   }, { global: true })
 }
 
-function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
-  // node-pty owns the spawn; the base env shares the subprocess seam's scrub.
+function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+  // The subprocess provider supplies its own scrubbed ambient base; these are
+  // deliberate terminal-specific overrides layered after it.
   return {
-    ...scrubbedParentEnv(),
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
@@ -71,11 +67,14 @@ function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
   }
 }
 
-function spawnArgv(ctx: Context, config: ResolvedConfig, policy: SandboxExecutionPolicy): string[] {
+function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSpec): string[] {
   const argv = [config.shellPath, ...config.shellArgs]
-  if (policy.mode === 'danger-full-access') return argv
-  // Re-state the discriminant because object spread does not preserve its narrowed type.
-  return ctx.sandbox.confine(argv, { ...policy, mode: policy.mode }).argv
+  const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
+  if (mode === 'danger-full-access') return argv
+  return ctx.sandbox.confine(argv, {
+    mode: mode,
+    workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
+  }).argv
 }
 
 /** Local shell backend registered under the configured type. */
@@ -85,13 +84,13 @@ export class LocalPtyBackend implements PtyBackend {
   constructor(
     private readonly ctx: Context,
     private readonly config: ResolvedConfig,
-    private readonly inspector: ProcessInspector,
-    private readonly spawnTerminal: typeof nodePty.spawn = nodePty.spawn,
+    private readonly spawnTerminal: (
+      spec: SubprocessTerminalSpawnSpec,
+    ) => Promise<SubprocessTerminalHandle> = spec => ctx.subprocess.spawnTerminal(spec),
     private readonly createSession: (
-      terminal: ReturnType<typeof nodePty.spawn>,
-      inspector: ProcessInspector,
+      terminal: SubprocessTerminalHandle,
       config: ResolvedConfig,
-    ) => LocalPtySession = (terminal, inspector, config) => new LocalPtySession(terminal, inspector, config),
+    ) => LocalPtySession = (terminal, config) => new LocalPtySession(terminal, config),
   ) {
     this.type = config.backendType
   }
@@ -99,19 +98,18 @@ export class LocalPtyBackend implements PtyBackend {
   async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
     spec.signal?.throwIfAborted()
     ensureSandboxModeFence(this.ctx, spec.owner)
-    const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session })
-    const argv = spawnArgv(this.ctx, this.config, policy)
-    const file = argv[0]
-    if (file === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    const options: IPtyForkOptions = {
-      name: 'dumb',
-      cols: this.config.cols,
-      rows: this.config.rows,
-      cwd: spec.cwd ?? policy.workspaceRoot,
+    const argv = spawnArgv(this.ctx, this.config, spec)
+    if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
+    const terminal = await this.spawnTerminal({
+      argv,
+      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
       env: childEnvironment(spec),
-    }
-    const terminal = this.spawnTerminal(file, argv.slice(1), options)
-    const session = this.createSession(terminal, this.inspector, this.config)
+      rows: this.config.rows,
+      cols: this.config.cols,
+      graceMs: this.config.disposeGraceMs,
+      signal: spec.signal,
+    })
+    const session = this.createSession(terminal, this.config)
     try {
       await session.initialize(spec.signal)
       return session
@@ -129,6 +127,5 @@ export class LocalPtyBackend implements PtyBackend {
 /** Register the local PTY backend. */
 export function apply(ctx: Context, config: Config): void {
   validateConfig(config)
-  const inspector = createProcessInspector()
-  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config, inspector))
+  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config))
 }
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 46f3be2ca8..a6abaf7785 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -1,8 +1,11 @@
-/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
 
-import { constants } from 'node:os'
 import { Buffer } from 'node:buffer'
-import type { IDisposable, IPty } from 'node-pty'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+} from '@deepseek-ai/dsh-subprocess'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -17,13 +20,8 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
 import { TerminalSanitizer } from './sanitize.ts'
 
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
 function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
   if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
   const chars = Array.from(text)
@@ -80,17 +78,16 @@ class LocalSendOperation implements PtySendOperation {
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
   private initialForegroundLeftWait: boolean
+  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
-    private readonly initialForegroundPgid: number | undefined,
-    initialForegroundWasWaiting: boolean,
     private readonly onCancel: () => void,
   ) {
     this.output = new BoundedTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
-    this.initialForegroundLeftWait = !initialForegroundWasWaiting
+    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
@@ -123,6 +120,11 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
+  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
+    this.initialForegroundPgid = foreground?.processGroupId
+    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
+  }
+
   acceptsStdinWait(pgid: number, waiting: boolean): boolean {
     // The same group may still expose the wait that existed before terminal.write.
     // Observe every poll so a departure before the exact-settlement threshold
@@ -139,27 +141,21 @@ class LocalSendOperation implements PtySendOperation {
   }
 }
 
-function signalName(number: number | undefined): NodeJS.Signals | null {
-  if (number === undefined || number === 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
-}
-
-/** Backend session wrapping one `node-pty` process and its captured process tree. */
+/** Backend session wrapping one provider-owned terminal process. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
   private readonly sanitizer: TerminalSanitizer
   private readonly scrollback: BoundedTextBuffer
-  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
-  private readonly dataDisposable: IDisposable
-  private readonly exitDisposable: IDisposable
+  private readonly outputEnded = Promise.withResolvers<void>()
+  private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
+  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private polling = false
   private promptSeen = false
   private promptTextSeen = false
   private shellPgid: number | undefined
@@ -167,23 +163,22 @@ export class LocalPtySession implements PtyBackendSession {
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
+  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: IPty,
-    private readonly inspector: ProcessInspector,
+    private readonly terminal: SubprocessTerminalHandle,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
     this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
     this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
-    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
-      const tail = this.sanitizer.flush()
-      this.appendOutput(tail)
-      this.statusValue = { kind: 'exited', exitCode, signal: signalName(signal) }
-      this.settleActive('session_exit')
-      this.exitPromise.resolve()
-    })
+    terminal.output.on('data', this.onTerminalData)
+    terminal.output.once('end', this.onTerminalEnd)
+    terminal.output.once('error', this.onTerminalError)
+    this.completion = terminal.done.then(
+      outcome => this.onExit(outcome),
+      (error: unknown) => { this.onTransportFailure(error) },
+    )
   }
 
   /**
@@ -213,14 +208,9 @@ export class LocalPtySession implements PtyBackendSession {
     if (this.active !== undefined) throw new Error('PTY session already has an active send')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
-    const initialForegroundPgid = this.inspector.foregroundPgid(this.pid)
-    const initialForegroundWasWaiting = initialForegroundPgid !== undefined
-      && this.inspector.isStdinWaiting(initialForegroundPgid)
     const operation = new LocalSendOperation(
       this.config.maxReadBytes,
       Date.now(),
-      initialForegroundPgid,
-      initialForegroundWasWaiting,
       () => { this.interrupt(operation) },
     )
     this.active = operation
@@ -233,20 +223,28 @@ export class LocalPtySession implements PtyBackendSession {
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-
-    try {
-      if (request.text.length > 0) this.terminal.write(request.text)
-      if (request.submit) this.terminal.write('\r')
-    } catch (error: unknown) {
-      this.clearActive()
-      operation.fail(error)
-      return operation
-    }
-
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    this.activeDeadlineTimer = setTimeout(() => {
+      if (this.active === operation) this.settleActive('timeout')
+    }, this.config.timeoutMs)
+    void this.beginSend(operation, request)
     return operation
   }
 
+  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    try {
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation || this.closing) return
+      operation.setInitialForeground(foreground)
+      const input = `${request.text}${request.submit ? '\r' : ''}`
+      if (input.length > 0) await this.terminal.write(Buffer.from(input, 'utf8'))
+      // Closing can race the awaited provider write even though static analysis sees only local assignments.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (this.active === operation && !this.closing) this.schedulePoll(operation, 0)
+    } catch (error: unknown) {
+      if (this.active === operation) this.failActive(error)
+    }
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -272,16 +270,9 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  signal(signal: PtySignal): Promise<PtySignalResult> {
-    return Promise.resolve().then(() => {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      if (signal === 'SIGKILL' && pgid === this.pid) {
-        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
-      }
-      this.inspector.signalGroup(pgid, signal)
-      return { delivered: true, targetPgid: pgid }
-    })
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    const targetPgid = await this.terminal.signalForeground(signal)
+    return { delivered: true, targetPgid }
   }
 
   status(): PtySessionStatus {
@@ -300,12 +291,35 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
+  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
+    try {
+      const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+      this.onData(this.decoder.decode(bytes, { stream: true }))
+    } catch (error: unknown) {
+      this.onTransportFailure(new Error('PTY emitted invalid UTF-8', { cause: error }))
+    }
+  }
+
+  private readonly onTerminalEnd = (): void => {
+    try {
+      this.onData(this.decoder.decode())
+      this.appendOutput(this.sanitizer.flush())
+    } catch (error: unknown) {
+      this.onTransportFailure(new Error('PTY ended with invalid UTF-8', { cause: error }))
+    } finally {
+      this.outputEnded.resolve()
+    }
+  }
+
+  private readonly onTerminalError = (error: Error): void => {
+    this.onTransportFailure(error)
+    this.outputEnded.resolve()
+  }
+
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -317,6 +331,21 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
+  private async onExit(outcome: SubprocessOutcome): Promise<void> {
+    await this.outputEnded.promise
+    if (this.transportFailure !== undefined) return
+    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+    this.settleActive('session_exit')
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+    this.terminal.terminate()
+  }
+
   private appendOutput(text: string): void {
     if (text.length === 0) return
     this.lastOutputAt = Date.now()
@@ -324,44 +353,56 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private pollReadiness(operation: LocalSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
+  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
+    if (this.active !== operation || this.polling) return
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = setTimeout(() => {
+      this.activeTimer = undefined
+      void this.pollReadiness(operation)
+    }, delayMs)
+  }
+
+  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
+    if (this.active !== operation || this.polling) return
+    this.polling = true
+    try {
+      if (this.statusValue.kind === 'exited') {
+        this.settleActive('session_exit')
+        return
+      }
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation) return
+      const idleFor = Date.now() - this.lastOutputAt
+      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
+        this.shellPgid = foreground.processGroupId
+      }
+      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
+        && foreground?.processGroupId === this.shellPgid) {
         this.settleActive('stdin_read')
         return
       }
+      const elapsed = Date.now() - operation.startedAt
+      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+      const acceptsStdinWait = startupHasOutput && foreground !== undefined
+        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
+      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+        this.settleActive('stdin_read')
+        return
+      }
+      // A prompt candidate can race bash's foreground handoff, but an interactive
+      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+      // on waiting for shell ownership instead of letting a child marker suppress
+      // readiness until the absolute timeout.
+      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+        this.settleActive('inferred_idle')
+      }
+    } catch (error: unknown) {
+      if (this.active === operation) this.failActive(error)
+    } finally {
+      this.polling = false
+      if (this.active === operation) this.schedulePoll(operation)
     }
-    const elapsed = Date.now() - operation.startedAt
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    let acceptsStdinWait = false
-    if (startupHasOutput) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      acceptsStdinWait = pgid !== undefined
-        && operation.acceptsStdinWait(pgid, this.inspector.isStdinWaiting(pgid))
-    }
-    if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
-      this.settleActive('stdin_read')
-      return
-    }
-    // A prompt candidate can race bash's foreground handoff, but an interactive
-    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-    // on waiting for shell ownership instead of letting a child marker suppress
-    // readiness until the absolute timeout. When a prompt marker was seen, the
-    // configured grace holds the fallback past the silence bound so polls in
-    // that window can observe the foreground handoff and settle as stdin_read.
-    const idleFor = Date.now() - this.lastOutputAt
-    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
   }
 
   private settleActive(waitReason: PtyWaitReason): void {
@@ -373,8 +414,10 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = undefined
+    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
+    this.activeDeadlineTimer = undefined
   }
 
   private clearActive(): void {
@@ -393,104 +436,30 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    try {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      this.inspector.signalGroup(pgid, 'SIGINT')
-    } catch (error: unknown) {
-      this.failActive(error)
-    }
-  }
-
-  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
-    return members.filter(member => this.inspector.isAlive(member))
-  }
-
-  private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
-  }
-
-  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = this.survivors(members)
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
-      survivors = this.survivors(members)
-    }
-    return survivors
-  }
-
-  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, signal)
-      } catch (_alreadyExitedDuringSignal) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-  }
-
-  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
-    const members: ProcessIdentity[] = []
-    const seen = new Set<string>()
-    for (const group of groups) {
-      for (const member of group) {
-        const key = JSON.stringify([member.pid, member.started])
-        if (seen.has(key)) continue
-        seen.add(key)
-        members.push(member)
-      }
-    }
-    return members
-  }
-
-  private async stopDescendants(): Promise<ProcessIdentity[]> {
-    const captured = this.descendants()
-    this.signalMembers(captured, 'SIGTERM')
-    const capturedSurvivors = await this.waitForExit(captured)
-    // A TERM-handling descendant may have forked while winding down. Rescan
-    // while the shell can still reap every member, then kill both the fresh
-    // tree and captured survivors that were reparented out of that tree.
-    const members = this.unionMembers(capturedSurvivors, this.descendants())
-    this.signalMembers(members, 'SIGKILL')
-    const survivors = await this.waitForExit(members)
-    return this.survivors(this.unionMembers(survivors, this.descendants()))
-  }
-
-  private async stopShell(): Promise<void> {
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExitedDuringTerm) {
-      // The exit notification remains authoritative.
-    }
-    if (this.statusValue.kind === 'running') {
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      try {
-        this.terminal.kill('SIGKILL')
-      } catch (_topLevelAlreadyExitedDuringKill) {
-        // The exit notification remains authoritative.
-      }
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
-    }
+    void this.terminal.signalForeground('SIGINT').catch((error: unknown) => {
+      if (this.active === operation) this.failActive(error)
+    })
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    const survivors = await this.stopDescendants()
-    if (survivors.length > 0) {
-      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    this.terminal.terminate()
+    const quiescent = await this.terminal.waitForExit()
+    if (!quiescent) {
+      throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
     }
-    await this.stopShell()
+    // Whole-session cleanup can fail before the top-level process exits. Wait
+    // for it first so that failure is reported instead of blocking forever on
+    // `done`; successful quiescence guarantees `done` can now settle status and
+    // drain the terminal output.
+    await this.completion
     this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    this.terminal.output.off('data', this.onTerminalData)
+    this.terminal.output.off('end', this.onTerminalEnd)
+    this.terminal.output.off('error', this.onTerminalError)
+    if (this.transportFailure !== undefined) throw this.transportFailure
   }
 }
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 1ad29d7d01..a8753deaf3 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it, vi } from 'vitest'
-import type { IPty, IPtyForkOptions } from 'node-pty'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { Inbox, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
@@ -11,12 +11,18 @@ import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/d
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
-import type { ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 import type { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
 
 class EmptySandbox extends SandboxProvider {
   confine(_argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
-    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
+    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
   }
 }
 
@@ -25,7 +31,7 @@ class RecordingSandbox extends SandboxProvider {
 
   confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
     this.calls.push({ argv, policy })
-    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
+    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
   }
 }
 
@@ -38,28 +44,37 @@ function config(): ResolvedConfig {
   }
 }
 
-function agent(ctx: Context, cwd?: string): Agent {
+function agent(ctx: Context): Agent {
   const id = SessionId('agent')
-  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0, ...cwd === undefined ? {} : { cwd } })
   return {
-    id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
-    status: 'idle',
-    ctx,
-    send: () => {},
-    followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
-    runMaintenance: task => task(new AbortController().signal),
-    whenIdle: () => Promise.resolve(),
+    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
+    followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
   }
 }
 
-const inspector = {
-  foregroundPgid: () => undefined,
-  isStdinWaiting: () => false,
-  processTree: () => [],
-  isAlive: () => false,
-  signalGroup() {},
-  signalProcess() {},
-} satisfies ProcessInspector
+function terminalHandle(): SubprocessTerminalHandle {
+  const output = new PassThrough()
+  return {
+    pid: 123,
+    output,
+    done: Promise.resolve({ exitCode: 0, signal: null }),
+    write: async () => {},
+    inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
+    signalForeground: async () => 123,
+    terminate: () => { output.end() },
+    waitForExit: async () => true,
+  }
+}
+
+class StubSubprocessService extends SubprocessService {
+  readonly cwd = '/tmp'
+  readonly runtimeRoot = '/tmp/dsh-runtime'
+  async resolveExecutable(command: string): Promise<string> { return command }
+  spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
+  async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    return terminalHandle()
+  }
+}
 
 function spec(owner: Agent, signal?: AbortSignal) {
   return {
@@ -81,12 +96,11 @@ function stubLocalSession(initialize: () => Promise<void> = () => Promise.resolv
 }
 
 function registerStubLocalBackend(ctx: Context, createSession: () => LocalPtySession) {
-  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy'], (providerCtx) => {
+  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'], (providerCtx) => {
     providerCtx.pty.registerBackend(new LocalPtyBackend(
       providerCtx,
       { ...config(), backendType: 'stub' },
-      inspector,
-      (() => ({})) as never,
+      async () => terminalHandle(),
       createSession,
     ))
   })
@@ -97,7 +111,7 @@ describe('LocalPtyBackend startup rollback', () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/tmp' })
-    const backend = new LocalPtyBackend(ctx, config(), inspector)
+    const backend = new LocalPtyBackend(ctx, config(), async () => terminalHandle())
     const controller = new AbortController()
     const abortReason = new Error('spawn aborted')
     controller.abort(abortReason)
@@ -109,11 +123,11 @@ describe('LocalPtyBackend startup rollback', () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
-    const spawnTerminal = (() => ({} as IPty)) as never
+    const spawnTerminal = async (): Promise<SubprocessTerminalHandle> => terminalHandle()
 
     const closed = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
     const failed = { initialize: () => Promise.reject(new Error('startup failed')), close: closed } as unknown as LocalPtySession
-    const backend = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => failed)
+    const backend = new LocalPtyBackend(ctx, config(), spawnTerminal, () => failed)
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('startup failed')
     expect(closed).toHaveBeenCalledWith('PTY startup failed')
 
@@ -123,7 +137,7 @@ describe('LocalPtyBackend startup rollback', () => {
       initialize: () => Promise.reject(startupFailure),
       close: () => Promise.reject(cleanupFailure),
     } as unknown as LocalPtySession
-    const aggregate = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => doublyFailed)
+    const aggregate = new LocalPtyBackend(ctx, config(), spawnTerminal, () => doublyFailed)
     await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toEqual(expect.objectContaining({
       name: 'PtyBackendCleanupError',
       spawnError: startupFailure,
@@ -131,79 +145,72 @@ describe('LocalPtyBackend startup rollback', () => {
     } satisfies Partial<PtyBackendCleanupError>))
   })
 
-  it('resolves session mode and root together before wrapping the shell', async () => {
+  it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(RecordingSandbox)
-    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/deployment-fallback' })
-    const terminal = {} as IPty
-    let spawned: { file: string; args: string[]; options: IPtyForkOptions } | undefined
-    const spawnTerminal = ((file: string, args: string[], options: IPtyForkOptions) => {
-      spawned = { file, args, options }
+    await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const terminal = terminalHandle()
+    let spawned: SubprocessTerminalSpawnSpec | undefined
+    const spawnTerminal = async (spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> => {
+      spawned = spec
       return terminal
-    }) as never
+    }
     const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
     const session = { initialize: initialized } as unknown as LocalPtySession
     const backend = new LocalPtyBackend(
       ctx,
       { ...config(), shellArgs: ['-i'] },
-      inspector,
       spawnTerminal,
       () => session,
     )
     const previous = process.env.PTY_TEST_SECRET
     process.env.PTY_TEST_SECRET = 'must-not-leak'
-    const owner = agent(ctx, '/session-workspace')
-    setSandboxMode(owner.session, 'workspace-write')
     try {
-      expect(await backend.spawn(spec(owner))).toBe(session)
+      expect(await backend.spawn({ ...spec(agent(ctx)), cwd: '/work' })).toBe(session)
     } finally {
       if (previous === undefined) delete process.env.PTY_TEST_SECRET
       else process.env.PTY_TEST_SECRET = previous
     }
 
     expect(spawned).toMatchObject({
-      file: '/sandbox',
-      args: ['--', '/bin/bash', '-i'],
-      options: {
-        name: 'dumb', cols: 80, rows: 24, cwd: '/session-workspace',
-        env: {
-          TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
-          DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
-        },
+      argv: ['/sandbox', '--', '/bin/bash', '-i'],
+      cols: 80,
+      rows: 24,
+      cwd: '/work',
+      graceMs: 10,
+      env: {
+        TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
+        DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
       },
     })
-    expect(spawned?.options.env?.PTY_TEST_SECRET).toBeUndefined()
+    expect(spawned?.env?.PTY_TEST_SECRET).toBeUndefined()
     expect(initialized).toHaveBeenCalledWith(undefined)
-    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
-      argv: ['/bin/bash', '-i'],
-      policy: { mode: 'workspace-write', workspaceRoot: '/session-workspace' },
-    }])
   })
 
   it('composes the default local session around a spawned terminal', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/workspace' })
-    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
-    const terminal = {
-      pid: 123, cols: 80, rows: 24, process: 'bash', handleFlowControl: false,
-      onData(listener: (data: string) => void) {
-        queueMicrotask(() => { listener('\x1b]133;D;0\x07dsh> ') })
-        return { dispose() {} }
+    const output = new PassThrough()
+    const outcome = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>()
+    const terminal: SubprocessTerminalHandle = {
+      pid: 123,
+      output,
+      done: outcome.promise,
+      write: async () => {},
+      inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
+      signalForeground: async () => 123,
+      terminate() {
+        output.end()
+        outcome.resolve({ exitCode: null, signal: 'SIGTERM' })
       },
-      onExit(listener: (event: { exitCode: number; signal?: number }) => void) {
-        exitListener = listener
-        return { dispose() {} }
-      },
-      write() {},
-      kill() { exitListener?.({ exitCode: 0, signal: 15 }) },
-      resize() {}, clear() {}, pause() {}, resume() {},
-    } as IPty
+      waitForExit: async () => true,
+    }
+    queueMicrotask(() => { output.write(Buffer.from('\x1b]133;D;0\x07dsh> ')) })
     const backend = new LocalPtyBackend(
       ctx,
       config(),
-      { ...inspector, foregroundPgid: () => terminal.pid },
-      () => terminal,
+      async () => terminal,
     )
     const session = await backend.spawn(spec(agent(ctx)))
     expect(session.motd).toBe('dsh> ')
@@ -217,7 +224,7 @@ describe('pty-local plugin shape', () => {
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(ptyLocal) as Record<string, unknown>
     expect(unwrapped.name).toBe('pty-local')
-    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy'])
+    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'])
     expect(unwrapped.Config).toBeDefined()
   })
 
@@ -227,6 +234,7 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
     const fiber = await ctx.plugin(ptyLocal, config())
     expect(ctx.pty.listBackends()).toEqual(['shell'])
     await fiber.dispose()
@@ -240,11 +248,12 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
     await ctx.plugin(ptyLocal, config())
 
     const session = ctx.sessions.create(SessionId('unowned-mode'))
     expect(() => {
-      session.append('turn/start', { turn: 1 })
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     }).not.toThrow()
     expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
   })
@@ -256,17 +265,13 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(RecordingSandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
 
     const session = ctx.sessions.create(SessionId('mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
-      status: 'idle',
-      ctx: ownerFiber.ctx,
-      send: () => {},
-      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
-      runMaintenance: task => task(new AbortController().signal),
-      whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
+      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
@@ -275,7 +280,7 @@ describe('pty-local plugin shape', () => {
     const unrelated = ctx.sessions.create(SessionId('unrelated-mode'))
     expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow()
     expect(() => {
-      session.append('turn/start', { turn: 1 })
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     }).not.toThrow()
 
     expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
@@ -304,17 +309,13 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(RecordingSandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
 
     const session = ctx.sessions.create(SessionId('pending-mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
-      status: 'idle',
-      ctx: ownerFiber.ctx,
-      send: () => {},
-      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
-      runMaintenance: task => task(new AbortController().signal),
-      whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
+      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const gate = Promise.withResolvers<undefined>()
diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index c57b0ebb8e..c02a9563ea 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -11,6 +11,7 @@ import type { PtySendOperation } from '@deepseek-ai/dsh-pty'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 
 const roots: string[] = []
@@ -57,6 +58,7 @@ async function harness(
   await ctx.plugin(PtyService)
   await ctx.plugin(PassthroughSandbox)
   await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: root })
+  await ctx.plugin(LocalSubprocessService)
   const fiber = await ctx.plugin(ptyLocal, {
     pollIntervalMs: 10,
     exactProbeAfterMs: 20,
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 53ce61eebc..7a775eb9a0 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -1,62 +1,17 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { IDisposable, IPty } from 'node-pty'
+import { PassThrough } from 'node:stream'
 import { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
 import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
-import type { ProcessIdentity, ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 import type { PtySendOperation, PtySessionStatus, PtySignal } from '@deepseek-ai/dsh-pty'
-
-class FakeTerminal {
-  pid = 123
-  cols = 80
-  rows = 24
-  process = 'bash'
-  handleFlowControl = false
-  writes: string[] = []
-  kills: string[] = []
-  throwWrite = false
-  throwKill = false
-  autoExitOnKill = true
-  private dataListeners = new Set<(data: string) => void>()
-  private exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
-
-  readonly onData = (listener: (data: string) => void): IDisposable => {
-    this.dataListeners.add(listener)
-    return { dispose: () => this.dataListeners.delete(listener) }
-  }
-
-  readonly onExit = (listener: (event: { exitCode: number; signal?: number }) => void): IDisposable => {
-    this.exitListeners.add(listener)
-    return { dispose: () => this.exitListeners.delete(listener) }
-  }
-
-  emitData(data: string): void {
-    for (const listener of this.dataListeners) listener(data)
-  }
-
-  emitExit(exitCode = 0, signal?: number): void {
-    for (const listener of this.exitListeners) listener({ exitCode, ...signal === undefined ? {} : { signal } })
-  }
-
-  write(data: string): void {
-    if (this.throwWrite) throw new Error('write failed')
-    this.writes.push(data)
-  }
-
-  kill(signal?: string): void {
-    if (this.throwKill) throw new Error('kill failed')
-    this.kills.push(signal ?? 'SIGHUP')
-    if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
-  }
-
-  resize() {}
-  clear() {}
-  pause() {}
-  resume() {}
-
-  asPty(): IPty {
-    return this
-  }
-}
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+} from '@deepseek-ai/dsh-subprocess'
+import type {
+  ProcessIdentity,
+  ProcessInspector,
+} from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 
 class FakeInspector implements ProcessInspector {
   pgid: number | undefined = 456
@@ -84,6 +39,89 @@ class FakeInspector implements ProcessInspector {
   }
 }
 
+class FakeTerminal implements SubprocessTerminalHandle {
+  pid = 123
+  readonly output = new PassThrough()
+  readonly writes: string[] = []
+  readonly kills: string[] = []
+  readonly outcome = Promise.withResolvers<SubprocessOutcome>()
+  readonly done = this.outcome.promise
+  throwWrite = false
+  throwKill = false
+  autoExitOnKill = true
+  quiescent = true
+  waitError: Error | undefined
+
+  constructor(public inspector = new FakeInspector()) {}
+
+  emitData(data: string): void {
+    this.output.write(Buffer.from(data, 'utf8'))
+  }
+
+  emitBytes(data: Uint8Array): void {
+    this.output.write(data)
+  }
+
+  emitError(error: Error): void {
+    this.output.emit('error', error)
+  }
+
+  emitFailure(error: unknown): void {
+    this.output.end()
+    this.outcome.reject(error)
+  }
+
+  emitExit(exitCode = 0, signal?: number): void {
+    this.output.end()
+    this.outcome.resolve({
+      exitCode: signal === undefined || signal === 0 ? exitCode : null,
+      signal: signal === 9 ? 'SIGKILL' : signal === 15 ? 'SIGTERM' : null,
+    })
+  }
+
+  async write(data: Uint8Array): Promise<void> {
+    if (this.throwWrite) throw new Error('write failed')
+    this.writes.push(Buffer.from(data).toString('utf8'))
+  }
+
+  async inspectForeground() {
+    const processGroupId = this.inspector.foregroundPgid()
+    return processGroupId === undefined
+      ? undefined
+      : { processGroupId, inputWaiting: this.inspector.isStdinWaiting() }
+  }
+
+  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    const foreground = await this.inspectForeground()
+    if (foreground === undefined) throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`)
+    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+    }
+    this.inspector.signalGroup(foreground.processGroupId, signal)
+    return foreground.processGroupId
+  }
+
+  terminate(): void {
+    if (this.throwKill) throw new Error('kill failed')
+    this.kills.push('SIGTERM')
+    if (this.autoExitOnKill) this.emitExit(0, 15)
+  }
+
+  async waitForExit(): Promise<boolean> {
+    if (this.waitError !== undefined) throw this.waitError
+    return this.quiescent
+  }
+}
+
+function makeSession(
+  terminal: FakeTerminal,
+  inspector: FakeInspector,
+  resolved: ResolvedConfig,
+): LocalPtySession {
+  terminal.inspector = inspector
+  return new LocalPtySession(terminal, resolved)
+}
+
 function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
   return {
     backendType: 'shell', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80,
@@ -108,13 +146,15 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
     expect(session.motd).toBe('dsh> ')
 
     inspector.waiting = true
     const operation = session.startSend({ text: 'python3', submit: true })
-    expect(terminal.writes).toEqual(['python3', '\r'])
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(terminal.writes).toEqual(['python3\r'])
     inspector.pgid = 789
     terminal.emitData('Python\r\n>>> ')
     await vi.advanceTimersByTimeAsync(20)
@@ -126,7 +166,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     inspector.waiting = true
@@ -148,7 +188,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({
+    const session = makeSession(terminal, inspector, config({
       exactProbeAfterMs: 50,
       idleSilenceMs: 100,
       timeoutMs: 200,
@@ -173,7 +213,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
     inspector.pgid = undefined
 
@@ -193,7 +233,7 @@ describe('LocalPtySession readiness and output', () => {
 
     const exiting = session.startSend({ text: 'exit', submit: true })
     terminal.emitExit(7, 9)
-    expect(await exiting.done).toMatchObject({ waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 7, signal: 'SIGKILL' } })
+    expect(await exiting.done).toMatchObject({ waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGKILL' } })
     expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
   })
 
@@ -201,13 +241,15 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     const controller = new AbortController()
     const operation = session.startSend({ text: 'sleep', submit: true, signal: controller.signal })
     expect(() => session.startSend({ text: 'again', submit: true })).toThrow('active send')
     controller.abort()
+    await Promise.resolve()
+    await Promise.resolve()
     expect(inspector.groups).toContainEqual([456, 'SIGINT'])
     expect(terminal.writes).not.toContain('\x03')
     terminal.emitData('\x1b]133;D;130\x07dsh> ')
@@ -229,14 +271,14 @@ describe('LocalPtySession readiness and output', () => {
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
     vi.useFakeTimers()
     const startupTerminal = new FakeTerminal()
-    const startup = new LocalPtySession(startupTerminal.asPty(), new FakeInspector(), config())
+    const startup = new LocalPtySession(startupTerminal, config())
     const initializing = startup.initialize(new AbortController().signal)
     startupTerminal.emitExit(1)
     await expect(initializing).rejects.toThrow('exited during startup')
     expect(startup.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
 
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    const session = new LocalPtySession(terminal, config())
     await initialize(session, terminal)
     const operation = session.startSend({ text: '', submit: false })
     const operationInternal = operation as unknown as {
@@ -247,11 +289,17 @@ describe('LocalPtySession readiness and output', () => {
     const sessionInternal = session as unknown as {
       pollReadiness(operation: PtySendOperation): void
       interrupt(operation: PtySendOperation): void
+      schedulePoll(operation: PtySendOperation): void
+      polling: boolean
       statusValue: PtySessionStatus
       appendOutput(text: string): void
     }
     sessionInternal.appendOutput('')
     sessionInternal.pollReadiness({} as PtySendOperation)
+    sessionInternal.schedulePoll({} as PtySendOperation)
+    sessionInternal.polling = true
+    sessionInternal.schedulePoll(operation)
+    sessionInternal.polling = false
     sessionInternal.interrupt({} as PtySendOperation)
     sessionInternal.statusValue = { kind: 'exited', exitCode: 2, signal: null }
     sessionInternal.pollReadiness(operation)
@@ -259,13 +307,15 @@ describe('LocalPtySession readiness and output', () => {
     operationInternal.settle('timeout', { kind: 'running' }, false)
 
     const unknownTerminal = new FakeTerminal()
-    const unknown = new LocalPtySession(unknownTerminal.asPty(), new FakeInspector(), config())
+    const unknown = new LocalPtySession(unknownTerminal, config())
     unknownTerminal.emitExit(1, 999)
-    expect(unknown.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
+    await vi.waitFor(() => {
+      expect(unknown.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    })
 
     const cancelTerminal = new FakeTerminal()
     const cancelInspector = new FakeInspector()
-    const cancel = new LocalPtySession(cancelTerminal.asPty(), cancelInspector, config())
+    const cancel = makeSession(cancelTerminal, cancelInspector, config())
     await initialize(cancel, cancelTerminal)
     const cancellable = cancel.startSend({ text: '', submit: false })
     cancelInspector.throwGroup = true
@@ -275,7 +325,7 @@ describe('LocalPtySession readiness and output', () => {
 
     const missingGroupTerminal = new FakeTerminal()
     const missingGroupInspector = new FakeInspector()
-    const missingGroup = new LocalPtySession(missingGroupTerminal.asPty(), missingGroupInspector, config())
+    const missingGroup = makeSession(missingGroupTerminal, missingGroupInspector, config())
     await initialize(missingGroup, missingGroupTerminal)
     missingGroupInspector.pgid = undefined
     const unresolved = missingGroup.startSend({ text: '', submit: false })
@@ -286,7 +336,7 @@ describe('LocalPtySession readiness and output', () => {
   it('does not treat zero-output startup silence as readiness and fails on startup timeout', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    const session = new LocalPtySession(terminal, config())
     let settled = false
     const initializing = session.initialize().then(() => { settled = true })
     await vi.advanceTimersByTimeAsync(60)
@@ -296,7 +346,7 @@ describe('LocalPtySession readiness and output', () => {
     await initializing
 
     const timeoutTerminal = new FakeTerminal()
-    const timeout = new LocalPtySession(timeoutTerminal.asPty(), new FakeInspector(), config())
+    const timeout = new LocalPtySession(timeoutTerminal, config())
     const timedOut = expect(timeout.initialize()).rejects.toThrow('startup timeout')
     await vi.advanceTimersByTimeAsync(100)
     await timedOut
@@ -306,7 +356,7 @@ describe('LocalPtySession readiness and output', () => {
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
     inspector.pgid = undefined
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     const controller = new AbortController()
     const reason = new Error('startup cancelled')
 
@@ -320,7 +370,7 @@ describe('LocalPtySession readiness and output', () => {
   it('waits for printable prompt text when the startup marker is split from PS1', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    const session = new LocalPtySession(terminal, config())
     let settled = false
     const initializing = session.initialize().then(() => { settled = true })
 
@@ -338,7 +388,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     const operation = session.startSend({ text: 'run', submit: true })
@@ -359,7 +409,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ handoffGraceMs: 40 }))
+    const session = makeSession(terminal, inspector, config({ handoffGraceMs: 40 }))
     await initialize(session, terminal)
 
     const operation = session.startSend({ text: 'run', submit: true })
@@ -380,7 +430,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     const operation = session.startSend({ text: 'bash -i', submit: true })
@@ -390,6 +440,156 @@ describe('LocalPtySession readiness and output', () => {
 
     expect((await operation.done).waitReason).toBe('inferred_idle')
   })
+
+  it('contains terminal transport failures and preserves the first failure', async () => {
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    const operation = session.startSend({ text: '', submit: false })
+    terminal.output.emit('data', 'plain text')
+    terminal.emitError(new Error('output transport failed'))
+    ;(session as unknown as { onTransportFailure(error: unknown): void })
+      .onTransportFailure(new Error('later failure'))
+    await expect(operation.done).rejects.toThrow('output transport failed')
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    await expect(session.close('transport')).rejects.toThrow('output transport failed')
+
+    const rejectedTerminal = new FakeTerminal()
+    const rejected = new LocalPtySession(rejectedTerminal, config())
+    const rejectedOperation = rejected.startSend({ text: '', submit: false })
+    rejectedTerminal.emitFailure('raw transport failure')
+    await expect(rejectedOperation.done).rejects.toThrow('raw transport failure')
+  })
+
+  it('rejects invalid UTF-8 in a data chunk and at stream end', async () => {
+    const chunkTerminal = new FakeTerminal()
+    const chunkSession = new LocalPtySession(chunkTerminal, config())
+    const chunkOperation = chunkSession.startSend({ text: '', submit: false })
+    chunkTerminal.emitBytes(Uint8Array.from([0xff]))
+    await expect(chunkOperation.done).rejects.toThrow('PTY emitted invalid UTF-8')
+
+    const endTerminal = new FakeTerminal()
+    const endSession = new LocalPtySession(endTerminal, config())
+    const endOperation = endSession.startSend({ text: '', submit: false })
+    endTerminal.emitBytes(Uint8Array.from([0xe2]))
+    endTerminal.emitExit()
+    await expect(endOperation.done).rejects.toThrow('PTY ended with invalid UTF-8')
+  })
+
+  it('contains readiness inspection failure and a stale inspection result', async () => {
+    vi.useFakeTimers()
+    const failedTerminal = new FakeTerminal()
+    const failedSession = new LocalPtySession(failedTerminal, config())
+    const failedOperation = failedSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    failedTerminal.inspectForeground = async () => { throw new Error('inspect failed') }
+    const failedInternal = failedSession as unknown as {
+      pollReadiness(operation: PtySendOperation): Promise<void>
+    }
+    await failedInternal.pollReadiness(failedOperation)
+    await expect(failedOperation.done).rejects.toThrow('inspect failed')
+
+    const staleTerminal = new FakeTerminal()
+    const staleSession = new LocalPtySession(staleTerminal, config())
+    const staleOperation = staleSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const gate = Promise.withResolvers<ReturnType<FakeTerminal['inspectForeground']> extends Promise<infer T> ? T : never>()
+    staleTerminal.inspectForeground = async () => await gate.promise
+    const staleInternal = staleSession as unknown as {
+      active: PtySendOperation | undefined
+      pollReadiness(operation: PtySendOperation): Promise<void>
+    }
+    const polling = staleInternal.pollReadiness(staleOperation)
+    staleInternal.active = undefined
+    gate.resolve({ processGroupId: 456, inputWaiting: false })
+    await polling
+    ;(staleOperation as unknown as {
+      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+    }).settle('timeout', { kind: 'running' }, false)
+  })
+
+  it('contains stale timer, write, inspection, and interrupt continuations', async () => {
+    vi.useFakeTimers()
+    const settle = (operation: PtySendOperation): void => {
+      ;(operation as unknown as {
+        settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+      }).settle('timeout', { kind: 'running' }, false)
+    }
+
+    const deadlineTerminal = new FakeTerminal()
+    const deadlineSession = new LocalPtySession(deadlineTerminal, config())
+    const deadlineOperation = deadlineSession.startSend({ text: '', submit: false })
+    ;(deadlineSession as unknown as { active: PtySendOperation | undefined }).active = undefined
+    await vi.advanceTimersByTimeAsync(100)
+    settle(deadlineOperation)
+
+    const writeTerminal = new FakeTerminal()
+    const writeGate = Promise.withResolvers<undefined>()
+    writeTerminal.write = async () => { await writeGate.promise }
+    const writeSession = new LocalPtySession(writeTerminal, config())
+    const writeOperation = writeSession.startSend({ text: 'x', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    ;(writeSession as unknown as { closing: boolean }).closing = true
+    writeGate.resolve(undefined)
+    await Promise.resolve()
+    await Promise.resolve()
+    settle(writeOperation)
+
+    const beginTerminal = new FakeTerminal()
+    const beginGate = Promise.withResolvers<never>()
+    beginTerminal.inspectForeground = async () => await beginGate.promise
+    const beginSession = new LocalPtySession(beginTerminal, config())
+    const beginOperation = beginSession.startSend({ text: '', submit: false })
+    ;(beginSession as unknown as { active: PtySendOperation | undefined }).active = undefined
+    beginGate.reject(new Error('stale begin failure'))
+    await Promise.resolve()
+    await Promise.resolve()
+    settle(beginOperation)
+
+    const scheduledTerminal = new FakeTerminal()
+    const scheduledSession = new LocalPtySession(scheduledTerminal, config())
+    const scheduledOperation = scheduledSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const scheduledInternal = scheduledSession as unknown as {
+      schedulePoll(operation: PtySendOperation, delayMs?: number): void
+      settleActive(reason: 'timeout'): void
+    }
+    scheduledInternal.schedulePoll(scheduledOperation, 5)
+    scheduledInternal.settleActive('timeout')
+    await scheduledOperation.done
+
+    const pollTerminal = new FakeTerminal()
+    const pollSession = new LocalPtySession(pollTerminal, config())
+    const pollOperation = pollSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const pollGate = Promise.withResolvers<never>()
+    pollTerminal.inspectForeground = async () => await pollGate.promise
+    const pollInternal = pollSession as unknown as {
+      active: PtySendOperation | undefined
+      pollReadiness(operation: PtySendOperation): Promise<void>
+    }
+    const stalePoll = pollInternal.pollReadiness(pollOperation)
+    pollInternal.active = undefined
+    pollGate.reject(new Error('stale poll failure'))
+    await stalePoll
+    settle(pollOperation)
+
+    const interruptTerminal = new FakeTerminal()
+    const interruptGate = Promise.withResolvers<never>()
+    interruptTerminal.signalForeground = async () => await interruptGate.promise
+    const interruptSession = new LocalPtySession(interruptTerminal, config())
+    const interruptOperation = interruptSession.startSend({ text: '', submit: false })
+    expect(interruptOperation.cancel()).toBe(true)
+    ;(interruptSession as unknown as { active: PtySendOperation | undefined }).active = undefined
+    interruptGate.reject(new Error('stale interrupt failure'))
+    await Promise.resolve()
+    await Promise.resolve()
+    settle(interruptOperation)
+  })
 })
 
 describe('LocalPtySession bounds, signals, and teardown', () => {
@@ -397,8 +597,7 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const session = new LocalPtySession(
-      terminal.asPty(),
-      new FakeInspector(),
+      terminal,
       config({ scrollbackLines: 3, scrollbackMaxBytes: 12, maxReadBytes: 6 }),
     )
     expect(session.read({})).toMatchObject({ text: '' })
@@ -415,7 +614,7 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     expect(() => session.read({ count: 0 })).toThrow('count')
 
     const tinyTerminal = new FakeTerminal()
-    const tiny = new LocalPtySession(tinyTerminal.asPty(), new FakeInspector(), config({ maxReadBytes: 1 }))
+    const tiny = new LocalPtySession(tinyTerminal, config({ maxReadBytes: 1 }))
     await initialize(tiny, tinyTerminal)
     const tinyOperation = tiny.startSend({ text: '', submit: false })
     tinyTerminal.emitData('一')
@@ -427,32 +626,38 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
   it('signals verified groups and refuses unresolved or shell-targeted hard kills', async () => {
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     expect(await session.signal('SIGINT')).toEqual({ delivered: true, targetPgid: 456 })
     inspector.pgid = terminal.pid
-    await expect(session.signal('SIGKILL')).rejects.toThrow('use terminal_close')
+    await expect(session.signal('SIGKILL')).rejects.toThrow('terminate the terminal session')
     inspector.pgid = undefined
     await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
   })
 
   it('closes idempotently, contains signal races, and reports survivors', async () => {
     const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 123, started: 'a' }]
-    inspector.alive.add(123)
-    inspector.throwProcess = true
-    terminal.throwKill = true
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 1 }))
+    terminal.quiescent = false
+    const session = new LocalPtySession(terminal, config({ disposeGraceMs: 1 }))
     const closing = session.close('test')
     expect(session.close('other')).toBe(closing)
-    await expect(closing).rejects.toThrow('surviving pids: 123')
+    await expect(closing).rejects.toThrow('did not reach quiescence')
     expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
   })
 
+  it('reports cleanup failure without waiting for top-level exit', async () => {
+    const terminal = new FakeTerminal()
+    terminal.autoExitOnKill = false
+    terminal.waitError = new Error('terminal cleanup failed; surviving pids: 456')
+    const session = new LocalPtySession(terminal, config())
+
+    await expect(session.close('survivor')).rejects.toThrow('surviving pids: 456')
+    expect(terminal.kills).toEqual(['SIGTERM'])
+  })
+
   it('settles an active send as session_exit when closed mid-operation', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config({ disposeGraceMs: 50 }))
+    const session = new LocalPtySession(terminal, config({ disposeGraceMs: 50 }))
     await initialize(session, terminal)
     const operation = session.startSend({ text: 'run', submit: true })
     // The shell returns to its prompt while the send is active; a running
@@ -467,94 +672,4 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await closing
   })
 
-  it('keeps the shell alive until SIGKILL recipients leave the process table', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 124, started: 'child' }]
-    inspector.alive.add(124)
-    inspector.removeOnSignal = false
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 20 }))
-
-    let settled = false
-    const closing = session.close('test').then(() => { settled = true })
-    await vi.advanceTimersByTimeAsync(20)
-    expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
-    expect(terminal.kills).toEqual([])
-    expect(settled).toBe(false)
-
-    inspector.alive.delete(124)
-    await vi.advanceTimersByTimeAsync(20)
-    await closing
-    expect(terminal.kills).toEqual(['SIGTERM'])
-    expect(settled).toBe(true)
-  })
-
-  it('rescans for descendants forked during TERM before stopping the shell', async () => {
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    let reads = 0
-    inspector.processTree = () => {
-      reads += 1
-      if (reads === 1) {
-        inspector.alive.add(124)
-        return [{ pid: 124, started: 'first' }]
-      }
-      if (reads === 2) {
-        inspector.alive.add(125)
-        return [{ pid: 125, started: 'late' }]
-      }
-      return []
-    }
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
-
-    await session.close('test')
-
-    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
-    expect(terminal.kills).toEqual(['SIGTERM'])
-  })
-
-  it('retains captured survivors that are reparented out of the teardown rescan', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    const captured = { pid: 124, started: 'captured' }
-    let reads = 0
-    inspector.alive.add(captured.pid)
-    inspector.processTree = () => reads++ === 0 ? [captured] : []
-    inspector.signalProcess = (identity, signal) => {
-      inspector.processes.push([identity.pid, signal])
-      if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
-    }
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 20 }))
-
-    const closing = session.close('test')
-    await vi.advanceTimersByTimeAsync(25)
-    await closing
-
-    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
-    expect(terminal.kills).toEqual(['SIGTERM'])
-  })
-
-  it('allows teardown to retry after a descendant-survivor failure', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 124, started: 'child' }]
-    inspector.alive.add(124)
-    inspector.removeOnSignal = false
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 10 }))
-
-    const first = session.close('first')
-    const rejected = expect(first).rejects.toThrow('surviving pids: 124')
-    await vi.advanceTimersByTimeAsync(25)
-    await rejected
-    expect(terminal.kills).toEqual([])
-
-    inspector.alive.delete(124)
-    const second = session.close('retry')
-    expect(second).not.toBe(first)
-    await second
-    expect(terminal.kills).toEqual(['SIGTERM'])
-  })
 })
diff --git a/packages/pty/tool-pty/package.json b/packages/pty/tool-pty/package.json
index 5512daba92..9027169941 100644
--- a/packages/pty/tool-pty/package.json
+++ b/packages/pty/tool-pty/package.json
@@ -51,6 +51,7 @@
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tasks-local": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts
index 835df86abc..35d0ea5d0a 100644
--- a/packages/pty/tool-pty/tests/loader-composition.spec.ts
+++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts
@@ -16,6 +16,7 @@ import PtyService from '@deepseek-ai/dsh-pty'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import * as PtyLocal from '@deepseek-ai/dsh-pty-local'
 import * as ToolPty from '@deepseek-ai/dsh-tool-pty'
 
@@ -72,6 +73,7 @@ suite('terminal real Loader composition through cordis.yml', () => {
       '  config:',
       '    mode: danger-full-access',
       `    workspaceRoot: ${JSON.stringify(root)}`,
+      "- name: '@deepseek-ai/dsh-subprocess-local'",
       "- name: '@deepseek-ai/dsh-pty-local'",
       '  config:',
       '    pollIntervalMs: 10',
@@ -95,6 +97,7 @@ suite('terminal real Loader composition through cordis.yml', () => {
       ['@deepseek-ai/dsh-pty', PtyService],
       ['@deepseek-ai/dsh-test-sandbox', PassthroughSandbox],
       ['@deepseek-ai/dsh-sandbox-policy', SandboxPolicyService],
+      ['@deepseek-ai/dsh-subprocess-local', LocalSubprocessService],
       ['@deepseek-ai/dsh-pty-local', PtyLocal],
       ['@deepseek-ai/dsh-tool-pty', ToolPty],
     ])
diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts
index 0f92cac1d6..9dc723fb58 100644
--- a/packages/skill/skill-local/tests/skill-local.spec.ts
+++ b/packages/skill/skill-local/tests/skill-local.spec.ts
@@ -42,6 +42,14 @@ class TestFileSystem extends FileSystem {
     return { targetKey: path as never, displayPath: path }
   }
 
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     this.statSignals.push(signal)
     if (this.failStatPaths.has(target.displayPath)) throw new FsError('stat failed', 'FS_NOT_FOUND')
@@ -84,6 +92,12 @@ class TestFileSystem extends FileSystem {
     return text
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    const text = await this.readText(target, signal)
+    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
+    return text
+  }
+
   override async streamText(_target: FsTarget): Promise<AsyncIterable<string>> {
     throw new Error('not needed in skill tests')
   }
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 9c0cb0c25d..256d4ad2d9 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: 187ea5b778a4bc1f9c3c9121adb18bda11cc7b58
-README.zh.md: dd3a975daec014131877d7b1523810bd932619d8
+README.md: c4bb1da1a172b05afa63834db4e5b1fa974baabb
+README.zh.md: f68bc1c720eeb5282bb9c94c951524a021e38b2f
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index 187ea5b778..c4bb1da1a1 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-This family runs host subprocesses behind an explicit process-lifecycle service.
+The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and complete session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
-| Package | Role | ctx key |
+| Package | ctx key | Role |
 |---|---|---|
-| [`subprocess/`](subprocess/README.md) | Defines subprocess launch, stream, termination, and disposal contracts | `ctx.subprocess` |
-| [`subprocess-local/`](subprocess-local/README.md) | Implements local process-tree execution | registers on `ctx.subprocess` |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: execution-world coordinates and executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, runtime storage, and terminate-and-join disposal |
 
-The service owns process lifetime; each consumer owns what the process does and which defaults apply.
+The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index dd3a975dae..f68bc1c720 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,12 +1,12 @@
-# subprocess/：子进程能力家族
+# subprocess/：进程管理能力家族
 
 [English](README.md) | 中文
 
-本家族通过显式的进程生命周期服务运行宿主子进程。
+同一执行世界中的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、采用原始或收集式 stdio 的完全显式受管子进程树，以及一项负责 PTY 分配、前台进程组和完整会话清理的深层终端进程原语。命令默认值补全、shell 语义、deadline、协议分帧、就绪检测与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[基于进程管理的 Code Runtime](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
-| 包 | 职责 | ctx 键 |
+| 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess/`](subprocess/README.md) | 定义子进程启动、流、终止和 dispose（资源释放）契约 | `ctx.subprocess` |
-| [`subprocess-local/`](subprocess-local/README.md) | 实现本地进程树执行 | 注册到 `ctx.subprocess` |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送、运行时存储，以及先终止再等待退出的资源释放 |
 
-服务负责进程生命周期；每个消费方负责进程执行的工作以及所应用的默认值。
+服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 28ebc2c110..d931d3574b 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: af9f92db714398dd52c9b5e7aeb64d5af71021da
-README.zh.md: da78cbcfbff174eb5fda5b8323fbdc84b50c9997
+README.md: 6bc1003ae5903bb5640728bc79c3f9042fddbe7a
+README.zh.md: 3c9ce73c7fcbeec9b17d73f212ecdcb6842ec133
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index af9f92db71..6bc1003ae5 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,14 +2,16 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam: `LocalSubprocessService` spawns each spec's argv as a detached process tree, wires the spec's per-stream stdio dispositions (raw pipes, inherit, bounded tail-keep collection with optional spill files), and signals tree-scoped with SIGTERM→SIGKILL escalation. It has no config: every disposition, limit, and directory arrives on the spawn spec, so the deployment-varying knobs stay with the calling seams' configs ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)).
+Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` owns a private runtime directory, resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
 
 ## Behavior (and where it came from)
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
+- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F` (injectable for tests). `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
-- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
+- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
+- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Linux `/proc`/syscall and macOS `ps` inspectors retain exact pid/start identity so pid reuse cannot redirect cleanup; the higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
@@ -22,8 +24,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Windows tree support is best-effort** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary.
-- **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
+- **Windows tree support is best-effort and untested in CI** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary; the suites cover the routing through an injected runner only, and `packages/subprocess/*` is excluded from the Windows test matrix.
+- **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
+- **A daemonized terminal descendant can escape the captured tree** — a child that reparents before teardown is no longer discoverable from the `node-pty` root. The local provider accepts this gap rather than signal the root PID's POSIX session, which can include unrelated launcher processes.
+- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
 
 The raw process handling lives in `src/spawn.ts`; `src/index.ts` is the service wiring.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index da78cbcfbf..3c9ce73c7f 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,15 +2,17 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现：`LocalSubprocessService` 将每个 spec 的 argv spawn 为 detached 进程树，依照 spec 中按流划分的 stdio 处置方式（disposition）完成接线（原始管道、inherit、附带可选 spill 文件的有界尾部保留收集），并以进程树为范围发送信号，按 SIGTERM→SIGKILL 逐级升级。该实现没有任何配置：每项处置方式、限制与目录都随 spawn spec 传入，因此随部署变化的可调参数留在各调用方 seam 的配置里（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 拥有私有运行时目录，解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 与平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md)和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
 
 ## 行为（以及设计来源）
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
-- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
-- **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
+- **带平台正确信号发送的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止动词）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
+- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
+- **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
+- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，在资源释放时删除；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。Linux 的 `/proc`／syscall 检查器与 macOS 的 `ps` 检查器会保留精确的 pid／启动身份，使 PID 复用无法把清理重定向到其他进程；上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
@@ -18,12 +20,14 @@
 
 #### KV Cache 影响
 
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+不会直接失效；请求前缀变更由具名消费方负责。
 
 ## 已知限制与暂缓事项
 
-- **Windows 进程树支持仅为尽力而为**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
-- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
+- **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
+- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 使用 `ps` 快照。
+- **守护化的终端后代可能逃离已捕获进程树**：子进程若在拆卸前重新设定父进程，便无法再从 `node-pty` 根发现。本地提供方接受这个缺口，不向根 PID 的 POSIX 会话发送信号，因为其中可能包含无关的启动器进程。
+- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
 原始进程处理位于 `src/spawn.ts`；`src/index.ts` 负责服务接线。
diff --git a/packages/subprocess/subprocess-local/package.json b/packages/subprocess/subprocess-local/package.json
index e1429bffd0..7a68a9b91b 100644
--- a/packages/subprocess/subprocess-local/package.json
+++ b/packages/subprocess/subprocess-local/package.json
@@ -21,8 +21,12 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
+  "scripts": {
+    "postinstall": "node scripts/ensure-spawn-helper.mjs"
+  },
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
@@ -30,6 +34,9 @@
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "node-pty": "^1.1.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
diff --git a/packages/pty/pty-local/scripts/ensure-spawn-helper.mjs b/packages/subprocess/subprocess-local/scripts/ensure-spawn-helper.mjs
similarity index 100%
rename from packages/pty/pty-local/scripts/ensure-spawn-helper.mjs
rename to packages/subprocess/subprocess-local/scripts/ensure-spawn-helper.mjs
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index eea1f1e739..40d2f52552 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -7,11 +7,26 @@
  * @module @deepseek-ai/dsh-subprocess-local
  */
 
+import { constants } from 'node:fs'
+import { mkdtempSync } from 'node:fs'
+import { access, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { delimiter, extname, isAbsolute, join } from 'node:path'
 import { Context } from 'cordis'
+import * as nodePty from 'node-pty'
+import type { IPtyForkOptions } from 'node-pty'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import { spawnSubprocess } from './spawn.ts'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { childEnv, spawnSubprocess } from './spawn.ts'
 import type { SpawnInternals } from './spawn.ts'
+import { createProcessInspector } from './process-inspector.ts'
+import type { ProcessInspector } from './process-inspector.ts'
+import { LocalTerminalHandle } from './terminal.ts'
 
 /**
  * Local subprocess service: detached process trees, Node-shaped stdio
@@ -20,10 +35,16 @@ import type { SpawnInternals } from './spawn.ts'
  * SIGTERM→grace→SIGKILL escalation.
  */
 export class LocalSubprocessService extends SubprocessService {
+  readonly cwd = process.cwd()
+  readonly runtimeRoot = mkdtempSync(join(tmpdir(), 'dsh-subprocess-runtime-'))
   /** Live handles retained only so disposal can terminate and join them. */
   private live = new Set<SubprocessHandle>()
+  /** Live terminal sessions retained through whole-session quiescence. */
+  private terminals = new Set<SubprocessTerminalHandle>()
   /** Test seam: spill and platform knobs forwarded to spawnSubprocess. */
   internals: SpawnInternals = {}
+  /** Test seam for platform process inspection; production resolves lazily on terminal spawn. */
+  terminalInspector: ProcessInspector | undefined
 
   constructor(ctx: Context) {
     super(ctx)
@@ -37,11 +58,58 @@ export class LocalSubprocessService extends SubprocessService {
         // Spawn-failure rejections already settled and left the live set.
         pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
       }
+      for (const terminal of this.terminals) {
+        terminal.terminate()
+        // Cleanup may reject before the top-level process exits (for example,
+        // an identity-fenced descendant survives escalation). Await the cleanup
+        // transaction directly so disposal reports that failure rather than
+        // waiting forever on `done`.
+        pending.push(terminal.waitForExit())
+      }
       this.live.clear()
+      this.terminals.clear()
       await Promise.all(pending)
+      await rm(this.runtimeRoot, { recursive: true, force: true })
     }, 'local subprocess teardown')
   }
 
+  async resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    if (command.length === 0) throw new Error('subprocess-local: executable must be non-empty')
+    signal?.throwIfAborted()
+    const environment = childEnv(env)
+    const absolute = isAbsolute(command)
+    const candidates = absolute ? [command] : this.executableCandidates(command, environment)
+    for (const candidate of candidates) {
+      signal?.throwIfAborted()
+      try {
+        const info = await stat(candidate)
+        if (!info.isFile()) continue
+        await access(candidate, constants.X_OK)
+        signal?.throwIfAborted()
+        return candidate
+      } catch {
+        // Try the next PATH candidate; the final miss receives one stable error.
+      }
+    }
+    signal?.throwIfAborted()
+    throw new Error(absolute
+      ? `subprocess-local: command ${JSON.stringify(command)} is not an executable file`
+      : `subprocess-local: command ${JSON.stringify(command)} was not found on PATH`)
+  }
+
+  private executableCandidates(command: string, env: NodeJS.ProcessEnv): string[] {
+    const path = env.PATH ?? ''
+    const extensions = process.platform === 'win32' && extname(command) === ''
+      ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+      : ['']
+    return path.split(delimiter).flatMap(directory =>
+      directory === '' ? [] : extensions.map(extension => join(directory, command + extension)))
+  }
+
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
     const handle = spawnSubprocess(spec, this.internals)
     this.live.add(handle)
@@ -54,6 +122,38 @@ export class LocalSubprocessService extends SubprocessService {
     handle.done.then(release, release)
     return handle
   }
+
+  // Local PTY allocation is synchronous, but the provider seam permits remote asynchronous allocation.
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    const file = spec.argv[0]
+    if (file === undefined || file.length === 0) {
+      throw new Error('subprocess-local: terminal argv must contain a program')
+    }
+    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`subprocess-local: terminal ${name} must be a positive safe integer`)
+      }
+    }
+    spec.signal?.throwIfAborted()
+    const options: IPtyForkOptions = {
+      name: 'dumb',
+      rows: spec.rows,
+      cols: spec.cols,
+      cwd: spec.cwd,
+      env: childEnv(spec.env),
+    }
+    const inspector = this.terminalInspector ?? createProcessInspector()
+    const terminal = nodePty.spawn(file, [...spec.argv.slice(1)], options)
+    const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs, spec.signal)
+    this.terminals.add(handle)
+    const release = async (): Promise<void> => {
+      await handle.waitForExit()
+      this.terminals.delete(handle)
+    }
+    void handle.done.then(release, release).catch(() => {})
+    return handle
+  }
 }
 
 export default LocalSubprocessService
diff --git a/packages/pty/pty-local/src/process-inspector.ts b/packages/subprocess/subprocess-local/src/process-inspector.ts
similarity index 96%
rename from packages/pty/pty-local/src/process-inspector.ts
rename to packages/subprocess/subprocess-local/src/process-inspector.ts
index 5be25a224a..f57184f289 100644
--- a/packages/pty/pty-local/src/process-inspector.ts
+++ b/packages/subprocess/subprocess-local/src/process-inspector.ts
@@ -1,8 +1,8 @@
-/** Platform process-table inspection used for readiness, signals, and teardown. */
+/** Platform process-table inspection for terminal readiness, signals, and teardown. */
 
 import { closeSync, openSync, readFileSync, readdirSync, readSync } from 'node:fs'
 import { execFileSync } from 'node:child_process'
-import type { PtySignal } from '@deepseek-ai/dsh-pty'
+import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess'
 
 /** PID plus start identity, preventing teardown escalation after PID reuse. */
 export interface ProcessIdentity {
@@ -18,7 +18,7 @@ export interface ProcessInspector {
   processTree(rootPid: number): ProcessIdentity[]
   /** Return whether the exact identity remains a non-quiescent process. */
   isAlive(identity: ProcessIdentity): boolean
-  signalGroup(pgid: number, signal: PtySignal): void
+  signalGroup(pgid: number, signal: SubprocessTerminalSignal): void
   signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void
 }
 
@@ -203,7 +203,7 @@ abstract class PosixProcessInspector implements ProcessInspector {
   abstract processTree(rootPid: number): ProcessIdentity[]
   abstract isAlive(identity: ProcessIdentity): boolean
 
-  signalGroup(pgid: number, signal: PtySignal): void {
+  signalGroup(pgid: number, signal: SubprocessTerminalSignal): void {
     this.internals.kill(-pgid, signal)
   }
 
@@ -327,5 +327,5 @@ export function createProcessInspector(
 ): ProcessInspector {
   if (platform === 'linux') return new LinuxProcessInspector(arch, internals)
   if (platform === 'darwin') return new MacProcessInspector(internals)
-  throw new Error(`pty-local: unsupported platform ${platform}`)
+  throw new Error(`subprocess-local: terminal inspection is unsupported on platform ${platform}`)
 }
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
new file mode 100644
index 0000000000..d4b7bd26d1
--- /dev/null
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -0,0 +1,226 @@
+/** Local node-pty terminal-process implementation for the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:os'
+import { PassThrough } from 'node:stream'
+import type { IDisposable, IPty } from 'node-pty'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+} from '@deepseek-ai/dsh-subprocess'
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function signalName(number: number | undefined): NodeJS.Signals | null {
+  if (number === undefined || number === 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
+
+/** A local terminal whose process-session ownership stays below the PTY backend. */
+export class LocalTerminalHandle implements SubprocessTerminalHandle {
+  readonly pid: number
+  readonly output = new PassThrough()
+  readonly done: Promise<SubprocessOutcome>
+
+  private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
+  private readonly dataDisposable: IDisposable
+  private readonly exitDisposable: IDisposable
+  private exited = false
+  private termination: Promise<void> | undefined
+  private removeAbort: (() => void) | undefined
+
+  /**
+   * @param terminal - allocated node-pty process.
+   * @param inspector - platform process/session operations.
+   * @param graceMs - TERM-to-KILL and exit-wait grace.
+   * @param signal - optional lifetime cancellation.
+   */
+  constructor(
+    private readonly terminal: IPty,
+    private readonly inspector: ProcessInspector,
+    private readonly graceMs: number,
+    signal?: AbortSignal,
+  ) {
+    this.pid = terminal.pid
+    this.done = this.outcome.promise
+    this.dataDisposable = terminal.onData((data) => { this.output.write(Buffer.from(data, 'utf8')) })
+    this.exitDisposable = terminal.onExit(({ exitCode, signal: exitSignal }) => {
+      if (this.exited) return
+      this.exited = true
+      this.output.end()
+      this.outcome.resolve({
+        exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
+        signal: signalName(exitSignal),
+      })
+      this.terminate()
+    })
+    if (signal !== undefined) {
+      const onAbort = (): void => { this.terminate() }
+      signal.addEventListener('abort', onAbort, { once: true })
+      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+      if (signal.aborted) this.terminate()
+    }
+  }
+
+  // node-pty writes synchronously; the seam returns a promise for remote transports.
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async write(data: Uint8Array): Promise<void> {
+    if (this.exited) throw new Error('terminal process has exited')
+    let text: string
+    try {
+      text = new TextDecoder('utf-8', { fatal: true }).decode(data)
+    } catch (error: unknown) {
+      throw new Error('terminal input must be valid UTF-8', { cause: error })
+    }
+    this.terminal.write(text)
+  }
+
+  // Local inspection is synchronous; the seam returns a promise for remote transports.
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    const processGroupId = this.inspector.foregroundPgid(this.pid)
+    if (processGroupId === undefined) return undefined
+    return {
+      processGroupId,
+      inputWaiting: this.inspector.isStdinWaiting(processGroupId),
+    }
+  }
+
+  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    const foreground = await this.inspectForeground()
+    if (foreground === undefined) {
+      throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`)
+    }
+    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+    }
+    this.inspector.signalGroup(foreground.processGroupId, signal)
+    return foreground.processGroupId
+  }
+
+  terminate(): void {
+    this.termination ??= this.closeOnce().catch((error: unknown) => {
+      this.termination = undefined
+      throw error
+    })
+    void this.termination.catch(() => {})
+  }
+
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    // A caller may begin waiting before the top-level process exits. The exit
+    // callback starts descendant cleanup in the same turn, so resolve that
+    // eventual transaction after `done` instead of snapshotting only `done`.
+    const quiescence = this.termination ?? this.done.then(() => this.termination)
+    if (signal === undefined) {
+      await quiescence
+      return true
+    }
+    if (signal.aborted) return false
+    return await new Promise<boolean>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(false) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void quiescence.then(
+        () => { cleanup(); resolve(true) },
+        (error: unknown) => {
+          cleanup()
+          // The owned cleanup transaction only throws Error diagnostics.
+          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+          reject(error)
+        },
+      )
+    })
+  }
+
+  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
+    return members.filter(member => this.inspector.isAlive(member))
+  }
+
+  private descendants(): ProcessIdentity[] {
+    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+  }
+
+  private async waitForMembers(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
+    const until = Date.now() + this.graceMs
+    let survivors = this.survivors(members)
+    while (survivors.length > 0 && Date.now() < until) {
+      await delay(Math.min(25, Math.max(1, until - Date.now())))
+      survivors = this.survivors(members)
+    }
+    return survivors
+  }
+
+  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
+    for (const member of members) {
+      try {
+        this.inspector.signalProcess(member, signal)
+      } catch (_alreadyExitedDuringSignal) {
+        // The exact process identity is rechecked; a same-tick exit is success.
+      }
+    }
+  }
+
+  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
+    const members: ProcessIdentity[] = []
+    const seen = new Set<string>()
+    for (const group of groups) {
+      for (const member of group) {
+        const key = `${member.pid}:${member.started}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        members.push(member)
+      }
+    }
+    return members
+  }
+
+  private async stopDescendants(): Promise<ProcessIdentity[]> {
+    const captured = this.descendants()
+    this.signalMembers(captured, 'SIGTERM')
+    const capturedSurvivors = await this.waitForMembers(captured)
+    const members = this.unionMembers(capturedSurvivors, this.descendants())
+    this.signalMembers(members, 'SIGKILL')
+    const survivors = await this.waitForMembers(members)
+    return this.survivors(this.unionMembers(survivors, this.descendants()))
+  }
+
+  private async stopShell(): Promise<void> {
+    if (!this.exited) {
+      try {
+        this.terminal.kill('SIGTERM')
+      } catch (_topLevelAlreadyExitedDuringTerm) {
+        // The exit callback is authoritative.
+      }
+      await Promise.race([this.done.then(() => undefined), delay(this.graceMs)])
+    }
+    if (!this.exited) {
+      try {
+        this.terminal.kill('SIGKILL')
+      } catch (_topLevelAlreadyExitedDuringKill) {
+        // The exit callback is authoritative.
+      }
+      await Promise.race([this.done.then(() => undefined), delay(this.graceMs)])
+    }
+    if (!this.exited) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`)
+  }
+
+  private async closeOnce(): Promise<void> {
+    const survivors = await this.stopDescendants()
+    if (survivors.length > 0) {
+      throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    }
+    await this.stopShell()
+    this.removeAbort?.()
+    this.removeAbort = undefined
+    this.dataDisposable.dispose()
+    this.exitDisposable.dispose()
+  }
+}
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index ca723fdb87..bc77d24cfd 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,7 +1,10 @@
-import { describe, expect, it } from 'vitest'
+import { PassThrough } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import { stat } from 'node:fs/promises'
+import { basename, delimiter, dirname } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
-import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 
 function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): SubprocessSpawnSpec {
   return {
@@ -18,6 +21,133 @@ function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): Su
 }
 
 describe('LocalSubprocessService', () => {
+  it('publishes execution-world paths and removes its private runtime directory', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const root = ctx.subprocess.runtimeRoot
+    expect(ctx.subprocess.cwd).toBe(process.cwd())
+    expect((await stat(root)).isDirectory()).toBe(true)
+    await fiber.dispose()
+    await expect(stat(root)).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
+  it('resolves absolute and PATH executables and honors lookup cancellation', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    expect(await ctx.subprocess.resolveExecutable(process.execPath)).toBe(process.execPath)
+    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
+      PATH: dirname(process.execPath),
+    })).toBe(process.execPath)
+    await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
+    await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
+      .rejects.toThrow('was not found on PATH')
+    await expect(ctx.subprocess.resolveExecutable('/dsh-absolute-command-that-does-not-exist'))
+      .rejects.toThrow('is not an executable file')
+    await expect(ctx.subprocess.resolveExecutable(process.cwd()))
+      .rejects.toThrow('is not an executable file')
+    await expect(ctx.subprocess.resolveExecutable(process.execPath, {}, AbortSignal.abort('stop')))
+      .rejects.toBe('stop')
+    await fiber.dispose()
+  })
+
+  it('builds Windows executable candidates without empty PATH entries', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const service = ctx.subprocess as LocalSubprocessService
+    const candidates = (service as unknown as {
+      executableCandidates(command: string, env: NodeJS.ProcessEnv): string[]
+    }).executableCandidates.bind(service)
+    const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
+    try {
+      expect(candidates('tool', { PATH: `${delimiter}/bin`, PATHEXT: '.EXE;.CMD' }))
+        .toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
+      expect(candidates('tool.exe', {})).toEqual([])
+      expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
+    } finally {
+      platform.mockRestore()
+      await fiber.dispose()
+    }
+  })
+
+  it('validates terminal spawn specs before allocating a PTY', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const base: SubprocessTerminalSpawnSpec = {
+      argv: ['bash'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 10,
+    }
+    await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [] })).rejects.toThrow('must contain a program')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [''] })).rejects.toThrow('must contain a program')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, rows: 1.5 })).rejects.toThrow('rows')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, cols: 0 })).rejects.toThrow('cols')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, graceMs: 0 })).rejects.toThrow('graceMs')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, signal: AbortSignal.abort('stop') })).rejects.toBe('stop')
+    await fiber.dispose()
+  })
+
+  it('terminates and joins an owned terminal during disposal', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const terminate = vi.fn()
+    const waitForExit = vi.fn(async () => true)
+    const terminal: SubprocessTerminalHandle = {
+      pid: 1,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => undefined,
+      signalForeground: async () => 1,
+      terminate,
+      waitForExit,
+    }
+    ;(ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.add(terminal)
+    await fiber.dispose()
+    expect(terminate).toHaveBeenCalledOnce()
+    expect(waitForExit).toHaveBeenCalledOnce()
+  })
+
+  it('contains a terminal release failure after top-level exit', async () => {
+    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
+    const terminal = {
+      pid: 123,
+      onData: () => ({ dispose: () => {} }),
+      onExit: (listener: (event: { exitCode: number; signal?: number }) => void) => {
+        exitListener = listener
+        return { dispose: () => {} }
+      },
+      write: () => {},
+      kill: () => {},
+    }
+    vi.resetModules()
+    vi.doMock('node-pty', () => ({ spawn: () => terminal }))
+    try {
+      const { default: IsolatedLocalSubprocessService } = await import('../src/index.ts')
+      const ctx = new Context()
+      const fiber = await ctx.plugin(IsolatedLocalSubprocessService)
+      const alive = new Set([124])
+      ;(ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>).terminalInspector = {
+        foregroundPgid: () => 123,
+        isStdinWaiting: () => false,
+        processTree: () => [{ pid: 124, started: 'child' }],
+        isAlive: identity => alive.has(identity.pid),
+        signalGroup: () => {},
+        signalProcess: () => {},
+      }
+      const handle = await ctx.subprocess.spawnTerminal({
+        argv: ['shell'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 1,
+      })
+      exitListener?.({ exitCode: 0 })
+      await handle.done
+      await new Promise(resolve => setTimeout(resolve, 10))
+      alive.clear()
+      handle.terminate()
+      await handle.waitForExit()
+      await fiber.dispose()
+    } finally {
+      vi.doUnmock('node-pty')
+      vi.resetModules()
+    }
+  })
+
   it('registers as ctx.subprocess and spawns managed handles', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
diff --git a/packages/pty/pty-local/tests/process-inspector.spec.ts b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
similarity index 98%
rename from packages/pty/pty-local/tests/process-inspector.spec.ts
rename to packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
index 218a3d77fe..e8ad2fd11e 100644
--- a/packages/pty/pty-local/tests/process-inspector.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
-import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
+import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
+import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 
 function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1, state = 'S'): string {
   const rest = [state, String(parentPid), String(pgrp), String(session), '99', String(tpgid)]
@@ -216,6 +216,6 @@ describe('macOS process inspector', () => {
     expect(createProcessInspector('darwin', 'arm64', fake.internals).foregroundPgid(1)).toBeUndefined()
     fake.internals.exec = () => { throw new Error('gone') }
     expect(createProcessInspector('darwin', 'arm64', fake.internals).foregroundPgid(1)).toBeUndefined()
-    expect(() => createProcessInspector('win32', 'x64', fake.internals)).toThrow('unsupported platform win32')
+    expect(() => createProcessInspector('win32', 'x64', fake.internals)).toThrow('unsupported on platform win32')
   })
 })
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
new file mode 100644
index 0000000000..417fd62517
--- /dev/null
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -0,0 +1,275 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { IDisposable, IPty } from 'node-pty'
+import { LocalTerminalHandle } from '@deepseek-ai/dsh-subprocess-local/src/terminal.ts'
+import type {
+  ProcessIdentity,
+  ProcessInspector,
+} from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
+import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess'
+
+class FakePty {
+  pid = 123
+  readonly writes: string[] = []
+  readonly kills: string[] = []
+  autoExitOnKill = true
+  throwKill = false
+  private readonly dataListeners = new Set<(data: string) => void>()
+  private readonly exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
+
+  readonly onData = (listener: (data: string) => void): IDisposable => {
+    this.dataListeners.add(listener)
+    return { dispose: () => { this.dataListeners.delete(listener) } }
+  }
+
+  readonly onExit = (listener: (event: { exitCode: number; signal?: number }) => void): IDisposable => {
+    this.exitListeners.add(listener)
+    return { dispose: () => { this.exitListeners.delete(listener) } }
+  }
+
+  emitData(data: string): void {
+    for (const listener of this.dataListeners) listener(data)
+  }
+
+  emitExit(exitCode = 0, signal?: number): void {
+    for (const listener of this.exitListeners) listener({ exitCode, ...signal === undefined ? {} : { signal } })
+  }
+
+  write(data: string): void { this.writes.push(data) }
+
+  kill(signal?: string): void {
+    if (this.throwKill) throw new Error('process raced')
+    this.kills.push(signal ?? 'SIGHUP')
+    if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
+  }
+
+  asPty(): IPty {
+    return this as unknown as IPty
+  }
+}
+
+class FakeInspector implements ProcessInspector {
+  pgid: number | undefined = 456
+  waiting = false
+  members: ProcessIdentity[] = []
+  readonly alive = new Set<number>()
+  readonly groups: Array<[number, SubprocessTerminalSignal]> = []
+  readonly processes: Array<[number, 'SIGTERM' | 'SIGKILL']> = []
+  throwGroup = false
+  throwProcess = false
+  removeOnSignal = true
+
+  foregroundPgid() { return this.pgid }
+  isStdinWaiting() { return this.waiting }
+  processTree() { return this.members }
+  isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
+  signalGroup(pgid: number, signal: SubprocessTerminalSignal) {
+    if (this.throwGroup) throw new Error('group failed')
+    this.groups.push([pgid, signal])
+  }
+  signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL') {
+    if (this.throwProcess) throw new Error('process raced')
+    this.processes.push([identity.pid, signal])
+    if (this.removeOnSignal) this.alive.delete(identity.pid)
+  }
+}
+
+afterEach(() => { vi.useRealTimers() })
+
+describe('LocalTerminalHandle', () => {
+  it('bridges terminal bytes, foreground control, and signalled exit facts', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.waiting = true
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+    const chunks: Buffer[] = []
+    handle.output.on('data', (chunk: Buffer) => { chunks.push(chunk) })
+
+    pty.emitData('hello €')
+    await handle.write(Buffer.from('input\r'))
+    expect(pty.writes).toEqual(['input\r'])
+    expect(await handle.inspectForeground()).toEqual({ processGroupId: 456, inputWaiting: true })
+    expect(await handle.signalForeground('SIGINT')).toBe(456)
+    expect(inspector.groups).toEqual([[456, 'SIGINT']])
+
+    pty.emitExit(7, 9)
+    pty.emitExit(0)
+    expect(await handle.done).toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(await handle.waitForExit()).toBe(true)
+    expect(Buffer.concat(chunks).toString('utf8')).toBe('hello €')
+  })
+
+  it('rejects invalid input and unsafe foreground signals', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+    await expect(handle.write(Uint8Array.from([0xff]))).rejects.toThrow('valid UTF-8')
+
+    inspector.pgid = handle.pid
+    await expect(handle.signalForeground('SIGKILL')).rejects.toThrow('terminate the terminal session')
+    inspector.pgid = undefined
+    expect(await handle.inspectForeground()).toBeUndefined()
+    await expect(handle.signalForeground('SIGTERM')).rejects.toThrow('cannot resolve')
+
+    pty.emitExit(3)
+    expect(await handle.done).toEqual({ exitCode: 3, signal: null })
+    await handle.waitForExit()
+    await expect(handle.write(Buffer.from('late'))).rejects.toThrow('has exited')
+  })
+
+  it('keeps the shell alive until forced descendants leave', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+
+    handle.terminate()
+    const quiescent = handle.waitForExit()
+    await vi.advanceTimersByTimeAsync(20)
+    expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
+    expect(pty.kills).toEqual([])
+
+    inspector.alive.delete(124)
+    await vi.advanceTimersByTimeAsync(20)
+    expect(await quiescent).toBe(true)
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('keeps an early exit wait pending through descendant cleanup', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+    const waiting = handle.waitForExit()
+    let settled = false
+    void waiting.then(() => { settled = true })
+
+    pty.emitExit()
+    await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(false)
+
+    inspector.alive.delete(124)
+    await vi.advanceTimersByTimeAsync(20)
+    expect(await waiting).toBe(true)
+  })
+
+  it('rescans for descendants forked during TERM', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    let reads = 0
+    inspector.processTree = () => {
+      reads += 1
+      if (reads === 1) {
+        inspector.alive.add(124)
+        return [{ pid: 124, started: 'first' }]
+      }
+      if (reads === 2) {
+        inspector.alive.add(125)
+        return [{ pid: 125, started: 'late' }]
+      }
+      return []
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+    handle.terminate()
+    await handle.waitForExit()
+    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('retains captured descendants after reparenting', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const captured = { pid: 124, started: 'captured' }
+    let reads = 0
+    inspector.alive.add(captured.pid)
+    inspector.processTree = () => reads++ === 0 ? [captured] : []
+    inspector.signalProcess = (identity, signal) => {
+      inspector.processes.push([identity.pid, signal])
+      if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+    handle.terminate()
+    const quiescent = handle.waitForExit()
+    await vi.advanceTimersByTimeAsync(25)
+    expect(await quiescent).toBe(true)
+    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
+  })
+
+  it('allows cleanup to retry after a surviving descendant leaves', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    handle.terminate()
+    const first = expect(handle.waitForExit(new AbortController().signal)).rejects.toThrow('surviving pids: 124')
+    await vi.advanceTimersByTimeAsync(25)
+    await first
+
+    inspector.alive.delete(124)
+    handle.terminate()
+    expect(await handle.waitForExit()).toBe(true)
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('bounds waits and reports a top-level process that ignores escalation', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    pty.autoExitOnKill = false
+    const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10)
+    expect(await handle.waitForExit(AbortSignal.abort())).toBe(false)
+    const controller = new AbortController()
+    const bounded = handle.waitForExit(controller.signal)
+    controller.abort()
+    expect(await bounded).toBe(false)
+
+    handle.terminate()
+    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pid: 123')
+    await vi.advanceTimersByTimeAsync(25)
+    await failed
+    expect(pty.kills).toEqual(['SIGTERM', 'SIGKILL'])
+
+    pty.emitExit(0, 999)
+    expect(await handle.done).toEqual({ exitCode: null, signal: null })
+    handle.terminate()
+    expect(await handle.waitForExit()).toBe(true)
+  })
+
+  it('contains process races and reacts to lifetime cancellation', async () => {
+    const pty = new FakePty()
+    pty.throwKill = true
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.throwProcess = true
+    const controller = new AbortController()
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 1, controller.signal)
+    controller.abort()
+    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
+    await failed
+
+    inspector.alive.delete(124)
+    pty.throwKill = false
+    handle.terminate()
+    await handle.waitForExit()
+
+    const preAbortedPty = new FakePty()
+    const preAborted = new LocalTerminalHandle(
+      preAbortedPty.asPty(),
+      new FakeInspector(),
+      1,
+      AbortSignal.abort('stop'),
+    )
+    await preAborted.waitForExit()
+    expect(preAbortedPty.kills).toEqual(['SIGTERM'])
+  })
+})
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index b178daafb2..84d7d4a666 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: e59dd96df036826f36bd0286c977438d2d87d1cf
-README.zh.md: e8fb89dfd1f8c41a0caefc96469c13d9ae7d415d
+README.md: 84b4b0c11c74c96929fa97b58fb33156d44e6ef1
+README.zh.md: dbd80a1c975719884481501f5cc43798e464a4fb
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index e59dd96df0..84b4b0c11c 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -2,15 +2,17 @@
 
 English | [中文](README.zh.md)
 
-The subprocess seam (`ctx.subprocess`). The abstract `SubprocessService` exposes one method — `spawn(spec): SubprocessHandle` — plus the vocabulary shared by every consumer: the fully-explicit `SubprocessSpawnSpec`, `SubprocessHandle` with its non-consuming offset-based output readers, `SubprocessOutcome`, `CollectedOutput`, and the managed `DSH_*` environment namespace (`DSH_ENV_PREFIX`, `DshEnvironment`). The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
+The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, private `runtimeRoot`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
 
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). Grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so the implementation can represent it with one Node timer instead of accepting a value that Node collapses to one millisecond. `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
+- `cwd` and `runtimeRoot` are absolute paths in the provider's execution world. Consumers materialize private helpers below `runtimeRoot`, never in a host-only temp directory. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
+- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and the spec's explicit `env` merges after the scrub with no namespace validation — a string deliberately forwards or overrides a value, while an `undefined` tombstone removes an ordinary ambient entry. Spawners that cannot route through the service (node-pty backends, SDK-managed transports) import the scrub.
+- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, valid-UTF-8 byte I/O, foreground-process-group inspection/signalling, TERM-to-KILL whole-session cleanup, and a quiescence wait. The output stream ends after queued output when the top-level process exits; a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or prove and clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
 See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
@@ -25,5 +27,5 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **node-pty and SDK-managed spawns share only the scrub** — the PTY backend's terminal fork and the MCP SDK's own stdio transport cannot route their spawns through this seam (the library owns the fork/spawn call); they import `scrubbedParentEnv` so the environment policy stays single-sourced.
+- **SDK-managed spawns remain outside** — an SDK transport that owns its internal spawn cannot route that call through this service; it can still import `scrubbedParentEnv` so environment policy stays single-sourced.
 - **Teardown ladders are consumer-owned** — the seam ships signalling verbs and the tree-liveness wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index e8fb89dfd1..dbd80a1c97 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,28 +2,30 @@
 
 [English](README.md) | 中文
 
-子进程 seam（`ctx.subprocess`）。抽象的 `SubprocessService` 只暴露一个方法：`spawn(spec): SubprocessHandle`，外加所有消费方共享的词汇：完全显式的 `SubprocessSpawnSpec`、携带基于偏移量的非消费式输出读取器的 `SubprocessHandle`、`SubprocessOutcome`、`CollectedOutput`，以及受管的 `DSH_*` 环境命名空间（`DSH_ENV_PREFIX`、`DshEnvironment`）。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+进程管理器 seam（`ctx.subprocess`）是同一执行世界中的进程侧。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
-- `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样实现便可用一个 Node 定时器表示它，而不会接受会被 Node 折叠为 1 毫秒的值。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
-- stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
+- `spawn(spec)` 立即返回一个实时句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
+- `cwd` 与 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，spec 的显式 `env` 在清理后合并且不做命名空间校验——字符串会有意转发或覆盖某个值，而 `undefined` tombstone 则会删除普通的环境条目。无法把 spawn 路由到该服务的进程启动方（node-pty 后端、由 SDK 管理的传输层）会导入该环境清理定义。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、有效 UTF-8 字节 I/O、前台进程组检查／信号发送、TERM→KILL 全会话清理，以及等待完全停稳。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法证明并清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[进程管理器数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由消费方负责。
+通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归消费方所有。
 
 #### KV Cache 影响
 
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+不会直接失效；请求前缀变更由具名消费方负责。
 
 ## 已知限制与暂缓事项
 
-- **node-pty 与由 SDK 管理的 spawn 只共享环境清理**：PTY 后端的终端 fork 与 MCP SDK 自己的 stdio 传输层无法把 spawn 路由到这道 seam（fork/spawn 调用归库所有）；它们改为导入 `scrubbedParentEnv`，使环境策略保持单一来源。
-- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
+- **由 SDK 管理的 spawn 仍在服务之外**：自行拥有内部 spawn 的 SDK 传输层无法经该服务路由这次调用；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
+- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合形状（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index d484faa24d..3c58a07a9e 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -1,10 +1,9 @@
 /**
- * The subprocess seam (`ctx.subprocess`): spawn fully-specified commands into
- * managed process trees with Node-shaped stdio dispositions — raw pipes for
- * protocol streams, inherit for diagnostics, bounded spill-backed collection
- * for batch output — plus tree-scoped signalling. Command defaulting, shell
- * semantics, deadlines, teardown ladders, framing, and presentation belong to
- * consumers; the bash executor seam is the owning template. The local implementation lives in
+ * The subprocess seam (`ctx.subprocess`): execution-world process coordinates,
+ * executable lookup, fully specified managed process trees with raw or
+ * collected stdio, and one terminal-process primitive. Command defaulting,
+ * shell semantics, deadlines, protocol framing, terminal readiness, and
+ * presentation belong to consumers. The local implementation lives in
  * `@deepseek-ai/dsh-subprocess-local`.
  * @module @deepseek-ai/dsh-subprocess
  */
@@ -12,6 +11,7 @@
 import { Context, Service } from 'cordis'
 import { DSH_ENV_PREFIX } from './types.ts'
 import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts'
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts'
 
 export { DSH_ENV_PREFIX } from './types.ts'
 export type {
@@ -28,6 +28,10 @@ export type {
   SubprocessSpawnSpec,
   SubprocessStdinMode,
   SubprocessStdio,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+  SubprocessTerminalSpawnSpec,
 } from './types.ts'
 
 /**
@@ -74,6 +78,8 @@ declare module 'cordis' {
  * duplicate-service behavior).
  *
  * Implementations must honor these semantics:
+ * - {@link cwd}, {@link runtimeRoot}, and executable paths belong to one
+ *   execution world shared with the mounted filesystem provider.
  * - {@link spawn} returns immediately with a live handle; `done` resolves at
  *   process close with exit facts and rejects only for spawn-level failures.
  * - Collect-mode readers are offset-based and non-consuming, so independent
@@ -87,12 +93,37 @@ declare module 'cordis' {
  *   quiescence.
  * - Disposal of the service terminates all still-running managed processes
  *   and awaits their exit.
+ * - {@link spawnTerminal} owns terminal allocation, byte transport,
+ *   foreground groups, signalling, and whole-session quiescence; readiness
+ *   and persistent-shell policy stay in the PTY consumer. Its output stream
+ *   ends after queued terminal output when the top-level process exits.
  */
 export abstract class SubprocessService extends Service {
   constructor(ctx: Context) {
     super(ctx, 'subprocess')
   }
 
+  /** Canonical default cwd in this provider's execution world. */
+  abstract readonly cwd: string
+
+  /** Private directory for runtime artifacts in this provider's execution world. */
+  abstract readonly runtimeRoot: string
+
+  /**
+   * Resolve one configured executable in this provider's execution world.
+   * Absolute paths are verified; bare names use the provider's scrubbed PATH
+   * plus explicit environment overrides.
+   * @param command - absolute executable path or bare PATH name.
+   * @param env - explicit environment entries used for lookup.
+   * @param signal - aborts remote or local lookup.
+   * @returns a canonical executable path.
+   */
+  abstract resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string>
+
   /**
    * Start one managed child process from a fully-specified spec; this seam
    * applies no defaults.
@@ -100,6 +131,15 @@ export abstract class SubprocessService extends Service {
    * @returns the live process handle (streams/readers, signalling, outcome promise).
    */
   abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+  /**
+   * Allocate a real terminal and start one owned process session. This is the
+   * only non-pipe process primitive: implementations own terminal byte I/O,
+   * foreground groups, signals, and complete session-tree cleanup.
+   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.
+   * @returns the live terminal handle after allocation succeeds.
+   */
+  abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
 }
 
 export default SubprocessService
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 6084cc8c8e..206104ad5b 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -192,3 +192,71 @@ export interface SubprocessHandle {
    */
   waitForExit(signal?: AbortSignal): Promise<boolean>
 }
+
+/** Signals supported by the terminal-process primitive. */
+export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP'
+
+/** A fully specified terminal-process spawn. */
+export interface SubprocessTerminalSpawnSpec {
+  /** Executable and arguments; `argv[0]` is the program. */
+  argv: readonly string[]
+  /** Working directory in this subprocess provider's execution world. */
+  cwd: string
+  /** Explicit environment layered after the provider's ambient scrub. */
+  env?: Record<string, string> | undefined
+  /** Initial terminal row count. */
+  rows: number
+  /** Initial terminal column count. */
+  cols: number
+  /** TERM-to-KILL cleanup grace for the complete terminal session. */
+  graceMs: number
+  /** Cancellation of setup or the live terminal session. */
+  signal?: AbortSignal | undefined
+}
+
+/** Current foreground process-group facts for one terminal. */
+export interface SubprocessTerminalForeground {
+  /** Foreground process-group id published by the terminal driver. */
+  processGroupId: number
+  /** Whether the provider can currently prove that group is waiting on terminal input. */
+  inputWaiting: boolean
+}
+
+/**
+ * One live terminal process and its owned OS session. Terminal allocation,
+ * foreground-group inspection/signalling, and session-tree cleanup are one
+ * deep subprocess primitive because none can be reconstructed from ordinary
+ * piped stdio without substrate-specific process control.
+ */
+export interface SubprocessTerminalHandle {
+  /** Top-level terminal process id. */
+  readonly pid: number
+  /** UTF-8 terminal output bytes in delivery order; ends after queued output when the terminal exits. */
+  readonly output: Readable
+  /** Resolves when the top-level process exits; rejects only for a live transport failure. */
+  readonly done: Promise<SubprocessOutcome>
+  /**
+   * Write bytes to the terminal input.
+   * @param data - valid UTF-8 bytes to deliver without implicit newline conversion.
+   */
+  write(data: Uint8Array): Promise<void>
+  /**
+   * Inspect the current foreground process group.
+   * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
+   */
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined>
+  /**
+   * Deliver a signal to the current foreground process group.
+   * @param signal - permitted terminal signal.
+   * @returns the exact group id that received it.
+   */
+  signalForeground(signal: SubprocessTerminalSignal): Promise<number>
+  /** Begin idempotent TERM-to-KILL cleanup of the complete terminal session. */
+  terminate(): void
+  /**
+   * Await whole-session quiescence, not only top-level process exit.
+   * @param signal - optional bound for this wait.
+   * @returns true after quiescence, false when `signal` aborts first.
+   */
+  waitForExit(signal?: AbortSignal): Promise<boolean>
+}
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index d0ef5c9fd6..853b333400 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -1,7 +1,14 @@
 import { describe, expect, it } from 'vitest'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import { scrubbedParentEnv, SubprocessService } from '@deepseek-ai/dsh-subprocess'
-import type { SubprocessHandle, SubprocessOutputRead, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessOutputRead,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
 
 /**
  * Minimal concrete service: a hand-built handle. The seam is spawn-only —
@@ -9,6 +16,13 @@ import type { SubprocessHandle, SubprocessOutputRead, SubprocessSpawnSpec } from
  * is all an implementation owes the abstract class.
  */
 class StubSubprocessService extends SubprocessService {
+  readonly cwd = '/stub'
+  readonly runtimeRoot = '/stub/.runtime'
+
+  async resolveExecutable(command: string): Promise<string> {
+    return `/bin/${command}`
+  }
+
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
     const read: SubprocessOutputRead = { text: '', nextOffset: 0, lossy: false }
     const collected = spec.stdio.stdout !== 'pipe' && spec.stdio.stdout !== 'inherit'
@@ -25,6 +39,19 @@ class StubSubprocessService extends SubprocessService {
       waitForExit: () => Promise.resolve(true),
     }
   }
+
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    return {
+      pid: spec.argv.length,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => ({ processGroupId: 1, inputWaiting: true }),
+      signalForeground: async () => 1,
+      terminate: () => {},
+      waitForExit: async () => true,
+    }
+  }
 }
 
 describe('SubprocessService seam', () => {
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 355b817e68..b20d5b5f3b 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -148,6 +148,7 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     'lib/invariant.js',
     ...manifest.bin ? ['lib/bin.js'] : [],
     ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
+    ...exportDefault(manifest, './runtime-host') === './lib/runtime-host.js' ? ['lib/runtime-host.js'] : [],
     // UI plugin packages ship their browser bundle beside the node lib
     // (single-artifact ruling: dist/ retired, ./client resolves lib/client.js).
     // Keyed on the artifact path, not the subpath name: apiproxy's ./client is
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 6d9665236a..256ae90caa 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -73,6 +73,8 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SubprocessOutputRead: 'subprocess.md',
   SubprocessOutputReader: 'subprocess.md',
   SubprocessSpawnSpec: 'subprocess.md',
+  SubprocessTerminalHandle: 'subprocess.md',
+  SubprocessTerminalSpawnSpec: 'subprocess.md',
   CodeRunRequest: 'code-runtime.md',
   CodeRunResult: 'code-runtime.md',
   CompactionResult: 'compaction.md',
@@ -242,6 +244,7 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'Partial',
   'Pick',
   'Promise',
+  'Record',
   'Readonly',
 ])
 
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 77432e7dbe..74a09a874e 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -623,11 +623,12 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     'packages/api/remotes/tests/built-lib.e2e.ts',
-    // The worker-entry packages' built bundles: the only automated proof
-    // that lib/index.js resolves its sibling lib/worker.cjs under plain node
-    // (the e2e lane runs unbuilt, so these files self-skip there).
+    // Built execution consumers: the only automated proof that package-name
+    // imports reach their lib/ entrypoints under plain Node. The e2e lane runs
+    // unbuilt, so these files self-skip there.
     'packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts',
     'packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts',
+    'packages/lsp/lsp-local/tests/built-lib.e2e.ts',
   ], {
     label: 'built-bin smoke',
     needs,
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 3ca0317cf4..9a249ca844 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,6 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/code-runtime/code-runtime-subprocess': { kind: 'indirect', reason: 'The subprocess backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1a8ef6508a..6252733511 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -169,6 +169,7 @@
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
+    { "path": "./packages/code-runtime/code-runtime-subprocess" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
     { "path": "./packages/bash/bash-local" },

From 16cac3b5afb7e829a3f02d9445e5991a6c30a5d3 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 00:05:46 +0800
Subject: [PATCH 040/262] fix(runtime): close remote cleanup and readiness
 races

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |   4 +-
 ...8-portable-execution-world-consumers.zh.md |   4 +-
 packages/pty/pty-local/README.i18n.yaml       |   4 +-
 packages/pty/pty-local/README.md              |   2 +-
 packages/pty/pty-local/README.zh.md           |   2 +-
 packages/pty/pty-local/src/session.ts         |  48 ++++++--
 packages/pty/pty-local/tests/session.spec.ts  | 112 ++++++++++++++++++
 packages/typert/README.i18n.yaml              |   6 +-
 9 files changed, 166 insertions(+), 20 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 8b4288edb4..0eb1611fe1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 000fa1b98964eb85550d0c607281937f8d7932c6
-2026-07-28-portable-execution-world-consumers.zh.md: 94e6bfcf94e450fafea2b33e152384da400e4b63
+2026-07-28-portable-execution-world-consumers.md: 5a15c2c0a4e552fadbdad9f7d09e00229afb033b
+2026-07-28-portable-execution-world-consumers.zh.md: 5ae7f3b96f4df4c3756d294ba12147a3b1b54d34
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 000fa1b989..5a15c2c0a4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,8 +22,8 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. A timed-out asynchronous write retains the send reservation until the provider settles it, and completion of a stale inspection resumes polling for the current send.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher reaps its controller before group termination becomes the fallback.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 94e6bfcf94..5ae7f3b96f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,8 +22,8 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。异步写入超时后仍保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会先回收 controller，进程组终止才会成为后备手段。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index d8f5c2e2d0..828e767a60 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 8a0a60139e27d98c4f506245a204723da997cd4a
-README.zh.md: 3df845931dac33abecbcd5030a1b204c68acc638
+README.md: 235599737d21289d291ccab8f06fbcca91c83223
+README.zh.md: ca01c9a10430644b0d6ea6c5cfa70472f0447b92
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 8a0a60139e..235599737d 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then reg
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 3df845931d..ca01c9a104 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index a6abaf7785..5ac4dbca73 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -94,6 +94,10 @@ class LocalSendOperation implements PtySendOperation {
     return this.promise.promise
   }
 
+  get settled(): boolean {
+    return this.finished
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -155,6 +159,8 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private writing: LocalSendOperation | undefined
+  private pollingReady: LocalSendOperation | undefined
   private polling = false
   private promptSeen = false
   private promptTextSeen = false
@@ -224,7 +230,7 @@ export class LocalPtySession implements PtyBackendSession {
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
     this.activeDeadlineTimer = setTimeout(() => {
-      if (this.active === operation) this.settleActive('timeout')
+      if (this.active === operation) this.settleActive('timeout', this.writing === operation)
     }, this.config.timeoutMs)
     void this.beginSend(operation, request)
     return operation
@@ -236,12 +242,29 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.active !== operation || this.closing) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
-      if (input.length > 0) await this.terminal.write(Buffer.from(input, 'utf8'))
+      if (input.length > 0) {
+        this.writing = operation
+        try {
+          await this.terminal.write(Buffer.from(input, 'utf8'))
+        } finally {
+          this.writing = undefined
+        }
+      }
+      if (this.active === operation && operation.settled) {
+        this.clearActive()
+        return
+      }
       // Closing can race the awaited provider write even though static analysis sees only local assignments.
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (this.active === operation && !this.closing) this.schedulePoll(operation, 0)
+      if (this.active === operation && !this.closing) {
+        this.pollingReady = operation
+        this.schedulePoll(operation, 0)
+      }
     } catch (error: unknown) {
-      if (this.active === operation) this.failActive(error)
+      if (this.active === operation) {
+        if (operation.settled) this.clearActive()
+        else this.failActive(error)
+      }
     }
   }
 
@@ -401,15 +424,24 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.active === operation) this.failActive(error)
     } finally {
       this.polling = false
-      if (this.active === operation) this.schedulePoll(operation)
+      const active = this.active
+      // Awaited provider inspection can clear or replace the active send despite static analysis.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
     }
   }
 
-  private settleActive(waitReason: PtyWaitReason): void {
+  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
@@ -424,6 +456,8 @@ export class LocalPtySession implements PtyBackendSession {
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    this.writing = undefined
+    this.pollingReady = undefined
     this.active = undefined
   }
 
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 7a775eb9a0..7e6b9407a0 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -268,6 +268,40 @@ describe('LocalPtySession readiness and output', () => {
     failedInternal.fail(new Error('ignored'))
   })
 
+  it('retains send ownership after timeout until an asynchronous provider write settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'slow write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(100)
+
+    expect((await operation.done).waitReason).toBe('timeout')
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+
+    writeGate.resolve(undefined)
+    await Promise.resolve()
+    await Promise.resolve()
+    const rejectedWrite = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await rejectedWrite.promise }
+    const rejected = session.startSend({ text: 'late rejection', submit: true })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await rejected.done).waitReason).toBe('timeout')
+    rejectedWrite.reject(new Error('write failed after timeout'))
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
     vi.useFakeTimers()
     const startupTerminal = new FakeTerminal()
@@ -509,6 +543,84 @@ describe('LocalPtySession readiness and output', () => {
     }).settle('timeout', { kind: 'running' }, false)
   })
 
+  it('reschedules readiness for a new send after a stale remote inspection releases the poll slot', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const old = session.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    let block = true
+    terminal.inspectForeground = async () => block
+      ? await inspection.promise
+      : { processGroupId: 456, inputWaiting: false }
+    const internals = session as unknown as {
+      pollReadiness(operation: PtySendOperation): Promise<void>
+      settleActive(reason: 'timeout'): void
+    }
+    const stalePoll = internals.pollReadiness(old)
+    internals.settleActive('timeout')
+    await old.done
+
+    block = false
+    const current = session.startSend({ text: '', submit: false })
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await Promise.resolve()
+    await Promise.resolve()
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await stalePoll
+    await vi.advanceTimersByTimeAsync(10)
+
+    expect((await current.done).waitReason).toBe('stdin_read')
+  })
+
+  it('does not poll a successor before its own pre-write inspection and write complete', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const old = session.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const staleInspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    const successorInspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    let inspectCalls = 0
+    terminal.inspectForeground = async () => {
+      inspectCalls += 1
+      return inspectCalls === 1 ? await staleInspection.promise : await successorInspection.promise
+    }
+    const internals = session as unknown as {
+      pollReadiness(operation: PtySendOperation): Promise<void>
+      settleActive(reason: 'timeout'): void
+    }
+    const stalePoll = internals.pollReadiness(old)
+    internals.settleActive('timeout')
+    await old.done
+
+    const current = session.startSend({ text: 'successor', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    staleInspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await stalePoll
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspectCalls).toBe(2)
+    expect(terminal.writes).toEqual([])
+
+    successorInspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(terminal.writes).toEqual(['successor\r'])
+    expect((await current.done).waitReason).toBe('stdin_read')
+  })
+
   it('contains stale timer, write, inspection, and interrupt continuations', async () => {
     vi.useFakeTimers()
     const settle = (operation: PtySendOperation): void => {
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index cf44d9aace..d075078b94 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/README.i18n.yaml
@@ -1,6 +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/typert/README.md
-README.md: ad9f843e48be0e3be85921ed8fd3ca4e2c327160
-README.zh.md: 0d4be016b766178b54f7e269583fa4200e3eb24b
+#   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-subprocess/README.md
+README.md: 9e0ea9065ea4e42696f6afcd243c385e514f7c2d
+README.zh.md: 6946248ec58054fcdd93a4c94affb55f90041301

From ac81165662eeee7fb9b4f77be358e78c8b0c6263 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 01:18:01 +0800
Subject: [PATCH 041/262] fix(runtime): close async cleanup and framing races

---
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 +-
 .../feature/2026-06-15-code-mode.md           |  4 +-
 .../feature/2026-06-15-code-mode.zh.md        |  4 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  6 +--
 .../2026-07-16-persistent-pty-sessions.zh.md  |  6 +--
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  4 +-
 packages/pty/pty-local/README.zh.md           |  4 +-
 packages/pty/pty-local/src/index.ts           |  3 +-
 packages/pty/pty-local/src/sanitize.ts        | 37 +++++++++-------
 packages/pty/pty-local/src/session.ts         | 22 +++++++---
 packages/pty/pty-local/tests/sanitize.spec.ts |  6 +--
 packages/pty/pty-local/tests/session.spec.ts  | 44 +++++++++++++++++++
 packages/typert/README.i18n.yaml              |  4 +-
 15 files changed, 109 insertions(+), 47 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index a878942993..42a11b8fb8 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 7e51b9fa726afe4c34b87457b562b4092ee6c93c
-2026-06-15-code-mode.zh.md: 4ba098d87d8c944e88c4cbe11ff78ac4383d3ac5
+2026-06-15-code-mode.md: b0778b2c9a8dfce8f786faccf6cc47f477c6b7c0
+2026-06-15-code-mode.zh.md: 437692eac3fc6740e0f1d4dd9001130fd6dd448a
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 7e51b9fa72..b0778b2c9a 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -79,7 +79,7 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
 
 ### Trust posture
 
@@ -95,7 +95,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
+- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 4ba098d87d..437692eac3 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -79,7 +79,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
+`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
@@ -95,7 +95,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 测试
 
-- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
+- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 6a801df865..8b33466ea7 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 65d265b83ab5ad89c2b919364043eb28e75977c7
-2026-07-16-persistent-pty-sessions.zh.md: 6ea92da9a1b2870f3773d84e7f5629bec220dd1c
+2026-07-16-persistent-pty-sessions.md: ef87c2806a237e6e6d44c1e62942146af24b8c19
+2026-07-16-persistent-pty-sessions.zh.md: 5f1bde39de5eca7aa57897d87c95675ce0da5abd
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 65d265b83a..ef87c2806a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -60,7 +60,7 @@ The local subprocess terminal primitive uses only public `node-pty` capabilities
 
 The UI render contract is exact and location-free. `terminal_send` uses terminal call/result cards only for foreground sends; its background form is generic `execute`. `terminal_open`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list` use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. No PTY tool emits `locations`.
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
+`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. Cancellation marks queued input before signaling the real foreground group, so input cannot execute if an asynchronous pre-write inspection settles afterward. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
 
 Foreground sends return a bounded rendered delta and two independent facts: `waitReason` (`stdin_read | inferred_idle | timeout | session_exit`) and `sessionStatus` (`running` or `exited` with exit code or signal). `session_exit` refers to the PTY's top-level shell process, not an arbitrary foreground command whose status the shell consumes. A timeout never implies process exit. `dsh-tool-pty.maxResultBytes` defaults to 262144, rejects values below 64 so creation acknowledgements retain registry-issued ids, and caps each single-text UTF-8 result after normalized tool or pipeline errors, wait, session, pagination, truncation, generic task-status wrappers, policy denials or short-circuits, and post-execute replacements or blocks; the terminal definitions' last-mile `finalizeContent` callback leaves deliberately structured multi-block policy content unchanged. The renderer reserves suffix space and preserves code-point boundaries instead of treating the backend payload cap as the final model bound.
 
@@ -72,7 +72,7 @@ With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `
 
 ### Local readiness detection
 
-The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then requires printable prompt text after that marker before declaring prompt readiness and runs three bounded fallback tiers. Carrying that state across data callbacks covers macOS delivery where the OSC marker and `PS1` arrive separately; the marker alone can no longer publish an empty MOTD. The marker is removed before output reaches the model and avoids a fixed silence delay for ordinary shell commands on both platforms. Unpublished startup does not accept zero-output silence as readiness; timeout rejects the spawn. If caller cancellation wins during startup, the backend closes the private session and propagates the exact `AbortSignal.reason`; a foreground PGID that is not observable yet cannot replace cancellation with a lookup error. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, and `timeoutMs`.
+The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then requires the printable tail after the latest marker to exactly equal the controlled `PS1` before declaring prompt readiness and runs three bounded fallback tiers. Carrying that tail across data callbacks covers delivery where the marker and prompt arrive separately; requiring the exact tail rejects a delayed earlier prompt once echoed input or output follows it, so it cannot settle the current send. The marker is removed before output reaches the model and avoids a fixed silence delay for ordinary shell commands on both platforms. Unpublished startup does not accept zero-output silence as readiness; timeout rejects the spawn. If caller cancellation wins during startup, the backend closes the private session and propagates the exact `AbortSignal.reason`; a foreground PGID that is not observable yet cannot replace cancellation with a lookup error. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, and `timeoutMs`.
 
 On Linux, the inspector reads the shell's terminal foreground PGID from `/proc/<shellPid>/stat`, enumerates every process and thread in that process group, and probes their current syscalls. A positive Tier 1 result requires an observed stdin wait: direct `read(0)`, a permitted read of a `select`/`pselect6` or `poll`/`ppoll` argument containing fd 0, or an epoll interest list containing fd 0. A wait already present before terminal input is not post-write readiness: the same PGID must be observed outside that wait before re-entering it, while a changed foreground PGID is new evidence. Unreadable process memory and unrecognized syscalls are misses, never positive guesses. Architecture tables contain only syscall numbers defined by the corresponding Linux UAPI; unsupported architectures skip Tier 1.
 
@@ -156,7 +156,7 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 ## Verification
 
-- Per-file coverage pins owner fencing, concurrent reservations, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents.
+- Per-file coverage pins owner fencing, concurrent reservations, cancellation during pre-write inspection, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits and delayed earlier prompts, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents.
 - Subprocess process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
 - Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 6ea92da9a1..5f1bde39de 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -60,7 +60,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 
 UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
+`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
 前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。`dsh-tool-pty.maxResultBytes` 默认为 262144；低于 64 的值会被拒绝，以确保创建确认保留 registry 签发的 id；每个单文本 UTF-8 结果在加入规范化的工具或流水线错误、等待、会话、分页、截断、通用 task 状态包装、策略拒绝或短路以及 post-execute 替换或阻断后，仍受该值限制；终端定义自有的末端 `finalizeContent` callback 会原样保留策略刻意返回的结构化多 block 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
@@ -72,7 +72,7 @@ UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发
 
 ### 本地就绪检测
 
-本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，并且只有在该 marker 后出现可打印的 prompt 文本时才据此声明 prompt 就绪；除此之外，它还运行 3 个有界 fallback 层级。在 data callback 之间保留这项状态，可以适配 macOS 分开交付 OSC marker 与 `PS1` 的情况；单独的 marker 不会发布空 MOTD。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。若调用方取消在 startup 期间胜出，后端会关闭私有会话并原样抛出 `AbortSignal.reason`；尚不可观察的前台 PGID 不会再用查找错误覆盖取消原因。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs` 和 `timeoutMs`。
+本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，并且只有在最近一个 marker 后的可打印尾部与受控 `PS1` 完全相等时才声明 prompt 就绪；除此之外，它还运行 3 个有界 fallback 层级。在 data callback 之间保留该尾部，可以适配 marker 与 prompt 被分开交付的情况；如果回显的输入或输出跟在延迟到达的先前 prompt 之后，要求尾部完全相等会拒绝该 prompt，使其无法完成当前 send。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。若调用方取消在 startup 期间胜出，后端会关闭私有会话并原样抛出 `AbortSignal.reason`；尚不可观察的前台 PGID 不会再用查找错误覆盖取消原因。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs` 和 `timeoutMs`。
 
 在 Linux 上，检查器从 `/proc/<shellPid>/stat` 读取 shell 的终端前台 PGID，枚举该进程组中的每个进程与线程，并检查它们当前的 syscall。Tier 1 只有观察到 stdin 等待才返回正结果：直接 `read(0)`、获准读取且含 fd 0 的 `select`/`pselect6` 或 `poll`/`ppoll` 参数，或者含 fd 0 的 epoll interest list。终端输入前就已存在的等待并不代表写入后就绪：必须先观察到同一 PGID 脱离该等待，之后再次进入等待才能使该次 send 完成；前台 PGID 发生变化则构成新的证据。无法读取的进程内存和未识别的 syscall 都是 miss，绝不作为正向猜测。架构表只包含对应 Linux UAPI 定义的 syscall number；不支持的架构跳过 Tier 1。
 
@@ -156,7 +156,7 @@ plugins:
 
 ## 验证
 
-- 每文件覆盖率固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
+- 每文件覆盖率固定 owner 隔离、并发预留、写入前检查期间的取消、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待与延迟到达的先前 prompt 的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
 - 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 828e767a60..e29a581f57 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 235599737d21289d291ccab8f06fbcca91c83223
-README.zh.md: ca01c9a10430644b0d6ea6c5cfa70472f0447b92
+README.md: 2c4ee44e8489cc6b53179769301e125dcca0ac8e
+README.zh.md: 947bab00b9d6aa5fb7b321fbee84f4b2e420133c
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 235599737d..2c4ee44e84 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,9 +8,9 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index ca01c9a104..947bab00b9 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,9 +8,9 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 0a54a0b804..a8d99cb243 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -14,6 +14,7 @@ import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
 import { LocalPtySession } from './session.ts'
+import { CONTROLLED_PROMPT } from './sanitize.ts'
 
 export { Config } from './config.ts'
 export type { Config as PtyLocalConfig } from './config.ts'
@@ -58,7 +59,7 @@ function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
-    PS1: 'dsh> ',
+    PS1: CONTROLLED_PROMPT,
     PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
     BASH_SILENCE_DEPRECATION_WARNING: '1',
     DSH_SHELL: '1',
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
index cc22c29c01..1f28315fb1 100644
--- a/packages/pty/pty-local/src/sanitize.ts
+++ b/packages/pty/pty-local/src/sanitize.ts
@@ -5,12 +5,15 @@ import { Buffer } from 'node:buffer'
 /** OSC marker emitted by the controlled bash before each prompt. */
 export const PROMPT_MARKER_PREFIX = '133;D;'
 
+/** Exact printable prompt emitted after the private marker. */
+export const CONTROLLED_PROMPT = 'dsh> '
+
 /** One sanitized chunk plus whether it contained the owned prompt marker. */
 export interface SanitizedChunk {
   text: string
   prompt: boolean
-  /** Present when printable text followed the latest owned prompt marker. */
-  promptText?: true
+  /** Printable text after the latest owned marker in this chunk. */
+  promptTail?: string
 }
 
 /**
@@ -23,7 +26,7 @@ export class TerminalSanitizer {
   private discardMode: 'osc' | 'csi' | undefined
   private discardOscEscape = false
   private trailingCarriageReturn = false
-  private awaitingPromptText = false
+  private trackingPromptTail = false
 
   constructor(private readonly maxPendingBytes: number) {}
 
@@ -36,24 +39,21 @@ export class TerminalSanitizer {
     this.pending += this.discardPrefix(chunk)
     let text = ''
     let prompt = false
-    let promptText = false
+    let includePromptTail = this.trackingPromptTail
+    let promptTail = ''
     let index = 0
-    const appendText = (value: string): boolean => {
+    const appendText = (value: string): void => {
       text += value
-      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
-        this.awaitingPromptText = false
-        return true
-      }
-      return false
+      if (this.trackingPromptTail) promptTail += value
     }
     while (index < this.pending.length) {
       const escape = this.pending.indexOf('\x1b', index)
       if (escape < 0) {
-        promptText = appendText(this.pending.slice(index)) || promptText
+        appendText(this.pending.slice(index))
         index = this.pending.length
         break
       }
-      promptText = appendText(this.pending.slice(index, escape)) || promptText
+      appendText(this.pending.slice(index, escape))
       if (escape + 1 >= this.pending.length) {
         index = escape
         break
@@ -74,8 +74,9 @@ export class TerminalSanitizer {
         const content = this.pending.slice(escape + 2, end - terminatorBytes)
         if (content.startsWith(PROMPT_MARKER_PREFIX)) {
           prompt = true
-          promptText = false
-          this.awaitingPromptText = true
+          this.trackingPromptTail = true
+          includePromptTail = true
+          promptTail = ''
         }
         index = end
         continue
@@ -99,7 +100,11 @@ export class TerminalSanitizer {
     }
     this.pending = this.pending.slice(index)
     this.enforcePendingBound()
-    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
+    return {
+      text: this.normalizeText(text),
+      prompt,
+      ...includePromptTail ? { promptTail } : {},
+    }
   }
 
   /**
@@ -111,7 +116,7 @@ export class TerminalSanitizer {
     this.pending = ''
     this.discardMode = undefined
     this.discardOscEscape = false
-    this.awaitingPromptText = false
+    this.trackingPromptTail = false
     const normalized = this.normalizeText(text)
     if (!this.trailingCarriageReturn) return normalized
     this.trailingCarriageReturn = false
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 5ac4dbca73..f984648f27 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -20,7 +20,7 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import { TerminalSanitizer } from './sanitize.ts'
+import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
 
 function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
   if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
@@ -77,6 +77,7 @@ class LocalSendOperation implements PtySendOperation {
   private readonly output: BoundedTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
+  private cancellationRequested = false
   private initialForegroundLeftWait: boolean
   private initialForegroundPgid: number | undefined
 
@@ -98,6 +99,10 @@ class LocalSendOperation implements PtySendOperation {
     return this.finished
   }
 
+  get cancelRequested(): boolean {
+    return this.cancellationRequested
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -140,6 +145,7 @@ class LocalSendOperation implements PtySendOperation {
 
   cancel(): boolean {
     if (this.finished) return false
+    this.cancellationRequested = true
     this.onCancel()
     return true
   }
@@ -164,6 +170,7 @@ export class LocalPtySession implements PtyBackendSession {
   private polling = false
   private promptSeen = false
   private promptTextSeen = false
+  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -223,6 +230,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.lastOutputAt = Date.now()
     this.promptSeen = false
     this.promptTextSeen = false
+    this.promptTail = ''
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
@@ -242,7 +250,7 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.active !== operation || this.closing) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
-      if (input.length > 0) {
+      if (input.length > 0 && !operation.cancelRequested) {
         this.writing = operation
         try {
           await this.terminal.write(Buffer.from(input, 'utf8'))
@@ -347,10 +355,14 @@ export class LocalPtySession implements PtyBackendSession {
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
+      this.promptTail = ''
       this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
+    }
+    if (this.promptSeen && sanitized.promptTail !== undefined) {
+      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
+      this.promptTail += sanitized.promptTail.slice(0, remaining)
+      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
+      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
     }
   }
 
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index 4da4ab0d73..f6649b3c6f 100644
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -7,7 +7,7 @@ describe('TerminalSanitizer', () => {
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
@@ -35,8 +35,8 @@ describe('TerminalSanitizer', () => {
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
     const sanitizer = new TerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 7e6b9407a0..6346a6bba2 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -268,6 +268,29 @@ describe('LocalPtySession readiness and output', () => {
     failedInternal.fail(new Error('ignored'))
   })
 
+  it('does not write a send canceled during asynchronous foreground inspection', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'must not execute', submit: true, signal: controller.signal })
+    controller.abort()
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(terminal.writes).toEqual([])
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+  })
+
   it('retains send ownership after timeout until an asynchronous provider write settles', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -418,6 +441,27 @@ describe('LocalPtySession readiness and output', () => {
     expect(session.motd).toBe('dsh> ')
   })
 
+  it('does not attribute a delayed prior prompt to the current send', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 100, timeoutMs: 200 }))
+    await initialize(session, terminal)
+
+    const operation = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
+    let settled = false
+    void operation.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    terminal.emitData('\x1b]133;D;0\x07dsh> printf \'PID=%s\\n\' "$!"\r\n')
+    await vi.advanceTimersByTimeAsync(20)
+    expect(settled).toBe(false)
+
+    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
+  })
+
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index d075078b94..d1678caf7e 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: 9e0ea9065ea4e42696f6afcd243c385e514f7c2d
-README.zh.md: 6946248ec58054fcdd93a4c94affb55f90041301
+README.md: 620728744fb2a63a730ee06ef3eb5c36505ae572
+README.zh.md: d3201d2e49e9dc89a9d274ca1075f450ad13c683

From e5f3a6736357c33d3d889ebda316646a409b3eb8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 01:15:35 +0800
Subject: [PATCH 042/262] fix(runtime): publish completion before pipe cleanup

---
 .../2026-07-28-portable-execution-world-consumers.i18n.yaml   | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.md          | 2 +-
 .../2026-07-28-portable-execution-world-consumers.zh.md       | 2 +-
 packages/typert/README.i18n.yaml                              | 4 ++--
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 0eb1611fe1..f72f7c1d89 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 5a15c2c0a4e552fadbdad9f7d09e00229afb033b
-2026-07-28-portable-execution-world-consumers.zh.md: 5ae7f3b96f4df4c3756d294ba12147a3b1b54d34
+2026-07-28-portable-execution-world-consumers.md: 145b23317552a51f608404a3308011fb8540319f
+2026-07-28-portable-execution-world-consumers.zh.md: 50e27ccce19516a02e4e5024efb8303231a2236e
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 5a15c2c0a4..145b233175 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -23,7 +23,7 @@ Generic consumers use that execution world:
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. A timed-out asynchronous write retains the send reservation until the provider settles it, and completion of a stale inspection resumes polling for the current send.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher reaps its controller before group termination becomes the fallback.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 5ae7f3b96f..50e27ccce1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。异步写入超时后仍保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会先回收 controller，进程组终止才会成为后备手段。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index d1678caf7e..384c9cdb94 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: 620728744fb2a63a730ee06ef3eb5c36505ae572
-README.zh.md: d3201d2e49e9dc89a9d274ca1075f450ad13c683
+README.md: db4478fe799dce1bbdb7e3ae3d31947515aae151
+README.zh.md: 238f5f66db58edb99945cfa43299635b4f8f36a8

From c17727d43dcb118158bc28bfec6cebe60097fae3 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 01:15:50 +0800
Subject: [PATCH 043/262] test(subprocess): cover terminal release cleanup

---
 .../subprocess-local/tests/local.spec.ts      | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index bc77d24cfd..7ff10a7348 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -105,6 +105,53 @@ describe('LocalSubprocessService', () => {
     expect(waitForExit).toHaveBeenCalledOnce()
   })
 
+  it('releases a terminal after top-level exit reaches quiescence', async () => {
+    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
+    const inspector = {
+      foregroundPgid: () => undefined,
+      isStdinWaiting: () => false,
+      processTree: () => [],
+      isAlive: () => false,
+      signalGroup: () => {},
+      signalProcess: () => {},
+    }
+    const terminal = {
+      pid: 123,
+      onData: () => ({ dispose: () => {} }),
+      onExit: (listener: (event: { exitCode: number; signal?: number }) => void) => {
+        exitListener = listener
+        return { dispose: () => {} }
+      },
+      write: () => {},
+      kill: () => {},
+    }
+    vi.resetModules()
+    vi.doMock('node-pty', () => ({ spawn: () => terminal }))
+    vi.doMock('../src/process-inspector.ts', async importOriginal => ({
+      ...await importOriginal<typeof import('../src/process-inspector.ts')>(),
+      createProcessInspector: () => inspector,
+    }))
+    try {
+      const { default: IsolatedLocalSubprocessService } = await import('../src/index.ts')
+      const ctx = new Context()
+      const fiber = await ctx.plugin(IsolatedLocalSubprocessService)
+      const service = ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>
+      const handle = await ctx.subprocess.spawnTerminal({
+        argv: ['shell'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 1,
+      })
+      expect((service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.size).toBe(1)
+      exitListener?.({ exitCode: 0 })
+      await handle.done
+      await new Promise(resolve => setImmediate(resolve))
+      expect((service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.size).toBe(0)
+      await fiber.dispose()
+    } finally {
+      vi.doUnmock('node-pty')
+      vi.doUnmock('../src/process-inspector.ts')
+      vi.resetModules()
+    }
+  })
+
   it('contains a terminal release failure after top-level exit', async () => {
     let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
     const terminal = {

From 32bce339da84917b696f1387d8e7e8417c73c27d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 02:40:02 +0800
Subject: [PATCH 044/262] fix(runtime): close lifecycle teardown races

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  6 +--
 ...8-portable-execution-world-consumers.zh.md |  6 +--
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  4 +-
 packages/pty/pty-local/README.zh.md           |  4 +-
 packages/pty/pty-local/src/index.ts           | 33 ++++++++++----
 packages/pty/pty-local/src/session.ts         | 12 +++--
 packages/pty/pty-local/tests/index.spec.ts    | 45 +++++++++++++++++++
 packages/pty/pty-local/tests/local.spec.ts    | 43 +++++++++++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 27 +++++++++++
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  4 +-
 .../subprocess/subprocess-local/README.zh.md  |  4 +-
 .../subprocess-local/src/process-inspector.ts | 14 ++++++
 .../subprocess-local/src/terminal.ts          |  9 +++-
 .../subprocess-local/tests/local.spec.ts      |  2 +
 .../tests/process-inspector.spec.ts           |  8 ++++
 .../subprocess-local/tests/terminal.spec.ts   | 32 +++++++++++++
 packages/typert/README.i18n.yaml              |  4 +-
 20 files changed, 233 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index f72f7c1d89..f97b09b940 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 145b23317552a51f608404a3308011fb8540319f
-2026-07-28-portable-execution-world-consumers.zh.md: 50e27ccce19516a02e4e5024efb8303231a2236e
+2026-07-28-portable-execution-world-consumers.md: 3d1928be882fb3fb621e733649146445c69e8a5b
+2026-07-28-portable-execution-world-consumers.zh.md: f385e502d5d737fe0d5ae6e28ac7a3a097d85a6b
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 145b233175..3d1928be88 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,8 +22,8 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. A timed-out asynchronous write retains the send reservation until the provider settles it, and completion of a stale inspection resumes polling for the current send.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -45,4 +45,4 @@ A remote execution provider implements only its shared sandbox owner plus filesy
 
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
-The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal still waits for exact PID-identity-fenced descendants and the top-level terminal process to reach quiescence.
+The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal waits for exact PID-identity-fenced descendants retained during foreground inspection, Linux session members that survive top-level exit, and the top-level terminal process to reach quiescence. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 50e27ccce1..f385e502d5 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,8 +22,8 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。异步写入超时后仍保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -45,4 +45,4 @@ Status: implemented
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
-本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）仍会等待受精确 PID 身份校验保护的后代进程和顶层终端进程完全停稳。
+本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程、在顶层进程退出后仍存活的 Linux 会话成员，以及顶层终端进程完全停稳。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index e29a581f57..05e9b904f9 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 2c4ee44e8489cc6b53179769301e125dcca0ac8e
-README.zh.md: 947bab00b9d6aa5fb7b321fbee84f4b2e420133c
+README.md: 7d0cd2c26c6c58a64ae9d5fe5598c8aa6ff62915
+README.zh.md: 0b8216a9f599c224bd2888eb428213c9d725a338
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 2c4ee44e84..7d0cd2c26c 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,9 +8,9 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the session's send slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 947bab00b9..0b8216a9f5 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,9 +8,9 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index a8d99cb243..62b5fdb71a 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -101,15 +101,30 @@ export class LocalPtyBackend implements PtyBackend {
     ensureSandboxModeFence(this.ctx, spec.owner)
     const argv = spawnArgv(this.ctx, this.config, spec)
     if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    const terminal = await this.spawnTerminal({
-      argv,
-      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
-      env: childEnvironment(spec),
-      rows: this.config.rows,
-      cols: this.config.cols,
-      graceMs: this.config.disposeGraceMs,
-      signal: spec.signal,
-    })
+    let terminalSignal: AbortSignal | undefined
+    let detachSetupSignal: (() => void) | undefined
+    if (spec.signal !== undefined) {
+      const source = spec.signal
+      const controller = new AbortController()
+      const onAbort = (): void => { controller.abort(source.reason) }
+      source.addEventListener('abort', onAbort, { once: true })
+      detachSetupSignal = () => { source.removeEventListener('abort', onAbort) }
+      terminalSignal = controller.signal
+    }
+    let terminal: SubprocessTerminalHandle
+    try {
+      terminal = await this.spawnTerminal({
+        argv,
+        cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+        env: childEnvironment(spec),
+        rows: this.config.rows,
+        cols: this.config.cols,
+        graceMs: this.config.disposeGraceMs,
+        signal: terminalSignal,
+      })
+    } finally {
+      detachSetupSignal?.()
+    }
     const session = this.createSession(terminal, this.config)
     try {
       await session.initialize(spec.signal)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index f984648f27..9a0beed6ff 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -473,17 +473,23 @@ export class LocalPtySession implements PtyBackendSession {
     this.active = undefined
   }
 
-  private failActive(error: unknown): void {
+  private failActive(error: unknown, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.fail(error)
   }
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
     void this.terminal.signalForeground('SIGINT').catch((error: unknown) => {
-      if (this.active === operation) this.failActive(error)
+      if (this.active === operation) this.failActive(error, this.writing === operation)
     })
   }
 
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index a8753deaf3..23e6f4bc89 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -187,6 +187,51 @@ describe('LocalPtyBackend startup rollback', () => {
     expect(initialized).toHaveBeenCalledWith(undefined)
   })
 
+  it('forwards setup cancellation only while terminal allocation is unpublished', async () => {
+    const ctx = new Context()
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const publishedController = new AbortController()
+    let publishedSignal: AbortSignal | undefined
+    const published = new LocalPtyBackend(
+      ctx,
+      config(),
+      async (spawnSpec) => {
+        publishedSignal = spawnSpec.signal
+        return terminalHandle()
+      },
+      () => stubLocalSession(),
+    )
+    await published.spawn(spec(agent(ctx), publishedController.signal))
+    expect(publishedSignal).toBeDefined()
+    expect(publishedSignal).not.toBe(publishedController.signal)
+    publishedController.abort(new Error('originating turn ended'))
+    expect(publishedSignal?.aborted).toBe(false)
+
+    const pendingController = new AbortController()
+    const seen = Promise.withResolvers<AbortSignal>()
+    const pending = new LocalPtyBackend(
+      ctx,
+      config(),
+      async spawnSpec => await new Promise<SubprocessTerminalHandle>((_resolve, reject) => {
+        const setupSignal = spawnSpec.signal as AbortSignal
+        seen.resolve(setupSignal)
+        const onAbort = (): void => {
+          reject(setupSignal.reason instanceof Error ? setupSignal.reason : new Error(String(setupSignal.reason)))
+        }
+        setupSignal.addEventListener('abort', onAbort, { once: true })
+      }),
+      () => stubLocalSession(),
+    )
+    const spawning = pending.spawn(spec(agent(ctx), pendingController.signal))
+    const pendingSignal = await seen.promise
+    const reason = new Error('cancel pending allocation')
+    pendingController.abort(reason)
+    await expect(spawning).rejects.toBe(reason)
+    expect(pendingSignal.aborted).toBe(true)
+  })
+
   it('composes the default local session around a spawned terminal', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index c02a9563ea..df05438864 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -1,4 +1,4 @@
-import { mkdtempSync, realpathSync, rmSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -156,6 +156,47 @@ describe('pty-local real shell', () => {
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
 
+  it('reaps a disowned same-session descendant after the shell exits naturally', async () => {
+    const { ctx, root, agent } = await harness('danger-full-access')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+    const pidFile = join(root, 'disowned.pid')
+    let pid: number | undefined
+    try {
+      const background = ctx.pty.startSend(agent, created.sessionId, {
+        text: `sh -c 'trap "" TERM; printf "%s" "$$" > "$1"; sleep 60' dsh "${pidFile}" & disown`,
+        submit: true,
+      })
+      await background.done
+      const pidDeadline = Date.now() + 2_000
+      let childPid = 0
+      while (childPid === 0 && Date.now() < pidDeadline) {
+        if (existsSync(pidFile)) childPid = Number(readFileSync(pidFile, 'utf8'))
+        if (childPid > 0) break
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(existsSync(pidFile), ctx.pty.read(agent, created.sessionId, { offset: 0, count: 100 }).text).toBe(true)
+      expect(childPid).toBeGreaterThan(0)
+      pid = childPid
+      expect(() => process.kill(childPid, 0)).not.toThrow()
+      await ctx.pty.startSend(agent, created.sessionId, { text: 'exit', submit: true }).done
+      const deadline = Date.now() + 2_000
+      while (ctx.pty.list(agent)[0]?.status.kind !== 'exited' && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(ctx.pty.list(agent)[0]?.status.kind).toBe('exited')
+      await ctx.pty.kill(agent, created.sessionId)
+      expect(() => process.kill(childPid, 0)).toThrow()
+    } finally {
+      if (pid !== undefined) {
+        try {
+          process.kill(pid, 'SIGKILL')
+        } catch (_alreadyReaped) {
+          // Product cleanup is the expected path; this only contains a failed regression.
+        }
+      }
+    }
+  }, 10_000)
+
   it('cancels a slow-starting raw-mode foreground process with a real SIGINT', async () => {
     const { ctx, agent } = await harness('danger-full-access', {
       idleSilenceMs: 10_000,
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 6346a6bba2..120b2881e1 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -27,6 +27,7 @@ class FakeInspector implements ProcessInspector {
   foregroundPgid() { return this.pgid }
   isStdinWaiting() { return this.waiting }
   processTree() { return this.members }
+  processSession() { return [] }
   isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
   signalGroup(pgid: number, signal: PtySignal) {
     if (this.throwGroup) throw new Error('group failed')
@@ -325,6 +326,32 @@ describe('LocalPtySession readiness and output', () => {
     expect((await next.done).waitReason).toBe('inferred_idle')
   })
 
+  it('retains send ownership when cancellation signalling fails during an asynchronous write', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    terminal.signalForeground = async () => { throw new Error('interrupt failed') }
+    const operation = session.startSend({ text: 'slow write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    const rejected = expect(operation.done).rejects.toThrow('interrupt failed')
+    expect(operation.cancel()).toBe(true)
+    await rejected
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+
+    writeGate.resolve(undefined)
+    await Promise.resolve()
+    await Promise.resolve()
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
     vi.useFakeTimers()
     const startupTerminal = new FakeTerminal()
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index d931d3574b..72f3c93da9 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 6bc1003ae5903bb5640728bc79c3f9042fddbe7a
-README.zh.md: 3c9ce73c7fcbeec9b17d73f212ecdcb6842ec133
+README.md: 38b26c33f3854acdb4a2bb48612da73361d727ba
+README.zh.md: fc4a5d4961fb7618b9db84b21063f907361a26d8
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 6bc1003ae5..38b26c33f3 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -11,7 +11,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Linux `/proc`/syscall and macOS `ps` inspectors retain exact pid/start identity so pid reuse cannot redirect cleanup; the higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
@@ -26,7 +26,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 - **Windows tree support is best-effort and untested in CI** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary; the suites cover the routing through an injected runner only, and `packages/subprocess/*` is excluded from the Windows test matrix.
 - **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
-- **A daemonized terminal descendant can escape the captured tree** — a child that reparents before teardown is no longer discoverable from the `node-pty` root. The local provider accepts this gap rather than signal the root PID's POSIX session, which can include unrelated launcher processes.
+- **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the `node-pty` root; on Linux, a child that calls `setsid` leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
 - **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 3c9ce73c7f..fc4a5d4961 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，在资源释放时删除；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。Linux 的 `/proc`／syscall 检查器与 macOS 的 `ps` 检查器会保留精确的 pid／启动身份，使 PID 复用无法把清理重定向到其他进程；上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
@@ -26,7 +26,7 @@
 
 - **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
 - **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 使用 `ps` 快照。
-- **守护化的终端后代可能逃离已捕获进程树**：子进程若在拆卸前重新设定父进程，便无法再从 `node-pty` 根发现。本地提供方接受这个缺口，不向根 PID 的 POSIX 会话发送信号，因为其中可能包含无关的启动器进程。
+- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程若在任何前台检查快照产生前重新设定父进程，便无法再从 `node-pty` 根发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与该提供方拥有的终端会话。本地提供方不会增加持续运行的进程表监视器。
 - **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
diff --git a/packages/subprocess/subprocess-local/src/process-inspector.ts b/packages/subprocess/subprocess-local/src/process-inspector.ts
index f57184f289..48b01e18e3 100644
--- a/packages/subprocess/subprocess-local/src/process-inspector.ts
+++ b/packages/subprocess/subprocess-local/src/process-inspector.ts
@@ -16,6 +16,8 @@ export interface ProcessInspector {
   isStdinWaiting(pgid: number): boolean
   /** Return the root and its current transitive descendants, children first. */
   processTree(rootPid: number): ProcessIdentity[]
+  /** Return current members of one POSIX process session when the platform exposes them. */
+  processSession(sessionId: number): ProcessIdentity[]
   /** Return whether the exact identity remains a non-quiescent process. */
   isAlive(identity: ProcessIdentity): boolean
   signalGroup(pgid: number, signal: SubprocessTerminalSignal): void
@@ -201,6 +203,7 @@ abstract class PosixProcessInspector implements ProcessInspector {
   abstract foregroundPgid(shellPid: number): number | undefined
   abstract isStdinWaiting(pgid: number): boolean
   abstract processTree(rootPid: number): ProcessIdentity[]
+  abstract processSession(sessionId: number): ProcessIdentity[]
   abstract isAlive(identity: ProcessIdentity): boolean
 
   signalGroup(pgid: number, signal: SubprocessTerminalSignal): void {
@@ -272,6 +275,13 @@ class LinuxProcessInspector extends PosixProcessInspector {
     return processTree(entries, rootPid)
   }
 
+  processSession(sessionId: number): ProcessIdentity[] {
+    return numericEntries(this.internals, '/proc').flatMap((pid) => {
+      const stat = readLinuxStat(this.internals, pid)
+      return stat?.session === sessionId ? [{ pid, started: stat.started }] : []
+    })
+  }
+
   isAlive(identity: ProcessIdentity): boolean {
     const stat = readLinuxStat(this.internals, identity.pid)
     return stat?.started === identity.started && !/^[ZXx]$/.test(stat.state)
@@ -307,6 +317,10 @@ class MacProcessInspector extends PosixProcessInspector {
     return processTree(macProcessTable(this.internals), rootPid)
   }
 
+  processSession(_sessionId: number): ProcessIdentity[] {
+    return []
+  }
+
   isAlive(identity: ProcessIdentity): boolean {
     return macProcessTable(this.internals).some(entry => entry.pid === identity.pid && entry.started === identity.started)
   }
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index d4b7bd26d1..8446f11b8f 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -36,6 +36,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private exited = false
   private termination: Promise<void> | undefined
   private removeAbort: (() => void) | undefined
+  private trackedDescendants: ProcessIdentity[] = []
 
   /**
    * @param terminal - allocated node-pty process.
@@ -86,6 +87,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   // Local inspection is synchronous; the seam returns a promise for remote transports.
   // eslint-disable-next-line @typescript-eslint/require-await
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    this.descendants()
     const processGroupId = this.inspector.foregroundPgid(this.pid)
     if (processGroupId === undefined) return undefined
     return {
@@ -145,7 +147,12 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+    this.trackedDescendants = this.survivors(this.unionMembers(
+      this.trackedDescendants,
+      this.inspector.processTree(this.pid),
+      this.inspector.processSession(this.pid),
+    ).filter(member => member.pid !== this.pid))
+    return this.trackedDescendants
   }
 
   private async waitForMembers(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 7ff10a7348..93be25acd0 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -111,6 +111,7 @@ describe('LocalSubprocessService', () => {
       foregroundPgid: () => undefined,
       isStdinWaiting: () => false,
       processTree: () => [],
+      processSession: () => [],
       isAlive: () => false,
       signalGroup: () => {},
       signalProcess: () => {},
@@ -175,6 +176,7 @@ describe('LocalSubprocessService', () => {
         foregroundPgid: () => 123,
         isStdinWaiting: () => false,
         processTree: () => [{ pid: 124, started: 'child' }],
+        processSession: () => [],
         isAlive: identity => alive.has(identity.pid),
         signalGroup: () => {},
         signalProcess: () => {},
diff --git a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
index e8ad2fd11e..bcc3ddb091 100644
--- a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
@@ -86,6 +86,13 @@ describe('Linux process inspector', () => {
       { pid: 10, started: '500' },
     ])
     expect(inspector.processTree(99)).toEqual([])
+    expect(inspector.processSession(30)).toEqual([
+      { pid: 10, started: '500' },
+      { pid: 11, started: '501' },
+      { pid: 12, started: '502' },
+      { pid: 13, started: '503' },
+    ])
+    expect(inspector.processSession(99)).toEqual([])
     expect(inspector.isAlive({ pid: 10, started: '500' })).toBe(true)
     expect(inspector.isAlive({ pid: 10, started: 'old' })).toBe(false)
     inspector.signalGroup(40, 'SIGINT')
@@ -197,6 +204,7 @@ describe('macOS process inspector', () => {
       { pid: 10, started: 'Mon Jul 21 10:00:00 2026' },
     ])
     expect(inspector.processTree(99)).toEqual([])
+    expect(inspector.processSession(10)).toEqual([])
     expect(inspector.isAlive({ pid: 11, started: 'Mon Jul 21 10:00:01 2026' })).toBe(true)
     inspector.signalGroup(55, 'SIGTSTP')
     inspector.signalProcess({ pid: 11, started: 'Mon Jul 21 10:00:01 2026' }, 'SIGKILL')
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 417fd62517..0202a3f33e 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -51,6 +51,7 @@ class FakeInspector implements ProcessInspector {
   pgid: number | undefined = 456
   waiting = false
   members: ProcessIdentity[] = []
+  sessionMembers: ProcessIdentity[] = []
   readonly alive = new Set<number>()
   readonly groups: Array<[number, SubprocessTerminalSignal]> = []
   readonly processes: Array<[number, 'SIGTERM' | 'SIGKILL']> = []
@@ -61,6 +62,7 @@ class FakeInspector implements ProcessInspector {
   foregroundPgid() { return this.pgid }
   isStdinWaiting() { return this.waiting }
   processTree() { return this.members }
+  processSession() { return this.sessionMembers }
   isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
   signalGroup(pgid: number, signal: SubprocessTerminalSignal) {
     if (this.throwGroup) throw new Error('group failed')
@@ -158,6 +160,36 @@ describe('LocalTerminalHandle', () => {
     expect(await waiting).toBe(true)
   })
 
+  it('cleans a same-session descendant after the top-level shell exits naturally', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const disowned = { pid: 124, started: 'disowned' }
+    inspector.processSession = () => inspector.alive.has(disowned.pid) ? [disowned] : []
+    inspector.alive.add(124)
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+
+    pty.emitExit()
+
+    expect(await handle.waitForExit()).toBe(true)
+    expect(inspector.processes).toEqual([[124, 'SIGTERM']])
+  })
+
+  it('retains an inspected descendant after it reparents away from the shell', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const descendant = { pid: 124, started: 'observed' }
+    inspector.members = [descendant]
+    inspector.alive.add(descendant.pid)
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+
+    await handle.inspectForeground()
+    inspector.members = []
+    pty.emitExit()
+
+    expect(await handle.waitForExit()).toBe(true)
+    expect(inspector.processes).toEqual([[124, 'SIGTERM']])
+  })
+
   it('rescans for descendants forked during TERM', async () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 384c9cdb94..13b8df9f71 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: db4478fe799dce1bbdb7e3ae3d31947515aae151
-README.zh.md: 238f5f66db58edb99945cfa43299635b4f8f36a8
+README.md: fd8cfccdb333018e551459195564daad157d3867
+README.zh.md: b5b495e22bbf4328d82925cc793588ee45e5c6e4

From 65264f6c80f034b0c1c0bd448c5635506b98b792 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:17:40 +0800
Subject: [PATCH 045/262] refactor(subprocess): share terminal lifecycle

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |   2 +-
 ...8-portable-execution-world-consumers.zh.md |   2 +-
 .../subprocess-local/src/terminal.ts          |  47 ++-----
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   1 +
 packages/subprocess/subprocess/README.zh.md   |   1 +
 packages/subprocess/subprocess/src/index.ts   |   2 +
 .../subprocess/src/terminal-lifecycle.ts      | 104 +++++++++++++++
 .../tests/terminal-lifecycle.spec.ts          | 125 ++++++++++++++++++
 10 files changed, 248 insertions(+), 44 deletions(-)
 create mode 100644 packages/subprocess/subprocess/src/terminal-lifecycle.ts
 create mode 100644 packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index f97b09b940..231037f054 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 3d1928be882fb3fb621e733649146445c69e8a5b
-2026-07-28-portable-execution-world-consumers.zh.md: f385e502d5d737fe0d5ae6e28ac7a3a097d85a6b
+2026-07-28-portable-execution-world-consumers.md: a5df393f31a25b7d16e63af240882e1d94093e34
+2026-07-28-portable-execution-world-consumers.zh.md: 87f11fa53b5b7579969dcb15dc3aaad978018773
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 3d1928be88..a5df393f31 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -16,7 +16,7 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, containment, and a bounded stable-handle text read. The existing text and mutation operations remain filesystem-owned.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. The interface package also exports a provider-neutral lifecycle controller that joins top-level settlement, lifetime cancellation, retryable provider cleanup, and bounded quiescence observation; each implementation supplies only its session-cleanup transaction. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index f385e502d5..87f11fa53b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI、包含关系，以及通过稳定句柄执行的有界文本读取。现有文本与变更操作仍归文件系统负责。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。接口包还导出一个提供方无关的生命周期控制器，用于组合顶层结算、生命周期取消、可重试的提供方清理与有界的完全停稳观测；每个实现只需提供自身的会话清理事务。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 8446f11b8f..2f1e4d4058 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -4,6 +4,7 @@ import { Buffer } from 'node:buffer'
 import { constants } from 'node:os'
 import { PassThrough } from 'node:stream'
 import type { IDisposable, IPty } from 'node-pty'
+import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -33,9 +34,8 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
   private readonly dataDisposable: IDisposable
   private readonly exitDisposable: IDisposable
+  private readonly lifecycle: SubprocessTerminalLifecycle
   private exited = false
-  private termination: Promise<void> | undefined
-  private removeAbort: (() => void) | undefined
   private trackedDescendants: ProcessIdentity[] = []
 
   /**
@@ -63,12 +63,11 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
       })
       this.terminate()
     })
-    if (signal !== undefined) {
-      const onAbort = (): void => { this.terminate() }
-      signal.addEventListener('abort', onAbort, { once: true })
-      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
-      if (signal.aborted) this.terminate()
-    }
+    this.lifecycle = new SubprocessTerminalLifecycle({
+      done: this.done,
+      cleanup: () => this.closeOnce(),
+      signal,
+    })
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
@@ -109,37 +108,11 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   terminate(): void {
-    this.termination ??= this.closeOnce().catch((error: unknown) => {
-      this.termination = undefined
-      throw error
-    })
-    void this.termination.catch(() => {})
+    this.lifecycle.terminate()
   }
 
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    // A caller may begin waiting before the top-level process exits. The exit
-    // callback starts descendant cleanup in the same turn, so resolve that
-    // eventual transaction after `done` instead of snapshotting only `done`.
-    const quiescence = this.termination ?? this.done.then(() => this.termination)
-    if (signal === undefined) {
-      await quiescence
-      return true
-    }
-    if (signal.aborted) return false
-    return await new Promise<boolean>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(false) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      void quiescence.then(
-        () => { cleanup(); resolve(true) },
-        (error: unknown) => {
-          cleanup()
-          // The owned cleanup transaction only throws Error diagnostics.
-          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
-          reject(error)
-        },
-      )
-    })
+    return await this.lifecycle.waitForExit(signal)
   }
 
   private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
@@ -225,8 +198,6 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
       throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
     await this.stopShell()
-    this.removeAbort?.()
-    this.removeAbort = undefined
     this.dataDisposable.dispose()
     this.exitDisposable.dispose()
   }
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 84d7d4a666..8e6c6a88e4 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 84b4b0c11c74c96929fa97b58fb33156d44e6ef1
-README.zh.md: dbd80a1c975719884481501f5cc43798e464a4fb
+README.md: d03824da33bb44b2525b1343a27557ed15823418
+README.zh.md: 34cc75c3cfc8148754343e92b0c204760b1fb543
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 84b4b0c11c..d03824da33 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -12,6 +12,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
 - `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, valid-UTF-8 byte I/O, foreground-process-group inspection/signalling, TERM-to-KILL whole-session cleanup, and a quiescence wait. The output stream ends after queued output when the top-level process exits; a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or prove and clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
+- `SubprocessTerminalLifecycle` composes a handle's top-level `done` promise with its provider-owned session cleanup. It binds lifetime cancellation, shares one active cleanup attempt, permits a failed attempt to retry, normalizes cleanup rejections, and bounds quiescence observation without knowing the provider's process mechanics.
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index dbd80a1c97..34cc75c3cf 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -12,6 +12,7 @@
 - stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
 - `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、有效 UTF-8 字节 I/O、前台进程组检查／信号发送、TERM→KILL 全会话清理，以及等待完全停稳。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法证明并清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
+- `SubprocessTerminalLifecycle` 把句柄的顶层 `done` promise 与由提供方负责的会话清理组合起来。它绑定生命周期取消，共享同一个进行中的清理尝试，允许失败的尝试重试，规范化清理拒绝，并在不了解提供方进程机制的情况下对完全停稳观测施加上限。
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 3c58a07a9e..df79ee5f3e 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -14,6 +14,8 @@ import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts'
 import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts'
 
 export { DSH_ENV_PREFIX } from './types.ts'
+export { SubprocessTerminalLifecycle } from './terminal-lifecycle.ts'
+export type { SubprocessTerminalLifecycleOptions } from './terminal-lifecycle.ts'
 export type {
   CollectedOutput,
   DshEnvironment,
diff --git a/packages/subprocess/subprocess/src/terminal-lifecycle.ts b/packages/subprocess/subprocess/src/terminal-lifecycle.ts
new file mode 100644
index 0000000000..76430fe7c6
--- /dev/null
+++ b/packages/subprocess/subprocess/src/terminal-lifecycle.ts
@@ -0,0 +1,104 @@
+/** Provider-neutral lifecycle transaction for terminal-process handles. */
+
+/** Inputs owned by one terminal-process lifecycle controller. */
+export interface SubprocessTerminalLifecycleOptions {
+  /** Settlement of the top-level terminal process or its live transport. */
+  readonly done: Promise<unknown>
+  /** Provider-owned cleanup that reaches whole-session quiescence. */
+  readonly cleanup: () => Promise<void>
+  /** Optional cancellation for the complete terminal lifetime. */
+  readonly signal?: AbortSignal | undefined
+}
+
+function normalizeCleanupError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Coordinates terminal cleanup without knowing how a provider allocates or
+ * terminates its process session. One active cleanup attempt is shared by all
+ * callers; a rejected attempt may be retried, and successful cleanup removes
+ * the lifetime abort listener.
+ */
+export class SubprocessTerminalLifecycle {
+  private cleanupAttempt: Promise<void> | undefined
+  private removeLifetimeAbort: (() => void) | undefined
+
+  /**
+   * @param options - top-level settlement, provider cleanup, and lifetime cancellation.
+   */
+  constructor(private readonly options: SubprocessTerminalLifecycleOptions) {
+    const onDone = (): void => { this.terminate() }
+    void options.done.then(onDone, onDone)
+
+    if (options.signal !== undefined) {
+      const onAbort = (): void => { this.terminate() }
+      options.signal.addEventListener('abort', onAbort, { once: true })
+      this.removeLifetimeAbort = () => { options.signal?.removeEventListener('abort', onAbort) }
+      if (options.signal.aborted) this.terminate()
+    }
+  }
+
+  /** Begin an idempotent provider cleanup attempt. */
+  terminate(): void {
+    void this.startCleanup().catch(() => {})
+  }
+
+  /**
+   * Wait for top-level settlement and successful whole-session cleanup.
+   * @param signal - optional bound for this observation only.
+   * @returns true after quiescence, false when the observer signal aborts first.
+   */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    const quiescence = this.cleanupAttempt ?? this.options.done.then(
+      () => this.startCleanup(),
+      () => this.startCleanup(),
+    )
+    if (signal === undefined) {
+      await quiescence
+      return true
+    }
+    if (signal.aborted) return false
+
+    return await new Promise<boolean>((resolve, reject) => {
+      let settled = false
+      const finish = (complete: () => void): void => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener('abort', onAbort)
+        complete()
+      }
+      const onAbort = (): void => { finish(() => { resolve(false) }) }
+
+      signal.addEventListener('abort', onAbort, { once: true })
+      if (signal.aborted) onAbort()
+      void quiescence.then(
+        () => { finish(() => { resolve(true) }) },
+        (error: unknown) => { finish(() => { reject(normalizeCleanupError(error)) }) },
+      )
+    })
+  }
+
+  private startCleanup(): Promise<void> {
+    if (this.cleanupAttempt !== undefined) return this.cleanupAttempt
+
+    const outcome = Promise.withResolvers<void>()
+    this.cleanupAttempt = outcome.promise.catch((error: unknown) => {
+      this.cleanupAttempt = undefined
+      throw normalizeCleanupError(error)
+    })
+    void this.cleanupAttempt.then(
+      () => {
+        this.removeLifetimeAbort?.()
+        this.removeLifetimeAbort = undefined
+      },
+      () => {},
+    )
+    try {
+      void this.options.cleanup().then(outcome.resolve, outcome.reject)
+    } catch (error: unknown) {
+      outcome.reject(error)
+    }
+    return this.cleanupAttempt
+  }
+}
diff --git a/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts b/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
new file mode 100644
index 0000000000..2dd688bbc0
--- /dev/null
+++ b/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from 'vitest'
+import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
+
+describe('SubprocessTerminalLifecycle', () => {
+  it('waits for top-level settlement and the provider cleanup transaction', async () => {
+    const done = Promise.withResolvers<undefined>()
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanup = vi.fn(() => cleanupGate.promise)
+    const lifecycle = new SubprocessTerminalLifecycle({ done: done.promise, cleanup })
+
+    const waiting = lifecycle.waitForExit()
+    expect(cleanup).not.toHaveBeenCalled()
+    done.resolve(undefined)
+    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
+
+    const observed = vi.fn()
+    void waiting.then(observed)
+    await Promise.resolve()
+    expect(observed).not.toHaveBeenCalled()
+
+    cleanupGate.resolve(undefined)
+    await expect(waiting).resolves.toBe(true)
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+    expect(cleanup).toHaveBeenCalledOnce()
+  })
+
+  it('normalizes cleanup failures, permits retries, and retains lifetime cancellation until success', async () => {
+    const done = Promise.withResolvers<undefined>()
+    const lifetime = new AbortController()
+    const removeListener = vi.spyOn(lifetime.signal, 'removeEventListener')
+    const synchronousFailure = new Error('first cleanup failed')
+    let attempt = 0
+    const cleanup = vi.fn((): Promise<void> => {
+      attempt += 1
+      if (attempt === 1) throw synchronousFailure
+      if (attempt === 2) {
+        return Promise.resolve().then(() => {
+          const nonErrorRejection: unknown = 'cleanup transport gone'
+          throw nonErrorRejection
+        })
+      }
+      return Promise.resolve()
+    })
+    const lifecycle = new SubprocessTerminalLifecycle({
+      done: done.promise,
+      cleanup,
+      signal: lifetime.signal,
+    })
+
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).rejects.toBe(synchronousFailure)
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).rejects.toThrow('cleanup transport gone')
+
+    lifetime.abort()
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+    expect(cleanup).toHaveBeenCalledTimes(3)
+    expect(removeListener).toHaveBeenCalledWith('abort', expect.any(Function))
+
+    done.reject(new Error('top-level transport failed'))
+    await Promise.resolve()
+    expect(cleanup).toHaveBeenCalledTimes(3)
+  })
+
+  it('starts cleanup for a pre-aborted lifetime and bounds a wait that is already aborted', async () => {
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanup = vi.fn(() => cleanupGate.promise)
+    const lifecycle = new SubprocessTerminalLifecycle({
+      done: new Promise(() => {}),
+      cleanup,
+      signal: AbortSignal.abort(new Error('lifetime cancelled')),
+    })
+
+    expect(cleanup).toHaveBeenCalledOnce()
+    await expect(lifecycle.waitForExit(AbortSignal.abort())).resolves.toBe(false)
+    cleanupGate.resolve(undefined)
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('contains cleanup settlement after an observer aborts between signal checks', async () => {
+    const firstCleanup = Promise.withResolvers<undefined>()
+    const cleanup = vi.fn()
+      .mockImplementationOnce(() => firstCleanup.promise)
+      .mockResolvedValueOnce(undefined)
+    const lifecycle = new SubprocessTerminalLifecycle({ done: Promise.resolve(), cleanup })
+    const observer = new AbortController().signal
+    vi.spyOn(observer, 'aborted', 'get')
+      .mockReturnValueOnce(false)
+      .mockReturnValueOnce(true)
+
+    await expect(lifecycle.waitForExit(observer)).resolves.toBe(false)
+    firstCleanup.reject(new Error('late cleanup failure'))
+    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
+    await Promise.resolve()
+
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+    expect(cleanup).toHaveBeenCalledTimes(2)
+  })
+
+  it('reports bounded cleanup success and failure', async () => {
+    const successful = new SubprocessTerminalLifecycle({
+      done: Promise.resolve(),
+      cleanup: async () => {},
+    })
+    await expect(successful.waitForExit(new AbortController().signal)).resolves.toBe(true)
+
+    const failure = new Error('quiescence failed')
+    const failed = new SubprocessTerminalLifecycle({
+      done: Promise.resolve(),
+      cleanup: () => Promise.reject(failure),
+    })
+    await expect(failed.waitForExit(new AbortController().signal)).rejects.toBe(failure)
+
+    const failedDone = Promise.withResolvers<undefined>()
+    const afterTransportFailure = new SubprocessTerminalLifecycle({
+      done: failedDone.promise,
+      cleanup: async () => {},
+    })
+    const waiting = afterTransportFailure.waitForExit()
+    failedDone.reject(new Error('transport failed'))
+    await expect(waiting).resolves.toBe(true)
+  })
+})

From a0200376a1aaa35e00c1e2583b47f5a39c5ba157 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:44:57 +0800
Subject: [PATCH 046/262] fix(pty): defer the first readiness poll

---
 packages/pty/pty-local/src/session.ts        |  2 +-
 packages/pty/pty-local/tests/session.spec.ts | 25 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 9a0beed6ff..03809aec9f 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -266,7 +266,7 @@ export class LocalPtySession implements PtyBackendSession {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       if (this.active === operation && !this.closing) {
         this.pollingReady = operation
-        this.schedulePoll(operation, 0)
+        this.schedulePoll(operation)
       }
     } catch (error: unknown) {
       if (this.active === operation) {
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 120b2881e1..5f0065d0ee 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -143,6 +143,31 @@ async function initialize(session: LocalPtySession, terminal: FakeTerminal): Pro
 }
 
 describe('LocalPtySession readiness and output', () => {
+  it('lets queued terminal output run before the first post-write readiness poll', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const inspect = terminal.inspectForeground.bind(terminal)
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      return await inspect()
+    }
+    const operation = session.startSend({ text: 'true', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(inspections).toBe(1)
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspections).toBe(1)
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect((await operation.done).waitReason).toBe('stdin_read')
+  })
+
   it('captures prompt MOTD, writes submit explicitly, and settles exact stdin waits', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 03f1c8eb437885469e3478a6982c525b4de6cb50 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:45:06 +0800
Subject: [PATCH 047/262] fix(subprocess): absolutize relative PATH lookups

---
 packages/subprocess/subprocess-local/src/index.ts        | 4 ++--
 packages/subprocess/subprocess-local/tests/local.spec.ts | 5 ++++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 40d2f52552..03755cd9ea 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -11,7 +11,7 @@ import { constants } from 'node:fs'
 import { mkdtempSync } from 'node:fs'
 import { access, rm, stat } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { delimiter, extname, isAbsolute, join } from 'node:path'
+import { delimiter, extname, isAbsolute, join, resolve } from 'node:path'
 import { Context } from 'cordis'
 import * as nodePty from 'node-pty'
 import type { IPtyForkOptions } from 'node-pty'
@@ -107,7 +107,7 @@ export class LocalSubprocessService extends SubprocessService {
       ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
-      directory === '' ? [] : extensions.map(extension => join(directory, command + extension)))
+      directory === '' ? [] : extensions.map(extension => resolve(this.cwd, directory, command + extension)))
   }
 
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 93be25acd0..6ce3d06b8e 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,7 +1,7 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { stat } from 'node:fs/promises'
-import { basename, delimiter, dirname } from 'node:path'
+import { basename, delimiter, dirname, relative } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
@@ -38,6 +38,9 @@ describe('LocalSubprocessService', () => {
     expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
       PATH: dirname(process.execPath),
     })).toBe(process.execPath)
+    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
+      PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
+    })).toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')

From 35376658061cc35aaf9316eca3100af6d0445357 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 04:19:04 +0800
Subject: [PATCH 048/262] fix(subprocess): honor Windows environment key casing

---
 packages/subprocess/subprocess-local/src/index.ts    | 12 ++++++++++--
 .../subprocess/subprocess-local/tests/local.spec.ts  |  4 +++-
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 03755cd9ea..4c5cad8018 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -102,9 +102,9 @@ export class LocalSubprocessService extends SubprocessService {
   }
 
   private executableCandidates(command: string, env: NodeJS.ProcessEnv): string[] {
-    const path = env.PATH ?? ''
+    const path = environmentValue(env, 'PATH') ?? ''
     const extensions = process.platform === 'win32' && extname(command) === ''
-      ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+      ? (environmentValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
       directory === '' ? [] : extensions.map(extension => resolve(this.cwd, directory, command + extension)))
@@ -156,4 +156,12 @@ export class LocalSubprocessService extends SubprocessService {
   }
 }
 
+/** Read a Windows environment key using the platform's case-insensitive semantics. */
+function environmentValue(env: NodeJS.ProcessEnv, name: 'PATH' | 'PATHEXT'): string | undefined {
+  const exact = env[name]
+  if (exact !== undefined || process.platform !== 'win32') return exact
+  const normalized = name.toUpperCase()
+  return Object.entries(env).find(([key]) => key.toUpperCase() === normalized)?.[1]
+}
+
 export default LocalSubprocessService
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 6ce3d06b8e..4662283aad 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -62,8 +62,10 @@ describe('LocalSubprocessService', () => {
     }).executableCandidates.bind(service)
     const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     try {
-      expect(candidates('tool', { PATH: `${delimiter}/bin`, PATHEXT: '.EXE;.CMD' }))
+      expect(candidates('tool', { Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' }))
         .toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
+      expect(candidates('tool', { Path: '/ambient', PATH: '/explicit', PATHEXT: '.EXE' }))
+        .toEqual(['/explicit/tool.EXE'])
       expect(candidates('tool.exe', {})).toEqual([])
       expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
     } finally {

From 4997fb219e38e26ef7e76d4c0531f029849bfc96 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 04:19:18 +0800
Subject: [PATCH 049/262] fix(lsp): preserve execution-world URI semantics

---
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  4 +-
 .../2026-07-15-lsp-capability-seam.md         |  6 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  6 +-
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 docs/core-data-structures/lsp.i18n.yaml       |  4 +-
 docs/core-data-structures/lsp.md              | 12 ++--
 docs/core-data-structures/lsp.zh.md           | 12 ++--
 packages/lsp/lsp-local/src/instance.ts        |  7 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |  8 +--
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |  8 +--
 packages/lsp/lsp/README.i18n.yaml             |  4 +-
 packages/lsp/lsp/README.md                    |  2 +-
 packages/lsp/lsp/README.zh.md                 | 14 ++--
 packages/lsp/lsp/src/types.ts                 | 10 +--
 packages/lsp/lsp/tests/lsp.spec.ts            |  8 +--
 packages/lsp/tool-lsp/README.i18n.yaml        |  4 +-
 packages/lsp/tool-lsp/README.md               |  2 +-
 packages/lsp/tool-lsp/README.zh.md            | 16 ++---
 packages/lsp/tool-lsp/src/index.ts            |  6 +-
 packages/lsp/tool-lsp/src/render.ts           | 72 ++++++++++++++-----
 packages/lsp/tool-lsp/tests/render.spec.ts    | 45 ++++++++----
 packages/lsp/tool-lsp/tests/tool-lsp.spec.ts  | 11 +--
 24 files changed, 162 insertions(+), 107 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index afb9251d33..bba045d606 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: a9dab45ebf034f6d5218b25a0868a7e86803719b
-2026-07-15-lsp-capability-seam.zh.md: b411a2456ea2a3838e56422f58954473da51ae23
+2026-07-15-lsp-capability-seam.md: 6e46fac0611c1b7282766cf57965a07e3ee6bb9b
+2026-07-15-lsp-capability-seam.zh.md: b535b60df70e8a6132bb1596581be3ab1daba932
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index a9dab45ebf..6e46fac061 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -62,7 +62,7 @@ interface LspProviderQuery extends LspQueryRequest {
 }
 
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null }
 
 interface LspProvider {
@@ -77,7 +77,7 @@ interface LspService {
 }
 ```
 
-Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's resolved workspace root so consumers relativize file URIs in the same canonical namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
+Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's canonical workspace URI so consumers relativize file URIs in the execution world's namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
 
 `dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their interface packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
 
@@ -98,7 +98,7 @@ interface LspToolInput {
 
 The tool requires `workspaceRoot` from session `header.cwd`, with no fallback; absence fails as `LSP_WORKSPACE_REQUIRED` before querying or startup. The local provider resolves relative paths against that root and accepts absolute paths directly; both forms are canonicalized and rejected before startup when the target is outside the canonical workspace.
 
-Locations render as stable, file-grouped `path:line:character` entries. A `file:` URI accepted by Node `fileURLToPath()` becomes a relative path inside the workspace or an absolute path outside it; other URIs remain verbatim. `maxLocations` defaults to `100` and reports omitted items; `maxResultChars` defaults to `16_000` and bounds every complete rendered result, including its truncation metadata. Empty locations and `null` hover are successful no-result responses; missing or malformed server payloads fail with structured `LSP_MALFORMED_RESPONSE` errors.
+Locations render as stable, file-grouped `path:line:character` entries without applying harness-host path rules. A valid `file:` URI becomes a relative path inside the provider's canonical workspace URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs remain verbatim. `maxLocations` defaults to `100` and reports omitted items; `maxResultChars` defaults to `16_000` and bounds every complete rendered result, including its truncation metadata. Empty locations and `null` hover are successful no-result responses; missing or malformed server payloads fail with structured `LSP_MALFORMED_RESPONSE` errors.
 
 The transport-neutral presenter uses `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }` with an args-derived operation/cursor `title`. Because `FileLocation` has no character, follow-along focuses the input line while the title preserves the cursor; presentation remains pure.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index b411a2456e..b535b60df7 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -62,7 +62,7 @@ interface LspProviderQuery extends LspQueryRequest {
 }
 
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null }
 
 interface LspProvider {
@@ -77,7 +77,7 @@ interface LspService {
 }
 ```
 
-映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方解析后的工作区根目录，使消费方依据同一规范化根目录相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
+映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方的规范工作区 URI，使消费方在执行世界的命名空间内相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
 
 `dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
@@ -98,7 +98,7 @@ interface LspToolInput {
 
 工具必须从会话 `header.cwd` 取得 `workspaceRoot`，没有后备值；缺失时在查询或启动前以 `LSP_WORKSPACE_REQUIRED` 失败。本地提供方基于根目录解析相对路径并直接接受绝对路径；两种路径都会进行规范化，如果目标位于规范工作区外，则在启动前拒绝。
 
-位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径，在工作区外转换为绝对路径；其他 URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并限制每个完整渲染结果，其中包括截断元数据。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
+位置在不应用 harness 宿主路径规则的情况下按文件稳定分组并渲染为 `path:line:character`。有效的 `file:` URI 落在提供方的规范工作区 URI 内时转换为相对路径，位于其外时转换为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并限制每个完整渲染结果，其中包括截断元数据。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
 
 与传输方式无关的展示器使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`，`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character，跟随位置聚焦输入行，标题保留完整光标；展示保持纯函数。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 231037f054..1033fffcc6 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: a5df393f31a25b7d16e63af240882e1d94093e34
-2026-07-28-portable-execution-world-consumers.zh.md: 87f11fa53b5b7579969dcb15dc3aaad978018773
+2026-07-28-portable-execution-world-consumers.md: 6f75778398e8f204c85b64fe096838a3b62d398e
+2026-07-28-portable-execution-world-consumers.zh.md: 22edc591f7716a92fd2a68d74c84168189743fbd
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index a5df393f31..6f75778398 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -21,7 +21,7 @@ The subprocess interface owns the process coordinates and primitives: canonical
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
-- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
+- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 87f11fa53b..22edc591f7 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
-- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
+- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/core-data-structures/lsp.i18n.yaml
index 5bed4a1a23..329d5086e0 100644
--- a/docs/core-data-structures/lsp.i18n.yaml
+++ b/docs/core-data-structures/lsp.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 docs/core-data-structures/lsp.md
-lsp.md: 62b133cbfdf521e067c56355664d7514a613397f
-lsp.zh.md: 51a19a51a8ad92e744cb920a51f3214f68ae0036
+lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
+lsp.zh.md: ef9623f01124bc459d3bbceba340c3870e678baa
diff --git a/docs/core-data-structures/lsp.md b/docs/core-data-structures/lsp.md
index 62b133cbfd..03d0ce2dbe 100644
--- a/docs/core-data-structures/lsp.md
+++ b/docs/core-data-structures/lsp.md
@@ -73,7 +73,7 @@ interface LspProviderQuery extends LspQueryRequest {
 
 ## Result
 
-A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to, so a caller relativizing display paths uses it rather than the possibly-symlinked request root.
+A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceUri`, the provider's canonical workspace `file:` URI. A caller relativizing location URIs uses that coordinate rather than applying host-platform path rules to the possibly-symlinked request root.
 
 ```ts type-equiv
 /** One resolved location: a document URI and the range within it. */
@@ -101,13 +101,13 @@ interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 ```
 
diff --git a/docs/core-data-structures/lsp.zh.md b/docs/core-data-structures/lsp.zh.md
index 51a19a51a8..d428f2b5f9 100644
--- a/docs/core-data-structures/lsp.zh.md
+++ b/docs/core-data-structures/lsp.zh.md
@@ -73,7 +73,7 @@ interface LspProviderQuery extends LspQueryRequest {
 
 ## 结果
 
-这是一个闭合的可辨识联合：导航操作规范化为 `locations`，`hover` 规范化为内容或 `null`。消费方使用 `switch` 对 `kind` 做穷尽处理，因此新增分支会使编译失败，直到完成处理。`findReferences` 始终包含声明；提供方在内部强制保证这一点，因此调用方没有对应 flag。`locations` 变体携带 `resolvedWorkspaceRoot`，即提供方对请求中 `workspaceRoot` 的规范形式，也是其 `file:` URI 所相对的根目录；调用方在相对化显示路径时应使用它，而不是可能经过符号链接的请求根目录。
+这是一个闭合的可辨识联合：导航操作规范化为 `locations`，`hover` 规范化为内容或 `null`。消费方使用 `switch` 对 `kind` 做穷尽处理，因此新增分支会使编译失败，直到完成处理。`findReferences` 始终包含声明；提供方在内部强制保证这一点，因此调用方没有对应 flag。`locations` 变体携带 `resolvedWorkspaceUri`，即提供方的规范工作区 `file:` URI。调用方相对化位置 URI 时应使用这一坐标，而不是对可能经过符号链接的请求根目录应用宿主平台路径规则。
 
 ```ts type-equiv
 /** One resolved location: a document URI and the range within it. */
@@ -101,13 +101,13 @@ interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 ```
 
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 8584f64f48..318704b9fc 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -244,10 +244,9 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
-    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
-    // display paths against, not the request's possibly-symlinked workspaceRoot.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
+    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
+    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 3027cbbd29..811f15c9fa 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -117,17 +117,17 @@ describe('LspInstance server-request handling', () => {
 
   it('accepts a lifecycle client/registerCapability request', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 
   it('rejects a workspace/applyEdit request but keeps serving', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 
   it('rejects an unknown server request but keeps serving', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 })
 
@@ -263,7 +263,7 @@ describe('LspInstance query and abort', () => {
     await expect(run(instance, 'goToDefinition')).resolves.toEqual({
       kind: 'locations',
       locations: [],
-      resolvedWorkspaceRoot: ws,
+      resolvedWorkspaceUri: pathToFileURL(ws).href,
     })
     expect(instance.dead).toBe(true)
   })
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index a7a006c06e..ce92e2c8fb 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -102,7 +102,7 @@ describe('lsp-local end to end over a fake server', () => {
     expect(result).toEqual<LspQueryResult>({
       kind: 'locations',
       locations: [{ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }],
-      resolvedWorkspaceRoot: ws,
+      resolvedWorkspaceUri: pathToFileURL(ws).href,
     })
     await ctx.fiber.dispose()
   })
@@ -133,7 +133,7 @@ describe('lsp-local end to end over a fake server', () => {
 
   it('returns an empty locations result for a null definition', async () => {
     const ctx = await mount({ LSP_FAKE_DEF: 'null' })
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
@@ -173,7 +173,7 @@ describe('lsp-local end to end over a fake server', () => {
 
   it('accepts openClose options sync', async () => {
     const ctx = await mount({ LSP_FAKE_SYNC: JSON.stringify({ openClose: true, change: 2 }), LSP_FAKE_DEF: 'null' })
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
@@ -297,7 +297,7 @@ describe('lsp-local end to end over a fake server', () => {
     controller.abort(new Error('mid-read cancel'))
     await expect(pending).rejects.toThrow(/mid-read cancel/)
     // A subsequent live query still works, proving no half-created instance poisoned the pool.
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index 3faf906868..02649a8d39 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
-README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
-README.zh.md: 9757147de692684747d9965efda6329b3bbe2638
+README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
+README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index f96fc67ec8..5c1044be50 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -27,7 +27,7 @@ Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner
 
 ## Vocabulary
 
-`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceRoot }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceRoot` is the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to; a caller relativizing display paths uses it, not the (possibly symlinked) request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
+`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceUri }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceUri` is the provider's canonical workspace `file:` URI; callers relativize location URIs against it instead of applying host-platform path rules to the possibly symlinked request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
 
 ## Model Experience
 
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index 9757147de6..cc412333e6 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -8,7 +8,7 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以带品牌类型的 id 和扩展名映射为键的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
+| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
@@ -18,16 +18,16 @@
 
 | 成员 | 语义 |
 |---|---|
-| `registerProvider(provider)` | 注册后端，以原子方式保留其带品牌类型的 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 一同 dispose（资源释放）。 |
+| `registerProvider(provider)` | 注册后端，以原子方式保留其品牌化 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 释放。 |
 | `query(request, signal?)` | 按文件最终扩展名选择提供方，从该提供方的映射派生 `languageId`，并运行一次查询。没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。 |
 
-选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR（热模块替换）顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
+选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR 顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
 
-提供方注册的是**能力**，而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
+提供方注册的是**能力** 而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
 
 ## 词汇
 
-`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具负责从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceRoot }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceRoot` 是提供方对请求 `workspaceRoot` 的规范形式，也是其 `file:` URI 所相对的根；调用方把显示路径相对化时使用该值，而非可能含符号链接的请求根。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` 代码，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
+`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
 
 ## 模型体验
 
@@ -39,6 +39,6 @@
 
 ## 已知限制与暂缓事项
 
-- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使语言 ID 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使 language id 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
 - **仅四种操作**：symbol 与 call hierarchy 暂缓（它们需要不同 schema）；diagnostics 需要独立的新鲜度／累积规则；修改操作（rename、code action、formatting）需要独立工具，并集成预览、权限和写入策略。
-- **没有观测接口**：可用性只能通过运行 `query()` 并按抛出的 `LspError` 代码进行路由来观测；没有提供方变更事件或能力状态查询。
+- **没有观测表层**：可用性只能通过运行 `query()` 并按抛出的 `LspError` code 路由来观测；没有提供方变更事件或能力状态查询。
diff --git a/packages/lsp/lsp/src/types.ts b/packages/lsp/lsp/src/types.ts
index d0c84f606d..d1bebe2a58 100644
--- a/packages/lsp/lsp/src/types.ts
+++ b/packages/lsp/lsp/src/types.ts
@@ -77,13 +77,13 @@ export interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 export type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 
 /**
diff --git a/packages/lsp/lsp/tests/lsp.spec.ts b/packages/lsp/lsp/tests/lsp.spec.ts
index 77ea9687c7..86c9b0ac53 100644
--- a/packages/lsp/lsp/tests/lsp.spec.ts
+++ b/packages/lsp/lsp/tests/lsp.spec.ts
@@ -13,7 +13,7 @@ import Lsp, {
 function makeProvider(
   id: string,
   extensionToLanguage: Record<string, string>,
-  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' },
+  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' },
 ): LspProvider & { seen: LspProviderQuery[]; seenSignals: (AbortSignal | undefined)[] } {
   const seen: LspProviderQuery[] = []
   const seenSignals: (AbortSignal | undefined)[] = []
@@ -63,7 +63,7 @@ describe('Lsp registration', () => {
     const provider = makeProvider('ts', { '.ts': 'typescript' })
     const dispose = lsp.registerProvider(provider)
 
-    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     expect(provider.seen[0]).toMatchObject({ filePath: 'a.ts', languageId: 'typescript' })
 
     dispose()
@@ -148,7 +148,7 @@ describe('Lsp registration', () => {
     const py = makeProvider('py', { '.py': 'python' })
     lsp.registerProvider(ts)
     lsp.registerProvider(py)
-    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     await expect(lsp.query(query('a.ts', 'hover'))).resolves.toEqual(hover)
   })
 
@@ -172,7 +172,7 @@ describe('Lsp registration', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       inner.lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
     }, { inject: ['lsp'] }))
-    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     await fiber.dispose()
     await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
   })
diff --git a/packages/lsp/tool-lsp/README.i18n.yaml b/packages/lsp/tool-lsp/README.i18n.yaml
index e2e7c7517f..85a33f73af 100644
--- a/packages/lsp/tool-lsp/README.i18n.yaml
+++ b/packages/lsp/tool-lsp/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/lsp/tool-lsp/README.md
-README.md: 9b4130015ddf7e1cad6fa9a0e131be86f3bd4bcc
-README.zh.md: a3f59fb6e39bb6c19cc2ef06d0bc256633e75386
+README.md: 1e89abf22e853735c094d17047b2c946af210905
+README.zh.md: 396b4d22ada8761b17c01d0c40e4bb4cfe80ca67
diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md
index 9b4130015d..1e89abf22e 100644
--- a/packages/lsp/tool-lsp/README.md
+++ b/packages/lsp/tool-lsp/README.md
@@ -10,7 +10,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In
 
 `lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
 
-The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceRoot }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering then projects stable, file-grouped `path:line:character` entries relativized against the result's `resolvedWorkspaceRoot` (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
 
 ## Configuration
 
diff --git a/packages/lsp/tool-lsp/README.zh.md b/packages/lsp/tool-lsp/README.zh.md
index a3f59fb6e3..396b4d22ad 100644
--- a/packages/lsp/tool-lsp/README.zh.md
+++ b/packages/lsp/tool-lsp/README.zh.md
@@ -8,13 +8,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 工具
 
-`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、语言 ID、工作区根目录、限制、超时、初始化和可执行文件均不进入模型输入。
+`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
 
-该工具要求从会话 `header.cwd` 取得工作区根目录，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceRoot }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。Native 渲染随后投影出稳定的、按文件分组的 `path:line:character` 条目，并相对于结果的 `resolvedWorkspaceRoot`（提供方的规范根目录）而非会话 cwd；因此，即使 cwd 包含符号链接，工作区内的结果仍渲染为相对路径。`file:` URI 位于工作区内时成为工作区相对路径，位于工作区外时成为绝对路径，其他 URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
+该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
 
 ## 配置
 
-| 配置键 | 默认值 | 含义 |
+| Key | 默认值 | 含义 |
 |---|---|---|
 | `maxLocations` | `100` | 出现省略标记前可渲染位置的最大数量。 |
 | `maxResultChars` | `16000` | 完整渲染结果的最大长度，包括截断元数据。 |
@@ -40,7 +40,7 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### KV Cache 影响
 
-只要插件作用域与指引文本不变，前缀就保持稳定；激活或 dispose（资源释放）可能使从该区段起的复用失效。
+只要插件 scope 与指引文本不变，前缀就保持稳定；激活或释放可能使从该区段起的复用失效。
 
 ### 工具 schema
 
@@ -54,13 +54,13 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### KV Cache 影响
 
-只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或作用域限制可能使从第一个变化的 schema token 起的复用失效。
+只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或 scope 限制可能使从第一个变化的 schema token 起的复用失效。
 
 ### 结果
 
 #### 模型看到的内容
 
-按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响 Native／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
+按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响原生／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
 
 #### Token 影响
 
@@ -74,7 +74,7 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### 模型看到的内容
 
-无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，编辑器跟随定位会聚焦所查询的行，标题则保留列号。
+无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，跟随焦点对准查询行，标题则保留列号。
 
 #### Token 影响
 
@@ -86,5 +86,5 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 ## 已知限制与暂缓事项
 
-- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；不在符号上的位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；非 symbol 位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
 - **不承诺跨服务器完整性**：受支持的服务器仍可能根据索引就绪情况返回空或部分结果；该工具不承诺跨语言或服务器的完整性。
diff --git a/packages/lsp/tool-lsp/src/index.ts b/packages/lsp/tool-lsp/src/index.ts
index e47dbc87db..688b48b369 100644
--- a/packages/lsp/tool-lsp/src/index.ts
+++ b/packages/lsp/tool-lsp/src/index.ts
@@ -138,7 +138,7 @@ export function apply(ctx: Context, config: Config): void {
                   },
                 },
               },
-              resolvedWorkspaceRoot: { type: 'string', required: true },
+              resolvedWorkspaceUri: { type: 'string', required: true },
             },
           },
           {
@@ -167,7 +167,7 @@ export function apply(ctx: Context, config: Config): void {
       render: (_args, value) => {
         switch (value.kind) {
           case 'locations':
-            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceRoot, resolved.maxLocations, resolved.maxResultChars) }]
+            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceUri, resolved.maxLocations, resolved.maxResultChars) }]
           case 'hover':
             return [{ type: 'text', text: formatHover(value.hover, resolved.maxResultChars) }]
           /* v8 ignore next -- exhaustive over the output schema's closed union; unreachable. */
@@ -200,7 +200,7 @@ export function apply(ctx: Context, config: Config): void {
                 end: { line: location.range.end.line, character: location.range.end.character },
               },
             })),
-            resolvedWorkspaceRoot: result.resolvedWorkspaceRoot,
+            resolvedWorkspaceUri: result.resolvedWorkspaceUri,
           }
         case 'hover':
           return {
diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 215dfb60e6..3f49d1edfd 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -6,8 +6,6 @@
  * @module @deepseek-ai/dsh-tool-lsp/render
  */
 
-import { fileURLToPath } from 'node:url'
-import { isAbsolute, relative, sep } from 'node:path'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp'
 
@@ -74,17 +72,17 @@ function oneBased(value: number, name: string): number {
 /**
  * Render a locations result grouped by file, converting each zero-based location back to a one-based
  * `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path;
- * outside it, an absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+ * outside it, a URI-derived absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
  * appends an omission marker when it truncates by count, then applies the complete result cap.
  * @param locations - the seam's locations (possibly empty).
- * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
  * @param maxLocations - the cap before truncation.
  * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
  * @returns the rendered text; a distinct no-result line when there are none.
  */
 export function formatLocations(
   locations: readonly LspLocation[],
-  workspaceRoot: string,
+  workspaceUri: string,
   maxLocations: number,
   maxResultChars: number,
 ): string {
@@ -93,7 +91,7 @@ export function formatLocations(
   const omitted = locations.length - shown.length
   const grouped = new Map<string, string[]>()
   for (const location of shown) {
-    const path = renderUri(location.uri, workspaceRoot)
+    const path = renderUri(location.uri, workspaceUri)
     const line = location.range.start.line + 1
     const character = location.range.start.character + 1
     const entries = grouped.get(path) ?? []
@@ -128,27 +126,63 @@ function boundResult(text: string, maxChars: number, label: string): string {
 }
 
 /**
- * Resolve a location URI to a display path. A `file:` URI accepted by Node becomes workspace-relative
- * (inside) or absolute (outside); any other URI is returned verbatim.
+ * Resolve a location URI without applying the harness host's path rules. A valid `file:` URI becomes
+ * workspace-relative when it is under the provider's canonical workspace URI, or a URI-derived
+ * absolute path otherwise; malformed and non-`file:` URIs remain verbatim.
  * @param uri - the target URI from the seam.
- * @param workspaceRoot - the canonical workspace root.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
  * @returns the display path or the verbatim URI.
  */
-export function renderUri(uri: string, workspaceRoot: string): string {
+export function renderUri(uri: string, workspaceUri: string): string {
   if (!uri.startsWith('file:')) return uri
-  let absolute: string
+  let target: URL
+  let workspace: URL
   try {
-    absolute = fileURLToPath(uri)
+    target = new URL(uri)
+    workspace = new URL(workspaceUri)
   } catch {
-    // A malformed file: URI is not a path we can resolve; show it verbatim.
     return uri
   }
-  const rel = relative(workspaceRoot, absolute)
-  if (rel === '') return '.'
-  // A leading `..` SEGMENT (or an absolute rel) means outside the workspace; guard against a false
-  // positive on an in-workspace path whose first component merely starts with dots (e.g. `..gen/x`).
-  const outside = rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)
-  return outside ? absolute : rel.split(sep).join('/')
+  if (workspace.protocol !== 'file:') return uri
+  const targetSegments = decodeFileSegments(target)
+  const workspaceSegments = decodeFileSegments(workspace)
+  if (targetSegments === undefined || workspaceSegments === undefined) return uri
+  const sameAuthority = target.hostname === workspace.hostname
+  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
+  const inside = sameAuthority
+    && targetSegments.length >= workspaceSegments.length
+    && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
+  if (inside) {
+    const relative = targetSegments.slice(workspaceSegments.length)
+    return relative.length === 0 ? '.' : relative.join('/')
+  }
+  return absoluteUriPath(target, targetSegments, workspaceSegments)
+}
+
+/** Decode URI path segments while rejecting encoded separators that would change path structure. */
+function decodeFileSegments(url: URL): string[] | undefined {
+  try {
+    const decoded = url.pathname.split('/').map(segment => decodeURIComponent(segment))
+    if (decoded.some(segment => /[/\\\0]/u.test(segment))) return undefined
+    while (decoded.at(-1) === '') decoded.pop()
+    decoded.shift()
+    return decoded
+  } catch {
+    return undefined
+  }
+}
+
+/** Windows execution-world path segments are case-insensitive even on a non-Windows harness host. */
+function samePathSegment(left: string, right: string, windowsWorld: boolean): boolean {
+  return windowsWorld ? left.toUpperCase() === right.toUpperCase() : left === right
+}
+
+/** Render an external file URL according to the execution-world style implied by its workspace URI. */
+function absoluteUriPath(target: URL, segments: readonly string[], workspaceSegments: readonly string[]): string {
+  if (target.hostname.length > 0) return `//${target.hostname}/${segments.join('/')}`
+  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
+  if (windowsWorld && /^[A-Za-z]:$/.test(segments[0] ?? '')) return segments.join('/')
+  return `/${segments.join('/')}`
 }
 
 /**
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index 1fd0eeba51..9f87d663fb 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -14,6 +14,7 @@ import {
 import type { LspLocation } from '@deepseek-ai/dsh-lsp'
 
 const WS = resolve('/home/u/proj')
+const WS_URI = pathToFileURL(WS).href
 
 function loc(uri: string, line: number, character = 0): LspLocation {
   return { uri, range: { start: { line, character }, end: { line, character: character + 1 } } }
@@ -48,64 +49,84 @@ describe('parseLspArgs', () => {
 describe('renderUri', () => {
   it('relativizes a file: URI inside the workspace with forward slashes', () => {
     const uri = pathToFileURL(join(WS, 'src', 'a.ts')).href
-    expect(renderUri(uri, WS)).toBe('src/a.ts')
+    expect(renderUri(uri, WS_URI)).toBe('src/a.ts')
   })
 
   it('returns an absolute path for a file: URI outside the workspace', () => {
     const outside = resolve(WS, '..', 'other', 'lib', 'b.ts')
     const uri = pathToFileURL(outside).href
-    expect(renderUri(uri, WS)).toBe(outside)
+    expect(renderUri(uri, WS_URI)).toBe(outside)
   })
 
   it('renders the workspace root itself as "."', () => {
-    expect(renderUri(pathToFileURL(WS).href, WS)).toBe('.')
+    expect(renderUri(WS_URI, WS_URI)).toBe('.')
   })
 
   it('keeps an in-workspace path whose first segment starts with dots relative', () => {
     // `..generated` is a real in-workspace dir, not a parent escape; only a `..` segment is external.
     const uri = pathToFileURL(join(WS, '..generated', 'a.ts')).href
-    expect(renderUri(uri, WS)).toBe('..generated/a.ts')
+    expect(renderUri(uri, WS_URI)).toBe('..generated/a.ts')
+  })
+
+  it('relativizes Windows execution-world URIs on a non-Windows host', () => {
+    expect(renderUri('file:///C:/WORKSPACE/src/a.ts', 'file:///c:/workspace')).toBe('src/a.ts')
+    expect(renderUri('file:///D:/lib/b.ts', 'file:///C:/workspace')).toBe('D:/lib/b.ts')
+  })
+
+  it('renders remote file authorities without host path conversion', () => {
+    expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
+    expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
+    expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
+  })
+
+  it('keeps malformed or mismatched URI coordinates verbatim', () => {
+    expect(renderUri('file://[', WS_URI)).toBe('file://[')
+    expect(renderUri('file:///a.ts', 'https://example.com/workspace')).toBe('file:///a.ts')
+    expect(renderUri('file:///a.ts', 'file:///bad%ZZ')).toBe('file:///a.ts')
+    expect(renderUri('file:///bad%5Cpath', WS_URI)).toBe('file:///bad%5Cpath')
+    expect(renderUri('file:///short', 'file:///short/deeper')).toBe('/short')
+    expect(renderUri('file:///', 'file:///C:/workspace')).toBe('/')
   })
 
   it('keeps a non-file URI verbatim', () => {
-    expect(renderUri('untitled:Untitled-1', WS)).toBe('untitled:Untitled-1')
-    expect(renderUri('jdt://contents/Foo.class', WS)).toBe('jdt://contents/Foo.class')
+    expect(renderUri('untitled:Untitled-1', WS_URI)).toBe('untitled:Untitled-1')
+    expect(renderUri('jdt://contents/Foo.class', WS_URI)).toBe('jdt://contents/Foo.class')
   })
 
   it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
     // An encoded path separator is invalid on every platform and must remain verbatim.
-    expect(renderUri('file:///bad%2Fpath', WS)).toBe('file:///bad%2Fpath')
+    expect(renderUri('file:///bad%2Fpath', WS_URI)).toBe('file:///bad%2Fpath')
   })
 })
 
 describe('formatLocations', () => {
   it('renders a no-result line for an empty list', () => {
-    expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
+    expect(formatLocations([], WS_URI, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
   })
 
   it('renders one-based path:line:character grouped by file', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS_URI, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toBe('a.ts:1:1\na.ts:5:3')
   })
 
   it('caps at maxLocations and marks the omission', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
     const many = Array.from({ length: 5 }, (_, i) => loc(a, i))
-    const text = formatLocations(many, WS, 2, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations(many, WS_URI, 2, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toContain('a.ts:1:1')
     expect(text).toContain('3 more locations omitted (limit 2).')
   })
 
   it('uses the singular omission marker for exactly one extra', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations([loc(a, 0), loc(a, 1)], WS_URI, 1, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toContain('1 more location omitted (limit 1).')
   })
 
   it('caps the complete location text even when one URI is enormous', () => {
     const maxResultChars = 80
-    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS, 1, maxResultChars)
+    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS_URI, 1, maxResultChars)
     expect(text).toHaveLength(maxResultChars)
     expect(text).toContain('locations truncated')
   })
diff --git a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
index de7a5319ef..846bd702ea 100644
--- a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
+++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
@@ -44,6 +44,7 @@ let seq = 0
 const testToolSignal = new AbortController().signal
 const workspaceRoot = resolve('/virtual/workspace')
 const resolvedWorkspaceRoot = resolve('/virtual/real-workspace')
+const resolvedWorkspaceUri = pathToFileURL(resolvedWorkspaceRoot).href
 const workspaceAlias = resolve('/virtual/workspace-alias')
 /** `cwd: null` means "no agent" (tests LSP_WORKSPACE_REQUIRED); a string is the session cwd. */
 function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
@@ -59,7 +60,7 @@ function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
 const okLocations: LspQueryResult = {
   kind: 'locations',
   locations: [{ uri: pathToFileURL(join(workspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-  resolvedWorkspaceRoot: workspaceRoot,
+  resolvedWorkspaceUri: pathToFileURL(workspaceRoot).href,
 }
 
 describe('tool-lsp registration', () => {
@@ -138,7 +139,7 @@ describe('tool-lsp execution', () => {
     const { ctx } = await mount(stubProvider(() => ({
       kind: 'locations',
       locations,
-      resolvedWorkspaceRoot: cappedWorkspaceRoot,
+      resolvedWorkspaceUri: pathToFileURL(cappedWorkspaceRoot).href,
     })), { maxLocations: 1 })
     const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, cappedWorkspaceRoot)
     expect(result.content[0]).toEqual({
@@ -147,17 +148,17 @@ describe('tool-lsp execution', () => {
     })
     expect(result).toMatchObject({
       isError: false,
-      value: { kind: 'locations', locations, resolvedWorkspaceRoot: cappedWorkspaceRoot },
+      value: { kind: 'locations', locations, resolvedWorkspaceUri: pathToFileURL(cappedWorkspaceRoot).href },
     })
   })
 
-  it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => {
+  it('relativizes against the provider resolvedWorkspaceUri, not the session cwd', async () => {
     // A symlinked session cwd resolves to the real path that contains the provider's location URIs.
     // Relativizing against the alias would misclassify the location as external.
     const provider = stubProvider(() => ({
       kind: 'locations',
       locations: [{ uri: pathToFileURL(join(resolvedWorkspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-      resolvedWorkspaceRoot,
+      resolvedWorkspaceUri,
     }))
     const { ctx } = await mount(provider)
     const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceAlias)

From 587fff9fe79170905352ee8639996f623e929158 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 04:43:54 +0800
Subject: [PATCH 050/262] fix(runtime): honor platform quiescence semantics

---
 packages/pty/pty-local/tests/local.spec.ts    | 20 ++++-
 .../subprocess/subprocess-local/src/spawn.ts  | 84 ++++++-------------
 .../subprocess-local/tests/local.spec.ts      |  8 +-
 3 files changed, 48 insertions(+), 64 deletions(-)

diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index df05438864..1c0de1660a 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -98,6 +98,22 @@ function expectReadyForNextSend(waitReason: string): void {
   expect(['stdin_read', 'inferred_idle']).toContain(waitReason)
 }
 
+function processIsRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+  } catch (_missingProcess) {
+    return false
+  }
+  if (process.platform !== 'linux') return true
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const state = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/, 1)[0]
+    return !/^[ZXx]$/.test(state ?? '')
+  } catch (_unreadableProcEntry) {
+    return false
+  }
+}
+
 describe('pty-local real shell', () => {
   it('persists cwd and environment across sends, scrubs secrets, and closes', async () => {
     const previous = process.env.DSH_TEST_SECRET
@@ -156,7 +172,7 @@ describe('pty-local real shell', () => {
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
 
-  it('reaps a disowned same-session descendant after the shell exits naturally', async () => {
+  it('quiesces a disowned same-session descendant after the shell exits naturally', async () => {
     const { ctx, root, agent } = await harness('danger-full-access')
     const created = await ctx.pty.spawn(agent, { type: 'shell' })
     const pidFile = join(root, 'disowned.pid')
@@ -185,7 +201,7 @@ describe('pty-local real shell', () => {
       }
       expect(ctx.pty.list(agent)[0]?.status.kind).toBe('exited')
       await ctx.pty.kill(agent, created.sessionId)
-      expect(() => process.kill(childPid, 0)).toThrow()
+      expect(processIsRunning(childPid)).toBe(false)
     } finally {
       if (pid !== undefined) {
         try {
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index 462da41382..feb0ed0767 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -15,7 +15,6 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout as sleepMs } from 'node:timers/promises'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   CollectedOutput,
   SubprocessCollect,
@@ -26,14 +25,23 @@ import type {
 } from '@deepseek-ai/dsh-subprocess'
 
 /**
- * Build a child environment: explicit caller entries merge after the scrubbed
- * parent base. A string deliberately restores or overrides an entry; an
- * explicit `undefined` tombstone removes an ordinary ambient entry.
- * @param extra - explicit caller entries and tombstones, merged after the scrub.
+ * Build a child environment: explicit caller entries override the scrubbed
+ * parent base using the target platform's environment-key semantics, so a
+ * deliberately supplied credential or current `DSH_*` fact wins over the
+ * scrub that dropped its ambient namesake.
+ * @param extra - explicit caller entries merged after the scrubbed parent.
  * @returns the environment to hand to `spawn` for the child process.
  */
-export function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
-  return { ...scrubbedParentEnv(), ...extra }
+export function childEnv(extra?: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+  const env = scrubbedParentEnv()
+  if (process.platform !== 'win32') return { ...env, ...extra }
+  let entries = Object.entries(env)
+  for (const [key, value] of Object.entries(extra ?? {})) {
+    const normalized = key.toUpperCase()
+    entries = entries.filter(([inherited]) => inherited.toUpperCase() !== normalized)
+    entries.push([key, value])
+  }
+  return Object.fromEntries(entries)
 }
 
 /** Injectable knobs so tests can exercise spill and platform behavior deterministically. */
@@ -299,12 +307,8 @@ function signalTree(
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param internals - test-only spill-directory, platform, and taskkill overrides.
  * @returns live subprocess handle.
- * @throws when `graceMs` cannot be represented by one Node timer.
  */
 export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): SubprocessHandle {
-  if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0 || spec.graceMs > MAX_TIMER_DELAY_MS) {
-    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
-  }
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
@@ -346,9 +350,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const stdoutCollector = collectStream(outMode, child.stdout, 'stdout')
   const stderrCollector = collectStream(errMode, child.stderr, 'stderr')
 
-  let graceTimer: ReturnType<typeof setTimeout> | undefined
-  let treeExitObserved = false
-  let treeExitObservation: Promise<void> | undefined
+  let graceTimer: NodeJS.Timeout | undefined
   let settled = false
 
   // Failed spawns use pid -1 so signalling remains a no-op.
@@ -356,9 +358,6 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
 
   /** Whether the detached tree's root (or POSIX group) is still alive. */
   const treeAlive = (): boolean => {
-    /* v8 ignore next -- only a timer callback already queued when the observer settles can enter here;
-       the guard is the final defense against probing an id after its tree was confirmed absent. */
-    if (treeExitObserved) return false
     if (pid <= 0) return false
     if (platform === 'win32') {
       // Windows has no group-liveness probe; the direct child's exit is the
@@ -381,40 +380,19 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
   }
 
-  /**
-   * Start or reuse the handle's single whole-tree exit observer. The first
-   * confirmed absence is a permanent no-more-signals boundary: it cancels a
-   * pending escalation before this process-group id can be reused.
-   */
-  const observeTreeExit = (): Promise<void> => {
-    treeExitObservation ??= (async () => {
-      while (treeAlive()) await sleepTick()
-      treeExitObserved = true
-      if (graceTimer !== undefined) clearTimeout(graceTimer)
-      graceTimer = undefined
-    })()
-    return treeExitObservation
-  }
-
   // The escalation's tier primitive (not on the handle — terminate() is the
   // only consumer-facing termination verb). Guards on TREE liveness, not
   // outcome settlement: a TERM-trapping helper can outlive the settled direct
   // child and must stay signalable, while a fully-dead tree (possible pid
   // reuse) must not be re-signalled by a later tier.
   const kill = (sig: NodeJS.Signals): void => {
-    /* v8 ignore next -- the shared exit observer cancels the ordinary dead-tree timer;
-       this remains the timer/death race guard and cannot be staged deterministically. */
     if (!treeAlive()) return
     signalTree(platform, pid, sig, child, taskkill)
   }
 
   const terminate = (): void => {
-    if (treeExitObserved || graceTimer !== undefined) return
-    // Observe from the first termination tier onward, even when inherited
-    // pipes delay `done` and no consumer has begun its own teardown wait.
-    void observeTreeExit()
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await.
-    if (treeExitObserved) return
+    if (graceTimer !== undefined) return // escalation already in flight
+    if (!treeAlive()) return
     kill('SIGTERM')
     // The escalation must survive direct-child settlement — the leader dying
     // does not mean the tree died — so settle does not clear this timer, and
@@ -436,7 +414,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   }
 
   const done = new Promise<SubprocessOutcome>((resolve, reject) => {
-    let pipeDrainTimer: ReturnType<typeof setTimeout> | undefined
+    let pipeDrainTimer: NodeJS.Timeout | undefined
     const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
       if (settled) return
       settled = true
@@ -459,9 +437,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
       // A surviving descendant that inherited a pipe must not hold the
       // outcome open indefinitely: after exit, the same bounded grace that
       // governs kills also bounds the close wait.
-      pipeDrainTimer = setTimeout(() => {
-        settle(exitCode, signal)
-      }, spec.graceMs)
+      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
     })
     child.on('close', settle)
     function cleanup(): void {
@@ -473,23 +449,11 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   })
 
   const waitForExit = async (signal?: AbortSignal): Promise<boolean> => {
-    const observed = observeTreeExit()
-    if (treeExitObserved) return true
-    if (signal?.aborted) return false
-    if (signal === undefined) {
-      await observed
-      return true
-    }
-    const aborted = Promise.withResolvers<boolean>()
-    const onAbort = (): void => { aborted.resolve(false) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    /* v8 ignore next -- closes the event-loop race between the preceding aborted check and listener registration. */
-    if (signal.aborted) onAbort()
-    try {
-      return await Promise.race([observed.then(() => true), aborted.promise])
-    } finally {
-      signal.removeEventListener('abort', onAbort)
+    while (treeAlive()) {
+      if (signal?.aborted) return false
+      await sleepTick()
     }
+    return true
   }
 
   return {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 4662283aad..b2ebfcfed0 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -5,6 +5,7 @@ import { basename, delimiter, dirname, relative } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { childEnv } from '../src/spawn.ts'
 
 function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): SubprocessSpawnSpec {
   return {
@@ -62,8 +63,11 @@ describe('LocalSubprocessService', () => {
     }).executableCandidates.bind(service)
     const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     try {
-      expect(candidates('tool', { Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' }))
-        .toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
+      expect(Object.keys(childEnv()).filter(key => key.toUpperCase() === 'PATH')).toHaveLength(1)
+      const explicit = childEnv({ Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' })
+      expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATH')).toEqual(['Path'])
+      expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATHEXT')).toEqual(['PathExt'])
+      expect(candidates('tool', explicit)).toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
       expect(candidates('tool', { Path: '/ambient', PATH: '/explicit', PATHEXT: '.EXE' }))
         .toEqual(['/explicit/tool.EXE'])
       expect(candidates('tool.exe', {})).toEqual([])

From f5f40c740377d37a7da1bb1e0c8143b9d3201ca7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:20:40 +0800
Subject: [PATCH 051/262] fix(pty): discard pre-write readiness evidence

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 13 ++++++---
 packages/pty/pty-local/tests/session.spec.ts  | 27 +++++++++++++++++++
 8 files changed, 44 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 1033fffcc6..30e672416a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 6f75778398e8f204c85b64fe096838a3b62d398e
-2026-07-28-portable-execution-world-consumers.zh.md: 22edc591f7716a92fd2a68d74c84168189743fbd
+2026-07-28-portable-execution-world-consumers.md: ccb7a13a9677c106976efbe95629d0d2c027b982
+2026-07-28-portable-execution-world-consumers.zh.md: 0a7b840049a826a47f4dc0476e5991bfd0578970
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 6f75778398..ccb7a13a96 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 22edc591f7..0a7b840049 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 05e9b904f9..4c153eff47 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 7d0cd2c26c6c58a64ae9d5fe5598c8aa6ff62915
-README.zh.md: 0b8216a9f599c224bd2888eb428213c9d725a338
+README.md: 74dfd7f59d45649f6daf0b42408285d9ede830a7
+README.zh.md: 2c7780f7e7db896c959e017dc39299e0e16f187d
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 7d0cd2c26c..74dfd7f59d 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the session's send slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 0b8216a9f5..2c7780f7e7 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 03809aec9f..d780719c54 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -227,10 +227,7 @@ export class LocalPtySession implements PtyBackendSession {
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
-    this.promptTail = ''
+    this.resetReadinessEvidence()
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
@@ -251,6 +248,7 @@ export class LocalPtySession implements PtyBackendSession {
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
       if (input.length > 0 && !operation.cancelRequested) {
+        this.resetReadinessEvidence()
         this.writing = operation
         try {
           await this.terminal.write(Buffer.from(input, 'utf8'))
@@ -276,6 +274,13 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
+  private resetReadinessEvidence(): void {
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    this.promptTail = ''
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 5f0065d0ee..40c60c570d 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -168,6 +168,29 @@ describe('LocalPtySession readiness and output', () => {
     expect((await operation.done).waitReason).toBe('stdin_read')
   })
 
+  it('discards prompt readiness observed during asynchronous pre-write inspection', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const operation = session.startSend({ text: 'long-running-command', submit: true })
+    let settled = false
+    void operation.done.then(() => { settled = true })
+
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    inspection.resolve({ processGroupId: 456, inputWaiting: true })
+    await vi.advanceTimersByTimeAsync(20)
+    expect(terminal.writes).toEqual(['long-running-command\r'])
+    expect(settled).toBe(false)
+
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect((await operation.done).waitReason).toBe('stdin_read')
+  })
+
   it('captures prompt MOTD, writes submit explicitly, and settles exact stdin waits', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -524,6 +547,8 @@ describe('LocalPtySession readiness and output', () => {
     const operation = session.startSend({ text: 'run', submit: true })
     let settled = false
     void operation.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
     inspector.pgid = 789
     terminal.emitData('\x1b]133;D;0\x07dsh> ')
     await vi.advanceTimersByTimeAsync(50)
@@ -545,6 +570,8 @@ describe('LocalPtySession readiness and output', () => {
     const operation = session.startSend({ text: 'run', submit: true })
     let settled = false
     void operation.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
     inspector.pgid = 789
     terminal.emitData('\x1b]133;D;0\x07dsh> ')
     // One poll past the silence bound would already have settled inferred_idle.

From ea75333c92e815a633664323dcd41565c83c4565 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:32:54 +0800
Subject: [PATCH 052/262] fix(lsp): compare UNC paths case-insensitively

---
 packages/lsp/tool-lsp/src/render.ts        | 7 ++++++-
 packages/lsp/tool-lsp/tests/render.spec.ts | 2 ++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 3f49d1edfd..4613312c87 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -148,7 +148,7 @@ export function renderUri(uri: string, workspaceUri: string): string {
   const workspaceSegments = decodeFileSegments(workspace)
   if (targetSegments === undefined || workspaceSegments === undefined) return uri
   const sameAuthority = target.hostname === workspace.hostname
-  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
+  const windowsWorld = isWindowsFileWorld(workspace, workspaceSegments)
   const inside = sameAuthority
     && targetSegments.length >= workspaceSegments.length
     && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
@@ -159,6 +159,11 @@ export function renderUri(uri: string, workspaceUri: string): string {
   return absoluteUriPath(target, targetSegments, workspaceSegments)
 }
 
+/** Whether a canonical file URI names a drive path or UNC path in a Windows execution world. */
+function isWindowsFileWorld(url: URL, segments: readonly string[]): boolean {
+  return url.hostname.length > 0 || /^[A-Za-z]:$/.test(segments[0] ?? '')
+}
+
 /** Decode URI path segments while rejecting encoded separators that would change path structure. */
 function decodeFileSegments(url: URL): string[] | undefined {
   try {
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index 9f87d663fb..d76600ea6f 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -75,8 +75,10 @@ describe('renderUri', () => {
 
   it('renders remote file authorities without host path conversion', () => {
     expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
+    expect(renderUri('file://SERVER/share/workspace/src/A.ts', 'file://server/Share/Workspace')).toBe('src/A.ts')
     expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
     expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
+    expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
   })
 
   it('keeps malformed or mismatched URI coordinates verbatim', () => {

From d29c73ddd6cbd4d5f4e8feab980f06961f5414f8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:04:36 +0800
Subject: [PATCH 053/262] fix(subprocess): treat zombie-only groups as
 quiescent

---
 .../subprocess-local/src/process-inspector.ts | 29 +++++++++++++++++++
 .../subprocess/subprocess-local/src/spawn.ts  |  9 ++++++
 .../tests/process-inspector.spec.ts           | 21 +++++++++++++-
 .../subprocess-local/tests/spawn.spec.ts      | 18 ++++++++++++
 4 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/packages/subprocess/subprocess-local/src/process-inspector.ts b/packages/subprocess/subprocess-local/src/process-inspector.ts
index 48b01e18e3..f31de010de 100644
--- a/packages/subprocess/subprocess-local/src/process-inspector.ts
+++ b/packages/subprocess/subprocess-local/src/process-inspector.ts
@@ -87,6 +87,35 @@ function readLinuxStat(internals: ProcessInspectorInternals, pid: number): ProcS
   }
 }
 
+/**
+ * Report whether a Linux process group has an executing member. `false`
+ * means the group contains only zombie/dead entries; `undefined` means the
+ * process table could not prove either outcome.
+ * @param processGroupId - POSIX process-group id to inspect.
+ * @param internals - injectable process-table operations.
+ * @returns Live-member presence, or `undefined` when unavailable/absent.
+ */
+export function linuxProcessGroupHasLiveMembers(
+  processGroupId: number,
+  internals: ProcessInspectorInternals = DEFAULT_INTERNALS,
+): boolean | undefined {
+  let entries: string[]
+  try {
+    entries = internals.readDir('/proc')
+  } catch (_unreadableProcDirectory) {
+    return undefined
+  }
+  let matched = false
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue
+    const stat = readLinuxStat(internals, Number(entry))
+    if (stat?.pgrp !== processGroupId) continue
+    matched = true
+    if (!/^[ZXx]$/.test(stat.state)) return true
+  }
+  return matched ? false : undefined
+}
+
 function numericEntries(internals: ProcessInspectorInternals, path: string): number[] {
   try {
     return internals.readDir(path).filter(entry => /^\d+$/.test(entry)).map(Number)
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index feb0ed0767..9fa70250dc 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -23,6 +23,7 @@ import type {
   SubprocessOutputMode,
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
+import { linuxProcessGroupHasLiveMembers } from './process-inspector.ts'
 
 /**
  * Build a child environment: explicit caller entries override the scrubbed
@@ -52,6 +53,8 @@ export interface SpawnInternals {
   taskkill?: (pid: number) => void
   /** Host platform override for signalling decisions. */
   platform?: NodeJS.Platform
+  /** Linux process-group member probe (defaults to `/proc` inspection). */
+  linuxProcessGroupHasLiveMembers?: (processGroupId: number) => boolean | undefined
 }
 
 /**
@@ -312,6 +315,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
+  const linuxGroupHasLiveMembers = internals.linuxProcessGroupHasLiveMembers ?? linuxProcessGroupHasLiveMembers
 
   if (spec.signal?.aborted) {
     throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
@@ -366,6 +370,11 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
     try {
       process.kill(-pid, 0)
+      // A group containing only unreaped zombies still answers kill(0), but
+      // it can execute no work and cannot be signalled into quiescence. Only
+      // inspect after direct-child settlement so live-process polls remain a
+      // syscall rather than repeated process-table scans.
+      if (settled && platform === 'linux' && linuxGroupHasLiveMembers(pid) === false) return false
       return true
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code
diff --git a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
index bcc3ddb091..c90a7b3490 100644
--- a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
+import {
+  createProcessInspector,
+  linuxProcessGroupHasLiveMembers,
+  parseProcStat,
+} from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 
 function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1, state = 'S'): string {
@@ -63,6 +67,21 @@ function fakeInternals() {
 }
 
 describe('Linux process inspector', () => {
+  it('treats zombie-only process groups as quiescent and fails closed when unobservable', () => {
+    const fake = fakeInternals()
+    expect(linuxProcessGroupHasLiveMembers(77, fake.internals)).toBeUndefined()
+
+    fake.dirs.set('/proc', ['self', '10', '11', '12'])
+    fake.files.set('/proc/10/stat', stat(10, 77, 10, -1, '500', 1, 'Z'))
+    fake.files.set('/proc/11/stat', stat(11, 77, 10, -1, '501', 1, 'X'))
+    fake.files.set('/proc/12/stat', stat(12, 88, 12, -1, '502'))
+    expect(linuxProcessGroupHasLiveMembers(77, fake.internals)).toBe(false)
+    expect(linuxProcessGroupHasLiveMembers(99, fake.internals)).toBeUndefined()
+
+    fake.files.set('/proc/11/stat', stat(11, 77, 10, -1, '501'))
+    expect(linuxProcessGroupHasLiveMembers(77, fake.internals)).toBe(true)
+  })
+
   it('parses stat safely, captures only the rooted process tree, and signals identities', () => {
     expect(parseProcStat('bad')).toBeUndefined()
     expect(parseProcStat('1 () ')).toBeUndefined()
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 08b6b1dbf8..7d92447794 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -268,6 +268,24 @@ describe('spawnSubprocess', () => {
     expect(result.signal).toBe('SIGTERM')
   })
 
+  it('does not wait for a Linux group that has only zombie members', async () => {
+    const pidFile = join(spillDir, `zombie-group-${Date.now()}.pid`)
+    let hasLiveMembers = false
+    const running = spawnSubprocess(spec(`sleep 60 & echo $! > ${pidFile}; echo leader-done`, { graceMs: 100 }), {
+      platform: 'linux',
+      linuxProcessGroupHasLiveMembers: () => hasLiveMembers,
+    })
+    const descendant = await waitForPidFile(pidFile)
+    try {
+      await running.done
+      await expect(running.waitForExit()).resolves.toBe(true)
+    } finally {
+      hasLiveMembers = true
+      running.terminate()
+      await waitGone(descendant)
+    }
+  })
+
   it('bounds inherited-pipe draining after the shell exits', async () => {
     const pidFile = join(spillDir, `pipe-holder-${Date.now()}.pid`)
     const started = Date.now()

From 3572c65d57214cd66819239616b5238e3482bb13 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:04:49 +0800
Subject: [PATCH 054/262] fix(pty): join asynchronous terminal operations

---
 packages/pty/pty-local/src/session.ts        | 19 ++++++--
 packages/pty/pty-local/tests/session.spec.ts | 47 ++++++++++++++++++++
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index d780719c54..0fb9f4ab0b 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -165,6 +165,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private readonly terminalOperations = new Set<Promise<void>>()
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
@@ -237,10 +238,18 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeDeadlineTimer = setTimeout(() => {
       if (this.active === operation) this.settleActive('timeout', this.writing === operation)
     }, this.config.timeoutMs)
-    void this.beginSend(operation, request)
+    this.ownTerminalOperation(this.beginSend(operation, request))
     return operation
   }
 
+  /** Retain one contained provider operation until its asynchronous work finishes. */
+  private ownTerminalOperation(operation: Promise<void>): void {
+    const tracked = operation.finally(() => { this.terminalOperations.delete(tracked) })
+    this.terminalOperations.add(tracked)
+    // beginSend(), pollReadiness(), and interrupt() contain their own boundary errors.
+    void tracked
+  }
+
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
     try {
       const foreground = await this.terminal.inspectForeground()
@@ -398,7 +407,7 @@ export class LocalPtySession implements PtyBackendSession {
     if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = setTimeout(() => {
       this.activeTimer = undefined
-      void this.pollReadiness(operation)
+      this.ownTerminalOperation(this.pollReadiness(operation))
     }, delayMs)
   }
 
@@ -467,6 +476,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeTimer = undefined
     if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
     this.activeDeadlineTimer = undefined
+    this.pollingReady = undefined
   }
 
   private clearActive(): void {
@@ -493,9 +503,9 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    void this.terminal.signalForeground('SIGINT').catch((error: unknown) => {
+    this.ownTerminalOperation(this.terminal.signalForeground('SIGINT').then(() => {}, (error: unknown) => {
       if (this.active === operation) this.failActive(error, this.writing === operation)
-    })
+    }))
   }
 
   private async closeOnce(reason: string): Promise<void> {
@@ -508,6 +518,7 @@ export class LocalPtySession implements PtyBackendSession {
     if (!quiescent) {
       throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
     }
+    await Promise.all(this.terminalOperations)
     // Whole-session cleanup can fail before the top-level process exits. Wait
     // for it first so that failure is reported instead of blocking forever on
     // `done`; successful quiescence guarantees `done` can now settle status and
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 40c60c570d..c5fc354106 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -907,4 +907,51 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await closing
   })
 
+  it('does not finish close while a pre-write terminal operation is pending', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const operation = session.startSend({ text: 'must not run', submit: true })
+    const closing = session.close('pending inspection')
+    let closed = false
+    void closing.then(() => { closed = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(closed).toBe(false)
+
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await closing
+    expect(closed).toBe(true)
+    expect(terminal.writes).toEqual([])
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
+  it('does not finish close while a terminal write is pending', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const write = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await write.promise }
+    const operation = session.startSend({ text: 'pending write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    const closing = session.close('pending write')
+    let closed = false
+    void closing.then(() => { closed = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(closed).toBe(false)
+
+    write.resolve(undefined)
+    await closing
+    expect(closed).toBe(true)
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
 })

From f2a3cc450e988bdb36083f57f2fb0303b96b7e89 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:04:59 +0800
Subject: [PATCH 055/262] fix(lsp): retain drive syntax in UNC worlds

---
 packages/lsp/tool-lsp/src/render.ts        | 5 ++---
 packages/lsp/tool-lsp/tests/render.spec.ts | 1 +
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 4613312c87..1e73e7ec6a 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -156,7 +156,7 @@ export function renderUri(uri: string, workspaceUri: string): string {
     const relative = targetSegments.slice(workspaceSegments.length)
     return relative.length === 0 ? '.' : relative.join('/')
   }
-  return absoluteUriPath(target, targetSegments, workspaceSegments)
+  return absoluteUriPath(target, targetSegments, windowsWorld)
 }
 
 /** Whether a canonical file URI names a drive path or UNC path in a Windows execution world. */
@@ -183,9 +183,8 @@ function samePathSegment(left: string, right: string, windowsWorld: boolean): bo
 }
 
 /** Render an external file URL according to the execution-world style implied by its workspace URI. */
-function absoluteUriPath(target: URL, segments: readonly string[], workspaceSegments: readonly string[]): string {
+function absoluteUriPath(target: URL, segments: readonly string[], windowsWorld: boolean): string {
   if (target.hostname.length > 0) return `//${target.hostname}/${segments.join('/')}`
-  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
   if (windowsWorld && /^[A-Za-z]:$/.test(segments[0] ?? '')) return segments.join('/')
   return `/${segments.join('/')}`
 }
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index d76600ea6f..953f7ef4c1 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -77,6 +77,7 @@ describe('renderUri', () => {
     expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
     expect(renderUri('file://SERVER/share/workspace/src/A.ts', 'file://server/Share/Workspace')).toBe('src/A.ts')
     expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
+    expect(renderUri('file:///D:/lib/a.ts', 'file://server/share/workspace')).toBe('D:/lib/a.ts')
     expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
     expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
   })

From 4d96ff40affe56f7301930cb45c9ee990bfe567c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:23:30 +0800
Subject: [PATCH 056/262] docs(lsp): align canonical output field

---
 .../2026-07-20-canonical-tool-output-contract.i18n.yaml       | 4 ++--
 .../architecture/2026-07-20-canonical-tool-output-contract.md | 2 +-
 .../2026-07-20-canonical-tool-output-contract.zh.md           | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index f8ce3ee5f5..b8db543510 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.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 .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
-2026-07-20-canonical-tool-output-contract.md: b2de9480d2659153dfb8a76ee07438d12e5b07c3
-2026-07-20-canonical-tool-output-contract.zh.md: 1852ae849aec27ef3af28895e902d840af5de14d
+2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
+2026-07-20-canonical-tool-output-contract.zh.md: fd1e55eab38e5929a2dc104073b49f9de7a493e2
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
index b2de9480d2..2429e1c141 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
@@ -46,7 +46,7 @@ The first-party tools preserve their existing Native text while returning domain
 | `glob` | `{ paths: string[] }` |
 | `grep` | `{ matches: [{ path, lineNumber, line }] }` |
 | `web_search` / `web_fetch` | The normalized `WebSearchResult` / `WebFetchResult` |
-| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceRoot }` or `{ kind: "hover", hover }` |
+| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }` |
 | `bash` | `{ kind: "background", taskId }` or `{ kind: "foreground" } & BashRunResult` |
 | `terminal_open` / `terminal_list` / `terminal_send` / `terminal_read` / `terminal_signal` / `terminal_close` | Public session snapshots, bounded read/send DTOs, signal/close outcomes, or a background task handle |
 | `task_output` / `task_list` / `task_kill` | Public task snapshots without owner or notification bookkeeping |
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
index 1852ae849a..26653ea769 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -46,7 +46,7 @@ type ToolExecutionResult =
 | `glob` | `{ paths: string[] }` |
 | `grep` | `{ matches: [{ path, lineNumber, line }] }` |
 | `web_search` ／ `web_fetch` | 归一化后的 `WebSearchResult` ／ `WebFetchResult` |
-| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceRoot }` 或 `{ kind: "hover", hover }` |
+| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }` |
 | `bash` | `{ kind: "background", taskId }` 或 `{ kind: "foreground" } & BashRunResult` |
 | `terminal_open` ／ `terminal_list` ／ `terminal_send` ／ `terminal_read` ／ `terminal_signal` ／ `terminal_close` | 公开会话快照、有界的读取／发送 DTO、信号／关闭操作结果，或后台任务句柄 |
 | `task_output` ／ `task_list` ／ `task_kill` | 不含所有者或通知管理信息的公开任务快照 |

From 6e5d711099a1db4f14bf897a9416c705d9fd2d4f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:59:55 +0800
Subject: [PATCH 057/262] fix(lsp): cancel executable setup on disposal

---
 packages/lsp/lsp-local/src/index.ts           | 49 ++++++++++++++-----
 packages/lsp/lsp-local/tests/provider.spec.ts | 37 +++++++++++++-
 2 files changed, 72 insertions(+), 14 deletions(-)

diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index d12e8986fc..0d511588bd 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -117,21 +117,44 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
+  const setupAbort = new AbortController()
+  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
+    // An async plugin callback must observe its own disposal before Cordis can
+    // run effect cleanup, because unload otherwise waits for this callback.
+    if (fiber === ctx.fiber && fiber.uid === null) {
+      setupAbort.abort(new Error('lsp-local setup disposed'))
+    }
+  })
+
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = await Promise.all(entries.map(async ([providerId, rawConfig]) => {
-    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-    const resolved = rawConfig as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const executable = await ctx.subprocess.resolveExecutable(resolved.command, resolved.env)
-    return new LocalLspProvider(
-      providerId,
-      ctx.fs,
-      resolved,
-      executable,
-      spec => ctx.subprocess.spawn(spec),
-    )
-  }))
+  const providers = await (async () => {
+    try {
+      return await Promise.all(entries.map(async ([providerId, rawConfig]) => {
+        if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+        const resolved = rawConfig as ResolvedServerConfig
+        validateServerConfig(providerId, resolved)
+        const executable = await ctx.subprocess.resolveExecutable(
+          resolved.command,
+          resolved.env,
+          setupAbort.signal,
+        )
+        setupAbort.signal.throwIfAborted()
+        return new LocalLspProvider(
+          providerId,
+          ctx.fs,
+          resolved,
+          executable,
+          spec => ctx.subprocess.spawn(spec),
+        )
+      }))
+    } catch (error: unknown) {
+      setupAbort.abort(error)
+      throw error
+    } finally {
+      stopSetupCancellation()
+    }
+  })()
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index b0209e09b8..8d8a7ad356 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { chmod, mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
@@ -195,6 +195,41 @@ describe('lsp-local provider resolution', () => {
     await ctx.fiber.dispose()
   })
 
+  it('aborts executable resolution when disposed during setup', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const subprocess = ctx.subprocess
+    const lookupStarted = Promise.withResolvers<AbortSignal>()
+    vi.spyOn(subprocess, 'resolveExecutable').mockImplementation(async (_command, _env, signal) => {
+      if (signal === undefined) throw new Error('missing setup signal')
+      lookupStarted.resolve(signal)
+      return await new Promise<string>((_resolve, reject) => {
+        const onAbort = (): void => {
+          reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+        }
+        signal.addEventListener('abort', onAbort, { once: true })
+        if (signal.aborted) onAbort()
+      })
+    })
+
+    const loading = ctx.plugin(LspLocal, config('pending', {
+      command: 'pending-lsp',
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))
+    const signal = await lookupStarted.promise
+    const unrelated = await ctx.plugin(() => {})
+    await unrelated.dispose()
+    expect(signal.aborted).toBe(false)
+    const disposing = loading.dispose()
+
+    await expect(loading).rejects.toThrow('lsp-local setup disposed')
+    await expect(disposing).resolves.toBeUndefined()
+    expect(signal.aborted).toBe(true)
+    await ctx.fiber.dispose()
+  })
+
   it('rolls back earlier registrations when a later server conflicts', async () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)

From a95e01d8b02bc4882d840441b59d680b34d9ab39 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:08 +0800
Subject: [PATCH 058/262] fix(pty): detach cancellation before close drain

---
 packages/pty/pty-local/src/session.ts        |  5 ++++-
 packages/pty/pty-local/tests/session.spec.ts | 22 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 0fb9f4ab0b..267c7c17fc 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -518,13 +518,16 @@ export class LocalPtySession implements PtyBackendSession {
     if (!quiescent) {
       throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
     }
+    // Quiescence is the active send's terminal outcome. Detach its abort
+    // listener before snapshotting provider operations so no late interrupt
+    // can enter the owned set after the drain starts.
+    this.settleActive('session_exit')
     await Promise.all(this.terminalOperations)
     // Whole-session cleanup can fail before the top-level process exits. Wait
     // for it first so that failure is reported instead of blocking forever on
     // `done`; successful quiescence guarantees `done` can now settle status and
     // drain the terminal output.
     await this.completion
-    this.settleActive('session_exit')
     this.terminal.output.off('data', this.onTerminalData)
     this.terminal.output.off('end', this.onTerminalEnd)
     this.terminal.output.off('error', this.onTerminalError)
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index c5fc354106..cce384bf6b 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -954,4 +954,26 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     expect((await operation.done).waitReason).toBe('session_exit')
   })
 
+  it('detaches active cancellation before draining terminal operations', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const signalForeground = vi.spyOn(terminal, 'signalForeground')
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'pending inspection', submit: true, signal: controller.signal })
+    const closing = session.close('pending cancellation')
+    await Promise.resolve()
+    await Promise.resolve()
+
+    controller.abort('late cancellation')
+    expect(signalForeground).not.toHaveBeenCalled()
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await closing
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
 })

From 06a922490418f6dea751328e8ee0970762036d6e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:21 +0800
Subject: [PATCH 059/262] fix(subprocess): retain failed terminal cleanup

---
 .../subprocess/subprocess-local/src/index.ts  |  3 +-
 .../subprocess-local/tests/local.spec.ts      | 30 +++++++++++++++++--
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 4c5cad8018..6d7684eeeb 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -64,10 +64,9 @@ export class LocalSubprocessService extends SubprocessService {
         // an identity-fenced descendant survives escalation). Await the cleanup
         // transaction directly so disposal reports that failure rather than
         // waiting forever on `done`.
-        pending.push(terminal.waitForExit())
+        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
-      this.terminals.clear()
       await Promise.all(pending)
       await rm(this.runtimeRoot, { recursive: true, force: true })
     }, 'local subprocess teardown')
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index b2ebfcfed0..b772545f7f 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,6 +1,6 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
-import { stat } from 'node:fs/promises'
+import { rm, stat } from 'node:fs/promises'
 import { basename, delimiter, dirname, relative } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -108,10 +108,36 @@ describe('LocalSubprocessService', () => {
       terminate,
       waitForExit,
     }
-    ;(ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.add(terminal)
+    const terminals = (ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
+    terminals.add(terminal)
     await fiber.dispose()
     expect(terminate).toHaveBeenCalledOnce()
     expect(waitForExit).toHaveBeenCalledOnce()
+    expect(terminals.size).toBe(0)
+  })
+
+  it('retains an owned terminal when disposal cleanup rejects', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const service = ctx.subprocess
+    const runtimeRoot = service.runtimeRoot
+    const terminal: SubprocessTerminalHandle = {
+      pid: 1,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => undefined,
+      signalForeground: async () => 1,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('retryable cleanup failure') }),
+    }
+    const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
+    terminals.add(terminal)
+
+    await fiber.dispose()
+    expect(terminals).toEqual(new Set([terminal]))
+    expect((await stat(runtimeRoot)).isDirectory()).toBe(true)
+    await rm(runtimeRoot, { recursive: true, force: true })
   })
 
   it('releases a terminal after top-level exit reaches quiescence', async () => {

From ea047cc634bf1674f0d563a4f68d72a284e1b97e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:33 +0800
Subject: [PATCH 060/262] test(subprocess): accept zombie quiescence

---
 .../subprocess/subprocess-local/tests/spawn.spec.ts  | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 7d92447794..b9f0bf0321 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -60,7 +60,7 @@ function spec(command: string, overrides: SpecOverrides = {}) {
   }
 }
 
-/** Poll until a pid no longer exists (kill(pid, 0) throws ESRCH). */
+/** Poll until a pid no longer exists, or is only a zombie on Linux. */
 async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
   const deadline = Date.now() + timeoutMs
   while (Date.now() < deadline) {
@@ -69,6 +69,16 @@ async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
     } catch {
       return
     }
+    if (process.platform === 'linux') {
+      try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+        const state = stat.slice(stat.lastIndexOf(')') + 2, stat.lastIndexOf(')') + 3)
+        if (state === 'Z' || state === 'X') return
+      } catch (error: unknown) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+        throw error
+      }
+    }
     await new Promise(resolve => setTimeout(resolve, 20))
   }
   throw new Error(`pid ${pid} still alive after ${timeoutMs}ms`)

From 562cd154a827ee2fc619f9d246a31f3f927e87d9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:44 +0800
Subject: [PATCH 061/262] docs(lsp): remove resolved URI limitation

---
 packages/lsp/lsp-local/README.i18n.yaml | 4 ++--
 packages/lsp/lsp-local/README.md        | 1 -
 packages/lsp/lsp-local/README.zh.md     | 1 -
 3 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 1504e6f726..e2b67d46d9 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-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/lsp/lsp-local/README.md
-README.md: 2c5ab309f3557ad77696a881b41d164e65bd24fe
-README.zh.md: d4493832964a5ac0d804602c18774bb106ddcbd9
+README.md: 299a5282bbca0a6d517af9342c4101cbdae33d4c
+README.zh.md: edf706fdb424756aa43b303b018b11e3764c2559
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 2c5ab309f3..299a5282bb 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -55,6 +55,5 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
-- **Execution-world URI rendering** — the stdio host produces provider-owned `file:` URIs. The current model tool renders them with the harness host's path library, so a Windows harness paired with a POSIX remote execution world may show remote locations as URIs or non-native paths; protocol queries remain correct.
 - **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index d449383296..edf706fdb4 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -55,6 +55,5 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 ## 已知限制与暂缓事项
 
 - **不提供隔离策略**：这个包（package）信任配置的服务器，不会对其进程执行沙箱化；受限部署必须提供适当的进程／文件系统提供方，或包装同一执行环境的沙箱。
-- **执行环境 URI 渲染**：stdio 主机生成归提供方所有的 `file:` URI。当前面向模型的工具使用 harness 宿主的路径库渲染这些 URI，因此 Windows harness 与 POSIX 远程执行环境配对时，可能把远程位置显示为 URI 或非本机路径；协议查询仍然正确。
 - **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
 - **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent 会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到释放。

From f84f63ccd777aee8961f7631008a7f30a68faaa6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:26:21 +0800
Subject: [PATCH 062/262] test(runtime): finish zombie quiescence migration

---
 packages/lsp/lsp-local/tests/instance.spec.ts       | 13 +++++++++++--
 .../subprocess/subprocess-local/tests/spawn.spec.ts |  6 +++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 811f15c9fa..08bad67ae2 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
 import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -346,14 +347,22 @@ describe('LspInstance disposal', () => {
 function processAlive(pid: number): boolean {
   try {
     process.kill(pid, 0)
-    return true
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false
     throw error
   }
+  if (process.platform !== 'linux') return true
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const state = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/, 1)[0]
+    return !/^[ZXx]$/.test(state ?? '')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
 }
 
-/** Wait until a process id disappears so temporary-workspace cleanup cannot race handle release. */
+/** Wait until a process can no longer execute so temporary-workspace cleanup cannot race handle release. */
 async function waitForProcessExit(pid: number, timeoutMs = 3_000): Promise<void> {
   const started = Date.now()
   while (processAlive(pid)) {
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index b9f0bf0321..f28f741992 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -665,7 +665,7 @@ describe('tree-survivor escalation (terminate and bounded waits reach helpers th
     clearTimeout(timer)
     running.terminate()
     await expect(running.waitForExit()).resolves.toBe(true)
-    expect(() => process.kill(helper, 0)).toThrow()
+    await expect(waitGone(helper)).resolves.toBeUndefined()
   })
 
   it('service teardown awaits tree survivors, not just handle settlement', async () => {
@@ -682,8 +682,8 @@ describe('tree-survivor escalation (terminate and bounded waits reach helpers th
     const helper = await waitForPidFile(pidFile)
     await running.done
     await fiber.dispose()
-    // Teardown itself waited for the survivor to die.
-    expect(() => process.kill(helper, 0)).toThrow()
+    // Teardown itself waited for the survivor to become quiescent.
+    await expect(waitGone(helper)).resolves.toBeUndefined()
   })
 })
 

From 71e0eeac40231c943490c328bd71be3fafdadc9b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:28:50 +0800
Subject: [PATCH 063/262] fix(code-runtime): contain hostile boundary failures

---
 .../code-runtime-worker/src/runtime-host.ts   |  6 +++++-
 .../code-runtime-worker/tests/runtime.spec.ts | 21 +++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index 334bd82e38..474a058e9f 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -49,7 +49,11 @@ export type RuntimeBindingReply =
  * @returns the caller-facing diagnostic text.
  */
 export function runtimeErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
+  try {
+    return error instanceof Error ? error.message : String(error)
+  } catch {
+    return 'binding rejected with an unrenderable value'
+  }
 }
 
 /**
diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
index 54f58eb414..db2c167354 100644
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -597,6 +597,27 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
     expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
   })
 
+  it('contains binding rejections whose thrown values cannot be rendered', async () => {
+    const { runtime } = await setup()
+    const result = await runtime.run({
+      program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
+      bindings: tools({
+        bad: async () => {
+          const hostile = new Error('hidden')
+          Object.defineProperty(hostile, 'message', {
+            get() { throw new Error('message getter failed') },
+          })
+          throw hostile
+        },
+      }),
+    })
+    expect(result.value).toEqual({
+      name: 'ToolCallError',
+      toolName: 'bad',
+      message: 'binding rejected with an unrenderable value',
+    })
+  })
+
   it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
     const { runtime } = await setup()
     let calls = 0

From f61a4943bdad0874a662f6fbfb8389cc140fd38f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:29:01 +0800
Subject: [PATCH 064/262] fix(lsp): preserve POSIX backslash paths

---
 packages/lsp/tool-lsp/src/render.ts        | 5 +++--
 packages/lsp/tool-lsp/tests/render.spec.ts | 6 +++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 1e73e7ec6a..2f376707db 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -149,6 +149,7 @@ export function renderUri(uri: string, workspaceUri: string): string {
   if (targetSegments === undefined || workspaceSegments === undefined) return uri
   const sameAuthority = target.hostname === workspace.hostname
   const windowsWorld = isWindowsFileWorld(workspace, workspaceSegments)
+  if (windowsWorld && [...targetSegments, ...workspaceSegments].some(segment => segment.includes('\\'))) return uri
   const inside = sameAuthority
     && targetSegments.length >= workspaceSegments.length
     && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
@@ -164,11 +165,11 @@ function isWindowsFileWorld(url: URL, segments: readonly string[]): boolean {
   return url.hostname.length > 0 || /^[A-Za-z]:$/.test(segments[0] ?? '')
 }
 
-/** Decode URI path segments while rejecting encoded separators that would change path structure. */
+/** Decode URI path segments while rejecting encoded POSIX separators and NUL. */
 function decodeFileSegments(url: URL): string[] | undefined {
   try {
     const decoded = url.pathname.split('/').map(segment => decodeURIComponent(segment))
-    if (decoded.some(segment => /[/\\\0]/u.test(segment))) return undefined
+    if (decoded.some(segment => /[/\0]/u.test(segment))) return undefined
     while (decoded.at(-1) === '') decoded.pop()
     decoded.shift()
     return decoded
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index 953f7ef4c1..f09297d3d4 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -82,11 +82,15 @@ describe('renderUri', () => {
     expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
   })
 
+  it('preserves backslashes as ordinary POSIX filename characters', () => {
+    expect(renderUri('file:///home/u/proj/dir%5Cname/a.ts', WS_URI)).toBe('dir\\name/a.ts')
+  })
+
   it('keeps malformed or mismatched URI coordinates verbatim', () => {
     expect(renderUri('file://[', WS_URI)).toBe('file://[')
     expect(renderUri('file:///a.ts', 'https://example.com/workspace')).toBe('file:///a.ts')
     expect(renderUri('file:///a.ts', 'file:///bad%ZZ')).toBe('file:///a.ts')
-    expect(renderUri('file:///bad%5Cpath', WS_URI)).toBe('file:///bad%5Cpath')
+    expect(renderUri('file:///C:/workspace/bad%5Cpath', 'file:///C:/workspace')).toBe('file:///C:/workspace/bad%5Cpath')
     expect(renderUri('file:///short', 'file:///short/deeper')).toBe('/short')
     expect(renderUri('file:///', 'file:///C:/workspace')).toBe('/')
   })

From 098f826001cc407e785cc70d2f8a89a77cfa8002 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:02:17 +0800
Subject: [PATCH 065/262] fix(subprocess): honor teardown and PATH semantics

---
 .../subprocess/subprocess-local/src/index.ts  |  7 ++--
 .../subprocess-local/tests/local.spec.ts      | 36 ++++++++++++++-----
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 6d7684eeeb..80d0b4c76b 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -67,7 +67,10 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
-      await Promise.all(pending)
+      const outcomes = await Promise.allSettled(pending)
+      for (const outcome of outcomes) {
+        if (outcome.status === 'rejected') throw outcome.reason
+      }
       await rm(this.runtimeRoot, { recursive: true, force: true })
     }, 'local subprocess teardown')
   }
@@ -106,7 +109,7 @@ export class LocalSubprocessService extends SubprocessService {
       ? (environmentValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
-      directory === '' ? [] : extensions.map(extension => resolve(this.cwd, directory, command + extension)))
+      extensions.map(extension => resolve(this.cwd, directory, command + extension)))
   }
 
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index b772545f7f..46f3b14bea 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,7 +1,7 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { rm, stat } from 'node:fs/promises'
-import { basename, delimiter, dirname, relative } from 'node:path'
+import { basename, dirname, relative, resolve } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
@@ -42,6 +42,9 @@ describe('LocalSubprocessService', () => {
     expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
       PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
     })).toBe(process.execPath)
+    Reflect.set(ctx.subprocess, 'cwd', dirname(process.execPath))
+    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), { PATH: '' }))
+      .toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')
@@ -54,7 +57,7 @@ describe('LocalSubprocessService', () => {
     await fiber.dispose()
   })
 
-  it('builds Windows executable candidates without empty PATH entries', async () => {
+  it('builds Windows executable candidates with case-insensitive overrides', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess as LocalSubprocessService
@@ -64,13 +67,13 @@ describe('LocalSubprocessService', () => {
     const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     try {
       expect(Object.keys(childEnv()).filter(key => key.toUpperCase() === 'PATH')).toHaveLength(1)
-      const explicit = childEnv({ Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' })
+      const explicit = childEnv({ Path: '/bin', PathExt: '.EXE;.CMD' })
       expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATH')).toEqual(['Path'])
       expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATHEXT')).toEqual(['PathExt'])
       expect(candidates('tool', explicit)).toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
       expect(candidates('tool', { Path: '/ambient', PATH: '/explicit', PATHEXT: '.EXE' }))
         .toEqual(['/explicit/tool.EXE'])
-      expect(candidates('tool.exe', {})).toEqual([])
+      expect(candidates('tool.exe', {})).toEqual([resolve(process.cwd(), 'tool.exe')])
       expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
     } finally {
       platform.mockRestore()
@@ -116,12 +119,12 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('retains an owned terminal when disposal cleanup rejects', async () => {
+  it('waits for every terminal cleanup and retains rejections', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
     const runtimeRoot = service.runtimeRoot
-    const terminal: SubprocessTerminalHandle = {
+    const failedTerminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
       done: Promise.resolve({ exitCode: 0, signal: null }),
@@ -131,11 +134,26 @@ describe('LocalSubprocessService', () => {
       terminate: vi.fn(),
       waitForExit: vi.fn(async () => { throw new Error('retryable cleanup failure') }),
     }
+    let finishCleanup!: () => void
+    const cleanup = new Promise<boolean>((resolve) => {
+      finishCleanup = () => { resolve(true) }
+    })
+    const drainingTerminal: SubprocessTerminalHandle = {
+      ...failedTerminal,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(() => cleanup),
+    }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
-    terminals.add(terminal)
+    terminals.add(failedTerminal)
+    terminals.add(drainingTerminal)
 
-    await fiber.dispose()
-    expect(terminals).toEqual(new Set([terminal]))
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise(resolve => setImmediate(resolve))
+    expect(disposed).toBe(false)
+    finishCleanup()
+    await disposing
+    expect(terminals).toEqual(new Set([failedTerminal]))
     expect((await stat(runtimeRoot)).isDirectory()).toBe(true)
     await rm(runtimeRoot, { recursive: true, force: true })
   })

From 4d63552d009aad6e09c06f87c3a68e1b2a0e10ac Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:17:45 +0800
Subject: [PATCH 066/262] fix(lsp): preserve workspace cancellation reason

---
 packages/lsp/lsp-local/src/host.ts        |  5 ++++-
 packages/lsp/lsp-local/tests/host.spec.ts | 20 ++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index 3a2b9fbd7b..55e13ed307 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -42,7 +42,10 @@ export async function canonicalizeWorkspace(
     throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  const info = await fs.stat(target, signal)
+  const info = await fs.stat(target, signal).catch((error: unknown) => {
+    throwIfAborted(signal)
+    throw error
+  })
   throwIfAborted(signal)
   if (info?.type !== 'directory') {
     throw new Error(`workspace root "${workspaceRoot}" is not a directory`)
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index cd7ed87e17..3db9deb50a 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -57,11 +57,31 @@ describe('canonicalizeWorkspace', () => {
     await expect(canonicalizeWorkspace(fs, join(root, 'nope'))).rejects.toThrow(/not a directory/)
   })
 
+  it('wraps a provider failure while resolving the workspace', async () => {
+    fs.resolve = async () => { throw 'raw workspace resolve failure' }
+    await expect(canonicalizeWorkspace(fs, ws))
+      .rejects.toThrow(`workspace root "${ws}" cannot be resolved: raw workspace resolve failure`)
+  })
+
   it('rejects a non-directory workspace', async () => {
     const file = join(root, 'file.txt')
     await writeFile(file, 'x')
     await expect(canonicalizeWorkspace(fs, file)).rejects.toThrow(/not a directory/)
   })
+
+  it('normalizes workspace metadata cancellation and preserves other provider failures', async () => {
+    const providerFailure = new Error('workspace metadata failed')
+    fs.stat = async () => { throw providerFailure }
+    await expect(canonicalizeWorkspace(fs, ws)).rejects.toBe(providerFailure)
+
+    const controller = new AbortController()
+    fs.stat = async () => {
+      controller.abort(new Error('workspace metadata cancelled'))
+      throw providerFailure
+    }
+    await expect(canonicalizeWorkspace(fs, ws, controller.signal))
+      .rejects.toThrow('workspace metadata cancelled')
+  })
 })
 
 describe('readHostSource', () => {

From 0fec058a483a1dae658250878c149b4fafa04f65 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:52:37 +0800
Subject: [PATCH 067/262] fix(pty): retain send ownership through cancellation

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 24 +++++++--
 packages/pty/pty-local/tests/session.spec.ts  | 54 +++++++++++++++++++
 11 files changed, 87 insertions(+), 15 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 30e672416a..02545da311 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: ccb7a13a9677c106976efbe95629d0d2c027b982
-2026-07-28-portable-execution-world-consumers.zh.md: 0a7b840049a826a47f4dc0476e5991bfd0578970
+2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
+2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index ccb7a13a96..715529e5f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 0a7b840049..a9d864b581 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 8b33466ea7..2694664183 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: ef87c2806a237e6e6d44c1e62942146af24b8c19
-2026-07-16-persistent-pty-sessions.zh.md: 5f1bde39de5eca7aa57897d87c95675ce0da5abd
+2026-07-16-persistent-pty-sessions.md: f94dd57622c555e195564cc2eee9b3228841d5cc
+2026-07-16-persistent-pty-sessions.zh.md: 6228571a6496e9d4cb031a2df958b80dee102fd3
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index ef87c2806a..f94dd57622 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -60,7 +60,7 @@ The local subprocess terminal primitive uses only public `node-pty` capabilities
 
 The UI render contract is exact and location-free. `terminal_send` uses terminal call/result cards only for foreground sends; its background form is generic `execute`. `terminal_open`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list` use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. No PTY tool emits `locations`.
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. Cancellation marks queued input before signaling the real foreground group, so input cannot execute if an asynchronous pre-write inspection settles afterward. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
+`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. Cancellation marks queued input before signaling the real foreground group, so input cannot execute if an asynchronous pre-write inspection settles afterward. The canceled send retains its reservation until asynchronous foreground signalling settles, so a successor cannot become that signal's target. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
 
 Foreground sends return a bounded rendered delta and two independent facts: `waitReason` (`stdin_read | inferred_idle | timeout | session_exit`) and `sessionStatus` (`running` or `exited` with exit code or signal). `session_exit` refers to the PTY's top-level shell process, not an arbitrary foreground command whose status the shell consumes. A timeout never implies process exit. `dsh-tool-pty.maxResultBytes` defaults to 262144, rejects values below 64 so creation acknowledgements retain registry-issued ids, and caps each single-text UTF-8 result after normalized tool or pipeline errors, wait, session, pagination, truncation, generic task-status wrappers, policy denials or short-circuits, and post-execute replacements or blocks; the terminal definitions' last-mile `finalizeContent` callback leaves deliberately structured multi-block policy content unchanged. The renderer reserves suffix space and preserves code-point boundaries instead of treating the backend payload cap as the final model bound.
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 5f1bde39de..6228571a64 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -60,7 +60,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 
 UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
+`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。被取消的发送会保留其预留，直至异步前台信号发送结算，因此后续发送不会成为该信号的目标。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
 前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。`dsh-tool-pty.maxResultBytes` 默认为 262144；低于 64 的值会被拒绝，以确保创建确认保留 registry 签发的 id；每个单文本 UTF-8 结果在加入规范化的工具或流水线错误、等待、会话、分页、截断、通用 task 状态包装、策略拒绝或短路以及 post-execute 替换或阻断后，仍受该值限制；终端定义自有的末端 `finalizeContent` callback 会原样保留策略刻意返回的结构化多 block 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 4c153eff47..c89122066a 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 74dfd7f59d45649f6daf0b42408285d9ede830a7
-README.zh.md: 2c7780f7e7db896c959e017dc39299e0e16f187d
+README.md: 7e31adfbc486a190252be867e2113948b17e7924
+README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 74dfd7f59d..7e31adfbc4 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then reg
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the session's send slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 2c7780f7e7..eb628aef9a 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 267c7c17fc..922db21152 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,6 +166,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
+  private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
@@ -403,7 +404,7 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
-    if (this.active !== operation || this.polling) return
+    if (this.active !== operation || this.interrupting === operation || this.polling) return
     if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = setTimeout(() => {
       this.activeTimer = undefined
@@ -480,9 +481,11 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private clearActive(): void {
+    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    if (this.interrupting === operation) this.interrupting = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -503,9 +506,24 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.ownTerminalOperation(this.terminal.signalForeground('SIGINT').then(() => {}, (error: unknown) => {
+    this.interrupting = operation
+    this.stopPolling()
+    this.ownTerminalOperation(this.interruptOnce(operation))
+  }
+
+  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
+    try {
+      await this.terminal.signalForeground('SIGINT')
+    } catch (error: unknown) {
       if (this.active === operation) this.failActive(error, this.writing === operation)
-    }))
+      return
+    } finally {
+      if (this.interrupting === operation) this.interrupting = undefined
+    }
+    if (this.active === operation && !operation.settled && !this.closing && this.writing !== operation) {
+      this.pollingReady = operation
+      this.schedulePoll(operation, 0)
+    }
   }
 
   private async closeOnce(reason: string): Promise<void> {
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index cce384bf6b..513dcbbbb4 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -340,6 +340,60 @@ describe('LocalPtySession readiness and output', () => {
     await operation.done
   })
 
+  it('retains a canceled send until asynchronous foreground signalling settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const signalGate = Promise.withResolvers<undefined>()
+    terminal.signalForeground = async (signal) => {
+      await signalGate.promise
+      const foreground = await terminal.inspectForeground()
+      if (foreground === undefined) throw new Error('cannot resolve foreground')
+      inspector.signalGroup(foreground.processGroupId, signal)
+      return foreground.processGroupId
+    }
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow('active send')
+    signalGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
+  })
+
+  it('does not resume cancellation polling after the terminal exits during signalling', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const signalGate = Promise.withResolvers<undefined>()
+    terminal.signalForeground = async () => {
+      await signalGate.promise
+      return 456
+    }
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    terminal.emitExit(0)
+    await expect(operation.done).resolves.toMatchObject({ waitReason: 'session_exit' })
+
+    signalGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(10)
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: 0, signal: null })
+  })
+
   it('retains send ownership after timeout until an asynchronous provider write settles', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From be3533fa19438cea98daad5727eb1a21e44a3f03 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:53:27 +0800
Subject: [PATCH 068/262] fix(subprocess): clean runtime state after teardown
 failure

---
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  2 +-
 .../subprocess/subprocess-local/README.zh.md  |  2 +-
 .../subprocess/subprocess-local/src/index.ts  | 14 +++--
 .../subprocess-local/tests/local.spec.ts      | 53 ++++++++++++++++---
 5 files changed, 60 insertions(+), 15 deletions(-)

diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 72f3c93da9..efbb1612bd 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 38b26c33f3854acdb4a2bb48612da73361d727ba
-README.zh.md: fc4a5d4961fb7618b9db84b21063f907361a26d8
+README.md: 61ee8ff9e09d5177ff6d5b3805dd84fb74c59961
+README.zh.md: 06a8e4bdd225e212aa67817ebbf66581314ab2bf
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 38b26c33f3..61ee8ff9e0 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index fc4a5d4961..06a8e4bdd2 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -10,7 +10,7 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，在资源释放时删除；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
+- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 80d0b4c76b..0d71cb0e33 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -67,11 +67,15 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
-      const outcomes = await Promise.allSettled(pending)
-      for (const outcome of outcomes) {
-        if (outcome.status === 'rejected') throw outcome.reason
-      }
-      await rm(this.runtimeRoot, { recursive: true, force: true })
+      const outcomes = [
+        ...await Promise.allSettled(pending),
+        ...await Promise.allSettled([rm(this.runtimeRoot, { recursive: true, force: true })]),
+      ]
+      const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
+        ? [outcome.reason as unknown]
+        : [])
+      if (failures.length === 1) throw failures[0]
+      if (failures.length > 1) throw new AggregateError(failures, 'local subprocess teardown failed')
     }, 'local subprocess teardown')
   }
 
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 46f3b14bea..e4dd4cfb44 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,6 +1,6 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
-import { rm, stat } from 'node:fs/promises'
+import { stat } from 'node:fs/promises'
 import { basename, dirname, relative, resolve } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -119,11 +119,15 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('waits for every terminal cleanup and retains rejections', async () => {
+  it('waits for every terminal cleanup, removes runtime state, and retains rejections', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
     const runtimeRoot = service.runtimeRoot
+    const firstFailure = new Error('first retryable cleanup failure')
+    const secondFailure = new Error('second retryable cleanup failure')
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
     const failedTerminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
@@ -132,7 +136,12 @@ describe('LocalSubprocessService', () => {
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
       terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw new Error('retryable cleanup failure') }),
+      waitForExit: vi.fn(async () => { throw firstFailure }),
+    }
+    const secondFailedTerminal: SubprocessTerminalHandle = {
+      ...failedTerminal,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw secondFailure }),
     }
     let finishCleanup!: () => void
     const cleanup = new Promise<boolean>((resolve) => {
@@ -145,6 +154,7 @@ describe('LocalSubprocessService', () => {
     }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(failedTerminal)
+    terminals.add(secondFailedTerminal)
     terminals.add(drainingTerminal)
 
     let disposed = false
@@ -153,9 +163,40 @@ describe('LocalSubprocessService', () => {
     expect(disposed).toBe(false)
     finishCleanup()
     await disposing
-    expect(terminals).toEqual(new Set([failedTerminal]))
-    expect((await stat(runtimeRoot)).isDirectory()).toBe(true)
-    await rm(runtimeRoot, { recursive: true, force: true })
+    expect(terminals).toEqual(new Set([failedTerminal, secondFailedTerminal]))
+    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect(disposalErrors).toHaveLength(1)
+    expect(disposalErrors[0]).toMatchObject({
+      errors: [firstFailure, secondFailure],
+      message: 'local subprocess teardown failed',
+    })
+  })
+
+  it('reports one cleanup failure without wrapping it after removing runtime state', async () => {
+    const ctx = new Context()
+    const failure = new Error('single cleanup failure')
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const service = ctx.subprocess
+    const runtimeRoot = service.runtimeRoot
+    const terminal: SubprocessTerminalHandle = {
+      pid: 1,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => undefined,
+      signalForeground: async () => 1,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw failure }),
+    }
+    const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
+    terminals.add(terminal)
+
+    await fiber.dispose()
+
+    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect(disposalErrors).toEqual([failure])
   })
 
   it('releases a terminal after top-level exit reaches quiescence', async () => {

From d6b3de6e0da064f5b95e29a4134e30da39ab2d1a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 11:57:12 +0800
Subject: [PATCH 069/262] fix(pty): fence delayed signal prompts

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 16 +++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 29 +++++++++++++++++++
 8 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 02545da311..803a2f83fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
-2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
+2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
+2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 715529e5f2..54b8ec19bc 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index a9d864b581..f21be00fd3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index c89122066a..3f21fb2bd3 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 7e31adfbc486a190252be867e2113948b17e7924
-README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
+README.md: c7b7a363f22821363a0fed81982165fd35326d12
+README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 7e31adfbc4..c7b7a363f2 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index eb628aef9a..859b94e4f2 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 922db21152..65a10c36ea 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,6 +166,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
+  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
@@ -173,6 +174,7 @@ export class LocalPtySession implements PtyBackendSession {
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
+  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -317,6 +319,7 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.active !== undefined) this.signaledOperation = this.active
     const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
@@ -365,7 +368,9 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt) {
+    if (sanitized.prompt && this.delayedSignaledPrompt) {
+      this.delayedSignaledPrompt = false
+    } else if (sanitized.prompt) {
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -461,6 +466,13 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
+    // A signaled command can return by silence before bash emits its prompt.
+    // Reserve that marker so it cannot become successor readiness after echo.
+    const signaled = this.signaledOperation === operation
+    if (signaled) this.signaledOperation = undefined
+    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
+      this.delayedSignaledPrompt = true
+    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -486,6 +498,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
+    if (this.signaledOperation === operation) this.signaledOperation = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -506,6 +519,7 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.signaledOperation = operation
     this.interrupting = operation
     this.stopPolling()
     this.ownTerminalOperation(this.interruptOnce(operation))
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 513dcbbbb4..28ad58f04d 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -591,6 +591,35 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
+  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
+    await initialize(session, terminal)
+
+    const interrupted = session.startSend({ text: 'sleep', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await session.signal('SIGINT')
+    await vi.advanceTimersByTimeAsync(50)
+    expect((await interrupted.done).waitReason).toBe('inferred_idle')
+
+    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
+    let settled = false
+    void successor.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(false)
+
+    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    const result = await successor.done
+    expect(result.waitReason).toBe('stdin_read')
+    expect(result.viewport).toContain('PID=123')
+  })
+
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 277870dac275292ce12f1de060421ba9cfd24661 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 12:05:00 +0800
Subject: [PATCH 070/262] Revert "fix(pty): fence delayed signal prompts"

This reverts commit a78958eeeaf04a3acdf22ef8a26dec370661a51d.
---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 16 +---------
 packages/pty/pty-local/tests/session.spec.ts  | 29 -------------------
 8 files changed, 9 insertions(+), 52 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 803a2f83fe..02545da311 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
-2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
+2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
+2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 54b8ec19bc..715529e5f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index f21be00fd3..a9d864b581 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 3f21fb2bd3..c89122066a 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: c7b7a363f22821363a0fed81982165fd35326d12
-README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
+README.md: 7e31adfbc486a190252be867e2113948b17e7924
+README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index c7b7a363f2..7e31adfbc4 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 859b94e4f2..eb628aef9a 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 65a10c36ea..922db21152 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,7 +166,6 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
-  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
@@ -174,7 +173,6 @@ export class LocalPtySession implements PtyBackendSession {
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
-  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -319,7 +317,6 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
-    if (this.active !== undefined) this.signaledOperation = this.active
     const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
@@ -368,9 +365,7 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt && this.delayedSignaledPrompt) {
-      this.delayedSignaledPrompt = false
-    } else if (sanitized.prompt) {
+    if (sanitized.prompt) {
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -466,13 +461,6 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    // A signaled command can return by silence before bash emits its prompt.
-    // Reserve that marker so it cannot become successor readiness after echo.
-    const signaled = this.signaledOperation === operation
-    if (signaled) this.signaledOperation = undefined
-    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
-      this.delayedSignaledPrompt = true
-    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -498,7 +486,6 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
-    if (this.signaledOperation === operation) this.signaledOperation = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -519,7 +506,6 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.signaledOperation = operation
     this.interrupting = operation
     this.stopPolling()
     this.ownTerminalOperation(this.interruptOnce(operation))
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 28ad58f04d..513dcbbbb4 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -591,35 +591,6 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
-  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
-    await initialize(session, terminal)
-
-    const interrupted = session.startSend({ text: 'sleep', submit: true })
-    await Promise.resolve()
-    await Promise.resolve()
-    await session.signal('SIGINT')
-    await vi.advanceTimersByTimeAsync(50)
-    expect((await interrupted.done).waitReason).toBe('inferred_idle')
-
-    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
-    let settled = false
-    void successor.done.then(() => { settled = true })
-    await Promise.resolve()
-    await Promise.resolve()
-    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    expect(settled).toBe(false)
-
-    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    const result = await successor.done
-    expect(result.waitReason).toBe('stdin_read')
-    expect(result.viewport).toContain('PID=123')
-  })
-
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 7eedfda961d4e30e10b3d4756650bab402542d0f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 11:57:12 +0800
Subject: [PATCH 071/262] fix(pty): fence delayed signal prompts

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 16 +++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 29 +++++++++++++++++++
 8 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 02545da311..803a2f83fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
-2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
+2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
+2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 715529e5f2..54b8ec19bc 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index a9d864b581..f21be00fd3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index c89122066a..3f21fb2bd3 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 7e31adfbc486a190252be867e2113948b17e7924
-README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
+README.md: c7b7a363f22821363a0fed81982165fd35326d12
+README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 7e31adfbc4..c7b7a363f2 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index eb628aef9a..859b94e4f2 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 922db21152..65a10c36ea 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,6 +166,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
+  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
@@ -173,6 +174,7 @@ export class LocalPtySession implements PtyBackendSession {
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
+  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -317,6 +319,7 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.active !== undefined) this.signaledOperation = this.active
     const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
@@ -365,7 +368,9 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt) {
+    if (sanitized.prompt && this.delayedSignaledPrompt) {
+      this.delayedSignaledPrompt = false
+    } else if (sanitized.prompt) {
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -461,6 +466,13 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
+    // A signaled command can return by silence before bash emits its prompt.
+    // Reserve that marker so it cannot become successor readiness after echo.
+    const signaled = this.signaledOperation === operation
+    if (signaled) this.signaledOperation = undefined
+    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
+      this.delayedSignaledPrompt = true
+    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -486,6 +498,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
+    if (this.signaledOperation === operation) this.signaledOperation = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -506,6 +519,7 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.signaledOperation = operation
     this.interrupting = operation
     this.stopPolling()
     this.ownTerminalOperation(this.interruptOnce(operation))
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 513dcbbbb4..28ad58f04d 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -591,6 +591,35 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
+  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
+    await initialize(session, terminal)
+
+    const interrupted = session.startSend({ text: 'sleep', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await session.signal('SIGINT')
+    await vi.advanceTimersByTimeAsync(50)
+    expect((await interrupted.done).waitReason).toBe('inferred_idle')
+
+    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
+    let settled = false
+    void successor.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(false)
+
+    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    const result = await successor.done
+    expect(result.waitReason).toBe('stdin_read')
+    expect(result.viewport).toContain('PID=123')
+  })
+
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 727546ce6d8cb4a12294d63da5f9cb43ee19443f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 12:59:49 +0800
Subject: [PATCH 072/262] fix(code-runtime): bound every subprocess frame hop

---
 packages/code-runtime/code-runtime-worker/src/runtime-host.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index 474a058e9f..d2bb1082b8 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -223,4 +223,5 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+export { jsonValueBytesUpTo } from './output-json.ts'
 export type { WorkerJsonWire } from './worker-json.ts'

From 045e8462ee5ba25d14e399060a4ccb3c40f89c5d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:00:12 +0800
Subject: [PATCH 073/262] fix(pty): drain public signals during close

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 ++--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 ++--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 12 +++++++----
 packages/pty/pty-local/tests/session.spec.ts  | 20 +++++++++++++++++++
 8 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 803a2f83fe..fecaacac05 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
-2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
+2026-07-28-portable-execution-world-consumers.md: fe9d7bdd38199a031989b093fd3e9d931d62c80a
+2026-07-28-portable-execution-world-consumers.zh.md: 9f4f38e6e4c6c7dba74e8de4c260ec633dade910
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 54b8ec19bc..fe9d7bdd38 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals after shutdown begins and drains public signals already in flight before returning.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index f21be00fd3..9f4f38e6e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作开始后会拒绝新的公开信号，并在返回前等待所有已在途的公开信号结算。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 3f21fb2bd3..2bd653983e 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: c7b7a363f22821363a0fed81982165fd35326d12
-README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
+README.md: bccef05ca73ec8d826621f814f232206fa9fea4b
+README.zh.md: 27d4d1193047eb1bb3bf2289697be3c0cc0253aa
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index c7b7a363f2..bccef05ca7 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then reg
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close rejects new public signals after shutdown begins, drains public signals already in flight, starts provider-owned TERM-to-KILL whole-session cleanup, and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 859b94e4f2..27d4d11930 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作会在关闭开始后拒绝新的公开信号请求，等待已经在途的公开信号请求全部结算，再启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 65a10c36ea..08b42466aa 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -165,7 +165,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
-  private readonly terminalOperations = new Set<Promise<void>>()
+  private readonly terminalOperations = new Set<Promise<unknown>>()
   private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
@@ -247,10 +247,13 @@ export class LocalPtySession implements PtyBackendSession {
 
   /** Retain one contained provider operation until its asynchronous work finishes. */
   private ownTerminalOperation(operation: Promise<void>): void {
+    void this.trackTerminalOperation(operation)
+  }
+
+  private trackTerminalOperation<T>(operation: Promise<T>): Promise<T> {
     const tracked = operation.finally(() => { this.terminalOperations.delete(tracked) })
     this.terminalOperations.add(tracked)
-    // beginSend(), pollReadiness(), and interrupt() contain their own boundary errors.
-    void tracked
+    return tracked
   }
 
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
@@ -319,8 +322,9 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.closing) throw new Error('PTY session is closing')
     if (this.active !== undefined) this.signaledOperation = this.active
-    const targetPgid = await this.terminal.signalForeground(signal)
+    const targetPgid = await this.trackTerminalOperation(this.terminal.signalForeground(signal))
     return { delivered: true, targetPgid }
   }
 
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 28ad58f04d..dc03da2a63 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -952,6 +952,26 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
   })
 
+  it('drains an in-flight public signal and rejects signals after close starts', async () => {
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    const signal = Promise.withResolvers<number>()
+    terminal.signalForeground = async () => await signal.promise
+
+    const signaling = session.signal('SIGINT')
+    const closing = session.close('public signal')
+    let closed = false
+    void closing.then(() => { closed = true })
+    await Promise.resolve()
+    expect(closed).toBe(false)
+    await expect(session.signal('SIGTERM')).rejects.toThrow('closing')
+
+    signal.resolve(456)
+    await expect(signaling).resolves.toEqual({ delivered: true, targetPgid: 456 })
+    await closing
+    expect(closed).toBe(true)
+  })
+
   it('closes idempotently, contains signal races, and reports survivors', async () => {
     const terminal = new FakeTerminal()
     terminal.quiescent = false

From 4fecc549981ebb572ad25bed32b78aa123d0dd78 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:51:55 +0800
Subject: [PATCH 074/262] fix(runtime): close teardown gaps and simplify
 framing

---
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  4 +-
 .../2026-07-15-lsp-capability-seam.md         |  2 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  2 +-
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  6 +-
 ...8-portable-execution-world-consumers.zh.md |  6 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 +-
 .../feature/2026-06-15-code-mode.md           |  2 +-
 .../feature/2026-06-15-code-mode.zh.md        |  2 +-
 packages/lsp/lsp-local/README.i18n.yaml       |  4 +-
 packages/lsp/lsp-local/README.md              |  2 +-
 packages/lsp/lsp-local/README.zh.md           |  2 +-
 packages/lsp/lsp-local/src/index.ts           | 41 ++++++++++---
 .../lsp/lsp-local/tests/lifecycle.spec.ts     | 59 +++++++++++++++++++
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  2 +-
 .../subprocess/subprocess-local/README.zh.md  |  2 +-
 .../subprocess-local/src/terminal.ts          |  6 +-
 .../subprocess-local/tests/terminal.spec.ts   | 42 +++++++++++++
 packages/typert/README.i18n.yaml              |  4 +-
 20 files changed, 164 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index bba045d606..c2ed39b07d 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 6e46fac0611c1b7282766cf57965a07e3ee6bb9b
-2026-07-15-lsp-capability-seam.zh.md: b535b60df70e8a6132bb1596581be3ab1daba932
+2026-07-15-lsp-capability-seam.md: 233a7321e1b4fded955144ed84fbc34df49e8964
+2026-07-15-lsp-capability-seam.zh.md: 547249fc22844878954fe7120dd8b5c87aabfc1a
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 6e46fac061..233a7321e1 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -112,7 +112,7 @@ Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutd
 
 ## Workspace, filesystem, and document synchronization
 
-`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It observes caller cancellation around each provider operation. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
+`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It fuses caller cancellation with provider disposal across each filesystem operation, tracks workspace lookups before they enter a queue, and awaits those lookups during disposal. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
 
 The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index b535b60df7..547249fc22 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -112,7 +112,7 @@ interface LspToolInput {
 
 ## 工作区、文件系统与文档同步
 
-`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它在每项提供方操作前后检查调用方是否取消。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
+`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它会针对每项文件系统操作合并调用方取消与提供方资源释放，跟踪尚未进入队列的工作区查找，并在资源释放期间等待这些查找结算。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
 
 `read` 工具的输出带窗口与行号，进入 transcript（文本记录）且已被观察，不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方，并排除非本地提供方。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index fecaacac05..de79bd2d8d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: fe9d7bdd38199a031989b093fd3e9d931d62c80a
-2026-07-28-portable-execution-world-consumers.zh.md: 9f4f38e6e4c6c7dba74e8de4c260ec633dade910
+2026-07-28-portable-execution-world-consumers.md: e943c54a3f3a4c93a95db999d4c60790457ba644
+2026-07-28-portable-execution-world-consumers.zh.md: 7755791d5763436866763e8d4ea9e0fab8203bb9
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index fe9d7bdd38..e943c54a3f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -21,9 +21,9 @@ The subprocess interface owns the process coordinates and primitives: canonical
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
-- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
+- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals after shutdown begins and drains public signals already in flight before returning.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -45,4 +45,4 @@ A remote execution provider implements only its shared sandbox owner plus filesy
 
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
-The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal waits for exact PID-identity-fenced descendants retained during foreground inspection, Linux session members that survive top-level exit, and the top-level terminal process to reach quiescence. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
+The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 9f4f38e6e4..7755791d57 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -21,9 +21,9 @@ Status: implemented
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
-- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
+- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作开始后会拒绝新的公开信号，并在返回前等待所有已在途的公开信号结算。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -45,4 +45,4 @@ Status: implemented
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
-本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程、在顶层进程退出后仍存活的 Linux 会话成员，以及顶层终端进程完全停稳。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
+本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 42a11b8fb8..112e4eed83 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: b0778b2c9a8dfce8f786faccf6cc47f477c6b7c0
-2026-06-15-code-mode.zh.md: 437692eac3fc6740e0f1d4dd9001130fd6dd448a
+2026-06-15-code-mode.md: 1be25f5b145e50d8fe391d22910b71d85181582e
+2026-06-15-code-mode.zh.md: a4e8fbbd339899937c4f39091b4befbbb78ec347
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index b0778b2c9a..1be25f5b14 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -79,7 +79,7 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
 
 ### Trust posture
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 437692eac3..a4e8fbbd33 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -79,7 +79,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
+`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index e2b67d46d9..5a1036a349 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-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/lsp/lsp-local/README.md
-README.md: 299a5282bbca0a6d517af9342c4101cbdae33d4c
-README.zh.md: edf706fdb424756aa43b303b018b11e3764c2559
+README.md: c96c4febc9d047b41789f2b7a73e3eaf4d35012b
+README.zh.md: 5bc2c3c8bb7a89afb673797f5a3b25bb9fc06748
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 299a5282bb..c96c4febc9 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -11,7 +11,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
 - Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
 - Uses a compatibility-first **transient-open** sequence per query: resolve and boundedly read the source through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
-- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
+- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel. Provider disposal aborts filesystem and protocol work, awaits workspace lookups that have not entered a queue, then drains every queue and server.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
 - Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
 - Uses `ctx.fs` canonical containment, file URIs, and stable bounded reads, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index edf706fdb4..5bc2c3c8bb 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -11,7 +11,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
 - 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
 - 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析源文件并进行有界读取、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
-- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。
+- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方资源释放会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找结算，再排空所有队列并等待所有服务器结算。
 - 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
 - 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
 - 使用 `ctx.fs` 提供的规范 containment、文件 URI 与稳定有界读取，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 0d511588bd..f3f45959e5 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -208,6 +208,9 @@ class LocalLspProvider implements LspProvider {
   private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
   private readonly queues = new Map<WorkspaceKey, Promise<void>>()
+  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
+  private readonly workspaceLookups = new Set<Promise<void>>()
+  private readonly lifetime = new AbortController()
   private disposed = false
 
   constructor(
@@ -234,32 +237,48 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
+  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
+  private querySignal(signal?: AbortSignal): AbortSignal {
+    return signal === undefined
+      ? this.lifetime.signal
+      : AbortSignal.any([signal, this.lifetime.signal])
+  }
+
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
     // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(this.fs, request.workspaceRoot, signal)
-    this.assertActive(signal)
+    const querySignal = this.querySignal(signal)
+    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
+    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
+    this.workspaceLookups.add(workspaceLookup)
+    let workspace: HostWorkspace
+    try {
+      workspace = await workspaceResult
+    } finally {
+      this.workspaceLookups.delete(workspaceLookup)
+    }
+    this.assertActive(querySignal)
     const workspaceKey = workspace.target.targetKey
-    return this.enqueue(workspaceKey, signal, async () => {
-      this.assertActive(signal)
+    return this.enqueue(workspaceKey, querySignal, async () => {
+      this.assertActive(querySignal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(signal)
+      this.assertActive(querySignal)
       let instance = this.instanceFor(workspaceKey, workspace)
       try {
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
         this.evictIfCurrent(workspaceKey, instance)
-        this.assertActive(signal)
+        this.assertActive(querySignal)
         instance = this.instanceFor(workspaceKey, workspace)
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
@@ -320,13 +339,17 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
+    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
+    const resolving = [...this.workspaceLookups]
     this.instances.clear()
     await Promise.all([
       ...live.map(instance => instance.dispose()),
       ...draining,
+      ...resolving,
     ])
     this.queues.clear()
+    this.workspaceLookups.clear()
   }
 }
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index ce92e2c8fb..0337b0fec2 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -301,6 +301,52 @@ describe('lsp-local end to end over a fake server', () => {
     await ctx.fiber.dispose()
   })
 
+  it('aborts and awaits a workspace lookup when the provider is disposed', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const fs = ctx.fs
+    const resolve = fs.resolve.bind(fs)
+    const started = Promise.withResolvers<AbortSignal>()
+    const release = Promise.withResolvers<undefined>()
+    vi.spyOn(fs, 'resolve').mockImplementation(async (path, options) => {
+      if (path !== ws) return await resolve(path, options)
+      const signal = options?.signal
+      if (signal === undefined) throw new Error('workspace lookup missing provider lifetime signal')
+      started.resolve(signal)
+      return await rejectWhenAborted(signal, release.promise)
+    })
+
+    const pending = ctx.lsp.query(query('goToDefinition'))
+    const signal = await started.promise
+    let disposed = false
+    const disposing = ctx.fiber.dispose().then(() => { disposed = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+
+    expect(signal.aborted).toBe(true)
+    expect(disposed).toBe(false)
+    release.resolve(undefined)
+    await expect(pending).rejects.toThrow('provider is disposed')
+    await expect(disposing).resolves.toBeUndefined()
+  })
+
+  it('aborts a queued source read when the provider is disposed', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const fs = ctx.fs
+    const started = Promise.withResolvers<AbortSignal>()
+    vi.spyOn(fs, 'readTextBounded').mockImplementation(async (_target, _maxBytes, signal) => {
+      if (signal === undefined) throw new Error('source read missing provider lifetime signal')
+      started.resolve(signal)
+      return await rejectWhenAborted(signal)
+    })
+
+    const pending = ctx.lsp.query(query('goToDefinition'))
+    const signal = await started.promise
+    const disposing = ctx.fiber.dispose()
+
+    await expect(pending).rejects.toThrow('provider is disposed')
+    await expect(disposing).resolves.toBeUndefined()
+    expect(signal.aborted).toBe(true)
+  })
+
   it('runs distinct workspaces in parallel instances', async () => {
     const ws2 = join(root, 'ws2')
     await mkdir(ws2)
@@ -358,3 +404,16 @@ async function waitFor(condition: () => Promise<boolean>, timeoutMs = 3000): Pro
     await new Promise<void>(resolve => setTimeout(resolve, 10))
   }
 }
+
+/** Hold one fake provider operation until cancellation, optionally behind a cleanup gate. */
+function rejectWhenAborted<T>(signal: AbortSignal, release: Promise<unknown> = Promise.resolve()): Promise<T> {
+  return new Promise((_resolve, reject) => {
+    const onAbort = (): void => {
+      void release.then(() => {
+        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+      })
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) onAbort()
+  })
+}
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index efbb1612bd..ded1d12b30 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 61ee8ff9e09d5177ff6d5b3805dd84fb74c59961
-README.zh.md: 06a8e4bdd225e212aa67817ebbf66581314ab2bf
+README.md: 9f30fa6dc676e7b82f87b75b78b7d3143f204c94
+README.zh.md: 0b6813ec7d754f42e8bf4c65a1dee33d77bf3787
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 61ee8ff9e0..9f30fa6dc6 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -11,7 +11,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 06a8e4bdd2..0b6813ec7d 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 2f1e4d4058..30e38bd422 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -193,11 +193,15 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async closeOnce(): Promise<void> {
-    const survivors = await this.stopDescendants()
+    let survivors = await this.stopDescendants()
     if (survivors.length > 0) {
       throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
     await this.stopShell()
+    survivors = await this.stopDescendants()
+    if (survivors.length > 0) {
+      throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    }
     this.dataDisposable.dispose()
     this.exitDisposable.dispose()
   }
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 0202a3f33e..456ce4ee8f 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -13,6 +13,7 @@ class FakePty {
   readonly kills: string[] = []
   autoExitOnKill = true
   throwKill = false
+  onKill?: () => void
   private readonly dataListeners = new Set<(data: string) => void>()
   private readonly exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
 
@@ -39,6 +40,7 @@ class FakePty {
   kill(signal?: string): void {
     if (this.throwKill) throw new Error('process raced')
     this.kills.push(signal ?? 'SIGHUP')
+    this.onKill?.()
     if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
   }
 
@@ -213,6 +215,46 @@ describe('LocalTerminalHandle', () => {
     expect(pty.kills).toEqual(['SIGTERM'])
   })
 
+  it('sweeps a same-session descendant forked while the shell handles TERM', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const late = { pid: 124, started: 'shell-term-trap' }
+    pty.onKill = () => {
+      inspector.sessionMembers = [late]
+      inspector.alive.add(late.pid)
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    handle.terminate()
+    await handle.waitForExit()
+
+    expect(inspector.processes).toEqual([[late.pid, 'SIGTERM']])
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('keeps a failed post-shell sweep retryable until its survivor leaves', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const late = { pid: 124, started: 'shell-term-survivor' }
+    inspector.removeOnSignal = false
+    pty.onKill = () => {
+      inspector.sessionMembers = [late]
+      inspector.alive.add(late.pid)
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    handle.terminate()
+    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
+    await vi.advanceTimersByTimeAsync(25)
+    await failed
+
+    inspector.alive.delete(late.pid)
+    handle.terminate()
+    expect(await handle.waitForExit()).toBe(true)
+    expect(inspector.processes).toEqual([[late.pid, 'SIGTERM'], [late.pid, 'SIGKILL']])
+  })
+
   it('retains captured descendants after reparenting', async () => {
     vi.useFakeTimers()
     const pty = new FakePty()
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 13b8df9f71..7a36ab0690 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: fd8cfccdb333018e551459195564daad157d3867
-README.zh.md: b5b495e22bbf4328d82925cc793588ee45e5c6e4
+README.md: 38ee201a1754c6f50b7fae60b77af7dae734c8f9
+README.zh.md: 6fec39de550b7e3f57cd613dbe23c9687cd840ac

From c1d550de5809abea2a5db920c02396d412a1f013 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 18:26:21 +0800
Subject: [PATCH 075/262] refactor(runtime): collapse speculative portability
 layers

Remove the one-consumer bounded-read primitive and shared terminal lifecycle controller, make terminal cleanup one awaited provider operation, and reuse one Code Runtime contract suite. Keep only reproduced cancellation and policy fixes; defer unproven replacement, prompt-attribution, and streaming-frame concerns to scoped markers.
---
 ...06-17-filesystem-capability-seam.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-capability-seam.md  |   4 +-
 ...026-06-17-filesystem-capability-seam.zh.md |   4 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   4 +-
 .../2026-07-15-lsp-capability-seam.md         |   8 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |   8 +-
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |  12 +-
 ...8-portable-execution-world-consumers.zh.md |  12 +-
 docs/config-catalog.md                        |   2 +-
 .../core-data-structures/filesystem.i18n.yaml |   4 +-
 docs/core-data-structures/filesystem.md       |   4 +-
 docs/core-data-structures/filesystem.zh.md    |   4 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.md       |   4 +-
 docs/core-data-structures/subprocess.zh.md    |   4 +-
 .../code-runtime-worker/src/runtime-host.ts   |   1 -
 .../code-runtime/tests/contract.ts            | 838 ++++++++++++++++++
 .../tests/workspace-context.spec.ts           |   6 -
 .../cordis/tool-cordis/src/api-catalog.ts     |   8 +-
 packages/fs/fs-local/README.i18n.yaml         |   4 +-
 packages/fs/fs-local/README.md                |   2 +-
 packages/fs/fs-local/README.zh.md             |   2 +-
 packages/fs/fs-local/src/fsio.ts              |  65 +-
 packages/fs/fs-local/src/index.ts             |   5 -
 packages/fs/fs-local/tests/filesystem.spec.ts |   9 -
 packages/fs/fs-local/tests/fsio.spec.ts       |  63 +-
 packages/fs/fs/README.i18n.yaml               |   4 +-
 packages/fs/fs/README.md                      |   9 +-
 packages/fs/fs/README.zh.md                   |   9 +-
 packages/fs/fs/src/index.ts                   |  17 +-
 packages/fs/fs/tests/service.spec.ts          |   5 -
 packages/fs/tool-fs/tests/tools.spec.ts       |   5 -
 packages/lsp/lsp-local/README.i18n.yaml       |   4 +-
 packages/lsp/lsp-local/README.md              |   6 +-
 packages/lsp/lsp-local/README.zh.md           |   6 +-
 packages/lsp/lsp-local/src/host.ts            |  26 +-
 packages/lsp/lsp-local/tests/host.spec.ts     |   6 +
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |   9 +-
 packages/lsp/tool-lsp/src/render.ts           |  57 +-
 packages/lsp/tool-lsp/tests/render.spec.ts    |   1 +
 packages/pty/pty-local/README.i18n.yaml       |   4 +-
 packages/pty/pty-local/README.md              |   4 +-
 packages/pty/pty-local/README.zh.md           |   4 +-
 packages/pty/pty-local/src/index.ts           |  33 +-
 packages/pty/pty-local/src/session.ts         | 130 ++-
 packages/pty/pty-local/tests/index.spec.ts    |  13 +-
 packages/pty/pty-local/tests/session.spec.ts  | 285 +++---
 .../skill-local/tests/skill-local.spec.ts     |   6 -
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   2 +-
 .../subprocess/subprocess-local/README.zh.md  |   2 +-
 .../subprocess/subprocess-local/src/index.ts  |  16 +-
 .../subprocess-local/src/terminal.ts          |  34 +-
 .../subprocess-local/tests/local.spec.ts      |  39 +-
 .../subprocess-local/tests/terminal.spec.ts   | 108 +--
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   3 +-
 packages/subprocess/subprocess/README.zh.md   |   3 +-
 packages/subprocess/subprocess/src/index.ts   |  13 +-
 .../subprocess/src/terminal-lifecycle.ts      | 104 ---
 packages/subprocess/subprocess/src/types.ts   |  17 +-
 .../subprocess/tests/service.spec.ts          |   3 +-
 .../tests/terminal-lifecycle.spec.ts          | 125 ---
 packages/typert/README.i18n.yaml              |   4 +-
 65 files changed, 1265 insertions(+), 948 deletions(-)
 create mode 100644 packages/code-runtime/code-runtime/tests/contract.ts
 delete mode 100644 packages/subprocess/subprocess/src/terminal-lifecycle.ts
 delete mode 100644 packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index dc9b924f54..ddb215be9f 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 2fb360e5ad3c972f4a8de50c602a79af158dfc22
-2026-06-17-filesystem-capability-seam.zh.md: 1f70113b1583d890047ee4a17161f76b6390d8e8
+2026-06-17-filesystem-capability-seam.md: 7436d2a9402c76f17c7d6571eb489a86e550ebfb
+2026-06-17-filesystem-capability-seam.zh.md: fdeafba387b562352b377321327c526a67669ef6
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 2fb360e5ad..7436d2a940 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -64,7 +64,7 @@ The interface covers these semantic operations:
 - Resolve a model/plugin-supplied path into a backend-defined target.
 - Convert a resolved target to the canonical process path or `file:` URI for the same execution world, and test containment without parsing its opaque key.
 - Stat target metadata without reading file contents.
-- Read complete or streamed UTF-8 text, including one stable-handle byte-bounded whole-file operation.
+- Read complete or streamed UTF-8 text; consumers apply their own view and retention limits.
 - Create or replace a UTF-8 text file.
 - Edit an existing UTF-8 text file by literal replacement.
 
@@ -88,7 +88,7 @@ Resolved targets must expose at least three concepts:
 
 Read and mutation results must include an opaque file `version`. The local backend derives its token from bigint stat metadata (`dev`, `ino`, `size`, `mtimeNs`, and `ctimeNs`) so same-size rewrites and inode replacement invalidate consumers reliably; a remote backend can use a revision id or hash-like token. The `dsh-fs-policy` plugin records versions for stale checks; consumers may display related metadata but must not interpret the version token.
 
-The provider hands back decoded text: `readText` returns a whole regular text file, `streamText` streams the same text semantics for large files, and `readTextBounded` holds one backend-owned stable handle while rejecting a complete file above its byte ceiling. Line windowing, numbered-line rendering, and total-line accounting live in the executor (`dsh-tool-fs`). The provider owns regular-file checks, UTF-8 decoding, binary/NUL rejection, and the bounded read's replacement/growth race; it does not know about line windows or views.
+The provider hands back decoded text: `readText` returns a whole regular text file and `streamText` streams the same text semantics for large files or consumer-owned retention limits. Line windowing, byte ceilings, numbered-line rendering, and total-line accounting live in consumers such as `dsh-tool-fs` and `dsh-lsp-local`. The provider owns regular-file checks, UTF-8 decoding, and binary/NUL rejection; it does not know about line windows, protocol limits, or views.
 
 Observed-state recording is not on `ctx.fs`: after a successful read the executor emits `fs/observed`, and the `dsh-fs-policy` plugin records `{ version }` for the deriving owner. There is no `full`/`partial` view — a read at any window records the version, and freshness (not view completeness) authorizes a later write/edit.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index 1f70113b15..fdeafba387 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -64,7 +64,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 - 将模型/插件提供的路径解析为后端定义的目标。
 - 将解析后的目标转换为同一执行环境的规范进程路径或 `file:` URI，并在不解析其不透明键的情况下检查包含关系。
 - 获取目标元数据而不读取文件内容。
-- 读取完整或流式 UTF-8 文本，其中包括一项持有稳定句柄、以字节为上限的全文件读取操作。
+- 读取完整或流式 UTF-8 文本；消费方执行各自的视图与保留上限。
 - 创建或替换一个 UTF-8 文本文件。
 - 通过字面替换编辑一个已有的 UTF-8 文本文件。
 
@@ -88,7 +88,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
 
-提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式传输相同的文本语义，`readTextBounded` 则持有一个归后端所有的稳定句柄，并在完整文件超过字节上限时拒绝。行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中。提供方负责普通文件检查、UTF-8 解码、二进制/NUL 拒绝，以及有界读取期间的路径替换／增长竞态；它不知道行窗口或视图。
+提供方返回已解码的文本：`readText` 返回整个普通文本文件，`streamText` 为大文件或消费方自有的保留上限流式传输相同的文本语义。行窗口化、字节上限、带行号渲染和总行数统计归 `dsh-tool-fs`、`dsh-lsp-local` 等消费方所有。提供方负责普通文件检查、UTF-8 解码和二进制／NUL 拒绝；它不知道行窗口、协议上限或视图。
 
 观测状态记录不在 `ctx.fs` 上：成功读取后，执行器发出 `fs/observed`，`dsh-fs-policy` 插件为推导出的 owner 记录 `{ version }`。没有 `full`/`partial` 视图——任何窗口的读取都记录版本，新鲜度（而非视图完整性）授权后续的写入/编辑。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index c2ed39b07d..aac1c86e11 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 233a7321e1b4fded955144ed84fbc34df49e8964
-2026-07-15-lsp-capability-seam.zh.md: 547249fc22844878954fe7120dd8b5c87aabfc1a
+2026-07-15-lsp-capability-seam.md: 63cec0a4e349ffc5be27a84e955b15e9168f898b
+2026-07-15-lsp-capability-seam.zh.md: cdb1289f6956d8a4e46ed92847ddd8a58e588afa
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 233a7321e1..63cec0a4e3 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -112,13 +112,13 @@ Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutd
 
 ## Workspace, filesystem, and document synchronization
 
-`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It fuses caller cancellation with provider disposal across each filesystem operation, tracks workspace lookups before they enter a queue, and awaits those lookups during disposal. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
+`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, consumes `streamText`, and enforces `maxDocumentBytes` as chunks arrive; the provider retains regular-file validation and UTF-8 decoding while the protocol consumer owns its document limit. It fuses caller cancellation with provider disposal across each filesystem operation, tracks workspace lookups before they enter a queue, and awaits those lookups during disposal. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
 
 The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers.
 
 The local provider uses a compatibility-first transient-open sequence for every query. It accepts legacy `textDocumentSync` `Full` or `Incremental`, or options with `openClose: true`; omitted, `None`, or explicitly incompatible synchronization fails as unsupported before `didOpen`.
 
-1. Resolve and contain the source through `ctx.fs`, then read its current bounded text through the same provider.
+1. Resolve and contain the source through `ctx.fs`, then stream its current text through the same provider while enforcing the document byte limit.
 2. Send `textDocument/didOpen` with version `1`, full text, and the configured language id. Its write remains abortable; failure or cancellation invalidates the instance and awaits bounded process termination before the pool can reuse it.
 3. Send the requested `textDocument/definition`, `textDocument/references`, `textDocument/implementation`, or `textDocument/hover` request.
 4. If `didOpen` succeeded, attempt `textDocument/didClose` in `finally` after the request settles or aborts. A close-write failure does not replace the settled result or error, but invalidates the instance and awaits bounded process termination.
@@ -157,7 +157,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 
 **Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
 
-**Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider reads bounded full text directly through the same `ctx.fs` execution world used by its subprocess.
+**Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider consumes streamed full text directly through the same `ctx.fs` execution world used by its subprocess.
 
 **Keep documents open.** Mirroring edits requires version ownership, all-path `didChange`, HMR recovery, eviction, and stale-state rules. Transient opens avoid that MVP state machine.
 
@@ -195,4 +195,4 @@ Extension ownership is exclusive within one runtime. Two providers cannot both c
 
 UTF-16 cursor columns are exact for the protocol but difficult for a model to count around non-BMP characters. Invalid or off-symbol positions may produce empty results, so error text and prompt examples must explain the coordinate convention without encouraging broad LSP use.
 
-The paired filesystem/subprocess providers align the query snapshot with the server index but do not make a trusted language server safe. Canonical containment rejects query sources outside the workspace; the server itself receives the execution world's configured authority and may read other paths or use caches.
+The paired filesystem/subprocess providers align the query snapshot with the server index but do not make a trusted language server safe. Canonical containment rejects query sources outside the workspace at resolution time, but stream opening does not add stable-handle identity across a concurrent path replacement; the server itself receives the execution world's configured authority and may read other paths or use caches.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index 547249fc22..cdb1289f69 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -112,13 +112,13 @@ interface LspToolInput {
 
 ## 工作区、文件系统与文档同步
 
-`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它会针对每项文件系统操作合并调用方取消与提供方资源释放，跟踪尚未进入队列的工作区查找，并在资源释放期间等待这些查找结算。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
+`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，消费 `streamText`，并在分片到达时执行 `maxDocumentBytes` 上限；普通文件校验和 UTF-8 解码仍由提供方负责，文档上限则由协议消费方负责。它会针对每项文件系统操作合并调用方取消与提供方资源释放，跟踪尚未进入队列的工作区查找，并在资源释放期间等待这些查找结算。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
 
 `read` 工具的输出带窗口与行号，进入 transcript（文本记录）且已被观察，不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方，并排除非本地提供方。
 
 本地提供方对每次查询都采用兼容优先的临时打开流程。它接受旧式 `textDocumentSync` 的 `Full` 或 `Incremental`，也接受设置了 `openClose: true` 的选项；同步能力缺失、为 `None` 或明确不兼容时，在 `didOpen` 前以不支持错误失败。
 
-1. 通过 `ctx.fs` 解析源文件并检查其位于工作区内，再通过同一提供方对当前文本进行有界读取。
+1. 通过 `ctx.fs` 解析源文件并检查其位于工作区内，再通过同一提供方流式读取当前文本，同时执行文档字节上限。
 2. 发送 `textDocument/didOpen`，其中包含版本 `1`、完整文本和配置的语言 id。该写入仍可取消；写入失败或遭取消会使实例失效，并等待有界进程终止完成，池才能复用它。
 3. 发送所请求的 `textDocument/definition`、`textDocument/references`、`textDocument/implementation` 或 `textDocument/hover` 请求。
 4. 如果 `didOpen` 成功，则在请求完成或取消后于 `finally` 中尝试发送 `textDocument/didClose`。关闭写入失败不会覆盖已经确定的结果或错误，但会使实例失效，并等待有界进程终止完成。
@@ -157,7 +157,7 @@ interface LspToolInput {
 
 **将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
 
-**通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境读取有界的完整文本。
+**通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境消费流式传输的完整文本。
 
 **保持文档打开。** 镜像编辑需要版本归属、覆盖所有路径的 `didChange`、HMR 恢复、淘汰和陈旧状态规则。临时打开避免在 MVP 引入这套状态机。
 
@@ -195,4 +195,4 @@ interface LspToolInput {
 
 UTF-16 光标列与协议完全一致，但模型难以在包含非 BMP 字符的文本中准确计数。无效位置或不在符号上的位置可能返回空结果，因此错误文本和提示词示例必须说明坐标约定，同时避免鼓励模型广泛使用 LSP。
 
-配对的文件系统／子进程提供方会对齐查询快照与服务器索引，但不会因此使受信任的语言服务器变得安全。规范 containment 会拒绝工作区外的查询源；服务器本身获得执行环境所配置的权限，仍可读取其他路径或使用缓存。
+配对的文件系统／子进程提供方会对齐查询快照与服务器索引，但不会因此使受信任的语言服务器变得安全。规范 containment 会在解析时拒绝工作区外的查询源，但打开流不会在路径并发替换期间额外保证稳定句柄身份；服务器本身获得执行环境所配置的权限，仍可读取其他路径或使用缓存。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index de79bd2d8d..7b6a74b7e8 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: e943c54a3f3a4c93a95db999d4c60790457ba644
-2026-07-28-portable-execution-world-consumers.zh.md: 7755791d5763436866763e8d4ea9e0fab8203bb9
+2026-07-28-portable-execution-world-consumers.md: d68fc92308079aa68a8f4e1accadde0addb0e5aa
+2026-07-28-portable-execution-world-consumers.zh.md: 5341cf1643cabb1043b977e18179dc857e37e121
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index e943c54a3f..d68fc92308 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -14,16 +14,16 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 `ctx.fs` and `ctx.subprocess` together define one execution world. Providers mounted together must describe the same path namespace, executables, processes, and terminal sessions; higher capabilities consume those two interfaces rather than name the provider.
 
-The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, containment, and a bounded stable-handle text read. The existing text and mutation operations remain filesystem-owned.
+The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. The interface package also exports a provider-neutral lifecycle controller that joins top-level settlement, lifetime cancellation, retryable provider cleanup, and bounded quiescence observation; each implementation supplies only its session-cleanup transaction. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches whole-session quiescence. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals after shutdown begins and drains public signals already in flight before returning.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -35,6 +35,10 @@ Generic consumers use that execution world:
 
 **Move PTY readiness and session policy into the subprocess service.** Rejected because those are persistent-terminal consumer semantics, not OS process mechanics. A subprocess provider owns what only its substrate can do; `dsh-pty-local` owns what a Harness terminal means.
 
+**Expose separate terminal termination and quiescence operations plus a shared lifecycle controller.** Rejected because every terminal consumer needs the same single cleanup outcome. Separate operations export provider bookkeeping, bounded-observer, and retry semantics without a production consumer; one awaited provider operation is a deeper interface.
+
+**Add a stable bounded-read primitive to the filesystem seam.** Rejected because only LSP needs a complete-document byte ceiling, which it can enforce while consuming the existing text stream. A second primitive forces every provider to implement stable-handle and no-follow mechanics, including a remote helper protocol, without an observed concurrent-replacement defect.
+
 **Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable and filesystem materialization; the worker backend has neither requirement and remains the supported single-process path.
 
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 7755791d57..5341cf1643 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -14,16 +14,16 @@ Status: implemented
 
 `ctx.fs` 与 `ctx.subprocess` 共同定义一个执行世界。共同挂载的提供方必须描述相同的路径命名空间、可执行文件、进程和终端会话；上层能力消费这两个接口，而不引用具体提供方。
 
-文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI、包含关系，以及通过稳定句柄执行的有界文本读取。现有文本与变更操作仍归文件系统负责。
+文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。接口包还导出一个提供方无关的生命周期控制器，用于组合顶层结算、生命周期取消、可重试的提供方清理与有界的完全停稳观测；每个实现只需提供自身的会话清理事务。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作开始后会拒绝新的公开信号，并在返回前等待所有已在途的公开信号结算。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -35,6 +35,10 @@ Status: implemented
 
 **把 PTY 就绪判断与会话策略移入进程管理服务。** 不予采纳，因为这些属于持久终端消费方的语义，而非 OS 进程机制。进程管理提供方负责只有其执行基底才能完成的操作；`dsh-pty-local` 负责 Harness 终端的语义。
 
+**分别公开终端终止与完全停稳操作，并提供共享生命周期控制器。** 不予采纳，因为每个终端消费方都需要相同的单一清理结果。拆分操作会把提供方簿记、有界观察者和重试语义暴露出来，却没有生产消费方；由提供方提供一个须等待的操作，接口更深。
+
+**在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
+
 **删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
 
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index c07e81089c..b70f468960 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -447,7 +447,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/fs-local/src/index.ts:40`](../packages/fs/fs-local/src/index.ts)
+Source: [`packages/fs/fs-local/src/index.ts:39`](../packages/fs/fs-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-sandbox`
 
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
index 129c5569b9..78386c54fd 100644
--- a/docs/core-data-structures/filesystem.i18n.yaml
+++ b/docs/core-data-structures/filesystem.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 docs/core-data-structures/filesystem.md
-filesystem.md: 50b936bdef7535769f19d6cc0a75eb11eea9a869
-filesystem.zh.md: 61a885203b0718b34b0fd936c318b03c65ce4770
+filesystem.md: addded9f673ed435e95109d4fb772967514c0b87
+filesystem.zh.md: 3ef16ede1e137d2a1310861941ac3244ca105650
diff --git a/docs/core-data-structures/filesystem.md b/docs/core-data-structures/filesystem.md
index 50b936bdef..addded9f67 100644
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -52,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure. Protocol consumers use `readTextBounded(target, maxBytes)` when size validation and the complete UTF-8 read must remain one backend-owned stable operation; composing `stat` with `readText` would admit growth and replacement races.
+`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure. A protocol consumer that needs a byte ceiling applies it while consuming `streamText`, so the filesystem seam needs no consumer-specific bounded-read primitive.
 
 ```ts type-equiv
 /**
@@ -258,4 +258,4 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `readTextBounded`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/core-data-structures/filesystem.zh.md
index 6b7642b3f7..1e378928ed 100644
--- a/docs/core-data-structures/filesystem.zh.md
+++ b/docs/core-data-structures/filesystem.zh.md
@@ -52,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。当大小校验与完整 UTF-8 读取必须保持为一个由后端负责的稳定操作时，协议消费方使用 `readTextBounded(target, maxBytes)`；组合 `stat` 与 `readText` 会容许文件增长与替换竞态。
+`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。需要字节上限的协议消费方在消费 `streamText` 时执行该上限，因此文件系统 seam 无需消费方专用的有界读取原语。
 
 ```ts type-equiv
 /**
@@ -258,4 +258,4 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`readTextBounded`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index fca7947aae..7cba3857bb 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: eae497530ff54a7a259c23a2d0f665f3313488f5
-subprocess.zh.md: c3504ef7cd42448a15341f7f92d0f309a6216de1
+subprocess.md: 89c75aea3393a000612e3b8f87d263c7b4fa7c60
+subprocess.zh.md: 83fb44f4750ba31db1f4336c0c293eb9e236be22
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index c866276b8e..d6e0105c59 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -240,9 +240,9 @@ interface SubprocessOutcome {
 
 ## Terminal-process primitive
 
-`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns raw UTF-8 byte transport, foreground-process-group inspection and signalling, TERM-to-KILL cleanup, and whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
+`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, `terminate`, and `waitForExit`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
 
 ## Service behavior
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index c3504ef7cd..83fb44f475 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -240,9 +240,9 @@ interface SubprocessOutcome {
 
 ## 终端进程原语
 
-`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责原始 UTF-8 字节传输、前台进程组检查与信号发送、TERM→KILL 清理，以及整个会话的完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
+`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使整个会话完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground`、`terminate` 和 `waitForExit`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
 
 ## 服务行为
 
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index d2bb1082b8..474a058e9f 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -223,5 +223,4 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-export { jsonValueBytesUpTo } from './output-json.ts'
 export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime/tests/contract.ts b/packages/code-runtime/code-runtime/tests/contract.ts
new file mode 100644
index 0000000000..f28545f8c1
--- /dev/null
+++ b/packages/code-runtime/code-runtime/tests/contract.ts
@@ -0,0 +1,838 @@
+import { describe, expect, it } from 'vitest'
+import type {
+  CodeBindingFunction,
+  CodeBindingNamespace,
+  CodeRunResult,
+  CodeRuntime,
+} from '@deepseek-ai/dsh-code-runtime'
+
+interface WorkerCodeRuntimeContractConfig {
+  computeMs?: number
+  maxWallMs?: number
+  maxOutputBytes?: number
+  maxOldGenerationSizeMb?: number
+}
+
+interface WorkerCodeRuntimeContractHarness {
+  runtime: CodeRuntime
+  dispose: () => Promise<void>
+}
+
+type WorkerCodeRuntimeContractSetup = (
+  config?: WorkerCodeRuntimeContractConfig,
+) => Promise<WorkerCodeRuntimeContractHarness>
+
+/** Convenience: one namespace `tools` with the given functions. */
+export function workerRuntimeTools(
+  functions: Record<string, (args: unknown) => Promise<unknown>>,
+): CodeBindingNamespace[] {
+  return [{
+    global: 'tools',
+    functions: functions as Record<string, CodeBindingFunction>,
+    errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+  }]
+}
+
+/** Run behavior shared by the direct and subprocess-hosted worker runtimes. */
+export function runWorkerCodeRuntimeContract(
+  label: string,
+  setup: WorkerCodeRuntimeContractSetup,
+): void {
+  describe(`${label} — programs and bindings (real workers)`, () => {
+    it('registers with the seam descriptors', async () => {
+      const { runtime } = await setup()
+      expect(runtime.language).toBe('typescript')
+      expect(runtime.isolation).toBe('worker-thread')
+    })
+
+    it('runs TypeScript (erasable syntax), captures output in order, returns the value', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          interface Point { x: number; y: number }
+          const p: Point = { x: 1, y: 2 } as Point;
+          console.log('point', p);
+          process.stdout.write('raw-out\\n');
+          console.warn('careful');
+          return p.x + p.y;
+        `,
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe(3)
+      expect(result.logs).toEqual(['point { x: 1, y: 2 }', 'raw-out\n', 'careful'])
+    })
+
+    it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => {
+      const { runtime } = await setup()
+      const calls: unknown[] = []
+      const result = await runtime.run({
+        program: `
+          const first = await tools.echo({ n: 1 });
+          let caught = {};
+          try { await tools.fail({}) } catch (error) { caught = { isTyped: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message } }
+          let caughtRaw = {};
+          try { await tools.failRaw({}) } catch (error) { caughtRaw = { name: error.name, toolName: error.toolName, message: error.message } }
+          return { first, caught, caughtRaw };
+        `,
+        bindings: workerRuntimeTools({
+          echo: async (args) => { calls.push(args); return { echoed: args } },
+          fail: async () => { throw new Error('nope') },
+          // A non-Error throw: the host renders it, the program still catches.
+          failRaw: async () => { throw 'raw-nope' },
+        }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toEqual({
+        first: { echoed: { n: 1 } },
+        caught: { isTyped: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
+        caughtRaw: { name: 'ToolCallError', toolName: 'failRaw', message: 'raw-nope' },
+      })
+      expect(calls).toEqual([{ n: 1 }])
+    })
+
+    it('materializes a typed rejection from a generic namespace descriptor', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          try { await helpers.fail({}) } catch (error) {
+            return {
+              isTyped: error instanceof HelperCallError,
+              name: error.name,
+              helperName: error.helperName,
+              message: error.message,
+            };
+          }
+        `,
+        bindings: [{
+          global: 'helpers',
+          functions: { fail: async () => { throw new Error('nope') } },
+          errorClass: { name: 'HelperCallError', memberNameProperty: 'helperName' },
+        }],
+      })
+      expect(result.value).toEqual({
+        isTyped: true,
+        name: 'HelperCallError',
+        helperName: 'fail',
+        message: 'nope',
+      })
+    })
+
+    it('bridges a deeply nested lossless JSON argument, resolution, and completion', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          let value = 'leaf';
+          for (let depth = 0; depth < 3_000; depth++) value = [value];
+          return await tools.echo(value);
+        `,
+        bindings: workerRuntimeTools({ echo: async args => args }),
+      })
+
+      expect(result.error).toBeUndefined()
+      let cursor = result.value
+      for (let depth = 0; depth < 3_000; depth++) {
+        expect(Array.isArray(cursor)).toBe(true)
+        cursor = Array.isArray(cursor) ? cursor[0] : undefined
+      }
+      expect(cursor).toBe('leaf')
+    }, 15_000)
+
+    it('reports non-erasable syntax as an exception without spawning a worker', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
+      expect(result.error?.kind).toBe('exception')
+      expect(result.error?.message).toMatch(/enum|strip/i)
+    })
+
+    it('reports a runtime throw as an exception with the message', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'throw new Error("kaboom")', bindings: [] })
+      expect(result.error?.kind).toBe('exception')
+      expect(result.error?.message).toContain('kaboom')
+    })
+
+    it('gives the program an EMPTY environment', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return JSON.stringify(process.env)', bindings: [] })
+      expect(result.value).toBe('{}')
+    })
+
+    it('rejects a non-lossless completion instead of replacing it with rendered text', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return { f: () => 1 }', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'invalid-output', message: 'program completion must be lossless JSON' })
+    })
+
+    it('completes a program that returns nothing with no value at all', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'const x = 1', bindings: [] })
+      expect(result.error).toBeUndefined()
+      expect('value' in result).toBe(false)
+    })
+
+    it('keeps logs streamed before a failure', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'console.log("before"); throw new Error("after-log")',
+        bindings: [],
+      })
+      expect(result.error?.kind).toBe('exception')
+      expect(result.logs).toContain('before')
+    })
+  })
+
+  describe(`${label} — budgets and containment (real workers)`, () => {
+    it('ends a hot loop at the compute budget — including behind a pending decoy dispatch', async () => {
+      const { runtime } = await setup({ computeMs: 300, maxWallMs: 30_000 })
+      const result = await runtime.run({
+        // The decoy: fire a call at a never-resolving binding WITHOUT awaiting,
+        // then spin. Host-side pending-call bookkeeping would pause a naive
+        // budget here; measured busy time cannot be fooled.
+        program: 'void tools.slow({}); for (;;) {}',
+        bindings: workerRuntimeTools({ slow: () => new Promise(() => {}) }),
+      })
+      expect(result.error?.kind).toBe('timeout')
+      expect(result.error?.message).toContain('compute budget')
+    }, 15_000)
+
+    it('does not charge time spent awaiting a slow binding against the compute budget', async () => {
+      // Keep the binding delay above the compute allowance while leaving enough
+      // headroom for worker bootstrap on loaded CI hosts.
+      const { runtime } = await setup({ computeMs: 1_000, maxWallMs: 30_000 })
+      const result = await runtime.run({
+        program: 'return await tools.slow({})',
+        bindings: workerRuntimeTools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 1_500)) }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('slow-done')
+    }, 15_000)
+
+    it('ends an idle-forever run at the wall-clock ceiling', async () => {
+      const { runtime } = await setup({ computeMs: 30_000, maxWallMs: 400 })
+      const result = await runtime.run({
+        program: 'await tools.never({}); return 1',
+        bindings: workerRuntimeTools({ never: () => new Promise(() => {}) }),
+      })
+      expect(result.error?.kind).toBe('timeout')
+      expect(result.error?.message).toContain('wall-clock ceiling')
+    }, 15_000)
+
+    it('reports an abort mid-run and stops the worker', async () => {
+      const { runtime } = await setup()
+      const controller = new AbortController()
+      setTimeout(() => { controller.abort('user-cancel') }, 150)
+      const result = await runtime.run({ program: 'for (;;) {}', bindings: [], signal: controller.signal })
+      expect(result.error).toEqual({ kind: 'abort', message: 'user-cancel' })
+    }, 15_000)
+
+    it('reports a pre-aborted signal without spawning', async () => {
+      const { runtime } = await setup()
+      const controller = new AbortController()
+      controller.abort('too-late')
+      const result = await runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
+      expect(result.error).toEqual({ kind: 'abort', message: 'too-late' })
+    })
+
+    it('applies the outer-output cap to failures before worker startup', async () => {
+      const capped = await setup({ maxOutputBytes: 64 })
+      const controller = new AbortController()
+      controller.abort('A'.repeat(1_000))
+      const aborted = await capped.runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
+      expect(aborted).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
+
+      const minimal = await setup({ maxOutputBytes: 4 })
+      const invalid = await minimal.runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
+      expect(invalid.error?.kind).toBe('output-limit')
+      expect(Buffer.byteLength(JSON.stringify(invalid.logs), 'utf8') + Buffer.byteLength(JSON.stringify(invalid.error?.message), 'utf8')).toBeLessThanOrEqual(4)
+    })
+
+    it('drops a binding resolution that lands after the run settled', async () => {
+      const { runtime } = await setup()
+      const controller = new AbortController()
+      let replyDelivered!: Promise<void>
+      const result = await runtime.run({
+        program: 'void tools.late({}); for (;;) {}',
+        bindings: workerRuntimeTools({
+          // Anchored on invocation: abort 100ms after the call reaches the
+          // host, resolve 400ms after — by then the run has settled, so the
+          // resolution's reply hits the post-settlement drop.
+          late: () => new Promise((resolve) => {
+            setTimeout(() => { controller.abort('cancel-now') }, 100)
+            replyDelivered = new Promise(done => setTimeout(() => { resolve('too-late'); done() }, 400))
+          }),
+        }),
+        signal: controller.signal,
+      })
+      expect(result.error).toEqual({ kind: 'abort', message: 'cancel-now' })
+      // Let the late resolution actually fire so its reply executes instead of
+      // being cancelled with the test.
+      await replyDelivered
+    }, 15_000)
+
+    it('contains an OOM under resourceLimits as worker-exit, host process healthy', async () => {
+      const { runtime } = await setup({ maxOldGenerationSizeMb: 32 })
+      const result = await runtime.run({
+        program: 'const hog = []; for (;;) hog.push(new Array(1e6).fill(1));',
+        bindings: [],
+      })
+      expect(result.error?.kind).toBe('worker-exit')
+      // And the host is fine: run something else.
+      const after = await runtime.run({ program: 'return "alive"', bindings: [] })
+      expect(after.value).toBe('alive')
+    }, 30_000)
+
+    it('reports a worker that exits before publishing a completion', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'process.exit(7)', bindings: [] })
+      expect(result).toEqual({
+        logs: [],
+        error: { kind: 'worker-exit', message: 'worker exited with code 7 before completing' },
+      })
+    })
+
+    it('fails runaway log output explicitly while retaining a bounded prefix', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 300 })
+      const result = await runtime.run({
+        program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1',
+        bindings: [],
+      })
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 300 bytes' })
+      expect(result.value).toBeUndefined()
+      expect(result.logs.length).toBeGreaterThan(0)
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(300)
+    })
+
+    it('retains a fitting prefix when one oversized log is the first output', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 96 })
+      const result = await runtime.run({
+        program: 'console.log(`start-${`😀"\\\\\\n`.repeat(100)}`); return null',
+        bindings: [],
+      })
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 96 bytes' })
+      expect(result.logs).toHaveLength(1)
+      expect(result.logs[0]?.startsWith('start-')).toBe(true)
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
+        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(96)
+    })
+
+    it('fails an oversized return value without substituting a string', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({ program: 'return "y".repeat(10_000)', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
+    })
+
+    it('uses UTF-8 serialized bytes at the exact completion boundary', async () => {
+      const exact = await setup({ maxOutputBytes: 7 })
+      const exactResult = await exact.runtime.run({ program: 'return "€"', bindings: [] })
+      // [] costs two bytes and JSON serialization of "€" costs five.
+      expect(exactResult).toEqual({ logs: [], value: '€' })
+
+      const over = await setup({ maxOutputBytes: 6 })
+      const overResult = await over.runtime.run({ program: 'return "€"', bindings: [] })
+      expect(overResult.error?.kind).toBe('output-limit')
+    })
+
+    it('accounts logs and completion in one exact combined ledger', async () => {
+      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
+      const exact = await setup({ maxOutputBytes: 11 })
+      expect(await exact.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] }))
+        .toEqual({ logs: ['abc'], value: 'xy' })
+
+      const over = await setup({ maxOutputBytes: 10 })
+      const result = await over.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error?.kind).toBe('output-limit')
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8') + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
+    })
+
+    it('accounts logs and exception diagnostics before the worker port boundary', async () => {
+      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
+      const exact = await setup({ maxOutputBytes: 11 })
+      expect(await exact.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] }))
+        .toEqual({ logs: ['abc'], error: { kind: 'exception', message: 'xy' } })
+
+      const over = await setup({ maxOutputBytes: 10 })
+      const result = await over.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] })
+      expect(result.error?.kind).toBe('output-limit')
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
+        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
+    })
+
+    it('does not send a giant Error stack across the worker port', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({
+        program: 'throw new Error("x".repeat(1_000_000))',
+        bindings: [],
+      })
+      expect(result).toEqual({
+        logs: [],
+        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+      })
+    })
+
+    it('completes a program that awaits its write callback, capturing the chunk', async () => {
+      // Node's write(chunk[, encoding][, callback]) contract: dropping the
+      // callback would leave this promise pending until the wall ceiling and
+      // misreport a completed program as a timeout.
+      const { runtime } = await setup({ maxWallMs: 2_000 })
+      const result = await runtime.run({
+        program: 'await new Promise(resolve => process.stdout.write("flushed", resolve)); return "done"',
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('done')
+      expect(result.logs).toContain('flushed')
+    })
+
+    it('returns a large JSON container exactly when the outer cap permits it', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return new Array(50_000).fill(7)', bindings: [] })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toEqual(new Array(50_000).fill(7))
+    })
+
+    it('returns an exact completion at the default 64 MiB combined boundary', async () => {
+      const { runtime } = await setup()
+      // [] costs two bytes and the JSON string contributes two quotes, leaving
+      // exactly this many payload bytes under the 67_108_864-byte default.
+      const result = await runtime.run({ program: 'return "x".repeat(67_108_860)', bindings: [] })
+      expect(result.error).toBeUndefined()
+      expect(result.logs).toEqual([])
+      expect(result.value).toHaveLength(67_108_860)
+    }, 60_000)
+
+    it('fails one byte over the default 64 MiB combined boundary', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return "x".repeat(67_108_861)', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' })
+    }, 60_000)
+
+    it('drains pipe output queued before terminal worker teardown completes', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 200_000 })
+      const payload = `late-pipe-${'x'.repeat(100_000)}`
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text);
+          write('late-pipe-' + 'x'.repeat(100_000));
+          parentPort.postMessage({ type: 'done', value: ['done'] });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('done')
+      expect(result.logs.join('') === payload).toBe(true)
+    }, 15_000)
+  })
+
+  describe(`${label} — hostile programs (real workers)`, () => {
+    it('survives forged port traffic: unknown binding names, duplicate ids, junk shapes', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
+          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
+          parentPort.postMessage({ type: 'call', id: 7778, global: 'tools', name: 'constructor', args: {} });
+          parentPort.postMessage({ type: 'junk' });
+          return await tools.real({});
+        `,
+        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('still-works')
+    })
+
+    it('survives arbitrary junk on the port: non-objects, junk types, malformed calls, logs, and dones', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          for (const junk of [
+            null, 42, 'junk', [],
+            { type: 'nope' },
+            { type: 'call' },
+            { type: 'call', id: 'x', global: 'tools', name: 'real', args: {} },
+            { type: 'call', id: 1e9, global: 7, name: 'real', args: {} },
+            { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} },
+            { type: 'log' },
+            { type: 'log', text: null },
+            { type: 'log', text: 7 },
+            { type: 'log', text: {} },
+            { type: 'done', error: 5 },
+            { type: 'done', error: { kind: 'exception', message: 5 } },
+            { type: 'done', error: { kind: 'invented', message: 'bad kind' } },
+          ]) parentPort.postMessage(junk);
+          return await tools.real({});
+        `,
+        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('still-works')
+      expect(result.logs).toEqual([])
+    })
+
+    it('fails forged log floods and forged done values through the same outer cap', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 200 })
+      const result = await runtime.run({
+        // Forged messages bypass worker-side capture and completion checks;
+        // the outer ledger must still contain them.
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', text: 'F'.repeat(100), forged: true });
+          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100000)] });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 200 bytes' })
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(200)
+    })
+
+    it('re-caps an oversized forged done value at the host boundary', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100_000)] });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({
+        logs: [],
+        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+      })
+    })
+
+    it('drops a malformed forged done carrying both value and error', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', value: 'lied', error: { kind: 'exception', message: 'fake failure' } });
+          return 'honest';
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], error: { kind: 'exception', message: 'fake failure' } })
+    })
+
+    it('contains a deeply nested forged completion without overflowing the host meter', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          const value = [];
+          for (let depth = 0; depth < 3_000; depth++) value.push({ kind: 'array', length: 1 });
+          value.push(null);
+          setTimeout(() => { parentPort.postMessage({ type: 'done', value }) }, 25);
+          // Prevent bootstrap's normal undefined completion from racing the forged terminal.
+          await new Promise(() => {});
+        `,
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      let value = result.value
+      let depth = 0
+      while (Array.isArray(value)) {
+        expect(value).toHaveLength(1)
+        value = value[0]
+        depth += 1
+      }
+      expect(depth).toBe(3_000)
+      expect(value).toBeNull()
+    }, 15_000)
+
+    it('turns forged over-limit error text into output-limit at the host', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', error: { kind: 'exception', message: '€'.repeat(1000) } });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
+    })
+
+    it('answers a binding whose resolution is not lossless JSON with a typed failure reply', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
+        bindings: workerRuntimeTools({ bad: async () => (() => 1) }),
+      })
+      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
+    })
+
+    it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
+      const { runtime } = await setup()
+      let calls = 0
+      const result = await runtime.run({
+        program: `
+          const decorated = [1]; Object.defineProperty(decorated, 'extra', { value: true });
+          const values = [new Date(), decorated, () => 1];
+          const failures = [];
+          for (const value of values) {
+            try { await tools.never(value) } catch (error) {
+              failures.push({ typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message });
+            }
+          }
+          return failures;
+        `,
+        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
+      })
+      expect(calls).toBe(0)
+      expect(result.value).toEqual(new Array(3).fill({
+        typed: true,
+        name: 'ToolCallError',
+        toolName: 'never',
+        message: 'binding arguments must be lossless JSON',
+      }))
+    })
+
+    it('rejects intrinsic-looking exotic objects as arguments and completions', async () => {
+      const { runtime } = await setup()
+      let calls = 0
+      const forgeObject = `
+        const prototype = Object.create(null);
+        const SpoofedObject = function Object() {};
+        SpoofedObject.prototype = prototype;
+        Object.defineProperty(prototype, 'constructor', { value: SpoofedObject });
+        const forged = Object.assign(Object.create(prototype), { value: 1 });
+        Function.prototype.toString = () => 'function Object() { [native code] }';
+      `
+      const argument = await runtime.run({
+        program: `${forgeObject}
+          try { await tools.never(forged) } catch (error) {
+            return { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
+          }
+        `,
+        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
+      })
+      expect(calls).toBe(0)
+      expect(argument.value).toEqual({
+        typed: true,
+        name: 'ToolCallError',
+        toolName: 'never',
+        message: 'binding arguments must be lossless JSON',
+      })
+
+      const completion = await runtime.run({ program: `${forgeObject}\nreturn forged`, bindings: [] })
+      expect(completion).toEqual({
+        logs: [],
+        error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' },
+      })
+    })
+
+    it('preserves binding and completion JSON after model code mutates boundary globals', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const arrayPrototype = Array.prototype;
+          const objectPrototype = Object.prototype;
+          const setPrototype = Set.prototype;
+          const stringPrototype = String.prototype;
+          Array.isArray = () => false;
+          arrayPrototype.at = arrayPrototype.includes = arrayPrototype.pop = arrayPrototype.push = () => { throw new Error('mutated array method') };
+          Object.defineProperty = Object.getOwnPropertyDescriptor = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') };
+          Object.hasOwn = () => false;
+          Object.is = () => true;
+          objectPrototype.propertyIsEnumerable = () => false;
+          Number.isFinite = Number.isSafeInteger = () => false;
+          Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') };
+          setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') };
+          stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') };
+          Buffer.byteLength = () => 0;
+          Function.prototype.toString = () => 'mutated';
+          objectPrototype.get = () => undefined;
+          objectPrototype.constructor = arrayPrototype.constructor = null;
+          globalThis.Array = globalThis.Buffer = globalThis.Error = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Reflect = globalThis.Set = globalThis.String = undefined;
+          const echoed = await tools.echo({ request: ['€', 1] });
+          let failure;
+          try { await tools.fail({}) } catch (error) {
+            failure = { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
+          }
+          return { echoed, failure, completion: { ok: true, amount: 42 } };
+        `,
+        bindings: workerRuntimeTools({ echo: async args => args, fail: async () => { throw new Error('nope') } }),
+      })
+      expect(result).toEqual({
+        logs: [],
+        value: {
+          echoed: { request: ['€', 1] },
+          failure: { typed: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
+          completion: { ok: true, amount: 42 },
+        },
+      })
+    })
+
+    it('rejects forged lossy binding arguments again at the host boundary', async () => {
+      const { runtime } = await setup()
+      let calls = 0
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          const forged = (id, args) => new Promise((resolve) => {
+            const receive = (message) => {
+              if (message?.type !== 'reply' || message.id !== id) return;
+              parentPort.off('message', receive);
+              resolve(message);
+            };
+            parentPort.on('message', receive);
+            parentPort.postMessage({ type: 'call', id, global: 'tools', name: 'never', args });
+          });
+          const sparse = []; sparse.length = 1;
+          const cycle = {}; cycle.self = cycle;
+          return await Promise.all([
+            forged(8001, new Date()),
+            forged(8002, -0),
+            forged(8003, sparse),
+            forged(8004, cycle),
+          ]);
+        `,
+        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
+      })
+      expect(calls).toBe(0)
+      expect(result.value).toEqual([8001, 8002, 8003, 8004].map(id => ({
+        type: 'reply',
+        id,
+        ok: false,
+        message: 'binding arguments must be lossless JSON',
+      })))
+    })
+
+    it('contains throwing getters while snapshotting binding resolutions', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
+        bindings: workerRuntimeTools({ bad: async () => Object.defineProperty({}, 'bad', { enumerable: true, get() { throw new Error('getter exploded') } }) }),
+      })
+      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
+    })
+
+    it('revalidates a forged lossy completion at the host boundary', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', value: -0 });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
+    })
+
+    it('honors a forged worker-side output-limit signal', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'output-limit' });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' } })
+    })
+
+    it('exposes binding names that collide with Object.prototype as ordinary functions', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'return [await tools["__proto__"]({}), await tools["constructor"]({}), typeof tools["hasOwnProperty"]]',
+        // Computed keys: a literal `'__proto__': …` entry would SET the record's
+        // prototype instead of declaring a binding of that name.
+        bindings: workerRuntimeTools({ ['__proto__']: async () => 'proto-ok', ['constructor']: async () => 'ctor-ok' }),
+      })
+      expect(result.value).toEqual(['proto-ok', 'ctor-ok', 'undefined'])
+    })
+  })
+
+  describe(`${label} — seam misuse and lifecycle`, () => {
+    it('rejects invalid and duplicate binding globals loudly', async () => {
+      const { runtime } = await setup()
+      const cases: [string, RegExp][] = [
+        ['not valid!', /not a usable identifier/],
+        ['await', /not a usable identifier/],
+        ['console', /duplicate binding global/],
+      ]
+      for (const [global, message] of cases) {
+        await expect(runtime.run({ program: 'return 1', bindings: [{ global, functions: {} }] })).rejects.toThrow(message)
+      }
+      await expect(runtime.run({
+        program: 'return 1',
+        bindings: [{ global: 'tools', functions: {} }, { global: 'tools', functions: {} }],
+      })).rejects.toThrow(/duplicate binding global/)
+
+      await expect(runtime.run({
+        program: 'return typeof ToolCallError',
+        bindings: [{ global: 'ToolCallError', functions: {} }],
+      })).resolves.toMatchObject({ value: 'object' })
+    })
+
+    it('rejects malformed or colliding binding error-class declarations', async () => {
+      const { runtime } = await setup()
+      const run = async (bindings: CodeBindingNamespace[]) => await runtime.run({ program: 'return 1', bindings })
+      const namespace = (global: string, name: string, memberNameProperty = 'memberName'): CodeBindingNamespace => ({
+        global,
+        functions: {},
+        errorClass: { name, memberNameProperty },
+      })
+
+      await expect(run([namespace('tools', 'not valid!')])).rejects.toThrow(/error class.*not a usable identifier/)
+      await expect(run([namespace('tools', 'await')])).rejects.toThrow(/error class.*not a usable identifier/)
+      await expect(run([namespace('tools', 'console')])).rejects.toThrow(/duplicate injected global/)
+      await expect(run([namespace('tools', 'tools')])).rejects.toThrow(/duplicate injected global/)
+      await expect(run([
+        namespace('tools', 'CallError'),
+        namespace('helpers', 'CallError'),
+      ])).rejects.toThrow(/duplicate injected global/)
+      await expect(run([namespace('tools', 'CallError', '')])).rejects.toThrow(/member property.*not usable/)
+      await expect(run([namespace('tools', 'CallError', 'message')])).rejects.toThrow(/member property.*not usable/)
+    })
+
+    it('rejects config values that are not positive numbers', async () => {
+      await expect(setup({ computeMs: -1 })).rejects.toThrow(/positive number/)
+    })
+
+    it('rejects a maxWallMs above Node\'s maximum timer delay', async () => {
+      // setTimeout clamps a delay past 2^31-1 ms to 1 ms, so the positivity check
+      // alone would accept a 25-day ceiling that expires on the first tick.
+      await expect(setup({ maxWallMs: 2_147_483_648 }))
+        .rejects.toThrow(/maxWallMs must be at most 2147483647/)
+      // The boundary itself is usable.
+      await expect(setup({ maxWallMs: 2_147_483_647 })).resolves.toBeTruthy()
+    })
+
+    it('requires maxOutputBytes to fit the smallest counted outer payloads', async () => {
+      await expect(setup({ maxOutputBytes: 3 })).rejects.toThrow(/safe integer of at least 4/)
+      await expect(setup({ maxOutputBytes: 4.5 })).rejects.toThrow(/safe integer of at least 4/)
+    })
+
+    it('keeps runs isolated: no state survives from one run to the next', async () => {
+      const { runtime } = await setup()
+      await runtime.run({ program: 'globalThis.leak = "value"; return 1', bindings: [] })
+      const second = await runtime.run({ program: 'return typeof globalThis.leak', bindings: [] })
+      expect(second.value).toBe('undefined')
+    })
+
+    it('disposal aborts in-flight runs, awaits worker exit, and rejects later runs', async () => {
+      const { runtime, dispose } = await setup()
+      const inflight: Promise<CodeRunResult> = runtime.run({ program: 'for (;;) {}', bindings: [] })
+      // Give the worker a moment to actually start spinning.
+      await new Promise(resolve => setTimeout(resolve, 200))
+      await dispose()
+      const result = await inflight
+      expect(result.error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+      await expect(runtime.run({ program: 'return 1', bindings: [] })).rejects.toThrow(/after disposal/)
+    }, 15_000)
+  })
+}
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 8620c38981..fcdcd7c422 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -117,12 +117,6 @@ class RecordingFileSystem extends FileSystem {
     return this.entries.get(target.targetKey)?.content ?? ''
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    const text = await this.readText(target, signal)
-    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
-    return text
-  }
-
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index c7b6df254e..2eb410acc6 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -336,10 +336,6 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
         jsDoc: '/**\n * Read the whole regular text file as a single decoded string.\n * @param target - the resolved target to read.\n * @param signal - aborts the read.\n * @returns the full decoded UTF-8 content.\n */',
       },
-      {
-        signature: 'abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>',
-        jsDoc: '/**\n * Read one regular UTF-8 text file through a backend-owned stable handle,\n * rejecting before more than `maxBytes` are retained. The size check and\n * bytes read are one operation: a caller must not emulate this with\n * {@link stat} followed by {@link readText}, which admits growth and path\n * replacement races between the two calls.\n * @param target - the resolved target to read.\n * @param maxBytes - positive safe-integer byte ceiling.\n * @param signal - aborts the open/read operation.\n * @returns the complete decoded text when it fits.\n */',
-      },
       {
         signature: 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
         jsDoc: '/**\n * Stream the whole regular text file as decoded text chunks (same text\n * semantics as {@link readText}, for large files). The backend owns\n * cross-chunk UTF-8 decoding and binary rejection so the policy layer never\n * touches raw bytes.\n * @param target - the resolved target to read.\n * @param signal - aborts the stream, including between chunks.\n * @returns the chunk iterable, decoded and validated like {@link readText}.\n */',
@@ -1000,7 +996,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>',
-        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
+        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
       },
     ],
   },
@@ -2909,7 +2905,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubprocessTerminalHandle',
-    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: Uint8Array): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): void;\n    waitForExit(signal?: AbortSignal): Promise<boolean>;\n}',
+    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: string): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): Promise<void>;\n}',
   },
   {
     name: 'SubprocessTerminalSignal',
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 57d2a32f97..e1870cbf41 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-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/fs/fs-local/README.md
-README.md: f5cf2441adcd62e55c6169ceb766f88382e314f5
-README.zh.md: 40f5a83626780bae8f335c80662721bae6cc0b0b
+README.md: fe0e5e9dec07fad745d6bea28da9009e517c7d85
+README.zh.md: 195f3963328035e9c6c382dd924cd04ee9e8c642
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index f5cf2441ad..fe0e5e9dec 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -17,7 +17,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
 - **Execution-world coordinates** — `processPath` exposes the target's canonical host path, `fileUrl` encodes that path through Node's platform-aware URL conversion, and `contains` uses platform path semantics to test identity or descendant containment without consumers parsing `targetKey`.
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
-- **`readText` / `readTextBounded` / `streamText`** — UTF-8 only. `readText` reads the whole file; `readTextBounded` opens one no-follow, nonblocking handle, verifies it is regular, and retains at most `maxBytes + 1` bytes so growth cannot bypass the cap; `streamText` decodes chunks so a huge file need not be held whole in memory. All reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing; protocol consumers such as the LSP host use the stable bounded operation.
+- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 40f5a83626..195f396332 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -17,7 +17,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`resolve(path, opts?)`**：相对 `path` 在调用方提供 `opts.cwd` 时以该值为基准解析（面向模型的工具会传入调用 agent（智能体）的会话 cwd；见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)），否则以 `config.cwd` 为基准（默认 `process.cwd()`）；绝对 `path` 会忽略两者。`opts.signal` 会在本地解析前后检查，远程同级后端则可以用它中止往返。`targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径会共享一个身份，写入/编辑落在链接目标上，同时保留链接。尚不存在的路径在父目录存在时使用 realpath 后的父目录加 basename；只有父目录无法解析时才回退到绝对路径。`displayPath` 是绝对但未经解析的路径。
 - **执行世界坐标**：`processPath` 公开目标的规范化宿主路径，`fileUrl` 通过 Node 的平台感知 URL 转换对该路径编码，`contains` 则使用平台路径语义检查身份相等或后代包含关系，消费方无需解析 `targetKey`。
 - **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
-- **`readText` / `readTextBounded` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`readTextBounded` 打开一个不跟随符号链接的非阻塞句柄，确认其为普通文件，并最多保留 `maxBytes + 1` 字节，使文件增长无法绕过上限；`streamText` 按分片解码，因此超大文件无需整体保存在内存中。三者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑；LSP 主机等协议消费方使用稳定的有界操作。
+- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
 - **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
 - **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index e95cb14cca..4925357e45 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -6,7 +6,7 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { constants, createReadStream } from 'node:fs'
+import { createReadStream } from 'node:fs'
 import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
 import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
@@ -377,69 +377,6 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
  * @param signal - aborts between handle operations.
  * @returns the complete decoded text when it fits.
  */
-export async function readWholeTextBounded(
-  target: LocalTarget,
-  maxBytes: number,
-  signal?: AbortSignal,
-): Promise<string> {
-  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-    throw new Error('bounded read maxBytes must be a positive safe integer')
-  }
-  throwIfAborted(signal, 'read')
-  let handle: Awaited<ReturnType<typeof open>>
-  try {
-    handle = await open(
-      target.targetKey,
-      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
-    )
-  } catch (error: unknown) {
-    if (isENOENT(error)) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
-    if (isPermissionError(error)) throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
-    throw new FsError(`cannot read "${target.displayPath}" safely: ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
-  }
-  try {
-    throwIfAborted(signal, 'read')
-    const info = await handle.stat()
-    if (!info.isFile()) {
-      throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
-    }
-    if (info.size > maxBytes) {
-      throw new FsError(
-        `cannot read "${target.displayPath}": ${info.size} bytes exceeds the ${maxBytes}-byte limit`,
-        'FS_IO_ERROR',
-      )
-    }
-    const chunks: Buffer[] = []
-    let total = 0
-    for (;;) {
-      throwIfAborted(signal, 'read')
-      // Allocate in fixed internal chunks so a permissive deployment cap does
-      // not reserve that entire cap for a small file. Once exactly at the
-      // bound, one final byte detects concurrent growth without retaining it.
-      const remaining = total === maxBytes ? 1 : Math.min(64 * 1024, maxBytes - total)
-      const chunk = Buffer.allocUnsafe(remaining)
-      const { bytesRead } = await handle.read(chunk, 0, chunk.length, total)
-      if (bytesRead === 0) break
-      total += bytesRead
-      if (total > maxBytes) {
-        throw new FsError(
-          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
-          'FS_IO_ERROR',
-        )
-      }
-      chunks.push(chunk.subarray(0, bytesRead))
-    }
-    throwIfAborted(signal, 'read')
-    const bytes = chunks.length === 1 ? chunks[0] as Buffer : Buffer.concat(chunks, total)
-    if (bytes.subarray(0, BINARY_SAMPLE_BYTES).includes(0)) {
-      throw new FsError(`cannot read "${target.displayPath}": binary file`, 'FS_NOT_TEXT')
-    }
-    return decodeUtf8(bytes, 'read', target.displayPath)
-  } finally {
-    await handle.close()
-  }
-}
-
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 1a266301db..f6049b1795 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -28,7 +28,6 @@ import {
   readForEdit,
   readTextForDiff,
   readWholeText,
-  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -126,10 +125,6 @@ export class LocalFileSystem extends FileSystem {
     return readWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal)
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    return readWholeTextBounded({ displayPath: target.displayPath, targetKey: target.targetKey }, maxBytes, signal)
-  }
-
   override streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     return Promise.resolve(streamWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal))
   }
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 02beab7323..4906bb0adc 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -218,15 +218,6 @@ describe('readText / streamText', () => {
     expect(await fs.readText(await fs.resolve('a.txt'))).toBe('one\ntwo\nthree')
   })
 
-  it('reads complete text through the stable byte bound', async () => {
-    await writeFile(join(dir, 'bounded.txt'), '€abc')
-    const target = await fs.resolve('bounded.txt')
-    expect(await fs.readTextBounded(target, 6)).toBe('€abc')
-    await expect(fs.readTextBounded(target, 5)).rejects.toThrow('exceeds the 5-byte limit')
-    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
-    await expect(fs.readTextBounded(target, 6, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
-  })
-
   it('streams the same text', async () => {
     await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 2c5fd7a8f4..15588e40b9 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -5,7 +5,7 @@
  * policy and lives in `dsh-fs-policy`, so it is not tested here.
  */
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { chmod, mkdtemp, readFile, rename, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -17,7 +17,6 @@ import {
   probeNoFollow,
   readForEdit,
   readWholeText,
-  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -317,66 +316,6 @@ describe('readWholeText', () => {
   })
 })
 
-describe('readWholeTextBounded', () => {
-  it('rejects non-files, binary text, and initial oversize without a full read', async () => {
-    await expect(readWholeTextBounded(localTarget(dir), 10)).rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
-    await writeFile(join(dir, 'large'), '12345')
-    await expect(readWholeTextBounded(localTarget(join(dir, 'large')), 4)).rejects.toThrow('exceeds the 4-byte limit')
-    await writeFile(join(dir, 'binary'), Buffer.from([0x61, 0x00, 0x62]))
-    await expect(readWholeTextBounded(localTarget(join(dir, 'binary')), 3)).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
-  })
-
-  it('detects growth past the bound on the same open handle', async () => {
-    const close = vi.fn(async () => {})
-    const read = vi.fn(async (buffer: Buffer, offset: number, length: number, position: number) => {
-      const bytes = position === 0 ? Buffer.from('abc') : Buffer.from('d')
-      bytes.copy(buffer, offset, 0, Math.min(length, bytes.length))
-      return { bytesRead: Math.min(length, bytes.length), buffer }
-    })
-    vi.resetModules()
-    vi.doMock('node:fs/promises', async (importOriginal) => {
-      const actual = await importOriginal<typeof import('node:fs/promises')>()
-      return {
-        ...actual,
-        open: async () => ({
-          stat: async () => ({ isFile: () => true, size: 3 }),
-          read,
-          close,
-        }),
-      }
-    })
-    try {
-      const isolated = await import('../src/fsio.ts')
-      await expect(isolated.readWholeTextBounded(localTarget('/virtual/growing'), 3))
-        .rejects.toThrow('grew past the 3-byte limit')
-      expect(close).toHaveBeenCalledOnce()
-    } finally {
-      vi.doUnmock('node:fs/promises')
-      vi.resetModules()
-    }
-  })
-
-  it('translates permission and generic open failures', async () => {
-    const failure: { current: Error & { code?: string } } = { current: Object.assign(new Error('denied'), { code: 'EACCES' }) }
-    vi.resetModules()
-    vi.doMock('node:fs/promises', async (importOriginal) => {
-      const actual = await importOriginal<typeof import('node:fs/promises')>()
-      return { ...actual, open: async () => { throw failure.current } }
-    })
-    try {
-      const isolated = await import('../src/fsio.ts')
-      await expect(isolated.readWholeTextBounded(localTarget('/virtual/denied'), 3))
-        .rejects.toMatchObject({ code: 'FS_PERMISSION_DENIED' })
-      failure.current = new Error('open broke')
-      await expect(isolated.readWholeTextBounded(localTarget('/virtual/broken'), 3))
-        .rejects.toMatchObject({ code: 'FS_IO_ERROR' })
-    } finally {
-      vi.doUnmock('node:fs/promises')
-      vi.resetModules()
-    }
-  })
-})
-
 describe('streamWholeText', () => {
   it('streams the whole file as decoded text', async () => {
     const file = join(dir, 'a.txt')
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 4a0e675c0c..d9b5f0ebc0 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 67079f795c705ab4c9cfa476e0458be04a48c6c8
-README.zh.md: d812a94fab9f4b7e9d15ff78bd1fea3bcc00c0d9
+README.md: bf1dd1c1eb65146258cd64e450749845522e7057
+README.zh.md: f3fcc0c3794b972233dc418e93bdd80b1cc8570a
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 67079f795c..bf1dd1c1eb 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read bounded or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
 This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
@@ -17,7 +17,7 @@ A future sandboxed, virtual, or remote backend implements this interface and the
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements twelve primitives.
+A backend subclasses `FileSystem` and implements eleven primitives.
 
 | Member | Semantics |
 |---|---|
@@ -28,8 +28,7 @@ A backend subclasses `FileSystem` and implements twelve primitives.
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
 | `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
-| `readTextBounded(target, maxBytes, signal?)` | Read one complete regular UTF-8 file through a backend-owned stable operation, rejecting before retaining more than `maxBytes`. Consumers must not emulate this with `stat` then `readText`, which admits growth and replacement races. |
-| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
+| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here); consumers that need a byte ceiling enforce it while consuming the stream. |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
 | `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
 | `editText(target, edit, expected?, signal?)` | Literal edit. `expected` is OPTIONAL: omit ⇒ unconditional edit of the current content; supply `{ version }` to guard (verified BEFORE matching). A missing target reports `FS_STALE_VERSION` either way. Applies and writes atomically — one mutation critical section. |
@@ -61,6 +60,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
-- **Twelve primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **Eleven primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
 - **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index d812a94fab..f3fcc0c379 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、有界或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
 本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
@@ -17,7 +17,7 @@
 
 ## 服务 API（`ctx.fs`）
 
-后端继承 `FileSystem` 并实现十二个原语。
+后端继承 `FileSystem` 并实现十一个原语。
 
 | 成员 | 语义 |
 |---|---|
@@ -28,8 +28,7 @@
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
 | `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
-| `readTextBounded(target, maxBytes, signal?)` | 通过后端自有的稳定操作读取一个完整的普通 UTF-8 文件，在保留超过 `maxBytes` 前拒绝。消费方不得以先 `stat` 再 `readText` 模拟此操作，因为那会容许文件增长与替换竞态。 |
-| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）。 |
+| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
 | `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
@@ -61,6 +60,6 @@
 ## 已知限制与延期工作
 
 - **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
-- **只有十二个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
+- **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
 - **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index 8bb20ece18..2d46868a57 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * Filesystem provider seam for one execution world. Backends own stable target
- * identity, process paths and file URIs, containment, stable bounded text
- * reads, decoding, binary rejection, and atomic mutations. Read windows and
+ * identity, process paths and file URIs, containment, text reads, decoding,
+ * binary rejection, and atomic mutations. Read windows and
  * observed-state policy stay in consumer and policy plugins; `editText`
  * remains here so version check, literal match, and rewrite share one critical
  * section.
@@ -172,19 +172,6 @@ export abstract class FileSystem extends Service {
    */
   abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
 
-  /**
-   * Read one regular UTF-8 text file through a backend-owned stable handle,
-   * rejecting before more than `maxBytes` are retained. The size check and
-   * bytes read are one operation: a caller must not emulate this with
-   * {@link stat} followed by {@link readText}, which admits growth and path
-   * replacement races between the two calls.
-   * @param target - the resolved target to read.
-   * @param maxBytes - positive safe-integer byte ceiling.
-   * @param signal - aborts the open/read operation.
-   * @returns the complete decoded text when it fits.
-   */
-  abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>
-
   /**
    * Stream the whole regular text file as decoded text chunks (same text
    * semantics as {@link readText}, for large files). The backend owns
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index 92f1cfc37f..f225e51cc0 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -46,11 +46,6 @@ class FakeFileSystem extends FileSystem {
     if (content === undefined) throw new FsError(`not found: ${target.displayPath}`, 'FS_NOT_FOUND')
     return content
   }
-  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
-    const content = await this.readText(target)
-    if (Buffer.byteLength(content) > maxBytes) throw new FsError('too large', 'FS_IO_ERROR')
-    return content
-  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = await this.readText(target)
     return (async function* () { yield content })()
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index f54701246a..b217260972 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -67,11 +67,6 @@ class FakeFs extends FileSystem {
   override async readText(target: FsTarget): Promise<string> {
     return this.files.get(target.targetKey) ?? ''
   }
-  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
-    const content = await this.readText(target)
-    if (Buffer.byteLength(content) > maxBytes) throw new Error('too large')
-    return content
-  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = this.files.get(target.targetKey) ?? ''
     return (async function* () { yield content })()
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 5a1036a349..55a9f97165 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-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/lsp/lsp-local/README.md
-README.md: c96c4febc9d047b41789f2b7a73e3eaf4d35012b
-README.zh.md: 5bc2c3c8bb7a89afb673797f5a3b25bb9fc06748
+README.md: ad8f4bc2318a58202f9596a18d402d2c6d45dae1
+README.zh.md: ff2686856a9e518a7fa846edf700da1b32e8a114
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index c96c4febc9..ad8f4bc231 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -10,11 +10,11 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
 - Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
-- Uses a compatibility-first **transient-open** sequence per query: resolve and boundedly read the source through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
+- Uses a compatibility-first **transient-open** sequence per query: resolve and byte-bound the source while streaming it through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
 - Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel. Provider disposal aborts filesystem and protocol work, awaits workspace lookups that have not entered a queue, then drains every queue and server.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
 - Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
-- Uses `ctx.fs` canonical containment, file URIs, and stable bounded reads, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
+- Uses `ctx.fs` canonical containment, file URIs, and streamed text validation, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
 
@@ -42,7 +42,7 @@ Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: {
 
 ## Security boundary
 
-The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, no-follow/stable bounded reads, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
+The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, regular-file streaming, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Containment is evaluated before the stream opens and does not promise stable-handle identity across concurrent path replacement. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
 
 ## Model Experience
 
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 5bc2c3c8bb..ff2686856a 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -10,11 +10,11 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
 - 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析源文件并进行有界读取、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析并流式读取源文件，同时执行字节上限；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，以及位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方资源释放会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找结算，再排空所有队列并等待所有服务器结算。
 - 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
 - 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
-- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与稳定有界读取，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与流式文本校验，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -42,7 +42,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 安全边界
 
-提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、不跟随符号链接的稳定有界读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
+提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、普通文件流式读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。系统在打开流之前检查 containment，但不保证路径并发替换期间的稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
 
 ## 模型体验
 
diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index 55e13ed307..b8939a2ae4 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -1,5 +1,6 @@
 /** Filesystem-seam source access for the generic stdio LSP provider. */
 
+import { Buffer } from 'node:buffer'
 import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs'
 import { throwIfAborted } from './abort.ts'
 
@@ -58,9 +59,9 @@ export async function canonicalizeWorkspace(
 }
 
 /**
- * Resolve, contain, and atomically read one bounded query source through
- * `ctx.fs`. The provider's bounded read owns stable-handle and no-follow
- * mechanics; this layer owns only LSP-facing validation and messages.
+ * Resolve, contain, and read one byte-bounded query source through `ctx.fs`.
+ * This layer owns the LSP-specific complete-document cap while the filesystem
+ * provider owns streaming, regular-file checks, and UTF-8 validation.
  * @param fs - filesystem provider sharing the server's execution world.
  * @param filePath - absolute source path or path relative to `workspace`.
  * @param workspace - already-canonical workspace.
@@ -90,17 +91,28 @@ export async function readHostSource(
   if (!fs.contains(workspace.target, target)) {
     throw new Error(`source "${filePath}" resolves outside the workspace`)
   }
-  let text: string
+  const chunks: string[] = []
+  let bytes = 0
   try {
-    text = await fs.readTextBounded(target, maxDocumentBytes, signal)
+    // XXX(lsp-source-replacement): Revisit stable-handle identity only if a real query observes
+    // replacement between canonical containment and the provider opening this stream.
+    const stream = await fs.streamText(target, signal)
+    for await (const chunk of stream) {
+      throwIfAborted(signal)
+      bytes += Buffer.byteLength(chunk)
+      if (bytes > maxDocumentBytes) {
+        throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
+      }
+      chunks.push(chunk)
+    }
   } catch (error: unknown) {
     throwIfAborted(signal)
-    throw new Error(`source "${filePath}" could not be opened safely: ${messageOf(error)}`, { cause: error })
+    throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
   return {
     fileUrl: fs.fileUrl(target),
-    text,
+    text: chunks.join(''),
   }
 }
 
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index 3db9deb50a..eea3851414 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -161,6 +161,12 @@ describe('readHostSource', () => {
     await expect(readSource('big.ts', 10)).rejects.toThrow(/10-byte limit/)
   })
 
+  it('counts the complete UTF-8 byte length at the configured boundary', async () => {
+    await writeFile(join(ws, 'multibyte.ts'), '€abc')
+    await expect(readSource('multibyte.ts', 6)).resolves.toMatchObject({ text: '€abc' })
+    await expect(readSource('multibyte.ts', 5)).rejects.toThrow(/5-byte limit/)
+  })
+
   it('rejects a non-UTF-8 source', async () => {
     await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00]))
     await expect(readSource('bin.ts')).rejects.toThrow(/invalid UTF-8|binary file/)
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 0337b0fec2..63aea8742c 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -328,14 +328,17 @@ describe('lsp-local end to end over a fake server', () => {
     await expect(disposing).resolves.toBeUndefined()
   })
 
-  it('aborts a queued source read when the provider is disposed', async () => {
+  it('aborts a queued source stream when the provider is disposed', async () => {
     const ctx = await mount({ LSP_FAKE_DEF: 'null' })
     const fs = ctx.fs
     const started = Promise.withResolvers<AbortSignal>()
-    vi.spyOn(fs, 'readTextBounded').mockImplementation(async (_target, _maxBytes, signal) => {
+    vi.spyOn(fs, 'streamText').mockImplementation(async (_target, signal) => {
       if (signal === undefined) throw new Error('source read missing provider lifetime signal')
       started.resolve(signal)
-      return await rejectWhenAborted(signal)
+      return (async function* () {
+        await rejectWhenAborted(signal)
+        yield ''
+      })()
     })
 
     const pending = ctx.lsp.query(query('goToDefinition'))
diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 2f376707db..761f5a7d34 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -8,6 +8,8 @@
 
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp'
+import { posix, win32 } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 /** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */
 export const LSP_OPERATIONS: readonly LspOperation[] = ['goToDefinition', 'findReferences', 'goToImplementation', 'hover']
@@ -144,52 +146,31 @@ export function renderUri(uri: string, workspaceUri: string): string {
     return uri
   }
   if (workspace.protocol !== 'file:') return uri
-  const targetSegments = decodeFileSegments(target)
-  const workspaceSegments = decodeFileSegments(workspace)
-  if (targetSegments === undefined || workspaceSegments === undefined) return uri
-  const sameAuthority = target.hostname === workspace.hostname
-  const windowsWorld = isWindowsFileWorld(workspace, workspaceSegments)
-  if (windowsWorld && [...targetSegments, ...workspaceSegments].some(segment => segment.includes('\\'))) return uri
-  const inside = sameAuthority
-    && targetSegments.length >= workspaceSegments.length
-    && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
-  if (inside) {
-    const relative = targetSegments.slice(workspaceSegments.length)
-    return relative.length === 0 ? '.' : relative.join('/')
-  }
-  return absoluteUriPath(target, targetSegments, windowsWorld)
+  const drivePath = /^\/[a-z](?::|%3A)/iu
+  const windowsWorld = workspace.hostname.length > 0 || drivePath.test(workspace.pathname)
+  const targetWindowsWorld = windowsWorld && (target.hostname.length > 0 || drivePath.test(target.pathname))
+  const workspacePath = filePath(workspace, windowsWorld)
+  const targetPath = filePath(target, targetWindowsWorld)
+  if (workspacePath === undefined || targetPath === undefined) return uri
+  if (windowsWorld !== targetWindowsWorld) return targetPath
+  const path = windowsWorld ? win32 : posix
+  const relative = path.relative(workspacePath, targetPath)
+  const outside = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
+  const rendered = relative === '' ? '.' : outside ? targetPath : relative
+  return windowsWorld ? rendered.replaceAll('\\', '/') : rendered
 }
 
-/** Whether a canonical file URI names a drive path or UNC path in a Windows execution world. */
-function isWindowsFileWorld(url: URL, segments: readonly string[]): boolean {
-  return url.hostname.length > 0 || /^[A-Za-z]:$/.test(segments[0] ?? '')
-}
-
-/** Decode URI path segments while rejecting encoded POSIX separators and NUL. */
-function decodeFileSegments(url: URL): string[] | undefined {
+/** Decode a file URL for its execution world while containing malformed URL failures. */
+function filePath(url: URL, windows: boolean): string | undefined {
   try {
-    const decoded = url.pathname.split('/').map(segment => decodeURIComponent(segment))
-    if (decoded.some(segment => /[/\0]/u.test(segment))) return undefined
-    while (decoded.at(-1) === '') decoded.pop()
-    decoded.shift()
-    return decoded
+    const path = fileURLToPath(url, { windows })
+    return path.includes('\0') ? undefined : path
   } catch {
+    // `fileURLToPath` rejects malformed escapes, authorities, and encoded path separators.
     return undefined
   }
 }
 
-/** Windows execution-world path segments are case-insensitive even on a non-Windows harness host. */
-function samePathSegment(left: string, right: string, windowsWorld: boolean): boolean {
-  return windowsWorld ? left.toUpperCase() === right.toUpperCase() : left === right
-}
-
-/** Render an external file URL according to the execution-world style implied by its workspace URI. */
-function absoluteUriPath(target: URL, segments: readonly string[], windowsWorld: boolean): string {
-  if (target.hostname.length > 0) return `//${target.hostname}/${segments.join('/')}`
-  if (windowsWorld && /^[A-Za-z]:$/.test(segments[0] ?? '')) return segments.join('/')
-  return `/${segments.join('/')}`
-}
-
 /**
  * UI presentation for a pending `lsp` call. Uses a generic search card; the title carries the
  * operation and one-based cursor, and `locations` focuses the queried line. The shared location
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index f09297d3d4..2d181f25b3 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -103,6 +103,7 @@ describe('renderUri', () => {
   it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
     // An encoded path separator is invalid on every platform and must remain verbatim.
     expect(renderUri('file:///bad%2Fpath', WS_URI)).toBe('file:///bad%2Fpath')
+    expect(renderUri('file:///bad%00path', WS_URI)).toBe('file:///bad%00path')
   })
 })
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 2bd653983e..c2a0f9b647 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: bccef05ca73ec8d826621f814f232206fa9fea4b
-README.zh.md: 27d4d1193047eb1bb3bf2289697be3c0cc0253aa
+README.md: c4af7bc8293689d64c58eebab2606d4f9b52fd2f
+README.zh.md: 21075ccbf53d173a54220b58b384f01cfe50ced1
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index bccef05ca7..c4af7bc829 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,9 +8,9 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close rejects new public signals after shutdown begins, drains public signals already in flight, starts provider-owned TERM-to-KILL whole-session cleanup, and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 27d4d11930..21075ccbf5 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,9 +8,9 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方信号会转发给终端分配和就绪初始化；句柄一经发布，便负责自身生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作会在关闭开始后拒绝新的公开信号请求，等待已经在途的公开信号请求全部结算，再启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待写入结算；写入被拒绝时不会发送信号。被取消的发送会保留其槽位，直至写入和前台信号发送都结算，因此后续发送既不会收到延迟字节，也不会成为该信号的目标。取消等待期间，绝对截止时间仍保持启用。信号发送失败属于终结性传输失败，并会使当前发送被拒绝。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待句柄执行由提供方负责的完整会话终止，之后才将当前发送以 `session_exit` 结算。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 62b5fdb71a..a8d99cb243 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -101,30 +101,15 @@ export class LocalPtyBackend implements PtyBackend {
     ensureSandboxModeFence(this.ctx, spec.owner)
     const argv = spawnArgv(this.ctx, this.config, spec)
     if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    let terminalSignal: AbortSignal | undefined
-    let detachSetupSignal: (() => void) | undefined
-    if (spec.signal !== undefined) {
-      const source = spec.signal
-      const controller = new AbortController()
-      const onAbort = (): void => { controller.abort(source.reason) }
-      source.addEventListener('abort', onAbort, { once: true })
-      detachSetupSignal = () => { source.removeEventListener('abort', onAbort) }
-      terminalSignal = controller.signal
-    }
-    let terminal: SubprocessTerminalHandle
-    try {
-      terminal = await this.spawnTerminal({
-        argv,
-        cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
-        env: childEnvironment(spec),
-        rows: this.config.rows,
-        cols: this.config.cols,
-        graceMs: this.config.disposeGraceMs,
-        signal: terminalSignal,
-      })
-    } finally {
-      detachSetupSignal?.()
-    }
+    const terminal = await this.spawnTerminal({
+      argv,
+      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+      env: childEnvironment(spec),
+      rows: this.config.rows,
+      cols: this.config.cols,
+      graceMs: this.config.disposeGraceMs,
+      signal: spec.signal,
+    })
     const session = this.createSession(terminal, this.config)
     try {
       await session.initialize(spec.signal)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 08b42466aa..076f21e3b9 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -155,7 +155,7 @@ class LocalSendOperation implements PtySendOperation {
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
-  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
+  private readonly decoder = new TextDecoder()
   private readonly sanitizer: TerminalSanitizer
   private readonly scrollback: BoundedTextBuffer
   private readonly outputEnded = Promise.withResolvers<void>()
@@ -165,16 +165,13 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
-  private readonly terminalOperations = new Set<Promise<unknown>>()
-  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
-  private writing: LocalSendOperation | undefined
+  private activeWrite: { operation: LocalSendOperation; settled: Promise<boolean> } | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
-  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -239,23 +236,14 @@ export class LocalPtySession implements PtyBackendSession {
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
     this.activeDeadlineTimer = setTimeout(() => {
-      if (this.active === operation) this.settleActive('timeout', this.writing === operation)
+      if (this.active === operation) {
+        this.settleActive('timeout', this.activeWrite?.operation === operation)
+      }
     }, this.config.timeoutMs)
-    this.ownTerminalOperation(this.beginSend(operation, request))
+    void this.beginSend(operation, request)
     return operation
   }
 
-  /** Retain one contained provider operation until its asynchronous work finishes. */
-  private ownTerminalOperation(operation: Promise<void>): void {
-    void this.trackTerminalOperation(operation)
-  }
-
-  private trackTerminalOperation<T>(operation: Promise<T>): Promise<T> {
-    const tracked = operation.finally(() => { this.terminalOperations.delete(tracked) })
-    this.terminalOperations.add(tracked)
-    return tracked
-  }
-
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
     try {
       const foreground = await this.terminal.inspectForeground()
@@ -264,13 +252,20 @@ export class LocalPtySession implements PtyBackendSession {
       const input = `${request.text}${request.submit ? '\r' : ''}`
       if (input.length > 0 && !operation.cancelRequested) {
         this.resetReadinessEvidence()
-        this.writing = operation
+        const write = this.terminal.write(input)
+        const activeWrite = {
+          operation,
+          settled: write.then(() => true, () => false),
+        }
+        this.activeWrite = activeWrite
         try {
-          await this.terminal.write(Buffer.from(input, 'utf8'))
+          await write
         } finally {
-          this.writing = undefined
+          this.activeWrite = undefined
         }
       }
+      // Cancellation owns post-write signalling and reservation release.
+      if (operation.cancelRequested) return
       if (this.active === operation && operation.settled) {
         this.clearActive()
         return
@@ -282,7 +277,7 @@ export class LocalPtySession implements PtyBackendSession {
         this.schedulePoll(operation)
       }
     } catch (error: unknown) {
-      if (this.active === operation) {
+      if (this.active === operation && !this.closing) {
         if (operation.settled) this.clearActive()
         else this.failActive(error)
       }
@@ -323,8 +318,7 @@ export class LocalPtySession implements PtyBackendSession {
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
     if (this.closing) throw new Error('PTY session is closing')
-    if (this.active !== undefined) this.signaledOperation = this.active
-    const targetPgid = await this.trackTerminalOperation(this.terminal.signalForeground(signal))
+    const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
 
@@ -345,23 +339,14 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
-    try {
-      const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
-      this.onData(this.decoder.decode(bytes, { stream: true }))
-    } catch (error: unknown) {
-      this.onTransportFailure(new Error('PTY emitted invalid UTF-8', { cause: error }))
-    }
+    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+    this.onData(this.decoder.decode(bytes, { stream: true }))
   }
 
   private readonly onTerminalEnd = (): void => {
-    try {
-      this.onData(this.decoder.decode())
-      this.appendOutput(this.sanitizer.flush())
-    } catch (error: unknown) {
-      this.onTransportFailure(new Error('PTY ended with invalid UTF-8', { cause: error }))
-    } finally {
-      this.outputEnded.resolve()
-    }
+    this.onData(this.decoder.decode())
+    this.appendOutput(this.sanitizer.flush())
+    this.outputEnded.resolve()
   }
 
   private readonly onTerminalError = (error: Error): void => {
@@ -372,9 +357,9 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt && this.delayedSignaledPrompt) {
-      this.delayedSignaledPrompt = false
-    } else if (sanitized.prompt) {
+    if (sanitized.prompt) {
+      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
+      // before attributing a signal-delayed prompt to a later send.
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -402,7 +387,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.transportFailure ??= failure
     this.statusValue = { kind: 'exited', exitCode: null, signal: null }
     this.failActive(failure)
-    this.terminal.terminate()
+    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -417,7 +402,7 @@ export class LocalPtySession implements PtyBackendSession {
     if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = setTimeout(() => {
       this.activeTimer = undefined
-      this.ownTerminalOperation(this.pollReadiness(operation))
+      void this.pollReadiness(operation)
     }, delayMs)
   }
 
@@ -457,7 +442,7 @@ export class LocalPtySession implements PtyBackendSession {
         this.settleActive('inferred_idle')
       }
     } catch (error: unknown) {
-      if (this.active === operation) this.failActive(error)
+      if (this.active === operation && !this.closing) this.failActive(error)
     } finally {
       this.polling = false
       const active = this.active
@@ -470,13 +455,6 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    // A signaled command can return by silence before bash emits its prompt.
-    // Reserve that marker so it cannot become successor readiness after echo.
-    const signaled = this.signaledOperation === operation
-    if (signaled) this.signaledOperation = undefined
-    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
-      this.delayedSignaledPrompt = true
-    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -489,10 +467,14 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
-    this.activeTimer = undefined
+    this.stopReadinessPolling()
     if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
     this.activeDeadlineTimer = undefined
+  }
+
+  private stopReadinessPolling(): void {
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = undefined
     this.pollingReady = undefined
   }
 
@@ -502,43 +484,38 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
-    if (this.signaledOperation === operation) this.signaledOperation = undefined
-    this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
   }
 
-  private failActive(error: unknown, retainOwnership = false): void {
+  private failActive(error: unknown): void {
     const operation = this.active
     if (operation === undefined) return
-    if (retainOwnership) {
-      this.stopPolling()
-      this.activeAbort?.()
-      this.activeAbort = undefined
-    } else {
-      this.clearActive()
-    }
+    this.clearActive()
     operation.fail(error)
   }
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.signaledOperation = operation
     this.interrupting = operation
-    this.stopPolling()
-    this.ownTerminalOperation(this.interruptOnce(operation))
+    this.stopReadinessPolling()
+    void this.interruptOnce(operation)
   }
 
   private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
+      const activeWrite = this.activeWrite
+      if (activeWrite?.operation === operation && !await activeWrite.settled) return
       await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
-      if (this.active === operation) this.failActive(error, this.writing === operation)
+      if (this.active === operation && !this.closing) this.onTransportFailure(error)
       return
     } finally {
       if (this.interrupting === operation) this.interrupting = undefined
     }
-    if (this.active === operation && !operation.settled && !this.closing && this.writing !== operation) {
+    if (this.active === operation && operation.settled) {
+      this.clearActive()
+    } else if (this.active === operation && !this.closing) {
       this.pollingReady = operation
       this.schedulePoll(operation, 0)
     }
@@ -549,20 +526,13 @@ export class LocalPtySession implements PtyBackendSession {
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    this.terminal.terminate()
-    const quiescent = await this.terminal.waitForExit()
-    if (!quiescent) {
-      throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
+    try {
+      await this.terminal.terminate()
+    } catch (error: unknown) {
+      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
     }
-    // Quiescence is the active send's terminal outcome. Detach its abort
-    // listener before snapshotting provider operations so no late interrupt
-    // can enter the owned set after the drain starts.
+    // Quiescence is the active send's terminal outcome.
     this.settleActive('session_exit')
-    await Promise.all(this.terminalOperations)
-    // Whole-session cleanup can fail before the top-level process exits. Wait
-    // for it first so that failure is reported instead of blocking forever on
-    // `done`; successful quiescence guarantees `done` can now settle status and
-    // drain the terminal output.
     await this.completion
     this.terminal.output.off('data', this.onTerminalData)
     this.terminal.output.off('end', this.onTerminalEnd)
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 23e6f4bc89..48c8272106 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -61,8 +61,7 @@ function terminalHandle(): SubprocessTerminalHandle {
     write: async () => {},
     inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
     signalForeground: async () => 123,
-    terminate: () => { output.end() },
-    waitForExit: async () => true,
+    terminate: async () => { output.end() },
   }
 }
 
@@ -187,7 +186,7 @@ describe('LocalPtyBackend startup rollback', () => {
     expect(initialized).toHaveBeenCalledWith(undefined)
   })
 
-  it('forwards setup cancellation only while terminal allocation is unpublished', async () => {
+  it('forwards terminal allocation cancellation directly', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
@@ -204,10 +203,9 @@ describe('LocalPtyBackend startup rollback', () => {
       () => stubLocalSession(),
     )
     await published.spawn(spec(agent(ctx), publishedController.signal))
-    expect(publishedSignal).toBeDefined()
-    expect(publishedSignal).not.toBe(publishedController.signal)
+    expect(publishedSignal).toBe(publishedController.signal)
     publishedController.abort(new Error('originating turn ended'))
-    expect(publishedSignal?.aborted).toBe(false)
+    expect(publishedSignal?.aborted).toBe(true)
 
     const pendingController = new AbortController()
     const seen = Promise.withResolvers<AbortSignal>()
@@ -245,11 +243,10 @@ describe('LocalPtyBackend startup rollback', () => {
       write: async () => {},
       inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
       signalForeground: async () => 123,
-      terminate() {
+      async terminate() {
         output.end()
         outcome.resolve({ exitCode: null, signal: 'SIGTERM' })
       },
-      waitForExit: async () => true,
     }
     queueMicrotask(() => { output.write(Buffer.from('\x1b]133;D;0\x07dsh> ')) })
     const backend = new LocalPtyBackend(
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index dc03da2a63..22b07a0f8f 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -50,8 +50,8 @@ class FakeTerminal implements SubprocessTerminalHandle {
   throwWrite = false
   throwKill = false
   autoExitOnKill = true
-  quiescent = true
-  waitError: Error | undefined
+  terminateError: Error | undefined
+  private cleanup: Promise<void> | undefined
 
   constructor(public inspector = new FakeInspector()) {}
 
@@ -80,9 +80,9 @@ class FakeTerminal implements SubprocessTerminalHandle {
     })
   }
 
-  async write(data: Uint8Array): Promise<void> {
+  async write(data: string): Promise<void> {
     if (this.throwWrite) throw new Error('write failed')
-    this.writes.push(Buffer.from(data).toString('utf8'))
+    this.writes.push(data)
   }
 
   async inspectForeground() {
@@ -102,16 +102,20 @@ class FakeTerminal implements SubprocessTerminalHandle {
     return foreground.processGroupId
   }
 
-  terminate(): void {
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.terminateOnce()
+    this.cleanup = cleanup
+    void cleanup.catch(() => { this.cleanup = undefined })
+    return cleanup
+  }
+
+  private async terminateOnce(): Promise<void> {
+    if (this.terminateError !== undefined) throw this.terminateError
     if (this.throwKill) throw new Error('kill failed')
     this.kills.push('SIGTERM')
     if (this.autoExitOnKill) this.emitExit(0, 15)
   }
-
-  async waitForExit(): Promise<boolean> {
-    if (this.waitError !== undefined) throw this.waitError
-    return this.quiescent
-  }
 }
 
 function makeSession(
@@ -370,6 +374,100 @@ describe('LocalPtySession readiness and output', () => {
     expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
   })
 
+  it('signals only after an in-flight provider write lands', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'must be interrupted', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    await vi.advanceTimersByTimeAsync(20)
+    expect(inspector.groups).toEqual([])
+
+    writeGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+  })
+
+  it('does not signal when a cancelled provider write rejects', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'rejected write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+
+    const rejected = expect(operation.done).rejects.toThrow('write failed after cancellation')
+    writeGate.reject(new Error('write failed after cancellation'))
+    await rejected
+    expect(inspector.groups).toEqual([])
+
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
+  it('releases a timed-out cancellation after the provider write and signal settle', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'slow cancelled write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    await vi.advanceTimersByTimeAsync(100)
+
+    expect((await operation.done).waitReason).toBe('timeout')
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+
+    writeGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
+  it('retains the absolute timeout after cancellation while output stays active', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const operation = session.startSend({ text: 'ignore-sigint-and-write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    for (let elapsed = 20; elapsed <= 100; elapsed += 20) {
+      terminal.emitData('.')
+      await vi.advanceTimersByTimeAsync(20)
+    }
+
+    expect(await operation.done).toMatchObject({ waitReason: 'timeout' })
+  })
+
   it('does not resume cancellation polling after the terminal exits during signalling', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -437,21 +535,24 @@ describe('LocalPtySession readiness and output', () => {
 
     const writeGate = Promise.withResolvers<undefined>()
     terminal.write = async () => { await writeGate.promise }
-    terminal.signalForeground = async () => { throw new Error('interrupt failed') }
+    let signalCalls = 0
+    terminal.signalForeground = async () => {
+      signalCalls += 1
+      throw new Error('interrupt failed')
+    }
     const operation = session.startSend({ text: 'slow write', submit: true })
     await Promise.resolve()
     await Promise.resolve()
-    const rejected = expect(operation.done).rejects.toThrow('interrupt failed')
     expect(operation.cancel()).toBe(true)
-    await rejected
+    await vi.advanceTimersByTimeAsync(20)
+    expect(signalCalls).toBe(0)
     expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
 
     writeGate.resolve(undefined)
-    await Promise.resolve()
-    await Promise.resolve()
-    const next = session.startSend({ text: '', submit: false })
-    await vi.advanceTimersByTimeAsync(100)
-    expect((await next.done).waitReason).toBe('inferred_idle')
+    await expect(operation.done).rejects.toThrow('interrupt failed')
+    expect(signalCalls).toBe(1)
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
   })
 
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
@@ -591,35 +692,6 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
-  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
-    await initialize(session, terminal)
-
-    const interrupted = session.startSend({ text: 'sleep', submit: true })
-    await Promise.resolve()
-    await Promise.resolve()
-    await session.signal('SIGINT')
-    await vi.advanceTimersByTimeAsync(50)
-    expect((await interrupted.done).waitReason).toBe('inferred_idle')
-
-    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
-    let settled = false
-    void successor.done.then(() => { settled = true })
-    await Promise.resolve()
-    await Promise.resolve()
-    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    expect(settled).toBe(false)
-
-    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    const result = await successor.done
-    expect(result.waitReason).toBe('stdin_read')
-    expect(result.viewport).toContain('PID=123')
-  })
-
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -683,6 +755,7 @@ describe('LocalPtySession readiness and output', () => {
 
   it('contains terminal transport failures and preserves the first failure', async () => {
     const terminal = new FakeTerminal()
+    terminal.terminateError = new Error('cleanup after transport failure')
     const session = new LocalPtySession(terminal, config())
     const operation = session.startSend({ text: '', submit: false })
     terminal.output.emit('data', 'plain text')
@@ -691,6 +764,7 @@ describe('LocalPtySession readiness and output', () => {
       .onTransportFailure(new Error('later failure'))
     await expect(operation.done).rejects.toThrow('output transport failed')
     expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    terminal.terminateError = undefined
     await expect(session.close('transport')).rejects.toThrow('output transport failed')
 
     const rejectedTerminal = new FakeTerminal()
@@ -700,19 +774,21 @@ describe('LocalPtySession readiness and output', () => {
     await expect(rejectedOperation.done).rejects.toThrow('raw transport failure')
   })
 
-  it('rejects invalid UTF-8 in a data chunk and at stream end', async () => {
+  it('replaces invalid UTF-8 terminal output', async () => {
     const chunkTerminal = new FakeTerminal()
     const chunkSession = new LocalPtySession(chunkTerminal, config())
     const chunkOperation = chunkSession.startSend({ text: '', submit: false })
     chunkTerminal.emitBytes(Uint8Array.from([0xff]))
-    await expect(chunkOperation.done).rejects.toThrow('PTY emitted invalid UTF-8')
+    expect(chunkOperation.readOutput()).toEqual({ delta: '�', truncated: false })
+    chunkTerminal.emitExit()
+    await chunkOperation.done
 
     const endTerminal = new FakeTerminal()
     const endSession = new LocalPtySession(endTerminal, config())
     const endOperation = endSession.startSend({ text: '', submit: false })
     endTerminal.emitBytes(Uint8Array.from([0xe2]))
     endTerminal.emitExit()
-    await expect(endOperation.done).rejects.toThrow('PTY ended with invalid UTF-8')
+    expect((await endOperation.done).viewport).toBe('�')
   })
 
   it('contains readiness inspection failure and a stale inspection result', async () => {
@@ -952,43 +1028,32 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
   })
 
-  it('drains an in-flight public signal and rejects signals after close starts', async () => {
+  it('closes idempotently and rejects new signals', async () => {
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config())
-    const signal = Promise.withResolvers<number>()
-    terminal.signalForeground = async () => await signal.promise
-
-    const signaling = session.signal('SIGINT')
-    const closing = session.close('public signal')
-    let closed = false
-    void closing.then(() => { closed = true })
-    await Promise.resolve()
-    expect(closed).toBe(false)
-    await expect(session.signal('SIGTERM')).rejects.toThrow('closing')
-
-    signal.resolve(456)
-    await expect(signaling).resolves.toEqual({ delivered: true, targetPgid: 456 })
-    await closing
-    expect(closed).toBe(true)
-  })
-
-  it('closes idempotently, contains signal races, and reports survivors', async () => {
-    const terminal = new FakeTerminal()
-    terminal.quiescent = false
+    terminal.throwKill = true
     const session = new LocalPtySession(terminal, config({ disposeGraceMs: 1 }))
     const closing = session.close('test')
     expect(session.close('other')).toBe(closing)
-    await expect(closing).rejects.toThrow('did not reach quiescence')
+    await expect(closing).rejects.toThrow('PTY cleanup failed (test)')
     expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
+    await expect(session.signal('SIGTERM')).rejects.toThrow('closing')
   })
 
-  it('reports cleanup failure without waiting for top-level exit', async () => {
+  it('reports cleanup failure without waiting for top-level exit and permits retry', async () => {
     const terminal = new FakeTerminal()
     terminal.autoExitOnKill = false
-    terminal.waitError = new Error('terminal cleanup failed; surviving pids: 456')
+    terminal.terminateError = new Error('terminal cleanup failed; surviving pids: 456')
     const session = new LocalPtySession(terminal, config())
 
-    await expect(session.close('survivor')).rejects.toThrow('surviving pids: 456')
+    await expect(session.close('survivor')).rejects.toMatchObject({
+      message: 'PTY cleanup failed (survivor)',
+      cause: terminal.terminateError,
+    })
+    expect(terminal.kills).toEqual([])
+
+    terminal.terminateError = undefined
+    terminal.autoExitOnKill = true
+    await expect(session.close('retry')).resolves.toBeUndefined()
     expect(terminal.kills).toEqual(['SIGTERM'])
   })
 
@@ -1010,73 +1075,25 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await closing
   })
 
-  it('does not finish close while a pre-write terminal operation is pending', async () => {
+  it('settles a closing send when provider termination cancels inspection', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const session = new LocalPtySession(terminal, config())
     await initialize(session, terminal)
-
     const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
     terminal.inspectForeground = async () => await inspection.promise
-    const operation = session.startSend({ text: 'must not run', submit: true })
-    const closing = session.close('pending inspection')
-    let closed = false
-    void closing.then(() => { closed = true })
+    const terminate = terminal.terminate.bind(terminal)
+    terminal.terminate = async () => {
+      inspection.reject(new Error('terminal terminated'))
+      await terminate()
+    }
+    const operation = session.startSend({ text: 'pending inspection', submit: true })
     await Promise.resolve()
-    await Promise.resolve()
-    expect(closed).toBe(false)
 
-    inspection.resolve({ processGroupId: 456, inputWaiting: false })
-    await closing
-    expect(closed).toBe(true)
+    await session.close('pending inspection')
+
+    expect((await operation.done).waitReason).toBe('session_exit')
     expect(terminal.writes).toEqual([])
-    expect((await operation.done).waitReason).toBe('session_exit')
-  })
-
-  it('does not finish close while a terminal write is pending', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config())
-    await initialize(session, terminal)
-
-    const write = Promise.withResolvers<undefined>()
-    terminal.write = async () => { await write.promise }
-    const operation = session.startSend({ text: 'pending write', submit: true })
-    await Promise.resolve()
-    await Promise.resolve()
-    const closing = session.close('pending write')
-    let closed = false
-    void closing.then(() => { closed = true })
-    await Promise.resolve()
-    await Promise.resolve()
-    expect(closed).toBe(false)
-
-    write.resolve(undefined)
-    await closing
-    expect(closed).toBe(true)
-    expect((await operation.done).waitReason).toBe('session_exit')
-  })
-
-  it('detaches active cancellation before draining terminal operations', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config())
-    await initialize(session, terminal)
-
-    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
-    terminal.inspectForeground = async () => await inspection.promise
-    const signalForeground = vi.spyOn(terminal, 'signalForeground')
-    const controller = new AbortController()
-    const operation = session.startSend({ text: 'pending inspection', submit: true, signal: controller.signal })
-    const closing = session.close('pending cancellation')
-    await Promise.resolve()
-    await Promise.resolve()
-
-    controller.abort('late cancellation')
-    expect(signalForeground).not.toHaveBeenCalled()
-    inspection.resolve({ processGroupId: 456, inputWaiting: false })
-    await closing
-    expect((await operation.done).waitReason).toBe('session_exit')
   })
 
 })
diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts
index 9dc723fb58..75f4a4ed65 100644
--- a/packages/skill/skill-local/tests/skill-local.spec.ts
+++ b/packages/skill/skill-local/tests/skill-local.spec.ts
@@ -92,12 +92,6 @@ class TestFileSystem extends FileSystem {
     return text
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    const text = await this.readText(target, signal)
-    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
-    return text
-  }
-
   override async streamText(_target: FsTarget): Promise<AsyncIterable<string>> {
     throw new Error('not needed in skill tests')
   }
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index ded1d12b30..d34e7475f9 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 9f30fa6dc676e7b82f87b75b78b7d3143f204c94
-README.zh.md: 0b6813ec7d754f42e8bf4c65a1dee33d77bf3787
+README.md: 31c5539750c4af2b1c4169ac1dce4c91da587af7
+README.zh.md: 74aed52084c0db3ed9bfe4fcb991f781976fb7b5
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 9f30fa6dc6..31c5539750 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -11,7 +11,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 0b6813ec7d..74aed52084 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，并公开一项须等待的终止操作，该操作会在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 0d71cb0e33..0d02f0e387 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -59,12 +59,7 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
       }
       for (const terminal of this.terminals) {
-        terminal.terminate()
-        // Cleanup may reject before the top-level process exits (for example,
-        // an identity-fenced descendant survives escalation). Await the cleanup
-        // transaction directly so disposal reports that failure rather than
-        // waiting forever on `done`.
-        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
+        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
       const outcomes = [
@@ -136,11 +131,6 @@ export class LocalSubprocessService extends SubprocessService {
     if (file === undefined || file.length === 0) {
       throw new Error('subprocess-local: terminal argv must contain a program')
     }
-    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
-      if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`subprocess-local: terminal ${name} must be a positive safe integer`)
-      }
-    }
     spec.signal?.throwIfAborted()
     const options: IPtyForkOptions = {
       name: 'dumb',
@@ -151,10 +141,10 @@ export class LocalSubprocessService extends SubprocessService {
     }
     const inspector = this.terminalInspector ?? createProcessInspector()
     const terminal = nodePty.spawn(file, [...spec.argv.slice(1)], options)
-    const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs, spec.signal)
+    const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs)
     this.terminals.add(handle)
     const release = async (): Promise<void> => {
-      await handle.waitForExit()
+      await handle.terminate()
       this.terminals.delete(handle)
     }
     void handle.done.then(release, release).catch(() => {})
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 30e38bd422..93b7a8fc2e 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -4,7 +4,6 @@ import { Buffer } from 'node:buffer'
 import { constants } from 'node:os'
 import { PassThrough } from 'node:stream'
 import type { IDisposable, IPty } from 'node-pty'
-import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -34,7 +33,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
   private readonly dataDisposable: IDisposable
   private readonly exitDisposable: IDisposable
-  private readonly lifecycle: SubprocessTerminalLifecycle
+  private cleanup: Promise<void> | undefined
   private exited = false
   private trackedDescendants: ProcessIdentity[] = []
 
@@ -42,13 +41,11 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
    * @param terminal - allocated node-pty process.
    * @param inspector - platform process/session operations.
    * @param graceMs - TERM-to-KILL and exit-wait grace.
-   * @param signal - optional lifetime cancellation.
    */
   constructor(
     private readonly terminal: IPty,
     private readonly inspector: ProcessInspector,
     private readonly graceMs: number,
-    signal?: AbortSignal,
   ) {
     this.pid = terminal.pid
     this.done = this.outcome.promise
@@ -61,26 +58,15 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
         exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
         signal: signalName(exitSignal),
       })
-      this.terminate()
-    })
-    this.lifecycle = new SubprocessTerminalLifecycle({
-      done: this.done,
-      cleanup: () => this.closeOnce(),
-      signal,
+      void this.terminate().catch(() => {})
     })
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
   // eslint-disable-next-line @typescript-eslint/require-await
-  async write(data: Uint8Array): Promise<void> {
+  async write(data: string): Promise<void> {
     if (this.exited) throw new Error('terminal process has exited')
-    let text: string
-    try {
-      text = new TextDecoder('utf-8', { fatal: true }).decode(data)
-    } catch (error: unknown) {
-      throw new Error('terminal input must be valid UTF-8', { cause: error })
-    }
-    this.terminal.write(text)
+    this.terminal.write(data)
   }
 
   // Local inspection is synchronous; the seam returns a promise for remote transports.
@@ -107,12 +93,12 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
     return foreground.processGroupId
   }
 
-  terminate(): void {
-    this.lifecycle.terminate()
-  }
-
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    return await this.lifecycle.waitForExit(signal)
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.closeOnce()
+    this.cleanup = cleanup
+    void cleanup.catch(() => { this.cleanup = undefined })
+    return cleanup
   }
 
   private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index e4dd4cfb44..e58c66f7fa 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -81,7 +81,7 @@ describe('LocalSubprocessService', () => {
     }
   })
 
-  it('validates terminal spawn specs before allocating a PTY', async () => {
+  it('validates terminal allocation inputs before allocating a PTY', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const base: SubprocessTerminalSpawnSpec = {
@@ -89,9 +89,6 @@ describe('LocalSubprocessService', () => {
     }
     await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [] })).rejects.toThrow('must contain a program')
     await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [''] })).rejects.toThrow('must contain a program')
-    await expect(ctx.subprocess.spawnTerminal({ ...base, rows: 1.5 })).rejects.toThrow('rows')
-    await expect(ctx.subprocess.spawnTerminal({ ...base, cols: 0 })).rejects.toThrow('cols')
-    await expect(ctx.subprocess.spawnTerminal({ ...base, graceMs: 0 })).rejects.toThrow('graceMs')
     await expect(ctx.subprocess.spawnTerminal({ ...base, signal: AbortSignal.abort('stop') })).rejects.toBe('stop')
     await fiber.dispose()
   })
@@ -99,8 +96,7 @@ describe('LocalSubprocessService', () => {
   it('terminates and joins an owned terminal during disposal', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
-    const terminate = vi.fn()
-    const waitForExit = vi.fn(async () => true)
+    const terminate = vi.fn(async () => {})
     const terminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
@@ -109,13 +105,11 @@ describe('LocalSubprocessService', () => {
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
       terminate,
-      waitForExit,
     }
     const terminals = (ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(terminal)
     await fiber.dispose()
     expect(terminate).toHaveBeenCalledOnce()
-    expect(waitForExit).toHaveBeenCalledOnce()
     expect(terminals.size).toBe(0)
   })
 
@@ -124,8 +118,8 @@ describe('LocalSubprocessService', () => {
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
     const runtimeRoot = service.runtimeRoot
-    const firstFailure = new Error('first retryable cleanup failure')
-    const secondFailure = new Error('second retryable cleanup failure')
+    const firstFailure = new Error('first cleanup failure')
+    const secondFailure = new Error('second cleanup failure')
     const disposalErrors: unknown[] = []
     ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
     const failedTerminal: SubprocessTerminalHandle = {
@@ -135,22 +129,19 @@ describe('LocalSubprocessService', () => {
       write: async () => {},
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw firstFailure }),
+      terminate: vi.fn(async () => { throw firstFailure }),
     }
     const secondFailedTerminal: SubprocessTerminalHandle = {
       ...failedTerminal,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw secondFailure }),
+      terminate: vi.fn(async () => { throw secondFailure }),
     }
     let finishCleanup!: () => void
-    const cleanup = new Promise<boolean>((resolve) => {
-      finishCleanup = () => { resolve(true) }
+    const cleanup = new Promise<void>((resolve) => {
+      finishCleanup = resolve
     })
     const drainingTerminal: SubprocessTerminalHandle = {
       ...failedTerminal,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(() => cleanup),
+      terminate: vi.fn(() => cleanup),
     }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(failedTerminal)
@@ -187,8 +178,7 @@ describe('LocalSubprocessService', () => {
       write: async () => {},
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw failure }),
+      terminate: vi.fn(async () => { throw failure }),
     }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(terminal)
@@ -247,7 +237,7 @@ describe('LocalSubprocessService', () => {
     }
   })
 
-  it('contains a terminal release failure after top-level exit', async () => {
+  it('retains a terminal whose automatic cleanup fails', async () => {
     let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
     const terminal = {
       pid: 123,
@@ -264,6 +254,8 @@ describe('LocalSubprocessService', () => {
     try {
       const { default: IsolatedLocalSubprocessService } = await import('../src/index.ts')
       const ctx = new Context()
+      const disposalErrors: unknown[] = []
+      ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
       const fiber = await ctx.plugin(IsolatedLocalSubprocessService)
       const alive = new Set([124])
       ;(ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>).terminalInspector = {
@@ -281,10 +273,9 @@ describe('LocalSubprocessService', () => {
       exitListener?.({ exitCode: 0 })
       await handle.done
       await new Promise(resolve => setTimeout(resolve, 10))
-      alive.clear()
-      handle.terminate()
-      await handle.waitForExit()
+      expect((ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.size).toBe(1)
       await fiber.dispose()
+      expect(disposalErrors).toHaveLength(1)
     } finally {
       vi.doUnmock('node-pty')
       vi.resetModules()
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 456ce4ee8f..2eeb7c6a27 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -89,7 +89,7 @@ describe('LocalTerminalHandle', () => {
     handle.output.on('data', (chunk: Buffer) => { chunks.push(chunk) })
 
     pty.emitData('hello €')
-    await handle.write(Buffer.from('input\r'))
+    await handle.write('input\r')
     expect(pty.writes).toEqual(['input\r'])
     expect(await handle.inspectForeground()).toEqual({ processGroupId: 456, inputWaiting: true })
     expect(await handle.signalForeground('SIGINT')).toBe(456)
@@ -98,16 +98,14 @@ describe('LocalTerminalHandle', () => {
     pty.emitExit(7, 9)
     pty.emitExit(0)
     expect(await handle.done).toEqual({ exitCode: null, signal: 'SIGKILL' })
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
     expect(Buffer.concat(chunks).toString('utf8')).toBe('hello €')
   })
 
-  it('rejects invalid input and unsafe foreground signals', async () => {
+  it('rejects unsafe foreground signals and writes after exit', async () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
-    await expect(handle.write(Uint8Array.from([0xff]))).rejects.toThrow('valid UTF-8')
-
     inspector.pgid = handle.pid
     await expect(handle.signalForeground('SIGKILL')).rejects.toThrow('terminate the terminal session')
     inspector.pgid = undefined
@@ -116,8 +114,8 @@ describe('LocalTerminalHandle', () => {
 
     pty.emitExit(3)
     expect(await handle.done).toEqual({ exitCode: 3, signal: null })
-    await handle.waitForExit()
-    await expect(handle.write(Buffer.from('late'))).rejects.toThrow('has exited')
+    await handle.terminate()
+    await expect(handle.write('late')).rejects.toThrow('has exited')
   })
 
   it('keeps the shell alive until forced descendants leave', async () => {
@@ -129,15 +127,14 @@ describe('LocalTerminalHandle', () => {
     inspector.removeOnSignal = false
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
 
-    handle.terminate()
-    const quiescent = handle.waitForExit()
+    const quiescent = handle.terminate()
     await vi.advanceTimersByTimeAsync(20)
     expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
     expect(pty.kills).toEqual([])
 
     inspector.alive.delete(124)
     await vi.advanceTimersByTimeAsync(20)
-    expect(await quiescent).toBe(true)
+    await quiescent
     expect(pty.kills).toEqual(['SIGTERM'])
   })
 
@@ -149,17 +146,16 @@ describe('LocalTerminalHandle', () => {
     inspector.alive.add(124)
     inspector.removeOnSignal = false
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
-    const waiting = handle.waitForExit()
+    pty.emitExit()
+    const waiting = handle.terminate()
     let settled = false
     void waiting.then(() => { settled = true })
-
-    pty.emitExit()
     await vi.advanceTimersByTimeAsync(10)
     expect(settled).toBe(false)
 
     inspector.alive.delete(124)
     await vi.advanceTimersByTimeAsync(20)
-    expect(await waiting).toBe(true)
+    await waiting
   })
 
   it('cleans a same-session descendant after the top-level shell exits naturally', async () => {
@@ -172,7 +168,7 @@ describe('LocalTerminalHandle', () => {
 
     pty.emitExit()
 
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
     expect(inspector.processes).toEqual([[124, 'SIGTERM']])
   })
 
@@ -188,7 +184,7 @@ describe('LocalTerminalHandle', () => {
     inspector.members = []
     pty.emitExit()
 
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
     expect(inspector.processes).toEqual([[124, 'SIGTERM']])
   })
 
@@ -209,8 +205,7 @@ describe('LocalTerminalHandle', () => {
       return []
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
-    handle.terminate()
-    await handle.waitForExit()
+    await handle.terminate()
     expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
     expect(pty.kills).toEqual(['SIGTERM'])
   })
@@ -225,14 +220,13 @@ describe('LocalTerminalHandle', () => {
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
 
-    handle.terminate()
-    await handle.waitForExit()
+    await handle.terminate()
 
     expect(inspector.processes).toEqual([[late.pid, 'SIGTERM']])
     expect(pty.kills).toEqual(['SIGTERM'])
   })
 
-  it('keeps a failed post-shell sweep retryable until its survivor leaves', async () => {
+  it('retries failed cleanup after a surviving descendant leaves', async () => {
     vi.useFakeTimers()
     const pty = new FakePty()
     const inspector = new FakeInspector()
@@ -244,14 +238,15 @@ describe('LocalTerminalHandle', () => {
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
 
-    handle.terminate()
-    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
+    const first = handle.terminate()
+    const failed = expect(first).rejects.toThrow('surviving pids: 124')
     await vi.advanceTimersByTimeAsync(25)
     await failed
 
     inspector.alive.delete(late.pid)
-    handle.terminate()
-    expect(await handle.waitForExit()).toBe(true)
+    const retry = handle.terminate()
+    expect(retry).not.toBe(first)
+    await retry
     expect(inspector.processes).toEqual([[late.pid, 'SIGTERM'], [late.pid, 'SIGKILL']])
   })
 
@@ -268,82 +263,35 @@ describe('LocalTerminalHandle', () => {
       if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
-    handle.terminate()
-    const quiescent = handle.waitForExit()
+    const quiescent = handle.terminate()
     await vi.advanceTimersByTimeAsync(25)
-    expect(await quiescent).toBe(true)
+    await quiescent
     expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
   })
 
-  it('allows cleanup to retry after a surviving descendant leaves', async () => {
-    vi.useFakeTimers()
-    const pty = new FakePty()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 124, started: 'child' }]
-    inspector.alive.add(124)
-    inspector.removeOnSignal = false
-    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
-
-    handle.terminate()
-    const first = expect(handle.waitForExit(new AbortController().signal)).rejects.toThrow('surviving pids: 124')
-    await vi.advanceTimersByTimeAsync(25)
-    await first
-
-    inspector.alive.delete(124)
-    handle.terminate()
-    expect(await handle.waitForExit()).toBe(true)
-    expect(pty.kills).toEqual(['SIGTERM'])
-  })
-
-  it('bounds waits and reports a top-level process that ignores escalation', async () => {
+  it('reports a top-level process that ignores escalation', async () => {
     vi.useFakeTimers()
     const pty = new FakePty()
     pty.autoExitOnKill = false
     const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10)
-    expect(await handle.waitForExit(AbortSignal.abort())).toBe(false)
-    const controller = new AbortController()
-    const bounded = handle.waitForExit(controller.signal)
-    controller.abort()
-    expect(await bounded).toBe(false)
-
-    handle.terminate()
-    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pid: 123')
+    const failed = expect(handle.terminate()).rejects.toThrow('surviving pid: 123')
     await vi.advanceTimersByTimeAsync(25)
     await failed
     expect(pty.kills).toEqual(['SIGTERM', 'SIGKILL'])
 
     pty.emitExit(0, 999)
     expect(await handle.done).toEqual({ exitCode: null, signal: null })
-    handle.terminate()
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
   })
 
-  it('contains process races and reacts to lifetime cancellation', async () => {
+  it('contains process races while reporting surviving descendants', async () => {
     const pty = new FakePty()
     pty.throwKill = true
     const inspector = new FakeInspector()
     inspector.members = [{ pid: 124, started: 'child' }]
     inspector.alive.add(124)
     inspector.throwProcess = true
-    const controller = new AbortController()
-    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 1, controller.signal)
-    controller.abort()
-    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
-    await failed
-
-    inspector.alive.delete(124)
-    pty.throwKill = false
-    handle.terminate()
-    await handle.waitForExit()
-
-    const preAbortedPty = new FakePty()
-    const preAborted = new LocalTerminalHandle(
-      preAbortedPty.asPty(),
-      new FakeInspector(),
-      1,
-      AbortSignal.abort('stop'),
-    )
-    await preAborted.waitForExit()
-    expect(preAbortedPty.kills).toEqual(['SIGTERM'])
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 1)
+    await expect(handle.terminate()).rejects.toThrow('surviving pids: 124')
   })
 })
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 8e6c6a88e4..f8678464a9 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: d03824da33bb44b2525b1343a27557ed15823418
-README.zh.md: 34cc75c3cfc8148754343e92b0c204760b1fb543
+README.md: 2fca5cdd08f3cbd36d8ef492226c91681b5568d0
+README.zh.md: 5830d0fc394160bc557e24646cc76d4bcfead13c
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index d03824da33..2fca5cdd08 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -11,8 +11,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, valid-UTF-8 byte I/O, foreground-process-group inspection/signalling, TERM-to-KILL whole-session cleanup, and a quiescence wait. The output stream ends after queued output when the top-level process exits; a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or prove and clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
-- `SubprocessTerminalLifecycle` composes a handle's top-level `done` promise with its provider-owned session cleanup. It binds lifetime cancellation, shares one active cleanup attempt, permits a failed attempt to retry, normalizes cleanup rejections, and bounds quiescence observation without knowing the provider's process mechanics.
+- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches whole-session quiescence and settles in-flight handle calls. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 34cc75c3cf..5830d0fc39 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -11,8 +11,7 @@
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、有效 UTF-8 字节 I/O、前台进程组检查／信号发送、TERM→KILL 全会话清理，以及等待完全停稳。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法证明并清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
-- `SubprocessTerminalLifecycle` 把句柄的顶层 `done` promise 与由提供方负责的会话清理组合起来。它绑定生命周期取消，共享同一个进行中的清理尝试，允许失败的尝试重试，规范化清理拒绝，并在不了解提供方进程机制的情况下对完全停稳观测施加上限。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使整个会话完全停稳，并让所有在途句柄调用结算。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index df79ee5f3e..e1749203dd 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -14,8 +14,6 @@ import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts'
 import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts'
 
 export { DSH_ENV_PREFIX } from './types.ts'
-export { SubprocessTerminalLifecycle } from './terminal-lifecycle.ts'
-export type { SubprocessTerminalLifecycleOptions } from './terminal-lifecycle.ts'
 export type {
   CollectedOutput,
   DshEnvironment,
@@ -95,10 +93,11 @@ declare module 'cordis' {
  *   quiescence.
  * - Disposal of the service terminates all still-running managed processes
  *   and awaits their exit.
- * - {@link spawnTerminal} owns terminal allocation, byte transport,
- *   foreground groups, signalling, and whole-session quiescence; readiness
- *   and persistent-shell policy stay in the PTY consumer. Its output stream
- *   ends after queued terminal output when the top-level process exits.
+ * - {@link spawnTerminal} owns terminal allocation, text transport,
+ *   foreground groups, signalling, and whole-session quiescence behind one
+ *   awaited termination method; readiness and persistent-shell policy stay
+ *   in the PTY consumer. Its output stream ends after queued terminal output
+ *   when the top-level process exits.
  */
 export abstract class SubprocessService extends Service {
   constructor(ctx: Context) {
@@ -138,7 +137,7 @@ export abstract class SubprocessService extends Service {
    * Allocate a real terminal and start one owned process session. This is the
    * only non-pipe process primitive: implementations own terminal byte I/O,
    * foreground groups, signals, and complete session-tree cleanup.
-   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.
+   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
    * @returns the live terminal handle after allocation succeeds.
    */
   abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
diff --git a/packages/subprocess/subprocess/src/terminal-lifecycle.ts b/packages/subprocess/subprocess/src/terminal-lifecycle.ts
deleted file mode 100644
index 76430fe7c6..0000000000
--- a/packages/subprocess/subprocess/src/terminal-lifecycle.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-/** Provider-neutral lifecycle transaction for terminal-process handles. */
-
-/** Inputs owned by one terminal-process lifecycle controller. */
-export interface SubprocessTerminalLifecycleOptions {
-  /** Settlement of the top-level terminal process or its live transport. */
-  readonly done: Promise<unknown>
-  /** Provider-owned cleanup that reaches whole-session quiescence. */
-  readonly cleanup: () => Promise<void>
-  /** Optional cancellation for the complete terminal lifetime. */
-  readonly signal?: AbortSignal | undefined
-}
-
-function normalizeCleanupError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
-/**
- * Coordinates terminal cleanup without knowing how a provider allocates or
- * terminates its process session. One active cleanup attempt is shared by all
- * callers; a rejected attempt may be retried, and successful cleanup removes
- * the lifetime abort listener.
- */
-export class SubprocessTerminalLifecycle {
-  private cleanupAttempt: Promise<void> | undefined
-  private removeLifetimeAbort: (() => void) | undefined
-
-  /**
-   * @param options - top-level settlement, provider cleanup, and lifetime cancellation.
-   */
-  constructor(private readonly options: SubprocessTerminalLifecycleOptions) {
-    const onDone = (): void => { this.terminate() }
-    void options.done.then(onDone, onDone)
-
-    if (options.signal !== undefined) {
-      const onAbort = (): void => { this.terminate() }
-      options.signal.addEventListener('abort', onAbort, { once: true })
-      this.removeLifetimeAbort = () => { options.signal?.removeEventListener('abort', onAbort) }
-      if (options.signal.aborted) this.terminate()
-    }
-  }
-
-  /** Begin an idempotent provider cleanup attempt. */
-  terminate(): void {
-    void this.startCleanup().catch(() => {})
-  }
-
-  /**
-   * Wait for top-level settlement and successful whole-session cleanup.
-   * @param signal - optional bound for this observation only.
-   * @returns true after quiescence, false when the observer signal aborts first.
-   */
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    const quiescence = this.cleanupAttempt ?? this.options.done.then(
-      () => this.startCleanup(),
-      () => this.startCleanup(),
-    )
-    if (signal === undefined) {
-      await quiescence
-      return true
-    }
-    if (signal.aborted) return false
-
-    return await new Promise<boolean>((resolve, reject) => {
-      let settled = false
-      const finish = (complete: () => void): void => {
-        if (settled) return
-        settled = true
-        signal.removeEventListener('abort', onAbort)
-        complete()
-      }
-      const onAbort = (): void => { finish(() => { resolve(false) }) }
-
-      signal.addEventListener('abort', onAbort, { once: true })
-      if (signal.aborted) onAbort()
-      void quiescence.then(
-        () => { finish(() => { resolve(true) }) },
-        (error: unknown) => { finish(() => { reject(normalizeCleanupError(error)) }) },
-      )
-    })
-  }
-
-  private startCleanup(): Promise<void> {
-    if (this.cleanupAttempt !== undefined) return this.cleanupAttempt
-
-    const outcome = Promise.withResolvers<void>()
-    this.cleanupAttempt = outcome.promise.catch((error: unknown) => {
-      this.cleanupAttempt = undefined
-      throw normalizeCleanupError(error)
-    })
-    void this.cleanupAttempt.then(
-      () => {
-        this.removeLifetimeAbort?.()
-        this.removeLifetimeAbort = undefined
-      },
-      () => {},
-    )
-    try {
-      void this.options.cleanup().then(outcome.resolve, outcome.reject)
-    } catch (error: unknown) {
-      outcome.reject(error)
-    }
-    return this.cleanupAttempt
-  }
-}
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 206104ad5b..6b606fd870 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -210,7 +210,7 @@ export interface SubprocessTerminalSpawnSpec {
   cols: number
   /** TERM-to-KILL cleanup grace for the complete terminal session. */
   graceMs: number
-  /** Cancellation of setup or the live terminal session. */
+  /** Cancellation of terminal allocation; a published handle owns its later lifetime. */
   signal?: AbortSignal | undefined
 }
 
@@ -236,10 +236,10 @@ export interface SubprocessTerminalHandle {
   /** Resolves when the top-level process exits; rejects only for a live transport failure. */
   readonly done: Promise<SubprocessOutcome>
   /**
-   * Write bytes to the terminal input.
-   * @param data - valid UTF-8 bytes to deliver without implicit newline conversion.
+   * Write text to the terminal input.
+   * @param data - text to deliver without implicit newline conversion.
    */
-  write(data: Uint8Array): Promise<void>
+  write(data: string): Promise<void>
   /**
    * Inspect the current foreground process group.
    * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
@@ -251,12 +251,9 @@ export interface SubprocessTerminalHandle {
    * @returns the exact group id that received it.
    */
   signalForeground(signal: SubprocessTerminalSignal): Promise<number>
-  /** Begin idempotent TERM-to-KILL cleanup of the complete terminal session. */
-  terminate(): void
   /**
-   * Await whole-session quiescence, not only top-level process exit.
-   * @param signal - optional bound for this wait.
-   * @returns true after quiescence, false when `signal` aborts first.
+   * Idempotently terminate the complete terminal session and await whole-session quiescence.
+   * After settlement, no write, inspection, or signal call remains in flight.
    */
-  waitForExit(signal?: AbortSignal): Promise<boolean>
+  terminate(): Promise<void>
 }
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index 853b333400..9f321caf54 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -48,8 +48,7 @@ class StubSubprocessService extends SubprocessService {
       write: async () => {},
       inspectForeground: async () => ({ processGroupId: 1, inputWaiting: true }),
       signalForeground: async () => 1,
-      terminate: () => {},
-      waitForExit: async () => true,
+      terminate: async () => {},
     }
   }
 }
diff --git a/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts b/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
deleted file mode 100644
index 2dd688bbc0..0000000000
--- a/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
-
-describe('SubprocessTerminalLifecycle', () => {
-  it('waits for top-level settlement and the provider cleanup transaction', async () => {
-    const done = Promise.withResolvers<undefined>()
-    const cleanupGate = Promise.withResolvers<undefined>()
-    const cleanup = vi.fn(() => cleanupGate.promise)
-    const lifecycle = new SubprocessTerminalLifecycle({ done: done.promise, cleanup })
-
-    const waiting = lifecycle.waitForExit()
-    expect(cleanup).not.toHaveBeenCalled()
-    done.resolve(undefined)
-    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
-
-    const observed = vi.fn()
-    void waiting.then(observed)
-    await Promise.resolve()
-    expect(observed).not.toHaveBeenCalled()
-
-    cleanupGate.resolve(undefined)
-    await expect(waiting).resolves.toBe(true)
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-    expect(cleanup).toHaveBeenCalledOnce()
-  })
-
-  it('normalizes cleanup failures, permits retries, and retains lifetime cancellation until success', async () => {
-    const done = Promise.withResolvers<undefined>()
-    const lifetime = new AbortController()
-    const removeListener = vi.spyOn(lifetime.signal, 'removeEventListener')
-    const synchronousFailure = new Error('first cleanup failed')
-    let attempt = 0
-    const cleanup = vi.fn((): Promise<void> => {
-      attempt += 1
-      if (attempt === 1) throw synchronousFailure
-      if (attempt === 2) {
-        return Promise.resolve().then(() => {
-          const nonErrorRejection: unknown = 'cleanup transport gone'
-          throw nonErrorRejection
-        })
-      }
-      return Promise.resolve()
-    })
-    const lifecycle = new SubprocessTerminalLifecycle({
-      done: done.promise,
-      cleanup,
-      signal: lifetime.signal,
-    })
-
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).rejects.toBe(synchronousFailure)
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).rejects.toThrow('cleanup transport gone')
-
-    lifetime.abort()
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-    expect(cleanup).toHaveBeenCalledTimes(3)
-    expect(removeListener).toHaveBeenCalledWith('abort', expect.any(Function))
-
-    done.reject(new Error('top-level transport failed'))
-    await Promise.resolve()
-    expect(cleanup).toHaveBeenCalledTimes(3)
-  })
-
-  it('starts cleanup for a pre-aborted lifetime and bounds a wait that is already aborted', async () => {
-    const cleanupGate = Promise.withResolvers<undefined>()
-    const cleanup = vi.fn(() => cleanupGate.promise)
-    const lifecycle = new SubprocessTerminalLifecycle({
-      done: new Promise(() => {}),
-      cleanup,
-      signal: AbortSignal.abort(new Error('lifetime cancelled')),
-    })
-
-    expect(cleanup).toHaveBeenCalledOnce()
-    await expect(lifecycle.waitForExit(AbortSignal.abort())).resolves.toBe(false)
-    cleanupGate.resolve(undefined)
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-  })
-
-  it('contains cleanup settlement after an observer aborts between signal checks', async () => {
-    const firstCleanup = Promise.withResolvers<undefined>()
-    const cleanup = vi.fn()
-      .mockImplementationOnce(() => firstCleanup.promise)
-      .mockResolvedValueOnce(undefined)
-    const lifecycle = new SubprocessTerminalLifecycle({ done: Promise.resolve(), cleanup })
-    const observer = new AbortController().signal
-    vi.spyOn(observer, 'aborted', 'get')
-      .mockReturnValueOnce(false)
-      .mockReturnValueOnce(true)
-
-    await expect(lifecycle.waitForExit(observer)).resolves.toBe(false)
-    firstCleanup.reject(new Error('late cleanup failure'))
-    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
-    await Promise.resolve()
-
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-    expect(cleanup).toHaveBeenCalledTimes(2)
-  })
-
-  it('reports bounded cleanup success and failure', async () => {
-    const successful = new SubprocessTerminalLifecycle({
-      done: Promise.resolve(),
-      cleanup: async () => {},
-    })
-    await expect(successful.waitForExit(new AbortController().signal)).resolves.toBe(true)
-
-    const failure = new Error('quiescence failed')
-    const failed = new SubprocessTerminalLifecycle({
-      done: Promise.resolve(),
-      cleanup: () => Promise.reject(failure),
-    })
-    await expect(failed.waitForExit(new AbortController().signal)).rejects.toBe(failure)
-
-    const failedDone = Promise.withResolvers<undefined>()
-    const afterTransportFailure = new SubprocessTerminalLifecycle({
-      done: failedDone.promise,
-      cleanup: async () => {},
-    })
-    const waiting = afterTransportFailure.waitForExit()
-    failedDone.reject(new Error('transport failed'))
-    await expect(waiting).resolves.toBe(true)
-  })
-})
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 7a36ab0690..21cca6cb44 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: 38ee201a1754c6f50b7fae60b77af7dae734c8f9
-README.zh.md: 6fec39de550b7e3f57cd613dbe23c9687cd840ac
+README.md: eff5a6e648eb13c3411c19bca4d05f0898d3ad05
+README.zh.md: 16cf0e0ea6d487e255fc520a8fa1f41f97ee5d30

From 124fc6a611d7aa5ea40be3039a137b4c9fab3ade Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 19:40:39 +0800
Subject: [PATCH 076/262] fix(runtime): close portable backend boundary gaps

---
 .../code-runtime/tests/contract.ts            | 15 ++++++++
 packages/fs/fs-local/src/fsio.ts              |  8 ----
 packages/pty/pty-local/src/session.ts         |  2 +-
 packages/pty/pty-local/tests/session.spec.ts  | 37 +++++++++++++++++++
 .../subprocess/subprocess-local/src/index.ts  |  3 +-
 .../subprocess-local/tests/local.spec.ts      |  4 +-
 packages/typert/README.i18n.yaml              |  4 +-
 7 files changed, 59 insertions(+), 14 deletions(-)

diff --git a/packages/code-runtime/code-runtime/tests/contract.ts b/packages/code-runtime/code-runtime/tests/contract.ts
index f28545f8c1..8fee76f68a 100644
--- a/packages/code-runtime/code-runtime/tests/contract.ts
+++ b/packages/code-runtime/code-runtime/tests/contract.ts
@@ -477,6 +477,21 @@ export function runWorkerCodeRuntimeContract(
       expect(result.logs).toEqual([])
     })
 
+    it('ignores forged controller-only failure classifications', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          for (const kind of ['abort', 'timeout', 'worker-exit']) {
+            parentPort.postMessage({ type: 'done', error: { kind, message: 'forged ' + kind } });
+          }
+          return 'honest';
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], value: 'honest' })
+    })
+
     it('fails forged log floods and forged done values through the same outer cap', async () => {
       const { runtime } = await setup({ maxOutputBytes: 200 })
       const result = await runtime.run({
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 4925357e45..c93e4ddaeb 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -369,14 +369,6 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
   return decodeUtf8(raw, 'read', target.displayPath)
 }
 
-/**
- * Read one regular UTF-8 file through a single no-follow handle, retaining at
- * most `maxBytes + 1` bytes so a concurrent grow cannot bypass the bound.
- * @param target - the resolved file to read.
- * @param maxBytes - positive safe-integer byte ceiling.
- * @param signal - aborts between handle operations.
- * @returns the complete decoded text when it fits.
- */
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 076f21e3b9..f9b35dc665 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -415,7 +415,7 @@ export class LocalPtySession implements PtyBackendSession {
         return
       }
       const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation) return
+      if (this.active !== operation || this.closing) return
       const idleFor = Date.now() - this.lastOutputAt
       if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
         this.shellPgid = foreground.processGroupId
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 22b07a0f8f..14cf252a0e 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -1096,4 +1096,41 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     expect(terminal.writes).toEqual([])
   })
 
+  it('does not let an in-flight readiness inspection outrun close', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    const originalInspect = terminal.inspectForeground.bind(terminal)
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      return inspections === 1 ? await originalInspect() : await inspection.promise
+    }
+    const operation = session.startSend({ text: 'pending readiness', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspections).toBe(2)
+
+    const termination = Promise.withResolvers<undefined>()
+    terminal.terminate = async () => {
+      await termination.promise
+      terminal.emitExit(0, 15)
+    }
+    const closing = session.close('in-flight readiness')
+    let settled = false
+    void operation.done.then(() => { settled = true })
+    inspection.resolve({ processGroupId: 456, inputWaiting: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+
+    termination.resolve(undefined)
+    await closing
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
 })
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 0d02f0e387..46d179a7b2 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -59,9 +59,10 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
       }
       for (const terminal of this.terminals) {
-        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
+        pending.push(terminal.terminate())
       }
       this.live.clear()
+      this.terminals.clear()
       const outcomes = [
         ...await Promise.allSettled(pending),
         ...await Promise.allSettled([rm(this.runtimeRoot, { recursive: true, force: true })]),
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index e58c66f7fa..ff83141fab 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -113,7 +113,7 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('waits for every terminal cleanup, removes runtime state, and retains rejections', async () => {
+  it('waits for every terminal cleanup and clears single-shot teardown ownership', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
@@ -154,7 +154,7 @@ describe('LocalSubprocessService', () => {
     expect(disposed).toBe(false)
     finishCleanup()
     await disposing
-    expect(terminals).toEqual(new Set([failedTerminal, secondFailedTerminal]))
+    expect(terminals.size).toBe(0)
     await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
     expect(disposalErrors).toHaveLength(1)
     expect(disposalErrors[0]).toMatchObject({
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 21cca6cb44..5e93edd997 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: eff5a6e648eb13c3411c19bca4d05f0898d3ad05
-README.zh.md: 16cf0e0ea6d487e255fc520a8fa1f41f97ee5d30
+README.md: 152921a1ed595676781aad170e3396f7ce613161
+README.zh.md: 3e8223c33c7ce85f342c9a36ab5a24c4d2a6cb94

From 674d23118bfa894e13142d8cc1746dd74c39fba0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 20:20:51 +0800
Subject: [PATCH 077/262] fix(runtime): close measured portability defects

---
 packages/lsp/lsp-local/src/host.ts            |  5 +--
 packages/lsp/lsp-local/src/index.ts           | 38 ++++++++--------
 packages/lsp/lsp-local/tests/host.spec.ts     |  4 +-
 packages/lsp/lsp-local/tests/provider.spec.ts | 44 +++++++++++++++++++
 packages/pty/pty-local/src/session.ts         |  2 +-
 packages/pty/pty-local/tests/session.spec.ts  |  6 +--
 6 files changed, 73 insertions(+), 26 deletions(-)

diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index b8939a2ae4..ffba6a1344 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -100,15 +100,14 @@ export async function readHostSource(
     for await (const chunk of stream) {
       throwIfAborted(signal)
       bytes += Buffer.byteLength(chunk)
-      if (bytes > maxDocumentBytes) {
-        throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
-      }
+      if (bytes > maxDocumentBytes) break
       chunks.push(chunk)
     }
   } catch (error: unknown) {
     throwIfAborted(signal)
     throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
   }
+  if (bytes > maxDocumentBytes) throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
   throwIfAborted(signal)
   return {
     fileUrl: fs.fileUrl(target),
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index f3f45959e5..0e9468cba9 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -129,27 +129,29 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
   const providers = await (async () => {
+    const lookups = entries.map(async ([providerId, rawConfig]) => {
+      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+      const resolved = rawConfig as ResolvedServerConfig
+      validateServerConfig(providerId, resolved)
+      const executable = await ctx.subprocess.resolveExecutable(
+        resolved.command,
+        resolved.env,
+        setupAbort.signal,
+      )
+      setupAbort.signal.throwIfAborted()
+      return new LocalLspProvider(
+        providerId,
+        ctx.fs,
+        resolved,
+        executable,
+        spec => ctx.subprocess.spawn(spec),
+      )
+    })
     try {
-      return await Promise.all(entries.map(async ([providerId, rawConfig]) => {
-        if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-        const resolved = rawConfig as ResolvedServerConfig
-        validateServerConfig(providerId, resolved)
-        const executable = await ctx.subprocess.resolveExecutable(
-          resolved.command,
-          resolved.env,
-          setupAbort.signal,
-        )
-        setupAbort.signal.throwIfAborted()
-        return new LocalLspProvider(
-          providerId,
-          ctx.fs,
-          resolved,
-          executable,
-          spec => ctx.subprocess.spawn(spec),
-        )
-      }))
+      return await Promise.all(lookups)
     } catch (error: unknown) {
       setupAbort.abort(error)
+      await Promise.allSettled(lookups)
       throw error
     } finally {
       stopSetupCancellation()
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index eea3851414..c97defc086 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -158,7 +158,9 @@ describe('readHostSource', () => {
 
   it('rejects an oversized source', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
-    await expect(readSource('big.ts', 10)).rejects.toThrow(/10-byte limit/)
+    await expect(readSource('big.ts', 10)).rejects.toMatchObject({
+      message: 'source "big.ts" exceeds the 10-byte limit',
+    })
   })
 
   it('counts the complete UTF-8 byte length at the configured boundary', async () => {
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index 8d8a7ad356..88b2b0144f 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -195,6 +195,50 @@ describe('lsp-local provider resolution', () => {
     await ctx.fiber.dispose()
   })
 
+  it('waits for aborted sibling executable lookups before setup rejects', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const slowStarted = Promise.withResolvers<undefined>()
+    const slowAborted = Promise.withResolvers<undefined>()
+    const releaseCleanup = Promise.withResolvers<undefined>()
+    vi.spyOn(ctx.subprocess, 'resolveExecutable').mockImplementation(async (command, _env, signal) => {
+      if (signal === undefined) throw new Error('missing setup signal')
+      if (command === 'slow-lsp') {
+        return await new Promise<string>((_resolve, reject) => {
+          const onAbort = (): void => {
+            slowAborted.resolve(undefined)
+            void releaseCleanup.promise.then(() => {
+              reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+            })
+          }
+          signal.addEventListener('abort', onAbort, { once: true })
+          slowStarted.resolve(undefined)
+          if (signal.aborted) onAbort()
+        })
+      }
+      await slowStarted.promise
+      throw new Error('lookup failed')
+    })
+
+    const loading = ctx.plugin(LspLocal, {
+      servers: {
+        slow: { command: 'slow-lsp', extensionToLanguage: { '.ts': 'typescript' } },
+        failing: { command: 'failing-lsp', extensionToLanguage: { '.js': 'javascript' } },
+      },
+    })
+    await slowAborted.promise
+    let settled = false
+    void loading.then(() => { settled = true }, () => { settled = true })
+    await new Promise<void>((resolve) => { setImmediate(resolve) })
+    expect(settled).toBe(false)
+
+    releaseCleanup.resolve(undefined)
+    await expect(loading).rejects.toThrow('lookup failed')
+    await ctx.fiber.dispose()
+  })
+
   it('aborts executable resolution when disposed during setup', async () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index f9b35dc665..5517cd902d 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -237,7 +237,7 @@ export class LocalPtySession implements PtyBackendSession {
     }
     this.activeDeadlineTimer = setTimeout(() => {
       if (this.active === operation) {
-        this.settleActive('timeout', this.activeWrite?.operation === operation)
+        this.settleActive('timeout', this.activeWrite?.operation === operation || this.interrupting === operation)
       }
     }, this.config.timeoutMs)
     void this.beginSend(operation, request)
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 14cf252a0e..fbe0aa807b 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -365,11 +365,11 @@ describe('LocalPtySession readiness and output', () => {
     expect(operation.cancel()).toBe(true)
 
     terminal.emitData('\x1b]133;D;130\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await operation.done).waitReason).toBe('timeout')
     expect(() => session.startSend({ text: 'successor', submit: true })).toThrow('active send')
     signalGate.resolve(undefined)
-    await vi.advanceTimersByTimeAsync(10)
-    await operation.done
+    await vi.advanceTimersByTimeAsync(0)
     expect(inspector.groups).toContainEqual([456, 'SIGINT'])
     expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
   })

From b71dbbe766edc0646a4f7c073d45867bb3248684 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 21:19:27 +0800
Subject: [PATCH 078/262] fix(runtime): close review lifecycle and bound gaps

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  2 +-
 docs/config-catalog.md                        |  2 +-
 .../code-runtime-worker/src/runtime-host.ts   |  1 +
 packages/lsp/lsp-local/src/index.ts           | 16 ++++-
 .../lsp/lsp-local/tests/lifecycle.spec.ts     | 72 +++++++++++++++++++
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           | 20 +++---
 packages/pty/pty-local/src/index.ts           |  8 ++-
 packages/pty/pty-local/tests/index.spec.ts    | 18 ++++-
 15 files changed, 130 insertions(+), 29 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 7b6a74b7e8..a7eaaa2e3a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: d68fc92308079aa68a8f4e1accadde0addb0e5aa
-2026-07-28-portable-execution-world-consumers.zh.md: 5341cf1643cabb1043b977e18179dc857e37e121
+2026-07-28-portable-execution-world-consumers.md: 260f38981ea0cd034f506594057483c6ccfa9617
+2026-07-28-portable-execution-world-consumers.zh.md: 0bf7b4dd1a87378b76f6a71343a8cb78766b7b3a
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index d68fc92308..260f38981e 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 5341cf1643..0bf7b4dd1a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 2694664183..72944d7433 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: f94dd57622c555e195564cc2eee9b3228841d5cc
-2026-07-16-persistent-pty-sessions.zh.md: 6228571a6496e9d4cb031a2df958b80dee102fd3
+2026-07-16-persistent-pty-sessions.md: 88296a9318b2c398fead382153bd2c652dbd9e68
+2026-07-16-persistent-pty-sessions.zh.md: 40f26c67fe046ad292f05919501600bd2e146c62
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index f94dd57622..88296a9318 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -41,7 +41,7 @@ Agent-scope disposal closes registrations first, then awaits quiescent teardown
 A registered `shell` backend constrains how a terminal starts; it does not constrain commands typed after startup. `dsh-pty-local` therefore applies two protections before spawning:
 
 - It supplies only terminal-specific environment overrides; the mounted subprocess provider applies the shared credential-shaped-name scrub before merging them.
-- It requires `ctx.sandbox` and the shared `ctx.sandboxPolicy`. At spawn, the backend resolves the owner's effective session mode over the deployment default and wraps the shell argv once; that mode and workspace root remain the process boundary for the PTY lifetime. A write that would change the effective `sandbox/mode` is rejected before commit while the owner has any open PTY or unpublished spawn, with an instruction to wait for creation to settle and close those sessions first; same-effective-mode writes remain valid. The pending reservation spans backend setup through publication, so there is no race in which a wider terminal appears after a downgrade. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
+- It requires the shared `ctx.sandboxPolicy`. At spawn, the backend resolves the owner's effective session mode over the deployment default; `danger-full-access` starts the shell directly, while confined modes require a same-world `ctx.sandbox` provider and wrap the shell argv once. That mode and workspace root remain the process boundary for the PTY lifetime. A write that would change the effective `sandbox/mode` is rejected before commit while the owner has any open PTY or unpublished spawn, with an instruction to wait for creation to settle and close those sessions first; same-effective-mode writes remain valid. The pending reservation spans backend setup through publication, so there is no race in which a wider terminal appears after a downgrade. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
 
 Sandboxing confines local process effects but does not make arbitrary shell input safe: network calls and other external side effects remain governed by deployment policy. Tool descriptions state that PTY sessions are less auditable than one-shot tools and should be used only when persistence or interactive stdin is necessary.
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 6228571a64..40f26c67fe 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -41,7 +41,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 注册的 `shell` 后端只约束终端如何启动，不约束启动后输入的命令。因此 `dsh-pty-local` 在 spawn 前应用两层保护：
 
 - 它只提供终端专用的环境覆盖；挂载的子进程提供方先清除名称形似凭据的环境变量，再合并这些覆盖。
-- 它要求 `ctx.sandbox` 和共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode，并只包装一次 shell argv；该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。只要 owner 有任何已打开的 PTY 或尚未发布的 spawn，任何会改变生效 `sandbox/mode` 的写入都会在提交前被拒绝，并提示先等待创建操作结算，再关闭这些会话；不会改变生效模式的写入仍然有效。这项进行中的预留从后端 setup 持续到发布完成，因此不存在降级后又出现权限更宽的终端这一竞态。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
+- 它要求共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode；`danger-full-access` 会直接启动 shell，受限模式则要求同一执行世界中存在 `ctx.sandbox` 提供方，并只包装一次 shell argv。该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。只要 owner 有任何已打开的 PTY 或尚未发布的 spawn，任何会改变生效 `sandbox/mode` 的写入都会在提交前被拒绝，并提示先等待创建操作结算，再关闭这些会话；不会改变生效模式的写入仍然有效。这项进行中的预留从后端 setup 持续到发布完成，因此不存在降级后又出现权限更宽的终端这一竞态。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
 
 沙箱限制本地进程副作用，但不会让任意 shell 输入自动安全：网络调用和其他外部副作用仍由部署策略治理。工具描述会说明 PTY 会话比一次性工具更难审计，只应在确实需要持久状态或交互式 stdin 时使用。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b70f468960..0514cdd969 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1072,7 +1072,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:69`](../packages/plan/plan-mode/s
 
 ## `@deepseek-ai/dsh-pty-local`
 
-Requires: `pty` · `sandbox` · `sandboxPolicy` · `subprocess`
+Requires: `pty` · `sandboxPolicy` · `subprocess`
 
 ```ts config-catalog
 /** Public plugin configuration. */
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index 474a058e9f..d2bb1082b8 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -223,4 +223,5 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+export { jsonValueBytesUpTo } from './output-json.ts'
 export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 0e9468cba9..fc7e50787f 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -106,6 +106,16 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
+/** Propagate teardown failures only after every sibling has settled. */
+function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
+  const failures: unknown[] = []
+  for (const result of results) {
+    if (result.status === 'rejected') failures.push(result.reason)
+  }
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) throw new AggregateError(failures, message)
+}
+
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
@@ -169,7 +179,8 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
+      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
+      throwTeardownFailures(results, 'lsp-local provider teardown failed')
     }
   }, 'lsp-local.registerProviders')
 }
@@ -346,12 +357,13 @@ class LocalLspProvider implements LspProvider {
     const draining = [...this.queues.values()]
     const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    await Promise.all([
+    const results = await Promise.allSettled([
       ...live.map(instance => instance.dispose()),
       ...draining,
       ...resolving,
     ])
     this.queues.clear()
     this.workspaceLookups.clear()
+    throwTeardownFailures(results, 'lsp-local instance teardown failed')
   }
 }
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 63aea8742c..7a30232e22 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -350,6 +350,78 @@ describe('lsp-local end to end over a fake server', () => {
     expect(signal.aborted).toBe(true)
   })
 
+  it('waits for every owned teardown before aggregating instance failures', async () => {
+    let provider: LspProvider | undefined
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' }, {}, (registered) => { provider = registered })
+    if (provider === undefined) throw new Error('expected lsp-local to register a provider')
+    const internals = provider as unknown as {
+      readonly instances: Map<string, { dispose(): Promise<void> }>
+      readonly queues: Map<string, Promise<void>>
+      readonly workspaceLookups: Set<Promise<void>>
+      disposeAll(): Promise<void>
+    }
+    const firstFailure = new Error('first instance cleanup failed')
+    const secondFailure = new Error('second instance cleanup failed')
+    const release = Promise.withResolvers<undefined>()
+    internals.instances.set('first', { dispose: async () => { throw firstFailure } })
+    internals.instances.set('second', { dispose: async () => { throw secondFailure } })
+    internals.queues.set('pending', release.promise)
+    internals.workspaceLookups.add(Promise.resolve())
+
+    let settled = false
+    const disposing = internals.disposeAll().finally(() => { settled = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(settled).toBe(false)
+    release.resolve(undefined)
+    await expect(disposing).rejects.toMatchObject({
+      errors: [firstFailure, secondFailure],
+      message: 'lsp-local instance teardown failed',
+    })
+    expect(internals.instances.size).toBe(0)
+    expect(internals.queues.size).toBe(0)
+    expect(internals.workspaceLookups.size).toBe(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for every provider before reporting plugin teardown failure', async () => {
+    const ctx = new Context()
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const providers: LspProvider[] = []
+    const register = ctx.lsp.registerProvider.bind(ctx.lsp)
+    const registrationSpy = vi.spyOn(ctx.lsp, 'registerProvider').mockImplementation((provider) => {
+      providers.push(provider)
+      return register(provider)
+    })
+    const fiber = await ctx.plugin(LspLocal, {
+      servers: {
+        first: fakeServer(),
+        second: fakeServer({}, { extensionToLanguage: { '.js': 'javascript' } }),
+      },
+    })
+    registrationSpy.mockRestore()
+    expect(providers).toHaveLength(2)
+    const failure = new Error('provider cleanup failed')
+    const release = Promise.withResolvers<undefined>()
+    const first = providers[0] as LspProvider & { disposeAll(): Promise<void> }
+    const second = providers[1] as LspProvider & { disposeAll(): Promise<void> }
+    first.disposeAll = async () => { throw failure }
+    second.disposeAll = async () => { await release.promise }
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(disposed).toBe(false)
+    expect(disposalErrors).toEqual([])
+    release.resolve(undefined)
+    await disposing
+    expect(disposalErrors).toEqual([failure])
+    await ctx.fiber.dispose()
+  })
+
   it('runs distinct workspaces in parallel instances', async () => {
     const ws2 = join(root, 'ws2')
     await mkdir(ws2)
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index c2a0f9b647..2689103443 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: c4af7bc8293689d64c58eebab2606d4f9b52fd2f
-README.zh.md: 21075ccbf53d173a54220b58b384f01cfe50ced1
+README.md: 92a3d7be68ada6f38ab3c4ca5bdd2622ebefc8ee
+README.zh.md: 016043f7842df8bb963cdc5eea015666c9ce6941
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index c4af7bc829..92a3d7be68 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -6,7 +6,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 21075ccbf5..016043f784 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-这是基于 `ctx.subprocess.spawnTerminal` 的 `ctx.pty` 持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
+这是一个基于 `ctx.subprocess.spawnTerminal`、为 `ctx.pty` 提供的持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方则负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方信号会转发给终端分配和就绪初始化；句柄一经发布，便负责自身生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待写入结算；写入被拒绝时不会发送信号。被取消的发送会保留其槽位，直至写入和前台信号发送都结算，因此后续发送既不会收到延迟字节，也不会成为该信号的目标。取消等待期间，绝对截止时间仍保持启用。信号发送失败属于终结性传输失败，并会使当前发送被拒绝。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待句柄执行由提供方负责的完整会话终止，之后才将当前发送以 `session_exit` 结算。
+取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
 
 ## 模型体验
 
@@ -22,15 +22,15 @@
 
 #### Token 影响
 
-消费方返回有界的后端输出前没有影响。此包不会把保留的 PTY scrollback 放入模型历史。
+消费方返回有界的后端输出前没有影响。此包（package）不会把保留的 PTY scrollback 放入模型历史。
 
 #### KV Cache 影响
 
-不会直接失效；提示词、schema 与追加结果由消费方负责。
+不会直接使 KV Cache 失效；提示词、schema 与追加结果由消费方负责。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
-- 精确 stdin 等待检测取决于挂载的进程管理提供方；无法证明该事实的提供方使用提示符标记和静默／超时就绪机制。
-- 清理保证遵循 `SubprocessTerminalHandle`；提供方特有缺口属于该实现的契约，而非此 PTY 消费方。
-- 会话无法跨 harness 进程退出保留。
+- 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
+- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的契约，而非这个 PTY 消费方。
+- harness 进程退出后，会话无法继续存在。
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index a8d99cb243..1fa3357002 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -22,7 +22,7 @@ export type { Config as PtyLocalConfig } from './config.ts'
 /** Cordis plugin name. */
 export const name = 'pty-local'
 /** Required services: PTY registry, shared confinement policy, and process substrate. */
-export const inject = ['pty', 'sandbox', 'sandboxPolicy', 'subprocess']
+export const inject = ['pty', 'sandboxPolicy', 'subprocess']
 
 interface SandboxModeFenceState {
   pty: Context['pty']
@@ -72,7 +72,11 @@ function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSp
   const argv = [config.shellPath, ...config.shellArgs]
   const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
   if (mode === 'danger-full-access') return argv
-  return ctx.sandbox.confine(argv, {
+  const sandbox = ctx.get('sandbox')
+  if (sandbox === undefined) {
+    throw new Error(`pty-local: sandbox mode "${mode}" requires a ctx.sandbox provider in the execution world`)
+  }
+  return sandbox.confine(argv, {
     mode: mode,
     workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
   }).argv
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 48c8272106..9206dd89ef 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -120,7 +120,6 @@ describe('LocalPtyBackend startup rollback', () => {
 
   it('closes failed startup and aggregates cleanup failure', async () => {
     const ctx = new Context()
-    await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
     const spawnTerminal = async (): Promise<SubprocessTerminalHandle> => terminalHandle()
 
@@ -186,6 +185,20 @@ describe('LocalPtyBackend startup rollback', () => {
     expect(initialized).toHaveBeenCalledWith(undefined)
   })
 
+  it('rejects a confined spawn without a sandbox provider', async () => {
+    const confinedCtx = new Context()
+    await confinedCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const confined = new LocalPtyBackend(
+      confinedCtx,
+      config(),
+      async () => { throw new Error('terminal spawn must not run') },
+      () => stubLocalSession(),
+    )
+    await expect(confined.spawn(spec(agent(confinedCtx)))).rejects.toThrow(
+      'sandbox mode "workspace-write" requires a ctx.sandbox provider in the execution world',
+    )
+  })
+
   it('forwards terminal allocation cancellation directly', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
@@ -266,7 +279,7 @@ describe('pty-local plugin shape', () => {
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(ptyLocal) as Record<string, unknown>
     expect(unwrapped.name).toBe('pty-local')
-    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'])
+    expect(unwrapped.inject).toEqual(['pty', 'sandboxPolicy', 'subprocess'])
     expect(unwrapped.Config).toBeDefined()
   })
 
@@ -274,7 +287,6 @@ describe('pty-local plugin shape', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(PtyService)
-    await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
     await ctx.plugin(StubSubprocessService)
     const fiber = await ctx.plugin(ptyLocal, config())

From ff86795b15576048529c7ccff4d00c38adbdb015 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 23:11:49 +0800
Subject: [PATCH 079/262] fix(pty): close provider cancellation races

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  4 +-
 ...8-portable-execution-world-consumers.zh.md |  4 +-
 .../core-data-structures/subprocess.i18n.yaml |  4 +-
 docs/core-data-structures/subprocess.md       |  2 +-
 docs/core-data-structures/subprocess.zh.md    |  2 +-
 packages/pty/pty-local/src/index.ts           | 18 ++++++-
 packages/pty/pty-local/src/session.ts         |  5 +-
 packages/pty/pty-local/tests/index.spec.ts    | 26 +++++++++
 packages/pty/pty-local/tests/session.spec.ts  | 53 ++++++++++++++++++-
 packages/subprocess/README.i18n.yaml          |  4 +-
 packages/subprocess/README.md                 |  2 +-
 packages/subprocess/README.zh.md              |  6 +--
 .../subprocess/subprocess/README.i18n.yaml    |  4 +-
 packages/subprocess/subprocess/README.md      |  2 +-
 packages/subprocess/subprocess/README.zh.md   | 24 ++++-----
 packages/subprocess/subprocess/src/types.ts   |  3 +-
 17 files changed, 131 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index a7eaaa2e3a..683a095229 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 260f38981ea0cd034f506594057483c6ccfa9617
-2026-07-28-portable-execution-world-consumers.zh.md: 0bf7b4dd1a87378b76f6a71343a8cb78766b7b3a
+2026-07-28-portable-execution-world-consumers.md: 03b274688e15661845c326afdd105b342dd6a513
+2026-07-28-portable-execution-world-consumers.zh.md: 1e3d8ae8e46d26f4bea47293104c52dbf33098d4
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 260f38981e..03b274688e 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -16,13 +16,13 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches whole-session quiescence. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 0bf7b4dd1a..1e3d8ae8e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -16,13 +16,13 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 7cba3857bb..f3b308b0be 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 89c75aea3393a000612e3b8f87d263c7b4fa7c60
-subprocess.zh.md: 83fb44f4750ba31db1f4336c0c293eb9e236be22
+subprocess.md: 95e9454a75112cf98e1ed583f970c50fe90aac37
+subprocess.zh.md: 58127d662fa599d19f632449d42b8aa3259886d6
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index d6e0105c59..935a7d60ac 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -240,7 +240,7 @@ interface SubprocessOutcome {
 
 ## Terminal-process primitive
 
-`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
+`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
 The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 83fb44f475..58127d662f 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -240,7 +240,7 @@ interface SubprocessOutcome {
 
 ## 终端进程原语
 
-`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使整个会话完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
+`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
 终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 1fa3357002..f91db5d386 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -82,6 +82,22 @@ function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSp
   }).argv
 }
 
+async function initializeSession(session: LocalPtySession, signal?: AbortSignal): Promise<void> {
+  if (signal === undefined) {
+    await session.initialize(signal)
+    return
+  }
+  const aborted = Promise.withResolvers<never>()
+  const onAbort = (): void => { aborted.reject(signal.reason) }
+  signal.addEventListener('abort', onAbort, { once: true })
+  try {
+    signal.throwIfAborted()
+    await Promise.race([session.initialize(signal), aborted.promise])
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
 /** Local shell backend registered under the configured type. */
 export class LocalPtyBackend implements PtyBackend {
   readonly type: string
@@ -116,7 +132,7 @@ export class LocalPtyBackend implements PtyBackend {
     })
     const session = this.createSession(terminal, this.config)
     try {
-      await session.initialize(spec.signal)
+      await initializeSession(session, spec.signal)
       return session
     } catch (error) {
       try {
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 5517cd902d..ebd7e076cf 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -6,6 +6,7 @@ import type {
   SubprocessTerminalForeground,
   SubprocessTerminalHandle,
 } from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -219,7 +220,7 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new Error('PTY session already has an active send')
+    if (this.active !== undefined) throw new PtyError('PTY session already has an active send or draining provider operation', 'SEND_ACTIVE')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -247,7 +248,7 @@ export class LocalPtySession implements PtyBackendSession {
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
     try {
       const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation || this.closing) return
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
       if (input.length > 0 && !operation.cancelRequested) {
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 9206dd89ef..f59cd3ab5a 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -143,6 +143,32 @@ describe('LocalPtyBackend startup rollback', () => {
     } satisfies Partial<PtyBackendCleanupError>))
   })
 
+  it('starts startup rollback when cancellation wins a stalled initialization', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    const initialization = Promise.withResolvers<undefined>()
+    const initializationStarted = Promise.withResolvers<undefined>()
+    const close = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = {
+      initialize: () => {
+        initializationStarted.resolve(undefined)
+        return initialization.promise
+      },
+      close,
+    } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(ctx, config(), async () => terminalHandle(), () => session)
+    const controller = new AbortController()
+    const reason = new Error('cancel stalled startup')
+
+    const spawning = backend.spawn(spec(agent(ctx), controller.signal))
+    await initializationStarted.promise
+    controller.abort(reason)
+
+    await expect(spawning).rejects.toBe(reason)
+    expect(close).toHaveBeenCalledWith('PTY startup failed')
+    initialization.resolve(undefined)
+  })
+
   it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(RecordingSandbox)
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index fbe0aa807b..8d11f8e6f4 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -8,6 +8,7 @@ import type {
   SubprocessTerminalHandle,
   SubprocessTerminalSignal,
 } from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   ProcessIdentity,
   ProcessInspector,
@@ -374,6 +375,54 @@ describe('LocalPtySession readiness and output', () => {
     expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
   })
 
+  it('does not let an in-flight readiness inspection release a canceled send before signalling settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const readiness = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      if (inspections === 1) return { processGroupId: 456, inputWaiting: false }
+      if (inspections === 2) return await readiness.promise
+      return { processGroupId: 456, inputWaiting: true }
+    }
+    const signalling = Promise.withResolvers<undefined>()
+    const signalled = Promise.withResolvers<number>()
+    terminal.signalForeground = async (signal) => {
+      await signalling.promise
+      const foreground = await terminal.inspectForeground()
+      if (foreground === undefined) throw new Error('cannot resolve foreground')
+      inspector.signalGroup(foreground.processGroupId, signal)
+      signalled.resolve(foreground.processGroupId)
+      return foreground.processGroupId
+    }
+
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspections).toBe(2)
+    expect(operation.cancel()).toBe(true)
+    let settled = false
+    void operation.done.then(() => { settled = true })
+
+    readiness.resolve({ processGroupId: 456, inputWaiting: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow(PtyError)
+
+    signalling.resolve(undefined)
+    expect(await signalled.promise).toBe(456)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    await session.close('test complete')
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
   it('signals only after an in-flight provider write lands', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -438,7 +487,9 @@ describe('LocalPtySession readiness and output', () => {
     await vi.advanceTimersByTimeAsync(100)
 
     expect((await operation.done).waitReason).toBe('timeout')
-    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow(expect.objectContaining({
+      code: 'SEND_ACTIVE',
+    }))
 
     writeGate.resolve(undefined)
     await vi.advanceTimersByTimeAsync(0)
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 256d4ad2d9..f6de20e259 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: c4bb1da1a172b05afa63834db4e5b1fa974baabb
-README.zh.md: f68bc1c720eeb5282bb9c94c951524a021e38b2f
+README.md: b4aaf78454a51af4d3f7ea9f1aef450fde8d729d
+README.zh.md: c5013ce19bacb582b6c8c93e0ea0a73ec776ee57
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index c4bb1da1a1..b4aaf78454 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and complete session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index f68bc1c720..c5013ce19b 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,12 +1,12 @@
-# subprocess/：进程管理能力家族
+# subprocess/：子进程能力家族
 
 [English](README.md) | 中文
 
-同一执行世界中的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、采用原始或收集式 stdio 的完全显式受管子进程树，以及一项负责 PTY 分配、前台进程组和完整会话清理的深层终端进程原语。命令默认值补全、shell 语义、deadline、协议分帧、就绪检测与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[基于进程管理的 Code Runtime](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
 | [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送、运行时存储，以及先终止再等待退出的资源释放 |
 
-服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
+即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index f8678464a9..92887cc247 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 2fca5cdd08f3cbd36d8ef492226c91681b5568d0
-README.zh.md: 5830d0fc394160bc557e24646cc76d4bcfead13c
+README.md: 12a88a86c3cd7bcde2858bdbd874c99533100e09
+README.zh.md: f4c265a0f55c4e35e4557516593dd0da236164c5
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 2fca5cdd08..12a88a86c3 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -11,7 +11,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches whole-session quiescence and settles in-flight handle calls. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
+- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches quiescence for every session member the provider can still observe and settles in-flight handle calls; providers document substrate-specific observability limits. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members; readiness, scrollback, and owner policy remain in the PTY consumer.
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 5830d0fc39..f4c265a0f5 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,30 +2,30 @@
 
 [English](README.md) | 中文
 
-进程管理器 seam（`ctx.subprocess`）是同一执行世界中的进程侧。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
-- `spawn(spec)` 立即返回一个实时句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- `cwd` 与 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
-- stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
+- `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
+- `cwd` 和 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 之下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使整个会话完全停稳，并让所有在途句柄调用结算。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；存活传输失败会拒绝 `done`。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[进程管理器数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归消费方所有。
+通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由消费方负责。
 
 #### KV Cache 影响
 
-不会直接失效；请求前缀变更由具名消费方负责。
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
 
 ## 已知限制与暂缓事项
 
-- **由 SDK 管理的 spawn 仍在服务之外**：自行拥有内部 spawn 的 SDK 传输层无法经该服务路由这次调用；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
-- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合形状（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
+- **由 SDK 管理的 spawn 仍在服务之外**：拥有内部 spawn 的 SDK 传输无法把该调用路由到本服务；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
+- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 6b606fd870..9801bf2f49 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -252,8 +252,9 @@ export interface SubprocessTerminalHandle {
    */
   signalForeground(signal: SubprocessTerminalSignal): Promise<number>
   /**
-   * Idempotently terminate the complete terminal session and await whole-session quiescence.
+   * Idempotently terminate every terminal-session member the provider can still observe and await quiescence.
    * After settlement, no write, inspection, or signal call remains in flight.
+   * Providers document substrate-specific observability limits.
    */
   terminate(): Promise<void>
 }

From dde55d5afecb75e8cd3f07f04e8f79e8199b53ba Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 02:04:11 +0800
Subject: [PATCH 080/262] docs(agent-notes): consolidate subprocess decisions

---
 ...26-subprocess-consumer-migration.i18n.yaml |  6 ---
 ...026-07-26-subprocess-consumer-migration.md | 38 -------------------
 ...-07-26-subprocess-consumer-migration.zh.md | 38 -------------------
 .../2026-07-26-subprocess-seam.i18n.yaml      |  4 +-
 .../2026-07-26-subprocess-seam.md             | 16 +++++---
 .../2026-07-26-subprocess-seam.zh.md          | 16 +++++---
 6 files changed, 24 insertions(+), 94 deletions(-)
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
deleted file mode 100644
index 469c3f9a24..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
-2026-07-26-subprocess-consumer-migration.md: abc7c8504595641b2b821df5ddbd4645c3a15336
-2026-07-26-subprocess-consumer-migration.zh.md: 500dcfe36f63315156b1a3cc48670eaf1c204b20
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
deleted file mode 100644
index abc7c85045..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: The subprocess seam goes Node-shaped and every eligible spawner rides it
-
-Status: implemented
-
-English | [中文](2026-07-26-subprocess-consumer-migration.zh.md)
-
-## Problem
-
-The [subprocess seam](2026-07-26-subprocess-seam.md) shipped shaped for exactly one consumer family: batch-collected stdout/stderr, batch stdin, a single escalating `kill()`. That was deliberate scope control, and its own note records "migrate the other spawn sites" as rejected-for-now. Review on the introducing PR reversed that deferral: the stacked follow-up should reshape the interface toward Node's API and move the remaining process-running places onto the service. The remaining spawners each carried a private copy of some slice of the same mechanics — lsp-local had its own detached-tree signalling (POSIX group + Windows taskkill + liveness polling), subagent-subprocess had the dispose ladder and its own scrub, mcp-client and pty-local and the SDK helper each had a third/fourth/fifth copy of the credential scrub — and none of it was swappable or centrally testable.
-
-## Decision
-
-The seam's vocabulary is now Node-shaped, and every spawner that can ride the service does:
-
-- **Per-stream stdio dispositions** on `SubprocessSpawnSpec`: `'pipe'` (the raw `Readable`/`Writable`, for consumer-owned protocol framing), `'inherit'` (diagnostics to the parent's stream), and collect mode `{ maxBytes, spill? }` — the original bounded tail-keep shape, with the spill file now optional so a diagnostic tail (a language server's stderr) buffers without touching disk. stdin is `'ignore'`, `'pipe'`, or `{ data }` (write-and-close batch).
-- **`SubprocessOutcome` carries exit facts only** (Node's close-event vocabulary); collected output stays readable through `handle.collected` after settlement (spill fds seal at the settle boundary), so batch and streaming callers share one access path and nothing is copied into the outcome.
-- **Tree-scoped termination behind one verb**: `terminate()` owns the SIGTERM→grace→SIGKILL escalation (serves the spec's abort signal too, and is a no-op once the tree is gone) — the handle exposes no single-signal `kill(signal?)`, so a consumer cannot skip the grace window; `waitForExit()` polls tree liveness (POSIX group probe; direct-child boundary on Windows); Windows tree termination (`taskkill /T`, injectable) moved in from lsp-local, so tree semantics are platform-correct for every consumer. (The stdin-EOF-first dispose ladder initially absorbed from `subagent-subprocess` later moved back out to its one consumer — see the [ladder-ownership Agent Note](2026-07-27-dispose-ladder-to-consumer.md).)
-- **One scrub definition**: `scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` live on the seam. Ordinary and terminal local spawns apply it inside `dsh-subprocess-local`; mcp-client still imports it because the MCP SDK owns that transport spawn, and the SDK helper's `scrubEnvironment()` defaults through it as well.
-
-Migrations landed with the reshape: **bash-local/bash-sandbox** (collect modes + batch stdin; the bash `kill()` maps to `terminate()` so `task_kill` keeps escalation semantics), **lsp-local** (piped protocol streams + a no-spill collected stderr tail; `LspConnection` takes the seam's spawn function; its private tree-op helpers deleted), **subagent-acp** (piped ndjson streams + inherited stderr; spawn failure surfaces through `done` rejection into the same startup race; disposal is the backend-owned `disposeAcpChild` ladder over the seam's verbs, with the plugin's configured graces), and **pty-local** through the later [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) (`node-pty` allocation and process inspection sit behind `spawnTerminal()`, while readiness and terminal policy remain in the consumer). **`dsh-subagent-subprocess` is deleted** — the dispose ladder and scrub are the seam's; the unused isolated-config-dir helper died with it (no consumer existed).
-
-Compositions mounting lsp-local or subagent-acp now load `dsh-subprocess-local` (the plugins inject `'subprocess'`); the acp/lsp test fixtures gained the row.
-
-## Alternatives considered
-
-**Keep the batch-only seam and let stream consumers stay bespoke.** The introducing note's position, rejected by review: it leaves three private copies of tree signalling and five of the scrub, and any future runner (containerized executor, remote process host) would have to pick which private copy to fork. The Node-shaped dispositions cover all three observed stream shapes without widening the outcome type or buffering piped streams.
-
-**A single `stdio: 'pipe' | 'inherit' | 'collect'` mode for all three streams at once.** Rejected: real consumers mix modes per stream (lsp: pipe/pipe/collect; acp: pipe/pipe/inherit; bash: data/collect/collect). Per-stream dispositions are exactly Node's shape and avoid a second spawn call for the mixed cases.
-
-**Keep pty-local and mcp-client spawns outside the service.** The MCP SDK still owns its transport spawn. PTY allocation is different: the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) moves `node-pty` behind one deep terminal primitive, resolving the ownership objection without pretending an ordinary piped spawn can provide terminal semantics.
-
-**Migrate the test-support launchers (acp-snapshot, loader-smoke) and the SDK package-manager runner.** Rejected: the support packages are deliberately dependency-light test infrastructure that must not depend on product seams, and the SDK wizard's `stdio: 'inherit'`-with-redirect semantics plus its out-of-composition lifecycle (no cordis context at all) make the service a poor fit; it shares the scrub instead.
-
-## Consequences
-
-Bought: one implementation of tree signalling, escalation, bounded collection, terminal process mechanics, and the scrub, tested once in `dsh-subprocess-local`'s suites (including injected-platform Windows coverage that lsp-local's private copy never had); lsp-local, pty-local, and subagent-acp shed provider-specific process plumbing and their children die with composition teardown like bash's; a whole package (`dsh-subagent-subprocess`) is gone. The seam README's "one consumer family" limitation is retired.
-
-Cost: the seam is wider — execution-world coordinates, executable lookup, three stdio modes, process-tree lifecycle, and one terminal primitive — so a future backend implements more surface; the compositions for lsp-local, pty-local, and subagent-acp each carry the subprocess row; and `SubprocessOutcome` no longer carries output, a breaking shape change inside the still-unreleased stack. MCP/SDK/test-support spawns remain outside the service by ownership, with the scrub as the shared floor.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
deleted file mode 100644
index 500dcfe36f..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: 进程 seam 转向 Node 形状，所有具备条件的 spawn 调用点一并迁入
-
-Status: implemented
-
-[English](2026-07-26-subprocess-consumer-migration.md) | 中文
-
-## 问题
-
-[进程 seam](2026-07-26-subprocess-seam.md) 交付时恰好只为一个消费方家族塑形：批量收集的 stdout/stderr、批量 stdin、单一的升级式 `kill()`。那是有意的范围控制，其自身的 Agent Note 也把「迁移其余 spawn 调用点」记为暂缓否决项。引入该 seam 的 PR（Pull Request）上的评审推翻了这一暂缓决定：堆叠其上的后续变更应当把接口向 Node 的 API 方向重塑，并把其余运行进程之处迁到该服务上。其余各 spawn 调用点此前各自持有同一套机制中某个切片的私有副本——lsp-local 自带 detached 进程树信号发送（POSIX 进程组 + Windows taskkill + 存活轮询），subagent-subprocess 自带 dispose（资源释放）阶梯和自己的凭据清除，mcp-client、pty-local 与 SDK helper 则各自持有凭据清除的第三、第四、第五份副本——而这一切既不可替换，也无法集中测试。
-
-## 决策
-
-这道 seam 的词汇如今已是 Node 形状，凡能接入该服务的 spawn 调用点均已迁入：
-
-- **按流划分的 stdio 处置方式（disposition）**，位于 `SubprocessSpawnSpec` 上：`'pipe'`（原始的 `Readable`/`Writable`，供消费方自有的协议分帧使用）、`'inherit'`（诊断输出直通父进程的流），以及收集模式（collect）`{ maxBytes, spill? }`——即最初的有界尾部保留形状，只是 spill 文件改为可选，使诊断尾部（例如语言服务器的 stderr）无需落盘即可缓冲。stdin 则为 `'ignore'`、`'pipe'` 或 `{ data }`（写完即关闭的批量形式）。
-- **`SubprocessOutcome` 只承载退出事实**（Node close 事件的词汇）；收集到的输出在结算后仍可经 `handle.collected` 读取（spill 文件描述符在结算边界封存），因此批量与流式调用方共用一条访问路径，也没有任何内容被复制进这份结果。
-- **以进程树为范围的终止，集中在一个动词后面**：`terminate()` 拥有 SIGTERM→宽限期→SIGKILL 升级（也承接 spec 的 abort 信号，进程树消亡后为空操作）——句柄不暴露单信号的 `kill(signal?)`，因此消费方无法跳过宽限窗口；`waitForExit()` 轮询进程树存活状态（POSIX 进程组探测；Windows 上以直接子进程为界）。Windows 进程树终止（`taskkill /T`，可注入）自 lsp-local 迁入，因此每个消费方拿到的进程树语义在各平台上都正确。（最初从 `subagent-subprocess` 吸收的以 stdin EOF 打头的 dispose 阶梯，后来又移回其唯一消费方——见[阶梯归属 Agent Note](2026-07-27-dispose-ladder-to-consumer.md)。）
-- **凭据清除只有一份定义**：`scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` 定义在 seam 上。普通本地 spawn 与终端本地 spawn 都在 `dsh-subprocess-local` 内部应用该定义；mcp-client 仍需导入它，因为 MCP SDK 拥有该传输层 spawn，SDK helper 的 `scrubEnvironment()` 默认同样委托给它。
-
-各项迁移随这次重塑一并落地：**bash-local/bash-sandbox**（收集模式 + 批量 stdin；bash 的 `kill()` 映射到 `terminate()`，因此 `task_kill` 保有升级语义），**lsp-local**（管道化的协议流 + 无 spill 的 stderr 收集尾部；`LspConnection` 改为接收 seam 的 spawn 函数；其私有的进程树操作辅助函数已删除），**subagent-acp**（管道化的 ndjson 流 + inherit 的 stderr；spawn 失败经 `done` 的 reject 汇入同一个启动竞态；dispose 是后端自有的 `disposeAcpChild` 阶梯，经由 seam 的动词运行，携带插件所配置的宽限期），以及后来通过[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)迁移的 **pty-local**（`node-pty` 分配与进程检查位于 `spawnTerminal()` 之后，就绪状态和终端策略仍归消费方所有）。**`dsh-subagent-subprocess` 已删除**——dispose 阶梯与凭据清除归 seam 所有；无人使用的隔离配置目录辅助函数随之消亡（其消费方本就不存在）。
-
-挂载 lsp-local 或 subagent-acp 的组合如今都加载 `dsh-subprocess-local`（这两个插件注入 `'subprocess'`）；acp/lsp 测试 fixture（测试前置数据）补上了这一行组合配置。
-
-## 曾考虑的替代方案
-
-**保持只支持批量的 seam，让流式消费方继续各自为政。**这正是引入该 seam 的 Agent Note 当初的立场，评审将其否决：这样会留下三份进程树信号发送的私有副本和五份凭据清除的私有副本，而未来任何运行器（容器化执行器、远程进程宿主）都得挑选去 fork 哪一份私有副本。Node 形状的处置方式覆盖已观察到的全部三种流形状，既不拓宽结果类型，也不缓冲管道化的流。
-
-**用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式一次性统辖全部三条流。**否决：真实消费方按流混用模式（lsp：pipe/pipe/collect；acp：pipe/pipe/inherit；bash：data/collect/collect）。按流划分的处置方式恰好就是 Node 的形状，也免去了混用场景的第二个 spawn 调用。
-
-**让 pty-local 与 mcp-client 的 spawn 留在服务之外。**MCP SDK 仍拥有其传输层 spawn。PTY 分配则不同：[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)把 `node-pty` 放到一个深层终端原语之后，既解决所有权异议，也不假装普通管道化 spawn 能够提供终端语义。
-
-**迁移 test-support 启动器（acp-snapshot、loader-smoke）与 SDK package-manager 运行器。**否决：support 各包（package）是刻意保持轻依赖的测试基础设施，不得依赖产品 seam；而 SDK 向导那套附带重定向的 `stdio: 'inherit'` 语义，加上其完全脱离组合的生命周期（根本没有 cordis 上下文），使该服务并不合用；它改为共享凭据清除。
-
-## 后果
-
-换来的是：进程树信号发送、升级、有界收集、终端进程机制与凭据清除各自只剩一份实现，且只在 `dsh-subprocess-local` 的测试套件中测试一次（其中包括 lsp-local 的私有副本从未有过的、以注入平台方式实现的 Windows 覆盖）；lsp-local、pty-local 与 subagent-acp 卸下了提供方专用的进程管道，其子进程如今像 bash 的一样随组合拆除而终止；一个完整的包（`dsh-subagent-subprocess`）就此消失。seam README 中「只有一个消费方家族」的限制说明也随之退役。
-
-代价是：这道 seam 变宽了，涵盖执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语，未来的后端因此要实现更宽的表面；lsp-local、pty-local 与 subagent-acp 的各组合如今都多出 subprocess 这一行组合配置；`SubprocessOutcome` 也不再承载输出，这是仍未发布的堆叠变更内部的一次破坏性形状变更。MCP／SDK／test-support 的 spawn 因所有权归属留在该服务之外，以凭据清除作为共享底线。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 94711572d6..0b62184128 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: d5dee7361e48f18f3147444b2db74da3dd1c1161
-2026-07-26-subprocess-seam.zh.md: 884c572dc65c0fbf240f7e4e3b0387038e21f5ad
+2026-07-26-subprocess-seam.md: 359977ac6a50394405163bc060f3a39eb68891fb
+2026-07-26-subprocess-seam.zh.md: 551fcc8f4df82d0c893d8e6f5423f172dfd5d9c5
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index d5dee7361e..359977ac6a 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Its vocabulary includes per-stream stdio dispositions, process and terminal handles, exit facts with deliberately no timeout/cancel classification, and the shared scrub plus `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` types. `argv` is never shell-interpreted.
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, credential scrub with explicit env merged after it, tree cleanup, and disposal that terminates and joins every managed process. It has no config; every limit arrives on the spec. Bash and PTY presentation environment overrides stay in their consumers.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
@@ -21,11 +21,17 @@ Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-su
 
 Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral seam shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
+Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy; Code Runtime uses ordinary raw pipes. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
+
 ## Alternatives considered
 
 **Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
 
-**Migrate the repo's other spawn sites in the introducing change.** Rejected as scope creep with real design risk at that scale. The later [consumer-migration](2026-07-26-subprocess-consumer-migration.md) and [portable execution-world](2026-07-28-portable-execution-world-consumers.md) decisions reshape the interface around the observed LSP, subagent, PTY, and Code Runtime consumers; SDK and test-support launchers remain outside by ownership.
+**Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, PTY, and Code Runtime shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
+
+**Use one `stdio: 'pipe' | 'inherit' | 'collect'` mode for all streams.** Rejected because real consumers mix modes per stream: LSP uses pipe/pipe/collect, ACP uses pipe/pipe/inherit, and Bash uses data/collect/collect.
+
+**Route every process launch through `ctx.subprocess`.** Rejected because the MCP SDK owns its transport spawn, the SDK wizard has no Cordis context and needs inherited redirection, the TUI probe is synchronous, and support launchers deliberately stay independent of product seams. PTY allocation did move behind `spawnTerminal()` because the provider, not the consumer, owns that substrate-specific primitive.
 
 **Put `run_in_background`/task semantics into the process seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The process seam sits *below* the bash executor, not beside the task registry.
 
@@ -33,6 +39,6 @@ Background-process lifetime moved from the executor to the subprocess service: t
 
 ## Consequences
 
-Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; the shared `DSH_*`/output vocabulary has a non-shell home; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
+Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; tree signalling, escalation, bounded collection, terminal mechanics, and credential scrubbing each have one implementation; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
 
-Cost: one more package pair and one more composition row everywhere a bash executor loads — a boot that loads an executor without the subprocess service leaves `ctx.bash` pending on `ctx.subprocess` (standard missing-service behavior). The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages now name the same types; the subprocess seam is the owner and the bash seam documents the re-export. The spawn-failure note became single-delivery through the read path where the old plumbing retained it in the stderr buffer for repeated `readFrom(0)` reads — acceptable because the bash background read path was already a consuming cursor, and the note reaches the one reader that exists.
+Cost: one more package pair and one more composition row wherever a consumer loads; a missing subprocess provider leaves the consumer pending by standard service-injection behavior. Every backend implements execution-world coordinates, executable lookup, three stdio modes, tree lifecycle, and one terminal primitive. The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages name the same types; the subprocess seam is the owner. The spawn-failure note became single-delivery through Bash's consuming read cursor instead of repeatable stderr-buffer content.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 884c572dc6..551fcc8f4d 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。其词汇包括按流划分的 stdio 处置方式（disposition）、进程与终端句柄、刻意不含超时／取消分类的退出事实，以及共享的凭据清除与 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` 类型。`argv` 绝不经过 shell 解释。
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查、清除之后合并显式 env 的凭据清除、进程树清理，以及终止每个受管进程并等待其退出的 dispose。该实现没有任何配置；每项限制都随 spec 到达。Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
@@ -21,11 +21,17 @@ Status: implemented
 
 后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
+基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略；Code Runtime 使用普通原始管道。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
+
 ## 曾考虑的替代方案
 
 **把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
 
-**在引入 seam 的同一变更中迁移仓库其余 spawn 调用点。**否决，因为在当时的规模下属于带有真实设计风险的范围蔓延。后续的[消费方迁移](2026-07-26-subprocess-consumer-migration.md)与[可移植执行环境](2026-07-28-portable-execution-world-consumers.md)决策围绕已观察到的 LSP、subagent、PTY 与 Code Runtime 消费方重塑接口；SDK 与 test-support 启动器因所有权归属仍留在服务之外。
+**保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP、PTY 与 Code Runtime 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
+
+**用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式统一全部流。**否决：真实消费方按流混用模式——LSP 使用 pipe/pipe/collect，ACP 使用 pipe/pipe/inherit，Bash 使用 data/collect/collect。
+
+**把每一次进程启动都路由到 `ctx.subprocess`。**否决：MCP SDK 拥有其传输 spawn，SDK 向导没有 Cordis 上下文且需要继承式重定向，TUI 探测是同步的，support 启动器则刻意独立于产品 seam。PTY 分配迁到 `spawnTerminal()`，因为这项底层专用原语归提供方而非消费方所有。
 
 **改把 `run_in_background`/任务语义放进进程 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。进程 seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
@@ -33,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP（Agent Client Protocol）消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；共享的 `DSH_*`/输出词汇有了一个不带 shell 含义的归属；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
+换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP 消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；进程树信号、升级终止、有界收集、终端机制与凭据清除各自只剩一份实现；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
 
-代价是：多出一对包，而且凡加载 bash 执行器之处都多一行组合配置。若某次启动加载了执行器却没有加载管理器，`ctx.bash` 会因等待 `ctx.subprocess` 而保持挂起（标准的服务缺失行为）。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包如今命名同一批类型；进程 seam 是所有者，bash seam 则记录这层重导出。spawn 失败提示经由读取路径变为单次交付，而旧管道曾把它保留在 stderr 缓冲区里，供重复的 `readFrom(0)` 读取；这一点可以接受，因为 bash 的后台读取路径本就是消费游标，该提示能到达唯一存在的那个读取方。
+代价是：多出一对包，而且凡加载消费方之处都多一行组合配置；缺少 subprocess 提供方时，消费方会按标准服务注入行为保持挂起。每个后端都要实现执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包命名同一批类型；进程 seam 是所有者。spawn 失败提示经由 Bash 的消费式读取游标变为单次交付，不再是可重复读取的 stderr 缓冲内容。

From 68ccf50a77f34288de50d5008eb636851cd48e18 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 02:04:21 +0800
Subject: [PATCH 081/262] refactor(code-runtime): generate shared subprocess
 runner

---
 package.json                                  |   2 +
 .../code-runtime-worker/src/bootstrap.ts      |  19 +-
 .../code-runtime-worker/src/runtime-host.ts   |  26 +-
 .../tests/bootstrap.spec.ts                   |  27 ++
 .../src/runner-source.generated.ts            |   6 +
 packages/util/atomic-write/src/runner.ts      | 390 ++++++++++++++++++
 scripts/gen-code-runtime-runner.ts            |  70 ++++
 scripts/run-gates.ts                          |   1 +
 vitest.config.ts                              |  96 +----
 9 files changed, 555 insertions(+), 82 deletions(-)
 create mode 100644 packages/util/atomic-write/src/runner-source.generated.ts
 create mode 100644 packages/util/atomic-write/src/runner.ts
 create mode 100644 scripts/gen-code-runtime-runner.ts

diff --git a/package.json b/package.json
index 423cbf813c..2b4971a6b7 100644
--- a/package.json
+++ b/package.json
@@ -112,6 +112,8 @@
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
     "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
+    "gen-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts",
+    "verify-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts --check",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
     "doc-sync": "tsx scripts/run-gates.ts doc-sync",
diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
index cbe0d0ac55..2207389c97 100644
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -6,6 +6,7 @@
  */
 
 import { inspect } from 'node:util'
+import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
 import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
 import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
 import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
@@ -310,6 +311,7 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
  * @param pending - the id-keyed map each posted call parks its handles in.
  * @param nextId - the shared mutable id counter (worker-issued correlation ids).
  * @param errorClasses - per-namespace constructors shared with program globals.
+ * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns one namespace object per declaration, in declaration order.
  */
 export function makeNamespaces(
@@ -318,6 +320,7 @@ export function makeNamespaces(
   pending: Map<number, PendingCall>,
   nextId: { value: number },
   errorClasses: Map<string, BindingErrorConstructor> = makeBindingErrorClasses(data),
+  maxFrameBytes?: number,
 ): Record<string, unknown>[] {
   return data.namespaces.map(({ global, names }) => {
     const errorClass = errorClasses.get(global)
@@ -335,6 +338,11 @@ export function makeNamespaces(
           if (detached === undefined) {
             return Promise.reject(bindingFailure(errorClass, name, 'binding arguments must be lossless JSON'))
           }
+          const call = { type: 'call' as const, id: nextId.value, global, name, args: encodeWorkerJson(detached) }
+          if (maxFrameBytes !== undefined
+            && jsonValueBytesUpTo(call as unknown as CodeJsonValue, maxFrameBytes) === undefined) {
+            return Promise.reject(bindingFailure(errorClass, name, 'binding arguments exceed maxFrameBytes'))
+          }
           return new Promise((resolve, reject) => {
             const id = nextId.value++
             pending.set(id, {
@@ -344,7 +352,7 @@ export function makeNamespaces(
               },
             })
             try {
-              port.postMessage({ type: 'call', id, global, name, args: encodeWorkerJson(detached) })
+              port.postMessage(call)
             } catch (error: unknown) {
               pending.delete(id)
               const message = `binding arguments must be structured-cloneable: ${error instanceof CapturedError ? error.message : String(error)}`
@@ -364,12 +372,14 @@ export function makeNamespaces(
  * @param port - host message port or test double.
  * @param data - the boot payload the host sent.
  * @param streams - stdout/stderr objects captured as program logs.
+ * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns after posting the done message.
  */
 export async function runWorkerMain(
   port: BootstrapPort,
   data: WorkerBootData,
   streams: { stdout: PatchableStream; stderr: PatchableStream },
+  maxFrameBytes?: number,
 ): Promise<void> {
   const logs = new LogBuffer(
     data.maxOutputBytes,
@@ -384,7 +394,7 @@ export async function runWorkerMain(
 
   const nextId = { value: 1 }
   const errorClasses = makeBindingErrorClasses(data)
-  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses)
+  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses, maxFrameBytes)
   const errorClassParameters: string[] = []
   const errorClassValues: BindingErrorConstructor[] = []
   for (const namespace of data.namespaces) {
@@ -420,5 +430,8 @@ export async function runWorkerMain(
       ...prepareException(error, logs.remainingOutputBytes(), data.maxOutputBytes),
     }
   }
-  port.postMessage(done)
+  port.postMessage(maxFrameBytes !== undefined
+    && jsonValueBytesUpTo(done as unknown as CodeJsonValue, maxFrameBytes) === undefined
+    ? { type: 'output-limit' }
+    : done)
 }
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index d2bb1082b8..47bfacfe91 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -1,6 +1,7 @@
 /** Shared host mechanics for local and subprocess-hosted TypeScript worker runtimes. */
 
 import { stripTypeScriptTypes } from 'node:module'
+import type { Readable } from 'node:stream'
 import type {
   CodeBindingNamespace,
   CodeJsonValue,
@@ -15,6 +16,28 @@ import type { WorkerJsonWire } from './worker-json.ts'
 /** Smallest cap that can represent an empty log array and failure message. */
 export const MIN_RUNTIME_OUTPUT_BYTES = 4
 
+/**
+ * Resolve after a worker pipe emits queued data or closes during termination.
+ * @param stream - captured worker or child-process pipe.
+ * @returns after no more queued bytes can arrive.
+ */
+export function waitForRuntimePipeDrain(stream: Readable): Promise<void> {
+  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
+  return new Promise((resolve) => {
+    const done = (): void => {
+      stream.off('end', done)
+      stream.off('close', done)
+      stream.off('error', done)
+      resolve()
+    }
+    stream.once('end', done)
+    stream.once('close', done)
+    stream.once('error', done)
+    /* v8 ignore next -- termination can win the adjacent listener-registration race. */
+    if (stream.readableEnded || stream.destroyed) done()
+  })
+}
+
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 const RESERVED_WORDS = new Set([
   'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
@@ -223,5 +246,6 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-export { jsonValueBytesUpTo } from './output-json.ts'
+export { jsonStringBytesUpTo, jsonValueBytesUpTo } from './output-json.ts'
+export { runWorkerMain } from './bootstrap.ts'
 export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
index a2aac6d9c2..247501df29 100644
--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -286,6 +286,23 @@ describe('makeNamespaces', () => {
     expect(nextId.value).toBe(1)
   })
 
+  it('rejects an oversized transport frame before posting or allocating a call id', async () => {
+    const port = new FakePort()
+    const pending = new Map<number, PendingCall>()
+    const nextId = { value: 1 }
+    const data = { namespaces: [toolNamespace(['x'])] }
+    const [tools] = makeNamespaces(
+      data, port, pending, nextId, makeBindingErrorClasses(data), 64,
+    ) as [Record<string, (args: unknown) => Promise<unknown>>]
+
+    await expect(tools.x?.({ text: 'x'.repeat(64) })).rejects.toMatchObject({
+      name: 'ToolCallError', toolName: 'x', message: 'binding arguments exceed maxFrameBytes',
+    })
+    expect(port.sent).toEqual([])
+    expect(pending.size).toBe(0)
+    expect(nextId.value).toBe(1)
+  })
+
   it('uses ordinary Error for non-tools namespace failures', async () => {
     const deniedPort = new FakePort()
     deniedPort.respond = message => message.type === 'call'
@@ -343,6 +360,16 @@ describe('runWorkerMain', () => {
     })
   })
 
+  it('reports output-limit before posting a completion that expands past the transport cap', async () => {
+    const port = new FakePort()
+    await runWorkerMain(port, {
+      maxOutputBytes: 1_000,
+      code: 'return Array.from({ length: 100 }, () => [])',
+      namespaces: [],
+    }, fakeStreams(), 100)
+    expect(port.sent.at(-1)).toEqual({ type: 'output-limit' })
+  })
+
   it('reports a thrown program error on the done message', async () => {
     const port = new FakePort()
     await runWorkerMain(port, { ...BOOT, code: 'throw new Error("boom")', namespaces: [] }, fakeStreams())
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
new file mode 100644
index 0000000000..d40c77783c
--- /dev/null
+++ b/packages/util/atomic-write/src/runner-source.generated.ts
@@ -0,0 +1,6 @@
+/**
+ * Generated dependency-free execution-world runner.
+ * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
+ */
+
+export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,me=Object.defineProperty,he=Object.getOwnPropertyDescriptor,T=Object.getPrototypeOf,ge=Object.hasOwn,E=Object.is,_e=Object.keys,D=Object.prototype,ve=Reflect.get(D,`propertyIsEnumerable`),O=Reflect.ownKeys,ye=Reflect.get(Set.prototype,`add`),be=Reflect.get(Set.prototype,`delete`),xe=Reflect.get(Set.prototype,`has`);function k(e){let t=pe(null);return t.value=e,t}function A(e,t,n){let r=k(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,me(e,t,r)}function j(e,t){A(e,e.length,t)}function M(e){if(e.length===0)return;let t=e.length-1,n=e[t];return me(e,`length`,k(t)),n}function N(e,t){return b(xe,e,[t])}function P(e,t){b(ye,e,[t])}function Se(e,t){b(be,e,[t])}function F(e,t){let n=he(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function I(e){return T(e)===null&&F(e,`Object`)}function L(e){let t=T(e);if(t===de)return!0;if(!C(t)||!F(t,`Array`))return!1;let n=T(t);return typeof n==`object`&&!!n&&I(n)}function R(e){let t=T(e);return t===null||t===D||typeof t==`object`&&I(t)}function z(e){let t=O(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ve,e,[r]))return}return t}function B(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?A(e.target,e.index,t):A(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=M(i);e!==void 0;e=M(i)){if(e.kind===`leave`){Se(t,e.source);continue}if(e.kind===`array-item`){if(!ge(e.source,e.index))return;j(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){j(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||E(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||N(t,n))return;if(C(n)){if(!L(n))return;let a=n.length;if(O(n).length!==a+1)return;let o=[];r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)j(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!R(n))return;let a=z(n);if(a===void 0)return;let o={};r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;j(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function V(e){let t=[],n=[e];for(let e=M(n);e!==void 0;e=M(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){j(t,e);continue}if(C(e)){j(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);j(n,r)}continue}let r=_e(e);j(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);j(n,a)}}return t}function H(e){if(!L(e)||O(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!ge(e,t))return!1;return!0}function U(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Ce(e){if(C(e)||!R(e))return;let t=z(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!U(t,`kind`)||!U(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!U(t,`kind`)||!U(t,`keys`))return;let e=n.keys;if(!C(e)||!H(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||N(r,t))return;P(r,t),j(i,t)}return{kind:`object`,keys:i}}}function W(e){try{if(!C(e)||!H(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)j(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;A(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||E(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Ce(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&j(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;M(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,we=Object.create,Te=Object.defineProperty;function K(e,t,n){let r=we(null);r.enumerable=!0,r.value=n,Te(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=B(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:V(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),K(this,`name`,e.name),K(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=W(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=B(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:V(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=W(e);return t===void 0?null:V(t)}function qe(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Je(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=qe(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}c||(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($()):t.type===`output-limit`?l({type:`output-limit`}):t.type===`done`&&(t.error===void 0?l({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):Ue(t.error)&&l({type:`done`,error:t.error})))}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ge(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=Ke(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Ye(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ge(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);t!==void 0&&(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($()):t.type===`log`&&typeof t.text==`string`?o({type:`log`,text:t.text})||s($()):t.type===`output-limit`?s({type:`output-limit`}):t.type===`done`&&(t.error===void 0?s({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):We(t.error)&&s({type:`done`,error:t.error})))}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=Ke(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Ye():Je();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
new file mode 100644
index 0000000000..7a0b3eb678
--- /dev/null
+++ b/packages/util/atomic-write/src/runner.ts
@@ -0,0 +1,390 @@
+/** Typed source for the dependency-free execution-world runner bundle. */
+
+import { Buffer } from 'node:buffer'
+import { fork } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import type { Readable } from 'node:stream'
+import { inspect } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
+import {
+  decodeWorkerJson,
+  encodeWorkerJson,
+  jsonStringBytesUpTo,
+  runWorkerMain,
+  waitForRuntimePipeDrain,
+} from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
+import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
+
+type WorkerBootData = Parameters<typeof runWorkerMain>[1]
+type Controller = ChildProcess & { stdout: Readable; stderr: Readable }
+type FailureKind = 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
+
+interface RuntimeBootData extends WorkerBootData {
+  type: 'boot'
+  maxFrameBytes: number
+  maxOldGenerationSizeMb: number
+  computeMs: number
+}
+
+interface RuntimeFailure {
+  kind: FailureKind
+  message: string
+}
+
+interface RuntimeCall {
+  type: 'call'
+  id: number
+  global: string
+  name: string
+  args: WorkerJsonWire | null
+}
+
+type RuntimeReply =
+  | { type: 'reply'; id: number; ok: true; value: unknown }
+  | { type: 'reply'; id: number; ok: false; message: string }
+
+type RuntimeMessage = RuntimeCall
+  | { type: 'log'; text: string }
+  | { type: 'output-limit' }
+  | { type: 'done'; value?: WorkerJsonWire | null; error?: RuntimeFailure }
+
+const failureKinds = new Set<FailureKind>([
+  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
+])
+
+let maxFrameBytes = 0
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
+}
+
+function encodeJsonBounded(value: unknown, maxBytes: number): string | undefined {
+  try {
+    const json: unknown = JSON.stringify(value)
+    return typeof json === 'string' && Buffer.byteLength(json) <= maxBytes ? json : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function emitJson(json: string): void {
+  process.stdout.write(json)
+  process.stdout.write('\n')
+}
+
+function emitFrame(message: RuntimeMessage): boolean {
+  const json = encodeJsonBounded(message, maxFrameBytes)
+  if (json === undefined) return false
+  emitJson(json)
+  return true
+}
+
+function validFailure(value: unknown): value is RuntimeFailure {
+  const record = recordOf(value)
+  return record !== undefined
+    && typeof record.kind === 'string'
+    && failureKinds.has(record.kind as FailureKind)
+    && typeof record.message === 'string'
+}
+
+function validWorkerFailure(value: unknown): value is RuntimeFailure {
+  return validFailure(value)
+    && (value.kind === 'exception' || value.kind === 'invalid-output' || value.kind === 'output-limit')
+}
+
+function runtimeBoot(value: unknown): RuntimeBootData | undefined {
+  const record = recordOf(value)
+  if (record === undefined
+    || record.type !== 'boot'
+    || typeof record.code !== 'string'
+    || !Array.isArray(record.namespaces)
+    || !Number.isSafeInteger(record.maxOutputBytes)
+    || (record.maxOutputBytes as number) < 4
+    || !Number.isSafeInteger(record.maxFrameBytes)
+    || (record.maxFrameBytes as number) < (record.maxOutputBytes as number)
+    || typeof record.computeMs !== 'number'
+    || !Number.isFinite(record.computeMs)
+    || (record.computeMs) <= 0
+    || typeof record.maxOldGenerationSizeMb !== 'number'
+    || !Number.isFinite(record.maxOldGenerationSizeMb)
+    || (record.maxOldGenerationSizeMb) <= 0) return undefined
+  return record as unknown as RuntimeBootData
+}
+
+function runtimeReply(value: unknown): RuntimeReply | undefined {
+  const record = recordOf(value)
+  if (record === undefined || record.type !== 'reply' || typeof record.id !== 'number' || typeof record.ok !== 'boolean') return undefined
+  return record.ok
+    ? { type: 'reply', id: record.id, ok: true, value: record.value }
+    : { type: 'reply', id: record.id, ok: false, message: String(record.message) }
+}
+
+function transportWireOrNull(input: unknown): WorkerJsonWire | null {
+  const value = decodeWorkerJson(input)
+  return value === undefined ? null : encodeWorkerJson(value)
+}
+
+function waitForChildExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise((resolve) => { child.once('exit', () => { resolve() }) })
+}
+
+function frameLimitFailure(): RuntimeMessage {
+  return {
+    type: 'done',
+    error: { kind: 'worker-exit', message: 'code runtime bridge frame exceeded maxFrameBytes' },
+  }
+}
+
+function runLauncher(): void {
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  let controller: Controller | undefined
+  let maxOutputBytes = 0
+  let logBytes = 2
+  let logEntries = 0
+  let settling = false
+
+  const finish = (message: RuntimeMessage): void => {
+    if (settling) return
+    const encoded = encodeJsonBounded(message, maxFrameBytes)
+      ?? encodeJsonBounded(frameLimitFailure(), maxFrameBytes)
+    settling = true
+    if (encoded !== undefined) emitJson(encoded)
+    const current = controller
+    controller = undefined
+    const drain = current === undefined
+      ? Promise.resolve()
+      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
+        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
+        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
+        const exited = waitForChildExit(current)
+        current.kill('SIGKILL')
+        await Promise.all([exited, stdoutDrained, stderrDrained])
+      })
+    void drain.catch((error: unknown) => {
+      process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(error)}\n`)
+    }).then(() => {
+      input.close()
+      process.stdin.destroy()
+    })
+  }
+
+  const forwardLog = (text: string): void => {
+    if (settling) return
+    const separator = logEntries > 0 ? 1 : 0
+    const cost = jsonStringBytesUpTo(text, maxOutputBytes - logBytes - separator)
+    if (cost === undefined) {
+      finish({ type: 'output-limit' })
+      return
+    }
+    logBytes += cost + separator
+    logEntries += 1
+    if (!emitFrame({ type: 'log', text })) finish(frameLimitFailure())
+  }
+
+  const startController = (boot: RuntimeBootData): void => {
+    maxOutputBytes = boot.maxOutputBytes
+    maxFrameBytes = boot.maxFrameBytes
+    controller = fork(fileURLToPath(import.meta.url), [], {
+      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
+      detached: false,
+      execArgv: [],
+      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    }) as Controller
+    const current = controller
+    current.stdout.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
+    current.stderr.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
+    current.on('message', (raw: unknown) => {
+      const message = recordOf(raw)
+      if (message === undefined) return
+      if (message.type === 'log' && typeof message.text === 'string') {
+        forwardLog(message.text)
+        return
+      }
+      if (settling) return
+      if (message.type === 'call'
+        && typeof message.id === 'number'
+        && typeof message.global === 'string'
+        && typeof message.name === 'string') {
+        if (!emitFrame({
+          type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
+        })) finish(frameLimitFailure())
+      } else if (message.type === 'output-limit') {
+        finish({ type: 'output-limit' })
+      } else if (message.type === 'done') {
+        if (message.error !== undefined) {
+          if (validFailure(message.error)) finish({ type: 'done', error: message.error })
+        } else {
+          finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
+        }
+      }
+    })
+    current.on('error', (error: Error) => {
+      finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller error: ${error.message}` } })
+    })
+    current.on('exit', (code: number | null) => {
+      if (!settling) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller exited with code ${code} before completing` } })
+      }
+    })
+    current.send(boot, (error: Error | null) => {
+      if (error !== null) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller boot failed: ${error.message}` } })
+      }
+    })
+  }
+
+  input.on('line', (line: string) => {
+    let raw: unknown
+    try {
+      raw = JSON.parse(line) as unknown
+    } catch (error: unknown) {
+      process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(error)}\n`)
+      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
+      return
+    }
+    if (controller === undefined) {
+      const boot = runtimeBoot(raw)
+      if (boot === undefined) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        return
+      }
+      startController(boot)
+      return
+    }
+    const reply = runtimeReply(raw)
+    if (reply !== undefined) {
+      controller.send(reply, (error: Error | null) => {
+        if (error !== null) {
+          finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller reply failed: ${error.message}` } })
+        }
+      })
+    }
+  })
+  input.on('close', () => {
+    if (controller !== undefined && !settling) {
+      finish({ type: 'done', error: { kind: 'abort', message: 'remote runner input closed' } })
+    }
+  })
+}
+
+function runController(): void {
+  let worker: Worker | undefined
+  let finished = false
+  let computeTimer: NodeJS.Timeout | undefined
+  let controllerMaxFrameBytes = 0
+
+  const send = (message: RuntimeMessage): boolean => {
+    if (process.send === undefined) return false
+    if (controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined) return false
+    process.send(message)
+    return true
+  }
+
+  const finish = (message: RuntimeMessage): void => {
+    if (finished) return
+    finished = true
+    clearInterval(computeTimer)
+    const bounded = controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined
+      ? frameLimitFailure()
+      : message
+    const current = worker
+    worker = undefined
+    const drain = current === undefined
+      ? Promise.resolve()
+      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
+        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
+        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
+        await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
+      })
+    void drain.catch((error: unknown) => {
+      send({ type: 'log', text: `dsh-code-runtime-subprocess worker cleanup error: ${String(error)}\n` })
+    }).then(() => {
+      if (process.send === undefined) {
+        process.exitCode = 1
+        return
+      }
+      process.send(bounded, () => { if (process.connected) process.disconnect() })
+    })
+  }
+
+  process.on('message', (raw: unknown) => {
+    if (worker === undefined) {
+      const boot = runtimeBoot(raw)
+      if (boot === undefined) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
+        return
+      }
+      controllerMaxFrameBytes = boot.maxFrameBytes
+      worker = new Worker(new URL(import.meta.url), {
+        workerData: boot,
+        env: {},
+        execArgv: [],
+        stdout: true,
+        stderr: true,
+        resourceLimits: { maxOldGenerationSizeMb: boot.maxOldGenerationSizeMb },
+      })
+      const current = worker
+      current.stdout.on('data', (data: Buffer) => {
+        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
+      })
+      current.stderr.on('data', (data: Buffer) => {
+        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
+      })
+      current.on('message', (messageRaw: unknown) => {
+        const message = recordOf(messageRaw)
+        if (message === undefined) return
+        if (message.type === 'call'
+          && typeof message.id === 'number'
+          && typeof message.global === 'string'
+          && typeof message.name === 'string') {
+          if (!send({
+            type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
+          })) finish(frameLimitFailure())
+        } else if (message.type === 'log' && typeof message.text === 'string') {
+          if (!send({ type: 'log', text: message.text })) finish(frameLimitFailure())
+        } else if (message.type === 'output-limit') {
+          finish({ type: 'output-limit' })
+        } else if (message.type === 'done') {
+          if (message.error !== undefined) {
+            if (validWorkerFailure(message.error)) finish({ type: 'done', error: message.error })
+          } else {
+            finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
+          }
+        }
+      })
+      current.on('error', (error: Error) => {
+        finish({
+          type: 'done',
+          error: { kind: 'worker-exit', message: `worker error: ${error.stack || error.message || inspect(error)}` },
+        })
+      })
+      current.on('exit', (code: number) => {
+        if (!finished) {
+          finish({ type: 'done', error: { kind: 'worker-exit', message: `worker exited with code ${code} before completing` } })
+        }
+      })
+      computeTimer = setInterval(() => {
+        if (worker !== undefined && worker.performance.eventLoopUtilization().active > boot.computeMs) {
+          finish({ type: 'done', error: { kind: 'timeout', message: `compute budget exhausted (${boot.computeMs}ms busy)` } })
+        }
+      }, 25)
+      return
+    }
+    const reply = runtimeReply(raw)
+    if (reply !== undefined) worker.postMessage(reply)
+  })
+  process.on('disconnect', () => { if (worker !== undefined && !finished) void worker.terminate() })
+}
+
+if (!isMainThread) {
+  if (parentPort === null) throw new Error('remote worker requires parentPort')
+  const boot = workerData as RuntimeBootData
+  void runWorkerMain(parentPort, boot, { stdout: process.stdout, stderr: process.stderr }, boot.maxFrameBytes)
+} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
+  runController()
+} else {
+  runLauncher()
+}
diff --git a/scripts/gen-code-runtime-runner.ts b/scripts/gen-code-runtime-runner.ts
new file mode 100644
index 0000000000..7e856e7651
--- /dev/null
+++ b/scripts/gen-code-runtime-runner.ts
@@ -0,0 +1,70 @@
+/** Generate the subprocess Code Runtime's dependency-free runner bundle. */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { build } from 'tsdown'
+
+const root = resolve(import.meta.dirname, '..')
+const ENTRY = 'packages/code-runtime/code-runtime-subprocess/src/runner.ts'
+const OUT = 'packages/code-runtime/code-runtime-subprocess/src/runner-source.generated.ts'
+
+/**
+ * Bundle the typed runner and shared worker implementation into one source literal.
+ * @returns generated TypeScript module consumed by the subprocess backend.
+ */
+export async function renderCodeRuntimeRunner(): Promise<string> {
+  const bundles = await build({
+    config: false,
+    entry: [resolve(root, ENTRY)],
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    write: false,
+    dts: false,
+    clean: false,
+    minify: true,
+    logLevel: 'silent',
+    report: false,
+    deps: { alwaysBundle: ['@deepseek-ai/dsh-code-runtime-worker'] },
+  })
+  try {
+    const chunks = bundles.flatMap(bundle => bundle.chunks).filter(chunk => chunk.type === 'chunk')
+    if (chunks.length !== 1) throw new Error(`gen-code-runtime-runner: expected one chunk, received ${chunks.length}`)
+    const chunk = chunks[0]
+    if (chunk === undefined) throw new Error('gen-code-runtime-runner: runner chunk is missing')
+    const external = chunk.imports.filter(specifier => !specifier.startsWith('node:'))
+    if (external.length > 0) {
+      throw new Error(`gen-code-runtime-runner: runner retained external imports: ${external.join(', ')}`)
+    }
+    return [
+      '/**',
+      ' * Generated dependency-free execution-world runner.',
+      ' * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.',
+      ' */',
+      '',
+      `export const CODE_RUNNER_SOURCE = ${JSON.stringify(chunk.code)}`,
+      '',
+    ].join('\n')
+  } finally {
+    await Promise.all(bundles.map(async (bundle) => { await bundle[Symbol.asyncDispose]() }))
+  }
+}
+
+async function main(): Promise<void> {
+  const content = await renderCodeRuntimeRunner()
+  const output = resolve(root, OUT)
+  if (process.argv.includes('--check')) {
+    const committed = existsSync(output) ? readFileSync(output, 'utf8') : null
+    if (committed === content) {
+      console.log(`gen-code-runtime-runner: ${OUT} is up to date.`)
+      return
+    }
+    console.error(`gen-code-runtime-runner: ${OUT} is stale. Run \`pnpm run gen-code-runtime-runner\` and commit it.`)
+    process.exitCode = 1
+    return
+  }
+  writeFileSync(output, content)
+  console.log(`gen-code-runtime-runner: wrote ${OUT}.`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) await main()
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 74a09a874e..6f59b64826 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -585,6 +585,7 @@ function docSyncLeafGates(options: {
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
     pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
+    pnpmScript('code-runtime-runner', 'verify-code-runtime-runner', { label: 'code-runtime runner' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links' }),
diff --git a/vitest.config.ts b/vitest.config.ts
index 6eb1bda354..996f2456c7 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,16 +1,5 @@
-import { spawnSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
-import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
-import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
-import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
-
-// Prints exact `path:line:col` records for every uncovered statement, branch
-// path, and function when a file misses the per-file 100% gate — the built-in
-// threshold ERRORs name only the file. Absolute path because istanbul-reports
-// require()s custom reporters (which is also why the reporter is CJS).
-const uncoveredLocationsReporter = fileURLToPath(new URL('./scripts/coverage-uncovered-locations.cjs', import.meta.url))
 
 // Resolution facade shared by every plugin instance below: tsconfig.base.json
 // has no include, which vite-tsconfig-paths treats as match-all, so its paths
@@ -20,14 +9,7 @@ const pathsPlugin = (): ReturnType<typeof tsconfigPaths> => tsconfigPaths({ proj
 
 const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
-      // Bash-requiring suites (a real POSIX shell is unavailable on Windows).
-      // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
-      // INCLUDED: PowerShell ships with Windows, so they run natively here.
-      // Replacing the old 'packages/bash/*' glob with this explicit list also
-      // newly INCLUDES packages/bash/bash (the pure seam package) on Windows.
-      'packages/bash/bash-local',
-      'packages/bash/bash-sandbox',
-      'packages/bash/tool-bash',
+      'packages/bash/*',
       'packages/hooks/*',
       'packages/subprocess/*',
       'packages/pty/pty-local',
@@ -44,20 +26,10 @@ const windowsCoverageExclusions = process.platform === 'win32'
       'packages/lsp/lsp-local/src/connection.ts',
       'packages/lsp/lsp-local/src/index.ts',
       'packages/lsp/lsp-local/src/instance.ts',
+      'packages/ui/tui/src/index.ts',
     ]
   : []
 
-// Mirrors windowsCoverageExclusions: pwsh-local's run/start/lifecycle suites
-// self-skip without a real pwsh (executor.spec.ts hasPwsh), leaving this file
-// far below per-file 100% on pwsh-less hosts; the exemption keeps those hosts
-// green while CI runners ship pwsh and still enforce the full bar. The probe
-// runs the suites' own resolution (the dependency-free resolve.ts module),
-// so the exemption is active exactly when the suites skip — a mismatched
-// narrower probe could exempt the file on hosts whose suites actually run.
-const pwshCoverageExclusions = spawnSync(resolvePwshPath(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$true'], { encoding: 'utf8' }).status === 0
-  ? []
-  : ['packages/bash/pwsh-local/src/index.ts']
-
 const testIncludes = [
   'packages/*/*/tests/**/*.spec.{ts,tsx}',
   'apps/*/tests/**/*.spec.ts',
@@ -65,17 +37,6 @@ const testIncludes = [
   'scripts/**/*.spec.ts',
 ]
 
-// The instrumented coverage gate sets this env; the exempt heavy suites then
-// run beside it uninstrumented (membership contract in scripts/coverage-exempt.ts).
-// A set-but-not-'1' value is a misconfiguration, not a silent no-op.
-const coverageExemptRaw = process.env[COVERAGE_EXEMPT_ENV]
-if (coverageExemptRaw !== undefined && coverageExemptRaw !== '' && coverageExemptRaw !== '1') {
-  throw new Error(`vitest config: ${COVERAGE_EXEMPT_ENV} must be '1' or unset, got ${JSON.stringify(coverageExemptRaw)}.`)
-}
-const coverageExemptExcludes = coverageExemptRaw === '1'
-  ? coverageExemptHeavySuites.map(suite => suite.exclude)
-  : []
-
 // These suites exercise process-global state, process APIs, or timing-sensitive process I/O
 // that worker threads cannot isolate reliably under aggregate gate contention.
 // Keep the narrow exception in forks while the rest of the inventory avoids per-file processes.
@@ -88,48 +49,39 @@ const processBoundTests = [
 ]
 
 export default defineConfig({
-  plugins: [pathsPlugin(), standardDecoratorPlugin()],
+  plugins: [pathsPlugin()],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
     include: testIncludes,
     exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
-    // One coverage invocation aggregates both projects. Regular suites fork on
-    // POSIX for Node stability and use threads on Windows; process-bound suites
-    // always fork.
+    // One coverage invocation aggregates both projects. Most suites use threads
+    // for lower startup/IPC overhead; only explicit process-bound suites fork.
     projects: [
       {
-        plugins: [pathsPlugin(), standardDecoratorPlugin()],
+        plugins: [pathsPlugin()],
         test: {
           name: 'thread-safe',
-          execArgv: vitestExecArgv,
-          // Node 24 has aborted in its CJS lexer (v8::ToLocalChecked Empty
-          // MaybeLocal in cjs_lexer::Parse) from worker threads on macOS
-          // arm64 and later on Linux. A fork contains that external runtime
-          // failure to the test process; Windows keeps the thread pool, where
-          // the abort has not reproduced and process spawn is costlier.
-          pool: process.platform === 'win32' ? 'threads' : 'forks',
+          // Node 24 has aborted in its CJS lexer from a macOS arm64 worker
+          // thread. A fork contains that external runtime failure to the test
+          // process; other hosts retain the lower-overhead thread pool.
+          pool: process.platform === 'darwin' ? 'forks' : 'threads',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: testIncludes,
           exclude: [
             ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
             ...processBoundTests,
-            ...coverageExemptExcludes,
           ],
         },
       },
       {
-        plugins: [pathsPlugin(), standardDecoratorPlugin()],
+        plugins: [pathsPlugin()],
         test: {
           name: 'process-bound',
-          execArgv: vitestExecArgv,
           pool: 'forks',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: processBoundTests,
-          exclude: [
-            ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
-            ...coverageExemptExcludes,
-          ],
+          exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
         },
       },
     ],
@@ -146,8 +98,7 @@ export default defineConfig({
         'packages/*/*/src/types.ts',
         'packages/*/*/src/bin.ts',
         'packages/*/*/src/worker.ts',
-        // A killed executable lint-contract test can leave a non-product source probe behind.
-        'packages/*/*/src/oxlint-contract-*.ts',
+        'packages/code-runtime/code-runtime-subprocess/src/runner.ts',
         // GUI step-1 skeleton (PR #500): client/web UI files whose remaining
         // branches need a browser-grade harness the jsdom lane doesn't cover
         // yet. TODO(gui): cover and remove as the client test lane matures.
@@ -156,7 +107,6 @@ export default defineConfig({
         'packages/client/ui-primitives/src/markdown/plain-text.ts',
         'packages/client/ui-question/src/client/QuestionComposer.tsx',
         'packages/client/ui-primitives/src/Menu.tsx',
-        'packages/client/ui-primitives/src/RiskConfirmation.tsx',
         'packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx',
         'packages/client/ui-workspace/src/client/WorkspacePicker.tsx',
         'packages/client/web-react/src/*',
@@ -181,10 +131,6 @@ export default defineConfig({
         'packages/client/hmr/src/invariant.ts',
         'packages/client/connection/src/index.ts',
         'packages/client/connection/src/http-bridge.ts',
-        // This assembly imports generated Host-for-Client code that exists
-        // only in lib; the post-build built-bin smoke executes both entries.
-        'packages/api/remotes/src/index.ts',
-        'packages/api/remotes/src/client/index.ts',
         // Slash/command/input round: per-file gaps deferred with the same
         // client-lane debt. TODO(gui): cover and remove with the lane above.
         'packages/client/connection/src/client/fixture.ts',
@@ -209,13 +155,9 @@ export default defineConfig({
         'packages/client/ui-sidebar/src/client/index.ts',
         'packages/client/ui-skill/src/client/index.ts',
         'packages/client/ui-workspace/src/client/index.ts',
-        'packages/client/test-runtime/src/translate.ts',
-        'packages/client/ui-primitives/src/JsonTree.tsx',
-        // Typert generator: correctness is pinned by its fixture suites and
-        // the byte-for-byte catalog reproduction test; per-file coverage
-        // would put whole-workspace compiler analysis under v8
-        // instrumentation — the coverage lane's longest tail.
-        'packages/typert/generator/src/*.ts',
+        'packages/typert/generator/src/analyzer.ts',
+        'packages/typert/generator/src/renderer.ts',
+        'packages/typert/generator/src/cordis-catalog.ts',
         'packages/host/apiproxy/src/index.ts',
         'packages/host/apiproxy/src/invariant.ts',
         'packages/host/apiproxy/src/api-proxy.ts',
@@ -225,9 +167,9 @@ export default defineConfig({
         'packages/ui/commands/src/index.ts',
         'packages/ui/commands/src/invariant.ts',
         'packages/session-projection/session-projection/src/index.ts',
+        'packages/ui/tui/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
-        ...pwshCoverageExclusions,
       ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.
@@ -240,9 +182,7 @@ export default defineConfig({
         functions: 100,
         lines: 100,
       },
-      reporter: process.env.CI
-        ? ['text', uncoveredLocationsReporter]
-        : ['text', 'html', uncoveredLocationsReporter],
+      reporter: process.env.CI ? ['text'] : ['text', 'html'],
     },
   },
 })

From e8409cf928a3f848f8c2e6a8ab85c32ecbd52de6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 02:27:12 +0800
Subject: [PATCH 082/262] fix(code-runtime): track generated runner source

---
 knip.json                                     |  1 +
 .../src/runner-source.generated.ts            |  2 +-
 packages/util/atomic-write/src/runner.ts      | 24 +++++++++++--------
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/knip.json b/knip.json
index 20bcb5ff2d..413b740578 100644
--- a/knip.json
+++ b/knip.json
@@ -385,6 +385,7 @@
     },
     "packages/code-runtime/code-runtime-subprocess": {
       "entry": [
+        "src/runner.ts",
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
       ],
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
index d40c77783c..8592fa2399 100644
--- a/packages/util/atomic-write/src/runner-source.generated.ts
+++ b/packages/util/atomic-write/src/runner-source.generated.ts
@@ -3,4 +3,4 @@
  * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
  */
 
-export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,me=Object.defineProperty,he=Object.getOwnPropertyDescriptor,T=Object.getPrototypeOf,ge=Object.hasOwn,E=Object.is,_e=Object.keys,D=Object.prototype,ve=Reflect.get(D,`propertyIsEnumerable`),O=Reflect.ownKeys,ye=Reflect.get(Set.prototype,`add`),be=Reflect.get(Set.prototype,`delete`),xe=Reflect.get(Set.prototype,`has`);function k(e){let t=pe(null);return t.value=e,t}function A(e,t,n){let r=k(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,me(e,t,r)}function j(e,t){A(e,e.length,t)}function M(e){if(e.length===0)return;let t=e.length-1,n=e[t];return me(e,`length`,k(t)),n}function N(e,t){return b(xe,e,[t])}function P(e,t){b(ye,e,[t])}function Se(e,t){b(be,e,[t])}function F(e,t){let n=he(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function I(e){return T(e)===null&&F(e,`Object`)}function L(e){let t=T(e);if(t===de)return!0;if(!C(t)||!F(t,`Array`))return!1;let n=T(t);return typeof n==`object`&&!!n&&I(n)}function R(e){let t=T(e);return t===null||t===D||typeof t==`object`&&I(t)}function z(e){let t=O(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ve,e,[r]))return}return t}function B(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?A(e.target,e.index,t):A(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=M(i);e!==void 0;e=M(i)){if(e.kind===`leave`){Se(t,e.source);continue}if(e.kind===`array-item`){if(!ge(e.source,e.index))return;j(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){j(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||E(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||N(t,n))return;if(C(n)){if(!L(n))return;let a=n.length;if(O(n).length!==a+1)return;let o=[];r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)j(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!R(n))return;let a=z(n);if(a===void 0)return;let o={};r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;j(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function V(e){let t=[],n=[e];for(let e=M(n);e!==void 0;e=M(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){j(t,e);continue}if(C(e)){j(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);j(n,r)}continue}let r=_e(e);j(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);j(n,a)}}return t}function H(e){if(!L(e)||O(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!ge(e,t))return!1;return!0}function U(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Ce(e){if(C(e)||!R(e))return;let t=z(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!U(t,`kind`)||!U(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!U(t,`kind`)||!U(t,`keys`))return;let e=n.keys;if(!C(e)||!H(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||N(r,t))return;P(r,t),j(i,t)}return{kind:`object`,keys:i}}}function W(e){try{if(!C(e)||!H(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)j(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;A(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||E(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Ce(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&j(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;M(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,we=Object.create,Te=Object.defineProperty;function K(e,t,n){let r=we(null);r.enumerable=!0,r.value=n,Te(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=B(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:V(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),K(this,`name`,e.name),K(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=W(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=B(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:V(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=W(e);return t===void 0?null:V(t)}function qe(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Je(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=qe(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}c||(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($()):t.type===`output-limit`?l({type:`output-limit`}):t.type===`done`&&(t.error===void 0?l({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):Ue(t.error)&&l({type:`done`,error:t.error})))}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ge(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=Ke(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Ye(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ge(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);t!==void 0&&(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($()):t.type===`log`&&typeof t.text==`string`?o({type:`log`,text:t.text})||s($()):t.type===`output-limit`?s({type:`output-limit`}):t.type===`done`&&(t.error===void 0?s({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):We(t.error)&&s({type:`done`,error:t.error})))}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=Ke(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Ye():Je();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
+export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,T=Object.defineProperty,me=Object.getOwnPropertyDescriptor,E=Object.getPrototypeOf,D=Object.hasOwn,O=Object.is,he=Object.keys,k=Object.prototype,ge=Reflect.get(k,`propertyIsEnumerable`),A=Reflect.ownKeys,_e=Reflect.get(Set.prototype,`add`),ve=Reflect.get(Set.prototype,`delete`),ye=Reflect.get(Set.prototype,`has`);function j(e){let t=pe(null);return t.value=e,t}function M(e,t,n){let r=j(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,T(e,t,r)}function N(e,t){M(e,e.length,t)}function P(e){if(e.length===0)return;let t=e.length-1,n=e[t];return T(e,`length`,j(t)),n}function F(e,t){return b(ye,e,[t])}function I(e,t){b(_e,e,[t])}function be(e,t){b(ve,e,[t])}function L(e,t){let n=me(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function R(e){return E(e)===null&&L(e,`Object`)}function z(e){let t=E(e);if(t===de)return!0;if(!C(t)||!L(t,`Array`))return!1;let n=E(t);return typeof n==`object`&&!!n&&R(n)}function B(e){let t=E(e);return t===null||t===k||typeof t==`object`&&R(t)}function V(e){let t=A(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ge,e,[r]))return}return t}function H(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?M(e.target,e.index,t):M(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=P(i);e!==void 0;e=P(i)){if(e.kind===`leave`){be(t,e.source);continue}if(e.kind===`array-item`){if(!D(e.source,e.index))return;N(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){N(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||O(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||F(t,n))return;if(C(n)){if(!z(n))return;let a=n.length;if(A(n).length!==a+1)return;let o=[];r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)N(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!B(n))return;let a=V(n);if(a===void 0)return;let o={};r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;N(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=P(n);e!==void 0;e=P(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){N(t,e);continue}if(C(e)){N(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);N(n,r)}continue}let r=he(e);N(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);N(n,a)}}return t}function xe(e){if(!z(e)||A(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!D(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Se(e){if(C(e)||!B(e))return;let t=V(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!C(e)||!xe(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||F(r,t))return;I(r,t),N(i,t)}return{kind:`object`,keys:i}}}function G(e){try{if(!C(e)||!xe(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)N(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;M(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||O(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Se(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&N(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;P(n)}}return n.length===0?r:void 0}catch{return}}const K=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new K(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof K?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends K{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new K(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=G(e.value);t===void 0?n.reject(new K(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new K(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof K?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new K(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=G(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}if(!c){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($());else if(t.type===`output-limit`)l({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,Ue);e!==void 0&&l(e)}}}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ke(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ke(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($());else if(t.type===`log`&&typeof t.text==`string`)o({type:`log`,text:t.text})||s($());else if(t.type===`output-limit`)s({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,We);e!==void 0&&s(e)}}}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=qe(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
index 7a0b3eb678..92fad6db2e 100644
--- a/packages/util/atomic-write/src/runner.ts
+++ b/packages/util/atomic-write/src/runner.ts
@@ -94,6 +94,16 @@ function validWorkerFailure(value: unknown): value is RuntimeFailure {
     && (value.kind === 'exception' || value.kind === 'invalid-output' || value.kind === 'output-limit')
 }
 
+function doneMessage(
+  message: Record<string, unknown>,
+  acceptsFailure: (value: unknown) => value is RuntimeFailure,
+): RuntimeMessage | undefined {
+  if (message.error !== undefined) {
+    return acceptsFailure(message.error) ? { type: 'done', error: message.error } : undefined
+  }
+  return { type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } }
+}
+
 function runtimeBoot(value: unknown): RuntimeBootData | undefined {
   const record = recordOf(value)
   if (record === undefined
@@ -214,11 +224,8 @@ function runLauncher(): void {
       } else if (message.type === 'output-limit') {
         finish({ type: 'output-limit' })
       } else if (message.type === 'done') {
-        if (message.error !== undefined) {
-          if (validFailure(message.error)) finish({ type: 'done', error: message.error })
-        } else {
-          finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
-        }
+        const done = doneMessage(message, validFailure)
+        if (done !== undefined) finish(done)
       }
     })
     current.on('error', (error: Error) => {
@@ -348,11 +355,8 @@ function runController(): void {
         } else if (message.type === 'output-limit') {
           finish({ type: 'output-limit' })
         } else if (message.type === 'done') {
-          if (message.error !== undefined) {
-            if (validWorkerFailure(message.error)) finish({ type: 'done', error: message.error })
-          } else {
-            finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
-          }
+          const done = doneMessage(message, validWorkerFailure)
+          if (done !== undefined) finish(done)
         }
       })
       current.on('error', (error: Error) => {

From 22fc228b9757626fbc0c3c9ab920ec9472b258ea Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 04:23:20 +0800
Subject: [PATCH 083/262] refactor(runtime): collapse unused setup layers

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 ++--
 ...7-28-portable-execution-world-consumers.md |  4 ++--
 ...8-portable-execution-world-consumers.zh.md |  4 ++--
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 ++--
 .../feature/2026-06-15-code-mode.md           |  6 ++---
 .../feature/2026-06-15-code-mode.zh.md        |  6 ++---
 docs/config-catalog.md                        |  4 ++--
 .../core-data-structures/subprocess.i18n.yaml |  4 ++--
 docs/core-data-structures/subprocess.md       |  2 +-
 docs/core-data-structures/subprocess.zh.md    |  2 +-
 packages/README.i18n.yaml                     |  4 ++--
 packages/README.md                            |  2 +-
 packages/README.zh.md                         |  2 +-
 packages/bash/pwsh-local/tsconfig.json        | 10 ++++----
 packages/code-runtime/code-runtime/README.md  |  4 ++--
 packages/pty/pty-local/tests/index.spec.ts    |  1 -
 .../subprocess-local/README.i18n.yaml         |  4 ++--
 .../subprocess/subprocess-local/README.md     |  4 ++--
 .../subprocess/subprocess-local/README.zh.md  | 24 +++++++++----------
 .../subprocess/subprocess-local/src/index.ts  | 14 ++++-------
 .../subprocess-local/tests/local.spec.ts      | 19 ++-------------
 .../subprocess/subprocess/README.i18n.yaml    |  4 ++--
 packages/subprocess/subprocess/README.md      |  4 ++--
 packages/subprocess/subprocess/README.zh.md   |  4 ++--
 packages/subprocess/subprocess/src/index.ts   |  7 ++----
 .../subprocess/tests/service.spec.ts          |  1 -
 packages/ui/app-boot/tsdown.config.ts         |  8 +------
 packages/util/atomic-write/README.i18n.yaml   |  6 ++---
 .../src/runner-source.generated.ts            |  2 +-
 packages/util/atomic-write/src/runner.ts      | 17 +++++++++----
 30 files changed, 78 insertions(+), 103 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 683a095229..3fce989f78 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 03b274688e15661845c326afdd105b342dd6a513
-2026-07-28-portable-execution-world-consumers.zh.md: 1e3d8ae8e46d26f4bea47293104c52dbf33098d4
+2026-07-28-portable-execution-world-consumers.md: 74fa2687782a2cf59be8dddf98fa4a08a953d565
+2026-07-28-portable-execution-world-consumers.zh.md: 35d4f3640a44564894fecfaa22c7255d7452dec9
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 03b274688e..74fa268778 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -23,7 +23,7 @@ Generic consumers use that execution world:
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-code-runtime-subprocess` passes a bundled dependency-free eval runner directly to `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote process worlds without a filesystem dependency or provider-specific package. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -39,7 +39,7 @@ Generic consumers use that execution world:
 
 **Add a stable bounded-read primitive to the filesystem seam.** Rejected because only LSP needs a complete-document byte ceiling, which it can enforce while consuming the existing text stream. A second primitive forces every provider to implement stable-handle and no-follow mechanics, including a remote helper protocol, without an observed concurrent-replacement defect.
 
-**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable and filesystem materialization; the worker backend has neither requirement and remains the supported single-process path.
+**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable; the worker backend does not and remains the supported single-process path.
 
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 1e3d8ae8e4..35d4f3640a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-code-runtime-subprocess` 将一个内置的无依赖 eval runner 直接传给 `ctx.subprocess`，从而在本地或远程进程执行环境中保留代码运行时的绑定与输出契约，且不依赖文件系统或提供方专用包。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -39,7 +39,7 @@ Status: implemented
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
+**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件，而 worker 后端不需要，并且仍是受支持的单进程路径。
 
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 112e4eed83..d2655b6d02 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 1be25f5b145e50d8fe391d22910b71d85181582e
-2026-06-15-code-mode.zh.md: a4e8fbbd339899937c4f39091b4befbbb78ec347
+2026-06-15-code-mode.md: a075ea66c150afb1b48f98c600b72eec57869962
+2026-06-15-code-mode.zh.md: c269c0a8709087e7b1e27051cbda3924f8dd9109
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 1be25f5b14..a075ea66c1 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -20,7 +20,7 @@ Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
 2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
-3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` materializes a runner through `ctx.fs` and launches it through `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
+3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` passes a bundled eval runner to `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
 
@@ -79,7 +79,7 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across another process world. It passes a dependency-free eval runner directly through the subprocess provider and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
 
 ### Trust posture
 
@@ -95,7 +95,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
+- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index a4e8fbbd33..c269c0a870 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -20,7 +20,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
 2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
-3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 在另一执行环境中启动。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
+3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则将一个内置的 eval runner 传给 `ctx.subprocess`，用于另一执行环境。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
 
@@ -79,7 +79,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
+`@deepseek-ai/dsh-code-runtime-subprocess` 在另一进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它通过子进程提供方直接传递一个无依赖的 eval runner，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
@@ -95,7 +95,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 测试
 
-- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
+- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 0514cdd969..a875c190fe 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -286,7 +286,7 @@ Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index
 
 ## `@deepseek-ai/dsh-code-runtime-subprocess`
 
-Requires: `fs` · `subprocess`
+Requires: `subprocess`
 
 ```ts config-catalog
 /** Runtime configuration; every execution and bridge bound is deployment-tunable. */
@@ -306,7 +306,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:28`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:27`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
 
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index f3b308b0be..f6c61bd691 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 95e9454a75112cf98e1ed583f970c50fe90aac37
-subprocess.zh.md: 58127d662fa599d19f632449d42b8aa3259886d6
+subprocess.md: f0fe691219df3afba2b836da8f1594fd5fe5a87b
+subprocess.zh.md: f59e787820ba2727fdc0c4b62c4aec7b8d2d6b7a
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 935a7d60ac..89f30095bc 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -8,7 +8,7 @@ Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subproces
 
 ## Execution-world coordinates
 
-One provider's `cwd`, `runtimeRoot`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides. Consumers use `runtimeRoot` for private materialized helpers and never assume a host path exists in that world.
+One provider's `cwd`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides.
 
 ## Managed environment namespace and captured output
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 58127d662f..f59e787820 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -8,7 +8,7 @@
 
 ## 执行世界坐标
 
-一个提供方的 `cwd`、`runtimeRoot`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。消费方使用 `runtimeRoot` 存放私有物化辅助程序，绝不假设该执行世界中存在某条宿主路径。
+一个提供方的 `cwd`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
 
 ## 受管环境命名空间与捕获的输出
 
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index c5be7e67d6..eaa48fac05 100644
--- 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: 7fcd98bd19ca3291f0472af57841f2f763bb346f
-README.zh.md: 7c4aed9b343ec57001883e094ea3dd0d73e2a920
+README.md: b498c146202f1a69d89805fa3e8966c4d0735d6c
+README.zh.md: 2eefc73ed0ea22aae5fde93284c25c5d03fe86c4
diff --git a/packages/README.md b/packages/README.md
index a711e4d303..7d591605ef 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -19,7 +19,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and filesystem/subprocess backends | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and subprocess backends | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 41380317f8..a9201d08a9 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及文件系统／进程管理后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及进程管理后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
diff --git a/packages/bash/pwsh-local/tsconfig.json b/packages/bash/pwsh-local/tsconfig.json
index 53ccc94926..7381575674 100644
--- a/packages/bash/pwsh-local/tsconfig.json
+++ b/packages/bash/pwsh-local/tsconfig.json
@@ -18,19 +18,19 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../../util/brand"
+      "path": "../code-runtime"
     },
     {
-      "path": "../../util/timeout"
-    },
-    {
-      "path": "../../bash/bash"
+      "path": "../code-runtime-worker"
     },
     {
       "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/timeout"
     }
   ]
 }
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 7014bf517a..d58508cd08 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the filesystem/subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
-- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the filesystem/subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
+- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
+- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index f59cd3ab5a..15e73ddc1c 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -67,7 +67,6 @@ function terminalHandle(): SubprocessTerminalHandle {
 
 class StubSubprocessService extends SubprocessService {
   readonly cwd = '/tmp'
-  readonly runtimeRoot = '/tmp/dsh-runtime'
   async resolveExecutable(command: string): Promise<string> { return command }
   spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
   async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index d34e7475f9..8b668b43f6 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 31c5539750c4af2b1c4169ac1dce4c91da587af7
-README.zh.md: 74aed52084c0db3ed9bfe4fcb991f781976fb7b5
+README.md: 4892ad49e571662b833b1dd6d64dc966f343ae3c
+README.zh.md: ca0df5ff18e9feb992cc3f6d0db90dc06cb275d8
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 31c5539750..13b51ec6d1 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` owns a private runtime directory, resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
+Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
 
 ## Behavior (and where it came from)
 
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Execution-world coordinates** — `cwd` is the host process cwd, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 74aed52084..ca0df5ff18 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,17 +2,17 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 拥有私有运行时目录，解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 与平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md)和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md) 和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
 
 ## 行为（以及设计来源）
 
-- **带平台正确信号发送的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止动词）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
-- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
-- **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，并公开一项须等待的终止操作，该操作会在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
-- **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
+- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
+- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
+- **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
+- **执行世界坐标**：`cwd` 是宿主进程 cwd，`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
+- **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
@@ -20,14 +20,14 @@
 
 #### KV Cache 影响
 
-不会直接失效；请求前缀变更由具名消费方负责。
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
 
 ## 已知限制与暂缓事项
 
 - **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
-- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 使用 `ps` 快照。
-- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程若在任何前台检查快照产生前重新设定父进程，便无法再从 `node-pty` 根发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与该提供方拥有的终端会话。本地提供方不会增加持续运行的进程表监视器。
-- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
+- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 则使用 `ps` 快照。
+- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 `node-pty` 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话。本地提供方不会新增持续进程表监视器。
+- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
 原始进程处理位于 `src/spawn.ts`；`src/index.ts` 负责服务接线。
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 46d179a7b2..262a2567b8 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -8,10 +8,8 @@
  */
 
 import { constants } from 'node:fs'
-import { mkdtempSync } from 'node:fs'
-import { access, rm, stat } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { delimiter, extname, isAbsolute, join, resolve } from 'node:path'
+import { access, stat } from 'node:fs/promises'
+import { delimiter, extname, isAbsolute, resolve } from 'node:path'
 import { Context } from 'cordis'
 import * as nodePty from 'node-pty'
 import type { IPtyForkOptions } from 'node-pty'
@@ -36,7 +34,6 @@ import { LocalTerminalHandle } from './terminal.ts'
  */
 export class LocalSubprocessService extends SubprocessService {
   readonly cwd = process.cwd()
-  readonly runtimeRoot = mkdtempSync(join(tmpdir(), 'dsh-subprocess-runtime-'))
   /** Live handles retained only so disposal can terminate and join them. */
   private live = new Set<SubprocessHandle>()
   /** Live terminal sessions retained through whole-session quiescence. */
@@ -63,10 +60,7 @@ export class LocalSubprocessService extends SubprocessService {
       }
       this.live.clear()
       this.terminals.clear()
-      const outcomes = [
-        ...await Promise.allSettled(pending),
-        ...await Promise.allSettled([rm(this.runtimeRoot, { recursive: true, force: true })]),
-      ]
+      const outcomes = await Promise.allSettled(pending)
       const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
         ? [outcome.reason as unknown]
         : [])
@@ -126,7 +120,7 @@ export class LocalSubprocessService extends SubprocessService {
   }
 
   // Local PTY allocation is synchronous, but the provider seam permits remote asynchronous allocation.
-  // eslint-disable-next-line @typescript-eslint/require-await
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
     const file = spec.argv[0]
     if (file === undefined || file.length === 0) {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index ff83141fab..e74927448d 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,6 +1,5 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
-import { stat } from 'node:fs/promises'
 import { basename, dirname, relative, resolve } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -22,16 +21,6 @@ function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): Su
 }
 
 describe('LocalSubprocessService', () => {
-  it('publishes execution-world paths and removes its private runtime directory', async () => {
-    const ctx = new Context()
-    const fiber = await ctx.plugin(LocalSubprocessService)
-    const root = ctx.subprocess.runtimeRoot
-    expect(ctx.subprocess.cwd).toBe(process.cwd())
-    expect((await stat(root)).isDirectory()).toBe(true)
-    await fiber.dispose()
-    await expect(stat(root)).rejects.toMatchObject({ code: 'ENOENT' })
-  })
-
   it('resolves absolute and PATH executables and honors lookup cancellation', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
@@ -113,11 +102,10 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('waits for every terminal cleanup and clears single-shot teardown ownership', async () => {
+  it('waits for every terminal cleanup and aggregates teardown failures', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
-    const runtimeRoot = service.runtimeRoot
     const firstFailure = new Error('first cleanup failure')
     const secondFailure = new Error('second cleanup failure')
     const disposalErrors: unknown[] = []
@@ -155,7 +143,6 @@ describe('LocalSubprocessService', () => {
     finishCleanup()
     await disposing
     expect(terminals.size).toBe(0)
-    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
     expect(disposalErrors).toHaveLength(1)
     expect(disposalErrors[0]).toMatchObject({
       errors: [firstFailure, secondFailure],
@@ -163,14 +150,13 @@ describe('LocalSubprocessService', () => {
     })
   })
 
-  it('reports one cleanup failure without wrapping it after removing runtime state', async () => {
+  it('reports one cleanup failure without wrapping it', async () => {
     const ctx = new Context()
     const failure = new Error('single cleanup failure')
     const disposalErrors: unknown[] = []
     ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
-    const runtimeRoot = service.runtimeRoot
     const terminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
@@ -185,7 +171,6 @@ describe('LocalSubprocessService', () => {
 
     await fiber.dispose()
 
-    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
     expect(disposalErrors).toEqual([failure])
   })
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 92887cc247..d12516f11f 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 12a88a86c3cd7bcde2858bdbd874c99533100e09
-README.zh.md: f4c265a0f55c4e35e4557516593dd0da236164c5
+README.md: 08fb03d6f145c1026180d92de2421b647cb3ebbe
+README.zh.md: 592fc83223092b3406e9070e11de2b20a63232a6
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 12a88a86c3..08fb03d6f1 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -2,12 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, private `runtimeRoot`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
+The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
 
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- `cwd` and `runtimeRoot` are absolute paths in the provider's execution world. Consumers materialize private helpers below `runtimeRoot`, never in a host-only temp directory. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
+- `cwd` and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index f4c265a0f5..592fc83223 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,12 +2,12 @@
 
 [English](README.md) | 中文
 
-子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- `cwd` 和 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 之下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- `cwd` 和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index e1749203dd..df3186c9b0 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -78,8 +78,8 @@ declare module 'cordis' {
  * duplicate-service behavior).
  *
  * Implementations must honor these semantics:
- * - {@link cwd}, {@link runtimeRoot}, and executable paths belong to one
- *   execution world shared with the mounted filesystem provider.
+ * - {@link cwd} and executable paths belong to one execution world shared
+ *   with the mounted filesystem provider.
  * - {@link spawn} returns immediately with a live handle; `done` resolves at
  *   process close with exit facts and rejects only for spawn-level failures.
  * - Collect-mode readers are offset-based and non-consuming, so independent
@@ -107,9 +107,6 @@ export abstract class SubprocessService extends Service {
   /** Canonical default cwd in this provider's execution world. */
   abstract readonly cwd: string
 
-  /** Private directory for runtime artifacts in this provider's execution world. */
-  abstract readonly runtimeRoot: string
-
   /**
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index 9f321caf54..2084310da9 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -17,7 +17,6 @@ import type {
  */
 class StubSubprocessService extends SubprocessService {
   readonly cwd = '/stub'
-  readonly runtimeRoot = '/stub/.runtime'
 
   async resolveExecutable(command: string): Promise<string> {
     return `/bin/${command}`
diff --git a/packages/ui/app-boot/tsdown.config.ts b/packages/ui/app-boot/tsdown.config.ts
index 88492d7c26..33db6be1b8 100644
--- a/packages/ui/app-boot/tsdown.config.ts
+++ b/packages/ui/app-boot/tsdown.config.ts
@@ -1,9 +1,6 @@
 import { defineConfig } from 'tsdown'
 
-/**
- * Embed Include while keeping Loader external so the built include tree and
- * app host bind to one Loader peer.
- */
+/** Bundle the host plugin and its dependency-free eval runner. */
 export default defineConfig({
   entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
@@ -13,7 +10,4 @@ export default defineConfig({
   fixedExtension: false,
   dts: false,
   clean: false,
-  deps: {
-    alwaysBundle: ['@cordisjs/plugin-include'],
-  },
 })
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index 33e1f6014b..efcd06f845 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.i18n.yaml
@@ -1,6 +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/util/atomic-write/README.md
-README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
-README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
+#   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-subprocess/README.md
+README.md: 897112a32fa3e776df756d4caaba97b617c6af9e
+README.zh.md: d9ab3713640fe955d2b36a8f0674f77686e4791b
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
index 8592fa2399..95da563dbb 100644
--- a/packages/util/atomic-write/src/runner-source.generated.ts
+++ b/packages/util/atomic-write/src/runner-source.generated.ts
@@ -3,4 +3,4 @@
  * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
  */
 
-export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,T=Object.defineProperty,me=Object.getOwnPropertyDescriptor,E=Object.getPrototypeOf,D=Object.hasOwn,O=Object.is,he=Object.keys,k=Object.prototype,ge=Reflect.get(k,`propertyIsEnumerable`),A=Reflect.ownKeys,_e=Reflect.get(Set.prototype,`add`),ve=Reflect.get(Set.prototype,`delete`),ye=Reflect.get(Set.prototype,`has`);function j(e){let t=pe(null);return t.value=e,t}function M(e,t,n){let r=j(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,T(e,t,r)}function N(e,t){M(e,e.length,t)}function P(e){if(e.length===0)return;let t=e.length-1,n=e[t];return T(e,`length`,j(t)),n}function F(e,t){return b(ye,e,[t])}function I(e,t){b(_e,e,[t])}function be(e,t){b(ve,e,[t])}function L(e,t){let n=me(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function R(e){return E(e)===null&&L(e,`Object`)}function z(e){let t=E(e);if(t===de)return!0;if(!C(t)||!L(t,`Array`))return!1;let n=E(t);return typeof n==`object`&&!!n&&R(n)}function B(e){let t=E(e);return t===null||t===k||typeof t==`object`&&R(t)}function V(e){let t=A(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ge,e,[r]))return}return t}function H(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?M(e.target,e.index,t):M(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=P(i);e!==void 0;e=P(i)){if(e.kind===`leave`){be(t,e.source);continue}if(e.kind===`array-item`){if(!D(e.source,e.index))return;N(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){N(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||O(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||F(t,n))return;if(C(n)){if(!z(n))return;let a=n.length;if(A(n).length!==a+1)return;let o=[];r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)N(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!B(n))return;let a=V(n);if(a===void 0)return;let o={};r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;N(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=P(n);e!==void 0;e=P(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){N(t,e);continue}if(C(e)){N(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);N(n,r)}continue}let r=he(e);N(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);N(n,a)}}return t}function xe(e){if(!z(e)||A(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!D(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Se(e){if(C(e)||!B(e))return;let t=V(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!C(e)||!xe(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||F(r,t))return;I(r,t),N(i,t)}return{kind:`object`,keys:i}}}function G(e){try{if(!C(e)||!xe(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)N(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;M(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||O(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Se(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&N(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;P(n)}}return n.length===0?r:void 0}catch{return}}const K=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new K(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof K?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends K{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new K(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=G(e.value);t===void 0?n.reject(new K(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new K(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof K?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new K(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=G(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}if(!c){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($());else if(t.type===`output-limit`)l({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,Ue);e!==void 0&&l(e)}}}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ke(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ke(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($());else if(t.type===`log`&&typeof t.text==`string`)o({type:`log`,text:t.text})||s($());else if(t.type===`output-limit`)s({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,We);e!==void 0&&s(e)}}}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=qe(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
+export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{spawn as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{Worker as i,isMainThread as a,parentPort as o,workerData as s}from\"node:worker_threads\";const c=Reflect.apply,l=Array.isArray,u=Buffer,d=Reflect.get(Buffer,`byteLength`),f=Object.create,p=Object.defineProperty,ee=Object.keys,te=String,ne=Reflect.get(String.prototype,`charCodeAt`),re=Reflect.get(String.prototype,`codePointAt`),ie=Reflect.get(String.prototype,`slice`);function m(e){let t=f(null);return t.value=e,t}function ae(e,t,n){let r=m(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function h(e){return c(d,u,[e,`utf8`])}function g(e,t){ae(e,e.length,t)}function _(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,m(t)),n}function v(e,t){return c(ie,e,[t,t+(c(re,e,[t])>65535?2:1)])}function y(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=c(ne,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:h(e)}function b(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=v(e,r);if(n+=y(i),n>t)return;r+=i.length}return n}function x(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=_(i);e!==void 0;e=_(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=b(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(h(te(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(l(a)){if(!r(2))return;a.length>0&&g(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=ee(a);e.length>0&&g(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=b(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:s})}return n}function oe(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=v(e,i),o=y(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:c(ie,e,[0,r])}const se=Reflect.get(Function.prototype,`toString`),S=Reflect.get(Reflect,`apply`),C=Error,ce=Set,w=Array.isArray,le=Array.prototype,T=Number.isFinite,ue=Number.isSafeInteger,de=Object.create,E=Object.defineProperty,fe=Object.getOwnPropertyDescriptor,D=Object.getPrototypeOf,O=Object.hasOwn,k=Object.is,pe=Object.keys,A=Object.prototype,me=Reflect.get(A,`propertyIsEnumerable`),j=Reflect.ownKeys,he=Reflect.get(Set.prototype,`add`),ge=Reflect.get(Set.prototype,`delete`),_e=Reflect.get(Set.prototype,`has`);function M(e){let t=de(null);return t.value=e,t}function N(e,t,n){let r=M(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,E(e,t,r)}function P(e,t){N(e,e.length,t)}function F(e){if(e.length===0)return;let t=e.length-1,n=e[t];return E(e,`length`,M(t)),n}function I(e,t){return S(_e,e,[t])}function L(e,t){S(he,e,[t])}function ve(e,t){S(ge,e,[t])}function R(e,t){let n=fe(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&S(se,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function z(e){return D(e)===null&&R(e,`Object`)}function B(e){let t=D(e);if(t===le)return!0;if(!w(t)||!R(t,`Array`))return!1;let n=D(t);return typeof n==`object`&&!!n&&z(n)}function V(e){let t=D(e);return t===null||t===A||typeof t==`object`&&z(t)}function ye(e){let t=j(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!S(me,e,[r]))return}return t}function H(e){let t=new ce,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?N(e.target,e.index,t):N(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=F(i);e!==void 0;e=F(i)){if(e.kind===`leave`){ve(t,e.source);continue}if(e.kind===`array-item`){if(!O(e.source,e.index))return;P(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){P(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!T(n)||k(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||I(t,n))return;if(w(n)){if(!B(n))return;let a=n.length;if(j(n).length!==a+1)return;let o=[];r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)P(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!V(n))return;let a=ye(n);if(a===void 0)return;let o={};r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;P(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=F(n);e!==void 0;e=F(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){P(t,e);continue}if(w(e)){P(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new C(`cannot encode a sparse JSON array`);P(n,r)}continue}let r=pe(e);P(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new C(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new C(`cannot encode an undefined JSON object property`);P(n,a)}}return t}function be(e){if(!B(e)||j(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!O(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function xe(e){if(w(e)||!V(e))return;let t=ye(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&ue(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!w(e)||!be(e))return;let r=new ce,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||I(r,t))return;L(r,t),P(i,t)}return{kind:`object`,keys:i}}}function Se(e){try{if(!w(e)||!be(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)P(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;N(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!T(r)||k(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=xe(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&P(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;F(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=b(e,n);if(r===void 0){this.truncated=!0;let r=oe(e,n);if(r.length>0){let e=b(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):x(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return b(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function K(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=Se(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(K(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&x(l,a)===void 0?Promise.reject(K(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(K(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(K(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&x(f,r)===void 0?{type:`output-limit`}:f)}function q(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let J=0;function Ve(){let e=process.execArgv.indexOf(`--eval`);if(e<0)throw Error(`code runtime runner requires its eval source`);let t=process.execArgv[e+1];if(t===void 0)throw Error(`code runtime runner requires its eval source`);return t}function Y(e){return typeof e==`object`&&e?e:void 0}function X(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function He(e){process.stdout.write(e),process.stdout.write(`\n`)}function Ue(e){let t=X(e,J);return t===void 0?!1:(He(t),!0)}function We(e){let t=Y(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function Ge(e){return We(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ke(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Z(e){let t=Y(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=Y(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=Se(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,i=0,a=2,o=0,s=!1,c=t=>{if(s)return;let n=X(t,J)??X($(),J);s=!0,n!==void 0&&He(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},l=e=>{if(s)return;let t=+(o>0),n=b(e,i-a-t);if(n===void 0){c({type:`output-limit`});return}a+=n+t,o+=1,Ue({type:`log`,text:e})||c($())},u=e=>{i=e.maxOutputBytes,J=e.maxFrameBytes,r=t(process.execPath,process.execArgv,{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{l(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{l(e.toString(`utf8`))}),n.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){l(t.text);return}if(!s){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)Ue({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,We);e!==void 0&&c(e)}}}}),n.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{s||c({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Z(t);if(e===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}u(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!s&&c({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let t,n=!1,a,o=0,s=e=>process.send===void 0||o>0&&X(e,o)===void 0?!1:(process.send(e),!0),c=e=>{if(n)return;n=!0,clearInterval(a);let r=o>0&&X(e,o)===void 0?$():e,i=t;t=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr);await Promise.all([i.terminate(),e,t])})).catch(e=>{s({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(r,()=>{process.connected&&process.disconnect()})})};process.on(`message`,l=>{if(t===void 0){let u=Z(l);if(u===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}o=u.maxFrameBytes,t=new i(new URL(`data:text/javascript;base64,${e.from(Ve()).toString(`base64`)}`),{workerData:u,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:u.maxOldGenerationSizeMb}});let d=t;d.stdout.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.stderr.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)s({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`log`&&typeof t.text==`string`)s({type:`log`,text:t.text})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,Ge);e!==void 0&&c(e)}}}),d.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),d.on(`exit`,e=>{n||c({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),a=setInterval(()=>{t!==void 0&&t.performance.eventLoopUtilization().active>u.computeMs&&c({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${u.computeMs}ms busy)`}})},25);return}let u=qe(l);u!==void 0&&t.postMessage(u)}),process.on(`disconnect`,()=>{t!==void 0&&!n&&t.terminate()})}if(a)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(o===null)throw Error(`remote worker requires parentPort`);let e=s;ze(o,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
index 92fad6db2e..2655d22026 100644
--- a/packages/util/atomic-write/src/runner.ts
+++ b/packages/util/atomic-write/src/runner.ts
@@ -1,12 +1,11 @@
 /** Typed source for the dependency-free execution-world runner bundle. */
 
 import { Buffer } from 'node:buffer'
-import { fork } from 'node:child_process'
+import { spawn } from 'node:child_process'
 import type { ChildProcess } from 'node:child_process'
 import { createInterface } from 'node:readline'
 import type { Readable } from 'node:stream'
 import { inspect } from 'node:util'
-import { fileURLToPath } from 'node:url'
 import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
 import {
   decodeWorkerJson,
@@ -56,6 +55,14 @@ const failureKinds = new Set<FailureKind>([
 
 let maxFrameBytes = 0
 
+function runnerSource(): string {
+  const evalIndex = process.execArgv.indexOf('--eval')
+  if (evalIndex < 0) throw new Error('code runtime runner requires its eval source')
+  const source = process.execArgv[evalIndex + 1]
+  if (source === undefined) throw new Error('code runtime runner requires its eval source')
+  return source
+}
+
 function recordOf(value: unknown): Record<string, unknown> | undefined {
   return typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
 }
@@ -197,10 +204,9 @@ function runLauncher(): void {
   const startController = (boot: RuntimeBootData): void => {
     maxOutputBytes = boot.maxOutputBytes
     maxFrameBytes = boot.maxFrameBytes
-    controller = fork(fileURLToPath(import.meta.url), [], {
+    controller = spawn(process.execPath, process.execArgv, {
       env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
       detached: false,
-      execArgv: [],
       stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
     }) as Controller
     const current = controller
@@ -325,7 +331,8 @@ function runController(): void {
         return
       }
       controllerMaxFrameBytes = boot.maxFrameBytes
-      worker = new Worker(new URL(import.meta.url), {
+      const sourceUrl = new URL(`data:text/javascript;base64,${Buffer.from(runnerSource()).toString('base64')}`)
+      worker = new Worker(sourceUrl, {
         workerData: boot,
         env: {},
         execArgv: [],

From 87b2c5d93f44bd52bfd52b536251e98ae7c274d2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 05:04:01 +0800
Subject: [PATCH 084/262] docs(runtime): remove stale runtime storage claims

---
 .../architecture/2026-07-26-subprocess-seam.i18n.yaml         | 4 ++--
 .../implemented/architecture/2026-07-26-subprocess-seam.md    | 4 ++--
 .../implemented/architecture/2026-07-26-subprocess-seam.zh.md | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.i18n.yaml   | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.md          | 2 +-
 .../2026-07-28-portable-execution-world-consumers.zh.md       | 2 +-
 docs/core-data-structures/subprocess.i18n.yaml                | 4 ++--
 docs/core-data-structures/subprocess.md                       | 2 +-
 docs/core-data-structures/subprocess.zh.md                    | 2 +-
 packages/subprocess/README.i18n.yaml                          | 4 ++--
 packages/subprocess/README.md                                 | 4 ++--
 packages/subprocess/README.zh.md                              | 4 ++--
 12 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 0b62184128..fde94ee5cf 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 359977ac6a50394405163bc060f3a39eb68891fb
-2026-07-26-subprocess-seam.zh.md: 551fcc8f4df82d0c893d8e6f5423f172dfd5d9c5
+2026-07-26-subprocess-seam.md: 214a46959c48862176e3c790d541def3444e31ad
+2026-07-26-subprocess-seam.zh.md: 13ba397458a041ec358828bab53e75516fd3e76d
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 359977ac6a..214a46959c 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 551fcc8f4d..13ba397458 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 3fce989f78..62592b5be0 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 74fa2687782a2cf59be8dddf98fa4a08a953d565
-2026-07-28-portable-execution-world-consumers.zh.md: 35d4f3640a44564894fecfaa22c7255d7452dec9
+2026-07-28-portable-execution-world-consumers.md: 97c8bcfc7bf84db4b6a2862fcc9d991ee7f4a7f6
+2026-07-28-portable-execution-world-consumers.zh.md: 025393f9e5ae99feba41fa8badeef8276151ba6f
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 74fa268778..97c8bcfc7b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -16,7 +16,7 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 35d4f3640a..025393f9e5 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index f6c61bd691..cfa3762222 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: f0fe691219df3afba2b836da8f1594fd5fe5a87b
-subprocess.zh.md: f59e787820ba2727fdc0c4b62c4aec7b8d2d6b7a
+subprocess.md: c68a2f77059f62b273c536987b321017f2a71bbb
+subprocess.zh.md: 061c681430ba1f011b4ed9e5c4d9fc8595fe6738
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 89f30095bc..a258ff4767 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -246,4 +246,4 @@ The terminal spec fully specifies argv, cwd, environment overrides, dimensions,
 
 ## Service behavior
 
-The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with temporary runtime storage, detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
+The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index f59e787820..061c681430 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -246,4 +246,4 @@ interface SubprocessOutcome {
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以临时运行时存储、detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index f6de20e259..af424b8809 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: b4aaf78454a51af4d3f7ea9f1aef450fde8d729d
-README.zh.md: c5013ce19bacb582b6c8c93e0ea0a73ec776ee57
+README.md: 5ea1ae3681f9340cfba798e659f454d6d05fdbfe
+README.zh.md: 4e1cb9472d6e90062ecde61db4200a79a56b16f1
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index b4aaf78454..5ea1ae3681 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: canonical cwd, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: execution-world coordinates and executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, runtime storage, and terminate-and-join disposal |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index c5013ce19b..4e1cb9472d 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：规范化 cwd、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
 | [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送、运行时存储，以及先终止再等待退出的资源释放 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。

From c1d08edd8324092c4981baee3bd030fbc2cd740b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 05:19:53 +0800
Subject: [PATCH 085/262] refactor(runtime): remove duplicate terminal
 ownership state

---
 packages/pty/pty-local/src/session.ts            | 16 ++++++----------
 .../subprocess/subprocess-local/src/terminal.ts  |  5 ++---
 .../subprocess-local/tests/terminal.spec.ts      |  1 +
 3 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index ebd7e076cf..faea1ef84d 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -167,7 +167,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private interrupting: LocalSendOperation | undefined
-  private activeWrite: { operation: LocalSendOperation; settled: Promise<boolean> } | undefined
+  private activeWrite: Promise<boolean> | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
   private promptSeen = false
@@ -238,7 +238,7 @@ export class LocalPtySession implements PtyBackendSession {
     }
     this.activeDeadlineTimer = setTimeout(() => {
       if (this.active === operation) {
-        this.settleActive('timeout', this.activeWrite?.operation === operation || this.interrupting === operation)
+        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
       }
     }, this.config.timeoutMs)
     void this.beginSend(operation, request)
@@ -254,11 +254,7 @@ export class LocalPtySession implements PtyBackendSession {
       if (input.length > 0 && !operation.cancelRequested) {
         this.resetReadinessEvidence()
         const write = this.terminal.write(input)
-        const activeWrite = {
-          operation,
-          settled: write.then(() => true, () => false),
-        }
-        this.activeWrite = activeWrite
+        this.activeWrite = write.then(() => true, () => false)
         try {
           await write
         } finally {
@@ -272,7 +268,7 @@ export class LocalPtySession implements PtyBackendSession {
         return
       }
       // Closing can race the awaited provider write even though static analysis sees only local assignments.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
       if (this.active === operation && !this.closing) {
         this.pollingReady = operation
         this.schedulePoll(operation)
@@ -448,7 +444,7 @@ export class LocalPtySession implements PtyBackendSession {
       this.polling = false
       const active = this.active
       // Awaited provider inspection can clear or replace the active send despite static analysis.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
       if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
     }
   }
@@ -506,7 +502,7 @@ export class LocalPtySession implements PtyBackendSession {
   private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
       const activeWrite = this.activeWrite
-      if (activeWrite?.operation === operation && !await activeWrite.settled) return
+      if (activeWrite !== undefined && !await activeWrite) return
       await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
       if (this.active === operation && !this.closing) this.onTransportFailure(error)
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 93b7a8fc2e..53c531675f 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -58,19 +58,18 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
         exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
         signal: signalName(exitSignal),
       })
-      void this.terminate().catch(() => {})
     })
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
-  // eslint-disable-next-line @typescript-eslint/require-await
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
   async write(data: string): Promise<void> {
     if (this.exited) throw new Error('terminal process has exited')
     this.terminal.write(data)
   }
 
   // Local inspection is synchronous; the seam returns a promise for remote transports.
-  // eslint-disable-next-line @typescript-eslint/require-await
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
     this.descendants()
     const processGroupId = this.inspector.foregroundPgid(this.pid)
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 2eeb7c6a27..8a6270883f 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -128,6 +128,7 @@ describe('LocalTerminalHandle', () => {
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
 
     const quiescent = handle.terminate()
+    expect(handle.terminate()).toBe(quiescent)
     await vi.advanceTimersByTimeAsync(20)
     expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
     expect(pty.kills).toEqual([])

From 4d5345794d73e51d09620cce859303d642a76bf1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:24:47 +0800
Subject: [PATCH 086/262] refactor(code-runtime): remove subprocess backend

---
 .../2026-07-26-subprocess-seam.i18n.yaml      |   4 +-
 .../2026-07-26-subprocess-seam.md             |  10 +-
 .../2026-07-26-subprocess-seam.zh.md          |  10 +-
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |  13 +-
 ...8-portable-execution-world-consumers.zh.md |  14 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |  14 +-
 .../feature/2026-06-15-code-mode.zh.md        |  14 +-
 docs/capability-seams.md                      |  79 +-
 docs/config-catalog.md                        |  26 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.md       |   6 +-
 docs/core-data-structures/subprocess.zh.md    |   6 +-
 knip.json                                     |  11 -
 package.json                                  |   2 -
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   2 +-
 packages/README.zh.md                         |   2 +-
 .../code-runtime-worker/src/bootstrap.ts      |  19 +-
 .../code-runtime-worker/src/runtime-host.ts   | 251 ------
 .../tests/bootstrap.spec.ts                   |  27 -
 .../code-runtime-worker/tsconfig.json         |   3 +
 .../code-runtime-worker/tsdown.config.ts      |  17 +-
 packages/code-runtime/code-runtime/README.md  |   4 +-
 .../code-runtime/tests/contract.ts            | 853 ------------------
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   4 +-
 packages/subprocess/README.zh.md              |   4 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   4 +-
 .../subprocess/subprocess-local/README.zh.md  |   4 +-
 .../subprocess/subprocess-local/src/index.ts  |   3 +-
 .../subprocess-local/tests/local.spec.ts      |   3 -
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   4 +-
 packages/subprocess/subprocess/README.zh.md   |   4 +-
 packages/subprocess/subprocess/src/index.ts   |  11 +-
 scripts/check-workspace-constraints.ts        |   1 -
 scripts/gen-code-runtime-runner.ts            |  70 --
 scripts/gen-doc-graphs.ts                     | 276 ++----
 scripts/run-gates.ts                          |   1 -
 .../verify-package-readme-model-experience.ts |   1 -
 tsconfig.host.json                            |   1 -
 44 files changed, 192 insertions(+), 1614 deletions(-)
 delete mode 100644 packages/code-runtime/code-runtime-worker/src/runtime-host.ts
 delete mode 100644 packages/code-runtime/code-runtime/tests/contract.ts
 delete mode 100644 scripts/gen-code-runtime-runner.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index fde94ee5cf..f805e7cde3 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 214a46959c48862176e3c790d541def3444e31ad
-2026-07-26-subprocess-seam.zh.md: 13ba397458a041ec358828bab53e75516fd3e76d
+2026-07-26-subprocess-seam.md: 8797102c65ebab663bcf72fced5791364fe2c6ae
+2026-07-26-subprocess-seam.zh.md: 8a7ff14079374d6d74a1ec729dd02c8961fa23e6
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 214a46959c..8797102c65 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,7 +12,7 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
 - **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
@@ -21,13 +21,13 @@ Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-su
 
 Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral seam shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
-Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy; Code Runtime uses ordinary raw pipes. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
+Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
 
 ## Alternatives considered
 
 **Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
 
-**Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, PTY, and Code Runtime shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
+**Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, and PTY shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
 
 **Use one `stdio: 'pipe' | 'inherit' | 'collect'` mode for all streams.** Rejected because real consumers mix modes per stream: LSP uses pipe/pipe/collect, ACP uses pipe/pipe/inherit, and Bash uses data/collect/collect.
 
@@ -39,6 +39,6 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 ## Consequences
 
-Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; tree signalling, escalation, bounded collection, terminal mechanics, and credential scrubbing each have one implementation; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
+Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; tree signalling, escalation, bounded collection, terminal mechanics, and credential scrubbing each have one implementation; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
 
-Cost: one more package pair and one more composition row wherever a consumer loads; a missing subprocess provider leaves the consumer pending by standard service-injection behavior. Every backend implements execution-world coordinates, executable lookup, three stdio modes, tree lifecycle, and one terminal primitive. The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages name the same types; the subprocess seam is the owner. The spawn-failure note became single-delivery through Bash's consuming read cursor instead of repeatable stderr-buffer content.
+Cost: one more package pair and one more composition row wherever a consumer loads; a missing subprocess provider leaves the consumer pending by standard service-injection behavior. Every backend implements executable lookup, three stdio modes, tree lifecycle, and one terminal primitive. The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages name the same types; the subprocess seam is the owner. The spawn-failure note became single-delivery through Bash's consuming read cursor instead of repeatable stderr-buffer content.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 13ba397458..8a7ff14079 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
 - **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
@@ -21,13 +21,13 @@ Status: implemented
 
 后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
-基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略；Code Runtime 使用普通原始管道。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
+基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
 
 ## 曾考虑的替代方案
 
 **把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
 
-**保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP、PTY 与 Code Runtime 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
+**保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP 与 PTY 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
 
 **用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式统一全部流。**否决：真实消费方按流混用模式——LSP 使用 pipe/pipe/collect，ACP 使用 pipe/pipe/inherit，Bash 使用 data/collect/collect。
 
@@ -39,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP 消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；进程树信号、升级终止、有界收集、终端机制与凭据清除各自只剩一份实现；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
+换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY 与 ACP 消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；进程树信号、升级终止、有界收集、终端机制与凭据清除各自只剩一份实现；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
 
-代价是：多出一对包，而且凡加载消费方之处都多一行组合配置；缺少 subprocess 提供方时，消费方会按标准服务注入行为保持挂起。每个后端都要实现执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包命名同一批类型；进程 seam 是所有者。spawn 失败提示经由 Bash 的消费式读取游标变为单次交付，不再是可重复读取的 stderr 缓冲内容。
+代价是：多出一对包，而且凡加载消费方之处都多一行组合配置；缺少 subprocess 提供方时，消费方会按标准服务注入行为保持挂起。每个后端都要实现可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包命名同一批类型；进程 seam 是所有者。spawn 失败提示经由 Bash 的消费式读取游标变为单次交付，不再是可重复读取的 stderr 缓冲内容。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 62592b5be0..06fd47f329 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 97c8bcfc7bf84db4b6a2862fcc9d991ee7f4a7f6
-2026-07-28-portable-execution-world-consumers.zh.md: 025393f9e5ae99feba41fa8badeef8276151ba6f
+2026-07-28-portable-execution-world-consumers.md: 402aa580255a5bd6aa0d046e3bcc16f712da520d
+2026-07-28-portable-execution-world-consumers.zh.md: 26d493a79f8adb9e729ff69b0673f2f2775868b0
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 97c8bcfc7b..402aa58025 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
 
 ## Problem
 
-The filesystem and subprocess seams made file and ordinary process access replaceable, but several higher capabilities still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY, LSP, and Code Runtime packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
+The filesystem and subprocess seams made file and ordinary process access replaceable, but PTY and LSP still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY and LSP packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
 
 Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
 
@@ -16,20 +16,17 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns executable lookup and process primitives: ordinary raw or collected process spawning and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
-- `dsh-code-runtime-subprocess` passes a bundled dependency-free eval runner directly to `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote process worlds without a filesystem dependency or provider-specific package. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
-
-`dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
 ## Alternatives considered
 
-**Keep one PTY, LSP, and Code Runtime package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
+**Keep one PTY and LSP package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
 
 **Model a terminal as an ordinary piped subprocess.** Rejected because pipes cannot allocate a controlling terminal, resolve the current foreground process group, or prove complete terminal-session cleanup. One terminal primitive is smaller and more honest than exposing substrate-specific escape hatches.
 
@@ -39,13 +36,11 @@ Generic consumers use that execution world:
 
 **Add a stable bounded-read primitive to the filesystem seam.** Rejected because only LSP needs a complete-document byte ceiling, which it can enforce while consuming the existing text stream. A second primitive forces every provider to implement stable-handle and no-follow mechanics, including a remote helper protocol, without an observed concurrent-replacement defect.
 
-**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable; the worker backend does not and remains the supported single-process path.
-
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
 
 ## Consequences
 
-A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, LSP, and subprocess Code Runtime compose above them, so fixes to those capabilities remain provider-neutral.
+A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, and LSP compose above them, so fixes to those capabilities remain provider-neutral.
 
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 025393f9e5..26d493a79f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但 PTY 和 LSP 仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY 与 LSP 包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
 
 普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
 
@@ -16,20 +16,16 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
-- `dsh-code-runtime-subprocess` 将一个内置的无依赖 eval runner 直接传给 `ctx.subprocess`，从而在本地或远程进程执行环境中保留代码运行时的绑定与输出契约，且不依赖文件系统或提供方专用包。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
-
-`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
-
 ## 考虑过的替代方案
 
-**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+**为每个远程提供方分别保留 PTY 与 LSP 包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
 
 **把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
 
@@ -39,13 +35,11 @@ Status: implemented
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件，而 worker 后端不需要，并且仍是受支持的单进程路径。
-
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
 
 ## 后果
 
-远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY 与 LSP 组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index d2655b6d02..8773a797e9 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: a075ea66c150afb1b48f98c600b72eec57869962
-2026-06-15-code-mode.zh.md: c269c0a8709087e7b1e27051cbda3924f8dd9109
+2026-06-15-code-mode.md: b6a24ecd9700e32912b8112b59cbd8b6ab131eb5
+2026-06-15-code-mode.zh.md: 4d0a4cf8fa31cf9d9954e5bd95f823dfc0668444
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index a075ea66c1..b6a24ecd97 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -20,7 +20,7 @@ Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
 2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
-3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` passes a bundled eval runner to `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
+3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
 
@@ -64,7 +64,7 @@ Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool en
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }` — the runtime exposes each namespace as a global object of async functions inside the program; the optional descriptor asks the runtime to inject a real program-visible rejection class without teaching the seam consumer-specific names. `CodeJsonValue` is this dependency-light seam's structural lossless-JSON type, so binding arguments and resolutions cross the implementation's serialization boundary whole.
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }` — program execution outcomes resolve as the `error` field. `run()` may reject only for caller/seam misuse (for example a duplicate binding namespace); consumers still contain a non-conforming backend rejection at their own error boundary.
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../../docs/defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout, a lossy completion is not an overflow, and a substrate exit is none of them.
-- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for both shipped backends; a Python backend would pair with its own SDK generator) and `isolation` (`'worker-thread'` for both shipped backends; the subprocess provider may add a container boundary). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the shipped backend; a Python backend would say so, and pair with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
 
 Requests contain every runtime input; implementations own validated timeout and cap defaults. The registry looks up the optional runtime only when Code Mode is assembled, so native mode does not depend on one. Missing or language-incompatible runtimes fail loudly. Alternate substrates or languages can replace the implementation behind the same seam, paired with the appropriate SDK generator.
 
@@ -79,11 +79,9 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across another process world. It passes a dependency-free eval runner directly through the subprocess provider and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
-
 ### Trust posture
 
-The runtimes provide containment, not an independent security boundary: model code can reach Node APIs and has the authority of its mounted execution world. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty worker environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary mount container-class filesystem/subprocess providers for both code and bash.
+The worker runtime provides containment, not a security boundary: model code can reach Node APIs and has authority comparable to the bash tool. `worker.terminate()` stops the thread but not OS processes it spawned. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary need a container-class backend for both code and bash; the runtime's isolation descriptor lets them distinguish that backend.
 
 ### What the model sees
 
@@ -95,7 +93,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
+- **Worker runtime:** Real-worker tests cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. A built-package test runs the worker entry under plain Node.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
@@ -120,7 +118,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Risks
 
-**A worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool and gating uses the same seams. The subprocess implementation can run inside a container-class execution world, but its worker descriptor does not itself claim that boundary.
+**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
 
 **`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
 
@@ -128,7 +126,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Registry scope growth.** `dsh-tools` absorbs codegen, a tool, a bridge, and an event. Contained by module boundaries inside the package (`ts-types.ts`, `code-mode.ts` beside `schema.ts`/`json-schema.ts`/`presentation.ts`) and by the seam: everything substrate-shaped lives behind `ctx.codeRuntime`.
 
-**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The direct worker runtime applies no per-binding byte cap; the subprocess runtime bounds each transport frame with `maxFrameBytes`, but repeated or concurrent calls can still consume process or worker memory. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is separately bounded by `maxOutputBytes`.
+**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The runtime validates both sides of the worker port and applies no per-binding byte cap; structured-clone cost and process or worker memory are the practical bounds. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is the only byte-capped boundary.
 
 **Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index c269c0a870..4d0a4cf8fa 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -20,7 +20,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
 2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
-3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则将一个内置的 eval runner 传给 `ctx.subprocess`，用于另一执行环境。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
+3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
 
@@ -64,7 +64,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }`——程序执行失败时，执行 promise 仍会 fulfill，并通过 `error` 字段返回失败结果。只有调用方/seam 误用（例如重复的绑定命名空间）时，`run()` 才会 reject；消费方仍在自己的错误边界处理不合规后端的拒绝。
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }`——按[防御性模式](../../../../docs/defensive-patterns.md)独立报告的正交结果；超时的 run 不是异常，abort 不是超时，有损完成值不是溢出，基底退出也与上述情况相互独立。
-- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——两种已交付后端均为 `'typescript'`；Python 后端会配对自己的 SDK 生成器）和 `isolation`（两种已交付后端均为 `'worker-thread'`；子进程提供方可以增加容器边界）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
+- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——交付的后端为 `'typescript'`；Python 后端会声明自己，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
 
 请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
 
@@ -79,11 +79,9 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在另一进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它通过子进程提供方直接传递一个无依赖的 eval runner，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
-
 ### 信任姿态
 
-这些运行时提供的是隔离，而非独立安全边界：模型代码可以访问 Node API，并拥有挂载的执行环境所授予的权限。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空 worker 环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署应当为代码和 bash 都挂载容器级文件系统／子进程提供方。
+worker 运行时提供的是隔离，而非安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
 
 ### 模型看到的内容
 
@@ -95,7 +93,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 测试
 
-- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
+- **Worker 运行时：** 真实 worker 测试覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。一个构建后包测试在纯 Node 下运行 worker 入口。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
@@ -120,7 +118,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 风险
 
-**worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，门禁使用相同的 seam。子进程实现可以在容器级执行环境中运行，但其 worker 描述符本身不声称具备该边界。
+**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，隔离程度超过它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
 
@@ -128,7 +126,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 **注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
 
-**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。直接 worker 运行时不对单次绑定设置字节数上限；子进程运行时使用 `maxFrameBytes` 限制每个传输帧，但重复或并发调用仍可能消耗进程或 worker 内存。包含日志、完成值和失败诊断的组合外层输出账本另由 `maxOutputBytes` 限制。
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
 
 **仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 1aee225b5d..c5ec654d0f 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -21,6 +21,7 @@ flowchart LR
   pkg_session["session"]
   svc_sessions["ctx.sessions<br/>In-memory session store"]
   pkg_agent["agent"]
+  pkg_cli_demo["cli-demo"]
   pkg_session_persistence["session-persistence"]
   pkg_session_query["session-query"]
   pkg_session_query_sqlite["session-query-sqlite"]
@@ -39,13 +40,6 @@ flowchart LR
   pkg_tool_bash["tool-bash"]
   pkg_hooks_claude["hooks-claude"]
   pkg_hooks_codex["hooks-codex"]
-  pkg_settings["settings"]
-  svc_settings["ctx.settings<br/>User-settings seam"]
-  pkg_settings_local["settings-local"]
-  pkg_apiproxy["apiproxy"]
-  pkg_credentials["credentials"]
-  svc_credentials["ctx.credentials<br/>Credential seam"]
-  pkg_credentials_local["credentials-local"]
   pkg_session_telemetry["session-telemetry"]
   svc_telemetry["ctx.telemetry<br/>Session telemetry seam"]
   pkg_session_telemetry_otel["session-telemetry-otel"]
@@ -57,10 +51,12 @@ flowchart LR
   svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
   pkg_workspace["workspace"]
   svc_workspace["ctx.workspace<br/>Workspace entity registry"]
+  pkg_apiproxy["apiproxy"]
   svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
   pkg_session_reference["session-reference"]
   pkg_tool_session_query["tool-session-query"]
   svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
+  pkg_tui["tui"]
   pkg_session_title["session-title"]
   svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
   pkg_session_title_first_message_llm["session-title-first-message-llm"]
@@ -88,12 +84,13 @@ flowchart LR
   pkg_host_apiproxy["host-apiproxy"]
   pkg_session_projection_cache["session-projection-cache"]
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
+  svc_tui["ctx.tui<br/>Mounted-terminal interaction service"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
-  pkg_skill_badge["skill-badge"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
+  pkg_tui_demo["tui-demo"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -103,19 +100,14 @@ flowchart LR
   pkg_subprocess_local["subprocess-local"]
   pkg_bash_local["bash-local"]
   pkg_bash_sandbox["bash-sandbox"]
+  pkg_pty_local["pty-local"]
   pkg_lsp_local["lsp-local"]
   pkg_subagent_acp["subagent-acp"]
-  pkg_subagent_codex["subagent-codex"]
-  pkg_subagent_claude_code["subagent-claude-code"]
   pkg_bash["bash"]
   svc_bash["ctx.bash<br/>Bash executor seam"]
-  pkg_pwsh_local["pwsh-local"]
-  pkg_tool_pwsh["tool-pwsh"]
-  pkg_bash_env["bash-env"]
   svc_bashEnv["ctx.bashEnv<br/>Managed bash environment registry"]
   pkg_pty["pty"]
   svc_pty["ctx.pty<br/>Persistent PTY session registry"]
-  pkg_pty_local["pty-local"]
   pkg_sandbox["sandbox"]
   svc_sandbox["ctx.sandbox<br/>Process-sandbox seam"]
   pkg_sandbox_local["sandbox-local"]
@@ -136,11 +128,9 @@ flowchart LR
   pkg_compact["compact"]
   svc_compact["ctx.compact<br/>Compaction seam"]
   pkg_subagent["subagent"]
-  svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
+  svc_subagents["ctx.subagents<br/>Subagent provider registry"]
   pkg_subagent_spawn["subagent-spawn"]
   pkg_subagent_fork["subagent-fork"]
-  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
-  pkg_tool_subagent_control["tool-subagent-control"]
   pkg_tool_ralph["tool-ralph"]
   pkg_tasks["tasks"]
   svc_tasks["ctx.tasks<br/>Background task registry"]
@@ -176,7 +166,6 @@ flowchart LR
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
   pkg_bash --> svc_bash
-  pkg_bash_env --> svc_bashEnv
   pkg_bash_local --> svc_bash
   pkg_bash_sandbox --> svc_bash
   pkg_code_runtime --> svc_codeRuntime
@@ -185,8 +174,6 @@ flowchart LR
   pkg_compact --> svc_compact
   pkg_compact_basic --> svc_compact
   pkg_compact_tool_result_prune --> svc_toolResultPrune
-  pkg_credentials --> svc_credentials
-  pkg_credentials_local --> svc_credentials
   pkg_directory_picker --> svc_directoryPicker
   pkg_directory_picker_browse --> svc_directoryPicker
   pkg_directory_picker_native --> svc_directoryPicker
@@ -204,7 +191,6 @@ flowchart LR
   pkg_plan_mode --> svc_planMode
   pkg_pty --> svc_pty
   pkg_pty_local --> svc_pty
-  pkg_pwsh_local --> svc_bash
   pkg_sandbox --> svc_sandbox
   pkg_sandbox_local --> svc_sandbox
   pkg_sandbox_policy --> svc_sandboxPolicy
@@ -222,10 +208,7 @@ flowchart LR
   pkg_session_title --> svc_sessionTitle
   pkg_session_title_all_messages_llm --> svc_sessionTitle
   pkg_session_title_first_message_llm --> svc_sessionTitle
-  pkg_settings --> svc_settings
-  pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
-  pkg_skill_badge --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
   pkg_spill_local --> svc_spillStore
@@ -235,9 +218,6 @@ flowchart LR
   pkg_storage_sqlite --> svc_storage
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
-  pkg_subagent_claude_code --> svc_subagents
-  pkg_subagent_codex --> svc_subagents
-  pkg_subagent_dsh_sdk --> svc_subagents
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
@@ -246,7 +226,10 @@ flowchart LR
   pkg_tasks --> svc_tasks
   pkg_tasks_local --> svc_tasks
   pkg_token_meter --> svc_tokenMeter
+  pkg_tool_bash --> svc_bashEnv
   pkg_tools --> svc_tools
+  pkg_tui --> svc_tui
+  pkg_tui --> svc_userInteraction
   pkg_typert_registry --> svc_typert
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
@@ -261,21 +244,18 @@ flowchart LR
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
+  svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
+  svc_agents --> pkg_tui_demo
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
   svc_bash --> pkg_hooks_claude
   svc_bash --> pkg_hooks_codex
   svc_bash --> pkg_tool_bash
-  svc_bash --> pkg_tool_pwsh
-  svc_bashEnv --> pkg_tool_bash
-  svc_bashEnv --> pkg_tool_pwsh
   svc_clientModuleHost --> pkg_hmr
   svc_codeRuntime --> pkg_tools
+  svc_commands --> pkg_tui
   svc_compact --> pkg_compact_basic
-  svc_credentials --> pkg_apiproxy
-  svc_credentials --> pkg_llm_deepseek
-  svc_credentials --> pkg_llm_pi_ai
   svc_directoryPicker --> pkg_apiproxy
   svc_fs --> pkg_tool_fs
   svc_httpServer --> pkg_connection
@@ -305,29 +285,26 @@ flowchart LR
   svc_sessionProjections --> pkg_tool_todo
   svc_sessionQuery --> pkg_session_reference
   svc_sessionQuery --> pkg_tool_session_query
+  svc_sessionReferences --> pkg_tui
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
+  svc_sessions --> pkg_cli_demo
   svc_sessions --> pkg_invariants
   svc_sessions --> pkg_session_persistence
   svc_sessions --> pkg_session_query
   svc_sessions --> pkg_session_query_sqlite
   svc_sessions --> pkg_subagent_inprocess
-  svc_settings --> pkg_apiproxy
-  svc_settings --> pkg_llm_deepseek
-  svc_settings --> pkg_llm_pi_ai
   svc_skills --> pkg_tool_skill
   svc_spillStore --> pkg_spill_policy
   svc_storage --> pkg_storage_domain
   svc_storageDomain --> pkg_workspace
   svc_subagents --> pkg_tool_ralph
   svc_subagents --> pkg_tool_subagent
-  svc_subagents --> pkg_tool_subagent_control
   svc_subprocess --> pkg_bash_local
   svc_subprocess --> pkg_bash_sandbox
   svc_subprocess --> pkg_lsp_local
+  svc_subprocess --> pkg_pty_local
   svc_subprocess --> pkg_subagent_acp
-  svc_subprocess --> pkg_subagent_claude_code
-  svc_subprocess --> pkg_subagent_codex
   svc_systemPrompt --> pkg_agent_loop
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_pty
@@ -352,6 +329,7 @@ flowchart LR
   svc_typert --> pkg_api_gateway
   svc_typert --> pkg_typert_loader
   svc_userInteraction --> pkg_tool_ask_user
+  svc_userInteraction --> pkg_tui
   svc_web --> pkg_tool_web
   svc_workflows --> pkg_tool_ralph
   svc_workflows --> pkg_tool_workflow
@@ -364,34 +342,33 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
-| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
-| `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
 | `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
 | `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
-| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
+| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | [`tui`](../packages/ui/tui) | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
-| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
+| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui) | - | Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.tui` | `bundle` | [`tui`](../packages/ui/tui) | - | - | - | One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state. |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation. |
-| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
-| `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp) | - | The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
+| `ctx.bashEnv` | `core` | [`tool-bash`](../packages/bash/tool-bash) | - | - | - | Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
@@ -400,7 +377,7 @@ flowchart LR
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
-| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a875c190fe..b8a49a7ba2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -284,30 +284,6 @@ export interface Config {
 
 Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
 
-## `@deepseek-ai/dsh-code-runtime-subprocess`
-
-Requires: `subprocess`
-
-```ts config-catalog
-/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
-export interface Config {
-  /** Worker measured event-loop busy-time budget. */
-  computeMs?: number
-  /** Host-observed wall-clock ceiling. */
-  maxWallMs?: number
-  /** Combined serialized outer logs/value/diagnostic cap. */
-  maxOutputBytes?: number
-  /** Worker old-generation heap cap in MiB. */
-  maxOldGenerationSizeMb?: number
-  /** Largest decoded bridge frame, including binding traffic. */
-  maxFrameBytes?: number
-  /** Process-tree TERM-to-KILL grace. */
-  killGraceMs?: number
-}
-```
-
-Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:27`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
-
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
 ```ts config-catalog
@@ -341,7 +317,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:30`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../packages/code-runtime/code-runtime-worker/src/index.ts)
 
 ## `@deepseek-ai/dsh-compact-basic`
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index cfa3762222..50e219a2c6 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: c68a2f77059f62b273c536987b321017f2a71bbb
-subprocess.zh.md: 061c681430ba1f011b4ed9e5c4d9fc8595fe6738
+subprocess.md: 895bfe3d763853a86648e8aaab8b091a26006255
+subprocess.zh.md: 044e924674ecf5dd8f8a1c71fe39653e7525dfb0
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index a258ff4767..023b122218 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -2,13 +2,13 @@
 
 English | [中文](subprocess.zh.md)
 
-The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, the LSP and Code Runtime hosts use raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
+The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
 
 Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
-## Execution-world coordinates
+## Executable lookup
 
-One provider's `cwd`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides.
+One provider's spawn working directories, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides.
 
 ## Managed environment namespace and captured output
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 061c681430..044e924674 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -2,13 +2,13 @@
 
 [English](subprocess.md) | 中文
 
-进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 与 Code Runtime 主机使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
 源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
-## 执行世界坐标
+## 可执行文件查找
 
-一个提供方的 `cwd`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
+一个提供方的 spawn 工作目录、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
 
 ## 受管环境命名空间与捕获的输出
 
diff --git a/knip.json b/knip.json
index 413b740578..ede8b2c738 100644
--- a/knip.json
+++ b/knip.json
@@ -383,17 +383,6 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/code-runtime/code-runtime-subprocess": {
-      "entry": [
-        "src/runner.ts",
-        "tests/**/*.spec.ts",
-        "tests/**/*.e2e.ts"
-      ],
-      "project": [
-        "src/**/*.ts",
-        "tests/**/*.ts"
-      ]
-    },
     "packages/llm/llm-deepseek": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/package.json b/package.json
index 2b4971a6b7..423cbf813c 100644
--- a/package.json
+++ b/package.json
@@ -112,8 +112,6 @@
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
     "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
-    "gen-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts",
-    "verify-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts --check",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
     "doc-sync": "tsx scripts/run-gates.ts doc-sync",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index eaa48fac05..1484411cca 100644
--- 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: b498c146202f1a69d89805fa3e8966c4d0735d6c
-README.zh.md: 2eefc73ed0ea22aae5fde93284c25c5d03fe86c4
+README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
+README.zh.md: faa879f3b5b62527c1d76ab3aff6a737f876ce4d
diff --git a/packages/README.md b/packages/README.md
index 7d591605ef..229feae568 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -19,7 +19,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and subprocess backends | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index a9201d08a9..bed31b657c 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及进程管理后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：用于模型编写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
index 2207389c97..cbe0d0ac55 100644
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -6,7 +6,6 @@
  */
 
 import { inspect } from 'node:util'
-import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
 import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
 import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
 import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
@@ -311,7 +310,6 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
  * @param pending - the id-keyed map each posted call parks its handles in.
  * @param nextId - the shared mutable id counter (worker-issued correlation ids).
  * @param errorClasses - per-namespace constructors shared with program globals.
- * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns one namespace object per declaration, in declaration order.
  */
 export function makeNamespaces(
@@ -320,7 +318,6 @@ export function makeNamespaces(
   pending: Map<number, PendingCall>,
   nextId: { value: number },
   errorClasses: Map<string, BindingErrorConstructor> = makeBindingErrorClasses(data),
-  maxFrameBytes?: number,
 ): Record<string, unknown>[] {
   return data.namespaces.map(({ global, names }) => {
     const errorClass = errorClasses.get(global)
@@ -338,11 +335,6 @@ export function makeNamespaces(
           if (detached === undefined) {
             return Promise.reject(bindingFailure(errorClass, name, 'binding arguments must be lossless JSON'))
           }
-          const call = { type: 'call' as const, id: nextId.value, global, name, args: encodeWorkerJson(detached) }
-          if (maxFrameBytes !== undefined
-            && jsonValueBytesUpTo(call as unknown as CodeJsonValue, maxFrameBytes) === undefined) {
-            return Promise.reject(bindingFailure(errorClass, name, 'binding arguments exceed maxFrameBytes'))
-          }
           return new Promise((resolve, reject) => {
             const id = nextId.value++
             pending.set(id, {
@@ -352,7 +344,7 @@ export function makeNamespaces(
               },
             })
             try {
-              port.postMessage(call)
+              port.postMessage({ type: 'call', id, global, name, args: encodeWorkerJson(detached) })
             } catch (error: unknown) {
               pending.delete(id)
               const message = `binding arguments must be structured-cloneable: ${error instanceof CapturedError ? error.message : String(error)}`
@@ -372,14 +364,12 @@ export function makeNamespaces(
  * @param port - host message port or test double.
  * @param data - the boot payload the host sent.
  * @param streams - stdout/stderr objects captured as program logs.
- * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns after posting the done message.
  */
 export async function runWorkerMain(
   port: BootstrapPort,
   data: WorkerBootData,
   streams: { stdout: PatchableStream; stderr: PatchableStream },
-  maxFrameBytes?: number,
 ): Promise<void> {
   const logs = new LogBuffer(
     data.maxOutputBytes,
@@ -394,7 +384,7 @@ export async function runWorkerMain(
 
   const nextId = { value: 1 }
   const errorClasses = makeBindingErrorClasses(data)
-  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses, maxFrameBytes)
+  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses)
   const errorClassParameters: string[] = []
   const errorClassValues: BindingErrorConstructor[] = []
   for (const namespace of data.namespaces) {
@@ -430,8 +420,5 @@ export async function runWorkerMain(
       ...prepareException(error, logs.remainingOutputBytes(), data.maxOutputBytes),
     }
   }
-  port.postMessage(maxFrameBytes !== undefined
-    && jsonValueBytesUpTo(done as unknown as CodeJsonValue, maxFrameBytes) === undefined
-    ? { type: 'output-limit' }
-    : done)
+  port.postMessage(done)
 }
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
deleted file mode 100644
index 47bfacfe91..0000000000
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ /dev/null
@@ -1,251 +0,0 @@
-/** Shared host mechanics for local and subprocess-hosted TypeScript worker runtimes. */
-
-import { stripTypeScriptTypes } from 'node:module'
-import type { Readable } from 'node:stream'
-import type {
-  CodeBindingNamespace,
-  CodeJsonValue,
-  CodeRunFailure,
-  CodeRunRequest,
-  CodeRunResult,
-} from '@deepseek-ai/dsh-code-runtime'
-import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
-import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-import type { WorkerJsonWire } from './worker-json.ts'
-
-/** Smallest cap that can represent an empty log array and failure message. */
-export const MIN_RUNTIME_OUTPUT_BYTES = 4
-
-/**
- * Resolve after a worker pipe emits queued data or closes during termination.
- * @param stream - captured worker or child-process pipe.
- * @returns after no more queued bytes can arrive.
- */
-export function waitForRuntimePipeDrain(stream: Readable): Promise<void> {
-  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
-  return new Promise((resolve) => {
-    const done = (): void => {
-      stream.off('end', done)
-      stream.off('close', done)
-      stream.off('error', done)
-      resolve()
-    }
-    stream.once('end', done)
-    stream.once('close', done)
-    stream.once('error', done)
-    /* v8 ignore next -- termination can win the adjacent listener-registration race. */
-    if (stream.readableEnded || stream.destroyed) done()
-  })
-}
-
-const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
-const RESERVED_WORDS = new Set([
-  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
-  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
-  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
-  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
-  'private', 'protected', 'public', 'arguments', 'eval',
-])
-const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
-const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
-
-/** One validated binding call received from an isolated worker. */
-export interface RuntimeBindingCall {
-  /** Correlation id supplied by the isolated worker. */
-  readonly id: number
-  /** Injected namespace global. */
-  readonly global: string
-  /** Declared namespace function. */
-  readonly name: string
-  /** Untrusted lossless-JSON wire payload. */
-  readonly args: unknown
-}
-
-/** One host reply to an isolated worker binding call. */
-export type RuntimeBindingReply =
-  | { readonly type: 'reply'; readonly id: number; readonly ok: true; readonly value: WorkerJsonWire }
-  | { readonly type: 'reply'; readonly id: number; readonly ok: false; readonly message: string }
-
-/**
- * Render an unknown thrown value without assuming it is an Error.
- * @param error - thrown or rejected value.
- * @returns the caller-facing diagnostic text.
- */
-export function runtimeErrorMessage(error: unknown): string {
-  try {
-    return error instanceof Error ? error.message : String(error)
-  } catch {
-    return 'binding rejected with an unrenderable value'
-  }
-}
-
-/**
- * Strip erasable TypeScript while preserving the program's body coordinates.
- * @param program - model-written async-function body.
- * @returns JavaScript source with the wrapper removed.
- */
-export function stripRuntimeProgram(program: string): string {
-  const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + program + STRIP_WRAP.suffix)
-  return stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
-}
-
-/**
- * Validate binding globals and typed-error declarations shared by worker runtimes.
- * @param request - code-runtime request carrying the namespaces.
- * @param implementationName - package name used in seam-misuse diagnostics.
- * @returns namespaces indexed by their injected global.
- */
-export function validateRuntimeBindings(
-  request: CodeRunRequest,
-  implementationName: string,
-): Map<string, CodeBindingNamespace> {
-  const bindings = new Map<string, CodeBindingNamespace>()
-  for (const namespace of request.bindings) {
-    if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
-      throw new Error(`${implementationName}: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
-    }
-    if (namespace.global === 'console' || bindings.has(namespace.global)) {
-      throw new Error(`${implementationName}: duplicate binding global ${JSON.stringify(namespace.global)}`)
-    }
-    bindings.set(namespace.global, namespace)
-  }
-
-  const errorClassNames = new Set<string>()
-  for (const namespace of request.bindings) {
-    const descriptor = namespace.errorClass
-    if (descriptor === undefined) continue
-    if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
-      throw new Error(`${implementationName}: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
-    }
-    if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
-      throw new Error(`${implementationName}: duplicate injected global ${JSON.stringify(descriptor.name)}`)
-    }
-    if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
-      throw new Error(`${implementationName}: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
-    }
-    errorClassNames.add(descriptor.name)
-  }
-  return bindings
-}
-
-/**
- * Resolve one untrusted worker call through a declared host binding.
- * @param call - parsed call envelope from the isolated worker.
- * @param bindings - namespaces returned by {@link validateRuntimeBindings}.
- * @returns a lossless-JSON success or stable rejection reply.
- */
-export async function invokeRuntimeBinding(
-  call: RuntimeBindingCall,
-  bindings: ReadonlyMap<string, CodeBindingNamespace>,
-): Promise<RuntimeBindingReply> {
-  const functions = bindings.get(call.global)?.functions
-  const fn = functions !== undefined && Object.hasOwn(functions, call.name) ? functions[call.name] : undefined
-  if (typeof fn !== 'function') {
-    return { type: 'reply', id: call.id, ok: false, message: `unknown binding ${JSON.stringify(`${call.global}.${call.name}`)}` }
-  }
-  const args = decodeWorkerJson(call.args)
-  if (args === undefined) {
-    return { type: 'reply', id: call.id, ok: false, message: 'binding arguments must be lossless JSON' }
-  }
-  try {
-    const resolved = await fn(args)
-    let value: CodeJsonValue | undefined
-    try {
-      value = snapshotCodeJsonValue(resolved)
-    } catch {
-      value = undefined
-    }
-    if (value === undefined) {
-      return { type: 'reply', id: call.id, ok: false, message: 'binding resolution must be lossless JSON' }
-    }
-    return { type: 'reply', id: call.id, ok: true, value: encodeWorkerJson(value) }
-  } catch (error: unknown) {
-    return { type: 'reply', id: call.id, ok: false, message: runtimeErrorMessage(error) }
-  }
-}
-
-/** One run's combined outer-output ledger; binding values never enter it. */
-export class RuntimeOutputLedger {
-  private bytes = 2
-  private entries = 0
-
-  /** @param maxBytes - hard cap for logs plus completion or failure payload. */
-  constructor(private readonly maxBytes: number) {}
-
-  /**
-   * Admit one exact log entry.
-   * @param text - candidate log entry.
-   * @param sink - ordered retained log list.
-   * @returns false when the hard cap was crossed.
-   */
-  admit(text: string, sink: string[]): boolean {
-    const separatorBytes = this.entries > 0 ? 1 : 0
-    const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
-    if (stringBytes === undefined) return false
-    this.bytes += stringBytes + separatorBytes
-    this.entries += 1
-    sink.push(text)
-    return true
-  }
-
-  /**
-   * Finalize a successful completion against the combined cap.
-   * @param logs - retained ordered logs.
-   * @param value - optional lossless-JSON completion.
-   * @returns the completion or output-limit result.
-   */
-  success(logs: string[], value?: CodeJsonValue): CodeRunResult {
-    if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
-    return { logs, ...value !== undefined ? { value } : {} }
-  }
-
-  /**
-   * Finalize one failure diagnostic against the combined cap.
-   * @param logs - retained ordered logs.
-   * @param error - structured runtime failure.
-   * @returns the failure or output-limit result.
-   */
-  failure(logs: string[], error: CodeRunFailure): CodeRunResult {
-    if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
-    return { logs, error }
-  }
-
-  /**
-   * Build an explicit output-limit failure with a fitting log prefix.
-   * @param logs - ordered logs observed before the limit.
-   * @returns bounded output-limit result.
-   */
-  limit(logs: string[]): CodeRunResult {
-    const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
-    const messageBytes = fullMessage.length + 2
-    const retained: string[] = []
-    let retainedBytes = 2
-    const logBudget = this.maxBytes - messageBytes
-    for (const text of logs) {
-      const separatorBytes = retained.length > 0 ? 1 : 0
-      const availableBytes = logBudget - retainedBytes - separatorBytes
-      const stringBytes = jsonStringBytesUpTo(text, availableBytes)
-      if (stringBytes !== undefined) {
-        retained.push(text)
-        retainedBytes += stringBytes + separatorBytes
-        continue
-      }
-      const prefix = truncateJsonStringBytes(text, availableBytes)
-      if (prefix.length > 0) {
-        const prefixBytes = jsonStringBytesUpTo(prefix, availableBytes)
-        /* v8 ignore next -- truncateJsonStringBytes guarantees the same bound. */
-        if (prefixBytes === undefined) throw new Error('output ledger produced an oversized log prefix')
-        retained.push(prefix)
-        retainedBytes += prefixBytes + separatorBytes
-      }
-      break
-    }
-    const message = truncateJsonStringBytes(fullMessage, this.maxBytes - retainedBytes)
-    return { logs: retained, error: { kind: 'output-limit', message } }
-  }
-}
-
-export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-export { jsonStringBytesUpTo, jsonValueBytesUpTo } from './output-json.ts'
-export { runWorkerMain } from './bootstrap.ts'
-export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
index 247501df29..a2aac6d9c2 100644
--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -286,23 +286,6 @@ describe('makeNamespaces', () => {
     expect(nextId.value).toBe(1)
   })
 
-  it('rejects an oversized transport frame before posting or allocating a call id', async () => {
-    const port = new FakePort()
-    const pending = new Map<number, PendingCall>()
-    const nextId = { value: 1 }
-    const data = { namespaces: [toolNamespace(['x'])] }
-    const [tools] = makeNamespaces(
-      data, port, pending, nextId, makeBindingErrorClasses(data), 64,
-    ) as [Record<string, (args: unknown) => Promise<unknown>>]
-
-    await expect(tools.x?.({ text: 'x'.repeat(64) })).rejects.toMatchObject({
-      name: 'ToolCallError', toolName: 'x', message: 'binding arguments exceed maxFrameBytes',
-    })
-    expect(port.sent).toEqual([])
-    expect(pending.size).toBe(0)
-    expect(nextId.value).toBe(1)
-  })
-
   it('uses ordinary Error for non-tools namespace failures', async () => {
     const deniedPort = new FakePort()
     deniedPort.respond = message => message.type === 'call'
@@ -360,16 +343,6 @@ describe('runWorkerMain', () => {
     })
   })
 
-  it('reports output-limit before posting a completion that expands past the transport cap', async () => {
-    const port = new FakePort()
-    await runWorkerMain(port, {
-      maxOutputBytes: 1_000,
-      code: 'return Array.from({ length: 100 }, () => [])',
-      namespaces: [],
-    }, fakeStreams(), 100)
-    expect(port.sent.at(-1)).toEqual({ type: 'output-limit' })
-  })
-
   it('reports a thrown program error on the done message', async () => {
     const port = new FakePort()
     await runWorkerMain(port, { ...BOOT, code: 'throw new Error("boom")', namespaces: [] }, fakeStreams())
diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json
index 340e68e848..555b3d161e 100644
--- a/packages/code-runtime/code-runtime-worker/tsconfig.json
+++ b/packages/code-runtime/code-runtime-worker/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
index dac6f12a65..1c40637722 100644
--- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts
+++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
@@ -1,10 +1,9 @@
 import { defineConfig } from 'tsdown'
 
 /**
- * Build the plugin, reusable runtime host, and worker as separate bundles. The
- * sibling `worker.cjs` is loaded by file and must be CommonJS for pkg's VFS
- * Worker hook. Separate builds inline shared implementation instead of
- * emitting an unlisted chunk outside the exact `files` whitelist.
+ * Build the index and worker as separate single-entry bundles. The sibling `worker.cjs` is loaded
+ * by file and must be CommonJS for pkg's VFS Worker hook. A multi-entry build emits an unlisted
+ * shared chunk omitted by the package's exact `files` whitelist; separate builds inline it.
  */
 export default defineConfig([
   {
@@ -17,16 +16,6 @@ export default defineConfig([
     dts: false,
     clean: false,
   },
-  {
-    entry: ['lib/types/runtime-host.js'],
-    outDir: 'lib',
-    format: ['esm'],
-    platform: 'node',
-    target: 'es2024',
-    fixedExtension: false,
-    dts: false,
-    clean: false,
-  },
   {
     entry: ['lib/types/worker.js'],
     outDir: 'lib',
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index d58508cd08..bb1c20d00a 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
-- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
+- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
+- **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
diff --git a/packages/code-runtime/code-runtime/tests/contract.ts b/packages/code-runtime/code-runtime/tests/contract.ts
deleted file mode 100644
index 8fee76f68a..0000000000
--- a/packages/code-runtime/code-runtime/tests/contract.ts
+++ /dev/null
@@ -1,853 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type {
-  CodeBindingFunction,
-  CodeBindingNamespace,
-  CodeRunResult,
-  CodeRuntime,
-} from '@deepseek-ai/dsh-code-runtime'
-
-interface WorkerCodeRuntimeContractConfig {
-  computeMs?: number
-  maxWallMs?: number
-  maxOutputBytes?: number
-  maxOldGenerationSizeMb?: number
-}
-
-interface WorkerCodeRuntimeContractHarness {
-  runtime: CodeRuntime
-  dispose: () => Promise<void>
-}
-
-type WorkerCodeRuntimeContractSetup = (
-  config?: WorkerCodeRuntimeContractConfig,
-) => Promise<WorkerCodeRuntimeContractHarness>
-
-/** Convenience: one namespace `tools` with the given functions. */
-export function workerRuntimeTools(
-  functions: Record<string, (args: unknown) => Promise<unknown>>,
-): CodeBindingNamespace[] {
-  return [{
-    global: 'tools',
-    functions: functions as Record<string, CodeBindingFunction>,
-    errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
-  }]
-}
-
-/** Run behavior shared by the direct and subprocess-hosted worker runtimes. */
-export function runWorkerCodeRuntimeContract(
-  label: string,
-  setup: WorkerCodeRuntimeContractSetup,
-): void {
-  describe(`${label} — programs and bindings (real workers)`, () => {
-    it('registers with the seam descriptors', async () => {
-      const { runtime } = await setup()
-      expect(runtime.language).toBe('typescript')
-      expect(runtime.isolation).toBe('worker-thread')
-    })
-
-    it('runs TypeScript (erasable syntax), captures output in order, returns the value', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          interface Point { x: number; y: number }
-          const p: Point = { x: 1, y: 2 } as Point;
-          console.log('point', p);
-          process.stdout.write('raw-out\\n');
-          console.warn('careful');
-          return p.x + p.y;
-        `,
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe(3)
-      expect(result.logs).toEqual(['point { x: 1, y: 2 }', 'raw-out\n', 'careful'])
-    })
-
-    it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => {
-      const { runtime } = await setup()
-      const calls: unknown[] = []
-      const result = await runtime.run({
-        program: `
-          const first = await tools.echo({ n: 1 });
-          let caught = {};
-          try { await tools.fail({}) } catch (error) { caught = { isTyped: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message } }
-          let caughtRaw = {};
-          try { await tools.failRaw({}) } catch (error) { caughtRaw = { name: error.name, toolName: error.toolName, message: error.message } }
-          return { first, caught, caughtRaw };
-        `,
-        bindings: workerRuntimeTools({
-          echo: async (args) => { calls.push(args); return { echoed: args } },
-          fail: async () => { throw new Error('nope') },
-          // A non-Error throw: the host renders it, the program still catches.
-          failRaw: async () => { throw 'raw-nope' },
-        }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toEqual({
-        first: { echoed: { n: 1 } },
-        caught: { isTyped: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
-        caughtRaw: { name: 'ToolCallError', toolName: 'failRaw', message: 'raw-nope' },
-      })
-      expect(calls).toEqual([{ n: 1 }])
-    })
-
-    it('materializes a typed rejection from a generic namespace descriptor', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          try { await helpers.fail({}) } catch (error) {
-            return {
-              isTyped: error instanceof HelperCallError,
-              name: error.name,
-              helperName: error.helperName,
-              message: error.message,
-            };
-          }
-        `,
-        bindings: [{
-          global: 'helpers',
-          functions: { fail: async () => { throw new Error('nope') } },
-          errorClass: { name: 'HelperCallError', memberNameProperty: 'helperName' },
-        }],
-      })
-      expect(result.value).toEqual({
-        isTyped: true,
-        name: 'HelperCallError',
-        helperName: 'fail',
-        message: 'nope',
-      })
-    })
-
-    it('bridges a deeply nested lossless JSON argument, resolution, and completion', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          let value = 'leaf';
-          for (let depth = 0; depth < 3_000; depth++) value = [value];
-          return await tools.echo(value);
-        `,
-        bindings: workerRuntimeTools({ echo: async args => args }),
-      })
-
-      expect(result.error).toBeUndefined()
-      let cursor = result.value
-      for (let depth = 0; depth < 3_000; depth++) {
-        expect(Array.isArray(cursor)).toBe(true)
-        cursor = Array.isArray(cursor) ? cursor[0] : undefined
-      }
-      expect(cursor).toBe('leaf')
-    }, 15_000)
-
-    it('reports non-erasable syntax as an exception without spawning a worker', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
-      expect(result.error?.kind).toBe('exception')
-      expect(result.error?.message).toMatch(/enum|strip/i)
-    })
-
-    it('reports a runtime throw as an exception with the message', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'throw new Error("kaboom")', bindings: [] })
-      expect(result.error?.kind).toBe('exception')
-      expect(result.error?.message).toContain('kaboom')
-    })
-
-    it('gives the program an EMPTY environment', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return JSON.stringify(process.env)', bindings: [] })
-      expect(result.value).toBe('{}')
-    })
-
-    it('rejects a non-lossless completion instead of replacing it with rendered text', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return { f: () => 1 }', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'invalid-output', message: 'program completion must be lossless JSON' })
-    })
-
-    it('completes a program that returns nothing with no value at all', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'const x = 1', bindings: [] })
-      expect(result.error).toBeUndefined()
-      expect('value' in result).toBe(false)
-    })
-
-    it('keeps logs streamed before a failure', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'console.log("before"); throw new Error("after-log")',
-        bindings: [],
-      })
-      expect(result.error?.kind).toBe('exception')
-      expect(result.logs).toContain('before')
-    })
-  })
-
-  describe(`${label} — budgets and containment (real workers)`, () => {
-    it('ends a hot loop at the compute budget — including behind a pending decoy dispatch', async () => {
-      const { runtime } = await setup({ computeMs: 300, maxWallMs: 30_000 })
-      const result = await runtime.run({
-        // The decoy: fire a call at a never-resolving binding WITHOUT awaiting,
-        // then spin. Host-side pending-call bookkeeping would pause a naive
-        // budget here; measured busy time cannot be fooled.
-        program: 'void tools.slow({}); for (;;) {}',
-        bindings: workerRuntimeTools({ slow: () => new Promise(() => {}) }),
-      })
-      expect(result.error?.kind).toBe('timeout')
-      expect(result.error?.message).toContain('compute budget')
-    }, 15_000)
-
-    it('does not charge time spent awaiting a slow binding against the compute budget', async () => {
-      // Keep the binding delay above the compute allowance while leaving enough
-      // headroom for worker bootstrap on loaded CI hosts.
-      const { runtime } = await setup({ computeMs: 1_000, maxWallMs: 30_000 })
-      const result = await runtime.run({
-        program: 'return await tools.slow({})',
-        bindings: workerRuntimeTools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 1_500)) }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('slow-done')
-    }, 15_000)
-
-    it('ends an idle-forever run at the wall-clock ceiling', async () => {
-      const { runtime } = await setup({ computeMs: 30_000, maxWallMs: 400 })
-      const result = await runtime.run({
-        program: 'await tools.never({}); return 1',
-        bindings: workerRuntimeTools({ never: () => new Promise(() => {}) }),
-      })
-      expect(result.error?.kind).toBe('timeout')
-      expect(result.error?.message).toContain('wall-clock ceiling')
-    }, 15_000)
-
-    it('reports an abort mid-run and stops the worker', async () => {
-      const { runtime } = await setup()
-      const controller = new AbortController()
-      setTimeout(() => { controller.abort('user-cancel') }, 150)
-      const result = await runtime.run({ program: 'for (;;) {}', bindings: [], signal: controller.signal })
-      expect(result.error).toEqual({ kind: 'abort', message: 'user-cancel' })
-    }, 15_000)
-
-    it('reports a pre-aborted signal without spawning', async () => {
-      const { runtime } = await setup()
-      const controller = new AbortController()
-      controller.abort('too-late')
-      const result = await runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
-      expect(result.error).toEqual({ kind: 'abort', message: 'too-late' })
-    })
-
-    it('applies the outer-output cap to failures before worker startup', async () => {
-      const capped = await setup({ maxOutputBytes: 64 })
-      const controller = new AbortController()
-      controller.abort('A'.repeat(1_000))
-      const aborted = await capped.runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
-      expect(aborted).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
-
-      const minimal = await setup({ maxOutputBytes: 4 })
-      const invalid = await minimal.runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
-      expect(invalid.error?.kind).toBe('output-limit')
-      expect(Buffer.byteLength(JSON.stringify(invalid.logs), 'utf8') + Buffer.byteLength(JSON.stringify(invalid.error?.message), 'utf8')).toBeLessThanOrEqual(4)
-    })
-
-    it('drops a binding resolution that lands after the run settled', async () => {
-      const { runtime } = await setup()
-      const controller = new AbortController()
-      let replyDelivered!: Promise<void>
-      const result = await runtime.run({
-        program: 'void tools.late({}); for (;;) {}',
-        bindings: workerRuntimeTools({
-          // Anchored on invocation: abort 100ms after the call reaches the
-          // host, resolve 400ms after — by then the run has settled, so the
-          // resolution's reply hits the post-settlement drop.
-          late: () => new Promise((resolve) => {
-            setTimeout(() => { controller.abort('cancel-now') }, 100)
-            replyDelivered = new Promise(done => setTimeout(() => { resolve('too-late'); done() }, 400))
-          }),
-        }),
-        signal: controller.signal,
-      })
-      expect(result.error).toEqual({ kind: 'abort', message: 'cancel-now' })
-      // Let the late resolution actually fire so its reply executes instead of
-      // being cancelled with the test.
-      await replyDelivered
-    }, 15_000)
-
-    it('contains an OOM under resourceLimits as worker-exit, host process healthy', async () => {
-      const { runtime } = await setup({ maxOldGenerationSizeMb: 32 })
-      const result = await runtime.run({
-        program: 'const hog = []; for (;;) hog.push(new Array(1e6).fill(1));',
-        bindings: [],
-      })
-      expect(result.error?.kind).toBe('worker-exit')
-      // And the host is fine: run something else.
-      const after = await runtime.run({ program: 'return "alive"', bindings: [] })
-      expect(after.value).toBe('alive')
-    }, 30_000)
-
-    it('reports a worker that exits before publishing a completion', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'process.exit(7)', bindings: [] })
-      expect(result).toEqual({
-        logs: [],
-        error: { kind: 'worker-exit', message: 'worker exited with code 7 before completing' },
-      })
-    })
-
-    it('fails runaway log output explicitly while retaining a bounded prefix', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 300 })
-      const result = await runtime.run({
-        program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1',
-        bindings: [],
-      })
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 300 bytes' })
-      expect(result.value).toBeUndefined()
-      expect(result.logs.length).toBeGreaterThan(0)
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(300)
-    })
-
-    it('retains a fitting prefix when one oversized log is the first output', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 96 })
-      const result = await runtime.run({
-        program: 'console.log(`start-${`😀"\\\\\\n`.repeat(100)}`); return null',
-        bindings: [],
-      })
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 96 bytes' })
-      expect(result.logs).toHaveLength(1)
-      expect(result.logs[0]?.startsWith('start-')).toBe(true)
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
-        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(96)
-    })
-
-    it('fails an oversized return value without substituting a string', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({ program: 'return "y".repeat(10_000)', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
-    })
-
-    it('uses UTF-8 serialized bytes at the exact completion boundary', async () => {
-      const exact = await setup({ maxOutputBytes: 7 })
-      const exactResult = await exact.runtime.run({ program: 'return "€"', bindings: [] })
-      // [] costs two bytes and JSON serialization of "€" costs five.
-      expect(exactResult).toEqual({ logs: [], value: '€' })
-
-      const over = await setup({ maxOutputBytes: 6 })
-      const overResult = await over.runtime.run({ program: 'return "€"', bindings: [] })
-      expect(overResult.error?.kind).toBe('output-limit')
-    })
-
-    it('accounts logs and completion in one exact combined ledger', async () => {
-      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
-      const exact = await setup({ maxOutputBytes: 11 })
-      expect(await exact.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] }))
-        .toEqual({ logs: ['abc'], value: 'xy' })
-
-      const over = await setup({ maxOutputBytes: 10 })
-      const result = await over.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error?.kind).toBe('output-limit')
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8') + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
-    })
-
-    it('accounts logs and exception diagnostics before the worker port boundary', async () => {
-      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
-      const exact = await setup({ maxOutputBytes: 11 })
-      expect(await exact.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] }))
-        .toEqual({ logs: ['abc'], error: { kind: 'exception', message: 'xy' } })
-
-      const over = await setup({ maxOutputBytes: 10 })
-      const result = await over.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] })
-      expect(result.error?.kind).toBe('output-limit')
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
-        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
-    })
-
-    it('does not send a giant Error stack across the worker port', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({
-        program: 'throw new Error("x".repeat(1_000_000))',
-        bindings: [],
-      })
-      expect(result).toEqual({
-        logs: [],
-        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
-      })
-    })
-
-    it('completes a program that awaits its write callback, capturing the chunk', async () => {
-      // Node's write(chunk[, encoding][, callback]) contract: dropping the
-      // callback would leave this promise pending until the wall ceiling and
-      // misreport a completed program as a timeout.
-      const { runtime } = await setup({ maxWallMs: 2_000 })
-      const result = await runtime.run({
-        program: 'await new Promise(resolve => process.stdout.write("flushed", resolve)); return "done"',
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('done')
-      expect(result.logs).toContain('flushed')
-    })
-
-    it('returns a large JSON container exactly when the outer cap permits it', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return new Array(50_000).fill(7)', bindings: [] })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toEqual(new Array(50_000).fill(7))
-    })
-
-    it('returns an exact completion at the default 64 MiB combined boundary', async () => {
-      const { runtime } = await setup()
-      // [] costs two bytes and the JSON string contributes two quotes, leaving
-      // exactly this many payload bytes under the 67_108_864-byte default.
-      const result = await runtime.run({ program: 'return "x".repeat(67_108_860)', bindings: [] })
-      expect(result.error).toBeUndefined()
-      expect(result.logs).toEqual([])
-      expect(result.value).toHaveLength(67_108_860)
-    }, 60_000)
-
-    it('fails one byte over the default 64 MiB combined boundary', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return "x".repeat(67_108_861)', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' })
-    }, 60_000)
-
-    it('drains pipe output queued before terminal worker teardown completes', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 200_000 })
-      const payload = `late-pipe-${'x'.repeat(100_000)}`
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text);
-          write('late-pipe-' + 'x'.repeat(100_000));
-          parentPort.postMessage({ type: 'done', value: ['done'] });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('done')
-      expect(result.logs.join('') === payload).toBe(true)
-    }, 15_000)
-  })
-
-  describe(`${label} — hostile programs (real workers)`, () => {
-    it('survives forged port traffic: unknown binding names, duplicate ids, junk shapes', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
-          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
-          parentPort.postMessage({ type: 'call', id: 7778, global: 'tools', name: 'constructor', args: {} });
-          parentPort.postMessage({ type: 'junk' });
-          return await tools.real({});
-        `,
-        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('still-works')
-    })
-
-    it('survives arbitrary junk on the port: non-objects, junk types, malformed calls, logs, and dones', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          for (const junk of [
-            null, 42, 'junk', [],
-            { type: 'nope' },
-            { type: 'call' },
-            { type: 'call', id: 'x', global: 'tools', name: 'real', args: {} },
-            { type: 'call', id: 1e9, global: 7, name: 'real', args: {} },
-            { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} },
-            { type: 'log' },
-            { type: 'log', text: null },
-            { type: 'log', text: 7 },
-            { type: 'log', text: {} },
-            { type: 'done', error: 5 },
-            { type: 'done', error: { kind: 'exception', message: 5 } },
-            { type: 'done', error: { kind: 'invented', message: 'bad kind' } },
-          ]) parentPort.postMessage(junk);
-          return await tools.real({});
-        `,
-        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('still-works')
-      expect(result.logs).toEqual([])
-    })
-
-    it('ignores forged controller-only failure classifications', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          for (const kind of ['abort', 'timeout', 'worker-exit']) {
-            parentPort.postMessage({ type: 'done', error: { kind, message: 'forged ' + kind } });
-          }
-          return 'honest';
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], value: 'honest' })
-    })
-
-    it('fails forged log floods and forged done values through the same outer cap', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 200 })
-      const result = await runtime.run({
-        // Forged messages bypass worker-side capture and completion checks;
-        // the outer ledger must still contain them.
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', text: 'F'.repeat(100), forged: true });
-          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100000)] });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 200 bytes' })
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(200)
-    })
-
-    it('re-caps an oversized forged done value at the host boundary', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100_000)] });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({
-        logs: [],
-        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
-      })
-    })
-
-    it('drops a malformed forged done carrying both value and error', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', value: 'lied', error: { kind: 'exception', message: 'fake failure' } });
-          return 'honest';
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], error: { kind: 'exception', message: 'fake failure' } })
-    })
-
-    it('contains a deeply nested forged completion without overflowing the host meter', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          const value = [];
-          for (let depth = 0; depth < 3_000; depth++) value.push({ kind: 'array', length: 1 });
-          value.push(null);
-          setTimeout(() => { parentPort.postMessage({ type: 'done', value }) }, 25);
-          // Prevent bootstrap's normal undefined completion from racing the forged terminal.
-          await new Promise(() => {});
-        `,
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      let value = result.value
-      let depth = 0
-      while (Array.isArray(value)) {
-        expect(value).toHaveLength(1)
-        value = value[0]
-        depth += 1
-      }
-      expect(depth).toBe(3_000)
-      expect(value).toBeNull()
-    }, 15_000)
-
-    it('turns forged over-limit error text into output-limit at the host', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', error: { kind: 'exception', message: '€'.repeat(1000) } });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
-    })
-
-    it('answers a binding whose resolution is not lossless JSON with a typed failure reply', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
-        bindings: workerRuntimeTools({ bad: async () => (() => 1) }),
-      })
-      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
-    })
-
-    it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
-      const { runtime } = await setup()
-      let calls = 0
-      const result = await runtime.run({
-        program: `
-          const decorated = [1]; Object.defineProperty(decorated, 'extra', { value: true });
-          const values = [new Date(), decorated, () => 1];
-          const failures = [];
-          for (const value of values) {
-            try { await tools.never(value) } catch (error) {
-              failures.push({ typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message });
-            }
-          }
-          return failures;
-        `,
-        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
-      })
-      expect(calls).toBe(0)
-      expect(result.value).toEqual(new Array(3).fill({
-        typed: true,
-        name: 'ToolCallError',
-        toolName: 'never',
-        message: 'binding arguments must be lossless JSON',
-      }))
-    })
-
-    it('rejects intrinsic-looking exotic objects as arguments and completions', async () => {
-      const { runtime } = await setup()
-      let calls = 0
-      const forgeObject = `
-        const prototype = Object.create(null);
-        const SpoofedObject = function Object() {};
-        SpoofedObject.prototype = prototype;
-        Object.defineProperty(prototype, 'constructor', { value: SpoofedObject });
-        const forged = Object.assign(Object.create(prototype), { value: 1 });
-        Function.prototype.toString = () => 'function Object() { [native code] }';
-      `
-      const argument = await runtime.run({
-        program: `${forgeObject}
-          try { await tools.never(forged) } catch (error) {
-            return { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
-          }
-        `,
-        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
-      })
-      expect(calls).toBe(0)
-      expect(argument.value).toEqual({
-        typed: true,
-        name: 'ToolCallError',
-        toolName: 'never',
-        message: 'binding arguments must be lossless JSON',
-      })
-
-      const completion = await runtime.run({ program: `${forgeObject}\nreturn forged`, bindings: [] })
-      expect(completion).toEqual({
-        logs: [],
-        error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' },
-      })
-    })
-
-    it('preserves binding and completion JSON after model code mutates boundary globals', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const arrayPrototype = Array.prototype;
-          const objectPrototype = Object.prototype;
-          const setPrototype = Set.prototype;
-          const stringPrototype = String.prototype;
-          Array.isArray = () => false;
-          arrayPrototype.at = arrayPrototype.includes = arrayPrototype.pop = arrayPrototype.push = () => { throw new Error('mutated array method') };
-          Object.defineProperty = Object.getOwnPropertyDescriptor = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') };
-          Object.hasOwn = () => false;
-          Object.is = () => true;
-          objectPrototype.propertyIsEnumerable = () => false;
-          Number.isFinite = Number.isSafeInteger = () => false;
-          Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') };
-          setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') };
-          stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') };
-          Buffer.byteLength = () => 0;
-          Function.prototype.toString = () => 'mutated';
-          objectPrototype.get = () => undefined;
-          objectPrototype.constructor = arrayPrototype.constructor = null;
-          globalThis.Array = globalThis.Buffer = globalThis.Error = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Reflect = globalThis.Set = globalThis.String = undefined;
-          const echoed = await tools.echo({ request: ['€', 1] });
-          let failure;
-          try { await tools.fail({}) } catch (error) {
-            failure = { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
-          }
-          return { echoed, failure, completion: { ok: true, amount: 42 } };
-        `,
-        bindings: workerRuntimeTools({ echo: async args => args, fail: async () => { throw new Error('nope') } }),
-      })
-      expect(result).toEqual({
-        logs: [],
-        value: {
-          echoed: { request: ['€', 1] },
-          failure: { typed: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
-          completion: { ok: true, amount: 42 },
-        },
-      })
-    })
-
-    it('rejects forged lossy binding arguments again at the host boundary', async () => {
-      const { runtime } = await setup()
-      let calls = 0
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          const forged = (id, args) => new Promise((resolve) => {
-            const receive = (message) => {
-              if (message?.type !== 'reply' || message.id !== id) return;
-              parentPort.off('message', receive);
-              resolve(message);
-            };
-            parentPort.on('message', receive);
-            parentPort.postMessage({ type: 'call', id, global: 'tools', name: 'never', args });
-          });
-          const sparse = []; sparse.length = 1;
-          const cycle = {}; cycle.self = cycle;
-          return await Promise.all([
-            forged(8001, new Date()),
-            forged(8002, -0),
-            forged(8003, sparse),
-            forged(8004, cycle),
-          ]);
-        `,
-        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
-      })
-      expect(calls).toBe(0)
-      expect(result.value).toEqual([8001, 8002, 8003, 8004].map(id => ({
-        type: 'reply',
-        id,
-        ok: false,
-        message: 'binding arguments must be lossless JSON',
-      })))
-    })
-
-    it('contains throwing getters while snapshotting binding resolutions', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
-        bindings: workerRuntimeTools({ bad: async () => Object.defineProperty({}, 'bad', { enumerable: true, get() { throw new Error('getter exploded') } }) }),
-      })
-      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
-    })
-
-    it('revalidates a forged lossy completion at the host boundary', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', value: -0 });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
-    })
-
-    it('honors a forged worker-side output-limit signal', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'output-limit' });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' } })
-    })
-
-    it('exposes binding names that collide with Object.prototype as ordinary functions', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'return [await tools["__proto__"]({}), await tools["constructor"]({}), typeof tools["hasOwnProperty"]]',
-        // Computed keys: a literal `'__proto__': …` entry would SET the record's
-        // prototype instead of declaring a binding of that name.
-        bindings: workerRuntimeTools({ ['__proto__']: async () => 'proto-ok', ['constructor']: async () => 'ctor-ok' }),
-      })
-      expect(result.value).toEqual(['proto-ok', 'ctor-ok', 'undefined'])
-    })
-  })
-
-  describe(`${label} — seam misuse and lifecycle`, () => {
-    it('rejects invalid and duplicate binding globals loudly', async () => {
-      const { runtime } = await setup()
-      const cases: [string, RegExp][] = [
-        ['not valid!', /not a usable identifier/],
-        ['await', /not a usable identifier/],
-        ['console', /duplicate binding global/],
-      ]
-      for (const [global, message] of cases) {
-        await expect(runtime.run({ program: 'return 1', bindings: [{ global, functions: {} }] })).rejects.toThrow(message)
-      }
-      await expect(runtime.run({
-        program: 'return 1',
-        bindings: [{ global: 'tools', functions: {} }, { global: 'tools', functions: {} }],
-      })).rejects.toThrow(/duplicate binding global/)
-
-      await expect(runtime.run({
-        program: 'return typeof ToolCallError',
-        bindings: [{ global: 'ToolCallError', functions: {} }],
-      })).resolves.toMatchObject({ value: 'object' })
-    })
-
-    it('rejects malformed or colliding binding error-class declarations', async () => {
-      const { runtime } = await setup()
-      const run = async (bindings: CodeBindingNamespace[]) => await runtime.run({ program: 'return 1', bindings })
-      const namespace = (global: string, name: string, memberNameProperty = 'memberName'): CodeBindingNamespace => ({
-        global,
-        functions: {},
-        errorClass: { name, memberNameProperty },
-      })
-
-      await expect(run([namespace('tools', 'not valid!')])).rejects.toThrow(/error class.*not a usable identifier/)
-      await expect(run([namespace('tools', 'await')])).rejects.toThrow(/error class.*not a usable identifier/)
-      await expect(run([namespace('tools', 'console')])).rejects.toThrow(/duplicate injected global/)
-      await expect(run([namespace('tools', 'tools')])).rejects.toThrow(/duplicate injected global/)
-      await expect(run([
-        namespace('tools', 'CallError'),
-        namespace('helpers', 'CallError'),
-      ])).rejects.toThrow(/duplicate injected global/)
-      await expect(run([namespace('tools', 'CallError', '')])).rejects.toThrow(/member property.*not usable/)
-      await expect(run([namespace('tools', 'CallError', 'message')])).rejects.toThrow(/member property.*not usable/)
-    })
-
-    it('rejects config values that are not positive numbers', async () => {
-      await expect(setup({ computeMs: -1 })).rejects.toThrow(/positive number/)
-    })
-
-    it('rejects a maxWallMs above Node\'s maximum timer delay', async () => {
-      // setTimeout clamps a delay past 2^31-1 ms to 1 ms, so the positivity check
-      // alone would accept a 25-day ceiling that expires on the first tick.
-      await expect(setup({ maxWallMs: 2_147_483_648 }))
-        .rejects.toThrow(/maxWallMs must be at most 2147483647/)
-      // The boundary itself is usable.
-      await expect(setup({ maxWallMs: 2_147_483_647 })).resolves.toBeTruthy()
-    })
-
-    it('requires maxOutputBytes to fit the smallest counted outer payloads', async () => {
-      await expect(setup({ maxOutputBytes: 3 })).rejects.toThrow(/safe integer of at least 4/)
-      await expect(setup({ maxOutputBytes: 4.5 })).rejects.toThrow(/safe integer of at least 4/)
-    })
-
-    it('keeps runs isolated: no state survives from one run to the next', async () => {
-      const { runtime } = await setup()
-      await runtime.run({ program: 'globalThis.leak = "value"; return 1', bindings: [] })
-      const second = await runtime.run({ program: 'return typeof globalThis.leak', bindings: [] })
-      expect(second.value).toBe('undefined')
-    })
-
-    it('disposal aborts in-flight runs, awaits worker exit, and rejects later runs', async () => {
-      const { runtime, dispose } = await setup()
-      const inflight: Promise<CodeRunResult> = runtime.run({ program: 'for (;;) {}', bindings: [] })
-      // Give the worker a moment to actually start spinning.
-      await new Promise(resolve => setTimeout(resolve, 200))
-      await dispose()
-      const result = await inflight
-      expect(result.error).toEqual({ kind: 'abort', message: 'runtime disposed' })
-      await expect(runtime.run({ program: 'return 1', bindings: [] })).rejects.toThrow(/after disposal/)
-    }, 15_000)
-  })
-}
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index af424b8809..0ebb5bd4af 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: 5ea1ae3681f9340cfba798e659f454d6d05fdbfe
-README.zh.md: 4e1cb9472d6e90062ecde61db4200a79a56b16f1
+README.md: f2b19436da40feb14d067e2cfc706222625680b5
+README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index 5ea1ae3681..f2b19436da 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: canonical cwd, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: execution-world coordinates and executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 4e1cb9472d..938312448d 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：规范化 cwd、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 8b668b43f6..ee90e9e607 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 4892ad49e571662b833b1dd6d64dc966f343ae3c
-README.zh.md: ca0df5ff18e9feb992cc3f6d0db90dc06cb275d8
+README.md: 85103c2634bd35b188acd71c7f037e3678a2542e
+README.zh.md: 505eac4f2650e6723e042cdb1122f9ef504ad7df
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 13b51ec6d1..c211ca26f1 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
+Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
 
 ## Behavior (and where it came from)
 
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Execution-world coordinates** — `cwd` is the host process cwd, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index ca0df5ff18..505eac4f26 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md) 和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
 
 ## 行为（以及设计来源）
 
@@ -10,7 +10,7 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **执行世界坐标**：`cwd` 是宿主进程 cwd，`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索。
+- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 262a2567b8..4a740a1e3b 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -33,7 +33,6 @@ import { LocalTerminalHandle } from './terminal.ts'
  * SIGTERM→grace→SIGKILL escalation.
  */
 export class LocalSubprocessService extends SubprocessService {
-  readonly cwd = process.cwd()
   /** Live handles retained only so disposal can terminate and join them. */
   private live = new Set<SubprocessHandle>()
   /** Live terminal sessions retained through whole-session quiescence. */
@@ -103,7 +102,7 @@ export class LocalSubprocessService extends SubprocessService {
       ? (environmentValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
-      extensions.map(extension => resolve(this.cwd, directory, command + extension)))
+      extensions.map(extension => resolve(process.cwd(), directory, command + extension)))
   }
 
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index e74927448d..a0455edef0 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -31,9 +31,6 @@ describe('LocalSubprocessService', () => {
     expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
       PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
     })).toBe(process.execPath)
-    Reflect.set(ctx.subprocess, 'cwd', dirname(process.execPath))
-    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), { PATH: '' }))
-      .toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index d12516f11f..e67bf1a87f 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 08fb03d6f145c1026180d92de2421b647cb3ebbe
-README.zh.md: 592fc83223092b3406e9070e11de2b20a63232a6
+README.md: ec4a4e3328a5a600441d2e7983b3844f4ccc5e91
+README.zh.md: 3da79995fad9a2c8f2a6020ae18152a0e4459c71
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 08fb03d6f1..ec4a4e3328 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -2,12 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
+The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
 
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- `cwd` and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
+- Spawn working directories and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 592fc83223..3da79995fa 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,12 +2,12 @@
 
 [English](README.md) | 中文
 
-子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- `cwd` 和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index df3186c9b0..14866c9784 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * The subprocess seam (`ctx.subprocess`): execution-world process coordinates,
- * executable lookup, fully specified managed process trees with raw or
+ * The subprocess seam (`ctx.subprocess`): execution-world executable lookup,
+ * fully specified managed process trees with raw or
  * collected stdio, and one terminal-process primitive. Command defaulting,
  * shell semantics, deadlines, protocol framing, terminal readiness, and
  * presentation belong to consumers. The local implementation lives in
@@ -78,8 +78,8 @@ declare module 'cordis' {
  * duplicate-service behavior).
  *
  * Implementations must honor these semantics:
- * - {@link cwd} and executable paths belong to one execution world shared
- *   with the mounted filesystem provider.
+ * - Executable paths belong to one execution world shared with the mounted
+ *   filesystem provider.
  * - {@link spawn} returns immediately with a live handle; `done` resolves at
  *   process close with exit facts and rejects only for spawn-level failures.
  * - Collect-mode readers are offset-based and non-consuming, so independent
@@ -104,9 +104,6 @@ export abstract class SubprocessService extends Service {
     super(ctx, 'subprocess')
   }
 
-  /** Canonical default cwd in this provider's execution world. */
-  abstract readonly cwd: string
-
   /**
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index b20d5b5f3b..355b817e68 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -148,7 +148,6 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     'lib/invariant.js',
     ...manifest.bin ? ['lib/bin.js'] : [],
     ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
-    ...exportDefault(manifest, './runtime-host') === './lib/runtime-host.js' ? ['lib/runtime-host.js'] : [],
     // UI plugin packages ship their browser bundle beside the node lib
     // (single-artifact ruling: dist/ retired, ./client resolves lib/client.js).
     // Keyed on the artifact path, not the subpath name: apiproxy's ./client is
diff --git a/scripts/gen-code-runtime-runner.ts b/scripts/gen-code-runtime-runner.ts
deleted file mode 100644
index 7e856e7651..0000000000
--- a/scripts/gen-code-runtime-runner.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-/** Generate the subprocess Code Runtime's dependency-free runner bundle. */
-
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { build } from 'tsdown'
-
-const root = resolve(import.meta.dirname, '..')
-const ENTRY = 'packages/code-runtime/code-runtime-subprocess/src/runner.ts'
-const OUT = 'packages/code-runtime/code-runtime-subprocess/src/runner-source.generated.ts'
-
-/**
- * Bundle the typed runner and shared worker implementation into one source literal.
- * @returns generated TypeScript module consumed by the subprocess backend.
- */
-export async function renderCodeRuntimeRunner(): Promise<string> {
-  const bundles = await build({
-    config: false,
-    entry: [resolve(root, ENTRY)],
-    format: ['esm'],
-    platform: 'node',
-    target: 'es2024',
-    write: false,
-    dts: false,
-    clean: false,
-    minify: true,
-    logLevel: 'silent',
-    report: false,
-    deps: { alwaysBundle: ['@deepseek-ai/dsh-code-runtime-worker'] },
-  })
-  try {
-    const chunks = bundles.flatMap(bundle => bundle.chunks).filter(chunk => chunk.type === 'chunk')
-    if (chunks.length !== 1) throw new Error(`gen-code-runtime-runner: expected one chunk, received ${chunks.length}`)
-    const chunk = chunks[0]
-    if (chunk === undefined) throw new Error('gen-code-runtime-runner: runner chunk is missing')
-    const external = chunk.imports.filter(specifier => !specifier.startsWith('node:'))
-    if (external.length > 0) {
-      throw new Error(`gen-code-runtime-runner: runner retained external imports: ${external.join(', ')}`)
-    }
-    return [
-      '/**',
-      ' * Generated dependency-free execution-world runner.',
-      ' * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.',
-      ' */',
-      '',
-      `export const CODE_RUNNER_SOURCE = ${JSON.stringify(chunk.code)}`,
-      '',
-    ].join('\n')
-  } finally {
-    await Promise.all(bundles.map(async (bundle) => { await bundle[Symbol.asyncDispose]() }))
-  }
-}
-
-async function main(): Promise<void> {
-  const content = await renderCodeRuntimeRunner()
-  const output = resolve(root, OUT)
-  if (process.argv.includes('--check')) {
-    const committed = existsSync(output) ? readFileSync(output, 'utf8') : null
-    if (committed === content) {
-      console.log(`gen-code-runtime-runner: ${OUT} is up to date.`)
-      return
-    }
-    console.error(`gen-code-runtime-runner: ${OUT} is stale. Run \`pnpm run gen-code-runtime-runner\` and commit it.`)
-    process.exitCode = 1
-    return
-  }
-  writeFileSync(output, content)
-  console.log(`gen-code-runtime-runner: wrote ${OUT}.`)
-}
-
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) await main()
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 7be0e1fa58..00520bdbe7 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -48,13 +48,9 @@ interface EventRelation {
   listeners: Set<string>
 }
 
-/** One scanned package source file and its owning package short name. */
-export interface PackageSource {
-  /** Repository-relative path. */
+interface PackageSource {
   rel: string
-  /** Package short name from the `packages/<group>/<pkg>/src` path. */
   pkg: string
-  /** The bound program source file. */
   sourceFile: ts.SourceFile
 }
 
@@ -124,7 +120,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -159,24 +155,6 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
-  {
-    key: 'settings',
-    pkg: 'settings',
-    title: 'User-settings seam',
-    mode: 'seam',
-    implementations: ['settings-local'],
-    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
-    note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer.',
-  },
-  {
-    key: 'credentials',
-    pkg: 'credentials',
-    title: 'Credential seam',
-    mode: 'seam',
-    implementations: ['credentials-local'],
-    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
-    note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage.',
-  },
   {
     key: 'telemetry',
     pkg: 'session-telemetry',
@@ -225,6 +203,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session-reference',
     title: 'Cross-session snapshot preparation',
     mode: 'core',
+    consumers: ['tui'],
     note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
   },
   {
@@ -256,7 +235,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'user-interaction',
     title: 'Human question/answer seam',
     mode: 'seam',
-    consumers: ['tool-ask-user'],
+    implementations: ['tui'],
+    consumers: ['tool-ask-user', 'tui'],
     note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
   },
   {
@@ -271,7 +251,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'commands',
     title: 'Human command registry',
     mode: 'core',
-    note: 'Plugins register direct human commands without sending invocations to the model.',
+    consumers: ['tui'],
+    note: 'Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model.',
   },
   {
     key: 'sessionProjections',
@@ -289,12 +270,19 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['host-apiproxy'],
     note: 'Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs.',
   },
+  {
+    key: 'tui',
+    pkg: 'tui',
+    title: 'Mounted-terminal interaction service',
+    mode: 'bundle',
+    note: 'One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state.',
+  },
   {
     key: 'skills',
     pkg: 'skill',
     title: 'Skill provider registry',
     mode: 'seam',
-    implementations: ['skill-badge', 'skill-local'],
+    implementations: ['skill-local'],
     consumers: ['tool-skill'],
     note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
   },
@@ -303,7 +291,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'agent',
     title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
+    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
   {
@@ -327,25 +315,24 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Subprocess seam',
     mode: 'seam',
     implementations: ['subprocess-local'],
-    consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
-    note: 'The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
+    consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp'],
+    note: 'The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
   },
   {
     key: 'bash',
     pkg: 'bash',
     title: 'Bash executor seam',
     mode: 'seam',
-    implementations: ['bash-local', 'bash-sandbox', 'pwsh-local'],
-    consumers: ['tool-bash', 'tool-pwsh', 'hooks-claude', 'hooks-codex'],
-    note: 'The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them.',
+    implementations: ['bash-local', 'bash-sandbox'],
+    consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
+    note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them.',
   },
   {
     key: 'bashEnv',
-    pkg: 'bash-env',
+    pkg: 'tool-bash',
     title: 'Managed bash environment registry',
     mode: 'core',
-    consumers: ['tool-bash', 'tool-pwsh'],
-    note: 'Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace.',
+    note: 'Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace.',
   },
   {
     key: 'pty',
@@ -422,11 +409,11 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'subagents',
     pkg: 'subagent',
-    title: 'Subagent provider and continuation service',
+    title: 'Subagent provider registry',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
-    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
-    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
+    consumers: ['tool-subagent', 'tool-ralph'],
+    note: 'Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route.',
   },
   {
     key: 'tasks',
@@ -605,8 +592,7 @@ function parseExampleCordis(rel: string): ExamplePlugin[] {
     if (current?.name) plugins.push({ id: current.id, name: current.name })
   }
   for (const line of text.split('\n')) {
-    // Top-level rows (`- id:`) and bundle-patch insert rows (`    - id:`).
-    const id = /^\s*-\s+id:\s+(.+?)\s*$/.exec(line)
+    const id = /^-\s+id:\s+(.+?)\s*$/.exec(line)
     if (id?.[1] !== undefined) {
       flush()
       current = { id: stripYamlScalar(id[1]) }
@@ -625,20 +611,28 @@ function stripYamlScalar(value: string): string {
 
 const APP_EXAMPLES = [
   {
-    id: 'dsh_base',
-    rel: 'apps/cli/composition.md',
-    title: 'DSH Base Composition',
-    label: 'packages/bundle/base/cordis.patch.yml',
-    config: 'packages/bundle/base/cordis.patch.yml',
-    summary: 'The dsh-base bundle patch every profile applies first; mode bundles (dsh-web-app, dsh-headless) and the user\'s profile layer patch over it.',
+    id: 'tui',
+    rel: 'examples/tui-agent/composition.md',
+    title: 'TUI Agent App Composition',
+    label: 'examples/tui-agent',
+    config: 'examples/tui-agent/cordis.yml',
+    summary: 'The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package.',
   },
   {
     id: 'headless',
     rel: 'examples/headless-agent/composition.md',
-    title: 'Headless Agent Snapshot Composition',
+    title: 'Headless Agent App Composition',
     label: 'examples/headless-agent',
     config: 'examples/headless-agent/cordis.yml',
-    summary: 'The headless snapshot composition combines the real DeepSeek adapter and coding capabilities with one explicitly configured persisted top-level agent; its JSONL driver is test-only.',
+    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
+  },
+  {
+    id: 'cordis',
+    rel: 'examples/cordis-agent/composition.md',
+    title: 'Cordis Agent App Composition',
+    label: 'examples/cordis-agent',
+    config: 'examples/cordis-agent/cordis.yml',
+    summary: 'The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its current-process runtime and mount or unmount in-memory temporary Plugins.',
   },
   {
     id: 'acp',
@@ -657,7 +651,11 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
-  if (pluginName === '@deepseek-ai/dsh-acp-demo') {
+  if (pluginName === '@deepseek-ai/dsh-tui-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'tui')}["@deepseek-ai/dsh-tui<br/>pre-created main agent"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
   }
   lines.push(
@@ -683,7 +681,7 @@ function renderAppComposition(example: AppExample): string {
     const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-acp-demo') {
+    if (plugin.name === '@deepseek-ai/dsh-tui-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
       renderAppExpansion(lines, pluginNode, plugin.name)
     }
   }
@@ -700,26 +698,13 @@ function renderAppComposition(example: AppExample): string {
   return lines.join('\n')
 }
 
-type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
-
-/**
- * The only method names visitSource classifies; receiver typing runs on these
- * alone. Obligation: every method name matched by a branch inside visitSource
- * must appear here — the prefilter drops non-members before any branch runs,
- * so a branch for an unlisted name is silently dead.
- */
-const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
-
 /** Collect event dispatch/listener relations from real cross-file receiver types. */
-export class EventRelationCollector {
+class EventRelationCollector {
   private readonly relations = new Map<string, EventRelation>()
-  private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
-  private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
-  private globalCallSites: CallSiteIndex | null = null
+  private readonly callSites = new Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>()
   private readonly contextType: ts.Type
   private readonly agentDispatchType: ts.Type
   private readonly eventsServiceType: ts.Type
-  private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
 
   constructor(
     private readonly project: TypeScriptProject,
@@ -728,7 +713,7 @@ export class EventRelationCollector {
     this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
     this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
     this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
-    this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
+    this.indexCallSites()
   }
 
   /** Return all event relations discovered from the Program. */
@@ -748,88 +733,20 @@ export class EventRelationCollector {
     return this.project.checker.getDeclaredTypeOfSymbol(symbol)
   }
 
-  /** Index resolved function calls in the given files for narrow argument-flow recovery. */
-  private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
-    const index: CallSiteIndex = new Map()
+  /** Index resolved local function calls for narrow argument-flow recovery. */
+  private indexCallSites(): void {
     const visit = (node: ts.Node): void => {
       if (ts.isCallExpression(node)) {
         const declaration = this.project.checker.getResolvedSignature(node)?.declaration
         if (declaration) {
-          const calls = index.get(declaration) ?? []
+          const calls = this.callSites.get(declaration) ?? []
           calls.push(node)
-          index.set(declaration, calls)
+          this.callSites.set(declaration, calls)
         }
       }
       ts.forEachChild(node, visit)
     }
-    for (const file of files) visit(file)
-    return index
-  }
-
-  /**
-   * Return every indexed call resolving to one local helper declaration.
-   * Fast path: when every same-file reference to the non-exported helper is
-   * provably a direct callee, module scoping confines all of its calls to that
-   * file, so only that file is indexed. Any other reference shape may alias
-   * the function value outward, so the original full package-source index
-   * decides instead.
-   */
-  private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
-    if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
-      this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
-    }
-    if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
-    const file = owner.getSourceFile()
-    let index = this.fileCallSites.get(file)
-    if (!index) {
-      index = this.buildCallSiteIndex([file])
-      this.fileCallSites.set(file, index)
-    }
-    return index.get(owner) ?? []
-  }
-
-  /**
-   * Prove every same-file reference to one helper is a direct callee. The
-   * proof owns its premises: an exported helper or a helper in a global
-   * script file (no import/export means program-wide scope, callable from
-   * another file with no same-file reference at all) fails immediately.
-   * Alias escapes (re-export statements, default exports, value reads)
-   * resolve back to the owner symbol at a non-callee position and fail the
-   * proof, as does anything the scan cannot positively classify.
-   */
-  private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
-    const cached = this.localCalleeProofs.get(owner)
-    if (cached !== undefined) return cached
-    if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
-      this.localCalleeProofs.set(owner, false)
-      return false
-    }
-    const name = owner.name
-    const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
-    let proven = !!ownerSymbol
-    const refersToOwner = (identifier: ts.Identifier): boolean => {
-      // Shorthand properties resolve to the property symbol; ask for the value side.
-      const local = ts.isShorthandPropertyAssignment(identifier.parent)
-        ? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
-        : this.project.checker.getSymbolAtLocation(identifier)
-      if (!local) return false
-      const symbol = local.flags & ts.SymbolFlags.Alias
-        ? this.project.checker.getAliasedSymbol(local)
-        : local
-      return symbol === ownerSymbol
-    }
-    const visit = (node: ts.Node): void => {
-      if (!proven) return
-      if (ts.isIdentifier(node) && node !== name && node.text === name?.text
-        && !isDirectCallee(node) && refersToOwner(node)) {
-        proven = false
-        return
-      }
-      ts.forEachChild(node, visit)
-    }
-    visit(owner.getSourceFile())
-    this.localCalleeProofs.set(owner, proven)
-    return proven
+    for (const source of this.sources) visit(source.sourceFile)
   }
 
   /** Walk one package source file and classify event API calls by receiver type. */
@@ -843,7 +760,7 @@ export class EventRelationCollector {
               this.addDispatcher(name, source.pkg, 'emitAgentEvent')
             }
           }
-        } else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
+        } else if (ts.isPropertyAccessExpression(node.expression)) {
           const receiverKind = this.receiverKind(node.expression.expression)
           const method = node.expression.name.text
           if (receiverKind === 'events-service' && method === 'dispatch') {
@@ -946,7 +863,7 @@ export class EventRelationCollector {
     const index = owner.parameters.indexOf(parameter)
     if (index < 0) return new Set()
     const events = new Set<string>()
-    for (const call of this.callSitesFor(owner)) {
+    for (const call of this.callSites.get(owner) ?? []) {
       const argument = call.arguments[index]
       if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
     }
@@ -993,21 +910,6 @@ export class EventRelationCollector {
   }
 }
 
-/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
-function isDirectCallee(identifier: ts.Identifier): boolean {
-  let current: ts.Node = identifier
-  while (
-    ts.isParenthesizedExpression(current.parent)
-    || ts.isAsExpression(current.parent)
-    || ts.isTypeAssertionExpression(current.parent)
-    || ts.isNonNullExpression(current.parent)
-    || ts.isSatisfiesExpression(current.parent)
-  ) {
-    current = current.parent
-  }
-  return ts.isCallExpression(current.parent) && current.parent.expression === current
-}
-
 /** Peel syntax-only wrappers that do not change an expression's runtime value. */
 function unwrapExpression(expression: ts.Expression): ts.Expression {
   let current = expression
@@ -1063,22 +965,14 @@ function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
   return out
 }
 
-/**
- * Select the package source files of one project in deterministic order.
- * @param project - the loaded repository TypeScript project.
- * @returns `packages/<group>/<pkg>/src` files tagged with their package name.
- */
-export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
-  return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  const sources = project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
     const rel = project.relativePath(sourceFile)
     const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
     return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
   }).sort((left, right) => left.rel.localeCompare(right.rel))
-}
-
-function collectEventRelations(): Map<string, EventRelation> {
-  const project = new TypeScriptProject(root)
-  return new EventRelationCollector(project, collectPackageSources(project)).collect()
+  return new EventRelationCollector(project, sources).collect()
 }
 
 function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
@@ -1159,22 +1053,20 @@ function renderLifecycle(): string {
     '  participant Session',
     '  participant SDK as UI or SDK listener',
     '  User->>Agent: followup(content)',
-    `  Agent-->>SDK: ${mermaidCode('agent/inbox/spliced')}`,
-    `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
-    '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
-    `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
-    `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
-    `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
-    '  Hooks-->>Driver: authoritative reject or enter(messages)',
-    '  alt proposed step rejected or pre-step failed',
-    '    Driver-->>Driver: claimed batch stays removed, no turn opens',
-    '  else enter proposed step',
+    '  Note over Agent,Driver: next-step acceptance window opens',
+    `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
+    '  Hooks-->>Driver: authoritative allow, block, or add context',
+    '  alt prompt blocked or admission failed',
+    '    Driver-->>Driver: append context-only batch or keep steering boundary pending',
+    '  else prompt allowed',
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
-    `  Driver->>Session: ${mermaidCode('step/start')}`,
-    `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
+    `  Driver->>Session: ${mermaidCode('user/message')}`,
     `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
+    `  Driver-->>Driver: ${mermaidCode('agent/step')} serial checkpoint`,
+    `  Driver->>Session: ${mermaidCode('step/start')}`,
     `  Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
     '  LLM-->>Driver: StreamChunk*',
     `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
@@ -1197,17 +1089,11 @@ function renderLifecycle(): string {
     `      Driver->>Session: ${mermaidCode('tool/result')}`,
     '    end',
     '  end',
+    '  Driver->>Session: post-tool context and steering (no prompt-submit)',
     `  Driver->>Session: ${mermaidCode('step/end')}`,
-    '  opt natural stop and next-step inbox empty',
-    `    Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
-    '  end',
-    '  opt next-step input is pending',
-    '    Driver-->>Driver: claim pending next-step input',
-    `    Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
-    `    Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
-    '    Hooks-->>Driver: authoritative reject or enter(messages)',
-    '  end',
+    `  Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
     '  end',
+    '  Note over Agent,Driver: next-step acceptance window closes',
     `  Driver->>Session: ${mermaidCode('turn/end')}`,
     '  end',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
@@ -1215,9 +1101,9 @@ function renderLifecycle(): string {
     '',
     'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
     '',
-    '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
+    '`dsh-compact-basic` uses `agent/step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
-    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later boundary claims their next-step batch.',
+    'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
     '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
@@ -1306,8 +1192,8 @@ function renderDocs(): GraphDoc[] {
 function renderIndex(docs: GraphDoc[]): string {
   const labels: Record<string, string> = {
     'docs/capability-seams.md': 'capability seams and core services',
-    'apps/cli/composition.md': 'dsh shared base composition',
     'examples/headless-agent/composition.md': 'headless-agent app composition',
+    'examples/tui-agent/composition.md': 'tui-agent app composition',
     'examples/cordis-agent/composition.md': 'cordis-agent app composition',
     'examples/acp-agent/composition.md': 'acp-agent app composition',
     'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -1316,8 +1202,8 @@ function renderIndex(docs: GraphDoc[]): string {
   }
   const modes: Record<string, string> = {
     'docs/capability-seams.md': 'hybrid generated',
-    'apps/cli/composition.md': 'hybrid generated',
     'examples/headless-agent/composition.md': 'hybrid generated',
+    'examples/tui-agent/composition.md': 'hybrid generated',
     'examples/cordis-agent/composition.md': 'hybrid generated',
     'examples/acp-agent/composition.md': 'hybrid generated',
     'docs/event-producer-consumer.md': 'hybrid generated',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 6f59b64826..74a09a874e 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -585,7 +585,6 @@ function docSyncLeafGates(options: {
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
     pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
-    pnpmScript('code-runtime-runner', 'verify-code-runtime-runner', { label: 'code-runtime runner' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links' }),
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 9a249ca844..3ca0317cf4 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,7 +47,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
-  'packages/code-runtime/code-runtime-subprocess': { kind: 'indirect', reason: 'The subprocess backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 6252733511..1a8ef6508a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -169,7 +169,6 @@
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
-    { "path": "./packages/code-runtime/code-runtime-subprocess" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
     { "path": "./packages/bash/bash-local" },

From e67a824604c3c098f01cb3e24fa189f56d4c8fc0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:38:03 +0800
Subject: [PATCH 087/262] docs(code-runtime): restore worker-only package
 summary

---
 packages/README.i18n.yaml | 2 +-
 packages/README.zh.md     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 1484411cca..458da3b713 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
 README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
-README.zh.md: faa879f3b5b62527c1d76ab3aff6a737f876ce4d
+README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7
diff --git a/packages/README.zh.md b/packages/README.zh.md
index bed31b657c..b84aef020a 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：用于模型编写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |

From 921f4ff7a32d3c8189e4983071281cdbc1525800 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:53:28 +0800
Subject: [PATCH 088/262] fix(pty): retain sends through cancellation polling

---
 packages/pty/pty-local/src/session.ts        |  4 +-
 packages/pty/pty-local/tests/session.spec.ts | 49 ++++++++++++++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index faea1ef84d..7116f44611 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -412,7 +412,7 @@ export class LocalPtySession implements PtyBackendSession {
         return
       }
       const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation || this.closing) return
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
       const idleFor = Date.now() - this.lastOutputAt
       if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
         this.shellPgid = foreground.processGroupId
@@ -439,7 +439,7 @@ export class LocalPtySession implements PtyBackendSession {
         this.settleActive('inferred_idle')
       }
     } catch (error: unknown) {
-      if (this.active === operation && !this.closing) this.failActive(error)
+      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
     } finally {
       this.polling = false
       const active = this.active
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 8d11f8e6f4..27abfcf74e 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -406,6 +406,7 @@ describe('LocalPtySession readiness and output', () => {
     await Promise.resolve()
     await vi.advanceTimersByTimeAsync(10)
     expect(inspections).toBe(2)
+    await vi.advanceTimersByTimeAsync(50)
     expect(operation.cancel()).toBe(true)
     let settled = false
     void operation.done.then(() => { settled = true })
@@ -423,6 +424,54 @@ describe('LocalPtySession readiness and output', () => {
     expect((await operation.done).waitReason).toBe('session_exit')
   })
 
+  it('does not let an in-flight readiness failure release a canceled send before signalling settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const readiness = Promise.withResolvers<never>()
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      if (inspections === 1) return { processGroupId: 456, inputWaiting: false }
+      if (inspections === 2) return await readiness.promise
+      return { processGroupId: 456, inputWaiting: true }
+    }
+    const signalling = Promise.withResolvers<undefined>()
+    const signalled = Promise.withResolvers<number>()
+    terminal.signalForeground = async (signal) => {
+      await signalling.promise
+      const foreground = await terminal.inspectForeground()
+      if (foreground === undefined) throw new Error('cannot resolve foreground')
+      inspector.signalGroup(foreground.processGroupId, signal)
+      signalled.resolve(foreground.processGroupId)
+      return foreground.processGroupId
+    }
+
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspections).toBe(2)
+    expect(operation.cancel()).toBe(true)
+    let settled = false
+    void operation.done.then(() => { settled = true })
+
+    readiness.reject(new Error('inspection failed during cancellation'))
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow(PtyError)
+
+    signalling.resolve(undefined)
+    expect(await signalled.promise).toBe(456)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    await session.close('test complete')
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
   it('signals only after an in-flight provider write lands', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 6e4bdbf0df411caca431986f39f8221ba6b64664 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 16:01:38 +0800
Subject: [PATCH 089/262] fix(pty): wire persistent Bash through subprocess

---
 examples/jsonrpc-agent/persistent-tools.cordis.yml             | 3 +++
 packages/pty/tool-bash-persistent/package.json                 | 1 +
 .../pty/tool-bash-persistent/tests/loader-composition.spec.ts  | 3 +++
 pnpm-lock.yaml                                                 | 3 +++
 4 files changed, 10 insertions(+)

diff --git a/examples/jsonrpc-agent/persistent-tools.cordis.yml b/examples/jsonrpc-agent/persistent-tools.cordis.yml
index 6f42441ca7..ebe0a00e61 100644
--- a/examples/jsonrpc-agent/persistent-tools.cordis.yml
+++ b/examples/jsonrpc-agent/persistent-tools.cordis.yml
@@ -18,6 +18,9 @@
     mode: danger-full-access
     workspaceRoot: !!js process.env.DSH_CWD ?? process.cwd()
 
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
 - id: pty
   name: '@deepseek-ai/dsh-pty'
 
diff --git a/packages/pty/tool-bash-persistent/package.json b/packages/pty/tool-bash-persistent/package.json
index b5cede3920..23aad9f32e 100644
--- a/packages/pty/tool-bash-persistent/package.json
+++ b/packages/pty/tool-bash-persistent/package.json
@@ -45,6 +45,7 @@
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts
index 16c4a7fea5..a69048e8d6 100644
--- a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts
+++ b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts
@@ -15,6 +15,7 @@ import * as PtyLocal from '@deepseek-ai/dsh-pty-local'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import * as ToolBashPersistent from '@deepseek-ai/dsh-tool-bash-persistent'
@@ -78,6 +79,7 @@ suite('persistent Bash through a real cordis.yml Loader composition', () => {
       '  config:',
       '    mode: danger-full-access',
       `    workspaceRoot: ${JSON.stringify(root)}`,
+      "- name: '@deepseek-ai/dsh-subprocess-local'",
       "- name: '@deepseek-ai/dsh-pty-local'",
       '  config:',
       '    pollIntervalMs: 10',
@@ -104,6 +106,7 @@ suite('persistent Bash through a real cordis.yml Loader composition', () => {
       ['@deepseek-ai/dsh-pty', PtyService],
       ['@deepseek-ai/dsh-test-sandbox', PassthroughSandbox],
       ['@deepseek-ai/dsh-sandbox-policy', SandboxPolicyService],
+      ['@deepseek-ai/dsh-subprocess-local', LocalSubprocessService],
       ['@deepseek-ai/dsh-pty-local', PtyLocal],
       ['@deepseek-ai/dsh-tool-bash-persistent', ToolBashPersistent],
     ])
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ccbc67c764..666d01c1c1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4508,6 +4508,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt

From d689907c121ea1f012cb18ecee835b4f567ece2e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 17:25:44 +0800
Subject: [PATCH 090/262] test(subprocess): drop obsolete cwd stubs

---
 packages/pty/pty-local/tests/index.spec.ts           | 1 -
 packages/subprocess/subprocess/tests/service.spec.ts | 2 --
 2 files changed, 3 deletions(-)

diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 15e73ddc1c..e6c4fde452 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -66,7 +66,6 @@ function terminalHandle(): SubprocessTerminalHandle {
 }
 
 class StubSubprocessService extends SubprocessService {
-  readonly cwd = '/tmp'
   async resolveExecutable(command: string): Promise<string> { return command }
   spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
   async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index 2084310da9..e4f770a9a3 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -16,8 +16,6 @@ import type {
  * is all an implementation owes the abstract class.
  */
 class StubSubprocessService extends SubprocessService {
-  readonly cwd = '/stub'
-
   async resolveExecutable(command: string): Promise<string> {
     return `/bin/${command}`
   }

From a662af94df3e628645bca2ca223b90e5f88bc2a6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 19:08:07 +0800
Subject: [PATCH 091/262] test(lsp): accept eager dead-slot eviction

---
 packages/lsp/lsp-local/tests/lifecycle.spec.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 7a30232e22..20c4bc7bf0 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -282,8 +282,9 @@ describe('lsp-local end to end over a fake server', () => {
       readonly instances: ReadonlyMap<string, { readonly dead: boolean }>
     }).instances
     const instance = [...instances.values()][0]
-    if (instance === undefined) throw new Error('expected one pooled LSP instance')
-    await waitFor(async () => instance.dead)
+    // The query's finally may already have observed the exit and evicted the dead slot. When the
+    // slot remains, synchronize with its close before proving the next query replaces it.
+    if (instance !== undefined) await waitFor(async () => instance.dead)
     expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
     await ctx.fiber.dispose()
   })

From e385c11e8e7b5d5d787c457760184b42fbd23767 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:11:57 +0800
Subject: [PATCH 092/262] fix(pty,subprocess,lsp): address review round on
 cancellation, lookup, and contracts

- pty-local: a pre-write inspection rejection no longer releases a canceled
  send while its foreground SIGINT is in flight; the interrupt path retains
  the slot and its post-signal tail resumes polling. Regression pins the
  failure-shaped cancellation and a close-during-write release.
- pty-local: SEND_ACTIVE names which provider operation is draining; README
  states the never-settling-provider outcome (slot retained, close recovers).
- subprocess-local: resolveExecutable rejects relative paths containing
  separators instead of expanding them per PATH entry with a misleading
  not-found error; seam JSDoc pins the rule for every provider.
- subprocess-local: LocalTerminalHandle documents why the seam's
  in-flight-join promise holds without operation tracking.
- lsp-local: the oversized-source diagnostic reports the observed byte lower
  bound; README documents that processId: null trades away server-side
  orphan cleanup after a hard-killed harness.
- pty/subprocess seams: cross-reference the twin five-member signal unions.
- pty-local: TODO markers for send-state consolidation and initialize-race
  relocation.
---
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 packages/lsp/lsp-local/README.i18n.yaml       |  4 +-
 packages/lsp/lsp-local/README.md              |  1 +
 packages/lsp/lsp-local/README.zh.md           | 27 +++++----
 packages/lsp/lsp-local/src/host.ts            |  6 +-
 packages/lsp/lsp-local/tests/host.spec.ts     |  4 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/index.ts           |  3 +
 packages/pty/pty-local/src/session.ts         | 30 +++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 59 +++++++++++++++++++
 packages/pty/pty/src/types.ts                 |  6 +-
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  2 +-
 .../subprocess/subprocess-local/README.zh.md  |  2 +-
 .../subprocess/subprocess-local/src/index.ts  |  5 ++
 .../subprocess-local/src/terminal.ts          |  9 ++-
 .../subprocess-local/tests/local.spec.ts      |  6 ++
 packages/subprocess/subprocess/src/index.ts   |  4 +-
 packages/subprocess/subprocess/src/types.ts   |  6 +-
 21 files changed, 155 insertions(+), 33 deletions(-)

diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 2eb410acc6..21848e55e2 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -988,7 +988,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
-        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: no current consumer defines which directory they would\n * resolve against, so providers fail loud instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
       },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 55a9f97165..03487d5719 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-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/lsp/lsp-local/README.md
-README.md: ad8f4bc2318a58202f9596a18d402d2c6d45dae1
-README.zh.md: ff2686856a9e518a7fa846edf700da1b32e8a114
+README.md: 661c27d3326adfc3408b33550a63fe3ebe183a39
+README.zh.md: 83f0eaa1fb4caccc381a1623b791355b2f5c5b65
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index ad8f4bc231..93d123fac7 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -57,3 +57,4 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 - **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
 - **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
+- **A hard-killed harness orphans language servers** — `initialize.processId: null` removes server-side client-PID monitoring, so servers are cleaned only by graceful service disposal; a SIGKILL'd harness leaves them running until they exit on their own.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index ff2686856a..83f0eaa1fb 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -2,19 +2,19 @@
 
 [English](README.md) | 中文
 
-`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于所挂载的同一执行环境。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，preset 应放在 `cordis.yml` overlay 中。
+`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于已挂载的执行世界中。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，预设应放在 `cordis.yml` overlay 中。
 
 Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）。
 
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析并流式读取源文件，同时执行字节上限；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，以及位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
-- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方资源释放会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找结算，再排空所有队列并等待所有服务器结算。
-- 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
-- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
-- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与流式文本校验，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
+- 每次查询都使用兼容性优先的**临时打开**序列：通过 `ctx.fs` 流式读取源文件，同时解析并限制其字节数；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，再执行位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方 dispose 会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找完成，随后排空每条队列与每个服务器。
+- 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
+- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程和协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID namespace 不得监视 harness 进程。
+- 使用 `ctx.fs` 提供的规范化包含关系、文件 URI 与流式文本验证，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -24,13 +24,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 |---|---|---|
 | `command` | （必填） | 要 spawn 的可执行文件：绝对路径，或在加载时从子进程 PATH 解析。不使用 shell 启动。 |
 | `args` | `[]` | 传给可执行文件的参数。 |
-| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
+| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`PASSWORD`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
 | `extensionToLanguage` | （必填） | 小写、以点开头的扩展名 → LSP language id（例如 `{ '.ts': 'typescript' }`）。 |
 | `initializationOptions` | `null` | 转发给服务器的静态 `initialize` 选项。 |
 | `configuration` | `null` | 每个 `workspace/configuration` 配置项的静态答案。 |
 | `maxMessageBytes` | `16000000` | 从服务器接受的单条 framed 消息最大大小。 |
 | `maxStderrBytes` | `1000000` | 为诊断保留的 stderr 尾部最大大小。 |
-| `maxDocumentBytes` | `4000000` | 该主机可打开的最大源文件。 |
+| `maxDocumentBytes` | `4000000` | 该主机可打开的源文件大小上限。 |
 | `shutdownTimeoutMs` | `5000` | 升级前用于优雅 `shutdown`／`exit` 的预算。 |
 | `killGraceMs` | `2000` | 请求取消及 SIGTERM→SIGKILL 升级的宽限期。 |
 
@@ -38,11 +38,11 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 协议行为
 
-初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会作为结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
+初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会以结构化 `LSP_MALFORMED_RESPONSE` 错误的形式失败。
 
 ## 安全边界
 
-提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、普通文件流式读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。系统在打开流之前检查 containment，但不保证路径并发替换期间的稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
+提供方信任其配置的服务器，不提供任何沙箱隔离。它把规范化身份、包含关系、普通文件流式读取、UTF-8 验证和文件 URI 编码委托给 `ctx.fs`；并在服务器启动前拒绝缺失、非普通文件、非 UTF-8、过大，或规范化后位于 Workspace 外部的查询源。包含关系在打开流之前评估，不承诺在并发路径替换期间保持稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须挂载描述同一执行世界的文件系统与进程管理提供方；分裂世界组合无效。
 
 ## 模型体验
 
@@ -54,6 +54,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 已知限制与暂缓事项
 
-- **不提供隔离策略**：这个包（package）信任配置的服务器，不会对其进程执行沙箱化；受限部署必须提供适当的进程／文件系统提供方，或包装同一执行环境的沙箱。
+- **不提供隔离策略**：本包（package）信任所配置的服务器，不对其进程实施沙箱；受限部署必须提供适当的进程／文件系统提供方，或使用同一执行世界的沙箱包装层。
 - **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
-- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent 会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到释放。
+- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent（智能体）会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到 dispose。
+- **被强制杀死的 harness 会遗留语言服务器**：`initialize.processId: null` 取消了服务器侧的客户端 PID 监视，因此服务器只能由服务的优雅 dispose 清理；被 SIGKILL 的 harness 会让它们继续运行，直到自行退出。
diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index ffba6a1344..ef4b56809d 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -107,7 +107,11 @@ export async function readHostSource(
     throwIfAborted(signal)
     throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
   }
-  if (bytes > maxDocumentBytes) throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
+  if (bytes > maxDocumentBytes) {
+    throw new Error(
+      `source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit; reading stopped after ${bytes} bytes`,
+    )
+  }
   throwIfAborted(signal)
   return {
     fileUrl: fs.fileUrl(target),
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index c97defc086..c06b6d9df8 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -156,10 +156,10 @@ describe('readHostSource', () => {
     await expect(readSource('.')).rejects.toThrow(/not a regular file/)
   })
 
-  it('rejects an oversized source', async () => {
+  it('rejects an oversized source and reports the observed lower bound', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
     await expect(readSource('big.ts', 10)).rejects.toMatchObject({
-      message: 'source "big.ts" exceeds the 10-byte limit',
+      message: 'source "big.ts" exceeds the 10-byte limit; reading stopped after 100 bytes',
     })
   })
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 2689103443..bd835a091d 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-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/pty/pty-local/README.md
-README.md: 92a3d7be68ada6f38ab3c4ca5bdd2622ebefc8ee
-README.zh.md: 016043f7842df8bb963cdc5eea015666c9ce6941
+README.md: 5acc92853e6e8fcb8938c48e391559bf4a28fb75
+README.zh.md: 353c2a4bdac7e8402fc63071dfb6fb85dcff66d5
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 92a3d7be68..3b1112b025 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. A provider write or signal that never settles therefore retains the slot indefinitely; closing the session (`terminal_close`) is the recovery. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 016043f784..a23a2f3338 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
+取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。因此，永不结算的提供方写入或信号会无限期保留该位置；恢复手段是关闭会话（`terminal_close`）。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index f91db5d386..b1e0e6edbd 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -82,6 +82,9 @@ function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSp
   }).argv
 }
 
+// TODO(pty-initialize-race-home): Fold this outer abort race into
+// LocalPtySession.initialize when the send-state consolidation lands; the
+// session already owns the send lifecycle the race protects.
 async function initializeSession(session: LocalPtySession, signal?: AbortSignal): Promise<void> {
   if (signal === undefined) {
     await session.initialize(signal)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 7116f44611..25ed8fe586 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -162,6 +162,11 @@ export class LocalPtySession implements PtyBackendSession {
   private readonly outputEnded = Promise.withResolvers<void>()
   private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
+  // TODO(pty-send-state-consolidation): Fold the per-send fields below
+  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
+  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
+  // cancellation/readiness interplay now has enough pinned tests to carry
+  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
@@ -220,7 +225,14 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new PtyError('PTY session already has an active send or draining provider operation', 'SEND_ACTIVE')
+    if (this.active !== undefined) {
+      const draining = this.activeWrite !== undefined
+        ? ' or draining provider write'
+        : this.interrupting !== undefined
+          ? ' or draining foreground interrupt'
+          : ''
+      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
+    }
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -246,8 +258,22 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    let foreground: SubprocessTerminalForeground | undefined
+    try {
+      foreground = await this.terminal.inspectForeground()
+    } catch (error: unknown) {
+      // A pre-write inspection failure while cancellation owns the slot must not
+      // release it: interruptOnce's in-flight foreground signal could land on a
+      // successor's foreground group. The interrupt path's post-signal tail
+      // resumes polling, whose guarded catch propagates a persistent failure.
+      // A retained settled operation implies that same in-flight interrupt, so
+      // this guard admits only an unsettled active send.
+      if (this.active === operation && !this.closing && this.interrupting !== operation) {
+        this.failActive(error)
+      }
+      return
+    }
     try {
-      const foreground = await this.terminal.inspectForeground()
       if (this.active !== operation || this.closing || this.interrupting === operation) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 27abfcf74e..0ca1835e53 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -345,6 +345,47 @@ describe('LocalPtySession readiness and output', () => {
     await operation.done
   })
 
+  it('retains a canceled send when the pre-write inspection rejects while its signal is in flight', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const failed = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await failed.promise
+    const uncanceled = session.startSend({ text: 'plain failure', submit: true })
+    failed.reject(new Error('inspect failed before write'))
+    await expect(uncanceled.done).rejects.toThrow('inspect failed before write')
+
+    terminal.inspectForeground = FakeTerminal.prototype.inspectForeground.bind(terminal)
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const signalGate = Promise.withResolvers<undefined>()
+    terminal.signalForeground = async (signal) => {
+      await signalGate.promise
+      inspector.signalGroup(456, signal)
+      return 456
+    }
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'must stay owned', submit: true, signal: controller.signal })
+    controller.abort()
+    inspection.reject(new Error('transient inspection failure'))
+    await Promise.resolve()
+    await Promise.resolve()
+
+    // The slot stays reserved while the cancellation's foreground signal is in flight.
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow('active send')
+    terminal.inspectForeground = async () => ({ processGroupId: 456, inputWaiting: false })
+    signalGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+  })
+
   it('retains a canceled send until asynchronous foreground signalling settles', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -1176,6 +1217,24 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
   })
 
   it('settles a closing send when provider termination cancels inspection', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+    const write = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await write.promise }
+    const writeOperation = session.startSend({ text: 'pending write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await session.close('pending write')
+    expect((await writeOperation.done).waitReason).toBe('session_exit')
+    // The rejection lands after close released the send; it must stay contained.
+    write.reject(new Error('write rejected during close'))
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+
+  it('settles a closing send when provider termination cancels a pending inspection', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const session = new LocalPtySession(terminal, config())
diff --git a/packages/pty/pty/src/types.ts b/packages/pty/pty/src/types.ts
index a4985ead93..0317bb9d43 100644
--- a/packages/pty/pty/src/types.ts
+++ b/packages/pty/pty/src/types.ts
@@ -28,7 +28,11 @@ export class PtyBackendCleanupError extends AggregateError {
 /** Why one interactive send returned control to its caller. */
 export type PtyWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
 
-/** Signals the model-facing PTY surface permits for foreground process groups. */
+/**
+ * Signals the model-facing PTY surface permits for foreground process groups.
+ * Kept member-identical to `SubprocessTerminalSignal` in
+ * `@deepseek-ai/dsh-subprocess` without a cross-seam dependency; change both together.
+ */
 export type PtySignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP'
 
 /** Top-level PTY process status, independent of a send's wait reason. */
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index ee90e9e607..87a95c3170 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 85103c2634bd35b188acd71c7f037e3678a2542e
-README.zh.md: 505eac4f2650e6723e042cdb1122f9ef504ad7df
+README.md: b901a69d6cfd45a084711ba0d32e555c481fd626
+README.zh.md: 5723dc99ff955c5f4b07ea96e7d2134100d9fd6a
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index c211ca26f1..9e3e8f7f2d 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative PATH entries resolve from the host process cwd.
+- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 505eac4f26..5723dc99ff 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -10,7 +10,7 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；相对 PATH 条目从宿主进程 cwd 解析。
+- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在接缝处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 4a740a1e3b..e441944225 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -77,6 +77,11 @@ export class LocalSubprocessService extends SubprocessService {
     signal?.throwIfAborted()
     const environment = childEnv(env)
     const absolute = isAbsolute(command)
+    if (!absolute && (command.includes('/') || (process.platform === 'win32' && command.includes('\\')))) {
+      throw new Error(
+        `subprocess-local: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`,
+      )
+    }
     const candidates = absolute ? [command] : this.executableCandidates(command, environment)
     for (const candidate of candidates) {
       signal?.throwIfAborted()
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 53c531675f..2d3d0bb78e 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -24,7 +24,14 @@ function signalName(number: number | undefined): NodeJS.Signals | null {
   return null
 }
 
-/** A local terminal whose process-session ownership stays below the PTY backend. */
+/**
+ * A local terminal whose process-session ownership stays below the PTY backend.
+ * The seam's terminate() promise — no write, inspection, or signal in flight
+ * after settlement — holds here without operation tracking only because every
+ * handle call completes synchronously under the hood (node-pty write, ps-based
+ * inspection). A first genuinely asynchronous step in any handle call must add
+ * the tracking a remote provider needs.
+ */
 export class LocalTerminalHandle implements SubprocessTerminalHandle {
   readonly pid: number
   readonly output = new PassThrough()
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index a0455edef0..347b9c9330 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -32,6 +32,10 @@ describe('LocalSubprocessService', () => {
       PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
     })).toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
+    await expect(ctx.subprocess.resolveExecutable('./bin/tsserver'))
+      .rejects.toThrow('is a relative path')
+    await expect(ctx.subprocess.resolveExecutable('node_modules/.bin/server'))
+      .rejects.toThrow('is a relative path')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')
     await expect(ctx.subprocess.resolveExecutable('/dsh-absolute-command-that-does-not-exist'))
@@ -61,6 +65,8 @@ describe('LocalSubprocessService', () => {
         .toEqual(['/explicit/tool.EXE'])
       expect(candidates('tool.exe', {})).toEqual([resolve(process.cwd(), 'tool.exe')])
       expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
+      await expect(ctx.subprocess.resolveExecutable(String.raw`bin\server.exe`))
+        .rejects.toThrow('is a relative path')
     } finally {
       platform.mockRestore()
       await fiber.dispose()
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 14866c9784..6b9904078f 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -107,7 +107,9 @@ export abstract class SubprocessService extends Service {
   /**
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
-   * plus explicit environment overrides.
+   * plus explicit environment overrides. Relative paths containing separators
+   * are rejected: no current consumer defines which directory they would
+   * resolve against, so providers fail loud instead of guessing.
    * @param command - absolute executable path or bare PATH name.
    * @param env - explicit environment entries used for lookup.
    * @param signal - aborts remote or local lookup.
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 9801bf2f49..2aa2de0c91 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -193,7 +193,11 @@ export interface SubprocessHandle {
   waitForExit(signal?: AbortSignal): Promise<boolean>
 }
 
-/** Signals supported by the terminal-process primitive. */
+/**
+ * Signals supported by the terminal-process primitive. Kept member-identical
+ * to `PtySignal` in `@deepseek-ai/dsh-pty` without a cross-seam dependency;
+ * change both together.
+ */
 export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP'
 
 /** A fully specified terminal-process spawn. */

From 18ab9f6db201468d6cc68de3a7f4a6176e97b93c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:34:31 +0800
Subject: [PATCH 093/262] fix(rebase): migrate the replayed stack onto current
 master APIs

The linear replay carried each commit's own lineage, so this checkpoint
restores the master-owned surfaces the conflicted regions clobbered and
migrates branch-owned code to master's post-rebase APIs:

- rebuild subprocess-local spawn.ts on master's tree-exit-observer
  machinery, keeping the branch's win32 childEnv key semantics and the
  Linux zombie-quiescence probe; the zombie test reaps its survivor
  directly since a confirmed-absent verdict is a permanent
  no-more-signals boundary
- migrate pty-local test stubs to the Inbox-model Agent interface,
  Session.create, runnerFailureRules, and the new turn/start payload
- implement the seam's resolveExecutable/spawnTerminal abstracts in the
  new pwsh-local and tool-fs-search test fakes
- restore code-runtime, atomic-write, pwsh-local, and app-boot to
  master's exact content (the net-zero code-runtime churn is pruned
  from this history) and drop rename-detection graft debris
- re-apply the PR's architecture rows and execution-world paragraph,
  re-record bilingual pairings, regenerate catalogs, and reconcile the
  lockfile
---
 ...0-canonical-tool-output-contract.i18n.yaml |   2 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |  16 +-
 .../feature/2026-06-15-code-mode.zh.md        |  42 +-
 docs/architecture.md                          |   6 +-
 docs/architecture.zh.md                       |   6 +-
 docs/capability-seams.md                      |  67 ++-
 docs/cordis-catalog/services.md               |  58 ++-
 .../core-data-structures/filesystem.i18n.yaml |   2 +-
 docs/core-data-structures/lsp.i18n.yaml       |   2 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.zh.md    |  30 +-
 packages/README.i18n.yaml                     |   4 +-
 .../bash/pwsh-local/tests/executor.spec.ts    |   2 +
 packages/bash/pwsh-local/tsconfig.json        |  10 +-
 .../code-runtime-worker/README.md             |   2 +-
 .../code-runtime-worker/tests/runtime.spec.ts |  21 -
 .../fs/tool-fs-search/tests/tools.spec.ts     |   2 +
 packages/lsp/lsp-local/README.md              |   2 +-
 packages/pty/pty-local/README.md              |  10 +-
 packages/pty/pty-local/README.zh.md           |  10 +-
 packages/pty/pty-local/tests/index.spec.ts    |  38 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   8 +-
 .../subprocess/subprocess-local/README.zh.md  |   6 +-
 .../subprocess/subprocess-local/src/spawn.ts  |  75 +++-
 .../subprocess-local/tests/spawn.spec.ts      |   8 +-
 packages/typert/README.i18n.yaml              |   6 +-
 packages/ui/app-boot/tsdown.config.ts         |   8 +-
 packages/util/atomic-write/README.i18n.yaml   |   6 +-
 .../src/runner-source.generated.ts            |   6 -
 packages/util/atomic-write/src/runner.ts      | 401 ------------------
 pnpm-lock.yaml                                |  25 +-
 scripts/gen-doc-graphs.ts                     | 276 ++++++++----
 vitest.config.ts                              |  86 +++-
 35 files changed, 582 insertions(+), 673 deletions(-)
 delete mode 100644 packages/util/atomic-write/src/runner-source.generated.ts
 delete mode 100644 packages/util/atomic-write/src/runner.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index b8db543510..680d2dd94a 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
 2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
-2026-07-20-canonical-tool-output-contract.zh.md: fd1e55eab38e5929a2dc104073b49f9de7a493e2
+2026-07-20-canonical-tool-output-contract.zh.md: 26653ea769b8a642b70c4d3dd2f5ab907a70bd85
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 8773a797e9..bc05e497c5 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: b6a24ecd9700e32912b8112b59cbd8b6ab131eb5
-2026-06-15-code-mode.zh.md: 4d0a4cf8fa31cf9d9954e5bd95f823dfc0668444
+2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
+2026-06-15-code-mode.zh.md: ca1bbe9ed3e412186763d1ed4fca9ed06669d4c3
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index b6a24ecd97..99bbed3eda 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-15-code-mode.zh.md)
 
 ## Problem
 
-In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and the loop dispatches each call through `ctx.tools.execute()` **sequentially** (parallel tool execution is an explicit open TODO in `dsh-tools` and [docs/architecture.md](../../../../docs/architecture.md)), with **every** intermediate `tool-result` re-entering the model's context on the next request.
+In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and at the time of this note the loop dispatched each call through `ctx.tools.execute()` **sequentially** (parallel tool execution was an open TODO then; bounded parallel dispatch has since shipped — the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md), the rolling pool in [docs/architecture.md](../../../../docs/architecture.md)) — with **every** intermediate `tool-result` re-entering the model's context on the next request.
 
 For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each round-trip drags the entire intermediate result back into context whether the model needs it or not.
 
@@ -32,7 +32,7 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
 
 **Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
 
-**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders TypeScript declarations plus fixed usage instructions for the scope's visible capabilities. It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
+**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md) added Python and the `ctx.codeRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
 
 **Assembly ownership.** `run_code` and `tools:sdk` enter the trusted `system-prompt/assemble` waterfall as normal assembly inputs. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace either contribution. The waterfall's returned assembly is final, so whoever changes these inputs owns preserving a viable Code Mode protocol when the deployment expects Code Mode to remain usable; no restoration pass overrides deliberate composition.
 
@@ -48,7 +48,7 @@ Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentat
 
 **Sub-call contexts are deferred through the parent.** Injecting inside `run_code` would break parent call/result adjacency, so `ToolRunContext.deferContext()` collects every sub-result `additionalContexts` entry in dispatch order. The registry carries that array even when the program later throws, and the loop appends each entry only after the outer result and every sibling result in the step. An outer post-execute block discards tool-deferred entries and exposes only contexts explicitly attached by the blocking decision.
 
-**Concurrency is serialized.** Each run owns a dispatch queue, so even `Promise.all` executes tool calls in submission order. Settlement abandons queued calls that have not started. Parallelism requires per-tool concurrency-safety metadata.
+**Concurrency is bounded, not serialized.** Each run owns a dispatch queue that starts calls strictly in submission order and classifies each one through `registry.executionMode`, the same fail-closed `isConcurrencySafe` contract the native loop uses. Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (default 10; `1` restores serial dispatch); an exclusive call drains the pool and runs alone. Settlement abandons queued calls that have not started. This note shipped the serialized placeholder; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler that replaced it.
 
 **Presentation.** `run_code`'s render intent is decided here per the [render-intent Agent Note](../architecture/2026-07-02-tool-render-intent-union.md): `presentCall` creates a `generic` card with `kind: 'execute'`, the program text as its title, and the same program text as `rawInput`; `run_code` intentionally declares no `presentResult`, so the TUI and host/client runtime (Web) complete that card through their generic raw-content fallback using the final durable `tool/result.content`, including captured logs plus the returned value, failure, or post-policy spill preview. This is not a `terminal` card: that card's semantics are "a shell command in a working directory", which a program is not. See the [result-card completeness note](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md).
 
@@ -64,7 +64,7 @@ Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool en
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }` — the runtime exposes each namespace as a global object of async functions inside the program; the optional descriptor asks the runtime to inject a real program-visible rejection class without teaching the seam consumer-specific names. `CodeJsonValue` is this dependency-light seam's structural lossless-JSON type, so binding arguments and resolutions cross the implementation's serialization boundary whole.
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }` — program execution outcomes resolve as the `error` field. `run()` may reject only for caller/seam misuse (for example a duplicate binding namespace); consumers still contain a non-conforming backend rejection at their own error boundary.
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../../docs/defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout, a lossy completion is not an overflow, and a substrate exit is none of them.
-- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the shipped backend; a Python backend would say so, and pair with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the first backend; a Python backend says `'python'` and pairs with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` accepts any `language` with a registered SDK renderer and `run_code` flavor (TypeScript and Python ship; see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)) and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
 
 Requests contain every runtime input; implementations own validated timeout and cap defaults. The registry looks up the optional runtime only when Code Mode is assembled, so native mode does not depend on one. Missing or language-incompatible runtimes fail loudly. Alternate substrates or languages can replace the implementation behind the same seam, paired with the appropriate SDK generator.
 
@@ -85,11 +85,11 @@ The worker runtime provides containment, not a security boundary: model code can
 
 ### What the model sees
 
-The SDK instructs the model to write an async erasable-TypeScript body, call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Calls remain sequential even under `Promise.all`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
+The SDK instructs the model to write an async body in the loaded runtime's language (an erasable-TypeScript body by default; a Python `async` body under a Python runtime — see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)), call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Both flavors state the same contract in their own primitive: independent read-only calls MAY overlap under `Promise.all` (TypeScript) or `asyncio.gather` (Python), mutating calls run alone in submission order, and dependent work sequences with `await`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
 
 ## Consequences
 
-Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch remains serialized, while per-call contexts retain their source, envelope, and metadata through the outer result.
+Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch starts in submission order under a bounded overlap pool, while per-call contexts retain their source, envelope, and metadata through the outer result.
 
 ## Testing
 
@@ -106,7 +106,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s is cheap to add as a logged surface replacement under reconstructable requests, but still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
 
-**Parallel native dispatch in the loop.** The other answer to round-trip cost; still valid future work (the open TODO), still blocked on concurrency-safety metadata, and still no composition — it parallelizes calls the model already decided on in one step. Code Mode's serialized-queue decision keeps the two compatible: when the metadata lands, both native parallel dispatch and per-tool binding parallelism unlock together.
+**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and that is how it played out: the metadata landed as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch and per-tool binding parallelism unlocked on the same classifier.
 
 **Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
 
@@ -128,6 +128,6 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The runtime validates both sides of the worker port and applies no per-binding byte cap; structured-clone cost and process or worker memory are the practical bounds. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is the only byte-capped boundary.
 
-**Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
+**Sub-dispatch overlap is bounded by tool safety claims, not by the caller.** A program's `Promise.all` or `asyncio.gather` buys wall-clock parallelism only across calls the tool itself classifies concurrency-safe; a run of exclusive calls still costs its round-trips in sequence, and models may over-expect. Both flavors' SDK instructions state the real contract. This note shipped the serialized placeholder that made the risk absolute; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler and its overlap cap.
 
 **Budget metering reads the event loop, not a flag.** Busy-time polling (`eventLoopUtilization()`) is coarser than an exact CPU meter — a budget expires up to one poll interval late — and its correctness claim ("a pending dispatch cannot pause it") is load-bearing against a hostile program. Both sides are unit-tested (hot loop with a pending decoy dispatch dies at `computeMs`; idle-on-slow-binding survives to `maxWallMs`), and the poll interval is an internal constant, not config — nothing a deployment could mis-tune into a bypass. `maxWallMs` is config, and it reaches `setTimeout`, which clamps a delay above `MAX_TIMER_DELAY_MS` (2^31-1 ms) to 1 ms; a positivity check alone therefore accepts a 25-day ceiling that expires on the first tick and times out every run. The worker runtime range-checks the field at load for that reason. `computeMs` needs no upper bound because it is compared against measured utilization instead of being handed to a timer.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 4d0a4cf8fa..ca1bbe9ed3 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行是 `dsh-tools` 和 [docs/architecture.md](../../../../docs/architecture.md) 中明确标注的 open TODO），且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
+在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，而在本 note 写作时，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行当时还是 open TODO；此后有界的并行分发已经交付——见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)，以及 [docs/architecture.md](../../../../docs/architecture.md) 中的 rolling pool）——且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
 
 对于多步工具操作，这种方式 token 开销大且串行。模型无法组合工具——遍历结果集、根据中间值分支、扇出、后处理——每次调用都需要一次完整的模型往返，而每次往返都会把完整的中间结果拖回上下文，不管模型是否需要。
 
@@ -19,7 +19,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 三项决策，各自在下方独立小节中展开：
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
-2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
+2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包`@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
 3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
@@ -32,7 +32,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
 
-**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染 TypeScript 声明加固定的使用说明。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
+**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](2026-07-31-code-mode-language-dispatch.md) 加入了 Python 与按 `ctx.codeRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
 
 **组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 Code Mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
 
@@ -40,7 +40,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 ### run_code 工具与分发桥
 
-在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
+在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调性守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
 
 1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
@@ -48,7 +48,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
 
-**并发被序列化。** 每次 run 拥有一个分发队列，因此即使 `Promise.all` 也按提交顺序执行工具调用。结算时放弃尚未开始的排队调用。并行化需要每个工具的并发安全元数据。
+**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 契约相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
 **呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
 
@@ -61,35 +61,35 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 `packages/code-runtime/code-runtime/`——`@deepseek-ai/dsh-code-runtime`，仅依赖 `cordis`。一个抽象的 `CodeRuntime extends Service`（`super(ctx, 'codeRuntime')`）加上词汇：
 
 - `CodeRunRequest = { program: string; bindings: CodeBindingNamespace[]; signal?: AbortSignal }`
-- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
+- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与返回值可以完整跨越实现的序列化边界。
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }`——程序执行失败时，执行 promise 仍会 fulfill，并通过 `error` 字段返回失败结果。只有调用方/seam 误用（例如重复的绑定命名空间）时，`run()` 才会 reject；消费方仍在自己的错误边界处理不合规后端的拒绝。
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }`——按[防御性模式](../../../../docs/defensive-patterns.md)独立报告的正交结果；超时的 run 不是异常，abort 不是超时，有损完成值不是溢出，基底退出也与上述情况相互独立。
-- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——交付的后端为 `'typescript'`；Python 后端会声明自己，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
+- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——首个后端为 `'typescript'`；Python 后端声明 `'python'`，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 接受任何注册了 SDK 渲染器与 `run_code` flavor 的 `language`（TypeScript 与 Python 已交付；见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
 
 请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
 
 ### worker-thread 运行时
 
-`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包（package）。每次 `run()`：
+`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包。每次 `run()`：
 
-1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且保持位置不变，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
+1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且会保留源码位置，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
 2. **每次 run spawn 一个全新 `Worker`**，来自包自身的 bootstrap 模块：`env: {}`（真正为空——比 spawn 命令的 scrubbed-env 规则更严格），`resourceLimits` 来自配置，`stdout`/`stderr` 捕获到 `logs` 而非继承。不做池化，不跨 run 保留状态：程序的世界随 worker 消亡，这使得 run 仅从日志即可重建，状态泄漏不可表达。
 3. **在 bootstrap 中执行**：剥离后的程序成为一个 `AsyncFunction` 的函数体，其参数是绑定全局变量、消费方声明的 reject 类和一个捕获式 `console` shim，因此顶层 `await` 和 `return` 可用。Code Mode 声明 `ToolCallError`，成员属性为 `toolName`；运行时无需硬编码工具即可实体化真正的构造函数。无损 JSON 完成值会精确跨越边界；`undefined` 仍表示缺席，有损值产生 `invalid-output`，过大的外层结果产生 `output-limit`，而不会退化为检查格式化后的字符串替代品。
 4. **通过消息端口桥接绑定**：worker 中的每个绑定函数发送 `{ id, global, name, args }` 并等待回复；宿主根据请求的绑定校验名称、调用、并回复 `{ id, ok, value }` 或 `{ id, ok: false, message }`（宿主侧绑定拒绝变为程序侧 rejection）。worker 侧的命名空间对象通过 `defineProperty` 构建为 null-prototype，因此名为 `__proto__`、`constructor` 或 `toString` 的绑定是普通自有属性，而非原型链碰撞。未知名称、重复 id 和结算后消息被拒绝或忽略——端口协议假设对端是恶意的，因为对端运行的是模型代码。
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
-6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
+6. **dispose（资源释放）至完全停稳**：服务自身的 dispose 终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
 ### 信任姿态
 
-worker 运行时提供的是隔离，而非安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
+worker 运行时只能约束程序的运行，而不构成安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
 
 ### 模型看到的内容
 
-SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。即使在 `Promise.all` 下调用仍保持顺序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
+SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一契约：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
 
 ## 后果
 
-切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发保持序列化，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
+切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发在有界的重叠池下按提交顺序启动，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
 
 ## 测试
 
@@ -104,9 +104,9 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 **`node:vm` 作为参考运行时，加固推迟。** 否决：`node:vm` 不是隔离（原型链逃逸可达宿主 realm）且无法中断热循环。worker 线程提供独立 isolate、空环境、`resourceLimits` 和可靠的 `terminate()`，信任等级等同于 bash，因此参考实现和生产实现是同一个包，无需 unsafe-acknowledgement 仪式。
 
-**在原生工具调用上做结果省略/摘要。** 仅解决问题的上下文膨胀一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
+**在原生工具调用上做结果省略/摘要。** 仅解决问题中上下文膨胀这一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
 
-**循环中的并行原生分发。** 往返成本的另一个答案；仍是有效的未来工作（open TODO），仍被并发安全元数据阻塞，且仍无组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的序列化队列决策保持两者兼容：当元数据就绪时，原生并行分发和每工具绑定并行化一起解锁。
+**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，后续也正是这样落地的：元数据以 `isConcurrencySafe` 的形式就绪（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发与每工具绑定并行化基于同一个分类器一起解锁。
 
 **始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
 
@@ -114,20 +114,20 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 **SDK 中的清洁化标识符别名**（`my-tool` → `my_tool`，Cloudflare 的做法）。否决：`declare const` 上的带引号键使每个名称可达，零别名碰撞逻辑；模型能正常处理 `tools["my-tool"](…)`。
 
-**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 全新保持了这一点。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
+**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 均使用全新实例则维持了这一保证。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
 
 ## 风险
 
-**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，隔离程度超过它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
+**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
 
 **SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
 
-**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
+**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 共同约束了这一增长：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
 
-**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 返回值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
 
-**仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
+**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实契约。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
-**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）对恶意程序是承重的。两侧都有单元测试（带 pending 诱饵分发的热循环在 `computeMs` 处死亡；在慢绑定上空闲的程序存活到 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
+**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）是抵御恶意程序的关键。两种情况均有单元测试（带 pending 诱饵分发的热循环会在耗尽 `computeMs` 预算时终止；等待慢速绑定的空闲程序则会持续运行至 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
diff --git a/docs/architecture.md b/docs/architecture.md
index ea78faa627..e88bdac118 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -26,12 +26,12 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry, streaming model calls |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware request and surface pressure |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
-| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | managed child-process trees for bash, LSP, and ACP subagent backends |
+| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | executable lookup, managed trees, terminals |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | owner-scoped persistent terminal sessions |
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement through argv wrapping and per-call policy |
 | `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | shared sandbox policy home |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
-| `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events |
+| `ctx.fs` | [`fs/`](../packages/fs/README.md) | execution-world paths, bounded IO, and policy events |
 | `ctx.lsp` | [`lsp/`](../packages/lsp/README.md) | semantic navigation registry |
 | `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill provider registry, progressive disclosure |
 | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
@@ -155,7 +155,7 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 ### Capability Pattern
 
-A swappable capability usually has **interface / implementation / consumer** layers: service/events, backend, and model-facing tools/prompts. Bash is the reference; the [capability graph](capability-seams.md) maps each family.
+Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md).
 
 Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](core-data-structures/subagent.md)).
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 5a46dfaf84..9314a3fbfc 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -26,12 +26,12 @@
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
-| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 供 bash、LSP 与 ACP subagent 后端使用的受管子进程树 |
+| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 通过 argv 包装和逐调用策略限制同一执行环境内的进程 |
 | `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | 共享沙箱策略归属点 |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | 执行模型编写的程序 |
-| `ctx.fs` | [`fs/`](../packages/fs/README.md) | 文件系统提供方原语和策略事件 |
+| `ctx.fs` | [`fs/`](../packages/fs/README.md) | 执行世界路径、有界 I/O 和策略事件 |
 | `ctx.lsp` | [`lsp/`](../packages/lsp/README.md) | 语义导航注册表 |
 | `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill（技能）提供方注册表和渐进式披露 |
 | `ctx.web` | [`web/`](../packages/web/README.md) | 搜索与抓取提供方注册表 |
@@ -155,7 +155,7 @@ idle inject:
 
 ### 功能模式
 
-可替换功能通常具有**接口／实现／消费方**三层：服务和事件、后端、面向模型的工具和提示词。Bash 是参考实现；[功能图](capability-seams.md)映射了每个包族。
+能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。
 
 例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](core-data-structures/subagent.md)）。
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index c5ec654d0f..ae90e4a9bf 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -40,6 +40,13 @@ flowchart LR
   pkg_tool_bash["tool-bash"]
   pkg_hooks_claude["hooks-claude"]
   pkg_hooks_codex["hooks-codex"]
+  pkg_settings["settings"]
+  svc_settings["ctx.settings<br/>User-settings seam"]
+  pkg_settings_local["settings-local"]
+  pkg_apiproxy["apiproxy"]
+  pkg_credentials["credentials"]
+  svc_credentials["ctx.credentials<br/>Credential seam"]
+  pkg_credentials_local["credentials-local"]
   pkg_session_telemetry["session-telemetry"]
   svc_telemetry["ctx.telemetry<br/>Session telemetry seam"]
   pkg_session_telemetry_otel["session-telemetry-otel"]
@@ -51,12 +58,10 @@ flowchart LR
   svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
   pkg_workspace["workspace"]
   svc_workspace["ctx.workspace<br/>Workspace entity registry"]
-  pkg_apiproxy["apiproxy"]
   svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
   pkg_session_reference["session-reference"]
   pkg_tool_session_query["tool-session-query"]
   svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
-  pkg_tui["tui"]
   pkg_session_title["session-title"]
   svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
   pkg_session_title_first_message_llm["session-title-first-message-llm"]
@@ -84,13 +89,11 @@ flowchart LR
   pkg_host_apiproxy["host-apiproxy"]
   pkg_session_projection_cache["session-projection-cache"]
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
-  svc_tui["ctx.tui<br/>Mounted-terminal interaction service"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
-  pkg_tui_demo["tui-demo"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -103,8 +106,13 @@ flowchart LR
   pkg_pty_local["pty-local"]
   pkg_lsp_local["lsp-local"]
   pkg_subagent_acp["subagent-acp"]
+  pkg_subagent_codex["subagent-codex"]
+  pkg_subagent_claude_code["subagent-claude-code"]
   pkg_bash["bash"]
   svc_bash["ctx.bash<br/>Bash executor seam"]
+  pkg_pwsh_local["pwsh-local"]
+  pkg_tool_pwsh["tool-pwsh"]
+  pkg_bash_env["bash-env"]
   svc_bashEnv["ctx.bashEnv<br/>Managed bash environment registry"]
   pkg_pty["pty"]
   svc_pty["ctx.pty<br/>Persistent PTY session registry"]
@@ -128,9 +136,11 @@ flowchart LR
   pkg_compact["compact"]
   svc_compact["ctx.compact<br/>Compaction seam"]
   pkg_subagent["subagent"]
-  svc_subagents["ctx.subagents<br/>Subagent provider registry"]
+  svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
   pkg_subagent_spawn["subagent-spawn"]
   pkg_subagent_fork["subagent-fork"]
+  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
+  pkg_tool_subagent_control["tool-subagent-control"]
   pkg_tool_ralph["tool-ralph"]
   pkg_tasks["tasks"]
   svc_tasks["ctx.tasks<br/>Background task registry"]
@@ -166,6 +176,7 @@ flowchart LR
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
   pkg_bash --> svc_bash
+  pkg_bash_env --> svc_bashEnv
   pkg_bash_local --> svc_bash
   pkg_bash_sandbox --> svc_bash
   pkg_code_runtime --> svc_codeRuntime
@@ -174,6 +185,8 @@ flowchart LR
   pkg_compact --> svc_compact
   pkg_compact_basic --> svc_compact
   pkg_compact_tool_result_prune --> svc_toolResultPrune
+  pkg_credentials --> svc_credentials
+  pkg_credentials_local --> svc_credentials
   pkg_directory_picker --> svc_directoryPicker
   pkg_directory_picker_browse --> svc_directoryPicker
   pkg_directory_picker_native --> svc_directoryPicker
@@ -191,6 +204,7 @@ flowchart LR
   pkg_plan_mode --> svc_planMode
   pkg_pty --> svc_pty
   pkg_pty_local --> svc_pty
+  pkg_pwsh_local --> svc_bash
   pkg_sandbox --> svc_sandbox
   pkg_sandbox_local --> svc_sandbox
   pkg_sandbox_policy --> svc_sandboxPolicy
@@ -208,6 +222,8 @@ flowchart LR
   pkg_session_title --> svc_sessionTitle
   pkg_session_title_all_messages_llm --> svc_sessionTitle
   pkg_session_title_first_message_llm --> svc_sessionTitle
+  pkg_settings --> svc_settings
+  pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
@@ -218,6 +234,9 @@ flowchart LR
   pkg_storage_sqlite --> svc_storage
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
+  pkg_subagent_claude_code --> svc_subagents
+  pkg_subagent_codex --> svc_subagents
+  pkg_subagent_dsh_sdk --> svc_subagents
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
@@ -226,10 +245,7 @@ flowchart LR
   pkg_tasks --> svc_tasks
   pkg_tasks_local --> svc_tasks
   pkg_token_meter --> svc_tokenMeter
-  pkg_tool_bash --> svc_bashEnv
   pkg_tools --> svc_tools
-  pkg_tui --> svc_tui
-  pkg_tui --> svc_userInteraction
   pkg_typert_registry --> svc_typert
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
@@ -246,16 +262,20 @@ flowchart LR
   svc_agents --> pkg_agent_loop
   svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
-  svc_agents --> pkg_tui_demo
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
   svc_bash --> pkg_hooks_claude
   svc_bash --> pkg_hooks_codex
   svc_bash --> pkg_tool_bash
+  svc_bash --> pkg_tool_pwsh
+  svc_bashEnv --> pkg_tool_bash
+  svc_bashEnv --> pkg_tool_pwsh
   svc_clientModuleHost --> pkg_hmr
   svc_codeRuntime --> pkg_tools
-  svc_commands --> pkg_tui
   svc_compact --> pkg_compact_basic
+  svc_credentials --> pkg_apiproxy
+  svc_credentials --> pkg_llm_deepseek
+  svc_credentials --> pkg_llm_pi_ai
   svc_directoryPicker --> pkg_apiproxy
   svc_fs --> pkg_tool_fs
   svc_httpServer --> pkg_connection
@@ -285,7 +305,6 @@ flowchart LR
   svc_sessionProjections --> pkg_tool_todo
   svc_sessionQuery --> pkg_session_reference
   svc_sessionQuery --> pkg_tool_session_query
-  svc_sessionReferences --> pkg_tui
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
   svc_sessions --> pkg_cli_demo
@@ -294,17 +313,23 @@ flowchart LR
   svc_sessions --> pkg_session_query
   svc_sessions --> pkg_session_query_sqlite
   svc_sessions --> pkg_subagent_inprocess
+  svc_settings --> pkg_apiproxy
+  svc_settings --> pkg_llm_deepseek
+  svc_settings --> pkg_llm_pi_ai
   svc_skills --> pkg_tool_skill
   svc_spillStore --> pkg_spill_policy
   svc_storage --> pkg_storage_domain
   svc_storageDomain --> pkg_workspace
   svc_subagents --> pkg_tool_ralph
   svc_subagents --> pkg_tool_subagent
+  svc_subagents --> pkg_tool_subagent_control
   svc_subprocess --> pkg_bash_local
   svc_subprocess --> pkg_bash_sandbox
   svc_subprocess --> pkg_lsp_local
   svc_subprocess --> pkg_pty_local
   svc_subprocess --> pkg_subagent_acp
+  svc_subprocess --> pkg_subagent_claude_code
+  svc_subprocess --> pkg_subagent_codex
   svc_systemPrompt --> pkg_agent_loop
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_pty
@@ -329,7 +354,6 @@ flowchart LR
   svc_typert --> pkg_api_gateway
   svc_typert --> pkg_typert_loader
   svc_userInteraction --> pkg_tool_ask_user
-  svc_userInteraction --> pkg_tui
   svc_web --> pkg_tool_web
   svc_workflows --> pkg_tool_ralph
   svc_workflows --> pkg_tool_workflow
@@ -347,28 +371,29 @@ flowchart LR
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
+| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
+| `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
 | `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
 | `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
-| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | [`tui`](../packages/ui/tui) | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
+| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
-| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui) | - | Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model. |
+| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.tui` | `bundle` | [`tui`](../packages/ui/tui) | - | - | - | One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp) | - | The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
-| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
-| `ctx.bashEnv` | `core` | [`tool-bash`](../packages/bash/tool-bash) | - | - | - | Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
+| `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
@@ -377,7 +402,7 @@ flowchart LR
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
-| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a9077ae139..7e125cd02c 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -594,6 +594,34 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea
  */
 abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
+/**
+ * Return the canonical absolute path a subprocess in this filesystem's
+ * execution world can open. The path is deliberately separate from
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+ * capability, but must continue treating the target key as opaque.
+ * @param target - the resolved target whose process path is required.
+ * @returns an absolute path in the backend's execution world.
+ */
+abstract processPath(target: FsTarget): string
+
+/**
+ * Return the canonical `file:` URI for a target in this filesystem's
+ * execution world. Backends own URI encoding because the host platform may
+ * differ from the execution platform.
+ * @param target - the resolved target to encode.
+ * @returns the target's canonical file URI.
+ */
+abstract fileUrl(target: FsTarget): string
+
+/**
+ * Test canonical containment without exposing or parsing backend target
+ * keys. Both targets must come from this provider.
+ * @param parent - canonical directory target.
+ * @param child - canonical candidate target.
+ * @returns true when `child` is `parent` or a descendant of it.
+ */
+abstract contains(parent: FsTarget, child: FsTarget): boolean
+
 /**
  * Return target metadata, or `undefined` when the target does not exist.
  * @param target - the resolved target to stat.
@@ -678,7 +706,7 @@ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version:
 
 Types: [FsDirEntry](../core-data-structures/filesystem.md) · [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsPathInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md) · [SandboxExecutionPolicy](../core-data-structures/sandbox.md)
 
-Source: [`packages/fs/fs/src/index.ts:81`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
 
 ## `ctx.goals` — `GoalService`
 
@@ -2215,12 +2243,27 @@ Abstract subprocess service. Subclass, implement spawn, and load the subclass as
 
 Implementations must honor these semantics:
 
+- Executable paths belong to one execution world shared with the mounted filesystem provider.
 - spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
 - Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
 - SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
+- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
 
 ```ts cordis-catalog
+/**
+ * Resolve one configured executable in this provider's execution world.
+ * Absolute paths are verified; bare names use the provider's scrubbed PATH
+ * plus explicit environment overrides. Relative paths containing separators
+ * are rejected: no current consumer defines which directory they would
+ * resolve against, so providers fail loud instead of guessing.
+ * @param command - absolute executable path or bare PATH name.
+ * @param env - explicit environment entries used for lookup.
+ * @param signal - aborts remote or local lookup.
+ * @returns a canonical executable path.
+ */
+abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
+
 /**
  * Start one managed child process from a fully-specified spec; this seam
  * applies no defaults.
@@ -2228,11 +2271,20 @@ Implementations must honor these semantics:
  * @returns the live process handle (streams/readers, signalling, outcome promise).
  */
 abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+/**
+ * Allocate a real terminal and start one owned process session. This is the
+ * only non-pipe process primitive: implementations own terminal byte I/O,
+ * foreground groups, signals, and complete session-tree cleanup.
+ * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+ * @returns the live terminal handle after allocation succeeds.
+ */
+abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
 ```
 
-Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md)
+Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md) · [SubprocessTerminalHandle](../core-data-structures/subprocess.md) · [SubprocessTerminalSpawnSpec](../core-data-structures/subprocess.md)
 
-Source: [`packages/subprocess/subprocess/src/index.ts:91`](../../packages/subprocess/subprocess/src/index.ts)
+Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
 
 ## `ctx.systemPrompt` — `SystemPrompt`
 
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
index 78386c54fd..2f9478a7ba 100644
--- a/docs/core-data-structures/filesystem.i18n.yaml
+++ b/docs/core-data-structures/filesystem.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/filesystem.md
 filesystem.md: addded9f673ed435e95109d4fb772967514c0b87
-filesystem.zh.md: 3ef16ede1e137d2a1310861941ac3244ca105650
+filesystem.zh.md: 1e378928ed570b97dbec73b836a7e6ff18726ff8
diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/core-data-structures/lsp.i18n.yaml
index 329d5086e0..25b54df775 100644
--- a/docs/core-data-structures/lsp.i18n.yaml
+++ b/docs/core-data-structures/lsp.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/lsp.md
 lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
-lsp.zh.md: ef9623f01124bc459d3bbceba340c3870e678baa
+lsp.zh.md: d428f2b5f9568b231b0b50a13bd4a41f7ea81346
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 50e219a2c6..b2d38854b2 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 895bfe3d763853a86648e8aaab8b091a26006255
-subprocess.zh.md: 044e924674ecf5dd8f8a1c71fe39653e7525dfb0
+subprocess.md: 023b122218ad1caa2b8e16c26b0bc8b0d4183c28
+subprocess.zh.md: 5ee9c782c0ce73ca9a2e694450ed38b8d548dc09
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 044e924674..5ee9c782c0 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -1,4 +1,4 @@
-# 进程管理器
+# 子进程
 
 [English](subprocess.md) | 中文
 
@@ -12,7 +12,7 @@
 
 ## 受管环境命名空间与捕获的输出
 
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的条目形式到达，每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
+`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的字符串条目形式到达，而显式的 `undefined` tombstone 会删除普通环境中已有的值。每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -36,7 +36,7 @@ interface CollectedOutput {
 }
 ```
 
-## Node 形状的 stdio 处置方式（disposition）
+## Node 风格的 stdio 处置方式（disposition）
 
 每条流的处置方式都显式给出，由各消费方自行选择：原始管道用于协议分帧（LSP JSON-RPC、ACP ndjson），inherit 用于直通的诊断输出，收集模式用于有界的批量输出；其中 spill 文件是可选的，因此诊断尾部（语言服务器的 stderr）可以只在内存中缓冲，不留下任何文件。
 
@@ -88,7 +88,7 @@ interface SubprocessStdio {
 
 ## 完全显式的 spawn spec
 
-该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的进程管理器默认值决定。`argv` 绝不经过 shell 解释。
+该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的子进程服务默认值决定。`argv` 绝不经过 shell 解释。
 
 ```ts type-equiv
 /**
@@ -105,10 +105,11 @@ interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
-   * escalation and for draining still-open collected pipes after the process
-   * exits (an inherited descriptor held by a surviving descendant cannot hold
-   * the outcome open indefinitely).
+   * Positive finite grace period in milliseconds, no greater than
+   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
+   * and for draining still-open collected pipes after the process exits (an
+   * inherited descriptor held by a surviving descendant cannot hold the
+   * outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -119,19 +120,18 @@ interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation:
-   * every entry is a deliberate caller opt-in, so a forwarded
-   * credential-shaped entry or a current `DSH_*` fact survives precisely
-   * because this layer merges after the scrub that drops its ambient
-   * namesake.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
    */
-  env?: Record<string, string> | undefined
+  env?: NodeJS.ProcessEnv | undefined
 }
 ```
 
 ## 句柄：流、读取器与以进程树为范围的终止
 
-spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树——这足以让消费方构建自己的拆卸阶梯（ACP 后端以 stdin EOF 打头的 `disposeAcpChild` 即是模板）。
+spawn 会立即返回一个活动句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树。这足以让消费方构建自己的拆卸阶梯；ACP 后端的 `disposeAcpChild` 以 stdin EOF 开始，即为仓库内模板。
 
 ```ts type-equiv
 /**
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 458da3b713..d10f476f79 100644
--- 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: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
-README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7
+README.md: 8fbb6069a784a5bd45423a4e1ae11834a597750d
+README.zh.md: 42a8d691344c716021188df6fd870a841d543f36
diff --git a/packages/bash/pwsh-local/tests/executor.spec.ts b/packages/bash/pwsh-local/tests/executor.spec.ts
index c7da16c44c..350ea4de89 100644
--- a/packages/bash/pwsh-local/tests/executor.spec.ts
+++ b/packages/bash/pwsh-local/tests/executor.spec.ts
@@ -119,6 +119,8 @@ describe('spawn construction (pure, every platform)', () => {
   /** A subprocess service that records spawn specs and settles instantly. */
   class CapturingSubprocessService extends SubprocessService {
     specs: SubprocessSpawnSpec[] = []
+    override async resolveExecutable(command: string): Promise<string> { return command }
+    override spawnTerminal(): Promise<never> { throw new Error('pwsh spawns pipes, never terminals') }
     private readonly reader: SubprocessOutputReader = {
       readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }),
     }
diff --git a/packages/bash/pwsh-local/tsconfig.json b/packages/bash/pwsh-local/tsconfig.json
index 7381575674..53ccc94926 100644
--- a/packages/bash/pwsh-local/tsconfig.json
+++ b/packages/bash/pwsh-local/tsconfig.json
@@ -18,19 +18,19 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../code-runtime"
+      "path": "../../util/brand"
     },
     {
-      "path": "../code-runtime-worker"
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../../bash/bash"
     },
     {
       "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
-    },
-    {
-      "path": "../../util/timeout"
     }
   ]
 }
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 3de3bc622e..590b79dcd1 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -34,7 +34,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
-The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The `./runtime-host` subpath shares type stripping, binding validation/dispatch, lossless JSON transport, and output accounting with sibling worker-based implementations; it is implementation support, not a plugin. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers remain source-private.
+The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
 
 ## Model Experience
 
diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
index db2c167354..54f58eb414 100644
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -597,27 +597,6 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
     expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
   })
 
-  it('contains binding rejections whose thrown values cannot be rendered', async () => {
-    const { runtime } = await setup()
-    const result = await runtime.run({
-      program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
-      bindings: tools({
-        bad: async () => {
-          const hostile = new Error('hidden')
-          Object.defineProperty(hostile, 'message', {
-            get() { throw new Error('message getter failed') },
-          })
-          throw hostile
-        },
-      }),
-    })
-    expect(result.value).toEqual({
-      name: 'ToolCallError',
-      toolName: 'bad',
-      message: 'binding rejected with an unrenderable value',
-    })
-  })
-
   it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
     const { runtime } = await setup()
     let calls = 0
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index e9ae5588ee..c02e4f93db 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -148,6 +148,8 @@ class FakeHandle implements SubprocessHandle {
  */
 class FakeSubprocess extends SubprocessService {
   spawns: SubprocessSpawnSpec[] = []
+  override async resolveExecutable(command: string): Promise<string> { return command }
+  override spawnTerminal(): Promise<never> { throw new Error('search tools spawn pipes, never terminals') }
   handles: FakeHandle[] = []
   /** Arms the per-spawn script; a `{ reject }` return scripts a spawn-level failure. */
   handler: (spec: SubprocessSpawnSpec) => ScriptedRun | { reject: Error } = () => runResult('')
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 93d123fac7..661c27d332 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -24,7 +24,7 @@ The `servers` record key is the stable provider id reserved on `ctx.lsp`; each v
 |---|---|---|
 | `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. |
 | `args` | `[]` | Arguments passed to the executable. |
-| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
+| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`PASSWORD`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
 | `extensionToLanguage` | (required) | Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). |
 | `initializationOptions` | `null` | Static `initialize` options forwarded to the server. |
 | `configuration` | `null` | Static answer to every `workspace/configuration` item. |
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 3b1112b025..5acc92853e 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -6,7 +6,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
@@ -14,19 +14,19 @@ Send cancellation marks queued input as canceled before asking the terminal hand
 
 ## Model Experience
 
-### Indirect consumer
+### Current file policy and indirect consumer
 
 #### What the model sees
 
-Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+The policy owner contributes capability-neutral `sandbox:policy` context. Through `@deepseek-ai/dsh-tool-pty` or another PTY consumer, the model may also receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
 
 #### Token effect
 
-None until a consumer returns bounded backend output. Retained PTY scrollback is not placed in model history by this package.
+The current-policy clause is present while this backend is mounted. Retained PTY scrollback is not placed in model history until a consumer returns bounded output.
 
 #### KV Cache effect
 
-No direct invalidation; the consumer owns prompts, schemas, and appended results.
+A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; consumer results remain append-only.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index a23a2f3338..353c2a4bda 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
@@ -14,19 +14,19 @@
 
 ## 模型体验
 
-### 间接消费方
+### 当前文件策略与间接消费方
 
 #### 模型看到的内容
 
-没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
+策略归属方会贡献与具体能力无关的 `sandbox:policy` 上下文。模型通过 `@deepseek-ai/dsh-tool-pty` 或其他 PTY 消费方还可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
 
 #### Token 影响
 
-消费方返回有界的后端输出前没有影响。此包（package）不会把保留的 PTY scrollback 放入模型历史。
+装载该后端期间，当前策略子句会一直存在。消费方返回有界输出前，保留的 PTY scrollback 不会进入模型历史。
 
 #### KV Cache 影响
 
-不会直接使 KV Cache 失效；提示词、schema 与追加结果由消费方负责。
+常驻策略发生变化时，会在保留的历史之后追加一份由归属方渲染、取代先前状态的运行时上下文快照；消费方结果保持仅追加。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index e6c4fde452..9f10a2cde8 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -3,7 +3,7 @@ import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { Inbox, type Agent } from '@deepseek-ai/dsh-agent'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
@@ -22,7 +22,7 @@ import type {
 
 class EmptySandbox extends SandboxProvider {
   confine(_argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
-    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
   }
 }
 
@@ -31,7 +31,7 @@ class RecordingSandbox extends SandboxProvider {
 
   confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
     this.calls.push({ argv, policy })
-    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
   }
 }
 
@@ -46,9 +46,15 @@ function config(): ResolvedConfig {
 
 function agent(ctx: Context): Agent {
   const id = SessionId('agent')
+  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0 })
   return {
-    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
-    followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle',
+    ctx,
+    send: () => {},
+    followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
   }
 }
 
@@ -331,7 +337,7 @@ describe('pty-local plugin shape', () => {
 
     const session = ctx.sessions.create(SessionId('unowned-mode'))
     expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/start', { turn: 1 })
     }).not.toThrow()
     expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
   })
@@ -348,8 +354,13 @@ describe('pty-local plugin shape', () => {
     const session = ctx.sessions.create(SessionId('mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+      status: 'idle',
+      ctx: ownerFiber.ctx,
+      send: () => {},
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
@@ -358,7 +369,7 @@ describe('pty-local plugin shape', () => {
     const unrelated = ctx.sessions.create(SessionId('unrelated-mode'))
     expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow()
     expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/start', { turn: 1 })
     }).not.toThrow()
 
     expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
@@ -392,8 +403,13 @@ describe('pty-local plugin shape', () => {
     const session = ctx.sessions.create(SessionId('pending-mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+      status: 'idle',
+      ctx: ownerFiber.ctx,
+      send: () => {},
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const gate = Promise.withResolvers<undefined>()
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 87a95c3170..22d971b251 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: b901a69d6cfd45a084711ba0d32e555c481fd626
-README.zh.md: 5723dc99ff955c5f4b07ea96e7d2134100d9fd6a
+README.md: 087ca24a3207cb8cb1568769a462fbbb010aaa35
+README.zh.md: 4d400906f71b653ce2be95a22751fd9893f447bd
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 9e3e8f7f2d..087ca24a32 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -6,9 +6,9 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 
 ## Behavior (and where it came from)
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F` (injectable for tests). `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
+- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
-- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
+- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
@@ -24,10 +24,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Windows tree support is best-effort and untested in CI** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary; the suites cover the routing through an injected runner only, and `packages/subprocess/*` is excluded from the Windows test matrix.
+- **Windows tree support is best-effort** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary.
 - **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
 - **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the `node-pty` root; on Linux, a child that calls `setsid` leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
-- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
+- **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
 
 The raw process handling lives in `src/spawn.ts`; `src/index.ts` is the service wiring.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 5723dc99ff..4d400906f7 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -6,9 +6,9 @@
 
 ## 行为（以及设计来源）
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
+- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在接缝处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
@@ -24,7 +24,7 @@
 
 ## 已知限制与暂缓事项
 
-- **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
+- **Windows 进程树支持仅为尽力而为**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
 - **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 则使用 `ps` 快照。
 - **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 `node-pty` 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话。本地提供方不会新增持续进程表监视器。
 - **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index 9fa70250dc..5b977cacc1 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -15,6 +15,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout as sleepMs } from 'node:timers/promises'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   CollectedOutput,
   SubprocessCollect,
@@ -27,16 +28,16 @@ import { linuxProcessGroupHasLiveMembers } from './process-inspector.ts'
 
 /**
  * Build a child environment: explicit caller entries override the scrubbed
- * parent base using the target platform's environment-key semantics, so a
- * deliberately supplied credential or current `DSH_*` fact wins over the
- * scrub that dropped its ambient namesake.
- * @param extra - explicit caller entries merged after the scrubbed parent.
+ * parent base using the target platform's environment-key semantics. A string
+ * deliberately restores or overrides an entry; an explicit `undefined`
+ * tombstone removes an ordinary ambient entry.
+ * @param extra - explicit caller entries and tombstones, merged after the scrub.
  * @returns the environment to hand to `spawn` for the child process.
  */
-export function childEnv(extra?: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+export function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
   const env = scrubbedParentEnv()
   if (process.platform !== 'win32') return { ...env, ...extra }
-  let entries = Object.entries(env)
+  let entries: [string, string | undefined][] = Object.entries(env)
   for (const [key, value] of Object.entries(extra ?? {})) {
     const normalized = key.toUpperCase()
     entries = entries.filter(([inherited]) => inherited.toUpperCase() !== normalized)
@@ -310,8 +311,12 @@ function signalTree(
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param internals - test-only spill-directory, platform, and taskkill overrides.
  * @returns live subprocess handle.
+ * @throws when `graceMs` cannot be represented by one Node timer.
  */
 export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): SubprocessHandle {
+  if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0 || spec.graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
@@ -354,7 +359,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const stdoutCollector = collectStream(outMode, child.stdout, 'stdout')
   const stderrCollector = collectStream(errMode, child.stderr, 'stderr')
 
-  let graceTimer: NodeJS.Timeout | undefined
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  let treeExitObserved = false
+  let treeExitObservation: Promise<void> | undefined
   let settled = false
 
   // Failed spawns use pid -1 so signalling remains a no-op.
@@ -362,6 +369,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
 
   /** Whether the detached tree's root (or POSIX group) is still alive. */
   const treeAlive = (): boolean => {
+    /* v8 ignore next -- only a timer callback already queued when the observer settles can enter here;
+       the guard is the final defense against probing an id after its tree was confirmed absent. */
+    if (treeExitObserved) return false
     if (pid <= 0) return false
     if (platform === 'win32') {
       // Windows has no group-liveness probe; the direct child's exit is the
@@ -389,19 +399,40 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
   }
 
+  /**
+   * Start or reuse the handle's single whole-tree exit observer. The first
+   * confirmed absence is a permanent no-more-signals boundary: it cancels a
+   * pending escalation before this process-group id can be reused.
+   */
+  const observeTreeExit = (): Promise<void> => {
+    treeExitObservation ??= (async () => {
+      while (treeAlive()) await sleepTick()
+      treeExitObserved = true
+      if (graceTimer !== undefined) clearTimeout(graceTimer)
+      graceTimer = undefined
+    })()
+    return treeExitObservation
+  }
+
   // The escalation's tier primitive (not on the handle — terminate() is the
   // only consumer-facing termination verb). Guards on TREE liveness, not
   // outcome settlement: a TERM-trapping helper can outlive the settled direct
   // child and must stay signalable, while a fully-dead tree (possible pid
   // reuse) must not be re-signalled by a later tier.
   const kill = (sig: NodeJS.Signals): void => {
+    /* v8 ignore next -- the shared exit observer cancels the ordinary dead-tree timer;
+       this remains the timer/death race guard and cannot be staged deterministically. */
     if (!treeAlive()) return
     signalTree(platform, pid, sig, child, taskkill)
   }
 
   const terminate = (): void => {
-    if (graceTimer !== undefined) return // escalation already in flight
-    if (!treeAlive()) return
+    if (treeExitObserved || graceTimer !== undefined) return
+    // Observe from the first termination tier onward, even when inherited
+    // pipes delay `done` and no consumer has begun its own teardown wait.
+    void observeTreeExit()
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await.
+    if (treeExitObserved) return
     kill('SIGTERM')
     // The escalation must survive direct-child settlement — the leader dying
     // does not mean the tree died — so settle does not clear this timer, and
@@ -423,7 +454,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   }
 
   const done = new Promise<SubprocessOutcome>((resolve, reject) => {
-    let pipeDrainTimer: NodeJS.Timeout | undefined
+    let pipeDrainTimer: ReturnType<typeof setTimeout> | undefined
     const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
       if (settled) return
       settled = true
@@ -446,7 +477,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
       // A surviving descendant that inherited a pipe must not hold the
       // outcome open indefinitely: after exit, the same bounded grace that
       // governs kills also bounds the close wait.
-      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
+      pipeDrainTimer = setTimeout(() => {
+        settle(exitCode, signal)
+      }, spec.graceMs)
     })
     child.on('close', settle)
     function cleanup(): void {
@@ -458,11 +491,23 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   })
 
   const waitForExit = async (signal?: AbortSignal): Promise<boolean> => {
-    while (treeAlive()) {
-      if (signal?.aborted) return false
-      await sleepTick()
+    const observed = observeTreeExit()
+    if (treeExitObserved) return true
+    if (signal?.aborted) return false
+    if (signal === undefined) {
+      await observed
+      return true
+    }
+    const aborted = Promise.withResolvers<boolean>()
+    const onAbort = (): void => { aborted.resolve(false) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    /* v8 ignore next -- closes the event-loop race between the preceding aborted check and listener registration. */
+    if (signal.aborted) onAbort()
+    try {
+      return await Promise.race([observed.then(() => true), aborted.promise])
+    } finally {
+      signal.removeEventListener('abort', onAbort)
     }
-    return true
   }
 
   return {
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index f28f741992..6bac46ac16 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -280,18 +280,18 @@ describe('spawnSubprocess', () => {
 
   it('does not wait for a Linux group that has only zombie members', async () => {
     const pidFile = join(spillDir, `zombie-group-${Date.now()}.pid`)
-    let hasLiveMembers = false
     const running = spawnSubprocess(spec(`sleep 60 & echo $! > ${pidFile}; echo leader-done`, { graceMs: 100 }), {
       platform: 'linux',
-      linuxProcessGroupHasLiveMembers: () => hasLiveMembers,
+      linuxProcessGroupHasLiveMembers: () => false,
     })
     const descendant = await waitForPidFile(pidFile)
     try {
       await running.done
       await expect(running.waitForExit()).resolves.toBe(true)
     } finally {
-      hasLiveMembers = true
-      running.terminate()
+      // The confirmed-absent verdict is a permanent no-more-signals boundary,
+      // so terminate() must stay inert here; reap the live survivor directly.
+      process.kill(descendant, 'SIGKILL')
       await waitGone(descendant)
     }
   })
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 5e93edd997..cf44d9aace 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/README.i18n.yaml
@@ -1,6 +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/code-runtime/code-runtime-subprocess/README.md
-README.md: 152921a1ed595676781aad170e3396f7ce613161
-README.zh.md: 3e8223c33c7ce85f342c9a36ab5a24c4d2a6cb94
+#   pnpm run verify-translation-pairing --write packages/typert/README.md
+README.md: ad9f843e48be0e3be85921ed8fd3ca4e2c327160
+README.zh.md: 0d4be016b766178b54f7e269583fa4200e3eb24b
diff --git a/packages/ui/app-boot/tsdown.config.ts b/packages/ui/app-boot/tsdown.config.ts
index 33db6be1b8..88492d7c26 100644
--- a/packages/ui/app-boot/tsdown.config.ts
+++ b/packages/ui/app-boot/tsdown.config.ts
@@ -1,6 +1,9 @@
 import { defineConfig } from 'tsdown'
 
-/** Bundle the host plugin and its dependency-free eval runner. */
+/**
+ * Embed Include while keeping Loader external so the built include tree and
+ * app host bind to one Loader peer.
+ */
 export default defineConfig({
   entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
@@ -10,4 +13,7 @@ export default defineConfig({
   fixedExtension: false,
   dts: false,
   clean: false,
+  deps: {
+    alwaysBundle: ['@cordisjs/plugin-include'],
+  },
 })
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index efcd06f845..33e1f6014b 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.i18n.yaml
@@ -1,6 +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/code-runtime/code-runtime-subprocess/README.md
-README.md: 897112a32fa3e776df756d4caaba97b617c6af9e
-README.zh.md: d9ab3713640fe955d2b36a8f0674f77686e4791b
+#   pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
+README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
+README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
deleted file mode 100644
index 95da563dbb..0000000000
--- a/packages/util/atomic-write/src/runner-source.generated.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
- * Generated dependency-free execution-world runner.
- * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
- */
-
-export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{spawn as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{Worker as i,isMainThread as a,parentPort as o,workerData as s}from\"node:worker_threads\";const c=Reflect.apply,l=Array.isArray,u=Buffer,d=Reflect.get(Buffer,`byteLength`),f=Object.create,p=Object.defineProperty,ee=Object.keys,te=String,ne=Reflect.get(String.prototype,`charCodeAt`),re=Reflect.get(String.prototype,`codePointAt`),ie=Reflect.get(String.prototype,`slice`);function m(e){let t=f(null);return t.value=e,t}function ae(e,t,n){let r=m(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function h(e){return c(d,u,[e,`utf8`])}function g(e,t){ae(e,e.length,t)}function _(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,m(t)),n}function v(e,t){return c(ie,e,[t,t+(c(re,e,[t])>65535?2:1)])}function y(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=c(ne,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:h(e)}function b(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=v(e,r);if(n+=y(i),n>t)return;r+=i.length}return n}function x(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=_(i);e!==void 0;e=_(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=b(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(h(te(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(l(a)){if(!r(2))return;a.length>0&&g(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=ee(a);e.length>0&&g(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=b(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:s})}return n}function oe(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=v(e,i),o=y(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:c(ie,e,[0,r])}const se=Reflect.get(Function.prototype,`toString`),S=Reflect.get(Reflect,`apply`),C=Error,ce=Set,w=Array.isArray,le=Array.prototype,T=Number.isFinite,ue=Number.isSafeInteger,de=Object.create,E=Object.defineProperty,fe=Object.getOwnPropertyDescriptor,D=Object.getPrototypeOf,O=Object.hasOwn,k=Object.is,pe=Object.keys,A=Object.prototype,me=Reflect.get(A,`propertyIsEnumerable`),j=Reflect.ownKeys,he=Reflect.get(Set.prototype,`add`),ge=Reflect.get(Set.prototype,`delete`),_e=Reflect.get(Set.prototype,`has`);function M(e){let t=de(null);return t.value=e,t}function N(e,t,n){let r=M(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,E(e,t,r)}function P(e,t){N(e,e.length,t)}function F(e){if(e.length===0)return;let t=e.length-1,n=e[t];return E(e,`length`,M(t)),n}function I(e,t){return S(_e,e,[t])}function L(e,t){S(he,e,[t])}function ve(e,t){S(ge,e,[t])}function R(e,t){let n=fe(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&S(se,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function z(e){return D(e)===null&&R(e,`Object`)}function B(e){let t=D(e);if(t===le)return!0;if(!w(t)||!R(t,`Array`))return!1;let n=D(t);return typeof n==`object`&&!!n&&z(n)}function V(e){let t=D(e);return t===null||t===A||typeof t==`object`&&z(t)}function ye(e){let t=j(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!S(me,e,[r]))return}return t}function H(e){let t=new ce,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?N(e.target,e.index,t):N(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=F(i);e!==void 0;e=F(i)){if(e.kind===`leave`){ve(t,e.source);continue}if(e.kind===`array-item`){if(!O(e.source,e.index))return;P(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){P(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!T(n)||k(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||I(t,n))return;if(w(n)){if(!B(n))return;let a=n.length;if(j(n).length!==a+1)return;let o=[];r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)P(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!V(n))return;let a=ye(n);if(a===void 0)return;let o={};r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;P(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=F(n);e!==void 0;e=F(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){P(t,e);continue}if(w(e)){P(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new C(`cannot encode a sparse JSON array`);P(n,r)}continue}let r=pe(e);P(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new C(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new C(`cannot encode an undefined JSON object property`);P(n,a)}}return t}function be(e){if(!B(e)||j(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!O(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function xe(e){if(w(e)||!V(e))return;let t=ye(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&ue(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!w(e)||!be(e))return;let r=new ce,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||I(r,t))return;L(r,t),P(i,t)}return{kind:`object`,keys:i}}}function Se(e){try{if(!w(e)||!be(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)P(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;N(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!T(r)||k(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=xe(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&P(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;F(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=b(e,n);if(r===void 0){this.truncated=!0;let r=oe(e,n);if(r.length>0){let e=b(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):x(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return b(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function K(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=Se(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(K(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&x(l,a)===void 0?Promise.reject(K(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(K(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(K(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&x(f,r)===void 0?{type:`output-limit`}:f)}function q(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let J=0;function Ve(){let e=process.execArgv.indexOf(`--eval`);if(e<0)throw Error(`code runtime runner requires its eval source`);let t=process.execArgv[e+1];if(t===void 0)throw Error(`code runtime runner requires its eval source`);return t}function Y(e){return typeof e==`object`&&e?e:void 0}function X(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function He(e){process.stdout.write(e),process.stdout.write(`\n`)}function Ue(e){let t=X(e,J);return t===void 0?!1:(He(t),!0)}function We(e){let t=Y(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function Ge(e){return We(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ke(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Z(e){let t=Y(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=Y(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=Se(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,i=0,a=2,o=0,s=!1,c=t=>{if(s)return;let n=X(t,J)??X($(),J);s=!0,n!==void 0&&He(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},l=e=>{if(s)return;let t=+(o>0),n=b(e,i-a-t);if(n===void 0){c({type:`output-limit`});return}a+=n+t,o+=1,Ue({type:`log`,text:e})||c($())},u=e=>{i=e.maxOutputBytes,J=e.maxFrameBytes,r=t(process.execPath,process.execArgv,{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{l(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{l(e.toString(`utf8`))}),n.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){l(t.text);return}if(!s){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)Ue({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,We);e!==void 0&&c(e)}}}}),n.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{s||c({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Z(t);if(e===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}u(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!s&&c({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let t,n=!1,a,o=0,s=e=>process.send===void 0||o>0&&X(e,o)===void 0?!1:(process.send(e),!0),c=e=>{if(n)return;n=!0,clearInterval(a);let r=o>0&&X(e,o)===void 0?$():e,i=t;t=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr);await Promise.all([i.terminate(),e,t])})).catch(e=>{s({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(r,()=>{process.connected&&process.disconnect()})})};process.on(`message`,l=>{if(t===void 0){let u=Z(l);if(u===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}o=u.maxFrameBytes,t=new i(new URL(`data:text/javascript;base64,${e.from(Ve()).toString(`base64`)}`),{workerData:u,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:u.maxOldGenerationSizeMb}});let d=t;d.stdout.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.stderr.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)s({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`log`&&typeof t.text==`string`)s({type:`log`,text:t.text})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,Ge);e!==void 0&&c(e)}}}),d.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),d.on(`exit`,e=>{n||c({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),a=setInterval(()=>{t!==void 0&&t.performance.eventLoopUtilization().active>u.computeMs&&c({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${u.computeMs}ms busy)`}})},25);return}let u=qe(l);u!==void 0&&t.postMessage(u)}),process.on(`disconnect`,()=>{t!==void 0&&!n&&t.terminate()})}if(a)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(o===null)throw Error(`remote worker requires parentPort`);let e=s;ze(o,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
deleted file mode 100644
index 2655d22026..0000000000
--- a/packages/util/atomic-write/src/runner.ts
+++ /dev/null
@@ -1,401 +0,0 @@
-/** Typed source for the dependency-free execution-world runner bundle. */
-
-import { Buffer } from 'node:buffer'
-import { spawn } from 'node:child_process'
-import type { ChildProcess } from 'node:child_process'
-import { createInterface } from 'node:readline'
-import type { Readable } from 'node:stream'
-import { inspect } from 'node:util'
-import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
-import {
-  decodeWorkerJson,
-  encodeWorkerJson,
-  jsonStringBytesUpTo,
-  runWorkerMain,
-  waitForRuntimePipeDrain,
-} from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
-import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
-
-type WorkerBootData = Parameters<typeof runWorkerMain>[1]
-type Controller = ChildProcess & { stdout: Readable; stderr: Readable }
-type FailureKind = 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
-
-interface RuntimeBootData extends WorkerBootData {
-  type: 'boot'
-  maxFrameBytes: number
-  maxOldGenerationSizeMb: number
-  computeMs: number
-}
-
-interface RuntimeFailure {
-  kind: FailureKind
-  message: string
-}
-
-interface RuntimeCall {
-  type: 'call'
-  id: number
-  global: string
-  name: string
-  args: WorkerJsonWire | null
-}
-
-type RuntimeReply =
-  | { type: 'reply'; id: number; ok: true; value: unknown }
-  | { type: 'reply'; id: number; ok: false; message: string }
-
-type RuntimeMessage = RuntimeCall
-  | { type: 'log'; text: string }
-  | { type: 'output-limit' }
-  | { type: 'done'; value?: WorkerJsonWire | null; error?: RuntimeFailure }
-
-const failureKinds = new Set<FailureKind>([
-  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
-])
-
-let maxFrameBytes = 0
-
-function runnerSource(): string {
-  const evalIndex = process.execArgv.indexOf('--eval')
-  if (evalIndex < 0) throw new Error('code runtime runner requires its eval source')
-  const source = process.execArgv[evalIndex + 1]
-  if (source === undefined) throw new Error('code runtime runner requires its eval source')
-  return source
-}
-
-function recordOf(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
-}
-
-function encodeJsonBounded(value: unknown, maxBytes: number): string | undefined {
-  try {
-    const json: unknown = JSON.stringify(value)
-    return typeof json === 'string' && Buffer.byteLength(json) <= maxBytes ? json : undefined
-  } catch {
-    return undefined
-  }
-}
-
-function emitJson(json: string): void {
-  process.stdout.write(json)
-  process.stdout.write('\n')
-}
-
-function emitFrame(message: RuntimeMessage): boolean {
-  const json = encodeJsonBounded(message, maxFrameBytes)
-  if (json === undefined) return false
-  emitJson(json)
-  return true
-}
-
-function validFailure(value: unknown): value is RuntimeFailure {
-  const record = recordOf(value)
-  return record !== undefined
-    && typeof record.kind === 'string'
-    && failureKinds.has(record.kind as FailureKind)
-    && typeof record.message === 'string'
-}
-
-function validWorkerFailure(value: unknown): value is RuntimeFailure {
-  return validFailure(value)
-    && (value.kind === 'exception' || value.kind === 'invalid-output' || value.kind === 'output-limit')
-}
-
-function doneMessage(
-  message: Record<string, unknown>,
-  acceptsFailure: (value: unknown) => value is RuntimeFailure,
-): RuntimeMessage | undefined {
-  if (message.error !== undefined) {
-    return acceptsFailure(message.error) ? { type: 'done', error: message.error } : undefined
-  }
-  return { type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } }
-}
-
-function runtimeBoot(value: unknown): RuntimeBootData | undefined {
-  const record = recordOf(value)
-  if (record === undefined
-    || record.type !== 'boot'
-    || typeof record.code !== 'string'
-    || !Array.isArray(record.namespaces)
-    || !Number.isSafeInteger(record.maxOutputBytes)
-    || (record.maxOutputBytes as number) < 4
-    || !Number.isSafeInteger(record.maxFrameBytes)
-    || (record.maxFrameBytes as number) < (record.maxOutputBytes as number)
-    || typeof record.computeMs !== 'number'
-    || !Number.isFinite(record.computeMs)
-    || (record.computeMs) <= 0
-    || typeof record.maxOldGenerationSizeMb !== 'number'
-    || !Number.isFinite(record.maxOldGenerationSizeMb)
-    || (record.maxOldGenerationSizeMb) <= 0) return undefined
-  return record as unknown as RuntimeBootData
-}
-
-function runtimeReply(value: unknown): RuntimeReply | undefined {
-  const record = recordOf(value)
-  if (record === undefined || record.type !== 'reply' || typeof record.id !== 'number' || typeof record.ok !== 'boolean') return undefined
-  return record.ok
-    ? { type: 'reply', id: record.id, ok: true, value: record.value }
-    : { type: 'reply', id: record.id, ok: false, message: String(record.message) }
-}
-
-function transportWireOrNull(input: unknown): WorkerJsonWire | null {
-  const value = decodeWorkerJson(input)
-  return value === undefined ? null : encodeWorkerJson(value)
-}
-
-function waitForChildExit(child: ChildProcess): Promise<void> {
-  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise((resolve) => { child.once('exit', () => { resolve() }) })
-}
-
-function frameLimitFailure(): RuntimeMessage {
-  return {
-    type: 'done',
-    error: { kind: 'worker-exit', message: 'code runtime bridge frame exceeded maxFrameBytes' },
-  }
-}
-
-function runLauncher(): void {
-  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  let controller: Controller | undefined
-  let maxOutputBytes = 0
-  let logBytes = 2
-  let logEntries = 0
-  let settling = false
-
-  const finish = (message: RuntimeMessage): void => {
-    if (settling) return
-    const encoded = encodeJsonBounded(message, maxFrameBytes)
-      ?? encodeJsonBounded(frameLimitFailure(), maxFrameBytes)
-    settling = true
-    if (encoded !== undefined) emitJson(encoded)
-    const current = controller
-    controller = undefined
-    const drain = current === undefined
-      ? Promise.resolve()
-      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
-        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
-        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
-        const exited = waitForChildExit(current)
-        current.kill('SIGKILL')
-        await Promise.all([exited, stdoutDrained, stderrDrained])
-      })
-    void drain.catch((error: unknown) => {
-      process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(error)}\n`)
-    }).then(() => {
-      input.close()
-      process.stdin.destroy()
-    })
-  }
-
-  const forwardLog = (text: string): void => {
-    if (settling) return
-    const separator = logEntries > 0 ? 1 : 0
-    const cost = jsonStringBytesUpTo(text, maxOutputBytes - logBytes - separator)
-    if (cost === undefined) {
-      finish({ type: 'output-limit' })
-      return
-    }
-    logBytes += cost + separator
-    logEntries += 1
-    if (!emitFrame({ type: 'log', text })) finish(frameLimitFailure())
-  }
-
-  const startController = (boot: RuntimeBootData): void => {
-    maxOutputBytes = boot.maxOutputBytes
-    maxFrameBytes = boot.maxFrameBytes
-    controller = spawn(process.execPath, process.execArgv, {
-      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
-      detached: false,
-      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-    }) as Controller
-    const current = controller
-    current.stdout.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
-    current.stderr.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
-    current.on('message', (raw: unknown) => {
-      const message = recordOf(raw)
-      if (message === undefined) return
-      if (message.type === 'log' && typeof message.text === 'string') {
-        forwardLog(message.text)
-        return
-      }
-      if (settling) return
-      if (message.type === 'call'
-        && typeof message.id === 'number'
-        && typeof message.global === 'string'
-        && typeof message.name === 'string') {
-        if (!emitFrame({
-          type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
-        })) finish(frameLimitFailure())
-      } else if (message.type === 'output-limit') {
-        finish({ type: 'output-limit' })
-      } else if (message.type === 'done') {
-        const done = doneMessage(message, validFailure)
-        if (done !== undefined) finish(done)
-      }
-    })
-    current.on('error', (error: Error) => {
-      finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller error: ${error.message}` } })
-    })
-    current.on('exit', (code: number | null) => {
-      if (!settling) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller exited with code ${code} before completing` } })
-      }
-    })
-    current.send(boot, (error: Error | null) => {
-      if (error !== null) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller boot failed: ${error.message}` } })
-      }
-    })
-  }
-
-  input.on('line', (line: string) => {
-    let raw: unknown
-    try {
-      raw = JSON.parse(line) as unknown
-    } catch (error: unknown) {
-      process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(error)}\n`)
-      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
-      return
-    }
-    if (controller === undefined) {
-      const boot = runtimeBoot(raw)
-      if (boot === undefined) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
-        return
-      }
-      startController(boot)
-      return
-    }
-    const reply = runtimeReply(raw)
-    if (reply !== undefined) {
-      controller.send(reply, (error: Error | null) => {
-        if (error !== null) {
-          finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller reply failed: ${error.message}` } })
-        }
-      })
-    }
-  })
-  input.on('close', () => {
-    if (controller !== undefined && !settling) {
-      finish({ type: 'done', error: { kind: 'abort', message: 'remote runner input closed' } })
-    }
-  })
-}
-
-function runController(): void {
-  let worker: Worker | undefined
-  let finished = false
-  let computeTimer: NodeJS.Timeout | undefined
-  let controllerMaxFrameBytes = 0
-
-  const send = (message: RuntimeMessage): boolean => {
-    if (process.send === undefined) return false
-    if (controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined) return false
-    process.send(message)
-    return true
-  }
-
-  const finish = (message: RuntimeMessage): void => {
-    if (finished) return
-    finished = true
-    clearInterval(computeTimer)
-    const bounded = controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined
-      ? frameLimitFailure()
-      : message
-    const current = worker
-    worker = undefined
-    const drain = current === undefined
-      ? Promise.resolve()
-      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
-        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
-        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
-        await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
-      })
-    void drain.catch((error: unknown) => {
-      send({ type: 'log', text: `dsh-code-runtime-subprocess worker cleanup error: ${String(error)}\n` })
-    }).then(() => {
-      if (process.send === undefined) {
-        process.exitCode = 1
-        return
-      }
-      process.send(bounded, () => { if (process.connected) process.disconnect() })
-    })
-  }
-
-  process.on('message', (raw: unknown) => {
-    if (worker === undefined) {
-      const boot = runtimeBoot(raw)
-      if (boot === undefined) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
-        return
-      }
-      controllerMaxFrameBytes = boot.maxFrameBytes
-      const sourceUrl = new URL(`data:text/javascript;base64,${Buffer.from(runnerSource()).toString('base64')}`)
-      worker = new Worker(sourceUrl, {
-        workerData: boot,
-        env: {},
-        execArgv: [],
-        stdout: true,
-        stderr: true,
-        resourceLimits: { maxOldGenerationSizeMb: boot.maxOldGenerationSizeMb },
-      })
-      const current = worker
-      current.stdout.on('data', (data: Buffer) => {
-        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
-      })
-      current.stderr.on('data', (data: Buffer) => {
-        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
-      })
-      current.on('message', (messageRaw: unknown) => {
-        const message = recordOf(messageRaw)
-        if (message === undefined) return
-        if (message.type === 'call'
-          && typeof message.id === 'number'
-          && typeof message.global === 'string'
-          && typeof message.name === 'string') {
-          if (!send({
-            type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
-          })) finish(frameLimitFailure())
-        } else if (message.type === 'log' && typeof message.text === 'string') {
-          if (!send({ type: 'log', text: message.text })) finish(frameLimitFailure())
-        } else if (message.type === 'output-limit') {
-          finish({ type: 'output-limit' })
-        } else if (message.type === 'done') {
-          const done = doneMessage(message, validWorkerFailure)
-          if (done !== undefined) finish(done)
-        }
-      })
-      current.on('error', (error: Error) => {
-        finish({
-          type: 'done',
-          error: { kind: 'worker-exit', message: `worker error: ${error.stack || error.message || inspect(error)}` },
-        })
-      })
-      current.on('exit', (code: number) => {
-        if (!finished) {
-          finish({ type: 'done', error: { kind: 'worker-exit', message: `worker exited with code ${code} before completing` } })
-        }
-      })
-      computeTimer = setInterval(() => {
-        if (worker !== undefined && worker.performance.eventLoopUtilization().active > boot.computeMs) {
-          finish({ type: 'done', error: { kind: 'timeout', message: `compute budget exhausted (${boot.computeMs}ms busy)` } })
-        }
-      }, 25)
-      return
-    }
-    const reply = runtimeReply(raw)
-    if (reply !== undefined) worker.postMessage(reply)
-  })
-  process.on('disconnect', () => { if (worker !== undefined && !finished) void worker.terminate() })
-}
-
-if (!isMainThread) {
-  if (parentPort === null) throw new Error('remote worker requires parentPort')
-  const boot = workerData as RuntimeBootData
-  void runWorkerMain(parentPort, boot, { stdout: process.stdout, stderr: process.stderr }, boot.maxFrameBytes)
-} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
-  runController()
-} else {
-  runLauncher()
-}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 666d01c1c1..87648e01e1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4275,6 +4275,12 @@ importers:
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
         version: link:../../util/brand
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-fs-local':
+        specifier: workspace:^
+        version: link:../../fs/fs-local
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4312,6 +4318,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-fs-local':
+        specifier: workspace:^
+        version: link:../../fs/fs-local
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4327,6 +4336,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -4440,9 +4452,6 @@ importers:
 
   packages/pty/pty-local:
     dependencies:
-      node-pty:
-        specifier: ^1.1.0
-        version: 1.1.0(patch_hash=7a0c04f1f49d798a9ffe2f7f414c01064a44ca2489772d0c3e1235ab336755e6)
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
@@ -4468,6 +4477,9 @@ importers:
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -4563,6 +4575,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -5940,6 +5955,10 @@ importers:
         version: link:../../../vendor/cordis
 
   packages/subprocess/subprocess-local:
+    dependencies:
+      node-pty:
+        specifier: ^1.1.0
+        version: 1.1.0(patch_hash=7a0c04f1f49d798a9ffe2f7f414c01064a44ca2489772d0c3e1235ab336755e6)
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 00520bdbe7..e254696491 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -48,9 +48,13 @@ interface EventRelation {
   listeners: Set<string>
 }
 
-interface PackageSource {
+/** One scanned package source file and its owning package short name. */
+export interface PackageSource {
+  /** Repository-relative path. */
   rel: string
+  /** Package short name from the `packages/<group>/<pkg>/src` path. */
   pkg: string
+  /** The bound program source file. */
   sourceFile: ts.SourceFile
 }
 
@@ -120,7 +124,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -155,6 +159,24 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
+  {
+    key: 'settings',
+    pkg: 'settings',
+    title: 'User-settings seam',
+    mode: 'seam',
+    implementations: ['settings-local'],
+    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
+    note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer.',
+  },
+  {
+    key: 'credentials',
+    pkg: 'credentials',
+    title: 'Credential seam',
+    mode: 'seam',
+    implementations: ['credentials-local'],
+    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
+    note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage.',
+  },
   {
     key: 'telemetry',
     pkg: 'session-telemetry',
@@ -203,7 +225,6 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session-reference',
     title: 'Cross-session snapshot preparation',
     mode: 'core',
-    consumers: ['tui'],
     note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
   },
   {
@@ -235,8 +256,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'user-interaction',
     title: 'Human question/answer seam',
     mode: 'seam',
-    implementations: ['tui'],
-    consumers: ['tool-ask-user', 'tui'],
+    consumers: ['tool-ask-user'],
     note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
   },
   {
@@ -251,8 +271,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'commands',
     title: 'Human command registry',
     mode: 'core',
-    consumers: ['tui'],
-    note: 'Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model.',
+    note: 'Plugins register direct human commands without sending invocations to the model.',
   },
   {
     key: 'sessionProjections',
@@ -270,19 +289,12 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['host-apiproxy'],
     note: 'Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs.',
   },
-  {
-    key: 'tui',
-    pkg: 'tui',
-    title: 'Mounted-terminal interaction service',
-    mode: 'bundle',
-    note: 'One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state.',
-  },
   {
     key: 'skills',
     pkg: 'skill',
     title: 'Skill provider registry',
     mode: 'seam',
-    implementations: ['skill-local'],
+    implementations: ['skill-badge', 'skill-local'],
     consumers: ['tool-skill'],
     note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
   },
@@ -291,7 +303,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'agent',
     title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo'],
+    consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
   {
@@ -315,24 +327,25 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Subprocess seam',
     mode: 'seam',
     implementations: ['subprocess-local'],
-    consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp'],
-    note: 'The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
+    consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
+    note: 'The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
   },
   {
     key: 'bash',
     pkg: 'bash',
     title: 'Bash executor seam',
     mode: 'seam',
-    implementations: ['bash-local', 'bash-sandbox'],
-    consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
-    note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them.',
+    implementations: ['bash-local', 'bash-sandbox', 'pwsh-local'],
+    consumers: ['tool-bash', 'tool-pwsh', 'hooks-claude', 'hooks-codex'],
+    note: 'The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them.',
   },
   {
     key: 'bashEnv',
-    pkg: 'tool-bash',
+    pkg: 'bash-env',
     title: 'Managed bash environment registry',
     mode: 'core',
-    note: 'Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace.',
+    consumers: ['tool-bash', 'tool-pwsh'],
+    note: 'Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace.',
   },
   {
     key: 'pty',
@@ -409,11 +422,11 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'subagents',
     pkg: 'subagent',
-    title: 'Subagent provider registry',
+    title: 'Subagent provider and continuation service',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
-    consumers: ['tool-subagent', 'tool-ralph'],
-    note: 'Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route.',
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
+    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
+    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
   },
   {
     key: 'tasks',
@@ -592,7 +605,8 @@ function parseExampleCordis(rel: string): ExamplePlugin[] {
     if (current?.name) plugins.push({ id: current.id, name: current.name })
   }
   for (const line of text.split('\n')) {
-    const id = /^-\s+id:\s+(.+?)\s*$/.exec(line)
+    // Top-level rows (`- id:`) and bundle-patch insert rows (`    - id:`).
+    const id = /^\s*-\s+id:\s+(.+?)\s*$/.exec(line)
     if (id?.[1] !== undefined) {
       flush()
       current = { id: stripYamlScalar(id[1]) }
@@ -611,28 +625,20 @@ function stripYamlScalar(value: string): string {
 
 const APP_EXAMPLES = [
   {
-    id: 'tui',
-    rel: 'examples/tui-agent/composition.md',
-    title: 'TUI Agent App Composition',
-    label: 'examples/tui-agent',
-    config: 'examples/tui-agent/cordis.yml',
-    summary: 'The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package.',
+    id: 'dsh_base',
+    rel: 'apps/cli/composition.md',
+    title: 'DSH Base Composition',
+    label: 'packages/bundle/base/cordis.patch.yml',
+    config: 'packages/bundle/base/cordis.patch.yml',
+    summary: 'The dsh-base bundle patch every profile applies first; mode bundles (dsh-web-app, dsh-headless) and the user\'s profile layer patch over it.',
   },
   {
     id: 'headless',
     rel: 'examples/headless-agent/composition.md',
-    title: 'Headless Agent App Composition',
+    title: 'Headless Agent Snapshot Composition',
     label: 'examples/headless-agent',
     config: 'examples/headless-agent/cordis.yml',
-    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
-  },
-  {
-    id: 'cordis',
-    rel: 'examples/cordis-agent/composition.md',
-    title: 'Cordis Agent App Composition',
-    label: 'examples/cordis-agent',
-    config: 'examples/cordis-agent/cordis.yml',
-    summary: 'The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its current-process runtime and mount or unmount in-memory temporary Plugins.',
+    summary: 'The headless snapshot composition combines the real DeepSeek adapter and coding capabilities with one explicitly configured persisted top-level agent; its JSONL driver is test-only.',
   },
   {
     id: 'acp',
@@ -651,11 +657,7 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
-  if (pluginName === '@deepseek-ai/dsh-tui-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'tui')}["@deepseek-ai/dsh-tui<br/>pre-created main agent"]`)
-  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
-  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
+  if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
   }
   lines.push(
@@ -681,7 +683,7 @@ function renderAppComposition(example: AppExample): string {
     const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-tui-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
+    if (plugin.name === '@deepseek-ai/dsh-acp-demo') {
       renderAppExpansion(lines, pluginNode, plugin.name)
     }
   }
@@ -698,13 +700,26 @@ function renderAppComposition(example: AppExample): string {
   return lines.join('\n')
 }
 
+type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
+
+/**
+ * The only method names visitSource classifies; receiver typing runs on these
+ * alone. Obligation: every method name matched by a branch inside visitSource
+ * must appear here — the prefilter drops non-members before any branch runs,
+ * so a branch for an unlisted name is silently dead.
+ */
+const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
+
 /** Collect event dispatch/listener relations from real cross-file receiver types. */
-class EventRelationCollector {
+export class EventRelationCollector {
   private readonly relations = new Map<string, EventRelation>()
-  private readonly callSites = new Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>()
+  private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
+  private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
+  private globalCallSites: CallSiteIndex | null = null
   private readonly contextType: ts.Type
   private readonly agentDispatchType: ts.Type
   private readonly eventsServiceType: ts.Type
+  private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
 
   constructor(
     private readonly project: TypeScriptProject,
@@ -713,7 +728,7 @@ class EventRelationCollector {
     this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
     this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
     this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
-    this.indexCallSites()
+    this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
   }
 
   /** Return all event relations discovered from the Program. */
@@ -733,20 +748,88 @@ class EventRelationCollector {
     return this.project.checker.getDeclaredTypeOfSymbol(symbol)
   }
 
-  /** Index resolved local function calls for narrow argument-flow recovery. */
-  private indexCallSites(): void {
+  /** Index resolved function calls in the given files for narrow argument-flow recovery. */
+  private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
+    const index: CallSiteIndex = new Map()
     const visit = (node: ts.Node): void => {
       if (ts.isCallExpression(node)) {
         const declaration = this.project.checker.getResolvedSignature(node)?.declaration
         if (declaration) {
-          const calls = this.callSites.get(declaration) ?? []
+          const calls = index.get(declaration) ?? []
           calls.push(node)
-          this.callSites.set(declaration, calls)
+          index.set(declaration, calls)
         }
       }
       ts.forEachChild(node, visit)
     }
-    for (const source of this.sources) visit(source.sourceFile)
+    for (const file of files) visit(file)
+    return index
+  }
+
+  /**
+   * Return every indexed call resolving to one local helper declaration.
+   * Fast path: when every same-file reference to the non-exported helper is
+   * provably a direct callee, module scoping confines all of its calls to that
+   * file, so only that file is indexed. Any other reference shape may alias
+   * the function value outward, so the original full package-source index
+   * decides instead.
+   */
+  private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
+    if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
+      this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
+    }
+    if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
+    const file = owner.getSourceFile()
+    let index = this.fileCallSites.get(file)
+    if (!index) {
+      index = this.buildCallSiteIndex([file])
+      this.fileCallSites.set(file, index)
+    }
+    return index.get(owner) ?? []
+  }
+
+  /**
+   * Prove every same-file reference to one helper is a direct callee. The
+   * proof owns its premises: an exported helper or a helper in a global
+   * script file (no import/export means program-wide scope, callable from
+   * another file with no same-file reference at all) fails immediately.
+   * Alias escapes (re-export statements, default exports, value reads)
+   * resolve back to the owner symbol at a non-callee position and fail the
+   * proof, as does anything the scan cannot positively classify.
+   */
+  private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
+    const cached = this.localCalleeProofs.get(owner)
+    if (cached !== undefined) return cached
+    if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
+      this.localCalleeProofs.set(owner, false)
+      return false
+    }
+    const name = owner.name
+    const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
+    let proven = !!ownerSymbol
+    const refersToOwner = (identifier: ts.Identifier): boolean => {
+      // Shorthand properties resolve to the property symbol; ask for the value side.
+      const local = ts.isShorthandPropertyAssignment(identifier.parent)
+        ? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
+        : this.project.checker.getSymbolAtLocation(identifier)
+      if (!local) return false
+      const symbol = local.flags & ts.SymbolFlags.Alias
+        ? this.project.checker.getAliasedSymbol(local)
+        : local
+      return symbol === ownerSymbol
+    }
+    const visit = (node: ts.Node): void => {
+      if (!proven) return
+      if (ts.isIdentifier(node) && node !== name && node.text === name?.text
+        && !isDirectCallee(node) && refersToOwner(node)) {
+        proven = false
+        return
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(owner.getSourceFile())
+    this.localCalleeProofs.set(owner, proven)
+    return proven
   }
 
   /** Walk one package source file and classify event API calls by receiver type. */
@@ -760,7 +843,7 @@ class EventRelationCollector {
               this.addDispatcher(name, source.pkg, 'emitAgentEvent')
             }
           }
-        } else if (ts.isPropertyAccessExpression(node.expression)) {
+        } else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
           const receiverKind = this.receiverKind(node.expression.expression)
           const method = node.expression.name.text
           if (receiverKind === 'events-service' && method === 'dispatch') {
@@ -863,7 +946,7 @@ class EventRelationCollector {
     const index = owner.parameters.indexOf(parameter)
     if (index < 0) return new Set()
     const events = new Set<string>()
-    for (const call of this.callSites.get(owner) ?? []) {
+    for (const call of this.callSitesFor(owner)) {
       const argument = call.arguments[index]
       if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
     }
@@ -910,6 +993,21 @@ class EventRelationCollector {
   }
 }
 
+/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
+function isDirectCallee(identifier: ts.Identifier): boolean {
+  let current: ts.Node = identifier
+  while (
+    ts.isParenthesizedExpression(current.parent)
+    || ts.isAsExpression(current.parent)
+    || ts.isTypeAssertionExpression(current.parent)
+    || ts.isNonNullExpression(current.parent)
+    || ts.isSatisfiesExpression(current.parent)
+  ) {
+    current = current.parent
+  }
+  return ts.isCallExpression(current.parent) && current.parent.expression === current
+}
+
 /** Peel syntax-only wrappers that do not change an expression's runtime value. */
 function unwrapExpression(expression: ts.Expression): ts.Expression {
   let current = expression
@@ -965,14 +1063,22 @@ function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
   return out
 }
 
-function collectEventRelations(): Map<string, EventRelation> {
-  const project = new TypeScriptProject(root)
-  const sources = project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+/**
+ * Select the package source files of one project in deterministic order.
+ * @param project - the loaded repository TypeScript project.
+ * @returns `packages/<group>/<pkg>/src` files tagged with their package name.
+ */
+export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
+  return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
     const rel = project.relativePath(sourceFile)
     const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
     return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
   }).sort((left, right) => left.rel.localeCompare(right.rel))
-  return new EventRelationCollector(project, sources).collect()
+}
+
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  return new EventRelationCollector(project, collectPackageSources(project)).collect()
 }
 
 function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
@@ -1053,20 +1159,22 @@ function renderLifecycle(): string {
     '  participant Session',
     '  participant SDK as UI or SDK listener',
     '  User->>Agent: followup(content)',
-    `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/spliced')}`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
-    '  Note over Agent,Driver: next-step acceptance window opens',
-    `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
-    '  Hooks-->>Driver: authoritative allow, block, or add context',
-    '  alt prompt blocked or admission failed',
-    '    Driver-->>Driver: append context-only batch or keep steering boundary pending',
-    '  else prompt allowed',
+    '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
+    `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
+    `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
+    `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
+    '  Hooks-->>Driver: authoritative reject or enter(messages)',
+    '  alt proposed step rejected or pre-step failed',
+    '    Driver-->>Driver: claimed batch stays removed, no turn opens',
+    '  else enter proposed step',
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
-    `  Driver->>Session: ${mermaidCode('user/message')}`,
-    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
-    `  Driver-->>Driver: ${mermaidCode('agent/step')} serial checkpoint`,
     `  Driver->>Session: ${mermaidCode('step/start')}`,
+    `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
+    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
     `  Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
     '  LLM-->>Driver: StreamChunk*',
     `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
@@ -1089,11 +1197,17 @@ function renderLifecycle(): string {
     `      Driver->>Session: ${mermaidCode('tool/result')}`,
     '    end',
     '  end',
-    '  Driver->>Session: post-tool context and steering (no prompt-submit)',
     `  Driver->>Session: ${mermaidCode('step/end')}`,
-    `  Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
+    '  opt natural stop and next-step inbox empty',
+    `    Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
+    '  end',
+    '  opt next-step input is pending',
+    '    Driver-->>Driver: claim pending next-step input',
+    `    Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
+    `    Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
+    '    Hooks-->>Driver: authoritative reject or enter(messages)',
+    '  end',
     '  end',
-    '  Note over Agent,Driver: next-step acceptance window closes',
     `  Driver->>Session: ${mermaidCode('turn/end')}`,
     '  end',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
@@ -1101,9 +1215,9 @@ function renderLifecycle(): string {
     '',
     'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
     '',
-    '`dsh-compact-basic` uses `agent/step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
+    '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
-    'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
+    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later boundary claims their next-step batch.',
     '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
@@ -1192,8 +1306,8 @@ function renderDocs(): GraphDoc[] {
 function renderIndex(docs: GraphDoc[]): string {
   const labels: Record<string, string> = {
     'docs/capability-seams.md': 'capability seams and core services',
+    'apps/cli/composition.md': 'dsh shared base composition',
     'examples/headless-agent/composition.md': 'headless-agent app composition',
-    'examples/tui-agent/composition.md': 'tui-agent app composition',
     'examples/cordis-agent/composition.md': 'cordis-agent app composition',
     'examples/acp-agent/composition.md': 'acp-agent app composition',
     'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -1202,8 +1316,8 @@ function renderIndex(docs: GraphDoc[]): string {
   }
   const modes: Record<string, string> = {
     'docs/capability-seams.md': 'hybrid generated',
+    'apps/cli/composition.md': 'hybrid generated',
     'examples/headless-agent/composition.md': 'hybrid generated',
-    'examples/tui-agent/composition.md': 'hybrid generated',
     'examples/cordis-agent/composition.md': 'hybrid generated',
     'examples/acp-agent/composition.md': 'hybrid generated',
     'docs/event-producer-consumer.md': 'hybrid generated',
diff --git a/vitest.config.ts b/vitest.config.ts
index 996f2456c7..5e6ac400ef 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,5 +1,16 @@
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
+import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
+import { vitestExecArgv } from './vitest.shared.ts'
+import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
+
+// Prints exact `path:line:col` records for every uncovered statement, branch
+// path, and function when a file misses the per-file 100% gate — the built-in
+// threshold ERRORs name only the file. Absolute path because istanbul-reports
+// require()s custom reporters (which is also why the reporter is CJS).
+const uncoveredLocationsReporter = fileURLToPath(new URL('./scripts/coverage-uncovered-locations.cjs', import.meta.url))
 
 // Resolution facade shared by every plugin instance below: tsconfig.base.json
 // has no include, which vite-tsconfig-paths treats as match-all, so its paths
@@ -9,7 +20,14 @@ const pathsPlugin = (): ReturnType<typeof tsconfigPaths> => tsconfigPaths({ proj
 
 const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
-      'packages/bash/*',
+      // Bash-requiring suites (a real POSIX shell is unavailable on Windows).
+      // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
+      // INCLUDED: PowerShell ships with Windows, so they run natively here.
+      // Replacing the old 'packages/bash/*' glob with this explicit list also
+      // newly INCLUDES packages/bash/bash (the pure seam package) on Windows.
+      'packages/bash/bash-local',
+      'packages/bash/bash-sandbox',
+      'packages/bash/tool-bash',
       'packages/hooks/*',
       'packages/subprocess/*',
       'packages/pty/pty-local',
@@ -26,10 +44,20 @@ const windowsCoverageExclusions = process.platform === 'win32'
       'packages/lsp/lsp-local/src/connection.ts',
       'packages/lsp/lsp-local/src/index.ts',
       'packages/lsp/lsp-local/src/instance.ts',
-      'packages/ui/tui/src/index.ts',
     ]
   : []
 
+// Mirrors windowsCoverageExclusions: pwsh-local's run/start/lifecycle suites
+// self-skip without a real pwsh (executor.spec.ts hasPwsh), leaving this file
+// far below per-file 100% on pwsh-less hosts; the exemption keeps those hosts
+// green while CI runners ship pwsh and still enforce the full bar. The probe
+// runs the suites' own resolution (the dependency-free resolve.ts module),
+// so the exemption is active exactly when the suites skip — a mismatched
+// narrower probe could exempt the file on hosts whose suites actually run.
+const pwshCoverageExclusions = spawnSync(resolvePwshPath(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$true'], { encoding: 'utf8' }).status === 0
+  ? []
+  : ['packages/bash/pwsh-local/src/index.ts']
+
 const testIncludes = [
   'packages/*/*/tests/**/*.spec.{ts,tsx}',
   'apps/*/tests/**/*.spec.ts',
@@ -37,6 +65,17 @@ const testIncludes = [
   'scripts/**/*.spec.ts',
 ]
 
+// The instrumented coverage gate sets this env; the exempt heavy suites then
+// run beside it uninstrumented (membership contract in scripts/coverage-exempt.ts).
+// A set-but-not-'1' value is a misconfiguration, not a silent no-op.
+const coverageExemptRaw = process.env[COVERAGE_EXEMPT_ENV]
+if (coverageExemptRaw !== undefined && coverageExemptRaw !== '' && coverageExemptRaw !== '1') {
+  throw new Error(`vitest config: ${COVERAGE_EXEMPT_ENV} must be '1' or unset, got ${JSON.stringify(coverageExemptRaw)}.`)
+}
+const coverageExemptExcludes = coverageExemptRaw === '1'
+  ? coverageExemptHeavySuites.map(suite => suite.exclude)
+  : []
+
 // These suites exercise process-global state, process APIs, or timing-sensitive process I/O
 // that worker threads cannot isolate reliably under aggregate gate contention.
 // Keep the narrow exception in forks while the rest of the inventory avoids per-file processes.
@@ -55,22 +94,27 @@ export default defineConfig({
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
     include: testIncludes,
     exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
-    // One coverage invocation aggregates both projects. Most suites use threads
-    // for lower startup/IPC overhead; only explicit process-bound suites fork.
+    // One coverage invocation aggregates both projects. Regular suites fork on
+    // POSIX for Node stability and use threads on Windows; process-bound suites
+    // always fork.
     projects: [
       {
         plugins: [pathsPlugin()],
         test: {
           name: 'thread-safe',
-          // Node 24 has aborted in its CJS lexer from a macOS arm64 worker
-          // thread. A fork contains that external runtime failure to the test
-          // process; other hosts retain the lower-overhead thread pool.
-          pool: process.platform === 'darwin' ? 'forks' : 'threads',
+          execArgv: vitestExecArgv,
+          // Node 24 has aborted in its CJS lexer (v8::ToLocalChecked Empty
+          // MaybeLocal in cjs_lexer::Parse) from worker threads on macOS
+          // arm64 and later on Linux. A fork contains that external runtime
+          // failure to the test process; Windows keeps the thread pool, where
+          // the abort has not reproduced and process spawn is costlier.
+          pool: process.platform === 'win32' ? 'threads' : 'forks',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: testIncludes,
           exclude: [
             ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
             ...processBoundTests,
+            ...coverageExemptExcludes,
           ],
         },
       },
@@ -78,10 +122,14 @@ export default defineConfig({
         plugins: [pathsPlugin()],
         test: {
           name: 'process-bound',
+          execArgv: vitestExecArgv,
           pool: 'forks',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: processBoundTests,
-          exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
+          exclude: [
+            ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
+            ...coverageExemptExcludes,
+          ],
         },
       },
     ],
@@ -98,7 +146,8 @@ export default defineConfig({
         'packages/*/*/src/types.ts',
         'packages/*/*/src/bin.ts',
         'packages/*/*/src/worker.ts',
-        'packages/code-runtime/code-runtime-subprocess/src/runner.ts',
+        // A killed executable lint-contract test can leave a non-product source probe behind.
+        'packages/*/*/src/oxlint-contract-*.ts',
         // GUI step-1 skeleton (PR #500): client/web UI files whose remaining
         // branches need a browser-grade harness the jsdom lane doesn't cover
         // yet. TODO(gui): cover and remove as the client test lane matures.
@@ -107,6 +156,7 @@ export default defineConfig({
         'packages/client/ui-primitives/src/markdown/plain-text.ts',
         'packages/client/ui-question/src/client/QuestionComposer.tsx',
         'packages/client/ui-primitives/src/Menu.tsx',
+        'packages/client/ui-primitives/src/RiskConfirmation.tsx',
         'packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx',
         'packages/client/ui-workspace/src/client/WorkspacePicker.tsx',
         'packages/client/web-react/src/*',
@@ -155,9 +205,13 @@ export default defineConfig({
         'packages/client/ui-sidebar/src/client/index.ts',
         'packages/client/ui-skill/src/client/index.ts',
         'packages/client/ui-workspace/src/client/index.ts',
-        'packages/typert/generator/src/analyzer.ts',
-        'packages/typert/generator/src/renderer.ts',
-        'packages/typert/generator/src/cordis-catalog.ts',
+        'packages/client/test-runtime/src/translate.ts',
+        'packages/client/ui-primitives/src/JsonTree.tsx',
+        // Typert generator: correctness is pinned by its fixture suites and
+        // the byte-for-byte catalog reproduction test; per-file coverage
+        // would put whole-workspace compiler analysis under v8
+        // instrumentation — the coverage lane's longest tail.
+        'packages/typert/generator/src/*.ts',
         'packages/host/apiproxy/src/index.ts',
         'packages/host/apiproxy/src/invariant.ts',
         'packages/host/apiproxy/src/api-proxy.ts',
@@ -167,9 +221,9 @@ export default defineConfig({
         'packages/ui/commands/src/index.ts',
         'packages/ui/commands/src/invariant.ts',
         'packages/session-projection/session-projection/src/index.ts',
-        'packages/ui/tui/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
+        ...pwshCoverageExclusions,
       ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.
@@ -182,7 +236,9 @@ export default defineConfig({
         functions: 100,
         lines: 100,
       },
-      reporter: process.env.CI ? ['text'] : ['text', 'html'],
+      reporter: process.env.CI
+        ? ['text', uncoveredLocationsReporter]
+        : ['text', 'html', uncoveredLocationsReporter],
     },
   },
 })

From d0701296223994d82323b7c249aa20ce9a325b35 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:09:51 +0800
Subject: [PATCH 094/262] fix(constraints): follow the spawn-helper relocation
 to subprocess-local

The workspace-constraints allowlist pinned scripts/ensure-spawn-helper.mjs
to dsh-pty-local; this branch relocates the helper (with node-pty
ownership) into dsh-subprocess-local, so the published-files expectation
moves with it.
---
 scripts/check-workspace-constraints.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 355b817e68..1c7bedc696 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -125,8 +125,8 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
   '@deepseek-ai/dsh-headless': ['cordis.patch.yml'],
   '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
   '@deepseek-ai/dsh-helper': ['lib/assets'],
-  '@deepseek-ai/dsh-pty-local': ['scripts/ensure-spawn-helper.mjs'],
   '@deepseek-ai/dsh-skill-badge': ['assets'],
+  '@deepseek-ai/dsh-subprocess-local': ['scripts/ensure-spawn-helper.mjs'],
   '@deepseek-ai/dsh-scripts': [
     'lib/dev/tsdown-config.js',
     'lib/local-plugin-loader-hooks.js',

From fbceb8dcd55535e84f5b2ced570cbc613a00891a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:40:45 +0800
Subject: [PATCH 095/262] fix(pty-local): restore the session-resolved
 workspace policy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The linear replay resurrected the July spawn path: mode folded inline
and both confinement and the default cwd fenced to the deployment
workspaceRoot. Master (and the pre-rebase merge result) resolve the
policy once per spawn — resolve({ session }) — so session.header.cwd
is both the workspace-write boundary and the default shell cwd, as the
README already states. Restores the single resolve, threads the policy
through spawnArgv and the cwd fallback, re-expresses master's
session-root test on the terminal spec, and pins the recorded confine
policy in the explicit-cwd test.

Also from the same review round: the Python SDK exe build stages
pty.node from subprocess-local (node-pty's home since the relocation),
and fs-local's README counts the seam's eleven primitives.
---
 packages/fs/fs-local/README.i18n.yaml      |  4 +--
 packages/fs/fs-local/README.md             |  2 +-
 packages/fs/fs-local/README.zh.md          |  2 +-
 packages/pty/pty-local/src/index.ts        | 20 +++++------
 packages/pty/pty-local/tests/index.spec.ts | 40 ++++++++++++++++++++--
 scripts/build-exe-for-python-sdk.ts        |  2 +-
 6 files changed, 52 insertions(+), 18 deletions(-)

diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index e1870cbf41..250b94dacf 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-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/fs/fs-local/README.md
-README.md: fe0e5e9dec07fad745d6bea28da9009e517c7d85
-README.zh.md: 195f3963328035e9c6c382dd924cd04ee9e8c642
+README.md: 2e934298ceff75440357b0742770010c8b1c3904
+README.zh.md: 14f4867ce0f9eaae2a1dea98dbd7d401c98d4535
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index fe0e5e9dec..2e934298ce 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the twelve `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 195f396332..14f4867ce0 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十二个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index b1e0e6edbd..fa2237c959 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -10,7 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
 import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
 import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
 import { LocalPtySession } from './session.ts'
@@ -68,18 +68,15 @@ function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
   }
 }
 
-function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSpec): string[] {
+function spawnArgv(ctx: Context, config: ResolvedConfig, policy: SandboxExecutionPolicy): string[] {
   const argv = [config.shellPath, ...config.shellArgs]
-  const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
-  if (mode === 'danger-full-access') return argv
+  if (policy.mode === 'danger-full-access') return argv
   const sandbox = ctx.get('sandbox')
   if (sandbox === undefined) {
-    throw new Error(`pty-local: sandbox mode "${mode}" requires a ctx.sandbox provider in the execution world`)
+    throw new Error(`pty-local: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`)
   }
-  return sandbox.confine(argv, {
-    mode: mode,
-    workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
-  }).argv
+  // Re-state the discriminant because object spread does not preserve its narrowed type.
+  return sandbox.confine(argv, { ...policy, mode: policy.mode }).argv
 }
 
 // TODO(pty-initialize-race-home): Fold this outer abort race into
@@ -122,11 +119,12 @@ export class LocalPtyBackend implements PtyBackend {
   async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
     spec.signal?.throwIfAborted()
     ensureSandboxModeFence(this.ctx, spec.owner)
-    const argv = spawnArgv(this.ctx, this.config, spec)
+    const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session })
+    const argv = spawnArgv(this.ctx, this.config, policy)
     if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
     const terminal = await this.spawnTerminal({
       argv,
-      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+      cwd: spec.cwd ?? policy.workspaceRoot,
       env: childEnvironment(spec),
       rows: this.config.rows,
       cols: this.config.cols,
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 9f10a2cde8..d61eb58da5 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -44,9 +44,9 @@ function config(): ResolvedConfig {
   }
 }
 
-function agent(ctx: Context): Agent {
+function agent(ctx: Context, cwd?: string): Agent {
   const id = SessionId('agent')
-  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0 })
+  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0, ...cwd === undefined ? {} : { cwd } })
   return {
     id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
     status: 'idle',
@@ -213,6 +213,42 @@ describe('LocalPtyBackend startup rollback', () => {
     })
     expect(spawned?.env?.PTY_TEST_SECRET).toBeUndefined()
     expect(initialized).toHaveBeenCalledWith(undefined)
+    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
+      argv: ['/bin/bash', '-i'],
+      policy: { mode: 'workspace-write', workspaceRoot: '/workspace' },
+    }])
+  })
+
+  it('resolves session mode and root together before wrapping the shell', async () => {
+    const ctx = new Context()
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/deployment-fallback' })
+    const terminal = terminalHandle()
+    let spawned: SubprocessTerminalSpawnSpec | undefined
+    const spawnTerminal = async (spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> => {
+      spawned = spec
+      return terminal
+    }
+    const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = { initialize: initialized } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(
+      ctx,
+      { ...config(), shellArgs: ['-i'] },
+      spawnTerminal,
+      () => session,
+    )
+    const owner = agent(ctx, '/session-workspace')
+    setSandboxMode(owner.session, 'workspace-write')
+    expect(await backend.spawn(spec(owner))).toBe(session)
+
+    expect(spawned).toMatchObject({
+      argv: ['/sandbox', '--', '/bin/bash', '-i'],
+      cwd: '/session-workspace',
+    })
+    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
+      argv: ['/bin/bash', '-i'],
+      policy: { mode: 'workspace-write', workspaceRoot: '/session-workspace' },
+    }])
   })
 
   it('rejects a confined spawn without a sandbox provider', async () => {
diff --git a/scripts/build-exe-for-python-sdk.ts b/scripts/build-exe-for-python-sdk.ts
index db72f4c52e..536342dc89 100644
--- a/scripts/build-exe-for-python-sdk.ts
+++ b/scripts/build-exe-for-python-sdk.ts
@@ -326,7 +326,7 @@ class SingleExeBuild {
     if (this.cli.dryRun) console.log(`build-exe-for-python-sdk: [dry-run] rm -rf ${stagedBuild}`)
     else await rm(stagedBuild, { recursive: true, force: true })
     if (target.platform !== 'linux') return
-    const source = join(root, 'packages', 'pty', 'pty-local', 'node_modules', 'node-pty', 'build', 'Release', 'pty.node')
+    const source = join(root, 'packages', 'subprocess', 'subprocess-local', 'node_modules', 'node-pty', 'build', 'Release', 'pty.node')
     const destination = join(stagedBuild, 'Release', 'pty.node')
     if (this.cli.dryRun) {
       console.log(`build-exe-for-python-sdk: [dry-run] cp ${source} ${destination}`)

From d47df8ff9dc9d2eaabac8ae09449e325212c5bbf Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 00:10:29 +0800
Subject: [PATCH 096/262] chore(rebase): refresh generated docs after the
 round-two replay

Restores master's vitest config and packages-README pairing record (the
replay had carried old-lineage copies; this branch claims neither), and
regenerates the doc graphs, catalogs, and architecture pairing the
replay's ours-side resolutions had flattened to master's content.
---
 docs/architecture.i18n.yaml     |  4 ++--
 docs/capability-seams.md        | 11 +++++------
 docs/event-producer-consumer.md |  8 ++++----
 docs/module-graph.md            | 15 ++++++++-------
 packages/README.i18n.yaml       |  4 ++--
 vitest.config.ts                | 12 ++++++++----
 6 files changed, 29 insertions(+), 25 deletions(-)

diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index de15631197..e0ddc02423 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: ea78faa62773a6b8ac98e5baab6e181ad6a3b7f0
-architecture.zh.md: 5a46dfaf84276de5f4dc0352a529bdd4e5d8c267
+architecture.md: e88bdac118e382d91c41c471d03182952d8a4508
+architecture.zh.md: 9314a3fbfc87d467a0f902fa1dae9e8f07e2eb28
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index ae90e4a9bf..50ebe88d4f 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -21,7 +21,6 @@ flowchart LR
   pkg_session["session"]
   svc_sessions["ctx.sessions<br/>In-memory session store"]
   pkg_agent["agent"]
-  pkg_cli_demo["cli-demo"]
   pkg_session_persistence["session-persistence"]
   pkg_session_query["session-query"]
   pkg_session_query_sqlite["session-query-sqlite"]
@@ -91,6 +90,7 @@ flowchart LR
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
+  pkg_skill_badge["skill-badge"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
@@ -225,6 +225,7 @@ flowchart LR
   pkg_settings --> svc_settings
   pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
+  pkg_skill_badge --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
   pkg_spill_local --> svc_spillStore
@@ -260,7 +261,6 @@ flowchart LR
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
-  svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
@@ -307,7 +307,6 @@ flowchart LR
   svc_sessionQuery --> pkg_tool_session_query
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
-  svc_sessions --> pkg_cli_demo
   svc_sessions --> pkg_invariants
   svc_sessions --> pkg_session_persistence
   svc_sessions --> pkg_session_query
@@ -366,7 +365,7 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
@@ -387,8 +386,8 @@ flowchart LR
 | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index acd2bc5e91..9699870ecc 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -24,9 +24,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
@@ -65,7 +65,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
-| `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
+| `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
 | `internal/service` | - | `gateway` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale` |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 22af77f9c5..38a85a508a 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -491,12 +491,6 @@ flowchart TD
   pkg_code_runtime_worker --> pkg_invariants
   pkg_code_runtime_worker --> pkg_session
   pkg_code_runtime_worker --> pkg_timeout
-  pkg_lsp_local --> pkg_brand
-  pkg_lsp_local --> pkg_invariants
-  pkg_lsp_local --> pkg_llm
-  pkg_lsp_local --> pkg_lsp
-  pkg_lsp_local --> pkg_subprocess
-  pkg_lsp_local --> pkg_timeout
   pkg_sandbox_local --> pkg_invariants
   pkg_sandbox_local --> pkg_llm
   pkg_sandbox_local --> pkg_sandbox
@@ -607,6 +601,13 @@ flowchart TD
   pkg_host_directory_picker_native --> pkg_client_ui_slots
   pkg_host_directory_picker_native --> pkg_client_ui_workspace
   pkg_host_directory_picker_native --> pkg_invariants
+  pkg_lsp_local --> pkg_brand
+  pkg_lsp_local --> pkg_fs
+  pkg_lsp_local --> pkg_invariants
+  pkg_lsp_local --> pkg_llm
+  pkg_lsp_local --> pkg_lsp
+  pkg_lsp_local --> pkg_subprocess
+  pkg_lsp_local --> pkg_timeout
   pkg_pty --> pkg_agent
   pkg_pty --> pkg_brand
   pkg_pty --> pkg_invariants
@@ -1238,7 +1239,6 @@ flowchart TD
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
@@ -1266,6 +1266,7 @@ flowchart TD
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index d10f476f79..8aa9b92b91 100644
--- 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: 8fbb6069a784a5bd45423a4e1ae11834a597750d
-README.zh.md: 42a8d691344c716021188df6fd870a841d543f36
+README.md: 229feae568ba6e40a9c633696097eff46fd5bc95
+README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
diff --git a/vitest.config.ts b/vitest.config.ts
index 5e6ac400ef..6eb1bda354 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
-import { vitestExecArgv } from './vitest.shared.ts'
+import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
 import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
 
 // Prints exact `path:line:col` records for every uncovered statement, branch
@@ -88,7 +88,7 @@ const processBoundTests = [
 ]
 
 export default defineConfig({
-  plugins: [pathsPlugin()],
+  plugins: [pathsPlugin(), standardDecoratorPlugin()],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
@@ -99,7 +99,7 @@ export default defineConfig({
     // always fork.
     projects: [
       {
-        plugins: [pathsPlugin()],
+        plugins: [pathsPlugin(), standardDecoratorPlugin()],
         test: {
           name: 'thread-safe',
           execArgv: vitestExecArgv,
@@ -119,7 +119,7 @@ export default defineConfig({
         },
       },
       {
-        plugins: [pathsPlugin()],
+        plugins: [pathsPlugin(), standardDecoratorPlugin()],
         test: {
           name: 'process-bound',
           execArgv: vitestExecArgv,
@@ -181,6 +181,10 @@ export default defineConfig({
         'packages/client/hmr/src/invariant.ts',
         'packages/client/connection/src/index.ts',
         'packages/client/connection/src/http-bridge.ts',
+        // This assembly imports generated Host-for-Client code that exists
+        // only in lib; the post-build built-bin smoke executes both entries.
+        'packages/api/remotes/src/index.ts',
+        'packages/api/remotes/src/client/index.ts',
         // Slash/command/input round: per-file gaps deferred with the same
         // client-lane debt. TODO(gui): cover and remove with the lane above.
         'packages/client/connection/src/client/fixture.ts',

From 9a4b70cf3be777a913cd79fc4aeeeadc8e71d3b8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:49:23 +0800
Subject: [PATCH 097/262] fix(i18n): harden stopped-merge recovery

---
 ...matic-translation-pairing-merges.i18n.yaml |   4 +-
 ...08-automatic-translation-pairing-merges.md |   6 +-
 ...automatic-translation-pairing-merges.zh.md |   6 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 docs/i18n/README.i18n.yaml                    |   4 +-
 docs/i18n/README.md                           |   2 +-
 docs/i18n/README.zh.md                        |   2 +-
 scripts/merge-translation-pairing.ts          |   5 +
 .../request-response.expected.json            |   8 +-
 scripts/translation-pairing-git.ts            |  17 ++-
 scripts/translation-pairing-merge.spec.ts     | 103 ++++++++++++++
 scripts/translation-pairing-merge.ts          | 131 +++++++++++++-----
 14 files changed, 237 insertions(+), 59 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
index bbd7870d69..7631476fb8 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.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 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
-2026-08-08-automatic-translation-pairing-merges.md: a1b92c97240e2019b188b606dc079b2211a89238
-2026-08-08-automatic-translation-pairing-merges.zh.md: 5c7249dc436d24aa955d9c042c8d1bdc84655868
+2026-08-08-automatic-translation-pairing-merges.md: e70864f1227fe11d7895dd85b0a99d166753a685
+2026-08-08-automatic-translation-pairing-merges.zh.md: 08da67d78e5cca23e3c5c698644c667813697812
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
index a1b92c9724..e70864f122 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
@@ -14,15 +14,15 @@ A bilingual consistency record contains the two owner files' exact blob hashes.
 
 The driver parses the ancestor, current, and other records and loads the six owner blobs named by their hashes. It independently runs Git's default three-way text merge for the English and Chinese triplets, requires both merges to be clean, verifies language switchers and the pairing structural signature, stores the two merged blobs, and writes their hashes as the canonical record. This composes confirmations already present in both parents; it never records an ordinary one-sided documentation edit.
 
-The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy, either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
+The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy (including a non-text `merge.default` inherited by an otherwise unspecified path), either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
 
-`pnpm run resolve-translation-pairing-conflicts` applies the same algorithm after a merge has already stopped. Before writing any sidecar, it proves that the staged owner blob IDs and working-tree bytes equal its independent merges; then it writes and stages every safe record as one batch while leaving unrelated conflicts untouched.
+`pnpm run resolve-translation-pairing-conflicts` applies the same algorithm after a merge has already stopped. Before writing any sidecar, it proves that the sidecar still contains Git's untouched conflict result and that the staged owner blob IDs and working-tree bytes equal its independent merges. It writes and stages every safe record as one batch even when another pair still needs manual work, then reports the remaining pairing conflicts and exits unsuccessfully so callers cannot mistake a partial resolution for a completed merge.
 
 `pre-merge-commit` and `pre-commit` verify staged `.i18n.yaml` files against the exact index bytes of their owners. They validate driver output but do not regenerate records, so bypassing a hook cannot silently bless translation drift; the corpus-wide `doc-sync` check remains authoritative in CI.
 
 ## Verification
 
-Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, owner-content conflicts, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
+Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, mixed safe and owner-conflicted pairs, edited sidecars, non-text default merge configuration, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
index 5c7249dc43..08da67d78e 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -14,15 +14,15 @@ Status: implemented
 
 驱动会解析祖先、当前和另一侧的记录，并加载其中 hash 指向的六个 Markdown blob。它分别对英文文档的三个 blob 与中文文档的三个 blob 运行 Git 默认的三方文本合并，要求两次合并都干净完成，校验语言切换行与配对结构签名，存储两个合并后的 blob，再将其 hash 写入规范记录。这一过程组合两个父提交中已经存在的确认；它绝不会为普通的单侧文档编辑写入记录。
 
-记录格式错误、对象缺失、配对文档采用其他合并策略、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
+记录格式错误、对象缺失、配对文档采用其他合并策略（包括原本未单独指定策略的路径继承了非文本 `merge.default`）、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
 
-`pnpm run resolve-translation-pairing-conflicts` 会在合并已经停止后应用同一算法。写入任何伴随文件之前，它会先验证暂存区中配对文档的 blob ID 以及工作树中的文件字节，都与工具独立完成的合并结果一致；随后它会将所有可安全生成的记录作为一个批次写入并暂存，同时不改动无关冲突。
+`pnpm run resolve-translation-pairing-conflicts` 会在合并已经停止后应用同一算法。写入任何伴随文件之前，它会验证伴随文件仍保留 Git 生成且未经改动的冲突结果，并验证暂存区中配对文档的 blob ID 以及工作树中的文件字节都与工具独立完成的合并结果一致。即使其他配对仍需手工处理，它也会将所有可安全生成的记录作为一个批次写入并暂存；随后报告剩余的配对冲突并以非零状态退出，确保调用方不会把仅部分解决误认为合并已经完成。
 
 `pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
 
 ## 验证
 
-脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、配对文档内容冲突、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
+脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、可安全解决的配对与配对文档冲突的配对并存、被编辑过的伴随文件、非文本默认合并配置、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
 
 ## 考虑过的替代方案
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 3c57bb057c..6397e9d97e 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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 docs/development.md
-development.md: 1b0a412cd55224740a074a88734bc5663a14effc
-development.zh.md: 3c01f680dd8107fe6b3369415a979cea69cd19a0
+development.md: ad0447a0e121eaa31fb6e98502c6a55a9456d768
+development.zh.md: aef8b25d2115d00d5cfdb76b342a57662030feee
diff --git a/docs/development.md b/docs/development.md
index 1b0a412cd5..ad0447a0e1 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git integrations
 
-The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
+The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 3c01f680dd..aef8b25d21 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git 集成
 
-当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
+当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 48d27cbb41..c62de565e7 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: 2f9d7d1112492545e4e82d8d99c3d11df383e42d
-README.zh.md: 65ac3552aa4b66cbd43e6b55b98f0e1d9491feea
+README.md: 30f56eeebf15a3edec559e3080247dab9ab14178
+README.zh.md: 91d5b35a00994beea70f2bbd674cfb557d6f834d
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 2f9d7d1112..30f56eeebf 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -17,7 +17,7 @@ This repo's documentation is read by people and agents both inside and outside t
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).
 
-  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
+  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
 - **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
 - **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 65ac3552aa..91d5b35a00 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -17,7 +17,7 @@
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。
 
-  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
+  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
 - **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
 - **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
diff --git a/scripts/merge-translation-pairing.ts b/scripts/merge-translation-pairing.ts
index 8d193ab9f9..30313d045a 100644
--- a/scripts/merge-translation-pairing.ts
+++ b/scripts/merge-translation-pairing.ts
@@ -38,5 +38,10 @@ try {
   }
 } catch (error) {
   console.error(`merge-translation-pairing: ${error instanceof Error ? error.message : String(error)}`)
+  console.error(
+    'merge-translation-pairing: resolve owner conflicts, then confirm the pair with '
+    + '`pnpm run verify-translation-pairing --write <pair>`; rerun '
+    + '`pnpm run resolve-translation-pairing-conflicts` for other safe records',
+  )
   process.exitCode = 1
 }
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index b45ffe01e0..311b0ecc80 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,19 +16,19 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing-git.ts b/scripts/translation-pairing-git.ts
index b18b2d5778..cda27426c6 100644
--- a/scripts/translation-pairing-git.ts
+++ b/scripts/translation-pairing-git.ts
@@ -5,6 +5,9 @@ import { createHash } from 'node:crypto'
 
 const SNAPSHOT_REF_PREFIX = 'refs/dsh/translation-pairing/snapshots'
 
+/** Maximum buffered stdout or stderr for repository-owned Git subprocesses. */
+export const GIT_COMMAND_MAX_BUFFER = 1 << 26
+
 /** Full SHA-1 Git blob hash (the 40-hex format used by pairing records). */
 export function gitBlobHash(content: Buffer): string {
   const hash = createHash('sha1')
@@ -13,10 +16,20 @@ export function gitBlobHash(content: Buffer): string {
   return hash.digest('hex')
 }
 
-function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
+/**
+ * Run one Git subprocess and return its exact stdout bytes.
+ *
+ * @param root - Repository root used as Git's working directory.
+ * @param args - Arguments following the `git` executable.
+ * @param operation - Human-readable operation for failure diagnostics.
+ * @param input - Optional stdin bytes.
+ * @returns Exact stdout bytes.
+ * @throws Error when Git cannot start or exits unsuccessfully.
+ */
+export function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
   const result = spawnSync('git', ['-C', root, ...args], {
     input,
-    maxBuffer: 1 << 26,
+    maxBuffer: GIT_COMMAND_MAX_BUFFER,
   })
   if (result.error) {
     throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index bd6d2a632b..6ddce4b30b 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -85,6 +85,12 @@ const otherSource = baseSource.replace('Beta base.', 'Beta other.')
 const otherZh = baseZh.replace('乙基础。', '乙对侧。')
 const mergedSource = currentSource.replace('Beta base.', 'Beta other.')
 const mergedZh = currentZh.replace('乙基础。', '乙对侧。')
+const manualBaseSource = baseSource.replace('guide.zh.md', 'manual.zh.md')
+const manualBaseZh = baseZh.replace('guide.md', 'manual.md')
+const manualCurrentSource = manualBaseSource.replace('Alpha base.', 'Alpha current.')
+const manualCurrentZh = manualBaseZh.replace('甲基础。', '甲当前。')
+const manualOtherSource = manualBaseSource.replace('Alpha base.', 'Alpha other.')
+const manualOtherZh = manualBaseZh.replace('甲基础。', '甲对侧。')
 
 function commitPair(fixture: Fixture, source: string, zh: string, message: string): string {
   const sidecar = record(fixture.root, 'docs/guide.md', source, zh)
@@ -113,6 +119,47 @@ function startStoppedPairingMerge(fixture: Fixture): void {
   expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
 }
 
+function commitMixedPairs(
+  fixture: Fixture,
+  guide: { source: string; zh: string },
+  manual: { source: string; zh: string },
+  message: string,
+): void {
+  record(fixture.root, 'docs/guide.md', guide.source, guide.zh)
+  record(fixture.root, 'docs/manual.md', manual.source, manual.zh)
+  git(fixture, ['add', '.'])
+  git(fixture, ['commit', '-m', message])
+}
+
+function startMixedPairingMerge(fixture: Fixture): void {
+  commitMixedPairs(
+    fixture,
+    { source: baseSource, zh: baseZh },
+    { source: manualBaseSource, zh: manualBaseZh },
+    'base',
+  )
+  git(fixture, ['switch', '-c', 'current'])
+  commitMixedPairs(
+    fixture,
+    { source: currentSource, zh: currentZh },
+    { source: manualCurrentSource, zh: manualCurrentZh },
+    'current',
+  )
+  git(fixture, ['switch', 'master'])
+  commitMixedPairs(
+    fixture,
+    { source: otherSource, zh: otherZh },
+    { source: manualOtherSource, zh: manualOtherZh },
+    'other',
+  )
+  git(fixture, ['switch', 'current'])
+  const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+    encoding: 'utf8',
+    env: fixture.env,
+  })
+  expect(merge.status).toBe(1)
+}
+
 function expectMergedPair(fixture: Fixture): void {
   expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(mergedSource)
   expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(mergedZh)
@@ -139,6 +186,7 @@ describe('translation pairing merge composition', () => {
 
   it('merges the owner blobs named by three valid records', () => {
     const fixture = createFixture(false)
+    git(fixture, ['config', 'merge.default', 'text'])
     const records = createDivergedPair(fixture)
 
     const result = mergeTranslationPairingRecords(
@@ -214,6 +262,20 @@ describe('translation pairing merge composition', () => {
     )).toThrow('docs/guide.md uses merge=custom-owner')
   })
 
+  it('refuses unspecified owners affected by merge.default', () => {
+    const fixture = createFixture(false)
+    git(fixture, ['config', 'merge.default', 'custom-owner'])
+    const records = createDivergedPair(fixture)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      records.ancestor,
+      records.current,
+      records.other,
+    )).toThrow('merge.default=custom-owner')
+  })
+
   it('runs as Git\'s custom driver and commits a clean composed record', () => {
     const fixture = createFixture()
     createDivergedPair(fixture)
@@ -231,6 +293,19 @@ describe('translation pairing merge composition', () => {
     expectMergedPair(fixture)
   })
 
+  it('prints the recovery path when driver input is not composable', () => {
+    const fixture = createFixture(false)
+    const result = spawnSync(process.execPath, ['--import', tsxLoader, driver], {
+      cwd: fixture.root,
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('pnpm run verify-translation-pairing --write <pair>')
+    expect(result.stderr).toContain('pnpm run resolve-translation-pairing-conflicts')
+  })
+
   it('resolves an already-stopped generated-only conflict from index stages', () => {
     const fixture = createFixture(false)
     startStoppedPairingMerge(fixture)
@@ -251,4 +326,32 @@ describe('translation pairing merge composition', () => {
     )
     expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
   })
+
+  it('refuses to overwrite an edited sidecar after a stopped merge', () => {
+    const fixture = createFixture(false)
+    startStoppedPairingMerge(fixture)
+    write(fixture.root, 'docs/guide.i18n.yaml', 'manually resolved\n')
+
+    expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(
+      'docs/guide.i18n.yaml has edited conflict content',
+    )
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe('manually resolved\n')
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+  })
+
+  it('resolves safe records while leaving an owner-conflicted pair untouched', () => {
+    const fixture = createFixture(false)
+    startMixedPairingMerge(fixture)
+
+    expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(
+      'docs/manual.i18n.yaml: docs/manual.md has content conflicts',
+    )
+
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U']).split('\n')).toEqual([
+      'docs/manual.i18n.yaml',
+      'docs/manual.md',
+      'docs/manual.zh.md',
+    ])
+    expectMergedPair(fixture)
+  })
 })
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
index 3297e30ea2..58b1be3fee 100644
--- a/scripts/translation-pairing-merge.ts
+++ b/scripts/translation-pairing-merge.ts
@@ -4,7 +4,13 @@ import { spawnSync } from 'node:child_process'
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
-import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  GIT_COMMAND_MAX_BUFFER,
+  gitBlobHash,
+  readGitIndexBlob,
+  runGit,
+  storeGitBlob,
+} from './translation-pairing-git.ts'
 import {
   linksTo,
   isTranslationScopeFile,
@@ -20,7 +26,6 @@ import {
   type TranslationPairingRecord,
 } from './translation-pairing-record.ts'
 
-const MAX_GIT_OUTPUT = 1 << 26
 const UNMERGED_ENTRY = /^(\d+) ([0-9a-f]+) ([123])\t([\s\S]+)$/
 
 /** A mechanically composed record and the exact merged owner contents it names. */
@@ -39,18 +44,6 @@ interface UnmergedStages {
   other?: string
 }
 
-function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
-  const result = spawnSync('git', ['-C', root, ...args], {
-    input,
-    maxBuffer: MAX_GIT_OUTPUT,
-  })
-  if (result.error) throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
-  if (result.status !== 0) {
-    throw new Error(`${operation} failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`)
-  }
-  return result.stdout
-}
-
 function readGitBlob(root: string, objectId: string, owner: string): Buffer {
   const content = runGit(root, ['cat-file', 'blob', objectId], `reading ${owner} blob ${objectId}`)
   if (gitBlobHash(content) !== objectId) {
@@ -59,6 +52,22 @@ function readGitBlob(root: string, objectId: string, owner: string): Buffer {
   return content
 }
 
+function readMergeDefault(root: string): string | undefined {
+  const result = spawnSync('git', ['-C', root, 'config', '--get', 'merge.default'], {
+    maxBuffer: GIT_COMMAND_MAX_BUFFER,
+  })
+  if (result.error) {
+    throw new Error(`reading merge.default failed: ${result.error.message}`, { cause: result.error })
+  }
+  if (result.status === 1) return undefined
+  if (result.status !== 0) {
+    throw new Error(
+      `reading merge.default failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`,
+    )
+  }
+  return result.stdout.toString('utf8').trim()
+}
+
 function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void {
   const output = runGit(
     root,
@@ -67,6 +76,7 @@ function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void
   ).toString('utf8')
   const fields = output.split('\0')
   fields.pop()
+  let mergeDefault: string | undefined
   for (let index = 0; index < fields.length; index += 3) {
     const path = fields[index]
     const value = fields[index + 2]
@@ -76,6 +86,14 @@ function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void
     if (!['unspecified', 'set', 'text'].includes(value)) {
       throw new Error(`${path} uses merge=${value}; the pairing driver only composes Git's default text merge`)
     }
+    if (value === 'unspecified') {
+      mergeDefault ??= readMergeDefault(root)
+      if (mergeDefault !== undefined && mergeDefault !== 'text') {
+        throw new Error(
+          `${path} inherits merge.default=${mergeDefault}; the pairing driver only composes Git's default text merge`,
+        )
+      }
+    }
   }
 }
 
@@ -101,7 +119,7 @@ function mergeBlobTriplet(
       '-L', `${owner}:ancestor`,
       '-L', `${owner}:other`,
       currentPath, ancestorPath, otherPath,
-    ], { maxBuffer: MAX_GIT_OUTPUT })
+    ], { maxBuffer: GIT_COMMAND_MAX_BUFFER })
     if (result.error) {
       throw new Error(`merging ${owner} failed: ${result.error.message}`, { cause: result.error })
     }
@@ -222,46 +240,85 @@ function unmergedSidecars(root: string): Map<string, UnmergedStages> {
   return records
 }
 
+function assertUneditedSidecar(
+  root: string,
+  metaPath: string,
+  currentRecord: string,
+  otherRecord: string,
+): void {
+  const worktreeRecord = readFileSync(join(root, metaPath), 'utf8')
+  if (worktreeRecord === currentRecord || worktreeRecord === otherRecord) return
+  const stageDataLines = [currentRecord, otherRecord]
+    .flatMap(record => record.split(/\r?\n/))
+    .filter(line => line !== '' && !line.startsWith('#'))
+  const hasUneditedConflict = worktreeRecord.includes('<<<<<<<')
+    && worktreeRecord.includes('=======')
+    && worktreeRecord.includes('>>>>>>>')
+    && stageDataLines.every(line => worktreeRecord.includes(line))
+  if (!hasUneditedConflict) {
+    throw new Error(`${metaPath} has edited conflict content; refusing to overwrite manual work`)
+  }
+}
+
 /**
  * Resolve every mechanically composable `.i18n.yaml` conflict in the index.
  *
  * The command first proves that Git's already-staged owner merges match the
  * independently composed contents, then writes and stages all sidecars as one
- * batch. Other conflicts remain untouched.
+ * batch. Other conflicts remain untouched; after staging the safe records, an
+ * aggregate error reports any pairing conflicts that still need manual work.
  *
  * @param root - Repository root with an in-progress merge-like operation.
  * @returns Repository-relative sidecar paths resolved and staged.
  */
 export function resolveTranslationPairingConflicts(root: string): string[] {
   const resolutions: { path: string; record: string }[] = []
+  const failures: { path: string; reason: string }[] = []
   for (const [metaPath, stages] of [...unmergedSidecars(root)].sort(([left], [right]) => left.localeCompare(right))) {
-    if (stages.ancestor === undefined || stages.current === undefined || stages.other === undefined) {
-      throw new Error(`${metaPath} is an add/delete or incomplete-stage conflict and requires manual resolution`)
-    }
-    const result = mergeTranslationPairingRecords(
-      root,
-      metaPath,
-      readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8'),
-      readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8'),
-      readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8'),
-    )
-    const paths = translationPairPathsFromMeta(metaPath)
-    if (readGitIndexBlob(root, paths.source)?.objectId !== result.sourceHash) {
-      throw new Error(`${paths.source} staged merge does not match the pairing driver's clean merge`)
-    }
-    if (readGitIndexBlob(root, paths.zh)?.objectId !== result.zhHash) {
-      throw new Error(`${paths.zh} staged merge does not match the pairing driver's clean merge`)
-    }
-    for (const [path, expected] of [[paths.source, result.sourceHash], [paths.zh, result.zhHash]] as const) {
-      if (gitBlobHash(readFileSync(join(root, path))) !== expected) {
-        throw new Error(`${path} has unstaged content; refusing to confirm bytes outside the merge result`)
+    try {
+      if (stages.ancestor === undefined || stages.current === undefined || stages.other === undefined) {
+        throw new Error('is an add/delete or incomplete-stage conflict and requires manual resolution')
       }
+      const ancestorRecord = readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8')
+      const currentRecord = readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8')
+      const otherRecord = readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8')
+      assertUneditedSidecar(root, metaPath, currentRecord, otherRecord)
+      const result = mergeTranslationPairingRecords(
+        root,
+        metaPath,
+        ancestorRecord,
+        currentRecord,
+        otherRecord,
+      )
+      const paths = translationPairPathsFromMeta(metaPath)
+      if (readGitIndexBlob(root, paths.source)?.objectId !== result.sourceHash) {
+        throw new Error(`${paths.source} staged merge does not match the pairing driver's clean merge`)
+      }
+      if (readGitIndexBlob(root, paths.zh)?.objectId !== result.zhHash) {
+        throw new Error(`${paths.zh} staged merge does not match the pairing driver's clean merge`)
+      }
+      for (const [path, expected] of [[paths.source, result.sourceHash], [paths.zh, result.zhHash]] as const) {
+        if (gitBlobHash(readFileSync(join(root, path))) !== expected) {
+          throw new Error(`${path} has unstaged content; refusing to confirm bytes outside the merge result`)
+        }
+      }
+      resolutions.push({ path: metaPath, record: result.record })
+    } catch (error) {
+      failures.push({ path: metaPath, reason: error instanceof Error ? error.message : String(error) })
     }
-    resolutions.push({ path: metaPath, record: result.record })
   }
   for (const resolution of resolutions) writeFileSync(join(root, resolution.path), resolution.record)
   if (resolutions.length > 0) {
     runGit(root, ['add', '--', ...resolutions.map(resolution => resolution.path)], 'staging resolved pairing records')
   }
+  if (failures.length > 0) {
+    const resolved = resolutions.length === 0
+      ? ''
+      : `resolved and staged ${resolutions.map(resolution => resolution.path).join(', ')}; `
+    throw new Error(
+      `${resolved}left ${String(failures.length)} pairing conflict(s) unresolved:\n`
+      + failures.map(failure => `- ${failure.path}: ${failure.reason}`).join('\n'),
+    )
+  }
   return resolutions.map(resolution => resolution.path)
 }

From b9b25f81cb5659b7b73ab6ec049a53a36e26407a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 22:17:54 +0800
Subject: [PATCH 098/262] fix(subprocess-local): fence descendant adoption on
 the shell's start identity

A recycled shell pid could donate an unrelated process's children to the
terminal session's cleanup signalling: post-exit rescans queried
processTree/processSession by numeric pid alone. The handle now captures
the spawned shell's start identity at construction and adopts newly
scanned members only while the root pid still carries it; already-adopted
members keep their own identities, which every signal already rechecks.
Regressions cover a recycled root donating an imposter child and a shell
whose identity was never observable; the terminal fakes now model the
root row the real /proc and ps scans include.

Also from the review round: tool-pty's dependency list is re-sorted, and
the LSP renderer documents the deliberate drive-letter reading of
ambiguous file: URIs (display-only blast radius).
---
 packages/lsp/tool-lsp/src/render.ts           |  3 ++
 packages/pty/tool-pty/package.json            |  2 +-
 .../subprocess-local/src/terminal.ts          | 16 ++++++-
 .../subprocess-local/tests/local.spec.ts      |  2 +-
 .../subprocess-local/tests/terminal.spec.ts   | 48 ++++++++++++++++---
 5 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 761f5a7d34..ad77b2a6e2 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -146,6 +146,9 @@ export function renderUri(uri: string, workspaceUri: string): string {
     return uri
   }
   if (workspace.protocol !== 'file:') return uri
+  // A `file:` URI does not carry its world's OS, so a leading `/X:` segment is
+  // read as a Windows drive. A POSIX workspace literally rooted at `/c:/...`
+  // would mis-render (display only; edits and reads use the exact URI).
   const drivePath = /^\/[a-z](?::|%3A)/iu
   const windowsWorld = workspace.hostname.length > 0 || drivePath.test(workspace.pathname)
   const targetWindowsWorld = windowsWorld && (target.hostname.length > 0 || drivePath.test(target.pathname))
diff --git a/packages/pty/tool-pty/package.json b/packages/pty/tool-pty/package.json
index 9027169941..f443bbbdf4 100644
--- a/packages/pty/tool-pty/package.json
+++ b/packages/pty/tool-pty/package.json
@@ -50,8 +50,8 @@
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tasks-local": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 2d3d0bb78e..2a763948bb 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -43,6 +43,8 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private cleanup: Promise<void> | undefined
   private exited = false
   private trackedDescendants: ProcessIdentity[] = []
+  /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
+  private readonly rootIdentity: ProcessIdentity | undefined
 
   /**
    * @param terminal - allocated node-pty process.
@@ -55,6 +57,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly graceMs: number,
   ) {
     this.pid = terminal.pid
+    this.rootIdentity = inspector.processTree(this.pid).find(member => member.pid === this.pid)
     this.done = this.outcome.promise
     this.dataDisposable = terminal.onData((data) => { this.output.write(Buffer.from(data, 'utf8')) })
     this.exitDisposable = terminal.onExit(({ exitCode, signal: exitSignal }) => {
@@ -112,10 +115,19 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private descendants(): ProcessIdentity[] {
+    // Adopt newly scanned members only while the numeric root pid provably
+    // still carries the spawned shell's start identity: after the shell dies,
+    // a recycled pid's tree and session must not donate an unrelated
+    // process's children to this session's signalling. Already-adopted
+    // members keep their own start identities, which every signal rechecks.
+    const tree = this.inspector.processTree(this.pid)
+    const root = tree.find(member => member.pid === this.pid)
+    const rootVerified = this.rootIdentity !== undefined
+      && root !== undefined
+      && root.started === this.rootIdentity.started
     this.trackedDescendants = this.survivors(this.unionMembers(
       this.trackedDescendants,
-      this.inspector.processTree(this.pid),
-      this.inspector.processSession(this.pid),
+      ...rootVerified ? [tree, this.inspector.processSession(this.pid)] : [],
     ).filter(member => member.pid !== this.pid))
     return this.trackedDescendants
   }
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 347b9c9330..c4e3f91522 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -249,7 +249,7 @@ describe('LocalSubprocessService', () => {
       ;(ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>).terminalInspector = {
         foregroundPgid: () => 123,
         isStdinWaiting: () => false,
-        processTree: () => [{ pid: 124, started: 'child' }],
+        processTree: () => [{ pid: 123, started: 'shell' }, { pid: 124, started: 'child' }],
         processSession: () => [],
         isAlive: identity => alive.has(identity.pid),
         signalGroup: () => {},
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 8a6270883f..79501c7dc4 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -52,6 +52,8 @@ class FakePty {
 class FakeInspector implements ProcessInspector {
   pgid: number | undefined = 456
   waiting = false
+  /** The shell's own row, present like the real /proc- and ps-backed scans; tests recycle or drop it. */
+  root: ProcessIdentity | undefined = { pid: 123, started: 'shell' }
   members: ProcessIdentity[] = []
   sessionMembers: ProcessIdentity[] = []
   readonly alive = new Set<number>()
@@ -63,7 +65,7 @@ class FakeInspector implements ProcessInspector {
 
   foregroundPgid() { return this.pgid }
   isStdinWaiting() { return this.waiting }
-  processTree() { return this.members }
+  processTree() { return this.root === undefined ? this.members : [this.root, ...this.members] }
   processSession() { return this.sessionMembers }
   isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
   signalGroup(pgid: number, signal: SubprocessTerminalSignal) {
@@ -189,19 +191,50 @@ describe('LocalTerminalHandle', () => {
     expect(inspector.processes).toEqual([[124, 'SIGTERM']])
   })
 
+  it('does not adopt the children of a recycled shell pid', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    pty.emitExit()
+    const imposterChild = { pid: 999, started: 'imposter-child' }
+    inspector.root = { pid: 123, started: 'imposter' }
+    inspector.members = [imposterChild]
+    inspector.alive.add(imposterChild.pid)
+
+    await handle.terminate()
+    expect(inspector.processes).toEqual([])
+  })
+
+  it('adopts nothing when the shell identity was never observable', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.root = undefined
+    const orphan = { pid: 321, started: 'unverifiable' }
+    inspector.members = [orphan]
+    inspector.alive.add(orphan.pid)
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    await handle.terminate()
+    expect(inspector.processes).toEqual([])
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
   it('rescans for descendants forked during TERM', async () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
+    const root = { pid: 123, started: 'shell' }
     let reads = 0
     inspector.processTree = () => {
       reads += 1
-      if (reads === 1) {
-        inspector.alive.add(124)
-        return [{ pid: 124, started: 'first' }]
-      }
+      if (reads === 1) return [root]
       if (reads === 2) {
+        inspector.alive.add(124)
+        return [root, { pid: 124, started: 'first' }]
+      }
+      if (reads === 3) {
         inspector.alive.add(125)
-        return [{ pid: 125, started: 'late' }]
+        return [root, { pid: 125, started: 'late' }]
       }
       return []
     }
@@ -256,9 +289,10 @@ describe('LocalTerminalHandle', () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
     const captured = { pid: 124, started: 'captured' }
+    const root = { pid: 123, started: 'shell' }
     let reads = 0
     inspector.alive.add(captured.pid)
-    inspector.processTree = () => reads++ === 0 ? [captured] : []
+    inspector.processTree = () => { reads += 1; return reads === 1 ? [root] : reads === 2 ? [root, captured] : [] }
     inspector.signalProcess = (identity, signal) => {
       inspector.processes.push([identity.pid, signal])
       if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)

From e7b682f1f65fa9de386edffd94bd4c46c232a786 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 10:05:30 +0800
Subject: [PATCH 099/262] feat(e2b): add remote runtime providers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   6 +
 .../2026-07-27-e2b-remote-runtime-poc.md      |  46 ++
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  46 ++
 docs/architecture.zh.md                       |   1 +
 docs/cordis-catalog/services.md               |  15 +
 examples/headless-agent/README.i18n.yaml      |   4 +-
 examples/headless-agent/README.md             |  26 +-
 examples/headless-agent/README.zh.md          |  26 +-
 examples/headless-agent/e2b.cordis.yml        |  30 +
 .../tests/fixtures/e2b/e2b/bin.ts             |  32 +
 .../tests/fixtures/e2b/e2b/cordis.yml         |  19 +
 examples/package.json                         |   3 +
 knip.json                                     |  11 +
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   1 +
 packages/README.zh.md                         |   1 +
 packages/e2b/README.i18n.yaml                 |   6 +
 packages/e2b/README.md                        |  13 +
 packages/e2b/README.zh.md                     |  13 +
 packages/e2b/e2b/README.i18n.yaml             |   6 +
 packages/e2b/e2b/README.md                    |  50 ++
 packages/e2b/e2b/README.zh.md                 |  50 ++
 packages/e2b/e2b/package.json                 |  44 ++
 packages/e2b/e2b/src/index.ts                 | 240 ++++++
 packages/e2b/e2b/src/invariant.ts             |  30 +
 packages/e2b/e2b/tests/composition.e2e.ts     |  39 +
 packages/e2b/e2b/tests/e2b.spec.ts            | 218 ++++++
 packages/e2b/e2b/tsconfig.json                |  25 +
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   3 +-
 packages/fs/README.zh.md                      |   3 +-
 packages/fs/fs-e2b/README.i18n.yaml           |   6 +
 packages/fs/fs-e2b/README.md                  |  29 +
 packages/fs/fs-e2b/README.zh.md               |  29 +
 packages/fs/fs-e2b/package.json               |  41 +
 packages/fs/fs-e2b/src/index.ts               | 423 ++++++++++
 packages/fs/fs-e2b/src/invariant.ts           |  27 +
 packages/fs/fs-e2b/tests/filesystem.spec.ts   | 537 +++++++++++++
 packages/fs/fs-e2b/tsconfig.json              |  25 +
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   7 +-
 packages/subprocess/README.zh.md              |  11 +-
 .../subprocess-e2b/README.i18n.yaml           |   6 +
 packages/subprocess/subprocess-e2b/README.md  |  32 +
 .../subprocess/subprocess-e2b/README.zh.md    |  32 +
 .../subprocess/subprocess-e2b/package.json    |  41 +
 .../subprocess/subprocess-e2b/src/index.ts    |  58 ++
 .../subprocess-e2b/src/invariant.ts           |  27 +
 .../subprocess/subprocess-e2b/src/output.ts   |  70 ++
 .../subprocess/subprocess-e2b/src/process.ts  | 417 ++++++++++
 .../subprocess-e2b/tests/subprocess.spec.ts   | 725 ++++++++++++++++++
 .../subprocess/subprocess-e2b/tsconfig.json   |  25 +
 scripts/gen-cordis-catalog.ts                 |   1 +
 .../verify-package-readme-model-experience.ts |   3 +
 tsconfig.base.json                            |   1 +
 tsconfig.host.json                            |   3 +
 56 files changed, 3565 insertions(+), 30 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
 create mode 100644 examples/headless-agent/e2b.cordis.yml
 create mode 100644 examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
 create mode 100644 examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
 create mode 100644 packages/e2b/README.i18n.yaml
 create mode 100644 packages/e2b/README.md
 create mode 100644 packages/e2b/README.zh.md
 create mode 100644 packages/e2b/e2b/README.i18n.yaml
 create mode 100644 packages/e2b/e2b/README.md
 create mode 100644 packages/e2b/e2b/README.zh.md
 create mode 100644 packages/e2b/e2b/package.json
 create mode 100644 packages/e2b/e2b/src/index.ts
 create mode 100644 packages/e2b/e2b/src/invariant.ts
 create mode 100644 packages/e2b/e2b/tests/composition.e2e.ts
 create mode 100644 packages/e2b/e2b/tests/e2b.spec.ts
 create mode 100644 packages/e2b/e2b/tsconfig.json
 create mode 100644 packages/fs/fs-e2b/README.i18n.yaml
 create mode 100644 packages/fs/fs-e2b/README.md
 create mode 100644 packages/fs/fs-e2b/README.zh.md
 create mode 100644 packages/fs/fs-e2b/package.json
 create mode 100644 packages/fs/fs-e2b/src/index.ts
 create mode 100644 packages/fs/fs-e2b/src/invariant.ts
 create mode 100644 packages/fs/fs-e2b/tests/filesystem.spec.ts
 create mode 100644 packages/fs/fs-e2b/tsconfig.json
 create mode 100644 packages/subprocess/subprocess-e2b/README.i18n.yaml
 create mode 100644 packages/subprocess/subprocess-e2b/README.md
 create mode 100644 packages/subprocess/subprocess-e2b/README.zh.md
 create mode 100644 packages/subprocess/subprocess-e2b/package.json
 create mode 100644 packages/subprocess/subprocess-e2b/src/index.ts
 create mode 100644 packages/subprocess/subprocess-e2b/src/invariant.ts
 create mode 100644 packages/subprocess/subprocess-e2b/src/output.ts
 create mode 100644 packages/subprocess/subprocess-e2b/src/process.ts
 create mode 100644 packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
 create mode 100644 packages/subprocess/subprocess-e2b/tsconfig.json

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
new file mode 100644
index 0000000000..13d081c28f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+2026-07-27-e2b-remote-runtime-poc.md: 307a08d6ca77c83bf836bc8d50b071fbf33ac49a
+2026-07-27-e2b-remote-runtime-poc.zh.md: bb4e657d999760f000949d509228bbb65f22773a
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
new file mode 100644
index 0000000000..307a08d6ca
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -0,0 +1,46 @@
+# Agent Note: Shared E2B remote runtime POC
+
+Status: implemented
+
+English | [中文](2026-07-27-e2b-remote-runtime-poc.zh.md)
+
+## Problem
+
+A remote coding-agent backend is useful only when file operations and commands observe one coherent world. Attaching E2B independently at individual tools would allow a Bash command and a filesystem edit to address different sandboxes, while moving the complete harness into a remote VM would couple provider experimentation to agent, session, model, persistence, and deployment changes.
+
+## Decision
+
+The E2B integration is a provider-composition POC with one shared lifecycle owner and two capability implementations:
+
+- `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
+- `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
+- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
+- The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
+
+The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes. The composition therefore gives filesystem tools and Bash one remote cwd, process namespace, and spill/state directory while preserving the existing capability interfaces and model-facing tools.
+
+## POC boundary
+
+Only filesystem state, command processes during the provider lifetime, and adapter-owned remote files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when the subprocess service disposes, including before a retained-sandbox pause or leave disposition.
+
+The POC has no PTY adapter, LSP-specific integration, session-persistence backend, code-runtime backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host process handles, output cursors, or locks.
+
+## Verification
+
+Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group/stdio/abort behavior, and the package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, proves FS-write→Bash-read and Bash-write→FS-read in the same remote cwd, proves neither file appears in the host cwd, disposes the composition, and confirms the sandbox id is gone.
+
+## Alternatives considered
+
+**A separate E2B sandbox per capability or tool** — rejected because file and command operations would not share identity or state, defeating the coding-agent use case and multiplying lifecycle ownership.
+
+**Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
+
+**Add E2B-specific Bash, PTY, LSP, persistence, and synchronization packages together** — rejected because Bash already has the required subprocess seam and the other capabilities need separate consumer evidence and lifecycle designs. Their absence is an explicit fidelity boundary, not an incomplete hidden plan.
+
+**Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
+
+## Consequences
+
+The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual state retention for experiments, while kill remains the demo's cleanup policy.
+
+The provider is not interchangeable with the local subprocess backend for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, callback output is not byte-faithful, signal attribution is inferred, and reconnect cannot restore handles. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
new file mode 100644
index 0000000000..bb4e657d99
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -0,0 +1,46 @@
+# Agent Note: 共享 E2B 远程运行时 POC
+
+Status: implemented
+
+[English](2026-07-27-e2b-remote-runtime-poc.md) | 中文
+
+## 问题
+
+远程 coding agent（智能体）后端只有在文件操作与命令观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，Bash 命令和文件系统编辑可能访问不同的沙箱；若把完整 harness 迁入远程 VM，则会把提供方实验与 agent、会话、模型、持久化及部署变更耦合在一起。
+
+## 决策
+
+E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和两个功能实现组成：
+
+- `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
+- `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
+- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
+- 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
+
+该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱。因此，该组合让文件系统工具与 Bash 共享一个远程 cwd、进程命名空间和 spill／状态目录，同时保留现有功能接口与面向模型的工具。
+
+## POC 边界
+
+只有文件系统状态、提供方存续期内的命令进程，以及适配器拥有的远程文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在进程管理服务 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
+
+本 POC 没有 PTY 适配器、LSP 专用集成、会话持久化后端、代码运行时后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主进程句柄、输出游标或锁。
+
+## 验证
+
+包测试固定生命周期清理、文件系统 seam 语义、进程管理的进程组／stdio／中止行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，证明同一远程 cwd 中 FS-write→Bash-read 和 Bash-write→FS-read 双向可见，证明两个文件均未出现在宿主 cwd 中，释放组合，并确认该沙箱 id 已不存在。
+
+## 曾考虑的替代方案
+
+**每项功能或每个工具使用独立的 E2B 沙箱。** 不予采纳，因为文件操作和命令操作将无法共享身份或状态，既违背 coding agent 用例，也会增加生命周期所有者的数量。
+
+**在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
+
+**同时添加 E2B 专用 Bash、PTY、LSP、持久化和同步包。** 不予采纳，因为 Bash 已经具备所需的进程管理 seam，其他功能则需要各自的消费方证据和生命周期设计。缺少它们是显式保真边界，而不是尚未公开的不完整计划。
+
+**仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
+
+## 后果
+
+这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留状态，演示仍以 `kill` 作为清理策略。
+
+该提供方并不能对所有消费方与本地进程管理后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，回调输出并非字节保真，信号归因依靠推断，重新连接也无法恢复句柄。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 9314a3fbfc..2d1a0b43d5 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -25,6 +25,7 @@
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
+| `ctx.e2b` | [`e2b/`](../packages/e2b/README.md) | 共享 E2B 沙箱 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
 | `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7e125cd02c..7ce45c6817 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -578,6 +578,21 @@ abstract capability(): DirectoryPickerCapability
 
 Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
 
+## `ctx.e2b` — `E2BSandboxService`
+
+Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decision. The connection begins at plugin construction; adapters await getSandbox before their first operation.
+
+```ts cordis-catalog
+/**
+ * Return the shared live SDK handle.
+ * @returns the created or reconnected sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation/reconnection or the service is disposing.
+ */
+async getSandbox(): Promise<Sandbox>
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
+
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index 7b6139f28b..56c02d3e0a 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/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 examples/headless-agent/README.md
-README.md: e00f3d2d4fd21a860239f3d3a3e5eb2d7520f14a
-README.zh.md: 6cd845783b1c112ba73676474b176ec28a4d0b78
+README.md: 16c45d304eb0f06a2b062518b053db683cd402c0
+README.zh.md: 72d2813d174e74a3bf93c363b268499a44f1cd4f
diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md
index e00f3d2d4f..16c45d304e 100644
--- a/examples/headless-agent/README.md
+++ b/examples/headless-agent/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This directory owns the replay and real-model test composition for a headless coding agent: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence. It explicitly mounts the shared agent spine, one root agent, persistence, and checkpoint policy; it is not a second product front door.
+Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence, with [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) as the app front door.
 
 ## Run it
 
@@ -10,13 +10,27 @@ This directory owns the replay and real-model test composition for a headless co
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run dsh run "fix the failing test in this workspace"
+pnpm run demo:headless "fix the failing test in this workspace"
+pnpm run demo:headless --output-format json -- "summarize the implementation"
+pnpm run demo:headless --output-format stream-json -- "run the focused tests"
 ```
 
-The product command is [`dsh run`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
+Exactly one nonblank positional task is required; quote tasks containing spaces. There is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the top-level session's canonical task-turn events before that record. Child sessions surface only through parent tool events and results.
 
-Snapshot suites run this directory's configuration through [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts), an unexported test-only process that emits canonical session events as JSONL before its result record. That stream is test infrastructure, not a supported CLI output format. Child sessions surface only through parent tool events and results.
+Each invocation creates and persists a fresh session, runs all model and tool steps in one turn, flushes, disposes, and exits. This is non-interactive automation: there is no prompt, approval, resume, second turn, or stdin context. The configured tools can mutate the launch workspace, run commands, spawn child agents, and consume provider tokens.
 
-## Advanced configuration
+## E2B POC overlay
 
-[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the test composition.
+[`e2b.cordis.yml`](e2b.cordis.yml) replaces the local filesystem and subprocess providers with one shared E2B sandbox while retaining `dsh-bash-local` and the same model-facing tools. Put `E2B_API_KEY` beside `DEEPSEEK_API_KEY` in the gitignored root `.env`, then run:
+
+```sh
+pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+```
+
+The overlay creates the same absolute cwd inside the sandbox, but it does not upload or mount the host workspace. File and Bash mutations exist only in E2B; Cordis, model calls, agent/session state, session logs, skills, and SDK buffers remain on the host. The demo kills its sandbox on timeout and disposal. It is a provider-composition POC, not a whole-harness migration or a workspace-sync feature.
+
+## Advanced and snapshot wiring
+
+[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the shipped leaf. [`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) replaces only the live LLM with replay. The tests under [`tests/`](tests/) own the keyless real-Loader smoke, key-gated world-verified smoke, and the `stream-json` replay snapshot with its parent and child session fixtures.
+
+The package-level [CLI contract](../../packages/examples/cli-demo/README.md) documents output records, exit status, cancellation, persistence, and model/token effects.
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index 6cd845783b..72d2813d17 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本目录负责 headless coding agent（智能体）的回放和真实模型测试组装：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与全新 agent Ralph 迭代 + `todo_write` + JSONL 持久化。本目录显式挂载共享 agent 主干、一个根 agent、持久化和检查点策略；它不是第二个产品入口。
+无头单次 agent（智能体）接线：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与新 agent Ralph 迭代 + `todo_write` + JSONL 持久化，并以 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) 作为应用入口。
 
 ## 运行
 
@@ -10,13 +10,27 @@
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run dsh run "fix the failing test in this workspace"
+pnpm run demo:headless "fix the failing test in this workspace"
+pnpm run demo:headless --output-format json -- "summarize the implementation"
+pnpm run demo:headless --output-format stream-json -- "run the focused tests"
 ```
 
-产品命令是 [`dsh run`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
+必须提供且只能提供一个非空位置任务；含空格的任务需要加引号。没有 `-p` 标志。`text` 打印最后一条包含文本的 assistant 消息，`json` 打印一条 DSH 原生结果记录，`stream-json` 则在该记录之前发出顶层会话的规范任务轮次事件。子会话只通过父工具事件和结果对外显示。
 
-快照套件通过 [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts) 运行本目录的配置。这个未导出且仅供测试使用的进程会在结果记录之前，以 JSONL 发出规范会话事件。该事件流属于测试基础设施，不是受支持的 CLI（命令行界面）输出格式。子会话只通过父会话的工具事件和结果对外显示。
+每次调用都会创建并持久化新会话，在一个轮次中运行所有模型和工具步骤，然后刷新、释放并退出。这是非交互式自动化：没有提示符、批准、恢复、第二轮次或 stdin 上下文。已配置工具可以修改启动 workspace、运行命令、spawn 子 agent，并消耗提供方 token。
 
-## 高级配置
+## E2B POC overlay
 
-[`advanced.cordis.yml`](advanced.cordis.yml) 在测试组装中添加 Code Mode 和 Cordis 工具。
+[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行：
+
+```sh
+pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+```
+
+该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。演示会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
+
+## 高级与快照接线
+
+[`advanced.cordis.yml`](advanced.cordis.yml) 在已交付叶节点上添加 Code Mode 和 Cordis 工具。[`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) 只将实时 LLM（大语言模型）替换为回放。[`tests/`](tests/) 下的测试拥有无密钥真实 Loader 冒烟测试、密钥门控的外部状态验证冒烟测试，以及带父子会话 fixture（测试前置数据）的 `stream-json` 回放快照。
+
+包级 [CLI 契约](../../packages/examples/cli-demo/README.md)记录输出记录、退出状态、取消、持久化以及模型／token 影响。
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
new file mode 100644
index 0000000000..4f961100b4
--- /dev/null
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -0,0 +1,30 @@
+# POC overlay: keep the headless agent and model-facing tools, but place its
+# filesystem and managed Bash process world in one short-lived E2B sandbox.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: subprocess
+        name: '@deepseek-ai/dsh-subprocess-local'
+        disabled: true
+      - id: fs-local
+        name: '@deepseek-ai/dsh-fs-local'
+        disabled: true
+      - id: bash
+        name: '@deepseek-ai/dsh-bash-local'
+        config:
+          cwd: !!js process.cwd()
+          timeoutMs: 60000
+      - insert:
+          - id: e2b
+            name: '@deepseek-ai/dsh-e2b'
+            config:
+              cwd: !!js process.cwd()
+              timeoutMs: 300000
+              onTimeout: kill
+              onDispose: kill
+          - id: subprocess-e2b
+            name: '@deepseek-ai/dsh-subprocess-e2b'
+          - id: fs-e2b
+            name: '@deepseek-ai/dsh-fs-e2b'
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
new file mode 100644
index 0000000000..3b2cef609b
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -0,0 +1,32 @@
+import { resolve } from 'node:path'
+import { boot } from '@deepseek-ai/dsh-app-boot'
+import type {} from '@deepseek-ai/dsh-e2b'
+import type {} from '@deepseek-ai/dsh-fs-e2b'
+import type {} from '@deepseek-ai/dsh-bash-local'
+
+const configPath = process.argv[2]
+if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
+
+const ctx = await boot('e2b-composition', resolve(configPath))
+try {
+  const fromFs = await ctx.fs.resolve('from-fs.txt')
+  await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
+  const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
+  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs\n') {
+    throw new Error(`E2B Bash could not read the FS write: ${JSON.stringify(bashRead)}`)
+  }
+
+  const bashWrite = await ctx.bash.run(ctx.bash.resolve({ command: "printf 'written-by-bash\\n' > from-bash.txt" }))
+  if (bashWrite.exitCode !== 0) {
+    throw new Error(`E2B Bash could not write the shared filesystem: ${JSON.stringify(bashWrite)}`)
+  }
+  const fromBash = await ctx.fs.resolve('from-bash.txt')
+  const fsRead = await ctx.fs.readText(fromBash)
+  process.stdout.write(`${JSON.stringify({
+    sandboxId: await ctx.e2b.sandboxId,
+    bashRead: bashRead.stdout.text,
+    fsRead,
+  })}\n`)
+} finally {
+  await ctx.fiber.dispose()
+}
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
new file mode 100644
index 0000000000..08a7e7225c
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -0,0 +1,19 @@
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: !!js process.cwd()
+    timeoutMs: 60000
+    onTimeout: kill
+    onDispose: kill
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: !!js process.cwd()
+    timeoutMs: 30000
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
diff --git a/examples/package.json b/examples/package.json
index 1f6e99d240..48ac39f5ca 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -26,7 +26,9 @@
     "@deepseek-ai/dsh-compact-basic": "workspace:*",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:*",
     "@deepseek-ai/dsh-credentials-local": "workspace:*",
+    "@deepseek-ai/dsh-e2b": "workspace:*",
     "@deepseek-ai/dsh-fs-local": "workspace:*",
+    "@deepseek-ai/dsh-fs-e2b": "workspace:*",
     "@deepseek-ai/dsh-fs-policy": "workspace:*",
     "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:*",
@@ -76,6 +78,7 @@
     "@deepseek-ai/dsh-subagent-fork": "workspace:*",
     "@deepseek-ai/dsh-subagent-spawn": "workspace:*",
     "@deepseek-ai/dsh-subprocess-local": "workspace:*",
+    "@deepseek-ai/dsh-subprocess-e2b": "workspace:*",
     "@deepseek-ai/dsh-system-prompt": "workspace:*",
     "@deepseek-ai/dsh-tasks-local": "workspace:*",
     "@deepseek-ai/dsh-time-context": "workspace:*",
diff --git a/knip.json b/knip.json
index ede8b2c738..d154cd646b 100644
--- a/knip.json
+++ b/knip.json
@@ -45,6 +45,7 @@
         "headless-agent/tests/fixtures/time-context-mock-llm.ts",
         "headless-agent/tests/fixtures/telemetry-otel-driver.ts",
         "headless-agent/tests/fixtures/telemetry-redact-rule.ts",
+        "headless-agent/tests/fixtures/e2b/e2b/bin.ts",
         "acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts",
         "acp-agent/tests/fixtures/child-question-tripwire.ts",
         "acp-agent/tests/fixtures/partial-landlock-sandbox.ts",
@@ -229,6 +230,16 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/e2b/e2b": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
     "packages/context/time-context": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 8aa9b92b91..3eee08f35b 100644
--- 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: 229feae568ba6e40a9c633696097eff46fd5bc95
-README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
+README.md: 1b2a1737bcac33829a65fa937668ca9496035330
+README.zh.md: 2ef61e9c38750f4420ce99abc9943af1f3308b56
diff --git a/packages/README.md b/packages/README.md
index 229feae568..54a5779016 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -16,6 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
+| [`e2b/`](e2b/README.md) | E2B remote filesystem/process providers | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index b84aef020a..46b112ec8f 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -16,6 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`e2b/`](e2b/README.md) | E2B 远程文件系统／进程管理提供方 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
new file mode 100644
index 0000000000..1bc9761930
--- /dev/null
+++ b/packages/e2b/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/e2b/README.md
+README.md: 4b28ec7c0452189a579a6d7e0cd22a0b8561784d
+README.zh.md: ab254eecad82c05cd6a6021e7f8bc4eda6cf3076
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
new file mode 100644
index 0000000000..4b28ec7c04
--- /dev/null
+++ b/packages/e2b/README.md
@@ -0,0 +1,13 @@
+# e2b/ — E2B remote runtime family
+
+English | [中文](README.zh.md)
+
+An experimental provider-composition POC that places the filesystem and managed subprocess world in one E2B Linux sandbox. The shared owner is separate from the capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
+
+| Package | ctx key | Role |
+|---|---|---|
+| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
+| [`fs-e2b`](../fs/fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
+| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
+
+The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it already delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world as `ctx.fs`. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, or E2B SDK buffers. The [decision record](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary and rejected expansion.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
new file mode 100644
index 0000000000..ab254eecad
--- /dev/null
+++ b/packages/e2b/README.zh.md
@@ -0,0 +1,13 @@
+# e2b/ — E2B 远程运行时家族
+
+[English](README.md) | 中文
+
+这是一个实验性提供方组合 POC，把文件系统和受管子进程环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器彼此分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
+
+| 包（package） | ctx 键 | 职责 |
+|---|---|---|
+| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
+| [`fs-e2b`](../fs/fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
+| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
+
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它已经把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 与 `ctx.fs` 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）或 E2B SDK 缓冲。[决策记录](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)负责说明 POC 边界及未采纳的扩展方案。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
new file mode 100644
index 0000000000..9255c21577
--- /dev/null
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
+README.md: bf62cb7d4811ca92f263bd3d337fff9fe41ce223
+README.zh.md: 8c7603aa501a2481aba6dab1f22750056e43ad26
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
new file mode 100644
index 0000000000..bf62cb7d48
--- /dev/null
+++ b/packages/e2b/e2b/README.md
@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-e2b
+
+English | [中文](README.zh.md)
+
+Shared lifecycle owner for one E2B sandbox. Filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`.
+
+## Configuration
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+    onTimeout: pause
+    onDispose: kill
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes. `onTimeout` is `pause` by default and accepts `pause | kill`; it applies only when this service creates a sandbox. Pause-on-timeout enables E2B auto-resume so the shared SDK handle wakes on its next operation. `onDispose` defaults to `kill` and accepts `kill | pause | leave`.
+
+Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` is creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
+
+## Lifecycle and ownership
+
+Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, then sets that directory to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+
+`pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
+
+## Model Experience
+
+None, as this shared runtime owner registers no model-visible context; provider adapters and their consumers own any rendered effects.
+
+#### KV Cache effect
+
+No direct invalidation; this package does not contribute request tokens.
+
+## Known Limitations and Deferred Work
+
+- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **Retained sandboxes do not restore host handles** — reconnect preserves remote files and adapter artifacts, but cannot reconstruct subprocess handles, stream cursors, or mutation locks; managed subprocesses terminate when their service disposes.
+- **No deployment platform is configured** — templates, volumes, snapshots, network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
+- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access also retains the template's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
new file mode 100644
index 0000000000..8c7603aa50
--- /dev/null
+++ b/packages/e2b/e2b/README.zh.md
@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-e2b
+
+[English](README.md) | 中文
+
+一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`。
+
+## 配置
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+    onTimeout: pause
+    onDispose: kill
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟。`onTimeout` 默认为 `pause`，接受 `pause | kill`；它只在本服务创建沙箱时生效。超时时 pause 会启用 E2B 自动恢复，使共享 SDK 句柄在下一次操作时唤醒。`onDispose` 默认为 `kill`，接受 `kill | pause | leave`。
+
+设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
+
+## 生命周期与所有权
+
+构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+
+`pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
+
+## 模型体验
+
+无。本共享运行时所有者不注册模型可见上下文；提供方适配器及其消费方拥有所有渲染效果。
+
+#### KV Cache 影响
+
+不会直接失效；本包不会贡献请求 token。
+
+## 已知限制与延后工作
+
+- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **保留的沙箱不会恢复宿主句柄**：重新连接会保留远程文件和适配器产物，但无法重建进程管理句柄、流游标或变更锁；进程管理服务 dispose 时会终止受管子进程。
+- **没有配置部署平台**：模板、卷、快照、网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用模板的策略。
diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
new file mode 100644
index 0000000000..7ecc5fabed
--- /dev/null
+++ b/packages/e2b/e2b/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-e2b",
+  "description": "Shared E2B sandbox lifecycle for DeepSeek Harness provider adapters",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "e2b": "2.29.1",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
new file mode 100644
index 0000000000..29cbf1dc53
--- /dev/null
+++ b/packages/e2b/e2b/src/index.ts
@@ -0,0 +1,240 @@
+/**
+ * Shared ownership of one E2B sandbox. Capability adapters await the same SDK
+ * handle, so filesystem and process operations inhabit one remote Linux world.
+ * @module @deepseek-ai/dsh-e2b
+ */
+
+import { posix } from 'node:path'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { Sandbox } from 'e2b'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+export {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  Sandbox,
+  SandboxError,
+  SandboxNotFoundError,
+  TimeoutError,
+} from 'e2b'
+export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
+
+/** Opaque E2B sandbox identity used for reconnecting a later harness process. */
+export type E2BSandboxId = Branded<'E2BSandboxId'>
+
+/**
+ * Brand an SDK sandbox id after E2B has created or resolved it.
+ * @param value - E2B's opaque sandbox id.
+ * @returns the same string with the harness brand.
+ */
+export function E2BSandboxId(value: string): E2BSandboxId {
+  return value as E2BSandboxId
+}
+
+/**
+ * Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
+ * @param value - Exact argument value to preserve.
+ * @returns A single shell word with no interpolation.
+ */
+export function quoteE2BShellArg(value: string): string {
+  return `'${value.replaceAll('\'', "'\"'\"'")}'`
+}
+
+/** Action taken on the owned sandbox when the Cordis service is disposed. */
+export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
+
+/** Action E2B takes when a newly created sandbox reaches its lifetime. */
+export type E2BTimeoutMode = 'kill' | 'pause'
+
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Existing sandbox to reconnect instead of creating a new one. */
+  sandboxId?: string
+  /** Template name or id for a newly created sandbox. */
+  template?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds. */
+  timeoutMs?: number
+  /** E2B action when a newly created sandbox reaches `timeoutMs`. */
+  onTimeout?: E2BTimeoutMode
+  /** Disposal policy; `pause` and `leave` retain remote state for reconnect. */
+  onDispose?: E2BDisposeMode
+}
+
+interface ResolvedConfig {
+  apiKey: string
+  cwd: string
+  timeoutMs: number
+  onTimeout: E2BTimeoutMode
+  onDispose: E2BDisposeMode
+  sandboxId?: string
+  template?: string
+}
+
+interface SchemaResolvedConfig extends Config {
+  cwd: string
+  timeoutMs: number
+  onTimeout: E2BTimeoutMode
+  onDispose: E2BDisposeMode
+}
+
+declare module 'cordis' {
+  interface Context {
+    e2b: E2BSandboxService
+  }
+}
+
+/**
+ * Owns one lazily consumable E2B SDK handle and its final kill/pause/leave
+ * decision. The connection begins at plugin construction; adapters await
+ * {@link getSandbox} before their first operation.
+ */
+export class E2BSandboxService extends Service {
+  static Config: z<Config> = z.object({
+    apiKey: z.string(),
+    sandboxId: z.string(),
+    template: z.string(),
+    cwd: z.string().default('/home/user/workspace'),
+    timeoutMs: z.number().default(300_000),
+    onTimeout: z.union(['kill', 'pause'] as const).default('pause'),
+    onDispose: z.union(['kill', 'pause', 'leave'] as const).default('kill'),
+  })
+
+  /** Validated remote working directory shared by provider adapters. */
+  readonly cwd: string
+  /** Remote directory reserved for adapter-owned process and terminal state. */
+  readonly runtimeRoot: string
+  /** Whether this service creates a sandbox rather than reconnecting one. */
+  readonly created: boolean
+  /** Configured action when a newly created sandbox reaches its lifetime. */
+  readonly timeoutMode: E2BTimeoutMode
+  /** Configured final sandbox disposition. */
+  readonly disposeMode: E2BDisposeMode
+  /** Sandbox id once E2B has created or resolved the remote runtime. */
+  readonly sandboxId: Promise<E2BSandboxId>
+
+  private readonly config: ResolvedConfig
+  private readonly ready: Promise<Sandbox>
+  private disposed = false
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'e2b')
+    // Schemastery fills these fields before construction; the type does not encode that step.
+    const resolved = config as SchemaResolvedConfig
+    const apiKey = config.apiKey ?? process.env.E2B_API_KEY
+    this.config = {
+      apiKey: apiKey ?? '',
+      cwd: resolved.cwd,
+      timeoutMs: resolved.timeoutMs,
+      onTimeout: resolved.onTimeout,
+      onDispose: resolved.onDispose,
+      ...(config.sandboxId !== undefined ? { sandboxId: config.sandboxId } : {}),
+      ...(config.template !== undefined ? { template: config.template } : {}),
+    }
+    this.validate()
+    this.cwd = this.config.cwd
+    this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
+    this.created = this.config.sandboxId === undefined
+    this.timeoutMode = this.config.onTimeout
+    this.disposeMode = this.config.onDispose
+    this.ready = this.open()
+    // A deployment may load the owner before any adapter uses it. Keep a
+    // failed eager connection observed; getSandbox() still returns the error.
+    void this.ready.catch(() => {})
+    this.sandboxId = this.ready.then(sandbox => E2BSandboxId(sandbox.sandboxId))
+    void this.sandboxId.catch(() => {})
+
+    ctx.effect(() => async () => {
+      this.disposed = true
+      let sandbox: Sandbox
+      try {
+        sandbox = await this.ready
+      } catch {
+        // Connection creation already failed and is exposed by getSandbox();
+        // there is no remote resource for teardown to own.
+        return
+      }
+      switch (this.config.onDispose) {
+        case 'kill':
+          await sandbox.kill()
+          return
+        case 'pause': {
+          await sandbox.pause()
+          return
+        }
+        case 'leave':
+          return
+      }
+    }, 'e2b sandbox teardown')
+  }
+
+  /**
+   * Return the shared live SDK handle.
+   * @returns the created or reconnected sandbox after the configured cwd exists.
+   * @throws when E2B rejects creation/reconnection or the service is disposing.
+   */
+  async getSandbox(): Promise<Sandbox> {
+    if (this.disposed) throw new Error('E2B sandbox service is disposing')
+    return await this.ready
+  }
+
+  private validate(): void {
+    if (this.config.apiKey.length === 0) {
+      throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
+    }
+    if (!posix.isAbsolute(this.config.cwd)) {
+      throw new Error(`dsh-e2b: cwd must be an absolute Linux path: ${this.config.cwd}`)
+    }
+    if (!Number.isFinite(this.config.timeoutMs) || this.config.timeoutMs <= 0) {
+      throw new Error('dsh-e2b: timeoutMs must be a positive finite number')
+    }
+    if (this.config.sandboxId !== undefined && this.config.sandboxId.length === 0) {
+      throw new Error('dsh-e2b: sandboxId must be non-empty when provided')
+    }
+    if (this.config.sandboxId !== undefined && this.config.template !== undefined) {
+      throw new Error('dsh-e2b: template applies only when creating; omit it when sandboxId reconnects')
+    }
+  }
+
+  private async open(): Promise<Sandbox> {
+    const connection = {
+      apiKey: this.config.apiKey,
+      timeoutMs: this.config.timeoutMs,
+    }
+    const sandbox = this.config.sandboxId === undefined
+      ? this.config.template === undefined
+        ? await Sandbox.create({
+          ...connection,
+          secure: true,
+          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
+        })
+        : await Sandbox.create(this.config.template, {
+          ...connection,
+          secure: true,
+          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
+        })
+      : await Sandbox.connect(this.config.sandboxId, connection)
+    try {
+      await sandbox.files.makeDir(this.cwd)
+      await sandbox.files.makeDir(this.runtimeRoot)
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`)
+      return sandbox
+    } catch (error: unknown) {
+      if (this.created) {
+        try {
+          await sandbox.kill()
+        } catch (_cleanupFailure) {
+          // The setup failure remains authoritative; E2B will still apply the configured lifetime.
+        }
+      }
+      throw error
+    }
+  }
+}
+
+export default E2BSandboxService
diff --git a/packages/e2b/e2b/src/invariant.ts b/packages/e2b/e2b/src/invariant.ts
new file mode 100644
index 0000000000..891cabb2db
--- /dev/null
+++ b/packages/e2b/e2b/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-e2b`.
+ * @module @deepseek-ai/dsh-e2b/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: sandbox creation and teardown have one SDK promise and
+ * no independent event or mutable-data relationship to cross-check.
+ */
+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))
+/* jscpd:ignore-end */
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
new file mode 100644
index 0000000000..8c01fae7b4
--- /dev/null
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -0,0 +1,39 @@
+import { access } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+
+const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
+const binScript = join(fixtureRoot, 'bin.ts')
+const configPath = join(fixtureRoot, 'cordis.yml')
+const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
+  it('shares remote state across FS and Bash without creating host workspace files', async () => {
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'E2B composition',
+      tempDirPrefix: 'dsh-e2b-composition-',
+      binScript,
+      libBinScript: binScript,
+      configPath,
+      tsconfigPath,
+      processTimeoutMs: 90_000,
+      inspect: async (cwd) => {
+        await expect(access(join(cwd, 'from-fs.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
+        await expect(access(join(cwd, 'from-bash.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
+      },
+    })
+
+    expect(stderr).toBe('')
+    const output = JSON.parse(stdout) as Record<string, unknown>
+    expect(output).toMatchObject({
+      bashRead: 'written-by-fs\n',
+      fsRead: 'written-by-bash\n',
+    })
+    const apiKey = process.env.E2B_API_KEY
+    if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
+    await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
+  }, 105_000)
+})
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
new file mode 100644
index 0000000000..c842731f5c
--- /dev/null
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -0,0 +1,218 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Sandbox as SandboxType } from 'e2b'
+import E2BSandboxService, {
+  E2BSandboxId,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import * as E2BInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+const sdk = vi.hoisted(() => ({
+  create: vi.fn(),
+  connect: vi.fn(),
+}))
+
+vi.mock('e2b', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('e2b')>()
+  // The mock replaces only the SDK's static factory surface and is never constructed.
+  // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+  class FakeSandbox {
+    static create(...args: unknown[]): unknown {
+      return sdk.create(...args)
+    }
+
+    static connect(...args: unknown[]): unknown {
+      return sdk.connect(...args)
+    }
+  }
+  return { ...actual, Sandbox: FakeSandbox }
+})
+
+interface SandboxFixture {
+  sandbox: SandboxType
+  makeDir: ReturnType<typeof vi.fn>
+  run: ReturnType<typeof vi.fn>
+  kill: ReturnType<typeof vi.fn>
+  pause: ReturnType<typeof vi.fn>
+}
+
+function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
+  const makeDir = vi.fn().mockResolvedValue(true)
+  const run = vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
+  const kill = vi.fn().mockResolvedValue(undefined)
+  const pause = vi.fn().mockResolvedValue(true)
+  const sandbox = {
+    sandboxId: id,
+    files: { makeDir },
+    commands: { run },
+    kill,
+    pause,
+  } as unknown as SandboxType
+  return { sandbox, makeDir, run, kill, pause }
+}
+
+beforeEach(() => {
+  sdk.create.mockReset()
+  sdk.connect.mockReset()
+  vi.unstubAllEnvs()
+})
+
+describe('E2BSandboxService', () => {
+  it('creates one protected shared sandbox and kills it on default disposal', async () => {
+    const fixture = fakeSandbox()
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    const service = ctx.e2b
+    await expect(service.getSandbox()).resolves.toBe(fixture.sandbox)
+    await expect(service.sandboxId).resolves.toBe(E2BSandboxId('sandbox-1'))
+    expect(service.cwd).toBe('/home/user/workspace')
+    expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
+    expect(service.created).toBe(true)
+    expect(service.timeoutMode).toBe('pause')
+    expect(service.disposeMode).toBe('kill')
+    expect(sdk.create).toHaveBeenCalledWith({
+      apiKey: 'test-key',
+      timeoutMs: 300_000,
+      secure: true,
+      lifecycle: { onTimeout: 'pause', autoResume: true },
+    })
+    expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
+    expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
+    expect(fixture.run).toHaveBeenCalledWith("chmod 700 -- '/home/user/workspace/.dsh-e2b'")
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    await expect(service.getSandbox()).rejects.toThrow(/disposing/)
+  })
+
+  it('creates from a template, honors timeout and pause policies, and reads the key from the environment', async () => {
+    vi.stubEnv('E2B_API_KEY', 'environment-key')
+    const fixture = fakeSandbox('template-sandbox')
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      template: 'agent-template',
+      cwd: '/workspace/project',
+      timeoutMs: 60_000,
+      onTimeout: 'kill',
+      onDispose: 'pause',
+    })
+    await ctx.e2b.getSandbox()
+
+    expect(sdk.create).toHaveBeenCalledWith('agent-template', {
+      apiKey: 'environment-key',
+      timeoutMs: 60_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill', autoResume: false },
+    })
+    await fiber.dispose()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+    expect(fixture.kill).not.toHaveBeenCalled()
+  })
+
+  it('accepts an already-paused result during configured pause disposal', async () => {
+    const fixture = fakeSandbox()
+    fixture.pause.mockResolvedValue(false)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', onDispose: 'pause' })
+    await ctx.e2b.getSandbox()
+    await fiber.dispose()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+  })
+
+  it('reconnects without applying creation lifecycle options and can leave state running', async () => {
+    const fixture = fakeSandbox('existing')
+    sdk.connect.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      apiKey: 'test-key',
+      sandboxId: 'existing',
+      timeoutMs: 90_000,
+      onDispose: 'leave',
+    })
+    await ctx.e2b.getSandbox()
+
+    expect(ctx.e2b.created).toBe(false)
+    expect(sdk.connect).toHaveBeenCalledWith('existing', { apiKey: 'test-key', timeoutMs: 90_000 })
+    expect(sdk.create).not.toHaveBeenCalled()
+    await fiber.dispose()
+    expect(fixture.kill).not.toHaveBeenCalled()
+    expect(fixture.pause).not.toHaveBeenCalled()
+  })
+
+  it('kills a newly created sandbox when remote directory setup fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
+    await expect(ctx.e2b.sandboxId).rejects.toThrow('setup failed')
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    await fiber.dispose()
+  })
+
+  it('preserves the setup failure even when cleanup also fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
+    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+  })
+
+  it('does not kill a reconnected sandbox when setup fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
+    sdk.connect.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
+    expect(fixture.kill).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    [{ apiKey: '' }, /configure apiKey/],
+    [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
+    [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
+    [{ apiKey: 'x', sandboxId: '' }, /sandboxId must be non-empty/],
+    [{ apiKey: 'x', sandboxId: 'one', template: 'two' }, /template applies only/],
+  ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
+    vi.stubEnv('E2B_API_KEY', '')
+    const ctx = new Context()
+    await expect(ctx.plugin(E2BSandboxService, config)).rejects.toThrow(message)
+    expect(sdk.create).not.toHaveBeenCalled()
+    expect(sdk.connect).not.toHaveBeenCalled()
+  })
+
+  it('requires a key when both config and the environment omit it', async () => {
+    const original = process.env.E2B_API_KEY
+    delete process.env.E2B_API_KEY
+    try {
+      const ctx = new Context()
+      await expect(ctx.plugin(E2BSandboxService, {})).rejects.toThrow(/configure apiKey/)
+    } finally {
+      if (original === undefined) delete process.env.E2B_API_KEY
+      else process.env.E2B_API_KEY = original
+    }
+  })
+})
+
+describe('E2B helpers and invariant companion', () => {
+  it('quotes opaque shell arguments without interpolation', () => {
+    expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/e2b/e2b/tsconfig.json b/packages/e2b/e2b/tsconfig.json
new file mode 100644
index 0000000000..5890a41d66
--- /dev/null
+++ b/packages/e2b/e2b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index c1a381cb81..eabb6a602e 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: b6adabd5744cb2b3dcee78b71815f8e95ba780f1
-README.zh.md: 0841f538932452921d2b0d7d9534f023672f241d
+README.md: 8ac8807cc9ca4b5cc31b686cef9796a8e42b7f81
+README.zh.md: 49705790cc0cdf1f7199251e09af0af01f704efb
diff --git a/packages/fs/README.md b/packages/fs/README.md
index b6adabd574..460af7c53b 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -8,12 +8,13 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 |---|---|---|
 | `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
+| `fs-e2b/` | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas — `fs-sandbox` is the first such replacement (an in-process path fence over the shared sandbox mode; see [the cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote runtime shared with the E2B subprocess provider ([POC decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 0841f53893..5f70e3cb50 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -8,12 +8,13 @@
 |---|---|---|
 | `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
+| `fs-e2b/` | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
 | `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
 | `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema；`fs-sandbox` 是第一个这样的替代实现（基于共享沙箱模式的进程内路径围栏；见[跨能力族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程运行时中（[POC 决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
diff --git a/packages/fs/fs-e2b/README.i18n.yaml b/packages/fs/fs-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..d3ea2786b2
--- /dev/null
+++ b/packages/fs/fs-e2b/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/fs/fs-e2b/README.md
+README.md: 2b23884e345e7c39b0559465afa0bc588699b70a
+README.zh.md: 1a9a174ac90c59b68b02887303f58ee2a99dc72e
diff --git a/packages/fs/fs-e2b/README.md b/packages/fs/fs-e2b/README.md
new file mode 100644
index 0000000000..2b23884e34
--- /dev/null
+++ b/packages/fs/fs-e2b/README.md
@@ -0,0 +1,29 @@
+# @deepseek-ai/dsh-fs-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+
+## Behavior
+
+- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
+- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through same-directory Linux `mv -f`. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
+
+The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
+
+## Model Experience
+
+Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
+- **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
+- **Custom templates must support the used Linux and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
diff --git a/packages/fs/fs-e2b/README.zh.md b/packages/fs/fs-e2b/README.zh.md
new file mode 100644
index 0000000000..1a9a174ac9
--- /dev/null
+++ b/packages/fs/fs-e2b/README.zh.md
@@ -0,0 +1,29 @@
+# @deepseek-ai/dsh-fs-e2b
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-fs`](../fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+
+## 行为
+
+- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
+- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过同目录 Linux `mv -f` 发布。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
+
+该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
+
+## 模型体验
+
+通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与延后工作
+
+- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
+- **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
+- **自定义模板必须支持所用的 Linux 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
diff --git a/packages/fs/fs-e2b/package.json b/packages/fs/fs-e2b/package.json
new file mode 100644
index 0000000000..cc96cba6c9
--- /dev/null
+++ b/packages/fs/fs-e2b/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-fs-e2b",
+  "description": "E2B filesystem implementation for DeepSeek Harness",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/fs/fs-e2b/src/index.ts b/packages/fs/fs-e2b/src/index.ts
new file mode 100644
index 0000000000..020b0f4857
--- /dev/null
+++ b/packages/fs/fs-e2b/src/index.ts
@@ -0,0 +1,423 @@
+/**
+ * E2B implementation of the filesystem provider seam. Paths, contents, and
+ * atomic staging files remain inside the shared remote sandbox.
+ * @module @deepseek-ai/dsh-fs-e2b
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { FileSystem, FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import type {
+  FsDirEntry,
+  FsEditOutcome,
+  FsEditRequest,
+  FsInfo,
+  FsPathInfo,
+  FsTarget,
+  FsWriteIntent,
+  FsWriteOutcome,
+} from '@deepseek-ai/dsh-fs'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
+
+const VERSION_METADATA_KEY = 'dsh-version'
+const BINARY_SAMPLE_BYTES = 8192
+
+function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
+  if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
+}
+
+function normalizeLineEndings(value: string): string {
+  return value.replaceAll('\r\n', '\n')
+}
+
+function detectsCrlf(value: string): boolean {
+  const sample = value.slice(0, 4096)
+  const crlf = sample.split('\r\n').length - 1
+  const lf = sample.split('\n').length - 1 - crlf
+  return crlf > lf
+}
+
+function restoreLineEndings(value: string, crlf: boolean): string {
+  return crlf ? normalizeLineEndings(value).replaceAll('\n', '\r\n') : value
+}
+
+function decodeText(bytes: Uint8Array, displayPath: string, binarySampleBytes: number): string {
+  if (bytes.subarray(0, binarySampleBytes).includes(0)) {
+    throw new FsError(`cannot read "${displayPath}": binary file`, 'FS_NOT_TEXT')
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch (error: unknown) {
+    throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+  }
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function entryType(entry: EntryInfo): FsInfo['type'] {
+  switch (entry.type) {
+    case FileType.FILE:
+      return 'file'
+    case FileType.DIR:
+      return 'directory'
+    default:
+      return 'other'
+  }
+}
+
+function entryVersion(entry: EntryInfo): ReturnType<typeof FsVersion> {
+  const facts = JSON.stringify([
+    entry.metadata?.[VERSION_METADATA_KEY],
+    entry.path,
+    entry.type,
+    entry.size,
+    entry.mode,
+    entry.modifiedTime?.toISOString(),
+    entry.symlinkTarget,
+  ])
+  return FsVersion(`e2b:${createHash('sha256').update(facts).digest('hex')}`)
+}
+
+function mapError(error: unknown, operation: string, displayPath: string, signal?: AbortSignal): FsError {
+  if (error instanceof FsError) return error
+  if (signal?.aborted === true || (error instanceof DOMException && error.name === 'AbortError')) {
+    return new FsError(`${operation} aborted`, 'FS_ABORTED', { cause: error })
+  }
+  if (error instanceof FileNotFoundError) {
+    return new FsError(`cannot ${operation} "${displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+  }
+  if (/permission denied|operation not permitted/i.test(String(error))) {
+    return new FsError(`cannot ${operation} "${displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
+  }
+  return new FsError(`cannot ${operation} "${displayPath}": ${String(error)}`, 'FS_IO_ERROR', { cause: error })
+}
+
+function literalEdit(content: string, request: FsEditRequest, displayPath: string): string {
+  const oldString = normalizeLineEndings(request.oldString)
+  const newString = normalizeLineEndings(request.newString)
+  if (oldString.length === 0) {
+    throw new FsError(`cannot edit "${displayPath}": old_string must be non-empty`, 'FS_EDIT_NOT_FOUND')
+  }
+  let matches = 0
+  let offset = 0
+  while (true) {
+    const found = content.indexOf(oldString, offset)
+    if (found < 0) break
+    matches += 1
+    offset = found + oldString.length
+  }
+  if (matches === 0) throw new FsError(`cannot edit "${displayPath}": old_string was not found`, 'FS_EDIT_NOT_FOUND')
+  if (!request.replaceAll && matches !== 1) {
+    throw new FsError(`cannot edit "${displayPath}": old_string matched ${matches} times`, 'FS_AMBIGUOUS_EDIT')
+  }
+  return request.replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString)
+}
+
+/** Remote filesystem backend sharing the sandbox owned by `ctx.e2b`. */
+export class E2BFileSystem extends FileSystem {
+  static inject = ['e2b']
+
+  private readonly locks = new Map<string, Promise<unknown>>()
+
+  override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
+    assertNotAborted(opts?.signal, 'resolve')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const displayPath = posix.resolve(opts?.cwd ?? this.ctx.e2b.cwd, path)
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const targetKey = await this.canonicalPath(sandbox, displayPath, opts?.signal)
+      assertNotAborted(opts?.signal, 'resolve')
+      return { targetKey: FsTargetKey(targetKey), displayPath }
+    } catch (error: unknown) {
+      throw mapError(error, 'resolve', displayPath, opts?.signal)
+    }
+  }
+
+  override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
+    assertNotAborted(signal, 'stat')
+    const entry = await this.probe(String(target.targetKey), target.displayPath, signal)
+    if (entry === undefined) return undefined
+    return {
+      version: entryVersion(entry),
+      type: entryType(entry),
+      ...(entry.type === FileType.FILE ? { size: entry.size } : {}),
+    }
+  }
+
+  override async lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined> {
+    assertNotAborted(signal, 'lstat')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const displayPath = posix.resolve(opts?.cwd ?? this.ctx.e2b.cwd, path)
+    const entry = await this.probe(displayPath, displayPath, signal)
+    if (entry === undefined) return undefined
+    const type = entry.symlinkTarget !== undefined
+      ? 'symlink' as const
+      : entry.type === FileType.FILE
+        ? 'file' as const
+        : entry.type === FileType.DIR
+          ? 'directory' as const
+          : 'other' as const
+    return {
+      version: entryVersion(entry),
+      type,
+      ...(entry.type === FileType.FILE ? { size: entry.size } : {}),
+    }
+  }
+
+  override async readText(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    try {
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'read')
+      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
+  override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    let stream: ReadableStream<Uint8Array>
+    try {
+      stream = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) })
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+    const displayPath = target.displayPath
+    return {
+      async *[Symbol.asyncIterator](): AsyncGenerator<string> {
+        const reader = stream.getReader()
+        const decoder = new TextDecoder('utf-8', { fatal: true })
+        let sampledBytes = 0
+        try {
+          while (true) {
+            assertNotAborted(signal, 'read')
+            const next = await reader.read()
+            if (next.done) break
+            if (sampledBytes < BINARY_SAMPLE_BYTES) {
+              const sample = next.value.subarray(0, BINARY_SAMPLE_BYTES - sampledBytes)
+              if (sample.includes(0)) throw new FsError(`cannot read "${displayPath}": binary file`, 'FS_NOT_TEXT')
+              sampledBytes += sample.length
+            }
+            let text: string
+            try {
+              text = decoder.decode(next.value, { stream: true })
+            } catch (error: unknown) {
+              throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+            }
+            if (text.length > 0) yield text
+          }
+          try {
+            decoder.decode()
+          } catch (error: unknown) {
+            throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+          }
+        } catch (error: unknown) {
+          throw mapError(error, 'read', displayPath, signal)
+        } finally {
+          reader.releaseLock()
+        }
+      },
+    }
+  }
+
+  override async listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]> {
+    const info = await this.stat(target, signal)
+    if (info === undefined) throw new FsError(`cannot list "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    if (info.type !== 'directory') throw new FsError(`cannot list "${target.displayPath}": not a directory`, 'FS_NOT_DIRECTORY')
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const listed = await sandbox.files.list(String(target.targetKey), { depth: 1, ...signalOpts(signal) })
+      const entries = await Promise.all(listed.map(async (entry): Promise<FsDirEntry> => {
+        const displayPath = posix.join(target.displayPath, entry.name)
+        const canonical = await this.canonicalPath(sandbox, entry.path, signal)
+        const resolved = await this.probe(canonical, displayPath, signal)
+        return {
+          name: entry.name,
+          type: resolved === undefined ? 'other' : entryType(resolved),
+          target: { targetKey: FsTargetKey(canonical), displayPath },
+          ...(resolved !== undefined ? { version: entryVersion(resolved) } : {}),
+          ...(resolved?.type === FileType.FILE ? { size: resolved.size } : {}),
+        }
+      }))
+      return entries.sort((left, right) => left.name.localeCompare(right.name))
+    } catch (error: unknown) {
+      throw mapError(error, 'list', target.displayPath, signal)
+    }
+  }
+
+  override async writeText(
+    target: FsTarget,
+    content: string,
+    expected?: FsWriteIntent,
+    signal?: AbortSignal,
+  ): Promise<FsWriteOutcome> {
+    return this.withLock(String(target.targetKey), async () => {
+      const existing = await this.probe(String(target.targetKey), target.displayPath, signal)
+      if (existing !== undefined && entryType(existing) !== 'file') {
+        throw new FsError(`cannot write "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      this.checkWriteIntent(existing, expected, target)
+      const before = existing === undefined ? null : await this.readForDiff(target, signal)
+      const version = await this.writeAtomic(target, content, existing, signal)
+      return {
+        operation: existing === undefined ? 'create' : 'update',
+        version,
+        before,
+        after: normalizeLineEndings(content),
+      }
+    })
+  }
+
+  override async editText(
+    target: FsTarget,
+    edit: FsEditRequest,
+    expected?: { version: ReturnType<typeof FsVersion> },
+    signal?: AbortSignal,
+  ): Promise<FsEditOutcome> {
+    return this.withLock(String(target.targetKey), async () => {
+      const existing = await this.probe(String(target.targetKey), target.displayPath, signal)
+      if (existing === undefined) {
+        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+      if (entryType(existing) !== 'file') {
+        throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      if (expected !== undefined && entryVersion(existing) !== expected.version) {
+        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+      const raw = await this.readForEdit(target, signal)
+      const before = normalizeLineEndings(raw)
+      const after = literalEdit(before, edit, target.displayPath)
+      const storage = restoreLineEndings(after, detectsCrlf(raw))
+      const version = await this.writeAtomic(target, storage, existing, signal)
+      return { version, before, after }
+    })
+  }
+
+  private async withLock<T>(targetKey: string, operation: () => Promise<T>): Promise<T> {
+    const prior = this.locks.get(targetKey) ?? Promise.resolve()
+    const run = prior.then(operation, operation)
+    const tail = run.then(() => undefined, () => undefined)
+    this.locks.set(targetKey, tail)
+    try {
+      return await run
+    } finally {
+      if (this.locks.get(targetKey) === tail) this.locks.delete(targetKey)
+    }
+  }
+
+  private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
+    try {
+      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, signalOpts(signal))
+      return result.stdout.replace(/\n$/, '')
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
+      throw error
+    }
+  }
+
+  private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
+    assertNotAborted(signal, 'stat')
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const entry = await sandbox.files.getInfo(path, signalOpts(signal))
+      assertNotAborted(signal, 'stat')
+      return entry
+    } catch (error: unknown) {
+      if (error instanceof FileNotFoundError) return undefined
+      throw mapError(error, 'stat', displayPath, signal)
+    }
+  }
+
+  private async requireRegular(target: FsTarget, signal?: AbortSignal): Promise<void> {
+    const info = await this.stat(target, signal)
+    if (info === undefined) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+  }
+
+  private checkWriteIntent(existing: EntryInfo | undefined, expected: FsWriteIntent | undefined, target: FsTarget): void {
+    if (expected?.kind === 'createIfAbsent' && existing !== undefined) {
+      throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, 'FS_NOT_OBSERVED')
+    }
+    if (expected?.kind === 'replaceIfVersion') {
+      if (existing === undefined || entryVersion(existing) !== expected.version) {
+        throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+    }
+  }
+
+  private async readForDiff(target: FsTarget, signal?: AbortSignal): Promise<string | null> {
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'read')
+      return normalizeLineEndings(decodeText(bytes, target.displayPath, bytes.length))
+    } catch (error: unknown) {
+      if (error instanceof FsError && error.code === 'FS_NOT_TEXT') return null
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
+  private async readForEdit(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'edit')
+      return decodeText(bytes, target.displayPath, bytes.length)
+    } catch (error: unknown) {
+      throw mapError(error, 'edit', target.displayPath, signal)
+    }
+  }
+
+  private async writeAtomic(
+    target: FsTarget,
+    content: string,
+    existing: EntryInfo | undefined,
+    signal?: AbortSignal,
+  ): Promise<ReturnType<typeof FsVersion>> {
+    assertNotAborted(signal, 'write')
+    const sandbox = await this.ctx.e2b.getSandbox()
+    const targetPath = String(target.targetKey)
+    const versionId = randomUUID()
+    const temporary = posix.join(posix.dirname(targetPath), `.${posix.basename(targetPath)}.dsh-${randomUUID()}.tmp`)
+    try {
+      await sandbox.files.write(temporary, content, {
+        metadata: { [VERSION_METADATA_KEY]: versionId },
+        ...signalOpts(signal),
+      })
+      assertNotAborted(signal, 'write')
+      const mode = existing === undefined ? 0o600 : existing.mode & 0o777
+      await sandbox.commands.run(
+        `chmod ${mode.toString(8)} -- ${quoteE2BShellArg(temporary)}`,
+        signalOpts(signal),
+      )
+      assertNotAborted(signal, 'write')
+      await sandbox.commands.run(
+        `mv -f -- ${quoteE2BShellArg(temporary)} ${quoteE2BShellArg(targetPath)}`,
+        signalOpts(signal),
+      )
+      const committed = await sandbox.files.getInfo(targetPath)
+      return entryVersion(committed)
+    } catch (error: unknown) {
+      try {
+        await sandbox.files.remove(temporary)
+      } catch (_temporaryAlreadyAbsent) {
+        // Only the private staging path is swallowed; the original failure owns the operation.
+      }
+      throw mapError(error, 'write', target.displayPath, signal)
+    }
+  }
+}
+
+export default E2BFileSystem
diff --git a/packages/fs/fs-e2b/src/invariant.ts b/packages/fs/fs-e2b/src/invariant.ts
new file mode 100644
index 0000000000..6294d66ace
--- /dev/null
+++ b/packages/fs/fs-e2b/src/invariant.ts
@@ -0,0 +1,27 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-e2b-invariant'
+/** Service required before reserving package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: each operation returns the E2B controller's committed
+ * result directly, with no independent event or cache to cross-check.
+ */
+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))
+/* jscpd:ignore-end */
diff --git a/packages/fs/fs-e2b/tests/filesystem.spec.ts b/packages/fs/fs-e2b/tests/filesystem.spec.ts
new file mode 100644
index 0000000000..b8eb5447d6
--- /dev/null
+++ b/packages/fs/fs-e2b/tests/filesystem.spec.ts
@@ -0,0 +1,537 @@
+import { dirname, posix } from 'node:path'
+import { Context } from 'cordis'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  type EntryInfo,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { FsVersion } from '@deepseek-ai/dsh-fs'
+import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
+import * as E2BFsInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { describe, expect, it } from 'vitest'
+
+interface RemoteNode {
+  type: FileType
+  data: Uint8Array
+  mode: number
+  modified: number
+  metadata?: Record<string, string>
+  symlinkTarget?: string
+}
+
+function bytes(value: string | readonly number[]): Uint8Array {
+  return typeof value === 'string' ? new TextEncoder().encode(value) : Uint8Array.from(value)
+}
+
+function commandError(exitCode: number, stderr = ''): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr, error: stderr })
+}
+
+class FakeRemote {
+  readonly nodes = new Map<string, RemoteNode>()
+  readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
+  readonly renames: Array<{ from: string; to: string }> = []
+  readonly removals: string[] = []
+  readonly commands: string[] = []
+  streamChunks: Uint8Array[] | undefined
+  nextCommandError: unknown
+  nextInfoError: unknown
+  nextListError: unknown
+  nextReadError: unknown
+  nextRenameError: unknown
+  nextRemoveError: unknown
+  abortAfterRename: AbortController | undefined
+  disappearOnInfo = new Set<string>()
+  private clock = 1
+
+  constructor() {
+    this.dir('/')
+    this.dir('/workspace')
+  }
+
+  dir(path: string): void {
+    this.nodes.set(path, { type: FileType.DIR, data: bytes(''), mode: 0o755, modified: this.clock++ })
+  }
+
+  file(path: string, data: string | readonly number[], mode = 0o644): void {
+    this.nodes.set(path, { type: FileType.FILE, data: bytes(data), mode, modified: this.clock++ })
+  }
+
+  other(path: string): void {
+    this.nodes.set(path, { type: 'other' as FileType, data: bytes(''), mode: 0o600, modified: this.clock++ })
+  }
+
+  symlink(path: string, target: string): void {
+    this.nodes.set(path, {
+      type: FileType.FILE,
+      data: bytes(''),
+      mode: 0o777,
+      modified: this.clock++,
+      symlinkTarget: target,
+    })
+  }
+
+  mutate(path: string, data: string): void {
+    const node = this.required(path)
+    node.data = bytes(data)
+    node.modified = this.clock++
+  }
+
+  private required(path: string): RemoteNode {
+    const node = this.nodes.get(path)
+    if (node === undefined) throw new FileNotFoundError(`missing: ${path}`)
+    return node
+  }
+
+  private followed(path: string): { path: string; node: RemoteNode; link?: RemoteNode } {
+    const node = this.required(path)
+    if (node.symlinkTarget === undefined) return { path, node }
+    return { path: node.symlinkTarget, node: this.required(node.symlinkTarget), link: node }
+  }
+
+  private info(path: string): EntryInfo {
+    if (this.disappearOnInfo.delete(path)) throw new FileNotFoundError(`missing: ${path}`)
+    return this.rawInfo(path)
+  }
+
+  private rawInfo(path: string): EntryInfo {
+    const followed = this.followed(path)
+    const node = followed.node
+    return {
+      name: posix.basename(path),
+      path,
+      type: node.type,
+      size: node.data.byteLength,
+      mode: node.mode,
+      permissions: 'rw-------',
+      owner: 'user',
+      group: 'user',
+      modifiedTime: new Date(node.modified),
+      ...(node.metadata !== undefined ? { metadata: { ...node.metadata } } : {}),
+      ...(followed.link?.symlinkTarget !== undefined ? { symlinkTarget: followed.link.symlinkTarget } : {}),
+    }
+  }
+
+  private checkAbort(options: { signal?: AbortSignal } | undefined): void {
+    if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
+  }
+
+  readonly sandbox = {
+    sandboxId: 'fake',
+    files: {
+      makeDir: async (path: string): Promise<boolean> => {
+        if (this.nodes.has(path)) return false
+        this.dir(path)
+        return true
+      },
+      getInfo: async (path: string, options?: { signal?: AbortSignal }): Promise<EntryInfo> => {
+        this.checkAbort(options)
+        if (this.nextInfoError !== undefined) {
+          const error = this.nextInfoError
+          this.nextInfoError = undefined
+          throw error
+        }
+        return this.info(path)
+      },
+      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array>> => {
+        this.checkAbort(options)
+        if (this.nextReadError !== undefined) {
+          const error = this.nextReadError
+          this.nextReadError = undefined
+          throw error
+        }
+        const data = this.followed(path).node.data
+        if (options.format === 'bytes') return data.slice()
+        const chunks = this.streamChunks ?? [data.slice()]
+        return new ReadableStream<Uint8Array>({
+          start(controller) {
+            for (const chunk of chunks) controller.enqueue(chunk)
+            controller.close()
+          },
+        })
+      },
+      list: async (path: string, options?: { depth?: number; signal?: AbortSignal }): Promise<EntryInfo[]> => {
+        this.checkAbort(options)
+        if (this.nextListError !== undefined) {
+          const error = this.nextListError
+          this.nextListError = undefined
+          throw error
+        }
+        this.required(path)
+        return [...this.nodes.keys()]
+          .filter(candidate => candidate !== path && dirname(candidate) === path)
+          .map(candidate => this.rawInfo(candidate))
+      },
+      write: async (path: string, data: string, options?: { metadata?: Record<string, string>; signal?: AbortSignal }): Promise<object> => {
+        this.checkAbort(options)
+        const parent = dirname(path)
+        if (!this.nodes.has(parent)) this.dir(parent)
+        this.nodes.set(path, {
+          type: FileType.FILE,
+          data: bytes(data),
+          mode: 0o644,
+          modified: this.clock++,
+          ...(options?.metadata !== undefined ? { metadata: { ...options.metadata } } : {}),
+        })
+        this.writes.push({ path, data, ...(options?.metadata !== undefined ? { metadata: options.metadata } : {}) })
+        return {}
+      },
+      rename: async (from: string, to: string, options?: { signal?: AbortSignal }): Promise<EntryInfo> => {
+        this.checkAbort(options)
+        if (this.nextRenameError !== undefined) {
+          const error = this.nextRenameError
+          this.nextRenameError = undefined
+          throw error
+        }
+        const node = this.required(from)
+        this.nodes.delete(from)
+        this.nodes.set(to, node)
+        this.renames.push({ from, to })
+        this.abortAfterRename?.abort('after commit')
+        return this.info(to)
+      },
+      remove: async (path: string): Promise<void> => {
+        this.removals.push(path)
+        if (this.nextRemoveError !== undefined) {
+          const error = this.nextRemoveError
+          this.nextRemoveError = undefined
+          throw error
+        }
+        this.nodes.delete(path)
+      },
+    },
+    commands: {
+      run: async (command: string, options?: { signal?: AbortSignal }): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
+        this.checkAbort(options)
+        this.commands.push(command)
+        if (this.nextCommandError !== undefined) {
+          const error = this.nextCommandError
+          this.nextCommandError = undefined
+          throw error
+        }
+        if (command.startsWith('realpath -m -- ')) {
+          const input = command.slice('realpath -m -- '.length).slice(1, -1)
+          const node = this.nodes.get(input)
+          return { exitCode: 0, stdout: `${node?.symlinkTarget ?? input}\n`, stderr: '' }
+        }
+        const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
+        if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
+        const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
+        if (move !== null) {
+          if (this.nextRenameError !== undefined) {
+            const error = this.nextRenameError
+            this.nextRenameError = undefined
+            throw error
+          }
+          const node = this.required(move[1]!)
+          this.nodes.delete(move[1]!)
+          this.nodes.set(move[2]!, node)
+          this.renames.push({ from: move[1]!, to: move[2]! })
+          this.abortAfterRename?.abort('after commit')
+        }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+async function setup(remote = new FakeRemote()): Promise<{ ctx: Context; fs: E2BFileSystem; remote: FakeRemote }> {
+  const ctx = new Context()
+  const runtime = {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    disposeMode: 'kill',
+    getSandbox: async () => remote.sandbox,
+  } as unknown as E2BSandboxService
+  ctx.provide('e2b', runtime)
+  await ctx.plugin(E2BFileSystem)
+  return { ctx, fs: ctx.fs as E2BFileSystem, remote }
+}
+
+async function expectCode(promise: Promise<unknown>, code: string): Promise<void> {
+  await expect(promise).rejects.toMatchObject({ code })
+}
+
+describe('E2BFileSystem identity, metadata, and reads', () => {
+  it('resolves remote paths, reports symlinks, and lists direct children in stable order', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/z.txt', 'z')
+    remote.file('/workspace/a.txt', 'a')
+    remote.dir('/workspace/dir')
+    remote.other('/workspace/special')
+    remote.file('/workspace/dir/nested.txt', 'nested')
+    remote.symlink('/workspace/link.txt', '/workspace/a.txt')
+    const { fs } = await setup(remote)
+
+    const link = await fs.resolve('link.txt')
+    expect(link).toEqual({ targetKey: '/workspace/a.txt', displayPath: '/workspace/link.txt' })
+    await expect(fs.lstat('link.txt')).resolves.toMatchObject({ type: 'symlink', size: 1 })
+    await expect(fs.lstat('a.txt')).resolves.toMatchObject({ type: 'file', size: 1 })
+    await expect(fs.lstat('dir')).resolves.toEqual(expect.objectContaining({ type: 'directory' }))
+    await expect(fs.lstat('special')).resolves.toEqual(expect.objectContaining({ type: 'other' }))
+    await expect(fs.lstat('missing')).resolves.toBeUndefined()
+    await expect(fs.stat(link)).resolves.toMatchObject({ type: 'file', size: 1 })
+    const directory = await fs.resolve('.')
+    const listed = await fs.listDir(directory)
+    expect(listed.map(entry => entry.name)).toEqual(['a.txt', 'dir', 'link.txt', 'special', 'z.txt'])
+    expect(listed.find(entry => entry.name === 'dir')).toMatchObject({ type: 'directory' })
+    expect(listed.find(entry => entry.name === 'link.txt')).toMatchObject({
+      type: 'file',
+      target: { targetKey: '/workspace/a.txt', displayPath: '/workspace/link.txt' },
+    })
+    expect(listed.some(entry => entry.name === 'nested.txt')).toBe(false)
+  })
+
+  it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/text.txt', 'A€B')
+    remote.streamChunks = [bytes([65, 0xe2]), bytes([0x82, 0xac, 66])]
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('text.txt')
+    await expect(fs.readText(target)).resolves.toBe('A€B')
+    let streamed = ''
+    for await (const chunk of await fs.streamText(target)) streamed += chunk
+    expect(streamed).toBe('A€B')
+
+    remote.streamChunks = [bytes([0xe2]), bytes([0x82, 0xac])]
+    let initiallyBuffered = ''
+    for await (const chunk of await fs.streamText(target)) initiallyBuffered += chunk
+    expect(initiallyBuffered).toBe('€')
+  })
+
+  it('matches local binary sampling while edits still reject any NUL byte', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/late-nul.txt', `${'a'.repeat(8192)}\0tail`)
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('late-nul.txt')
+    await expect(fs.readText(target)).resolves.toContain('\0tail')
+    remote.streamChunks = [bytes('a'.repeat(8192)), bytes([0, 116])]
+    let streamed = ''
+    for await (const chunk of await fs.streamText(target)) streamed += chunk
+    expect(streamed).toBe(`${'a'.repeat(8192)}\0t`)
+    await expectCode(fs.editText(target, { oldString: 'tail', newString: 'end', replaceAll: false }), 'FS_NOT_TEXT')
+  })
+
+  it('maps binary, invalid UTF-8, missing, and non-regular read failures', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/binary', [0, 1])
+    remote.file('/workspace/invalid', [0xff])
+    remote.dir('/workspace/directory')
+    const { fs } = await setup(remote)
+    await expectCode(fs.readText(await fs.resolve('binary')), 'FS_NOT_TEXT')
+    await expectCode(fs.readText(await fs.resolve('invalid')), 'FS_NOT_TEXT')
+    await expectCode(fs.readText(await fs.resolve('missing')), 'FS_NOT_FOUND')
+    await expectCode(fs.readText(await fs.resolve('directory')), 'FS_NOT_REGULAR_FILE')
+
+    remote.streamChunks = [bytes([0xff])]
+    const invalid = await fs.streamText(await fs.resolve('invalid'))
+    await expect((async () => { for await (const _chunk of invalid) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+    remote.streamChunks = [bytes([0])]
+    const binary = await fs.streamText(await fs.resolve('binary'))
+    await expect((async () => { for await (const _chunk of binary) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+
+    remote.streamChunks = [bytes([0xe2])]
+    const incomplete = await fs.streamText(await fs.resolve('invalid'))
+    await expect((async () => { for await (const _chunk of incomplete) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+
+    const raced = await fs.resolve('invalid')
+    remote.nextReadError = new FileNotFoundError('gone after stat')
+    await expectCode(fs.streamText(raced), 'FS_NOT_FOUND')
+  })
+
+  it('honors aborts before and during remote reads', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'a')
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('a', { signal: AbortSignal.abort() }), 'FS_ABORTED')
+    await expectCode(fs.lstat('a', undefined, AbortSignal.abort()), 'FS_ABORTED')
+    await expectCode(fs.stat(await fs.resolve('a'), AbortSignal.abort()), 'FS_ABORTED')
+    remote.nextReadError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
+  })
+
+  it('rejects empty paths and directory-listing type errors', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file', 'x')
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('   '), 'FS_NOT_FOUND')
+    await expectCode(fs.lstat(''), 'FS_NOT_FOUND')
+    await expectCode(fs.listDir(await fs.resolve('missing')), 'FS_NOT_FOUND')
+    await expectCode(fs.listDir(await fs.resolve('/workspace/file')), 'FS_NOT_DIRECTORY')
+    remote.nextListError = new Error('listing transport failed')
+    await expectCode(fs.listDir(await fs.resolve('/workspace')), 'FS_IO_ERROR')
+  })
+})
+
+describe('E2BFileSystem atomic writes and edits', () => {
+  it('creates owner-only files and returns metadata after the committed move', async () => {
+    const { fs, remote } = await setup()
+    const target = await fs.resolve('new.txt')
+    const outcome = await fs.writeText(target, 'one\r\ntwo\rthree', { kind: 'createIfAbsent' })
+    expect(outcome).toMatchObject({ operation: 'create', before: null, after: 'one\ntwo\rthree' })
+    expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
+    expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
+    await expect(fs.stat(target)).resolves.toMatchObject({ version: outcome.version, size: 14 })
+  })
+
+  it('preserves replacement mode, normalizes only CRLF for diffs, and changes version on external writes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'old\r\nline\rlone', 0o640)
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const before = (await fs.stat(target))!.version
+    const outcome = await fs.writeText(target, 'new', { kind: 'replaceIfVersion', version: before })
+    expect(outcome).toMatchObject({ operation: 'update', before: 'old\nline\rlone', after: 'new' })
+    expect(remote.nodes.get('/workspace/file.txt')?.mode).toBe(0o640)
+    const committed = outcome.version
+    remote.mutate('/workspace/file.txt', 'external')
+    expect((await fs.stat(target))!.version).not.toBe(committed)
+  })
+
+  it('returns null as the overwrite diff basis for binary or invalid prior content', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', [0xff])
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    await expect(fs.writeText(target, 'valid')).resolves.toMatchObject({ before: null, after: 'valid' })
+  })
+
+  it('fails an overwrite when reading its text diff basis fails for another reason', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'prior')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    remote.nextReadError = new Error('read transport failed')
+    await expectCode(fs.writeText(target, 'replacement'), 'FS_IO_ERROR')
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/file.txt')?.data)).toBe('prior')
+  })
+
+  it('enforces create and version intents before publication', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'v1')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    await expectCode(fs.writeText(target, 'blind', { kind: 'createIfAbsent' }), 'FS_NOT_OBSERVED')
+    remote.mutate('/workspace/file.txt', 'v2')
+    await expectCode(fs.writeText(target, 'stale', { kind: 'replaceIfVersion', version }), 'FS_STALE_VERSION')
+    await expectCode(fs.writeText(await fs.resolve('missing'), 'stale', { kind: 'replaceIfVersion', version }), 'FS_STALE_VERSION')
+    remote.dir('/workspace/dir')
+    await expectCode(fs.writeText(await fs.resolve('dir'), 'x'), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('does not turn an abort observed after a successful move into a failed write', async () => {
+    const remote = new FakeRemote()
+    const controller = new AbortController()
+    remote.abortAfterRename = controller
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes', undefined, controller.signal))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(controller.signal.aborted).toBe(true)
+  })
+
+  it('cleans staging files and maps command, permission, and abort failures', async () => {
+    const remote = new FakeRemote()
+    const { fs } = await setup(remote)
+    const commandTarget = await fs.resolve('command')
+    remote.nextCommandError = commandError(1, 'chmod failed')
+    await expectCode(fs.writeText(commandTarget, 'x'), 'FS_IO_ERROR')
+    expect(remote.removals).toHaveLength(1)
+
+    remote.nextRenameError = new Error('permission denied')
+    await expectCode(fs.writeText(await fs.resolve('permission'), 'x'), 'FS_PERMISSION_DENIED')
+    remote.nextRemoveError = new Error('cleanup also failed')
+    remote.nextRenameError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.writeText(await fs.resolve('abort'), 'x'), 'FS_ABORTED')
+  })
+
+  it('applies literal edits atomically and restores the detected CRLF style', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'one\r\ntwo\r\nthree\n')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    const outcome = await fs.editText(
+      target,
+      { oldString: 'two\r\n', newString: 'TWO\r\n', replaceAll: false },
+      { version },
+    )
+    expect(outcome).toMatchObject({ before: 'one\ntwo\nthree\n', after: 'one\nTWO\nthree\n' })
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/file.txt')?.data)).toBe('one\r\nTWO\r\nthree\r\n')
+  })
+
+  it('reports stale and literal-match failures with stable codes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'a a')
+    remote.dir('/workspace/dir')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    await expectCode(fs.editText(target, { oldString: '', newString: 'x', replaceAll: false }), 'FS_EDIT_NOT_FOUND')
+    await expectCode(fs.editText(target, { oldString: 'z', newString: 'x', replaceAll: false }), 'FS_EDIT_NOT_FOUND')
+    await expectCode(fs.editText(target, { oldString: 'a', newString: 'x', replaceAll: false }), 'FS_AMBIGUOUS_EDIT')
+    await expect(fs.editText(target, { oldString: 'a', newString: 'x', replaceAll: true }))
+      .resolves.toMatchObject({ after: 'x x' })
+    await expectCode(fs.editText(target, { oldString: 'x', newString: 'y', replaceAll: false }, { version: FsVersion('stale') }), 'FS_STALE_VERSION')
+    await expectCode(fs.editText(await fs.resolve('missing'), { oldString: 'x', newString: 'y', replaceAll: false }), 'FS_STALE_VERSION')
+    await expectCode(fs.editText(await fs.resolve('dir'), { oldString: 'x', newString: 'y', replaceAll: false }), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('serializes guarded mutations so only one stale version can win', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'base')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    const results = await Promise.allSettled([
+      fs.writeText(target, 'one', { kind: 'replaceIfVersion', version }),
+      fs.editText(target, { oldString: 'base', newString: 'two', replaceAll: false }, { version }),
+    ])
+    expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1)
+    expect(results.filter(result => result.status === 'rejected')).toHaveLength(1)
+  })
+})
+
+describe('E2B filesystem adapter integration edges', () => {
+  it('maps canonicalization, permission, and generic provider failures', async () => {
+    const remote = new FakeRemote()
+    const { fs } = await setup(remote)
+    remote.nextCommandError = commandError(1, 'not a directory')
+    await expectCode(fs.resolve('bad'), 'FS_IO_ERROR')
+    remote.nextCommandError = commandError(1)
+    await expectCode(fs.resolve('bad-again'), 'FS_IO_ERROR')
+    remote.nextCommandError = new Error('canonical transport failed')
+    await expectCode(fs.resolve('bad-transport'), 'FS_IO_ERROR')
+    remote.file('/workspace/a', 'a')
+    const target = await fs.resolve('a')
+    remote.nextInfoError = new Error('metadata transport failed')
+    await expectCode(fs.stat(target), 'FS_IO_ERROR')
+    remote.nextReadError = new Error('operation not permitted')
+    await expectCode(fs.readText(target), 'FS_PERMISSION_DENIED')
+    remote.nextReadError = 'transport vanished'
+    await expectCode(fs.readText(target), 'FS_IO_ERROR')
+  })
+
+  it('keeps a listed child whose metadata disappears as an other entry', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'a')
+    remote.disappearOnInfo.add('/workspace/a')
+    const { fs } = await setup(remote)
+    const listed = await fs.listDir(await fs.resolve('/workspace'))
+    expect(listed).toEqual([{
+      name: 'a',
+      type: 'other',
+      target: { targetKey: '/workspace/a', displayPath: '/workspace/a' },
+    }])
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BFsInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/fs/fs-e2b/tsconfig.json b/packages/fs/fs-e2b/tsconfig.json
new file mode 100644
index 0000000000..c424efd2e5
--- /dev/null
+++ b/packages/fs/fs-e2b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../e2b/e2b"
+    },
+    {
+      "path": "../fs"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 0ebb5bd4af..0efaf7838e 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: f2b19436da40feb14d067e2cfc706222625680b5
-README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
+README.md: ae18c55205edd6085a0ed8de1bb7f875c411c79f
+README.zh.md: e27fd240e4c1e96d8b859b326574e441241e8508
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index f2b19436da..ae18c55205 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared home for spawning managed child-process trees: fully-specified spawn specs with Node-shaped per-stream stdio dispositions (raw pipes, inherit, bounded tail-keep collection with spill files), the one credential scrub every harness spawner uses, offset-based incremental reads, tree-scoped signalling with SIGTERM→grace→SIGKILL escalation, and the cooperative dispose ladder. Command defaulting, shell semantics, deadlines, protocol framing, and presentation stay with consumers — the [bash executors](../bash/README.md), the [LSP host](../lsp/README.md), and the [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: abstract `SubprocessService.spawn(spec)`, the fully-explicit `SubprocessSpawnSpec` with per-stream stdio dispositions, `SubprocessHandle` (streams, offset-based readers, terminate/waitForExit/dispose), and the shared scrub + `DSH_*`/`CollectedOutput` vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, per-disposition stream wiring, tail-keep truncation with bounded private spill files, the `DSH_*` merge order, tree signalling with escalation, the dispose ladder, and terminate-and-join disposal |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 938312448d..e27fd240e4 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,12 +1,13 @@
-# subprocess/：子进程能力家族
+# subprocess/：进程管理能力家族
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其 stdio 处置方式（disposition）为 Node 形状、按流划分（原始管道、inherit、附带 spill 文件的有界尾部保留收集）；harness 中所有 spawn 调用方共用的那一份凭据清除；基于偏移量的增量读取；以进程树为范围、带 SIGTERM→宽限期→SIGKILL 升级的信号发送；以及协作式 dispose（资源释放）阶梯。命令默认值补全、shell 语义、deadline、协议分帧与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
 
-即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
+服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/packages/subprocess/subprocess-e2b/README.i18n.yaml b/packages/subprocess/subprocess-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..dfbe97e8b9
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/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/subprocess/subprocess-e2b/README.md
+README.md: 9ec1518103413f33a52023c17722bf5a5fe275ce
+README.zh.md: f50ff2f3d85a5ddd9bd352e95d0eb0a23e756404
diff --git a/packages/subprocess/subprocess-e2b/README.md b/packages/subprocess/subprocess-e2b/README.md
new file mode 100644
index 0000000000..9ec1518103
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/README.md
@@ -0,0 +1,32 @@
+# @deepseek-ai/dsh-subprocess-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
+
+## Behavior
+
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the SDK returns the command PID; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Linux process groups** — a quoted wrapper starts each argv under `setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of assuming the SDK command PID is the group id. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
+- **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
+
+The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, and `kill`. A custom template must retain compatible commands.
+
+## Model Experience
+
+Indirectly, through consumer seams such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumers own any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate even when this adapter exposes bounded tails, so the subprocess seam's normal host-memory bound is not achieved.
+- **Pipe output is not byte-faithful** — E2B delivers separately decoded strings rather than raw bytes, so split multibyte sequences and arbitrary binary protocols can be corrupted; LSP and other framed byte-stream consumers are unsupported.
+- **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
+- **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
+- **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
+- **Signal attribution is inferred** — when termination was requested and E2B reports a nonzero exit code, the adapter reports the last requested signal because the SDK result does not identify the terminating signal.
+- **Linux utility and E2B transport semantics are assumed** — there is no PTY, Windows, arbitrary-template, or network-partition fidelity layer.
diff --git a/packages/subprocess/subprocess-e2b/README.zh.md b/packages/subprocess/subprocess-e2b/README.zh.md
new file mode 100644
index 0000000000..f50ff2f3d8
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/README.zh.md
@@ -0,0 +1,32 @@
+# @deepseek-ai/dsh-subprocess-e2b
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
+
+## 行为
+
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。SDK 返回命令 PID 之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **Linux 进程组**：带引号保护的包装层会在 `setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会假设 SDK 命令 PID 就是进程组 ID。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
+- **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+
+基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee` 和 `kill`。自定义模板必须保留兼容的命令。
+
+## 模型体验
+
+通过消费方 seam 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些消费方会渲染远程输出、退出事实、后台增量和 spill 路径。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与延后工作
+
+- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会持续累积，因此无法达到进程管理 seam 通常提供的宿主内存边界。
+- **Pipe 输出并非字节保真**：E2B 交付的是分别解码后的字符串，而不是原始字节，因此拆分的多字节序列和任意二进制协议可能损坏；不支持 LSP 及其他带帧字节流消费方。
+- **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
+- **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
+- **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
+- **信号归因依靠推断**：如果已经请求终止，而 E2B 报告非零退出码，适配器会报告最后请求的信号，因为 SDK 结果不标识终止信号。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 PTY、Windows、任意模板或网络分区的保真层。
diff --git a/packages/subprocess/subprocess-e2b/package.json b/packages/subprocess/subprocess-e2b/package.json
new file mode 100644
index 0000000000..d73607d1f3
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-subprocess-e2b",
+  "description": "E2B subprocess implementation for DeepSeek Harness",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/subprocess/subprocess-e2b/src/index.ts b/packages/subprocess/subprocess-e2b/src/index.ts
new file mode 100644
index 0000000000..2856df67bd
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/index.ts
@@ -0,0 +1,58 @@
+/**
+ * E2B implementation of the subprocess seam. Each handle starts through the
+ * shared sandbox and retains command output/status paths in that remote world.
+ * @module @deepseek-ai/dsh-subprocess-e2b
+ */
+
+import { randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { Context } from 'cordis'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { E2BSubprocessHandle } from './process.ts'
+
+/** E2B command manager registered as `ctx.subprocess`. */
+export class E2BSubprocessService extends SubprocessService {
+  static inject = ['e2b']
+
+  private readonly live = new Set<E2BSubprocessHandle>()
+
+  /** Create the E2B subprocess service and bind its disposal policy. */
+  constructor(ctx: Context) {
+    super(ctx)
+    ctx.effect(() => async () => {
+      const handles = [...this.live]
+      for (const handle of handles) handle.terminate()
+      await Promise.all(handles.map(async (handle) => {
+        await handle.done.catch(() => {})
+        await handle.waitForExit()
+      }))
+      this.live.clear()
+    }, 'e2b subprocess teardown')
+  }
+
+  /** @inheritdoc */
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('invalid argv: expected a non-empty program name at argv[0]')
+    }
+    if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0) {
+      throw new Error('subprocess-e2b: graceMs must be a positive finite number')
+    }
+    if (spec.signal?.aborted === true) {
+      throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
+    }
+    const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
+    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir)
+    this.live.add(handle)
+    const release = async (): Promise<void> => {
+      await handle.waitForExit()
+      this.live.delete(handle)
+    }
+    void handle.done.then(release, release).catch(() => {})
+    return handle
+  }
+}
+
+export default E2BSubprocessService
diff --git a/packages/subprocess/subprocess-e2b/src/invariant.ts b/packages/subprocess/subprocess-e2b/src/invariant.ts
new file mode 100644
index 0000000000..4416175b1b
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/invariant.ts
@@ -0,0 +1,27 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subprocess-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'subprocess-e2b-invariant'
+/** Service required before reserving package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: live remote handles are private teardown ownership,
+ * and the E2B command event stream is the sole outcome authority.
+ */
+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))
+/* jscpd:ignore-end */
diff --git a/packages/subprocess/subprocess-e2b/src/output.ts b/packages/subprocess/subprocess-e2b/src/output.ts
new file mode 100644
index 0000000000..b6551983a0
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/output.ts
@@ -0,0 +1,70 @@
+/** Bounded host-side projection of a complete output file retained in E2B. */
+
+import { Buffer } from 'node:buffer'
+import type { SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
+
+/** Offset reader used for one collect-mode E2B stream. */
+export class E2BOutputReader implements SubprocessOutputReader {
+  private chunks: Buffer[] = []
+  private retainedBytes = 0
+  private totalBytes = 0
+
+  /**
+   * Create a bounded reader over one remote spill path.
+   * @param maxBytes - In-memory tail cap.
+   * @param maxSpillBytes - Maximum complete remote file size the caller accepts.
+   * @param spillPath - Remote full-output path.
+   */
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxSpillBytes: number | undefined,
+    private readonly spillPath: string,
+  ) {}
+
+  /** Total bytes observed from the SDK stream. */
+  get size(): number {
+    return this.totalBytes
+  }
+
+  /**
+   * Append one decoded SDK output event.
+   * @param text - Event text delivered by E2B.
+   */
+  push(text: string): void {
+    if (text.length === 0) return
+    const chunk = Buffer.from(text)
+    this.totalBytes += chunk.length
+    this.chunks.push(chunk)
+    this.retainedBytes += chunk.length
+    while (this.retainedBytes > this.maxBytes) {
+      const head = this.chunks[0] as Buffer
+      const excess = this.retainedBytes - this.maxBytes
+      if (head.length <= excess) {
+        this.chunks.shift()
+        this.retainedBytes -= head.length
+      } else {
+        this.chunks[0] = head.subarray(excess)
+        this.retainedBytes -= excess
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  readFrom(fromByte: number): SubprocessOutputRead {
+    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
+      throw new Error('subprocess output offset must be a non-negative safe integer')
+    }
+    const retained = Buffer.concat(this.chunks, this.retainedBytes)
+    const firstRetained = this.totalBytes - this.retainedBytes
+    const lossy = fromByte < firstRetained
+    const start = lossy ? 0 : Math.min(retained.length, Math.max(0, fromByte - firstRetained))
+    return {
+      text: retained.subarray(start).toString('utf8'),
+      nextOffset: this.totalBytes,
+      lossy,
+      ...(lossy && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
+        ? { spillPath: this.spillPath }
+        : {}),
+    }
+  }
+}
diff --git a/packages/subprocess/subprocess-e2b/src/process.ts b/packages/subprocess/subprocess-e2b/src/process.ts
new file mode 100644
index 0000000000..507ea700c4
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/process.ts
@@ -0,0 +1,417 @@
+/** One asynchronously-started E2B command projected onto the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { PassThrough, Writable } from 'node:stream'
+import { posix } from 'node:path'
+import {
+  CommandExitError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessCollect,
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessOutputMode,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { E2BOutputReader } from './output.ts'
+
+const GROUP_POLL_MS = 20
+
+function isCollect(mode: SubprocessOutputMode): mode is SubprocessCollect {
+  return mode !== 'pipe' && mode !== 'inherit'
+}
+
+function hasSpill(mode: SubprocessOutputMode): mode is SubprocessCollect & { spill: { maxBytes: number } } {
+  return isCollect(mode) && mode.spill !== undefined
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+class DeferredStdin extends Writable {
+  constructor(private readonly ready: Promise<CommandHandle>) {
+    super({ decodeStrings: false })
+  }
+
+  override _write(chunk: string | Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    void this.ready.then(handle => handle.sendStdin(chunk)).then(
+      () => { callback() },
+      (error: unknown) => { callback(asError(error)) },
+    )
+  }
+
+  override _final(callback: (error?: Error | null) => void): void {
+    void this.ready.then(handle => handle.closeStdin()).then(
+      () => { callback() },
+      (error: unknown) => { callback(asError(error)) },
+    )
+  }
+}
+
+interface RemotePaths {
+  pid: string
+  status: string
+  stdout: string
+  stderr: string
+}
+
+function explicitEnvironmentNames(env: Readonly<Record<string, string>> | undefined): string {
+  return Object.keys(env ?? {})
+    .map(quoteE2BShellArg)
+    .join(' ')
+}
+
+function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
+  const stdoutRedirect = hasSpill(spec.stdio.stdout)
+    ? `> >(tee -a -- ${quoteE2BShellArg(paths.stdout)})`
+    : ''
+  const stderrRedirect = hasSpill(spec.stdio.stderr)
+    ? `2> >(tee -a -- ${quoteE2BShellArg(paths.stderr)} >&2)`
+    : ''
+  const environmentNames = explicitEnvironmentNames(spec.env)
+  const inner = [
+    'set +e',
+    'umask 077',
+    'dsh_e2b_pgid="$(ps -o pgid= -p "$$" | tr -d " ")"',
+    `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
+    'dsh_e2b_env=()',
+    `dsh_e2b_explicit=(${environmentNames})`,
+    'while IFS= read -r dsh_e2b_name; do',
+    '  case "${dsh_e2b_name^^}" in DSH_*|*KEY*|*SECRET*|*TOKEN*) continue ;; esac',
+    '  dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}")',
+    'done < <(compgen -e)',
+    'for dsh_e2b_name in "${dsh_e2b_explicit[@]}"; do dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}"); done',
+    `env -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    'dsh_e2b_status=$?',
+    'wait',
+    `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
+    'exit "$dsh_e2b_status"',
+  ].join('\n')
+  const argv = spec.argv.map(quoteE2BShellArg).join(' ')
+  return `exec setsid --wait -- bash -c ${quoteE2BShellArg(inner)} dsh-e2b ${argv}`
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function isAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true
+}
+
+function waitTick(signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted === true) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve(true)
+    }, GROUP_POLL_MS)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve(false)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** E2B-backed subprocess handle with deferred remote PID acquisition. */
+export class E2BSubprocessHandle implements SubprocessHandle {
+  readonly stdin: Writable | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr: PassThrough | undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+
+  private readonly readyState = Promise.withResolvers<CommandHandle>()
+  private readonly stdoutReader: E2BOutputReader | undefined
+  private readonly stderrReader: E2BOutputReader | undefined
+  private readonly paths: RemotePaths
+  private remotePid = -1
+  private settled = false
+  private terminationRequested = false
+  private terminationSignal: NodeJS.Signals | null = null
+  private termination: Promise<void> | undefined
+
+  /**
+   * Begin an E2B command without blocking the synchronous subprocess spawn seam.
+   * @param runtime - Shared E2B sandbox owner.
+   * @param spec - Fully resolved subprocess request.
+   * @param stateDir - Remote directory retaining process identity, status, and valid spills.
+   */
+  constructor(
+    private readonly runtime: E2BSandboxService,
+    private readonly spec: SubprocessSpawnSpec,
+    readonly stateDir: string,
+  ) {
+    this.paths = {
+      pid: posix.join(stateDir, 'pid'),
+      status: posix.join(stateDir, 'exit-code'),
+      stdout: posix.join(stateDir, 'stdout.log'),
+      stderr: posix.join(stateDir, 'stderr.log'),
+    }
+    const outMode = spec.stdio.stdout
+    const errMode = spec.stdio.stderr
+    this.stdout = outMode === 'pipe' ? new PassThrough() : undefined
+    this.stderr = errMode === 'pipe' ? new PassThrough() : undefined
+    this.stdoutReader = isCollect(outMode)
+      ? new E2BOutputReader(outMode.maxBytes, outMode.spill?.maxBytes, this.paths.stdout)
+      : undefined
+    this.stderrReader = isCollect(errMode)
+      ? new E2BOutputReader(errMode.maxBytes, errMode.spill?.maxBytes, this.paths.stderr)
+      : undefined
+    this.collected = {
+      ...(this.stdoutReader !== undefined ? { stdout: this.stdoutReader } : {}),
+      ...(this.stderrReader !== undefined ? { stderr: this.stderrReader } : {}),
+    }
+    this.stdin = spec.stdio.stdin === 'pipe' ? new DeferredStdin(this.readyState.promise) : undefined
+    void this.readyState.promise.catch(() => {})
+    spec.signal?.addEventListener('abort', this.onAbort, { once: true })
+    this.done = this.run()
+    void this.done.catch(() => {})
+    if (spec.signal?.aborted === true) this.terminate()
+  }
+
+  /** Remote process id after start; `-1` while E2B startup is pending or after it fails. */
+  get pid(): number {
+    return this.remotePid
+  }
+
+  /** @inheritdoc */
+  terminate(): void {
+    if (this.terminationRequested || this.settled) return
+    this.terminationRequested = true
+    this.termination = this.terminateRemote()
+    void this.termination.catch(() => {})
+  }
+
+  /** @inheritdoc */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    let handle: CommandHandle | undefined
+    try {
+      handle = await this.readyForWait(signal)
+    } catch {
+      return true
+    }
+    if (handle === undefined) return false
+    let sandbox: Sandbox
+    try {
+      sandbox = await this.runtime.getSandbox()
+    } catch (error: unknown) {
+      if (isAborted(signal)) return false
+      throw error
+    }
+    while (await this.groupAlive(sandbox, this.remotePid, signal)) {
+      if (!await waitTick(signal)) return false
+    }
+    return !isAborted(signal)
+  }
+
+  private readyForWait(signal: AbortSignal | undefined): Promise<CommandHandle | undefined> {
+    if (signal === undefined) return this.readyState.promise
+    return new Promise<CommandHandle | undefined>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(undefined) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      if (signal.aborted) {
+        onAbort()
+        return
+      }
+      void this.readyState.promise.then(
+        (handle) => { cleanup(); resolve(handle) },
+        (error: unknown) => { cleanup(); reject(asError(error)) },
+      )
+    })
+  }
+
+  private readonly onAbort = (): void => { this.terminate() }
+
+  private async run(): Promise<SubprocessOutcome> {
+    try {
+      const sandbox = await this.runtime.getSandbox()
+      await this.prepareState(sandbox)
+      const handle = await sandbox.commands.run(
+        commandText(this.spec, this.paths),
+        {
+          background: true,
+          cwd: this.spec.cwd,
+          stdin: this.spec.stdio.stdin !== 'ignore',
+          timeoutMs: 0,
+          ...(this.spec.env !== undefined ? { envs: this.spec.env } : {}),
+          onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
+          onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
+        },
+      )
+      if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+        throw new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
+      }
+      const completion = handle.wait()
+      void completion.catch(() => {})
+      this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      this.readyState.resolve(handle)
+      await this.writeBatchStdin(handle)
+      const outcome = await this.waitForCommand(completion)
+      await this.finalizeSpills(sandbox)
+      return outcome
+    } catch (error: unknown) {
+      this.readyState.reject(error)
+      throw error
+    } finally {
+      this.settled = true
+      this.spec.signal?.removeEventListener('abort', this.onAbort)
+      this.stdout?.end()
+      this.stderr?.end()
+    }
+  }
+
+  private async prepareState(sandbox: Sandbox): Promise<void> {
+    await sandbox.files.makeDir(this.stateDir)
+    const files = [
+      { path: this.paths.pid, data: '' },
+      { path: this.paths.status, data: '' },
+      ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
+      ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
+    ]
+    await sandbox.files.write(files)
+    await sandbox.commands.run([
+      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
+      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
+    ].join('\n'))
+  }
+
+  private async writeBatchStdin(handle: CommandHandle): Promise<void> {
+    if (typeof this.spec.stdio.stdin !== 'object') return
+    try {
+      await handle.sendStdin(this.spec.stdio.stdin.data)
+      await handle.closeStdin()
+    } catch (_processClosedItsInput) {
+      // Like the local adapter, batch stdin is best-effort; exit and output remain authoritative.
+    }
+  }
+
+  private async dispatchOutput(stream: 'stdout' | 'stderr', data: string): Promise<void> {
+    try {
+      if (stream === 'stdout') {
+        this.stdoutReader?.push(data)
+        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, data)
+        return
+      }
+      this.stderrReader?.push(data)
+      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, data)
+    } catch (error: unknown) {
+      const target = stream === 'stdout' ? this.stdout : this.stderr
+      target?.destroy(asError(error))
+    }
+  }
+
+  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: string): Promise<void> {
+    const target = pipe ?? inherited
+    if (target === undefined || data.length === 0) return
+    if (target.destroyed) throw new Error('subprocess output stream is closed')
+    if (target.write(Buffer.from(data))) return
+    await new Promise<void>((resolve, reject) => {
+      const onDrain = (): void => { cleanup(); resolve() }
+      const onError = (error: Error): void => { cleanup(); reject(error) }
+      const cleanup = (): void => {
+        target.removeListener('drain', onDrain)
+        target.removeListener('error', onError)
+      }
+      target.once('drain', onDrain)
+      target.once('error', onError)
+    })
+  }
+
+  private async waitForProcessGroupId(sandbox: Sandbox, completion: Promise<CommandResult>): Promise<number> {
+    const commandSettled = completion.then(
+      () => true,
+      () => true,
+    )
+    while (true) {
+      const raw = await sandbox.files.read(this.paths.pid)
+      const value = raw.trim()
+      if (value.length > 0) {
+        const pid = Number(value)
+        if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(pid)) {
+          throw new Error(`subprocess-e2b: remote wrapper published invalid process-group id ${JSON.stringify(value)}`)
+        }
+        return pid
+      }
+      const settled = await Promise.race([commandSettled, waitTick().then(() => false)])
+      if (settled) throw new Error('subprocess-e2b: remote command exited before publishing its process-group id')
+    }
+  }
+
+  private async waitForCommand(completion: Promise<CommandResult>): Promise<SubprocessOutcome> {
+    try {
+      const result = await completion
+      return { exitCode: result.exitCode, signal: null }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) {
+        return this.terminationSignal === null
+          ? { exitCode: error.exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
+      }
+      throw error
+    }
+  }
+
+  private async terminateRemote(): Promise<void> {
+    let handle: CommandHandle
+    try {
+      handle = await this.readyState.promise
+    } catch {
+      return
+    }
+    const sandbox = await this.runtime.getSandbox()
+    this.terminationSignal = 'SIGTERM'
+    await this.signalGroup(sandbox, this.remotePid, 'TERM')
+    const deadline = Date.now() + this.spec.graceMs
+    while (Date.now() < deadline && await this.groupAlive(sandbox, this.remotePid)) {
+      await waitTick()
+    }
+    if (!await this.groupAlive(sandbox, this.remotePid)) return
+    this.terminationSignal = 'SIGKILL'
+    try {
+      await this.signalGroup(sandbox, this.remotePid, 'KILL')
+    } finally {
+      await handle.kill().catch(() => false)
+    }
+  }
+
+  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<void> {
+    try {
+      await sandbox.commands.run(`kill -${signal} -- -${pid}`)
+    } catch (error: unknown) {
+      if (!(error instanceof CommandExitError)) throw error
+    }
+  }
+
+  private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
+    try {
+      await sandbox.commands.run(`kill -0 -- -${pid}`, signalOpts(signal))
+      return true
+    } catch (error: unknown) {
+      if (signal?.aborted === true) return false
+      if (error instanceof CommandExitError) return false
+      throw error
+    }
+  }
+
+  private async finalizeSpills(sandbox: Sandbox): Promise<void> {
+    const removals: Promise<void>[] = []
+    const collect = (mode: SubprocessOutputMode, reader: E2BOutputReader | undefined, path: string): void => {
+      if (!hasSpill(mode)) return
+      // A spill mode is a collect mode, so construction always created its reader.
+      const size = (reader as E2BOutputReader).size
+      if (size <= mode.maxBytes || size > mode.spill.maxBytes) {
+        removals.push(sandbox.files.remove(path).catch(() => {}))
+      }
+    }
+    collect(this.spec.stdio.stdout, this.stdoutReader, this.paths.stdout)
+    collect(this.spec.stdio.stderr, this.stderrReader, this.paths.stderr)
+    await Promise.all(removals)
+  }
+}
diff --git a/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts b/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
new file mode 100644
index 0000000000..ff9d48073c
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
@@ -0,0 +1,725 @@
+import { once } from 'node:events'
+import { Context } from 'cordis'
+import {
+  CommandExitError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import * as E2BSubprocessInvariant from '../src/invariant.ts'
+import { E2BOutputReader } from '../src/output.ts'
+import { E2BSubprocessHandle } from '../src/process.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { describe, expect, it, vi } from 'vitest'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+interface StartOptions {
+  background: true
+  cwd: string
+  stdin: boolean
+  timeoutMs: number
+  signal?: AbortSignal
+  envs?: Record<string, string>
+  onStdout?: (data: string) => void | Promise<void>
+  onStderr?: (data: string) => void | Promise<void>
+}
+
+class FakeCommandHandle {
+  pid = 4242
+  readonly sent: Array<string | Uint8Array> = []
+  closes = 0
+  kills = 0
+  killError: unknown
+  private readonly result = Promise.withResolvers<CommandResult>()
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    return this.result.promise
+  }
+
+  async sendStdin(data: string | Uint8Array): Promise<void> {
+    this.sent.push(data)
+  }
+
+  async closeStdin(): Promise<void> {
+    this.closes += 1
+  }
+
+  async kill(): Promise<boolean> {
+    this.kills += 1
+    if (this.killError !== undefined) throw this.killError
+    return true
+  }
+
+  succeed(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  fail(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+}
+
+class FakeSandbox {
+  readonly handle = new FakeCommandHandle()
+  readonly commandsSeen: string[] = []
+  readonly writtenFiles: string[][] = []
+  readonly removed: string[] = []
+  readonly directories: string[] = []
+  startOptions: StartOptions | undefined
+  backgroundError: unknown
+  nextRemoveError: unknown
+  probeError: unknown
+  signalError: unknown
+  trapsTerm = false
+  alive = true
+  processGroupId = '4242\n'
+  readonly processGroupReads: string[] = []
+  beforeProbe: (() => void) | undefined
+  afterProbe: (() => void) | undefined
+  private startGate: Promise<void> | undefined
+  private openStart: (() => void) | undefined
+
+  deferStart(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.startGate = gate.promise
+    this.openStart = () => { gate.resolve(undefined) }
+  }
+
+  releaseStart(): void {
+    this.openStart?.()
+  }
+
+  finish(exitCode = 0): void {
+    this.alive = false
+    if (exitCode === 0) this.handle.succeed(0)
+    else this.handle.fail(exitCode)
+  }
+
+  async stdout(data: string): Promise<void> {
+    await this.startOptions?.onStdout?.(data)
+  }
+
+  async stderr(data: string): Promise<void> {
+    await this.startOptions?.onStderr?.(data)
+  }
+
+  readonly sandbox = {
+    sandboxId: 'fake',
+    files: {
+      makeDir: async (path: string): Promise<boolean> => {
+        this.directories.push(path)
+        return true
+      },
+      write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
+        this.writtenFiles.push(files.map(file => file.path))
+        return files.map(() => ({}))
+      },
+      read: async (): Promise<string> => this.processGroupReads.shift() ?? this.processGroupId,
+      remove: async (path: string): Promise<void> => {
+        this.removed.push(path)
+        if (this.nextRemoveError !== undefined) {
+          const error = this.nextRemoveError
+          this.nextRemoveError = undefined
+          throw error
+        }
+      },
+    },
+    commands: {
+      run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
+        this.commandsSeen.push(command)
+        if (command.startsWith('kill -0 ')) {
+          this.beforeProbe?.()
+          if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
+          if (this.probeError !== undefined) {
+            const error = this.probeError
+            this.probeError = undefined
+            throw error
+          }
+          if (!this.alive) throw commandError(1)
+          this.afterProbe?.()
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }
+        if (command.startsWith('kill -TERM ')) {
+          if (this.signalError !== undefined) {
+            const error = this.signalError
+            this.signalError = undefined
+            throw error
+          }
+          if (!this.trapsTerm) {
+            this.alive = false
+            this.handle.fail(143)
+          }
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }
+        if (command.startsWith('kill -KILL ')) {
+          if (this.signalError !== undefined) {
+            const error = this.signalError
+            this.signalError = undefined
+            throw error
+          }
+          this.alive = false
+          this.handle.fail(137)
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }
+        if ((options as StartOptions | undefined)?.background === true) {
+          this.startOptions = options as StartOptions
+          await this.startGate
+          if (this.backgroundError !== undefined) throw this.backgroundError
+          return this.handle as unknown as CommandHandle
+        }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function spec(overrides: Partial<SubprocessSpawnSpec> = {}): SubprocessSpawnSpec {
+  return {
+    argv: ['bash', '-c', 'printf ok'],
+    cwd: '/workspace',
+    stdio: {
+      stdin: 'ignore',
+      stdout: { maxBytes: 4, spill: { maxBytes: 16 } },
+      stderr: { maxBytes: 4 },
+    },
+    graceMs: 5,
+    ...overrides,
+  }
+}
+
+function runtime(fake: FakeSandbox, getSandbox: () => Promise<Sandbox> = async () => fake.sandbox): E2BSandboxService {
+  return {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    disposeMode: 'kill',
+    getSandbox,
+  } as unknown as E2BSandboxService
+}
+
+async function flush(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+describe('E2BOutputReader', () => {
+  it('keeps a byte-exact tail with independent whole-stream cursors', () => {
+    const reader = new E2BOutputReader(4, 10, '/remote/spill')
+    reader.push('')
+    reader.push('ab')
+    reader.push('cdef')
+    expect(reader.size).toBe(6)
+    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true, spillPath: '/remote/spill' })
+    expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
+  })
+
+  it('drops whole head chunks and withholds absent or over-cap spills', () => {
+    const withoutSpill = new E2BOutputReader(2, undefined, '/unused')
+    withoutSpill.push('ab')
+    withoutSpill.push('cd')
+    expect(withoutSpill.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
+    const overCap = new E2BOutputReader(2, 3, '/too-small')
+    overCap.push('abcd')
+    expect(overCap.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
+    expect(() => overCap.readFrom(-1)).toThrow(/non-negative safe integer/)
+    expect(() => overCap.readFrom(1.5)).toThrow(/non-negative safe integer/)
+  })
+})
+
+describe('E2BSubprocessHandle', () => {
+  it('starts asynchronously, keeps secrets out of the command, and supports deferred piped stdin/output', async () => {
+    const fake = new FakeSandbox()
+    fake.processGroupId = '4343\n'
+    fake.deferStart()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      argv: ['tool', 'argument with spaces'],
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
+      env: { PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
+    }), '/workspace/.dsh-e2b/processes/one')
+    expect(handle.pid).toBe(-1)
+    handle.stdin!.write('hello')
+    handle.stdin!.end()
+    fake.releaseStart()
+    await flush()
+    expect(handle.pid).toBe(4343)
+    expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
+    expect(fake.handle.closes).toBe(1)
+    expect(fake.startOptions?.envs).toEqual({ PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' })
+    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
+    expect(command).toContain('exec setsid --wait -- bash -c')
+    expect(command).toContain('DEEPSEEK_API_KEY')
+    expect(command).toContain('DSH_MODE')
+    expect(command).not.toContain('explicit-secret')
+    expect(fake.writtenFiles[0]).toEqual([
+      '/workspace/.dsh-e2b/processes/one/pid',
+      '/workspace/.dsh-e2b/processes/one/exit-code',
+      '/workspace/.dsh-e2b/processes/one/stderr.log',
+    ])
+
+    let piped = ''
+    handle.stdout!.on('data', (chunk) => { piped += String(chunk) })
+    await fake.stdout('pipe-data')
+    await fake.stderr('err')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(piped).toBe('pipe-data')
+    expect(handle.collected.stderr!.readFrom(0)).toMatchObject({ text: 'err', lossy: false })
+    expect(fake.removed).toContain('/workspace/.dsh-e2b/processes/one/stderr.log')
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
+    const writeFake = new FakeSandbox()
+    writeFake.deferStart()
+    vi.spyOn(writeFake.handle, 'sendStdin').mockRejectedValueOnce('stdin rejected')
+    const writeHandle = new E2BSubprocessHandle(runtime(writeFake), spec({
+      stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
+    }), '/runtime/stdin-write-error')
+    const writeError = once(writeHandle.stdin!, 'error')
+    writeHandle.stdin!.write('input')
+    writeFake.releaseStart()
+    await expect(writeError).resolves.toMatchObject([{ message: 'stdin rejected' }])
+    writeFake.finish()
+    await writeHandle.done
+
+    const closeFake = new FakeSandbox()
+    vi.spyOn(closeFake.handle, 'closeStdin').mockRejectedValueOnce(new Error('close rejected'))
+    const closeHandle = new E2BSubprocessHandle(runtime(closeFake), spec({
+      stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
+    }), '/runtime/stdin-close-error')
+    await flush()
+    const closeError = once(closeHandle.stdin!, 'error')
+    closeHandle.stdin!.end()
+    await expect(closeError).resolves.toMatchObject([{ message: 'close rejected' }])
+    closeFake.finish()
+    await closeHandle.done
+  })
+
+  it('collects bounded tails, retains valid spills, and maps natural nonzero exits', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: {
+        stdin: { data: 'batch' },
+        stdout: { maxBytes: 4, spill: { maxBytes: 16 } },
+        stderr: { maxBytes: 3 },
+      },
+    }), '/runtime/two')
+    await flush()
+    await fake.stdout('abcdef')
+    await fake.stderr('12345')
+    fake.finish(7)
+    await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null })
+    expect(fake.handle.sent).toEqual(['batch'])
+    expect(fake.handle.closes).toBe(1)
+    expect(handle.collected.stdout!.readFrom(0)).toEqual({
+      text: 'cdef',
+      nextOffset: 6,
+      lossy: true,
+      spillPath: '/runtime/two/stdout.log',
+    })
+    expect(handle.collected.stderr!.readFrom(0)).toEqual({ text: '345', nextOffset: 5, lossy: true })
+    expect(fake.removed).not.toContain('/runtime/two/stdout.log')
+  })
+
+  it('removes a spill once the complete stream exceeds its cap', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: { maxBytes: 2, spill: { maxBytes: 3 } }, stderr: 'inherit' },
+    }), '/runtime/oversize')
+    await flush()
+    await fake.stdout('abcd')
+    await fake.stderr('')
+    fake.finish()
+    await handle.done
+    expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
+    expect(fake.removed).toContain('/runtime/oversize/stdout.log')
+  })
+
+  it('contains remote spill-removal failures and routes empty inherited output', async () => {
+    const fake = new FakeSandbox()
+    fake.nextRemoveError = new Error('already removed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4, spill: { maxBytes: 8 } } },
+    }), '/runtime/remove-error')
+    await flush()
+    await fake.stdout('')
+    await fake.stderr('')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.removed).toContain('/runtime/remove-error/stderr.log')
+  })
+
+  it('terminates a process group with TERM and reports the signal outcome', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/term')
+    await flush()
+    handle.terminate()
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
+    expect(fake.commandsSeen).not.toContain('kill -KILL -- -4242')
+  })
+
+  it('escalates a TERM-trapping process group to KILL and uses the SDK kill as fallback', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.handle.killError = new Error('already gone')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/kill')
+    await flush()
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain('kill -KILL -- -4242')
+    expect(fake.handle.kills).toBe(1)
+  })
+
+  it('honors termination requested before asynchronous startup finishes', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/deferred-kill')
+    handle.terminate()
+    fake.releaseStart()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('reacts to a signal that aborts after the remote command has started', async () => {
+    const fake = new FakeSandbox()
+    const controller = new AbortController()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: controller.signal }), '/runtime/live-abort')
+    await flush()
+    controller.abort('stop')
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('bounds waitForExit while startup or a live group is pending', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/wait')
+    const beforeStart = new AbortController()
+    const pending = handle.waitForExit(beforeStart.signal)
+    beforeStart.abort()
+    await expect(pending).resolves.toBe(false)
+    await expect(handle.waitForExit(AbortSignal.abort())).resolves.toBe(false)
+    fake.releaseStart()
+    await flush()
+    const live = new AbortController()
+    const liveWait = handle.waitForExit(live.signal)
+    live.abort()
+    await expect(liveWait).resolves.toBe(false)
+    fake.finish()
+    await handle.done
+  })
+
+  it('bounds both sides of the liveness-poll abort race', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-abort')
+    await flush()
+
+    const beforeTick = new AbortController()
+    fake.afterProbe = () => { beforeTick.abort(); fake.afterProbe = undefined }
+    await expect(handle.waitForExit(beforeTick.signal)).resolves.toBe(false)
+
+    const duringTick = new AbortController()
+    fake.afterProbe = () => {
+      fake.afterProbe = undefined
+      setTimeout(() => { duringTick.abort() }, 0)
+    }
+    await expect(handle.waitForExit(duringTick.signal)).resolves.toBe(false)
+
+    const duringProbe = new AbortController()
+    fake.beforeProbe = () => { duringProbe.abort(); fake.beforeProbe = undefined }
+    await expect(handle.waitForExit(duringProbe.signal)).resolves.toBe(false)
+    fake.finish()
+    await handle.done
+  })
+
+  it('observes a live group across one successful bounded poll', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-success')
+    await flush()
+    setTimeout(() => { fake.finish() }, 1)
+    await expect(handle.waitForExit(new AbortController().signal)).resolves.toBe(true)
+    await handle.done
+  })
+
+  it('treats startup failure as no live tree and contains readiness rejection', async () => {
+    const fake = new FakeSandbox()
+    fake.backgroundError = new Error('start failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail')
+    await expect(handle.done).rejects.toThrow('start failed')
+    expect(handle.pid).toBe(-1)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    handle.terminate()
+  })
+
+  it('bounds a readiness rejection with a still-live caller signal', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    fake.backgroundError = new Error('start failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail-with-signal')
+    const waiting = handle.waitForExit(new AbortController().signal)
+    fake.releaseStart()
+    await expect(handle.done).rejects.toThrow('start failed')
+    await expect(waiting).resolves.toBe(true)
+  })
+
+  it('propagates an unavailable sandbox unless the caller aborts the wait', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const unavailable = runtime(fake, async () => {
+      calls += 1
+      if (calls === 1) return fake.sandbox
+      throw new Error('connection unavailable')
+    })
+    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/unavailable')
+    await flush()
+    await expect(handle.waitForExit()).rejects.toThrow('connection unavailable')
+    fake.finish()
+    await handle.done
+  })
+
+  it('returns false when the caller aborts while reconnecting for liveness', async () => {
+    const fake = new FakeSandbox()
+    const reconnect = Promise.withResolvers<Sandbox>()
+    let calls = 0
+    const unavailable = runtime(fake, async () => {
+      calls += 1
+      return calls === 1 ? fake.sandbox : await reconnect.promise
+    })
+    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/reconnect-abort')
+    await flush()
+    const controller = new AbortController()
+    const waiting = handle.waitForExit(controller.signal)
+    await flush()
+    controller.abort()
+    reconnect.reject(new Error('connection unavailable'))
+    await expect(waiting).resolves.toBe(false)
+    fake.finish()
+    await handle.done
+  })
+
+  it('returns false when a liveness request itself is aborted and surfaces other probe failures', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/probe')
+    await flush()
+    const controller = new AbortController()
+    controller.abort()
+    await expect(handle.waitForExit(controller.signal)).resolves.toBe(false)
+    fake.probeError = new Error('probe failed')
+    await expect(handle.waitForExit()).rejects.toThrow('probe failed')
+    fake.finish()
+    await handle.done
+  })
+
+  it('makes batch stdin close failures best-effort', async () => {
+    const fake = new FakeSandbox()
+    vi.spyOn(fake.handle, 'sendStdin').mockRejectedValueOnce(new Error('closed'))
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: { data: 'ignored' }, stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
+    }), '/runtime/stdin-closed')
+    await flush()
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('rejects malformed SDK process ids and non-command settlement failures', async () => {
+    const invalidPid = new FakeSandbox()
+    invalidPid.handle.pid = 0
+    const invalid = new E2BSubprocessHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
+    await expect(invalid.done).rejects.toThrow(/invalid command pid 0/)
+    await expect(invalid.waitForExit()).resolves.toBe(true)
+
+    const crashedFake = new FakeSandbox()
+    const crashed = new E2BSubprocessHandle(runtime(crashedFake), spec(), '/runtime/crashed')
+    await flush()
+    crashedFake.alive = false
+    crashedFake.handle.crash(new Error('command transport failed'))
+    await expect(crashed.done).rejects.toThrow('command transport failed')
+  })
+
+  it('rejects invalid or absent process-group publication', async () => {
+    const invalidGroup = new FakeSandbox()
+    invalidGroup.processGroupId = 'not-a-pid\n'
+    const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
+    await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
+
+    const absentGroup = new FakeSandbox()
+    absentGroup.processGroupId = ''
+    const absent = new E2BSubprocessHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
+    await flush()
+    absentGroup.finish()
+    await expect(absent.done).rejects.toThrow(/exited before publishing/)
+  })
+
+  it('waits for delayed process-group publication', async () => {
+    const fake = new FakeSandbox()
+    fake.processGroupReads.push('', '4242\n')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/delayed-group')
+    await vi.waitFor(() => { expect(handle.pid).toBe(4242) })
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('handles output backpressure and contains a stderr sink failure', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
+    }), '/runtime/backpressure')
+    await flush()
+
+    handle.stdout!.on('error', () => {})
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockReturnValueOnce(false)
+    const stdoutPending = fake.stdout('blocked')
+    queueMicrotask(() => { handle.stdout!.emit('drain') })
+    await stdoutPending
+    stdoutWrite.mockRestore()
+
+    handle.stderr!.on('error', () => {})
+    const stderrWrite = vi.spyOn(handle.stderr!, 'write').mockReturnValueOnce(false)
+    const stderrPending = fake.stderr('broken')
+    queueMicrotask(() => { handle.stderr!.emit('error', new Error('sink failed')) })
+    await stderrPending
+    stderrWrite.mockRestore()
+
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('contains a pipe callback failure instead of rejecting command settlement', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/pipe-error')
+    await flush()
+    const emitted = once(handle.stdout!, 'error')
+    handle.stdout!.destroy(new Error('consumer failed'))
+    await emitted
+    await fake.stdout('late output')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('contains an already-gone group signal and observes non-command signal failures', async () => {
+    const gone = new FakeSandbox()
+    gone.trapsTerm = true
+    gone.signalError = commandError(1)
+    const goneHandle = new E2BSubprocessHandle(runtime(gone), spec({ graceMs: 1 }), '/runtime/gone-signal')
+    await flush()
+    goneHandle.terminate()
+    await expect(goneHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+
+    const failed = new FakeSandbox()
+    failed.signalError = new Error('signal transport failed')
+    const failedHandle = new E2BSubprocessHandle(runtime(failed), spec(), '/runtime/failed-signal')
+    await flush()
+    failedHandle.terminate()
+    await flush()
+    failed.finish()
+    await expect(failedHandle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+})
+
+describe('E2BSubprocessService', () => {
+  async function service(
+    fake = new FakeSandbox(),
+    providedRuntime: E2BSandboxService = runtime(fake),
+  ): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>> }> {
+    const ctx = new Context()
+    ctx.provide('e2b', providedRuntime)
+    const fiber = await ctx.plugin(E2BSubprocessService)
+    return { ctx, fiber }
+  }
+
+  it('registers handles and disposal terminates and joins live remote groups regardless of sandbox policy', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec({ graceMs: 1 }))
+    await flush()
+    await fiber.dispose()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(fake.alive).toBe(false)
+  })
+
+  it('releases naturally settled handles before later service disposal', async () => {
+    const fake = new FakeSandbox()
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec())
+    await flush()
+    fake.finish()
+    await handle.done
+    await flush()
+    const signalsBefore = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    await fiber.dispose()
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -')).length).toBe(signalsBefore)
+  })
+
+  it('contains a release liveness failure and retries quiescence during disposal', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const reconnecting = runtime(fake, async () => {
+      calls += 1
+      if (calls === 2) throw new Error('transient liveness failure')
+      return fake.sandbox
+    })
+    const { ctx, fiber } = await service(fake, reconnecting)
+    const handle = ctx.subprocess.spawn(spec())
+    await flush()
+    fake.finish()
+    await handle.done
+    await flush()
+    await fiber.dispose()
+    expect(calls).toBeGreaterThanOrEqual(3)
+  })
+
+  it('contains spawn rejection while disposal is joining the pending handle', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    fake.backgroundError = new Error('start failed during disposal')
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec())
+    const disposing = fiber.dispose()
+    fake.releaseStart()
+    await expect(disposing).resolves.toBeUndefined()
+    await expect(handle.done).rejects.toThrow('start failed during disposal')
+  })
+
+  it('validates synchronous spawn preconditions', async () => {
+    const { ctx } = await service()
+    expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/)
+    expect(() => ctx.subprocess.spawn(spec({ graceMs: 0 }))).toThrow(/positive finite/)
+    expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/)
+    expect(() => ctx.subprocess.spawn(spec({ signal: { aborted: true, reason: undefined } as AbortSignal }))).toThrow(/aborted$/)
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BSubprocessInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/subprocess/subprocess-e2b/tsconfig.json b/packages/subprocess/subprocess-e2b/tsconfig.json
new file mode 100644
index 0000000000..f3bb8c2a26
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../e2b/e2b"
+    },
+    {
+      "path": "../subprocess"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 256ae90caa..b17cc5b4f8 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -301,6 +301,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   PermissionSelect: 'permissions projection payload is owned by packages/ui/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
   ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
+  Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 3ca0317cf4..90aa22e322 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -50,6 +50,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
+  'packages/e2b/e2b': { kind: 'none', reason: 'The shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.' },
   'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers no model surface.' },
   'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers no model surface.' },
@@ -82,6 +83,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
   'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
+  'packages/fs/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
@@ -98,6 +100,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
+  'packages/subprocess/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index de9b63459c..8380182e83 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -188,6 +188,7 @@
         "./packages/bash/*/src",
         "./packages/pty/*/src",
         "./packages/subprocess/*/src",
+        "./packages/e2b/*/src",
         "./packages/code-runtime/*/src",
         "./packages/fs/*/src",
         "./packages/lsp/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1a8ef6508a..03b1bcd2dd 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -162,6 +162,8 @@
     { "path": "./packages/examples/agent-spine-demo" },
     { "path": "./packages/subprocess/subprocess" },
     { "path": "./packages/subprocess/subprocess-local" },
+    { "path": "./packages/e2b/e2b" },
+    { "path": "./packages/subprocess/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
     { "path": "./packages/pty/pty-local" },
@@ -183,6 +185,7 @@
     { "path": "./packages/bash/tool-bash" },
     { "path": "./packages/fs/fs" },
     { "path": "./packages/fs/fs-local" },
+    { "path": "./packages/fs/fs-e2b" },
     { "path": "./packages/fs/fs-policy" },
     { "path": "./packages/fs/fs-sandbox" },
     { "path": "./packages/fs/tool-fs" },

From 6667102890ce0cf50f6122ecb676a4deccd60499 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:59:47 +0800
Subject: [PATCH 100/262] Add E2B PTY, LSP, and code runtime providers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |  11 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  11 +-
 ...active-semantic-code-runtime-poc.i18n.yaml |   6 +
 ...b-interactive-semantic-code-runtime-poc.md |  57 ++
 ...nteractive-semantic-code-runtime-poc.zh.md |  57 ++
 docs/cordis-catalog/services.md               |   4 +-
 examples/headless-agent/e2b.cordis.yml        |  34 +-
 .../tests/fixtures/e2b/e2b/bin.ts             | 143 +++++
 .../tests/fixtures/e2b/e2b/cordis.yml         |  40 ++
 .../tests/fixtures/e2b/e2b/fixture-lsp.mjs    |  85 +++
 examples/package.json                         |   5 +
 packages/code-runtime/README.i18n.yaml        |   4 +-
 packages/code-runtime/README.md               |   9 +-
 packages/code-runtime/README.zh.md            |  13 +-
 .../code-runtime-e2b/README.i18n.yaml         |   6 +
 .../code-runtime/code-runtime-e2b/README.md   |  44 ++
 .../code-runtime-e2b/README.zh.md             |  44 ++
 .../code-runtime-e2b/package.json             |  52 ++
 .../code-runtime-e2b/src/index.ts             | 441 +++++++++++++++
 .../code-runtime-e2b/src/invariant.ts         |  20 +
 .../code-runtime-e2b/src/runner-source.ts     | 460 ++++++++++++++++
 .../code-runtime-e2b/tests/runtime.spec.ts    | 460 ++++++++++++++++
 .../code-runtime-e2b/tsconfig.json            |  20 +
 .../code-runtime-worker/README.i18n.yaml      |   4 +-
 .../code-runtime-worker/README.md             |   6 +-
 .../code-runtime-worker/README.zh.md          |  26 +-
 .../code-runtime-worker/src/index.ts          |  35 +-
 .../code-runtime/README.i18n.yaml             |   4 +-
 packages/code-runtime/code-runtime/README.md  |   2 +-
 .../code-runtime/code-runtime/README.zh.md    |  20 +-
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |   7 +-
 packages/e2b/README.zh.md                     |   7 +-
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/frame.ts                 |  75 +++
 packages/e2b/e2b/src/index.ts                 |  24 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  42 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  46 ++
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |   5 +-
 packages/lsp/README.zh.md                     |   5 +-
 packages/lsp/lsp-e2b/README.i18n.yaml         |   6 +
 packages/lsp/lsp-e2b/README.md                |  47 ++
 packages/lsp/lsp-e2b/README.zh.md             |  47 ++
 packages/lsp/lsp-e2b/package.json             |  52 ++
 packages/lsp/lsp-e2b/src/index.ts             | 358 ++++++++++++
 packages/lsp/lsp-e2b/src/invariant.ts         |  20 +
 packages/lsp/lsp-e2b/src/proxy-source.ts      |  55 ++
 packages/lsp/lsp-e2b/src/transport.ts         | 183 +++++++
 packages/lsp/lsp-e2b/tests/provider.spec.ts   | 397 ++++++++++++++
 packages/lsp/lsp-e2b/tests/transport.spec.ts  | 181 +++++++
 packages/lsp/lsp-e2b/tsconfig.json            |  20 +
 packages/lsp/lsp-local/src/instance.ts        |  22 +-
 .../lsp/lsp-local/tests/fixture-server.ts     |   6 +
 packages/lsp/lsp-local/tests/instance.spec.ts |   5 +
 packages/lsp/lsp/README.i18n.yaml             |   4 +-
 packages/lsp/lsp/README.md                    |   1 +
 packages/lsp/lsp/README.zh.md                 |   1 +
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |   5 +-
 packages/pty/README.zh.md                     |   5 +-
 packages/pty/pty-e2b/README.i18n.yaml         |   6 +
 packages/pty/pty-e2b/README.md                |  54 ++
 packages/pty/pty-e2b/README.zh.md             |  54 ++
 packages/pty/pty-e2b/package.json             |  46 ++
 packages/pty/pty-e2b/src/config.ts            |  64 +++
 packages/pty/pty-e2b/src/index.ts             |  93 ++++
 packages/pty/pty-e2b/src/invariant.ts         |  20 +
 packages/pty/pty-e2b/src/session.ts           | 367 +++++++++++++
 packages/pty/pty-e2b/tests/index.spec.ts      | 195 +++++++
 packages/pty/pty-e2b/tests/session.spec.ts    | 398 ++++++++++++++
 packages/pty/pty-e2b/tsconfig.json            |  16 +
 packages/pty/pty-local/src/sanitize.ts        | 188 -------
 packages/pty/pty-local/src/session.ts         | 511 ++++++------------
 packages/pty/pty-local/tests/sanitize.spec.ts |  34 +-
 packages/pty/pty/src/index.ts                 |   9 +
 packages/pty/pty/src/terminal.ts              | 273 ++++++++++
 .../verify-package-readme-model-experience.ts |   2 +
 tsconfig.host.json                            |   3 +
 82 files changed, 5462 insertions(+), 644 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
 create mode 100644 examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs
 create mode 100644 packages/code-runtime/code-runtime-e2b/README.i18n.yaml
 create mode 100644 packages/code-runtime/code-runtime-e2b/README.md
 create mode 100644 packages/code-runtime/code-runtime-e2b/README.zh.md
 create mode 100644 packages/code-runtime/code-runtime-e2b/package.json
 create mode 100644 packages/code-runtime/code-runtime-e2b/src/index.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/src/invariant.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/src/runner-source.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/tsconfig.json
 create mode 100644 packages/e2b/e2b/src/frame.ts
 create mode 100644 packages/lsp/lsp-e2b/README.i18n.yaml
 create mode 100644 packages/lsp/lsp-e2b/README.md
 create mode 100644 packages/lsp/lsp-e2b/README.zh.md
 create mode 100644 packages/lsp/lsp-e2b/package.json
 create mode 100644 packages/lsp/lsp-e2b/src/index.ts
 create mode 100644 packages/lsp/lsp-e2b/src/invariant.ts
 create mode 100644 packages/lsp/lsp-e2b/src/proxy-source.ts
 create mode 100644 packages/lsp/lsp-e2b/src/transport.ts
 create mode 100644 packages/lsp/lsp-e2b/tests/provider.spec.ts
 create mode 100644 packages/lsp/lsp-e2b/tests/transport.spec.ts
 create mode 100644 packages/lsp/lsp-e2b/tsconfig.json
 create mode 100644 packages/pty/pty-e2b/README.i18n.yaml
 create mode 100644 packages/pty/pty-e2b/README.md
 create mode 100644 packages/pty/pty-e2b/README.zh.md
 create mode 100644 packages/pty/pty-e2b/package.json
 create mode 100644 packages/pty/pty-e2b/src/config.ts
 create mode 100644 packages/pty/pty-e2b/src/index.ts
 create mode 100644 packages/pty/pty-e2b/src/invariant.ts
 create mode 100644 packages/pty/pty-e2b/src/session.ts
 create mode 100644 packages/pty/pty-e2b/tests/index.spec.ts
 create mode 100644 packages/pty/pty-e2b/tests/session.spec.ts
 create mode 100644 packages/pty/pty-e2b/tsconfig.json
 delete mode 100644 packages/pty/pty-local/src/sanitize.ts
 create mode 100644 packages/pty/pty/src/terminal.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 13d081c28f..46f1849b07 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 307a08d6ca77c83bf836bc8d50b071fbf33ac49a
-2026-07-27-e2b-remote-runtime-poc.zh.md: bb4e657d999760f000949d509228bbb65f22773a
+2026-07-27-e2b-remote-runtime-poc.md: 730e6f0e1958ccab43a5a6a11931f9407b38ef16
+2026-07-27-e2b-remote-runtime-poc.zh.md: 5f1ae07b985787a7dc1bd61f2a5b7ff0512d85c1
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 307a08d6ca..730e6f0e19 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -16,18 +16,19 @@ The E2B integration is a provider-composition POC with one shared lifecycle owne
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
 - `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
 - The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
+- PTY, LSP, and Code Runtime remain separate capability providers over the same owner, with their runtime split recorded in the [extension decision](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
 
 The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes. The composition therefore gives filesystem tools and Bash one remote cwd, process namespace, and spill/state directory while preserving the existing capability interfaces and model-facing tools.
 
 ## POC boundary
 
-Only filesystem state, command processes during the provider lifetime, and adapter-owned remote files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when the subprocess service disposes, including before a retained-sandbox pause or leave disposition.
+Filesystem state, managed commands, interactive shells, language servers, code workers, and adapter-owned files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, capability protocol state, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when their provider disposes, including before a retained-sandbox pause or leave disposition.
 
-The POC has no PTY adapter, LSP-specific integration, session-persistence backend, code-runtime backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host process handles, output cursors, or locks.
+The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host PTY/LSP/code-runtime state, process handles, output cursors, pending calls, or locks.
 
 ## Verification
 
-Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group/stdio/abort behavior, and the package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, proves FS-write→Bash-read and Bash-write→FS-read in the same remote cwd, proves neither file appears in the host cwd, disposes the composition, and confirms the sandbox id is gone.
+Package tests pin lifecycle cleanup, filesystem semantics, subprocess groups, byte framing, PTY readiness/signals, LSP transport and containment, Code Runtime binding/output behavior, and package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, exercises filesystem, Bash/subprocess, PTY, LSP, and Code Runtime through source and built package paths, proves host-workspace isolation, disposes the composition, and confirms the sandbox id is gone.
 
 ## Alternatives considered
 
@@ -35,7 +36,7 @@ Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group
 
 **Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
 
-**Add E2B-specific Bash, PTY, LSP, persistence, and synchronization packages together** — rejected because Bash already has the required subprocess seam and the other capabilities need separate consumer evidence and lifecycle designs. Their absence is an explicit fidelity boundary, not an incomplete hidden plan.
+**Put every E2B capability in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem, subprocess, PTY, LSP, and Code Runtime retain separate provider contracts, configuration, tests, and consumers; Bash continues to reuse its subprocess seam.
 
 **Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
 
@@ -43,4 +44,4 @@ Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group
 
 The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual state retention for experiments, while kill remains the demo's cleanup policy.
 
-The provider is not interchangeable with the local subprocess backend for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, callback output is not byte-faithful, signal attribution is inferred, and reconnect cannot restore handles. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The provider is not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index bb4e657d99..5f1ae07b98 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -16,18 +16,19 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
 - `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
 - 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
+- PTY、LSP 与 Code Runtime 仍是基于同一所有者的独立功能提供方；其运行时划分见[扩展决策](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
 
 该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱。因此，该组合让文件系统工具与 Bash 共享一个远程 cwd、进程命名空间和 spill／状态目录，同时保留现有功能接口与面向模型的工具。
 
 ## POC 边界
 
-只有文件系统状态、提供方存续期内的命令进程，以及适配器拥有的远程文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在进程管理服务 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
+文件系统状态、受管命令、交互式 shell、语言服务器、代码 worker 和适配器拥有的文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排、功能协议状态和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在所属提供方 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
 
-本 POC 没有 PTY 适配器、LSP 专用集成、会话持久化后端、代码运行时后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主进程句柄、输出游标或锁。
+本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主 PTY／LSP／Code Runtime 状态、进程句柄、输出游标、待处理调用或锁。
 
 ## 验证
 
-包测试固定生命周期清理、文件系统 seam 语义、进程管理的进程组／stdio／中止行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，证明同一远程 cwd 中 FS-write→Bash-read 和 Bash-write→FS-read 双向可见，证明两个文件均未出现在宿主 cwd 中，释放组合，并确认该沙箱 id 已不存在。
+包测试固定生命周期清理、文件系统语义、进程管理的进程组、字节分帧、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定／输出行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，通过源代码与已构建包路径演练文件系统、Bash／进程管理、PTY、LSP 和 Code Runtime，证明宿主工作区隔离，释放组合，并确认该沙箱 id 已不存在。
 
 ## 曾考虑的替代方案
 
@@ -35,7 +36,7 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 
 **在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
 
-**同时添加 E2B 专用 Bash、PTY、LSP、持久化和同步包。** 不予采纳，因为 Bash 已经具备所需的进程管理 seam，其他功能则需要各自的消费方证据和生命周期设计。缺少它们是显式保真边界，而不是尚未公开的不完整计划。
+**把所有 E2B 功能放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统、进程管理、PTY、LSP 与 Code Runtime 各自保留独立的提供方契约、配置、测试和消费方；Bash 继续复用其进程管理 seam。
 
 **仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
 
@@ -43,4 +44,4 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 
 这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留状态，演示仍以 `kill` 作为清理策略。
 
-该提供方并不能对所有消费方与本地进程管理后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，回调输出并非字节保真，信号归因依靠推断，重新连接也无法恢复句柄。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+该提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
new file mode 100644
index 0000000000..e34f939a7f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.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 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
+2026-07-28-e2b-interactive-semantic-code-runtime-poc.md: befaa47dd56b7f425e72978ae040bd0815cc9f92
+2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md: 677c3a09f6846320d3e000e9607becb3dee865cf
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
new file mode 100644
index 0000000000..befaa47dd5
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
@@ -0,0 +1,57 @@
+# Agent Note: E2B interactive, semantic, and code-runtime POC
+
+Status: implemented
+
+English | [中文](2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md)
+
+## Problem
+
+The [shared E2B runtime](2026-07-27-e2b-remote-runtime-poc.md) proves that filesystem operations and one-shot commands can inhabit one remote coding world, but an assembled coding agent also uses persistent terminals, language servers, and model-written Code Mode programs. Falling back to host implementations for those capabilities splits observable state: a Bash edit exists in E2B while a host PTY, LSP process, or code worker addresses a different filesystem and process namespace.
+
+Moving the complete harness process into E2B would unify that state but also changes plugin loading, credentials, model transport, session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
+
+## Decision
+
+Three opt-in providers extend the existing shared sandbox:
+
+- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` and keeps exact-Agent ownership in the existing registry.
+- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
+- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
+
+All three inject `ctx.e2b`; none creates another sandbox. The opt-in overlay composes them with `dsh-fs-e2b`, `dsh-subprocess-e2b`, and the existing `dsh-bash-local`, so files, foreground commands, interactive shell processes, language servers, and code workers observe one remote cwd.
+
+The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling moves into `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
+
+## Runtime boundary
+
+E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
+
+The host owns Cordis and plugin objects, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The host workspace is not mounted or synchronized merely because its absolute cwd string is reused remotely.
+
+Byte-sensitive protocols use the narrowest adapter needed for E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+
+Retaining a sandbox preserves remote files and any unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups are terminated and awaited when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
+
+## Verification
+
+Focused unit suites pin configuration, publication rollback, byte framing, multibyte boundaries, readiness, signals, timeout/abort ordering, output limits, hostile Code Runtime traffic, and disposal to quiescence. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+
+A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
+
+## Alternatives considered
+
+**Run the complete harness inside E2B** — rejected because it couples this provider experiment to credentials, LLM transport, plugin deployment, session persistence, supervision, and remote package installation. None is necessary to prove the capability seams.
+
+**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
+
+**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
+
+**Add a generic distributed-runtime abstraction first** — rejected because the three existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
+
+**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
+
+## Consequences
+
+The assembled POC keeps the coding world remote without moving the agent runtime or changing model-visible tool contracts. It demonstrates that PTY, LSP, and Code Runtime can share E2B state through existing plugins, while making the remaining host state explicit.
+
+This is not a deployment platform. Language-server installation, templates, volumes, snapshots, network policy, workspace synchronization, durable remote handles, and whole-harness execution remain outside scope. E2B SDK buffering and host protocol state remain memory costs. Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group is not made reconnectable or owned by this composition.
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
new file mode 100644
index 0000000000..677c3a09f6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
@@ -0,0 +1,57 @@
+# Agent Note: E2B 交互式、语义与代码运行时 POC
+
+Status: implemented
+
+[English](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) | 中文
+
+## 问题
+
+[共享 E2B 运行时](2026-07-27-e2b-remote-runtime-poc.md)证明，文件系统操作与一次性命令可以共处一个远程 coding 环境，但组装完成的 coding agent（智能体）还会使用持久终端、语言服务器，以及模型编写的 Code Mode 程序。若这些功能回退到宿主实现，可观测状态就会分裂：Bash 修改存在于 E2B 中，而宿主 PTY、LSP 进程或代码 worker 面向的却是另一个文件系统与进程命名空间。
+
+把完整 harness 进程迁入 E2B 可以统一这些状态，但也会改变插件加载、凭据、模型传输、会话持久性、监管和部署。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
+
+## 决策
+
+三个可选提供方扩展现有共享沙箱：
+
+- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
+- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
+- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
+
+三个提供方均注入 `ctx.e2b`，无一创建其他沙箱。可选叠加配置将它们与 `dsh-fs-e2b`、`dsh-subprocess-e2b` 和现有的 `dsh-bash-local` 组合，使文件、前台命令、交互式 shell 进程、语言服务器和代码 worker 观察到同一个远程 cwd。
+
+这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理移入 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
+
+## 运行时边界
+
+E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
+
+宿主拥有 Cordis 与插件对象、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。宿主工作区不会仅因远程复用了其绝对 cwd 字符串就被挂载或同步。
+
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+
+保留沙箱只会保存远程文件与任何未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
+
+## 验证
+
+聚焦单元测试固定配置、发布回滚、字节分帧、多字节边界、就绪状态、信号、超时／中止顺序、输出上限、恶意 Code Runtime 通信，以及等待完全停稳的资源释放。相邻本地后端测试固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+
+凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
+
+## 曾考虑的替代方案
+
+**在 E2B 内运行完整 harness。** 不予采纳，因为这会把这项提供方实验与凭据、LLM 传输、插件部署、会话持久化、监管和远程包安装耦合。要证明功能 seam，无需引入任何一项。
+
+**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
+
+**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
+
+**先添加通用分布式运行时抽象。** 不予采纳，因为现有三个功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
+
+**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
+
+## 后果
+
+组装后的 POC 在不迁移 agent 运行时、不改变模型可见工具契约的前提下，把 coding 环境保留在远程。它证明 PTY、LSP 与 Code Runtime 可以通过现有插件共享 E2B 状态，同时明确列出仍留在宿主的状态。
+
+这不是部署平台。语言服务器安装、模板、卷、快照、网络策略、工作区同步、持久远程句柄和完整 harness 执行仍不在范围内。E2B SDK 缓冲与宿主协议状态仍会占用内存。模型程序与 Node worker 内部机制共享一个 JavaScript realm；有意逃离已捕获远程进程组的进程，也不会因此变得可重新连接或由该组合管理。
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7ce45c6817..33f357d2bf 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:119`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
@@ -1180,7 +1180,7 @@ list(owner: Agent): PtySessionSnapshot[]
 
 Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md)
 
-Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
+Source: [`packages/pty/pty/src/index.ts:114`](../../packages/pty/pty/src/index.ts)
 
 ## `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 4f961100b4..877172c343 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,9 +1,10 @@
-# POC overlay: keep the headless agent and model-facing tools, but place its
-# filesystem and managed Bash process world in one short-lived E2B sandbox.
+# POC overlay: keep the advanced headless agent and model-facing tools, but
+# place its filesystem, processes, terminals, language servers, and Code Mode
+# execution in one short-lived E2B sandbox.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
-    path: ./cordis.yml
+    path: ./advanced.cordis.yml
     patches:
       - id: subprocess
         name: '@deepseek-ai/dsh-subprocess-local'
@@ -11,6 +12,9 @@
       - id: fs-local
         name: '@deepseek-ai/dsh-fs-local'
         disabled: true
+      - id: code-runtime
+        name: '@deepseek-ai/dsh-code-runtime-worker'
+        disabled: true
       - id: bash
         name: '@deepseek-ai/dsh-bash-local'
         config:
@@ -28,3 +32,27 @@
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
             name: '@deepseek-ai/dsh-fs-e2b'
+          - id: code-runtime-e2b
+            name: '@deepseek-ai/dsh-code-runtime-e2b'
+          - id: pty
+            name: '@deepseek-ai/dsh-pty'
+          - id: pty-e2b
+            name: '@deepseek-ai/dsh-pty-e2b'
+          - id: tool-pty
+            name: '@deepseek-ai/dsh-tool-pty'
+          - id: lsp
+            name: '@deepseek-ai/dsh-lsp'
+          - id: lsp-e2b
+            name: '@deepseek-ai/dsh-lsp-e2b'
+            config:
+              servers:
+                typescript:
+                  command: npx
+                  args: [--yes, typescript-language-server@5.0.0, --stdio]
+                  extensionToLanguage:
+                    .ts: typescript
+                    .tsx: typescriptreact
+                    .js: javascript
+                    .jsx: javascriptreact
+          - id: tool-lsp
+            name: '@deepseek-ai/dsh-tool-lsp'
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 3b2cef609b..33e9530708 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,13 +1,38 @@
+import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-code-runtime-e2b'
 import type {} from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
+import type {} from '@deepseek-ai/dsh-lsp-e2b'
+import type {} from '@deepseek-ai/dsh-pty-e2b'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
 
 const ctx = await boot('e2b-composition', resolve(configPath))
+const ownerFiber = ctx.plugin(() => {})
+const ownerId = SessionId('e2b-live-owner')
+const owner: Agent = {
+  id: ownerId,
+  options: {},
+  session: new Session(ownerId),
+  status: 'idle',
+  acceptsNextStep: false,
+  ctx: ownerFiber.ctx,
+  followup: () => AgentMessageId('unused'),
+  steer: () => AgentMessageId('unused'),
+  inject: () => AgentMessageId('unused'),
+  send: () => AgentMessageId('unused'),
+  cancel() {},
+  whenIdle: () => Promise.resolve(),
+}
+const unregisterOwner = ctx.agents.register(owner)
+let terminalId: Awaited<ReturnType<typeof ctx.pty.spawn>>['sessionId'] | undefined
 try {
   const fromFs = await ctx.fs.resolve('from-fs.txt')
   await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
@@ -22,11 +47,129 @@ try {
   }
   const fromBash = await ctx.fs.resolve('from-bash.txt')
   const fsRead = await ctx.fs.readText(fromBash)
+
+  const lspFixture = await readFile(new URL('./fixture-lsp.mjs', import.meta.url), 'utf8')
+  const remoteLspFixture = await ctx.fs.resolve('fixture-lsp.mjs')
+  await ctx.fs.writeText(remoteLspFixture, lspFixture, { kind: 'createIfAbsent' })
+  const remoteSource = await ctx.fs.resolve('multibyte.ts')
+  await ctx.fs.writeText(remoteSource, 'const café = "你好"\nconsole.log(café)\n', { kind: 'createIfAbsent' })
+  const hover = await ctx.lsp.query({
+    operation: 'hover',
+    filePath: 'multibyte.ts',
+    position: { line: 0, character: 7 },
+    workspaceRoot: process.cwd(),
+  })
+  const definition = await ctx.lsp.query({
+    operation: 'goToDefinition',
+    filePath: 'multibyte.ts',
+    position: { line: 0, character: 7 },
+    workspaceRoot: process.cwd(),
+  })
+
+  const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
+  terminalId = terminal.sessionId
+  const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
+    text: "printf 'PTY-你好\\n'",
+    submit: true,
+  }).done
+  const sleeping = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
+  await new Promise(resolveDelay => setTimeout(resolveDelay, 150))
+  const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
+  const interrupted = await sleeping.done
+  const terminalScrollback = ctx.pty.read(owner, terminal.sessionId, { count: 50 })
+  await ctx.pty.kill(owner, terminal.sessionId, 'live E2B composition complete')
+  terminalId = undefined
+
+  const code = await ctx.codeRuntime.run({
+    program: `
+      console.log('remote-log 你好', 42)
+      const arrayPrototype = Array.prototype
+      const objectPrototype = Object.prototype
+      const setPrototype = Set.prototype
+      const stringPrototype = String.prototype
+      Array.isArray = () => false
+      Object.defineProperty = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') }
+      Object.hasOwn = () => false
+      Object.is = () => true
+      objectPrototype.propertyIsEnumerable = () => false
+      Number.isFinite = Number.isSafeInteger = () => false
+      Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') }
+      setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') }
+      stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') }
+      Buffer.byteLength = () => 0
+      Function.prototype.toString = () => 'mutated'
+      objectPrototype.constructor = arrayPrototype.constructor = null
+      globalThis.Array = globalThis.Buffer = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Promise = globalThis.Reflect = globalThis.Set = globalThis.String = undefined
+      process.stdout.write('post-mutation', () => {})
+      const doubled: number = await bridge.double({ value: 21 })
+      let typed = false
+      try {
+        await bridge.fail({ reason: 'expected' })
+      } catch (error) {
+        typed = error instanceof BridgeError && (error as { member: string }).member === 'fail'
+      }
+      return { doubled, typed }
+    `,
+    bindings: [{
+      global: 'bridge',
+      errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
+      functions: {
+        double: async (args) => {
+          const value = (args as { value: number }).value
+          return value * 2
+        },
+        fail: async () => { throw new Error('binding rejected') },
+      },
+    }],
+  })
+  const hostileOutput = await ctx.codeRuntime.run({
+    program: `
+      const payload = '🙂'.repeat(4096)
+      String.prototype[Symbol.iterator] = () => { throw new Error('mutated string iterator') }
+      console.log(payload)
+      return true
+    `,
+    bindings: [],
+  })
+  const timedOut = await ctx.codeRuntime.run({
+    program: 'await new Promise(() => {})',
+    bindings: [],
+  })
+  const abortController = new AbortController()
+  const aborting = ctx.codeRuntime.run({
+    program: 'await new Promise(() => {})',
+    bindings: [],
+    signal: abortController.signal,
+  })
+  setTimeout(() => { abortController.abort('live abort') }, 50)
+  const aborted = await aborting
+  const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
+  const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
+    JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
+  )
+
   process.stdout.write(`${JSON.stringify({
     sandboxId: await ctx.e2b.sandboxId,
     bashRead: bashRead.stdout.text,
     fsRead,
+    hover,
+    definition,
+    terminal: {
+      motd: terminal.motd,
+      echo: terminalEcho,
+      signal: terminalSignal,
+      interrupted,
+      scrollback: terminalScrollback.text,
+    },
+    code,
+    hostileOutput,
+    timedOut,
+    aborted,
+    lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
+  if (terminalId !== undefined) await ctx.pty.kill(owner, terminalId, 'fixture cleanup').catch(() => false)
+  unregisterOwner()
+  await ownerFiber.dispose()
   await ctx.fiber.dispose()
 }
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 08a7e7225c..f5cf403c4b 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -17,3 +17,43 @@
 
 - id: fs-e2b
   name: '@deepseek-ai/dsh-fs-e2b'
+
+- id: agents
+  name: '@deepseek-ai/dsh-agent'
+
+- id: pty
+  name: '@deepseek-ai/dsh-pty'
+
+- id: pty-e2b
+  name: '@deepseek-ai/dsh-pty-e2b'
+  config:
+    pollIntervalMs: 25
+    idleSilenceMs: 2000
+    timeoutMs: 5000
+    disposeGraceMs: 1000
+
+- id: lsp
+  name: '@deepseek-ai/dsh-lsp'
+
+- id: lsp-e2b
+  name: '@deepseek-ai/dsh-lsp-e2b'
+  config:
+    servers:
+      fixture:
+        command: node
+        args:
+          - !!js process.cwd() + '/fixture-lsp.mjs'
+        extensionToLanguage:
+          .ts: typescript
+        shutdownTimeoutMs: 1000
+        killGraceMs: 500
+
+- id: code-runtime-e2b
+  name: '@deepseek-ai/dsh-code-runtime-e2b'
+  config:
+    computeMs: 500
+    maxWallMs: 5000
+    maxOutputBytes: 4096
+    maxOldGenerationSizeMb: 128
+    maxFrameBytes: 4194304
+    killGraceMs: 500
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs b/examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs
new file mode 100644
index 0000000000..dc4f7bb219
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs
@@ -0,0 +1,85 @@
+import { Buffer } from 'node:buffer'
+
+let pending = Buffer.alloc(0)
+let source = ''
+let sourceUri = ''
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message))
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`)
+  process.stdout.write(body)
+}
+
+function respond(id, result) {
+  send({ jsonrpc: '2.0', id, result })
+}
+
+function dispatch(message) {
+  switch (message.method) {
+    case 'initialize':
+      respond(message.id, {
+        capabilities: {
+          positionEncoding: 'utf-16',
+          textDocumentSync: { openClose: true, change: 1 },
+          definitionProvider: true,
+          referencesProvider: true,
+          implementationProvider: true,
+          hoverProvider: true,
+        },
+      })
+      return
+    case 'textDocument/didOpen':
+      source = message.params.textDocument.text
+      sourceUri = message.params.textDocument.uri
+      return
+    case 'textDocument/didClose':
+      source = ''
+      sourceUri = ''
+      return
+    case 'textDocument/hover':
+      if (!source.includes('const café = "你好"')) {
+        send({ jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'multibyte source was corrupted' } })
+        return
+      }
+      respond(message.id, {
+        contents: { kind: 'markdown', value: '**remote hover** 你好 café' },
+        range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } },
+      })
+      return
+    case 'textDocument/definition':
+    case 'textDocument/references':
+    case 'textDocument/implementation':
+      respond(message.id, [{
+        uri: sourceUri,
+        range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } },
+      }])
+      return
+    case 'shutdown':
+      respond(message.id, null)
+      return
+    case 'exit':
+      process.exit(0)
+      return
+  }
+}
+
+function drain() {
+  for (;;) {
+    const headerEnd = pending.indexOf('\r\n\r\n')
+    if (headerEnd < 0) return
+    const header = pending.subarray(0, headerEnd).toString('ascii')
+    const match = /(?:^|\r\n)Content-Length: ([0-9]+)(?:\r\n|$)/i.exec(header)
+    if (!match) throw new Error('missing Content-Length')
+    const length = Number(match[1])
+    const bodyStart = headerEnd + 4
+    if (pending.length < bodyStart + length) return
+    const body = pending.subarray(bodyStart, bodyStart + length)
+    pending = pending.subarray(bodyStart + length)
+    dispatch(JSON.parse(body.toString('utf8')))
+  }
+}
+
+process.stdin.on('data', chunk => {
+  pending = Buffer.concat([pending, chunk])
+  drain()
+})
diff --git a/examples/package.json b/examples/package.json
index 48ac39f5ca..8dd631e760 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -43,10 +43,12 @@
     "@deepseek-ai/dsh-llm-replay": "workspace:*",
     "@deepseek-ai/dsh-loader-smoke": "workspace:*",
     "@deepseek-ai/dsh-lsp": "workspace:*",
+    "@deepseek-ai/dsh-lsp-e2b": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
     "@deepseek-ai/dsh-permission": "workspace:*",
     "@deepseek-ai/dsh-plan-mode": "workspace:*",
     "@deepseek-ai/dsh-pty": "workspace:*",
+    "@deepseek-ai/dsh-pty-e2b": "workspace:*",
     "@deepseek-ai/dsh-pty-local": "workspace:*",
     "@deepseek-ai/dsh-pwsh-local": "workspace:*",
     "@deepseek-ai/dsh-repeat-tool-guard": "workspace:*",
@@ -54,7 +56,10 @@
     "@deepseek-ai/dsh-sandbox": "workspace:*",
     "@deepseek-ai/dsh-sandbox-local": "workspace:*",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+<<<<<<< HEAD
     "@deepseek-ai/dsh-scope": "workspace:*",
+=======
+>>>>>>> 3f6c905d5e (Add E2B PTY, LSP, and code runtime providers)
     "@deepseek-ai/dsh-session": "workspace:*",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:*",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 3eb462d513..f9160b4f8e 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
-README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
+README.md: f59fc3b15331b4799cbc7a3fbe27ce8cd9a12e51
+README.zh.md: 02ade97887fab8a8a0c22efcf73bb2dd1f2cf33c
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index f20a287419..f59fc3b153 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -2,11 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the generated TypeScript SDK); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | Code-execution seam and shared vocabulary | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
+| `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` |
+| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
 
-Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
+Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [remote extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index f5cd4c9949..02ade97887 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -1,12 +1,13 @@
-# code-runtime/ — 代码执行能力家族
+# code-runtime/：代码执行能力家族
 
 [English](README.md) | 中文
 
-代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）；设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
+代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于针对宿主提供的异步绑定执行一段模型编写的程序，并捕获程序打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具与生成的 TypeScript SDK）；设计记录在 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 中。这些都是**产品** 包。
 
-| 包 | 职责 | ctx key |
+| 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | 代码执行 seam 与共享词汇 | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
+| `code-runtime/` | 抽象代码执行 seam（接口 + 词汇） | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | worker 线程后端：每次运行使用全新 worker，由宿主侧剥离 TypeScript 类型（类型注解仅供参考，绝不执行类型检查）、端口桥接绑定、预算／堆隔离 | 注册 `ctx.codeRuntime` |
+| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
 
-后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
+不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[远程扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
diff --git a/packages/code-runtime/code-runtime-e2b/README.i18n.yaml b/packages/code-runtime/code-runtime-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..c00b40f4a2
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/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/code-runtime/code-runtime-e2b/README.md
+README.md: bf26174c59c1df18f63278acb7923fd409860b44
+README.zh.md: c87945da30a6f8d77eb3722879510bb6159b3ee8
diff --git a/packages/code-runtime/code-runtime-e2b/README.md b/packages/code-runtime/code-runtime-e2b/README.md
new file mode 100644
index 0000000000..bf26174c59
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/README.md
@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-code-runtime-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of [`ctx.codeRuntime`](../code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `computeMs` | `60000` | Remote worker event-loop busy-time budget. |
+| `maxWallMs` | `600000` | Host-observed wall-clock ceiling. |
+| `maxOutputBytes` | `67108864` | Combined serialized outer logs/value/diagnostic cap. |
+| `maxOldGenerationSizeMb` | `512` | Remote worker old-generation heap cap in MiB. |
+| `maxFrameBytes` | `268435456` | Largest decoded bridge frame, including binding traffic. |
+| `killGraceMs` | `2000` | Remote process-group TERM-to-KILL grace. |
+
+Every value is a positive safe integer. `maxOutputBytes` is at least four bytes, `maxWallMs` cannot exceed Node's maximum timer delay, and `maxFrameBytes` cannot be smaller than `maxOutputBytes`. The service requires the concrete `dsh-subprocess-e2b` backend so run cleanup has remote process-group semantics.
+
+## Execution and bridge contract
+
+Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner creates a fresh worker thread with an empty environment and heap limit, measures active event-loop time, and destroys that worker after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
+
+The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
+
+Program failures resolve as `CodeRunResult.error`; only seam misuse rejects. `isolation` is reported as `container`, which is a deployment descriptor rather than a security claim.
+
+## Model Experience
+
+Indirectly, through Code Mode in `dsh-tools`, which returns program logs, values, or typed failures through the existing `run_code` result contract.
+
+#### KV Cache effect
+
+No direct invalidation; Code Mode owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Not a whole-agent runtime** — Cordis, sessions, LLM calls, binding dispatch, TypeScript stripping, output ledgers, and E2B SDK state remain on the host.
+- **No reconnectable runs** — retaining a sandbox preserves files but not worker/subprocess handles, binding calls, timers, or output cursors.
+- **Node worker internals share the model realm** — mutating realm-wide globals or prototypes that Node itself uses can terminate the worker; captured adapter intrinsics are not a separate JavaScript realm or a security boundary.
+- **Deliberate process-group escape is not captured** — model code can create a new POSIX session; that unmanaged process is outside this backend's cleanup identity.
+- **Intermediate binding traffic is memory-bounded only per frame** — it does not enter model context or the outer-output ledger, but aggregate host/remote process memory remains the limit.
+- **Experimental type stripping** — the backend shares the worker implementation's reliance on Node's experimental erasable-syntax API.
+- **Sandbox policy is template-owned** — this package adds no network, volume, snapshot, or workspace-synchronization policy.
diff --git a/packages/code-runtime/code-runtime-e2b/README.zh.md b/packages/code-runtime/code-runtime-e2b/README.zh.md
new file mode 100644
index 0000000000..c87945da30
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/README.zh.md
@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-code-runtime-e2b
+
+[English](README.md) | 中文
+
+[`ctx.codeRuntime`](../code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `computeMs` | `60000` | 远程 worker 的事件循环忙碌时间预算。 |
+| `maxWallMs` | `600000` | 宿主观测到的墙钟时间上限。 |
+| `maxOutputBytes` | `67108864` | 外层日志、值和诊断合计的序列化上限。 |
+| `maxOldGenerationSizeMb` | `512` | 远程 worker 的老生代堆上限（MiB）。 |
+| `maxFrameBytes` | `268435456` | 已解码桥接帧的最大大小，包括绑定流量。 |
+| `killGraceMs` | `2000` | 远程进程组 TERM 到 KILL 的宽限期。 |
+
+每个值都必须是正的安全整数。`maxOutputBytes` 必须至少为 4 字节，`maxWallMs` 不得超过 Node 的最大定时器延迟，且 `maxFrameBytes` 不得小于 `maxOutputBytes`。本服务要求使用具体的 `dsh-subprocess-e2b` 后端，使运行清理具备远程进程组语义。
+
+## 执行与桥接契约
+
+设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会创建一个具有空环境与堆上限的全新 worker 线程，测量事件循环活跃时间，并在一次运行结算后销毁该 worker。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
+
+由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
+
+程序失败会 resolve 为 `CodeRunResult.error`；只有 seam 误用才会 reject。`isolation` 报告为 `container`；这是部署描述符，不构成安全声明。
+
+## 模型体验
+
+通过 `dsh-tools` 中的 Code Mode 间接影响模型；它会通过现有 `run_code` 结果契约返回程序日志、值或类型化失败。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由 Code Mode 负责。
+
+## 已知限制与暂缓工作
+
+- **并非完整的 agent（智能体）运行时**：Cordis、会话、LLM（大语言模型）调用、绑定分发、TypeScript 类型剥离、输出账本和 E2B SDK 状态仍保留在宿主侧。
+- **运行不可重连**：保留沙箱会保留文件，但不会保留 worker／进程管理句柄、绑定调用、定时器或输出游标。
+- **Node worker 内部机制与模型共享同一 realm**：修改 Node 自身使用、影响整个 realm 的全局对象或原型可能会终止 worker；已捕获的适配器 intrinsic 并不构成独立的 JavaScript realm 或安全边界。
+- **不会捕获有意逃逸进程组的行为**：模型代码可以创建新的 POSIX 会话；该非受管进程不属于此后端的清理身份范围。
+- **中间绑定流量的内存边界仅适用于单帧**：它不会进入模型上下文或外层输出账本，但其总量仍只受宿主／远程进程内存限制。
+- **实验性类型剥离**：该后端与 worker 实现一样，依赖 Node 的实验性可擦除语法 API。
+- **沙箱策略归模板负责**：本包不会额外增加网络、卷、快照或工作区同步策略。
diff --git a/packages/code-runtime/code-runtime-e2b/package.json b/packages/code-runtime/code-runtime-e2b/package.json
new file mode 100644
index 0000000000..222ae71bef
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-code-runtime-e2b",
+  "description": "E2B code-runtime implementation for DeepSeek Harness",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-code-runtime-worker": "^0.0.1",
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-code-runtime": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/code-runtime/code-runtime-e2b/src/index.ts b/packages/code-runtime/code-runtime-e2b/src/index.ts
new file mode 100644
index 0000000000..fbfbdea91f
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/src/index.ts
@@ -0,0 +1,441 @@
+/** E2B process/worker implementation of the harness code-runtime seam. */
+
+import { posix } from 'node:path'
+import { stripTypeScriptTypes } from 'node:module'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
+import type {
+  CodeBindingNamespace,
+  CodeJsonValue,
+  CodeRunFailure,
+  CodeRunRequest,
+  CodeRunResult,
+} from '@deepseek-ai/dsh-code-runtime'
+import {
+  E2BFrameDecoder,
+  encodeE2BFrame,
+  quoteE2BShellArg,
+  resolveE2BExecutable,
+} from '@deepseek-ai/dsh-e2b'
+import {
+  decodeWorkerJson,
+  encodeWorkerJson,
+  OutputLedger,
+} from '@deepseek-ai/dsh-code-runtime-worker'
+import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { CODE_RUNNER_SOURCE } from './runner-source.ts'
+
+/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
+export interface Config {
+  /** Remote worker measured event-loop busy-time budget. */
+  computeMs?: number
+  /** Host-observed wall-clock ceiling. */
+  maxWallMs?: number
+  /** Combined serialized outer logs/value/diagnostic cap. */
+  maxOutputBytes?: number
+  /** Remote worker old-generation heap cap in MiB. */
+  maxOldGenerationSizeMb?: number
+  /** Largest decoded bridge frame, including binding traffic. */
+  maxFrameBytes?: number
+  /** Remote process-group TERM-to-KILL grace. */
+  killGraceMs?: number
+}
+
+type ResolvedConfig = Required<Config>
+
+interface LiveRun {
+  settle(failure: CodeRunFailure): void
+  finished: Promise<void>
+}
+
+interface CallMessage {
+  type: 'call'
+  id: number
+  global: string
+  name: string
+  args: WorkerJsonWire
+}
+
+interface LogMessage {
+  type: 'log'
+  text: string
+}
+
+interface DoneMessage {
+  type: 'done'
+  value?: WorkerJsonWire
+  error?: CodeRunFailure
+}
+
+type RunnerMessage = CallMessage | LogMessage | DoneMessage | { type: 'output-limit' }
+
+const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
+const MIN_OUTPUT_BYTES = 4
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+/* jscpd:ignore-start -- Backends enforce the same injected-global vocabulary without coupling lifecycle implementations. */
+const RESERVED_WORDS = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
+  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
+  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
+  'private', 'protected', 'public', 'arguments', 'eval',
+])
+const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
+/* jscpd:ignore-end */
+const FAILURE_KINDS = new Set<CodeRunFailure['kind']>([
+  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
+])
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function parseRunnerMessage(raw: unknown): RunnerMessage | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const record = raw as Record<string, unknown>
+  if (record.type === 'output-limit') return { type: 'output-limit' }
+  if (record.type === 'log') return typeof record.text === 'string' ? { type: 'log', text: record.text } : undefined
+  if (record.type === 'call') {
+    if (!Number.isSafeInteger(record.id) || (record.id as number) < 1 || typeof record.global !== 'string' || typeof record.name !== 'string' || !Array.isArray(record.args)) return undefined
+    return { type: 'call', id: record.id as number, global: record.global, name: record.name, args: record.args as WorkerJsonWire }
+  }
+  if (record.type !== 'done') return undefined
+  if (record.error === undefined) {
+    return { type: 'done', ...record.value === undefined ? {} : { value: record.value as WorkerJsonWire } }
+  }
+  if (typeof record.error !== 'object' || record.error === null) return undefined
+  const error = record.error as Record<string, unknown>
+  if (typeof error.kind !== 'string' || !FAILURE_KINDS.has(error.kind as CodeRunFailure['kind']) || typeof error.message !== 'string') return undefined
+  return { type: 'done', error: { kind: error.kind as CodeRunFailure['kind'], message: error.message } }
+}
+
+/** E2B-backed runtime: host-side type stripping, remote worker execution, host binding dispatch. */
+export class E2BCodeRuntime extends CodeRuntime {
+  static inject = ['e2b', 'subprocess']
+
+  static Config: z<Config> = z.object({
+    computeMs: z.number().default(60_000),
+    maxWallMs: z.number().default(600_000),
+    maxOutputBytes: z.number().default(67_108_864),
+    maxOldGenerationSizeMb: z.number().default(512),
+    maxFrameBytes: z.number().default(268_435_456),
+    killGraceMs: z.number().default(2_000),
+  })
+
+  readonly language = 'typescript'
+  readonly isolation = 'container'
+
+  private readonly config: ResolvedConfig
+  private readonly ready: Promise<{ node: string; runner: string }>
+  private readonly live = new Set<LiveRun>()
+  private readonly subprocess: E2BSubprocessService
+  private disposed = false
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx)
+    if (!(ctx.subprocess instanceof E2BSubprocessService)) {
+      throw new Error('code-runtime-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
+    }
+    this.subprocess = ctx.subprocess
+    this.config = config as ResolvedConfig
+    for (const [key, value] of Object.entries(this.config)) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`code-runtime-e2b: config.${key} must be a positive safe integer`)
+      }
+    }
+    if (this.config.maxOutputBytes < MIN_OUTPUT_BYTES) {
+      throw new Error(`code-runtime-e2b: config.maxOutputBytes must be at least ${MIN_OUTPUT_BYTES}`)
+    }
+    if (this.config.maxWallMs > MAX_TIMER_DELAY_MS) {
+      throw new Error(`code-runtime-e2b: config.maxWallMs must be at most ${MAX_TIMER_DELAY_MS}`)
+    }
+    if (this.config.maxFrameBytes < this.config.maxOutputBytes) {
+      throw new Error('code-runtime-e2b: config.maxFrameBytes must be at least maxOutputBytes')
+    }
+    this.ready = this.prepare()
+    void this.ready.catch(() => {})
+    ctx.effect(() => () => this.teardown(), 'E2B code-runtime teardown')
+  }
+
+  /* jscpd:ignore-start -- Seam-level abort and type-strip results remain identical across execution substrates. */
+  /** Execute one type-stripped program in a fresh E2B worker process. */
+  async run(request: CodeRunRequest): Promise<CodeRunResult> {
+    if (this.disposed) throw new Error('code-runtime-e2b: run() after disposal')
+    const bindings = this.validateBindings(request)
+    if (request.signal?.aborted === true) {
+      return this.failure({ kind: 'abort', message: String(request.signal.reason) })
+    }
+    let code: string
+    try {
+      const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + request.program + STRIP_WRAP.suffix)
+      code = stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
+    } catch (error: unknown) {
+      return this.failure({ kind: 'exception', message: messageOf(error) })
+    }
+    let runtime: Awaited<typeof this.ready>
+    try {
+      runtime = await this.ready
+    } catch (error: unknown) {
+      return this.failure({ kind: 'worker-exit', message: `E2B runtime setup failed: ${messageOf(error)}` })
+    }
+    // Disposal can race the awaited remote setup after the pre-await check.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
+    return await this.execute(request, code, bindings, runtime)
+  }
+  /* jscpd:ignore-end */
+
+  private async prepare(): Promise<{ node: string; runner: string }> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    const runner = posix.join(this.ctx.e2b.runtimeRoot, 'code-runtime-runner.mjs')
+    await sandbox.files.write([{ path: runner, data: CODE_RUNNER_SOURCE }])
+    await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(runner)}`)
+    const node = await resolveE2BExecutable(sandbox, 'node')
+    return { node, runner }
+  }
+
+  private failure(error: CodeRunFailure): CodeRunResult {
+    return new OutputLedger(this.config.maxOutputBytes).failure([], error)
+  }
+
+  /* jscpd:ignore-start -- Binding names have one seam contract while dispatch and teardown remain backend-owned. */
+  private validateBindings(request: CodeRunRequest): Map<string, CodeBindingNamespace> {
+    const bindings = new Map<string, CodeBindingNamespace>()
+    for (const namespace of request.bindings) {
+      if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
+        throw new Error(`code-runtime-e2b: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
+      }
+      if (namespace.global === 'console' || bindings.has(namespace.global)) {
+        throw new Error(`code-runtime-e2b: duplicate binding global ${JSON.stringify(namespace.global)}`)
+      }
+      bindings.set(namespace.global, namespace)
+    }
+    const errorClassNames = new Set<string>()
+    for (const namespace of request.bindings) {
+      const descriptor = namespace.errorClass
+      if (descriptor === undefined) continue
+      if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
+        throw new Error(`code-runtime-e2b: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
+      }
+      if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
+        throw new Error(`code-runtime-e2b: duplicate injected global ${JSON.stringify(descriptor.name)}`)
+      }
+      if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
+        throw new Error(`code-runtime-e2b: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
+      }
+      errorClassNames.add(descriptor.name)
+    }
+    return bindings
+  }
+  /* jscpd:ignore-end */
+
+  private async execute(
+    request: CodeRunRequest,
+    code: string,
+    bindings: Map<string, CodeBindingNamespace>,
+    runtime: { node: string; runner: string },
+  ): Promise<CodeRunResult> {
+    const handle = this.subprocess.spawn({
+      argv: [runtime.node, runtime.runner],
+      cwd: this.ctx.e2b.cwd,
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
+      graceMs: this.config.killGraceMs,
+      ...request.signal === undefined ? {} : { signal: request.signal },
+      env: {},
+    })
+    if (handle.stdin === undefined || handle.stdout === undefined) {
+      handle.terminate()
+      await Promise.allSettled([handle.done])
+      try {
+        await handle.waitForExit()
+      } catch (error: unknown) {
+        return this.failure({ kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(error)}` })
+      }
+      return this.failure({ kind: 'worker-exit', message: 'E2B subprocess dropped a piped runtime stream' })
+    }
+    const stdin = handle.stdin
+    const stdout = handle.stdout
+
+    return new Promise<CodeRunResult>((resolve) => {
+      const output = new OutputLedger(this.config.maxOutputBytes)
+      const logs: string[] = []
+      const answered = new Set<number>()
+      const decoder = new E2BFrameDecoder(this.config.maxFrameBytes)
+      let settled = false
+      let finishResolve!: () => void
+      const finished = new Promise<void>((done) => { finishResolve = done })
+      const wallTimer: { current: NodeJS.Timeout | undefined } = { current: undefined }
+      const live: LiveRun = {
+        finished,
+        settle: (failure) => { finish(() => output.failure(logs, failure)) },
+      }
+
+      const finish = (result: CodeRunResult | (() => CodeRunResult)): void => {
+        if (settled) return
+        settled = true
+        clearTimeout(wallTimer.current)
+        request.signal?.removeEventListener('abort', onAbort)
+        this.live.delete(live)
+        void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
+          handle.terminate()
+          await handle.done.catch(() => {})
+          let cleanupError: unknown
+          try {
+            await handle.waitForExit()
+          } catch (error: unknown) {
+            cleanupError = error
+          }
+          try {
+            decoder.finish()
+          } catch (error: unknown) {
+            result = output.failure(logs, { kind: 'worker-exit', message: messageOf(error) })
+          }
+          if (cleanupError !== undefined) {
+            result = output.failure(logs, { kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(cleanupError)}` })
+          }
+          const final = typeof result === 'function' ? result() : result
+          finishResolve()
+          resolve(final)
+        })
+      }
+
+      const sendReply = (message: unknown): void => {
+        if (settled) return
+        stdin.write(encodeE2BFrame(message), (error?: Error | null) => {
+          if (error !== undefined && error !== null) {
+            finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge write failed: ${error.message}` }))
+          }
+        })
+      }
+
+      /* jscpd:ignore-start -- Host binding resolution mirrors worker semantics over a different transport. */
+      const onCall = (message: CallMessage): void => {
+        if (answered.has(message.id)) return
+        answered.add(message.id)
+        const functions = bindings.get(message.global)?.functions
+        const fn = functions !== undefined && Object.hasOwn(functions, message.name) ? functions[message.name] : undefined
+        if (typeof fn !== 'function') {
+          sendReply({ type: 'reply', id: message.id, ok: false, message: `unknown binding ${JSON.stringify(`${message.global}.${message.name}`)}` })
+          return
+        }
+        const args = decodeWorkerJson(message.args)
+        if (args === undefined) {
+          sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding arguments must be lossless JSON' })
+          return
+        }
+        void (async () => {
+          try {
+            const resolved = await fn(args)
+            let value: CodeJsonValue | undefined
+            try {
+              value = snapshotJsonValue(resolved)
+            } catch {
+              value = undefined
+            }
+            if (value === undefined) {
+              sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding resolution must be lossless JSON' })
+            } else {
+              sendReply({ type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(value) })
+            }
+          } catch (error: unknown) {
+            sendReply({ type: 'reply', id: message.id, ok: false, message: messageOf(error) })
+          }
+        })()
+      }
+      /* jscpd:ignore-end */
+
+      const onMessage = (raw: unknown): void => {
+        if (settled) return
+        const message = parseRunnerMessage(raw)
+        if (message === undefined) return
+        if (message.type === 'log') {
+          if (!output.admit(message.text, logs)) finish(output.limit([...logs, message.text]))
+          return
+        }
+        if (message.type === 'output-limit') {
+          finish(output.limit(logs))
+          return
+        }
+        if (message.type === 'call') {
+          onCall(message)
+          return
+        }
+        if (message.error !== undefined) {
+          finish(() => output.failure(logs, message.error as CodeRunFailure))
+        } else if (message.value === undefined) {
+          finish(() => output.success(logs))
+        } else {
+          const value = decodeWorkerJson(message.value)
+          if (value === undefined) finish(() => output.failure(logs, { kind: 'invalid-output', message: 'program completion must be lossless JSON' }))
+          else finish(() => output.success(logs, value))
+        }
+      }
+
+      stdout.on('data', (chunk: Buffer) => {
+        if (settled) return
+        try {
+          for (const frame of decoder.push(chunk.toString('utf8'))) onMessage(frame)
+        } catch (error: unknown) {
+          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
+        }
+      })
+      stdout.on('error', (error: Error) => {
+        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdout failed: ${error.message}` }))
+      })
+      stdin.on('error', (error: Error) => {
+        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdin failed: ${error.message}` }))
+      })
+      void handle.done.then(
+        () => {
+          if (!settled) {
+            const stderr = handle.collected.stderr?.readFrom(0).text.trim()
+            finish(() => output.failure(logs, { kind: 'worker-exit', message: stderr === undefined || stderr === '' ? 'E2B runtime exited before completing' : `E2B runtime exited before completing: ${stderr}` }))
+          }
+        },
+        (error: unknown) => {
+          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` }))
+        },
+      )
+
+      const onAbort = (): void => {
+        finish(() => output.failure(logs, { kind: 'abort', message: String(request.signal?.reason) }))
+      }
+      request.signal?.addEventListener('abort', onAbort, { once: true })
+      wallTimer.current = setTimeout(() => {
+        finish(() => output.failure(logs, { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` }))
+      }, this.config.maxWallMs)
+      this.live.add(live)
+      if (request.signal?.aborted === true) {
+        onAbort()
+        return
+      }
+      sendReply({
+        type: 'boot',
+        code,
+        namespaces: [...bindings].map(([global, namespace]) => ({
+          global,
+          names: Object.keys(namespace.functions),
+          ...namespace.errorClass === undefined ? {} : { errorClass: namespace.errorClass },
+        })),
+        computeMs: this.config.computeMs,
+        maxOutputBytes: this.config.maxOutputBytes,
+        maxOldGenerationSizeMb: this.config.maxOldGenerationSizeMb,
+      })
+    })
+  }
+
+  /* jscpd:ignore-start -- Code-runtime backends share the service lifecycle but own different child identities. */
+  private async teardown(): Promise<void> {
+    this.disposed = true
+    const runs = [...this.live]
+    for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
+    await Promise.all(runs.map(run => run.finished))
+  }
+  /* jscpd:ignore-end */
+}
+
+export default E2BCodeRuntime
diff --git a/packages/code-runtime/code-runtime-e2b/src/invariant.ts b/packages/code-runtime/code-runtime-e2b/src/invariant.ts
new file mode 100644
index 0000000000..4112cdc76b
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/src/invariant.ts
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-code-runtime-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-code-runtime-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'code-runtime-e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the service owns every one-shot remote run. */
+const install: InvariantInstaller = () => {}
+
+/** Register this package's invariant companion. */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/code-runtime/code-runtime-e2b/src/runner-source.ts b/packages/code-runtime/code-runtime-e2b/src/runner-source.ts
new file mode 100644
index 0000000000..b0355f20ce
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/src/runner-source.ts
@@ -0,0 +1,460 @@
+/** Dependency-free remote code runner installed inside the E2B sandbox. */
+
+/** Node program that runs one model program in a fresh remote worker thread. */
+export const CODE_RUNNER_SOURCE = String.raw`import { Buffer } from 'node:buffer'
+import { inspect } from 'node:util'
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { createInterface } from 'node:readline'
+
+const emitFrame = message => {
+  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
+}
+
+const parseFrame = line => JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
+
+if (isMainThread) {
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  let worker
+  let finished = false
+  let computeTimer
+  const finish = message => {
+    if (finished) return
+    finished = true
+    clearInterval(computeTimer)
+    emitFrame(message)
+    const current = worker
+    worker = undefined
+    Promise.resolve(current ? current.terminate() : undefined).finally(() => {
+      input.close()
+      process.stdin.destroy()
+    })
+  }
+  input.on('line', line => {
+    let message
+    try {
+      message = parseFrame(line)
+    } catch (error) {
+      process.stderr.write('code-runtime-e2b frame error: ' + String(error) + '\n')
+      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
+      return
+    }
+    if (!worker) {
+      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces)) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        return
+      }
+      worker = new Worker(new URL(import.meta.url), {
+        workerData: message,
+        env: {},
+        stdout: true,
+        stderr: true,
+        resourceLimits: { maxOldGenerationSizeMb: message.maxOldGenerationSizeMb },
+      })
+      worker.stdout.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
+      worker.stderr.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
+      worker.on('message', raw => {
+        if (!raw || typeof raw !== 'object') return
+        if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
+          emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
+        } else if (raw.type === 'log' && typeof raw.text === 'string') {
+          emitFrame({ type: 'log', text: raw.text })
+        } else if (raw.type === 'output-limit') {
+          finish({ type: 'output-limit' })
+        } else if (raw.type === 'done') {
+          if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
+            finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
+          } else if (raw.value === undefined || Array.isArray(raw.value)) {
+            finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
+          }
+        }
+      })
+      worker.on('error', error => {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker error: ' + error.message } })
+      })
+      worker.on('exit', code => {
+        if (!finished) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker exited with code ' + code + ' before completing' } })
+      })
+      computeTimer = setInterval(() => {
+        if (!worker) return
+        if (worker.performance.eventLoopUtilization().active > message.computeMs) {
+          finish({ type: 'done', error: { kind: 'timeout', message: 'compute budget exhausted (' + message.computeMs + 'ms busy)' } })
+        }
+      }, 25)
+      return
+    }
+    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
+      worker.postMessage(message.ok
+        ? { type: 'reply', id: message.id, ok: true, value: message.value }
+        : { type: 'reply', id: message.id, ok: false, message: String(message.message) })
+    }
+  })
+  input.on('close', () => { if (worker && !finished) void worker.terminate() })
+} else {
+  const port = parentPort
+  if (!port) throw new Error('remote worker requires parentPort')
+
+  const CapturedError = Error
+  const ArrayIsArray = Array.isArray
+  const ArrayPrototype = Array.prototype
+  const ObjectPrototype = Object.prototype
+  const ObjectCreate = Object.create
+  const ObjectDefineProperty = Object.defineProperty
+  const ObjectGetPrototypeOf = Object.getPrototypeOf
+  const ObjectHasOwn = Object.hasOwn
+  const ObjectKeys = Object.keys
+  const ObjectIs = Object.is
+  const ObjectPropertyIsEnumerable = Object.prototype.propertyIsEnumerable
+  const ReflectOwnKeys = Reflect.ownKeys
+  const ReflectApply = Reflect.apply
+  const NumberIsFinite = Number.isFinite
+  const NumberIsSafeInteger = Number.isSafeInteger
+  const PromiseCtor = Promise
+  const PromiseReject = Promise.reject
+  const QueueMicrotask = queueMicrotask
+  const BufferByteLength = Buffer.byteLength
+  const SetCtor = Set
+  const SetAdd = Set.prototype.add
+  const SetDelete = Set.prototype.delete
+  const SetHas = Set.prototype.has
+  const MapDelete = Map.prototype.delete
+  const MapGet = Map.prototype.get
+  const MapSet = Map.prototype.set
+  const ArrayJoin = Array.prototype.join
+  const ArrayPop = Array.prototype.pop
+  const StringCharCodeAt = String.prototype.charCodeAt
+  const StringSlice = String.prototype.slice
+  const JSONStringify = JSON.stringify
+  const StringValue = String
+
+  const define = (target, key, value) => {
+    const descriptor = ObjectCreate(null)
+    descriptor.value = value
+    descriptor.enumerable = true
+    descriptor.configurable = true
+    descriptor.writable = true
+    ObjectDefineProperty(target, key, descriptor)
+  }
+  const append = (target, value) => { define(target, target.length, value) }
+  const pop = target => ReflectApply(ArrayPop, target, [])
+  const setAdd = (target, value) => { ReflectApply(SetAdd, target, [value]) }
+  const setDelete = (target, value) => { ReflectApply(SetDelete, target, [value]) }
+  const setHas = (target, value) => ReflectApply(SetHas, target, [value])
+  const mapDelete = (target, key) => { ReflectApply(MapDelete, target, [key]) }
+  const mapGet = (target, key) => ReflectApply(MapGet, target, [key])
+  const mapSet = (target, key, value) => { ReflectApply(MapSet, target, [key, value]) }
+  const plainObject = value => {
+    const prototype = ObjectGetPrototypeOf(value)
+    return prototype === null || prototype === ObjectPrototype
+  }
+  const ownEnumerableStringKeys = value => {
+    const keys = ReflectOwnKeys(value)
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index]
+      if (typeof key !== 'string' || !ReflectApply(ObjectPropertyIsEnumerable, value, [key])) return undefined
+    }
+    return keys
+  }
+  const assign = (destination, value) => {
+    if (destination.kind === 'root') destination.holder.value = value
+    else define(destination.target, destination.key, value)
+  }
+  const snapshot = input => {
+    const active = new SetCtor()
+    const holder = ObjectCreate(null)
+    const tasks = [{ kind: 'visit', value: input, destination: { kind: 'root', holder } }]
+    while (tasks.length) {
+      const task = pop(tasks)
+      if (task.kind === 'leave') { setDelete(active, task.source); continue }
+      const candidate = task.value
+      if (candidate === null || typeof candidate === 'boolean' || typeof candidate === 'string') {
+        assign(task.destination, candidate); continue
+      }
+      if (typeof candidate === 'number') {
+        if (!NumberIsFinite(candidate) || ObjectIs(candidate, -0)) return undefined
+        assign(task.destination, candidate); continue
+      }
+      if (typeof candidate !== 'object' || setHas(active, candidate)) return undefined
+      if (ArrayIsArray(candidate)) {
+        if (ObjectGetPrototypeOf(candidate) !== ArrayPrototype || ReflectOwnKeys(candidate).length !== candidate.length + 1) return undefined
+        const target = []
+        assign(task.destination, target)
+        setAdd(active, candidate)
+        append(tasks, { kind: 'leave', source: candidate })
+        for (let index = candidate.length - 1; index >= 0; index--) {
+          if (!ObjectHasOwn(candidate, index)) return undefined
+          append(tasks, { kind: 'visit', value: candidate[index], destination: { kind: 'slot', target, key: index } })
+        }
+        continue
+      }
+      if (!plainObject(candidate)) return undefined
+      const keys = ownEnumerableStringKeys(candidate)
+      if (!keys) return undefined
+      const target = {}
+      assign(task.destination, target)
+      setAdd(active, candidate)
+      append(tasks, { kind: 'leave', source: candidate })
+      for (let index = keys.length - 1; index >= 0; index--) {
+        const key = keys[index]
+        append(tasks, { kind: 'visit', value: candidate[key], destination: { kind: 'slot', target, key } })
+      }
+    }
+    return holder.value
+  }
+  const encodeWire = value => {
+    const wire = []
+    const pending = [value]
+    while (pending.length) {
+      const current = pop(pending)
+      if (current === null || typeof current === 'boolean' || typeof current === 'number' || typeof current === 'string') {
+        append(wire, current); continue
+      }
+      if (ArrayIsArray(current)) {
+        append(wire, { kind: 'array', length: current.length })
+        for (let index = current.length - 1; index >= 0; index--) append(pending, current[index])
+      } else {
+        const keys = ObjectKeys(current)
+        append(wire, { kind: 'object', keys })
+        for (let index = keys.length - 1; index >= 0; index--) append(pending, current[keys[index]])
+      }
+    }
+    return wire
+  }
+  const decodeWire = wire => {
+    if (!ArrayIsArray(wire) || wire.length === 0) return undefined
+    const frames = []
+    let root
+    let assigned = false
+    const attach = value => {
+      const parent = frames[frames.length - 1]
+      if (!parent) {
+        if (assigned) return false
+        root = value; assigned = true; return true
+      }
+      if (parent.kind === 'array') append(parent.target, value)
+      else define(parent.target, parent.keys[parent.index], value)
+      parent.index += 1
+      return true
+    }
+    for (let tokenIndex = 0; tokenIndex < wire.length; tokenIndex++) {
+      const token = wire[tokenIndex]
+      let value
+      let frame
+      if (token === null || typeof token === 'boolean' || typeof token === 'string') value = token
+      else if (typeof token === 'number') {
+        if (!NumberIsFinite(token) || ObjectIs(token, -0)) return undefined
+        value = token
+      } else {
+        if (!plainObject(token)) return undefined
+        const keys = ownEnumerableStringKeys(token)
+        if (!keys || keys.length !== 2 || keys[0] !== 'kind') return undefined
+        if (token.kind === 'array' && keys[1] === 'length' && NumberIsSafeInteger(token.length) && token.length >= 0) {
+          value = []
+          if (token.length > wire.length - tokenIndex - 1) return undefined
+          if (token.length) frame = { kind: 'array', target: value, length: token.length, index: 0 }
+        } else if (token.kind === 'object' && keys[1] === 'keys' && ArrayIsArray(token.keys)) {
+          const unique = new SetCtor()
+          const objectKeys = []
+          for (const key of token.keys) {
+            if (typeof key !== 'string' || setHas(unique, key)) return undefined
+            setAdd(unique, key); append(objectKeys, key)
+          }
+          if (objectKeys.length > wire.length - tokenIndex - 1) return undefined
+          value = {}
+          if (objectKeys.length) frame = { kind: 'object', target: value, keys: objectKeys, index: 0 }
+        } else return undefined
+      }
+      if (!attach(value)) return undefined
+      if (frame) append(frames, frame)
+      while (frames.length) {
+        const current = frames[frames.length - 1]
+        const length = current.kind === 'array' ? current.length : current.keys.length
+        if (current.index < length) break
+        pop(frames)
+      }
+    }
+    return frames.length === 0 ? root : undefined
+  }
+  const byteLength = text => ReflectApply(BufferByteLength, Buffer, [text])
+  const jsonStringBytes = text => byteLength(JSONStringify(text))
+  const jsonValueBytes = value => {
+    let bytes = 0
+    const tasks = [{ kind: 'value', value }]
+    while (tasks.length) {
+      const task = pop(tasks)
+      if (task.kind === 'separator') { bytes += 1; continue }
+      if (task.kind === 'key') { bytes += jsonStringBytes(task.value) + 1; continue }
+      const current = task.value
+      if (current === null) bytes += 4
+      else if (typeof current === 'string') bytes += jsonStringBytes(current)
+      else if (typeof current === 'number' || typeof current === 'boolean') bytes += byteLength(StringValue(current))
+      else if (ArrayIsArray(current)) {
+        bytes += 2
+        for (let index = current.length - 1; index >= 0; index--) {
+          append(tasks, { kind: 'value', value: current[index] })
+          if (index > 0) append(tasks, { kind: 'separator' })
+        }
+      } else {
+        bytes += 2
+        const keys = ObjectKeys(current)
+        for (let index = keys.length - 1; index >= 0; index--) {
+          const key = keys[index]
+          append(tasks, { kind: 'value', value: current[key] })
+          append(tasks, { kind: 'key', value: key })
+          if (index > 0) append(tasks, { kind: 'separator' })
+        }
+      }
+    }
+    return bytes
+  }
+  const truncate = (text, available) => {
+    if (available < 2) return ''
+    let result = ''
+    let bytes = 2
+    let index = 0
+    while (index < text.length) {
+      const first = ReflectApply(StringCharCodeAt, text, [index])
+      let end = index + 1
+      if (first >= 0xd800 && first <= 0xdbff && end < text.length) {
+        const second = ReflectApply(StringCharCodeAt, text, [end])
+        if (second >= 0xdc00 && second <= 0xdfff) end += 1
+      }
+      const character = ReflectApply(StringSlice, text, [index, end])
+      const cost = jsonStringBytes(character) - 2
+      if (bytes + cost > available) break
+      bytes += cost
+      result += character
+      index = end
+    }
+    return result
+  }
+  let logBytes = 2
+  let logEntries = 0
+  let limited = false
+  const pushLog = text => {
+    if (limited) return
+    const separator = logEntries > 0 ? 1 : 0
+    const available = workerData.maxOutputBytes - logBytes - separator
+    const cost = jsonStringBytes(text)
+    if (cost > available) {
+      const prefix = truncate(text, available)
+      if (prefix) {
+        logBytes += jsonStringBytes(prefix) + separator
+        logEntries += 1
+        port.postMessage({ type: 'log', text: prefix })
+      }
+      limited = true
+      port.postMessage({ type: 'output-limit' })
+      return
+    }
+    logBytes += cost + separator
+    logEntries += 1
+    port.postMessage({ type: 'log', text })
+  }
+  const originalStdout = process.stdout.write
+  const originalStderr = process.stderr.write
+  process.stdout.write = (chunk, ...rest) => {
+    pushLog(typeof chunk === 'string' ? chunk : StringValue(chunk))
+    let callback
+    for (let index = 0; index < rest.length; index++) {
+      if (typeof rest[index] === 'function') { callback = rest[index]; break }
+    }
+    if (callback) QueueMicrotask(() => { callback(null) })
+    return true
+  }
+  process.stderr.write = process.stdout.write
+  const consoleShim = ObjectCreate(null)
+  for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
+    define(consoleShim, level, (...args) => {
+      const rendered = []
+      for (let index = 0; index < args.length; index++) {
+        const value = args[index]
+        append(rendered, typeof value === 'string' ? value : inspect(value, { depth: 4, maxArrayLength: 100, maxStringLength: 10000 }))
+      }
+      pushLog(ReflectApply(ArrayJoin, rendered, [' ']))
+    })
+  }
+  const pending = new Map()
+  let nextId = 1
+  const errorClasses = new Map()
+  for (const namespace of workerData.namespaces) {
+    if (!namespace.errorClass) continue
+    const descriptor = namespace.errorClass
+    mapSet(errorClasses, namespace.global, class BindingCallError extends CapturedError {
+      constructor(memberName, message) {
+        super(message)
+        ObjectDefineProperty(this, 'name', { value: descriptor.name, enumerable: true })
+        ObjectDefineProperty(this, descriptor.memberNameProperty, { value: memberName, enumerable: true })
+      }
+    })
+  }
+  port.on('message', message => {
+    if (!message || message.type !== 'reply' || typeof message.id !== 'number') return
+    const entry = mapGet(pending, message.id)
+    if (!entry) return
+    mapDelete(pending, message.id)
+    if (!message.ok) { entry.reject(new CapturedError(StringValue(message.message))); return }
+    const value = decodeWire(message.value)
+    if (value === undefined) entry.reject(new CapturedError('binding resolution must be lossless JSON'))
+    else entry.resolve(value)
+  })
+  const namespaces = workerData.namespaces.map(namespace => {
+    const target = ObjectCreate(null)
+    const ErrorClass = mapGet(errorClasses, namespace.global)
+    for (const name of namespace.names) {
+      define(target, name, args => {
+        const detached = snapshot(args)
+        if (detached === undefined) {
+          return ReflectApply(PromiseReject, PromiseCtor, [ErrorClass ? new ErrorClass(name, 'binding arguments must be lossless JSON') : new CapturedError('binding arguments must be lossless JSON')])
+        }
+        return new PromiseCtor((resolve, reject) => {
+          const id = nextId++
+          mapSet(pending, id, {
+            resolve,
+            reject: error => { reject(ErrorClass ? new ErrorClass(name, error.message) : error) },
+          })
+          port.postMessage({ type: 'call', id, global: namespace.global, name, args: encodeWire(detached) })
+        })
+      })
+    }
+    return target
+  })
+  const errorClassNames = []
+  const errorClassValues = []
+  for (const namespace of workerData.namespaces) {
+    if (!namespace.errorClass) continue
+    append(errorClassNames, namespace.errorClass.name)
+    append(errorClassValues, mapGet(errorClasses, namespace.global))
+  }
+  const AsyncFunction = ObjectGetPrototypeOf(async function () {}).constructor
+  try {
+    const fn = new AsyncFunction(...workerData.namespaces.map(value => value.global), ...errorClassNames, 'console', '"use strict";\n' + workerData.code)
+    const value = await fn(...namespaces, ...errorClassValues, consoleShim)
+    if (!limited) {
+      if (value === undefined) port.postMessage({ type: 'done' })
+      else {
+        const detached = snapshot(value)
+        if (detached === undefined) {
+          const message = 'program completion must be lossless JSON'
+          if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
+          else port.postMessage({ type: 'done', error: { kind: 'invalid-output', message } })
+        } else if (jsonValueBytes(detached) > workerData.maxOutputBytes - logBytes) {
+          port.postMessage({ type: 'output-limit' })
+        } else {
+          port.postMessage({ type: 'done', value: encodeWire(detached) })
+        }
+      }
+    }
+  } catch (error) {
+    if (!limited) {
+      let message
+      try { message = error instanceof CapturedError ? error.stack || error.message : StringValue(error) }
+      catch { message = 'program threw an unrenderable value' }
+      if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
+      else port.postMessage({ type: 'done', error: { kind: 'exception', message } })
+    }
+  } finally {
+    process.stdout.write = originalStdout
+    process.stderr.write = originalStderr
+  }
+}
+`
diff --git a/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
new file mode 100644
index 0000000000..ff1c5dd84a
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
@@ -0,0 +1,460 @@
+import { PassThrough, Writable } from 'node:stream'
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+import {
+  E2BFrameDecoder,
+  encodeE2BFrame,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import {
+  encodeWorkerJson,
+} from '@deepseek-ai/dsh-code-runtime-worker'
+import E2BCodeRuntime from '@deepseek-ai/dsh-code-runtime-e2b'
+import * as E2BCodeRuntimeInvariant from '../src/invariant.ts'
+import { CODE_RUNNER_SOURCE } from '../src/runner-source.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+class FakeHandle implements SubprocessHandle {
+  readonly pid = 123
+  readonly stdin: Writable | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr = undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+  readonly writes: unknown[] = []
+  readonly result = Promise.withResolvers<SubprocessOutcome>()
+  terminated = 0
+  waitCalls = 0
+  private readonly decoder = new E2BFrameDecoder(10_000_000)
+  private readonly waitError: Error | undefined
+  private settled = false
+
+  constructor(
+    private readonly onMessage: (message: unknown, handle: FakeHandle) => void = () => {},
+    options: { stdin?: boolean; stdout?: boolean; stderr?: string; writeError?: Error; waitError?: Error } = {},
+  ) {
+    this.waitError = options.waitError
+    this.stdin = options.stdin === false
+      ? undefined
+      : options.writeError === undefined
+        ? new PassThrough()
+        : new Writable({ write: (_chunk, _encoding, callback) => { callback(options.writeError) } })
+    this.stdout = options.stdout === false ? undefined : new PassThrough()
+    this.collected = options.stderr === undefined
+      ? {}
+      : { stderr: { readFrom: () => ({ text: options.stderr as string, nextOffset: 0, lossy: false }) } }
+    this.done = this.result.promise
+    this.stdin?.on('data', (chunk: Buffer) => {
+      for (const message of this.decoder.push(chunk.toString('ascii'))) {
+        this.writes.push(message)
+        this.onMessage(message, this)
+      }
+    })
+  }
+
+  emit(message: unknown): void {
+    this.stdout?.write(encodeE2BFrame(message))
+  }
+
+  emitRaw(text: string): void {
+    this.stdout?.write(text)
+  }
+
+  exit(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
+    if (this.settled) return
+    this.settled = true
+    this.stdout?.end()
+    this.result.resolve(outcome)
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.stdout?.end()
+    this.result.reject(error)
+  }
+
+  terminate(): void {
+    this.terminated += 1
+    this.exit({ exitCode: null, signal: 'SIGTERM' })
+  }
+
+  async waitForExit(): Promise<boolean> {
+    this.waitCalls += 1
+    if (this.waitError !== undefined) throw this.waitError
+    return true
+  }
+}
+
+interface RuntimeFixture {
+  ctx: Context
+  fiber: Awaited<ReturnType<Context['plugin']>>
+  runtime: E2BCodeRuntime
+  sandbox: Sandbox
+  spawn: ReturnType<typeof vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>>
+  write: ReturnType<typeof vi.fn>
+  run: ReturnType<typeof vi.fn>
+}
+
+async function setup(
+  handles: FakeHandle[] = [],
+  config: Record<string, number> = {},
+  sandboxOverrides: Partial<Sandbox> = {},
+  getSandbox?: () => Promise<Sandbox>,
+): Promise<RuntimeFixture> {
+  const write = vi.fn().mockResolvedValue([])
+  const run = vi.fn().mockImplementation(async (command: string) => ({
+    exitCode: 0,
+    stdout: command.startsWith('command -v') ? '/usr/bin/node\n' : '',
+    stderr: '',
+  }))
+  const sandbox = {
+    files: { write },
+    commands: { run },
+    ...sandboxOverrides,
+  } as unknown as Sandbox
+  const e2b = {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    getSandbox: getSandbox ?? (async () => sandbox),
+  } as unknown as E2BSandboxService
+  const spawn = vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>(() => {
+    const handle = handles.shift()
+    if (handle === undefined) throw new Error('no fake handle queued')
+    return handle
+  })
+  const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+  Object.defineProperty(subprocess, 'spawn', { value: spawn })
+  const ctx = new Context()
+  ctx.provide('e2b', e2b)
+  ctx.provide('subprocess', subprocess)
+  const fiber = await ctx.plugin(E2BCodeRuntime, config)
+  return { ctx, fiber, runtime: ctx.codeRuntime as E2BCodeRuntime, sandbox, spawn, write, run }
+}
+
+function request(program = 'return 1') {
+  return { program, bindings: [] }
+}
+
+describe('E2BCodeRuntime', () => {
+  it('prepares the remote runner and returns logs and a lossless completion', async () => {
+    const handle = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type !== 'boot') return
+      current.emit({ type: 'log', text: 'remote 你好' })
+      current.emitRaw(
+        encodeE2BFrame({ type: 'done', value: encodeWorkerJson({ answer: 42 }) })
+        + encodeE2BFrame({ type: 'log', text: 'ignored after done' }),
+      )
+      current.emit({ type: 'log', text: 'also ignored after done' })
+    })
+    const fixture = await setup([handle])
+
+    await expect(fixture.runtime.run(request('const answer: number = 42; return { answer }')))
+      .resolves.toEqual({ logs: ['remote 你好'], value: { answer: 42 } })
+    expect(fixture.runtime.language).toBe('typescript')
+    expect(fixture.runtime.isolation).toBe('container')
+    expect(fixture.write).toHaveBeenCalledWith([{ path: '/workspace/.dsh-e2b/code-runtime-runner.mjs', data: CODE_RUNNER_SOURCE }])
+    expect(fixture.run).toHaveBeenCalledWith("chmod 600 -- '/workspace/.dsh-e2b/code-runtime-runner.mjs'")
+    expect(fixture.spawn).toHaveBeenCalledWith(expect.objectContaining({
+      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/code-runtime-runner.mjs'],
+      cwd: '/workspace',
+      env: {},
+    }))
+    expect(handle.terminated).toBe(1)
+    expect(handle.waitCalls).toBe(1)
+    await fixture.fiber.dispose()
+  })
+
+  it('bridges binding success, host rejection, unknown members, and invalid values', async () => {
+    const replies: unknown[] = []
+    const handle = new FakeHandle((message, current) => {
+      const record = message as { type?: string; id?: number; ok?: boolean }
+      if (record.type === 'boot') {
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 4 }) })
+        current.emit({ type: 'call', id: 2, global: 'bridge', name: 'fail', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 3, global: 'bridge', name: 'missing', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 4, global: 'bridge', name: 'double', args: [] })
+        current.emit({ type: 'call', id: 5, global: 'bridge', name: 'invalid', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 6, global: 'bridge', name: 'throwing', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 99 }) })
+        return
+      }
+      if (record.type === 'reply') {
+        replies.push(message)
+        if (replies.length === 6) current.emit({ type: 'done', value: encodeWorkerJson('done') })
+      }
+    })
+    const fixture = await setup([handle])
+    const result = await fixture.runtime.run({
+      program: 'return await bridge.double({ value: 4 })',
+      bindings: [
+        {
+          global: 'bridge',
+          errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
+          functions: {
+            double: async args => (args as { value: number }).value * 2,
+            fail: async () => { throw 'nope' },
+            invalid: (async () => undefined) as never,
+            throwing: async () => Object.defineProperty({}, 'value', {
+              enumerable: true,
+              get: () => { throw new Error('getter failed') },
+            }),
+          },
+        },
+        { global: 'plain', functions: {} },
+      ],
+    })
+
+    expect(result).toEqual({ logs: [], value: 'done' })
+    expect(replies.sort((left, right) => (left as { id: number }).id - (right as { id: number }).id)).toEqual([
+      { type: 'reply', id: 1, ok: true, value: encodeWorkerJson(8) },
+      { type: 'reply', id: 2, ok: false, message: 'nope' },
+      { type: 'reply', id: 3, ok: false, message: 'unknown binding "bridge.missing"' },
+      { type: 'reply', id: 4, ok: false, message: 'binding arguments must be lossless JSON' },
+      { type: 'reply', id: 5, ok: false, message: 'binding resolution must be lossless JSON' },
+      { type: 'reply', id: 6, ok: false, message: 'binding resolution must be lossless JSON' },
+    ])
+    await fixture.fiber.dispose()
+  })
+
+  it('ignores malformed runner traffic and classifies terminal runner messages', async () => {
+    const ignored = [
+      null, 1, {}, { type: 'log' }, { type: 'call' },
+      { type: 'call', id: 0, global: 'x', name: 'y', args: [] },
+      { type: 'call', id: 1, global: 1, name: 'y', args: [] },
+      { type: 'call', id: 1, global: 'x', name: 1, args: [] },
+      { type: 'call', id: 1, global: 'x', name: 'y', args: {} },
+      { type: 'done', error: null },
+      { type: 'done', error: { kind: 'invented', message: 'x' } },
+      { type: 'done', error: { kind: 'exception', message: 1 } },
+    ]
+    const handles = [
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type !== 'boot') return
+        for (const item of ignored) current.emit(item)
+        current.emit({ type: 'done' })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', error: { kind: 'exception', message: 'boom' } })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', value: [] })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'output-limit' })
+      }),
+    ]
+    const fixture = await setup(handles, { maxOutputBytes: 64, maxFrameBytes: 128 })
+
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [] })
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'exception', message: 'boom' } })
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
+    await fixture.fiber.dispose()
+  })
+
+  it('enforces the host output ledger and catches malformed bridge output', async () => {
+    const handles = [
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'log', text: 'x'.repeat(1_000) })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emitRaw('not-base64\n')
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emitRaw('é')
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.stdout?.emit('error', new Error('stdout broke'))
+      }),
+    ]
+    const fixture = await setup(handles, { maxOutputBytes: 128, maxFrameBytes: 4_096 })
+
+    expect((await fixture.runtime.run(request())).error?.kind).toBe('output-limit')
+    const malformed = (await fixture.runtime.run(request())).error
+    expect(malformed?.kind).toBe('worker-exit')
+    expect(malformed?.message).toContain('bridge failed')
+    expect((await fixture.runtime.run(request())).error?.message).toContain('non-ASCII')
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdout failed: stdout broke' })
+    await fixture.fiber.dispose()
+  })
+
+  it('contains stdin errors, process exits, spawn failures, and missing pipes', async () => {
+    const writeError = new FakeHandle(() => {}, { writeError: new Error('write callback broke') })
+    const stdinError = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') current.stdin?.emit('error', new Error('stdin broke'))
+    })
+    const earlyExit = new FakeHandle(() => {}, { stderr: 'remote diagnostic' })
+    const quietExit = new FakeHandle()
+    const emptyStderrExit = new FakeHandle(() => {}, { stderr: '' })
+    const spawnFailure = new FakeHandle()
+    const missingStdin = new FakeHandle(() => {}, { stdin: false })
+    const missingStdout = new FakeHandle(() => {}, { stdout: false, waitError: new Error('missing-stream process query failed') })
+    const truncated = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') {
+        current.emitRaw('YQ==')
+        setImmediate(() => { current.exit() })
+      }
+    })
+    const cleanupFailure = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
+    }, { waitError: new Error('process query failed') })
+    const fixture = await setup([
+      writeError, stdinError, earlyExit, quietExit, emptyStderrExit,
+      spawnFailure, missingStdin, missingStdout, truncated, cleanupFailure,
+    ])
+
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime bridge write failed: write callback broke' })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdin failed: stdin broke' })
+    setImmediate(() => { earlyExit.exit() })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing: remote diagnostic' })
+    setImmediate(() => { quietExit.exit() })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
+    setImmediate(() => { emptyStderrExit.exit() })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
+    setImmediate(() => { spawnFailure.crash('spawn rejected') })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime spawn failed: spawn rejected' })
+    expect((await fixture.runtime.run(request())).error?.message).toContain('dropped a piped runtime stream')
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: missing-stream process query failed' })
+    expect(missingStdin.terminated).toBe(1)
+    expect(missingStdin.waitCalls).toBe(1)
+    expect(missingStdout.terminated).toBe(1)
+    expect(missingStdout.waitCalls).toBe(1)
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B frame stream ended mid-frame' })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: process query failed' })
+    await fixture.fiber.dispose()
+  })
+
+  it('reports wall timeout, abort, pre-abort, type-strip failure, and disposal', async () => {
+    const timeout = new FakeHandle()
+    const abort = new FakeHandle()
+    const disposing = new FakeHandle()
+    const fixture = await setup([timeout, abort, disposing], { maxWallMs: 20 })
+
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'timeout', message: 'wall-clock ceiling reached (20ms)' })
+    const controller = new AbortController()
+    const aborting = fixture.runtime.run({ ...request(), signal: controller.signal })
+    controller.abort('stop')
+    expect((await aborting).error).toEqual({ kind: 'abort', message: 'stop' })
+    expect((await fixture.runtime.run({ ...request(), signal: AbortSignal.abort('already') })).error)
+      .toEqual({ kind: 'abort', message: 'already' })
+    expect((await fixture.runtime.run(request('enum E { A }'))).error?.kind).toBe('exception')
+
+    const live = fixture.runtime.run(request())
+    await new Promise(resolve => setImmediate(resolve))
+    await fixture.fiber.dispose()
+    expect((await live).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+    await expect(fixture.runtime.run(request())).rejects.toThrow('after disposal')
+  })
+
+  it('drops binding replies that settle after abort', async () => {
+    const controller = new AbortController()
+    const resolution = Promise.withResolvers<string>()
+    const invoked = Promise.withResolvers<undefined>()
+    const handle = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') {
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'late', args: encodeWorkerJson(null) })
+      }
+    })
+    const fixture = await setup([handle])
+    const running = fixture.runtime.run({
+      program: 'return await bridge.late(null)',
+      bindings: [{
+        global: 'bridge',
+        functions: {
+          late: async () => {
+            invoked.resolve(undefined)
+            return await resolution.promise
+          },
+        },
+      }],
+      signal: controller.signal,
+    })
+    await invoked.promise
+    controller.abort('stop')
+    expect((await running).error).toEqual({ kind: 'abort', message: 'stop' })
+    resolution.resolve('late')
+    await new Promise(resolve => setImmediate(resolve))
+    expect(handle.writes).toHaveLength(1)
+    await fixture.fiber.dispose()
+  })
+
+  it('validates binding and runtime configuration before remote execution', async () => {
+    const fixture = await setup([])
+    const invalidRequests = [
+      { global: 'not-valid!', functions: {} },
+      { global: 'await', functions: {} },
+      { global: 'console', functions: {} },
+      { global: 'same', functions: {} },
+      { global: 'same', functions: {} },
+      { global: 'ok', functions: {}, errorClass: { name: 'not-valid!', memberNameProperty: 'member' } },
+      { global: 'ok', functions: {}, errorClass: { name: 'await', memberNameProperty: 'member' } },
+      { global: 'Clash', functions: {}, errorClass: { name: 'Clash', memberNameProperty: 'member' } },
+      { global: 'one', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
+      { global: 'two', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
+      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: '' } },
+      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'message' } },
+    ]
+    for (const bindings of [
+      [invalidRequests[0]], [invalidRequests[1]], [invalidRequests[2]],
+      invalidRequests.slice(3, 5), [invalidRequests[5]], [invalidRequests[6]],
+      [invalidRequests[7]], invalidRequests.slice(8, 10), [invalidRequests[10]], [invalidRequests[11]],
+    ]) {
+      await expect(fixture.runtime.run({ program: 'return 1', bindings: bindings as never })).rejects.toThrow()
+    }
+    await fixture.fiber.dispose()
+
+    for (const config of [
+      { computeMs: 0 }, { computeMs: 1.5 }, { maxOutputBytes: 3 },
+      { maxWallMs: 2_147_483_648 }, { maxFrameBytes: 10, maxOutputBytes: 20 },
+    ]) {
+      const ctx = new Context()
+      const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+      ctx.provide('e2b', { getSandbox: async () => ({}) } as never)
+      ctx.provide('subprocess', subprocess)
+      await expect(ctx.plugin(E2BCodeRuntime, config)).rejects.toThrow()
+    }
+
+    const wrong = new Context()
+    wrong.provide('e2b', { getSandbox: async () => ({}) } as never)
+    wrong.provide('subprocess', {} as never)
+    await expect(wrong.plugin(E2BCodeRuntime, {})).rejects.toThrow('dsh-subprocess-e2b')
+  })
+
+  it('turns asynchronous runtime preparation failure into a run result', async () => {
+    const sandbox = {
+      files: { write: vi.fn().mockRejectedValue(new Error('upload failed')) },
+      commands: { run: vi.fn() },
+    } as unknown as Sandbox
+    const fixture = await setup([], {}, sandbox)
+    expect((await fixture.runtime.run(request())).error).toEqual({
+      kind: 'worker-exit',
+      message: 'E2B runtime setup failed: upload failed',
+    })
+    await fixture.fiber.dispose()
+  })
+
+  it('returns disposal when remote preparation completes after teardown', async () => {
+    const gate = Promise.withResolvers<Sandbox>()
+    const fixture = await setup([], {}, {}, () => gate.promise)
+    const running = fixture.runtime.run(request())
+    await (fixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
+    gate.resolve(fixture.sandbox)
+    expect((await running).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+    await fixture.fiber.dispose()
+  })
+
+  it('registers the package-owned invariant companion', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BCodeRuntimeInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/code-runtime/code-runtime-e2b/tsconfig.json b/packages/code-runtime/code-runtime-e2b/tsconfig.json
new file mode 100644
index 0000000000..4ddc3b5ffe
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../code-runtime" },
+    { "path": "../code-runtime-worker" },
+    { "path": "../../e2b/e2b" },
+    { "path": "../../core/session" },
+    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../../util/timeout" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index 8d3568e82e..d3472a697e 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
-README.md: 590b79dcd1bc322350060b55767b09c6305edacc
-README.zh.md: 12c25f892bd20892cb47e593f16b6aadd9ffa84c
+README.md: 4b14c6fad5d1e491faeb54c9cb0e4403c8e2d8dd
+README.zh.md: c522917835b562cf7648d8bc78f0315b7c52d2d2
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 590b79dcd1..4b14c6fad5 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -32,7 +32,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 ## The worker entry, unbuilt and built
 
-Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
+Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local JSON snapshotter is parity-tested against the session-owned canonical boundary; both sides flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. `tests/built-lib.e2e.ts` pins the real load path required by [docs/testing.md](../../../docs/testing.md).
 
 The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
 
@@ -46,8 +46,8 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.
-- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — amaro or sucrase are the named drop-in replacements if the relied-on behavior shifts.
+- **OS processes a program spawns survive this backend's termination** — `worker.terminate()` ends only the thread; deployments needing remote process-group cleanup can select the E2B backend, whose separate limitations still apply.
+- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
 - **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
 - **Intermediate binding values have no byte cap** — a program can exhaust process or worker memory with a value that never becomes outer output.
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index 12c25f892b..c522917835 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -23,18 +23,18 @@
 - **每次运行使用一个全新 worker，不设池化**：程序所在的世界会随 worker 一同终止，不会留下需要记录的跨运行状态，也无法发生状态泄漏；仅凭会话日志即可重建运行。
 - **在执行上下文中，由宿主侧剥离类型**：程序会包裹在异步函数外壳中，通过 `node:module` 的 `stripTypeScriptTypes` 剥离类型（只支持可擦除语法；`enum`／namespace 会作为程序 `exception` 被拒绝，且不会启动 worker），再按字节位置切回原内容。之后程序作为 `AsyncFunction` 的函数体执行，因此顶层 `await`／`return` 可用。
 - **端口把对端视为不可信**：模型代码能够访问 `parentPort` 并伪造通信，因此任何代码读取入站消息前，系统都会验证其形状并重新构建（`null`、原始值、无效类型和格式错误的载荷会被静默丢弃；伪造的额外字段绝不会被带入）；宿主对每个调用 id 最多响应一次，只将绑定名称解析为自有属性（伪造的 `constructor` 无法沿原型链访问），丢弃结算后的回复，并验证每个绑定 resolve 值与完成值是否为无损 JSON。伪造的 `log`／`done` 消息无法绕过外层上限：宿主会再次验证，并统计每条获准日志以及完成值或诊断。worker 侧命名空间使用 null-prototype 和 `defineProperty`，因此形似 `__proto__` 的绑定名称只是普通键。
-- **绑定调用被拒绝时使用的异常类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收调用失败的成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误 intrinsic 与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
-- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟限制为 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
-- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为自身嵌套深度有界的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
-- **日志主动流入一个外层账本**：console／stdout／stderr 文本按产生顺序经端口传输，因此超时或被终止的程序仍会显示已经打印的内容。worker 会精确统计 JSON 字符串的字节数，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
-- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既不会获得环境变量中的凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
-- **dispose（资源释放）时等待完全停稳**：清理会使进行中的运行以 `abort` 失败，并会等待每个 worker 退出后再完成。
+- **绑定 reject 类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收失败成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
+- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟夹到 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
+- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为有深度上限的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
+- **日志主动流入一个外层账本**：console／stdout／stderr 文本按发送顺序穿过端口，因此超时或被终止的程序仍会显示已经打印的内容。worker 会按 JSON 字符串精确计费，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
+- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既没有环境凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
+- **释放资源时等待完全停稳**：清理会把进行中的运行标记为 `abort`，并在 resolve 前等待每个 worker 退出。
 
 ## 未构建与已构建的 worker 入口
 
-源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口周围展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。演练这个已发布入口路径的仓库级要求由[测试策略](../../../docs/testing.md)规定。
+源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地 JSON 快照器会与会话自有的规范边界执行一致性测试；消息端口两侧都会展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的 VFS Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。`tests/built-lib.e2e.ts` 固定了 [docs/testing.md](../../../docs/testing.md) 要求的真实加载路径。
 
-SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Config`。运行所用的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
+SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
 
 ## 模型体验
 
@@ -42,13 +42,13 @@ SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Confi
 
 #### KV Cache 影响
 
-不会直接失效；由上述消费方负责请求前缀变更。
+不会直接失效；由具名消费方负责请求前缀变更。
 
-## 已知限制与暂缓事项
+## 已知限制与暂缓工作
 
-- **程序派生的 OS 进程在程序终止后仍会存活**：`worker.terminate()` 只结束线程，比 bash-local 的进程组终止更弱；在容器后端出现前，孤儿进程清理属于部署职责。
-- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：如依赖的行为发生变化，amaro 或 sucrase 是已经点名的直接替代品。
+- **程序 spawn 的 OS 进程在该后端终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理远程进程组的部署可以选择 E2B 后端，但该后端自身的限制仍然适用。
+- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：依赖的行为由单元测试固定；如其发生变化，amaro／sucrase 是已经点名的直接替代品。
 - **`computeMs` 到期最多可能超过一个轮询间隔**：系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
-- **程序获得一个含 5 个方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
+- **程序获得一个含 5 种方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
 - **中间绑定值没有字节上限**：程序可以用永远不会成为外层输出的值耗尽进程或 worker 内存。
 - **默认 64 MiB 是拒绝边界，不是可恢复存储**：外层落盘只能保存发生 `output-limit` 后返回的有界日志和诊断；在运行时上限之外被拒绝的字节永远不会到达落盘层。
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 43801899a2..2ece0b5c39 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -21,6 +21,10 @@ import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from
 import { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
 import type { WorkerJsonWire } from './worker-json.ts'
 
+export { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
+export { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
+export type { WorkerJsonWire } from './worker-json.ts'
+
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
   /**
@@ -165,14 +169,19 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
 }
 
 
-/** One run's combined outer-output ledger; binding values never enter it. */
-class OutputLedger {
+/** Shared outer-output accounting for one isolated run; binding values never enter it. */
+export class OutputLedger {
   private bytes = 2 // JSON serialization of the empty logs array: []
   private entries = 0
 
   constructor(private readonly maxBytes: number) {}
 
-  /** Admit one exact log entry, or report that the hard cap was crossed. */
+  /**
+   * Admit one exact log entry, or report that the hard cap was crossed.
+   * @param text - Candidate log entry.
+   * @param sink - Accepted log entries for the current run.
+   * @returns Whether the complete entry fits the remaining outer-output budget.
+   */
   admit(text: string, sink: string[]): boolean {
     const separatorBytes = this.entries > 0 ? 1 : 0
     const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
@@ -183,19 +192,33 @@ class OutputLedger {
     return true
   }
 
-  /** Finalize a successful absent-or-JSON completion against the combined cap. */
+  /**
+   * Finalize a successful absent-or-JSON completion against the combined cap.
+   * @param logs - Already accepted log entries.
+   * @param value - Optional lossless-JSON completion value.
+   * @returns A success result or an output-limit failure.
+   */
   success(logs: string[], value?: CodeJsonValue): CodeRunResult {
     if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, ...value !== undefined ? { value } : {} }
   }
 
-  /** Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap. */
+  /**
+   * Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap.
+   * @param logs - Already accepted log entries.
+   * @param error - Candidate failure diagnostic.
+   * @returns The diagnostic result or an output-limit failure.
+   */
   failure(logs: string[], error: CodeRunFailure): CodeRunResult {
     if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, error }
   }
 
-  /** Build the explicit output-limit failure while retaining a fitting prefix of the final log. */
+  /**
+   * Build the explicit output-limit failure while retaining a fitting prefix of the final log.
+   * @param logs - Candidate log entries in original order.
+   * @returns A capped output-limit result.
+   */
   limit(logs: string[]): CodeRunResult {
     const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
     // The fixed diagnostic is ASCII, so every character is one byte plus the quotes.
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index a6bd209c7b..51c1466872 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: 15fbcecf77b2318acf3b09101802cd032ae426d2
+README.md: c7690412d0f1bc8556fc758da4e94c6ce5a08d8f
+README.zh.md: ecfa48a97c46113c52f13c7a6edfc5d6fbbc2285
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index bb1c20d00a..4018cdf508 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
+- **Isolation is backend-specific** — the worker backend is process-local, while the E2B backend reports `container` and keeps orchestration and bindings on the host; the descriptor remains informational rather than a security claim.
 - **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index 15fbcecf77..ecfa48a97c 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -4,23 +4,21 @@
 
 这是**代码执行 seam**：抽象的 `CodeRuntime` 服务（`ctx.codeRuntime`）只定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
-此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
+此包是该能力的接口层（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。两者都由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有工具形状的内容都留在消费方。
 
 ## 服务 API（`ctx.codeRuntime`）
 
 | 成员 | 语义 |
 |---|---|
-| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
-| `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
+| `run(request)` | 针对请求的绑定执行一段程序。**每一种程序结果都通过 error 字段完成 resolve**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底死亡（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如资源释放后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
+| `language` | 只读描述符：`run` 期望的源语言（已知值为 `'typescript'`）。仅供参考，不作门禁；生成语言专用呈现的消费方会对该值执行分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为不可信对等方（任意绑定名称都是自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；资源释放会终止进行中的运行，并且在完成前等待其退出。
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
-
-binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收 reject 成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
 
 ## 模型体验
 
@@ -28,11 +26,11 @@ binding-global 与 error-class 名称是**语言可移植**的：必须匹配标
 
 #### KV Cache 影响
 
-不会直接失效；由上述消费方负责请求前缀变更。
+不会直接失效；由具名消费方负责请求前缀变更。
 
-## 已知限制与暂缓事项
+## 已知限制与暂缓工作
 
-- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
+- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供活跃程序输出的流式日志或进度接口。
 - **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
-- **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
+- **隔离方式由后端决定**：worker 后端位于宿主进程内，而 E2B 后端报告 `container`，并把编排与绑定留在宿主；该描述符仍只提供信息，不构成安全声明。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 1bc9761930..444145fbb8 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: 4b28ec7c0452189a579a6d7e0cd22a0b8561784d
-README.zh.md: ab254eecad82c05cd6a6021e7f8bc4eda6cf3076
+README.md: 9e7f1a98ada9f56f3d1e3f74d2a906f8a1c7bc15
+README.zh.md: 53fdf30eaf405ab5313274a7fadde0b044b7fba1
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index 4b28ec7c04..9e7f1a98ad 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -2,12 +2,15 @@
 
 English | [中文](README.zh.md)
 
-An experimental provider-composition POC that places the filesystem and managed subprocess world in one E2B Linux sandbox. The shared owner is separate from the capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
+An experimental provider-composition POC that places the mutable coding world in one E2B Linux sandbox. The shared owner is separate from capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
 | [`fs-e2b`](../fs/fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
+| [`pty-e2b`](../pty/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
+| [`lsp-e2b`](../lsp/lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
+| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it already delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world as `ctx.fs`. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, or E2B SDK buffers. The [decision record](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary and rejected expansion.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [base decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) and [runtime-extension decision](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) own the POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index ab254eecad..53fdf30eaf 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -2,12 +2,15 @@
 
 [English](README.md) | 中文
 
-这是一个实验性提供方组合 POC，把文件系统和受管子进程环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器彼此分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
+这是一个实验性提供方组合 POC，把可变的编码环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
 
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
 | [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
 | [`fs-e2b`](../fs/fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
+| [`pty-e2b`](../pty/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
+| [`lsp-e2b`](../lsp/lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
+| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它已经把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 与 `ctx.fs` 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）或 E2B SDK 缓冲。[决策记录](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)负责说明 POC 边界及未采纳的扩展方案。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[基础决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)与[运行时扩展决策](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)共同界定 POC 边界。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 9255c21577..164bb47784 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: bf62cb7d4811ca92f263bd3d337fff9fe41ce223
-README.zh.md: 8c7603aa501a2481aba6dab1f22750056e43ad26
+README.md: 5f89a4bcffdfd11fef8929d2a2ceecb41af319e2
+README.zh.md: b4956033bae131bb8aa236276323ecba30f00115
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index bf62cb7d48..5f89a4bcff 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared lifecycle owner for one E2B sandbox. Filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`.
+Shared lifecycle owner for one E2B sandbox. Capability adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in adapters.
 
 ## Configuration
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 8c7603aa50..b4956033ba 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`。
+一个 E2B 沙箱的共享生命周期所有者。功能适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选适配器见[包族索引](../README.md)。
 
 ## 配置
 
diff --git a/packages/e2b/e2b/src/frame.ts b/packages/e2b/e2b/src/frame.ts
new file mode 100644
index 0000000000..39800b4428
--- /dev/null
+++ b/packages/e2b/e2b/src/frame.ts
@@ -0,0 +1,75 @@
+/** ASCII/base64 JSON framing for byte-faithful protocols over E2B text callbacks. */
+
+import { Buffer } from 'node:buffer'
+
+const BASE64_LINE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+/**
+ * Encode one JSON-compatible value as a newline-delimited ASCII frame.
+ * @param value - Value accepted by `JSON.stringify`.
+ * @returns Base64-encoded UTF-8 JSON followed by one newline.
+ */
+export function encodeE2BFrame(value: unknown): string {
+  const json: unknown = JSON.stringify(value)
+  if (typeof json !== 'string') throw new Error('E2B frame value is not JSON-serializable')
+  return `${Buffer.from(json).toString('base64')}\n`
+}
+
+/** Incremental decoder for newline-delimited base64 JSON frames. */
+export class E2BFrameDecoder {
+  private pending = ''
+  private readonly maxEncodedChars: number
+
+  /** @param maxFrameBytes - Maximum decoded UTF-8 JSON bytes in one frame. */
+  constructor(private readonly maxFrameBytes: number) {
+    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+      throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
+    }
+    this.maxEncodedChars = Math.ceil(maxFrameBytes / 3) * 4
+  }
+
+  /**
+   * Consume one E2B callback chunk.
+   * @param chunk - ASCII text received from the remote helper.
+   * @returns Every complete decoded JSON value, in order.
+   */
+  push(chunk: string): unknown[] {
+    if (/[^\x0a\x20-\x7e]/.test(chunk)) throw new Error('E2B frame stream contained non-ASCII data')
+    this.pending += chunk
+    const values: unknown[] = []
+    for (;;) {
+      const newline = this.pending.indexOf('\n')
+      if (newline < 0) {
+        if (this.pending.length > this.maxEncodedChars) throw new Error('E2B frame exceeded its byte limit')
+        return values
+      }
+      const line = this.pending.slice(0, newline)
+      this.pending = this.pending.slice(newline + 1)
+      values.push(this.decode(line))
+    }
+  }
+
+  /** Reject a truncated final frame. */
+  finish(): void {
+    if (this.pending.length !== 0) throw new Error('E2B frame stream ended mid-frame')
+  }
+
+  private decode(line: string): unknown {
+    if (line.length === 0 || line.length > this.maxEncodedChars || !BASE64_LINE.test(line)) {
+      throw new Error('E2B frame contained invalid base64 or exceeded its byte limit')
+    }
+    const bytes = Buffer.from(line, 'base64')
+    if (bytes.length > this.maxFrameBytes) throw new Error('E2B frame exceeded its byte limit')
+    let json: string
+    try {
+      json = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    } catch (error: unknown) {
+      throw new Error('E2B frame contained invalid UTF-8', { cause: error })
+    }
+    try {
+      return JSON.parse(json) as unknown
+    } catch (error: unknown) {
+      throw new Error('E2B frame contained invalid JSON', { cause: error })
+    }
+  }
+}
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 29cbf1dc53..4c4597f6ef 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -10,6 +10,8 @@ import z from 'schemastery'
 import { Sandbox } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
+export { E2BFrameDecoder, encodeE2BFrame } from './frame.ts'
+
 export {
   CommandExitError,
   FileNotFoundError,
@@ -19,7 +21,7 @@ export {
   SandboxNotFoundError,
   TimeoutError,
 } from 'e2b'
-export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
+export type { CommandHandle, CommandResult, EntryInfo, ProcessInfo, PtyOutput } from 'e2b'
 
 /** Opaque E2B sandbox identity used for reconnecting a later harness process. */
 export type E2BSandboxId = Branded<'E2BSandboxId'>
@@ -42,6 +44,26 @@ export function quoteE2BShellArg(value: string): string {
   return `'${value.replaceAll('\'', "'\"'\"'")}'`
 }
 
+/**
+ * Resolve one executable inside an E2B sandbox and require an absolute result.
+ * @param sandbox - Sandbox whose PATH and filesystem own the executable.
+ * @param command - Absolute path or bare executable name.
+ * @returns Verified absolute remote executable path.
+ */
+export async function resolveE2BExecutable(sandbox: Sandbox, command: string): Promise<string> {
+  if (command.length === 0) throw new Error('E2B executable name must be non-empty')
+  if (posix.isAbsolute(command)) {
+    await sandbox.commands.run(`test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`)
+    return command
+  }
+  const result = await sandbox.commands.run(`command -v -- ${quoteE2BShellArg(command)}`)
+  const executable = result.stdout.trim()
+  if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+    throw new Error(`E2B executable ${JSON.stringify(command)} did not resolve to one absolute path`)
+  }
+  return executable
+}
+
 /** Action taken on the owned sandbox when the Cordis service is disposed. */
 export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
 
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 8c01fae7b4..d056d4b851 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -11,7 +11,7 @@ const configPath = join(fixtureRoot, 'cordis.yml')
 const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
-  it('shares remote state across FS and Bash without creating host workspace files', async () => {
+  it('runs FS, Bash, PTY, LSP, and Code Runtime in one sandbox and deletes it', async () => {
     const { stdout, stderr } = await runLoaderSmoke({
       label: 'E2B composition',
       tempDirPrefix: 'dsh-e2b-composition-',
@@ -19,10 +19,14 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       libBinScript: binScript,
       configPath,
       tsconfigPath,
-      processTimeoutMs: 90_000,
+      env: {
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      processTimeoutMs: 120_000,
       inspect: async (cwd) => {
-        await expect(access(join(cwd, 'from-fs.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
-        await expect(access(join(cwd, 'from-bash.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
+        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte.ts', 'fixture-lsp.mjs']) {
+          await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
+        }
       },
     })
 
@@ -31,9 +35,37 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(output).toMatchObject({
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
+      hover: {
+        kind: 'hover',
+        hover: { contents: '**remote hover** 你好 café' },
+      },
+      definition: {
+        kind: 'locations',
+        locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
+      },
+      terminal: {
+        echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
+        signal: { delivered: true },
+        interrupted: { sessionStatus: { kind: 'running' } },
+      },
+      hostileOutput: { error: { kind: 'output-limit' } },
+      timedOut: { error: { kind: 'timeout' } },
+      aborted: { error: { kind: 'abort', message: 'live abort' } },
+      lingeringCodeRunners: 0,
+    })
+    expect((output.terminal as { motd: string }).motd.length).toBeGreaterThan(0)
+    expect((output.terminal as { echo: { viewport: string } }).echo.viewport).toContain('PTY-你好')
+    expect((output.terminal as { scrollback: string }).scrollback).toContain('PTY-你好')
+    expect((output.terminal as { signal: { targetPgid: number } }).signal.targetPgid).toBeGreaterThan(0)
+    expect(['stdin_read', 'inferred_idle']).toContain(
+      (output.terminal as { interrupted: { waitReason: string } }).interrupted.waitReason,
+    )
+    expect(output.code).toEqual({
+      value: { doubled: 42, typed: true },
+      logs: ['remote-log 你好 42', 'post-mutation'],
     })
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
-  }, 105_000)
+  }, 135_000)
 })
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index c842731f5c..541e69df9c 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -2,8 +2,11 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
+  E2BFrameDecoder,
   E2BSandboxId,
+  encodeE2BFrame,
   quoteE2BShellArg,
+  resolveE2BExecutable,
 } from '@deepseek-ai/dsh-e2b'
 import * as E2BInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -209,6 +212,49 @@ describe('E2B helpers and invariant companion', () => {
     expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
   })
 
+  it('resolves absolute and PATH executables inside the sandbox', async () => {
+    const run = vi.fn()
+      .mockResolvedValueOnce({ exitCode: 0, stdout: '', stderr: '' })
+      .mockResolvedValueOnce({ exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' })
+    const sandbox = { commands: { run } } as unknown as SandboxType
+    await expect(resolveE2BExecutable(sandbox, '/bin/bash')).resolves.toBe('/bin/bash')
+    await expect(resolveE2BExecutable(sandbox, 'node')).resolves.toBe('/usr/bin/node')
+    expect(run).toHaveBeenNthCalledWith(1, "test -f '/bin/bash' -a -x '/bin/bash'")
+    expect(run).toHaveBeenNthCalledWith(2, "command -v -- 'node'")
+  })
+
+  it('rejects empty or non-absolute executable resolutions', async () => {
+    const sandbox = {
+      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: 'relative\npath\n', stderr: '' }) },
+    } as unknown as SandboxType
+    await expect(resolveE2BExecutable(sandbox, '')).rejects.toThrow('non-empty')
+    await expect(resolveE2BExecutable(sandbox, 'tool')).rejects.toThrow('did not resolve')
+  })
+
+  it('round-trips split and adjacent ASCII/base64 JSON frames', () => {
+    const decoder = new E2BFrameDecoder(128)
+    const encoded = encodeE2BFrame({ text: '你好' }) + encodeE2BFrame([1, true])
+    expect(decoder.push(encoded.slice(0, 5))).toEqual([])
+    expect(decoder.push(encoded.slice(5))).toEqual([{ text: '你好' }, [1, true]])
+    expect(() => { decoder.finish() }).not.toThrow()
+    expect(() => encodeE2BFrame(undefined)).toThrow('not JSON-serializable')
+  })
+
+  it('rejects malformed, oversized, and truncated frame streams', () => {
+    expect(() => new E2BFrameDecoder(0)).toThrow('positive safe integer')
+    expect(() => new E2BFrameDecoder(1.5)).toThrow('positive safe integer')
+    expect(() => new E2BFrameDecoder(4).push('é')).toThrow('non-ASCII')
+    expect(() => new E2BFrameDecoder(3).push('AAAAA')).toThrow('byte limit')
+    expect(() => new E2BFrameDecoder(8).push('\n')).toThrow('invalid base64')
+    expect(() => new E2BFrameDecoder(8).push('abc!\n')).toThrow('invalid base64')
+    expect(() => new E2BFrameDecoder(2).push(`${Buffer.from('abc').toString('base64')}\n`)).toThrow('byte limit')
+    expect(() => new E2BFrameDecoder(8).push('/w==\n')).toThrow('invalid UTF-8')
+    expect(() => new E2BFrameDecoder(16).push(`${Buffer.from('not-json').toString('base64')}\n`)).toThrow('invalid JSON')
+    const truncated = new E2BFrameDecoder(8)
+    truncated.push('YQ==')
+    expect(() => { truncated.finish() }).toThrow('mid-frame')
+  })
+
   it('registers the package-owned empty invariant installer', async () => {
     const ctx = new Context()
     await ctx.plugin(InvariantService, { enabled: true })
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index 9919cdaba5..c28c0282c2 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
-README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
+README.md: 74ed729d97013de3d7f502f728e3abe62348846f
+README.zh.md: 5a08d54ca6c54d8355454fc3021a0da48772000b
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 7fbdf07173..74ed729d97 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -7,9 +7,10 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 | Package | Role | ctx key |
 |---|---|---|
 | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
-| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| [`lsp-local/`](lsp-local/README.md) | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| [`lsp-e2b/`](lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
-See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) for the remote process/filesystem boundary.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index e059dbd80b..5a08d54ca6 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -7,9 +7,10 @@
 | 包 | 职责 | ctx key |
 |---|---|---|
 | `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
-| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| [`lsp-local/`](lsp-local/README.md) | 通用多服务器本地后端（spawn、JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| [`lsp-e2b/`](lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
-设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
+协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
diff --git a/packages/lsp/lsp-e2b/README.i18n.yaml b/packages/lsp/lsp-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..fa159820a9
--- /dev/null
+++ b/packages/lsp/lsp-e2b/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/lsp/lsp-e2b/README.md
+README.md: 968487b7c5f63b2165cf66797a4182642507a8e9
+README.zh.md: 2b937f01156c3194f64ed9fb54478fec5c77305b
diff --git a/packages/lsp/lsp-e2b/README.md b/packages/lsp/lsp-e2b/README.md
new file mode 100644
index 0000000000..968487b7c5
--- /dev/null
+++ b/packages/lsp/lsp-e2b/README.md
@@ -0,0 +1,47 @@
+# @deepseek-ai/dsh-lsp-e2b
+
+English | [中文](README.zh.md)
+
+Generic E2B language-server backend for [`ctx.lsp`](../lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
+
+## Plugin and configuration
+
+The `lsp-e2b` plugin injects `e2b`, `lsp`, and the concrete `dsh-subprocess-e2b` service. `servers` is a non-empty provider-id table:
+
+| Server key | Default | Meaning |
+|---|---|---|
+| `command` | required | Remote executable, absolute or resolved on the sandbox PATH at load. |
+| `args` | `[]` | Remote server arguments. |
+| `env` | `{}` | Explicit environment entries passed through the subprocess adapter. |
+| `extensionToLanguage` | required | Lowercase leading-dot extension to LSP language id. |
+| `initializationOptions` / `configuration` | `null` / `null` | Static initialize options and `workspace/configuration` answer. |
+| `maxMessageBytes` | `16000000` | Largest LSP message accepted from the server. |
+| `maxStderrBytes` | `1000000` | Retained raw server stderr tail. |
+| `maxDocumentBytes` | `4000000` | Largest remote source opened for one query. |
+| `shutdownTimeoutMs` | `5000` | Graceful protocol-shutdown budget. |
+| `killGraceMs` | `2000` | Request-cancel and TERM-to-KILL grace. |
+
+Provider ids and commands are non-empty; numeric bounds are positive safe integers, and timer values cannot exceed Node's maximum timer delay. Setup uploads one owner-private proxy under `ctx.e2b.runtimeRoot`, resolves Node and every configured server executable remotely, then registers all providers atomically.
+
+## Remote protocol and filesystem
+
+E2B command callbacks are text, while LSP is byte-framed. The installed proxy therefore base64-frames raw server stdout, stderr, and stdin as newline-delimited ASCII JSON; the host validates and decodes every frame before handing bytes to the shared `LspInstance` protocol engine. `initialize.processId` is `null` because host and server do not share a process namespace.
+
+One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, requires a regular file, enforces the size bound before and after reading, decodes strict UTF-8, and uses the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
+
+The subprocess adapter owns process groups and escalation, so cancellation and disposal await remote server quiescence. The host owns LSP request ids, pending requests, provider queues, and normalized results.
+
+## Model Experience
+
+Indirectly, through `@deepseek-ai/dsh-tool-lsp`, which exposes normalized semantic navigation and hover results without changing its model-facing schema.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Configured servers only** — this package does not install language servers, select presets, or synchronize a host workspace into E2B.
+- **Host protocol state is not reconnectable** — retaining a sandbox does not restore provider queues, JSON-RPC requests, subprocess handles, or document lifecycle state.
+- **SDK output retention remains** — ASCII framing preserves protocol bytes, but E2B and the subprocess adapter still retain callback output in host memory.
+- **Sandbox policy is template-owned** — this provider adds no volume, snapshot, credential, or network-policy layer.
diff --git a/packages/lsp/lsp-e2b/README.zh.md b/packages/lsp/lsp-e2b/README.zh.md
new file mode 100644
index 0000000000..2b937f0115
--- /dev/null
+++ b/packages/lsp/lsp-e2b/README.zh.md
@@ -0,0 +1,47 @@
+# @deepseek-ai/dsh-lsp-e2b
+
+[English](README.md) | 中文
+
+用于 [`ctx.lsp`](../lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
+
+## 插件与配置
+
+`lsp-e2b` 插件注入 `e2b`、`lsp` 和具体的 `dsh-subprocess-e2b` 服务。`servers` 是一张非空的提供方 id 表：
+
+| 服务器键 | 默认值 | 含义 |
+|---|---|---|
+| `command` | 必填 | 远程可执行文件：绝对路径，或在加载时通过沙箱 PATH 解析。 |
+| `args` | `[]` | 远程服务器参数。 |
+| `env` | `{}` | 经由进程管理适配器传入的显式环境条目。 |
+| `extensionToLanguage` | 必填 | 小写、以点开头的扩展名到 LSP language id 的映射。 |
+| `initializationOptions` / `configuration` | `null` / `null` | 静态初始化选项和 `workspace/configuration` 应答。 |
+| `maxMessageBytes` | `16000000` | 从服务器接受的 LSP 消息大小上限。 |
+| `maxStderrBytes` | `1000000` | 保留的服务器原始 stderr 尾部上限。 |
+| `maxDocumentBytes` | `4000000` | 单次查询可打开的最大远程源文件。 |
+| `shutdownTimeoutMs` | `5000` | 协议优雅关闭预算。 |
+| `killGraceMs` | `2000` | 请求取消与 TERM 到 KILL 升级的宽限期。 |
+
+提供方 id 与命令必须非空；数值上限必须是正的安全整数，定时器取值不得超过 Node 的最大定时器延迟。设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个仅供所有者使用的私有代理，在远程解析 Node 和每个已配置服务器的可执行文件，再以原子方式注册所有提供方。
+
+## 远程协议与文件系统
+
+E2B 命令回调交付的是文本，而 LSP 按字节分帧。因此，已安装的代理会把服务器 stdout、stderr 和 stdin 的原始字节进行 base64 编码，封装为以换行分隔的 ASCII JSON 帧；宿主会验证并解码每一帧，再把字节交给共享的 `LspInstance` 协议引擎。`initialize.processId` 为 `null`，因为宿主与服务器不共享进程命名空间。
+
+每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，要求源文件为普通文件，在读取前后都检查大小上限，使用严格的 UTF-8 解码，并采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
+
+进程管理适配器负责进程组和终止升级，因此取消与资源释放都会等待远程服务器完全停稳。宿主负责 LSP 请求 id、待完成请求、提供方队列和规范化结果。
+
+## 模型体验
+
+通过 `@deepseek-ai/dsh-tool-lsp` 间接影响模型；该包会公开规范化的语义导航与悬停结果，而不改变其面向模型的 schema。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由 `dsh-tool-lsp` 负责。
+
+## 已知限制与暂缓工作
+
+- **仅支持已配置的服务器**：本包不会安装语言服务器、选择 preset，或把宿主工作区同步到 E2B。
+- **宿主协议状态不可重连**：保留沙箱并不会恢复提供方队列、JSON-RPC 请求、进程管理句柄或文档生命周期状态。
+- **SDK 仍会保留输出**：ASCII 分帧能保留协议字节，但 E2B 和进程管理适配器仍会在宿主内存中保留回调输出。
+- **沙箱策略归模板负责**：本提供方不会额外增加卷、快照、凭据或网络策略层。
diff --git a/packages/lsp/lsp-e2b/package.json b/packages/lsp/lsp-e2b/package.json
new file mode 100644
index 0000000000..0671341f3c
--- /dev/null
+++ b/packages/lsp/lsp-e2b/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-lsp-e2b",
+  "description": "E2B language-server provider for DeepSeek Harness",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-lsp": "^0.0.1",
+    "@deepseek-ai/dsh-lsp-local": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-lsp": "workspace:^",
+    "@deepseek-ai/dsh-lsp-local": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/lsp/lsp-e2b/src/index.ts b/packages/lsp/lsp-e2b/src/index.ts
new file mode 100644
index 0000000000..eb9596db5f
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/index.ts
@@ -0,0 +1,358 @@
+/** E2B filesystem and process backend for the harness LSP capability seam. */
+
+import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import {
+  FileType,
+  quoteE2BShellArg,
+  resolveE2BExecutable,
+} from '@deepseek-ai/dsh-e2b'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
+import type { LspProvider, LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
+import { LspInstance } from '@deepseek-ai/dsh-lsp-local'
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { LSP_PROXY_SOURCE } from './proxy-source.ts'
+import { E2BLspTransport } from './transport.ts'
+
+export { E2BLspTransport } from './transport.ts'
+
+/** Cordis plugin name. */
+export const name = 'lsp-e2b'
+/** Services required by the remote provider. */
+export const inject = ['e2b', 'lsp', 'subprocess']
+
+const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
+const DEFAULT_MAX_STDERR_BYTES = 1_000_000
+const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
+const DEFAULT_KILL_GRACE_MS = 2_000
+
+/* jscpd:ignore-start -- Loader requires each backend to expose its own statically walkable server schema. */
+/** One configured language server inside the shared E2B sandbox. */
+export interface LspE2BServerConfig {
+  /** Remote executable, absolute or resolved on the sandbox PATH. */
+  command: string
+  /** Lowercase leading-dot extension to LSP language id. */
+  extensionToLanguage: Record<string, string>
+  /** Remote executable arguments. */
+  args?: string[]
+  /** Explicit remote environment overrides. */
+  env?: Record<string, string>
+  /** Static `initialize` options. */
+  initializationOptions?: unknown
+  /** Static answer to every `workspace/configuration` item. */
+  configuration?: unknown
+  /** Largest LSP message accepted from the server. */
+  maxMessageBytes?: number
+  /** Largest remote stderr tail retained for diagnostics. */
+  maxStderrBytes?: number
+  /** Largest remote source opened for one query. */
+  maxDocumentBytes?: number
+  /** Graceful LSP shutdown budget. */
+  shutdownTimeoutMs?: number
+  /** Request-cancel and TERM-to-KILL grace. */
+  killGraceMs?: number
+}
+
+/** Plugin configuration. */
+export interface Config {
+  /** Non-empty provider-id to remote-server table. */
+  servers: Record<string, LspE2BServerConfig>
+}
+
+type ResolvedServerConfig = Required<LspE2BServerConfig>
+
+const ServerConfig: z<LspE2BServerConfig> = z.object({
+  command: z.string().required(),
+  args: z.array(String).default([]),
+  env: z.dict(String).default({}),
+  extensionToLanguage: z.dict(String).required(),
+  initializationOptions: z.any().default(null),
+  configuration: z.any().default(null),
+  maxMessageBytes: z.number().default(DEFAULT_MAX_MESSAGE_BYTES),
+  maxStderrBytes: z.number().default(DEFAULT_MAX_STDERR_BYTES),
+  maxDocumentBytes: z.number().default(DEFAULT_MAX_DOCUMENT_BYTES),
+  shutdownTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_SHUTDOWN_TIMEOUT_MS),
+  killGraceMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_KILL_GRACE_MS),
+})
+
+/** Schemastery plugin configuration. */
+export const Config: z<Config> = z.object({
+  servers: z.dict(ServerConfig).required(),
+})
+/* jscpd:ignore-end */
+
+interface RemoteSource {
+  canonicalPath: string
+  text: string
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  try {
+    signal.throwIfAborted()
+  } catch (error: unknown) {
+    return error
+  }
+  return new DOMException('The operation was aborted', 'AbortError')
+}
+
+function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return promise
+  // AbortSignal permits opaque reasons, and callers observe the exact reason.
+  // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+  if (signal.aborted) return Promise.reject(abortReason(signal))
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      cleanup()
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Preserve the signal's exact opaque reason.
+      reject(abortReason(signal))
+    }
+    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void promise.then(
+      (value) => { cleanup(); resolve(value) },
+      (error: unknown) => { cleanup(); reject(error instanceof Error ? error : new Error(String(error))) },
+    )
+  })
+}
+
+function validateServerConfig(providerId: string, config: ResolvedServerConfig): void {
+  if (config.command.length === 0) throw new Error(`lsp-e2b: servers.${providerId}.command must be non-empty`)
+  for (const name of ['maxMessageBytes', 'maxStderrBytes', 'maxDocumentBytes', 'shutdownTimeoutMs', 'killGraceMs'] as const) {
+    const value = config[name]
+    if (!Number.isSafeInteger(value) || value <= 0 || (name.endsWith('Ms') && value > MAX_TIMER_DELAY_MS)) {
+      throw new Error(`lsp-e2b: servers.${providerId}.${name} must be a positive safe integer${name.endsWith('Ms') ? ` no greater than ${MAX_TIMER_DELAY_MS}` : ''}`)
+    }
+  }
+}
+
+async function canonicalRemotePath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
+  signal?.throwIfAborted()
+  const result = await sandbox.commands.run(`realpath -e -- ${quoteE2BShellArg(path)}`, signal === undefined ? {} : { signal })
+  signal?.throwIfAborted()
+  const canonical = result.stdout.trim()
+  if (!posix.isAbsolute(canonical) || canonical.includes('\n')) throw new Error(`remote path ${JSON.stringify(path)} did not resolve canonically`)
+  return canonical
+}
+
+/**
+ * Canonicalize and validate one workspace inside E2B.
+ * @param sandbox - Shared sandbox that owns the workspace.
+ * @param workspaceRoot - Remote workspace path supplied by the query.
+ * @param signal - Optional query cancellation signal.
+ * @returns The canonical remote directory path.
+ */
+export async function canonicalizeE2BWorkspace(
+  sandbox: Sandbox,
+  workspaceRoot: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const canonical = await canonicalRemotePath(sandbox, workspaceRoot, signal)
+  const info = await sandbox.files.getInfo(canonical, signal === undefined ? {} : { signal })
+  signal?.throwIfAborted()
+  if (info.type !== FileType.DIR) throw new Error(`workspace root ${JSON.stringify(workspaceRoot)} is not a directory`)
+  return canonical
+}
+
+/**
+ * Resolve, contain, and read one UTF-8 query source inside E2B.
+ * @param sandbox - Shared sandbox that owns the source.
+ * @param filePath - Absolute path or path relative to the canonical workspace.
+ * @param workspace - Canonical remote workspace directory.
+ * @param maxDocumentBytes - Maximum source size before and after reading.
+ * @param signal - Optional query cancellation signal.
+ * @returns The canonical source path and decoded text.
+ */
+export async function readE2BSource(
+  sandbox: Sandbox,
+  filePath: string,
+  workspace: string,
+  maxDocumentBytes: number,
+  signal?: AbortSignal,
+): Promise<RemoteSource> {
+  const requested = posix.isAbsolute(filePath) ? filePath : posix.resolve(workspace, filePath)
+  const canonicalPath = await canonicalRemotePath(sandbox, requested, signal)
+  const relative = posix.relative(workspace, canonicalPath)
+  if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
+    throw new Error(`source ${JSON.stringify(filePath)} resolves outside the workspace`)
+  }
+  const info = await sandbox.files.getInfo(canonicalPath, signal === undefined ? {} : { signal })
+  if (info.type !== FileType.FILE) throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
+  if (info.size > maxDocumentBytes) {
+    throw new Error(`source ${JSON.stringify(filePath)} is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
+  }
+  const bytes = await sandbox.files.read(canonicalPath, { format: 'bytes', ...signal === undefined ? {} : { signal } })
+  signal?.throwIfAborted()
+  if (bytes.length > maxDocumentBytes) {
+    throw new Error(`source ${JSON.stringify(filePath)} grew past the ${maxDocumentBytes}-byte limit while reading`)
+  }
+  let text: string
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch (error: unknown) {
+    throw new Error(`source ${JSON.stringify(filePath)} is not valid UTF-8 text`, { cause: error })
+  }
+  return { canonicalPath, text }
+}
+
+/* jscpd:ignore-start -- Provider identity mirrors the seam while remote source and process ownership stay local. */
+/** One pooled remote provider with an isolated server per canonical workspace. */
+export class E2BLspProvider implements LspProvider {
+  readonly id: LspProviderId
+  readonly extensionToLanguage: Readonly<Record<string, string>>
+  private readonly instances = new Map<string, LspInstance>()
+  private readonly queues = new Map<string, Promise<void>>()
+  private disposed = false
+
+  constructor(
+    providerId: string,
+    private readonly sandbox: Sandbox,
+    private readonly subprocess: E2BSubprocessService,
+    private readonly config: ResolvedServerConfig,
+    private readonly executable: string,
+    private readonly nodeExecutable: string,
+    private readonly proxyPath: string,
+  ) {
+    this.id = LspProviderId(providerId)
+    this.extensionToLanguage = config.extensionToLanguage
+  }
+  /* jscpd:ignore-end */
+
+  async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
+    this.assertActive(signal)
+    const workspace = await canonicalizeE2BWorkspace(this.sandbox, request.workspaceRoot, signal)
+    this.assertActive(signal)
+    return this.enqueue(workspace, signal, async () => {
+      this.assertActive(signal)
+      const source = await readE2BSource(this.sandbox, request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      this.assertActive(signal)
+      let instance = this.instanceFor(workspace)
+      try {
+        return await instance.query(request, source, signal)
+      } catch (error: unknown) {
+        if (!instance.isTransportFailure(error)) throw error
+        await instance.dispose()
+        this.evict(workspace, instance)
+        this.assertActive(signal)
+        instance = this.instanceFor(workspace)
+        return await instance.query(request, source, signal)
+      } finally {
+        if (instance.dead) {
+          await instance.dispose()
+          this.evict(workspace, instance)
+        }
+      }
+    })
+  }
+
+  /* jscpd:ignore-start -- Queue and pooling semantics are shared; transport failure and disposal identities differ. */
+  /** Stop accepting work and await every remote server and queued query. */
+  async disposeAll(): Promise<void> {
+    this.disposed = true
+    const instances = [...this.instances.values()]
+    const queues = [...this.queues.values()]
+    this.instances.clear()
+    await Promise.all([...instances.map(instance => instance.dispose()), ...queues])
+    this.queues.clear()
+  }
+
+  private assertActive(signal?: AbortSignal): void {
+    if (this.disposed) throw new LspError('lsp-e2b provider is disposed', 'LSP_DISPOSED')
+    signal?.throwIfAborted()
+  }
+
+  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+    const previous = this.queues.get(workspace) ?? Promise.resolve()
+    const result = abortable(previous, signal).then(run)
+    const tail = previous.then(() => result).then(() => undefined, () => undefined)
+    this.queues.set(workspace, tail)
+    void tail.then(() => { if (this.queues.get(workspace) === tail) this.queues.delete(workspace) })
+    return result
+  }
+
+  private instanceFor(workspace: string): LspInstance {
+    this.assertActive()
+    const existing = this.instances.get(workspace)
+    if (existing !== undefined) return existing
+    const created = this.createInstance(workspace)
+    this.instances.set(workspace, created)
+    return created
+  }
+  /* jscpd:ignore-end */
+
+  private createInstance(workspace: string): LspInstance {
+    return new LspInstance({
+      command: this.executable,
+      args: this.config.args,
+      cwd: workspace,
+      env: this.config.env,
+      configuration: this.config.configuration,
+      initializationOptions: this.config.initializationOptions,
+      maxMessageBytes: this.config.maxMessageBytes,
+      maxStderrBytes: this.config.maxStderrBytes,
+      shutdownTimeoutMs: this.config.shutdownTimeoutMs,
+      killGraceMs: this.config.killGraceMs,
+      clientProcessId: null,
+    }, (spec: SubprocessSpawnSpec) => {
+      const originalArgv = Buffer.from(JSON.stringify(spec.argv)).toString('base64')
+      const inner = this.subprocess.spawn({
+        ...spec,
+        argv: [this.nodeExecutable, this.proxyPath, originalArgv],
+        stdio: {
+          stdin: 'pipe',
+          stdout: 'pipe',
+          stderr: { maxBytes: this.config.maxStderrBytes },
+        },
+      })
+      const rawBound = Math.max(this.config.maxMessageBytes, this.config.maxStderrBytes)
+      return new E2BLspTransport(inner, rawBound * 2 + 1024, this.config.maxStderrBytes)
+    })
+  }
+
+  private evict(workspace: string, instance: LspInstance): void {
+    if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
+  }
+}
+
+/** Install the proxy, resolve remote commands, and atomically register providers. */
+export async function apply(ctx: Context, config: Config): Promise<void> {
+  if (!(ctx.subprocess instanceof E2BSubprocessService)) {
+    throw new Error('lsp-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
+  }
+  const subprocess = ctx.subprocess
+  const entries = Object.entries(config.servers)
+  if (entries.length === 0) throw new Error('lsp-e2b: servers must contain at least one server')
+  const sandbox = await ctx.e2b.getSandbox()
+  const proxyPath = posix.join(ctx.e2b.runtimeRoot, 'lsp-stdio-proxy.mjs')
+  await sandbox.files.write([{ path: proxyPath, data: LSP_PROXY_SOURCE }])
+  await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(proxyPath)}`)
+  const nodeExecutable = await resolveE2BExecutable(sandbox, 'node')
+  const providers = await Promise.all(entries.map(async ([providerId, raw]) => {
+    if (providerId.trim() === '') throw new Error('lsp-e2b: server ids must be non-empty strings')
+    const resolved = raw as ResolvedServerConfig
+    validateServerConfig(providerId, resolved)
+    const executable = await resolveE2BExecutable(sandbox, resolved.command)
+    return new E2BLspProvider(providerId, sandbox, subprocess, resolved, executable, nodeExecutable, proxyPath)
+  }))
+
+  /* jscpd:ignore-start -- Every provider table publishes atomically through the same registry contract. */
+  ctx.effect(() => {
+    const disposers: Array<() => void> = []
+    try {
+      for (const provider of providers) disposers.push(ctx.lsp.registerProvider(provider))
+    } catch (error: unknown) {
+      for (const dispose of disposers.reverse()) dispose()
+      throw error
+    }
+    return async () => {
+      for (const dispose of disposers.reverse()) dispose()
+      await Promise.all(providers.map(provider => provider.disposeAll()))
+    }
+  }, 'lsp-e2b.registerProviders')
+  /* jscpd:ignore-end */
+}
diff --git a/packages/lsp/lsp-e2b/src/invariant.ts b/packages/lsp/lsp-e2b/src/invariant.ts
new file mode 100644
index 0000000000..129cf0a6d4
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/invariant.ts
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-lsp-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-lsp-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'lsp-e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the LSP registry owns provider publication. */
+const install: InvariantInstaller = () => {}
+
+/** Register this package's invariant companion. */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/lsp/lsp-e2b/src/proxy-source.ts b/packages/lsp/lsp-e2b/src/proxy-source.ts
new file mode 100644
index 0000000000..5b6fe42d07
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/proxy-source.ts
@@ -0,0 +1,55 @@
+/** Dependency-free remote stdio proxy installed inside the E2B sandbox. */
+
+/**
+ * Node program that base64-frames raw child stdio so E2B's text callbacks
+ * never decode the language server's byte stream.
+ */
+export const LSP_PROXY_SOURCE = String.raw`import { Buffer } from 'node:buffer'
+import { spawn } from 'node:child_process'
+import { createInterface } from 'node:readline'
+
+const emit = (message) => {
+  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
+}
+
+let argv
+try {
+  argv = JSON.parse(Buffer.from(process.argv[2], 'base64').toString('utf8'))
+  if (!Array.isArray(argv) || argv.length === 0 || argv.some(value => typeof value !== 'string')) throw new Error('invalid argv')
+} catch (error) {
+  process.stderr.write('lsp-e2b proxy argv error: ' + String(error) + '\n')
+  process.exitCode = 125
+  process.stdin.destroy()
+}
+
+if (argv) {
+  const child = spawn(argv[0], argv.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], env: process.env })
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  child.stdout.on('data', data => { emit({ type: 'stdout', data: data.toString('base64') }) })
+  child.stderr.on('data', data => { emit({ type: 'stderr', data: data.toString('base64') }) })
+  child.on('error', error => {
+    emit({ type: 'stderr', data: Buffer.from('language server spawn failed: ' + error.message).toString('base64') })
+  })
+  child.on('close', (code, signal) => {
+    emit({ type: 'exit', code, signal })
+    input.close()
+    process.stdin.destroy()
+    process.exitCode = code === null ? 1 : code
+  })
+  input.on('line', line => {
+    input.pause()
+    try {
+      const message = JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
+      if (!message || message.type !== 'stdin' || typeof message.data !== 'string') throw new Error('invalid stdin frame')
+      const data = Buffer.from(message.data, 'base64')
+      if (data.toString('base64') !== message.data) throw new Error('invalid stdin base64')
+      if (child.stdin.write(data)) input.resume()
+      else child.stdin.once('drain', () => { input.resume() })
+    } catch (error) {
+      process.stderr.write('lsp-e2b proxy stdin error: ' + String(error) + '\n')
+      child.kill('SIGTERM')
+    }
+  })
+  input.on('close', () => { child.stdin.end() })
+}
+`
diff --git a/packages/lsp/lsp-e2b/src/transport.ts b/packages/lsp/lsp-e2b/src/transport.ts
new file mode 100644
index 0000000000..ddd3445db8
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/transport.ts
@@ -0,0 +1,183 @@
+/** Byte-faithful stdio transport over an E2B subprocess and ASCII/base64 frames. */
+
+import { Buffer } from 'node:buffer'
+import { PassThrough, Writable } from 'node:stream'
+import { E2BFrameDecoder, encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessOutputRead,
+  SubprocessOutputReader,
+} from '@deepseek-ai/dsh-subprocess'
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+class ByteTailReader implements SubprocessOutputReader {
+  private chunks: Buffer[] = []
+  private totalBytes = 0
+  private retainedBytes = 0
+  private dropped = false
+
+  constructor(private readonly maxBytes: number) {}
+
+  append(data: Buffer): void {
+    if (data.length === 0) return
+    this.chunks.push(data)
+    this.totalBytes += data.length
+    this.retainedBytes += data.length
+    while (this.retainedBytes > this.maxBytes && this.chunks.length > 0) {
+      const first = this.chunks[0] as Buffer
+      const excess = this.retainedBytes - this.maxBytes
+      if (first.length <= excess) {
+        this.chunks.shift()
+        this.retainedBytes -= first.length
+      } else {
+        this.chunks[0] = first.subarray(excess)
+        this.retainedBytes -= excess
+      }
+      this.dropped = true
+    }
+  }
+
+  readFrom(fromByte: number): SubprocessOutputRead {
+    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
+      throw new Error('subprocess output offset must be a non-negative safe integer')
+    }
+    const retainedStart = this.totalBytes - this.retainedBytes
+    const lossy = fromByte < retainedStart
+    const start = lossy ? 0 : Math.min(this.retainedBytes, fromByte - retainedStart)
+    const bytes = Buffer.concat(this.chunks).subarray(start)
+    return { text: bytes.toString('utf8'), nextOffset: this.totalBytes, lossy: lossy || this.dropped && fromByte === 0 }
+  }
+}
+
+class FramedInput extends Writable {
+  constructor(private readonly target: Writable) {
+    super()
+    target.on('error', (error: Error) => { this.destroy(error) })
+  }
+
+  override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    this.target.write(encodeE2BFrame({ type: 'stdin', data: chunk.toString('base64') }), callback)
+  }
+
+  override _final(callback: (error?: Error | null) => void): void {
+    this.target.end(callback)
+  }
+}
+
+/** Subprocess handle that decodes a remote proxy's stdout/stderr byte frames. */
+export class E2BLspTransport implements SubprocessHandle {
+  readonly stdin: Writable
+  readonly stdout = new PassThrough()
+  readonly stderr = undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+  private readonly stderrTail: ByteTailReader
+  private readonly decoder: E2BFrameDecoder
+  private failed: Error | undefined
+
+  /**
+   * @param inner - E2B subprocess running the installed proxy.
+   * @param maxFrameBytes - Maximum decoded proxy frame size.
+   * @param maxStderrBytes - Retained raw language-server stderr tail.
+   */
+  constructor(
+    private readonly inner: SubprocessHandle,
+    maxFrameBytes: number,
+    maxStderrBytes: number,
+  ) {
+    if (inner.stdin === undefined || inner.stdout === undefined) {
+      inner.terminate()
+      throw new Error('lsp-e2b: proxy subprocess dropped a piped stream')
+    }
+    this.stdin = new FramedInput(inner.stdin)
+    this.stderrTail = new ByteTailReader(maxStderrBytes)
+    this.collected = { stderr: this.stderrTail }
+    this.decoder = new E2BFrameDecoder(maxFrameBytes)
+    inner.stdout.on('data', (chunk: Buffer) => { this.onProxyData(chunk) })
+    inner.stdout.on('error', (error: Error) => { this.fail(error) })
+    this.done = inner.done.then(
+      (outcome) => {
+        this.finishFrames()
+        this.captureProxyStderr()
+        this.stdout.end()
+        if (this.failed !== undefined) throw this.failed
+        return outcome
+      },
+      (error: unknown) => {
+        this.captureProxyStderr()
+        this.stdout.end()
+        throw error
+      },
+    )
+    void this.done.catch(() => {})
+  }
+
+  get pid(): number {
+    return this.inner.pid
+  }
+
+  terminate(): void {
+    this.inner.terminate()
+  }
+
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    return await this.inner.waitForExit(signal)
+  }
+
+  private onProxyData(chunk: Buffer): void {
+    if (this.failed !== undefined) return
+    let frames: unknown[]
+    try {
+      frames = this.decoder.push(chunk.toString('utf8'))
+    } catch (error: unknown) {
+      this.fail(asError(error))
+      return
+    }
+    for (const frame of frames) this.dispatch(frame)
+  }
+
+  private dispatch(frame: unknown): void {
+    if (typeof frame !== 'object' || frame === null) {
+      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
+      return
+    }
+    const record = frame as Record<string, unknown>
+    if (record.type === 'exit' && (record.code === null || typeof record.code === 'number') && (record.signal === null || typeof record.signal === 'string')) return
+    if ((record.type !== 'stdout' && record.type !== 'stderr') || typeof record.data !== 'string') {
+      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
+      return
+    }
+    const data = Buffer.from(record.data, 'base64')
+    if (data.toString('base64') !== record.data) {
+      this.fail(new Error('lsp-e2b: proxy emitted invalid base64'))
+      return
+    }
+    if (record.type === 'stdout') this.stdout.write(data)
+    else this.stderrTail.append(data)
+  }
+
+  private finishFrames(): void {
+    if (this.failed !== undefined) return
+    try {
+      this.decoder.finish()
+    } catch (error: unknown) {
+      this.fail(asError(error))
+    }
+  }
+
+  private captureProxyStderr(): void {
+    const diagnostic = this.inner.collected.stderr?.readFrom(0).text
+    if (diagnostic !== undefined && diagnostic.length > 0) this.stderrTail.append(Buffer.from(diagnostic))
+  }
+
+  private fail(error: Error): void {
+    if (this.failed !== undefined) return
+    this.failed = error
+    this.inner.terminate()
+    this.stdout.end()
+  }
+}
diff --git a/packages/lsp/lsp-e2b/tests/provider.spec.ts b/packages/lsp/lsp-e2b/tests/provider.spec.ts
new file mode 100644
index 0000000000..0b41be12a3
--- /dev/null
+++ b/packages/lsp/lsp-e2b/tests/provider.spec.ts
@@ -0,0 +1,397 @@
+import { PassThrough } from 'node:stream'
+import { Context } from 'cordis'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  FileType,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+
+const mockedLsp = vi.hoisted(() => {
+  interface Plan {
+    query?: (...args: unknown[]) => unknown
+    transportFailure?: unknown
+    dead?: boolean
+    deadAfterQuery?: boolean
+    disposeError?: unknown
+  }
+
+  class FakeLspInstance {
+    static readonly instances: FakeLspInstance[] = []
+    static readonly plans: Plan[] = []
+    readonly plan: Plan
+    readonly transport: unknown
+    readonly queries: unknown[][] = []
+    dead: boolean
+    disposals = 0
+
+    constructor(
+      readonly spec: Record<string, unknown>,
+      spawner: (spec: SubprocessSpawnSpec) => unknown,
+    ) {
+      this.plan = FakeLspInstance.plans.shift() ?? {}
+      this.dead = this.plan.dead === true
+      this.transport = spawner({
+        argv: [String(spec.command), ...(spec.args as string[])],
+        cwd: String(spec.cwd),
+        env: spec.env as Record<string, string>,
+        graceMs: Number(spec.killGraceMs),
+        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: Number(spec.maxStderrBytes) } },
+      })
+      FakeLspInstance.instances.push(this)
+    }
+
+    async query(...args: unknown[]): Promise<unknown> {
+      this.queries.push(args)
+      const result = await Promise.resolve(this.plan.query?.(...args) ?? { kind: 'hover', hover: null })
+      if (this.plan.deadAfterQuery === true) this.dead = true
+      return result
+    }
+
+    isTransportFailure(error: unknown): boolean {
+      return error === this.plan.transportFailure
+    }
+
+    async dispose(): Promise<void> {
+      this.disposals += 1
+      this.dead = true
+      if (this.plan.disposeError !== undefined) throw this.plan.disposeError
+    }
+  }
+
+  return { FakeLspInstance }
+})
+
+vi.mock('@deepseek-ai/dsh-lsp-local', () => ({ LspInstance: mockedLsp.FakeLspInstance }))
+
+import {
+  E2BLspProvider,
+  apply,
+  canonicalizeE2BWorkspace,
+  readE2BSource,
+} from '@deepseek-ai/dsh-lsp-e2b'
+import type { LspE2BServerConfig } from '@deepseek-ai/dsh-lsp-e2b'
+import * as E2BLspInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+class FakeInnerHandle implements SubprocessHandle {
+  readonly pid = 777
+  readonly stdin = new PassThrough()
+  readonly stdout = new PassThrough()
+  readonly stderr = undefined
+  readonly collected = { stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) } }
+  readonly done = Promise.resolve({ exitCode: 0, signal: null })
+  terminate(): void {}
+  async waitForExit(): Promise<boolean> { return true }
+}
+
+class FakeRemote {
+  readonly writes: Array<Array<{ path: string; data: string }>> = []
+  readonly commands: string[] = []
+  readonly infos = new Map<string, { type: FileType; size: number }>()
+  readonly contents = new Map<string, Uint8Array>()
+  readonly realpaths = new Map<string, string>()
+  forcedRealpath: string | undefined
+
+  constructor() {
+    this.infos.set('/workspace', { type: FileType.DIR, size: 0 })
+    this.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 12 })
+    this.contents.set('/workspace/file.ts', Buffer.from('const x = 1'))
+  }
+
+  readonly sandbox = {
+    commands: {
+      run: async (command: string) => {
+        this.commands.push(command)
+        if (command.startsWith('realpath ')) {
+          const match = /'([^']*)'$/.exec(command)
+          const requested = match?.[1] ?? ''
+          return { exitCode: 0, stdout: `${this.forcedRealpath ?? this.realpaths.get(requested) ?? requested}\n`, stderr: '' }
+        }
+        if (command.startsWith('command -v')) return { exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+    files: {
+      write: async (files: Array<{ path: string; data: string }>) => {
+        this.writes.push(files)
+        return files.map(() => ({}))
+      },
+      getInfo: async (path: string) => {
+        const info = this.infos.get(path)
+        if (info === undefined) throw new Error(`missing info for ${path}`)
+        return info
+      },
+      read: async (path: string) => this.contents.get(path) ?? new Uint8Array(),
+    },
+  } as unknown as Sandbox
+}
+
+function subprocess(spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())): E2BSubprocessService {
+  const service = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+  Object.defineProperty(service, 'spawn', { value: spawn })
+  return service
+}
+
+function server(overrides: Partial<LspE2BServerConfig> = {}): Required<LspE2BServerConfig> {
+  return {
+    command: '/usr/bin/server', args: ['--stdio'], env: {},
+    extensionToLanguage: { '.ts': 'typescript' },
+    initializationOptions: null, configuration: null,
+    maxMessageBytes: 1_024, maxStderrBytes: 128, maxDocumentBytes: 1_024,
+    shutdownTimeoutMs: 100, killGraceMs: 50,
+    ...overrides,
+  }
+}
+
+function provider(remote = new FakeRemote(), service = subprocess()): E2BLspProvider {
+  return new E2BLspProvider(
+    'fixture', remote.sandbox, service, server(),
+    '/usr/bin/server', '/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs',
+  )
+}
+
+function query(workspaceRoot = '/workspace') {
+  return {
+    operation: 'hover' as const,
+    filePath: 'file.ts',
+    position: { line: 0, character: 1 },
+    workspaceRoot,
+    languageId: 'typescript',
+  }
+}
+
+beforeEach(() => {
+  mockedLsp.FakeLspInstance.instances.length = 0
+  mockedLsp.FakeLspInstance.plans.length = 0
+})
+
+describe('E2B LSP filesystem boundary', () => {
+  it('canonicalizes a directory and reads a contained UTF-8 source', async () => {
+    const remote = new FakeRemote()
+    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace')).resolves.toBe('/workspace')
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024)).resolves.toEqual({
+      canonicalPath: '/workspace/file.ts',
+      text: 'const x = 1',
+    })
+    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024)).resolves.toMatchObject({
+      canonicalPath: '/workspace/file.ts',
+    })
+    const signal = new AbortController().signal
+    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace', signal)).resolves.toBe('/workspace')
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, signal)).resolves.toMatchObject({
+      canonicalPath: '/workspace/file.ts',
+    })
+  })
+
+  it('rejects malformed workspaces and source containment/type/size/encoding failures', async () => {
+    const malformed = new FakeRemote()
+    malformed.forcedRealpath = 'relative'
+    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
+    malformed.forcedRealpath = '/workspace\nother'
+    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
+
+    const notDirectory = new FakeRemote()
+    notDirectory.infos.set('/workspace', { type: FileType.FILE, size: 0 })
+    await expect(canonicalizeE2BWorkspace(notDirectory.sandbox, '/workspace')).rejects.toThrow('not a directory')
+
+    const outside = new FakeRemote()
+    outside.realpaths.set('/workspace/file.ts', '/outside/file.ts')
+    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('outside the workspace')
+
+    const notFile = new FakeRemote()
+    notFile.infos.set('/workspace/file.ts', { type: FileType.DIR, size: 0 })
+    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not a regular file')
+
+    const tooLarge = new FakeRemote()
+    tooLarge.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 21 })
+    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('over the 20-byte limit')
+
+    const grew = new FakeRemote()
+    grew.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
+    grew.contents.set('/workspace/file.ts', Buffer.alloc(21))
+    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('grew past')
+
+    const invalid = new FakeRemote()
+    invalid.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
+    invalid.contents.set('/workspace/file.ts', Uint8Array.from([0xff]))
+    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not valid UTF-8')
+
+    await expect(canonicalizeE2BWorkspace(new FakeRemote().sandbox, '/workspace', AbortSignal.abort('stop')))
+      .rejects.toBe('stop')
+  })
+})
+
+describe('E2BLspProvider pooling and lifecycle', () => {
+  it('reuses one canonical-workspace instance and constructs the remote proxy transport', async () => {
+    const spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())
+    const remote = new FakeRemote()
+    mockedLsp.FakeLspInstance.plans.push({ query: async () => ({ kind: 'hover', hover: { contents: 'ok' } }) })
+    const current = provider(remote, subprocess(spawn))
+
+    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
+    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
+    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(1)
+    expect(mockedLsp.FakeLspInstance.instances[0]?.spec).toMatchObject({ clientProcessId: null, cwd: '/workspace' })
+    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
+      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs', expect.any(String)],
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 128 } },
+    }))
+    expect(current.id).toBe('fixture')
+    expect(current.extensionToLanguage).toEqual({ '.ts': 'typescript' })
+    await current.disposeAll()
+    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
+  })
+
+  it('replaces one transport failure, but preserves ordinary query errors', async () => {
+    const transportFailure = new Error('transport failed')
+    mockedLsp.FakeLspInstance.plans.push(
+      { transportFailure, query: async () => { throw transportFailure } },
+      { query: async () => ({ kind: 'hover', hover: { contents: 'retried' } }) },
+    )
+    const retried = provider()
+    await expect(retried.query(query())).resolves.toMatchObject({ hover: { contents: 'retried' } })
+    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
+    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
+
+    const ordinary = new Error('ordinary failure')
+    mockedLsp.FakeLspInstance.plans.push(
+      { query: async () => { throw ordinary }, dead: true },
+      { query: async () => ({ kind: 'hover', hover: null }) },
+    )
+    const failed = provider()
+    await expect(failed.query(query())).rejects.toBe(ordinary)
+    await expect(failed.query(query())).resolves.toMatchObject({ kind: 'hover' })
+  })
+
+  it('evicts a server that dies after a successful query', async () => {
+    mockedLsp.FakeLspInstance.plans.push(
+      { deadAfterQuery: true, query: async () => ({ kind: 'hover', hover: null }) },
+      { query: async () => ({ kind: 'hover', hover: null }) },
+    )
+    const current = provider()
+    await current.query(query())
+    await current.query(query())
+    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
+    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
+  })
+
+  it('serializes a workspace queue, observes queued abort, and awaits work on disposal', async () => {
+    const first = Promise.withResolvers<unknown>()
+    mockedLsp.FakeLspInstance.plans.push({ query: () => first.promise })
+    const current = provider()
+    const running = current.query(query())
+    const controller = new AbortController()
+    const queued = current.query(query(), controller.signal)
+    await new Promise(resolve => setImmediate(resolve))
+    controller.abort('queued stop')
+    await expect(queued).rejects.toBe('queued stop')
+
+    const disposing = current.disposeAll()
+    first.resolve({ kind: 'hover', hover: null })
+    await expect(running).resolves.toMatchObject({ kind: 'hover' })
+    await disposing
+    await expect(current.query(query())).rejects.toMatchObject({ code: 'LSP_DISPOSED' })
+  })
+
+  it('covers pre-abort, synthetic abort, resolve, and rejection in the queue race', async () => {
+    const current = provider()
+    const internal = current as unknown as {
+      queues: Map<string, Promise<void>>
+      enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T>
+    }
+    await expect(internal.enqueue('pre', AbortSignal.abort('pre-stop'), async () => 'unused')).rejects.toBe('pre-stop')
+
+    const signal = new AbortController().signal
+    await expect(internal.enqueue('resolve', signal, async () => 'ok')).resolves.toBe('ok')
+
+    const failure = new Error('queue failed')
+    const rejected = Promise.reject<undefined>(failure)
+    void rejected.catch(() => {})
+    internal.queues.set('reject', rejected)
+    await expect(internal.enqueue('reject', signal, async () => 'unused')).rejects.toBe(failure)
+
+    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Exercise normalization at the promise boundary.
+    const opaque = Promise.reject<undefined>('opaque queue failure')
+    void opaque.catch(() => {})
+    internal.queues.set('opaque', opaque)
+    await expect(internal.enqueue('opaque', signal, async () => 'unused')).rejects.toEqual(new Error('opaque queue failure'))
+
+    const synthetic = {
+      aborted: false,
+      reason: undefined,
+      throwIfAborted() {},
+      addEventListener(_type: string, listener: () => void) { listener() },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    await expect(internal.enqueue('synthetic', synthetic, async () => 'unused')).rejects.toMatchObject({ name: 'AbortError' })
+    await current.disposeAll()
+  })
+})
+
+describe('lsp-e2b plugin composition', () => {
+  function pluginContext(
+    remote: FakeRemote,
+    service: E2BSubprocessService,
+    registerProvider = vi.fn(() => vi.fn()),
+  ) {
+    const effects: Array<() => void | Promise<void>> = []
+    const ctx = {
+      subprocess: service,
+      e2b: {
+        runtimeRoot: '/workspace/.dsh-e2b',
+        getSandbox: async () => remote.sandbox,
+      },
+      lsp: { registerProvider },
+      effect: (callback: () => (() => void | Promise<void>)) => { effects.push(callback()) },
+    } as unknown as Context
+    return { ctx, effects, registerProvider }
+  }
+
+  it('installs one proxy, resolves commands, registers providers, and disposes them', async () => {
+    const remote = new FakeRemote()
+    const fixture = pluginContext(remote, subprocess())
+    await apply(fixture.ctx, { servers: { one: server(), two: server({ command: 'server-two' }) } })
+    expect(remote.writes).toHaveLength(1)
+    expect(remote.writes[0]?.[0]?.path).toBe('/workspace/.dsh-e2b/lsp-stdio-proxy.mjs')
+    expect(remote.commands).toContain("chmod 600 -- '/workspace/.dsh-e2b/lsp-stdio-proxy.mjs'")
+    expect(fixture.registerProvider).toHaveBeenCalledTimes(2)
+    await fixture.effects[0]?.()
+  })
+
+  it('rolls back partial registration and rejects invalid composition/configuration', async () => {
+    const remote = new FakeRemote()
+    const firstDispose = vi.fn()
+    const register = vi.fn()
+      .mockReturnValueOnce(firstDispose)
+      .mockImplementationOnce(() => { throw new Error('duplicate provider') })
+    const rollback = pluginContext(remote, subprocess(), register)
+    await expect(apply(rollback.ctx, { servers: { one: server(), two: server() } })).rejects.toThrow('duplicate provider')
+    expect(firstDispose).toHaveBeenCalledOnce()
+
+    const wrong = pluginContext(remote, {} as E2BSubprocessService)
+    await expect(apply(wrong.ctx, { servers: { one: server() } })).rejects.toThrow('dsh-subprocess-e2b')
+
+    const empty = pluginContext(remote, subprocess())
+    await expect(apply(empty.ctx, { servers: {} })).rejects.toThrow('at least one server')
+
+    for (const [id, config] of [
+      ['', server()],
+      ['one', server({ command: '' })],
+      ['one', server({ maxMessageBytes: 0 })],
+      ['one', server({ maxStderrBytes: 1.5 })],
+      ['one', server({ shutdownTimeoutMs: 2_147_483_648 })],
+    ] as const) {
+      const fixture = pluginContext(new FakeRemote(), subprocess())
+      await expect(apply(fixture.ctx, { servers: { [id]: config } })).rejects.toThrow()
+    }
+  })
+
+  it('registers the package-owned invariant companion', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BLspInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/lsp/lsp-e2b/tests/transport.spec.ts b/packages/lsp/lsp-e2b/tests/transport.spec.ts
new file mode 100644
index 0000000000..ae5106bc09
--- /dev/null
+++ b/packages/lsp/lsp-e2b/tests/transport.spec.ts
@@ -0,0 +1,181 @@
+import { once } from 'node:events'
+import { PassThrough } from 'node:stream'
+import { describe, expect, it } from 'vitest'
+import { encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
+import type { SubprocessHandle, SubprocessOutcome } from '@deepseek-ai/dsh-subprocess'
+import { E2BLspTransport } from '@deepseek-ai/dsh-lsp-e2b'
+
+class FakeHandle implements SubprocessHandle {
+  readonly pid = 321
+  readonly stdin: PassThrough | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr = undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly result = Promise.withResolvers<SubprocessOutcome>()
+  readonly done = this.result.promise
+  terminated = 0
+  waitResult = true
+
+  constructor(options: { stdin?: boolean; stdout?: boolean; diagnostic?: string } = {}) {
+    this.stdin = options.stdin === false ? undefined : new PassThrough()
+    this.stdout = options.stdout === false ? undefined : new PassThrough()
+    this.collected = options.diagnostic === undefined
+      ? {}
+      : { stderr: { readFrom: () => ({ text: options.diagnostic as string, nextOffset: 0, lossy: false }) } }
+  }
+
+  terminate(): void {
+    this.terminated += 1
+  }
+
+  async waitForExit(): Promise<boolean> {
+    return this.waitResult
+  }
+
+  resolve(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
+    this.stdout?.end()
+    this.result.resolve(outcome)
+  }
+
+  reject(error: unknown): void {
+    this.stdout?.end()
+    this.result.reject(error)
+  }
+}
+
+function proxyFrame(type: 'stdout' | 'stderr', data: string | Buffer): string {
+  return encodeE2BFrame({ type, data: Buffer.from(data).toString('base64') })
+}
+
+describe('E2BLspTransport', () => {
+  it('frames stdin, decodes split byte output, and exposes handle lifecycle', async () => {
+    const inner = new FakeHandle({ diagnostic: 'proxy diagnostic' })
+    const transport = new E2BLspTransport(inner, 1_024, 64)
+    let stdin = ''
+    inner.stdin?.on('data', (chunk) => { stdin += String(chunk) })
+    let stdout = Buffer.alloc(0)
+    transport.stdout.on('data', (chunk) => { stdout = Buffer.concat([stdout, chunk]) })
+
+    transport.stdin.write(Buffer.from([0, 0xff]))
+    await new Promise(resolve => setImmediate(resolve))
+    const encodedInput = stdin.trim()
+    const input = JSON.parse(Buffer.from(encodedInput, 'base64').toString('utf8')) as Record<string, string>
+    expect(input).toEqual({ type: 'stdin', data: 'AP8=' })
+
+    const frames = proxyFrame('stdout', Buffer.from([0, 0xff]))
+      + proxyFrame('stderr', 'server diagnostic')
+      + encodeE2BFrame({ type: 'exit', code: 0, signal: null })
+    inner.stdout?.write(frames.slice(0, 7))
+    inner.stdout?.write(frames.slice(7))
+    inner.stdout?.write(proxyFrame('stderr', ''))
+    inner.stdout?.write(encodeE2BFrame({ type: 'exit', code: null, signal: 'SIGTERM' }))
+    inner.resolve()
+
+    await expect(transport.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(stdout).toEqual(Buffer.from([0, 0xff]))
+    expect(transport.collected.stderr?.readFrom(0).text).toBe('server diagnosticproxy diagnostic')
+    expect(transport.pid).toBe(321)
+    inner.waitResult = false
+    await expect(transport.waitForExit()).resolves.toBe(false)
+    transport.terminate()
+    expect(inner.terminated).toBe(1)
+  })
+
+  it('ends the inner stdin and retains a bounded byte tail with independent offsets', async () => {
+    const inner = new FakeHandle()
+    const transport = new E2BLspTransport(inner, 1_024, 4)
+    const finished = once(inner.stdin!, 'finish')
+    transport.stdin.end()
+    await finished
+
+    inner.stdout?.write(proxyFrame('stderr', 'ab'))
+    inner.stdout?.write(proxyFrame('stderr', 'cdef'))
+    const reader = transport.collected.stderr!
+    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
+    expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
+    expect(() => reader.readFrom(-1)).toThrow('non-negative safe integer')
+    expect(() => reader.readFrom(1.5)).toThrow('non-negative safe integer')
+    inner.resolve()
+    await transport.done
+
+    const partialInner = new FakeHandle()
+    const partial = new E2BLspTransport(partialInner, 1_024, 4)
+    partialInner.stdout?.write(proxyFrame('stderr', 'abcdef'))
+    expect(partial.collected.stderr?.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
+    partialInner.resolve()
+    await partial.done
+  })
+
+  it.each([
+    ['non-object', encodeE2BFrame(null), 'malformed frame'],
+    ['wrong type', encodeE2BFrame({ type: 'other', data: '' }), 'malformed frame'],
+    ['invalid exit', encodeE2BFrame({ type: 'exit', code: 'zero', signal: null }), 'malformed frame'],
+    ['missing data', encodeE2BFrame({ type: 'stdout' }), 'malformed frame'],
+    ['invalid base64', encodeE2BFrame({ type: 'stdout', data: 'abc' }), 'invalid base64'],
+    ['invalid outer frame', 'not-base64\n', 'invalid base64'],
+    ['non-ASCII outer frame', 'é', 'non-ASCII'],
+  ])('fails %s proxy traffic and terminates the group', async (_name, frame, message) => {
+    const inner = new FakeHandle()
+    const transport = new E2BLspTransport(inner, 1_024, 32)
+    inner.stdout?.write(frame)
+    inner.stdout?.write(proxyFrame('stdout', 'ignored'))
+    inner.stdout?.emit('error', new Error('second failure'))
+    inner.resolve()
+    await expect(transport.done).rejects.toThrow(message)
+    expect(inner.terminated).toBe(1)
+  })
+
+  it('fails truncated frames and preserves inner spawn rejection', async () => {
+    const truncatedInner = new FakeHandle()
+    const truncated = new E2BLspTransport(truncatedInner, 1_024, 32)
+    truncatedInner.stdout?.write('YQ==')
+    truncatedInner.resolve()
+    await expect(truncated.done).rejects.toThrow('mid-frame')
+
+    const rejectedInner = new FakeHandle({ diagnostic: 'tail' })
+    const rejected = new E2BLspTransport(rejectedInner, 1_024, 32)
+    rejectedInner.reject(new Error('spawn failed'))
+    await expect(rejected.done).rejects.toThrow('spawn failed')
+    expect(rejected.collected.stderr?.readFrom(0).text).toBe('tail')
+  })
+
+  it('forwards output and input stream errors without an unhandled inner error', async () => {
+    const outputInner = new FakeHandle()
+    const output = new E2BLspTransport(outputInner, 1_024, 32)
+    outputInner.stdout?.emit('error', new Error('proxy stdout failed'))
+    outputInner.resolve()
+    await expect(output.done).rejects.toThrow('proxy stdout failed')
+
+    const inputInner = new FakeHandle()
+    const input = new E2BLspTransport(inputInner, 1_024, 32)
+    const outerError = once(input.stdin, 'error')
+    inputInner.stdin?.emit('error', new Error('proxy stdin failed'))
+    await expect(outerError).resolves.toMatchObject([{ message: 'proxy stdin failed' }])
+    inputInner.resolve()
+    await input.done
+  })
+
+  it('normalizes a non-Error decoder throw', async () => {
+    const inner = new FakeHandle()
+    const transport = new E2BLspTransport(inner, 1_024, 32)
+    const internal = transport as unknown as {
+      decoder: { push(chunk: string): unknown[] }
+      onProxyData(chunk: Buffer): void
+    }
+    internal.decoder = { push: () => { throw 'raw decoder failure' } }
+    internal.onProxyData(Buffer.from('x'))
+    inner.resolve()
+    await expect(transport.done).rejects.toThrow('raw decoder failure')
+  })
+
+  it('rejects a subprocess that drops either required pipe', () => {
+    const missingStdin = new FakeHandle({ stdin: false })
+    const missingStdout = new FakeHandle({ stdout: false })
+    expect(() => new E2BLspTransport(missingStdin, 10, 10)).toThrow('dropped a piped stream')
+    expect(() => new E2BLspTransport(missingStdout, 10, 10)).toThrow('dropped a piped stream')
+    expect(missingStdin.terminated).toBe(1)
+    expect(missingStdout.terminated).toBe(1)
+  })
+})
diff --git a/packages/lsp/lsp-e2b/tsconfig.json b/packages/lsp/lsp-e2b/tsconfig.json
new file mode 100644
index 0000000000..4679845db8
--- /dev/null
+++ b/packages/lsp/lsp-e2b/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../e2b/e2b" },
+    { "path": "../lsp" },
+    { "path": "../lsp-local" },
+    { "path": "../../subprocess/subprocess" },
+    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../../util/timeout" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 318704b9fc..d643db1528 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -7,6 +7,7 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
+import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -30,12 +31,12 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
-  /** Canonical workspace file URI supplied by the filesystem provider. */
-  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
   readonly shutdownTimeoutMs: number
+  /** PID advertised to the server; `null` when client and server do not share a process namespace. */
+  readonly clientProcessId?: number | null
 }
 
 /**
@@ -109,11 +110,9 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      // A subprocess provider may run in another PID namespace or machine;
-      // the host PID would let the server monitor an unrelated process.
-      processId: null,
-      rootUri: this.spec.workspaceUri,
-      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
+      processId: this.spec.clientProcessId === undefined ? process.pid : this.spec.clientProcessId,
+      rootUri: pathToFileURL(this.spec.cwd).href,
+      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -150,7 +149,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = source.fileUrl
+    const uri = pathToFileURL(source.canonicalPath).href
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
@@ -244,9 +243,10 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
-    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
+    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
+    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
+    // display paths against, not the request's possibly-symlinked workspaceRoot.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {
diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts
index 9399b5a1a7..89053894ee 100644
--- a/packages/lsp/lsp-local/tests/fixture-server.ts
+++ b/packages/lsp/lsp-local/tests/fixture-server.ts
@@ -15,6 +15,7 @@
  * - LSP_FAKE_REPLY_DELAY_MS: delays each textDocument/* response by this many milliseconds.
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
+ * - LSP_FAKE_EXPECT_PROCESS_ID: expected JSON `initialize.processId`; mismatch exits nonzero.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
  * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
  * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
@@ -37,6 +38,7 @@ const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1'
 const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
 const openMarker = process.env.LSP_FAKE_OPEN_MARKER
 const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
+const expectedProcessId = process.env.LSP_FAKE_EXPECT_PROCESS_ID
 const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
 const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0)
 const exitMarker = process.env.LSP_FAKE_EXIT_MARKER
@@ -102,6 +104,10 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
     return
   }
   if (method === 'initialize') {
+    if (expectedProcessId !== undefined) {
+      const params = message.params as { processId?: unknown } | undefined
+      if (JSON.stringify(params?.processId) !== expectedProcessId) process.exit(2)
+    }
     if (garbage) process.stdout.write('this is not a framed message\r\n')
     send({
       id,
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 08bad67ae2..939b58f0b1 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -109,6 +109,11 @@ const RESPONDING_SERVER =
 const locJson = () => JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
 
 describe('LspInstance server-request handling', () => {
+  it('advertises a null process id across process namespaces', async () => {
+    const instance = makeInstance({ LSP_FAKE_EXPECT_PROCESS_ID: 'null', LSP_FAKE_DEF: 'null' }, { clientProcessId: null })
+    await expect(run(instance, 'goToDefinition')).resolves.toMatchObject({ kind: 'locations' })
+  })
+
   it('answers workspace/configuration with the static config per item', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() })
     // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index 02649a8d39..b672a405de 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
-README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
-README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
+README.md: bcffd460f192b0e6ac214ad0bc0d43da4c81d68c
+README.zh.md: e9df352e999834235a66ef7a500e300dadc2029c
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index 5c1044be50..4dc0436bbb 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -10,6 +10,7 @@ This package is the interface third of the LSP capability:
 |---|---|
 | `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
 | `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
+| `@deepseek-ai/dsh-lsp-e2b` | a generic E2B backend that registers configured remote stdio providers |
 | `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
 
 The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index cc412333e6..fdaedc9a96 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -10,6 +10,7 @@
 |---|---|
 | `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
+| `@deepseek-ai/dsh-lsp-e2b` | 通用 E2B 后端，注册已配置的远程 stdio 提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
 该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 65d541a7c1..c0fa873642 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: a4f743056b4a524be9623b0f700f37e0534b463f
-README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
+README.md: 239c751f30f8e5c543e6737e65a67f9bb22f79ad
+README.zh.md: edaae7f948d957e2fce2b3f331cc2af61cfabd36
diff --git a/packages/pty/README.md b/packages/pty/README.md
index a4f743056b..239c751f30 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -7,7 +7,8 @@ English | [中文](README.zh.md)
 | Package | Role | ctx key |
 |---|---|---|
 | [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
-| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
+| [`pty-local`](pty-local/README.md) (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
+| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
+The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index c84ad3f1b5..edaae7f948 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -7,7 +7,8 @@
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
-| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
+| [`pty-local`](pty-local/README.md)（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
+| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
+核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
diff --git a/packages/pty/pty-e2b/README.i18n.yaml b/packages/pty/pty-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..bfd7795349
--- /dev/null
+++ b/packages/pty/pty-e2b/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/pty/pty-e2b/README.md
+README.md: 7a8ddc9e08f4d28d69b97825232b00e2d8f394b7
+README.zh.md: 2151ca1f2d91b01a7b0106153f708ace2c3d2726
diff --git a/packages/pty/pty-e2b/README.md b/packages/pty/pty-e2b/README.md
new file mode 100644
index 0000000000..7a8ddc9e08
--- /dev/null
+++ b/packages/pty/pty-e2b/README.md
@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-pty-e2b
+
+English | [中文](README.zh.md)
+
+E2B byte-PTY backend for [`ctx.pty`](../pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
+
+## Plugin and configuration
+
+The `pty-e2b` plugin injects `e2b` and `pty`, then registers one backend under `backendType`.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `backendType` | `shell` | Registry type selected by `terminal_open`. |
+| `rows` / `cols` | `40` / `160` | Initial remote PTY size. |
+| `scrollbackLines` | `10000` | Maximum retained logical lines. |
+| `scrollbackMaxBytes` | `4194304` | Maximum retained UTF-8 scrollback bytes. |
+| `maxReadBytes` | `262144` | Maximum bytes returned by one read or settled send. |
+| `pollIntervalMs` | `50` | Host readiness-poll interval. |
+| `idleSilenceMs` | `3000` | Output silence that yields `inferred_idle`. |
+| `timeoutMs` | `30000` | Absolute startup and send wait bound. |
+| `disposeGraceMs` | `3000` | TERM-to-KILL cleanup grace. |
+
+Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute.
+
+## Runtime contract
+
+The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
+
+Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. Close sends `SIGTERM` to the PTY process group, waits, escalates through E2B's PTY kill, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
+
+The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
+
+## Model Experience
+
+### Indirect consumer
+
+#### What the model sees
+
+Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, signal results, and cleanup failures.
+
+#### Token effect
+
+None until a consumer returns bounded backend output. Retained host PTY scrollback is not placed in model history by this package.
+
+#### KV Cache effect
+
+No direct invalidation; the consumer owns prompts, schemas, and appended results.
+
+## Known Limitations and Deferred Work
+
+- **Line-oriented terminal model** — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
+- **Readiness is marker-or-silence based** — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so `inferred_idle` is deliberately possible.
+- **UTF-8 only** — invalid byte sequences fail the session instead of returning lossy text.
+- **No reconnectable terminal handles** — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.
diff --git a/packages/pty/pty-e2b/README.zh.md b/packages/pty/pty-e2b/README.zh.md
new file mode 100644
index 0000000000..2151ca1f2d
--- /dev/null
+++ b/packages/pty/pty-e2b/README.zh.md
@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-pty-e2b
+
+[English](README.md) | 中文
+
+用于 [`ctx.pty`](../pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
+
+## 插件与配置
+
+`pty-e2b` 插件注入 `e2b` 和 `pty`，然后以 `backendType` 注册一个后端。
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `backendType` | `shell` | `terminal_open` 选择的注册表类型。 |
+| `rows` / `cols` | `40` / `160` | 远程 PTY 的初始尺寸。 |
+| `scrollbackLines` | `10000` | 保留的逻辑行数上限。 |
+| `scrollbackMaxBytes` | `4194304` | 保留的 UTF-8 scrollback 字节数上限。 |
+| `maxReadBytes` | `262144` | 单次读取或发送结算时返回的字节数上限。 |
+| `pollIntervalMs` | `50` | 宿主就绪轮询间隔。 |
+| `idleSilenceMs` | `3000` | 触发 `inferred_idle` 的输出静默时长。 |
+| `timeoutMs` | `30000` | 启动与发送等待的绝对上限。 |
+| `disposeGraceMs` | `3000` | TERM 到 KILL 的清理宽限期。 |
+
+数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。
+
+## 运行时契约
+
+该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
+
+每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。关闭操作向 PTY 进程组发送 `SIGTERM`，等待后通过 E2B 的 PTY kill 操作升级，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
+
+远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
+
+## 模型体验
+
+### 间接消费方
+
+#### 模型看到的内容
+
+没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因、信号结果和清理失败。
+
+#### Token 影响
+
+消费方返回有界的后端输出前没有影响。本包不会把宿主保留的 PTY scrollback 放入模型历史。
+
+#### KV Cache 影响
+
+不会直接失效；提示词、schema 和追加结果由消费方负责。
+
+## 已知限制与暂缓工作
+
+- **面向行的终端模型**：CSI／OSC 控制序列会被移除；备用屏幕与完整终端仿真仍不受支持。
+- **就绪判断基于标记或静默**：E2B 会公开前台进程组，但不提供本地后端使用的 Linux syscall 检查，因此系统有意保留返回 `inferred_idle` 的可能性。
+- **仅支持 UTF-8**：无效字节序列会使会话失败，而不是返回有损文本。
+- **没有可重连的终端句柄**：保留 E2B 沙箱会保留远程文件，但不会保留宿主所有权、缓冲区、回调或实时 PTY 会话。
diff --git a/packages/pty/pty-e2b/package.json b/packages/pty/pty-e2b/package.json
new file mode 100644
index 0000000000..cc31699ab1
--- /dev/null
+++ b/packages/pty/pty-e2b/package.json
@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-pty-e2b",
+  "description": "E2B PTY provider for DeepSeek Harness",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-pty": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-pty": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/pty/pty-e2b/src/config.ts b/packages/pty/pty-e2b/src/config.ts
new file mode 100644
index 0000000000..e6849bf54d
--- /dev/null
+++ b/packages/pty/pty-e2b/src/config.ts
@@ -0,0 +1,64 @@
+/** Validated configuration for the E2B PTY backend. */
+
+import z from 'schemastery'
+
+/** Public plugin configuration. */
+export interface Config {
+  /** Backend registry type. */
+  backendType?: string
+  /** Initial terminal rows. */
+  rows?: number
+  /** Initial terminal columns. */
+  cols?: number
+  /** Maximum retained logical lines. */
+  scrollbackLines?: number
+  /** Maximum retained UTF-8 bytes. */
+  scrollbackMaxBytes?: number
+  /** Maximum bytes returned by one read or settled viewport. */
+  maxReadBytes?: number
+  /** Readiness polling interval. */
+  pollIntervalMs?: number
+  /** Output silence duration that yields `inferred_idle`. */
+  idleSilenceMs?: number
+  /** Absolute send and startup wait bound. */
+  timeoutMs?: number
+  /** Grace before PTY teardown escalates from TERM to KILL. */
+  disposeGraceMs?: number
+}
+
+/** Configuration after Schemastery defaults. */
+export type ResolvedConfig = Required<Config>
+
+/* jscpd:ignore-start -- Loader requires a backend-local schema and load-time diagnostics. */
+/** Schemastery config exposed by the plugin. */
+export const Config: z<Config> = z.object({
+  backendType: z.string().default('shell'),
+  rows: z.number().default(40),
+  cols: z.number().default(160),
+  scrollbackLines: z.number().default(10_000),
+  scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
+  maxReadBytes: z.number().default(256 * 1024),
+  pollIntervalMs: z.number().default(50),
+  idleSilenceMs: z.number().default(3_000),
+  timeoutMs: z.number().default(30_000),
+  disposeGraceMs: z.number().default(3_000),
+})
+
+/**
+ * Validate the resolved configuration before publishing the backend.
+ * @param config - Schemastery-resolved plugin configuration.
+ * @returns Nothing; success narrows every optional field to its resolved value.
+ */
+export function validateConfig(config: Config): asserts config is ResolvedConfig {
+  const resolved = config as ResolvedConfig
+  if (resolved.backendType.length === 0) throw new Error('pty-e2b: backendType must be non-empty')
+  for (const [name, value] of Object.entries(resolved)) {
+    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`pty-e2b: ${name} must be a positive safe integer`)
+    }
+  }
+  if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) {
+    throw new Error('pty-e2b: maxReadBytes must not exceed scrollbackMaxBytes')
+  }
+}
+/* jscpd:ignore-end */
diff --git a/packages/pty/pty-e2b/src/index.ts b/packages/pty/pty-e2b/src/index.ts
new file mode 100644
index 0000000000..fca16cf5c7
--- /dev/null
+++ b/packages/pty/pty-e2b/src/index.ts
@@ -0,0 +1,93 @@
+/** E2B byte-PTY backend for persistent interactive terminal sessions. */
+
+import { posix } from 'node:path'
+import type { Context } from 'cordis'
+import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
+import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
+import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
+import { E2BPtySession } from './session.ts'
+
+export { Config } from './config.ts'
+export type { Config as PtyE2BConfig } from './config.ts'
+export { E2BPtySession } from './session.ts'
+
+/** Cordis plugin name. */
+export const name = 'pty-e2b'
+/** Required shared sandbox owner and PTY registry. */
+export const inject = ['e2b', 'pty']
+
+function terminalEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+  return {
+    TERM: 'dumb',
+    PAGER: 'cat',
+    GIT_PAGER: 'cat',
+    PS1: 'dsh> ',
+    PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
+    BASH_SILENCE_DEPRECATION_WARNING: '1',
+    DSH_SHELL: '1',
+    DSH_SESSION_ID: spec.owner.id,
+    DSH_PTY_SESSION_ID: spec.sessionId,
+  }
+}
+
+/** E2B backend registered under the configured terminal type. */
+export class E2BPtyBackend implements PtyBackend {
+  readonly type: string
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: ResolvedConfig,
+    private readonly createPty: (
+      sandbox: Sandbox,
+      options: Parameters<Sandbox['pty']['create']>[0],
+    ) => Promise<CommandHandle> = (sandbox, options) => sandbox.pty.create(options),
+  ) {
+    this.type = config.backendType
+  }
+
+  /** Create, initialize, and publish one remote PTY session. */
+  async spawn(spec: PtyBackendSpawnSpec): Promise<E2BPtySession> {
+    spec.signal?.throwIfAborted()
+    const sandbox = await this.ctx.e2b.getSandbox()
+    spec.signal?.throwIfAborted()
+    const pending: Uint8Array[] = []
+    const created: { session?: E2BPtySession } = {}
+    const handle = await this.createPty(sandbox, {
+      rows: this.config.rows,
+      cols: this.config.cols,
+      cwd: posix.resolve(this.ctx.e2b.cwd, spec.cwd ?? this.ctx.e2b.cwd),
+      envs: terminalEnvironment(spec),
+      timeoutMs: 0,
+      ...spec.signal === undefined ? {} : { signal: spec.signal },
+      onData: (data) => {
+        if (created.session === undefined) pending.push(Uint8Array.from(data))
+        else created.session.onData(data)
+      },
+    })
+    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+      await handle.kill().catch(() => false)
+      throw new Error(`pty-e2b: E2B returned invalid PTY pid ${handle.pid}`)
+    }
+    const session = new E2BPtySession(sandbox, handle, this.config)
+    created.session = session
+    for (const data of pending) session.onData(data)
+    try {
+      await session.initialize(spec.signal)
+      return session
+    } catch (error: unknown) {
+      try {
+        await session.close('E2B PTY startup failed')
+      } catch (cleanupError: unknown) {
+        throw new PtyBackendCleanupError(error, cleanupError)
+      }
+      throw error
+    }
+  }
+}
+
+/** Register the E2B PTY backend. */
+export function apply(ctx: Context, config: Config): void {
+  validateConfig(config)
+  ctx.pty.registerBackend(new E2BPtyBackend(ctx, config))
+}
diff --git a/packages/pty/pty-e2b/src/invariant.ts b/packages/pty/pty-e2b/src/invariant.ts
new file mode 100644
index 0000000000..b86fdffc5d
--- /dev/null
+++ b/packages/pty/pty-e2b/src/invariant.ts
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-pty-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-pty-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'pty-e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the PTY registry owns publication and cleanup. */
+const install: InvariantInstaller = () => {}
+
+/** Register this package's invariant companion. */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/pty/pty-e2b/src/session.ts b/packages/pty/pty-e2b/src/session.ts
new file mode 100644
index 0000000000..e5dfc05efe
--- /dev/null
+++ b/packages/pty/pty-e2b/src/session.ts
@@ -0,0 +1,367 @@
+/** One byte-oriented E2B PTY session projected onto the harness PTY seam. */
+
+import { Buffer } from 'node:buffer'
+import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { CommandExitError } from '@deepseek-ai/dsh-e2b'
+import {
+  PtyTerminalSanitizer,
+  PtyTextBuffer,
+  ptySignalName,
+  ptyUtf8Tail,
+} from '@deepseek-ai/dsh-pty'
+import type {
+  PtyBackendSession,
+  PtyReadRequest,
+  PtyReadResult,
+  PtySendOperation,
+  PtySendRead,
+  PtySendRequest,
+  PtySendResult,
+  PtySessionStatus,
+  PtySignal,
+  PtySignalResult,
+  PtyWaitReason,
+} from '@deepseek-ai/dsh-pty'
+import type { ResolvedConfig } from './config.ts'
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/* jscpd:ignore-start -- Operation state stays backend-local because process readiness and cleanup identities diverge. */
+class E2BSendOperation implements PtySendOperation {
+  private readonly output: PtyTextBuffer
+  private readonly result = Promise.withResolvers<PtySendResult>()
+  private finished = false
+
+  constructor(
+    maxBytes: number,
+    readonly startedAt: number,
+    private readonly onCancel: () => void,
+  ) {
+    this.output = new PtyTextBuffer(maxBytes)
+  }
+
+  get done(): Promise<PtySendResult> {
+    return this.result.promise
+  }
+
+  append(text: string): void {
+    if (!this.finished) this.output.append(text)
+  }
+
+  settle(waitReason: PtyWaitReason, sessionStatus: PtySessionStatus, inheritedTruncation: boolean): void {
+    if (this.finished) return
+    this.finished = true
+    const read = this.output.snapshot()
+    this.result.resolve({
+      viewport: read.text,
+      waitReason,
+      sessionStatus,
+      truncated: read.truncated || inheritedTruncation,
+    })
+  }
+
+  fail(error: unknown): void {
+    if (this.finished) return
+    this.finished = true
+    this.result.reject(error)
+  }
+
+  readOutput(): PtySendRead {
+    return this.output.consume()
+  }
+
+  cancel(): boolean {
+    if (this.finished) return false
+    this.onCancel()
+    return true
+  }
+}
+/* jscpd:ignore-end */
+
+/** Live session around one E2B SDK PTY handle. */
+export class E2BPtySession implements PtyBackendSession {
+  motd = ''
+  readonly pid: number
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
+  private readonly sanitizer: PtyTerminalSanitizer
+  private readonly scrollback: PtyTextBuffer
+  private readonly exited = Promise.withResolvers<void>()
+  private statusValue: PtySessionStatus = { kind: 'running' }
+  private active: E2BSendOperation | undefined
+  private activeTimer: NodeJS.Timeout | undefined
+  private activeAbort: (() => void) | undefined
+  private promptSeen = false
+  private promptTextSeen = false
+  private initializing = false
+  private lastOutputAt = Date.now()
+  private closing = false
+  private closePromise: Promise<void> | undefined
+  private closeSignal: NodeJS.Signals | null = null
+  private transportFailure: Error | undefined
+  private remoteExited = false
+
+  constructor(
+    private readonly sandbox: Sandbox,
+    private readonly handle: CommandHandle,
+    private readonly config: ResolvedConfig,
+  ) {
+    this.pid = handle.pid
+    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
+    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    const completion = handle.wait()
+    void completion.then(
+      (result) => { this.onExit(result.exitCode) },
+      (error: unknown) => {
+        if (error instanceof CommandExitError) this.onExit(error.exitCode)
+        else this.onTransportFailure(error)
+      },
+    )
+  }
+
+  /**
+   * Consume bytes received by the SDK's PTY callback.
+   * @param data - Exact callback bytes in delivery order.
+   */
+  onData(data: Uint8Array): void {
+    let decoded: string
+    try {
+      decoded = this.decoder.decode(data, { stream: true })
+    } catch (error: unknown) {
+      this.onTransportFailure(new Error('pty-e2b: PTY emitted invalid UTF-8', { cause: error }))
+      return
+    }
+    const sanitized = this.sanitizer.push(decoded)
+    this.appendOutput(sanitized.text)
+    if (sanitized.prompt) {
+      this.promptSeen = true
+      this.promptTextSeen = sanitized.promptText === true
+      this.lastOutputAt = Date.now()
+    } else if (this.promptSeen && sanitized.promptText === true) {
+      this.promptTextSeen = true
+    }
+  }
+
+  /**
+   * Await the first prompt or bounded startup fallback.
+   * @param signal - Optional startup cancellation signal.
+   */
+  async initialize(signal?: AbortSignal): Promise<void> {
+    this.initializing = true
+    try {
+      const operation = this.startSend({ text: '', submit: false, ...signal === undefined ? {} : { signal } })
+      const result = await operation.done
+      if (result.waitReason === 'session_exit') throw new Error('E2B PTY shell exited during startup')
+      if (result.waitReason === 'timeout') throw new Error('E2B PTY shell did not reach readiness before startup timeout')
+      this.motd = result.viewport
+    } catch (error: unknown) {
+      signal?.throwIfAborted()
+      throw error
+    } finally {
+      this.initializing = false
+    }
+  }
+
+  /* jscpd:ignore-start -- PTY backends share request admission while owning distinct input and readiness transports. */
+  startSend(request: PtySendRequest): PtySendOperation {
+    if (this.closing) throw new Error('E2B PTY session is closing')
+    if (this.statusValue.kind === 'exited') throw new Error('E2B PTY session has exited')
+    if (this.active !== undefined) throw new Error('E2B PTY session already has an active send')
+    if (request.signal?.aborted === true) throw new Error('E2B PTY send aborted before write')
+
+    const operation = new E2BSendOperation(
+      this.config.maxReadBytes,
+      Date.now(),
+      () => { this.interrupt(operation) },
+    )
+    this.active = operation
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    if (request.signal !== undefined) {
+      const onAbort = (): void => { operation.cancel() }
+      request.signal.addEventListener('abort', onAbort, { once: true })
+      this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
+    }
+
+    const input = `${request.text}${request.submit ? '\r' : ''}`
+    if (input.length > 0) {
+      void this.sandbox.pty.sendInput(this.pid, Buffer.from(input)).catch((error: unknown) => {
+        if (this.active === operation) this.failActive(error)
+      })
+    }
+    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    return operation
+  }
+  /* jscpd:ignore-end */
+
+  /* jscpd:ignore-start -- The seam requires identical bounded-read coordinates across backend buffers. */
+  read(request: PtyReadRequest): PtyReadResult {
+    const snapshot = this.scrollback.snapshot()
+    const lines = snapshot.text.split('\n')
+    const totalLines = snapshot.text.length === 0 ? 0 : lines.length
+    const offset = request.offset ?? 0
+    const count = request.count ?? 500
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('PTY read offset must be a non-negative safe integer')
+    if (!Number.isSafeInteger(count) || count <= 0) throw new Error('PTY read count must be a positive safe integer')
+    if (offset >= totalLines) {
+      return { text: '', totalLines, lineBegin: offset, lineEnd: offset, truncated: snapshot.truncated }
+    }
+    const end = totalLines - offset
+    const start = Math.max(0, end - count)
+    const bounded = ptyUtf8Tail(lines.slice(start, end).join('\n'), this.config.maxReadBytes)
+    const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
+    return {
+      text: bounded.text,
+      totalLines,
+      lineBegin: offset,
+      lineEnd: offset + returnedLines,
+      truncated: snapshot.truncated || bounded.truncated,
+    }
+  }
+  /* jscpd:ignore-end */
+
+  /* jscpd:ignore-start -- Signal, status, and close methods preserve the seam shape around remote identities. */
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    const pgid = await this.foregroundPgid()
+    if (signal === 'SIGKILL' && pgid === this.pid) {
+      throw new Error('refusing to SIGKILL the E2B PTY shell; use terminal_close')
+    }
+    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${pgid}`)
+    return { delivered: true, targetPgid: pgid }
+  }
+
+  status(): PtySessionStatus {
+    return this.statusValue
+  }
+
+  close(reason: string): Promise<void> {
+    this.closing = true
+    if (this.closePromise !== undefined) return this.closePromise
+    const closing = this.closeOnce(reason).catch((error: unknown) => {
+      this.closePromise = undefined
+      this.failActive(error)
+      throw error
+    })
+    this.closePromise = closing
+    return closing
+  }
+  /* jscpd:ignore-end */
+
+  private appendOutput(text: string): void {
+    if (text.length === 0) return
+    this.lastOutputAt = Date.now()
+    this.scrollback.append(text)
+    this.active?.append(text)
+  }
+
+  private pollReadiness(operation: E2BSendOperation): void {
+    if (this.active !== operation) return
+    if (this.statusValue.kind === 'exited') {
+      this.settleActive('session_exit')
+      return
+    }
+    const elapsed = Date.now() - operation.startedAt
+    const idleFor = Date.now() - this.lastOutputAt
+    if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs) {
+      this.settleActive('stdin_read')
+      return
+    }
+    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+    if (startupHasOutput && idleFor >= this.config.idleSilenceMs) {
+      this.settleActive('inferred_idle')
+      return
+    }
+    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
+  }
+
+  private settleActive(waitReason: PtyWaitReason): void {
+    const operation = this.active
+    if (operation === undefined) return
+    const inherited = this.scrollback.snapshot().truncated
+    this.clearActive()
+    operation.settle(waitReason, this.statusValue, inherited)
+  }
+
+  private clearActive(): void {
+    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    this.activeTimer = undefined
+    this.activeAbort?.()
+    this.activeAbort = undefined
+    this.active = undefined
+  }
+
+  private failActive(error: unknown): void {
+    const operation = this.active
+    if (operation === undefined) return
+    this.clearActive()
+    operation.fail(error)
+  }
+
+  private interrupt(operation: E2BSendOperation): void {
+    if (this.active !== operation) return
+    void this.signal('SIGINT').catch((error: unknown) => { this.failActive(error) })
+  }
+
+  private async foregroundPgid(): Promise<number> {
+    const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
+    const raw = result.stdout.trim()
+    const pgid = Number(raw)
+    if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid)) {
+      throw new Error(`cannot resolve foreground process group for E2B PTY ${this.pid}`)
+    }
+    return pgid
+  }
+
+  private onExit(exitCode: number): void {
+    this.remoteExited = true
+    let tail = ''
+    try {
+      tail = this.decoder.decode()
+    } catch (error: unknown) {
+      this.transportFailure ??= new Error('pty-e2b: PTY ended with invalid UTF-8', { cause: error })
+    }
+    this.appendOutput(this.sanitizer.push(tail).text)
+    this.appendOutput(this.sanitizer.flush())
+    const inferredSignal = this.closeSignal ?? (exitCode > 128 ? ptySignalName(exitCode - 128) : null)
+    this.statusValue = {
+      kind: 'exited',
+      exitCode: inferredSignal === null ? exitCode : null,
+      signal: inferredSignal,
+    }
+    if (this.transportFailure === undefined) this.settleActive('session_exit')
+    else this.failActive(this.transportFailure)
+    this.exited.resolve()
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+  }
+
+  private async closeOnce(reason: string): Promise<void> {
+    if (!this.remoteExited) {
+      this.closeSignal = 'SIGTERM'
+      try {
+        await this.sandbox.commands.run(`kill -TERM -- -${this.pid}`)
+      } catch (error: unknown) {
+        if (!(error instanceof CommandExitError)) throw error
+      }
+      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (!this.remoteExited) {
+      this.closeSignal = 'SIGKILL'
+      await this.sandbox.pty.kill(this.pid)
+      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (!this.remoteExited) {
+      throw new Error(`E2B PTY cleanup failed (${reason}); surviving pid: ${this.pid}`)
+    }
+    this.settleActive('session_exit')
+    await this.handle.disconnect().catch(() => {})
+    if (this.transportFailure !== undefined) throw this.transportFailure
+  }
+}
diff --git a/packages/pty/pty-e2b/tests/index.spec.ts b/packages/pty/pty-e2b/tests/index.spec.ts
new file mode 100644
index 0000000000..567b3b9215
--- /dev/null
+++ b/packages/pty/pty-e2b/tests/index.spec.ts
@@ -0,0 +1,195 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/dsh-pty'
+import { E2BPtyBackend, apply } from '@deepseek-ai/dsh-pty-e2b'
+import { validateConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
+import * as E2BPtyInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+
+function config() {
+  return {
+    backendType: 'shell', rows: 24, cols: 80,
+    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
+    pollIntervalMs: 1, idleSilenceMs: 2, timeoutMs: 5, disposeGraceMs: 1,
+  }
+}
+
+function owner(ctx: Context): Agent {
+  const id = SessionId('owner')
+  return {
+    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
+    followup: () => AgentMessageId('unused'), steer: () => AgentMessageId('unused'),
+    inject: () => AgentMessageId('unused'), send: () => AgentMessageId('unused'),
+    cancel() {}, whenIdle: () => Promise.resolve(),
+  }
+}
+
+function handle(pid = 123, kill = vi.fn().mockResolvedValue(true)): CommandHandle {
+  const result = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
+  return {
+    pid,
+    wait: () => result.promise,
+    kill,
+    disconnect: vi.fn().mockResolvedValue(undefined),
+  } as unknown as CommandHandle
+}
+
+describe('E2BPtyBackend and plugin', () => {
+  it('creates a remote PTY with isolated environment and initializes the session', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const sandbox = {} as Sandbox
+    ctx.provide('e2b', {
+      cwd: '/workspace',
+      getSandbox: async () => sandbox,
+    } as E2BSandboxService)
+    const created = handle()
+    let options: Parameters<Sandbox['pty']['create']>[0] | undefined
+    const backend = new E2BPtyBackend(ctx, config(), async (_sandbox, received) => {
+      options = received
+      void received.onData(Buffer.from('banner\n'))
+      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
+      return created
+    })
+    const pending = backend.spawn({
+      sessionId: PtySessionId('pty-1'), owner: owner(ctx), type: 'shell', cwd: 'project',
+      signal: new AbortController().signal,
+    })
+    await vi.advanceTimersByTimeAsync(2)
+    const session = await pending
+
+    expect(session.motd).toBe('dsh> ')
+    expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
+    expect(options?.envs).toMatchObject({
+      TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
+      DSH_SHELL: '1', DSH_SESSION_ID: 'owner', DSH_PTY_SESSION_ID: 'pty-1',
+    })
+    vi.useRealTimers()
+  })
+
+  it('uses the SDK PTY create method and the shared cwd by default', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const created = handle()
+    const create = vi.fn(async (received: Parameters<Sandbox['pty']['create']>[0]) => {
+      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
+      return created
+    })
+    const sandbox = { pty: { create } } as unknown as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
+    const backend = new E2BPtyBackend(ctx, config())
+    const pending = backend.spawn({ sessionId: PtySessionId('default'), owner: owner(ctx), type: 'shell' })
+    await vi.advanceTimersByTimeAsync(2)
+    await pending
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ cwd: '/workspace' }))
+    vi.useRealTimers()
+  })
+
+  it('rejects aborts and invalid pids, killing a malformed SDK handle', async () => {
+    const ctx = new Context()
+    const sandbox = {} as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
+    const create = vi.fn().mockResolvedValue(handle(0))
+    const backend = new E2BPtyBackend(ctx, config(), create)
+    const aborted = AbortSignal.abort(new Error('stop'))
+    await expect(backend.spawn({ sessionId: PtySessionId('one'), owner: owner(ctx), type: 'shell', signal: aborted })).rejects.toThrow('stop')
+    expect(create).not.toHaveBeenCalled()
+
+    const malformedKill = vi.fn().mockResolvedValue(true)
+    const malformed = handle(0, malformedKill)
+    const invalid = new E2BPtyBackend(ctx, config(), async () => malformed)
+    await expect(invalid.spawn({ sessionId: PtySessionId('two'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
+    expect(malformedKill).toHaveBeenCalledOnce()
+
+    const killFailureKill = vi.fn().mockRejectedValue(new Error('already gone'))
+    const killFailure = handle(0, killFailureKill)
+    const raced = new E2BPtyBackend(ctx, config(), async () => killFailure)
+    await expect(raced.spawn({ sessionId: PtySessionId('three'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
+  })
+
+  it('cleans failed startup and aggregates a cleanup failure', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const sandbox = {
+      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }) },
+      pty: { kill: vi.fn().mockRejectedValue(new Error('cleanup failed')) },
+    } as unknown as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
+    const failedHandle = handle()
+    const backend = new E2BPtyBackend(ctx, config(), async () => failedHandle)
+    const pending = backend.spawn({ sessionId: PtySessionId('failed'), owner: owner(ctx), type: 'shell' })
+    const rejected = expect(pending).rejects.toMatchObject({
+      name: 'PtyBackendCleanupError',
+      cleanupError: expect.objectContaining({ message: 'cleanup failed' }),
+    } satisfies Partial<PtyBackendCleanupError>)
+    await vi.advanceTimersByTimeAsync(6)
+    await vi.advanceTimersByTimeAsync(2)
+    await rejected
+    vi.useRealTimers()
+  })
+
+  it('preserves startup failure when cleanup succeeds', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const completion = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
+    const created = {
+      pid: 123,
+      wait: () => completion.promise,
+      disconnect: vi.fn().mockResolvedValue(undefined),
+    } as unknown as CommandHandle
+    const sandbox = {
+      commands: {
+        run: vi.fn(async (command: string) => {
+          if (command.startsWith('kill -TERM')) completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }),
+      },
+      pty: { kill: vi.fn().mockResolvedValue(true) },
+    } as unknown as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
+    const backend = new E2BPtyBackend(ctx, config(), async () => created)
+    const rejected = expect(backend.spawn({ sessionId: PtySessionId('failed-clean'), owner: owner(ctx), type: 'shell' }))
+      .rejects.toThrow('startup timeout')
+    await vi.advanceTimersByTimeAsync(6)
+    await rejected
+    vi.useRealTimers()
+  })
+
+  it('validates configuration and registers the selected backend type', async () => {
+    const valid = config()
+    expect(() => { validateConfig(valid) }).not.toThrow()
+    for (const invalid of [
+      { ...valid, backendType: '' },
+      { ...valid, rows: 0 },
+      { ...valid, rows: 1.5 },
+      { ...valid, maxReadBytes: 129 },
+    ]) {
+      expect(() => { validateConfig(invalid) }).toThrow()
+    }
+
+    const registerBackend = vi.fn()
+    apply({ pty: { registerBackend } } as unknown as Context, valid)
+    expect(registerBackend).toHaveBeenCalledWith(expect.objectContaining({ type: 'shell' }))
+
+    const ctx = new Context()
+    await ctx.plugin(PtyService)
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => ({}) } as never)
+    const fiber = await ctx.plugin({
+      inject: ['pty', 'e2b'],
+      apply: (pluginCtx: Context) => { apply(pluginCtx, valid) },
+    })
+    expect(ctx.pty.listBackends()).toEqual(['shell'])
+    await fiber.dispose()
+  })
+
+  it('registers the package-owned invariant companion', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BPtyInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/pty/pty-e2b/tests/session.spec.ts b/packages/pty/pty-e2b/tests/session.spec.ts
new file mode 100644
index 0000000000..6dced22ed2
--- /dev/null
+++ b/packages/pty/pty-e2b/tests/session.spec.ts
@@ -0,0 +1,398 @@
+import { Buffer } from 'node:buffer'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  CommandExitError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type { PtySendOperation, PtySessionStatus } from '@deepseek-ai/dsh-pty'
+import { E2BPtySession } from '@deepseek-ai/dsh-pty-e2b'
+import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+class FakePtyHandle {
+  pid = 123
+  readonly result = Promise.withResolvers<CommandResult>()
+  disconnects = 0
+  kills = 0
+  disconnectError: unknown
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    return this.result.promise
+  }
+
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
+  async kill(): Promise<boolean> {
+    this.kills += 1
+    return true
+  }
+
+  exit(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  failExit(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+
+  asHandle(): CommandHandle {
+    return this as unknown as CommandHandle
+  }
+}
+
+class FakeSandbox {
+  readonly sent: Array<{ pid: number; data: Buffer }> = []
+  readonly commands: string[] = []
+  readonly killed: number[] = []
+  pgid = '456\n'
+  sendError: unknown
+  commandError: unknown
+  killError: unknown
+  onTerm: (() => void) | undefined
+  onKill: (() => void) | undefined
+
+  readonly sandbox = {
+    pty: {
+      sendInput: async (pid: number, data: Uint8Array): Promise<void> => {
+        this.sent.push({ pid, data: Buffer.from(data) })
+        if (this.sendError !== undefined) throw this.sendError
+      },
+      kill: async (pid: number): Promise<boolean> => {
+        this.killed.push(pid)
+        if (this.killError !== undefined) throw this.killError
+        this.onKill?.()
+        return true
+      },
+    },
+    commands: {
+      run: async (command: string): Promise<CommandResult> => {
+        this.commands.push(command)
+        if (this.commandError !== undefined) {
+          const error = this.commandError
+          this.commandError = undefined
+          throw error
+        }
+        if (command.startsWith('ps ')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
+        if (command.startsWith('kill -TERM')) this.onTerm?.()
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
+  return {
+    backendType: 'shell', rows: 24, cols: 80,
+    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
+    pollIntervalMs: 10, idleSilenceMs: 40, timeoutMs: 100, disposeGraceMs: 20,
+    ...overrides,
+  }
+}
+
+async function initialize(session: E2BPtySession): Promise<void> {
+  const pending = session.initialize()
+  session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+  await vi.advanceTimersByTimeAsync(10)
+  await pending
+}
+
+afterEach(() => { vi.useRealTimers() })
+
+describe('E2BPtySession readiness, output, and signals', () => {
+  it('initializes, sends UTF-8 input, settles at a prompt, and reads bounded scrollback', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config({ maxReadBytes: 12 }))
+    expect(session.read({})).toMatchObject({ text: '', totalLines: 0 })
+    await initialize(session)
+    expect(session.motd).toBe('dsh> ')
+
+    const operation = session.startSend({ text: 'printf 你好', submit: true })
+    expect(fake.sent).toEqual([{ pid: 123, data: Buffer.from('printf 你好\r') }])
+    session.onData(Buffer.from('一\n二\n三\x1b]133;D;0\x07dsh> '))
+    const bounded = operation.readOutput()
+    expect(bounded.delta).toContain('三')
+    expect(bounded.truncated).toBe(true)
+    await vi.advanceTimersByTimeAsync(10)
+    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read', sessionStatus: { kind: 'running' } })
+    expect(operation.cancel()).toBe(false)
+    expect(session.read({ count: 2 }).text).toContain('dsh>')
+    expect(session.read({ offset: 99 })).toMatchObject({ text: '', lineBegin: 99, lineEnd: 99 })
+    expect(() => session.read({ offset: -1 })).toThrow('non-negative safe integer')
+    expect(() => session.read({ offset: 1.5 })).toThrow('non-negative safe integer')
+    expect(() => session.read({ count: 0 })).toThrow('positive safe integer')
+    expect(() => session.read({ count: 1.5 })).toThrow('positive safe integer')
+
+    await expect(session.signal('SIGTERM')).resolves.toEqual({ delivered: true, targetPgid: 456 })
+    expect(fake.commands).toContain('kill -TERM -- -456')
+    expect(session.status()).toEqual({ kind: 'running' })
+  })
+
+  it('distinguishes inferred idle, timeout, session exit, and no-output startup timeout', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    await initialize(session)
+
+    const inferred = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(40)
+    expect((await inferred.done).waitReason).toBe('inferred_idle')
+
+    const timeout = session.startSend({ text: '', submit: false })
+    for (let index = 0; index < 3; index += 1) {
+      await vi.advanceTimersByTimeAsync(30)
+      session.onData(Buffer.from('.'))
+    }
+    await vi.advanceTimersByTimeAsync(10)
+    expect((await timeout.done).waitReason).toBe('timeout')
+
+    const exiting = session.startSend({ text: '', submit: false })
+    handle.failExit(143)
+    expect(await exiting.done).toMatchObject({
+      waitReason: 'session_exit',
+      sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' },
+    })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
+
+    const startupHandle = new FakePtyHandle()
+    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), config())
+    const timedOut = expect(startup.initialize()).rejects.toThrow('startup timeout')
+    await vi.advanceTimersByTimeAsync(100)
+    await timedOut
+  })
+
+  it('handles split prompt text, stale operations, and explicit cancellation', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const initializing = session.initialize()
+    session.onData(Buffer.from('\x1b]133;D;0\x07'))
+    await vi.advanceTimersByTimeAsync(20)
+    session.onData(Buffer.from('dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await initializing
+
+    const operation = session.startSend({ text: 'sleep', submit: true })
+    const internal = session as unknown as {
+      pollReadiness(operation: PtySendOperation): void
+      interrupt(operation: PtySendOperation): void
+      settleActive(reason: 'timeout'): void
+      failActive(error: unknown): void
+      appendOutput(text: string): void
+      statusValue: PtySessionStatus
+    }
+    internal.pollReadiness({} as PtySendOperation)
+    internal.interrupt({} as PtySendOperation)
+    internal.appendOutput('')
+    fake.pgid = '789\n'
+    expect(operation.cancel()).toBe(true)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(fake.commands).toContain('kill -INT -- -789')
+    session.onData(Buffer.from('\x1b]133;D;130\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+
+    internal.settleActive('timeout')
+    internal.failActive(new Error('ignored'))
+    const operationInternal = operation as unknown as {
+      append(text: string): void
+      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+      fail(error: unknown): void
+    }
+    operationInternal.append('ignored')
+    operationInternal.settle('timeout', { kind: 'running' }, false)
+    operationInternal.fail(new Error('ignored'))
+  })
+
+  it('observes AbortSignal and contains send or foreground lookup failures', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    await initialize(session)
+
+    const controller = new AbortController()
+    const aborting = session.startSend({ text: '', submit: false, signal: controller.signal })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('active send')
+    fake.pgid = 'not-a-pgid\n'
+    controller.abort()
+    await expect(aborting.done).rejects.toThrow('cannot resolve foreground process group')
+
+    const already = new AbortController()
+    already.abort()
+    expect(() => session.startSend({ text: '', submit: false, signal: already.signal })).toThrow('aborted before write')
+
+    fake.sendError = new Error('send failed')
+    const failed = session.startSend({ text: 'x', submit: false })
+    await expect(failed.done).rejects.toThrow('send failed')
+
+    fake.pgid = '123\n'
+    await expect(session.signal('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
+    fake.pgid = '0\n'
+    await expect(session.signal('SIGINT')).rejects.toThrow('cannot resolve')
+
+    const deferred = Promise.withResolvers<undefined>()
+    fake.sendError = undefined
+    const sendInput = vi.spyOn(fake.sandbox.pty, 'sendInput').mockReturnValueOnce(deferred.promise)
+    const late = session.startSend({ text: 'late', submit: false })
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await late.done
+    deferred.reject(new Error('late failure'))
+    await vi.advanceTimersByTimeAsync(0)
+    expect(sendInput).toHaveBeenCalled()
+  })
+
+  it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
+    const fake = new FakeSandbox()
+    const abortHandle = new FakePtyHandle()
+    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), config())
+    const controller = new AbortController()
+    const reason = new Error('startup cancelled')
+    const initializing = abortSession.initialize(controller.signal)
+    const rejected = expect(initializing).rejects.toBe(reason)
+    controller.abort(reason)
+    await rejected
+
+    const invalidHandle = new FakePtyHandle()
+    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), config())
+    const pending = invalid.startSend({ text: '', submit: false })
+    invalid.onData(Uint8Array.from([0xff]))
+    await expect(pending.done).rejects.toThrow('invalid UTF-8')
+    expect(invalid.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+
+    const crashHandle = new FakePtyHandle()
+    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), config())
+    const active = crashed.startSend({ text: '', submit: false })
+    crashHandle.crash('transport gone')
+    await expect(active.done).rejects.toEqual(new Error('transport gone'))
+
+    const startupExitHandle = new FakePtyHandle()
+    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), config())
+    const exitedDuringStartup = expect(startupExit.initialize()).rejects.toThrow('exited during startup')
+    startupExitHandle.exit(7)
+    await exitedDuringStartup
+  })
+
+  it('covers empty bounded reads and polling an exited active session', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const tinyHandle = new FakePtyHandle()
+    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), config({ maxReadBytes: 1 }))
+    tiny.onData(Buffer.from('你'))
+    expect(tiny.read({ count: 1 })).toMatchObject({ text: '', lineEnd: 0 })
+
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const operation = session.startSend({ text: '', submit: false })
+    const internal = session as unknown as {
+      pollReadiness(operation: PtySendOperation): void
+      clearActive(): void
+      statusValue: PtySessionStatus
+    }
+    internal.statusValue = { kind: 'exited', exitCode: 7, signal: null }
+    internal.pollReadiness(operation)
+    expect((await operation.done).waitReason).toBe('session_exit')
+    internal.clearActive()
+  })
+})
+
+describe('E2BPtySession teardown', () => {
+  it('terminates the process group once, awaits exit, and disconnects', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    fake.onTerm = () => { handle.failExit(143) }
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const first = session.close('done')
+    expect(session.close('again')).toBe(first)
+    await first
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGTERM' })
+    expect(handle.disconnects).toBe(1)
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
+  })
+
+  it('contains an already-gone TERM, escalates to KILL, and reports a survivor', async () => {
+    vi.useFakeTimers()
+    const gone = new FakeSandbox()
+    const goneHandle = new FakePtyHandle()
+    gone.commandError = commandError(1)
+    gone.onKill = () => { goneHandle.failExit(137) }
+    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), config())
+    const closingGone = goneSession.close('gone')
+    await vi.advanceTimersByTimeAsync(20)
+    await closingGone
+    expect(gone.killed).toEqual([123])
+    expect(goneSession.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGKILL' })
+
+    const survivor = new FakeSandbox()
+    const survivorHandle = new FakePtyHandle()
+    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), config())
+    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving pid: 123')
+    await vi.advanceTimersByTimeAsync(40)
+    await failed
+    survivorHandle.exit()
+    await expect(survivorSession.close('retry')).resolves.toBeUndefined()
+  })
+
+  it('propagates cleanup transport failures and lets close retry', async () => {
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    fake.commandError = new Error('TERM transport failed')
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    await expect(session.close('failure')).rejects.toThrow('TERM transport failed')
+    handle.exit()
+    await expect(session.close('retry')).resolves.toBeUndefined()
+
+    const invalidTailHandle = new FakePtyHandle()
+    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), config())
+    invalidTail.onData(Uint8Array.from([0xe2]))
+    invalidTailHandle.exit()
+    await expect(invalidTail.close('invalid tail')).rejects.toThrow('invalid UTF-8')
+
+    const normalHandle = new FakePtyHandle()
+    normalHandle.disconnectError = new Error('disconnect raced')
+    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), config())
+    normalHandle.exit(7)
+    await Promise.resolve()
+    expect(normal.status()).toEqual({ kind: 'exited', exitCode: 7, signal: null })
+    await expect(normal.close('already exited')).resolves.toBeUndefined()
+  })
+
+  it('kills a remotely live PTY after its host transport fails', async () => {
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const active = session.startSend({ text: '', submit: false })
+    session.onData(Uint8Array.from([0xff]))
+    await expect(active.done).rejects.toThrow('invalid UTF-8')
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+
+    fake.onTerm = () => { handle.failExit(143) }
+    await expect(session.close('transport failed')).rejects.toThrow('invalid UTF-8')
+    expect(fake.commands).toContain('kill -TERM -- -123')
+    expect(handle.disconnects).toBe(1)
+  })
+})
diff --git a/packages/pty/pty-e2b/tsconfig.json b/packages/pty/pty-e2b/tsconfig.json
new file mode 100644
index 0000000000..0a7647aa80
--- /dev/null
+++ b/packages/pty/pty-e2b/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../e2b/e2b" },
+    { "path": "../pty" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
deleted file mode 100644
index 1f28315fb1..0000000000
--- a/packages/pty/pty-local/src/sanitize.ts
+++ /dev/null
@@ -1,188 +0,0 @@
-/** Streaming terminal-control sanitizer for the line-oriented first release. */
-
-import { Buffer } from 'node:buffer'
-
-/** OSC marker emitted by the controlled bash before each prompt. */
-export const PROMPT_MARKER_PREFIX = '133;D;'
-
-/** Exact printable prompt emitted after the private marker. */
-export const CONTROLLED_PROMPT = 'dsh> '
-
-/** One sanitized chunk plus whether it contained the owned prompt marker. */
-export interface SanitizedChunk {
-  text: string
-  prompt: boolean
-  /** Printable text after the latest owned marker in this chunk. */
-  promptTail?: string
-}
-
-/**
- * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
- * Full terminal emulation is deliberately deferred; ordinary line output and
- * the private prompt marker are the supported contract.
- */
-export class TerminalSanitizer {
-  private pending = ''
-  private discardMode: 'osc' | 'csi' | undefined
-  private discardOscEscape = false
-  private trailingCarriageReturn = false
-  private trackingPromptTail = false
-
-  constructor(private readonly maxPendingBytes: number) {}
-
-  /**
-   * Consume one decoded `node-pty` data chunk.
-   * @param chunk - decoded terminal data.
-   * @returns Printable text and whether the private prompt marker completed.
-   */
-  push(chunk: string): SanitizedChunk {
-    this.pending += this.discardPrefix(chunk)
-    let text = ''
-    let prompt = false
-    let includePromptTail = this.trackingPromptTail
-    let promptTail = ''
-    let index = 0
-    const appendText = (value: string): void => {
-      text += value
-      if (this.trackingPromptTail) promptTail += value
-    }
-    while (index < this.pending.length) {
-      const escape = this.pending.indexOf('\x1b', index)
-      if (escape < 0) {
-        appendText(this.pending.slice(index))
-        index = this.pending.length
-        break
-      }
-      appendText(this.pending.slice(index, escape))
-      if (escape + 1 >= this.pending.length) {
-        index = escape
-        break
-      }
-      const kind = this.pending[escape + 1]
-      if (kind === ']') {
-        const bel = this.pending.indexOf('\x07', escape + 2)
-        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
-        let end = -1
-        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
-        else if (bel >= 0) end = bel + 1
-        else if (stringTerminator >= 0) end = stringTerminator + 2
-        if (end < 0) {
-          index = escape
-          break
-        }
-        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
-        const content = this.pending.slice(escape + 2, end - terminatorBytes)
-        if (content.startsWith(PROMPT_MARKER_PREFIX)) {
-          prompt = true
-          this.trackingPromptTail = true
-          includePromptTail = true
-          promptTail = ''
-        }
-        index = end
-        continue
-      }
-      if (kind === '[') {
-        let end = escape + 2
-        while (end < this.pending.length) {
-          const code = this.pending.charCodeAt(end)
-          if (code >= 0x40 && code <= 0x7e) break
-          end += 1
-        }
-        if (end >= this.pending.length) {
-          index = escape
-          break
-        }
-        index = end + 1
-        continue
-      }
-      // Two-byte escape family (save/restore cursor and similar).
-      index = escape + 2
-    }
-    this.pending = this.pending.slice(index)
-    this.enforcePendingBound()
-    return {
-      text: this.normalizeText(text),
-      prompt,
-      ...includePromptTail ? { promptTail } : {},
-    }
-  }
-
-  /**
-   * Flush a trailing printable fragment when the PTY exits.
-   * @returns Remaining printable text; incomplete escapes are discarded.
-   */
-  flush(): string {
-    const text = this.pending.startsWith('\x1b') ? '' : this.pending
-    this.pending = ''
-    this.discardMode = undefined
-    this.discardOscEscape = false
-    this.trackingPromptTail = false
-    const normalized = this.normalizeText(text)
-    if (!this.trailingCarriageReturn) return normalized
-    this.trailingCarriageReturn = false
-    return `${normalized}\n`
-  }
-
-  private normalizeText(text: string): string {
-    let complete = this.trailingCarriageReturn ? `\r${text}` : text
-    this.trailingCarriageReturn = false
-    if (complete.endsWith('\r')) {
-      complete = complete.slice(0, -1)
-      this.trailingCarriageReturn = true
-    }
-    return normalizeTerminalText(complete)
-  }
-
-  private enforcePendingBound(): void {
-    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
-    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
-    this.pending = ''
-  }
-
-  private discardPrefix(chunk: string): string {
-    if (this.discardMode === undefined) return chunk
-    if (this.discardMode === 'csi') {
-      for (let index = 0; index < chunk.length; index += 1) {
-        const code = chunk.charCodeAt(index)
-        if (code >= 0x40 && code <= 0x7e) {
-          this.discardMode = undefined
-          return chunk.slice(index + 1)
-        }
-      }
-      return ''
-    }
-
-    let index = 0
-    if (this.discardOscEscape) {
-      this.discardOscEscape = false
-      if (chunk.startsWith('\\')) {
-        this.discardMode = undefined
-        return chunk.slice(1)
-      }
-    }
-    while (index < chunk.length) {
-      if (chunk[index] === '\x07') {
-        this.discardMode = undefined
-        return chunk.slice(index + 1)
-      }
-      if (chunk[index] === '\x1b') {
-        if (chunk[index + 1] === '\\') {
-          this.discardMode = undefined
-          return chunk.slice(index + 2)
-        }
-        if (index + 1 === chunk.length) this.discardOscEscape = true
-      }
-      index += 1
-    }
-    return ''
-  }
-}
-
-/**
- * Normalize CRLF and standalone carriage returns for line-oriented rendering.
- * @param text - sanitized terminal text.
- * @returns Line-normalized text with BEL removed.
- */
-export function normalizeTerminalText(text: string): string {
-  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
-}
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 25ed8fe586..ebf6b559d1 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -1,12 +1,7 @@
-/** Persistent PTY session over the subprocess seam's terminal primitive. */
+/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
 
-import { Buffer } from 'node:buffer'
-import type {
-  SubprocessOutcome,
-  SubprocessTerminalForeground,
-  SubprocessTerminalHandle,
-} from '@deepseek-ai/dsh-subprocess'
-import { PtyError } from '@deepseek-ai/dsh-pty'
+import type { IDisposable, IPty } from 'node-pty'
+import { PtyTerminalSanitizer, PtyTextBuffer, ptySignalName, ptyUtf8Tail } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -21,89 +16,30 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
 
-function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
-  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
-  const chars = Array.from(text)
-  let bytes = 0
-  let start = chars.length
-  while (start > 0) {
-    const next = Buffer.byteLength(chars[start - 1] as string)
-    if (bytes + next > maxBytes) break
-    bytes += next
-    start -= 1
-  }
-  return { text: chars.slice(start).join(''), truncated: true }
-}
-
-class BoundedTextBuffer {
-  private value = ''
-  private dropped = false
-
-  constructor(
-    private readonly maxBytes: number,
-    private readonly maxLines?: number,
-  ) {}
-
-  append(text: string): void {
-    if (text.length === 0) return
-    this.value += text
-    if (this.maxLines !== undefined) {
-      const lines = this.value.split('\n')
-      if (lines.length > this.maxLines) {
-        this.value = lines.slice(lines.length - this.maxLines).join('\n')
-        this.dropped = true
-      }
-    }
-    const tail = utf8Tail(this.value, this.maxBytes)
-    this.value = tail.text
-    this.dropped ||= tail.truncated
-  }
-
-  consume(): PtySendRead {
-    const delta = this.value
-    const truncated = this.dropped
-    this.value = ''
-    this.dropped = false
-    return { delta, truncated }
-  }
-
-  snapshot(): { text: string; truncated: boolean } {
-    return { text: this.value, truncated: this.dropped }
-  }
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
 }
 
 class LocalSendOperation implements PtySendOperation {
-  private readonly output: BoundedTextBuffer
+  private readonly output: PtyTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
-  private cancellationRequested = false
-  private initialForegroundLeftWait: boolean
-  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
     private readonly onCancel: () => void,
   ) {
-    this.output = new BoundedTextBuffer(maxBytes)
+    this.output = new PtyTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
-    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
     return this.promise.promise
   }
 
-  get settled(): boolean {
-    return this.finished
-  }
-
-  get cancelRequested(): boolean {
-    return this.cancellationRequested
-  }
-
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -130,75 +66,50 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
-  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
-    this.initialForegroundPgid = foreground?.processGroupId
-    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
-  }
-
-  acceptsStdinWait(pgid: number, waiting: boolean): boolean {
-    // The same group may still expose the wait that existed before terminal.write.
-    // Observe every poll so a departure before the exact-settlement threshold
-    // still makes a later return to that wait post-write evidence.
-    if (pgid !== this.initialForegroundPgid) return waiting
-    if (!waiting) this.initialForegroundLeftWait = true
-    return waiting && this.initialForegroundLeftWait
-  }
-
   cancel(): boolean {
     if (this.finished) return false
-    this.cancellationRequested = true
     this.onCancel()
     return true
   }
 }
 
-/** Backend session wrapping one provider-owned terminal process. */
+/** Backend session wrapping one `node-pty` process and its captured process tree. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
-  private readonly decoder = new TextDecoder()
-  private readonly sanitizer: TerminalSanitizer
-  private readonly scrollback: BoundedTextBuffer
-  private readonly outputEnded = Promise.withResolvers<void>()
-  private readonly completion: Promise<void>
+  private readonly sanitizer: PtyTerminalSanitizer
+  private readonly scrollback: PtyTextBuffer
+  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
+  private readonly dataDisposable: IDisposable
+  private readonly exitDisposable: IDisposable
   private statusValue: PtySessionStatus = { kind: 'running' }
-  // TODO(pty-send-state-consolidation): Fold the per-send fields below
-  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
-  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
-  // cancellation/readiness interplay now has enough pinned tests to carry
-  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
-  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
-  private interrupting: LocalSendOperation | undefined
-  private activeWrite: Promise<boolean> | undefined
-  private pollingReady: LocalSendOperation | undefined
-  private polling = false
   private promptSeen = false
   private promptTextSeen = false
-  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
-  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: SubprocessTerminalHandle,
+    private readonly terminal: IPty,
+    private readonly inspector: ProcessInspector,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
-    this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
-    this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    terminal.output.on('data', this.onTerminalData)
-    terminal.output.once('end', this.onTerminalEnd)
-    terminal.output.once('error', this.onTerminalError)
-    this.completion = terminal.done.then(
-      outcome => this.onExit(outcome),
-      (error: unknown) => { this.onTransportFailure(error) },
-    )
+    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
+    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
+    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
+      const tail = this.sanitizer.flush()
+      this.appendOutput(tail)
+      this.statusValue = { kind: 'exited', exitCode, signal: ptySignalName(signal) }
+      this.settleActive('session_exit')
+      this.exitPromise.resolve()
+    })
   }
 
   /**
@@ -225,14 +136,7 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) {
-      const draining = this.activeWrite !== undefined
-        ? ' or draining provider write'
-        : this.interrupting !== undefined
-          ? ' or draining foreground interrupt'
-          : ''
-      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
-    }
+    if (this.active !== undefined) throw new Error('PTY session already has an active send')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -241,79 +145,29 @@ export class LocalPtySession implements PtyBackendSession {
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.resetReadinessEvidence()
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-    this.activeDeadlineTimer = setTimeout(() => {
-      if (this.active === operation) {
-        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
-      }
-    }, this.config.timeoutMs)
-    void this.beginSend(operation, request)
+
+    try {
+      if (request.text.length > 0) this.terminal.write(request.text)
+      if (request.submit) this.terminal.write('\r')
+    } catch (error: unknown) {
+      this.clearActive()
+      operation.fail(error)
+      return operation
+    }
+
+    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
     return operation
   }
 
-  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
-    let foreground: SubprocessTerminalForeground | undefined
-    try {
-      foreground = await this.terminal.inspectForeground()
-    } catch (error: unknown) {
-      // A pre-write inspection failure while cancellation owns the slot must not
-      // release it: interruptOnce's in-flight foreground signal could land on a
-      // successor's foreground group. The interrupt path's post-signal tail
-      // resumes polling, whose guarded catch propagates a persistent failure.
-      // A retained settled operation implies that same in-flight interrupt, so
-      // this guard admits only an unsettled active send.
-      if (this.active === operation && !this.closing && this.interrupting !== operation) {
-        this.failActive(error)
-      }
-      return
-    }
-    try {
-      if (this.active !== operation || this.closing || this.interrupting === operation) return
-      operation.setInitialForeground(foreground)
-      const input = `${request.text}${request.submit ? '\r' : ''}`
-      if (input.length > 0 && !operation.cancelRequested) {
-        this.resetReadinessEvidence()
-        const write = this.terminal.write(input)
-        this.activeWrite = write.then(() => true, () => false)
-        try {
-          await write
-        } finally {
-          this.activeWrite = undefined
-        }
-      }
-      // Cancellation owns post-write signalling and reservation release.
-      if (operation.cancelRequested) return
-      if (this.active === operation && operation.settled) {
-        this.clearActive()
-        return
-      }
-      // Closing can race the awaited provider write even though static analysis sees only local assignments.
-      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
-      if (this.active === operation && !this.closing) {
-        this.pollingReady = operation
-        this.schedulePoll(operation)
-      }
-    } catch (error: unknown) {
-      if (this.active === operation && !this.closing) {
-        if (operation.settled) this.clearActive()
-        else this.failActive(error)
-      }
-    }
-  }
-
-  private resetReadinessEvidence(): void {
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
-    this.promptTail = ''
-  }
-
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -328,7 +182,7 @@ export class LocalPtySession implements PtyBackendSession {
     const end = totalLines - offset
     const start = Math.max(0, end - count)
     const requested = lines.slice(start, end).join('\n')
-    const bounded = utf8Tail(requested, this.config.maxReadBytes)
+    const bounded = ptyUtf8Tail(requested, this.config.maxReadBytes)
     const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
     return {
       text: bounded.text,
@@ -339,10 +193,16 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  async signal(signal: PtySignal): Promise<PtySignalResult> {
-    if (this.closing) throw new Error('PTY session is closing')
-    const targetPgid = await this.terminal.signalForeground(signal)
-    return { delivered: true, targetPgid }
+  signal(signal: PtySignal): Promise<PtySignalResult> {
+    return Promise.resolve().then(() => {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
+      if (signal === 'SIGKILL' && pgid === this.pid) {
+        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
+      }
+      this.inspector.signalGroup(pgid, signal)
+      return { delivered: true, targetPgid: pgid }
+    })
   }
 
   status(): PtySessionStatus {
@@ -361,56 +221,21 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
-  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
-    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
-    this.onData(this.decoder.decode(bytes, { stream: true }))
-  }
-
-  private readonly onTerminalEnd = (): void => {
-    this.onData(this.decoder.decode())
-    this.appendOutput(this.sanitizer.flush())
-    this.outputEnded.resolve()
-  }
-
-  private readonly onTerminalError = (error: Error): void => {
-    this.onTransportFailure(error)
-    this.outputEnded.resolve()
-  }
-
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
-      // before attributing a signal-delayed prompt to a later send.
+      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
+      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTail = ''
+      this.promptTextSeen = sanitized.promptText === true
       this.lastOutputAt = Date.now()
+    } else if (this.promptSeen && sanitized.promptText === true) {
+      this.promptTextSeen = true
     }
-    if (this.promptSeen && sanitized.promptTail !== undefined) {
-      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
-      this.promptTail += sanitized.promptTail.slice(0, remaining)
-      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
-      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
-    }
-  }
-
-  private async onExit(outcome: SubprocessOutcome): Promise<void> {
-    await this.outputEnded.promise
-    if (this.transportFailure !== undefined) return
-    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
-    this.settleActive('session_exit')
-  }
-
-  private onTransportFailure(error: unknown): void {
-    const failure = error instanceof Error ? error : new Error(String(error))
-    this.transportFailure ??= failure
-    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
-    this.failActive(failure)
-    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -420,94 +245,60 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
-    if (this.active !== operation || this.interrupting === operation || this.polling) return
-    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
-    this.activeTimer = setTimeout(() => {
-      this.activeTimer = undefined
-      void this.pollReadiness(operation)
-    }, delayMs)
-  }
-
-  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
-    if (this.active !== operation || this.polling) return
-    this.polling = true
-    try {
-      if (this.statusValue.kind === 'exited') {
-        this.settleActive('session_exit')
-        return
-      }
-      const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation || this.closing || this.interrupting === operation) return
-      const idleFor = Date.now() - this.lastOutputAt
-      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
-        this.shellPgid = foreground.processGroupId
-      }
-      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
-        && foreground?.processGroupId === this.shellPgid) {
-        this.settleActive('stdin_read')
-        return
-      }
-      const elapsed = Date.now() - operation.startedAt
-      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-      const acceptsStdinWait = startupHasOutput && foreground !== undefined
-        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
-      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
-        this.settleActive('stdin_read')
-        return
-      }
-      // A prompt candidate can race bash's foreground handoff, but an interactive
-      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-      // on waiting for shell ownership instead of letting a child marker suppress
-      // readiness until the absolute timeout.
-      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-        this.settleActive('inferred_idle')
-      }
-    } catch (error: unknown) {
-      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
-    } finally {
-      this.polling = false
-      const active = this.active
-      // Awaited provider inspection can clear or replace the active send despite static analysis.
-      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
-      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
+  private pollReadiness(operation: LocalSendOperation): void {
+    if (this.active !== operation) return
+    if (this.statusValue.kind === 'exited') {
+      this.settleActive('session_exit')
+      return
     }
+    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
+        this.settleActive('stdin_read')
+        return
+      }
+    }
+    const elapsed = Date.now() - operation.startedAt
+    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+    if (startupHasOutput && elapsed >= this.config.exactProbeAfterMs) {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid !== undefined && this.inspector.isStdinWaiting(pgid)) {
+        this.settleActive('stdin_read')
+        return
+      }
+    }
+    // A prompt candidate can race bash's foreground handoff, but an interactive
+    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+    // on waiting for shell ownership instead of letting a child marker suppress
+    // readiness until the absolute timeout. When a prompt marker was seen, the
+    // configured grace holds the fallback past the silence bound so polls in
+    // that window can observe the foreground handoff and settle as stdin_read.
+    const idleFor = Date.now() - this.lastOutputAt
+    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+      this.settleActive('inferred_idle')
+      return
+    }
+    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
   }
 
-  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
+  private settleActive(waitReason: PtyWaitReason): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    if (retainOwnership) {
-      this.stopPolling()
-      this.activeAbort?.()
-      this.activeAbort = undefined
-    } else {
-      this.clearActive()
-    }
+    this.clearActive()
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
   private stopPolling(): void {
-    this.stopReadinessPolling()
-    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
-    this.activeDeadlineTimer = undefined
-  }
-
-  private stopReadinessPolling(): void {
-    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
     this.activeTimer = undefined
-    this.pollingReady = undefined
   }
 
   private clearActive(): void {
-    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
-    if (this.interrupting === operation) this.interrupting = undefined
-    this.pollingReady = undefined
     this.active = undefined
   }
 
@@ -520,46 +311,104 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.interrupting = operation
-    this.stopReadinessPolling()
-    void this.interruptOnce(operation)
+    try {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
+      this.inspector.signalGroup(pgid, 'SIGINT')
+    } catch (error: unknown) {
+      this.failActive(error)
+    }
   }
 
-  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
-    try {
-      const activeWrite = this.activeWrite
-      if (activeWrite !== undefined && !await activeWrite) return
-      await this.terminal.signalForeground('SIGINT')
-    } catch (error: unknown) {
-      if (this.active === operation && !this.closing) this.onTransportFailure(error)
-      return
-    } finally {
-      if (this.interrupting === operation) this.interrupting = undefined
+  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
+    return members.filter(member => this.inspector.isAlive(member))
+  }
+
+  private descendants(): ProcessIdentity[] {
+    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+  }
+
+  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
+    const deadline = Date.now() + this.config.disposeGraceMs
+    let survivors = this.survivors(members)
+    while (survivors.length > 0 && Date.now() < deadline) {
+      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
+      survivors = this.survivors(members)
     }
-    if (this.active === operation && operation.settled) {
-      this.clearActive()
-    } else if (this.active === operation && !this.closing) {
-      this.pollingReady = operation
-      this.schedulePoll(operation, 0)
+    return survivors
+  }
+
+  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
+    for (const member of members) {
+      try {
+        this.inspector.signalProcess(member, signal)
+      } catch (_alreadyExitedDuringSignal) {
+        // Identity is rechecked by the inspector; a same-tick exit is success.
+      }
+    }
+  }
+
+  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
+    const members: ProcessIdentity[] = []
+    const seen = new Set<string>()
+    for (const group of groups) {
+      for (const member of group) {
+        const key = JSON.stringify([member.pid, member.started])
+        if (seen.has(key)) continue
+        seen.add(key)
+        members.push(member)
+      }
+    }
+    return members
+  }
+
+  private async stopDescendants(): Promise<ProcessIdentity[]> {
+    const captured = this.descendants()
+    this.signalMembers(captured, 'SIGTERM')
+    const capturedSurvivors = await this.waitForExit(captured)
+    // A TERM-handling descendant may have forked while winding down. Rescan
+    // while the shell can still reap every member, then kill both the fresh
+    // tree and captured survivors that were reparented out of that tree.
+    const members = this.unionMembers(capturedSurvivors, this.descendants())
+    this.signalMembers(members, 'SIGKILL')
+    const survivors = await this.waitForExit(members)
+    return this.survivors(this.unionMembers(survivors, this.descendants()))
+  }
+
+  private async stopShell(): Promise<void> {
+    try {
+      this.terminal.kill('SIGTERM')
+    } catch (_topLevelAlreadyExitedDuringTerm) {
+      // The exit notification remains authoritative.
+    }
+    if (this.statusValue.kind === 'running') {
+      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (this.statusValue.kind === 'running') {
+      try {
+        this.terminal.kill('SIGKILL')
+      } catch (_topLevelAlreadyExitedDuringKill) {
+        // The exit notification remains authoritative.
+      }
+      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (this.statusValue.kind === 'running') {
+      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
     }
   }
 
   private async closeOnce(reason: string): Promise<void> {
+    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    try {
-      await this.terminal.terminate()
-    } catch (error: unknown) {
-      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
+    const survivors = await this.stopDescendants()
+    if (survivors.length > 0) {
+      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
-    // Quiescence is the active send's terminal outcome.
+    await this.stopShell()
     this.settleActive('session_exit')
-    await this.completion
-    this.terminal.output.off('data', this.onTerminalData)
-    this.terminal.output.off('end', this.onTerminalEnd)
-    this.terminal.output.off('error', this.onTerminalError)
-    if (this.transportFailure !== undefined) throw this.transportFailure
+    this.exitDisposable.dispose()
   }
 }
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index f6649b3c6f..06ec076358 100644
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -1,17 +1,17 @@
 import { describe, expect, it } from 'vitest'
-import { normalizeTerminalText, TerminalSanitizer } from '@deepseek-ai/dsh-pty-local/src/sanitize.ts'
+import { normalizePtyTerminalText, PtyTerminalSanitizer } from '@deepseek-ai/dsh-pty'
 
-describe('TerminalSanitizer', () => {
+describe('PtyTerminalSanitizer', () => {
   it('removes split CSI and owned OSC prompt markers', () => {
-    const sanitizer = new TerminalSanitizer(64)
+    const sanitizer = new PtyTerminalSanitizer(64)
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
-    const sanitizer = new TerminalSanitizer(64)
+    const sanitizer = new PtyTerminalSanitizer(64)
     expect(sanitizer.push('a\x1b]0;title\x1b\\b\x1b7c\x07')).toEqual({ text: 'abc', prompt: false })
     expect(sanitizer.push('tail\x1b')).toEqual({ text: 'tail', prompt: false })
     expect(sanitizer.flush()).toBe('')
@@ -22,11 +22,11 @@ describe('TerminalSanitizer', () => {
   })
 
   it('normalizes CRLF and standalone carriage returns', () => {
-    expect(normalizeTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
+    expect(normalizePtyTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
   })
 
   it('carries a trailing carriage return across data chunks and flushes standalone CR', () => {
-    const sanitizer = new TerminalSanitizer(64)
+    const sanitizer = new PtyTerminalSanitizer(64)
     expect(sanitizer.push('a\r')).toEqual({ text: 'a', prompt: false })
     expect(sanitizer.push('\nb')).toEqual({ text: '\nb', prompt: false })
     expect(sanitizer.push('\r')).toEqual({ text: '', prompt: false })
@@ -34,41 +34,41 @@ describe('TerminalSanitizer', () => {
   })
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
-    const sanitizer = new TerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
+    const sanitizer = new PtyTerminalSanitizer(64)
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {
-    const oscBel = new TerminalSanitizer(8)
+    const oscBel = new PtyTerminalSanitizer(8)
     expect(oscBel.push(`\x1b]0;${'x'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(oscBel.push('more\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscSt = new TerminalSanitizer(8)
+    const oscSt = new PtyTerminalSanitizer(8)
     oscSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscSt.push('more\x1b')).toEqual({ text: '', prompt: false })
     expect(oscSt.push('\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscDirectSt = new TerminalSanitizer(8)
+    const oscDirectSt = new PtyTerminalSanitizer(8)
     oscDirectSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscDirectSt.push('more\x1b\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscFalseSt = new TerminalSanitizer(8)
+    const oscFalseSt = new PtyTerminalSanitizer(8)
     oscFalseSt.push(`\x1b]0;${'x'.repeat(16)}`)
     oscFalseSt.push('\x1b')
     expect(oscFalseSt.push('more')).toEqual({ text: '', prompt: false })
     expect(oscFalseSt.push('\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscNonTerminatingEscape = new TerminalSanitizer(8)
+    const oscNonTerminatingEscape = new PtyTerminalSanitizer(8)
     oscNonTerminatingEscape.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscNonTerminatingEscape.push('more\x1bxmore\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const csi = new TerminalSanitizer(8)
+    const csi = new PtyTerminalSanitizer(8)
     expect(csi.push(`\x1b[${'1'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(csi.push('123')).toEqual({ text: '', prompt: false })
     expect(csi.push('mtext')).toEqual({ text: 'text', prompt: false })
 
-    const flushed = new TerminalSanitizer(8)
+    const flushed = new PtyTerminalSanitizer(8)
     flushed.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(flushed.flush()).toBe('')
     expect(flushed.push('text')).toEqual({ text: 'text', prompt: false })
diff --git a/packages/pty/pty/src/index.ts b/packages/pty/pty/src/index.ts
index 8ff4168e1a..5cb375fbca 100644
--- a/packages/pty/pty/src/index.ts
+++ b/packages/pty/pty/src/index.ts
@@ -41,6 +41,15 @@ export type {
   PtyWaitReason,
 } from './types.ts'
 export { PtyBackendCleanupError } from './types.ts'
+export {
+  normalizePtyTerminalText,
+  PTY_PROMPT_MARKER_PREFIX,
+  PtyTerminalSanitizer,
+  PtyTextBuffer,
+  ptySignalName,
+  ptyUtf8Tail,
+} from './terminal.ts'
+export type { PtySanitizedChunk } from './terminal.ts'
 
 /** Opaque identity minted by {@link PtyService} for one live PTY session. */
 export type PtySessionId = PtySessionIdValue
diff --git a/packages/pty/pty/src/terminal.ts b/packages/pty/pty/src/terminal.ts
new file mode 100644
index 0000000000..ed005dda41
--- /dev/null
+++ b/packages/pty/pty/src/terminal.ts
@@ -0,0 +1,273 @@
+/** Backend-neutral line-oriented terminal buffering and control-sequence sanitization. */
+
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:os'
+import type { PtySendRead } from './types.ts'
+
+/** OSC marker emitted by a controlled bash before each prompt. */
+export const PTY_PROMPT_MARKER_PREFIX = '133;D;'
+
+/** One sanitized chunk plus whether it contained the controlled prompt marker. */
+export interface PtySanitizedChunk {
+  /** Printable, line-normalized terminal text. */
+  text: string
+  /** Whether the chunk completed the controlled prompt marker. */
+  prompt: boolean
+  /** Present when printable text followed the latest controlled prompt marker. */
+  promptText?: true
+}
+
+/**
+ * Return the largest code-point-aligned UTF-8 tail within a byte cap.
+ * @param text - Candidate terminal text.
+ * @param maxBytes - Maximum retained UTF-8 bytes.
+ * @returns The retained tail and whether its head was dropped.
+ */
+export function ptyUtf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
+  const chars = Array.from(text)
+  let bytes = 0
+  let start = chars.length
+  while (start > 0) {
+    const next = Buffer.byteLength(chars[start - 1] as string)
+    if (bytes + next > maxBytes) break
+    bytes += next
+    start -= 1
+  }
+  return { text: chars.slice(start).join(''), truncated: true }
+}
+
+/** UTF-8 and optionally line-bounded terminal text buffer. */
+export class PtyTextBuffer {
+  private value = ''
+  private dropped = false
+
+  /**
+   * @param maxBytes - Maximum retained UTF-8 bytes.
+   * @param maxLines - Optional maximum retained logical lines.
+   */
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxLines?: number,
+  ) {}
+
+  /**
+   * Append terminal text and drop the oldest excess.
+   * @param text - Decoded and sanitized terminal text.
+   */
+  append(text: string): void {
+    if (text.length === 0) return
+    this.value += text
+    if (this.maxLines !== undefined) {
+      const lines = this.value.split('\n')
+      if (lines.length > this.maxLines) {
+        this.value = lines.slice(lines.length - this.maxLines).join('\n')
+        this.dropped = true
+      }
+    }
+    const tail = ptyUtf8Tail(this.value, this.maxBytes)
+    this.value = tail.text
+    this.dropped ||= tail.truncated
+  }
+
+  /**
+   * Consume all currently retained operation text.
+   * @returns The delta and whether older text was dropped.
+   */
+  consume(): PtySendRead {
+    const delta = this.value
+    const truncated = this.dropped
+    this.value = ''
+    this.dropped = false
+    return { delta, truncated }
+  }
+
+  /**
+   * Return the retained text without consuming it.
+   * @returns The retained text and whether its head was dropped.
+   */
+  snapshot(): { text: string; truncated: boolean } {
+    return { text: this.value, truncated: this.dropped }
+  }
+}
+
+/**
+ * Streaming terminal-control sanitizer for line-oriented PTY backends.
+ * Full terminal emulation is deliberately outside the PTY seam.
+ */
+export class PtyTerminalSanitizer {
+  private pending = ''
+  private discardMode: 'osc' | 'csi' | undefined
+  private discardOscEscape = false
+  private trailingCarriageReturn = false
+  private awaitingPromptText = false
+
+  /** @param maxPendingBytes - Bound for an incomplete terminal-control sequence. */
+  constructor(private readonly maxPendingBytes: number) {}
+
+  /**
+   * Consume one decoded PTY data chunk.
+   * @param chunk - Decoded terminal data.
+   * @returns Printable text and prompt-marker facts.
+   */
+  push(chunk: string): PtySanitizedChunk {
+    this.pending += this.discardPrefix(chunk)
+    let text = ''
+    let prompt = false
+    let promptText = false
+    let index = 0
+    const appendText = (value: string): boolean => {
+      text += value
+      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
+        this.awaitingPromptText = false
+        return true
+      }
+      return false
+    }
+    while (index < this.pending.length) {
+      const escape = this.pending.indexOf('\x1b', index)
+      if (escape < 0) {
+        promptText = appendText(this.pending.slice(index)) || promptText
+        index = this.pending.length
+        break
+      }
+      promptText = appendText(this.pending.slice(index, escape)) || promptText
+      if (escape + 1 >= this.pending.length) {
+        index = escape
+        break
+      }
+      const kind = this.pending[escape + 1]
+      if (kind === ']') {
+        const bel = this.pending.indexOf('\x07', escape + 2)
+        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
+        let end = -1
+        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
+        else if (bel >= 0) end = bel + 1
+        else if (stringTerminator >= 0) end = stringTerminator + 2
+        if (end < 0) {
+          index = escape
+          break
+        }
+        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
+        const content = this.pending.slice(escape + 2, end - terminatorBytes)
+        if (content.startsWith(PTY_PROMPT_MARKER_PREFIX)) {
+          prompt = true
+          promptText = false
+          this.awaitingPromptText = true
+        }
+        index = end
+        continue
+      }
+      if (kind === '[') {
+        let end = escape + 2
+        while (end < this.pending.length) {
+          const code = this.pending.charCodeAt(end)
+          if (code >= 0x40 && code <= 0x7e) break
+          end += 1
+        }
+        if (end >= this.pending.length) {
+          index = escape
+          break
+        }
+        index = end + 1
+        continue
+      }
+      index = escape + 2
+    }
+    this.pending = this.pending.slice(index)
+    this.enforcePendingBound()
+    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
+  }
+
+  /**
+   * Flush printable trailing data and discard incomplete controls.
+   * @returns Remaining normalized printable text.
+   */
+  flush(): string {
+    const text = this.pending.startsWith('\x1b') ? '' : this.pending
+    this.pending = ''
+    this.discardMode = undefined
+    this.discardOscEscape = false
+    this.awaitingPromptText = false
+    const normalized = this.normalizeText(text)
+    if (!this.trailingCarriageReturn) return normalized
+    this.trailingCarriageReturn = false
+    return `${normalized}\n`
+  }
+
+  private normalizeText(text: string): string {
+    let complete = this.trailingCarriageReturn ? `\r${text}` : text
+    this.trailingCarriageReturn = false
+    if (complete.endsWith('\r')) {
+      complete = complete.slice(0, -1)
+      this.trailingCarriageReturn = true
+    }
+    return normalizePtyTerminalText(complete)
+  }
+
+  private enforcePendingBound(): void {
+    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
+    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
+    this.pending = ''
+  }
+
+  private discardPrefix(chunk: string): string {
+    if (this.discardMode === undefined) return chunk
+    if (this.discardMode === 'csi') {
+      for (let index = 0; index < chunk.length; index += 1) {
+        const code = chunk.charCodeAt(index)
+        if (code >= 0x40 && code <= 0x7e) {
+          this.discardMode = undefined
+          return chunk.slice(index + 1)
+        }
+      }
+      return ''
+    }
+
+    let index = 0
+    if (this.discardOscEscape) {
+      this.discardOscEscape = false
+      if (chunk.startsWith('\\')) {
+        this.discardMode = undefined
+        return chunk.slice(1)
+      }
+    }
+    while (index < chunk.length) {
+      if (chunk[index] === '\x07') {
+        this.discardMode = undefined
+        return chunk.slice(index + 1)
+      }
+      if (chunk[index] === '\x1b') {
+        if (chunk[index + 1] === '\\') {
+          this.discardMode = undefined
+          return chunk.slice(index + 2)
+        }
+        if (index + 1 === chunk.length) this.discardOscEscape = true
+      }
+      index += 1
+    }
+    return ''
+  }
+}
+
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - Sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export function normalizePtyTerminalText(text: string): string {
+  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
+}
+
+/**
+ * Convert a platform signal number into the seam's signal-name vocabulary.
+ * @param number - Platform signal number, zero, or an absent signal.
+ * @returns The matching Node signal name, or `null` when unknown or absent.
+ */
+export function ptySignalName(number: number | undefined): NodeJS.Signals | null {
+  if (number === undefined || number === 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 90aa22e322..5ab5dc2e4e 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,6 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/code-runtime/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
@@ -98,6 +99,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
+  'packages/lsp/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 03b1bcd2dd..1f70e79a4f 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -166,10 +166,12 @@
     { "path": "./packages/subprocess/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
+    { "path": "./packages/pty/pty-e2b" },
     { "path": "./packages/pty/pty-local" },
     { "path": "./packages/pty/tool-bash-persistent" },
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
+    { "path": "./packages/code-runtime/code-runtime-e2b" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -266,6 +268,7 @@
     { "path": "./packages/sdk/create-sdk" },
     { "path": "./packages/sdk/telemetry" },
     { "path": "./packages/lsp/lsp" },
+    { "path": "./packages/lsp/lsp-e2b" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
     { "path": "./apps/cli" }

From e64d40837c04bc6b39ea958ce8afc26cba97b2ed Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 14:52:37 +0800
Subject: [PATCH 101/262] refactor(e2b): group remote providers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |  4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      | 40 ++++++++++---
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   | 40 ++++++++++---
 ...active-semantic-code-runtime-poc.i18n.yaml |  6 --
 ...b-interactive-semantic-code-runtime-poc.md | 57 -------------------
 ...nteractive-semantic-code-runtime-poc.zh.md | 57 -------------------
 AGENTS.md                                     | 21 +++----
 packages/README.i18n.yaml                     |  4 +-
 packages/README.md                            |  2 +-
 packages/README.zh.md                         |  2 +-
 packages/code-runtime/README.i18n.yaml        |  4 +-
 packages/code-runtime/README.md               |  4 +-
 packages/code-runtime/README.zh.md            |  4 +-
 .../code-runtime-e2b/README.i18n.yaml         |  6 --
 packages/e2b/README.i18n.yaml                 |  4 +-
 packages/e2b/README.md                        | 12 ++--
 packages/e2b/README.zh.md                     | 12 ++--
 .../code-runtime-e2b}/README.i18n.yaml        |  6 +-
 .../code-runtime-e2b/README.md                |  2 +-
 .../code-runtime-e2b/README.zh.md             |  2 +-
 .../code-runtime-e2b/package.json             |  0
 .../code-runtime-e2b/src/index.ts             |  0
 .../code-runtime-e2b/src/invariant.ts         |  0
 .../code-runtime-e2b/src/runner-source.ts     |  0
 .../code-runtime-e2b/tests/runtime.spec.ts    |  0
 .../code-runtime-e2b/tsconfig.json            |  8 +--
 packages/{fs => e2b}/fs-e2b/README.i18n.yaml  |  6 +-
 packages/{fs => e2b}/fs-e2b/README.md         |  4 +-
 packages/{fs => e2b}/fs-e2b/README.zh.md      |  4 +-
 packages/{fs => e2b}/fs-e2b/package.json      |  0
 packages/{fs => e2b}/fs-e2b/src/index.ts      |  0
 packages/{fs => e2b}/fs-e2b/src/invariant.ts  |  0
 .../fs-e2b/tests/filesystem.spec.ts           |  0
 packages/{fs => e2b}/fs-e2b/tsconfig.json     |  4 +-
 .../pty-e2b => e2b/lsp-e2b}/README.i18n.yaml  |  6 +-
 packages/{lsp => e2b}/lsp-e2b/README.md       |  2 +-
 packages/{lsp => e2b}/lsp-e2b/README.zh.md    |  2 +-
 packages/{lsp => e2b}/lsp-e2b/package.json    |  0
 packages/{lsp => e2b}/lsp-e2b/src/index.ts    |  0
 .../{lsp => e2b}/lsp-e2b/src/invariant.ts     |  0
 .../{lsp => e2b}/lsp-e2b/src/proxy-source.ts  |  0
 .../{lsp => e2b}/lsp-e2b/src/transport.ts     |  0
 .../lsp-e2b/tests/provider.spec.ts            |  0
 .../lsp-e2b/tests/transport.spec.ts           |  0
 packages/{lsp => e2b}/lsp-e2b/tsconfig.json   |  8 +--
 .../lsp-e2b => e2b/pty-e2b}/README.i18n.yaml  |  6 +-
 packages/{pty => e2b}/pty-e2b/README.md       |  2 +-
 packages/{pty => e2b}/pty-e2b/README.zh.md    |  2 +-
 packages/{pty => e2b}/pty-e2b/package.json    |  0
 packages/{pty => e2b}/pty-e2b/src/config.ts   |  0
 packages/{pty => e2b}/pty-e2b/src/index.ts    |  0
 .../{pty => e2b}/pty-e2b/src/invariant.ts     |  0
 packages/{pty => e2b}/pty-e2b/src/session.ts  |  0
 .../{pty => e2b}/pty-e2b/tests/index.spec.ts  |  0
 .../pty-e2b/tests/session.spec.ts             |  0
 packages/{pty => e2b}/pty-e2b/tsconfig.json   |  4 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  6 ++
 .../subprocess-e2b/README.md                  |  2 +-
 .../subprocess-e2b/README.zh.md               |  2 +-
 .../subprocess-e2b/package.json               |  0
 .../subprocess-e2b/src/index.ts               |  0
 .../subprocess-e2b/src/invariant.ts           |  0
 .../subprocess-e2b/src/output.ts              |  0
 .../subprocess-e2b/src/process.ts             |  0
 .../subprocess-e2b/tests/subprocess.spec.ts   |  0
 .../subprocess-e2b/tsconfig.json              |  4 +-
 packages/fs/README.i18n.yaml                  |  4 +-
 packages/fs/README.md                         |  2 +-
 packages/fs/README.zh.md                      |  2 +-
 packages/lsp/README.i18n.yaml                 |  4 +-
 packages/lsp/README.md                        |  4 +-
 packages/lsp/README.zh.md                     |  4 +-
 packages/pty/README.i18n.yaml                 |  4 +-
 packages/pty/README.md                        |  4 +-
 packages/pty/README.zh.md                     |  4 +-
 packages/subprocess/README.i18n.yaml          |  4 +-
 packages/subprocess/README.md                 |  2 +-
 packages/subprocess/README.zh.md              |  2 +-
 .../verify-package-readme-model-experience.ts |  8 +--
 tsconfig.base.json                            |  1 +
 tsconfig.host.json                            | 10 ++--
 81 files changed, 171 insertions(+), 249 deletions(-)
 delete mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
 delete mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
 delete mode 100644 packages/code-runtime/code-runtime-e2b/README.i18n.yaml
 rename packages/{subprocess/subprocess-e2b => e2b/code-runtime-e2b}/README.i18n.yaml (54%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/README.md (93%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/README.zh.md (93%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/package.json (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/src/index.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/src/invariant.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/src/runner-source.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/tests/runtime.spec.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/tsconfig.json (70%)
 rename packages/{fs => e2b}/fs-e2b/README.i18n.yaml (56%)
 rename packages/{fs => e2b}/fs-e2b/README.md (81%)
 rename packages/{fs => e2b}/fs-e2b/README.zh.md (81%)
 rename packages/{fs => e2b}/fs-e2b/package.json (100%)
 rename packages/{fs => e2b}/fs-e2b/src/index.ts (100%)
 rename packages/{fs => e2b}/fs-e2b/src/invariant.ts (100%)
 rename packages/{fs => e2b}/fs-e2b/tests/filesystem.spec.ts (100%)
 rename packages/{fs => e2b}/fs-e2b/tsconfig.json (87%)
 rename packages/{pty/pty-e2b => e2b/lsp-e2b}/README.i18n.yaml (60%)
 rename packages/{lsp => e2b}/lsp-e2b/README.md (92%)
 rename packages/{lsp => e2b}/lsp-e2b/README.zh.md (92%)
 rename packages/{lsp => e2b}/lsp-e2b/package.json (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/index.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/invariant.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/proxy-source.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/transport.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/tests/provider.spec.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/tests/transport.spec.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/tsconfig.json (75%)
 rename packages/{lsp/lsp-e2b => e2b/pty-e2b}/README.i18n.yaml (60%)
 rename packages/{pty => e2b}/pty-e2b/README.md (93%)
 rename packages/{pty => e2b}/pty-e2b/README.zh.md (93%)
 rename packages/{pty => e2b}/pty-e2b/package.json (100%)
 rename packages/{pty => e2b}/pty-e2b/src/config.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/src/index.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/src/invariant.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/src/session.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/tests/index.spec.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/tests/session.spec.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/tsconfig.json (85%)
 create mode 100644 packages/e2b/subprocess-e2b/README.i18n.yaml
 rename packages/{subprocess => e2b}/subprocess-e2b/README.md (89%)
 rename packages/{subprocess => e2b}/subprocess-e2b/README.zh.md (89%)
 rename packages/{subprocess => e2b}/subprocess-e2b/package.json (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/index.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/invariant.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/output.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/process.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/tests/subprocess.spec.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/tsconfig.json (84%)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 46f1849b07..5ed4e445b8 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 730e6f0e1958ccab43a5a6a11931f9407b38ef16
-2026-07-27-e2b-remote-runtime-poc.zh.md: 5f1ae07b985787a7dc1bd61f2a5b7ff0512d85c1
+2026-07-27-e2b-remote-runtime-poc.md: a713cca3fd9e7ee11a2c487bf6ed2c3a205dc502
+2026-07-27-e2b-remote-runtime-poc.zh.md: 7afd54f72622d51a3d71719b3b4975ccd7f83e3a
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 730e6f0e19..a713cca3fd 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -6,29 +6,43 @@ English | [中文](2026-07-27-e2b-remote-runtime-poc.zh.md)
 
 ## Problem
 
-A remote coding-agent backend is useful only when file operations and commands observe one coherent world. Attaching E2B independently at individual tools would allow a Bash command and a filesystem edit to address different sandboxes, while moving the complete harness into a remote VM would couple provider experimentation to agent, session, model, persistence, and deployment changes.
+A remote coding-agent backend is useful only when filesystem operations, one-shot commands, persistent terminals, language servers, and model-written programs observe one coherent world. Attaching E2B independently at individual tools would let those capabilities address different sandboxes, while retaining host PTY, LSP, or worker backends would split state across machines even when the cwd strings match.
+
+Moving the complete harness into a remote VM would unify that state but also couple provider experimentation to plugin loading, credentials, model transport, agent/session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
 
 ## Decision
 
-The E2B integration is a provider-composition POC with one shared lifecycle owner and two capability implementations:
+The E2B integration is an opt-in provider-composition POC. Its six E2B-specific packages live under `packages/e2b/` while retaining seam-specific npm names:
 
 - `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
 - `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
+- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` while the existing registry retains exact-Agent ownership.
+- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
+- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
 - The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
-- PTY, LSP, and Code Runtime remain separate capability providers over the same owner, with their runtime split recorded in the [extension decision](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
 
-The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes. The composition therefore gives filesystem tools and Bash one remote cwd, process namespace, and spill/state directory while preserving the existing capability interfaces and model-facing tools.
+The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces and model-facing tools.
+
+The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling lives in `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
 
 ## POC boundary
 
-Filesystem state, managed commands, interactive shells, language servers, code workers, and adapter-owned files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, capability protocol state, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when their provider disposes, including before a retained-sandbox pause or leave disposition.
+E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
 
-The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host PTY/LSP/code-runtime state, process handles, output cursors, pending calls, or locks.
+The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
+
+Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+
+Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
+
+The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
 
 ## Verification
 
-Package tests pin lifecycle cleanup, filesystem semantics, subprocess groups, byte framing, PTY readiness/signals, LSP transport and containment, Code Runtime binding/output behavior, and package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, exercises filesystem, Bash/subprocess, PTY, LSP, and Code Runtime through source and built package paths, proves host-workspace isolation, disposes the composition, and confirms the sandbox id is gone.
+Focused package suites pin owner lifecycle cleanup, filesystem semantics, subprocess process groups, configuration and publication rollback, byte framing and multibyte boundaries, PTY readiness/signals, LSP transport and source containment, Code Runtime bindings, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+
+A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
 
 ## Alternatives considered
 
@@ -40,8 +54,16 @@ Package tests pin lifecycle cleanup, filesystem semantics, subprocess groups, by
 
 **Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
 
+**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
+
+**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
+
+**Add a generic distributed-runtime abstraction first** — rejected because the existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
+
+**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
+
 ## Consequences
 
-The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual state retention for experiments, while kill remains the demo's cleanup policy.
+The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The provider is not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 5f1ae07b98..7afd54f726 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -6,29 +6,43 @@ Status: implemented
 
 ## 问题
 
-远程 coding agent（智能体）后端只有在文件操作与命令观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，Bash 命令和文件系统编辑可能访问不同的沙箱；若把完整 harness 迁入远程 VM，则会把提供方实验与 agent、会话、模型、持久化及部署变更耦合在一起。
+远程 coding agent（智能体）后端只有在文件系统操作、一次性命令、持久终端、语言服务器和模型编写的程序观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，这些功能可能访问不同的沙箱；即使 cwd 字符串相同，保留宿主 PTY、LSP 或 worker 后端也会让状态分散在不同机器上。
+
+把完整 harness 迁入远程 VM 可以统一这些状态，但也会把提供方实验与插件加载、凭据、模型传输、agent／会话持久性、监管和部署耦合在一起。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
 
 ## 决策
 
-E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和两个功能实现组成：
+E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专用包（package）位于 `packages/e2b/` 下，同时保留按 seam 区分的 npm 名称：
 
 - `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
 - `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
+- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
+- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
+- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
 - 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
-- PTY、LSP 与 Code Runtime 仍是基于同一所有者的独立功能提供方；其运行时划分见[扩展决策](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
 
-该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱。因此，该组合让文件系统工具与 Bash 共享一个远程 cwd、进程命名空间和 spill／状态目录，同时保留现有功能接口与面向模型的工具。
+该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口与面向模型的工具。
+
+这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理位于 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
 
 ## POC 边界
 
-文件系统状态、受管命令、交互式 shell、语言服务器、代码 worker 和适配器拥有的文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排、功能协议状态和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在所属提供方 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
+E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
 
-本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主 PTY／LSP／Code Runtime 状态、进程句柄、输出游标、待处理调用或锁。
+宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
+
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+
+保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
+
+本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄或完整 harness 执行。
 
 ## 验证
 
-包测试固定生命周期清理、文件系统语义、进程管理的进程组、字节分帧、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定／输出行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，通过源代码与已构建包路径演练文件系统、Bash／进程管理、PTY、LSP 和 Code Runtime，证明宿主工作区隔离，释放组合，并确认该沙箱 id 已不存在。
+聚焦包测试套件固定所有者生命周期清理、文件系统语义、进程管理的进程组、配置与发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+
+凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
@@ -40,8 +54,16 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 
 **仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
 
+**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
+
+**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
+
+**先添加通用分布式运行时抽象。** 不予采纳，因为现有功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
+
+**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
+
 ## 后果
 
-这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留状态，演示仍以 `kill` 作为清理策略。
+这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-该提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离已捕获远程进程组的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
deleted file mode 100644
index e34f939a7f..0000000000
--- a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
-2026-07-28-e2b-interactive-semantic-code-runtime-poc.md: befaa47dd56b7f425e72978ae040bd0815cc9f92
-2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md: 677c3a09f6846320d3e000e9607becb3dee865cf
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
deleted file mode 100644
index befaa47dd5..0000000000
--- a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Agent Note: E2B interactive, semantic, and code-runtime POC
-
-Status: implemented
-
-English | [中文](2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md)
-
-## Problem
-
-The [shared E2B runtime](2026-07-27-e2b-remote-runtime-poc.md) proves that filesystem operations and one-shot commands can inhabit one remote coding world, but an assembled coding agent also uses persistent terminals, language servers, and model-written Code Mode programs. Falling back to host implementations for those capabilities splits observable state: a Bash edit exists in E2B while a host PTY, LSP process, or code worker addresses a different filesystem and process namespace.
-
-Moving the complete harness process into E2B would unify that state but also changes plugin loading, credentials, model transport, session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
-
-## Decision
-
-Three opt-in providers extend the existing shared sandbox:
-
-- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` and keeps exact-Agent ownership in the existing registry.
-- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
-- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
-
-All three inject `ctx.e2b`; none creates another sandbox. The opt-in overlay composes them with `dsh-fs-e2b`, `dsh-subprocess-e2b`, and the existing `dsh-bash-local`, so files, foreground commands, interactive shell processes, language servers, and code workers observe one remote cwd.
-
-The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling moves into `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
-
-## Runtime boundary
-
-E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
-
-The host owns Cordis and plugin objects, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The host workspace is not mounted or synchronized merely because its absolute cwd string is reused remotely.
-
-Byte-sensitive protocols use the narrowest adapter needed for E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
-
-Retaining a sandbox preserves remote files and any unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups are terminated and awaited when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
-
-## Verification
-
-Focused unit suites pin configuration, publication rollback, byte framing, multibyte boundaries, readiness, signals, timeout/abort ordering, output limits, hostile Code Runtime traffic, and disposal to quiescence. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
-
-A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
-
-## Alternatives considered
-
-**Run the complete harness inside E2B** — rejected because it couples this provider experiment to credentials, LLM transport, plugin deployment, session persistence, supervision, and remote package installation. None is necessary to prove the capability seams.
-
-**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
-
-**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
-
-**Add a generic distributed-runtime abstraction first** — rejected because the three existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
-
-**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
-
-## Consequences
-
-The assembled POC keeps the coding world remote without moving the agent runtime or changing model-visible tool contracts. It demonstrates that PTY, LSP, and Code Runtime can share E2B state through existing plugins, while making the remaining host state explicit.
-
-This is not a deployment platform. Language-server installation, templates, volumes, snapshots, network policy, workspace synchronization, durable remote handles, and whole-harness execution remain outside scope. E2B SDK buffering and host protocol state remain memory costs. Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group is not made reconnectable or owned by this composition.
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
deleted file mode 100644
index 677c3a09f6..0000000000
--- a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Agent Note: E2B 交互式、语义与代码运行时 POC
-
-Status: implemented
-
-[English](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) | 中文
-
-## 问题
-
-[共享 E2B 运行时](2026-07-27-e2b-remote-runtime-poc.md)证明，文件系统操作与一次性命令可以共处一个远程 coding 环境，但组装完成的 coding agent（智能体）还会使用持久终端、语言服务器，以及模型编写的 Code Mode 程序。若这些功能回退到宿主实现，可观测状态就会分裂：Bash 修改存在于 E2B 中，而宿主 PTY、LSP 进程或代码 worker 面向的却是另一个文件系统与进程命名空间。
-
-把完整 harness 进程迁入 E2B 可以统一这些状态，但也会改变插件加载、凭据、模型传输、会话持久性、监管和部署。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
-
-## 决策
-
-三个可选提供方扩展现有共享沙箱：
-
-- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
-- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
-- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
-
-三个提供方均注入 `ctx.e2b`，无一创建其他沙箱。可选叠加配置将它们与 `dsh-fs-e2b`、`dsh-subprocess-e2b` 和现有的 `dsh-bash-local` 组合，使文件、前台命令、交互式 shell 进程、语言服务器和代码 worker 观察到同一个远程 cwd。
-
-这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理移入 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
-
-## 运行时边界
-
-E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
-
-宿主拥有 Cordis 与插件对象、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。宿主工作区不会仅因远程复用了其绝对 cwd 字符串就被挂载或同步。
-
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
-
-保留沙箱只会保存远程文件与任何未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
-
-## 验证
-
-聚焦单元测试固定配置、发布回滚、字节分帧、多字节边界、就绪状态、信号、超时／中止顺序、输出上限、恶意 Code Runtime 通信，以及等待完全停稳的资源释放。相邻本地后端测试固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
-
-凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
-
-## 曾考虑的替代方案
-
-**在 E2B 内运行完整 harness。** 不予采纳，因为这会把这项提供方实验与凭据、LLM 传输、插件部署、会话持久化、监管和远程包安装耦合。要证明功能 seam，无需引入任何一项。
-
-**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
-
-**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
-
-**先添加通用分布式运行时抽象。** 不予采纳，因为现有三个功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
-
-**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
-
-## 后果
-
-组装后的 POC 在不迁移 agent 运行时、不改变模型可见工具契约的前提下，把 coding 环境保留在远程。它证明 PTY、LSP 与 Code Runtime 可以通过现有插件共享 E2B 状态，同时明确列出仍留在宿主的状态。
-
-这不是部署平台。语言服务器安装、模板、卷、快照、网络策略、工作区同步、持久远程句柄和完整 harness 执行仍不在范围内。E2B SDK 缓冲与宿主协议状态仍会占用内存。模型程序与 Node worker 内部机制共享一个 JavaScript realm；有意逃离已捕获远程进程组的进程，也不会因此变得可重新连接或由该组合管理。
diff --git a/AGENTS.md b/AGENTS.md
index 64f2e944a8..c663a5e099 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,10 +12,9 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
-  api/         Remote BFF assembly and TypeRT RPC gateway
-  typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
-  bash/        bash executor seam + local/pwsh impls + model-facing shell tools
+  e2b/         remote-runtime POC
+  bash/        bash executor seam + local impl + model-facing bash tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
   fs/          filesystem seam + local impl + policy gate + read/write/edit tools
@@ -25,7 +24,6 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   compact/     compaction seam + basic backend
   context/     request-context plugins
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
-  bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
   plan/        plan mode as logged per-agent collaboration state
@@ -33,11 +31,9 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
   session-persistence/  persistence seam + JSONL/SQLite backends
-  settings/    user-settings seam + file-backed provider
-  credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
-  ui/          JSON-RPC bridge; boot, approval, interaction plugins
-  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
+  ui/          TUI/JSON-RPC bridges; boot, approval, interaction plugins
+  examples/    demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
@@ -59,7 +55,7 @@ pnpm run clean           # remove build outputs and safe residue from deleted pa
 pnpm run test           # vitest unit tests
 pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src
 pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
-pnpm run test:snapshot  # keyless ACP/headless replay vs expected outputs; filter: -t <name>
+pnpm run test:snapshot  # keyless ACP/headless/TUI replay vs expected outputs; filter: -t <name>
 pnpm run test:snapshot:record  # re-record expected outputs (needs key)
 pnpm run typecheck
 pnpm run lint
@@ -70,6 +66,7 @@ pnpm run hygiene        # knip + publint + workspace constraints + NodeNext cons
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm run demo:headless "task" # one-shot agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:tui       # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis    # the agent modifies its own runtime (needs key)
 pnpm run demo:acp       # ACP automation server (needs DEEPSEEK_API_KEY)
 ```
@@ -80,7 +77,7 @@ When required `gh`, `pnpm`, build, test, or generator commands fail because the
 
 ### Run relevant checks locally
 
-Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
+Agents MUST run relevant tests and checks before pushing; select them with [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md) and report only commands run.
 
 - Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
 - Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
@@ -93,7 +90,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)).
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
@@ -117,7 +114,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
-- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
+- **Use incremental merge commits.** Split independent changes; never squash, rebase, or rewrite pushed history. Fix the introducing PR before merging down-stack. If the base advances mid-merge, never restart: finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
 - **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 3eee08f35b..b8320d8c19 100644
--- 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: 1b2a1737bcac33829a65fa937668ca9496035330
-README.zh.md: 2ef61e9c38750f4420ce99abc9943af1f3308b56
+README.md: c46a08f76f9f38f9620c03f05f28e7698487afc8
+README.zh.md: 65a5c6c88b9b37b3f948b11c6db778e42965643d
diff --git a/packages/README.md b/packages/README.md
index 54a5779016..b2a870f516 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -16,7 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
-| [`e2b/`](e2b/README.md) | E2B remote filesystem/process providers | POC |
+| [`e2b/`](e2b/README.md) | E2B remote-runtime provider family | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 46b112ec8f..c8079c3d03 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -16,7 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
-| [`e2b/`](e2b/README.md) | E2B 远程文件系统／进程管理提供方 | POC |
+| [`e2b/`](e2b/README.md) | E2B 远程运行时提供方系列 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index f9160b4f8e..30c5ca2572 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: f59fc3b15331b4799cbc7a3fbe27ce8cd9a12e51
-README.zh.md: 02ade97887fab8a8a0c22efcf73bb2dd1f2cf33c
+README.md: 34eecc4874afc5a576ed129e72eeeb944b95f67f
+README.zh.md: 85d7a95a37cd1f4090062f3036a6634fde5011ee
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index f59fc3b153..34eecc4874 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -8,6 +8,6 @@ The code-execution capability seam (see [capability seams](../../.agents/notes/i
 |---|---|---|
 | `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` |
-| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
+| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
 
-Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [remote extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
+Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index 02ade97887..85d7a95a37 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | `code-runtime/` | 抽象代码执行 seam（接口 + 词汇） | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | worker 线程后端：每次运行使用全新 worker，由宿主侧剥离 TypeScript 类型（类型注解仅供参考，绝不执行类型检查）、端口桥接绑定、预算／堆隔离 | 注册 `ctx.codeRuntime` |
-| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
+| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
 
-不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[远程扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
+不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
diff --git a/packages/code-runtime/code-runtime-e2b/README.i18n.yaml b/packages/code-runtime/code-runtime-e2b/README.i18n.yaml
deleted file mode 100644
index c00b40f4a2..0000000000
--- a/packages/code-runtime/code-runtime-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/code-runtime/code-runtime-e2b/README.md
-README.md: bf26174c59c1df18f63278acb7923fd409860b44
-README.zh.md: c87945da30a6f8d77eb3722879510bb6159b3ee8
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 444145fbb8..1ded2a1d34 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: 9e7f1a98ada9f56f3d1e3f74d2a906f8a1c7bc15
-README.zh.md: 53fdf30eaf405ab5313274a7fadde0b044b7fba1
+README.md: b25f00fb5f32643008127f0cee4f3d758018404a
+README.zh.md: fc3d6901f3cdf6c645cfde49dc46108759959aca
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index 9e7f1a98ad..b25f00fb5f 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -7,10 +7,10 @@ An experimental provider-composition POC that places the mutable coding world in
 | Package | ctx key | Role |
 |---|---|---|
 | [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
-| [`fs-e2b`](../fs/fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
-| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
-| [`pty-e2b`](../pty/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
-| [`lsp-e2b`](../lsp/lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
-| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
+| [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
+| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
+| [`lsp-e2b`](lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
+| [`code-runtime-e2b`](code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [base decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) and [runtime-extension decision](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) own the POC boundary.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index 53fdf30eaf..fc3d6901f3 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -7,10 +7,10 @@
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
 | [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
-| [`fs-e2b`](../fs/fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
-| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
-| [`pty-e2b`](../pty/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
-| [`lsp-e2b`](../lsp/lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
-| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
+| [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
+| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
+| [`lsp-e2b`](lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
+| [`code-runtime-e2b`](code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[基础决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)与[运行时扩展决策](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)共同界定 POC 边界。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界。
diff --git a/packages/subprocess/subprocess-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
similarity index 54%
rename from packages/subprocess/subprocess-e2b/README.i18n.yaml
rename to packages/e2b/code-runtime-e2b/README.i18n.yaml
index dfbe97e8b9..9eb2633b86 100644
--- a/packages/subprocess/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/code-runtime-e2b/README.i18n.yaml
@@ -1,6 +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/subprocess/subprocess-e2b/README.md
-README.md: 9ec1518103413f33a52023c17722bf5a5fe275ce
-README.zh.md: f50ff2f3d85a5ddd9bd352e95d0eb0a23e756404
+#   pnpm run verify-translation-pairing --write packages/e2b/code-runtime-e2b/README.md
+README.md: 1007800c59725d116197a52f6d087ea5e2860686
+README.zh.md: a56026bce760879079627dd63a80dfe95c4d2049
diff --git a/packages/code-runtime/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
similarity index 93%
rename from packages/code-runtime/code-runtime-e2b/README.md
rename to packages/e2b/code-runtime-e2b/README.md
index bf26174c59..1007800c59 100644
--- a/packages/code-runtime/code-runtime-e2b/README.md
+++ b/packages/e2b/code-runtime-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of [`ctx.codeRuntime`](../code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
+E2B implementation of [`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
 
 ## Configuration
 
diff --git a/packages/code-runtime/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
similarity index 93%
rename from packages/code-runtime/code-runtime-e2b/README.zh.md
rename to packages/e2b/code-runtime-e2b/README.zh.md
index c87945da30..a56026bce7 100644
--- a/packages/code-runtime/code-runtime-e2b/README.zh.md
+++ b/packages/e2b/code-runtime-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`ctx.codeRuntime`](../code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
+[`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
 
 ## 配置
 
diff --git a/packages/code-runtime/code-runtime-e2b/package.json b/packages/e2b/code-runtime-e2b/package.json
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/package.json
rename to packages/e2b/code-runtime-e2b/package.json
diff --git a/packages/code-runtime/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/src/index.ts
rename to packages/e2b/code-runtime-e2b/src/index.ts
diff --git a/packages/code-runtime/code-runtime-e2b/src/invariant.ts b/packages/e2b/code-runtime-e2b/src/invariant.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/src/invariant.ts
rename to packages/e2b/code-runtime-e2b/src/invariant.ts
diff --git a/packages/code-runtime/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/src/runner-source.ts
rename to packages/e2b/code-runtime-e2b/src/runner-source.ts
diff --git a/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
rename to packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
diff --git a/packages/code-runtime/code-runtime-e2b/tsconfig.json b/packages/e2b/code-runtime-e2b/tsconfig.json
similarity index 70%
rename from packages/code-runtime/code-runtime-e2b/tsconfig.json
rename to packages/e2b/code-runtime-e2b/tsconfig.json
index 4ddc3b5ffe..3bc2e21873 100644
--- a/packages/code-runtime/code-runtime-e2b/tsconfig.json
+++ b/packages/e2b/code-runtime-e2b/tsconfig.json
@@ -9,11 +9,11 @@
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
-    { "path": "../code-runtime" },
-    { "path": "../code-runtime-worker" },
-    { "path": "../../e2b/e2b" },
+    { "path": "../../code-runtime/code-runtime" },
+    { "path": "../../code-runtime/code-runtime-worker" },
+    { "path": "../e2b" },
     { "path": "../../core/session" },
-    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../subprocess-e2b" },
     { "path": "../../util/timeout" },
     { "path": "../../support/invariants" }
   ]
diff --git a/packages/fs/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
similarity index 56%
rename from packages/fs/fs-e2b/README.i18n.yaml
rename to packages/e2b/fs-e2b/README.i18n.yaml
index d3ea2786b2..b416105166 100644
--- a/packages/fs/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/README.i18n.yaml
@@ -1,6 +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/fs/fs-e2b/README.md
-README.md: 2b23884e345e7c39b0559465afa0bc588699b70a
-README.zh.md: 1a9a174ac90c59b68b02887303f58ee2a99dc72e
+#   pnpm run verify-translation-pairing --write packages/e2b/fs-e2b/README.md
+README.md: d8f3915fa281e8b9c062e3412c92bc6358616284
+README.zh.md: 93d27bcdd514ccbf87e07d0eff5958edf3c726c1
diff --git a/packages/fs/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
similarity index 81%
rename from packages/fs/fs-e2b/README.md
rename to packages/e2b/fs-e2b/README.md
index 2b23884e34..d8f3915fa2 100644
--- a/packages/fs/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-fs`](../fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
 
 ## Behavior
 
@@ -15,7 +15,7 @@ The provider does not copy, mount, or reconcile the host workspace. Giving it a
 
 ## Model Experience
 
-Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
+Indirectly, through [`dsh-tool-fs`](../../fs/tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
 
 #### KV Cache effect
 
diff --git a/packages/fs/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
similarity index 81%
rename from packages/fs/fs-e2b/README.zh.md
rename to packages/e2b/fs-e2b/README.zh.md
index 1a9a174ac9..93d27bcdd5 100644
--- a/packages/fs/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-fs`](../fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
 
 ## 行为
 
@@ -15,7 +15,7 @@
 
 ## 模型体验
 
-通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
+通过 [`dsh-tool-fs`](../../fs/tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
 
 #### KV Cache 影响
 
diff --git a/packages/fs/fs-e2b/package.json b/packages/e2b/fs-e2b/package.json
similarity index 100%
rename from packages/fs/fs-e2b/package.json
rename to packages/e2b/fs-e2b/package.json
diff --git a/packages/fs/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
similarity index 100%
rename from packages/fs/fs-e2b/src/index.ts
rename to packages/e2b/fs-e2b/src/index.ts
diff --git a/packages/fs/fs-e2b/src/invariant.ts b/packages/e2b/fs-e2b/src/invariant.ts
similarity index 100%
rename from packages/fs/fs-e2b/src/invariant.ts
rename to packages/e2b/fs-e2b/src/invariant.ts
diff --git a/packages/fs/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
similarity index 100%
rename from packages/fs/fs-e2b/tests/filesystem.spec.ts
rename to packages/e2b/fs-e2b/tests/filesystem.spec.ts
diff --git a/packages/fs/fs-e2b/tsconfig.json b/packages/e2b/fs-e2b/tsconfig.json
similarity index 87%
rename from packages/fs/fs-e2b/tsconfig.json
rename to packages/e2b/fs-e2b/tsconfig.json
index c424efd2e5..bcb54a88d9 100644
--- a/packages/fs/fs-e2b/tsconfig.json
+++ b/packages/e2b/fs-e2b/tsconfig.json
@@ -13,10 +13,10 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../e2b/e2b"
+      "path": "../e2b"
     },
     {
-      "path": "../fs"
+      "path": "../../fs/fs"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/pty/pty-e2b/README.i18n.yaml b/packages/e2b/lsp-e2b/README.i18n.yaml
similarity index 60%
rename from packages/pty/pty-e2b/README.i18n.yaml
rename to packages/e2b/lsp-e2b/README.i18n.yaml
index bfd7795349..5f126d7e56 100644
--- a/packages/pty/pty-e2b/README.i18n.yaml
+++ b/packages/e2b/lsp-e2b/README.i18n.yaml
@@ -1,6 +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/pty/pty-e2b/README.md
-README.md: 7a8ddc9e08f4d28d69b97825232b00e2d8f394b7
-README.zh.md: 2151ca1f2d91b01a7b0106153f708ace2c3d2726
+#   pnpm run verify-translation-pairing --write packages/e2b/lsp-e2b/README.md
+README.md: ded928ec073e6c0943d574d86359eeec586bb862
+README.zh.md: 91eb7cecb49adcf73f4be948e9a5da400981e6f1
diff --git a/packages/lsp/lsp-e2b/README.md b/packages/e2b/lsp-e2b/README.md
similarity index 92%
rename from packages/lsp/lsp-e2b/README.md
rename to packages/e2b/lsp-e2b/README.md
index 968487b7c5..ded928ec07 100644
--- a/packages/lsp/lsp-e2b/README.md
+++ b/packages/e2b/lsp-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Generic E2B language-server backend for [`ctx.lsp`](../lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
+Generic E2B language-server backend for [`ctx.lsp`](../../lsp/lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
 
 ## Plugin and configuration
 
diff --git a/packages/lsp/lsp-e2b/README.zh.md b/packages/e2b/lsp-e2b/README.zh.md
similarity index 92%
rename from packages/lsp/lsp-e2b/README.zh.md
rename to packages/e2b/lsp-e2b/README.zh.md
index 2b937f0115..91eb7cecb4 100644
--- a/packages/lsp/lsp-e2b/README.zh.md
+++ b/packages/e2b/lsp-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-用于 [`ctx.lsp`](../lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
+用于 [`ctx.lsp`](../../lsp/lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
 
 ## 插件与配置
 
diff --git a/packages/lsp/lsp-e2b/package.json b/packages/e2b/lsp-e2b/package.json
similarity index 100%
rename from packages/lsp/lsp-e2b/package.json
rename to packages/e2b/lsp-e2b/package.json
diff --git a/packages/lsp/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/index.ts
rename to packages/e2b/lsp-e2b/src/index.ts
diff --git a/packages/lsp/lsp-e2b/src/invariant.ts b/packages/e2b/lsp-e2b/src/invariant.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/invariant.ts
rename to packages/e2b/lsp-e2b/src/invariant.ts
diff --git a/packages/lsp/lsp-e2b/src/proxy-source.ts b/packages/e2b/lsp-e2b/src/proxy-source.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/proxy-source.ts
rename to packages/e2b/lsp-e2b/src/proxy-source.ts
diff --git a/packages/lsp/lsp-e2b/src/transport.ts b/packages/e2b/lsp-e2b/src/transport.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/transport.ts
rename to packages/e2b/lsp-e2b/src/transport.ts
diff --git a/packages/lsp/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/tests/provider.spec.ts
rename to packages/e2b/lsp-e2b/tests/provider.spec.ts
diff --git a/packages/lsp/lsp-e2b/tests/transport.spec.ts b/packages/e2b/lsp-e2b/tests/transport.spec.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/tests/transport.spec.ts
rename to packages/e2b/lsp-e2b/tests/transport.spec.ts
diff --git a/packages/lsp/lsp-e2b/tsconfig.json b/packages/e2b/lsp-e2b/tsconfig.json
similarity index 75%
rename from packages/lsp/lsp-e2b/tsconfig.json
rename to packages/e2b/lsp-e2b/tsconfig.json
index 4679845db8..a6c0fd8ece 100644
--- a/packages/lsp/lsp-e2b/tsconfig.json
+++ b/packages/e2b/lsp-e2b/tsconfig.json
@@ -9,11 +9,11 @@
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
-    { "path": "../../e2b/e2b" },
-    { "path": "../lsp" },
-    { "path": "../lsp-local" },
+    { "path": "../e2b" },
+    { "path": "../../lsp/lsp" },
+    { "path": "../../lsp/lsp-local" },
     { "path": "../../subprocess/subprocess" },
-    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../subprocess-e2b" },
     { "path": "../../util/timeout" },
     { "path": "../../support/invariants" }
   ]
diff --git a/packages/lsp/lsp-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
similarity index 60%
rename from packages/lsp/lsp-e2b/README.i18n.yaml
rename to packages/e2b/pty-e2b/README.i18n.yaml
index fa159820a9..1bd8485e8f 100644
--- a/packages/lsp/lsp-e2b/README.i18n.yaml
+++ b/packages/e2b/pty-e2b/README.i18n.yaml
@@ -1,6 +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/lsp/lsp-e2b/README.md
-README.md: 968487b7c5f63b2165cf66797a4182642507a8e9
-README.zh.md: 2b937f01156c3194f64ed9fb54478fec5c77305b
+#   pnpm run verify-translation-pairing --write packages/e2b/pty-e2b/README.md
+README.md: 3d363309f6bd1c4def5fbff668735958ca2de52d
+README.zh.md: 78d61cc654bf6eb46a3bec7124b3cc06cc7e34e9
diff --git a/packages/pty/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
similarity index 93%
rename from packages/pty/pty-e2b/README.md
rename to packages/e2b/pty-e2b/README.md
index 7a8ddc9e08..3d363309f6 100644
--- a/packages/pty/pty-e2b/README.md
+++ b/packages/e2b/pty-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B byte-PTY backend for [`ctx.pty`](../pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
+E2B byte-PTY backend for [`ctx.pty`](../../pty/pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
 
 ## Plugin and configuration
 
diff --git a/packages/pty/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
similarity index 93%
rename from packages/pty/pty-e2b/README.zh.md
rename to packages/e2b/pty-e2b/README.zh.md
index 2151ca1f2d..78d61cc654 100644
--- a/packages/pty/pty-e2b/README.zh.md
+++ b/packages/e2b/pty-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-用于 [`ctx.pty`](../pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
+用于 [`ctx.pty`](../../pty/pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
 
 ## 插件与配置
 
diff --git a/packages/pty/pty-e2b/package.json b/packages/e2b/pty-e2b/package.json
similarity index 100%
rename from packages/pty/pty-e2b/package.json
rename to packages/e2b/pty-e2b/package.json
diff --git a/packages/pty/pty-e2b/src/config.ts b/packages/e2b/pty-e2b/src/config.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/config.ts
rename to packages/e2b/pty-e2b/src/config.ts
diff --git a/packages/pty/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/index.ts
rename to packages/e2b/pty-e2b/src/index.ts
diff --git a/packages/pty/pty-e2b/src/invariant.ts b/packages/e2b/pty-e2b/src/invariant.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/invariant.ts
rename to packages/e2b/pty-e2b/src/invariant.ts
diff --git a/packages/pty/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/session.ts
rename to packages/e2b/pty-e2b/src/session.ts
diff --git a/packages/pty/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
similarity index 100%
rename from packages/pty/pty-e2b/tests/index.spec.ts
rename to packages/e2b/pty-e2b/tests/index.spec.ts
diff --git a/packages/pty/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
similarity index 100%
rename from packages/pty/pty-e2b/tests/session.spec.ts
rename to packages/e2b/pty-e2b/tests/session.spec.ts
diff --git a/packages/pty/pty-e2b/tsconfig.json b/packages/e2b/pty-e2b/tsconfig.json
similarity index 85%
rename from packages/pty/pty-e2b/tsconfig.json
rename to packages/e2b/pty-e2b/tsconfig.json
index 0a7647aa80..06bf0cd589 100644
--- a/packages/pty/pty-e2b/tsconfig.json
+++ b/packages/e2b/pty-e2b/tsconfig.json
@@ -9,8 +9,8 @@
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
-    { "path": "../../e2b/e2b" },
-    { "path": "../pty" },
+    { "path": "../e2b" },
+    { "path": "../../pty/pty" },
     { "path": "../../support/invariants" }
   ]
 }
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..26bc8f0b51
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
+README.md: ce61de1100791be6e5c4db74c73ff43566281ed9
+README.zh.md: a4c619f0c002cc1d36310c5a9b4a3f7ae655ad1f
diff --git a/packages/subprocess/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
similarity index 89%
rename from packages/subprocess/subprocess-e2b/README.md
rename to packages/e2b/subprocess-e2b/README.md
index 9ec1518103..ce61de1100 100644
--- a/packages/subprocess/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
 
 ## Behavior
 
diff --git a/packages/subprocess/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
similarity index 89%
rename from packages/subprocess/subprocess-e2b/README.zh.md
rename to packages/e2b/subprocess-e2b/README.zh.md
index f50ff2f3d8..a4c619f0c0 100644
--- a/packages/subprocess/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
 
 ## 行为
 
diff --git a/packages/subprocess/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
similarity index 100%
rename from packages/subprocess/subprocess-e2b/package.json
rename to packages/e2b/subprocess-e2b/package.json
diff --git a/packages/subprocess/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/index.ts
rename to packages/e2b/subprocess-e2b/src/index.ts
diff --git a/packages/subprocess/subprocess-e2b/src/invariant.ts b/packages/e2b/subprocess-e2b/src/invariant.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/invariant.ts
rename to packages/e2b/subprocess-e2b/src/invariant.ts
diff --git a/packages/subprocess/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/output.ts
rename to packages/e2b/subprocess-e2b/src/output.ts
diff --git a/packages/subprocess/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/process.ts
rename to packages/e2b/subprocess-e2b/src/process.ts
diff --git a/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
rename to packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
diff --git a/packages/subprocess/subprocess-e2b/tsconfig.json b/packages/e2b/subprocess-e2b/tsconfig.json
similarity index 84%
rename from packages/subprocess/subprocess-e2b/tsconfig.json
rename to packages/e2b/subprocess-e2b/tsconfig.json
index f3bb8c2a26..fda7cfc667 100644
--- a/packages/subprocess/subprocess-e2b/tsconfig.json
+++ b/packages/e2b/subprocess-e2b/tsconfig.json
@@ -13,10 +13,10 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../e2b/e2b"
+      "path": "../e2b"
     },
     {
-      "path": "../subprocess"
+      "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index eabb6a602e..6b5a5d8b76 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 8ac8807cc9ca4b5cc31b686cef9796a8e42b7f81
-README.zh.md: 49705790cc0cdf1f7199251e09af0af01f704efb
+README.md: 0b9a244d0c42542909460edf7109dfb9cee34503
+README.zh.md: 77da9b73f866fd88fcb81b28cbb622b0389bf5f0
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 460af7c53b..96bbe6c95b 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -8,7 +8,7 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 |---|---|---|
 | `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
-| `fs-e2b/` | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
+| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 5f70e3cb50..7f091b4f09 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -8,7 +8,7 @@
 |---|---|---|
 | `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
-| `fs-e2b/` | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
+| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
 | `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
 | `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index c28c0282c2..be241ada6e 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 74ed729d97013de3d7f502f728e3abe62348846f
-README.zh.md: 5a08d54ca6c54d8355454fc3021a0da48772000b
+README.md: d8bc6047e7eadeb2993f1114564b41913b2970dc
+README.zh.md: d838af346626bb96299a3b702df0dabb6231c15a
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 74ed729d97..d8bc6047e7 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -8,9 +8,9 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 |---|---|---|
 | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
 | [`lsp-local/`](lsp-local/README.md) | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
-| [`lsp-e2b/`](lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
+| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
-See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) for the remote process/filesystem boundary.
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) for the remote process/filesystem boundary.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index 5a08d54ca6..d838af3466 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -8,9 +8,9 @@
 |---|---|---|
 | `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
 | [`lsp-local/`](lsp-local/README.md) | 通用多服务器本地后端（spawn、JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
-| [`lsp-e2b/`](lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
+| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
-协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
+协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)。
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index c0fa873642..2dff12e3da 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: 239c751f30f8e5c543e6737e65a67f9bb22f79ad
-README.zh.md: edaae7f948d957e2fce2b3f331cc2af61cfabd36
+README.md: a6706ed653bc60909a23b3598c41bb10ef499cbe
+README.zh.md: 01fecf8d57d933168e91331c4d3c3e4666c13cdc
diff --git a/packages/pty/README.md b/packages/pty/README.md
index 239c751f30..a6706ed653 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -8,7 +8,7 @@ English | [中文](README.zh.md)
 |---|---|---|
 | [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
 | [`pty-local`](pty-local/README.md) (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
-| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
+| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
+The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index edaae7f948..01fecf8d57 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -8,7 +8,7 @@
 |---|---|---|
 | [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
 | [`pty-local`](pty-local/README.md)（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
-| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
+| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
+核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 0efaf7838e..4097420382 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: ae18c55205edd6085a0ed8de1bb7f875c411c79f
-README.zh.md: e27fd240e4c1e96d8b859b326574e441241e8508
+README.md: cdea3803e903b31e895658745bc6dbf5a3c04c71
+README.zh.md: 95b02b6491077750f23ff12ffd14c1aa174609be
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index ae18c55205..cdea3803e9 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -8,6 +8,6 @@ The shared home for spawning managed child-process trees: fully-specified spawn
 |---|---|---|
 | [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: abstract `SubprocessService.spawn(spec)`, the fully-explicit `SubprocessSpawnSpec` with per-stream stdio dispositions, `SubprocessHandle` (streams, offset-based readers, terminate/waitForExit/dispose), and the shared scrub + `DSH_*`/`CollectedOutput` vocabulary |
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, per-disposition stream wiring, tail-keep truncation with bounded private spill files, the `DSH_*` merge order, tree signalling with escalation, the dispose ladder, and terminate-and-join disposal |
-| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
+| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index e27fd240e4..95b02b6491 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -8,6 +8,6 @@ spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其
 |---|---|---|
 | [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
-| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
+| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
 
 服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 5ab5dc2e4e..5ad70c0e68 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,7 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
-  'packages/code-runtime/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/e2b/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
@@ -84,7 +84,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
   'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
-  'packages/fs/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
+  'packages/e2b/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
@@ -99,10 +99,10 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
-  'packages/lsp/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
+  'packages/e2b/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
-  'packages/subprocess/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
+  'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 8380182e83..0673c35b90 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -85,6 +85,7 @@
         "./packages/llm/*/src/invariant.ts",
         "./packages/bash/*/src/invariant.ts",
         "./packages/subprocess/*/src/invariant.ts",
+        "./packages/e2b/*/src/invariant.ts",
         "./packages/code-runtime/*/src/invariant.ts",
         "./packages/fs/*/src/invariant.ts",
         "./packages/skill/*/src/invariant.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1f70e79a4f..526d4ef4b8 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -163,15 +163,15 @@
     { "path": "./packages/subprocess/subprocess" },
     { "path": "./packages/subprocess/subprocess-local" },
     { "path": "./packages/e2b/e2b" },
-    { "path": "./packages/subprocess/subprocess-e2b" },
+    { "path": "./packages/e2b/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
-    { "path": "./packages/pty/pty-e2b" },
+    { "path": "./packages/e2b/pty-e2b" },
     { "path": "./packages/pty/pty-local" },
     { "path": "./packages/pty/tool-bash-persistent" },
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
-    { "path": "./packages/code-runtime/code-runtime-e2b" },
+    { "path": "./packages/e2b/code-runtime-e2b" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -187,7 +187,7 @@
     { "path": "./packages/bash/tool-bash" },
     { "path": "./packages/fs/fs" },
     { "path": "./packages/fs/fs-local" },
-    { "path": "./packages/fs/fs-e2b" },
+    { "path": "./packages/e2b/fs-e2b" },
     { "path": "./packages/fs/fs-policy" },
     { "path": "./packages/fs/fs-sandbox" },
     { "path": "./packages/fs/tool-fs" },
@@ -268,7 +268,7 @@
     { "path": "./packages/sdk/create-sdk" },
     { "path": "./packages/sdk/telemetry" },
     { "path": "./packages/lsp/lsp" },
-    { "path": "./packages/lsp/lsp-e2b" },
+    { "path": "./packages/e2b/lsp-e2b" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
     { "path": "./apps/cli" }

From 3dea36f1ce43d72413fb2b6e8fc3144b7e358d86 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:26:20 +0800
Subject: [PATCH 102/262] fix(e2b): close remote lifecycle gaps

---
 .../tests/fixtures/e2b/e2b/bin.ts             |  71 ++++++-
 .../tests/fixtures/e2b/e2b/cordis.yml         |   4 +-
 packages/e2b/code-runtime-e2b/src/index.ts    |  91 ++++++--
 .../code-runtime-e2b/tests/runtime.spec.ts    | 142 ++++++++++++-
 packages/e2b/e2b/src/frame.ts                 |  23 +-
 packages/e2b/e2b/src/index.ts                 |   8 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  10 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  25 +++
 packages/e2b/fs-e2b/src/index.ts              |   9 +
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |  25 ++-
 packages/e2b/lsp-e2b/src/index.ts             |  11 +
 packages/e2b/lsp-e2b/tests/provider.spec.ts   |   5 +
 packages/e2b/pty-e2b/src/index.ts             |   5 +-
 packages/e2b/pty-e2b/tests/index.spec.ts      |   4 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   2 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  47 +++--
 .../subprocess-e2b/tests/subprocess.spec.ts   |  47 ++++-
 packages/lsp/lsp-local/src/index.ts           | 199 ++++++++----------
 packages/lsp/lsp-local/src/instance.ts        |  13 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |   2 +
 22 files changed, 568 insertions(+), 181 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 33e9530708..89b09a6818 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { posix, resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
 import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -48,20 +48,68 @@ try {
   const fromBash = await ctx.fs.resolve('from-bash.txt')
   const fsRead = await ctx.fs.readText(fromBash)
 
+  const environmentHandle = ctx.subprocess.spawn({
+    argv: ['env'],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 65_536 }, stderr: { maxBytes: 4_096 } },
+    graceMs: 500,
+    env: {
+      'FOO-BAR': 'hyphen-value',
+      DSH_EXPLICIT: 'managed-value',
+      TOKEN_EXPLICIT: 'credential-value',
+    },
+  })
+  const environmentOutcome = await environmentHandle.done
+  const environmentText = environmentHandle.collected.stdout?.readFrom(0).text
+  if (environmentOutcome.exitCode !== 0 || environmentText === undefined) {
+    throw new Error(`E2B subprocess environment probe failed: ${JSON.stringify(environmentOutcome)}`)
+  }
+  const environmentLines = new Set(environmentText.trimEnd().split('\n'))
+  const explicitEnvironment = [
+    'FOO-BAR=hyphen-value',
+    'DSH_EXPLICIT=managed-value',
+    'TOKEN_EXPLICIT=credential-value',
+  ].every(entry => environmentLines.has(entry))
+  if (!explicitEnvironment) throw new Error(`E2B subprocess dropped an explicit environment entry: ${environmentText}`)
+
+  const spillHandle = ctx.subprocess.spawn({
+    argv: ['bash', '-c', "printf '0123456789'; sleep 30"],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 4, spill: { maxBytes: 6 } }, stderr: { maxBytes: 4_096 } },
+    graceMs: 500,
+    env: {},
+  })
+  const spillReader = spillHandle.collected.stdout
+  if (spillReader === undefined) throw new Error('E2B subprocess omitted its configured stdout collector')
+  const spillDeadline = Date.now() + 5_000
+  while (spillReader.readFrom(0).nextOffset < 10) {
+    if (Date.now() >= spillDeadline) throw new Error('E2B subprocess did not stream the spill probe output')
+    await new Promise(resolveDelay => setTimeout(resolveDelay, 20))
+  }
+  const spillPath = posix.join((spillHandle as unknown as { stateDir: string }).stateDir, 'stdout.log')
+  const liveSpillBytes = (await (await ctx.e2b.getSandbox()).files.getInfo(spillPath)).size
+  spillHandle.terminate()
+  const spillOutcome = await spillHandle.done
+  const spillExited = await spillHandle.waitForExit(AbortSignal.timeout(5_000))
+  const spillRead = spillReader.readFrom(0)
+  if (liveSpillBytes !== 6 || !spillExited || spillRead.spillPath !== undefined) {
+    throw new Error(`E2B subprocess spill bound failed: ${JSON.stringify({ liveSpillBytes, spillExited, spillRead })}`)
+  }
+
   const lspFixture = await readFile(new URL('./fixture-lsp.mjs', import.meta.url), 'utf8')
   const remoteLspFixture = await ctx.fs.resolve('fixture-lsp.mjs')
   await ctx.fs.writeText(remoteLspFixture, lspFixture, { kind: 'createIfAbsent' })
-  const remoteSource = await ctx.fs.resolve('multibyte.ts')
+  const remoteSource = await ctx.fs.resolve('multibyte # file.ts')
   await ctx.fs.writeText(remoteSource, 'const café = "你好"\nconsole.log(café)\n', { kind: 'createIfAbsent' })
   const hover = await ctx.lsp.query({
     operation: 'hover',
-    filePath: 'multibyte.ts',
+    filePath: 'multibyte # file.ts',
     position: { line: 0, character: 7 },
     workspaceRoot: process.cwd(),
   })
   const definition = await ctx.lsp.query({
     operation: 'goToDefinition',
-    filePath: 'multibyte.ts',
+    filePath: 'multibyte # file.ts',
     position: { line: 0, character: 7 },
     workspaceRoot: process.cwd(),
   })
@@ -143,6 +191,17 @@ try {
   })
   setTimeout(() => { abortController.abort('live abort') }, 50)
   const aborted = await aborting
+  const oversizedBoot = await ctx.codeRuntime.run({
+    program: `return ${JSON.stringify('x'.repeat(40_000))}`,
+    bindings: [],
+  })
+  const oversizedReply = await ctx.codeRuntime.run({
+    program: 'return await bridge.large(null)',
+    bindings: [{
+      global: 'bridge',
+      functions: { large: async () => 'x'.repeat(40_000) },
+    }],
+  })
   const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
   const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
     JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
@@ -152,6 +211,8 @@ try {
     sandboxId: await ctx.e2b.sandboxId,
     bashRead: bashRead.stdout.text,
     fsRead,
+    explicitEnvironment,
+    spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
     terminal: {
@@ -165,6 +226,8 @@ try {
     hostileOutput,
     timedOut,
     aborted,
+    oversizedBoot,
+    oversizedReply,
     lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index f5cf403c4b..6b3350e49c 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -2,7 +2,7 @@
   name: '@deepseek-ai/dsh-e2b'
   config:
     cwd: !!js process.cwd()
-    timeoutMs: 60000
+    timeoutMs: 120000
     onTimeout: kill
     onDispose: kill
 
@@ -55,5 +55,5 @@
     maxWallMs: 5000
     maxOutputBytes: 4096
     maxOldGenerationSizeMb: 128
-    maxFrameBytes: 4194304
+    maxFrameBytes: 32768
     killGraceMs: 500
diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
index fbfbdea91f..a567a2bb6d 100644
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ b/packages/e2b/code-runtime-e2b/src/index.ts
@@ -14,7 +14,7 @@ import type {
 } from '@deepseek-ai/dsh-code-runtime'
 import {
   E2BFrameDecoder,
-  encodeE2BFrame,
+  encodeBoundedE2BFrame,
   quoteE2BShellArg,
   resolveE2BExecutable,
 } from '@deepseek-ai/dsh-e2b'
@@ -25,6 +25,7 @@ import {
 } from '@deepseek-ai/dsh-code-runtime-worker'
 import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker'
 import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { CODE_RUNNER_SOURCE } from './runner-source.ts'
@@ -46,6 +47,7 @@ export interface Config {
 }
 
 type ResolvedConfig = Required<Config>
+type PreparedRuntime = { node: string; runner: string }
 
 interface LiveRun {
   settle(failure: CodeRunFailure): void
@@ -130,7 +132,7 @@ export class E2BCodeRuntime extends CodeRuntime {
   readonly isolation = 'container'
 
   private readonly config: ResolvedConfig
-  private readonly ready: Promise<{ node: string; runner: string }>
+  private readonly ready: Promise<PreparedRuntime>
   private readonly live = new Set<LiveRun>()
   private readonly subprocess: E2BSubprocessService
   private disposed = false
@@ -176,25 +178,61 @@ export class E2BCodeRuntime extends CodeRuntime {
     } catch (error: unknown) {
       return this.failure({ kind: 'exception', message: messageOf(error) })
     }
-    let runtime: Awaited<typeof this.ready>
+    let runtime: PreparedRuntime | undefined
     try {
-      runtime = await this.ready
+      runtime = await this.awaitPreparation(request.signal)
     } catch (error: unknown) {
+      // Disposal can race the awaited setup despite the synchronous precheck.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
       return this.failure({ kind: 'worker-exit', message: `E2B runtime setup failed: ${messageOf(error)}` })
     }
+    if (runtime === undefined) {
+      return this.failure({ kind: 'abort', message: String(request.signal?.reason) })
+    }
     // Disposal can race the awaited remote setup after the pre-await check.
+    /* v8 ignore start -- requires disposal between promise resolution and its awaiting continuation. */
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
+    /* v8 ignore stop */
     return await this.execute(request, code, bindings, runtime)
   }
   /* jscpd:ignore-end */
 
-  private async prepare(): Promise<{ node: string; runner: string }> {
+  private awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
+    if (signal === undefined) return this.ready
+    return new Promise<PreparedRuntime | undefined>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(undefined) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      if (signal.aborted) {
+        onAbort()
+        return
+      }
+      void this.ready.then(
+        (runtime) => { cleanup(); resolve(runtime) },
+        (error: unknown) => {
+          cleanup()
+          reject(error instanceof Error ? error : new Error(String(error)))
+        },
+      )
+    })
+  }
+
+  private assertPreparationActive(): void {
+    if (this.disposed) throw new Error('code-runtime-e2b: runtime disposed during setup')
+  }
+
+  private async prepare(): Promise<PreparedRuntime> {
     const sandbox = await this.ctx.e2b.getSandbox()
+    this.assertPreparationActive()
     const runner = posix.join(this.ctx.e2b.runtimeRoot, 'code-runtime-runner.mjs')
     await sandbox.files.write([{ path: runner, data: CODE_RUNNER_SOURCE }])
+    this.assertPreparationActive()
     await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(runner)}`)
+    this.assertPreparationActive()
     const node = await resolveE2BExecutable(sandbox, 'node')
+    this.assertPreparationActive()
     return { node, runner }
   }
 
@@ -237,16 +275,25 @@ export class E2BCodeRuntime extends CodeRuntime {
     request: CodeRunRequest,
     code: string,
     bindings: Map<string, CodeBindingNamespace>,
-    runtime: { node: string; runner: string },
+    runtime: PreparedRuntime,
   ): Promise<CodeRunResult> {
-    const handle = this.subprocess.spawn({
-      argv: [runtime.node, runtime.runner],
-      cwd: this.ctx.e2b.cwd,
-      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
-      graceMs: this.config.killGraceMs,
-      ...request.signal === undefined ? {} : { signal: request.signal },
-      env: {},
-    })
+    let handle: SubprocessHandle
+    try {
+      handle = this.subprocess.spawn({
+        argv: [runtime.node, runtime.runner],
+        cwd: this.ctx.e2b.cwd,
+        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
+        graceMs: this.config.killGraceMs,
+        ...request.signal === undefined ? {} : { signal: request.signal },
+        env: {},
+      })
+    } catch (error: unknown) {
+      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
+      if (request.signal?.aborted === true) {
+        return this.failure({ kind: 'abort', message: String(request.signal.reason) })
+      }
+      return this.failure({ kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` })
+    }
     if (handle.stdin === undefined || handle.stdout === undefined) {
       handle.terminate()
       await Promise.allSettled([handle.done])
@@ -279,7 +326,6 @@ export class E2BCodeRuntime extends CodeRuntime {
         settled = true
         clearTimeout(wallTimer.current)
         request.signal?.removeEventListener('abort', onAbort)
-        this.live.delete(live)
         void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
           handle.terminate()
           await handle.done.catch(() => {})
@@ -298,6 +344,7 @@ export class E2BCodeRuntime extends CodeRuntime {
             result = output.failure(logs, { kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(cleanupError)}` })
           }
           const final = typeof result === 'function' ? result() : result
+          this.live.delete(live)
           finishResolve()
           resolve(final)
         })
@@ -305,7 +352,14 @@ export class E2BCodeRuntime extends CodeRuntime {
 
       const sendReply = (message: unknown): void => {
         if (settled) return
-        stdin.write(encodeE2BFrame(message), (error?: Error | null) => {
+        let frame: string
+        try {
+          frame = encodeBoundedE2BFrame(message, this.config.maxFrameBytes)
+        } catch (error: unknown) {
+          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
+          return
+        }
+        stdin.write(frame, (error?: Error | null) => {
           if (error !== undefined && error !== null) {
             finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge write failed: ${error.message}` }))
           }
@@ -433,7 +487,10 @@ export class E2BCodeRuntime extends CodeRuntime {
     this.disposed = true
     const runs = [...this.live]
     for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
-    await Promise.all(runs.map(run => run.finished))
+    await Promise.all([
+      this.ready.then(() => {}, () => {}),
+      ...runs.map(run => run.finished),
+    ])
   }
   /* jscpd:ignore-end */
 }
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
index ff1c5dd84a..9824fb2cf0 100644
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
@@ -34,13 +34,22 @@ class FakeHandle implements SubprocessHandle {
   waitCalls = 0
   private readonly decoder = new E2BFrameDecoder(10_000_000)
   private readonly waitError: Error | undefined
+  private readonly waitResult: Promise<boolean> | undefined
   private settled = false
 
   constructor(
     private readonly onMessage: (message: unknown, handle: FakeHandle) => void = () => {},
-    options: { stdin?: boolean; stdout?: boolean; stderr?: string; writeError?: Error; waitError?: Error } = {},
+    options: {
+      stdin?: boolean
+      stdout?: boolean
+      stderr?: string
+      writeError?: Error
+      waitError?: Error
+      waitResult?: Promise<boolean>
+    } = {},
   ) {
     this.waitError = options.waitError
+    this.waitResult = options.waitResult
     this.stdin = options.stdin === false
       ? undefined
       : options.writeError === undefined
@@ -89,6 +98,7 @@ class FakeHandle implements SubprocessHandle {
   async waitForExit(): Promise<boolean> {
     this.waitCalls += 1
     if (this.waitError !== undefined) throw this.waitError
+    if (this.waitResult !== undefined) return await this.waitResult
     return true
   }
 }
@@ -286,6 +296,30 @@ describe('E2BCodeRuntime', () => {
     await fixture.fiber.dispose()
   })
 
+  it('enforces the outbound frame bound on boot and binding replies', async () => {
+    const oversizedBoot = new FakeHandle()
+    const oversizedReply = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') {
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'large', args: encodeWorkerJson(null) })
+      }
+    })
+    const fixture = await setup([oversizedBoot, oversizedReply], { maxOutputBytes: 128, maxFrameBytes: 512 })
+
+    const bootResult = await fixture.runtime.run(request(`return ${JSON.stringify('x'.repeat(1_000))}`))
+    expect(bootResult.error).toMatchObject({ kind: 'worker-exit' })
+    expect(bootResult.error?.message).toContain('frame exceeded its byte limit')
+    expect(oversizedBoot.writes).toHaveLength(0)
+
+    const replyResult = await fixture.runtime.run({
+      program: 'return await bridge.large(null)',
+      bindings: [{ global: 'bridge', functions: { large: async () => 'x'.repeat(1_000) } }],
+    })
+    expect(replyResult.error).toMatchObject({ kind: 'worker-exit' })
+    expect(replyResult.error?.message).toContain('frame exceeded its byte limit')
+    expect(oversizedReply.writes).toHaveLength(1)
+    await fixture.fiber.dispose()
+  })
+
   it('contains stdin errors, process exits, spawn failures, and missing pipes', async () => {
     const writeError = new FakeHandle(() => {}, { writeError: new Error('write callback broke') })
     const stdinError = new FakeHandle((message, current) => {
@@ -445,12 +479,116 @@ describe('E2BCodeRuntime', () => {
     const gate = Promise.withResolvers<Sandbox>()
     const fixture = await setup([], {}, {}, () => gate.promise)
     const running = fixture.runtime.run(request())
-    await (fixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
+    const disposing = fixture.fiber.dispose()
+    let disposed = false
+    void disposing.then(() => { disposed = true })
+    await new Promise(resolve => setImmediate(resolve))
+    const disposedBeforeSetup = disposed
     gate.resolve(fixture.sandbox)
+    await disposing
+    expect(disposedBeforeSetup).toBe(false)
     expect((await running).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+    expect(fixture.write).not.toHaveBeenCalled()
+  })
+
+  it('observes abort while runtime preparation is pending', async () => {
+    const gate = Promise.withResolvers<Sandbox>()
+    const fixture = await setup([], {}, {}, () => gate.promise)
+    const controller = new AbortController()
+    const running = fixture.runtime.run({ ...request(), signal: controller.signal })
+
+    controller.abort('stop during setup')
+    const early = await Promise.race([
+      running.then(result => ({ kind: 'result' as const, result })),
+      new Promise<{ kind: 'pending' }>((resolve) => { setImmediate(() => { resolve({ kind: 'pending' }) }) }),
+    ])
+    expect(fixture.spawn).not.toHaveBeenCalled()
+
+    gate.resolve(fixture.sandbox)
+    expect(early).toMatchObject({ kind: 'result', result: { error: { kind: 'abort', message: 'stop during setup' } } })
+    await running
     await fixture.fiber.dispose()
   })
 
+  it('classifies an abort that races synchronous subprocess spawn', async () => {
+    const fixture = await setup()
+    const controller = new AbortController()
+    fixture.spawn.mockImplementationOnce(() => {
+      controller.abort('stop at spawn')
+      throw new Error('aborted before spawn')
+    })
+
+    expect((await fixture.runtime.run({ ...request(), signal: controller.signal })).error)
+      .toEqual({ kind: 'abort', message: 'stop at spawn' })
+
+    fixture.spawn.mockImplementationOnce(() => { throw new Error('synchronous spawn failure') })
+    expect((await fixture.runtime.run(request())).error).toEqual({
+      kind: 'worker-exit',
+      message: 'E2B runtime spawn failed: synchronous spawn failure',
+    })
+    await fixture.fiber.dispose()
+
+    const disposingFixture = await setup()
+    disposingFixture.spawn.mockImplementationOnce(() => {
+      void (disposingFixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
+      throw new Error('spawn raced disposal')
+    })
+    expect((await disposingFixture.runtime.run(request())).error)
+      .toEqual({ kind: 'abort', message: 'runtime disposed' })
+    await disposingFixture.fiber.dispose()
+  })
+
+  it('closes both abort races around runtime readiness and live-run publication', async () => {
+    let preparationAborted = false
+    const preparationSignal = {
+      get aborted() { return preparationAborted },
+      reason: 'preparation race',
+      addEventListener() { preparationAborted = true },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    const liveHandle = new FakeHandle()
+    const fixture = await setup([liveHandle])
+    expect((await fixture.runtime.run({ ...request(), signal: preparationSignal })).error)
+      .toEqual({ kind: 'abort', message: 'preparation race' })
+    expect(fixture.spawn).not.toHaveBeenCalled()
+
+    let liveAborted = false
+    let registrations = 0
+    const liveSignal = {
+      get aborted() { return liveAborted },
+      reason: 'live publication race',
+      addEventListener() {
+        registrations += 1
+        if (registrations === 2) liveAborted = true
+      },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    expect((await fixture.runtime.run({ ...request(), signal: liveSignal })).error)
+      .toEqual({ kind: 'abort', message: 'live publication race' })
+    await fixture.fiber.dispose()
+  })
+
+  it('retains a live run until remote cleanup reaches quiescence', async () => {
+    const cleanup = Promise.withResolvers<boolean>()
+    const handle = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
+    }, { waitResult: cleanup.promise })
+    const fixture = await setup([handle])
+    const running = fixture.runtime.run(request())
+    await vi.waitFor(() => { expect(handle.waitCalls).toBe(1) })
+
+    const disposing = fixture.fiber.dispose()
+    let disposed = false
+    void disposing.then(() => { disposed = true })
+    await new Promise(resolve => setImmediate(resolve))
+    const disposedBeforeCleanup = disposed
+
+    cleanup.resolve(true)
+    await expect(running).resolves.toEqual({ logs: [] })
+    await expect(disposing).resolves.toBeUndefined()
+    expect(disposedBeforeCleanup).toBe(false)
+  })
+
   it('registers the package-owned invariant companion', async () => {
     const ctx = new Context()
     await ctx.plugin(InvariantService, { enabled: true })
diff --git a/packages/e2b/e2b/src/frame.ts b/packages/e2b/e2b/src/frame.ts
index 39800b4428..5b6fe536c0 100644
--- a/packages/e2b/e2b/src/frame.ts
+++ b/packages/e2b/e2b/src/frame.ts
@@ -10,9 +10,30 @@ const BASE64_LINE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3
  * @returns Base64-encoded UTF-8 JSON followed by one newline.
  */
 export function encodeE2BFrame(value: unknown): string {
+  return encodeFrame(value)
+}
+
+/**
+ * Encode one JSON-compatible value while enforcing the decoded frame bound.
+ * @param value - Value accepted by `JSON.stringify`.
+ * @param maxFrameBytes - Maximum UTF-8 JSON bytes in the encoded frame.
+ * @returns Base64-encoded UTF-8 JSON followed by one newline.
+ */
+export function encodeBoundedE2BFrame(value: unknown, maxFrameBytes: number): string {
+  if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+    throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
+  }
+  return encodeFrame(value, maxFrameBytes)
+}
+
+function encodeFrame(value: unknown, maxFrameBytes?: number): string {
   const json: unknown = JSON.stringify(value)
   if (typeof json !== 'string') throw new Error('E2B frame value is not JSON-serializable')
-  return `${Buffer.from(json).toString('base64')}\n`
+  const bytes = Buffer.from(json)
+  if (maxFrameBytes !== undefined && bytes.length > maxFrameBytes) {
+    throw new Error('E2B frame exceeded its byte limit')
+  }
+  return `${bytes.toString('base64')}\n`
 }
 
 /** Incremental decoder for newline-delimited base64 JSON frames. */
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 4c4597f6ef..11625b3b21 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -10,7 +10,7 @@ import z from 'schemastery'
 import { Sandbox } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
-export { E2BFrameDecoder, encodeE2BFrame } from './frame.ts'
+export { E2BFrameDecoder, encodeBoundedE2BFrame, encodeE2BFrame } from './frame.ts'
 
 export {
   CommandExitError,
@@ -202,7 +202,11 @@ export class E2BSandboxService extends Service {
    */
   async getSandbox(): Promise<Sandbox> {
     if (this.disposed) throw new Error('E2B sandbox service is disposing')
-    return await this.ready
+    const sandbox = await this.ready
+    // Disposal can race the awaited sandbox readiness despite the synchronous precheck.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.disposed) throw new Error('E2B sandbox service is disposing')
+    return sandbox
   }
 
   private validate(): void {
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index d056d4b851..5c9bd56fc9 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -24,7 +24,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       },
       processTimeoutMs: 120_000,
       inspect: async (cwd) => {
-        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte.ts', 'fixture-lsp.mjs']) {
+        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte # file.ts', 'fixture-lsp.mjs']) {
           await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
         }
       },
@@ -35,6 +35,12 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(output).toMatchObject({
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
+      explicitEnvironment: true,
+      spill: {
+        liveBytes: 6,
+        outcome: { exitCode: null, signal: 'SIGTERM' },
+        read: { text: '6789', nextOffset: 10, lossy: true },
+      },
       hover: {
         kind: 'hover',
         hover: { contents: '**remote hover** 你好 café' },
@@ -51,6 +57,8 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       hostileOutput: { error: { kind: 'output-limit' } },
       timedOut: { error: { kind: 'timeout' } },
       aborted: { error: { kind: 'abort', message: 'live abort' } },
+      oversizedBoot: { error: { kind: 'worker-exit' } },
+      oversizedReply: { error: { kind: 'worker-exit' } },
       lingeringCodeRunners: 0,
     })
     expect((output.terminal as { motd: string }).motd.length).toBeGreaterThan(0)
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index 541e69df9c..58d2ffbd7a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -4,6 +4,7 @@ import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   E2BFrameDecoder,
   E2BSandboxId,
+  encodeBoundedE2BFrame,
   encodeE2BFrame,
   quoteE2BShellArg,
   resolveE2BExecutable,
@@ -91,6 +92,22 @@ describe('E2BSandboxService', () => {
     await expect(service.getSandbox()).rejects.toThrow(/disposing/)
   })
 
+  it('rejects handle acquisition when disposal starts during setup', async () => {
+    const fixture = fakeSandbox()
+    const opening = Promise.withResolvers<SandboxType>()
+    sdk.create.mockReturnValue(opening.promise)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    const acquisition = ctx.e2b.getSandbox()
+    const disposing = fiber.dispose()
+    opening.resolve(fixture.sandbox)
+
+    await expect(acquisition).rejects.toThrow(/disposing/)
+    await expect(disposing).resolves.toBeUndefined()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
   it('creates from a template, honors timeout and pause policies, and reads the key from the environment', async () => {
     vi.stubEnv('E2B_API_KEY', 'environment-key')
     const fixture = fakeSandbox('template-sandbox')
@@ -240,6 +257,14 @@ describe('E2B helpers and invariant companion', () => {
     expect(() => encodeE2BFrame(undefined)).toThrow('not JSON-serializable')
   })
 
+  it('bounds outbound frames by decoded UTF-8 bytes', () => {
+    const exact = encodeBoundedE2BFrame({ text: '你' }, 14)
+    expect(new E2BFrameDecoder(14).push(exact)).toEqual([{ text: '你' }])
+    expect(() => encodeBoundedE2BFrame({ text: '你' }, 13)).toThrow('byte limit')
+    expect(() => encodeBoundedE2BFrame(null, 0)).toThrow('positive safe integer')
+    expect(() => encodeBoundedE2BFrame(null, 1.5)).toThrow('positive safe integer')
+  })
+
   it('rejects malformed, oversized, and truncated frame streams', () => {
     expect(() => new E2BFrameDecoder(0)).toThrow('positive safe integer')
     expect(() => new E2BFrameDecoder(1.5)).toThrow('positive safe integer')
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 020b0f4857..4f733f1fba 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -199,6 +199,7 @@ export class E2BFileSystem extends FileSystem {
         const reader = stream.getReader()
         const decoder = new TextDecoder('utf-8', { fatal: true })
         let sampledBytes = 0
+        let completed = false
         try {
           while (true) {
             assertNotAborted(signal, 'read')
@@ -222,9 +223,17 @@ export class E2BFileSystem extends FileSystem {
           } catch (error: unknown) {
             throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
           }
+          completed = true
         } catch (error: unknown) {
           throw mapError(error, 'read', displayPath, signal)
         } finally {
+          if (!completed) {
+            try {
+              await reader.cancel()
+            } catch (_streamCancellationFailure) {
+              // The primary read outcome owns the result; cancellation is best-effort after early stop.
+            }
+          }
           reader.releaseLock()
         }
       },
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index b8eb5447d6..177bb9e59c 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -12,7 +12,7 @@ import { FsVersion } from '@deepseek-ai/dsh-fs'
 import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
 import * as E2BFsInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 interface RemoteNode {
   type: FileType
@@ -38,6 +38,8 @@ class FakeRemote {
   readonly removals: string[] = []
   readonly commands: string[] = []
   streamChunks: Uint8Array[] | undefined
+  streamKeepOpen = false
+  readonly streamCancel = vi.fn()
   nextCommandError: unknown
   nextInfoError: unknown
   nextListError: unknown
@@ -148,10 +150,11 @@ class FakeRemote {
         if (options.format === 'bytes') return data.slice()
         const chunks = this.streamChunks ?? [data.slice()]
         return new ReadableStream<Uint8Array>({
-          start(controller) {
+          start: (controller) => {
             for (const chunk of chunks) controller.enqueue(chunk)
-            controller.close()
+            if (!this.streamKeepOpen) controller.close()
           },
+          cancel: () => { this.streamCancel() },
         })
       },
       list: async (path: string, options?: { depth?: number; signal?: AbortSignal }): Promise<EntryInfo[]> => {
@@ -303,6 +306,22 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect(initiallyBuffered).toBe('€')
   })
 
+  it('cancels a remote stream when its consumer stops early', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/text.txt', 'ab')
+    remote.streamChunks = [bytes('a'), bytes('b')]
+    remote.streamKeepOpen = true
+    const { fs } = await setup(remote)
+    const stream = await fs.streamText(await fs.resolve('text.txt'))
+
+    for await (const chunk of stream) {
+      expect(chunk).toBe('a')
+      break
+    }
+
+    expect(remote.streamCancel).toHaveBeenCalledOnce()
+  })
+
   it('matches local binary sampling while edits still reject any NUL byte', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/late-nul.txt', `${'a'.repeat(8192)}\0tail`)
diff --git a/packages/e2b/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
index eb9596db5f..b378ebfc9a 100644
--- a/packages/e2b/lsp-e2b/src/index.ts
+++ b/packages/e2b/lsp-e2b/src/index.ts
@@ -200,6 +200,16 @@ export async function readE2BSource(
   return { canonicalPath, text }
 }
 
+/**
+ * Encode one absolute remote Linux path as a host-independent file URI.
+ * @param path - Canonical POSIX path inside E2B.
+ * @returns The equivalent percent-encoded file URI.
+ */
+export function e2bFileUri(path: string): string {
+  if (!posix.isAbsolute(path)) throw new Error(`lsp-e2b: expected an absolute remote path, received ${JSON.stringify(path)}`)
+  return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
+}
+
 /* jscpd:ignore-start -- Provider identity mirrors the seam while remote source and process ownership stay local. */
 /** One pooled remote provider with an isolated server per canonical workspace. */
 export class E2BLspProvider implements LspProvider {
@@ -298,6 +308,7 @@ export class E2BLspProvider implements LspProvider {
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
       clientProcessId: null,
+      pathToFileUri: e2bFileUri,
     }, (spec: SubprocessSpawnSpec) => {
       const originalArgv = Buffer.from(JSON.stringify(spec.argv)).toString('base64')
       const inner = this.subprocess.spawn({
diff --git a/packages/e2b/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
index 0b41be12a3..d746abe7f7 100644
--- a/packages/e2b/lsp-e2b/tests/provider.spec.ts
+++ b/packages/e2b/lsp-e2b/tests/provider.spec.ts
@@ -69,6 +69,7 @@ import {
   E2BLspProvider,
   apply,
   canonicalizeE2BWorkspace,
+  e2bFileUri,
   readE2BSource,
 } from '@deepseek-ai/dsh-lsp-e2b'
 import type { LspE2BServerConfig } from '@deepseek-ai/dsh-lsp-e2b'
@@ -234,6 +235,10 @@ describe('E2BLspProvider pooling and lifecycle', () => {
     await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
     expect(mockedLsp.FakeLspInstance.instances).toHaveLength(1)
     expect(mockedLsp.FakeLspInstance.instances[0]?.spec).toMatchObject({ clientProcessId: null, cwd: '/workspace' })
+    expect(e2bFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
+    expect(() => e2bFileUri('relative.ts')).toThrow('absolute remote path')
+    const pathToFileUri = mockedLsp.FakeLspInstance.instances[0]?.spec.pathToFileUri as (path: string) => string
+    expect(pathToFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
     expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
       argv: ['/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs', expect.any(String)],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 128 } },
diff --git a/packages/e2b/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
index fca16cf5c7..8fd7a519a0 100644
--- a/packages/e2b/pty-e2b/src/index.ts
+++ b/packages/e2b/pty-e2b/src/index.ts
@@ -71,9 +71,10 @@ export class E2BPtyBackend implements PtyBackend {
     }
     const session = new E2BPtySession(sandbox, handle, this.config)
     created.session = session
-    for (const data of pending) session.onData(data)
     try {
-      await session.initialize(spec.signal)
+      const initializing = session.initialize(spec.signal)
+      for (const data of pending) session.onData(data)
+      await initializing
       return session
     } catch (error: unknown) {
       try {
diff --git a/packages/e2b/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
index 567b3b9215..e306d8b86b 100644
--- a/packages/e2b/pty-e2b/tests/index.spec.ts
+++ b/packages/e2b/pty-e2b/tests/index.spec.ts
@@ -52,7 +52,7 @@ describe('E2BPtyBackend and plugin', () => {
     const backend = new E2BPtyBackend(ctx, config(), async (_sandbox, received) => {
       options = received
       void received.onData(Buffer.from('banner\n'))
-      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
+      void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
       return created
     })
     const pending = backend.spawn({
@@ -62,7 +62,7 @@ describe('E2BPtyBackend and plugin', () => {
     await vi.advanceTimersByTimeAsync(2)
     const session = await pending
 
-    expect(session.motd).toBe('dsh> ')
+    expect(session.motd).toBe('banner\ndsh> ')
     expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
     expect(options?.envs).toMatchObject({
       TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 26bc8f0b51..8b8a70838c 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: ce61de1100791be6e5c4db74c73ff43566281ed9
-README.zh.md: a4c619f0c002cc1d36310c5a9b4a3f7ae655ad1f
+README.md: 3b3bfa88e7e6483decfcdec11355942ae4ff7403
+README.zh.md: 3ff9a51c60636dea5789f9dd11b04aa902b91d0c
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index ce61de1100..3b3bfa88e7 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -11,7 +11,7 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
 - **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
 
-The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, and `kill`. A custom template must retain compatible commands.
+The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index a4c619f0c0..3ff9a51c60 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -11,7 +11,7 @@
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
 - **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 
-基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee` 和 `kill`。自定义模板必须保留兼容的命令。
+基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 507ea700c4..86bdade589 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -55,37 +55,38 @@ class DeferredStdin extends Writable {
 interface RemotePaths {
   pid: string
   status: string
+  environment: string
   stdout: string
   stderr: string
 }
 
-function explicitEnvironmentNames(env: Readonly<Record<string, string>> | undefined): string {
-  return Object.keys(env ?? {})
-    .map(quoteE2BShellArg)
-    .join(' ')
+function explicitEnvironment(env: Readonly<Record<string, string>> | undefined): string {
+  return Object.entries(env ?? {})
+    .map(([name, value]) => `${name}=${value}\0`)
+    .join('')
 }
 
 function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   const stdoutRedirect = hasSpill(spec.stdio.stdout)
-    ? `> >(tee -a -- ${quoteE2BShellArg(paths.stdout)})`
+    ? `> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}))`
     : ''
   const stderrRedirect = hasSpill(spec.stdio.stderr)
-    ? `2> >(tee -a -- ${quoteE2BShellArg(paths.stderr)} >&2)`
+    ? `2> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) >&2)`
     : ''
-  const environmentNames = explicitEnvironmentNames(spec.env)
   const inner = [
     'set +e',
     'umask 077',
     'dsh_e2b_pgid="$(ps -o pgid= -p "$$" | tr -d " ")"',
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
+    `mapfile -d '' -t dsh_e2b_explicit < ${quoteE2BShellArg(paths.environment)}`,
+    `: > ${quoteE2BShellArg(paths.environment)}`,
     'dsh_e2b_env=()',
-    `dsh_e2b_explicit=(${environmentNames})`,
-    'while IFS= read -r dsh_e2b_name; do',
+    "while IFS= read -r -d '' dsh_e2b_entry; do",
+    '  dsh_e2b_name="${dsh_e2b_entry%%=*}"',
     '  case "${dsh_e2b_name^^}" in DSH_*|*KEY*|*SECRET*|*TOKEN*) continue ;; esac',
-    '  dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}")',
-    'done < <(compgen -e)',
-    'for dsh_e2b_name in "${dsh_e2b_explicit[@]}"; do dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}"); done',
-    `env -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    '  dsh_e2b_env+=("$dsh_e2b_entry")',
+    'done < <(env -0)',
+    `env -i "\${dsh_e2b_env[@]}" "\${dsh_e2b_explicit[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
     'wait',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
@@ -131,7 +132,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
   private remotePid = -1
-  private settled = false
   private terminationRequested = false
   private terminationSignal: NodeJS.Signals | null = null
   private termination: Promise<void> | undefined
@@ -150,6 +150,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     this.paths = {
       pid: posix.join(stateDir, 'pid'),
       status: posix.join(stateDir, 'exit-code'),
+      environment: posix.join(stateDir, 'environment'),
       stdout: posix.join(stateDir, 'stdout.log'),
       stderr: posix.join(stateDir, 'stderr.log'),
     }
@@ -182,7 +183,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationRequested || this.settled) return
+    if (this.terminationRequested) return
     this.terminationRequested = true
     this.termination = this.terminateRemote()
     void this.termination.catch(() => {})
@@ -240,7 +241,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           cwd: this.spec.cwd,
           stdin: this.spec.stdio.stdin !== 'ignore',
           timeoutMs: 0,
-          ...(this.spec.env !== undefined ? { envs: this.spec.env } : {}),
           onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
           onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
         },
@@ -250,7 +250,12 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       const completion = handle.wait()
       void completion.catch(() => {})
-      this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      try {
+        this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      } catch (error: unknown) {
+        await Promise.allSettled([handle.kill()])
+        throw error
+      }
       this.readyState.resolve(handle)
       await this.writeBatchStdin(handle)
       const outcome = await this.waitForCommand(completion)
@@ -260,7 +265,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       this.readyState.reject(error)
       throw error
     } finally {
-      this.settled = true
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
       this.stderr?.end()
@@ -269,17 +273,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
     await sandbox.files.makeDir(this.stateDir)
+    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
+      { path: this.paths.environment, data: explicitEnvironment(this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
     await sandbox.files.write(files)
-    await sandbox.commands.run([
-      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
-      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
-    ].join('\n'))
+    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`)
   }
 
   private async writeBatchStdin(handle: CommandHandle): Promise<void> {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index ff9d48073c..6be645a713 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -80,6 +80,7 @@ class FakeSandbox {
   readonly handle = new FakeCommandHandle()
   readonly commandsSeen: string[] = []
   readonly writtenFiles: string[][] = []
+  readonly writtenFileData = new Map<string, string>()
   readonly removed: string[] = []
   readonly directories: string[] = []
   startOptions: StartOptions | undefined
@@ -129,6 +130,7 @@ class FakeSandbox {
       },
       write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
         this.writtenFiles.push(files.map(file => file.path))
+        for (const file of files) this.writtenFileData.set(file.path, file.data)
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => this.processGroupReads.shift() ?? this.processGroupId,
@@ -251,7 +253,7 @@ describe('E2BSubprocessHandle', () => {
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
       argv: ['tool', 'argument with spaces'],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
-      env: { PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
+      env: { PATH: '/bin', 'FOO-BAR': 'hyphen-value', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
     }), '/workspace/.dsh-e2b/processes/one')
     expect(handle.pid).toBe(-1)
     handle.stdin!.write('hello')
@@ -261,17 +263,26 @@ describe('E2BSubprocessHandle', () => {
     expect(handle.pid).toBe(4343)
     expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
     expect(fake.handle.closes).toBe(1)
-    expect(fake.startOptions?.envs).toEqual({ PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' })
+    expect(fake.startOptions?.envs).toBeUndefined()
     const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
     expect(command).toContain('exec setsid --wait -- bash -c')
-    expect(command).toContain('DEEPSEEK_API_KEY')
-    expect(command).toContain('DSH_MODE')
+    expect(command).not.toContain('DEEPSEEK_API_KEY')
+    expect(command).not.toContain('DSH_MODE')
+    expect(command).not.toContain('FOO-BAR')
     expect(command).not.toContain('explicit-secret')
+    expect(command).not.toContain('hyphen-value')
+    expect(command).not.toContain('${!dsh_e2b_name}')
+    expect(command).toContain('env -0')
+    expect(command).toContain('mapfile -d')
     expect(fake.writtenFiles[0]).toEqual([
       '/workspace/.dsh-e2b/processes/one/pid',
       '/workspace/.dsh-e2b/processes/one/exit-code',
+      '/workspace/.dsh-e2b/processes/one/environment',
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
+    expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
+      'PATH=/bin\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+    )
 
     let piped = ''
     handle.stdout!.on('data', (chunk) => { piped += String(chunk) })
@@ -350,6 +361,11 @@ describe('E2BSubprocessHandle', () => {
     await handle.done
     expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     expect(fake.removed).toContain('/runtime/oversize/stdout.log')
+    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
+    expect(command).toContain('head -c 3')
+    expect(command).toContain('/runtime/oversize/stdout.log')
+    expect(command).toContain('tee --output-error=warn-nopipe')
+    expect(command).not.toContain('tee -a')
   })
 
   it('contains remote spill-removal failures and routes empty inherited output', async () => {
@@ -415,6 +431,22 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('can terminate a surviving process group after the command leader settles', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/surviving-group')
+    await flush()
+    fake.handle.succeed(0)
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.alive).toBe(true)
+
+    handle.terminate()
+    await flush()
+    const signaled = fake.commandsSeen.includes('kill -TERM -- -4242')
+    if (!signaled) fake.finish()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(signaled).toBe(true)
+  })
+
   it('bounds waitForExit while startup or a live group is pending', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
@@ -564,8 +596,14 @@ describe('E2BSubprocessHandle', () => {
   it('rejects invalid or absent process-group publication', async () => {
     const invalidGroup = new FakeSandbox()
     invalidGroup.processGroupId = 'not-a-pid\n'
+    vi.spyOn(invalidGroup.handle, 'kill').mockImplementation(async () => {
+      invalidGroup.handle.kills += 1
+      invalidGroup.finish()
+      return true
+    })
     const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
+    expect(invalidGroup.handle.kills).toBe(1)
 
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
@@ -573,6 +611,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
     absentGroup.finish()
     await expect(absent.done).rejects.toThrow(/exited before publishing/)
+    expect(absentGroup.handle.kills).toBe(1)
   })
 
   it('waits for delayed process-group publication', async () => {
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index fc7e50787f..3a2baa0c55 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -1,16 +1,19 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace target, serves transient-open queries
+ * single-flights one server process per canonical workspace realpath, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through `ctx.fs` and launch servers through
- * `ctx.subprocess`, so both local and remote implementations share one host.
+ * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
+ * and trust their configured servers — no sandbox confinement.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
+import { accessSync, constants, statSync } from 'node:fs'
+import { delimiter, isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -22,9 +25,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
-import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
+import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -44,7 +47,10 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['fs', 'lsp', 'subprocess']
+export const inject = ['lsp', 'subprocess']
+
+/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
+
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -86,7 +92,6 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
-type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -106,67 +111,27 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
-/** Propagate teardown failures only after every sibling has settled. */
-function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
-  const failures: unknown[] = []
-  for (const result of results) {
-    if (result.status === 'rejected') failures.push(result.reason)
-  }
-  if (failures.length === 1) throw failures[0]
-  if (failures.length > 1) throw new AggregateError(failures, message)
-}
-
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
+ * @param ctx - the plugin context (must inject `lsp`).
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export async function apply(ctx: Context, config: Config): Promise<void> {
+export function apply(ctx: Context, config: Config): void {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
-  const setupAbort = new AbortController()
-  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
-    // An async plugin callback must observe its own disposal before Cordis can
-    // run effect cleanup, because unload otherwise waits for this callback.
-    if (fiber === ctx.fiber && fiber.uid === null) {
-      setupAbort.abort(new Error('lsp-local setup disposed'))
-    }
-  })
-
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = await (async () => {
-    const lookups = entries.map(async ([providerId, rawConfig]) => {
-      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-      const resolved = rawConfig as ResolvedServerConfig
-      validateServerConfig(providerId, resolved)
-      const executable = await ctx.subprocess.resolveExecutable(
-        resolved.command,
-        resolved.env,
-        setupAbort.signal,
-      )
-      setupAbort.signal.throwIfAborted()
-      return new LocalLspProvider(
-        providerId,
-        ctx.fs,
-        resolved,
-        executable,
-        spec => ctx.subprocess.spawn(spec),
-      )
-    })
-    try {
-      return await Promise.all(lookups)
-    } catch (error: unknown) {
-      setupAbort.abort(error)
-      await Promise.allSettled(lookups)
-      throw error
-    } finally {
-      stopSetupCancellation()
-    }
-  })()
+  const providers = entries.map(([providerId, rawConfig]) => {
+    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+    const resolved = rawConfig as ResolvedServerConfig
+    validateServerConfig(providerId, resolved)
+    const childEnv = buildChildEnv(resolved.env)
+    const executable = resolveExecutable(resolved.command, childEnv)
+    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
+  })
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -179,8 +144,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
-      throwTeardownFailures(results, 'lsp-local provider teardown failed')
+      await Promise.all(providers.map(provider => provider.disposeAll()))
     }
   }, 'lsp-local.registerProviders')
 }
@@ -217,19 +181,16 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per stable canonical workspace identity. */
-  private readonly instances = new Map<WorkspaceKey, LspInstance>()
+  /** One live instance per canonical workspace realpath. */
+  private readonly instances = new Map<string, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
-  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
-  private readonly workspaceLookups = new Set<Promise<void>>()
-  private readonly lifetime = new AbortController()
+  private readonly queues = new Map<string, Promise<void>>()
   private disposed = false
 
   constructor(
     providerId: string,
-    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
+    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -250,60 +211,43 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
-  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
-  private querySignal(signal?: AbortSignal): AbortSignal {
-    return signal === undefined
-      ? this.lifetime.signal
-      : AbortSignal.any([signal, this.lifetime.signal])
-  }
-
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const querySignal = this.querySignal(signal)
-    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
-    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
-    this.workspaceLookups.add(workspaceLookup)
-    let workspace: HostWorkspace
-    try {
-      workspace = await workspaceResult
-    } finally {
-      this.workspaceLookups.delete(workspaceLookup)
-    }
-    this.assertActive(querySignal)
-    const workspaceKey = workspace.target.targetKey
-    return this.enqueue(workspaceKey, querySignal, async () => {
-      this.assertActive(querySignal)
+    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
+    this.assertActive(signal)
+    return this.enqueue(workspace, signal, async () => {
+      this.assertActive(signal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
+      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(querySignal)
-      let instance = this.instanceFor(workspaceKey, workspace)
+      this.assertActive(signal)
+      let instance = this.instanceFor(workspace)
       try {
-        return await instance.query(request, source, querySignal)
+        return await instance.query(request, source, signal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspaceKey, instance)
-        this.assertActive(querySignal)
-        instance = this.instanceFor(workspaceKey, workspace)
-        return await instance.query(request, source, querySignal)
+        this.evictIfCurrent(workspace, instance)
+        this.assertActive(signal)
+        instance = this.instanceFor(workspace)
+        return await instance.query(request, source, signal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspaceKey, instance)
+          this.evictIfCurrent(workspace, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -317,34 +261,34 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
+  private instanceFor(workspace: string): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspaceKey)
+    const existing = this.instances.get(workspace)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspaceKey, created)
+    this.instances.set(workspace, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
+  private evictIfCurrent(workspace: string, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: HostWorkspace): LspInstance {
+  private createInstance(workspace: string): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace.canonicalPath,
-      workspaceUri: workspace.fileUrl,
-      env: this.config.env,
+      cwd: workspace,
+      env: this.childEnv,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
       maxStderrBytes: this.config.maxStderrBytes,
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
+      pathToFileUri: path => pathToFileURL(path).href,
     }
     return new LspInstance(spec, this.spawner)
   }
@@ -352,18 +296,51 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
-    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
-    const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    const results = await Promise.allSettled([
+    await Promise.all([
       ...live.map(instance => instance.dispose()),
       ...draining,
-      ...resolving,
     ])
     this.queues.clear()
-    this.workspaceLookups.clear()
-    throwTeardownFailures(results, 'lsp-local instance teardown failed')
+  }
+}
+
+/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  return { ...scrubbedParentEnv(), ...extra }
+}
+
+/**
+ * Resolve the server executable to an absolute path: an absolute command is verified directly; a
+ * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
+ */
+function resolveExecutable(command: string, childEnv: Record<string, string>): string {
+  if (isAbsolute(command)) {
+    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
+    if (!isExecutableFileSync(command)) {
+      throw new Error(`lsp-local: command "${command}" is not an executable file`)
+    }
+    return command
+  }
+  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
+  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
+  for (const dir of pathValue.split(delimiter)) {
+    if (dir === '') continue
+    const candidate = join(dir, command)
+    if (isExecutableFileSync(candidate)) return candidate
+  }
+  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
+}
+
+/** Synchronous regular-file and executable check used only at load-time resolution. */
+function isExecutableFileSync(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
   }
 }
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index d643db1528..5a12192c62 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -7,7 +7,6 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
-import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -37,6 +36,12 @@ export interface InstanceSpec extends ConnectionSpec {
   readonly shutdownTimeoutMs: number
   /** PID advertised to the server; `null` when client and server do not share a process namespace. */
   readonly clientProcessId?: number | null
+  /**
+   * Encode one implementation-native absolute path as a file URI.
+   * @param path - Canonical workspace or source path.
+   * @returns A file URI interpreted in the server's filesystem namespace.
+   */
+  readonly pathToFileUri: (path: string) => string
 }
 
 /**
@@ -111,8 +116,8 @@ export class LspInstance {
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
       processId: this.spec.clientProcessId === undefined ? process.pid : this.spec.clientProcessId,
-      rootUri: pathToFileURL(this.spec.cwd).href,
-      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
+      rootUri: this.spec.pathToFileUri(this.spec.cwd),
+      workspaceFolders: [{ uri: this.spec.pathToFileUri(this.spec.cwd), name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -149,7 +154,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = pathToFileURL(source.canonicalPath).href
+    const uri = this.spec.pathToFileUri(source.canonicalPath)
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 939b58f0b1..fc1d05843c 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -56,6 +56,7 @@ function makeInstance(
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 200,
     killGraceMs: 200,
+    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess, writer)
   live.push(instance)
@@ -91,6 +92,7 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 150,
     killGraceMs: 150,
+    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess)
   live.push(instance)

From bccad1bb31d21a0290cdcbab23584c86feba80b1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:30:28 +0800
Subject: [PATCH 103/262] fix(e2b): normalize setup rejection reasons

---
 packages/e2b/code-runtime-e2b/src/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
index a567a2bb6d..b6245244ba 100644
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ b/packages/e2b/code-runtime-e2b/src/index.ts
@@ -213,7 +213,7 @@ export class E2BCodeRuntime extends CodeRuntime {
         (runtime) => { cleanup(); resolve(runtime) },
         (error: unknown) => {
           cleanup()
-          reject(error instanceof Error ? error : new Error(String(error)))
+          reject(new Error(messageOf(error), { cause: error }))
         },
       )
     })

From dc44f93c39d284d378bc687769a0616758a13f82 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:54:29 +0800
Subject: [PATCH 104/262] fix(e2b): simplify setup abort wait

---
 packages/e2b/code-runtime-e2b/src/index.ts | 32 ++++++++++------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
index b6245244ba..c37cb3cc64 100644
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ b/packages/e2b/code-runtime-e2b/src/index.ts
@@ -199,24 +199,20 @@ export class E2BCodeRuntime extends CodeRuntime {
   }
   /* jscpd:ignore-end */
 
-  private awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
-    if (signal === undefined) return this.ready
-    return new Promise<PreparedRuntime | undefined>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(undefined) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      if (signal.aborted) {
-        onAbort()
-        return
-      }
-      void this.ready.then(
-        (runtime) => { cleanup(); resolve(runtime) },
-        (error: unknown) => {
-          cleanup()
-          reject(new Error(messageOf(error), { cause: error }))
-        },
-      )
-    })
+  private async awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
+    if (signal === undefined) return await this.ready
+    const aborted = Promise.withResolvers<undefined>()
+    const onAbort = (): void => { aborted.resolve(undefined) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) {
+      signal.removeEventListener('abort', onAbort)
+      return undefined
+    }
+    try {
+      return await Promise.race([this.ready, aborted.promise])
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+    }
   }
 
   private assertPreparationActive(): void {

From 3e343b44778633350f02420c11cc45ea0168e91e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 18:31:37 +0800
Subject: [PATCH 105/262] fix(e2b): harden remote adapter boundaries

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |  12 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  12 +-
 .../tests/fixtures/e2b/e2b/bin.ts             | 128 ++++++++++-
 .../tests/fixtures/e2b/e2b/cordis.yml         |   2 +-
 .../e2b/code-runtime-e2b/README.i18n.yaml     |   4 +-
 packages/e2b/code-runtime-e2b/README.md       |   2 +-
 packages/e2b/code-runtime-e2b/README.zh.md    |   2 +-
 .../e2b/code-runtime-e2b/src/runner-source.ts | 212 ++++++++++++++++--
 .../code-runtime-e2b/tests/runtime.spec.ts    | 117 ++++++++++
 packages/e2b/e2b/tests/composition.e2e.ts     |  64 +++++-
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   2 +-
 packages/e2b/fs-e2b/README.zh.md              |   2 +-
 packages/e2b/fs-e2b/src/index.ts              |   6 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |  11 +
 packages/e2b/lsp-e2b/README.i18n.yaml         |   4 +-
 packages/e2b/lsp-e2b/README.md                |   2 +-
 packages/e2b/lsp-e2b/README.zh.md             |   2 +-
 packages/e2b/lsp-e2b/src/index.ts             |  90 +++++++-
 packages/e2b/lsp-e2b/tests/provider.spec.ts   |  44 ++--
 packages/e2b/pty-e2b/README.i18n.yaml         |   4 +-
 packages/e2b/pty-e2b/README.md                |   5 +-
 packages/e2b/pty-e2b/README.zh.md             |   5 +-
 packages/e2b/pty-e2b/src/index.ts             |  42 +++-
 packages/e2b/pty-e2b/src/session.ts           |  56 ++++-
 packages/e2b/pty-e2b/tests/index.spec.ts      |  63 +++++-
 packages/e2b/pty-e2b/tests/session.spec.ts    | 109 ++++++---
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   4 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  22 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   |  41 +++-
 33 files changed, 939 insertions(+), 146 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 5ed4e445b8..beb49fba76 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: a713cca3fd9e7ee11a2c487bf6ed2c3a205dc502
-2026-07-27-e2b-remote-runtime-poc.zh.md: 7afd54f72622d51a3d71719b3b4975ccd7f83e3a
+2026-07-27-e2b-remote-runtime-poc.md: efb91fc166f36dc8fb047d686e8cd82d93b9af6a
+2026-07-27-e2b-remote-runtime-poc.zh.md: eb14cccc284d38cdc5cc704512b6899621a9a840
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index a713cca3fd..efb91fc166 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -18,7 +18,7 @@ The E2B integration is an opt-in provider-composition POC. Its six E2B-specific
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
 - `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
 - `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` while the existing registry retains exact-Agent ownership.
-- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
+- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through a bounded no-follow helper in E2B, and runs servers through `dsh-subprocess-e2b`.
 - `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
 - The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
 
@@ -28,11 +28,11 @@ The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without cha
 
 ## POC boundary
 
-E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
+E2B owns the mutable filesystem, command and Bash processes, PTY shell and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP installs a bounded remote source reader, while Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -40,9 +40,9 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 ## Verification
 
-Focused package suites pin owner lifecycle cleanup, filesystem semantics, subprocess process groups, configuration and publication rollback, byte framing and multibyte boundaries, PTY readiness/signals, LSP transport and source containment, Code Runtime bindings, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signals/default-environment scrubbing/terminal-session cleanup, stable bounded LSP source reads, Code Runtime binding and descriptor isolation, worker-pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
 
-A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing and process-tree cleanup, stable bounded LSP source reads, Code Runtime host bindings and descriptor-isolated output accounting, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
@@ -66,4 +66,4 @@ A credential-gated Loader composition creates one real E2B sandbox and exercises
 
 The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or PTY session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 7afd54f726..eb14cccc28 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -18,7 +18,7 @@ E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
 - `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
 - `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
-- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
+- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B 内有界且不跟随链接的辅助程序读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
 - `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
 - 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
 
@@ -28,11 +28,11 @@ E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专
 
 ## POC 边界
 
-E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
+E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 会安装一个有界的远程源码读取器；Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -40,9 +40,9 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程
 
 ## 验证
 
-聚焦包测试套件固定所有者生命周期清理、文件系统语义、进程管理的进程组、配置与发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号／默认环境清理／终端会话清理、稳定且有界的 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
 
-凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理与进程树清理、稳定且有界的 LSP 源码读取、Code Runtime 宿主绑定与描述符隔离的输出记账、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
@@ -66,4 +66,4 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程
 
 这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离已捕获远程进程组的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或 PTY 会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 89b09a6818..4f2401d2c7 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -5,7 +5,7 @@ import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-code-runtime-e2b'
-import type {} from '@deepseek-ai/dsh-e2b'
+import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
 import type {} from '@deepseek-ai/dsh-lsp-e2b'
@@ -34,6 +34,7 @@ const owner: Agent = {
 const unregisterOwner = ctx.agents.register(owner)
 let terminalId: Awaited<ReturnType<typeof ctx.pty.spawn>>['sessionId'] | undefined
 try {
+  const sandbox = await ctx.e2b.getSandbox()
   const fromFs = await ctx.fs.resolve('from-fs.txt')
   await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
   const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
@@ -72,6 +73,38 @@ try {
   ].every(entry => environmentLines.has(entry))
   if (!explicitEnvironment) throw new Error(`E2B subprocess dropped an explicit environment entry: ${environmentText}`)
 
+  const remoteFiles = sandbox.files as unknown as {
+    read(path: string, options?: unknown): Promise<unknown>
+  }
+  const readRemoteFile = remoteFiles.read.bind(sandbox.files)
+  let publicationFaultInjected = false
+  remoteFiles.read = async (path, options) => {
+    if (!publicationFaultInjected && path.includes('/processes/') && path.endsWith('/pid')) {
+      publicationFaultInjected = true
+      throw new Error('injected process-group publication read failure')
+    }
+    return await readRemoteFile(path, options)
+  }
+  let publicationRollback = false
+  try {
+    const unpublished = ctx.subprocess.spawn({
+      argv: ['bash', '-c', 'exec -a dsh-publication-survivor sleep 30 & wait'],
+      cwd: process.cwd(),
+      stdio: { stdin: 'ignore', stdout: { maxBytes: 4_096 }, stderr: { maxBytes: 4_096 } },
+      graceMs: 500,
+      env: {},
+    })
+    await unpublished.done
+    throw new Error('E2B subprocess unexpectedly survived an injected publication failure')
+  } catch (error: unknown) {
+    if (!String(error).includes('injected process-group publication read failure')) throw error
+    const processes = await sandbox.commands.run('ps -eo args=')
+    publicationRollback = publicationFaultInjected && !processes.stdout.includes('dsh-publication-survivor')
+    if (!publicationRollback) throw new Error('E2B subprocess publication rollback left its remote process group alive')
+  } finally {
+    remoteFiles.read = readRemoteFile
+  }
+
   const spillHandle = ctx.subprocess.spawn({
     argv: ['bash', '-c', "printf '0123456789'; sleep 30"],
     cwd: process.cwd(),
@@ -81,7 +114,7 @@ try {
   })
   const spillReader = spillHandle.collected.stdout
   if (spillReader === undefined) throw new Error('E2B subprocess omitted its configured stdout collector')
-  const spillDeadline = Date.now() + 5_000
+  const spillDeadline = Date.now() + 15_000
   while (spillReader.readFrom(0).nextOffset < 10) {
     if (Date.now() >= spillDeadline) throw new Error('E2B subprocess did not stream the spill probe output')
     await new Promise(resolveDelay => setTimeout(resolveDelay, 20))
@@ -114,6 +147,53 @@ try {
     workspaceRoot: process.cwd(),
   })
 
+  const swappedSource = await ctx.fs.resolve('swapped-source.ts')
+  const swappedSourcePath = posix.join(process.cwd(), 'swapped-source.ts')
+  await ctx.fs.writeText(swappedSource, 'const safe = true\n', { kind: 'createIfAbsent' })
+  const remoteCommands = sandbox.commands as unknown as {
+    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
+  }
+  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
+  let containmentFaultInjected = false
+  remoteCommands.run = async (command, options) => {
+    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-source.ts')) {
+      containmentFaultInjected = true
+      await runRemoteCommand(`rm -f -- ${quoteE2BShellArg(swappedSourcePath)} && ln -s -- /etc/hosts ${quoteE2BShellArg(swappedSourcePath)}`)
+    }
+    return await runRemoteCommand(command, options)
+  }
+  let lspContainment = false
+  try {
+    await ctx.lsp.query({
+      operation: 'hover',
+      filePath: 'swapped-source.ts',
+      position: { line: 0, character: 1 },
+      workspaceRoot: process.cwd(),
+    })
+  } catch (error: unknown) {
+    lspContainment = containmentFaultInjected && String(error).includes('opened safely')
+    if (!lspContainment) throw error
+  } finally {
+    remoteCommands.run = runRemoteCommand
+  }
+  if (!lspContainment) throw new Error('E2B LSP source swap was not rejected')
+
+  const oversizedSourcePath = posix.join(process.cwd(), 'oversized-source.ts')
+  await sandbox.commands.run(`head -c 4000001 /dev/zero > ${quoteE2BShellArg(oversizedSourcePath)}`)
+  let lspDocumentBound = false
+  try {
+    await ctx.lsp.query({
+      operation: 'hover',
+      filePath: 'oversized-source.ts',
+      position: { line: 0, character: 0 },
+      workspaceRoot: process.cwd(),
+    })
+  } catch (error: unknown) {
+    lspDocumentBound = String(error).includes('over the 4000000-byte limit')
+    if (!lspDocumentBound) throw error
+  }
+  if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
+
   const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
   terminalId = terminal.sessionId
   const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -124,9 +204,19 @@ try {
   await new Promise(resolveDelay => setTimeout(resolveDelay, 150))
   const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
   const interrupted = await sleeping.done
+  const stubborn = await ctx.pty.startSend(owner, terminal.sessionId, {
+    text: "bash -c 'trap \"\" TERM; exec sleep 30' & printf 'DSH_STUBBORN_PID=%s\\n' \"$!\"",
+    submit: true,
+  }).done
+  const stubbornMatch = /DSH_STUBBORN_PID=([1-9][0-9]*)/.exec(stubborn.viewport)
+  if (stubbornMatch?.[1] === undefined) throw new Error(`E2B PTY did not report its stubborn child: ${stubborn.viewport}`)
+  const stubbornPid = Number(stubbornMatch[1])
   const terminalScrollback = ctx.pty.read(owner, terminal.sessionId, { count: 50 })
   await ctx.pty.kill(owner, terminal.sessionId, 'live E2B composition complete')
   terminalId = undefined
+  const stubbornProbe = await sandbox.commands.run(`if kill -0 ${stubbornPid} 2>/dev/null; then printf alive; else printf gone; fi`)
+  const terminalTreeCleanup = stubbornProbe.stdout === 'gone'
+  if (!terminalTreeCleanup) throw new Error(`E2B PTY left process ${stubbornPid} alive after close`)
 
   const code = await ctx.codeRuntime.run({
     program: `
@@ -179,6 +269,33 @@ try {
     `,
     bindings: [],
   })
+  const nativeOutput = await ctx.codeRuntime.run({
+    program: `
+      let stdoutPrototype = Object.getPrototypeOf(process.stdout)
+      while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
+      Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(8192)])
+      return true
+    `,
+    bindings: [],
+  })
+  const descriptorOutput = await ctx.codeRuntime.run({
+    program: `
+      const fs = await import('node:fs')
+      const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
+      fs.writeSync(1, forged)
+      fs.writeSync(1, 'x'.repeat(8192))
+      return true
+    `,
+    bindings: [],
+  })
+  const inheritedOutput = await ctx.codeRuntime.run({
+    program: `
+      const childProcess = await import('node:child_process')
+      childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("x".repeat(8192))'], { stdio: 'inherit' })
+      return true
+    `,
+    bindings: [],
+  })
   const timedOut = await ctx.codeRuntime.run({
     program: 'await new Promise(() => {})',
     bindings: [],
@@ -212,18 +329,25 @@ try {
     bashRead: bashRead.stdout.text,
     fsRead,
     explicitEnvironment,
+    publicationRollback,
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
+    lspContainment,
+    lspDocumentBound,
     terminal: {
       motd: terminal.motd,
       echo: terminalEcho,
       signal: terminalSignal,
       interrupted,
+      treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
     code,
     hostileOutput,
+    nativeOutput,
+    descriptorOutput,
+    inheritedOutput,
     timedOut,
     aborted,
     oversizedBoot,
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 6b3350e49c..65bd3d5246 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -2,7 +2,7 @@
   name: '@deepseek-ai/dsh-e2b'
   config:
     cwd: !!js process.cwd()
-    timeoutMs: 120000
+    timeoutMs: 180000
     onTimeout: kill
     onDispose: kill
 
diff --git a/packages/e2b/code-runtime-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
index 9eb2633b86..ba43d787b8 100644
--- a/packages/e2b/code-runtime-e2b/README.i18n.yaml
+++ b/packages/e2b/code-runtime-e2b/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/e2b/code-runtime-e2b/README.md
-README.md: 1007800c59725d116197a52f6d087ea5e2860686
-README.zh.md: a56026bce760879079627dd63a80dfe95c4d2049
+README.md: 171e63a8c1ca70deb63e9860f5088b83401a37d0
+README.zh.md: b70984e765d32985436c15dd543263cc06a25715
diff --git a/packages/e2b/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
index 1007800c59..171e63a8c1 100644
--- a/packages/e2b/code-runtime-e2b/README.md
+++ b/packages/e2b/code-runtime-e2b/README.md
@@ -19,7 +19,7 @@ Every value is a positive safe integer. `maxOutputBytes` is at least four bytes,
 
 ## Execution and bridge contract
 
-Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner creates a fresh worker thread with an empty environment and heap limit, measures active event-loop time, and destroys that worker after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
+Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; worker and controller pipes drain before the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
 
 The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
 
diff --git a/packages/e2b/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
index a56026bce7..b70984e765 100644
--- a/packages/e2b/code-runtime-e2b/README.zh.md
+++ b/packages/e2b/code-runtime-e2b/README.zh.md
@@ -19,7 +19,7 @@
 
 ## 执行与桥接契约
 
-设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会创建一个具有空环境与堆上限的全新 worker 线程，测量事件循环活跃时间，并在一次运行结算后销毁该 worker。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
+设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；worker 与 controller 管道会在发出终结帧前排空。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
 
 由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
 
diff --git a/packages/e2b/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
index b0355f20ce..e5cf6ebefa 100644
--- a/packages/e2b/code-runtime-e2b/src/runner-source.ts
+++ b/packages/e2b/code-runtime-e2b/src/runner-source.ts
@@ -2,9 +2,11 @@
 
 /** Node program that runs one model program in a fresh remote worker thread. */
 export const CODE_RUNNER_SOURCE = String.raw`import { Buffer } from 'node:buffer'
+import { fork } from 'node:child_process'
 import { inspect } from 'node:util'
 import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
 import { createInterface } from 'node:readline'
+import { fileURLToPath } from 'node:url'
 
 const emitFrame = message => {
   process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
@@ -12,23 +14,140 @@ const emitFrame = message => {
 
 const parseFrame = line => JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
 
-if (isMainThread) {
+const waitForPipeDrain = stream => {
+  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
+  return new Promise(resolve => {
+    const done = () => {
+      stream.off('end', done)
+      stream.off('close', done)
+      stream.off('error', done)
+      resolve()
+    }
+    stream.once('end', done)
+    stream.once('close', done)
+    stream.once('error', done)
+    if (stream.readableEnded || stream.destroyed) done()
+  })
+}
+
+const waitForChildExit = child => {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise(resolve => { child.once('exit', resolve) })
+}
+
+const jsonStringBytes = text => Buffer.byteLength(JSON.stringify(text))
+
+const truncateLog = (text, available) => {
+  if (available < 2) return ''
+  let result = ''
+  let bytes = 2
+  for (const character of text) {
+    const cost = jsonStringBytes(character) - 2
+    if (bytes + cost > available) break
+    bytes += cost
+    result += character
+  }
+  return result
+}
+
+const runLauncher = () => {
   const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  let worker
-  let finished = false
-  let computeTimer
+  let controller
+  let maxOutputBytes = 0
+  let logBytes = 2
+  let logEntries = 0
+  let settling = false
+  let closed = false
+  let terminal
+
   const finish = message => {
-    if (finished) return
-    finished = true
-    clearInterval(computeTimer)
-    emitFrame(message)
-    const current = worker
-    worker = undefined
-    Promise.resolve(current ? current.terminate() : undefined).finally(() => {
+    if (settling) {
+      if (message.type === 'output-limit') terminal = message
+      return
+    }
+    settling = true
+    terminal = message
+    const current = controller
+    controller = undefined
+    const drain = current
+      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
+          const stdoutDrained = waitForPipeDrain(current.stdout)
+          const stderrDrained = waitForPipeDrain(current.stderr)
+          const exited = waitForChildExit(current)
+          current.kill('SIGKILL')
+          await Promise.all([exited, stdoutDrained, stderrDrained])
+        })
+      : Promise.resolve()
+    void drain.catch(error => {
+      process.stderr.write('code-runtime-e2b controller cleanup error: ' + String(error) + '\n')
+    }).then(() => {
+      closed = true
+      emitFrame(terminal)
       input.close()
       process.stdin.destroy()
     })
   }
+
+  const forwardLog = text => {
+    if (closed || terminal?.type === 'output-limit') return
+    const separator = logEntries > 0 ? 1 : 0
+    const available = maxOutputBytes - logBytes - separator
+    const cost = jsonStringBytes(text)
+    if (cost > available) {
+      const prefix = truncateLog(text, available)
+      if (prefix) {
+        logBytes += jsonStringBytes(prefix) + separator
+        logEntries += 1
+        emitFrame({ type: 'log', text: prefix })
+      }
+      finish({ type: 'output-limit' })
+      return
+    }
+    logBytes += cost + separator
+    logEntries += 1
+    emitFrame({ type: 'log', text })
+  }
+
+  const startController = message => {
+    maxOutputBytes = message.maxOutputBytes
+    controller = fork(fileURLToPath(import.meta.url), [], {
+      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
+      execArgv: [],
+      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    })
+    const current = controller
+    current.stdout.on('data', data => { forwardLog(data.toString('utf8')) })
+    current.stderr.on('data', data => { forwardLog(data.toString('utf8')) })
+    current.on('message', raw => {
+      if (!raw || typeof raw !== 'object') return
+      if (raw.type === 'log' && typeof raw.text === 'string') {
+        forwardLog(raw.text)
+        return
+      }
+      if (settling) return
+      if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
+        emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
+      } else if (raw.type === 'output-limit') {
+        finish({ type: 'output-limit' })
+      } else if (raw.type === 'done') {
+        if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
+          finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
+        } else if (raw.value === undefined || Array.isArray(raw.value)) {
+          finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
+        }
+      }
+    })
+    current.on('error', error => {
+      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller error: ' + error.message } })
+    })
+    current.on('exit', code => {
+      if (!settling) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller exited with code ' + code + ' before completing' } })
+    })
+    current.send(message, error => {
+      if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller boot failed: ' + error.message } })
+    })
+  }
+
   input.on('line', line => {
     let message
     try {
@@ -38,26 +157,77 @@ if (isMainThread) {
       finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
       return
     }
+    if (!controller) {
+      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces) || !Number.isSafeInteger(message.maxOutputBytes) || message.maxOutputBytes < 4) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        return
+      }
+      startController(message)
+      return
+    }
+    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
+      controller.send(message.ok
+        ? { type: 'reply', id: message.id, ok: true, value: message.value }
+        : { type: 'reply', id: message.id, ok: false, message: String(message.message) }, error => {
+          if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller reply failed: ' + error.message } })
+        })
+    }
+  })
+  input.on('close', () => { if (controller && !settling) controller.kill('SIGKILL') })
+}
+
+const runController = () => {
+  let worker
+  let finished = false
+  let computeTimer
+  const send = message => {
+    if (process.send) process.send(message)
+  }
+  const finish = message => {
+    if (finished) return
+    finished = true
+    clearInterval(computeTimer)
+    const current = worker
+    worker = undefined
+    const drain = current
+      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
+          const stdoutDrained = waitForPipeDrain(current.stdout)
+          const stderrDrained = waitForPipeDrain(current.stderr)
+          await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
+        })
+      : Promise.resolve()
+    void drain.catch(error => {
+      send({ type: 'log', text: 'code-runtime-e2b worker cleanup error: ' + String(error) + '\n' })
+    }).then(() => {
+      if (!process.send) {
+        process.exitCode = 1
+        return
+      }
+      process.send(message, () => { if (process.connected) process.disconnect() })
+    })
+  }
+  process.on('message', message => {
     if (!worker) {
       if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces)) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
         return
       }
       worker = new Worker(new URL(import.meta.url), {
         workerData: message,
         env: {},
+        execArgv: [],
         stdout: true,
         stderr: true,
         resourceLimits: { maxOldGenerationSizeMb: message.maxOldGenerationSizeMb },
       })
-      worker.stdout.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
-      worker.stderr.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
+      worker.stdout.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
+      worker.stderr.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
       worker.on('message', raw => {
         if (!raw || typeof raw !== 'object') return
         if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
-          emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
+          send({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
         } else if (raw.type === 'log' && typeof raw.text === 'string') {
-          emitFrame({ type: 'log', text: raw.text })
+          send({ type: 'log', text: raw.text })
         } else if (raw.type === 'output-limit') {
           finish({ type: 'output-limit' })
         } else if (raw.type === 'done') {
@@ -88,8 +258,10 @@ if (isMainThread) {
         : { type: 'reply', id: message.id, ok: false, message: String(message.message) })
     }
   })
-  input.on('close', () => { if (worker && !finished) void worker.terminate() })
-} else {
+  process.on('disconnect', () => { if (worker && !finished) void worker.terminate() })
+}
+
+if (!isMainThread) {
   const port = parentPort
   if (!port) throw new Error('remote worker requires parentPort')
 
@@ -456,5 +628,9 @@ if (isMainThread) {
     process.stdout.write = originalStdout
     process.stderr.write = originalStderr
   }
+} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
+  runController()
+} else {
+  runLauncher()
 }
 `
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
index 9824fb2cf0..9743c361c5 100644
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
@@ -1,3 +1,7 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { PassThrough, Writable } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
@@ -153,7 +157,120 @@ function request(program = 'return 1') {
   return { program, bindings: [] }
 }
 
+async function runInstalledRunner(
+  code: string,
+  maxOutputBytes = 2_000_000,
+): Promise<{ messages: unknown[]; stderr: string }> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-runner-'))
+  const runner = join(directory, 'runner.mjs')
+  await writeFile(runner, CODE_RUNNER_SOURCE)
+  const child = spawn(process.execPath, [runner], { stdio: ['pipe', 'pipe', 'pipe'] })
+  const decoder = new E2BFrameDecoder(4_000_000)
+  const messages: unknown[] = []
+  let stderr = ''
+  let outputError: unknown
+  child.stdout.setEncoding('ascii')
+  child.stdout.on('data', (chunk: string) => {
+    try {
+      messages.push(...decoder.push(chunk))
+    } catch (error: unknown) {
+      outputError = error
+      child.kill('SIGKILL')
+    }
+  })
+  child.stderr.setEncoding('utf8')
+  child.stderr.on('data', (chunk: string) => { stderr += chunk })
+
+  try {
+    child.stdin.write(encodeE2BFrame({
+      type: 'boot',
+      code,
+      namespaces: [],
+      computeMs: 1_000,
+      maxOutputBytes,
+      maxOldGenerationSizeMb: 128,
+    }))
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        child.kill('SIGKILL')
+        reject(new Error('installed E2B code runner did not exit'))
+      }, 5_000)
+      child.once('error', (error) => {
+        clearTimeout(timeout)
+        reject(error)
+      })
+      child.once('exit', () => {
+        clearTimeout(timeout)
+        resolve()
+      })
+    })
+    if (outputError !== undefined) throw outputError
+    decoder.finish()
+    return { messages, stderr }
+  } finally {
+    child.kill('SIGKILL')
+    await rm(directory, { recursive: true, force: true })
+  }
+}
+
 describe('E2BCodeRuntime', () => {
+  it('keeps model-owned descriptors outside the host framing process', async () => {
+    const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
+    const { messages, stderr } = await runInstalledRunner(
+      `
+        const fs = await import('node:fs')
+        const childProcess = await import('node:child_process')
+        fs.writeSync(1, ${JSON.stringify(forged)})
+        childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("child-native")'], { stdio: 'inherit' })
+        return true
+      `,
+    )
+    const records = messages as Array<{ type?: string; text?: string; value?: unknown }>
+    const terminal = records.filter(message => message.type === 'done')
+
+    expect(stderr).toBe('')
+    expect(terminal).toEqual([{ type: 'done', value: [true] }])
+    expect(records.at(-1)).toEqual(terminal[0])
+    expect(records.filter(message => message.type === 'log').map(message => message.text).join(''))
+      .toContain(forged + 'child-native')
+  })
+
+  it('bounds native descriptor output before it reaches the host protocol', async () => {
+    const { messages, stderr } = await runInstalledRunner(
+      "(await import('node:fs')).writeSync(1, 'x'.repeat(4096)); return true",
+      64,
+    )
+    const records = messages as Array<{ type?: string; text?: string }>
+
+    expect(stderr).toBe('')
+    expect(records.at(-1)).toEqual({ type: 'output-limit' })
+    expect(Buffer.byteLength(records.filter(message => message.type === 'log').map(message => message.text).join('')))
+      .toBeLessThanOrEqual(62)
+  })
+
+  it('drains native worker pipes before emitting the terminal frame', async () => {
+    const expectedBytes = 1_048_576
+    const { messages, stderr } = await runInstalledRunner(
+      `
+        let stdoutPrototype = Object.getPrototypeOf(process.stdout)
+        while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
+        Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(${expectedBytes})])
+        return true
+      `,
+    )
+    const records = messages as Array<{ type?: string; text?: string }>
+    const terminalIndex = records.findIndex(message => message.type === 'done')
+    const nativeOutput = records
+      .slice(0, terminalIndex)
+      .filter(message => message.type === 'log')
+      .map(message => message.text ?? '')
+      .join('')
+
+    expect(stderr).toBe('')
+    expect(terminalIndex).toBe(records.length - 1)
+    expect(Buffer.byteLength(nativeOutput)).toBe(expectedBytes)
+  })
+
   it('prepares the remote runner and returns logs and a lossless completion', async () => {
     const handle = new FakeHandle((message, current) => {
       if ((message as { type?: string }).type !== 'boot') return
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 5c9bd56fc9..4f4ea19eb9 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -1,9 +1,15 @@
 import { access } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import { E2BPtyBackend } from '@deepseek-ai/dsh-pty-e2b'
+import { PtySessionId } from '@deepseek-ai/dsh-pty'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
 
 const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
 const binScript = join(fixtureRoot, 'bin.ts')
@@ -11,6 +17,53 @@ const configPath = join(fixtureRoot, 'cordis.yml')
 const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
+  it('scrubs sandbox-default credentials from an actual E2B PTY', async () => {
+    const apiKey = process.env.E2B_API_KEY
+    if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared before the PTY environment test')
+    const sandbox = await Sandbox.create({
+      apiKey,
+      envs: { NPM_TOKEN: 'sentinel-secret', DSH_STALE: 'sentinel-stale', KEEP: 'visible' },
+      timeoutMs: 60_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
+    try {
+      const ctx = new Context()
+      ctx.provide('e2b', { cwd: '/home/user', getSandbox: async () => sandbox } as never)
+      const ownerId = SessionId('e2b-pty-env-owner')
+      const owner: Agent = {
+        id: ownerId,
+        options: {},
+        session: new Session(ownerId),
+        status: 'idle',
+        acceptsNextStep: false,
+        ctx,
+        followup: () => AgentMessageId('unused'),
+        steer: () => AgentMessageId('unused'),
+        inject: () => AgentMessageId('unused'),
+        send: () => AgentMessageId('unused'),
+        cancel() {},
+        whenIdle: () => Promise.resolve(),
+      }
+      const backend = new E2BPtyBackend(ctx, {
+        backendType: 'shell', rows: 24, cols: 80,
+        scrollbackLines: 100, scrollbackMaxBytes: 65_536, maxReadBytes: 16_384,
+        pollIntervalMs: 25, idleSilenceMs: 1_000, timeoutMs: 5_000, disposeGraceMs: 1_000,
+      })
+      const session = await backend.spawn({ sessionId: PtySessionId('env'), owner, type: 'shell' })
+      const result = await session.startSend({
+        text: "printf 'NPM=<%s> DSH=<%s> KEEP=<%s>\\n' \"$NPM_TOKEN\" \"$DSH_STALE\" \"$KEEP\"",
+        submit: true,
+      }).done
+      expect(result.viewport).toContain('NPM=<> DSH=<> KEEP=<visible>')
+      expect(result.viewport).not.toContain('sentinel-secret')
+      expect(result.viewport).not.toContain('sentinel-stale')
+      await session.close('environment test complete')
+    } finally {
+      await sandbox.kill().catch(() => false)
+    }
+  }, 70_000)
+
   it('runs FS, Bash, PTY, LSP, and Code Runtime in one sandbox and deletes it', async () => {
     const { stdout, stderr } = await runLoaderSmoke({
       label: 'E2B composition',
@@ -22,7 +75,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       env: {
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
       },
-      processTimeoutMs: 120_000,
+      processTimeoutMs: 180_000,
       inspect: async (cwd) => {
         for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte # file.ts', 'fixture-lsp.mjs']) {
           await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
@@ -36,6 +89,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
+      publicationRollback: true,
       spill: {
         liveBytes: 6,
         outcome: { exitCode: null, signal: 'SIGTERM' },
@@ -49,12 +103,18 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         kind: 'locations',
         locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
       },
+      lspContainment: true,
+      lspDocumentBound: true,
       terminal: {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
         signal: { delivered: true },
         interrupted: { sessionStatus: { kind: 'running' } },
+        treeCleanup: true,
       },
       hostileOutput: { error: { kind: 'output-limit' } },
+      nativeOutput: { error: { kind: 'output-limit' } },
+      descriptorOutput: { error: { kind: 'output-limit' } },
+      inheritedOutput: { error: { kind: 'output-limit' } },
       timedOut: { error: { kind: 'timeout' } },
       aborted: { error: { kind: 'abort', message: 'live abort' } },
       oversizedBoot: { error: { kind: 'worker-exit' } },
@@ -75,5 +135,5 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
-  }, 135_000)
+  }, 195_000)
 })
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index b416105166..95a3a9eea6 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: d8f3915fa281e8b9c062e3412c92bc6358616284
-README.zh.md: 93d27bcdd514ccbf87e07d0eff5958edf3c726c1
+README.md: a505703fc764f8441fa54d2b1d922762eb3fafdf
+README.zh.md: 626fdb52979d29f12d1bc1b67b0ea13730003af7
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index d8f3915fa2..a505703fc7 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -8,7 +8,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through same-directory Linux `mv -f`. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through E2B's same-directory atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 93d27bcdd5..626fdb5297 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -8,7 +8,7 @@
 
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过同目录 Linux `mv -f` 发布。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 4f733f1fba..2a7fd1275f 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -412,11 +412,7 @@ export class E2BFileSystem extends FileSystem {
         signalOpts(signal),
       )
       assertNotAborted(signal, 'write')
-      await sandbox.commands.run(
-        `mv -f -- ${quoteE2BShellArg(temporary)} ${quoteE2BShellArg(targetPath)}`,
-        signalOpts(signal),
-      )
-      const committed = await sandbox.files.getInfo(targetPath)
+      const committed = await sandbox.files.rename(temporary, targetPath, signalOpts(signal))
       return entryVersion(committed)
     } catch (error: unknown) {
       try {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 177bb9e59c..13d94e70c7 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -453,6 +453,17 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(controller.signal.aborted).toBe(true)
   })
 
+  it('returns committed rename metadata without a fallible post-commit lookup', async () => {
+    const remote = new FakeRemote()
+    const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
+    const { fs } = await setup(remote)
+
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes'))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(getInfo).toHaveBeenCalledTimes(1)
+    expect(remote.renames).toHaveLength(1)
+  })
+
   it('cleans staging files and maps command, permission, and abort failures', async () => {
     const remote = new FakeRemote()
     const { fs } = await setup(remote)
diff --git a/packages/e2b/lsp-e2b/README.i18n.yaml b/packages/e2b/lsp-e2b/README.i18n.yaml
index 5f126d7e56..066820d9fd 100644
--- a/packages/e2b/lsp-e2b/README.i18n.yaml
+++ b/packages/e2b/lsp-e2b/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/e2b/lsp-e2b/README.md
-README.md: ded928ec073e6c0943d574d86359eeec586bb862
-README.zh.md: 91eb7cecb49adcf73f4be948e9a5da400981e6f1
+README.md: 6cc118767adc5d2df855b009f48faab596928fb7
+README.zh.md: b384e9efd0e5c62b0ee6e69f73755e1bbe0192df
diff --git a/packages/e2b/lsp-e2b/README.md b/packages/e2b/lsp-e2b/README.md
index ded928ec07..6cc118767a 100644
--- a/packages/e2b/lsp-e2b/README.md
+++ b/packages/e2b/lsp-e2b/README.md
@@ -27,7 +27,7 @@ Provider ids and commands are non-empty; numeric bounds are positive safe intege
 
 E2B command callbacks are text, while LSP is byte-framed. The installed proxy therefore base64-frames raw server stdout, stderr, and stdin as newline-delimited ASCII JSON; the host validates and decodes every frame before handing bytes to the shared `LspInstance` protocol engine. `initialize.processId` is `null` because host and server do not share a process namespace.
 
-One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, requires a regular file, enforces the size bound before and after reading, decodes strict UTF-8, and uses the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
+One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, then uses a remote helper to open the canonical source without following the final symlink and to verify and read one stable descriptor. The helper requires a regular file and reads at most `maxDocumentBytes + 1` bytes before strict UTF-8 decoding. Queries use the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
 
 The subprocess adapter owns process groups and escalation, so cancellation and disposal await remote server quiescence. The host owns LSP request ids, pending requests, provider queues, and normalized results.
 
diff --git a/packages/e2b/lsp-e2b/README.zh.md b/packages/e2b/lsp-e2b/README.zh.md
index 91eb7cecb4..b384e9efd0 100644
--- a/packages/e2b/lsp-e2b/README.zh.md
+++ b/packages/e2b/lsp-e2b/README.zh.md
@@ -27,7 +27,7 @@
 
 E2B 命令回调交付的是文本，而 LSP 按字节分帧。因此，已安装的代理会把服务器 stdout、stderr 和 stdin 的原始字节进行 base64 编码，封装为以换行分隔的 ASCII JSON 帧；宿主会验证并解码每一帧，再把字节交给共享的 `LspInstance` 协议引擎。`initialize.processId` 为 `null`，因为宿主与服务器不共享进程命名空间。
 
-每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，要求源文件为普通文件，在读取前后都检查大小上限，使用严格的 UTF-8 解码，并采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
+每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，再由远程 helper 以不跟随最终符号链接的方式打开规范化源文件，并在同一个稳定描述符上完成验证与读取。该 helper 要求目标为普通文件，最多读取 `maxDocumentBytes + 1` 字节，随后执行严格的 UTF-8 解码。查询采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
 
 进程管理适配器负责进程组和终止升级，因此取消与资源释放都会等待远程服务器完全停稳。宿主负责 LSP 请求 id、待完成请求、提供方队列和规范化结果。
 
diff --git a/packages/e2b/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
index b378ebfc9a..fa6b3729da 100644
--- a/packages/e2b/lsp-e2b/src/index.ts
+++ b/packages/e2b/lsp-e2b/src/index.ts
@@ -92,6 +92,46 @@ interface RemoteSource {
   text: string
 }
 
+interface RemoteSourceReadResponse {
+  kind: 'ok' | 'not-file' | 'oversize' | 'grew' | 'open-error'
+  data?: string
+  size?: number
+  message?: string
+}
+
+const SOURCE_READER_SOURCE = String.raw`
+/* dsh-e2b-source-reader */
+const fs = require('node:fs')
+const path = process.argv[1]
+const maxBytes = Number(process.argv[2])
+let descriptor
+let response
+try {
+  descriptor = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+  const info = fs.fstatSync(descriptor)
+  if (!info.isFile()) response = { kind: 'not-file' }
+  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
+  else {
+    const chunks = []
+    let total = 0
+    while (total <= maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
+      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
+      if (bytesRead === 0) break
+      chunks.push(chunk.subarray(0, bytesRead))
+      total += bytesRead
+    }
+    response = total > maxBytes
+      ? { kind: 'grew' }
+      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
+  }
+} catch (error) {
+  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
+}
+if (descriptor !== undefined) fs.closeSync(descriptor)
+process.stdout.write(JSON.stringify(response))
+`
+
 function abortReason(signal: AbortSignal): unknown {
   try {
     signal.throwIfAborted()
@@ -164,7 +204,8 @@ export async function canonicalizeE2BWorkspace(
  * @param sandbox - Shared sandbox that owns the source.
  * @param filePath - Absolute path or path relative to the canonical workspace.
  * @param workspace - Canonical remote workspace directory.
- * @param maxDocumentBytes - Maximum source size before and after reading.
+ * @param maxDocumentBytes - Maximum bytes read through the stable remote handle.
+ * @param nodeExecutable - Resolved remote Node executable used by the bounded reader.
  * @param signal - Optional query cancellation signal.
  * @returns The canonical source path and decoded text.
  */
@@ -173,6 +214,7 @@ export async function readE2BSource(
   filePath: string,
   workspace: string,
   maxDocumentBytes: number,
+  nodeExecutable: string,
   signal?: AbortSignal,
 ): Promise<RemoteSource> {
   const requested = posix.isAbsolute(filePath) ? filePath : posix.resolve(workspace, filePath)
@@ -181,16 +223,39 @@ export async function readE2BSource(
   if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
     throw new Error(`source ${JSON.stringify(filePath)} resolves outside the workspace`)
   }
-  const info = await sandbox.files.getInfo(canonicalPath, signal === undefined ? {} : { signal })
-  if (info.type !== FileType.FILE) throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
-  if (info.size > maxDocumentBytes) {
-    throw new Error(`source ${JSON.stringify(filePath)} is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-  }
-  const bytes = await sandbox.files.read(canonicalPath, { format: 'bytes', ...signal === undefined ? {} : { signal } })
+  const command = [
+    quoteE2BShellArg(nodeExecutable),
+    '--input-type=commonjs',
+    '-e',
+    quoteE2BShellArg(SOURCE_READER_SOURCE),
+    quoteE2BShellArg(canonicalPath),
+    String(maxDocumentBytes),
+  ].join(' ')
+  const result = await sandbox.commands.run(command, signal === undefined ? {} : { signal })
   signal?.throwIfAborted()
-  if (bytes.length > maxDocumentBytes) {
+  let response: RemoteSourceReadResponse
+  try {
+    response = JSON.parse(result.stdout) as RemoteSourceReadResponse
+  } catch (error: unknown) {
+    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`, { cause: error })
+  }
+  if (response.kind === 'not-file') throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
+  if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
+    throw new Error(`source ${JSON.stringify(filePath)} is ${response.size} bytes, over the ${maxDocumentBytes}-byte limit`)
+  }
+  if (response.kind === 'grew') {
     throw new Error(`source ${JSON.stringify(filePath)} grew past the ${maxDocumentBytes}-byte limit while reading`)
   }
+  if (response.kind === 'open-error' && typeof response.message === 'string') {
+    throw new Error(`source ${JSON.stringify(filePath)} could not be opened safely: ${response.message}`)
+  }
+  if (response.kind !== 'ok' || typeof response.data !== 'string') {
+    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`)
+  }
+  const bytes = Buffer.from(response.data, 'base64')
+  if (bytes.toString('base64') !== response.data || bytes.length > maxDocumentBytes) {
+    throw new Error(`source ${JSON.stringify(filePath)} reader returned invalid bounded bytes`)
+  }
   let text: string
   try {
     text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
@@ -239,7 +304,14 @@ export class E2BLspProvider implements LspProvider {
     this.assertActive(signal)
     return this.enqueue(workspace, signal, async () => {
       this.assertActive(signal)
-      const source = await readE2BSource(this.sandbox, request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readE2BSource(
+        this.sandbox,
+        request.filePath,
+        workspace,
+        this.config.maxDocumentBytes,
+        this.nodeExecutable,
+        signal,
+      )
       this.assertActive(signal)
       let instance = this.instanceFor(workspace)
       try {
diff --git a/packages/e2b/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
index d746abe7f7..dc92053e4a 100644
--- a/packages/e2b/lsp-e2b/tests/provider.spec.ts
+++ b/packages/e2b/lsp-e2b/tests/provider.spec.ts
@@ -94,11 +94,14 @@ class FakeRemote {
   readonly contents = new Map<string, Uint8Array>()
   readonly realpaths = new Map<string, string>()
   forcedRealpath: string | undefined
+  readerResponse: unknown
+  readerOutput: string | undefined
 
   constructor() {
     this.infos.set('/workspace', { type: FileType.DIR, size: 0 })
     this.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 12 })
     this.contents.set('/workspace/file.ts', Buffer.from('const x = 1'))
+    this.readerResponse = { kind: 'ok', data: Buffer.from('const x = 1').toString('base64') }
   }
 
   readonly sandbox = {
@@ -110,6 +113,9 @@ class FakeRemote {
           const requested = match?.[1] ?? ''
           return { exitCode: 0, stdout: `${this.forcedRealpath ?? this.realpaths.get(requested) ?? requested}\n`, stderr: '' }
         }
+        if (command.includes('dsh-e2b-source-reader')) {
+          return { exitCode: 0, stdout: this.readerOutput ?? JSON.stringify(this.readerResponse), stderr: '' }
+        }
         if (command.startsWith('command -v')) return { exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' }
         return { exitCode: 0, stdout: '', stderr: '' }
       },
@@ -172,16 +178,16 @@ describe('E2B LSP filesystem boundary', () => {
   it('canonicalizes a directory and reads a contained UTF-8 source', async () => {
     const remote = new FakeRemote()
     await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace')).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024)).resolves.toEqual({
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toEqual({
       canonicalPath: '/workspace/file.ts',
       text: 'const x = 1',
     })
-    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024)).resolves.toMatchObject({
+    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toMatchObject({
       canonicalPath: '/workspace/file.ts',
     })
     const signal = new AbortController().signal
     await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace', signal)).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, signal)).resolves.toMatchObject({
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node', signal)).resolves.toMatchObject({
       canonicalPath: '/workspace/file.ts',
     })
   })
@@ -199,25 +205,35 @@ describe('E2B LSP filesystem boundary', () => {
 
     const outside = new FakeRemote()
     outside.realpaths.set('/workspace/file.ts', '/outside/file.ts')
-    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('outside the workspace')
+    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('outside the workspace')
 
     const notFile = new FakeRemote()
-    notFile.infos.set('/workspace/file.ts', { type: FileType.DIR, size: 0 })
-    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not a regular file')
+    notFile.readerResponse = { kind: 'not-file' }
+    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not a regular file')
 
     const tooLarge = new FakeRemote()
-    tooLarge.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 21 })
-    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('over the 20-byte limit')
+    tooLarge.readerResponse = { kind: 'oversize', size: 21 }
+    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('over the 20-byte limit')
 
     const grew = new FakeRemote()
-    grew.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
-    grew.contents.set('/workspace/file.ts', Buffer.alloc(21))
-    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('grew past')
+    grew.readerResponse = { kind: 'grew' }
+    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('grew past')
 
     const invalid = new FakeRemote()
-    invalid.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
-    invalid.contents.set('/workspace/file.ts', Uint8Array.from([0xff]))
-    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not valid UTF-8')
+    invalid.readerResponse = { kind: 'ok', data: Buffer.from([0xff]).toString('base64') }
+    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not valid UTF-8')
+
+    const swapped = new FakeRemote()
+    swapped.readerResponse = { kind: 'open-error', message: 'ELOOP: symbolic link encountered' }
+    await expect(readE2BSource(swapped.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('opened safely')
+
+    const malformedReader = new FakeRemote()
+    malformedReader.readerResponse = { kind: 'ok', data: '*' }
+    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid bounded bytes')
+    malformedReader.readerResponse = { kind: 'oversize', size: 'large' }
+    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
+    malformedReader.readerOutput = '{'
+    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
 
     await expect(canonicalizeE2BWorkspace(new FakeRemote().sandbox, '/workspace', AbortSignal.abort('stop')))
       .rejects.toBe('stop')
diff --git a/packages/e2b/pty-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
index 1bd8485e8f..ddae4c21db 100644
--- a/packages/e2b/pty-e2b/README.i18n.yaml
+++ b/packages/e2b/pty-e2b/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/e2b/pty-e2b/README.md
-README.md: 3d363309f6bd1c4def5fbff668735958ca2de52d
-README.zh.md: 78d61cc654bf6eb46a3bec7124b3cc06cc7e34e9
+README.md: d6d8e05f13701b85cee9a9646bfdd82ac07769da
+README.zh.md: 265257c72e7bcbd2dfd805b343db5bab7173ab51
diff --git a/packages/e2b/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
index 3d363309f6..d6d8e05f13 100644
--- a/packages/e2b/pty-e2b/README.md
+++ b/packages/e2b/pty-e2b/README.md
@@ -20,13 +20,13 @@ The `pty-e2b` plugin injects `e2b` and `pty`, then registers one backend under `
 | `timeoutMs` | `30000` | Absolute startup and send wait bound. |
 | `disposeGraceMs` | `3000` | TERM-to-KILL cleanup grace. |
 
-Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute.
+Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute. Before launch, the backend enumerates sandbox-default environment names, blanks `DSH_*` and credential-shaped names, then overlays its controlled terminal values and explicit `spec.env` entries.
 
 ## Runtime contract
 
 The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
 
-Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. Close sends `SIGTERM` to the PTY process group, waits, escalates through E2B's PTY kill, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
+Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
 
 The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
 
@@ -51,4 +51,5 @@ No direct invalidation; the consumer owns prompts, schemas, and appended results
 - **Line-oriented terminal model** — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
 - **Readiness is marker-or-silence based** — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so `inferred_idle` is deliberately possible.
 - **UTF-8 only** — invalid byte sequences fail the session instead of returning lossy text.
+- **Deliberate session escape is unmanaged** — a process that calls `setsid` leaves the terminal session and is outside this backend's cleanup identity.
 - **No reconnectable terminal handles** — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.
diff --git a/packages/e2b/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
index 78d61cc654..265257c72e 100644
--- a/packages/e2b/pty-e2b/README.zh.md
+++ b/packages/e2b/pty-e2b/README.zh.md
@@ -20,13 +20,13 @@
 | `timeoutMs` | `30000` | 启动与发送等待的绝对上限。 |
 | `disposeGraceMs` | `3000` | TERM 到 KILL 的清理宽限期。 |
 
-数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。
+数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。启动前，后端会枚举沙箱默认环境变量名，清空 `DSH_*` 和形似凭据的名称，再覆盖其受控终端值与显式 `spec.env` 条目。
 
 ## 运行时契约
 
 该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
 
-每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。关闭操作向 PTY 进程组发送 `SIGTERM`，等待后通过 E2B 的 PTY kill 操作升级，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
+每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
 
 远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
 
@@ -51,4 +51,5 @@
 - **面向行的终端模型**：CSI／OSC 控制序列会被移除；备用屏幕与完整终端仿真仍不受支持。
 - **就绪判断基于标记或静默**：E2B 会公开前台进程组，但不提供本地后端使用的 Linux syscall 检查，因此系统有意保留返回 `inferred_idle` 的可能性。
 - **仅支持 UTF-8**：无效字节序列会使会话失败，而不是返回有损文本。
+- **主动逃离会话的进程不受管理**：调用 `setsid` 的进程会离开终端会话，因而不属于本后端的清理身份。
 - **没有可重连的终端句柄**：保留 E2B 沙箱会保留远程文件，但不会保留宿主所有权、缓冲区、回调或实时 PTY 会话。
diff --git a/packages/e2b/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
index 8fd7a519a0..d665a734b7 100644
--- a/packages/e2b/pty-e2b/src/index.ts
+++ b/packages/e2b/pty-e2b/src/index.ts
@@ -17,8 +17,22 @@ export const name = 'pty-e2b'
 /** Required shared sandbox owner and PTY registry. */
 export const inject = ['e2b', 'pty']
 
-function terminalEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+const SENSITIVE_ENV_NAME = /KEY|SECRET|TOKEN/i
+
+async function terminalEnvironment(
+  sandbox: Sandbox,
+  spec: PtyBackendSpawnSpec,
+): Promise<Record<string, string>> {
+  const discovered = await sandbox.commands.run(
+    'env -0 | cut -z -d= -f1',
+    spec.signal === undefined ? {} : { signal: spec.signal },
+  )
+  spec.signal?.throwIfAborted()
+  const scrubbed = Object.fromEntries(discovered.stdout.split('\0')
+    .filter(name => name.startsWith('DSH_') || SENSITIVE_ENV_NAME.test(name))
+    .map(name => [name, '']))
   return {
+    ...scrubbed,
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
@@ -31,6 +45,20 @@ function terminalEnvironment(spec: PtyBackendSpawnSpec): Record<string, string>
   }
 }
 
+async function resolveTerminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
+  const result = await sandbox.commands.run(
+    `ps -o sid= -p ${pid}`,
+    signal === undefined ? {} : { signal },
+  )
+  signal?.throwIfAborted()
+  const raw = result.stdout.trim()
+  const sessionId = Number(raw)
+  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(sessionId)) {
+    throw new Error(`pty-e2b: cannot resolve process session for E2B PTY ${pid}`)
+  }
+  return sessionId
+}
+
 /** E2B backend registered under the configured terminal type. */
 export class E2BPtyBackend implements PtyBackend {
   readonly type: string
@@ -57,7 +85,7 @@ export class E2BPtyBackend implements PtyBackend {
       rows: this.config.rows,
       cols: this.config.cols,
       cwd: posix.resolve(this.ctx.e2b.cwd, spec.cwd ?? this.ctx.e2b.cwd),
-      envs: terminalEnvironment(spec),
+      envs: await terminalEnvironment(sandbox, spec),
       timeoutMs: 0,
       ...spec.signal === undefined ? {} : { signal: spec.signal },
       onData: (data) => {
@@ -69,7 +97,15 @@ export class E2BPtyBackend implements PtyBackend {
       await handle.kill().catch(() => false)
       throw new Error(`pty-e2b: E2B returned invalid PTY pid ${handle.pid}`)
     }
-    const session = new E2BPtySession(sandbox, handle, this.config)
+    let terminalSessionId: number
+    try {
+      terminalSessionId = await resolveTerminalSessionId(sandbox, handle.pid, spec.signal)
+    } catch (error: unknown) {
+      await handle.kill().catch(() => false)
+      await Promise.allSettled([handle.wait()])
+      throw error
+    }
+    const session = new E2BPtySession(sandbox, handle, terminalSessionId, this.config)
     created.session = session
     try {
       const initializing = session.initialize(spec.signal)
diff --git a/packages/e2b/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
index e5dfc05efe..bf8780103d 100644
--- a/packages/e2b/pty-e2b/src/session.ts
+++ b/packages/e2b/pty-e2b/src/session.ts
@@ -105,6 +105,7 @@ export class E2BPtySession implements PtyBackendSession {
   constructor(
     private readonly sandbox: Sandbox,
     private readonly handle: CommandHandle,
+    private readonly terminalSessionId: number,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = handle.pid
@@ -314,6 +315,40 @@ export class E2BPtySession implements PtyBackendSession {
     return pgid
   }
 
+  private async sessionProcessGroups(): Promise<number[]> {
+    const result = await this.sandbox.commands.run(
+      `ps -eo sid=,pgid= | awk '$1 == ${this.terminalSessionId} { print $2 }'`,
+    )
+    const groups = new Set<number>()
+    for (const raw of result.stdout.trim().split(/\s+/)) {
+      if (raw.length === 0) continue
+      const pgid = Number(raw)
+      if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid) || pgid <= 1) {
+        throw new Error(`pty-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.terminalSessionId}`)
+      }
+      groups.add(pgid)
+    }
+    return [...groups]
+  }
+
+  private async signalProcessGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+    try {
+      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(pgid => `-${pgid}`).join(' ')}`)
+    } catch (error: unknown) {
+      if (!(error instanceof CommandExitError)) throw error
+    }
+  }
+
+  private async awaitSessionEmpty(timeoutMs: number, signal?: 'KILL'): Promise<number[]> {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const groups = await this.sessionProcessGroups()
+      if (groups.length === 0 || Date.now() >= deadline) return groups
+      if (signal !== undefined) await this.signalProcessGroups(groups, signal)
+      await delay(Math.min(this.config.pollIntervalMs, deadline - Date.now()))
+    }
+  }
+
   private onExit(exitCode: number): void {
     this.remoteExited = true
     let tail = ''
@@ -343,19 +378,20 @@ export class E2BPtySession implements PtyBackendSession {
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    if (!this.remoteExited) {
+    let survivingGroups = await this.sessionProcessGroups()
+    if (survivingGroups.length > 0) {
       this.closeSignal = 'SIGTERM'
-      try {
-        await this.sandbox.commands.run(`kill -TERM -- -${this.pid}`)
-      } catch (error: unknown) {
-        if (!(error instanceof CommandExitError)) throw error
-      }
-      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+      await this.signalProcessGroups(survivingGroups, 'TERM')
+      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs)
     }
-    if (!this.remoteExited) {
+    if (survivingGroups.length > 0 || !this.remoteExited) {
       this.closeSignal = 'SIGKILL'
-      await this.sandbox.pty.kill(this.pid)
-      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+      if (!this.remoteExited) await this.sandbox.pty.kill(this.pid)
+      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs, 'KILL')
+      if (!this.remoteExited) await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (survivingGroups.length > 0) {
+      throw new Error(`E2B PTY cleanup failed (${reason}); surviving process groups: ${survivingGroups.join(', ')}`)
     }
     if (!this.remoteExited) {
       throw new Error(`E2B PTY cleanup failed (${reason}); surviving pid: ${this.pid}`)
diff --git a/packages/e2b/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
index e306d8b86b..476ddc38df 100644
--- a/packages/e2b/pty-e2b/tests/index.spec.ts
+++ b/packages/e2b/pty-e2b/tests/index.spec.ts
@@ -42,7 +42,10 @@ describe('E2BPtyBackend and plugin', () => {
   it('creates a remote PTY with isolated environment and initializes the session', async () => {
     vi.useFakeTimers()
     const ctx = new Context()
-    const sandbox = {} as Sandbox
+    const run = vi.fn(async (command: string) => command.startsWith('env -0')
+      ? { exitCode: 0, stdout: 'NPM_TOKEN\0DSH_STALE\0KEEP\0', stderr: '' }
+      : { exitCode: 0, stdout: '123\n', stderr: '' })
+    const sandbox = { commands: { run } } as unknown as Sandbox
     ctx.provide('e2b', {
       cwd: '/workspace',
       getSandbox: async () => sandbox,
@@ -65,9 +68,11 @@ describe('E2BPtyBackend and plugin', () => {
     expect(session.motd).toBe('banner\ndsh> ')
     expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
     expect(options?.envs).toMatchObject({
+      NPM_TOKEN: '', DSH_STALE: '',
       TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
       DSH_SHELL: '1', DSH_SESSION_ID: 'owner', DSH_PTY_SESSION_ID: 'pty-1',
     })
+    expect(options?.envs).not.toHaveProperty('KEEP')
     vi.useRealTimers()
   })
 
@@ -79,7 +84,10 @@ describe('E2BPtyBackend and plugin', () => {
       setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
       return created
     })
-    const sandbox = { pty: { create } } as unknown as Sandbox
+    const sandbox = {
+      commands: { run: async (command: string) => ({ exitCode: 0, stdout: command.startsWith('env -0') ? '' : '123\n', stderr: '' }) },
+      pty: { create },
+    } as unknown as Sandbox
     ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
     const backend = new E2BPtyBackend(ctx, config())
     const pending = backend.spawn({ sessionId: PtySessionId('default'), owner: owner(ctx), type: 'shell' })
@@ -91,7 +99,9 @@ describe('E2BPtyBackend and plugin', () => {
 
   it('rejects aborts and invalid pids, killing a malformed SDK handle', async () => {
     const ctx = new Context()
-    const sandbox = {} as Sandbox
+    const sandbox = {
+      commands: { run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
+    } as unknown as Sandbox
     ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
     const create = vi.fn().mockResolvedValue(handle(0))
     const backend = new E2BPtyBackend(ctx, config(), create)
@@ -109,13 +119,47 @@ describe('E2BPtyBackend and plugin', () => {
     const killFailure = handle(0, killFailureKill)
     const raced = new E2BPtyBackend(ctx, config(), async () => killFailure)
     await expect(raced.spawn({ sessionId: PtySessionId('three'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
+
+    const invalidSessionKill = vi.fn().mockRejectedValue(new Error('kill raced'))
+    const invalidSessionHandle = {
+      pid: 123,
+      wait: vi.fn().mockRejectedValue(new Error('already exited')),
+      kill: invalidSessionKill,
+      disconnect: vi.fn(),
+    } as unknown as CommandHandle
+    const invalidSessionSandbox = {
+      commands: {
+        run: async (command: string) => ({
+          exitCode: 0,
+          stdout: command.startsWith('env -0') ? '' : '9007199254740992\n',
+          stderr: '',
+        }),
+      },
+    } as unknown as Sandbox
+    const invalidSessionContext = new Context()
+    invalidSessionContext.provide('e2b', {
+      cwd: '/workspace',
+      getSandbox: async () => invalidSessionSandbox,
+    } as E2BSandboxService)
+    const invalidSession = new E2BPtyBackend(invalidSessionContext, config(), async () => invalidSessionHandle)
+    await expect(invalidSession.spawn({
+      sessionId: PtySessionId('four'), owner: owner(invalidSessionContext), type: 'shell',
+    }))
+      .rejects.toThrow('cannot resolve process session')
+    expect(invalidSessionKill).toHaveBeenCalledOnce()
   })
 
   it('cleans failed startup and aggregates a cleanup failure', async () => {
     vi.useFakeTimers()
     const ctx = new Context()
     const sandbox = {
-      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }) },
+      commands: {
+        run: vi.fn(async (command: string) => ({
+          exitCode: 0,
+          stdout: command.startsWith('ps -o sid=') || command.startsWith('ps -eo sid=') ? '123\n' : '',
+          stderr: '',
+        })),
+      },
       pty: { kill: vi.fn().mockRejectedValue(new Error('cleanup failed')) },
     } as unknown as Sandbox
     ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
@@ -141,10 +185,19 @@ describe('E2BPtyBackend and plugin', () => {
       wait: () => completion.promise,
       disconnect: vi.fn().mockResolvedValue(undefined),
     } as unknown as CommandHandle
+    let sessionRunning = true
     const sandbox = {
       commands: {
         run: vi.fn(async (command: string) => {
-          if (command.startsWith('kill -TERM')) completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
+          if (command.startsWith('env -0')) return { exitCode: 0, stdout: '', stderr: '' }
+          if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: '123\n', stderr: '' }
+          if (command.startsWith('ps -eo sid=')) {
+            return { exitCode: 0, stdout: sessionRunning ? '123\n' : '', stderr: '' }
+          }
+          if (command.startsWith('kill -TERM')) {
+            sessionRunning = false
+            completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
+          }
           return { exitCode: 0, stdout: '', stderr: '' }
         }),
       },
diff --git a/packages/e2b/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
index 6dced22ed2..554a4a3590 100644
--- a/packages/e2b/pty-e2b/tests/session.spec.ts
+++ b/packages/e2b/pty-e2b/tests/session.spec.ts
@@ -64,10 +64,12 @@ class FakeSandbox {
   readonly commands: string[] = []
   readonly killed: number[] = []
   pgid = '456\n'
+  sessionGroups = [123]
   sendError: unknown
-  commandError: unknown
+  signalError: unknown
   killError: unknown
   onTerm: (() => void) | undefined
+  onGroupKill: (() => void) | undefined
   onKill: (() => void) | undefined
 
   readonly sandbox = {
@@ -86,13 +88,19 @@ class FakeSandbox {
     commands: {
       run: async (command: string): Promise<CommandResult> => {
         this.commands.push(command)
-        if (this.commandError !== undefined) {
-          const error = this.commandError
-          this.commandError = undefined
-          throw error
+        if (command.startsWith('ps -o tpgid')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
+        if (command.startsWith('ps -eo sid=')) {
+          return { exitCode: 0, stdout: this.sessionGroups.map(value => `${value}\n`).join(''), stderr: '' }
+        }
+        if (command.startsWith('kill -')) {
+          if (this.signalError !== undefined) {
+            const error = this.signalError
+            this.signalError = undefined
+            throw error
+          }
+          if (command.startsWith('kill -TERM')) this.onTerm?.()
+          if (command.startsWith('kill -KILL')) this.onGroupKill?.()
         }
-        if (command.startsWith('ps ')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
-        if (command.startsWith('kill -TERM')) this.onTerm?.()
         return { exitCode: 0, stdout: '', stderr: '' }
       },
     },
@@ -122,7 +130,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config({ maxReadBytes: 12 }))
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config({ maxReadBytes: 12 }))
     expect(session.read({})).toMatchObject({ text: '', totalLines: 0 })
     await initialize(session)
     expect(session.motd).toBe('dsh> ')
@@ -152,7 +160,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     await initialize(session)
 
     const inferred = session.startSend({ text: '', submit: false })
@@ -176,7 +184,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
 
     const startupHandle = new FakePtyHandle()
-    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), config())
+    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), 123, config())
     const timedOut = expect(startup.initialize()).rejects.toThrow('startup timeout')
     await vi.advanceTimersByTimeAsync(100)
     await timedOut
@@ -186,7 +194,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const initializing = session.initialize()
     session.onData(Buffer.from('\x1b]133;D;0\x07'))
     await vi.advanceTimersByTimeAsync(20)
@@ -230,7 +238,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     await initialize(session)
 
     const controller = new AbortController()
@@ -268,7 +276,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
   it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
     const fake = new FakeSandbox()
     const abortHandle = new FakePtyHandle()
-    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), config())
+    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), 123, config())
     const controller = new AbortController()
     const reason = new Error('startup cancelled')
     const initializing = abortSession.initialize(controller.signal)
@@ -277,20 +285,20 @@ describe('E2BPtySession readiness, output, and signals', () => {
     await rejected
 
     const invalidHandle = new FakePtyHandle()
-    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), config())
+    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), 123, config())
     const pending = invalid.startSend({ text: '', submit: false })
     invalid.onData(Uint8Array.from([0xff]))
     await expect(pending.done).rejects.toThrow('invalid UTF-8')
     expect(invalid.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
 
     const crashHandle = new FakePtyHandle()
-    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), config())
+    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), 123, config())
     const active = crashed.startSend({ text: '', submit: false })
     crashHandle.crash('transport gone')
     await expect(active.done).rejects.toEqual(new Error('transport gone'))
 
     const startupExitHandle = new FakePtyHandle()
-    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), config())
+    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), 123, config())
     const exitedDuringStartup = expect(startupExit.initialize()).rejects.toThrow('exited during startup')
     startupExitHandle.exit(7)
     await exitedDuringStartup
@@ -300,12 +308,12 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const tinyHandle = new FakePtyHandle()
-    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), config({ maxReadBytes: 1 }))
+    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), 123, config({ maxReadBytes: 1 }))
     tiny.onData(Buffer.from('你'))
     expect(tiny.read({ count: 1 })).toMatchObject({ text: '', lineEnd: 0 })
 
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const operation = session.startSend({ text: '', submit: false })
     const internal = session as unknown as {
       pollReadiness(operation: PtySendOperation): void
@@ -324,8 +332,8 @@ describe('E2BPtySession teardown', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    fake.onTerm = () => { handle.failExit(143) }
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const first = session.close('done')
     expect(session.close('again')).toBe(first)
     await first
@@ -334,63 +342,100 @@ describe('E2BPtySession teardown', () => {
     expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
   })
 
+  it('escalates every job-control group that survives shell exit', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    fake.sessionGroups = [123, 456]
+    const handle = new FakePtyHandle()
+    fake.onTerm = () => { fake.sessionGroups = [456]; handle.failExit(143) }
+    fake.onGroupKill = () => { fake.sessionGroups = [] }
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
+
+    const closing = session.close('tree cleanup')
+    await vi.advanceTimersByTimeAsync(100)
+    await closing
+
+    expect(fake.commands).toContain('kill -TERM -- -123 -456')
+    expect(fake.commands).toContain('kill -KILL -- -456')
+  })
+
   it('contains an already-gone TERM, escalates to KILL, and reports a survivor', async () => {
     vi.useFakeTimers()
     const gone = new FakeSandbox()
     const goneHandle = new FakePtyHandle()
-    gone.commandError = commandError(1)
+    gone.signalError = commandError(1)
+    gone.onGroupKill = () => { gone.sessionGroups = [] }
     gone.onKill = () => { goneHandle.failExit(137) }
-    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), config())
+    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), 123, config())
     const closingGone = goneSession.close('gone')
-    await vi.advanceTimersByTimeAsync(20)
+    await vi.advanceTimersByTimeAsync(100)
     await closingGone
     expect(gone.killed).toEqual([123])
     expect(goneSession.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGKILL' })
 
     const survivor = new FakeSandbox()
     const survivorHandle = new FakePtyHandle()
-    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), config())
-    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving pid: 123')
-    await vi.advanceTimersByTimeAsync(40)
+    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
+    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving process groups: 123')
+    await vi.advanceTimersByTimeAsync(100)
     await failed
     survivorHandle.exit()
+    survivor.sessionGroups = []
     await expect(survivorSession.close('retry')).resolves.toBeUndefined()
   })
 
   it('propagates cleanup transport failures and lets close retry', async () => {
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    fake.commandError = new Error('TERM transport failed')
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    fake.signalError = new Error('TERM transport failed')
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     await expect(session.close('failure')).rejects.toThrow('TERM transport failed')
     handle.exit()
+    fake.sessionGroups = []
     await expect(session.close('retry')).resolves.toBeUndefined()
 
     const invalidTailHandle = new FakePtyHandle()
-    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), config())
+    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), 123, config())
     invalidTail.onData(Uint8Array.from([0xe2]))
     invalidTailHandle.exit()
     await expect(invalidTail.close('invalid tail')).rejects.toThrow('invalid UTF-8')
 
     const normalHandle = new FakePtyHandle()
     normalHandle.disconnectError = new Error('disconnect raced')
-    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), config())
+    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), 123, config())
     normalHandle.exit(7)
     await Promise.resolve()
     expect(normal.status()).toEqual({ kind: 'exited', exitCode: 7, signal: null })
     await expect(normal.close('already exited')).resolves.toBeUndefined()
   })
 
+  it('rejects invalid session groups and a shell handle that survives SDK kill', async () => {
+    const invalid = new FakeSandbox()
+    invalid.sessionGroups = [1]
+    const invalidSession = new E2BPtySession(invalid.sandbox, new FakePtyHandle().asHandle(), 123, config())
+    await expect(invalidSession.close('invalid group')).rejects.toThrow('invalid process group')
+
+    vi.useFakeTimers()
+    const survivor = new FakeSandbox()
+    survivor.sessionGroups = []
+    const survivorHandle = new FakePtyHandle()
+    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
+    const failed = expect(survivorSession.close('shell survived')).rejects.toThrow('surviving pid: 123')
+    await vi.advanceTimersByTimeAsync(100)
+    await failed
+    expect(survivor.killed).toEqual([123])
+  })
+
   it('kills a remotely live PTY after its host transport fails', async () => {
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const active = session.startSend({ text: '', submit: false })
     session.onData(Uint8Array.from([0xff]))
     await expect(active.done).rejects.toThrow('invalid UTF-8')
     expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
 
-    fake.onTerm = () => { handle.failExit(143) }
+    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
     await expect(session.close('transport failed')).rejects.toThrow('invalid UTF-8')
     expect(fake.commands).toContain('kill -TERM -- -123')
     expect(handle.disconnects).toBe(1)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 8b8a70838c..f05191a45b 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 3b3bfa88e7e6483decfcdec11355942ae4ff7403
-README.zh.md: 3ff9a51c60636dea5789f9dd11b04aa902b91d0c
+README.md: 066d35a099f560fe40fe629ede632c37535129f7
+README.zh.md: d3af14e8cc58c7d86331156358f78a0abbb24c39
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 3b3bfa88e7..066d35a099 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -6,8 +6,8 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 ## Behavior
 
-- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the SDK returns the command PID; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
-- **Linux process groups** — a quoted wrapper starts each argv under `setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of assuming the SDK command PID is the group id. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
 - **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 3ff9a51c60..d3af14e8cc 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -6,8 +6,8 @@
 
 ## 行为
 
-- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。SDK 返回命令 PID 之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
-- **Linux 进程组**：带引号保护的包装层会在 `setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会假设 SDK 命令 PID 就是进程组 ID。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
 - **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 86bdade589..3b9594a752 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -253,7 +253,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       try {
         this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
       } catch (error: unknown) {
-        await Promise.allSettled([handle.kill()])
+        try {
+          await this.rollbackUnpublishedGroup(sandbox, handle)
+        } catch (cleanupError: unknown) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'subprocess-e2b: process-group publication failed and rollback did not reach quiescence',
+          )
+        }
         throw error
       }
       this.readyState.resolve(handle)
@@ -361,6 +368,19 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
   }
 
+  private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
+    // The background command begins with `exec setsid`, so E2B's command PID is
+    // the provisional group id even before the private publication file can be
+    // trusted. Kill that group before the SDK-PID fallback, then prove no group
+    // member survived before rejecting startup.
+    try {
+      await this.signalGroup(sandbox, handle.pid, 'KILL')
+    } finally {
+      await handle.kill().catch(() => false)
+    }
+    while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
+  }
+
   private async terminateRemote(): Promise<void> {
     let handle: CommandHandle
     try {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 6be645a713..fd4cc97a83 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -89,6 +89,7 @@ class FakeSandbox {
   probeError: unknown
   signalError: unknown
   trapsTerm = false
+  delaysKill = false
   alive = true
   processGroupId = '4242\n'
   readonly processGroupReads: string[] = []
@@ -176,7 +177,7 @@ class FakeSandbox {
             this.signalError = undefined
             throw error
           }
-          this.alive = false
+          if (!this.delaysKill) this.alive = false
           this.handle.fail(137)
           return { exitCode: 0, stdout: '', stderr: '' }
         }
@@ -596,14 +597,13 @@ describe('E2BSubprocessHandle', () => {
   it('rejects invalid or absent process-group publication', async () => {
     const invalidGroup = new FakeSandbox()
     invalidGroup.processGroupId = 'not-a-pid\n'
-    vi.spyOn(invalidGroup.handle, 'kill').mockImplementation(async () => {
-      invalidGroup.handle.kills += 1
-      invalidGroup.finish()
-      return true
-    })
+    invalidGroup.delaysKill = true
+    invalidGroup.afterProbe = () => { invalidGroup.alive = false }
     const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
     expect(invalidGroup.handle.kills).toBe(1)
+    expect(invalidGroup.commandsSeen).toContain('kill -KILL -- -4242')
+    await expect(invalid.waitForExit()).resolves.toBe(true)
 
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
@@ -612,6 +612,35 @@ describe('E2BSubprocessHandle', () => {
     absentGroup.finish()
     await expect(absent.done).rejects.toThrow(/exited before publishing/)
     expect(absentGroup.handle.kills).toBe(1)
+    expect(absentGroup.commandsSeen).toContain('kill -KILL -- -4242')
+    await expect(absent.waitForExit()).resolves.toBe(true)
+  })
+
+  it('preserves publication and rollback failures when cleanup cannot be verified', async () => {
+    const fake = new FakeSandbox()
+    fake.processGroupId = 'not-a-pid\n'
+    fake.signalError = new Error('rollback signal failed')
+    fake.handle.killError = new Error('SDK kill failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/failed-rollback')
+
+    let failure: unknown
+    try {
+      await handle.done
+    } catch (error: unknown) {
+      failure = error
+    }
+    expect(failure).toBeInstanceOf(AggregateError)
+    if (!(failure instanceof AggregateError)) throw new Error('expected AggregateError')
+    expect(failure.message).toBe('subprocess-e2b: process-group publication failed and rollback did not reach quiescence')
+    const failures = Array.from(failure.errors as Iterable<unknown>)
+    expect(failures).toHaveLength(2)
+    expect(failures[0]).toBeInstanceOf(Error)
+    expect(failures[1]).toBeInstanceOf(Error)
+    if (!(failures[0] instanceof Error) || !(failures[1] instanceof Error)) throw new Error('expected nested errors')
+    expect(failures[0].message).toContain('invalid process-group id')
+    expect(failures[1].message).toBe('rollback signal failed')
+    expect(fake.handle.kills).toBe(1)
+    fake.finish()
   })
 
   it('waits for delayed process-group publication', async () => {

From 64b4669a742b975e717e1544316efee427925bad Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 18:38:45 +0800
Subject: [PATCH 106/262] docs(packages): fit merged group map budget

---
 packages/README.i18n.yaml | 4 ++--
 packages/README.md        | 4 ++--
 packages/README.zh.md     | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index b8320d8c19..a0827779db 100644
--- 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: c46a08f76f9f38f9620c03f05f28e7698487afc8
-README.zh.md: 65a5c6c88b9b37b3f948b11c6db778e42965643d
+README.md: 7dc52943e488a14e0c055ac72be0b2ad6f752455
+README.zh.md: bc3dbf0b4533d1d6adf6d49b0376a3dcdd6bfdb5
diff --git a/packages/README.md b/packages/README.md
index b2a870f516..125b466d72 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -6,7 +6,7 @@ Packages use the `@deepseek-ai/dsh-*` scope. Cordis `Service` subclasses and fun
 
 ## Hierarchy
 
-Packages live at `packages/<group>/<pkg>/`; groups are containers, while names remain `@deepseek-ai/dsh-<pkg>`. **Each group README is the canonical package/ctx-key map.**
+Groups contain packages at `packages/<group>/<pkg>/`; names remain `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
 
 | Group | Role | Release expectation |
 |---|---|---|
@@ -16,7 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
-| [`e2b/`](e2b/README.md) | E2B remote-runtime provider family | POC |
+| [`e2b/`](e2b/README.md) | E2B providers | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index c8079c3d03..1667c88273 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 层级结构
 
-包位于 `packages/<group>/<pkg>/`；组是容器，包名仍为 `@deepseek-ai/dsh-<pkg>`。**每个组 README 是规范的包／ctx 键映射。**
+组在 `packages/<group>/<pkg>/` 容纳包；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 是规范的包／ctx 键映射。**
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
@@ -16,7 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
-| [`e2b/`](e2b/README.md) | E2B 远程运行时提供方系列 | POC |
+| [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |

From 97496c3d00b4165dfb64d57b55d00e3462bedab4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 19:21:39 +0800
Subject: [PATCH 107/262] fix(e2b): close remaining remote lifecycle races

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   6 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   6 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  59 ++-
 .../e2b/code-runtime-e2b/README.i18n.yaml     |   4 +-
 packages/e2b/code-runtime-e2b/README.md       |   2 +-
 packages/e2b/code-runtime-e2b/README.zh.md    |   2 +-
 .../e2b/code-runtime-e2b/src/runner-source.ts |  17 +-
 .../code-runtime-e2b/tests/runtime.spec.ts    |  52 ++-
 packages/e2b/e2b/tests/composition.e2e.ts     |   3 +
 packages/e2b/lsp-e2b/README.i18n.yaml         |   6 -
 packages/e2b/lsp-e2b/README.md                |  47 --
 packages/e2b/lsp-e2b/README.zh.md             |  47 --
 packages/e2b/lsp-e2b/package.json             |  52 ---
 packages/e2b/lsp-e2b/src/index.ts             | 441 ------------------
 packages/e2b/lsp-e2b/src/invariant.ts         |  20 -
 packages/e2b/lsp-e2b/src/proxy-source.ts      |  55 ---
 packages/e2b/lsp-e2b/src/transport.ts         | 183 --------
 packages/e2b/lsp-e2b/tests/provider.spec.ts   | 418 -----------------
 packages/e2b/lsp-e2b/tests/transport.spec.ts  | 181 -------
 packages/e2b/lsp-e2b/tsconfig.json            |  20 -
 packages/e2b/pty-e2b/README.i18n.yaml         |   4 +-
 packages/e2b/pty-e2b/README.md                |   2 +-
 packages/e2b/pty-e2b/README.zh.md             |   2 +-
 packages/e2b/pty-e2b/src/session.ts           |  14 +-
 packages/e2b/pty-e2b/tests/session.spec.ts    |  44 +-
 26 files changed, 193 insertions(+), 1498 deletions(-)
 delete mode 100644 packages/e2b/lsp-e2b/README.i18n.yaml
 delete mode 100644 packages/e2b/lsp-e2b/README.md
 delete mode 100644 packages/e2b/lsp-e2b/README.zh.md
 delete mode 100644 packages/e2b/lsp-e2b/package.json
 delete mode 100644 packages/e2b/lsp-e2b/src/index.ts
 delete mode 100644 packages/e2b/lsp-e2b/src/invariant.ts
 delete mode 100644 packages/e2b/lsp-e2b/src/proxy-source.ts
 delete mode 100644 packages/e2b/lsp-e2b/src/transport.ts
 delete mode 100644 packages/e2b/lsp-e2b/tests/provider.spec.ts
 delete mode 100644 packages/e2b/lsp-e2b/tests/transport.spec.ts
 delete mode 100644 packages/e2b/lsp-e2b/tsconfig.json

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index beb49fba76..04ebe420ac 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: efb91fc166f36dc8fb047d686e8cd82d93b9af6a
-2026-07-27-e2b-remote-runtime-poc.zh.md: eb14cccc284d38cdc5cc704512b6899621a9a840
+2026-07-27-e2b-remote-runtime-poc.md: 4e6414b7d919d765712ac9314ce73a69c5c6344e
+2026-07-27-e2b-remote-runtime-poc.zh.md: 4d39ed7eb07cdd17c5bfa9155bc7efabaa798117
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index efb91fc166..4e6414b7d9 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -32,7 +32,7 @@ E2B owns the mutable filesystem, command and Bash processes, PTY shell and termi
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP installs a bounded remote source reader, while Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly and carries send identity across asynchronous foreground-group lookup. LSP installs a bounded remote source reader that walks no-follow directory descriptors beneath the canonical workspace. Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors, and gives each controller a process group that is killed before its inherited pipes drain. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -40,9 +40,9 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 ## Verification
 
-Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signals/default-environment scrubbing/terminal-session cleanup, stable bounded LSP source reads, Code Runtime binding and descriptor isolation, worker-pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signal identity/default-environment scrubbing/terminal-session cleanup, descriptor-walked bounded LSP source reads, Code Runtime binding and descriptor isolation, worker and descendant-held pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing and process-tree cleanup, stable bounded LSP source reads, Code Runtime host bindings and descriptor-isolated output accounting, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index eb14cccc28..4d39ed7eb0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -32,7 +32,7 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 会安装一个有界的远程源码读取器；Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调，并在异步查找前台进程组的过程中保留发送操作身份。LSP 会安装一个有界的远程源码读取器，通过不跟随符号链接打开的目录描述符在规范化工作区下逐级遍历。Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内，并为每个 controller 分配一个进程组，在 controller 继承的管道排空前终止该组。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -40,9 +40,9 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 ## 验证
 
-聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号／默认环境清理／终端会话清理、稳定且有界的 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号身份／默认环境清理／终端会话清理、基于描述符逐级遍历的有界 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道及后代进程所持管道的排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理与进程树清理、稳定且有界的 LSP 源码读取、Code Runtime 宿主绑定与描述符隔离的输出记账、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 4f2401d2c7..a997752711 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -147,18 +147,23 @@ try {
     workspaceRoot: process.cwd(),
   })
 
-  const swappedSource = await ctx.fs.resolve('swapped-source.ts')
-  const swappedSourcePath = posix.join(process.cwd(), 'swapped-source.ts')
-  await ctx.fs.writeText(swappedSource, 'const safe = true\n', { kind: 'createIfAbsent' })
+  const swappedParentPath = posix.join(process.cwd(), 'swapped-parent')
+  const swappedSourcePath = posix.join(swappedParentPath, 'source.ts')
+  const swappedOutsidePath = '/tmp/dsh-e2b-lsp-outside'
+  await sandbox.commands.run(
+    `mkdir -p -- ${quoteE2BShellArg(swappedParentPath)} ${quoteE2BShellArg(swappedOutsidePath)} && printf 'const safe = true\\n' > ${quoteE2BShellArg(swappedSourcePath)} && printf 'const outside = true\\n' > ${quoteE2BShellArg(posix.join(swappedOutsidePath, 'source.ts'))}`,
+  )
   const remoteCommands = sandbox.commands as unknown as {
     run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
   }
   const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   let containmentFaultInjected = false
   remoteCommands.run = async (command, options) => {
-    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-source.ts')) {
+    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-parent/source.ts')) {
       containmentFaultInjected = true
-      await runRemoteCommand(`rm -f -- ${quoteE2BShellArg(swappedSourcePath)} && ln -s -- /etc/hosts ${quoteE2BShellArg(swappedSourcePath)}`)
+      await runRemoteCommand(
+        `rm -rf -- ${quoteE2BShellArg(swappedParentPath)} && ln -s -- ${quoteE2BShellArg(swappedOutsidePath)} ${quoteE2BShellArg(swappedParentPath)}`,
+      )
     }
     return await runRemoteCommand(command, options)
   }
@@ -166,7 +171,7 @@ try {
   try {
     await ctx.lsp.query({
       operation: 'hover',
-      filePath: 'swapped-source.ts',
+      filePath: 'swapped-parent/source.ts',
       position: { line: 0, character: 1 },
       workspaceRoot: process.cwd(),
     })
@@ -200,8 +205,28 @@ try {
     text: "printf 'PTY-你好\\n'",
     submit: true,
   }).done
+  const foregroundLookup = Promise.withResolvers<undefined>()
+  let delayedForegroundLookup = false
+  remoteCommands.run = async (command, options) => {
+    if (!delayedForegroundLookup && command.startsWith('ps -o tpgid=')) {
+      delayedForegroundLookup = true
+      await foregroundLookup.promise
+    }
+    return await runRemoteCommand(command, options)
+  }
+  const staleInterrupt = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 0.2', submit: true })
+  if (!staleInterrupt.cancel()) throw new Error('E2B PTY refused the stale-interrupt probe cancellation')
+  await staleInterrupt.done
   const sleeping = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
-  await new Promise(resolveDelay => setTimeout(resolveDelay, 150))
+  foregroundLookup.resolve(undefined)
+  const interruptIdentitySafe = await Promise.race([
+    sleeping.done.then(() => false),
+    new Promise<true>(resolveDelay => setTimeout(() => { resolveDelay(true) }, 300)),
+  ])
+  remoteCommands.run = runRemoteCommand
+  if (!delayedForegroundLookup || !interruptIdentitySafe) {
+    throw new Error('E2B PTY stale interrupt affected its successor send')
+  }
   const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
   const interrupted = await sleeping.done
   const stubborn = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -296,6 +321,23 @@ try {
     `,
     bindings: [],
   })
+  const descendantPipe = await ctx.codeRuntime.run({
+    program: `
+      const childProcess = await import('node:child_process')
+      const child = childProcess.spawn(
+        process.execPath,
+        ['-e', 'setInterval(() => {}, 1000)', 'dsh-code-runtime-descendant'],
+        { stdio: ['ignore', 'inherit', 'inherit'] },
+      )
+      return child.pid > 0
+    `,
+    bindings: [],
+  })
+  const descendantProcesses = await sandbox.commands.list()
+  const descendantCleanup = !descendantProcesses.some(processInfo =>
+    JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-code-runtime-descendant'),
+  )
+  if (!descendantCleanup) throw new Error('E2B Code Runtime left a pipe-holding descendant alive')
   const timedOut = await ctx.codeRuntime.run({
     program: 'await new Promise(() => {})',
     bindings: [],
@@ -340,6 +382,7 @@ try {
       echo: terminalEcho,
       signal: terminalSignal,
       interrupted,
+      interruptIdentitySafe,
       treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
@@ -348,6 +391,8 @@ try {
     nativeOutput,
     descriptorOutput,
     inheritedOutput,
+    descendantPipe,
+    descendantCleanup,
     timedOut,
     aborted,
     oversizedBoot,
diff --git a/packages/e2b/code-runtime-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
index ba43d787b8..eb4e75f297 100644
--- a/packages/e2b/code-runtime-e2b/README.i18n.yaml
+++ b/packages/e2b/code-runtime-e2b/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/e2b/code-runtime-e2b/README.md
-README.md: 171e63a8c1ca70deb63e9860f5088b83401a37d0
-README.zh.md: b70984e765d32985436c15dd543263cc06a25715
+README.md: a8623f95d16b54b29e53bb9cf2c528b36f121283
+README.zh.md: 2b4a37864e3c6755a74f0d2ef6ce38aa39aae24b
diff --git a/packages/e2b/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
index 171e63a8c1..a8623f95d1 100644
--- a/packages/e2b/code-runtime-e2b/README.md
+++ b/packages/e2b/code-runtime-e2b/README.md
@@ -19,7 +19,7 @@ Every value is a positive safe integer. `maxOutputBytes` is at least four bytes,
 
 ## Execution and bridge contract
 
-Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; worker and controller pipes drain before the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
+Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller process group whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; completion kills the controller group before draining its pipes and emitting the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in either managed group stop with the run.
 
 The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
 
diff --git a/packages/e2b/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
index b70984e765..2b4a37864e 100644
--- a/packages/e2b/code-runtime-e2b/README.zh.md
+++ b/packages/e2b/code-runtime-e2b/README.zh.md
@@ -19,7 +19,7 @@
 
 ## 执行与桥接契约
 
-设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；worker 与 controller 管道会在发出终结帧前排空。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
+设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller 进程组，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；运行结算会先终止 controller 进程组，再排空其管道并发出终结帧。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此任一受管组内的普通子进程会随本次运行一同停止。
 
 由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
 
diff --git a/packages/e2b/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
index e5cf6ebefa..527f21114e 100644
--- a/packages/e2b/code-runtime-e2b/src/runner-source.ts
+++ b/packages/e2b/code-runtime-e2b/src/runner-source.ts
@@ -35,6 +35,18 @@ const waitForChildExit = child => {
   return new Promise(resolve => { child.once('exit', resolve) })
 }
 
+const killControllerGroup = child => {
+  if (process.platform !== 'win32' && Number.isSafeInteger(child.pid)) {
+    try {
+      process.kill(-child.pid, 'SIGKILL')
+    } catch (error) {
+      if (!error || typeof error !== 'object' || error.code !== 'ESRCH') throw error
+    }
+    return
+  }
+  child.kill('SIGKILL')
+}
+
 const jsonStringBytes = text => Buffer.byteLength(JSON.stringify(text))
 
 const truncateLog = (text, available) => {
@@ -74,7 +86,7 @@ const runLauncher = () => {
           const stdoutDrained = waitForPipeDrain(current.stdout)
           const stderrDrained = waitForPipeDrain(current.stderr)
           const exited = waitForChildExit(current)
-          current.kill('SIGKILL')
+          killControllerGroup(current)
           await Promise.all([exited, stdoutDrained, stderrDrained])
         })
       : Promise.resolve()
@@ -112,6 +124,7 @@ const runLauncher = () => {
     maxOutputBytes = message.maxOutputBytes
     controller = fork(fileURLToPath(import.meta.url), [], {
       env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
+      detached: process.platform !== 'win32',
       execArgv: [],
       stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
     })
@@ -173,7 +186,7 @@ const runLauncher = () => {
         })
     }
   })
-  input.on('close', () => { if (controller && !settling) controller.kill('SIGKILL') })
+  input.on('close', () => { if (controller && !settling) killControllerGroup(controller) })
 }
 
 const runController = () => {
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
index 9743c361c5..f99485a929 100644
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
@@ -1,8 +1,9 @@
 import { spawn } from 'node:child_process'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { access, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PassThrough, Writable } from 'node:stream'
+import { setTimeout as delay } from 'node:timers/promises'
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import type { Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -271,6 +272,55 @@ describe('E2BCodeRuntime', () => {
     expect(Buffer.byteLength(nativeOutput)).toBe(expectedBytes)
   })
 
+  it.skipIf(process.platform === 'win32')('reaps descendant-held controller pipes before completion', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-descendant-'))
+    const marker = join(directory, 'started')
+    const release = join(directory, 'release')
+    const childSource = `
+      const fs = require('node:fs')
+      fs.writeFileSync(${JSON.stringify(marker)}, 'started')
+      const timer = setInterval(() => {
+        if (fs.existsSync(${JSON.stringify(release)})) clearInterval(timer)
+      }, 10)
+    `
+    let running: ReturnType<typeof runInstalledRunner> | undefined
+    try {
+      running = runInstalledRunner(`
+        const fs = await import('node:fs')
+        const childProcess = await import('node:child_process')
+        childProcess.spawn(process.execPath, ['-e', ${JSON.stringify(childSource)}], {
+          stdio: ['ignore', 'inherit', 'inherit'],
+        })
+        while (!fs.existsSync(${JSON.stringify(marker)})) await new Promise(resolve => setTimeout(resolve, 5))
+        return true
+      `)
+      const deadline = Date.now() + 2_000
+      for (;;) {
+        try {
+          await access(marker)
+          break
+        } catch (error: unknown) {
+          if (Date.now() >= deadline) throw error
+          await delay(10)
+        }
+      }
+      const completed = await Promise.race([
+        running.then(() => true),
+        delay(500).then(() => false),
+      ])
+      await writeFile(release, '')
+      const { messages, stderr } = await running
+
+      expect(completed).toBe(true)
+      expect(stderr).toBe('')
+      expect(messages.at(-1)).toEqual({ type: 'done', value: [true] })
+    } finally {
+      await writeFile(release, '').catch(() => undefined)
+      await running?.catch(() => undefined)
+      await rm(directory, { recursive: true, force: true })
+    }
+  })
+
   it('prepares the remote runner and returns logs and a lossless completion', async () => {
     const handle = new FakeHandle((message, current) => {
       if ((message as { type?: string }).type !== 'boot') return
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 4f4ea19eb9..1bfbab1e8e 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -109,12 +109,15 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
         signal: { delivered: true },
         interrupted: { sessionStatus: { kind: 'running' } },
+        interruptIdentitySafe: true,
         treeCleanup: true,
       },
       hostileOutput: { error: { kind: 'output-limit' } },
       nativeOutput: { error: { kind: 'output-limit' } },
       descriptorOutput: { error: { kind: 'output-limit' } },
       inheritedOutput: { error: { kind: 'output-limit' } },
+      descendantPipe: { value: true, logs: [] },
+      descendantCleanup: true,
       timedOut: { error: { kind: 'timeout' } },
       aborted: { error: { kind: 'abort', message: 'live abort' } },
       oversizedBoot: { error: { kind: 'worker-exit' } },
diff --git a/packages/e2b/lsp-e2b/README.i18n.yaml b/packages/e2b/lsp-e2b/README.i18n.yaml
deleted file mode 100644
index 066820d9fd..0000000000
--- a/packages/e2b/lsp-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/e2b/lsp-e2b/README.md
-README.md: 6cc118767adc5d2df855b009f48faab596928fb7
-README.zh.md: b384e9efd0e5c62b0ee6e69f73755e1bbe0192df
diff --git a/packages/e2b/lsp-e2b/README.md b/packages/e2b/lsp-e2b/README.md
deleted file mode 100644
index 6cc118767a..0000000000
--- a/packages/e2b/lsp-e2b/README.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# @deepseek-ai/dsh-lsp-e2b
-
-English | [中文](README.zh.md)
-
-Generic E2B language-server backend for [`ctx.lsp`](../../lsp/lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
-
-## Plugin and configuration
-
-The `lsp-e2b` plugin injects `e2b`, `lsp`, and the concrete `dsh-subprocess-e2b` service. `servers` is a non-empty provider-id table:
-
-| Server key | Default | Meaning |
-|---|---|---|
-| `command` | required | Remote executable, absolute or resolved on the sandbox PATH at load. |
-| `args` | `[]` | Remote server arguments. |
-| `env` | `{}` | Explicit environment entries passed through the subprocess adapter. |
-| `extensionToLanguage` | required | Lowercase leading-dot extension to LSP language id. |
-| `initializationOptions` / `configuration` | `null` / `null` | Static initialize options and `workspace/configuration` answer. |
-| `maxMessageBytes` | `16000000` | Largest LSP message accepted from the server. |
-| `maxStderrBytes` | `1000000` | Retained raw server stderr tail. |
-| `maxDocumentBytes` | `4000000` | Largest remote source opened for one query. |
-| `shutdownTimeoutMs` | `5000` | Graceful protocol-shutdown budget. |
-| `killGraceMs` | `2000` | Request-cancel and TERM-to-KILL grace. |
-
-Provider ids and commands are non-empty; numeric bounds are positive safe integers, and timer values cannot exceed Node's maximum timer delay. Setup uploads one owner-private proxy under `ctx.e2b.runtimeRoot`, resolves Node and every configured server executable remotely, then registers all providers atomically.
-
-## Remote protocol and filesystem
-
-E2B command callbacks are text, while LSP is byte-framed. The installed proxy therefore base64-frames raw server stdout, stderr, and stdin as newline-delimited ASCII JSON; the host validates and decodes every frame before handing bytes to the shared `LspInstance` protocol engine. `initialize.processId` is `null` because host and server do not share a process namespace.
-
-One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, then uses a remote helper to open the canonical source without following the final symlink and to verify and read one stable descriptor. The helper requires a regular file and reads at most `maxDocumentBytes + 1` bytes before strict UTF-8 decoding. Queries use the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
-
-The subprocess adapter owns process groups and escalation, so cancellation and disposal await remote server quiescence. The host owns LSP request ids, pending requests, provider queues, and normalized results.
-
-## Model Experience
-
-Indirectly, through `@deepseek-ai/dsh-tool-lsp`, which exposes normalized semantic navigation and hover results without changing its model-facing schema.
-
-#### KV Cache effect
-
-No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **Configured servers only** — this package does not install language servers, select presets, or synchronize a host workspace into E2B.
-- **Host protocol state is not reconnectable** — retaining a sandbox does not restore provider queues, JSON-RPC requests, subprocess handles, or document lifecycle state.
-- **SDK output retention remains** — ASCII framing preserves protocol bytes, but E2B and the subprocess adapter still retain callback output in host memory.
-- **Sandbox policy is template-owned** — this provider adds no volume, snapshot, credential, or network-policy layer.
diff --git a/packages/e2b/lsp-e2b/README.zh.md b/packages/e2b/lsp-e2b/README.zh.md
deleted file mode 100644
index b384e9efd0..0000000000
--- a/packages/e2b/lsp-e2b/README.zh.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# @deepseek-ai/dsh-lsp-e2b
-
-[English](README.md) | 中文
-
-用于 [`ctx.lsp`](../../lsp/lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
-
-## 插件与配置
-
-`lsp-e2b` 插件注入 `e2b`、`lsp` 和具体的 `dsh-subprocess-e2b` 服务。`servers` 是一张非空的提供方 id 表：
-
-| 服务器键 | 默认值 | 含义 |
-|---|---|---|
-| `command` | 必填 | 远程可执行文件：绝对路径，或在加载时通过沙箱 PATH 解析。 |
-| `args` | `[]` | 远程服务器参数。 |
-| `env` | `{}` | 经由进程管理适配器传入的显式环境条目。 |
-| `extensionToLanguage` | 必填 | 小写、以点开头的扩展名到 LSP language id 的映射。 |
-| `initializationOptions` / `configuration` | `null` / `null` | 静态初始化选项和 `workspace/configuration` 应答。 |
-| `maxMessageBytes` | `16000000` | 从服务器接受的 LSP 消息大小上限。 |
-| `maxStderrBytes` | `1000000` | 保留的服务器原始 stderr 尾部上限。 |
-| `maxDocumentBytes` | `4000000` | 单次查询可打开的最大远程源文件。 |
-| `shutdownTimeoutMs` | `5000` | 协议优雅关闭预算。 |
-| `killGraceMs` | `2000` | 请求取消与 TERM 到 KILL 升级的宽限期。 |
-
-提供方 id 与命令必须非空；数值上限必须是正的安全整数，定时器取值不得超过 Node 的最大定时器延迟。设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个仅供所有者使用的私有代理，在远程解析 Node 和每个已配置服务器的可执行文件，再以原子方式注册所有提供方。
-
-## 远程协议与文件系统
-
-E2B 命令回调交付的是文本，而 LSP 按字节分帧。因此，已安装的代理会把服务器 stdout、stderr 和 stdin 的原始字节进行 base64 编码，封装为以换行分隔的 ASCII JSON 帧；宿主会验证并解码每一帧，再把字节交给共享的 `LspInstance` 协议引擎。`initialize.processId` 为 `null`，因为宿主与服务器不共享进程命名空间。
-
-每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，再由远程 helper 以不跟随最终符号链接的方式打开规范化源文件，并在同一个稳定描述符上完成验证与读取。该 helper 要求目标为普通文件，最多读取 `maxDocumentBytes + 1` 字节，随后执行严格的 UTF-8 解码。查询采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
-
-进程管理适配器负责进程组和终止升级，因此取消与资源释放都会等待远程服务器完全停稳。宿主负责 LSP 请求 id、待完成请求、提供方队列和规范化结果。
-
-## 模型体验
-
-通过 `@deepseek-ai/dsh-tool-lsp` 间接影响模型；该包会公开规范化的语义导航与悬停结果，而不改变其面向模型的 schema。
-
-#### KV Cache 影响
-
-不会直接失效；请求前缀变更由 `dsh-tool-lsp` 负责。
-
-## 已知限制与暂缓工作
-
-- **仅支持已配置的服务器**：本包不会安装语言服务器、选择 preset，或把宿主工作区同步到 E2B。
-- **宿主协议状态不可重连**：保留沙箱并不会恢复提供方队列、JSON-RPC 请求、进程管理句柄或文档生命周期状态。
-- **SDK 仍会保留输出**：ASCII 分帧能保留协议字节，但 E2B 和进程管理适配器仍会在宿主内存中保留回调输出。
-- **沙箱策略归模板负责**：本提供方不会额外增加卷、快照、凭据或网络策略层。
diff --git a/packages/e2b/lsp-e2b/package.json b/packages/e2b/lsp-e2b/package.json
deleted file mode 100644
index 0671341f3c..0000000000
--- a/packages/e2b/lsp-e2b/package.json
+++ /dev/null
@@ -1,52 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-lsp-e2b",
-  "description": "E2B language-server provider for DeepSeek Harness",
-  "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"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@deepseek-ai/dsh-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-lsp": "^0.0.1",
-    "@deepseek-ai/dsh-lsp-local": "^0.0.1",
-    "@deepseek-ai/dsh-subprocess": "^0.0.1",
-    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-timeout": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-e2b": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-lsp": "workspace:^",
-    "@deepseek-ai/dsh-lsp-local": "workspace:^",
-    "@deepseek-ai/dsh-subprocess": "workspace:^",
-    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
-    "@deepseek-ai/dsh-timeout": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
-  }
-}
diff --git a/packages/e2b/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
deleted file mode 100644
index fa6b3729da..0000000000
--- a/packages/e2b/lsp-e2b/src/index.ts
+++ /dev/null
@@ -1,441 +0,0 @@
-/** E2B filesystem and process backend for the harness LSP capability seam. */
-
-import { Buffer } from 'node:buffer'
-import { posix } from 'node:path'
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import {
-  FileType,
-  quoteE2BShellArg,
-  resolveE2BExecutable,
-} from '@deepseek-ai/dsh-e2b'
-import type { Sandbox } from '@deepseek-ai/dsh-e2b'
-import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
-import type { LspProvider, LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
-import { LspInstance } from '@deepseek-ai/dsh-lsp-local'
-import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { LSP_PROXY_SOURCE } from './proxy-source.ts'
-import { E2BLspTransport } from './transport.ts'
-
-export { E2BLspTransport } from './transport.ts'
-
-/** Cordis plugin name. */
-export const name = 'lsp-e2b'
-/** Services required by the remote provider. */
-export const inject = ['e2b', 'lsp', 'subprocess']
-
-const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
-const DEFAULT_MAX_STDERR_BYTES = 1_000_000
-const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000
-const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
-const DEFAULT_KILL_GRACE_MS = 2_000
-
-/* jscpd:ignore-start -- Loader requires each backend to expose its own statically walkable server schema. */
-/** One configured language server inside the shared E2B sandbox. */
-export interface LspE2BServerConfig {
-  /** Remote executable, absolute or resolved on the sandbox PATH. */
-  command: string
-  /** Lowercase leading-dot extension to LSP language id. */
-  extensionToLanguage: Record<string, string>
-  /** Remote executable arguments. */
-  args?: string[]
-  /** Explicit remote environment overrides. */
-  env?: Record<string, string>
-  /** Static `initialize` options. */
-  initializationOptions?: unknown
-  /** Static answer to every `workspace/configuration` item. */
-  configuration?: unknown
-  /** Largest LSP message accepted from the server. */
-  maxMessageBytes?: number
-  /** Largest remote stderr tail retained for diagnostics. */
-  maxStderrBytes?: number
-  /** Largest remote source opened for one query. */
-  maxDocumentBytes?: number
-  /** Graceful LSP shutdown budget. */
-  shutdownTimeoutMs?: number
-  /** Request-cancel and TERM-to-KILL grace. */
-  killGraceMs?: number
-}
-
-/** Plugin configuration. */
-export interface Config {
-  /** Non-empty provider-id to remote-server table. */
-  servers: Record<string, LspE2BServerConfig>
-}
-
-type ResolvedServerConfig = Required<LspE2BServerConfig>
-
-const ServerConfig: z<LspE2BServerConfig> = z.object({
-  command: z.string().required(),
-  args: z.array(String).default([]),
-  env: z.dict(String).default({}),
-  extensionToLanguage: z.dict(String).required(),
-  initializationOptions: z.any().default(null),
-  configuration: z.any().default(null),
-  maxMessageBytes: z.number().default(DEFAULT_MAX_MESSAGE_BYTES),
-  maxStderrBytes: z.number().default(DEFAULT_MAX_STDERR_BYTES),
-  maxDocumentBytes: z.number().default(DEFAULT_MAX_DOCUMENT_BYTES),
-  shutdownTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_SHUTDOWN_TIMEOUT_MS),
-  killGraceMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_KILL_GRACE_MS),
-})
-
-/** Schemastery plugin configuration. */
-export const Config: z<Config> = z.object({
-  servers: z.dict(ServerConfig).required(),
-})
-/* jscpd:ignore-end */
-
-interface RemoteSource {
-  canonicalPath: string
-  text: string
-}
-
-interface RemoteSourceReadResponse {
-  kind: 'ok' | 'not-file' | 'oversize' | 'grew' | 'open-error'
-  data?: string
-  size?: number
-  message?: string
-}
-
-const SOURCE_READER_SOURCE = String.raw`
-/* dsh-e2b-source-reader */
-const fs = require('node:fs')
-const path = process.argv[1]
-const maxBytes = Number(process.argv[2])
-let descriptor
-let response
-try {
-  descriptor = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
-  const info = fs.fstatSync(descriptor)
-  if (!info.isFile()) response = { kind: 'not-file' }
-  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
-  else {
-    const chunks = []
-    let total = 0
-    while (total <= maxBytes) {
-      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
-      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
-      if (bytesRead === 0) break
-      chunks.push(chunk.subarray(0, bytesRead))
-      total += bytesRead
-    }
-    response = total > maxBytes
-      ? { kind: 'grew' }
-      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
-  }
-} catch (error) {
-  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
-}
-if (descriptor !== undefined) fs.closeSync(descriptor)
-process.stdout.write(JSON.stringify(response))
-`
-
-function abortReason(signal: AbortSignal): unknown {
-  try {
-    signal.throwIfAborted()
-  } catch (error: unknown) {
-    return error
-  }
-  return new DOMException('The operation was aborted', 'AbortError')
-}
-
-function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (signal === undefined) return promise
-  // AbortSignal permits opaque reasons, and callers observe the exact reason.
-  // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
-  if (signal.aborted) return Promise.reject(abortReason(signal))
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = (): void => {
-      cleanup()
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Preserve the signal's exact opaque reason.
-      reject(abortReason(signal))
-    }
-    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    void promise.then(
-      (value) => { cleanup(); resolve(value) },
-      (error: unknown) => { cleanup(); reject(error instanceof Error ? error : new Error(String(error))) },
-    )
-  })
-}
-
-function validateServerConfig(providerId: string, config: ResolvedServerConfig): void {
-  if (config.command.length === 0) throw new Error(`lsp-e2b: servers.${providerId}.command must be non-empty`)
-  for (const name of ['maxMessageBytes', 'maxStderrBytes', 'maxDocumentBytes', 'shutdownTimeoutMs', 'killGraceMs'] as const) {
-    const value = config[name]
-    if (!Number.isSafeInteger(value) || value <= 0 || (name.endsWith('Ms') && value > MAX_TIMER_DELAY_MS)) {
-      throw new Error(`lsp-e2b: servers.${providerId}.${name} must be a positive safe integer${name.endsWith('Ms') ? ` no greater than ${MAX_TIMER_DELAY_MS}` : ''}`)
-    }
-  }
-}
-
-async function canonicalRemotePath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
-  signal?.throwIfAborted()
-  const result = await sandbox.commands.run(`realpath -e -- ${quoteE2BShellArg(path)}`, signal === undefined ? {} : { signal })
-  signal?.throwIfAborted()
-  const canonical = result.stdout.trim()
-  if (!posix.isAbsolute(canonical) || canonical.includes('\n')) throw new Error(`remote path ${JSON.stringify(path)} did not resolve canonically`)
-  return canonical
-}
-
-/**
- * Canonicalize and validate one workspace inside E2B.
- * @param sandbox - Shared sandbox that owns the workspace.
- * @param workspaceRoot - Remote workspace path supplied by the query.
- * @param signal - Optional query cancellation signal.
- * @returns The canonical remote directory path.
- */
-export async function canonicalizeE2BWorkspace(
-  sandbox: Sandbox,
-  workspaceRoot: string,
-  signal?: AbortSignal,
-): Promise<string> {
-  const canonical = await canonicalRemotePath(sandbox, workspaceRoot, signal)
-  const info = await sandbox.files.getInfo(canonical, signal === undefined ? {} : { signal })
-  signal?.throwIfAborted()
-  if (info.type !== FileType.DIR) throw new Error(`workspace root ${JSON.stringify(workspaceRoot)} is not a directory`)
-  return canonical
-}
-
-/**
- * Resolve, contain, and read one UTF-8 query source inside E2B.
- * @param sandbox - Shared sandbox that owns the source.
- * @param filePath - Absolute path or path relative to the canonical workspace.
- * @param workspace - Canonical remote workspace directory.
- * @param maxDocumentBytes - Maximum bytes read through the stable remote handle.
- * @param nodeExecutable - Resolved remote Node executable used by the bounded reader.
- * @param signal - Optional query cancellation signal.
- * @returns The canonical source path and decoded text.
- */
-export async function readE2BSource(
-  sandbox: Sandbox,
-  filePath: string,
-  workspace: string,
-  maxDocumentBytes: number,
-  nodeExecutable: string,
-  signal?: AbortSignal,
-): Promise<RemoteSource> {
-  const requested = posix.isAbsolute(filePath) ? filePath : posix.resolve(workspace, filePath)
-  const canonicalPath = await canonicalRemotePath(sandbox, requested, signal)
-  const relative = posix.relative(workspace, canonicalPath)
-  if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
-    throw new Error(`source ${JSON.stringify(filePath)} resolves outside the workspace`)
-  }
-  const command = [
-    quoteE2BShellArg(nodeExecutable),
-    '--input-type=commonjs',
-    '-e',
-    quoteE2BShellArg(SOURCE_READER_SOURCE),
-    quoteE2BShellArg(canonicalPath),
-    String(maxDocumentBytes),
-  ].join(' ')
-  const result = await sandbox.commands.run(command, signal === undefined ? {} : { signal })
-  signal?.throwIfAborted()
-  let response: RemoteSourceReadResponse
-  try {
-    response = JSON.parse(result.stdout) as RemoteSourceReadResponse
-  } catch (error: unknown) {
-    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`, { cause: error })
-  }
-  if (response.kind === 'not-file') throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
-  if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
-    throw new Error(`source ${JSON.stringify(filePath)} is ${response.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-  }
-  if (response.kind === 'grew') {
-    throw new Error(`source ${JSON.stringify(filePath)} grew past the ${maxDocumentBytes}-byte limit while reading`)
-  }
-  if (response.kind === 'open-error' && typeof response.message === 'string') {
-    throw new Error(`source ${JSON.stringify(filePath)} could not be opened safely: ${response.message}`)
-  }
-  if (response.kind !== 'ok' || typeof response.data !== 'string') {
-    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`)
-  }
-  const bytes = Buffer.from(response.data, 'base64')
-  if (bytes.toString('base64') !== response.data || bytes.length > maxDocumentBytes) {
-    throw new Error(`source ${JSON.stringify(filePath)} reader returned invalid bounded bytes`)
-  }
-  let text: string
-  try {
-    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
-  } catch (error: unknown) {
-    throw new Error(`source ${JSON.stringify(filePath)} is not valid UTF-8 text`, { cause: error })
-  }
-  return { canonicalPath, text }
-}
-
-/**
- * Encode one absolute remote Linux path as a host-independent file URI.
- * @param path - Canonical POSIX path inside E2B.
- * @returns The equivalent percent-encoded file URI.
- */
-export function e2bFileUri(path: string): string {
-  if (!posix.isAbsolute(path)) throw new Error(`lsp-e2b: expected an absolute remote path, received ${JSON.stringify(path)}`)
-  return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
-}
-
-/* jscpd:ignore-start -- Provider identity mirrors the seam while remote source and process ownership stay local. */
-/** One pooled remote provider with an isolated server per canonical workspace. */
-export class E2BLspProvider implements LspProvider {
-  readonly id: LspProviderId
-  readonly extensionToLanguage: Readonly<Record<string, string>>
-  private readonly instances = new Map<string, LspInstance>()
-  private readonly queues = new Map<string, Promise<void>>()
-  private disposed = false
-
-  constructor(
-    providerId: string,
-    private readonly sandbox: Sandbox,
-    private readonly subprocess: E2BSubprocessService,
-    private readonly config: ResolvedServerConfig,
-    private readonly executable: string,
-    private readonly nodeExecutable: string,
-    private readonly proxyPath: string,
-  ) {
-    this.id = LspProviderId(providerId)
-    this.extensionToLanguage = config.extensionToLanguage
-  }
-  /* jscpd:ignore-end */
-
-  async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    this.assertActive(signal)
-    const workspace = await canonicalizeE2BWorkspace(this.sandbox, request.workspaceRoot, signal)
-    this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
-      this.assertActive(signal)
-      const source = await readE2BSource(
-        this.sandbox,
-        request.filePath,
-        workspace,
-        this.config.maxDocumentBytes,
-        this.nodeExecutable,
-        signal,
-      )
-      this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
-      try {
-        return await instance.query(request, source, signal)
-      } catch (error: unknown) {
-        if (!instance.isTransportFailure(error)) throw error
-        await instance.dispose()
-        this.evict(workspace, instance)
-        this.assertActive(signal)
-        instance = this.instanceFor(workspace)
-        return await instance.query(request, source, signal)
-      } finally {
-        if (instance.dead) {
-          await instance.dispose()
-          this.evict(workspace, instance)
-        }
-      }
-    })
-  }
-
-  /* jscpd:ignore-start -- Queue and pooling semantics are shared; transport failure and disposal identities differ. */
-  /** Stop accepting work and await every remote server and queued query. */
-  async disposeAll(): Promise<void> {
-    this.disposed = true
-    const instances = [...this.instances.values()]
-    const queues = [...this.queues.values()]
-    this.instances.clear()
-    await Promise.all([...instances.map(instance => instance.dispose()), ...queues])
-    this.queues.clear()
-  }
-
-  private assertActive(signal?: AbortSignal): void {
-    if (this.disposed) throw new LspError('lsp-e2b provider is disposed', 'LSP_DISPOSED')
-    signal?.throwIfAborted()
-  }
-
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
-    const previous = this.queues.get(workspace) ?? Promise.resolve()
-    const result = abortable(previous, signal).then(run)
-    const tail = previous.then(() => result).then(() => undefined, () => undefined)
-    this.queues.set(workspace, tail)
-    void tail.then(() => { if (this.queues.get(workspace) === tail) this.queues.delete(workspace) })
-    return result
-  }
-
-  private instanceFor(workspace: string): LspInstance {
-    this.assertActive()
-    const existing = this.instances.get(workspace)
-    if (existing !== undefined) return existing
-    const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
-    return created
-  }
-  /* jscpd:ignore-end */
-
-  private createInstance(workspace: string): LspInstance {
-    return new LspInstance({
-      command: this.executable,
-      args: this.config.args,
-      cwd: workspace,
-      env: this.config.env,
-      configuration: this.config.configuration,
-      initializationOptions: this.config.initializationOptions,
-      maxMessageBytes: this.config.maxMessageBytes,
-      maxStderrBytes: this.config.maxStderrBytes,
-      shutdownTimeoutMs: this.config.shutdownTimeoutMs,
-      killGraceMs: this.config.killGraceMs,
-      clientProcessId: null,
-      pathToFileUri: e2bFileUri,
-    }, (spec: SubprocessSpawnSpec) => {
-      const originalArgv = Buffer.from(JSON.stringify(spec.argv)).toString('base64')
-      const inner = this.subprocess.spawn({
-        ...spec,
-        argv: [this.nodeExecutable, this.proxyPath, originalArgv],
-        stdio: {
-          stdin: 'pipe',
-          stdout: 'pipe',
-          stderr: { maxBytes: this.config.maxStderrBytes },
-        },
-      })
-      const rawBound = Math.max(this.config.maxMessageBytes, this.config.maxStderrBytes)
-      return new E2BLspTransport(inner, rawBound * 2 + 1024, this.config.maxStderrBytes)
-    })
-  }
-
-  private evict(workspace: string, instance: LspInstance): void {
-    if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
-  }
-}
-
-/** Install the proxy, resolve remote commands, and atomically register providers. */
-export async function apply(ctx: Context, config: Config): Promise<void> {
-  if (!(ctx.subprocess instanceof E2BSubprocessService)) {
-    throw new Error('lsp-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
-  }
-  const subprocess = ctx.subprocess
-  const entries = Object.entries(config.servers)
-  if (entries.length === 0) throw new Error('lsp-e2b: servers must contain at least one server')
-  const sandbox = await ctx.e2b.getSandbox()
-  const proxyPath = posix.join(ctx.e2b.runtimeRoot, 'lsp-stdio-proxy.mjs')
-  await sandbox.files.write([{ path: proxyPath, data: LSP_PROXY_SOURCE }])
-  await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(proxyPath)}`)
-  const nodeExecutable = await resolveE2BExecutable(sandbox, 'node')
-  const providers = await Promise.all(entries.map(async ([providerId, raw]) => {
-    if (providerId.trim() === '') throw new Error('lsp-e2b: server ids must be non-empty strings')
-    const resolved = raw as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const executable = await resolveE2BExecutable(sandbox, resolved.command)
-    return new E2BLspProvider(providerId, sandbox, subprocess, resolved, executable, nodeExecutable, proxyPath)
-  }))
-
-  /* jscpd:ignore-start -- Every provider table publishes atomically through the same registry contract. */
-  ctx.effect(() => {
-    const disposers: Array<() => void> = []
-    try {
-      for (const provider of providers) disposers.push(ctx.lsp.registerProvider(provider))
-    } catch (error: unknown) {
-      for (const dispose of disposers.reverse()) dispose()
-      throw error
-    }
-    return async () => {
-      for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
-    }
-  }, 'lsp-e2b.registerProviders')
-  /* jscpd:ignore-end */
-}
diff --git a/packages/e2b/lsp-e2b/src/invariant.ts b/packages/e2b/lsp-e2b/src/invariant.ts
deleted file mode 100644
index 129cf0a6d4..0000000000
--- a/packages/e2b/lsp-e2b/src/invariant.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-lsp-e2b`. */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-lsp-e2b'
-
-/** Cordis companion plugin name. */
-export const name = 'lsp-e2b-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/** No runtime invariant: the LSP registry owns provider publication. */
-const install: InvariantInstaller = () => {}
-
-/** Register this package's invariant companion. */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/e2b/lsp-e2b/src/proxy-source.ts b/packages/e2b/lsp-e2b/src/proxy-source.ts
deleted file mode 100644
index 5b6fe42d07..0000000000
--- a/packages/e2b/lsp-e2b/src/proxy-source.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-/** Dependency-free remote stdio proxy installed inside the E2B sandbox. */
-
-/**
- * Node program that base64-frames raw child stdio so E2B's text callbacks
- * never decode the language server's byte stream.
- */
-export const LSP_PROXY_SOURCE = String.raw`import { Buffer } from 'node:buffer'
-import { spawn } from 'node:child_process'
-import { createInterface } from 'node:readline'
-
-const emit = (message) => {
-  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
-}
-
-let argv
-try {
-  argv = JSON.parse(Buffer.from(process.argv[2], 'base64').toString('utf8'))
-  if (!Array.isArray(argv) || argv.length === 0 || argv.some(value => typeof value !== 'string')) throw new Error('invalid argv')
-} catch (error) {
-  process.stderr.write('lsp-e2b proxy argv error: ' + String(error) + '\n')
-  process.exitCode = 125
-  process.stdin.destroy()
-}
-
-if (argv) {
-  const child = spawn(argv[0], argv.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], env: process.env })
-  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  child.stdout.on('data', data => { emit({ type: 'stdout', data: data.toString('base64') }) })
-  child.stderr.on('data', data => { emit({ type: 'stderr', data: data.toString('base64') }) })
-  child.on('error', error => {
-    emit({ type: 'stderr', data: Buffer.from('language server spawn failed: ' + error.message).toString('base64') })
-  })
-  child.on('close', (code, signal) => {
-    emit({ type: 'exit', code, signal })
-    input.close()
-    process.stdin.destroy()
-    process.exitCode = code === null ? 1 : code
-  })
-  input.on('line', line => {
-    input.pause()
-    try {
-      const message = JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
-      if (!message || message.type !== 'stdin' || typeof message.data !== 'string') throw new Error('invalid stdin frame')
-      const data = Buffer.from(message.data, 'base64')
-      if (data.toString('base64') !== message.data) throw new Error('invalid stdin base64')
-      if (child.stdin.write(data)) input.resume()
-      else child.stdin.once('drain', () => { input.resume() })
-    } catch (error) {
-      process.stderr.write('lsp-e2b proxy stdin error: ' + String(error) + '\n')
-      child.kill('SIGTERM')
-    }
-  })
-  input.on('close', () => { child.stdin.end() })
-}
-`
diff --git a/packages/e2b/lsp-e2b/src/transport.ts b/packages/e2b/lsp-e2b/src/transport.ts
deleted file mode 100644
index ddd3445db8..0000000000
--- a/packages/e2b/lsp-e2b/src/transport.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-/** Byte-faithful stdio transport over an E2B subprocess and ASCII/base64 frames. */
-
-import { Buffer } from 'node:buffer'
-import { PassThrough, Writable } from 'node:stream'
-import { E2BFrameDecoder, encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
-import type {
-  SubprocessHandle,
-  SubprocessOutcome,
-  SubprocessOutputRead,
-  SubprocessOutputReader,
-} from '@deepseek-ai/dsh-subprocess'
-
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
-class ByteTailReader implements SubprocessOutputReader {
-  private chunks: Buffer[] = []
-  private totalBytes = 0
-  private retainedBytes = 0
-  private dropped = false
-
-  constructor(private readonly maxBytes: number) {}
-
-  append(data: Buffer): void {
-    if (data.length === 0) return
-    this.chunks.push(data)
-    this.totalBytes += data.length
-    this.retainedBytes += data.length
-    while (this.retainedBytes > this.maxBytes && this.chunks.length > 0) {
-      const first = this.chunks[0] as Buffer
-      const excess = this.retainedBytes - this.maxBytes
-      if (first.length <= excess) {
-        this.chunks.shift()
-        this.retainedBytes -= first.length
-      } else {
-        this.chunks[0] = first.subarray(excess)
-        this.retainedBytes -= excess
-      }
-      this.dropped = true
-    }
-  }
-
-  readFrom(fromByte: number): SubprocessOutputRead {
-    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
-      throw new Error('subprocess output offset must be a non-negative safe integer')
-    }
-    const retainedStart = this.totalBytes - this.retainedBytes
-    const lossy = fromByte < retainedStart
-    const start = lossy ? 0 : Math.min(this.retainedBytes, fromByte - retainedStart)
-    const bytes = Buffer.concat(this.chunks).subarray(start)
-    return { text: bytes.toString('utf8'), nextOffset: this.totalBytes, lossy: lossy || this.dropped && fromByte === 0 }
-  }
-}
-
-class FramedInput extends Writable {
-  constructor(private readonly target: Writable) {
-    super()
-    target.on('error', (error: Error) => { this.destroy(error) })
-  }
-
-  override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
-    this.target.write(encodeE2BFrame({ type: 'stdin', data: chunk.toString('base64') }), callback)
-  }
-
-  override _final(callback: (error?: Error | null) => void): void {
-    this.target.end(callback)
-  }
-}
-
-/** Subprocess handle that decodes a remote proxy's stdout/stderr byte frames. */
-export class E2BLspTransport implements SubprocessHandle {
-  readonly stdin: Writable
-  readonly stdout = new PassThrough()
-  readonly stderr = undefined
-  readonly collected: SubprocessHandle['collected']
-  readonly done: Promise<SubprocessOutcome>
-  private readonly stderrTail: ByteTailReader
-  private readonly decoder: E2BFrameDecoder
-  private failed: Error | undefined
-
-  /**
-   * @param inner - E2B subprocess running the installed proxy.
-   * @param maxFrameBytes - Maximum decoded proxy frame size.
-   * @param maxStderrBytes - Retained raw language-server stderr tail.
-   */
-  constructor(
-    private readonly inner: SubprocessHandle,
-    maxFrameBytes: number,
-    maxStderrBytes: number,
-  ) {
-    if (inner.stdin === undefined || inner.stdout === undefined) {
-      inner.terminate()
-      throw new Error('lsp-e2b: proxy subprocess dropped a piped stream')
-    }
-    this.stdin = new FramedInput(inner.stdin)
-    this.stderrTail = new ByteTailReader(maxStderrBytes)
-    this.collected = { stderr: this.stderrTail }
-    this.decoder = new E2BFrameDecoder(maxFrameBytes)
-    inner.stdout.on('data', (chunk: Buffer) => { this.onProxyData(chunk) })
-    inner.stdout.on('error', (error: Error) => { this.fail(error) })
-    this.done = inner.done.then(
-      (outcome) => {
-        this.finishFrames()
-        this.captureProxyStderr()
-        this.stdout.end()
-        if (this.failed !== undefined) throw this.failed
-        return outcome
-      },
-      (error: unknown) => {
-        this.captureProxyStderr()
-        this.stdout.end()
-        throw error
-      },
-    )
-    void this.done.catch(() => {})
-  }
-
-  get pid(): number {
-    return this.inner.pid
-  }
-
-  terminate(): void {
-    this.inner.terminate()
-  }
-
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    return await this.inner.waitForExit(signal)
-  }
-
-  private onProxyData(chunk: Buffer): void {
-    if (this.failed !== undefined) return
-    let frames: unknown[]
-    try {
-      frames = this.decoder.push(chunk.toString('utf8'))
-    } catch (error: unknown) {
-      this.fail(asError(error))
-      return
-    }
-    for (const frame of frames) this.dispatch(frame)
-  }
-
-  private dispatch(frame: unknown): void {
-    if (typeof frame !== 'object' || frame === null) {
-      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
-      return
-    }
-    const record = frame as Record<string, unknown>
-    if (record.type === 'exit' && (record.code === null || typeof record.code === 'number') && (record.signal === null || typeof record.signal === 'string')) return
-    if ((record.type !== 'stdout' && record.type !== 'stderr') || typeof record.data !== 'string') {
-      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
-      return
-    }
-    const data = Buffer.from(record.data, 'base64')
-    if (data.toString('base64') !== record.data) {
-      this.fail(new Error('lsp-e2b: proxy emitted invalid base64'))
-      return
-    }
-    if (record.type === 'stdout') this.stdout.write(data)
-    else this.stderrTail.append(data)
-  }
-
-  private finishFrames(): void {
-    if (this.failed !== undefined) return
-    try {
-      this.decoder.finish()
-    } catch (error: unknown) {
-      this.fail(asError(error))
-    }
-  }
-
-  private captureProxyStderr(): void {
-    const diagnostic = this.inner.collected.stderr?.readFrom(0).text
-    if (diagnostic !== undefined && diagnostic.length > 0) this.stderrTail.append(Buffer.from(diagnostic))
-  }
-
-  private fail(error: Error): void {
-    if (this.failed !== undefined) return
-    this.failed = error
-    this.inner.terminate()
-    this.stdout.end()
-  }
-}
diff --git a/packages/e2b/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
deleted file mode 100644
index dc92053e4a..0000000000
--- a/packages/e2b/lsp-e2b/tests/provider.spec.ts
+++ /dev/null
@@ -1,418 +0,0 @@
-import { PassThrough } from 'node:stream'
-import { Context } from 'cordis'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import {
-  FileType,
-  type Sandbox,
-} from '@deepseek-ai/dsh-e2b'
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-
-const mockedLsp = vi.hoisted(() => {
-  interface Plan {
-    query?: (...args: unknown[]) => unknown
-    transportFailure?: unknown
-    dead?: boolean
-    deadAfterQuery?: boolean
-    disposeError?: unknown
-  }
-
-  class FakeLspInstance {
-    static readonly instances: FakeLspInstance[] = []
-    static readonly plans: Plan[] = []
-    readonly plan: Plan
-    readonly transport: unknown
-    readonly queries: unknown[][] = []
-    dead: boolean
-    disposals = 0
-
-    constructor(
-      readonly spec: Record<string, unknown>,
-      spawner: (spec: SubprocessSpawnSpec) => unknown,
-    ) {
-      this.plan = FakeLspInstance.plans.shift() ?? {}
-      this.dead = this.plan.dead === true
-      this.transport = spawner({
-        argv: [String(spec.command), ...(spec.args as string[])],
-        cwd: String(spec.cwd),
-        env: spec.env as Record<string, string>,
-        graceMs: Number(spec.killGraceMs),
-        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: Number(spec.maxStderrBytes) } },
-      })
-      FakeLspInstance.instances.push(this)
-    }
-
-    async query(...args: unknown[]): Promise<unknown> {
-      this.queries.push(args)
-      const result = await Promise.resolve(this.plan.query?.(...args) ?? { kind: 'hover', hover: null })
-      if (this.plan.deadAfterQuery === true) this.dead = true
-      return result
-    }
-
-    isTransportFailure(error: unknown): boolean {
-      return error === this.plan.transportFailure
-    }
-
-    async dispose(): Promise<void> {
-      this.disposals += 1
-      this.dead = true
-      if (this.plan.disposeError !== undefined) throw this.plan.disposeError
-    }
-  }
-
-  return { FakeLspInstance }
-})
-
-vi.mock('@deepseek-ai/dsh-lsp-local', () => ({ LspInstance: mockedLsp.FakeLspInstance }))
-
-import {
-  E2BLspProvider,
-  apply,
-  canonicalizeE2BWorkspace,
-  e2bFileUri,
-  readE2BSource,
-} from '@deepseek-ai/dsh-lsp-e2b'
-import type { LspE2BServerConfig } from '@deepseek-ai/dsh-lsp-e2b'
-import * as E2BLspInvariant from '../src/invariant.ts'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-
-class FakeInnerHandle implements SubprocessHandle {
-  readonly pid = 777
-  readonly stdin = new PassThrough()
-  readonly stdout = new PassThrough()
-  readonly stderr = undefined
-  readonly collected = { stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) } }
-  readonly done = Promise.resolve({ exitCode: 0, signal: null })
-  terminate(): void {}
-  async waitForExit(): Promise<boolean> { return true }
-}
-
-class FakeRemote {
-  readonly writes: Array<Array<{ path: string; data: string }>> = []
-  readonly commands: string[] = []
-  readonly infos = new Map<string, { type: FileType; size: number }>()
-  readonly contents = new Map<string, Uint8Array>()
-  readonly realpaths = new Map<string, string>()
-  forcedRealpath: string | undefined
-  readerResponse: unknown
-  readerOutput: string | undefined
-
-  constructor() {
-    this.infos.set('/workspace', { type: FileType.DIR, size: 0 })
-    this.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 12 })
-    this.contents.set('/workspace/file.ts', Buffer.from('const x = 1'))
-    this.readerResponse = { kind: 'ok', data: Buffer.from('const x = 1').toString('base64') }
-  }
-
-  readonly sandbox = {
-    commands: {
-      run: async (command: string) => {
-        this.commands.push(command)
-        if (command.startsWith('realpath ')) {
-          const match = /'([^']*)'$/.exec(command)
-          const requested = match?.[1] ?? ''
-          return { exitCode: 0, stdout: `${this.forcedRealpath ?? this.realpaths.get(requested) ?? requested}\n`, stderr: '' }
-        }
-        if (command.includes('dsh-e2b-source-reader')) {
-          return { exitCode: 0, stdout: this.readerOutput ?? JSON.stringify(this.readerResponse), stderr: '' }
-        }
-        if (command.startsWith('command -v')) return { exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' }
-        return { exitCode: 0, stdout: '', stderr: '' }
-      },
-    },
-    files: {
-      write: async (files: Array<{ path: string; data: string }>) => {
-        this.writes.push(files)
-        return files.map(() => ({}))
-      },
-      getInfo: async (path: string) => {
-        const info = this.infos.get(path)
-        if (info === undefined) throw new Error(`missing info for ${path}`)
-        return info
-      },
-      read: async (path: string) => this.contents.get(path) ?? new Uint8Array(),
-    },
-  } as unknown as Sandbox
-}
-
-function subprocess(spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())): E2BSubprocessService {
-  const service = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
-  Object.defineProperty(service, 'spawn', { value: spawn })
-  return service
-}
-
-function server(overrides: Partial<LspE2BServerConfig> = {}): Required<LspE2BServerConfig> {
-  return {
-    command: '/usr/bin/server', args: ['--stdio'], env: {},
-    extensionToLanguage: { '.ts': 'typescript' },
-    initializationOptions: null, configuration: null,
-    maxMessageBytes: 1_024, maxStderrBytes: 128, maxDocumentBytes: 1_024,
-    shutdownTimeoutMs: 100, killGraceMs: 50,
-    ...overrides,
-  }
-}
-
-function provider(remote = new FakeRemote(), service = subprocess()): E2BLspProvider {
-  return new E2BLspProvider(
-    'fixture', remote.sandbox, service, server(),
-    '/usr/bin/server', '/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs',
-  )
-}
-
-function query(workspaceRoot = '/workspace') {
-  return {
-    operation: 'hover' as const,
-    filePath: 'file.ts',
-    position: { line: 0, character: 1 },
-    workspaceRoot,
-    languageId: 'typescript',
-  }
-}
-
-beforeEach(() => {
-  mockedLsp.FakeLspInstance.instances.length = 0
-  mockedLsp.FakeLspInstance.plans.length = 0
-})
-
-describe('E2B LSP filesystem boundary', () => {
-  it('canonicalizes a directory and reads a contained UTF-8 source', async () => {
-    const remote = new FakeRemote()
-    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace')).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toEqual({
-      canonicalPath: '/workspace/file.ts',
-      text: 'const x = 1',
-    })
-    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toMatchObject({
-      canonicalPath: '/workspace/file.ts',
-    })
-    const signal = new AbortController().signal
-    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace', signal)).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node', signal)).resolves.toMatchObject({
-      canonicalPath: '/workspace/file.ts',
-    })
-  })
-
-  it('rejects malformed workspaces and source containment/type/size/encoding failures', async () => {
-    const malformed = new FakeRemote()
-    malformed.forcedRealpath = 'relative'
-    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
-    malformed.forcedRealpath = '/workspace\nother'
-    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
-
-    const notDirectory = new FakeRemote()
-    notDirectory.infos.set('/workspace', { type: FileType.FILE, size: 0 })
-    await expect(canonicalizeE2BWorkspace(notDirectory.sandbox, '/workspace')).rejects.toThrow('not a directory')
-
-    const outside = new FakeRemote()
-    outside.realpaths.set('/workspace/file.ts', '/outside/file.ts')
-    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('outside the workspace')
-
-    const notFile = new FakeRemote()
-    notFile.readerResponse = { kind: 'not-file' }
-    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not a regular file')
-
-    const tooLarge = new FakeRemote()
-    tooLarge.readerResponse = { kind: 'oversize', size: 21 }
-    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('over the 20-byte limit')
-
-    const grew = new FakeRemote()
-    grew.readerResponse = { kind: 'grew' }
-    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('grew past')
-
-    const invalid = new FakeRemote()
-    invalid.readerResponse = { kind: 'ok', data: Buffer.from([0xff]).toString('base64') }
-    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not valid UTF-8')
-
-    const swapped = new FakeRemote()
-    swapped.readerResponse = { kind: 'open-error', message: 'ELOOP: symbolic link encountered' }
-    await expect(readE2BSource(swapped.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('opened safely')
-
-    const malformedReader = new FakeRemote()
-    malformedReader.readerResponse = { kind: 'ok', data: '*' }
-    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid bounded bytes')
-    malformedReader.readerResponse = { kind: 'oversize', size: 'large' }
-    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
-    malformedReader.readerOutput = '{'
-    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
-
-    await expect(canonicalizeE2BWorkspace(new FakeRemote().sandbox, '/workspace', AbortSignal.abort('stop')))
-      .rejects.toBe('stop')
-  })
-})
-
-describe('E2BLspProvider pooling and lifecycle', () => {
-  it('reuses one canonical-workspace instance and constructs the remote proxy transport', async () => {
-    const spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())
-    const remote = new FakeRemote()
-    mockedLsp.FakeLspInstance.plans.push({ query: async () => ({ kind: 'hover', hover: { contents: 'ok' } }) })
-    const current = provider(remote, subprocess(spawn))
-
-    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
-    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
-    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(1)
-    expect(mockedLsp.FakeLspInstance.instances[0]?.spec).toMatchObject({ clientProcessId: null, cwd: '/workspace' })
-    expect(e2bFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
-    expect(() => e2bFileUri('relative.ts')).toThrow('absolute remote path')
-    const pathToFileUri = mockedLsp.FakeLspInstance.instances[0]?.spec.pathToFileUri as (path: string) => string
-    expect(pathToFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
-    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
-      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs', expect.any(String)],
-      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 128 } },
-    }))
-    expect(current.id).toBe('fixture')
-    expect(current.extensionToLanguage).toEqual({ '.ts': 'typescript' })
-    await current.disposeAll()
-    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
-  })
-
-  it('replaces one transport failure, but preserves ordinary query errors', async () => {
-    const transportFailure = new Error('transport failed')
-    mockedLsp.FakeLspInstance.plans.push(
-      { transportFailure, query: async () => { throw transportFailure } },
-      { query: async () => ({ kind: 'hover', hover: { contents: 'retried' } }) },
-    )
-    const retried = provider()
-    await expect(retried.query(query())).resolves.toMatchObject({ hover: { contents: 'retried' } })
-    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
-    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
-
-    const ordinary = new Error('ordinary failure')
-    mockedLsp.FakeLspInstance.plans.push(
-      { query: async () => { throw ordinary }, dead: true },
-      { query: async () => ({ kind: 'hover', hover: null }) },
-    )
-    const failed = provider()
-    await expect(failed.query(query())).rejects.toBe(ordinary)
-    await expect(failed.query(query())).resolves.toMatchObject({ kind: 'hover' })
-  })
-
-  it('evicts a server that dies after a successful query', async () => {
-    mockedLsp.FakeLspInstance.plans.push(
-      { deadAfterQuery: true, query: async () => ({ kind: 'hover', hover: null }) },
-      { query: async () => ({ kind: 'hover', hover: null }) },
-    )
-    const current = provider()
-    await current.query(query())
-    await current.query(query())
-    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
-    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
-  })
-
-  it('serializes a workspace queue, observes queued abort, and awaits work on disposal', async () => {
-    const first = Promise.withResolvers<unknown>()
-    mockedLsp.FakeLspInstance.plans.push({ query: () => first.promise })
-    const current = provider()
-    const running = current.query(query())
-    const controller = new AbortController()
-    const queued = current.query(query(), controller.signal)
-    await new Promise(resolve => setImmediate(resolve))
-    controller.abort('queued stop')
-    await expect(queued).rejects.toBe('queued stop')
-
-    const disposing = current.disposeAll()
-    first.resolve({ kind: 'hover', hover: null })
-    await expect(running).resolves.toMatchObject({ kind: 'hover' })
-    await disposing
-    await expect(current.query(query())).rejects.toMatchObject({ code: 'LSP_DISPOSED' })
-  })
-
-  it('covers pre-abort, synthetic abort, resolve, and rejection in the queue race', async () => {
-    const current = provider()
-    const internal = current as unknown as {
-      queues: Map<string, Promise<void>>
-      enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T>
-    }
-    await expect(internal.enqueue('pre', AbortSignal.abort('pre-stop'), async () => 'unused')).rejects.toBe('pre-stop')
-
-    const signal = new AbortController().signal
-    await expect(internal.enqueue('resolve', signal, async () => 'ok')).resolves.toBe('ok')
-
-    const failure = new Error('queue failed')
-    const rejected = Promise.reject<undefined>(failure)
-    void rejected.catch(() => {})
-    internal.queues.set('reject', rejected)
-    await expect(internal.enqueue('reject', signal, async () => 'unused')).rejects.toBe(failure)
-
-    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Exercise normalization at the promise boundary.
-    const opaque = Promise.reject<undefined>('opaque queue failure')
-    void opaque.catch(() => {})
-    internal.queues.set('opaque', opaque)
-    await expect(internal.enqueue('opaque', signal, async () => 'unused')).rejects.toEqual(new Error('opaque queue failure'))
-
-    const synthetic = {
-      aborted: false,
-      reason: undefined,
-      throwIfAborted() {},
-      addEventListener(_type: string, listener: () => void) { listener() },
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    await expect(internal.enqueue('synthetic', synthetic, async () => 'unused')).rejects.toMatchObject({ name: 'AbortError' })
-    await current.disposeAll()
-  })
-})
-
-describe('lsp-e2b plugin composition', () => {
-  function pluginContext(
-    remote: FakeRemote,
-    service: E2BSubprocessService,
-    registerProvider = vi.fn(() => vi.fn()),
-  ) {
-    const effects: Array<() => void | Promise<void>> = []
-    const ctx = {
-      subprocess: service,
-      e2b: {
-        runtimeRoot: '/workspace/.dsh-e2b',
-        getSandbox: async () => remote.sandbox,
-      },
-      lsp: { registerProvider },
-      effect: (callback: () => (() => void | Promise<void>)) => { effects.push(callback()) },
-    } as unknown as Context
-    return { ctx, effects, registerProvider }
-  }
-
-  it('installs one proxy, resolves commands, registers providers, and disposes them', async () => {
-    const remote = new FakeRemote()
-    const fixture = pluginContext(remote, subprocess())
-    await apply(fixture.ctx, { servers: { one: server(), two: server({ command: 'server-two' }) } })
-    expect(remote.writes).toHaveLength(1)
-    expect(remote.writes[0]?.[0]?.path).toBe('/workspace/.dsh-e2b/lsp-stdio-proxy.mjs')
-    expect(remote.commands).toContain("chmod 600 -- '/workspace/.dsh-e2b/lsp-stdio-proxy.mjs'")
-    expect(fixture.registerProvider).toHaveBeenCalledTimes(2)
-    await fixture.effects[0]?.()
-  })
-
-  it('rolls back partial registration and rejects invalid composition/configuration', async () => {
-    const remote = new FakeRemote()
-    const firstDispose = vi.fn()
-    const register = vi.fn()
-      .mockReturnValueOnce(firstDispose)
-      .mockImplementationOnce(() => { throw new Error('duplicate provider') })
-    const rollback = pluginContext(remote, subprocess(), register)
-    await expect(apply(rollback.ctx, { servers: { one: server(), two: server() } })).rejects.toThrow('duplicate provider')
-    expect(firstDispose).toHaveBeenCalledOnce()
-
-    const wrong = pluginContext(remote, {} as E2BSubprocessService)
-    await expect(apply(wrong.ctx, { servers: { one: server() } })).rejects.toThrow('dsh-subprocess-e2b')
-
-    const empty = pluginContext(remote, subprocess())
-    await expect(apply(empty.ctx, { servers: {} })).rejects.toThrow('at least one server')
-
-    for (const [id, config] of [
-      ['', server()],
-      ['one', server({ command: '' })],
-      ['one', server({ maxMessageBytes: 0 })],
-      ['one', server({ maxStderrBytes: 1.5 })],
-      ['one', server({ shutdownTimeoutMs: 2_147_483_648 })],
-    ] as const) {
-      const fixture = pluginContext(new FakeRemote(), subprocess())
-      await expect(apply(fixture.ctx, { servers: { [id]: config } })).rejects.toThrow()
-    }
-  })
-
-  it('registers the package-owned invariant companion', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    const fiber = await ctx.plugin(E2BLspInvariant).await()
-    await fiber.dispose()
-  })
-})
diff --git a/packages/e2b/lsp-e2b/tests/transport.spec.ts b/packages/e2b/lsp-e2b/tests/transport.spec.ts
deleted file mode 100644
index ae5106bc09..0000000000
--- a/packages/e2b/lsp-e2b/tests/transport.spec.ts
+++ /dev/null
@@ -1,181 +0,0 @@
-import { once } from 'node:events'
-import { PassThrough } from 'node:stream'
-import { describe, expect, it } from 'vitest'
-import { encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
-import type { SubprocessHandle, SubprocessOutcome } from '@deepseek-ai/dsh-subprocess'
-import { E2BLspTransport } from '@deepseek-ai/dsh-lsp-e2b'
-
-class FakeHandle implements SubprocessHandle {
-  readonly pid = 321
-  readonly stdin: PassThrough | undefined
-  readonly stdout: PassThrough | undefined
-  readonly stderr = undefined
-  readonly collected: SubprocessHandle['collected']
-  readonly result = Promise.withResolvers<SubprocessOutcome>()
-  readonly done = this.result.promise
-  terminated = 0
-  waitResult = true
-
-  constructor(options: { stdin?: boolean; stdout?: boolean; diagnostic?: string } = {}) {
-    this.stdin = options.stdin === false ? undefined : new PassThrough()
-    this.stdout = options.stdout === false ? undefined : new PassThrough()
-    this.collected = options.diagnostic === undefined
-      ? {}
-      : { stderr: { readFrom: () => ({ text: options.diagnostic as string, nextOffset: 0, lossy: false }) } }
-  }
-
-  terminate(): void {
-    this.terminated += 1
-  }
-
-  async waitForExit(): Promise<boolean> {
-    return this.waitResult
-  }
-
-  resolve(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
-    this.stdout?.end()
-    this.result.resolve(outcome)
-  }
-
-  reject(error: unknown): void {
-    this.stdout?.end()
-    this.result.reject(error)
-  }
-}
-
-function proxyFrame(type: 'stdout' | 'stderr', data: string | Buffer): string {
-  return encodeE2BFrame({ type, data: Buffer.from(data).toString('base64') })
-}
-
-describe('E2BLspTransport', () => {
-  it('frames stdin, decodes split byte output, and exposes handle lifecycle', async () => {
-    const inner = new FakeHandle({ diagnostic: 'proxy diagnostic' })
-    const transport = new E2BLspTransport(inner, 1_024, 64)
-    let stdin = ''
-    inner.stdin?.on('data', (chunk) => { stdin += String(chunk) })
-    let stdout = Buffer.alloc(0)
-    transport.stdout.on('data', (chunk) => { stdout = Buffer.concat([stdout, chunk]) })
-
-    transport.stdin.write(Buffer.from([0, 0xff]))
-    await new Promise(resolve => setImmediate(resolve))
-    const encodedInput = stdin.trim()
-    const input = JSON.parse(Buffer.from(encodedInput, 'base64').toString('utf8')) as Record<string, string>
-    expect(input).toEqual({ type: 'stdin', data: 'AP8=' })
-
-    const frames = proxyFrame('stdout', Buffer.from([0, 0xff]))
-      + proxyFrame('stderr', 'server diagnostic')
-      + encodeE2BFrame({ type: 'exit', code: 0, signal: null })
-    inner.stdout?.write(frames.slice(0, 7))
-    inner.stdout?.write(frames.slice(7))
-    inner.stdout?.write(proxyFrame('stderr', ''))
-    inner.stdout?.write(encodeE2BFrame({ type: 'exit', code: null, signal: 'SIGTERM' }))
-    inner.resolve()
-
-    await expect(transport.done).resolves.toEqual({ exitCode: 0, signal: null })
-    expect(stdout).toEqual(Buffer.from([0, 0xff]))
-    expect(transport.collected.stderr?.readFrom(0).text).toBe('server diagnosticproxy diagnostic')
-    expect(transport.pid).toBe(321)
-    inner.waitResult = false
-    await expect(transport.waitForExit()).resolves.toBe(false)
-    transport.terminate()
-    expect(inner.terminated).toBe(1)
-  })
-
-  it('ends the inner stdin and retains a bounded byte tail with independent offsets', async () => {
-    const inner = new FakeHandle()
-    const transport = new E2BLspTransport(inner, 1_024, 4)
-    const finished = once(inner.stdin!, 'finish')
-    transport.stdin.end()
-    await finished
-
-    inner.stdout?.write(proxyFrame('stderr', 'ab'))
-    inner.stdout?.write(proxyFrame('stderr', 'cdef'))
-    const reader = transport.collected.stderr!
-    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
-    expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
-    expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
-    expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
-    expect(() => reader.readFrom(-1)).toThrow('non-negative safe integer')
-    expect(() => reader.readFrom(1.5)).toThrow('non-negative safe integer')
-    inner.resolve()
-    await transport.done
-
-    const partialInner = new FakeHandle()
-    const partial = new E2BLspTransport(partialInner, 1_024, 4)
-    partialInner.stdout?.write(proxyFrame('stderr', 'abcdef'))
-    expect(partial.collected.stderr?.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
-    partialInner.resolve()
-    await partial.done
-  })
-
-  it.each([
-    ['non-object', encodeE2BFrame(null), 'malformed frame'],
-    ['wrong type', encodeE2BFrame({ type: 'other', data: '' }), 'malformed frame'],
-    ['invalid exit', encodeE2BFrame({ type: 'exit', code: 'zero', signal: null }), 'malformed frame'],
-    ['missing data', encodeE2BFrame({ type: 'stdout' }), 'malformed frame'],
-    ['invalid base64', encodeE2BFrame({ type: 'stdout', data: 'abc' }), 'invalid base64'],
-    ['invalid outer frame', 'not-base64\n', 'invalid base64'],
-    ['non-ASCII outer frame', 'é', 'non-ASCII'],
-  ])('fails %s proxy traffic and terminates the group', async (_name, frame, message) => {
-    const inner = new FakeHandle()
-    const transport = new E2BLspTransport(inner, 1_024, 32)
-    inner.stdout?.write(frame)
-    inner.stdout?.write(proxyFrame('stdout', 'ignored'))
-    inner.stdout?.emit('error', new Error('second failure'))
-    inner.resolve()
-    await expect(transport.done).rejects.toThrow(message)
-    expect(inner.terminated).toBe(1)
-  })
-
-  it('fails truncated frames and preserves inner spawn rejection', async () => {
-    const truncatedInner = new FakeHandle()
-    const truncated = new E2BLspTransport(truncatedInner, 1_024, 32)
-    truncatedInner.stdout?.write('YQ==')
-    truncatedInner.resolve()
-    await expect(truncated.done).rejects.toThrow('mid-frame')
-
-    const rejectedInner = new FakeHandle({ diagnostic: 'tail' })
-    const rejected = new E2BLspTransport(rejectedInner, 1_024, 32)
-    rejectedInner.reject(new Error('spawn failed'))
-    await expect(rejected.done).rejects.toThrow('spawn failed')
-    expect(rejected.collected.stderr?.readFrom(0).text).toBe('tail')
-  })
-
-  it('forwards output and input stream errors without an unhandled inner error', async () => {
-    const outputInner = new FakeHandle()
-    const output = new E2BLspTransport(outputInner, 1_024, 32)
-    outputInner.stdout?.emit('error', new Error('proxy stdout failed'))
-    outputInner.resolve()
-    await expect(output.done).rejects.toThrow('proxy stdout failed')
-
-    const inputInner = new FakeHandle()
-    const input = new E2BLspTransport(inputInner, 1_024, 32)
-    const outerError = once(input.stdin, 'error')
-    inputInner.stdin?.emit('error', new Error('proxy stdin failed'))
-    await expect(outerError).resolves.toMatchObject([{ message: 'proxy stdin failed' }])
-    inputInner.resolve()
-    await input.done
-  })
-
-  it('normalizes a non-Error decoder throw', async () => {
-    const inner = new FakeHandle()
-    const transport = new E2BLspTransport(inner, 1_024, 32)
-    const internal = transport as unknown as {
-      decoder: { push(chunk: string): unknown[] }
-      onProxyData(chunk: Buffer): void
-    }
-    internal.decoder = { push: () => { throw 'raw decoder failure' } }
-    internal.onProxyData(Buffer.from('x'))
-    inner.resolve()
-    await expect(transport.done).rejects.toThrow('raw decoder failure')
-  })
-
-  it('rejects a subprocess that drops either required pipe', () => {
-    const missingStdin = new FakeHandle({ stdin: false })
-    const missingStdout = new FakeHandle({ stdout: false })
-    expect(() => new E2BLspTransport(missingStdin, 10, 10)).toThrow('dropped a piped stream')
-    expect(() => new E2BLspTransport(missingStdout, 10, 10)).toThrow('dropped a piped stream')
-    expect(missingStdin.terminated).toBe(1)
-    expect(missingStdout.terminated).toBe(1)
-  })
-})
diff --git a/packages/e2b/lsp-e2b/tsconfig.json b/packages/e2b/lsp-e2b/tsconfig.json
deleted file mode 100644
index a6c0fd8ece..0000000000
--- a/packages/e2b/lsp-e2b/tsconfig.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../../../vendor/cosmokit" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../../vendor/schemastery" },
-    { "path": "../e2b" },
-    { "path": "../../lsp/lsp" },
-    { "path": "../../lsp/lsp-local" },
-    { "path": "../../subprocess/subprocess" },
-    { "path": "../subprocess-e2b" },
-    { "path": "../../util/timeout" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/e2b/pty-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
index ddae4c21db..580f874e62 100644
--- a/packages/e2b/pty-e2b/README.i18n.yaml
+++ b/packages/e2b/pty-e2b/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/e2b/pty-e2b/README.md
-README.md: d6d8e05f13701b85cee9a9646bfdd82ac07769da
-README.zh.md: 265257c72e7bcbd2dfd805b343db5bab7173ab51
+README.md: d1b1731cd7b65577a18814a90363acdc66d7d262
+README.zh.md: 4aa2cc8d661e61e80ef61693422a7b6f73c2cb67
diff --git a/packages/e2b/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
index d6d8e05f13..d1b1731cd7 100644
--- a/packages/e2b/pty-e2b/README.md
+++ b/packages/e2b/pty-e2b/README.md
@@ -26,7 +26,7 @@ Numeric values are positive safe integers, `backendType` is non-empty, and `maxR
 
 The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
 
-Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
+Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; cancellation rechecks the originating send after lookup so a settled operation cannot signal or fail its successor, and `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
 
 The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
 
diff --git a/packages/e2b/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
index 265257c72e..4aa2cc8d66 100644
--- a/packages/e2b/pty-e2b/README.zh.md
+++ b/packages/e2b/pty-e2b/README.zh.md
@@ -26,7 +26,7 @@
 
 该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
 
-每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
+每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；取消处理会在查找后重新检查原发送操作是否仍为当前操作，以免已结算的操作向后继操作发送信号或令其失败；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
 
 远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
 
diff --git a/packages/e2b/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
index bf8780103d..7742cd44f0 100644
--- a/packages/e2b/pty-e2b/src/session.ts
+++ b/packages/e2b/pty-e2b/src/session.ts
@@ -226,6 +226,10 @@ export class E2BPtySession implements PtyBackendSession {
   /* jscpd:ignore-start -- Signal, status, and close methods preserve the seam shape around remote identities. */
   async signal(signal: PtySignal): Promise<PtySignalResult> {
     const pgid = await this.foregroundPgid()
+    return await this.deliverSignal(signal, pgid)
+  }
+
+  private async deliverSignal(signal: PtySignal, pgid: number): Promise<PtySignalResult> {
     if (signal === 'SIGKILL' && pgid === this.pid) {
       throw new Error('refusing to SIGKILL the E2B PTY shell; use terminal_close')
     }
@@ -302,7 +306,15 @@ export class E2BPtySession implements PtyBackendSession {
 
   private interrupt(operation: E2BSendOperation): void {
     if (this.active !== operation) return
-    void this.signal('SIGINT').catch((error: unknown) => { this.failActive(error) })
+    void this.interruptActive(operation).catch((error: unknown) => {
+      if (this.active === operation) this.failActive(error)
+    })
+  }
+
+  private async interruptActive(operation: E2BSendOperation): Promise<void> {
+    const pgid = await this.foregroundPgid()
+    if (this.active !== operation) return
+    await this.deliverSignal('SIGINT', pgid)
   }
 
   private async foregroundPgid(): Promise<number> {
diff --git a/packages/e2b/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
index 554a4a3590..1fedf6bbac 100644
--- a/packages/e2b/pty-e2b/tests/session.spec.ts
+++ b/packages/e2b/pty-e2b/tests/session.spec.ts
@@ -68,6 +68,7 @@ class FakeSandbox {
   sendError: unknown
   signalError: unknown
   killError: unknown
+  foregroundLookup: Promise<CommandResult> | undefined
   onTerm: (() => void) | undefined
   onGroupKill: (() => void) | undefined
   onKill: (() => void) | undefined
@@ -88,7 +89,9 @@ class FakeSandbox {
     commands: {
       run: async (command: string): Promise<CommandResult> => {
         this.commands.push(command)
-        if (command.startsWith('ps -o tpgid')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
+        if (command.startsWith('ps -o tpgid')) {
+          return await (this.foregroundLookup ?? Promise.resolve({ exitCode: 0, stdout: this.pgid, stderr: '' }))
+        }
         if (command.startsWith('ps -eo sid=')) {
           return { exitCode: 0, stdout: this.sessionGroups.map(value => `${value}\n`).join(''), stderr: '' }
         }
@@ -273,6 +276,45 @@ describe('E2BPtySession readiness, output, and signals', () => {
     expect(sendInput).toHaveBeenCalled()
   })
 
+  it('does not let a stale interrupt signal or fail a successor send', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
+    await initialize(session)
+
+    const lookup = Promise.withResolvers<CommandResult>()
+    fake.foregroundLookup = lookup.promise
+    const stale = session.startSend({ text: 'old', submit: true })
+    expect(stale.cancel()).toBe(true)
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await stale.done
+
+    const successor = session.startSend({ text: 'new', submit: true })
+    fake.signalError = new Error('late interrupt failure')
+    lookup.resolve({ exitCode: 0, stdout: '789\n', stderr: '' })
+    await vi.advanceTimersByTimeAsync(0)
+    expect(fake.commands).not.toContain('kill -INT -- -789')
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await expect(successor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
+
+    const failedLookup = Promise.withResolvers<CommandResult>()
+    fake.foregroundLookup = failedLookup.promise
+    const staleFailure = session.startSend({ text: 'old failure', submit: true })
+    expect(staleFailure.cancel()).toBe(true)
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await staleFailure.done
+    const finalSuccessor = session.startSend({ text: 'new after failure', submit: true })
+    failedLookup.reject(new Error('late lookup failure'))
+    await vi.advanceTimersByTimeAsync(0)
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await expect(finalSuccessor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
+  })
+
   it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
     const fake = new FakeSandbox()
     const abortHandle = new FakePtyHandle()

From 2abc9823e761e5abce520799504d264581719930 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 02:51:44 +0800
Subject: [PATCH 108/262] refactor(e2b): compose portable runtime consumers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |  28 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  28 +-
 examples/headless-agent/e2b.cordis.yml        |  23 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  19 +-
 .../tests/fixtures/e2b/e2b/cordis.yml         |  23 +-
 examples/package.json                         |   2 -
 packages/README.i18n.yaml                     |   4 +-
 packages/README.zh.md                         |   2 +-
 .../code-runtime-worker/README.i18n.yaml      |   4 +-
 .../code-runtime-worker/README.md             |   2 +-
 .../code-runtime-worker/README.zh.md          |   2 +-
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |  11 +-
 packages/e2b/README.zh.md                     |  11 +-
 .../e2b/code-runtime-e2b/README.i18n.yaml     |   6 -
 packages/e2b/code-runtime-e2b/README.md       |  44 -
 packages/e2b/code-runtime-e2b/README.zh.md    |  44 -
 packages/e2b/code-runtime-e2b/package.json    |  52 --
 packages/e2b/code-runtime-e2b/src/index.ts    | 494 -----------
 .../e2b/code-runtime-e2b/src/invariant.ts     |  20 -
 .../e2b/code-runtime-e2b/src/runner-source.ts | 649 ---------------
 .../code-runtime-e2b/tests/runtime.spec.ts    | 765 ------------------
 packages/e2b/code-runtime-e2b/tsconfig.json   |  20 -
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/frame.ts                 |  96 ---
 packages/e2b/e2b/src/index.ts                 |  22 -
 packages/e2b/e2b/tests/composition.e2e.ts     |  36 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  55 --
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   4 +-
 packages/e2b/fs-e2b/README.zh.md              |   4 +-
 packages/e2b/fs-e2b/src/index.ts              |  99 +++
 packages/e2b/fs-e2b/src/source-reader.ts      |  63 ++
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 107 ++-
 packages/e2b/pty-e2b/README.i18n.yaml         |   6 -
 packages/e2b/pty-e2b/README.md                |  55 --
 packages/e2b/pty-e2b/README.zh.md             |  55 --
 packages/e2b/pty-e2b/package.json             |  46 --
 packages/e2b/pty-e2b/src/config.ts            |  64 --
 packages/e2b/pty-e2b/src/index.ts             | 130 ---
 packages/e2b/pty-e2b/src/invariant.ts         |  20 -
 packages/e2b/pty-e2b/src/session.ts           | 415 ----------
 packages/e2b/pty-e2b/tests/index.spec.ts      | 248 ------
 packages/e2b/pty-e2b/tests/session.spec.ts    | 485 -----------
 packages/e2b/pty-e2b/tsconfig.json            |  16 -
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  11 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  11 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  93 ++-
 packages/e2b/subprocess-e2b/src/terminal.ts   | 386 +++++++++
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 541 +++++++++++++
 packages/fs/README.i18n.yaml                  |   4 +-
 .../lsp/lsp-local/tests/fixture-server.ts     |   6 -
 packages/lsp/lsp-local/tests/instance.spec.ts |   5 -
 packages/lsp/lsp/README.i18n.yaml             |   6 +-
 packages/lsp/lsp/README.md                    |   1 -
 packages/lsp/lsp/README.zh.md                 |   1 -
 packages/pty/pty/src/index.ts                 |   9 -
 packages/pty/pty/src/terminal.ts              | 273 -------
 .../verify-package-readme-model-experience.ts |   2 -
 tsconfig.host.json                            |   3 -
 64 files changed, 1426 insertions(+), 4229 deletions(-)
 delete mode 100644 packages/e2b/code-runtime-e2b/README.i18n.yaml
 delete mode 100644 packages/e2b/code-runtime-e2b/README.md
 delete mode 100644 packages/e2b/code-runtime-e2b/README.zh.md
 delete mode 100644 packages/e2b/code-runtime-e2b/package.json
 delete mode 100644 packages/e2b/code-runtime-e2b/src/index.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/src/invariant.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/src/runner-source.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/tsconfig.json
 delete mode 100644 packages/e2b/e2b/src/frame.ts
 create mode 100644 packages/e2b/fs-e2b/src/source-reader.ts
 delete mode 100644 packages/e2b/pty-e2b/README.i18n.yaml
 delete mode 100644 packages/e2b/pty-e2b/README.md
 delete mode 100644 packages/e2b/pty-e2b/README.zh.md
 delete mode 100644 packages/e2b/pty-e2b/package.json
 delete mode 100644 packages/e2b/pty-e2b/src/config.ts
 delete mode 100644 packages/e2b/pty-e2b/src/index.ts
 delete mode 100644 packages/e2b/pty-e2b/src/invariant.ts
 delete mode 100644 packages/e2b/pty-e2b/src/session.ts
 delete mode 100644 packages/e2b/pty-e2b/tests/index.spec.ts
 delete mode 100644 packages/e2b/pty-e2b/tests/session.spec.ts
 delete mode 100644 packages/e2b/pty-e2b/tsconfig.json
 create mode 100644 packages/e2b/subprocess-e2b/src/terminal.ts
 create mode 100644 packages/e2b/subprocess-e2b/tests/terminal.spec.ts
 delete mode 100644 packages/pty/pty/src/terminal.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 04ebe420ac..fc187ec47b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 4e6414b7d919d765712ac9314ce73a69c5c6344e
-2026-07-27-e2b-remote-runtime-poc.zh.md: 4d39ed7eb07cdd17c5bfa9155bc7efabaa798117
+2026-07-27-e2b-remote-runtime-poc.md: df0d6be97c502a9afe1a7aff3656a7567d302704
+2026-07-27-e2b-remote-runtime-poc.zh.md: 111d7aa63f8f7e51a82cfa0e42c489901f2b88e4
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 4e6414b7d9..df0d6be97c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -12,27 +12,23 @@ Moving the complete harness into a remote VM would unify that state but also cou
 
 ## Decision
 
-The E2B integration is an opt-in provider-composition POC. Its six E2B-specific packages live under `packages/e2b/` while retaining seam-specific npm names:
+The E2B integration is an opt-in provider-composition POC. Its three E2B-specific packages live together under `packages/e2b/`:
 
 - `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
-- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
-- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` while the existing registry retains exact-Agent ownership.
-- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through a bounded no-follow helper in E2B, and runs servers through `dsh-subprocess-e2b`.
-- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
-- The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
+- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, byte PTYs, and remote Linux process groups.
 
-The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces and model-facing tools.
+The higher capabilities use provider-neutral implementations. `dsh-bash-local` delegates command mechanics to `ctx.subprocess`; `dsh-pty-local` delegates terminal allocation and signalling to `ctx.subprocess.spawnTerminal()`; `dsh-lsp-local` reads through `ctx.fs` and launches through `ctx.subprocess`; `dsh-code-runtime-subprocess` materializes its runner through `ctx.fs` and starts it through `ctx.subprocess`. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns those generic interfaces and consumers.
 
-The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling lives in `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
+The E2B owner is the sole source of sandbox identity. Its two adapters never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces, generic implementations, model-facing tools, and agent loop.
 
 ## POC boundary
 
-E2B owns the mutable filesystem, command and Bash processes, PTY shell and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly and carries send identity across asynchronous foreground-group lookup. LSP installs a bounded remote source reader that walks no-follow directory descriptors beneath the canonical workspace. Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors, and gives each controller a process group that is killed before its inherited pipes drain. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses UTF-8 JSON over command pipes; E2B's decoded callback transport is not an arbitrary binary channel.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -40,7 +36,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 ## Verification
 
-Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signal identity/default-environment scrubbing/terminal-session cleanup, descriptor-walked bounded LSP source reads, Code Runtime binding and descriptor isolation, worker and descendant-held pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
 A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
@@ -50,13 +46,13 @@ A credential-gated Loader composition creates real E2B sandboxes and exercises F
 
 **Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
 
-**Put every E2B capability in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem, subprocess, PTY, LSP, and Code Runtime retain separate provider contracts, configuration, tests, and consumers; Bash continues to reuse its subprocess seam.
+**Put every E2B operation in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem and subprocess retain separate provider contracts, tests, and consumers; the owner exposes one shared SDK handle without becoming a capability grab bag.
 
 **Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
 
-**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
+**Keep E2B-specific PTY, LSP, and Code Runtime packages** — rejected because their domain behavior does not vary with E2B. They were shallow adapters that duplicated existing consumers to replace filesystem and process operations; moving those operations behind the fundamental seams gives every provider one implementation of readiness, protocol, binding, and presentation behavior.
 
-**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
+**Call E2B Filesystem, Commands, or PTY APIs directly from higher capabilities** — rejected because it bypasses the `ctx.fs` and `ctx.subprocess` contracts, duplicates execution-world policy in each consumer, and forks model-facing behavior. The subprocess seam includes the irreducible terminal primitive because ordinary pipes cannot supply foreground groups or whole-session cleanup.
 
 **Add a generic distributed-runtime abstraction first** — rejected because the existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
 
@@ -64,6 +60,6 @@ A credential-gated Loader composition creates real E2B sandboxes and exercises F
 
 ## Consequences
 
-The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
+The three-package composition demonstrates that filesystem and subprocess are the sufficient provider seams for moving an agent's mutable coding world off-host without changing the loop, higher capability implementations, or model-facing tool packages. Fixes to Bash, PTY, LSP, and Code Runtime remain provider-neutral. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or PTY session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, command callbacks are text-decoded rather than arbitrary binary streams, exact terminal stdin-wait inspection is unavailable, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; Code Runtime uses validated ASCII/base64 framing; the exercised LSP path carries valid UTF-8 JSON. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 4d39ed7eb0..111d7aa63f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -12,27 +12,23 @@ Status: implemented
 
 ## 决策
 
-E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专用包（package）位于 `packages/e2b/` 下，同时保留按 seam 区分的 npm 名称：
+E2B 集成是一个选择性启用的提供方组合 POC。它的 3 个 E2B 专用包（package）集中位于 `packages/e2b/` 下：
 
 - `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
-- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
-- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
-- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B 内有界且不跟随链接的辅助程序读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
-- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
-- 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
+- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands、字节 PTY 和远程 Linux 进程组之上实现 `ctx.subprocess`。
 
-该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口与面向模型的工具。
+上层功能使用提供方无关的实现。`dsh-bash-local` 把命令机制委托给 `ctx.subprocess`；`dsh-pty-local` 把终端分配与信号发送委托给 `ctx.subprocess.spawnTerminal()`；`dsh-lsp-local` 通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动；`dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 启动它。这些通用接口与消费方由[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)负责定义。
 
-这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理位于 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
+E2B 所有者是沙箱身份的唯一真源。其两个适配器绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口、通用实现、面向模型的工具与 agent loop（智能体循环）。
 
 ## POC 边界
 
-E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
+E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调，并在异步查找前台进程组的过程中保留发送操作身份。LSP 会安装一个有界的远程源码读取器，通过不跟随符号链接打开的目录描述符在规范化工作区下逐级遍历。Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内，并为每个 controller 分配一个进程组，在 controller 继承的管道排空前终止该组。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用 UTF-8 JSON；E2B 的已解码回调传输并非任意二进制通道。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -40,7 +36,7 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 ## 验证
 
-聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号身份／默认环境清理／终端会话清理、基于描述符逐级遍历的有界 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道及后代进程所持管道的排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
 凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
@@ -50,13 +46,13 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 **在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
 
-**把所有 E2B 功能放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统、进程管理、PTY、LSP 与 Code Runtime 各自保留独立的提供方契约、配置、测试和消费方；Bash 继续复用其进程管理 seam。
+**把所有 E2B 操作放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统与进程管理各自保留独立的提供方契约、测试和消费方；所有者只公开一个共享 SDK 句柄，不会因此包揽各类功能。
 
 **仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
 
-**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
+**保留 E2B 专用的 PTY、LSP 与 Code Runtime 包。** 不予采纳，因为它们的领域行为不会随 E2B 改变。这些浅层适配器为了替换文件系统与进程操作而重复现有消费方；把这些操作移到基础 seam 之后，可让所有提供方共享同一套就绪判定、协议、绑定与呈现行为实现。
 
-**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
+**从上层功能直接调用 E2B Filesystem、Commands 或 PTY API。** 不予采纳，因为这会绕过 `ctx.fs` 与 `ctx.subprocess` 契约，在每个消费方中重复执行环境策略，并使面向模型的行为产生分叉。进程管理 seam 纳入不可约简的终端原语，因为普通管道无法提供前台进程组或全会话清理。
 
 **先添加通用分布式运行时抽象。** 不予采纳，因为现有功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
 
@@ -64,6 +60,6 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 ## 后果
 
-这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
+这个由 3 个包组成的组合证明，文件系统与进程管理这两个提供方 seam 足以把 agent 的可变 coding 环境移出宿主，而无需改变循环、上层功能实现或面向模型的工具包。Bash、PTY、LSP 与 Code Runtime 的修复仍与提供方无关。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或 PTY 会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，命令回调传递的是已解码文本而非任意二进制流，无法精确检查终端 stdin 等待状态，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；Code Runtime 使用经过验证的 ASCII/base64 分帧；已演练的 LSP 路径承载有效的 UTF-8 JSON。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 877172c343..32d7049c5d 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,6 +1,6 @@
 # POC overlay: keep the advanced headless agent and model-facing tools, but
-# place its filesystem, processes, terminals, language servers, and Code Mode
-# execution in one short-lived E2B sandbox.
+# place its filesystem and process substrate in one short-lived E2B sandbox;
+# the generic Bash, PTY, LSP, and Code Runtime consumers compose above them.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
@@ -32,18 +32,25 @@
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
             name: '@deepseek-ai/dsh-fs-e2b'
-          - id: code-runtime-e2b
-            name: '@deepseek-ai/dsh-code-runtime-e2b'
+          - id: code-runtime-subprocess
+            name: '@deepseek-ai/dsh-code-runtime-subprocess'
+          - id: sandbox
+            name: '@deepseek-ai/dsh-sandbox-local'
+          - id: sandbox-policy
+            name: '@deepseek-ai/dsh-sandbox-policy'
+            config:
+              mode: danger-full-access
+              workspaceRoot: !!js process.cwd()
           - id: pty
             name: '@deepseek-ai/dsh-pty'
-          - id: pty-e2b
-            name: '@deepseek-ai/dsh-pty-e2b'
+          - id: pty-local
+            name: '@deepseek-ai/dsh-pty-local'
           - id: tool-pty
             name: '@deepseek-ai/dsh-tool-pty'
           - id: lsp
             name: '@deepseek-ai/dsh-lsp'
-          - id: lsp-e2b
-            name: '@deepseek-ai/dsh-lsp-e2b'
+          - id: lsp-local
+            name: '@deepseek-ai/dsh-lsp-local'
             config:
               servers:
                 typescript:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index a997752711..aeb447b0e8 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,15 +1,14 @@
 import { readFile } from 'node:fs/promises'
 import { posix, resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
-import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-code-runtime-e2b'
+import type {} from '@deepseek-ai/dsh-code-runtime-subprocess'
 import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
-import type {} from '@deepseek-ai/dsh-lsp-e2b'
-import type {} from '@deepseek-ai/dsh-pty-e2b'
+import type {} from '@deepseek-ai/dsh-lsp-local'
+import type {} from '@deepseek-ai/dsh-pty-local'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
@@ -24,10 +23,10 @@ const owner: Agent = {
   status: 'idle',
   acceptsNextStep: false,
   ctx: ownerFiber.ctx,
-  followup: () => AgentMessageId('unused'),
-  steer: () => AgentMessageId('unused'),
-  inject: () => AgentMessageId('unused'),
-  send: () => AgentMessageId('unused'),
+  followup() {},
+  steer() {},
+  inject() {},
+  send() {},
   cancel() {},
   whenIdle: () => Promise.resolve(),
 }
@@ -159,7 +158,7 @@ try {
   const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   let containmentFaultInjected = false
   remoteCommands.run = async (command, options) => {
-    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-parent/source.ts')) {
+    if (!containmentFaultInjected && command.includes('dsh-e2b-bounded-reader') && command.includes('swapped-parent/source.ts')) {
       containmentFaultInjected = true
       await runRemoteCommand(
         `rm -rf -- ${quoteE2BShellArg(swappedParentPath)} && ln -s -- ${quoteE2BShellArg(swappedOutsidePath)} ${quoteE2BShellArg(swappedParentPath)}`,
@@ -194,7 +193,7 @@ try {
       workspaceRoot: process.cwd(),
     })
   } catch (error: unknown) {
-    lspDocumentBound = String(error).includes('over the 4000000-byte limit')
+    lspDocumentBound = String(error).includes('exceeds the 4000000-byte limit')
     if (!lspDocumentBound) throw error
   }
   if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 65bd3d5246..93bb6b65e5 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -21,22 +21,33 @@
 - id: agents
   name: '@deepseek-ai/dsh-agent'
 
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: danger-full-access
+    workspaceRoot: !!js process.cwd()
+
 - id: pty
   name: '@deepseek-ai/dsh-pty'
 
-- id: pty-e2b
-  name: '@deepseek-ai/dsh-pty-e2b'
+- id: pty-local
+  name: '@deepseek-ai/dsh-pty-local'
   config:
     pollIntervalMs: 25
+    exactProbeAfterMs: 150
     idleSilenceMs: 2000
+    handoffGraceMs: 500
     timeoutMs: 5000
     disposeGraceMs: 1000
 
 - id: lsp
   name: '@deepseek-ai/dsh-lsp'
 
-- id: lsp-e2b
-  name: '@deepseek-ai/dsh-lsp-e2b'
+- id: lsp-local
+  name: '@deepseek-ai/dsh-lsp-local'
   config:
     servers:
       fixture:
@@ -48,8 +59,8 @@
         shutdownTimeoutMs: 1000
         killGraceMs: 500
 
-- id: code-runtime-e2b
-  name: '@deepseek-ai/dsh-code-runtime-e2b'
+- id: code-runtime-subprocess
+  name: '@deepseek-ai/dsh-code-runtime-subprocess'
   config:
     computeMs: 500
     maxWallMs: 5000
diff --git a/examples/package.json b/examples/package.json
index 8dd631e760..e4251c9475 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -43,12 +43,10 @@
     "@deepseek-ai/dsh-llm-replay": "workspace:*",
     "@deepseek-ai/dsh-loader-smoke": "workspace:*",
     "@deepseek-ai/dsh-lsp": "workspace:*",
-    "@deepseek-ai/dsh-lsp-e2b": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
     "@deepseek-ai/dsh-permission": "workspace:*",
     "@deepseek-ai/dsh-plan-mode": "workspace:*",
     "@deepseek-ai/dsh-pty": "workspace:*",
-    "@deepseek-ai/dsh-pty-e2b": "workspace:*",
     "@deepseek-ai/dsh-pty-local": "workspace:*",
     "@deepseek-ai/dsh-pwsh-local": "workspace:*",
     "@deepseek-ai/dsh-repeat-tool-guard": "workspace:*",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index a0827779db..f101375bc6 100644
--- 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: 7dc52943e488a14e0c055ac72be0b2ad6f752455
-README.zh.md: bc3dbf0b4533d1d6adf6d49b0376a3dcdd6bfdb5
+README.md: 1fd0c9c2385f3169791a28f3ef50bb42792760af
+README.zh.md: f9f7d5ae8839ea7033a349ac7a0083a97780a21c
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 1667c88273..86a316dca7 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 层级结构
 
-组在 `packages/<group>/<pkg>/` 容纳包；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 是规范的包／ctx 键映射。**
+包按组置于 `packages/<group>/<pkg>/`；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 负责包／ctx 键映射。**
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index d3472a697e..10c721446f 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
-README.md: 4b14c6fad5d1e491faeb54c9cb0e4403c8e2d8dd
-README.zh.md: c522917835b562cf7648d8bc78f0315b7c52d2d2
+README.md: 35196a0b4fba5cd0388246a70354308ece08b39f
+README.zh.md: 49871c38c540addd06f5d24793ae00b45e2f8bb0
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 4b14c6fad5..fbe387e4ea 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -46,7 +46,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **OS processes a program spawns survive this backend's termination** — `worker.terminate()` ends only the thread; deployments needing remote process-group cleanup can select the E2B backend, whose separate limitations still apply.
+- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only; deployments requiring process-tree cleanup select `dsh-code-runtime-subprocess`, whose mounted subprocess provider owns that cleanup.
 - **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
 - **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index c522917835..57f2a1145a 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -46,7 +46,7 @@ SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的
 
 ## 已知限制与暂缓工作
 
-- **程序 spawn 的 OS 进程在该后端终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理远程进程组的部署可以选择 E2B 后端，但该后端自身的限制仍然适用。
+- **程序 spawn 的 OS 进程在终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理进程树的部署应选择 `dsh-code-runtime-subprocess`，由其挂载的子进程提供方负责该清理。
 - **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：依赖的行为由单元测试固定；如其发生变化，amaro／sucrase 是已经点名的直接替代品。
 - **`computeMs` 到期最多可能超过一个轮询间隔**：系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
 - **程序获得一个含 5 种方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 1ded2a1d34..9b56a3ef55 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: b25f00fb5f32643008127f0cee4f3d758018404a
-README.zh.md: fc3d6901f3cdf6c645cfde49dc46108759959aca
+README.md: ef2e5ef49056e6688630e785a61c01fa53febbb1
+README.zh.md: d76b05f9b60bc471c1793decd1def1d15615c852
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index b25f00fb5f..ef2e5ef490 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -2,15 +2,14 @@
 
 English | [中文](README.zh.md)
 
-An experimental provider-composition POC that places the mutable coding world in one E2B Linux sandbox. The shared owner is separate from capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
+An experimental provider-composition POC that places one filesystem/process execution world in an E2B Linux sandbox. E2B supplies only sandbox lifecycle and the two fundamental OS adapters; provider-neutral consumers build higher capabilities above them.
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
-| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
-| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
-| [`lsp-e2b`](lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
-| [`code-runtime-e2b`](code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), [`dsh-lsp-local`](../lsp/lsp-local/README.md), and [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
+
+This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary; the [portable-consumer decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns the generic composition.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index fc3d6901f3..d76b05f9b6 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -2,15 +2,14 @@
 
 [English](README.md) | 中文
 
-这是一个实验性提供方组合 POC，把可变的编码环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
+这是一个实验性提供方组合 POC，把一个文件系统／进程执行环境放进 E2B Linux 沙箱。E2B 只提供沙箱生命周期与两个基础 OS 适配器；提供方无关的消费方在其上构建更高层能力。
 
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
 | [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
-| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
-| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
-| [`lsp-e2b`](lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
-| [`code-runtime-e2b`](code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md)、[`dsh-lsp-local`](../lsp/lsp-local/README.md) 及 [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
+
+该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界；[可移植消费方决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)界定通用组合。
diff --git a/packages/e2b/code-runtime-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
deleted file mode 100644
index eb4e75f297..0000000000
--- a/packages/e2b/code-runtime-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/e2b/code-runtime-e2b/README.md
-README.md: a8623f95d16b54b29e53bb9cf2c528b36f121283
-README.zh.md: 2b4a37864e3c6755a74f0d2ef6ce38aa39aae24b
diff --git a/packages/e2b/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
deleted file mode 100644
index a8623f95d1..0000000000
--- a/packages/e2b/code-runtime-e2b/README.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# @deepseek-ai/dsh-code-runtime-e2b
-
-English | [中文](README.zh.md)
-
-E2B implementation of [`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
-
-## Configuration
-
-| Key | Default | Meaning |
-|---|---|---|
-| `computeMs` | `60000` | Remote worker event-loop busy-time budget. |
-| `maxWallMs` | `600000` | Host-observed wall-clock ceiling. |
-| `maxOutputBytes` | `67108864` | Combined serialized outer logs/value/diagnostic cap. |
-| `maxOldGenerationSizeMb` | `512` | Remote worker old-generation heap cap in MiB. |
-| `maxFrameBytes` | `268435456` | Largest decoded bridge frame, including binding traffic. |
-| `killGraceMs` | `2000` | Remote process-group TERM-to-KILL grace. |
-
-Every value is a positive safe integer. `maxOutputBytes` is at least four bytes, `maxWallMs` cannot exceed Node's maximum timer delay, and `maxFrameBytes` cannot be smaller than `maxOutputBytes`. The service requires the concrete `dsh-subprocess-e2b` backend so run cleanup has remote process-group semantics.
-
-## Execution and bridge contract
-
-Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller process group whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; completion kills the controller group before draining its pipes and emitting the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in either managed group stop with the run.
-
-The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
-
-Program failures resolve as `CodeRunResult.error`; only seam misuse rejects. `isolation` is reported as `container`, which is a deployment descriptor rather than a security claim.
-
-## Model Experience
-
-Indirectly, through Code Mode in `dsh-tools`, which returns program logs, values, or typed failures through the existing `run_code` result contract.
-
-#### KV Cache effect
-
-No direct invalidation; Code Mode owns request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **Not a whole-agent runtime** — Cordis, sessions, LLM calls, binding dispatch, TypeScript stripping, output ledgers, and E2B SDK state remain on the host.
-- **No reconnectable runs** — retaining a sandbox preserves files but not worker/subprocess handles, binding calls, timers, or output cursors.
-- **Node worker internals share the model realm** — mutating realm-wide globals or prototypes that Node itself uses can terminate the worker; captured adapter intrinsics are not a separate JavaScript realm or a security boundary.
-- **Deliberate process-group escape is not captured** — model code can create a new POSIX session; that unmanaged process is outside this backend's cleanup identity.
-- **Intermediate binding traffic is memory-bounded only per frame** — it does not enter model context or the outer-output ledger, but aggregate host/remote process memory remains the limit.
-- **Experimental type stripping** — the backend shares the worker implementation's reliance on Node's experimental erasable-syntax API.
-- **Sandbox policy is template-owned** — this package adds no network, volume, snapshot, or workspace-synchronization policy.
diff --git a/packages/e2b/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
deleted file mode 100644
index 2b4a37864e..0000000000
--- a/packages/e2b/code-runtime-e2b/README.zh.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# @deepseek-ai/dsh-code-runtime-e2b
-
-[English](README.md) | 中文
-
-[`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
-
-## 配置
-
-| 配置键 | 默认值 | 含义 |
-|---|---|---|
-| `computeMs` | `60000` | 远程 worker 的事件循环忙碌时间预算。 |
-| `maxWallMs` | `600000` | 宿主观测到的墙钟时间上限。 |
-| `maxOutputBytes` | `67108864` | 外层日志、值和诊断合计的序列化上限。 |
-| `maxOldGenerationSizeMb` | `512` | 远程 worker 的老生代堆上限（MiB）。 |
-| `maxFrameBytes` | `268435456` | 已解码桥接帧的最大大小，包括绑定流量。 |
-| `killGraceMs` | `2000` | 远程进程组 TERM 到 KILL 的宽限期。 |
-
-每个值都必须是正的安全整数。`maxOutputBytes` 必须至少为 4 字节，`maxWallMs` 不得超过 Node 的最大定时器延迟，且 `maxFrameBytes` 不得小于 `maxOutputBytes`。本服务要求使用具体的 `dsh-subprocess-e2b` 后端，使运行清理具备远程进程组语义。
-
-## 执行与桥接契约
-
-设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller 进程组，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；运行结算会先终止 controller 进程组，再排空其管道并发出终结帧。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此任一受管组内的普通子进程会随本次运行一同停止。
-
-由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
-
-程序失败会 resolve 为 `CodeRunResult.error`；只有 seam 误用才会 reject。`isolation` 报告为 `container`；这是部署描述符，不构成安全声明。
-
-## 模型体验
-
-通过 `dsh-tools` 中的 Code Mode 间接影响模型；它会通过现有 `run_code` 结果契约返回程序日志、值或类型化失败。
-
-#### KV Cache 影响
-
-不会直接失效；请求前缀变更由 Code Mode 负责。
-
-## 已知限制与暂缓工作
-
-- **并非完整的 agent（智能体）运行时**：Cordis、会话、LLM（大语言模型）调用、绑定分发、TypeScript 类型剥离、输出账本和 E2B SDK 状态仍保留在宿主侧。
-- **运行不可重连**：保留沙箱会保留文件，但不会保留 worker／进程管理句柄、绑定调用、定时器或输出游标。
-- **Node worker 内部机制与模型共享同一 realm**：修改 Node 自身使用、影响整个 realm 的全局对象或原型可能会终止 worker；已捕获的适配器 intrinsic 并不构成独立的 JavaScript realm 或安全边界。
-- **不会捕获有意逃逸进程组的行为**：模型代码可以创建新的 POSIX 会话；该非受管进程不属于此后端的清理身份范围。
-- **中间绑定流量的内存边界仅适用于单帧**：它不会进入模型上下文或外层输出账本，但其总量仍只受宿主／远程进程内存限制。
-- **实验性类型剥离**：该后端与 worker 实现一样，依赖 Node 的实验性可擦除语法 API。
-- **沙箱策略归模板负责**：本包不会额外增加网络、卷、快照或工作区同步策略。
diff --git a/packages/e2b/code-runtime-e2b/package.json b/packages/e2b/code-runtime-e2b/package.json
deleted file mode 100644
index 222ae71bef..0000000000
--- a/packages/e2b/code-runtime-e2b/package.json
+++ /dev/null
@@ -1,52 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-code-runtime-e2b",
-  "description": "E2B code-runtime implementation for DeepSeek Harness",
-  "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"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
-    "@deepseek-ai/dsh-code-runtime-worker": "^0.0.1",
-    "@deepseek-ai/dsh-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-timeout": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-code-runtime": "workspace:^",
-    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
-    "@deepseek-ai/dsh-e2b": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
-    "@deepseek-ai/dsh-timeout": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
-  }
-}
diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
deleted file mode 100644
index c37cb3cc64..0000000000
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ /dev/null
@@ -1,494 +0,0 @@
-/** E2B process/worker implementation of the harness code-runtime seam. */
-
-import { posix } from 'node:path'
-import { stripTypeScriptTypes } from 'node:module'
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type {
-  CodeBindingNamespace,
-  CodeJsonValue,
-  CodeRunFailure,
-  CodeRunRequest,
-  CodeRunResult,
-} from '@deepseek-ai/dsh-code-runtime'
-import {
-  E2BFrameDecoder,
-  encodeBoundedE2BFrame,
-  quoteE2BShellArg,
-  resolveE2BExecutable,
-} from '@deepseek-ai/dsh-e2b'
-import {
-  decodeWorkerJson,
-  encodeWorkerJson,
-  OutputLedger,
-} from '@deepseek-ai/dsh-code-runtime-worker'
-import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker'
-import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
-import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { CODE_RUNNER_SOURCE } from './runner-source.ts'
-
-/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
-export interface Config {
-  /** Remote worker measured event-loop busy-time budget. */
-  computeMs?: number
-  /** Host-observed wall-clock ceiling. */
-  maxWallMs?: number
-  /** Combined serialized outer logs/value/diagnostic cap. */
-  maxOutputBytes?: number
-  /** Remote worker old-generation heap cap in MiB. */
-  maxOldGenerationSizeMb?: number
-  /** Largest decoded bridge frame, including binding traffic. */
-  maxFrameBytes?: number
-  /** Remote process-group TERM-to-KILL grace. */
-  killGraceMs?: number
-}
-
-type ResolvedConfig = Required<Config>
-type PreparedRuntime = { node: string; runner: string }
-
-interface LiveRun {
-  settle(failure: CodeRunFailure): void
-  finished: Promise<void>
-}
-
-interface CallMessage {
-  type: 'call'
-  id: number
-  global: string
-  name: string
-  args: WorkerJsonWire
-}
-
-interface LogMessage {
-  type: 'log'
-  text: string
-}
-
-interface DoneMessage {
-  type: 'done'
-  value?: WorkerJsonWire
-  error?: CodeRunFailure
-}
-
-type RunnerMessage = CallMessage | LogMessage | DoneMessage | { type: 'output-limit' }
-
-const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
-const MIN_OUTPUT_BYTES = 4
-const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
-/* jscpd:ignore-start -- Backends enforce the same injected-global vocabulary without coupling lifecycle implementations. */
-const RESERVED_WORDS = new Set([
-  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
-  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
-  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
-  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
-  'private', 'protected', 'public', 'arguments', 'eval',
-])
-const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
-/* jscpd:ignore-end */
-const FAILURE_KINDS = new Set<CodeRunFailure['kind']>([
-  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
-])
-
-function messageOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
-
-function parseRunnerMessage(raw: unknown): RunnerMessage | undefined {
-  if (typeof raw !== 'object' || raw === null) return undefined
-  const record = raw as Record<string, unknown>
-  if (record.type === 'output-limit') return { type: 'output-limit' }
-  if (record.type === 'log') return typeof record.text === 'string' ? { type: 'log', text: record.text } : undefined
-  if (record.type === 'call') {
-    if (!Number.isSafeInteger(record.id) || (record.id as number) < 1 || typeof record.global !== 'string' || typeof record.name !== 'string' || !Array.isArray(record.args)) return undefined
-    return { type: 'call', id: record.id as number, global: record.global, name: record.name, args: record.args as WorkerJsonWire }
-  }
-  if (record.type !== 'done') return undefined
-  if (record.error === undefined) {
-    return { type: 'done', ...record.value === undefined ? {} : { value: record.value as WorkerJsonWire } }
-  }
-  if (typeof record.error !== 'object' || record.error === null) return undefined
-  const error = record.error as Record<string, unknown>
-  if (typeof error.kind !== 'string' || !FAILURE_KINDS.has(error.kind as CodeRunFailure['kind']) || typeof error.message !== 'string') return undefined
-  return { type: 'done', error: { kind: error.kind as CodeRunFailure['kind'], message: error.message } }
-}
-
-/** E2B-backed runtime: host-side type stripping, remote worker execution, host binding dispatch. */
-export class E2BCodeRuntime extends CodeRuntime {
-  static inject = ['e2b', 'subprocess']
-
-  static Config: z<Config> = z.object({
-    computeMs: z.number().default(60_000),
-    maxWallMs: z.number().default(600_000),
-    maxOutputBytes: z.number().default(67_108_864),
-    maxOldGenerationSizeMb: z.number().default(512),
-    maxFrameBytes: z.number().default(268_435_456),
-    killGraceMs: z.number().default(2_000),
-  })
-
-  readonly language = 'typescript'
-  readonly isolation = 'container'
-
-  private readonly config: ResolvedConfig
-  private readonly ready: Promise<PreparedRuntime>
-  private readonly live = new Set<LiveRun>()
-  private readonly subprocess: E2BSubprocessService
-  private disposed = false
-
-  constructor(ctx: Context, config: Config) {
-    super(ctx)
-    if (!(ctx.subprocess instanceof E2BSubprocessService)) {
-      throw new Error('code-runtime-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
-    }
-    this.subprocess = ctx.subprocess
-    this.config = config as ResolvedConfig
-    for (const [key, value] of Object.entries(this.config)) {
-      if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`code-runtime-e2b: config.${key} must be a positive safe integer`)
-      }
-    }
-    if (this.config.maxOutputBytes < MIN_OUTPUT_BYTES) {
-      throw new Error(`code-runtime-e2b: config.maxOutputBytes must be at least ${MIN_OUTPUT_BYTES}`)
-    }
-    if (this.config.maxWallMs > MAX_TIMER_DELAY_MS) {
-      throw new Error(`code-runtime-e2b: config.maxWallMs must be at most ${MAX_TIMER_DELAY_MS}`)
-    }
-    if (this.config.maxFrameBytes < this.config.maxOutputBytes) {
-      throw new Error('code-runtime-e2b: config.maxFrameBytes must be at least maxOutputBytes')
-    }
-    this.ready = this.prepare()
-    void this.ready.catch(() => {})
-    ctx.effect(() => () => this.teardown(), 'E2B code-runtime teardown')
-  }
-
-  /* jscpd:ignore-start -- Seam-level abort and type-strip results remain identical across execution substrates. */
-  /** Execute one type-stripped program in a fresh E2B worker process. */
-  async run(request: CodeRunRequest): Promise<CodeRunResult> {
-    if (this.disposed) throw new Error('code-runtime-e2b: run() after disposal')
-    const bindings = this.validateBindings(request)
-    if (request.signal?.aborted === true) {
-      return this.failure({ kind: 'abort', message: String(request.signal.reason) })
-    }
-    let code: string
-    try {
-      const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + request.program + STRIP_WRAP.suffix)
-      code = stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
-    } catch (error: unknown) {
-      return this.failure({ kind: 'exception', message: messageOf(error) })
-    }
-    let runtime: PreparedRuntime | undefined
-    try {
-      runtime = await this.awaitPreparation(request.signal)
-    } catch (error: unknown) {
-      // Disposal can race the awaited setup despite the synchronous precheck.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
-      return this.failure({ kind: 'worker-exit', message: `E2B runtime setup failed: ${messageOf(error)}` })
-    }
-    if (runtime === undefined) {
-      return this.failure({ kind: 'abort', message: String(request.signal?.reason) })
-    }
-    // Disposal can race the awaited remote setup after the pre-await check.
-    /* v8 ignore start -- requires disposal between promise resolution and its awaiting continuation. */
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
-    /* v8 ignore stop */
-    return await this.execute(request, code, bindings, runtime)
-  }
-  /* jscpd:ignore-end */
-
-  private async awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
-    if (signal === undefined) return await this.ready
-    const aborted = Promise.withResolvers<undefined>()
-    const onAbort = (): void => { aborted.resolve(undefined) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    if (signal.aborted) {
-      signal.removeEventListener('abort', onAbort)
-      return undefined
-    }
-    try {
-      return await Promise.race([this.ready, aborted.promise])
-    } finally {
-      signal.removeEventListener('abort', onAbort)
-    }
-  }
-
-  private assertPreparationActive(): void {
-    if (this.disposed) throw new Error('code-runtime-e2b: runtime disposed during setup')
-  }
-
-  private async prepare(): Promise<PreparedRuntime> {
-    const sandbox = await this.ctx.e2b.getSandbox()
-    this.assertPreparationActive()
-    const runner = posix.join(this.ctx.e2b.runtimeRoot, 'code-runtime-runner.mjs')
-    await sandbox.files.write([{ path: runner, data: CODE_RUNNER_SOURCE }])
-    this.assertPreparationActive()
-    await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(runner)}`)
-    this.assertPreparationActive()
-    const node = await resolveE2BExecutable(sandbox, 'node')
-    this.assertPreparationActive()
-    return { node, runner }
-  }
-
-  private failure(error: CodeRunFailure): CodeRunResult {
-    return new OutputLedger(this.config.maxOutputBytes).failure([], error)
-  }
-
-  /* jscpd:ignore-start -- Binding names have one seam contract while dispatch and teardown remain backend-owned. */
-  private validateBindings(request: CodeRunRequest): Map<string, CodeBindingNamespace> {
-    const bindings = new Map<string, CodeBindingNamespace>()
-    for (const namespace of request.bindings) {
-      if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
-        throw new Error(`code-runtime-e2b: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
-      }
-      if (namespace.global === 'console' || bindings.has(namespace.global)) {
-        throw new Error(`code-runtime-e2b: duplicate binding global ${JSON.stringify(namespace.global)}`)
-      }
-      bindings.set(namespace.global, namespace)
-    }
-    const errorClassNames = new Set<string>()
-    for (const namespace of request.bindings) {
-      const descriptor = namespace.errorClass
-      if (descriptor === undefined) continue
-      if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
-        throw new Error(`code-runtime-e2b: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
-      }
-      if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
-        throw new Error(`code-runtime-e2b: duplicate injected global ${JSON.stringify(descriptor.name)}`)
-      }
-      if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
-        throw new Error(`code-runtime-e2b: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
-      }
-      errorClassNames.add(descriptor.name)
-    }
-    return bindings
-  }
-  /* jscpd:ignore-end */
-
-  private async execute(
-    request: CodeRunRequest,
-    code: string,
-    bindings: Map<string, CodeBindingNamespace>,
-    runtime: PreparedRuntime,
-  ): Promise<CodeRunResult> {
-    let handle: SubprocessHandle
-    try {
-      handle = this.subprocess.spawn({
-        argv: [runtime.node, runtime.runner],
-        cwd: this.ctx.e2b.cwd,
-        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
-        graceMs: this.config.killGraceMs,
-        ...request.signal === undefined ? {} : { signal: request.signal },
-        env: {},
-      })
-    } catch (error: unknown) {
-      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
-      if (request.signal?.aborted === true) {
-        return this.failure({ kind: 'abort', message: String(request.signal.reason) })
-      }
-      return this.failure({ kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` })
-    }
-    if (handle.stdin === undefined || handle.stdout === undefined) {
-      handle.terminate()
-      await Promise.allSettled([handle.done])
-      try {
-        await handle.waitForExit()
-      } catch (error: unknown) {
-        return this.failure({ kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(error)}` })
-      }
-      return this.failure({ kind: 'worker-exit', message: 'E2B subprocess dropped a piped runtime stream' })
-    }
-    const stdin = handle.stdin
-    const stdout = handle.stdout
-
-    return new Promise<CodeRunResult>((resolve) => {
-      const output = new OutputLedger(this.config.maxOutputBytes)
-      const logs: string[] = []
-      const answered = new Set<number>()
-      const decoder = new E2BFrameDecoder(this.config.maxFrameBytes)
-      let settled = false
-      let finishResolve!: () => void
-      const finished = new Promise<void>((done) => { finishResolve = done })
-      const wallTimer: { current: NodeJS.Timeout | undefined } = { current: undefined }
-      const live: LiveRun = {
-        finished,
-        settle: (failure) => { finish(() => output.failure(logs, failure)) },
-      }
-
-      const finish = (result: CodeRunResult | (() => CodeRunResult)): void => {
-        if (settled) return
-        settled = true
-        clearTimeout(wallTimer.current)
-        request.signal?.removeEventListener('abort', onAbort)
-        void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
-          handle.terminate()
-          await handle.done.catch(() => {})
-          let cleanupError: unknown
-          try {
-            await handle.waitForExit()
-          } catch (error: unknown) {
-            cleanupError = error
-          }
-          try {
-            decoder.finish()
-          } catch (error: unknown) {
-            result = output.failure(logs, { kind: 'worker-exit', message: messageOf(error) })
-          }
-          if (cleanupError !== undefined) {
-            result = output.failure(logs, { kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(cleanupError)}` })
-          }
-          const final = typeof result === 'function' ? result() : result
-          this.live.delete(live)
-          finishResolve()
-          resolve(final)
-        })
-      }
-
-      const sendReply = (message: unknown): void => {
-        if (settled) return
-        let frame: string
-        try {
-          frame = encodeBoundedE2BFrame(message, this.config.maxFrameBytes)
-        } catch (error: unknown) {
-          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
-          return
-        }
-        stdin.write(frame, (error?: Error | null) => {
-          if (error !== undefined && error !== null) {
-            finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge write failed: ${error.message}` }))
-          }
-        })
-      }
-
-      /* jscpd:ignore-start -- Host binding resolution mirrors worker semantics over a different transport. */
-      const onCall = (message: CallMessage): void => {
-        if (answered.has(message.id)) return
-        answered.add(message.id)
-        const functions = bindings.get(message.global)?.functions
-        const fn = functions !== undefined && Object.hasOwn(functions, message.name) ? functions[message.name] : undefined
-        if (typeof fn !== 'function') {
-          sendReply({ type: 'reply', id: message.id, ok: false, message: `unknown binding ${JSON.stringify(`${message.global}.${message.name}`)}` })
-          return
-        }
-        const args = decodeWorkerJson(message.args)
-        if (args === undefined) {
-          sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding arguments must be lossless JSON' })
-          return
-        }
-        void (async () => {
-          try {
-            const resolved = await fn(args)
-            let value: CodeJsonValue | undefined
-            try {
-              value = snapshotJsonValue(resolved)
-            } catch {
-              value = undefined
-            }
-            if (value === undefined) {
-              sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding resolution must be lossless JSON' })
-            } else {
-              sendReply({ type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(value) })
-            }
-          } catch (error: unknown) {
-            sendReply({ type: 'reply', id: message.id, ok: false, message: messageOf(error) })
-          }
-        })()
-      }
-      /* jscpd:ignore-end */
-
-      const onMessage = (raw: unknown): void => {
-        if (settled) return
-        const message = parseRunnerMessage(raw)
-        if (message === undefined) return
-        if (message.type === 'log') {
-          if (!output.admit(message.text, logs)) finish(output.limit([...logs, message.text]))
-          return
-        }
-        if (message.type === 'output-limit') {
-          finish(output.limit(logs))
-          return
-        }
-        if (message.type === 'call') {
-          onCall(message)
-          return
-        }
-        if (message.error !== undefined) {
-          finish(() => output.failure(logs, message.error as CodeRunFailure))
-        } else if (message.value === undefined) {
-          finish(() => output.success(logs))
-        } else {
-          const value = decodeWorkerJson(message.value)
-          if (value === undefined) finish(() => output.failure(logs, { kind: 'invalid-output', message: 'program completion must be lossless JSON' }))
-          else finish(() => output.success(logs, value))
-        }
-      }
-
-      stdout.on('data', (chunk: Buffer) => {
-        if (settled) return
-        try {
-          for (const frame of decoder.push(chunk.toString('utf8'))) onMessage(frame)
-        } catch (error: unknown) {
-          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
-        }
-      })
-      stdout.on('error', (error: Error) => {
-        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdout failed: ${error.message}` }))
-      })
-      stdin.on('error', (error: Error) => {
-        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdin failed: ${error.message}` }))
-      })
-      void handle.done.then(
-        () => {
-          if (!settled) {
-            const stderr = handle.collected.stderr?.readFrom(0).text.trim()
-            finish(() => output.failure(logs, { kind: 'worker-exit', message: stderr === undefined || stderr === '' ? 'E2B runtime exited before completing' : `E2B runtime exited before completing: ${stderr}` }))
-          }
-        },
-        (error: unknown) => {
-          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` }))
-        },
-      )
-
-      const onAbort = (): void => {
-        finish(() => output.failure(logs, { kind: 'abort', message: String(request.signal?.reason) }))
-      }
-      request.signal?.addEventListener('abort', onAbort, { once: true })
-      wallTimer.current = setTimeout(() => {
-        finish(() => output.failure(logs, { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` }))
-      }, this.config.maxWallMs)
-      this.live.add(live)
-      if (request.signal?.aborted === true) {
-        onAbort()
-        return
-      }
-      sendReply({
-        type: 'boot',
-        code,
-        namespaces: [...bindings].map(([global, namespace]) => ({
-          global,
-          names: Object.keys(namespace.functions),
-          ...namespace.errorClass === undefined ? {} : { errorClass: namespace.errorClass },
-        })),
-        computeMs: this.config.computeMs,
-        maxOutputBytes: this.config.maxOutputBytes,
-        maxOldGenerationSizeMb: this.config.maxOldGenerationSizeMb,
-      })
-    })
-  }
-
-  /* jscpd:ignore-start -- Code-runtime backends share the service lifecycle but own different child identities. */
-  private async teardown(): Promise<void> {
-    this.disposed = true
-    const runs = [...this.live]
-    for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
-    await Promise.all([
-      this.ready.then(() => {}, () => {}),
-      ...runs.map(run => run.finished),
-    ])
-  }
-  /* jscpd:ignore-end */
-}
-
-export default E2BCodeRuntime
diff --git a/packages/e2b/code-runtime-e2b/src/invariant.ts b/packages/e2b/code-runtime-e2b/src/invariant.ts
deleted file mode 100644
index 4112cdc76b..0000000000
--- a/packages/e2b/code-runtime-e2b/src/invariant.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-code-runtime-e2b`. */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-code-runtime-e2b'
-
-/** Cordis companion plugin name. */
-export const name = 'code-runtime-e2b-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/** No runtime invariant: the service owns every one-shot remote run. */
-const install: InvariantInstaller = () => {}
-
-/** Register this package's invariant companion. */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/e2b/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
deleted file mode 100644
index 527f21114e..0000000000
--- a/packages/e2b/code-runtime-e2b/src/runner-source.ts
+++ /dev/null
@@ -1,649 +0,0 @@
-/** Dependency-free remote code runner installed inside the E2B sandbox. */
-
-/** Node program that runs one model program in a fresh remote worker thread. */
-export const CODE_RUNNER_SOURCE = String.raw`import { Buffer } from 'node:buffer'
-import { fork } from 'node:child_process'
-import { inspect } from 'node:util'
-import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
-import { createInterface } from 'node:readline'
-import { fileURLToPath } from 'node:url'
-
-const emitFrame = message => {
-  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
-}
-
-const parseFrame = line => JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
-
-const waitForPipeDrain = stream => {
-  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
-  return new Promise(resolve => {
-    const done = () => {
-      stream.off('end', done)
-      stream.off('close', done)
-      stream.off('error', done)
-      resolve()
-    }
-    stream.once('end', done)
-    stream.once('close', done)
-    stream.once('error', done)
-    if (stream.readableEnded || stream.destroyed) done()
-  })
-}
-
-const waitForChildExit = child => {
-  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise(resolve => { child.once('exit', resolve) })
-}
-
-const killControllerGroup = child => {
-  if (process.platform !== 'win32' && Number.isSafeInteger(child.pid)) {
-    try {
-      process.kill(-child.pid, 'SIGKILL')
-    } catch (error) {
-      if (!error || typeof error !== 'object' || error.code !== 'ESRCH') throw error
-    }
-    return
-  }
-  child.kill('SIGKILL')
-}
-
-const jsonStringBytes = text => Buffer.byteLength(JSON.stringify(text))
-
-const truncateLog = (text, available) => {
-  if (available < 2) return ''
-  let result = ''
-  let bytes = 2
-  for (const character of text) {
-    const cost = jsonStringBytes(character) - 2
-    if (bytes + cost > available) break
-    bytes += cost
-    result += character
-  }
-  return result
-}
-
-const runLauncher = () => {
-  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  let controller
-  let maxOutputBytes = 0
-  let logBytes = 2
-  let logEntries = 0
-  let settling = false
-  let closed = false
-  let terminal
-
-  const finish = message => {
-    if (settling) {
-      if (message.type === 'output-limit') terminal = message
-      return
-    }
-    settling = true
-    terminal = message
-    const current = controller
-    controller = undefined
-    const drain = current
-      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
-          const stdoutDrained = waitForPipeDrain(current.stdout)
-          const stderrDrained = waitForPipeDrain(current.stderr)
-          const exited = waitForChildExit(current)
-          killControllerGroup(current)
-          await Promise.all([exited, stdoutDrained, stderrDrained])
-        })
-      : Promise.resolve()
-    void drain.catch(error => {
-      process.stderr.write('code-runtime-e2b controller cleanup error: ' + String(error) + '\n')
-    }).then(() => {
-      closed = true
-      emitFrame(terminal)
-      input.close()
-      process.stdin.destroy()
-    })
-  }
-
-  const forwardLog = text => {
-    if (closed || terminal?.type === 'output-limit') return
-    const separator = logEntries > 0 ? 1 : 0
-    const available = maxOutputBytes - logBytes - separator
-    const cost = jsonStringBytes(text)
-    if (cost > available) {
-      const prefix = truncateLog(text, available)
-      if (prefix) {
-        logBytes += jsonStringBytes(prefix) + separator
-        logEntries += 1
-        emitFrame({ type: 'log', text: prefix })
-      }
-      finish({ type: 'output-limit' })
-      return
-    }
-    logBytes += cost + separator
-    logEntries += 1
-    emitFrame({ type: 'log', text })
-  }
-
-  const startController = message => {
-    maxOutputBytes = message.maxOutputBytes
-    controller = fork(fileURLToPath(import.meta.url), [], {
-      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
-      detached: process.platform !== 'win32',
-      execArgv: [],
-      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-    })
-    const current = controller
-    current.stdout.on('data', data => { forwardLog(data.toString('utf8')) })
-    current.stderr.on('data', data => { forwardLog(data.toString('utf8')) })
-    current.on('message', raw => {
-      if (!raw || typeof raw !== 'object') return
-      if (raw.type === 'log' && typeof raw.text === 'string') {
-        forwardLog(raw.text)
-        return
-      }
-      if (settling) return
-      if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
-        emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
-      } else if (raw.type === 'output-limit') {
-        finish({ type: 'output-limit' })
-      } else if (raw.type === 'done') {
-        if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
-          finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
-        } else if (raw.value === undefined || Array.isArray(raw.value)) {
-          finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
-        }
-      }
-    })
-    current.on('error', error => {
-      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller error: ' + error.message } })
-    })
-    current.on('exit', code => {
-      if (!settling) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller exited with code ' + code + ' before completing' } })
-    })
-    current.send(message, error => {
-      if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller boot failed: ' + error.message } })
-    })
-  }
-
-  input.on('line', line => {
-    let message
-    try {
-      message = parseFrame(line)
-    } catch (error) {
-      process.stderr.write('code-runtime-e2b frame error: ' + String(error) + '\n')
-      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
-      return
-    }
-    if (!controller) {
-      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces) || !Number.isSafeInteger(message.maxOutputBytes) || message.maxOutputBytes < 4) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
-        return
-      }
-      startController(message)
-      return
-    }
-    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
-      controller.send(message.ok
-        ? { type: 'reply', id: message.id, ok: true, value: message.value }
-        : { type: 'reply', id: message.id, ok: false, message: String(message.message) }, error => {
-          if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller reply failed: ' + error.message } })
-        })
-    }
-  })
-  input.on('close', () => { if (controller && !settling) killControllerGroup(controller) })
-}
-
-const runController = () => {
-  let worker
-  let finished = false
-  let computeTimer
-  const send = message => {
-    if (process.send) process.send(message)
-  }
-  const finish = message => {
-    if (finished) return
-    finished = true
-    clearInterval(computeTimer)
-    const current = worker
-    worker = undefined
-    const drain = current
-      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
-          const stdoutDrained = waitForPipeDrain(current.stdout)
-          const stderrDrained = waitForPipeDrain(current.stderr)
-          await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
-        })
-      : Promise.resolve()
-    void drain.catch(error => {
-      send({ type: 'log', text: 'code-runtime-e2b worker cleanup error: ' + String(error) + '\n' })
-    }).then(() => {
-      if (!process.send) {
-        process.exitCode = 1
-        return
-      }
-      process.send(message, () => { if (process.connected) process.disconnect() })
-    })
-  }
-  process.on('message', message => {
-    if (!worker) {
-      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces)) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
-        return
-      }
-      worker = new Worker(new URL(import.meta.url), {
-        workerData: message,
-        env: {},
-        execArgv: [],
-        stdout: true,
-        stderr: true,
-        resourceLimits: { maxOldGenerationSizeMb: message.maxOldGenerationSizeMb },
-      })
-      worker.stdout.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
-      worker.stderr.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
-      worker.on('message', raw => {
-        if (!raw || typeof raw !== 'object') return
-        if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
-          send({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
-        } else if (raw.type === 'log' && typeof raw.text === 'string') {
-          send({ type: 'log', text: raw.text })
-        } else if (raw.type === 'output-limit') {
-          finish({ type: 'output-limit' })
-        } else if (raw.type === 'done') {
-          if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
-            finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
-          } else if (raw.value === undefined || Array.isArray(raw.value)) {
-            finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
-          }
-        }
-      })
-      worker.on('error', error => {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker error: ' + error.message } })
-      })
-      worker.on('exit', code => {
-        if (!finished) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker exited with code ' + code + ' before completing' } })
-      })
-      computeTimer = setInterval(() => {
-        if (!worker) return
-        if (worker.performance.eventLoopUtilization().active > message.computeMs) {
-          finish({ type: 'done', error: { kind: 'timeout', message: 'compute budget exhausted (' + message.computeMs + 'ms busy)' } })
-        }
-      }, 25)
-      return
-    }
-    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
-      worker.postMessage(message.ok
-        ? { type: 'reply', id: message.id, ok: true, value: message.value }
-        : { type: 'reply', id: message.id, ok: false, message: String(message.message) })
-    }
-  })
-  process.on('disconnect', () => { if (worker && !finished) void worker.terminate() })
-}
-
-if (!isMainThread) {
-  const port = parentPort
-  if (!port) throw new Error('remote worker requires parentPort')
-
-  const CapturedError = Error
-  const ArrayIsArray = Array.isArray
-  const ArrayPrototype = Array.prototype
-  const ObjectPrototype = Object.prototype
-  const ObjectCreate = Object.create
-  const ObjectDefineProperty = Object.defineProperty
-  const ObjectGetPrototypeOf = Object.getPrototypeOf
-  const ObjectHasOwn = Object.hasOwn
-  const ObjectKeys = Object.keys
-  const ObjectIs = Object.is
-  const ObjectPropertyIsEnumerable = Object.prototype.propertyIsEnumerable
-  const ReflectOwnKeys = Reflect.ownKeys
-  const ReflectApply = Reflect.apply
-  const NumberIsFinite = Number.isFinite
-  const NumberIsSafeInteger = Number.isSafeInteger
-  const PromiseCtor = Promise
-  const PromiseReject = Promise.reject
-  const QueueMicrotask = queueMicrotask
-  const BufferByteLength = Buffer.byteLength
-  const SetCtor = Set
-  const SetAdd = Set.prototype.add
-  const SetDelete = Set.prototype.delete
-  const SetHas = Set.prototype.has
-  const MapDelete = Map.prototype.delete
-  const MapGet = Map.prototype.get
-  const MapSet = Map.prototype.set
-  const ArrayJoin = Array.prototype.join
-  const ArrayPop = Array.prototype.pop
-  const StringCharCodeAt = String.prototype.charCodeAt
-  const StringSlice = String.prototype.slice
-  const JSONStringify = JSON.stringify
-  const StringValue = String
-
-  const define = (target, key, value) => {
-    const descriptor = ObjectCreate(null)
-    descriptor.value = value
-    descriptor.enumerable = true
-    descriptor.configurable = true
-    descriptor.writable = true
-    ObjectDefineProperty(target, key, descriptor)
-  }
-  const append = (target, value) => { define(target, target.length, value) }
-  const pop = target => ReflectApply(ArrayPop, target, [])
-  const setAdd = (target, value) => { ReflectApply(SetAdd, target, [value]) }
-  const setDelete = (target, value) => { ReflectApply(SetDelete, target, [value]) }
-  const setHas = (target, value) => ReflectApply(SetHas, target, [value])
-  const mapDelete = (target, key) => { ReflectApply(MapDelete, target, [key]) }
-  const mapGet = (target, key) => ReflectApply(MapGet, target, [key])
-  const mapSet = (target, key, value) => { ReflectApply(MapSet, target, [key, value]) }
-  const plainObject = value => {
-    const prototype = ObjectGetPrototypeOf(value)
-    return prototype === null || prototype === ObjectPrototype
-  }
-  const ownEnumerableStringKeys = value => {
-    const keys = ReflectOwnKeys(value)
-    for (let index = 0; index < keys.length; index++) {
-      const key = keys[index]
-      if (typeof key !== 'string' || !ReflectApply(ObjectPropertyIsEnumerable, value, [key])) return undefined
-    }
-    return keys
-  }
-  const assign = (destination, value) => {
-    if (destination.kind === 'root') destination.holder.value = value
-    else define(destination.target, destination.key, value)
-  }
-  const snapshot = input => {
-    const active = new SetCtor()
-    const holder = ObjectCreate(null)
-    const tasks = [{ kind: 'visit', value: input, destination: { kind: 'root', holder } }]
-    while (tasks.length) {
-      const task = pop(tasks)
-      if (task.kind === 'leave') { setDelete(active, task.source); continue }
-      const candidate = task.value
-      if (candidate === null || typeof candidate === 'boolean' || typeof candidate === 'string') {
-        assign(task.destination, candidate); continue
-      }
-      if (typeof candidate === 'number') {
-        if (!NumberIsFinite(candidate) || ObjectIs(candidate, -0)) return undefined
-        assign(task.destination, candidate); continue
-      }
-      if (typeof candidate !== 'object' || setHas(active, candidate)) return undefined
-      if (ArrayIsArray(candidate)) {
-        if (ObjectGetPrototypeOf(candidate) !== ArrayPrototype || ReflectOwnKeys(candidate).length !== candidate.length + 1) return undefined
-        const target = []
-        assign(task.destination, target)
-        setAdd(active, candidate)
-        append(tasks, { kind: 'leave', source: candidate })
-        for (let index = candidate.length - 1; index >= 0; index--) {
-          if (!ObjectHasOwn(candidate, index)) return undefined
-          append(tasks, { kind: 'visit', value: candidate[index], destination: { kind: 'slot', target, key: index } })
-        }
-        continue
-      }
-      if (!plainObject(candidate)) return undefined
-      const keys = ownEnumerableStringKeys(candidate)
-      if (!keys) return undefined
-      const target = {}
-      assign(task.destination, target)
-      setAdd(active, candidate)
-      append(tasks, { kind: 'leave', source: candidate })
-      for (let index = keys.length - 1; index >= 0; index--) {
-        const key = keys[index]
-        append(tasks, { kind: 'visit', value: candidate[key], destination: { kind: 'slot', target, key } })
-      }
-    }
-    return holder.value
-  }
-  const encodeWire = value => {
-    const wire = []
-    const pending = [value]
-    while (pending.length) {
-      const current = pop(pending)
-      if (current === null || typeof current === 'boolean' || typeof current === 'number' || typeof current === 'string') {
-        append(wire, current); continue
-      }
-      if (ArrayIsArray(current)) {
-        append(wire, { kind: 'array', length: current.length })
-        for (let index = current.length - 1; index >= 0; index--) append(pending, current[index])
-      } else {
-        const keys = ObjectKeys(current)
-        append(wire, { kind: 'object', keys })
-        for (let index = keys.length - 1; index >= 0; index--) append(pending, current[keys[index]])
-      }
-    }
-    return wire
-  }
-  const decodeWire = wire => {
-    if (!ArrayIsArray(wire) || wire.length === 0) return undefined
-    const frames = []
-    let root
-    let assigned = false
-    const attach = value => {
-      const parent = frames[frames.length - 1]
-      if (!parent) {
-        if (assigned) return false
-        root = value; assigned = true; return true
-      }
-      if (parent.kind === 'array') append(parent.target, value)
-      else define(parent.target, parent.keys[parent.index], value)
-      parent.index += 1
-      return true
-    }
-    for (let tokenIndex = 0; tokenIndex < wire.length; tokenIndex++) {
-      const token = wire[tokenIndex]
-      let value
-      let frame
-      if (token === null || typeof token === 'boolean' || typeof token === 'string') value = token
-      else if (typeof token === 'number') {
-        if (!NumberIsFinite(token) || ObjectIs(token, -0)) return undefined
-        value = token
-      } else {
-        if (!plainObject(token)) return undefined
-        const keys = ownEnumerableStringKeys(token)
-        if (!keys || keys.length !== 2 || keys[0] !== 'kind') return undefined
-        if (token.kind === 'array' && keys[1] === 'length' && NumberIsSafeInteger(token.length) && token.length >= 0) {
-          value = []
-          if (token.length > wire.length - tokenIndex - 1) return undefined
-          if (token.length) frame = { kind: 'array', target: value, length: token.length, index: 0 }
-        } else if (token.kind === 'object' && keys[1] === 'keys' && ArrayIsArray(token.keys)) {
-          const unique = new SetCtor()
-          const objectKeys = []
-          for (const key of token.keys) {
-            if (typeof key !== 'string' || setHas(unique, key)) return undefined
-            setAdd(unique, key); append(objectKeys, key)
-          }
-          if (objectKeys.length > wire.length - tokenIndex - 1) return undefined
-          value = {}
-          if (objectKeys.length) frame = { kind: 'object', target: value, keys: objectKeys, index: 0 }
-        } else return undefined
-      }
-      if (!attach(value)) return undefined
-      if (frame) append(frames, frame)
-      while (frames.length) {
-        const current = frames[frames.length - 1]
-        const length = current.kind === 'array' ? current.length : current.keys.length
-        if (current.index < length) break
-        pop(frames)
-      }
-    }
-    return frames.length === 0 ? root : undefined
-  }
-  const byteLength = text => ReflectApply(BufferByteLength, Buffer, [text])
-  const jsonStringBytes = text => byteLength(JSONStringify(text))
-  const jsonValueBytes = value => {
-    let bytes = 0
-    const tasks = [{ kind: 'value', value }]
-    while (tasks.length) {
-      const task = pop(tasks)
-      if (task.kind === 'separator') { bytes += 1; continue }
-      if (task.kind === 'key') { bytes += jsonStringBytes(task.value) + 1; continue }
-      const current = task.value
-      if (current === null) bytes += 4
-      else if (typeof current === 'string') bytes += jsonStringBytes(current)
-      else if (typeof current === 'number' || typeof current === 'boolean') bytes += byteLength(StringValue(current))
-      else if (ArrayIsArray(current)) {
-        bytes += 2
-        for (let index = current.length - 1; index >= 0; index--) {
-          append(tasks, { kind: 'value', value: current[index] })
-          if (index > 0) append(tasks, { kind: 'separator' })
-        }
-      } else {
-        bytes += 2
-        const keys = ObjectKeys(current)
-        for (let index = keys.length - 1; index >= 0; index--) {
-          const key = keys[index]
-          append(tasks, { kind: 'value', value: current[key] })
-          append(tasks, { kind: 'key', value: key })
-          if (index > 0) append(tasks, { kind: 'separator' })
-        }
-      }
-    }
-    return bytes
-  }
-  const truncate = (text, available) => {
-    if (available < 2) return ''
-    let result = ''
-    let bytes = 2
-    let index = 0
-    while (index < text.length) {
-      const first = ReflectApply(StringCharCodeAt, text, [index])
-      let end = index + 1
-      if (first >= 0xd800 && first <= 0xdbff && end < text.length) {
-        const second = ReflectApply(StringCharCodeAt, text, [end])
-        if (second >= 0xdc00 && second <= 0xdfff) end += 1
-      }
-      const character = ReflectApply(StringSlice, text, [index, end])
-      const cost = jsonStringBytes(character) - 2
-      if (bytes + cost > available) break
-      bytes += cost
-      result += character
-      index = end
-    }
-    return result
-  }
-  let logBytes = 2
-  let logEntries = 0
-  let limited = false
-  const pushLog = text => {
-    if (limited) return
-    const separator = logEntries > 0 ? 1 : 0
-    const available = workerData.maxOutputBytes - logBytes - separator
-    const cost = jsonStringBytes(text)
-    if (cost > available) {
-      const prefix = truncate(text, available)
-      if (prefix) {
-        logBytes += jsonStringBytes(prefix) + separator
-        logEntries += 1
-        port.postMessage({ type: 'log', text: prefix })
-      }
-      limited = true
-      port.postMessage({ type: 'output-limit' })
-      return
-    }
-    logBytes += cost + separator
-    logEntries += 1
-    port.postMessage({ type: 'log', text })
-  }
-  const originalStdout = process.stdout.write
-  const originalStderr = process.stderr.write
-  process.stdout.write = (chunk, ...rest) => {
-    pushLog(typeof chunk === 'string' ? chunk : StringValue(chunk))
-    let callback
-    for (let index = 0; index < rest.length; index++) {
-      if (typeof rest[index] === 'function') { callback = rest[index]; break }
-    }
-    if (callback) QueueMicrotask(() => { callback(null) })
-    return true
-  }
-  process.stderr.write = process.stdout.write
-  const consoleShim = ObjectCreate(null)
-  for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
-    define(consoleShim, level, (...args) => {
-      const rendered = []
-      for (let index = 0; index < args.length; index++) {
-        const value = args[index]
-        append(rendered, typeof value === 'string' ? value : inspect(value, { depth: 4, maxArrayLength: 100, maxStringLength: 10000 }))
-      }
-      pushLog(ReflectApply(ArrayJoin, rendered, [' ']))
-    })
-  }
-  const pending = new Map()
-  let nextId = 1
-  const errorClasses = new Map()
-  for (const namespace of workerData.namespaces) {
-    if (!namespace.errorClass) continue
-    const descriptor = namespace.errorClass
-    mapSet(errorClasses, namespace.global, class BindingCallError extends CapturedError {
-      constructor(memberName, message) {
-        super(message)
-        ObjectDefineProperty(this, 'name', { value: descriptor.name, enumerable: true })
-        ObjectDefineProperty(this, descriptor.memberNameProperty, { value: memberName, enumerable: true })
-      }
-    })
-  }
-  port.on('message', message => {
-    if (!message || message.type !== 'reply' || typeof message.id !== 'number') return
-    const entry = mapGet(pending, message.id)
-    if (!entry) return
-    mapDelete(pending, message.id)
-    if (!message.ok) { entry.reject(new CapturedError(StringValue(message.message))); return }
-    const value = decodeWire(message.value)
-    if (value === undefined) entry.reject(new CapturedError('binding resolution must be lossless JSON'))
-    else entry.resolve(value)
-  })
-  const namespaces = workerData.namespaces.map(namespace => {
-    const target = ObjectCreate(null)
-    const ErrorClass = mapGet(errorClasses, namespace.global)
-    for (const name of namespace.names) {
-      define(target, name, args => {
-        const detached = snapshot(args)
-        if (detached === undefined) {
-          return ReflectApply(PromiseReject, PromiseCtor, [ErrorClass ? new ErrorClass(name, 'binding arguments must be lossless JSON') : new CapturedError('binding arguments must be lossless JSON')])
-        }
-        return new PromiseCtor((resolve, reject) => {
-          const id = nextId++
-          mapSet(pending, id, {
-            resolve,
-            reject: error => { reject(ErrorClass ? new ErrorClass(name, error.message) : error) },
-          })
-          port.postMessage({ type: 'call', id, global: namespace.global, name, args: encodeWire(detached) })
-        })
-      })
-    }
-    return target
-  })
-  const errorClassNames = []
-  const errorClassValues = []
-  for (const namespace of workerData.namespaces) {
-    if (!namespace.errorClass) continue
-    append(errorClassNames, namespace.errorClass.name)
-    append(errorClassValues, mapGet(errorClasses, namespace.global))
-  }
-  const AsyncFunction = ObjectGetPrototypeOf(async function () {}).constructor
-  try {
-    const fn = new AsyncFunction(...workerData.namespaces.map(value => value.global), ...errorClassNames, 'console', '"use strict";\n' + workerData.code)
-    const value = await fn(...namespaces, ...errorClassValues, consoleShim)
-    if (!limited) {
-      if (value === undefined) port.postMessage({ type: 'done' })
-      else {
-        const detached = snapshot(value)
-        if (detached === undefined) {
-          const message = 'program completion must be lossless JSON'
-          if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
-          else port.postMessage({ type: 'done', error: { kind: 'invalid-output', message } })
-        } else if (jsonValueBytes(detached) > workerData.maxOutputBytes - logBytes) {
-          port.postMessage({ type: 'output-limit' })
-        } else {
-          port.postMessage({ type: 'done', value: encodeWire(detached) })
-        }
-      }
-    }
-  } catch (error) {
-    if (!limited) {
-      let message
-      try { message = error instanceof CapturedError ? error.stack || error.message : StringValue(error) }
-      catch { message = 'program threw an unrenderable value' }
-      if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
-      else port.postMessage({ type: 'done', error: { kind: 'exception', message } })
-    }
-  } finally {
-    process.stdout.write = originalStdout
-    process.stderr.write = originalStderr
-  }
-} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
-  runController()
-} else {
-  runLauncher()
-}
-`
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
deleted file mode 100644
index f99485a929..0000000000
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ /dev/null
@@ -1,765 +0,0 @@
-import { spawn } from 'node:child_process'
-import { access, mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { PassThrough, Writable } from 'node:stream'
-import { setTimeout as delay } from 'node:timers/promises'
-import { Context } from 'cordis'
-import { describe, expect, it, vi } from 'vitest'
-import type { Sandbox } from '@deepseek-ai/dsh-e2b'
-import {
-  E2BFrameDecoder,
-  encodeE2BFrame,
-} from '@deepseek-ai/dsh-e2b'
-import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import type {
-  SubprocessHandle,
-  SubprocessOutcome,
-  SubprocessSpawnSpec,
-} from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import {
-  encodeWorkerJson,
-} from '@deepseek-ai/dsh-code-runtime-worker'
-import E2BCodeRuntime from '@deepseek-ai/dsh-code-runtime-e2b'
-import * as E2BCodeRuntimeInvariant from '../src/invariant.ts'
-import { CODE_RUNNER_SOURCE } from '../src/runner-source.ts'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-
-class FakeHandle implements SubprocessHandle {
-  readonly pid = 123
-  readonly stdin: Writable | undefined
-  readonly stdout: PassThrough | undefined
-  readonly stderr = undefined
-  readonly collected: SubprocessHandle['collected']
-  readonly done: Promise<SubprocessOutcome>
-  readonly writes: unknown[] = []
-  readonly result = Promise.withResolvers<SubprocessOutcome>()
-  terminated = 0
-  waitCalls = 0
-  private readonly decoder = new E2BFrameDecoder(10_000_000)
-  private readonly waitError: Error | undefined
-  private readonly waitResult: Promise<boolean> | undefined
-  private settled = false
-
-  constructor(
-    private readonly onMessage: (message: unknown, handle: FakeHandle) => void = () => {},
-    options: {
-      stdin?: boolean
-      stdout?: boolean
-      stderr?: string
-      writeError?: Error
-      waitError?: Error
-      waitResult?: Promise<boolean>
-    } = {},
-  ) {
-    this.waitError = options.waitError
-    this.waitResult = options.waitResult
-    this.stdin = options.stdin === false
-      ? undefined
-      : options.writeError === undefined
-        ? new PassThrough()
-        : new Writable({ write: (_chunk, _encoding, callback) => { callback(options.writeError) } })
-    this.stdout = options.stdout === false ? undefined : new PassThrough()
-    this.collected = options.stderr === undefined
-      ? {}
-      : { stderr: { readFrom: () => ({ text: options.stderr as string, nextOffset: 0, lossy: false }) } }
-    this.done = this.result.promise
-    this.stdin?.on('data', (chunk: Buffer) => {
-      for (const message of this.decoder.push(chunk.toString('ascii'))) {
-        this.writes.push(message)
-        this.onMessage(message, this)
-      }
-    })
-  }
-
-  emit(message: unknown): void {
-    this.stdout?.write(encodeE2BFrame(message))
-  }
-
-  emitRaw(text: string): void {
-    this.stdout?.write(text)
-  }
-
-  exit(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
-    if (this.settled) return
-    this.settled = true
-    this.stdout?.end()
-    this.result.resolve(outcome)
-  }
-
-  crash(error: unknown): void {
-    if (this.settled) return
-    this.settled = true
-    this.stdout?.end()
-    this.result.reject(error)
-  }
-
-  terminate(): void {
-    this.terminated += 1
-    this.exit({ exitCode: null, signal: 'SIGTERM' })
-  }
-
-  async waitForExit(): Promise<boolean> {
-    this.waitCalls += 1
-    if (this.waitError !== undefined) throw this.waitError
-    if (this.waitResult !== undefined) return await this.waitResult
-    return true
-  }
-}
-
-interface RuntimeFixture {
-  ctx: Context
-  fiber: Awaited<ReturnType<Context['plugin']>>
-  runtime: E2BCodeRuntime
-  sandbox: Sandbox
-  spawn: ReturnType<typeof vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>>
-  write: ReturnType<typeof vi.fn>
-  run: ReturnType<typeof vi.fn>
-}
-
-async function setup(
-  handles: FakeHandle[] = [],
-  config: Record<string, number> = {},
-  sandboxOverrides: Partial<Sandbox> = {},
-  getSandbox?: () => Promise<Sandbox>,
-): Promise<RuntimeFixture> {
-  const write = vi.fn().mockResolvedValue([])
-  const run = vi.fn().mockImplementation(async (command: string) => ({
-    exitCode: 0,
-    stdout: command.startsWith('command -v') ? '/usr/bin/node\n' : '',
-    stderr: '',
-  }))
-  const sandbox = {
-    files: { write },
-    commands: { run },
-    ...sandboxOverrides,
-  } as unknown as Sandbox
-  const e2b = {
-    cwd: '/workspace',
-    runtimeRoot: '/workspace/.dsh-e2b',
-    getSandbox: getSandbox ?? (async () => sandbox),
-  } as unknown as E2BSandboxService
-  const spawn = vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>(() => {
-    const handle = handles.shift()
-    if (handle === undefined) throw new Error('no fake handle queued')
-    return handle
-  })
-  const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
-  Object.defineProperty(subprocess, 'spawn', { value: spawn })
-  const ctx = new Context()
-  ctx.provide('e2b', e2b)
-  ctx.provide('subprocess', subprocess)
-  const fiber = await ctx.plugin(E2BCodeRuntime, config)
-  return { ctx, fiber, runtime: ctx.codeRuntime as E2BCodeRuntime, sandbox, spawn, write, run }
-}
-
-function request(program = 'return 1') {
-  return { program, bindings: [] }
-}
-
-async function runInstalledRunner(
-  code: string,
-  maxOutputBytes = 2_000_000,
-): Promise<{ messages: unknown[]; stderr: string }> {
-  const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-runner-'))
-  const runner = join(directory, 'runner.mjs')
-  await writeFile(runner, CODE_RUNNER_SOURCE)
-  const child = spawn(process.execPath, [runner], { stdio: ['pipe', 'pipe', 'pipe'] })
-  const decoder = new E2BFrameDecoder(4_000_000)
-  const messages: unknown[] = []
-  let stderr = ''
-  let outputError: unknown
-  child.stdout.setEncoding('ascii')
-  child.stdout.on('data', (chunk: string) => {
-    try {
-      messages.push(...decoder.push(chunk))
-    } catch (error: unknown) {
-      outputError = error
-      child.kill('SIGKILL')
-    }
-  })
-  child.stderr.setEncoding('utf8')
-  child.stderr.on('data', (chunk: string) => { stderr += chunk })
-
-  try {
-    child.stdin.write(encodeE2BFrame({
-      type: 'boot',
-      code,
-      namespaces: [],
-      computeMs: 1_000,
-      maxOutputBytes,
-      maxOldGenerationSizeMb: 128,
-    }))
-    await new Promise<void>((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        child.kill('SIGKILL')
-        reject(new Error('installed E2B code runner did not exit'))
-      }, 5_000)
-      child.once('error', (error) => {
-        clearTimeout(timeout)
-        reject(error)
-      })
-      child.once('exit', () => {
-        clearTimeout(timeout)
-        resolve()
-      })
-    })
-    if (outputError !== undefined) throw outputError
-    decoder.finish()
-    return { messages, stderr }
-  } finally {
-    child.kill('SIGKILL')
-    await rm(directory, { recursive: true, force: true })
-  }
-}
-
-describe('E2BCodeRuntime', () => {
-  it('keeps model-owned descriptors outside the host framing process', async () => {
-    const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
-    const { messages, stderr } = await runInstalledRunner(
-      `
-        const fs = await import('node:fs')
-        const childProcess = await import('node:child_process')
-        fs.writeSync(1, ${JSON.stringify(forged)})
-        childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("child-native")'], { stdio: 'inherit' })
-        return true
-      `,
-    )
-    const records = messages as Array<{ type?: string; text?: string; value?: unknown }>
-    const terminal = records.filter(message => message.type === 'done')
-
-    expect(stderr).toBe('')
-    expect(terminal).toEqual([{ type: 'done', value: [true] }])
-    expect(records.at(-1)).toEqual(terminal[0])
-    expect(records.filter(message => message.type === 'log').map(message => message.text).join(''))
-      .toContain(forged + 'child-native')
-  })
-
-  it('bounds native descriptor output before it reaches the host protocol', async () => {
-    const { messages, stderr } = await runInstalledRunner(
-      "(await import('node:fs')).writeSync(1, 'x'.repeat(4096)); return true",
-      64,
-    )
-    const records = messages as Array<{ type?: string; text?: string }>
-
-    expect(stderr).toBe('')
-    expect(records.at(-1)).toEqual({ type: 'output-limit' })
-    expect(Buffer.byteLength(records.filter(message => message.type === 'log').map(message => message.text).join('')))
-      .toBeLessThanOrEqual(62)
-  })
-
-  it('drains native worker pipes before emitting the terminal frame', async () => {
-    const expectedBytes = 1_048_576
-    const { messages, stderr } = await runInstalledRunner(
-      `
-        let stdoutPrototype = Object.getPrototypeOf(process.stdout)
-        while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
-        Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(${expectedBytes})])
-        return true
-      `,
-    )
-    const records = messages as Array<{ type?: string; text?: string }>
-    const terminalIndex = records.findIndex(message => message.type === 'done')
-    const nativeOutput = records
-      .slice(0, terminalIndex)
-      .filter(message => message.type === 'log')
-      .map(message => message.text ?? '')
-      .join('')
-
-    expect(stderr).toBe('')
-    expect(terminalIndex).toBe(records.length - 1)
-    expect(Buffer.byteLength(nativeOutput)).toBe(expectedBytes)
-  })
-
-  it.skipIf(process.platform === 'win32')('reaps descendant-held controller pipes before completion', async () => {
-    const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-descendant-'))
-    const marker = join(directory, 'started')
-    const release = join(directory, 'release')
-    const childSource = `
-      const fs = require('node:fs')
-      fs.writeFileSync(${JSON.stringify(marker)}, 'started')
-      const timer = setInterval(() => {
-        if (fs.existsSync(${JSON.stringify(release)})) clearInterval(timer)
-      }, 10)
-    `
-    let running: ReturnType<typeof runInstalledRunner> | undefined
-    try {
-      running = runInstalledRunner(`
-        const fs = await import('node:fs')
-        const childProcess = await import('node:child_process')
-        childProcess.spawn(process.execPath, ['-e', ${JSON.stringify(childSource)}], {
-          stdio: ['ignore', 'inherit', 'inherit'],
-        })
-        while (!fs.existsSync(${JSON.stringify(marker)})) await new Promise(resolve => setTimeout(resolve, 5))
-        return true
-      `)
-      const deadline = Date.now() + 2_000
-      for (;;) {
-        try {
-          await access(marker)
-          break
-        } catch (error: unknown) {
-          if (Date.now() >= deadline) throw error
-          await delay(10)
-        }
-      }
-      const completed = await Promise.race([
-        running.then(() => true),
-        delay(500).then(() => false),
-      ])
-      await writeFile(release, '')
-      const { messages, stderr } = await running
-
-      expect(completed).toBe(true)
-      expect(stderr).toBe('')
-      expect(messages.at(-1)).toEqual({ type: 'done', value: [true] })
-    } finally {
-      await writeFile(release, '').catch(() => undefined)
-      await running?.catch(() => undefined)
-      await rm(directory, { recursive: true, force: true })
-    }
-  })
-
-  it('prepares the remote runner and returns logs and a lossless completion', async () => {
-    const handle = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type !== 'boot') return
-      current.emit({ type: 'log', text: 'remote 你好' })
-      current.emitRaw(
-        encodeE2BFrame({ type: 'done', value: encodeWorkerJson({ answer: 42 }) })
-        + encodeE2BFrame({ type: 'log', text: 'ignored after done' }),
-      )
-      current.emit({ type: 'log', text: 'also ignored after done' })
-    })
-    const fixture = await setup([handle])
-
-    await expect(fixture.runtime.run(request('const answer: number = 42; return { answer }')))
-      .resolves.toEqual({ logs: ['remote 你好'], value: { answer: 42 } })
-    expect(fixture.runtime.language).toBe('typescript')
-    expect(fixture.runtime.isolation).toBe('container')
-    expect(fixture.write).toHaveBeenCalledWith([{ path: '/workspace/.dsh-e2b/code-runtime-runner.mjs', data: CODE_RUNNER_SOURCE }])
-    expect(fixture.run).toHaveBeenCalledWith("chmod 600 -- '/workspace/.dsh-e2b/code-runtime-runner.mjs'")
-    expect(fixture.spawn).toHaveBeenCalledWith(expect.objectContaining({
-      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/code-runtime-runner.mjs'],
-      cwd: '/workspace',
-      env: {},
-    }))
-    expect(handle.terminated).toBe(1)
-    expect(handle.waitCalls).toBe(1)
-    await fixture.fiber.dispose()
-  })
-
-  it('bridges binding success, host rejection, unknown members, and invalid values', async () => {
-    const replies: unknown[] = []
-    const handle = new FakeHandle((message, current) => {
-      const record = message as { type?: string; id?: number; ok?: boolean }
-      if (record.type === 'boot') {
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 4 }) })
-        current.emit({ type: 'call', id: 2, global: 'bridge', name: 'fail', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 3, global: 'bridge', name: 'missing', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 4, global: 'bridge', name: 'double', args: [] })
-        current.emit({ type: 'call', id: 5, global: 'bridge', name: 'invalid', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 6, global: 'bridge', name: 'throwing', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 99 }) })
-        return
-      }
-      if (record.type === 'reply') {
-        replies.push(message)
-        if (replies.length === 6) current.emit({ type: 'done', value: encodeWorkerJson('done') })
-      }
-    })
-    const fixture = await setup([handle])
-    const result = await fixture.runtime.run({
-      program: 'return await bridge.double({ value: 4 })',
-      bindings: [
-        {
-          global: 'bridge',
-          errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
-          functions: {
-            double: async args => (args as { value: number }).value * 2,
-            fail: async () => { throw 'nope' },
-            invalid: (async () => undefined) as never,
-            throwing: async () => Object.defineProperty({}, 'value', {
-              enumerable: true,
-              get: () => { throw new Error('getter failed') },
-            }),
-          },
-        },
-        { global: 'plain', functions: {} },
-      ],
-    })
-
-    expect(result).toEqual({ logs: [], value: 'done' })
-    expect(replies.sort((left, right) => (left as { id: number }).id - (right as { id: number }).id)).toEqual([
-      { type: 'reply', id: 1, ok: true, value: encodeWorkerJson(8) },
-      { type: 'reply', id: 2, ok: false, message: 'nope' },
-      { type: 'reply', id: 3, ok: false, message: 'unknown binding "bridge.missing"' },
-      { type: 'reply', id: 4, ok: false, message: 'binding arguments must be lossless JSON' },
-      { type: 'reply', id: 5, ok: false, message: 'binding resolution must be lossless JSON' },
-      { type: 'reply', id: 6, ok: false, message: 'binding resolution must be lossless JSON' },
-    ])
-    await fixture.fiber.dispose()
-  })
-
-  it('ignores malformed runner traffic and classifies terminal runner messages', async () => {
-    const ignored = [
-      null, 1, {}, { type: 'log' }, { type: 'call' },
-      { type: 'call', id: 0, global: 'x', name: 'y', args: [] },
-      { type: 'call', id: 1, global: 1, name: 'y', args: [] },
-      { type: 'call', id: 1, global: 'x', name: 1, args: [] },
-      { type: 'call', id: 1, global: 'x', name: 'y', args: {} },
-      { type: 'done', error: null },
-      { type: 'done', error: { kind: 'invented', message: 'x' } },
-      { type: 'done', error: { kind: 'exception', message: 1 } },
-    ]
-    const handles = [
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type !== 'boot') return
-        for (const item of ignored) current.emit(item)
-        current.emit({ type: 'done' })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', error: { kind: 'exception', message: 'boom' } })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', value: [] })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'output-limit' })
-      }),
-    ]
-    const fixture = await setup(handles, { maxOutputBytes: 64, maxFrameBytes: 128 })
-
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [] })
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'exception', message: 'boom' } })
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
-    await fixture.fiber.dispose()
-  })
-
-  it('enforces the host output ledger and catches malformed bridge output', async () => {
-    const handles = [
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'log', text: 'x'.repeat(1_000) })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emitRaw('not-base64\n')
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emitRaw('é')
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.stdout?.emit('error', new Error('stdout broke'))
-      }),
-    ]
-    const fixture = await setup(handles, { maxOutputBytes: 128, maxFrameBytes: 4_096 })
-
-    expect((await fixture.runtime.run(request())).error?.kind).toBe('output-limit')
-    const malformed = (await fixture.runtime.run(request())).error
-    expect(malformed?.kind).toBe('worker-exit')
-    expect(malformed?.message).toContain('bridge failed')
-    expect((await fixture.runtime.run(request())).error?.message).toContain('non-ASCII')
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdout failed: stdout broke' })
-    await fixture.fiber.dispose()
-  })
-
-  it('enforces the outbound frame bound on boot and binding replies', async () => {
-    const oversizedBoot = new FakeHandle()
-    const oversizedReply = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') {
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'large', args: encodeWorkerJson(null) })
-      }
-    })
-    const fixture = await setup([oversizedBoot, oversizedReply], { maxOutputBytes: 128, maxFrameBytes: 512 })
-
-    const bootResult = await fixture.runtime.run(request(`return ${JSON.stringify('x'.repeat(1_000))}`))
-    expect(bootResult.error).toMatchObject({ kind: 'worker-exit' })
-    expect(bootResult.error?.message).toContain('frame exceeded its byte limit')
-    expect(oversizedBoot.writes).toHaveLength(0)
-
-    const replyResult = await fixture.runtime.run({
-      program: 'return await bridge.large(null)',
-      bindings: [{ global: 'bridge', functions: { large: async () => 'x'.repeat(1_000) } }],
-    })
-    expect(replyResult.error).toMatchObject({ kind: 'worker-exit' })
-    expect(replyResult.error?.message).toContain('frame exceeded its byte limit')
-    expect(oversizedReply.writes).toHaveLength(1)
-    await fixture.fiber.dispose()
-  })
-
-  it('contains stdin errors, process exits, spawn failures, and missing pipes', async () => {
-    const writeError = new FakeHandle(() => {}, { writeError: new Error('write callback broke') })
-    const stdinError = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') current.stdin?.emit('error', new Error('stdin broke'))
-    })
-    const earlyExit = new FakeHandle(() => {}, { stderr: 'remote diagnostic' })
-    const quietExit = new FakeHandle()
-    const emptyStderrExit = new FakeHandle(() => {}, { stderr: '' })
-    const spawnFailure = new FakeHandle()
-    const missingStdin = new FakeHandle(() => {}, { stdin: false })
-    const missingStdout = new FakeHandle(() => {}, { stdout: false, waitError: new Error('missing-stream process query failed') })
-    const truncated = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') {
-        current.emitRaw('YQ==')
-        setImmediate(() => { current.exit() })
-      }
-    })
-    const cleanupFailure = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
-    }, { waitError: new Error('process query failed') })
-    const fixture = await setup([
-      writeError, stdinError, earlyExit, quietExit, emptyStderrExit,
-      spawnFailure, missingStdin, missingStdout, truncated, cleanupFailure,
-    ])
-
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime bridge write failed: write callback broke' })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdin failed: stdin broke' })
-    setImmediate(() => { earlyExit.exit() })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing: remote diagnostic' })
-    setImmediate(() => { quietExit.exit() })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
-    setImmediate(() => { emptyStderrExit.exit() })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
-    setImmediate(() => { spawnFailure.crash('spawn rejected') })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime spawn failed: spawn rejected' })
-    expect((await fixture.runtime.run(request())).error?.message).toContain('dropped a piped runtime stream')
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: missing-stream process query failed' })
-    expect(missingStdin.terminated).toBe(1)
-    expect(missingStdin.waitCalls).toBe(1)
-    expect(missingStdout.terminated).toBe(1)
-    expect(missingStdout.waitCalls).toBe(1)
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B frame stream ended mid-frame' })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: process query failed' })
-    await fixture.fiber.dispose()
-  })
-
-  it('reports wall timeout, abort, pre-abort, type-strip failure, and disposal', async () => {
-    const timeout = new FakeHandle()
-    const abort = new FakeHandle()
-    const disposing = new FakeHandle()
-    const fixture = await setup([timeout, abort, disposing], { maxWallMs: 20 })
-
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'timeout', message: 'wall-clock ceiling reached (20ms)' })
-    const controller = new AbortController()
-    const aborting = fixture.runtime.run({ ...request(), signal: controller.signal })
-    controller.abort('stop')
-    expect((await aborting).error).toEqual({ kind: 'abort', message: 'stop' })
-    expect((await fixture.runtime.run({ ...request(), signal: AbortSignal.abort('already') })).error)
-      .toEqual({ kind: 'abort', message: 'already' })
-    expect((await fixture.runtime.run(request('enum E { A }'))).error?.kind).toBe('exception')
-
-    const live = fixture.runtime.run(request())
-    await new Promise(resolve => setImmediate(resolve))
-    await fixture.fiber.dispose()
-    expect((await live).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
-    await expect(fixture.runtime.run(request())).rejects.toThrow('after disposal')
-  })
-
-  it('drops binding replies that settle after abort', async () => {
-    const controller = new AbortController()
-    const resolution = Promise.withResolvers<string>()
-    const invoked = Promise.withResolvers<undefined>()
-    const handle = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') {
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'late', args: encodeWorkerJson(null) })
-      }
-    })
-    const fixture = await setup([handle])
-    const running = fixture.runtime.run({
-      program: 'return await bridge.late(null)',
-      bindings: [{
-        global: 'bridge',
-        functions: {
-          late: async () => {
-            invoked.resolve(undefined)
-            return await resolution.promise
-          },
-        },
-      }],
-      signal: controller.signal,
-    })
-    await invoked.promise
-    controller.abort('stop')
-    expect((await running).error).toEqual({ kind: 'abort', message: 'stop' })
-    resolution.resolve('late')
-    await new Promise(resolve => setImmediate(resolve))
-    expect(handle.writes).toHaveLength(1)
-    await fixture.fiber.dispose()
-  })
-
-  it('validates binding and runtime configuration before remote execution', async () => {
-    const fixture = await setup([])
-    const invalidRequests = [
-      { global: 'not-valid!', functions: {} },
-      { global: 'await', functions: {} },
-      { global: 'console', functions: {} },
-      { global: 'same', functions: {} },
-      { global: 'same', functions: {} },
-      { global: 'ok', functions: {}, errorClass: { name: 'not-valid!', memberNameProperty: 'member' } },
-      { global: 'ok', functions: {}, errorClass: { name: 'await', memberNameProperty: 'member' } },
-      { global: 'Clash', functions: {}, errorClass: { name: 'Clash', memberNameProperty: 'member' } },
-      { global: 'one', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
-      { global: 'two', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
-      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: '' } },
-      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'message' } },
-    ]
-    for (const bindings of [
-      [invalidRequests[0]], [invalidRequests[1]], [invalidRequests[2]],
-      invalidRequests.slice(3, 5), [invalidRequests[5]], [invalidRequests[6]],
-      [invalidRequests[7]], invalidRequests.slice(8, 10), [invalidRequests[10]], [invalidRequests[11]],
-    ]) {
-      await expect(fixture.runtime.run({ program: 'return 1', bindings: bindings as never })).rejects.toThrow()
-    }
-    await fixture.fiber.dispose()
-
-    for (const config of [
-      { computeMs: 0 }, { computeMs: 1.5 }, { maxOutputBytes: 3 },
-      { maxWallMs: 2_147_483_648 }, { maxFrameBytes: 10, maxOutputBytes: 20 },
-    ]) {
-      const ctx = new Context()
-      const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
-      ctx.provide('e2b', { getSandbox: async () => ({}) } as never)
-      ctx.provide('subprocess', subprocess)
-      await expect(ctx.plugin(E2BCodeRuntime, config)).rejects.toThrow()
-    }
-
-    const wrong = new Context()
-    wrong.provide('e2b', { getSandbox: async () => ({}) } as never)
-    wrong.provide('subprocess', {} as never)
-    await expect(wrong.plugin(E2BCodeRuntime, {})).rejects.toThrow('dsh-subprocess-e2b')
-  })
-
-  it('turns asynchronous runtime preparation failure into a run result', async () => {
-    const sandbox = {
-      files: { write: vi.fn().mockRejectedValue(new Error('upload failed')) },
-      commands: { run: vi.fn() },
-    } as unknown as Sandbox
-    const fixture = await setup([], {}, sandbox)
-    expect((await fixture.runtime.run(request())).error).toEqual({
-      kind: 'worker-exit',
-      message: 'E2B runtime setup failed: upload failed',
-    })
-    await fixture.fiber.dispose()
-  })
-
-  it('returns disposal when remote preparation completes after teardown', async () => {
-    const gate = Promise.withResolvers<Sandbox>()
-    const fixture = await setup([], {}, {}, () => gate.promise)
-    const running = fixture.runtime.run(request())
-    const disposing = fixture.fiber.dispose()
-    let disposed = false
-    void disposing.then(() => { disposed = true })
-    await new Promise(resolve => setImmediate(resolve))
-    const disposedBeforeSetup = disposed
-    gate.resolve(fixture.sandbox)
-    await disposing
-    expect(disposedBeforeSetup).toBe(false)
-    expect((await running).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
-    expect(fixture.write).not.toHaveBeenCalled()
-  })
-
-  it('observes abort while runtime preparation is pending', async () => {
-    const gate = Promise.withResolvers<Sandbox>()
-    const fixture = await setup([], {}, {}, () => gate.promise)
-    const controller = new AbortController()
-    const running = fixture.runtime.run({ ...request(), signal: controller.signal })
-
-    controller.abort('stop during setup')
-    const early = await Promise.race([
-      running.then(result => ({ kind: 'result' as const, result })),
-      new Promise<{ kind: 'pending' }>((resolve) => { setImmediate(() => { resolve({ kind: 'pending' }) }) }),
-    ])
-    expect(fixture.spawn).not.toHaveBeenCalled()
-
-    gate.resolve(fixture.sandbox)
-    expect(early).toMatchObject({ kind: 'result', result: { error: { kind: 'abort', message: 'stop during setup' } } })
-    await running
-    await fixture.fiber.dispose()
-  })
-
-  it('classifies an abort that races synchronous subprocess spawn', async () => {
-    const fixture = await setup()
-    const controller = new AbortController()
-    fixture.spawn.mockImplementationOnce(() => {
-      controller.abort('stop at spawn')
-      throw new Error('aborted before spawn')
-    })
-
-    expect((await fixture.runtime.run({ ...request(), signal: controller.signal })).error)
-      .toEqual({ kind: 'abort', message: 'stop at spawn' })
-
-    fixture.spawn.mockImplementationOnce(() => { throw new Error('synchronous spawn failure') })
-    expect((await fixture.runtime.run(request())).error).toEqual({
-      kind: 'worker-exit',
-      message: 'E2B runtime spawn failed: synchronous spawn failure',
-    })
-    await fixture.fiber.dispose()
-
-    const disposingFixture = await setup()
-    disposingFixture.spawn.mockImplementationOnce(() => {
-      void (disposingFixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
-      throw new Error('spawn raced disposal')
-    })
-    expect((await disposingFixture.runtime.run(request())).error)
-      .toEqual({ kind: 'abort', message: 'runtime disposed' })
-    await disposingFixture.fiber.dispose()
-  })
-
-  it('closes both abort races around runtime readiness and live-run publication', async () => {
-    let preparationAborted = false
-    const preparationSignal = {
-      get aborted() { return preparationAborted },
-      reason: 'preparation race',
-      addEventListener() { preparationAborted = true },
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    const liveHandle = new FakeHandle()
-    const fixture = await setup([liveHandle])
-    expect((await fixture.runtime.run({ ...request(), signal: preparationSignal })).error)
-      .toEqual({ kind: 'abort', message: 'preparation race' })
-    expect(fixture.spawn).not.toHaveBeenCalled()
-
-    let liveAborted = false
-    let registrations = 0
-    const liveSignal = {
-      get aborted() { return liveAborted },
-      reason: 'live publication race',
-      addEventListener() {
-        registrations += 1
-        if (registrations === 2) liveAborted = true
-      },
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    expect((await fixture.runtime.run({ ...request(), signal: liveSignal })).error)
-      .toEqual({ kind: 'abort', message: 'live publication race' })
-    await fixture.fiber.dispose()
-  })
-
-  it('retains a live run until remote cleanup reaches quiescence', async () => {
-    const cleanup = Promise.withResolvers<boolean>()
-    const handle = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
-    }, { waitResult: cleanup.promise })
-    const fixture = await setup([handle])
-    const running = fixture.runtime.run(request())
-    await vi.waitFor(() => { expect(handle.waitCalls).toBe(1) })
-
-    const disposing = fixture.fiber.dispose()
-    let disposed = false
-    void disposing.then(() => { disposed = true })
-    await new Promise(resolve => setImmediate(resolve))
-    const disposedBeforeCleanup = disposed
-
-    cleanup.resolve(true)
-    await expect(running).resolves.toEqual({ logs: [] })
-    await expect(disposing).resolves.toBeUndefined()
-    expect(disposedBeforeCleanup).toBe(false)
-  })
-
-  it('registers the package-owned invariant companion', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    const fiber = await ctx.plugin(E2BCodeRuntimeInvariant).await()
-    await fiber.dispose()
-  })
-})
diff --git a/packages/e2b/code-runtime-e2b/tsconfig.json b/packages/e2b/code-runtime-e2b/tsconfig.json
deleted file mode 100644
index 3bc2e21873..0000000000
--- a/packages/e2b/code-runtime-e2b/tsconfig.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../../../vendor/cosmokit" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../../vendor/schemastery" },
-    { "path": "../../code-runtime/code-runtime" },
-    { "path": "../../code-runtime/code-runtime-worker" },
-    { "path": "../e2b" },
-    { "path": "../../core/session" },
-    { "path": "../subprocess-e2b" },
-    { "path": "../../util/timeout" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 164bb47784..8ffb6e981f 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 5f89a4bcffdfd11fef8929d2a2ceecb41af319e2
-README.zh.md: b4956033bae131bb8aa236276323ecba30f00115
+README.md: 00264b8f0b03e4af8512025322fe3e457e7b6b9b
+README.zh.md: 93fad661ded446e78e3addc0c8b2b8fdc39bd994
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 5f89a4bcff..00264b8f0b 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared lifecycle owner for one E2B sandbox. Capability adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in adapters.
+Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in composition.
 
 ## Configuration
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index b4956033ba..93fad661de 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 E2B 沙箱的共享生命周期所有者。功能适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选适配器见[包族索引](../README.md)。
+一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选组合见[包族索引](../README.md)。
 
 ## 配置
 
diff --git a/packages/e2b/e2b/src/frame.ts b/packages/e2b/e2b/src/frame.ts
deleted file mode 100644
index 5b6fe536c0..0000000000
--- a/packages/e2b/e2b/src/frame.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/** ASCII/base64 JSON framing for byte-faithful protocols over E2B text callbacks. */
-
-import { Buffer } from 'node:buffer'
-
-const BASE64_LINE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
-
-/**
- * Encode one JSON-compatible value as a newline-delimited ASCII frame.
- * @param value - Value accepted by `JSON.stringify`.
- * @returns Base64-encoded UTF-8 JSON followed by one newline.
- */
-export function encodeE2BFrame(value: unknown): string {
-  return encodeFrame(value)
-}
-
-/**
- * Encode one JSON-compatible value while enforcing the decoded frame bound.
- * @param value - Value accepted by `JSON.stringify`.
- * @param maxFrameBytes - Maximum UTF-8 JSON bytes in the encoded frame.
- * @returns Base64-encoded UTF-8 JSON followed by one newline.
- */
-export function encodeBoundedE2BFrame(value: unknown, maxFrameBytes: number): string {
-  if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
-    throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
-  }
-  return encodeFrame(value, maxFrameBytes)
-}
-
-function encodeFrame(value: unknown, maxFrameBytes?: number): string {
-  const json: unknown = JSON.stringify(value)
-  if (typeof json !== 'string') throw new Error('E2B frame value is not JSON-serializable')
-  const bytes = Buffer.from(json)
-  if (maxFrameBytes !== undefined && bytes.length > maxFrameBytes) {
-    throw new Error('E2B frame exceeded its byte limit')
-  }
-  return `${bytes.toString('base64')}\n`
-}
-
-/** Incremental decoder for newline-delimited base64 JSON frames. */
-export class E2BFrameDecoder {
-  private pending = ''
-  private readonly maxEncodedChars: number
-
-  /** @param maxFrameBytes - Maximum decoded UTF-8 JSON bytes in one frame. */
-  constructor(private readonly maxFrameBytes: number) {
-    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
-      throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
-    }
-    this.maxEncodedChars = Math.ceil(maxFrameBytes / 3) * 4
-  }
-
-  /**
-   * Consume one E2B callback chunk.
-   * @param chunk - ASCII text received from the remote helper.
-   * @returns Every complete decoded JSON value, in order.
-   */
-  push(chunk: string): unknown[] {
-    if (/[^\x0a\x20-\x7e]/.test(chunk)) throw new Error('E2B frame stream contained non-ASCII data')
-    this.pending += chunk
-    const values: unknown[] = []
-    for (;;) {
-      const newline = this.pending.indexOf('\n')
-      if (newline < 0) {
-        if (this.pending.length > this.maxEncodedChars) throw new Error('E2B frame exceeded its byte limit')
-        return values
-      }
-      const line = this.pending.slice(0, newline)
-      this.pending = this.pending.slice(newline + 1)
-      values.push(this.decode(line))
-    }
-  }
-
-  /** Reject a truncated final frame. */
-  finish(): void {
-    if (this.pending.length !== 0) throw new Error('E2B frame stream ended mid-frame')
-  }
-
-  private decode(line: string): unknown {
-    if (line.length === 0 || line.length > this.maxEncodedChars || !BASE64_LINE.test(line)) {
-      throw new Error('E2B frame contained invalid base64 or exceeded its byte limit')
-    }
-    const bytes = Buffer.from(line, 'base64')
-    if (bytes.length > this.maxFrameBytes) throw new Error('E2B frame exceeded its byte limit')
-    let json: string
-    try {
-      json = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
-    } catch (error: unknown) {
-      throw new Error('E2B frame contained invalid UTF-8', { cause: error })
-    }
-    try {
-      return JSON.parse(json) as unknown
-    } catch (error: unknown) {
-      throw new Error('E2B frame contained invalid JSON', { cause: error })
-    }
-  }
-}
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 11625b3b21..184c49f811 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -10,8 +10,6 @@ import z from 'schemastery'
 import { Sandbox } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
-export { E2BFrameDecoder, encodeBoundedE2BFrame, encodeE2BFrame } from './frame.ts'
-
 export {
   CommandExitError,
   FileNotFoundError,
@@ -44,26 +42,6 @@ export function quoteE2BShellArg(value: string): string {
   return `'${value.replaceAll('\'', "'\"'\"'")}'`
 }
 
-/**
- * Resolve one executable inside an E2B sandbox and require an absolute result.
- * @param sandbox - Sandbox whose PATH and filesystem own the executable.
- * @param command - Absolute path or bare executable name.
- * @returns Verified absolute remote executable path.
- */
-export async function resolveE2BExecutable(sandbox: Sandbox, command: string): Promise<string> {
-  if (command.length === 0) throw new Error('E2B executable name must be non-empty')
-  if (posix.isAbsolute(command)) {
-    await sandbox.commands.run(`test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`)
-    return command
-  }
-  const result = await sandbox.commands.run(`command -v -- ${quoteE2BShellArg(command)}`)
-  const executable = result.stdout.trim()
-  if (!posix.isAbsolute(executable) || executable.includes('\n')) {
-    throw new Error(`E2B executable ${JSON.stringify(command)} did not resolve to one absolute path`)
-  }
-  return executable
-}
-
 /** Action taken on the owned sandbox when the Cordis service is disposed. */
 export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
 
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 1bfbab1e8e..98fcdeae7f 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -3,13 +3,13 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
-import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
-import { E2BPtyBackend } from '@deepseek-ai/dsh-pty-e2b'
-import { PtySessionId } from '@deepseek-ai/dsh-pty'
+import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
+import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 
 const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
 const binScript = join(fixtureRoot, 'bin.ts')
@@ -29,7 +29,17 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     })
     try {
       const ctx = new Context()
-      ctx.provide('e2b', { cwd: '/home/user', getSandbox: async () => sandbox } as never)
+      ctx.provide('e2b', {
+        cwd: '/home/user',
+        runtimeRoot: '/home/user/.dsh-e2b',
+        getSandbox: async () => sandbox,
+      } as never)
+      ctx.provide('sandboxPolicy', {
+        defaultMode: 'danger-full-access',
+        workspaceRoot: '/home/user',
+      } as never)
+      const ptyFiber = await ctx.plugin(PtyService)
+      const subprocessFiber = await ctx.plugin(E2BSubprocessService)
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
@@ -38,17 +48,19 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         status: 'idle',
         acceptsNextStep: false,
         ctx,
-        followup: () => AgentMessageId('unused'),
-        steer: () => AgentMessageId('unused'),
-        inject: () => AgentMessageId('unused'),
-        send: () => AgentMessageId('unused'),
+        followup() {},
+        steer() {},
+        inject() {},
+        send() {},
         cancel() {},
         whenIdle: () => Promise.resolve(),
       }
-      const backend = new E2BPtyBackend(ctx, {
-        backendType: 'shell', rows: 24, cols: 80,
+      const backend = new LocalPtyBackend(ctx, {
+        backendType: 'shell', shellPath: '/bin/bash', shellArgs: ['--noprofile', '--norc', '-i'],
+        rows: 24, cols: 80,
         scrollbackLines: 100, scrollbackMaxBytes: 65_536, maxReadBytes: 16_384,
-        pollIntervalMs: 25, idleSilenceMs: 1_000, timeoutMs: 5_000, disposeGraceMs: 1_000,
+        pollIntervalMs: 25, exactProbeAfterMs: 150, idleSilenceMs: 1_000,
+        handoffGraceMs: 500, timeoutMs: 5_000, disposeGraceMs: 1_000,
       })
       const session = await backend.spawn({ sessionId: PtySessionId('env'), owner, type: 'shell' })
       const result = await session.startSend({
@@ -59,6 +71,8 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       expect(result.viewport).not.toContain('sentinel-secret')
       expect(result.viewport).not.toContain('sentinel-stale')
       await session.close('environment test complete')
+      await subprocessFiber.dispose()
+      await ptyFiber.dispose()
     } finally {
       await sandbox.kill().catch(() => false)
     }
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index 58d2ffbd7a..c0770f5917 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -2,12 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
-  E2BFrameDecoder,
   E2BSandboxId,
-  encodeBoundedE2BFrame,
-  encodeE2BFrame,
   quoteE2BShellArg,
-  resolveE2BExecutable,
 } from '@deepseek-ai/dsh-e2b'
 import * as E2BInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -229,57 +225,6 @@ describe('E2B helpers and invariant companion', () => {
     expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
   })
 
-  it('resolves absolute and PATH executables inside the sandbox', async () => {
-    const run = vi.fn()
-      .mockResolvedValueOnce({ exitCode: 0, stdout: '', stderr: '' })
-      .mockResolvedValueOnce({ exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' })
-    const sandbox = { commands: { run } } as unknown as SandboxType
-    await expect(resolveE2BExecutable(sandbox, '/bin/bash')).resolves.toBe('/bin/bash')
-    await expect(resolveE2BExecutable(sandbox, 'node')).resolves.toBe('/usr/bin/node')
-    expect(run).toHaveBeenNthCalledWith(1, "test -f '/bin/bash' -a -x '/bin/bash'")
-    expect(run).toHaveBeenNthCalledWith(2, "command -v -- 'node'")
-  })
-
-  it('rejects empty or non-absolute executable resolutions', async () => {
-    const sandbox = {
-      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: 'relative\npath\n', stderr: '' }) },
-    } as unknown as SandboxType
-    await expect(resolveE2BExecutable(sandbox, '')).rejects.toThrow('non-empty')
-    await expect(resolveE2BExecutable(sandbox, 'tool')).rejects.toThrow('did not resolve')
-  })
-
-  it('round-trips split and adjacent ASCII/base64 JSON frames', () => {
-    const decoder = new E2BFrameDecoder(128)
-    const encoded = encodeE2BFrame({ text: '你好' }) + encodeE2BFrame([1, true])
-    expect(decoder.push(encoded.slice(0, 5))).toEqual([])
-    expect(decoder.push(encoded.slice(5))).toEqual([{ text: '你好' }, [1, true]])
-    expect(() => { decoder.finish() }).not.toThrow()
-    expect(() => encodeE2BFrame(undefined)).toThrow('not JSON-serializable')
-  })
-
-  it('bounds outbound frames by decoded UTF-8 bytes', () => {
-    const exact = encodeBoundedE2BFrame({ text: '你' }, 14)
-    expect(new E2BFrameDecoder(14).push(exact)).toEqual([{ text: '你' }])
-    expect(() => encodeBoundedE2BFrame({ text: '你' }, 13)).toThrow('byte limit')
-    expect(() => encodeBoundedE2BFrame(null, 0)).toThrow('positive safe integer')
-    expect(() => encodeBoundedE2BFrame(null, 1.5)).toThrow('positive safe integer')
-  })
-
-  it('rejects malformed, oversized, and truncated frame streams', () => {
-    expect(() => new E2BFrameDecoder(0)).toThrow('positive safe integer')
-    expect(() => new E2BFrameDecoder(1.5)).toThrow('positive safe integer')
-    expect(() => new E2BFrameDecoder(4).push('é')).toThrow('non-ASCII')
-    expect(() => new E2BFrameDecoder(3).push('AAAAA')).toThrow('byte limit')
-    expect(() => new E2BFrameDecoder(8).push('\n')).toThrow('invalid base64')
-    expect(() => new E2BFrameDecoder(8).push('abc!\n')).toThrow('invalid base64')
-    expect(() => new E2BFrameDecoder(2).push(`${Buffer.from('abc').toString('base64')}\n`)).toThrow('byte limit')
-    expect(() => new E2BFrameDecoder(8).push('/w==\n')).toThrow('invalid UTF-8')
-    expect(() => new E2BFrameDecoder(16).push(`${Buffer.from('not-json').toString('base64')}\n`)).toThrow('invalid JSON')
-    const truncated = new E2BFrameDecoder(8)
-    truncated.push('YQ==')
-    expect(() => { truncated.finish() }).toThrow('mid-frame')
-  })
-
   it('registers the package-owned empty invariant installer', async () => {
     const ctx = new Context()
     await ctx.plugin(InvariantService, { enabled: true })
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 95a3a9eea6..6e45ccaaf6 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: a505703fc764f8441fa54d2b1d922762eb3fafdf
-README.zh.md: 626fdb52979d29f12d1bc1b67b0ea13730003af7
+README.md: 86ad8720d3e4c7ce70ee0ac8c41713af03ed297a
+README.zh.md: 90dff57a5b9fe786aea3315633125536277ecc20
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index a505703fc7..86ad8720d3 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -7,7 +7,9 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 ## Behavior
 
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
+- **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
 - **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through E2B's same-directory atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
 
@@ -26,4 +28,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
 - **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
-- **Custom templates must support the used Linux and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
+- **Custom templates must support the used Linux, Node, procfs, and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, file metadata extended attributes, `/proc/self/fd`, and no-follow descriptor opens are required; unsupported templates fail rather than degrade silently.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 626fdb5297..90dff57a5b 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -7,7 +7,9 @@
 ## 行为
 
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
+- **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
 - **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
 
@@ -26,4 +28,4 @@
 - **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
 - **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
-- **自定义模板必须支持所用的 Linux 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
+- **自定义模板必须支持所用的 Linux、Node、procfs 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取、文件元数据扩展属性、`/proc/self/fd` 和不跟随链接的描述符打开操作；不支持的模板会失败，而不会静默降级。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 2a7fd1275f..2452e856ca 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -5,6 +5,7 @@
  */
 
 import { createHash, randomUUID } from 'node:crypto'
+import { Buffer } from 'node:buffer'
 import { posix } from 'node:path'
 import { FileSystem, FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -24,10 +25,18 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { BOUNDED_READER_SOURCE } from './source-reader.ts'
 
 const VERSION_METADATA_KEY = 'dsh-version'
 const BINARY_SAMPLE_BYTES = 8192
 
+type BoundedReadResponse =
+  | { kind: 'ok'; data: string }
+  | { kind: 'not-file' }
+  | { kind: 'oversize'; size: number }
+  | { kind: 'grew' }
+  | { kind: 'open-error'; message: string }
+
 function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
   if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
 }
@@ -141,6 +150,21 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
+  override processPath(target: FsTarget): string {
+    return String(target.targetKey)
+  }
+
+  override fileUrl(target: FsTarget): string {
+    const path = this.processPath(target)
+    if (!posix.isAbsolute(path)) throw new Error(`fs-e2b: expected an absolute process path: ${JSON.stringify(path)}`)
+    return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
+  }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    const relative = posix.relative(this.processPath(parent), this.processPath(child))
+    return relative === '' || (relative !== '..' && !relative.startsWith('../') && !posix.isAbsolute(relative))
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     assertNotAborted(signal, 'stat')
     const entry = await this.probe(String(target.targetKey), target.displayPath, signal)
@@ -184,6 +208,69 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+      throw new Error('bounded read maxBytes must be a positive safe integer')
+    }
+    assertNotAborted(signal, 'read')
+    const sandbox = await this.ctx.e2b.getSandbox()
+    try {
+      const node = await sandbox.commands.run('command -v -- node', signalOpts(signal))
+      const executable = node.stdout.trim()
+      if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+        throw new Error('fs-e2b: bounded reader requires one absolute Node executable')
+      }
+      const command = [
+        quoteE2BShellArg(executable),
+        '--input-type=commonjs',
+        '-e',
+        quoteE2BShellArg(BOUNDED_READER_SOURCE),
+        quoteE2BShellArg(this.processPath(target)),
+        String(maxBytes),
+      ].join(' ')
+      const result = await sandbox.commands.run(command, signalOpts(signal))
+      assertNotAborted(signal, 'read')
+      const response = this.parseBoundedRead(result.stdout, target)
+      if (response.kind === 'not-file') {
+        throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
+        throw new FsError(
+          `cannot read "${target.displayPath}": ${response.size} bytes exceeds the ${maxBytes}-byte limit`,
+          'FS_IO_ERROR',
+        )
+      }
+      if (response.kind === 'grew') {
+        throw new FsError(
+          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
+          'FS_IO_ERROR',
+        )
+      }
+      if (response.kind === 'open-error' && typeof response.message === 'string') {
+        if (/ENOENT|no such file/i.test(response.message)) {
+          throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+        }
+        if (/EACCES|EPERM|permission denied|operation not permitted/i.test(response.message)) {
+          throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED')
+        }
+        throw new FsError(
+          `cannot read "${target.displayPath}" safely: ${response.message}`,
+          'FS_IO_ERROR',
+        )
+      }
+      if (response.kind !== 'ok' || typeof response.data !== 'string') {
+        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned an invalid response`, 'FS_IO_ERROR')
+      }
+      const bytes = Buffer.from(response.data, 'base64')
+      if (bytes.toString('base64') !== response.data || bytes.length > maxBytes) {
+        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned invalid bytes`, 'FS_IO_ERROR')
+      }
+      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     const sandbox = await this.ctx.e2b.getSandbox()
     await this.requireRegular(target, signal)
@@ -336,6 +423,18 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
+  private parseBoundedRead(stdout: string, target: FsTarget): BoundedReadResponse {
+    try {
+      return JSON.parse(stdout) as BoundedReadResponse
+    } catch (error: unknown) {
+      throw new FsError(
+        `cannot read "${target.displayPath}": bounded reader returned invalid JSON`,
+        'FS_IO_ERROR',
+        { cause: error },
+      )
+    }
+  }
+
   private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
     assertNotAborted(signal, 'stat')
     try {
diff --git a/packages/e2b/fs-e2b/src/source-reader.ts b/packages/e2b/fs-e2b/src/source-reader.ts
new file mode 100644
index 0000000000..9cb522ecbb
--- /dev/null
+++ b/packages/e2b/fs-e2b/src/source-reader.ts
@@ -0,0 +1,63 @@
+/** Dependency-free stable-handle bounded reader installed inside E2B. */
+export const BOUNDED_READER_SOURCE = String.raw`
+/* dsh-e2b-bounded-reader */
+const fs = require('node:fs')
+const target = process.argv[1]
+const maxBytes = Number(process.argv[2])
+const directoryFlags = fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
+const fileFlags = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
+let directory
+let descriptor
+let response
+
+const openChild = (parent, component, flags) => fs.openSync('/proc/self/fd/' + parent + '/' + component, flags)
+const invalidComponent = component => component === '' || component === '.' || component === '..'
+
+try {
+  if (typeof target !== 'string' || !target.startsWith('/') || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('bounded reader requires an absolute target and positive byte limit')
+  }
+  const components = target === '/' ? [] : target.slice(1).split('/')
+  if (components.length === 0 || components.some(invalidComponent)) {
+    throw new Error('bounded reader received a non-canonical file path')
+  }
+
+  directory = fs.openSync('/', directoryFlags)
+  for (const component of components.slice(0, -1)) {
+    const child = openChild(directory, component, directoryFlags)
+    fs.closeSync(directory)
+    directory = child
+  }
+  descriptor = openChild(directory, components.at(-1), fileFlags)
+
+  const info = fs.fstatSync(descriptor)
+  if (!info.isFile()) response = { kind: 'not-file' }
+  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
+  else {
+    const chunks = []
+    let total = 0
+    while (total <= maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
+      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
+      if (bytesRead === 0) break
+      chunks.push(chunk.subarray(0, bytesRead))
+      total += bytesRead
+    }
+    response = total > maxBytes
+      ? { kind: 'grew' }
+      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
+  }
+} catch (error) {
+  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
+} finally {
+  for (const openDescriptor of [descriptor, directory]) {
+    if (openDescriptor === undefined) continue
+    try {
+      fs.closeSync(openDescriptor)
+    } catch (error) {
+      response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
+    }
+  }
+}
+process.stdout.write(JSON.stringify(response))
+`
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 13d94e70c7..648631c7ee 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer'
 import { dirname, posix } from 'node:path'
 import { Context } from 'cordis'
 import {
@@ -8,7 +9,7 @@ import {
   type Sandbox,
 } from '@deepseek-ai/dsh-e2b'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { FsVersion } from '@deepseek-ai/dsh-fs'
+import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
 import * as E2BFsInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -46,6 +47,10 @@ class FakeRemote {
   nextReadError: unknown
   nextRenameError: unknown
   nextRemoveError: unknown
+  boundedOutput: string | undefined
+  boundedError: unknown
+  nodeExecutable = '/usr/bin/node\n'
+  abortAfterBoundedCommand: AbortController | undefined
   abortAfterRename: AbortController | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
@@ -221,6 +226,14 @@ class FakeRemote {
           const node = this.nodes.get(input)
           return { exitCode: 0, stdout: `${node?.symlinkTarget ?? input}\n`, stderr: '' }
         }
+        if (command === 'command -v -- node') {
+          return { exitCode: 0, stdout: this.nodeExecutable, stderr: '' }
+        }
+        if (command.includes('dsh-e2b-bounded-reader')) {
+          if (this.boundedError !== undefined) throw this.boundedError
+          this.abortAfterBoundedCommand?.abort('after bounded read')
+          return { exitCode: 0, stdout: this.boundedOutput ?? '{"kind":"ok","data":""}', stderr: '' }
+        }
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
         const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
@@ -289,6 +302,26 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect(listed.some(entry => entry.name === 'nested.txt')).toBe(false)
   })
 
+  it('projects canonical process paths, file URLs, and containment', async () => {
+    const remote = new FakeRemote()
+    remote.dir('/workspace/nested')
+    remote.file('/workspace/nested/multibyte # file.ts', 'text')
+    remote.file('/outside.ts', 'outside')
+    const { fs } = await setup(remote)
+    const workspace = await fs.resolve('/workspace')
+    const nested = await fs.resolve('/workspace/nested/multibyte # file.ts')
+    const outside = await fs.resolve('/outside.ts')
+
+    expect(fs.processPath(nested)).toBe('/workspace/nested/multibyte # file.ts')
+    expect(fs.fileUrl(nested)).toBe('file:///workspace/nested/multibyte%20%23%20file.ts')
+    expect(fs.contains(workspace, workspace)).toBe(true)
+    expect(fs.contains(workspace, nested)).toBe(true)
+    expect(fs.contains(nested, workspace)).toBe(false)
+    expect(fs.contains(workspace, outside)).toBe(false)
+    expect(() => fs.fileUrl({ targetKey: FsTargetKey('relative'), displayPath: 'relative' }))
+      .toThrow('expected an absolute process path')
+  })
+
   it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/text.txt', 'A€B')
@@ -373,6 +406,78 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
   })
 
+  it('performs stable bounded reads through the remote no-follow reader', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('a')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('hello 你好').toString('base64') })
+    await expect(fs.readTextBounded(target, 64)).resolves.toBe('hello 你好')
+    expect(remote.commands.some(command => command.includes('dsh-e2b-bounded-reader'))).toBe(true)
+
+    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
+    await expect(fs.readTextBounded(target, 1.5)).rejects.toThrow('positive safe integer')
+    await expect(fs.readTextBounded(target, 64, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+
+  it('maps bounded-reader file, size, and open failures', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('a')
+    const cases: Array<[unknown, string]> = [
+      [{ kind: 'not-file' }, 'FS_NOT_REGULAR_FILE'],
+      [{ kind: 'oversize', size: 65 }, 'FS_IO_ERROR'],
+      [{ kind: 'grew' }, 'FS_IO_ERROR'],
+      [{ kind: 'open-error', message: 'ENOENT: no such file' }, 'FS_NOT_FOUND'],
+      [{ kind: 'open-error', message: 'EACCES: permission denied' }, 'FS_PERMISSION_DENIED'],
+      [{ kind: 'open-error', message: 'ELOOP: symbolic link' }, 'FS_IO_ERROR'],
+      [{ kind: 'oversize', size: 'large' }, 'FS_IO_ERROR'],
+      [{ kind: 'open-error', message: 7 }, 'FS_IO_ERROR'],
+      [{ kind: 'unknown' }, 'FS_IO_ERROR'],
+    ]
+    for (const [response, code] of cases) {
+      remote.boundedOutput = JSON.stringify(response)
+      await expectCode(fs.readTextBounded(target, 64), code)
+    }
+  })
+
+  it('rejects malformed bounded-reader transports and bytes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('a')
+
+    remote.boundedOutput = 'not-json'
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: '!!!!' })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('12345').toString('base64') })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0]).toString('base64') })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0xff]).toString('base64') })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
+
+    remote.nodeExecutable = 'node\n'
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.nodeExecutable = '/usr/bin/node\n/other\n'
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.nodeExecutable = '/usr/bin/node\n'
+    remote.boundedError = new Error('reader transport failed')
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+  })
+
+  it('does not turn a post-read abort into successful source text', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const controller = new AbortController()
+    remote.abortAfterBoundedCommand = controller
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('text').toString('base64') })
+    const { fs } = await setup(remote)
+    await expectCode(fs.readTextBounded(await fs.resolve('a'), 4, controller.signal), 'FS_ABORTED')
+  })
+
   it('rejects empty paths and directory-listing type errors', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/file', 'x')
diff --git a/packages/e2b/pty-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
deleted file mode 100644
index 580f874e62..0000000000
--- a/packages/e2b/pty-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/e2b/pty-e2b/README.md
-README.md: d1b1731cd7b65577a18814a90363acdc66d7d262
-README.zh.md: 4aa2cc8d661e61e80ef61693422a7b6f73c2cb67
diff --git a/packages/e2b/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
deleted file mode 100644
index d1b1731cd7..0000000000
--- a/packages/e2b/pty-e2b/README.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# @deepseek-ai/dsh-pty-e2b
-
-English | [中文](README.zh.md)
-
-E2B byte-PTY backend for [`ctx.pty`](../../pty/pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
-
-## Plugin and configuration
-
-The `pty-e2b` plugin injects `e2b` and `pty`, then registers one backend under `backendType`.
-
-| Key | Default | Meaning |
-|---|---|---|
-| `backendType` | `shell` | Registry type selected by `terminal_open`. |
-| `rows` / `cols` | `40` / `160` | Initial remote PTY size. |
-| `scrollbackLines` | `10000` | Maximum retained logical lines. |
-| `scrollbackMaxBytes` | `4194304` | Maximum retained UTF-8 scrollback bytes. |
-| `maxReadBytes` | `262144` | Maximum bytes returned by one read or settled send. |
-| `pollIntervalMs` | `50` | Host readiness-poll interval. |
-| `idleSilenceMs` | `3000` | Output silence that yields `inferred_idle`. |
-| `timeoutMs` | `30000` | Absolute startup and send wait bound. |
-| `disposeGraceMs` | `3000` | TERM-to-KILL cleanup grace. |
-
-Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute. Before launch, the backend enumerates sandbox-default environment names, blanks `DSH_*` and credential-shaped names, then overlays its controlled terminal values and explicit `spec.env` entries.
-
-## Runtime contract
-
-The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
-
-Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; cancellation rechecks the originating send after lookup so a settled operation cannot signal or fail its successor, and `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
-
-The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
-
-## Model Experience
-
-### Indirect consumer
-
-#### What the model sees
-
-Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, signal results, and cleanup failures.
-
-#### Token effect
-
-None until a consumer returns bounded backend output. Retained host PTY scrollback is not placed in model history by this package.
-
-#### KV Cache effect
-
-No direct invalidation; the consumer owns prompts, schemas, and appended results.
-
-## Known Limitations and Deferred Work
-
-- **Line-oriented terminal model** — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
-- **Readiness is marker-or-silence based** — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so `inferred_idle` is deliberately possible.
-- **UTF-8 only** — invalid byte sequences fail the session instead of returning lossy text.
-- **Deliberate session escape is unmanaged** — a process that calls `setsid` leaves the terminal session and is outside this backend's cleanup identity.
-- **No reconnectable terminal handles** — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.
diff --git a/packages/e2b/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
deleted file mode 100644
index 4aa2cc8d66..0000000000
--- a/packages/e2b/pty-e2b/README.zh.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# @deepseek-ai/dsh-pty-e2b
-
-[English](README.md) | 中文
-
-用于 [`ctx.pty`](../../pty/pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
-
-## 插件与配置
-
-`pty-e2b` 插件注入 `e2b` 和 `pty`，然后以 `backendType` 注册一个后端。
-
-| 配置键 | 默认值 | 含义 |
-|---|---|---|
-| `backendType` | `shell` | `terminal_open` 选择的注册表类型。 |
-| `rows` / `cols` | `40` / `160` | 远程 PTY 的初始尺寸。 |
-| `scrollbackLines` | `10000` | 保留的逻辑行数上限。 |
-| `scrollbackMaxBytes` | `4194304` | 保留的 UTF-8 scrollback 字节数上限。 |
-| `maxReadBytes` | `262144` | 单次读取或发送结算时返回的字节数上限。 |
-| `pollIntervalMs` | `50` | 宿主就绪轮询间隔。 |
-| `idleSilenceMs` | `3000` | 触发 `inferred_idle` 的输出静默时长。 |
-| `timeoutMs` | `30000` | 启动与发送等待的绝对上限。 |
-| `disposeGraceMs` | `3000` | TERM 到 KILL 的清理宽限期。 |
-
-数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。启动前，后端会枚举沙箱默认环境变量名，清空 `DSH_*` 和形似凭据的名称，再覆盖其受控终端值与显式 `spec.env` 条目。
-
-## 运行时契约
-
-该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
-
-每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；取消处理会在查找后重新检查原发送操作是否仍为当前操作，以免已结算的操作向后继操作发送信号或令其失败；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
-
-远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
-
-## 模型体验
-
-### 间接消费方
-
-#### 模型看到的内容
-
-没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因、信号结果和清理失败。
-
-#### Token 影响
-
-消费方返回有界的后端输出前没有影响。本包不会把宿主保留的 PTY scrollback 放入模型历史。
-
-#### KV Cache 影响
-
-不会直接失效；提示词、schema 和追加结果由消费方负责。
-
-## 已知限制与暂缓工作
-
-- **面向行的终端模型**：CSI／OSC 控制序列会被移除；备用屏幕与完整终端仿真仍不受支持。
-- **就绪判断基于标记或静默**：E2B 会公开前台进程组，但不提供本地后端使用的 Linux syscall 检查，因此系统有意保留返回 `inferred_idle` 的可能性。
-- **仅支持 UTF-8**：无效字节序列会使会话失败，而不是返回有损文本。
-- **主动逃离会话的进程不受管理**：调用 `setsid` 的进程会离开终端会话，因而不属于本后端的清理身份。
-- **没有可重连的终端句柄**：保留 E2B 沙箱会保留远程文件，但不会保留宿主所有权、缓冲区、回调或实时 PTY 会话。
diff --git a/packages/e2b/pty-e2b/package.json b/packages/e2b/pty-e2b/package.json
deleted file mode 100644
index cc31699ab1..0000000000
--- a/packages/e2b/pty-e2b/package.json
+++ /dev/null
@@ -1,46 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-pty-e2b",
-  "description": "E2B PTY provider for DeepSeek Harness",
-  "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"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@deepseek-ai/dsh-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-pty": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-e2b": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-pty": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
-  }
-}
diff --git a/packages/e2b/pty-e2b/src/config.ts b/packages/e2b/pty-e2b/src/config.ts
deleted file mode 100644
index e6849bf54d..0000000000
--- a/packages/e2b/pty-e2b/src/config.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-/** Validated configuration for the E2B PTY backend. */
-
-import z from 'schemastery'
-
-/** Public plugin configuration. */
-export interface Config {
-  /** Backend registry type. */
-  backendType?: string
-  /** Initial terminal rows. */
-  rows?: number
-  /** Initial terminal columns. */
-  cols?: number
-  /** Maximum retained logical lines. */
-  scrollbackLines?: number
-  /** Maximum retained UTF-8 bytes. */
-  scrollbackMaxBytes?: number
-  /** Maximum bytes returned by one read or settled viewport. */
-  maxReadBytes?: number
-  /** Readiness polling interval. */
-  pollIntervalMs?: number
-  /** Output silence duration that yields `inferred_idle`. */
-  idleSilenceMs?: number
-  /** Absolute send and startup wait bound. */
-  timeoutMs?: number
-  /** Grace before PTY teardown escalates from TERM to KILL. */
-  disposeGraceMs?: number
-}
-
-/** Configuration after Schemastery defaults. */
-export type ResolvedConfig = Required<Config>
-
-/* jscpd:ignore-start -- Loader requires a backend-local schema and load-time diagnostics. */
-/** Schemastery config exposed by the plugin. */
-export const Config: z<Config> = z.object({
-  backendType: z.string().default('shell'),
-  rows: z.number().default(40),
-  cols: z.number().default(160),
-  scrollbackLines: z.number().default(10_000),
-  scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
-  maxReadBytes: z.number().default(256 * 1024),
-  pollIntervalMs: z.number().default(50),
-  idleSilenceMs: z.number().default(3_000),
-  timeoutMs: z.number().default(30_000),
-  disposeGraceMs: z.number().default(3_000),
-})
-
-/**
- * Validate the resolved configuration before publishing the backend.
- * @param config - Schemastery-resolved plugin configuration.
- * @returns Nothing; success narrows every optional field to its resolved value.
- */
-export function validateConfig(config: Config): asserts config is ResolvedConfig {
-  const resolved = config as ResolvedConfig
-  if (resolved.backendType.length === 0) throw new Error('pty-e2b: backendType must be non-empty')
-  for (const [name, value] of Object.entries(resolved)) {
-    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
-      throw new Error(`pty-e2b: ${name} must be a positive safe integer`)
-    }
-  }
-  if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) {
-    throw new Error('pty-e2b: maxReadBytes must not exceed scrollbackMaxBytes')
-  }
-}
-/* jscpd:ignore-end */
diff --git a/packages/e2b/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
deleted file mode 100644
index d665a734b7..0000000000
--- a/packages/e2b/pty-e2b/src/index.ts
+++ /dev/null
@@ -1,130 +0,0 @@
-/** E2B byte-PTY backend for persistent interactive terminal sessions. */
-
-import { posix } from 'node:path'
-import type { Context } from 'cordis'
-import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
-import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
-import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
-import { E2BPtySession } from './session.ts'
-
-export { Config } from './config.ts'
-export type { Config as PtyE2BConfig } from './config.ts'
-export { E2BPtySession } from './session.ts'
-
-/** Cordis plugin name. */
-export const name = 'pty-e2b'
-/** Required shared sandbox owner and PTY registry. */
-export const inject = ['e2b', 'pty']
-
-const SENSITIVE_ENV_NAME = /KEY|SECRET|TOKEN/i
-
-async function terminalEnvironment(
-  sandbox: Sandbox,
-  spec: PtyBackendSpawnSpec,
-): Promise<Record<string, string>> {
-  const discovered = await sandbox.commands.run(
-    'env -0 | cut -z -d= -f1',
-    spec.signal === undefined ? {} : { signal: spec.signal },
-  )
-  spec.signal?.throwIfAborted()
-  const scrubbed = Object.fromEntries(discovered.stdout.split('\0')
-    .filter(name => name.startsWith('DSH_') || SENSITIVE_ENV_NAME.test(name))
-    .map(name => [name, '']))
-  return {
-    ...scrubbed,
-    TERM: 'dumb',
-    PAGER: 'cat',
-    GIT_PAGER: 'cat',
-    PS1: 'dsh> ',
-    PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
-    BASH_SILENCE_DEPRECATION_WARNING: '1',
-    DSH_SHELL: '1',
-    DSH_SESSION_ID: spec.owner.id,
-    DSH_PTY_SESSION_ID: spec.sessionId,
-  }
-}
-
-async function resolveTerminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
-  const result = await sandbox.commands.run(
-    `ps -o sid= -p ${pid}`,
-    signal === undefined ? {} : { signal },
-  )
-  signal?.throwIfAborted()
-  const raw = result.stdout.trim()
-  const sessionId = Number(raw)
-  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(sessionId)) {
-    throw new Error(`pty-e2b: cannot resolve process session for E2B PTY ${pid}`)
-  }
-  return sessionId
-}
-
-/** E2B backend registered under the configured terminal type. */
-export class E2BPtyBackend implements PtyBackend {
-  readonly type: string
-
-  constructor(
-    private readonly ctx: Context,
-    private readonly config: ResolvedConfig,
-    private readonly createPty: (
-      sandbox: Sandbox,
-      options: Parameters<Sandbox['pty']['create']>[0],
-    ) => Promise<CommandHandle> = (sandbox, options) => sandbox.pty.create(options),
-  ) {
-    this.type = config.backendType
-  }
-
-  /** Create, initialize, and publish one remote PTY session. */
-  async spawn(spec: PtyBackendSpawnSpec): Promise<E2BPtySession> {
-    spec.signal?.throwIfAborted()
-    const sandbox = await this.ctx.e2b.getSandbox()
-    spec.signal?.throwIfAborted()
-    const pending: Uint8Array[] = []
-    const created: { session?: E2BPtySession } = {}
-    const handle = await this.createPty(sandbox, {
-      rows: this.config.rows,
-      cols: this.config.cols,
-      cwd: posix.resolve(this.ctx.e2b.cwd, spec.cwd ?? this.ctx.e2b.cwd),
-      envs: await terminalEnvironment(sandbox, spec),
-      timeoutMs: 0,
-      ...spec.signal === undefined ? {} : { signal: spec.signal },
-      onData: (data) => {
-        if (created.session === undefined) pending.push(Uint8Array.from(data))
-        else created.session.onData(data)
-      },
-    })
-    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
-      await handle.kill().catch(() => false)
-      throw new Error(`pty-e2b: E2B returned invalid PTY pid ${handle.pid}`)
-    }
-    let terminalSessionId: number
-    try {
-      terminalSessionId = await resolveTerminalSessionId(sandbox, handle.pid, spec.signal)
-    } catch (error: unknown) {
-      await handle.kill().catch(() => false)
-      await Promise.allSettled([handle.wait()])
-      throw error
-    }
-    const session = new E2BPtySession(sandbox, handle, terminalSessionId, this.config)
-    created.session = session
-    try {
-      const initializing = session.initialize(spec.signal)
-      for (const data of pending) session.onData(data)
-      await initializing
-      return session
-    } catch (error: unknown) {
-      try {
-        await session.close('E2B PTY startup failed')
-      } catch (cleanupError: unknown) {
-        throw new PtyBackendCleanupError(error, cleanupError)
-      }
-      throw error
-    }
-  }
-}
-
-/** Register the E2B PTY backend. */
-export function apply(ctx: Context, config: Config): void {
-  validateConfig(config)
-  ctx.pty.registerBackend(new E2BPtyBackend(ctx, config))
-}
diff --git a/packages/e2b/pty-e2b/src/invariant.ts b/packages/e2b/pty-e2b/src/invariant.ts
deleted file mode 100644
index b86fdffc5d..0000000000
--- a/packages/e2b/pty-e2b/src/invariant.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-pty-e2b`. */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-pty-e2b'
-
-/** Cordis companion plugin name. */
-export const name = 'pty-e2b-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/** No runtime invariant: the PTY registry owns publication and cleanup. */
-const install: InvariantInstaller = () => {}
-
-/** Register this package's invariant companion. */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/e2b/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
deleted file mode 100644
index 7742cd44f0..0000000000
--- a/packages/e2b/pty-e2b/src/session.ts
+++ /dev/null
@@ -1,415 +0,0 @@
-/** One byte-oriented E2B PTY session projected onto the harness PTY seam. */
-
-import { Buffer } from 'node:buffer'
-import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { CommandExitError } from '@deepseek-ai/dsh-e2b'
-import {
-  PtyTerminalSanitizer,
-  PtyTextBuffer,
-  ptySignalName,
-  ptyUtf8Tail,
-} from '@deepseek-ai/dsh-pty'
-import type {
-  PtyBackendSession,
-  PtyReadRequest,
-  PtyReadResult,
-  PtySendOperation,
-  PtySendRead,
-  PtySendRequest,
-  PtySendResult,
-  PtySessionStatus,
-  PtySignal,
-  PtySignalResult,
-  PtyWaitReason,
-} from '@deepseek-ai/dsh-pty'
-import type { ResolvedConfig } from './config.ts'
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
-/* jscpd:ignore-start -- Operation state stays backend-local because process readiness and cleanup identities diverge. */
-class E2BSendOperation implements PtySendOperation {
-  private readonly output: PtyTextBuffer
-  private readonly result = Promise.withResolvers<PtySendResult>()
-  private finished = false
-
-  constructor(
-    maxBytes: number,
-    readonly startedAt: number,
-    private readonly onCancel: () => void,
-  ) {
-    this.output = new PtyTextBuffer(maxBytes)
-  }
-
-  get done(): Promise<PtySendResult> {
-    return this.result.promise
-  }
-
-  append(text: string): void {
-    if (!this.finished) this.output.append(text)
-  }
-
-  settle(waitReason: PtyWaitReason, sessionStatus: PtySessionStatus, inheritedTruncation: boolean): void {
-    if (this.finished) return
-    this.finished = true
-    const read = this.output.snapshot()
-    this.result.resolve({
-      viewport: read.text,
-      waitReason,
-      sessionStatus,
-      truncated: read.truncated || inheritedTruncation,
-    })
-  }
-
-  fail(error: unknown): void {
-    if (this.finished) return
-    this.finished = true
-    this.result.reject(error)
-  }
-
-  readOutput(): PtySendRead {
-    return this.output.consume()
-  }
-
-  cancel(): boolean {
-    if (this.finished) return false
-    this.onCancel()
-    return true
-  }
-}
-/* jscpd:ignore-end */
-
-/** Live session around one E2B SDK PTY handle. */
-export class E2BPtySession implements PtyBackendSession {
-  motd = ''
-  readonly pid: number
-  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
-  private readonly sanitizer: PtyTerminalSanitizer
-  private readonly scrollback: PtyTextBuffer
-  private readonly exited = Promise.withResolvers<void>()
-  private statusValue: PtySessionStatus = { kind: 'running' }
-  private active: E2BSendOperation | undefined
-  private activeTimer: NodeJS.Timeout | undefined
-  private activeAbort: (() => void) | undefined
-  private promptSeen = false
-  private promptTextSeen = false
-  private initializing = false
-  private lastOutputAt = Date.now()
-  private closing = false
-  private closePromise: Promise<void> | undefined
-  private closeSignal: NodeJS.Signals | null = null
-  private transportFailure: Error | undefined
-  private remoteExited = false
-
-  constructor(
-    private readonly sandbox: Sandbox,
-    private readonly handle: CommandHandle,
-    private readonly terminalSessionId: number,
-    private readonly config: ResolvedConfig,
-  ) {
-    this.pid = handle.pid
-    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
-    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    const completion = handle.wait()
-    void completion.then(
-      (result) => { this.onExit(result.exitCode) },
-      (error: unknown) => {
-        if (error instanceof CommandExitError) this.onExit(error.exitCode)
-        else this.onTransportFailure(error)
-      },
-    )
-  }
-
-  /**
-   * Consume bytes received by the SDK's PTY callback.
-   * @param data - Exact callback bytes in delivery order.
-   */
-  onData(data: Uint8Array): void {
-    let decoded: string
-    try {
-      decoded = this.decoder.decode(data, { stream: true })
-    } catch (error: unknown) {
-      this.onTransportFailure(new Error('pty-e2b: PTY emitted invalid UTF-8', { cause: error }))
-      return
-    }
-    const sanitized = this.sanitizer.push(decoded)
-    this.appendOutput(sanitized.text)
-    if (sanitized.prompt) {
-      this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
-      this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
-    }
-  }
-
-  /**
-   * Await the first prompt or bounded startup fallback.
-   * @param signal - Optional startup cancellation signal.
-   */
-  async initialize(signal?: AbortSignal): Promise<void> {
-    this.initializing = true
-    try {
-      const operation = this.startSend({ text: '', submit: false, ...signal === undefined ? {} : { signal } })
-      const result = await operation.done
-      if (result.waitReason === 'session_exit') throw new Error('E2B PTY shell exited during startup')
-      if (result.waitReason === 'timeout') throw new Error('E2B PTY shell did not reach readiness before startup timeout')
-      this.motd = result.viewport
-    } catch (error: unknown) {
-      signal?.throwIfAborted()
-      throw error
-    } finally {
-      this.initializing = false
-    }
-  }
-
-  /* jscpd:ignore-start -- PTY backends share request admission while owning distinct input and readiness transports. */
-  startSend(request: PtySendRequest): PtySendOperation {
-    if (this.closing) throw new Error('E2B PTY session is closing')
-    if (this.statusValue.kind === 'exited') throw new Error('E2B PTY session has exited')
-    if (this.active !== undefined) throw new Error('E2B PTY session already has an active send')
-    if (request.signal?.aborted === true) throw new Error('E2B PTY send aborted before write')
-
-    const operation = new E2BSendOperation(
-      this.config.maxReadBytes,
-      Date.now(),
-      () => { this.interrupt(operation) },
-    )
-    this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
-    if (request.signal !== undefined) {
-      const onAbort = (): void => { operation.cancel() }
-      request.signal.addEventListener('abort', onAbort, { once: true })
-      this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
-    }
-
-    const input = `${request.text}${request.submit ? '\r' : ''}`
-    if (input.length > 0) {
-      void this.sandbox.pty.sendInput(this.pid, Buffer.from(input)).catch((error: unknown) => {
-        if (this.active === operation) this.failActive(error)
-      })
-    }
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
-    return operation
-  }
-  /* jscpd:ignore-end */
-
-  /* jscpd:ignore-start -- The seam requires identical bounded-read coordinates across backend buffers. */
-  read(request: PtyReadRequest): PtyReadResult {
-    const snapshot = this.scrollback.snapshot()
-    const lines = snapshot.text.split('\n')
-    const totalLines = snapshot.text.length === 0 ? 0 : lines.length
-    const offset = request.offset ?? 0
-    const count = request.count ?? 500
-    if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('PTY read offset must be a non-negative safe integer')
-    if (!Number.isSafeInteger(count) || count <= 0) throw new Error('PTY read count must be a positive safe integer')
-    if (offset >= totalLines) {
-      return { text: '', totalLines, lineBegin: offset, lineEnd: offset, truncated: snapshot.truncated }
-    }
-    const end = totalLines - offset
-    const start = Math.max(0, end - count)
-    const bounded = ptyUtf8Tail(lines.slice(start, end).join('\n'), this.config.maxReadBytes)
-    const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
-    return {
-      text: bounded.text,
-      totalLines,
-      lineBegin: offset,
-      lineEnd: offset + returnedLines,
-      truncated: snapshot.truncated || bounded.truncated,
-    }
-  }
-  /* jscpd:ignore-end */
-
-  /* jscpd:ignore-start -- Signal, status, and close methods preserve the seam shape around remote identities. */
-  async signal(signal: PtySignal): Promise<PtySignalResult> {
-    const pgid = await this.foregroundPgid()
-    return await this.deliverSignal(signal, pgid)
-  }
-
-  private async deliverSignal(signal: PtySignal, pgid: number): Promise<PtySignalResult> {
-    if (signal === 'SIGKILL' && pgid === this.pid) {
-      throw new Error('refusing to SIGKILL the E2B PTY shell; use terminal_close')
-    }
-    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${pgid}`)
-    return { delivered: true, targetPgid: pgid }
-  }
-
-  status(): PtySessionStatus {
-    return this.statusValue
-  }
-
-  close(reason: string): Promise<void> {
-    this.closing = true
-    if (this.closePromise !== undefined) return this.closePromise
-    const closing = this.closeOnce(reason).catch((error: unknown) => {
-      this.closePromise = undefined
-      this.failActive(error)
-      throw error
-    })
-    this.closePromise = closing
-    return closing
-  }
-  /* jscpd:ignore-end */
-
-  private appendOutput(text: string): void {
-    if (text.length === 0) return
-    this.lastOutputAt = Date.now()
-    this.scrollback.append(text)
-    this.active?.append(text)
-  }
-
-  private pollReadiness(operation: E2BSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    const elapsed = Date.now() - operation.startedAt
-    const idleFor = Date.now() - this.lastOutputAt
-    if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs) {
-      this.settleActive('stdin_read')
-      return
-    }
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
-  }
-
-  private settleActive(waitReason: PtyWaitReason): void {
-    const operation = this.active
-    if (operation === undefined) return
-    const inherited = this.scrollback.snapshot().truncated
-    this.clearActive()
-    operation.settle(waitReason, this.statusValue, inherited)
-  }
-
-  private clearActive(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
-    this.activeTimer = undefined
-    this.activeAbort?.()
-    this.activeAbort = undefined
-    this.active = undefined
-  }
-
-  private failActive(error: unknown): void {
-    const operation = this.active
-    if (operation === undefined) return
-    this.clearActive()
-    operation.fail(error)
-  }
-
-  private interrupt(operation: E2BSendOperation): void {
-    if (this.active !== operation) return
-    void this.interruptActive(operation).catch((error: unknown) => {
-      if (this.active === operation) this.failActive(error)
-    })
-  }
-
-  private async interruptActive(operation: E2BSendOperation): Promise<void> {
-    const pgid = await this.foregroundPgid()
-    if (this.active !== operation) return
-    await this.deliverSignal('SIGINT', pgid)
-  }
-
-  private async foregroundPgid(): Promise<number> {
-    const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
-    const raw = result.stdout.trim()
-    const pgid = Number(raw)
-    if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid)) {
-      throw new Error(`cannot resolve foreground process group for E2B PTY ${this.pid}`)
-    }
-    return pgid
-  }
-
-  private async sessionProcessGroups(): Promise<number[]> {
-    const result = await this.sandbox.commands.run(
-      `ps -eo sid=,pgid= | awk '$1 == ${this.terminalSessionId} { print $2 }'`,
-    )
-    const groups = new Set<number>()
-    for (const raw of result.stdout.trim().split(/\s+/)) {
-      if (raw.length === 0) continue
-      const pgid = Number(raw)
-      if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid) || pgid <= 1) {
-        throw new Error(`pty-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.terminalSessionId}`)
-      }
-      groups.add(pgid)
-    }
-    return [...groups]
-  }
-
-  private async signalProcessGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
-    try {
-      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(pgid => `-${pgid}`).join(' ')}`)
-    } catch (error: unknown) {
-      if (!(error instanceof CommandExitError)) throw error
-    }
-  }
-
-  private async awaitSessionEmpty(timeoutMs: number, signal?: 'KILL'): Promise<number[]> {
-    const deadline = Date.now() + timeoutMs
-    for (;;) {
-      const groups = await this.sessionProcessGroups()
-      if (groups.length === 0 || Date.now() >= deadline) return groups
-      if (signal !== undefined) await this.signalProcessGroups(groups, signal)
-      await delay(Math.min(this.config.pollIntervalMs, deadline - Date.now()))
-    }
-  }
-
-  private onExit(exitCode: number): void {
-    this.remoteExited = true
-    let tail = ''
-    try {
-      tail = this.decoder.decode()
-    } catch (error: unknown) {
-      this.transportFailure ??= new Error('pty-e2b: PTY ended with invalid UTF-8', { cause: error })
-    }
-    this.appendOutput(this.sanitizer.push(tail).text)
-    this.appendOutput(this.sanitizer.flush())
-    const inferredSignal = this.closeSignal ?? (exitCode > 128 ? ptySignalName(exitCode - 128) : null)
-    this.statusValue = {
-      kind: 'exited',
-      exitCode: inferredSignal === null ? exitCode : null,
-      signal: inferredSignal,
-    }
-    if (this.transportFailure === undefined) this.settleActive('session_exit')
-    else this.failActive(this.transportFailure)
-    this.exited.resolve()
-  }
-
-  private onTransportFailure(error: unknown): void {
-    const failure = error instanceof Error ? error : new Error(String(error))
-    this.transportFailure ??= failure
-    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
-    this.failActive(failure)
-  }
-
-  private async closeOnce(reason: string): Promise<void> {
-    let survivingGroups = await this.sessionProcessGroups()
-    if (survivingGroups.length > 0) {
-      this.closeSignal = 'SIGTERM'
-      await this.signalProcessGroups(survivingGroups, 'TERM')
-      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs)
-    }
-    if (survivingGroups.length > 0 || !this.remoteExited) {
-      this.closeSignal = 'SIGKILL'
-      if (!this.remoteExited) await this.sandbox.pty.kill(this.pid)
-      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs, 'KILL')
-      if (!this.remoteExited) await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (survivingGroups.length > 0) {
-      throw new Error(`E2B PTY cleanup failed (${reason}); surviving process groups: ${survivingGroups.join(', ')}`)
-    }
-    if (!this.remoteExited) {
-      throw new Error(`E2B PTY cleanup failed (${reason}); surviving pid: ${this.pid}`)
-    }
-    this.settleActive('session_exit')
-    await this.handle.disconnect().catch(() => {})
-    if (this.transportFailure !== undefined) throw this.transportFailure
-  }
-}
diff --git a/packages/e2b/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
deleted file mode 100644
index 476ddc38df..0000000000
--- a/packages/e2b/pty-e2b/tests/index.spec.ts
+++ /dev/null
@@ -1,248 +0,0 @@
-import { Context } from 'cordis'
-import { describe, expect, it, vi } from 'vitest'
-import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
-import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/dsh-pty'
-import { E2BPtyBackend, apply } from '@deepseek-ai/dsh-pty-e2b'
-import { validateConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
-import * as E2BPtyInvariant from '../src/invariant.ts'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-import { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-
-function config() {
-  return {
-    backendType: 'shell', rows: 24, cols: 80,
-    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
-    pollIntervalMs: 1, idleSilenceMs: 2, timeoutMs: 5, disposeGraceMs: 1,
-  }
-}
-
-function owner(ctx: Context): Agent {
-  const id = SessionId('owner')
-  return {
-    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
-    followup: () => AgentMessageId('unused'), steer: () => AgentMessageId('unused'),
-    inject: () => AgentMessageId('unused'), send: () => AgentMessageId('unused'),
-    cancel() {}, whenIdle: () => Promise.resolve(),
-  }
-}
-
-function handle(pid = 123, kill = vi.fn().mockResolvedValue(true)): CommandHandle {
-  const result = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
-  return {
-    pid,
-    wait: () => result.promise,
-    kill,
-    disconnect: vi.fn().mockResolvedValue(undefined),
-  } as unknown as CommandHandle
-}
-
-describe('E2BPtyBackend and plugin', () => {
-  it('creates a remote PTY with isolated environment and initializes the session', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const run = vi.fn(async (command: string) => command.startsWith('env -0')
-      ? { exitCode: 0, stdout: 'NPM_TOKEN\0DSH_STALE\0KEEP\0', stderr: '' }
-      : { exitCode: 0, stdout: '123\n', stderr: '' })
-    const sandbox = { commands: { run } } as unknown as Sandbox
-    ctx.provide('e2b', {
-      cwd: '/workspace',
-      getSandbox: async () => sandbox,
-    } as E2BSandboxService)
-    const created = handle()
-    let options: Parameters<Sandbox['pty']['create']>[0] | undefined
-    const backend = new E2BPtyBackend(ctx, config(), async (_sandbox, received) => {
-      options = received
-      void received.onData(Buffer.from('banner\n'))
-      void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-      return created
-    })
-    const pending = backend.spawn({
-      sessionId: PtySessionId('pty-1'), owner: owner(ctx), type: 'shell', cwd: 'project',
-      signal: new AbortController().signal,
-    })
-    await vi.advanceTimersByTimeAsync(2)
-    const session = await pending
-
-    expect(session.motd).toBe('banner\ndsh> ')
-    expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
-    expect(options?.envs).toMatchObject({
-      NPM_TOKEN: '', DSH_STALE: '',
-      TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
-      DSH_SHELL: '1', DSH_SESSION_ID: 'owner', DSH_PTY_SESSION_ID: 'pty-1',
-    })
-    expect(options?.envs).not.toHaveProperty('KEEP')
-    vi.useRealTimers()
-  })
-
-  it('uses the SDK PTY create method and the shared cwd by default', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const created = handle()
-    const create = vi.fn(async (received: Parameters<Sandbox['pty']['create']>[0]) => {
-      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
-      return created
-    })
-    const sandbox = {
-      commands: { run: async (command: string) => ({ exitCode: 0, stdout: command.startsWith('env -0') ? '' : '123\n', stderr: '' }) },
-      pty: { create },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
-    const backend = new E2BPtyBackend(ctx, config())
-    const pending = backend.spawn({ sessionId: PtySessionId('default'), owner: owner(ctx), type: 'shell' })
-    await vi.advanceTimersByTimeAsync(2)
-    await pending
-    expect(create).toHaveBeenCalledWith(expect.objectContaining({ cwd: '/workspace' }))
-    vi.useRealTimers()
-  })
-
-  it('rejects aborts and invalid pids, killing a malformed SDK handle', async () => {
-    const ctx = new Context()
-    const sandbox = {
-      commands: { run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
-    const create = vi.fn().mockResolvedValue(handle(0))
-    const backend = new E2BPtyBackend(ctx, config(), create)
-    const aborted = AbortSignal.abort(new Error('stop'))
-    await expect(backend.spawn({ sessionId: PtySessionId('one'), owner: owner(ctx), type: 'shell', signal: aborted })).rejects.toThrow('stop')
-    expect(create).not.toHaveBeenCalled()
-
-    const malformedKill = vi.fn().mockResolvedValue(true)
-    const malformed = handle(0, malformedKill)
-    const invalid = new E2BPtyBackend(ctx, config(), async () => malformed)
-    await expect(invalid.spawn({ sessionId: PtySessionId('two'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
-    expect(malformedKill).toHaveBeenCalledOnce()
-
-    const killFailureKill = vi.fn().mockRejectedValue(new Error('already gone'))
-    const killFailure = handle(0, killFailureKill)
-    const raced = new E2BPtyBackend(ctx, config(), async () => killFailure)
-    await expect(raced.spawn({ sessionId: PtySessionId('three'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
-
-    const invalidSessionKill = vi.fn().mockRejectedValue(new Error('kill raced'))
-    const invalidSessionHandle = {
-      pid: 123,
-      wait: vi.fn().mockRejectedValue(new Error('already exited')),
-      kill: invalidSessionKill,
-      disconnect: vi.fn(),
-    } as unknown as CommandHandle
-    const invalidSessionSandbox = {
-      commands: {
-        run: async (command: string) => ({
-          exitCode: 0,
-          stdout: command.startsWith('env -0') ? '' : '9007199254740992\n',
-          stderr: '',
-        }),
-      },
-    } as unknown as Sandbox
-    const invalidSessionContext = new Context()
-    invalidSessionContext.provide('e2b', {
-      cwd: '/workspace',
-      getSandbox: async () => invalidSessionSandbox,
-    } as E2BSandboxService)
-    const invalidSession = new E2BPtyBackend(invalidSessionContext, config(), async () => invalidSessionHandle)
-    await expect(invalidSession.spawn({
-      sessionId: PtySessionId('four'), owner: owner(invalidSessionContext), type: 'shell',
-    }))
-      .rejects.toThrow('cannot resolve process session')
-    expect(invalidSessionKill).toHaveBeenCalledOnce()
-  })
-
-  it('cleans failed startup and aggregates a cleanup failure', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const sandbox = {
-      commands: {
-        run: vi.fn(async (command: string) => ({
-          exitCode: 0,
-          stdout: command.startsWith('ps -o sid=') || command.startsWith('ps -eo sid=') ? '123\n' : '',
-          stderr: '',
-        })),
-      },
-      pty: { kill: vi.fn().mockRejectedValue(new Error('cleanup failed')) },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
-    const failedHandle = handle()
-    const backend = new E2BPtyBackend(ctx, config(), async () => failedHandle)
-    const pending = backend.spawn({ sessionId: PtySessionId('failed'), owner: owner(ctx), type: 'shell' })
-    const rejected = expect(pending).rejects.toMatchObject({
-      name: 'PtyBackendCleanupError',
-      cleanupError: expect.objectContaining({ message: 'cleanup failed' }),
-    } satisfies Partial<PtyBackendCleanupError>)
-    await vi.advanceTimersByTimeAsync(6)
-    await vi.advanceTimersByTimeAsync(2)
-    await rejected
-    vi.useRealTimers()
-  })
-
-  it('preserves startup failure when cleanup succeeds', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const completion = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
-    const created = {
-      pid: 123,
-      wait: () => completion.promise,
-      disconnect: vi.fn().mockResolvedValue(undefined),
-    } as unknown as CommandHandle
-    let sessionRunning = true
-    const sandbox = {
-      commands: {
-        run: vi.fn(async (command: string) => {
-          if (command.startsWith('env -0')) return { exitCode: 0, stdout: '', stderr: '' }
-          if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: '123\n', stderr: '' }
-          if (command.startsWith('ps -eo sid=')) {
-            return { exitCode: 0, stdout: sessionRunning ? '123\n' : '', stderr: '' }
-          }
-          if (command.startsWith('kill -TERM')) {
-            sessionRunning = false
-            completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
-          }
-          return { exitCode: 0, stdout: '', stderr: '' }
-        }),
-      },
-      pty: { kill: vi.fn().mockResolvedValue(true) },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
-    const backend = new E2BPtyBackend(ctx, config(), async () => created)
-    const rejected = expect(backend.spawn({ sessionId: PtySessionId('failed-clean'), owner: owner(ctx), type: 'shell' }))
-      .rejects.toThrow('startup timeout')
-    await vi.advanceTimersByTimeAsync(6)
-    await rejected
-    vi.useRealTimers()
-  })
-
-  it('validates configuration and registers the selected backend type', async () => {
-    const valid = config()
-    expect(() => { validateConfig(valid) }).not.toThrow()
-    for (const invalid of [
-      { ...valid, backendType: '' },
-      { ...valid, rows: 0 },
-      { ...valid, rows: 1.5 },
-      { ...valid, maxReadBytes: 129 },
-    ]) {
-      expect(() => { validateConfig(invalid) }).toThrow()
-    }
-
-    const registerBackend = vi.fn()
-    apply({ pty: { registerBackend } } as unknown as Context, valid)
-    expect(registerBackend).toHaveBeenCalledWith(expect.objectContaining({ type: 'shell' }))
-
-    const ctx = new Context()
-    await ctx.plugin(PtyService)
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => ({}) } as never)
-    const fiber = await ctx.plugin({
-      inject: ['pty', 'e2b'],
-      apply: (pluginCtx: Context) => { apply(pluginCtx, valid) },
-    })
-    expect(ctx.pty.listBackends()).toEqual(['shell'])
-    await fiber.dispose()
-  })
-
-  it('registers the package-owned invariant companion', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    const fiber = await ctx.plugin(E2BPtyInvariant).await()
-    await fiber.dispose()
-  })
-})
diff --git a/packages/e2b/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
deleted file mode 100644
index 1fedf6bbac..0000000000
--- a/packages/e2b/pty-e2b/tests/session.spec.ts
+++ /dev/null
@@ -1,485 +0,0 @@
-import { Buffer } from 'node:buffer'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import {
-  CommandExitError,
-  type CommandHandle,
-  type CommandResult,
-  type Sandbox,
-} from '@deepseek-ai/dsh-e2b'
-import type { PtySendOperation, PtySessionStatus } from '@deepseek-ai/dsh-pty'
-import { E2BPtySession } from '@deepseek-ai/dsh-pty-e2b'
-import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
-
-function commandError(exitCode: number): CommandExitError {
-  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
-}
-
-class FakePtyHandle {
-  pid = 123
-  readonly result = Promise.withResolvers<CommandResult>()
-  disconnects = 0
-  kills = 0
-  disconnectError: unknown
-  private settled = false
-
-  wait(): Promise<CommandResult> {
-    return this.result.promise
-  }
-
-  async disconnect(): Promise<void> {
-    this.disconnects += 1
-    if (this.disconnectError !== undefined) throw this.disconnectError
-  }
-
-  async kill(): Promise<boolean> {
-    this.kills += 1
-    return true
-  }
-
-  exit(exitCode = 0): void {
-    if (this.settled) return
-    this.settled = true
-    this.result.resolve({ exitCode, stdout: '', stderr: '' })
-  }
-
-  failExit(exitCode: number): void {
-    if (this.settled) return
-    this.settled = true
-    this.result.reject(commandError(exitCode))
-  }
-
-  crash(error: unknown): void {
-    if (this.settled) return
-    this.settled = true
-    this.result.reject(error)
-  }
-
-  asHandle(): CommandHandle {
-    return this as unknown as CommandHandle
-  }
-}
-
-class FakeSandbox {
-  readonly sent: Array<{ pid: number; data: Buffer }> = []
-  readonly commands: string[] = []
-  readonly killed: number[] = []
-  pgid = '456\n'
-  sessionGroups = [123]
-  sendError: unknown
-  signalError: unknown
-  killError: unknown
-  foregroundLookup: Promise<CommandResult> | undefined
-  onTerm: (() => void) | undefined
-  onGroupKill: (() => void) | undefined
-  onKill: (() => void) | undefined
-
-  readonly sandbox = {
-    pty: {
-      sendInput: async (pid: number, data: Uint8Array): Promise<void> => {
-        this.sent.push({ pid, data: Buffer.from(data) })
-        if (this.sendError !== undefined) throw this.sendError
-      },
-      kill: async (pid: number): Promise<boolean> => {
-        this.killed.push(pid)
-        if (this.killError !== undefined) throw this.killError
-        this.onKill?.()
-        return true
-      },
-    },
-    commands: {
-      run: async (command: string): Promise<CommandResult> => {
-        this.commands.push(command)
-        if (command.startsWith('ps -o tpgid')) {
-          return await (this.foregroundLookup ?? Promise.resolve({ exitCode: 0, stdout: this.pgid, stderr: '' }))
-        }
-        if (command.startsWith('ps -eo sid=')) {
-          return { exitCode: 0, stdout: this.sessionGroups.map(value => `${value}\n`).join(''), stderr: '' }
-        }
-        if (command.startsWith('kill -')) {
-          if (this.signalError !== undefined) {
-            const error = this.signalError
-            this.signalError = undefined
-            throw error
-          }
-          if (command.startsWith('kill -TERM')) this.onTerm?.()
-          if (command.startsWith('kill -KILL')) this.onGroupKill?.()
-        }
-        return { exitCode: 0, stdout: '', stderr: '' }
-      },
-    },
-  } as unknown as Sandbox
-}
-
-function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
-  return {
-    backendType: 'shell', rows: 24, cols: 80,
-    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
-    pollIntervalMs: 10, idleSilenceMs: 40, timeoutMs: 100, disposeGraceMs: 20,
-    ...overrides,
-  }
-}
-
-async function initialize(session: E2BPtySession): Promise<void> {
-  const pending = session.initialize()
-  session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-  await vi.advanceTimersByTimeAsync(10)
-  await pending
-}
-
-afterEach(() => { vi.useRealTimers() })
-
-describe('E2BPtySession readiness, output, and signals', () => {
-  it('initializes, sends UTF-8 input, settles at a prompt, and reads bounded scrollback', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config({ maxReadBytes: 12 }))
-    expect(session.read({})).toMatchObject({ text: '', totalLines: 0 })
-    await initialize(session)
-    expect(session.motd).toBe('dsh> ')
-
-    const operation = session.startSend({ text: 'printf 你好', submit: true })
-    expect(fake.sent).toEqual([{ pid: 123, data: Buffer.from('printf 你好\r') }])
-    session.onData(Buffer.from('一\n二\n三\x1b]133;D;0\x07dsh> '))
-    const bounded = operation.readOutput()
-    expect(bounded.delta).toContain('三')
-    expect(bounded.truncated).toBe(true)
-    await vi.advanceTimersByTimeAsync(10)
-    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read', sessionStatus: { kind: 'running' } })
-    expect(operation.cancel()).toBe(false)
-    expect(session.read({ count: 2 }).text).toContain('dsh>')
-    expect(session.read({ offset: 99 })).toMatchObject({ text: '', lineBegin: 99, lineEnd: 99 })
-    expect(() => session.read({ offset: -1 })).toThrow('non-negative safe integer')
-    expect(() => session.read({ offset: 1.5 })).toThrow('non-negative safe integer')
-    expect(() => session.read({ count: 0 })).toThrow('positive safe integer')
-    expect(() => session.read({ count: 1.5 })).toThrow('positive safe integer')
-
-    await expect(session.signal('SIGTERM')).resolves.toEqual({ delivered: true, targetPgid: 456 })
-    expect(fake.commands).toContain('kill -TERM -- -456')
-    expect(session.status()).toEqual({ kind: 'running' })
-  })
-
-  it('distinguishes inferred idle, timeout, session exit, and no-output startup timeout', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await initialize(session)
-
-    const inferred = session.startSend({ text: '', submit: false })
-    await vi.advanceTimersByTimeAsync(40)
-    expect((await inferred.done).waitReason).toBe('inferred_idle')
-
-    const timeout = session.startSend({ text: '', submit: false })
-    for (let index = 0; index < 3; index += 1) {
-      await vi.advanceTimersByTimeAsync(30)
-      session.onData(Buffer.from('.'))
-    }
-    await vi.advanceTimersByTimeAsync(10)
-    expect((await timeout.done).waitReason).toBe('timeout')
-
-    const exiting = session.startSend({ text: '', submit: false })
-    handle.failExit(143)
-    expect(await exiting.done).toMatchObject({
-      waitReason: 'session_exit',
-      sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' },
-    })
-    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
-
-    const startupHandle = new FakePtyHandle()
-    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), 123, config())
-    const timedOut = expect(startup.initialize()).rejects.toThrow('startup timeout')
-    await vi.advanceTimersByTimeAsync(100)
-    await timedOut
-  })
-
-  it('handles split prompt text, stale operations, and explicit cancellation', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const initializing = session.initialize()
-    session.onData(Buffer.from('\x1b]133;D;0\x07'))
-    await vi.advanceTimersByTimeAsync(20)
-    session.onData(Buffer.from('dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await initializing
-
-    const operation = session.startSend({ text: 'sleep', submit: true })
-    const internal = session as unknown as {
-      pollReadiness(operation: PtySendOperation): void
-      interrupt(operation: PtySendOperation): void
-      settleActive(reason: 'timeout'): void
-      failActive(error: unknown): void
-      appendOutput(text: string): void
-      statusValue: PtySessionStatus
-    }
-    internal.pollReadiness({} as PtySendOperation)
-    internal.interrupt({} as PtySendOperation)
-    internal.appendOutput('')
-    fake.pgid = '789\n'
-    expect(operation.cancel()).toBe(true)
-    await vi.advanceTimersByTimeAsync(0)
-    expect(fake.commands).toContain('kill -INT -- -789')
-    session.onData(Buffer.from('\x1b]133;D;130\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await operation.done
-
-    internal.settleActive('timeout')
-    internal.failActive(new Error('ignored'))
-    const operationInternal = operation as unknown as {
-      append(text: string): void
-      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
-      fail(error: unknown): void
-    }
-    operationInternal.append('ignored')
-    operationInternal.settle('timeout', { kind: 'running' }, false)
-    operationInternal.fail(new Error('ignored'))
-  })
-
-  it('observes AbortSignal and contains send or foreground lookup failures', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await initialize(session)
-
-    const controller = new AbortController()
-    const aborting = session.startSend({ text: '', submit: false, signal: controller.signal })
-    expect(() => session.startSend({ text: '', submit: false })).toThrow('active send')
-    fake.pgid = 'not-a-pgid\n'
-    controller.abort()
-    await expect(aborting.done).rejects.toThrow('cannot resolve foreground process group')
-
-    const already = new AbortController()
-    already.abort()
-    expect(() => session.startSend({ text: '', submit: false, signal: already.signal })).toThrow('aborted before write')
-
-    fake.sendError = new Error('send failed')
-    const failed = session.startSend({ text: 'x', submit: false })
-    await expect(failed.done).rejects.toThrow('send failed')
-
-    fake.pgid = '123\n'
-    await expect(session.signal('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
-    fake.pgid = '0\n'
-    await expect(session.signal('SIGINT')).rejects.toThrow('cannot resolve')
-
-    const deferred = Promise.withResolvers<undefined>()
-    fake.sendError = undefined
-    const sendInput = vi.spyOn(fake.sandbox.pty, 'sendInput').mockReturnValueOnce(deferred.promise)
-    const late = session.startSend({ text: 'late', submit: false })
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await late.done
-    deferred.reject(new Error('late failure'))
-    await vi.advanceTimersByTimeAsync(0)
-    expect(sendInput).toHaveBeenCalled()
-  })
-
-  it('does not let a stale interrupt signal or fail a successor send', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await initialize(session)
-
-    const lookup = Promise.withResolvers<CommandResult>()
-    fake.foregroundLookup = lookup.promise
-    const stale = session.startSend({ text: 'old', submit: true })
-    expect(stale.cancel()).toBe(true)
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await stale.done
-
-    const successor = session.startSend({ text: 'new', submit: true })
-    fake.signalError = new Error('late interrupt failure')
-    lookup.resolve({ exitCode: 0, stdout: '789\n', stderr: '' })
-    await vi.advanceTimersByTimeAsync(0)
-    expect(fake.commands).not.toContain('kill -INT -- -789')
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await expect(successor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
-
-    const failedLookup = Promise.withResolvers<CommandResult>()
-    fake.foregroundLookup = failedLookup.promise
-    const staleFailure = session.startSend({ text: 'old failure', submit: true })
-    expect(staleFailure.cancel()).toBe(true)
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await staleFailure.done
-    const finalSuccessor = session.startSend({ text: 'new after failure', submit: true })
-    failedLookup.reject(new Error('late lookup failure'))
-    await vi.advanceTimersByTimeAsync(0)
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await expect(finalSuccessor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
-  })
-
-  it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
-    const fake = new FakeSandbox()
-    const abortHandle = new FakePtyHandle()
-    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), 123, config())
-    const controller = new AbortController()
-    const reason = new Error('startup cancelled')
-    const initializing = abortSession.initialize(controller.signal)
-    const rejected = expect(initializing).rejects.toBe(reason)
-    controller.abort(reason)
-    await rejected
-
-    const invalidHandle = new FakePtyHandle()
-    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), 123, config())
-    const pending = invalid.startSend({ text: '', submit: false })
-    invalid.onData(Uint8Array.from([0xff]))
-    await expect(pending.done).rejects.toThrow('invalid UTF-8')
-    expect(invalid.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
-
-    const crashHandle = new FakePtyHandle()
-    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), 123, config())
-    const active = crashed.startSend({ text: '', submit: false })
-    crashHandle.crash('transport gone')
-    await expect(active.done).rejects.toEqual(new Error('transport gone'))
-
-    const startupExitHandle = new FakePtyHandle()
-    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), 123, config())
-    const exitedDuringStartup = expect(startupExit.initialize()).rejects.toThrow('exited during startup')
-    startupExitHandle.exit(7)
-    await exitedDuringStartup
-  })
-
-  it('covers empty bounded reads and polling an exited active session', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const tinyHandle = new FakePtyHandle()
-    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), 123, config({ maxReadBytes: 1 }))
-    tiny.onData(Buffer.from('你'))
-    expect(tiny.read({ count: 1 })).toMatchObject({ text: '', lineEnd: 0 })
-
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const operation = session.startSend({ text: '', submit: false })
-    const internal = session as unknown as {
-      pollReadiness(operation: PtySendOperation): void
-      clearActive(): void
-      statusValue: PtySessionStatus
-    }
-    internal.statusValue = { kind: 'exited', exitCode: 7, signal: null }
-    internal.pollReadiness(operation)
-    expect((await operation.done).waitReason).toBe('session_exit')
-    internal.clearActive()
-  })
-})
-
-describe('E2BPtySession teardown', () => {
-  it('terminates the process group once, awaits exit, and disconnects', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const first = session.close('done')
-    expect(session.close('again')).toBe(first)
-    await first
-    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGTERM' })
-    expect(handle.disconnects).toBe(1)
-    expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
-  })
-
-  it('escalates every job-control group that survives shell exit', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    fake.sessionGroups = [123, 456]
-    const handle = new FakePtyHandle()
-    fake.onTerm = () => { fake.sessionGroups = [456]; handle.failExit(143) }
-    fake.onGroupKill = () => { fake.sessionGroups = [] }
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-
-    const closing = session.close('tree cleanup')
-    await vi.advanceTimersByTimeAsync(100)
-    await closing
-
-    expect(fake.commands).toContain('kill -TERM -- -123 -456')
-    expect(fake.commands).toContain('kill -KILL -- -456')
-  })
-
-  it('contains an already-gone TERM, escalates to KILL, and reports a survivor', async () => {
-    vi.useFakeTimers()
-    const gone = new FakeSandbox()
-    const goneHandle = new FakePtyHandle()
-    gone.signalError = commandError(1)
-    gone.onGroupKill = () => { gone.sessionGroups = [] }
-    gone.onKill = () => { goneHandle.failExit(137) }
-    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), 123, config())
-    const closingGone = goneSession.close('gone')
-    await vi.advanceTimersByTimeAsync(100)
-    await closingGone
-    expect(gone.killed).toEqual([123])
-    expect(goneSession.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGKILL' })
-
-    const survivor = new FakeSandbox()
-    const survivorHandle = new FakePtyHandle()
-    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
-    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving process groups: 123')
-    await vi.advanceTimersByTimeAsync(100)
-    await failed
-    survivorHandle.exit()
-    survivor.sessionGroups = []
-    await expect(survivorSession.close('retry')).resolves.toBeUndefined()
-  })
-
-  it('propagates cleanup transport failures and lets close retry', async () => {
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    fake.signalError = new Error('TERM transport failed')
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await expect(session.close('failure')).rejects.toThrow('TERM transport failed')
-    handle.exit()
-    fake.sessionGroups = []
-    await expect(session.close('retry')).resolves.toBeUndefined()
-
-    const invalidTailHandle = new FakePtyHandle()
-    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), 123, config())
-    invalidTail.onData(Uint8Array.from([0xe2]))
-    invalidTailHandle.exit()
-    await expect(invalidTail.close('invalid tail')).rejects.toThrow('invalid UTF-8')
-
-    const normalHandle = new FakePtyHandle()
-    normalHandle.disconnectError = new Error('disconnect raced')
-    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), 123, config())
-    normalHandle.exit(7)
-    await Promise.resolve()
-    expect(normal.status()).toEqual({ kind: 'exited', exitCode: 7, signal: null })
-    await expect(normal.close('already exited')).resolves.toBeUndefined()
-  })
-
-  it('rejects invalid session groups and a shell handle that survives SDK kill', async () => {
-    const invalid = new FakeSandbox()
-    invalid.sessionGroups = [1]
-    const invalidSession = new E2BPtySession(invalid.sandbox, new FakePtyHandle().asHandle(), 123, config())
-    await expect(invalidSession.close('invalid group')).rejects.toThrow('invalid process group')
-
-    vi.useFakeTimers()
-    const survivor = new FakeSandbox()
-    survivor.sessionGroups = []
-    const survivorHandle = new FakePtyHandle()
-    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
-    const failed = expect(survivorSession.close('shell survived')).rejects.toThrow('surviving pid: 123')
-    await vi.advanceTimersByTimeAsync(100)
-    await failed
-    expect(survivor.killed).toEqual([123])
-  })
-
-  it('kills a remotely live PTY after its host transport fails', async () => {
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const active = session.startSend({ text: '', submit: false })
-    session.onData(Uint8Array.from([0xff]))
-    await expect(active.done).rejects.toThrow('invalid UTF-8')
-    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
-
-    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
-    await expect(session.close('transport failed')).rejects.toThrow('invalid UTF-8')
-    expect(fake.commands).toContain('kill -TERM -- -123')
-    expect(handle.disconnects).toBe(1)
-  })
-})
diff --git a/packages/e2b/pty-e2b/tsconfig.json b/packages/e2b/pty-e2b/tsconfig.json
deleted file mode 100644
index 06bf0cd589..0000000000
--- a/packages/e2b/pty-e2b/tsconfig.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../../../vendor/cosmokit" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../../vendor/schemastery" },
-    { "path": "../e2b" },
-    { "path": "../../pty/pty" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index f05191a45b..dca7b016c2 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 066d35a099f560fe40fe629ede632c37535129f7
-README.zh.md: d3af14e8cc58c7d86331156358f78a0abbb24c39
+README.md: e0805345e708c67c6de721d95641e2366a7f990e
+README.zh.md: f83969c794e50f0658aa86218a0f5f3c89d53b56
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 066d35a099..e0805345e7 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,16 +2,18 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, LSP, and subprocess Code Runtime consumers then execute in the shared remote sandbox without E2B-specific capability packages.
 
 ## Behavior
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
 - **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
-The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands.
+The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
@@ -24,9 +26,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate even when this adapter exposes bounded tails, so the subprocess seam's normal host-memory bound is not achieved.
-- **Pipe output is not byte-faithful** — E2B delivers separately decoded strings rather than raw bytes, so split multibyte sequences and arbitrary binary protocols can be corrupted; LSP and other framed byte-stream consumers are unsupported.
+- **Command-pipe output is text-decoded by the SDK** — valid UTF-8 protocol traffic, including the exercised LSP composition and Code Runtime's ASCII/base64 frames, is supported; arbitrary binary protocols and invalid UTF-8 are not byte-faithful.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
 - **Signal attribution is inferred** — when termination was requested and E2B reports a nonzero exit code, the adapter reports the last requested signal because the SDK result does not identify the terminating signal.
-- **Linux utility and E2B transport semantics are assumed** — there is no PTY, Windows, arbitrary-template, or network-partition fidelity layer.
+- **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
+- **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index d3af14e8cc..f83969c794 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,16 +2,18 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY、LSP 以及使用 subprocess 的 Code Runtime 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
 
 ## 行为
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
 - **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
-基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令。
+基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
@@ -24,9 +26,10 @@
 ## 已知限制与延后工作
 
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会持续累积，因此无法达到进程管理 seam 通常提供的宿主内存边界。
-- **Pipe 输出并非字节保真**：E2B 交付的是分别解码后的字符串，而不是原始字节，因此拆分的多字节序列和任意二进制协议可能损坏；不支持 LSP 及其他带帧字节流消费方。
+- **命令管道输出由 SDK 解码为文本**：支持有效的 UTF-8 协议流量，包括已经过测试的 LSP 组合与 Code Runtime 的 ASCII/base64 帧；任意二进制协议和无效 UTF-8 不具备字节保真。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
 - **信号归因依靠推断**：如果已经请求终止，而 E2B 报告非零退出码，适配器会报告最后请求的信号，因为 SDK 结果不标识终止信号。
-- **依赖 Linux 工具与 E2B 传输语义**：没有 PTY、Windows、任意模板或网络分区的保真层。
+- **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 2856df67bd..1547e1b46e 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -8,29 +8,87 @@ import { randomUUID } from 'node:crypto'
 import { posix } from 'node:path'
 import { Context } from 'cordis'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import { E2BSubprocessHandle } from './process.ts'
+import { spawnE2BTerminal } from './terminal.ts'
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
 
 /** E2B command manager registered as `ctx.subprocess`. */
 export class E2BSubprocessService extends SubprocessService {
   static inject = ['e2b']
 
   private readonly live = new Set<E2BSubprocessHandle>()
+  private readonly terminals = new Set<SubprocessTerminalHandle>()
+
+  /** @inheritdoc */
+  readonly cwd: string
+
+  /** @inheritdoc */
+  readonly runtimeRoot: string
 
   /** Create the E2B subprocess service and bind its disposal policy. */
   constructor(ctx: Context) {
     super(ctx)
+    this.cwd = ctx.e2b.cwd
+    this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
       const handles = [...this.live]
-      for (const handle of handles) handle.terminate()
-      await Promise.all(handles.map(async (handle) => {
-        await handle.done.catch(() => {})
-        await handle.waitForExit()
-      }))
+      const terminals = [...this.terminals]
+      const pending: Promise<unknown>[] = []
+      for (const handle of handles) {
+        handle.terminate()
+        pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
+      }
+      for (const terminal of terminals) {
+        terminal.terminate()
+        pending.push(terminal.waitForExit())
+      }
       this.live.clear()
+      this.terminals.clear()
+      await Promise.all(pending)
     }, 'e2b subprocess teardown')
   }
 
+  /** @inheritdoc */
+  async resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    if (command.length === 0) throw new Error('subprocess-e2b: executable name must be non-empty')
+    signal?.throwIfAborted()
+    const sandbox = await this.ctx.e2b.getSandbox()
+    if (posix.isAbsolute(command)) {
+      await sandbox.commands.run(
+        `test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`,
+        signalOpts(signal),
+      )
+      signal?.throwIfAborted()
+      return command
+    }
+    const path = env?.PATH
+    const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
+    const result = await sandbox.commands.run(
+      `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
+      signalOpts(signal),
+    )
+    signal?.throwIfAborted()
+    const executable = result.stdout.trim()
+    if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+      throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
+    }
+    return executable
+  }
+
   /** @inheritdoc */
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
     const program = spec.argv[0]
@@ -53,6 +111,29 @@ export class E2BSubprocessService extends SubprocessService {
     void handle.done.then(release, release).catch(() => {})
     return handle
   }
+
+  /** @inheritdoc */
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('subprocess-e2b: terminal argv must contain a program')
+    }
+    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`subprocess-e2b: terminal ${name} must be a positive safe integer`)
+      }
+    }
+    spec.signal?.throwIfAborted()
+    const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
+    const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
+    this.terminals.add(terminal)
+    const release = async (): Promise<void> => {
+      await terminal.waitForExit()
+      this.terminals.delete(terminal)
+    }
+    void terminal.done.then(release, release).catch(() => {})
+    return terminal
+  }
 }
 
 export default E2BSubprocessService
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
new file mode 100644
index 0000000000..88bea44fde
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -0,0 +1,386 @@
+/** E2B PTY allocation and process-session ownership for the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:os'
+import { PassThrough } from 'node:stream'
+import { posix } from 'node:path'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+
+const POLL_MS = 20
+
+const TERMINAL_RUNNER_SOURCE = [
+  '#!/bin/bash',
+  'set -euo pipefail',
+  'dsh_state=$1',
+  'mapfile -d \'\' -t dsh_env < "$dsh_state/environment"',
+  'mapfile -d \'\' -t dsh_argv < "$dsh_state/argv"',
+  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/runner.bash"',
+  'if (( ${#dsh_argv[@]} == 0 )); then',
+  "  printf 'terminal runner received empty argv\\n' >&2",
+  '  exit 125',
+  'fi',
+  "printf 'ready\\n' > \"$dsh_state/ready\"",
+  'exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"',
+  '',
+].join('\n')
+
+interface TerminalPaths {
+  runner: string
+  environment: string
+  argv: string
+  ready: string
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function commandSignal(exitCode: number): NodeJS.Signals | null {
+  const number = exitCode - 128
+  if (number <= 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
+
+function parsePositiveId(value: string, message: string): number {
+  const raw = value.trim()
+  const id = Number(raw)
+  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(id)) throw new Error(message)
+  return id
+}
+
+function serializeValues(values: readonly string[], kind: string): string {
+  for (const value of values) {
+    if (value.includes('\0')) throw new Error(`subprocess-e2b: terminal ${kind} must not contain NUL bytes`)
+  }
+  return values.map(value => `${value}\0`).join('')
+}
+
+function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
+  const environment = new Map<string, string>()
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    const name = entry.slice(0, separator)
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, entry.slice(separator + 1))
+  }
+  for (const [name, value] of Object.entries(explicit ?? {})) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+      throw new Error('subprocess-e2b: terminal environment entries require non-empty NUL-free names without = and NUL-free values')
+    }
+    environment.set(name, value)
+  }
+  return serializeValues([...environment].map(([name, value]) => `${name}=${value}`), 'environment')
+}
+
+async function terminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
+  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, signalOpts(signal))
+  signal?.throwIfAborted()
+  return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
+}
+
+async function waitUntilReady(
+  sandbox: Sandbox,
+  paths: TerminalPaths,
+  completion: Promise<CommandResult>,
+  signal?: AbortSignal,
+): Promise<void> {
+  const settled = completion.then(() => true, () => true)
+  for (;;) {
+    signal?.throwIfAborted()
+    try {
+      if ((await sandbox.files.read(paths.ready, signalOpts(signal))).trim() === 'ready') return
+    } catch (error: unknown) {
+      if (!(error instanceof FileNotFoundError)) throw error
+    }
+    if (await Promise.race([settled, delay(POLL_MS).then(() => false)])) {
+      throw new Error('subprocess-e2b: terminal exited before publishing readiness')
+    }
+  }
+}
+
+/** One E2B PTY and all process groups in its remote process session. */
+export class E2BTerminalHandle implements SubprocessTerminalHandle {
+  readonly pid: number
+  readonly done: Promise<SubprocessOutcome>
+
+  private topLevelExited = false
+  private termination: Promise<void> | undefined
+  private terminationSignal: NodeJS.Signals | null = null
+  private removeAbort: (() => void) | undefined
+
+  constructor(
+    private readonly sandbox: Sandbox,
+    private readonly handle: CommandHandle,
+    readonly output: PassThrough,
+    private readonly completion: Promise<CommandResult>,
+    private readonly sessionId: number,
+    private readonly stateDir: string,
+    private readonly graceMs: number,
+    signal?: AbortSignal,
+  ) {
+    this.pid = handle.pid
+    this.done = this.waitForCommand()
+    void this.done.then(() => { this.terminate() }, () => { this.terminate() })
+    if (signal !== undefined) {
+      const onAbort = (): void => { this.terminate() }
+      signal.addEventListener('abort', onAbort, { once: true })
+      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+      if (signal.aborted) this.terminate()
+    }
+  }
+
+  /** @inheritdoc */
+  async write(data: Uint8Array): Promise<void> {
+    if (this.topLevelExited) throw new Error('terminal process has exited')
+    await this.sandbox.pty.sendInput(this.pid, data)
+  }
+
+  /** @inheritdoc */
+  async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    try {
+      const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
+      return {
+        processGroupId: parsePositiveId(
+          result.stdout,
+          `subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`,
+        ),
+        // E2B exposes process-table commands but not the /proc memory access
+        // needed to prove a specific syscall is waiting on fd 0.
+        inputWaiting: false,
+      }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError && this.topLevelExited) return undefined
+      throw error
+    }
+  }
+
+  /** @inheritdoc */
+  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    const foreground = await this.inspectForeground()
+    if (foreground === undefined) {
+      throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
+    }
+    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+    }
+    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${foreground.processGroupId}`)
+    return foreground.processGroupId
+  }
+
+  /** @inheritdoc */
+  terminate(): void {
+    this.termination ??= this.closeOnce().catch((error: unknown) => {
+      this.termination = undefined
+      throw error
+    })
+    void this.termination.catch(() => {})
+  }
+
+  /** @inheritdoc */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    const quiescence = this.termination ?? this.done.then(
+      () => { this.terminate(); return this.termination },
+      () => { this.terminate(); return this.termination },
+    )
+    if (signal === undefined) {
+      await quiescence
+      return true
+    }
+    if (signal.aborted) return false
+    return await new Promise<boolean>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(false) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void quiescence.then(
+        () => { cleanup(); resolve(true) },
+        (error: unknown) => {
+          cleanup()
+          reject(error instanceof Error ? error : new Error(String(error)))
+        },
+      )
+    })
+  }
+
+  private async waitForCommand(): Promise<SubprocessOutcome> {
+    try {
+      const result = await this.completion
+      return { exitCode: result.exitCode, signal: null }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) {
+        const signal = this.terminationSignal ?? commandSignal(error.exitCode)
+        return signal === null ? { exitCode: error.exitCode, signal: null } : { exitCode: null, signal }
+      }
+      this.output.destroy(error instanceof Error ? error : new Error(String(error)))
+      throw error
+    } finally {
+      this.topLevelExited = true
+      if (!this.output.destroyed) this.output.end()
+    }
+  }
+
+  private async sessionProcessGroups(): Promise<number[]> {
+    const result = await this.sandbox.commands.run(
+      `ps -eo sid=,pgid= | awk '$1 == ${this.sessionId} { print $2 }'`,
+    )
+    const groups = new Set<number>()
+    for (const raw of result.stdout.trim().split(/\s+/)) {
+      if (raw.length === 0) continue
+      const group = parsePositiveId(
+        raw,
+        `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.sessionId}`,
+      )
+      if (group <= 1) {
+        throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${this.sessionId}`)
+      }
+      groups.add(group)
+    }
+    return [...groups]
+  }
+
+  private async signalGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+    if (groups.length === 0) return
+    try {
+      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
+    } catch (error: unknown) {
+      if (!(error instanceof CommandExitError)) throw error
+    }
+  }
+
+  private async awaitSessionEmpty(kill = false): Promise<number[]> {
+    const deadline = Date.now() + this.graceMs
+    for (;;) {
+      const groups = await this.sessionProcessGroups()
+      if (groups.length === 0 || Date.now() >= deadline) return groups
+      if (kill) await this.signalGroups(groups, 'KILL')
+      await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
+    }
+  }
+
+  private async closeOnce(): Promise<void> {
+    let groups = await this.sessionProcessGroups()
+    if (groups.length > 0) {
+      this.terminationSignal = 'SIGTERM'
+      await this.signalGroups(groups, 'TERM')
+      groups = await this.awaitSessionEmpty()
+    }
+    if (groups.length === 0 && !this.topLevelExited) {
+      await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
+    }
+    if (groups.length > 0 || !this.topLevelExited) {
+      this.terminationSignal = 'SIGKILL'
+      if (!this.topLevelExited) await this.sandbox.pty.kill(this.pid)
+      groups = await this.awaitSessionEmpty(true)
+      if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
+    }
+    if (groups.length > 0) {
+      throw new Error(`subprocess-e2b: terminal cleanup failed; surviving process groups: ${groups.join(', ')}`)
+    }
+    if (!this.topLevelExited) {
+      throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
+    }
+    this.removeAbort?.()
+    this.removeAbort = undefined
+    await this.handle.disconnect()
+    await this.sandbox.files.remove(this.stateDir).catch(() => {})
+  }
+}
+
+/**
+ * Allocate an E2B PTY, replace its bootstrap shell with the requested argv,
+ * and return only after the private runner has published readiness.
+ * @param runtime - Shared E2B sandbox owner.
+ * @param spec - Fully specified terminal-process request.
+ * @param stateDir - Private remote directory for one startup transaction.
+ * @returns The live subprocess terminal handle.
+ */
+export async function spawnE2BTerminal(
+  runtime: E2BSandboxService,
+  spec: SubprocessTerminalSpawnSpec,
+  stateDir: string,
+): Promise<E2BTerminalHandle> {
+  const sandbox = await runtime.getSandbox()
+  spec.signal?.throwIfAborted()
+  const paths: TerminalPaths = {
+    runner: posix.join(stateDir, 'runner.bash'),
+    environment: posix.join(stateDir, 'environment'),
+    argv: posix.join(stateDir, 'argv'),
+    ready: posix.join(stateDir, 'ready'),
+  }
+  const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
+  const environment = remoteEnvironment(ambient.stdout, spec.env)
+  const argv = serializeValues(spec.argv, 'argv')
+  await sandbox.files.makeDir(stateDir)
+  await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
+  await sandbox.files.write([
+    { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
+    { path: paths.environment, data: environment },
+    { path: paths.argv, data: argv },
+  ], signalOpts(spec.signal))
+  await sandbox.commands.run(
+    `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
+    signalOpts(spec.signal),
+  )
+
+  const output = new PassThrough()
+  let handle: CommandHandle | undefined
+  let completion: Promise<CommandResult> | undefined
+  try {
+    handle = await sandbox.pty.create({
+      rows: spec.rows,
+      cols: spec.cols,
+      cwd: spec.cwd,
+      envs: { TERM: 'dumb' },
+      timeoutMs: 0,
+      ...signalOpts(spec.signal),
+      onData: (data) => { if (!output.destroyed) output.write(Buffer.from(data)) },
+    })
+    completion = handle.wait()
+    void completion.catch(() => {})
+    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+      throw new Error(`subprocess-e2b: E2B returned invalid terminal pid ${handle.pid}`)
+    }
+    const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
+    await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
+    await waitUntilReady(sandbox, paths, completion, spec.signal)
+    const sessionId = await terminalSessionId(sandbox, handle.pid, spec.signal)
+    return new E2BTerminalHandle(
+      sandbox,
+      handle,
+      output,
+      completion,
+      sessionId,
+      stateDir,
+      spec.graceMs,
+      spec.signal,
+    )
+  } catch (error: unknown) {
+    output.destroy()
+    if (handle !== undefined) await handle.kill().catch(() => false)
+    if (completion !== undefined) await completion.catch(() => {})
+    await sandbox.files.remove(stateDir).catch(() => {})
+    throw error
+  }
+}
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
new file mode 100644
index 0000000000..9022e3d213
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -0,0 +1,541 @@
+import { Buffer } from 'node:buffer'
+import { once } from 'node:events'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { spawnE2BTerminal } from '../src/terminal.ts'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+class FakeTerminalCommandHandle {
+  pid = 123
+  disconnects = 0
+  sdkKills = 0
+  disconnectError: unknown
+  sdkKillError: unknown
+  private readonly result = Promise.withResolvers<CommandResult>()
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    return this.result.promise
+  }
+
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
+  async kill(): Promise<boolean> {
+    this.sdkKills += 1
+    if (this.sdkKillError !== undefined) {
+      const error = this.sdkKillError
+      this.fail(137)
+      throw error
+    }
+    this.fail(137)
+    return true
+  }
+
+  succeed(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  fail(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+
+  asHandle(): CommandHandle {
+    return this as unknown as CommandHandle
+  }
+}
+
+class FakeTerminalSandbox {
+  readonly handle = new FakeTerminalCommandHandle()
+  readonly commands: string[] = []
+  readonly inputs: Array<{ pid: number; data: Buffer }> = []
+  readonly removed: string[] = []
+  readonly directories: string[] = []
+  readonly writes = new Map<string, string>()
+  createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
+  ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  ready: string | Error = 'ready\n'
+  sessionId = '123\n'
+  foreground = '456\n'
+  groups = [123]
+  createError: unknown
+  sendError: unknown
+  commandFailure: unknown
+  foregroundFailure: unknown
+  termFailure: unknown
+  removeError: unknown
+  clearOnTerm = true
+  clearOnKill = true
+  settleOnPtyKill = true
+  ptyKills = 0
+  resolvedExecutable = '/usr/bin/node\n'
+
+  readonly sandbox = {
+    files: {
+      makeDir: async (path: string): Promise<boolean> => {
+        this.directories.push(path)
+        return true
+      },
+      write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
+        for (const file of files) this.writes.set(file.path, file.data)
+        return files.map(() => ({}))
+      },
+      read: async (): Promise<string> => {
+        if (this.ready instanceof Error) throw this.ready
+        return this.ready
+      },
+      remove: async (path: string): Promise<void> => {
+        this.removed.push(path)
+        if (this.removeError !== undefined) throw this.removeError
+      },
+    },
+    commands: {
+      run: async (command: string, options?: { signal?: AbortSignal }): Promise<CommandResult> => {
+        this.commands.push(command)
+        options?.signal?.throwIfAborted()
+        if (this.commandFailure !== undefined) {
+          const error = this.commandFailure
+          this.commandFailure = undefined
+          throw error
+        }
+        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        if (command.includes('command -v -- ')) {
+          return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
+        }
+        if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        if (command.startsWith('ps -o tpgid=')) {
+          if (this.foregroundFailure !== undefined) throw this.foregroundFailure
+          return { exitCode: 0, stdout: this.foreground, stderr: '' }
+        }
+        if (command.startsWith('ps -eo sid=')) {
+          return { exitCode: 0, stdout: this.groups.map(group => `${group}\n`).join(''), stderr: '' }
+        }
+        if (command.startsWith('kill -TERM -- ')) {
+          if (this.termFailure !== undefined) throw this.termFailure
+          if (this.clearOnTerm) {
+            this.groups = []
+            this.handle.fail(143)
+          }
+        }
+        if (command.startsWith('kill -KILL -- ') && this.clearOnKill) this.groups = []
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+    pty: {
+      create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
+        this.createOptions = options
+        if (this.createError !== undefined) throw this.createError
+        await options.onData(Buffer.from('buffered banner\n'))
+        return this.handle.asHandle()
+      },
+      sendInput: async (pid: number, data: Uint8Array, options?: { signal?: AbortSignal }): Promise<void> => {
+        options?.signal?.throwIfAborted()
+        this.inputs.push({ pid, data: Buffer.from(data) })
+        if (this.sendError !== undefined) throw this.sendError
+      },
+      kill: async (pid: number): Promise<boolean> => {
+        this.ptyKills += 1
+        if (this.settleOnPtyKill) this.handle.fail(137)
+        return pid === this.handle.pid
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function runtime(fake: FakeTerminalSandbox): E2BSandboxService {
+  return {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    disposeMode: 'kill',
+    getSandbox: async () => fake.sandbox,
+  } as unknown as E2BSandboxService
+}
+
+function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessTerminalSpawnSpec {
+  return {
+    argv: ['/bin/bash', '--noprofile', '--norc'],
+    cwd: '/workspace',
+    rows: 24,
+    cols: 80,
+    graceMs: 5,
+    env: { TERM: 'dumb', DSH_SESSION_ID: 'owner', TOKEN_EXPLICIT: 'kept' },
+    ...overrides,
+  }
+}
+
+describe('E2B terminal allocation', () => {
+  it('boots the requested argv through a private runner and preserves buffered bytes', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
+    let output = ''
+    terminal.output.on('data', (chunk) => { output += String(chunk) })
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(output).toBe('buffered banner\n')
+    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
+    expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('TOKEN_EXPLICIT=kept\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
+    expect(fake.writes.get('/runtime/terminal-one/argv')).toBe('/bin/bash\0--noprofile\0--norc\0')
+    const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
+    expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
+    expect(runner).toContain('exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"')
+    expect(runner).not.toContain('\u007f')
+
+    await terminal.write(Buffer.from('echo ok\r'))
+    expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
+    await expect(terminal.inspectForeground()).resolves.toEqual({ processGroupId: 456, inputWaiting: false })
+    await expect(terminal.signalForeground('SIGINT')).resolves.toBe(456)
+    expect(fake.commands).toContain('kill -INT -- -456')
+
+    terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.handle.disconnects).toBe(1)
+    expect(fake.removed).toContain('/runtime/terminal-one')
+  })
+
+  it('inherits only safe ambient values and binds live abort to terminal cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const controller = new AbortController()
+    const terminal = await spawnE2BTerminal(
+      runtime(fake),
+      spec({ env: undefined, signal: controller.signal }),
+      '/runtime/abort-live',
+    )
+    const environment = fake.writes.get('/runtime/abort-live/environment') ?? ''
+    expect(environment).toContain('KEEP=visible\0')
+    expect(environment).not.toContain('secret')
+    expect(environment).not.toContain('DSH_STALE')
+
+    controller.abort(new Error('stop'))
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(terminal.waitForExit(controller.signal)).resolves.toBe(false)
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('rejects malformed environment and argv values before PTY allocation', async () => {
+    const invalidName = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
+      .rejects.toThrow('environment entries')
+    expect(invalidName.createOptions).toBeUndefined()
+
+    const invalidValue = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
+      .rejects.toThrow('environment entries')
+
+    const invalidArg = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
+      .rejects.toThrow('argv must not contain NUL')
+  })
+
+  it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
+    const invalidPid = new FakeTerminalSandbox()
+    invalidPid.handle.pid = 0
+    await expect(spawnE2BTerminal(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
+      .rejects.toThrow('invalid terminal pid 0')
+    expect(invalidPid.handle.sdkKills).toBe(1)
+    expect(invalidPid.removed).toContain('/runtime/invalid-pid')
+
+    const failedInput = new FakeTerminalSandbox()
+    failedInput.sendError = new Error('bootstrap failed')
+    await expect(spawnE2BTerminal(runtime(failedInput), spec(), '/runtime/input'))
+      .rejects.toThrow('bootstrap failed')
+    expect(failedInput.handle.sdkKills).toBe(1)
+
+    const exited = new FakeTerminalSandbox()
+    exited.ready = new FileNotFoundError('not ready')
+    queueMicrotask(() => { exited.handle.succeed(0) })
+    await expect(spawnE2BTerminal(runtime(exited), spec(), '/runtime/exited'))
+      .rejects.toThrow('exited before publishing readiness')
+
+    const invalidSession = new FakeTerminalSandbox()
+    invalidSession.sessionId = 'not-a-session\n'
+    await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
+      .rejects.toThrow('cannot resolve process session')
+    expect(invalidSession.handle.sdkKills).toBe(1)
+
+    const cleanupFailed = new FakeTerminalSandbox()
+    cleanupFailed.handle.pid = 0
+    cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
+    cleanupFailed.removeError = new Error('remove transport failed')
+    await expect(spawnE2BTerminal(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
+      .rejects.toThrow('invalid terminal pid 0')
+  })
+
+  it('propagates setup cancellation and provider failures', async () => {
+    const aborted = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
+      .rejects.toThrow('stop')
+
+    const createFailed = new FakeTerminalSandbox()
+    createFailed.createError = new Error('create failed')
+    await expect(spawnE2BTerminal(runtime(createFailed), spec(), '/runtime/create'))
+      .rejects.toThrow('create failed')
+
+    const readFailed = new FakeTerminalSandbox()
+    readFailed.ready = new Error('ready transport failed')
+    await expect(spawnE2BTerminal(runtime(readFailed), spec(), '/runtime/read'))
+      .rejects.toThrow('ready transport failed')
+  })
+})
+
+describe('E2B terminal lifecycle', () => {
+  it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/natural')
+    terminal.output.resume()
+    const ended = once(terminal.output, 'end')
+    fake.handle.succeed(7)
+    await expect(terminal.done).resolves.toEqual({ exitCode: 7, signal: null })
+    await ended
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await expect(terminal.write(Buffer.from('late'))).rejects.toThrow('exited')
+    fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+  })
+
+  it.each([
+    [7, { exitCode: 7, signal: null }],
+    [143, { exitCode: null, signal: 'SIGTERM' }],
+    [255, { exitCode: 255, signal: null }],
+  ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
+    fake.handle.fail(exitCode)
+    await expect(terminal.done).resolves.toEqual(expected)
+    await expect(terminal.waitForExit(new AbortController().signal)).resolves.toBe(true)
+  })
+
+  it('lets an early quiescence observer follow a transport rejection', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/early-observer')
+    terminal.output.on('error', () => {})
+    const quiescence = terminal.waitForExit()
+    fake.handle.crash(new Error('transport failed'))
+    await expect(terminal.done).rejects.toThrow('transport failed')
+    await expect(quiescence).resolves.toBe(true)
+  })
+
+  it('rejects killing the terminal shell and propagates live foreground failures', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.foreground = '123\n'
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/signal')
+    await expect(terminal.signalForeground('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
+    fake.foreground = 'invalid\n'
+    await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
+    fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
+    fake.clearOnTerm = true
+    terminal.terminate()
+    await terminal.waitForExit()
+  })
+
+  it('escalates surviving process groups and bounds an observing wait', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = [123, 456]
+    fake.clearOnTerm = false
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/escalate')
+    const controller = new AbortController()
+    const observing = terminal.waitForExit(controller.signal)
+    controller.abort()
+    await expect(observing).resolves.toBe(false)
+
+    terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.commands).toContain('kill -TERM -- -123 -456')
+    expect(fake.commands).toContain('kill -KILL -- -123 -456')
+  })
+
+  it('surfaces cleanup failures and allows a later retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = [1]
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
+    terminal.terminate()
+    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('unsafe process group 1')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('propagates a process-group signalling transport failure before retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.termFailure = new Error('signal transport failed')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
+    terminal.terminate()
+    await expect(terminal.waitForExit()).rejects.toThrow('signal transport failed')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('keeps command rejection authoritative while cleanup is already waiting', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.removeError = new Error('private state already gone')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/reject-during-cleanup')
+    terminal.output.on('error', () => {})
+    terminal.terminate()
+    await Promise.resolve()
+    fake.handle.crash(new Error('command transport failed'))
+    await expect(terminal.done).rejects.toThrow('command transport failed')
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('keeps a late command rejection authoritative after PTY kill', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.settleOnPtyKill = false
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
+    terminal.output.on('error', () => {})
+    terminal.terminate()
+    while (fake.ptyKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
+    await Promise.resolve()
+    fake.handle.crash(new Error('late command transport failed'))
+    await expect(terminal.done).rejects.toThrow('late command transport failed')
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('reports surviving groups, a surviving top-level pid, and transport failure', async () => {
+    const survivor = new FakeTerminalSandbox()
+    survivor.clearOnTerm = false
+    survivor.clearOnKill = false
+    const terminal = await spawnE2BTerminal(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
+    terminal.terminate()
+    await expect(terminal.waitForExit()).rejects.toThrow('surviving process groups: 123')
+
+    const livePid = new FakeTerminalSandbox()
+    livePid.groups = []
+    livePid.settleOnPtyKill = false
+    const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
+    live.terminate()
+    await expect(live.waitForExit()).rejects.toThrow('surviving pid: 123')
+    livePid.handle.succeed(0)
+    await live.done
+
+    const crashed = new FakeTerminalSandbox()
+    crashed.groups = []
+    const failed = await spawnE2BTerminal(runtime(crashed), spec(), '/runtime/crashed')
+    const outputError = once(failed.output, 'error')
+    crashed.handle.crash('transport gone')
+    await expect(failed.done).rejects.toEqual('transport gone')
+    await expect(outputError).resolves.toMatchObject([{ message: 'transport gone' }])
+    await expect(failed.waitForExit()).resolves.toBe(true)
+  })
+})
+
+describe('E2B subprocess terminal service', () => {
+  async function service(fake = new FakeTerminalSandbox()): Promise<{
+    ctx: Context
+    fiber: Awaited<ReturnType<Context['plugin']>>
+    fake: FakeTerminalSandbox
+  }> {
+    const ctx = new Context()
+    ctx.provide('e2b', runtime(fake))
+    const fiber = await ctx.plugin(E2BSubprocessService)
+    return { ctx, fiber, fake }
+  }
+
+  it('publishes execution-world coordinates and resolves remote executables', async () => {
+    const { ctx } = await service()
+    expect(ctx.subprocess.cwd).toBe('/workspace')
+    expect(ctx.subprocess.runtimeRoot).toBe('/workspace/.dsh-e2b')
+    await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
+    await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
+      .resolves.toBe('/usr/bin/node')
+    expect((ctx.e2b)).toBeDefined()
+  })
+
+  it('rejects invalid executable lookup inputs and results', async () => {
+    const { ctx, fake } = await service()
+    await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
+    await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
+      .rejects.toThrow('stop')
+    fake.resolvedExecutable = 'relative/node\n'
+    await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
+    fake.resolvedExecutable = '/one\n/two\n'
+    await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
+  })
+
+  it('owns live terminals through service disposal', async () => {
+    const { ctx, fiber, fake } = await service()
+    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    await fiber.dispose()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('releases naturally settled terminals and validates terminal requests', async () => {
+    const { ctx, fiber, fake } = await service()
+    for (const request of [
+      spec({ argv: [] }),
+      spec({ rows: 0 }),
+      spec({ cols: 1.5 }),
+      spec({ graceMs: 0 }),
+      spec({ signal: AbortSignal.abort(new Error('cancelled')) }),
+    ]) {
+      await expect(ctx.subprocess.spawnTerminal(request)).rejects.toThrow()
+    }
+
+    fake.groups = []
+    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.waitForExit()
+    const signals = fake.commands.filter(command => command.startsWith('kill -')).length
+    await fiber.dispose()
+    expect(fake.commands.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
+  it('contains a failed automatic terminal release until service disposal retries it', async () => {
+    const { fiber, fake } = await service()
+    fake.clearOnTerm = false
+    fake.clearOnKill = false
+    const terminal = await (fiber.ctx).subprocess.spawnTerminal(spec({ graceMs: 1 }))
+    fake.handle.succeed(0)
+    await terminal.done
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(fake.commands).toContain('kill -KILL -- -123')
+
+    fake.groups = []
+    await fiber.dispose()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+})
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index 6b5a5d8b76..ae44721735 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 0b9a244d0c42542909460edf7109dfb9cee34503
-README.zh.md: 77da9b73f866fd88fcb81b28cbb622b0389bf5f0
+README.md: 96bbe6c95bd2aca7e66cf2d57abb3f056cd19390
+README.zh.md: 7f091b4f0955b847d21b8b3423dab421e610cda3
diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts
index 89053894ee..9399b5a1a7 100644
--- a/packages/lsp/lsp-local/tests/fixture-server.ts
+++ b/packages/lsp/lsp-local/tests/fixture-server.ts
@@ -15,7 +15,6 @@
  * - LSP_FAKE_REPLY_DELAY_MS: delays each textDocument/* response by this many milliseconds.
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
- * - LSP_FAKE_EXPECT_PROCESS_ID: expected JSON `initialize.processId`; mismatch exits nonzero.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
  * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
  * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
@@ -38,7 +37,6 @@ const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1'
 const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
 const openMarker = process.env.LSP_FAKE_OPEN_MARKER
 const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
-const expectedProcessId = process.env.LSP_FAKE_EXPECT_PROCESS_ID
 const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
 const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0)
 const exitMarker = process.env.LSP_FAKE_EXIT_MARKER
@@ -104,10 +102,6 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
     return
   }
   if (method === 'initialize') {
-    if (expectedProcessId !== undefined) {
-      const params = message.params as { processId?: unknown } | undefined
-      if (JSON.stringify(params?.processId) !== expectedProcessId) process.exit(2)
-    }
     if (garbage) process.stdout.write('this is not a framed message\r\n')
     send({
       id,
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index fc1d05843c..22877a94c8 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -111,11 +111,6 @@ const RESPONDING_SERVER =
 const locJson = () => JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
 
 describe('LspInstance server-request handling', () => {
-  it('advertises a null process id across process namespaces', async () => {
-    const instance = makeInstance({ LSP_FAKE_EXPECT_PROCESS_ID: 'null', LSP_FAKE_DEF: 'null' }, { clientProcessId: null })
-    await expect(run(instance, 'goToDefinition')).resolves.toMatchObject({ kind: 'locations' })
-  })
-
   it('answers workspace/configuration with the static config per item', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() })
     // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index b672a405de..e63252c7f8 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/README.i18n.yaml
@@ -1,6 +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/lsp/lsp/README.md
-README.md: bcffd460f192b0e6ac214ad0bc0d43da4c81d68c
-README.zh.md: e9df352e999834235a66ef7a500e300dadc2029c
+#   pnpm run verify-translation-pairing --write
+README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
+README.zh.md: 13ae9700e284ff238147538a571622066efc5747
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index 4dc0436bbb..5c1044be50 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -10,7 +10,6 @@ This package is the interface third of the LSP capability:
 |---|---|
 | `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
 | `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
-| `@deepseek-ai/dsh-lsp-e2b` | a generic E2B backend that registers configured remote stdio providers |
 | `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
 
 The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index fdaedc9a96..cc412333e6 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -10,7 +10,6 @@
 |---|---|
 | `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
-| `@deepseek-ai/dsh-lsp-e2b` | 通用 E2B 后端，注册已配置的远程 stdio 提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
 该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
diff --git a/packages/pty/pty/src/index.ts b/packages/pty/pty/src/index.ts
index 5cb375fbca..8ff4168e1a 100644
--- a/packages/pty/pty/src/index.ts
+++ b/packages/pty/pty/src/index.ts
@@ -41,15 +41,6 @@ export type {
   PtyWaitReason,
 } from './types.ts'
 export { PtyBackendCleanupError } from './types.ts'
-export {
-  normalizePtyTerminalText,
-  PTY_PROMPT_MARKER_PREFIX,
-  PtyTerminalSanitizer,
-  PtyTextBuffer,
-  ptySignalName,
-  ptyUtf8Tail,
-} from './terminal.ts'
-export type { PtySanitizedChunk } from './terminal.ts'
 
 /** Opaque identity minted by {@link PtyService} for one live PTY session. */
 export type PtySessionId = PtySessionIdValue
diff --git a/packages/pty/pty/src/terminal.ts b/packages/pty/pty/src/terminal.ts
deleted file mode 100644
index ed005dda41..0000000000
--- a/packages/pty/pty/src/terminal.ts
+++ /dev/null
@@ -1,273 +0,0 @@
-/** Backend-neutral line-oriented terminal buffering and control-sequence sanitization. */
-
-import { Buffer } from 'node:buffer'
-import { constants } from 'node:os'
-import type { PtySendRead } from './types.ts'
-
-/** OSC marker emitted by a controlled bash before each prompt. */
-export const PTY_PROMPT_MARKER_PREFIX = '133;D;'
-
-/** One sanitized chunk plus whether it contained the controlled prompt marker. */
-export interface PtySanitizedChunk {
-  /** Printable, line-normalized terminal text. */
-  text: string
-  /** Whether the chunk completed the controlled prompt marker. */
-  prompt: boolean
-  /** Present when printable text followed the latest controlled prompt marker. */
-  promptText?: true
-}
-
-/**
- * Return the largest code-point-aligned UTF-8 tail within a byte cap.
- * @param text - Candidate terminal text.
- * @param maxBytes - Maximum retained UTF-8 bytes.
- * @returns The retained tail and whether its head was dropped.
- */
-export function ptyUtf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
-  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
-  const chars = Array.from(text)
-  let bytes = 0
-  let start = chars.length
-  while (start > 0) {
-    const next = Buffer.byteLength(chars[start - 1] as string)
-    if (bytes + next > maxBytes) break
-    bytes += next
-    start -= 1
-  }
-  return { text: chars.slice(start).join(''), truncated: true }
-}
-
-/** UTF-8 and optionally line-bounded terminal text buffer. */
-export class PtyTextBuffer {
-  private value = ''
-  private dropped = false
-
-  /**
-   * @param maxBytes - Maximum retained UTF-8 bytes.
-   * @param maxLines - Optional maximum retained logical lines.
-   */
-  constructor(
-    private readonly maxBytes: number,
-    private readonly maxLines?: number,
-  ) {}
-
-  /**
-   * Append terminal text and drop the oldest excess.
-   * @param text - Decoded and sanitized terminal text.
-   */
-  append(text: string): void {
-    if (text.length === 0) return
-    this.value += text
-    if (this.maxLines !== undefined) {
-      const lines = this.value.split('\n')
-      if (lines.length > this.maxLines) {
-        this.value = lines.slice(lines.length - this.maxLines).join('\n')
-        this.dropped = true
-      }
-    }
-    const tail = ptyUtf8Tail(this.value, this.maxBytes)
-    this.value = tail.text
-    this.dropped ||= tail.truncated
-  }
-
-  /**
-   * Consume all currently retained operation text.
-   * @returns The delta and whether older text was dropped.
-   */
-  consume(): PtySendRead {
-    const delta = this.value
-    const truncated = this.dropped
-    this.value = ''
-    this.dropped = false
-    return { delta, truncated }
-  }
-
-  /**
-   * Return the retained text without consuming it.
-   * @returns The retained text and whether its head was dropped.
-   */
-  snapshot(): { text: string; truncated: boolean } {
-    return { text: this.value, truncated: this.dropped }
-  }
-}
-
-/**
- * Streaming terminal-control sanitizer for line-oriented PTY backends.
- * Full terminal emulation is deliberately outside the PTY seam.
- */
-export class PtyTerminalSanitizer {
-  private pending = ''
-  private discardMode: 'osc' | 'csi' | undefined
-  private discardOscEscape = false
-  private trailingCarriageReturn = false
-  private awaitingPromptText = false
-
-  /** @param maxPendingBytes - Bound for an incomplete terminal-control sequence. */
-  constructor(private readonly maxPendingBytes: number) {}
-
-  /**
-   * Consume one decoded PTY data chunk.
-   * @param chunk - Decoded terminal data.
-   * @returns Printable text and prompt-marker facts.
-   */
-  push(chunk: string): PtySanitizedChunk {
-    this.pending += this.discardPrefix(chunk)
-    let text = ''
-    let prompt = false
-    let promptText = false
-    let index = 0
-    const appendText = (value: string): boolean => {
-      text += value
-      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
-        this.awaitingPromptText = false
-        return true
-      }
-      return false
-    }
-    while (index < this.pending.length) {
-      const escape = this.pending.indexOf('\x1b', index)
-      if (escape < 0) {
-        promptText = appendText(this.pending.slice(index)) || promptText
-        index = this.pending.length
-        break
-      }
-      promptText = appendText(this.pending.slice(index, escape)) || promptText
-      if (escape + 1 >= this.pending.length) {
-        index = escape
-        break
-      }
-      const kind = this.pending[escape + 1]
-      if (kind === ']') {
-        const bel = this.pending.indexOf('\x07', escape + 2)
-        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
-        let end = -1
-        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
-        else if (bel >= 0) end = bel + 1
-        else if (stringTerminator >= 0) end = stringTerminator + 2
-        if (end < 0) {
-          index = escape
-          break
-        }
-        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
-        const content = this.pending.slice(escape + 2, end - terminatorBytes)
-        if (content.startsWith(PTY_PROMPT_MARKER_PREFIX)) {
-          prompt = true
-          promptText = false
-          this.awaitingPromptText = true
-        }
-        index = end
-        continue
-      }
-      if (kind === '[') {
-        let end = escape + 2
-        while (end < this.pending.length) {
-          const code = this.pending.charCodeAt(end)
-          if (code >= 0x40 && code <= 0x7e) break
-          end += 1
-        }
-        if (end >= this.pending.length) {
-          index = escape
-          break
-        }
-        index = end + 1
-        continue
-      }
-      index = escape + 2
-    }
-    this.pending = this.pending.slice(index)
-    this.enforcePendingBound()
-    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
-  }
-
-  /**
-   * Flush printable trailing data and discard incomplete controls.
-   * @returns Remaining normalized printable text.
-   */
-  flush(): string {
-    const text = this.pending.startsWith('\x1b') ? '' : this.pending
-    this.pending = ''
-    this.discardMode = undefined
-    this.discardOscEscape = false
-    this.awaitingPromptText = false
-    const normalized = this.normalizeText(text)
-    if (!this.trailingCarriageReturn) return normalized
-    this.trailingCarriageReturn = false
-    return `${normalized}\n`
-  }
-
-  private normalizeText(text: string): string {
-    let complete = this.trailingCarriageReturn ? `\r${text}` : text
-    this.trailingCarriageReturn = false
-    if (complete.endsWith('\r')) {
-      complete = complete.slice(0, -1)
-      this.trailingCarriageReturn = true
-    }
-    return normalizePtyTerminalText(complete)
-  }
-
-  private enforcePendingBound(): void {
-    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
-    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
-    this.pending = ''
-  }
-
-  private discardPrefix(chunk: string): string {
-    if (this.discardMode === undefined) return chunk
-    if (this.discardMode === 'csi') {
-      for (let index = 0; index < chunk.length; index += 1) {
-        const code = chunk.charCodeAt(index)
-        if (code >= 0x40 && code <= 0x7e) {
-          this.discardMode = undefined
-          return chunk.slice(index + 1)
-        }
-      }
-      return ''
-    }
-
-    let index = 0
-    if (this.discardOscEscape) {
-      this.discardOscEscape = false
-      if (chunk.startsWith('\\')) {
-        this.discardMode = undefined
-        return chunk.slice(1)
-      }
-    }
-    while (index < chunk.length) {
-      if (chunk[index] === '\x07') {
-        this.discardMode = undefined
-        return chunk.slice(index + 1)
-      }
-      if (chunk[index] === '\x1b') {
-        if (chunk[index + 1] === '\\') {
-          this.discardMode = undefined
-          return chunk.slice(index + 2)
-        }
-        if (index + 1 === chunk.length) this.discardOscEscape = true
-      }
-      index += 1
-    }
-    return ''
-  }
-}
-
-/**
- * Normalize CRLF and standalone carriage returns for line-oriented rendering.
- * @param text - Sanitized terminal text.
- * @returns Line-normalized text with BEL removed.
- */
-export function normalizePtyTerminalText(text: string): string {
-  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
-}
-
-/**
- * Convert a platform signal number into the seam's signal-name vocabulary.
- * @param number - Platform signal number, zero, or an absent signal.
- * @returns The matching Node signal name, or `null` when unknown or absent.
- */
-export function ptySignalName(number: number | undefined): NodeJS.Signals | null {
-  if (number === undefined || number === 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
-}
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 5ad70c0e68..6fda3901b6 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,7 +47,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
-  'packages/e2b/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
@@ -99,7 +98,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
-  'packages/e2b/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
   'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 526d4ef4b8..101c810c91 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -166,12 +166,10 @@
     { "path": "./packages/e2b/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
-    { "path": "./packages/e2b/pty-e2b" },
     { "path": "./packages/pty/pty-local" },
     { "path": "./packages/pty/tool-bash-persistent" },
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
-    { "path": "./packages/e2b/code-runtime-e2b" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -268,7 +266,6 @@
     { "path": "./packages/sdk/create-sdk" },
     { "path": "./packages/sdk/telemetry" },
     { "path": "./packages/lsp/lsp" },
-    { "path": "./packages/e2b/lsp-e2b" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
     { "path": "./apps/cli" }

From 2188cb908c5f9e71efd7ad1333f3f46b8d4b44ae Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:32:29 +0800
Subject: [PATCH 109/262] refactor(e2b): delegate terminal lifecycle

---
 docs/cordis-catalog/services.md               |  4 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   | 48 ++++-------------
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 53 ++++++++++++++++++-
 3 files changed, 63 insertions(+), 42 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 33f357d2bf..7ce45c6817 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:119`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
@@ -1180,7 +1180,7 @@ list(owner: Agent): PtySessionSnapshot[]
 
 Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md)
 
-Source: [`packages/pty/pty/src/index.ts:114`](../../packages/pty/pty/src/index.ts)
+Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
 
 ## `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 88bea44fde..1a916c0fd5 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -10,7 +10,7 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+import { SENSITIVE_ENV_PATTERN, SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -127,9 +127,8 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   readonly done: Promise<SubprocessOutcome>
 
   private topLevelExited = false
-  private termination: Promise<void> | undefined
+  private readonly lifecycle: SubprocessTerminalLifecycle
   private terminationSignal: NodeJS.Signals | null = null
-  private removeAbort: (() => void) | undefined
 
   constructor(
     private readonly sandbox: Sandbox,
@@ -143,13 +142,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   ) {
     this.pid = handle.pid
     this.done = this.waitForCommand()
-    void this.done.then(() => { this.terminate() }, () => { this.terminate() })
-    if (signal !== undefined) {
-      const onAbort = (): void => { this.terminate() }
-      signal.addEventListener('abort', onAbort, { once: true })
-      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
-      if (signal.aborted) this.terminate()
-    }
+    this.lifecycle = new SubprocessTerminalLifecycle({
+      done: this.done,
+      cleanup: () => this.closeOnce(),
+      signal,
+    })
   }
 
   /** @inheritdoc */
@@ -192,36 +189,12 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    this.termination ??= this.closeOnce().catch((error: unknown) => {
-      this.termination = undefined
-      throw error
-    })
-    void this.termination.catch(() => {})
+    this.lifecycle.terminate()
   }
 
   /** @inheritdoc */
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    const quiescence = this.termination ?? this.done.then(
-      () => { this.terminate(); return this.termination },
-      () => { this.terminate(); return this.termination },
-    )
-    if (signal === undefined) {
-      await quiescence
-      return true
-    }
-    if (signal.aborted) return false
-    return await new Promise<boolean>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(false) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      void quiescence.then(
-        () => { cleanup(); resolve(true) },
-        (error: unknown) => {
-          cleanup()
-          reject(error instanceof Error ? error : new Error(String(error)))
-        },
-      )
-    })
+    return await this.lifecycle.waitForExit(signal)
   }
 
   private async waitForCommand(): Promise<SubprocessOutcome> {
@@ -261,7 +234,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async signalGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
-    if (groups.length === 0) return
     try {
       await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
     } catch (error: unknown) {
@@ -301,8 +273,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (!this.topLevelExited) {
       throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
     }
-    this.removeAbort?.()
-    this.removeAbort = undefined
     await this.handle.disconnect()
     await this.sandbox.files.remove(this.stateDir).catch(() => {})
   }
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 9022e3d213..43cb88ea87 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -1,5 +1,6 @@
 import { Buffer } from 'node:buffer'
 import { once } from 'node:events'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import {
@@ -12,7 +13,7 @@ import {
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { spawnE2BTerminal } from '../src/terminal.ts'
+import { E2BTerminalHandle, spawnE2BTerminal } from '../src/terminal.ts'
 
 function commandError(exitCode: number): CommandExitError {
   return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
@@ -80,6 +81,7 @@ class FakeTerminalSandbox {
   createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
   ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   ready: string | Error = 'ready\n'
+  readyMisses = 0
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
@@ -106,6 +108,10 @@ class FakeTerminalSandbox {
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => {
+        if (this.readyMisses > 0) {
+          this.readyMisses -= 1
+          throw new FileNotFoundError('not ready')
+        }
         if (this.ready instanceof Error) throw this.ready
         return this.ready
       },
@@ -191,6 +197,7 @@ function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessT
 describe('E2B terminal allocation', () => {
   it('boots the requested argv through a private runner and preserves buffered bytes', async () => {
     const fake = new FakeTerminalSandbox()
+    fake.readyMisses = 1
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
     let output = ''
     terminal.output.on('data', (chunk) => { output += String(chunk) })
@@ -281,6 +288,9 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
       .rejects.toThrow('cannot resolve process session')
     expect(invalidSession.handle.sdkKills).toBe(1)
+    const lateData = invalidSession.createOptions?.onData
+    if (lateData === undefined) throw new Error('missing captured terminal callback')
+    expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
 
     const cleanupFailed = new FakeTerminalSandbox()
     cleanupFailed.handle.pid = 0
@@ -321,6 +331,26 @@ describe('E2B terminal lifecycle', () => {
     await expect(terminal.write(Buffer.from('late'))).rejects.toThrow('exited')
     fake.foregroundFailure = commandError(1)
     await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+    await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('cannot resolve foreground process group')
+  })
+
+  it('starts cleanup when the lifetime signal is already aborted at handle publication', async () => {
+    const fake = new FakeTerminalSandbox()
+    const controller = new AbortController()
+    controller.abort(new Error('publication cancelled'))
+    const terminal = new E2BTerminalHandle(
+      fake.sandbox,
+      fake.handle.asHandle(),
+      new PassThrough(),
+      fake.handle.wait(),
+      123,
+      '/runtime/pre-aborted',
+      1,
+      controller.signal,
+    )
+
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
   it.each([
@@ -404,6 +434,27 @@ describe('E2B terminal lifecycle', () => {
     await terminal.done
     terminal.terminate()
     await expect(terminal.waitForExit()).resolves.toBe(true)
+
+    const alreadyExited = new FakeTerminalSandbox()
+    alreadyExited.termFailure = commandError(1)
+    const tolerant = await spawnE2BTerminal(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
+    tolerant.terminate()
+    await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(tolerant.waitForExit()).resolves.toBe(true)
+  })
+
+  it('normalizes a non-Error cleanup rejection for an observing wait', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/non-error-cleanup')
+    fake.commandFailure = 'cleanup transport gone'
+    terminal.terminate()
+    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('cleanup transport gone')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
   it('keeps command rejection authoritative while cleanup is already waiting', async () => {

From 8877f5d58239806d28173410275e50f9ea477384 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:55:03 +0800
Subject: [PATCH 110/262] fix(e2b): normalize relative executable paths

---
 packages/e2b/e2b/tests/composition.e2e.ts       |  5 ++++-
 packages/e2b/subprocess-e2b/src/index.ts        |  6 +++---
 .../e2b/subprocess-e2b/tests/terminal.spec.ts   | 17 ++++++++++++++---
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 98fcdeae7f..e87627af8e 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -1,5 +1,5 @@
 import { access } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, posix } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -40,6 +40,9 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       } as never)
       const ptyFiber = await ctx.plugin(PtyService)
       const subprocessFiber = await ctx.plugin(E2BSubprocessService)
+      const node = await ctx.subprocess.resolveExecutable('node')
+      const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
+      await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 1547e1b46e..86ca5ceada 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -79,14 +79,14 @@ export class E2BSubprocessService extends SubprocessService {
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
       `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
-      signalOpts(signal),
+      { cwd: this.cwd, ...signalOpts(signal) },
     )
     signal?.throwIfAborted()
     const executable = result.stdout.trim()
-    if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+    if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
       throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
     }
-    return executable
+    return posix.resolve(this.cwd, executable)
   }
 
   /** @inheritdoc */
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 43cb88ea87..81716c3d52 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -19,6 +19,11 @@ function commandError(exitCode: number): CommandExitError {
   return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
 }
 
+interface CommandOptions {
+  signal?: AbortSignal
+  cwd?: string
+}
+
 class FakeTerminalCommandHandle {
   pid = 123
   disconnects = 0
@@ -74,6 +79,7 @@ class FakeTerminalCommandHandle {
 class FakeTerminalSandbox {
   readonly handle = new FakeTerminalCommandHandle()
   readonly commands: string[] = []
+  readonly commandOptions: CommandOptions[] = []
   readonly inputs: Array<{ pid: number; data: Buffer }> = []
   readonly removed: string[] = []
   readonly directories: string[] = []
@@ -121,8 +127,9 @@ class FakeTerminalSandbox {
       },
     },
     commands: {
-      run: async (command: string, options?: { signal?: AbortSignal }): Promise<CommandResult> => {
+      run: async (command: string, options?: CommandOptions): Promise<CommandResult> => {
         this.commands.push(command)
+        if (options !== undefined) this.commandOptions.push(options)
         options?.signal?.throwIfAborted()
         if (this.commandFailure !== undefined) {
           const error = this.commandFailure
@@ -525,12 +532,16 @@ describe('E2B subprocess terminal service', () => {
   }
 
   it('publishes execution-world coordinates and resolves remote executables', async () => {
-    const { ctx } = await service()
+    const { ctx, fake } = await service()
     expect(ctx.subprocess.cwd).toBe('/workspace')
     expect(ctx.subprocess.runtimeRoot).toBe('/workspace/.dsh-e2b')
     await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
     await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
       .resolves.toBe('/usr/bin/node')
+    fake.resolvedExecutable = 'tools/bin/node\n'
+    await expect(ctx.subprocess.resolveExecutable('node', { PATH: 'tools/bin' }))
+      .resolves.toBe('/workspace/tools/bin/node')
+    expect(fake.commandOptions.at(-1)).toMatchObject({ cwd: '/workspace' })
     expect((ctx.e2b)).toBeDefined()
   })
 
@@ -539,7 +550,7 @@ describe('E2B subprocess terminal service', () => {
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
     await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
       .rejects.toThrow('stop')
-    fake.resolvedExecutable = 'relative/node\n'
+    fake.resolvedExecutable = 'node\n'
     await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
     fake.resolvedExecutable = '/one\n/two\n'
     await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')

From fd78d9bc58cc324c38fe1ac8b882558da152edd9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:31:22 +0800
Subject: [PATCH 111/262] fix(e2b): harden remote process lifecycle

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   6 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   6 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  14 ++
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |  26 ++-
 packages/e2b/e2b/tests/composition.e2e.ts     |  17 ++
 packages/e2b/e2b/tests/e2b.spec.ts            |  27 +++
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   9 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   9 +-
 packages/e2b/subprocess-e2b/src/output.ts     |  68 +++++-
 packages/e2b/subprocess-e2b/src/process.ts    | 137 ++++++++----
 packages/e2b/subprocess-e2b/src/terminal.ts   | 201 +++++++++++++-----
 .../subprocess-e2b/tests/subprocess.spec.ts   | 136 ++++++++++--
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  67 +++++-
 18 files changed, 586 insertions(+), 153 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index fc187ec47b..b5e8e6e47c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: df0d6be97c502a9afe1a7aff3656a7567d302704
-2026-07-27-e2b-remote-runtime-poc.zh.md: 111d7aa63f8f7e51a82cfa0e42c489901f2b88e4
+2026-07-27-e2b-remote-runtime-poc.md: 029950cb2dae47bcf1ce819156135e58d46a4bb6
+2026-07-27-e2b-remote-runtime-poc.zh.md: 4029cc85d206e0dd0b7dbd91ec03674062df8531
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index df0d6be97c..029950cb2d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -28,7 +28,7 @@ E2B owns the mutable filesystem, managed command and Bash processes, terminal al
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses UTF-8 JSON over command pipes; E2B's decoded callback transport is not an arbitrary binary channel.
+The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. For ordinary command pipes, its remote wrapper branches raw spill bytes before framing each live chunk as newline-delimited base64 ASCII; the host restores raw bytes across arbitrary decoded SDK callback boundaries. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -38,7 +38,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, byte-split UTF-8 command output, bounded raw spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
@@ -62,4 +62,4 @@ A credential-gated Loader composition creates real E2B sandboxes and exercises F
 
 The three-package composition demonstrates that filesystem and subprocess are the sufficient provider seams for moving an agent's mutable coding world off-host without changing the loop, higher capability implementations, or model-facing tool packages. Fixes to Bash, PTY, LSP, and Code Runtime remain provider-neutral. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, command callbacks are text-decoded rather than arbitrary binary streams, exact terminal stdin-wait inspection is unavailable, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; Code Runtime uses validated ASCII/base64 framing; the exercised LSP path carries valid UTF-8 JSON. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains the complete base64 command transport in SDK memory, exact terminal stdin-wait inspection is unavailable, E2B supplies no independent signal fact, and reconnect cannot restore handles or protocol state. The adapter reports only its own requested TERM/KILL as signals and preserves every unrequested SDK exit as an exit code. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 111d7aa63f..4029cc85d2 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -28,7 +28,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用 UTF-8 JSON；E2B 的已解码回调传输并非任意二进制通道。
+基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。对于普通命令管道，其远程包装层会先分流原始 spill 字节，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意已解码 SDK 回调边界恢复原始字节。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -38,7 +38,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
@@ -62,4 +62,4 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 这个由 3 个包组成的组合证明，文件系统与进程管理这两个提供方 seam 足以把 agent 的可变 coding 环境移出宿主，而无需改变循环、上层功能实现或面向模型的工具包。Bash、PTY、LSP 与 Code Runtime 的修复仍与提供方无关。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，命令回调传递的是已解码文本而非任意二进制流，无法精确检查终端 stdin 等待状态，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；Code Runtime 使用经过验证的 ASCII/base64 分帧；已演练的 LSP 路径承载有效的 UTF-8 JSON。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整的 base64 命令传输，无法精确检查终端 stdin 等待状态，E2B 不提供独立的信号事实，重新连接也无法恢复句柄或协议状态。适配器只会把自己请求的 TERM/KILL 报告为信号，其他未请求的 SDK 退出都保留为退出码。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index aeb447b0e8..7c5fce5535 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -72,6 +72,19 @@ try {
   ].every(entry => environmentLines.has(entry))
   if (!explicitEnvironment) throw new Error(`E2B subprocess dropped an explicit environment entry: ${environmentText}`)
 
+  const splitUtf8Handle = ctx.subprocess.spawn({
+    argv: ['bash', '-c', "printf '\\344'; sleep 0.05; printf '\\275'; sleep 0.05; printf '\\240'; sleep 0.05; printf '\\345'; sleep 0.05; printf '\\245'; sleep 0.05; printf '\\275'"],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 32 }, stderr: { maxBytes: 4_096 } },
+    graceMs: 500,
+    env: {},
+  })
+  const splitUtf8Outcome = await splitUtf8Handle.done
+  const splitUtf8Output = splitUtf8Handle.collected.stdout?.readFrom(0).text
+  if (splitUtf8Outcome.exitCode !== 0 || splitUtf8Output !== '你好') {
+    throw new Error(`E2B subprocess corrupted split UTF-8 output: ${JSON.stringify({ splitUtf8Outcome, splitUtf8Output })}`)
+  }
+
   const remoteFiles = sandbox.files as unknown as {
     read(path: string, options?: unknown): Promise<unknown>
   }
@@ -370,6 +383,7 @@ try {
     bashRead: bashRead.stdout.text,
     fsRead,
     explicitEnvironment,
+    splitUtf8Output,
     publicationRollback,
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 8ffb6e981f..229a9e9343 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 00264b8f0b03e4af8512025322fe3e457e7b6b9b
-README.zh.md: 93fad661ded446e78e3addc0c8b2b8fdc39bd994
+README.md: 56606a22c36e65bcc53f2b8cce27f0739da1b8e2
+README.zh.md: 2e3213e431f15f1b22d2b8a429b27ab8a6a78671
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 00264b8f0b..56606a22c3 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -30,7 +30,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, then sets that directory to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
 `pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 93fad661de..2e3213e431 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -30,7 +30,7 @@
 
 构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 `pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 184c49f811..96da912033 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -7,7 +7,7 @@
 import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { Sandbox } from 'e2b'
+import { Sandbox, SandboxNotFoundError } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 export {
@@ -159,16 +159,22 @@ export class E2BSandboxService extends Service {
         // there is no remote resource for teardown to own.
         return
       }
-      switch (this.config.onDispose) {
-        case 'kill':
-          await sandbox.kill()
-          return
-        case 'pause': {
-          await sandbox.pause()
-          return
+      try {
+        switch (this.config.onDispose) {
+          case 'kill':
+            await sandbox.kill()
+            return
+          case 'pause': {
+            await sandbox.pause()
+            return
+          }
+          case 'leave':
+            return
         }
-        case 'leave':
-          return
+      } catch (error: unknown) {
+        // A kill-on-timeout sandbox is already quiescent; every other disposal
+        // failure still reports that the configured final disposition is unknown.
+        if (!(error instanceof SandboxNotFoundError)) throw error
       }
     }, 'e2b sandbox teardown')
   }
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index e87627af8e..4e7be57c45 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -43,6 +43,22 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       const node = await ctx.subprocess.resolveExecutable('node')
       const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
       await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
+      const environmentProbe = ctx.subprocess.spawn({
+        argv: ['/bin/bash', '-c', [
+          'dsh_leak=0',
+          'for dsh_pid in "$PPID" $(ps -o pid= --ppid "$PPID"); do',
+          '  [[ "$dsh_pid" == "$$" ]] && continue',
+          '  if tr "\\0" "\\n" < "/proc/$dsh_pid/environ" 2>/dev/null | grep -Fqx "NPM_TOKEN=sentinel-secret"; then dsh_leak=1; fi',
+          'done',
+          'printf "DIRECT=<%s> LEAK=<%s>\\n" "${NPM_TOKEN-}" "$dsh_leak"',
+        ].join('\n')],
+        cwd: '/home/user',
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 1_024 }, stderr: { maxBytes: 1_024 } },
+        graceMs: 500,
+        env: {},
+      })
+      await expect(environmentProbe.done).resolves.toEqual({ exitCode: 0, signal: null })
+      expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
@@ -106,6 +122,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
+      splitUtf8Output: '你好',
       publicationRollback: true,
       spill: {
         liveBytes: 6,
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index c0770f5917..bb96ca806a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   E2BSandboxId,
+  SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import * as E2BInvariant from '../src/invariant.ts'
@@ -140,6 +141,32 @@ describe('E2BSandboxService', () => {
     expect(fixture.pause).toHaveBeenCalledOnce()
   })
 
+  it('treats a timeout-killed sandbox as already quiescent during disposal', async () => {
+    const fixture = fakeSandbox()
+    fixture.pause.mockRejectedValue(new SandboxNotFoundError('sandbox expired'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      apiKey: 'test-key',
+      onTimeout: 'kill',
+      onDispose: 'pause',
+    })
+    await ctx.e2b.getSandbox()
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+  })
+
+  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+    const fixture = fakeSandbox()
+    fixture.kill.mockRejectedValue(new Error('disposition unknown'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await ctx.e2b.getSandbox()
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
   it('reconnects without applying creation lifecycle options and can leave state running', async () => {
     const fixture = fakeSandbox('existing')
     sdk.connect.mockResolvedValue(fixture.sandbox)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index dca7b016c2..33a36141d0 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: e0805345e708c67c6de721d95641e2366a7f990e
-README.zh.md: f83969c794e50f0658aa86218a0f5f3c89d53b56
+README.md: 58f13b264324d2168d4bc264b60100cdafa0a366
+README.zh.md: d547e4e8d66f629edcef753651180fe1806ad9bf
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index e0805345e7..58f13b2643 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -10,10 +10,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
-- **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
-The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
@@ -25,11 +25,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate even when this adapter exposes bounded tails, so the subprocess seam's normal host-memory bound is not achieved.
-- **Command-pipe output is text-decoded by the SDK** — valid UTF-8 protocol traffic, including the exercised LSP composition and Code Runtime's ASCII/base64 frames, is supported; arbitrary binary protocols and invalid UTF-8 are not byte-faithful.
+- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
-- **Signal attribution is inferred** — when termination was requested and E2B reports a nonzero exit code, the adapter reports the last requested signal because the SDK result does not identify the terminating signal.
+- **E2B exposes no signal fact** — only an adapter-requested `SIGTERM` or `SIGKILL` is reported as a signal; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
 - **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index f83969c794..d547e4e8d6 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -10,10 +10,10 @@
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
-- **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
-基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
@@ -25,11 +25,10 @@
 
 ## 已知限制与延后工作
 
-- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会持续累积，因此无法达到进程管理 seam 通常提供的宿主内存边界。
-- **命令管道输出由 SDK 解码为文本**：支持有效的 UTF-8 协议流量，包括已经过测试的 LSP 组合与 Code Runtime 的 ASCII/base64 帧；任意二进制协议和无效 UTF-8 不具备字节保真。
+- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
-- **信号归因依靠推断**：如果已经请求终止，而 E2B 报告非零退出码，适配器会报告最后请求的信号，因为 SDK 结果不标识终止信号。
+- **E2B 不公开信号事实**：只有适配器请求的 `SIGTERM` 或 `SIGKILL` 会报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
 - **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
index b6551983a0..6cb61e4f09 100644
--- a/packages/e2b/subprocess-e2b/src/output.ts
+++ b/packages/e2b/subprocess-e2b/src/output.ts
@@ -3,6 +3,64 @@
 import { Buffer } from 'node:buffer'
 import type { SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
 
+const BASE64_TEXT = /^[A-Za-z0-9+/]+={0,2}$/u
+
+/** Reserved non-base64 frame proving that one remote encoder reached clean EOF. */
+export const E2B_OUTPUT_COMPLETE_FRAME = '!dsh-e2b-output-complete!'
+
+/** Incrementally decode newline-delimited base64 frames emitted by one remote encoder. */
+export class E2BBase64Decoder {
+  private pending = ''
+  private complete = false
+
+  /**
+   * Decode every complete newline-delimited frame in one arbitrarily split SDK callback.
+   * @param text - ASCII base64 frames from E2B's decoded callback.
+   * @returns the complete raw bytes made available by this callback.
+   */
+  push(text: string): Buffer {
+    if (text.length === 0) return Buffer.alloc(0)
+    this.pending += text
+    const decoded: Buffer[] = []
+    for (;;) {
+      const boundary = this.pending.indexOf('\n')
+      if (boundary < 0) break
+      const frame = this.pending.slice(0, boundary)
+      this.pending = this.pending.slice(boundary + 1)
+      if (frame === E2B_OUTPUT_COMPLETE_FRAME) {
+        if (this.complete) throw new Error('subprocess-e2b: duplicate output transport completion')
+        this.complete = true
+        continue
+      }
+      if (this.complete) throw new Error('subprocess-e2b: output transport continued after completion')
+      if (!BASE64_TEXT.test(frame)) {
+        throw new Error('subprocess-e2b: invalid base64 output transport')
+      }
+      const bytes = Buffer.from(frame, 'base64')
+      if (bytes.toString('base64') !== frame) {
+        throw new Error('subprocess-e2b: invalid base64 output transport')
+      }
+      decoded.push(bytes)
+    }
+    return Buffer.concat(decoded)
+  }
+
+  /**
+   * Validate clean encoder completion, or discard an interrupted trailing frame after requested termination.
+   * @param requireComplete - Whether natural completion requires the reserved EOF frame.
+   */
+  finish(requireComplete = true): void {
+    if (!requireComplete) {
+      this.pending = ''
+      return
+    }
+    if (this.pending.length > 0) {
+      throw new Error('subprocess-e2b: truncated base64 output transport')
+    }
+    if (!this.complete) throw new Error('subprocess-e2b: incomplete output transport')
+  }
+}
+
 /** Offset reader used for one collect-mode E2B stream. */
 export class E2BOutputReader implements SubprocessOutputReader {
   private chunks: Buffer[] = []
@@ -27,12 +85,12 @@ export class E2BOutputReader implements SubprocessOutputReader {
   }
 
   /**
-   * Append one decoded SDK output event.
-   * @param text - Event text delivered by E2B.
+   * Append one byte-faithful decoded transport event.
+   * @param bytes - Raw command bytes recovered from the ASCII SDK transport.
    */
-  push(text: string): void {
-    if (text.length === 0) return
-    const chunk = Buffer.from(text)
+  push(bytes: Uint8Array): void {
+    if (bytes.length === 0) return
+    const chunk = Buffer.from(bytes)
     this.totalBytes += chunk.length
     this.chunks.push(chunk)
     this.retainedBytes += chunk.length
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 3b9594a752..9eeee5d877 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -8,6 +8,7 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessCollect,
   SubprocessHandle,
@@ -16,9 +17,21 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { E2BOutputReader } from './output.ts'
+import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
+const OUTPUT_ENCODER_SOURCE = [
+  '(async () => {',
+  '  for await (const chunk of process.stdin) {',
+  "    if (!process.stdout.write(chunk.toString('base64') + '\\n')) {",
+  "      await new Promise(resolve => process.stdout.once('drain', resolve))",
+  '    }',
+  '  }',
+  `  if (!process.stdout.write(${JSON.stringify(E2B_OUTPUT_COMPLETE_FRAME)} + '\\n')) {`,
+  "    await new Promise(resolve => process.stdout.once('drain', resolve))",
+  '  }',
+  '})().catch(() => { process.exitCode = 1 })',
+].join('\n')
 
 function isCollect(mode: SubprocessOutputMode): mode is SubprocessCollect {
   return mode !== 'pipe' && mode !== 'inherit'
@@ -60,40 +73,65 @@ interface RemotePaths {
   stderr: string
 }
 
-function explicitEnvironment(env: Readonly<Record<string, string>> | undefined): string {
-  return Object.entries(env ?? {})
-    .map(([name, value]) => `${name}=${value}\0`)
-    .join('')
+function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
+  const environment = new Map<string, string>()
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    const name = entry.slice(0, separator)
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, entry.slice(separator + 1))
+  }
+  for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
 
 function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
+  const encoder = `"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e ${quoteE2BShellArg(OUTPUT_ENCODER_SOURCE)}`
   const stdoutRedirect = hasSpill(spec.stdio.stdout)
-    ? `> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}))`
-    : ''
+    ? `> >("$dsh_e2b_tee" --output-error=warn-nopipe >("$dsh_e2b_head" -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}) | ${encoder} 2>/dev/null)`
+    : `> >(${encoder} 2>/dev/null)`
   const stderrRedirect = hasSpill(spec.stdio.stderr)
-    ? `2> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) >&2)`
-    : ''
+    ? `2> >("$dsh_e2b_tee" --output-error=warn-nopipe >("$dsh_e2b_head" -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) | ${encoder} >&2 2>/dev/null)`
+    : `2> >(${encoder} >&2 2>/dev/null)`
   const inner = [
     'set +e',
     'umask 077',
-    'dsh_e2b_pgid="$(ps -o pgid= -p "$$" | tr -d " ")"',
+    'dsh_e2b_env_bin=$1',
+    'dsh_e2b_node=$2',
+    'dsh_e2b_ps=$3',
+    'dsh_e2b_tr=$4',
+    'dsh_e2b_tee=$5',
+    'dsh_e2b_head=$6',
+    'shift 6',
+    'dsh_e2b_pgid="$("$dsh_e2b_ps" -o pgid= -p "$$" | "$dsh_e2b_tr" -d " ")"',
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
-    `mapfile -d '' -t dsh_e2b_explicit < ${quoteE2BShellArg(paths.environment)}`,
+    `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
     `: > ${quoteE2BShellArg(paths.environment)}`,
-    'dsh_e2b_env=()',
-    "while IFS= read -r -d '' dsh_e2b_entry; do",
-    '  dsh_e2b_name="${dsh_e2b_entry%%=*}"',
-    '  case "${dsh_e2b_name^^}" in DSH_*|*KEY*|*SECRET*|*TOKEN*) continue ;; esac',
-    '  dsh_e2b_env+=("$dsh_e2b_entry")',
-    'done < <(env -0)',
-    `env -i "\${dsh_e2b_env[@]}" "\${dsh_e2b_explicit[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    `"$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
     'wait',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
     'exit "$dsh_e2b_status"',
   ].join('\n')
   const argv = spec.argv.map(quoteE2BShellArg).join(' ')
-  return `exec setsid --wait -- bash -c ${quoteE2BShellArg(inner)} dsh-e2b ${argv}`
+  const bootstrap = [
+    `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
+    'dsh_e2b_env_bin="$(command -v env)"',
+    'dsh_e2b_setsid="$(command -v setsid)"',
+    'dsh_e2b_bash="$(command -v bash)"',
+    'dsh_e2b_node="$(command -v node)"',
+    'dsh_e2b_ps="$(command -v ps)"',
+    'dsh_e2b_tr="$(command -v tr)"',
+    'dsh_e2b_tee="$(command -v tee)"',
+    'dsh_e2b_head="$(command -v head)"',
+    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head"; do',
+    '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
+    'done',
+    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" ${argv}`,
+  ].join('\n')
+  return bootstrap
 }
 
 function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
@@ -128,10 +166,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   readonly done: Promise<SubprocessOutcome>
 
   private readonly readyState = Promise.withResolvers<CommandHandle>()
+  private readonly stdoutDecoder = new E2BBase64Decoder()
+  private readonly stderrDecoder = new E2BBase64Decoder()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
   private remotePid = -1
+  private commandHandle: CommandHandle | undefined
+  private outputTransportError: Error | undefined
   private terminationRequested = false
   private terminationSignal: NodeJS.Signals | null = null
   private termination: Promise<void> | undefined
@@ -195,7 +237,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     try {
       handle = await this.readyForWait(signal)
     } catch {
-      return true
+      handle = this.commandHandle
+      if (handle === undefined) return true
     }
     if (handle === undefined) return false
     let sandbox: Sandbox
@@ -205,7 +248,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (isAborted(signal)) return false
       throw error
     }
-    while (await this.groupAlive(sandbox, this.remotePid, signal)) {
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
+    while (await this.groupAlive(sandbox, processGroupId, signal)) {
       if (!await waitTick(signal)) return false
     }
     return !isAborted(signal)
@@ -248,6 +292,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
         throw new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
       }
+      this.commandHandle = handle
       const completion = handle.wait()
       void completion.catch(() => {})
       try {
@@ -266,6 +311,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       this.readyState.resolve(handle)
       await this.writeBatchStdin(handle)
       const outcome = await this.waitForCommand(completion)
+      if (this.outputTransportError !== undefined) throw this.outputTransportError
+      const requireCompleteOutput = this.terminationSignal === null
+      this.stdoutDecoder.finish(requireCompleteOutput)
+      this.stderrDecoder.finish(requireCompleteOutput)
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
@@ -279,12 +328,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
+    const ambient = await sandbox.commands.run('env -0')
     await sandbox.files.makeDir(this.stateDir)
     await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
-      { path: this.paths.environment, data: explicitEnvironment(this.spec.env) },
+      { path: this.paths.environment, data: remoteEnvironment(ambient.stdout, this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
@@ -303,25 +353,34 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async dispatchOutput(stream: 'stdout' | 'stderr', data: string): Promise<void> {
+    let bytes: Buffer
+    try {
+      bytes = stream === 'stdout' ? this.stdoutDecoder.push(data) : this.stderrDecoder.push(data)
+    } catch (error: unknown) {
+      this.outputTransportError ??= asError(error)
+      const target = stream === 'stdout' ? this.stdout : this.stderr
+      target?.destroy(this.outputTransportError)
+      return
+    }
     try {
       if (stream === 'stdout') {
-        this.stdoutReader?.push(data)
-        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, data)
+        this.stdoutReader?.push(bytes)
+        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, bytes)
         return
       }
-      this.stderrReader?.push(data)
-      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, data)
+      this.stderrReader?.push(bytes)
+      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, bytes)
     } catch (error: unknown) {
       const target = stream === 'stdout' ? this.stdout : this.stderr
       target?.destroy(asError(error))
     }
   }
 
-  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: string): Promise<void> {
+  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
     const target = pipe ?? inherited
     if (target === undefined || data.length === 0) return
     if (target.destroyed) throw new Error('subprocess output stream is closed')
-    if (target.write(Buffer.from(data))) return
+    if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
@@ -369,10 +428,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
-    // The background command begins with `exec setsid`, so E2B's command PID is
-    // the provisional group id even before the private publication file can be
-    // trusted. Kill that group before the SDK-PID fallback, then prove no group
-    // member survived before rejecting startup.
+    // The bootstrap ends in an exec chain through the scrubbed environment and
+    // `setsid`, so E2B's command PID is the provisional group id even before the
+    // private publication file can be trusted. Kill that group before the SDK-PID
+    // fallback, then prove no group member survived before rejecting startup.
     try {
       await this.signalGroup(sandbox, handle.pid, 'KILL')
     } finally {
@@ -382,23 +441,25 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async terminateRemote(): Promise<void> {
-    let handle: CommandHandle
+    let handle: CommandHandle | undefined
     try {
       handle = await this.readyState.promise
     } catch {
-      return
+      handle = this.commandHandle
     }
+    if (handle === undefined) return
     const sandbox = await this.runtime.getSandbox()
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
     this.terminationSignal = 'SIGTERM'
-    await this.signalGroup(sandbox, this.remotePid, 'TERM')
+    await this.signalGroup(sandbox, processGroupId, 'TERM')
     const deadline = Date.now() + this.spec.graceMs
-    while (Date.now() < deadline && await this.groupAlive(sandbox, this.remotePid)) {
+    while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
       await waitTick()
     }
-    if (!await this.groupAlive(sandbox, this.remotePid)) return
+    if (!await this.groupAlive(sandbox, processGroupId)) return
     this.terminationSignal = 'SIGKILL'
     try {
-      await this.signalGroup(sandbox, this.remotePid, 'KILL')
+      await this.signalGroup(sandbox, processGroupId, 'KILL')
     } finally {
       await handle.kill().catch(() => false)
     }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 1a916c0fd5..565e406b97 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -1,7 +1,6 @@
 /** E2B PTY allocation and process-session ownership for the subprocess seam. */
 
 import { Buffer } from 'node:buffer'
-import { constants } from 'node:os'
 import { PassThrough } from 'node:stream'
 import { posix } from 'node:path'
 import {
@@ -53,13 +52,8 @@ function delay(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
 
-function commandSignal(exitCode: number): NodeJS.Signals | null {
-  const number = exitCode - 128
-  if (number <= 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
 }
 
 function parsePositiveId(value: string, message: string): number {
@@ -121,6 +115,132 @@ async function waitUntilReady(
   }
 }
 
+async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
+  const result = await sandbox.commands.run(
+    `ps -eo sid=,pgid= | awk '$1 == ${sessionId} { print $2 }'`,
+  )
+  const groups = new Set<number>()
+  for (const raw of result.stdout.trim().split(/\s+/)) {
+    if (raw.length === 0) continue
+    const group = parsePositiveId(
+      raw,
+      `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${sessionId}`,
+    )
+    if (group <= 1) {
+      throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${sessionId}`)
+    }
+    groups.add(group)
+  }
+  return [...groups]
+}
+
+async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+  try {
+    await sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
+  } catch (error: unknown) {
+    if (!(error instanceof CommandExitError)) throw error
+  }
+}
+
+async function awaitSessionEmpty(
+  sandbox: Sandbox,
+  sessionId: number,
+  graceMs: number,
+  kill = false,
+): Promise<number[]> {
+  const deadline = Date.now() + graceMs
+  for (;;) {
+    const groups = await sessionProcessGroups(sandbox, sessionId)
+    if (groups.length === 0 || Date.now() >= deadline) return groups
+    if (kill) await signalGroups(sandbox, groups, 'KILL')
+    await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
+  }
+}
+
+async function rollbackUnpublishedTerminal(
+  sandbox: Sandbox,
+  handle: CommandHandle,
+  completion: Promise<CommandResult>,
+  graceMs: number,
+): Promise<void> {
+  let topLevelExited = false
+  void completion.then(
+    () => { topLevelExited = true },
+    () => { topLevelExited = true },
+  )
+  const validPid = Number.isSafeInteger(handle.pid) && handle.pid > 1
+  const attemptFailures: Error[] = []
+  let sessionId: number | undefined
+  if (validPid) {
+    sessionId = handle.pid
+    try {
+      sessionId = await terminalSessionId(sandbox, handle.pid)
+    } catch (_sessionLookupFailure) {
+      // E2B's PTY leader is also the provisional POSIX session leader, so its
+      // PID remains usable after the setup lookup itself fails or is canceled.
+    }
+    try {
+      let groups = await sessionProcessGroups(sandbox, sessionId)
+      if (groups.length > 0) {
+        await signalGroups(sandbox, groups, 'TERM')
+        groups = await awaitSessionEmpty(sandbox, sessionId, graceMs)
+      }
+      if (groups.length > 0) {
+        await signalGroups(sandbox, groups, 'KILL')
+        await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+      }
+    } catch (error: unknown) {
+      attemptFailures.push(asError(error))
+    }
+  }
+  // Completion can settle while any awaited provider cleanup above is running.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!topLevelExited) {
+    if (validPid) {
+      try {
+        await sandbox.pty.kill(handle.pid)
+      } catch (error: unknown) {
+        attemptFailures.push(asError(error))
+      }
+    }
+    // The awaited PTY fallback can settle completion before the SDK fallback.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!topLevelExited) {
+      try {
+        await handle.kill()
+      } catch (error: unknown) {
+        attemptFailures.push(asError(error))
+      }
+    }
+    await Promise.race([completion.catch(() => undefined), delay(graceMs)])
+  }
+  const proofFailures: Error[] = []
+  if (sessionId !== undefined) {
+    try {
+      const groups = await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+      if (groups.length > 0) {
+        proofFailures.push(new Error(
+          `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
+        ))
+      }
+    } catch (error: unknown) {
+      proofFailures.push(asError(error))
+    }
+  }
+  // The bounded completion race above updates this callback-owned state.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!topLevelExited) {
+    proofFailures.push(new Error(`subprocess-e2b: terminal setup rollback failed; surviving pid: ${handle.pid}`))
+  }
+  if (proofFailures.length > 0) {
+    throw new AggregateError(
+      [...attemptFailures, ...proofFailures],
+      'subprocess-e2b: terminal setup rollback did not reach quiescence',
+    )
+  }
+  await handle.disconnect()
+}
+
 /** One E2B PTY and all process groups in its remote process session. */
 export class E2BTerminalHandle implements SubprocessTerminalHandle {
   readonly pid: number
@@ -203,8 +323,9 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
       return { exitCode: result.exitCode, signal: null }
     } catch (error: unknown) {
       if (error instanceof CommandExitError) {
-        const signal = this.terminationSignal ?? commandSignal(error.exitCode)
-        return signal === null ? { exitCode: error.exitCode, signal: null } : { exitCode: null, signal }
+        return this.terminationSignal === null
+          ? { exitCode: error.exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
       }
       this.output.destroy(error instanceof Error ? error : new Error(String(error)))
       throw error
@@ -214,49 +335,12 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     }
   }
 
-  private async sessionProcessGroups(): Promise<number[]> {
-    const result = await this.sandbox.commands.run(
-      `ps -eo sid=,pgid= | awk '$1 == ${this.sessionId} { print $2 }'`,
-    )
-    const groups = new Set<number>()
-    for (const raw of result.stdout.trim().split(/\s+/)) {
-      if (raw.length === 0) continue
-      const group = parsePositiveId(
-        raw,
-        `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.sessionId}`,
-      )
-      if (group <= 1) {
-        throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${this.sessionId}`)
-      }
-      groups.add(group)
-    }
-    return [...groups]
-  }
-
-  private async signalGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
-    try {
-      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
-    } catch (error: unknown) {
-      if (!(error instanceof CommandExitError)) throw error
-    }
-  }
-
-  private async awaitSessionEmpty(kill = false): Promise<number[]> {
-    const deadline = Date.now() + this.graceMs
-    for (;;) {
-      const groups = await this.sessionProcessGroups()
-      if (groups.length === 0 || Date.now() >= deadline) return groups
-      if (kill) await this.signalGroups(groups, 'KILL')
-      await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
-    }
-  }
-
   private async closeOnce(): Promise<void> {
-    let groups = await this.sessionProcessGroups()
+    let groups = await sessionProcessGroups(this.sandbox, this.sessionId)
     if (groups.length > 0) {
       this.terminationSignal = 'SIGTERM'
-      await this.signalGroups(groups, 'TERM')
-      groups = await this.awaitSessionEmpty()
+      await signalGroups(this.sandbox, groups, 'TERM')
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs)
     }
     if (groups.length === 0 && !this.topLevelExited) {
       await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
@@ -264,7 +348,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (groups.length > 0 || !this.topLevelExited) {
       this.terminationSignal = 'SIGKILL'
       if (!this.topLevelExited) await this.sandbox.pty.kill(this.pid)
-      groups = await this.awaitSessionEmpty(true)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
     if (groups.length > 0) {
@@ -348,9 +432,20 @@ export async function spawnE2BTerminal(
     )
   } catch (error: unknown) {
     output.destroy()
-    if (handle !== undefined) await handle.kill().catch(() => false)
-    if (completion !== undefined) await completion.catch(() => {})
+    let cleanupError: Error | undefined
+    if (handle !== undefined && completion !== undefined) {
+      try {
+        await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
+      } catch (rollbackError: unknown) {
+        cleanupError = asError(rollbackError)
+      }
+    } else if (handle !== undefined) {
+      await handle.kill().catch(() => false)
+    }
     await sandbox.files.remove(stateDir).catch(() => {})
+    if (cleanupError !== undefined) {
+      throw new AggregateError([asError(error), cleanupError], asError(error).message)
+    }
     throw error
   }
 }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index fd4cc97a83..32adf872b3 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -10,7 +10,7 @@ import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 import * as E2BSubprocessInvariant from '../src/invariant.ts'
-import { E2BOutputReader } from '../src/output.ts'
+import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from '../src/output.ts'
 import { E2BSubprocessHandle } from '../src/process.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import { describe, expect, it, vi } from 'vitest'
@@ -91,6 +91,7 @@ class FakeSandbox {
   trapsTerm = false
   delaysKill = false
   alive = true
+  ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   processGroupId = '4242\n'
   readonly processGroupReads: string[] = []
   beforeProbe: (() => void) | undefined
@@ -110,15 +111,35 @@ class FakeSandbox {
 
   finish(exitCode = 0): void {
     this.alive = false
-    if (exitCode === 0) this.handle.succeed(0)
-    else this.handle.fail(exitCode)
+    void this.completeOutput().then(
+      () => {
+        if (exitCode === 0) this.handle.succeed(0)
+        else this.handle.fail(exitCode)
+      },
+      (error: unknown) => { this.handle.crash(error) },
+    )
+  }
+
+  async completeOutput(): Promise<void> {
+    await Promise.all([
+      this.stdoutWire(`${E2B_OUTPUT_COMPLETE_FRAME}\n`),
+      this.stderrWire(`${E2B_OUTPUT_COMPLETE_FRAME}\n`),
+    ])
   }
 
   async stdout(data: string): Promise<void> {
-    await this.startOptions?.onStdout?.(data)
+    await this.stdoutWire(data.length === 0 ? '' : `${Buffer.from(data).toString('base64')}\n`)
   }
 
   async stderr(data: string): Promise<void> {
+    await this.stderrWire(data.length === 0 ? '' : `${Buffer.from(data).toString('base64')}\n`)
+  }
+
+  async stdoutWire(data: string): Promise<void> {
+    await this.startOptions?.onStdout?.(data)
+  }
+
+  async stderrWire(data: string): Promise<void> {
     await this.startOptions?.onStderr?.(data)
   }
 
@@ -147,6 +168,7 @@ class FakeSandbox {
     commands: {
       run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
         this.commandsSeen.push(command)
+        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
         if (command.startsWith('kill -0 ')) {
           this.beforeProbe?.()
           if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
@@ -221,11 +243,35 @@ async function flush(): Promise<void> {
 }
 
 describe('E2BOutputReader', () => {
+  it('decodes base64 across arbitrary callback boundaries and rejects malformed framing', () => {
+    const decoder = new E2BBase64Decoder()
+    expect(decoder.push('')).toEqual(Buffer.alloc(0))
+    expect(decoder.push('5')).toEqual(Buffer.alloc(0))
+    expect(decoder.push('L2')).toEqual(Buffer.alloc(0))
+    expect(decoder.push('g\n').toString()).toBe('你')
+    expect(decoder.push('YQ==\nYg==\n').toString()).toBe('ab')
+    expect(decoder.push(`${Buffer.from([0, 255]).toString('base64')}\n`)).toEqual(Buffer.from([0, 255]))
+    expect(decoder.push(`${E2B_OUTPUT_COMPLETE_FRAME}\n`)).toEqual(Buffer.alloc(0))
+    decoder.finish()
+
+    expect(() => new E2BBase64Decoder().push('%\n')).toThrow('invalid base64')
+    expect(() => new E2BBase64Decoder().push('AB==\n')).toThrow('invalid base64')
+    expect(() => decoder.push(`${E2B_OUTPUT_COMPLETE_FRAME}\n`)).toThrow('duplicate output transport completion')
+    expect(() => decoder.push('YQ==\n')).toThrow('continued after completion')
+    const truncated = new E2BBase64Decoder()
+    truncated.push('YQ')
+    expect(() => { truncated.finish() }).toThrow('truncated base64')
+    expect(() => { new E2BBase64Decoder().finish() }).toThrow('incomplete output transport')
+    const interrupted = new E2BBase64Decoder()
+    interrupted.push('YQ')
+    expect(() => { interrupted.finish(false) }).not.toThrow()
+  })
+
   it('keeps a byte-exact tail with independent whole-stream cursors', () => {
     const reader = new E2BOutputReader(4, 10, '/remote/spill')
-    reader.push('')
-    reader.push('ab')
-    reader.push('cdef')
+    reader.push(Buffer.alloc(0))
+    reader.push(Buffer.from('ab'))
+    reader.push(Buffer.from('cdef'))
     expect(reader.size).toBe(6)
     expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true, spillPath: '/remote/spill' })
     expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
@@ -235,11 +281,11 @@ describe('E2BOutputReader', () => {
 
   it('drops whole head chunks and withholds absent or over-cap spills', () => {
     const withoutSpill = new E2BOutputReader(2, undefined, '/unused')
-    withoutSpill.push('ab')
-    withoutSpill.push('cd')
+    withoutSpill.push(Buffer.from('ab'))
+    withoutSpill.push(Buffer.from('cd'))
     expect(withoutSpill.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     const overCap = new E2BOutputReader(2, 3, '/too-small')
-    overCap.push('abcd')
+    overCap.push(Buffer.from('abcd'))
     expect(overCap.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     expect(() => overCap.readFrom(-1)).toThrow(/non-negative safe integer/)
     expect(() => overCap.readFrom(1.5)).toThrow(/non-negative safe integer/)
@@ -265,16 +311,22 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
     expect(fake.handle.closes).toBe(1)
     expect(fake.startOptions?.envs).toBeUndefined()
-    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
-    expect(command).toContain('exec setsid --wait -- bash -c')
+    const command = fake.commandsSeen.find(value => value.includes('exec "$dsh_e2b_env_bin" -i'))!
+    expect(command).toContain('"$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c')
     expect(command).not.toContain('DEEPSEEK_API_KEY')
     expect(command).not.toContain('DSH_MODE')
     expect(command).not.toContain('FOO-BAR')
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(command).toContain('env -0')
+    expect(fake.commandsSeen).toContain('env -0')
     expect(command).toContain('mapfile -d')
+    expect(command).toContain('dsh_e2b_node="$(command -v node)"')
+    expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
+    expect(command).toContain('exec "$dsh_e2b_env_bin" -i "${dsh_e2b_env[@]}"')
+    expect(command).toContain('>&2 2>/dev/null')
+    expect(command).not.toContain('2>/dev/null >&2')
+    expect(command).toContain('base64')
     expect(fake.writtenFiles[0]).toEqual([
       '/workspace/.dsh-e2b/processes/one/pid',
       '/workspace/.dsh-e2b/processes/one/exit-code',
@@ -282,7 +334,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -297,6 +349,47 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('preserves UTF-8 bytes when the ASCII transport is split across callbacks', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/split-utf8')
+    await flush()
+    const chunks: Buffer[] = []
+    handle.stdout!.on('data', (chunk: Buffer) => { chunks.push(chunk) })
+    for (const character of `${Buffer.from('A你好B').toString('base64')}\n`) {
+      await fake.stdoutWire(character)
+    }
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(Buffer.concat(chunks).toString('utf8')).toBe('A你好B')
+  })
+
+  it('rejects malformed output transport without confusing it with a consumer sink failure', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/malformed-output')
+    await flush()
+    await fake.stdoutWire('%\n')
+    fake.finish()
+    await expect(handle.done).rejects.toThrow('invalid base64 output transport')
+
+    const stderrFake = new FakeSandbox()
+    const stderrHandle = new E2BSubprocessHandle(runtime(stderrFake), spec(), '/runtime/malformed-stderr')
+    await flush()
+    await stderrFake.stderrWire('%\n')
+    stderrFake.finish()
+    await expect(stderrHandle.done).rejects.toThrow('invalid base64 output transport')
+  })
+
+  it('rejects a naturally completed command whose encoder omits its completion frame', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/incomplete-output')
+    await flush()
+    fake.alive = false
+    fake.handle.succeed(0)
+    await expect(handle.done).rejects.toThrow('incomplete output transport')
+  })
+
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
@@ -362,10 +455,10 @@ describe('E2BSubprocessHandle', () => {
     await handle.done
     expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     expect(fake.removed).toContain('/runtime/oversize/stdout.log')
-    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
-    expect(command).toContain('head -c 3')
+    const command = fake.commandsSeen.find(value => value.includes('dsh_e2b_tee='))!
+    expect(command).toContain('"$dsh_e2b_head" -c 3')
     expect(command).toContain('/runtime/oversize/stdout.log')
-    expect(command).toContain('tee --output-error=warn-nopipe')
+    expect(command).toContain('"$dsh_e2b_tee" --output-error=warn-nopipe')
     expect(command).not.toContain('tee -a')
   })
 
@@ -436,6 +529,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/surviving-group')
     await flush()
+    await fake.completeOutput()
     fake.handle.succeed(0)
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(fake.alive).toBe(true)
@@ -640,7 +734,13 @@ describe('E2BSubprocessHandle', () => {
     expect(failures[0].message).toContain('invalid process-group id')
     expect(failures[1].message).toBe('rollback signal failed')
     expect(fake.handle.kills).toBe(1)
-    fake.finish()
+    const bounded = new AbortController()
+    const waiting = handle.waitForExit(bounded.signal)
+    bounded.abort()
+    await expect(waiting).resolves.toBe(false)
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
   })
 
   it('waits for delayed process-group publication', async () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 81716c3d52..cefa432acd 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -30,10 +30,13 @@ class FakeTerminalCommandHandle {
   sdkKills = 0
   disconnectError: unknown
   sdkKillError: unknown
+  waitError: unknown
+  settleOnSdkKill = true
   private readonly result = Promise.withResolvers<CommandResult>()
   private settled = false
 
   wait(): Promise<CommandResult> {
+    if (this.waitError !== undefined) throw this.waitError
     return this.result.promise
   }
 
@@ -46,10 +49,10 @@ class FakeTerminalCommandHandle {
     this.sdkKills += 1
     if (this.sdkKillError !== undefined) {
       const error = this.sdkKillError
-      this.fail(137)
+      if (this.settleOnSdkKill) this.fail(137)
       throw error
     }
-    this.fail(137)
+    if (this.settleOnSdkKill) this.fail(137)
     return true
   }
 
@@ -94,8 +97,10 @@ class FakeTerminalSandbox {
   createError: unknown
   sendError: unknown
   commandFailure: unknown
+  sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
+  ptyKillError: unknown
   removeError: unknown
   clearOnTerm = true
   clearOnKill = true
@@ -146,6 +151,7 @@ class FakeTerminalSandbox {
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
         }
         if (command.startsWith('ps -eo sid=')) {
+          if (this.sessionGroupsFailure !== undefined) throw this.sessionGroupsFailure
           return { exitCode: 0, stdout: this.groups.map(group => `${group}\n`).join(''), stderr: '' }
         }
         if (command.startsWith('kill -TERM -- ')) {
@@ -173,6 +179,7 @@ class FakeTerminalSandbox {
       },
       kill: async (pid: number): Promise<boolean> => {
         this.ptyKills += 1
+        if (this.ptyKillError !== undefined) throw this.ptyKillError
         if (this.settleOnPtyKill) this.handle.fail(137)
         return pid === this.handle.pid
       },
@@ -282,7 +289,8 @@ describe('E2B terminal allocation', () => {
     failedInput.sendError = new Error('bootstrap failed')
     await expect(spawnE2BTerminal(runtime(failedInput), spec(), '/runtime/input'))
       .rejects.toThrow('bootstrap failed')
-    expect(failedInput.handle.sdkKills).toBe(1)
+    expect(failedInput.commands).toContain('kill -TERM -- -123')
+    expect(failedInput.groups).toEqual([])
 
     const exited = new FakeTerminalSandbox()
     exited.ready = new FileNotFoundError('not ready')
@@ -292,13 +300,62 @@ describe('E2B terminal allocation', () => {
 
     const invalidSession = new FakeTerminalSandbox()
     invalidSession.sessionId = 'not-a-session\n'
+    invalidSession.clearOnTerm = false
     await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
       .rejects.toThrow('cannot resolve process session')
-    expect(invalidSession.handle.sdkKills).toBe(1)
+    expect(invalidSession.commands).toContain('kill -TERM -- -123')
+    expect(invalidSession.commands).toContain('kill -KILL -- -123')
+    expect(invalidSession.groups).toEqual([])
+    expect(invalidSession.ptyKills).toBe(1)
     const lateData = invalidSession.createOptions?.onData
     if (lateData === undefined) throw new Error('missing captured terminal callback')
     expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
 
+    const termFailed = new FakeTerminalSandbox()
+    termFailed.sendError = new Error('bootstrap failed')
+    termFailed.termFailure = new Error('TERM transport failed')
+    await expect(spawnE2BTerminal(runtime(termFailed), spec(), '/runtime/term-failed'))
+      .rejects.toThrow('bootstrap failed')
+    expect(termFailed.commands).toContain('kill -KILL -- -123')
+    expect(termFailed.ptyKills).toBe(1)
+
+    const uninspectable = new FakeTerminalSandbox()
+    uninspectable.sendError = new Error('bootstrap failed')
+    uninspectable.sessionGroupsFailure = 'session enumeration failed'
+    uninspectable.ptyKillError = new Error('PTY kill failed')
+    let uninspectableFailure: unknown
+    try {
+      await spawnE2BTerminal(runtime(uninspectable), spec(), '/runtime/uninspectable')
+    } catch (error: unknown) {
+      uninspectableFailure = error
+    }
+    expect(uninspectableFailure).toBeInstanceOf(AggregateError)
+    expect(uninspectable.ptyKills).toBe(1)
+    expect(uninspectable.handle.sdkKills).toBe(1)
+
+    const survivingGroups = new FakeTerminalSandbox()
+    survivingGroups.sendError = new Error('bootstrap failed')
+    survivingGroups.clearOnTerm = false
+    survivingGroups.clearOnKill = false
+    await expect(spawnE2BTerminal(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
+      .rejects.toThrow('bootstrap failed')
+
+    const survivingPid = new FakeTerminalSandbox()
+    survivingPid.sendError = new Error('bootstrap failed')
+    survivingPid.groups = []
+    survivingPid.settleOnPtyKill = false
+    survivingPid.handle.settleOnSdkKill = false
+    await expect(spawnE2BTerminal(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
+      .rejects.toThrow('bootstrap failed')
+
+    const waitFailed = new FakeTerminalSandbox()
+    waitFailed.handle.waitError = new Error('wait failed')
+    waitFailed.handle.settleOnSdkKill = false
+    waitFailed.handle.sdkKillError = new Error('kill failed')
+    await expect(spawnE2BTerminal(runtime(waitFailed), spec(), '/runtime/wait-failed'))
+      .rejects.toThrow('wait failed')
+    expect(waitFailed.handle.sdkKills).toBe(1)
+
     const cleanupFailed = new FakeTerminalSandbox()
     cleanupFailed.handle.pid = 0
     cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
@@ -362,7 +419,7 @@ describe('E2B terminal lifecycle', () => {
 
   it.each([
     [7, { exitCode: 7, signal: null }],
-    [143, { exitCode: null, signal: 'SIGTERM' }],
+    [143, { exitCode: 143, signal: null }],
     [255, { exitCode: 255, signal: null }],
   ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
     const fake = new FakeTerminalSandbox()

From 62df6d0c0977a71c689e91abb4b27c6f4c9a3262 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:45:55 +0800
Subject: [PATCH 112/262] refactor(e2b): share environment scrubbing

---
 .../e2b/subprocess-e2b/src/environment.ts     | 21 +++++++++++++++++++
 packages/e2b/subprocess-e2b/src/process.ts    | 12 ++---------
 packages/e2b/subprocess-e2b/src/terminal.ts   | 13 +++---------
 3 files changed, 26 insertions(+), 20 deletions(-)
 create mode 100644 packages/e2b/subprocess-e2b/src/environment.ts

diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
new file mode 100644
index 0000000000..cc9b41296a
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -0,0 +1,21 @@
+/** Shared remote-environment scrubbing for E2B process and terminal launchers. */
+
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+
+/**
+ * Parse an E2B NUL-delimited environment while removing harness-private and credential-shaped names.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Mutable retained entries for the caller to overlay and serialize.
+ */
+export function scrubRemoteEnvironment(raw: string): Map<string, string> {
+  const environment = new Map<string, string>()
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    const name = entry.slice(0, separator)
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, entry.slice(separator + 1))
+  }
+  return environment
+}
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 9eeee5d877..5f8a107cf6 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -8,7 +8,6 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessCollect,
   SubprocessHandle,
@@ -17,6 +16,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { scrubRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -74,15 +74,7 @@ interface RemotePaths {
 }
 
 function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = new Map<string, string>()
-  for (const entry of raw.split('\0')) {
-    if (entry.length === 0) continue
-    const separator = entry.indexOf('=')
-    if (separator <= 0) continue
-    const name = entry.slice(0, separator)
-    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
-    environment.set(name, entry.slice(separator + 1))
-  }
+  const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
   return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 565e406b97..7185899f79 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -9,7 +9,7 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SENSITIVE_ENV_PATTERN, SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
+import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -18,6 +18,7 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { scrubRemoteEnvironment } from './environment.ts'
 
 const POLL_MS = 20
 
@@ -71,15 +72,7 @@ function serializeValues(values: readonly string[], kind: string): string {
 }
 
 function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = new Map<string, string>()
-  for (const entry of raw.split('\0')) {
-    if (entry.length === 0) continue
-    const separator = entry.indexOf('=')
-    if (separator <= 0) continue
-    const name = entry.slice(0, separator)
-    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
-    environment.set(name, entry.slice(separator + 1))
-  }
+  const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) {
     if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
       throw new Error('subprocess-e2b: terminal environment entries require non-empty NUL-free names without = and NUL-free values')

From ec0310ca1b5eca56424c617af7360d40b329ce59 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:03:04 +0800
Subject: [PATCH 113/262] fix(e2b): harden remote teardown transactions

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   2 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   2 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  25 ++
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |   6 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  29 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  23 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  12 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  12 +-
 packages/e2b/subprocess-e2b/src/index.ts      |   6 +-
 packages/e2b/subprocess-e2b/src/output.ts     |   8 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 332 ++++++++++++++----
 packages/e2b/subprocess-e2b/src/terminal.ts   |  47 +--
 .../subprocess-e2b/tests/subprocess.spec.ts   | 311 +++++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  16 +
 19 files changed, 712 insertions(+), 135 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index b5e8e6e47c..079924ac74 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 029950cb2dae47bcf1ce819156135e58d46a4bb6
-2026-07-27-e2b-remote-runtime-poc.zh.md: 4029cc85d206e0dd0b7dbd91ec03674062df8531
+2026-07-27-e2b-remote-runtime-poc.md: 02de8df021094fa326431a996cd183d13b9c0c8c
+2026-07-27-e2b-remote-runtime-poc.zh.md: 3b7ddf761b2cbf950898a0083cf9da653d20e723
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 029950cb2d..02de8df021 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -38,7 +38,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, byte-split UTF-8 command output, bounded raw spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 4029cc85d2..3b7ddf761b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -38,7 +38,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 7c5fce5535..6fa95c24b6 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -85,6 +85,30 @@ try {
     throw new Error(`E2B subprocess corrupted split UTF-8 output: ${JSON.stringify({ splitUtf8Outcome, splitUtf8Output })}`)
   }
 
+  const outputDrainStarted = Date.now()
+  const outputDrainHandle = ctx.subprocess.spawn({
+    argv: ['bash', '-c', "bash -c 'exec -a dsh-output-drain-descendant sleep 30' & printf 'leader-done\\n'"],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 64 }, stderr: { maxBytes: 4_096 } },
+    graceMs: 250,
+    env: {},
+  })
+  const outputDrainOutcome = await outputDrainHandle.done
+  const outputDrainText = outputDrainHandle.collected.stdout?.readFrom(0).text
+  const outputDrainElapsedMs = Date.now() - outputDrainStarted
+  outputDrainHandle.terminate()
+  const outputDrainExited = await outputDrainHandle.waitForExit(AbortSignal.timeout(5_000))
+  const outputDrainProcesses = await sandbox.commands.list()
+  const outputDrainClean = !outputDrainProcesses.some(processInfo =>
+    JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-output-drain-descendant'),
+  )
+  if (outputDrainOutcome.exitCode !== 0 || outputDrainText !== 'leader-done\n'
+    || outputDrainElapsedMs >= 10_000 || !outputDrainExited || !outputDrainClean) {
+    throw new Error(`E2B subprocess output drain was not bounded: ${JSON.stringify({
+      outputDrainOutcome, outputDrainText, outputDrainElapsedMs, outputDrainExited, outputDrainClean,
+    })}`)
+  }
+
   const remoteFiles = sandbox.files as unknown as {
     read(path: string, options?: unknown): Promise<unknown>
   }
@@ -384,6 +408,7 @@ try {
     fsRead,
     explicitEnvironment,
     splitUtf8Output,
+    outputDrain: { outcome: outputDrainOutcome, text: outputDrainText, exited: outputDrainExited, clean: outputDrainClean },
     publicationRollback,
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 229a9e9343..d8f1dcdc3f 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 56606a22c36e65bcc53f2b8cce27f0739da1b8e2
-README.zh.md: 2e3213e431f15f1b22d2b8a429b27ab8a6a78671
+README.md: 01c7ade2f5f31e34091ad0ae910287e659f15549
+README.zh.md: fb95a12cbbbd431ccb3283a14bb63b324f9bdea6
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 56606a22c3..01c7ade2f5 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -28,7 +28,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 ## Lifecycle and ownership
 
-Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, then sets that directory to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
 Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 2e3213e431..fb95a12cbb 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -28,7 +28,7 @@
 
 ## 生命周期与所有权
 
-构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
 资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 96da912033..2c0b3c635c 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -7,7 +7,7 @@
 import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { Sandbox, SandboxNotFoundError } from 'e2b'
+import { FileType, Sandbox, SandboxNotFoundError } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 export {
@@ -232,6 +232,10 @@ export class E2BSandboxService extends Service {
     try {
       await sandbox.files.makeDir(this.cwd)
       await sandbox.files.makeDir(this.runtimeRoot)
+      const runtimeRoot = await sandbox.files.getInfo(this.runtimeRoot)
+      if (runtimeRoot.type !== FileType.DIR || runtimeRoot.symlinkTarget !== undefined) {
+        throw new Error(`dsh-e2b: runtime root must be a real directory: ${this.runtimeRoot}`)
+      }
       await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`)
       return sandbox
     } catch (error: unknown) {
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 4e7be57c45..1ece44bb6a 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -5,7 +5,7 @@ import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import E2BSandboxService, { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -92,6 +92,27 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       await session.close('environment test complete')
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
+
+      await sandbox.commands.run([
+        'rm -rf -- /home/user/.dsh-e2b /home/user/dsh-e2b-runtime-target',
+        'mkdir -p -- /home/user/dsh-e2b-runtime-target',
+        'chmod 755 -- /home/user/dsh-e2b-runtime-target',
+        'ln -s -- /home/user/dsh-e2b-runtime-target /home/user/.dsh-e2b',
+      ].join('\n'))
+      const linkedCtx = new Context()
+      const linkedFiber = await linkedCtx.plugin(E2BSandboxService, {
+        apiKey,
+        sandboxId: sandbox.sandboxId,
+        cwd: '/home/user',
+        onDispose: 'leave',
+      })
+      try {
+        await expect(linkedCtx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
+        const target = await sandbox.files.getInfo('/home/user/dsh-e2b-runtime-target')
+        expect(target.mode & 0o777).toBe(0o755)
+      } finally {
+        await linkedFiber.dispose()
+      }
     } finally {
       await sandbox.kill().catch(() => false)
     }
@@ -123,6 +144,12 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
       splitUtf8Output: '你好',
+      outputDrain: {
+        outcome: { exitCode: 0, signal: null },
+        text: 'leader-done\n',
+        exited: true,
+        clean: true,
+      },
       publicationRollback: true,
       spill: {
         liveBytes: 6,
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index bb96ca806a..ff90c37b3a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   E2BSandboxId,
+  FileType,
   SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
@@ -33,6 +34,7 @@ vi.mock('e2b', async (importOriginal) => {
 interface SandboxFixture {
   sandbox: SandboxType
   makeDir: ReturnType<typeof vi.fn>
+  getInfo: ReturnType<typeof vi.fn>
   run: ReturnType<typeof vi.fn>
   kill: ReturnType<typeof vi.fn>
   pause: ReturnType<typeof vi.fn>
@@ -40,17 +42,18 @@ interface SandboxFixture {
 
 function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
   const makeDir = vi.fn().mockResolvedValue(true)
+  const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
   const run = vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
   const kill = vi.fn().mockResolvedValue(undefined)
   const pause = vi.fn().mockResolvedValue(true)
   const sandbox = {
     sandboxId: id,
-    files: { makeDir },
+    files: { makeDir, getInfo },
     commands: { run },
     kill,
     pause,
   } as unknown as SandboxType
-  return { sandbox, makeDir, run, kill, pause }
+  return { sandbox, makeDir, getInfo, run, kill, pause }
 }
 
 beforeEach(() => {
@@ -82,6 +85,7 @@ describe('E2BSandboxService', () => {
     })
     expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
     expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
+    expect(fixture.getInfo).toHaveBeenCalledWith('/home/user/workspace/.dsh-e2b')
     expect(fixture.run).toHaveBeenCalledWith("chmod 700 -- '/home/user/workspace/.dsh-e2b'")
 
     await fiber.dispose()
@@ -220,6 +224,21 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).not.toHaveBeenCalled()
   })
 
+  it.each([
+    ['symbolic link', { type: FileType.DIR, symlinkTarget: '/tmp/redirected' }],
+    ['regular file', { type: FileType.FILE }],
+  ])('rejects a reserved runtime root that is a %s', async (_label, info) => {
+    const fixture = fakeSandbox()
+    fixture.getInfo.mockResolvedValueOnce(info)
+    sdk.connect.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
+    expect(fixture.run).not.toHaveBeenCalled()
+    expect(fixture.kill).not.toHaveBeenCalled()
+  })
+
   it.each([
     [{ apiKey: '' }, /configure apiKey/],
     [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 33a36141d0..091a6972cf 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 58f13b264324d2168d4bc264b60100cdafa0a366
-README.zh.md: d547e4e8d66f629edcef753651180fe1806ad9bf
+README.md: b1aa480305fef9ca485340b6bdae50f9fcffd88f
+README.zh.md: b4824c90e7fb908d9c12e77c19d2b952055dcb40
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 58f13b2643..b1aa480305 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -6,14 +6,14 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 ## Behavior
 
-- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
-- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
-- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers; after `graceMs`, the adapter disconnects an incomplete SDK stream, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Setup and teardown own the private state transaction, including failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index d547e4e8d6..b4824c90e7 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -6,14 +6,14 @@
 
 ## 行为
 
-- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
-- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
-- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态；超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。setup 与 teardown 负责私有状态事务，包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 86ca5ceada..27efb216da 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -46,14 +46,12 @@ export class E2BSubprocessService extends SubprocessService {
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
-        pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
+        pending.push(handle.waitForExit().then(() => { this.live.delete(handle) }))
       }
       for (const terminal of terminals) {
         terminal.terminate()
-        pending.push(terminal.waitForExit())
+        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
-      this.live.clear()
-      this.terminals.clear()
       await Promise.all(pending)
     }, 'e2b subprocess teardown')
   }
diff --git a/packages/e2b/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
index 6cb61e4f09..8afcd138dc 100644
--- a/packages/e2b/subprocess-e2b/src/output.ts
+++ b/packages/e2b/subprocess-e2b/src/output.ts
@@ -66,6 +66,7 @@ export class E2BOutputReader implements SubprocessOutputReader {
   private chunks: Buffer[] = []
   private retainedBytes = 0
   private totalBytes = 0
+  private spillValid = true
 
   /**
    * Create a bounded reader over one remote spill path.
@@ -84,6 +85,11 @@ export class E2BOutputReader implements SubprocessOutputReader {
     return this.totalBytes
   }
 
+  /** Stop advertising a remote spill whose writer did not reach clean EOF. */
+  invalidateSpill(): void {
+    this.spillValid = false
+  }
+
   /**
    * Append one byte-faithful decoded transport event.
    * @param bytes - Raw command bytes recovered from the ASCII SDK transport.
@@ -120,7 +126,7 @@ export class E2BOutputReader implements SubprocessOutputReader {
       text: retained.subarray(start).toString('utf8'),
       nextOffset: this.totalBytes,
       lossy,
-      ...(lossy && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
+      ...(lossy && this.spillValid && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
         ? { spillPath: this.spillPath }
         : {}),
     }
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 5f8a107cf6..3a8047eb54 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -5,6 +5,7 @@ import { PassThrough, Writable } from 'node:stream'
 import { posix } from 'node:path'
 import {
   CommandExitError,
+  FileNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -41,6 +42,10 @@ function hasSpill(mode: SubprocessOutputMode): mode is SubprocessCollect & { spi
   return isCollect(mode) && mode.spill !== undefined
 }
 
+function isValidProcessId(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0
+}
+
 function asError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error))
 }
@@ -73,6 +78,20 @@ interface RemotePaths {
   stderr: string
 }
 
+type CommandSettlement =
+  | { kind: 'result'; result: CommandResult }
+  | { kind: 'error'; error: unknown }
+
+function withinMs<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+  return new Promise<T | undefined>((resolve) => {
+    const timer = setTimeout(() => { resolve(undefined) }, timeoutMs)
+    void promise.then((value) => {
+      clearTimeout(timer)
+      resolve(value)
+    })
+  })
+}
+
 function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
   const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
@@ -96,15 +115,16 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     'dsh_e2b_tr=$4',
     'dsh_e2b_tee=$5',
     'dsh_e2b_head=$6',
-    'shift 6',
+    'dsh_e2b_rm=$7',
+    'shift 7',
     'dsh_e2b_pgid="$("$dsh_e2b_ps" -o pgid= -p "$$" | "$dsh_e2b_tr" -d " ")"',
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
     `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
-    `: > ${quoteE2BShellArg(paths.environment)}`,
+    `"$dsh_e2b_rm" -f -- ${quoteE2BShellArg(paths.environment)}`,
     `"$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
-    'wait',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
+    'wait',
     'exit "$dsh_e2b_status"',
   ].join('\n')
   const argv = spec.argv.map(quoteE2BShellArg).join(' ')
@@ -118,10 +138,11 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     'dsh_e2b_tr="$(command -v tr)"',
     'dsh_e2b_tee="$(command -v tee)"',
     'dsh_e2b_head="$(command -v head)"',
-    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head"; do',
+    'dsh_e2b_rm="$(command -v rm)"',
+    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm"; do',
     '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
     'done',
-    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" ${argv}`,
+    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
   ].join('\n')
   return bootstrap
 }
@@ -149,6 +170,26 @@ function waitTick(signal?: AbortSignal): Promise<boolean> {
   })
 }
 
+const WAIT_ABORTED = Symbol('wait aborted')
+
+function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.resolve(WAIT_ABORTED)
+  return new Promise<T | typeof WAIT_ABORTED>((resolve, reject) => {
+    const onAbort = (): void => { cleanup(); resolve(WAIT_ABORTED) }
+    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) {
+      onAbort()
+      return
+    }
+    void promise.then(
+      (value) => { cleanup(); resolve(value) },
+      (error: unknown) => { cleanup(); reject(asError(error)) },
+    )
+  })
+}
+
 /** E2B-backed subprocess handle with deferred remote PID acquisition. */
 export class E2BSubprocessHandle implements SubprocessHandle {
   readonly stdin: Writable | undefined
@@ -157,6 +198,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   readonly collected: SubprocessHandle['collected']
   readonly done: Promise<SubprocessOutcome>
 
+  private readonly commandState = Promise.withResolvers<CommandHandle | undefined>()
   private readonly readyState = Promise.withResolvers<CommandHandle>()
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
@@ -166,9 +208,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private remotePid = -1
   private commandHandle: CommandHandle | undefined
   private outputTransportError: Error | undefined
-  private terminationRequested = false
+  private outputDrainExpired = false
+  private stateDirectoryCreated = false
+  private invalidHandleQuiescent = false
+  private provisionalHandleQuiescent = false
+  private terminationStarted = false
+  private terminationAttempt: Promise<void> | undefined
+  private terminationFailure: Error | undefined
   private terminationSignal: NodeJS.Signals | null = null
-  private termination: Promise<void> | undefined
 
   /**
    * Begin an E2B command without blocking the synchronous subprocess spawn seam.
@@ -217,22 +264,47 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationRequested) return
-    this.terminationRequested = true
-    this.termination = this.terminateRemote()
-    void this.termination.catch(() => {})
+    if (this.terminationAttempt !== undefined) return
+    this.terminationStarted = true
+    this.terminationFailure = undefined
+    const attempt = this.terminateRemote()
+    this.terminationAttempt = attempt
+    void attempt.then(
+      () => {
+        this.terminationAttempt = undefined
+      },
+      (error: unknown) => {
+        this.terminationFailure = asError(error)
+        this.terminationAttempt = undefined
+      },
+    )
   }
 
   /** @inheritdoc */
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
     let handle: CommandHandle | undefined
-    try {
-      handle = await this.readyForWait(signal)
-    } catch {
-      handle = this.commandHandle
+    if (this.terminationStarted) {
+      const observed = await waitWithSignal(this.commandState.promise, signal)
+      if (observed === WAIT_ABORTED) return false
+      handle = observed
       if (handle === undefined) return true
+      if (this.remotePid <= 0) {
+        const attempt = this.terminationAttempt
+        if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
+        this.throwTerminationFailure()
+        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) return true
+      }
+    } else {
+      try {
+        const observed = await waitWithSignal(this.readyState.promise, signal)
+        if (observed === WAIT_ABORTED) return false
+        handle = observed
+      } catch {
+        handle = this.commandHandle
+        if (handle === undefined) return true
+      }
     }
-    if (handle === undefined) return false
+    this.throwTerminationFailure()
     let sandbox: Sandbox
     try {
       sandbox = await this.runtime.getSandbox()
@@ -242,33 +314,19 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
     const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
     while (await this.groupAlive(sandbox, processGroupId, signal)) {
+      this.throwTerminationFailure()
       if (!await waitTick(signal)) return false
     }
+    this.throwTerminationFailure()
     return !isAborted(signal)
   }
 
-  private readyForWait(signal: AbortSignal | undefined): Promise<CommandHandle | undefined> {
-    if (signal === undefined) return this.readyState.promise
-    return new Promise<CommandHandle | undefined>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(undefined) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      if (signal.aborted) {
-        onAbort()
-        return
-      }
-      void this.readyState.promise.then(
-        (handle) => { cleanup(); resolve(handle) },
-        (error: unknown) => { cleanup(); reject(asError(error)) },
-      )
-    })
-  }
-
   private readonly onAbort = (): void => { this.terminate() }
 
   private async run(): Promise<SubprocessOutcome> {
+    let sandbox: Sandbox | undefined
     try {
-      const sandbox = await this.runtime.getSandbox()
+      sandbox = await this.runtime.getSandbox()
       await this.prepareState(sandbox)
       const handle = await sandbox.commands.run(
         commandText(this.spec, this.paths),
@@ -281,12 +339,26 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
         },
       )
-      if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
-        throw new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
-      }
       this.commandHandle = handle
       const completion = handle.wait()
       void completion.catch(() => {})
+      if (!isValidProcessId(handle.pid)) {
+        const invalidPid = new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
+        try {
+          await handle.kill()
+          this.invalidHandleQuiescent = true
+          this.commandHandle = undefined
+        } catch (cleanupError: unknown) {
+          this.terminationFailure = asError(cleanupError)
+          this.commandState.resolve(handle)
+          throw new AggregateError(
+            [invalidPid, cleanupError],
+            'subprocess-e2b: invalid command pid rollback did not reach quiescence',
+          )
+        }
+        throw invalidPid
+      }
+      this.commandState.resolve(handle)
       try {
         this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
       } catch (error: unknown) {
@@ -302,16 +374,28 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       this.readyState.resolve(handle)
       await this.writeBatchStdin(handle)
-      const outcome = await this.waitForCommand(completion)
+      const outcome = await this.waitForCommand(sandbox, handle, completion)
       if (this.outputTransportError !== undefined) throw this.outputTransportError
-      const requireCompleteOutput = this.terminationSignal === null
+      const requireCompleteOutput = this.terminationSignal === null && !this.outputDrainExpired
       this.stdoutDecoder.finish(requireCompleteOutput)
       this.stderrDecoder.finish(requireCompleteOutput)
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
-      this.readyState.reject(error)
-      throw error
+      this.commandState.resolve(undefined)
+      let failure = error
+      if (sandbox !== undefined && this.stateDirectoryCreated) {
+        try {
+          await this.removeFailedState(sandbox)
+        } catch (cleanupError: unknown) {
+          failure = new AggregateError(
+            [error, cleanupError],
+            'subprocess-e2b: command failed and private state cleanup failed',
+          )
+        }
+      }
+      this.readyState.reject(failure)
+      throw failure
     } finally {
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
@@ -322,6 +406,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private async prepareState(sandbox: Sandbox): Promise<void> {
     const ambient = await sandbox.commands.run('env -0')
     await sandbox.files.makeDir(this.stateDir)
+    this.stateDirectoryCreated = true
     await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
     const files = [
       { path: this.paths.pid, data: '' },
@@ -405,20 +490,45 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
   }
 
-  private async waitForCommand(completion: Promise<CommandResult>): Promise<SubprocessOutcome> {
-    try {
-      const result = await completion
-      return { exitCode: result.exitCode, signal: null }
-    } catch (error: unknown) {
-      if (error instanceof CommandExitError) {
-        return this.terminationSignal === null
-          ? { exitCode: error.exitCode, signal: null }
-          : { exitCode: null, signal: this.terminationSignal }
+  private async waitForCommand(
+    sandbox: Sandbox,
+    handle: CommandHandle,
+    completion: Promise<CommandResult>,
+  ): Promise<SubprocessOutcome> {
+    const settlement = completion.then<CommandSettlement, CommandSettlement>(
+      result => ({ kind: 'result', result }),
+      (error: unknown) => ({ kind: 'error', error }),
+    )
+    while (true) {
+      const rawStatus = (await sandbox.files.read(this.paths.status)).trim()
+      if (rawStatus.length > 0) {
+        const exitCode = Number(rawStatus)
+        if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
+          throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
+        }
+        const completed = await withinMs(settlement, this.spec.graceMs)
+        if (completed !== undefined) return this.commandOutcome(completed)
+        this.outputDrainExpired = true
+        this.stdoutReader?.invalidateSpill()
+        this.stderrReader?.invalidateSpill()
+        await handle.disconnect()
+        return { exitCode, signal: null }
       }
-      throw error
+      const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
+      if (completed !== undefined) return this.commandOutcome(completed)
     }
   }
 
+  private commandOutcome(settlement: CommandSettlement): SubprocessOutcome {
+    if (settlement.kind === 'result') return { exitCode: settlement.result.exitCode, signal: null }
+    if (settlement.error instanceof CommandExitError) {
+      return this.terminationSignal === null
+        ? { exitCode: settlement.error.exitCode, signal: null }
+        : { exitCode: null, signal: this.terminationSignal }
+    }
+    throw settlement.error
+  }
+
   private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
     // The bootstrap ends in an exec chain through the scrubbed environment and
     // `setsid`, so E2B's command PID is the provisional group id even before the
@@ -433,35 +543,99 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async terminateRemote(): Promise<void> {
-    let handle: CommandHandle | undefined
-    try {
-      handle = await this.readyState.promise
-    } catch {
-      handle = this.commandHandle
-    }
+    const handle = await this.commandState.promise
     if (handle === undefined) return
-    const sandbox = await this.runtime.getSandbox()
-    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
-    this.terminationSignal = 'SIGTERM'
-    await this.signalGroup(sandbox, processGroupId, 'TERM')
-    const deadline = Date.now() + this.spec.graceMs
-    while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
-      await waitTick()
+    if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
+      await handle.kill()
+      this.invalidHandleQuiescent = true
+      this.commandHandle = undefined
+      return
     }
-    if (!await this.groupAlive(sandbox, processGroupId)) return
-    this.terminationSignal = 'SIGKILL'
+    if (this.remotePid <= 0) {
+      const sandbox = await this.runtime.getSandbox()
+      this.terminationSignal = 'SIGTERM'
+      try {
+        const delivered = await this.signalGroup(sandbox, handle.pid, 'TERM')
+        if (delivered) {
+          const deadline = Date.now() + this.spec.graceMs
+          while (Date.now() < deadline && await this.groupAlive(sandbox, handle.pid)) await waitTick()
+          if (!await this.groupAlive(sandbox, handle.pid)) {
+            this.provisionalHandleQuiescent = true
+            return
+          }
+        }
+      } catch (_gracefulTerminationFailure) {
+        // A missing or unobservable provisional group still has the SDK handle fallback.
+      }
+      this.terminationSignal = 'SIGKILL'
+      let groupDelivered = false
+      let groupFailure: unknown
+      try {
+        groupDelivered = await this.signalGroup(sandbox, handle.pid, 'KILL')
+      } catch (error: unknown) {
+        groupFailure = error
+      }
+      let handleFailure: unknown
+      try {
+        await handle.kill()
+        this.provisionalHandleQuiescent = true
+      } catch (error: unknown) {
+        handleFailure = error
+      }
+      if (!groupDelivered && handleFailure !== undefined) {
+        throw new AggregateError(
+          [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
+          'subprocess-e2b: force termination failed through both process-group and SDK transports',
+        )
+      }
+      return
+    }
+    const sandbox = await this.runtime.getSandbox()
+    const processGroupId = this.remotePid
+    this.terminationSignal = 'SIGTERM'
     try {
-      await this.signalGroup(sandbox, processGroupId, 'KILL')
-    } finally {
-      await handle.kill().catch(() => false)
+      await this.signalGroup(sandbox, processGroupId, 'TERM')
+      const deadline = Date.now() + this.spec.graceMs
+      while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
+        await waitTick()
+      }
+      if (!await this.groupAlive(sandbox, processGroupId)) return
+    } catch (_gracefulTerminationFailure) {
+      // Failed TERM delivery or observation cannot prove exit; force cleanup still owns the group.
+    }
+    this.terminationSignal = 'SIGKILL'
+    let groupFailure: unknown
+    let groupDelivered = false
+    try {
+      groupDelivered = await this.signalGroup(sandbox, processGroupId, 'KILL')
+    } catch (error: unknown) {
+      groupFailure = error
+    }
+    let handleFailure: unknown
+    try {
+      await handle.kill()
+    } catch (error: unknown) {
+      handleFailure = error
+    }
+    if (!groupDelivered && handleFailure !== undefined && await this.groupAlive(sandbox, processGroupId)) {
+      throw new AggregateError(
+        [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
+        'subprocess-e2b: force termination failed through both process-group and SDK transports',
+      )
     }
   }
 
-  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<void> {
+  private throwTerminationFailure(): void {
+    if (this.terminationFailure !== undefined) throw this.terminationFailure
+  }
+
+  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<boolean> {
     try {
       await sandbox.commands.run(`kill -${signal} -- -${pid}`)
+      return true
     } catch (error: unknown) {
-      if (!(error instanceof CommandExitError)) throw error
+      if (error instanceof CommandExitError) return false
+      throw error
     }
   }
 
@@ -482,7 +656,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!hasSpill(mode)) return
       // A spill mode is a collect mode, so construction always created its reader.
       const size = (reader as E2BOutputReader).size
-      if (size <= mode.maxBytes || size > mode.spill.maxBytes) {
+      if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
         removals.push(sandbox.files.remove(path).catch(() => {}))
       }
     }
@@ -490,4 +664,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     collect(this.spec.stdio.stderr, this.stderrReader, this.paths.stderr)
     await Promise.all(removals)
   }
+
+  private async removeFailedState(sandbox: Sandbox): Promise<void> {
+    const failures: Error[] = []
+    for (const path of [this.paths.environment, this.stateDir]) {
+      try {
+        await sandbox.files.remove(path)
+      } catch (error: unknown) {
+        if (!(error instanceof FileNotFoundError)) failures.push(asError(error))
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'subprocess-e2b: failed to remove private command state')
+    }
+  }
 }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 7185899f79..fb8dac6f49 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -376,25 +376,26 @@ export async function spawnE2BTerminal(
     argv: posix.join(stateDir, 'argv'),
     ready: posix.join(stateDir, 'ready'),
   }
-  const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
-  const environment = remoteEnvironment(ambient.stdout, spec.env)
-  const argv = serializeValues(spec.argv, 'argv')
-  await sandbox.files.makeDir(stateDir)
-  await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
-  await sandbox.files.write([
-    { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
-    { path: paths.environment, data: environment },
-    { path: paths.argv, data: argv },
-  ], signalOpts(spec.signal))
-  await sandbox.commands.run(
-    `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
-    signalOpts(spec.signal),
-  )
-
   const output = new PassThrough()
   let handle: CommandHandle | undefined
   let completion: Promise<CommandResult> | undefined
+  let stateDirectoryCreated = false
   try {
+    const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
+    const environment = remoteEnvironment(ambient.stdout, spec.env)
+    const argv = serializeValues(spec.argv, 'argv')
+    await sandbox.files.makeDir(stateDir)
+    stateDirectoryCreated = true
+    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
+    await sandbox.files.write([
+      { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
+      { path: paths.environment, data: environment },
+      { path: paths.argv, data: argv },
+    ], signalOpts(spec.signal))
+    await sandbox.commands.run(
+      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
+      signalOpts(spec.signal),
+    )
     handle = await sandbox.pty.create({
       rows: spec.rows,
       cols: spec.cols,
@@ -425,19 +426,25 @@ export async function spawnE2BTerminal(
     )
   } catch (error: unknown) {
     output.destroy()
-    let cleanupError: Error | undefined
+    const cleanupErrors: Error[] = []
     if (handle !== undefined && completion !== undefined) {
       try {
         await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
       } catch (rollbackError: unknown) {
-        cleanupError = asError(rollbackError)
+        cleanupErrors.push(asError(rollbackError))
       }
     } else if (handle !== undefined) {
       await handle.kill().catch(() => false)
     }
-    await sandbox.files.remove(stateDir).catch(() => {})
-    if (cleanupError !== undefined) {
-      throw new AggregateError([asError(error), cleanupError], asError(error).message)
+    if (stateDirectoryCreated) {
+      try {
+        await sandbox.files.remove(stateDir)
+      } catch (stateError: unknown) {
+        if (!(stateError instanceof FileNotFoundError)) cleanupErrors.push(asError(stateError))
+      }
+    }
+    if (cleanupErrors.length > 0) {
+      throw new AggregateError([asError(error), ...cleanupErrors], asError(error).message)
     }
     throw error
   }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 32adf872b3..d81b49a600 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -2,6 +2,7 @@ import { once } from 'node:events'
 import { Context } from 'cordis'
 import {
   CommandExitError,
+  FileNotFoundError,
   type CommandHandle,
   type CommandResult,
   type Sandbox,
@@ -35,10 +36,14 @@ class FakeCommandHandle {
   readonly sent: Array<string | Uint8Array> = []
   closes = 0
   kills = 0
+  disconnects = 0
   killError: unknown
+  disconnectError: unknown
   private readonly result = Promise.withResolvers<CommandResult>()
   private settled = false
 
+  constructor(private readonly onKill: () => void = () => {}) {}
+
   wait(): Promise<CommandResult> {
     return this.result.promise
   }
@@ -54,9 +59,15 @@ class FakeCommandHandle {
   async kill(): Promise<boolean> {
     this.kills += 1
     if (this.killError !== undefined) throw this.killError
+    this.onKill()
     return true
   }
 
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
   succeed(exitCode = 0): void {
     if (this.settled) return
     this.settled = true
@@ -77,7 +88,7 @@ class FakeCommandHandle {
 }
 
 class FakeSandbox {
-  readonly handle = new FakeCommandHandle()
+  readonly handle: FakeCommandHandle
   readonly commandsSeen: string[] = []
   readonly writtenFiles: string[][] = []
   readonly writtenFileData = new Map<string, string>()
@@ -85,19 +96,35 @@ class FakeSandbox {
   readonly directories: string[] = []
   startOptions: StartOptions | undefined
   backgroundError: unknown
+  envError: unknown
   nextRemoveError: unknown
   probeError: unknown
   signalError: unknown
+  readonly signalErrors: unknown[] = []
   trapsTerm = false
   delaysKill = false
+  sdkKillStops = true
   alive = true
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   processGroupId = '4242\n'
+  exitStatus = ''
   readonly processGroupReads: string[] = []
+  afterStatusRead: (() => void) | undefined
   beforeProbe: (() => void) | undefined
   afterProbe: (() => void) | undefined
   private startGate: Promise<void> | undefined
   private openStart: (() => void) | undefined
+  private processGroupReadGate: Promise<void> | undefined
+  private openProcessGroupRead: (() => void) | undefined
+
+  constructor() {
+    this.handle = new FakeCommandHandle(() => {
+      if (this.sdkKillStops) {
+        this.alive = false
+        this.handle.fail(137)
+      }
+    })
+  }
 
   deferStart(): void {
     const gate = Promise.withResolvers<undefined>()
@@ -109,6 +136,16 @@ class FakeSandbox {
     this.openStart?.()
   }
 
+  deferProcessGroupRead(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.processGroupReadGate = gate.promise
+    this.openProcessGroupRead = () => { gate.resolve(undefined) }
+  }
+
+  releaseProcessGroupRead(): void {
+    this.openProcessGroupRead?.()
+  }
+
   finish(exitCode = 0): void {
     this.alive = false
     void this.completeOutput().then(
@@ -155,7 +192,14 @@ class FakeSandbox {
         for (const file of files) this.writtenFileData.set(file.path, file.data)
         return files.map(() => ({}))
       },
-      read: async (): Promise<string> => this.processGroupReads.shift() ?? this.processGroupId,
+      read: async (path: string): Promise<string> => {
+        if (!path.endsWith('/exit-code')) {
+          await this.processGroupReadGate
+          return this.processGroupReads.shift() ?? this.processGroupId
+        }
+        this.afterStatusRead?.()
+        return this.exitStatus
+      },
       remove: async (path: string): Promise<void> => {
         this.removed.push(path)
         if (this.nextRemoveError !== undefined) {
@@ -168,7 +212,10 @@ class FakeSandbox {
     commands: {
       run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
         this.commandsSeen.push(command)
-        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        if (command === 'env -0') {
+          if (this.envError !== undefined) throw this.envError
+          return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        }
         if (command.startsWith('kill -0 ')) {
           this.beforeProbe?.()
           if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
@@ -182,9 +229,9 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -TERM ')) {
-          if (this.signalError !== undefined) {
-            const error = this.signalError
-            this.signalError = undefined
+          const error = this.signalErrors.shift() ?? this.signalError
+          if (error !== undefined) {
+            if (this.signalErrors.length === 0) this.signalError = undefined
             throw error
           }
           if (!this.trapsTerm) {
@@ -194,9 +241,9 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -KILL ')) {
-          if (this.signalError !== undefined) {
-            const error = this.signalError
-            this.signalError = undefined
+          const error = this.signalErrors.shift() ?? this.signalError
+          if (error !== undefined) {
+            if (this.signalErrors.length === 0) this.signalError = undefined
             throw error
           }
           if (!this.delaysKill) this.alive = false
@@ -277,6 +324,8 @@ describe('E2BOutputReader', () => {
     expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
     expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
     expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
+    reader.invalidateSpill()
+    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
   })
 
   it('drops whole head chunks and withholds absent or over-cap spills', () => {
@@ -390,6 +439,50 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).rejects.toThrow('incomplete output transport')
   })
 
+  it('bounds descendant-held output draining and withholds the incomplete spill', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-bound')
+    await flush()
+    await fake.stdout('leader-output')
+    fake.exitStatus = '0\n'
+
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.handle.disconnects).toBe(1)
+    expect(handle.collected.stdout?.readFrom(0)).toEqual({
+      text: 'tput',
+      nextOffset: 13,
+      lossy: true,
+    })
+    expect(fake.removed).toContain('/runtime/drain-bound/stdout.log')
+
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('accepts clean encoder completion inside the output-drain grace', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
+    await flush()
+    fake.exitStatus = '0\n'
+    fake.afterStatusRead = () => {
+      fake.afterStatusRead = undefined
+      setTimeout(() => { fake.finish() }, 0)
+    }
+
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.handle.disconnects).toBe(0)
+  })
+
+  it('rejects an invalid direct-command exit status', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')
+    await flush()
+    fake.exitStatus = '999\n'
+    await expect(handle.done).rejects.toThrow('invalid exit code')
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
@@ -510,6 +603,97 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('kills through the provisional SDK handle before process-group publication', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.signalErrors.push(commandError(1), commandError(1))
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/pre-publication-kill')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    expect(fake.alive).toBe(false)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    fake.releaseProcessGroupRead()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+  })
+
+  it('bounds a quiescence observer while provisional termination is awaiting the controller', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    const reconnect = Promise.withResolvers<Sandbox>()
+    let calls = 0
+    const delayedRuntime = runtime(fake, async () => {
+      calls += 1
+      return calls === 1 ? fake.sandbox : await reconnect.promise
+    })
+    const handle = new E2BSubprocessHandle(delayedRuntime, spec(), '/runtime/pre-publication-observer')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+    handle.terminate()
+
+    const controller = new AbortController()
+    const waiting = handle.waitForExit(controller.signal)
+    await flush()
+    controller.abort()
+    await expect(waiting).resolves.toBe(false)
+
+    reconnect.resolve(fake.sandbox)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.releaseProcessGroupRead()
+    await handle.done
+  })
+
+  it('proves a provisional group exit when the SDK kill fallback fails', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.trapsTerm = true
+    fake.handle.killError = new Error('SDK kill unavailable')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-group-kill')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.releaseProcessGroupRead()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+  })
+
+  it('reports failed provisional group and SDK force transports', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-failure')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+
+    fake.handle.killError = undefined
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.releaseProcessGroupRead()
+    await handle.done
+
+    const absentGroup = new FakeSandbox()
+    absentGroup.deferProcessGroupRead()
+    absentGroup.signalErrors.push(commandError(1), commandError(1))
+    absentGroup.handle.killError = new Error('SDK kill failed without a provisional group')
+    const absentHandle = new E2BSubprocessHandle(
+      runtime(absentGroup),
+      spec({ graceMs: 1 }),
+      '/runtime/pre-publication-absent-group',
+    )
+    await vi.waitFor(() => { expect(absentGroup.startOptions).toBeDefined() })
+    absentHandle.terminate()
+    await expect(absentHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    absentGroup.handle.killError = undefined
+    absentHandle.terminate()
+    await expect(absentHandle.waitForExit()).resolves.toBe(true)
+    absentGroup.releaseProcessGroupRead()
+    await absentHandle.done
+  })
+
   it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
@@ -559,6 +743,17 @@ describe('E2BSubprocessHandle', () => {
     await expect(liveWait).resolves.toBe(false)
     fake.finish()
     await handle.done
+
+    const terminatingFake = new FakeSandbox()
+    terminatingFake.deferStart()
+    const terminating = new E2BSubprocessHandle(runtime(terminatingFake), spec(), '/runtime/wait-termination-start')
+    terminating.terminate()
+    const beforeHandle = new AbortController()
+    const handlePending = terminating.waitForExit(beforeHandle.signal)
+    beforeHandle.abort()
+    await expect(handlePending).resolves.toBe(false)
+    terminatingFake.releaseStart()
+    await terminating.done
   })
 
   it('bounds both sides of the liveness-poll abort race', async () => {
@@ -580,6 +775,14 @@ describe('E2BSubprocessHandle', () => {
     const duringProbe = new AbortController()
     fake.beforeProbe = () => { duringProbe.abort(); fake.beforeProbe = undefined }
     await expect(handle.waitForExit(duringProbe.signal)).resolves.toBe(false)
+
+    let racedAbort = false
+    const raceSignal = {
+      get aborted() { return racedAbort },
+      addEventListener: () => { racedAbort = true },
+      removeEventListener: () => {},
+    } as unknown as AbortSignal
+    await expect(handle.waitForExit(raceSignal)).resolves.toBe(false)
     fake.finish()
     await handle.done
   })
@@ -599,8 +802,36 @@ describe('E2BSubprocessHandle', () => {
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail')
     await expect(handle.done).rejects.toThrow('start failed')
     expect(handle.pid).toBe(-1)
+    expect(fake.removed).toContain('/runtime/fail/environment')
+    expect(fake.removed).toContain('/runtime/fail')
     await expect(handle.waitForExit()).resolves.toBe(true)
     handle.terminate()
+
+    const unavailableHandle = new E2BSubprocessHandle(
+      runtime(new FakeSandbox(), async () => { throw new Error('sandbox unavailable') }),
+      spec(),
+      '/runtime/unavailable-start',
+    )
+    await expect(unavailableHandle.done).rejects.toThrow('sandbox unavailable')
+    await expect(unavailableHandle.waitForExit()).resolves.toBe(true)
+
+    const envFailure = new FakeSandbox()
+    envFailure.envError = new Error('ambient lookup failed')
+    const envHandle = new E2BSubprocessHandle(runtime(envFailure), spec(), '/runtime/env-failure')
+    await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
+    expect(envFailure.removed).toEqual([])
+
+    const cleanupFailure = new FakeSandbox()
+    cleanupFailure.backgroundError = new Error('start failed before credential consumption')
+    cleanupFailure.nextRemoveError = new Error('credential cleanup failed')
+    const cleanupHandle = new E2BSubprocessHandle(runtime(cleanupFailure), spec(), '/runtime/cleanup-failure')
+    await expect(cleanupHandle.done).rejects.toThrow('command failed and private state cleanup failed')
+
+    const absentState = new FakeSandbox()
+    absentState.backgroundError = new Error('start failed after external cleanup')
+    absentState.nextRemoveError = new FileNotFoundError('already removed')
+    const absentHandle = new E2BSubprocessHandle(runtime(absentState), spec(), '/runtime/absent-state')
+    await expect(absentHandle.done).rejects.toThrow('start failed after external cleanup')
   })
 
   it('bounds a readiness rejection with a still-live caller signal', async () => {
@@ -678,8 +909,20 @@ describe('E2BSubprocessHandle', () => {
     invalidPid.handle.pid = 0
     const invalid = new E2BSubprocessHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
     await expect(invalid.done).rejects.toThrow(/invalid command pid 0/)
+    expect(invalidPid.handle.kills).toBe(1)
+    expect(invalidPid.removed).toContain('/runtime/invalid-pid/environment')
     await expect(invalid.waitForExit()).resolves.toBe(true)
 
+    const failedRollback = new FakeSandbox()
+    failedRollback.handle.pid = 0
+    failedRollback.handle.killError = new Error('invalid handle kill failed')
+    const retained = new E2BSubprocessHandle(runtime(failedRollback), spec(), '/runtime/invalid-pid-retained')
+    await expect(retained.done).rejects.toThrow('invalid command pid rollback did not reach quiescence')
+    await expect(retained.waitForExit()).rejects.toThrow('invalid handle kill failed')
+    failedRollback.handle.killError = undefined
+    retained.terminate()
+    await expect(retained.waitForExit()).resolves.toBe(true)
+
     const crashedFake = new FakeSandbox()
     const crashed = new E2BSubprocessHandle(runtime(crashedFake), spec(), '/runtime/crashed')
     await flush()
@@ -692,6 +935,7 @@ describe('E2BSubprocessHandle', () => {
     const invalidGroup = new FakeSandbox()
     invalidGroup.processGroupId = 'not-a-pid\n'
     invalidGroup.delaysKill = true
+    invalidGroup.sdkKillStops = false
     invalidGroup.afterProbe = () => { invalidGroup.alive = false }
     const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
@@ -791,7 +1035,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
   })
 
-  it('contains an already-gone group signal and observes non-command signal failures', async () => {
+  it('contains an already-gone group signal and escalates after a TERM transport failure', async () => {
     const gone = new FakeSandbox()
     gone.trapsTerm = true
     gone.signalError = commandError(1)
@@ -805,9 +1049,35 @@ describe('E2BSubprocessHandle', () => {
     const failedHandle = new E2BSubprocessHandle(runtime(failed), spec(), '/runtime/failed-signal')
     await flush()
     failedHandle.terminate()
+    await expect(failedHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(failed.commandsSeen).toContain('kill -KILL -- -4242')
+  })
+
+  it('allows termination retry after both force transports fail', async () => {
+    const fake = new FakeSandbox()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry-signal')
     await flush()
-    failed.finish()
-    await expect(failedHandle.done).resolves.toEqual({ exitCode: 0, signal: null })
+
+    handle.terminate()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    fake.handle.killError = undefined
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -TERM '))).toHaveLength(2)
+
+    const missingGroup = new FakeSandbox()
+    missingGroup.trapsTerm = true
+    missingGroup.signalErrors.push(undefined, commandError(1))
+    missingGroup.handle.killError = new Error('SDK kill failed after group exit race')
+    const raced = new E2BSubprocessHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
+    await flush()
+    raced.terminate()
+    await expect(raced.waitForExit()).rejects.toThrow('force termination failed through both')
+    missingGroup.handle.killError = undefined
+    raced.terminate()
+    await expect(raced.waitForExit()).resolves.toBe(true)
   })
 })
 
@@ -833,6 +1103,23 @@ describe('E2BSubprocessService', () => {
     expect(fake.alive).toBe(false)
   })
 
+  it('reports a failed termination transaction from disposal instead of waiting on done', async () => {
+    const fake = new FakeSandbox()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec({ graceMs: 1 }))
+    await flush()
+
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+
+    fake.handle.killError = undefined
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
   it('releases naturally settled handles before later service disposal', async () => {
     const fake = new FakeSandbox()
     const { ctx, fiber } = await service(fake)
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index cefa432acd..bda01a5a61 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -95,6 +95,7 @@ class FakeTerminalSandbox {
   foreground = '456\n'
   groups = [123]
   createError: unknown
+  writeError: unknown
   sendError: unknown
   commandFailure: unknown
   sessionGroupsFailure: unknown
@@ -116,6 +117,7 @@ class FakeTerminalSandbox {
       },
       write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
         for (const file of files) this.writes.set(file.path, file.data)
+        if (this.writeError !== undefined) throw this.writeError
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => {
@@ -278,6 +280,20 @@ describe('E2B terminal allocation', () => {
   })
 
   it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
+    const failedState = new FakeTerminalSandbox()
+    failedState.writeError = new Error('state write failed')
+    await expect(spawnE2BTerminal(runtime(failedState), spec(), '/runtime/state-write'))
+      .rejects.toThrow('state write failed')
+    expect(failedState.writes.get('/runtime/state-write/environment')).toContain('KEEP=visible\0')
+    expect(failedState.removed).toContain('/runtime/state-write')
+    expect(failedState.createOptions).toBeUndefined()
+
+    const stateAlreadyGone = new FakeTerminalSandbox()
+    stateAlreadyGone.writeError = new Error('state write failed after external cleanup')
+    stateAlreadyGone.removeError = new FileNotFoundError('state already gone')
+    await expect(spawnE2BTerminal(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
+      .rejects.toThrow('state write failed after external cleanup')
+
     const invalidPid = new FakeTerminalSandbox()
     invalidPid.handle.pid = 0
     await expect(spawnE2BTerminal(runtime(invalidPid), spec(), '/runtime/invalid-pid'))

From e9bef2967dcd6c399637482f8cb1739cf90bf6e0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:07:31 +0800
Subject: [PATCH 114/262] fix(e2b): preserve signals after output drain

---
 packages/e2b/subprocess-e2b/src/process.ts    |  4 +++-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 22 ++++++++++++++++++-
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 3a8047eb54..473c1a0af4 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -512,7 +512,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
         await handle.disconnect()
-        return { exitCode, signal: null }
+        return this.terminationSignal === null
+          ? { exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
       }
       const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
       if (completed !== undefined) return this.commandOutcome(completed)
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index d81b49a600..457e68f24d 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -103,6 +103,7 @@ class FakeSandbox {
   readonly signalErrors: unknown[] = []
   trapsTerm = false
   delaysKill = false
+  delaysKillCompletion = false
   sdkKillStops = true
   alive = true
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
@@ -247,7 +248,7 @@ class FakeSandbox {
             throw error
           }
           if (!this.delaysKill) this.alive = false
-          this.handle.fail(137)
+          if (!this.delaysKillCompletion) this.handle.fail(137)
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if ((options as StartOptions | undefined)?.background === true) {
@@ -473,6 +474,25 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.disconnects).toBe(0)
   })
 
+  it('preserves a requested signal when output draining expires', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.delaysKill = true
+    fake.delaysKillCompletion = true
+    fake.sdkKillStops = false
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-signal')
+    await flush()
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.commandsSeen).toContain('kill -KILL -- -4242') })
+    fake.exitStatus = '143\n'
+
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(fake.handle.disconnects).toBe(1)
+    fake.alive = false
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
   it('rejects an invalid direct-command exit status', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')

From 022841027fb05a18c5567095d6fed88aebb9ad00 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:42:25 +0800
Subject: [PATCH 115/262] fix(e2b): fence teardown and terminal publication

---
 packages/e2b/e2b/tests/composition.e2e.ts     |  5 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  4 +-
 packages/e2b/subprocess-e2b/src/index.ts      | 42 +++++++--
 packages/e2b/subprocess-e2b/src/process.ts    |  4 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   | 82 ++++++++++++++++-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 25 ++++++
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 89 ++++++++++++++++++-
 9 files changed, 237 insertions(+), 22 deletions(-)

diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 1ece44bb6a..34875d5153 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -185,7 +185,10 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       oversizedReply: { error: { kind: 'worker-exit' } },
       lingeringCodeRunners: 0,
     })
-    expect((output.terminal as { motd: string }).motd.length).toBeGreaterThan(0)
+    const terminalMotd = (output.terminal as { motd: string }).motd
+    expect(terminalMotd.length).toBeGreaterThan(0)
+    expect(terminalMotd).not.toContain('exec /bin/bash')
+    expect(terminalMotd).not.toContain('.dsh-e2b/terminals/')
     expect((output.terminal as { echo: { viewport: string } }).echo.viewport).toContain('PTY-你好')
     expect((output.terminal as { scrollback: string }).scrollback).toContain('PTY-你好')
     expect((output.terminal as { signal: { targetPgid: number } }).signal.targetPgid).toBeGreaterThan(0)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 091a6972cf..2d20e4ad4c 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: b1aa480305fef9ca485340b6bdae50f9fcffd88f
-README.zh.md: b4824c90e7fb908d9c12e77c19d2b952055dcb40
+README.md: 03146e02cc76b78fbb93faec7d36d1865418b670
+README.zh.md: 6ed49a355586c6df2a594f83b687e6a565d07cf0
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index b1aa480305..fb3d79433f 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,10 +8,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while successful termination remains a permanent no-op. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers; after `graceMs`, the adapter disconnects an incomplete SDK stream, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Setup and teardown own the private state transaction, including failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, fence publication during service disposal, and include failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index b4824c90e7..ec012b6a05 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,10 +8,10 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；成功终止后，重复终止将永久为空操作。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态；超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。setup 与 teardown 负责私有状态事务，包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间阻止发布，并包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 27efb216da..fcf2c6f0a4 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -28,6 +28,8 @@ export class E2BSubprocessService extends SubprocessService {
 
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
+  private readonly terminalSetups = new Set<Promise<void>>()
+  private disposing = false
 
   /** @inheritdoc */
   readonly cwd: string
@@ -41,12 +43,17 @@ export class E2BSubprocessService extends SubprocessService {
     this.cwd = ctx.e2b.cwd
     this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
+      this.disposing = true
+      await Promise.all([...this.terminalSetups])
       const handles = [...this.live]
       const terminals = [...this.terminals]
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
-        pending.push(handle.waitForExit().then(() => { this.live.delete(handle) }))
+        pending.push(handle.waitForExit().then(async () => {
+          await handle.done.catch(() => undefined)
+          this.live.delete(handle)
+        }))
       }
       for (const terminal of terminals) {
         terminal.terminate()
@@ -89,6 +96,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
@@ -112,6 +120,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
@@ -123,14 +132,31 @@ export class E2BSubprocessService extends SubprocessService {
     }
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
-    const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
-    this.terminals.add(terminal)
-    const release = async (): Promise<void> => {
-      await terminal.waitForExit()
-      this.terminals.delete(terminal)
+    const setup = Promise.withResolvers<void>()
+    this.terminalSetups.add(setup.promise)
+    try {
+      const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
+      this.terminals.add(terminal)
+      if (this.isDisposing()) {
+        terminal.terminate()
+        await terminal.waitForExit()
+        this.terminals.delete(terminal)
+        throw new Error('subprocess-e2b: service disposed during terminal setup')
+      }
+      const release = async (): Promise<void> => {
+        await terminal.waitForExit()
+        this.terminals.delete(terminal)
+      }
+      void terminal.done.then(release, release).catch(() => {})
+      return terminal
+    } finally {
+      this.terminalSetups.delete(setup.promise)
+      setup.resolve()
     }
-    void terminal.done.then(release, release).catch(() => {})
-    return terminal
+  }
+
+  private isDisposing(): boolean {
+    return this.disposing
   }
 }
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 473c1a0af4..3038f312dc 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -213,6 +213,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private invalidHandleQuiescent = false
   private provisionalHandleQuiescent = false
   private terminationStarted = false
+  private terminationSucceeded = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
   private terminationSignal: NodeJS.Signals | null = null
@@ -264,13 +265,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationAttempt !== undefined) return
+    if (this.terminationSucceeded || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
     void attempt.then(
       () => {
+        this.terminationSucceeded = true
         this.terminationAttempt = undefined
       },
       (error: unknown) => {
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index fb8dac6f49..78668490d7 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -1,6 +1,7 @@
 /** E2B PTY allocation and process-session ownership for the subprocess seam. */
 
 import { Buffer } from 'node:buffer'
+import { randomUUID } from 'node:crypto'
 import { PassThrough } from 'node:stream'
 import { posix } from 'node:path'
 import {
@@ -28,11 +29,13 @@ const TERMINAL_RUNNER_SOURCE = [
   'dsh_state=$1',
   'mapfile -d \'\' -t dsh_env < "$dsh_state/environment"',
   'mapfile -d \'\' -t dsh_argv < "$dsh_state/argv"',
-  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/runner.bash"',
+  'dsh_output_marker=$(<"$dsh_state/output-marker")',
+  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/output-marker" "$dsh_state/runner.bash"',
   'if (( ${#dsh_argv[@]} == 0 )); then',
   "  printf 'terminal runner received empty argv\\n' >&2",
   '  exit 125',
   'fi',
+  'printf \'%s\' "$dsh_output_marker"',
   "printf 'ready\\n' > \"$dsh_state/ready\"",
   'exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"',
   '',
@@ -42,6 +45,7 @@ interface TerminalPaths {
   runner: string
   environment: string
   argv: string
+  outputMarker: string
   ready: string
 }
 
@@ -53,6 +57,73 @@ function delay(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
 
+class BootstrapOutputFilter {
+  readonly ready: Promise<void>
+
+  private readonly readyState = Promise.withResolvers<void>()
+  private pending = Buffer.alloc(0)
+  private published = false
+
+  constructor(
+    private readonly marker: Buffer,
+    private readonly output: PassThrough,
+  ) {
+    this.ready = this.readyState.promise
+  }
+
+  push(data: Uint8Array): void {
+    if (this.published) {
+      this.write(data)
+      return
+    }
+    const combined = Buffer.concat([this.pending, Buffer.from(data)])
+    const markerOffset = combined.indexOf(this.marker)
+    if (markerOffset < 0) {
+      const retained = Math.min(combined.length, this.marker.length - 1)
+      this.pending = Buffer.from(combined.subarray(combined.length - retained))
+      return
+    }
+    this.published = true
+    this.pending = Buffer.alloc(0)
+    this.readyState.resolve()
+    this.write(combined.subarray(markerOffset + this.marker.length))
+  }
+
+  private write(data: Uint8Array): void {
+    if (data.length > 0 && !this.output.destroyed) this.output.write(data)
+  }
+}
+
+async function waitForBootstrapOutput(
+  ready: Promise<void>,
+  completion: Promise<CommandResult>,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted()
+  await new Promise<void>((resolve, reject) => {
+    let settled = false
+    let removeAbort: (() => void) | undefined
+    const finish = (complete: () => void): void => {
+      if (settled) return
+      settled = true
+      removeAbort?.()
+      complete()
+    }
+    const onExit = (): void => {
+      finish(() => { reject(new Error('subprocess-e2b: terminal exited before publishing its output boundary')) })
+    }
+    if (signal !== undefined) {
+      const onAbort = (): void => {
+        finish(() => { reject(asError(signal.reason)) })
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+      removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+    }
+    void ready.then(() => { finish(resolve) })
+    void completion.then(onExit, onExit)
+  })
+}
+
 function asError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error))
 }
@@ -374,9 +445,12 @@ export async function spawnE2BTerminal(
     runner: posix.join(stateDir, 'runner.bash'),
     environment: posix.join(stateDir, 'environment'),
     argv: posix.join(stateDir, 'argv'),
+    outputMarker: posix.join(stateDir, 'output-marker'),
     ready: posix.join(stateDir, 'ready'),
   }
+  const outputMarker = Buffer.from(`dsh-e2b-bootstrap:${randomUUID()}`)
   const output = new PassThrough()
+  const outputFilter = new BootstrapOutputFilter(outputMarker, output)
   let handle: CommandHandle | undefined
   let completion: Promise<CommandResult> | undefined
   let stateDirectoryCreated = false
@@ -391,9 +465,10 @@ export async function spawnE2BTerminal(
       { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
       { path: paths.environment, data: environment },
       { path: paths.argv, data: argv },
+      { path: paths.outputMarker, data: outputMarker.toString('utf8') },
     ], signalOpts(spec.signal))
     await sandbox.commands.run(
-      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
+      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)} ${quoteE2BShellArg(paths.outputMarker)}`,
       signalOpts(spec.signal),
     )
     handle = await sandbox.pty.create({
@@ -403,7 +478,7 @@ export async function spawnE2BTerminal(
       envs: { TERM: 'dumb' },
       timeoutMs: 0,
       ...signalOpts(spec.signal),
-      onData: (data) => { if (!output.destroyed) output.write(Buffer.from(data)) },
+      onData: (data) => { outputFilter.push(data) },
     })
     completion = handle.wait()
     void completion.catch(() => {})
@@ -413,6 +488,7 @@ export async function spawnE2BTerminal(
     const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
     await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
     await waitUntilReady(sandbox, paths, completion, spec.signal)
+    await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
     const sessionId = await terminalSessionId(sandbox, handle.pid, spec.signal)
     return new E2BTerminalHandle(
       sandbox,
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 457e68f24d..be8850d905 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -599,6 +599,12 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
     expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
     expect(fake.commandsSeen).not.toContain('kill -KILL -- -4242')
+    const signals = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    fake.alive = true
+    handle.terminate()
+    await flush()
+    expect(fake.alive).toBe(true)
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
   })
 
   it('escalates a TERM-trapping process group to KILL and uses the SDK kill as fallback', async () => {
@@ -1123,6 +1129,24 @@ describe('E2BSubprocessService', () => {
     expect(fake.alive).toBe(false)
   })
 
+  it('awaits SDK settlement after the remote process group becomes quiescent', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec())
+    await flush()
+    fake.alive = false
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await flush()
+    expect(disposed).toBe(false)
+
+    fake.finish()
+    await disposing
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
   it('reports a failed termination transaction from disposal instead of waiting on done', async () => {
     const fake = new FakeSandbox()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
@@ -1178,6 +1202,7 @@ describe('E2BSubprocessService', () => {
     const { ctx, fiber } = await service(fake)
     const handle = ctx.subprocess.spawn(spec())
     const disposing = fiber.dispose()
+    expect(() => ctx.subprocess.spawn(spec())).toThrow('service is disposing')
     fake.releaseStart()
     await expect(disposing).resolves.toBeUndefined()
     await expect(handle.done).rejects.toThrow('start failed during disposal')
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index bda01a5a61..1eac9a5780 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -2,7 +2,7 @@ import { Buffer } from 'node:buffer'
 import { once } from 'node:events'
 import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import {
   CommandExitError,
   FileNotFoundError,
@@ -91,6 +91,7 @@ class FakeTerminalSandbox {
   ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   ready: string | Error = 'ready\n'
   readyMisses = 0
+  readyReads = 0
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
@@ -108,6 +109,20 @@ class FakeTerminalSandbox {
   settleOnPtyKill = true
   ptyKills = 0
   resolvedExecutable = '/usr/bin/node\n'
+  requestedOutput = 'requested-shell$ '
+  emitOutputMarker = true
+  private createGate: Promise<void> | undefined
+  private releaseCreateGate: (() => void) | undefined
+
+  deferCreate(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.createGate = gate.promise
+    this.releaseCreateGate = () => { gate.resolve(undefined) }
+  }
+
+  releaseCreate(): void {
+    this.releaseCreateGate?.()
+  }
 
   readonly sandbox = {
     files: {
@@ -121,6 +136,7 @@ class FakeTerminalSandbox {
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => {
+        this.readyReads += 1
         if (this.readyMisses > 0) {
           this.readyMisses -= 1
           throw new FileNotFoundError('not ready')
@@ -170,6 +186,7 @@ class FakeTerminalSandbox {
     pty: {
       create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
         this.createOptions = options
+        await this.createGate
         if (this.createError !== undefined) throw this.createError
         await options.onData(Buffer.from('buffered banner\n'))
         return this.handle.asHandle()
@@ -178,6 +195,17 @@ class FakeTerminalSandbox {
         options?.signal?.throwIfAborted()
         this.inputs.push({ pid, data: Buffer.from(data) })
         if (this.sendError !== undefined) throw this.sendError
+        if (this.emitOutputMarker && Buffer.from(data).includes(Buffer.from('runner.bash'))) {
+          const marker = [...this.writes].find(([path]) => path.endsWith('/output-marker'))?.[1]
+          const onData = this.createOptions?.onData
+          if (marker !== undefined && onData !== undefined) {
+            await onData(Buffer.from(Buffer.from(data).toString().replace(/\r$/, '\r\n')))
+            const split = Math.floor(marker.length / 2)
+            await onData(Buffer.from(marker.slice(0, split)))
+            await onData(Buffer.from(marker.slice(split)))
+            await onData(Buffer.from(this.requestedOutput))
+          }
+        }
       },
       kill: async (pid: number): Promise<boolean> => {
         this.ptyKills += 1
@@ -211,7 +239,7 @@ function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessT
 }
 
 describe('E2B terminal allocation', () => {
-  it('boots the requested argv through a private runner and preserves buffered bytes', async () => {
+  it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
     fake.readyMisses = 1
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
@@ -219,7 +247,9 @@ describe('E2B terminal allocation', () => {
     terminal.output.on('data', (chunk) => { output += String(chunk) })
     await new Promise(resolve => setTimeout(resolve, 0))
 
-    expect(output).toBe('buffered banner\n')
+    expect(output).toBe('requested-shell$ ')
+    expect(output).not.toContain('buffered banner')
+    expect(output).not.toContain('runner.bash')
     expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
     expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
@@ -227,10 +257,17 @@ describe('E2B terminal allocation', () => {
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
     expect(fake.writes.get('/runtime/terminal-one/argv')).toBe('/bin/bash\0--noprofile\0--norc\0')
+    const marker = fake.writes.get('/runtime/terminal-one/output-marker') ?? ''
+    expect(marker).toMatch(/^dsh-e2b-bootstrap:/)
+    expect(fake.inputs[0]?.data.toString()).not.toContain(marker)
     const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
     expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
+    expect(runner).toContain('printf \'%s\' "$dsh_output_marker"')
     expect(runner).toContain('exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"')
     expect(runner).not.toContain('\u007f')
+    terminal.output.destroy()
+    await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
+    expect(output).toBe('requested-shell$ ')
 
     await terminal.write(Buffer.from('echo ok\r'))
     expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
@@ -395,6 +432,29 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(readFailed), spec(), '/runtime/read'))
       .rejects.toThrow('ready transport failed')
   })
+
+  it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
+    const exited = new FakeTerminalSandbox()
+    exited.emitOutputMarker = false
+    const exiting = spawnE2BTerminal(runtime(exited), spec(), '/runtime/missing-output-boundary')
+    await vi.waitFor(() => { expect(exited.inputs).toHaveLength(1) })
+    exited.handle.succeed(0)
+    await expect(exiting).rejects.toThrow('terminal exited before publishing its output boundary')
+
+    const cancelled = new FakeTerminalSandbox()
+    cancelled.emitOutputMarker = false
+    const controller = new AbortController()
+    const cancelling = spawnE2BTerminal(
+      runtime(cancelled),
+      spec({ signal: controller.signal }),
+      '/runtime/cancel-output-boundary',
+    )
+    await vi.waitFor(() => { expect(cancelled.inputs).toHaveLength(1) })
+    await vi.waitFor(() => { expect(cancelled.readyReads).toBeGreaterThan(0) })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    controller.abort(new Error('cancel output boundary'))
+    await expect(cancelling).rejects.toThrow('cancel output boundary')
+  })
 })
 
 describe('E2B terminal lifecycle', () => {
@@ -637,6 +697,29 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.handle.disconnects).toBe(1)
   })
 
+  it('joins and rejects terminal setup that completes during service disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.deferCreate()
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
+
+    let disposed = false
+    const subprocess = ctx.subprocess
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(disposed).toBe(false)
+    await expect(subprocess.spawnTerminal(spec())).rejects.toThrow('service is disposing')
+    fake.releaseCreate()
+
+    await rejected
+    await disposing
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+    expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
+  })
+
   it('releases naturally settled terminals and validates terminal requests', async () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [

From ed5d21277faa85ad97cf4fbe17ee62e3ca1bfdb8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:05:37 +0800
Subject: [PATCH 116/262] test(e2b): observe disposal before spawn fence

---
 packages/e2b/subprocess-e2b/tests/subprocess.spec.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index be8850d905..8e6e420bcc 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -1200,9 +1200,11 @@ describe('E2BSubprocessService', () => {
     fake.deferStart()
     fake.backgroundError = new Error('start failed during disposal')
     const { ctx, fiber } = await service(fake)
-    const handle = ctx.subprocess.spawn(spec())
+    const subprocess = ctx.subprocess
+    const handle = subprocess.spawn(spec())
     const disposing = fiber.dispose()
-    expect(() => ctx.subprocess.spawn(spec())).toThrow('service is disposing')
+    await flush()
+    expect(() => subprocess.spawn(spec())).toThrow('service is disposing')
     fake.releaseStart()
     await expect(disposing).resolves.toBeUndefined()
     await expect(handle.done).rejects.toThrow('start failed during disposal')

From f5306f6e898c797900c66d1441ce0f7729007732 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:06:02 +0800
Subject: [PATCH 117/262] docs(e2b): record subprocess teardown contract

---
 packages/e2b/subprocess-e2b/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 2d20e4ad4c..3a577227f8 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 03146e02cc76b78fbb93faec7d36d1865418b670
-README.zh.md: 6ed49a355586c6df2a594f83b687e6a565d07cf0
+README.md: fb3d79433fba8bb86097cffb09a257ad5756cc2b
+README.zh.md: ec012b6a05c1a5f911d5ede9730f0f7207d5a645

From 219999cd2f3e0abf3878d354de3bf42cfc2e6134 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:19:46 +0800
Subject: [PATCH 118/262] fix(e2b): close adapter lifecycle review gaps

---
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   2 +-
 packages/e2b/fs-e2b/README.zh.md              |   2 +-
 packages/e2b/fs-e2b/src/index.ts              |  24 ++-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |  33 +++-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  10 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  10 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  20 +++
 packages/e2b/subprocess-e2b/src/index.ts      |  25 ++-
 packages/e2b/subprocess-e2b/src/process.ts    |  67 +++++---
 packages/e2b/subprocess-e2b/src/terminal.ts   |  61 ++++----
 .../subprocess-e2b/tests/subprocess.spec.ts   | 146 +++++++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  70 ++++++---
 14 files changed, 375 insertions(+), 103 deletions(-)

diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 6e45ccaaf6..3c2b30ad15 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 86ad8720d3e4c7ce70ee0ac8c41713af03ed297a
-README.zh.md: 90dff57a5b9fe786aea3315633125536277ecc20
+README.md: 8abf130ce16e2b79cda5fc858182159442f9e3c3
+README.zh.md: 943d9603046ad9b2a65f41d5801cac882040a0ff
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 86ad8720d3..8abf130ce1 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -10,7 +10,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
 - **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
-- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through E2B's same-directory atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 90dff57a5b..943d960304 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -10,7 +10,7 @@
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
 - **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
-- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 2452e856ca..0824c3f87c 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -498,8 +498,15 @@ export class E2BFileSystem extends FileSystem {
     const sandbox = await this.ctx.e2b.getSandbox()
     const targetPath = String(target.targetKey)
     const versionId = randomUUID()
-    const temporary = posix.join(posix.dirname(targetPath), `.${posix.basename(targetPath)}.dsh-${randomUUID()}.tmp`)
+    const stagingDirectory = posix.join(posix.dirname(targetPath), `.dsh-${randomUUID()}.tmp`)
+    const temporary = posix.join(stagingDirectory, 'content')
+    let stagingDirectoryCreated = false
     try {
+      const created = await sandbox.files.makeDir(stagingDirectory, signalOpts(signal))
+      if (!created) throw new Error('private staging directory already exists')
+      stagingDirectoryCreated = true
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, signalOpts(signal))
+      assertNotAborted(signal, 'write')
       await sandbox.files.write(temporary, content, {
         metadata: { [VERSION_METADATA_KEY]: versionId },
         ...signalOpts(signal),
@@ -512,12 +519,19 @@ export class E2BFileSystem extends FileSystem {
       )
       assertNotAborted(signal, 'write')
       const committed = await sandbox.files.rename(temporary, targetPath, signalOpts(signal))
+      try {
+        await sandbox.files.remove(stagingDirectory)
+      } catch (_committedStagingCleanupFailure) {
+        // The target is already committed; an empty private directory cannot turn that write into a failure.
+      }
       return entryVersion(committed)
     } catch (error: unknown) {
-      try {
-        await sandbox.files.remove(temporary)
-      } catch (_temporaryAlreadyAbsent) {
-        // Only the private staging path is swallowed; the original failure owns the operation.
+      if (stagingDirectoryCreated) {
+        try {
+          await sandbox.files.remove(stagingDirectory)
+        } catch (_stagingDirectoryAlreadyAbsentOrCleanupFailed) {
+          // Only the private staging directory is swallowed; the original failure owns the operation.
+        }
       }
       throw mapError(error, 'write', target.displayPath, signal)
     }
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 648631c7ee..303f99c1e8 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -35,6 +35,7 @@ function commandError(exitCode: number, stderr = ''): CommandExitError {
 class FakeRemote {
   readonly nodes = new Map<string, RemoteNode>()
   readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
+  readonly writeParentModes: number[] = []
   readonly renames: Array<{ from: string; to: string }> = []
   readonly removals: string[] = []
   readonly commands: string[] = []
@@ -42,6 +43,7 @@ class FakeRemote {
   streamKeepOpen = false
   readonly streamCancel = vi.fn()
   nextCommandError: unknown
+  nextMakeDirResult: boolean | undefined
   nextInfoError: unknown
   nextListError: unknown
   nextReadError: unknown
@@ -130,7 +132,13 @@ class FakeRemote {
   readonly sandbox = {
     sandboxId: 'fake',
     files: {
-      makeDir: async (path: string): Promise<boolean> => {
+      makeDir: async (path: string, options?: { signal?: AbortSignal }): Promise<boolean> => {
+        this.checkAbort(options)
+        if (this.nextMakeDirResult !== undefined) {
+          const result = this.nextMakeDirResult
+          this.nextMakeDirResult = undefined
+          return result
+        }
         if (this.nodes.has(path)) return false
         this.dir(path)
         return true
@@ -178,6 +186,7 @@ class FakeRemote {
         this.checkAbort(options)
         const parent = dirname(path)
         if (!this.nodes.has(parent)) this.dir(parent)
+        this.writeParentModes.push(this.required(parent).mode)
         this.nodes.set(path, {
           type: FileType.FILE,
           data: bytes(data),
@@ -209,7 +218,9 @@ class FakeRemote {
           this.nextRemoveError = undefined
           throw error
         }
-        this.nodes.delete(path)
+        for (const candidate of this.nodes.keys()) {
+          if (candidate === path || candidate.startsWith(`${path}/`)) this.nodes.delete(candidate)
+        }
       },
     },
     commands: {
@@ -499,6 +510,10 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(outcome).toMatchObject({ operation: 'create', before: null, after: 'one\ntwo\rthree' })
     expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
     expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
+    expect(remote.writeParentModes).toEqual([0o700])
+    const stagingDirectory = posix.dirname(remote.writes[0]!.path)
+    expect(posix.dirname(stagingDirectory)).toBe('/workspace')
+    expect(remote.removals).toContain(stagingDirectory)
     await expect(fs.stat(target)).resolves.toMatchObject({ version: outcome.version, size: 14 })
   })
 
@@ -558,6 +573,15 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(controller.signal.aborted).toBe(true)
   })
 
+  it('does not turn post-commit staging cleanup failure into a failed write', async () => {
+    const remote = new FakeRemote()
+    remote.nextRemoveError = new Error('empty staging cleanup failed')
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes'))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/committed')?.data)).toBe('yes')
+  })
+
   it('returns committed rename metadata without a fallible post-commit lookup', async () => {
     const remote = new FakeRemote()
     const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
@@ -582,6 +606,11 @@ describe('E2BFileSystem atomic writes and edits', () => {
     remote.nextRemoveError = new Error('cleanup also failed')
     remote.nextRenameError = new DOMException('aborted', 'AbortError')
     await expectCode(fs.writeText(await fs.resolve('abort'), 'x'), 'FS_ABORTED')
+
+    const removalsBeforeCollision = remote.removals.length
+    remote.nextMakeDirResult = false
+    await expectCode(fs.writeText(await fs.resolve('collision'), 'x'), 'FS_IO_ERROR')
+    expect(remote.removals).toHaveLength(removalsBeforeCollision)
   })
 
   it('applies literal edits atomically and restores the detected CRLF style', async () => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 3a577227f8..41d964a58a 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: fb3d79433fba8bb86097cffb09a257ad5756cc2b
-README.zh.md: ec012b6a05c1a5f911d5ede9730f0f7207d5a645
+README.md: 42cd4951edb101dc75980e114e704c4aab50ae25
+README.zh.md: c4b318184cb7616a378e3336f4f4a7c366a98807
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index fb3d79433f..42cd4951ed 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,10 +8,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while successful termination remains a permanent no-op. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
-- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers; after `graceMs`, the adapter disconnects an incomplete SDK stream, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, fence publication during service disposal, and include failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination; raw pipes instead await lossless transport completion and preserve backpressure. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
@@ -29,6 +29,6 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
-- **E2B exposes no signal fact** — only an adapter-requested `SIGTERM` or `SIGKILL` is reported as a signal; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
+- **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
 - **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index ec012b6a05..c4b318184c 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,10 +8,10 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；成功终止后，重复终止将永久为空操作。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
-- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态；超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间阻止发布，并包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用；原始 pipe 则会等待无损传输完成并保留背压。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
@@ -29,6 +29,6 @@
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
-- **E2B 不公开信号事实**：只有适配器请求的 `SIGTERM` 或 `SIGKILL` 会报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
+- **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
 - **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index cc9b41296a..f9c30d378f 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -19,3 +19,23 @@ export function scrubRemoteEnvironment(raw: string): Map<string, string> {
   }
   return environment
 }
+
+/**
+ * Overlay explicit entries and serialize one validated E2B environment.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @param explicit - Deliberate caller overrides applied after ambient scrubbing.
+ * @returns NUL-delimited `name=value` entries accepted by `env -i`.
+ */
+export function serializeRemoteEnvironment(
+  raw: string,
+  explicit: Readonly<Record<string, string>> | undefined,
+): string {
+  const environment = scrubRemoteEnvironment(raw)
+  for (const [name, value] of Object.entries(explicit ?? {})) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+      throw new Error('subprocess-e2b: environment entries require non-empty NUL-free names without = and NUL-free values')
+    }
+    environment.set(name, value)
+  }
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
+}
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index fcf2c6f0a4..bf7edc41a1 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -28,7 +28,8 @@ export class E2BSubprocessService extends SubprocessService {
 
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
-  private readonly terminalSetups = new Set<Promise<void>>()
+  private readonly terminalSetups = new Map<Promise<void>, AbortController>()
+  private readonly failedTerminalSetupCleanups = new Set<() => Promise<void>>()
   private disposing = false
 
   /** @inheritdoc */
@@ -44,9 +45,13 @@ export class E2BSubprocessService extends SubprocessService {
     this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
       this.disposing = true
-      await Promise.all([...this.terminalSetups])
+      for (const controller of this.terminalSetups.values()) {
+        controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
+      }
+      await Promise.all([...this.terminalSetups.keys()])
       const handles = [...this.live]
       const terminals = [...this.terminals]
+      const failedTerminalSetupCleanups = [...this.failedTerminalSetupCleanups]
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
@@ -59,6 +64,9 @@ export class E2BSubprocessService extends SubprocessService {
         terminal.terminate()
         pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
+      for (const cleanup of failedTerminalSetupCleanups) {
+        pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
+      }
       await Promise.all(pending)
     }, 'e2b subprocess teardown')
   }
@@ -133,9 +141,18 @@ export class E2BSubprocessService extends SubprocessService {
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
     const setup = Promise.withResolvers<void>()
-    this.terminalSetups.add(setup.promise)
+    const setupController = new AbortController()
+    const setupSignal = spec.signal === undefined
+      ? setupController.signal
+      : AbortSignal.any([spec.signal, setupController.signal])
+    this.terminalSetups.set(setup.promise, setupController)
     try {
-      const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
+      const terminal = await spawnE2BTerminal(
+        this.ctx.e2b,
+        { ...spec, signal: setupSignal },
+        stateDir,
+        (cleanup) => { this.failedTerminalSetupCleanups.add(cleanup) },
+      )
       this.terminals.add(terminal)
       if (this.isDisposing()) {
         terminal.terminate()
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 3038f312dc..4855b27b81 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -17,7 +17,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { scrubRemoteEnvironment } from './environment.ts'
+import { serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -92,12 +92,6 @@ function withinMs<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefi
   })
 }
 
-function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = scrubRemoteEnvironment(raw)
-  for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
-  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
-}
-
 function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   const encoder = `"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e ${quoteE2BShellArg(OUTPUT_ENCODER_SOURCE)}`
   const stdoutRedirect = hasSpill(spec.stdio.stdout)
@@ -213,7 +207,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private invalidHandleQuiescent = false
   private provisionalHandleQuiescent = false
   private terminationStarted = false
-  private terminationSucceeded = false
+  private terminationFenced = false
+  private quiescenceProven = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
   private terminationSignal: NodeJS.Signals | null = null
@@ -265,18 +260,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationSucceeded || this.terminationAttempt !== undefined) return
+    if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
     void attempt.then(
       () => {
-        this.terminationSucceeded = true
+        this.terminationFenced = true
         this.terminationAttempt = undefined
       },
       (error: unknown) => {
-        this.terminationFailure = asError(error)
+        if (!this.quiescenceProven) this.terminationFailure = asError(error)
         this.terminationAttempt = undefined
       },
     )
@@ -284,17 +279,24 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    if (this.quiescenceProven) return true
     let handle: CommandHandle | undefined
     if (this.terminationStarted) {
       const observed = await waitWithSignal(this.commandState.promise, signal)
       if (observed === WAIT_ABORTED) return false
       handle = observed
-      if (handle === undefined) return true
+      if (handle === undefined) {
+        this.markQuiescent()
+        return true
+      }
       if (this.remotePid <= 0) {
         const attempt = this.terminationAttempt
         if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
         this.throwTerminationFailure()
-        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) return true
+        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) {
+          this.markQuiescent()
+          return true
+        }
       }
     } else {
       try {
@@ -303,7 +305,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         handle = observed
       } catch {
         handle = this.commandHandle
-        if (handle === undefined) return true
+        if (handle === undefined) {
+          this.markQuiescent()
+          return true
+        }
       }
     }
     this.throwTerminationFailure()
@@ -320,11 +325,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!await waitTick(signal)) return false
     }
     this.throwTerminationFailure()
-    return !isAborted(signal)
+    if (isAborted(signal)) return false
+    this.markQuiescent()
+    return true
   }
 
   private readonly onAbort = (): void => { this.terminate() }
 
+  private markQuiescent(): void {
+    this.quiescenceProven = true
+    this.terminationFailure = undefined
+  }
+
   private async run(): Promise<SubprocessOutcome> {
     let sandbox: Sandbox | undefined
     try {
@@ -385,7 +397,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       return outcome
     } catch (error: unknown) {
       this.commandState.resolve(undefined)
-      let failure = error
+      let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
           await this.removeFailedState(sandbox)
@@ -413,7 +425,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
-      { path: this.paths.environment, data: remoteEnvironment(ambient.stdout, this.spec.env) },
+      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient.stdout, this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
@@ -508,15 +520,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
           throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
         }
+        if (this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe') {
+          return this.commandOutcome(await settlement)
+        }
         const completed = await withinMs(settlement, this.spec.graceMs)
         if (completed !== undefined) return this.commandOutcome(completed)
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
         await handle.disconnect()
-        return this.terminationSignal === null
-          ? { exitCode, signal: null }
-          : { exitCode: null, signal: this.terminationSignal }
+        return { exitCode, signal: null }
       }
       const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
       if (completed !== undefined) return this.commandOutcome(completed)
@@ -533,6 +546,20 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     throw settlement.error
   }
 
+  private async rollbackPublishedFailure(error: unknown): Promise<unknown> {
+    if (this.remotePid <= 0 || this.commandHandle === undefined || this.quiescenceProven) return error
+    this.terminate()
+    try {
+      await this.waitForExit()
+      return error
+    } catch (cleanupError: unknown) {
+      return new AggregateError(
+        [asError(error), asError(cleanupError)],
+        'subprocess-e2b: command monitoring failed and process-group rollback did not reach quiescence',
+      )
+    }
+  }
+
   private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
     // The bootstrap ends in an exec chain through the scrubbed environment and
     // `setsid`, so E2B's command PID is the provisional group id even before the
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 78668490d7..0f5809fa44 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -19,7 +19,7 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { scrubRemoteEnvironment } from './environment.ts'
+import { serializeRemoteEnvironment } from './environment.ts'
 
 const POLL_MS = 20
 
@@ -142,17 +142,6 @@ function serializeValues(values: readonly string[], kind: string): string {
   return values.map(value => `${value}\0`).join('')
 }
 
-function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = scrubRemoteEnvironment(raw)
-  for (const [name, value] of Object.entries(explicit ?? {})) {
-    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
-      throw new Error('subprocess-e2b: terminal environment entries require non-empty NUL-free names without = and NUL-free values')
-    }
-    environment.set(name, value)
-  }
-  return serializeValues([...environment].map(([name, value]) => `${name}=${value}`), 'environment')
-}
-
 async function terminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
   const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, signalOpts(signal))
   signal?.throwIfAborted()
@@ -432,12 +421,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
  * @param runtime - Shared E2B sandbox owner.
  * @param spec - Fully specified terminal-process request.
  * @param stateDir - Private remote directory for one startup transaction.
+ * @param retainFailedCleanup - Optional owner for retrying a cleanup transaction that could not prove quiescence.
  * @returns The live subprocess terminal handle.
  */
 export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
+  retainFailedCleanup?: (cleanup: () => Promise<void>) => void,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
@@ -456,7 +447,7 @@ export async function spawnE2BTerminal(
   let stateDirectoryCreated = false
   try {
     const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
-    const environment = remoteEnvironment(ambient.stdout, spec.env)
+    const environment = serializeRemoteEnvironment(ambient.stdout, spec.env)
     const argv = serializeValues(spec.argv, 'argv')
     await sandbox.files.makeDir(stateDir)
     stateDirectoryCreated = true
@@ -502,25 +493,37 @@ export async function spawnE2BTerminal(
     )
   } catch (error: unknown) {
     output.destroy()
-    const cleanupErrors: Error[] = []
-    if (handle !== undefined && completion !== undefined) {
-      try {
-        await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
-      } catch (rollbackError: unknown) {
-        cleanupErrors.push(asError(rollbackError))
+    let terminalQuiescent = handle === undefined
+    let stateRemoved = !stateDirectoryCreated
+    const retryCleanup = async (): Promise<void> => {
+      const failures: Error[] = []
+      if (!terminalQuiescent && handle !== undefined) {
+        try {
+          if (completion === undefined) await handle.kill()
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
+          terminalQuiescent = true
+        } catch (cleanupError: unknown) {
+          failures.push(asError(cleanupError))
+        }
       }
-    } else if (handle !== undefined) {
-      await handle.kill().catch(() => false)
-    }
-    if (stateDirectoryCreated) {
-      try {
-        await sandbox.files.remove(stateDir)
-      } catch (stateError: unknown) {
-        if (!(stateError instanceof FileNotFoundError)) cleanupErrors.push(asError(stateError))
+      if (!stateRemoved) {
+        try {
+          await sandbox.files.remove(stateDir)
+          stateRemoved = true
+        } catch (stateError: unknown) {
+          if (stateError instanceof FileNotFoundError) stateRemoved = true
+          else failures.push(asError(stateError))
+        }
+      }
+      if (failures.length > 0) {
+        throw new AggregateError(failures, 'subprocess-e2b: terminal setup cleanup did not complete')
       }
     }
-    if (cleanupErrors.length > 0) {
-      throw new AggregateError([asError(error), ...cleanupErrors], asError(error).message)
+    try {
+      await retryCleanup()
+    } catch (cleanupError: unknown) {
+      retainFailedCleanup?.(retryCleanup)
+      throw new AggregateError([asError(error), asError(cleanupError)], asError(error).message)
     }
     throw error
   }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 8e6e420bcc..462e943a1b 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -97,6 +97,7 @@ class FakeSandbox {
   startOptions: StartOptions | undefined
   backgroundError: unknown
   envError: unknown
+  statusError: unknown
   nextRemoveError: unknown
   probeError: unknown
   signalError: unknown
@@ -117,6 +118,8 @@ class FakeSandbox {
   private openStart: (() => void) | undefined
   private processGroupReadGate: Promise<void> | undefined
   private openProcessGroupRead: (() => void) | undefined
+  private signalGate: Promise<void> | undefined
+  private openSignal: (() => void) | undefined
 
   constructor() {
     this.handle = new FakeCommandHandle(() => {
@@ -147,6 +150,16 @@ class FakeSandbox {
     this.openProcessGroupRead?.()
   }
 
+  deferSignals(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.signalGate = gate.promise
+    this.openSignal = () => { gate.resolve(undefined) }
+  }
+
+  releaseSignals(): void {
+    this.openSignal?.()
+  }
+
   finish(exitCode = 0): void {
     this.alive = false
     void this.completeOutput().then(
@@ -198,6 +211,11 @@ class FakeSandbox {
           await this.processGroupReadGate
           return this.processGroupReads.shift() ?? this.processGroupId
         }
+        if (this.statusError !== undefined) {
+          const error = this.statusError
+          this.statusError = undefined
+          throw error
+        }
         this.afterStatusRead?.()
         return this.exitStatus
       },
@@ -230,6 +248,7 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -TERM ')) {
+          await this.signalGate
           const error = this.signalErrors.shift() ?? this.signalError
           if (error !== undefined) {
             if (this.signalErrors.length === 0) this.signalError = undefined
@@ -242,6 +261,7 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -KILL ')) {
+          await this.signalGate
           const error = this.signalErrors.shift() ?? this.signalError
           if (error !== undefined) {
             if (this.signalErrors.length === 0) this.signalError = undefined
@@ -399,6 +419,16 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('rejects malformed environment entries before command start', async () => {
+    for (const env of [{ 'BAD=NAME': 'x' }, { BAD: 'x\0INJECTED=1' }]) {
+      const fake = new FakeSandbox()
+      const handle = new E2BSubprocessHandle(runtime(fake), spec({ env }), '/runtime/invalid-environment')
+      await expect(handle.done).rejects.toThrow('environment entries')
+      expect(fake.startOptions).toBeUndefined()
+      expect(fake.removed).toContain('/runtime/invalid-environment')
+    }
+  })
+
   it('preserves UTF-8 bytes when the ASCII transport is split across callbacks', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
@@ -460,6 +490,29 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('waits for lossless raw-pipe output after the direct status is published', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      graceMs: 1,
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/pipe-drain')
+    let output = ''
+    handle.stdout!.on('data', (chunk) => { output += String(chunk) })
+    await flush()
+    fake.exitStatus = '0\n'
+
+    let settled = false
+    void handle.done.then(() => { settled = true })
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(settled).toBe(false)
+    expect(fake.handle.disconnects).toBe(0)
+
+    await fake.stdout('complete protocol frame')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(output).toBe('complete protocol frame')
+  })
+
   it('accepts clean encoder completion inside the output-drain grace', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
@@ -474,7 +527,7 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.disconnects).toBe(0)
   })
 
-  it('preserves a requested signal when output draining expires', async () => {
+  it('preserves a published exit code when requested termination outlives output draining', async () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
     fake.delaysKill = true
@@ -485,9 +538,9 @@ describe('E2BSubprocessHandle', () => {
 
     handle.terminate()
     await vi.waitFor(() => { expect(fake.commandsSeen).toContain('kill -KILL -- -4242') })
-    fake.exitStatus = '143\n'
+    fake.exitStatus = '0\n'
 
-    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(fake.handle.disconnects).toBe(1)
     fake.alive = false
     await expect(handle.waitForExit()).resolves.toBe(true)
@@ -503,6 +556,31 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('rolls back a published process group before rejecting a monitoring failure', async () => {
+    const fake = new FakeSandbox()
+    fake.statusError = new Error('status transport failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/status-failure')
+
+    await expect(handle.done).rejects.toThrow('status transport failed')
+    expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
+    expect(fake.alive).toBe(false)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    const failed = new FakeSandbox()
+    failed.statusError = new Error('status transport failed')
+    failed.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    failed.handle.killError = new Error('SDK kill failed')
+    const retained = new E2BSubprocessHandle(runtime(failed), spec({ graceMs: 1 }), '/runtime/status-cleanup-failure')
+
+    await expect(retained.done).rejects.toThrow(
+      'command monitoring failed and process-group rollback did not reach quiescence',
+    )
+    expect(failed.alive).toBe(true)
+    failed.handle.killError = undefined
+    retained.terminate()
+    await expect(retained.waitForExit()).resolves.toBe(true)
+  })
+
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
@@ -607,6 +685,46 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
   })
 
+  it('makes termination a permanent no-op after natural quiescence is observed', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/natural-quiescence')
+    await flush()
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    const signals = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    fake.alive = true
+    handle.terminate()
+    await flush()
+    expect(fake.alive).toBe(true)
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
+  it('keeps proven quiescence after a concurrent termination transport fails', async () => {
+    const fake = new FakeSandbox()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    fake.deferSignals()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/quiescent-race')
+    await flush()
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.commandsSeen).toContain('kill -TERM -- -4242') })
+    fake.alive = false
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    fake.probeError = new Error('post-quiescence probe failed')
+    fake.releaseSignals()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    const signals = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
   it('escalates a TERM-trapping process group to KILL and uses the SDK kill as fallback', async () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
@@ -620,6 +738,28 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.kills).toBe(1)
   })
 
+  it('does not treat successful termination transport as observed quiescence', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.delaysKill = true
+    fake.delaysKillCompletion = true
+    fake.sdkKillStops = false
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/termination-fence')
+    await flush()
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+
+    let quiescent = false
+    const waiting = handle.waitForExit().then((value) => { quiescent = value })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(quiescent).toBe(false)
+
+    fake.alive = false
+    fake.finish()
+    await waiting
+    expect(quiescent).toBe(true)
+  })
+
   it('honors termination requested before asynchronous startup finishes', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 1eac9a5780..e77646e586 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -111,18 +111,7 @@ class FakeTerminalSandbox {
   resolvedExecutable = '/usr/bin/node\n'
   requestedOutput = 'requested-shell$ '
   emitOutputMarker = true
-  private createGate: Promise<void> | undefined
-  private releaseCreateGate: (() => void) | undefined
-
-  deferCreate(): void {
-    const gate = Promise.withResolvers<undefined>()
-    this.createGate = gate.promise
-    this.releaseCreateGate = () => { gate.resolve(undefined) }
-  }
-
-  releaseCreate(): void {
-    this.releaseCreateGate?.()
-  }
+  afterSessionLookup: (() => void) | undefined
 
   readonly sandbox = {
     files: {
@@ -163,7 +152,10 @@ class FakeTerminalSandbox {
         if (command.includes('command -v -- ')) {
           return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
         }
-        if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        if (command.startsWith('ps -o sid=')) {
+          this.afterSessionLookup?.()
+          return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        }
         if (command.startsWith('ps -o tpgid=')) {
           if (this.foregroundFailure !== undefined) throw this.foregroundFailure
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
@@ -186,7 +178,6 @@ class FakeTerminalSandbox {
     pty: {
       create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
         this.createOptions = options
-        await this.createGate
         if (this.createError !== undefined) throw this.createError
         await options.onData(Buffer.from('buffered banner\n'))
         return this.handle.asHandle()
@@ -691,7 +682,7 @@ describe('E2B subprocess terminal service', () => {
 
   it('owns live terminals through service disposal', async () => {
     const { ctx, fiber, fake } = await service()
-    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    const terminal = await ctx.subprocess.spawnTerminal(spec({ signal: new AbortController().signal }))
     await fiber.dispose()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
     expect(fake.handle.disconnects).toBe(1)
@@ -699,19 +690,19 @@ describe('E2B subprocess terminal service', () => {
 
   it('joins and rejects terminal setup that completes during service disposal', async () => {
     const fake = new FakeTerminalSandbox()
-    fake.deferCreate()
     const { ctx, fiber } = await service(fake)
+    let disposing: Promise<void> | undefined
+    fake.afterSessionLookup = () => {
+      fake.afterSessionLookup = undefined
+      queueMicrotask(() => {
+        queueMicrotask(() => { disposing = fiber.dispose() })
+      })
+    }
+    const subprocess = ctx.subprocess
     const spawning = ctx.subprocess.spawnTerminal(spec())
     const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
-    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
-
-    let disposed = false
-    const subprocess = ctx.subprocess
-    const disposing = fiber.dispose().then(() => { disposed = true })
-    await new Promise(resolve => setTimeout(resolve, 0))
-    expect(disposed).toBe(false)
+    await vi.waitFor(() => { expect(disposing).toBeDefined() })
     await expect(subprocess.spawnTerminal(spec())).rejects.toThrow('service is disposing')
-    fake.releaseCreate()
 
     await rejected
     await disposing
@@ -720,6 +711,37 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
   })
 
+  it('aborts and rolls back terminal setup that cannot publish readiness during disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.ready = new FileNotFoundError('not ready')
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.readyReads).toBeGreaterThan(0) })
+
+    await fiber.dispose()
+    await rejected
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('retains failed terminal setup cleanup for disposal retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.sendError = new Error('bootstrap failed')
+    fake.clearOnTerm = false
+    fake.clearOnKill = false
+    const { ctx, fiber } = await service(fake)
+
+    await expect(ctx.subprocess.spawnTerminal(spec({ graceMs: 1 }))).rejects.toThrow('bootstrap failed')
+    expect(fake.groups).toEqual([123])
+    expect(fake.handle.disconnects).toBe(0)
+
+    fake.clearOnKill = true
+    await fiber.dispose()
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
   it('releases naturally settled terminals and validates terminal requests', async () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [

From d0648446c97e426c53deefe7d41cc25b1016bbaa Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:54:14 +0800
Subject: [PATCH 119/262] fix(e2b): close final lifecycle gaps

---
 packages/e2b/e2b/README.i18n.yaml             |  4 +-
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/src/index.ts                 | 17 +++++++--
 packages/e2b/e2b/tests/e2b.spec.ts            | 22 ++++++++++-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  4 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 17 +++++----
 packages/e2b/subprocess-e2b/src/terminal.ts   |  2 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 38 +++++++++++++++++--
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 22 ++++++++++-
 12 files changed, 111 insertions(+), 27 deletions(-)

diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index d8f1dcdc3f..46ff37b222 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 01c7ade2f5f31e34091ad0ae910287e659f15549
-README.zh.md: fb95a12cbbbd431ccb3283a14bb63b324f9bdea6
+README.md: ccafa9df480e3812d3d3b6d25b513e7b5d2afc9f
+README.zh.md: 60eefd46a0a9a017f4db57e4dc5313d533eeba04
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 01c7ade2f5..ccafa9df48 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -30,7 +30,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
 `pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index fb95a12cbb..60eefd46a0 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -30,7 +30,7 @@
 
 构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 `pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 2c0b3c635c..31e4f911a2 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -120,6 +120,7 @@ export class E2BSandboxService extends Service {
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
+  private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
   constructor(ctx: Context, config: Config) {
@@ -155,8 +156,16 @@ export class E2BSandboxService extends Service {
       try {
         sandbox = await this.ready
       } catch {
-        // Connection creation already failed and is exposed by getSandbox();
-        // there is no remote resource for teardown to own.
+        const failedSetupSandbox = this.failedSetupSandbox
+        if (failedSetupSandbox === undefined) return
+        sandbox = failedSetupSandbox
+        try {
+          await sandbox.kill()
+          this.failedSetupSandbox = undefined
+        } catch (error: unknown) {
+          if (!(error instanceof SandboxNotFoundError)) throw error
+          this.failedSetupSandbox = undefined
+        }
         return
       }
       try {
@@ -243,7 +252,9 @@ export class E2BSandboxService extends Service {
         try {
           await sandbox.kill()
         } catch (_cleanupFailure) {
-          // The setup failure remains authoritative; E2B will still apply the configured lifetime.
+          // Preserve the setup failure as the public error while retaining the
+          // created handle for the service disposer to retry this rollback.
+          this.failedSetupSandbox = sandbox
         }
       }
       throw error
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index ff90c37b3a..fea24fa1cd 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -210,8 +210,28 @@ describe('E2BSandboxService', () => {
     fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
     sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
-    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
     await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+    expect(fixture.kill).toHaveBeenCalledOnce()
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledTimes(2)
+  })
+
+  it.each([
+    ['retries a still-failing rollback', new Error('retry failed')],
+    ['accepts a setup sandbox that expired before retry', new SandboxNotFoundError('sandbox expired')],
+  ])('%s during disposal', async (_label, retryError) => {
+    const fixture = fakeSandbox()
+    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
+    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed')).mockRejectedValueOnce(retryError)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledTimes(2)
   })
 
   it('does not kill a reconnected sandbox when setup fails', async () => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 41d964a58a..0a9baf6d27 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 42cd4951edb101dc75980e114e704c4aab50ae25
-README.zh.md: c4b318184cb7616a378e3336f4f4a7c366a98807
+README.md: 1c05509308e4f8b8b07cffd85e289b3ebee70318
+README.zh.md: b536d4e9d083076eccef4ca238dda1b2a503bee1
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 42cd4951ed..1c05509308 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,10 +8,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination; raw pipes instead await lossless transport completion and preserve backpressure. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index c4b318184c..b536d4e9d0 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,10 +8,10 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用；原始 pipe 则会等待无损传输完成并保留背压。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 4855b27b81..5387966578 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -474,12 +474,15 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
+      const onClose = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
       const cleanup = (): void => {
         target.removeListener('drain', onDrain)
+        target.removeListener('close', onClose)
         target.removeListener('error', onError)
       }
       target.once('drain', onDrain)
+      target.once('close', onClose)
       target.once('error', onError)
     })
   }
@@ -671,14 +674,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
-    try {
-      await sandbox.commands.run(`kill -0 -- -${pid}`, signalOpts(signal))
-      return true
-    } catch (error: unknown) {
-      if (signal?.aborted === true) return false
-      if (error instanceof CommandExitError) return false
+    const result = await sandbox.commands.run(
+      `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
+      signalOpts(signal),
+    ).catch((error: unknown) => {
+      if (signal?.aborted === true) return undefined
       throw error
-    }
+    })
+    return result?.stdout.trim() === 'live'
   }
 
   private async finalizeSpills(sandbox: Sandbox): Promise<void> {
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 0f5809fa44..be79199b58 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -170,7 +170,7 @@ async function waitUntilReady(
 
 async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
   const result = await sandbox.commands.run(
-    `ps -eo sid=,pgid= | awk '$1 == ${sessionId} { print $2 }'`,
+    `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
   )
   const groups = new Set<number>()
   for (const raw of result.stdout.trim().split(/\s+/)) {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 462e943a1b..b7d1642bd6 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -107,6 +107,7 @@ class FakeSandbox {
   delaysKillCompletion = false
   sdkKillStops = true
   alive = true
+  zombieOnly = false
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   processGroupId = '4242\n'
   exitStatus = ''
@@ -235,7 +236,7 @@ class FakeSandbox {
           if (this.envError !== undefined) throw this.envError
           return { exitCode: 0, stdout: this.ambient, stderr: '' }
         }
-        if (command.startsWith('kill -0 ')) {
+        if (command.startsWith('set -o pipefail; ps -eo pgid=,stat=')) {
           this.beforeProbe?.()
           if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
           if (this.probeError !== undefined) {
@@ -243,9 +244,9 @@ class FakeSandbox {
             this.probeError = undefined
             throw error
           }
-          if (!this.alive) throw commandError(1)
+          const stdout = this.alive && !this.zombieOnly ? 'live\n' : ''
           this.afterProbe?.()
-          return { exitCode: 0, stdout: '', stderr: '' }
+          return { exitCode: 0, stdout, stderr: '' }
         }
         if (command.startsWith('kill -TERM ')) {
           await this.signalGate
@@ -701,6 +702,20 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
   })
 
+  it('treats a zombie-only process group as quiescent', async () => {
+    const fake = new FakeSandbox()
+    fake.zombieOnly = true
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/zombie-quiescence')
+    await flush()
+
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain(
+      'set -o pipefail; ps -eo pgid=,stat= | awk \'$1 == 4242 && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }\'',
+    )
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
   it('keeps proven quiescence after a concurrent termination transport fails', async () => {
     const fake = new FakeSandbox()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
@@ -1187,6 +1202,23 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
   })
 
+  it('settles output backpressure when the consumer closes the pipe', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/backpressure-close')
+    await flush()
+
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockReturnValueOnce(false)
+    const pending = fake.stdout('discarded')
+    queueMicrotask(() => { handle.stdout!.destroy() })
+    await pending
+    stdoutWrite.mockRestore()
+
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
   it('contains a pipe callback failure instead of rejecting command settlement', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index e77646e586..b47cb8ffb1 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -95,6 +95,7 @@ class FakeTerminalSandbox {
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
+  zombieGroups: number[] = []
   createError: unknown
   writeError: unknown
   sendError: unknown
@@ -160,9 +161,12 @@ class FakeTerminalSandbox {
           if (this.foregroundFailure !== undefined) throw this.foregroundFailure
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
         }
-        if (command.startsWith('ps -eo sid=')) {
+        if (command.startsWith('set -o pipefail; ps -eo sid=')) {
           if (this.sessionGroupsFailure !== undefined) throw this.sessionGroupsFailure
-          return { exitCode: 0, stdout: this.groups.map(group => `${group}\n`).join(''), stderr: '' }
+          const groups = command.includes('stat=') && command.includes('$3 !~ /^[ZXx]/')
+            ? this.groups
+            : [...this.groups, ...this.zombieGroups]
+          return { exitCode: 0, stdout: groups.map(group => `${group}\n`).join(''), stderr: '' }
         }
         if (command.startsWith('kill -TERM -- ')) {
           if (this.termFailure !== undefined) throw this.termFailure
@@ -508,6 +512,20 @@ describe('E2B terminal lifecycle', () => {
     await expect(quiescence).resolves.toBe(true)
   })
 
+  it('treats a terminal session containing only zombies as quiescent', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.zombieGroups = [123]
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/zombie-session')
+
+    fake.handle.succeed(0)
+    await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.commands).toContain(
+      "set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == 123 && $3 !~ /^[ZXx]/ { print $2 }'",
+    )
+  })
+
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
     const fake = new FakeTerminalSandbox()
     fake.foreground = '123\n'

From 896bcd64a10d74f75a674e278bd816738a31062e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:14:06 +0800
Subject: [PATCH 120/262] fix(e2b): await teardown and honor published status

---
 packages/e2b/subprocess-e2b/src/index.ts      |  5 ++-
 packages/e2b/subprocess-e2b/src/process.ts    | 11 +++--
 .../subprocess-e2b/tests/subprocess.spec.ts   | 43 +++++++++++++++++++
 3 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index bf7edc41a1..4516bffa84 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -67,7 +67,10 @@ export class E2BSubprocessService extends SubprocessService {
       for (const cleanup of failedTerminalSetupCleanups) {
         pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
       }
-      await Promise.all(pending)
+      const outcomes = await Promise.allSettled(pending)
+      for (const outcome of outcomes) {
+        if (outcome.status === 'rejected') throw outcome.reason
+      }
     }, 'e2b subprocess teardown')
   }
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 5387966578..478dc96c30 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -524,10 +524,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
         }
         if (this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe') {
-          return this.commandOutcome(await settlement)
+          return this.commandOutcome(await settlement, exitCode)
         }
         const completed = await withinMs(settlement, this.spec.graceMs)
-        if (completed !== undefined) return this.commandOutcome(completed)
+        if (completed !== undefined) return this.commandOutcome(completed, exitCode)
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
@@ -539,9 +539,12 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
   }
 
-  private commandOutcome(settlement: CommandSettlement): SubprocessOutcome {
-    if (settlement.kind === 'result') return { exitCode: settlement.result.exitCode, signal: null }
+  private commandOutcome(settlement: CommandSettlement, publishedExitCode?: number): SubprocessOutcome {
+    if (settlement.kind === 'result') {
+      return { exitCode: publishedExitCode ?? settlement.result.exitCode, signal: null }
+    }
     if (settlement.error instanceof CommandExitError) {
+      if (publishedExitCode !== undefined) return { exitCode: publishedExitCode, signal: null }
       return this.terminationSignal === null
         ? { exitCode: settlement.error.exitCode, signal: null }
         : { exitCode: null, signal: this.terminationSignal }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index b7d1642bd6..6d20abd3c1 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -547,6 +547,20 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('preserves a published nonzero exit code when termination settles the SDK inside the drain grace', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-signal-settled')
+    await flush()
+    fake.exitStatus = '7\n'
+    fake.afterStatusRead = () => {
+      fake.afterStatusRead = undefined
+      handle.terminate()
+    }
+
+    await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
   it('rejects an invalid direct-command exit status', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')
@@ -1336,6 +1350,35 @@ describe('E2BSubprocessService', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('waits for every owned cleanup before reporting a disposal failure', async () => {
+    const { ctx, fiber } = await service()
+    const failed = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('cleanup failed') }),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    let finishCleanup!: () => void
+    const cleanup = new Promise<boolean>((resolve) => {
+      finishCleanup = () => { resolve(true) }
+    })
+    const draining = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(() => cleanup),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    const live = (ctx.subprocess as unknown as { live: Set<E2BSubprocessHandle> }).live
+    live.add(failed)
+    live.add(draining)
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await flush()
+    expect(disposed).toBe(false)
+    finishCleanup()
+    await disposing
+    expect(live).toEqual(new Set([failed]))
+  })
+
   it('releases naturally settled handles before later service disposal', async () => {
     const fake = new FakeSandbox()
     const { ctx, fiber } = await service(fake)

From cf4b721a8d7a3df38a1152295e098ce0ed3e20f4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:27:56 +0800
Subject: [PATCH 121/262] test(e2b): snapshot provider-neutral overlay surface

---
 .../headless-agent/e2b.cordis.snapshot.yml    | 58 +++++++++++++++++++
 .../headless-agent/tests/headless.snapshot.ts | 56 ++++++++++++++++++
 .../tests/snapshots/e2b-overlay/input.json    |  8 +++
 .../e2b-overlay/replay.override.json          | 12 ++++
 .../e2b-overlay/stream-json.expected.jsonl    | 14 +++++
 5 files changed, 148 insertions(+)
 create mode 100644 examples/headless-agent/e2b.cordis.snapshot.yml
 create mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/input.json
 create mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
 create mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl

diff --git a/examples/headless-agent/e2b.cordis.snapshot.yml b/examples/headless-agent/e2b.cordis.snapshot.yml
new file mode 100644
index 0000000000..3f39f0ffe4
--- /dev/null
+++ b/examples/headless-agent/e2b.cordis.snapshot.yml
@@ -0,0 +1,58 @@
+# Keyless counterpart to e2b.cordis.yml. It keeps the same generic PTY, LSP,
+# and subprocess Code Runtime consumers, but supplies their fundamental
+# filesystem/process world locally and replaces the live model with replay.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: cli-agent
+        name: '@deepseek-ai/dsh-cli-demo'
+        config:
+          provider: deepseek
+          model: deepseek-v4-pro
+          persistenceRoot: './.sessions'
+          persistenceCompression: none
+          workspaceContext:
+            maxBytes: 65536
+          tools:
+            mode: both
+          persona: |
+            You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
+
+            Verify your work by running the code or tests. Keep answers brief and factual.
+      - insert:
+          - id: code-runtime-subprocess
+            name: '@deepseek-ai/dsh-code-runtime-subprocess'
+          - id: tool-cordis
+            name: '@deepseek-ai/dsh-tool-cordis'
+          - id: sandbox
+            name: '@deepseek-ai/dsh-sandbox-local'
+          - id: sandbox-policy
+            name: '@deepseek-ai/dsh-sandbox-policy'
+            config:
+              mode: danger-full-access
+              workspaceRoot: !!js process.cwd()
+          - id: pty
+            name: '@deepseek-ai/dsh-pty'
+          - id: pty-local
+            name: '@deepseek-ai/dsh-pty-local'
+          - id: tool-pty
+            name: '@deepseek-ai/dsh-tool-pty'
+          - id: lsp
+            name: '@deepseek-ai/dsh-lsp'
+          - id: lsp-local
+            name: '@deepseek-ai/dsh-lsp-local'
+            config:
+              servers:
+                typescript:
+                  command: node
+                  extensionToLanguage:
+                    .ts: typescript
+          - id: tool-lsp
+            name: '@deepseek-ai/dsh-tool-lsp'
+          - id: llm-replay
+            name: '@deepseek-ai/dsh-llm-replay'
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 87261439da..ca8e93724c 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -25,6 +25,8 @@ const advancedScenarioDir = join(snapshotsDir, 'advanced-toolchain')
 const advancedSessionFixture = join(advancedScenarioDir, 'session.jsonl')
 const advancedStreamExpected = join(advancedScenarioDir, 'stream-json.expected.jsonl')
 const advancedConfigPath = fileURLToPath(new URL('../advanced.cordis.snapshot.yml', import.meta.url))
+const e2bScenarioDir = join(snapshotsDir, 'e2b-overlay')
+const e2bConfigPath = fileURLToPath(new URL('../e2b.cordis.snapshot.yml', import.meta.url))
 const ptyScenarioDir = join(snapshotsDir, 'pty-tools')
 const ptySessionFixture = join(ptyScenarioDir, 'session.jsonl')
 const ptyStreamExpected = join(ptyScenarioDir, 'stream-json.expected.jsonl')
@@ -608,6 +610,60 @@ describe('headless stream-json snapshots', () => {
     expect(normalized).toBe(await readFile(advancedStreamExpected, 'utf8'))
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('pins the E2B overlay provider-neutral tool surface', async () => {
+    const prompt = await scenarioPrompt(e2bScenarioDir, 'e2b-overlay')
+    const streamExpected = join(e2bScenarioDir, 'stream-json.expected.jsonl')
+    let runCwd = ''
+    const result = await runLoaderSmoke({
+      label: 'E2B overlay headless stream-json snapshot',
+      tempDirPrefix: 'headless-snapshot-e2b-overlay-',
+      binScript,
+      configPath: e2bConfigPath,
+      binArgs: ['--config', e2bConfigPath, '--output-format', 'stream-json', prompt],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT: 'replay',
+        DSH_SNAPSHOT_FILE: join(e2bScenarioDir, 'session.jsonl'),
+        DSH_SNAPSHOT_OVERRIDE: join(e2bScenarioDir, 'replay.override.json'),
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: (cwd) => { runCwd = cwd },
+      inspect: async (cwd) => {
+        const logs = await persistedLogs(cwd)
+        expect(logs).toHaveLength(1)
+        const headers = parseJsonl(logs[0]?.content ?? '').filter(record => record.type === 'request/header')
+        expect(headers).toHaveLength(1)
+        const data = headers[0]?.data as JsonObject | undefined
+        const header = data?.header as JsonObject | undefined
+        if (!Array.isArray(header?.tools)) throw new Error('E2B overlay snapshot request has no tool schemas')
+        const toolNames = header.tools.map((tool, index) => {
+          if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) {
+            throw new Error(`E2B overlay snapshot tool schema ${index} is not an object`)
+          }
+          const name = (tool as JsonObject).name
+          if (typeof name !== 'string') throw new Error(`E2B overlay snapshot tool schema ${index} has no name`)
+          return name
+        })
+        expect(toolNames.filter(name => name === 'lsp' || name === 'run_code' || name.startsWith('terminal_')).sort())
+          .toEqual([
+            'lsp',
+            'run_code',
+            'terminal_close',
+            'terminal_list',
+            'terminal_open',
+            'terminal_read',
+            'terminal_send',
+            'terminal_signal',
+          ])
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
+    if (refreshing) await writeFile(streamExpected, normalized)
+    expect(normalized).toBe(await readFile(streamExpected, 'utf8'))
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('replays persisted goal tools through the one-shot app', async () => {
     const prompt = await scenarioPrompt(goalScenarioDir, 'goal-tools')
     const streamExpected = join(goalScenarioDir, 'stream-json.expected.jsonl')
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/input.json b/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
new file mode 100644
index 0000000000..00fd27ce2e
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
@@ -0,0 +1,8 @@
+{
+  "steps": [
+    {
+      "op": "prompt",
+      "text": "Report the assembled E2B overlay tool surface."
+    }
+  ]
+}
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json b/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
new file mode 100644
index 0000000000..d1a71ce58c
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
@@ -0,0 +1,12 @@
+[
+  {
+    "kind": "chunks",
+    "chunks": [
+      { "type": "block-start", "index": 0, "blockType": "text" },
+      { "type": "text-delta", "index": 0, "text": "E2B_SURFACE_OK" },
+      { "type": "block-end", "index": 0, "block": { "type": "text", "text": "E2B_SURFACE_OK" } },
+      { "type": "usage", "usage": { "inputTokens": 8, "outputTokens": 3 } },
+      { "type": "finish", "reason": { "kind": "stop" } }
+    ]
+  }
+]
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
new file mode 100644
index 0000000000..2fb74415cb
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
@@ -0,0 +1,14 @@
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Report the assembled E2B overlay tool surface."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":2,"time":0,"data":{"title":"Report the assembled E2B overlay","messageSeqs":[1],"source":{"kind":"fallback"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"E2B_SURFACE_OK"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"E2B_SURFACE_OK"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":8,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"E2B_SURFACE_OK"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"{{sessionId}}"},"usage":{"inputTokens":8,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":11,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":12,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"E2B_SURFACE_OK","reason":{"kind":"completed"},"usage":{"inputTokens":8,"outputTokens":3}}

From c122d984c4905d2d5d404fbe7686deded7737b07 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 11:23:01 +0800
Subject: [PATCH 122/262] fix(e2b): harden cancellation and teardown boundaries

---
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |   8 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  48 ++++++-
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   2 +-
 packages/e2b/fs-e2b/README.zh.md              |   2 +-
 packages/e2b/fs-e2b/src/index.ts              |   2 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |   1 +
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   5 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   5 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  34 ++++-
 packages/e2b/subprocess-e2b/src/terminal.ts   |  47 +++++--
 .../subprocess-e2b/tests/subprocess.spec.ts   |  98 +++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 121 +++++++++++++++++-
 17 files changed, 351 insertions(+), 38 deletions(-)

diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 46ff37b222..2fc8d403d1 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: ccafa9df480e3812d3d3b6d25b513e7b5d2afc9f
-README.zh.md: 60eefd46a0a9a017f4db57e4dc5313d533eeba04
+README.md: 6eb7d69dd6355de870db6bf05540f2629f464bc8
+README.zh.md: b2e2616cf779bce659fdef58840aa51f095a73cf
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index ccafa9df48..6eb7d69dd6 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -30,7 +30,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` is accepted when disposal requests `kill`, or when this service created a sandbox with `onTimeout: kill`; otherwise, a not-found error from a requested `pause` rejects teardown because retention was not proved. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
 `pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 60eefd46a0..b2e2616cf7 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -30,7 +30,7 @@
 
 构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 仅在资源释放请求 `kill`，或本服务创建了配置为 `onTimeout: kill` 的沙箱时才可接受；否则，`pause` 请求返回的未找到错误会导致 teardown 拒绝，因为无法证明保留成功。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 `pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 31e4f911a2..150961a897 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -181,9 +181,13 @@ export class E2BSandboxService extends Service {
             return
         }
       } catch (error: unknown) {
-        // A kill-on-timeout sandbox is already quiescent; every other disposal
-        // failure still reports that the configured final disposition is unknown.
         if (!(error instanceof SandboxNotFoundError)) throw error
+        // Missing proves the requested disposition only when this owner asked
+        // for deletion or created the sandbox with timeout deletion. A
+        // reconnected sandbox's creation lifecycle is unknown.
+        if (this.config.onDispose === 'kill') return
+        if (this.created && this.config.onTimeout === 'kill') return
+        throw error
       }
     }, 'e2b sandbox teardown')
   }
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index fea24fa1cd..a4eba5ebc9 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -160,15 +160,59 @@ describe('E2BSandboxService', () => {
     expect(fixture.pause).toHaveBeenCalledOnce()
   })
 
-  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+  it('accepts a missing sandbox when disposal itself requests deletion', async () => {
     const fixture = fakeSandbox()
-    fixture.kill.mockRejectedValue(new Error('disposition unknown'))
+    fixture.kill.mockRejectedValue(new SandboxNotFoundError('already deleted'))
     sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await ctx.e2b.getSandbox()
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    expect(errors).toEqual([])
+  })
+
+  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+    const fixture = fakeSandbox()
+    const failure = new Error('disposition unknown')
+    fixture.kill.mockRejectedValue(failure)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
     const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
     await ctx.e2b.getSandbox()
     await expect(fiber.dispose()).resolves.toBeUndefined()
     expect(fixture.kill).toHaveBeenCalledOnce()
+    expect(errors).toContain(failure)
+  })
+
+  it.each([
+    ['a created pause-on-timeout sandbox', false],
+    ['a reconnected sandbox with unknown creation policy', true],
+  ] as const)('reports missing during pause disposal for %s', async (_label, reconnect) => {
+    const fixture = fakeSandbox()
+    const failure = new SandboxNotFoundError('sandbox unexpectedly missing')
+    fixture.pause.mockRejectedValue(failure)
+    if (reconnect) sdk.connect.mockResolvedValue(fixture.sandbox)
+    else sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      apiKey: 'test-key',
+      onTimeout: reconnect ? 'kill' : 'pause',
+      onDispose: 'pause',
+      ...(reconnect ? { sandboxId: 'existing' } : {}),
+    })
+    await ctx.e2b.getSandbox()
+
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+    expect(errors).toContain(failure)
   })
 
   it('reconnects without applying creation lifecycle options and can leave state running', async () => {
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 3c2b30ad15..87f1c7c69b 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 8abf130ce16e2b79cda5fc858182159442f9e3c3
-README.zh.md: 943d9603046ad9b2a65f41d5801cac882040a0ff
+README.md: bb92b5785383e9703a382fddefcd1cff9b2644cb
+README.zh.md: 57ebfdbb92799660e74078fcd0affcc8d5bc120a
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 8abf130ce1..bb92b57853 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -11,7 +11,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
 - **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
 - **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
-- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
 
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 943d960304..57ebfdbb92 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -11,7 +11,7 @@
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
 - **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
 - **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
-- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
 
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 0824c3f87c..d41c2e3d32 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -518,7 +518,7 @@ export class E2BFileSystem extends FileSystem {
         signalOpts(signal),
       )
       assertNotAborted(signal, 'write')
-      const committed = await sandbox.files.rename(temporary, targetPath, signalOpts(signal))
+      const committed = await sandbox.files.rename(temporary, targetPath)
       try {
         await sandbox.files.remove(stagingDirectory)
       } catch (_committedStagingCleanupFailure) {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 303f99c1e8..1689fb4023 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -209,6 +209,7 @@ class FakeRemote {
         this.nodes.set(to, node)
         this.renames.push({ from, to })
         this.abortAfterRename?.abort('after commit')
+        this.checkAbort(options)
         return this.info(to)
       },
       remove: async (path: string): Promise<void> => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 0a9baf6d27..8378cfa114 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 1c05509308e4f8b8b07cffd85e289b3ebee70318
-README.zh.md: b536d4e9d083076eccef4ca238dda1b2a503bee1
+README.md: 66481fb1c5edd4c124c2c58aaa5c86a1683e5a3b
+README.zh.md: 5e4b8bbe401cf4a565ccd53270df9fb6b5de9315
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 1c05509308..66481fb1c5 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -10,8 +10,9 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
-- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination; raw pipes instead await lossless transport completion and preserve backpressure. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index b536d4e9d0..5e4b8bbe40 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -10,8 +10,9 @@
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
-- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用；原始 pipe 则会等待无损传输完成并保留背压。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 478dc96c30..c7d19e0ab8 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -6,6 +6,7 @@ import { posix } from 'node:path'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -115,7 +116,7 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
     `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
     `"$dsh_e2b_rm" -f -- ${quoteE2BShellArg(paths.environment)}`,
-    `"$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    `"$dsh_e2b_env_bin" -i -- "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
     'wait',
@@ -136,7 +137,7 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm"; do',
     '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
     'done',
-    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
+    `exec "$dsh_e2b_env_bin" -i -- "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
   ].join('\n')
   return bootstrap
 }
@@ -196,6 +197,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly readyState = Promise.withResolvers<CommandHandle>()
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
+  private readonly outputTermination = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
@@ -262,6 +264,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   terminate(): void {
     if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
+    this.outputTermination.abort()
+    this.stdout?.destroy()
+    this.stderr?.destroy()
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
@@ -317,6 +322,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       sandbox = await this.runtime.getSandbox()
     } catch (error: unknown) {
       if (isAborted(signal)) return false
+      if (error instanceof SandboxNotFoundError) {
+        this.markQuiescent()
+        return true
+      }
       throw error
     }
     const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
@@ -469,21 +478,25 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
     const target = pipe ?? inherited
-    if (target === undefined || data.length === 0) return
+    if (target === undefined || data.length === 0 || this.outputTermination.signal.aborted) return
     if (target.destroyed) throw new Error('subprocess output stream is closed')
     if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
       const onClose = (): void => { cleanup(); resolve() }
+      const onTermination = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
       const cleanup = (): void => {
         target.removeListener('drain', onDrain)
         target.removeListener('close', onClose)
         target.removeListener('error', onError)
+        this.outputTermination.signal.removeEventListener('abort', onTermination)
       }
       target.once('drain', onDrain)
       target.once('close', onClose)
       target.once('error', onError)
+      this.outputTermination.signal.addEventListener('abort', onTermination, { once: true })
+      if (this.outputTermination.signal.aborted) onTermination()
     })
   }
 
@@ -580,6 +593,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async terminateRemote(): Promise<void> {
+    try {
+      await this.terminateRemoteInSandbox()
+    } catch (error: unknown) {
+      if (error instanceof SandboxNotFoundError) {
+        this.markQuiescent()
+        return
+      }
+      throw error
+    }
+  }
+
+  private async terminateRemoteInSandbox(): Promise<void> {
     const handle = await this.commandState.promise
     if (handle === undefined) return
     if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
@@ -671,7 +696,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       await sandbox.commands.run(`kill -${signal} -- -${pid}`)
       return true
     } catch (error: unknown) {
-      if (error instanceof CommandExitError) return false
+      if (error instanceof CommandExitError || error instanceof SandboxNotFoundError) return false
       throw error
     }
   }
@@ -682,6 +707,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       signalOpts(signal),
     ).catch((error: unknown) => {
       if (signal?.aborted === true) return undefined
+      if (error instanceof SandboxNotFoundError) return { exitCode: 0, stdout: '', stderr: '' }
       throw error
     })
     return result?.stdout.trim() === 'live'
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index be79199b58..f918f802ba 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -7,6 +7,7 @@ import { posix } from 'node:path'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -37,7 +38,7 @@ const TERMINAL_RUNNER_SOURCE = [
   'fi',
   'printf \'%s\' "$dsh_output_marker"',
   "printf 'ready\\n' > \"$dsh_state/ready\"",
-  'exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"',
+  'exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"',
   '',
 ].join('\n')
 
@@ -169,9 +170,15 @@ async function waitUntilReady(
 }
 
 async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
-  const result = await sandbox.commands.run(
-    `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
-  )
+  let result: CommandResult
+  try {
+    result = await sandbox.commands.run(
+      `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
+    )
+  } catch (error: unknown) {
+    if (error instanceof SandboxNotFoundError) return []
+    throw error
+  }
   const groups = new Set<number>()
   for (const raw of result.stdout.trim().split(/\s+/)) {
     if (raw.length === 0) continue
@@ -191,7 +198,7 @@ async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' |
   try {
     await sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
   } catch (error: unknown) {
-    if (!(error instanceof CommandExitError)) throw error
+    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
   }
 }
 
@@ -253,6 +260,7 @@ async function rollbackUnpublishedTerminal(
       try {
         await sandbox.pty.kill(handle.pid)
       } catch (error: unknown) {
+        if (error instanceof SandboxNotFoundError) return
         attemptFailures.push(asError(error))
       }
     }
@@ -262,6 +270,7 @@ async function rollbackUnpublishedTerminal(
       try {
         await handle.kill()
       } catch (error: unknown) {
+        if (error instanceof SandboxNotFoundError) return
         attemptFailures.push(asError(error))
       }
     }
@@ -291,7 +300,11 @@ async function rollbackUnpublishedTerminal(
       'subprocess-e2b: terminal setup rollback did not reach quiescence',
     )
   }
-  await handle.disconnect()
+  try {
+    await handle.disconnect()
+  } catch (error: unknown) {
+    if (!(error instanceof SandboxNotFoundError)) throw error
+  }
 }
 
 /** One E2B PTY and all process groups in its remote process session. */
@@ -400,7 +413,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     }
     if (groups.length > 0 || !this.topLevelExited) {
       this.terminationSignal = 'SIGKILL'
-      if (!this.topLevelExited) await this.sandbox.pty.kill(this.pid)
+      if (!this.topLevelExited) {
+        try {
+          await this.sandbox.pty.kill(this.pid)
+        } catch (error: unknown) {
+          if (error instanceof SandboxNotFoundError) return
+          throw error
+        }
+      }
       groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
@@ -410,7 +430,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (!this.topLevelExited) {
       throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
     }
-    await this.handle.disconnect()
+    try {
+      await this.handle.disconnect()
+    } catch (error: unknown) {
+      if (!(error instanceof SandboxNotFoundError)) throw error
+    }
     await this.sandbox.files.remove(this.stateDir).catch(() => {})
   }
 }
@@ -468,11 +492,11 @@ export async function spawnE2BTerminal(
       cwd: spec.cwd,
       envs: { TERM: 'dumb' },
       timeoutMs: 0,
-      ...signalOpts(spec.signal),
       onData: (data) => { outputFilter.push(data) },
     })
     completion = handle.wait()
     void completion.catch(() => {})
+    spec.signal?.throwIfAborted()
     if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
       throw new Error(`subprocess-e2b: E2B returned invalid terminal pid ${handle.pid}`)
     }
@@ -503,7 +527,8 @@ export async function spawnE2BTerminal(
           else await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
           terminalQuiescent = true
         } catch (cleanupError: unknown) {
-          failures.push(asError(cleanupError))
+          if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
+          else failures.push(asError(cleanupError))
         }
       }
       if (!stateRemoved) {
@@ -511,7 +536,7 @@ export async function spawnE2BTerminal(
           await sandbox.files.remove(stateDir)
           stateRemoved = true
         } catch (stateError: unknown) {
-          if (stateError instanceof FileNotFoundError) stateRemoved = true
+          if (stateError instanceof FileNotFoundError || stateError instanceof SandboxNotFoundError) stateRemoved = true
           else failures.push(asError(stateError))
         }
       }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 6d20abd3c1..680d309bbb 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   type CommandHandle,
   type CommandResult,
   type Sandbox,
@@ -371,7 +372,13 @@ describe('E2BSubprocessHandle', () => {
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
       argv: ['tool', 'argument with spaces'],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
-      env: { PATH: '/bin', 'FOO-BAR': 'hyphen-value', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
+      env: {
+        PATH: '/bin',
+        'FOO-BAR': 'hyphen-value',
+        '--split-string': 'literal-value',
+        DEEPSEEK_API_KEY: 'explicit-secret',
+        DSH_MODE: 'test',
+      },
     }), '/workspace/.dsh-e2b/processes/one')
     expect(handle.pid).toBe(-1)
     handle.stdin!.write('hello')
@@ -394,7 +401,8 @@ describe('E2BSubprocessHandle', () => {
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
-    expect(command).toContain('exec "$dsh_e2b_env_bin" -i "${dsh_e2b_env[@]}"')
+    expect(command).toContain('"$dsh_e2b_env_bin" -i -- "${dsh_e2b_env[@]}" "$@"')
+    expect(command).toContain('exec "$dsh_e2b_env_bin" -i -- "${dsh_e2b_env[@]}"')
     expect(command).toContain('>&2 2>/dev/null')
     expect(command).not.toContain('2>/dev/null >&2')
     expect(command).toContain('base64')
@@ -405,7 +413,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -1088,6 +1096,52 @@ describe('E2BSubprocessHandle', () => {
     await handle.done
   })
 
+  it('treats a timeout-killed sandbox as quiescent during liveness probing', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/expired-sandbox')
+    await flush()
+    fake.finish()
+    await handle.done
+    fake.probeError = new SandboxNotFoundError('sandbox expired')
+
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('treats a missing sandbox handle as quiescent during liveness acquisition', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+      calls += 1
+      if (calls === 1) return fake.sandbox
+      throw new SandboxNotFoundError('sandbox expired')
+    }), spec(), '/runtime/expired-acquisition')
+    await flush()
+
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await fake.completeOutput()
+    fake.alive = false
+    fake.handle.succeed(0)
+    await handle.done
+  })
+
+  it('treats sandbox loss during termination as quiescent', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+      calls += 1
+      if (calls === 1) return fake.sandbox
+      throw new SandboxNotFoundError('sandbox expired')
+    }), spec(), '/runtime/expired-termination')
+    await flush()
+    await fake.completeOutput()
+
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.alive = false
+    fake.handle.succeed(0)
+    await handle.done
+  })
+
   it('makes batch stdin close failures best-effort', async () => {
     const fake = new FakeSandbox()
     vi.spyOn(fake.handle, 'sendStdin').mockRejectedValueOnce(new Error('closed'))
@@ -1233,6 +1287,44 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
   })
 
+  it('breaks output backpressure when termination owns the command', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/backpressure-termination')
+    await flush()
+
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockReturnValueOnce(false)
+    let released = false
+    const pending = fake.stdout('blocked').then(() => { released = true })
+    await Promise.resolve()
+    handle.terminate()
+    await flush()
+    const releasedByTermination = released
+    if (!released) handle.stdout!.emit('drain')
+    await pending
+    stdoutWrite.mockRestore()
+    await handle.done
+
+    expect(releasedByTermination).toBe(true)
+  })
+
+  it('settles backpressure when a synchronous pipe write starts termination', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/backpressure-synchronous-termination')
+    await flush()
+
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockImplementationOnce(() => {
+      handle.terminate()
+      return false
+    })
+    await expect(fake.stdout('blocked')).resolves.toBeUndefined()
+    stdoutWrite.mockRestore()
+    await handle.done
+  })
+
   it('contains a pipe callback failure instead of rejecting command settlement', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index b47cb8ffb1..c6ec5bfaad 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -6,6 +6,7 @@ import { describe, expect, it, vi } from 'vitest'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   type CommandHandle,
   type CommandResult,
   type Sandbox,
@@ -113,6 +114,18 @@ class FakeTerminalSandbox {
   requestedOutput = 'requested-shell$ '
   emitOutputMarker = true
   afterSessionLookup: (() => void) | undefined
+  private createGate: Promise<undefined> | undefined
+  private releaseCreateGate: (() => void) | undefined
+
+  deferCreate(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.createGate = gate.promise
+    this.releaseCreateGate = () => { gate.resolve(undefined) }
+  }
+
+  releaseCreate(): void {
+    this.releaseCreateGate?.()
+  }
 
   readonly sandbox = {
     files: {
@@ -183,6 +196,8 @@ class FakeTerminalSandbox {
       create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
         this.createOptions = options
         if (this.createError !== undefined) throw this.createError
+        await this.createGate
+        options.signal?.throwIfAborted()
         await options.onData(Buffer.from('buffered banner\n'))
         return this.handle.asHandle()
       },
@@ -258,7 +273,7 @@ describe('E2B terminal allocation', () => {
     const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
     expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
     expect(runner).toContain('printf \'%s\' "$dsh_output_marker"')
-    expect(runner).toContain('exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"')
+    expect(runner).toContain('exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"')
     expect(runner).not.toContain('\u007f')
     terminal.output.destroy()
     await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
@@ -296,6 +311,25 @@ describe('E2B terminal allocation', () => {
     await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
+  it('publishes the PTY handle before honoring allocation cancellation', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.deferCreate()
+    const controller = new AbortController()
+    const spawning = spawnE2BTerminal(
+      runtime(fake),
+      spec({ signal: controller.signal }),
+      '/runtime/allocation-cancel',
+    )
+    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
+
+    controller.abort(new Error('allocation cancelled'))
+    fake.releaseCreate()
+    await expect(spawning).rejects.toThrow('allocation cancelled')
+    expect(fake.createOptions?.signal).toBeUndefined()
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
   it('rejects malformed environment and argv values before PTY allocation', async () => {
     const invalidName = new FakeTerminalSandbox()
     await expect(spawnE2BTerminal(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
@@ -410,6 +444,44 @@ describe('E2B terminal allocation', () => {
     cleanupFailed.removeError = new Error('remove transport failed')
     await expect(spawnE2BTerminal(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
       .rejects.toThrow('invalid terminal pid 0')
+
+    const expiredDuringRollback = new FakeTerminalSandbox()
+    expiredDuringRollback.sendError = new Error('bootstrap failed before timeout')
+    expiredDuringRollback.groups = []
+    expiredDuringRollback.settleOnPtyKill = false
+    expiredDuringRollback.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
+    await expect(spawnE2BTerminal(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
+      .rejects.toThrow('bootstrap failed before timeout')
+    expect(expiredDuringRollback.ptyKills).toBe(1)
+
+    const expiredBeforeSdkRollback = new FakeTerminalSandbox()
+    expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
+    expiredBeforeSdkRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    expiredBeforeSdkRollback.handle.settleOnSdkKill = false
+    await expect(spawnE2BTerminal(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
+      .rejects.toThrow('wait failed after timeout')
+
+    const expiredDuringSdkFallback = new FakeTerminalSandbox()
+    expiredDuringSdkFallback.sendError = new Error('bootstrap failed before SDK fallback')
+    expiredDuringSdkFallback.groups = []
+    expiredDuringSdkFallback.settleOnPtyKill = false
+    expiredDuringSdkFallback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringSdkFallback.handle.settleOnSdkKill = false
+    await expect(spawnE2BTerminal(runtime(expiredDuringSdkFallback), spec(), '/runtime/expired-sdk-fallback'))
+      .rejects.toThrow('bootstrap failed before SDK fallback')
+
+    const missingDuringDisconnect = new FakeTerminalSandbox()
+    missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
+    missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
+    await expect(spawnE2BTerminal(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
+      .rejects.toThrow('bootstrap failed before disconnect')
+
+    const failedDisconnect = new FakeTerminalSandbox()
+    failedDisconnect.sendError = new Error('bootstrap failed with disconnect failure')
+    failedDisconnect.handle.disconnectError = new Error('disconnect transport failed')
+    await expect(spawnE2BTerminal(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
+      .rejects.toThrow('bootstrap failed with disconnect failure')
   })
 
   it('propagates setup cancellation and provider failures', async () => {
@@ -526,6 +598,53 @@ describe('E2B terminal lifecycle', () => {
     )
   })
 
+  it('treats a timeout-killed sandbox as quiescent during terminal cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/expired-sandbox')
+    fake.sessionGroupsFailure = new SandboxNotFoundError('sandbox expired')
+    fake.handle.succeed(0)
+
+    await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('treats sandbox disappearance during PTY kill as quiescent', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.settleOnPtyKill = false
+    fake.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
+
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.ptyKills).toBe(1)
+  })
+
+  it('propagates a non-missing PTY kill failure', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.settleOnPtyKill = false
+    fake.ptyKillError = new Error('PTY kill transport failed')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
+
+    terminal.terminate()
+    await expect(terminal.waitForExit()).rejects.toThrow('PTY kill transport failed')
+  })
+
+  it.each([
+    ['accepts sandbox loss', new SandboxNotFoundError('sandbox expired'), true],
+    ['propagates another failure', new Error('disconnect failed'), false],
+  ] as const)('%s while disconnecting a settled terminal', async (_label, failure, accepted) => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
+    fake.handle.disconnectError = failure
+    fake.groups = []
+    fake.handle.succeed(0)
+
+    if (accepted) await expect(terminal.waitForExit()).resolves.toBe(true)
+    else await expect(terminal.waitForExit()).rejects.toThrow('disconnect failed')
+  })
+
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
     const fake = new FakeTerminalSandbox()
     fake.foreground = '123\n'

From ca79f4364c63c3f0d7a9ace8c127fc2f696e5fdf Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 12:15:18 +0800
Subject: [PATCH 123/262] test(e2b): prove stale interrupt isolation

---
 .../tests/fixtures/e2b/e2b/bin.ts             | 30 +++++++++++++++++--
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 6fa95c24b6..b4acfd1e5a 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -252,14 +252,38 @@ try {
   }
   const staleInterrupt = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 0.2', submit: true })
   if (!staleInterrupt.cancel()) throw new Error('E2B PTY refused the stale-interrupt probe cancellation')
-  await staleInterrupt.done
-  const sleeping = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
+  let canceledSendRetained = false
+  try {
+    ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
+  } catch (error: unknown) {
+    canceledSendRetained = String(error).includes('active send')
+  }
   foregroundLookup.resolve(undefined)
+  await staleInterrupt.done
+  remoteCommands.run = runRemoteCommand
+  if (!canceledSendRetained) throw new Error('E2B PTY released a canceled send before foreground signalling settled')
+  const sleeping = ctx.pty.startSend(owner, terminal.sessionId, {
+    text: "printf 'DSH_SLEEP_%s\\n' READY; sleep 30",
+    submit: true,
+  })
+  let sleepReadyOutput = ''
+  const sleepReadyDeadline = Date.now() + 5_000
+  while (!sleepReadyOutput.includes('DSH_SLEEP_READY\n')) {
+    sleepReadyOutput += sleeping.readOutput().delta
+    if (sleepReadyOutput.includes('DSH_SLEEP_READY\n')) break
+    const settled = await Promise.race([
+      sleeping.done.then(result => ({ result })),
+      new Promise<undefined>(resolveDelay => setTimeout(() => { resolveDelay(undefined) }, 25)),
+    ])
+    if (settled !== undefined) {
+      throw new Error(`E2B PTY successor settled before executing: ${JSON.stringify(settled.result)}`)
+    }
+    if (Date.now() >= sleepReadyDeadline) throw new Error(`E2B PTY successor did not execute: ${sleepReadyOutput}`)
+  }
   const interruptIdentitySafe = await Promise.race([
     sleeping.done.then(() => false),
     new Promise<true>(resolveDelay => setTimeout(() => { resolveDelay(true) }, 300)),
   ])
-  remoteCommands.run = runRemoteCommand
   if (!delayedForegroundLookup || !interruptIdentitySafe) {
     throw new Error('E2B PTY stale interrupt affected its successor send')
   }

From 091af03a81319ccadde487a981933558de3c7c60 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:01:37 +0800
Subject: [PATCH 124/262] fix(e2b): harden remote startup and teardown

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   2 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   2 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   8 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   8 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  24 ++++
 packages/e2b/subprocess-e2b/src/process.ts    |  42 +++++--
 packages/e2b/subprocess-e2b/src/terminal.ts   |   8 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 109 +++++++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |   9 +-
 11 files changed, 182 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 079924ac74..1343d33032 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 02de8df021094fa326431a996cd183d13b9c0c8c
-2026-07-27-e2b-remote-runtime-poc.zh.md: 3b7ddf761b2cbf950898a0083cf9da653d20e723
+2026-07-27-e2b-remote-runtime-poc.md: cccee91998e832cc9cf53e554e104ccc5caada38
+2026-07-27-e2b-remote-runtime-poc.zh.md: b1a30c92e313b1395006ebd4fd17eacda2546ad5
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 02de8df021..cccee91998 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -28,7 +28,7 @@ E2B owns the mutable filesystem, managed command and Bash processes, terminal al
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. For ordinary command pipes, its remote wrapper branches raw spill bytes before framing each live chunk as newline-delimited base64 ASCII; the host restores raw bytes across arbitrary decoded SDK callback boundaries. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
+The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. Ambient environments and ordinary command pipes cross decoded SDK callback boundaries as ASCII/base64 before strict UTF-8 or raw-byte restoration; startup preparation carries the handle's owned cancellation signal, and provisional termination proves the remote group empty after SDK fallback. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 3b7ddf761b..b1a30c92e3 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -28,7 +28,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。对于普通命令管道，其远程包装层会先分流原始 spill 字节，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意已解码 SDK 回调边界恢复原始字节。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
+基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。环境快照与普通命令管道会先以 ASCII/base64 跨越已解码的 SDK 回调边界，再执行严格 UTF-8 解码或恢复原始字节；启动准备会携带句柄自有的取消信号，临时终止则会在 SDK 回退后证明远程进程组为空。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 8378cfa114..3f64c67b7e 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 66481fb1c5edd4c124c2c58aaa5c86a1683e5a3b
-README.zh.md: 5e4b8bbe401cf4a565ccd53270df9fb6b5de9315
+README.md: aaac559e60162c3051cc6f06cbcfac011f5eb59a
+README.zh.md: 904e4fd1d9a13082ddfc8183c0e42abc25bd1caf
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 66481fb1c5..aaac559e60 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -6,15 +6,15 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 ## Behavior
 
-- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses both the provisional group and SDK handle and proves the group empty before reporting quiescence; if publication fails, rollback applies the same proof before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 5e4b8bbe40..904e4fd1d9 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -6,15 +6,15 @@
 
 ## 行为
 
-- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作会同时使用临时进程组与 SDK 句柄，并在报告完全停稳前证明进程组为空；如果发布失败，回滚会在启动拒绝前执行相同证明。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index f9c30d378f..2b2516a706 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -1,7 +1,31 @@
 /** Shared remote-environment scrubbing for E2B process and terminal launchers. */
 
+import { Buffer } from 'node:buffer'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
 import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+/**
+ * Read the remote environment through ASCII base64 so SDK callback chunking cannot corrupt UTF-8.
+ * @param sandbox - shared E2B execution world.
+ * @param signal - optional cancellation for the control-plane request.
+ * @returns the complete NUL-delimited UTF-8 environment.
+ */
+export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
+  const result = await sandbox.commands.run(
+    'set -o pipefail; env -0 | base64 -w 0',
+    signal === undefined ? {} : { signal },
+  )
+  const encoded = result.stdout.trim()
+  if (!BASE64.test(encoded)) throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(encoded, 'base64'))
+  } catch (error: unknown) {
+    throw new Error('subprocess-e2b: remote environment is not valid UTF-8', { cause: error })
+  }
+}
+
 /**
  * Parse an E2B NUL-delimited environment while removing harness-private and credential-shaped names.
  * @param raw - The complete NUL-delimited remote environment.
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index c7d19e0ab8..8c83c4b84b 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -18,7 +18,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { serializeRemoteEnvironment } from './environment.ts'
+import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -198,6 +198,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
   private readonly outputTermination = new AbortController()
+  private readonly startupController = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
@@ -206,6 +207,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private outputTransportError: Error | undefined
   private outputDrainExpired = false
   private stateDirectoryCreated = false
+  private preparing = true
   private invalidHandleQuiescent = false
   private provisionalHandleQuiescent = false
   private terminationStarted = false
@@ -264,6 +266,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   terminate(): void {
     if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
+    if (this.preparing) this.startupController.abort(new Error('subprocess-e2b: command terminated during startup'))
     this.outputTermination.abort()
     this.stdout?.destroy()
     this.stderr?.destroy()
@@ -298,6 +301,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         const attempt = this.terminationAttempt
         if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
         this.throwTerminationFailure()
+        /* v8 ignore else -- successful provisional cleanup always records one proof; failures throw above. */
         if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) {
           this.markQuiescent()
           return true
@@ -351,6 +355,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     try {
       sandbox = await this.runtime.getSandbox()
       await this.prepareState(sandbox)
+      this.preparing = false
       const handle = await sandbox.commands.run(
         commandText(this.spec, this.paths),
         {
@@ -405,7 +410,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
-      this.commandState.resolve(undefined)
+      const canceledPreparation = this.preparing
+        && this.terminationStarted
+        && this.startupController.signal.aborted
       let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
@@ -417,9 +424,12 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           )
         }
       }
+      this.commandState.resolve(undefined)
       this.readyState.reject(failure)
+      if (canceledPreparation && failure === error) return { exitCode: null, signal: 'SIGTERM' }
       throw failure
     } finally {
+      this.preparing = false
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
       this.stderr?.end()
@@ -427,19 +437,21 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
-    const ambient = await sandbox.commands.run('env -0')
-    await sandbox.files.makeDir(this.stateDir)
+    const signal = this.startupController.signal
+    const ambient = await readRemoteEnvironment(sandbox, signal)
+    await sandbox.files.makeDir(this.stateDir, { signal })
     this.stateDirectoryCreated = true
-    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
+    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`, { signal })
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
-      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient.stdout, this.spec.env) },
+      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient, this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
-    await sandbox.files.write(files)
-    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`)
+    await sandbox.files.write(files, { signal })
+    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`, { signal })
+    signal.throwIfAborted()
   }
 
   private async writeBatchStdin(handle: CommandHandle): Promise<void> {
@@ -639,17 +651,23 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       let handleFailure: unknown
       try {
-        await handle.kill()
-        this.provisionalHandleQuiescent = true
+        if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
       } catch (error: unknown) {
         handleFailure = error
       }
-      if (!groupDelivered && handleFailure !== undefined) {
+      if (!groupDelivered && await this.groupAlive(sandbox, handle.pid)) {
         throw new AggregateError(
-          [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
+          [
+            ...(groupFailure === undefined ? [] : [groupFailure]),
+            ...(handleFailure === undefined
+              ? [new Error('E2B SDK kill did not quiesce the provisional process group')]
+              : [handleFailure]),
+          ],
           'subprocess-e2b: force termination failed through both process-group and SDK transports',
         )
       }
+      while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
+      this.provisionalHandleQuiescent = true
       return
     }
     const sandbox = await this.runtime.getSandbox()
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index f918f802ba..9e0258c10d 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -20,7 +20,7 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { serializeRemoteEnvironment } from './environment.ts'
+import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 
 const POLL_MS = 20
 
@@ -355,7 +355,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
         inputWaiting: false,
       }
     } catch (error: unknown) {
-      if (error instanceof CommandExitError && this.topLevelExited) return undefined
+      if (error instanceof CommandExitError && (error.exitCode === 1 || this.topLevelExited)) return undefined
       throw error
     }
   }
@@ -470,8 +470,8 @@ export async function spawnE2BTerminal(
   let completion: Promise<CommandResult> | undefined
   let stateDirectoryCreated = false
   try {
-    const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
-    const environment = serializeRemoteEnvironment(ambient.stdout, spec.env)
+    const ambient = await readRemoteEnvironment(sandbox, spec.signal)
+    const environment = serializeRemoteEnvironment(ambient, spec.env)
     const argv = serializeValues(spec.argv, 'argv')
     await sandbox.files.makeDir(stateDir)
     stateDirectoryCreated = true
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 680d309bbb..d3c96cf2fc 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -39,6 +39,7 @@ class FakeCommandHandle {
   kills = 0
   disconnects = 0
   killError: unknown
+  killResult = true
   disconnectError: unknown
   private readonly result = Promise.withResolvers<CommandResult>()
   private settled = false
@@ -61,7 +62,7 @@ class FakeCommandHandle {
     this.kills += 1
     if (this.killError !== undefined) throw this.killError
     this.onKill()
-    return true
+    return this.killResult
   }
 
   async disconnect(): Promise<void> {
@@ -109,7 +110,9 @@ class FakeSandbox {
   sdkKillStops = true
   alive = true
   zombieOnly = false
-  ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  ambient = 'PATH=/ambient/bin\0KEEP=safe\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  environmentWire: string | undefined
+  environmentRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   processGroupId = '4242\n'
   exitStatus = ''
   readonly processGroupReads: string[] = []
@@ -233,9 +236,14 @@ class FakeSandbox {
     commands: {
       run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
         this.commandsSeen.push(command)
-        if (command === 'env -0') {
+        if (command.includes('env -0 | base64')) {
+          await this.environmentRequest?.(options?.signal)
           if (this.envError !== undefined) throw this.envError
-          return { exitCode: 0, stdout: this.ambient, stderr: '' }
+          return {
+            exitCode: 0,
+            stdout: this.environmentWire ?? Buffer.from(this.ambient).toString('base64'),
+            stderr: '',
+          }
         }
         if (command.startsWith('set -o pipefail; ps -eo pgid=,stat=')) {
           this.beforeProbe?.()
@@ -397,7 +405,7 @@ describe('E2BSubprocessHandle', () => {
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(fake.commandsSeen).toContain('env -0')
+    expect(fake.commandsSeen).toContain('set -o pipefail; env -0 | base64 -w 0')
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
@@ -413,7 +421,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -806,6 +814,33 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('aborts a stalled preparation request before reporting startup quiescence', async () => {
+    const fake = new FakeSandbox()
+    let preparationSignal: AbortSignal | undefined
+    fake.environmentRequest = async (signal) => {
+      preparationSignal = signal
+      await new Promise<never>((_resolve, reject) => {
+        const rejectAbort = (): void => {
+          const reason: unknown = signal?.reason
+          reject(reason instanceof Error ? reason : new Error(String(reason)))
+        }
+        if (signal?.aborted === true) {
+          rejectAbort()
+          return
+        }
+        signal?.addEventListener('abort', rejectAbort, { once: true })
+      })
+    }
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/stalled-preparation')
+    await vi.waitFor(() => { expect(preparationSignal).toBeDefined() })
+
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(preparationSignal?.aborted).toBe(true)
+    expect(fake.startOptions).toBeUndefined()
+  })
+
   it('kills through the provisional SDK handle before process-group publication', async () => {
     const fake = new FakeSandbox()
     fake.deferProcessGroupRead()
@@ -822,6 +857,32 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
   })
 
+  it('does not treat an unsuccessful SDK fallback as provisional group quiescence', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.trapsTerm = true
+    fake.delaysKill = true
+    fake.delaysKillCompletion = true
+    fake.sdkKillStops = false
+    fake.handle.killResult = false
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/provisional-sdk-false')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    let quiescent = false
+    const waiting = handle.waitForExit().then((value) => { quiescent = value })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(quiescent).toBe(false)
+
+    fake.alive = false
+    await waiting
+    expect(quiescent).toBe(true)
+    fake.releaseProcessGroupRead()
+    fake.finish()
+    await handle.done
+  })
+
   it('bounds a quiescence observer while provisional termination is awaiting the controller', async () => {
     const fake = new FakeSandbox()
     fake.deferProcessGroupRead()
@@ -895,6 +956,23 @@ describe('E2BSubprocessHandle', () => {
     await expect(absentHandle.waitForExit()).resolves.toBe(true)
     absentGroup.releaseProcessGroupRead()
     await absentHandle.done
+
+    const optimisticSdk = new FakeSandbox()
+    optimisticSdk.deferProcessGroupRead()
+    optimisticSdk.signalErrors.push(commandError(1), commandError(1))
+    optimisticSdk.sdkKillStops = false
+    const optimisticHandle = new E2BSubprocessHandle(
+      runtime(optimisticSdk),
+      spec({ graceMs: 1 }),
+      '/runtime/pre-publication-optimistic-sdk',
+    )
+    await vi.waitFor(() => { expect(optimisticSdk.startOptions).toBeDefined() })
+    optimisticHandle.terminate()
+    await expect(optimisticHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    optimisticHandle.terminate()
+    await expect(optimisticHandle.waitForExit()).resolves.toBe(true)
+    optimisticSdk.releaseProcessGroupRead()
+    await optimisticHandle.done
   })
 
   it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
@@ -1024,6 +1102,24 @@ describe('E2BSubprocessHandle', () => {
     await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
     expect(envFailure.removed).toEqual([])
 
+    const malformedEnvironment = new FakeSandbox()
+    malformedEnvironment.environmentWire = '%'
+    const malformedEnvironmentHandle = new E2BSubprocessHandle(
+      runtime(malformedEnvironment),
+      spec(),
+      '/runtime/malformed-environment',
+    )
+    await expect(malformedEnvironmentHandle.done).rejects.toThrow('invalid base64')
+
+    const invalidUtf8Environment = new FakeSandbox()
+    invalidUtf8Environment.environmentWire = Buffer.from([0xff]).toString('base64')
+    const invalidUtf8EnvironmentHandle = new E2BSubprocessHandle(
+      runtime(invalidUtf8Environment),
+      spec(),
+      '/runtime/invalid-utf8-environment',
+    )
+    await expect(invalidUtf8EnvironmentHandle.done).rejects.toThrow('not valid UTF-8')
+
     const cleanupFailure = new FakeSandbox()
     cleanupFailure.backgroundError = new Error('start failed before credential consumption')
     cleanupFailure.nextRemoveError = new Error('credential cleanup failed')
@@ -1509,6 +1605,7 @@ describe('E2BSubprocessService', () => {
     const { ctx, fiber } = await service(fake)
     const subprocess = ctx.subprocess
     const handle = subprocess.spawn(spec())
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
     const disposing = fiber.dispose()
     await flush()
     expect(() => subprocess.spawn(spec())).toThrow('service is disposing')
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index c6ec5bfaad..00b9fc41fc 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -89,7 +89,7 @@ class FakeTerminalSandbox {
   readonly directories: string[] = []
   readonly writes = new Map<string, string>()
   createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
-  ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  ambient = 'KEEP=visible\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   ready: string | Error = 'ready\n'
   readyMisses = 0
   readyReads = 0
@@ -162,7 +162,9 @@ class FakeTerminalSandbox {
           this.commandFailure = undefined
           throw error
         }
-        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        if (command.includes('env -0 | base64')) {
+          return { exitCode: 0, stdout: Buffer.from(this.ambient).toString('base64'), stderr: '' }
+        }
         if (command.includes('command -v -- ')) {
           return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
         }
@@ -263,6 +265,7 @@ describe('E2B terminal allocation', () => {
     expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
     expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('UNICODE=你好\0')
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('TOKEN_EXPLICIT=kept\0')
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
@@ -653,6 +656,8 @@ describe('E2B terminal lifecycle', () => {
     fake.foreground = 'invalid\n'
     await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
     fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+    fake.foregroundFailure = commandError(2)
     await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
     fake.clearOnTerm = true
     terminal.terminate()

From 81e2e1f647b07b20ec7974176770fdd9a7764c64 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 15:30:32 +0800
Subject: [PATCH 125/262] fix(e2b): harden SDK shell and cleanup boundaries

E2B starts command and PTY requests through login shells, so isolate each control shell behind a fresh randomized HOME and blank sandbox credential names before mutable profiles can run. Preserve the real remote HOME only for the requested argv.

Collapse duplicate termination state, keep failed force cleanup retryable until quiescence is observed, and make terminal state allocation cancellable. Leave numeric PGID reuse as an explicit provider-level TODO because a userspace precheck would remain TOCTOU.
---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   4 +-
 docs/cordis-catalog/services.md               |   2 +-
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |  17 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  26 ++-
 packages/e2b/e2b/tests/e2b.spec.ts            |  27 ++-
 packages/e2b/fs-e2b/src/index.ts              |  15 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |   8 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   4 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  57 ++++--
 packages/e2b/subprocess-e2b/src/index.ts      |   6 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 182 ++++++++----------
 packages/e2b/subprocess-e2b/src/terminal.ts   |  99 +++++++---
 .../subprocess-e2b/tests/subprocess.spec.ts   | 127 ++++++++----
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  51 ++++-
 21 files changed, 438 insertions(+), 211 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 1343d33032..2c3db3fad4 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: cccee91998e832cc9cf53e554e104ccc5caada38
-2026-07-27-e2b-remote-runtime-poc.zh.md: b1a30c92e313b1395006ebd4fd17eacda2546ad5
+2026-07-27-e2b-remote-runtime-poc.md: 79c5bfe2dfa11cd695c7134e6ceffb639b449688
+2026-07-27-e2b-remote-runtime-poc.zh.md: 729a10ec7efa4dd55f041dc804d2252102b13c01
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index cccee91998..79c5bfe2df 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -28,7 +28,7 @@ E2B owns the mutable filesystem, managed command and Bash processes, terminal al
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. Ambient environments and ordinary command pipes cross decoded SDK callback boundaries as ASCII/base64 before strict UTF-8 or raw-byte restoration; startup preparation carries the handle's owned cancellation signal, and provisional termination proves the remote group empty after SDK fallback. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
+The fundamental adapters carry the substrate-specific mechanics. Adapter-internal E2B command and PTY login shells use a fresh randomized root-level `HOME`; `dsh-subprocess-e2b` also gives them empty overrides for scrubbed credential names before user profiles run. The subprocess adapter consumes E2B's byte PTY callback, transports environment snapshots and command bytes as ASCII/base64 across decoded SDK callbacks, and uses one cancellation controller plus one retryable group-cleanup transaction that reports success only after proving quiescence. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated newline-delimited UTF-8 JSON and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -38,7 +38,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, hostile command and PTY login-profile isolation, default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index b1a30c92e3..729a10ec7e 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -28,7 +28,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。环境快照与普通命令管道会先以 ASCII/base64 跨越已解码的 SDK 回调边界，再执行严格 UTF-8 解码或恢复原始字节；启动准备会携带句柄自有的取消信号，临时终止则会在 SDK 回退后证明远程进程组为空。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
+基础适配器承载基底专用机制。适配器内部的 E2B 命令与 PTY 登录 shell 使用位于根目录下、全新随机生成的 `HOME`；在用户 profile 脚本运行前，`dsh-subprocess-e2b` 还会为它们设置已清理凭据名称的空值覆盖。该子进程适配器消费 E2B 的字节 PTY 回调，以 ASCII/base64 跨越已解码的 SDK 回调传输环境快照与命令字节，并使用一个取消控制器与一个可重试的进程组清理事务，后者只有在证明完全停稳后才报告成功。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 以经过验证、由换行符分隔的 UTF-8 JSON 承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -38,7 +38,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、恶意命令与 PTY 登录 profile 隔离、默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7ce45c6817..cdd2d87435 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:109`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 2fc8d403d1..fb645c2e36 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 6eb7d69dd6355de870db6bf05540f2629f464bc8
-README.zh.md: b2e2616cf779bce659fdef58840aa51f095a73cf
+README.md: 402903184934903eceb36a04d670e4490879ac65
+README.zh.md: 1fec6ab66858f04a47c8a2a7cb5f6a8907ab6cac
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 6eb7d69dd6..4029031849 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -28,7 +28,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 ## Lifecycle and ownership
 
-Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
 Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` is accepted when disposal requests `kill`, or when this service created a sandbox with `onTimeout: kill`; otherwise, a not-found error from a requested `pause` rejects teardown because retention was not proved. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index b2e2616cf7..1fec6ab668 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -28,7 +28,7 @@
 
 ## 生命周期与所有权
 
-构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
 资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 仅在资源释放请求 `kill`，或本服务创建了配置为 `onTimeout: kill` 的沙箱时才可接受；否则，`pause` 请求返回的未找到错误会导致 teardown 拒绝，因为无法证明保留成功。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 150961a897..9e8960a685 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -4,6 +4,7 @@
  * @module @deepseek-ai/dsh-e2b
  */
 
+import { randomUUID } from 'node:crypto'
 import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
@@ -42,6 +43,17 @@ export function quoteE2BShellArg(value: string): string {
   return `'${value.replaceAll('\'', "'\"'\"'")}'`
 }
 
+/**
+ * Isolate E2B's hard-coded login shell behind a fresh randomized home path.
+ * @param overrides - Additional environment entries for the internal command.
+ * @returns A fresh mutable map that the E2B SDK may extend.
+ */
+export function e2bControlEnvs(
+  overrides: Readonly<Record<string, string>> = {},
+): Record<string, string> {
+  return { ...overrides, HOME: `/.dsh-e2b-control-${randomUUID()}` }
+}
+
 /** Action taken on the owned sandbox when the Cordis service is disposed. */
 export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
 
@@ -249,7 +261,10 @@ export class E2BSandboxService extends Service {
       if (runtimeRoot.type !== FileType.DIR || runtimeRoot.symlinkTarget !== undefined) {
         throw new Error(`dsh-e2b: runtime root must be a real directory: ${this.runtimeRoot}`)
       }
-      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`)
+      await sandbox.commands.run(
+        `chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`,
+        { envs: e2bControlEnvs() },
+      )
       return sandbox
     } catch (error: unknown) {
       if (this.created) {
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 34875d5153..f9fcbfae8a 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -5,7 +5,12 @@ import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import E2BSandboxService, { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import E2BSandboxService, {
+  e2bControlEnvs,
+  FileNotFoundError,
+  Sandbox,
+  SandboxNotFoundError,
+} from '@deepseek-ai/dsh-e2b'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -17,7 +22,7 @@ const configPath = join(fixtureRoot, 'cordis.yml')
 const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
-  it('scrubs sandbox-default credentials from an actual E2B PTY', async () => {
+  it('scrubs credentials before actual E2B command and PTY login shells', async () => {
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared before the PTY environment test')
     const sandbox = await Sandbox.create({
@@ -28,6 +33,18 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       lifecycle: { onTimeout: 'kill' },
     })
     try {
+      const profileLeakPath = '/home/user/dsh-e2b-bootstrap-profile-leak'
+      const hostileProfile = [
+        'if [[ "${NPM_TOKEN-}" == "sentinel-secret" ]]; then',
+        `  printf leaked > ${profileLeakPath}`,
+        'fi',
+        '',
+      ].join('\n')
+      await sandbox.files.write([
+        { path: '/home/user/.bash_profile', data: hostileProfile },
+        { path: '/home/user/.profile', data: hostileProfile },
+        { path: '/home/user/.bashrc', data: hostileProfile },
+      ])
       const ctx = new Context()
       ctx.provide('e2b', {
         cwd: '/home/user',
@@ -43,6 +60,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       const node = await ctx.subprocess.resolveExecutable('node')
       const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
       await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const environmentProbe = ctx.subprocess.spawn({
         argv: ['/bin/bash', '-c', [
           'dsh_leak=0',
@@ -59,6 +77,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       })
       await expect(environmentProbe.done).resolves.toEqual({ exitCode: 0, signal: null })
       expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
@@ -89,6 +108,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       expect(result.viewport).toContain('NPM=<> DSH=<> KEEP=<visible>')
       expect(result.viewport).not.toContain('sentinel-secret')
       expect(result.viewport).not.toContain('sentinel-stale')
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       await session.close('environment test complete')
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
@@ -98,7 +118,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         'mkdir -p -- /home/user/dsh-e2b-runtime-target',
         'chmod 755 -- /home/user/dsh-e2b-runtime-target',
         'ln -s -- /home/user/dsh-e2b-runtime-target /home/user/.dsh-e2b',
-      ].join('\n'))
+      ].join('\n'), { envs: e2bControlEnvs({ NPM_TOKEN: '' }) })
       const linkedCtx = new Context()
       const linkedFiber = await linkedCtx.plugin(E2BSandboxService, {
         apiKey,
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index a4eba5ebc9..46ba452210 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -1,7 +1,9 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Mock } from 'vitest'
 import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
+  e2bControlEnvs,
   E2BSandboxId,
   FileType,
   SandboxNotFoundError,
@@ -35,15 +37,20 @@ interface SandboxFixture {
   sandbox: SandboxType
   makeDir: ReturnType<typeof vi.fn>
   getInfo: ReturnType<typeof vi.fn>
-  run: ReturnType<typeof vi.fn>
+  run: Mock<RunCommand>
   kill: ReturnType<typeof vi.fn>
   pause: ReturnType<typeof vi.fn>
 }
 
+type RunCommand = (
+  command: string,
+  options?: { envs?: Record<string, string> },
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>
+
 function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
   const makeDir = vi.fn().mockResolvedValue(true)
   const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
-  const run = vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
+  const run = vi.fn<RunCommand>().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
   const kill = vi.fn().mockResolvedValue(undefined)
   const pause = vi.fn().mockResolvedValue(true)
   const sandbox = {
@@ -63,6 +70,15 @@ beforeEach(() => {
 })
 
 describe('E2BSandboxService', () => {
+  it('gives each SDK login shell a fresh non-overridable control home', () => {
+    const first = e2bControlEnvs({ HOME: '/hostile', NPM_TOKEN: '' })
+    const second = e2bControlEnvs()
+
+    expect(first.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(first).toEqual({ HOME: first.HOME, NPM_TOKEN: '' })
+    expect(first.HOME).not.toBe(second.HOME)
+  })
+
   it('creates one protected shared sandbox and kills it on default disposal', async () => {
     const fixture = fakeSandbox()
     sdk.create.mockResolvedValue(fixture.sandbox)
@@ -86,7 +102,12 @@ describe('E2BSandboxService', () => {
     expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
     expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
     expect(fixture.getInfo).toHaveBeenCalledWith('/home/user/workspace/.dsh-e2b')
-    expect(fixture.run).toHaveBeenCalledWith("chmod 700 -- '/home/user/workspace/.dsh-e2b'")
+    const runOptions = fixture.run.mock.calls[0]?.[1]
+    expect(runOptions?.envs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(fixture.run).toHaveBeenCalledWith(
+      "chmod 700 -- '/home/user/workspace/.dsh-e2b'",
+      { envs: { HOME: runOptions?.envs?.HOME } },
+    )
 
     await fiber.dispose()
     expect(fixture.kill).toHaveBeenCalledOnce()
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index d41c2e3d32..7c81791d55 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -20,6 +20,7 @@ import type {
 } from '@deepseek-ai/dsh-fs'
 import {
   CommandExitError,
+  e2bControlEnvs,
   FileNotFoundError,
   FileType,
   quoteE2BShellArg,
@@ -71,6 +72,10 @@ function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal }
 }
 
+function commandOpts(signal: AbortSignal | undefined): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(), ...signalOpts(signal) }
+}
+
 function entryType(entry: EntryInfo): FsInfo['type'] {
   switch (entry.type) {
     case FileType.FILE:
@@ -215,7 +220,7 @@ export class E2BFileSystem extends FileSystem {
     assertNotAborted(signal, 'read')
     const sandbox = await this.ctx.e2b.getSandbox()
     try {
-      const node = await sandbox.commands.run('command -v -- node', signalOpts(signal))
+      const node = await sandbox.commands.run('command -v -- node', commandOpts(signal))
       const executable = node.stdout.trim()
       if (!posix.isAbsolute(executable) || executable.includes('\n')) {
         throw new Error('fs-e2b: bounded reader requires one absolute Node executable')
@@ -228,7 +233,7 @@ export class E2BFileSystem extends FileSystem {
         quoteE2BShellArg(this.processPath(target)),
         String(maxBytes),
       ].join(' ')
-      const result = await sandbox.commands.run(command, signalOpts(signal))
+      const result = await sandbox.commands.run(command, commandOpts(signal))
       assertNotAborted(signal, 'read')
       const response = this.parseBoundedRead(result.stdout, target)
       if (response.kind === 'not-file') {
@@ -415,7 +420,7 @@ export class E2BFileSystem extends FileSystem {
 
   private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
     try {
-      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, signalOpts(signal))
+      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, commandOpts(signal))
       return result.stdout.replace(/\n$/, '')
     } catch (error: unknown) {
       if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
@@ -505,7 +510,7 @@ export class E2BFileSystem extends FileSystem {
       const created = await sandbox.files.makeDir(stagingDirectory, signalOpts(signal))
       if (!created) throw new Error('private staging directory already exists')
       stagingDirectoryCreated = true
-      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, signalOpts(signal))
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, commandOpts(signal))
       assertNotAborted(signal, 'write')
       await sandbox.files.write(temporary, content, {
         metadata: { [VERSION_METADATA_KEY]: versionId },
@@ -515,7 +520,7 @@ export class E2BFileSystem extends FileSystem {
       const mode = existing === undefined ? 0o600 : existing.mode & 0o777
       await sandbox.commands.run(
         `chmod ${mode.toString(8)} -- ${quoteE2BShellArg(temporary)}`,
-        signalOpts(signal),
+        commandOpts(signal),
       )
       assertNotAborted(signal, 'write')
       const committed = await sandbox.files.rename(temporary, targetPath)
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 1689fb4023..23835e9967 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -225,8 +225,14 @@ class FakeRemote {
       },
     },
     commands: {
-      run: async (command: string, options?: { signal?: AbortSignal }): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
+      run: async (
+        command: string,
+        options?: { envs?: Record<string, string>; signal?: AbortSignal },
+      ): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
         this.checkAbort(options)
+        const home = options?.envs?.HOME
+        expect(home).toMatch(/^\/\.dsh-e2b-control-/)
+        expect(options?.envs).toEqual({ HOME: home })
         this.commands.push(command)
         if (this.nextCommandError !== undefined) {
           const error = this.nextCommandError
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 3f64c67b7e..ac7b8d42a5 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: aaac559e60162c3051cc6f06cbcfac011f5eb59a
-README.zh.md: 904e4fd1d9a13082ddfc8183c0e42abc25bd1caf
+README.md: 9b86af428533ebcc2c0da56339e6ea2a28170fd3
+README.zh.md: e3e8368534266e35ec04dcf5a2d6718829b4a016
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index aaac559e60..9b86af4285 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,8 +8,8 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses both the provisional group and SDK handle and proves the group empty before reporting quiescence; if publication fails, rollback applies the same proof before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. E2B's fixed command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 904e4fd1d9..e3e8368534 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,8 +8,8 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作会同时使用临时进程组与 SDK 句柄，并在报告完全停稳前证明进程组为空；如果发布失败，回滚会在启动拒绝前执行相同证明。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，E2B 固定的命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 2b2516a706..5322491261 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -1,11 +1,24 @@
 /** Shared remote-environment scrubbing for E2B process and terminal launchers. */
 
 import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import { e2bControlEnvs } from '@deepseek-ai/dsh-e2b'
 import type { Sandbox } from '@deepseek-ai/dsh-e2b'
 import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 
 const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
 
+function remoteEnvironmentEntries(raw: string): Array<readonly [string, string]> {
+  const entries: Array<readonly [string, string]> = []
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    entries.push([entry.slice(0, separator), entry.slice(separator + 1)])
+  }
+  return entries
+}
+
 /**
  * Read the remote environment through ASCII base64 so SDK callback chunking cannot corrupt UTF-8.
  * @param sandbox - shared E2B execution world.
@@ -14,16 +27,29 @@ const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
  */
 export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
   const result = await sandbox.commands.run(
-    'set -o pipefail; env -0 | base64 -w 0',
-    signal === undefined ? {} : { signal },
+    'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
   )
-  const encoded = result.stdout.trim()
-  if (!BASE64.test(encoded)) throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  const lines = result.stdout.trim().split('\n')
+  if (lines.length !== 2 || !lines.every(line => BASE64.test(line))) {
+    throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  }
+  const [encodedHome, encodedEnvironment] = lines as [string, string]
+  let home: string
+  let raw: string
   try {
-    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(encoded, 'base64'))
+    const decoder = new TextDecoder('utf-8', { fatal: true })
+    home = decoder.decode(Buffer.from(encodedHome, 'base64'))
+    raw = decoder.decode(Buffer.from(encodedEnvironment, 'base64'))
   } catch (error: unknown) {
     throw new Error('subprocess-e2b: remote environment is not valid UTF-8', { cause: error })
   }
+  if (!posix.isAbsolute(home) || home.includes('\0')) {
+    throw new Error(`subprocess-e2b: remote login home is invalid: ${JSON.stringify(home)}`)
+  }
+  const environment = new Map(remoteEnvironmentEntries(raw))
+  environment.set('HOME', home)
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
 
 /**
@@ -33,13 +59,22 @@ export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSign
  */
 export function scrubRemoteEnvironment(raw: string): Map<string, string> {
   const environment = new Map<string, string>()
-  for (const entry of raw.split('\0')) {
-    if (entry.length === 0) continue
-    const separator = entry.indexOf('=')
-    if (separator <= 0) continue
-    const name = entry.slice(0, separator)
+  for (const [name, value] of remoteEnvironmentEntries(raw)) {
     if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
-    environment.set(name, entry.slice(separator + 1))
+    environment.set(name, value)
+  }
+  return environment
+}
+
+/**
+ * Isolate E2B's fixed login-shell bootstrap from user profiles and ambient credentials.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Explicit E2B command or PTY overrides for bootstrap-shell startup.
+ */
+export function bootstrapEnvironment(raw: string): Record<string, string> {
+  const environment: Record<string, string> = { TERM: 'dumb' }
+  for (const [name] of remoteEnvironmentEntries(raw)) {
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) environment[name] = ''
   }
   return environment
 }
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 4516bffa84..7318dfde95 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -14,7 +14,7 @@ import type {
   SubprocessTerminalHandle,
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
-import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
+import { e2bControlEnvs, quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import { E2BSubprocessHandle } from './process.ts'
 import { spawnE2BTerminal } from './terminal.ts'
 
@@ -86,7 +86,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (posix.isAbsolute(command)) {
       await sandbox.commands.run(
         `test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`,
-        signalOpts(signal),
+        { envs: e2bControlEnvs(), ...signalOpts(signal) },
       )
       signal?.throwIfAborted()
       return command
@@ -95,7 +95,7 @@ export class E2BSubprocessService extends SubprocessService {
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
       `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
-      { cwd: this.cwd, ...signalOpts(signal) },
+      { cwd: this.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
     )
     signal?.throwIfAborted()
     const executable = result.stdout.trim()
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 8c83c4b84b..6b17f3b682 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -5,6 +5,7 @@ import { PassThrough, Writable } from 'node:stream'
 import { posix } from 'node:path'
 import {
   CommandExitError,
+  e2bControlEnvs,
   FileNotFoundError,
   SandboxNotFoundError,
   quoteE2BShellArg,
@@ -18,7 +19,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
+import { bootstrapEnvironment, readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -142,8 +143,11 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   return bootstrap
 }
 
-function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
-  return signal === undefined ? {} : { signal }
+function commandOpts(
+  envs: Record<string, string>,
+  signal: AbortSignal | undefined,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...(signal === undefined ? {} : { signal }) }
 }
 
 function isAborted(signal: AbortSignal | undefined): boolean {
@@ -197,21 +201,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly readyState = Promise.withResolvers<CommandHandle>()
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
-  private readonly outputTermination = new AbortController()
-  private readonly startupController = new AbortController()
+  private readonly terminationController = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
+  private controlEnvs: Record<string, string> = {}
   private remotePid = -1
   private commandHandle: CommandHandle | undefined
   private outputTransportError: Error | undefined
   private outputDrainExpired = false
   private stateDirectoryCreated = false
   private preparing = true
-  private invalidHandleQuiescent = false
-  private provisionalHandleQuiescent = false
   private terminationStarted = false
-  private terminationFenced = false
   private quiescenceProven = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
@@ -264,20 +265,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
+    if (this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
-    if (this.preparing) this.startupController.abort(new Error('subprocess-e2b: command terminated during startup'))
-    this.outputTermination.abort()
+    this.terminationController.abort(new Error('subprocess-e2b: command terminated'))
     this.stdout?.destroy()
     this.stderr?.destroy()
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
     void attempt.then(
-      () => {
-        this.terminationFenced = true
-        this.terminationAttempt = undefined
-      },
+      () => { this.terminationAttempt = undefined },
       (error: unknown) => {
         if (!this.quiescenceProven) this.terminationFailure = asError(error)
         this.terminationAttempt = undefined
@@ -301,11 +298,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         const attempt = this.terminationAttempt
         if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
         this.throwTerminationFailure()
-        /* v8 ignore else -- successful provisional cleanup always records one proof; failures throw above. */
-        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) {
-          this.markQuiescent()
-          return true
-        }
+        // Successful pre-publication termination records quiescence; its only other outcome is the failure above.
+        return true
       }
     } else {
       try {
@@ -361,6 +355,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         {
           background: true,
           cwd: this.spec.cwd,
+          envs: e2bControlEnvs(this.controlEnvs),
           stdin: this.spec.stdio.stdin !== 'ignore',
           timeoutMs: 0,
           onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
@@ -374,7 +369,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         const invalidPid = new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
         try {
           await handle.kill()
-          this.invalidHandleQuiescent = true
+          this.markQuiescent()
           this.commandHandle = undefined
         } catch (cleanupError: unknown) {
           this.terminationFailure = asError(cleanupError)
@@ -412,7 +407,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     } catch (error: unknown) {
       const canceledPreparation = this.preparing
         && this.terminationStarted
-        && this.startupController.signal.aborted
+        && this.terminationController.signal.aborted
       let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
@@ -437,11 +432,15 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
-    const signal = this.startupController.signal
+    const signal = this.terminationController.signal
     const ambient = await readRemoteEnvironment(sandbox, signal)
+    this.controlEnvs = bootstrapEnvironment(ambient)
     await sandbox.files.makeDir(this.stateDir, { signal })
     this.stateDirectoryCreated = true
-    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`, { signal })
+    await sandbox.commands.run(
+      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
+      commandOpts(this.controlEnvs, signal),
+    )
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
@@ -450,7 +449,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
     await sandbox.files.write(files, { signal })
-    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`, { signal })
+    await sandbox.commands.run(
+      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
+      commandOpts(this.controlEnvs, signal),
+    )
     signal.throwIfAborted()
   }
 
@@ -490,7 +492,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
     const target = pipe ?? inherited
-    if (target === undefined || data.length === 0 || this.outputTermination.signal.aborted) return
+    if (target === undefined || data.length === 0 || this.terminationController.signal.aborted) return
     if (target.destroyed) throw new Error('subprocess output stream is closed')
     if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
@@ -502,13 +504,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         target.removeListener('drain', onDrain)
         target.removeListener('close', onClose)
         target.removeListener('error', onError)
-        this.outputTermination.signal.removeEventListener('abort', onTermination)
+        this.terminationController.signal.removeEventListener('abort', onTermination)
       }
       target.once('drain', onDrain)
       target.once('close', onClose)
       target.once('error', onError)
-      this.outputTermination.signal.addEventListener('abort', onTermination, { once: true })
-      if (this.outputTermination.signal.aborted) onTermination()
+      this.terminationController.signal.addEventListener('abort', onTermination, { once: true })
+      if (this.terminationController.signal.aborted) onTermination()
     })
   }
 
@@ -596,12 +598,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     // `setsid`, so E2B's command PID is the provisional group id even before the
     // private publication file can be trusted. Kill that group before the SDK-PID
     // fallback, then prove no group member survived before rejecting startup.
-    try {
-      await this.signalGroup(sandbox, handle.pid, 'KILL')
-    } finally {
-      await handle.kill().catch(() => false)
-    }
-    while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
+    await this.forceKillGroup(sandbox, handle, handle.pid)
+    this.markQuiescent()
   }
 
   private async terminateRemote(): Promise<void> {
@@ -618,91 +616,76 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async terminateRemoteInSandbox(): Promise<void> {
     const handle = await this.commandState.promise
-    if (handle === undefined) return
+    if (handle === undefined) {
+      this.markQuiescent()
+      return
+    }
     if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
       await handle.kill()
-      this.invalidHandleQuiescent = true
+      this.markQuiescent()
       this.commandHandle = undefined
       return
     }
-    if (this.remotePid <= 0) {
-      const sandbox = await this.runtime.getSandbox()
-      this.terminationSignal = 'SIGTERM'
-      try {
-        const delivered = await this.signalGroup(sandbox, handle.pid, 'TERM')
-        if (delivered) {
-          const deadline = Date.now() + this.spec.graceMs
-          while (Date.now() < deadline && await this.groupAlive(sandbox, handle.pid)) await waitTick()
-          if (!await this.groupAlive(sandbox, handle.pid)) {
-            this.provisionalHandleQuiescent = true
-            return
-          }
-        }
-      } catch (_gracefulTerminationFailure) {
-        // A missing or unobservable provisional group still has the SDK handle fallback.
-      }
-      this.terminationSignal = 'SIGKILL'
-      let groupDelivered = false
-      let groupFailure: unknown
-      try {
-        groupDelivered = await this.signalGroup(sandbox, handle.pid, 'KILL')
-      } catch (error: unknown) {
-        groupFailure = error
-      }
-      let handleFailure: unknown
-      try {
-        if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
-      } catch (error: unknown) {
-        handleFailure = error
-      }
-      if (!groupDelivered && await this.groupAlive(sandbox, handle.pid)) {
-        throw new AggregateError(
-          [
-            ...(groupFailure === undefined ? [] : [groupFailure]),
-            ...(handleFailure === undefined
-              ? [new Error('E2B SDK kill did not quiesce the provisional process group')]
-              : [handleFailure]),
-          ],
-          'subprocess-e2b: force termination failed through both process-group and SDK transports',
-        )
-      }
-      while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
-      this.provisionalHandleQuiescent = true
-      return
-    }
     const sandbox = await this.runtime.getSandbox()
-    const processGroupId = this.remotePid
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
+    await this.terminateGroup(sandbox, handle, processGroupId)
+  }
+
+  private async terminateGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     this.terminationSignal = 'SIGTERM'
     try {
       await this.signalGroup(sandbox, processGroupId, 'TERM')
-      const deadline = Date.now() + this.spec.graceMs
-      while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
-        await waitTick()
+      if (await this.waitForGroupExit(sandbox, processGroupId)) {
+        this.markQuiescent()
+        return
       }
-      if (!await this.groupAlive(sandbox, processGroupId)) return
     } catch (_gracefulTerminationFailure) {
       // Failed TERM delivery or observation cannot prove exit; force cleanup still owns the group.
     }
     this.terminationSignal = 'SIGKILL'
+    await this.forceKillGroup(sandbox, handle, processGroupId)
+    this.markQuiescent()
+  }
+
+  private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     let groupFailure: unknown
-    let groupDelivered = false
     try {
-      groupDelivered = await this.signalGroup(sandbox, processGroupId, 'KILL')
+      if (!await this.signalGroup(sandbox, processGroupId, 'KILL')) {
+        groupFailure = new Error('process-group KILL did not report delivery')
+      }
     } catch (error: unknown) {
       groupFailure = error
     }
     let handleFailure: unknown
     try {
-      await handle.kill()
+      if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
     } catch (error: unknown) {
       handleFailure = error
     }
-    if (!groupDelivered && handleFailure !== undefined && await this.groupAlive(sandbox, processGroupId)) {
-      throw new AggregateError(
-        [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
-        'subprocess-e2b: force termination failed through both process-group and SDK transports',
-      )
+    let proofFailure: unknown
+    try {
+      if (await this.waitForGroupExit(sandbox, processGroupId)) return
+      proofFailure = new Error(`remote process group ${processGroupId} remained live after force termination`)
+    } catch (error: unknown) {
+      proofFailure = error
     }
+    throw new AggregateError(
+      [
+        ...(groupFailure === undefined ? [] : [groupFailure]),
+        ...(handleFailure === undefined ? [] : [handleFailure]),
+        proofFailure,
+      ],
+      'subprocess-e2b: force termination failed through both process-group and SDK transports',
+    )
+  }
+
+  private async waitForGroupExit(sandbox: Sandbox, processGroupId: number): Promise<boolean> {
+    const deadline = Date.now() + this.spec.graceMs
+    while (await this.groupAlive(sandbox, processGroupId)) {
+      if (Date.now() >= deadline) return false
+      await waitTick()
+    }
+    return true
   }
 
   private throwTerminationFailure(): void {
@@ -710,8 +693,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<boolean> {
+    // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
+    // a userspace identity precheck cannot close the numeric-PGID reuse race.
     try {
-      await sandbox.commands.run(`kill -${signal} -- -${pid}`)
+      await sandbox.commands.run(
+        `kill -${signal} -- -${pid}`,
+        commandOpts(this.controlEnvs, undefined),
+      )
       return true
     } catch (error: unknown) {
       if (error instanceof CommandExitError || error instanceof SandboxNotFoundError) return false
@@ -722,7 +710,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
     const result = await sandbox.commands.run(
       `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
-      signalOpts(signal),
+      commandOpts(this.controlEnvs, signal),
     ).catch((error: unknown) => {
       if (signal?.aborted === true) return undefined
       if (error instanceof SandboxNotFoundError) return { exitCode: 0, stdout: '', stderr: '' }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 9e0258c10d..ff8af60da9 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -6,6 +6,7 @@ import { PassThrough } from 'node:stream'
 import { posix } from 'node:path'
 import {
   CommandExitError,
+  e2bControlEnvs,
   FileNotFoundError,
   SandboxNotFoundError,
   quoteE2BShellArg,
@@ -20,7 +21,11 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
+import {
+  bootstrapEnvironment,
+  readRemoteEnvironment,
+  serializeRemoteEnvironment,
+} from './environment.ts'
 
 const POLL_MS = 20
 
@@ -54,6 +59,13 @@ function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal }
 }
 
+function commandOpts(
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
+}
+
 function delay(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
@@ -143,8 +155,13 @@ function serializeValues(values: readonly string[], kind: string): string {
   return values.map(value => `${value}\0`).join('')
 }
 
-async function terminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
-  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, signalOpts(signal))
+async function terminalSessionId(
+  sandbox: Sandbox,
+  pid: number,
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): Promise<number> {
+  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, commandOpts(envs, signal))
   signal?.throwIfAborted()
   return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
 }
@@ -169,11 +186,16 @@ async function waitUntilReady(
   }
 }
 
-async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
+async function sessionProcessGroups(
+  sandbox: Sandbox,
+  sessionId: number,
+  envs: Record<string, string>,
+): Promise<number[]> {
   let result: CommandResult
   try {
     result = await sandbox.commands.run(
       `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
+      commandOpts(envs),
     )
   } catch (error: unknown) {
     if (error instanceof SandboxNotFoundError) return []
@@ -194,9 +216,17 @@ async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promis
   return [...groups]
 }
 
-async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+async function signalGroups(
+  sandbox: Sandbox,
+  groups: number[],
+  signal: 'TERM' | 'KILL',
+  envs: Record<string, string>,
+): Promise<void> {
   try {
-    await sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
+    await sandbox.commands.run(
+      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
+      commandOpts(envs),
+    )
   } catch (error: unknown) {
     if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
   }
@@ -205,14 +235,15 @@ async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' |
 async function awaitSessionEmpty(
   sandbox: Sandbox,
   sessionId: number,
+  envs: Record<string, string>,
   graceMs: number,
   kill = false,
 ): Promise<number[]> {
   const deadline = Date.now() + graceMs
   for (;;) {
-    const groups = await sessionProcessGroups(sandbox, sessionId)
+    const groups = await sessionProcessGroups(sandbox, sessionId, envs)
     if (groups.length === 0 || Date.now() >= deadline) return groups
-    if (kill) await signalGroups(sandbox, groups, 'KILL')
+    if (kill) await signalGroups(sandbox, groups, 'KILL', envs)
     await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
   }
 }
@@ -221,6 +252,7 @@ async function rollbackUnpublishedTerminal(
   sandbox: Sandbox,
   handle: CommandHandle,
   completion: Promise<CommandResult>,
+  envs: Record<string, string>,
   graceMs: number,
 ): Promise<void> {
   let topLevelExited = false
@@ -234,20 +266,20 @@ async function rollbackUnpublishedTerminal(
   if (validPid) {
     sessionId = handle.pid
     try {
-      sessionId = await terminalSessionId(sandbox, handle.pid)
+      sessionId = await terminalSessionId(sandbox, handle.pid, envs)
     } catch (_sessionLookupFailure) {
       // E2B's PTY leader is also the provisional POSIX session leader, so its
       // PID remains usable after the setup lookup itself fails or is canceled.
     }
     try {
-      let groups = await sessionProcessGroups(sandbox, sessionId)
+      let groups = await sessionProcessGroups(sandbox, sessionId, envs)
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'TERM')
-        groups = await awaitSessionEmpty(sandbox, sessionId, graceMs)
+        await signalGroups(sandbox, groups, 'TERM', envs)
+        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs)
       }
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'KILL')
-        await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+        await signalGroups(sandbox, groups, 'KILL', envs)
+        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
       }
     } catch (error: unknown) {
       attemptFailures.push(asError(error))
@@ -279,7 +311,7 @@ async function rollbackUnpublishedTerminal(
   const proofFailures: Error[] = []
   if (sessionId !== undefined) {
     try {
-      const groups = await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
       if (groups.length > 0) {
         proofFailures.push(new Error(
           `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
@@ -322,6 +354,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     readonly output: PassThrough,
     private readonly completion: Promise<CommandResult>,
     private readonly sessionId: number,
+    private readonly controlEnvs: Record<string, string>,
     private readonly stateDir: string,
     private readonly graceMs: number,
     signal?: AbortSignal,
@@ -344,7 +377,10 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   /** @inheritdoc */
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
     try {
-      const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
+      const result = await this.sandbox.commands.run(
+        `ps -o tpgid= -p ${this.pid}`,
+        commandOpts(this.controlEnvs),
+      )
       return {
         processGroupId: parsePositiveId(
           result.stdout,
@@ -369,7 +405,10 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
       throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
     }
-    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${foreground.processGroupId}`)
+    await this.sandbox.commands.run(
+      `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
+      commandOpts(this.controlEnvs),
+    )
     return foreground.processGroupId
   }
 
@@ -402,11 +441,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async closeOnce(): Promise<void> {
-    let groups = await sessionProcessGroups(this.sandbox, this.sessionId)
+    let groups = await sessionProcessGroups(this.sandbox, this.sessionId, this.controlEnvs)
     if (groups.length > 0) {
       this.terminationSignal = 'SIGTERM'
-      await signalGroups(this.sandbox, groups, 'TERM')
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs)
+      await signalGroups(this.sandbox, groups, 'TERM', this.controlEnvs)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs)
     }
     if (groups.length === 0 && !this.topLevelExited) {
       await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
@@ -421,7 +460,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
           throw error
         }
       }
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs, true)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
     if (groups.length > 0) {
@@ -469,13 +508,18 @@ export async function spawnE2BTerminal(
   let handle: CommandHandle | undefined
   let completion: Promise<CommandResult> | undefined
   let stateDirectoryCreated = false
+  let controlEnvs: Record<string, string> = {}
   try {
     const ambient = await readRemoteEnvironment(sandbox, spec.signal)
+    controlEnvs = bootstrapEnvironment(ambient)
     const environment = serializeRemoteEnvironment(ambient, spec.env)
     const argv = serializeValues(spec.argv, 'argv')
-    await sandbox.files.makeDir(stateDir)
     stateDirectoryCreated = true
-    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
+    await sandbox.files.makeDir(stateDir, signalOpts(spec.signal))
+    await sandbox.commands.run(
+      `chmod 700 -- ${quoteE2BShellArg(stateDir)}`,
+      commandOpts(controlEnvs, spec.signal),
+    )
     await sandbox.files.write([
       { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
       { path: paths.environment, data: environment },
@@ -484,13 +528,13 @@ export async function spawnE2BTerminal(
     ], signalOpts(spec.signal))
     await sandbox.commands.run(
       `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)} ${quoteE2BShellArg(paths.outputMarker)}`,
-      signalOpts(spec.signal),
+      commandOpts(controlEnvs, spec.signal),
     )
     handle = await sandbox.pty.create({
       rows: spec.rows,
       cols: spec.cols,
       cwd: spec.cwd,
-      envs: { TERM: 'dumb' },
+      envs: e2bControlEnvs(controlEnvs),
       timeoutMs: 0,
       onData: (data) => { outputFilter.push(data) },
     })
@@ -504,13 +548,14 @@ export async function spawnE2BTerminal(
     await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
     await waitUntilReady(sandbox, paths, completion, spec.signal)
     await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
-    const sessionId = await terminalSessionId(sandbox, handle.pid, spec.signal)
+    const sessionId = await terminalSessionId(sandbox, handle.pid, controlEnvs, spec.signal)
     return new E2BTerminalHandle(
       sandbox,
       handle,
       output,
       completion,
       sessionId,
+      controlEnvs,
       stateDir,
       spec.graceMs,
       spec.signal,
@@ -524,7 +569,7 @@ export async function spawnE2BTerminal(
       if (!terminalQuiescent && handle !== undefined) {
         try {
           if (completion === undefined) await handle.kill()
-          else await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs)
           terminalQuiescent = true
         } catch (cleanupError: unknown) {
           if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index d3c96cf2fc..0e906b1cfb 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -111,6 +111,7 @@ class FakeSandbox {
   alive = true
   zombieOnly = false
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  environmentHome = '/home/user'
   environmentWire: string | undefined
   environmentRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   processGroupId = '4242\n'
@@ -241,7 +242,9 @@ class FakeSandbox {
           if (this.envError !== undefined) throw this.envError
           return {
             exitCode: 0,
-            stdout: this.environmentWire ?? Buffer.from(this.ambient).toString('base64'),
+            stdout: this.environmentWire ?? [this.environmentHome, this.ambient]
+              .map(value => Buffer.from(value).toString('base64'))
+              .join('\n'),
             stderr: '',
           }
         }
@@ -396,7 +399,14 @@ describe('E2BSubprocessHandle', () => {
     expect(handle.pid).toBe(4343)
     expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
     expect(fake.handle.closes).toBe(1)
-    expect(fake.startOptions?.envs).toBeUndefined()
+    const controlEnvs = fake.startOptions?.envs
+    expect(controlEnvs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(controlEnvs).toEqual({
+      TERM: 'dumb',
+      NPM_TOKEN: '',
+      DSH_STALE: '',
+      HOME: controlEnvs?.HOME,
+    })
     const command = fake.commandsSeen.find(value => value.includes('exec "$dsh_e2b_env_bin" -i'))!
     expect(command).toContain('"$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c')
     expect(command).not.toContain('DEEPSEEK_API_KEY')
@@ -405,7 +415,9 @@ describe('E2BSubprocessHandle', () => {
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(fake.commandsSeen).toContain('set -o pipefail; env -0 | base64 -w 0')
+    expect(fake.commandsSeen).toContain(
+      'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    )
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
@@ -421,7 +433,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0HOME=/home/user\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -560,6 +572,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(fake.handle.disconnects).toBe(1)
     fake.alive = false
+    handle.terminate()
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
@@ -783,7 +796,7 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.kills).toBe(1)
   })
 
-  it('does not treat successful termination transport as observed quiescence', async () => {
+  it('keeps force cleanup retryable until quiescence is proven', async () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
     fake.delaysKill = true
@@ -793,16 +806,15 @@ describe('E2BSubprocessHandle', () => {
     await flush()
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    expect(fake.alive).toBe(true)
 
-    let quiescent = false
-    const waiting = handle.waitForExit().then((value) => { quiescent = value })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    expect(quiescent).toBe(false)
-
-    fake.alive = false
-    fake.finish()
-    await waiting
-    expect(quiescent).toBe(true)
+    fake.delaysKill = false
+    fake.delaysKillCompletion = false
+    fake.sdkKillStops = true
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
   })
 
   it('honors termination requested before asynchronous startup finishes', async () => {
@@ -870,14 +882,10 @@ describe('E2BSubprocessHandle', () => {
 
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
-    let quiescent = false
-    const waiting = handle.waitForExit().then((value) => { quiescent = value })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    expect(quiescent).toBe(false)
-
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
     fake.alive = false
-    await waiting
-    expect(quiescent).toBe(true)
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
     fake.releaseProcessGroupRead()
     fake.finish()
     await handle.done
@@ -1102,23 +1110,36 @@ describe('E2BSubprocessHandle', () => {
     await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
     expect(envFailure.removed).toEqual([])
 
-    const malformedEnvironment = new FakeSandbox()
-    malformedEnvironment.environmentWire = '%'
-    const malformedEnvironmentHandle = new E2BSubprocessHandle(
-      runtime(malformedEnvironment),
-      spec(),
-      '/runtime/malformed-environment',
+    const expectEnvironmentFailure = async (name: string, wire: string, message: string): Promise<void> => {
+      const fake = new FakeSandbox()
+      fake.environmentWire = wire
+      const failed = new E2BSubprocessHandle(runtime(fake), spec(), `/runtime/${name}`)
+      await expect(failed.done).rejects.toThrow(message)
+    }
+    const encodedEnvironment = Buffer.from('PATH=/bin\0').toString('base64')
+    const encodedHome = Buffer.from('/home/user').toString('base64')
+    await expectEnvironmentFailure('malformed-frame', '%', 'invalid base64')
+    await expectEnvironmentFailure('malformed-base64', `${encodedHome}\n%`, 'invalid base64')
+    await expectEnvironmentFailure(
+      'invalid-utf8-home',
+      `${Buffer.from([0xff]).toString('base64')}\n${encodedEnvironment}`,
+      'not valid UTF-8',
     )
-    await expect(malformedEnvironmentHandle.done).rejects.toThrow('invalid base64')
-
-    const invalidUtf8Environment = new FakeSandbox()
-    invalidUtf8Environment.environmentWire = Buffer.from([0xff]).toString('base64')
-    const invalidUtf8EnvironmentHandle = new E2BSubprocessHandle(
-      runtime(invalidUtf8Environment),
-      spec(),
-      '/runtime/invalid-utf8-environment',
+    await expectEnvironmentFailure(
+      'invalid-utf8-environment',
+      `${encodedHome}\n${Buffer.from([0xff]).toString('base64')}`,
+      'not valid UTF-8',
+    )
+    await expectEnvironmentFailure(
+      'relative-home',
+      `${Buffer.from('home/user').toString('base64')}\n${encodedEnvironment}`,
+      'remote login home is invalid',
+    )
+    await expectEnvironmentFailure(
+      'nul-home',
+      `${Buffer.from('/home/user\0tail').toString('base64')}\n${encodedEnvironment}`,
+      'remote login home is invalid',
     )
-    await expect(invalidUtf8EnvironmentHandle.done).rejects.toThrow('not valid UTF-8')
 
     const cleanupFailure = new FakeSandbox()
     cleanupFailure.backgroundError = new Error('start failed before credential consumption')
@@ -1318,10 +1339,11 @@ describe('E2BSubprocessHandle', () => {
     const failures = Array.from(failure.errors as Iterable<unknown>)
     expect(failures).toHaveLength(2)
     expect(failures[0]).toBeInstanceOf(Error)
-    expect(failures[1]).toBeInstanceOf(Error)
-    if (!(failures[0] instanceof Error) || !(failures[1] instanceof Error)) throw new Error('expected nested errors')
+    expect(failures[1]).toBeInstanceOf(AggregateError)
+    if (!(failures[0] instanceof Error) || !(failures[1] instanceof AggregateError)) throw new Error('expected nested errors')
     expect(failures[0].message).toContain('invalid process-group id')
-    expect(failures[1].message).toBe('rollback signal failed')
+    expect(failures[1].message).toBe('subprocess-e2b: force termination failed through both process-group and SDK transports')
+    expect(Array.from(failures[1].errors as Iterable<unknown>)).toContainEqual(new Error('rollback signal failed'))
     expect(fake.handle.kills).toBe(1)
     const bounded = new AbortController()
     const waiting = handle.waitForExit(bounded.signal)
@@ -1330,6 +1352,15 @@ describe('E2BSubprocessHandle', () => {
     handle.terminate()
     await expect(handle.waitForExit()).resolves.toBe(true)
     expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
+
+    const naturallyGone = new FakeSandbox()
+    naturallyGone.processGroupId = 'not-a-pid\n'
+    naturallyGone.signalError = new Error('rollback signal failed')
+    naturallyGone.handle.killError = new Error('SDK kill failed')
+    const observed = new E2BSubprocessHandle(runtime(naturallyGone), spec(), '/runtime/failed-rollback-observed')
+    await expect(observed.done).rejects.toThrow('process-group publication failed')
+    naturallyGone.alive = false
+    await expect(observed.waitForExit()).resolves.toBe(true)
   })
 
   it('waits for delayed process-group publication', async () => {
@@ -1479,6 +1510,24 @@ describe('E2BSubprocessHandle', () => {
     raced.terminate()
     await expect(raced.waitForExit()).resolves.toBe(true)
   })
+
+  it('rejects an optimistic SDK kill while descendants survive a failed group KILL', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.sdkKillStops = false
+    fake.signalErrors.push(undefined, new Error('KILL transport failed'))
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/optimistic-sdk-kill')
+    await flush()
+
+    handle.terminate()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    expect(fake.alive).toBe(true)
+
+    fake.sdkKillStops = true
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+  })
 })
 
 describe('E2BSubprocessService', () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 00b9fc41fc..8ad0eb1dde 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -23,6 +23,7 @@ function commandError(exitCode: number): CommandExitError {
 interface CommandOptions {
   signal?: AbortSignal
   cwd?: string
+  envs?: Record<string, string>
 }
 
 class FakeTerminalCommandHandle {
@@ -101,6 +102,7 @@ class FakeTerminalSandbox {
   writeError: unknown
   sendError: unknown
   commandFailure: unknown
+  makeDirRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
@@ -129,8 +131,10 @@ class FakeTerminalSandbox {
 
   readonly sandbox = {
     files: {
-      makeDir: async (path: string): Promise<boolean> => {
+      makeDir: async (path: string, options?: CommandOptions): Promise<boolean> => {
         this.directories.push(path)
+        await this.makeDirRequest?.(options?.signal)
+        options?.signal?.throwIfAborted()
         return true
       },
       write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
@@ -163,7 +167,11 @@ class FakeTerminalSandbox {
           throw error
         }
         if (command.includes('env -0 | base64')) {
-          return { exitCode: 0, stdout: Buffer.from(this.ambient).toString('base64'), stderr: '' }
+          return {
+            exitCode: 0,
+            stdout: ['/home/user', this.ambient].map(value => Buffer.from(value).toString('base64')).join('\n'),
+            stderr: '',
+          }
         }
         if (command.includes('command -v -- ')) {
           return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
@@ -262,7 +270,15 @@ describe('E2B terminal allocation', () => {
     expect(output).toBe('requested-shell$ ')
     expect(output).not.toContain('buffered banner')
     expect(output).not.toContain('runner.bash')
-    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
+    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0 })
+    const controlEnvs = fake.createOptions?.envs
+    expect(controlEnvs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(controlEnvs).toEqual({
+      TERM: 'dumb',
+      NPM_TOKEN: '',
+      DSH_STALE: '',
+      HOME: controlEnvs?.HOME,
+    })
     expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('UNICODE=你好\0')
@@ -554,6 +570,7 @@ describe('E2B terminal lifecycle', () => {
       new PassThrough(),
       fake.handle.wait(),
       123,
+      { TERM: 'dumb' },
       '/runtime/pre-aborted',
       1,
       controller.signal,
@@ -807,7 +824,10 @@ describe('E2B subprocess terminal service', () => {
     fake.resolvedExecutable = 'tools/bin/node\n'
     await expect(ctx.subprocess.resolveExecutable('node', { PATH: 'tools/bin' }))
       .resolves.toBe('/workspace/tools/bin/node')
-    expect(fake.commandOptions.at(-1)).toMatchObject({ cwd: '/workspace' })
+    const commandOptions = fake.commandOptions.at(-1)
+    expect(commandOptions).toMatchObject({ cwd: '/workspace' })
+    expect(commandOptions?.envs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(commandOptions?.envs).toEqual({ HOME: commandOptions?.envs?.HOME })
     expect((ctx.e2b)).toBeDefined()
   })
 
@@ -867,6 +887,29 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.handle.disconnects).toBe(1)
   })
 
+  it('owns and cancels terminal state-directory creation during disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.makeDirRequest = async (signal) => {
+      await new Promise<never>((_resolve, reject) => {
+        const onAbort = (): void => {
+          const reason: unknown = signal?.reason
+          reject(reason instanceof Error ? reason : new Error(String(reason)))
+        }
+        signal?.addEventListener('abort', onAbort, { once: true })
+        if (signal?.aborted === true) onAbort()
+      })
+    }
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.directories.some(path => path.includes('/terminals/'))).toBe(true) })
+
+    await fiber.dispose()
+    await rejected
+    expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
+    expect(fake.createOptions).toBeUndefined()
+  })
+
   it('retains failed terminal setup cleanup for disposal retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.sendError = new Error('bootstrap failed')

From 65b345c96a77a40628ad6bbdee9c065894d03957 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:17:56 +0800
Subject: [PATCH 126/262] test(e2b): tolerate real-provider runtime latency

---
 examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 93bb6b65e5..d2b73c1077 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -63,7 +63,7 @@
   name: '@deepseek-ai/dsh-code-runtime-subprocess'
   config:
     computeMs: 500
-    maxWallMs: 5000
+    maxWallMs: 15000
     maxOutputBytes: 4096
     maxOldGenerationSizeMb: 128
     maxFrameBytes: 32768

From 917a7493f7ba0e6e2ab59a458d08566aa14669cc Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 19:07:11 +0800
Subject: [PATCH 127/262] refactor(e2b): keep provider layer substrate-only

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |  26 +++
 ...8-portable-execution-world-consumers.zh.md |  44 ++++-
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   6 -
 .../2026-07-27-e2b-remote-runtime-poc.md      |  65 --------
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  65 --------
 .../tests/fixtures/e2b/e2b/bin.ts             |  58 +++----
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |   2 +-
 packages/e2b/README.zh.md                     |   2 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |   4 +-
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   6 +-
 packages/e2b/fs-e2b/README.zh.md              |   6 +-
 packages/e2b/fs-e2b/src/index.ts              | 129 +++++----------
 packages/e2b/fs-e2b/src/source-reader.ts      |  63 --------
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 152 +++++++-----------
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   6 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   6 +-
 .../e2b/subprocess-e2b/src/environment.ts     |   2 +
 packages/e2b/subprocess-e2b/src/index.ts      |  16 +-
 packages/e2b/subprocess-e2b/src/process.ts    |   4 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   |  37 +++--
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 135 +++++-----------
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   2 +-
 packages/fs/README.zh.md                      |   2 +-
 28 files changed, 280 insertions(+), 578 deletions(-)
 delete mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
 delete mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
 delete mode 100644 packages/e2b/fs-e2b/src/source-reader.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 06fd47f329..fc3b5b012f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 402aa580255a5bd6aa0d046e3bcc16f712da520d
-2026-07-28-portable-execution-world-consumers.zh.md: 26d493a79f8adb9e729ff69b0673f2f2775868b0
+2026-07-28-portable-execution-world-consumers.md: 250445cfed6a4fe2dd188562813d586df29992c1
+2026-07-28-portable-execution-world-consumers.zh.md: 361c4de4e813aa7f57a7eb5acc75087b2630db43
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 402aa58025..4c593604f4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -8,6 +8,8 @@ English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
 
 The filesystem and subprocess seams made file and ordinary process access replaceable, but PTY and LSP still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY and LSP packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
 
+A remote coding world is useful only when file operations, commands, terminals, language servers, and model-written programs share one sandbox identity. Moving the complete harness into that sandbox would also entangle provider experimentation with plugin loading, credentials, model transport, session durability, supervision, and deployment.
+
 Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
 
 ## Decision
@@ -24,10 +26,26 @@ Generic consumers use that execution world:
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
 
+## E2B POC boundary
+
+The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates or reconnects one sandbox and owns kill/pause/leave disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole sandbox identity from the owner and never create private sandboxes.
+
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, subprocess Code Runtime processes, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, Code Runtime program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
+
+The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
+
+Retaining a sandbox preserves remote files and unmanaged state only. Reconnect does not reconstruct host process or terminal handles, protocol connections, pending calls, output cursors, timers, or locks. The POC adds no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
+
+## Verification
+
+Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, post-rename version reread plus guarded edit, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP document bounds, Code Runtime bindings/limits/cleanup, host-workspace isolation, and final sandbox deletion.
+
 ## Alternatives considered
 
 **Keep one PTY and LSP package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
 
+**Create a separate sandbox per capability or tool.** Rejected because file and process operations would not share identity or state, defeating the coding use case and multiplying lifecycle owners.
+
 **Model a terminal as an ordinary piped subprocess.** Rejected because pipes cannot allocate a controlling terminal, resolve the current foreground process group, or prove complete terminal-session cleanup. One terminal primitive is smaller and more honest than exposing substrate-specific escape hatches.
 
 **Move PTY readiness and session policy into the subprocess service.** Rejected because those are persistent-terminal consumer semantics, not OS process mechanics. A subprocess provider owns what only its substrate can do; `dsh-pty-local` owns what a Harness terminal means.
@@ -38,6 +56,12 @@ Generic consumers use that execution world:
 
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
 
+**Put every provider operation in one shared owner package.** Rejected because sandbox identity and lifecycle are the owner's only concerns. Filesystem and subprocess retain distinct contracts, tests, and consumers without turning the owner into a capability grab bag.
+
+**Implement remote filesystem operations only through shell commands.** Rejected because that discards structured filesystem identity, errors, streaming, version guards, and atomic mutation semantics already consumed by the file tools.
+
+**Add a generic distributed-runtime abstraction or reconnect live handles.** Rejected because the existing capability seams carry the demonstrated contracts, while remote identity alone cannot reconstruct callbacks, pending promises, authority, protocol state, or output cursors. A new layer would speculate about persistence and synchronization beyond the POC.
+
 ## Consequences
 
 A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, and LSP compose above them, so fixes to those capabilities remain provider-neutral.
@@ -45,3 +69,5 @@ A remote execution provider implements only its shared sandbox owner plus filesy
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
 The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
+
+The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, retained artifacts accumulate, and escaped processes or reconnect state are not recovered. These are provider constraints, not justification for compatibility shims or more E2B packages.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 26d493a79f..361c4de4e8 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -6,7 +6,9 @@ Status: implemented
 
 ## 问题
 
-文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但 PTY 和 LSP 仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY 与 LSP 包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+
+只有文件操作、命令、终端、语言服务器和模型编写的程序共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
 普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
 
@@ -16,16 +18,36 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+
+`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
+
+## E2B POC 边界
+
+可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建或重新连接一个沙箱，并负责 kill、pause 或 leave 资源释放；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的沙箱身份，绝不创建私有沙箱。
+
+E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取、子进程代码运行时进程，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、代码运行时程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
+
+适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
+
+保留沙箱只会保留远程文件与非托管状态。重新连接不会重建宿主进程或终端句柄、协议连接、待处理调用、输出游标、计时器或锁。该 POC 不会新增会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄，也不会在其中运行整个 harness。
+
+## 验证
+
+聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、重命名后的版本重读与带保护编辑、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 文档上限、代码运行时绑定／上限／清理、宿主工作区隔离，以及最终沙箱删除。
+
 ## 考虑过的替代方案
 
-**为每个远程提供方分别保留 PTY 与 LSP 包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+
+**为每项能力或工具创建独立沙箱。** 不予采纳，因为文件与进程操作将无法共享身份或状态，从而破坏编码用例，并增加生命周期所有者的数量。
 
 **把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
 
@@ -35,12 +57,22 @@ Status: implemented
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
+**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
+
+**在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop。
+
+**把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的契约、测试和消费方，同时避免把所有者变成无边界的能力集合。
+
+**只通过 shell 命令实现远程文件系统操作。** 不予采纳，因为这会丢弃现有文件工具已消费的结构化文件系统身份、错误、流式输出、版本保护和原子变更语义。
+
+**新增通用分布式运行时抽象，或重新连接活跃句柄。** 不予采纳，因为现有能力 seam 已承载经证实的契约，而仅凭远程身份无法重建回调、待处理 promise、权限、协议状态或输出游标。新增一层只会推测 POC 边界之外的持久化与同步问题。
 
 ## 后果
 
-远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY 与 LSP 组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
 本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
+
+E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；保留的产物会累积；也不会恢复逃逸进程或重连状态。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
deleted file mode 100644
index 2c3db3fad4..0000000000
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 79c5bfe2dfa11cd695c7134e6ceffb639b449688
-2026-07-27-e2b-remote-runtime-poc.zh.md: 729a10ec7efa4dd55f041dc804d2252102b13c01
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
deleted file mode 100644
index 79c5bfe2df..0000000000
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Agent Note: Shared E2B remote runtime POC
-
-Status: implemented
-
-English | [中文](2026-07-27-e2b-remote-runtime-poc.zh.md)
-
-## Problem
-
-A remote coding-agent backend is useful only when filesystem operations, one-shot commands, persistent terminals, language servers, and model-written programs observe one coherent world. Attaching E2B independently at individual tools would let those capabilities address different sandboxes, while retaining host PTY, LSP, or worker backends would split state across machines even when the cwd strings match.
-
-Moving the complete harness into a remote VM would unify that state but also couple provider experimentation to plugin loading, credentials, model transport, agent/session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
-
-## Decision
-
-The E2B integration is an opt-in provider-composition POC. Its three E2B-specific packages live together under `packages/e2b/`:
-
-- `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
-- `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
-- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, byte PTYs, and remote Linux process groups.
-
-The higher capabilities use provider-neutral implementations. `dsh-bash-local` delegates command mechanics to `ctx.subprocess`; `dsh-pty-local` delegates terminal allocation and signalling to `ctx.subprocess.spawnTerminal()`; `dsh-lsp-local` reads through `ctx.fs` and launches through `ctx.subprocess`; `dsh-code-runtime-subprocess` materializes its runner through `ctx.fs` and starts it through `ctx.subprocess`. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns those generic interfaces and consumers.
-
-The E2B owner is the sole source of sandbox identity. Its two adapters never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces, generic implementations, model-facing tools, and agent loop.
-
-## POC boundary
-
-E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
-
-The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
-
-The fundamental adapters carry the substrate-specific mechanics. Adapter-internal E2B command and PTY login shells use a fresh randomized root-level `HOME`; `dsh-subprocess-e2b` also gives them empty overrides for scrubbed credential names before user profiles run. The subprocess adapter consumes E2B's byte PTY callback, transports environment snapshots and command bytes as ASCII/base64 across decoded SDK callbacks, and uses one cancellation controller plus one retryable group-cleanup transaction that reports success only after proving quiescence. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated newline-delimited UTF-8 JSON and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
-
-Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
-
-The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
-
-## Verification
-
-Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
-
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, hostile command and PTY login-profile isolation, default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
-
-## Alternatives considered
-
-**A separate E2B sandbox per capability or tool** — rejected because file and command operations would not share identity or state, defeating the coding-agent use case and multiplying lifecycle ownership.
-
-**Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
-
-**Put every E2B operation in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem and subprocess retain separate provider contracts, tests, and consumers; the owner exposes one shared SDK handle without becoming a capability grab bag.
-
-**Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
-
-**Keep E2B-specific PTY, LSP, and Code Runtime packages** — rejected because their domain behavior does not vary with E2B. They were shallow adapters that duplicated existing consumers to replace filesystem and process operations; moving those operations behind the fundamental seams gives every provider one implementation of readiness, protocol, binding, and presentation behavior.
-
-**Call E2B Filesystem, Commands, or PTY APIs directly from higher capabilities** — rejected because it bypasses the `ctx.fs` and `ctx.subprocess` contracts, duplicates execution-world policy in each consumer, and forks model-facing behavior. The subprocess seam includes the irreducible terminal primitive because ordinary pipes cannot supply foreground groups or whole-session cleanup.
-
-**Add a generic distributed-runtime abstraction first** — rejected because the existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
-
-**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
-
-## Consequences
-
-The three-package composition demonstrates that filesystem and subprocess are the sufficient provider seams for moving an agent's mutable coding world off-host without changing the loop, higher capability implementations, or model-facing tool packages. Fixes to Bash, PTY, LSP, and Code Runtime remain provider-neutral. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
-
-The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains the complete base64 command transport in SDK memory, exact terminal stdin-wait inspection is unavailable, E2B supplies no independent signal fact, and reconnect cannot restore handles or protocol state. The adapter reports only its own requested TERM/KILL as signals and preserves every unrequested SDK exit as an exit code. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
deleted file mode 100644
index 729a10ec7e..0000000000
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Agent Note: 共享 E2B 远程运行时 POC
-
-Status: implemented
-
-[English](2026-07-27-e2b-remote-runtime-poc.md) | 中文
-
-## 问题
-
-远程 coding agent（智能体）后端只有在文件系统操作、一次性命令、持久终端、语言服务器和模型编写的程序观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，这些功能可能访问不同的沙箱；即使 cwd 字符串相同，保留宿主 PTY、LSP 或 worker 后端也会让状态分散在不同机器上。
-
-把完整 harness 迁入远程 VM 可以统一这些状态，但也会把提供方实验与插件加载、凭据、模型传输、agent／会话持久性、监管和部署耦合在一起。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
-
-## 决策
-
-E2B 集成是一个选择性启用的提供方组合 POC。它的 3 个 E2B 专用包（package）集中位于 `packages/e2b/` 下：
-
-- `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
-- `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
-- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands、字节 PTY 和远程 Linux 进程组之上实现 `ctx.subprocess`。
-
-上层功能使用提供方无关的实现。`dsh-bash-local` 把命令机制委托给 `ctx.subprocess`；`dsh-pty-local` 把终端分配与信号发送委托给 `ctx.subprocess.spawnTerminal()`；`dsh-lsp-local` 通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动；`dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 启动它。这些通用接口与消费方由[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)负责定义。
-
-E2B 所有者是沙箱身份的唯一真源。其两个适配器绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口、通用实现、面向模型的工具与 agent loop（智能体循环）。
-
-## POC 边界
-
-E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
-
-宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
-
-基础适配器承载基底专用机制。适配器内部的 E2B 命令与 PTY 登录 shell 使用位于根目录下、全新随机生成的 `HOME`；在用户 profile 脚本运行前，`dsh-subprocess-e2b` 还会为它们设置已清理凭据名称的空值覆盖。该子进程适配器消费 E2B 的字节 PTY 回调，以 ASCII/base64 跨越已解码的 SDK 回调传输环境快照与命令字节，并使用一个取消控制器与一个可重试的进程组清理事务，后者只有在证明完全停稳后才报告成功。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 以经过验证、由换行符分隔的 UTF-8 JSON 承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
-
-保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
-
-本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄或完整 harness 执行。
-
-## 验证
-
-聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
-
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、恶意命令与 PTY 登录 profile 隔离、默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
-
-## 曾考虑的替代方案
-
-**每项功能或每个工具使用独立的 E2B 沙箱。** 不予采纳，因为文件操作和命令操作将无法共享身份或状态，既违背 coding agent 用例，也会增加生命周期所有者的数量。
-
-**在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
-
-**把所有 E2B 操作放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统与进程管理各自保留独立的提供方契约、测试和消费方；所有者只公开一个共享 SDK 句柄，不会因此包揽各类功能。
-
-**仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
-
-**保留 E2B 专用的 PTY、LSP 与 Code Runtime 包。** 不予采纳，因为它们的领域行为不会随 E2B 改变。这些浅层适配器为了替换文件系统与进程操作而重复现有消费方；把这些操作移到基础 seam 之后，可让所有提供方共享同一套就绪判定、协议、绑定与呈现行为实现。
-
-**从上层功能直接调用 E2B Filesystem、Commands 或 PTY API。** 不予采纳，因为这会绕过 `ctx.fs` 与 `ctx.subprocess` 契约，在每个消费方中重复执行环境策略，并使面向模型的行为产生分叉。进程管理 seam 纳入不可约简的终端原语，因为普通管道无法提供前台进程组或全会话清理。
-
-**先添加通用分布式运行时抽象。** 不予采纳，因为现有功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
-
-**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
-
-## 后果
-
-这个由 3 个包组成的组合证明，文件系统与进程管理这两个提供方 seam 足以把 agent 的可变 coding 环境移出宿主，而无需改变循环、上层功能实现或面向模型的工具包。Bash、PTY、LSP 与 Code Runtime 的修复仍与提供方无关。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
-
-这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整的 base64 命令传输，无法精确检查终端 stdin 等待状态，E2B 不提供独立的信号事实，重新连接也无法恢复句柄或协议状态。适配器只会把自己请求的 TERM/KILL 报告为信号，其他未请求的 SDK 退出都保留为退出码。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index b4acfd1e5a..856a26ed78 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -35,9 +35,19 @@ let terminalId: Awaited<ReturnType<typeof ctx.pty.spawn>>['sessionId'] | undefin
 try {
   const sandbox = await ctx.e2b.getSandbox()
   const fromFs = await ctx.fs.resolve('from-fs.txt')
-  await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
+  const written = await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
+  const reread = await ctx.fs.stat(fromFs)
+  if (reread?.version !== written.version) {
+    throw new Error(`E2B rename did not preserve version metadata: ${JSON.stringify({ written, reread })}`)
+  }
+  await ctx.fs.editText(
+    fromFs,
+    { oldString: 'written-by-fs', newString: 'written-by-fs-versioned', replaceAll: false },
+    { version: reread.version },
+  )
+  const fsVersionGuard = true
   const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
-  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs\n') {
+  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs-versioned\n') {
     throw new Error(`E2B Bash could not read the FS write: ${JSON.stringify(bashRead)}`)
   }
 
@@ -183,44 +193,8 @@ try {
     workspaceRoot: process.cwd(),
   })
 
-  const swappedParentPath = posix.join(process.cwd(), 'swapped-parent')
-  const swappedSourcePath = posix.join(swappedParentPath, 'source.ts')
-  const swappedOutsidePath = '/tmp/dsh-e2b-lsp-outside'
-  await sandbox.commands.run(
-    `mkdir -p -- ${quoteE2BShellArg(swappedParentPath)} ${quoteE2BShellArg(swappedOutsidePath)} && printf 'const safe = true\\n' > ${quoteE2BShellArg(swappedSourcePath)} && printf 'const outside = true\\n' > ${quoteE2BShellArg(posix.join(swappedOutsidePath, 'source.ts'))}`,
-  )
-  const remoteCommands = sandbox.commands as unknown as {
-    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
-  }
-  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
-  let containmentFaultInjected = false
-  remoteCommands.run = async (command, options) => {
-    if (!containmentFaultInjected && command.includes('dsh-e2b-bounded-reader') && command.includes('swapped-parent/source.ts')) {
-      containmentFaultInjected = true
-      await runRemoteCommand(
-        `rm -rf -- ${quoteE2BShellArg(swappedParentPath)} && ln -s -- ${quoteE2BShellArg(swappedOutsidePath)} ${quoteE2BShellArg(swappedParentPath)}`,
-      )
-    }
-    return await runRemoteCommand(command, options)
-  }
-  let lspContainment = false
-  try {
-    await ctx.lsp.query({
-      operation: 'hover',
-      filePath: 'swapped-parent/source.ts',
-      position: { line: 0, character: 1 },
-      workspaceRoot: process.cwd(),
-    })
-  } catch (error: unknown) {
-    lspContainment = containmentFaultInjected && String(error).includes('opened safely')
-    if (!lspContainment) throw error
-  } finally {
-    remoteCommands.run = runRemoteCommand
-  }
-  if (!lspContainment) throw new Error('E2B LSP source swap was not rejected')
-
   const oversizedSourcePath = posix.join(process.cwd(), 'oversized-source.ts')
-  await sandbox.commands.run(`head -c 4000001 /dev/zero > ${quoteE2BShellArg(oversizedSourcePath)}`)
+  await sandbox.commands.run(`head -c 4000001 /dev/zero | tr '\\0' x > ${quoteE2BShellArg(oversizedSourcePath)}`)
   let lspDocumentBound = false
   try {
     await ctx.lsp.query({
@@ -235,6 +209,10 @@ try {
   }
   if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
 
+  const remoteCommands = sandbox.commands as unknown as {
+    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
+  }
+  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
   terminalId = terminal.sessionId
   const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -429,6 +407,7 @@ try {
   process.stdout.write(`${JSON.stringify({
     sandboxId: await ctx.e2b.sandboxId,
     bashRead: bashRead.stdout.text,
+    fsVersionGuard,
     fsRead,
     explicitEnvironment,
     splitUtf8Output,
@@ -437,7 +416,6 @@ try {
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
-    lspContainment,
     lspDocumentBound,
     terminal: {
       motd: terminal.motd,
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 9b56a3ef55..2b6a8efb69 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: ef2e5ef49056e6688630e785a61c01fa53febbb1
-README.zh.md: d76b05f9b60bc471c1793decd1def1d15615c852
+README.md: cb733ba00d21070773ff9b381e4a72d9d3b9a8df
+README.zh.md: 29f8e58a0cdc59098cf8d74120cb360d11cfbcb3
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index ef2e5ef490..cb733ba00d 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -12,4 +12,4 @@ An experimental provider-composition POC that places one filesystem/process exec
 
 The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), [`dsh-lsp-local`](../lsp/lsp-local/README.md), and [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
 
-This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary; the [portable-consumer decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns the generic composition.
+This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index d76b05f9b6..29f8e58a0c 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -12,4 +12,4 @@
 
 现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md)、[`dsh-lsp-local`](../lsp/lsp-local/README.md) 及 [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
 
-该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界；[可移植消费方决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)界定通用组合。
+该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index f9fcbfae8a..6600f1046d 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -160,7 +160,8 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(stderr).toBe('')
     const output = JSON.parse(stdout) as Record<string, unknown>
     expect(output).toMatchObject({
-      bashRead: 'written-by-fs\n',
+      bashRead: 'written-by-fs-versioned\n',
+      fsVersionGuard: true,
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
       splitUtf8Output: '你好',
@@ -184,7 +185,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         kind: 'locations',
         locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
       },
-      lspContainment: true,
       lspDocumentBound: true,
       terminal: {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 87f1c7c69b..3f756bf2f9 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: bb92b5785383e9703a382fddefcd1cff9b2644cb
-README.zh.md: 57ebfdbb92799660e74078fcd0affcc8d5bc120a
+README.md: 6827e16e9c45532590ee1aa986c18a353d175fdc
+README.zh.md: 21b067829ea95c4581d7e89f3d225f9c90e630ef
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index bb92b57853..6827e16e9c 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -6,10 +6,9 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 
 ## Behavior
 
-- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
 - **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
 
@@ -27,5 +26,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
 - **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
-- **Custom templates must support the used Linux, Node, procfs, and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, file metadata extended attributes, `/proc/self/fd`, and no-follow descriptor opens are required; unsupported templates fail rather than degrade silently.
+- **Custom templates must support the used Linux/GNU and E2B filesystem features** — `realpath -mz`, `base64 -w0`, `chmod`, same-filesystem rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 57ebfdbb92..21b067829e 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -6,10 +6,9 @@
 
 ## 行为
 
-- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
 - **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
 
@@ -27,5 +26,6 @@
 
 - **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
 - **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
-- **自定义模板必须支持所用的 Linux、Node、procfs 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取、文件元数据扩展属性、`/proc/self/fd` 和不跟随链接的描述符打开操作；不支持的模板会失败，而不会静默降级。
+- **自定义模板必须支持所用的 Linux/GNU 与 E2B 文件系统功能**：必须支持 `realpath -mz`、`base64 -w0`、`chmod`、同一文件系统内的 rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 7c81791d55..3b0c835d8c 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -26,17 +26,10 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { BOUNDED_READER_SOURCE } from './source-reader.ts'
 
 const VERSION_METADATA_KEY = 'dsh-version'
 const BINARY_SAMPLE_BYTES = 8192
-
-type BoundedReadResponse =
-  | { kind: 'ok'; data: string }
-  | { kind: 'not-file' }
-  | { kind: 'oversize'; size: number }
-  | { kind: 'grew' }
-  | { kind: 'open-error'; message: string }
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
 
 function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
   if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
@@ -68,6 +61,27 @@ function decodeText(bytes: Uint8Array, displayPath: string, binarySampleBytes: n
   }
 }
 
+function decodeCanonicalPath(encoded: string): string {
+  if (encoded.length === 0 || !BASE64.test(encoded)) {
+    throw new Error('fs-e2b: canonical path transport returned invalid base64')
+  }
+  const framed = Buffer.from(encoded, 'base64')
+  if (framed.toString('base64') !== encoded
+    || framed.length < 2
+    || framed.at(-1) !== 0
+    || framed.subarray(0, -1).includes(0)) {
+    throw new Error('fs-e2b: canonical path transport returned invalid NUL framing')
+  }
+  let path: string
+  try {
+    path = new TextDecoder('utf-8', { fatal: true }).decode(framed.subarray(0, -1))
+  } catch (error: unknown) {
+    throw new Error('fs-e2b: canonical path is not valid UTF-8', { cause: error })
+  }
+  if (!posix.isAbsolute(path)) throw new Error('fs-e2b: canonical path is not absolute')
+  return path
+}
+
 function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal }
 }
@@ -213,69 +227,6 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-      throw new Error('bounded read maxBytes must be a positive safe integer')
-    }
-    assertNotAborted(signal, 'read')
-    const sandbox = await this.ctx.e2b.getSandbox()
-    try {
-      const node = await sandbox.commands.run('command -v -- node', commandOpts(signal))
-      const executable = node.stdout.trim()
-      if (!posix.isAbsolute(executable) || executable.includes('\n')) {
-        throw new Error('fs-e2b: bounded reader requires one absolute Node executable')
-      }
-      const command = [
-        quoteE2BShellArg(executable),
-        '--input-type=commonjs',
-        '-e',
-        quoteE2BShellArg(BOUNDED_READER_SOURCE),
-        quoteE2BShellArg(this.processPath(target)),
-        String(maxBytes),
-      ].join(' ')
-      const result = await sandbox.commands.run(command, commandOpts(signal))
-      assertNotAborted(signal, 'read')
-      const response = this.parseBoundedRead(result.stdout, target)
-      if (response.kind === 'not-file') {
-        throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
-      }
-      if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
-        throw new FsError(
-          `cannot read "${target.displayPath}": ${response.size} bytes exceeds the ${maxBytes}-byte limit`,
-          'FS_IO_ERROR',
-        )
-      }
-      if (response.kind === 'grew') {
-        throw new FsError(
-          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
-          'FS_IO_ERROR',
-        )
-      }
-      if (response.kind === 'open-error' && typeof response.message === 'string') {
-        if (/ENOENT|no such file/i.test(response.message)) {
-          throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
-        }
-        if (/EACCES|EPERM|permission denied|operation not permitted/i.test(response.message)) {
-          throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED')
-        }
-        throw new FsError(
-          `cannot read "${target.displayPath}" safely: ${response.message}`,
-          'FS_IO_ERROR',
-        )
-      }
-      if (response.kind !== 'ok' || typeof response.data !== 'string') {
-        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned an invalid response`, 'FS_IO_ERROR')
-      }
-      const bytes = Buffer.from(response.data, 'base64')
-      if (bytes.toString('base64') !== response.data || bytes.length > maxBytes) {
-        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned invalid bytes`, 'FS_IO_ERROR')
-      }
-      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
-    } catch (error: unknown) {
-      throw mapError(error, 'read', target.displayPath, signal)
-    }
-  }
-
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     const sandbox = await this.ctx.e2b.getSandbox()
     await this.requireRegular(target, signal)
@@ -339,18 +290,23 @@ export class E2BFileSystem extends FileSystem {
     try {
       const sandbox = await this.ctx.e2b.getSandbox()
       const listed = await sandbox.files.list(String(target.targetKey), { depth: 1, ...signalOpts(signal) })
-      const entries = await Promise.all(listed.map(async (entry): Promise<FsDirEntry> => {
+      const entries: FsDirEntry[] = []
+      for (const entry of listed) {
         const displayPath = posix.join(target.displayPath, entry.name)
-        const canonical = await this.canonicalPath(sandbox, entry.path, signal)
-        const resolved = await this.probe(canonical, displayPath, signal)
-        return {
+        const canonical = entry.symlinkTarget === undefined
+          ? entry.path
+          : await this.canonicalPath(sandbox, entry.path, signal)
+        const resolved = entry.symlinkTarget === undefined
+          ? entry
+          : await this.probe(canonical, displayPath, signal)
+        entries.push({
           name: entry.name,
           type: resolved === undefined ? 'other' : entryType(resolved),
           target: { targetKey: FsTargetKey(canonical), displayPath },
           ...(resolved !== undefined ? { version: entryVersion(resolved) } : {}),
           ...(resolved?.type === FileType.FILE ? { size: resolved.size } : {}),
-        }
-      }))
+        })
+      }
       return entries.sort((left, right) => left.name.localeCompare(right.name))
     } catch (error: unknown) {
       throw mapError(error, 'list', target.displayPath, signal)
@@ -420,26 +376,17 @@ export class E2BFileSystem extends FileSystem {
 
   private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
     try {
-      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, commandOpts(signal))
-      return result.stdout.replace(/\n$/, '')
+      const result = await sandbox.commands.run(
+        `set -o pipefail; realpath -mz -- ${quoteE2BShellArg(path)} | base64 -w0`,
+        commandOpts(signal),
+      )
+      return decodeCanonicalPath(result.stdout)
     } catch (error: unknown) {
       if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
       throw error
     }
   }
 
-  private parseBoundedRead(stdout: string, target: FsTarget): BoundedReadResponse {
-    try {
-      return JSON.parse(stdout) as BoundedReadResponse
-    } catch (error: unknown) {
-      throw new FsError(
-        `cannot read "${target.displayPath}": bounded reader returned invalid JSON`,
-        'FS_IO_ERROR',
-        { cause: error },
-      )
-    }
-  }
-
   private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
     assertNotAborted(signal, 'stat')
     try {
diff --git a/packages/e2b/fs-e2b/src/source-reader.ts b/packages/e2b/fs-e2b/src/source-reader.ts
deleted file mode 100644
index 9cb522ecbb..0000000000
--- a/packages/e2b/fs-e2b/src/source-reader.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-/** Dependency-free stable-handle bounded reader installed inside E2B. */
-export const BOUNDED_READER_SOURCE = String.raw`
-/* dsh-e2b-bounded-reader */
-const fs = require('node:fs')
-const target = process.argv[1]
-const maxBytes = Number(process.argv[2])
-const directoryFlags = fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
-const fileFlags = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
-let directory
-let descriptor
-let response
-
-const openChild = (parent, component, flags) => fs.openSync('/proc/self/fd/' + parent + '/' + component, flags)
-const invalidComponent = component => component === '' || component === '.' || component === '..'
-
-try {
-  if (typeof target !== 'string' || !target.startsWith('/') || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-    throw new Error('bounded reader requires an absolute target and positive byte limit')
-  }
-  const components = target === '/' ? [] : target.slice(1).split('/')
-  if (components.length === 0 || components.some(invalidComponent)) {
-    throw new Error('bounded reader received a non-canonical file path')
-  }
-
-  directory = fs.openSync('/', directoryFlags)
-  for (const component of components.slice(0, -1)) {
-    const child = openChild(directory, component, directoryFlags)
-    fs.closeSync(directory)
-    directory = child
-  }
-  descriptor = openChild(directory, components.at(-1), fileFlags)
-
-  const info = fs.fstatSync(descriptor)
-  if (!info.isFile()) response = { kind: 'not-file' }
-  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
-  else {
-    const chunks = []
-    let total = 0
-    while (total <= maxBytes) {
-      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
-      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
-      if (bytesRead === 0) break
-      chunks.push(chunk.subarray(0, bytesRead))
-      total += bytesRead
-    }
-    response = total > maxBytes
-      ? { kind: 'grew' }
-      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
-  }
-} catch (error) {
-  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
-} finally {
-  for (const openDescriptor of [descriptor, directory]) {
-    if (openDescriptor === undefined) continue
-    try {
-      fs.closeSync(openDescriptor)
-    } catch (error) {
-      response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
-    }
-  }
-}
-process.stdout.write(JSON.stringify(response))
-`
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 23835e9967..91f9a278fd 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -49,10 +49,7 @@ class FakeRemote {
   nextReadError: unknown
   nextRenameError: unknown
   nextRemoveError: unknown
-  boundedOutput: string | undefined
-  boundedError: unknown
-  nodeExecutable = '/usr/bin/node\n'
-  abortAfterBoundedCommand: AbortController | undefined
+  canonicalOutput: string | undefined
   abortAfterRename: AbortController | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
@@ -239,18 +236,18 @@ class FakeRemote {
           this.nextCommandError = undefined
           throw error
         }
-        if (command.startsWith('realpath -m -- ')) {
-          const input = command.slice('realpath -m -- '.length).slice(1, -1)
+        const realpathPrefix = 'set -o pipefail; realpath -mz -- '
+        const realpathSuffix = ' | base64 -w0'
+        if (command.startsWith(realpathPrefix) && command.endsWith(realpathSuffix)) {
+          const quoted = command.slice(realpathPrefix.length, -realpathSuffix.length)
+          const input = quoted.slice(1, -1).replaceAll(String.raw`'"'"'`, '\'')
           const node = this.nodes.get(input)
-          return { exitCode: 0, stdout: `${node?.symlinkTarget ?? input}\n`, stderr: '' }
-        }
-        if (command === 'command -v -- node') {
-          return { exitCode: 0, stdout: this.nodeExecutable, stderr: '' }
-        }
-        if (command.includes('dsh-e2b-bounded-reader')) {
-          if (this.boundedError !== undefined) throw this.boundedError
-          this.abortAfterBoundedCommand?.abort('after bounded read')
-          return { exitCode: 0, stdout: this.boundedOutput ?? '{"kind":"ok","data":""}', stderr: '' }
+          const canonical = `${node?.symlinkTarget ?? input}\0`
+          return {
+            exitCode: 0,
+            stdout: this.canonicalOutput ?? Buffer.from(canonical).toString('base64'),
+            stderr: '',
+          }
         }
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
@@ -340,6 +337,28 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
       .toThrow('expected an absolute process path')
   })
 
+  it('preserves newline and multibyte canonical paths through strict ASCII framing', async () => {
+    const remote = new FakeRemote()
+    const path = '/workspace/你好\nfile.ts'
+    remote.file(path, 'text')
+    const { fs } = await setup(remote)
+
+    await expect(fs.resolve(path)).resolves.toEqual({ targetKey: path, displayPath: path })
+  })
+
+  it.each([
+    ['invalid base64', '!!!!'],
+    ['missing terminator', Buffer.from('/workspace/file').toString('base64')],
+    ['multiple records', Buffer.from('/workspace/file\0/other\0').toString('base64')],
+    ['invalid UTF-8', Buffer.from([47, 0xff, 0]).toString('base64')],
+    ['relative path', Buffer.from('workspace/file\0').toString('base64')],
+  ])('rejects %s from canonical path transport', async (_label, output) => {
+    const remote = new FakeRemote()
+    remote.canonicalOutput = output
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('file'), 'FS_IO_ERROR')
+  })
+
   it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/text.txt', 'A€B')
@@ -424,78 +443,6 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
   })
 
-  it('performs stable bounded reads through the remote no-follow reader', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const { fs } = await setup(remote)
-    const target = await fs.resolve('a')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('hello 你好').toString('base64') })
-    await expect(fs.readTextBounded(target, 64)).resolves.toBe('hello 你好')
-    expect(remote.commands.some(command => command.includes('dsh-e2b-bounded-reader'))).toBe(true)
-
-    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
-    await expect(fs.readTextBounded(target, 1.5)).rejects.toThrow('positive safe integer')
-    await expect(fs.readTextBounded(target, 64, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
-  })
-
-  it('maps bounded-reader file, size, and open failures', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const { fs } = await setup(remote)
-    const target = await fs.resolve('a')
-    const cases: Array<[unknown, string]> = [
-      [{ kind: 'not-file' }, 'FS_NOT_REGULAR_FILE'],
-      [{ kind: 'oversize', size: 65 }, 'FS_IO_ERROR'],
-      [{ kind: 'grew' }, 'FS_IO_ERROR'],
-      [{ kind: 'open-error', message: 'ENOENT: no such file' }, 'FS_NOT_FOUND'],
-      [{ kind: 'open-error', message: 'EACCES: permission denied' }, 'FS_PERMISSION_DENIED'],
-      [{ kind: 'open-error', message: 'ELOOP: symbolic link' }, 'FS_IO_ERROR'],
-      [{ kind: 'oversize', size: 'large' }, 'FS_IO_ERROR'],
-      [{ kind: 'open-error', message: 7 }, 'FS_IO_ERROR'],
-      [{ kind: 'unknown' }, 'FS_IO_ERROR'],
-    ]
-    for (const [response, code] of cases) {
-      remote.boundedOutput = JSON.stringify(response)
-      await expectCode(fs.readTextBounded(target, 64), code)
-    }
-  })
-
-  it('rejects malformed bounded-reader transports and bytes', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const { fs } = await setup(remote)
-    const target = await fs.resolve('a')
-
-    remote.boundedOutput = 'not-json'
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: '!!!!' })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('12345').toString('base64') })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0]).toString('base64') })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0xff]).toString('base64') })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
-
-    remote.nodeExecutable = 'node\n'
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.nodeExecutable = '/usr/bin/node\n/other\n'
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.nodeExecutable = '/usr/bin/node\n'
-    remote.boundedError = new Error('reader transport failed')
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-  })
-
-  it('does not turn a post-read abort into successful source text', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const controller = new AbortController()
-    remote.abortAfterBoundedCommand = controller
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('text').toString('base64') })
-    const { fs } = await setup(remote)
-    await expectCode(fs.readTextBounded(await fs.resolve('a'), 4, controller.signal), 'FS_ABORTED')
-  })
-
   it('rejects empty paths and directory-listing type errors', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/file', 'x')
@@ -686,17 +633,34 @@ describe('E2B filesystem adapter integration edges', () => {
     await expectCode(fs.readText(target), 'FS_IO_ERROR')
   })
 
-  it('keeps a listed child whose metadata disappears as an other entry', async () => {
+  it('uses listing metadata directly and canonicalizes only symbolic links', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/a', 'a')
-    remote.disappearOnInfo.add('/workspace/a')
+    remote.file('/workspace/target', 'target')
+    remote.file('/workspace/gone', 'gone')
+    remote.symlink('/workspace/link', '/workspace/target')
+    remote.symlink('/workspace/vanished-link', '/workspace/gone')
+    remote.disappearOnInfo.add('/workspace/gone')
     const { fs } = await setup(remote)
-    const listed = await fs.listDir(await fs.resolve('/workspace'))
-    expect(listed).toEqual([{
-      name: 'a',
+    const directory = await fs.resolve('/workspace')
+    const commandsBefore = remote.commands.length
+    const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
+
+    const listed = await fs.listDir(directory)
+
+    expect(listed.find(entry => entry.name === 'a')).toMatchObject({
+      type: 'file', target: { targetKey: '/workspace/a' }, size: 1,
+    })
+    expect(listed.find(entry => entry.name === 'link')).toMatchObject({
+      type: 'file', target: { targetKey: '/workspace/target' }, size: 6,
+    })
+    expect(listed.find(entry => entry.name === 'vanished-link')).toEqual({
+      name: 'vanished-link',
       type: 'other',
-      target: { targetKey: '/workspace/a', displayPath: '/workspace/a' },
-    }])
+      target: { targetKey: '/workspace/gone', displayPath: '/workspace/vanished-link' },
+    })
+    expect(remote.commands.slice(commandsBefore)).toHaveLength(2)
+    expect(getInfo).toHaveBeenCalledTimes(3)
   })
 
   it('registers the package-owned empty invariant installer', async () => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index ac7b8d42a5..20ba9b597e 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 9b86af428533ebcc2c0da56339e6ea2a28170fd3
-README.zh.md: e3e8368534266e35ec04dcf5a2d6718829b4a016
+README.md: 9e044c13b673461a876e016ec560db4897a27c66
+README.zh.md: b9180c0c0679915fae7a1db22353613708392a8c
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 9b86af4285..9e044c13b6 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -9,9 +9,9 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. E2B's fixed command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Environment boundary** — one trusted control-shell probe transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
@@ -30,6 +30,8 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
+- **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
+- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. In a reconnected sandbox, a same-UID untrusted process could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive or a hardened template to close the gap.
 - **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
 - **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index e3e8368534..b9180c0c06 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -9,9 +9,9 @@
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，E2B 固定的命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **环境边界**：一次受信任的控制 shell 探测会以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
@@ -30,6 +30,8 @@
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
+- **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
+- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。在重新连接的沙箱中，一个同 UID 的不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语或经加固的模板才能弥合该缺口。
 - **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
 - **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 5322491261..907810a1d7 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -26,6 +26,8 @@ function remoteEnvironmentEntries(raw: string): Array<readonly [string, string]>
  * @returns the complete NUL-delimited UTF-8 environment.
  */
 export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
+  // TODO(e2b-replace-environment): Remove this ambient probe when E2B can start
+  // a command with a replacement environment instead of merged overrides.
   const result = await sandbox.commands.run(
     'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
     { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 7318dfde95..990ab20a62 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -61,8 +61,7 @@ export class E2BSubprocessService extends SubprocessService {
         }))
       }
       for (const terminal of terminals) {
-        terminal.terminate()
-        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
+        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
       for (const cleanup of failedTerminalSetupCleanups) {
         pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
@@ -125,7 +124,9 @@ export class E2BSubprocessService extends SubprocessService {
       await handle.waitForExit()
       this.live.delete(handle)
     }
-    void handle.done.then(release, release).catch(() => {})
+    void handle.done.then(release, release).catch((_automaticReleaseFailure: unknown) => {
+      // Retain the handle so service disposal can retry its cleanup transaction.
+    })
     return handle
   }
 
@@ -158,16 +159,17 @@ export class E2BSubprocessService extends SubprocessService {
       )
       this.terminals.add(terminal)
       if (this.isDisposing()) {
-        terminal.terminate()
-        await terminal.waitForExit()
+        await terminal.terminate()
         this.terminals.delete(terminal)
         throw new Error('subprocess-e2b: service disposed during terminal setup')
       }
       const release = async (): Promise<void> => {
-        await terminal.waitForExit()
+        await terminal.terminate()
         this.terminals.delete(terminal)
       }
-      void terminal.done.then(release, release).catch(() => {})
+      void terminal.done.then(release, release).catch((_automaticReleaseFailure: unknown) => {
+        // Retain the terminal so service disposal can retry its cleanup transaction.
+      })
       return terminal
     } finally {
       this.terminalSetups.delete(setup.promise)
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 6b17f3b682..02e1583e56 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -726,7 +726,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       // A spill mode is a collect mode, so construction always created its reader.
       const size = (reader as E2BOutputReader).size
       if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
-        removals.push(sandbox.files.remove(path).catch(() => {}))
+        removals.push(sandbox.files.remove(path).catch((_adapterPrivateSpillRemovalFailure: unknown) => {
+          // The command outcome is authoritative; a retained sandbox tolerates private residue.
+        }))
       }
     }
     collect(this.spec.stdio.stdout, this.stdoutReader, this.paths.stdout)
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index ff8af60da9..6c4b23d1c1 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -12,7 +12,6 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -345,7 +344,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   readonly done: Promise<SubprocessOutcome>
 
   private topLevelExited = false
-  private readonly lifecycle: SubprocessTerminalLifecycle
+  private cleanup: Promise<void> | undefined
   private terminationSignal: NodeJS.Signals | null = null
 
   constructor(
@@ -357,21 +356,17 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     private readonly controlEnvs: Record<string, string>,
     private readonly stateDir: string,
     private readonly graceMs: number,
-    signal?: AbortSignal,
   ) {
     this.pid = handle.pid
     this.done = this.waitForCommand()
-    this.lifecycle = new SubprocessTerminalLifecycle({
-      done: this.done,
-      cleanup: () => this.closeOnce(),
-      signal,
-    })
   }
 
+  // TODO(e2b-pgid-identity): Replace retained numeric PTY/session ids when E2B
+  // exposes identity-bound input, foreground-signal, and cleanup operations.
   /** @inheritdoc */
-  async write(data: Uint8Array): Promise<void> {
+  async write(data: string): Promise<void> {
     if (this.topLevelExited) throw new Error('terminal process has exited')
-    await this.sandbox.pty.sendInput(this.pid, data)
+    await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'))
   }
 
   /** @inheritdoc */
@@ -413,13 +408,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   /** @inheritdoc */
-  terminate(): void {
-    this.lifecycle.terminate()
-  }
-
-  /** @inheritdoc */
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    return await this.lifecycle.waitForExit(signal)
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.closeOnce()
+    this.cleanup = cleanup
+    void cleanup.catch((_cleanupFailure: unknown) => {
+      this.cleanup = undefined
+    })
+    return cleanup
   }
 
   private async waitForCommand(): Promise<SubprocessOutcome> {
@@ -474,7 +470,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     } catch (error: unknown) {
       if (!(error instanceof SandboxNotFoundError)) throw error
     }
-    await this.sandbox.files.remove(this.stateDir).catch(() => {})
+    try {
+      await this.sandbox.files.remove(this.stateDir)
+    } catch (_adapterPrivateStateRemovalFailure) {
+      // The terminal is quiescent; a retained sandbox tolerates private residue.
+    }
   }
 }
 
@@ -558,7 +558,6 @@ export async function spawnE2BTerminal(
       controlEnvs,
       stateDir,
       spec.graceMs,
-      spec.signal,
     )
   } catch (error: unknown) {
     output.destroy()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 8ad0eb1dde..6c3ef477af 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -1,6 +1,5 @@
 import { Buffer } from 'node:buffer'
 import { once } from 'node:events'
-import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import {
@@ -14,7 +13,7 @@ import {
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { E2BTerminalHandle, spawnE2BTerminal } from '../src/terminal.ts'
+import { spawnE2BTerminal } from '../src/terminal.ts'
 
 function commandError(exitCode: number): CommandExitError {
   return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
@@ -298,20 +297,20 @@ describe('E2B terminal allocation', () => {
     await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
     expect(output).toBe('requested-shell$ ')
 
-    await terminal.write(Buffer.from('echo ok\r'))
+    await terminal.write('echo ok\r')
     expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
     await expect(terminal.inspectForeground()).resolves.toEqual({ processGroupId: 456, inputWaiting: false })
     await expect(terminal.signalForeground('SIGINT')).resolves.toBe(456)
     expect(fake.commands).toContain('kill -INT -- -456')
 
-    terminal.terminate()
+    const terminated = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminated
     expect(fake.handle.disconnects).toBe(1)
     expect(fake.removed).toContain('/runtime/terminal-one')
   })
 
-  it('inherits only safe ambient values and binds live abort to terminal cleanup', async () => {
+  it('inherits only safe ambient values and limits the allocation signal to setup', async () => {
     const fake = new FakeTerminalSandbox()
     const controller = new AbortController()
     const terminal = await spawnE2BTerminal(
@@ -325,9 +324,10 @@ describe('E2B terminal allocation', () => {
     expect(environment).not.toContain('DSH_STALE')
 
     controller.abort(new Error('stop'))
+    await terminal.write('still live\r')
+    expect(fake.inputs.at(-1)?.data.toString()).toBe('still live\r')
+    await terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
-    await expect(terminal.waitForExit(controller.signal)).resolves.toBe(false)
-    await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
   it('publishes the PTY handle before honoring allocation cancellation', async () => {
@@ -553,31 +553,11 @@ describe('E2B terminal lifecycle', () => {
     fake.handle.succeed(7)
     await expect(terminal.done).resolves.toEqual({ exitCode: 7, signal: null })
     await ended
-    await expect(terminal.waitForExit()).resolves.toBe(true)
-    await expect(terminal.write(Buffer.from('late'))).rejects.toThrow('exited')
+    await expect(terminal.write('late')).rejects.toThrow('exited')
     fake.foregroundFailure = commandError(1)
     await expect(terminal.inspectForeground()).resolves.toBeUndefined()
     await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('cannot resolve foreground process group')
-  })
-
-  it('starts cleanup when the lifetime signal is already aborted at handle publication', async () => {
-    const fake = new FakeTerminalSandbox()
-    const controller = new AbortController()
-    controller.abort(new Error('publication cancelled'))
-    const terminal = new E2BTerminalHandle(
-      fake.sandbox,
-      fake.handle.asHandle(),
-      new PassThrough(),
-      fake.handle.wait(),
-      123,
-      { TERM: 'dumb' },
-      '/runtime/pre-aborted',
-      1,
-      controller.signal,
-    )
-
-    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it.each([
@@ -590,18 +570,7 @@ describe('E2B terminal lifecycle', () => {
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
     fake.handle.fail(exitCode)
     await expect(terminal.done).resolves.toEqual(expected)
-    await expect(terminal.waitForExit(new AbortController().signal)).resolves.toBe(true)
-  })
-
-  it('lets an early quiescence observer follow a transport rejection', async () => {
-    const fake = new FakeTerminalSandbox()
-    fake.groups = []
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/early-observer')
-    terminal.output.on('error', () => {})
-    const quiescence = terminal.waitForExit()
-    fake.handle.crash(new Error('transport failed'))
-    await expect(terminal.done).rejects.toThrow('transport failed')
-    await expect(quiescence).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it('treats a terminal session containing only zombies as quiescent', async () => {
@@ -612,7 +581,7 @@ describe('E2B terminal lifecycle', () => {
 
     fake.handle.succeed(0)
     await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
     expect(fake.commands).toContain(
       "set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == 123 && $3 !~ /^[ZXx]/ { print $2 }'",
     )
@@ -625,7 +594,7 @@ describe('E2B terminal lifecycle', () => {
     fake.handle.succeed(0)
 
     await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it('treats sandbox disappearance during PTY kill as quiescent', async () => {
@@ -635,8 +604,7 @@ describe('E2B terminal lifecycle', () => {
     fake.ptyKillError = new SandboxNotFoundError('sandbox expired')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
 
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
     expect(fake.ptyKills).toBe(1)
   })
 
@@ -647,8 +615,11 @@ describe('E2B terminal lifecycle', () => {
     fake.ptyKillError = new Error('PTY kill transport failed')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
 
-    terminal.terminate()
-    await expect(terminal.waitForExit()).rejects.toThrow('PTY kill transport failed')
+    await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
+    fake.ptyKillError = undefined
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.terminate()
   })
 
   it.each([
@@ -661,8 +632,8 @@ describe('E2B terminal lifecycle', () => {
     fake.groups = []
     fake.handle.succeed(0)
 
-    if (accepted) await expect(terminal.waitForExit()).resolves.toBe(true)
-    else await expect(terminal.waitForExit()).rejects.toThrow('disconnect failed')
+    if (accepted) await expect(terminal.terminate()).resolves.toBeUndefined()
+    else await expect(terminal.terminate()).rejects.toThrow('disconnect failed')
   })
 
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
@@ -677,23 +648,17 @@ describe('E2B terminal lifecycle', () => {
     fake.foregroundFailure = commandError(2)
     await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
     fake.clearOnTerm = true
-    terminal.terminate()
-    await terminal.waitForExit()
+    await terminal.terminate()
   })
 
-  it('escalates surviving process groups and bounds an observing wait', async () => {
+  it('escalates surviving process groups', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [123, 456]
     fake.clearOnTerm = false
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/escalate')
-    const controller = new AbortController()
-    const observing = terminal.waitForExit(controller.signal)
-    controller.abort()
-    await expect(observing).resolves.toBe(false)
-
-    terminal.terminate()
+    const terminating = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminating
     expect(fake.commands).toContain('kill -TERM -- -123 -456')
     expect(fake.commands).toContain('kill -KILL -- -123 -456')
   })
@@ -702,49 +667,31 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [1]
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
-    terminal.terminate()
-    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('unsafe process group 1')
+    await expect(terminal.terminate()).rejects.toThrow('unsafe process group 1')
 
     fake.groups = []
     fake.handle.succeed(0)
     await terminal.done
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it('propagates a process-group signalling transport failure before retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.termFailure = new Error('signal transport failed')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
-    terminal.terminate()
-    await expect(terminal.waitForExit()).rejects.toThrow('signal transport failed')
+    await expect(terminal.terminate()).rejects.toThrow('signal transport failed')
 
     fake.groups = []
     fake.handle.succeed(0)
     await terminal.done
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
 
     const alreadyExited = new FakeTerminalSandbox()
     alreadyExited.termFailure = commandError(1)
     const tolerant = await spawnE2BTerminal(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
-    tolerant.terminate()
+    const tolerantTermination = tolerant.terminate()
     await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
-    await expect(tolerant.waitForExit()).resolves.toBe(true)
-  })
-
-  it('normalizes a non-Error cleanup rejection for an observing wait', async () => {
-    const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/non-error-cleanup')
-    fake.commandFailure = 'cleanup transport gone'
-    terminal.terminate()
-    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('cleanup transport gone')
-
-    fake.groups = []
-    fake.handle.succeed(0)
-    await terminal.done
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await tolerantTermination
   })
 
   it('keeps command rejection authoritative while cleanup is already waiting', async () => {
@@ -753,11 +700,11 @@ describe('E2B terminal lifecycle', () => {
     fake.removeError = new Error('private state already gone')
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/reject-during-cleanup')
     terminal.output.on('error', () => {})
-    terminal.terminate()
+    const cleanup = terminal.terminate()
     await Promise.resolve()
     fake.handle.crash(new Error('command transport failed'))
     await expect(terminal.done).rejects.toThrow('command transport failed')
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await cleanup
   })
 
   it('keeps a late command rejection authoritative after PTY kill', async () => {
@@ -766,12 +713,12 @@ describe('E2B terminal lifecycle', () => {
     fake.settleOnPtyKill = false
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
     terminal.output.on('error', () => {})
-    terminal.terminate()
+    const cleanup = terminal.terminate()
     while (fake.ptyKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
     await Promise.resolve()
     fake.handle.crash(new Error('late command transport failed'))
     await expect(terminal.done).rejects.toThrow('late command transport failed')
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await cleanup
   })
 
   it('reports surviving groups, a surviving top-level pid, and transport failure', async () => {
@@ -779,15 +726,13 @@ describe('E2B terminal lifecycle', () => {
     survivor.clearOnTerm = false
     survivor.clearOnKill = false
     const terminal = await spawnE2BTerminal(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
-    terminal.terminate()
-    await expect(terminal.waitForExit()).rejects.toThrow('surviving process groups: 123')
+    await expect(terminal.terminate()).rejects.toThrow('surviving process groups: 123')
 
     const livePid = new FakeTerminalSandbox()
     livePid.groups = []
     livePid.settleOnPtyKill = false
     const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
-    live.terminate()
-    await expect(live.waitForExit()).rejects.toThrow('surviving pid: 123')
+    await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
     livePid.handle.succeed(0)
     await live.done
 
@@ -798,7 +743,7 @@ describe('E2B terminal lifecycle', () => {
     crashed.handle.crash('transport gone')
     await expect(failed.done).rejects.toEqual('transport gone')
     await expect(outputError).resolves.toMatchObject([{ message: 'transport gone' }])
-    await expect(failed.waitForExit()).resolves.toBe(true)
+    await failed.terminate()
   })
 })
 
@@ -943,7 +888,7 @@ describe('E2B subprocess terminal service', () => {
     const terminal = await ctx.subprocess.spawnTerminal(spec())
     fake.handle.succeed(0)
     await terminal.done
-    await terminal.waitForExit()
+    await terminal.terminate()
     const signals = fake.commands.filter(command => command.startsWith('kill -')).length
     await fiber.dispose()
     expect(fake.commands.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
@@ -961,6 +906,6 @@ describe('E2B subprocess terminal service', () => {
 
     fake.groups = []
     await fiber.dispose()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await expect(terminal.terminate()).resolves.toBeUndefined()
   })
 })
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index ae44721735..f4719447aa 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 96bbe6c95bd2aca7e66cf2d57abb3f056cd19390
-README.zh.md: 7f091b4f0955b847d21b8b3423dab421e610cda3
+README.md: b15012e882b60847e1ad22edf08d1202ba64fe5b
+README.zh.md: 628f6c74894bc67559d49f7cf5d1378d0ece2382
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 96bbe6c95b..b15012e882 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -14,7 +14,7 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote runtime shared with the E2B subprocess provider ([POC decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 7f091b4f09..628f6c7489 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -14,7 +14,7 @@
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程运行时中（[POC 决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 

From 677541d1230a78fe7af64fd28f0afdaba00225ab Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 22:04:55 +0800
Subject: [PATCH 128/262] fix(e2b): close proven provider boundary gaps

---
 docs/cordis-catalog/services.md               |  2 +-
 packages/e2b/e2b/README.i18n.yaml             |  4 +-
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/src/index.ts                 | 21 ++---
 packages/e2b/e2b/tests/e2b.spec.ts            |  6 +-
 packages/e2b/fs-e2b/src/invariant.ts          |  5 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  6 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  6 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  2 +-
 packages/e2b/subprocess-e2b/src/invariant.ts  |  5 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 15 ++--
 packages/e2b/subprocess-e2b/src/terminal.ts   | 85 +++++++++++++------
 .../subprocess-e2b/tests/subprocess.spec.ts   | 11 ++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 61 +++++++++++++
 16 files changed, 167 insertions(+), 70 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index cdd2d87435..3942c0696d 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:109`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:108`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index fb645c2e36..7d6b503ef4 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 402903184934903eceb36a04d670e4490879ac65
-README.zh.md: 1fec6ab66858f04a47c8a2a7cb5f6a8907ab6cac
+README.md: 6881556dc18497956966aff74adc085d8e8620d3
+README.zh.md: aea13f341f903e6c47b7484f477bf54cebf101c6
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 4029031849..6881556dc1 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -24,7 +24,7 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
 
 `apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes. `onTimeout` is `pause` by default and accepts `pause | kill`; it applies only when this service creates a sandbox. Pause-on-timeout enables E2B auto-resume so the shared SDK handle wakes on its next operation. `onDispose` defaults to `kill` and accepts `kill | pause | leave`.
 
-Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` is creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
+Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` and `onTimeout` are creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
 
 ## Lifecycle and ownership
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 1fec6ab668..aea13f341f 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -24,7 +24,7 @@
 
 `apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟。`onTimeout` 默认为 `pause`，接受 `pause | kill`；它只在本服务创建沙箱时生效。超时时 pause 会启用 E2B 自动恢复，使共享 SDK 句柄在下一次操作时唤醒。`onDispose` 默认为 `kill`，接受 `kill | pause | leave`。
 
-设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
+设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 和 `onTimeout` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
 
 ## 生命周期与所有权
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 9e8960a685..3285d82395 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -91,7 +91,6 @@ interface ResolvedConfig {
 interface SchemaResolvedConfig extends Config {
   cwd: string
   timeoutMs: number
-  onTimeout: E2BTimeoutMode
   onDispose: E2BDisposeMode
 }
 
@@ -113,7 +112,7 @@ export class E2BSandboxService extends Service {
     template: z.string(),
     cwd: z.string().default('/home/user/workspace'),
     timeoutMs: z.number().default(300_000),
-    onTimeout: z.union(['kill', 'pause'] as const).default('pause'),
+    onTimeout: z.union(['kill', 'pause'] as const),
     onDispose: z.union(['kill', 'pause', 'leave'] as const).default('kill'),
   })
 
@@ -121,17 +120,12 @@ export class E2BSandboxService extends Service {
   readonly cwd: string
   /** Remote directory reserved for adapter-owned process and terminal state. */
   readonly runtimeRoot: string
-  /** Whether this service creates a sandbox rather than reconnecting one. */
-  readonly created: boolean
-  /** Configured action when a newly created sandbox reaches its lifetime. */
-  readonly timeoutMode: E2BTimeoutMode
-  /** Configured final sandbox disposition. */
-  readonly disposeMode: E2BDisposeMode
   /** Sandbox id once E2B has created or resolved the remote runtime. */
   readonly sandboxId: Promise<E2BSandboxId>
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
+  private readonly created: boolean
   private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
@@ -144,17 +138,15 @@ export class E2BSandboxService extends Service {
       apiKey: apiKey ?? '',
       cwd: resolved.cwd,
       timeoutMs: resolved.timeoutMs,
-      onTimeout: resolved.onTimeout,
+      onTimeout: config.onTimeout ?? 'pause',
       onDispose: resolved.onDispose,
       ...(config.sandboxId !== undefined ? { sandboxId: config.sandboxId } : {}),
       ...(config.template !== undefined ? { template: config.template } : {}),
     }
-    this.validate()
+    this.validate(config)
     this.cwd = this.config.cwd
     this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
     this.created = this.config.sandboxId === undefined
-    this.timeoutMode = this.config.onTimeout
-    this.disposeMode = this.config.onDispose
     this.ready = this.open()
     // A deployment may load the owner before any adapter uses it. Keep a
     // failed eager connection observed; getSandbox() still returns the error.
@@ -218,7 +210,7 @@ export class E2BSandboxService extends Service {
     return sandbox
   }
 
-  private validate(): void {
+  private validate(input: Config): void {
     if (this.config.apiKey.length === 0) {
       throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
     }
@@ -234,6 +226,9 @@ export class E2BSandboxService extends Service {
     if (this.config.sandboxId !== undefined && this.config.template !== undefined) {
       throw new Error('dsh-e2b: template applies only when creating; omit it when sandboxId reconnects')
     }
+    if (this.config.sandboxId !== undefined && input.onTimeout !== undefined) {
+      throw new Error('dsh-e2b: onTimeout applies only when creating; omit it when sandboxId reconnects')
+    }
   }
 
   private async open(): Promise<Sandbox> {
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index 46ba452210..af55a2419a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -90,9 +90,6 @@ describe('E2BSandboxService', () => {
     await expect(service.sandboxId).resolves.toBe(E2BSandboxId('sandbox-1'))
     expect(service.cwd).toBe('/home/user/workspace')
     expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
-    expect(service.created).toBe(true)
-    expect(service.timeoutMode).toBe('pause')
-    expect(service.disposeMode).toBe('kill')
     expect(sdk.create).toHaveBeenCalledWith({
       apiKey: 'test-key',
       timeoutMs: 300_000,
@@ -225,7 +222,6 @@ describe('E2BSandboxService', () => {
     ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
     const fiber = await ctx.plugin(E2BSandboxService, {
       apiKey: 'test-key',
-      onTimeout: reconnect ? 'kill' : 'pause',
       onDispose: 'pause',
       ...(reconnect ? { sandboxId: 'existing' } : {}),
     })
@@ -248,7 +244,6 @@ describe('E2BSandboxService', () => {
     })
     await ctx.e2b.getSandbox()
 
-    expect(ctx.e2b.created).toBe(false)
     expect(sdk.connect).toHaveBeenCalledWith('existing', { apiKey: 'test-key', timeoutMs: 90_000 })
     expect(sdk.create).not.toHaveBeenCalled()
     await fiber.dispose()
@@ -330,6 +325,7 @@ describe('E2BSandboxService', () => {
     [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
     [{ apiKey: 'x', sandboxId: '' }, /sandboxId must be non-empty/],
     [{ apiKey: 'x', sandboxId: 'one', template: 'two' }, /template applies only/],
+    [{ apiKey: 'x', sandboxId: 'one', onTimeout: 'kill' }, /onTimeout applies only/],
   ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
     vi.stubEnv('E2B_API_KEY', '')
     const ctx = new Context()
diff --git a/packages/e2b/fs-e2b/src/invariant.ts b/packages/e2b/fs-e2b/src/invariant.ts
index 6294d66ace..9f14bb37a6 100644
--- a/packages/e2b/fs-e2b/src/invariant.ts
+++ b/packages/e2b/fs-e2b/src/invariant.ts
@@ -1,4 +1,7 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`. */
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`.
+ * @module @deepseek-ai/dsh-fs-e2b/invariant
+ */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 20ba9b597e..9ac46f1bcb 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 9e044c13b673461a876e016ec560db4897a27c66
-README.zh.md: b9180c0c0679915fae7a1db22353613708392a8c
+README.md: 9d563c91c149d28718159af1b1f8ddbd6652dc44
+README.zh.md: be189f41818c66aeff2bed7b1851b82ca08f08f4
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 9e044c13b6..9d563c91c1 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -9,12 +9,12 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — one trusted control-shell probe transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the template's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index b9180c0c06..be189f4181 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -9,12 +9,12 @@
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：一次受信任的控制 shell 探测会以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变模板 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 907810a1d7..8daae9ccfd 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -29,7 +29,7 @@ export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSign
   // TODO(e2b-replace-environment): Remove this ambient probe when E2B can start
   // a command with a replacement environment instead of merged overrides.
   const result = await sandbox.commands.run(
-    'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    'set -o pipefail; dsh_e2b_passwd="$(getent passwd "$(id -u)")"; IFS=: read -r _ _ _ _ _ dsh_e2b_home _ <<<"$dsh_e2b_passwd"; test -n "$dsh_e2b_home" -a -d "$dsh_e2b_home"; printf \'%s\' "$dsh_e2b_home" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
     { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
   )
   const lines = result.stdout.trim().split('\n')
diff --git a/packages/e2b/subprocess-e2b/src/invariant.ts b/packages/e2b/subprocess-e2b/src/invariant.ts
index 4416175b1b..9f8b8fb739 100644
--- a/packages/e2b/subprocess-e2b/src/invariant.ts
+++ b/packages/e2b/subprocess-e2b/src/invariant.ts
@@ -1,4 +1,7 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`. */
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`.
+ * @module @deepseek-ai/dsh-subprocess-e2b/invariant
+ */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 02e1583e56..83dedd4e97 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -104,7 +104,6 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     : `2> >(${encoder} >&2 2>/dev/null)`
   const inner = [
     'set +e',
-    'umask 077',
     'dsh_e2b_env_bin=$1',
     'dsh_e2b_node=$2',
     'dsh_e2b_ps=$3',
@@ -520,6 +519,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       () => true,
     )
     while (true) {
+      // TODO(e2b-publication-cancel): Join cancellation to the existing
+      // termination transaction before aborting an in-flight SDK file read.
       const raw = await sandbox.files.read(this.paths.pid)
       const value = raw.trim()
       if (value.length > 0) {
@@ -543,6 +544,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       result => ({ kind: 'result', result }),
       (error: unknown) => ({ kind: 'error', error }),
     )
+    const hasPipeOutput = this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe'
+    let completed = hasPipeOutput ? await settlement : undefined
     while (true) {
       const rawStatus = (await sandbox.files.read(this.paths.status)).trim()
       if (rawStatus.length > 0) {
@@ -550,19 +553,19 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
           throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
         }
-        if (this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe') {
-          return this.commandOutcome(await settlement, exitCode)
-        }
-        const completed = await withinMs(settlement, this.spec.graceMs)
         if (completed !== undefined) return this.commandOutcome(completed, exitCode)
+        const drained = await withinMs(settlement, this.spec.graceMs)
+        if (drained !== undefined) return this.commandOutcome(drained, exitCode)
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
         await handle.disconnect()
         return { exitCode, signal: null }
       }
-      const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
       if (completed !== undefined) return this.commandOutcome(completed)
+      // TODO(e2b-status-watch): Replace collect/inherit polling when E2B can
+      // observe direct-command exit independently of descendant-held output.
+      completed = await Promise.race([settlement, waitTick().then(() => undefined)])
     }
   }
 
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 6c4b23d1c1..8d003dfc35 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -345,6 +345,9 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
 
   private topLevelExited = false
   private cleanup: Promise<void> | undefined
+  private readonly operationController = new AbortController()
+  private readonly operations = new Set<Promise<unknown>>()
+  private terminating = false
   private terminationSignal: NodeJS.Signals | null = null
 
   constructor(
@@ -364,17 +367,56 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   // TODO(e2b-pgid-identity): Replace retained numeric PTY/session ids when E2B
   // exposes identity-bound input, foreground-signal, and cleanup operations.
   /** @inheritdoc */
-  async write(data: string): Promise<void> {
-    if (this.topLevelExited) throw new Error('terminal process has exited')
-    await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'))
+  write(data: string): Promise<void> {
+    return this.trackOperation(async (signal) => {
+      if (this.topLevelExited) throw new Error('terminal process has exited')
+      await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'), { signal })
+    })
   }
 
   /** @inheritdoc */
-  async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    return this.trackOperation(signal => this.inspectForegroundOnce(signal))
+  }
+
+  /** @inheritdoc */
+  signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    return this.trackOperation(async (operationSignal) => {
+      const foreground = await this.inspectForegroundOnce(operationSignal)
+      if (foreground === undefined) {
+        throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
+      }
+      if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+        throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+      }
+      await this.sandbox.commands.run(
+        `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
+        commandOpts(this.controlEnvs, operationSignal),
+      )
+      return foreground.processGroupId
+    })
+  }
+
+  /** @inheritdoc */
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    this.terminating = true
+    this.operationController.abort(new Error('subprocess-e2b: terminal is terminating'))
+    const cleanup = this.closeAfterOperations()
+    this.cleanup = cleanup
+    void cleanup.catch((_cleanupFailure: unknown) => {
+      this.cleanup = undefined
+    })
+    return cleanup
+  }
+
+  private async inspectForegroundOnce(
+    signal: AbortSignal,
+  ): Promise<SubprocessTerminalForeground | undefined> {
     try {
       const result = await this.sandbox.commands.run(
         `ps -o tpgid= -p ${this.pid}`,
-        commandOpts(this.controlEnvs),
+        commandOpts(this.controlEnvs, signal),
       )
       return {
         processGroupId: parsePositiveId(
@@ -391,31 +433,20 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     }
   }
 
-  /** @inheritdoc */
-  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
-    const foreground = await this.inspectForeground()
-    if (foreground === undefined) {
-      throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
-    }
-    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
-      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
-    }
-    await this.sandbox.commands.run(
-      `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
-      commandOpts(this.controlEnvs),
+  private trackOperation<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> {
+    if (this.terminating) return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    const pending = operation(this.operationController.signal)
+    this.operations.add(pending)
+    void pending.then(
+      () => { this.operations.delete(pending) },
+      () => { this.operations.delete(pending) },
     )
-    return foreground.processGroupId
+    return pending
   }
 
-  /** @inheritdoc */
-  terminate(): Promise<void> {
-    if (this.cleanup !== undefined) return this.cleanup
-    const cleanup = this.closeOnce()
-    this.cleanup = cleanup
-    void cleanup.catch((_cleanupFailure: unknown) => {
-      this.cleanup = undefined
-    })
-    return cleanup
+  private async closeAfterOperations(): Promise<void> {
+    if (this.operations.size > 0) await Promise.allSettled(this.operations)
+    await this.closeOnce()
   }
 
   private async waitForCommand(): Promise<SubprocessOutcome> {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 0e906b1cfb..83e86892d4 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -116,6 +116,7 @@ class FakeSandbox {
   environmentRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   processGroupId = '4242\n'
   exitStatus = ''
+  statusReads = 0
   readonly processGroupReads: string[] = []
   afterStatusRead: (() => void) | undefined
   beforeProbe: (() => void) | undefined
@@ -222,6 +223,7 @@ class FakeSandbox {
           this.statusError = undefined
           throw error
         }
+        this.statusReads += 1
         this.afterStatusRead?.()
         return this.exitStatus
       },
@@ -415,9 +417,10 @@ describe('E2BSubprocessHandle', () => {
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(fake.commandsSeen).toContain(
-      'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
-    )
+    const environmentProbe = fake.commandsSeen.find(value => value.includes('env -0 | base64'))
+    expect(environmentProbe).toContain('getent passwd "$(id -u)"')
+    expect(environmentProbe).toContain('test -n "$dsh_e2b_home" -a -d "$dsh_e2b_home"')
+    expect(environmentProbe).not.toContain('"$PWD"')
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
@@ -535,11 +538,13 @@ describe('E2BSubprocessHandle', () => {
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(settled).toBe(false)
     expect(fake.handle.disconnects).toBe(0)
+    expect(fake.statusReads).toBe(0)
 
     await fake.stdout('complete protocol frame')
     fake.finish()
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(output).toBe('complete protocol frame')
+    expect(fake.statusReads).toBe(1)
   })
 
   it('accepts clean encoder completion inside the output-drain grace', async () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 6c3ef477af..a4f4008a56 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -102,6 +102,9 @@ class FakeTerminalSandbox {
   sendError: unknown
   commandFailure: unknown
   makeDirRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  sendInputRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  foregroundRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  signalRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
@@ -180,6 +183,8 @@ class FakeTerminalSandbox {
           return { exitCode: 0, stdout: this.sessionId, stderr: '' }
         }
         if (command.startsWith('ps -o tpgid=')) {
+          await this.foregroundRequest?.(options?.signal)
+          options?.signal?.throwIfAborted()
           if (this.foregroundFailure !== undefined) throw this.foregroundFailure
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
         }
@@ -197,6 +202,10 @@ class FakeTerminalSandbox {
             this.handle.fail(143)
           }
         }
+        if (command.startsWith('kill -INT -- ')) {
+          await this.signalRequest?.(options?.signal)
+          options?.signal?.throwIfAborted()
+        }
         if (command.startsWith('kill -KILL -- ') && this.clearOnKill) this.groups = []
         return { exitCode: 0, stdout: '', stderr: '' }
       },
@@ -211,6 +220,8 @@ class FakeTerminalSandbox {
         return this.handle.asHandle()
       },
       sendInput: async (pid: number, data: Uint8Array, options?: { signal?: AbortSignal }): Promise<void> => {
+        options?.signal?.throwIfAborted()
+        await this.sendInputRequest?.(options?.signal)
         options?.signal?.throwIfAborted()
         this.inputs.push({ pid, data: Buffer.from(data) })
         if (this.sendError !== undefined) throw this.sendError
@@ -257,6 +268,19 @@ function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessT
   }
 }
 
+function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
+  return async (signal: AbortSignal | undefined): Promise<void> => {
+    if (signal === undefined) throw new Error('expected an operation signal')
+    signal.throwIfAborted()
+    started.resolve(signal)
+    await new Promise<void>((_resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+      }, { once: true })
+    })
+  }
+}
+
 describe('E2B terminal allocation', () => {
   it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
@@ -544,6 +568,43 @@ describe('E2B terminal allocation', () => {
 })
 
 describe('E2B terminal lifecycle', () => {
+  it('aborts and joins in-flight terminal operations before cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/in-flight-operations')
+    const writeStarted = Promise.withResolvers<AbortSignal>()
+    const inspectStarted = Promise.withResolvers<AbortSignal>()
+    const signalStarted = Promise.withResolvers<AbortSignal>()
+    fake.sendInputRequest = holdRequestUntilAbort(writeStarted)
+    let foregroundRequests = 0
+    fake.foregroundRequest = async (signal) => {
+      foregroundRequests += 1
+      if (foregroundRequests === 1) await holdRequestUntilAbort(inspectStarted)(signal)
+    }
+    let signalCompleted = false
+    fake.signalRequest = async (operationSignal) => {
+      await holdRequestUntilAbort(signalStarted)(operationSignal)
+      signalCompleted = true
+    }
+    const write = terminal.write('late input')
+    const inspect = terminal.inspectForeground()
+    await Promise.all([writeStarted.promise, inspectStarted.promise])
+    const signal = terminal.signalForeground('SIGINT')
+    await signalStarted.promise
+
+    const terminating = terminal.terminate()
+    await expect(write).rejects.toThrow('terminal is terminating')
+    await expect(inspect).rejects.toThrow('terminal is terminating')
+    await expect(signal).rejects.toThrow('terminal is terminating')
+    await terminating
+    expect(signalCompleted).toBe(false)
+    expect(fake.inputs).toHaveLength(1)
+    const commandCount = fake.commands.length
+    await expect(terminal.write('after termination')).rejects.toThrow('terminal is terminating')
+    await expect(terminal.inspectForeground()).rejects.toThrow('terminal is terminating')
+    await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('terminal is terminating')
+    expect(fake.commands).toHaveLength(commandCount)
+  })
+
   it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []

From e8d55999456164af0a9842d0f103c2a9b77916ec Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 23:53:20 +0800
Subject: [PATCH 129/262] refactor(e2b): narrow settlement polling helper

---
 packages/e2b/subprocess-e2b/src/process.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 83dedd4e97..5e383a50e2 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -84,10 +84,10 @@ type CommandSettlement =
   | { kind: 'result'; result: CommandResult }
   | { kind: 'error'; error: unknown }
 
-function withinMs<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
-  return new Promise<T | undefined>((resolve) => {
+function withinMs(settlement: Promise<CommandSettlement>, timeoutMs: number): Promise<CommandSettlement | undefined> {
+  return new Promise<CommandSettlement | undefined>((resolve) => {
     const timer = setTimeout(() => { resolve(undefined) }, timeoutMs)
-    void promise.then((value) => {
+    void settlement.then((value) => {
       clearTimeout(timer)
       resolve(value)
     })
@@ -563,8 +563,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         return { exitCode, signal: null }
       }
       if (completed !== undefined) return this.commandOutcome(completed)
-      // TODO(e2b-status-watch): Replace collect/inherit polling when E2B can
-      // observe direct-command exit independently of descendant-held output.
+      // TODO(e2b-status-watch): Replace collect/inherit control-plane polling
+      // when E2B can observe direct-command exit independently of descendant-held output.
       completed = await Promise.race([settlement, waitTick().then(() => undefined)])
     }
   }

From bb0be75d8549473996bbea3761897465e5a92141 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 23:56:02 +0800
Subject: [PATCH 130/262] refactor(e2b): drop obsolete host sandbox overlay

---
 examples/headless-agent/e2b.cordis.snapshot.yml           | 2 --
 examples/headless-agent/e2b.cordis.yml                    | 2 --
 examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml | 3 ---
 3 files changed, 7 deletions(-)

diff --git a/examples/headless-agent/e2b.cordis.snapshot.yml b/examples/headless-agent/e2b.cordis.snapshot.yml
index 3f39f0ffe4..936aab290d 100644
--- a/examples/headless-agent/e2b.cordis.snapshot.yml
+++ b/examples/headless-agent/e2b.cordis.snapshot.yml
@@ -29,8 +29,6 @@
             name: '@deepseek-ai/dsh-code-runtime-subprocess'
           - id: tool-cordis
             name: '@deepseek-ai/dsh-tool-cordis'
-          - id: sandbox
-            name: '@deepseek-ai/dsh-sandbox-local'
           - id: sandbox-policy
             name: '@deepseek-ai/dsh-sandbox-policy'
             config:
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 32d7049c5d..683bb7a0d4 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -34,8 +34,6 @@
             name: '@deepseek-ai/dsh-fs-e2b'
           - id: code-runtime-subprocess
             name: '@deepseek-ai/dsh-code-runtime-subprocess'
-          - id: sandbox
-            name: '@deepseek-ai/dsh-sandbox-local'
           - id: sandbox-policy
             name: '@deepseek-ai/dsh-sandbox-policy'
             config:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index d2b73c1077..4132f4d1d6 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -21,9 +21,6 @@
 - id: agents
   name: '@deepseek-ai/dsh-agent'
 
-- id: sandbox
-  name: '@deepseek-ai/dsh-sandbox-local'
-
 - id: sandbox-policy
   name: '@deepseek-ai/dsh-sandbox-policy'
   config:

From de77310c6f68bafc6593dd37f134fd282bcbdd7b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 04:25:47 +0800
Subject: [PATCH 131/262] refactor(e2b): narrow the sandbox POC

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |   8 +-
 ...8-portable-execution-world-consumers.zh.md |   8 +-
 AGENTS.md                                     |   7 +-
 docs/cordis-catalog/services.md               |   8 +-
 .../headless-agent/e2b.cordis.snapshot.yml    |  56 -----
 examples/headless-agent/e2b.cordis.yml        |   7 -
 .../tests/fixtures/e2b/e2b/bin.ts             | 215 +-----------------
 .../tests/fixtures/e2b/e2b/cordis.yml         |   4 -
 .../headless-agent/tests/headless.snapshot.ts |  56 -----
 .../tests/snapshots/e2b-overlay/input.json    |   8 -
 .../e2b-overlay/replay.override.json          |  12 -
 .../e2b-overlay/stream-json.expected.jsonl    |  14 --
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |   2 +-
 packages/e2b/README.zh.md                     |   2 +-
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |  18 +-
 packages/e2b/e2b/README.zh.md                 |  18 +-
 packages/e2b/e2b/package.json                 |   2 -
 packages/e2b/e2b/src/index.ts                 | 146 +++---------
 packages/e2b/e2b/tests/composition.e2e.ts     |  51 +----
 packages/e2b/e2b/tests/e2b.spec.ts            | 122 +---------
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   4 +-
 packages/e2b/fs-e2b/README.zh.md              |   4 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |   1 -
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  11 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  11 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  13 +-
 packages/e2b/subprocess-e2b/src/output.ts     |   3 -
 packages/e2b/subprocess-e2b/src/process.ts    |  59 ++---
 packages/e2b/subprocess-e2b/src/terminal.ts   |  72 ++----
 .../subprocess-e2b/tests/subprocess.spec.ts   |   4 -
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  85 ++-----
 pnpm-lock.yaml                                |   6 +-
 37 files changed, 176 insertions(+), 881 deletions(-)
 delete mode 100644 examples/headless-agent/e2b.cordis.snapshot.yml
 delete mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/input.json
 delete mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
 delete mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index fc3b5b012f..c7ce82595d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 250445cfed6a4fe2dd188562813d586df29992c1
-2026-07-28-portable-execution-world-consumers.zh.md: 361c4de4e813aa7f57a7eb5acc75087b2630db43
+2026-07-28-portable-execution-world-consumers.md: 57c3a8a8b211279593359b02def865644052f549
+2026-07-28-portable-execution-world-consumers.zh.md: 8231913c26f75361add7a28bc40f7723c9b18728
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 4c593604f4..6f296bfa74 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -28,17 +28,17 @@ Generic consumers use that execution world:
 
 ## E2B POC boundary
 
-The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates or reconnects one sandbox and owns kill/pause/leave disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole sandbox identity from the owner and never create private sandboxes.
+The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates one sandbox and deletes it on timeout or disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole SDK handle from the owner and never create private sandboxes.
 
 E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, subprocess Code Runtime processes, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, Code Runtime program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
 
 The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
 
-Retaining a sandbox preserves remote files and unmanaged state only. Reconnect does not reconstruct host process or terminal handles, protocol connections, pending calls, output cursors, timers, or locks. The POC adds no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
+Sandbox state is deliberately ephemeral: timeout and disposal delete the remote files and unmanaged state. The POC adds no reconnect or pause/leave retention, session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
 
 ## Verification
 
-Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, post-rename version reread plus guarded edit, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP document bounds, Code Runtime bindings/limits/cleanup, host-workspace isolation, and final sandbox deletion.
+Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP queries, Code Runtime bindings and cleanup, host-workspace isolation, and final sandbox deletion.
 
 ## Alternatives considered
 
@@ -70,4 +70,4 @@ The fundamental interfaces are wider, and a filesystem/subprocess pair must agre
 
 The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
 
-The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, retained artifacts accumulate, and escaped processes or reconnect state are not recovered. These are provider constraints, not justification for compatibility shims or more E2B packages.
+The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, and adapter artifacts remain until sandbox deletion. These are provider constraints, not justification for compatibility shims or more E2B packages.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 361c4de4e8..471753573d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -31,17 +31,17 @@ Status: implemented
 
 ## E2B POC 边界
 
-可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建或重新连接一个沙箱，并负责 kill、pause 或 leave 资源释放；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的沙箱身份，绝不创建私有沙箱。
+可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建一个沙箱，并在超时或资源释放时将其删除；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的 SDK 句柄，绝不创建私有沙箱。
 
 E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取、子进程代码运行时进程，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、代码运行时程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
 
 适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
 
-保留沙箱只会保留远程文件与非托管状态。重新连接不会重建宿主进程或终端句柄、协议连接、待处理调用、输出游标、计时器或锁。该 POC 不会新增会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄，也不会在其中运行整个 harness。
+沙箱状态有意保持短暂：超时与资源释放会删除远程文件和非托管状态。该 POC 不提供重新连接、pause/leave 保留、会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄，也不会在其中运行整个 harness。
 
 ## 验证
 
-聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、重命名后的版本重读与带保护编辑、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 文档上限、代码运行时绑定／上限／清理、宿主工作区隔离，以及最终沙箱删除。
+聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 查询、代码运行时绑定与清理、宿主工作区隔离，以及最终沙箱删除。
 
 ## 考虑过的替代方案
 
@@ -75,4 +75,4 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
 
-E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；保留的产物会累积；也不会恢复逃逸进程或重连状态。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。
+E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；适配器产物会一直保留到沙箱删除。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。
diff --git a/AGENTS.md b/AGENTS.md
index c663a5e099..1d2a6d977c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,8 +12,9 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
+  typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
-  e2b/         remote-runtime POC
+  e2b/         E2B POC: sandbox owner + FS/subprocess adapters
   bash/        bash executor seam + local impl + model-facing bash tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
@@ -90,7 +91,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)).
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). TUI/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
@@ -114,7 +115,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
-- **Use incremental merge commits.** Split independent changes; never squash, rebase, or rewrite pushed history. Fix the introducing PR before merging down-stack. If the base advances mid-merge, never restart: finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
+- **Use incremental merge commits.** Split independent changes. Pushed history may be rewritten before review; afterward prefer new commits. Fix the introducing PR before merging down-stack. If the base advances mid-merge, finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
 - **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 3942c0696d..db66ca5799 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -580,18 +580,18 @@ Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/
 
 ## `ctx.e2b` — `E2BSandboxService`
 
-Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decision. The connection begins at plugin construction; adapters await getSandbox before their first operation.
+Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
 
 ```ts cordis-catalog
 /**
  * Return the shared live SDK handle.
- * @returns the created or reconnected sandbox after the configured cwd exists.
- * @throws when E2B rejects creation/reconnection or the service is disposing.
+ * @returns the created sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation or the service is disposing.
  */
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:108`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:76`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/examples/headless-agent/e2b.cordis.snapshot.yml b/examples/headless-agent/e2b.cordis.snapshot.yml
deleted file mode 100644
index 936aab290d..0000000000
--- a/examples/headless-agent/e2b.cordis.snapshot.yml
+++ /dev/null
@@ -1,56 +0,0 @@
-# Keyless counterpart to e2b.cordis.yml. It keeps the same generic PTY, LSP,
-# and subprocess Code Runtime consumers, but supplies their fundamental
-# filesystem/process world locally and replaces the live model with replay.
-- id: base
-  name: '@cordisjs/plugin-include'
-  config:
-    path: ./cordis.yml
-    patches:
-      - id: llm-deepseek
-        name: '@deepseek-ai/dsh-llm-deepseek'
-        disabled: true
-      - id: cli-agent
-        name: '@deepseek-ai/dsh-cli-demo'
-        config:
-          provider: deepseek
-          model: deepseek-v4-pro
-          persistenceRoot: './.sessions'
-          persistenceCompression: none
-          workspaceContext:
-            maxBytes: 65536
-          tools:
-            mode: both
-          persona: |
-            You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
-
-            Verify your work by running the code or tests. Keep answers brief and factual.
-      - insert:
-          - id: code-runtime-subprocess
-            name: '@deepseek-ai/dsh-code-runtime-subprocess'
-          - id: tool-cordis
-            name: '@deepseek-ai/dsh-tool-cordis'
-          - id: sandbox-policy
-            name: '@deepseek-ai/dsh-sandbox-policy'
-            config:
-              mode: danger-full-access
-              workspaceRoot: !!js process.cwd()
-          - id: pty
-            name: '@deepseek-ai/dsh-pty'
-          - id: pty-local
-            name: '@deepseek-ai/dsh-pty-local'
-          - id: tool-pty
-            name: '@deepseek-ai/dsh-tool-pty'
-          - id: lsp
-            name: '@deepseek-ai/dsh-lsp'
-          - id: lsp-local
-            name: '@deepseek-ai/dsh-lsp-local'
-            config:
-              servers:
-                typescript:
-                  command: node
-                  extensionToLanguage:
-                    .ts: typescript
-          - id: tool-lsp
-            name: '@deepseek-ai/dsh-tool-lsp'
-          - id: llm-replay
-            name: '@deepseek-ai/dsh-llm-replay'
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 683bb7a0d4..724f30240d 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -15,19 +15,12 @@
       - id: code-runtime
         name: '@deepseek-ai/dsh-code-runtime-worker'
         disabled: true
-      - id: bash
-        name: '@deepseek-ai/dsh-bash-local'
-        config:
-          cwd: !!js process.cwd()
-          timeoutMs: 60000
       - insert:
           - id: e2b
             name: '@deepseek-ai/dsh-e2b'
             config:
               cwd: !!js process.cwd()
               timeoutMs: 300000
-              onTimeout: kill
-              onDispose: kill
           - id: subprocess-e2b
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 856a26ed78..570a244e88 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,10 +1,9 @@
 import { readFile } from 'node:fs/promises'
-import { posix, resolve } from 'node:path'
+import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-code-runtime-subprocess'
-import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
 import type {} from '@deepseek-ai/dsh-lsp-local'
@@ -36,18 +35,17 @@ try {
   const sandbox = await ctx.e2b.getSandbox()
   const fromFs = await ctx.fs.resolve('from-fs.txt')
   const written = await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
-  const reread = await ctx.fs.stat(fromFs)
-  if (reread?.version !== written.version) {
-    throw new Error(`E2B rename did not preserve version metadata: ${JSON.stringify({ written, reread })}`)
+  const observed = await ctx.fs.stat(fromFs)
+  if (observed?.version !== written.version) {
+    throw new Error(`E2B rename did not preserve version metadata: ${JSON.stringify({ written, observed })}`)
   }
   await ctx.fs.editText(
     fromFs,
-    { oldString: 'written-by-fs', newString: 'written-by-fs-versioned', replaceAll: false },
-    { version: reread.version },
+    { oldString: 'written-by-fs', newString: 'versioned-by-fs', replaceAll: false },
+    { version: observed.version },
   )
-  const fsVersionGuard = true
   const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
-  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs-versioned\n') {
+  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'versioned-by-fs\n') {
     throw new Error(`E2B Bash could not read the FS write: ${JSON.stringify(bashRead)}`)
   }
 
@@ -114,67 +112,11 @@ try {
   )
   if (outputDrainOutcome.exitCode !== 0 || outputDrainText !== 'leader-done\n'
     || outputDrainElapsedMs >= 10_000 || !outputDrainExited || !outputDrainClean) {
-    throw new Error(`E2B subprocess output drain was not bounded: ${JSON.stringify({
+    throw new Error(`E2B subprocess did not bound descendant-held output: ${JSON.stringify({
       outputDrainOutcome, outputDrainText, outputDrainElapsedMs, outputDrainExited, outputDrainClean,
     })}`)
   }
 
-  const remoteFiles = sandbox.files as unknown as {
-    read(path: string, options?: unknown): Promise<unknown>
-  }
-  const readRemoteFile = remoteFiles.read.bind(sandbox.files)
-  let publicationFaultInjected = false
-  remoteFiles.read = async (path, options) => {
-    if (!publicationFaultInjected && path.includes('/processes/') && path.endsWith('/pid')) {
-      publicationFaultInjected = true
-      throw new Error('injected process-group publication read failure')
-    }
-    return await readRemoteFile(path, options)
-  }
-  let publicationRollback = false
-  try {
-    const unpublished = ctx.subprocess.spawn({
-      argv: ['bash', '-c', 'exec -a dsh-publication-survivor sleep 30 & wait'],
-      cwd: process.cwd(),
-      stdio: { stdin: 'ignore', stdout: { maxBytes: 4_096 }, stderr: { maxBytes: 4_096 } },
-      graceMs: 500,
-      env: {},
-    })
-    await unpublished.done
-    throw new Error('E2B subprocess unexpectedly survived an injected publication failure')
-  } catch (error: unknown) {
-    if (!String(error).includes('injected process-group publication read failure')) throw error
-    const processes = await sandbox.commands.run('ps -eo args=')
-    publicationRollback = publicationFaultInjected && !processes.stdout.includes('dsh-publication-survivor')
-    if (!publicationRollback) throw new Error('E2B subprocess publication rollback left its remote process group alive')
-  } finally {
-    remoteFiles.read = readRemoteFile
-  }
-
-  const spillHandle = ctx.subprocess.spawn({
-    argv: ['bash', '-c', "printf '0123456789'; sleep 30"],
-    cwd: process.cwd(),
-    stdio: { stdin: 'ignore', stdout: { maxBytes: 4, spill: { maxBytes: 6 } }, stderr: { maxBytes: 4_096 } },
-    graceMs: 500,
-    env: {},
-  })
-  const spillReader = spillHandle.collected.stdout
-  if (spillReader === undefined) throw new Error('E2B subprocess omitted its configured stdout collector')
-  const spillDeadline = Date.now() + 15_000
-  while (spillReader.readFrom(0).nextOffset < 10) {
-    if (Date.now() >= spillDeadline) throw new Error('E2B subprocess did not stream the spill probe output')
-    await new Promise(resolveDelay => setTimeout(resolveDelay, 20))
-  }
-  const spillPath = posix.join((spillHandle as unknown as { stateDir: string }).stateDir, 'stdout.log')
-  const liveSpillBytes = (await (await ctx.e2b.getSandbox()).files.getInfo(spillPath)).size
-  spillHandle.terminate()
-  const spillOutcome = await spillHandle.done
-  const spillExited = await spillHandle.waitForExit(AbortSignal.timeout(5_000))
-  const spillRead = spillReader.readFrom(0)
-  if (liveSpillBytes !== 6 || !spillExited || spillRead.spillPath !== undefined) {
-    throw new Error(`E2B subprocess spill bound failed: ${JSON.stringify({ liveSpillBytes, spillExited, spillRead })}`)
-  }
-
   const lspFixture = await readFile(new URL('./fixture-lsp.mjs', import.meta.url), 'utf8')
   const remoteLspFixture = await ctx.fs.resolve('fixture-lsp.mjs')
   await ctx.fs.writeText(remoteLspFixture, lspFixture, { kind: 'createIfAbsent' })
@@ -193,53 +135,12 @@ try {
     workspaceRoot: process.cwd(),
   })
 
-  const oversizedSourcePath = posix.join(process.cwd(), 'oversized-source.ts')
-  await sandbox.commands.run(`head -c 4000001 /dev/zero | tr '\\0' x > ${quoteE2BShellArg(oversizedSourcePath)}`)
-  let lspDocumentBound = false
-  try {
-    await ctx.lsp.query({
-      operation: 'hover',
-      filePath: 'oversized-source.ts',
-      position: { line: 0, character: 0 },
-      workspaceRoot: process.cwd(),
-    })
-  } catch (error: unknown) {
-    lspDocumentBound = String(error).includes('exceeds the 4000000-byte limit')
-    if (!lspDocumentBound) throw error
-  }
-  if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
-
-  const remoteCommands = sandbox.commands as unknown as {
-    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
-  }
-  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
   terminalId = terminal.sessionId
   const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
     text: "printf 'PTY-你好\\n'",
     submit: true,
   }).done
-  const foregroundLookup = Promise.withResolvers<undefined>()
-  let delayedForegroundLookup = false
-  remoteCommands.run = async (command, options) => {
-    if (!delayedForegroundLookup && command.startsWith('ps -o tpgid=')) {
-      delayedForegroundLookup = true
-      await foregroundLookup.promise
-    }
-    return await runRemoteCommand(command, options)
-  }
-  const staleInterrupt = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 0.2', submit: true })
-  if (!staleInterrupt.cancel()) throw new Error('E2B PTY refused the stale-interrupt probe cancellation')
-  let canceledSendRetained = false
-  try {
-    ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
-  } catch (error: unknown) {
-    canceledSendRetained = String(error).includes('active send')
-  }
-  foregroundLookup.resolve(undefined)
-  await staleInterrupt.done
-  remoteCommands.run = runRemoteCommand
-  if (!canceledSendRetained) throw new Error('E2B PTY released a canceled send before foreground signalling settled')
   const sleeping = ctx.pty.startSend(owner, terminal.sessionId, {
     text: "printf 'DSH_SLEEP_%s\\n' READY; sleep 30",
     submit: true,
@@ -258,13 +159,6 @@ try {
     }
     if (Date.now() >= sleepReadyDeadline) throw new Error(`E2B PTY successor did not execute: ${sleepReadyOutput}`)
   }
-  const interruptIdentitySafe = await Promise.race([
-    sleeping.done.then(() => false),
-    new Promise<true>(resolveDelay => setTimeout(() => { resolveDelay(true) }, 300)),
-  ])
-  if (!delayedForegroundLookup || !interruptIdentitySafe) {
-    throw new Error('E2B PTY stale interrupt affected its successor send')
-  }
   const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
   const interrupted = await sleeping.done
   const stubborn = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -284,24 +178,6 @@ try {
   const code = await ctx.codeRuntime.run({
     program: `
       console.log('remote-log 你好', 42)
-      const arrayPrototype = Array.prototype
-      const objectPrototype = Object.prototype
-      const setPrototype = Set.prototype
-      const stringPrototype = String.prototype
-      Array.isArray = () => false
-      Object.defineProperty = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') }
-      Object.hasOwn = () => false
-      Object.is = () => true
-      objectPrototype.propertyIsEnumerable = () => false
-      Number.isFinite = Number.isSafeInteger = () => false
-      Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') }
-      setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') }
-      stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') }
-      Buffer.byteLength = () => 0
-      Function.prototype.toString = () => 'mutated'
-      objectPrototype.constructor = arrayPrototype.constructor = null
-      globalThis.Array = globalThis.Buffer = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Promise = globalThis.Reflect = globalThis.Set = globalThis.String = undefined
-      process.stdout.write('post-mutation', () => {})
       const doubled: number = await bridge.double({ value: 21 })
       let typed = false
       try {
@@ -323,42 +199,6 @@ try {
       },
     }],
   })
-  const hostileOutput = await ctx.codeRuntime.run({
-    program: `
-      const payload = '🙂'.repeat(4096)
-      String.prototype[Symbol.iterator] = () => { throw new Error('mutated string iterator') }
-      console.log(payload)
-      return true
-    `,
-    bindings: [],
-  })
-  const nativeOutput = await ctx.codeRuntime.run({
-    program: `
-      let stdoutPrototype = Object.getPrototypeOf(process.stdout)
-      while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
-      Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(8192)])
-      return true
-    `,
-    bindings: [],
-  })
-  const descriptorOutput = await ctx.codeRuntime.run({
-    program: `
-      const fs = await import('node:fs')
-      const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
-      fs.writeSync(1, forged)
-      fs.writeSync(1, 'x'.repeat(8192))
-      return true
-    `,
-    bindings: [],
-  })
-  const inheritedOutput = await ctx.codeRuntime.run({
-    program: `
-      const childProcess = await import('node:child_process')
-      childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("x".repeat(8192))'], { stdio: 'inherit' })
-      return true
-    `,
-    bindings: [],
-  })
   const descendantPipe = await ctx.codeRuntime.run({
     program: `
       const childProcess = await import('node:child_process')
@@ -376,67 +216,30 @@ try {
     JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-code-runtime-descendant'),
   )
   if (!descendantCleanup) throw new Error('E2B Code Runtime left a pipe-holding descendant alive')
-  const timedOut = await ctx.codeRuntime.run({
-    program: 'await new Promise(() => {})',
-    bindings: [],
-  })
-  const abortController = new AbortController()
-  const aborting = ctx.codeRuntime.run({
-    program: 'await new Promise(() => {})',
-    bindings: [],
-    signal: abortController.signal,
-  })
-  setTimeout(() => { abortController.abort('live abort') }, 50)
-  const aborted = await aborting
-  const oversizedBoot = await ctx.codeRuntime.run({
-    program: `return ${JSON.stringify('x'.repeat(40_000))}`,
-    bindings: [],
-  })
-  const oversizedReply = await ctx.codeRuntime.run({
-    program: 'return await bridge.large(null)',
-    bindings: [{
-      global: 'bridge',
-      functions: { large: async () => 'x'.repeat(40_000) },
-    }],
-  })
   const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
   const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
     JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
   )
 
   process.stdout.write(`${JSON.stringify({
-    sandboxId: await ctx.e2b.sandboxId,
+    sandboxId: (await ctx.e2b.getSandbox()).sandboxId,
     bashRead: bashRead.stdout.text,
-    fsVersionGuard,
     fsRead,
     explicitEnvironment,
     splitUtf8Output,
-    outputDrain: { outcome: outputDrainOutcome, text: outputDrainText, exited: outputDrainExited, clean: outputDrainClean },
-    publicationRollback,
-    spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
-    lspDocumentBound,
     terminal: {
       motd: terminal.motd,
       echo: terminalEcho,
       signal: terminalSignal,
       interrupted,
-      interruptIdentitySafe,
       treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
     code,
-    hostileOutput,
-    nativeOutput,
-    descriptorOutput,
-    inheritedOutput,
     descendantPipe,
     descendantCleanup,
-    timedOut,
-    aborted,
-    oversizedBoot,
-    oversizedReply,
     lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 4132f4d1d6..043362aaa1 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -3,8 +3,6 @@
   config:
     cwd: !!js process.cwd()
     timeoutMs: 180000
-    onTimeout: kill
-    onDispose: kill
 
 - id: subprocess-e2b
   name: '@deepseek-ai/dsh-subprocess-e2b'
@@ -12,7 +10,6 @@
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
-    cwd: !!js process.cwd()
     timeoutMs: 30000
 
 - id: fs-e2b
@@ -63,5 +60,4 @@
     maxWallMs: 15000
     maxOutputBytes: 4096
     maxOldGenerationSizeMb: 128
-    maxFrameBytes: 32768
     killGraceMs: 500
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index ca8e93724c..87261439da 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -25,8 +25,6 @@ const advancedScenarioDir = join(snapshotsDir, 'advanced-toolchain')
 const advancedSessionFixture = join(advancedScenarioDir, 'session.jsonl')
 const advancedStreamExpected = join(advancedScenarioDir, 'stream-json.expected.jsonl')
 const advancedConfigPath = fileURLToPath(new URL('../advanced.cordis.snapshot.yml', import.meta.url))
-const e2bScenarioDir = join(snapshotsDir, 'e2b-overlay')
-const e2bConfigPath = fileURLToPath(new URL('../e2b.cordis.snapshot.yml', import.meta.url))
 const ptyScenarioDir = join(snapshotsDir, 'pty-tools')
 const ptySessionFixture = join(ptyScenarioDir, 'session.jsonl')
 const ptyStreamExpected = join(ptyScenarioDir, 'stream-json.expected.jsonl')
@@ -610,60 +608,6 @@ describe('headless stream-json snapshots', () => {
     expect(normalized).toBe(await readFile(advancedStreamExpected, 'utf8'))
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('pins the E2B overlay provider-neutral tool surface', async () => {
-    const prompt = await scenarioPrompt(e2bScenarioDir, 'e2b-overlay')
-    const streamExpected = join(e2bScenarioDir, 'stream-json.expected.jsonl')
-    let runCwd = ''
-    const result = await runLoaderSmoke({
-      label: 'E2B overlay headless stream-json snapshot',
-      tempDirPrefix: 'headless-snapshot-e2b-overlay-',
-      binScript,
-      configPath: e2bConfigPath,
-      binArgs: ['--config', e2bConfigPath, '--output-format', 'stream-json', prompt],
-      tsconfigPath,
-      env: {
-        DSH_SNAPSHOT: 'replay',
-        DSH_SNAPSHOT_FILE: join(e2bScenarioDir, 'session.jsonl'),
-        DSH_SNAPSHOT_OVERRIDE: join(e2bScenarioDir, 'replay.override.json'),
-        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
-      },
-      prepare: (cwd) => { runCwd = cwd },
-      inspect: async (cwd) => {
-        const logs = await persistedLogs(cwd)
-        expect(logs).toHaveLength(1)
-        const headers = parseJsonl(logs[0]?.content ?? '').filter(record => record.type === 'request/header')
-        expect(headers).toHaveLength(1)
-        const data = headers[0]?.data as JsonObject | undefined
-        const header = data?.header as JsonObject | undefined
-        if (!Array.isArray(header?.tools)) throw new Error('E2B overlay snapshot request has no tool schemas')
-        const toolNames = header.tools.map((tool, index) => {
-          if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) {
-            throw new Error(`E2B overlay snapshot tool schema ${index} is not an object`)
-          }
-          const name = (tool as JsonObject).name
-          if (typeof name !== 'string') throw new Error(`E2B overlay snapshot tool schema ${index} has no name`)
-          return name
-        })
-        expect(toolNames.filter(name => name === 'lsp' || name === 'run_code' || name.startsWith('terminal_')).sort())
-          .toEqual([
-            'lsp',
-            'run_code',
-            'terminal_close',
-            'terminal_list',
-            'terminal_open',
-            'terminal_read',
-            'terminal_send',
-            'terminal_signal',
-          ])
-      },
-    })
-
-    expect(result.stderr).toBe('')
-    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
-    if (refreshing) await writeFile(streamExpected, normalized)
-    expect(normalized).toBe(await readFile(streamExpected, 'utf8'))
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
-
   it('replays persisted goal tools through the one-shot app', async () => {
     const prompt = await scenarioPrompt(goalScenarioDir, 'goal-tools')
     const streamExpected = join(goalScenarioDir, 'stream-json.expected.jsonl')
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/input.json b/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
deleted file mode 100644
index 00fd27ce2e..0000000000
--- a/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "steps": [
-    {
-      "op": "prompt",
-      "text": "Report the assembled E2B overlay tool surface."
-    }
-  ]
-}
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json b/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
deleted file mode 100644
index d1a71ce58c..0000000000
--- a/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
+++ /dev/null
@@ -1,12 +0,0 @@
-[
-  {
-    "kind": "chunks",
-    "chunks": [
-      { "type": "block-start", "index": 0, "blockType": "text" },
-      { "type": "text-delta", "index": 0, "text": "E2B_SURFACE_OK" },
-      { "type": "block-end", "index": 0, "block": { "type": "text", "text": "E2B_SURFACE_OK" } },
-      { "type": "usage", "usage": { "inputTokens": 8, "outputTokens": 3 } },
-      { "type": "finish", "reason": { "kind": "stop" } }
-    ]
-  }
-]
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
deleted file mode 100644
index 2fb74415cb..0000000000
--- a/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
+++ /dev/null
@@ -1,14 +0,0 @@
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Report the assembled E2B overlay tool surface."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":2,"time":0,"data":{"title":"Report the assembled E2B overlay","messageSeqs":[1],"source":{"kind":"fallback"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"E2B_SURFACE_OK"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"E2B_SURFACE_OK"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":8,"outputTokens":3}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"E2B_SURFACE_OK"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"{{sessionId}}"},"usage":{"inputTokens":8,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":11,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":12,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
-{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"E2B_SURFACE_OK","reason":{"kind":"completed"},"usage":{"inputTokens":8,"outputTokens":3}}
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 2b6a8efb69..6b1dc7506b 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: cb733ba00d21070773ff9b381e4a72d9d3b9a8df
-README.zh.md: 29f8e58a0cdc59098cf8d74120cb360d11cfbcb3
+README.md: 3c85b2790d3414af73625e65732df58ff9fec566
+README.zh.md: a759539fc054dd68e75f3c7660ccc3b762985af5
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index cb733ba00d..3c85b2790d 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -6,7 +6,7 @@ An experimental provider-composition POC that places one filesystem/process exec
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
+| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create one sandbox, prepare its working/runtime directories, expose the shared SDK handle, and delete it on timeout or disposal |
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index 29f8e58a0c..a759539fc0 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -6,7 +6,7 @@
 
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
-| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
+| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建一个沙箱，准备其工作目录与运行时目录，公开共享 SDK 句柄，并在超时或资源释放时将其删除 |
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 7d6b503ef4..c338fb0263 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 6881556dc18497956966aff74adc085d8e8620d3
-README.zh.md: aea13f341f903e6c47b7484f477bf54cebf101c6
+README.md: 6045b313a91edafc25361eba3f3c4dacf56b4eb0
+README.zh.md: dc157d9b5167488530c7d63b59aed793ab6aa4c7
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 6881556dc1..6045b313a9 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -12,8 +12,6 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
   config:
     cwd: /home/user/workspace
     timeoutMs: 300000
-    onTimeout: pause
-    onDispose: kill
 
 - id: subprocess-e2b
   name: '@deepseek-ai/dsh-subprocess-e2b'
@@ -22,17 +20,13 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
   name: '@deepseek-ai/dsh-fs-e2b'
 ```
 
-`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes. `onTimeout` is `pause` by default and accepts `pause | kill`; it applies only when this service creates a sandbox. Pause-on-timeout enables E2B auto-resume so the shared SDK handle wakes on its next operation. `onDispose` defaults to `kill` and accepts `kill | pause | leave`.
-
-Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` and `onTimeout` are creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
+`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes and controls the sandbox lifetime; expiry deletes the sandbox.
 
 ## Lifecycle and ownership
 
-Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+Construction starts one sandbox creation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` is accepted when disposal requests `kill`, or when this service created a sandbox with `onTimeout: kill`; otherwise, a not-found error from a requested `pause` rejects teardown because retention was not proved. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
-
-`pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
+Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure also deletes the newly created sandbox; if that rollback fails, disposal retries it before releasing ownership. Provider plugins must load after this owner and dispose before it.
 
 ## Model Experience
 
@@ -45,6 +39,6 @@ No direct invalidation; this package does not contribute request tokens.
 ## Known Limitations and Deferred Work
 
 - **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
-- **Retained sandboxes do not restore host handles** — reconnect preserves remote files and adapter artifacts, but cannot reconstruct subprocess handles, stream cursors, or mutation locks; managed subprocesses terminate when their service disposes.
-- **No deployment platform is configured** — templates, volumes, snapshots, network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
-- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access also retains the template's policy.
+- **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
+- **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
+- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index aea13f341f..dc157d9b51 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -12,8 +12,6 @@
   config:
     cwd: /home/user/workspace
     timeoutMs: 300000
-    onTimeout: pause
-    onDispose: kill
 
 - id: subprocess-e2b
   name: '@deepseek-ai/dsh-subprocess-e2b'
@@ -22,17 +20,13 @@
   name: '@deepseek-ai/dsh-fs-e2b'
 ```
 
-`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟。`onTimeout` 默认为 `pause`，接受 `pause | kill`；它只在本服务创建沙箱时生效。超时时 pause 会启用 E2B 自动恢复，使共享 SDK 句柄在下一次操作时唤醒。`onDispose` 默认为 `kill`，接受 `kill | pause | leave`。
-
-设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 和 `onTimeout` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
+`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟并控制沙箱生命周期；超时会删除沙箱。
 
 ## 生命周期与所有权
 
-构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+构造阶段会启动一次沙箱创建。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 仅在资源释放请求 `kill`，或本服务创建了配置为 `onTimeout: kill` 的沙箱时才可接受；否则，`pause` 请求返回的未找到错误会导致 teardown 拒绝，因为无法证明保留成功。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
-
-`pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时也会删除新建沙箱；如果该回滚失败，资源释放会在解除所有权前重试。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 ## 模型体验
 
@@ -45,6 +39,6 @@
 ## 已知限制与延后工作
 
 - **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
-- **保留的沙箱不会恢复宿主句柄**：重新连接会保留远程文件和适配器产物，但无法重建进程管理句柄、流游标或变更锁；进程管理服务 dispose 时会终止受管子进程。
-- **没有配置部署平台**：模板、卷、快照、网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
-- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用模板的策略。
+- **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
+- **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。
diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index 7ecc5fabed..82fda6b303 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/package.json
@@ -27,7 +27,6 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
@@ -36,7 +35,6 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-loader-smoke": "workspace:^",
     "cordis": "^4.0.0-rc.7"
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 3285d82395..d6797b9147 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -9,30 +9,15 @@ import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import { FileType, Sandbox, SandboxNotFoundError } from 'e2b'
-import type { Branded } from '@deepseek-ai/dsh-brand'
 
 export {
   CommandExitError,
   FileNotFoundError,
   FileType,
   Sandbox,
-  SandboxError,
   SandboxNotFoundError,
-  TimeoutError,
 } from 'e2b'
-export type { CommandHandle, CommandResult, EntryInfo, ProcessInfo, PtyOutput } from 'e2b'
-
-/** Opaque E2B sandbox identity used for reconnecting a later harness process. */
-export type E2BSandboxId = Branded<'E2BSandboxId'>
-
-/**
- * Brand an SDK sandbox id after E2B has created or resolved it.
- * @param value - E2B's opaque sandbox id.
- * @returns the same string with the harness brand.
- */
-export function E2BSandboxId(value: string): E2BSandboxId {
-  return value as E2BSandboxId
-}
+export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
 
 /**
  * Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
@@ -54,44 +39,25 @@ export function e2bControlEnvs(
   return { ...overrides, HOME: `/.dsh-e2b-control-${randomUUID()}` }
 }
 
-/** Action taken on the owned sandbox when the Cordis service is disposed. */
-export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
-
-/** Action E2B takes when a newly created sandbox reaches its lifetime. */
-export type E2BTimeoutMode = 'kill' | 'pause'
-
 /** Configuration for the shared E2B sandbox owner. */
 export interface Config {
   /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
   apiKey?: string
-  /** Existing sandbox to reconnect instead of creating a new one. */
-  sandboxId?: string
-  /** Template name or id for a newly created sandbox. */
-  template?: string
   /** Shared remote working directory, created before adapters receive the sandbox. */
   cwd?: string
-  /** E2B sandbox lifetime in milliseconds. */
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
   timeoutMs?: number
-  /** E2B action when a newly created sandbox reaches `timeoutMs`. */
-  onTimeout?: E2BTimeoutMode
-  /** Disposal policy; `pause` and `leave` retain remote state for reconnect. */
-  onDispose?: E2BDisposeMode
 }
 
 interface ResolvedConfig {
   apiKey: string
   cwd: string
   timeoutMs: number
-  onTimeout: E2BTimeoutMode
-  onDispose: E2BDisposeMode
-  sandboxId?: string
-  template?: string
 }
 
 interface SchemaResolvedConfig extends Config {
   cwd: string
   timeoutMs: number
-  onDispose: E2BDisposeMode
 }
 
 declare module 'cordis' {
@@ -101,31 +67,24 @@ declare module 'cordis' {
 }
 
 /**
- * Owns one lazily consumable E2B SDK handle and its final kill/pause/leave
- * decision. The connection begins at plugin construction; adapters await
+ * Creates one lazily consumable E2B SDK handle and deletes the sandbox at
+ * timeout or disposal. Creation begins at plugin construction; adapters await
  * {@link getSandbox} before their first operation.
  */
 export class E2BSandboxService extends Service {
   static Config: z<Config> = z.object({
     apiKey: z.string(),
-    sandboxId: z.string(),
-    template: z.string(),
     cwd: z.string().default('/home/user/workspace'),
     timeoutMs: z.number().default(300_000),
-    onTimeout: z.union(['kill', 'pause'] as const),
-    onDispose: z.union(['kill', 'pause', 'leave'] as const).default('kill'),
   })
 
   /** Validated remote working directory shared by provider adapters. */
   readonly cwd: string
   /** Remote directory reserved for adapter-owned process and terminal state. */
   readonly runtimeRoot: string
-  /** Sandbox id once E2B has created or resolved the remote runtime. */
-  readonly sandboxId: Promise<E2BSandboxId>
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
-  private readonly created: boolean
   private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
@@ -138,79 +97,50 @@ export class E2BSandboxService extends Service {
       apiKey: apiKey ?? '',
       cwd: resolved.cwd,
       timeoutMs: resolved.timeoutMs,
-      onTimeout: config.onTimeout ?? 'pause',
-      onDispose: resolved.onDispose,
-      ...(config.sandboxId !== undefined ? { sandboxId: config.sandboxId } : {}),
-      ...(config.template !== undefined ? { template: config.template } : {}),
     }
-    this.validate(config)
+    this.validate()
     this.cwd = this.config.cwd
     this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
-    this.created = this.config.sandboxId === undefined
     this.ready = this.open()
     // A deployment may load the owner before any adapter uses it. Keep a
     // failed eager connection observed; getSandbox() still returns the error.
     void this.ready.catch(() => {})
-    this.sandboxId = this.ready.then(sandbox => E2BSandboxId(sandbox.sandboxId))
-    void this.sandboxId.catch(() => {})
 
     ctx.effect(() => async () => {
       this.disposed = true
-      let sandbox: Sandbox
-      try {
-        sandbox = await this.ready
-      } catch {
-        const failedSetupSandbox = this.failedSetupSandbox
-        if (failedSetupSandbox === undefined) return
-        sandbox = failedSetupSandbox
+      let sandbox = this.failedSetupSandbox
+      if (sandbox === undefined) {
         try {
-          await sandbox.kill()
-          this.failedSetupSandbox = undefined
-        } catch (error: unknown) {
-          if (!(error instanceof SandboxNotFoundError)) throw error
-          this.failedSetupSandbox = undefined
+          sandbox = await this.ready
+        } catch {
+          sandbox = this.failedSetupSandbox
         }
-        return
       }
+      if (sandbox === undefined) return
       try {
-        switch (this.config.onDispose) {
-          case 'kill':
-            await sandbox.kill()
-            return
-          case 'pause': {
-            await sandbox.pause()
-            return
-          }
-          case 'leave':
-            return
-        }
+        await sandbox.kill()
       } catch (error: unknown) {
         if (!(error instanceof SandboxNotFoundError)) throw error
-        // Missing proves the requested disposition only when this owner asked
-        // for deletion or created the sandbox with timeout deletion. A
-        // reconnected sandbox's creation lifecycle is unknown.
-        if (this.config.onDispose === 'kill') return
-        if (this.created && this.config.onTimeout === 'kill') return
-        throw error
       }
+      this.failedSetupSandbox = undefined
     }, 'e2b sandbox teardown')
   }
 
   /**
    * Return the shared live SDK handle.
-   * @returns the created or reconnected sandbox after the configured cwd exists.
-   * @throws when E2B rejects creation/reconnection or the service is disposing.
+   * @returns the created sandbox after the configured cwd exists.
+   * @throws when E2B rejects creation or the service is disposing.
    */
   async getSandbox(): Promise<Sandbox> {
     if (this.disposed) throw new Error('E2B sandbox service is disposing')
     const sandbox = await this.ready
     // Disposal can race the awaited sandbox readiness despite the synchronous precheck.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- Awaiting readiness yields to disposal.
     if (this.disposed) throw new Error('E2B sandbox service is disposing')
     return sandbox
   }
 
-  private validate(input: Config): void {
+  private validate(): void {
     if (this.config.apiKey.length === 0) {
       throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
     }
@@ -220,35 +150,15 @@ export class E2BSandboxService extends Service {
     if (!Number.isFinite(this.config.timeoutMs) || this.config.timeoutMs <= 0) {
       throw new Error('dsh-e2b: timeoutMs must be a positive finite number')
     }
-    if (this.config.sandboxId !== undefined && this.config.sandboxId.length === 0) {
-      throw new Error('dsh-e2b: sandboxId must be non-empty when provided')
-    }
-    if (this.config.sandboxId !== undefined && this.config.template !== undefined) {
-      throw new Error('dsh-e2b: template applies only when creating; omit it when sandboxId reconnects')
-    }
-    if (this.config.sandboxId !== undefined && input.onTimeout !== undefined) {
-      throw new Error('dsh-e2b: onTimeout applies only when creating; omit it when sandboxId reconnects')
-    }
   }
 
   private async open(): Promise<Sandbox> {
-    const connection = {
+    const sandbox = await Sandbox.create({
       apiKey: this.config.apiKey,
       timeoutMs: this.config.timeoutMs,
-    }
-    const sandbox = this.config.sandboxId === undefined
-      ? this.config.template === undefined
-        ? await Sandbox.create({
-          ...connection,
-          secure: true,
-          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
-        })
-        : await Sandbox.create(this.config.template, {
-          ...connection,
-          secure: true,
-          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
-        })
-      : await Sandbox.connect(this.config.sandboxId, connection)
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
     try {
       await sandbox.files.makeDir(this.cwd)
       await sandbox.files.makeDir(this.runtimeRoot)
@@ -262,14 +172,12 @@ export class E2BSandboxService extends Service {
       )
       return sandbox
     } catch (error: unknown) {
-      if (this.created) {
-        try {
-          await sandbox.kill()
-        } catch (_cleanupFailure) {
-          // Preserve the setup failure as the public error while retaining the
-          // created handle for the service disposer to retry this rollback.
-          this.failedSetupSandbox = sandbox
-        }
+      try {
+        await sandbox.kill()
+      } catch (_cleanupFailure) {
+        // Preserve the setup failure as the public error while retaining the
+        // created handle for the service disposer to retry this rollback.
+        this.failedSetupSandbox = sandbox
       }
       throw error
     }
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 6600f1046d..2eca4f1f63 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -5,8 +5,7 @@ import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import E2BSandboxService, {
-  e2bControlEnvs,
+import {
   FileNotFoundError,
   Sandbox,
   SandboxNotFoundError,
@@ -113,26 +112,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
 
-      await sandbox.commands.run([
-        'rm -rf -- /home/user/.dsh-e2b /home/user/dsh-e2b-runtime-target',
-        'mkdir -p -- /home/user/dsh-e2b-runtime-target',
-        'chmod 755 -- /home/user/dsh-e2b-runtime-target',
-        'ln -s -- /home/user/dsh-e2b-runtime-target /home/user/.dsh-e2b',
-      ].join('\n'), { envs: e2bControlEnvs({ NPM_TOKEN: '' }) })
-      const linkedCtx = new Context()
-      const linkedFiber = await linkedCtx.plugin(E2BSandboxService, {
-        apiKey,
-        sandboxId: sandbox.sandboxId,
-        cwd: '/home/user',
-        onDispose: 'leave',
-      })
-      try {
-        await expect(linkedCtx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
-        const target = await sandbox.files.getInfo('/home/user/dsh-e2b-runtime-target')
-        expect(target.mode & 0o777).toBe(0o755)
-      } finally {
-        await linkedFiber.dispose()
-      }
     } finally {
       await sandbox.kill().catch(() => false)
     }
@@ -160,23 +139,10 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(stderr).toBe('')
     const output = JSON.parse(stdout) as Record<string, unknown>
     expect(output).toMatchObject({
-      bashRead: 'written-by-fs-versioned\n',
-      fsVersionGuard: true,
+      bashRead: 'versioned-by-fs\n',
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
       splitUtf8Output: '你好',
-      outputDrain: {
-        outcome: { exitCode: 0, signal: null },
-        text: 'leader-done\n',
-        exited: true,
-        clean: true,
-      },
-      publicationRollback: true,
-      spill: {
-        liveBytes: 6,
-        outcome: { exitCode: null, signal: 'SIGTERM' },
-        read: { text: '6789', nextOffset: 10, lossy: true },
-      },
       hover: {
         kind: 'hover',
         hover: { contents: '**remote hover** 你好 café' },
@@ -185,24 +151,14 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         kind: 'locations',
         locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
       },
-      lspDocumentBound: true,
       terminal: {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
         signal: { delivered: true },
         interrupted: { sessionStatus: { kind: 'running' } },
-        interruptIdentitySafe: true,
         treeCleanup: true,
       },
-      hostileOutput: { error: { kind: 'output-limit' } },
-      nativeOutput: { error: { kind: 'output-limit' } },
-      descriptorOutput: { error: { kind: 'output-limit' } },
-      inheritedOutput: { error: { kind: 'output-limit' } },
       descendantPipe: { value: true, logs: [] },
       descendantCleanup: true,
-      timedOut: { error: { kind: 'timeout' } },
-      aborted: { error: { kind: 'abort', message: 'live abort' } },
-      oversizedBoot: { error: { kind: 'worker-exit' } },
-      oversizedReply: { error: { kind: 'worker-exit' } },
       lingeringCodeRunners: 0,
     })
     const terminalMotd = (output.terminal as { motd: string }).motd
@@ -217,10 +173,11 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     )
     expect(output.code).toEqual({
       value: { doubled: 42, typed: true },
-      logs: ['remote-log 你好 42', 'post-mutation'],
+      logs: ['remote-log 你好 42'],
     })
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
+    await expect(Sandbox.list({ apiKey }).nextItems()).resolves.toEqual([])
   }, 195_000)
 })
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index af55a2419a..e3a6c09039 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -4,7 +4,6 @@ import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   e2bControlEnvs,
-  E2BSandboxId,
   FileType,
   SandboxNotFoundError,
   quoteE2BShellArg,
@@ -14,21 +13,16 @@ import InvariantService from '@deepseek-ai/dsh-invariants'
 
 const sdk = vi.hoisted(() => ({
   create: vi.fn(),
-  connect: vi.fn(),
 }))
 
 vi.mock('e2b', async (importOriginal) => {
   const actual = await importOriginal<typeof import('e2b')>()
   // The mock replaces only the SDK's static factory surface and is never constructed.
-  // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+  // oxlint-disable-next-line typescript/no-extraneous-class -- The SDK contract is a class with a static factory.
   class FakeSandbox {
     static create(...args: unknown[]): unknown {
       return sdk.create(...args)
     }
-
-    static connect(...args: unknown[]): unknown {
-      return sdk.connect(...args)
-    }
   }
   return { ...actual, Sandbox: FakeSandbox }
 })
@@ -39,7 +33,6 @@ interface SandboxFixture {
   getInfo: ReturnType<typeof vi.fn>
   run: Mock<RunCommand>
   kill: ReturnType<typeof vi.fn>
-  pause: ReturnType<typeof vi.fn>
 }
 
 type RunCommand = (
@@ -52,20 +45,17 @@ function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
   const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
   const run = vi.fn<RunCommand>().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
   const kill = vi.fn().mockResolvedValue(undefined)
-  const pause = vi.fn().mockResolvedValue(true)
   const sandbox = {
     sandboxId: id,
     files: { makeDir, getInfo },
     commands: { run },
     kill,
-    pause,
   } as unknown as SandboxType
-  return { sandbox, makeDir, getInfo, run, kill, pause }
+  return { sandbox, makeDir, getInfo, run, kill }
 }
 
 beforeEach(() => {
   sdk.create.mockReset()
-  sdk.connect.mockReset()
   vi.unstubAllEnvs()
 })
 
@@ -87,14 +77,13 @@ describe('E2BSandboxService', () => {
 
     const service = ctx.e2b
     await expect(service.getSandbox()).resolves.toBe(fixture.sandbox)
-    await expect(service.sandboxId).resolves.toBe(E2BSandboxId('sandbox-1'))
     expect(service.cwd).toBe('/home/user/workspace')
     expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
     expect(sdk.create).toHaveBeenCalledWith({
       apiKey: 'test-key',
       timeoutMs: 300_000,
       secure: true,
-      lifecycle: { onTimeout: 'pause', autoResume: true },
+      lifecycle: { onTimeout: 'kill' },
     })
     expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
     expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
@@ -127,55 +116,26 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
-  it('creates from a template, honors timeout and pause policies, and reads the key from the environment', async () => {
+  it('reads the key from the environment and honors the configured cwd and lifetime', async () => {
     vi.stubEnv('E2B_API_KEY', 'environment-key')
-    const fixture = fakeSandbox('template-sandbox')
+    const fixture = fakeSandbox('configured-sandbox')
     sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
     const fiber = await ctx.plugin(E2BSandboxService, {
-      template: 'agent-template',
       cwd: '/workspace/project',
       timeoutMs: 60_000,
-      onTimeout: 'kill',
-      onDispose: 'pause',
     })
     await ctx.e2b.getSandbox()
 
-    expect(sdk.create).toHaveBeenCalledWith('agent-template', {
+    expect(sdk.create).toHaveBeenCalledWith({
       apiKey: 'environment-key',
       timeoutMs: 60_000,
       secure: true,
-      lifecycle: { onTimeout: 'kill', autoResume: false },
+      lifecycle: { onTimeout: 'kill' },
     })
+    expect(ctx.e2b.cwd).toBe('/workspace/project')
     await fiber.dispose()
-    expect(fixture.pause).toHaveBeenCalledOnce()
-    expect(fixture.kill).not.toHaveBeenCalled()
-  })
-
-  it('accepts an already-paused result during configured pause disposal', async () => {
-    const fixture = fakeSandbox()
-    fixture.pause.mockResolvedValue(false)
-    sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', onDispose: 'pause' })
-    await ctx.e2b.getSandbox()
-    await fiber.dispose()
-    expect(fixture.pause).toHaveBeenCalledOnce()
-  })
-
-  it('treats a timeout-killed sandbox as already quiescent during disposal', async () => {
-    const fixture = fakeSandbox()
-    fixture.pause.mockRejectedValue(new SandboxNotFoundError('sandbox expired'))
-    sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, {
-      apiKey: 'test-key',
-      onTimeout: 'kill',
-      onDispose: 'pause',
-    })
-    await ctx.e2b.getSandbox()
-    await expect(fiber.dispose()).resolves.toBeUndefined()
-    expect(fixture.pause).toHaveBeenCalledOnce()
+    expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
   it('accepts a missing sandbox when disposal itself requests deletion', async () => {
@@ -208,49 +168,6 @@ describe('E2BSandboxService', () => {
     expect(errors).toContain(failure)
   })
 
-  it.each([
-    ['a created pause-on-timeout sandbox', false],
-    ['a reconnected sandbox with unknown creation policy', true],
-  ] as const)('reports missing during pause disposal for %s', async (_label, reconnect) => {
-    const fixture = fakeSandbox()
-    const failure = new SandboxNotFoundError('sandbox unexpectedly missing')
-    fixture.pause.mockRejectedValue(failure)
-    if (reconnect) sdk.connect.mockResolvedValue(fixture.sandbox)
-    else sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const errors: unknown[] = []
-    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
-    const fiber = await ctx.plugin(E2BSandboxService, {
-      apiKey: 'test-key',
-      onDispose: 'pause',
-      ...(reconnect ? { sandboxId: 'existing' } : {}),
-    })
-    await ctx.e2b.getSandbox()
-
-    await expect(fiber.dispose()).resolves.toBeUndefined()
-    expect(fixture.pause).toHaveBeenCalledOnce()
-    expect(errors).toContain(failure)
-  })
-
-  it('reconnects without applying creation lifecycle options and can leave state running', async () => {
-    const fixture = fakeSandbox('existing')
-    sdk.connect.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, {
-      apiKey: 'test-key',
-      sandboxId: 'existing',
-      timeoutMs: 90_000,
-      onDispose: 'leave',
-    })
-    await ctx.e2b.getSandbox()
-
-    expect(sdk.connect).toHaveBeenCalledWith('existing', { apiKey: 'test-key', timeoutMs: 90_000 })
-    expect(sdk.create).not.toHaveBeenCalled()
-    await fiber.dispose()
-    expect(fixture.kill).not.toHaveBeenCalled()
-    expect(fixture.pause).not.toHaveBeenCalled()
-  })
-
   it('kills a newly created sandbox when remote directory setup fails', async () => {
     const fixture = fakeSandbox()
     fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
@@ -259,7 +176,6 @@ describe('E2BSandboxService', () => {
     const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
 
     await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
-    await expect(ctx.e2b.sandboxId).rejects.toThrow('setup failed')
     expect(fixture.kill).toHaveBeenCalledOnce()
     await fiber.dispose()
   })
@@ -294,44 +210,30 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).toHaveBeenCalledTimes(2)
   })
 
-  it('does not kill a reconnected sandbox when setup fails', async () => {
-    const fixture = fakeSandbox()
-    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
-    sdk.connect.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
-    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
-    expect(fixture.kill).not.toHaveBeenCalled()
-  })
-
   it.each([
     ['symbolic link', { type: FileType.DIR, symlinkTarget: '/tmp/redirected' }],
     ['regular file', { type: FileType.FILE }],
   ])('rejects a reserved runtime root that is a %s', async (_label, info) => {
     const fixture = fakeSandbox()
     fixture.getInfo.mockResolvedValueOnce(info)
-    sdk.connect.mockResolvedValue(fixture.sandbox)
+    sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
-    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
 
     await expect(ctx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
     expect(fixture.run).not.toHaveBeenCalled()
-    expect(fixture.kill).not.toHaveBeenCalled()
+    expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
   it.each([
     [{ apiKey: '' }, /configure apiKey/],
     [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
     [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
-    [{ apiKey: 'x', sandboxId: '' }, /sandboxId must be non-empty/],
-    [{ apiKey: 'x', sandboxId: 'one', template: 'two' }, /template applies only/],
-    [{ apiKey: 'x', sandboxId: 'one', onTimeout: 'kill' }, /onTimeout applies only/],
   ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
     vi.stubEnv('E2B_API_KEY', '')
     const ctx = new Context()
     await expect(ctx.plugin(E2BSandboxService, config)).rejects.toThrow(message)
     expect(sdk.create).not.toHaveBeenCalled()
-    expect(sdk.connect).not.toHaveBeenCalled()
   })
 
   it('requires a key when both config and the environment omit it', async () => {
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 3f756bf2f9..a8edcb34ab 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 6827e16e9c45532590ee1aa986c18a353d175fdc
-README.zh.md: 21b067829ea95c4581d7e89f3d225f9c90e630ef
+README.md: cd170bcbe2831b0856b51791a2045382d93c1148
+README.zh.md: f97790cf1d4ef90f042df8ed564723e186327f00
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 6827e16e9c..cd170bcbe2 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -24,8 +24,8 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
+- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, or external process populates it; local files are neither uploaded nor reflected back.
 - **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
 - **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
-- **Custom templates must support the used Linux/GNU and E2B filesystem features** — `realpath -mz`, `base64 -w0`, `chmod`, same-filesystem rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
+- **The POC targets E2B's default Linux image** — it relies on GNU `realpath`/`base64`/`chmod`, same-filesystem rename, streaming reads, and metadata extended attributes; custom templates are outside this POC.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 21b067829e..f97790cf1d 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -24,8 +24,8 @@
 
 ## 已知限制与延后工作
 
-- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
+- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
 - **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
 - **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
-- **自定义模板必须支持所用的 Linux/GNU 与 E2B 文件系统功能**：必须支持 `realpath -mz`、`base64 -w0`、`chmod`、同一文件系统内的 rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
+- **该 POC 面向 E2B 默认 Linux 镜像**：它依赖 GNU `realpath`／`base64`／`chmod`、同一文件系统内的 rename、流式读取和元数据扩展属性；自定义模板不在该 POC 范围内。
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 91f9a278fd..618472a6b8 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -275,7 +275,6 @@ async function setup(remote = new FakeRemote()): Promise<{ ctx: Context; fs: E2B
   const runtime = {
     cwd: '/workspace',
     runtimeRoot: '/workspace/.dsh-e2b',
-    disposeMode: 'kill',
     getSandbox: async () => remote.sandbox,
   } as unknown as E2BSandboxService
   ctx.provide('e2b', runtime)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 9ac46f1bcb..96fb24e21b 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 9d563c91c149d28718159af1b1f8ddbd6652dc44
-README.zh.md: be189f41818c66aeff2bed7b1851b82ca08f08f4
+README.md: 4e47566d55cf9400459993185f03482761c92096
+README.zh.md: 21ef231af700f72c2c5ec1fc651297ebdd17d49b
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 9d563c91c1..4e47566d55 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -9,12 +9,12 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the template's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`. A custom template must retain compatible commands and E2B PTY support.
+The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
 
 ## Model Experience
 
@@ -28,10 +28,9 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
-- **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
-- **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
+- **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep.
 - **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
-- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. In a reconnected sandbox, a same-UID untrusted process could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive or a hardened template to close the gap.
+- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. A same-UID untrusted process already in the sandbox could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive to close the gap.
 - **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
-- **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
+- **Linux utility and E2B transport semantics are assumed** — there is no Windows, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index be189f4181..21ef231af7 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -9,12 +9,12 @@
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变模板 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
 
 ## 模型体验
 
@@ -28,10 +28,9 @@
 
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
-- **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
-- **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
+- **私有状态随沙箱生命周期存在**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。
 - **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
-- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。在重新连接的沙箱中，一个同 UID 的不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语或经加固的模板才能弥合该缺口。
+- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。一个已在沙箱内运行的同 UID 不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语才能弥合该缺口。
 - **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
-- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 990ab20a62..63cafcbfe0 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -106,7 +106,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
-    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
+    if (this.disposing) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
@@ -115,7 +115,7 @@ export class E2BSubprocessService extends SubprocessService {
       throw new Error('subprocess-e2b: graceMs must be a positive finite number')
     }
     if (spec.signal?.aborted === true) {
-      throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
+      throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
     }
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
     const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir)
@@ -132,7 +132,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
-    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
+    if (this.disposing) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
@@ -158,7 +158,8 @@ export class E2BSubprocessService extends SubprocessService {
         (cleanup) => { this.failedTerminalSetupCleanups.add(cleanup) },
       )
       this.terminals.add(terminal)
-      if (this.isDisposing()) {
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
+      if (this.disposing) {
         await terminal.terminate()
         this.terminals.delete(terminal)
         throw new Error('subprocess-e2b: service disposed during terminal setup')
@@ -176,10 +177,6 @@ export class E2BSubprocessService extends SubprocessService {
       setup.resolve()
     }
   }
-
-  private isDisposing(): boolean {
-    return this.disposing
-  }
 }
 
 export default E2BSubprocessService
diff --git a/packages/e2b/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
index 8afcd138dc..ba1dc1a716 100644
--- a/packages/e2b/subprocess-e2b/src/output.ts
+++ b/packages/e2b/subprocess-e2b/src/output.ts
@@ -115,9 +115,6 @@ export class E2BOutputReader implements SubprocessOutputReader {
 
   /** @inheritdoc */
   readFrom(fromByte: number): SubprocessOutputRead {
-    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
-      throw new Error('subprocess output offset must be a non-negative safe integer')
-    }
     const retained = Buffer.concat(this.chunks, this.retainedBytes)
     const firstRetained = this.totalBytes - this.retainedBytes
     const lossy = fromByte < firstRetained
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 5e383a50e2..fe964a7395 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -149,10 +149,6 @@ function commandOpts(
   return { envs: e2bControlEnvs(envs), ...(signal === undefined ? {} : { signal }) }
 }
 
-function isAborted(signal: AbortSignal | undefined): boolean {
-  return signal?.aborted === true
-}
-
 function waitTick(signal?: AbortSignal): Promise<boolean> {
   if (signal?.aborted === true) return Promise.resolve(false)
   return new Promise<boolean>((resolve) => {
@@ -173,7 +169,7 @@ const WAIT_ABORTED = Symbol('wait aborted')
 function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
   if (signal === undefined) return promise
   if (signal.aborted) return Promise.resolve(WAIT_ABORTED)
-  return new Promise<T | typeof WAIT_ABORTED>((resolve, reject) => {
+  return new Promise<T | typeof WAIT_ABORTED>((resolve) => {
     const onAbort = (): void => { cleanup(); resolve(WAIT_ABORTED) }
     const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
     signal.addEventListener('abort', onAbort, { once: true })
@@ -181,10 +177,7 @@ function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined)
       onAbort()
       return
     }
-    void promise.then(
-      (value) => { cleanup(); resolve(value) },
-      (error: unknown) => { cleanup(); reject(asError(error)) },
-    )
+    void promise.then((value) => { cleanup(); resolve(value) })
   })
 }
 
@@ -206,12 +199,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly paths: RemotePaths
   private controlEnvs: Record<string, string> = {}
   private remotePid = -1
-  private commandHandle: CommandHandle | undefined
   private outputTransportError: Error | undefined
   private outputDrainExpired = false
   private stateDirectoryCreated = false
-  private preparing = true
-  private terminationStarted = false
   private quiescenceProven = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
@@ -265,7 +255,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   /** @inheritdoc */
   terminate(): void {
     if (this.quiescenceProven || this.terminationAttempt !== undefined) return
-    this.terminationStarted = true
     this.terminationController.abort(new Error('subprocess-e2b: command terminated'))
     this.stdout?.destroy()
     this.stderr?.destroy()
@@ -285,7 +274,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
     if (this.quiescenceProven) return true
     let handle: CommandHandle | undefined
-    if (this.terminationStarted) {
+    if (this.terminationController.signal.aborted) {
       const observed = await waitWithSignal(this.commandState.promise, signal)
       if (observed === WAIT_ABORTED) return false
       handle = observed
@@ -295,22 +284,23 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       if (this.remotePid <= 0) {
         const attempt = this.terminationAttempt
-        if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
+        if (attempt !== undefined && await waitWithSignal(attempt.catch(() => undefined), signal) === WAIT_ABORTED) {
+          return false
+        }
         this.throwTerminationFailure()
         // Successful pre-publication termination records quiescence; its only other outcome is the failure above.
         return true
       }
     } else {
-      try {
-        const observed = await waitWithSignal(this.readyState.promise, signal)
-        if (observed === WAIT_ABORTED) return false
-        handle = observed
-      } catch {
-        handle = this.commandHandle
-        if (handle === undefined) {
-          this.markQuiescent()
-          return true
-        }
+      const observed = await waitWithSignal(
+        this.readyState.promise.catch(() => this.commandState.promise),
+        signal,
+      )
+      if (observed === WAIT_ABORTED) return false
+      handle = observed
+      if (handle === undefined) {
+        this.markQuiescent()
+        return true
       }
     }
     this.throwTerminationFailure()
@@ -318,7 +308,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     try {
       sandbox = await this.runtime.getSandbox()
     } catch (error: unknown) {
-      if (isAborted(signal)) return false
+      if (signal?.aborted === true) return false
       if (error instanceof SandboxNotFoundError) {
         this.markQuiescent()
         return true
@@ -331,7 +321,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!await waitTick(signal)) return false
     }
     this.throwTerminationFailure()
-    if (isAborted(signal)) return false
+    if (signal?.aborted === true) return false
     this.markQuiescent()
     return true
   }
@@ -345,10 +335,11 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async run(): Promise<SubprocessOutcome> {
     let sandbox: Sandbox | undefined
+    let preparing = true
     try {
       sandbox = await this.runtime.getSandbox()
       await this.prepareState(sandbox)
-      this.preparing = false
+      preparing = false
       const handle = await sandbox.commands.run(
         commandText(this.spec, this.paths),
         {
@@ -361,7 +352,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
         },
       )
-      this.commandHandle = handle
       const completion = handle.wait()
       void completion.catch(() => {})
       if (!isValidProcessId(handle.pid)) {
@@ -369,7 +359,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         try {
           await handle.kill()
           this.markQuiescent()
-          this.commandHandle = undefined
         } catch (cleanupError: unknown) {
           this.terminationFailure = asError(cleanupError)
           this.commandState.resolve(handle)
@@ -404,9 +393,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
-      const canceledPreparation = this.preparing
-        && this.terminationStarted
-        && this.terminationController.signal.aborted
+      const canceledPreparation = preparing && this.terminationController.signal.aborted
       let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
@@ -423,7 +410,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (canceledPreparation && failure === error) return { exitCode: null, signal: 'SIGTERM' }
       throw failure
     } finally {
-      this.preparing = false
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
       this.stderr?.end()
@@ -583,7 +569,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async rollbackPublishedFailure(error: unknown): Promise<unknown> {
-    if (this.remotePid <= 0 || this.commandHandle === undefined || this.quiescenceProven) return error
+    if (this.remotePid <= 0 || this.quiescenceProven) return error
     this.terminate()
     try {
       await this.waitForExit()
@@ -626,7 +612,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
       await handle.kill()
       this.markQuiescent()
-      this.commandHandle = undefined
       return
     }
     const sandbox = await this.runtime.getSandbox()
@@ -730,7 +715,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       const size = (reader as E2BOutputReader).size
       if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
         removals.push(sandbox.files.remove(path).catch((_adapterPrivateSpillRemovalFailure: unknown) => {
-          // The command outcome is authoritative; a retained sandbox tolerates private residue.
+          // The command outcome is authoritative; owner teardown bounds private residue.
         }))
       }
     }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 8d003dfc35..3876191759 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -41,7 +41,6 @@ const TERMINAL_RUNNER_SOURCE = [
   '  exit 125',
   'fi',
   'printf \'%s\' "$dsh_output_marker"',
-  "printf 'ready\\n' > \"$dsh_state/ready\"",
   'exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"',
   '',
 ].join('\n')
@@ -51,7 +50,6 @@ interface TerminalPaths {
   environment: string
   argv: string
   outputMarker: string
-  ready: string
 }
 
 function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
@@ -165,26 +163,6 @@ async function terminalSessionId(
   return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
 }
 
-async function waitUntilReady(
-  sandbox: Sandbox,
-  paths: TerminalPaths,
-  completion: Promise<CommandResult>,
-  signal?: AbortSignal,
-): Promise<void> {
-  const settled = completion.then(() => true, () => true)
-  for (;;) {
-    signal?.throwIfAborted()
-    try {
-      if ((await sandbox.files.read(paths.ready, signalOpts(signal))).trim() === 'ready') return
-    } catch (error: unknown) {
-      if (!(error instanceof FileNotFoundError)) throw error
-    }
-    if (await Promise.race([settled, delay(POLL_MS).then(() => false)])) {
-      throw new Error('subprocess-e2b: terminal exited before publishing readiness')
-    }
-  }
-}
-
 async function sessionProcessGroups(
   sandbox: Sandbox,
   sessionId: number,
@@ -241,8 +219,13 @@ async function awaitSessionEmpty(
   const deadline = Date.now() + graceMs
   for (;;) {
     const groups = await sessionProcessGroups(sandbox, sessionId, envs)
-    if (groups.length === 0 || Date.now() >= deadline) return groups
-    if (kill) await signalGroups(sandbox, groups, 'KILL', envs)
+    if (groups.length === 0) return groups
+    if (kill) {
+      await signalGroups(sandbox, groups, 'KILL', envs)
+      if (Date.now() >= deadline) return await sessionProcessGroups(sandbox, sessionId, envs)
+    } else if (Date.now() >= deadline) {
+      return groups
+    }
     await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
   }
 }
@@ -277,7 +260,6 @@ async function rollbackUnpublishedTerminal(
         groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs)
       }
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'KILL', envs)
         await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
       }
     } catch (error: unknown) {
@@ -285,25 +267,13 @@ async function rollbackUnpublishedTerminal(
     }
   }
   // Completion can settle while any awaited provider cleanup above is running.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- Provider cleanup yields to completion.
   if (!topLevelExited) {
-    if (validPid) {
-      try {
-        await sandbox.pty.kill(handle.pid)
-      } catch (error: unknown) {
-        if (error instanceof SandboxNotFoundError) return
-        attemptFailures.push(asError(error))
-      }
-    }
-    // The awaited PTY fallback can settle completion before the SDK fallback.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!topLevelExited) {
-      try {
-        await handle.kill()
-      } catch (error: unknown) {
-        if (error instanceof SandboxNotFoundError) return
-        attemptFailures.push(asError(error))
-      }
+    try {
+      await handle.kill()
+    } catch (error: unknown) {
+      if (error instanceof SandboxNotFoundError) return
+      attemptFailures.push(asError(error))
     }
     await Promise.race([completion.catch(() => undefined), delay(graceMs)])
   }
@@ -321,7 +291,7 @@ async function rollbackUnpublishedTerminal(
     }
   }
   // The bounded completion race above updates this callback-owned state.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- The callback mutates this after a race.
   if (!topLevelExited) {
     proofFailures.push(new Error(`subprocess-e2b: terminal setup rollback failed; surviving pid: ${handle.pid}`))
   }
@@ -347,7 +317,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   private cleanup: Promise<void> | undefined
   private readonly operationController = new AbortController()
   private readonly operations = new Set<Promise<unknown>>()
-  private terminating = false
   private terminationSignal: NodeJS.Signals | null = null
 
   constructor(
@@ -400,7 +369,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   /** @inheritdoc */
   terminate(): Promise<void> {
     if (this.cleanup !== undefined) return this.cleanup
-    this.terminating = true
     this.operationController.abort(new Error('subprocess-e2b: terminal is terminating'))
     const cleanup = this.closeAfterOperations()
     this.cleanup = cleanup
@@ -434,7 +402,9 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private trackOperation<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> {
-    if (this.terminating) return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    if (this.operationController.signal.aborted) {
+      return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    }
     const pending = operation(this.operationController.signal)
     this.operations.add(pending)
     void pending.then(
@@ -445,7 +415,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async closeAfterOperations(): Promise<void> {
-    if (this.operations.size > 0) await Promise.allSettled(this.operations)
+    await Promise.allSettled(this.operations)
     await this.closeOnce()
   }
 
@@ -481,7 +451,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
       this.terminationSignal = 'SIGKILL'
       if (!this.topLevelExited) {
         try {
-          await this.sandbox.pty.kill(this.pid)
+          await this.handle.kill()
         } catch (error: unknown) {
           if (error instanceof SandboxNotFoundError) return
           throw error
@@ -504,7 +474,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     try {
       await this.sandbox.files.remove(this.stateDir)
     } catch (_adapterPrivateStateRemovalFailure) {
-      // The terminal is quiescent; a retained sandbox tolerates private residue.
+      // The terminal is quiescent; owner teardown bounds private residue.
     }
   }
 }
@@ -531,7 +501,6 @@ export async function spawnE2BTerminal(
     environment: posix.join(stateDir, 'environment'),
     argv: posix.join(stateDir, 'argv'),
     outputMarker: posix.join(stateDir, 'output-marker'),
-    ready: posix.join(stateDir, 'ready'),
   }
   const outputMarker = Buffer.from(`dsh-e2b-bootstrap:${randomUUID()}`)
   const output = new PassThrough()
@@ -577,7 +546,6 @@ export async function spawnE2BTerminal(
     }
     const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
     await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
-    await waitUntilReady(sandbox, paths, completion, spec.signal)
     await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
     const sessionId = await terminalSessionId(sandbox, handle.pid, controlEnvs, spec.signal)
     return new E2BTerminalHandle(
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 83e86892d4..f7adf8183c 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -316,7 +316,6 @@ function runtime(fake: FakeSandbox, getSandbox: () => Promise<Sandbox> = async (
   return {
     cwd: '/workspace',
     runtimeRoot: '/workspace/.dsh-e2b',
-    disposeMode: 'kill',
     getSandbox,
   } as unknown as E2BSandboxService
 }
@@ -372,8 +371,6 @@ describe('E2BOutputReader', () => {
     const overCap = new E2BOutputReader(2, 3, '/too-small')
     overCap.push(Buffer.from('abcd'))
     expect(overCap.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
-    expect(() => overCap.readFrom(-1)).toThrow(/non-negative safe integer/)
-    expect(() => overCap.readFrom(1.5)).toThrow(/non-negative safe integer/)
   })
 })
 
@@ -1673,7 +1670,6 @@ describe('E2BSubprocessService', () => {
     expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/)
     expect(() => ctx.subprocess.spawn(spec({ graceMs: 0 }))).toThrow(/positive finite/)
     expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/)
-    expect(() => ctx.subprocess.spawn(spec({ signal: { aborted: true, reason: undefined } as AbortSignal }))).toThrow(/aborted$/)
   })
 
   it('registers the package-owned empty invariant installer', async () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index a4f4008a56..08d49bb87b 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -90,9 +90,6 @@ class FakeTerminalSandbox {
   readonly writes = new Map<string, string>()
   createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
   ambient = 'KEEP=visible\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
-  ready: string | Error = 'ready\n'
-  readyMisses = 0
-  readyReads = 0
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
@@ -108,12 +105,9 @@ class FakeTerminalSandbox {
   sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
-  ptyKillError: unknown
   removeError: unknown
   clearOnTerm = true
   clearOnKill = true
-  settleOnPtyKill = true
-  ptyKills = 0
   resolvedExecutable = '/usr/bin/node\n'
   requestedOutput = 'requested-shell$ '
   emitOutputMarker = true
@@ -144,15 +138,6 @@ class FakeTerminalSandbox {
         if (this.writeError !== undefined) throw this.writeError
         return files.map(() => ({}))
       },
-      read: async (): Promise<string> => {
-        this.readyReads += 1
-        if (this.readyMisses > 0) {
-          this.readyMisses -= 1
-          throw new FileNotFoundError('not ready')
-        }
-        if (this.ready instanceof Error) throw this.ready
-        return this.ready
-      },
       remove: async (path: string): Promise<void> => {
         this.removed.push(path)
         if (this.removeError !== undefined) throw this.removeError
@@ -237,12 +222,6 @@ class FakeTerminalSandbox {
           }
         }
       },
-      kill: async (pid: number): Promise<boolean> => {
-        this.ptyKills += 1
-        if (this.ptyKillError !== undefined) throw this.ptyKillError
-        if (this.settleOnPtyKill) this.handle.fail(137)
-        return pid === this.handle.pid
-      },
     },
   } as unknown as Sandbox
 }
@@ -251,7 +230,6 @@ function runtime(fake: FakeTerminalSandbox): E2BSandboxService {
   return {
     cwd: '/workspace',
     runtimeRoot: '/workspace/.dsh-e2b',
-    disposeMode: 'kill',
     getSandbox: async () => fake.sandbox,
   } as unknown as E2BSandboxService
 }
@@ -284,7 +262,6 @@ function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
 describe('E2B terminal allocation', () => {
   it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
-    fake.readyMisses = 1
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
     let output = ''
     terminal.output.on('data', (chunk) => { output += String(chunk) })
@@ -417,12 +394,6 @@ describe('E2B terminal allocation', () => {
     expect(failedInput.commands).toContain('kill -TERM -- -123')
     expect(failedInput.groups).toEqual([])
 
-    const exited = new FakeTerminalSandbox()
-    exited.ready = new FileNotFoundError('not ready')
-    queueMicrotask(() => { exited.handle.succeed(0) })
-    await expect(spawnE2BTerminal(runtime(exited), spec(), '/runtime/exited'))
-      .rejects.toThrow('exited before publishing readiness')
-
     const invalidSession = new FakeTerminalSandbox()
     invalidSession.sessionId = 'not-a-session\n'
     invalidSession.clearOnTerm = false
@@ -431,7 +402,7 @@ describe('E2B terminal allocation', () => {
     expect(invalidSession.commands).toContain('kill -TERM -- -123')
     expect(invalidSession.commands).toContain('kill -KILL -- -123')
     expect(invalidSession.groups).toEqual([])
-    expect(invalidSession.ptyKills).toBe(1)
+    expect(invalidSession.handle.sdkKills).toBe(1)
     const lateData = invalidSession.createOptions?.onData
     if (lateData === undefined) throw new Error('missing captured terminal callback')
     expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
@@ -442,12 +413,12 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(termFailed), spec(), '/runtime/term-failed'))
       .rejects.toThrow('bootstrap failed')
     expect(termFailed.commands).toContain('kill -KILL -- -123')
-    expect(termFailed.ptyKills).toBe(1)
+    expect(termFailed.handle.sdkKills).toBe(1)
 
     const uninspectable = new FakeTerminalSandbox()
     uninspectable.sendError = new Error('bootstrap failed')
     uninspectable.sessionGroupsFailure = 'session enumeration failed'
-    uninspectable.ptyKillError = new Error('PTY kill failed')
+    uninspectable.handle.sdkKillError = new Error('PTY kill failed')
     let uninspectableFailure: unknown
     try {
       await spawnE2BTerminal(runtime(uninspectable), spec(), '/runtime/uninspectable')
@@ -455,7 +426,6 @@ describe('E2B terminal allocation', () => {
       uninspectableFailure = error
     }
     expect(uninspectableFailure).toBeInstanceOf(AggregateError)
-    expect(uninspectable.ptyKills).toBe(1)
     expect(uninspectable.handle.sdkKills).toBe(1)
 
     const survivingGroups = new FakeTerminalSandbox()
@@ -468,7 +438,6 @@ describe('E2B terminal allocation', () => {
     const survivingPid = new FakeTerminalSandbox()
     survivingPid.sendError = new Error('bootstrap failed')
     survivingPid.groups = []
-    survivingPid.settleOnPtyKill = false
     survivingPid.handle.settleOnSdkKill = false
     await expect(spawnE2BTerminal(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
       .rejects.toThrow('bootstrap failed')
@@ -491,12 +460,12 @@ describe('E2B terminal allocation', () => {
     const expiredDuringRollback = new FakeTerminalSandbox()
     expiredDuringRollback.sendError = new Error('bootstrap failed before timeout')
     expiredDuringRollback.groups = []
-    expiredDuringRollback.settleOnPtyKill = false
-    expiredDuringRollback.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringRollback.handle.settleOnSdkKill = false
+    expiredDuringRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
     await expect(spawnE2BTerminal(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
       .rejects.toThrow('bootstrap failed before timeout')
-    expect(expiredDuringRollback.ptyKills).toBe(1)
+    expect(expiredDuringRollback.handle.sdkKills).toBe(1)
 
     const expiredBeforeSdkRollback = new FakeTerminalSandbox()
     expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
@@ -505,15 +474,6 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
       .rejects.toThrow('wait failed after timeout')
 
-    const expiredDuringSdkFallback = new FakeTerminalSandbox()
-    expiredDuringSdkFallback.sendError = new Error('bootstrap failed before SDK fallback')
-    expiredDuringSdkFallback.groups = []
-    expiredDuringSdkFallback.settleOnPtyKill = false
-    expiredDuringSdkFallback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
-    expiredDuringSdkFallback.handle.settleOnSdkKill = false
-    await expect(spawnE2BTerminal(runtime(expiredDuringSdkFallback), spec(), '/runtime/expired-sdk-fallback'))
-      .rejects.toThrow('bootstrap failed before SDK fallback')
-
     const missingDuringDisconnect = new FakeTerminalSandbox()
     missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
     missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
@@ -537,10 +497,6 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(createFailed), spec(), '/runtime/create'))
       .rejects.toThrow('create failed')
 
-    const readFailed = new FakeTerminalSandbox()
-    readFailed.ready = new Error('ready transport failed')
-    await expect(spawnE2BTerminal(runtime(readFailed), spec(), '/runtime/read'))
-      .rejects.toThrow('ready transport failed')
   })
 
   it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
@@ -560,7 +516,6 @@ describe('E2B terminal allocation', () => {
       '/runtime/cancel-output-boundary',
     )
     await vi.waitFor(() => { expect(cancelled.inputs).toHaveLength(1) })
-    await vi.waitFor(() => { expect(cancelled.readyReads).toBeGreaterThan(0) })
     await new Promise(resolve => setTimeout(resolve, 0))
     controller.abort(new Error('cancel output boundary'))
     await expect(cancelling).rejects.toThrow('cancel output boundary')
@@ -661,23 +616,23 @@ describe('E2B terminal lifecycle', () => {
   it('treats sandbox disappearance during PTY kill as quiescent', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    fake.settleOnPtyKill = false
-    fake.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    fake.handle.settleOnSdkKill = false
+    fake.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
 
     await terminal.terminate()
-    expect(fake.ptyKills).toBe(1)
+    expect(fake.handle.sdkKills).toBe(1)
   })
 
   it('propagates a non-missing PTY kill failure', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    fake.settleOnPtyKill = false
-    fake.ptyKillError = new Error('PTY kill transport failed')
+    fake.handle.settleOnSdkKill = false
+    fake.handle.sdkKillError = new Error('PTY kill transport failed')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
 
     await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
-    fake.ptyKillError = undefined
+    fake.handle.sdkKillError = undefined
     fake.handle.succeed(0)
     await terminal.done
     await terminal.terminate()
@@ -712,11 +667,11 @@ describe('E2B terminal lifecycle', () => {
     await terminal.terminate()
   })
 
-  it('escalates surviving process groups', async () => {
+  it('sends KILL before checking an expired force-cleanup deadline', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [123, 456]
     fake.clearOnTerm = false
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/escalate')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
     const terminating = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
     await terminating
@@ -771,11 +726,11 @@ describe('E2B terminal lifecycle', () => {
   it('keeps a late command rejection authoritative after PTY kill', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    fake.settleOnPtyKill = false
+    fake.handle.settleOnSdkKill = false
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
     terminal.output.on('error', () => {})
     const cleanup = terminal.terminate()
-    while (fake.ptyKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
+    while (fake.handle.sdkKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
     await Promise.resolve()
     fake.handle.crash(new Error('late command transport failed'))
     await expect(terminal.done).rejects.toThrow('late command transport failed')
@@ -791,7 +746,7 @@ describe('E2B terminal lifecycle', () => {
 
     const livePid = new FakeTerminalSandbox()
     livePid.groups = []
-    livePid.settleOnPtyKill = false
+    livePid.handle.settleOnSdkKill = false
     const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
     await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
     livePid.handle.succeed(0)
@@ -879,13 +834,13 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
   })
 
-  it('aborts and rolls back terminal setup that cannot publish readiness during disposal', async () => {
+  it('aborts and rolls back terminal setup that cannot publish its output boundary during disposal', async () => {
     const fake = new FakeTerminalSandbox()
-    fake.ready = new FileNotFoundError('not ready')
+    fake.emitOutputMarker = false
     const { ctx, fiber } = await service(fake)
     const spawning = ctx.subprocess.spawnTerminal(spec())
     const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
-    await vi.waitFor(() => { expect(fake.readyReads).toBeGreaterThan(0) })
+    await vi.waitFor(() => { expect(fake.inputs).toHaveLength(1) })
 
     await fiber.dispose()
     await rejected
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 87648e01e1..f682bc6847 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -716,6 +716,9 @@ importers:
 
   packages/bash/bash:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3091,9 +3094,6 @@ importers:
 
   packages/credentials/credentials:
     devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants

From b1b2d63785a8b3a5341d2420401f7576ce12ff50 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 06:02:10 +0800
Subject: [PATCH 132/262] refactor(e2b): drop speculative cleanup retry state

---
 AGENTS.md                                     |  6 ++--
 docs/cordis-catalog/services.md               |  2 +-
 packages/e2b/e2b/README.i18n.yaml             |  4 +--
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/src/index.ts                 | 23 +++++--------
 packages/e2b/e2b/tests/e2b.spec.ts            | 20 ++---------
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +--
 packages/e2b/subprocess-e2b/README.md         |  2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  2 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  6 ----
 packages/e2b/subprocess-e2b/src/process.ts    | 33 +++++--------------
 packages/e2b/subprocess-e2b/src/terminal.ts   |  9 +++--
 .../subprocess-e2b/tests/subprocess.spec.ts   | 27 ++++++++-------
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 17 ----------
 15 files changed, 48 insertions(+), 111 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1d2a6d977c..87f545ee86 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,12 +14,12 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
   typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
-  e2b/         E2B POC: sandbox owner + FS/subprocess adapters
+  e2b/         E2B POC: sandbox + FS/subprocess adapters
   bash/        bash executor seam + local impl + model-facing bash tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
-  fs/          filesystem seam + local impl + policy gate + read/write/edit tools
-  lsp/         language-server seam + local stdio provider + model-facing lsp tool
+  fs/          filesystem seam/backends/policy/tools
+  lsp/         language-server seam/local backend/tool
   skill/       skill provider registry + local impl + catalog/loader tool
   web/         web seam + search/fetch providers + model-facing web tools
   compact/     compaction seam + basic backend
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index db66ca5799..8af0e6ca30 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:76`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index c338fb0263..3587067d31 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 6045b313a91edafc25361eba3f3c4dacf56b4eb0
-README.zh.md: dc157d9b5167488530c7d63b59aed793ab6aa4c7
+README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
+README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 6045b313a9..7ade7c3d65 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -26,7 +26,7 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
 
 Construction starts one sandbox creation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command.
 
-Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure also deletes the newly created sandbox; if that rollback fails, disposal retries it before releasing ownership. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure makes one deletion attempt; the configured E2B timeout bounds a second failure. Provider plugins must load after this owner and dispose before it.
 
 ## Model Experience
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index dc157d9b51..b683f33d22 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -26,7 +26,7 @@
 
 构造阶段会启动一次沙箱创建。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时也会删除新建沙箱；如果该回滚失败，资源释放会在解除所有权前重试。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时会尝试删除一次；若该尝试也失败，则由已配置的 E2B 超时约束沙箱的存活时间。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 ## 模型体验
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index d6797b9147..906941d421 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -85,7 +85,6 @@ export class E2BSandboxService extends Service {
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
-  private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
   constructor(ctx: Context, config: Config) {
@@ -108,21 +107,18 @@ export class E2BSandboxService extends Service {
 
     ctx.effect(() => async () => {
       this.disposed = true
-      let sandbox = this.failedSetupSandbox
-      if (sandbox === undefined) {
-        try {
-          sandbox = await this.ready
-        } catch {
-          sandbox = this.failedSetupSandbox
-        }
+      let sandbox: Sandbox
+      try {
+        sandbox = await this.ready
+      } catch (_sandboxSetupFailure) {
+        // open() either acquired no sandbox or already made the POC's one rollback attempt.
+        return
       }
-      if (sandbox === undefined) return
       try {
         await sandbox.kill()
       } catch (error: unknown) {
         if (!(error instanceof SandboxNotFoundError)) throw error
       }
-      this.failedSetupSandbox = undefined
     }, 'e2b sandbox teardown')
   }
 
@@ -174,10 +170,9 @@ export class E2BSandboxService extends Service {
     } catch (error: unknown) {
       try {
         await sandbox.kill()
-      } catch (_cleanupFailure) {
-        // Preserve the setup failure as the public error while retaining the
-        // created handle for the service disposer to retry this rollback.
-        this.failedSetupSandbox = sandbox
+      } catch (_sandboxSetupRollbackFailure) {
+        // TODO(e2b-setup-rollback): Add retry state only if a real double failure
+        // outlives E2B's configured sandbox timeout.
       }
       throw error
     }
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index e3a6c09039..b108bc68b0 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -180,7 +180,7 @@ describe('E2BSandboxService', () => {
     await fiber.dispose()
   })
 
-  it('preserves the setup failure even when cleanup also fails', async () => {
+  it('preserves the setup failure after its one rollback attempt fails', async () => {
     const fixture = fakeSandbox()
     fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
     fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
@@ -191,23 +191,7 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).toHaveBeenCalledOnce()
 
     await fiber.dispose()
-    expect(fixture.kill).toHaveBeenCalledTimes(2)
-  })
-
-  it.each([
-    ['retries a still-failing rollback', new Error('retry failed')],
-    ['accepts a setup sandbox that expired before retry', new SandboxNotFoundError('sandbox expired')],
-  ])('%s during disposal', async (_label, retryError) => {
-    const fixture = fakeSandbox()
-    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
-    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed')).mockRejectedValueOnce(retryError)
-    sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
-
-    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
-    await fiber.dispose()
-    expect(fixture.kill).toHaveBeenCalledTimes(2)
+    expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
   it.each([
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 96fb24e21b..381ada5198 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 4e47566d55cf9400459993185f03482761c92096
-README.zh.md: 21ef231af700f72c2c5ec1fc651297ebdd17d49b
+README.md: 3ddfe5bc47309ba56d3f8af7720fcbe71ec8a302
+README.zh.md: c4db7bf8bb8a0f4b2f147dd22868978be5d1fcf4
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 4e47566d55..3ddfe5bc47 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -11,7 +11,7 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 21ef231af7..c4db7bf8bb 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -11,7 +11,7 @@
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 63cafcbfe0..976880ab01 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -29,7 +29,6 @@ export class E2BSubprocessService extends SubprocessService {
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
   private readonly terminalSetups = new Map<Promise<void>, AbortController>()
-  private readonly failedTerminalSetupCleanups = new Set<() => Promise<void>>()
   private disposing = false
 
   /** @inheritdoc */
@@ -51,7 +50,6 @@ export class E2BSubprocessService extends SubprocessService {
       await Promise.all([...this.terminalSetups.keys()])
       const handles = [...this.live]
       const terminals = [...this.terminals]
-      const failedTerminalSetupCleanups = [...this.failedTerminalSetupCleanups]
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
@@ -63,9 +61,6 @@ export class E2BSubprocessService extends SubprocessService {
       for (const terminal of terminals) {
         pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
-      for (const cleanup of failedTerminalSetupCleanups) {
-        pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
-      }
       const outcomes = await Promise.allSettled(pending)
       for (const outcome of outcomes) {
         if (outcome.status === 'rejected') throw outcome.reason
@@ -155,7 +150,6 @@ export class E2BSubprocessService extends SubprocessService {
         this.ctx.e2b,
         { ...spec, signal: setupSignal },
         stateDir,
-        (cleanup) => { this.failedTerminalSetupCleanups.add(cleanup) },
       )
       this.terminals.add(terminal)
       // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index fe964a7395..c0aceda334 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -636,35 +636,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
-    let groupFailure: unknown
     try {
-      if (!await this.signalGroup(sandbox, processGroupId, 'KILL')) {
-        groupFailure = new Error('process-group KILL did not report delivery')
-      }
-    } catch (error: unknown) {
-      groupFailure = error
+      await this.signalGroup(sandbox, processGroupId, 'KILL')
+    } catch (_processGroupKillFailure) {
+      // SDK kill and the final liveness probe remain independent cleanup paths.
     }
-    let handleFailure: unknown
     try {
-      if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
-    } catch (error: unknown) {
-      handleFailure = error
+      await handle.kill()
+    } catch (_sdkKillFailure) {
+      // The final liveness probe, not either transport's self-report, proves cleanup.
     }
-    let proofFailure: unknown
-    try {
-      if (await this.waitForGroupExit(sandbox, processGroupId)) return
-      proofFailure = new Error(`remote process group ${processGroupId} remained live after force termination`)
-    } catch (error: unknown) {
-      proofFailure = error
-    }
-    throw new AggregateError(
-      [
-        ...(groupFailure === undefined ? [] : [groupFailure]),
-        ...(handleFailure === undefined ? [] : [handleFailure]),
-        proofFailure,
-      ],
-      'subprocess-e2b: force termination failed through both process-group and SDK transports',
-    )
+    if (await this.waitForGroupExit(sandbox, processGroupId)) return
+    throw new Error(`subprocess-e2b: remote process group ${processGroupId} remained live after force termination`)
   }
 
   private async waitForGroupExit(sandbox: Sandbox, processGroupId: number): Promise<boolean> {
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 3876191759..3108a4a60a 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -485,14 +485,12 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
  * @param runtime - Shared E2B sandbox owner.
  * @param spec - Fully specified terminal-process request.
  * @param stateDir - Private remote directory for one startup transaction.
- * @param retainFailedCleanup - Optional owner for retrying a cleanup transaction that could not prove quiescence.
  * @returns The live subprocess terminal handle.
  */
 export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
-  retainFailedCleanup?: (cleanup: () => Promise<void>) => void,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
@@ -562,7 +560,7 @@ export async function spawnE2BTerminal(
     output.destroy()
     let terminalQuiescent = handle === undefined
     let stateRemoved = !stateDirectoryCreated
-    const retryCleanup = async (): Promise<void> => {
+    const cleanup = async (): Promise<void> => {
       const failures: Error[] = []
       if (!terminalQuiescent && handle !== undefined) {
         try {
@@ -588,9 +586,10 @@ export async function spawnE2BTerminal(
       }
     }
     try {
-      await retryCleanup()
+      await cleanup()
     } catch (cleanupError: unknown) {
-      retainFailedCleanup?.(retryCleanup)
+      // TODO(e2b-terminal-setup-rollback): Retain retry state only if a real
+      // double failure must be recovered before sandbox disposal or timeout.
       throw new AggregateError([asError(error), asError(cleanupError)], asError(error).message)
     }
     throw error
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index f7adf8183c..471716ef1a 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -808,7 +808,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     expect(fake.alive).toBe(true)
 
     fake.delaysKill = false
@@ -884,7 +884,7 @@ describe('E2BSubprocessHandle', () => {
 
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     fake.alive = false
     handle.terminate()
     await expect(handle.waitForExit()).resolves.toBe(true)
@@ -941,7 +941,7 @@ describe('E2BSubprocessHandle', () => {
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
 
     fake.handle.killError = undefined
     handle.terminate()
@@ -960,7 +960,7 @@ describe('E2BSubprocessHandle', () => {
     )
     await vi.waitFor(() => { expect(absentGroup.startOptions).toBeDefined() })
     absentHandle.terminate()
-    await expect(absentHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(absentHandle.waitForExit()).rejects.toThrow('remained live after force termination')
     absentGroup.handle.killError = undefined
     absentHandle.terminate()
     await expect(absentHandle.waitForExit()).resolves.toBe(true)
@@ -978,7 +978,7 @@ describe('E2BSubprocessHandle', () => {
     )
     await vi.waitFor(() => { expect(optimisticSdk.startOptions).toBeDefined() })
     optimisticHandle.terminate()
-    await expect(optimisticHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(optimisticHandle.waitForExit()).rejects.toThrow('remained live after force termination')
     optimisticHandle.terminate()
     await expect(optimisticHandle.waitForExit()).resolves.toBe(true)
     optimisticSdk.releaseProcessGroupRead()
@@ -1322,7 +1322,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(absent.waitForExit()).resolves.toBe(true)
   })
 
-  it('preserves publication and rollback failures when cleanup cannot be verified', async () => {
+  it('preserves publication failure and reports cleanup that cannot be verified', async () => {
     const fake = new FakeSandbox()
     fake.processGroupId = 'not-a-pid\n'
     fake.signalError = new Error('rollback signal failed')
@@ -1341,11 +1341,10 @@ describe('E2BSubprocessHandle', () => {
     const failures = Array.from(failure.errors as Iterable<unknown>)
     expect(failures).toHaveLength(2)
     expect(failures[0]).toBeInstanceOf(Error)
-    expect(failures[1]).toBeInstanceOf(AggregateError)
-    if (!(failures[0] instanceof Error) || !(failures[1] instanceof AggregateError)) throw new Error('expected nested errors')
+    expect(failures[1]).toBeInstanceOf(Error)
+    if (!(failures[0] instanceof Error) || !(failures[1] instanceof Error)) throw new Error('expected nested errors')
     expect(failures[0].message).toContain('invalid process-group id')
-    expect(failures[1].message).toBe('subprocess-e2b: force termination failed through both process-group and SDK transports')
-    expect(Array.from(failures[1].errors as Iterable<unknown>)).toContainEqual(new Error('rollback signal failed'))
+    expect(failures[1].message).toContain('remained live after force termination')
     expect(fake.handle.kills).toBe(1)
     const bounded = new AbortController()
     const waiting = handle.waitForExit(bounded.signal)
@@ -1494,7 +1493,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
 
     handle.terminate()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     fake.handle.killError = undefined
     handle.terminate()
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
@@ -1507,7 +1506,7 @@ describe('E2BSubprocessHandle', () => {
     const raced = new E2BSubprocessHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
     await flush()
     raced.terminate()
-    await expect(raced.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(raced.waitForExit()).rejects.toThrow('remained live after force termination')
     missingGroup.handle.killError = undefined
     raced.terminate()
     await expect(raced.waitForExit()).resolves.toBe(true)
@@ -1522,7 +1521,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
 
     handle.terminate()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     expect(fake.alive).toBe(true)
 
     fake.sdkKillStops = true
@@ -1581,7 +1580,7 @@ describe('E2BSubprocessService', () => {
     await flush()
 
     await expect(fiber.dispose()).resolves.toBeUndefined()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
 
     fake.handle.killError = undefined
     handle.terminate()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 08d49bb87b..067910a10b 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -871,23 +871,6 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.createOptions).toBeUndefined()
   })
 
-  it('retains failed terminal setup cleanup for disposal retry', async () => {
-    const fake = new FakeTerminalSandbox()
-    fake.sendError = new Error('bootstrap failed')
-    fake.clearOnTerm = false
-    fake.clearOnKill = false
-    const { ctx, fiber } = await service(fake)
-
-    await expect(ctx.subprocess.spawnTerminal(spec({ graceMs: 1 }))).rejects.toThrow('bootstrap failed')
-    expect(fake.groups).toEqual([123])
-    expect(fake.handle.disconnects).toBe(0)
-
-    fake.clearOnKill = true
-    await fiber.dispose()
-    expect(fake.groups).toEqual([])
-    expect(fake.handle.disconnects).toBe(1)
-  })
-
   it('releases naturally settled terminals and validates terminal requests', async () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [

From 258bd4456b21bb037583d696b351a2fbb6ceb6e9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 06:02:22 +0800
Subject: [PATCH 133/262] test(e2b): poll sandbox list convergence

---
 packages/e2b/e2b/tests/composition.e2e.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 2eca4f1f63..bf53ba7bb9 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -178,6 +178,9 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
-    await expect(Sandbox.list({ apiKey }).nextItems()).resolves.toEqual([])
+    await expect.poll(async () => {
+      const sandboxes = await Sandbox.list({ apiKey }).nextItems()
+      return sandboxes.some(sandbox => sandbox.sandboxId === output.sandboxId)
+    }, { interval: 250, timeout: 5_000 }).toBe(false)
   }, 195_000)
 })

From 26b18ba189715c8a4ff40cb785c34daf83957e53 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:50:47 +0800
Subject: [PATCH 134/262] refactor(e2b): keep code runtime host-local

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  6 +--
 ...8-portable-execution-world-consumers.zh.md |  6 +--
 examples/headless-agent/e2b.cordis.yml        |  7 +--
 .../tests/fixtures/e2b/e2b/bin.ts             | 51 -------------------
 .../tests/fixtures/e2b/e2b/cordis.yml         |  9 ----
 packages/README.i18n.yaml                     |  4 +-
 packages/e2b/README.i18n.yaml                 |  4 +-
 packages/e2b/README.md                        |  2 +-
 packages/e2b/README.zh.md                     |  2 +-
 packages/e2b/e2b/README.i18n.yaml             |  4 +-
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/tests/composition.e2e.ts     | 11 +---
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  2 +-
 packages/e2b/subprocess-e2b/src/index.ts      | 14 ++---
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  4 +-
 19 files changed, 29 insertions(+), 111 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index c7ce82595d..fb8a3344c1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 57c3a8a8b211279593359b02def865644052f549
-2026-07-28-portable-execution-world-consumers.zh.md: 8231913c26f75361add7a28bc40f7723c9b18728
+2026-07-28-portable-execution-world-consumers.md: fcc30d553f07a28b44227f614f62c2027f8f3dd3
+2026-07-28-portable-execution-world-consumers.zh.md: 5e1e73aee7b96ffe1ae9862f72114a48152ad218
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 6f296bfa74..fcc30d553f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
 
 The filesystem and subprocess seams made file and ordinary process access replaceable, but PTY and LSP still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY and LSP packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
 
-A remote coding world is useful only when file operations, commands, terminals, language servers, and model-written programs share one sandbox identity. Moving the complete harness into that sandbox would also entangle provider experimentation with plugin loading, credentials, model transport, session durability, supervision, and deployment.
+A remote coding world is useful only when file operations, commands, terminals, and language servers share one sandbox identity. Moving the complete harness into that sandbox would also entangle provider experimentation with plugin loading, credentials, model transport, session durability, supervision, and deployment.
 
 Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
 
@@ -30,7 +30,7 @@ Generic consumers use that execution world:
 
 The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates one sandbox and deletes it on timeout or disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole SDK handle from the owner and never create private sandboxes.
 
-E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, subprocess Code Runtime processes, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, Code Runtime program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, the worker-backed Code Runtime and its program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
 
 The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
 
@@ -38,7 +38,7 @@ Sandbox state is deliberately ephemeral: timeout and disposal delete the remote
 
 ## Verification
 
-Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP queries, Code Runtime bindings and cleanup, host-workspace isolation, and final sandbox deletion.
+Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP queries, host-workspace isolation, and final sandbox deletion.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 471753573d..2ab0685a1d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
 
-只有文件操作、命令、终端、语言服务器和模型编写的程序共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
+只有文件操作、命令、终端和语言服务器共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
 普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建一个沙箱，并在超时或资源释放时将其删除；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的 SDK 句柄，绝不创建私有沙箱。
 
-E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取、子进程代码运行时进程，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、代码运行时程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
+E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、基于 worker 的代码运行时及其程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
 
 适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
 
@@ -41,7 +41,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 ## 验证
 
-聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 查询、代码运行时绑定与清理、宿主工作区隔离，以及最终沙箱删除。
+聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 查询、宿主工作区隔离，以及最终沙箱删除。
 
 ## 考虑过的替代方案
 
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 724f30240d..a65b0baf81 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,6 +1,6 @@
 # POC overlay: keep the advanced headless agent and model-facing tools, but
 # place its filesystem and process substrate in one short-lived E2B sandbox;
-# the generic Bash, PTY, LSP, and Code Runtime consumers compose above them.
+# the generic Bash, PTY, and LSP consumers compose above them.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
@@ -12,9 +12,6 @@
       - id: fs-local
         name: '@deepseek-ai/dsh-fs-local'
         disabled: true
-      - id: code-runtime
-        name: '@deepseek-ai/dsh-code-runtime-worker'
-        disabled: true
       - insert:
           - id: e2b
             name: '@deepseek-ai/dsh-e2b'
@@ -25,8 +22,6 @@
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
             name: '@deepseek-ai/dsh-fs-e2b'
-          - id: code-runtime-subprocess
-            name: '@deepseek-ai/dsh-code-runtime-subprocess'
           - id: sandbox-policy
             name: '@deepseek-ai/dsh-sandbox-policy'
             config:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 570a244e88..7348d1d181 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -3,7 +3,6 @@ import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-code-runtime-subprocess'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
 import type {} from '@deepseek-ai/dsh-lsp-local'
@@ -175,52 +174,6 @@ try {
   const terminalTreeCleanup = stubbornProbe.stdout === 'gone'
   if (!terminalTreeCleanup) throw new Error(`E2B PTY left process ${stubbornPid} alive after close`)
 
-  const code = await ctx.codeRuntime.run({
-    program: `
-      console.log('remote-log 你好', 42)
-      const doubled: number = await bridge.double({ value: 21 })
-      let typed = false
-      try {
-        await bridge.fail({ reason: 'expected' })
-      } catch (error) {
-        typed = error instanceof BridgeError && (error as { member: string }).member === 'fail'
-      }
-      return { doubled, typed }
-    `,
-    bindings: [{
-      global: 'bridge',
-      errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
-      functions: {
-        double: async (args) => {
-          const value = (args as { value: number }).value
-          return value * 2
-        },
-        fail: async () => { throw new Error('binding rejected') },
-      },
-    }],
-  })
-  const descendantPipe = await ctx.codeRuntime.run({
-    program: `
-      const childProcess = await import('node:child_process')
-      const child = childProcess.spawn(
-        process.execPath,
-        ['-e', 'setInterval(() => {}, 1000)', 'dsh-code-runtime-descendant'],
-        { stdio: ['ignore', 'inherit', 'inherit'] },
-      )
-      return child.pid > 0
-    `,
-    bindings: [],
-  })
-  const descendantProcesses = await sandbox.commands.list()
-  const descendantCleanup = !descendantProcesses.some(processInfo =>
-    JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-code-runtime-descendant'),
-  )
-  if (!descendantCleanup) throw new Error('E2B Code Runtime left a pipe-holding descendant alive')
-  const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
-  const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
-    JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
-  )
-
   process.stdout.write(`${JSON.stringify({
     sandboxId: (await ctx.e2b.getSandbox()).sandboxId,
     bashRead: bashRead.stdout.text,
@@ -237,10 +190,6 @@ try {
       treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
-    code,
-    descendantPipe,
-    descendantCleanup,
-    lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
   if (terminalId !== undefined) await ctx.pty.kill(owner, terminalId, 'fixture cleanup').catch(() => false)
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 043362aaa1..3a6deb7e49 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -52,12 +52,3 @@
           .ts: typescript
         shutdownTimeoutMs: 1000
         killGraceMs: 500
-
-- id: code-runtime-subprocess
-  name: '@deepseek-ai/dsh-code-runtime-subprocess'
-  config:
-    computeMs: 500
-    maxWallMs: 15000
-    maxOutputBytes: 4096
-    maxOldGenerationSizeMb: 128
-    killGraceMs: 500
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index f101375bc6..ce95627688 100644
--- 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: 1fd0c9c2385f3169791a28f3ef50bb42792760af
-README.zh.md: f9f7d5ae8839ea7033a349ac7a0083a97780a21c
+README.md: a9a121d0cb13cd5e2148da8d754967359be06bab
+README.zh.md: c6500ebb2abce14fabf68b79ec20f5c23cf5d5f7
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 6b1dc7506b..b93f48d8cd 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: 3c85b2790d3414af73625e65732df58ff9fec566
-README.zh.md: a759539fc054dd68e75f3c7660ccc3b762985af5
+README.md: adc002649e44faefd2f6bd84b7b45fb9fc6fa41d
+README.zh.md: d941de8da2cb831a69a165c86a825def68c2b319
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index 3c85b2790d..adc002649e 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -10,6 +10,6 @@ An experimental provider-composition POC that places one filesystem/process exec
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), [`dsh-lsp-local`](../lsp/lsp-local/README.md), and [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox. The worker-backed Code Runtime remains host-local and reaches that world only through the tools its programs call.
 
 This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index a759539fc0..d941de8da2 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -10,6 +10,6 @@
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md)、[`dsh-lsp-local`](../lsp/lsp-local/README.md) 及 [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。基于 worker 的代码运行时仍在宿主本地运行，只会通过其程序调用的工具触达该执行世界。
 
 该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 3587067d31..0256b3ccfe 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
-README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad
+README.md: 52f99178ce8c06e61c13ea9364769ac887db4410
+README.zh.md: 98ba7e79841f548ff6465fda4bc37170c17bc6e0
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 7ade7c3d65..52f99178ce 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -38,7 +38,7 @@ No direct invalidation; this package does not contribute request tokens.
 
 ## Known Limitations and Deferred Work
 
-- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **This is not a whole-harness runtime** — Cordis services, the worker-backed Code Runtime, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
 - **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
 - **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
 - **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index b683f33d22..98ba7e7984 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -38,7 +38,7 @@
 
 ## 已知限制与延后工作
 
-- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **这不是完整的 harness 运行时**：Cordis 服务、基于 worker 的代码运行时、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
 - **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
 - **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
 - **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index bf53ba7bb9..3f0b69668d 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -57,7 +57,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       const ptyFiber = await ctx.plugin(PtyService)
       const subprocessFiber = await ctx.plugin(E2BSubprocessService)
       const node = await ctx.subprocess.resolveExecutable('node')
-      const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
+      const relativeNodePath = posix.relative(ctx.e2b.cwd, posix.dirname(node)) || '.'
       await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
       await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const environmentProbe = ctx.subprocess.spawn({
@@ -117,7 +117,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     }
   }, 70_000)
 
-  it('runs FS, Bash, PTY, LSP, and Code Runtime in one sandbox and deletes it', async () => {
+  it('runs FS, Bash, PTY, and LSP in one sandbox and deletes it', async () => {
     const { stdout, stderr } = await runLoaderSmoke({
       label: 'E2B composition',
       tempDirPrefix: 'dsh-e2b-composition-',
@@ -157,9 +157,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         interrupted: { sessionStatus: { kind: 'running' } },
         treeCleanup: true,
       },
-      descendantPipe: { value: true, logs: [] },
-      descendantCleanup: true,
-      lingeringCodeRunners: 0,
     })
     const terminalMotd = (output.terminal as { motd: string }).motd
     expect(terminalMotd.length).toBeGreaterThan(0)
@@ -171,10 +168,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(['stdin_read', 'inferred_idle']).toContain(
       (output.terminal as { interrupted: { waitReason: string } }).interrupted.waitReason,
     )
-    expect(output.code).toEqual({
-      value: { doubled: 42, typed: true },
-      logs: ['remote-log 你好 42'],
-    })
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 381ada5198..0a18bf24a1 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 3ddfe5bc47309ba56d3f8af7720fcbe71ec8a302
-README.zh.md: c4db7bf8bb8a0f4b2f147dd22868978be5d1fcf4
+README.md: 3bb9802c3afa41f3949fceeb73e76ea5cebce744
+README.zh.md: 520f0ea1cde18ed523ba80015d3d4700730aba7a
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 3ddfe5bc47..3bb9802c3a 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, LSP, and subprocess Code Runtime consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
 
 ## Behavior
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index c4db7bf8bb..520f0ea1cd 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY、LSP 以及使用 subprocess 的 Code Runtime 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
 
 ## 行为
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 976880ab01..15e7feccdd 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -31,17 +31,9 @@ export class E2BSubprocessService extends SubprocessService {
   private readonly terminalSetups = new Map<Promise<void>, AbortController>()
   private disposing = false
 
-  /** @inheritdoc */
-  readonly cwd: string
-
-  /** @inheritdoc */
-  readonly runtimeRoot: string
-
   /** Create the E2B subprocess service and bind its disposal policy. */
   constructor(ctx: Context) {
     super(ctx)
-    this.cwd = ctx.e2b.cwd
-    this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
       this.disposing = true
       for (const controller of this.terminalSetups.values()) {
@@ -89,14 +81,14 @@ export class E2BSubprocessService extends SubprocessService {
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
       `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
-      { cwd: this.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
+      { cwd: this.ctx.e2b.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
     )
     signal?.throwIfAborted()
     const executable = result.stdout.trim()
     if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
       throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
     }
-    return posix.resolve(this.cwd, executable)
+    return posix.resolve(this.ctx.e2b.cwd, executable)
   }
 
   /** @inheritdoc */
@@ -138,7 +130,7 @@ export class E2BSubprocessService extends SubprocessService {
       }
     }
     spec.signal?.throwIfAborted()
-    const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
+    const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
     const setup = Promise.withResolvers<void>()
     const setupController = new AbortController()
     const setupSignal = spec.signal === undefined
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 067910a10b..9973b5151a 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -775,10 +775,8 @@ describe('E2B subprocess terminal service', () => {
     return { ctx, fiber, fake }
   }
 
-  it('publishes execution-world coordinates and resolves remote executables', async () => {
+  it('resolves remote executables', async () => {
     const { ctx, fake } = await service()
-    expect(ctx.subprocess.cwd).toBe('/workspace')
-    expect(ctx.subprocess.runtimeRoot).toBe('/workspace/.dsh-e2b')
     await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
     await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
       .resolves.toBe('/usr/bin/node')

From e6b3afbee9078429f18a11ce30b2c869e5532545 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 20:02:38 +0800
Subject: [PATCH 135/262] docs(e2b): remove code runtime residue

---
 .../2026-07-28-portable-execution-world-consumers.i18n.yaml   | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.md          | 2 +-
 .../2026-07-28-portable-execution-world-consumers.zh.md       | 2 +-
 packages/e2b/README.i18n.yaml                                 | 4 ++--
 packages/e2b/README.md                                        | 2 +-
 packages/e2b/README.zh.md                                     | 2 +-
 packages/e2b/e2b/README.i18n.yaml                             | 4 ++--
 packages/e2b/e2b/README.md                                    | 2 +-
 packages/e2b/e2b/README.zh.md                                 | 2 +-
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index fb8a3344c1..8cd6ad419a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: fcc30d553f07a28b44227f614f62c2027f8f3dd3
-2026-07-28-portable-execution-world-consumers.zh.md: 5e1e73aee7b96ffe1ae9862f72114a48152ad218
+2026-07-28-portable-execution-world-consumers.md: 2cfdf08ac369048994ebc64d498caaa0847b77de
+2026-07-28-portable-execution-world-consumers.zh.md: ce6650a284e7d64fb1277c758bb77c2394e942c8
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index fcc30d553f..2cfdf08ac3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -30,7 +30,7 @@ Generic consumers use that execution world:
 
 The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates one sandbox and deletes it on timeout or disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole SDK handle from the owner and never create private sandboxes.
 
-E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, the worker-backed Code Runtime and its program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
 
 The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 2ab0685a1d..68d022216c 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -33,7 +33,7 @@ Status: implemented
 
 可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建一个沙箱，并在超时或资源释放时将其删除；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的 SDK 句柄，绝不创建私有沙箱。
 
-E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、基于 worker 的代码运行时及其程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
+E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
 
 适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
 
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index b93f48d8cd..4125487253 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: adc002649e44faefd2f6bd84b7b45fb9fc6fa41d
-README.zh.md: d941de8da2cb831a69a165c86a825def68c2b319
+README.md: f9758e2748aaa2acffb0e928752b2b0fb70cd0a4
+README.zh.md: de068c16d4309499f5dcaa2d08cd9b6cc3023d94
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index adc002649e..f9758e2748 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -10,6 +10,6 @@ An experimental provider-composition POC that places one filesystem/process exec
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox. The worker-backed Code Runtime remains host-local and reaches that world only through the tools its programs call.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
 
 This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index d941de8da2..de068c16d4 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -10,6 +10,6 @@
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。基于 worker 的代码运行时仍在宿主本地运行，只会通过其程序调用的工具触达该执行世界。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
 
 该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 0256b3ccfe..3587067d31 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 52f99178ce8c06e61c13ea9364769ac887db4410
-README.zh.md: 98ba7e79841f548ff6465fda4bc37170c17bc6e0
+README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
+README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 52f99178ce..7ade7c3d65 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -38,7 +38,7 @@ No direct invalidation; this package does not contribute request tokens.
 
 ## Known Limitations and Deferred Work
 
-- **This is not a whole-harness runtime** — Cordis services, the worker-backed Code Runtime, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
 - **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
 - **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
 - **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 98ba7e7984..b683f33d22 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -38,7 +38,7 @@
 
 ## 已知限制与延后工作
 
-- **这不是完整的 harness 运行时**：Cordis 服务、基于 worker 的代码运行时、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
 - **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
 - **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
 - **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。

From f5866fc2023c2c190f61229a8da4aaf917e55a4a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 15:38:00 +0800
Subject: [PATCH 136/262] fix(e2b): address review round on cadence config,
 disposal, and SDK edge cases

- subprocess-e2b: the 20 ms remote poll cadence becomes a validated pollMs
  Config field (each tick is one control-plane request); the README documents
  the latency-versus-request-count trade.
- subprocess-e2b: extract src/remote.ts owning asError, signalOpts,
  commandOpts, delay, waitTick, and one tolerant signalRemoteGroups shared by
  the pgid-keyed process ladder and sid-keyed terminal ladder, so the two
  teardown paths keep identical error tolerance.
- subprocess-e2b: service disposal aggregates sibling cleanup failures into
  one AggregateError instead of discarding all but the first.
- subprocess-e2b: waitForProcessGroupId refuses published group ids <= 1, so
  a same-UID rewrite of the pid file cannot aim termination at kill -- -1;
  README documents the same-UID control-state limitation.
- subprocess-e2b: drain-grace expiry now releases an inherited-output E2B
  callback blocked on host backpressure before disconnecting, so the SDK
  settlement cannot stay pinned behind an unread host stream.
- subprocess-e2b: spawn/spawnTerminal stop validating typed spec fields
  (trust-TypeScript rule; pty-local validates its config before specs exist);
  resolveExecutable rejects separator-containing relative paths per the seam
  contract; terminal setups tracked as a Set of records.
- subprocess-e2b: PTY output push-without-backpressure is a documented
  contract (flowing consumer folds bytes; paused consumer buffers).
- fs-e2b: streamText normalizes the pinned SDK's empty-file '' return into an
  empty stream instead of throwing on getReader().
- e2b overlays: comment the one-world cwd invariant across e2b.cwd,
  workspaceRoot, and bash-local's implicit default workdir.
---
 docs/config-catalog.md                        | 14 +++
 examples/headless-agent/e2b.cordis.yml        |  6 ++
 .../tests/fixtures/e2b/e2b/cordis.yml         |  3 +
 packages/e2b/fs-e2b/src/index.ts              |  8 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 13 ++-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         | 13 ++-
 packages/e2b/subprocess-e2b/README.zh.md      | 13 ++-
 packages/e2b/subprocess-e2b/package.json      |  3 +
 packages/e2b/subprocess-e2b/src/index.ts      | 77 ++++++++++-----
 packages/e2b/subprocess-e2b/src/process.ts    | 77 +++++----------
 packages/e2b/subprocess-e2b/src/remote.ts     | 97 +++++++++++++++++++
 packages/e2b/subprocess-e2b/src/terminal.ts   | 64 ++++--------
 .../subprocess-e2b/tests/subprocess.spec.ts   | 72 +++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 14 ++-
 15 files changed, 339 insertions(+), 139 deletions(-)
 create mode 100644 packages/e2b/subprocess-e2b/src/remote.ts

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b8a49a7ba2..977921db07 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1813,6 +1813,20 @@ export interface Config {
 
 Source: [`packages/subagent/subagent-spawn/src/index.ts:25`](../packages/subagent/subagent-spawn/src/index.ts)
 
+## `@deepseek-ai/dsh-subprocess-e2b`
+
+Requires: `e2b`
+
+```ts config-catalog
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+```
+
+Source: [`packages/e2b/subprocess-e2b/src/index.ts:24`](../packages/e2b/subprocess-e2b/src/index.ts)
+
 ## `@deepseek-ai/dsh-system-prompt`
 
 ```ts config-catalog
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index a65b0baf81..61bdbc8aa7 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,6 +1,12 @@
 # POC overlay: keep the advanced headless agent and model-facing tools, but
 # place its filesystem and process substrate in one short-lived E2B sandbox;
 # the generic Bash, PTY, and LSP consumers compose above them.
+#
+# One-world invariant: e2b.cwd, sandbox-policy.workspaceRoot, and bash-local's
+# default workdir (implicit host process.cwd()) must all name the same remote
+# directory. Only e2b.cwd is created at sandbox open; dropping its !!js line
+# falls back to /home/user/workspace while Bash and PTY keep targeting the
+# host path, so every tool call fails with a remote spawn error.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 3a6deb7e49..e6fd968779 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -1,3 +1,6 @@
+# One-world invariant (same pairing as examples/headless-agent/e2b.cordis.yml):
+# e2b.cwd and sandbox-policy.workspaceRoot must name the same remote directory,
+# which is also bash-local's implicit default workdir.
 - id: e2b
   name: '@deepseek-ai/dsh-e2b'
   config:
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 3b0c835d8c..84c9ac7868 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -232,7 +232,13 @@ export class E2BFileSystem extends FileSystem {
     await this.requireRegular(target, signal)
     let stream: ReadableStream<Uint8Array>
     try {
-      stream = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) })
+      // The pinned SDK's stream overload lies for empty files: content-length 0
+      // returns '' instead of a ReadableStream.
+      const read = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) }) as
+        ReadableStream<Uint8Array> | string
+      stream = typeof read === 'string'
+        ? new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+        : read
     } catch (error: unknown) {
       throw mapError(error, 'read', target.displayPath, signal)
     }
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 618472a6b8..9cad00b6eb 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -149,7 +149,7 @@ class FakeRemote {
         }
         return this.info(path)
       },
-      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array>> => {
+      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array> | string> => {
         this.checkAbort(options)
         if (this.nextReadError !== undefined) {
           const error = this.nextReadError
@@ -158,6 +158,8 @@ class FakeRemote {
         }
         const data = this.followed(path).node.data
         if (options.format === 'bytes') return data.slice()
+        // Pinned-SDK fidelity: a content-length-0 response returns '' even in stream format.
+        if (data.length === 0 && this.streamChunks === undefined) return ''
         const chunks = this.streamChunks ?? [data.slice()]
         return new ReadableStream<Uint8Array>({
           start: (controller) => {
@@ -375,6 +377,15 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect(initiallyBuffered).toBe('€')
   })
 
+  it('streams an empty file even though the pinned SDK returns a non-stream value', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/empty.txt', '')
+    const { fs } = await setup(remote)
+    let streamed = ''
+    for await (const chunk of await fs.streamText(await fs.resolve('empty.txt'))) streamed += chunk
+    expect(streamed).toBe('')
+  })
+
   it('cancels a remote stream when its consumer stops early', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/text.txt', 'ab')
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 0a18bf24a1..d0ce148746 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 3bb9802c3afa41f3949fceeb73e76ea5cebce744
-README.zh.md: 520f0ea1cde18ed523ba80015d3d4700730aba7a
+README.md: 926d4f22f8e96daa103c236121d35e461290221a
+README.zh.md: d1634b6d1a701f7f4815135b4ec6bb86ad1a8c87
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 3bb9802c3a..926d4f22f8 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,16 +2,22 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. Load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+
+## Configuration
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `pollMs` | `20` | Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request, so a larger value trades exit-observation latency for fewer requests. |
 
 ## Behavior
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
-- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
+- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides, and rejects relative paths containing separators like every subprocess provider.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Terminal output is pushed to the handle's stream without awaiting host backpressure: a flowing consumer (the PTY backend attaches one at construction) folds bytes into its own bounded state, while a paused consumer buffers in host memory. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
@@ -29,6 +35,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep.
+- **Control state shares the sandbox user's UID** — E2B runs every command as the same default user, so `0700`/`0600` modes cannot isolate `.dsh-e2b` control files from concurrently running sandbox processes. A background process could rewrite `pid`/`exit-code` or read a not-yet-consumed `environment` file. The adapter validates published values and refuses group ids whose negative form is unsafe to signal (`<= 1`), but real isolation needs an E2B per-command user or an out-of-band control channel.
 - **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
 - **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. A same-UID untrusted process already in the sandbox could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive to close the gap.
 - **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 520f0ea1cd..d1634b6d1a 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,16 +2,22 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+| --- | --- | --- |
+| `pollMs` | `20` | 远程状态／存活轮询节奏（毫秒）；每个 tick 是一次控制面请求，调大该值以牺牲退出观察延迟换取更少的请求。 |
 
 ## 行为
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
-- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
+- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称，并与所有 subprocess 提供方一致地拒绝含分隔符的相对路径。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。终端输出推入句柄流时不等待宿主背压：流动的消费方（PTY 后端在构造时就挂上一个）把字节折叠进自身的有界状态，而暂停的消费方会在宿主内存中缓冲。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
@@ -29,6 +35,7 @@ E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **私有状态随沙箱生命周期存在**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。
+- **控制状态与沙箱用户同 UID**：E2B 以同一默认用户运行每条命令，因此 `0700`/`0600` 权限无法把 `.dsh-e2b` 控制文件与并发运行的沙箱进程隔离开。后台进程可以改写 `pid`/`exit-code`，或读取尚未被消费的 `environment` 文件。适配器会验证已发布的值，并拒绝取负后不安全的进程组 ID（`<= 1`），但真正的隔离需要 E2B 提供按命令用户或带外控制通道。
 - **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
 - **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。一个已在沙箱内运行的同 UID 不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语才能弥合该缺口。
 - **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index d73607d1f3..fa96e17293 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/package.json
@@ -32,6 +32,9 @@
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-e2b": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 15e7feccdd..38b1d32465 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -7,6 +7,7 @@
 import { randomUUID } from 'node:crypto'
 import { posix } from 'node:path'
 import { Context } from 'cordis'
+import z from 'schemastery'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessHandle,
@@ -16,30 +17,53 @@ import type {
 } from '@deepseek-ai/dsh-subprocess'
 import { e2bControlEnvs, quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import { E2BSubprocessHandle } from './process.ts'
+import { asError, signalOpts } from './remote.ts'
 import { spawnE2BTerminal } from './terminal.ts'
 
-function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
-  return signal === undefined ? {} : { signal }
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+
+interface SchemaResolvedConfig extends Config {
+  pollMs: number
+}
+
+interface TerminalSetup {
+  done: Promise<void>
+  controller: AbortController
 }
 
 /** E2B command manager registered as `ctx.subprocess`. */
 export class E2BSubprocessService extends SubprocessService {
   static inject = ['e2b']
 
+  static Config: z<Config> = z.object({
+    pollMs: z.number().default(20),
+  })
+
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
-  private readonly terminalSetups = new Map<Promise<void>, AbortController>()
+  private readonly terminalSetups = new Set<TerminalSetup>()
+  private readonly pollMs: number
   private disposing = false
 
   /** Create the E2B subprocess service and bind its disposal policy. */
-  constructor(ctx: Context) {
+  constructor(ctx: Context, config: Config) {
     super(ctx)
+    // Schemastery fills pollMs before construction; the type does not encode that step.
+    const { pollMs } = config as SchemaResolvedConfig
+    if (!Number.isSafeInteger(pollMs) || pollMs <= 0) {
+      throw new Error('subprocess-e2b: pollMs must be a positive safe integer')
+    }
+    this.pollMs = pollMs
     ctx.effect(() => async () => {
       this.disposing = true
-      for (const controller of this.terminalSetups.values()) {
-        controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
+      for (const setup of this.terminalSetups) {
+        setup.controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
       }
-      await Promise.all([...this.terminalSetups.keys()])
+      await Promise.all([...this.terminalSetups].map(setup => setup.done))
       const handles = [...this.live]
       const terminals = [...this.terminals]
       const pending: Promise<unknown>[] = []
@@ -54,9 +78,11 @@ export class E2BSubprocessService extends SubprocessService {
         pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
       const outcomes = await Promise.allSettled(pending)
-      for (const outcome of outcomes) {
-        if (outcome.status === 'rejected') throw outcome.reason
-      }
+      const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
+        ? [outcome.reason as unknown]
+        : [])
+      if (failures.length === 1) throw asError(failures[0])
+      if (failures.length > 1) throw new AggregateError(failures, 'subprocess-e2b: teardown failed')
     }, 'e2b subprocess teardown')
   }
 
@@ -77,6 +103,11 @@ export class E2BSubprocessService extends SubprocessService {
       signal?.throwIfAborted()
       return command
     }
+    if (command.includes('/')) {
+      throw new Error(
+        `subprocess-e2b: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`,
+      )
+    }
     const path = env?.PATH
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
@@ -88,6 +119,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
       throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
     }
+    // A relative result comes from a relative PATH entry; the lookup ran with the shared cwd.
     return posix.resolve(this.ctx.e2b.cwd, executable)
   }
 
@@ -98,14 +130,11 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
     }
-    if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0) {
-      throw new Error('subprocess-e2b: graceMs must be a positive finite number')
-    }
     if (spec.signal?.aborted === true) {
       throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
     }
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
-    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir)
+    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir, this.pollMs)
     this.live.add(handle)
     const release = async (): Promise<void> => {
       await handle.waitForExit()
@@ -124,24 +153,20 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
     }
-    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
-      if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`subprocess-e2b: terminal ${name} must be a positive safe integer`)
-      }
-    }
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
-    const setup = Promise.withResolvers<void>()
-    const setupController = new AbortController()
+    const done = Promise.withResolvers<void>()
+    const setup: TerminalSetup = { done: done.promise, controller: new AbortController() }
     const setupSignal = spec.signal === undefined
-      ? setupController.signal
-      : AbortSignal.any([spec.signal, setupController.signal])
-    this.terminalSetups.set(setup.promise, setupController)
+      ? setup.controller.signal
+      : AbortSignal.any([spec.signal, setup.controller.signal])
+    this.terminalSetups.add(setup)
     try {
       const terminal = await spawnE2BTerminal(
         this.ctx.e2b,
         { ...spec, signal: setupSignal },
         stateDir,
+        this.pollMs,
       )
       this.terminals.add(terminal)
       // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
@@ -159,8 +184,8 @@ export class E2BSubprocessService extends SubprocessService {
       })
       return terminal
     } finally {
-      this.terminalSetups.delete(setup.promise)
-      setup.resolve()
+      this.terminalSetups.delete(setup)
+      done.resolve()
     }
   }
 }
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index c0aceda334..feb21a70bc 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -21,8 +21,8 @@ import type {
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import { bootstrapEnvironment, readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
+import { asError, commandOpts, signalRemoteGroups, waitTick } from './remote.ts'
 
-const GROUP_POLL_MS = 20
 const OUTPUT_ENCODER_SOURCE = [
   '(async () => {',
   '  for await (const chunk of process.stdin) {',
@@ -48,10 +48,6 @@ function isValidProcessId(value: number): boolean {
   return Number.isSafeInteger(value) && value > 0
 }
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
 class DeferredStdin extends Writable {
   constructor(private readonly ready: Promise<CommandHandle>) {
     super({ decodeStrings: false })
@@ -142,28 +138,6 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   return bootstrap
 }
 
-function commandOpts(
-  envs: Record<string, string>,
-  signal: AbortSignal | undefined,
-): { envs: Record<string, string>; signal?: AbortSignal } {
-  return { envs: e2bControlEnvs(envs), ...(signal === undefined ? {} : { signal }) }
-}
-
-function waitTick(signal?: AbortSignal): Promise<boolean> {
-  if (signal?.aborted === true) return Promise.resolve(false)
-  return new Promise<boolean>((resolve) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort)
-      resolve(true)
-    }, GROUP_POLL_MS)
-    const onAbort = (): void => {
-      clearTimeout(timer)
-      resolve(false)
-    }
-    signal?.addEventListener('abort', onAbort, { once: true })
-  })
-}
-
 const WAIT_ABORTED = Symbol('wait aborted')
 
 function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
@@ -194,6 +168,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
   private readonly terminationController = new AbortController()
+  /** Releases output waits that survive the command outcome, so blocked SDK callbacks settle. */
+  private readonly outputReleased = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
@@ -212,11 +188,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
    * @param runtime - Shared E2B sandbox owner.
    * @param spec - Fully resolved subprocess request.
    * @param stateDir - Remote directory retaining process identity, status, and valid spills.
+   * @param pollMs - Remote status/liveness poll cadence.
    */
   constructor(
     private readonly runtime: E2BSandboxService,
     private readonly spec: SubprocessSpawnSpec,
     readonly stateDir: string,
+    private readonly pollMs = 20,
   ) {
     this.paths = {
       pid: posix.join(stateDir, 'pid'),
@@ -318,7 +296,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
     while (await this.groupAlive(sandbox, processGroupId, signal)) {
       this.throwTerminationFailure()
-      if (!await waitTick(signal)) return false
+      if (!await waitTick(this.pollMs, signal)) return false
     }
     this.throwTerminationFailure()
     if (signal?.aborted === true) return false
@@ -483,19 +461,21 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
       const onClose = (): void => { cleanup(); resolve() }
-      const onTermination = (): void => { cleanup(); resolve() }
+      const onRelease = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
       const cleanup = (): void => {
         target.removeListener('drain', onDrain)
         target.removeListener('close', onClose)
         target.removeListener('error', onError)
-        this.terminationController.signal.removeEventListener('abort', onTermination)
+        this.terminationController.signal.removeEventListener('abort', onRelease)
+        this.outputReleased.signal.removeEventListener('abort', onRelease)
       }
       target.once('drain', onDrain)
       target.once('close', onClose)
       target.once('error', onError)
-      this.terminationController.signal.addEventListener('abort', onTermination, { once: true })
-      if (this.terminationController.signal.aborted) onTermination()
+      this.terminationController.signal.addEventListener('abort', onRelease, { once: true })
+      this.outputReleased.signal.addEventListener('abort', onRelease, { once: true })
+      if (this.terminationController.signal.aborted || this.outputReleased.signal.aborted) onRelease()
     })
   }
 
@@ -514,9 +494,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(pid)) {
           throw new Error(`subprocess-e2b: remote wrapper published invalid process-group id ${JSON.stringify(value)}`)
         }
+        // A same-UID sandbox process can rewrite this file; refuse ids whose
+        // negative form addresses every process (`kill -- -1`) or init's group.
+        if (pid <= 1) {
+          throw new Error(`subprocess-e2b: unsafe published process-group id ${pid}`)
+        }
         return pid
       }
-      const settled = await Promise.race([commandSettled, waitTick().then(() => false)])
+      const settled = await Promise.race([commandSettled, waitTick(this.pollMs).then(() => false)])
       if (settled) throw new Error('subprocess-e2b: remote command exited before publishing its process-group id')
     }
   }
@@ -545,13 +530,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
+        // Release inherited-output waits so a callback blocked on host
+        // backpressure cannot keep the disconnected SDK settlement pending.
+        this.outputReleased.abort(new Error('subprocess-e2b: output drain grace expired'))
         await handle.disconnect()
         return { exitCode, signal: null }
       }
       if (completed !== undefined) return this.commandOutcome(completed)
       // TODO(e2b-status-watch): Replace collect/inherit control-plane polling
       // when E2B can observe direct-command exit independently of descendant-held output.
-      completed = await Promise.race([settlement, waitTick().then(() => undefined)])
+      completed = await Promise.race([settlement, waitTick(this.pollMs).then(() => undefined)])
     }
   }
 
@@ -622,7 +610,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private async terminateGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     this.terminationSignal = 'SIGTERM'
     try {
-      await this.signalGroup(sandbox, processGroupId, 'TERM')
+      await signalRemoteGroups(sandbox, this.controlEnvs, [processGroupId], 'TERM')
       if (await this.waitForGroupExit(sandbox, processGroupId)) {
         this.markQuiescent()
         return
@@ -637,7 +625,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     try {
-      await this.signalGroup(sandbox, processGroupId, 'KILL')
+      await signalRemoteGroups(sandbox, this.controlEnvs, [processGroupId], 'KILL')
     } catch (_processGroupKillFailure) {
       // SDK kill and the final liveness probe remain independent cleanup paths.
     }
@@ -654,7 +642,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const deadline = Date.now() + this.spec.graceMs
     while (await this.groupAlive(sandbox, processGroupId)) {
       if (Date.now() >= deadline) return false
-      await waitTick()
+      await waitTick(this.pollMs)
     }
     return true
   }
@@ -663,21 +651,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     if (this.terminationFailure !== undefined) throw this.terminationFailure
   }
 
-  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<boolean> {
-    // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
-    // a userspace identity precheck cannot close the numeric-PGID reuse race.
-    try {
-      await sandbox.commands.run(
-        `kill -${signal} -- -${pid}`,
-        commandOpts(this.controlEnvs, undefined),
-      )
-      return true
-    } catch (error: unknown) {
-      if (error instanceof CommandExitError || error instanceof SandboxNotFoundError) return false
-      throw error
-    }
-  }
-
   private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
     const result = await sandbox.commands.run(
       `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
diff --git a/packages/e2b/subprocess-e2b/src/remote.ts b/packages/e2b/subprocess-e2b/src/remote.ts
new file mode 100644
index 0000000000..1937f54bf0
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/src/remote.ts
@@ -0,0 +1,97 @@
+/**
+ * Shared remote-control helpers for the E2B subprocess adapter: SDK option
+ * shaping, poll ticks, and the one tolerant process-group signal used by both
+ * the ordinary-process and terminal teardown ladders.
+ */
+
+import { CommandExitError, e2bControlEnvs, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+
+/**
+ * Normalize an unknown rejection into an Error.
+ * @param error - Any thrown or rejected value.
+ * @returns The value itself when already an Error, else a stringified wrapper.
+ */
+export function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Shape the optional-signal SDK options object.
+ * @param signal - Optional cancellation for one SDK request.
+ * @returns An options fragment that omits an undefined signal.
+ */
+export function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+/**
+ * Shape control-shell command options with the isolated HOME override.
+ * @param envs - Explicit environment entries for the control command.
+ * @param signal - Optional cancellation for the SDK request.
+ * @returns Options for `sandbox.commands.run` control invocations.
+ */
+export function commandOpts(
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
+}
+
+/**
+ * Resolve after one duration.
+ * @param ms - Milliseconds to wait.
+ * @returns Settles after the timeout.
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Wait one poll interval or until the signal aborts.
+ * @param pollMs - Poll cadence in milliseconds.
+ * @param signal - Optional abort that ends the wait early.
+ * @returns `true` after a full tick, `false` when aborted first.
+ */
+export function waitTick(pollMs: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted === true) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve(true)
+    }, pollMs)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve(false)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * Signal remote process groups, tolerating the shared teardown outcomes: a
+ * nonzero `kill` (groups already gone) and a disappeared sandbox. Both the
+ * pgid-keyed process ladder and the sid-keyed terminal ladder deliver signals
+ * through this single tolerance so they cannot drift apart.
+ * @param sandbox - Live SDK handle.
+ * @param envs - Control-shell environment entries.
+ * @param groups - Positive process-group ids to signal.
+ * @param signal - `TERM` or `KILL`.
+ */
+export async function signalRemoteGroups(
+  sandbox: Sandbox,
+  envs: Record<string, string>,
+  groups: readonly number[],
+  signal: 'TERM' | 'KILL',
+): Promise<void> {
+  // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
+  // a userspace identity precheck cannot close the numeric-PGID reuse race.
+  try {
+    await sandbox.commands.run(
+      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
+      commandOpts(envs),
+    )
+  } catch (error: unknown) {
+    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
+  }
+}
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 3108a4a60a..fd10ecdd8e 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -25,8 +25,7 @@ import {
   readRemoteEnvironment,
   serializeRemoteEnvironment,
 } from './environment.ts'
-
-const POLL_MS = 20
+import { asError, commandOpts, delay, signalOpts, signalRemoteGroups } from './remote.ts'
 
 const TERMINAL_RUNNER_SOURCE = [
   '#!/bin/bash',
@@ -52,21 +51,6 @@ interface TerminalPaths {
   outputMarker: string
 }
 
-function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
-  return signal === undefined ? {} : { signal }
-}
-
-function commandOpts(
-  envs: Record<string, string>,
-  signal?: AbortSignal,
-): { envs: Record<string, string>; signal?: AbortSignal } {
-  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
-}
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
 class BootstrapOutputFilter {
   readonly ready: Promise<void>
 
@@ -134,10 +118,6 @@ async function waitForBootstrapOutput(
   })
 }
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
 function parsePositiveId(value: string, message: string): number {
   const raw = value.trim()
   const id = Number(raw)
@@ -193,27 +173,12 @@ async function sessionProcessGroups(
   return [...groups]
 }
 
-async function signalGroups(
-  sandbox: Sandbox,
-  groups: number[],
-  signal: 'TERM' | 'KILL',
-  envs: Record<string, string>,
-): Promise<void> {
-  try {
-    await sandbox.commands.run(
-      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
-      commandOpts(envs),
-    )
-  } catch (error: unknown) {
-    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
-  }
-}
-
 async function awaitSessionEmpty(
   sandbox: Sandbox,
   sessionId: number,
   envs: Record<string, string>,
   graceMs: number,
+  pollMs: number,
   kill = false,
 ): Promise<number[]> {
   const deadline = Date.now() + graceMs
@@ -221,12 +186,12 @@ async function awaitSessionEmpty(
     const groups = await sessionProcessGroups(sandbox, sessionId, envs)
     if (groups.length === 0) return groups
     if (kill) {
-      await signalGroups(sandbox, groups, 'KILL', envs)
+      await signalRemoteGroups(sandbox, envs, groups, 'KILL')
       if (Date.now() >= deadline) return await sessionProcessGroups(sandbox, sessionId, envs)
     } else if (Date.now() >= deadline) {
       return groups
     }
-    await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
+    await delay(Math.min(pollMs, Math.max(1, deadline - Date.now())))
   }
 }
 
@@ -236,6 +201,7 @@ async function rollbackUnpublishedTerminal(
   completion: Promise<CommandResult>,
   envs: Record<string, string>,
   graceMs: number,
+  pollMs: number,
 ): Promise<void> {
   let topLevelExited = false
   void completion.then(
@@ -256,11 +222,11 @@ async function rollbackUnpublishedTerminal(
     try {
       let groups = await sessionProcessGroups(sandbox, sessionId, envs)
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'TERM', envs)
-        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs)
+        await signalRemoteGroups(sandbox, envs, groups, 'TERM')
+        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs)
       }
       if (groups.length > 0) {
-        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
+        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs, true)
       }
     } catch (error: unknown) {
       attemptFailures.push(asError(error))
@@ -280,7 +246,7 @@ async function rollbackUnpublishedTerminal(
   const proofFailures: Error[] = []
   if (sessionId !== undefined) {
     try {
-      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
+      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs, true)
       if (groups.length > 0) {
         proofFailures.push(new Error(
           `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
@@ -328,6 +294,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     private readonly controlEnvs: Record<string, string>,
     private readonly stateDir: string,
     private readonly graceMs: number,
+    private readonly pollMs: number,
   ) {
     this.pid = handle.pid
     this.done = this.waitForCommand()
@@ -441,8 +408,8 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     let groups = await sessionProcessGroups(this.sandbox, this.sessionId, this.controlEnvs)
     if (groups.length > 0) {
       this.terminationSignal = 'SIGTERM'
-      await signalGroups(this.sandbox, groups, 'TERM', this.controlEnvs)
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs)
+      await signalRemoteGroups(this.sandbox, this.controlEnvs, groups, 'TERM')
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, this.pollMs)
     }
     if (groups.length === 0 && !this.topLevelExited) {
       await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
@@ -457,7 +424,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
           throw error
         }
       }
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, true)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, this.pollMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
     if (groups.length > 0) {
@@ -485,12 +452,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
  * @param runtime - Shared E2B sandbox owner.
  * @param spec - Fully specified terminal-process request.
  * @param stateDir - Private remote directory for one startup transaction.
+ * @param pollMs - Remote session liveness poll cadence.
  * @returns The live subprocess terminal handle.
  */
 export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
+  pollMs = 20,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
@@ -555,6 +524,7 @@ export async function spawnE2BTerminal(
       controlEnvs,
       stateDir,
       spec.graceMs,
+      pollMs,
     )
   } catch (error: unknown) {
     output.destroy()
@@ -565,7 +535,7 @@ export async function spawnE2BTerminal(
       if (!terminalQuiescent && handle !== undefined) {
         try {
           if (completion === undefined) await handle.kill()
-          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs)
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs, pollMs)
           terminalQuiescent = true
         } catch (cleanupError: unknown) {
           if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 471716ef1a..747dc936c6 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -519,6 +519,38 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('releases an inherited-output callback blocked on host backpressure at drain expiry', async () => {
+    const fake = new FakeSandbox()
+    const written: string[] = []
+    const stdoutWrite = vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: Uint8Array) => {
+      written.push(Buffer.from(chunk).toString())
+      return false
+    }) as typeof process.stdout.write)
+    try {
+      const handle = new E2BSubprocessHandle(runtime(fake), spec({
+        graceMs: 5,
+        stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4 } },
+      }), '/runtime/inherit-backpressure')
+      await flush()
+      let callbackSettled = false
+      const blocked = fake.stdout('blocked bytes').then(() => { callbackSettled = true })
+      await flush()
+      expect(callbackSettled).toBe(false)
+      fake.exitStatus = '0\n'
+
+      await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+      await blocked
+      expect(callbackSettled).toBe(true)
+      expect(written.join('')).toBe('blocked bytes')
+      expect(fake.handle.disconnects).toBe(1)
+
+      handle.terminate()
+      await expect(handle.waitForExit()).resolves.toBe(true)
+    } finally {
+      stdoutWrite.mockRestore()
+    }
+  })
+
   it('waits for lossless raw-pipe output after the direct status is published', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
@@ -1311,6 +1343,17 @@ describe('E2BSubprocessHandle', () => {
     expect(invalidGroup.commandsSeen).toContain('kill -KILL -- -4242')
     await expect(invalid.waitForExit()).resolves.toBe(true)
 
+    // A rewritten pid file must not aim the kill at every process (`-- -1`).
+    const unsafeGroup = new FakeSandbox()
+    unsafeGroup.processGroupId = '1\n'
+    unsafeGroup.delaysKill = true
+    unsafeGroup.sdkKillStops = false
+    unsafeGroup.afterProbe = () => { unsafeGroup.alive = false }
+    const unsafe = new E2BSubprocessHandle(runtime(unsafeGroup), spec(), '/runtime/unsafe-group')
+    await expect(unsafe.done).rejects.toThrow(/unsafe published process-group id 1/)
+    expect(unsafeGroup.commandsSeen).not.toContain('kill -KILL -- -1')
+    await expect(unsafe.waitForExit()).resolves.toBe(true)
+
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
     const absent = new E2BSubprocessHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
@@ -1588,6 +1631,34 @@ describe('E2BSubprocessService', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('aggregates sibling cleanup failures instead of reporting only the first', async () => {
+    const { ctx, fiber } = await service()
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    const first = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('first cleanup failed') }),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    const second = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('second cleanup failed') }),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    const live = (ctx.subprocess as unknown as { live: Set<E2BSubprocessHandle> }).live
+    live.add(first)
+    live.add(second)
+
+    await fiber.dispose()
+    const failure = disposalErrors[0]
+    expect(failure).toBeInstanceOf(AggregateError)
+    if (!(failure instanceof AggregateError)) throw new Error('expected AggregateError')
+    expect(failure.errors.map(error => (error as Error).message).sort()).toEqual([
+      'first cleanup failed',
+      'second cleanup failed',
+    ])
+  })
+
   it('waits for every owned cleanup before reporting a disposal failure', async () => {
     const { ctx, fiber } = await service()
     const failed = {
@@ -1667,7 +1738,6 @@ describe('E2BSubprocessService', () => {
   it('validates synchronous spawn preconditions', async () => {
     const { ctx } = await service()
     expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/)
-    expect(() => ctx.subprocess.spawn(spec({ graceMs: 0 }))).toThrow(/positive finite/)
     expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/)
   })
 
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 9973b5151a..826732f057 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -793,6 +793,8 @@ describe('E2B subprocess terminal service', () => {
   it('rejects invalid executable lookup inputs and results', async () => {
     const { ctx, fake } = await service()
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
+    await expect(ctx.subprocess.resolveExecutable('./bin/server')).rejects.toThrow('is a relative path')
+    await expect(ctx.subprocess.resolveExecutable('node_modules/.bin/server')).rejects.toThrow('is a relative path')
     await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
       .rejects.toThrow('stop')
     fake.resolvedExecutable = 'node\n'
@@ -801,6 +803,15 @@ describe('E2B subprocess terminal service', () => {
     await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
   })
 
+  it('rejects a non-positive poll cadence at load', async () => {
+    const ctx = new Context()
+    ctx.provide('e2b', runtime(new FakeTerminalSandbox()))
+    await expect(ctx.plugin(E2BSubprocessService, { pollMs: 0 }))
+      .rejects.toThrow('pollMs must be a positive safe integer')
+    const explicit = await ctx.plugin(E2BSubprocessService, { pollMs: 5 })
+    await explicit.dispose()
+  })
+
   it('owns live terminals through service disposal', async () => {
     const { ctx, fiber, fake } = await service()
     const terminal = await ctx.subprocess.spawnTerminal(spec({ signal: new AbortController().signal }))
@@ -873,9 +884,6 @@ describe('E2B subprocess terminal service', () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [
       spec({ argv: [] }),
-      spec({ rows: 0 }),
-      spec({ cols: 1.5 }),
-      spec({ graceMs: 0 }),
       spec({ signal: AbortSignal.abort(new Error('cancelled')) }),
     ]) {
       await expect(ctx.subprocess.spawnTerminal(request)).rejects.toThrow()

From 6e1ae76c9bbf001b68dfdeac93f628f755fcdbbd Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 3 Aug 2026 02:17:04 +0800
Subject: [PATCH 137/262] test(e2b): satisfy the steer() receipt signature in
 Agent stubs

Master's steering-receipt API (agent.steer returns SteeringReceipt) reached
this branch through the parent sync; the two E2B live-fixture Agent stubs
return the same rejected-outcome receipt the pty test stubs use.
---
 examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts | 2 +-
 packages/e2b/e2b/tests/composition.e2e.ts             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 7348d1d181..985b0a6121 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -22,7 +22,7 @@ const owner: Agent = {
   acceptsNextStep: false,
   ctx: ownerFiber.ctx,
   followup() {},
-  steer() {},
+  steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
   inject() {},
   send() {},
   cancel() {},
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 3f0b69668d..c09243183e 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -86,7 +86,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         acceptsNextStep: false,
         ctx,
         followup() {},
-        steer() {},
+        steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
         inject() {},
         send() {},
         cancel() {},

From d488330ba4890d12de3373718b243d4ac27b5783 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:04:33 +0800
Subject: [PATCH 138/262] fix(rebase): migrate the replayed E2B branch onto the
 rebased parent

The linear replay carried old-lineage content over parent-owned files;
this checkpoint restores them and adapts the branch to the parent's
post-rebase seam:

- restore all pty/lsp/subprocess/code-runtime surfaces to the parent's
  exact content (this branch claims none of them) and drop the net-zero
  code-runtime-e2b/pty-e2b/lsp-e2b residue and its registrations
- widen serializeRemoteEnvironment to the seam's NodeJS.ProcessEnv
  tombstone contract: an explicit undefined removes an ambient entry
- migrate the two E2B fixture Agent stubs to the Inbox-model interface
  and Session.create
- re-apply the branch's gen-doc-graphs roles, THIRD_PARTY_NOTICES e2b
  row, and packages/README group row (trimmed to the doc budget);
  regenerate catalogs and re-record bilingual pairings
---
 ...8-portable-execution-world-consumers.zh.md |  15 +-
 THIRD_PARTY_NOTICES.md                        |   2 +
 docs/architecture.zh.md                       |   1 -
 docs/capability-seams.md                      |  14 +-
 docs/config-catalog.md                        |  17 +
 .../tests/fixtures/e2b/e2b/bin.ts             |  13 +-
 examples/package.json                         |   3 -
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   2 +-
 packages/code-runtime/README.i18n.yaml        |   4 +-
 packages/code-runtime/README.md               |   9 +-
 packages/code-runtime/README.zh.md            |  13 +-
 .../code-runtime-worker/README.i18n.yaml      |   4 +-
 .../code-runtime-worker/README.md             |   6 +-
 .../code-runtime-worker/README.zh.md          |  26 +-
 .../code-runtime-worker/src/index.ts          |  35 +-
 .../code-runtime/README.i18n.yaml             |   4 +-
 packages/code-runtime/code-runtime/README.md  |   2 +-
 .../code-runtime/code-runtime/README.zh.md    |  20 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |  10 +
 packages/e2b/e2b/tests/composition.e2e.ts     |  13 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  10 +-
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |   5 +-
 packages/lsp/README.zh.md                     |   5 +-
 packages/lsp/lsp-local/src/index.ts           | 199 ++++---
 packages/lsp/lsp-local/src/instance.ts        |  27 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |   2 -
 packages/lsp/lsp/README.i18n.yaml             |   6 +-
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |   5 +-
 packages/pty/README.zh.md                     |   5 +-
 packages/pty/pty-local/src/sanitize.ts        | 188 +++++++
 packages/pty/pty-local/src/session.ts         | 513 ++++++++++++------
 packages/pty/pty-local/tests/sanitize.spec.ts |  34 +-
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   7 +-
 packages/subprocess/README.zh.md              |  11 +-
 pnpm-lock.yaml                                | 230 +++++++-
 scripts/gen-doc-graphs.ts                     |  13 +-
 40 files changed, 1043 insertions(+), 446 deletions(-)
 create mode 100644 packages/pty/pty-local/src/sanitize.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 68d022216c..ce6650a284 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但 PTY 和 LSP 仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY 与 LSP 包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
 
 只有文件操作、命令、终端和语言服务器共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
@@ -18,16 +18,13 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
-
-`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
 
 ## E2B POC 边界
 
@@ -45,7 +42,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 ## 考虑过的替代方案
 
-**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+**为每个远程提供方分别保留 PTY 与 LSP 包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
 
 **为每项能力或工具创建独立沙箱。** 不予采纳，因为文件与进程操作将无法共享身份或状态，从而破坏编码用例，并增加生命周期所有者的数量。
 
@@ -57,8 +54,6 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
-
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop。
 
 **把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的契约、测试和消费方，同时避免把所有者变成无边界的能力集合。
@@ -69,7 +64,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 ## 后果
 
-远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY 与 LSP 组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 1d169819b4..9060950bea 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -57,6 +57,8 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
+| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
+| [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 2d1a0b43d5..9314a3fbfc 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -25,7 +25,6 @@
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
-| `ctx.e2b` | [`e2b/`](../packages/e2b/README.md) | 共享 E2B 沙箱 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
 | `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 50ebe88d4f..4ed8a260d4 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -98,6 +98,10 @@ flowchart LR
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
   svc_goals["ctx.goals<br/>Same-session goal domain"]
+  pkg_e2b["e2b"]
+  svc_e2b["ctx.e2b<br/>E2B sandbox lifecycle owner"]
+  pkg_fs_e2b["fs-e2b"]
+  pkg_subprocess_e2b["subprocess-e2b"]
   pkg_subprocess["subprocess"]
   svc_subprocess["ctx.subprocess<br/>Subprocess seam"]
   pkg_subprocess_local["subprocess-local"]
@@ -190,7 +194,9 @@ flowchart LR
   pkg_directory_picker --> svc_directoryPicker
   pkg_directory_picker_browse --> svc_directoryPicker
   pkg_directory_picker_native --> svc_directoryPicker
+  pkg_e2b --> svc_e2b
   pkg_fs --> svc_fs
+  pkg_fs_e2b --> svc_fs
   pkg_fs_local --> svc_fs
   pkg_fs_sandbox --> svc_fs
   pkg_goal --> svc_goals
@@ -241,6 +247,7 @@ flowchart LR
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
+  pkg_subprocess_e2b --> svc_subprocess
   pkg_subprocess_local --> svc_subprocess
   pkg_system_prompt --> svc_systemPrompt
   pkg_tasks --> svc_tasks
@@ -277,6 +284,8 @@ flowchart LR
   svc_credentials --> pkg_llm_deepseek
   svc_credentials --> pkg_llm_pi_ai
   svc_directoryPicker --> pkg_apiproxy
+  svc_e2b --> pkg_fs_e2b
+  svc_e2b --> pkg_subprocess_e2b
   svc_fs --> pkg_tool_fs
   svc_httpServer --> pkg_connection
   svc_httpServer --> pkg_hmr
@@ -390,7 +399,8 @@ flowchart LR
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
+| `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
 | `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
@@ -399,7 +409,7 @@ flowchart LR
 | `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
 | `ctx.permission` | `core` | [`permission`](../packages/ui/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
-| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
+| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 977921db07..58b319d662 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -399,6 +399,22 @@ export interface Config {
 
 Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
 
+## `@deepseek-ai/dsh-e2b`
+
+```ts config-catalog
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
+  timeoutMs?: number
+}
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts)
+
 ## `@deepseek-ai/dsh-frontend-static`
 
 Requires: `httpServer`
@@ -2587,6 +2603,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-command-feedback` — requires `commands` ([`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts))
 - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts))
 - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
+- `@deepseek-ai/dsh-fs-e2b` — requires `e2b` ([`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
 - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker-auto` — requires `httpServer` · `loader` ([`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts))
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 985b0a6121..7a787c735b 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
+import { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
@@ -14,18 +15,20 @@ if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
 const ctx = await boot('e2b-composition', resolve(configPath))
 const ownerFiber = ctx.plugin(() => {})
 const ownerId = SessionId('e2b-live-owner')
+const session = Session.create(ownerId)
 const owner: Agent = {
   id: ownerId,
   options: {},
-  session: new Session(ownerId),
+  session,
+  inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
   status: 'idle',
-  acceptsNextStep: false,
   ctx: ownerFiber.ctx,
-  followup() {},
-  steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
-  inject() {},
   send() {},
+  followup() {},
+  steer() {},
+  inject() {},
   cancel() {},
+  runMaintenance: task => task(new AbortController().signal),
   whenIdle: () => Promise.resolve(),
 }
 const unregisterOwner = ctx.agents.register(owner)
diff --git a/examples/package.json b/examples/package.json
index e4251c9475..48ac39f5ca 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -54,10 +54,7 @@
     "@deepseek-ai/dsh-sandbox": "workspace:*",
     "@deepseek-ai/dsh-sandbox-local": "workspace:*",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
-<<<<<<< HEAD
     "@deepseek-ai/dsh-scope": "workspace:*",
-=======
->>>>>>> 3f6c905d5e (Add E2B PTY, LSP, and code runtime providers)
     "@deepseek-ai/dsh-session": "workspace:*",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:*",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index ce95627688..7e74d63f31 100644
--- 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: a9a121d0cb13cd5e2148da8d754967359be06bab
-README.zh.md: c6500ebb2abce14fabf68b79ec20f5c23cf5d5f7
+README.md: 1516c20ff55f366fe6af6b0be5495958708f29e3
+README.zh.md: 42f4d2b8d924b19fd3cde863dafb8c59d9c078cf
diff --git a/packages/README.md b/packages/README.md
index 125b466d72..98fc87a6b2 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -6,7 +6,7 @@ Packages use the `@deepseek-ai/dsh-*` scope. Cordis `Service` subclasses and fun
 
 ## Hierarchy
 
-Groups contain packages at `packages/<group>/<pkg>/`; names remain `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
+Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
 
 | Group | Role | Release expectation |
 |---|---|---|
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 30c5ca2572..3eb462d513 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: 34eecc4874afc5a576ed129e72eeeb944b95f67f
-README.zh.md: 85d7a95a37cd1f4090062f3036a6634fde5011ee
+README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
+README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index 34eecc4874..f20a287419 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -2,12 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the generated TypeScript SDK); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` |
-| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution seam and shared vocabulary | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
 
-Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
+Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index 85d7a95a37..f5cd4c9949 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -1,13 +1,12 @@
-# code-runtime/：代码执行能力家族
+# code-runtime/ — 代码执行能力家族
 
 [English](README.md) | 中文
 
-代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于针对宿主提供的异步绑定执行一段模型编写的程序，并捕获程序打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具与生成的 TypeScript SDK）；设计记录在 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 中。这些都是**产品** 包。
+代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）；设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
 
-| 包 | 职责 | ctx 键 |
+| 包 | 职责 | ctx key |
 |---|---|---|
-| `code-runtime/` | 抽象代码执行 seam（接口 + 词汇） | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | worker 线程后端：每次运行使用全新 worker，由宿主侧剥离 TypeScript 类型（类型注解仅供参考，绝不执行类型检查）、端口桥接绑定、预算／堆隔离 | 注册 `ctx.codeRuntime` |
-| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行 seam 与共享词汇 | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
 
-不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
+后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index 10c721446f..8d3568e82e 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
-README.md: 35196a0b4fba5cd0388246a70354308ece08b39f
-README.zh.md: 49871c38c540addd06f5d24793ae00b45e2f8bb0
+README.md: 590b79dcd1bc322350060b55767b09c6305edacc
+README.zh.md: 12c25f892bd20892cb47e593f16b6aadd9ffa84c
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index fbe387e4ea..590b79dcd1 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -32,7 +32,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 ## The worker entry, unbuilt and built
 
-Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local JSON snapshotter is parity-tested against the session-owned canonical boundary; both sides flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. `tests/built-lib.e2e.ts` pins the real load path required by [docs/testing.md](../../../docs/testing.md).
+Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
 The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
 
@@ -46,8 +46,8 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only; deployments requiring process-tree cleanup select `dsh-code-runtime-subprocess`, whose mounted subprocess provider owns that cleanup.
-- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
+- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.
+- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — amaro or sucrase are the named drop-in replacements if the relied-on behavior shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
 - **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
 - **Intermediate binding values have no byte cap** — a program can exhaust process or worker memory with a value that never becomes outer output.
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index 57f2a1145a..12c25f892b 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -23,18 +23,18 @@
 - **每次运行使用一个全新 worker，不设池化**：程序所在的世界会随 worker 一同终止，不会留下需要记录的跨运行状态，也无法发生状态泄漏；仅凭会话日志即可重建运行。
 - **在执行上下文中，由宿主侧剥离类型**：程序会包裹在异步函数外壳中，通过 `node:module` 的 `stripTypeScriptTypes` 剥离类型（只支持可擦除语法；`enum`／namespace 会作为程序 `exception` 被拒绝，且不会启动 worker），再按字节位置切回原内容。之后程序作为 `AsyncFunction` 的函数体执行，因此顶层 `await`／`return` 可用。
 - **端口把对端视为不可信**：模型代码能够访问 `parentPort` 并伪造通信，因此任何代码读取入站消息前，系统都会验证其形状并重新构建（`null`、原始值、无效类型和格式错误的载荷会被静默丢弃；伪造的额外字段绝不会被带入）；宿主对每个调用 id 最多响应一次，只将绑定名称解析为自有属性（伪造的 `constructor` 无法沿原型链访问），丢弃结算后的回复，并验证每个绑定 resolve 值与完成值是否为无损 JSON。伪造的 `log`／`done` 消息无法绕过外层上限：宿主会再次验证，并统计每条获准日志以及完成值或诊断。worker 侧命名空间使用 null-prototype 和 `defineProperty`，因此形似 `__proto__` 的绑定名称只是普通键。
-- **绑定 reject 类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收失败成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
-- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟夹到 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
-- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为有深度上限的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
-- **日志主动流入一个外层账本**：console／stdout／stderr 文本按发送顺序穿过端口，因此超时或被终止的程序仍会显示已经打印的内容。worker 会按 JSON 字符串精确计费，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
-- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既没有环境凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
-- **释放资源时等待完全停稳**：清理会把进行中的运行标记为 `abort`，并在 resolve 前等待每个 worker 退出。
+- **绑定调用被拒绝时使用的异常类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收调用失败的成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误 intrinsic 与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
+- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟限制为 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
+- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为自身嵌套深度有界的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
+- **日志主动流入一个外层账本**：console／stdout／stderr 文本按产生顺序经端口传输，因此超时或被终止的程序仍会显示已经打印的内容。worker 会精确统计 JSON 字符串的字节数，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
+- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既不会获得环境变量中的凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
+- **dispose（资源释放）时等待完全停稳**：清理会使进行中的运行以 `abort` 失败，并会等待每个 worker 退出后再完成。
 
 ## 未构建与已构建的 worker 入口
 
-源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地 JSON 快照器会与会话自有的规范边界执行一致性测试；消息端口两侧都会展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的 VFS Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。`tests/built-lib.e2e.ts` 固定了 [docs/testing.md](../../../docs/testing.md) 要求的真实加载路径。
+源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口周围展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。演练这个已发布入口路径的仓库级要求由[测试策略](../../../docs/testing.md)规定。
 
-SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
+SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Config`。运行所用的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
 
 ## 模型体验
 
@@ -42,13 +42,13 @@ SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的
 
 #### KV Cache 影响
 
-不会直接失效；由具名消费方负责请求前缀变更。
+不会直接失效；由上述消费方负责请求前缀变更。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
-- **程序 spawn 的 OS 进程在终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理进程树的部署应选择 `dsh-code-runtime-subprocess`，由其挂载的子进程提供方负责该清理。
-- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：依赖的行为由单元测试固定；如其发生变化，amaro／sucrase 是已经点名的直接替代品。
+- **程序派生的 OS 进程在程序终止后仍会存活**：`worker.terminate()` 只结束线程，比 bash-local 的进程组终止更弱；在容器后端出现前，孤儿进程清理属于部署职责。
+- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：如依赖的行为发生变化，amaro 或 sucrase 是已经点名的直接替代品。
 - **`computeMs` 到期最多可能超过一个轮询间隔**：系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
-- **程序获得一个含 5 种方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
+- **程序获得一个含 5 个方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
 - **中间绑定值没有字节上限**：程序可以用永远不会成为外层输出的值耗尽进程或 worker 内存。
 - **默认 64 MiB 是拒绝边界，不是可恢复存储**：外层落盘只能保存发生 `output-limit` 后返回的有界日志和诊断；在运行时上限之外被拒绝的字节永远不会到达落盘层。
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 2ece0b5c39..43801899a2 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -21,10 +21,6 @@ import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from
 import { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
 import type { WorkerJsonWire } from './worker-json.ts'
 
-export { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
-export { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
-export type { WorkerJsonWire } from './worker-json.ts'
-
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
   /**
@@ -169,19 +165,14 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
 }
 
 
-/** Shared outer-output accounting for one isolated run; binding values never enter it. */
-export class OutputLedger {
+/** One run's combined outer-output ledger; binding values never enter it. */
+class OutputLedger {
   private bytes = 2 // JSON serialization of the empty logs array: []
   private entries = 0
 
   constructor(private readonly maxBytes: number) {}
 
-  /**
-   * Admit one exact log entry, or report that the hard cap was crossed.
-   * @param text - Candidate log entry.
-   * @param sink - Accepted log entries for the current run.
-   * @returns Whether the complete entry fits the remaining outer-output budget.
-   */
+  /** Admit one exact log entry, or report that the hard cap was crossed. */
   admit(text: string, sink: string[]): boolean {
     const separatorBytes = this.entries > 0 ? 1 : 0
     const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
@@ -192,33 +183,19 @@ export class OutputLedger {
     return true
   }
 
-  /**
-   * Finalize a successful absent-or-JSON completion against the combined cap.
-   * @param logs - Already accepted log entries.
-   * @param value - Optional lossless-JSON completion value.
-   * @returns A success result or an output-limit failure.
-   */
+  /** Finalize a successful absent-or-JSON completion against the combined cap. */
   success(logs: string[], value?: CodeJsonValue): CodeRunResult {
     if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, ...value !== undefined ? { value } : {} }
   }
 
-  /**
-   * Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap.
-   * @param logs - Already accepted log entries.
-   * @param error - Candidate failure diagnostic.
-   * @returns The diagnostic result or an output-limit failure.
-   */
+  /** Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap. */
   failure(logs: string[], error: CodeRunFailure): CodeRunResult {
     if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, error }
   }
 
-  /**
-   * Build the explicit output-limit failure while retaining a fitting prefix of the final log.
-   * @param logs - Candidate log entries in original order.
-   * @returns A capped output-limit result.
-   */
+  /** Build the explicit output-limit failure while retaining a fitting prefix of the final log. */
   limit(logs: string[]): CodeRunResult {
     const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
     // The fixed diagnostic is ASCII, so every character is one byte plus the quotes.
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 51c1466872..a6bd209c7b 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: c7690412d0f1bc8556fc758da4e94c6ce5a08d8f
-README.zh.md: ecfa48a97c46113c52f13c7a6edfc5d6fbbc2285
+README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
+README.zh.md: 15fbcecf77b2318acf3b09101802cd032ae426d2
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 4018cdf508..bb1c20d00a 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **Isolation is backend-specific** — the worker backend is process-local, while the E2B backend reports `container` and keeps orchestration and bindings on the host; the descriptor remains informational rather than a security claim.
+- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
 - **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index ecfa48a97c..15fbcecf77 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -4,21 +4,23 @@
 
 这是**代码执行 seam**：抽象的 `CodeRuntime` 服务（`ctx.codeRuntime`）只定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
-此包是该能力的接口层（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。两者都由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有工具形状的内容都留在消费方。
+此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
 
 ## 服务 API（`ctx.codeRuntime`）
 
 | 成员 | 语义 |
 |---|---|
-| `run(request)` | 针对请求的绑定执行一段程序。**每一种程序结果都通过 error 字段完成 resolve**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底死亡（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如资源释放后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
-| `language` | 只读描述符：`run` 期望的源语言（已知值为 `'typescript'`）。仅供参考，不作门禁；生成语言专用呈现的消费方会对该值执行分支，遇到无法呈现的语言时明确失败。 |
+| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
+| `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为不可信对等方（任意绑定名称都是自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；资源释放会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收 reject 成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+
+binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
 ## 模型体验
 
@@ -26,11 +28,11 @@
 
 #### KV Cache 影响
 
-不会直接失效；由具名消费方负责请求前缀变更。
+不会直接失效；由上述消费方负责请求前缀变更。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
-- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供活跃程序输出的流式日志或进度接口。
+- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
 - **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
-- **隔离方式由后端决定**：worker 后端位于宿主进程内，而 E2B 后端报告 `container`，并把编排与绑定留在宿主；该描述符仍只提供信息，不构成安全声明。
+- **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 21848e55e2..5bd34a8642 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -304,6 +304,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'e2b',
+    summary: 'Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal.',
+    methods: [
+      {
+        signature: 'async getSandbox(): Promise<Sandbox>',
+        jsDoc: '/**\n * Return the shared live SDK handle.\n * @returns the created sandbox after the configured cwd exists.\n * @throws when E2B rejects creation or the service is disposing.\n */',
+      },
+    ],
+  },
   {
     key: 'fs',
     summary: 'Abstract filesystem provider.',
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index c09243183e..01316aeb2d 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -3,6 +3,7 @@ import { join, posix } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
+import { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import {
@@ -78,18 +79,20 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
       await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const ownerId = SessionId('e2b-pty-env-owner')
+      const ownerSession = Session.create(ownerId)
       const owner: Agent = {
         id: ownerId,
         options: {},
-        session: new Session(ownerId),
+        session: ownerSession,
+        inbox: new Inbox(ownerSession, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
         status: 'idle',
-        acceptsNextStep: false,
         ctx,
-        followup() {},
-        steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
-        inject() {},
         send() {},
+        followup() {},
+        steer() {},
+        inject() {},
         cancel() {},
+        runMaintenance: task => task(new AbortController().signal),
         whenIdle: () => Promise.resolve(),
       }
       const backend = new LocalPtyBackend(ctx, {
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 8daae9ccfd..7cdb1b7fbf 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -84,19 +84,21 @@ export function bootstrapEnvironment(raw: string): Record<string, string> {
 /**
  * Overlay explicit entries and serialize one validated E2B environment.
  * @param raw - The complete NUL-delimited remote environment.
- * @param explicit - Deliberate caller overrides applied after ambient scrubbing.
+ * @param explicit - Deliberate caller overrides applied after ambient scrubbing; an `undefined` tombstone removes an ambient entry.
  * @returns NUL-delimited `name=value` entries accepted by `env -i`.
  */
 export function serializeRemoteEnvironment(
   raw: string,
-  explicit: Readonly<Record<string, string>> | undefined,
+  explicit: Readonly<NodeJS.ProcessEnv> | undefined,
 ): string {
   const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) {
-    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value?.includes('\0') === true) {
       throw new Error('subprocess-e2b: environment entries require non-empty NUL-free names without = and NUL-free values')
     }
-    environment.set(name, value)
+    // An explicit undefined is the seam's tombstone: remove the ambient entry.
+    if (value === undefined) environment.delete(name)
+    else environment.set(name, value)
   }
   return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index be241ada6e..9919cdaba5 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: d8bc6047e7eadeb2993f1114564b41913b2970dc
-README.zh.md: d838af346626bb96299a3b702df0dabb6231c15a
+README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
+README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index d8bc6047e7..7fbdf07173 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -7,10 +7,9 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 | Package | Role | ctx key |
 |---|---|---|
 | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
-| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
+| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
-See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) for the remote process/filesystem boundary.
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index d838af3466..e059dbd80b 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -7,10 +7,9 @@
 | 包 | 职责 | ctx key |
 |---|---|---|
 | `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | 通用多服务器本地后端（spawn、JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
-| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
+| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
-协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)。
+设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 3a2baa0c55..fc7e50787f 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -1,19 +1,16 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace realpath, serves transient-open queries
+ * single-flights one server process per canonical workspace target, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
- * and trust their configured servers — no sandbox confinement.
+ * query. Providers read sources through `ctx.fs` and launch servers through
+ * `ctx.subprocess`, so both local and remote implementations share one host.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
-import { accessSync, constants, statSync } from 'node:fs'
-import { delimiter, isAbsolute, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -25,9 +22,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
+import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -47,10 +44,7 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['lsp', 'subprocess']
-
-/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
-
+export const inject = ['fs', 'lsp', 'subprocess']
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -92,6 +86,7 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
+type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -111,27 +106,67 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
+/** Propagate teardown failures only after every sibling has settled. */
+function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
+  const failures: unknown[] = []
+  for (const result of results) {
+    if (result.status === 'rejected') failures.push(result.reason)
+  }
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) throw new AggregateError(failures, message)
+}
+
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context (must inject `lsp`).
+ * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export function apply(ctx: Context, config: Config): void {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
+  const setupAbort = new AbortController()
+  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
+    // An async plugin callback must observe its own disposal before Cordis can
+    // run effect cleanup, because unload otherwise waits for this callback.
+    if (fiber === ctx.fiber && fiber.uid === null) {
+      setupAbort.abort(new Error('lsp-local setup disposed'))
+    }
+  })
+
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = entries.map(([providerId, rawConfig]) => {
-    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-    const resolved = rawConfig as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const childEnv = buildChildEnv(resolved.env)
-    const executable = resolveExecutable(resolved.command, childEnv)
-    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
-  })
+  const providers = await (async () => {
+    const lookups = entries.map(async ([providerId, rawConfig]) => {
+      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+      const resolved = rawConfig as ResolvedServerConfig
+      validateServerConfig(providerId, resolved)
+      const executable = await ctx.subprocess.resolveExecutable(
+        resolved.command,
+        resolved.env,
+        setupAbort.signal,
+      )
+      setupAbort.signal.throwIfAborted()
+      return new LocalLspProvider(
+        providerId,
+        ctx.fs,
+        resolved,
+        executable,
+        spec => ctx.subprocess.spawn(spec),
+      )
+    })
+    try {
+      return await Promise.all(lookups)
+    } catch (error: unknown) {
+      setupAbort.abort(error)
+      await Promise.allSettled(lookups)
+      throw error
+    } finally {
+      stopSetupCancellation()
+    }
+  })()
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -144,7 +179,8 @@ export function apply(ctx: Context, config: Config): void {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
+      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
+      throwTeardownFailures(results, 'lsp-local provider teardown failed')
     }
   }, 'lsp-local.registerProviders')
 }
@@ -181,16 +217,19 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per canonical workspace realpath. */
-  private readonly instances = new Map<string, LspInstance>()
+  /** One live instance per stable canonical workspace identity. */
+  private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<string, Promise<void>>()
+  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
+  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
+  private readonly workspaceLookups = new Set<Promise<void>>()
+  private readonly lifetime = new AbortController()
   private disposed = false
 
   constructor(
     providerId: string,
+    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
-    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -211,43 +250,60 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
+  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
+  private querySignal(signal?: AbortSignal): AbortSignal {
+    return signal === undefined
+      ? this.lifetime.signal
+      : AbortSignal.any([signal, this.lifetime.signal])
+  }
+
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
-    this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
-      this.assertActive(signal)
+    const querySignal = this.querySignal(signal)
+    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
+    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
+    this.workspaceLookups.add(workspaceLookup)
+    let workspace: HostWorkspace
+    try {
+      workspace = await workspaceResult
+    } finally {
+      this.workspaceLookups.delete(workspaceLookup)
+    }
+    this.assertActive(querySignal)
+    const workspaceKey = workspace.target.targetKey
+    return this.enqueue(workspaceKey, querySignal, async () => {
+      this.assertActive(querySignal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
+      this.assertActive(querySignal)
+      let instance = this.instanceFor(workspaceKey, workspace)
       try {
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspace, instance)
-        this.assertActive(signal)
-        instance = this.instanceFor(workspace)
-        return await instance.query(request, source, signal)
+        this.evictIfCurrent(workspaceKey, instance)
+        this.assertActive(querySignal)
+        instance = this.instanceFor(workspaceKey, workspace)
+        return await instance.query(request, source, querySignal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspace, instance)
+          this.evictIfCurrent(workspaceKey, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -261,34 +317,34 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspace: string): LspInstance {
+  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspace)
+    const existing = this.instances.get(workspaceKey)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
+    this.instances.set(workspaceKey, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: string, instance: LspInstance): void {
+  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: string): LspInstance {
+  private createInstance(workspace: HostWorkspace): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace,
-      env: this.childEnv,
+      cwd: workspace.canonicalPath,
+      workspaceUri: workspace.fileUrl,
+      env: this.config.env,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
       maxStderrBytes: this.config.maxStderrBytes,
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
-      pathToFileUri: path => pathToFileURL(path).href,
     }
     return new LspInstance(spec, this.spawner)
   }
@@ -296,51 +352,18 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
+    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
+    const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    await Promise.all([
+    const results = await Promise.allSettled([
       ...live.map(instance => instance.dispose()),
       ...draining,
+      ...resolving,
     ])
     this.queues.clear()
-  }
-}
-
-/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
-function buildChildEnv(extra: Record<string, string>): Record<string, string> {
-  return { ...scrubbedParentEnv(), ...extra }
-}
-
-/**
- * Resolve the server executable to an absolute path: an absolute command is verified directly; a
- * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
- */
-function resolveExecutable(command: string, childEnv: Record<string, string>): string {
-  if (isAbsolute(command)) {
-    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
-    if (!isExecutableFileSync(command)) {
-      throw new Error(`lsp-local: command "${command}" is not an executable file`)
-    }
-    return command
-  }
-  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
-  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
-  for (const dir of pathValue.split(delimiter)) {
-    if (dir === '') continue
-    const candidate = join(dir, command)
-    if (isExecutableFileSync(candidate)) return candidate
-  }
-  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
-}
-
-/** Synchronous regular-file and executable check used only at load-time resolution. */
-function isExecutableFileSync(path: string): boolean {
-  try {
-    if (!statSync(path).isFile()) return false
-    accessSync(path, constants.X_OK)
-    return true
-  } catch {
-    return false
+    this.workspaceLookups.clear()
+    throwTeardownFailures(results, 'lsp-local instance teardown failed')
   }
 }
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 5a12192c62..318704b9fc 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -30,18 +30,12 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
+  /** Canonical workspace file URI supplied by the filesystem provider. */
+  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
   readonly shutdownTimeoutMs: number
-  /** PID advertised to the server; `null` when client and server do not share a process namespace. */
-  readonly clientProcessId?: number | null
-  /**
-   * Encode one implementation-native absolute path as a file URI.
-   * @param path - Canonical workspace or source path.
-   * @returns A file URI interpreted in the server's filesystem namespace.
-   */
-  readonly pathToFileUri: (path: string) => string
 }
 
 /**
@@ -115,9 +109,11 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      processId: this.spec.clientProcessId === undefined ? process.pid : this.spec.clientProcessId,
-      rootUri: this.spec.pathToFileUri(this.spec.cwd),
-      workspaceFolders: [{ uri: this.spec.pathToFileUri(this.spec.cwd), name: 'workspace' }],
+      // A subprocess provider may run in another PID namespace or machine;
+      // the host PID would let the server monitor an unrelated process.
+      processId: null,
+      rootUri: this.spec.workspaceUri,
+      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -154,7 +150,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = this.spec.pathToFileUri(source.canonicalPath)
+    const uri = source.fileUrl
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
@@ -248,10 +244,9 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
-    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
-    // display paths against, not the request's possibly-symlinked workspaceRoot.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
+    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
+    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 22877a94c8..08bad67ae2 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -56,7 +56,6 @@ function makeInstance(
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 200,
     killGraceMs: 200,
-    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess, writer)
   live.push(instance)
@@ -92,7 +91,6 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 150,
     killGraceMs: 150,
-    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess)
   live.push(instance)
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index e63252c7f8..02649a8d39 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/README.i18n.yaml
@@ -1,6 +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
-README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
-README.zh.md: 13ae9700e284ff238147538a571622066efc5747
+#   pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
+README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
+README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 2dff12e3da..65d541a7c1 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: a6706ed653bc60909a23b3598c41bb10ef499cbe
-README.zh.md: 01fecf8d57d933168e91331c4d3c3e4666c13cdc
+README.md: a4f743056b4a524be9623b0f700f37e0534b463f
+README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
diff --git a/packages/pty/README.md b/packages/pty/README.md
index a6706ed653..a4f743056b 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -7,8 +7,7 @@ English | [中文](README.zh.md)
 | Package | Role | ctx key |
 |---|---|---|
 | [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
-| [`pty-local`](pty-local/README.md) (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
-| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
+| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
+The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index 01fecf8d57..c84ad3f1b5 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -7,8 +7,7 @@
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
-| [`pty-local`](pty-local/README.md)（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
-| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
+| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
+设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
new file mode 100644
index 0000000000..1f28315fb1
--- /dev/null
+++ b/packages/pty/pty-local/src/sanitize.ts
@@ -0,0 +1,188 @@
+/** Streaming terminal-control sanitizer for the line-oriented first release. */
+
+import { Buffer } from 'node:buffer'
+
+/** OSC marker emitted by the controlled bash before each prompt. */
+export const PROMPT_MARKER_PREFIX = '133;D;'
+
+/** Exact printable prompt emitted after the private marker. */
+export const CONTROLLED_PROMPT = 'dsh> '
+
+/** One sanitized chunk plus whether it contained the owned prompt marker. */
+export interface SanitizedChunk {
+  text: string
+  prompt: boolean
+  /** Printable text after the latest owned marker in this chunk. */
+  promptTail?: string
+}
+
+/**
+ * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+ * Full terminal emulation is deliberately deferred; ordinary line output and
+ * the private prompt marker are the supported contract.
+ */
+export class TerminalSanitizer {
+  private pending = ''
+  private discardMode: 'osc' | 'csi' | undefined
+  private discardOscEscape = false
+  private trailingCarriageReturn = false
+  private trackingPromptTail = false
+
+  constructor(private readonly maxPendingBytes: number) {}
+
+  /**
+   * Consume one decoded `node-pty` data chunk.
+   * @param chunk - decoded terminal data.
+   * @returns Printable text and whether the private prompt marker completed.
+   */
+  push(chunk: string): SanitizedChunk {
+    this.pending += this.discardPrefix(chunk)
+    let text = ''
+    let prompt = false
+    let includePromptTail = this.trackingPromptTail
+    let promptTail = ''
+    let index = 0
+    const appendText = (value: string): void => {
+      text += value
+      if (this.trackingPromptTail) promptTail += value
+    }
+    while (index < this.pending.length) {
+      const escape = this.pending.indexOf('\x1b', index)
+      if (escape < 0) {
+        appendText(this.pending.slice(index))
+        index = this.pending.length
+        break
+      }
+      appendText(this.pending.slice(index, escape))
+      if (escape + 1 >= this.pending.length) {
+        index = escape
+        break
+      }
+      const kind = this.pending[escape + 1]
+      if (kind === ']') {
+        const bel = this.pending.indexOf('\x07', escape + 2)
+        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
+        let end = -1
+        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
+        else if (bel >= 0) end = bel + 1
+        else if (stringTerminator >= 0) end = stringTerminator + 2
+        if (end < 0) {
+          index = escape
+          break
+        }
+        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
+        const content = this.pending.slice(escape + 2, end - terminatorBytes)
+        if (content.startsWith(PROMPT_MARKER_PREFIX)) {
+          prompt = true
+          this.trackingPromptTail = true
+          includePromptTail = true
+          promptTail = ''
+        }
+        index = end
+        continue
+      }
+      if (kind === '[') {
+        let end = escape + 2
+        while (end < this.pending.length) {
+          const code = this.pending.charCodeAt(end)
+          if (code >= 0x40 && code <= 0x7e) break
+          end += 1
+        }
+        if (end >= this.pending.length) {
+          index = escape
+          break
+        }
+        index = end + 1
+        continue
+      }
+      // Two-byte escape family (save/restore cursor and similar).
+      index = escape + 2
+    }
+    this.pending = this.pending.slice(index)
+    this.enforcePendingBound()
+    return {
+      text: this.normalizeText(text),
+      prompt,
+      ...includePromptTail ? { promptTail } : {},
+    }
+  }
+
+  /**
+   * Flush a trailing printable fragment when the PTY exits.
+   * @returns Remaining printable text; incomplete escapes are discarded.
+   */
+  flush(): string {
+    const text = this.pending.startsWith('\x1b') ? '' : this.pending
+    this.pending = ''
+    this.discardMode = undefined
+    this.discardOscEscape = false
+    this.trackingPromptTail = false
+    const normalized = this.normalizeText(text)
+    if (!this.trailingCarriageReturn) return normalized
+    this.trailingCarriageReturn = false
+    return `${normalized}\n`
+  }
+
+  private normalizeText(text: string): string {
+    let complete = this.trailingCarriageReturn ? `\r${text}` : text
+    this.trailingCarriageReturn = false
+    if (complete.endsWith('\r')) {
+      complete = complete.slice(0, -1)
+      this.trailingCarriageReturn = true
+    }
+    return normalizeTerminalText(complete)
+  }
+
+  private enforcePendingBound(): void {
+    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
+    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
+    this.pending = ''
+  }
+
+  private discardPrefix(chunk: string): string {
+    if (this.discardMode === undefined) return chunk
+    if (this.discardMode === 'csi') {
+      for (let index = 0; index < chunk.length; index += 1) {
+        const code = chunk.charCodeAt(index)
+        if (code >= 0x40 && code <= 0x7e) {
+          this.discardMode = undefined
+          return chunk.slice(index + 1)
+        }
+      }
+      return ''
+    }
+
+    let index = 0
+    if (this.discardOscEscape) {
+      this.discardOscEscape = false
+      if (chunk.startsWith('\\')) {
+        this.discardMode = undefined
+        return chunk.slice(1)
+      }
+    }
+    while (index < chunk.length) {
+      if (chunk[index] === '\x07') {
+        this.discardMode = undefined
+        return chunk.slice(index + 1)
+      }
+      if (chunk[index] === '\x1b') {
+        if (chunk[index + 1] === '\\') {
+          this.discardMode = undefined
+          return chunk.slice(index + 2)
+        }
+        if (index + 1 === chunk.length) this.discardOscEscape = true
+      }
+      index += 1
+    }
+    return ''
+  }
+}
+
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export function normalizeTerminalText(text: string): string {
+  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
+}
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index ebf6b559d1..25ed8fe586 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -1,7 +1,12 @@
-/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
 
-import type { IDisposable, IPty } from 'node-pty'
-import { PtyTerminalSanitizer, PtyTextBuffer, ptySignalName, ptyUtf8Tail } from '@deepseek-ai/dsh-pty'
+import { Buffer } from 'node:buffer'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+} from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -16,30 +21,89 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
+import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
 
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
+function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
+  const chars = Array.from(text)
+  let bytes = 0
+  let start = chars.length
+  while (start > 0) {
+    const next = Buffer.byteLength(chars[start - 1] as string)
+    if (bytes + next > maxBytes) break
+    bytes += next
+    start -= 1
+  }
+  return { text: chars.slice(start).join(''), truncated: true }
+}
+
+class BoundedTextBuffer {
+  private value = ''
+  private dropped = false
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxLines?: number,
+  ) {}
+
+  append(text: string): void {
+    if (text.length === 0) return
+    this.value += text
+    if (this.maxLines !== undefined) {
+      const lines = this.value.split('\n')
+      if (lines.length > this.maxLines) {
+        this.value = lines.slice(lines.length - this.maxLines).join('\n')
+        this.dropped = true
+      }
+    }
+    const tail = utf8Tail(this.value, this.maxBytes)
+    this.value = tail.text
+    this.dropped ||= tail.truncated
+  }
+
+  consume(): PtySendRead {
+    const delta = this.value
+    const truncated = this.dropped
+    this.value = ''
+    this.dropped = false
+    return { delta, truncated }
+  }
+
+  snapshot(): { text: string; truncated: boolean } {
+    return { text: this.value, truncated: this.dropped }
+  }
 }
 
 class LocalSendOperation implements PtySendOperation {
-  private readonly output: PtyTextBuffer
+  private readonly output: BoundedTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
+  private cancellationRequested = false
+  private initialForegroundLeftWait: boolean
+  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
     private readonly onCancel: () => void,
   ) {
-    this.output = new PtyTextBuffer(maxBytes)
+    this.output = new BoundedTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
+    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
     return this.promise.promise
   }
 
+  get settled(): boolean {
+    return this.finished
+  }
+
+  get cancelRequested(): boolean {
+    return this.cancellationRequested
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -66,50 +130,75 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
+  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
+    this.initialForegroundPgid = foreground?.processGroupId
+    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
+  }
+
+  acceptsStdinWait(pgid: number, waiting: boolean): boolean {
+    // The same group may still expose the wait that existed before terminal.write.
+    // Observe every poll so a departure before the exact-settlement threshold
+    // still makes a later return to that wait post-write evidence.
+    if (pgid !== this.initialForegroundPgid) return waiting
+    if (!waiting) this.initialForegroundLeftWait = true
+    return waiting && this.initialForegroundLeftWait
+  }
+
   cancel(): boolean {
     if (this.finished) return false
+    this.cancellationRequested = true
     this.onCancel()
     return true
   }
 }
 
-/** Backend session wrapping one `node-pty` process and its captured process tree. */
+/** Backend session wrapping one provider-owned terminal process. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
-  private readonly sanitizer: PtyTerminalSanitizer
-  private readonly scrollback: PtyTextBuffer
-  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
-  private readonly dataDisposable: IDisposable
-  private readonly exitDisposable: IDisposable
+  private readonly decoder = new TextDecoder()
+  private readonly sanitizer: TerminalSanitizer
+  private readonly scrollback: BoundedTextBuffer
+  private readonly outputEnded = Promise.withResolvers<void>()
+  private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
+  // TODO(pty-send-state-consolidation): Fold the per-send fields below
+  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
+  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
+  // cancellation/readiness interplay now has enough pinned tests to carry
+  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
+  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private interrupting: LocalSendOperation | undefined
+  private activeWrite: Promise<boolean> | undefined
+  private pollingReady: LocalSendOperation | undefined
+  private polling = false
   private promptSeen = false
   private promptTextSeen = false
+  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
+  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: IPty,
-    private readonly inspector: ProcessInspector,
+    private readonly terminal: SubprocessTerminalHandle,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
-    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
-    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
-    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
-      const tail = this.sanitizer.flush()
-      this.appendOutput(tail)
-      this.statusValue = { kind: 'exited', exitCode, signal: ptySignalName(signal) }
-      this.settleActive('session_exit')
-      this.exitPromise.resolve()
-    })
+    this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
+    this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    terminal.output.on('data', this.onTerminalData)
+    terminal.output.once('end', this.onTerminalEnd)
+    terminal.output.once('error', this.onTerminalError)
+    this.completion = terminal.done.then(
+      outcome => this.onExit(outcome),
+      (error: unknown) => { this.onTransportFailure(error) },
+    )
   }
 
   /**
@@ -136,7 +225,14 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new Error('PTY session already has an active send')
+    if (this.active !== undefined) {
+      const draining = this.activeWrite !== undefined
+        ? ' or draining provider write'
+        : this.interrupting !== undefined
+          ? ' or draining foreground interrupt'
+          : ''
+      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
+    }
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -145,29 +241,79 @@ export class LocalPtySession implements PtyBackendSession {
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
+    this.resetReadinessEvidence()
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-
-    try {
-      if (request.text.length > 0) this.terminal.write(request.text)
-      if (request.submit) this.terminal.write('\r')
-    } catch (error: unknown) {
-      this.clearActive()
-      operation.fail(error)
-      return operation
-    }
-
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    this.activeDeadlineTimer = setTimeout(() => {
+      if (this.active === operation) {
+        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
+      }
+    }, this.config.timeoutMs)
+    void this.beginSend(operation, request)
     return operation
   }
 
+  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    let foreground: SubprocessTerminalForeground | undefined
+    try {
+      foreground = await this.terminal.inspectForeground()
+    } catch (error: unknown) {
+      // A pre-write inspection failure while cancellation owns the slot must not
+      // release it: interruptOnce's in-flight foreground signal could land on a
+      // successor's foreground group. The interrupt path's post-signal tail
+      // resumes polling, whose guarded catch propagates a persistent failure.
+      // A retained settled operation implies that same in-flight interrupt, so
+      // this guard admits only an unsettled active send.
+      if (this.active === operation && !this.closing && this.interrupting !== operation) {
+        this.failActive(error)
+      }
+      return
+    }
+    try {
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
+      operation.setInitialForeground(foreground)
+      const input = `${request.text}${request.submit ? '\r' : ''}`
+      if (input.length > 0 && !operation.cancelRequested) {
+        this.resetReadinessEvidence()
+        const write = this.terminal.write(input)
+        this.activeWrite = write.then(() => true, () => false)
+        try {
+          await write
+        } finally {
+          this.activeWrite = undefined
+        }
+      }
+      // Cancellation owns post-write signalling and reservation release.
+      if (operation.cancelRequested) return
+      if (this.active === operation && operation.settled) {
+        this.clearActive()
+        return
+      }
+      // Closing can race the awaited provider write even though static analysis sees only local assignments.
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
+      if (this.active === operation && !this.closing) {
+        this.pollingReady = operation
+        this.schedulePoll(operation)
+      }
+    } catch (error: unknown) {
+      if (this.active === operation && !this.closing) {
+        if (operation.settled) this.clearActive()
+        else this.failActive(error)
+      }
+    }
+  }
+
+  private resetReadinessEvidence(): void {
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    this.promptTail = ''
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -182,7 +328,7 @@ export class LocalPtySession implements PtyBackendSession {
     const end = totalLines - offset
     const start = Math.max(0, end - count)
     const requested = lines.slice(start, end).join('\n')
-    const bounded = ptyUtf8Tail(requested, this.config.maxReadBytes)
+    const bounded = utf8Tail(requested, this.config.maxReadBytes)
     const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
     return {
       text: bounded.text,
@@ -193,16 +339,10 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  signal(signal: PtySignal): Promise<PtySignalResult> {
-    return Promise.resolve().then(() => {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      if (signal === 'SIGKILL' && pgid === this.pid) {
-        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
-      }
-      this.inspector.signalGroup(pgid, signal)
-      return { delivered: true, targetPgid: pgid }
-    })
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.closing) throw new Error('PTY session is closing')
+    const targetPgid = await this.terminal.signalForeground(signal)
+    return { delivered: true, targetPgid }
   }
 
   status(): PtySessionStatus {
@@ -221,21 +361,56 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
+  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
+    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+    this.onData(this.decoder.decode(bytes, { stream: true }))
+  }
+
+  private readonly onTerminalEnd = (): void => {
+    this.onData(this.decoder.decode())
+    this.appendOutput(this.sanitizer.flush())
+    this.outputEnded.resolve()
+  }
+
+  private readonly onTerminalError = (error: Error): void => {
+    this.onTransportFailure(error)
+    this.outputEnded.resolve()
+  }
+
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
+      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
+      // before attributing a signal-delayed prompt to a later send.
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
+      this.promptTail = ''
       this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
     }
+    if (this.promptSeen && sanitized.promptTail !== undefined) {
+      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
+      this.promptTail += sanitized.promptTail.slice(0, remaining)
+      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
+      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
+    }
+  }
+
+  private async onExit(outcome: SubprocessOutcome): Promise<void> {
+    await this.outputEnded.promise
+    if (this.transportFailure !== undefined) return
+    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+    this.settleActive('session_exit')
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -245,60 +420,94 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private pollReadiness(operation: LocalSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
-        this.settleActive('stdin_read')
-        return
-      }
-    }
-    const elapsed = Date.now() - operation.startedAt
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    if (startupHasOutput && elapsed >= this.config.exactProbeAfterMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid !== undefined && this.inspector.isStdinWaiting(pgid)) {
-        this.settleActive('stdin_read')
-        return
-      }
-    }
-    // A prompt candidate can race bash's foreground handoff, but an interactive
-    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-    // on waiting for shell ownership instead of letting a child marker suppress
-    // readiness until the absolute timeout. When a prompt marker was seen, the
-    // configured grace holds the fallback past the silence bound so polls in
-    // that window can observe the foreground handoff and settle as stdin_read.
-    const idleFor = Date.now() - this.lastOutputAt
-    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
+  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
+    if (this.active !== operation || this.interrupting === operation || this.polling) return
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = setTimeout(() => {
+      this.activeTimer = undefined
+      void this.pollReadiness(operation)
+    }, delayMs)
   }
 
-  private settleActive(waitReason: PtyWaitReason): void {
+  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
+    if (this.active !== operation || this.polling) return
+    this.polling = true
+    try {
+      if (this.statusValue.kind === 'exited') {
+        this.settleActive('session_exit')
+        return
+      }
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
+      const idleFor = Date.now() - this.lastOutputAt
+      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
+        this.shellPgid = foreground.processGroupId
+      }
+      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
+        && foreground?.processGroupId === this.shellPgid) {
+        this.settleActive('stdin_read')
+        return
+      }
+      const elapsed = Date.now() - operation.startedAt
+      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+      const acceptsStdinWait = startupHasOutput && foreground !== undefined
+        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
+      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+        this.settleActive('stdin_read')
+        return
+      }
+      // A prompt candidate can race bash's foreground handoff, but an interactive
+      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+      // on waiting for shell ownership instead of letting a child marker suppress
+      // readiness until the absolute timeout.
+      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+        this.settleActive('inferred_idle')
+      }
+    } catch (error: unknown) {
+      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
+    } finally {
+      this.polling = false
+      const active = this.active
+      // Awaited provider inspection can clear or replace the active send despite static analysis.
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
+      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
+    }
+  }
+
+  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    this.stopReadinessPolling()
+    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
+    this.activeDeadlineTimer = undefined
+  }
+
+  private stopReadinessPolling(): void {
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = undefined
+    this.pollingReady = undefined
   }
 
   private clearActive(): void {
+    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    if (this.interrupting === operation) this.interrupting = undefined
+    this.pollingReady = undefined
     this.active = undefined
   }
 
@@ -311,104 +520,46 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.interrupting = operation
+    this.stopReadinessPolling()
+    void this.interruptOnce(operation)
+  }
+
+  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      this.inspector.signalGroup(pgid, 'SIGINT')
+      const activeWrite = this.activeWrite
+      if (activeWrite !== undefined && !await activeWrite) return
+      await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
-      this.failActive(error)
+      if (this.active === operation && !this.closing) this.onTransportFailure(error)
+      return
+    } finally {
+      if (this.interrupting === operation) this.interrupting = undefined
     }
-  }
-
-  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
-    return members.filter(member => this.inspector.isAlive(member))
-  }
-
-  private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
-  }
-
-  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = this.survivors(members)
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
-      survivors = this.survivors(members)
-    }
-    return survivors
-  }
-
-  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, signal)
-      } catch (_alreadyExitedDuringSignal) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-  }
-
-  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
-    const members: ProcessIdentity[] = []
-    const seen = new Set<string>()
-    for (const group of groups) {
-      for (const member of group) {
-        const key = JSON.stringify([member.pid, member.started])
-        if (seen.has(key)) continue
-        seen.add(key)
-        members.push(member)
-      }
-    }
-    return members
-  }
-
-  private async stopDescendants(): Promise<ProcessIdentity[]> {
-    const captured = this.descendants()
-    this.signalMembers(captured, 'SIGTERM')
-    const capturedSurvivors = await this.waitForExit(captured)
-    // A TERM-handling descendant may have forked while winding down. Rescan
-    // while the shell can still reap every member, then kill both the fresh
-    // tree and captured survivors that were reparented out of that tree.
-    const members = this.unionMembers(capturedSurvivors, this.descendants())
-    this.signalMembers(members, 'SIGKILL')
-    const survivors = await this.waitForExit(members)
-    return this.survivors(this.unionMembers(survivors, this.descendants()))
-  }
-
-  private async stopShell(): Promise<void> {
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExitedDuringTerm) {
-      // The exit notification remains authoritative.
-    }
-    if (this.statusValue.kind === 'running') {
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      try {
-        this.terminal.kill('SIGKILL')
-      } catch (_topLevelAlreadyExitedDuringKill) {
-        // The exit notification remains authoritative.
-      }
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
+    if (this.active === operation && operation.settled) {
+      this.clearActive()
+    } else if (this.active === operation && !this.closing) {
+      this.pollingReady = operation
+      this.schedulePoll(operation, 0)
     }
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    const survivors = await this.stopDescendants()
-    if (survivors.length > 0) {
-      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    try {
+      await this.terminal.terminate()
+    } catch (error: unknown) {
+      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
     }
-    await this.stopShell()
+    // Quiescence is the active send's terminal outcome.
     this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    await this.completion
+    this.terminal.output.off('data', this.onTerminalData)
+    this.terminal.output.off('end', this.onTerminalEnd)
+    this.terminal.output.off('error', this.onTerminalError)
+    if (this.transportFailure !== undefined) throw this.transportFailure
   }
 }
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index 06ec076358..f6649b3c6f 100644
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -1,17 +1,17 @@
 import { describe, expect, it } from 'vitest'
-import { normalizePtyTerminalText, PtyTerminalSanitizer } from '@deepseek-ai/dsh-pty'
+import { normalizeTerminalText, TerminalSanitizer } from '@deepseek-ai/dsh-pty-local/src/sanitize.ts'
 
-describe('PtyTerminalSanitizer', () => {
+describe('TerminalSanitizer', () => {
   it('removes split CSI and owned OSC prompt markers', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
+    const sanitizer = new TerminalSanitizer(64)
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
+    const sanitizer = new TerminalSanitizer(64)
     expect(sanitizer.push('a\x1b]0;title\x1b\\b\x1b7c\x07')).toEqual({ text: 'abc', prompt: false })
     expect(sanitizer.push('tail\x1b')).toEqual({ text: 'tail', prompt: false })
     expect(sanitizer.flush()).toBe('')
@@ -22,11 +22,11 @@ describe('PtyTerminalSanitizer', () => {
   })
 
   it('normalizes CRLF and standalone carriage returns', () => {
-    expect(normalizePtyTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
+    expect(normalizeTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
   })
 
   it('carries a trailing carriage return across data chunks and flushes standalone CR', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
+    const sanitizer = new TerminalSanitizer(64)
     expect(sanitizer.push('a\r')).toEqual({ text: 'a', prompt: false })
     expect(sanitizer.push('\nb')).toEqual({ text: '\nb', prompt: false })
     expect(sanitizer.push('\r')).toEqual({ text: '', prompt: false })
@@ -34,41 +34,41 @@ describe('PtyTerminalSanitizer', () => {
   })
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
+    const sanitizer = new TerminalSanitizer(64)
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {
-    const oscBel = new PtyTerminalSanitizer(8)
+    const oscBel = new TerminalSanitizer(8)
     expect(oscBel.push(`\x1b]0;${'x'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(oscBel.push('more\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscSt = new PtyTerminalSanitizer(8)
+    const oscSt = new TerminalSanitizer(8)
     oscSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscSt.push('more\x1b')).toEqual({ text: '', prompt: false })
     expect(oscSt.push('\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscDirectSt = new PtyTerminalSanitizer(8)
+    const oscDirectSt = new TerminalSanitizer(8)
     oscDirectSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscDirectSt.push('more\x1b\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscFalseSt = new PtyTerminalSanitizer(8)
+    const oscFalseSt = new TerminalSanitizer(8)
     oscFalseSt.push(`\x1b]0;${'x'.repeat(16)}`)
     oscFalseSt.push('\x1b')
     expect(oscFalseSt.push('more')).toEqual({ text: '', prompt: false })
     expect(oscFalseSt.push('\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscNonTerminatingEscape = new PtyTerminalSanitizer(8)
+    const oscNonTerminatingEscape = new TerminalSanitizer(8)
     oscNonTerminatingEscape.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscNonTerminatingEscape.push('more\x1bxmore\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const csi = new PtyTerminalSanitizer(8)
+    const csi = new TerminalSanitizer(8)
     expect(csi.push(`\x1b[${'1'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(csi.push('123')).toEqual({ text: '', prompt: false })
     expect(csi.push('mtext')).toEqual({ text: 'text', prompt: false })
 
-    const flushed = new PtyTerminalSanitizer(8)
+    const flushed = new TerminalSanitizer(8)
     flushed.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(flushed.flush()).toBe('')
     expect(flushed.push('text')).toEqual({ text: 'text', prompt: false })
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 4097420382..0ebb5bd4af 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: cdea3803e903b31e895658745bc6dbf5a3c04c71
-README.zh.md: 95b02b6491077750f23ff12ffd14c1aa174609be
+README.md: f2b19436da40feb14d067e2cfc706222625680b5
+README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index cdea3803e9..f2b19436da 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,12 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The shared home for spawning managed child-process trees: fully-specified spawn specs with Node-shaped per-stream stdio dispositions (raw pipes, inherit, bounded tail-keep collection with spill files), the one credential scrub every harness spawner uses, offset-based incremental reads, tree-scoped signalling with SIGTERM→grace→SIGKILL escalation, and the cooperative dispose ladder. Command defaulting, shell semantics, deadlines, protocol framing, and presentation stay with consumers — the [bash executors](../bash/README.md), the [LSP host](../lsp/README.md), and the [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: abstract `SubprocessService.spawn(spec)`, the fully-explicit `SubprocessSpawnSpec` with per-stream stdio dispositions, `SubprocessHandle` (streams, offset-based readers, terminate/waitForExit/dispose), and the shared scrub + `DSH_*`/`CollectedOutput` vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, per-disposition stream wiring, tail-keep truncation with bounded private spill files, the `DSH_*` merge order, tree signalling with escalation, the dispose ladder, and terminate-and-join disposal |
-| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 95b02b6491..938312448d 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,13 +1,12 @@
-# subprocess/：进程管理能力家族
+# subprocess/：子进程能力家族
 
 [English](README.md) | 中文
 
-spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其 stdio 处置方式（disposition）为 Node 形状、按流划分（原始管道、inherit、附带 spill 文件的有界尾部保留收集）；harness 中所有 spawn 调用方共用的那一份凭据清除；基于偏移量的增量读取；以进程树为范围、带 SIGTERM→宽限期→SIGKILL 升级的信号发送；以及协作式 dispose（资源释放）阶梯。命令默认值补全、shell 语义、deadline、协议分帧与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
-| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
-服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
+即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f682bc6847..d2e7d0ec1c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -346,6 +346,12 @@ importers:
       '@deepseek-ai/dsh-credentials-local':
         specifier: workspace:*
         version: link:../packages/credentials/credentials-local
+      '@deepseek-ai/dsh-e2b':
+        specifier: workspace:*
+        version: link:../packages/e2b/e2b
+      '@deepseek-ai/dsh-fs-e2b':
+        specifier: workspace:*
+        version: link:../packages/e2b/fs-e2b
       '@deepseek-ai/dsh-fs-local':
         specifier: workspace:*
         version: link:../packages/fs/fs-local
@@ -493,6 +499,9 @@ importers:
       '@deepseek-ai/dsh-subagent-spawn':
         specifier: workspace:*
         version: link:../packages/subagent/subagent-spawn
+      '@deepseek-ai/dsh-subprocess-e2b':
+        specifier: workspace:*
+        version: link:../packages/e2b/subprocess-e2b
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:*
         version: link:../packages/subprocess/subprocess-local
@@ -716,9 +725,6 @@ importers:
 
   packages/bash/bash:
     devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3094,6 +3100,9 @@ importers:
 
   packages/credentials/credentials:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3132,6 +3141,59 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/e2b/e2b:
+    dependencies:
+      e2b:
+        specifier: 2.29.1
+        version: 2.29.1
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-loader-smoke':
+        specifier: workspace:^
+        version: link:../../support/loader-smoke
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/e2b/fs-e2b:
+    devDependencies:
+      '@deepseek-ai/dsh-e2b':
+        specifier: workspace:^
+        version: link:../e2b
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/e2b/subprocess-e2b:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-e2b':
+        specifier: workspace:^
+        version: link:../e2b
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-subprocess':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/examples/acp-demo:
     devDependencies:
       '@cordisjs/plugin-include':
@@ -7848,6 +7910,9 @@ packages:
     resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
     hasBin: true
 
+  '@bufbuild/protobuf@2.13.0':
+    resolution: {integrity: sha512-acq7c49vxfm1ggJ95P70TX7ABDM0vxr1SYD3BB0o0jnBLB4OAqeHyKuN+cD3w80gXEDQ2zxHpR6CUeA+O/aU9g==}
+
   '@chevrotain/types@11.1.2':
     resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
 
@@ -7859,6 +7924,17 @@ packages:
     resolution: {integrity: sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A==}
     engines: {node: '>= 20.12.0'}
 
+  '@connectrpc/connect-web@2.0.0-rc.3':
+    resolution: {integrity: sha512-w88P8Lsn5CCsA7MFRl2e6oLY4J/5toiNtJns/YJrlyQaWOy3RO8pDgkz+iIkG98RPMhj2thuBvsd3Cn4DKKCkw==}
+    peerDependencies:
+      '@bufbuild/protobuf': ^2.2.0
+      '@connectrpc/connect': 2.0.0-rc.3
+
+  '@connectrpc/connect@2.0.0-rc.3':
+    resolution: {integrity: sha512-ARBt64yEyKbanyRETTjcjJuHr2YXorzQo0etyS5+P6oSeW8xEuzajA9g+zDnMcj1hlX2dQE93foIWQGfpru7gQ==}
+    peerDependencies:
+      '@bufbuild/protobuf': ^2.2.0
+
   '@csstools/color-helpers@6.1.0':
     resolution: {integrity: sha512-064IFJdjTfUqnjpCVpMOdbr8FLQBhinbZj6yRv2An2E41O/pLEXqfFRWqGq/SxlE5PEUYTlvWsG2r8MswAVvkg==}
     engines: {node: '>=20.19.0'}
@@ -8478,6 +8554,14 @@ packages:
     resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
     engines: {node: '>=12'}
 
+  '@isaacs/cliui@9.0.0':
+    resolution: {integrity: sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==}
+    engines: {node: '>=18'}
+
+  '@isaacs/fs-minipass@4.0.1':
+    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
+    engines: {node: '>=18.0.0'}
+
   '@joplin/turndown-plugin-gfm@1.0.67':
     resolution: {integrity: sha512-FZfW5EZfidhzd1IaY1uxHnIZPTVOxAdleMZ4/1U6Nt5b7+Qj5JThDnaIomuJtetnUBzuRNbe9FWMuqD4B3dlWA==}
 
@@ -10263,6 +10347,10 @@ packages:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
 
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
   character-entities-html4@2.1.0:
     resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
 
@@ -10280,6 +10368,10 @@ packages:
     resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
     engines: {node: '>= 20.19.0'}
 
+  chownr@3.0.0:
+    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
+    engines: {node: '>=18'}
+
   clsx@2.1.1:
     resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
     engines: {node: '>=6'}
@@ -10306,6 +10398,9 @@ packages:
     resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
     engines: {node: '>= 12'}
 
+  compare-versions@6.1.1:
+    resolution: {integrity: sha512-4hm4VPpIecmlg59CHXnRDnqGplJFrbLG4aFEl5vl6cK1u76ws3LLvX7ikFnTDl5vo39sjWD6AaDPYodJp/NNHg==}
+
   content-disposition@1.1.0:
     resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
     engines: {node: '>=18'}
@@ -10571,6 +10666,9 @@ packages:
     resolution: {integrity: sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw==}
     engines: {node: '>=0.3.1'}
 
+  dockerfile-ast@0.7.1:
+    resolution: {integrity: sha512-oX/A4I0EhSkGqrFv0YuvPkBUSYp1XiY8O8zAKc8Djglx8ocz+JfOr8gP0ryRMC2myqvDLagmnZaU9ot1vG2ijw==}
+
   dom-accessibility-api@0.5.16:
     resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
 
@@ -10590,6 +10688,10 @@ packages:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
     engines: {node: '>= 0.4'}
 
+  e2b@2.29.1:
+    resolution: {integrity: sha512-n4aGNwRKTj2oct7BrOWfR4T+xGO834vbsrzfSlWUNJrhz615Lp+ad9hc8KtRaaHULKr/W/14Z6v4c7fqk3y0pg==}
+    engines: {node: '>=20.18.1'}
+
   eastasianwidth@0.2.0:
     resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
 
@@ -10920,6 +11022,12 @@ packages:
     deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
     hasBin: true
 
+  glob@11.1.0:
+    resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==}
+    engines: {node: 20 || >=22}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+    hasBin: true
+
   globals@17.7.0:
     resolution: {integrity: sha512-Czmyns5dUsq4seFBR/Kdydhmo8y9kC79hiSkPn0YcGtNnYWnrgt0vjrSjx9tspoDGWm2CMarffRuLjM4xUz8xg==}
     engines: {node: '>=18'}
@@ -11103,6 +11211,10 @@ packages:
   jackspeak@3.4.3:
     resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
 
+  jackspeak@4.2.3:
+    resolution: {integrity: sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==}
+    engines: {node: 20 || >=22}
+
   jiti@2.7.0:
     resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
     hasBin: true
@@ -11599,6 +11711,10 @@ packages:
   minisearch@7.2.0:
     resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==}
 
+  minizlib@3.1.0:
+    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
+    engines: {node: '>= 18'}
+
   mitt@3.0.1:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
 
@@ -11742,6 +11858,12 @@ packages:
       zod:
         optional: true
 
+  openapi-fetch@0.14.1:
+    resolution: {integrity: sha512-l7RarRHxlEZYjMLd/PR0slfMVse2/vvIAGm75/F7J6MlQ8/b9uUQmUF2kCPrQhJqMXSxmYWObVgeYXbFYzZR+A==}
+
+  openapi-typescript-helpers@0.0.15:
+    resolution: {integrity: sha512-opyTPaunsklCBpTK8JGef6mfPhLSnyy5a0IN9vKtx3+4aExf+KxEqYwIy3hqkedXIB97u357uLMJsOnm3GVjsw==}
+
   optionator@0.9.4:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
@@ -11828,6 +11950,10 @@ packages:
     resolution: {integrity: sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==}
     engines: {node: '>=16 || 14 >=14.18'}
 
+  path-scurry@2.0.2:
+    resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
+    engines: {node: 18 || 20 || >=22}
+
   path-to-regexp@8.4.2:
     resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
 
@@ -11848,6 +11974,9 @@ packages:
     resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
     engines: {node: '>=16.20.0'}
 
+  platform@1.3.6:
+    resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
+
   playwright-core@1.61.1:
     resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
     engines: {node: '>=18'}
@@ -12226,6 +12355,10 @@ packages:
   tabbable@6.5.0:
     resolution: {integrity: sha512-wieBHXygIm7OyQOu5hQlkk62/WyCFYGlWg7L6/ZCUZwx0o398Zkn4pVmMyfYhfMG8kGrj/Krt8eIk6UKC6VzwA==}
 
+  tar@7.5.22:
+    resolution: {integrity: sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==}
+    engines: {node: '>=18'}
+
   tinybench@2.9.0:
     resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
 
@@ -12629,6 +12762,9 @@ packages:
   vscode-languageserver-protocol@3.18.2:
     resolution: {integrity: sha512-XRyDbT0Pp3sSNti3JmxVEUMySWCSi1hhM+/KUlCy1hV1zmrqpM1OwO12EAki8blhmLuIMpaJrYbo0OzGVfK2Qg==}
 
+  vscode-languageserver-textdocument@1.0.12:
+    resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
+
   vscode-languageserver-types@3.18.0:
     resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==}
 
@@ -12723,6 +12859,10 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
+  yallist@5.0.0:
+    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
+    engines: {node: '>=18'}
+
   yaml@2.9.0:
     resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
     engines: {node: '>= 14.6'}
@@ -13326,6 +13466,8 @@ snapshots:
     dependencies:
       css-tree: 3.2.1
 
+  '@bufbuild/protobuf@2.13.0': {}
+
   '@chevrotain/types@11.1.2': {}
 
   '@clack/core@1.4.3':
@@ -13340,6 +13482,15 @@ snapshots:
       fast-wrap-ansi: 0.2.2
       sisteransi: 1.0.5
 
+  '@connectrpc/connect-web@2.0.0-rc.3(@bufbuild/protobuf@2.13.0)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0))':
+    dependencies:
+      '@bufbuild/protobuf': 2.13.0
+      '@connectrpc/connect': 2.0.0-rc.3(@bufbuild/protobuf@2.13.0)
+
+  '@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0)':
+    dependencies:
+      '@bufbuild/protobuf': 2.13.0
+
   '@csstools/color-helpers@6.1.0': {}
 
   '@csstools/css-calc@3.2.1(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
@@ -13756,6 +13907,12 @@ snapshots:
       wrap-ansi: 8.1.0
       wrap-ansi-cjs: wrap-ansi@7.0.0
 
+  '@isaacs/cliui@9.0.0': {}
+
+  '@isaacs/fs-minipass@4.0.1':
+    dependencies:
+      minipass: 7.1.3
+
   '@joplin/turndown-plugin-gfm@1.0.67': {}
 
   '@jridgewell/gen-mapping@0.3.13':
@@ -15310,6 +15467,8 @@ snapshots:
 
   chai@6.2.2: {}
 
+  chalk@5.6.2: {}
+
   character-entities-html4@2.1.0: {}
 
   character-entities-legacy@3.0.0: {}
@@ -15324,6 +15483,8 @@ snapshots:
     dependencies:
       readdirp: 5.0.0
 
+  chownr@3.0.0: {}
+
   clsx@2.1.1: {}
 
   color-convert@2.0.1:
@@ -15340,6 +15501,8 @@ snapshots:
 
   commander@8.3.0: {}
 
+  compare-versions@6.1.1: {}
+
   content-disposition@1.1.0: {}
 
   content-type@1.0.5: {}
@@ -15611,6 +15774,11 @@ snapshots:
 
   diff@9.0.0: {}
 
+  dockerfile-ast@0.7.1:
+    dependencies:
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-languageserver-types: 3.18.0
+
   dom-accessibility-api@0.5.16: {}
 
   dompurify@3.4.11:
@@ -15627,6 +15795,20 @@ snapshots:
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  e2b@2.29.1:
+    dependencies:
+      '@bufbuild/protobuf': 2.13.0
+      '@connectrpc/connect': 2.0.0-rc.3(@bufbuild/protobuf@2.13.0)
+      '@connectrpc/connect-web': 2.0.0-rc.3(@bufbuild/protobuf@2.13.0)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0))
+      chalk: 5.6.2
+      compare-versions: 6.1.1
+      dockerfile-ast: 0.7.1
+      glob: 11.1.0
+      openapi-fetch: 0.14.1
+      platform: 1.3.6
+      tar: 7.5.22
+      undici: 7.28.0
+
   eastasianwidth@0.2.0: {}
 
   ecdsa-sig-formatter@1.0.11:
@@ -16089,6 +16271,15 @@ snapshots:
       package-json-from-dist: 1.0.1
       path-scurry: 1.11.1
 
+  glob@11.1.0:
+    dependencies:
+      foreground-child: 3.3.1
+      jackspeak: 4.2.3
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      package-json-from-dist: 1.0.1
+      path-scurry: 2.0.2
+
   globals@17.7.0: {}
 
   globrex@0.1.2: {}
@@ -16258,6 +16449,10 @@ snapshots:
     optionalDependencies:
       '@pkgjs/parseargs': 0.11.0
 
+  jackspeak@4.2.3:
+    dependencies:
+      '@isaacs/cliui': 9.0.0
+
   jiti@2.7.0: {}
 
   jose@6.2.3: {}
@@ -16942,6 +17137,10 @@ snapshots:
 
   minisearch@7.2.0: {}
 
+  minizlib@3.1.0:
+    dependencies:
+      minipass: 7.1.3
+
   mitt@3.0.1: {}
 
   mri@1.2.0: {}
@@ -17062,6 +17261,12 @@ snapshots:
       ws: 8.21.0
       zod: 4.4.3
 
+  openapi-fetch@0.14.1:
+    dependencies:
+      openapi-typescript-helpers: 0.0.15
+
+  openapi-typescript-helpers@0.0.15: {}
+
   optionator@0.9.4:
     dependencies:
       deep-is: 0.1.4
@@ -17194,6 +17399,11 @@ snapshots:
       lru-cache: 10.4.3
       minipass: 7.1.3
 
+  path-scurry@2.0.2:
+    dependencies:
+      lru-cache: 11.5.1
+      minipass: 7.1.3
+
   path-to-regexp@8.4.2: {}
 
   pathe@2.0.3: {}
@@ -17206,6 +17416,8 @@ snapshots:
 
   pkce-challenge@5.0.1: {}
 
+  platform@1.3.6: {}
+
   playwright-core@1.61.1: {}
 
   playwright@1.61.1:
@@ -17659,6 +17871,14 @@ snapshots:
 
   tabbable@6.5.0: {}
 
+  tar@7.5.22:
+    dependencies:
+      '@isaacs/fs-minipass': 4.0.1
+      chownr: 3.0.0
+      minipass: 7.1.3
+      minizlib: 3.1.0
+      yallist: 5.0.0
+
   tinybench@2.9.0: {}
 
   tinyexec@1.2.4: {}
@@ -18092,6 +18312,8 @@ snapshots:
       vscode-jsonrpc: 9.0.1
       vscode-languageserver-types: 3.18.0
 
+  vscode-languageserver-textdocument@1.0.12: {}
+
   vscode-languageserver-types@3.18.0: {}
 
   vue@3.5.39(typescript@6.0.3):
@@ -18163,6 +18385,8 @@ snapshots:
 
   yallist@3.1.1: {}
 
+  yallist@5.0.0: {}
+
   yaml@2.9.0: {}
 
   yocto-queue@0.1.0: {}
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index e254696491..e6d6acbdf2 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -70,6 +70,7 @@ const GROUP_ORDER = [
   'bash',
   'pty',
   'sandbox',
+  'e2b',
   'fs',
   'skill',
   'compact',
@@ -321,12 +322,20 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'core',
     note: 'Folds revisioned objective state from the session log and keeps live continuation activation process-local.',
   },
+  {
+    key: 'e2b',
+    pkg: 'e2b',
+    title: 'E2B sandbox lifecycle owner',
+    mode: 'core',
+    consumers: ['fs-e2b', 'subprocess-e2b'],
+    note: 'Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime.',
+  },
   {
     key: 'subprocess',
     pkg: 'subprocess',
     title: 'Subprocess seam',
     mode: 'seam',
-    implementations: ['subprocess-local'],
+    implementations: ['subprocess-local', 'subprocess-e2b'],
     consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
     note: 'The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
   },
@@ -405,7 +414,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'fs',
     title: 'Filesystem provider seam',
     mode: 'seam',
-    implementations: ['fs-local', 'fs-sandbox'],
+    implementations: ['fs-local', 'fs-sandbox', 'fs-e2b'],
     consumers: ['tool-fs'],
     companions: ['fs-policy'],
     note: 'tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate.',

From 55c0a44bd97113a3437b562df6acfb87a619582d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:11:31 +0800
Subject: [PATCH 139/262] fix(e2b): trim published files to the hardened
 allowlist

Master's publication hardening enforces the exact package files list;
the three E2B manifests still published src and d.ts maps.
---
 packages/e2b/e2b/package.json            | 4 +---
 packages/e2b/fs-e2b/package.json         | 4 +---
 packages/e2b/subprocess-e2b/package.json | 4 +---
 3 files changed, 3 insertions(+), 9 deletions(-)

diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index 82fda6b303..a77e3d9464 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/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": {
diff --git a/packages/e2b/fs-e2b/package.json b/packages/e2b/fs-e2b/package.json
index cc96cba6c9..02925ee7c4 100644
--- a/packages/e2b/fs-e2b/package.json
+++ b/packages/e2b/fs-e2b/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": {
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index fa96e17293..abf3d5973c 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/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": {

From 72419bc33351b659874a7be32b3b74c2053e1815 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:29:14 +0800
Subject: [PATCH 140/262] test(e2b): cover the environment tombstone removal

The serializer's undefined-tombstone branch (from the seam's
NodeJS.ProcessEnv migration) removes an ambient entry; the composition
env test now exercises it against the scrubbed ambient KEEP entry.
---
 packages/e2b/subprocess-e2b/tests/subprocess.spec.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 747dc936c6..d40c69df89 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -388,6 +388,8 @@ describe('E2BSubprocessHandle', () => {
         '--split-string': 'literal-value',
         DEEPSEEK_API_KEY: 'explicit-secret',
         DSH_MODE: 'test',
+        // The seam's tombstone: an explicit undefined removes the ambient entry.
+        KEEP: undefined,
       },
     }), '/workspace/.dsh-e2b/processes/one')
     expect(handle.pid).toBe(-1)
@@ -433,7 +435,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0HOME=/home/user\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0UNICODE=你好\0HOME=/home/user\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''

From e0a31475fc0767f1f081f86de237592ebd5e915d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 00:27:21 +0800
Subject: [PATCH 141/262] chore(rebase): re-record the packages-README pairing
 after the cascade

The parent's round-two replay restored master's pairing record while
this branch's e2b group row changes both sides; re-record the pair.
---
 packages/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 7e74d63f31..143e7704c2 100644
--- 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: 1516c20ff55f366fe6af6b0be5495958708f29e3
-README.zh.md: 42f4d2b8d924b19fd3cde863dafb8c59d9c078cf
+README.md: 98fc87a6b26a42c58bb63cba96cd6af384f3ec71
+README.zh.md: 86a316dca77efd5e5eb59e3fca7d53890a34901d

From 0569437ff3219757001c3d7501d88f24172a7575 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:16:24 +0800
Subject: [PATCH 142/262] chore(rebase): regenerate third-party notices and the
 module graph

Master turned THIRD_PARTY_NOTICES.md into generator output (the branch's
hand-added e2b row carried a stale dotenv entry), and the cascade's
ours-side resolution flattened the module graph to the parent's content;
both regenerate from the current tree.
---
 THIRD_PARTY_NOTICES.md |  1 -
 docs/module-graph.md   | 15 +++++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 9060950bea..48f04c9799 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -57,7 +57,6 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
-| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
 | [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 38a85a508a..91d584466b 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -204,6 +204,11 @@ flowchart TD
     pkg_credentials["credentials"]
     pkg_credentials_local["credentials-local"]
   end
+  subgraph group_e2b["packages/e2b"]
+    pkg_e2b["e2b"]
+    pkg_fs_e2b["fs-e2b"]
+    pkg_subprocess_e2b["subprocess-e2b"]
+  end
   subgraph group_examples["packages/examples"]
     pkg_acp_demo["acp-demo"]
     pkg_agent_spine_demo["agent-spine-demo"]
@@ -309,6 +314,7 @@ flowchart TD
   pkg_client_web --> pkg_invariants
   pkg_client_web_react --> pkg_invariants
   pkg_code_runtime --> pkg_invariants
+  pkg_e2b --> pkg_invariants
   pkg_jsonrpc_demo --> pkg_invariants
   pkg_host_apiproxy --> pkg_invariants
   pkg_host_directory_picker --> pkg_invariants
@@ -331,6 +337,9 @@ flowchart TD
   pkg_client_runtime --> pkg_typert_registry
   pkg_credentials --> pkg_brand
   pkg_credentials --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_e2b
+  pkg_subprocess_e2b --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_subprocess
   pkg_frontend_static --> pkg_host_webserver
   pkg_frontend_static --> pkg_invariants
   pkg_helper --> pkg_brand
@@ -591,6 +600,9 @@ flowchart TD
   pkg_tmux_context --> pkg_bash
   pkg_tmux_context --> pkg_invariants
   pkg_tmux_context --> pkg_session
+  pkg_fs_e2b --> pkg_e2b
+  pkg_fs_e2b --> pkg_fs
+  pkg_fs_e2b --> pkg_invariants
   pkg_host_directory_picker_browse --> pkg_client_locale
   pkg_host_directory_picker_browse --> pkg_client_runtime
   pkg_host_directory_picker_browse --> pkg_client_ui_primitives
@@ -1181,6 +1193,7 @@ flowchart TD
 | [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-web-react`](../packages/client/web-react) | `client` | [`invariants`](../packages/support/invariants) |
 | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/support/invariants) |
+| [`e2b`](../packages/e2b/e2b) | `e2b` | [`invariants`](../packages/support/invariants) |
 | [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | [`invariants`](../packages/support/invariants) |
 | [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker`](../packages/host/directory-picker) | `host` | [`invariants`](../packages/support/invariants) |
@@ -1195,6 +1208,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
@@ -1264,6 +1278,7 @@ flowchart TD
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |

From 10fc9405c772bbb75868d62d04487f3f529dabb4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:29:10 +0800
Subject: [PATCH 143/262] docs(e2b): re-home the overlay section on master's
 README

Master rewrote the headless README around the profile CLI and removed
cli-demo; the replay had resurrected the old body. The branch's claim is
the E2B overlay section alone, now inserted into master's text with the
credential-gated live composition e2e as the runnable instruction (the
config-file demo runner no longer exists).
---
 examples/headless-agent/README.i18n.yaml |  4 ++--
 examples/headless-agent/README.md        | 22 +++++++++-------------
 examples/headless-agent/README.zh.md     | 22 +++++++++-------------
 3 files changed, 20 insertions(+), 28 deletions(-)

diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index 56c02d3e0a..4a71194e5f 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/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 examples/headless-agent/README.md
-README.md: 16c45d304eb0f06a2b062518b053db683cd402c0
-README.zh.md: 72d2813d174e74a3bf93c363b268499a44f1cd4f
+README.md: 6e80e56dec70c2be341ae5dfbad70e13a5109715
+README.zh.md: ea8c41b9ae75f0cee3edd78e59408f37c19182d3
diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md
index 16c45d304e..6e80e56dec 100644
--- a/examples/headless-agent/README.md
+++ b/examples/headless-agent/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence, with [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) as the app front door.
+This directory owns the replay and real-model test composition for a headless coding agent: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence. It explicitly mounts the shared agent spine, one root agent, persistence, and checkpoint policy; it is not a second product front door.
 
 ## Run it
 
@@ -10,27 +10,23 @@ Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools +
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run demo:headless "fix the failing test in this workspace"
-pnpm run demo:headless --output-format json -- "summarize the implementation"
-pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+pnpm run dsh run "fix the failing test in this workspace"
 ```
 
-Exactly one nonblank positional task is required; quote tasks containing spaces. There is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the top-level session's canonical task-turn events before that record. Child sessions surface only through parent tool events and results.
+The product command is [`dsh run`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
 
-Each invocation creates and persists a fresh session, runs all model and tool steps in one turn, flushes, disposes, and exits. This is non-interactive automation: there is no prompt, approval, resume, second turn, or stdin context. The configured tools can mutate the launch workspace, run commands, spawn child agents, and consume provider tokens.
+Snapshot suites run this directory's configuration through [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts), an unexported test-only process that emits canonical session events as JSONL before its result record. That stream is test infrastructure, not a supported CLI output format. Child sessions surface only through parent tool events and results.
 
 ## E2B POC overlay
 
-[`e2b.cordis.yml`](e2b.cordis.yml) replaces the local filesystem and subprocess providers with one shared E2B sandbox while retaining `dsh-bash-local` and the same model-facing tools. Put `E2B_API_KEY` beside `DEEPSEEK_API_KEY` in the gitignored root `.env`, then run:
+[`e2b.cordis.yml`](e2b.cordis.yml) replaces the local filesystem and subprocess providers with one shared E2B sandbox while retaining `dsh-bash-local` and the same model-facing tools. Put `E2B_API_KEY` beside `DEEPSEEK_API_KEY` in the gitignored root `.env`, then run the credential-gated live composition, which drives FS, Bash, PTY, and LSP in one sandbox and proves final deletion:
 
 ```sh
-pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+pnpm exec vitest run --config vitest.e2e.config.ts packages/e2b/e2b/tests/composition.e2e.ts
 ```
 
-The overlay creates the same absolute cwd inside the sandbox, but it does not upload or mount the host workspace. File and Bash mutations exist only in E2B; Cordis, model calls, agent/session state, session logs, skills, and SDK buffers remain on the host. The demo kills its sandbox on timeout and disposal. It is a provider-composition POC, not a whole-harness migration or a workspace-sync feature.
+The overlay creates the same absolute cwd inside the sandbox, but it does not upload or mount the host workspace. File and Bash mutations exist only in E2B; Cordis, model calls, agent/session state, session logs, skills, and SDK buffers remain on the host. The composition kills its sandbox on timeout and disposal. It is a provider-composition POC, not a whole-harness migration or a workspace-sync feature.
 
-## Advanced and snapshot wiring
+## Advanced configuration
 
-[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the shipped leaf. [`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) replaces only the live LLM with replay. The tests under [`tests/`](tests/) own the keyless real-Loader smoke, key-gated world-verified smoke, and the `stream-json` replay snapshot with its parent and child session fixtures.
-
-The package-level [CLI contract](../../packages/examples/cli-demo/README.md) documents output records, exit status, cancellation, persistence, and model/token effects.
+[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the test composition.
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index 72d2813d17..ea8c41b9ae 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-无头单次 agent（智能体）接线：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与新 agent Ralph 迭代 + `todo_write` + JSONL 持久化，并以 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) 作为应用入口。
+本目录负责 headless coding agent（智能体）的回放和真实模型测试组装：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与全新 agent Ralph 迭代 + `todo_write` + JSONL 持久化。本目录显式挂载共享 agent 主干、一个根 agent、持久化和检查点策略；它不是第二个产品入口。
 
 ## 运行
 
@@ -10,27 +10,23 @@
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run demo:headless "fix the failing test in this workspace"
-pnpm run demo:headless --output-format json -- "summarize the implementation"
-pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+pnpm run dsh run "fix the failing test in this workspace"
 ```
 
-必须提供且只能提供一个非空位置任务；含空格的任务需要加引号。没有 `-p` 标志。`text` 打印最后一条包含文本的 assistant 消息，`json` 打印一条 DSH 原生结果记录，`stream-json` 则在该记录之前发出顶层会话的规范任务轮次事件。子会话只通过父工具事件和结果对外显示。
+产品命令是 [`dsh run`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
 
-每次调用都会创建并持久化新会话，在一个轮次中运行所有模型和工具步骤，然后刷新、释放并退出。这是非交互式自动化：没有提示符、批准、恢复、第二轮次或 stdin 上下文。已配置工具可以修改启动 workspace、运行命令、spawn 子 agent，并消耗提供方 token。
+快照套件通过 [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts) 运行本目录的配置。这个未导出且仅供测试使用的进程会在结果记录之前，以 JSONL 发出规范会话事件。该事件流属于测试基础设施，不是受支持的 CLI（命令行界面）输出格式。子会话只通过父会话的工具事件和结果对外显示。
 
 ## E2B POC overlay
 
-[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行：
+[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行凭据门控的实机组合测试；它在同一个沙箱中驱动 FS、Bash、PTY 和 LSP，并证明沙箱最终被删除：
 
 ```sh
-pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+pnpm exec vitest run --config vitest.e2e.config.ts packages/e2b/e2b/tests/composition.e2e.ts
 ```
 
-该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。演示会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
+该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。该组合会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
 
-## 高级与快照接线
+## 高级配置
 
-[`advanced.cordis.yml`](advanced.cordis.yml) 在已交付叶节点上添加 Code Mode 和 Cordis 工具。[`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) 只将实时 LLM（大语言模型）替换为回放。[`tests/`](tests/) 下的测试拥有无密钥真实 Loader 冒烟测试、密钥门控的外部状态验证冒烟测试，以及带父子会话 fixture（测试前置数据）的 `stream-json` 回放快照。
-
-包级 [CLI 契约](../../packages/examples/cli-demo/README.md)记录输出记录、退出状态、取消、持久化以及模型／token 影响。
+[`advanced.cordis.yml`](advanced.cordis.yml) 在测试组装中添加 Code Mode 和 Cordis 工具。

From 450ec99325ebef5d21fdcae1a0ef62b98027dd68 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 22:37:38 +0800
Subject: [PATCH 144/262] fix(e2b): address the v7 review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- restore the parent's AGENTS.md body around this branch's e2b row (the
  replay had resurrected the pre-profile-CLI layout, deleting the api/,
  bundle/, settings/, and credentials/ groups); the fs/lsp row
  condensations stay for the word budget
- aggregate the composite rollback failure, not the original error, when
  private state cleanup also fails — a surviving remote group is no
  longer hidden by a later cleanup error (triple-failure regression)
- own the state directory before the makeDir RPC, matching the terminal
  transaction, so a cancellation racing a committed creation still
  enters cleanup
- drop the hidden pollMs parameter defaults; the schemastery default is
  the one home, and tests pass the cadence explicitly
- restore spawn/spawnTerminal graceMs validation to the seam's
  documented bound (the earlier removal cited subprocess-local as not
  validating; it does), with rejection regressions
---
 AGENTS.md                                     |  19 +-
 docs/config-catalog.md                        |   2 +-
 docs/module-graph.md                          |   3 +-
 packages/e2b/subprocess-e2b/package.json      |   2 +
 packages/e2b/subprocess-e2b/src/index.ts      |  15 ++
 packages/e2b/subprocess-e2b/src/process.ts    |   8 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   |   2 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 190 +++++++++++-------
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  96 +++++----
 packages/e2b/subprocess-e2b/tsconfig.json     |  15 +-
 pnpm-lock.yaml                                |   3 +
 11 files changed, 218 insertions(+), 137 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 87f545ee86..61812e586c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,10 +12,11 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
+  api/         Remote BFF assembly and TypeRT RPC gateway
   typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
   e2b/         E2B POC: sandbox + FS/subprocess adapters
-  bash/        bash executor seam + local impl + model-facing bash tools
+  bash/        bash executor seam + local/pwsh impls + model-facing shell tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
   fs/          filesystem seam/backends/policy/tools
@@ -25,6 +26,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   compact/     compaction seam + basic backend
   context/     request-context plugins
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
+  bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
   plan/        plan mode as logged per-agent collaboration state
@@ -32,9 +34,11 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
   session-persistence/  persistence seam + JSONL/SQLite backends
+  settings/    user-settings seam + file-backed provider
+  credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
-  ui/          TUI/JSON-RPC bridges; boot, approval, interaction plugins
-  examples/    demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load
+  ui/          JSON-RPC bridge; boot, approval, interaction plugins
+  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
@@ -56,7 +60,7 @@ pnpm run clean           # remove build outputs and safe residue from deleted pa
 pnpm run test           # vitest unit tests
 pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src
 pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
-pnpm run test:snapshot  # keyless ACP/headless/TUI replay vs expected outputs; filter: -t <name>
+pnpm run test:snapshot  # keyless ACP/headless replay vs expected outputs; filter: -t <name>
 pnpm run test:snapshot:record  # re-record expected outputs (needs key)
 pnpm run typecheck
 pnpm run lint
@@ -67,7 +71,6 @@ pnpm run hygiene        # knip + publint + workspace constraints + NodeNext cons
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm run demo:headless "task" # one-shot agent (needs DEEPSEEK_API_KEY)
-pnpm run demo:tui       # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis    # the agent modifies its own runtime (needs key)
 pnpm run demo:acp       # ACP automation server (needs DEEPSEEK_API_KEY)
 ```
@@ -78,7 +81,7 @@ When required `gh`, `pnpm`, build, test, or generator commands fail because the
 
 ### Run relevant checks locally
 
-Agents MUST run relevant tests and checks before pushing; select them with [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md) and report only commands run.
+Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
 
 - Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
 - Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
@@ -91,7 +94,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). TUI/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
@@ -115,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
-- **Use incremental merge commits.** Split independent changes. Pushed history may be rewritten before review; afterward prefer new commits. Fix the introducing PR before merging down-stack. If the base advances mid-merge, finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
+- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
 - **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 58b319d662..c74358fd39 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1841,7 +1841,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/e2b/subprocess-e2b/src/index.ts:24`](../packages/e2b/subprocess-e2b/src/index.ts)
+Source: [`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts)
 
 ## `@deepseek-ai/dsh-system-prompt`
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 91d584466b..2e71473379 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -340,6 +340,7 @@ flowchart TD
   pkg_subprocess_e2b --> pkg_e2b
   pkg_subprocess_e2b --> pkg_invariants
   pkg_subprocess_e2b --> pkg_subprocess
+  pkg_subprocess_e2b --> pkg_timeout
   pkg_frontend_static --> pkg_host_webserver
   pkg_frontend_static --> pkg_invariants
   pkg_helper --> pkg_brand
@@ -1208,7 +1209,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
-| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index abf3d5973c..007b88f1c9 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/package.json
@@ -28,6 +28,7 @@
     "@deepseek-ai/dsh-e2b": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -37,6 +38,7 @@
     "@deepseek-ai/dsh-e2b": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 38b1d32465..c6d2dbd4eb 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -9,6 +9,7 @@ import { posix } from 'node:path'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   SubprocessHandle,
   SubprocessSpawnSpec,
@@ -35,6 +36,18 @@ interface TerminalSetup {
   controller: AbortController
 }
 
+/**
+ * Enforce the seam's documented grace bound (positive, finite, one Node timer),
+ * matching subprocess-local's spawn-time check; an unbounded grace would make
+ * the remote force-escalation deadline unreachable.
+ * @param graceMs - The spec's cleanup grace in milliseconds.
+ */
+function requireRepresentableGrace(graceMs: number): void {
+  if (!Number.isFinite(graceMs) || graceMs <= 0 || graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+}
+
 /** E2B command manager registered as `ctx.subprocess`. */
 export class E2BSubprocessService extends SubprocessService {
   static inject = ['e2b']
@@ -130,6 +143,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
     }
+    requireRepresentableGrace(spec.graceMs)
     if (spec.signal?.aborted === true) {
       throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
     }
@@ -153,6 +167,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
     }
+    requireRepresentableGrace(spec.graceMs)
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
     const done = Promise.withResolvers<void>()
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index feb21a70bc..c80a2f5bd9 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -194,7 +194,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     private readonly runtime: E2BSandboxService,
     private readonly spec: SubprocessSpawnSpec,
     readonly stateDir: string,
-    private readonly pollMs = 20,
+    private readonly pollMs: number,
   ) {
     this.paths = {
       pid: posix.join(stateDir, 'pid'),
@@ -378,7 +378,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           await this.removeFailedState(sandbox)
         } catch (cleanupError: unknown) {
           failure = new AggregateError(
-            [error, cleanupError],
+            [failure, cleanupError],
             'subprocess-e2b: command failed and private state cleanup failed',
           )
         }
@@ -398,8 +398,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const signal = this.terminationController.signal
     const ambient = await readRemoteEnvironment(sandbox, signal)
     this.controlEnvs = bootstrapEnvironment(ambient)
-    await sandbox.files.makeDir(this.stateDir, { signal })
+    // Own the directory before the request: a cancellation racing a committed
+    // creation must still enter cleanup (removal tolerates an absent path).
     this.stateDirectoryCreated = true
+    await sandbox.files.makeDir(this.stateDir, { signal })
     await sandbox.commands.run(
       `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
       commandOpts(this.controlEnvs, signal),
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index fd10ecdd8e..c8f3bb57b7 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -459,7 +459,7 @@ export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
-  pollMs = 20,
+  pollMs: number,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index d40c69df89..153b144ccd 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -324,6 +324,16 @@ async function flush(): Promise<void> {
   await new Promise(resolve => setTimeout(resolve, 0))
 }
 
+/** Construct the handle under test with the config default the service would pass. */
+function testHandle(
+  runtime: ConstructorParameters<typeof E2BSubprocessHandle>[0],
+  spec: ConstructorParameters<typeof E2BSubprocessHandle>[1],
+  stateDir: string,
+  pollMs = 20,
+): E2BSubprocessHandle {
+  return new E2BSubprocessHandle(runtime, spec, stateDir, pollMs)
+}
+
 describe('E2BOutputReader', () => {
   it('decodes base64 across arbitrary callback boundaries and rejects malformed framing', () => {
     const decoder = new E2BBase64Decoder()
@@ -379,7 +389,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.processGroupId = '4343\n'
     fake.deferStart()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       argv: ['tool', 'argument with spaces'],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
       env: {
@@ -450,10 +460,23 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('rejects an unrepresentable graceMs before any remote work', () => {
+    const ctx = new Context()
+    const service = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+    Reflect.set(service, 'disposing', false)
+    Reflect.set(service, 'ctx', ctx)
+    for (const graceMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(() => service.spawn(spec({ graceMs }))).toThrow('graceMs must be a positive finite number')
+      void expect(service.spawnTerminal({
+        argv: ['bash'], cwd: '/w', rows: 24, cols: 80, graceMs,
+      })).rejects.toThrow('graceMs must be a positive finite number')
+    }
+  })
+
   it('rejects malformed environment entries before command start', async () => {
     for (const env of [{ 'BAD=NAME': 'x' }, { BAD: 'x\0INJECTED=1' }]) {
       const fake = new FakeSandbox()
-      const handle = new E2BSubprocessHandle(runtime(fake), spec({ env }), '/runtime/invalid-environment')
+      const handle = testHandle(runtime(fake), spec({ env }), '/runtime/invalid-environment')
       await expect(handle.done).rejects.toThrow('environment entries')
       expect(fake.startOptions).toBeUndefined()
       expect(fake.removed).toContain('/runtime/invalid-environment')
@@ -462,7 +485,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('preserves UTF-8 bytes when the ASCII transport is split across callbacks', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/split-utf8')
     await flush()
@@ -478,14 +501,14 @@ describe('E2BSubprocessHandle', () => {
 
   it('rejects malformed output transport without confusing it with a consumer sink failure', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/malformed-output')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/malformed-output')
     await flush()
     await fake.stdoutWire('%\n')
     fake.finish()
     await expect(handle.done).rejects.toThrow('invalid base64 output transport')
 
     const stderrFake = new FakeSandbox()
-    const stderrHandle = new E2BSubprocessHandle(runtime(stderrFake), spec(), '/runtime/malformed-stderr')
+    const stderrHandle = testHandle(runtime(stderrFake), spec(), '/runtime/malformed-stderr')
     await flush()
     await stderrFake.stderrWire('%\n')
     stderrFake.finish()
@@ -494,7 +517,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('rejects a naturally completed command whose encoder omits its completion frame', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/incomplete-output')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/incomplete-output')
     await flush()
     fake.alive = false
     fake.handle.succeed(0)
@@ -503,7 +526,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('bounds descendant-held output draining and withholds the incomplete spill', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-bound')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-bound')
     await flush()
     await fake.stdout('leader-output')
     fake.exitStatus = '0\n'
@@ -529,7 +552,7 @@ describe('E2BSubprocessHandle', () => {
       return false
     }) as typeof process.stdout.write)
     try {
-      const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      const handle = testHandle(runtime(fake), spec({
         graceMs: 5,
         stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4 } },
       }), '/runtime/inherit-backpressure')
@@ -555,7 +578,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('waits for lossless raw-pipe output after the direct status is published', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       graceMs: 1,
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/pipe-drain')
@@ -580,7 +603,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('accepts clean encoder completion inside the output-drain grace', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
     await flush()
     fake.exitStatus = '0\n'
     fake.afterStatusRead = () => {
@@ -598,7 +621,7 @@ describe('E2BSubprocessHandle', () => {
     fake.delaysKill = true
     fake.delaysKillCompletion = true
     fake.sdkKillStops = false
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-signal')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-signal')
     await flush()
 
     handle.terminate()
@@ -614,7 +637,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('preserves a published nonzero exit code when termination settles the SDK inside the drain grace', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-signal-settled')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-signal-settled')
     await flush()
     fake.exitStatus = '7\n'
     fake.afterStatusRead = () => {
@@ -628,7 +651,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('rejects an invalid direct-command exit status', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/invalid-status')
     await flush()
     fake.exitStatus = '999\n'
     await expect(handle.done).rejects.toThrow('invalid exit code')
@@ -639,7 +662,7 @@ describe('E2BSubprocessHandle', () => {
   it('rolls back a published process group before rejecting a monitoring failure', async () => {
     const fake = new FakeSandbox()
     fake.statusError = new Error('status transport failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/status-failure')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/status-failure')
 
     await expect(handle.done).rejects.toThrow('status transport failed')
     expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
@@ -650,7 +673,7 @@ describe('E2BSubprocessHandle', () => {
     failed.statusError = new Error('status transport failed')
     failed.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     failed.handle.killError = new Error('SDK kill failed')
-    const retained = new E2BSubprocessHandle(runtime(failed), spec({ graceMs: 1 }), '/runtime/status-cleanup-failure')
+    const retained = testHandle(runtime(failed), spec({ graceMs: 1 }), '/runtime/status-cleanup-failure')
 
     await expect(retained.done).rejects.toThrow(
       'command monitoring failed and process-group rollback did not reach quiescence',
@@ -659,13 +682,30 @@ describe('E2BSubprocessHandle', () => {
     failed.handle.killError = undefined
     retained.terminate()
     await expect(retained.waitForExit()).resolves.toBe(true)
+
+    // A state-cleanup failure on top preserves the rollback failure instead of
+    // re-aggregating only the original monitoring error.
+    const triple = new FakeSandbox()
+    triple.statusError = new Error('status transport failed')
+    triple.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    triple.handle.killError = new Error('SDK kill failed')
+    triple.nextRemoveError = new Error('state cleanup failed')
+    const tripleHandle = testHandle(runtime(triple), spec({ graceMs: 1 }), '/runtime/triple-failure')
+    const failure = await tripleHandle.done.catch((error: unknown) => error as AggregateError)
+    expect(failure).toBeInstanceOf(AggregateError)
+    expect((failure as AggregateError).message).toContain('private state cleanup failed')
+    const nested = (failure as AggregateError).errors[0] as AggregateError
+    expect(nested.message).toContain('rollback did not reach quiescence')
+    triple.handle.killError = undefined
+    tripleHandle.terminate()
+    await expect(tripleHandle.waitForExit()).resolves.toBe(true)
   })
 
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
     vi.spyOn(writeFake.handle, 'sendStdin').mockRejectedValueOnce('stdin rejected')
-    const writeHandle = new E2BSubprocessHandle(runtime(writeFake), spec({
+    const writeHandle = testHandle(runtime(writeFake), spec({
       stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
     }), '/runtime/stdin-write-error')
     const writeError = once(writeHandle.stdin!, 'error')
@@ -677,7 +717,7 @@ describe('E2BSubprocessHandle', () => {
 
     const closeFake = new FakeSandbox()
     vi.spyOn(closeFake.handle, 'closeStdin').mockRejectedValueOnce(new Error('close rejected'))
-    const closeHandle = new E2BSubprocessHandle(runtime(closeFake), spec({
+    const closeHandle = testHandle(runtime(closeFake), spec({
       stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
     }), '/runtime/stdin-close-error')
     await flush()
@@ -690,7 +730,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('collects bounded tails, retains valid spills, and maps natural nonzero exits', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: {
         stdin: { data: 'batch' },
         stdout: { maxBytes: 4, spill: { maxBytes: 16 } },
@@ -716,7 +756,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('removes a spill once the complete stream exceeds its cap', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: { maxBytes: 2, spill: { maxBytes: 3 } }, stderr: 'inherit' },
     }), '/runtime/oversize')
     await flush()
@@ -736,7 +776,7 @@ describe('E2BSubprocessHandle', () => {
   it('contains remote spill-removal failures and routes empty inherited output', async () => {
     const fake = new FakeSandbox()
     fake.nextRemoveError = new Error('already removed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4, spill: { maxBytes: 8 } } },
     }), '/runtime/remove-error')
     await flush()
@@ -749,7 +789,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('terminates a process group with TERM and reports the signal outcome', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/term')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/term')
     await flush()
     handle.terminate()
     handle.terminate()
@@ -767,7 +807,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('makes termination a permanent no-op after natural quiescence is observed', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/natural-quiescence')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/natural-quiescence')
     await flush()
     fake.finish()
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
@@ -784,7 +824,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats a zombie-only process group as quiescent', async () => {
     const fake = new FakeSandbox()
     fake.zombieOnly = true
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/zombie-quiescence')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/zombie-quiescence')
     await flush()
 
     await expect(handle.waitForExit()).resolves.toBe(true)
@@ -800,7 +840,7 @@ describe('E2BSubprocessHandle', () => {
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     fake.handle.killError = new Error('SDK kill failed')
     fake.deferSignals()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/quiescent-race')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/quiescent-race')
     await flush()
 
     handle.terminate()
@@ -823,7 +863,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
     fake.handle.killError = new Error('already gone')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/kill')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/kill')
     await flush()
     handle.terminate()
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
@@ -838,7 +878,7 @@ describe('E2BSubprocessHandle', () => {
     fake.delaysKill = true
     fake.delaysKillCompletion = true
     fake.sdkKillStops = false
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/termination-fence')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/termination-fence')
     await flush()
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
@@ -856,7 +896,7 @@ describe('E2BSubprocessHandle', () => {
   it('honors termination requested before asynchronous startup finishes', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/deferred-kill')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/deferred-kill')
     handle.terminate()
     fake.releaseStart()
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
@@ -879,7 +919,7 @@ describe('E2BSubprocessHandle', () => {
         signal?.addEventListener('abort', rejectAbort, { once: true })
       })
     }
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/stalled-preparation')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/stalled-preparation')
     await vi.waitFor(() => { expect(preparationSignal).toBeDefined() })
 
     handle.terminate()
@@ -893,7 +933,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.deferProcessGroupRead()
     fake.signalErrors.push(commandError(1), commandError(1))
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/pre-publication-kill')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/pre-publication-kill')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -913,7 +953,7 @@ describe('E2BSubprocessHandle', () => {
     fake.delaysKillCompletion = true
     fake.sdkKillStops = false
     fake.handle.killResult = false
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/provisional-sdk-false')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/provisional-sdk-false')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -936,7 +976,7 @@ describe('E2BSubprocessHandle', () => {
       calls += 1
       return calls === 1 ? fake.sandbox : await reconnect.promise
     })
-    const handle = new E2BSubprocessHandle(delayedRuntime, spec(), '/runtime/pre-publication-observer')
+    const handle = testHandle(delayedRuntime, spec(), '/runtime/pre-publication-observer')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
     handle.terminate()
 
@@ -957,7 +997,7 @@ describe('E2BSubprocessHandle', () => {
     fake.deferProcessGroupRead()
     fake.trapsTerm = true
     fake.handle.killError = new Error('SDK kill unavailable')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-group-kill')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-group-kill')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -971,7 +1011,7 @@ describe('E2BSubprocessHandle', () => {
     fake.deferProcessGroupRead()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     fake.handle.killError = new Error('SDK kill failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-failure')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-failure')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -987,7 +1027,7 @@ describe('E2BSubprocessHandle', () => {
     absentGroup.deferProcessGroupRead()
     absentGroup.signalErrors.push(commandError(1), commandError(1))
     absentGroup.handle.killError = new Error('SDK kill failed without a provisional group')
-    const absentHandle = new E2BSubprocessHandle(
+    const absentHandle = testHandle(
       runtime(absentGroup),
       spec({ graceMs: 1 }),
       '/runtime/pre-publication-absent-group',
@@ -1005,7 +1045,7 @@ describe('E2BSubprocessHandle', () => {
     optimisticSdk.deferProcessGroupRead()
     optimisticSdk.signalErrors.push(commandError(1), commandError(1))
     optimisticSdk.sdkKillStops = false
-    const optimisticHandle = new E2BSubprocessHandle(
+    const optimisticHandle = testHandle(
       runtime(optimisticSdk),
       spec({ graceMs: 1 }),
       '/runtime/pre-publication-optimistic-sdk',
@@ -1021,14 +1061,14 @@ describe('E2BSubprocessHandle', () => {
 
   it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
+    const handle = testHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
   it('reacts to a signal that aborts after the remote command has started', async () => {
     const fake = new FakeSandbox()
     const controller = new AbortController()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: controller.signal }), '/runtime/live-abort')
+    const handle = testHandle(runtime(fake), spec({ signal: controller.signal }), '/runtime/live-abort')
     await flush()
     controller.abort('stop')
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
@@ -1036,7 +1076,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('can terminate a surviving process group after the command leader settles', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/surviving-group')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/surviving-group')
     await flush()
     await fake.completeOutput()
     fake.handle.succeed(0)
@@ -1054,7 +1094,7 @@ describe('E2BSubprocessHandle', () => {
   it('bounds waitForExit while startup or a live group is pending', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/wait')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/wait')
     const beforeStart = new AbortController()
     const pending = handle.waitForExit(beforeStart.signal)
     beforeStart.abort()
@@ -1071,7 +1111,7 @@ describe('E2BSubprocessHandle', () => {
 
     const terminatingFake = new FakeSandbox()
     terminatingFake.deferStart()
-    const terminating = new E2BSubprocessHandle(runtime(terminatingFake), spec(), '/runtime/wait-termination-start')
+    const terminating = testHandle(runtime(terminatingFake), spec(), '/runtime/wait-termination-start')
     terminating.terminate()
     const beforeHandle = new AbortController()
     const handlePending = terminating.waitForExit(beforeHandle.signal)
@@ -1083,7 +1123,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('bounds both sides of the liveness-poll abort race', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-abort')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/poll-abort')
     await flush()
 
     const beforeTick = new AbortController()
@@ -1114,7 +1154,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('observes a live group across one successful bounded poll', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-success')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/poll-success')
     await flush()
     setTimeout(() => { fake.finish() }, 1)
     await expect(handle.waitForExit(new AbortController().signal)).resolves.toBe(true)
@@ -1124,7 +1164,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats startup failure as no live tree and contains readiness rejection', async () => {
     const fake = new FakeSandbox()
     fake.backgroundError = new Error('start failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/fail')
     await expect(handle.done).rejects.toThrow('start failed')
     expect(handle.pid).toBe(-1)
     expect(fake.removed).toContain('/runtime/fail/environment')
@@ -1132,7 +1172,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
     handle.terminate()
 
-    const unavailableHandle = new E2BSubprocessHandle(
+    const unavailableHandle = testHandle(
       runtime(new FakeSandbox(), async () => { throw new Error('sandbox unavailable') }),
       spec(),
       '/runtime/unavailable-start',
@@ -1142,14 +1182,14 @@ describe('E2BSubprocessHandle', () => {
 
     const envFailure = new FakeSandbox()
     envFailure.envError = new Error('ambient lookup failed')
-    const envHandle = new E2BSubprocessHandle(runtime(envFailure), spec(), '/runtime/env-failure')
+    const envHandle = testHandle(runtime(envFailure), spec(), '/runtime/env-failure')
     await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
     expect(envFailure.removed).toEqual([])
 
     const expectEnvironmentFailure = async (name: string, wire: string, message: string): Promise<void> => {
       const fake = new FakeSandbox()
       fake.environmentWire = wire
-      const failed = new E2BSubprocessHandle(runtime(fake), spec(), `/runtime/${name}`)
+      const failed = testHandle(runtime(fake), spec(), `/runtime/${name}`)
       await expect(failed.done).rejects.toThrow(message)
     }
     const encodedEnvironment = Buffer.from('PATH=/bin\0').toString('base64')
@@ -1180,13 +1220,13 @@ describe('E2BSubprocessHandle', () => {
     const cleanupFailure = new FakeSandbox()
     cleanupFailure.backgroundError = new Error('start failed before credential consumption')
     cleanupFailure.nextRemoveError = new Error('credential cleanup failed')
-    const cleanupHandle = new E2BSubprocessHandle(runtime(cleanupFailure), spec(), '/runtime/cleanup-failure')
+    const cleanupHandle = testHandle(runtime(cleanupFailure), spec(), '/runtime/cleanup-failure')
     await expect(cleanupHandle.done).rejects.toThrow('command failed and private state cleanup failed')
 
     const absentState = new FakeSandbox()
     absentState.backgroundError = new Error('start failed after external cleanup')
     absentState.nextRemoveError = new FileNotFoundError('already removed')
-    const absentHandle = new E2BSubprocessHandle(runtime(absentState), spec(), '/runtime/absent-state')
+    const absentHandle = testHandle(runtime(absentState), spec(), '/runtime/absent-state')
     await expect(absentHandle.done).rejects.toThrow('start failed after external cleanup')
   })
 
@@ -1194,7 +1234,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.deferStart()
     fake.backgroundError = new Error('start failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail-with-signal')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/fail-with-signal')
     const waiting = handle.waitForExit(new AbortController().signal)
     fake.releaseStart()
     await expect(handle.done).rejects.toThrow('start failed')
@@ -1209,7 +1249,7 @@ describe('E2BSubprocessHandle', () => {
       if (calls === 1) return fake.sandbox
       throw new Error('connection unavailable')
     })
-    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/unavailable')
+    const handle = testHandle(unavailable, spec(), '/runtime/unavailable')
     await flush()
     await expect(handle.waitForExit()).rejects.toThrow('connection unavailable')
     fake.finish()
@@ -1224,7 +1264,7 @@ describe('E2BSubprocessHandle', () => {
       calls += 1
       return calls === 1 ? fake.sandbox : await reconnect.promise
     })
-    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/reconnect-abort')
+    const handle = testHandle(unavailable, spec(), '/runtime/reconnect-abort')
     await flush()
     const controller = new AbortController()
     const waiting = handle.waitForExit(controller.signal)
@@ -1238,7 +1278,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('returns false when a liveness request itself is aborted and surfaces other probe failures', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/probe')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/probe')
     await flush()
     const controller = new AbortController()
     controller.abort()
@@ -1251,7 +1291,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('treats a timeout-killed sandbox as quiescent during liveness probing', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/expired-sandbox')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/expired-sandbox')
     await flush()
     fake.finish()
     await handle.done
@@ -1263,7 +1303,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats a missing sandbox handle as quiescent during liveness acquisition', async () => {
     const fake = new FakeSandbox()
     let calls = 0
-    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+    const handle = testHandle(runtime(fake, async () => {
       calls += 1
       if (calls === 1) return fake.sandbox
       throw new SandboxNotFoundError('sandbox expired')
@@ -1280,7 +1320,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats sandbox loss during termination as quiescent', async () => {
     const fake = new FakeSandbox()
     let calls = 0
-    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+    const handle = testHandle(runtime(fake, async () => {
       calls += 1
       if (calls === 1) return fake.sandbox
       throw new SandboxNotFoundError('sandbox expired')
@@ -1298,7 +1338,7 @@ describe('E2BSubprocessHandle', () => {
   it('makes batch stdin close failures best-effort', async () => {
     const fake = new FakeSandbox()
     vi.spyOn(fake.handle, 'sendStdin').mockRejectedValueOnce(new Error('closed'))
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: { data: 'ignored' }, stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
     }), '/runtime/stdin-closed')
     await flush()
@@ -1309,7 +1349,7 @@ describe('E2BSubprocessHandle', () => {
   it('rejects malformed SDK process ids and non-command settlement failures', async () => {
     const invalidPid = new FakeSandbox()
     invalidPid.handle.pid = 0
-    const invalid = new E2BSubprocessHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
+    const invalid = testHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
     await expect(invalid.done).rejects.toThrow(/invalid command pid 0/)
     expect(invalidPid.handle.kills).toBe(1)
     expect(invalidPid.removed).toContain('/runtime/invalid-pid/environment')
@@ -1318,7 +1358,7 @@ describe('E2BSubprocessHandle', () => {
     const failedRollback = new FakeSandbox()
     failedRollback.handle.pid = 0
     failedRollback.handle.killError = new Error('invalid handle kill failed')
-    const retained = new E2BSubprocessHandle(runtime(failedRollback), spec(), '/runtime/invalid-pid-retained')
+    const retained = testHandle(runtime(failedRollback), spec(), '/runtime/invalid-pid-retained')
     await expect(retained.done).rejects.toThrow('invalid command pid rollback did not reach quiescence')
     await expect(retained.waitForExit()).rejects.toThrow('invalid handle kill failed')
     failedRollback.handle.killError = undefined
@@ -1326,7 +1366,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(retained.waitForExit()).resolves.toBe(true)
 
     const crashedFake = new FakeSandbox()
-    const crashed = new E2BSubprocessHandle(runtime(crashedFake), spec(), '/runtime/crashed')
+    const crashed = testHandle(runtime(crashedFake), spec(), '/runtime/crashed')
     await flush()
     crashedFake.alive = false
     crashedFake.handle.crash(new Error('command transport failed'))
@@ -1339,7 +1379,7 @@ describe('E2BSubprocessHandle', () => {
     invalidGroup.delaysKill = true
     invalidGroup.sdkKillStops = false
     invalidGroup.afterProbe = () => { invalidGroup.alive = false }
-    const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
+    const invalid = testHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
     expect(invalidGroup.handle.kills).toBe(1)
     expect(invalidGroup.commandsSeen).toContain('kill -KILL -- -4242')
@@ -1351,14 +1391,14 @@ describe('E2BSubprocessHandle', () => {
     unsafeGroup.delaysKill = true
     unsafeGroup.sdkKillStops = false
     unsafeGroup.afterProbe = () => { unsafeGroup.alive = false }
-    const unsafe = new E2BSubprocessHandle(runtime(unsafeGroup), spec(), '/runtime/unsafe-group')
+    const unsafe = testHandle(runtime(unsafeGroup), spec(), '/runtime/unsafe-group')
     await expect(unsafe.done).rejects.toThrow(/unsafe published process-group id 1/)
     expect(unsafeGroup.commandsSeen).not.toContain('kill -KILL -- -1')
     await expect(unsafe.waitForExit()).resolves.toBe(true)
 
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
-    const absent = new E2BSubprocessHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
+    const absent = testHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
     await flush()
     absentGroup.finish()
     await expect(absent.done).rejects.toThrow(/exited before publishing/)
@@ -1372,7 +1412,7 @@ describe('E2BSubprocessHandle', () => {
     fake.processGroupId = 'not-a-pid\n'
     fake.signalError = new Error('rollback signal failed')
     fake.handle.killError = new Error('SDK kill failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/failed-rollback')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/failed-rollback')
 
     let failure: unknown
     try {
@@ -1403,7 +1443,7 @@ describe('E2BSubprocessHandle', () => {
     naturallyGone.processGroupId = 'not-a-pid\n'
     naturallyGone.signalError = new Error('rollback signal failed')
     naturallyGone.handle.killError = new Error('SDK kill failed')
-    const observed = new E2BSubprocessHandle(runtime(naturallyGone), spec(), '/runtime/failed-rollback-observed')
+    const observed = testHandle(runtime(naturallyGone), spec(), '/runtime/failed-rollback-observed')
     await expect(observed.done).rejects.toThrow('process-group publication failed')
     naturallyGone.alive = false
     await expect(observed.waitForExit()).resolves.toBe(true)
@@ -1412,7 +1452,7 @@ describe('E2BSubprocessHandle', () => {
   it('waits for delayed process-group publication', async () => {
     const fake = new FakeSandbox()
     fake.processGroupReads.push('', '4242\n')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/delayed-group')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/delayed-group')
     await vi.waitFor(() => { expect(handle.pid).toBe(4242) })
     fake.finish()
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
@@ -1420,7 +1460,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('handles output backpressure and contains a stderr sink failure', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
     }), '/runtime/backpressure')
     await flush()
@@ -1445,7 +1485,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('settles output backpressure when the consumer closes the pipe', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/backpressure-close')
     await flush()
@@ -1462,7 +1502,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('breaks output backpressure when termination owns the command', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/backpressure-termination')
     await flush()
@@ -1484,7 +1524,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('settles backpressure when a synchronous pipe write starts termination', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/backpressure-synchronous-termination')
     await flush()
@@ -1500,7 +1540,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('contains a pipe callback failure instead of rejecting command settlement', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/pipe-error')
     await flush()
@@ -1516,14 +1556,14 @@ describe('E2BSubprocessHandle', () => {
     const gone = new FakeSandbox()
     gone.trapsTerm = true
     gone.signalError = commandError(1)
-    const goneHandle = new E2BSubprocessHandle(runtime(gone), spec({ graceMs: 1 }), '/runtime/gone-signal')
+    const goneHandle = testHandle(runtime(gone), spec({ graceMs: 1 }), '/runtime/gone-signal')
     await flush()
     goneHandle.terminate()
     await expect(goneHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
 
     const failed = new FakeSandbox()
     failed.signalError = new Error('signal transport failed')
-    const failedHandle = new E2BSubprocessHandle(runtime(failed), spec(), '/runtime/failed-signal')
+    const failedHandle = testHandle(runtime(failed), spec(), '/runtime/failed-signal')
     await flush()
     failedHandle.terminate()
     await expect(failedHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
@@ -1534,7 +1574,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     fake.handle.killError = new Error('SDK kill failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry-signal')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry-signal')
     await flush()
 
     handle.terminate()
@@ -1548,7 +1588,7 @@ describe('E2BSubprocessHandle', () => {
     missingGroup.trapsTerm = true
     missingGroup.signalErrors.push(undefined, commandError(1))
     missingGroup.handle.killError = new Error('SDK kill failed after group exit race')
-    const raced = new E2BSubprocessHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
+    const raced = testHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
     await flush()
     raced.terminate()
     await expect(raced.waitForExit()).rejects.toThrow('remained live after force termination')
@@ -1562,7 +1602,7 @@ describe('E2BSubprocessHandle', () => {
     fake.trapsTerm = true
     fake.sdkKillStops = false
     fake.signalErrors.push(undefined, new Error('KILL transport failed'))
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/optimistic-sdk-kill')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/optimistic-sdk-kill')
     await flush()
 
     handle.terminate()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 826732f057..5472b2cfa7 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -259,10 +259,20 @@ function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
   }
 }
 
+/** Spawn the terminal under test with the config default the service would pass. */
+function testSpawn(
+  runtime: Parameters<typeof spawnE2BTerminal>[0],
+  spec: Parameters<typeof spawnE2BTerminal>[1],
+  stateDir: string,
+  pollMs = 20,
+): ReturnType<typeof spawnE2BTerminal> {
+  return spawnE2BTerminal(runtime, spec, stateDir, pollMs)
+}
+
 describe('E2B terminal allocation', () => {
   it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/terminal-one')
     let output = ''
     terminal.output.on('data', (chunk) => { output += String(chunk) })
     await new Promise(resolve => setTimeout(resolve, 0))
@@ -314,7 +324,7 @@ describe('E2B terminal allocation', () => {
   it('inherits only safe ambient values and limits the allocation signal to setup', async () => {
     const fake = new FakeTerminalSandbox()
     const controller = new AbortController()
-    const terminal = await spawnE2BTerminal(
+    const terminal = await testSpawn(
       runtime(fake),
       spec({ env: undefined, signal: controller.signal }),
       '/runtime/abort-live',
@@ -335,7 +345,7 @@ describe('E2B terminal allocation', () => {
     const fake = new FakeTerminalSandbox()
     fake.deferCreate()
     const controller = new AbortController()
-    const spawning = spawnE2BTerminal(
+    const spawning = testSpawn(
       runtime(fake),
       spec({ signal: controller.signal }),
       '/runtime/allocation-cancel',
@@ -352,23 +362,23 @@ describe('E2B terminal allocation', () => {
 
   it('rejects malformed environment and argv values before PTY allocation', async () => {
     const invalidName = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
+    await expect(testSpawn(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
       .rejects.toThrow('environment entries')
     expect(invalidName.createOptions).toBeUndefined()
 
     const invalidValue = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
+    await expect(testSpawn(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
       .rejects.toThrow('environment entries')
 
     const invalidArg = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
+    await expect(testSpawn(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
       .rejects.toThrow('argv must not contain NUL')
   })
 
   it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
     const failedState = new FakeTerminalSandbox()
     failedState.writeError = new Error('state write failed')
-    await expect(spawnE2BTerminal(runtime(failedState), spec(), '/runtime/state-write'))
+    await expect(testSpawn(runtime(failedState), spec(), '/runtime/state-write'))
       .rejects.toThrow('state write failed')
     expect(failedState.writes.get('/runtime/state-write/environment')).toContain('KEEP=visible\0')
     expect(failedState.removed).toContain('/runtime/state-write')
@@ -377,19 +387,19 @@ describe('E2B terminal allocation', () => {
     const stateAlreadyGone = new FakeTerminalSandbox()
     stateAlreadyGone.writeError = new Error('state write failed after external cleanup')
     stateAlreadyGone.removeError = new FileNotFoundError('state already gone')
-    await expect(spawnE2BTerminal(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
+    await expect(testSpawn(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
       .rejects.toThrow('state write failed after external cleanup')
 
     const invalidPid = new FakeTerminalSandbox()
     invalidPid.handle.pid = 0
-    await expect(spawnE2BTerminal(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
+    await expect(testSpawn(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
       .rejects.toThrow('invalid terminal pid 0')
     expect(invalidPid.handle.sdkKills).toBe(1)
     expect(invalidPid.removed).toContain('/runtime/invalid-pid')
 
     const failedInput = new FakeTerminalSandbox()
     failedInput.sendError = new Error('bootstrap failed')
-    await expect(spawnE2BTerminal(runtime(failedInput), spec(), '/runtime/input'))
+    await expect(testSpawn(runtime(failedInput), spec(), '/runtime/input'))
       .rejects.toThrow('bootstrap failed')
     expect(failedInput.commands).toContain('kill -TERM -- -123')
     expect(failedInput.groups).toEqual([])
@@ -397,7 +407,7 @@ describe('E2B terminal allocation', () => {
     const invalidSession = new FakeTerminalSandbox()
     invalidSession.sessionId = 'not-a-session\n'
     invalidSession.clearOnTerm = false
-    await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
+    await expect(testSpawn(runtime(invalidSession), spec(), '/runtime/session'))
       .rejects.toThrow('cannot resolve process session')
     expect(invalidSession.commands).toContain('kill -TERM -- -123')
     expect(invalidSession.commands).toContain('kill -KILL -- -123')
@@ -410,7 +420,7 @@ describe('E2B terminal allocation', () => {
     const termFailed = new FakeTerminalSandbox()
     termFailed.sendError = new Error('bootstrap failed')
     termFailed.termFailure = new Error('TERM transport failed')
-    await expect(spawnE2BTerminal(runtime(termFailed), spec(), '/runtime/term-failed'))
+    await expect(testSpawn(runtime(termFailed), spec(), '/runtime/term-failed'))
       .rejects.toThrow('bootstrap failed')
     expect(termFailed.commands).toContain('kill -KILL -- -123')
     expect(termFailed.handle.sdkKills).toBe(1)
@@ -421,7 +431,7 @@ describe('E2B terminal allocation', () => {
     uninspectable.handle.sdkKillError = new Error('PTY kill failed')
     let uninspectableFailure: unknown
     try {
-      await spawnE2BTerminal(runtime(uninspectable), spec(), '/runtime/uninspectable')
+      await testSpawn(runtime(uninspectable), spec(), '/runtime/uninspectable')
     } catch (error: unknown) {
       uninspectableFailure = error
     }
@@ -432,21 +442,21 @@ describe('E2B terminal allocation', () => {
     survivingGroups.sendError = new Error('bootstrap failed')
     survivingGroups.clearOnTerm = false
     survivingGroups.clearOnKill = false
-    await expect(spawnE2BTerminal(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
+    await expect(testSpawn(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
       .rejects.toThrow('bootstrap failed')
 
     const survivingPid = new FakeTerminalSandbox()
     survivingPid.sendError = new Error('bootstrap failed')
     survivingPid.groups = []
     survivingPid.handle.settleOnSdkKill = false
-    await expect(spawnE2BTerminal(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
+    await expect(testSpawn(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
       .rejects.toThrow('bootstrap failed')
 
     const waitFailed = new FakeTerminalSandbox()
     waitFailed.handle.waitError = new Error('wait failed')
     waitFailed.handle.settleOnSdkKill = false
     waitFailed.handle.sdkKillError = new Error('kill failed')
-    await expect(spawnE2BTerminal(runtime(waitFailed), spec(), '/runtime/wait-failed'))
+    await expect(testSpawn(runtime(waitFailed), spec(), '/runtime/wait-failed'))
       .rejects.toThrow('wait failed')
     expect(waitFailed.handle.sdkKills).toBe(1)
 
@@ -454,7 +464,7 @@ describe('E2B terminal allocation', () => {
     cleanupFailed.handle.pid = 0
     cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
     cleanupFailed.removeError = new Error('remove transport failed')
-    await expect(spawnE2BTerminal(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
+    await expect(testSpawn(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
       .rejects.toThrow('invalid terminal pid 0')
 
     const expiredDuringRollback = new FakeTerminalSandbox()
@@ -463,7 +473,7 @@ describe('E2B terminal allocation', () => {
     expiredDuringRollback.handle.settleOnSdkKill = false
     expiredDuringRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
-    await expect(spawnE2BTerminal(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
+    await expect(testSpawn(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
       .rejects.toThrow('bootstrap failed before timeout')
     expect(expiredDuringRollback.handle.sdkKills).toBe(1)
 
@@ -471,30 +481,30 @@ describe('E2B terminal allocation', () => {
     expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
     expiredBeforeSdkRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     expiredBeforeSdkRollback.handle.settleOnSdkKill = false
-    await expect(spawnE2BTerminal(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
+    await expect(testSpawn(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
       .rejects.toThrow('wait failed after timeout')
 
     const missingDuringDisconnect = new FakeTerminalSandbox()
     missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
     missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
-    await expect(spawnE2BTerminal(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
+    await expect(testSpawn(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
       .rejects.toThrow('bootstrap failed before disconnect')
 
     const failedDisconnect = new FakeTerminalSandbox()
     failedDisconnect.sendError = new Error('bootstrap failed with disconnect failure')
     failedDisconnect.handle.disconnectError = new Error('disconnect transport failed')
-    await expect(spawnE2BTerminal(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
+    await expect(testSpawn(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
       .rejects.toThrow('bootstrap failed with disconnect failure')
   })
 
   it('propagates setup cancellation and provider failures', async () => {
     const aborted = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
+    await expect(testSpawn(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
       .rejects.toThrow('stop')
 
     const createFailed = new FakeTerminalSandbox()
     createFailed.createError = new Error('create failed')
-    await expect(spawnE2BTerminal(runtime(createFailed), spec(), '/runtime/create'))
+    await expect(testSpawn(runtime(createFailed), spec(), '/runtime/create'))
       .rejects.toThrow('create failed')
 
   })
@@ -502,7 +512,7 @@ describe('E2B terminal allocation', () => {
   it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
     const exited = new FakeTerminalSandbox()
     exited.emitOutputMarker = false
-    const exiting = spawnE2BTerminal(runtime(exited), spec(), '/runtime/missing-output-boundary')
+    const exiting = testSpawn(runtime(exited), spec(), '/runtime/missing-output-boundary')
     await vi.waitFor(() => { expect(exited.inputs).toHaveLength(1) })
     exited.handle.succeed(0)
     await expect(exiting).rejects.toThrow('terminal exited before publishing its output boundary')
@@ -510,7 +520,7 @@ describe('E2B terminal allocation', () => {
     const cancelled = new FakeTerminalSandbox()
     cancelled.emitOutputMarker = false
     const controller = new AbortController()
-    const cancelling = spawnE2BTerminal(
+    const cancelling = testSpawn(
       runtime(cancelled),
       spec({ signal: controller.signal }),
       '/runtime/cancel-output-boundary',
@@ -525,7 +535,7 @@ describe('E2B terminal allocation', () => {
 describe('E2B terminal lifecycle', () => {
   it('aborts and joins in-flight terminal operations before cleanup', async () => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/in-flight-operations')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/in-flight-operations')
     const writeStarted = Promise.withResolvers<AbortSignal>()
     const inspectStarted = Promise.withResolvers<AbortSignal>()
     const signalStarted = Promise.withResolvers<AbortSignal>()
@@ -563,7 +573,7 @@ describe('E2B terminal lifecycle', () => {
   it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/natural')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/natural')
     terminal.output.resume()
     const ended = once(terminal.output, 'end')
     fake.handle.succeed(7)
@@ -583,7 +593,7 @@ describe('E2B terminal lifecycle', () => {
   ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
+    const terminal = await testSpawn(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
     fake.handle.fail(exitCode)
     await expect(terminal.done).resolves.toEqual(expected)
     await terminal.terminate()
@@ -593,7 +603,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
     fake.zombieGroups = [123]
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/zombie-session')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/zombie-session')
 
     fake.handle.succeed(0)
     await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
@@ -605,7 +615,7 @@ describe('E2B terminal lifecycle', () => {
 
   it('treats a timeout-killed sandbox as quiescent during terminal cleanup', async () => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/expired-sandbox')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/expired-sandbox')
     fake.sessionGroupsFailure = new SandboxNotFoundError('sandbox expired')
     fake.handle.succeed(0)
 
@@ -618,7 +628,7 @@ describe('E2B terminal lifecycle', () => {
     fake.groups = []
     fake.handle.settleOnSdkKill = false
     fake.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
 
     await terminal.terminate()
     expect(fake.handle.sdkKills).toBe(1)
@@ -629,7 +639,7 @@ describe('E2B terminal lifecycle', () => {
     fake.groups = []
     fake.handle.settleOnSdkKill = false
     fake.handle.sdkKillError = new Error('PTY kill transport failed')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
 
     await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
     fake.handle.sdkKillError = undefined
@@ -643,7 +653,7 @@ describe('E2B terminal lifecycle', () => {
     ['propagates another failure', new Error('disconnect failed'), false],
   ] as const)('%s while disconnecting a settled terminal', async (_label, failure, accepted) => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
+    const terminal = await testSpawn(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
     fake.handle.disconnectError = failure
     fake.groups = []
     fake.handle.succeed(0)
@@ -655,7 +665,7 @@ describe('E2B terminal lifecycle', () => {
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
     const fake = new FakeTerminalSandbox()
     fake.foreground = '123\n'
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/signal')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/signal')
     await expect(terminal.signalForeground('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
     fake.foreground = 'invalid\n'
     await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
@@ -671,7 +681,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [123, 456]
     fake.clearOnTerm = false
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
     const terminating = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
     await terminating
@@ -682,7 +692,7 @@ describe('E2B terminal lifecycle', () => {
   it('surfaces cleanup failures and allows a later retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [1]
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
     await expect(terminal.terminate()).rejects.toThrow('unsafe process group 1')
 
     fake.groups = []
@@ -694,7 +704,7 @@ describe('E2B terminal lifecycle', () => {
   it('propagates a process-group signalling transport failure before retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.termFailure = new Error('signal transport failed')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
     await expect(terminal.terminate()).rejects.toThrow('signal transport failed')
 
     fake.groups = []
@@ -704,7 +714,7 @@ describe('E2B terminal lifecycle', () => {
 
     const alreadyExited = new FakeTerminalSandbox()
     alreadyExited.termFailure = commandError(1)
-    const tolerant = await spawnE2BTerminal(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
+    const tolerant = await testSpawn(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
     const tolerantTermination = tolerant.terminate()
     await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
     await tolerantTermination
@@ -714,7 +724,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
     fake.removeError = new Error('private state already gone')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/reject-during-cleanup')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/reject-during-cleanup')
     terminal.output.on('error', () => {})
     const cleanup = terminal.terminate()
     await Promise.resolve()
@@ -727,7 +737,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
     fake.handle.settleOnSdkKill = false
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
     terminal.output.on('error', () => {})
     const cleanup = terminal.terminate()
     while (fake.handle.sdkKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
@@ -741,20 +751,20 @@ describe('E2B terminal lifecycle', () => {
     const survivor = new FakeTerminalSandbox()
     survivor.clearOnTerm = false
     survivor.clearOnKill = false
-    const terminal = await spawnE2BTerminal(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
+    const terminal = await testSpawn(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
     await expect(terminal.terminate()).rejects.toThrow('surviving process groups: 123')
 
     const livePid = new FakeTerminalSandbox()
     livePid.groups = []
     livePid.handle.settleOnSdkKill = false
-    const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
+    const live = await testSpawn(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
     await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
     livePid.handle.succeed(0)
     await live.done
 
     const crashed = new FakeTerminalSandbox()
     crashed.groups = []
-    const failed = await spawnE2BTerminal(runtime(crashed), spec(), '/runtime/crashed')
+    const failed = await testSpawn(runtime(crashed), spec(), '/runtime/crashed')
     const outputError = once(failed.output, 'error')
     crashed.handle.crash('transport gone')
     await expect(failed.done).rejects.toEqual('transport gone')
diff --git a/packages/e2b/subprocess-e2b/tsconfig.json b/packages/e2b/subprocess-e2b/tsconfig.json
index fda7cfc667..1bae0ef012 100644
--- a/packages/e2b/subprocess-e2b/tsconfig.json
+++ b/packages/e2b/subprocess-e2b/tsconfig.json
@@ -4,22 +4,27 @@
     "rootDir": "src",
     "outDir": "lib/types"
   },
-  "include": ["src"],
+  "include": [
+    "src"
+  ],
   "references": [
-    {
-      "path": "../../../vendor/cosmokit"
-    },
     {
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../e2b"
+      "path": "../../../vendor/cosmokit"
     },
     {
       "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../e2b"
     }
   ]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d2e7d0ec1c..fab00ba9cb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3190,6 +3190,9 @@ importers:
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From b77dbf8ad8b307a18115bdcf808572f9ad76f71e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:06:26 +0800
Subject: [PATCH 145/262] fix(e2b): mount sandbox policy in live PTY test

---
 packages/e2b/e2b/package.json             | 1 +
 packages/e2b/e2b/tests/composition.e2e.ts | 8 +++++---
 pnpm-lock.yaml                            | 3 +++
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index a77e3d9464..5abacb278a 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/package.json
@@ -35,6 +35,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 01316aeb2d..6da102a827 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -13,6 +13,7 @@ import {
 } from '@deepseek-ai/dsh-e2b'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 
@@ -51,10 +52,10 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         runtimeRoot: '/home/user/.dsh-e2b',
         getSandbox: async () => sandbox,
       } as never)
-      ctx.provide('sandboxPolicy', {
-        defaultMode: 'danger-full-access',
+      const sandboxPolicyFiber = await ctx.plugin(SandboxPolicyService, {
+        mode: 'danger-full-access',
         workspaceRoot: '/home/user',
-      } as never)
+      })
       const ptyFiber = await ctx.plugin(PtyService)
       const subprocessFiber = await ctx.plugin(E2BSubprocessService)
       const node = await ctx.subprocess.resolveExecutable('node')
@@ -114,6 +115,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       await session.close('environment test complete')
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
+      await sandboxPolicyFiber.dispose()
 
     } finally {
       await sandbox.kill().catch(() => false)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fab00ba9cb..a92883786a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3156,6 +3156,9 @@ importers:
       '@deepseek-ai/dsh-loader-smoke':
         specifier: workspace:^
         version: link:../../support/loader-smoke
+      '@deepseek-ai/dsh-sandbox-policy':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox-policy
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From 9c13a62702039e2f55c52f95fff02182e0b37af7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:37:46 +0800
Subject: [PATCH 146/262] fix(i18n): preserve merge conflicts without runtime

---
 ...matic-translation-pairing-merges.i18n.yaml |   4 +-
 ...08-automatic-translation-pairing-merges.md |  18 +-
 ...automatic-translation-pairing-merges.zh.md |  18 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +
 docs/development.zh.md                        |   2 +
 scripts/install-lefthook.mjs                  |  13 +-
 scripts/install-lefthook.spec.ts              |  27 ++-
 scripts/merge-translation-pairing-driver.sh   |  35 ++++
 scripts/merge-translation-pairing.ts          |  50 ++---
 scripts/translation-pairing-merge.spec.ts     | 195 +++++++++++++++++-
 scripts/translation-pairing-merge.ts          |  50 +++--
 12 files changed, 358 insertions(+), 60 deletions(-)
 create mode 100755 scripts/merge-translation-pairing-driver.sh

diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
index 7631476fb8..0c44f790b7 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.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 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
-2026-08-08-automatic-translation-pairing-merges.md: e70864f1227fe11d7895dd85b0a99d166753a685
-2026-08-08-automatic-translation-pairing-merges.zh.md: 08da67d78e5cca23e3c5c698644c667813697812
+2026-08-08-automatic-translation-pairing-merges.md: ac4e0c11290abfd48d0f3caf037062aa2fe36c4d
+2026-08-08-automatic-translation-pairing-merges.zh.md: 38e8c0a5613a6bd0b3e76143a93c93653430d0c2
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
index e70864f122..ac4e0c1129 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
@@ -12,6 +12,8 @@ A bilingual consistency record contains the two owner files' exact blob hashes.
 
 `*.i18n.yaml` uses the repository-owned `dsh-translation-pairing` merge driver. The worktree-local Git installer registers its command alongside Lefthook setup; Git configuration remains local because a tracked attribute can name a driver but cannot carry its executable command.
 
+The installer loads the exact Node/tsx entrypoint before publishing worktree integration. Git invokes a checked-in shell launcher that does not require Node and repeats this probe before every driver execution. When the runtime or entrypoint is unavailable, the launcher materializes Git's ordinary three-way text result in the sidecar but returns a conflict even when that text merge is clean, so Git retains the unmerged index stages and never accepts unverified metadata.
+
 The driver parses the ancestor, current, and other records and loads the six owner blobs named by their hashes. It independently runs Git's default three-way text merge for the English and Chinese triplets, requires both merges to be clean, verifies language switchers and the pairing structural signature, stores the two merged blobs, and writes their hashes as the canonical record. This composes confirmations already present in both parents; it never records an ordinary one-sided documentation edit.
 
 The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy (including a non-text `merge.default` inherited by an otherwise unspecified path), either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
@@ -20,9 +22,21 @@ The driver fails with an ordinary unresolved sidecar when a record is malformed,
 
 `pre-merge-commit` and `pre-commit` verify staged `.i18n.yaml` files against the exact index bytes of their owners. They validate driver output but do not regenerate records, so bypassing a hook cannot silently bless translation drift; the corpus-wide `doc-sync` check remains authoritative in CI.
 
+## Failure contract
+
+| Failure during a normal `git merge` | Observable state | Recovery |
+|---|---|---|
+| A fresh install cannot probe the driver or install Lefthook | No new driver or hook-path configuration is published; any newly added integration is rolled back to the previous hook lookup. | Restore the dependencies and rerun `node scripts/install-lefthook.mjs`. |
+| Node, tsx, or the driver entrypoint becomes unavailable after installation | The merge stops with the sidecar at `UU`, index stages 1/2/3 remain, the worktree sidecar contains Git's text result, `MERGE_HEAD` exists, and no commit is created. | Restore the dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. |
+| The repository-aware driver rejects the records | The merge stops with the sidecar unresolved and no commit; the driver prints the owner-repair and explicit-resolver path. | Repair the owner conflict or record, then run the printed resolver workflow or abort. |
+| The driver process crashes with a status above 128 | Git aborts the merge strategy without publishing `MERGE_HEAD` or unmerged index stages. | Repair the runtime and rerun the merge. |
+| `pre-merge-commit` rejects an otherwise clean file merge | No unmerged entries remain, the complete result is staged with `MERGE_HEAD`, and no merge commit is created. | Repair the hook failure and run `git commit`, or run `git merge --abort`. |
+
+An installer rollback failure reports both the original installation error and every rollback error. Because worktree configuration may then be partial, the contributor repairs or inspects it before merging instead of relying on a silent fallback.
+
 ## Verification
 
-Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, mixed safe and owner-conflicted pairs, edited sidecars, non-text default merge configuration, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
+Script tests exercise clean composition through the installed launcher, missing-runtime and broken-entrypoint text fallback, installer probe rollback, a rejecting `pre-merge-commit` hook, explicit recovery from an unresolved index, mixed safe and owner-conflicted pairs, edited sidecars, non-text default merge configuration, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
 
 ## Alternatives considered
 
@@ -38,4 +52,4 @@ Script tests exercise clean composition through a real custom-driver Git merge,
 
 Installed worktrees automatically remove pairing-record-only conflicts while preserving human judgment for owner conflicts and translation quality. GitHub's hosted mergeability calculation does not run the worktree-local executable, so a contributor or agent must still merge the base and push the resulting commit before the remote conflict badge clears.
 
-The installer reserves `merge.dsh-translation-pairing.*` in worktree configuration and refuses a conflicting custom value. Merge execution depends on the installed Node dependencies, like the repository's contributor hooks; missing setup fails rather than selecting stale metadata.
+The installer reserves `merge.dsh-translation-pairing.*` in worktree configuration and refuses a conflicting custom value. Automatic composition depends on the installed Node dependencies, like the repository's contributor hooks; runtime loss produces a visible unresolved text result rather than selecting stale metadata.
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
index 08da67d78e..38e8c0a561 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -12,6 +12,8 @@ Status: implemented
 
 `*.i18n.yaml` 使用由仓库维护的 `dsh-translation-pairing` 合并驱动。worktree 本地的 Git 安装脚本在设置 Lefthook 的同时注册该驱动命令；Git 配置仍限定于当前 worktree，因为受跟踪的属性可以指定驱动，却无法携带其可执行命令。
 
+安装脚本会在发布 worktree 集成前加载确切的 Node/tsx 入口点。Git 会调用仓库内已提交且不依赖 Node 的 shell 启动器；该启动器会在每次执行驱动前重复这项探测。运行时或入口点不可用时，即使文本合并干净完成，启动器也会将 Git 的普通三方文本合并结果写入伴随文件并返回冲突状态，使 Git 保留未合并的索引阶段，绝不接受未经验证的元数据。
+
 驱动会解析祖先、当前和另一侧的记录，并加载其中 hash 指向的六个 Markdown blob。它分别对英文文档的三个 blob 与中文文档的三个 blob 运行 Git 默认的三方文本合并，要求两次合并都干净完成，校验语言切换行与配对结构签名，存储两个合并后的 blob，再将其 hash 写入规范记录。这一过程组合两个父提交中已经存在的确认；它绝不会为普通的单侧文档编辑写入记录。
 
 记录格式错误、对象缺失、配对文档采用其他合并策略（包括原本未单独指定策略的路径继承了非文本 `merge.default`）、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
@@ -20,9 +22,21 @@ Status: implemented
 
 `pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
 
+## 失败契约
+
+| 普通 `git merge` 期间的失败 | 可观察状态 | 恢复 |
+|---|---|---|
+| 全新安装无法探测驱动或安装 Lefthook | 不会发布新的驱动或钩子路径配置；任何新增集成都会回滚到原有的钩子查找方式。 | 恢复依赖并重新运行 `node scripts/install-lefthook.mjs`。 |
+| 安装后 Node、tsx 或驱动入口点变得不可用 | 合并停止，伴随文件状态为 `UU`；索引阶段 1/2/3 保留，worktree 中的伴随文件包含 Git 的文本结果，`MERGE_HEAD` 存在，且不创建提交。 | 恢复依赖并运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。 |
+| 了解仓库状态的驱动拒绝记录 | 合并停止，伴随文件保持未解决状态且不创建提交；驱动会打印修复配对文档和运行显式冲突解决命令的路径。 | 修复配对文档冲突或记录，然后运行打印出的冲突解决工作流，或中止合并。 |
+| 驱动进程以大于 128 的状态码崩溃 | Git 中止合并策略，既不写入 `MERGE_HEAD`，也不产生未合并的索引阶段。 | 修复运行时并重新执行合并。 |
+| `pre-merge-commit` 拒绝原本能干净完成的文件合并 | 不再有未合并条目，完整结果已暂存且 `MERGE_HEAD` 存在，但不会创建合并提交。 | 修复钩子失败并运行 `git commit`，或运行 `git merge --abort`。 |
+
+安装脚本回滚失败时，会同时报告最初的安装错误和每一项回滚错误。此时 worktree 配置可能只完成了一部分，因此贡献者会先修复或检查配置再执行合并，而不是依赖静默回退。
+
 ## 验证
 
-脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、可安全解决的配对与配对文档冲突的配对并存、被编辑过的伴随文件、非文本默认合并配置、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
+脚本测试通过已安装的启动器覆盖无冲突组合，并覆盖运行时缺失与入口点损坏时的文本回退、安装脚本探测回滚、拒绝合并的 `pre-merge-commit` 钩子、从含未解决条目的索引中显式恢复、可安全解决的配对与配对文档冲突的配对并存、被编辑过的伴随文件、非文本默认合并配置、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
 
 ## 考虑过的替代方案
 
@@ -38,4 +52,4 @@ Status: implemented
 
 完成安装的 worktree 会自动消除仅由配对记录引起的冲突，同时仍由人工处理配对文档冲突并评判翻译质量。GitHub 托管的可合并性计算不会运行 worktree 本地的可执行命令，因此仍须由贡献者或 agent 将 base 分支合入当前分支并推送结果提交，远端冲突标记才会消失。
 
-安装脚本会在 worktree 配置中预留 `merge.dsh-translation-pairing.*`，并拒绝与之冲突的自定义值。与仓库贡献者钩子一样，合并过程依赖已安装的 Node 依赖；安装未完成时，合并会失败，而不是选择陈旧元数据。
+安装脚本会在 worktree 配置中预留 `merge.dsh-translation-pairing.*`，并拒绝与之冲突的自定义值。与仓库贡献者钩子一样，自动组合依赖已安装的 Node 依赖；运行时不可用时会产生可见的未解决文本结果，而不是选择陈旧元数据。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 6397e9d97e..43f985604b 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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 docs/development.md
-development.md: ad0447a0e121eaa31fb6e98502c6a55a9456d768
-development.zh.md: aef8b25d2115d00d5cfdb76b342a57662030feee
+development.md: 0032000e298ef49516d618e932258e79cf90e802
+development.zh.md: d681306e31991794519b62c3edbb6ca35ebc228b
diff --git a/docs/development.md b/docs/development.md
index ad0447a0e1..0032000e29 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -102,6 +102,8 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
 
+The installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.
+
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
 - `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
diff --git a/docs/development.zh.md b/docs/development.zh.md
index aef8b25d21..d681306e31 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -102,6 +102,8 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
 
+安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。
+
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
diff --git a/scripts/install-lefthook.mjs b/scripts/install-lefthook.mjs
index b928582a8a..198f428b0a 100644
--- a/scripts/install-lefthook.mjs
+++ b/scripts/install-lefthook.mjs
@@ -31,9 +31,15 @@ const PAIRING_MERGE_DRIVER_CONFIG = [
   ['merge.dsh-translation-pairing.name', 'DeepSeek Harness bilingual pairing records'],
   [
     'merge.dsh-translation-pairing.driver',
-    'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P',
+    'scripts/merge-translation-pairing-driver.sh %O %A %B %P',
   ],
 ]
+const PAIRING_MERGE_DRIVER_PROBE = [
+  '--import',
+  'tsx/esm',
+  'scripts/merge-translation-pairing.ts',
+  '--probe',
+]
 
 function errorCode(error) {
   return typeof error === 'object' && error !== null && 'code' in error
@@ -678,6 +684,10 @@ function installPairingMergeDriver(root, worktreeConfigPath) {
   }
 }
 
+function probePairingMergeDriver(root) {
+  capture(process.execPath, PAIRING_MERGE_DRIVER_PROBE, { cwd: root })
+}
+
 async function main() {
   if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') return
   if (typeof lefthookPackage.bin?.lefthook !== 'string') return
@@ -767,6 +777,7 @@ async function main() {
     let pathChanged = false
     let rollbackPairingMergeDriver = () => {}
     try {
+      probePairingMergeDriver(root)
       rollbackPairingMergeDriver = installPairingMergeDriver(root, worktreeConfigPath)
       git(['config', '--worktree', 'core.hooksPath', hooksPath], root)
       pathChanged = worktreePath !== hooksPath
diff --git a/scripts/install-lefthook.spec.ts b/scripts/install-lefthook.spec.ts
index df9f1cd6d8..4d5b585213 100644
--- a/scripts/install-lefthook.spec.ts
+++ b/scripts/install-lefthook.spec.ts
@@ -18,7 +18,9 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 
 const installer = fileURLToPath(new URL('./install-lefthook.mjs', import.meta.url))
-const pairingMergeDriver = 'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P'
+const pairingMergeDriver = 'scripts/merge-translation-pairing-driver.sh %O %A %B %P'
+const scriptsDirectory = fileURLToPath(new URL('.', import.meta.url))
+const tsxPackageDirectory = dirname(fileURLToPath(import.meta.resolve('tsx/package.json')))
 const fixtures: string[] = []
 // Multi-worktree cases spawn several Git and Node subprocesses; coverage concurrency can
 // legitimately exceed Vitest's default deadline without changing the installer behavior.
@@ -123,6 +125,12 @@ function installFakeLefthook(root: string): void {
   chmodSync(shim, 0o755)
 }
 
+function installPairingProbeFixture(root: string): void {
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+  symlinkSync(scriptsDirectory, join(root, 'scripts'), linkType)
+  symlinkSync(tsxPackageDirectory, join(root, 'node_modules/tsx'), linkType)
+}
+
 function createFixture(names: { main?: string; linked?: string } = {}): Fixture {
   const container = mkdtempSync(join(tmpdir(), 'dsh-lefthook-'))
   fixtures.push(container)
@@ -152,6 +160,8 @@ function createFixture(names: { main?: string; linked?: string } = {}): Fixture
   write(join(linked, 'lefthook.yml'), 'linked-worktree-config\n')
   installFakeLefthook(main)
   installFakeLefthook(linked)
+  installPairingProbeFixture(main)
+  installPairingProbeFixture(linked)
   return fixture
 }
 
@@ -287,6 +297,7 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     git(fixture, fixture.main, ['worktree', 'add', '-b', 'late-linked', lateLinked])
     write(join(lateLinked, 'lefthook.yml'), 'late-linked-worktree-config\n')
     installFakeLefthook(lateLinked)
+    installPairingProbeFixture(lateLinked)
     expect(git(fixture, lateLinked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(mainHooks)
 
     const linkedInstall = await runInstaller(fixture, lateLinked)
@@ -791,6 +802,20 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy pre-push\n')
   })
 
+  it('does not publish worktree integration when the pairing driver probe fails', async () => {
+    const fixture = createFixture()
+    rmSync(join(fixture.main, 'node_modules/tsx'), { recursive: true, force: true })
+
+    const result = await runInstaller(fixture, fixture.main)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('merge-translation-pairing.ts --probe failed')
+    expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
+  })
+
   it('reports installation and hook-path rollback failures together', async () => {
     const fixture = createFixture()
 
diff --git a/scripts/merge-translation-pairing-driver.sh b/scripts/merge-translation-pairing-driver.sh
new file mode 100755
index 0000000000..c1fffaff20
--- /dev/null
+++ b/scripts/merge-translation-pairing-driver.sh
@@ -0,0 +1,35 @@
+#!/bin/sh
+
+if [ "$#" -ne 4 ]; then
+  echo 'merge-translation-pairing: expected <ancestor> <current> <other> <repository-path>' >&2
+  exit 129
+fi
+
+ancestor_path=$1
+current_path=$2
+other_path=$3
+meta_path=$4
+driver_directory=$(CDPATH= cd -P "$(dirname "$0")" && pwd) || exit 129
+driver_path=$driver_directory/merge-translation-pairing.ts
+
+if command -v node >/dev/null 2>&1 \
+  && node --import tsx/esm "$driver_path" --probe >/dev/null 2>&1; then
+  exec node --import tsx/esm "$driver_path" \
+    "$ancestor_path" "$current_path" "$other_path" "$meta_path"
+fi
+
+echo "merge-translation-pairing: runtime is unavailable; leaving an ordinary text conflict in $meta_path" >&2
+git merge-file \
+  -L "$meta_path:current" \
+  -L "$meta_path:ancestor" \
+  -L "$meta_path:other" \
+  -- "$current_path" "$ancestor_path" "$other_path"
+fallback_status=$?
+echo 'merge-translation-pairing: restore Node dependencies, then rerun the merge or `pnpm run resolve-translation-pairing-conflicts`; use `git merge --abort` to cancel' >&2
+
+# A clean text merge is still unverified pairing metadata, so the driver must
+# leave Git's index stages unresolved until the repository-aware resolver runs.
+if [ "$fallback_status" -gt 127 ]; then
+  exit "$fallback_status"
+fi
+exit 1
diff --git a/scripts/merge-translation-pairing.ts b/scripts/merge-translation-pairing.ts
index 30313d045a..dda2621a36 100644
--- a/scripts/merge-translation-pairing.ts
+++ b/scripts/merge-translation-pairing.ts
@@ -10,31 +10,35 @@ import {
 const args = process.argv.slice(2)
 
 try {
-  const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
-  if (args[0] === '--resolve') {
-    if (args.length !== 1) throw new Error('--resolve takes no paths; it inspects the unmerged index')
-    const resolved = resolveTranslationPairingConflicts(root)
-    if (resolved.length === 0) {
-      console.log('merge-translation-pairing: no unresolved pairing records')
-    } else {
-      for (const path of resolved) console.log(`merge-translation-pairing: resolved ${path}`)
-    }
+  if (args[0] === '--probe') {
+    if (args.length !== 1) throw new Error('--probe takes no other arguments')
   } else {
-    if (args.length !== 4) {
-      throw new Error('merge-driver mode requires <ancestor> <current> <other> <repository-path>')
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
+    if (args[0] === '--resolve') {
+      if (args.length !== 1) throw new Error('--resolve takes no paths; it inspects the unmerged index')
+      const resolved = resolveTranslationPairingConflicts(root)
+      if (resolved.length === 0) {
+        console.log('merge-translation-pairing: no unresolved pairing records')
+      } else {
+        for (const path of resolved) console.log(`merge-translation-pairing: resolved ${path}`)
+      }
+    } else {
+      if (args.length !== 4) {
+        throw new Error('merge-driver mode requires <ancestor> <current> <other> <repository-path>')
+      }
+      const [ancestorPath, currentPath, otherPath, metaPath] = args
+      if (ancestorPath === undefined || currentPath === undefined || otherPath === undefined || metaPath === undefined) {
+        throw new Error('merge-driver arguments are incomplete')
+      }
+      const result = mergeTranslationPairingRecords(
+        root,
+        metaPath,
+        readFileSync(ancestorPath, 'utf8'),
+        readFileSync(currentPath, 'utf8'),
+        readFileSync(otherPath, 'utf8'),
+      )
+      writeFileSync(currentPath, result.record)
     }
-    const [ancestorPath, currentPath, otherPath, metaPath] = args
-    if (ancestorPath === undefined || currentPath === undefined || otherPath === undefined || metaPath === undefined) {
-      throw new Error('merge-driver arguments are incomplete')
-    }
-    const result = mergeTranslationPairingRecords(
-      root,
-      metaPath,
-      readFileSync(ancestorPath, 'utf8'),
-      readFileSync(currentPath, 'utf8'),
-      readFileSync(otherPath, 'utf8'),
-    )
-    writeFileSync(currentPath, result.record)
   }
 } catch (error) {
   console.error(`merge-translation-pairing: ${error instanceof Error ? error.message : String(error)}`)
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index 6ddce4b30b..26f13748ed 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -1,9 +1,9 @@
 /** Integration coverage for automatic and explicit pairing-record conflict resolution. */
 
 import { execFileSync, spawnSync } from 'node:child_process'
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
@@ -17,6 +17,8 @@ import {
 } from './translation-pairing-record.ts'
 
 const driver = fileURLToPath(new URL('./merge-translation-pairing.ts', import.meta.url))
+const driverLauncher = fileURLToPath(new URL('./merge-translation-pairing-driver.sh', import.meta.url))
+const workspaceRoot = fileURLToPath(new URL('../', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx/esm'))
 const fixtures: string[] = []
 
@@ -46,6 +48,16 @@ function shellQuote(value: string): string {
   return `"${value.replace(/["\\$`]/g, '\\$&')}"`
 }
 
+function installFixtureRuntime(root: string): void {
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+  symlinkSync(
+    join(workspaceRoot, 'node_modules'),
+    join(root, 'node_modules'),
+    linkType,
+  )
+  symlinkSync(join(workspaceRoot, 'scripts'), join(root, 'scripts'), linkType)
+}
+
 function createFixture(attributes = true): Fixture {
   const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
   fixtures.push(root)
@@ -99,6 +111,17 @@ function commitPair(fixture: Fixture, source: string, zh: string, message: strin
   return sidecar
 }
 
+function commitTextCleanPair(fixture: Fixture, source: string, zh: string, message: string): void {
+  const sidecar = record(fixture.root, 'docs/guide.md', source, zh)
+  write(
+    fixture.root,
+    'docs/guide.i18n.yaml',
+    sidecar.replace('\nguide.zh.md:', '\n# Stable separator for independent line merges.\nguide.zh.md:'),
+  )
+  git(fixture, ['add', '.'])
+  git(fixture, ['commit', '-m', message])
+}
+
 function createDivergedPair(fixture: Fixture): { ancestor: string; current: string; other: string } {
   const ancestor = commitPair(fixture, baseSource, baseZh, 'base')
   git(fixture, ['switch', '-c', 'current'])
@@ -109,6 +132,15 @@ function createDivergedPair(fixture: Fixture): { ancestor: string; current: stri
   return { ancestor, current, other }
 }
 
+function createTextCleanDivergedPair(fixture: Fixture): void {
+  commitTextCleanPair(fixture, baseSource, baseZh, 'base')
+  git(fixture, ['switch', '-c', 'current'])
+  commitTextCleanPair(fixture, currentSource, baseZh, 'current source')
+  git(fixture, ['switch', 'master'])
+  commitTextCleanPair(fixture, baseSource, otherZh, 'other translation')
+  git(fixture, ['switch', 'current'])
+}
+
 function startStoppedPairingMerge(fixture: Fixture): void {
   createDivergedPair(fixture)
   const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
@@ -279,13 +311,12 @@ describe('translation pairing merge composition', () => {
   it('runs as Git\'s custom driver and commits a clean composed record', () => {
     const fixture = createFixture()
     createDivergedPair(fixture)
-    const command = [
-      shellQuote(process.execPath),
-      '--import', shellQuote(tsxLoader),
-      shellQuote(driver),
-      '%O', '%A', '%B', '%P',
-    ].join(' ')
-    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
+    installFixtureRuntime(fixture.root)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      'scripts/merge-translation-pairing-driver.sh %O %A %B %P',
+    ])
 
     git(fixture, ['merge', '--no-edit', 'master'])
 
@@ -293,6 +324,152 @@ describe('translation pairing merge composition', () => {
     expectMergedPair(fixture)
   })
 
+  it('leaves an ordinary recoverable conflict when the configured runtime is unavailable', () => {
+    const fixture = createFixture()
+    const records = createDivergedPair(fixture)
+    const fakeBin = join(fixture.root, 'fake-bin')
+    const fakeNode = join(fakeBin, 'node')
+    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
+    chmodSync(fakeNode, 0o755)
+    const command = [
+      shellQuote(driverLauncher),
+      '%O', '%A', '%B', '%P',
+    ].join(' ')
+    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
+    const headBefore = git(fixture, ['rev-parse', 'HEAD'])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: {
+        ...fixture.env,
+        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+      },
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
+    expect(git(fixture, ['rev-parse', 'HEAD'])).toBe(headBefore)
+    expect(git(fixture, ['rev-parse', '--verify', 'MERGE_HEAD'])).not.toBe('')
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+    expect(git(fixture, ['ls-files', '--unmerged', '--', 'docs/guide.i18n.yaml']).split('\n')).toHaveLength(3)
+    const conflicted = readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')
+    expect(conflicted).toContain('<<<<<<< docs/guide.i18n.yaml:current')
+    for (const record of [records.current, records.other]) {
+      const dataLines = record.split('\n').filter(line => line !== '' && !line.startsWith('#')).join('\n')
+      expect(conflicted).toContain(dataLines)
+    }
+
+    expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
+    expectMergedPair(fixture)
+  })
+
+  it('falls back before a broken driver entrypoint can replace the launcher', () => {
+    const fixture = createFixture()
+    createDivergedPair(fixture)
+    const fakeBin = join(fixture.root, 'fake-bin')
+    const fakeNode = join(fakeBin, 'node')
+    write(
+      fixture.root,
+      'fake-bin/node',
+      '#!/bin/sh\nif [ "$3" = "--eval" ]; then exit 0; fi\nexit 72\n',
+    )
+    chmodSync(fakeNode, 0o755)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      `${shellQuote(driverLauncher)} %O %A %B %P`,
+    ])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: {
+        ...fixture.env,
+        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+      },
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toContain(
+      '<<<<<<< docs/guide.i18n.yaml:current',
+    )
+  })
+
+  it('keeps a clean text fallback unresolved until the explicit resolver confirms it', () => {
+    const fixture = createFixture()
+    createTextCleanDivergedPair(fixture)
+    const fakeBin = join(fixture.root, 'fake-bin')
+    const fakeNode = join(fakeBin, 'node')
+    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
+    chmodSync(fakeNode, 0o755)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      `${shellQuote(driverLauncher)} %O %A %B %P`,
+    ])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: {
+        ...fixture.env,
+        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+      },
+    })
+
+    expect(result.status).toBe(1)
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+    const canonicalRecord = renderTranslationPairingRecord(translationPairPaths('docs/guide.md'), {
+      sourceHash: gitBlobHash(Buffer.from(currentSource)),
+      zhHash: gitBlobHash(Buffer.from(otherZh)),
+    })
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe(
+      canonicalRecord.replace(
+        '\nguide.zh.md:',
+        '\n# Stable separator for independent line merges.\nguide.zh.md:',
+      ),
+    )
+
+    expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
+    expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(currentSource)
+    expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(otherZh)
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe(canonicalRecord)
+  })
+
+  it('leaves a staged merge when the pre-merge-commit hook rejects it', () => {
+    const fixture = createFixture()
+    createDivergedPair(fixture)
+    installFixtureRuntime(fixture.root)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      'scripts/merge-translation-pairing-driver.sh %O %A %B %P',
+    ])
+    const hooks = join(fixture.root, 'hooks')
+    write(
+      fixture.root,
+      'hooks/pre-merge-commit',
+      '#!/bin/sh\necho "fixture pre-merge-commit rejection" >&2\nexit 77\n',
+    )
+    chmodSync(join(hooks, 'pre-merge-commit'), 0o755)
+    git(fixture, ['config', 'core.hooksPath', hooks])
+    const headBefore = git(fixture, ['rev-parse', 'HEAD'])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-edit', 'master'], {
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('fixture pre-merge-commit rejection')
+    expect(git(fixture, ['rev-parse', 'HEAD'])).toBe(headBefore)
+    expect(git(fixture, ['rev-parse', '--verify', 'MERGE_HEAD'])).not.toBe('')
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('')
+    expect(git(fixture, ['diff', '--cached', '--name-only']).split('\n')).toContain(
+      'docs/guide.i18n.yaml',
+    )
+    expectMergedPair(fixture)
+  })
+
   it('prints the recovery path when driver input is not composable', () => {
     const fixture = createFixture(false)
     const result = spawnSync(process.execPath, ['--import', tsxLoader, driver], {
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
index 58b1be3fee..7c6d38469c 100644
--- a/scripts/translation-pairing-merge.ts
+++ b/scripts/translation-pairing-merge.ts
@@ -97,13 +97,13 @@ function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void
   }
 }
 
-function mergeBlobTriplet(
+function runTextMerge(
   root: string,
-  owner: string,
-  ancestor: Buffer,
-  current: Buffer,
-  other: Buffer,
-): Buffer {
+  label: string,
+  ancestor: Buffer | string,
+  current: Buffer | string,
+  other: Buffer | string,
+): { output: Buffer; status: number | null } {
   const temporary = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
   try {
     const ancestorPath = join(temporary, 'ancestor')
@@ -115,26 +115,37 @@ function mergeBlobTriplet(
     const result = spawnSync('git', [
       '-C', root,
       'merge-file', '-p',
-      '-L', `${owner}:current`,
-      '-L', `${owner}:ancestor`,
-      '-L', `${owner}:other`,
+      '-L', `${label}:current`,
+      '-L', `${label}:ancestor`,
+      '-L', `${label}:other`,
       currentPath, ancestorPath, otherPath,
     ], { maxBuffer: GIT_COMMAND_MAX_BUFFER })
     if (result.error) {
-      throw new Error(`merging ${owner} failed: ${result.error.message}`, { cause: result.error })
+      throw new Error(`merging ${label} failed: ${result.error.message}`, { cause: result.error })
     }
-    if (result.status !== 0) {
-      const kind = result.status !== null && result.status > 0 && result.status <= 127
-        ? 'has content conflicts'
-        : `failed with status ${String(result.status)}`
-      throw new Error(`${owner} ${kind}`)
-    }
-    return result.stdout
+    return { output: result.stdout, status: result.status }
   } finally {
     rmSync(temporary, { recursive: true, force: true })
   }
 }
 
+function mergeBlobTriplet(
+  root: string,
+  owner: string,
+  ancestor: Buffer,
+  current: Buffer,
+  other: Buffer,
+): Buffer {
+  const result = runTextMerge(root, owner, ancestor, current, other)
+  if (result.status !== 0) {
+    const kind = result.status !== null && result.status > 0 && result.status <= 127
+      ? 'has content conflicts'
+      : `failed with status ${String(result.status)}`
+    throw new Error(`${owner} ${kind}`)
+  }
+  return result.output
+}
+
 function loadRecordOwners(
   root: string,
   label: string,
@@ -243,11 +254,14 @@ function unmergedSidecars(root: string): Map<string, UnmergedStages> {
 function assertUneditedSidecar(
   root: string,
   metaPath: string,
+  ancestorRecord: string,
   currentRecord: string,
   otherRecord: string,
 ): void {
   const worktreeRecord = readFileSync(join(root, metaPath), 'utf8')
   if (worktreeRecord === currentRecord || worktreeRecord === otherRecord) return
+  const textMerge = runTextMerge(root, metaPath, ancestorRecord, currentRecord, otherRecord)
+  if (textMerge.status === 0 && textMerge.output.toString('utf8') === worktreeRecord) return
   const stageDataLines = [currentRecord, otherRecord]
     .flatMap(record => record.split(/\r?\n/))
     .filter(line => line !== '' && !line.startsWith('#'))
@@ -282,7 +296,7 @@ export function resolveTranslationPairingConflicts(root: string): string[] {
       const ancestorRecord = readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8')
       const currentRecord = readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8')
       const otherRecord = readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8')
-      assertUneditedSidecar(root, metaPath, currentRecord, otherRecord)
+      assertUneditedSidecar(root, metaPath, ancestorRecord, currentRecord, otherRecord)
       const result = mergeTranslationPairingRecords(
         root,
         metaPath,

From 58b89fb6b44654f5fedc496e4e5b3b325f17aae4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:50:13 +0800
Subject: [PATCH 147/262] test(i18n): align merge failure fixtures

---
 .../request-response.expected.json            |  4 +-
 scripts/translation-pairing-merge.spec.ts     | 78 +++++++------------
 2 files changed, 28 insertions(+), 54 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 311b0ecc80..ec8c282b80 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index 26f13748ed..118a2023b9 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -58,6 +58,28 @@ function installFixtureRuntime(root: string): void {
   symlinkSync(join(workspaceRoot, 'scripts'), join(root, 'scripts'), linkType)
 }
 
+function startMergeWithFakeNode(
+  fixture: Fixture,
+  nodeScript = '#!/bin/sh\nexit 72\n',
+) {
+  const fakeBin = join(fixture.root, 'fake-bin')
+  const fakeNode = join(fakeBin, 'node')
+  write(fixture.root, 'fake-bin/node', nodeScript)
+  chmodSync(fakeNode, 0o755)
+  git(fixture, [
+    'config',
+    'merge.dsh-translation-pairing.driver',
+    `${shellQuote(driverLauncher)} %O %A %B %P`,
+  ])
+  return spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+    encoding: 'utf8',
+    env: {
+      ...fixture.env,
+      PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+    },
+  })
+}
+
 function createFixture(attributes = true): Fixture {
   const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
   fixtures.push(root)
@@ -327,24 +349,9 @@ describe('translation pairing merge composition', () => {
   it('leaves an ordinary recoverable conflict when the configured runtime is unavailable', () => {
     const fixture = createFixture()
     const records = createDivergedPair(fixture)
-    const fakeBin = join(fixture.root, 'fake-bin')
-    const fakeNode = join(fakeBin, 'node')
-    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
-    chmodSync(fakeNode, 0o755)
-    const command = [
-      shellQuote(driverLauncher),
-      '%O', '%A', '%B', '%P',
-    ].join(' ')
-    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
     const headBefore = git(fixture, ['rev-parse', 'HEAD'])
 
-    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: {
-        ...fixture.env,
-        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
-      },
-    })
+    const result = startMergeWithFakeNode(fixture)
 
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
@@ -366,27 +373,10 @@ describe('translation pairing merge composition', () => {
   it('falls back before a broken driver entrypoint can replace the launcher', () => {
     const fixture = createFixture()
     createDivergedPair(fixture)
-    const fakeBin = join(fixture.root, 'fake-bin')
-    const fakeNode = join(fakeBin, 'node')
-    write(
-      fixture.root,
-      'fake-bin/node',
+    const result = startMergeWithFakeNode(
+      fixture,
       '#!/bin/sh\nif [ "$3" = "--eval" ]; then exit 0; fi\nexit 72\n',
     )
-    chmodSync(fakeNode, 0o755)
-    git(fixture, [
-      'config',
-      'merge.dsh-translation-pairing.driver',
-      `${shellQuote(driverLauncher)} %O %A %B %P`,
-    ])
-
-    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: {
-        ...fixture.env,
-        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
-      },
-    })
 
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
@@ -398,23 +388,7 @@ describe('translation pairing merge composition', () => {
   it('keeps a clean text fallback unresolved until the explicit resolver confirms it', () => {
     const fixture = createFixture()
     createTextCleanDivergedPair(fixture)
-    const fakeBin = join(fixture.root, 'fake-bin')
-    const fakeNode = join(fakeBin, 'node')
-    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
-    chmodSync(fakeNode, 0o755)
-    git(fixture, [
-      'config',
-      'merge.dsh-translation-pairing.driver',
-      `${shellQuote(driverLauncher)} %O %A %B %P`,
-    ])
-
-    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: {
-        ...fixture.env,
-        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
-      },
-    })
+    const result = startMergeWithFakeNode(fixture)
 
     expect(result.status).toBe(1)
     expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')

From f34b2bb634b4959beb342b4cb6bdb38235b08a5c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:51:56 +0800
Subject: [PATCH 148/262] ci(e2b): add manual live sandbox workflow

---
 .github/workflows/e2b-e2e.yml | 58 +++++++++++++++++++++++++++++++++++
 scripts/ci-workflow.spec.ts   | 27 ++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 .github/workflows/e2b-e2e.yml

diff --git a/.github/workflows/e2b-e2e.yml b/.github/workflows/e2b-e2e.yml
new file mode 100644
index 0000000000..abbd0482ed
--- /dev/null
+++ b/.github/workflows/e2b-e2e.yml
@@ -0,0 +1,58 @@
+name: E2E (E2B sandbox)
+
+# This suite provisions external E2B sandboxes and is intentionally opt-in.
+# It has no push, pull_request, schedule, or workflow_call trigger.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # CI runs must never report to the production telemetry endpoint baked
+  # into apps/cli/cordis.yml (AppCLIEntry disables the row when set).
+  DSH_TELEMETRY_DISABLED: '1'
+
+jobs:
+  e2b:
+    runs-on: ubuntu-latest
+    name: E2B live Loader composition
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install (immutable)
+        run: pnpm install --frozen-lockfile
+
+      # The tests self-skip locally when the credential is absent. A manually
+      # dispatched run must fail instead of reporting an all-skipped green.
+      - name: Preflight (require E2B API key)
+        env:
+          E2B_API_KEY: ${{ secrets.E2B_API_KEY_EXTERNAL }}
+        run: |
+          set -euo pipefail
+          if [ -z "${E2B_API_KEY:-}" ]; then
+            echo "::error::E2B_API_KEY is empty. Configure the E2B_API_KEY_EXTERNAL repository secret."
+            exit 1
+          fi
+          echo "E2B_API_KEY present."
+
+      # The Loader smoke runs package exports under plain Node in lib mode.
+      - name: Build (lib for the E2B Loader smoke)
+        run: pnpm run build
+
+      - name: E2B tests (live sandbox)
+        env:
+          E2B_API_KEY: ${{ secrets.E2B_API_KEY_EXTERNAL }}
+          DSH_E2E_MAX_WORKERS: '1'
+          DSH_EXAMPLE_MODE: lib
+        run: >-
+          pnpm exec vitest run --config vitest.e2e.config.ts
+          packages/e2b/e2b/tests/composition.e2e.ts
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index baeac7a8c0..0395fe8c36 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -28,6 +28,33 @@ describe('CI workflow', () => {
   })
 })
 
+describe('E2B e2e workflow', () => {
+  it('is manual-only and fails loud before running the focused live suite', () => {
+    const workflow = loadWorkflow('.github/workflows/e2b-e2e.yml')
+    expect(workflow.on).toEqual({ workflow_dispatch: null })
+    if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.e2b) || !Array.isArray(workflow.jobs.e2b.steps)) {
+      throw new TypeError('E2B e2e workflow must define the e2b job steps')
+    }
+
+    const steps = workflow.jobs.e2b.steps.filter(isRecord)
+    const preflight = steps.find(step => step.name === 'Preflight (require E2B API key)')
+    const e2b = steps.find(step => step.name === 'E2B tests (live sandbox)')
+
+    expect(preflight).toMatchObject({
+      env: { E2B_API_KEY: '${{ secrets.E2B_API_KEY_EXTERNAL }}' },
+    })
+    expect(preflight?.run).toContain('E2B_API_KEY_EXTERNAL repository secret')
+    expect(e2b).toMatchObject({
+      env: {
+        E2B_API_KEY: '${{ secrets.E2B_API_KEY_EXTERNAL }}',
+        DSH_E2E_MAX_WORKERS: '1',
+        DSH_EXAMPLE_MODE: 'lib',
+      },
+    })
+    expect(e2b?.run).toContain('packages/e2b/e2b/tests/composition.e2e.ts')
+  })
+})
+
 describe('Issue lifecycle workflow', () => {
   it('uses review signals instead of rerunning when a draft becomes ready', () => {
     const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')

From 645fcf57137a82000f115aaabb7500b8682d6391 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 00:53:05 +0800
Subject: [PATCH 149/262] docs(agent-note): propose packages/ regrouping by
 measured clustering

RFC settling the target group map: fold the session family into one
session/ group, dissolve ui/ into interaction/ (+tui), boot/, and the
scaffold/ developer-tooling family (absorbing jsonrpc as server),
merge timeout/ into guard/, and rename cordis/ to self-modification/.
Zero npm renames now; five FIXME-tracked intended renames. Squash of
the reviewed RFC iterations (turtle1999 map corrections applied).
---
 .../2026-07-29-package-regrouping.i18n.yaml   |   6 +
 .../2026-07-29-package-regrouping.md          | 106 ++++++++++++++++++
 .../2026-07-29-package-regrouping.zh.md       | 106 ++++++++++++++++++
 3 files changed, 218 insertions(+)
 create mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
 create mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
 create mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md

diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
new file mode 100644
index 0000000000..cdd772386f
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.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 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
+2026-07-29-package-regrouping.md: 9a56f9f5f1e0aef7d1f9efe60168ec1b0f41cce8
+2026-07-29-package-regrouping.zh.md: c49c5a1daffaff599f70f36b62e4dd3b5de3e5cf
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
new file mode 100644
index 0000000000..9a56f9f5f1
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
@@ -0,0 +1,106 @@
+# Agent Note: Regroup packages/ by measured clustering
+
+Status: proposed
+
+English | [中文](2026-07-29-package-regrouping.zh.md)
+
+## Problem
+
+The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../archived/architecture/2026-06-20-package-hierarchy.md)) has drifted since June: 167 packages now sit in 40 groups, and several group boundaries no longer match how the packages actually cluster.
+
+- `ui/` mixes four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the `sdk/` stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrates the mixture instead of stating a role.
+- The session family is fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
+- Two group names collide with unrelated packages: `telemetry/` (session reporting) vs `sdk/telemetry` = `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
+- `cordis/` names its group after the framework every package is built on, so the name discriminates nothing; its single package `tool-cordis` is the runtime self-modification toolset.
+- `sdk/` folder names are inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeat the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` do not.
+
+The north star for the regrouping: **closely clustered packages share a group.** A cluster is measured — peer-dependency edges and co-change — not thematic. An isolated seam family may stand alone as a small group; the failure mode to avoid is the grab-bag whose name describes no single role.
+
+## Proposal
+
+Recompose six groups; every other group keeps today's boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names do not change in this reorganization; the folder tree carries the whole change.
+
+| Group | Members (folder names) | From |
+|---|---|---|
+| `session/` | session-persistence, session-persistence-jsonl, session-persistence-sqlite, session-checkpoint-policy, session-projection, session-projection-cache, session-title, session-title-llm, session-title-first-message-llm, session-title-all-messages-llm, session-telemetry, session-telemetry-otel | `session-persistence/` + `session-projection/` + `session-title/` + `telemetry/` |
+| `interaction/` | user-interaction, user-approval, permission, tool-ask-user, commands, tui | `ui/` |
+| `boot/` | app-boot | `ui/` |
+| `scaffold/` | helper, scripts, create-sdk, protocol, client, server, telemetry | `sdk/` + `ui/jsonrpc` |
+| `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
+| `self-modification/` | tool-cordis | `cordis/` |
+
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ends the group-name collision with `dsh-telemetry`.
+- **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
+- **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
+- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is today's `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it says nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style.
+- **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
+- **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
+
+40 groups become 37; the win is clustering correctness and truthful names, not count.
+
+## Deferred renames (FIXME markers)
+
+Five npm names should eventually change, but renaming inside the reorganization would turn a pure-move PR into an import-churn PR. Instead, the implementation adds a `FIXME` to each affected package's module JSDoc naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
+
+| Current npm name | Intended name | Why |
+|---|---|---|
+| `@deepseek-ai/dsh-jsonrpc` | `@deepseek-ai/dsh-sdk-server` | Names the wire encoding, not the role; it is the server half of the SDK protocol |
+| `@deepseek-ai/dsh-telemetry` | `@deepseek-ai/dsh-sdk-telemetry` | Collides with the `dsh-session-telemetry` family; it is launcher-side SDK telemetry |
+| `@deepseek-ai/dsh-helper` | `@deepseek-ai/dsh-sdk-helper` | Indefensibly generic as a published name |
+| `@deepseek-ai/dsh-scripts` | `@deepseek-ai/dsh-sdk-scripts` | Same |
+| `@deepseek-ai/dsh-timeout-policy` | `@deepseek-ai/dsh-timeout-guard` | Suggestion, not settled: aligns the name with its `guard/` home; decide at resolution time |
+
+The first four are settled intent; resolving them converges the SDK wire stack's npm names on `dsh-sdk-*` (the npm prefix names the product stack; the `scaffold/` folder names the role). `@deepseek-ai/create-sdk` keeps its documented npm-initializer exception.
+
+## Implementation
+
+One mechanical PR, landed in a quiet window: a single conflict event for the many open PRs, an atomic documentation update, and pure-move reviewability (`git mv` + path fixes, rename detection intact). If review prefers, the same content splits into a three-PR stack (the session fold; `ui/` dissolution + `scaffold/`; `self-modification/` + `guard/` merge), at the cost of three rebase events for everyone else.
+
+A group move touches: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose (root and `apps/cli` READMEs, 7 script files + 22 docs files measured today; `verify-package-paths` gates the Markdown/TypeScript classes of stragglers). This list conveys the shape of the change, not a file inventory: every remaining group-path referent (workspace configs, test globs, lint keys) is found mechanically at implementation time by the acceptance gates failing loud, which is the repository's own misconfiguration rule.
+
+A group move does not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name (verified by grep before this proposal). Each FIXME lands in the same PR as the move that creates its context.
+
+`client/` and `host/` are out of scope and unchanged. The in-flight `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
+
+## Alternatives considered
+
+**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, sdk edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
+
+**Abstract layer names** (`capability/`, `policy/`, `extension/`, `provider/`). Rejected: they describe every plugin equally badly, and a `capability/` bucket would hold ~50 packages.
+
+**A full npm rename sweep** (`dsh-<group>-<pkg>` for every package). Rejected: npm names are flat, so group-prefixing adds churn across imports, configs, and fixtures with no disambiguation gain; targeted FIXME-tracked renames cover the actual collisions.
+
+**Performing the five renames inside the reorganization.** Rejected in review: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
+
+**A two-way session split** (`session-core/` + `session-utils/`). Rejected: query belongs to neither side cleanly, and `session-core` invites confusion with `core/session` (`dsh-session`, the live in-memory service, which stays in `core/`).
+
+**A three-way session split** (`session-store/` + `session-query/` + `session-utils/`), this RFC's first draft. Rejected in review: `session-utils/` was a negatively-defined annex ("derived, nothing load-bearing depends on it") — the grab-bag shape the north star forbids, and factually wrong besides (`session-query` peer-depends on `dsh-session-title`). The invented compound names also read machine-generated; one plain `session/` group says what a human would say. Query stays standalone in both drafts: it is an independently consumed read surface with its own tool package and backend.
+
+**Recomposing `ui/` as a single `channels/` group** (tui + jsonrpc + acp + interaction seams + boot). Rejected: the same grab-bag under a new name — those packages serve four planes, `jsonrpc`'s measured cluster is the SDK wire stack, and `acp/` is an automation transport, not a human channel.
+
+**A standalone one-package `tui/` group**, this RFC's first draft. Rejected in review: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
+
+**Keeping the group name `sdk/`.** Rejected in review: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
+
+**Moving `app-boot` to `apps/`** (review question). Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
+
+**Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; review settled on `self-modification/` as the plainer term.
+
+**Renaming `context/` to `request-context/`.** Rejected: within this tree the group is unambiguous in situ; the churn is unjustified.
+
+## Acceptance criteria
+
+- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged.
+- Zero npm renames: the workspace package-name set is identical before and after.
+- The five FIXME markers are present, each naming its intended new name.
+- New and updated group READMEs form complete bilingual triplets; the packages/README.md hierarchy table matches the tree; docs/module-graph.md is regenerated.
+- `pnpm run typecheck`, `pnpm run test`, `pnpm run doc-sync`, and `pnpm run hygiene` pass, and the unit/snapshot suites collect the same test files before and after the move (group-scoped globs in test configs must not silently match nothing).
+
+## Risks
+
+- **Open-PR conflicts.** Every open PR touching a moved file must rebase across the move. Mitigated by landing as one PR in a quiet window, publishing the mapping table in the PR body, and the moves being pure renames (rename detection resolves most hunks mechanically).
+- **Reference drift.** Docs or scripts citing old paths can go stale; `verify-package-paths` exists precisely for moved-package drift and runs in `doc-sync`.
+- **Translation load.** Five new group README triplets plus edits to existing pairs land in the implementation PR.
+- **Deferred renames are release blockers by design.** A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
+- **Single-package groups remain** (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
+- **What this gives up:** nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
new file mode 100644
index 0000000000..c49c5a1daf
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
@@ -0,0 +1,106 @@
+# Agent Note: 按实测聚类重新划分 packages/ 分组
+
+Status: proposed
+
+[English](2026-07-29-package-regrouping.md) | 中文
+
+## Problem
+
+两级 `packages/<group>/<pkg>` 层级结构（[原始决策](../../archived/architecture/2026-06-20-package-hierarchy.md)）自 6 月以来已经漂移：167 个包（package）如今坐落在 40 个组里，若干组边界已经对不上这些包的实际聚类。
+
+- `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 `sdk/` 这一栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
+- 会话家族被割裂在五个组里——`session-persistence/`、`session-projection/`、`session-query/`、`session-title/` 与 `telemetry/`——而实测依赖边明明把它们连成一体（query → persistence、title → projection、projection → persistence；见 [docs/module-graph.md](../../../../docs/module-graph.md)）。
+- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `sdk/telemetry` = `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
+- `cordis/` 拿所有包共同依托的框架给自己的组命名，这个名字因此毫无区分度；组里唯一的包 `tool-cordis` 是运行时自我修改工具集。
+- `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
+
+这次重新分组的指导准则：**聚类紧密的包同处一组。**聚类以实测为准（对等依赖边与 co-change），而非按主题归类。孤立的 seam 家族可以自成一个小组；要避免的失败形态，是名字概括不出单一职责的大杂烩组。
+
+## Proposal
+
+重组六个组；其余每个组都保持今天的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。这次重组不改任何 npm 包名；整个变更全部由目录树承载。
+
+| 组 | 成员（目录名） | 来源 |
+|---|---|---|
+| `session/` | session-persistence、session-persistence-jsonl、session-persistence-sqlite、session-checkpoint-policy、session-projection、session-projection-cache、session-title、session-title-llm、session-title-first-message-llm、session-title-all-messages-llm、session-telemetry、session-telemetry-otel | `session-persistence/` + `session-projection/` + `session-title/` + `telemetry/` |
+| `interaction/` | user-interaction、user-approval、permission、tool-ask-user、commands、tui | `ui/` |
+| `boot/` | app-boot | `ui/` |
+| `scaffold/` | helper、scripts、create-sdk、protocol、client、server、telemetry | `sdk/` + `ui/jsonrpc` |
+| `guard/` | repeat-tool-guard、timeout-policy | `guard/` + `timeout/` |
+| `self-modification/` | tool-cordis | `cordis/` |
+
+- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（评审意见：名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
+- **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
+- **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
+- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即今天的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致。
+- **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
+- **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
+
+40 个组变为 37 个；收益在聚类正确与名实相符，不在数量增减。
+
+## Deferred renames (FIXME markers)
+
+五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。实现改为在每个受影响包的模块 JSDoc 里加一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
+
+| 当前 npm 名 | 目标名 | 原因 |
+|---|---|---|
+| `@deepseek-ai/dsh-jsonrpc` | `@deepseek-ai/dsh-sdk-server` | 名字说的是协议编码而非角色；它是 SDK 协议的服务端一半 |
+| `@deepseek-ai/dsh-telemetry` | `@deepseek-ai/dsh-sdk-telemetry` | 与 `dsh-session-telemetry` 家族撞名；它是启动器侧 SDK telemetry |
+| `@deepseek-ai/dsh-helper` | `@deepseek-ai/dsh-sdk-helper` | 作为公开发布名空泛得站不住脚 |
+| `@deepseek-ai/dsh-scripts` | `@deepseek-ai/dsh-sdk-scripts` | 同上 |
+| `@deepseek-ai/dsh-timeout-policy` | `@deepseek-ai/dsh-timeout-guard` | 仅为建议、尚未定案：使名字与其 `guard/` 归属对齐；到解决时再定 |
+
+前四个是已定的意图；兑现之后，SDK 通信栈的 npm 名随之收敛为 `dsh-sdk-*`（npm 前缀指产品栈，`scaffold/` 目录名指角色）。`@deepseek-ai/create-sdk` 保留其文档记载的 npm 初始化器特例。
+
+## Implementation
+
+整个变更作为一个机械化 PR，在低活动窗口期合入：众多开放中的 PR 只经历一次冲突事件，文档得到一次原子更新，评审享有纯移动的可评审性（`git mv` 加路径修正，重命名检测完好）。若评审偏好拆分，同样的内容也可以拆成三个 PR 的堆叠（会话折叠；`ui/` 解散加 `scaffold/`；`self-modification/` 加 `guard/` 合并），代价是其他所有人要经历三次变基事件。
+
+组移动会触及：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文中以仓库根为基准的 `packages/...` 引用（根 README 与 `apps/cli` README、今天实测 7 个脚本文件加 22 个文档文件；`verify-package-paths` 兜住 Markdown／TypeScript 这两类漏网引用）。这份清单陈述的是变更的形态，不是文件清点：其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都在实现时由验收门禁的响亮失败机械地找出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+
+组移动不触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包（提案之前已用 grep 核实）。每条 FIXME 都与创造其上下文的那次移动落在同一个 PR。
+
+`client/` 与 `host/` 不在本次范围内，保持不变。在途的 `experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
+
+## Alternatives considered
+
+**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、sdk 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
+
+**抽象分层名**（`capability/`、`policy/`、`extension/`、`provider/`）。不予采纳：这些名字对每个插件都同样地不达意，而且一个 `capability/` 桶会装下约 50 个包。
+
+**一轮全量 npm 重命名**（每个包都改为 `dsh-<group>-<pkg>`）。不予采纳：npm 包名是扁平的，加组前缀只会在 import、配置和 fixture 之间制造改动，却换不来任何消歧收益；用 FIXME 跟踪的定点改名足以覆盖真正的撞名。
+
+**在重组内部一并完成那五个改名。** 评审中否决：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
+
+**会话两分法**（`session-core/` + `session-utils/`）。不予采纳：query 放哪一侧都不干净，而且 `session-core` 容易与 `core/session` 混淆（后者是 `dsh-session`，常驻内存的实时服务，留在 `core/` 不动）。
+
+**会话三分法**（`session-store/` + `session-query/` + `session-utils/`），即本 RFC 的初稿。评审中否决：`session-utils/` 是靠否定条件圈出来的附属区（「派生的、没有承重方依赖」）——正是指导准则禁止的大杂烩形态，而且事实层面也站不住（`session-query` 对 `dsh-session-title` 声明对等依赖）。杜撰的复合名也读起来不像人起的；一个朴素的 `session/` 组说的就是人会说的话。query 在两版草稿中都保持独立：它是被独立消费的读取面，自带自己的工具包与后端。
+
+**把 `ui/` 重组为单一 `channels/` 组**（tui + jsonrpc + acp + 交互 seam + boot）。不予采纳：不过是换个名字的同一个大杂烩——这些包服务于四个平面，`jsonrpc` 的实测聚类归属是 SDK 通信栈，而 `acp/` 是自动化传输通道，不是人类通道。
+
+**独立的单包 `tui/` 组**，即本 RFC 的初稿。评审中否决：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
+
+**保留组名 `sdk/`。** 评审中否决：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
+
+**把 `app-boot` 挪到 `apps/`**（评审提问）。不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
+
+**把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；评审定为更朴素的 `self-modification/`。
+
+**把 `context/` 改名为 `request-context/`。** 不予采纳：在这棵树里，该组就地看并无歧义；这份改动开销并不值得。
+
+## Acceptance criteria
+
+- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。
+- npm 改名为零：workspace 的包名集合在前后完全相同。
+- 五条 FIXME 标记全部就位，每条都写明其意图中的新名字。
+- 新增与更新的组 README 构成完整的双语三文件配对；packages/README.md 的层级结构表与目录树一致；docs/module-graph.md 已重新生成。
+- `pnpm run typecheck`、`pnpm run test`、`pnpm run doc-sync`、`pnpm run hygiene` 全部通过，且单元／快照套件在移动前后收集到相同的测试文件（测试配置里按组划定的 glob 不得无声地匹配为空）。
+
+## Risks
+
+- **开放 PR 的冲突。** 每个触碰被移动文件的开放 PR 都必须跨过这次移动做变基。缓解方式：作为单个 PR 在低活动窗口期落地、在 PR 正文公布映射表，且移动都是纯改名（重命名检测可机械化解决大多数改动块）。
+- **引用漂移。** 引用旧路径的文档或脚本可能变得陈旧；`verify-package-paths` 正是为包移动造成的漂移而设，并随 `doc-sync`（文档同步门禁）运行。
+- **翻译负担。** 五组新的组 README 三文件配对，加上既有配对的修改，都随实现 PR 一同落地。
+- **推迟的改名按设计就是发布阻塞项。** 日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
+- **单包组依然存在**（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
+- **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。

From 7e445c3a676596b373cc20478384352ad86d8299 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 01:52:06 +0800
Subject: [PATCH 150/262] refactor(session): fold the session family into
 packages/session/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.

Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
---
 .../2026-06-18-session-surface.i18n.yaml      |  4 +-
 .../2026-06-18-session-surface.md             |  6 +--
 .../2026-06-18-session-surface.zh.md          |  6 +--
 ...-07-21-log-backed-session-titles.i18n.yaml |  4 +-
 .../2026-07-21-log-backed-session-titles.md   |  2 +-
 ...2026-07-21-log-backed-session-titles.zh.md |  2 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |  4 +-
 ...26-07-23-session-telemetry-otel-revival.md |  2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |  2 +-
 .../2026-07-06-node-engine-floor.i18n.yaml    |  4 +-
 .../process/2026-07-06-node-engine-floor.md   |  2 +-
 .../2026-07-06-node-engine-floor.zh.md        |  2 +-
 ...-domain-kv-storage-and-workspace.i18n.yaml |  4 +-
 ...6-07-24-domain-kv-storage-and-workspace.md |  4 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md |  2 +-
 ...root-and-derived-medium-recovery.i18n.yaml |  4 +-
 ...torage-root-and-derived-medium-recovery.md |  2 +-
 ...age-root-and-derived-medium-recovery.zh.md |  2 +-
 ...ssembled-assistant-messages-only.i18n.yaml |  4 +-
 ...06-20-assembled-assistant-messages-only.md |  2 +-
 ...20-assembled-assistant-messages-only.zh.md |  2 +-
 ...ld-session-persistence-interface.i18n.yaml |  4 +-
 ...6-20-fold-session-persistence-interface.md |  2 +-
 ...0-fold-session-persistence-interface.zh.md |  2 +-
 ...06-20-truncate-interrupted-turns.i18n.yaml |  4 +-
 .../2026-06-20-truncate-interrupted-turns.md  |  2 +-
 ...026-06-20-truncate-interrupted-turns.zh.md |  2 +-
 AGENTS.md                                     |  2 +-
 docs/architecture.i18n.yaml                   |  4 +-
 docs/architecture.md                          |  4 +-
 docs/architecture.zh.md                       |  4 +-
 docs/capability-seams.md                      | 12 ++---
 .../persistence.i18n.yaml                     |  4 +-
 docs/core-data-structures/persistence.md      |  6 +--
 docs/core-data-structures/persistence.zh.md   |  6 +--
 .../session-title.i18n.yaml                   |  4 +-
 docs/core-data-structures/session-title.md    |  4 +-
 docs/core-data-structures/session-title.zh.md |  4 +-
 docs/persistence-catalog.md                   |  4 +-
 knip.json                                     |  6 +--
 packages/README.i18n.yaml                     |  4 +-
 packages/README.md                            |  5 +-
 packages/README.zh.md                         |  5 +-
 packages/client/runtime/tsconfig.json         |  4 +-
 packages/client/ui-conversation/tsconfig.json |  2 +-
 packages/core/agent-loop/tsconfig.json        |  2 +-
 .../examples/acp-demo/tests/built-bin.e2e.ts  |  4 +-
 packages/examples/acp-demo/tsconfig.json      |  4 +-
 .../examples/agent-spine-demo/tsconfig.json   |  2 +-
 packages/goal/goal/tsconfig.json              |  2 +-
 packages/hooks/hooks-claude/tsconfig.json     |  2 +-
 packages/hooks/hooks-codex/tsconfig.json      |  2 +-
 packages/host/apiproxy/tsconfig.json          |  8 +--
 packages/llm/token-meter/tsconfig.json        |  2 +-
 packages/plan/plan-mode/tsconfig.json         |  2 +-
 packages/sdk/helper/tsconfig.json             |  4 +-
 packages/session-persistence/README.i18n.yaml |  6 ---
 packages/session-persistence/README.md        | 14 ------
 packages/session-persistence/README.zh.md     | 14 ------
 packages/session-projection/README.i18n.yaml  |  6 ---
 packages/session-projection/README.md         | 10 ----
 packages/session-projection/README.zh.md      | 10 ----
 .../session-query-sqlite/tsconfig.json        |  2 +-
 .../session-query/session-query/tsconfig.json |  4 +-
 packages/session-title/README.md              | 14 ------
 packages/session-title/README.zh.md           | 14 ------
 .../README.i18n.yaml                          |  6 +--
 packages/session/README.md                    | 49 +++++++++++++++++++
 packages/session/README.zh.md                 | 49 +++++++++++++++++++
 .../README.i18n.yaml                          |  0
 .../session-checkpoint-policy/README.md       |  0
 .../session-checkpoint-policy/README.zh.md    |  0
 .../session-checkpoint-policy/package.json    |  0
 .../session-checkpoint-policy/src/index.ts    |  0
 .../src/invariant.ts                          |  0
 .../tests/crash-recovery.e2e.ts               |  0
 .../tests/fixtures/crash-child.ts             |  0
 .../tests/session-checkpoint-policy.spec.ts   |  0
 .../session-checkpoint-policy/tsconfig.json   |  2 +-
 .../README.i18n.yaml                          |  0
 .../session-persistence-jsonl/README.md       |  0
 .../session-persistence-jsonl/README.zh.md    |  0
 .../session-persistence-jsonl/package.json    |  0
 .../session-persistence-jsonl/src/format.ts   |  0
 .../session-persistence-jsonl/src/index.ts    |  0
 .../src/invariant.ts                          |  0
 .../session-persistence-jsonl/src/win32.ts    |  0
 .../src/zstd-private-decoder.ts               |  0
 .../src/zstd-public-decoder.ts                |  0
 .../session-persistence-jsonl/src/zstd.ts     |  0
 .../tests/jsonl.spec.ts                       |  0
 .../tests/win32.spec.ts                       |  0
 .../tests/zstd.compat.spec.ts                 |  0
 .../tests/zstd.spec.ts                        |  0
 .../session-persistence-jsonl/tsconfig.json   |  2 +-
 .../README.i18n.yaml                          |  0
 .../session-persistence-sqlite/README.md      |  0
 .../session-persistence-sqlite/README.zh.md   |  0
 .../session-persistence-sqlite/package.json   |  0
 .../session-persistence-sqlite/src/index.ts   |  0
 .../src/invariant.ts                          |  0
 .../session-persistence-sqlite/src/schema.ts  |  0
 .../tests/sqlite.spec.ts                      |  0
 .../session-persistence-sqlite/tsconfig.json  |  2 +-
 .../session-persistence/README.i18n.yaml      |  0
 .../session-persistence/README.md             |  0
 .../session-persistence/README.zh.md          |  0
 .../session-persistence/package.json          |  0
 .../session-persistence/src/coordinator.ts    |  0
 .../session-persistence/src/index.ts          |  0
 .../session-persistence/src/invariant.ts      |  0
 .../session-persistence/src/preparations.ts   |  0
 .../session-persistence/src/revision.ts       |  0
 .../session-persistence/src/write-behind.ts   |  0
 .../session-persistence/tests/contract.ts     |  0
 .../tests/coordinator-contract.ts             |  0
 .../tests/persistence.spec.ts                 |  0
 .../tests/preparations.spec.ts                |  0
 .../tests/write-behind.spec.ts                |  0
 .../session-persistence/tsconfig.json         |  0
 .../session-projection-cache/README.i18n.yaml |  0
 .../session-projection-cache/README.md        |  0
 .../session-projection-cache/README.zh.md     |  0
 .../session-projection-cache/package.json     |  0
 .../session-projection-cache/src/index.ts     |  0
 .../session-projection-cache/src/invariant.ts |  0
 .../session-projection-cache/src/spec.ts      |  0
 .../tests/cache.spec.ts                       |  0
 .../session-projection-cache/tsconfig.json    |  2 +-
 .../session-projection/README.i18n.yaml       |  0
 .../session-projection/README.md              |  0
 .../session-projection/README.zh.md           |  0
 .../session-projection/package.json           |  0
 .../session-projection/src/index.ts           |  0
 .../session-projection/src/invariant.ts       |  0
 .../session-projection/src/types.ts           |  0
 .../session-projection/tests/registry.spec.ts |  0
 .../session-projection/tsconfig.json          |  0
 .../session-telemetry-otel/README.i18n.yaml   |  0
 .../session-telemetry-otel/README.md          |  0
 .../session-telemetry-otel/README.zh.md       |  0
 .../session-telemetry-otel/package.json       |  0
 .../session-telemetry-otel/src/index.ts       |  0
 .../session-telemetry-otel/src/invariant.ts   |  0
 .../session-telemetry-otel/src/user-id.ts     |  0
 .../tests/loader-composition.e2e.ts           |  0
 .../session-telemetry-otel/tests/otel.spec.ts |  0
 .../tests/user-id.spec.ts                     |  0
 .../session-telemetry-otel/tsconfig.json      |  0
 .../session-telemetry/README.i18n.yaml        |  0
 .../session-telemetry/README.md               |  0
 .../session-telemetry/README.zh.md            |  0
 .../session-telemetry/package.json            |  0
 .../session-telemetry/src/coordinator.ts      |  0
 .../session-telemetry/src/index.ts            |  0
 .../session-telemetry/src/invariant.ts        |  0
 .../session-telemetry/tests/redact.spec.ts    |  0
 .../session-telemetry/tests/telemetry.spec.ts |  0
 .../session-telemetry/tsconfig.json           |  0
 .../README.i18n.yaml                          |  0
 .../session-title-all-messages-llm/README.md  |  0
 .../README.zh.md                              |  0
 .../package.json                              |  0
 .../src/index.ts                              |  0
 .../src/invariant.ts                          |  0
 .../tests/provider.spec.ts                    |  0
 .../tsconfig.json                             |  0
 .../README.i18n.yaml                          |  0
 .../session-title-first-message-llm/README.md |  0
 .../README.zh.md                              |  0
 .../package.json                              |  0
 .../src/index.ts                              |  0
 .../src/invariant.ts                          |  0
 .../tests/loader-composition.spec.ts          |  0
 .../tests/provider.e2e.ts                     |  0
 .../tests/provider.spec.ts                    |  0
 .../tsconfig.json                             |  0
 .../session-title-llm/README.i18n.yaml        |  0
 .../session-title-llm/README.md               |  0
 .../session-title-llm/README.zh.md            |  0
 .../session-title-llm/package.json            |  0
 .../session-title-llm/src/index.ts            |  0
 .../session-title-llm/src/invariant.ts        |  0
 .../session-title-llm/tests/llm.spec.ts       |  0
 .../session-title-llm/tsconfig.json           |  0
 .../session-title/README.i18n.yaml            |  0
 .../session-title/README.md                   |  0
 .../session-title/README.zh.md                |  0
 .../session-title/package.json                |  0
 .../session-title/src/client.ts               |  0
 .../session-title/src/index.ts                |  0
 .../session-title/src/invariant.ts            |  0
 .../session-title/src/normalize.ts            |  0
 .../session-title/src/types.ts                |  0
 .../session-title/tests/invariant.spec.ts     |  0
 .../session-title/tests/persistence.spec.ts   |  0
 .../session-title/tests/projection.spec.ts    |  0
 .../session-title/tests/provider.spec.ts      |  0
 .../session-title/tests/rename.spec.ts        |  0
 .../tests/service-contracts.spec.ts           |  0
 .../session-title/tests/session-title.spec.ts |  0
 .../session-title/tsconfig.json               |  2 +-
 packages/subagent/subagent/tsconfig.json      |  2 +-
 packages/telemetry/README.i18n.yaml           |  6 ---
 packages/telemetry/README.md                  | 10 ----
 packages/telemetry/README.zh.md               | 10 ----
 packages/todo/tool-todo/README.i18n.yaml      |  4 +-
 packages/todo/tool-todo/README.md             |  2 +-
 packages/todo/tool-todo/README.zh.md          |  2 +-
 packages/todo/tool-todo/tsconfig.json         |  2 +-
 .../jsonrpc/tests/built-scope-carrier.e2e.ts  |  2 +-
 packages/ui/permission/tsconfig.json          |  2 +-
 packages/workspace/workspace/tsconfig.json    |  2 +-
 scripts/gen-cordis-catalog.ts                 | 12 ++---
 scripts/run-gates.ts                          |  2 +-
 scripts/type-equiv.manifest.json              | 28 +++++------
 .../verify-package-readme-model-experience.ts |  8 +--
 tsconfig.base.json                            | 16 ++----
 tsconfig.host.json                            | 24 ++++-----
 vitest.config.ts                              |  2 +-
 220 files changed, 258 insertions(+), 286 deletions(-)
 delete mode 100644 packages/session-persistence/README.i18n.yaml
 delete mode 100644 packages/session-persistence/README.md
 delete mode 100644 packages/session-persistence/README.zh.md
 delete mode 100644 packages/session-projection/README.i18n.yaml
 delete mode 100644 packages/session-projection/README.md
 delete mode 100644 packages/session-projection/README.zh.md
 delete mode 100644 packages/session-title/README.md
 delete mode 100644 packages/session-title/README.zh.md
 rename packages/{session-title => session}/README.i18n.yaml (71%)
 create mode 100644 packages/session/README.md
 create mode 100644 packages/session/README.zh.md
 rename packages/{session-persistence => session}/session-checkpoint-policy/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/README.md (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/package.json (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tests/crash-recovery.e2e.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tests/fixtures/crash-child.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tsconfig.json (89%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/README.md (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/package.json (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/format.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/win32.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/zstd-private-decoder.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/zstd-public-decoder.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/zstd.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/jsonl.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/win32.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/zstd.compat.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/zstd.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tsconfig.json (87%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/README.md (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/package.json (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/src/schema.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/tests/sqlite.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/tsconfig.json (87%)
 rename packages/{session-persistence => session}/session-persistence/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-persistence/README.md (100%)
 rename packages/{session-persistence => session}/session-persistence/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-persistence/package.json (100%)
 rename packages/{session-persistence => session}/session-persistence/src/coordinator.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/preparations.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/revision.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/write-behind.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/contract.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/coordinator-contract.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/persistence.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/preparations.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/write-behind.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tsconfig.json (100%)
 rename packages/{session-projection => session}/session-projection-cache/README.i18n.yaml (100%)
 rename packages/{session-projection => session}/session-projection-cache/README.md (100%)
 rename packages/{session-projection => session}/session-projection-cache/README.zh.md (100%)
 rename packages/{session-projection => session}/session-projection-cache/package.json (100%)
 rename packages/{session-projection => session}/session-projection-cache/src/index.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/src/invariant.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/src/spec.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/tests/cache.spec.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/tsconfig.json (90%)
 rename packages/{session-projection => session}/session-projection/README.i18n.yaml (100%)
 rename packages/{session-projection => session}/session-projection/README.md (100%)
 rename packages/{session-projection => session}/session-projection/README.zh.md (100%)
 rename packages/{session-projection => session}/session-projection/package.json (100%)
 rename packages/{session-projection => session}/session-projection/src/index.ts (100%)
 rename packages/{session-projection => session}/session-projection/src/invariant.ts (100%)
 rename packages/{session-projection => session}/session-projection/src/types.ts (100%)
 rename packages/{session-projection => session}/session-projection/tests/registry.spec.ts (100%)
 rename packages/{session-projection => session}/session-projection/tsconfig.json (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/README.i18n.yaml (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/README.md (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/README.zh.md (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/package.json (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/src/index.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/src/invariant.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/src/user-id.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tests/loader-composition.e2e.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tests/otel.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tests/user-id.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tsconfig.json (100%)
 rename packages/{telemetry => session}/session-telemetry/README.i18n.yaml (100%)
 rename packages/{telemetry => session}/session-telemetry/README.md (100%)
 rename packages/{telemetry => session}/session-telemetry/README.zh.md (100%)
 rename packages/{telemetry => session}/session-telemetry/package.json (100%)
 rename packages/{telemetry => session}/session-telemetry/src/coordinator.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/src/index.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/src/invariant.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/tests/redact.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/tests/telemetry.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/README.md (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/README.zh.md (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/package.json (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/src/index.ts (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/tests/provider.spec.ts (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/README.md (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/README.zh.md (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/package.json (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/src/index.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tests/loader-composition.spec.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tests/provider.e2e.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tests/provider.spec.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title-llm/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title-llm/README.md (100%)
 rename packages/{session-title => session}/session-title-llm/README.zh.md (100%)
 rename packages/{session-title => session}/session-title-llm/package.json (100%)
 rename packages/{session-title => session}/session-title-llm/src/index.ts (100%)
 rename packages/{session-title => session}/session-title-llm/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title-llm/tests/llm.spec.ts (100%)
 rename packages/{session-title => session}/session-title-llm/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title/README.md (100%)
 rename packages/{session-title => session}/session-title/README.zh.md (100%)
 rename packages/{session-title => session}/session-title/package.json (100%)
 rename packages/{session-title => session}/session-title/src/client.ts (100%)
 rename packages/{session-title => session}/session-title/src/index.ts (100%)
 rename packages/{session-title => session}/session-title/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title/src/normalize.ts (100%)
 rename packages/{session-title => session}/session-title/src/types.ts (100%)
 rename packages/{session-title => session}/session-title/tests/invariant.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/persistence.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/projection.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/provider.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/rename.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/service-contracts.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/session-title.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tsconfig.json (90%)
 delete mode 100644 packages/telemetry/README.i18n.yaml
 delete mode 100644 packages/telemetry/README.md
 delete mode 100644 packages/telemetry/README.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index 7c05a0ada8..911d0709f1 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: eeac53534c70099e4102aff9ef226702ea939654
-2026-06-18-session-surface.zh.md: c58d3da049cd6c18e564e596354f5d1831c4756f
+2026-06-18-session-surface.md: 1bb3baac5e9bea3f657cbd3be2623223bda78ce2
+2026-06-18-session-surface.zh.md: bfbfd097ffeca59dec163dff911315d0ed94d028
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index eeac53534c..1bb3baac5e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -64,9 +64,9 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 
 - **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array for candidate acceptance and live projection; `SessionSurface` is its readonly public view. `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants).
 - **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Chunk seqs are collected for `assistant/message` provenance; `tool/call` seqs are captured for `tool/result` provenance.
-- **`packages/session-persistence/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
-- **`packages/session-persistence/session-persistence-jsonl`**: No changes required.
-- **`packages/session-persistence/session-persistence`**: Abstract interface unchanged.
+- **`packages/session/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
+- **`packages/session/session-persistence-jsonl`**: No changes required.
+- **`packages/session/session-persistence`**: Abstract interface unchanged.
 
 The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index c58d3da049..bfbfd097ff 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -64,9 +64,9 @@ export type SurfaceOp =
 
 - **`packages/core/session`**：`surface.ts`（`SurfaceManager`）维护一个用于候选接纳和实时投影的有序 seq 数组；`SessionSurface` 是其只读公共视图。`SurfaceOp`/`SurfaceIntent` 与顶层会话事件字段记录条目如何加入它。`append()` 要求 surface 事件携带 `SurfaceIntent`，`deriveMessages()` 以遍历 surface 作为唯一派生路径，`repair.ts` 则发出 surface 感知的闭合事件。种子构造函数拒绝缺少 `surfaceOp` 标记的可进入 surface 的种子事件（见「不变式」一节）。
 - **`packages/core/agent-loop`**：所有涉及 surface 事件的追加操作都传入 surface 选项。收集分片 seq 用于 `assistant/message` 溯源；捕获 `tool/call` seq 用于 `tool/result` 溯源。
-- **`packages/session-persistence/session-persistence-sqlite`**：`events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）；`SCHEMA_VERSION` 递增（bump-and-reject，无迁移）。
-- **`packages/session-persistence/session-persistence-jsonl`**：无需改动。
-- **`packages/session-persistence/session-persistence`**：抽象接口不变。
+- **`packages/session/session-persistence-sqlite`**：`events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）；`SCHEMA_VERSION` 递增（bump-and-reject，无迁移）。
+- **`packages/session/session-persistence-jsonl`**：无需改动。
+- **`packages/session/session-persistence`**：抽象接口不变。
 
 Surface 是未来历史操纵的基础。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index 5c5054b0c9..e109560a2f 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.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 .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
-2026-07-21-log-backed-session-titles.md: 5f4c53a5fb866663bbfaae6b3fdafb4660424804
-2026-07-21-log-backed-session-titles.zh.md: f9629c1109c8428c74270de9475423d29b99e8f1
+2026-07-21-log-backed-session-titles.md: 89e6e67fb9ece4c087ba7b1bc52e61b78b94586c
+2026-07-21-log-backed-session-titles.zh.md: 4df21be565f57db056f506df477f665908d1fdfa
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
index 5f4c53a5fb..89e6e67fb9 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
@@ -12,7 +12,7 @@ Session identity metadata is immutable, and the event log is the replay and fork
 
 ## Decision
 
-The [`session-title` capability family](../../../../packages/session-title/README.md) owns title state and generation policy. `@deepseek-ai/dsh-session-title` provides `ctx.sessionTitle`, a deterministic first-message fallback, and a registry for at most one optional asynchronous provider. `@deepseek-ai/dsh-session-title-llm` owns the common auxiliary-model request policy; separate first-message and all-user-messages plugins choose input cadence. The shared agent spine mounts only the fallback service. The Web host mounts that service plus the first-message model provider with explicit overridable limits, so a fresh Web session gains an immediate fallback and then a non-blocking model summary. Other compositions choose either model provider explicitly.
+The [`session-title` capability family](../../../../packages/session/README.md) owns title state and generation policy. `@deepseek-ai/dsh-session-title` provides `ctx.sessionTitle`, a deterministic first-message fallback, and a registry for at most one optional asynchronous provider. `@deepseek-ai/dsh-session-title-llm` owns the common auxiliary-model request policy; separate first-message and all-user-messages plugins choose input cadence. The shared agent spine mounts only the fallback service. The Web host mounts that service plus the first-message model provider with explicit overridable limits, so a fresh Web session gains an immediate fallback and then a non-blocking model summary. Other compositions choose either model provider explicitly.
 
 ### Event ownership and folding
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index f9629c1109..4df21be565 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-[`session-title` 功能包族](../../../../packages/session-title/README.md)负责标题状态和生成策略。`@deepseek-ai/dsh-session-title` 提供 `ctx.sessionTitle`、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。`@deepseek-ai/dsh-session-title-llm` 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载回退服务。Web host 会挂载该服务和首消息模型提供方，并显式设置可覆盖的限制，因此新建的 Web 会话会立即获得回退标题，随后在不阻塞主响应的情况下获得模型摘要。其他组合需显式选择任一模型提供方。
+[`session-title` 功能包族](../../../../packages/session/README.md)负责标题状态和生成策略。`@deepseek-ai/dsh-session-title` 提供 `ctx.sessionTitle`、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。`@deepseek-ai/dsh-session-title-llm` 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载回退服务。Web host 会挂载该服务和首消息模型提供方，并显式设置可覆盖的限制，因此新建的 Web 会话会立即获得回退标题，随后在不阻塞主响应的情况下获得模型摘要。其他组合需显式选择任一模型提供方。
 
 ### 事件归属与折叠
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index 27786e85a2..58b5371ba2 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: f83128e8bf62e0718e59912c16c4e449855aaa1a
-2026-07-23-session-telemetry-otel-revival.zh.md: bef3bd9cbc22f363b92880864651dcaa782fc1de
+2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
+2026-07-23-session-telemetry-otel-revival.zh.md: 4e834f8b129e2062064cf3497370fecf6f88db29
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index f83128e8bf..e6a213af65 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -10,7 +10,7 @@ Every deployment that wants harness sessions in an observability stack must hand
 
 ## Decision
 
-`packages/telemetry/` revives the two reviewed packages under the SDK stance — the harness provides the capability, the deployment configures where records go and owns what leaves in them:
+`packages/session/` (formerly `telemetry/`) revives the two reviewed packages under the SDK stance — the harness provides the capability, the deployment configures where records go and owns what leaves in them:
 
 - **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: live adoption with cursor read-back and the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), buffer-free on-demand replay from the canonical log, the fixed first-chunk-per-(turn, step) projection, the live `agent/error` relay, and live dispose-time `shutdown` records.
 - **The `telemetry/record` waterfall** — the delta over the branch version and the seam's redaction extension point. Every record passes it before reaching any backend; the seam ships NO rules of its own — the innermost `next()` is a pass-through, deployments mount their rules as listeners (stacking by transforming `next()`'s return value), and a throwing rule withholds the record fail-closed. Redaction applies to the exported copy only; the canonical log is never rewritten.
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index bef3bd9cbc..4e834f8b12 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`packages/telemetry/` 以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
+`packages/session/`（原 `telemetry/`）以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
 
 - **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时收养与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
 - **`telemetry/record` waterfall（瀑布式事件）** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何后端前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
index d96a3b4d6c..ddca590dea 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.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 .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
-2026-07-06-node-engine-floor.md: e42b809f83fe388526ecbd74192989e0bcdbba67
-2026-07-06-node-engine-floor.zh.md: 92fa00f7a270f4506cba6c899e9edf6a2fdd3209
+2026-07-06-node-engine-floor.md: ad21fbfe034cbf4bb7b75aaac4113f3139a1832d
+2026-07-06-node-engine-floor.zh.md: 0d1c31ed74565f9b20116cd0e666246baad9bf79
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
index e42b809f83..ad21fbfe03 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
@@ -14,7 +14,7 @@ Set `engines.node` to `^22.19.0 || >=24.0.0` and test keyless CI on `['22.19', 2
 
 Two Node features gate the source runtime:
 
-- **`node:sqlite`** — `packages/session-persistence/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
+- **`node:sqlite`** — `packages/session/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
 - **Native TypeScript type-stripping** — the built-mode `examples/headless-agent/tests/keyless-smoke.e2e.ts` smoke boots its unexported `.ts` driver under plain `node` (no tsx) and loads the example's `.ts` test adapter (`cli-mock-llm.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.
 
 Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use.
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
index 92fa00f7a2..0d1c31ed74 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 两个 Node 特性决定了源码运行时的门槛：
 
-- **`node:sqlite`**：`packages/session-persistence/session-persistence-sqlite` 在顶层执行 `import { DatabaseSync } from 'node:sqlite'`。该模块在 **22.13**（LTS）和 **23.4**（Current）取消了 `--experimental-sqlite` 标志要求；在此之前，导入它会在加载时抛出异常。
+- **`node:sqlite`**：`packages/session/session-persistence-sqlite` 在顶层执行 `import { DatabaseSync } from 'node:sqlite'`。该模块在 **22.13**（LTS）和 **23.4**（Current）取消了 `--experimental-sqlite` 标志要求；在此之前，导入它会在加载时抛出异常。
 - **原生 TypeScript 类型剥离**——构建模式的 `examples/headless-agent/tests/keyless-smoke.e2e.ts` 冒烟测试使用纯 `node`（无 tsx）启动该示例未导出的 `.ts` driver，并加载示例的 `.ts` 测试适配器（`cli-mock-llm.ts`）。类型剥离从 **22.18**（LTS）和 **23.6**（Current）起成为默认行为；更早版本需要 `--experimental-strip-types`。
 
 这些源码特性在 22.x 线上于 **22.18** 全部就绪，但已安装的 Pi 适配器依赖将宣传的 LTS 下限进一步提高。`@deepseek-ai/dsh-llm-pi-ai` 依赖 `@earendil-works/pi-ai@0.79.3`，后者的包声明 `engines.node >=22.19.0`，因此 LTS 下限为 **22.19**。24.x 分支保持 `>=24.0.0`。该不相交范围完全排除了 Node 23：Node 23.0–23.5 至少还有一个源码特性需要标志，而 23 线是非 LTS/已 EOL 的，宣传 `>=23.6` 会增加一条已终止的发布线和一条 CI 分支，而没有任何部署应当使用它。
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 176097ad5e..620fa2291f 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.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 .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
-2026-07-24-domain-kv-storage-and-workspace.md: 230877628428dc88dbddeecfe5f4353cf15e151d
-2026-07-24-domain-kv-storage-and-workspace.zh.md: cb1fb1346a28b0c3249848705ca209f57cab766e
+2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
+2026-07-24-domain-kv-storage-and-workspace.zh.md: 15460e305d2d9aca3009025cf0218eb6c54c7237
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
index 2308776284..1cb2bc4b29 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-24-domain-kv-storage-and-workspace.zh.md)
 
 ## Problem
 
-The host's only persistence surface is the session event log (`packages/session-persistence`: append-only, one file per session). Anything that does not belong to a single session has nowhere to live, and two real needs exist today:
+The host's only persistence surface is the session event log (`packages/session/session-persistence`: append-only, one file per session). Anything that does not belong to a single session has nowhere to live, and two real needs exist today:
 
 - **The workspace entity.** The GUI needs workspace as a real object: path, title, and the list of owned sessions. Ownership belongs to the workspace — "which sessions belong to this workspace" is not any single session's fact, so writing it into the session log is semantically wrong. Until now workspace was only a sidebar visual grouping derived from cwd, with no entity (that conclusion has been overturned).
 - **Dynamic session metadata** (the foreseeable second consumer). Cold session listings read only the first log line (an immutable creation-time snapshot); title, terminal status, and anything that evolves with the session is unavailable. The fix direction is a sidecar metadata table — exactly a KV table with high-frequency per-key updates.
@@ -26,7 +26,7 @@ Create the `packages/storage/` group — the `ctx.storage` hub (backend registry
 | `@deepseek-ai/dsh-storage-sqlite` | `packages/storage/storage-sqlite/` | registers backend `sqlite` | ✓ |
 | `@deepseek-ai/dsh-storage-domain` | `packages/storage/storage-domain/` | mounts `ctx.storage.domain` | ✓ |
 | `@deepseek-ai/dsh-workspace` | `packages/workspace/workspace/` | `ctx.workspace` | ✓ |
-| `SessionPersistence.delete` extension + cascade orchestration | `packages/session-persistence/*` | new method on the existing seam | ✗ future work (session side untouched this phase) |
+| `SessionPersistence.delete` extension + cascade orchestration | `packages/session/session-persistence*` | new method on the existing seam | ✗ future work (session side untouched this phase) |
 | `workspace.*` / `session.delete` RPC, GUI wiring, boot assembly | — | — | ✗ next phase |
 
 (workspace lives in its own group rather than `packages/host/`: the host group's naming rule requires the `dsh-host-*` prefix while this package is named `dsh-workspace`; and the workspace entity is a domain concept, not bound to the host assembly tier. Unrelated to the existing `workspace-context` package — that is an AGENTS.md instruction loader.)
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index cb1fb1346a..15460e305d 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -26,7 +26,7 @@ host 侧唯一的持久化面是 session 事件日志（`packages/session-persis
 | `@deepseek-ai/dsh-storage-sqlite` | `packages/storage/storage-sqlite/` | 注册后端 `sqlite` | ✓ |
 | `@deepseek-ai/dsh-storage-domain` | `packages/storage/storage-domain/` | 挂载 `ctx.storage.domain` | ✓ |
 | `@deepseek-ai/dsh-workspace` | `packages/workspace/workspace/` | `ctx.workspace` | ✓ |
-| `SessionPersistence.delete` 扩面 + 级联删编排 | `packages/session-persistence/*` | 既有 seam 新方法 | ✗ future work（本期不动 session 侧） |
+| `SessionPersistence.delete` 扩面 + 级联删编排 | `packages/session/*` | 既有 seam 新方法 | ✗ future work（本期不动 session 侧） |
 | `workspace.*` / `session.delete` RPC、GUI 接线、boot 组装 | — | — | ✗ 下期 |
 
 （workspace 放独立组不放 `packages/host/`：host 组命名规则要求 `dsh-host-*` 前缀，而包名定为 `dsh-workspace`；且 workspace 实体是领域概念，不绑定 host 装配层。与既有 `workspace-context` 包无关——那是 AGENTS.md 指令加载器。）
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
index f1bd359e19..040d099f38 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.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 .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
-2026-07-28-storage-root-and-derived-medium-recovery.md: 2edb60d204da736bf14ace6278fa4ee7b9e4b8f7
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 802ca16f399446777203581d246444e53d632a34
+2026-07-28-storage-root-and-derived-medium-recovery.md: c7b423770fcca89c54d3866db7701348351cc259
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 54a2bbc6496bd8cce594b3ce3a105e4be6e8ff64
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
index 2edb60d204..c7b423770f 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-28-storage-root-and-derived-medium-recovery.zh.md)
 
 The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
 
-**Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session-persistence/session-persistence-jsonl/src/index.ts).
+**Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session/session-persistence-jsonl/src/index.ts).
 
 **How recovery works today.** Inside a healthy medium the cache is fully self-healing by design: a `stateVersion`-mismatched row is discarded and refolded, a log shrunk below a row's watermark is detected by the anchored restore floor and answered with one full re-read, and every background write is fail-soft. But at the *medium* level there is no recovery at all: a truncated, hand-edited, or version-bumped `session_projcache.json` fails `openJsonUnit` with `malformed-medium`/`version-mismatch` (packages/storage/storage-json/src/format.ts), a schema-drifted record fails domain open with `invalid-record` (packages/storage/storage-domain/src/index.ts), the rejection propagates through `SessionProjectionCache[Service.init]`, and under the CLI's fail-loud boot the assembly refuses to start. A file whose entire content is rebuildable from session logs can brick boot. This contradicts the cache package's own stated stance ("a stale or unreadable cache costs a longer tail replay, never a wrong value") and the cache domain spec's JSDoc ("version bumps discard the whole medium"), which today describes an aspiration, not the implementation. The same fail-loud path is *correct* for `workspace.json` — workspace records are authoritative, not derivable — so the missing concept is a per-domain declaration of authority, not a global behavior change.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
index 802ca16f39..54a2bbc649 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 持久投影缓存（[RFC](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
 
-**文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session-persistence/session-persistence-jsonl/src/index.ts）。
+**文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session/session-persistence-jsonl/src/index.ts）。
 
 **现在是怎么恢复的。** 在健康介质内部，缓存按设计完全自愈：`stateVersion` 不匹配的行被丢弃重折，日志缩短到行水位以下由带锚的 restore floor 检出并以一次全量重读回答，每次后台写都是 fail-soft。但在*介质*层面完全没有恢复：被截断、被手改或版本被 bump 的 `session_projcache.json` 会让 `openJsonUnit` 以 `malformed-medium`/`version-mismatch` 失败（packages/storage/storage-json/src/format.ts），schema 漂移的记录让域 open 以 `invalid-record` 失败（packages/storage/storage-domain/src/index.ts），拒绝一路穿过 `SessionProjectionCache[Service.init]`，在 CLI 的 fail-loud 启动下整个组装拒绝启动。一个内容完全可从会话日志重建的文件能把启动搞死。这与缓存包自己声明的立场（"a stale or unreadable cache costs a longer tail replay, never a wrong value"）和缓存域 spec 的 JSDoc（"version bumps discard the whole medium"）相矛盾——后者今天描述的是愿望而非实现。同一条 fail-loud 路径对 `workspace.json` 却是*正确*的——工作区记录是权威数据，不可派生——所以缺的概念是按域声明权威性，而不是全局改行为。
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
index e252ed8190..d9dd98233e 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.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 .agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
-2026-06-20-assembled-assistant-messages-only.md: ba8135a3d63f292cfedd23de8b4b9d43b4455e8c
-2026-06-20-assembled-assistant-messages-only.zh.md: 5d29655a0697d05f20e491d28272898a08ec3e0b
+2026-06-20-assembled-assistant-messages-only.md: edc756f71271065ec579a2becb8597190b34cdc8
+2026-06-20-assembled-assistant-messages-only.zh.md: e5f4f8a63a35f5f40c482a4a4855937cc8e6d544
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
index ba8135a3d6..edc756f712 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
@@ -19,7 +19,7 @@ ACP `session/load` can replay prior assistant messages as complete content block
 ## Acceptance criteria
 
 - `SessionEventMap` drops `assistant/chunk`, or marks it as non-persisted if a transitional live event is needed.
-- [Session persistence docs](../../../../packages/session-persistence/session-persistence/README.md) no longer require every stream chunk to be stored verbatim.
+- [Session persistence docs](../../../../packages/session/session-persistence/README.md) no longer require every stream chunk to be stored verbatim.
 - `llm-replay` and ACP snapshots use an explicit replay fixture format or sidecar for model chunks.
 - `session/load` renders completed assistant messages from `assistant/message`.
 - Stored logs get much smaller and remain `seq`-contiguous without chunk holes.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
index 5d29655a06..e5f4f8a63a 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
@@ -19,7 +19,7 @@ ACP `session/load` 可以将先前的 assistant 消息作为完整内容块回
 ## 验收标准
 
 - `SessionEventMap` 移除 `assistant/chunk`，或在需要过渡性实时事件时将其标记为非持久化。
-- [会话持久化文档](../../../../packages/session-persistence/session-persistence/README.md)不再要求逐字存储每个流式分片。
+- [会话持久化文档](../../../../packages/session/session-persistence/README.md)不再要求逐字存储每个流式分片。
 - `llm-replay` 和 ACP 快照使用显式的回放 fixture 格式或伴随文件来存储模型分片。
 - `session/load` 从 `assistant/message` 渲染已完成的 assistant 消息。
 - 存储的日志大幅缩小，且删除分片后仍保持 `seq` 连续，不留下序号缺口。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 0ae596bf03..4c5b2d04de 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.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 .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
-2026-06-20-fold-session-persistence-interface.md: 895b868b2a80d8655284bae1364a85e19e174da7
-2026-06-20-fold-session-persistence-interface.zh.md: d5ce0ed4532706ffadb43460cd0974507393a5ed
+2026-06-20-fold-session-persistence-interface.md: c0da160e766cf0bed532f0d11bd52e3a027dbe8b
+2026-06-20-fold-session-persistence-interface.zh.md: 93ab244429600bd15e2d8dadfa7dc218e37c2eff
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
index 895b868b2a..c0da160e76 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
@@ -22,7 +22,7 @@ The implementing PR should update the [capability seams](../../implemented/archi
 - `dsh-session` exports the persistence service type, coordinator, and contract helpers.
 - JSONL and SQLite backend packages depend on `dsh-session` directly.
 - `agent-loop` resume uses the session-owned service key.
-- [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), [shared persistence write coordinator](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), and [package docs](../../../../packages/session-persistence/session-persistence/README.md) explain why backend implementations remain separate.
+- [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), [shared persistence write coordinator](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), and [package docs](../../../../packages/session/session-persistence/README.md) explain why backend implementations remain separate.
 
 ## What we give up
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index d5ce0ed453..93ab244429 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -22,7 +22,7 @@ Status: rejected — 独立的持久化接口包是为持久化后端设计的
 - `dsh-session` 导出持久化服务类型、协调器和契约辅助工具。
 - JSONL 和 SQLite 后端包直接依赖 `dsh-session`。
 - `agent-loop` 的恢复功能使用会话包拥有的服务键。
-- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session-persistence/session-persistence/README.md)说明后端实现为何仍保持独立。
+- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session/session-persistence/README.md)说明后端实现为何仍保持独立。
 
 ## 放弃了什么
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
index 09f42a9047..7e9b79fdeb 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.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 .agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
-2026-06-20-truncate-interrupted-turns.md: 3c7acf8d673568f851edd52635a28f73d9bf5f6f
-2026-06-20-truncate-interrupted-turns.zh.md: f348e6a99d8214f7968d9f57931f9dddd37973be
+2026-06-20-truncate-interrupted-turns.md: c4b0084de537927a27829eb78990c6559bd1df7d
+2026-06-20-truncate-interrupted-turns.zh.md: 2d3eca74416eff360029e3ac77f04662878a0084
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
index 3c7acf8d67..c4b0084de5 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
@@ -21,7 +21,7 @@ This makes the persisted turn boundary simple: a completed `turn/end` is the che
 - `TurnEndReasonMap` drops the `interrupted` variant.
 - `interruptedTurnClosers()` and its tests disappear.
 - The persistence coordinator's repair hook truncates backend-specific torn/open tail state without appending closers.
-- [Session persistence docs](../../../../packages/session-persistence/session-persistence/README.md) say load returns the last completed turn, plus no partial final turn.
+- [Session persistence docs](../../../../packages/session/session-persistence/README.md) say load returns the last completed turn, plus no partial final turn.
 - Snapshot and contract tests update together with the behavior they pin.
 - The session format version and recorded fixtures are refreshed; non-current stored logs are rejected per the pre-release format policy, with no migration path.
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
index f348e6a99d..2d3eca7441 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
@@ -21,7 +21,7 @@ Status: rejected — 单个轮次可以包含大量真实工作，包括多个
 - `TurnEndReasonMap` 移除 `interrupted` 变体。
 - `interruptedTurnClosers()` 及其测试删除。
 - 持久化协调器的修复钩子截断后端特有的撕裂或未关闭的尾部状态，不追加关闭事件。
-- [会话持久化文档](../../../../packages/session-persistence/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
+- [会话持久化文档](../../../../packages/session/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
 - 快照与契约测试随其所固定的行为一同更新。
 - 会话格式版本与记录的 fixture（测试前置数据）刷新；按预发布格式策略，非当前版本的存储日志被拒绝，不提供迁移路径。
 
diff --git a/AGENTS.md b/AGENTS.md
index 47a90f0065..7727539bd9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,7 +33,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   guard/       loop-hygiene plugins
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
-  session-persistence/  persistence seam + JSONL/SQLite backends
+  session/     durable session data plane: persistence, projection, titles, reporting
   settings/    user-settings seam + file-backed provider
   credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index e0ddc02423..4d10310333 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: e88bdac118e382d91c41c471d03182952d8a4508
-architecture.zh.md: 9314a3fbfc87d467a0f902fa1dae9e8f07e2eb28
+architecture.md: c14d68c47f6ed0786e8fc0b0650dbc67678250fb
+architecture.zh.md: df484762d29e170a5b1ba64f0637c5170c2c5ef4
diff --git a/docs/architecture.md b/docs/architecture.md
index e88bdac118..c14d68c47f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -41,9 +41,9 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | background task registry, generic `task_*` controls |
 | `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | script-driven multi-agent orchestration |
 | `ctx.goals` | [`goal/`](../packages/goal/README.md) | persisted same-session goals |
-| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable session-log storage |
+| `ctx.sessionPersistence` | [`session/`](../packages/session/README.md) | durable session-log storage |
 | `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | live-preferred exact/filter/trace queries over SQLite FTS, workspace-authorized model tools |
-| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | log-backed fallbacks, one optional asynchronous provider |
+| `ctx.sessionTitle` | [`session/session-title`](../packages/session/README.md) | log-backed fallbacks, one optional asynchronous provider |
 | `ctx.settings` | [`settings/`](../packages/settings/README.md) | per-plugin user-settings namespaces layered over composition entries |
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | named secret references resolved per operation, never inlined in configuration |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI-host directory picking (`native`/`browse` interactions) |
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 9314a3fbfc..df484762d2 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -41,9 +41,9 @@
 | `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | 后台任务注册表和通用 `task_*` 控制 |
 | `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | 脚本驱动的多 agent 编排 |
 | `ctx.goals` | [`goal/`](../packages/goal/README.md) | 持久化的同会话目标 |
-| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | 会话日志的持久化存储 |
+| `ctx.sessionPersistence` | [`session/`](../packages/session/README.md) | 会话日志的持久化存储 |
 | `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | 基于 SQLite 全文搜索的实时优先精确检索／过滤／追踪、经工作区授权的模型工具 |
-| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | 基于日志的回退标题和单个可选异步提供方 |
+| `ctx.sessionTitle` | [`session/session-title`](../packages/session/README.md) | 基于日志的回退标题和单个可选异步提供方 |
 | `ctx.settings` | [`settings/`](../packages/settings/README.md) | 按插件划分的用户设置命名空间，分层叠加在装配条目之上 |
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | 具名密钥引用，按操作解析，绝不内联进配置 |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI 宿主目录选取（`native`／`browse` 交互） |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 4ed8a260d4..60a19999f3 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -374,27 +374,27 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
-| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
+| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
 | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
-| `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
+| `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
 | `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
-| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
+| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
 | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
-| `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
-| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
+| `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
+| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/core-data-structures/persistence.i18n.yaml
index fe28a36f40..eccd3f146e 100644
--- a/docs/core-data-structures/persistence.i18n.yaml
+++ b/docs/core-data-structures/persistence.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 docs/core-data-structures/persistence.md
-persistence.md: 3d2bc7ff3b45cd3f38fca0b880a0df9adb928bad
-persistence.zh.md: 035f46d76e0189bd686e991c3d56d486b6f309d5
+persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6
+persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad
diff --git a/docs/core-data-structures/persistence.md b/docs/core-data-structures/persistence.md
index 3d2bc7ff3b..177d596d3d 100644
--- a/docs/core-data-structures/persistence.md
+++ b/docs/core-data-structures/persistence.md
@@ -4,7 +4,7 @@ English | [中文](persistence.zh.md)
 
 The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
 
-The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session-persistence/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
 
 ## The flush checkpoint
 
@@ -202,5 +202,5 @@ interface SessionPersistenceSnapshot {
 
 Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`, proving the seam is genuinely backend-agnostic:
 
-- **[dsh-session-persistence-jsonl](../../packages/session-persistence/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
-- **[dsh-session-persistence-sqlite](../../packages/session-persistence/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
+- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
+- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
diff --git a/docs/core-data-structures/persistence.zh.md b/docs/core-data-structures/persistence.zh.md
index 035f46d76e..6582c0d7d0 100644
--- a/docs/core-data-structures/persistence.zh.md
+++ b/docs/core-data-structures/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session-persistence/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
@@ -202,5 +202,5 @@ interface SessionPersistenceSnapshot {
 
 两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`，证明该 seam 确实与后端无关：
 
-- **[dsh-session-persistence-jsonl](../../packages/session-persistence/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
-- **[dsh-session-persistence-sqlite](../../packages/session-persistence/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
+- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
+- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
diff --git a/docs/core-data-structures/session-title.i18n.yaml b/docs/core-data-structures/session-title.i18n.yaml
index 67f9ac765b..ed9955472c 100644
--- a/docs/core-data-structures/session-title.i18n.yaml
+++ b/docs/core-data-structures/session-title.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 docs/core-data-structures/session-title.md
-session-title.md: fff1aa1f6be45d0cfc4d7f6a9527ccb93561618f
-session-title.zh.md: 77a0a5e94053c94bf84bbc749cb6e260898b5d00
+session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e
+session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e
diff --git a/docs/core-data-structures/session-title.md b/docs/core-data-structures/session-title.md
index fff1aa1f6b..7bced67f07 100644
--- a/docs/core-data-structures/session-title.md
+++ b/docs/core-data-structures/session-title.md
@@ -2,9 +2,9 @@
 
 English | [中文](session-title.zh.md)
 
-Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session-title/session-title). The shared LLM helper owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete event declarations.
+Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session/session-title). The shared LLM helper owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete event declarations.
 
-Sources: [`packages/session-title/session-title/src/index.ts`](../../packages/session-title/session-title/src/index.ts), [`packages/session-title/session-title-llm/src/index.ts`](../../packages/session-title/session-title-llm/src/index.ts)
+Sources: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts), [`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
 
 ## Durable title state
 
diff --git a/docs/core-data-structures/session-title.zh.md b/docs/core-data-structures/session-title.zh.md
index 77a0a5e940..e8e501d3aa 100644
--- a/docs/core-data-structures/session-title.zh.md
+++ b/docs/core-data-structures/session-title.zh.md
@@ -2,9 +2,9 @@
 
 [English](session-title.md) | 中文
 
-[`@deepseek-ai/dsh-session-title`](../../packages/session-title/session-title) 所拥有的持久、后写覆盖的标题状态与可选异步提供方词汇。共享 LLM（大语言模型）辅助组件负责精确的辅助请求记录。各包 README 负责时序、回退、失败与 fork 行为；生成的[持久化日志事件目录](../persistence-catalog.md)负责完整的事件声明。
+[`@deepseek-ai/dsh-session-title`](../../packages/session/session-title) 所拥有的持久、后写覆盖的标题状态与可选异步提供方词汇。共享 LLM（大语言模型）辅助组件负责精确的辅助请求记录。各包 README 负责时序、回退、失败与 fork 行为；生成的[持久化日志事件目录](../persistence-catalog.md)负责完整的事件声明。
 
-源码：[`packages/session-title/session-title/src/index.ts`](../../packages/session-title/session-title/src/index.ts)、[`packages/session-title/session-title-llm/src/index.ts`](../../packages/session-title/session-title-llm/src/index.ts)
+源码：[`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts)、[`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
 
 ## 持久标题状态
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 3845c2cb1a..daf2ea7ab2 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -557,7 +557,7 @@ Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/
 
 Types: [SessionTitleEventData](core-data-structures/session-title.md)
 
-Source: [`packages/session-title/session-title/src/index.ts:100`](../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
 
 #### `session/title-llm-request` — log-only
 
@@ -568,7 +568,7 @@ Source: [`packages/session-title/session-title/src/index.ts:100`](../packages/se
 
 Types: [SessionTitleLlmRequestEventData](core-data-structures/session-title.md)
 
-Source: [`packages/session-title/session-title-llm/src/index.ts:43`](../packages/session-title/session-title-llm/src/index.ts)
+Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
 
 ### `step/*`
 
diff --git a/knip.json b/knip.json
index d154cd646b..0e82064200 100644
--- a/knip.json
+++ b/knip.json
@@ -283,7 +283,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/telemetry/session-telemetry-otel": {
+    "packages/session/session-telemetry-otel": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -414,7 +414,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/session-title/session-title-first-message-llm": {
+    "packages/session/session-title-first-message-llm": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -434,7 +434,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/session-persistence/session-checkpoint-policy": {
+    "packages/session/session-checkpoint-policy": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 143e7704c2..44dd906b76 100644
--- 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: 98fc87a6b26a42c58bb63cba96cd6af384f3ec71
-README.zh.md: 86a316dca77efd5e5eb59e3fca7d53890a34901d
+README.md: 9f8b3f936af6392239218d5389c91c87d0f7d1f9
+README.zh.md: 2f4e86cb541a8a34762b36cac57f456de96cac5d
diff --git a/packages/README.md b/packages/README.md
index 98fc87a6b2..9f8b3f936a 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -39,13 +39,10 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`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 |
+| [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
-| [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service and opt-in LLM providers | Product — stable surface |
 | [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable surface |
 | [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable surface |
-| [`telemetry/`](telemetry/README.md) | Session reporting: capture/redact seam, OTel backend | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 86a316dca7..2f4e86cb54 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -39,13 +39,10 @@
 | [`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：领域折叠单元供给全量值 | 产品：稳定表面 |
+| [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定表面 |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
-| [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务与选用 LLM 提供方 | 产品：稳定表面 |
 | [`settings/`](settings/README.md) | 用户设置 seam + 文件 provider | 产品：稳定表面 |
 | [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` provider | 产品：稳定表面 |
-| [`telemetry/`](telemetry/README.md) | 会话上报：捕获／脱敏 seam、OTel 后端 | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
 | [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index f93546e855..71cfb229a9 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -30,10 +30,10 @@
       "path": "../../compact/compact"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
       "path": "../../llm/llm"
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 04b265bdd5..0505786841 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../runtime"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../llm/token-meter"
diff --git a/packages/core/agent-loop/tsconfig.json b/packages/core/agent-loop/tsconfig.json
index 0949f18453..c3504e4eb4 100644
--- a/packages/core/agent-loop/tsconfig.json
+++ b/packages/core/agent-loop/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../core/system-prompt"
diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index 6f67baa5a5..d09a0e333d 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -34,8 +34,8 @@ const dshPackages = [
   'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
   'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
-  'session-persistence/session-persistence',
-  'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
+  'session/session-persistence',
+  'session/session-checkpoint-policy', 'session/session-persistence-jsonl',
   'acp/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
diff --git a/packages/examples/acp-demo/tsconfig.json b/packages/examples/acp-demo/tsconfig.json
index 6eeffc5eef..34b48fc46a 100644
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -39,10 +39,10 @@
       "path": "../../context/workspace-context"
     },
     {
-      "path": "../../session-persistence/session-checkpoint-policy"
+      "path": "../../session/session-checkpoint-policy"
     },
     {
-      "path": "../../session-persistence/session-persistence-jsonl"
+      "path": "../../session/session-persistence-jsonl"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/examples/agent-spine-demo/tsconfig.json b/packages/examples/agent-spine-demo/tsconfig.json
index f245e9f4d0..e31863d3b1 100644
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
       "path": "../../core/system-prompt"
diff --git a/packages/goal/goal/tsconfig.json b/packages/goal/goal/tsconfig.json
index f106707bd3..1484f5a4b9 100644
--- a/packages/goal/goal/tsconfig.json
+++ b/packages/goal/goal/tsconfig.json
@@ -33,7 +33,7 @@
       "path": "../../core/agent"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../typert/type-meta"
diff --git a/packages/hooks/hooks-claude/tsconfig.json b/packages/hooks/hooks-claude/tsconfig.json
index 445d0f68b1..e254c7146f 100644
--- a/packages/hooks/hooks-claude/tsconfig.json
+++ b/packages/hooks/hooks-claude/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../subagent/subagent"
diff --git a/packages/hooks/hooks-codex/tsconfig.json b/packages/hooks/hooks-codex/tsconfig.json
index 3bd9bd91e5..46e8216404 100644
--- a/packages/hooks/hooks-codex/tsconfig.json
+++ b/packages/hooks/hooks-codex/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../llm/llm"
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 8686a9e468..58c63f5669 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -42,19 +42,19 @@
       "path": "../../core/tools"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
-      "path": "../../session-projection/session-projection-cache"
+      "path": "../../session/session-projection-cache"
     },
     {
       "path": "../../session-query/session-query"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
       "path": "../../session-query/session-query"
diff --git a/packages/llm/token-meter/tsconfig.json b/packages/llm/token-meter/tsconfig.json
index b8b32e36fa..404607f87a 100644
--- a/packages/llm/token-meter/tsconfig.json
+++ b/packages/llm/token-meter/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../compact/compact"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/plan/plan-mode/tsconfig.json b/packages/plan/plan-mode/tsconfig.json
index a9b2d4dccf..6fa3cffbbc 100644
--- a/packages/plan/plan-mode/tsconfig.json
+++ b/packages/plan/plan-mode/tsconfig.json
@@ -33,7 +33,7 @@
       "path": "../../ui/commands"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/sdk/helper/tsconfig.json b/packages/sdk/helper/tsconfig.json
index 528b370a5c..f33033f47f 100644
--- a/packages/sdk/helper/tsconfig.json
+++ b/packages/sdk/helper/tsconfig.json
@@ -19,10 +19,10 @@
       "path": "../../hooks/hooks-codex"
     },
     {
-      "path": "../../session-persistence/session-persistence-jsonl"
+      "path": "../../session/session-persistence-jsonl"
     },
     {
-      "path": "../../session-persistence/session-persistence-sqlite"
+      "path": "../../session/session-persistence-sqlite"
     },
     {
       "path": "../../subagent/tool-subagent"
diff --git a/packages/session-persistence/README.i18n.yaml b/packages/session-persistence/README.i18n.yaml
deleted file mode 100644
index 85eb2bd27d..0000000000
--- a/packages/session-persistence/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/session-persistence/README.md
-README.md: 060f757b3568318b0be4b01b3a10d019d28eac3b
-README.zh.md: 67022565f7dabcbbccee30d5ce60fa559088ca39
diff --git a/packages/session-persistence/README.md b/packages/session-persistence/README.md
deleted file mode 100644
index 060f757b35..0000000000
--- a/packages/session-persistence/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-persistence/ — persistence capability family
-
-English | [中文](README.zh.md)
-
-This family defines durable session persistence, semantic checkpoint policy, and the shipped storage backends.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`session-persistence/`](session-persistence/README.md) | Defines the persistence service and shared write coordination | `ctx.sessionPersistence` |
-| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | Applies semantic durability checkpoints | wraps `ctx.llm` and `ctx.tools` |
-| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | Persists sessions in JSONL files | registers on `ctx.sessionPersistence` |
-| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | Persists sessions in SQLite | registers on `ctx.sessionPersistence` |
-
-The [session-persistence decision](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) records the family design.
diff --git a/packages/session-persistence/README.zh.md b/packages/session-persistence/README.zh.md
deleted file mode 100644
index 67022565f7..0000000000
--- a/packages/session-persistence/README.zh.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-persistence/：持久化能力家族
-
-[English](README.md) | 中文
-
-本家族定义持久会话数据的持久化机制、语义检查点策略以及随产品交付的存储后端。
-
-| 包 | 职责 | ctx 键 |
-|---|---|---|
-| [`session-persistence/`](session-persistence/README.md) | 定义持久化服务和共享写入协调机制 | `ctx.sessionPersistence` |
-| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | 应用语义持久性检查点 | 包装 `ctx.llm` 和 `ctx.tools` |
-| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | 将会话持久化到 JSONL 文件 | 注册到 `ctx.sessionPersistence` |
-| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | 将会话持久化到 SQLite | 注册到 `ctx.sessionPersistence` |
-
-[会话持久化决策](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)记录了该家族的设计。
diff --git a/packages/session-projection/README.i18n.yaml b/packages/session-projection/README.i18n.yaml
deleted file mode 100644
index 5e03069b99..0000000000
--- a/packages/session-projection/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/session-projection/README.md
-README.md: f1fc8337bbea6663915c19f39fdf02f14190370d
-README.zh.md: 3323166f496fabafabcd96abeaec707a28ce552a
diff --git a/packages/session-projection/README.md b/packages/session-projection/README.md
deleted file mode 100644
index f1fc8337bb..0000000000
--- a/packages/session-projection/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# session-projection/ — session projection capability family
-
-English | [中文](README.zh.md)
-
-This family serves current, log-derived per-session state to client carriers.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`session-projection/`](session-projection/README.md) | Defines and drives session projection units | `ctx.sessionProjections` |
-| [`session-projection-cache/`](session-projection-cache/README.md) | Persists and restores projection checkpoints | `ctx.sessionProjectionCache` |
diff --git a/packages/session-projection/README.zh.md b/packages/session-projection/README.zh.md
deleted file mode 100644
index 3323166f49..0000000000
--- a/packages/session-projection/README.zh.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# session-projection/：会话投影能力家族
-
-[English](README.md) | 中文
-
-本家族向客户端载体提供从日志派生的当前逐会话状态。
-
-| 包 | 职责 | ctx 键 |
-|---|---|---|
-| [`session-projection/`](session-projection/README.md) | 定义并驱动会话投影单元 | `ctx.sessionProjections` |
-| [`session-projection-cache/`](session-projection-cache/README.md) | 持久化并恢复投影检查点 | `ctx.sessionProjectionCache` |
diff --git a/packages/session-query/session-query-sqlite/tsconfig.json b/packages/session-query/session-query-sqlite/tsconfig.json
index 1f09565c4a..2a74d8e326 100644
--- a/packages/session-query/session-query-sqlite/tsconfig.json
+++ b/packages/session-query/session-query-sqlite/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-query/session-query/tsconfig.json b/packages/session-query/session-query/tsconfig.json
index 0f17353fee..9e661c1c2c 100644
--- a/packages/session-query/session-query/tsconfig.json
+++ b/packages/session-query/session-query/tsconfig.json
@@ -24,10 +24,10 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-title/README.md b/packages/session-title/README.md
deleted file mode 100644
index c2ccc1cd6d..0000000000
--- a/packages/session-title/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-title/ — log-backed session-title capability family
-
-English | [中文](README.zh.md)
-
-This family derives durable session titles from the session log, with an optional model-backed provider.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`session-title/`](session-title/README.md) | Owns title state, fallback behavior, provider registration, and refresh | `ctx.sessionTitle` |
-| [`session-title-llm/`](session-title-llm/README.md) | Provides shared model-backed title generation | — |
-| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | Titles a session from its first eligible human message | registers on `ctx.sessionTitle` |
-| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | Titles a session from all eligible human messages | registers on `ctx.sessionTitle` |
-
-Deployments may register one model-backed provider; the service retains a deterministic fallback when none is present.
diff --git a/packages/session-title/README.zh.md b/packages/session-title/README.zh.md
deleted file mode 100644
index b8df266a86..0000000000
--- a/packages/session-title/README.zh.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-title/：日志支持的会话标题能力族
-
-[English](README.md) | 中文
-
-该包族从会话日志派生持久会话标题，并支持可选的模型后端 provider。
-
-| 包 | 职责 | ctx key |
-|---|---|---|
-| [`session-title/`](session-title/README.md) | 负责标题状态、回退行为、provider 注册与刷新 | `ctx.sessionTitle` |
-| [`session-title-llm/`](session-title-llm/README.md) | 提供共享的模型标题生成能力 | — |
-| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | 根据第一条合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
-| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | 根据所有合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
-
-部署可注册一个模型后端 provider；未注册时，服务仍提供确定性回退。
diff --git a/packages/session-title/README.i18n.yaml b/packages/session/README.i18n.yaml
similarity index 71%
rename from packages/session-title/README.i18n.yaml
rename to packages/session/README.i18n.yaml
index 2c5d1f2788..b500a64611 100644
--- a/packages/session-title/README.i18n.yaml
+++ b/packages/session/README.i18n.yaml
@@ -1,6 +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/session-title/README.md
-README.md: c2ccc1cd6d329a58f673a9ea5d47ce2f35c9dc41
-README.zh.md: b8df266a861da5cb20a76d0738bba4993218c3d5
+#   pnpm run verify-translation-pairing --write packages/session/README.md
+README.md: 45eff16ad57ec1ccc8ebdd55db82f41b5adfc111
+README.zh.md: 2d67e28ef169f4e4376b2a644a3b842e5835df04
diff --git a/packages/session/README.md b/packages/session/README.md
new file mode 100644
index 0000000000..45eff16ad5
--- /dev/null
+++ b/packages/session/README.md
@@ -0,0 +1,49 @@
+# session/ — durable session data plane
+
+English | [中文](README.zh.md)
+
+The durable family around `core/session`'s live in-memory service: the persistence seam with its storage backends and checkpoint policy, the projection seam that serves whole log-derived values, log-backed titles, and outbound session telemetry. All **product** packages. `session-query/` remains a sibling group: the read/tool surface is consumed independently of persistence internals.
+
+## Persistence
+
+Durable session persistence, semantic checkpoint policy, and the shipped storage backends.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-persistence/`](session-persistence/README.md) | Defines the persistence service and shared write coordination | `ctx.sessionPersistence` |
+| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | Applies semantic durability checkpoints | wraps `ctx.llm` and `ctx.tools` |
+| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | Persists sessions in JSONL files | registers on `ctx.sessionPersistence` |
+| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | Persists sessions in SQLite | registers on `ctx.sessionPersistence` |
+
+The [session-persistence decision](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) records the persistence design.
+
+## Projection
+
+Serves current, log-derived per-session state to client carriers.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-projection/`](session-projection/README.md) | Defines and drives session projection units | `ctx.sessionProjections` |
+| [`session-projection-cache/`](session-projection-cache/README.md) | Persists and restores projection checkpoints | `ctx.sessionProjectionCache` |
+
+## Titles
+
+Derives durable session titles from the session log, with an optional model-backed provider.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-title/`](session-title/README.md) | Owns title state, fallback behavior, provider registration, and refresh | `ctx.sessionTitle` |
+| [`session-title-llm/`](session-title-llm/README.md) | Provides shared model-backed title generation | — |
+| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | Titles a session from its first eligible human message | registers on `ctx.sessionTitle` |
+| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | Titles a session from all eligible human messages | registers on `ctx.sessionTitle` |
+
+Deployments may register one model-backed provider; the service retains a deterministic fallback when none is present.
+
+## Telemetry
+
+Projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The [telemetry decision](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) records the reporting boundary; the [mode decision](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md) records immediate, feedback-gated, and disabled delivery.
+
+| Package | Role |
+|---|---|
+| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
+| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
diff --git a/packages/session/README.zh.md b/packages/session/README.zh.md
new file mode 100644
index 0000000000..2d67e28ef1
--- /dev/null
+++ b/packages/session/README.zh.md
@@ -0,0 +1,49 @@
+# session/：持久会话数据平面
+
+[English](README.md) | 中文
+
+围绕 `core/session` 常驻内存实时服务的持久家族：持久化 seam 连同其存储后端与检查点策略、供出日志派生全量值的投影 seam、日志支持的标题，以及外发会话遥测。全部都是**产品**包（package）。`session-query/` 仍是同级独立组：读取／工具面的消费不依赖持久化内部实现。
+
+## 持久化
+
+持久会话数据的持久化机制、语义检查点策略以及随产品交付的存储后端。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| [`session-persistence/`](session-persistence/README.md) | 定义持久化服务和共享写入协调机制 | `ctx.sessionPersistence` |
+| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | 应用语义持久性检查点 | 包装 `ctx.llm` 和 `ctx.tools` |
+| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | 将会话持久化到 JSONL 文件 | 注册到 `ctx.sessionPersistence` |
+| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | 将会话持久化到 SQLite | 注册到 `ctx.sessionPersistence` |
+
+[会话持久化决策](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)记录了持久化设计。
+
+## 投影
+
+向客户端载体提供从日志派生的当前逐会话状态。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| [`session-projection/`](session-projection/README.md) | 定义并驱动会话投影单元 | `ctx.sessionProjections` |
+| [`session-projection-cache/`](session-projection-cache/README.md) | 持久化并恢复投影检查点 | `ctx.sessionProjectionCache` |
+
+## 标题
+
+从会话日志派生持久会话标题，并支持可选的模型后端 provider。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| [`session-title/`](session-title/README.md) | 负责标题状态、回退行为、provider 注册与刷新 | `ctx.sessionTitle` |
+| [`session-title-llm/`](session-title-llm/README.md) | 提供共享的模型标题生成能力 | — |
+| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | 根据第一条合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
+| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | 根据所有合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
+
+部署可注册一个模型后端 provider；未注册时，服务仍提供确定性回退。
+
+## 遥测
+
+将会话活动投影为外发遥测，并将投递委派给配置的上报后端。[遥测决策](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)记录上报边界；[模式决策](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)记录即时、反馈门控与禁用投递。
+
+| 包 | 职责 |
+|---|---|
+| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
+| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
diff --git a/packages/session-persistence/session-checkpoint-policy/README.i18n.yaml b/packages/session/session-checkpoint-policy/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/README.i18n.yaml
rename to packages/session/session-checkpoint-policy/README.i18n.yaml
diff --git a/packages/session-persistence/session-checkpoint-policy/README.md b/packages/session/session-checkpoint-policy/README.md
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/README.md
rename to packages/session/session-checkpoint-policy/README.md
diff --git a/packages/session-persistence/session-checkpoint-policy/README.zh.md b/packages/session/session-checkpoint-policy/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/README.zh.md
rename to packages/session/session-checkpoint-policy/README.zh.md
diff --git a/packages/session-persistence/session-checkpoint-policy/package.json b/packages/session/session-checkpoint-policy/package.json
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/package.json
rename to packages/session/session-checkpoint-policy/package.json
diff --git a/packages/session-persistence/session-checkpoint-policy/src/index.ts b/packages/session/session-checkpoint-policy/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/src/index.ts
rename to packages/session/session-checkpoint-policy/src/index.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/src/invariant.ts b/packages/session/session-checkpoint-policy/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/src/invariant.ts
rename to packages/session/session-checkpoint-policy/src/invariant.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts b/packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts
rename to packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts b/packages/session/session-checkpoint-policy/tests/fixtures/crash-child.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts
rename to packages/session/session-checkpoint-policy/tests/fixtures/crash-child.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts b/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
rename to packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tsconfig.json b/packages/session/session-checkpoint-policy/tsconfig.json
similarity index 89%
rename from packages/session-persistence/session-checkpoint-policy/tsconfig.json
rename to packages/session/session-checkpoint-policy/tsconfig.json
index 1b81e05951..400f67a53b 100644
--- a/packages/session-persistence/session-checkpoint-policy/tsconfig.json
+++ b/packages/session/session-checkpoint-policy/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-persistence/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/README.i18n.yaml
rename to packages/session/session-persistence-jsonl/README.i18n.yaml
diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/README.md
rename to packages/session/session-persistence-jsonl/README.md
diff --git a/packages/session-persistence/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/README.zh.md
rename to packages/session/session-persistence-jsonl/README.zh.md
diff --git a/packages/session-persistence/session-persistence-jsonl/package.json b/packages/session/session-persistence-jsonl/package.json
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/package.json
rename to packages/session/session-persistence-jsonl/package.json
diff --git a/packages/session-persistence/session-persistence-jsonl/src/format.ts b/packages/session/session-persistence-jsonl/src/format.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/format.ts
rename to packages/session/session-persistence-jsonl/src/format.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/index.ts
rename to packages/session/session-persistence-jsonl/src/index.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/invariant.ts b/packages/session/session-persistence-jsonl/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/invariant.ts
rename to packages/session/session-persistence-jsonl/src/invariant.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session/session-persistence-jsonl/src/win32.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/win32.ts
rename to packages/session/session-persistence-jsonl/src/win32.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd-private-decoder.ts b/packages/session/session-persistence-jsonl/src/zstd-private-decoder.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/zstd-private-decoder.ts
rename to packages/session/session-persistence-jsonl/src/zstd-private-decoder.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd-public-decoder.ts b/packages/session/session-persistence-jsonl/src/zstd-public-decoder.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/zstd-public-decoder.ts
rename to packages/session/session-persistence-jsonl/src/zstd-public-decoder.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd.ts b/packages/session/session-persistence-jsonl/src/zstd.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/zstd.ts
rename to packages/session/session-persistence-jsonl/src/zstd.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
rename to packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session/session-persistence-jsonl/tests/win32.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
rename to packages/session/session-persistence-jsonl/tests/win32.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts
rename to packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
rename to packages/session/session-persistence-jsonl/tests/zstd.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tsconfig.json b/packages/session/session-persistence-jsonl/tsconfig.json
similarity index 87%
rename from packages/session-persistence/session-persistence-jsonl/tsconfig.json
rename to packages/session/session-persistence-jsonl/tsconfig.json
index 044156938b..240c0b0ea9 100644
--- a/packages/session-persistence/session-persistence-jsonl/tsconfig.json
+++ b/packages/session/session-persistence-jsonl/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-persistence/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/README.i18n.yaml
rename to packages/session/session-persistence-sqlite/README.i18n.yaml
diff --git a/packages/session-persistence/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/README.md
rename to packages/session/session-persistence-sqlite/README.md
diff --git a/packages/session-persistence/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/README.zh.md
rename to packages/session/session-persistence-sqlite/README.zh.md
diff --git a/packages/session-persistence/session-persistence-sqlite/package.json b/packages/session/session-persistence-sqlite/package.json
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/package.json
rename to packages/session/session-persistence-sqlite/package.json
diff --git a/packages/session-persistence/session-persistence-sqlite/src/index.ts b/packages/session/session-persistence-sqlite/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/src/index.ts
rename to packages/session/session-persistence-sqlite/src/index.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/src/invariant.ts b/packages/session/session-persistence-sqlite/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/src/invariant.ts
rename to packages/session/session-persistence-sqlite/src/invariant.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/src/schema.ts b/packages/session/session-persistence-sqlite/src/schema.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/src/schema.ts
rename to packages/session/session-persistence-sqlite/src/schema.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session/session-persistence-sqlite/tests/sqlite.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
rename to packages/session/session-persistence-sqlite/tests/sqlite.spec.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/tsconfig.json b/packages/session/session-persistence-sqlite/tsconfig.json
similarity index 87%
rename from packages/session-persistence/session-persistence-sqlite/tsconfig.json
rename to packages/session/session-persistence-sqlite/tsconfig.json
index 044156938b..240c0b0ea9 100644
--- a/packages/session-persistence/session-persistence-sqlite/tsconfig.json
+++ b/packages/session/session-persistence-sqlite/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-persistence/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-persistence/README.i18n.yaml
rename to packages/session/session-persistence/README.i18n.yaml
diff --git a/packages/session-persistence/session-persistence/README.md b/packages/session/session-persistence/README.md
similarity index 100%
rename from packages/session-persistence/session-persistence/README.md
rename to packages/session/session-persistence/README.md
diff --git a/packages/session-persistence/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-persistence/README.zh.md
rename to packages/session/session-persistence/README.zh.md
diff --git a/packages/session-persistence/session-persistence/package.json b/packages/session/session-persistence/package.json
similarity index 100%
rename from packages/session-persistence/session-persistence/package.json
rename to packages/session/session-persistence/package.json
diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/coordinator.ts
rename to packages/session/session-persistence/src/coordinator.ts
diff --git a/packages/session-persistence/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/index.ts
rename to packages/session/session-persistence/src/index.ts
diff --git a/packages/session-persistence/session-persistence/src/invariant.ts b/packages/session/session-persistence/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/invariant.ts
rename to packages/session/session-persistence/src/invariant.ts
diff --git a/packages/session-persistence/session-persistence/src/preparations.ts b/packages/session/session-persistence/src/preparations.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/preparations.ts
rename to packages/session/session-persistence/src/preparations.ts
diff --git a/packages/session-persistence/session-persistence/src/revision.ts b/packages/session/session-persistence/src/revision.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/revision.ts
rename to packages/session/session-persistence/src/revision.ts
diff --git a/packages/session-persistence/session-persistence/src/write-behind.ts b/packages/session/session-persistence/src/write-behind.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/write-behind.ts
rename to packages/session/session-persistence/src/write-behind.ts
diff --git a/packages/session-persistence/session-persistence/tests/contract.ts b/packages/session/session-persistence/tests/contract.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/contract.ts
rename to packages/session/session-persistence/tests/contract.ts
diff --git a/packages/session-persistence/session-persistence/tests/coordinator-contract.ts b/packages/session/session-persistence/tests/coordinator-contract.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/coordinator-contract.ts
rename to packages/session/session-persistence/tests/coordinator-contract.ts
diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/persistence.spec.ts
rename to packages/session/session-persistence/tests/persistence.spec.ts
diff --git a/packages/session-persistence/session-persistence/tests/preparations.spec.ts b/packages/session/session-persistence/tests/preparations.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/preparations.spec.ts
rename to packages/session/session-persistence/tests/preparations.spec.ts
diff --git a/packages/session-persistence/session-persistence/tests/write-behind.spec.ts b/packages/session/session-persistence/tests/write-behind.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/write-behind.spec.ts
rename to packages/session/session-persistence/tests/write-behind.spec.ts
diff --git a/packages/session-persistence/session-persistence/tsconfig.json b/packages/session/session-persistence/tsconfig.json
similarity index 100%
rename from packages/session-persistence/session-persistence/tsconfig.json
rename to packages/session/session-persistence/tsconfig.json
diff --git a/packages/session-projection/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
similarity index 100%
rename from packages/session-projection/session-projection-cache/README.i18n.yaml
rename to packages/session/session-projection-cache/README.i18n.yaml
diff --git a/packages/session-projection/session-projection-cache/README.md b/packages/session/session-projection-cache/README.md
similarity index 100%
rename from packages/session-projection/session-projection-cache/README.md
rename to packages/session/session-projection-cache/README.md
diff --git a/packages/session-projection/session-projection-cache/README.zh.md b/packages/session/session-projection-cache/README.zh.md
similarity index 100%
rename from packages/session-projection/session-projection-cache/README.zh.md
rename to packages/session/session-projection-cache/README.zh.md
diff --git a/packages/session-projection/session-projection-cache/package.json b/packages/session/session-projection-cache/package.json
similarity index 100%
rename from packages/session-projection/session-projection-cache/package.json
rename to packages/session/session-projection-cache/package.json
diff --git a/packages/session-projection/session-projection-cache/src/index.ts b/packages/session/session-projection-cache/src/index.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/src/index.ts
rename to packages/session/session-projection-cache/src/index.ts
diff --git a/packages/session-projection/session-projection-cache/src/invariant.ts b/packages/session/session-projection-cache/src/invariant.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/src/invariant.ts
rename to packages/session/session-projection-cache/src/invariant.ts
diff --git a/packages/session-projection/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/src/spec.ts
rename to packages/session/session-projection-cache/src/spec.ts
diff --git a/packages/session-projection/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/tests/cache.spec.ts
rename to packages/session/session-projection-cache/tests/cache.spec.ts
diff --git a/packages/session-projection/session-projection-cache/tsconfig.json b/packages/session/session-projection-cache/tsconfig.json
similarity index 90%
rename from packages/session-projection/session-projection-cache/tsconfig.json
rename to packages/session/session-projection-cache/tsconfig.json
index baba6c805b..cf253dbe79 100644
--- a/packages/session-projection/session-projection-cache/tsconfig.json
+++ b/packages/session/session-projection-cache/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../session-projection"
diff --git a/packages/session-projection/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
similarity index 100%
rename from packages/session-projection/session-projection/README.i18n.yaml
rename to packages/session/session-projection/README.i18n.yaml
diff --git a/packages/session-projection/session-projection/README.md b/packages/session/session-projection/README.md
similarity index 100%
rename from packages/session-projection/session-projection/README.md
rename to packages/session/session-projection/README.md
diff --git a/packages/session-projection/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
similarity index 100%
rename from packages/session-projection/session-projection/README.zh.md
rename to packages/session/session-projection/README.zh.md
diff --git a/packages/session-projection/session-projection/package.json b/packages/session/session-projection/package.json
similarity index 100%
rename from packages/session-projection/session-projection/package.json
rename to packages/session/session-projection/package.json
diff --git a/packages/session-projection/session-projection/src/index.ts b/packages/session/session-projection/src/index.ts
similarity index 100%
rename from packages/session-projection/session-projection/src/index.ts
rename to packages/session/session-projection/src/index.ts
diff --git a/packages/session-projection/session-projection/src/invariant.ts b/packages/session/session-projection/src/invariant.ts
similarity index 100%
rename from packages/session-projection/session-projection/src/invariant.ts
rename to packages/session/session-projection/src/invariant.ts
diff --git a/packages/session-projection/session-projection/src/types.ts b/packages/session/session-projection/src/types.ts
similarity index 100%
rename from packages/session-projection/session-projection/src/types.ts
rename to packages/session/session-projection/src/types.ts
diff --git a/packages/session-projection/session-projection/tests/registry.spec.ts b/packages/session/session-projection/tests/registry.spec.ts
similarity index 100%
rename from packages/session-projection/session-projection/tests/registry.spec.ts
rename to packages/session/session-projection/tests/registry.spec.ts
diff --git a/packages/session-projection/session-projection/tsconfig.json b/packages/session/session-projection/tsconfig.json
similarity index 100%
rename from packages/session-projection/session-projection/tsconfig.json
rename to packages/session/session-projection/tsconfig.json
diff --git a/packages/telemetry/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/README.i18n.yaml
rename to packages/session/session-telemetry-otel/README.i18n.yaml
diff --git a/packages/telemetry/session-telemetry-otel/README.md b/packages/session/session-telemetry-otel/README.md
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/README.md
rename to packages/session/session-telemetry-otel/README.md
diff --git a/packages/telemetry/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/README.zh.md
rename to packages/session/session-telemetry-otel/README.zh.md
diff --git a/packages/telemetry/session-telemetry-otel/package.json b/packages/session/session-telemetry-otel/package.json
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/package.json
rename to packages/session/session-telemetry-otel/package.json
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/session/session-telemetry-otel/src/index.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/src/index.ts
rename to packages/session/session-telemetry-otel/src/index.ts
diff --git a/packages/telemetry/session-telemetry-otel/src/invariant.ts b/packages/session/session-telemetry-otel/src/invariant.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/src/invariant.ts
rename to packages/session/session-telemetry-otel/src/invariant.ts
diff --git a/packages/telemetry/session-telemetry-otel/src/user-id.ts b/packages/session/session-telemetry-otel/src/user-id.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/src/user-id.ts
rename to packages/session/session-telemetry-otel/src/user-id.ts
diff --git a/packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts b/packages/session/session-telemetry-otel/tests/loader-composition.e2e.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts
rename to packages/session/session-telemetry-otel/tests/loader-composition.e2e.ts
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/session/session-telemetry-otel/tests/otel.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
rename to packages/session/session-telemetry-otel/tests/otel.spec.ts
diff --git a/packages/telemetry/session-telemetry-otel/tests/user-id.spec.ts b/packages/session/session-telemetry-otel/tests/user-id.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tests/user-id.spec.ts
rename to packages/session/session-telemetry-otel/tests/user-id.spec.ts
diff --git a/packages/telemetry/session-telemetry-otel/tsconfig.json b/packages/session/session-telemetry-otel/tsconfig.json
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tsconfig.json
rename to packages/session/session-telemetry-otel/tsconfig.json
diff --git a/packages/telemetry/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
similarity index 100%
rename from packages/telemetry/session-telemetry/README.i18n.yaml
rename to packages/session/session-telemetry/README.i18n.yaml
diff --git a/packages/telemetry/session-telemetry/README.md b/packages/session/session-telemetry/README.md
similarity index 100%
rename from packages/telemetry/session-telemetry/README.md
rename to packages/session/session-telemetry/README.md
diff --git a/packages/telemetry/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
similarity index 100%
rename from packages/telemetry/session-telemetry/README.zh.md
rename to packages/session/session-telemetry/README.zh.md
diff --git a/packages/telemetry/session-telemetry/package.json b/packages/session/session-telemetry/package.json
similarity index 100%
rename from packages/telemetry/session-telemetry/package.json
rename to packages/session/session-telemetry/package.json
diff --git a/packages/telemetry/session-telemetry/src/coordinator.ts b/packages/session/session-telemetry/src/coordinator.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/src/coordinator.ts
rename to packages/session/session-telemetry/src/coordinator.ts
diff --git a/packages/telemetry/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/src/index.ts
rename to packages/session/session-telemetry/src/index.ts
diff --git a/packages/telemetry/session-telemetry/src/invariant.ts b/packages/session/session-telemetry/src/invariant.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/src/invariant.ts
rename to packages/session/session-telemetry/src/invariant.ts
diff --git a/packages/telemetry/session-telemetry/tests/redact.spec.ts b/packages/session/session-telemetry/tests/redact.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/tests/redact.spec.ts
rename to packages/session/session-telemetry/tests/redact.spec.ts
diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/session/session-telemetry/tests/telemetry.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/tests/telemetry.spec.ts
rename to packages/session/session-telemetry/tests/telemetry.spec.ts
diff --git a/packages/telemetry/session-telemetry/tsconfig.json b/packages/session/session-telemetry/tsconfig.json
similarity index 100%
rename from packages/telemetry/session-telemetry/tsconfig.json
rename to packages/session/session-telemetry/tsconfig.json
diff --git a/packages/session-title/session-title-all-messages-llm/README.i18n.yaml b/packages/session/session-title-all-messages-llm/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/README.i18n.yaml
rename to packages/session/session-title-all-messages-llm/README.i18n.yaml
diff --git a/packages/session-title/session-title-all-messages-llm/README.md b/packages/session/session-title-all-messages-llm/README.md
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/README.md
rename to packages/session/session-title-all-messages-llm/README.md
diff --git a/packages/session-title/session-title-all-messages-llm/README.zh.md b/packages/session/session-title-all-messages-llm/README.zh.md
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/README.zh.md
rename to packages/session/session-title-all-messages-llm/README.zh.md
diff --git a/packages/session-title/session-title-all-messages-llm/package.json b/packages/session/session-title-all-messages-llm/package.json
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/package.json
rename to packages/session/session-title-all-messages-llm/package.json
diff --git a/packages/session-title/session-title-all-messages-llm/src/index.ts b/packages/session/session-title-all-messages-llm/src/index.ts
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/src/index.ts
rename to packages/session/session-title-all-messages-llm/src/index.ts
diff --git a/packages/session-title/session-title-all-messages-llm/src/invariant.ts b/packages/session/session-title-all-messages-llm/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/src/invariant.ts
rename to packages/session/session-title-all-messages-llm/src/invariant.ts
diff --git a/packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts b/packages/session/session-title-all-messages-llm/tests/provider.spec.ts
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts
rename to packages/session/session-title-all-messages-llm/tests/provider.spec.ts
diff --git a/packages/session-title/session-title-all-messages-llm/tsconfig.json b/packages/session/session-title-all-messages-llm/tsconfig.json
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/tsconfig.json
rename to packages/session/session-title-all-messages-llm/tsconfig.json
diff --git a/packages/session-title/session-title-first-message-llm/README.i18n.yaml b/packages/session/session-title-first-message-llm/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/README.i18n.yaml
rename to packages/session/session-title-first-message-llm/README.i18n.yaml
diff --git a/packages/session-title/session-title-first-message-llm/README.md b/packages/session/session-title-first-message-llm/README.md
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/README.md
rename to packages/session/session-title-first-message-llm/README.md
diff --git a/packages/session-title/session-title-first-message-llm/README.zh.md b/packages/session/session-title-first-message-llm/README.zh.md
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/README.zh.md
rename to packages/session/session-title-first-message-llm/README.zh.md
diff --git a/packages/session-title/session-title-first-message-llm/package.json b/packages/session/session-title-first-message-llm/package.json
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/package.json
rename to packages/session/session-title-first-message-llm/package.json
diff --git a/packages/session-title/session-title-first-message-llm/src/index.ts b/packages/session/session-title-first-message-llm/src/index.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/src/index.ts
rename to packages/session/session-title-first-message-llm/src/index.ts
diff --git a/packages/session-title/session-title-first-message-llm/src/invariant.ts b/packages/session/session-title-first-message-llm/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/src/invariant.ts
rename to packages/session/session-title-first-message-llm/src/invariant.ts
diff --git a/packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts b/packages/session/session-title-first-message-llm/tests/loader-composition.spec.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts
rename to packages/session/session-title-first-message-llm/tests/loader-composition.spec.ts
diff --git a/packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts b/packages/session/session-title-first-message-llm/tests/provider.e2e.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts
rename to packages/session/session-title-first-message-llm/tests/provider.e2e.ts
diff --git a/packages/session-title/session-title-first-message-llm/tests/provider.spec.ts b/packages/session/session-title-first-message-llm/tests/provider.spec.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tests/provider.spec.ts
rename to packages/session/session-title-first-message-llm/tests/provider.spec.ts
diff --git a/packages/session-title/session-title-first-message-llm/tsconfig.json b/packages/session/session-title-first-message-llm/tsconfig.json
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tsconfig.json
rename to packages/session/session-title-first-message-llm/tsconfig.json
diff --git a/packages/session-title/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title-llm/README.i18n.yaml
rename to packages/session/session-title-llm/README.i18n.yaml
diff --git a/packages/session-title/session-title-llm/README.md b/packages/session/session-title-llm/README.md
similarity index 100%
rename from packages/session-title/session-title-llm/README.md
rename to packages/session/session-title-llm/README.md
diff --git a/packages/session-title/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
similarity index 100%
rename from packages/session-title/session-title-llm/README.zh.md
rename to packages/session/session-title-llm/README.zh.md
diff --git a/packages/session-title/session-title-llm/package.json b/packages/session/session-title-llm/package.json
similarity index 100%
rename from packages/session-title/session-title-llm/package.json
rename to packages/session/session-title-llm/package.json
diff --git a/packages/session-title/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
similarity index 100%
rename from packages/session-title/session-title-llm/src/index.ts
rename to packages/session/session-title-llm/src/index.ts
diff --git a/packages/session-title/session-title-llm/src/invariant.ts b/packages/session/session-title-llm/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title-llm/src/invariant.ts
rename to packages/session/session-title-llm/src/invariant.ts
diff --git a/packages/session-title/session-title-llm/tests/llm.spec.ts b/packages/session/session-title-llm/tests/llm.spec.ts
similarity index 100%
rename from packages/session-title/session-title-llm/tests/llm.spec.ts
rename to packages/session/session-title-llm/tests/llm.spec.ts
diff --git a/packages/session-title/session-title-llm/tsconfig.json b/packages/session/session-title-llm/tsconfig.json
similarity index 100%
rename from packages/session-title/session-title-llm/tsconfig.json
rename to packages/session/session-title-llm/tsconfig.json
diff --git a/packages/session-title/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title/README.i18n.yaml
rename to packages/session/session-title/README.i18n.yaml
diff --git a/packages/session-title/session-title/README.md b/packages/session/session-title/README.md
similarity index 100%
rename from packages/session-title/session-title/README.md
rename to packages/session/session-title/README.md
diff --git a/packages/session-title/session-title/README.zh.md b/packages/session/session-title/README.zh.md
similarity index 100%
rename from packages/session-title/session-title/README.zh.md
rename to packages/session/session-title/README.zh.md
diff --git a/packages/session-title/session-title/package.json b/packages/session/session-title/package.json
similarity index 100%
rename from packages/session-title/session-title/package.json
rename to packages/session/session-title/package.json
diff --git a/packages/session-title/session-title/src/client.ts b/packages/session/session-title/src/client.ts
similarity index 100%
rename from packages/session-title/session-title/src/client.ts
rename to packages/session/session-title/src/client.ts
diff --git a/packages/session-title/session-title/src/index.ts b/packages/session/session-title/src/index.ts
similarity index 100%
rename from packages/session-title/session-title/src/index.ts
rename to packages/session/session-title/src/index.ts
diff --git a/packages/session-title/session-title/src/invariant.ts b/packages/session/session-title/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title/src/invariant.ts
rename to packages/session/session-title/src/invariant.ts
diff --git a/packages/session-title/session-title/src/normalize.ts b/packages/session/session-title/src/normalize.ts
similarity index 100%
rename from packages/session-title/session-title/src/normalize.ts
rename to packages/session/session-title/src/normalize.ts
diff --git a/packages/session-title/session-title/src/types.ts b/packages/session/session-title/src/types.ts
similarity index 100%
rename from packages/session-title/session-title/src/types.ts
rename to packages/session/session-title/src/types.ts
diff --git a/packages/session-title/session-title/tests/invariant.spec.ts b/packages/session/session-title/tests/invariant.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/invariant.spec.ts
rename to packages/session/session-title/tests/invariant.spec.ts
diff --git a/packages/session-title/session-title/tests/persistence.spec.ts b/packages/session/session-title/tests/persistence.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/persistence.spec.ts
rename to packages/session/session-title/tests/persistence.spec.ts
diff --git a/packages/session-title/session-title/tests/projection.spec.ts b/packages/session/session-title/tests/projection.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/projection.spec.ts
rename to packages/session/session-title/tests/projection.spec.ts
diff --git a/packages/session-title/session-title/tests/provider.spec.ts b/packages/session/session-title/tests/provider.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/provider.spec.ts
rename to packages/session/session-title/tests/provider.spec.ts
diff --git a/packages/session-title/session-title/tests/rename.spec.ts b/packages/session/session-title/tests/rename.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/rename.spec.ts
rename to packages/session/session-title/tests/rename.spec.ts
diff --git a/packages/session-title/session-title/tests/service-contracts.spec.ts b/packages/session/session-title/tests/service-contracts.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/service-contracts.spec.ts
rename to packages/session/session-title/tests/service-contracts.spec.ts
diff --git a/packages/session-title/session-title/tests/session-title.spec.ts b/packages/session/session-title/tests/session-title.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/session-title.spec.ts
rename to packages/session/session-title/tests/session-title.spec.ts
diff --git a/packages/session-title/session-title/tsconfig.json b/packages/session/session-title/tsconfig.json
similarity index 90%
rename from packages/session-title/session-title/tsconfig.json
rename to packages/session/session-title/tsconfig.json
index 80aef8bbfb..ca7c8e65dd 100644
--- a/packages/session-title/session-title/tsconfig.json
+++ b/packages/session/session-title/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../session-projection"
     }
   ]
 }
diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json
index de2fff3d84..ccfecc02e4 100644
--- a/packages/subagent/subagent/tsconfig.json
+++ b/packages/subagent/subagent/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/scope"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../session-projection/session-projection"
diff --git a/packages/telemetry/README.i18n.yaml b/packages/telemetry/README.i18n.yaml
deleted file mode 100644
index 6f60d47612..0000000000
--- a/packages/telemetry/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/telemetry/README.md
-README.md: d1910323176738d1ecab8fe8e6c07a2811f0f5cd
-README.zh.md: 229cd3acc5ce3dc49a9c862efa824f4ee6a1fa7b
diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md
deleted file mode 100644
index d191032317..0000000000
--- a/packages/telemetry/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# telemetry/ — session telemetry capability family
-
-English | [中文](README.zh.md)
-
-This family projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The [telemetry decision](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) records the reporting boundary; the [mode decision](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md) records immediate, feedback-gated, and disabled delivery.
-
-| Package | Role |
-|---|---|
-| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
-| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
diff --git a/packages/telemetry/README.zh.md b/packages/telemetry/README.zh.md
deleted file mode 100644
index 229cd3acc5..0000000000
--- a/packages/telemetry/README.zh.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# telemetry/：会话遥测能力家族
-
-[English](README.md) | 中文
-
-本家族将会话活动投影为外发遥测，并将投递委派给配置的上报后端。[遥测决策](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)记录上报边界；[模式决策](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)记录即时、反馈门控与禁用投递。
-
-| 包 | 职责 |
-|---|---|
-| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
-| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
diff --git a/packages/todo/tool-todo/README.i18n.yaml b/packages/todo/tool-todo/README.i18n.yaml
index 20b8dffbbf..6aa521df26 100644
--- a/packages/todo/tool-todo/README.i18n.yaml
+++ b/packages/todo/tool-todo/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/todo/tool-todo/README.md
-README.md: 914e89a000e4bb87ebd7844f05db3809c6726528
-README.zh.md: c88dbf976fa5110028fcc964ab9aa8efcc3244d3
+README.md: 7c993ac6f7f0047d008a09e5ff52cb752f94763c
+README.zh.md: 9cea66147beddab7d62ed7344cbe866495e28022
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 914e89a000..7c993ac6f7 100644
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -30,7 +30,7 @@ The canonical result is `{ todos, counts: { pending, inProgress, completed } }`;
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the interface package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the interface package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
 
 ## Export shape
 
diff --git a/packages/todo/tool-todo/README.zh.md b/packages/todo/tool-todo/README.zh.md
index c88dbf976f..9cea66147b 100644
--- a/packages/todo/tool-todo/README.zh.md
+++ b/packages/todo/tool-todo/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 会话投影
 
-当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
+当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
 
 ## 导出形状
 
diff --git a/packages/todo/tool-todo/tsconfig.json b/packages/todo/tool-todo/tsconfig.json
index b35157e58d..6160fdbeb7 100644
--- a/packages/todo/tool-todo/tsconfig.json
+++ b/packages/todo/tool-todo/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts b/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
index 051b0eef20..1de16660a8 100644
--- a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
+++ b/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
@@ -35,7 +35,7 @@ const [
   load("vendor/cordis/lib/index.js"),
   load("packages/examples/agent-spine-demo/lib/index.js"),
   load("packages/subagent/subagent/lib/index.js"),
-  load("packages/session-persistence/session-persistence-jsonl/lib/index.js"),
+  load("packages/session/session-persistence-jsonl/lib/index.js"),
   load("packages/ui/jsonrpc/lib/index.js"),
   load("packages/core/session/lib/index.js"),
 ]);
diff --git a/packages/ui/permission/tsconfig.json b/packages/ui/permission/tsconfig.json
index 9dc4afcd9a..b951d622a8 100644
--- a/packages/ui/permission/tsconfig.json
+++ b/packages/ui/permission/tsconfig.json
@@ -36,7 +36,7 @@
       "path": "../../support/invariants"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../settings/settings"
diff --git a/packages/workspace/workspace/tsconfig.json b/packages/workspace/workspace/tsconfig.json
index 0bddf4672c..bbdf80fae2 100644
--- a/packages/workspace/workspace/tsconfig.json
+++ b/packages/workspace/workspace/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../util/brand"
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b17cc5b4f8..2c347613e8 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -270,11 +270,11 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   DomainSpec: 'domain declaration contract is owned by packages/storage/storage-domain/README.md',
   StorageBackend: 'backend contract is owned by packages/storage/storage/src/backend.ts',
   StorageForms: 'merge-extensible form map is owned by packages/storage/storage/src/index.ts',
-  ProjectionDefinition: 'projection unit contract is owned by packages/session-projection/session-projection/README.md',
-  SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session-projection/session-projection/src/types.ts',
-  ProjectionChangeListener: 'change-feed listener contract is owned by packages/session-projection/session-projection/src/index.ts',
-  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session-projection/session-projection/src/index.ts',
-  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session-projection/session-projection/src/index.ts',
+  ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
+  SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session/session-projection/src/types.ts',
+  ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
+  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session/session-projection/src/index.ts',
+  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session/session-projection/src/index.ts',
   CommandExecution: 'executor return contract is owned by packages/ui/commands/src/index.ts',
   TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
   TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
@@ -305,7 +305,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
-  TelemetryRecord: 'seam-local record contract is owned by packages/telemetry/session-telemetry/src/index.ts',
+  TelemetryRecord: 'seam-local record contract is owned by packages/session/session-telemetry/src/index.ts',
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 74a09a874e..258b70f87d 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -312,7 +312,7 @@ function nodeCompatSmokeGates(options: { cliSmoke?: boolean } = {}): Gate[] {
     pnpmExec('jsonl-zstd-smoke', [
       'vitest',
       'run',
-      'packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts',
+      'packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts',
     ], { label: 'JSONL Zstandard smoke' }),
     pnpmExec('dsh-source-launch-smoke', [
       'vitest',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 9c99ed4632..e4eaf15398 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -448,7 +448,7 @@
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionLocation",
-      "source": "packages/session-persistence/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-query.md",
@@ -528,57 +528,57 @@
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderId",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleModelProvenance",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleSource",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleEventData",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleSnapshot",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleLlmRequestEventData",
-      "source": "packages/session-title/session-title-llm/src/index.ts"
+      "source": "packages/session/session-title-llm/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleUserMessage",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleAutomaticMode",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderRequest",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderResult",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProvider",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-reference.md",
@@ -1323,12 +1323,12 @@
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionPersistenceRevision",
-      "source": "packages/session-persistence/session-persistence/src/revision.ts"
+      "source": "packages/session/session-persistence/src/revision.ts"
     },
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionPersistenceSnapshot",
-      "source": "packages/session-persistence/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-query.md",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 6fda3901b6..5930d39e26 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -109,8 +109,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/sdk/sdk-client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
   'packages/sdk/sdk-protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
   'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
-  'packages/session-projection/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
-  'packages/session-projection/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
+  'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
+  'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
   'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers no model surface.' },
   'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model surface a value feeds.' },
@@ -118,8 +118,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model surface a value authorizes.' },
   'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model surface.' },
   'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers no model surface.' },
-  'packages/telemetry/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
-  'packages/telemetry/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
+  'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
+  'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-badge': { kind: 'indirect', reason: 'The bundled provider delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 0673c35b90..e09ab93743 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -54,11 +54,11 @@
       "@deepseek-ai/dsh-typert-generator": ["./packages/typert/generator/src/index.ts"],
       "@deepseek-ai/dsh-session/types": ["./packages/core/session/src/types.ts"],
       "@deepseek-ai/dsh-session/surface": ["./packages/core/session/src/surface.ts"],
-      "@deepseek-ai/dsh-session-projection/types": ["./packages/session-projection/session-projection/src/types.ts"],
+      "@deepseek-ai/dsh-session-projection/types": ["./packages/session/session-projection/src/types.ts"],
       "@deepseek-ai/dsh-tool-todo/types": ["./packages/todo/tool-todo/src/types.ts"],
       "@deepseek-ai/dsh-tool-todo/client": ["./packages/todo/tool-todo/src/client.ts"],
-      "@deepseek-ai/dsh-session-title/types": ["./packages/session-title/session-title/src/types.ts"],
-      "@deepseek-ai/dsh-session-title/client": ["./packages/session-title/session-title/src/client.ts"],
+      "@deepseek-ai/dsh-session-title/types": ["./packages/session/session-title/src/types.ts"],
+      "@deepseek-ai/dsh-session-title/client": ["./packages/session/session-title/src/client.ts"],
       "@deepseek-ai/dsh-plan-mode/types": ["./packages/plan/plan-mode/src/types.ts"],
       "@deepseek-ai/dsh-plan-mode/client": ["./packages/plan/plan-mode/src/client.ts"],
       "@deepseek-ai/dsh-pwsh-local": ["./packages/bash/pwsh-local/src/index.ts"],
@@ -106,13 +106,10 @@
         "./packages/cordis/*/src/invariant.ts",
         "./packages/sandbox/*/src/invariant.ts",
         "./packages/hooks/*/src/invariant.ts",
-        "./packages/session-persistence/*/src/invariant.ts",
-        "./packages/session-projection/*/src/invariant.ts",
-        "./packages/session-title/*/src/invariant.ts",
+        "./packages/session/*/src/invariant.ts",
         "./packages/session-query/*/src/invariant.ts",
         "./packages/settings/*/src/invariant.ts",
         "./packages/credentials/*/src/invariant.ts",
-        "./packages/telemetry/*/src/invariant.ts",
         "./packages/acp/*/src/invariant.ts",
         "./packages/storage/*/src/invariant.ts",
         "./packages/workspace/*/src/invariant.ts",
@@ -211,13 +208,10 @@
         "./packages/cordis/*/src",
         "./packages/sandbox/*/src",
         "./packages/hooks/*/src",
-        "./packages/session-persistence/*/src",
-        "./packages/session-projection/*/src",
+        "./packages/session/*/src",
         "./packages/session-query/*/src",
-        "./packages/session-title/*/src",
         "./packages/settings/*/src",
         "./packages/credentials/*/src",
-        "./packages/telemetry/*/src",
         "./packages/acp/*/src",
         "./packages/storage/*/src",
         "./packages/workspace/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 101c810c91..0f44c4b7de 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -112,12 +112,12 @@
     { "path": "./packages/api/gateway" },
     { "path": "./packages/api/remotes/tsconfig.host.json" },
     { "path": "./packages/typert/loader" },
-    { "path": "./packages/session-persistence/session-persistence" },
-    { "path": "./packages/session-persistence/session-checkpoint-policy" },
-    { "path": "./packages/session-persistence/session-persistence-jsonl" },
-    { "path": "./packages/session-persistence/session-persistence-sqlite" },
-    { "path": "./packages/session-projection/session-projection" },
-    { "path": "./packages/session-projection/session-projection-cache" },
+    { "path": "./packages/session/session-persistence" },
+    { "path": "./packages/session/session-checkpoint-policy" },
+    { "path": "./packages/session/session-persistence-jsonl" },
+    { "path": "./packages/session/session-persistence-sqlite" },
+    { "path": "./packages/session/session-projection" },
+    { "path": "./packages/session/session-projection-cache" },
     { "path": "./packages/session-query/session-query" },
     { "path": "./packages/session-query/session-query-sqlite" },
     { "path": "./packages/settings/settings" },
@@ -130,12 +130,12 @@
     { "path": "./packages/storage/storage-sqlite" },
     { "path": "./packages/storage/storage-domain" },
     { "path": "./packages/workspace/workspace" },
-    { "path": "./packages/session-title/session-title" },
-    { "path": "./packages/session-title/session-title-llm" },
-    { "path": "./packages/session-title/session-title-first-message-llm" },
-    { "path": "./packages/session-title/session-title-all-messages-llm" },
-    { "path": "./packages/telemetry/session-telemetry" },
-    { "path": "./packages/telemetry/session-telemetry-otel" },
+    { "path": "./packages/session/session-title" },
+    { "path": "./packages/session/session-title-llm" },
+    { "path": "./packages/session/session-title-first-message-llm" },
+    { "path": "./packages/session/session-title-all-messages-llm" },
+    { "path": "./packages/session/session-telemetry" },
+    { "path": "./packages/session/session-telemetry-otel" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
     { "path": "./packages/ui/commands" },
diff --git a/vitest.config.ts b/vitest.config.ts
index 6eb1bda354..29ad406e75 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -224,7 +224,7 @@ export default defineConfig({
         // cover and remove with the client test lane above.
         'packages/ui/commands/src/index.ts',
         'packages/ui/commands/src/invariant.ts',
-        'packages/session-projection/session-projection/src/index.ts',
+        'packages/session/session-projection/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
         ...pwshCoverageExclusions,

From 3fc35c91ff490e3ad1ad5fed34aa1e3ed7145eec Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 03:13:49 +0800
Subject: [PATCH 151/262] refactor(packages): dissolve ui/ and rename sdk/ to
 scaffold/

git mv per the regrouping RFC: the five human-collaboration seams and
tui join packages/interaction/, app-boot becomes packages/boot/, and
jsonrpc joins the renamed scaffold/ (formerly sdk/) as its server half
beside client/protocol/create-sdk/helper/scripts/telemetry, whose
folders drop the legacy sdk- prefix. Three new group README triplets
replace the ui/ and sdk/ ones; tsconfig references/paths/globs,
knip keys, vitest globs, gate scripts, catalogs, docs, and the
lockfile follow. Adds the four settled FIXME rename markers
(dsh-sdk-server, dsh-sdk-telemetry, dsh-sdk-helper, dsh-sdk-scripts).

The scaffold folders diverge from their npm names until those renames
land, so tsconfig.base.json maps the three affected names explicitly
beside the group wildcard. Also repairs two pre-existing stale-path
classes the strengthened sweep surfaced: docs/web-styling.md's retired
web-ui host package and type-model spec fixture-literal joins.

app-boot's three Loader-composition specs time out at the default 5s
under full-suite parallel load on this filesystem (pre-existing;
pass isolated with --testTimeout=30000); interaction/scaffold/boot
suites otherwise green (687 passed).
---
 ...026-07-27-tui-chat-channel-module-split.md |  2 +-
 ...-07-27-tui-chat-channel-module-split.zh.md |  2 +-
 ...-07-24-tui-turn-end-stop-reason-notices.md |  2 +-
 ...-24-tui-turn-end-stop-reason-notices.zh.md |  2 +-
 ...17-dedicated-full-screen-tui-front-door.md |  2 +-
 ...dedicated-full-screen-tui-front-door.zh.md |  2 +-
 .../feature/2026-07-20-windows-tui-support.md |  2 +-
 .../2026-07-20-windows-tui-support.zh.md      |  2 +-
 .../2026-07-21-tui-skill-slash-command.md     |  2 +-
 .../2026-07-21-tui-skill-slash-command.zh.md  |  2 +-
 ...-07-27-assistant-timing-header-trailing.md |  2 +-
 ...-27-assistant-timing-header-trailing.zh.md |  2 +-
 ...7-26-execa-for-test-subprocess-plumbing.md |  2 +-
 ...6-execa-for-test-subprocess-plumbing.zh.md |  2 +-
 ...cutable-sdk-runtime-distribution.i18n.yaml |  4 +--
 ...ile-executable-sdk-runtime-distribution.md |  4 +--
 ...-executable-sdk-runtime-distribution.zh.md |  4 +--
 ...-20-config-hot-reload-resilience.i18n.yaml |  4 +--
 ...2026-07-20-config-hot-reload-resilience.md |  2 +-
 ...6-07-20-config-hot-reload-resilience.zh.md |  2 +-
 .../2026-07-06-approval-seam.i18n.yaml        |  4 +--
 .../feature/2026-07-06-approval-seam.md       |  4 +--
 .../feature/2026-07-06-approval-seam.zh.md    |  4 +--
 ...nt-persona-tool-filter-and-depth.i18n.yaml |  4 +--
 ...-subagent-persona-tool-filter-and-depth.md |  2 +-
 ...bagent-persona-tool-filter-and-depth.zh.md |  2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |  4 +--
 .../feature/2026-07-16-harness-level-loop.md  |  2 +-
 .../2026-07-16-harness-level-loop.zh.md       |  2 +-
 ...7-19-plugin-command-registration.i18n.yaml |  4 +--
 .../2026-07-19-plugin-command-registration.md |  2 +-
 ...26-07-19-plugin-command-registration.zh.md |  2 +-
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |  4 +--
 .../2026-07-20-dsh-cli-personal-config.md     |  2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |  2 +-
 ...continuable-background-subagents.i18n.yaml |  4 +--
 ...-07-21-continuable-background-subagents.md |  2 +-
 ...-21-continuable-background-subagents.zh.md |  2 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |  4 +--
 ...typescript-sdk-and-sdk-subagent-backend.md |  4 +--
 ...escript-sdk-and-sdk-subagent-backend.zh.md |  4 +--
 ...ssion-projection-and-command-log.i18n.yaml |  4 +--
 ...7-27-session-projection-and-command-log.md |  2 +-
 ...7-session-projection-and-command-log.zh.md |  2 +-
 ...6-07-19-make-jsonrpc-directional.i18n.yaml |  4 +--
 .../2026-07-19-make-jsonrpc-directional.md    |  6 ++--
 .../2026-07-19-make-jsonrpc-directional.zh.md |  6 ++--
 AGENTS.md                                     |  4 ++-
 apps/cli/tsconfig.json                        |  2 +-
 docs/architecture.i18n.yaml                   |  4 +--
 docs/architecture.md                          |  2 +-
 docs/architecture.zh.md                       |  2 +-
 docs/capability-seams.md                      |  8 ++---
 docs/core-data-structures/approval.i18n.yaml  |  4 +--
 docs/core-data-structures/approval.md         |  4 +--
 docs/core-data-structures/approval.zh.md      |  4 +--
 docs/core-data-structures/commands.i18n.yaml  |  4 +--
 docs/core-data-structures/commands.md         |  4 +--
 docs/core-data-structures/commands.zh.md      |  4 +--
 .../user-interaction.i18n.yaml                |  4 +--
 docs/core-data-structures/user-interaction.md |  4 +--
 .../user-interaction.zh.md                    |  4 +--
 docs/testing.i18n.yaml                        |  4 +--
 docs/testing.md                               |  2 +-
 docs/testing.zh.md                            |  2 +-
 docs/tool-catalog.md                          |  2 +-
 knip.json                                     |  8 ++---
 packages/README.i18n.yaml                     |  4 +--
 packages/README.md                            |  5 +--
 packages/README.zh.md                         |  5 +--
 packages/acp/acp/tsconfig.json                |  2 +-
 packages/bash/tool-bash/tsconfig.json         |  2 +-
 packages/{sdk => boot}/README.i18n.yaml       |  6 ++--
 packages/boot/README.md                       |  9 +++++
 packages/boot/README.zh.md                    |  9 +++++
 .../{ui => boot}/app-boot/README.i18n.yaml    |  2 +-
 packages/{ui => boot}/app-boot/README.md      |  0
 packages/{ui => boot}/app-boot/README.zh.md   |  0
 packages/{ui => boot}/app-boot/package.json   |  0
 packages/{ui => boot}/app-boot/src/index.ts   |  0
 .../{ui => boot}/app-boot/src/invariant.ts    |  0
 packages/{ui => boot}/app-boot/src/profile.ts |  0
 .../app-boot/tests/app-boot.spec.ts           |  0
 .../app-boot/tests/config-dump.spec.ts        |  0
 .../app-boot/tests/config-reload.spec.ts      |  0
 .../app-boot/tests/hmr-config.spec.ts         |  0
 .../app-boot/tests/profile.spec.ts            |  0
 .../app-boot/tests/repository-cache.spec.ts   |  0
 .../app-boot/tests/user-patches.spec.ts       |  0
 packages/{ui => boot}/app-boot/tsconfig.json  |  0
 .../{ui => boot}/app-boot/tsdown.config.ts    |  0
 packages/bundle/README.i18n.yaml              |  6 ++++
 packages/client/connection/tsconfig.json      |  6 ++--
 packages/client/runtime/tsconfig.json         |  2 +-
 packages/client/ui-conversation/tsconfig.json |  2 +-
 packages/client/ui-permission/tsconfig.json   |  2 +-
 packages/client/ui-question/tsconfig.json     |  2 +-
 .../compact/command-compact/tsconfig.json     |  2 +-
 packages/compact/compact/README.i18n.yaml     |  4 +--
 packages/compact/compact/README.md            |  2 +-
 packages/compact/compact/README.zh.md         |  2 +-
 packages/core/tools/README.i18n.yaml          |  4 +--
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/README.zh.md              |  2 +-
 packages/core/tools/tsconfig.json             |  2 +-
 .../examples/acp-demo/tests/built-bin.e2e.ts  |  2 +-
 packages/examples/acp-demo/tsconfig.json      |  2 +-
 packages/examples/jsonrpc-demo/tsconfig.json  |  2 +-
 packages/fs/tool-fs/tsconfig.json             |  2 +-
 packages/goal/command-goal/tsconfig.json      |  2 +-
 packages/host/apiproxy/tsconfig.json          |  6 ++--
 packages/interaction/README.i18n.yaml         |  6 ++++
 packages/{ui => interaction}/README.md        |  6 ++--
 packages/{ui => interaction}/README.zh.md     |  6 ++--
 .../commands/README.i18n.yaml                 |  2 +-
 .../{ui => interaction}/commands/README.md    |  0
 .../{ui => interaction}/commands/README.zh.md |  0
 .../{ui => interaction}/commands/package.json |  0
 .../{ui => interaction}/commands/src/brand.ts |  0
 .../{ui => interaction}/commands/src/index.ts |  0
 .../commands/src/invariant.ts                 |  0
 .../commands/tests/commands.spec.ts           |  0
 .../commands/tests/invariant.spec.ts          |  0
 .../commands/tsconfig.json                    |  0
 .../interaction/permission/README.i18n.yaml   |  6 ++++
 .../{ui => interaction}/permission/README.md  |  0
 .../permission/README.zh.md                   |  0
 .../permission/package.json                   |  0
 .../permission/src/client.ts                  |  0
 .../permission/src/index.ts                   |  0
 .../permission/src/invariant.ts               |  0
 .../permission/src/types.ts                   |  0
 .../permission/tests/invariant.spec.ts        |  0
 .../permission/tests/permission.spec.ts       |  0
 .../permission/tests/projection.spec.ts       |  0
 .../permission/tsconfig.json                  |  0
 .../tool-ask-user/README.i18n.yaml            |  2 +-
 .../tool-ask-user/README.md                   |  0
 .../tool-ask-user/README.zh.md                |  0
 .../tool-ask-user/package.json                |  0
 .../tool-ask-user/src/index.ts                |  0
 .../tool-ask-user/src/invariant.ts            |  0
 .../tool-ask-user/tests/tool-ask-user.spec.ts |  0
 .../tool-ask-user/tsconfig.json               |  0
 .../user-approval/README.i18n.yaml            |  2 +-
 .../user-approval/README.md                   |  0
 .../user-approval/README.zh.md                |  0
 .../user-approval/package.json                |  0
 .../user-approval/src/index.ts                |  0
 .../user-approval/src/invariant.ts            |  0
 .../user-approval/src/types.ts                |  0
 .../user-approval/tests/approval.spec.ts      |  0
 .../user-approval/tests/invariant.spec.ts     |  0
 .../user-approval/tsconfig.json               |  0
 .../user-approval/tsdown.config.ts            |  0
 .../user-interaction/README.i18n.yaml         |  6 ++++
 .../user-interaction/README.md                |  0
 .../user-interaction/README.zh.md             |  0
 .../user-interaction/package.json             |  0
 .../user-interaction/src/index.ts             |  0
 .../user-interaction/src/invariant.ts         |  0
 .../user-interaction/src/types.ts             |  0
 .../tests/user-interaction.spec.ts            |  0
 .../user-interaction/tsconfig.json            |  0
 packages/plan/plan-mode/tsconfig.json         |  4 +--
 packages/{ui => scaffold}/README.i18n.yaml    |  6 ++--
 packages/{sdk => scaffold}/README.md          |  9 ++---
 packages/scaffold/README.zh.md                | 17 +++++++++
 .../client}/README.i18n.yaml                  |  2 +-
 .../sdk-client => scaffold/client}/README.md  |  0
 .../client}/README.zh.md                      |  0
 .../client}/package.json                      |  0
 .../sdk-client => scaffold/client}/src/api.ts |  0
 .../client}/src/client.ts                     |  0
 .../client}/src/dispose.ts                    |  0
 .../client}/src/index.ts                      |  0
 .../client}/src/invariant.ts                  |  0
 .../client}/src/types.ts                      |  0
 .../client}/tests/dispose.spec.ts             |  0
 .../client}/tests/fake-runtime.ts             |  0
 .../client}/tests/sdk-client.spec.ts          |  0
 .../client}/tsconfig.json                     |  2 +-
 .../create-sdk/README.i18n.yaml               |  2 +-
 .../{sdk => scaffold}/create-sdk/README.md    |  0
 .../{sdk => scaffold}/create-sdk/README.zh.md |  0
 .../{sdk => scaffold}/create-sdk/package.json |  0
 .../{sdk => scaffold}/create-sdk/src/args.ts  |  0
 .../{sdk => scaffold}/create-sdk/src/bin.ts   |  0
 .../create-sdk/src/command.ts                 |  0
 .../create-sdk/src/create-questions.ts        |  0
 .../create-sdk/src/create-wizard.ts           |  0
 .../create-sdk/src/headless.ts                |  0
 .../{sdk => scaffold}/create-sdk/src/index.ts |  0
 .../create-sdk/src/invariant.ts               |  0
 .../create-sdk/src/project-scaffolder.ts      |  0
 .../src/templates/assets/created.txt.tpl      |  0
 .../templates/assets/install-question.txt.tpl |  0
 .../src/templates/assets/next-steps.txt.tpl   |  0
 .../templates/assets/setup-failure.txt.tpl    |  0
 .../src/templates/assets/usage.txt.tpl        |  0
 .../src/templates/create-templates.ts         |  0
 .../create-sdk/tests/built-artifacts.e2e.ts   |  4 +--
 .../create-sdk/tests/create.snapshot.ts       |  0
 .../create-sdk/tests/create.spec.ts           |  0
 .../create-sdk/tests/link-workspace.e2e.ts    |  2 +-
 .../create-sdk/tsconfig.json                  |  0
 .../create-sdk/tsdown.config.ts               |  0
 .../{sdk => scaffold}/helper/README.i18n.yaml |  2 +-
 packages/{sdk => scaffold}/helper/README.md   |  0
 .../{sdk => scaffold}/helper/README.zh.md     |  0
 .../{sdk => scaffold}/helper/package.json     |  0
 .../helper/src/documents/cordis-yaml-file.ts  |  0
 .../helper/src/documents/env-file.ts          |  0
 .../helper/src/documents/package-json-file.ts |  0
 .../src/documents/pnpm-workspace-file.ts      |  0
 .../helper/src/documents/project-file.ts      |  0
 .../helper/src/documents/tsconfig-file.ts     |  0
 .../helper/src/features/builtin/app.ts        |  0
 .../helper/src/features/builtin/helpers.ts    |  0
 .../helper/src/features/builtin/index.ts      |  0
 .../helper/src/features/builtin/provider.ts   |  0
 .../helper/src/features/builtin/spine.ts      |  0
 .../helper/src/features/define-feature.ts     |  0
 .../src/features/feature-configurator.ts      |  0
 .../helper/src/features/feature.ts            |  0
 .../helper/src/features/registry.ts           |  0
 .../helper/src/features/resources.ts          |  0
 packages/{sdk => scaffold}/helper/src/ids.ts  |  0
 .../{sdk => scaffold}/helper/src/index.ts     |  4 +++
 .../{sdk => scaffold}/helper/src/invariant.ts |  0
 .../src/package-managers/link-workspace.ts    |  0
 .../src/package-managers/package-manager.ts   |  0
 .../src/plugins/local-plugin-blueprint.ts     |  0
 .../helper/src/project/change-set.ts          |  0
 .../src/project/npm-dependency-policy.ts      |  0
 .../src/project/project-edit-session.ts       |  0
 .../helper/src/project/sdk-project.ts         |  2 +-
 .../helper/src/project/types.ts               |  0
 .../src/questions/clack-nested-multiselect.ts |  0
 .../helper/src/questions/clack-prompt-port.ts |  0
 .../src/questions/headless-prompt-port.ts     |  0
 .../helper/src/questions/prompt-port.ts       |  0
 .../helper/src/questions/question.ts          |  0
 .../helper/src/templates/assets/README.md.tpl |  0
 .../helper/src/templates/assets/gitignore.tpl |  0
 .../helper/src/templates/assets/index.ts.tpl  |  0
 .../assets/local-plugin-tsdown.config.ts.tpl  |  0
 .../src/templates/assets/local-plugin.ts.tpl  |  0
 .../src/templates/assets/local-tool.ts.tpl    |  0
 .../src/templates/assets/package.json.tpl     |  0
 .../src/templates/assets/persona.txt.tpl      |  0
 .../templates/assets/tsconfig.base.json.tpl   |  0
 .../src/templates/assets/tsdown.config.ts.tpl |  0
 .../src/templates/assets/yarnrc.yml.tpl       |  0
 .../helper/src/templates/project-template.ts  |  0
 .../helper/src/templates/template-assets.ts   |  0
 .../helper/src/templates/text-template.ts     |  0
 .../helper/tests/documents.spec.ts            |  0
 .../helper/tests/headless-prompt-port.spec.ts |  0
 .../helper/tests/project.spec.ts              |  0
 .../helper/tests/questions.spec.ts            |  0
 .../{sdk => scaffold}/helper/tsconfig.json    |  0
 .../{sdk => scaffold}/helper/tsdown.config.ts |  0
 packages/scaffold/protocol/README.i18n.yaml   |  6 ++++
 .../protocol}/README.md                       |  6 ++--
 .../protocol}/README.zh.md                    |  0
 .../protocol}/package.json                    |  0
 .../protocol}/src/index.ts                    |  0
 .../protocol}/src/invariant.ts                |  0
 .../protocol}/src/transport.ts                |  0
 .../protocol}/src/types.ts                    |  0
 .../protocol}/tests/transport.spec.ts         |  0
 .../protocol}/tsconfig.json                   |  0
 .../scripts/README.i18n.yaml                  |  2 +-
 packages/{sdk => scaffold}/scripts/README.md  |  0
 .../{sdk => scaffold}/scripts/README.zh.md    |  0
 .../{sdk => scaffold}/scripts/package.json    |  0
 .../{sdk => scaffold}/scripts/src/args.ts     |  0
 packages/{sdk => scaffold}/scripts/src/bin.ts |  0
 .../{sdk => scaffold}/scripts/src/build.ts    |  0
 .../{sdk => scaffold}/scripts/src/command.ts  |  0
 .../{sdk => scaffold}/scripts/src/config.ts   |  0
 .../scripts/src/config/config-workflow.ts     |  0
 .../scripts/src/create-plugin.ts              |  0
 .../scripts/src/dev/tsdown-config.ts          |  0
 packages/scaffold/scripts/src/index.ts        | 11 ++++++
 .../scripts/src/invariant.ts                  |  0
 .../scripts/src/local-plugin-loader-hooks.ts  |  0
 .../{sdk => scaffold}/scripts/src/runtime.ts  |  0
 .../scripts/src/telemetry.ts                  |  0
 .../assets/config-install-failure.txt.tpl     |  0
 .../src/templates/assets/usage.txt.tpl        |  0
 .../src/templates/dsh-sdk-templates.ts        |  0
 .../__snapshots__/config.snapshot.ts.snap     |  0
 .../scripts/tests/config.snapshot.ts          |  0
 .../scripts/tests/scripts.spec.ts             |  0
 .../{sdk => scaffold}/scripts/tsconfig.json   |  2 +-
 .../scripts/tsdown.config.ts                  |  0
 packages/scaffold/server/README.i18n.yaml     |  6 ++++
 .../{ui/jsonrpc => scaffold/server}/README.md |  2 +-
 .../jsonrpc => scaffold/server}/README.zh.md  |  2 +-
 .../jsonrpc => scaffold/server}/package.json  |  0
 .../jsonrpc => scaffold/server}/src/index.ts  |  4 +++
 .../server}/src/invariant.ts                  |  0
 .../jsonrpc => scaffold/server}/src/server.ts |  0
 .../server}/tests/built-scope-carrier.e2e.ts  |  2 +-
 .../server}/tests/plugin-apply.spec.ts        |  0
 .../server}/tests/plugin-shape.spec.ts        |  0
 .../server}/tests/server.spec.ts              |  0
 .../jsonrpc => scaffold/server}/tsconfig.json |  2 +-
 .../telemetry/README.i18n.yaml                |  2 +-
 .../{sdk => scaffold}/telemetry/README.md     |  0
 .../{sdk => scaffold}/telemetry/README.zh.md  |  0
 .../{sdk => scaffold}/telemetry/package.json  |  0
 .../telemetry/src/anonymous-id.ts             |  0
 .../telemetry/src/consent-resolver.ts         |  0
 .../{sdk => scaffold}/telemetry/src/index.ts  |  4 +++
 .../telemetry/src/invariant.ts                |  0
 .../telemetry/src/payload.ts                  |  0
 .../telemetry/src/reporter.ts                 |  0
 .../telemetry/src/secret-redactor.ts          |  0
 .../telemetry/tests/anonymous-id.spec.ts      |  0
 .../telemetry/tests/consent-resolver.spec.ts  |  0
 .../telemetry/tests/payload.spec.ts           |  0
 .../telemetry/tests/reporter.spec.ts          |  0
 .../telemetry/tests/secret-redactor.spec.ts   |  0
 .../{sdk => scaffold}/telemetry/tsconfig.json |  0
 packages/sdk/README.zh.md                     | 16 ---------
 packages/sdk/scripts/src/index.ts             |  7 ----
 packages/sdk/sdk-protocol/README.i18n.yaml    |  6 ----
 .../subagent-dsh-sdk/README.i18n.yaml         |  4 +--
 packages/subagent/subagent-dsh-sdk/README.md  |  2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |  2 +-
 .../tests/subagent-dsh-sdk.spec.ts            |  2 +-
 .../subagent/subagent-dsh-sdk/tsconfig.json   |  4 +--
 .../subagent/subagent-inprocess/tsconfig.json |  2 +-
 .../typert/generator/tests/type-model.spec.ts | 22 ++++++------
 packages/ui/jsonrpc/README.i18n.yaml          |  6 ----
 packages/ui/permission/README.i18n.yaml       |  6 ----
 packages/ui/user-interaction/README.i18n.yaml |  6 ----
 scripts/gen-cordis-catalog.ts                 | 10 +++---
 scripts/gen-third-party-notices.spec.ts       |  2 +-
 scripts/gen-tool-catalog.ts                   |  2 +-
 scripts/run-gates.ts                          |  2 +-
 scripts/type-equiv.manifest.json              | 36 +++++++++----------
 .../verify-package-readme-model-experience.ts | 18 +++++-----
 tsconfig.base.json                            | 23 ++++++++----
 tsconfig.host.json                            | 26 +++++++-------
 vendor/README.md                              |  8 ++---
 vitest.config.ts                              | 10 +++---
 vitest.snapshot.config.ts                     |  2 +-
 351 files changed, 368 insertions(+), 311 deletions(-)
 rename packages/{sdk => boot}/README.i18n.yaml (57%)
 create mode 100644 packages/boot/README.md
 create mode 100644 packages/boot/README.zh.md
 rename packages/{ui => boot}/app-boot/README.i18n.yaml (81%)
 rename packages/{ui => boot}/app-boot/README.md (100%)
 rename packages/{ui => boot}/app-boot/README.zh.md (100%)
 rename packages/{ui => boot}/app-boot/package.json (100%)
 rename packages/{ui => boot}/app-boot/src/index.ts (100%)
 rename packages/{ui => boot}/app-boot/src/invariant.ts (100%)
 rename packages/{ui => boot}/app-boot/src/profile.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/app-boot.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/config-dump.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/config-reload.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/hmr-config.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/profile.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/repository-cache.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/user-patches.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tsconfig.json (100%)
 rename packages/{ui => boot}/app-boot/tsdown.config.ts (100%)
 create mode 100644 packages/interaction/README.i18n.yaml
 rename packages/{ui => interaction}/README.md (71%)
 rename packages/{ui => interaction}/README.zh.md (69%)
 rename packages/{ui => interaction}/commands/README.i18n.yaml (79%)
 rename packages/{ui => interaction}/commands/README.md (100%)
 rename packages/{ui => interaction}/commands/README.zh.md (100%)
 rename packages/{ui => interaction}/commands/package.json (100%)
 rename packages/{ui => interaction}/commands/src/brand.ts (100%)
 rename packages/{ui => interaction}/commands/src/index.ts (100%)
 rename packages/{ui => interaction}/commands/src/invariant.ts (100%)
 rename packages/{ui => interaction}/commands/tests/commands.spec.ts (100%)
 rename packages/{ui => interaction}/commands/tests/invariant.spec.ts (100%)
 rename packages/{ui => interaction}/commands/tsconfig.json (100%)
 create mode 100644 packages/interaction/permission/README.i18n.yaml
 rename packages/{ui => interaction}/permission/README.md (100%)
 rename packages/{ui => interaction}/permission/README.zh.md (100%)
 rename packages/{ui => interaction}/permission/package.json (100%)
 rename packages/{ui => interaction}/permission/src/client.ts (100%)
 rename packages/{ui => interaction}/permission/src/index.ts (100%)
 rename packages/{ui => interaction}/permission/src/invariant.ts (100%)
 rename packages/{ui => interaction}/permission/src/types.ts (100%)
 rename packages/{ui => interaction}/permission/tests/invariant.spec.ts (100%)
 rename packages/{ui => interaction}/permission/tests/permission.spec.ts (100%)
 rename packages/{ui => interaction}/permission/tests/projection.spec.ts (100%)
 rename packages/{ui => interaction}/permission/tsconfig.json (100%)
 rename packages/{ui => interaction}/tool-ask-user/README.i18n.yaml (79%)
 rename packages/{ui => interaction}/tool-ask-user/README.md (100%)
 rename packages/{ui => interaction}/tool-ask-user/README.zh.md (100%)
 rename packages/{ui => interaction}/tool-ask-user/package.json (100%)
 rename packages/{ui => interaction}/tool-ask-user/src/index.ts (100%)
 rename packages/{ui => interaction}/tool-ask-user/src/invariant.ts (100%)
 rename packages/{ui => interaction}/tool-ask-user/tests/tool-ask-user.spec.ts (100%)
 rename packages/{ui => interaction}/tool-ask-user/tsconfig.json (100%)
 rename packages/{ui => interaction}/user-approval/README.i18n.yaml (79%)
 rename packages/{ui => interaction}/user-approval/README.md (100%)
 rename packages/{ui => interaction}/user-approval/README.zh.md (100%)
 rename packages/{ui => interaction}/user-approval/package.json (100%)
 rename packages/{ui => interaction}/user-approval/src/index.ts (100%)
 rename packages/{ui => interaction}/user-approval/src/invariant.ts (100%)
 rename packages/{ui => interaction}/user-approval/src/types.ts (100%)
 rename packages/{ui => interaction}/user-approval/tests/approval.spec.ts (100%)
 rename packages/{ui => interaction}/user-approval/tests/invariant.spec.ts (100%)
 rename packages/{ui => interaction}/user-approval/tsconfig.json (100%)
 rename packages/{ui => interaction}/user-approval/tsdown.config.ts (100%)
 create mode 100644 packages/interaction/user-interaction/README.i18n.yaml
 rename packages/{ui => interaction}/user-interaction/README.md (100%)
 rename packages/{ui => interaction}/user-interaction/README.zh.md (100%)
 rename packages/{ui => interaction}/user-interaction/package.json (100%)
 rename packages/{ui => interaction}/user-interaction/src/index.ts (100%)
 rename packages/{ui => interaction}/user-interaction/src/invariant.ts (100%)
 rename packages/{ui => interaction}/user-interaction/src/types.ts (100%)
 rename packages/{ui => interaction}/user-interaction/tests/user-interaction.spec.ts (100%)
 rename packages/{ui => interaction}/user-interaction/tsconfig.json (100%)
 rename packages/{ui => scaffold}/README.i18n.yaml (57%)
 rename packages/{sdk => scaffold}/README.md (64%)
 create mode 100644 packages/scaffold/README.zh.md
 rename packages/{sdk/sdk-client => scaffold/client}/README.i18n.yaml (80%)
 rename packages/{sdk/sdk-client => scaffold/client}/README.md (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/README.zh.md (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/package.json (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/api.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/client.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/dispose.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/index.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/invariant.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/types.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tests/dispose.spec.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tests/fake-runtime.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tests/sdk-client.spec.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tsconfig.json (93%)
 rename packages/{sdk => scaffold}/create-sdk/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/create-sdk/README.md (100%)
 rename packages/{sdk => scaffold}/create-sdk/README.zh.md (100%)
 rename packages/{sdk => scaffold}/create-sdk/package.json (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/args.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/bin.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/command.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/create-questions.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/create-wizard.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/headless.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/index.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/project-scaffolder.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/created.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/install-question.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/next-steps.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/setup-failure.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/usage.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/create-templates.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/tests/built-artifacts.e2e.ts (87%)
 rename packages/{sdk => scaffold}/create-sdk/tests/create.snapshot.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/tests/create.spec.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/tests/link-workspace.e2e.ts (98%)
 rename packages/{sdk => scaffold}/create-sdk/tsconfig.json (100%)
 rename packages/{sdk => scaffold}/create-sdk/tsdown.config.ts (100%)
 rename packages/{sdk => scaffold}/helper/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/helper/README.md (100%)
 rename packages/{sdk => scaffold}/helper/README.zh.md (100%)
 rename packages/{sdk => scaffold}/helper/package.json (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/cordis-yaml-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/env-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/package-json-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/pnpm-workspace-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/project-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/tsconfig-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/app.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/helpers.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/index.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/provider.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/spine.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/define-feature.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/feature-configurator.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/feature.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/registry.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/resources.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/ids.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/index.ts (86%)
 rename packages/{sdk => scaffold}/helper/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/package-managers/link-workspace.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/package-managers/package-manager.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/plugins/local-plugin-blueprint.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/change-set.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/npm-dependency-policy.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/project-edit-session.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/sdk-project.ts (99%)
 rename packages/{sdk => scaffold}/helper/src/project/types.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/clack-nested-multiselect.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/clack-prompt-port.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/headless-prompt-port.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/prompt-port.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/question.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/README.md.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/gitignore.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/index.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/local-plugin.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/local-tool.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/package.json.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/persona.txt.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/tsconfig.base.json.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/tsdown.config.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/yarnrc.yml.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/project-template.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/template-assets.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/text-template.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/documents.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/headless-prompt-port.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/project.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/questions.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tsconfig.json (100%)
 rename packages/{sdk => scaffold}/helper/tsdown.config.ts (100%)
 create mode 100644 packages/scaffold/protocol/README.i18n.yaml
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/README.md (90%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/README.zh.md (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/package.json (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/index.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/invariant.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/transport.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/types.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/tests/transport.spec.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/tsconfig.json (100%)
 rename packages/{sdk => scaffold}/scripts/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/scripts/README.md (100%)
 rename packages/{sdk => scaffold}/scripts/README.zh.md (100%)
 rename packages/{sdk => scaffold}/scripts/package.json (100%)
 rename packages/{sdk => scaffold}/scripts/src/args.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/bin.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/build.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/command.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/config.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/config/config-workflow.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/create-plugin.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/dev/tsdown-config.ts (100%)
 create mode 100644 packages/scaffold/scripts/src/index.ts
 rename packages/{sdk => scaffold}/scripts/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/local-plugin-loader-hooks.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/runtime.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/telemetry.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/templates/assets/config-install-failure.txt.tpl (100%)
 rename packages/{sdk => scaffold}/scripts/src/templates/assets/usage.txt.tpl (100%)
 rename packages/{sdk => scaffold}/scripts/src/templates/dsh-sdk-templates.ts (100%)
 rename packages/{sdk => scaffold}/scripts/tests/__snapshots__/config.snapshot.ts.snap (100%)
 rename packages/{sdk => scaffold}/scripts/tests/config.snapshot.ts (100%)
 rename packages/{sdk => scaffold}/scripts/tests/scripts.spec.ts (100%)
 rename packages/{sdk => scaffold}/scripts/tsconfig.json (88%)
 rename packages/{sdk => scaffold}/scripts/tsdown.config.ts (100%)
 create mode 100644 packages/scaffold/server/README.i18n.yaml
 rename packages/{ui/jsonrpc => scaffold/server}/README.md (95%)
 rename packages/{ui/jsonrpc => scaffold/server}/README.zh.md (95%)
 rename packages/{ui/jsonrpc => scaffold/server}/package.json (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/src/index.ts (92%)
 rename packages/{ui/jsonrpc => scaffold/server}/src/invariant.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/src/server.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/built-scope-carrier.e2e.ts (98%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/plugin-apply.spec.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/plugin-shape.spec.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/server.spec.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tsconfig.json (93%)
 rename packages/{sdk => scaffold}/telemetry/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/telemetry/README.md (100%)
 rename packages/{sdk => scaffold}/telemetry/README.zh.md (100%)
 rename packages/{sdk => scaffold}/telemetry/package.json (100%)
 rename packages/{sdk => scaffold}/telemetry/src/anonymous-id.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/consent-resolver.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/index.ts (82%)
 rename packages/{sdk => scaffold}/telemetry/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/payload.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/reporter.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/secret-redactor.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/anonymous-id.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/consent-resolver.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/payload.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/reporter.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/secret-redactor.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tsconfig.json (100%)
 delete mode 100644 packages/sdk/README.zh.md
 delete mode 100644 packages/sdk/scripts/src/index.ts
 delete mode 100644 packages/sdk/sdk-protocol/README.i18n.yaml
 delete mode 100644 packages/ui/jsonrpc/README.i18n.yaml
 delete mode 100644 packages/ui/permission/README.i18n.yaml
 delete mode 100644 packages/ui/user-interaction/README.i18n.yaml

diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
index 3cf9548d4d..9b2c456d88 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
@@ -7,7 +7,7 @@ English | [中文](2026-07-27-tui-chat-channel-module-split.zh.md)
 
 ## Problem
 
-`packages/ui/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
+`packages/interaction/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
 
 ## Decision
 
diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
index d5de02bd0f..44e8ffeac4 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
@@ -7,7 +7,7 @@ Archived: 2026-08-04
 
 ## Problem
 
-`packages/ui/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
+`packages/interaction/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
 
 ## Decision
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
index 62784ed7cd..998e9dfcdc 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
@@ -11,7 +11,7 @@ The TUI rendered transcript notices for `error`, `aborted`, `max-tokens`, `rejec
 
 ## Decision
 
-The `turn/end` case in `packages/ui/tui/src/index.ts` switches on the reason's discriminant and covers every kind: `completed` stays silent because the settled assistant message and its `Completed` timing header already present that outcome; `disposed` appends `Turn stopped: the agent was disposed.`; and the merge-extensible default appends `Turn ended: <kind>.` so an unknown plugin-added outcome still names why the agent stopped. All other kinds keep their existing notices.
+The `turn/end` case in `packages/interaction/tui/src/index.ts` switches on the reason's discriminant and covers every kind: `completed` stays silent because the settled assistant message and its `Completed` timing header already present that outcome; `disposed` appends `Turn stopped: the agent was disposed.`; and the merge-extensible default appends `Turn ended: <kind>.` so an unknown plugin-added outcome still names why the agent stopped. All other kinds keep their existing notices.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
index 162ba4ed44..ad53755259 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
@@ -11,7 +11,7 @@ TUI 会为 `error`、`aborted`、`max-tokens`、`rejected`、`interrupted` 这
 
 ## 决策
 
-`packages/ui/tui/src/index.ts` 中的 `turn/end` 分支按 reason 的判别字段做 switch，覆盖每一种 kind：`completed` 保持沉默，因为已定稿的助手消息及其 `Completed` 计时头部已经呈现了这一结果；`disposed` 追加 `Turn stopped: the agent was disposed.`；merge 扩展的 default 分支追加 `Turn ended: <kind>.`，让未知的插件新增结果仍能点明 agent 停止的原因。其余各 kind 保留现有通知。
+`packages/interaction/tui/src/index.ts` 中的 `turn/end` 分支按 reason 的判别字段做 switch，覆盖每一种 kind：`completed` 保持沉默，因为已定稿的助手消息及其 `Completed` 计时头部已经呈现了这一结果；`disposed` 追加 `Turn stopped: the agent was disposed.`；merge 扩展的 default 分支追加 `Turn ended: <kind>.`，让未知的插件新增结果仍能点明 agent 停止的原因。其余各 kind 保留现有通知。
 
 ## 备选方案
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
index 1a04e738a2..184a05ed23 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
@@ -15,7 +15,7 @@ The interactive channel must remain a Cordis plugin over the same agent, session
 
 ## Decision
 
-DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
+DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
 
 The package is a terminal front door, not a complete application. A host mounts `@deepseek-ai/dsh-tui` before its configured agent and composes the backends, tools, and policies around it. The product CLI currently ships no terminal composition; non-interactive tasks use headless mode, Web owns the installed human surface, and ACP remains a separate automation protocol.
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
index 75fc3d47aa..6ac3eefa51 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
@@ -15,7 +15,7 @@ Archived: 2026-08-04
 
 ## 决策
 
-DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
+DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
 
 该包是终端入口，而不是完整应用。宿主在已配置 agent 之前挂载 `@deepseek-ai/dsh-tui`，并围绕它组合后端、工具和策略。产品 CLI 目前不交付终端组合；非交互任务使用 headless 模式，Web 是已安装产品中面向人的界面，而 ACP 仍是独立的自动化协议。
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
index 9308df7fb4..2c8e92671f 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
@@ -13,7 +13,7 @@ The TUI platform contract must follow the runtime shipped to users rather than t
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
+[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
 
 The real Loader smoke selects a native pseudo-terminal boundary by host. macOS and Linux retain the Python POSIX PTY driver. Windows uses `node-pty` and ConPTY. Both drivers receive the same launch command, environment, terminal dimensions, marker-gated input actions, timeout, expected exit code, and output assertions, and all three smoke scenarios run on every supported platform.
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
index 8b4a1eb4ce..cb5d05da2b 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
@@ -13,7 +13,7 @@ TUI 平台契约必须以交付给用户的运行时为准，而不是取决于
 
 ## 决策
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
+[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
 
 真实 Loader 冒烟测试根据宿主选择原生伪终端边界。macOS 和 Linux 继续使用 Python POSIX PTY 驱动，Windows 则使用 `node-pty` 和 ConPTY。两种驱动接收相同的启动命令、环境、终端尺寸、以标记为触发条件的输入动作、超时、预期退出码和输出断言；3 个冒烟场景都会在每个受支持平台上运行。
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
index e151f92d0d..038d12a561 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
@@ -11,7 +11,7 @@ The [skill system](2026-07-05-skill-system.md) shipped with model-initiated load
 
 ## Decision
 
-The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
+The [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
 
 The TUI reads the skill service through `ctx.get('skills')`, not a declared injection, because skills mount conditionally: a deployment without the registry keeps a working front door, and `/skill:` there reports that skills are unavailable rather than failing to mount. `createTuiChat` is synchronous while `ctx.skills.list()` is async, so autocomplete seeds the static slash commands immediately and rebuilds the provider with `skill:<name>` entries once the catalog resolves; a resolution that arrives after disposal is dropped, and a rejected lookup keeps the base commands.
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
index ac1c4da948..af01642c07 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-04
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
+[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
 
 TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:<name>` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
index 2ef926cff9..ff4a310f08 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
@@ -13,7 +13,7 @@ The TUI assistant message opened with a single header line joining the `Assistan
 
 **Split the label from the timing; render the timing as the message's trailing line.**
 
-`AssistantMessageComponent` (packages/ui/tui/src/index.ts) now emits the bold `Assistant` label as the first line and appends the dim timing string (already assembled by `StreamingAssistantComponent.rebuild()` as `header`, including the `· Completed …` suffix when settled) as the last child, after reasoning and text. The timing content, bucket-hiding, and completion-time behavior are unchanged — only its position moved from the top to the bottom of the message.
+`AssistantMessageComponent` (packages/interaction/tui/src/index.ts) now emits the bold `Assistant` label as the first line and appends the dim timing string (already assembled by `StreamingAssistantComponent.rebuild()` as `header`, including the `· Completed …` suffix when settled) as the last child, after reasoning and text. The timing content, bucket-hiding, and completion-time behavior are unchanged — only its position moved from the top to the bottom of the message.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
index 282ac1e65b..08ced9603d 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
@@ -13,7 +13,7 @@ TUI 的助手消息此前以一行开头，把 `Assistant` 标签和步骤计时
 
 **把标签与计时拆开；计时作为消息的末行渲染。**
 
-`AssistantMessageComponent`（packages/ui/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
+`AssistantMessageComponent`（packages/interaction/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
index ca5edc50bf..76cc213ba8 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
@@ -11,7 +11,7 @@ Roughly ten e2e/smoke files re-derived the same spawn-collect-timeout choreograp
 
 Two related test-infra hand-rolls compounded the case:
 
-- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/sdk/scripts`).
+- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/scaffold/scripts`).
 - `apps/web/tests/smoke-real.e2e.ts` and `apps/web/tests/scaffold.ts` carried two verbatim copies of a regex `.env` parser (~20 lines) where the `process.loadEnvFile` builtin has exactly the required no-override semantics — and the vitest e2e/snapshot/web configs already load root `.env` with it before these files run, making the copies dead.
 - The snapshot harness hand-rolled three poll-until-deadline loops (`waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile` in `packages/support/acp-snapshot/src/harness.ts`, ~55 lines) plus `waitForFile` in `crash-recovery.e2e.ts`, where `vi.waitFor`/`expect.poll` cover the shape — vitest is already a runtime dependency of `dsh-acp-snapshot`, so this adds nothing.
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
index 186e5cd560..f597fd1e08 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-07
 
 另有两处相关的测试基础设施手写代码进一步强化了替换的理由：
 
-- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/sdk/scripts`）。
+- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/scaffold/scripts`）。
 - `apps/web/tests/smoke-real.e2e.ts` 与 `apps/web/tests/scaffold.ts` 曾携带两份逐字相同的正则 `.env` 解析器拷贝（约 20 行），而内置的 `process.loadEnvFile` 恰好具备所需的「不覆盖已有值」语义；并且 vitest 的 e2e/snapshot/web 配置在这些文件运行之前就已用它加载了根 `.env`，这两份拷贝实为死代码。
 - 快照 harness 曾手写三个「轮询直到截止时间」的循环（`packages/support/acp-snapshot/src/harness.ts` 中的 `waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile`，约 55 行），外加 `crash-recovery.e2e.ts` 中的 `waitForFile`，而 `vi.waitFor`/`expect.poll` 正好覆盖这种形态；vitest 本来就是 `dsh-acp-snapshot` 的运行时依赖，因此这不新增任何东西。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index 7a0b74dfaf..08d8319d33 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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 .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: f3da981c478ef08672a82f23ab9cd42e0f38ebab
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 5a8e15aab79875bdb08e6347199924c4215a2705
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: fe09e1b83f4f0a9f867f78351f643b1bd26d7c9d
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: ee49d7ea8fade9d3e323e8c6921479b8053809af
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index f3da981c47..fe09e1b83f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -27,8 +27,8 @@ Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's t
 
 The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `acp/acp` + `examples/acp-demo` pattern — the serving surface is itself a plugin:
 
-- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
-- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).
+- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
+- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).
 
 Config discovery has two channels and fails loudly when both are missing: the `DSH_CORDIS_CONFIG` environment variable first (the SDK client convention), then an argv positional argument; no default path and no built-in fallback whatsoever — "the plugins actually booted are decided by an external cordis.yml" is a hard semantic.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index 5a8e15aab7..ee49d7ea8f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -27,8 +27,8 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 确定性协议实现（`server.ts` / `transport.ts`）按 `acp/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件：
 
-- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
-- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
+- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
+- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
 
 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——「实际启动的插件由外部 `cordis.yml` 决定」是硬语义。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
index 6f4a6d363d..6e2c9a635d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.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 .agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
-2026-07-20-config-hot-reload-resilience.md: 0f15bb0aaacb6e06c416cbe35b44155279497eee
-2026-07-20-config-hot-reload-resilience.zh.md: 8a185c1915b5247150d8bb1dd5c42d69bd4f2a35
+2026-07-20-config-hot-reload-resilience.md: 2b98ee73e1c7734da9c0ae6df5e3de1af6a5cbeb
+2026-07-20-config-hot-reload-resilience.zh.md: 4ddf1f07f4ff5449f3bd91aa2b38f6045eb4e1c6
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
index 0f15bb0aaa..2b98ee73e1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
@@ -38,4 +38,4 @@ HMR contains live refresh rejection. Its `registerConfig(filename, refresh)` met
 
 ## Testing
 
-`packages/ui/app-boot/tests/config-reload.spec.ts` boots real temporary Loader/Include trees and covers parse and shape rejection, import-before-dispose, plugin/config restoration, multi-entry rollback, ancestor disablement, overlay convergence, option identity, failed direct-update persistence, and failed programmatic moves. `packages/ui/app-boot/tests/hmr-config.spec.ts` covers existing and missing exact paths, add/change/removal, serialized coalescing, disposal drainage, non-`Error` normalization, failure broadcast, and rejecting-observer containment. `packages/host/webserver/tests/webserver.spec.ts` proves a service-gated startup failure rejects Loader composition with its bind diagnostic, `packages/typert/loader/tests/loader.spec.ts` exercises awaited programmatic removal through a real Loader consumer, and the ACP `pty-tools` snapshot guards concurrent composition from reordering equal-priority prompt sections.
+`packages/boot/app-boot/tests/config-reload.spec.ts` boots real temporary Loader/Include trees and covers parse and shape rejection, import-before-dispose, plugin/config restoration, multi-entry rollback, ancestor disablement, overlay convergence, option identity, failed direct-update persistence, and failed programmatic moves. `packages/boot/app-boot/tests/hmr-config.spec.ts` covers existing and missing exact paths, add/change/removal, serialized coalescing, disposal drainage, non-`Error` normalization, failure broadcast, and rejecting-observer containment. `packages/host/webserver/tests/webserver.spec.ts` proves a service-gated startup failure rejects Loader composition with its bind diagnostic, `packages/typert/loader/tests/loader.spec.ts` exercises awaited programmatic removal through a real Loader consumer, and the ACP `pty-tools` snapshot guards concurrent composition from reordering equal-priority prompt sections.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
index 8a185c1915..4ddf1f07f4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
@@ -38,4 +38,4 @@ HMR 收容实时刷新 rejection。其 `registerConfig(filename, refresh)` 方
 
 ## Testing
 
-`packages/ui/app-boot/tests/config-reload.spec.ts` 启动真实的临时 Loader/Include 树，并覆盖对解析和形状错误的拒绝、先导入再 dispose、插件/配置恢复、多配置项回滚、祖先禁用、overlay 收敛、option 对象身份、失败的直接更新不持久化以及失败的程序化移动。`packages/ui/app-boot/tests/hmr-config.spec.ts` 覆盖现有和缺失的确切路径、添加/变更/移除、串行化合并、dispose 排空、非 `Error` 值的规范化、失败广播以及对发生 rejection 的观察者的收容。`packages/host/webserver/tests/webserver.spec.ts` 证明受服务门控的启动失败会让 Loader 组合以其 bind 诊断 reject；`packages/typert/loader/tests/loader.spec.ts` 则通过真实 Loader 消费方演练可等待的程序化移除；ACP（Agent Client Protocol）的 `pty-tools` 快照会防止并发组合改变同优先级提示词段的顺序。
+`packages/boot/app-boot/tests/config-reload.spec.ts` 启动真实的临时 Loader/Include 树，并覆盖对解析和形状错误的拒绝、先导入再 dispose、插件/配置恢复、多配置项回滚、祖先禁用、overlay 收敛、option 对象身份、失败的直接更新不持久化以及失败的程序化移动。`packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖现有和缺失的确切路径、添加/变更/移除、串行化合并、dispose 排空、非 `Error` 值的规范化、失败广播以及对发生 rejection 的观察者的收容。`packages/host/webserver/tests/webserver.spec.ts` 证明受服务门控的启动失败会让 Loader 组合以其 bind 诊断 reject；`packages/typert/loader/tests/loader.spec.ts` 则通过真实 Loader 消费方演练可等待的程序化移除；ACP（Agent Client Protocol）的 `pty-tools` 快照会防止并发组合改变同优先级提示词段的顺序。
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index fa097ae230..b5c6343382 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.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 .agents/notes/implemented/feature/2026-07-06-approval-seam.md
-2026-07-06-approval-seam.md: ae143a41302b7bcd6029345fa91ca4eda837c141
-2026-07-06-approval-seam.zh.md: 2f95f67ecd33b4c659e56d5f3cc6168bf01e35ce
+2026-07-06-approval-seam.md: a286e07d51a70232f9aab0af5d8a19622cd222d4
+2026-07-06-approval-seam.zh.md: 6656cfe46de663f0e89eacc78dcfb3425812f9e0
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
index ae143a4130..a286e07d51 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
@@ -12,7 +12,7 @@ The routing problem is ownership: a permission request must reach the channel th
 
 ## Decision
 
-One package, `dsh-user-approval` (`packages/ui/user-approval`), owns the vocabulary and the `ctx.approval` service — the mechanism. The policy — who answers, and whether a session is asked at all — lives outside it: answerers are `approval/request` waterfall listeners registered by channel-owning plugins (the ACP bridge, host adapters, and test scripts), and a per-session policy tier can decide before a channel is involved. Consumers (`dsh-tools`' ask routing and the sandbox escalation gate) resolve a question to a closed outcome and derive their own tool results from it. This is deliberately one package, not the capability-seam three (see Alternatives).
+One package, `dsh-user-approval` (`packages/interaction/user-approval`), owns the vocabulary and the `ctx.approval` service — the mechanism. The policy — who answers, and whether a session is asked at all — lives outside it: answerers are `approval/request` waterfall listeners registered by channel-owning plugins (the ACP bridge, host adapters, and test scripts), and a per-session policy tier can decide before a channel is involved. Consumers (`dsh-tools`' ask routing and the sandbox escalation gate) resolve a question to a closed outcome and derive their own tool results from it. This is deliberately one package, not the capability-seam three (see Alternatives).
 
 ### How a deployment uses it
 
@@ -95,7 +95,7 @@ Snapshots record allowed and rejected sandbox escalation through `session/reques
 
 - **A single registered provider instead of waterfall listeners** — rejected: a `registerProvider()` surface forces every composition question — allowlist pre-filters, external hook deciders, scripted test answers, a policy gate in front of a human — inside one provider implementation. The waterfall gets composition, fail-closed absence, and HMR disposal from machinery the runtime already has; the seam's JSDoc pins the single-decision-slot convention instead of inventing a provider registry.
 - **An inline `tools/pre-execute` permission gate in the ACP bridge** — rejected: prompting for every bridge-owned call hardwires the asking policy into the transport, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hook-produced `ask` decisions without a shared mechanism.
-- **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/ui/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
+- **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/interaction/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
 - **Static optional injection in `dsh-tools`** — rejected: the vendored cordis `Inject` type has no optional flag — the object form maps service names to intercept config, and a declared inject gates the fiber. `ctx.get('approval')` is the documented opportunistic-consumption pattern (the `tool-bash` owner-token lookup, the loop's persistence probe), reads presence per call, and degrades correctly across HMR without extra machinery.
 - **The capability-seam three-package split** — rejected: interface/implementation/consumer fits a seam whose implementation is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture an implementation package with nothing in it ("don't split preemptively").
 - **Offering `allow_always` now** — rejected: the protocol can express it, but honoring it means designing grant storage, scope identity, and revocation (§ Deferred). Advertising an option the harness cannot honor manufactures doomed grants.
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
index 2f95f67ecd..6656cfe46d 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-一个包`dsh-user-approval`（`packages/ui/user-approval`）负责定义词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP（Agent Client Protocol）桥、宿主适配器、测试脚本），而每会话的策略层可以在任何通道介入之前做出决定。消费方（`dsh-tools` 的 ask 路由和沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
+一个包`dsh-user-approval`（`packages/interaction/user-approval`）负责定义词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP（Agent Client Protocol）桥、宿主适配器、测试脚本），而每会话的策略层可以在任何通道介入之前做出决定。消费方（`dsh-tools` 的 ask 路由和沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
 
 ### 部署如何使用它
 
@@ -95,7 +95,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - **单一注册提供方而非 waterfall 监听器**：否决。`registerProvider()` 接口迫使所有组合问题——允许列表预过滤、外部钩子决策者、脚本化测试应答、人类前面的策略门禁——都塞进一个提供方实现。waterfall 直接复用运行时已有的组合能力、缺失时默认拒绝行为和 HMR（热模块替换）资源释放机制；seam 的 JSDoc 以约定固定单决策槽语义，而非发明一个提供方注册表。
 - **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
-- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/ui/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
+- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
 - **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
 - **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
 - **现在就提供 `allow_always`**：否决。协议能表达它，但兑现它意味着设计授权存储、作用域标识和撤销（§ 延后）。展示 harness 无法兑现的选项只会制造注定失败的授权。
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
index 205ce40bb2..b2e1785796 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.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 .agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
-2026-07-12-subagent-persona-tool-filter-and-depth.md: c690f4701a54272205eedf719fbfe0863bac566c
-2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: e14214b16c413eaa05bcea7bcdf9bca996e8d616
+2026-07-12-subagent-persona-tool-filter-and-depth.md: 2c5eaf8829e01536a2de34cc190573ff35e4ab77
+2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: 355db26ecaf57137420798474561d6a7032757cb
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
index c690f4701a..2c5eaf8829 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
@@ -53,7 +53,7 @@ The depth limit bounds recursive delegation independently of tool visibility. A
 
 The effective parent depth is the greater of durable `SessionHeader.delegationDepth` and runtime `AgentOptions.subagentDepth`. An in-process child records its derived depth in the session header, and resume restores that header, so a restart cannot lower the recursion count.
 
-Every public entry validates the domain rather than relying on one model-facing configuration path. Negative values, fractions, negative zero, non-finite values, unsafe integers, malformed stored parent depth, and derived overflow all reject. A direct `SubagentStartRequest` may omit the cap to leave depth unbounded; loader-resolved `dsh-tool-subagent` configuration instead defaults to `3`, accepts a numeric override, and uses explicit `'provider-managed'` to omit the cap for an out-of-process provider whose deployment owns its recursion budget. Three is a small finite default that still permits a root plus three descendant generations: the [SDK helper's generated subagent entries](../../../../packages/sdk/helper/src/features/builtin/index.ts) and [JSON-RPC example](../../../../examples/jsonrpc-agent/cordis.yml) use that general policy, while the shipped interactive ACP, headless, and REPL examples pin one. A numeric tool cap fails at provider mount when the provider lacks `depthLimit`.
+Every public entry validates the domain rather than relying on one model-facing configuration path. Negative values, fractions, negative zero, non-finite values, unsafe integers, malformed stored parent depth, and derived overflow all reject. A direct `SubagentStartRequest` may omit the cap to leave depth unbounded; loader-resolved `dsh-tool-subagent` configuration instead defaults to `3`, accepts a numeric override, and uses explicit `'provider-managed'` to omit the cap for an out-of-process provider whose deployment owns its recursion budget. Three is a small finite default that still permits a root plus three descendant generations: the [SDK helper's generated subagent entries](../../../../packages/scaffold/helper/src/features/builtin/index.ts) and [JSON-RPC example](../../../../examples/jsonrpc-agent/cordis.yml) use that general policy, while the shipped interactive ACP, headless, and REPL examples pin one. A numeric tool cap fails at provider mount when the provider lacks `depthLimit`.
 
 A deployment can combine depth and filtering, but the numeric cap does not synthesize a filter. The delegation tool stays visible at the cap because authorization may depend on runtime state; every attempted start checks the calling agent's current durable and runtime depth, and a rejected start returns an errored tool result without publishing a child. A deployment may separately deny delegation tools in children when its visibility policy is static. Neither choice changes the provider's conversation-history behavior.
 
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
index e14214b16c..355db26eca 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
@@ -53,7 +53,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
 
 有效父级深度取持久 `SessionHeader.delegationDepth` 与运行时 `AgentOptions.subagentDepth` 中的较大值。进程内子 agent 把推导出的深度记录在会话 header 中，恢复时会重新载入该 header，因此重启无法降低递归计数。
 
-每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[SDK 辅助函数生成的 subagent 条目](../../../../packages/sdk/helper/src/features/builtin/index.ts)和 [JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而已交付的交互式 ACP、headless 和 REPL 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
+每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[SDK 辅助函数生成的 subagent 条目](../../../../packages/scaffold/helper/src/features/builtin/index.ts)和 [JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而已交付的交互式 ACP、headless 和 REPL 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
 
 部署可以组合深度与过滤，但数值上限不会合成过滤器。委派工具在上限处仍然可见，因为授权可能依赖运行时状态；每次尝试启动都会检查调用方 agent 当前的持久与运行时深度，被拒绝的启动返回错误工具结果，且不发布子 agent。可见性策略固定的部署可以另外在子 agent 中 deny 委派工具。两种选择都不改变提供方的对话历史行为。
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 673e4869af..a54f2e9496 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: 36a567204ee1082d48126369ee0b7277c9f24ca8
-2026-07-16-harness-level-loop.zh.md: cb8d29b4c77848613a6718ea3a343b0ee3294ea4
+2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
+2026-07-16-harness-level-loop.zh.md: 0ec2dc2294c1adf8b7f6f810bfaffa7e08c19ed2
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index 36a567204e..f37bea0842 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -38,7 +38,7 @@ Time-based `/loop` or scheduled execution is a third policy and is not implement
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`, domain service | Owns `GoalId`, compare-and-set `GoalRef`, `GoalSnapshot`, four-state `GoalPhase`, structured `GoalBlockReason`, process-local `GoalActivation`, replay folding, and `get`, `create`, `edit`, `pause`, `resume`, `complete`, `block`, `clear`, and `disarm` verbs. |
 | `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; authenticates live turn provenance and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`, continuation policy | Reserves, fences, admits, attributes, settles, cancels, and quiescently drains same-session goal rounds without importing the concrete loop. |
-| `@deepseek-ai/dsh-commands` | `packages/ui/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
+| `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`, human-command producer | Registers `/goal` status, creation, edit, pause, resume, and clear over the goal domain for TUI. |
 | `@deepseek-ai/dsh-tool-ralph` | `packages/workflow/tool-ralph/`, fixed workflow consumer | Registers `ralph({ objective, maxRounds? })`, validates the fresh structured provider and bounded `RalphRoundReport`, and returns `complete`, `blocked`, or `budget-limited`. |
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index cb8d29b4c7..0ec2dc2294 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -38,7 +38,7 @@ Status: implemented
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`，领域服务 | 拥有 `GoalId`、比较并交换 `GoalRef`、`GoalSnapshot`、四状态 `GoalPhase`、结构化 `GoalBlockReason`、进程本地 `GoalActivation`、重放折叠，以及 `get`、`create`、`edit`、`pause`、`resume`、`complete`、`block`、`clear` 与 `disarm` 动词。 |
 | `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`，面向模型消费方 | 注册互斥的 `get_goal`、`create_goal` 与 `update_goal`；认证实时 Turn 来源，并把自治 Round 权限收窄到带机器可路由原因代码的完成或阻塞报告。 |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`，续行策略 | 在不导入具体 loop 的情况下，预留、设围栏、接纳、归属、结算、取消并排空同会话 Goal Round，直至完全停稳。 |
-| `@deepseek-ai/dsh-commands` | `packages/ui/commands/`，UI 注册表 | 拥有面向人类专用命令的 `CommandDefinition`、发现、作用域注册、直接分发、`CommandResult` 与请求取消。 |
+| `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`，UI 注册表 | 拥有面向人类专用命令的 `CommandDefinition`、发现、作用域注册、直接分发、`CommandResult` 与请求取消。 |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`，人类命令生产方 | 为 TUI 注册构建在目标领域之上的 `/goal` 状态、创建、编辑、暂停、恢复与清除。 |
 | `@deepseek-ai/dsh-tool-ralph` | `packages/workflow/tool-ralph/`，固定工作流消费方 | 注册 `ralph({ objective, maxRounds? })`，验证全新结构化 provider 与有界 `RalphRoundReport`，并返回 `complete`、`blocked` 或 `budget-limited`。 |
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
index c3bbbe1d22..e58d618cf3 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.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 .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
-2026-07-19-plugin-command-registration.md: 5233ce511dc9798733513ccbf6824f3e1b68d2e6
-2026-07-19-plugin-command-registration.zh.md: 7f41b9d2d00373901b51e3338fa51e1cadf886a9
+2026-07-19-plugin-command-registration.md: c8f0f2772a41948e9eb257a16f40194518c568f9
+2026-07-19-plugin-command-registration.zh.md: 94853393f5f71b29cfbd8da5443b3d73ded20e92
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
index 5233ce511d..c8f0f2772a 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
@@ -12,7 +12,7 @@ A shared mechanism must remain a UI concern rather than a model tool or agent-lo
 
 ## Decision
 
-`@deepseek-ai/dsh-commands` in `packages/ui/commands/` is the product command registry. The TUI app bundle mounts it beside its consuming front door; the [automation-only ACP app](../simplification/2026-07-23-acp-automation-only-protocol.md) and the executor-less, UI-less agent spine omit it. TUI injects the service, while command producers depend only on the registry and any domain they operate.
+`@deepseek-ai/dsh-commands` in `packages/interaction/commands/` is the product command registry. The TUI app bundle mounts it beside its consuming front door; the [automation-only ACP app](../simplification/2026-07-23-acp-automation-only-protocol.md) and the executor-less, UI-less agent spine omit it. TUI injects the service, while command producers depend only on the registry and any domain they operate.
 
 ### Registry contract
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
index 7f41b9d2d0..94853393f5 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
@@ -12,7 +12,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派
 
 ## 决策
 
-位于 `packages/ui/commands/` 的 `@deepseek-ai/dsh-commands` 是产品命令注册表。TUI 应用 bundle（组合包）把它挂载在消费该服务的入口旁；[仅面向自动化的 ACP（Agent Client Protocol）应用](../simplification/2026-07-23-acp-automation-only-protocol.md)和无执行器、无 UI 的智能体 spine（主干）都省略该服务。TUI 注入该服务，命令生产者只依赖注册表及其操作的领域。
+位于 `packages/interaction/commands/` 的 `@deepseek-ai/dsh-commands` 是产品命令注册表。TUI 应用 bundle（组合包）把它挂载在消费该服务的入口旁；[仅面向自动化的 ACP（Agent Client Protocol）应用](../simplification/2026-07-23-acp-automation-only-protocol.md)和无执行器、无 UI 的智能体 spine（主干）都省略该服务。TUI 注入该服务，命令生产者只依赖注册表及其操作的领域。
 
 ### 注册表契约
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index ee99911ee8..0cf926921b 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: 2a8ae4b235823b4493d2f082d37b85806f45b662
-2026-07-20-dsh-cli-personal-config.zh.md: d8ff6c4fcc5da8f1db6f030e990118e30ae6fe41
+2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
+2026-07-20-dsh-cli-personal-config.zh.md: b33a7fa321ca04f41e47386544ffc0f268a8b1b6
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index 2a8ae4b235..c00432ba2b 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -48,4 +48,4 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 
 ## Testing
 
-`packages/ui/app-boot/tests/user-patches.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `apps/cli/tests/built-bin.e2e.ts` boots the real dsh bin over a profile and exercises the live patch layer end to end. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
+`packages/boot/app-boot/tests/user-patches.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `apps/cli/tests/built-bin.e2e.ts` boots the real dsh bin over a profile and exercises the live patch layer end to end. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index d8ff6c4fcc..b33a7fa321 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -48,4 +48,4 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 ## Testing
 
-`packages/ui/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
+`packages/boot/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index a7d065d42d..1d93b7f440 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.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 .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
-2026-07-21-continuable-background-subagents.md: 6bbbfb25fb24eba95de888c9d23c79e24fc8535b
-2026-07-21-continuable-background-subagents.zh.md: e23fbe67cc2d16a2c01a1b7ed4884008f8932dd4
+2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
+2026-07-21-continuable-background-subagents.zh.md: 799e1914bdeb571dc697652081be6b0170768655
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
index 6bbbfb25fb..e37abdd798 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
@@ -112,7 +112,7 @@ Task records and active-run associations are process-local. Persistence makes th
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` pins the continuable durability boundary: an absent or detached flush listener and a permanent listener failure reject with `DURABILITY_FAILED`, a transient loop-checkpoint failure can succeed on the final confirmation, cancellation owns either final-checkpoint outcome, resume also confirms durability, and foreground runs remain best-effort. `packages/subagent/subagent/tests/continuation.spec.ts` drives the real stack (agent loop, JSONL persistence, spawn/fork providers, Task service, and `ctx.subagents`) keylessly: initial and resumed activations create fresh Tasks and dispose their runs before terminal; the descriptor event is pre-turn, model-hidden, versioned, durable under the service-allocated child id, and survives blocked or throwing initial prompt admission; cancellation, steering, cold follow-up, authorization, ownership conflicts, and resume races retain the contracts described above.
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` pins the `send_message` schema, coordinator attribution, both route renderings, the not-delivered failure, the no-agent rejection, and HMR disposal.
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` covers the configured background route: continuable mode requires a resumable provider and returns both ids without requiring `send_message`, while one-shot mode keeps the plain Task acknowledgement even when the provider can resume.
-- `packages/sdk/helper/tests/project.spec.ts` pins the Task service and model-facing Task controls in generated spawn and fork compositions.
+- `packages/scaffold/helper/tests/project.spec.ts` pins the Task service and model-facing Task controls in generated spawn and fork compositions.
 - The keyless ACP snapshot scenario `subagent-continuable` (examples/acp-agent) pins the model-visible transcript: the two-id acknowledgement, a final durability-confirmation failure rendered through `task_output` without unconfirmed child output, and a `send_message` follow-up whose started Task fails with the id unavailable.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index e23fbe67cc..799e1914bd 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -112,7 +112,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述契约。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
-- `packages/sdk/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
+- `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
 - 无密钥 ACP 快照场景 `subagent-continuable`（examples/acp-agent）固定模型可见的 transcript：双 id 确认消息、最终持久性确认失败（该失败通过 `task_output` 呈现，且不包含未经确认的 child 输出），以及一次 `send_message` 后续操作——其已启动的 Task 会带着「id 不可用」失败。
 
 ## 影响
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index 6018cb1305..38dc165e7f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.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 .agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: 96ffd772810a7908ff452967aa0be0e540bc2d8c
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 74ae4b81807d1267dc19f30d2bb51e50a775c4be
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: c5c6c4eac053e9a3adfa2a2a441ac492ba3391ac
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 643ec36134a1ebe940da5de5b373fa0c25afcd42
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
index 96ffd77281..c5c6c4eac0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
@@ -12,8 +12,8 @@ The stdio JSON-RPC serving surface (`@deepseek-ai/dsh-jsonrpc`, the [single-exe
 
 Three packages, layered exactly like the existing Python stack, plus one seam registration:
 
-- **`@deepseek-ai/dsh-sdk-protocol`** (`packages/sdk/sdk-protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
-- **`@deepseek-ai/dsh-sdk-client`** (`packages/sdk/sdk-client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
+- **`@deepseek-ai/dsh-sdk-protocol`** (`packages/scaffold/protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
+- **`@deepseek-ai/dsh-sdk-client`** (`packages/scaffold/client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
 - **`@deepseek-ai/dsh-subagent-dsh-sdk`** (`packages/subagent/subagent-dsh-sdk/`) — the second out-of-process `SubagentProvider`, structured as `subagent-acp`'s sibling: same all-false capabilities and `inheritsParentContext: false`, same publish-after-handshake ownership transaction, same result-never-rejects flattening through an `onError` sink, same parent-namespace run id. The child answer is read from streamed `session.event`s — the last complete `assistant/message`, else accumulated `text-delta` chunks, so partial answers survive cancellation. Stop reasons map from the child's structured `TurnEndReason` (`completed`/`max-tokens`/`aborted` pass through; everything else, including a settled-without-turn child, is `error`). Its `provider`/`model` config feeds the child's `initialize`; `env` is where deployments pass the child's own key and `DSH_CORDIS_CONFIG`.
 - **The subagent seam grows `out-of-process.ts`**: the provider-side vocabulary both out-of-process backends share — `NO_START_CAPABILITIES`, timing-bound validation, child cwd resolution (config override, else the delegating parent session's workspace), the never-reject `settleRunResult`, and the `subprocessRunHandle` publication. Process mechanics (spawn, env scrub, tree-scoped teardown) live in the `dsh-subprocess` seam; `subagent-acp` spawns through `ctx.subprocess`, while this backend spawns through the SDK client (the subprocess README's documented exception for SDK-managed transports) and applies the seam's `scrubbedParentEnv()` itself.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index 74ae4b8180..643ec36134 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -12,8 +12,8 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 三个包，分层与既有 Python 栈完全一致，外加一个 seam 注册：
 
-- **`@deepseek-ai/dsh-sdk-protocol`**（`packages/sdk/sdk-protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
-- **`@deepseek-ai/dsh-sdk-client`**（`packages/sdk/sdk-client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
+- **`@deepseek-ai/dsh-sdk-protocol`**（`packages/scaffold/protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
+- **`@deepseek-ai/dsh-sdk-client`**（`packages/scaffold/client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
 - **`@deepseek-ai/dsh-subagent-dsh-sdk`**（`packages/subagent/subagent-dsh-sdk/`）—— 第二个进程外 `SubagentProvider`，采用与 `subagent-acp` 对等的结构：同样的全 false 能力与 `inheritsParentContext: false`，同样的握手后发布所有权事务，同样通过 `onError` sink 将结果归一为绝不拒绝，同样的父命名空间 run id。子答案从流式 `session.event` 读取——最后一条完整 `assistant/message`，否则累积的 `text-delta` 块，部分答案在取消时得以保留。停止原因由子进程的结构化 `TurnEndReason` 映射（`completed`/`max-tokens`/`aborted` 直通；其余一切、包括未运行任何轮次便已结束的子进程，都是 `error`）。其 `provider`/`model` 配置喂给子进程的 `initialize`；`env` 是部署传入子进程自有密钥与 `DSH_CORDIS_CONFIG` 的地方。
 - **subagent seam 新增 `out-of-process.ts`**：两个进程外后端共享的 provider 侧词汇——`NO_START_CAPABILITIES`、时限校验、子进程 cwd 解析（配置覆盖、否则发起委托的父会话工作区）、绝不拒绝的 `settleRunResult`、以及 `subprocessRunHandle` 发布。进程机制（spawn、环境清理、进程树清理）属于 `dsh-subprocess` seam；`subagent-acp` 经 `ctx.subprocess` spawn 子进程，本后端则经 SDK 客户端 spawn 子进程（subprocess README 记载的 SDK 托管传输例外）并自行应用该 seam 的 `scrubbedParentEnv()`。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index 7adc61691c..0fe388a3dc 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 8226325d4cd4047c3a9c41eb9427082c59753dd5
-2026-07-27-session-projection-and-command-log.zh.md: b55704f28799008b5e2323d846696e4768fcd6d6
+2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
+2026-07-27-session-projection-and-command-log.zh.md: 89877d3aabcd074863f912b334c927268014e4d8
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 8226325d4c..2fc463ab6e 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -123,7 +123,7 @@ Two log-only (non-surface, model-invisible) events, mirroring the `tool/call`/`t
 'command/done': { commandId: string; kind: 'success' | 'error'; text?: string }
 ```
 
-The host command executor (`packages/ui/commands`) appends `command/run` before invoking the handler and `command/done` at settlement — direct standalone appends on the receiving agent's session, in the same shape as every other plugin-owned log-only event after the [synthetic-turn removal](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md): no turn wraps them (turns describe model-loop executions only), persistence drains them at ordinary checkpoints, and the commands package's own invariant companion enforces the run/done pairing. The payload is structured — `name` and, by default, `args` are the parser's own split (`parseCommand`'s name and rawInput), so a consumer (a projection unit folding its own command records, a rich command card) never re-parses a line. A definition sets `recordInput: false` when its authoritative domain event owns the payload; `command/run` then omits `args` rather than duplicating it. `text` is the handler's verbatim outcome — factual data of the same nature as `tool/result.content`, not presentation (how it is laid out remains client-computed at render time, satisfying the "presentation never enters the log" red line). Domains that want the model to know the outcome keep doing what they do today (plan's narration, goal's inject) — that is a domain decision, unchanged.
+The host command executor (`packages/interaction/commands`) appends `command/run` before invoking the handler and `command/done` at settlement — direct standalone appends on the receiving agent's session, in the same shape as every other plugin-owned log-only event after the [synthetic-turn removal](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md): no turn wraps them (turns describe model-loop executions only), persistence drains them at ordinary checkpoints, and the commands package's own invariant companion enforces the run/done pairing. The payload is structured — `name` and, by default, `args` are the parser's own split (`parseCommand`'s name and rawInput), so a consumer (a projection unit folding its own command records, a rich command card) never re-parses a line. A definition sets `recordInput: false` when its authoritative domain event owns the payload; `command/run` then omits `args` rather than duplicating it. `text` is the handler's verbatim outcome — factual data of the same nature as `tool/result.content`, not presentation (how it is laid out remains client-computed at render time, satisfying the "presentation never enters the log" red line). Domains that want the model to know the outcome keep doing what they do today (plan's narration, goal's inject) — that is a domain decision, unchanged.
 
 Because committed events broadcast on the mux stream, refresh persistence, multi-tab sync, and fork/resume recovery all come for free. The `command.execute` RPC degrades to admission — `{ matched, commandId? }`: whether the line resolved, and the minted pairing id when it did, so the issuing client can correlate its request with the flow node the lifecycle events produce. The one-shot notice channel (`runDetached` → `noticeFor`) is retired.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index b55704f287..89877d3aab 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -123,7 +123,7 @@ type UseProjection = {
 'command/done': { commandId: string; kind: 'success' | 'error'; text?: string }
 ```
 
-host 侧命令执行器（`packages/ui/commands`）在调用处理器前追加 `command/run`，在结算时追加 `command/done`——在接收 agent 的会话上直接独立追加，与[合成轮次移除](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)之后所有插件自有 log-only 事件同一形状：没有轮次包裹它们（轮次只描述模型循环执行），持久化在常规检查点排空它们，run/done 配对由 commands 包自己的 invariant 伴生插件把守。载荷是结构化的——`name` 以及默认携带的 `args` 来自解析器自己的切分（`parseCommand` 的 name 与 rawInput），因此消费方（折叠自己命令记录的投影单元、富命令卡片）永远无需重新解析行文本。当载荷由权威领域事件持有时，命令定义会设置 `recordInput: false`；此时 `command/run` 省略 `args`，而不是重复该载荷。`text` 是处理器的原样结果——与 `tool/result.content` 同一性质的事实数据，不是呈现（版式如何编排仍由客户端在渲染时计算，满足「呈现永不入日志」这条红线）。想让模型知道结果的领域继续做它们今天在做的事（plan 的旁白、goal 的注入）——那是领域自己的决定，保持不变。
+host 侧命令执行器（`packages/interaction/commands`）在调用处理器前追加 `command/run`，在结算时追加 `command/done`——在接收 agent 的会话上直接独立追加，与[合成轮次移除](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)之后所有插件自有 log-only 事件同一形状：没有轮次包裹它们（轮次只描述模型循环执行），持久化在常规检查点排空它们，run/done 配对由 commands 包自己的 invariant 伴生插件把守。载荷是结构化的——`name` 以及默认携带的 `args` 来自解析器自己的切分（`parseCommand` 的 name 与 rawInput），因此消费方（折叠自己命令记录的投影单元、富命令卡片）永远无需重新解析行文本。当载荷由权威领域事件持有时，命令定义会设置 `recordInput: false`；此时 `command/run` 省略 `args`，而不是重复该载荷。`text` 是处理器的原样结果——与 `tool/result.content` 同一性质的事实数据，不是呈现（版式如何编排仍由客户端在渲染时计算，满足「呈现永不入日志」这条红线）。想让模型知道结果的领域继续做它们今天在做的事（plan 的旁白、goal 的注入）——那是领域自己的决定，保持不变。
 
 由于已提交事件会在 mux 流上广播，刷新后仍在、多标签页同步、fork/恢复后可还原这三件事随之全部自动获得。`command.execute` RPC 退化为准入判定——`{ matched, commandId? }`：该行是否匹配命中，以及命中时新铸的配对 id，发起命令的客户端据此把自己的请求与生命周期事件产出的 flow 节点关联起来。一次性通知通道（`runDetached` → `noticeFor`）就此下线。
 
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
index cdebeeac5c..71d6fa82b5 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.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 .agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
-2026-07-19-make-jsonrpc-directional.md: 910b4988aca34dec499b2e34cb2a42042c81b0cb
-2026-07-19-make-jsonrpc-directional.zh.md: 9810cf758faa078583955ba541e2b2fe9ad9c855
+2026-07-19-make-jsonrpc-directional.md: 945d58a0c989dac2beeb129bfd545fe5674c63cd
+2026-07-19-make-jsonrpc-directional.zh.md: 181aab8cd2f2473f0b2694df1dff072fd805e69d
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
index 910b4988ac..945d58a0c9 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
@@ -20,11 +20,11 @@ Return the settled outcome directly from `session/prompt` as `{ status, reason }
 
 ## Implementation plan
 
-1. In `packages/ui/jsonrpc/src/server.ts`, replace `SessionPromptResult.accepted` with `status: 'ok' | 'error' | 'aborted'` and the captured `TurnEndReason`. `HarnessSdkServer.prompt()` will return `completed` as `ok`, `aborted` as `aborted`, and every other current or merge-extensible reason as `error`; reaching idle without a `turn/end` remains an invariant error. Remove only `session.finished`, leaving `session.event`, `subagent.started`, and `subagent.finished` unchanged.
-2. In `packages/sdk/sdk-protocol/src/transport.ts`, narrow the shared class to the directions with consumers — inbound requests/outbound responses (the server) and outbound requests/inbound responses plus inbound notifications (the TypeScript SDK client) — removing only server-originated `request()` use and client-originated notification dispatch, or split the class into a server-side and client-side transport. Request result, method-not-found, and handler-error responses retain their current behavior and remain ordered after notifications emitted by the awaited handler.
+1. In `packages/scaffold/server/src/server.ts`, replace `SessionPromptResult.accepted` with `status: 'ok' | 'error' | 'aborted'` and the captured `TurnEndReason`. `HarnessSdkServer.prompt()` will return `completed` as `ok`, `aborted` as `aborted`, and every other current or merge-extensible reason as `error`; reaching idle without a `turn/end` remains an invariant error. Remove only `session.finished`, leaving `session.event`, `subagent.started`, and `subagent.finished` unchanged.
+2. In `packages/scaffold/protocol/src/transport.ts`, narrow the shared class to the directions with consumers — inbound requests/outbound responses (the server) and outbound requests/inbound responses plus inbound notifications (the TypeScript SDK client) — removing only server-originated `request()` use and client-originated notification dispatch, or split the class into a server-side and client-side transport. Request result, method-not-found, and handler-error responses retain their current behavior and remain ordered after notifications emitted by the awaited handler.
 3. In `python/sdk/src/deepseek_harness/client.py`, `models.py`, and `__init__.py`, remove `IncomingRequest`, `_requests`, `notify()`, `next_request()`, `respond()`, and `respond_error()`. Add a public validated `SessionPromptResponse` carrying status and reason, return it from `session_prompt()`, and keep an explicit reader guard that ignores unexpected server-request frames instead of allowing them to match a response waiter.
 4. In `python/sdk/src/deepseek_harness/api.py`, build `TurnResult.status` and a new `TurnResult.reason` from `SessionPromptResponse`, then delete the `session.finished` branch and second completion loop. Keep the subscription open during the request and preserve `_request_raw()`'s final notification drain so the last `turn/end` event and any subagent notification written before the response are collected before `Session.run()` reconstructs the final assistant message.
-5. Replace the symmetric transport-pair cases in `packages/sdk/sdk-protocol/tests/transport.spec.ts` with per-direction coverage, and update `server.spec.ts`, `plugin-apply.spec.ts`, and `built-scope-carrier.e2e.ts` for direct outcomes, ordering, overlap, shutdown, and the narrowed fake; update the TypeScript SDK client (`packages/sdk/sdk-client`) and its suites for response-based settlement. Update `python/sdk/tests/test_client.py` for response-based settlement, unexpected-request-frame handling, callback and concurrency behavior, and the removed public helpers. Update the JSON-RPC and bilingual Python SDK READMEs, export JSDoc and declarations, `scripts/smoke-python-runtime.py`, and the Python single-executable snapshot.
+5. Replace the symmetric transport-pair cases in `packages/scaffold/protocol/tests/transport.spec.ts` with per-direction coverage, and update `server.spec.ts`, `plugin-apply.spec.ts`, and `built-scope-carrier.e2e.ts` for direct outcomes, ordering, overlap, shutdown, and the narrowed fake; update the TypeScript SDK client (`packages/scaffold/client`) and its suites for response-based settlement. Update `python/sdk/tests/test_client.py` for response-based settlement, unexpected-request-frame handling, callback and concurrency behavior, and the removed public helpers. Update the JSON-RPC and bilingual Python SDK READMEs, export JSDoc and declarations, `scripts/smoke-python-runtime.py`, and the Python single-executable snapshot.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
index 9810cf758f..181aab8cd2 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
@@ -20,11 +20,11 @@ JSON-RPC 桥接层把两个端点都建模为对称的对等端，但实际协
 
 ## 实施计划
 
-1. 在 `packages/ui/jsonrpc/src/server.ts` 中，用 `status: 'ok' | 'error' | 'aborted'` 和捕获的 `TurnEndReason` 替换 `SessionPromptResult.accepted`。`HarnessSdkServer.prompt()` 把 `completed` 映射为 `ok`，把 `aborted` 映射为 `aborted`，把其他当前已有或可通过声明合并扩展的原因映射为 `error`；进入空闲状态却没有 `turn/end` 仍视为不变量错误。只删除 `session.finished`，保持 `session.event`、`subagent.started` 和 `subagent.finished` 不变。
-2. 在 `packages/sdk/sdk-protocol/src/transport.ts` 中，把共享类收窄到有消费者的方向——入站请求/出站响应（服务端）与出站请求/入站响应及入站通知（TypeScript SDK 客户端）——只删除服务端发起的 `request()` 用法与客户端发起的通知分发，或把该类拆分为服务端与客户端两个传输。请求结果、方法不存在与处理器错误响应保持原有行为，并继续排在被等待处理器发出的通知之后。
+1. 在 `packages/scaffold/server/src/server.ts` 中，用 `status: 'ok' | 'error' | 'aborted'` 和捕获的 `TurnEndReason` 替换 `SessionPromptResult.accepted`。`HarnessSdkServer.prompt()` 把 `completed` 映射为 `ok`，把 `aborted` 映射为 `aborted`，把其他当前已有或可通过声明合并扩展的原因映射为 `error`；进入空闲状态却没有 `turn/end` 仍视为不变量错误。只删除 `session.finished`，保持 `session.event`、`subagent.started` 和 `subagent.finished` 不变。
+2. 在 `packages/scaffold/protocol/src/transport.ts` 中，把共享类收窄到有消费者的方向——入站请求/出站响应（服务端）与出站请求/入站响应及入站通知（TypeScript SDK 客户端）——只删除服务端发起的 `request()` 用法与客户端发起的通知分发，或把该类拆分为服务端与客户端两个传输。请求结果、方法不存在与处理器错误响应保持原有行为，并继续排在被等待处理器发出的通知之后。
 3. 在 `python/sdk/src/deepseek_harness/client.py`、`models.py` 和 `__init__.py` 中，删除 `IncomingRequest`、`_requests`、`notify()`、`next_request()`、`respond()` 和 `respond_error()`。新增公开且经过校验的 `SessionPromptResponse` 来携带状态与原因，由 `session_prompt()` 返回该对象，并保留明确的读取保护：忽略意外的服务端请求帧，避免它们命中响应等待器。
 4. 在 `python/sdk/src/deepseek_harness/api.py` 中，根据 `SessionPromptResponse` 构造 `TurnResult.status` 和新增的 `TurnResult.reason`，再删除 `session.finished` 分支与第二个完成循环。请求期间保持订阅打开，并保留 `_request_raw()` 最后的通知排空步骤，确保写在响应前的最后一条 `turn/end` 事件与任何 subagent 通知，都会在 `Session.run()` 重建最终助手消息之前被收集。
-5. 用按方向的覆盖替换 `packages/sdk/sdk-protocol/tests/transport.spec.ts` 中的对称传输对用例，并更新 `server.spec.ts`、`plugin-apply.spec.ts` 和 `built-scope-carrier.e2e.ts`，覆盖直接结果、顺序、重叠、关闭和收窄后的伪实现；同步更新 TypeScript SDK 客户端（`packages/sdk/sdk-client`）及其套件以采用基于响应的结束流程。更新 `python/sdk/tests/test_client.py`，覆盖基于响应的结束流程、意外请求帧处理、回调与并发行为，以及已删除的公开辅助方法。同步更新 JSON-RPC README、双语 Python SDK README、导出 JSDoc 与声明、`scripts/smoke-python-runtime.py` 和 Python 单可执行文件快照。
+5. 用按方向的覆盖替换 `packages/scaffold/protocol/tests/transport.spec.ts` 中的对称传输对用例，并更新 `server.spec.ts`、`plugin-apply.spec.ts` 和 `built-scope-carrier.e2e.ts`，覆盖直接结果、顺序、重叠、关闭和收窄后的伪实现；同步更新 TypeScript SDK 客户端（`packages/scaffold/client`）及其套件以采用基于响应的结束流程。更新 `python/sdk/tests/test_client.py`，覆盖基于响应的结束流程、意外请求帧处理、回调与并发行为，以及已删除的公开辅助方法。同步更新 JSON-RPC README、双语 Python SDK README、导出 JSDoc 与声明、`scripts/smoke-python-runtime.py` 和 Python 单可执行文件快照。
 
 ## 备选方案
 
diff --git a/AGENTS.md b/AGENTS.md
index 7727539bd9..7c9b795ddc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,7 +37,9 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   settings/    user-settings seam + file-backed provider
   credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
-  ui/          JSON-RPC bridge; boot, approval, interaction plugins
+  interaction/ approval/interaction seams, permission, commands, ask-user tool
+  boot/        shared app-bin boot glue
+  scaffold/    project tooling: helper, launcher, initializer, SDK wire protocol + ends
   examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure
   util/        zero-dependency utilities
diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json
index 36c4bad6dd..d830e8fba6 100644
--- a/apps/cli/tsconfig.json
+++ b/apps/cli/tsconfig.json
@@ -18,7 +18,7 @@
       "path": "../../vendor/include"
     },
     {
-      "path": "../../packages/ui/app-boot"
+      "path": "../../packages/boot/app-boot"
     },
     {
       "path": "../../packages/bundle/base"
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 4d10310333..76491a37fe 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: c14d68c47f6ed0786e8fc0b0650dbc67678250fb
-architecture.zh.md: df484762d29e170a5b1ba64f0637c5170c2c5ef4
+architecture.md: cee159452fc536c98a006cfa3ea92e9d21a1e77b
+architecture.zh.md: cf10e60a5d5e4fe3f39d72bef3d48fe7c2f3c105
diff --git a/docs/architecture.md b/docs/architecture.md
index c14d68c47f..cee159452f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -163,7 +163,7 @@ Exceptions combine LLM interface/consumer, filesystem policy, web registries, an
 
 ### Bundles And Apps
 
-`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own CLI, ACP automation, and JSON-RPC front doors ([README](../packages/examples/agent-spine-demo/README.md), [acp/](../packages/acp/README.md), [ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK defaults when config is absent ([Python SDK](../python/README.md)). Thin deployments use swappable backends and optional tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own CLI, ACP automation, and JSON-RPC front doors ([README](../packages/examples/agent-spine-demo/README.md), [acp/](../packages/acp/README.md), [interaction/](../packages/interaction/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK defaults when config is absent ([Python SDK](../python/README.md)). Thin deployments use swappable backends and optional tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
 
 ### Where New Behavior Goes
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index df484762d2..cf10e60a5d 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -163,7 +163,7 @@ idle inject:
 
 ### 组合包与应用
 
-`dsh-agent-spine-demo` 组合一套主干和可选目标。应用包负责 CLI（命令行界面）、ACP 自动化入口和 JSON-RPC 入口（[README](../packages/examples/agent-spine-demo/README.md)、[acp/](../packages/acp/README.md)、[ui/](../packages/ui/README.md)）。`dsh-jsonrpc-agent` 启动外部 `cordis.yml`；Python SDK 在配置缺失时提供默认项（[Python SDK](../python/README.md)）。轻量部署使用可替换后端和可选工具（[examples/](../examples/AGENTS.md)、[可运行接线](cookbook/extension-cookbook.md#runnable-wirings)、[图谱](graph-atlas.md)）。
+`dsh-agent-spine-demo` 组合一套主干和可选目标。应用包负责 CLI（命令行界面）、ACP 自动化入口和 JSON-RPC 入口（[README](../packages/examples/agent-spine-demo/README.md)、[acp/](../packages/acp/README.md)、[interaction/](../packages/interaction/README.md)）。`dsh-jsonrpc-agent` 启动外部 `cordis.yml`；Python SDK 在配置缺失时提供默认项（[Python SDK](../python/README.md)）。轻量部署使用可替换后端和可选工具（[examples/](../examples/AGENTS.md)、[可运行接线](cookbook/extension-cookbook.md#runnable-wirings)、[图谱](graph-atlas.md)）。
 
 ### 新行为的归属位置
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 60a19999f3..c191f6a659 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -389,10 +389,10 @@ flowchart LR
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/interaction/user-interaction) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
-| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
+| `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
@@ -407,7 +407,7 @@ flowchart LR
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
 | `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
-| `ctx.permission` | `core` | [`permission`](../packages/ui/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
+| `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
diff --git a/docs/core-data-structures/approval.i18n.yaml b/docs/core-data-structures/approval.i18n.yaml
index 0679cd47bd..975f631805 100644
--- a/docs/core-data-structures/approval.i18n.yaml
+++ b/docs/core-data-structures/approval.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 docs/core-data-structures/approval.md
-approval.md: f1889b25e2bbbcb157b0bced070b1f157a867504
-approval.zh.md: 48222991312f9ae97c9249f1232b261d2393d282
+approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069
+approval.zh.md: c19285572b667512427b71d4af214acbc2baf334
diff --git a/docs/core-data-structures/approval.md b/docs/core-data-structures/approval.md
index f1889b25e2..8f17f98101 100644
--- a/docs/core-data-structures/approval.md
+++ b/docs/core-data-structures/approval.md
@@ -2,9 +2,9 @@
 
 English | [中文](approval.zh.md)
 
-The user-approval seam of [dsh-user-approval](../../packages/ui/user-approval) answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the `ctx.approval` dispatch service, the `approval/request` answerer waterfall, the log-only audit pair, and the per-session `ask`/`never` policy. UI channels may provide human answerers; the [ACP automation bridge](../../packages/acp/acp) provides one-shot machine decisions for its own agents. Callers such as [dsh-tools](../../packages/core/tools) and [dsh-tool-bash](../../packages/bash/tool-bash) consume the closed outcome and fail closed unless it is `allowed-once`.
+The user-approval seam of [dsh-user-approval](../../packages/interaction/user-approval) answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the `ctx.approval` dispatch service, the `approval/request` answerer waterfall, the log-only audit pair, and the per-session `ask`/`never` policy. UI channels may provide human answerers; the [ACP automation bridge](../../packages/acp/acp) provides one-shot machine decisions for its own agents. Callers such as [dsh-tools](../../packages/core/tools) and [dsh-tool-bash](../../packages/bash/tool-bash) consume the closed outcome and fail closed unless it is `allowed-once`.
 
-Source: [`packages/ui/user-approval/src/index.ts`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts`](../../packages/interaction/user-approval/src/index.ts)
 
 ## Identity and outcome
 
diff --git a/docs/core-data-structures/approval.zh.md b/docs/core-data-structures/approval.zh.md
index 4822299131..c19285572b 100644
--- a/docs/core-data-structures/approval.zh.md
+++ b/docs/core-data-structures/approval.zh.md
@@ -2,9 +2,9 @@
 
 [English](approval.md) | 中文
 
-[dsh-user-approval](../../packages/ui/user-approval) 的用户审批 seam 回答一个问题：这个具体操作是否可以继续？它拥有共享的请求/结果词汇、`ctx.approval` 分发服务、`approval/request` 应答者 waterfall（瀑布式事件）、仅记录日志的审计事件对，以及按会话的 `ask`/`never` 策略。UI 通道可以提供人类应答者；[ACP（Agent Client Protocol）自动化桥接层](../../packages/acp/acp)为其拥有的 agent（智能体）提供一次性机器决策。调用方如 [dsh-tools](../../packages/core/tools) 和 [dsh-tool-bash](../../packages/bash/tool-bash) 消费闭合的结果，除非结果为 `allowed-once`，否则一律拒绝。
+[dsh-user-approval](../../packages/interaction/user-approval) 的用户审批 seam 回答一个问题：这个具体操作是否可以继续？它拥有共享的请求/结果词汇、`ctx.approval` 分发服务、`approval/request` 应答者 waterfall（瀑布式事件）、仅记录日志的审计事件对，以及按会话的 `ask`/`never` 策略。UI 通道可以提供人类应答者；[ACP（Agent Client Protocol）自动化桥接层](../../packages/acp/acp)为其拥有的 agent（智能体）提供一次性机器决策。调用方如 [dsh-tools](../../packages/core/tools) 和 [dsh-tool-bash](../../packages/bash/tool-bash) 消费闭合的结果，除非结果为 `allowed-once`，否则一律拒绝。
 
-源码：[`packages/ui/user-approval/src/index.ts`](../../packages/ui/user-approval/src/index.ts)
+源码：[`packages/interaction/user-approval/src/index.ts`](../../packages/interaction/user-approval/src/index.ts)
 
 ## 标识与结果
 
diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/core-data-structures/commands.i18n.yaml
index 532151ef70..18df873acc 100644
--- a/docs/core-data-structures/commands.i18n.yaml
+++ b/docs/core-data-structures/commands.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 docs/core-data-structures/commands.md
-commands.md: 1390f736ff582a997ee710cfd27fce4e7db3461f
-commands.zh.md: 53aec9bd138773df7fceb45e5d6c30b7205dd0d9
+commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c
+commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb
diff --git a/docs/core-data-structures/commands.md b/docs/core-data-structures/commands.md
index 1390f736ff..83ce9c2498 100644
--- a/docs/core-data-structures/commands.md
+++ b/docs/core-data-structures/commands.md
@@ -2,9 +2,9 @@
 
 English | [中文](commands.zh.md)
 
-The human-command seam of [`dsh-commands`](../../packages/ui/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/ui/commands/README.md) owns composition and limitations.
+The human-command seam of [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
 
-Source: [`packages/ui/commands/src/index.ts`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## Input metadata
 
diff --git a/docs/core-data-structures/commands.zh.md b/docs/core-data-structures/commands.zh.md
index 53aec9bd13..c486f48017 100644
--- a/docs/core-data-structures/commands.zh.md
+++ b/docs/core-data-structures/commands.zh.md
@@ -2,9 +2,9 @@
 
 [English](commands.md) | 中文
 
-[`dsh-commands`](../../packages/ui/commands) 的用户命令 seam。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/ui/commands/README.md) 负责组合方式与限制。
+[`dsh-commands`](../../packages/interaction/commands) 的用户命令 seam。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/interaction/commands/README.md) 负责组合方式与限制。
 
-来源：[`packages/ui/commands/src/index.ts`](../../packages/ui/commands/src/index.ts)
+来源：[`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## 输入元数据
 
diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml
index 5480052231..3768cfcf7b 100644
--- a/docs/core-data-structures/user-interaction.i18n.yaml
+++ b/docs/core-data-structures/user-interaction.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 docs/core-data-structures/user-interaction.md
-user-interaction.md: 73727cbb754f10633d3213f67f7c3c9fdb215500
-user-interaction.zh.md: b6e95af4026e58c63c713d87ee9a86b3712b311f
+user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014
+user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b
diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md
index 73727cbb75..ec22eb28e9 100644
--- a/docs/core-data-structures/user-interaction.md
+++ b/docs/core-data-structures/user-interaction.md
@@ -2,9 +2,9 @@
 
 English | [中文](user-interaction.zh.md)
 
-The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`; the host runtime relays requests to its connected client.
+The user-interaction seam of [dsh-user-interaction](../../packages/interaction/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`; the host runtime relays requests to its connected client.
 
-Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
+Source: [`packages/interaction/user-interaction/src/index.ts`](../../packages/interaction/user-interaction/src/index.ts)
 
 ## Question options
 
diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md
index b6e95af402..814f8911e4 100644
--- a/docs/core-data-structures/user-interaction.zh.md
+++ b/docs/core-data-structures/user-interaction.zh.md
@@ -2,9 +2,9 @@
 
 [English](user-interaction.md) | 中文
 
-[dsh-user-interaction](../../packages/ui/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给它连接的客户端。
+[dsh-user-interaction](../../packages/interaction/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给它连接的客户端。
 
-源码：[`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
+源码：[`packages/interaction/user-interaction/src/index.ts`](../../packages/interaction/user-interaction/src/index.ts)
 
 ## 问题选项
 
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 90970c8c57..0b7cdfdc76 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.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 docs/testing.md
-testing.md: fecf02fe887aac5c92c739523f10a0562eba6242
-testing.zh.md: a34f56fac72baa9916d5f96e83048ad54cf23d4a
+testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
+testing.zh.md: e9182495fbdbb1458c9ff5b30a9591f8b70f27c5
diff --git a/docs/testing.md b/docs/testing.md
index fecf02fe88..296dd76911 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -32,7 +32,7 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword
 
 - Product-visible plugins require a non-unit REAL-composition test. Hand-built `ctx.plugin(...)` suites are insufficient: boot test-only `cordis.yml` through Loader and app/process, mock only external/nondeterministic boundaries, and assert model-visible request/log, durable state, or user-visible output. Keep opt-ins out of shipped defaults.
 - A guard only guards if the regression actually fails it. For a plugin without `inject` (bundle/composition plugins), a Loader smoke stays green under a broken export shape — add an explicit `expect('default' in mod).toBe(false)` plus an `unwrapExports` round-trip assertion, and prove it: introduce the regression, watch red, revert.
-- "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` under plain `node`, exposing failures tsx masks (settle races, module resolution, swallowed load failures). The same applies to non-index runtime entries (the worker-thread sibling `lib/worker.cjs`) and singleton modules shared across bundles (`packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts`). Keep the built-artifact smokes green (`packages/ui/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
+- "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` under plain `node`, exposing failures tsx masks (settle races, module resolution, swallowed load failures). The same applies to non-index runtime entries (the worker-thread sibling `lib/worker.cjs`) and singleton modules shared across bundles (`packages/scaffold/server/tests/built-scope-carrier.e2e.ts`). Keep the built-artifact smokes green (`packages/examples/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
 
 ## Test resolution: source plane only
 
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index a34f56fac7..e9182495fb 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -32,7 +32,7 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - 产品可见的插件必须有一个非单元的真实组合测试。手动构建的 `ctx.plugin(...)` 套件不够：通过 Loader 和 app/process 启动仅用于测试的 `cordis.yml`，只 mock 外部/不确定边界，断言模型可见的请求/日志、持久状态或用户可见输出。不要把 opt-in 选项混入交付默认值。
 - 一个守卫只有在回归真的能让它失败时才有效。对于没有 `inject` 的插件（bundle/组合插件），Loader 冒烟测试在导出形状损坏时仍然绿着——需要添加显式的 `expect('default' in mod).toBe(false)` 加 `unwrapExports` 往返断言，并证明它有效：引入回归、观察变红、回退。
-- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/ui/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。
+- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/scaffold/server/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/examples/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。
 
 ## 测试解析：仅限源码
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index adb73f104d..0cb985d07d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -107,7 +107,7 @@ Ask the user a concise question when you need confirmation, a choice, or missing
 }
 ```
 
-Source: [`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts)
+Source: [`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)
 
 ask_user_question pauses the tool call until the active UI provider returns a human answer.
 
diff --git a/knip.json b/knip.json
index 0e82064200..63db33e51c 100644
--- a/knip.json
+++ b/knip.json
@@ -513,7 +513,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/ui/jsonrpc": {
+    "packages/scaffold/server": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -523,7 +523,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/ui/commands": {
+    "packages/interaction/commands": {
       "entry": [
         "tests/**/*.spec.ts"
       ],
@@ -537,7 +537,7 @@
         "src/**/*.ts"
       ]
     },
-    "packages/sdk/create-sdk": {
+    "packages/scaffold/create-sdk": {
       "entry": [
         "src/bin.ts",
         "tests/**/*.spec.ts",
@@ -549,7 +549,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/sdk/scripts": {
+    "packages/scaffold/scripts": {
       "entry": [
         "src/bin.ts",
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 44dd906b76..68da8ae611 100644
--- 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: 9f8b3f936af6392239218d5389c91c87d0f7d1f9
-README.zh.md: 2f4e86cb541a8a34762b36cac57f456de96cac5d
+README.md: 198caca8c8b8231ece4d7160c809ba7b881e775c
+README.zh.md: bf2bf437796d904d135b610ff2c7a2d4d21b0298
diff --git a/packages/README.md b/packages/README.md
index 9f8b3f936a..198caca8c8 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -45,9 +45,10 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
-| [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
+| [`scaffold/`](scaffold/README.md) | Create/launch/drive project tooling: helper, launcher, initializer, wire protocol with both ends, launcher telemetry | Product — stable surface |
 | [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable surface |
-| [`ui/`](ui/README.md) | JSON-RPC integration, approval/interaction seams, ask-user tool | Product — stable surface |
+| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable surface |
+| [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable surface |
 | [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable surface |
 | [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable surface |
 | [`experimental/`](experimental/README.md) | Prototypes and internal plugins | Unreleased |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 2f4e86cb54..bf2bf43779 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -45,9 +45,10 @@
 | [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` provider | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
-| [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
+| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定表面 |
 | [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
-| [`ui/`](ui/README.md) | JSON-RPC 集成、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
+| [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定表面 |
+| [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定表面 |
 | [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定表面 |
 | [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定表面 |
 | [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 |
diff --git a/packages/acp/acp/tsconfig.json b/packages/acp/acp/tsconfig.json
index 3109e0eea8..177b3cb3cd 100644
--- a/packages/acp/acp/tsconfig.json
+++ b/packages/acp/acp/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/agent"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/bash/tool-bash/tsconfig.json b/packages/bash/tool-bash/tsconfig.json
index b122ed58ca..93cbe93786 100644
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -39,7 +39,7 @@
       "path": "../../bash/bash-env"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
       "path": "../../sandbox/sandbox"
diff --git a/packages/sdk/README.i18n.yaml b/packages/boot/README.i18n.yaml
similarity index 57%
rename from packages/sdk/README.i18n.yaml
rename to packages/boot/README.i18n.yaml
index 738a0610ab..151e5e5c08 100644
--- a/packages/sdk/README.i18n.yaml
+++ b/packages/boot/README.i18n.yaml
@@ -1,6 +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/sdk/README.md
-README.md: 3f99d6d45ddc64ac068457b0d03e533d21451a5f
-README.zh.md: 003383c5f6238b37893927813959d52d96350c3e
+#   pnpm run verify-translation-pairing --write packages/boot/README.md
+README.md: 7727f4fbab62a930051fd3b92d04513ac9f5d218
+README.zh.md: aa9a56619ee55c3be8feb58881f77c460861b1ac
diff --git a/packages/boot/README.md b/packages/boot/README.md
new file mode 100644
index 0000000000..7727f4fbab
--- /dev/null
+++ b/packages/boot/README.md
@@ -0,0 +1,9 @@
+# boot/ — shared app-bin boot glue
+
+English | [中文](README.zh.md)
+
+The channel-neutral boot library the app bins share. A role-complete single-package group: it belongs to no channel and no assembly — `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
new file mode 100644
index 0000000000..aa9a56619e
--- /dev/null
+++ b/packages/boot/README.zh.md
@@ -0,0 +1,9 @@
+# boot/：共享的 app bin 启动粘合层
+
+[English](README.md) | 中文
+
+各 app bin 共享、与通道无关的启动库。一个角色完备的单包组：它不归属任何通道也不归属任何组装——`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器和 [`examples/`](../examples/README.md) 各演示 bin 都消费它。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
similarity index 81%
rename from packages/ui/app-boot/README.i18n.yaml
rename to packages/boot/app-boot/README.i18n.yaml
index 24f04a21c1..3ae6f5427c 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -1,6 +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/ui/app-boot/README.md
+#   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
 README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
diff --git a/packages/ui/app-boot/README.md b/packages/boot/app-boot/README.md
similarity index 100%
rename from packages/ui/app-boot/README.md
rename to packages/boot/app-boot/README.md
diff --git a/packages/ui/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
similarity index 100%
rename from packages/ui/app-boot/README.zh.md
rename to packages/boot/app-boot/README.zh.md
diff --git a/packages/ui/app-boot/package.json b/packages/boot/app-boot/package.json
similarity index 100%
rename from packages/ui/app-boot/package.json
rename to packages/boot/app-boot/package.json
diff --git a/packages/ui/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
similarity index 100%
rename from packages/ui/app-boot/src/index.ts
rename to packages/boot/app-boot/src/index.ts
diff --git a/packages/ui/app-boot/src/invariant.ts b/packages/boot/app-boot/src/invariant.ts
similarity index 100%
rename from packages/ui/app-boot/src/invariant.ts
rename to packages/boot/app-boot/src/invariant.ts
diff --git a/packages/ui/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
similarity index 100%
rename from packages/ui/app-boot/src/profile.ts
rename to packages/boot/app-boot/src/profile.ts
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/boot/app-boot/tests/app-boot.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/app-boot.spec.ts
rename to packages/boot/app-boot/tests/app-boot.spec.ts
diff --git a/packages/ui/app-boot/tests/config-dump.spec.ts b/packages/boot/app-boot/tests/config-dump.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/config-dump.spec.ts
rename to packages/boot/app-boot/tests/config-dump.spec.ts
diff --git a/packages/ui/app-boot/tests/config-reload.spec.ts b/packages/boot/app-boot/tests/config-reload.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/config-reload.spec.ts
rename to packages/boot/app-boot/tests/config-reload.spec.ts
diff --git a/packages/ui/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/hmr-config.spec.ts
rename to packages/boot/app-boot/tests/hmr-config.spec.ts
diff --git a/packages/ui/app-boot/tests/profile.spec.ts b/packages/boot/app-boot/tests/profile.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/profile.spec.ts
rename to packages/boot/app-boot/tests/profile.spec.ts
diff --git a/packages/ui/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/repository-cache.spec.ts
rename to packages/boot/app-boot/tests/repository-cache.spec.ts
diff --git a/packages/ui/app-boot/tests/user-patches.spec.ts b/packages/boot/app-boot/tests/user-patches.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/user-patches.spec.ts
rename to packages/boot/app-boot/tests/user-patches.spec.ts
diff --git a/packages/ui/app-boot/tsconfig.json b/packages/boot/app-boot/tsconfig.json
similarity index 100%
rename from packages/ui/app-boot/tsconfig.json
rename to packages/boot/app-boot/tsconfig.json
diff --git a/packages/ui/app-boot/tsdown.config.ts b/packages/boot/app-boot/tsdown.config.ts
similarity index 100%
rename from packages/ui/app-boot/tsdown.config.ts
rename to packages/boot/app-boot/tsdown.config.ts
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 27e50409cd..5199e0939e 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -1,6 +1,12 @@
 # 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:
+<<<<<<<< HEAD:packages/bundle/README.i18n.yaml
 #   pnpm run verify-translation-pairing --write packages/bundle/README.md
 README.md: 4759170435a80e85731446cef21d24fff2abed66
 README.zh.md: 1ef610a1b7b3c591c9a900e04f2d8096b0b086b9
+========
+#   pnpm run verify-translation-pairing --write packages/interaction/tui/README.md
+README.md: c81cac891403e5294c4456ce4d4048ecd74666ce
+README.zh.md: 01055619f4df460284564f0a1816de366d809e01
+>>>>>>>> a58746f4cc (refactor(packages): dissolve ui/ and rename sdk/ to scaffold/):packages/interaction/tui/README.i18n.yaml
diff --git a/packages/client/connection/tsconfig.json b/packages/client/connection/tsconfig.json
index 6ff7fbfb25..58c04d18bd 100644
--- a/packages/client/connection/tsconfig.json
+++ b/packages/client/connection/tsconfig.json
@@ -16,7 +16,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../util/brand"
@@ -28,10 +28,10 @@
       "path": "../../host/webserver"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
-      "path": "../../ui/user-interaction"
+      "path": "../../interaction/user-interaction"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 71cfb229a9..867b2f588c 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../host/apiproxy"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../compact/compact"
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 0505786841..89d0067caf 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -51,7 +51,7 @@
       "path": "../../support/invariants"
     },
     {
-      "path": "../../ui/permission"
+      "path": "../../interaction/permission"
     }
   ],
   "exclude": [
diff --git a/packages/client/ui-permission/tsconfig.json b/packages/client/ui-permission/tsconfig.json
index 32f84d6a2d..bfc71e2e3c 100644
--- a/packages/client/ui-permission/tsconfig.json
+++ b/packages/client/ui-permission/tsconfig.json
@@ -39,7 +39,7 @@
       "path": "../web-react"
     },
     {
-      "path": "../../ui/permission"
+      "path": "../../interaction/permission"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/client/ui-question/tsconfig.json b/packages/client/ui-question/tsconfig.json
index 6b5b0acc3a..1b920ce207 100644
--- a/packages/client/ui-question/tsconfig.json
+++ b/packages/client/ui-question/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../ui-slots"
     },
     {
-      "path": "../../ui/tool-ask-user"
+      "path": "../../interaction/tool-ask-user"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/compact/command-compact/tsconfig.json b/packages/compact/command-compact/tsconfig.json
index f99f2b98b4..c1040bf92a 100644
--- a/packages/compact/command-compact/tsconfig.json
+++ b/packages/compact/command-compact/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../compact"
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index 6463edbc33..1ab398842f 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: cd2404cda8d8702ca0400d3f23d9e1fe041495a1
-README.zh.md: ed6ccc630118dc1bd6d6ea761beefafadb4bd48f
+README.md: 5703540435b976cfc03987edca28e2b5cd24ae0d
+README.zh.md: 434b9bfa3d0d7f21fc262929ac72ff5ab15d5057
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index cd2404cda8..5703540435 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -68,7 +68,7 @@ Subclass `CompactService`, implement `compactIfNeeded`, `compactNow`, and `compa
 
 ## Recognizing a checkpoint outside the host program (`./checkpoint`)
 
-`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../ui/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there.
+`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there.
 
 ## Model Experience
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index ed6ccc6301..434b9bfa3d 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -68,7 +68,7 @@
 
 ## 在 host 程序之外识别检查点（`./checkpoint`）
 
-`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../ui/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。
+`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../interaction/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。
 
 ## 模型体验
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index c1bd91ce2b..e8157eed7e 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: 81cc57983d83fd19468017b217d4db9978f4e228
-README.zh.md: 9f875bd80a03d1d0f78625ee98eeaad9d118f871
+README.md: fd5cb85540e42e62de28f96bf59890da9561f51e
+README.zh.md: 5911b25b1d77710077063a643a29e500e4da8e95
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 81cc57983d..fd5cb85540 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -45,7 +45,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 - `ToolExecution` — the readonly pipeline view: immutable `{ token, callId, name, arguments, signal, agent?, parent? }`; the registry separately retains and re-fuses the original caller signal. `ToolDispatchExecution` is the `tools/execute`-only view whose required signal is mutable, so a wrapper may replace and restore it but cannot delete it. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
 - `ToolRunContext` — the execution passed to a tool body, extending `ToolExecution` with `deferContext(context)`. It defers one context until the tool's final result reaches the loop — typically a nested-dispatch context ferried by a composite tool, or a fresh plugin-sourced instruction minted by a leaf tool (`tool-goal`'s wrap-up) — even when the tool later throws or cancellation wins; it never injects immediately.
 - `ToolExecutionResult` — discriminated execution-local outcome. Success is `{ isError:false, value:JsonValue, content, meta?, additionalContexts? }`; failure is `{ isError:true, error:{ message, info? }, content, meta?, additionalContexts? }` and has no value. Call identity stays on the immutable `ToolExecution`. The registry snapshots, validates, and freezes the canonical value before rendering, then materializes the durable presentation fields before final observation. `ToolFailure.info` carries an internal `{ name, code }` for a `HarnessError`; `additionalContexts` preserves every deferred or post-execute identified `UserMessage` for the loop's post-result FIFO.
-- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../ui/user-approval/README.md) when mounted and otherwise degrades to deny.
+- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../interaction/user-approval/README.md) when mounted and otherwise degrades to deny.
 - `PostToolDecision` — accept may replace `content` or `value`, never both, and may attach `additionalContexts`; block turns feedback into a valueless failure. Content replacement preserves the canonical value and metadata. Value replacement is revalidated and rerenders content/metadata. Accept preserves tool-deferred contexts before decision contexts; block discards tool-deferred contexts and exposes only contexts explicitly supplied by the blocking decision.
 - `ToolGuard` — `(execution) => string | undefined`; the returned string is a final monotonic denial reason evaluated after the reorderable pre-execute waterfall and before dispatch.
 - `ToolCallView` / `ToolResultView` — provider-neutral `card`-tagged render intents a tool returns from `presentCall` / `presentResult` to own how a UI renders ITS calls (see "Tool-owned UI presentation").
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 9f875bd80a..5911b25b1d 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -45,7 +45,7 @@ tools:
 - `ToolExecution`：只读流水线视图：不可变的 `{ token, callId, name, arguments, signal, agent?, parent? }`；注册表会另行保留并重新融合调用方的原始信号。`ToolDispatchExecution` 是仅供 `tools/execute` 使用的视图，其必填信号可变，因此包装层可以替换并还原它，但不能删除它。嵌套调用的 `parent` 是 `ToolExecutionToken`，而不是执行对象。
 - `ToolRunContext`：传给工具主体的执行上下文，在 `ToolExecution` 基础上增加 `deferContext(context)`。它把一条上下文推迟到该工具的最终结果抵达循环时——通常是组合工具转运的嵌套分发上下文，也可以是叶子工具铸造的全新插件来源指令（如 `tool-goal` 的收尾注入）——即使工具后来抛出或取消胜出也不例外；该方法绝不会立即注入上下文。
 - `ToolExecutionResult`：可辨识的执行局部结果。成功形态为 `{ isError:false, value:JsonValue, content, meta?, additionalContexts? }`；失败形态为 `{ isError:true, error:{ message, info? }, content, meta?, additionalContexts? }`，且不含值。调用身份保留在不可变的 `ToolExecution` 上。注册表会在呈现前快照、验证并冻结规范值，随后在最终观测前实体化持久呈现字段。`ToolFailure.info` 携带内部的 `{ name, code }`，用于表示 `HarnessError`；`additionalContexts` 会保留每个通过延迟或 post-execute 加入且带标识的 `UserMessage`，供循环在结果后按 FIFO 顺序处理。
-- `PreToolDecision`：`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`。该类型有意不提供输入改写；`ask` 在挂载 [`ctx.approval`](../../ui/user-approval/README.md) 时由它处理，否则退化为拒绝。
+- `PreToolDecision`：`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`。该类型有意不提供输入改写；`ask` 在挂载 [`ctx.approval`](../../interaction/user-approval/README.md) 时由它处理，否则退化为拒绝。
 - `PostToolDecision`：接受决定可以替换 `content` 或 `value`（不能同时替换），并可附加 `additionalContexts`；阻止决定会把反馈变成无值失败。替换内容会保留规范值和元数据。替换值会重新验证，并重新呈现内容／元数据。接受决定会先保留工具延迟的上下文，再附加决定上下文；阻止决定会丢弃工具延迟的上下文，只公开阻止决定显式提供的上下文。
 - `ToolGuard`：`(execution) => string | undefined`；返回的字符串是最终单调拒绝理由，在可重排的前置执行 waterfall 之后、分发之前求值。
 - `ToolCallView` / `ToolResultView`：提供方无关、带 `card` 标签的呈现意图；工具通过 `presentCall` / `presentResult` 返回该意图，从而拥有 UI 呈现其自身调用的方式（参见「工具拥有的 UI 呈现」）。
diff --git a/packages/core/tools/tsconfig.json b/packages/core/tools/tsconfig.json
index 918112d7d0..de5756ecbd 100644
--- a/packages/core/tools/tsconfig.json
+++ b/packages/core/tools/tsconfig.json
@@ -33,7 +33,7 @@
       "path": "../../core/scope"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index d09a0e333d..14b2c3f607 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -33,7 +33,7 @@ const decompress = promisify(zstdDecompress)
 const dshPackages = [
   'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
-  'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
+  'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'context/workspace-context', 'support/invariants', 'boot/app-boot',
   'session/session-persistence',
   'session/session-checkpoint-policy', 'session/session-persistence-jsonl',
   'acp/acp', 'examples/acp-demo', 'util/paths',
diff --git a/packages/examples/acp-demo/tsconfig.json b/packages/examples/acp-demo/tsconfig.json
index 34b48fc46a..5c7193f1bb 100644
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -18,7 +18,7 @@
       "path": "../../../vendor/loader"
     },
     {
-      "path": "../../ui/app-boot"
+      "path": "../../boot/app-boot"
     },
     {
       "path": "../../acp/acp"
diff --git a/packages/examples/jsonrpc-demo/tsconfig.json b/packages/examples/jsonrpc-demo/tsconfig.json
index aba279d405..061bbf68c3 100644
--- a/packages/examples/jsonrpc-demo/tsconfig.json
+++ b/packages/examples/jsonrpc-demo/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/loader"
     },
     {
-      "path": "../../ui/app-boot"
+      "path": "../../boot/app-boot"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/fs/tool-fs/tsconfig.json b/packages/fs/tool-fs/tsconfig.json
index fb420b553c..a3f128143c 100644
--- a/packages/fs/tool-fs/tsconfig.json
+++ b/packages/fs/tool-fs/tsconfig.json
@@ -40,7 +40,7 @@
       "path": "../../sandbox/sandbox-policy"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     }
   ]
 }
diff --git a/packages/goal/command-goal/tsconfig.json b/packages/goal/command-goal/tsconfig.json
index 8b03235814..488c576922 100644
--- a/packages/goal/command-goal/tsconfig.json
+++ b/packages/goal/command-goal/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../goal"
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 58c63f5669..64d7944892 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -66,13 +66,13 @@
       "path": "../../skill/skill"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
-      "path": "../../ui/user-interaction"
+      "path": "../../interaction/user-interaction"
     },
     {
       "path": "../../workspace/workspace"
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
new file mode 100644
index 0000000000..2555e896a1
--- /dev/null
+++ b/packages/interaction/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/interaction/README.md
+README.md: 506b47753fc9250f9f7bd971265421ad46a106b2
+README.zh.md: 34d336f3d3c10deab166d5c13bb86c13ee9bced0
diff --git a/packages/ui/README.md b/packages/interaction/README.md
similarity index 71%
rename from packages/ui/README.md
rename to packages/interaction/README.md
index 15754410a4..506b47753f 100644
--- a/packages/ui/README.md
+++ b/packages/interaction/README.md
@@ -1,8 +1,8 @@
-# ui/ — human and SDK-client integration surfaces
+# interaction/ — the human-collaboration plane
 
 English | [中文](README.zh.md)
 
-Human-facing channels and the out-of-process SDK server. These are **product** packages: real interfaces that a person or SDK client drives.
+The seams through which a human collaborates with a running agent — questions, approvals, permission presets, commands. These are **product** packages: real interfaces a person drives.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -11,7 +11,5 @@ Human-facing channels and the out-of-process SDK server. These are **product** p
 | [`permission/`](permission/README.md) | Presents and persists user-facing permission presets. | `ctx.permission` |
 | [`user-interaction/`](user-interaction/README.md) | Defines the provider-neutral human question/answer seam. | `ctx.userInteraction` |
 | [`tool-ask-user/`](tool-ask-user/README.md) | Exposes human questions to the model. | (registers on `ctx.tools`) |
-| [`jsonrpc/`](jsonrpc/README.md) | Serves out-of-process SDK clients over stdio JSON-RPC. | (drives `ctx.agents`) |
-| [`app-boot/`](app-boot/README.md) | Provides shared boot support for application launchers. | (library for the bins) |
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
diff --git a/packages/ui/README.zh.md b/packages/interaction/README.zh.md
similarity index 69%
rename from packages/ui/README.zh.md
rename to packages/interaction/README.zh.md
index 4023b80085..34d336f3d3 100644
--- a/packages/ui/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -1,8 +1,8 @@
-# ui/：面向用户和 SDK 客户端的集成接口
+# interaction/：人机协作平面
 
 [English](README.md) | 中文
 
-面向用户的通道和进程外 SDK 服务器。这些是**产品**包：由用户或 SDK 客户端直接操作的真实接口。
+人与运行中的 agent（智能体）协作所经由的各个 seam——提问、审批、权限预设、命令。这些是**产品**包（package）：由用户直接操作的真实接口。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
@@ -11,7 +11,5 @@
 | [`permission/`](permission/README.md) | 呈现并持久化面向用户的权限预设。 | `ctx.permission` |
 | [`user-interaction/`](user-interaction/README.md) | 定义与提供方无关的用户问答 seam。 | `ctx.userInteraction` |
 | [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
-| [`jsonrpc/`](jsonrpc/README.md) | 通过 stdio JSON-RPC 为进程外 SDK 客户端提供服务。 | （驱动 `ctx.agents`） |
-| [`app-boot/`](app-boot/README.md) | 为应用启动器提供共享启动支持。 | （供各 bin 使用的库） |
 
 这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
diff --git a/packages/ui/commands/README.i18n.yaml b/packages/interaction/commands/README.i18n.yaml
similarity index 79%
rename from packages/ui/commands/README.i18n.yaml
rename to packages/interaction/commands/README.i18n.yaml
index be55a19ca3..967fa0d4ef 100644
--- a/packages/ui/commands/README.i18n.yaml
+++ b/packages/interaction/commands/README.i18n.yaml
@@ -1,6 +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/ui/commands/README.md
+#   pnpm run verify-translation-pairing --write packages/interaction/commands/README.md
 README.md: 1709bdcdce4e43d98cfea5ff3972ab95bfd3c33b
 README.zh.md: 569f2aa8293793b26d63ee16e3ea7600e04a8397
diff --git a/packages/ui/commands/README.md b/packages/interaction/commands/README.md
similarity index 100%
rename from packages/ui/commands/README.md
rename to packages/interaction/commands/README.md
diff --git a/packages/ui/commands/README.zh.md b/packages/interaction/commands/README.zh.md
similarity index 100%
rename from packages/ui/commands/README.zh.md
rename to packages/interaction/commands/README.zh.md
diff --git a/packages/ui/commands/package.json b/packages/interaction/commands/package.json
similarity index 100%
rename from packages/ui/commands/package.json
rename to packages/interaction/commands/package.json
diff --git a/packages/ui/commands/src/brand.ts b/packages/interaction/commands/src/brand.ts
similarity index 100%
rename from packages/ui/commands/src/brand.ts
rename to packages/interaction/commands/src/brand.ts
diff --git a/packages/ui/commands/src/index.ts b/packages/interaction/commands/src/index.ts
similarity index 100%
rename from packages/ui/commands/src/index.ts
rename to packages/interaction/commands/src/index.ts
diff --git a/packages/ui/commands/src/invariant.ts b/packages/interaction/commands/src/invariant.ts
similarity index 100%
rename from packages/ui/commands/src/invariant.ts
rename to packages/interaction/commands/src/invariant.ts
diff --git a/packages/ui/commands/tests/commands.spec.ts b/packages/interaction/commands/tests/commands.spec.ts
similarity index 100%
rename from packages/ui/commands/tests/commands.spec.ts
rename to packages/interaction/commands/tests/commands.spec.ts
diff --git a/packages/ui/commands/tests/invariant.spec.ts b/packages/interaction/commands/tests/invariant.spec.ts
similarity index 100%
rename from packages/ui/commands/tests/invariant.spec.ts
rename to packages/interaction/commands/tests/invariant.spec.ts
diff --git a/packages/ui/commands/tsconfig.json b/packages/interaction/commands/tsconfig.json
similarity index 100%
rename from packages/ui/commands/tsconfig.json
rename to packages/interaction/commands/tsconfig.json
diff --git a/packages/interaction/permission/README.i18n.yaml b/packages/interaction/permission/README.i18n.yaml
new file mode 100644
index 0000000000..b5883174dc
--- /dev/null
+++ b/packages/interaction/permission/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/interaction/permission/README.md
+README.md: 814085ed6f2c9650854f377e1c97e442fc4211a4
+README.zh.md: 36880d6b8c3f0b39b88db1abb02534f30e3355fa
diff --git a/packages/ui/permission/README.md b/packages/interaction/permission/README.md
similarity index 100%
rename from packages/ui/permission/README.md
rename to packages/interaction/permission/README.md
diff --git a/packages/ui/permission/README.zh.md b/packages/interaction/permission/README.zh.md
similarity index 100%
rename from packages/ui/permission/README.zh.md
rename to packages/interaction/permission/README.zh.md
diff --git a/packages/ui/permission/package.json b/packages/interaction/permission/package.json
similarity index 100%
rename from packages/ui/permission/package.json
rename to packages/interaction/permission/package.json
diff --git a/packages/ui/permission/src/client.ts b/packages/interaction/permission/src/client.ts
similarity index 100%
rename from packages/ui/permission/src/client.ts
rename to packages/interaction/permission/src/client.ts
diff --git a/packages/ui/permission/src/index.ts b/packages/interaction/permission/src/index.ts
similarity index 100%
rename from packages/ui/permission/src/index.ts
rename to packages/interaction/permission/src/index.ts
diff --git a/packages/ui/permission/src/invariant.ts b/packages/interaction/permission/src/invariant.ts
similarity index 100%
rename from packages/ui/permission/src/invariant.ts
rename to packages/interaction/permission/src/invariant.ts
diff --git a/packages/ui/permission/src/types.ts b/packages/interaction/permission/src/types.ts
similarity index 100%
rename from packages/ui/permission/src/types.ts
rename to packages/interaction/permission/src/types.ts
diff --git a/packages/ui/permission/tests/invariant.spec.ts b/packages/interaction/permission/tests/invariant.spec.ts
similarity index 100%
rename from packages/ui/permission/tests/invariant.spec.ts
rename to packages/interaction/permission/tests/invariant.spec.ts
diff --git a/packages/ui/permission/tests/permission.spec.ts b/packages/interaction/permission/tests/permission.spec.ts
similarity index 100%
rename from packages/ui/permission/tests/permission.spec.ts
rename to packages/interaction/permission/tests/permission.spec.ts
diff --git a/packages/ui/permission/tests/projection.spec.ts b/packages/interaction/permission/tests/projection.spec.ts
similarity index 100%
rename from packages/ui/permission/tests/projection.spec.ts
rename to packages/interaction/permission/tests/projection.spec.ts
diff --git a/packages/ui/permission/tsconfig.json b/packages/interaction/permission/tsconfig.json
similarity index 100%
rename from packages/ui/permission/tsconfig.json
rename to packages/interaction/permission/tsconfig.json
diff --git a/packages/ui/tool-ask-user/README.i18n.yaml b/packages/interaction/tool-ask-user/README.i18n.yaml
similarity index 79%
rename from packages/ui/tool-ask-user/README.i18n.yaml
rename to packages/interaction/tool-ask-user/README.i18n.yaml
index bbd0ba0561..f88c303525 100644
--- a/packages/ui/tool-ask-user/README.i18n.yaml
+++ b/packages/interaction/tool-ask-user/README.i18n.yaml
@@ -1,6 +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/ui/tool-ask-user/README.md
+#   pnpm run verify-translation-pairing --write packages/interaction/tool-ask-user/README.md
 README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
 README.zh.md: 3f7b814b83c8c6957a4b2574ee69e87d45f65ae6
diff --git a/packages/ui/tool-ask-user/README.md b/packages/interaction/tool-ask-user/README.md
similarity index 100%
rename from packages/ui/tool-ask-user/README.md
rename to packages/interaction/tool-ask-user/README.md
diff --git a/packages/ui/tool-ask-user/README.zh.md b/packages/interaction/tool-ask-user/README.zh.md
similarity index 100%
rename from packages/ui/tool-ask-user/README.zh.md
rename to packages/interaction/tool-ask-user/README.zh.md
diff --git a/packages/ui/tool-ask-user/package.json b/packages/interaction/tool-ask-user/package.json
similarity index 100%
rename from packages/ui/tool-ask-user/package.json
rename to packages/interaction/tool-ask-user/package.json
diff --git a/packages/ui/tool-ask-user/src/index.ts b/packages/interaction/tool-ask-user/src/index.ts
similarity index 100%
rename from packages/ui/tool-ask-user/src/index.ts
rename to packages/interaction/tool-ask-user/src/index.ts
diff --git a/packages/ui/tool-ask-user/src/invariant.ts b/packages/interaction/tool-ask-user/src/invariant.ts
similarity index 100%
rename from packages/ui/tool-ask-user/src/invariant.ts
rename to packages/interaction/tool-ask-user/src/invariant.ts
diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts
similarity index 100%
rename from packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
rename to packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts
diff --git a/packages/ui/tool-ask-user/tsconfig.json b/packages/interaction/tool-ask-user/tsconfig.json
similarity index 100%
rename from packages/ui/tool-ask-user/tsconfig.json
rename to packages/interaction/tool-ask-user/tsconfig.json
diff --git a/packages/ui/user-approval/README.i18n.yaml b/packages/interaction/user-approval/README.i18n.yaml
similarity index 79%
rename from packages/ui/user-approval/README.i18n.yaml
rename to packages/interaction/user-approval/README.i18n.yaml
index cf9c8e1fce..36188334e7 100644
--- a/packages/ui/user-approval/README.i18n.yaml
+++ b/packages/interaction/user-approval/README.i18n.yaml
@@ -1,6 +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/ui/user-approval/README.md
+#   pnpm run verify-translation-pairing --write packages/interaction/user-approval/README.md
 README.md: 7b87a75d1c7c43874c484bc11f8deed45cb523ce
 README.zh.md: 3c02f8d673a62c3ee954da26f6341b433032a88c
diff --git a/packages/ui/user-approval/README.md b/packages/interaction/user-approval/README.md
similarity index 100%
rename from packages/ui/user-approval/README.md
rename to packages/interaction/user-approval/README.md
diff --git a/packages/ui/user-approval/README.zh.md b/packages/interaction/user-approval/README.zh.md
similarity index 100%
rename from packages/ui/user-approval/README.zh.md
rename to packages/interaction/user-approval/README.zh.md
diff --git a/packages/ui/user-approval/package.json b/packages/interaction/user-approval/package.json
similarity index 100%
rename from packages/ui/user-approval/package.json
rename to packages/interaction/user-approval/package.json
diff --git a/packages/ui/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
similarity index 100%
rename from packages/ui/user-approval/src/index.ts
rename to packages/interaction/user-approval/src/index.ts
diff --git a/packages/ui/user-approval/src/invariant.ts b/packages/interaction/user-approval/src/invariant.ts
similarity index 100%
rename from packages/ui/user-approval/src/invariant.ts
rename to packages/interaction/user-approval/src/invariant.ts
diff --git a/packages/ui/user-approval/src/types.ts b/packages/interaction/user-approval/src/types.ts
similarity index 100%
rename from packages/ui/user-approval/src/types.ts
rename to packages/interaction/user-approval/src/types.ts
diff --git a/packages/ui/user-approval/tests/approval.spec.ts b/packages/interaction/user-approval/tests/approval.spec.ts
similarity index 100%
rename from packages/ui/user-approval/tests/approval.spec.ts
rename to packages/interaction/user-approval/tests/approval.spec.ts
diff --git a/packages/ui/user-approval/tests/invariant.spec.ts b/packages/interaction/user-approval/tests/invariant.spec.ts
similarity index 100%
rename from packages/ui/user-approval/tests/invariant.spec.ts
rename to packages/interaction/user-approval/tests/invariant.spec.ts
diff --git a/packages/ui/user-approval/tsconfig.json b/packages/interaction/user-approval/tsconfig.json
similarity index 100%
rename from packages/ui/user-approval/tsconfig.json
rename to packages/interaction/user-approval/tsconfig.json
diff --git a/packages/ui/user-approval/tsdown.config.ts b/packages/interaction/user-approval/tsdown.config.ts
similarity index 100%
rename from packages/ui/user-approval/tsdown.config.ts
rename to packages/interaction/user-approval/tsdown.config.ts
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
new file mode 100644
index 0000000000..f467aaf4e1
--- /dev/null
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
+README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32
+README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79
diff --git a/packages/ui/user-interaction/README.md b/packages/interaction/user-interaction/README.md
similarity index 100%
rename from packages/ui/user-interaction/README.md
rename to packages/interaction/user-interaction/README.md
diff --git a/packages/ui/user-interaction/README.zh.md b/packages/interaction/user-interaction/README.zh.md
similarity index 100%
rename from packages/ui/user-interaction/README.zh.md
rename to packages/interaction/user-interaction/README.zh.md
diff --git a/packages/ui/user-interaction/package.json b/packages/interaction/user-interaction/package.json
similarity index 100%
rename from packages/ui/user-interaction/package.json
rename to packages/interaction/user-interaction/package.json
diff --git a/packages/ui/user-interaction/src/index.ts b/packages/interaction/user-interaction/src/index.ts
similarity index 100%
rename from packages/ui/user-interaction/src/index.ts
rename to packages/interaction/user-interaction/src/index.ts
diff --git a/packages/ui/user-interaction/src/invariant.ts b/packages/interaction/user-interaction/src/invariant.ts
similarity index 100%
rename from packages/ui/user-interaction/src/invariant.ts
rename to packages/interaction/user-interaction/src/invariant.ts
diff --git a/packages/ui/user-interaction/src/types.ts b/packages/interaction/user-interaction/src/types.ts
similarity index 100%
rename from packages/ui/user-interaction/src/types.ts
rename to packages/interaction/user-interaction/src/types.ts
diff --git a/packages/ui/user-interaction/tests/user-interaction.spec.ts b/packages/interaction/user-interaction/tests/user-interaction.spec.ts
similarity index 100%
rename from packages/ui/user-interaction/tests/user-interaction.spec.ts
rename to packages/interaction/user-interaction/tests/user-interaction.spec.ts
diff --git a/packages/ui/user-interaction/tsconfig.json b/packages/interaction/user-interaction/tsconfig.json
similarity index 100%
rename from packages/ui/user-interaction/tsconfig.json
rename to packages/interaction/user-interaction/tsconfig.json
diff --git a/packages/plan/plan-mode/tsconfig.json b/packages/plan/plan-mode/tsconfig.json
index 6fa3cffbbc..4dde8fda45 100644
--- a/packages/plan/plan-mode/tsconfig.json
+++ b/packages/plan/plan-mode/tsconfig.json
@@ -27,10 +27,10 @@
       "path": "../../core/system-prompt"
     },
     {
-      "path": "../../ui/user-interaction"
+      "path": "../../interaction/user-interaction"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../session/session-projection"
diff --git a/packages/ui/README.i18n.yaml b/packages/scaffold/README.i18n.yaml
similarity index 57%
rename from packages/ui/README.i18n.yaml
rename to packages/scaffold/README.i18n.yaml
index fba1f95c52..1480a14b69 100644
--- a/packages/ui/README.i18n.yaml
+++ b/packages/scaffold/README.i18n.yaml
@@ -1,6 +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/ui/README.md
-README.md: 15754410a4a81eb3fc898dd55269ddd1637e1dab
-README.zh.md: 4023b80085998f57ed321bfda3a0abdd08b70a28
+#   pnpm run verify-translation-pairing --write packages/scaffold/README.md
+README.md: b166a351a53afe075ecb794fe2bf6f0702a435ae
+README.zh.md: 6e2a65ea554487f48563c16e1defa37ef1a5e043
diff --git a/packages/sdk/README.md b/packages/scaffold/README.md
similarity index 64%
rename from packages/sdk/README.md
rename to packages/scaffold/README.md
index 3f99d6d45d..b166a351a5 100644
--- a/packages/sdk/README.md
+++ b/packages/scaffold/README.md
@@ -1,16 +1,17 @@
-# SDK packages
+# scaffold/ — create, launch, and drive projects from outside
 
 English | [中文](README.zh.md)
 
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process.
+This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md).
 
 | Package | Role |
 |---|---|
 | [`helper/`](helper/README.md) | Provides the shared project-editing domain |
 | [`scripts/`](scripts/README.md) | Provides the `dsh-sdk` project commands |
 | [`create-sdk/`](create-sdk/README.md) | Creates new SDK projects |
-| [`sdk-protocol/`](sdk-protocol/README.md) | Defines the SDK runtime wire protocol |
-| [`sdk-client/`](sdk-client/README.md) | Drives a Harness runtime through the TypeScript client API |
+| [`protocol/`](protocol/README.md) | Defines the SDK runtime wire protocol |
+| [`client/`](client/README.md) | Drives a Harness runtime through the TypeScript client API |
+| [`server/`](server/README.md) | Serves out-of-process SDK clients over stdio JSON-RPC |
 | [`telemetry/`](telemetry/README.md) | Provides launcher telemetry, consent, and redaction primitives |
 
 `@deepseek-ai/create-sdk` follows npm's scoped initializer naming convention; the other packages follow the repository's `@deepseek-ai/dsh-*` convention. See the [developer-project workflow](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md), [project-editing architecture](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md), and [TypeScript SDK design](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md).
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
new file mode 100644
index 0000000000..6e2a65ea55
--- /dev/null
+++ b/packages/scaffold/README.zh.md
@@ -0,0 +1,17 @@
+# scaffold/：从外部创建、启动、驱动项目
+
+[English](README.md) | 中文
+
+本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
+
+| 包 | 职责 |
+|---|---|
+| [`helper/`](helper/README.md) | 提供共享的项目编辑领域 |
+| [`scripts/`](scripts/README.md) | 提供 `dsh-sdk` 项目命令 |
+| [`create-sdk/`](create-sdk/README.md) | 创建新的 SDK 项目 |
+| [`protocol/`](protocol/README.md) | 定义 SDK 运行时通信协议 |
+| [`client/`](client/README.md) | 通过 TypeScript 客户端 API 驱动 Harness 运行时 |
+| [`server/`](server/README.md) | 通过 stdio JSON-RPC 为进程外 SDK 客户端提供服务 |
+| [`telemetry/`](telemetry/README.md) | 提供启动器 telemetry、同意与脱敏原语 |
+
+`@deepseek-ai/create-sdk` 遵循 npm 的 scoped initializer 命名约定；其余包遵循仓库的 `@deepseek-ai/dsh-*` 约定。参见[开发者项目工作流](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)、[项目编辑架构](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)与 [TypeScript SDK 设计](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)。
diff --git a/packages/sdk/sdk-client/README.i18n.yaml b/packages/scaffold/client/README.i18n.yaml
similarity index 80%
rename from packages/sdk/sdk-client/README.i18n.yaml
rename to packages/scaffold/client/README.i18n.yaml
index bff82b8aec..0a71141cd6 100644
--- a/packages/sdk/sdk-client/README.i18n.yaml
+++ b/packages/scaffold/client/README.i18n.yaml
@@ -1,6 +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/sdk/sdk-client/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/client/README.md
 README.md: f27ec256330254156c45b136c21308529ea99e3d
 README.zh.md: bd23762500a4da469839da8ddb50455e3419b553
diff --git a/packages/sdk/sdk-client/README.md b/packages/scaffold/client/README.md
similarity index 100%
rename from packages/sdk/sdk-client/README.md
rename to packages/scaffold/client/README.md
diff --git a/packages/sdk/sdk-client/README.zh.md b/packages/scaffold/client/README.zh.md
similarity index 100%
rename from packages/sdk/sdk-client/README.zh.md
rename to packages/scaffold/client/README.zh.md
diff --git a/packages/sdk/sdk-client/package.json b/packages/scaffold/client/package.json
similarity index 100%
rename from packages/sdk/sdk-client/package.json
rename to packages/scaffold/client/package.json
diff --git a/packages/sdk/sdk-client/src/api.ts b/packages/scaffold/client/src/api.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/api.ts
rename to packages/scaffold/client/src/api.ts
diff --git a/packages/sdk/sdk-client/src/client.ts b/packages/scaffold/client/src/client.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/client.ts
rename to packages/scaffold/client/src/client.ts
diff --git a/packages/sdk/sdk-client/src/dispose.ts b/packages/scaffold/client/src/dispose.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/dispose.ts
rename to packages/scaffold/client/src/dispose.ts
diff --git a/packages/sdk/sdk-client/src/index.ts b/packages/scaffold/client/src/index.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/index.ts
rename to packages/scaffold/client/src/index.ts
diff --git a/packages/sdk/sdk-client/src/invariant.ts b/packages/scaffold/client/src/invariant.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/invariant.ts
rename to packages/scaffold/client/src/invariant.ts
diff --git a/packages/sdk/sdk-client/src/types.ts b/packages/scaffold/client/src/types.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/types.ts
rename to packages/scaffold/client/src/types.ts
diff --git a/packages/sdk/sdk-client/tests/dispose.spec.ts b/packages/scaffold/client/tests/dispose.spec.ts
similarity index 100%
rename from packages/sdk/sdk-client/tests/dispose.spec.ts
rename to packages/scaffold/client/tests/dispose.spec.ts
diff --git a/packages/sdk/sdk-client/tests/fake-runtime.ts b/packages/scaffold/client/tests/fake-runtime.ts
similarity index 100%
rename from packages/sdk/sdk-client/tests/fake-runtime.ts
rename to packages/scaffold/client/tests/fake-runtime.ts
diff --git a/packages/sdk/sdk-client/tests/sdk-client.spec.ts b/packages/scaffold/client/tests/sdk-client.spec.ts
similarity index 100%
rename from packages/sdk/sdk-client/tests/sdk-client.spec.ts
rename to packages/scaffold/client/tests/sdk-client.spec.ts
diff --git a/packages/sdk/sdk-client/tsconfig.json b/packages/scaffold/client/tsconfig.json
similarity index 93%
rename from packages/sdk/sdk-client/tsconfig.json
rename to packages/scaffold/client/tsconfig.json
index 567c6582bb..a5456f5ad3 100644
--- a/packages/sdk/sdk-client/tsconfig.json
+++ b/packages/scaffold/client/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../sdk-protocol"
+      "path": "../protocol"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/sdk/create-sdk/README.i18n.yaml b/packages/scaffold/create-sdk/README.i18n.yaml
similarity index 80%
rename from packages/sdk/create-sdk/README.i18n.yaml
rename to packages/scaffold/create-sdk/README.i18n.yaml
index 27609d9a11..62d5bd3793 100644
--- a/packages/sdk/create-sdk/README.i18n.yaml
+++ b/packages/scaffold/create-sdk/README.i18n.yaml
@@ -1,6 +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/sdk/create-sdk/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/create-sdk/README.md
 README.md: aa09236832a50abdcd2b158e0561db26bce19cf6
 README.zh.md: a4685e66bc3eb7924dd247a7b6b420f6bcc70990
diff --git a/packages/sdk/create-sdk/README.md b/packages/scaffold/create-sdk/README.md
similarity index 100%
rename from packages/sdk/create-sdk/README.md
rename to packages/scaffold/create-sdk/README.md
diff --git a/packages/sdk/create-sdk/README.zh.md b/packages/scaffold/create-sdk/README.zh.md
similarity index 100%
rename from packages/sdk/create-sdk/README.zh.md
rename to packages/scaffold/create-sdk/README.zh.md
diff --git a/packages/sdk/create-sdk/package.json b/packages/scaffold/create-sdk/package.json
similarity index 100%
rename from packages/sdk/create-sdk/package.json
rename to packages/scaffold/create-sdk/package.json
diff --git a/packages/sdk/create-sdk/src/args.ts b/packages/scaffold/create-sdk/src/args.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/args.ts
rename to packages/scaffold/create-sdk/src/args.ts
diff --git a/packages/sdk/create-sdk/src/bin.ts b/packages/scaffold/create-sdk/src/bin.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/bin.ts
rename to packages/scaffold/create-sdk/src/bin.ts
diff --git a/packages/sdk/create-sdk/src/command.ts b/packages/scaffold/create-sdk/src/command.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/command.ts
rename to packages/scaffold/create-sdk/src/command.ts
diff --git a/packages/sdk/create-sdk/src/create-questions.ts b/packages/scaffold/create-sdk/src/create-questions.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/create-questions.ts
rename to packages/scaffold/create-sdk/src/create-questions.ts
diff --git a/packages/sdk/create-sdk/src/create-wizard.ts b/packages/scaffold/create-sdk/src/create-wizard.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/create-wizard.ts
rename to packages/scaffold/create-sdk/src/create-wizard.ts
diff --git a/packages/sdk/create-sdk/src/headless.ts b/packages/scaffold/create-sdk/src/headless.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/headless.ts
rename to packages/scaffold/create-sdk/src/headless.ts
diff --git a/packages/sdk/create-sdk/src/index.ts b/packages/scaffold/create-sdk/src/index.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/index.ts
rename to packages/scaffold/create-sdk/src/index.ts
diff --git a/packages/sdk/create-sdk/src/invariant.ts b/packages/scaffold/create-sdk/src/invariant.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/invariant.ts
rename to packages/scaffold/create-sdk/src/invariant.ts
diff --git a/packages/sdk/create-sdk/src/project-scaffolder.ts b/packages/scaffold/create-sdk/src/project-scaffolder.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/project-scaffolder.ts
rename to packages/scaffold/create-sdk/src/project-scaffolder.ts
diff --git a/packages/sdk/create-sdk/src/templates/assets/created.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/created.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/create-templates.ts b/packages/scaffold/create-sdk/src/templates/create-templates.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/create-templates.ts
rename to packages/scaffold/create-sdk/src/templates/create-templates.ts
diff --git a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts b/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
similarity index 87%
rename from packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
rename to packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
index 4b2de078c7..827abe06a2 100644
--- a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
+++ b/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
@@ -7,8 +7,8 @@ import { describe, expect, it } from 'vitest'
 
 const execFileAsync = promisify(execFile)
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const createBin = join(repoRoot, 'packages/sdk/create-sdk/lib/bin.js')
-const scriptsBin = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
+const createBin = join(repoRoot, 'packages/scaffold/create-sdk/lib/bin.js')
+const scriptsBin = join(repoRoot, 'packages/scaffold/scripts/lib/bin.js')
 
 describe.skipIf(!existsSync(createBin) || !existsSync(scriptsBin))(
   'SDK built artifacts',
diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/scaffold/create-sdk/tests/create.snapshot.ts
similarity index 100%
rename from packages/sdk/create-sdk/tests/create.snapshot.ts
rename to packages/scaffold/create-sdk/tests/create.snapshot.ts
diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/scaffold/create-sdk/tests/create.spec.ts
similarity index 100%
rename from packages/sdk/create-sdk/tests/create.spec.ts
rename to packages/scaffold/create-sdk/tests/create.spec.ts
diff --git a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts b/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
similarity index 98%
rename from packages/sdk/create-sdk/tests/link-workspace.e2e.ts
rename to packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
index b7739acc16..b978c8217e 100644
--- a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
+++ b/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
@@ -17,7 +17,7 @@ import { scaffoldProject } from '../src/project-scaffolder.ts'
 
 const execFileAsync = promisify(execFile)
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const builtScripts = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
+const builtScripts = join(repoRoot, 'packages/scaffold/scripts/lib/bin.js')
 const temporary: string[] = []
 
 function resolveCorepackHome(): string {
diff --git a/packages/sdk/create-sdk/tsconfig.json b/packages/scaffold/create-sdk/tsconfig.json
similarity index 100%
rename from packages/sdk/create-sdk/tsconfig.json
rename to packages/scaffold/create-sdk/tsconfig.json
diff --git a/packages/sdk/create-sdk/tsdown.config.ts b/packages/scaffold/create-sdk/tsdown.config.ts
similarity index 100%
rename from packages/sdk/create-sdk/tsdown.config.ts
rename to packages/scaffold/create-sdk/tsdown.config.ts
diff --git a/packages/sdk/helper/README.i18n.yaml b/packages/scaffold/helper/README.i18n.yaml
similarity index 80%
rename from packages/sdk/helper/README.i18n.yaml
rename to packages/scaffold/helper/README.i18n.yaml
index bb5acbdcc2..a62db5f38a 100644
--- a/packages/sdk/helper/README.i18n.yaml
+++ b/packages/scaffold/helper/README.i18n.yaml
@@ -1,6 +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/sdk/helper/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/helper/README.md
 README.md: 416fcab9815e50ca662333eb6925cc37eb0c41c4
 README.zh.md: c50ec7aafa03377bd11759c50eeb2422a12fab68
diff --git a/packages/sdk/helper/README.md b/packages/scaffold/helper/README.md
similarity index 100%
rename from packages/sdk/helper/README.md
rename to packages/scaffold/helper/README.md
diff --git a/packages/sdk/helper/README.zh.md b/packages/scaffold/helper/README.zh.md
similarity index 100%
rename from packages/sdk/helper/README.zh.md
rename to packages/scaffold/helper/README.zh.md
diff --git a/packages/sdk/helper/package.json b/packages/scaffold/helper/package.json
similarity index 100%
rename from packages/sdk/helper/package.json
rename to packages/scaffold/helper/package.json
diff --git a/packages/sdk/helper/src/documents/cordis-yaml-file.ts b/packages/scaffold/helper/src/documents/cordis-yaml-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/cordis-yaml-file.ts
rename to packages/scaffold/helper/src/documents/cordis-yaml-file.ts
diff --git a/packages/sdk/helper/src/documents/env-file.ts b/packages/scaffold/helper/src/documents/env-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/env-file.ts
rename to packages/scaffold/helper/src/documents/env-file.ts
diff --git a/packages/sdk/helper/src/documents/package-json-file.ts b/packages/scaffold/helper/src/documents/package-json-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/package-json-file.ts
rename to packages/scaffold/helper/src/documents/package-json-file.ts
diff --git a/packages/sdk/helper/src/documents/pnpm-workspace-file.ts b/packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/pnpm-workspace-file.ts
rename to packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
diff --git a/packages/sdk/helper/src/documents/project-file.ts b/packages/scaffold/helper/src/documents/project-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/project-file.ts
rename to packages/scaffold/helper/src/documents/project-file.ts
diff --git a/packages/sdk/helper/src/documents/tsconfig-file.ts b/packages/scaffold/helper/src/documents/tsconfig-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/tsconfig-file.ts
rename to packages/scaffold/helper/src/documents/tsconfig-file.ts
diff --git a/packages/sdk/helper/src/features/builtin/app.ts b/packages/scaffold/helper/src/features/builtin/app.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/app.ts
rename to packages/scaffold/helper/src/features/builtin/app.ts
diff --git a/packages/sdk/helper/src/features/builtin/helpers.ts b/packages/scaffold/helper/src/features/builtin/helpers.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/helpers.ts
rename to packages/scaffold/helper/src/features/builtin/helpers.ts
diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/scaffold/helper/src/features/builtin/index.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/index.ts
rename to packages/scaffold/helper/src/features/builtin/index.ts
diff --git a/packages/sdk/helper/src/features/builtin/provider.ts b/packages/scaffold/helper/src/features/builtin/provider.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/provider.ts
rename to packages/scaffold/helper/src/features/builtin/provider.ts
diff --git a/packages/sdk/helper/src/features/builtin/spine.ts b/packages/scaffold/helper/src/features/builtin/spine.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/spine.ts
rename to packages/scaffold/helper/src/features/builtin/spine.ts
diff --git a/packages/sdk/helper/src/features/define-feature.ts b/packages/scaffold/helper/src/features/define-feature.ts
similarity index 100%
rename from packages/sdk/helper/src/features/define-feature.ts
rename to packages/scaffold/helper/src/features/define-feature.ts
diff --git a/packages/sdk/helper/src/features/feature-configurator.ts b/packages/scaffold/helper/src/features/feature-configurator.ts
similarity index 100%
rename from packages/sdk/helper/src/features/feature-configurator.ts
rename to packages/scaffold/helper/src/features/feature-configurator.ts
diff --git a/packages/sdk/helper/src/features/feature.ts b/packages/scaffold/helper/src/features/feature.ts
similarity index 100%
rename from packages/sdk/helper/src/features/feature.ts
rename to packages/scaffold/helper/src/features/feature.ts
diff --git a/packages/sdk/helper/src/features/registry.ts b/packages/scaffold/helper/src/features/registry.ts
similarity index 100%
rename from packages/sdk/helper/src/features/registry.ts
rename to packages/scaffold/helper/src/features/registry.ts
diff --git a/packages/sdk/helper/src/features/resources.ts b/packages/scaffold/helper/src/features/resources.ts
similarity index 100%
rename from packages/sdk/helper/src/features/resources.ts
rename to packages/scaffold/helper/src/features/resources.ts
diff --git a/packages/sdk/helper/src/ids.ts b/packages/scaffold/helper/src/ids.ts
similarity index 100%
rename from packages/sdk/helper/src/ids.ts
rename to packages/scaffold/helper/src/ids.ts
diff --git a/packages/sdk/helper/src/index.ts b/packages/scaffold/helper/src/index.ts
similarity index 86%
rename from packages/sdk/helper/src/index.ts
rename to packages/scaffold/helper/src/index.ts
index 85aba58a99..8c8e0db4b9 100644
--- a/packages/sdk/helper/src/index.ts
+++ b/packages/scaffold/helper/src/index.ts
@@ -1,6 +1,10 @@
 /**
  * Shared domain and infrastructure for DeepSeek Harness SDK project tooling.
  *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-helper` before the first tagged release —
+ * the current name is indefensibly generic as a published name
+ * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-helper
  */
 
diff --git a/packages/sdk/helper/src/invariant.ts b/packages/scaffold/helper/src/invariant.ts
similarity index 100%
rename from packages/sdk/helper/src/invariant.ts
rename to packages/scaffold/helper/src/invariant.ts
diff --git a/packages/sdk/helper/src/package-managers/link-workspace.ts b/packages/scaffold/helper/src/package-managers/link-workspace.ts
similarity index 100%
rename from packages/sdk/helper/src/package-managers/link-workspace.ts
rename to packages/scaffold/helper/src/package-managers/link-workspace.ts
diff --git a/packages/sdk/helper/src/package-managers/package-manager.ts b/packages/scaffold/helper/src/package-managers/package-manager.ts
similarity index 100%
rename from packages/sdk/helper/src/package-managers/package-manager.ts
rename to packages/scaffold/helper/src/package-managers/package-manager.ts
diff --git a/packages/sdk/helper/src/plugins/local-plugin-blueprint.ts b/packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
similarity index 100%
rename from packages/sdk/helper/src/plugins/local-plugin-blueprint.ts
rename to packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
diff --git a/packages/sdk/helper/src/project/change-set.ts b/packages/scaffold/helper/src/project/change-set.ts
similarity index 100%
rename from packages/sdk/helper/src/project/change-set.ts
rename to packages/scaffold/helper/src/project/change-set.ts
diff --git a/packages/sdk/helper/src/project/npm-dependency-policy.ts b/packages/scaffold/helper/src/project/npm-dependency-policy.ts
similarity index 100%
rename from packages/sdk/helper/src/project/npm-dependency-policy.ts
rename to packages/scaffold/helper/src/project/npm-dependency-policy.ts
diff --git a/packages/sdk/helper/src/project/project-edit-session.ts b/packages/scaffold/helper/src/project/project-edit-session.ts
similarity index 100%
rename from packages/sdk/helper/src/project/project-edit-session.ts
rename to packages/scaffold/helper/src/project/project-edit-session.ts
diff --git a/packages/sdk/helper/src/project/sdk-project.ts b/packages/scaffold/helper/src/project/sdk-project.ts
similarity index 99%
rename from packages/sdk/helper/src/project/sdk-project.ts
rename to packages/scaffold/helper/src/project/sdk-project.ts
index e9302aa428..41b66fe7d0 100644
--- a/packages/sdk/helper/src/project/sdk-project.ts
+++ b/packages/scaffold/helper/src/project/sdk-project.ts
@@ -98,7 +98,7 @@ async function detectPackageManager(root: string, manifest: Readonly<PackageMani
 
 function linkedRepositoryRoot(root: string, manifest: Readonly<PackageManifest>): string | undefined {
   const spec = manifest.dependencies?.['@deepseek-ai/dsh-scripts']
-  const match = /^(?:file|link|portal):(.+)\/packages\/sdk\/scripts\/?$/.exec(spec ?? '')
+  const match = /^(?:file|link|portal):(.+)\/packages\/scaffold\/scripts\/?$/.exec(spec ?? '')
   return match?.[1] ? resolve(root, match[1]) : undefined
 }
 
diff --git a/packages/sdk/helper/src/project/types.ts b/packages/scaffold/helper/src/project/types.ts
similarity index 100%
rename from packages/sdk/helper/src/project/types.ts
rename to packages/scaffold/helper/src/project/types.ts
diff --git a/packages/sdk/helper/src/questions/clack-nested-multiselect.ts b/packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/clack-nested-multiselect.ts
rename to packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
diff --git a/packages/sdk/helper/src/questions/clack-prompt-port.ts b/packages/scaffold/helper/src/questions/clack-prompt-port.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/clack-prompt-port.ts
rename to packages/scaffold/helper/src/questions/clack-prompt-port.ts
diff --git a/packages/sdk/helper/src/questions/headless-prompt-port.ts b/packages/scaffold/helper/src/questions/headless-prompt-port.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/headless-prompt-port.ts
rename to packages/scaffold/helper/src/questions/headless-prompt-port.ts
diff --git a/packages/sdk/helper/src/questions/prompt-port.ts b/packages/scaffold/helper/src/questions/prompt-port.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/prompt-port.ts
rename to packages/scaffold/helper/src/questions/prompt-port.ts
diff --git a/packages/sdk/helper/src/questions/question.ts b/packages/scaffold/helper/src/questions/question.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/question.ts
rename to packages/scaffold/helper/src/questions/question.ts
diff --git a/packages/sdk/helper/src/templates/assets/README.md.tpl b/packages/scaffold/helper/src/templates/assets/README.md.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/README.md.tpl
rename to packages/scaffold/helper/src/templates/assets/README.md.tpl
diff --git a/packages/sdk/helper/src/templates/assets/gitignore.tpl b/packages/scaffold/helper/src/templates/assets/gitignore.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/gitignore.tpl
rename to packages/scaffold/helper/src/templates/assets/gitignore.tpl
diff --git a/packages/sdk/helper/src/templates/assets/index.ts.tpl b/packages/scaffold/helper/src/templates/assets/index.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/index.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/index.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/local-tool.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/local-tool.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/package.json.tpl b/packages/scaffold/helper/src/templates/assets/package.json.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/package.json.tpl
rename to packages/scaffold/helper/src/templates/assets/package.json.tpl
diff --git a/packages/sdk/helper/src/templates/assets/persona.txt.tpl b/packages/scaffold/helper/src/templates/assets/persona.txt.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/persona.txt.tpl
rename to packages/scaffold/helper/src/templates/assets/persona.txt.tpl
diff --git a/packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl b/packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl
rename to packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
diff --git a/packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl b/packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl b/packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl
rename to packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
diff --git a/packages/sdk/helper/src/templates/project-template.ts b/packages/scaffold/helper/src/templates/project-template.ts
similarity index 100%
rename from packages/sdk/helper/src/templates/project-template.ts
rename to packages/scaffold/helper/src/templates/project-template.ts
diff --git a/packages/sdk/helper/src/templates/template-assets.ts b/packages/scaffold/helper/src/templates/template-assets.ts
similarity index 100%
rename from packages/sdk/helper/src/templates/template-assets.ts
rename to packages/scaffold/helper/src/templates/template-assets.ts
diff --git a/packages/sdk/helper/src/templates/text-template.ts b/packages/scaffold/helper/src/templates/text-template.ts
similarity index 100%
rename from packages/sdk/helper/src/templates/text-template.ts
rename to packages/scaffold/helper/src/templates/text-template.ts
diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/scaffold/helper/tests/documents.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/documents.spec.ts
rename to packages/scaffold/helper/tests/documents.spec.ts
diff --git a/packages/sdk/helper/tests/headless-prompt-port.spec.ts b/packages/scaffold/helper/tests/headless-prompt-port.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/headless-prompt-port.spec.ts
rename to packages/scaffold/helper/tests/headless-prompt-port.spec.ts
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/scaffold/helper/tests/project.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/project.spec.ts
rename to packages/scaffold/helper/tests/project.spec.ts
diff --git a/packages/sdk/helper/tests/questions.spec.ts b/packages/scaffold/helper/tests/questions.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/questions.spec.ts
rename to packages/scaffold/helper/tests/questions.spec.ts
diff --git a/packages/sdk/helper/tsconfig.json b/packages/scaffold/helper/tsconfig.json
similarity index 100%
rename from packages/sdk/helper/tsconfig.json
rename to packages/scaffold/helper/tsconfig.json
diff --git a/packages/sdk/helper/tsdown.config.ts b/packages/scaffold/helper/tsdown.config.ts
similarity index 100%
rename from packages/sdk/helper/tsdown.config.ts
rename to packages/scaffold/helper/tsdown.config.ts
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
new file mode 100644
index 0000000000..df0623573b
--- /dev/null
+++ b/packages/scaffold/protocol/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/scaffold/protocol/README.md
+README.md: dc42f385f6e7fd6327ca79887d3cf22d7c34ccdf
+README.zh.md: a292120be8b5b09aaadb05f9dbc272a51bd74831
diff --git a/packages/sdk/sdk-protocol/README.md b/packages/scaffold/protocol/README.md
similarity index 90%
rename from packages/sdk/sdk-protocol/README.md
rename to packages/scaffold/protocol/README.md
index 2d141e6f62..b8420eb19a 100644
--- a/packages/sdk/sdk-protocol/README.md
+++ b/packages/scaffold/protocol/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) plugin; clients are [`dsh-sdk-client`](../sdk-client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
+The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../../scaffold/server/README.md) plugin; clients are [`dsh-sdk-client`](../client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
 
 ## Transport
 
@@ -26,7 +26,7 @@ The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delim
 
 ## Model Experience
 
-None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) entry.
+None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../scaffold/server/README.md) entry.
 
 #### KV Cache effect
 
@@ -35,5 +35,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No protocol-version negotiation** — the handshake carries only `serverInfo.version` (`0.0.1`, unvalidated by clients); pre-release stance, no compatibility promise.
-- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../ui/jsonrpc/README.md).
+- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../scaffold/server/README.md).
 - **Server→client requests are dead capability** — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.
diff --git a/packages/sdk/sdk-protocol/README.zh.md b/packages/scaffold/protocol/README.zh.md
similarity index 100%
rename from packages/sdk/sdk-protocol/README.zh.md
rename to packages/scaffold/protocol/README.zh.md
diff --git a/packages/sdk/sdk-protocol/package.json b/packages/scaffold/protocol/package.json
similarity index 100%
rename from packages/sdk/sdk-protocol/package.json
rename to packages/scaffold/protocol/package.json
diff --git a/packages/sdk/sdk-protocol/src/index.ts b/packages/scaffold/protocol/src/index.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/index.ts
rename to packages/scaffold/protocol/src/index.ts
diff --git a/packages/sdk/sdk-protocol/src/invariant.ts b/packages/scaffold/protocol/src/invariant.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/invariant.ts
rename to packages/scaffold/protocol/src/invariant.ts
diff --git a/packages/sdk/sdk-protocol/src/transport.ts b/packages/scaffold/protocol/src/transport.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/transport.ts
rename to packages/scaffold/protocol/src/transport.ts
diff --git a/packages/sdk/sdk-protocol/src/types.ts b/packages/scaffold/protocol/src/types.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/types.ts
rename to packages/scaffold/protocol/src/types.ts
diff --git a/packages/sdk/sdk-protocol/tests/transport.spec.ts b/packages/scaffold/protocol/tests/transport.spec.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/tests/transport.spec.ts
rename to packages/scaffold/protocol/tests/transport.spec.ts
diff --git a/packages/sdk/sdk-protocol/tsconfig.json b/packages/scaffold/protocol/tsconfig.json
similarity index 100%
rename from packages/sdk/sdk-protocol/tsconfig.json
rename to packages/scaffold/protocol/tsconfig.json
diff --git a/packages/sdk/scripts/README.i18n.yaml b/packages/scaffold/scripts/README.i18n.yaml
similarity index 80%
rename from packages/sdk/scripts/README.i18n.yaml
rename to packages/scaffold/scripts/README.i18n.yaml
index b148eb76ab..db65cb315f 100644
--- a/packages/sdk/scripts/README.i18n.yaml
+++ b/packages/scaffold/scripts/README.i18n.yaml
@@ -1,6 +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/sdk/scripts/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/scripts/README.md
 README.md: 9a696bf5a4de9a80f0741f07a7e753733bc2f998
 README.zh.md: cf9fc2cbbe467eb86e89d9eb77e9bc34860b5a3a
diff --git a/packages/sdk/scripts/README.md b/packages/scaffold/scripts/README.md
similarity index 100%
rename from packages/sdk/scripts/README.md
rename to packages/scaffold/scripts/README.md
diff --git a/packages/sdk/scripts/README.zh.md b/packages/scaffold/scripts/README.zh.md
similarity index 100%
rename from packages/sdk/scripts/README.zh.md
rename to packages/scaffold/scripts/README.zh.md
diff --git a/packages/sdk/scripts/package.json b/packages/scaffold/scripts/package.json
similarity index 100%
rename from packages/sdk/scripts/package.json
rename to packages/scaffold/scripts/package.json
diff --git a/packages/sdk/scripts/src/args.ts b/packages/scaffold/scripts/src/args.ts
similarity index 100%
rename from packages/sdk/scripts/src/args.ts
rename to packages/scaffold/scripts/src/args.ts
diff --git a/packages/sdk/scripts/src/bin.ts b/packages/scaffold/scripts/src/bin.ts
similarity index 100%
rename from packages/sdk/scripts/src/bin.ts
rename to packages/scaffold/scripts/src/bin.ts
diff --git a/packages/sdk/scripts/src/build.ts b/packages/scaffold/scripts/src/build.ts
similarity index 100%
rename from packages/sdk/scripts/src/build.ts
rename to packages/scaffold/scripts/src/build.ts
diff --git a/packages/sdk/scripts/src/command.ts b/packages/scaffold/scripts/src/command.ts
similarity index 100%
rename from packages/sdk/scripts/src/command.ts
rename to packages/scaffold/scripts/src/command.ts
diff --git a/packages/sdk/scripts/src/config.ts b/packages/scaffold/scripts/src/config.ts
similarity index 100%
rename from packages/sdk/scripts/src/config.ts
rename to packages/scaffold/scripts/src/config.ts
diff --git a/packages/sdk/scripts/src/config/config-workflow.ts b/packages/scaffold/scripts/src/config/config-workflow.ts
similarity index 100%
rename from packages/sdk/scripts/src/config/config-workflow.ts
rename to packages/scaffold/scripts/src/config/config-workflow.ts
diff --git a/packages/sdk/scripts/src/create-plugin.ts b/packages/scaffold/scripts/src/create-plugin.ts
similarity index 100%
rename from packages/sdk/scripts/src/create-plugin.ts
rename to packages/scaffold/scripts/src/create-plugin.ts
diff --git a/packages/sdk/scripts/src/dev/tsdown-config.ts b/packages/scaffold/scripts/src/dev/tsdown-config.ts
similarity index 100%
rename from packages/sdk/scripts/src/dev/tsdown-config.ts
rename to packages/scaffold/scripts/src/dev/tsdown-config.ts
diff --git a/packages/scaffold/scripts/src/index.ts b/packages/scaffold/scripts/src/index.ts
new file mode 100644
index 0000000000..0af3ef0b30
--- /dev/null
+++ b/packages/scaffold/scripts/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Public DeepSeek Harness SDK runtime entry points.
+ *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-scripts` before the first tagged release —
+ * the current name is indefensibly generic as a published name
+ * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
+ * @module @deepseek-ai/dsh-scripts
+ */
+
+export { runSDK, startSDK, type SdkBootContext } from './runtime.ts'
diff --git a/packages/sdk/scripts/src/invariant.ts b/packages/scaffold/scripts/src/invariant.ts
similarity index 100%
rename from packages/sdk/scripts/src/invariant.ts
rename to packages/scaffold/scripts/src/invariant.ts
diff --git a/packages/sdk/scripts/src/local-plugin-loader-hooks.ts b/packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
similarity index 100%
rename from packages/sdk/scripts/src/local-plugin-loader-hooks.ts
rename to packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
diff --git a/packages/sdk/scripts/src/runtime.ts b/packages/scaffold/scripts/src/runtime.ts
similarity index 100%
rename from packages/sdk/scripts/src/runtime.ts
rename to packages/scaffold/scripts/src/runtime.ts
diff --git a/packages/sdk/scripts/src/telemetry.ts b/packages/scaffold/scripts/src/telemetry.ts
similarity index 100%
rename from packages/sdk/scripts/src/telemetry.ts
rename to packages/scaffold/scripts/src/telemetry.ts
diff --git a/packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl b/packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
similarity index 100%
rename from packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl
rename to packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
diff --git a/packages/sdk/scripts/src/templates/assets/usage.txt.tpl b/packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
similarity index 100%
rename from packages/sdk/scripts/src/templates/assets/usage.txt.tpl
rename to packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
diff --git a/packages/sdk/scripts/src/templates/dsh-sdk-templates.ts b/packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
similarity index 100%
rename from packages/sdk/scripts/src/templates/dsh-sdk-templates.ts
rename to packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
diff --git a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap b/packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
similarity index 100%
rename from packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
rename to packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
diff --git a/packages/sdk/scripts/tests/config.snapshot.ts b/packages/scaffold/scripts/tests/config.snapshot.ts
similarity index 100%
rename from packages/sdk/scripts/tests/config.snapshot.ts
rename to packages/scaffold/scripts/tests/config.snapshot.ts
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/scaffold/scripts/tests/scripts.spec.ts
similarity index 100%
rename from packages/sdk/scripts/tests/scripts.spec.ts
rename to packages/scaffold/scripts/tests/scripts.spec.ts
diff --git a/packages/sdk/scripts/tsconfig.json b/packages/scaffold/scripts/tsconfig.json
similarity index 88%
rename from packages/sdk/scripts/tsconfig.json
rename to packages/scaffold/scripts/tsconfig.json
index d3dacea10b..2230a377ab 100644
--- a/packages/sdk/scripts/tsconfig.json
+++ b/packages/scaffold/scripts/tsconfig.json
@@ -8,7 +8,7 @@
   "references": [
     { "path": "../helper" },
     { "path": "../telemetry" },
-    { "path": "../../ui/app-boot" },
+    { "path": "../../boot/app-boot" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../support/invariants" }
   ]
diff --git a/packages/sdk/scripts/tsdown.config.ts b/packages/scaffold/scripts/tsdown.config.ts
similarity index 100%
rename from packages/sdk/scripts/tsdown.config.ts
rename to packages/scaffold/scripts/tsdown.config.ts
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
new file mode 100644
index 0000000000..0672ad22a6
--- /dev/null
+++ b/packages/scaffold/server/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/scaffold/server/README.md
+README.md: 7ada4fbe6a53e90fcd45c20d9472cb87dbf6b4cf
+README.zh.md: b8362f7762b963ed6caff1b2ba87421152ecb483
diff --git a/packages/ui/jsonrpc/README.md b/packages/scaffold/server/README.md
similarity index 95%
rename from packages/ui/jsonrpc/README.md
rename to packages/scaffold/server/README.md
index 9cd4876b52..0afb3a38ec 100644
--- a/packages/ui/jsonrpc/README.md
+++ b/packages/scaffold/server/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; the transport and the named wire types live in [`dsh-sdk-protocol`](../../sdk/sdk-protocol/README.md), shared with the client SDKs; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
+The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; the transport and the named wire types live in [`dsh-sdk-protocol`](../../scaffold/protocol/README.md), shared with the client SDKs; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
 
 ## Wiring
 
diff --git a/packages/ui/jsonrpc/README.zh.md b/packages/scaffold/server/README.zh.md
similarity index 95%
rename from packages/ui/jsonrpc/README.zh.md
rename to packages/scaffold/server/README.zh.md
index a2b979da44..5305434abb 100644
--- a/packages/ui/jsonrpc/README.zh.md
+++ b/packages/scaffold/server/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../../sdk/sdk-protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
+`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../../scaffold/protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
 
 ## 组装
 
diff --git a/packages/ui/jsonrpc/package.json b/packages/scaffold/server/package.json
similarity index 100%
rename from packages/ui/jsonrpc/package.json
rename to packages/scaffold/server/package.json
diff --git a/packages/ui/jsonrpc/src/index.ts b/packages/scaffold/server/src/index.ts
similarity index 92%
rename from packages/ui/jsonrpc/src/index.ts
rename to packages/scaffold/server/src/index.ts
index 423f338877..9985cadfb4 100644
--- a/packages/ui/jsonrpc/src/index.ts
+++ b/packages/scaffold/server/src/index.ts
@@ -6,6 +6,10 @@
  * owns EOF and signal exits. Keep named plugin exports with no default export so
  * Loader `unwrapExports` preserves `name`, `inject`, `Config`, and `apply`.
  *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-server` before the first tagged release —
+ * the current name says the wire encoding, not the role; it is the server half of
+ * the SDK protocol ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-jsonrpc
  */
 
diff --git a/packages/ui/jsonrpc/src/invariant.ts b/packages/scaffold/server/src/invariant.ts
similarity index 100%
rename from packages/ui/jsonrpc/src/invariant.ts
rename to packages/scaffold/server/src/invariant.ts
diff --git a/packages/ui/jsonrpc/src/server.ts b/packages/scaffold/server/src/server.ts
similarity index 100%
rename from packages/ui/jsonrpc/src/server.ts
rename to packages/scaffold/server/src/server.ts
diff --git a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts b/packages/scaffold/server/tests/built-scope-carrier.e2e.ts
similarity index 98%
rename from packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
rename to packages/scaffold/server/tests/built-scope-carrier.e2e.ts
index 1de16660a8..b3519110b5 100644
--- a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
+++ b/packages/scaffold/server/tests/built-scope-carrier.e2e.ts
@@ -36,7 +36,7 @@ const [
   load("packages/examples/agent-spine-demo/lib/index.js"),
   load("packages/subagent/subagent/lib/index.js"),
   load("packages/session/session-persistence-jsonl/lib/index.js"),
-  load("packages/ui/jsonrpc/lib/index.js"),
+  load("packages/scaffold/server/lib/index.js"),
   load("packages/core/session/lib/index.js"),
 ]);
 
diff --git a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts b/packages/scaffold/server/tests/plugin-apply.spec.ts
similarity index 100%
rename from packages/ui/jsonrpc/tests/plugin-apply.spec.ts
rename to packages/scaffold/server/tests/plugin-apply.spec.ts
diff --git a/packages/ui/jsonrpc/tests/plugin-shape.spec.ts b/packages/scaffold/server/tests/plugin-shape.spec.ts
similarity index 100%
rename from packages/ui/jsonrpc/tests/plugin-shape.spec.ts
rename to packages/scaffold/server/tests/plugin-shape.spec.ts
diff --git a/packages/ui/jsonrpc/tests/server.spec.ts b/packages/scaffold/server/tests/server.spec.ts
similarity index 100%
rename from packages/ui/jsonrpc/tests/server.spec.ts
rename to packages/scaffold/server/tests/server.spec.ts
diff --git a/packages/ui/jsonrpc/tsconfig.json b/packages/scaffold/server/tsconfig.json
similarity index 93%
rename from packages/ui/jsonrpc/tsconfig.json
rename to packages/scaffold/server/tsconfig.json
index 00ac7000e6..56419b6b84 100644
--- a/packages/ui/jsonrpc/tsconfig.json
+++ b/packages/scaffold/server/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../sdk/sdk-protocol"
+      "path": "../protocol"
     },
     {
       "path": "../../subagent/subagent"
diff --git a/packages/sdk/telemetry/README.i18n.yaml b/packages/scaffold/telemetry/README.i18n.yaml
similarity index 80%
rename from packages/sdk/telemetry/README.i18n.yaml
rename to packages/scaffold/telemetry/README.i18n.yaml
index 1604b40bf4..4d70fce157 100644
--- a/packages/sdk/telemetry/README.i18n.yaml
+++ b/packages/scaffold/telemetry/README.i18n.yaml
@@ -1,6 +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/sdk/telemetry/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/telemetry/README.md
 README.md: c87735a93e7659f2913f4dd325176a8ae40cf29b
 README.zh.md: 24d6e72d988f94cdbc6aa01607edbfc105213267
diff --git a/packages/sdk/telemetry/README.md b/packages/scaffold/telemetry/README.md
similarity index 100%
rename from packages/sdk/telemetry/README.md
rename to packages/scaffold/telemetry/README.md
diff --git a/packages/sdk/telemetry/README.zh.md b/packages/scaffold/telemetry/README.zh.md
similarity index 100%
rename from packages/sdk/telemetry/README.zh.md
rename to packages/scaffold/telemetry/README.zh.md
diff --git a/packages/sdk/telemetry/package.json b/packages/scaffold/telemetry/package.json
similarity index 100%
rename from packages/sdk/telemetry/package.json
rename to packages/scaffold/telemetry/package.json
diff --git a/packages/sdk/telemetry/src/anonymous-id.ts b/packages/scaffold/telemetry/src/anonymous-id.ts
similarity index 100%
rename from packages/sdk/telemetry/src/anonymous-id.ts
rename to packages/scaffold/telemetry/src/anonymous-id.ts
diff --git a/packages/sdk/telemetry/src/consent-resolver.ts b/packages/scaffold/telemetry/src/consent-resolver.ts
similarity index 100%
rename from packages/sdk/telemetry/src/consent-resolver.ts
rename to packages/scaffold/telemetry/src/consent-resolver.ts
diff --git a/packages/sdk/telemetry/src/index.ts b/packages/scaffold/telemetry/src/index.ts
similarity index 82%
rename from packages/sdk/telemetry/src/index.ts
rename to packages/scaffold/telemetry/src/index.ts
index 107956fa39..17ea1d02c7 100644
--- a/packages/sdk/telemetry/src/index.ts
+++ b/packages/scaffold/telemetry/src/index.ts
@@ -7,6 +7,10 @@
  * the launcher command dispatch and the helper feature catalog lives outside
  * this package.
  *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-telemetry` before the first tagged release —
+ * the current name collides with the `dsh-session-telemetry` family; this is
+ * launcher-side SDK telemetry ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-telemetry
  */
 
diff --git a/packages/sdk/telemetry/src/invariant.ts b/packages/scaffold/telemetry/src/invariant.ts
similarity index 100%
rename from packages/sdk/telemetry/src/invariant.ts
rename to packages/scaffold/telemetry/src/invariant.ts
diff --git a/packages/sdk/telemetry/src/payload.ts b/packages/scaffold/telemetry/src/payload.ts
similarity index 100%
rename from packages/sdk/telemetry/src/payload.ts
rename to packages/scaffold/telemetry/src/payload.ts
diff --git a/packages/sdk/telemetry/src/reporter.ts b/packages/scaffold/telemetry/src/reporter.ts
similarity index 100%
rename from packages/sdk/telemetry/src/reporter.ts
rename to packages/scaffold/telemetry/src/reporter.ts
diff --git a/packages/sdk/telemetry/src/secret-redactor.ts b/packages/scaffold/telemetry/src/secret-redactor.ts
similarity index 100%
rename from packages/sdk/telemetry/src/secret-redactor.ts
rename to packages/scaffold/telemetry/src/secret-redactor.ts
diff --git a/packages/sdk/telemetry/tests/anonymous-id.spec.ts b/packages/scaffold/telemetry/tests/anonymous-id.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/anonymous-id.spec.ts
rename to packages/scaffold/telemetry/tests/anonymous-id.spec.ts
diff --git a/packages/sdk/telemetry/tests/consent-resolver.spec.ts b/packages/scaffold/telemetry/tests/consent-resolver.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/consent-resolver.spec.ts
rename to packages/scaffold/telemetry/tests/consent-resolver.spec.ts
diff --git a/packages/sdk/telemetry/tests/payload.spec.ts b/packages/scaffold/telemetry/tests/payload.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/payload.spec.ts
rename to packages/scaffold/telemetry/tests/payload.spec.ts
diff --git a/packages/sdk/telemetry/tests/reporter.spec.ts b/packages/scaffold/telemetry/tests/reporter.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/reporter.spec.ts
rename to packages/scaffold/telemetry/tests/reporter.spec.ts
diff --git a/packages/sdk/telemetry/tests/secret-redactor.spec.ts b/packages/scaffold/telemetry/tests/secret-redactor.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/secret-redactor.spec.ts
rename to packages/scaffold/telemetry/tests/secret-redactor.spec.ts
diff --git a/packages/sdk/telemetry/tsconfig.json b/packages/scaffold/telemetry/tsconfig.json
similarity index 100%
rename from packages/sdk/telemetry/tsconfig.json
rename to packages/scaffold/telemetry/tsconfig.json
diff --git a/packages/sdk/README.zh.md b/packages/sdk/README.zh.md
deleted file mode 100644
index 003383c5f6..0000000000
--- a/packages/sdk/README.zh.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# SDK 包
-
-[English](README.md) | 中文
-
-本分组包含 Harness 项目的开发者工具，以及从另一个进程驱动 Harness 运行时的客户端栈。
-
-| 包 | 职责 |
-|---|---|
-| [`helper/`](helper/README.md) | 提供共享的项目编辑领域 |
-| [`scripts/`](scripts/README.md) | 提供 `dsh-sdk` 项目命令 |
-| [`create-sdk/`](create-sdk/README.md) | 创建新的 SDK 项目 |
-| [`sdk-protocol/`](sdk-protocol/README.md) | 定义 SDK 运行时协议格式 |
-| [`sdk-client/`](sdk-client/README.md) | 通过 TypeScript 客户端 API 驱动 Harness 运行时 |
-| [`telemetry/`](telemetry/README.md) | 提供启动器遥测、同意和脱敏原语 |
-
-`@deepseek-ai/create-sdk` 遵循 npm 的 scoped initializer 命名约定；其他包遵循仓库的 `@deepseek-ai/dsh-*` 约定。参见[开发者项目工作流](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)、[项目编辑架构](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)和 [TypeScript SDK 设计](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)。
diff --git a/packages/sdk/scripts/src/index.ts b/packages/sdk/scripts/src/index.ts
deleted file mode 100644
index 5180f885c8..0000000000
--- a/packages/sdk/scripts/src/index.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-/**
- * Public DeepSeek Harness SDK runtime entry points.
- *
- * @module @deepseek-ai/dsh-scripts
- */
-
-export { runSDK, startSDK, type SdkBootContext } from './runtime.ts'
diff --git a/packages/sdk/sdk-protocol/README.i18n.yaml b/packages/sdk/sdk-protocol/README.i18n.yaml
deleted file mode 100644
index f878b9fd63..0000000000
--- a/packages/sdk/sdk-protocol/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/sdk/sdk-protocol/README.md
-README.md: 2d141e6f62ac0d324933996c282a2d0380af29f2
-README.zh.md: bc459f8817c9477a451015f7629168e246ee531c
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 3598c77d31..246d702892 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-dsh-sdk/README.md
-README.md: c0e2f4e9ece366e28492e32d97afa533fd948141
-README.zh.md: 4cf6c58fff44b1c11cf0a6c321da2c02d52bb8c9
+README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
+README.zh.md: ffb1b8f4cddca4566a20593bdac54801ad8db38f
diff --git a/packages/subagent/subagent-dsh-sdk/README.md b/packages/subagent/subagent-dsh-sdk/README.md
index c0e2f4e9ec..0bbcfa105e 100644
--- a/packages/subagent/subagent-dsh-sdk/README.md
+++ b/packages/subagent/subagent-dsh-sdk/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../sdk/sdk-client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
+The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../scaffold/client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
 
 ## Start and ownership
 
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index 4cf6c58fff..ffb1b8f4cd 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../sdk/sdk-client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程契约：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程契约：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
 
 ## 启动与所有权
 
diff --git a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
index 5603e0e9a0..e42a76c90c 100644
--- a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
+++ b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
@@ -24,7 +24,7 @@ import {
   type SdkRunSpec,
 } from '../src/run.ts'
 
-const fakeRuntime = fileURLToPath(new URL('../../../sdk/sdk-client/tests/fake-runtime.ts', import.meta.url))
+const fakeRuntime = fileURLToPath(new URL('../../../scaffold/client/tests/fake-runtime.ts', import.meta.url))
 
 /** A parent Agent stub. The SDK backend reads exactly one thing off it: the session header's cwd (the workspace its child inherits). */
 const fakeParent = { id: 'parent', session: { header: { cwd: process.cwd() } } } as unknown as Agent
diff --git a/packages/subagent/subagent-dsh-sdk/tsconfig.json b/packages/subagent/subagent-dsh-sdk/tsconfig.json
index 79ff03f1a4..2b9aa29e21 100644
--- a/packages/subagent/subagent-dsh-sdk/tsconfig.json
+++ b/packages/subagent/subagent-dsh-sdk/tsconfig.json
@@ -27,10 +27,10 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../sdk/sdk-client"
+      "path": "../../scaffold/client"
     },
     {
-      "path": "../../sdk/sdk-protocol"
+      "path": "../../scaffold/protocol"
     },
     {
       "path": "../subagent"
diff --git a/packages/subagent/subagent-inprocess/tsconfig.json b/packages/subagent/subagent-inprocess/tsconfig.json
index 22c00b3a94..23406e362e 100644
--- a/packages/subagent/subagent-inprocess/tsconfig.json
+++ b/packages/subagent/subagent-inprocess/tsconfig.json
@@ -39,7 +39,7 @@
       "path": "../../support/invariants"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     }
   ]
 }
diff --git a/packages/typert/generator/tests/type-model.spec.ts b/packages/typert/generator/tests/type-model.spec.ts
index 40a91e3ef5..e1b5d99de9 100644
--- a/packages/typert/generator/tests/type-model.spec.ts
+++ b/packages/typert/generator/tests/type-model.spec.ts
@@ -419,7 +419,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
 
   it('rejects relative imports across face boundaries', () => {
     const root = copyFixture('typert-relative-face-')
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     const source = readFileSync(sourcePath, 'utf8')
       .replace("from '@fixture/host'", "from '../../host/src/index.ts'")
     writeFileSync(sourcePath, source)
@@ -435,7 +435,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
       join(root, 'packages/host/src/private.ts'),
       'export interface PrivateHost { readonly value: string }\n',
     )
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     const source = readFileSync(sourcePath, 'utf8')
       .replace(
         "import type { HostAgent, Payload } from '@fixture/host'",
@@ -458,7 +458,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
       join(root, 'packages/host/src/private.ts'),
       'export interface PrivateHost { readonly value: string }\n',
     )
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(sourcePath, [
       readFileSync(sourcePath, 'utf8'),
       "export type { PrivateHost } from '@fixture/host/private'",
@@ -472,7 +472,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
 
   it('rejects cross-face namespace re-exports until the model has a namespace target', () => {
     const root = copyFixture('typert-namespace-reexport-')
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(sourcePath, [
       readFileSync(sourcePath, 'utf8'),
       "export type * as HostNamespace from '@fixture/host'",
@@ -487,10 +487,10 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
   it('ignores cross-face namespace exports that are not package exports', () => {
     const root = copyFixture('typert-private-namespace-reexport-')
     writeFileSync(
-      join(root, 'packages/client/src/internal.ts'),
+      join(root, 'packages/client', 'src/internal.ts'),
       "export type * as HiddenHostNamespace from '@fixture/host'\n",
     )
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(sourcePath, [
       "import './internal.ts'",
       readFileSync(sourcePath, 'utf8'),
@@ -503,7 +503,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
 
   it('records public symbols from explicit cross-face star re-exports', () => {
     const root = copyFixture('typert-star-reexport-')
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(
       sourcePath,
       readFileSync(sourcePath, 'utf8')
@@ -1138,7 +1138,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
 
   it('rejects a public Typert subpath that points outside the root-level face artifact', () => {
     const root = copyFixture('typert-artifact-path-')
-    const manifestPath = join(root, 'packages/client/package.json')
+    const manifestPath = join(root, 'packages/client', 'package.json')
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
       exports: Record<string, { types: string; default: string }>
     }
@@ -1154,7 +1154,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
 
   it('rejects absent Typert exports and package file entries', () => {
     const noSubpathRoot = copyFixture('typert-missing-artifact-export-')
-    const noSubpathManifest = join(noSubpathRoot, 'packages/client/package.json')
+    const noSubpathManifest = join(noSubpathRoot, 'packages/client', 'package.json')
     const noSubpath = JSON.parse(readFileSync(noSubpathManifest, 'utf8')) as Record<string, unknown>
     noSubpath.exports = './lib/index.js'
     writeFileSync(noSubpathManifest, `${JSON.stringify(noSubpath, null, 2)}\n`)
@@ -1163,7 +1163,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
     )
 
     const invalidSubpathRoot = copyFixture('typert-invalid-artifact-export-')
-    const invalidSubpathManifest = join(invalidSubpathRoot, 'packages/client/package.json')
+    const invalidSubpathManifest = join(invalidSubpathRoot, 'packages/client', 'package.json')
     const invalidSubpath = JSON.parse(readFileSync(invalidSubpathManifest, 'utf8')) as {
       exports: Record<string, unknown>
     }
@@ -1174,7 +1174,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
     )
 
     const noFilesRoot = copyFixture('typert-missing-artifact-files-')
-    const noFilesManifest = join(noFilesRoot, 'packages/client/package.json')
+    const noFilesManifest = join(noFilesRoot, 'packages/client', 'package.json')
     const noFiles = JSON.parse(readFileSync(noFilesManifest, 'utf8')) as Record<string, unknown>
     delete noFiles.files
     writeFileSync(noFilesManifest, `${JSON.stringify(noFiles, null, 2)}\n`)
diff --git a/packages/ui/jsonrpc/README.i18n.yaml b/packages/ui/jsonrpc/README.i18n.yaml
deleted file mode 100644
index d81f54f405..0000000000
--- a/packages/ui/jsonrpc/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/ui/jsonrpc/README.md
-README.md: 9cd4876b52f9527745b27041eb2555408c73fabd
-README.zh.md: a2b979da448c04c0578382889be2ae3ea6076166
diff --git a/packages/ui/permission/README.i18n.yaml b/packages/ui/permission/README.i18n.yaml
deleted file mode 100644
index cb48934488..0000000000
--- a/packages/ui/permission/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/ui/permission/README.md
-README.md: 4f7f560bb81eaad3b6b95b2742432fa252682d5a
-README.zh.md: d45f89e243ce2d8f6bb08943fb7e776ced106b5a
diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml
deleted file mode 100644
index 1da849ed9b..0000000000
--- a/packages/ui/user-interaction/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/ui/user-interaction/README.md
-README.md: cba015e782623b3a5adf018303823577a0b96774
-README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 2c347613e8..08019b567e 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -275,7 +275,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
   ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session/session-projection/src/index.ts',
   ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session/session-projection/src/index.ts',
-  CommandExecution: 'executor return contract is owned by packages/ui/commands/src/index.ts',
+  CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
   TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
   TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
   TypertPackageFilter: 'registry package query filter is owned by packages/typert/registry/README.md',
@@ -295,10 +295,10 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
   InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
-  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
-  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
-  KnobState: 'projection unit state shape is owned by packages/ui/permission/README.md',
-  PermissionSelect: 'permissions projection payload is owned by packages/ui/permission/src/types.ts',
+  PresetOption: 'deployment menu metadata is owned by packages/interaction/permission/README.md',
+  PresetSpec: 'deployment preset composition is owned by packages/interaction/permission/README.md',
+  KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
+  PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
   ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
   Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts
index 8299114ff5..c9b1f41dbf 100644
--- a/scripts/gen-third-party-notices.spec.ts
+++ b/scripts/gen-third-party-notices.spec.ts
@@ -70,7 +70,7 @@ describe('tierExternalDeps', () => {
   it('keeps a package runtime when any shipping area declares it, and excludes workspace links', () => {
     const { manifests, names } = workspace({
       'package.json': { devDependencies: { shared: '^1' } },
-      'packages/ui/tui/package.json': { name: '@deepseek-ai/dsh-tui', dependencies: { shared: '^1', '@deepseek-ai/dsh-cli': 'workspace:^' } },
+      'packages/interaction/tui/package.json': { name: '@deepseek-ai/dsh-tui', dependencies: { shared: '^1', '@deepseek-ai/dsh-cli': 'workspace:^' } },
       'apps/cli/package.json': { name: '@deepseek-ai/dsh-cli' },
     })
 
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index b59aafe5f0..06475808e1 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -154,7 +154,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
   {
     pkg: '@deepseek-ai/dsh-tool-ask-user',
     dir: 'tool-ask-user',
-    source: 'packages/ui/tool-ask-user/src/index.ts',
+    source: 'packages/interaction/tool-ask-user/src/index.ts',
     requires: ['ctx.tools', 'ctx.userInteraction'],
     writes: ['tool/call', 'tool/result after a UI/provider answers the question'],
     async mount(ctx) {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 258b70f87d..d99889d28b 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -619,7 +619,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'apps/cli/tests/built-bin.e2e.ts',
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
-    'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
+    'packages/scaffold/server/tests/built-scope-carrier.e2e.ts',
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     'packages/api/remotes/tests/built-lib.e2e.ts',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index e4eaf15398..903172e48f 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -234,32 +234,32 @@
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandInputDescriptor",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandDefinition",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandInvocation",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandResult",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandDescriptor",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "ParsedCommand",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/system-prompt.md",
@@ -733,62 +733,62 @@
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionOption",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionIntent",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionItem",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionRequest",
-      "source": "packages/ui/user-interaction/src/index.ts"
+      "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionAnswerItem",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionAnswer",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "UserInteractionProvider",
-      "source": "packages/ui/user-interaction/src/index.ts"
+      "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "UserInteractionError",
-      "source": "packages/ui/user-interaction/src/index.ts"
+      "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalRequestId",
-      "source": "packages/ui/user-approval/src/types.ts"
+      "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalOutcome",
-      "source": "packages/ui/user-approval/src/types.ts"
+      "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalPolicy",
-      "source": "packages/ui/user-approval/src/index.ts"
+      "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalRequest",
-      "source": "packages/ui/user-approval/src/index.ts"
+      "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/bash.md",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 5930d39e26..a0eec4960f 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -103,12 +103,12 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
-  'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
-  'packages/sdk/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
-  'packages/sdk/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
-  'packages/sdk/sdk-client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
-  'packages/sdk/sdk-protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
-  'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
+  'packages/scaffold/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
+  'packages/scaffold/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
+  'packages/scaffold/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
+  'packages/scaffold/client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
+  'packages/scaffold/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
+  'packages/scaffold/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
   'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
   'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
@@ -138,10 +138,10 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
   'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
   'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
-  'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
+  'packages/boot/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
   'packages/examples/jsonrpc-demo': { kind: 'indirect', reason: 'Only the externally configured plugin tree contributes model context.' },
-  'packages/ui/permission': { kind: 'indirect', reason: 'The service writes mechanism events rendered by dsh-user-approval and dsh-tool-bash.' },
-  'packages/ui/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
+  'packages/interaction/permission': { kind: 'indirect', reason: 'The service writes mechanism events rendered by dsh-user-approval and dsh-tool-bash.' },
+  'packages/interaction/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
   'packages/util/timeout': { kind: 'indirect', reason: 'Only timeout consumers render timeout outcomes.' },
   'packages/util/retention': { kind: 'indirect', reason: 'Only retention consumers render retained content and omission metadata.' },
   'packages/util/native-command': { kind: 'none', reason: 'The host-side subprocess runner registers no model surface.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index e09ab93743..b748020e11 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -70,12 +70,13 @@
       "@deepseek-ai/dsh-llm/brand": ["./packages/llm/llm/src/brand.ts"],
       "@deepseek-ai/dsh-llm-retry/types": ["./packages/llm/llm-retry/src/types.ts"],
       "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"],
-      "@deepseek-ai/dsh-commands/brand": ["./packages/ui/commands/src/brand.ts"],
+      "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"],
       "@deepseek-ai/dsh-compact/checkpoint": ["./packages/compact/compact/src/checkpoint.ts"],
       "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"],
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
-      "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"],
-      "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"],
+      "@deepseek-ai/dsh-user-approval/types": ["./packages/interaction/user-approval/src/types.ts"],
+      "@deepseek-ai/dsh-user-interaction/types": ["./packages/interaction/user-interaction/src/types.ts"],
+      "@deepseek-ai/dsh-agent/brand": ["./packages/core/agent/src/brand.ts"],
       "@deepseek-ai/dsh-agent/invariant": ["./packages/core/agent/src/invariant.ts"],
       "@deepseek-ai/dsh-scope/invariant": ["./packages/core/scope/src/invariant.ts"],
       "@deepseek-ai/dsh-agent-loop/invariant": ["./packages/core/agent-loop/src/invariant.ts"],
@@ -113,8 +114,9 @@
         "./packages/acp/*/src/invariant.ts",
         "./packages/storage/*/src/invariant.ts",
         "./packages/workspace/*/src/invariant.ts",
-        "./packages/sdk/*/src/invariant.ts",
-        "./packages/ui/*/src/invariant.ts",
+        "./packages/scaffold/*/src/invariant.ts",
+        "./packages/interaction/*/src/invariant.ts",
+        "./packages/boot/*/src/invariant.ts",
         "./packages/examples/*/src/invariant.ts",
         "./packages/util/*/src/invariant.ts",
         "./packages/mcp/*/src/invariant.ts",
@@ -179,6 +181,12 @@
       "@deepseek-ai/dsh-client-ui-models": ["./packages/client/ui-models/src"],
       "@deepseek-ai/dsh-client-locale": ["./packages/client/locale/src"],
       "@deepseek-ai/dsh-client-web": ["./packages/client/web/src"],
+      // scaffold/ folders are role-named without the sdk- prefix (folder ≠ npm
+      // suffix), so the generic wildcard cannot map these three; the npm-side
+      // renames that restore symmetry are FIXME-tracked in the regrouping note.
+      "@deepseek-ai/dsh-sdk-client": ["./packages/scaffold/client/src"],
+      "@deepseek-ai/dsh-sdk-protocol": ["./packages/scaffold/protocol/src"],
+      "@deepseek-ai/dsh-jsonrpc": ["./packages/scaffold/server/src"],
       "@deepseek-ai/dsh-*": [
         "./packages/core/*/src",
         "./packages/prompt/*/src",
@@ -215,8 +223,9 @@
         "./packages/acp/*/src",
         "./packages/storage/*/src",
         "./packages/workspace/*/src",
-        "./packages/sdk/*/src",
-        "./packages/ui/*/src",
+        "./packages/scaffold/*/src",
+        "./packages/interaction/*/src",
+        "./packages/boot/*/src",
         "./packages/examples/*/src",
         "./packages/util/*/src",
         "./packages/mcp/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 0f44c4b7de..c1cc0705cf 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -138,7 +138,7 @@
     { "path": "./packages/session/session-telemetry-otel" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
-    { "path": "./packages/ui/commands" },
+    { "path": "./packages/interaction/commands" },
     { "path": "./packages/goal/goal" },
     { "path": "./packages/goal/tool-goal" },
     { "path": "./packages/goal/goal-session" },
@@ -147,15 +147,15 @@
     { "path": "./packages/context/time-context" },
     { "path": "./packages/context/tmux-context" },
     { "path": "./packages/context/session-reference" },
-    { "path": "./packages/ui/user-interaction" },
-    { "path": "./packages/ui/user-approval" },
-    { "path": "./packages/ui/permission" },
+    { "path": "./packages/interaction/user-interaction" },
+    { "path": "./packages/interaction/user-approval" },
+    { "path": "./packages/interaction/permission" },
     { "path": "./packages/core/tools" },
     { "path": "./packages/skill/skill" },
     { "path": "./packages/skill/skill-badge" },
     { "path": "./packages/skill/skill-local" },
     { "path": "./packages/skill/tool-skill" },
-    { "path": "./packages/ui/tool-ask-user" },
+    { "path": "./packages/interaction/tool-ask-user" },
     { "path": "./packages/context/workspace-context" },
     { "path": "./packages/core/agent-loop" },
     { "path": "./packages/llm/llm-retry" },
@@ -212,8 +212,8 @@
     { "path": "./packages/bundle/base" },
     { "path": "./packages/bundle/headless" },
     { "path": "./packages/bundle/web-app" },
-    { "path": "./packages/ui/app-boot" },
-    { "path": "./packages/ui/jsonrpc" },
+    { "path": "./packages/boot/app-boot" },
+    { "path": "./packages/scaffold/server" },
     { "path": "./packages/examples/jsonrpc-demo" },
     { "path": "./packages/support/llm-replay" },
     { "path": "./packages/typert/generator" },
@@ -259,12 +259,12 @@
     { "path": "./packages/host/directory-picker-native" },
     { "path": "./packages/host/frontend-static" },
     { "path": "./packages/host/webserver" },
-    { "path": "./packages/sdk/sdk-client" },
-    { "path": "./packages/sdk/helper" },
-    { "path": "./packages/sdk/sdk-protocol" },
-    { "path": "./packages/sdk/scripts" },
-    { "path": "./packages/sdk/create-sdk" },
-    { "path": "./packages/sdk/telemetry" },
+    { "path": "./packages/scaffold/client" },
+    { "path": "./packages/scaffold/helper" },
+    { "path": "./packages/scaffold/protocol" },
+    { "path": "./packages/scaffold/scripts" },
+    { "path": "./packages/scaffold/create-sdk" },
+    { "path": "./packages/scaffold/telemetry" },
     { "path": "./packages/lsp/lsp" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
diff --git a/vendor/README.md b/vendor/README.md
index 4bf1d43f46..02e33ea723 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -37,11 +37,11 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 5. **`schemastery/tsdown.config.ts` and `logger-console/tsdown.config.ts`**: ours, not upstream files — per-package build-shape overrides (dual ESM+CJS output; separate node/browser entries) for the repo-root tsdown build. They read the JS emitted under `lib/types` and then write the publish runtime entries under `lib/`. Like the regenerated tsconfigs, they are not part of the upstream sync surface.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
-8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/ui/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/ui/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
+8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
-12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
+12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
 14. **`include/src/index.ts` `writeTask` type**: widened the optional `writeTask?: NodeJS.Timeout` property to `NodeJS.Timeout | undefined` — the debounced writer assigns `undefined` on flush, which `exactOptionalPropertyTypes` rejects on a plain optional. Type-only; no behavior change.
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 29ad406e75..4456782519 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -32,8 +32,8 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       'packages/subprocess/*',
       'packages/pty/pty-local',
       'packages/sandbox/sandbox-local',
-      'packages/sdk/create-sdk',
-      'packages/sdk/helper',
+      'packages/scaffold/create-sdk',
+      'packages/scaffold/helper',
     ]
   : []
 
@@ -83,7 +83,7 @@ const processBoundTests = [
   'packages/subprocess/subprocess-local/tests/spawn.spec.ts',
   'packages/context/time-context/tests/time-context.spec.ts',
   'packages/llm/llm-pi-ai/tests/adapter.spec.ts',
-  'packages/ui/app-boot/tests/app-boot.spec.ts',
+  'packages/boot/app-boot/tests/app-boot.spec.ts',
   'packages/workflow/workflow-workerthread/tests/session.spec.ts',
 ]
 
@@ -222,8 +222,8 @@ export default defineConfig({
         // Projection/command round: executor lifecycle branches and the
         // registry's drive tails need the same maturing lanes. TODO(gui):
         // cover and remove with the client test lane above.
-        'packages/ui/commands/src/index.ts',
-        'packages/ui/commands/src/invariant.ts',
+        'packages/interaction/commands/src/index.ts',
+        'packages/interaction/commands/src/invariant.ts',
         'packages/session/session-projection/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 049688a0ec..cf9cae0780 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -51,7 +51,7 @@ export default defineConfig({
       ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? ['apps/web/tests/**/*.snapshot.ts'] : []),
       'apps/cli/tests/**/*.snapshot.ts',
       'examples/*/tests/**/*.snapshot.ts',
-      'packages/sdk/*/tests/**/*.snapshot.ts',
+      'packages/scaffold/*/tests/**/*.snapshot.ts',
     ],
     // Replay never writes committed outputs and every scenario owns its
     // mutable runtime state (the subprocess suites use a unique temp dir and

From 2a40cbf8efb0a9e9e3690b8c7ad0eb65a8d319c5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 03:40:42 +0800
Subject: [PATCH 152/262] refactor(packages): merge timeout/ into guard/,
 rename cordis/ to self-modification/

git mv timeout-policy beside repeat-tool-guard (both are loop-hygiene
policies on the tool-execution pipeline, and the timeout/ group name
collided with util/timeout) and tool-cordis into self-modification/
(naming the role the framework name obscured). Merged/renamed group
README triplets, tsconfig globs, generator sources, hierarchy tables,
catalogs, and the timeout-policy design note's group references
follow. Adds the fifth FIXME marker (dsh-timeout-guard, recorded as a
suggestion to settle at resolution time).

guard + self-modification suites: 197 passed.
---
 ...-07-28-dsh-guided-skill-session-commands.i18n.yaml |  6 +++---
 .../2026-07-28-dsh-guided-skill-session-commands.md   |  2 +-
 ...2026-07-28-dsh-guided-skill-session-commands.zh.md |  2 +-
 .../2026-07-07-tool-call-timeout-policy.i18n.yaml     |  4 ++--
 .../2026-07-07-tool-call-timeout-policy.md            |  4 ++--
 .../2026-07-07-tool-call-timeout-policy.zh.md         |  4 ++--
 ...2026-07-19-cooperative-tool-cancellation.i18n.yaml |  4 ++--
 .../2026-07-19-cooperative-tool-cancellation.md       |  2 +-
 .../2026-07-19-cooperative-tool-cancellation.zh.md    |  2 +-
 ...-package-manager-native-repository-cache.i18n.yaml |  4 ++--
 ...6-07-30-package-manager-native-repository-cache.md |  2 +-
 ...7-30-package-manager-native-repository-cache.zh.md |  2 +-
 ...26-07-08-self-referential-cordis-toolset.i18n.yaml |  4 ++--
 .../2026-07-08-self-referential-cordis-toolset.md     |  2 +-
 .../2026-07-08-self-referential-cordis-toolset.zh.md  |  2 +-
 ...2026-07-31-even-out-shipped-tool-rosters.i18n.yaml |  4 ++--
 .../2026-07-31-even-out-shipped-tool-rosters.md       |  2 +-
 .../2026-07-31-even-out-shipped-tool-rosters.zh.md    |  2 +-
 .../2026-07-29-shared-base-config-overlays.i18n.yaml  |  4 ++--
 .../2026-07-29-shared-base-config-overlays.md         |  4 ++--
 .../2026-07-29-shared-base-config-overlays.zh.md      |  4 ++--
 ...2026-07-04-prune-dead-core-spine-surface.i18n.yaml |  4 ++--
 .../2026-07-04-prune-dead-core-spine-surface.md       |  2 +-
 .../2026-07-04-prune-dead-core-spine-surface.zh.md    |  2 +-
 AGENTS.md                                             |  6 +++---
 README.i18n.yaml                                      |  4 ++--
 README.md                                             |  2 +-
 README.zh.md                                          |  2 +-
 docs/capability-seams.md                              |  2 +-
 docs/tool-catalog.md                                  |  6 +++---
 packages/README.i18n.yaml                             |  4 ++--
 packages/README.md                                    |  5 ++---
 packages/README.zh.md                                 |  5 ++---
 packages/boot/app-boot/src/index.ts                   |  2 +-
 packages/cordis/README.md                             | 10 ----------
 packages/cordis/README.zh.md                          | 10 ----------
 packages/guard/README.i18n.yaml                       |  4 ++--
 packages/guard/README.md                              |  3 ++-
 packages/guard/README.zh.md                           |  3 ++-
 .../timeout-policy/README.i18n.yaml                   |  2 +-
 packages/{timeout => guard}/timeout-policy/README.md  |  0
 .../{timeout => guard}/timeout-policy/README.zh.md    |  0
 .../{timeout => guard}/timeout-policy/package.json    |  0
 .../{timeout => guard}/timeout-policy/src/index.ts    |  6 ++++++
 .../timeout-policy/src/invariant.ts                   |  0
 .../timeout-policy/tests/timeout-policy.spec.ts       |  0
 .../{timeout => guard}/timeout-policy/tsconfig.json   |  0
 packages/interaction/permission/README.i18n.yaml      |  4 ++--
 .../interaction/user-interaction/README.i18n.yaml     |  4 ++--
 packages/scaffold/protocol/README.i18n.yaml           |  4 ++--
 packages/scaffold/server/README.i18n.yaml             |  4 ++--
 .../{cordis => self-modification}/README.i18n.yaml    |  6 +++---
 packages/self-modification/README.md                  | 10 ++++++++++
 packages/self-modification/README.zh.md               | 10 ++++++++++
 .../repository-plugin/README.i18n.yaml                |  2 +-
 .../repository-plugin/README.md                       |  0
 .../repository-plugin/README.zh.md                    |  0
 .../repository-plugin/package.json                    |  0
 .../repository-plugin/src/bin.ts                      |  0
 .../repository-plugin/src/format.ts                   |  0
 .../repository-plugin/src/index.ts                    |  0
 .../repository-plugin/src/invariant.ts                |  0
 .../repository-plugin/src/mcp.ts                      |  0
 .../repository-plugin/src/source.ts                   |  2 +-
 .../repository-plugin/tests/mcp-format.spec.ts        |  0
 .../repository-plugin/tests/repository-plugin.spec.ts |  0
 .../repository-plugin/tsconfig.json                   |  0
 .../repository-plugin/tsdown.config.ts                |  0
 .../tool-cordis/README.i18n.yaml                      |  2 +-
 .../tool-cordis/README.md                             |  0
 .../tool-cordis/README.zh.md                          |  0
 .../tool-cordis/package.json                          |  0
 .../tool-cordis/src/api-catalog.ts                    |  0
 .../tool-cordis/src/fiber-state.ts                    |  0
 .../tool-cordis/src/guard.ts                          |  0
 .../tool-cordis/src/index.ts                          |  0
 .../tool-cordis/src/inspect.ts                        |  0
 .../tool-cordis/src/invariant.ts                      |  0
 .../tool-cordis/src/mount.ts                          |  0
 .../tool-cordis/src/present.ts                        |  0
 .../tool-cordis/src/sandbox.ts                        |  0
 .../tool-cordis/tests/cordis-lifecycle.spec.ts        |  0
 .../tool-cordis/tests/cross-mount.spec.ts             |  0
 .../tool-cordis/tests/helpers.ts                      |  0
 .../tool-cordis/tests/inspect.spec.ts                 |  0
 .../tool-cordis/tests/integration.spec.ts             |  0
 .../tool-cordis/tests/mount.spec.ts                   |  0
 .../tool-cordis/tests/present.spec.ts                 |  0
 .../tool-cordis/tests/sandbox-context.spec.ts         |  0
 .../tool-cordis/tests/tool-cordis.spec.ts             |  0
 .../tool-cordis/tests/unmount-hmr.spec.ts             |  0
 .../tool-cordis/tsconfig.json                         |  0
 packages/timeout/README.i18n.yaml                     |  6 ------
 packages/timeout/README.md                            | 11 -----------
 packages/timeout/README.zh.md                         | 11 -----------
 .../typert/generator/tests/cordis-catalog.spec.ts     |  2 +-
 packages/web/tool-web/README.i18n.yaml                |  4 ++--
 packages/web/tool-web/README.md                       |  4 ++--
 packages/web/tool-web/README.zh.md                    |  4 ++--
 packages/web/tool-web/tsconfig.json                   |  2 +-
 packages/web/web-fetch-local/README.i18n.yaml         |  4 ++--
 packages/web/web-fetch-local/README.md                |  2 +-
 packages/web/web-fetch-local/README.zh.md             |  2 +-
 scripts/gen-cordis-catalog.ts                         |  2 +-
 scripts/gen-tool-catalog.ts                           |  2 +-
 tsconfig.base.json                                    |  6 ++----
 tsconfig.host.json                                    |  6 +++---
 107 files changed, 121 insertions(+), 145 deletions(-)
 delete mode 100644 packages/cordis/README.md
 delete mode 100644 packages/cordis/README.zh.md
 rename packages/{timeout => guard}/timeout-policy/README.i18n.yaml (79%)
 rename packages/{timeout => guard}/timeout-policy/README.md (100%)
 rename packages/{timeout => guard}/timeout-policy/README.zh.md (100%)
 rename packages/{timeout => guard}/timeout-policy/package.json (100%)
 rename packages/{timeout => guard}/timeout-policy/src/index.ts (91%)
 rename packages/{timeout => guard}/timeout-policy/src/invariant.ts (100%)
 rename packages/{timeout => guard}/timeout-policy/tests/timeout-policy.spec.ts (100%)
 rename packages/{timeout => guard}/timeout-policy/tsconfig.json (100%)
 rename packages/{cordis => self-modification}/README.i18n.yaml (55%)
 create mode 100644 packages/self-modification/README.md
 create mode 100644 packages/self-modification/README.zh.md
 rename packages/{cordis => self-modification}/repository-plugin/README.i18n.yaml (77%)
 rename packages/{cordis => self-modification}/repository-plugin/README.md (100%)
 rename packages/{cordis => self-modification}/repository-plugin/README.zh.md (100%)
 rename packages/{cordis => self-modification}/repository-plugin/package.json (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/bin.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/format.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/index.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/invariant.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/mcp.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/source.ts (98%)
 rename packages/{cordis => self-modification}/repository-plugin/tests/mcp-format.spec.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/tests/repository-plugin.spec.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/tsconfig.json (100%)
 rename packages/{cordis => self-modification}/repository-plugin/tsdown.config.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/README.i18n.yaml (78%)
 rename packages/{cordis => self-modification}/tool-cordis/README.md (100%)
 rename packages/{cordis => self-modification}/tool-cordis/README.zh.md (100%)
 rename packages/{cordis => self-modification}/tool-cordis/package.json (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/api-catalog.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/fiber-state.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/guard.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/index.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/inspect.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/invariant.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/mount.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/present.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/sandbox.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/cordis-lifecycle.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/cross-mount.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/helpers.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/inspect.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/integration.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/mount.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/present.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/sandbox-context.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/tool-cordis.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/unmount-hmr.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tsconfig.json (100%)
 delete mode 100644 packages/timeout/README.i18n.yaml
 delete mode 100644 packages/timeout/README.md
 delete mode 100644 packages/timeout/README.zh.md

diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
index 8feded0ad4..a9e56019b3 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
@@ -1,6 +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 .agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md
-2026-07-28-dsh-guided-skill-session-commands.md: 454d090a55db8987f8e4987aba67deff1b21b1a0
-2026-07-28-dsh-guided-skill-session-commands.zh.md: 64dad4e39c6fd3e3341313c3f8dd2b04947695cf
+#   pnpm run verify-translation-pairing --write .agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
+2026-07-28-dsh-guided-skill-session-commands.md: 606513919a927af3bb7e9b74544fd8df9a1682ce
+2026-07-28-dsh-guided-skill-session-commands.zh.md: 39af4a3a554ba3053f25b3d034346d3e1f4ce237
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
index 454d090a55..606513919a 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
@@ -25,7 +25,7 @@ The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED
 
 `apps/cli/tests/args.spec.ts` gains routing for `migrate`/`upgrade` (bare discriminant) and exit-1 for every leaked option on either side of each subcommand.
 
-`packages/ui/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
+`packages/interaction/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
 
 No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery.
 
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
index 64dad4e39c..39af4a3a55 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
@@ -25,7 +25,7 @@ Archived: 2026-08-03
 
 `apps/cli/tests/args.spec.ts` 新增 `migrate`/`upgrade` 的路由（裸判别式），以及每个子命令两侧任一泄漏选项的退出码 1。
 
-`packages/ui/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
+`packages/interaction/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
 
 无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index f51277307f..e400692950 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.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 .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
-2026-07-07-tool-call-timeout-policy.md: 69fd1ee721de69621d3b57c10d960da0651b94dd
-2026-07-07-tool-call-timeout-policy.zh.md: 0b8d07788dce152985e133923bb673f80175e68d
+2026-07-07-tool-call-timeout-policy.md: b85a4d2d60ef60d9f75bd47d4d405aa55c132af6
+2026-07-07-tool-call-timeout-policy.zh.md: e67b9e4223f486208061f3944369cf3ec06fe72d
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index 69fd1ee721..b85a4d2d60 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -40,7 +40,7 @@ That the catch is the base `next` — not something outside the waterfall — is
 
 ### The `timeout-policy` plugin
 
-The plugin is `@deepseek-ai/dsh-timeout-policy`, a zero-config function/namespace plugin (`name` / `inject` / `apply`) in the `packages/timeout/` group. The per-tool budget is DECLARED on the tool, not on this plugin: a `ToolDefinition` carries an optional `timeoutMs`, which the owning tool plugin sets from its own config. `dsh-tool-web`, for example, resolves `fetchTimeoutMs` / `searchTimeoutMs` (default 30000) onto the `web_fetch` / `web_search` definitions:
+The plugin is `@deepseek-ai/dsh-timeout-policy`, a zero-config function/namespace plugin (`name` / `inject` / `apply`) in the `packages/guard/` group (originally its own `timeout/` group). The per-tool budget is DECLARED on the tool, not on this plugin: a `ToolDefinition` carries an optional `timeoutMs`, which the owning tool plugin sets from its own config. `dsh-tool-web`, for example, resolves `fetchTimeoutMs` / `searchTimeoutMs` (default 30000) onto the `web_fetch` / `web_search` definitions:
 
 ```yaml
 - id: timeout-policy
@@ -89,7 +89,7 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit
 
 ## Alternatives considered
 
-**Name the plugin `tool-timeout`.** The literal Agent Note name matched the `gen-tool-catalog` completeness guard's `packages/*/tool-*` glob, which requires every match to register a model-facing tool. This plugin registers none — it is a `tools/execute` wrapper — so a `tool-*` name would either fail `verify-tool-catalog` or force a misleading boot entry. The package is `@deepseek-ai/dsh-timeout-policy` in a new `packages/timeout/` group; the cordis.yml `id` can still be `timeout-policy`.
+**Name the plugin `tool-timeout`.** The literal Agent Note name matched the `gen-tool-catalog` completeness guard's `packages/*/tool-*` glob, which requires every match to register a model-facing tool. This plugin registers none — it is a `tools/execute` wrapper — so a `tool-*` name would either fail `verify-tool-catalog` or force a misleading boot entry. The package is `@deepseek-ai/dsh-timeout-policy` in what was then a new `timeout/` group, since folded into `packages/guard/`; the cordis.yml `id` can still be `timeout-policy`.
 
 **Keep per-tool timeout handling only.** This was the shape for `bash` and `web_fetch`, and it matches Claude Code and Codex for shell commands. It loses for web-style tools because every new timeout-capable tool must choose validation, cap semantics, docs, snapshots, and classification. The plugin centralizes policy and classification while leaving each tool's schema focused on business input.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index 0b8d07788d..e67b9e4223 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -40,7 +40,7 @@ catch 是基础 `next`（而非 waterfall 之外的东西）这一点至关重
 
 ### `timeout-policy` 插件
 
-该插件是 `@deepseek-ai/dsh-timeout-policy`，一个零配置的函数/命名空间插件（`name` / `inject` / `apply`），位于 `packages/timeout/` 组。每个工具的预算声明在工具自身，而非本插件：`ToolDefinition` 携带一个可选的 `timeoutMs`，由拥有该工具的插件从自身配置中设置。例如 `dsh-tool-web` 将 `fetchTimeoutMs` / `searchTimeoutMs`（默认 30000）解析到 `web_fetch` / `web_search` 的定义上：
+该插件是 `@deepseek-ai/dsh-timeout-policy`，一个零配置的函数/命名空间插件（`name` / `inject` / `apply`），位于 `packages/guard/` 组。每个工具的预算声明在工具自身，而非本插件：`ToolDefinition` 携带一个可选的 `timeoutMs`，由拥有该工具的插件从自身配置中设置。例如 `dsh-tool-web` 将 `fetchTimeoutMs` / `searchTimeoutMs`（默认 30000）解析到 `web_fetch` / `web_search` 的定义上：
 
 ```yaml
 - id: timeout-policy
@@ -89,7 +89,7 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 ## 曾考虑的替代方案
 
-**将插件命名为 `tool-timeout`。** 字面的 Agent Note 名称匹配了 `gen-tool-catalog` 完整性守卫的 `packages/*/tool-*` glob，该 glob 要求每个匹配项注册一个面向模型的工具。本插件不注册任何工具——它是一个 `tools/execute` 包装器——因此 `tool-*` 名称要么导致 `verify-tool-catalog` 失败，要么强制产生一个误导性的启动条目。包为 `@deepseek-ai/dsh-timeout-policy`，位于新的 `packages/timeout/` 组；cordis.yml 的 `id` 仍可为 `timeout-policy`。
+**将插件命名为 `tool-timeout`。** 字面的 Agent Note 名称匹配了 `gen-tool-catalog` 完整性守卫的 `packages/*/tool-*` glob，该 glob 要求每个匹配项注册一个面向模型的工具。本插件不注册任何工具——它是一个 `tools/execute` 包装器——因此 `tool-*` 名称要么导致 `verify-tool-catalog` 失败，要么强制产生一个误导性的启动条目。包为 `@deepseek-ai/dsh-timeout-policy`，位于新的 `packages/guard/` 组；cordis.yml 的 `id` 仍可为 `timeout-policy`。
 
 **仅保留逐工具的超时处理。** 这是 `bash` 和 `web_fetch` 的既有形态，也与 Claude Code 和 Codex 对 shell 命令的做法一致。它对 web 类工具不利，因为每个新的支持超时的工具都必须自行选择校验方式、上限语义、文档、快照和分类。插件集中了策略和分类，让每个工具的 schema 专注于业务输入。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index 2f56298d57..82d87580f8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.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 .agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
-2026-07-19-cooperative-tool-cancellation.md: be237f6ca9475699bb4af76896772a1a7409033d
-2026-07-19-cooperative-tool-cancellation.zh.md: dbc74588931a2ae75678b0026df7a8175b0d20b6
+2026-07-19-cooperative-tool-cancellation.md: 4e82452cd6883593d4693766bea803c97fa4c977
+2026-07-19-cooperative-tool-cancellation.zh.md: 1d9fd3dcc8fa65e6f06050be749eec6ac9e996c2
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
index be237f6ca9..4e82452cd6 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
@@ -46,7 +46,7 @@ This decision requires cancellation at the tool invocation seam only. Making sig
 
 ## Verification
 
-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/timeout/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
 
 No registry test can prove that arbitrary third-party same-process code observes the signal or stops in bounded time. Capability tests continue to prove cancellation and quiescence at the boundary that owns each side effect.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index dbc7458893..1d9fd3dcc8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -46,7 +46,7 @@ Status: implemented
 
 ## 验证
 
-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/timeout/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
 
 任何注册表测试都无法证明任意第三方同进程代码会观察信号或在有界时间内停止。各能力的测试仍需在拥有相应副作用的边界证明取消与完全停稳。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index 6c888c7cad..e556108299 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.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 .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
-2026-07-30-package-manager-native-repository-cache.md: f8a6706065a936ca4a9abf2a50d266a60f09b252
-2026-07-30-package-manager-native-repository-cache.zh.md: b1fea3d655f8d7aeb466744dc27bbf4ba69993ec
+2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
+2026-07-30-package-manager-native-repository-cache.zh.md: ac72e5dc4ffa764e1dc430764a6f52fc083d32a4
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
index f8a6706065..0ea145f20a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
@@ -44,4 +44,4 @@ An identical specifier permanently reuses its published entry. The caller change
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` covers same-process single-flight, cross-instance cache reuse, exact-specifier separation, failed-stage cleanup and retry, and boundary validation. Its real local-Git case invokes the bundled pnpm, runs the fixture repository's `prepare` script, and reads the prepared file from the installed cache entry without network access.
+`packages/boot/app-boot/tests/repository-cache.spec.ts` covers same-process single-flight, cross-instance cache reuse, exact-specifier separation, failed-stage cleanup and retry, and boundary validation. Its real local-Git case invokes the bundled pnpm, runs the fixture repository's `prepare` script, and reads the prepared file from the installed cache entry without network access.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index b1fea3d655..ac72e5dc4f 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -44,4 +44,4 @@ Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 覆盖同进程 single-flight、跨实例缓存复用、精确 specifier 隔离、失败暂存清理与重试，以及边界校验。其真实本地 Git 用例会调用随附的 pnpm，运行 fixture（测试前置数据）仓库的 `prepare` 脚本，并在不访问网络的情况下，从已安装缓存项中读取准备后的文件。
+`packages/boot/app-boot/tests/repository-cache.spec.ts` 覆盖同进程 single-flight、跨实例缓存复用、精确 specifier 隔离、失败暂存清理与重试，以及边界校验。其真实本地 Git 用例会调用随附的 pnpm，运行 fixture（测试前置数据）仓库的 `prepare` 脚本，并在不访问网络的情况下，从已安装缓存项中读取准备后的文件。
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 487726c0e3..105a9d3cfd 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: 335d5e808016ebc37c8457c5dcf4d7da9d8b8c93
-2026-07-08-self-referential-cordis-toolset.zh.md: 46d492cd92495a1e4d516db3f82c9e75486bc386
+2026-07-08-self-referential-cordis-toolset.md: 29d331008d4111ae00147f2ddd19a628135339ac
+2026-07-08-self-referential-cordis-toolset.zh.md: 55013b774b4b6b371d9cbe6ac492b4e95500a7ff
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index 335d5e8080..29d331008d 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -12,7 +12,7 @@ First, model-written registration must be validated where it happens: a malforme
 
 ## Decision
 
-The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) and is demoed by `examples/web-cordis`. It gives the model three tools over the live Cordis runtime in the current DSH process: inspect it, mount an in-memory temporary Plugin, and unmount that Plugin to quiescence.
+The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/self-modification/tool-cordis/README.md) and is demoed by `examples/web-cordis`. It gives the model three tools over the live Cordis runtime in the current DSH process: inspect it, mount an in-memory temporary Plugin, and unmount that Plugin to quiescence.
 
 The vm isolates accidental global pollution, and the context façade hides framework internals. Neither restricts the authority of exposed services: a temporary Plugin can call `ctx.bash` with the host executor's privileges and reach the real filesystem and web services. It runs in the shared DSH runtime and may affect other sessions in that process. This is an opt-in development tool with bash-equivalent trust, not a security boundary or product default.
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index 46d492cd92..55013b774b 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) 发布，并由 `examples/web-cordis` 演示。它为模型提供三个工具，用于操作当前 DSH 进程中的活跃 Cordis 运行时：检查该运行时、挂载一个仅存于内存的临时 Plugin，再将该 Plugin 卸载至完全停稳。
+该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/self-modification/tool-cordis/README.md) 发布，并由 `examples/web-cordis` 演示。它为模型提供三个工具，用于操作当前 DSH 进程中的活跃 Cordis 运行时：检查该运行时、挂载一个仅存于内存的临时 Plugin，再将该 Plugin 卸载至完全停稳。
 
 vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节。但二者都不限制已暴露服务的权限：临时 Plugin 可以调用 `ctx.bash` 以宿主执行器的权限运行命令，也能访问真实的文件系统和网络服务。它运行在共享 DSH runtime 中，可能影响同一进程的其他 session。这是一个需要显式启用的开发工具，信任等级与 bash 相当，不是安全边界，也不是产品默认配置。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
index cbe53b9622..d1cef43cc1 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.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 .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
-2026-07-31-even-out-shipped-tool-rosters.md: d12db993654d9f2b41a16a4663dc64aefe8e3a2f
-2026-07-31-even-out-shipped-tool-rosters.zh.md: 8381a457def1a909b300de52dc011e2437c7e9f3
+2026-07-31-even-out-shipped-tool-rosters.md: 0195620055da5e570d2f54792d950a88bab8d652
+2026-07-31-even-out-shipped-tool-rosters.zh.md: cc67f24720f650283daa4ee85a0a1af5358756a8
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
index d12db99365..0195620055 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
@@ -22,7 +22,7 @@ Two rows stay surface-specific. `tmux-context` is TUI-only because a browser sur
 
 Three capabilities stay out on the evidence their own packages record, and are listed here so "we forgot" and "we decided against" stay distinguishable.
 
-**`dsh-tool-cordis`** lets the model write JavaScript and mount it as a temporary plugin. Its README states the limit: "The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node" ([Known limitations](../../../../packages/cordis/tool-cordis/README.md)). The `node:vm` realm lives inside the harness process while `dsh-sandbox-local` confines only the argv it spawns, so on the Web surface both the sandbox and the approval seam are bypassed rather than enforced.
+**`dsh-tool-cordis`** lets the model write JavaScript and mount it as a temporary plugin. Its README states the limit: "The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node" ([Known limitations](../../../../packages/self-modification/tool-cordis/README.md)). The `node:vm` realm lives inside the harness process while `dsh-sandbox-local` confines only the argv it spawns, so on the Web surface both the sandbox and the approval seam are bypassed rather than enforced.
 
 **`dsh-web-fetch-local`** stays unmounted and `dsh-tool-web` keeps `fetch: false`. SSRF protection is deferred in the implementation ([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) validates protocol, credentials, and length only) and the package says so: "this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets" ([README](../../../../packages/web/web-fetch-local/README.md)). The model chooses the target, which includes the harness's own gateway on loopback, private ranges, and cloud metadata endpoints.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
index 8381a457de..cc67f24720 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 有三项能力基于其自身包所记录的证据保持在外,列在这里是为了让「我们忘了」和「我们决定不要」保持可区分。
 
-**`dsh-tool-cordis`** 让模型写一段 JavaScript 并挂成临时插件。它的 README 写明了这个界限:「The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node」([Known limitations](../../../../packages/cordis/tool-cordis/README.md))。`node:vm` 的 realm 就在 harness 进程内,而 `dsh-sandbox-local` 只约束它 spawn 出去的 argv,因此在 Web surface 上,沙箱与批准接缝是被绕过而非被执行。
+**`dsh-tool-cordis`** 让模型写一段 JavaScript 并挂成临时插件。它的 README 写明了这个界限:「The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node」([Known limitations](../../../../packages/self-modification/tool-cordis/README.md))。`node:vm` 的 realm 就在 harness 进程内,而 `dsh-sandbox-local` 只约束它 spawn 出去的 argv,因此在 Web surface 上,沙箱与批准接缝是被绕过而非被执行。
 
 **`dsh-web-fetch-local`** 保持不挂,`dsh-tool-web` 保持 `fetch: false`。SSRF 防护在实现中是 deferred 状态([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) 只校验协议、凭据与长度),包里也直说了:「this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets」([README](../../../../packages/web/web-fetch-local/README.md))。目标由模型选择,其中包括 harness 自己跑在环回地址上的网关、内网段和云元数据端点。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
index ecfb0ca0e8..4396748bc7 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.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 .agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
-2026-07-29-shared-base-config-overlays.md: 9fae9775e0b37acc99ce2eb5fc630e6f4f52bf1d
-2026-07-29-shared-base-config-overlays.zh.md: 20cc3e522c369315a1fafc84778fced0260581d0
+2026-07-29-shared-base-config-overlays.md: b2ca5cc8d3a160dd09550827d5f8148c14048ea4
+2026-07-29-shared-base-config-overlays.zh.md: e14aa87bdd6ed3bd711bb9786220b5baf0566e8e
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
index 9fae9775e0..b2ca5cc8d3 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
@@ -24,7 +24,7 @@ Precedence is list order, last write winning per row: base, then the surface ove
 
 A patch replaces its target row's whole `config` rather than merging, which shapes the split: a row whose value differs per surface lives in the overlays, never in the base, so no row is patched by three layers at once. Session identity therefore cannot ride a config key at all — it moved to `dsh-agent-loop`'s `CONFIGURED_AGENT_IDENTITIES_KEY`, as the launcher-owned identity record documented.
 
-`examples/tui-agent`, `examples/cordis-agent`, `examples/code-mode`, and `packages/examples/tui-demo` are deleted. The TUI tests move to `apps/cli/tests/`, the cordis-toolset e2e to `packages/cordis/tool-cordis/tests/`, and the supported Code Mode demo remains the ACP overlay at `examples/acp-agent/code-mode.cordis.yml`.
+`examples/tui-agent`, `examples/cordis-agent`, `examples/code-mode`, and `packages/examples/tui-demo` are deleted. The TUI tests move to `apps/cli/tests/`, the cordis-toolset e2e to `packages/self-modification/tool-cordis/tests/`, and the supported Code Mode demo remains the ACP overlay at `examples/acp-agent/code-mode.cordis.yml`.
 
 ## Alternatives considered
 
@@ -48,6 +48,6 @@ A patch whose `id` matches no row stays a no-op rather than an error. That is de
 
 Composition is checked by booting each tree through the real Loader and inspecting settled entries, not by reading YAML; both surfaces settle with zero unloaded rows, and Web starts its `httpServer` with sandboxed Bash and filesystem providers. Code Mode remains covered by the ACP overlay and programmatic TUI snapshots rather than a separate shipped TUI application.
 
-All eight terminal snapshot scenarios replay byte-identically after moving, and the 14-case PTY smoke passes, including two cases that assert a personal overlay reaches an **inserted** row — the behavior the vendored `plugin-include` fix enables ([`vendor/README.md`](../../../../vendor/README.md) local modification 8, covered by `packages/ui/app-boot/tests/config-reload.spec.ts`).
+All eight terminal snapshot scenarios replay byte-identically after moving, and the 14-case PTY smoke passes, including two cases that assert a personal overlay reaches an **inserted** row — the behavior the vendored `plugin-include` fix enables ([`vendor/README.md`](../../../../vendor/README.md) local modification 8, covered by `packages/boot/app-boot/tests/config-reload.spec.ts`).
 
 Flattening surfaced three latent defects, each fixed here: the TUI captured the optional `sessionQuery` service once at construction and so could permanently disable `/resume` when it won the mount race; the shipped session-store root silently reverted to a project-local `./.sessions`; and `--config-replace` was dropped by the resume handoff.
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
index 20cc3e522c..e14aa87bdd 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，正如启动器持有身份的记录所述。
 
-`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/cordis/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP overlay。
+`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/self-modification/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP overlay。
 
 ## 备选方案
 
@@ -48,6 +48,6 @@ patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆
 
 组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：两个界面都能稳定完成且没有未加载项；Web 会以沙箱化 Bash 与文件系统提供方启动 `httpServer`。Code Mode 继续由 ACP overlay 与程序化 TUI 快照覆盖，而不再维护独立交付的 TUI 应用。
 
-全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/ui/app-boot/tests/config-reload.spec.ts` 覆盖）。
+全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/boot/app-boot/tests/config-reload.spec.ts` 覆盖）。
 
 平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在 resume 交接中被丢弃。
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
index b7cfbde315..af8cad7d63 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.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 .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
-2026-07-04-prune-dead-core-spine-surface.md: 473f655ab0944b43f9b1193413801eb7a80286d8
-2026-07-04-prune-dead-core-spine-surface.zh.md: 3389c0161efa78252c9810d64f46d0cd8a7a034c
+2026-07-04-prune-dead-core-spine-surface.md: 7ee7ffc6e8c0f3672c98be6e23ef45a1abfc2b4e
+2026-07-04-prune-dead-core-spine-surface.zh.md: b65d607c1736545089c7116f8a14ab6e7510a8e1
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
index 473f655ab0..7ee7ffc6e8 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-04-prune-dead-core-spine-surface.zh.md)
 
 Several package-root exports, result fields, and convenience methods have no production consumer. They survive because tests import internals through public entry points or because a type anticipated a caller that never arrived. Each item is small in isolation, but together they enlarge the SDK contract, generated catalogs, documentation, and regression matrix without enabling a shipped path.
 
-The production corpus is `packages/*/*/src`, example sources/config, and runtime scripts. Tests, package READMEs, and Agent Note prose are evidence of publication but not fixed callers. `cordis_inspect` makes `packages/cordis/tool-cordis/src/api-catalog.ts` model-visible, and `cordis_mount` can invoke injected services through guarded real-service proxies, so catalogued service methods and returned shapes are a genuine dynamic product surface. The table therefore distinguishes absence of a fixed repository caller from unreachability: rows touching catalogued vocabulary intentionally contract what model-written mounts can discover and call, while package-root implementation helpers are not reached through that service façade. Exact-symbol searches produce the following inventory:
+The production corpus is `packages/*/*/src`, example sources/config, and runtime scripts. Tests, package READMEs, and Agent Note prose are evidence of publication but not fixed callers. `cordis_inspect` makes `packages/self-modification/tool-cordis/src/api-catalog.ts` model-visible, and `cordis_mount` can invoke injected services through guarded real-service proxies, so catalogued service methods and returned shapes are a genuine dynamic product surface. The table therefore distinguishes absence of a fixed repository caller from unreachability: rows touching catalogued vocabulary intentionally contract what model-written mounts can discover and call, while package-root implementation helpers are not reached through that service façade. Exact-symbol searches produce the following inventory:
 
 | Surface | Production evidence | Simplification |
 | --- | --- | --- |
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
index 3389c0161e..b65d607c17 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 若干包根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 契约、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
 
-生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note 行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/cordis/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
+生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note 行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/self-modification/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
 
 | 接口 | 生产证据 | 简化方式 |
 | --- | --- | --- |
diff --git a/AGENTS.md b/AGENTS.md
index 7c9b795ddc..35fbc54ca6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,9 +29,9 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
-  plan/        plan mode as logged per-agent collaboration state
-  guard/       loop-hygiene plugins
-  cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
+  plan/        plan mode as logged collaboration state
+  guard/       loop-hygiene plugins + tool-call timeouts
+  self-modification/  the agent inspects/mounts plugins in its runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
   session/     durable session data plane: persistence, projection, titles, reporting
   settings/    user-settings seam + file-backed provider
diff --git a/README.i18n.yaml b/README.i18n.yaml
index c4ad1f0fd9..077f5fa7f2 100644
--- a/README.i18n.yaml
+++ b/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 README.md
-README.md: 64f06c0aec0905fa7deabbec0deea61e1c7a40d4
-README.zh.md: fee03118926028833c828809764ebb5f6375259e
+README.md: ff4cf661a060772973629844d43758d26ac1be02
+README.zh.md: 977de7f22244ff49579393edcce66d02c5782de4
diff --git a/README.md b/README.md
index 64f06c0aec..ff4cf661a0 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ Built-in capabilities cover file reading, editing, and search; shell and persist
 - **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.
 - **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).
 - **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).
-- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).
+- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).
 
 ## Community
 
diff --git a/README.zh.md b/README.zh.md
index fee0311892..977de7f222 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -76,7 +76,7 @@ pnpm run demo:acp
 - **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
 - **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。
 - **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。
-- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。
+- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。
 
 ## 社区
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index c191f6a659..4b46a6566b 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -389,7 +389,7 @@ flowchart LR
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/self-modification/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/interaction/user-interaction) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
 | `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 0cb985d07d..699617eef4 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -280,7 +280,7 @@ Inspect the live Cordis runtime in the current DSH process. Read-only. Sections:
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
 ### `cordis_mount`
 
@@ -301,7 +301,7 @@ Mount a temporary Cordis Plugin in the current DSH process. This creates an in-m
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
 ### `cordis_unmount`
 
@@ -322,7 +322,7 @@ Unmount a current-process temporary Plugin created by cordis_mount. Waits for it
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
 Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes.
 
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 68da8ae611..039e8bb78d 100644
--- 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: 198caca8c8b8231ece4d7160c809ba7b881e775c
-README.zh.md: bf2bf437796d904d135b610ff2c7a2d4d21b0298
+README.md: 7589f37b174b94558bff9f74f860bb4b42705fb8
+README.zh.md: 4e99dd9313cca89e84ae0bfaf4a2179d726da864
diff --git a/packages/README.md b/packages/README.md
index 198caca8c8..7589f37b17 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -34,10 +34,9 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`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 `tools/execute` deadline enforcement | Product — stable surface |
-| [`guard/`](guard/README.md) | Loop-hygiene advisory repeat-call reminders | Product — stable surface |
+| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer | 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 |
+| [`self-modification/`](self-modification/README.md) | The agent modifies its own runtime: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) and 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/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index bf2bf43779..4e99dd9313 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -34,10 +34,9 @@
 | [`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) | 循环卫生建议性重复调用提醒 | 产品：稳定表面 |
+| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
 | [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
-| [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检、临时 Plugin、受限 repository Plugin 加载 | 产品：稳定表面 |
+| [`self-modification/`](self-modification/README.md) | agent 修改自身运行时：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)），以及受限 repository Plugin 加载 | 产品：稳定表面 |
 | [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
 | [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定表面 |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index 5f90a5ee30..dec77aecab 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -641,7 +641,7 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
 
 /**
  * Value mirrors used because Cordis's const enum has no runtime object to import.
- * Keep aligned with `packages/cordis/tool-cordis/src/fiber-state.ts` and
+ * Keep aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts` and
  * `packages/client/web/src/loader-status.ts`.
  */
 const FIBER_PENDING = 0 as FiberState.PENDING
diff --git a/packages/cordis/README.md b/packages/cordis/README.md
deleted file mode 100644
index e8b0790f91..0000000000
--- a/packages/cordis/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# packages/cordis — Cordis runtime integration
-
-English | [中文](README.zh.md)
-
-Plugins that integrate Harness-owned formats with the Cordis runtime: the self-referential model toolset and the restricted repository Plugin runtime.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`tool-cordis/`](tool-cordis/README.md) | Model-facing runtime inspection and temporary-plugin tools | registers on `ctx.tools` |
-| [`repository-plugin/`](repository-plugin/README.md) | Repository skill and MCP composition | registers a Loader builtin |
diff --git a/packages/cordis/README.zh.md b/packages/cordis/README.zh.md
deleted file mode 100644
index c452f9a7ef..0000000000
--- a/packages/cordis/README.zh.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# packages/cordis — Cordis 运行时集成
-
-[English](README.md) | 中文
-
-把 Harness 所有的格式与 Cordis 运行时集成的插件：自指的面向模型工具集，以及受限的 repository Plugin 运行时。
-
-| 包 | 职责 | ctx key |
-|---|---|---|
-| [`tool-cordis/`](tool-cordis/README.md) | 面向模型的运行时检查和临时插件工具 | 注册到 `ctx.tools` |
-| [`repository-plugin/`](repository-plugin/README.md) | repository skill 与 MCP 组合 | 注册一个 Loader builtin |
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index 637a36063e..8251a76ed5 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
-README.md: 8da2f2ddcc1432e7963e600b35549f5e26121af2
-README.zh.md: aa8b5bd1f7d10d90d1dc84d07a7aad81bfb4259c
+README.md: 5791474a2fd6aeda728d4c335c930069ade6e023
+README.zh.md: 82d779d2f1834317672b8fb03f2a4a875bb566fc
diff --git a/packages/guard/README.md b/packages/guard/README.md
index 8da2f2ddcc..5791474a2f 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -2,8 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Behavioral guard plugins watch the agent loop for unproductive patterns and nudge the model back on course. A guard is a self-contained consumer of core seams, not a swappable capability.
+Behavioral guard plugins watch the agent loop for unproductive patterns and enforce per-call budgets. A guard is a self-contained consumer of core seams, not a swappable capability.
 
 | Package | Role | ctx key |
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | Advisory reminders for repeated tool calls | listens on tool and agent events |
+| [`timeout-policy/`](timeout-policy/README.md) | Arms per-call tool deadlines as deployment policy | registers a `tools/execute` listener |
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index aa8b5bd1f7..82d779d2f1 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -2,8 +2,9 @@
 
 [English](README.md) | 中文
 
-行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并推动模型回到正轨。guard 是 core seam 的自包含消费方，而非可替换能力。
+行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是 core seam 的自包含消费方，而非可替换能力。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | 针对重复工具调用的建议性提醒 | 监听工具和 agent 事件 |
+| [`timeout-policy/`](timeout-policy/README.md) | 以部署策略形式设置单次工具调用截止时间 | 注册 `tools/execute` 监听器 |
diff --git a/packages/timeout/timeout-policy/README.i18n.yaml b/packages/guard/timeout-policy/README.i18n.yaml
similarity index 79%
rename from packages/timeout/timeout-policy/README.i18n.yaml
rename to packages/guard/timeout-policy/README.i18n.yaml
index 377d2c528d..3c41810118 100644
--- a/packages/timeout/timeout-policy/README.i18n.yaml
+++ b/packages/guard/timeout-policy/README.i18n.yaml
@@ -1,6 +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/timeout/timeout-policy/README.md
+#   pnpm run verify-translation-pairing --write packages/guard/timeout-policy/README.md
 README.md: 3e5769e2f8b95392e9d489659c6bae634ab3ff18
 README.zh.md: bfba62cdfae8bb956aec43bcf6e8df12407d8ba2
diff --git a/packages/timeout/timeout-policy/README.md b/packages/guard/timeout-policy/README.md
similarity index 100%
rename from packages/timeout/timeout-policy/README.md
rename to packages/guard/timeout-policy/README.md
diff --git a/packages/timeout/timeout-policy/README.zh.md b/packages/guard/timeout-policy/README.zh.md
similarity index 100%
rename from packages/timeout/timeout-policy/README.zh.md
rename to packages/guard/timeout-policy/README.zh.md
diff --git a/packages/timeout/timeout-policy/package.json b/packages/guard/timeout-policy/package.json
similarity index 100%
rename from packages/timeout/timeout-policy/package.json
rename to packages/guard/timeout-policy/package.json
diff --git a/packages/timeout/timeout-policy/src/index.ts b/packages/guard/timeout-policy/src/index.ts
similarity index 91%
rename from packages/timeout/timeout-policy/src/index.ts
rename to packages/guard/timeout-policy/src/index.ts
index 61470ea6af..1c18fa5e13 100644
--- a/packages/timeout/timeout-policy/src/index.ts
+++ b/packages/guard/timeout-policy/src/index.ts
@@ -2,6 +2,12 @@
  * Cooperative tool-call timeout enforcer. A tool declares `timeoutMs` and
  * promises to honor `exec.signal`; this wrapper arms that deadline and maps its
  * own expiry to `TOOL_TIMEOUT` without racing or abandoning the tool promise.
+ *
+ * FIXME: settle the intended `@deepseek-ai/dsh-timeout-guard` rename before the
+ * first tagged release — suggestion only, aligning the name with its `guard/`
+ * home; decide at resolution time
+ * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-timeout-policy
  */
 
diff --git a/packages/timeout/timeout-policy/src/invariant.ts b/packages/guard/timeout-policy/src/invariant.ts
similarity index 100%
rename from packages/timeout/timeout-policy/src/invariant.ts
rename to packages/guard/timeout-policy/src/invariant.ts
diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/guard/timeout-policy/tests/timeout-policy.spec.ts
similarity index 100%
rename from packages/timeout/timeout-policy/tests/timeout-policy.spec.ts
rename to packages/guard/timeout-policy/tests/timeout-policy.spec.ts
diff --git a/packages/timeout/timeout-policy/tsconfig.json b/packages/guard/timeout-policy/tsconfig.json
similarity index 100%
rename from packages/timeout/timeout-policy/tsconfig.json
rename to packages/guard/timeout-policy/tsconfig.json
diff --git a/packages/interaction/permission/README.i18n.yaml b/packages/interaction/permission/README.i18n.yaml
index b5883174dc..34533f9da4 100644
--- a/packages/interaction/permission/README.i18n.yaml
+++ b/packages/interaction/permission/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/interaction/permission/README.md
-README.md: 814085ed6f2c9650854f377e1c97e442fc4211a4
-README.zh.md: 36880d6b8c3f0b39b88db1abb02534f30e3355fa
+README.md: 4f7f560bb81eaad3b6b95b2742432fa252682d5a
+README.zh.md: 79d0ce9c095d3426f3219f04d9cb7ec3b161a184
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index f467aaf4e1..feab1813a7 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
-README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32
-README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79
+README.md: d62e75d110b8be339c5f9449b0834320f695ac99
+README.zh.md: 55258e85e56df2375ed8f195fa0b3b731a9cb816
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
index df0623573b..b77c8fce63 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/scaffold/protocol/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/scaffold/protocol/README.md
-README.md: dc42f385f6e7fd6327ca79887d3cf22d7c34ccdf
-README.zh.md: a292120be8b5b09aaadb05f9dbc272a51bd74831
+README.md: 35b62d2ffc43c54dc81f6a5ecfb1a0ef4294439d
+README.zh.md: a02ba94e7d8fae19bff48d8fda363e23fc173850
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
index 0672ad22a6..46a18ec199 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/scaffold/server/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/scaffold/server/README.md
-README.md: 7ada4fbe6a53e90fcd45c20d9472cb87dbf6b4cf
-README.zh.md: b8362f7762b963ed6caff1b2ba87421152ecb483
+README.md: e0e06e27320ab41f131a1a36a7ccbd26271ce67c
+README.zh.md: ed87a869180571a3cbb51c2ce92a0647e545ca3a
diff --git a/packages/cordis/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
similarity index 55%
rename from packages/cordis/README.i18n.yaml
rename to packages/self-modification/README.i18n.yaml
index 2eacddb52c..9a6a070b95 100644
--- a/packages/cordis/README.i18n.yaml
+++ b/packages/self-modification/README.i18n.yaml
@@ -1,6 +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/cordis/README.md
-README.md: e8b0790f911d1acc1216d412191ca967e0e1ac27
-README.zh.md: c452f9a7ef69e7f5af8900153271d500f19f9e47
+#   pnpm run verify-translation-pairing --write packages/self-modification/README.md
+README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
+README.zh.md: 9874ead263e9860b94992cb176be3c6f8c454ece
diff --git a/packages/self-modification/README.md b/packages/self-modification/README.md
new file mode 100644
index 0000000000..53f700993c
--- /dev/null
+++ b/packages/self-modification/README.md
@@ -0,0 +1,10 @@
+# self-modification/ — the agent modifies its own runtime
+
+English | [中文](README.zh.md)
+
+Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again — plus the restricted repository Plugin runtime. The group is the landing zone for future self-modification packages. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`tool-cordis/`](tool-cordis/README.md) | Model-facing runtime inspection and temporary-plugin tools | registers on `ctx.tools` |
+| [`repository-plugin/`](repository-plugin/README.md) | Repository skill and MCP composition | registers a Loader builtin |
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
new file mode 100644
index 0000000000..9874ead263
--- /dev/null
+++ b/packages/self-modification/README.zh.md
@@ -0,0 +1,10 @@
+# self-modification/：agent 修改自身运行时
+
+[English](README.md) | 中文
+
+这些面向模型的工具作用于 agent（智能体）自身所在的实时 Cordis 运行时，可检查已加载的插件和服务接口、挂载模型编写的插件，并将其 dispose（资源释放）——外加受限 repository Plugin 运行时。该组也是未来自我修改类包的落点。设计说明见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+
+| 包（package） | 角色 | ctx 键 |
+|---|---|---|
+| [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
+| [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
diff --git a/packages/cordis/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
similarity index 77%
rename from packages/cordis/repository-plugin/README.i18n.yaml
rename to packages/self-modification/repository-plugin/README.i18n.yaml
index daf43fa018..e0ce60a641 100644
--- a/packages/cordis/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/README.i18n.yaml
@@ -1,6 +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/cordis/repository-plugin/README.md
+#   pnpm run verify-translation-pairing --write packages/self-modification/repository-plugin/README.md
 README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
 README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b
diff --git a/packages/cordis/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
similarity index 100%
rename from packages/cordis/repository-plugin/README.md
rename to packages/self-modification/repository-plugin/README.md
diff --git a/packages/cordis/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
similarity index 100%
rename from packages/cordis/repository-plugin/README.zh.md
rename to packages/self-modification/repository-plugin/README.zh.md
diff --git a/packages/cordis/repository-plugin/package.json b/packages/self-modification/repository-plugin/package.json
similarity index 100%
rename from packages/cordis/repository-plugin/package.json
rename to packages/self-modification/repository-plugin/package.json
diff --git a/packages/cordis/repository-plugin/src/bin.ts b/packages/self-modification/repository-plugin/src/bin.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/bin.ts
rename to packages/self-modification/repository-plugin/src/bin.ts
diff --git a/packages/cordis/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/format.ts
rename to packages/self-modification/repository-plugin/src/format.ts
diff --git a/packages/cordis/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/index.ts
rename to packages/self-modification/repository-plugin/src/index.ts
diff --git a/packages/cordis/repository-plugin/src/invariant.ts b/packages/self-modification/repository-plugin/src/invariant.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/invariant.ts
rename to packages/self-modification/repository-plugin/src/invariant.ts
diff --git a/packages/cordis/repository-plugin/src/mcp.ts b/packages/self-modification/repository-plugin/src/mcp.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/mcp.ts
rename to packages/self-modification/repository-plugin/src/mcp.ts
diff --git a/packages/cordis/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
similarity index 98%
rename from packages/cordis/repository-plugin/src/source.ts
rename to packages/self-modification/repository-plugin/src/source.ts
index 3ccddc6c52..0befb82e42 100644
--- a/packages/cordis/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -11,7 +11,7 @@ import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { PREPARED_ENTRY_FILENAME } from './format.ts'
 
 // Value mirror: Cordis's const enum has no runtime object to import. Keep
-// aligned with `packages/cordis/tool-cordis/src/fiber-state.ts`.
+// aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts`.
 const FIBER_ACTIVE = 2 as FiberState.ACTIVE
 
 /** Directory under the Harness home containing immutable repository generations. */
diff --git a/packages/cordis/repository-plugin/tests/mcp-format.spec.ts b/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
similarity index 100%
rename from packages/cordis/repository-plugin/tests/mcp-format.spec.ts
rename to packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
diff --git a/packages/cordis/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
similarity index 100%
rename from packages/cordis/repository-plugin/tests/repository-plugin.spec.ts
rename to packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
diff --git a/packages/cordis/repository-plugin/tsconfig.json b/packages/self-modification/repository-plugin/tsconfig.json
similarity index 100%
rename from packages/cordis/repository-plugin/tsconfig.json
rename to packages/self-modification/repository-plugin/tsconfig.json
diff --git a/packages/cordis/repository-plugin/tsdown.config.ts b/packages/self-modification/repository-plugin/tsdown.config.ts
similarity index 100%
rename from packages/cordis/repository-plugin/tsdown.config.ts
rename to packages/self-modification/repository-plugin/tsdown.config.ts
diff --git a/packages/cordis/tool-cordis/README.i18n.yaml b/packages/self-modification/tool-cordis/README.i18n.yaml
similarity index 78%
rename from packages/cordis/tool-cordis/README.i18n.yaml
rename to packages/self-modification/tool-cordis/README.i18n.yaml
index fd2b5443ef..c25dda28e3 100644
--- a/packages/cordis/tool-cordis/README.i18n.yaml
+++ b/packages/self-modification/tool-cordis/README.i18n.yaml
@@ -1,6 +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/cordis/tool-cordis/README.md
+#   pnpm run verify-translation-pairing --write packages/self-modification/tool-cordis/README.md
 README.md: 9986310160c2b56126155a4c3ef84d66018d31c2
 README.zh.md: d955306e1e5d4154f58c771704782ece44a15c99
diff --git a/packages/cordis/tool-cordis/README.md b/packages/self-modification/tool-cordis/README.md
similarity index 100%
rename from packages/cordis/tool-cordis/README.md
rename to packages/self-modification/tool-cordis/README.md
diff --git a/packages/cordis/tool-cordis/README.zh.md b/packages/self-modification/tool-cordis/README.zh.md
similarity index 100%
rename from packages/cordis/tool-cordis/README.zh.md
rename to packages/self-modification/tool-cordis/README.zh.md
diff --git a/packages/cordis/tool-cordis/package.json b/packages/self-modification/tool-cordis/package.json
similarity index 100%
rename from packages/cordis/tool-cordis/package.json
rename to packages/self-modification/tool-cordis/package.json
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/api-catalog.ts
rename to packages/self-modification/tool-cordis/src/api-catalog.ts
diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/self-modification/tool-cordis/src/fiber-state.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/fiber-state.ts
rename to packages/self-modification/tool-cordis/src/fiber-state.ts
diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/self-modification/tool-cordis/src/guard.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/guard.ts
rename to packages/self-modification/tool-cordis/src/guard.ts
diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/self-modification/tool-cordis/src/index.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/index.ts
rename to packages/self-modification/tool-cordis/src/index.ts
diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/self-modification/tool-cordis/src/inspect.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/inspect.ts
rename to packages/self-modification/tool-cordis/src/inspect.ts
diff --git a/packages/cordis/tool-cordis/src/invariant.ts b/packages/self-modification/tool-cordis/src/invariant.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/invariant.ts
rename to packages/self-modification/tool-cordis/src/invariant.ts
diff --git a/packages/cordis/tool-cordis/src/mount.ts b/packages/self-modification/tool-cordis/src/mount.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/mount.ts
rename to packages/self-modification/tool-cordis/src/mount.ts
diff --git a/packages/cordis/tool-cordis/src/present.ts b/packages/self-modification/tool-cordis/src/present.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/present.ts
rename to packages/self-modification/tool-cordis/src/present.ts
diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/self-modification/tool-cordis/src/sandbox.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/sandbox.ts
rename to packages/self-modification/tool-cordis/src/sandbox.ts
diff --git a/packages/cordis/tool-cordis/tests/cordis-lifecycle.spec.ts b/packages/self-modification/tool-cordis/tests/cordis-lifecycle.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/cordis-lifecycle.spec.ts
rename to packages/self-modification/tool-cordis/tests/cordis-lifecycle.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/self-modification/tool-cordis/tests/cross-mount.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/cross-mount.spec.ts
rename to packages/self-modification/tool-cordis/tests/cross-mount.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/helpers.ts b/packages/self-modification/tool-cordis/tests/helpers.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/helpers.ts
rename to packages/self-modification/tool-cordis/tests/helpers.ts
diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/inspect.spec.ts
rename to packages/self-modification/tool-cordis/tests/inspect.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/integration.spec.ts b/packages/self-modification/tool-cordis/tests/integration.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/integration.spec.ts
rename to packages/self-modification/tool-cordis/tests/integration.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/self-modification/tool-cordis/tests/mount.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/mount.spec.ts
rename to packages/self-modification/tool-cordis/tests/mount.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/present.spec.ts b/packages/self-modification/tool-cordis/tests/present.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/present.spec.ts
rename to packages/self-modification/tool-cordis/tests/present.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/self-modification/tool-cordis/tests/sandbox-context.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
rename to packages/self-modification/tool-cordis/tests/sandbox-context.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts b/packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/tool-cordis.spec.ts
rename to packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts b/packages/self-modification/tool-cordis/tests/unmount-hmr.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts
rename to packages/self-modification/tool-cordis/tests/unmount-hmr.spec.ts
diff --git a/packages/cordis/tool-cordis/tsconfig.json b/packages/self-modification/tool-cordis/tsconfig.json
similarity index 100%
rename from packages/cordis/tool-cordis/tsconfig.json
rename to packages/self-modification/tool-cordis/tsconfig.json
diff --git a/packages/timeout/README.i18n.yaml b/packages/timeout/README.i18n.yaml
deleted file mode 100644
index 33a7a5b26d..0000000000
--- a/packages/timeout/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/timeout/README.md
-README.md: d9d8e8a829d8d466d1cc3e42a6c32ac4b3db428b
-README.zh.md: c5920258ade7022fb5b28a351ba060eb56e8bc3c
diff --git a/packages/timeout/README.md b/packages/timeout/README.md
deleted file mode 100644
index d9d8e8a829..0000000000
--- a/packages/timeout/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# timeout/ — tool-call timeout policy
-
-English | [中文](README.zh.md)
-
-This group applies deployment-configured deadlines to model-facing tool calls. Capabilities remain responsible for terminating their own work.
-
-| Package | Role |
-|---|---|
-| [`timeout-policy/`](timeout-policy/README.md) | Enforces configured per-tool call deadlines |
-
-The pure timing primitives live in [`util/timeout`](../util/timeout/README.md). See the [timeout-library decision](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md).
diff --git a/packages/timeout/README.zh.md b/packages/timeout/README.zh.md
deleted file mode 100644
index c5920258ad..0000000000
--- a/packages/timeout/README.zh.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# timeout/：工具调用超时策略
-
-[English](README.md) | 中文
-
-本分组将部署配置的截止时间应用于面向模型的工具调用。各项能力仍负责终止自身工作。
-
-| 包 | 职责 |
-|---|---|
-| [`timeout-policy/`](timeout-policy/README.md) | 强制执行配置的逐工具调用截止时间 |
-
-纯计时原语位于 [`util/timeout`](../util/timeout/README.md)。参见[超时库决策](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)。
diff --git a/packages/typert/generator/tests/cordis-catalog.spec.ts b/packages/typert/generator/tests/cordis-catalog.spec.ts
index 6e6b93dfdc..644bb28de2 100644
--- a/packages/typert/generator/tests/cordis-catalog.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog.spec.ts
@@ -18,7 +18,7 @@ describe('Typert-backed Cordis catalog', () => {
     expect(renderEvents([...model.events], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/events.md'))
     expect(renderServices([...model.services], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/services.md'))
     expect(projector.renderRuntimeApi(model)).toBe(
-      expected('packages/cordis/tool-cordis/src/api-catalog.ts'),
+      expected('packages/self-modification/tool-cordis/src/api-catalog.ts'),
     )
   })
 })
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index eb57a7b20a..4751678c04 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/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/web/tool-web/README.md
-README.md: 791ea87c655444e639ef85ccce737066ead8b749
-README.zh.md: ffcf2d9813dcb94d8106b2c7d5f8ee9fc25e1aaa
+README.md: 646601bb5bd6c27876918b7aca49962ae34bae33
+README.zh.md: 192b7020f5fac026f325448630b2e17d7ce6a0c4
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 791ea87c65..646601bb5b 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and the UI presentation projection — `presentCall`, `presentResult` (a `card: 'web'` result card discriminated by `kind: 'search' | 'fetch'`), and the `output.presentationMeta` that carries the structured search sources or the fetch summary the lossy render text cannot (see the [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)). All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — each tool's cooperative tool-call budget is declared here via config (`fetchTimeoutMs`/`searchTimeoutMs`, attached as `ToolDefinition.timeoutMs`) and enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam.
+The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and the UI presentation projection — `presentCall`, `presentResult` (a `card: 'web'` result card discriminated by `kind: 'search' | 'fetch'`), and the `output.presentationMeta` that carries the structured search sources or the fetch summary the lossy render text cannot (see the [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)). All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — each tool's cooperative tool-call budget is declared here via config (`fetchTimeoutMs`/`searchTimeoutMs`, attached as `ToolDefinition.timeoutMs`) and enforced by [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam.
 
 Each tool is registered independently; a product that wants only one disables the other via config (`{ search: false }` / `{ fetch: false }`). Search guidance mentions `web_fetch` only when fetch is also config-enabled; a search-only composition instead tells the model to use returned snippets and cite their URLs.
 
@@ -28,7 +28,7 @@ The normalized seam results are also the canonical tool values: `WebSearchResult
 | `searchTimeoutMs` | `30000` | Cooperative tool-call timeout budget (ms) for `web_search`. |
 | `fetchMaxOutputChars` | `200000` | Cap on source characters converted synchronously and on one complete `web_fetch` output (header, rendered body, and footer); a cut body gets the truncation notice when it fits. |
 
-`fetchTimeoutMs`/`searchTimeoutMs` declare each tool's cooperative timeout budget (attached as `ToolDefinition.timeoutMs`), enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md); the model-facing schema exposes no timeout argument. `fetchMaxOutputChars` bounds both synchronous conversion work and the complete rendered result: only that many source characters are converted, and the header, converted prefix, and truncation notice are then capped together. The default leaves headroom above the local provider's 100,000-character body cap, but rendered expansion can still make the final bound truncate the result.
+`fetchTimeoutMs`/`searchTimeoutMs` declare each tool's cooperative timeout budget (attached as `ToolDefinition.timeoutMs`), enforced by [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md); the model-facing schema exposes no timeout argument. `fetchMaxOutputChars` bounds both synchronous conversion work and the complete rendered result: only that many source characters are converted, and the header, converted prefix, and truncation notice are then capped together. The default leaves headroom above the local provider's 100,000-character body cap, but rendered expansion can still make the final bound truncate the result.
 
 ```yaml
 - id: tool-web
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index ffcf2d9813..192b7020f5 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向模型的 web 工具套件 `web_search` 与 `web_fetch`，构建于 [web 能力 seam](../web/README.md)（`ctx.web`）之上。它只负责面向模型的事项：工具名称、JSON Schema、snake_case 参数名称、提示词区段、结果数量上限、结果格式、HTML→markdown 呈现，以及 UI 呈现投影——`presentCall`、`presentResult`（以 `kind: 'search' | 'fetch'` 区分的 `card: 'web'` 结果卡片），以及承载有损渲染文本无法携带的结构化搜索来源或抓取摘要的 `output.presentationMeta`（见 [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)）。所有 web 访问都通过 `ctx.web`；该包绝不导入具体提供方。两个工具都不公开面向模型的超时：每个工具的协作式工具调用超时预算通过配置在此声明（`fetchTimeoutMs`／`searchTimeoutMs`，附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md)（`tools/execute` 包装层）强制执行；每个工具只把 `exec.signal` 转发给 seam。
+面向模型的 web 工具套件 `web_search` 与 `web_fetch`，构建于 [web 能力 seam](../web/README.md)（`ctx.web`）之上。它只负责面向模型的事项：工具名称、JSON Schema、snake_case 参数名称、提示词区段、结果数量上限、结果格式、HTML→markdown 呈现，以及 UI 呈现投影——`presentCall`、`presentResult`（以 `kind: 'search' | 'fetch'` 区分的 `card: 'web'` 结果卡片），以及承载有损渲染文本无法携带的结构化搜索来源或抓取摘要的 `output.presentationMeta`（见 [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)）。所有 web 访问都通过 `ctx.web`；该包绝不导入具体提供方。两个工具都不公开面向模型的超时：每个工具的协作式工具调用超时预算通过配置在此声明（`fetchTimeoutMs`／`searchTimeoutMs`，附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md)（`tools/execute` 包装层）强制执行；每个工具只把 `exec.signal` 转发给 seam。
 
 每个工具独立注册；只需要其中一个工具的产品可以通过配置禁用另一个（`{ search: false }`／`{ fetch: false }`）。仅当抓取也通过配置启用时，搜索指引才会提及 `web_fetch`；仅启用搜索的组合则会要求模型使用返回的 snippet 并引用其 URL。
 
@@ -28,7 +28,7 @@
 | `searchTimeoutMs` | `30000` | `web_search` 的协作式工具调用超时预算（ms）。 |
 | `fetchMaxOutputChars` | `200000` | 同步转换的源字符数与单次完整 `web_fetch` 输出的上限（状态头、渲染后的主体与页脚合并计算）；主体被截断时，在能容纳的情况下附带截断提示。 |
 
-`fetchTimeoutMs`／`searchTimeoutMs` 声明每个工具的协作式超时预算（附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) 强制执行；面向模型的 schema 不公开超时参数。`fetchMaxOutputChars` 同时限制同步转换工作量和完整渲染结果：只转换至多该数量的源字符，随后对状态头、转换后的前缀和截断提示合并设限。默认值为本地提供方的 100,000 字符主体上限留出余量，但渲染膨胀仍可能使最终上限截断结果。
+`fetchTimeoutMs`／`searchTimeoutMs` 声明每个工具的协作式超时预算（附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md) 强制执行；面向模型的 schema 不公开超时参数。`fetchMaxOutputChars` 同时限制同步转换工作量和完整渲染结果：只转换至多该数量的源字符，随后对状态头、转换后的前缀和截断提示合并设限。默认值为本地提供方的 100,000 字符主体上限留出余量，但渲染膨胀仍可能使最终上限截断结果。
 
 ```yaml
 - id: tool-web
diff --git a/packages/web/tool-web/tsconfig.json b/packages/web/tool-web/tsconfig.json
index f6684272ce..232d6f6c50 100644
--- a/packages/web/tool-web/tsconfig.json
+++ b/packages/web/tool-web/tsconfig.json
@@ -25,7 +25,7 @@
       "path": "../../core/system-prompt"
     },
     {
-      "path": "../../timeout/timeout-policy"
+      "path": "../../guard/timeout-policy"
     },
     {
       "path": "../web"
diff --git a/packages/web/web-fetch-local/README.i18n.yaml b/packages/web/web-fetch-local/README.i18n.yaml
index 0e487b6ef5..5511f72975 100644
--- a/packages/web/web-fetch-local/README.i18n.yaml
+++ b/packages/web/web-fetch-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/web/web-fetch-local/README.md
-README.md: 8cadba2de7a2708252ebc7143840825fd4fe4549
-README.zh.md: b3f0707c448da7abaaafe2cdcf2520914ffff932
+README.md: 531bfc94a4b2867b1a81d2e0b398ec403186b347
+README.zh.md: 260227679b72ec993dbb9e42a9d2a814bf691e2c
diff --git a/packages/web/web-fetch-local/README.md b/packages/web/web-fetch-local/README.md
index 8cadba2de7..531bfc94a4 100644
--- a/packages/web/web-fetch-local/README.md
+++ b/packages/web/web-fetch-local/README.md
@@ -10,7 +10,7 @@ This is an **implementation** package: it registers a provider into `ctx.web`, i
 
 The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, a resource-backstop timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@deepseek-ai/dsh-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource.
 
-The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-timeout-policy`](../../timeout/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
+The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
 
 A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct seam caller whose provider budget elapsed.
 
diff --git a/packages/web/web-fetch-local/README.zh.md b/packages/web/web-fetch-local/README.zh.md
index b3f0707c44..260227679b 100644
--- a/packages/web/web-fetch-local/README.zh.md
+++ b/packages/web/web-fetch-local/README.zh.md
@@ -10,7 +10,7 @@
 
 提供方拥有**安全资源获取**：URL 验证、HTTP 传输、重定向策略、资源兜底超时、中止传播、字节上限、charset 解码、内容类型分类与二进制拒绝。`@deepseek-ai/dsh-tool-web` 拥有**呈现**（HTML→markdown、截断格式）。非 2xx HTTP 响应是*结果*（状态码 + 解码主体），不是错误；`WebError` 只用于无法安全获取或表示资源的失败。
 
-提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-timeout-policy`](../../timeout/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
+提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-timeout-policy`](../../guard/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
 
 已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接 seam 调用方的提供方预算已经耗尽。
 
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 08019b567e..302ec7fdd9 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -16,7 +16,7 @@ import { renderCordisCoreApiPages } from './cordis-core-api.ts'
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
-const OUT_RUNTIME_API = 'packages/cordis/tool-cordis/src/api-catalog.ts'
+const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
 /** One primary core-data-structures page per project type used by a generated signature. */
 export const LINK_MAP: Readonly<Record<string, string>> = {
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 06475808e1..55ec5eb57f 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -226,7 +226,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
   {
     pkg: '@deepseek-ai/dsh-tool-cordis',
     dir: 'tool-cordis',
-    source: 'packages/cordis/tool-cordis/src/index.ts',
+    source: 'packages/self-modification/tool-cordis/src/index.ts',
     requires: ['ctx.tools'],
     writes: ['tool/call', 'tool/result', 'process-local temporary Plugin lifecycle'],
     async mount(ctx) {
diff --git a/tsconfig.base.json b/tsconfig.base.json
index b748020e11..d8b777a2ad 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -101,10 +101,9 @@
         "./packages/workflow/*/src/invariant.ts",
         "./packages/web/*/src/invariant.ts",
         "./packages/spill/*/src/invariant.ts",
-        "./packages/timeout/*/src/invariant.ts",
         "./packages/todo/*/src/invariant.ts",
         "./packages/bundle/*/src/invariant.ts",
-        "./packages/cordis/*/src/invariant.ts",
+        "./packages/self-modification/*/src/invariant.ts",
         "./packages/sandbox/*/src/invariant.ts",
         "./packages/hooks/*/src/invariant.ts",
         "./packages/session/*/src/invariant.ts",
@@ -210,10 +209,9 @@
         "./packages/workflow/*/src",
         "./packages/web/*/src",
         "./packages/spill/*/src",
-        "./packages/timeout/*/src",
         "./packages/todo/*/src",
         "./packages/bundle/*/src",
-        "./packages/cordis/*/src",
+        "./packages/self-modification/*/src",
         "./packages/sandbox/*/src",
         "./packages/hooks/*/src",
         "./packages/session/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index c1cc0705cf..31631995cf 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -204,7 +204,7 @@
     { "path": "./packages/spill/spill" },
     { "path": "./packages/spill/spill-local" },
     { "path": "./packages/spill/spill-policy" },
-    { "path": "./packages/timeout/timeout-policy" },
+    { "path": "./packages/guard/timeout-policy" },
     { "path": "./packages/support/invariants" },
     { "path": "./packages/support/agent-loop-testkit" },
     { "path": "./packages/acp/acp" },
@@ -241,8 +241,8 @@
     { "path": "./packages/todo/tool-todo" },
     { "path": "./packages/plan/plan-mode" },
     { "path": "./packages/guard/repeat-tool-guard" },
-    { "path": "./packages/cordis/tool-cordis" },
-    { "path": "./packages/cordis/repository-plugin" },
+    { "path": "./packages/self-modification/tool-cordis" },
+    { "path": "./packages/self-modification/repository-plugin" },
     { "path": "./packages/hooks/hook-protocol" },
     { "path": "./packages/hooks/hooks-claude" },
     { "path": "./packages/hooks/hooks-codex" },

From 36cf4f32f4817d6865c1454d6cd5a18c4bb4cf77 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 03:48:07 +0800
Subject: [PATCH 153/262] docs(agent-note): flip the regrouping note to
 implemented

Move the triplet to implemented/architecture/, rewrite Proposal into a
present-tense Decision, fold Acceptance criteria and Risks into
Consequences (recording what pins the result), retitle the migration
section to what the move actually touched, and repoint the seven
inbound FIXME/README links.
---
 ...026-07-27-tui-chat-channel-module-split.md |    2 +-
 ...-07-27-tui-chat-channel-module-split.zh.md |    2 +-
 ...-07-24-tui-turn-end-stop-reason-notices.md |    2 +-
 ...-24-tui-turn-end-stop-reason-notices.zh.md |    2 +-
 ...17-dedicated-full-screen-tui-front-door.md |    2 +-
 ...dedicated-full-screen-tui-front-door.zh.md |    2 +-
 .../feature/2026-07-20-windows-tui-support.md |    2 +-
 .../2026-07-20-windows-tui-support.zh.md      |    2 +-
 .../2026-07-21-tui-skill-slash-command.md     |    2 +-
 .../2026-07-21-tui-skill-slash-command.zh.md  |    2 +-
 ...-07-27-assistant-timing-header-trailing.md |    2 +-
 ...-27-assistant-timing-header-trailing.zh.md |    2 +-
 ...sh-guided-skill-session-commands.i18n.yaml |    6 +-
 ...07-28-dsh-guided-skill-session-commands.md |    2 +-
 ...28-dsh-guided-skill-session-commands.zh.md |    2 +-
 ...7-26-execa-for-test-subprocess-plumbing.md |    2 +-
 ...6-execa-for-test-subprocess-plumbing.zh.md |    2 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |    6 +
 .../2026-07-29-package-regrouping.md          |   60 +-
 .../2026-07-29-package-regrouping.zh.md       |   52 +-
 ...-yaml-and-user-environment-layer.i18n.yaml |    4 +-
 ...entials-yaml-and-user-environment-layer.md |    4 +-
 ...ials-yaml-and-user-environment-layer.zh.md |    4 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |    4 +-
 ...6-07-31-fail-loud-releases-the-terminal.md |    2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |    2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |    4 +-
 ...26-08-03-cli-signal-shutdown-escalation.md |    2 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |    2 +-
 ...3-hmr-initial-scan-boot-deadlock.i18n.yaml |    4 +-
 ...26-08-03-hmr-initial-scan-boot-deadlock.md |    2 +-
 ...08-03-hmr-initial-scan-boot-deadlock.zh.md |    2 +-
 .../2026-07-28-feedback-command.i18n.yaml     |    4 +-
 .../feature/2026-07-28-feedback-command.md    |    2 +-
 .../feature/2026-07-28-feedback-command.zh.md |    2 +-
 ...-domain-kv-storage-and-workspace.i18n.yaml |    2 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md |    2 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |    6 -
 AGENTS.md                                     |   26 +-
 apps/cli/reference/README.i18n.yaml           |    4 +-
 apps/cli/reference/README.md                  |    2 +-
 apps/cli/reference/README.zh.md               |    2 +-
 docs/config-catalog.md                        |   62 +-
 docs/cordis-catalog/events.md                 |    6 +-
 docs/cordis-catalog/services.md               |   18 +-
 docs/event-producer-consumer.md               |   28 +-
 docs/module-graph.md                          |  354 +++--
 docs/persistence-catalog.md                   |   12 +-
 examples/web-cordis/README.i18n.yaml          |    4 +-
 examples/web-cordis/README.md                 |    4 +-
 examples/web-cordis/README.zh.md              |    4 +-
 packages/api/remotes/tsconfig.host.json       |    2 +-
 packages/bash/bash-env/tsconfig.json          |    2 +-
 packages/bundle/README.i18n.yaml              |   10 +-
 packages/bundle/README.md                     |    2 +-
 packages/bundle/README.zh.md                  |    2 +-
 .../compact/command-compact/README.i18n.yaml  |    4 +-
 packages/compact/command-compact/README.md    |    2 +-
 packages/compact/command-compact/README.zh.md |    2 +-
 .../credentials-local/README.i18n.yaml        |    4 +-
 .../credentials/credentials-local/README.md   |    2 +-
 .../credentials-local/README.zh.md            |    2 +-
 .../examples/jsonrpc-demo/README.i18n.yaml    |    4 +-
 packages/examples/jsonrpc-demo/README.md      |    4 +-
 packages/examples/jsonrpc-demo/README.zh.md   |    4 +-
 packages/feedback/README.i18n.yaml            |    4 +-
 packages/feedback/README.md                   |    2 +-
 packages/feedback/README.zh.md                |    2 +-
 .../command-feedback/README.i18n.yaml         |    4 +-
 packages/feedback/command-feedback/README.md  |    6 +-
 .../feedback/command-feedback/README.zh.md    |    6 +-
 .../feedback/command-feedback/tsconfig.json   |    2 +-
 packages/goal/command-goal/README.i18n.yaml   |    4 +-
 packages/goal/command-goal/README.md          |    2 +-
 packages/goal/command-goal/README.zh.md       |    2 +-
 packages/guard/timeout-policy/src/index.ts    |    2 +-
 .../interaction/permission/README.i18n.yaml   |    2 +-
 .../user-interaction/README.i18n.yaml         |    4 +-
 packages/plan/plan-mode/README.i18n.yaml      |    4 +-
 packages/plan/plan-mode/README.md             |    2 +-
 packages/plan/plan-mode/README.zh.md          |    2 +-
 packages/scaffold/README.i18n.yaml            |    4 +-
 packages/scaffold/README.md                   |    2 +-
 packages/scaffold/README.zh.md                |    2 +-
 packages/scaffold/client/README.i18n.yaml     |    4 +-
 packages/scaffold/client/README.md            |    2 +-
 packages/scaffold/client/README.zh.md         |    2 +-
 packages/scaffold/helper/src/index.ts         |    2 +-
 packages/scaffold/protocol/README.i18n.yaml   |    4 +-
 packages/scaffold/protocol/README.md          |    6 +-
 packages/scaffold/protocol/README.zh.md       |    6 +-
 packages/scaffold/scripts/src/index.ts        |    2 +-
 packages/scaffold/server/README.i18n.yaml     |    4 +-
 packages/scaffold/server/src/index.ts         |    2 +-
 packages/scaffold/telemetry/src/index.ts      |    3 +-
 .../subagent/subagent-codex/tsconfig.json     |    2 +-
 packages/subagent/subagent/tsconfig.json      |    4 +-
 .../typert/generator/tests/type-model.spec.ts |    4 +-
 packages/util/environment/README.i18n.yaml    |    4 +-
 packages/util/environment/README.md           |    2 +-
 packages/util/environment/README.zh.md        |    2 +-
 pnpm-lock.yaml                                | 1284 ++++++++---------
 .../request-response.expected.json            |    4 +-
 scripts/type-equiv.manifest.json              |    2 +-
 scripts/verify-package-paths.ts               |   16 +-
 105 files changed, 1089 insertions(+), 1112 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-29-package-regrouping.md (56%)
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-29-package-regrouping.zh.md (66%)
 delete mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml

diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
index 9b2c456d88..3cf9548d4d 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
@@ -7,7 +7,7 @@ English | [中文](2026-07-27-tui-chat-channel-module-split.zh.md)
 
 ## Problem
 
-`packages/interaction/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
+`packages/ui/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
 
 ## Decision
 
diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
index 44e8ffeac4..d5de02bd0f 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
@@ -7,7 +7,7 @@ Archived: 2026-08-04
 
 ## Problem
 
-`packages/interaction/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
+`packages/ui/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
 
 ## Decision
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
index 998e9dfcdc..62784ed7cd 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
@@ -11,7 +11,7 @@ The TUI rendered transcript notices for `error`, `aborted`, `max-tokens`, `rejec
 
 ## Decision
 
-The `turn/end` case in `packages/interaction/tui/src/index.ts` switches on the reason's discriminant and covers every kind: `completed` stays silent because the settled assistant message and its `Completed` timing header already present that outcome; `disposed` appends `Turn stopped: the agent was disposed.`; and the merge-extensible default appends `Turn ended: <kind>.` so an unknown plugin-added outcome still names why the agent stopped. All other kinds keep their existing notices.
+The `turn/end` case in `packages/ui/tui/src/index.ts` switches on the reason's discriminant and covers every kind: `completed` stays silent because the settled assistant message and its `Completed` timing header already present that outcome; `disposed` appends `Turn stopped: the agent was disposed.`; and the merge-extensible default appends `Turn ended: <kind>.` so an unknown plugin-added outcome still names why the agent stopped. All other kinds keep their existing notices.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
index ad53755259..162ba4ed44 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
@@ -11,7 +11,7 @@ TUI 会为 `error`、`aborted`、`max-tokens`、`rejected`、`interrupted` 这
 
 ## 决策
 
-`packages/interaction/tui/src/index.ts` 中的 `turn/end` 分支按 reason 的判别字段做 switch，覆盖每一种 kind：`completed` 保持沉默，因为已定稿的助手消息及其 `Completed` 计时头部已经呈现了这一结果；`disposed` 追加 `Turn stopped: the agent was disposed.`；merge 扩展的 default 分支追加 `Turn ended: <kind>.`，让未知的插件新增结果仍能点明 agent 停止的原因。其余各 kind 保留现有通知。
+`packages/ui/tui/src/index.ts` 中的 `turn/end` 分支按 reason 的判别字段做 switch，覆盖每一种 kind：`completed` 保持沉默，因为已定稿的助手消息及其 `Completed` 计时头部已经呈现了这一结果；`disposed` 追加 `Turn stopped: the agent was disposed.`；merge 扩展的 default 分支追加 `Turn ended: <kind>.`，让未知的插件新增结果仍能点明 agent 停止的原因。其余各 kind 保留现有通知。
 
 ## 备选方案
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
index 184a05ed23..1a04e738a2 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
@@ -15,7 +15,7 @@ The interactive channel must remain a Cordis plugin over the same agent, session
 
 ## Decision
 
-DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
+DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
 
 The package is a terminal front door, not a complete application. A host mounts `@deepseek-ai/dsh-tui` before its configured agent and composes the backends, tools, and policies around it. The product CLI currently ships no terminal composition; non-interactive tasks use headless mode, Web owns the installed human surface, and ACP remains a separate automation protocol.
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
index 6ac3eefa51..75fc3d47aa 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
@@ -15,7 +15,7 @@ Archived: 2026-08-04
 
 ## 决策
 
-DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
+DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
 
 该包是终端入口，而不是完整应用。宿主在已配置 agent 之前挂载 `@deepseek-ai/dsh-tui`，并围绕它组合后端、工具和策略。产品 CLI 目前不交付终端组合；非交互任务使用 headless 模式，Web 是已安装产品中面向人的界面，而 ACP 仍是独立的自动化协议。
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
index 2c8e92671f..9308df7fb4 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
@@ -13,7 +13,7 @@ The TUI platform contract must follow the runtime shipped to users rather than t
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
+[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
 
 The real Loader smoke selects a native pseudo-terminal boundary by host. macOS and Linux retain the Python POSIX PTY driver. Windows uses `node-pty` and ConPTY. Both drivers receive the same launch command, environment, terminal dimensions, marker-gated input actions, timeout, expected exit code, and output assertions, and all three smoke scenarios run on every supported platform.
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
index cb5d05da2b..8b4a1eb4ce 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
@@ -13,7 +13,7 @@ TUI 平台契约必须以交付给用户的运行时为准，而不是取决于
 
 ## 决策
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
+[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
 
 真实 Loader 冒烟测试根据宿主选择原生伪终端边界。macOS 和 Linux 继续使用 Python POSIX PTY 驱动，Windows 则使用 `node-pty` 和 ConPTY。两种驱动接收相同的启动命令、环境、终端尺寸、以标记为触发条件的输入动作、超时、预期退出码和输出断言；3 个冒烟场景都会在每个受支持平台上运行。
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
index 038d12a561..e151f92d0d 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
@@ -11,7 +11,7 @@ The [skill system](2026-07-05-skill-system.md) shipped with model-initiated load
 
 ## Decision
 
-The [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
+The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
 
 The TUI reads the skill service through `ctx.get('skills')`, not a declared injection, because skills mount conditionally: a deployment without the registry keeps a working front door, and `/skill:` there reports that skills are unavailable rather than failing to mount. `createTuiChat` is synchronous while `ctx.skills.list()` is async, so autocomplete seeds the static slash commands immediately and rebuilds the provider with `skill:<name>` entries once the catalog resolves; a resolution that arrives after disposal is dropped, and a rejected lookup keeps the base commands.
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
index af01642c07..ac1c4da948 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-04
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
+[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
 
 TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:<name>` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
index ff4a310f08..2ef926cff9 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
@@ -13,7 +13,7 @@ The TUI assistant message opened with a single header line joining the `Assistan
 
 **Split the label from the timing; render the timing as the message's trailing line.**
 
-`AssistantMessageComponent` (packages/interaction/tui/src/index.ts) now emits the bold `Assistant` label as the first line and appends the dim timing string (already assembled by `StreamingAssistantComponent.rebuild()` as `header`, including the `· Completed …` suffix when settled) as the last child, after reasoning and text. The timing content, bucket-hiding, and completion-time behavior are unchanged — only its position moved from the top to the bottom of the message.
+`AssistantMessageComponent` (packages/ui/tui/src/index.ts) now emits the bold `Assistant` label as the first line and appends the dim timing string (already assembled by `StreamingAssistantComponent.rebuild()` as `header`, including the `· Completed …` suffix when settled) as the last child, after reasoning and text. The timing content, bucket-hiding, and completion-time behavior are unchanged — only its position moved from the top to the bottom of the message.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
index 08ced9603d..282ac1e65b 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
@@ -13,7 +13,7 @@ TUI 的助手消息此前以一行开头，把 `Assistant` 标签和步骤计时
 
 **把标签与计时拆开；计时作为消息的末行渲染。**
 
-`AssistantMessageComponent`（packages/interaction/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
+`AssistantMessageComponent`（packages/ui/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
index a9e56019b3..8feded0ad4 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
@@ -1,6 +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 .agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
-2026-07-28-dsh-guided-skill-session-commands.md: 606513919a927af3bb7e9b74544fd8df9a1682ce
-2026-07-28-dsh-guided-skill-session-commands.zh.md: 39af4a3a554ba3053f25b3d034346d3e1f4ce237
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md
+2026-07-28-dsh-guided-skill-session-commands.md: 454d090a55db8987f8e4987aba67deff1b21b1a0
+2026-07-28-dsh-guided-skill-session-commands.zh.md: 64dad4e39c6fd3e3341313c3f8dd2b04947695cf
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
index 606513919a..454d090a55 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
@@ -25,7 +25,7 @@ The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED
 
 `apps/cli/tests/args.spec.ts` gains routing for `migrate`/`upgrade` (bare discriminant) and exit-1 for every leaked option on either side of each subcommand.
 
-`packages/interaction/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
+`packages/ui/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
 
 No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery.
 
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
index 39af4a3a55..64dad4e39c 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
@@ -25,7 +25,7 @@ Archived: 2026-08-03
 
 `apps/cli/tests/args.spec.ts` 新增 `migrate`/`upgrade` 的路由（裸判别式），以及每个子命令两侧任一泄漏选项的退出码 1。
 
-`packages/interaction/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
+`packages/ui/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
 
 无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
index 76cc213ba8..ca5edc50bf 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
@@ -11,7 +11,7 @@ Roughly ten e2e/smoke files re-derived the same spawn-collect-timeout choreograp
 
 Two related test-infra hand-rolls compounded the case:
 
-- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/scaffold/scripts`).
+- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/sdk/scripts`).
 - `apps/web/tests/smoke-real.e2e.ts` and `apps/web/tests/scaffold.ts` carried two verbatim copies of a regex `.env` parser (~20 lines) where the `process.loadEnvFile` builtin has exactly the required no-override semantics — and the vitest e2e/snapshot/web configs already load root `.env` with it before these files run, making the copies dead.
 - The snapshot harness hand-rolled three poll-until-deadline loops (`waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile` in `packages/support/acp-snapshot/src/harness.ts`, ~55 lines) plus `waitForFile` in `crash-recovery.e2e.ts`, where `vi.waitFor`/`expect.poll` cover the shape — vitest is already a runtime dependency of `dsh-acp-snapshot`, so this adds nothing.
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
index f597fd1e08..186e5cd560 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-07
 
 另有两处相关的测试基础设施手写代码进一步强化了替换的理由：
 
-- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/scaffold/scripts`）。
+- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/sdk/scripts`）。
 - `apps/web/tests/smoke-real.e2e.ts` 与 `apps/web/tests/scaffold.ts` 曾携带两份逐字相同的正则 `.env` 解析器拷贝（约 20 行），而内置的 `process.loadEnvFile` 恰好具备所需的「不覆盖已有值」语义；并且 vitest 的 e2e/snapshot/web 配置在这些文件运行之前就已用它加载了根 `.env`，这两份拷贝实为死代码。
 - 快照 harness 曾手写三个「轮询直到截止时间」的循环（`packages/support/acp-snapshot/src/harness.ts` 中的 `waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile`，约 55 行），外加 `crash-recovery.e2e.ts` 中的 `waitForFile`，而 `vi.waitFor`/`expect.poll` 正好覆盖这种形态；vitest 本来就是 `dsh-acp-snapshot` 的运行时依赖，因此这不新增任何东西。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
new file mode 100644
index 0000000000..e597017076
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.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 .agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
+2026-07-29-package-regrouping.md: bb9f7deb775a0922de8b20f766446ebf007718d3
+2026-07-29-package-regrouping.zh.md: 1d7d79e0cfad95382c036b3c99712775870aa48a
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
similarity index 56%
rename from .agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
rename to .agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
index 9a56f9f5f1..bb9f7deb77 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
@@ -1,24 +1,24 @@
 # Agent Note: Regroup packages/ by measured clustering
 
-Status: proposed
+Status: implemented
 
 English | [中文](2026-07-29-package-regrouping.zh.md)
 
 ## Problem
 
-The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../archived/architecture/2026-06-20-package-hierarchy.md)) has drifted since June: 167 packages now sit in 40 groups, and several group boundaries no longer match how the packages actually cluster.
+The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../archived/architecture/2026-06-20-package-hierarchy.md)) had drifted since June: 167 packages sat in 42 groups, and several group boundaries no longer matched how the packages actually cluster.
 
-- `ui/` mixes four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the `sdk/` stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrates the mixture instead of stating a role.
-- The session family is fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
-- Two group names collide with unrelated packages: `telemetry/` (session reporting) vs `sdk/telemetry` = `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
-- `cordis/` names its group after the framework every package is built on, so the name discriminates nothing; its single package `tool-cordis` is the runtime self-modification toolset.
-- `sdk/` folder names are inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeat the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` do not.
+- `ui/` mixed four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the SDK wire stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrated the mixture instead of stating a role.
+- The session family was fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
+- Two group names collided with unrelated packages: `telemetry/` (session reporting) vs `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
+- `cordis/` named its group after the framework every package is built on, so the name discriminated nothing; its single package `tool-cordis` is the runtime self-modification toolset.
+- The old `sdk/` folder names were inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeated the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` did not.
 
 The north star for the regrouping: **closely clustered packages share a group.** A cluster is measured — peer-dependency edges and co-change — not thematic. An isolated seam family may stand alone as a small group; the failure mode to avoid is the grab-bag whose name describes no single role.
 
-## Proposal
+## Decision
 
-Recompose six groups; every other group keeps today's boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names do not change in this reorganization; the folder tree carries the whole change.
+Six groups are recomposed; every other group keeps its prior boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names did not change; the folder tree carries the whole change.
 
 | Group | Members (folder names) | From |
 |---|---|---|
@@ -29,18 +29,18 @@ Recompose six groups; every other group keeps today's boundary and contents (the
 | `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ends the group-name collision with `dsh-telemetry`.
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
 - **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
 - **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
-- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is today's `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it says nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style.
+- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
 - **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
 - **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
 
-40 groups become 37; the win is clustering correctness and truthful names, not count.
+42 groups became 39; the win is clustering correctness and truthful names, not count.
 
 ## Deferred renames (FIXME markers)
 
-Five npm names should eventually change, but renaming inside the reorganization would turn a pure-move PR into an import-churn PR. Instead, the implementation adds a `FIXME` to each affected package's module JSDoc naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
+Five npm names should eventually change, but renaming inside the reorganization would have turned a pure-move PR into an import-churn PR. Instead, each affected package's module JSDoc carries a `FIXME` naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
 
 | Current npm name | Intended name | Why |
 |---|---|---|
@@ -52,19 +52,17 @@ Five npm names should eventually change, but renaming inside the reorganization
 
 The first four are settled intent; resolving them converges the SDK wire stack's npm names on `dsh-sdk-*` (the npm prefix names the product stack; the `scaffold/` folder names the role). `@deepseek-ai/create-sdk` keeps its documented npm-initializer exception.
 
-## Implementation
+## What the move touched
 
-One mechanical PR, landed in a quiet window: a single conflict event for the many open PRs, an atomic documentation update, and pure-move reviewability (`git mv` + path fixes, rename detection intact). If review prefers, the same content splits into a three-PR stack (the session fold; `ui/` dissolution + `scaffold/`; `self-modification/` + `guard/` merge), at the cost of three rebase events for everyone else.
+The moves landed as `git mv` commits, one per region (the session fold; `ui/` dissolution + `scaffold/`; `guard/` merge + `self-modification/`), so rename detection carries review. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
 
-A group move touches: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose (root and `apps/cli` READMEs, 7 script files + 22 docs files measured today; `verify-package-paths` gates the Markdown/TypeScript classes of stragglers). This list conveys the shape of the change, not a file inventory: every remaining group-path referent (workspace configs, test globs, lint keys) is found mechanically at implementation time by the acceptance gates failing loud, which is the repository's own misconfiguration rule.
+A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name. Each FIXME landed in the same commit as the move that created its context.
 
-A group move does not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name (verified by grep before this proposal). Each FIXME lands in the same PR as the move that creates its context.
-
-`client/` and `host/` are out of scope and unchanged. The in-flight `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
+`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
 
 ## Alternatives considered
 
-**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, sdk edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
+**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, scaffold edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
 
 **Abstract layer names** (`capability/`, `policy/`, `extension/`, `provider/`). Rejected: they describe every plugin equally badly, and a `capability/` bucket would hold ~50 packages.
 
@@ -88,19 +86,11 @@ A group move does not touch: npm names, imports, `cordis.yml` configs, snapshot
 
 **Renaming `context/` to `request-context/`.** Rejected: within this tree the group is unambiguous in situ; the churn is unjustified.
 
-## Acceptance criteria
+## Consequences
 
-- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged.
-- Zero npm renames: the workspace package-name set is identical before and after.
-- The five FIXME markers are present, each naming its intended new name.
-- New and updated group READMEs form complete bilingual triplets; the packages/README.md hierarchy table matches the tree; docs/module-graph.md is regenerated.
-- `pnpm run typecheck`, `pnpm run test`, `pnpm run doc-sync`, and `pnpm run hygiene` pass, and the unit/snapshot suites collect the same test files before and after the move (group-scoped globs in test configs must not silently match nothing).
-
-## Risks
-
-- **Open-PR conflicts.** Every open PR touching a moved file must rebase across the move. Mitigated by landing as one PR in a quiet window, publishing the mapping table in the PR body, and the moves being pure renames (rename detection resolves most hunks mechanically).
-- **Reference drift.** Docs or scripts citing old paths can go stale; `verify-package-paths` exists precisely for moved-package drift and runs in `doc-sync`.
-- **Translation load.** Five new group README triplets plus edits to existing pairs land in the implementation PR.
-- **Deferred renames are release blockers by design.** A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
-- **Single-package groups remain** (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
-- **What this gives up:** nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
+- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged. The workspace package-name set is identical before and after (zero npm renames), and the five FIXME markers pin the deferred ones. A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
+- What pins the result: `pnpm run typecheck`, the unit suites of every moved group, `verify-package-paths`, `verify-md-links`, and the corpus-wide translation pairing all pass on the moved tree; the group-scoped test globs in `vitest.snapshot.config.ts` were rewritten with the moves so the suites collect the same test files as before (a fail-open glob would silently drop coverage).
+- Every open PR touching a moved file rebases across the move once; the mapping table in the PR body and rename detection resolve most hunks mechanically.
+- Single-package groups remain (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
+- The `scaffold/` folders diverge from their npm names until the deferred renames land — the one transitional asymmetry, carried by three explicit `paths` entries in `tsconfig.base.json` and resolved by the FIXME renames.
+- What this gave up: nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
similarity index 66%
rename from .agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
rename to .agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
index c49c5a1daf..1d7d79e0cf 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
@@ -1,24 +1,24 @@
 # Agent Note: 按实测聚类重新划分 packages/ 分组
 
-Status: proposed
+Status: implemented
 
 [English](2026-07-29-package-regrouping.md) | 中文
 
 ## Problem
 
-两级 `packages/<group>/<pkg>` 层级结构（[原始决策](../../archived/architecture/2026-06-20-package-hierarchy.md)）自 6 月以来已经漂移：167 个包（package）如今坐落在 40 个组里，若干组边界已经对不上这些包的实际聚类。
+两级 `packages/<group>/<pkg>` 层级结构（[原始决策](../../archived/architecture/2026-06-20-package-hierarchy.md)）自 6 月以来已经漂移：167 个包（package）彼时坐落在 42 个组里，若干组边界已经对不上这些包的实际聚类。
 
-- `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 `sdk/` 这一栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
+- `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 SDK 通信栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
 - 会话家族被割裂在五个组里——`session-persistence/`、`session-projection/`、`session-query/`、`session-title/` 与 `telemetry/`——而实测依赖边明明把它们连成一体（query → persistence、title → projection、projection → persistence；见 [docs/module-graph.md](../../../../docs/module-graph.md)）。
-- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `sdk/telemetry` = `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
+- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
 - `cordis/` 拿所有包共同依托的框架给自己的组命名，这个名字因此毫无区分度；组里唯一的包 `tool-cordis` 是运行时自我修改工具集。
-- `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
+- 旧 `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
 
 这次重新分组的指导准则：**聚类紧密的包同处一组。**聚类以实测为准（对等依赖边与 co-change），而非按主题归类。孤立的 seam 家族可以自成一个小组；要避免的失败形态，是名字概括不出单一职责的大杂烩组。
 
-## Proposal
+## Decision
 
-重组六个组；其余每个组都保持今天的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。这次重组不改任何 npm 包名；整个变更全部由目录树承载。
+重组六个组；其余每个组都保持先前的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。npm 包名一个未改；整个变更全部由目录树承载。
 
 | 组 | 成员（目录名） | 来源 |
 |---|---|---|
@@ -32,15 +32,15 @@ Status: proposed
 - **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（评审意见：名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
 - **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
 - **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
-- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即今天的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致。
+- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
 - **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
 - **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
 
-40 个组变为 37 个；收益在聚类正确与名实相符，不在数量增减。
+42 个组变为 39 个；收益在聚类正确与名实相符，不在数量增减。
 
 ## Deferred renames (FIXME markers)
 
-五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。实现改为在每个受影响包的模块 JSDoc 里加一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
+五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。因此每个受影响包的模块 JSDoc 里带有一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
 
 | 当前 npm 名 | 目标名 | 原因 |
 |---|---|---|
@@ -52,19 +52,17 @@ Status: proposed
 
 前四个是已定的意图；兑现之后，SDK 通信栈的 npm 名随之收敛为 `dsh-sdk-*`（npm 前缀指产品栈，`scaffold/` 目录名指角色）。`@deepseek-ai/create-sdk` 保留其文档记载的 npm 初始化器特例。
 
-## Implementation
+## What the move touched
 
-整个变更作为一个机械化 PR，在低活动窗口期合入：众多开放中的 PR 只经历一次冲突事件，文档得到一次原子更新，评审享有纯移动的可评审性（`git mv` 加路径修正，重命名检测完好）。若评审偏好拆分，同样的内容也可以拆成三个 PR 的堆叠（会话折叠；`ui/` 解散加 `scaffold/`；`self-modification/` 加 `guard/` 合并），代价是其他所有人要经历三次变基事件。
+移动以 `git mv` 提交落地，每个区域一个提交（会话折叠；`ui/` 解散加 `scaffold/`；`guard/` 合并加 `self-modification/`），评审由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
 
-组移动会触及：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文中以仓库根为基准的 `packages/...` 引用（根 README 与 `apps/cli` README、今天实测 7 个脚本文件加 22 个文档文件；`verify-package-paths` 兜住 Markdown／TypeScript 这两类漏网引用）。这份清单陈述的是变更的形态，不是文件清点：其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都在实现时由验收门禁的响亮失败机械地找出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。每条 FIXME 都与创造其上下文的那次移动落在同一个提交。
 
-组移动不触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包（提案之前已用 grep 核实）。每条 FIXME 都与创造其上下文的那次移动落在同一个 PR。
-
-`client/` 与 `host/` 不在本次范围内，保持不变。在途的 `experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
+`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
 
 ## Alternatives considered
 
-**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、sdk 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
+**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、scaffold 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
 
 **抽象分层名**（`capability/`、`policy/`、`extension/`、`provider/`）。不予采纳：这些名字对每个插件都同样地不达意，而且一个 `capability/` 桶会装下约 50 个包。
 
@@ -88,19 +86,11 @@ Status: proposed
 
 **把 `context/` 改名为 `request-context/`。** 不予采纳：在这棵树里，该组就地看并无歧义；这份改动开销并不值得。
 
-## Acceptance criteria
+## Consequences
 
-- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。
-- npm 改名为零：workspace 的包名集合在前后完全相同。
-- 五条 FIXME 标记全部就位，每条都写明其意图中的新名字。
-- 新增与更新的组 README 构成完整的双语三文件配对；packages/README.md 的层级结构表与目录树一致；docs/module-graph.md 已重新生成。
-- `pnpm run typecheck`、`pnpm run test`、`pnpm run doc-sync`、`pnpm run hygiene` 全部通过，且单元／快照套件在移动前后收集到相同的测试文件（测试配置里按组划定的 glob 不得无声地匹配为空）。
-
-## Risks
-
-- **开放 PR 的冲突。** 每个触碰被移动文件的开放 PR 都必须跨过这次移动做变基。缓解方式：作为单个 PR 在低活动窗口期落地、在 PR 正文公布映射表，且移动都是纯改名（重命名检测可机械化解决大多数改动块）。
-- **引用漂移。** 引用旧路径的文档或脚本可能变得陈旧；`verify-package-paths` 正是为包移动造成的漂移而设，并随 `doc-sync`（文档同步门禁）运行。
-- **翻译负担。** 五组新的组 README 三文件配对，加上既有配对的修改，都随实现 PR 一同落地。
-- **推迟的改名按设计就是发布阻塞项。** 日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
-- **单包组依然存在**（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
+- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。workspace 的包名集合在前后完全相同（npm 改名为零），五条 FIXME 标记钉住推迟的改名。日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
+- 结果由以下检查钉住：`pnpm run typecheck`、每个被移动组的单元测试套件、`verify-package-paths`、`verify-md-links` 与全语料翻译配对在移动后的树上全部通过；`vitest.snapshot.config.ts` 中按组划定的测试 glob 随移动一并改写，套件收集到与移动前相同的测试文件（glob 匹配为空会无声地丢失覆盖）。
+- 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；PR 正文中的映射表与重命名检测可机械化解决大多数改动块。
+- 单包组依然存在（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
+- 在推迟的改名落地之前，`scaffold/` 的目录名与其 npm 名并不一致——这是唯一的过渡性不对称，由 `tsconfig.base.json` 里三条显式 `paths` 映射承载，并由 FIXME 改名最终消除。
 - **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
index ba4444166c..e083adcca5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.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 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
-2026-08-04-credentials-yaml-and-user-environment-layer.md: 4ecbc41adf4e22c74ecf425c2caf628efdf7cf54
-2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 370179b442783f4f8ecd8e3badbd236a924f5f81
+2026-08-04-credentials-yaml-and-user-environment-layer.md: 44bdea243671093b34a6338ed1c95bf25bcc78f4
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 5f724c7a12365e6e87e03b5926f837a5251b6118
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
index 4ecbc41adf..44bdea2436 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
@@ -23,7 +23,7 @@ OPENAI_API_KEY: sk-…
 
 Because the document holds credentials and nothing else, every deviation is a rejection rather than a skipped entry: a non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail — loud at boot and at a write, warn-and-keep-the-last-good-snapshot on a live reload. A silently ignored key would read as "the secret I stored has no effect", which is the failure this change exists to remove. The dotenv physical-line editor is replaced by a patch of the parsed document, so comments and untouched entries keep their formatting, any string value round-trips (multi-line included), and no entry is unwritable for want of a quoting style. The writer lock, read-modify-write, atomic `0600` write under a `0700` directory, exact-path watcher, content-equality self-write suppression, and quiescent disposal are unchanged.
 
-**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) parses the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` by materializing each accepted value only when the process has no higher-layer value. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
+**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/boot/app-boot/README.md) parses the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` by materializing each accepted value only when the process has no higher-layer value. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
 
 Credential precedence distinguishes the inherited environment from discovered files: the inherited value stays the read-only per-run override, the managed document wins next, and project then user `.env` values remain writable fallbacks. A `set` therefore replaces a discovered-file value instead of rejecting a write that only the flattened `process.env` view would consider shadowed.
 
@@ -38,7 +38,7 @@ There is no migration. A key already in `$DSH_HOME/.env` keeps resolving as a fa
 
 ## Alternatives considered
 
-**Keep one `$DSH_HOME/.env` and teach the CLI to hoist it.** Rejected: hoisting the store is precisely what makes stored keys unrotatable, which is why [app-boot documented the exclusion](../../../../packages/ui/app-boot/README.md) in the first place. The conflict is the file's two jobs, not the loader.
+**Keep one `$DSH_HOME/.env` and teach the CLI to hoist it.** Rejected: hoisting the store is precisely what makes stored keys unrotatable, which is why [app-boot documented the exclusion](../../../../packages/boot/app-boot/README.md) in the first place. The conflict is the file's two jobs, not the loader.
 
 **`$DSH_HOME/.credentials.env` — a second dotenv file.** Rejected: dotenv suits an environment layer but cannot express "a managed document indexed by credential reference". It cannot reject a non-string or an unaddressable key, and its line editor already refused values it could not quote, leaving entries readable but unwritable.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
index 370179b442..5f724c7a12 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -23,7 +23,7 @@ OPENAI_API_KEY: sk-…
 
 因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
 
-**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
+**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/boot/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
 
 凭据优先级会区分继承环境与发现的文件：继承值仍是只读的按次覆盖，其后是受管文档，再后是仍可写的项目与用户 `.env` 后备值。因此 `set` 会替换发现文件中的值，而不是因为扁平化的 `process.env` 视图认为写入会被遮蔽就加以拒绝。
 
@@ -38,7 +38,7 @@ OPENAI_API_KEY: sk-…
 
 ## Alternatives considered
 
-**保留单一的 `$DSH_HOME/.env`，让 CLI 去提升它。** 否决：提升存储本身正是让已存密钥无法轮换的原因，这也是 [app-boot 当初记录该排除](../../../../packages/ui/app-boot/README.md)的理由。冲突来自这个文件的两份工作，而不是加载器。
+**保留单一的 `$DSH_HOME/.env`，让 CLI 去提升它。** 否决：提升存储本身正是让已存密钥无法轮换的原因，这也是 [app-boot 当初记录该排除](../../../../packages/boot/app-boot/README.md)的理由。冲突来自这个文件的两份工作，而不是加载器。
 
 **`$DSH_HOME/.credentials.env`——第二个 dotenv 文件。** 否决：dotenv 适合环境层，却无法表达「一份按凭据引用索引的受管文档」。它无法拒绝非字符串或无法寻址的键，而且它的行编辑器本来就会拒绝无法加引号的值，留下可读却不可写的条目。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index 4931fa907b..fda3830670 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.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 .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
-2026-07-31-fail-loud-releases-the-terminal.md: 2a6e7fcbbdd5d35bcf70dee09fdb9e5592486b78
-2026-07-31-fail-loud-releases-the-terminal.zh.md: f75c21cf79b241e6714c10ec7df9ac25f3d978b4
+2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 64459614dc3376a1c773de72cd36aa455894a03c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
index 2a6e7fcbbd..5fe812e5fe 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
@@ -52,7 +52,7 @@ The guarantee belongs to whichever bin owns the terminal: a surface that grabs t
 
 ## Testing
 
-`packages/ui/app-boot/tests/app-boot.spec.ts` covers the release contract: the hook is awaited before the exit commits, a rejecting hook still exits 1, a never-settling hook exits after `FAIL_LOUD_RELEASE_TIMEOUT_MS`, and a burst of rejections reports only the first while the release still completes.
+`packages/boot/app-boot/tests/app-boot.spec.ts` covers the release contract: the hook is awaited before the exit commits, a rejecting hook still exits 1, a never-settling hook exits after `FAIL_LOUD_RELEASE_TIMEOUT_MS`, and a burst of rejections reports only the first while the release still completes.
 
 Those fake-process tests cannot observe the two failure modes that matter most — process exit code with a real event loop, and terminal state after exit — so the regression lives in `apps/cli/tests/tui-keyless-smoke.e2e.ts`. It boots the shipped tree in a real PTY over `fixtures/tui-invalid-provider.cordis.yml` (a list-shaped `providers`, the mistake users actually make), expects exit 1, and asserts the captured bytes contain both the labelled boot rejection (`dsh: plugin tree failed to load:`) and `ESC[?2004l`. The same case pins the boot path end to end: it caught the [HMR initial-scan boot deadlock](2026-08-03-hmr-initial-scan-boot-deadlock.md) that silently exited 13 with the terminal stranded.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index f75c21cf79..64459614dc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -52,7 +52,7 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 ## Testing
 
-`packages/ui/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
 
 这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 4752010ef6..36c7895ac2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.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 .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
-2026-08-03-cli-signal-shutdown-escalation.md: 7c9715c37ee57be9fa0f67af0c19f0bfa84845da
-2026-08-03-cli-signal-shutdown-escalation.zh.md: f3485edc9e453c0b774f442bfce6d678d63f2224
+2026-08-03-cli-signal-shutdown-escalation.md: c8aac6e2be927bd1f4a445c00e0aaa870b10a465
+2026-08-03-cli-signal-shutdown-escalation.zh.md: 66fe7062ea35a6cc91dbdd6644088cb086a15439
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
index 7c9715c37e..c8aac6e2be 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
@@ -49,4 +49,4 @@ The controller is launcher infrastructure rather than a Cordis plugin: it makes
 
 `apps/cli/tests/headless-shutdown.e2e.ts` boots the real shipped Web/headless Loader tree in a PTY with a test-only plugin whose disposer announces entry and never settles. The test sends SIGINT after the observation URL, waits for proof that disposal started, sends SIGINT again, and requires exit 130. The source/artifact launch resolver keeps the same regression on both execution planes. This PTY case covers the user-visible process state; no model-output snapshot changes.
 
-`packages/telemetry/session-telemetry-otel/tests/otel.spec.ts` holds a real OTLP request open after timer export begins and pins that Cordis disposal returns at `shutdownTimeoutMillis`, despite the SDK's `forceFlush()` remaining pending. The collector is then released so the still-observed provider Promise settles cleanly.
+`packages/session/session-telemetry-otel/tests/otel.spec.ts` holds a real OTLP request open after timer export begins and pins that Cordis disposal returns at `shutdownTimeoutMillis`, despite the SDK's `forceFlush()` remaining pending. The collector is then released so the still-observed provider Promise settles cleanly.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index f3485edc9e..66fe7062ea 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -49,4 +49,4 @@ headless 对完成的轮次仍以 0 退出，对其他轮次结束原因或 API
 
 `apps/cli/tests/headless-shutdown.e2e.ts` 在 PTY 中启动真实交付的 Web/headless Loader 插件树，并挂载一个仅用于测试的插件；该插件的 disposer 会声明已经进入清理流程，但永不结算。测试在观察地址出现后发送 SIGINT，等待 dispose 已启动的证据，再次发送 SIGINT，并要求进程以 130 退出。源码／产物启动解析器使两个执行平面都覆盖同一项回归。该 PTY 用例覆盖用户可见的进程状态；模型输出快照没有变化。
 
-`packages/telemetry/session-telemetry-otel/tests/otel.spec.ts` 在定时器导出开始后保持一条真实 OTLP 请求打开，并固定以下行为：即使 SDK 的 `forceFlush()` 仍待结算，Cordis dispose 也会在 `shutdownTimeoutMillis` 到期时返回。随后测试释放 collector，使仍受观察的提供方 Promise 干净结算。
+`packages/session/session-telemetry-otel/tests/otel.spec.ts` 在定时器导出开始后保持一条真实 OTLP 请求打开，并固定以下行为：即使 SDK 的 `forceFlush()` 仍待结算，Cordis dispose 也会在 `shutdownTimeoutMillis` 到期时返回。随后测试释放 collector，使仍受观察的提供方 Promise 干净结算。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 170627ea76..51fbed7ba9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.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 .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
-2026-08-03-hmr-initial-scan-boot-deadlock.md: 4b3e259c216d258c321ab06c41225b33ed240d19
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: ce1bc8396ac6e7fb6ecb1647fe2b29cdc788c7e1
+2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 5f8d50c4c0103eb2209eafb89cf34233c4c1bc35
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
index 4b3e259c21..1a70fbafc7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
@@ -38,4 +38,4 @@ One latent gap remains: a config edit made during a *failing* initial apply can
 
 ## Testing
 
-The `dsh` invalid-provider PTY case in `apps/cli/tests/tui-keyless-smoke.e2e.ts` pins the end-to-end contract: exit 1, the labelled `dsh: plugin tree failed to load:` diagnostic naming `$.providers`, and the bracketed-paste reset proving the tree was disposed. Before this fix the same case observed exit 13 with no diagnostic. Reload behavior stays covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/ui/app-boot/tests/hmr-config.spec.ts`.
+The `dsh` invalid-provider PTY case in `apps/cli/tests/tui-keyless-smoke.e2e.ts` pins the end-to-end contract: exit 1, the labelled `dsh: plugin tree failed to load:` diagnostic naming `$.providers`, and the bracketed-paste reset proving the tree was disposed. Before this fix the same case observed exit 13 with no diagnostic. Reload behavior stays covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/boot/app-boot/tests/hmr-config.spec.ts`.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index ce1bc8396a..5f8d50c4c0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -38,4 +38,4 @@
 
 ## 测试
 
-`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/ui/app-boot/tests/config-reload.spec.ts` 与 `packages/ui/app-boot/tests/hmr-config.spec.ts` 覆盖。
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index 8374a59b63..9f60321cc8 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.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 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
-2026-07-28-feedback-command.md: 56660b3796c44d3d510dd2901e6a155498673d88
-2026-07-28-feedback-command.zh.md: ec03a5c4a0e96d5350085c3d8d26f2523962f1b5
+2026-07-28-feedback-command.md: 78cc9e89a5811b3f1520bae2bd971cbcf2522ede
+2026-07-28-feedback-command.zh.md: c8870ca2988501d7899ae826e1bbcbad0bef5678
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
index 56660b3796..78cc9e89a5 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
@@ -46,7 +46,7 @@ Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /pla
 
 **Make `/feedback` a true no-op that records nothing.** The most literal reading of "does not do anything". Rejected because it makes the command pointless: the stated requirement was that the remark reach the session log.
 
-**Register the command inside an existing package** such as `packages/ui/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.
+**Register the command inside an existing package** such as `packages/interaction/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.
 
 **Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer needs that structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index ec03a5c4a0..c8870ca298 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -46,7 +46,7 @@ Status: implemented
 
 **让 `/feedback` 成为真正的空操作，什么都不记录。** 这是对「什么都不做」最字面的理解。已否决：这会使命令失去意义——明确的要求是让这条评论进入会话日志。
 
-**在现有包中注册该命令**，例如 `packages/ui/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。
+**在现有包中注册该命令**，例如 `packages/interaction/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。
 
 **从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：没有消费方需要该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 620fa2291f..8109eb4854 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
 2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
-2026-07-24-domain-kv-storage-and-workspace.zh.md: 15460e305d2d9aca3009025cf0218eb6c54c7237
+2026-07-24-domain-kv-storage-and-workspace.zh.md: 2904065a7374803495a9bbf8ff4e044310d9bd02
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index 15460e305d..2904065a73 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-host 侧唯一的持久化面是 session 事件日志（`packages/session-persistence`：仅追加、一 session 一文件）。凡是"不属于某个 session"的信息就没有落盘处，眼下有两个真实需求：
+host 侧唯一的持久化面是 session 事件日志（`packages/session/session-persistence`：仅追加、一 session 一文件）。凡是"不属于某个 session"的信息就没有落盘处，眼下有两个真实需求：
 
 - **workspace 实体**。GUI 要把 workspace 做成真实对象：路径、标题、关联 session 清单。归属关系由 workspace 持有——"哪些 session 属于这个 workspace"不是任何单个 session 自己的事实，塞进 session log 语义不成立。此前 workspace 只是 sidebar 上按 cwd 分组的视觉概念，没有实体（该结论已被推翻）。
 - **session 动态元信息**（可预见的第二个消费方）。冷会话列表只读日志首行 header（创建时的不可变快照），title、结束状态这类随会话推进变化的信息拿不到；补齐方向是 sidecar 元数据表——正是一张按 key 高频点更新的 KV 表。
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
deleted file mode 100644
index cdd772386f..0000000000
--- a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
-2026-07-29-package-regrouping.md: 9a56f9f5f1e0aef7d1f9efe60168ec1b0f41cce8
-2026-07-29-package-regrouping.zh.md: c49c5a1daffaff599f70f36b62e4dd3b5de3e5cf
diff --git a/AGENTS.md b/AGENTS.md
index 35fbc54ca6..dcb001768e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,22 +25,22 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   web/         web seam + search/fetch providers + model-facing web tools
   compact/     compaction seam + basic backend
   context/     request-context plugins
-  subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
-  bundle/      profile plugin bundles: installable patch layers for dsh --profile
+  subagent/    subagent seam + spawn/fork/ACP backends + tool
+  bundle/      installable dsh --profile patch-layer bundles
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
-  plan/        plan mode as logged collaboration state
-  guard/       loop-hygiene plugins + tool-call timeouts
-  self-modification/  the agent inspects/mounts plugins in its runtime
-  hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
-  session/     durable session data plane: persistence, projection, titles, reporting
-  settings/    user-settings seam + file-backed provider
-  credentials/ credential-reference seam + env-over-.env provider
+  plan/        plan mode as logged state
+  guard/       loop-hygiene + tool-timeout plugins
+  self-modification/  the agent inspects/mounts its own plugins
+  hooks/       Claude Code/Codex hook bridges + wire-protocol library
+  session/     durable session data: persistence, projection, titles, telemetry
+  settings/    user-settings seam + file provider
+  credentials/ credential-reference seam + env/.env provider
   acp/         automation-only Agent Client Protocol server
-  interaction/ approval/interaction seams, permission, commands, ask-user tool
-  boot/        shared app-bin boot glue
-  scaffold/    project tooling: helper, launcher, initializer, SDK wire protocol + ends
-  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
+  interaction/ approval/interaction seams, permission, commands, ask-user
+  boot/        shared app-bin glue
+  scaffold/    project tooling: helper, launcher, initializer, SDK protocol
+  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 27e391320a..325de8db4e 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: 496cecdb64e3254a2a77690f55f760b4cd90b521
-README.zh.md: 4673bf764347307a9b91e2a5474a8439cf67b481
+README.md: e616b420d60e0fa372bf38950207245cb60ced98
+README.zh.md: a65140e6dc9374e21bdd3018bce45432794a7b10
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 496cecdb64..e616b420d6 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -69,7 +69,7 @@ The base bundle mounts the native DeepSeek adapter, settings and credential prov
 
 Session events stream as OTLP/HTTP logs by default. `DSH_TELEMETRY_OTLP_URL` selects another collector. Any non-empty `DSH_TELEMETRY_DISABLED` disables the telemetry row before boot. The shipped base has no telemetry redaction rule, so exported records can contain message text, tool arguments and results, and workspace paths; the [telemetry Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md) owns that deployment decision.
 
-The empty `repository-plugins` row lets profile patch layers mount prepared immutable repository Plugin generations. See the [repository Plugin contract](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration). The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
+The empty `repository-plugins` row lets profile patch layers mount prepared immutable repository Plugin generations. See the [repository Plugin contract](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration). The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
 
 ## Source launcher
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 4673bf7643..a65140e6dc 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -69,7 +69,7 @@ dsh web --dump-config
 
 会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
 
-空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index c74358fd39..254d85ccd1 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -76,7 +76,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
 
 Source: [`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
 
@@ -639,7 +639,7 @@ export interface JsonRpcConfig {
 
 Depends on: `Readable` (`node:stream`) · `Writable` (`node:stream`)
 
-Source: [`packages/ui/jsonrpc/src/index.ts:25`](../packages/ui/jsonrpc/src/index.ts)
+Source: [`packages/scaffold/server/src/index.ts:29`](../packages/scaffold/server/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-deepseek`
 
@@ -1046,7 +1046,7 @@ export interface PresetSpec {
 
 Depends on: [`ApprovalPolicy`](core-data-structures/approval.md) · [`SandboxMode`](core-data-structures/sandbox.md)
 
-Source: [`packages/ui/permission/src/index.ts:140`](../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts)
 
 ## `@deepseek-ai/dsh-plan-mode`
 
@@ -1182,7 +1182,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/cordis/repository-plugin/src/index.ts:42`](../packages/cordis/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:42`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 
@@ -1273,7 +1273,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:59`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session/session-persistence-jsonl/src/index.ts:59`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-sqlite`
 
@@ -1316,7 +1316,7 @@ export interface Config {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:67`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
+Source: [`packages/session/session-persistence-sqlite/src/index.ts:67`](../packages/session/session-persistence-sqlite/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-projection-cache`
 
@@ -1337,7 +1337,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session-projection/session-projection-cache/src/index.ts:42`](../packages/session-projection/session-projection-cache/src/index.ts)
+Source: [`packages/session/session-projection-cache/src/index.ts:42`](../packages/session/session-projection-cache/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-query-sqlite`
 
@@ -1437,7 +1437,7 @@ export enum TelemetryMode {
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:80`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/session/session-telemetry-otel/src/index.ts:80`](../packages/session/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
@@ -1455,7 +1455,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session-title/session-title/src/index.ts:79`](../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:79`](../packages/session/session-title/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title-all-messages-llm`
 
@@ -1466,9 +1466,9 @@ Requires: `sessionTitle` · `llm` · `sessions`
 export type Config = SessionTitleLlmConfig
 ```
 
-Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-llm/src/index.ts)
+Depends on: [`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
 
-Source: [`packages/session-title/session-title-all-messages-llm/src/index.ts:15`](../packages/session-title/session-title-all-messages-llm/src/index.ts)
+Source: [`packages/session/session-title-all-messages-llm/src/index.ts:15`](../packages/session/session-title-all-messages-llm/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title-first-message-llm`
 
@@ -1479,9 +1479,9 @@ Requires: `sessionTitle` · `llm` · `sessions`
 export type Config = SessionTitleLlmConfig
 ```
 
-Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-llm/src/index.ts)
+Depends on: [`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
 
-Source: [`packages/session-title/session-title-first-message-llm/src/index.ts:15`](../packages/session-title/session-title-first-message-llm/src/index.ts)
+Source: [`packages/session/session-title-first-message-llm/src/index.ts:15`](../packages/session/session-title-first-message-llm/src/index.ts)
 
 ## `@deepseek-ai/dsh-settings-local`
 
@@ -1955,7 +1955,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts:25`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts:25`](../packages/self-modification/tool-cordis/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-fs`
 
@@ -2365,7 +2365,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:178`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
@@ -2602,7 +2602,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-command-compact` — requires `commands` · `compact` ([`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts))
 - `@deepseek-ai/dsh-command-feedback` — requires `commands` ([`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts))
 - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts))
-- `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
+- `@deepseek-ai/dsh-commands` ([`packages/interaction/commands/src/index.ts`](../packages/interaction/commands/src/index.ts))
 - `@deepseek-ai/dsh-fs-e2b` — requires `e2b` ([`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
 - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
@@ -2612,17 +2612,17 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-lsp` ([`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts))
 - `@deepseek-ai/dsh-pty` ([`packages/pty/pty/src/index.ts`](../packages/pty/pty/src/index.ts))
 - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
-- `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session-persistence/session-checkpoint-policy/src/index.ts`](../packages/session-persistence/session-checkpoint-policy/src/index.ts))
-- `@deepseek-ai/dsh-session-projection` ([`packages/session-projection/session-projection/src/index.ts`](../packages/session-projection/session-projection/src/index.ts))
+- `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts))
+- `@deepseek-ai/dsh-session-projection` ([`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts))
 - `@deepseek-ai/dsh-skill-badge` — requires `skills` ([`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts))
 - `@deepseek-ai/dsh-storage` ([`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts))
 - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))
 - `@deepseek-ai/dsh-subprocess-local` ([`packages/subprocess/subprocess-local/src/index.ts`](../packages/subprocess/subprocess-local/src/index.ts))
 - `@deepseek-ai/dsh-tasks-local` ([`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts))
-- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
-- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
+- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts))
+- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
-- `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
+- `@deepseek-ai/dsh-user-interaction` ([`packages/interaction/user-interaction/src/index.ts`](../packages/interaction/user-interaction/src/index.ts))
 - `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
 
 ## Seam packages (not directly loadable)
@@ -2636,7 +2636,7 @@ Abstract service classes — a deployment loads a concrete implementation packag
 - `@deepseek-ai/dsh-fs` — abstract `FileSystem` ([`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker` — abstract `DirectoryPicker` ([`packages/host/directory-picker/src/index.ts`](../packages/host/directory-picker/src/index.ts))
 - `@deepseek-ai/dsh-sandbox` — abstract `SandboxProvider` ([`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts))
-- `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session-persistence/session-persistence/src/index.ts`](../packages/session-persistence/session-persistence/src/index.ts))
+- `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session/session-persistence/src/index.ts`](../packages/session/session-persistence/src/index.ts))
 - `@deepseek-ai/dsh-session-query` — abstract `SessionQueryService` ([`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts))
 - `@deepseek-ai/dsh-settings` — abstract `Settings` ([`packages/settings/settings/src/index.ts`](../packages/settings/settings/src/index.ts))
 - `@deepseek-ai/dsh-spill` — abstract `SpillStore` ([`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts))
@@ -2648,10 +2648,10 @@ Abstract service classes — a deployment loads a concrete implementation packag
 
 Imported as libraries by other packages; a `cordis.yml` cannot load them.
 
-- `@deepseek-ai/create-sdk` ([`packages/sdk/create-sdk/src/index.ts`](../packages/sdk/create-sdk/src/index.ts))
+- `@deepseek-ai/create-sdk` ([`packages/scaffold/create-sdk/src/index.ts`](../packages/scaffold/create-sdk/src/index.ts))
 - `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
 - `@deepseek-ai/dsh-agent-loop-testkit` ([`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts))
-- `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
+- `@deepseek-ai/dsh-app-boot` ([`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-atomic-write` ([`packages/util/atomic-write/src/index.ts`](../packages/util/atomic-write/src/index.ts))
 - `@deepseek-ai/dsh-base` ([`packages/bundle/base/src/index.ts`](../packages/bundle/base/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
@@ -2662,7 +2662,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
 - `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
 - `@deepseek-ai/dsh-environment` ([`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts))
-- `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
+- `@deepseek-ai/dsh-helper` ([`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
 - `@deepseek-ai/dsh-llm-mock-server` ([`packages/support/llm-mock-server/src/index.ts`](../packages/support/llm-mock-server/src/index.ts))
@@ -2671,13 +2671,13 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-paths` ([`packages/util/paths/src/index.ts`](../packages/util/paths/src/index.ts))
 - `@deepseek-ai/dsh-retention` ([`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts))
 - `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
-- `@deepseek-ai/dsh-scripts` ([`packages/sdk/scripts/src/index.ts`](../packages/sdk/scripts/src/index.ts))
-- `@deepseek-ai/dsh-sdk-client` ([`packages/sdk/sdk-client/src/index.ts`](../packages/sdk/sdk-client/src/index.ts))
-- `@deepseek-ai/dsh-sdk-protocol` ([`packages/sdk/sdk-protocol/src/index.ts`](../packages/sdk/sdk-protocol/src/index.ts))
-- `@deepseek-ai/dsh-session-telemetry` ([`packages/telemetry/session-telemetry/src/index.ts`](../packages/telemetry/session-telemetry/src/index.ts))
-- `@deepseek-ai/dsh-session-title-llm` ([`packages/session-title/session-title-llm/src/index.ts`](../packages/session-title/session-title-llm/src/index.ts))
+- `@deepseek-ai/dsh-scripts` ([`packages/scaffold/scripts/src/index.ts`](../packages/scaffold/scripts/src/index.ts))
+- `@deepseek-ai/dsh-sdk-client` ([`packages/scaffold/client/src/index.ts`](../packages/scaffold/client/src/index.ts))
+- `@deepseek-ai/dsh-sdk-protocol` ([`packages/scaffold/protocol/src/index.ts`](../packages/scaffold/protocol/src/index.ts))
+- `@deepseek-ai/dsh-session-telemetry` ([`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts))
+- `@deepseek-ai/dsh-session-title-llm` ([`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
-- `@deepseek-ai/dsh-telemetry` ([`packages/sdk/telemetry/src/index.ts`](../packages/sdk/telemetry/src/index.ts))
+- `@deepseek-ai/dsh-telemetry` ([`packages/scaffold/telemetry/src/index.ts`](../packages/scaffold/telemetry/src/index.ts))
 - `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
 - `@deepseek-ai/dsh-type-meta` ([`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts))
 - `@deepseek-ai/dsh-typert-generator` ([`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts))
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 7015d39bc8..2c99c451d2 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -325,7 +325,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 
 Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:30`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
 
 ## `commands/*`
 
@@ -343,7 +343,7 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/ui/commands/src/index.ts:172`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
 
 ## `credentials/*`
 
@@ -822,7 +822,7 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:43`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `tools/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 8af0e6ca30..56a0d0d2e6 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -262,7 +262,7 @@ overrideOf(session: Session): ApprovalPolicy | undefined
 
 Types: [Agent](../core-data-structures/core.md) · [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalPolicy](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:193`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
 
 ## `ctx.bash` — `BashExecutor` (abstract seam)
 
@@ -451,7 +451,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md)
 
-Source: [`packages/ui/commands/src/index.ts:305`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
 
 ## `ctx.compact` — `CompactService` (abstract seam)
 
@@ -1062,7 +1062,7 @@ set(session: Session, name: string): void
 
 Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/ui/permission/src/index.ts:159`](../../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 
 ## `ctx.planMode` — `PlanModeService`
 
@@ -1352,7 +1352,7 @@ abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot
 
 Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionInspection](../core-data-structures/persistence.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md) · [SessionPreparation](../core-data-structures/persistence.md)
 
-Source: [`packages/session-persistence/session-persistence/src/index.ts:72`](../../packages/session-persistence/session-persistence/src/index.ts)
+Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 
 ## `ctx.sessionProjectionCache` — `SessionProjectionCache`
 
@@ -1400,7 +1400,7 @@ async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnaps
 
 Types: [Session](../core-data-structures/session.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/session-projection/session-projection-cache/src/index.ts:71`](../../packages/session-projection/session-projection-cache/src/index.ts)
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
 
 ## `ctx.sessionProjections` — `SessionProjectionRegistry`
 
@@ -1508,7 +1508,7 @@ restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseS
 
 Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/session-projection/session-projection/src/index.ts:156`](../../packages/session-projection/session-projection/src/index.ts)
+Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 
 ## `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
@@ -1846,7 +1846,7 @@ register(provider: SessionTitleProvider): () => Promise<void>
 
 Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
 
-Source: [`packages/session-title/session-title/src/index.ts:261`](../../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
 
 ## `ctx.settings` — `Settings` (abstract seam)
 
@@ -2473,7 +2473,7 @@ flush?(): void
 abstract shutdown(): Promise<void>
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:140`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `ctx.tokenMeter` — `TokenMeterService`
 
@@ -2745,7 +2745,7 @@ async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 
 Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md)
 
-Source: [`packages/ui/user-interaction/src/index.ts:51`](../../packages/ui/user-interaction/src/index.ts)
+Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
 
 ## `ctx.web` — `WebService`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 9699870ecc..f5ea3eba36 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -10,18 +10,18 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
 | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
 | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
 | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
 | `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
+| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -29,24 +29,24 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
-| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`loader-smoke`](../packages/support/loader-smoke), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/support/loader-smoke), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:43`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
+| `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
 | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
 | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
 | `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
@@ -64,7 +64,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
 | `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
-| `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
+| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
 | `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
 | `internal/service` | - | `gateway` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 2e71473379..6f47c36e97 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -93,41 +93,22 @@ flowchart TD
     pkg_spill_local["spill-local"]
     pkg_spill_policy["spill-policy"]
   end
-  subgraph group_timeout["packages/timeout"]
-    pkg_timeout_policy["timeout-policy"]
-  end
   subgraph group_todo["packages/todo"]
     pkg_tool_todo["tool-todo"]
   end
   subgraph group_plan["packages/plan"]
     pkg_plan_mode["plan-mode"]
   end
-  subgraph group_cordis["packages/cordis"]
-    pkg_repository_plugin["repository-plugin"]
-    pkg_tool_cordis["tool-cordis"]
-  end
   subgraph group_hooks["packages/hooks"]
     pkg_hook_protocol["hook-protocol"]
     pkg_hooks_claude["hooks-claude"]
     pkg_hooks_codex["hooks-codex"]
   end
-  subgraph group_session_persistence["packages/session-persistence"]
-    pkg_session_checkpoint_policy["session-checkpoint-policy"]
-    pkg_session_persistence["session-persistence"]
-    pkg_session_persistence_jsonl["session-persistence-jsonl"]
-    pkg_session_persistence_sqlite["session-persistence-sqlite"]
-  end
   subgraph group_session_query["packages/session-query"]
     pkg_session_query["session-query"]
     pkg_session_query_sqlite["session-query-sqlite"]
     pkg_tool_session_query["tool-session-query"]
   end
-  subgraph group_session_title["packages/session-title"]
-    pkg_session_title["session-title"]
-    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
-    pkg_session_title_first_message_llm["session-title-first-message-llm"]
-    pkg_session_title_llm["session-title-llm"]
-  end
   subgraph group_support["packages/support"]
     pkg_acp_snapshot["acp-snapshot"]
     pkg_agent_loop_testkit["agent-loop-testkit"]
@@ -139,19 +120,13 @@ flowchart TD
   subgraph group_acp["packages/acp"]
     pkg_acp["acp"]
   end
-  subgraph group_ui["packages/ui"]
-    pkg_app_boot["app-boot"]
-    pkg_commands["commands"]
-    pkg_jsonrpc["jsonrpc"]
-    pkg_permission["permission"]
-    pkg_tool_ask_user["tool-ask-user"]
-    pkg_user_approval["user-approval"]
-    pkg_user_interaction["user-interaction"]
-  end
   subgraph group_api["packages/api"]
     pkg_api_gateway["api-gateway"]
     pkg_api_remotes["api-remotes"]
   end
+  subgraph group_boot["packages/boot"]
+    pkg_app_boot["app-boot"]
+  end
   subgraph group_bundle["packages/bundle"]
     pkg_base["base"]
     pkg_headless["headless"]
@@ -219,6 +194,7 @@ flowchart TD
   end
   subgraph group_guard["packages/guard"]
     pkg_repeat_tool_guard["repeat-tool-guard"]
+    pkg_timeout_policy["timeout-policy"]
   end
   subgraph group_host["packages/host"]
     pkg_frontend_static["frontend-static"]
@@ -229,6 +205,13 @@ flowchart TD
     pkg_host_directory_picker_native["host-directory-picker-native"]
     pkg_host_webserver["host-webserver"]
   end
+  subgraph group_interaction["packages/interaction"]
+    pkg_commands["commands"]
+    pkg_permission["permission"]
+    pkg_tool_ask_user["tool-ask-user"]
+    pkg_user_approval["user-approval"]
+    pkg_user_interaction["user-interaction"]
+  end
   subgraph group_lsp["packages/lsp"]
     pkg_lsp["lsp"]
     pkg_lsp_local["lsp-local"]
@@ -248,16 +231,31 @@ flowchart TD
     pkg_sandbox_local["sandbox-local"]
     pkg_sandbox_policy["sandbox-policy"]
   end
-  subgraph group_sdk["packages/sdk"]
+  subgraph group_scaffold["packages/scaffold"]
     pkg_helper["helper"]
+    pkg_jsonrpc["jsonrpc"]
     pkg_scripts["scripts"]
     pkg_sdk_client["sdk-client"]
     pkg_sdk_protocol["sdk-protocol"]
     pkg_telemetry["telemetry"]
   end
-  subgraph group_session_projection["packages/session-projection"]
+  subgraph group_self_modification["packages/self-modification"]
+    pkg_repository_plugin["repository-plugin"]
+    pkg_tool_cordis["tool-cordis"]
+  end
+  subgraph group_session["packages/session"]
+    pkg_session_checkpoint_policy["session-checkpoint-policy"]
+    pkg_session_persistence["session-persistence"]
+    pkg_session_persistence_jsonl["session-persistence-jsonl"]
+    pkg_session_persistence_sqlite["session-persistence-sqlite"]
     pkg_session_projection["session-projection"]
     pkg_session_projection_cache["session-projection-cache"]
+    pkg_session_telemetry["session-telemetry"]
+    pkg_session_telemetry_otel["session-telemetry-otel"]
+    pkg_session_title["session-title"]
+    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+    pkg_session_title_first_message_llm["session-title-first-message-llm"]
+    pkg_session_title_llm["session-title-llm"]
   end
   subgraph group_settings["packages/settings"]
     pkg_settings["settings"]
@@ -278,10 +276,6 @@ flowchart TD
     pkg_tasks_local["tasks-local"]
     pkg_tool_tasks["tool-tasks"]
   end
-  subgraph group_telemetry["packages/telemetry"]
-    pkg_session_telemetry["session-telemetry"]
-    pkg_session_telemetry_otel["session-telemetry-otel"]
-  end
   subgraph group_typert["packages/typert"]
     pkg_type_meta["type-meta"]
     pkg_typert_generator["typert-generator"]
@@ -457,10 +451,6 @@ flowchart TD
   pkg_spill --> pkg_invariants
   pkg_spill --> pkg_llm
   pkg_spill --> pkg_session
-  pkg_session_persistence --> pkg_brand
-  pkg_session_persistence --> pkg_invariants
-  pkg_session_persistence --> pkg_session
-  pkg_session_persistence --> pkg_timeout
   pkg_acp_snapshot --> pkg_invariants
   pkg_acp_snapshot --> pkg_session
   pkg_app_boot --> pkg_environment
@@ -504,6 +494,10 @@ flowchart TD
   pkg_sandbox_local --> pkg_invariants
   pkg_sandbox_local --> pkg_llm
   pkg_sandbox_local --> pkg_sandbox
+  pkg_session_persistence --> pkg_brand
+  pkg_session_persistence --> pkg_invariants
+  pkg_session_persistence --> pkg_session
+  pkg_session_persistence --> pkg_timeout
   pkg_session_projection --> pkg_invariants
   pkg_session_projection --> pkg_session
   pkg_llm_retry --> pkg_agent
@@ -551,17 +545,6 @@ flowchart TD
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_invariants
   pkg_hook_protocol --> pkg_session
-  pkg_session_persistence_jsonl --> pkg_invariants
-  pkg_session_persistence_jsonl --> pkg_session
-  pkg_session_persistence_jsonl --> pkg_session_persistence
-  pkg_session_persistence_sqlite --> pkg_invariants
-  pkg_session_persistence_sqlite --> pkg_session
-  pkg_session_persistence_sqlite --> pkg_session_persistence
-  pkg_session_title --> pkg_brand
-  pkg_session_title --> pkg_invariants
-  pkg_session_title --> pkg_llm
-  pkg_session_title --> pkg_session
-  pkg_session_title --> pkg_session_projection
   pkg_llm_replay --> pkg_compact
   pkg_llm_replay --> pkg_invariants
   pkg_llm_replay --> pkg_llm
@@ -570,21 +553,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
   pkg_loader_smoke --> pkg_session
-  pkg_commands --> pkg_agent
-  pkg_commands --> pkg_brand
-  pkg_commands --> pkg_invariants
-  pkg_commands --> pkg_scope
-  pkg_commands --> pkg_session
-  pkg_user_approval --> pkg_agent
-  pkg_user_approval --> pkg_brand
-  pkg_user_approval --> pkg_invariants
-  pkg_user_approval --> pkg_llm
-  pkg_user_approval --> pkg_scope
-  pkg_user_approval --> pkg_session
-  pkg_user_approval --> pkg_system_prompt
-  pkg_user_interaction --> pkg_agent
-  pkg_user_interaction --> pkg_invariants
-  pkg_user_interaction --> pkg_llm
   pkg_headless --> pkg_agent
   pkg_headless --> pkg_host_apiproxy
   pkg_headless --> pkg_host_webserver
@@ -614,6 +582,21 @@ flowchart TD
   pkg_host_directory_picker_native --> pkg_client_ui_slots
   pkg_host_directory_picker_native --> pkg_client_ui_workspace
   pkg_host_directory_picker_native --> pkg_invariants
+  pkg_commands --> pkg_agent
+  pkg_commands --> pkg_brand
+  pkg_commands --> pkg_invariants
+  pkg_commands --> pkg_scope
+  pkg_commands --> pkg_session
+  pkg_user_approval --> pkg_agent
+  pkg_user_approval --> pkg_brand
+  pkg_user_approval --> pkg_invariants
+  pkg_user_approval --> pkg_llm
+  pkg_user_approval --> pkg_scope
+  pkg_user_approval --> pkg_session
+  pkg_user_approval --> pkg_system_prompt
+  pkg_user_interaction --> pkg_agent
+  pkg_user_interaction --> pkg_invariants
+  pkg_user_interaction --> pkg_llm
   pkg_lsp_local --> pkg_brand
   pkg_lsp_local --> pkg_fs
   pkg_lsp_local --> pkg_invariants
@@ -631,18 +614,29 @@ flowchart TD
   pkg_sandbox_policy --> pkg_system_prompt
   pkg_scripts --> pkg_app_boot
   pkg_scripts --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_session
+  pkg_session_persistence_jsonl --> pkg_session_persistence
+  pkg_session_persistence_sqlite --> pkg_invariants
+  pkg_session_persistence_sqlite --> pkg_session
+  pkg_session_persistence_sqlite --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_invariants
   pkg_session_projection_cache --> pkg_session
   pkg_session_projection_cache --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_session_projection
   pkg_session_projection_cache --> pkg_storage_domain
+  pkg_session_telemetry --> pkg_agent
+  pkg_session_telemetry --> pkg_invariants
+  pkg_session_telemetry --> pkg_session
+  pkg_session_title --> pkg_brand
+  pkg_session_title --> pkg_invariants
+  pkg_session_title --> pkg_llm
+  pkg_session_title --> pkg_session
+  pkg_session_title --> pkg_session_projection
   pkg_tasks --> pkg_agent
   pkg_tasks --> pkg_brand
   pkg_tasks --> pkg_invariants
   pkg_tasks --> pkg_session
-  pkg_session_telemetry --> pkg_agent
-  pkg_session_telemetry --> pkg_invariants
-  pkg_session_telemetry --> pkg_session
   pkg_workflow --> pkg_agent
   pkg_workflow --> pkg_brand
   pkg_workflow --> pkg_invariants
@@ -694,24 +688,10 @@ flowchart TD
   pkg_session_query --> pkg_session
   pkg_session_query --> pkg_session_persistence
   pkg_session_query --> pkg_session_title
-  pkg_session_title_llm --> pkg_invariants
-  pkg_session_title_llm --> pkg_llm
-  pkg_session_title_llm --> pkg_session
-  pkg_session_title_llm --> pkg_session_title
-  pkg_session_title_llm --> pkg_timeout
   pkg_acp --> pkg_agent
   pkg_acp --> pkg_invariants
   pkg_acp --> pkg_session
   pkg_acp --> pkg_user_approval
-  pkg_permission --> pkg_bash
-  pkg_permission --> pkg_commands
-  pkg_permission --> pkg_invariants
-  pkg_permission --> pkg_sandbox
-  pkg_permission --> pkg_sandbox_policy
-  pkg_permission --> pkg_session
-  pkg_permission --> pkg_session_projection
-  pkg_permission --> pkg_settings
-  pkg_permission --> pkg_user_approval
   pkg_api_remotes --> pkg_agent
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_invariants
@@ -732,6 +712,15 @@ flowchart TD
   pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
   pkg_host_directory_picker_auto --> pkg_host_webserver
   pkg_host_directory_picker_auto --> pkg_invariants
+  pkg_permission --> pkg_bash
+  pkg_permission --> pkg_commands
+  pkg_permission --> pkg_invariants
+  pkg_permission --> pkg_sandbox
+  pkg_permission --> pkg_sandbox_policy
+  pkg_permission --> pkg_session
+  pkg_permission --> pkg_session_projection
+  pkg_permission --> pkg_settings
+  pkg_permission --> pkg_user_approval
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -739,6 +728,11 @@ flowchart TD
   pkg_pty_local --> pkg_sandbox_policy
   pkg_pty_local --> pkg_session
   pkg_pty_local --> pkg_subprocess
+  pkg_session_title_llm --> pkg_invariants
+  pkg_session_title_llm --> pkg_llm
+  pkg_session_title_llm --> pkg_session
+  pkg_session_title_llm --> pkg_session_title
+  pkg_session_title_llm --> pkg_timeout
   pkg_tasks_local --> pkg_agent
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
@@ -820,10 +814,6 @@ flowchart TD
   pkg_spill_policy --> pkg_session
   pkg_spill_policy --> pkg_spill
   pkg_spill_policy --> pkg_tools
-  pkg_timeout_policy --> pkg_invariants
-  pkg_timeout_policy --> pkg_llm
-  pkg_timeout_policy --> pkg_timeout
-  pkg_timeout_policy --> pkg_tools
   pkg_tool_todo --> pkg_agent
   pkg_tool_todo --> pkg_invariants
   pkg_tool_todo --> pkg_session
@@ -838,9 +828,6 @@ flowchart TD
   pkg_plan_mode --> pkg_system_prompt
   pkg_plan_mode --> pkg_tools
   pkg_plan_mode --> pkg_user_interaction
-  pkg_tool_cordis --> pkg_invariants
-  pkg_tool_cordis --> pkg_scope
-  pkg_tool_cordis --> pkg_tools
   pkg_hooks_codex --> pkg_agent
   pkg_hooks_codex --> pkg_hook_protocol
   pkg_hooks_codex --> pkg_invariants
@@ -848,12 +835,6 @@ flowchart TD
   pkg_hooks_codex --> pkg_session
   pkg_hooks_codex --> pkg_session_persistence
   pkg_hooks_codex --> pkg_tools
-  pkg_session_checkpoint_policy --> pkg_agent
-  pkg_session_checkpoint_policy --> pkg_invariants
-  pkg_session_checkpoint_policy --> pkg_llm
-  pkg_session_checkpoint_policy --> pkg_session
-  pkg_session_checkpoint_policy --> pkg_session_persistence
-  pkg_session_checkpoint_policy --> pkg_tools
   pkg_session_query_sqlite --> pkg_invariants
   pkg_session_query_sqlite --> pkg_session
   pkg_session_query_sqlite --> pkg_session_persistence
@@ -865,26 +846,12 @@ flowchart TD
   pkg_tool_session_query --> pkg_system_prompt
   pkg_tool_session_query --> pkg_timeout
   pkg_tool_session_query --> pkg_tools
-  pkg_session_title_all_messages_llm --> pkg_invariants
-  pkg_session_title_all_messages_llm --> pkg_llm
-  pkg_session_title_all_messages_llm --> pkg_session
-  pkg_session_title_all_messages_llm --> pkg_session_title
-  pkg_session_title_all_messages_llm --> pkg_session_title_llm
-  pkg_session_title_first_message_llm --> pkg_invariants
-  pkg_session_title_first_message_llm --> pkg_llm
-  pkg_session_title_first_message_llm --> pkg_session
-  pkg_session_title_first_message_llm --> pkg_session_title
-  pkg_session_title_first_message_llm --> pkg_session_title_llm
   pkg_agent_loop_testkit --> pkg_agent
   pkg_agent_loop_testkit --> pkg_invariants
   pkg_agent_loop_testkit --> pkg_llm
   pkg_agent_loop_testkit --> pkg_session
   pkg_agent_loop_testkit --> pkg_system_prompt
   pkg_agent_loop_testkit --> pkg_tools
-  pkg_tool_ask_user --> pkg_agent
-  pkg_tool_ask_user --> pkg_invariants
-  pkg_tool_ask_user --> pkg_tools
-  pkg_tool_ask_user --> pkg_user_interaction
   pkg_client_ui_command --> pkg_client_connection
   pkg_client_ui_command --> pkg_client_locale
   pkg_client_ui_command --> pkg_client_runtime
@@ -929,6 +896,14 @@ flowchart TD
   pkg_repeat_tool_guard --> pkg_agent
   pkg_repeat_tool_guard --> pkg_invariants
   pkg_repeat_tool_guard --> pkg_tools
+  pkg_timeout_policy --> pkg_invariants
+  pkg_timeout_policy --> pkg_llm
+  pkg_timeout_policy --> pkg_timeout
+  pkg_timeout_policy --> pkg_tools
+  pkg_tool_ask_user --> pkg_agent
+  pkg_tool_ask_user --> pkg_invariants
+  pkg_tool_ask_user --> pkg_tools
+  pkg_tool_ask_user --> pkg_user_interaction
   pkg_tool_lsp --> pkg_invariants
   pkg_tool_lsp --> pkg_llm
   pkg_tool_lsp --> pkg_lsp
@@ -952,13 +927,15 @@ flowchart TD
   pkg_tool_pty --> pkg_system_prompt
   pkg_tool_pty --> pkg_tasks
   pkg_tool_pty --> pkg_tools
-  pkg_tool_tasks --> pkg_agent
-  pkg_tool_tasks --> pkg_invariants
-  pkg_tool_tasks --> pkg_llm
-  pkg_tool_tasks --> pkg_retention
-  pkg_tool_tasks --> pkg_system_prompt
-  pkg_tool_tasks --> pkg_tasks
-  pkg_tool_tasks --> pkg_tools
+  pkg_tool_cordis --> pkg_invariants
+  pkg_tool_cordis --> pkg_scope
+  pkg_tool_cordis --> pkg_tools
+  pkg_session_checkpoint_policy --> pkg_agent
+  pkg_session_checkpoint_policy --> pkg_invariants
+  pkg_session_checkpoint_policy --> pkg_llm
+  pkg_session_checkpoint_policy --> pkg_session
+  pkg_session_checkpoint_policy --> pkg_session_persistence
+  pkg_session_checkpoint_policy --> pkg_tools
   pkg_session_telemetry_otel --> pkg_brand
   pkg_session_telemetry_otel --> pkg_command_feedback
   pkg_session_telemetry_otel --> pkg_invariants
@@ -966,6 +943,23 @@ flowchart TD
   pkg_session_telemetry_otel --> pkg_paths
   pkg_session_telemetry_otel --> pkg_session
   pkg_session_telemetry_otel --> pkg_session_telemetry
+  pkg_session_title_all_messages_llm --> pkg_invariants
+  pkg_session_title_all_messages_llm --> pkg_llm
+  pkg_session_title_all_messages_llm --> pkg_session
+  pkg_session_title_all_messages_llm --> pkg_session_title
+  pkg_session_title_all_messages_llm --> pkg_session_title_llm
+  pkg_session_title_first_message_llm --> pkg_invariants
+  pkg_session_title_first_message_llm --> pkg_llm
+  pkg_session_title_first_message_llm --> pkg_session
+  pkg_session_title_first_message_llm --> pkg_session_title
+  pkg_session_title_first_message_llm --> pkg_session_title_llm
+  pkg_tool_tasks --> pkg_agent
+  pkg_tool_tasks --> pkg_invariants
+  pkg_tool_tasks --> pkg_llm
+  pkg_tool_tasks --> pkg_retention
+  pkg_tool_tasks --> pkg_system_prompt
+  pkg_tool_tasks --> pkg_tasks
+  pkg_tool_tasks --> pkg_tools
   pkg_tool_workflow --> pkg_agent
   pkg_tool_workflow --> pkg_invariants
   pkg_tool_workflow --> pkg_llm
@@ -1028,10 +1022,6 @@ flowchart TD
   pkg_tool_subagent_report --> pkg_llm
   pkg_tool_subagent_report --> pkg_subagent
   pkg_tool_subagent_report --> pkg_tools
-  pkg_repository_plugin --> pkg_invariants
-  pkg_repository_plugin --> pkg_mcp_client
-  pkg_repository_plugin --> pkg_paths
-  pkg_repository_plugin --> pkg_skill_local
   pkg_hooks_claude --> pkg_agent
   pkg_hooks_claude --> pkg_hook_protocol
   pkg_hooks_claude --> pkg_invariants
@@ -1091,6 +1081,10 @@ flowchart TD
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
   pkg_sdk_protocol --> pkg_subagent
+  pkg_repository_plugin --> pkg_invariants
+  pkg_repository_plugin --> pkg_mcp_client
+  pkg_repository_plugin --> pkg_paths
+  pkg_repository_plugin --> pkg_skill_local
   pkg_tool_ralph --> pkg_agent
   pkg_tool_ralph --> pkg_invariants
   pkg_tool_ralph --> pkg_llm
@@ -1121,14 +1115,6 @@ flowchart TD
   pkg_subagent_spawn --> pkg_invariants
   pkg_subagent_spawn --> pkg_subagent
   pkg_subagent_spawn --> pkg_subagent_inprocess
-  pkg_jsonrpc --> pkg_agent
-  pkg_jsonrpc --> pkg_invariants
-  pkg_jsonrpc --> pkg_llm
-  pkg_jsonrpc --> pkg_llm_deepseek
-  pkg_jsonrpc --> pkg_scope
-  pkg_jsonrpc --> pkg_sdk_protocol
-  pkg_jsonrpc --> pkg_session
-  pkg_jsonrpc --> pkg_subagent
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1151,6 +1137,14 @@ flowchart TD
   pkg_agent_spine_demo --> pkg_tool_tasks
   pkg_agent_spine_demo --> pkg_tools
   pkg_agent_spine_demo --> pkg_workspace_context
+  pkg_jsonrpc --> pkg_agent
+  pkg_jsonrpc --> pkg_invariants
+  pkg_jsonrpc --> pkg_llm
+  pkg_jsonrpc --> pkg_llm_deepseek
+  pkg_jsonrpc --> pkg_scope
+  pkg_jsonrpc --> pkg_sdk_protocol
+  pkg_jsonrpc --> pkg_session
+  pkg_jsonrpc --> pkg_subagent
   pkg_sdk_client --> pkg_invariants
   pkg_sdk_client --> pkg_llm
   pkg_sdk_client --> pkg_sdk_protocol
@@ -1211,8 +1205,8 @@ flowchart TD
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
-| [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`helper`](../packages/scaffold/helper) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`telemetry`](../packages/scaffold/telemetry) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
@@ -1244,9 +1238,8 @@ flowchart TD
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`app-boot`](../packages/boot/app-boot) | `boot` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
 | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
@@ -1255,10 +1248,11 @@ flowchart TD
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
-| [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
-| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`type-meta`](../packages/typert/type-meta) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
@@ -1267,14 +1261,8 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`session-title`](../packages/session-title/session-title) | `session-title` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
-| [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1282,55 +1270,55 @@ flowchart TD
 | [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
+| [`user-approval`](../packages/interaction/user-approval) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`user-interaction`](../packages/interaction/user-interaction) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
-| [`session-projection-cache`](../packages/session-projection/session-projection-cache) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
+| [`scripts`](../packages/scaffold/scripts) | `scaffold` | [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants) |
+| [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
+| [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-title`](../packages/session/session-title) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`session-telemetry`](../packages/telemetry/session-telemetry) | `telemetry` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
-| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
-| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
+| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
-| [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) |
-| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
-| [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/ui/user-approval) |
-| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
+| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
-| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
+| [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
-| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
 | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
-| [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`tools`](../packages/core/tools) |
-| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
-| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy) | `session-persistence` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query) |
+| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
+| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
-| [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
@@ -1338,37 +1326,43 @@ flowchart TD
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
 | [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/self-modification/tool-cordis) | `self-modification` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
+| [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
+| [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
 | [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
-| [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
-| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`repository-plugin`](../packages/cordis/repository-plugin) | `cordis` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
-| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
-| [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
-| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
-| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
+| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index daf2ea7ab2..b238e56399 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -125,7 +125,7 @@ Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/type
 
 Types: [CallId](core-data-structures/core.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:44`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
 
 #### `approval/decided` — log-only
 
@@ -141,7 +141,7 @@ Source: [`packages/ui/user-approval/src/index.ts:44`](../packages/ui/user-approv
 }
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:55`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:55`](../packages/interaction/user-approval/src/index.ts)
 
 #### `approval/policy` — log-only
 
@@ -161,7 +161,7 @@ Source: [`packages/ui/user-approval/src/index.ts:55`](../packages/ui/user-approv
 }
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:67`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:67`](../packages/interaction/user-approval/src/index.ts)
 
 ### `assistant/*`
 
@@ -211,7 +211,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:151`](../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
 
 #### `command/run` — log-only
 
@@ -229,7 +229,7 @@ Source: [`packages/ui/commands/src/index.ts:151`](../packages/ui/commands/src/in
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:144`](../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
 
 ### `compact/*`
 
@@ -449,7 +449,7 @@ Source: [`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src
 'permission/preset': { preset: string }
 ```
 
-Source: [`packages/ui/permission/src/index.ts:50`](../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts:50`](../packages/interaction/permission/src/index.ts)
 
 ### `plan/*`
 
diff --git a/examples/web-cordis/README.i18n.yaml b/examples/web-cordis/README.i18n.yaml
index 0564a4e0fc..86cc276a4e 100644
--- a/examples/web-cordis/README.i18n.yaml
+++ b/examples/web-cordis/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 examples/web-cordis/README.md
-README.md: 75c7610fecc20777607c7c8cbb6ed2fc7f590b73
-README.zh.md: 5c25347ee17037bbfc7d10a5507424ce52e3faff
+README.md: 21fe0a210b2e591a96dc254014a0f91ed9afa2ba
+README.zh.md: 35158affd5cbdd6f8fa7f5910500f21c2b241309
diff --git a/examples/web-cordis/README.md b/examples/web-cordis/README.md
index 75c7610fec..21fe0a210b 100644
--- a/examples/web-cordis/README.md
+++ b/examples/web-cordis/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Self-referential demonstration of [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
+Self-referential demonstration of [`@deepseek-ai/dsh-tool-cordis`](../../packages/self-modification/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
 
 ## Run it
 
@@ -18,4 +18,4 @@ Start the ACP automation server instead:
 pnpm run demo:cordis acp
 ```
 
-Both commands require `DEEPSEEK_API_KEY`. The [Cordis tool reference](../../packages/cordis/tool-cordis/README.md) owns the tool, lifecycle, and safety contracts.
+Both commands require `DEEPSEEK_API_KEY`. The [Cordis tool reference](../../packages/self-modification/tool-cordis/README.md) owns the tool, lifecycle, and safety contracts.
diff --git a/examples/web-cordis/README.zh.md b/examples/web-cordis/README.zh.md
index 5c25347ee1..35158affd5 100644
--- a/examples/web-cordis/README.zh.md
+++ b/examples/web-cordis/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md) 的自指示例。agent（智能体）可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
+[`@deepseek-ai/dsh-tool-cordis`](../../packages/self-modification/tool-cordis/README.md) 的自指示例。agent（智能体）可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
 
 ## 运行
 
@@ -18,4 +18,4 @@ pnpm run demo:cordis
 pnpm run demo:cordis acp
 ```
 
-这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/cordis/tool-cordis/README.md)定义。
+这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json
index 1d4c35a9e2..1082a0d94b 100644
--- a/packages/api/remotes/tsconfig.host.json
+++ b/packages/api/remotes/tsconfig.host.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/bash/bash-env/tsconfig.json b/packages/bash/bash-env/tsconfig.json
index bcf5eb5229..d48ddfc73b 100644
--- a/packages/bash/bash-env/tsconfig.json
+++ b/packages/bash/bash-env/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/tools"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 5199e0939e..98df59d988 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -1,12 +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:
-<<<<<<<< HEAD:packages/bundle/README.i18n.yaml
 #   pnpm run verify-translation-pairing --write packages/bundle/README.md
-README.md: 4759170435a80e85731446cef21d24fff2abed66
-README.zh.md: 1ef610a1b7b3c591c9a900e04f2d8096b0b086b9
-========
-#   pnpm run verify-translation-pairing --write packages/interaction/tui/README.md
-README.md: c81cac891403e5294c4456ce4d4048ecd74666ce
-README.zh.md: 01055619f4df460284564f0a1816de366d809e01
->>>>>>>> a58746f4cc (refactor(packages): dissolve ui/ and rename sdk/ to scaffold/):packages/interaction/tui/README.i18n.yaml
+README.md: af06fe921a66378894a4ab0174ef403499f5f68c
+README.zh.md: ef2027e347b79e14574ba1164aa9fddd364327e9
diff --git a/packages/bundle/README.md b/packages/bundle/README.md
index 4759170435..af06fe921a 100644
--- a/packages/bundle/README.md
+++ b/packages/bundle/README.md
@@ -2,7 +2,7 @@
 
 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.
+Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, making them installable patch layers for `dsh --profile` compositions ([profile contract](../boot/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 |
 |---|---|---|
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index 1ef610a1b7..ef2027e347 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../ui/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/compact/command-compact/README.i18n.yaml b/packages/compact/command-compact/README.i18n.yaml
index 35ebe66e2b..68dfebd1b9 100644
--- a/packages/compact/command-compact/README.i18n.yaml
+++ b/packages/compact/command-compact/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/compact/command-compact/README.md
-README.md: 54f341e39447a423964b7d7435cfb638857eda6e
-README.zh.md: d4a122b8a19cdf907212ad019b2528ae52d03886
+README.md: 5af39e82928d64c11474199b6b30058e9d289f45
+README.zh.md: a582bd5272b2e39ac1ffbf839888a4006b6d44bc
diff --git a/packages/compact/command-compact/README.md b/packages/compact/command-compact/README.md
index 54f341e394..5af39e8292 100644
--- a/packages/compact/command-compact/README.md
+++ b/packages/compact/command-compact/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Human-facing `/compact` control over [`ctx.compact`](../compact/README.md). The plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [queued manual compaction Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md) owns the admission, lock, and durability decisions.
+Human-facing `/compact` control over [`ctx.compact`](../compact/README.md). The plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [queued manual compaction Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md) owns the admission, lock, and durability decisions.
 
 ## Command contract
 
diff --git a/packages/compact/command-compact/README.zh.md b/packages/compact/command-compact/README.zh.md
index d4a122b8a1..a582bd5272 100644
--- a/packages/compact/command-compact/README.zh.md
+++ b/packages/compact/command-compact/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-通过 [`ctx.compact`](../compact/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
+通过 [`ctx.compact`](../compact/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
 
 ## 命令契约
 
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 07a3efd5c3..182ac31809 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-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/credentials/credentials-local/README.md
-README.md: 8e95a890a8e38172cf8984653a01c59570f0061a
-README.zh.md: 04ad07ae4e703ab0416d1d8f1bb6a6ff90adf337
+README.md: 6051c07628c0214f9396d12554719c5614610826
+README.zh.md: c6f3901af925d4bd31d2dcfbf5f5f65de62dac81
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 8e95a890a8..6051c07628 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -51,7 +51,7 @@ External edits publish `credentials/updated` per changed reference after the sna
 
 ## Security boundary
 
-The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Harness-home layers](../../ui/app-boot/README.md#profiles)) — so reaching the value takes a deliberate read of a path the agent was not given.
+The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Harness-home layers](../../boot/app-boot/README.md#profiles)) — so reaching the value takes a deliberate read of a path the agent was not given.
 
 That is discretion, not a boundary. A deployment that must keep provider keys away from its own agent cannot get there with file permissions; an OS-keychain provider — a store the model's processes cannot read at all — is the deferred answer and belongs beside this provider as a sibling package.
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 04ad07ae4e..c6f3901af9 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -51,7 +51,7 @@ OPENAI_API_KEY: sk-…
 
 ## 安全边界
 
-文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../ui/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../boot/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
 
 这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串提供方——一个模型的进程根本读不到的存储——才是延后的答案，它应当作为平级包与本提供方并列。
 
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index 4e7935dd3a..c47938ce3b 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/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/examples/jsonrpc-demo/README.md
-README.md: 2cc496da3e22baf9e87afe4c3ca183ae3f16a5ae
-README.zh.md: 98d397b3c346ee47e9a667b2ccec0179f009a05b
+README.md: fff8e78698cd3d6320606084ef5c533be7c52633
+README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
diff --git a/packages/examples/jsonrpc-demo/README.md b/packages/examples/jsonrpc-demo/README.md
index 2cc496da3e..fff8e78698 100644
--- a/packages/examples/jsonrpc-demo/README.md
+++ b/packages/examples/jsonrpc-demo/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../ui/jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published bin is `dsh-jsonrpc-agent`, and `lib/bin.js` also ships as the `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) used by the Python SDK.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../scaffold/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published bin is `dsh-jsonrpc-agent`, and `lib/bin.js` also ships as the `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) used by the Python SDK.
 
 ## Config discovery
 
-The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../ui/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
+The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../boot/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
 
 A config without `dsh-jsonrpc` is valid and serves nothing; the bin does not designate a server plugin.
 
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 98d397b3c3..75382b97ea 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../ui/jsonrpc/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
 
 ## 配置发现
 
-第一个非空通道生效：先 `$DSH_CORDIS_CONFIG`，再位置参数 `argv[2]`。如果二者都没有指向现有文件，bin 会向 stderr 打印单行用法并以 1 退出；没有工作目录回退或内置回退。[`dsh-app-boot`](../../ui/app-boot/README.md) 会使插件加载失败成为致命错误。此协议不使用 `DSH_SNAPSHOT`。
+第一个非空通道生效：先 `$DSH_CORDIS_CONFIG`，再位置参数 `argv[2]`。如果二者都没有指向现有文件，bin 会向 stderr 打印单行用法并以 1 退出；没有工作目录回退或内置回退。[`dsh-app-boot`](../../boot/app-boot/README.md) 会使插件加载失败成为致命错误。此协议不使用 `DSH_SNAPSHOT`。
 
 不含 `dsh-jsonrpc` 的配置仍然有效，只是不提供任何服务；bin 不会指定服务器插件。
 
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index 4ad5a93fb5..d0fe492135 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/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/feedback/README.md
-README.md: d2a4a5a27e1c661d2f62b328578fd890a0c622ee
-README.zh.md: 2fa42e3bb5f05dfc425356f302f44e497b100f24
+README.md: af8e9d5c4903594299284d09f880aa8929f5e051
+README.zh.md: 01a26798d0b7dc8b376929252a60a99fff11b640
diff --git a/packages/feedback/README.md b/packages/feedback/README.md
index d2a4a5a27e..af8e9d5c49 100644
--- a/packages/feedback/README.md
+++ b/packages/feedback/README.md
@@ -8,4 +8,4 @@ The feedback family lets a human record a remark about the session without actin
 |---|---|---|
 | `command-feedback/` | Trigger-independent `feedback/record` event plus the human-facing `/feedback` producer | — |
 
-A recorded remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
+A recorded remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../session/session-telemetry-otel) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index 2fa42e3bb5..01a26798d0 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -8,4 +8,4 @@ feedback 家族让人类记录对会话的评价，但不据此采取任何动
 |---|---|---|
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 
-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
+被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index ad645a61d3..20eb2741d6 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/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/feedback/command-feedback/README.md
-README.md: 1923267eb3a25a4be564fa4f4535f7a3459ca481
-README.zh.md: 674665167030aa6214e9acaa7e6f5314a78c5b14
+README.md: e2eb6d4cf2b40e83efad1fa158edd72578658f56
+README.zh.md: f87067d67cf9dcb8f4da97afe3a9d59eb828faf7
diff --git a/packages/feedback/command-feedback/README.md b/packages/feedback/command-feedback/README.md
index 1923267eb3..e2eb6d4cf2 100644
--- a/packages/feedback/command-feedback/README.md
+++ b/packages/feedback/command-feedback/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Trigger-independent session feedback plus human-facing `/feedback` capture. The package exports `recordFeedback(session, text)`, which appends one log-only `feedback/record` event. Its plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers it; the shipped Web client executes it without a model turn.
+Trigger-independent session feedback plus human-facing `/feedback` capture. The package exports `recordFeedback(session, text)`, which appends one log-only `feedback/record` event. Its plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers it; the shipped Web client executes it without a model turn.
 
 ## Command contract
 
@@ -15,9 +15,9 @@ Surrounding whitespace is discarded, but feedback is otherwise unparsed: no trun
 
 ## What this plugin does and does not do
 
-`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) consumer observes the event without changing its capture contract.
+`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) consumer observes the event without changing its capture contract.
 
-The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../ui/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.
+The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../interaction/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.
 
 The event is authoritative rather than the command record because feedback may arrive through a trigger other than `/feedback`. Keeping the payload out of `command/run` avoids two records carrying the same text.
 
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index 6746651670..f87067d67c 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
+与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
 
 ## 命令契约
 
@@ -15,9 +15,9 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) 消费方会观察该事件，但不改变它的采集契约。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集契约。
 
-反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../ui/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
+反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
 权威记录是该事件，而不是命令记录，因为反馈可能来自 `/feedback` 之外的触发方式。让载荷不进入 `command/run`，可避免两条记录携带相同文本。
 
diff --git a/packages/feedback/command-feedback/tsconfig.json b/packages/feedback/command-feedback/tsconfig.json
index 0a99f13f01..f59431af9a 100644
--- a/packages/feedback/command-feedback/tsconfig.json
+++ b/packages/feedback/command-feedback/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../core/session"
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 6586a5eda8..8f238d7429 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/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/goal/command-goal/README.md
-README.md: a02803b3ef7f93f0c4910ec2be662cc7836d9048
-README.zh.md: 9c6d0cc6e7309a138e17f1a2d5ad6c5285913394
+README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
+README.zh.md: cc5f7ba9bd3c5e50d3b7ce204d8d8c400e4f0955
diff --git a/packages/goal/command-goal/README.md b/packages/goal/command-goal/README.md
index a02803b3ef..1ac1b8a0e2 100644
--- a/packages/goal/command-goal/README.md
+++ b/packages/goal/command-goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Human-facing `/goal` control over [`ctx.goals`](../goal/README.md). The plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [human goal-command Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) owns the UX and composition decisions.
+Human-facing `/goal` control over [`ctx.goals`](../goal/README.md). The plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [human goal-command Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) owns the UX and composition decisions.
 
 ## Command contract
 
diff --git a/packages/goal/command-goal/README.zh.md b/packages/goal/command-goal/README.zh.md
index 9c6d0cc6e7..cc5f7ba9bd 100644
--- a/packages/goal/command-goal/README.zh.md
+++ b/packages/goal/command-goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md)负责用户体验与组合决策。
+面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md)负责用户体验与组合决策。
 
 ## 命令契约
 
diff --git a/packages/guard/timeout-policy/src/index.ts b/packages/guard/timeout-policy/src/index.ts
index 1c18fa5e13..f554b1a93e 100644
--- a/packages/guard/timeout-policy/src/index.ts
+++ b/packages/guard/timeout-policy/src/index.ts
@@ -6,7 +6,7 @@
  * FIXME: settle the intended `@deepseek-ai/dsh-timeout-guard` rename before the
  * first tagged release — suggestion only, aligning the name with its `guard/`
  * home; decide at resolution time
- * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-timeout-policy
  */
diff --git a/packages/interaction/permission/README.i18n.yaml b/packages/interaction/permission/README.i18n.yaml
index 34533f9da4..c8e4b28311 100644
--- a/packages/interaction/permission/README.i18n.yaml
+++ b/packages/interaction/permission/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/interaction/permission/README.md
 README.md: 4f7f560bb81eaad3b6b95b2742432fa252682d5a
-README.zh.md: 79d0ce9c095d3426f3219f04d9cb7ec3b161a184
+README.zh.md: d45f89e243ce2d8f6bb08943fb7e776ced106b5a
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index feab1813a7..aafe594c7e 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
-README.md: d62e75d110b8be339c5f9449b0834320f695ac99
-README.zh.md: 55258e85e56df2375ed8f195fa0b3b731a9cb816
+README.md: cba015e782623b3a5adf018303823577a0b96774
+README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index b24d4b1954..86afdb6310 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/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/plan/plan-mode/README.md
-README.md: f2a78fe98b6a85ce91d727e95ddf62e6f77546b7
-README.zh.md: e1b5f111fd8f761fdd8f25558463c0cc327a14be
+README.md: 6c8ba23b76e83665d4f8dcb5ecb41689347f6423
+README.zh.md: b306d5562af21dd9a95bb68c9acfc3f40c52136f
diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md
index f2a78fe98b..6c8ba23b76 100644
--- a/packages/plan/plan-mode/README.md
+++ b/packages/plan/plan-mode/README.md
@@ -22,7 +22,7 @@ The Web client consumes the plugin-owned `/plan` command; other front doors may
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, keeping the logged request and the run plane from forking). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, keeping the logged request and the run plane from forking). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
 
 ## Configuration
 
diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md
index e1b5f111fd..b306d5562a 100644
--- a/packages/plan/plan-mode/README.zh.md
+++ b/packages/plan/plan-mode/README.zh.md
@@ -22,7 +22,7 @@ Web 客户端使用该插件提供的 `/plan` 命令；其他入口可以直接
 
 ## 会话投影
 
-当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。该单元折叠两类事件：名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会设置目标状态（`off` → 未激活，其余 → 激活），`plan/mode` 会提交已记录状态并清除该目标；其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在尚未落实的选择与已记录状态不同时为 true。该值完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它。`/plan` 处理器会在任何可能失败的路径之前调用 `set()`，避免已写入日志的请求与运行面分叉。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
+当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。该单元折叠两类事件：名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会设置目标状态（`off` → 未激活，其余 → 激活），`plan/mode` 会提交已记录状态并清除该目标；其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在尚未落实的选择与已记录状态不同时为 true。该值完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它。`/plan` 处理器会在任何可能失败的路径之前调用 `set()`，避免已写入日志的请求与运行面分叉。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
 
 ## 配置
 
diff --git a/packages/scaffold/README.i18n.yaml b/packages/scaffold/README.i18n.yaml
index 1480a14b69..7ddc22328c 100644
--- a/packages/scaffold/README.i18n.yaml
+++ b/packages/scaffold/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/scaffold/README.md
-README.md: b166a351a53afe075ecb794fe2bf6f0702a435ae
-README.zh.md: 6e2a65ea554487f48563c16e1defa37ef1a5e043
+README.md: 19c2f28f48d1c2d8747b635c10d6781c29e02f15
+README.zh.md: ecad2592eb32a30444f9112571379939da6afeec
diff --git a/packages/scaffold/README.md b/packages/scaffold/README.md
index b166a351a5..19c2f28f48 100644
--- a/packages/scaffold/README.md
+++ b/packages/scaffold/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md).
+This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
 
 | Package | Role |
 |---|---|
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
index 6e2a65ea55..ecad2592eb 100644
--- a/packages/scaffold/README.zh.md
+++ b/packages/scaffold/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
+本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
 
 | 包 | 职责 |
 |---|---|
diff --git a/packages/scaffold/client/README.i18n.yaml b/packages/scaffold/client/README.i18n.yaml
index 0a71141cd6..c08016649d 100644
--- a/packages/scaffold/client/README.i18n.yaml
+++ b/packages/scaffold/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/scaffold/client/README.md
-README.md: f27ec256330254156c45b136c21308529ea99e3d
-README.zh.md: bd23762500a4da469839da8ddb50455e3419b553
+README.md: b33457875f81d11d09bab2e5aa5ce730e233c78a
+README.zh.md: 271f07ffb0f97abe005971962beb517acfdc05a4
diff --git a/packages/scaffold/client/README.md b/packages/scaffold/client/README.md
index f27ec25633..b33457875f 100644
--- a/packages/scaffold/client/README.md
+++ b/packages/scaffold/client/README.md
@@ -44,6 +44,6 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No bundled-runtime resolution** — callers name the runtime executable explicitly; packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists.
-- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../sdk-protocol/README.md)).
+- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../protocol/README.md)).
 - **No per-prompt result or cancel** — low-level `prompt()` returns only an enqueue receipt; high-level `run()` owns receipt-to-idle collection, and abandoning it means closing the runtime.
 - **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows.
diff --git a/packages/scaffold/client/README.zh.md b/packages/scaffold/client/README.zh.md
index bd23762500..271f07ffb0 100644
--- a/packages/scaffold/client/README.zh.md
+++ b/packages/scaffold/client/README.zh.md
@@ -44,6 +44,6 @@ console.log(result.finalResponse)
 ## 已知限制与暂缓事项
 
 - **无捆绑运行时解析**——调用方显式指定运行时可执行文件；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费方。
-- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../sdk-protocol/README.md)）。
+- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../protocol/README.md)）。
 - **没有逐提示词结果或取消**——低层 `prompt()` 只返回入队回执；高层 `run()` 负责从回执收集到 idle，放弃该过程意味着关闭运行时。
 - **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现；传输层为未来审批流保留了承载能力。
diff --git a/packages/scaffold/helper/src/index.ts b/packages/scaffold/helper/src/index.ts
index 8c8e0db4b9..db4468aae5 100644
--- a/packages/scaffold/helper/src/index.ts
+++ b/packages/scaffold/helper/src/index.ts
@@ -3,7 +3,7 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-helper` before the first tagged release —
  * the current name is indefensibly generic as a published name
- * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-helper
  */
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
index b77c8fce63..719a135b37 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/scaffold/protocol/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/scaffold/protocol/README.md
-README.md: 35b62d2ffc43c54dc81f6a5ecfb1a0ef4294439d
-README.zh.md: a02ba94e7d8fae19bff48d8fda363e23fc173850
+README.md: 88a48957d0d44cec9f776d31eab7d25bd353de5f
+README.zh.md: c662d28ec6eea5fe4829030daf210a91fd70ff0f
diff --git a/packages/scaffold/protocol/README.md b/packages/scaffold/protocol/README.md
index b8420eb19a..88a48957d0 100644
--- a/packages/scaffold/protocol/README.md
+++ b/packages/scaffold/protocol/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../../scaffold/server/README.md) plugin; clients are [`dsh-sdk-client`](../client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
+The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../server/README.md) plugin; clients are [`dsh-sdk-client`](../client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
 
 ## Transport
 
@@ -26,7 +26,7 @@ The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delim
 
 ## Model Experience
 
-None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../scaffold/server/README.md) entry.
+None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../server/README.md) entry.
 
 #### KV Cache effect
 
@@ -35,5 +35,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No protocol-version negotiation** — the handshake carries only `serverInfo.version` (`0.0.1`, unvalidated by clients); pre-release stance, no compatibility promise.
-- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../scaffold/server/README.md).
+- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../server/README.md).
 - **Server→client requests are dead capability** — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.
diff --git a/packages/scaffold/protocol/README.zh.md b/packages/scaffold/protocol/README.zh.md
index bc459f8817..c662d28ec6 100644
--- a/packages/scaffold/protocol/README.zh.md
+++ b/packages/scaffold/protocol/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按换行分帧的 JSON-RPC 2.0 传输类，加上协议两端共同使用的具名请求、结果与通知类型。包根枚举协议消费方接口；源模块不支持深层导入。服务端是 [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) 插件；客户端是 [`dsh-sdk-client`](../sdk-client/README.md)（TypeScript）与 [Python SDK](../../../python/README.md)（后者复现这些结构但不导入它们）。纯库——无插件、无 Config、无注册。
+DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按换行分帧的 JSON-RPC 2.0 传输类，加上协议两端共同使用的具名请求、结果与通知类型。包根枚举协议消费方接口；源模块不支持深层导入。服务端是 [`dsh-jsonrpc`](../server/README.md) 插件；客户端是 [`dsh-sdk-client`](../client/README.md)（TypeScript）与 [Python SDK](../../../python/README.md)（后者复现这些结构但不导入它们）。纯库——无插件、无 Config、无注册。
 
 ## 传输
 
@@ -26,7 +26,7 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 
 ## 模型体验
 
-无，因为此包定义面向客户端的协议格式；模型可见接口属于组合在对外服务入口 [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) 后方的运行时插件。
+无，因为此包定义面向客户端的协议格式；模型可见接口属于组合在对外服务入口 [`dsh-jsonrpc`](../server/README.md) 后方的运行时插件。
 
 #### KV Cache 影响
 
@@ -35,5 +35,5 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 ## 已知限制与暂缓事项
 
 - **无协议版本协商**——握手只携带 `serverInfo.version`（`0.0.1`，客户端不校验）；处于预发布阶段，无兼容承诺。
-- **无取消与会话关闭方法**——客户端放弃轮次的方式是关闭运行时进程；见 [`dsh-jsonrpc` README](../../ui/jsonrpc/README.md)。
+- **无取消与会话关闭方法**——客户端放弃轮次的方式是关闭运行时进程；见 [`dsh-jsonrpc` README](../server/README.md)。
 - **server→client 请求是未使用的功能**——传输层支持，但服务器从不发送；Python SDK 的应答接口为未来审批流程预留。
diff --git a/packages/scaffold/scripts/src/index.ts b/packages/scaffold/scripts/src/index.ts
index 0af3ef0b30..0db62945f9 100644
--- a/packages/scaffold/scripts/src/index.ts
+++ b/packages/scaffold/scripts/src/index.ts
@@ -3,7 +3,7 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-scripts` before the first tagged release —
  * the current name is indefensibly generic as a published name
- * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-scripts
  */
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
index 46a18ec199..fc60d047d1 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/scaffold/server/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/scaffold/server/README.md
-README.md: e0e06e27320ab41f131a1a36a7ccbd26271ce67c
-README.zh.md: ed87a869180571a3cbb51c2ce92a0647e545ca3a
+README.md: 0afb3a38ece57f74729a218dc85348fa6c7fa529
+README.zh.md: 5305434abbd83eb230dcdd81e72120d96da26cda
diff --git a/packages/scaffold/server/src/index.ts b/packages/scaffold/server/src/index.ts
index 9985cadfb4..f0261e1a21 100644
--- a/packages/scaffold/server/src/index.ts
+++ b/packages/scaffold/server/src/index.ts
@@ -8,7 +8,7 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-server` before the first tagged release —
  * the current name says the wire encoding, not the role; it is the server half of
- * the SDK protocol ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * the SDK protocol ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-jsonrpc
  */
diff --git a/packages/scaffold/telemetry/src/index.ts b/packages/scaffold/telemetry/src/index.ts
index 17ea1d02c7..3c0a5beae7 100644
--- a/packages/scaffold/telemetry/src/index.ts
+++ b/packages/scaffold/telemetry/src/index.ts
@@ -9,7 +9,8 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-telemetry` before the first tagged release —
  * the current name collides with the `dsh-session-telemetry` family; this is
- * launcher-side SDK telemetry ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * launcher-side SDK telemetry
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-telemetry
  */
diff --git a/packages/subagent/subagent-codex/tsconfig.json b/packages/subagent/subagent-codex/tsconfig.json
index b9f33967ba..3bb974477e 100644
--- a/packages/subagent/subagent-codex/tsconfig.json
+++ b/packages/subagent/subagent-codex/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../llm/llm"
     },
     {
-      "path": "../../sdk/sdk-protocol"
+      "path": "../../scaffold/protocol"
     },
     {
       "path": "../../core/session"
diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json
index ccfecc02e4..c72f2ef68d 100644
--- a/packages/subagent/subagent/tsconfig.json
+++ b/packages/subagent/subagent/tsconfig.json
@@ -30,10 +30,10 @@
       "path": "../../session/session-persistence"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
-      "path": "../../session-projection/session-projection-cache"
+      "path": "../../session/session-projection-cache"
     },
     {
       "path": "../../tasks/tasks"
diff --git a/packages/typert/generator/tests/type-model.spec.ts b/packages/typert/generator/tests/type-model.spec.ts
index e1b5d99de9..f8c41fb157 100644
--- a/packages/typert/generator/tests/type-model.spec.ts
+++ b/packages/typert/generator/tests/type-model.spec.ts
@@ -1264,14 +1264,14 @@ function configureDualRuntimeClient(root: string, splitProjects: boolean): void
   const hostAggregate = JSON.parse(readFileSync(hostAggregatePath, 'utf8')) as {
     references: { path: string }[]
   }
-  hostAggregate.references.push({ path: './packages/client/tsconfig.host.json' })
+  hostAggregate.references.push({ path: ['.', 'packages', 'client', 'tsconfig.host.json'].join('/') })
   writeFileSync(hostAggregatePath, `${JSON.stringify(hostAggregate, null, 2)}\n`)
 
   const clientAggregatePath = join(root, 'tsconfig.client.json')
   const clientAggregate = JSON.parse(readFileSync(clientAggregatePath, 'utf8')) as {
     references: { path: string }[]
   }
-  clientAggregate.references = [{ path: './packages/client/tsconfig.client.json' }]
+  clientAggregate.references = [{ path: ['.', 'packages', 'client', 'tsconfig.client.json'].join('/') }]
   writeFileSync(clientAggregatePath, `${JSON.stringify(clientAggregate, null, 2)}\n`)
 }
 
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 1c5f784bc4..633064ae4c 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
-README.md: af6b0d9cc66b0bdfa1ad9ffb273260d0f4f06ddc
-README.zh.md: 98c3c69ec96f835721e042960fe044fe075e6159
+README.md: 599a9ba747905b66452b57717dabcc6f4678a3dd
+README.zh.md: 69f9c670bbb3ea1b2fbddaa7508a19dfb47fad12
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index af6b0d9cc6..599a9ba747 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -32,5 +32,5 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 ## Known Limitations and Deferred Work
 
-- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. The product launcher's [`.env` contract](../../ui/app-boot/README.md#profiles) rejects bootstrap variables before materialization.
+- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. The product launcher's [`.env` contract](../../boot/app-boot/README.md#profiles) rejects bootstrap variables before materialization.
 - **No per-workspace layer** — the project layer is the *invoking* directory, fixed at launch. A workspace selected later in the Web UI contributes nothing, deliberately: following it would let a model's own workspace change the harness environment mid-session.
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 98c3c69ec9..69f9c670bb 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -32,5 +32,5 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 ## Known Limitations and Deferred Work
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../ui/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a92883786a..e9726e9bee 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -142,7 +142,7 @@ importers:
         version: link:../../vendor/timer
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../packages/ui/app-boot
+        version: link:../../packages/boot/app-boot
       '@deepseek-ai/dsh-base':
         specifier: workspace:^
         version: link:../../packages/bundle/base
@@ -169,13 +169,13 @@ importers:
         version: link:../../packages/context/tmux-context
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
-        version: link:../../packages/ui/tool-ask-user
+        version: link:../../packages/interaction/tool-ask-user
       '@deepseek-ai/dsh-tool-bash-persistent':
         specifier: workspace:^
         version: link:../../packages/pty/tool-bash-persistent
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:^
-        version: link:../../packages/cordis/tool-cordis
+        version: link:../../packages/self-modification/tool-cordis
       '@deepseek-ai/dsh-web-app':
         specifier: workspace:^
         version: link:../../packages/bundle/web-app
@@ -309,7 +309,7 @@ importers:
         version: link:../packages/examples/agent-spine-demo
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:*
-        version: link:../packages/ui/app-boot
+        version: link:../packages/boot/app-boot
       '@deepseek-ai/dsh-bash':
         specifier: workspace:*
         version: link:../packages/bash/bash
@@ -333,7 +333,7 @@ importers:
         version: link:../packages/goal/command-goal
       '@deepseek-ai/dsh-commands':
         specifier: workspace:*
-        version: link:../packages/ui/commands
+        version: link:../packages/interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:*
         version: link:../packages/compact/compact
@@ -378,7 +378,7 @@ importers:
         version: link:../packages/support/invariants
       '@deepseek-ai/dsh-jsonrpc':
         specifier: workspace:*
-        version: link:../packages/ui/jsonrpc
+        version: link:../packages/scaffold/server
       '@deepseek-ai/dsh-llm':
         specifier: workspace:*
         version: link:../packages/llm/llm
@@ -402,7 +402,7 @@ importers:
         version: link:../packages/lsp/lsp-local
       '@deepseek-ai/dsh-permission':
         specifier: workspace:*
-        version: link:../packages/ui/permission
+        version: link:../packages/interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:*
         version: link:../packages/plan/plan-mode
@@ -420,7 +420,7 @@ importers:
         version: link:../packages/guard/repeat-tool-guard
       '@deepseek-ai/dsh-repository-plugin':
         specifier: workspace:*
-        version: link:../packages/cordis/repository-plugin
+        version: link:../packages/self-modification/repository-plugin
       '@deepseek-ai/dsh-sandbox':
         specifier: workspace:*
         version: link:../packages/sandbox/sandbox
@@ -438,13 +438,13 @@ importers:
         version: link:../packages/core/session
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:*
-        version: link:../packages/session-persistence/session-checkpoint-policy
+        version: link:../packages/session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:*
-        version: link:../packages/session-persistence/session-persistence-jsonl
+        version: link:../packages/session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:*
-        version: link:../packages/session-projection/session-projection
+        version: link:../packages/session/session-projection
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:*
         version: link:../packages/session-query/session-query
@@ -456,13 +456,13 @@ importers:
         version: link:../packages/context/session-reference
       '@deepseek-ai/dsh-session-telemetry-otel':
         specifier: workspace:*
-        version: link:../packages/telemetry/session-telemetry-otel
+        version: link:../packages/session/session-telemetry-otel
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:*
-        version: link:../packages/session-title/session-title
+        version: link:../packages/session/session-title
       '@deepseek-ai/dsh-session-title-first-message-llm':
         specifier: workspace:*
-        version: link:../packages/session-title/session-title-first-message-llm
+        version: link:../packages/session/session-title-first-message-llm
       '@deepseek-ai/dsh-settings-local':
         specifier: workspace:*
         version: link:../packages/settings/settings-local
@@ -516,13 +516,13 @@ importers:
         version: link:../packages/context/time-context
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:*
-        version: link:../packages/timeout/timeout-policy
+        version: link:../packages/guard/timeout-policy
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:*
         version: link:../packages/llm/token-meter
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:*
-        version: link:../packages/ui/tool-ask-user
+        version: link:../packages/interaction/tool-ask-user
       '@deepseek-ai/dsh-tool-bash':
         specifier: workspace:*
         version: link:../packages/bash/tool-bash
@@ -531,7 +531,7 @@ importers:
         version: link:../packages/pty/tool-bash-persistent
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:*
-        version: link:../packages/cordis/tool-cordis
+        version: link:../packages/self-modification/tool-cordis
       '@deepseek-ai/dsh-tool-fs':
         specifier: workspace:*
         version: link:../packages/fs/tool-fs
@@ -588,10 +588,10 @@ importers:
         version: link:../packages/core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:*
-        version: link:../packages/ui/user-approval
+        version: link:../packages/interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:*
-        version: link:../packages/ui/user-interaction
+        version: link:../packages/interaction/user-interaction
       '@deepseek-ai/dsh-web':
         specifier: workspace:*
         version: link:../packages/web/web
@@ -665,7 +665,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -715,7 +715,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-typert-registry':
         specifier: workspace:^
         version: link:../../typert/registry
@@ -761,7 +761,7 @@ importers:
         version: link:../../util/paths
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -890,7 +890,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:^
         version: link:../../subprocess/subprocess-local
@@ -911,7 +911,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -965,6 +965,43 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/boot/app-boot:
+    dependencies:
+      js-yaml:
+        specifier: ^4.2.0
+        version: 4.2.0
+    devDependencies:
+      '@cordisjs/plugin-hmr':
+        specifier: workspace:^
+        version: link:../../../vendor/hmr
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@cordisjs/plugin-timer':
+        specifier: workspace:^
+        version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-paths':
+        specifier: workspace:^
+        version: link:../../util/paths
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/bundle/base:
     dependencies:
       '@cordisjs/plugin-hmr':
@@ -999,7 +1036,7 @@ importers:
         version: link:../../goal/command-goal
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact-basic':
         specifier: workspace:^
         version: link:../../compact/compact-basic
@@ -1035,7 +1072,7 @@ importers:
         version: link:../../llm/llm-retry
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../ui/permission
+        version: link:../../interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:^
         version: link:../../plan/plan-mode
@@ -1044,7 +1081,7 @@ importers:
         version: link:../../guard/repeat-tool-guard
       '@deepseek-ai/dsh-repository-plugin':
         specifier: workspace:^
-        version: link:../../cordis/repository-plugin
+        version: link:../../self-modification/repository-plugin
       '@deepseek-ai/dsh-sandbox-local':
         specifier: workspace:^
         version: link:../../sandbox/sandbox-local
@@ -1056,25 +1093,25 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:^
-        version: link:../../session-persistence/session-checkpoint-policy
+        version: link:../../session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-query-sqlite':
         specifier: workspace:^
         version: link:../../session-query/session-query-sqlite
       '@deepseek-ai/dsh-session-telemetry-otel':
         specifier: workspace:^
-        version: link:../../telemetry/session-telemetry-otel
+        version: link:../../session/session-telemetry-otel
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       '@deepseek-ai/dsh-session-title-first-message-llm':
         specifier: workspace:^
-        version: link:../../session-title/session-title-first-message-llm
+        version: link:../../session/session-title-first-message-llm
       '@deepseek-ai/dsh-settings-local':
         specifier: workspace:^
         version: link:../../settings/settings-local
@@ -1113,7 +1150,7 @@ importers:
         version: link:../../tasks/tasks-local
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../timeout/timeout-policy
+        version: link:../../guard/timeout-policy
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../llm/token-meter
@@ -1170,10 +1207,10 @@ importers:
         version: link:../../typert/registry
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       '@deepseek-ai/dsh-web':
         specifier: workspace:^
         version: link:../../web/web
@@ -1328,7 +1365,7 @@ importers:
         version: link:../../host/webserver
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection-cache
+        version: link:../../session/session-projection-cache
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -1362,7 +1399,7 @@ importers:
     dependencies:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-host-apiproxy':
         specifier: workspace:^
         version: link:../../host/apiproxy
@@ -1466,7 +1503,7 @@ importers:
         version: link:../ui-slots
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../../compact/compact
@@ -1484,10 +1521,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       immer:
         specifier: ^10.1.1
         version: 10.2.0
@@ -1651,13 +1688,13 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../ui/permission
+        version: link:../../interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:^
         version: link:../../plan/plan-mode
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../llm/token-meter
@@ -1895,7 +1932,7 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../ui/permission
+        version: link:../../interaction/permission
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
@@ -2043,7 +2080,7 @@ importers:
         version: link:../ui-slots
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
-        version: link:../../ui/tool-ask-user
+        version: link:../../interaction/tool-ask-user
       clsx:
         specifier: ^2.0.0
         version: 2.1.1
@@ -2068,7 +2105,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
@@ -2614,7 +2651,7 @@ importers:
         version: link:../../core/agent
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../compact
@@ -2871,83 +2908,6 @@ importers:
         specifier: ^4.0.0-rc.6
         version: link:../../../vendor/cordis
 
-  packages/cordis/repository-plugin:
-    dependencies:
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-mcp-client':
-        specifier: workspace:^
-        version: link:../../mcp/mcp-client
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-      '@deepseek-ai/dsh-skill':
-        specifier: workspace:^
-        version: link:../../skill/skill
-      '@deepseek-ai/dsh-skill-local':
-        specifier: workspace:^
-        version: link:../../skill/skill-local
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/cordis/tool-cordis:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: ^1.0.0-rc.5
-        version: link:../../../vendor/loader
-      '@cordisjs/plugin-timer':
-        specifier: workspace:^
-        version: link:../../../vendor/timer
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-agent-loop':
-        specifier: workspace:^
-        version: link:../../core/agent-loop
-      '@deepseek-ai/dsh-agent-loop-testkit':
-        specifier: workspace:^
-        version: link:../../support/agent-loop-testkit
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/core/agent:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -2998,10 +2958,10 @@ importers:
         version: link:../session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../system-prompt
@@ -3093,7 +3053,7 @@ importers:
         version: link:../system-prompt
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -3219,16 +3179,16 @@ importers:
         version: link:../agent-spine-demo
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../ui/app-boot
+        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:^
-        version: link:../../session-persistence/session-checkpoint-policy
+        version: link:../../session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../session-query/session-query
@@ -3316,7 +3276,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       '@deepseek-ai/dsh-skill':
         specifier: workspace:^
         version: link:../../skill/skill
@@ -3367,7 +3327,7 @@ importers:
     dependencies:
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../ui/app-boot
+        version: link:../../boot/app-boot
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -3389,7 +3349,7 @@ importers:
         version: link:../../core/agent
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3532,7 +3492,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -3639,7 +3599,7 @@ importers:
         version: link:../../core/agent
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../goal
@@ -3688,7 +3648,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-type-meta':
         specifier: workspace:^
         version: link:../../typert/type-meta
@@ -3794,6 +3754,24 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/guard/timeout-policy:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/hooks/hook-protocol:
     devDependencies:
       '@deepseek-ai/dsh-bash':
@@ -3844,10 +3822,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../../subagent/subagent
@@ -3896,10 +3874,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:^
         version: link:../../subprocess/subprocess-local
@@ -3923,7 +3901,7 @@ importers:
         version: link:../../util/brand
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../../credentials/credentials
@@ -3944,19 +3922,19 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection-cache
+        version: link:../../session/session-projection-cache
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../session-query/session-query
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       '@deepseek-ai/dsh-settings':
         specifier: workspace:^
         version: link:../../settings/settings
@@ -3971,10 +3949,10 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       '@deepseek-ai/dsh-workspace':
         specifier: workspace:^
         version: link:../../workspace/workspace
@@ -4152,6 +4130,137 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/interaction/commands:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/permission:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@deepseek-ai/dsh-bash':
+        specifier: workspace:^
+        version: link:../../bash/bash
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../commands
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-sandbox':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox
+      '@deepseek-ai/dsh-sandbox-policy':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox-policy
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-projection':
+        specifier: workspace:^
+        version: link:../../session/session-projection
+      '@deepseek-ai/dsh-settings':
+        specifier: workspace:^
+        version: link:../../settings/settings
+      '@deepseek-ai/dsh-user-approval':
+        specifier: workspace:^
+        version: link:../user-approval
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/tool-ask-user:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-user-interaction':
+        specifier: workspace:^
+        version: link:../user-interaction
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/user-approval:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/user-interaction:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/llm/llm:
     dependencies:
       schemastery:
@@ -4274,10 +4383,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
+        version: link:../../session/session-persistence-sqlite
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -4314,7 +4423,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -4415,7 +4524,7 @@ importers:
         version: link:../../util/timeout
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../timeout/timeout-policy
+        version: link:../../guard/timeout-policy
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -4474,7 +4583,7 @@ importers:
         version: link:../../code-runtime/code-runtime
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4486,7 +4595,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -4495,7 +4604,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -4724,7 +4833,25 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/create-sdk:
+  packages/scaffold/client:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-sdk-protocol':
+        specifier: workspace:^
+        version: link:../protocol
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/scaffold/create-sdk:
     dependencies:
       '@deepseek-ai/dsh-helper':
         specifier: workspace:^
@@ -4740,7 +4867,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/helper:
+  packages/scaffold/helper:
     dependencies:
       '@clack/core':
         specifier: ^1.4.3
@@ -4772,10 +4899,10 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
+        version: link:../../session/session-persistence-sqlite
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
@@ -4792,56 +4919,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/scripts:
-    dependencies:
-      '@deepseek-ai/dsh-helper':
-        specifier: workspace:^
-        version: link:../helper
-      '@deepseek-ai/dsh-telemetry':
-        specifier: workspace:^
-        version: link:../telemetry
-      commander:
-        specifier: ^15.0.0
-        version: 15.0.0
-      node-addon-require-builtin:
-        specifier: ^0.1.4
-        version: 0.1.4
-    devDependencies:
-      '@deepseek-ai/dsh-app-boot':
-        specifier: workspace:^
-        version: link:../../ui/app-boot
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-      tsdown:
-        specifier: ^0.22.2
-        version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
-      tsx:
-        specifier: ^4.22.4
-        version: 4.22.4
-
-  packages/sdk/sdk-client:
-    devDependencies:
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-sdk-protocol':
-        specifier: workspace:^
-        version: link:../sdk-protocol
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/sdk/sdk-protocol:
+  packages/scaffold/protocol:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -4859,7 +4937,81 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/telemetry:
+  packages/scaffold/scripts:
+    dependencies:
+      '@deepseek-ai/dsh-helper':
+        specifier: workspace:^
+        version: link:../helper
+      '@deepseek-ai/dsh-telemetry':
+        specifier: workspace:^
+        version: link:../telemetry
+      commander:
+        specifier: ^15.0.0
+        version: 15.0.0
+      node-addon-require-builtin:
+        specifier: ^0.1.4
+        version: 0.1.4
+    devDependencies:
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../boot/app-boot
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+      tsdown:
+        specifier: ^0.22.2
+        version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
+      tsx:
+        specifier: ^4.22.4
+        version: 4.22.4
+
+  packages/scaffold/server:
+    dependencies:
+      schemastery:
+        specifier: ^3.17.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-spine-demo':
+        specifier: workspace:^
+        version: link:../../examples/agent-spine-demo
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-llm-deepseek':
+        specifier: workspace:^
+        version: link:../../llm/llm-deepseek
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-sdk-protocol':
+        specifier: workspace:^
+        version: link:../protocol
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session/session-persistence-jsonl
+      '@deepseek-ai/dsh-subagent':
+        specifier: workspace:^
+        version: link:../../subagent/subagent
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/scaffold/telemetry:
     dependencies:
       yaml:
         specifier: ^2.9.0
@@ -4878,7 +5030,185 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-checkpoint-policy:
+  packages/self-modification/repository-plugin:
+    dependencies:
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-mcp-client':
+        specifier: workspace:^
+        version: link:../../mcp/mcp-client
+      '@deepseek-ai/dsh-paths':
+        specifier: workspace:^
+        version: link:../../util/paths
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../../skill/skill
+      '@deepseek-ai/dsh-skill-local':
+        specifier: workspace:^
+        version: link:../../skill/skill-local
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/self-modification/tool-cordis:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: ^1.0.0-rc.5
+        version: link:../../../vendor/loader
+      '@cordisjs/plugin-timer':
+        specifier: workspace:^
+        version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-agent-loop-testkit':
+        specifier: workspace:^
+        version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session-query/session-query:
+    devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session/session-persistence
+      '@deepseek-ai/dsh-session-title':
+        specifier: workspace:^
+        version: link:../../session/session-title
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session-query/session-query-sqlite:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session/session-persistence
+      '@deepseek-ai/dsh-session-persistence-sqlite':
+        specifier: workspace:^
+        version: link:../../session/session-persistence-sqlite
+      '@deepseek-ai/dsh-session-query':
+        specifier: workspace:^
+        version: link:../session-query
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session-query/tool-session-query:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session/session-persistence
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-query':
+        specifier: workspace:^
+        version: link:../session-query
+      '@deepseek-ai/dsh-session-query-sqlite':
+        specifier: workspace:^
+        version: link:../session-query-sqlite
+      '@deepseek-ai/dsh-session-title':
+        specifier: workspace:^
+        version: link:../../session/session-title
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      '@deepseek-ai/dsh-timeout-policy':
+        specifier: workspace:^
+        version: link:../../guard/timeout-policy
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session/session-checkpoint-policy:
     devDependencies:
       '@cordisjs/plugin-loader':
         specifier: workspace:^
@@ -4917,7 +5247,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-persistence:
+  packages/session/session-persistence:
     devDependencies:
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
@@ -4938,7 +5268,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-persistence-jsonl:
+  packages/session/session-persistence-jsonl:
     dependencies:
       koffi:
         specifier: ^3.1.0
@@ -4960,7 +5290,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-persistence-sqlite:
+  packages/session/session-persistence-sqlite:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -4979,7 +5309,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-projection/session-projection:
+  packages/session/session-projection:
     dependencies:
       zod:
         specifier: ^4.4.3
@@ -4995,7 +5325,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-projection/session-projection-cache:
+  packages/session/session-projection-cache:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5012,7 +5342,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../session-persistence
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
         version: link:../session-projection
@@ -5026,63 +5356,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-query/session-query:
-    devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
-      '@deepseek-ai/dsh-session-title':
-        specifier: workspace:^
-        version: link:../../session-title/session-title
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/session-query/session-query-sqlite:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
-      '@deepseek-ai/dsh-session-persistence-sqlite':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
-      '@deepseek-ai/dsh-session-query':
-        specifier: workspace:^
-        version: link:../session-query
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/session-query/tool-session-query:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
+  packages/session/session-telemetry:
     devDependencies:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
@@ -5090,44 +5364,66 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
-      '@deepseek-ai/dsh-session-persistence-jsonl':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
-      '@deepseek-ai/dsh-session-query':
-        specifier: workspace:^
-        version: link:../session-query
-      '@deepseek-ai/dsh-session-query-sqlite':
-        specifier: workspace:^
-        version: link:../session-query-sqlite
-      '@deepseek-ai/dsh-session-title':
-        specifier: workspace:^
-        version: link:../../session-title/session-title
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-timeout':
-        specifier: workspace:^
-        version: link:../../util/timeout
-      '@deepseek-ai/dsh-timeout-policy':
-        specifier: workspace:^
-        version: link:../../timeout/timeout-policy
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title:
+  packages/session/session-telemetry-otel:
+    dependencies:
+      '@opentelemetry/api':
+        specifier: ^1.9.1
+        version: 1.9.1
+      '@opentelemetry/api-logs':
+        specifier: ^0.220.0
+        version: 0.220.0
+      '@opentelemetry/exporter-logs-otlp-http':
+        specifier: ^0.220.0
+        version: 0.220.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-exporter-base':
+        specifier: ^0.220.0
+        version: 0.220.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources':
+        specifier: ^2.9.0
+        version: 2.10.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs':
+        specifier: ^0.220.0
+        version: 0.220.0(@opentelemetry/api@1.9.1)
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:^
+        version: link:../../feedback/command-feedback
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-paths':
+        specifier: workspace:^
+        version: link:../../util/paths
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-telemetry':
+        specifier: workspace:^
+        version: link:../session-telemetry
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session/session-title:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5150,18 +5446,18 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
+        version: link:../session-persistence-sqlite
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../session-projection
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title-all-messages-llm:
+  packages/session/session-title-all-messages-llm:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5186,7 +5482,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title-first-message-llm:
+  packages/session/session-title-first-message-llm:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5220,7 +5516,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title-llm:
+  packages/session/session-title-llm:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5541,13 +5837,13 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection-cache
+        version: link:../../session/session-projection-cache
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -5673,7 +5969,7 @@ importers:
         version: link:../../support/loader-smoke
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../sdk/sdk-protocol
+        version: link:../../scaffold/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -5719,10 +6015,10 @@ importers:
         version: link:../../support/loader-smoke
       '@deepseek-ai/dsh-sdk-client':
         specifier: workspace:^
-        version: link:../../sdk/sdk-client
+        version: link:../../scaffold/client
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../sdk/sdk-protocol
+        version: link:../../scaffold/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -5816,7 +6112,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -5896,10 +6192,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -5947,13 +6243,13 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -5993,10 +6289,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -6231,91 +6527,6 @@ importers:
         specifier: ^4.0.0-rc.6
         version: link:../../../vendor/cordis
 
-  packages/telemetry/session-telemetry:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/telemetry/session-telemetry-otel:
-    dependencies:
-      '@opentelemetry/api':
-        specifier: ^1.9.1
-        version: 1.9.1
-      '@opentelemetry/api-logs':
-        specifier: ^0.220.0
-        version: 0.220.0
-      '@opentelemetry/exporter-logs-otlp-http':
-        specifier: ^0.220.0
-        version: 0.220.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/otlp-exporter-base':
-        specifier: ^0.220.0
-        version: 0.220.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/resources':
-        specifier: ^2.9.0
-        version: 2.10.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/sdk-logs':
-        specifier: ^0.220.0
-        version: 0.220.0(@opentelemetry/api@1.9.1)
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-command-feedback':
-        specifier: workspace:^
-        version: link:../../feedback/command-feedback
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-telemetry':
-        specifier: workspace:^
-        version: link:../session-telemetry
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/timeout/timeout-policy:
-    devDependencies:
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-timeout':
-        specifier: workspace:^
-        version: link:../../util/timeout
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/todo/tool-todo:
     dependencies:
       schemastery:
@@ -6354,7 +6565,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -6363,7 +6574,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -6382,7 +6593,7 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:^
-        version: link:../../cordis/tool-cordis
+        version: link:../../self-modification/tool-cordis
       '@deepseek-ai/dsh-typert-registry':
         specifier: workspace:^
         version: link:../registry
@@ -6440,217 +6651,6 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/ui/app-boot:
-    dependencies:
-      js-yaml:
-        specifier: ^4.2.0
-        version: 4.2.0
-    devDependencies:
-      '@cordisjs/plugin-hmr':
-        specifier: workspace:^
-        version: link:../../../vendor/hmr
-      '@cordisjs/plugin-include':
-        specifier: workspace:^
-        version: link:../../../vendor/include
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@cordisjs/plugin-timer':
-        specifier: workspace:^
-        version: link:../../../vendor/timer
-      '@deepseek-ai/dsh-environment':
-        specifier: workspace:^
-        version: link:../../util/environment
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@types/js-yaml':
-        specifier: ^4.0.9
-        version: 4.0.9
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/commands:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/jsonrpc:
-    dependencies:
-      schemastery:
-        specifier: ^3.17.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-agent-spine-demo':
-        specifier: workspace:^
-        version: link:../../examples/agent-spine-demo
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-llm-deepseek':
-        specifier: workspace:^
-        version: link:../../llm/llm-deepseek
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-sdk-protocol':
-        specifier: workspace:^
-        version: link:../../sdk/sdk-protocol
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence-jsonl':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
-      '@deepseek-ai/dsh-subagent':
-        specifier: workspace:^
-        version: link:../../subagent/subagent
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/permission:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-    devDependencies:
-      '@deepseek-ai/dsh-bash':
-        specifier: workspace:^
-        version: link:../../bash/bash
-      '@deepseek-ai/dsh-commands':
-        specifier: workspace:^
-        version: link:../commands
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-sandbox':
-        specifier: workspace:^
-        version: link:../../sandbox/sandbox
-      '@deepseek-ai/dsh-sandbox-policy':
-        specifier: workspace:^
-        version: link:../../sandbox/sandbox-policy
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-projection':
-        specifier: workspace:^
-        version: link:../../session-projection/session-projection
-      '@deepseek-ai/dsh-settings':
-        specifier: workspace:^
-        version: link:../../settings/settings
-      '@deepseek-ai/dsh-user-approval':
-        specifier: workspace:^
-        version: link:../user-approval
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/tool-ask-user:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      '@deepseek-ai/dsh-user-interaction':
-        specifier: workspace:^
-        version: link:../user-interaction
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/user-approval:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/user-interaction:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/util/atomic-write:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -6749,7 +6749,7 @@ importers:
         version: link:../../core/system-prompt
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../timeout/timeout-policy
+        version: link:../../guard/timeout-policy
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -7049,7 +7049,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -7085,7 +7085,7 @@ importers:
         version: link:../../packages/examples/agent-spine-demo
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../packages/ui/app-boot
+        version: link:../../packages/boot/app-boot
       '@deepseek-ai/dsh-bash':
         specifier: workspace:^
         version: link:../../packages/bash/bash
@@ -7109,7 +7109,7 @@ importers:
         version: link:../../packages/goal/command-goal
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../packages/ui/commands
+        version: link:../../packages/interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../../packages/compact/compact
@@ -7154,7 +7154,7 @@ importers:
         version: link:../../packages/support/invariants
       '@deepseek-ai/dsh-jsonrpc':
         specifier: workspace:^
-        version: link:../../packages/ui/jsonrpc
+        version: link:../../packages/scaffold/server
       '@deepseek-ai/dsh-jsonrpc-demo':
         specifier: workspace:^
         version: link:../../packages/examples/jsonrpc-demo
@@ -7175,7 +7175,7 @@ importers:
         version: link:../../packages/util/paths
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../packages/ui/permission
+        version: link:../../packages/interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:^
         version: link:../../packages/plan/plan-mode
@@ -7205,25 +7205,25 @@ importers:
         version: link:../../packages/core/scope
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../packages/sdk/sdk-protocol
+        version: link:../../packages/scaffold/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../packages/core/session
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-checkpoint-policy
+        version: link:../../packages/session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-persistence
+        version: link:../../packages/session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-persistence-jsonl
+        version: link:../../packages/session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-persistence-sqlite
+        version: link:../../packages/session/session-persistence-sqlite
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../packages/session-projection/session-projection
+        version: link:../../packages/session/session-projection
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../packages/session-query/session-query
@@ -7235,7 +7235,7 @@ importers:
         version: link:../../packages/context/session-reference
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../packages/session-title/session-title
+        version: link:../../packages/session/session-title
       '@deepseek-ai/dsh-settings':
         specifier: workspace:^
         version: link:../../packages/settings/settings
@@ -7280,13 +7280,13 @@ importers:
         version: link:../../packages/util/timeout
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../packages/timeout/timeout-policy
+        version: link:../../packages/guard/timeout-policy
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../packages/llm/token-meter
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
-        version: link:../../packages/ui/tool-ask-user
+        version: link:../../packages/interaction/tool-ask-user
       '@deepseek-ai/dsh-tool-bash':
         specifier: workspace:^
         version: link:../../packages/bash/tool-bash
@@ -7295,7 +7295,7 @@ importers:
         version: link:../../packages/pty/tool-bash-persistent
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:^
-        version: link:../../packages/cordis/tool-cordis
+        version: link:../../packages/self-modification/tool-cordis
       '@deepseek-ai/dsh-tool-fs':
         specifier: workspace:^
         version: link:../../packages/fs/tool-fs
@@ -7334,10 +7334,10 @@ importers:
         version: link:../../packages/typert/type-meta
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../packages/ui/user-approval
+        version: link:../../packages/interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../packages/ui/user-interaction
+        version: link:../../packages/interaction/user-interaction
       '@deepseek-ai/dsh-web':
         specifier: workspace:^
         version: link:../../packages/web/web
@@ -14103,7 +14103,7 @@ snapshots:
 
   '@opentelemetry/api-logs@0.220.0':
     dependencies:
-      '@opentelemetry/api': 1.9.0
+      '@opentelemetry/api': 1.9.1
 
   '@opentelemetry/api@1.9.0': {}
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index ec8c282b80..40b3f620e3 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -8,11 +8,11 @@
       },
       {
         "role": "user",
-        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
+        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 903172e48f..9180a3bd9a 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -443,7 +443,7 @@
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionInspection",
-      "source": "packages/session-persistence/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/persistence.md",
diff --git a/scripts/verify-package-paths.ts b/scripts/verify-package-paths.ts
index f709354899..85c18e3cee 100644
--- a/scripts/verify-package-paths.ts
+++ b/scripts/verify-package-paths.ts
@@ -1,8 +1,8 @@
 /**
  * Find stale root-relative `packages/...` references in repo-authored prose and
- * TypeScript. A missing path is reported only when it names a real package leaf;
- * globs, placeholders, hypothetical packages, and unbuilt `lib/` output are
- * outside the check.
+ * TypeScript. A missing path is reported only when it names a real package leaf
+ * outside its own explaining group directory; globs, placeholders, hypothetical
+ * packages, and unbuilt `lib/` output are outside the check.
  */
 
 import { existsSync, globSync } from 'node:fs'
@@ -66,7 +66,15 @@ function isDriftedPackageReference(ref: string): boolean {
   const libAt = parts.indexOf('lib')
   if (libAt === 3 && existsSync(resolve(root, parts.slice(0, 3).join('/')))) return false
   // A missing reference is drift only when a path segment names a live package.
-  return ref.split('/').slice(1).some(segment => packageNames.has(segment))
+  // A leading segment that is itself an existing group directory is explained by
+  // the group, not by a relocated leaf sharing its name (`client` is both the
+  // client-modules group and the scaffold leaf), so only later segments count.
+  const segments = ref.split('/').slice(1)
+  const [group] = segments
+  const scanned = group !== undefined && segments.length > 1 && existsSync(resolve(root, 'packages', group))
+    ? segments.slice(1)
+    : segments
+  return scanned.some(segment => packageNames.has(segment))
 }
 
 /** Find missing package references whose path names a live package; bare paths, typos, and illustrative skeletons do not count. */

From ba3125234a4e968d19220eeac10642c41524fc19 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 18:06:07 +0800
Subject: [PATCH 154/262] docs: rename core-data-structures/ to subsystems/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The folder is becoming the home of one-doc-per-subsystem pages (intro +
data structures + cordis services/events), so the name must describe the
whole contract, not just the type-vocabulary third of it. Mechanical
rename rebuilt on current master: every inbound Markdown link, generator
constant, website route, type-equiv manifest path, and spec expectation
moves together; the zh sides of the notes whose prose names the folder
are aligned (子系统) in the same change; touched bilingual pairs
re-recorded; translation-prompt snapshot re-recorded (its example embeds
development.md). Historical Agent Note slugs keep their dated
filenames.
---
 ...eneric-long-running-tool-runtime.i18n.yaml |   4 +-
 ...06-20-generic-long-running-tool-runtime.md |   2 +-
 ...20-generic-long-running-tool-runtime.zh.md |   2 +-
 ...andatory-app-attribution-headers.i18n.yaml |   4 +-
 ...06-21-mandatory-app-attribution-headers.md |   2 +-
 ...21-mandatory-app-attribution-headers.zh.md |   2 +-
 ...stdin-env-trusted-plugin-surface.i18n.yaml |   4 +-
 ...0-bash-stdin-env-trusted-plugin-surface.md |   2 +-
 ...ash-stdin-env-trusted-plugin-surface.zh.md |   2 +-
 ...2026-07-15-agent-initiator-scope.i18n.yaml |   4 +-
 .../2026-07-15-agent-initiator-scope.md       |   2 +-
 .../2026-07-15-agent-initiator-scope.zh.md    |   2 +-
 .../2026-06-30-interception-seams.i18n.yaml   |   4 +-
 .../feature/2026-06-30-interception-seams.md  |   2 +-
 .../2026-06-30-interception-seams.zh.md       |   2 +-
 .../2026-07-05-dynamic-workflows.i18n.yaml    |   4 +-
 .../feature/2026-07-05-dynamic-workflows.md   |   2 +-
 .../2026-07-05-dynamic-workflows.zh.md        |   2 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |   4 +-
 .../feature/2026-07-05-skill-system.md        |   2 +-
 .../feature/2026-07-05-skill-system.zh.md     |   2 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |   4 +-
 .../implemented/feature/2026-07-06-sandbox.md |   2 +-
 .../feature/2026-07-06-sandbox.zh.md          |   2 +-
 ...-10-parallel-tool-call-execution.i18n.yaml |   4 +-
 ...2026-07-10-parallel-tool-call-execution.md |   2 +-
 ...6-07-10-parallel-tool-call-execution.zh.md |   2 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |   4 +-
 .../2026-07-31-code-mode-language-dispatch.md |   4 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |   4 +-
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   4 +-
 ...6-06-20-core-data-structures-catalog.zh.md |   2 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |   4 +-
 ...6-06-22-fork-child-replay-seed-boundary.md |   2 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |   2 +-
 .agents/skills/dsh-code-review/SKILL.md       |   2 +-
 docs/AGENTS.md                                |   4 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   8 +-
 docs/architecture.zh.md                       |   8 +-
 docs/config-catalog.md                        |  12 +-
 docs/cordis-catalog/events.md                 |  84 +--
 docs/cordis-catalog/services.md               |  78 +--
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   4 +-
 docs/development.zh.md                        |   4 +-
 docs/graph-atlas.md                           |   2 +-
 docs/i18n/style-samples.md                    |   4 +-
 docs/persistence-catalog.md                   |  26 +-
 ...ice-misclassified-child-failures.i18n.yaml |   4 +-
 ...ial-notice-misclassified-child-failures.md |   2 +-
 ...-notice-misclassified-child-failures.zh.md |   2 +-
 .../approval.i18n.yaml                        |   2 +-
 .../approval.md                               |   0
 .../approval.zh.md                            |   0
 .../bash.i18n.yaml                            |   0
 .../bash.md                                   |   0
 .../bash.zh.md                                |   0
 .../code-runtime.i18n.yaml                    |   0
 .../code-runtime.md                           |   0
 .../code-runtime.zh.md                        |   0
 .../commands.i18n.yaml                        |   2 +-
 .../commands.md                               |   0
 .../commands.zh.md                            |   0
 .../compaction.i18n.yaml                      |   2 +-
 .../compaction.md                             |   0
 .../compaction.zh.md                          |   0
 .../core.i18n.yaml                            |   2 +-
 .../core.md                                   |   0
 .../core.zh.md                                |   0
 .../credentials.i18n.yaml                     |   2 +-
 .../credentials.md                            |   0
 .../credentials.zh.md                         |   0
 .../filesystem.i18n.yaml                      |   0
 .../filesystem.md                             |   0
 .../filesystem.zh.md                          |   0
 .../goal.i18n.yaml                            |   0
 .../goal.md                                   |   0
 .../goal.zh.md                                |   0
 .../llm-streaming.i18n.yaml                   |   2 +-
 .../llm-streaming.md                          |   0
 .../llm-streaming.zh.md                       |   0
 .../lsp.i18n.yaml                             |   0
 .../lsp.md                                    |   0
 .../lsp.zh.md                                 |   0
 .../persistence.i18n.yaml                     |   2 +-
 .../persistence.md                            |   0
 .../persistence.zh.md                         |   0
 .../pty.i18n.yaml                             |   0
 .../pty.md                                    |   0
 .../pty.zh.md                                 |   0
 .../sandbox.i18n.yaml                         |   0
 .../sandbox.md                                |   0
 .../sandbox.zh.md                             |   0
 .../scope.i18n.yaml                           |   0
 .../scope.md                                  |   0
 .../scope.zh.md                               |   0
 .../session-query.i18n.yaml                   |   0
 .../session-query.md                          |   0
 .../session-query.zh.md                       |   0
 .../session-reference.i18n.yaml               |   2 +-
 .../session-reference.md                      |   0
 .../session-reference.zh.md                   |   0
 .../session-title.i18n.yaml                   |   2 +-
 .../session-title.md                          |   0
 .../session-title.zh.md                       |   0
 .../session.i18n.yaml                         |   2 +-
 .../session.md                                |   0
 .../session.zh.md                             |   0
 .../settings.i18n.yaml                        |   2 +-
 .../settings.md                               |   0
 .../settings.zh.md                            |   0
 .../skills.i18n.yaml                          |   2 +-
 .../skills.md                                 |   0
 .../skills.zh.md                              |   0
 .../spill.i18n.yaml                           |   0
 .../spill.md                                  |   0
 .../spill.zh.md                               |   0
 .../subagent.i18n.yaml                        |   0
 .../subagent.md                               |   0
 .../subagent.zh.md                            |   0
 .../subprocess.i18n.yaml                      |   0
 .../subprocess.md                             |   0
 .../subprocess.zh.md                          |   0
 .../system-prompt.i18n.yaml                   |   2 +-
 .../system-prompt.md                          |   0
 .../system-prompt.zh.md                       |   0
 .../tasks.i18n.yaml                           |   0
 .../tasks.md                                  |   0
 .../tasks.zh.md                               |   0
 .../token-meter.i18n.yaml                     |   0
 .../token-meter.md                            |   0
 .../token-meter.zh.md                         |   0
 .../tools.i18n.yaml                           |   2 +-
 .../tools.md                                  |   0
 .../tools.zh.md                               |   0
 .../typert.i18n.yaml                          |   0
 .../typert.md                                 |   0
 .../typert.zh.md                              |   0
 .../user-interaction.i18n.yaml                |   2 +-
 .../user-interaction.md                       |   0
 .../user-interaction.zh.md                    |   0
 .../web.i18n.yaml                             |   0
 .../web.md                                    |   0
 .../web.zh.md                                 |   0
 .../workflow.i18n.yaml                        |   0
 .../workflow.md                               |   0
 .../workflow.zh.md                            |   0
 docs/tool-catalog.md                          |   2 +-
 packages/bash/bash/README.i18n.yaml           |   4 +-
 packages/bash/bash/README.md                  |   2 +-
 packages/bash/bash/README.zh.md               |   2 +-
 packages/compact/compact/README.i18n.yaml     |   4 +-
 packages/compact/compact/README.md            |   2 +-
 packages/compact/compact/README.zh.md         |   2 +-
 packages/core/session/README.i18n.yaml        |   4 +-
 packages/core/session/README.md               |   2 +-
 packages/core/session/README.zh.md            |   2 +-
 packages/core/tools/src/index.ts              |   2 +-
 packages/goal/goal/README.i18n.yaml           |   4 +-
 packages/goal/goal/README.md                  |   2 +-
 packages/goal/goal/README.zh.md               |   2 +-
 packages/sandbox/sandbox/README.i18n.yaml     |   4 +-
 packages/sandbox/sandbox/README.md            |   2 +-
 packages/sandbox/sandbox/README.zh.md         |   2 +-
 .../session/session-title/README.i18n.yaml    |   6 +-
 packages/session/session-title/README.md      |   2 +-
 packages/session/session-title/README.zh.md   |   2 +-
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   2 +-
 packages/subprocess/subprocess/README.zh.md   |   2 +-
 packages/tasks/tasks/README.i18n.yaml         |   4 +-
 packages/tasks/tasks/README.md                |   2 +-
 packages/tasks/tasks/README.zh.md             |   2 +-
 .../typert/generator/src/cordis-catalog.ts    |   6 +-
 .../tests/cordis-catalog-contract.spec.ts     |   2 +-
 scripts/gen-config-catalog.ts                 |   6 +-
 scripts/gen-cordis-catalog.ts                 |   2 +-
 scripts/gen-doc-graphs.ts                     |   2 +-
 scripts/gen-persistence-catalog.ts            |   8 +-
 scripts/gen-tool-catalog.ts                   |   2 +-
 scripts/project-doc-site.spec.ts              |   8 +-
 .../request-response.expected.json            |   4 +-
 scripts/type-equiv.manifest.json              | 624 +++++++++---------
 website/docs.ts                               |  10 +-
 186 files changed, 564 insertions(+), 564 deletions(-)
 rename docs/{core-data-structures => subsystems}/approval.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/approval.md (100%)
 rename docs/{core-data-structures => subsystems}/approval.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/bash.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/bash.md (100%)
 rename docs/{core-data-structures => subsystems}/bash.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/code-runtime.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/code-runtime.md (100%)
 rename docs/{core-data-structures => subsystems}/code-runtime.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/commands.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/commands.md (100%)
 rename docs/{core-data-structures => subsystems}/commands.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/compaction.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/compaction.md (100%)
 rename docs/{core-data-structures => subsystems}/compaction.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/core.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/core.md (100%)
 rename docs/{core-data-structures => subsystems}/core.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/credentials.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/credentials.md (100%)
 rename docs/{core-data-structures => subsystems}/credentials.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/filesystem.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/filesystem.md (100%)
 rename docs/{core-data-structures => subsystems}/filesystem.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/goal.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/goal.md (100%)
 rename docs/{core-data-structures => subsystems}/goal.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/llm-streaming.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/llm-streaming.md (100%)
 rename docs/{core-data-structures => subsystems}/llm-streaming.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/lsp.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/lsp.md (100%)
 rename docs/{core-data-structures => subsystems}/lsp.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/persistence.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/persistence.md (100%)
 rename docs/{core-data-structures => subsystems}/persistence.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/pty.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/pty.md (100%)
 rename docs/{core-data-structures => subsystems}/pty.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/sandbox.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/sandbox.md (100%)
 rename docs/{core-data-structures => subsystems}/sandbox.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/scope.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/scope.md (100%)
 rename docs/{core-data-structures => subsystems}/scope.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session-query.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/session-query.md (100%)
 rename docs/{core-data-structures => subsystems}/session-query.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session-reference.i18n.yaml (79%)
 rename docs/{core-data-structures => subsystems}/session-reference.md (100%)
 rename docs/{core-data-structures => subsystems}/session-reference.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session-title.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/session-title.md (100%)
 rename docs/{core-data-structures => subsystems}/session-title.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/session.md (100%)
 rename docs/{core-data-structures => subsystems}/session.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/settings.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/settings.md (100%)
 rename docs/{core-data-structures => subsystems}/settings.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/skills.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/skills.md (100%)
 rename docs/{core-data-structures => subsystems}/skills.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/spill.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/spill.md (100%)
 rename docs/{core-data-structures => subsystems}/spill.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/subagent.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/subagent.md (100%)
 rename docs/{core-data-structures => subsystems}/subagent.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/subprocess.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/subprocess.md (100%)
 rename docs/{core-data-structures => subsystems}/subprocess.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/system-prompt.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/system-prompt.md (100%)
 rename docs/{core-data-structures => subsystems}/system-prompt.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/tasks.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/tasks.md (100%)
 rename docs/{core-data-structures => subsystems}/tasks.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/token-meter.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/token-meter.md (100%)
 rename docs/{core-data-structures => subsystems}/token-meter.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/tools.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/tools.md (100%)
 rename docs/{core-data-structures => subsystems}/tools.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/typert.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/typert.md (100%)
 rename docs/{core-data-structures => subsystems}/typert.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/user-interaction.i18n.yaml (79%)
 rename docs/{core-data-structures => subsystems}/user-interaction.md (100%)
 rename docs/{core-data-structures => subsystems}/user-interaction.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/web.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/web.md (100%)
 rename docs/{core-data-structures => subsystems}/web.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/workflow.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/workflow.md (100%)
 rename docs/{core-data-structures => subsystems}/workflow.zh.md (100%)

diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index e1171d5877..cb9ed4275a 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: cb9d9487cd274696ae20dddab8c6888b4cf4b833
-2026-06-20-generic-long-running-tool-runtime.zh.md: fe5ca223975445991e7fe96376cbfccf432ad241
+2026-06-20-generic-long-running-tool-runtime.md: 90100ea8f146e505c4fbb95760781839bd4bd34a
+2026-06-20-generic-long-running-tool-runtime.zh.md: bdcd8e8fe2a50033177354ce5ce043c4b5264621
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index cb9d9487cd..90100ea8f1 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -23,7 +23,7 @@ Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into in
 
 ## Runtime contract
 
-The literal types live in the [task data-structure catalog](../../../../docs/core-data-structures/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
+The literal types live in the [task data-structure catalog](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
 `outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control surfaces apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing surface behavior, so the runtime does not impose a hidden default on unrelated producer families.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index fe5ca22397..bdcd8e8fe2 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 运行时契约
 
-字面类型见[任务数据结构目录](../../../../docs/core-data-structures/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
+字面类型见[任务数据结构目录](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
 `outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index b6788a47ef..3db3ea7fa4 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: ad9d65805c8f0c96bd811b5036310d019760627e
-2026-06-21-mandatory-app-attribution-headers.zh.md: 3021c7fcca00f2e929d997625c303f9a27dbf673
+2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
+2026-06-21-mandatory-app-attribution-headers.zh.md: cdada9cb235d57ad5cac98ebe0572013cac728ef
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index ad9d65805c..de9125bc89 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -51,7 +51,7 @@ Endpoint detection is not part of this Agent Note because no endpoint-specific m
 
 The landed contract:
 
-- `dsh-llm` documents the mandatory `User-Agent` attribution contract for `LlmAdapter` authors (`LlmAdapter` JSDoc, package README, and the adapter-contract section of `docs/core-data-structures/llm-streaming.md`).
+- `dsh-llm` documents the mandatory `User-Agent` attribution contract for `LlmAdapter` authors (`LlmAdapter` JSDoc, package README, and the adapter-contract section of `docs/subsystems/llm-streaming.md`).
 - A shared helper (`attributionHeaders` / `userAgent`) constructs the app identity and the standard `User-Agent` value from package metadata, so adapters do not hand-copy version constants.
 - `dsh-llm-deepseek` sends the shared `User-Agent` on every request and its mock-server suite asserts the exact value.
 - `dsh-llm-pi-ai` sends the same `User-Agent` through pi-ai's `StreamOptions.headers` hook and its mock-server suite asserts the exact value.
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 3021c7fcca..cdada9cb23 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 已落地的契约：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/core-data-structures/llm-streaming.md` 的适配器契约（adapter contract）章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器契约（adapter contract）章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
index 5dbfcf94ef..459ffa188c 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 556d5dd86dfcc92c4628e68c19390f0033560d25
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 325e3d303bdb6836c8928fdae00de59fb954ff37
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: aa0c785be84bcb8a49f8a2670afa0f6bed6277db
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 48108fdd5b8217263590fba336480f1b487e882f
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
index 556d5dd86d..aa0c785be8 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
@@ -30,4 +30,4 @@ Three deliberate choices:
 
 ## Consequences
 
-Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/core-data-structures/bash.md).
+Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/bash.md).
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
index 325e3d303b..48108fdd5b 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/core-data-structures/bash.md)。
+钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/subsystems/bash.md)。
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
index 233164d4e4..c85bb100aa 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.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 .agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
-2026-07-15-agent-initiator-scope.md: 69648100e76cfc212469854188d664357fec22f1
-2026-07-15-agent-initiator-scope.zh.md: 505d198ccd2a54af1a15fc1ad6c03b27d217eca0
+2026-07-15-agent-initiator-scope.md: 2f388ae1de3dd6583686e129a03f0cd76701e18d
+2026-07-15-agent-initiator-scope.zh.md: 64f70a4d1c3368d5621edb7251d0b567505affc0
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
index 69648100e7..2f388ae1de 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
@@ -12,7 +12,7 @@ Deep process-local infrastructure sometimes needs a trusted initiating Agent bel
 
 ## Decision
 
-The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../../docs/core-data-structures/core.md#initiating-agent) identifies the carried type.
+The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../../docs/subsystems/core.md#initiating-agent) identifies the carried type.
 
 `currentInitiator()` reads optionally, `requireInitiator()` throws `no initiating agent is active`, and `withInitiator(agent, operation)` preserves the operation's exact synchronous value or Promise. `withoutInitiator(operation)` establishes a clearing boundary for work that must not inherit an Agent. Session remains derived as `agent.session`; turn, step, tool call, `signal`, model, `cwd`, sandbox, and authorization stay with their existing owners.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
index 505d198ccd..64f70a4d1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
@@ -12,7 +12,7 @@ harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负
 
 ## 决策
 
-必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../../docs/core-data-structures/core.md#initiating-agent)标明了所携带的类型。
+必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../../docs/subsystems/core.md#initiating-agent)标明了所携带的类型。
 
 `currentInitiator()` 用于可选读取，`requireInitiator()` 抛出 `no initiating agent is active`，`withInitiator(agent, operation)` 保留操作返回的同步值或 Promise 本身。`withoutInitiator(operation)` 会建立清空边界，供不得继承 Agent 的工作使用。会话仍通过 `agent.session` 推导；轮次、步骤、工具调用、`signal`、模型、`cwd`、沙箱和授权继续由现有归属方管理。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
index 3be447fe2f..8481cc20d5 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.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 .agents/notes/implemented/feature/2026-06-30-interception-seams.md
-2026-06-30-interception-seams.md: c318e41cfb1d64230b6151f1febad85d75b1451d
-2026-06-30-interception-seams.zh.md: 1b274fae4bc7fde326dbb0eeec54d57f73987803
+2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
+2026-06-30-interception-seams.zh.md: 4e7b6a5ac9ca88919246508cf86c486b06888417
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
index c318e41cfb..3b2c62cd44 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
@@ -56,4 +56,4 @@ The seam package does **not** declare `hook/*` session events (the durable hook-
 
 ## Consequences
 
-The canonical interception surface is uniformly typed without giving every extension the same power: hooks return decisions, execution wrappers wrap, terminal guards only deny, and final observers only observe. The loop owns session-start, pre-step claim settlement, post-tool context buffering, and stopping; `dsh-tools` owns identity sealing and the five-phase execution pipeline. Their contracts are documented in [architecture.md](../../../../docs/architecture.md), package READMEs, [core interception decisions](../../../../docs/core-data-structures/core.md#interception-decisions), and [tool structures](../../../../docs/core-data-structures/tools.md). The ACP bridge settles an initial pre-step rejection from its blocked no-step turn as `end_turn`, while hook-driven snapshots verify the observable bridge behavior end to end.
+The canonical interception surface is uniformly typed without giving every extension the same power: hooks return decisions, execution wrappers wrap, terminal guards only deny, and final observers only observe. The loop owns session-start, pre-step claim settlement, post-tool context buffering, and stopping; `dsh-tools` owns identity sealing and the five-phase execution pipeline. Their contracts are documented in [architecture.md](../../../../docs/architecture.md), package READMEs, [core interception decisions](../../../../docs/subsystems/core.md#interception-decisions), and [tool structures](../../../../docs/subsystems/tools.md). The ACP bridge settles an initial pre-step rejection from its blocked no-step turn as `end_turn`, while hook-driven snapshots verify the observable bridge behavior end to end.
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
index 1b274fae4b..4e7b6a5ac9 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -56,4 +56,4 @@ seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；
 
 ## 后果
 
-规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/core-data-structures/core.md#interception-decisions) 与[工具结构](../../../../docs/core-data-structures/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 15054d6ba1..394af669cd 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: bba62098c66477a3f1929f9029e81c645bfc4d41
-2026-07-05-dynamic-workflows.zh.md: 2005ca14883ae137148541273900c7f3e65769a5
+2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3
+2026-07-05-dynamic-workflows.zh.md: 246727649be8acc17dac1335d353e9b1591e3890
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index bba62098c6..b0fb2349e6 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -20,7 +20,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre
 
 ### The seam (dsh-workflow)
 
-`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [core-data-structures/workflow.md](../../../../docs/core-data-structures/workflow.md).
+`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [subsystems/workflow.md](../../../../docs/subsystems/workflow.md).
 
 ### The engine (dsh-workflow-workerthread): one worker thread per run
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index 2005ca1488..246727649b 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -20,7 +20,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 ### seam（dsh-workflow）
 
-`ctx.workflows` 是 bash 形态的抽象 `WorkflowService`——每个上下文一个引擎，无命名提供方注册表（引擎是部署级替换，不是共存者）。`start(request)` 对无法启动的脚本同步抛出；返回的 `WorkflowRun` 的 `result` 永不 reject（失败时结算为 `stopReason: 'error' | 'cancelled'`）。`workflow/*` 事件是仅观察的 emit，携带数据快照（id + meta；`workflow/end` 省略 result 值），按监听器隔离，与 `subagent/start`/`subagent/end` 对称——控制权留在 run 的持有者手中。词汇详情见 [core-data-structures/workflow.md](../../../../docs/core-data-structures/workflow.md)。
+`ctx.workflows` 是 bash 形态的抽象 `WorkflowService`——每个上下文一个引擎，无命名提供方注册表（引擎是部署级替换，不是共存者）。`start(request)` 对无法启动的脚本同步抛出；返回的 `WorkflowRun` 的 `result` 永不 reject（失败时结算为 `stopReason: 'error' | 'cancelled'`）。`workflow/*` 事件是仅观察的 emit，携带数据快照（id + meta；`workflow/end` 省略 result 值），按监听器隔离，与 `subagent/start`/`subagent/end` 对称——控制权留在 run 的持有者手中。词汇详情见 [subsystems/workflow.md](../../../../docs/subsystems/workflow.md)。
 
 ### 引擎（dsh-workflow-workerthread）：每次运行一个 worker 线程
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index a98beff699..6fff14bc85 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: a998d70ec934aed4bf7ce32aa711abd47b508a1d
-2026-07-05-skill-system.zh.md: 4fa7c4fd657c2f41f16b30679ec95e61a75f8a0c
+2026-07-05-skill-system.md: bb7c03a64a3d0d0f700e21bc96633f1c3ea181b9
+2026-07-05-skill-system.zh.md: 8e26e52d3366505a958dd4b19461edf8bf740b00
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index a998d70ec9..bb7c03a64a 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -28,7 +28,7 @@ Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is lo
 
 The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path.
 
-The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/core-data-structures/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md).
+The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 4fa7c4fd65..8e26e52d33 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -28,7 +28,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/core-data-structures/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
+数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 7294f47357..00f475040c 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 583b388815cd9b2b9cf94ce393839169ce3ffac3
-2026-07-06-sandbox.zh.md: e435b671a42ca5c3ea4f6800bf91d6e006da35d3
+2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
+2026-07-06-sandbox.zh.md: 8f575e3cd14973aaaaf9254337b985110bc99d6b
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 583b388815..06c5590454 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -200,7 +200,7 @@ Costs and accepted limits:
 In-repo precedents this design copies or contrasts with:
 
 - [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
-- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/core-data-structures/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention.
+- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/subsystems/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention.
 - [The approval seam Agent Note](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there.
 - [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [standalone log-only events](../simplification/2026-07-28-remove-synthetic-log-only-turns.md) — the log-as-store foundation the per-session modes fold over, and the explicit durability boundary the anchoring design obeys.
 - [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index e435b671a4..8f575e3cd1 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -200,7 +200,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 本设计复制或对比的仓库内先例：
 
 - [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
-- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/core-data-structures/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
+- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/subsystems/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
 - [批准 seam Agent Note](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。
 - [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[独立纯日志事件](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)——按会话模式 fold 所依赖的日志即存储基础，以及锚定设计遵守的显式持久性边界。
 - [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 3119d28d71..6462a2c873 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.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 .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
-2026-07-10-parallel-tool-call-execution.md: 19f5dc189821433052edfa72613980a2e94e2cae
-2026-07-10-parallel-tool-call-execution.zh.md: 69bff90c11fa132ded325ef610dabf5c609f21af
+2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45
+2026-07-10-parallel-tool-call-execution.zh.md: 985557974c79d4080c4e35ccbb9740439988261a
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
index 19f5dc1898..7fd540539f 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
@@ -14,7 +14,7 @@ The session log remains authoritative: every started call has an audit event, or
 
 ## Decision
 
-Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../../docs/core-data-structures/tools.md).
+Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../../docs/subsystems/tools.md).
 
 The classifier is deliberately unary. Returning `true` is the tool's promise that this call may overlap with any sibling call that also returns `true`; the scheduler does not compare calls or prove that their resource accesses are compatible.
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 69bff90c11..985557974c 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/core-data-structures/tools.md)。
+每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/subsystems/tools.md)。
 
 分类器有意设计为一元函数。返回 `true` 表示工具承诺：此调用可以与任何同样返回 `true` 的并列调用重叠执行。调度器不会比较调用，也不会证明它们的资源访问相容。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index 66ac99d37c..e6ca4048fd 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
-2026-07-31-code-mode-language-dispatch.md: 96001252d6494d058a8df9974fb5a0d59e7d7112
-2026-07-31-code-mode-language-dispatch.zh.md: aa7eb2a6b4b9117f1d707b37afcdbe12b814bad2
+2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
+2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
index 96001252d6..71e4fd5a30 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
@@ -17,7 +17,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at
 - `SDK_RENDERERS` (index.ts) maps a language to its `tools:sdk` renderer — `typescript → renderToolsSdk`, `python → renderToolsSdkPy`. The `tools:sdk` section reads the loaded runtime's language and picks the renderer; `requireCodeRuntime` rejects a `mode: code`/`both` runtime whose language is absent from the table, naming the known languages.
 - `RUN_CODE_FLAVORS` (code-mode.ts) maps a language to its two model-facing `run_code` strings (tool `description` and the `code` parameter description), so a language's SDK section and its transport schema always agree.
 
-Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/core-data-structures/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
+Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
 
 `code-mode.ts` depends only on the runtime seam (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the seam's `language` field, which is already on master.
 
@@ -37,7 +37,7 @@ The standard that cap serves is grammatical validity, and the boundary is delibe
 
 ## Consequences
 
-Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/core-data-structures/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
+Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
 
 The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index aa7eb2a6b4..1dbb3d889d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -17,7 +17,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 - `SDK_RENDERERS`（index.ts）把语言映射到它的 `tools:sdk` 渲染器——`typescript → renderToolsSdk`、`python → renderToolsSdkPy`。`tools:sdk` 段读取所加载运行时的语言并选出渲染器；`requireCodeRuntime` 拒绝其语言不在表中的 `mode: code`/`both` 运行时，并列出已知语言。
 - `RUN_CODE_FLAVORS`（code-mode.ts）把语言映射到它那两条面向模型的 `run_code` 字符串（工具 `description` 与 `code` 参数描述），使一种语言的 SDK 段与它的传输 schema 始终一致。
 
-两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/core-data-structures/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
+两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
 
 `code-mode.ts` 只依赖运行时 seam（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要 seam 的 `language` 字段，而该字段已在 master 上。
 
@@ -37,7 +37,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ## Consequences
 
-新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/core-data-structures/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
+新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
 
 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 4acabc8700..13c54fa458 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 7ee1e0ac3df7cb37fc9797702d44f409da820a94
-2026-06-20-core-data-structures-catalog.zh.md: 7cb0ae216f5c5f429c18d097862350997a8335d3
+2026-06-20-core-data-structures-catalog.md: 57433fdcb3c77976c4ba0cfe7d157f94dff331dd
+2026-06-20-core-data-structures-catalog.zh.md: 3956839c8211e294280805d9b6993e5607bfe04f
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 7ee1e0ac3d..57433fdcb3 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -1,4 +1,4 @@
-# Agent Note: Core-data-structures catalog and the `ts type-equiv` drift gate
+# Agent Note: Subsystems catalog and the `ts type-equiv` drift gate
 
 Status: implemented
 
@@ -12,7 +12,7 @@ So the work had two intertwined questions: **what belongs in such a catalog** (t
 
 ## Decision
 
-A new `docs/core-data-structures/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
+A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
 
 ### What counts as "core" — the spine-vs-seam line
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 7cb0ae216f..3956839c82 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-新增的 `docs/core-data-structures/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
+新增的 `docs/subsystems/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
 
 ### 何为「核心」——主干与 seam 的分界线
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 70d56bbca5..5ef82c77de 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.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 .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
-2026-06-22-fork-child-replay-seed-boundary.md: ed3ec095bc14128f5ebc0a9188bc022ef97b1c8b
-2026-06-22-fork-child-replay-seed-boundary.zh.md: 1d938cbf6c9c32a144d58fed48e552d85aa9c625
+2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d
+2026-06-22-fork-child-replay-seed-boundary.zh.md: f64fc55fc63e2caa4b50112407b645e6e7f12b0f
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
index ed3ec095bc..27db3b768f 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
@@ -44,6 +44,6 @@ This closes the routing correctness gap, and two recorded fork scenarios exercis
 
 ## Consequences
 
-- A new persisted header field across core + both backends; the core-data-structures catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks).
+- A new persisted header field across core + both backends; the subsystems catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks).
 - Existing SQLite databases at schema v2 are rejected on open (no user data pre-release).
 - Spawn replay is unchanged (`seedLength` 0). Fork replay now routes a child to its own script; covered by a regression in `llm-replay`'s tests (a child fixture whose seeded prefix carries a parent chunk — the derived child script must exclude it, proven red without the slice) and a persistence round-trip test (both backends, via the shared coordinator contract).
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index 1d938cbf6c..f64fc55fc6 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -44,6 +44,6 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla
 
 ## 后果
 
-- core 与两个后端新增一个持久化 header 字段；核心数据结构目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
+- core 与两个后端新增一个持久化 header 字段；子系统目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
 - 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。
 - spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。
diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index f933beb86b..81f63fac2f 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -21,7 +21,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
 1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
 2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
-3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
+3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
 4. **Registrations clean up.** Verify each new registry contribution satisfies the disposal-test contract in [packages/AGENTS.md](../../../packages/AGENTS.md).
 5. **Invariant companions are semantic.** For every touched `./invariant`, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness ([repository rule](../../../AGENTS.md#conventions); [package contract](../../../packages/AGENTS.md)).
 6. **Required evidence exists.** Verify the author ran the [relevant local checks](../../../AGENTS.md#run-relevant-checks-locally) for the diff and that CI covers the exhaustive matrix; review the semantic gaps neither can detect.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index cd4e8aaaa5..3bbd4f330d 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -21,7 +21,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
 | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [core-data-structures/](core-data-structures/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
+| [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
@@ -37,7 +37,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The [core-data-structures catalog](core-data-structures/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](core-data-structures/core.md#what-counts-as-core)).
+- **The [core-data-structures catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 76491a37fe..15a6ba3fb5 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: cee159452fc536c98a006cfa3ea92e9d21a1e77b
-architecture.zh.md: cf10e60a5d5e4fe3f39d72bef3d48fe7c2f3c105
+architecture.md: 7baf550128fe83528ce12bf2f9b40cfc8f78e322
+architecture.zh.md: 076edd0549fb7f648a7a1b06d7027a1e6eca735f
diff --git a/docs/architecture.md b/docs/architecture.md
index cee159452f..7baf550128 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -123,7 +123,7 @@ Adapter selection, dispatch, and iteration failures become terminal error or abo
 
 Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Waking input that lands after the abort fires but before convergence runs at the driver's convergence boundary, while a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
 
-Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
+Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap).
 
 ### Agent Handles
 
@@ -147,9 +147,9 @@ Between turns, owners append log-only events through `Session`, flushing only fo
 
 ### Model Content
 
-Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](core-data-structures/token-meter.md).
+Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](subsystems/token-meter.md).
 
-Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](core-data-structures/llm-streaming.md)).
+Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)).
 
 ## Extension And Composition
 
@@ -157,7 +157,7 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md).
 
-Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](core-data-structures/subagent.md)).
+Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)).
 
 `dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths.
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index cf10e60a5d..076edd0549 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -123,7 +123,7 @@ idle inject:
 
 其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
-轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。
+轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap)。
 
 ### Agent 句柄
 
@@ -147,9 +147,9 @@ idle inject:
 
 ### 模型内容
 
-消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](core-data-structures/token-meter.md)。
+消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](core-data-structures/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
@@ -157,7 +157,7 @@ idle inject:
 
 能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。
 
-例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](core-data-structures/subagent.md)）。
+例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
 
 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 254d85ccd1..850f4731e2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -3,7 +3,7 @@
 
 # Plugin Config Catalog
 
-Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md) documents the types these declarations reference.
+Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
 
 This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.
 
@@ -106,7 +106,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md)
+Depends on: [`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:236`](../packages/core/agent-loop/src/index.ts)
 
@@ -1044,7 +1044,7 @@ export interface PresetSpec {
 }
 ```
 
-Depends on: [`ApprovalPolicy`](core-data-structures/approval.md) · [`SandboxMode`](core-data-structures/sandbox.md)
+Depends on: [`ApprovalPolicy`](subsystems/approval.md) · [`SandboxMode`](subsystems/sandbox.md)
 
 Source: [`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts)
 
@@ -1234,7 +1234,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`SandboxMode`](core-data-structures/sandbox.md)
+Depends on: [`SandboxMode`](subsystems/sandbox.md)
 
 Source: [`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts)
 
@@ -2193,7 +2193,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`AgentOptions`](core-data-structures/core.md)
+Depends on: [`AgentOptions`](subsystems/core.md)
 
 Source: [`packages/subagent/tool-subagent/src/index.ts:25`](../packages/subagent/tool-subagent/src/index.ts)
 
@@ -2212,7 +2212,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`SubagentReportDelivery`](core-data-structures/subagent.md)
+Depends on: [`SubagentReportDelivery`](subsystems/subagent.md)
 
 Source: [`packages/subagent/tool-subagent-report/src/index.ts:22`](../packages/subagent/tool-subagent-report/src/index.ts)
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 2c99c451d2..dd9cf5bfa5 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -3,7 +3,7 @@
 
 # Cordis Events Catalog
 
-Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.
+Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.
 
 This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
 
@@ -31,7 +31,7 @@ A fully configured agent and live session were published. Setup is composition-o
 'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
 
@@ -51,7 +51,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
 
@@ -73,7 +73,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
@@ -95,7 +95,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
@@ -114,7 +114,7 @@ One message was discarded from the live inbox.
 'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
@@ -133,7 +133,7 @@ One message entered the live inbox.
 'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
@@ -156,7 +156,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [PreStepDecision](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
 
@@ -180,7 +180,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [LlmCallConfig](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
@@ -207,7 +207,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [LlmFailure](../subsystems/llm-streaming.md) · [RequestErrorAction](../subsystems/core.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
 
@@ -229,7 +229,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [SessionStartSource](../subsystems/core.md)
 
 Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
 
@@ -250,7 +250,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [AgentStatus](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
 
@@ -279,7 +279,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
 
@@ -302,7 +302,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
 ```
 
-Types: [SessionId](../core-data-structures/core.md)
+Types: [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
 
@@ -323,7 +323,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
 ```
 
-Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md)
+Types: [ApprovalOutcome](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [ApprovalService](../subsystems/approval.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
 
@@ -367,7 +367,7 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
 'credentials/updated'(ref: CredentialRef): void
 ```
 
-Types: [CredentialRef](../core-data-structures/credentials.md)
+Types: [CredentialRef](../subsystems/credentials.md)
 
 Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
 
@@ -408,7 +408,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
-Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
+Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
 
@@ -428,7 +428,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
 ```
 
-Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
+Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
 
@@ -448,7 +448,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
-Types: [FsTarget](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md)
+Types: [FsTarget](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
 
@@ -470,7 +470,7 @@ Goal mutation accepted by one live agent. The matching `goal/change` session eve
 'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [GoalChanged](../core-data-structures/goal.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [GoalChanged](../subsystems/goal.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
 
@@ -515,7 +515,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [GenerateOptions](../subsystems/core.md) · [LlmService](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
 
 Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 
@@ -540,7 +540,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
 
@@ -561,7 +561,7 @@ Emitted once when an announced session leaves the store, including publication r
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
 
@@ -584,7 +584,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
@@ -604,7 +604,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
 
@@ -629,7 +629,7 @@ One registered namespace's RAW user section changed, whether or not the resolved
 'settings/document-updated'(ns: SettingsNamespace, revision: number): void
 ```
 
-Types: [SettingsNamespace](../core-data-structures/settings.md)
+Types: [SettingsNamespace](../subsystems/settings.md)
 
 Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
 
@@ -656,7 +656,7 @@ Committed change to one registered namespace's resolved value. Emitted after the
 'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
 ```
 
-Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md)
+Types: [SettingsNamespace](../subsystems/settings.md) · [SettingsUpdateSource](../subsystems/settings.md)
 
 Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
 
@@ -697,7 +697,7 @@ A published child settled. Scope-filtered dispatch uses the same delegating pare
 'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
+Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
 
@@ -714,7 +714,7 @@ A provider became resolvable in the registry.
 'subagent/provider-added'(provider: SubagentProvider): void
 ```
 
-Types: [SubagentProvider](../core-data-structures/subagent.md)
+Types: [SubagentProvider](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
 
@@ -751,7 +751,7 @@ A provider established a published child. For in-process providers, `ctx.agents.
 'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
+Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
 
@@ -775,7 +775,7 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc
 'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
 ```
 
-Types: [AssembleContext](../core-data-structures/system-prompt.md) · [Scoped](../core-data-structures/scope.md) · [SystemPrompt](../core-data-structures/system-prompt.md)
+Types: [AssembleContext](../subsystems/system-prompt.md) · [Scoped](../subsystems/scope.md) · [SystemPrompt](../subsystems/system-prompt.md)
 
 Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
 
@@ -865,7 +865,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
 ```
 
-Types: [CodeDispatchLog](../core-data-structures/tools.md) · [ContentBlock](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [CodeDispatchLog](../subsystems/tools.md) · [ContentBlock](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
 
@@ -887,7 +887,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [ToolDispatchExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [Scoped](../subsystems/scope.md) · [ToolDispatchExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
 
@@ -910,7 +910,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
 ```
 
-Types: [PostToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [PostToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
 
@@ -931,7 +931,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
 ```
 
-Types: [PreToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [PreToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
 
@@ -950,7 +950,7 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
 
@@ -974,7 +974,7 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P
 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
 
@@ -995,7 +995,7 @@ One `agent()` call established a published child run. Paired with Events['workfl
 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1016,7 +1016,7 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves
 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1034,7 +1034,7 @@ The script emitted a narration line (a `log(message)` call).
 'workflow/log'(info: WorkflowRunInfo, message: string): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1053,7 +1053,7 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs
 'workflow/phase'(info: WorkflowRunInfo, title: string): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1071,7 +1071,7 @@ A workflow run started — the script's meta block validated, the body about to
 'workflow/start'(info: WorkflowRunInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 56a0d0d2e6..dbab056105 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -3,7 +3,7 @@
 
 # Cordis Services Catalog
 
-Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
+Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
 
 This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
 
@@ -42,7 +42,7 @@ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<Agent
 async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [AgentOptions](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md) · [AgentOptions](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
 
@@ -214,7 +214,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
@@ -260,7 +260,7 @@ async request(req: ApprovalRequest): Promise<ApprovalOutcome>
 overrideOf(session: Session): ApprovalPolicy | undefined
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalPolicy](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [Session](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [ApprovalOutcome](../subsystems/approval.md) · [ApprovalPolicy](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
 
@@ -300,7 +300,7 @@ abstract run(spec: BashExecSpec): Promise<BashRunResult>
 abstract start(spec: BashExecSpec): BashProcess
 ```
 
-Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashProcess](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
+Types: [BashExecRequest](../subsystems/bash.md) · [BashExecSpec](../subsystems/bash.md) · [BashProcess](../subsystems/bash.md) · [BashRunResult](../subsystems/bash.md)
 
 Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
 
@@ -331,7 +331,7 @@ collect(execution: ToolExecution): DshEnvironment
 list(): BashEnvVariableInfo[]
 ```
 
-Types: [DshEnvironment](../core-data-structures/subprocess.md) · [ToolExecution](../core-data-structures/tools.md)
+Types: [DshEnvironment](../subsystems/subprocess.md) · [ToolExecution](../subsystems/tools.md)
 
 Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
 
@@ -396,7 +396,7 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
-Types: [CodeRunRequest](../core-data-structures/code-runtime.md) · [CodeRunResult](../core-data-structures/code-runtime.md)
+Types: [CodeRunRequest](../subsystems/code-runtime.md) · [CodeRunResult](../subsystems/code-runtime.md)
 
 Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
 
@@ -449,7 +449,7 @@ find(agent: Agent, name: string): CommandDefinition | undefined
 async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md)
+Types: [Agent](../subsystems/core.md) · [CommandDefinition](../subsystems/commands.md) · [CommandDescriptor](../subsystems/commands.md)
 
 Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
 
@@ -514,7 +514,7 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Types: [CompactionResult](../core-data-structures/compaction.md) · [CompactionTrigger](../core-data-structures/compaction.md)
+Types: [CompactionResult](../subsystems/compaction.md) · [CompactionTrigger](../subsystems/compaction.md)
 
 Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
 
@@ -560,7 +560,7 @@ abstract set(ref: CredentialRef, value: string): Promise<void>
 abstract unset(ref: CredentialRef): Promise<void>
 ```
 
-Types: [CredentialInfo](../core-data-structures/credentials.md) · [CredentialRef](../core-data-structures/credentials.md) · [ResolvedCredential](../core-data-structures/credentials.md)
+Types: [CredentialInfo](../subsystems/credentials.md) · [CredentialRef](../subsystems/credentials.md) · [ResolvedCredential](../subsystems/credentials.md)
 
 Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
 
@@ -719,7 +719,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent,
 abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
 ```
 
-Types: [FsDirEntry](../core-data-structures/filesystem.md) · [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsPathInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md) · [SandboxExecutionPolicy](../core-data-structures/sandbox.md)
+Types: [FsDirEntry](../subsystems/filesystem.md) · [FsEditOutcome](../subsystems/filesystem.md) · [FsEditRequest](../subsystems/filesystem.md) · [FsInfo](../subsystems/filesystem.md) · [FsPathInfo](../subsystems/filesystem.md) · [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md) · [FsWriteOutcome](../subsystems/filesystem.md) · [SandboxExecutionPolicy](../subsystems/sandbox.md)
 
 Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
 
@@ -814,7 +814,7 @@ block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
 @Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-data-structures/goal.md) · [CreateGoalResult](../core-data-structures/goal.md) · [EditGoalRequest](../core-data-structures/goal.md) · [GoalBlockReason](../core-data-structures/goal.md) · [GoalRef](../core-data-structures/goal.md) · [GoalView](../core-data-structures/goal.md)
+Types: [Agent](../subsystems/core.md) · [CreateGoalRequest](../subsystems/goal.md) · [CreateGoalResult](../subsystems/goal.md) · [EditGoalRequest](../subsystems/goal.md) · [GoalBlockReason](../subsystems/goal.md) · [GoalRef](../subsystems/goal.md) · [GoalView](../subsystems/goal.md)
 
 Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
 
@@ -1008,7 +1008,7 @@ async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<Prepared
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [DirectoryRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmDiscoveredModel](../core-data-structures/core.md) · [LlmModelDiscoveryRequest](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [AdapterRegistrationHandle](../subsystems/core.md) · [DirectoryRegistrationHandle](../subsystems/core.md) · [GenerateOptions](../subsystems/core.md) · [LlmAdapter](../subsystems/llm-streaming.md) · [LlmCallConfig](../subsystems/core.md) · [LlmConfigurableProvider](../subsystems/core.md) · [LlmDiscoveredModel](../subsystems/core.md) · [LlmModelDiscoveryRequest](../subsystems/core.md) · [LlmModelInfo](../subsystems/core.md) · [LlmProviderInfo](../subsystems/core.md) · [LlmResolvedModelInfo](../subsystems/core.md) · [PreparedLlmCall](../subsystems/llm-streaming.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
 
 Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
@@ -1060,7 +1060,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
+Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 
@@ -1096,7 +1096,7 @@ get(agent: Agent): { active: boolean; pending?: boolean }
 set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md)
 
 Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
 
@@ -1178,7 +1178,7 @@ async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Pr
 list(owner: Agent): PtySessionSnapshot[]
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md)
+Types: [Agent](../subsystems/core.md) · [PtyBackend](../subsystems/pty.md) · [PtyReadRequest](../subsystems/pty.md) · [PtyReadResult](../subsystems/pty.md) · [PtySendOperation](../subsystems/pty.md) · [PtySendRequest](../subsystems/pty.md) · [PtySessionId](../subsystems/pty.md) · [PtySessionSnapshot](../subsystems/pty.md) · [PtySignal](../subsystems/pty.md) · [PtySignalResult](../subsystems/pty.md) · [PtySpawnRequest](../subsystems/pty.md) · [PtySpawnResult](../subsystems/pty.md)
 
 Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
 
@@ -1201,7 +1201,7 @@ Abstract process-sandbox service. confine must return enforcing argv or fail clo
 abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
 ```
 
-Types: [ConfinedArgv](../core-data-structures/sandbox.md) · [SandboxPolicy](../core-data-structures/sandbox.md)
+Types: [ConfinedArgv](../subsystems/sandbox.md) · [SandboxPolicy](../subsystems/sandbox.md)
 
 Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
 
@@ -1229,7 +1229,7 @@ resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
 overrideOf(session: Session): SandboxMode | undefined
 ```
 
-Types: [SandboxExecutionPolicy](../core-data-structures/sandbox.md) · [SandboxMode](../core-data-structures/sandbox.md) · [SandboxPolicyRequest](../core-data-structures/sandbox.md) · [Session](../core-data-structures/session.md)
+Types: [SandboxExecutionPolicy](../subsystems/sandbox.md) · [SandboxMode](../subsystems/sandbox.md) · [SandboxPolicyRequest](../subsystems/sandbox.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
 
@@ -1350,7 +1350,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionInspection](../core-data-structures/persistence.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md) · [SessionPreparation](../core-data-structures/persistence.md)
+Types: [SessionEvent](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) · [SessionInspection](../subsystems/persistence.md) · [SessionLocation](../subsystems/persistence.md) · [SessionPersistenceSnapshot](../subsystems/persistence.md) · [SessionPreparation](../subsystems/persistence.md)
 
 Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 
@@ -1398,7 +1398,7 @@ async write(session: Session): Promise<void>
 async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
+Types: [Session](../subsystems/session.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
 
@@ -1506,7 +1506,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
 restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
+Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 
@@ -1633,7 +1633,7 @@ async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promi
 async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
 ```
 
-Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventResultFilter](../core-data-structures/session-query.md) · [SessionEventSearchDocument](../core-data-structures/session-query.md) · [SessionEventSearchPage](../core-data-structures/session-query.md) · [SessionEventSearchRequest](../core-data-structures/session-query.md) · [SessionEventTraceObservation](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionLogSnapshot](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionResultFilter](../core-data-structures/session-query.md) · [SessionSearchExecContext](../core-data-structures/session-query.md) · [SessionSearchHit](../core-data-structures/session-query.md) · [SessionSearchPage](../core-data-structures/session-query.md) · [SessionSearchRequest](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleObservation](../core-data-structures/session-query.md) · [SessionTitleObservationResult](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+Types: [SessionEventReadRequest](../subsystems/session-query.md) · [SessionEventRecord](../subsystems/session-query.md) · [SessionEventResultFilter](../subsystems/session-query.md) · [SessionEventSearchDocument](../subsystems/session-query.md) · [SessionEventSearchPage](../subsystems/session-query.md) · [SessionEventSearchRequest](../subsystems/session-query.md) · [SessionEventTraceObservation](../subsystems/session-query.md) · [SessionEventTraceRequest](../subsystems/session-query.md) · [SessionEventWindow](../subsystems/session-query.md) · [SessionId](../subsystems/core.md) · [SessionLineageTrace](../subsystems/session-query.md) · [SessionLogSnapshot](../subsystems/session-query.md) · [SessionRecord](../subsystems/session-query.md) · [SessionResultFilter](../subsystems/session-query.md) · [SessionSearchExecContext](../subsystems/session-query.md) · [SessionSearchHit](../subsystems/session-query.md) · [SessionSearchPage](../subsystems/session-query.md) · [SessionSearchRequest](../subsystems/session-query.md) · [SessionSurfaceSnapshot](../subsystems/session-query.md) · [SessionTitleObservation](../subsystems/session-query.md) · [SessionTitleObservationResult](../subsystems/session-query.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
 
 Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
 
@@ -1663,7 +1663,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con
 async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [PreparedReferencedMessage](../core-data-structures/session-reference.md) · [SessionReferenceCandidate](../core-data-structures/session-reference.md) · [SessionReferenceInput](../core-data-structures/session-reference.md)
+Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [PreparedReferencedMessage](../subsystems/session-reference.md) · [SessionReferenceCandidate](../subsystems/session-reference.md) · [SessionReferenceInput](../subsystems/session-reference.md)
 
 Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
 
@@ -1797,7 +1797,7 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [PrepareSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
+Types: [CreateSessionOptions](../subsystems/persistence.md) · [PrepareSessionOptions](../subsystems/persistence.md) · [Session](../subsystems/session.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
 
@@ -1844,7 +1844,7 @@ async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnaps
 register(provider: SessionTitleProvider): () => Promise<void>
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+Types: [Session](../subsystems/session.md) · [SessionTitleProvider](../subsystems/session-title.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
 
 Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
 
@@ -1929,7 +1929,7 @@ async replace(ns: SettingsNamespace, section: object, expectedRevision?: number)
 async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
 ```
 
-Types: [SettingsDescribeOptions](../core-data-structures/settings.md) · [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsPathOp](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md)
+Types: [SettingsDescribeOptions](../subsystems/settings.md) · [SettingsDescriptor](../subsystems/settings.md) · [SettingsNamespace](../subsystems/settings.md) · [SettingsPathOp](../subsystems/settings.md) · [SettingsRegisterOptions](../subsystems/settings.md) · [SettingsScope](../subsystems/settings.md)
 
 Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
 
@@ -1987,7 +1987,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
-Types: [SkillCatalogSnapshot](../core-data-structures/skills.md) · [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillProviderControl](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md)
+Types: [SkillCatalogSnapshot](../subsystems/skills.md) · [SkillDefinition](../subsystems/skills.md) · [SkillLookupOptions](../subsystems/skills.md) · [SkillProvider](../subsystems/skills.md) · [SkillProviderControl](../subsystems/skills.md) · [SkillRegistration](../subsystems/skills.md) · [SkillSummary](../subsystems/skills.md)
 
 Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
 
@@ -2010,7 +2010,7 @@ Semantics every implementation must honor:
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
 ```
 
-Types: [SaveTextSpill](../core-data-structures/spill.md) · [SpillRef](../core-data-structures/spill.md)
+Types: [SaveTextSpill](../subsystems/spill.md) · [SpillRef](../subsystems/spill.md)
 
 Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
 
@@ -2248,7 +2248,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentDescendantListEntry](../core-data-structures/subagent.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [ContinuableSetupContribution](../subsystems/subagent.md) · [ContinuableStart](../subsystems/subagent.md) · [ContinuableStartSpec](../subsystems/subagent.md) · [MessageId](../subsystems/core.md) · [SessionId](../subsystems/core.md) · [SubagentDescendantListEntry](../subsystems/subagent.md) · [SubagentFollowupOptions](../subsystems/subagent.md) · [SubagentInterruptAuthority](../subsystems/subagent.md) · [SubagentListEntry](../subsystems/subagent.md) · [SubagentProvider](../subsystems/subagent.md) · [SubagentReportOptions](../subsystems/subagent.md) · [SubagentRun](../subsystems/subagent.md) · [SubagentStartRequest](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
@@ -2297,7 +2297,7 @@ abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
 abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
 ```
 
-Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md) · [SubprocessTerminalHandle](../core-data-structures/subprocess.md) · [SubprocessTerminalSpawnSpec](../core-data-structures/subprocess.md)
+Types: [SubprocessHandle](../subsystems/subprocess.md) · [SubprocessSpawnSpec](../subsystems/subprocess.md) · [SubprocessTerminalHandle](../subsystems/subprocess.md) · [SubprocessTerminalSpawnSpec](../subsystems/subprocess.md)
 
 Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
 
@@ -2353,7 +2353,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
-Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptContext](../core-data-structures/system-prompt.md) · [PromptSection](../core-data-structures/system-prompt.md) · [ToolProviderResult](../core-data-structures/system-prompt.md)
+Types: [AssembleContext](../subsystems/system-prompt.md) · [PromptContext](../subsystems/system-prompt.md) · [PromptSection](../subsystems/system-prompt.md) · [ToolProviderResult](../subsystems/system-prompt.md)
 
 Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
 
@@ -2448,7 +2448,7 @@ abstract onTaskDone(listener: TaskDoneListener): () => void
 abstract attachSurface(name: string): () => void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [TaskDoneListener](../core-data-structures/tasks.md) · [TaskId](../core-data-structures/tasks.md) · [TaskRead](../core-data-structures/tasks.md) · [TaskSnapshot](../core-data-structures/tasks.md) · [TaskStart](../core-data-structures/tasks.md)
+Types: [Agent](../subsystems/core.md) · [TaskDoneListener](../subsystems/tasks.md) · [TaskId](../subsystems/tasks.md) · [TaskRead](../subsystems/tasks.md) · [TaskSnapshot](../subsystems/tasks.md) · [TaskStart](../subsystems/tasks.md)
 
 Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
 
@@ -2507,7 +2507,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md)
+Types: [EpochHeader](../subsystems/session.md) · [Message](../subsystems/core.md) · [Session](../subsystems/session.md) · [TokenMeasurement](../subsystems/token-meter.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 
@@ -2547,7 +2547,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 pruneSession(session: Session): PruneResult
 ```
 
-Types: [ContentBlock](../core-data-structures/core.md) · [PruneResult](../core-data-structures/compaction.md) · [Session](../core-data-structures/session.md)
+Types: [ContentBlock](../subsystems/core.md) · [PruneResult](../subsystems/compaction.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 
@@ -2630,7 +2630,7 @@ executionMode(exec: ToolExecutionInput): ToolExecutionMode
 async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 ```
 
-Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md)
+Types: [ScopeKey](../subsystems/scope.md) · [ToolDefinition](../subsystems/tools.md) · [ToolExecutionInput](../subsystems/tools.md) · [ToolExecutionMode](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolGuard](../subsystems/tools.md) · [ToolRestriction](../subsystems/tools.md) · [ToolSchema](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
 
@@ -2743,7 +2743,7 @@ registerProvider(provider: UserInteractionProvider): () => void
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
 
-Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md)
+Types: [AskUserQuestionAnswer](../subsystems/user-interaction.md) · [AskUserQuestionRequest](../subsystems/user-interaction.md) · [UserInteractionProvider](../subsystems/user-interaction.md)
 
 Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
 
@@ -2801,7 +2801,7 @@ async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearch
 async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
 ```
 
-Types: [WebFetchProvider](../core-data-structures/web.md) · [WebFetchRequest](../core-data-structures/web.md) · [WebFetchResult](../core-data-structures/web.md) · [WebSearchProvider](../core-data-structures/web.md) · [WebSearchRequest](../core-data-structures/web.md) · [WebSearchResult](../core-data-structures/web.md)
+Types: [WebFetchProvider](../subsystems/web.md) · [WebFetchRequest](../subsystems/web.md) · [WebFetchResult](../subsystems/web.md) · [WebSearchProvider](../subsystems/web.md) · [WebSearchRequest](../subsystems/web.md) · [WebSearchResult](../subsystems/web.md)
 
 Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
 
@@ -2819,7 +2819,7 @@ Workflow execution seam. Invalid requests throw before publication; a live run i
 abstract start(request: WorkflowStartRequest): WorkflowRun
 ```
 
-Types: [WorkflowRun](../core-data-structures/workflow.md) · [WorkflowStartRequest](../core-data-structures/workflow.md)
+Types: [WorkflowRun](../subsystems/workflow.md) · [WorkflowStartRequest](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
 
@@ -2885,7 +2885,7 @@ archiveSession(sessionId: SessionId): Promise<void>
 async resolveByPath(path: string): Promise<Workspace | undefined>
 ```
 
-Types: [SessionId](../core-data-structures/core.md)
+Types: [SessionId](../subsystems/core.md)
 
 Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 43f985604b..13c766cc80 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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 docs/development.md
-development.md: 0032000e298ef49516d618e932258e79cf90e802
-development.zh.md: d681306e31991794519b62c3edbb6ca35ebc228b
+development.md: 134109fd2a09dfa36aaf2ccdba14daccf896da60
+development.zh.md: 741a860770ee3b20fe94cb0b4993bb281b605b26
diff --git a/docs/development.md b/docs/development.md
index 0032000e29..134109fd2a 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -156,10 +156,10 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel
 
 ### Documenting types verbatim (`ts type-equiv`)
 
-The [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
+The [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
 
 ```json
-{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
+{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
 `pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `"projection": "public-api"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.
diff --git a/docs/development.zh.md b/docs/development.zh.md
index d681306e31..741a860770 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -156,10 +156,10 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
-{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
+{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
 `pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index e783d5fddf..0c955c9480 100644
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -3,7 +3,7 @@
 
 # Documentation Graph Index
 
-These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).
+These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).
 
 The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).
 
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 87ef939730..b9a330f21d 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -14,9 +14,9 @@
 
 依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-spine-demo`，它的职责是组装整套实体主干。
 
-> This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
+> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index b238e56399..04f992e536 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -3,11 +3,11 @@
 
 # Session Persistence Event Catalog
 
-Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
-The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
+The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
 
 ## Event envelope
 
@@ -123,7 +123,7 @@ Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/type
 }
 ```
 
-Types: [CallId](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md)
 
 Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
 
@@ -172,7 +172,7 @@ Source: [`packages/interaction/user-approval/src/index.ts:67`](../packages/inter
 'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
 ```
 
-Types: [StreamChunk](core-data-structures/llm-streaming.md)
+Types: [StreamChunk](subsystems/llm-streaming.md)
 
 Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts)
 
@@ -188,7 +188,7 @@ Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/
 'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage }
 ```
 
-Types: [TokenUsage](core-data-structures/llm-streaming.md)
+Types: [TokenUsage](subsystems/llm-streaming.md)
 
 Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts)
 
@@ -328,7 +328,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 )
 ```
 
-Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
+Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
 Source: [`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
 
@@ -555,7 +555,7 @@ Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/
 'session/title': SessionTitleEventData
 ```
 
-Types: [SessionTitleEventData](core-data-structures/session-title.md)
+Types: [SessionTitleEventData](subsystems/session-title.md)
 
 Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
 
@@ -566,7 +566,7 @@ Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/
 'session/title-llm-request': SessionTitleLlmRequestEventData
 ```
 
-Types: [SessionTitleLlmRequestEventData](core-data-structures/session-title.md)
+Types: [SessionTitleLlmRequestEventData](subsystems/session-title.md)
 
 Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
 
@@ -616,7 +616,7 @@ Source: [`packages/subagent/subagent/src/descriptor.ts:37`](../packages/subagent
 'todo/write': { todos: TodoItem[] }
 ```
 
-Types: [TodoItem](core-data-structures/session.md)
+Types: [TodoItem](subsystems/session.md)
 
 Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts)
 
@@ -633,7 +633,7 @@ Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/
 'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
 ```
 
-Types: [CallId](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md)
 
 Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts)
 
@@ -658,7 +658,7 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
 'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
 ```
 
-Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
 
 Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
 
@@ -681,7 +681,7 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c
 'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
 ```
 
-Types: [CallId](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md)
 
 Source: [`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
 
@@ -726,7 +726,7 @@ Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/
 'turn/end': { turn: number; reason: TurnEndReason }
 ```
 
-Types: [TurnEndReason](core-data-structures/session.md)
+Types: [TurnEndReason](subsystems/session.md)
 
 Source: [`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts)
 
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
index 47a2e3fdd7..b54453f3c4 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.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 docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
-0004-landlock-partial-notice-misclassified-child-failures.md: db810fdc896f9734d1b581617838d72166f4efc9
-0004-landlock-partial-notice-misclassified-child-failures.zh.md: 4a31fb038c44b036e6a183040947295a47221967
+0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198
+0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
index db810fdc89..ed59fa9d2b 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
@@ -40,7 +40,7 @@ Stderr remains an in-band attribution channel. A confined child can deliberately
 
 ## Guardrails added
 
-- [`RunnerFailureRule`](../core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) carries optional allowed exit codes, case-insensitive per-line fatal signatures, and case-insensitive exact informational-line exclusions.
+- [`RunnerFailureRule`](../subsystems/sandbox.md#wrapped-argv-and-classification-dialects) carries optional allowed exit codes, case-insensitive per-line fatal signatures, and case-insensitive exact informational-line exclusions.
 - [`dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) maps Landlock to exit 125 plus a non-notice `landlock-run:` line while bwrap, Seatbelt, and custom runners remain signature-only.
 - [`dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) directly spawns the provider argv, so a pre-start rejection uses the spawn-error channel instead of localized shell diagnostics. Settled foreground and background execution share one evidence-returning classifier; fatal evidence outranks denial, and foreground errors report the matched fatal line without changing captured stderr.
 - [`dsh-tool-fs-search`](../../packages/fs/tool-fs-search/) uses packaged ripgrep through `ctx.subprocess` and remains outside the sandboxed bash seam.
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
index 4a31fb038c..5cf3e4422a 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
@@ -40,7 +40,7 @@ stderr 仍是带内归因通道。受限子进程可以故意复现 runner 的
 
 ## 已添加的防护措施
 
-- [`RunnerFailureRule`](../core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) 携带可选的允许退出码、不区分大小写的逐行致命签名，以及按不区分大小写的整行精确匹配排除的信息性行。
+- [`RunnerFailureRule`](../subsystems/sandbox.md#wrapped-argv-and-classification-dialects) 携带可选的允许退出码、不区分大小写的逐行致命签名，以及按不区分大小写的整行精确匹配排除的信息性行。
 - [`dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) 把 Landlock 映射为退出码 125 加一行非通知的 `landlock-run:` 诊断，而 bwrap、Seatbelt 和自定义 runner 仍仅依据签名。
 - [`dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) 直接 spawn 提供方 argv，因此启动前遭拒时使用 spawn 错误通道，而非本地化的 shell 诊断。已结算的前台与后台执行共用一个返回证据的分类器；致命证据优先于拒绝，前台错误会报告匹配到的致命行，同时保持捕获的 stderr 不变。
 - [`dsh-tool-fs-search`](../../packages/fs/tool-fs-search/) 通过 `ctx.subprocess` 运行打包的 ripgrep，并继续位于沙箱化 bash seam 之外。
diff --git a/docs/core-data-structures/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/approval.i18n.yaml
rename to docs/subsystems/approval.i18n.yaml
index 975f631805..a3447601a4 100644
--- a/docs/core-data-structures/approval.i18n.yaml
+++ b/docs/subsystems/approval.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/approval.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/approval.md
 approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069
 approval.zh.md: c19285572b667512427b71d4af214acbc2baf334
diff --git a/docs/core-data-structures/approval.md b/docs/subsystems/approval.md
similarity index 100%
rename from docs/core-data-structures/approval.md
rename to docs/subsystems/approval.md
diff --git a/docs/core-data-structures/approval.zh.md b/docs/subsystems/approval.zh.md
similarity index 100%
rename from docs/core-data-structures/approval.zh.md
rename to docs/subsystems/approval.zh.md
diff --git a/docs/core-data-structures/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/bash.i18n.yaml
rename to docs/subsystems/bash.i18n.yaml
diff --git a/docs/core-data-structures/bash.md b/docs/subsystems/bash.md
similarity index 100%
rename from docs/core-data-structures/bash.md
rename to docs/subsystems/bash.md
diff --git a/docs/core-data-structures/bash.zh.md b/docs/subsystems/bash.zh.md
similarity index 100%
rename from docs/core-data-structures/bash.zh.md
rename to docs/subsystems/bash.zh.md
diff --git a/docs/core-data-structures/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/code-runtime.i18n.yaml
rename to docs/subsystems/code-runtime.i18n.yaml
diff --git a/docs/core-data-structures/code-runtime.md b/docs/subsystems/code-runtime.md
similarity index 100%
rename from docs/core-data-structures/code-runtime.md
rename to docs/subsystems/code-runtime.md
diff --git a/docs/core-data-structures/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
similarity index 100%
rename from docs/core-data-structures/code-runtime.zh.md
rename to docs/subsystems/code-runtime.zh.md
diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/commands.i18n.yaml
rename to docs/subsystems/commands.i18n.yaml
index 18df873acc..a741971a9a 100644
--- a/docs/core-data-structures/commands.i18n.yaml
+++ b/docs/subsystems/commands.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/commands.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/commands.md
 commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c
 commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb
diff --git a/docs/core-data-structures/commands.md b/docs/subsystems/commands.md
similarity index 100%
rename from docs/core-data-structures/commands.md
rename to docs/subsystems/commands.md
diff --git a/docs/core-data-structures/commands.zh.md b/docs/subsystems/commands.zh.md
similarity index 100%
rename from docs/core-data-structures/commands.zh.md
rename to docs/subsystems/commands.zh.md
diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/compaction.i18n.yaml
rename to docs/subsystems/compaction.i18n.yaml
index 2ad9ea8e8a..7dc00cebfc 100644
--- a/docs/core-data-structures/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/compaction.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/compaction.md
 compaction.md: f1df5b83bd43136af60988dabd9dc68fe32467a2
 compaction.zh.md: 52540250d466f81f51cf7c681bb6f1436e29a12d
diff --git a/docs/core-data-structures/compaction.md b/docs/subsystems/compaction.md
similarity index 100%
rename from docs/core-data-structures/compaction.md
rename to docs/subsystems/compaction.md
diff --git a/docs/core-data-structures/compaction.zh.md b/docs/subsystems/compaction.zh.md
similarity index 100%
rename from docs/core-data-structures/compaction.zh.md
rename to docs/subsystems/compaction.zh.md
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/core.i18n.yaml
rename to docs/subsystems/core.i18n.yaml
index ee870f9334..3057ee36ee 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/core.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: 8f413a7a064ad6f63e0caec31354869e51139020
 core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5
diff --git a/docs/core-data-structures/core.md b/docs/subsystems/core.md
similarity index 100%
rename from docs/core-data-structures/core.md
rename to docs/subsystems/core.md
diff --git a/docs/core-data-structures/core.zh.md b/docs/subsystems/core.zh.md
similarity index 100%
rename from docs/core-data-structures/core.zh.md
rename to docs/subsystems/core.zh.md
diff --git a/docs/core-data-structures/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/credentials.i18n.yaml
rename to docs/subsystems/credentials.i18n.yaml
index d44275d97e..f7899eaf6e 100644
--- a/docs/core-data-structures/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/credentials.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
 credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e
 credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8
diff --git a/docs/core-data-structures/credentials.md b/docs/subsystems/credentials.md
similarity index 100%
rename from docs/core-data-structures/credentials.md
rename to docs/subsystems/credentials.md
diff --git a/docs/core-data-structures/credentials.zh.md b/docs/subsystems/credentials.zh.md
similarity index 100%
rename from docs/core-data-structures/credentials.zh.md
rename to docs/subsystems/credentials.zh.md
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/filesystem.i18n.yaml
rename to docs/subsystems/filesystem.i18n.yaml
diff --git a/docs/core-data-structures/filesystem.md b/docs/subsystems/filesystem.md
similarity index 100%
rename from docs/core-data-structures/filesystem.md
rename to docs/subsystems/filesystem.md
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
similarity index 100%
rename from docs/core-data-structures/filesystem.zh.md
rename to docs/subsystems/filesystem.zh.md
diff --git a/docs/core-data-structures/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/goal.i18n.yaml
rename to docs/subsystems/goal.i18n.yaml
diff --git a/docs/core-data-structures/goal.md b/docs/subsystems/goal.md
similarity index 100%
rename from docs/core-data-structures/goal.md
rename to docs/subsystems/goal.md
diff --git a/docs/core-data-structures/goal.zh.md b/docs/subsystems/goal.zh.md
similarity index 100%
rename from docs/core-data-structures/goal.zh.md
rename to docs/subsystems/goal.zh.md
diff --git a/docs/core-data-structures/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/llm-streaming.i18n.yaml
rename to docs/subsystems/llm-streaming.i18n.yaml
index 7168f9bd85..1ff1a1d42b 100644
--- a/docs/core-data-structures/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/llm-streaming.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: 5c90b3ce4ac65a99997f6ba7ad5deac494b7f772
 llm-streaming.zh.md: 7fd0043234cb40d6b21cec6ff101993164785a6e
diff --git a/docs/core-data-structures/llm-streaming.md b/docs/subsystems/llm-streaming.md
similarity index 100%
rename from docs/core-data-structures/llm-streaming.md
rename to docs/subsystems/llm-streaming.md
diff --git a/docs/core-data-structures/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
similarity index 100%
rename from docs/core-data-structures/llm-streaming.zh.md
rename to docs/subsystems/llm-streaming.zh.md
diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/lsp.i18n.yaml
rename to docs/subsystems/lsp.i18n.yaml
diff --git a/docs/core-data-structures/lsp.md b/docs/subsystems/lsp.md
similarity index 100%
rename from docs/core-data-structures/lsp.md
rename to docs/subsystems/lsp.md
diff --git a/docs/core-data-structures/lsp.zh.md b/docs/subsystems/lsp.zh.md
similarity index 100%
rename from docs/core-data-structures/lsp.zh.md
rename to docs/subsystems/lsp.zh.md
diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/persistence.i18n.yaml
rename to docs/subsystems/persistence.i18n.yaml
index eccd3f146e..697094b490 100644
--- a/docs/core-data-structures/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/persistence.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
 persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6
 persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad
diff --git a/docs/core-data-structures/persistence.md b/docs/subsystems/persistence.md
similarity index 100%
rename from docs/core-data-structures/persistence.md
rename to docs/subsystems/persistence.md
diff --git a/docs/core-data-structures/persistence.zh.md b/docs/subsystems/persistence.zh.md
similarity index 100%
rename from docs/core-data-structures/persistence.zh.md
rename to docs/subsystems/persistence.zh.md
diff --git a/docs/core-data-structures/pty.i18n.yaml b/docs/subsystems/pty.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/pty.i18n.yaml
rename to docs/subsystems/pty.i18n.yaml
diff --git a/docs/core-data-structures/pty.md b/docs/subsystems/pty.md
similarity index 100%
rename from docs/core-data-structures/pty.md
rename to docs/subsystems/pty.md
diff --git a/docs/core-data-structures/pty.zh.md b/docs/subsystems/pty.zh.md
similarity index 100%
rename from docs/core-data-structures/pty.zh.md
rename to docs/subsystems/pty.zh.md
diff --git a/docs/core-data-structures/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/sandbox.i18n.yaml
rename to docs/subsystems/sandbox.i18n.yaml
diff --git a/docs/core-data-structures/sandbox.md b/docs/subsystems/sandbox.md
similarity index 100%
rename from docs/core-data-structures/sandbox.md
rename to docs/subsystems/sandbox.md
diff --git a/docs/core-data-structures/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
similarity index 100%
rename from docs/core-data-structures/sandbox.zh.md
rename to docs/subsystems/sandbox.zh.md
diff --git a/docs/core-data-structures/scope.i18n.yaml b/docs/subsystems/scope.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/scope.i18n.yaml
rename to docs/subsystems/scope.i18n.yaml
diff --git a/docs/core-data-structures/scope.md b/docs/subsystems/scope.md
similarity index 100%
rename from docs/core-data-structures/scope.md
rename to docs/subsystems/scope.md
diff --git a/docs/core-data-structures/scope.zh.md b/docs/subsystems/scope.zh.md
similarity index 100%
rename from docs/core-data-structures/scope.zh.md
rename to docs/subsystems/scope.zh.md
diff --git a/docs/core-data-structures/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/session-query.i18n.yaml
rename to docs/subsystems/session-query.i18n.yaml
diff --git a/docs/core-data-structures/session-query.md b/docs/subsystems/session-query.md
similarity index 100%
rename from docs/core-data-structures/session-query.md
rename to docs/subsystems/session-query.md
diff --git a/docs/core-data-structures/session-query.zh.md b/docs/subsystems/session-query.zh.md
similarity index 100%
rename from docs/core-data-structures/session-query.zh.md
rename to docs/subsystems/session-query.zh.md
diff --git a/docs/core-data-structures/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
similarity index 79%
rename from docs/core-data-structures/session-reference.i18n.yaml
rename to docs/subsystems/session-reference.i18n.yaml
index 85bbcf8877..f119c67913 100644
--- a/docs/core-data-structures/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/session-reference.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-reference.md
 session-reference.md: 5375677f6a1748909743ca76d5191cb9e736a40a
 session-reference.zh.md: 3ff4a1719926bda0a9111482a7778a8c94553370
diff --git a/docs/core-data-structures/session-reference.md b/docs/subsystems/session-reference.md
similarity index 100%
rename from docs/core-data-structures/session-reference.md
rename to docs/subsystems/session-reference.md
diff --git a/docs/core-data-structures/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
similarity index 100%
rename from docs/core-data-structures/session-reference.zh.md
rename to docs/subsystems/session-reference.zh.md
diff --git a/docs/core-data-structures/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/session-title.i18n.yaml
rename to docs/subsystems/session-title.i18n.yaml
index ed9955472c..c85d4dfac1 100644
--- a/docs/core-data-structures/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/session-title.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-title.md
 session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e
 session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e
diff --git a/docs/core-data-structures/session-title.md b/docs/subsystems/session-title.md
similarity index 100%
rename from docs/core-data-structures/session-title.md
rename to docs/subsystems/session-title.md
diff --git a/docs/core-data-structures/session-title.zh.md b/docs/subsystems/session-title.zh.md
similarity index 100%
rename from docs/core-data-structures/session-title.zh.md
rename to docs/subsystems/session-title.zh.md
diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/session.i18n.yaml
rename to docs/subsystems/session.i18n.yaml
index 16e969bd94..dd7135e8d3 100644
--- a/docs/core-data-structures/session.i18n.yaml
+++ b/docs/subsystems/session.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/session.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/session.md
 session.md: 5d54b03df8ec3345e8bf04702f242e3aacf8ec39
 session.zh.md: 5a867cfe302bf02994bfe5a5a704bed55222e8ea
diff --git a/docs/core-data-structures/session.md b/docs/subsystems/session.md
similarity index 100%
rename from docs/core-data-structures/session.md
rename to docs/subsystems/session.md
diff --git a/docs/core-data-structures/session.zh.md b/docs/subsystems/session.zh.md
similarity index 100%
rename from docs/core-data-structures/session.zh.md
rename to docs/subsystems/session.zh.md
diff --git a/docs/core-data-structures/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/settings.i18n.yaml
rename to docs/subsystems/settings.i18n.yaml
index cf262dc1e9..f4518f4414 100644
--- a/docs/core-data-structures/settings.i18n.yaml
+++ b/docs/subsystems/settings.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/settings.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/settings.md
 settings.md: bd01c1d28407af9cab26f624a054a010e25a3ddd
 settings.zh.md: 1cb7f8b507f29f2b6876fd48b4c37284df235e53
diff --git a/docs/core-data-structures/settings.md b/docs/subsystems/settings.md
similarity index 100%
rename from docs/core-data-structures/settings.md
rename to docs/subsystems/settings.md
diff --git a/docs/core-data-structures/settings.zh.md b/docs/subsystems/settings.zh.md
similarity index 100%
rename from docs/core-data-structures/settings.zh.md
rename to docs/subsystems/settings.zh.md
diff --git a/docs/core-data-structures/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/skills.i18n.yaml
rename to docs/subsystems/skills.i18n.yaml
index d0ce7b7574..6ab9693cca 100644
--- a/docs/core-data-structures/skills.i18n.yaml
+++ b/docs/subsystems/skills.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/skills.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/skills.md
 skills.md: d862cbc07135680c2377b4c8c82c80d055344221
 skills.zh.md: 3f8c034ec2aa24b4acdbbc1e2ac27717c21649d5
diff --git a/docs/core-data-structures/skills.md b/docs/subsystems/skills.md
similarity index 100%
rename from docs/core-data-structures/skills.md
rename to docs/subsystems/skills.md
diff --git a/docs/core-data-structures/skills.zh.md b/docs/subsystems/skills.zh.md
similarity index 100%
rename from docs/core-data-structures/skills.zh.md
rename to docs/subsystems/skills.zh.md
diff --git a/docs/core-data-structures/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/spill.i18n.yaml
rename to docs/subsystems/spill.i18n.yaml
diff --git a/docs/core-data-structures/spill.md b/docs/subsystems/spill.md
similarity index 100%
rename from docs/core-data-structures/spill.md
rename to docs/subsystems/spill.md
diff --git a/docs/core-data-structures/spill.zh.md b/docs/subsystems/spill.zh.md
similarity index 100%
rename from docs/core-data-structures/spill.zh.md
rename to docs/subsystems/spill.zh.md
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/subagent.i18n.yaml
rename to docs/subsystems/subagent.i18n.yaml
diff --git a/docs/core-data-structures/subagent.md b/docs/subsystems/subagent.md
similarity index 100%
rename from docs/core-data-structures/subagent.md
rename to docs/subsystems/subagent.md
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/subsystems/subagent.zh.md
similarity index 100%
rename from docs/core-data-structures/subagent.zh.md
rename to docs/subsystems/subagent.zh.md
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/subprocess.i18n.yaml
rename to docs/subsystems/subprocess.i18n.yaml
diff --git a/docs/core-data-structures/subprocess.md b/docs/subsystems/subprocess.md
similarity index 100%
rename from docs/core-data-structures/subprocess.md
rename to docs/subsystems/subprocess.md
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
similarity index 100%
rename from docs/core-data-structures/subprocess.zh.md
rename to docs/subsystems/subprocess.zh.md
diff --git a/docs/core-data-structures/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/system-prompt.i18n.yaml
rename to docs/subsystems/system-prompt.i18n.yaml
index 8d9cd0897f..5c39e3cbcb 100644
--- a/docs/core-data-structures/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/system-prompt.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
 system-prompt.md: 59193c1881abcadbc8a1778cde92f5a6572eee24
 system-prompt.zh.md: 41e45417817895ccf6def70e510eca7422a65e41
diff --git a/docs/core-data-structures/system-prompt.md b/docs/subsystems/system-prompt.md
similarity index 100%
rename from docs/core-data-structures/system-prompt.md
rename to docs/subsystems/system-prompt.md
diff --git a/docs/core-data-structures/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
similarity index 100%
rename from docs/core-data-structures/system-prompt.zh.md
rename to docs/subsystems/system-prompt.zh.md
diff --git a/docs/core-data-structures/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/tasks.i18n.yaml
rename to docs/subsystems/tasks.i18n.yaml
diff --git a/docs/core-data-structures/tasks.md b/docs/subsystems/tasks.md
similarity index 100%
rename from docs/core-data-structures/tasks.md
rename to docs/subsystems/tasks.md
diff --git a/docs/core-data-structures/tasks.zh.md b/docs/subsystems/tasks.zh.md
similarity index 100%
rename from docs/core-data-structures/tasks.zh.md
rename to docs/subsystems/tasks.zh.md
diff --git a/docs/core-data-structures/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/token-meter.i18n.yaml
rename to docs/subsystems/token-meter.i18n.yaml
diff --git a/docs/core-data-structures/token-meter.md b/docs/subsystems/token-meter.md
similarity index 100%
rename from docs/core-data-structures/token-meter.md
rename to docs/subsystems/token-meter.md
diff --git a/docs/core-data-structures/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
similarity index 100%
rename from docs/core-data-structures/token-meter.zh.md
rename to docs/subsystems/token-meter.zh.md
diff --git a/docs/core-data-structures/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/tools.i18n.yaml
rename to docs/subsystems/tools.i18n.yaml
index cd2add6a82..a30f122038 100644
--- a/docs/core-data-structures/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/tools.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
 tools.md: 853eed16cff451edcc32bc3aa5c6bc7cabb0f518
 tools.zh.md: ec8809f6bebd185404828c5c5879f8eff832ea9a
diff --git a/docs/core-data-structures/tools.md b/docs/subsystems/tools.md
similarity index 100%
rename from docs/core-data-structures/tools.md
rename to docs/subsystems/tools.md
diff --git a/docs/core-data-structures/tools.zh.md b/docs/subsystems/tools.zh.md
similarity index 100%
rename from docs/core-data-structures/tools.zh.md
rename to docs/subsystems/tools.zh.md
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/typert.i18n.yaml
rename to docs/subsystems/typert.i18n.yaml
diff --git a/docs/core-data-structures/typert.md b/docs/subsystems/typert.md
similarity index 100%
rename from docs/core-data-structures/typert.md
rename to docs/subsystems/typert.md
diff --git a/docs/core-data-structures/typert.zh.md b/docs/subsystems/typert.zh.md
similarity index 100%
rename from docs/core-data-structures/typert.zh.md
rename to docs/subsystems/typert.zh.md
diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
similarity index 79%
rename from docs/core-data-structures/user-interaction.i18n.yaml
rename to docs/subsystems/user-interaction.i18n.yaml
index 3768cfcf7b..80ebb810c8 100644
--- a/docs/core-data-structures/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/user-interaction.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/user-interaction.md
 user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014
 user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b
diff --git a/docs/core-data-structures/user-interaction.md b/docs/subsystems/user-interaction.md
similarity index 100%
rename from docs/core-data-structures/user-interaction.md
rename to docs/subsystems/user-interaction.md
diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
similarity index 100%
rename from docs/core-data-structures/user-interaction.zh.md
rename to docs/subsystems/user-interaction.zh.md
diff --git a/docs/core-data-structures/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/web.i18n.yaml
rename to docs/subsystems/web.i18n.yaml
diff --git a/docs/core-data-structures/web.md b/docs/subsystems/web.md
similarity index 100%
rename from docs/core-data-structures/web.md
rename to docs/subsystems/web.md
diff --git a/docs/core-data-structures/web.zh.md b/docs/subsystems/web.zh.md
similarity index 100%
rename from docs/core-data-structures/web.zh.md
rename to docs/subsystems/web.zh.md
diff --git a/docs/core-data-structures/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/workflow.i18n.yaml
rename to docs/subsystems/workflow.i18n.yaml
diff --git a/docs/core-data-structures/workflow.md b/docs/subsystems/workflow.md
similarity index 100%
rename from docs/core-data-structures/workflow.md
rename to docs/subsystems/workflow.md
diff --git a/docs/core-data-structures/workflow.zh.md b/docs/subsystems/workflow.zh.md
similarity index 100%
rename from docs/core-data-structures/workflow.zh.md
rename to docs/subsystems/workflow.zh.md
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 699617eef4..a100469102 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -3,7 +3,7 @@
 
 # Tool Schema Catalog
 
-Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
+Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
 
 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 978de64ed1..eee269c121 100644
--- 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: 88f519a21a0889d6b7649502c51077940c23709f
-README.zh.md: 294044692133da8baa57583146352e84c1ff9946
+README.md: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee
+README.zh.md: c343e17bfd97eaf17316c034c263b0c71bb8327a
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 88f519a21a..690f4e6174 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -31,7 +31,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp
 
 `BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, dshEnv?, sandboxPolicy?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, dshEnv?, sandboxPolicy) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxPolicy` is optional on the request and required-but-nullable on the resolved spec: it carries the complete per-call mode and workspace root. The sandbox tool path resolves it from the calling session through `ctx.sandboxPolicy`; a direct sandbox-executor caller falls back to deployment policy, while a non-sandboxing executor carries the field and confines nothing.
 
-The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md).
+The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [subsystems/bash.md](../../../docs/subsystems/bash.md).
 
 `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).
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 2940446921..c343e17bfd 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -31,7 +31,7 @@
 
 `BashExecRequest`（command、workdir?、timeoutMs?、stdoutMaxBytes?、signal?、stdin?、env?、dshEnv?、sandboxPolicy?）在执行前解析为 `BashExecSpec`（command、workdir、timeoutMs、stdoutMaxBytes、signal?、stdin?、env?、dshEnv?、sandboxPolicy）。`stdoutMaxBytes` 是受信任前台运行的捕获预算，用于必须解析完整有界 stdout 的消费方；面向模型的 bash 工具不公开该字段。`sandboxPolicy` 在请求上可选，在已解析 spec 上必填但可为 null：它携带完整的每次调用模式与工作区根目录。沙箱工具路径通过 `ctx.sandboxPolicy` 从调用会话解析它；沙箱执行器的直接调用方回退到部署策略，非沙箱执行器则携带该字段但不作限制。
 
-每会话沙箱模式覆盖词汇（`'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)。
+每会话沙箱模式覆盖词汇（`'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` 与 [subsystems/bash.md](../../../docs/subsystems/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](../../../.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)。
 
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index 1ab398842f..1252d99e0f 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: 5703540435b976cfc03987edca28e2b5cd24ae0d
-README.zh.md: 434b9bfa3d0d7f21fc262929ac72ff5ab15d5057
+README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22
+README.zh.md: 330b5b0cb9d5c2bf3953354112f3488447e71f87
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 5703540435..2bf39cac91 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -24,7 +24,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten
 | `compactNow(agent, signal)` | Explicitly compact one useful balanced older span even below automatic pressure. It synchronously reserves idle turn admission before yielding, writes nothing when no useful span exists, records a standalone `compact/* { turn: null }` attempt before summarization, and awaits its durability checkpoint before release. Expected operational failures use `ManualCompactionError`; cancellation rethrows the exact abort reason. |
 | `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source is `COMPACT_CHECKPOINT_SOURCE`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
-`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/core-data-structures/compaction.md#compactionresult).
+`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/subsystems/compaction.md#compactionresult).
 
 `compactIfNeeded` and `compactNow` take a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization. Automatic and explicit-region brackets recover their numeric owner from the currently open turn. Manual brackets require no open turn and stamp `turn: null`.
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 434b9bfa3d..330b5b0cb9 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -24,7 +24,7 @@
 | `compactNow(agent, signal)` | 即使未达到自动压力，也显式压缩一段有效、平衡的较早范围。该操作会在让出控制权前同步预留空闲轮次接纳；没有有效范围时不写入任何内容；在摘要前记录独立的 `compact/* { turn: null }` 尝试；释放预留前等待其持久性检查点。预期操作失败使用 `ManualCompactionError`；取消会原样重新抛出 abort 原因。 |
 | `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源为 `COMPACT_CHECKPOINT_SOURCE`。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 |
 
-`CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/core-data-structures/compaction.md#compactionresult)。
+`CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/subsystems/compaction.md#compactionresult)。
 
 `compactIfNeeded` 和 `compactNow` 必须传入 `signal`；`compactRegion` 的该参数可选。通过 `ctx.llm.stream()` 摘要的后端**必须** 将它转发到调用的 `GenerateOptions.signal`，因此 abort 或 fiber dispose（资源释放）会停止进行中的摘要。自动和显式范围标记对会从当前打开的轮次恢复其数字形式归属。手动标记对不要求存在打开的轮次，并标记 `turn: null`。
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 0b2d50957e..c30b37e549 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: e2c014a1448125b23475d6cdf52c02f10fc54794
-README.zh.md: a4aeead796961bd66a6c7ca1f9a66dffb60eba5d
+README.md: 07ee53006b390e5ad3979502b2f1aa24f5a6ce7a
+README.zh.md: d4a90de10b92a489f8f575b926d758b45d8f5051
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index e2c014a144..07ee53006b 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -56,7 +56,7 @@ The shared [storage codec](src/chunk-rows.ts) losslessly converts event sequence
 
 ### Surface types
 
-This package owns ordered surface projection, replacement validation, replay, and the type guards that distinguish append-origin from replacement events. The [surface type catalog](../../../docs/core-data-structures/session.md#surface-types) owns the exact shapes and field semantics. A human transcript must project append-origin events rather than `session.surface`, because landed replacements shadow history the reader already saw; model-facing consumers continue to read `session.surface`.
+This package owns ordered surface projection, replacement validation, replay, and the type guards that distinguish append-origin from replacement events. The [surface type catalog](../../../docs/subsystems/session.md#surface-types) owns the exact shapes and field semantics. A human transcript must project append-origin events rather than `session.surface`, because landed replacements shadow history the reader already saw; model-facing consumers continue to read `session.surface`.
 
 ### Request-header reconstruction (`request-header.ts`)
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index a4aeead796..d4a90de10b 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -56,7 +56,7 @@
 
 ### Surface 类型
 
-此包拥有有序 surface 投影、替换校验、回放，以及区分追加来源事件与替换事件的类型守卫。[surface 类型目录](../../../docs/core-data-structures/session.md#surface-types)拥有精确形状与字段语义。面向人的 transcript（文本记录）必须投影追加来源事件，而不是 `session.surface`，因为已落地的替换会遮蔽读者已经看到的历史；面向模型的消费方继续读取 `session.surface`。
+此包拥有有序 surface 投影、替换校验、回放，以及区分追加来源事件与替换事件的类型守卫。[surface 类型目录](../../../docs/subsystems/session.md#surface-types)拥有精确形状与字段语义。面向人的 transcript（文本记录）必须投影追加来源事件，而不是 `session.surface`，因为已落地的替换会遮蔽读者已经看到的历史；面向模型的消费方继续读取 `session.surface`。
 
 ### 请求头重建（`request-header.ts`）
 
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index b49350c1a3..657de4578e 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -39,7 +39,7 @@ import { renderToolsSdkPy } from './py-types.ts'
  * the flavor table is checked against too, so any of the three left out is a
  * typecheck failure. What no check reaches is the prose that names the values
  * instead of deriving them: the seam's `dsh-code-runtime` README pair, its
- * `CodeRuntime.language` JSDoc, and `docs/core-data-structures/code-runtime.md`
+ * `CodeRuntime.language` JSDoc, and `docs/subsystems/code-runtime.md`
  * with its zh pair, plus this package's own README pair and the
  * {@link Config.mode} JSDoc.
  */
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index d918caf377..6362a6d1e9 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/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/goal/goal/README.md
-README.md: fc2a672c11c68ad72437251b087a274e1c4388d3
-README.zh.md: eaaae5b333151b1d936effc593b21cac515471e2
+README.md: fc2fd8791096bcc9077ef7972da86b0e07c6f18e
+README.zh.md: 311ec1d03436cc45bbea28df96e66579852058b0
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index fc2a672c11..fc2fd87910 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Event-sourced same-session goal state. The service retains one current completion objective in an agent's existing session while keeping permission to continue as process-local activation. The [goal-domain Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the design rationale; the [goal type catalog](../../../docs/core-data-structures/goal.md) records the literal data shapes.
+Event-sourced same-session goal state. The service retains one current completion objective in an agent's existing session while keeping permission to continue as process-local activation. The [goal-domain Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the design rationale; the [goal type catalog](../../../docs/subsystems/goal.md) records the literal data shapes.
 
 ## Config
 
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index eaaae5b333..311ec1d034 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/core-data-structures/goal.md)记录具体的数据形状。
+事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。
 
 ## 配置
 
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 11f2a2ed86..99a5265418 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/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/sandbox/sandbox/README.md
-README.md: 1b522b2c72d00bfed89650aa7f22b65a72d26085
-README.zh.md: adccd4421a74ef073ad3ffc3a23bccb0354d99aa
+README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
+README.zh.md: e43d1918a99fa96688632551a8f861c2c91f9c2a
diff --git a/packages/sandbox/sandbox/README.md b/packages/sandbox/sandbox/README.md
index 1b522b2c72..8c1c747f6c 100644
--- a/packages/sandbox/sandbox/README.md
+++ b/packages/sandbox/sandbox/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.
 
-The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
+The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
 
 Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.
 
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index adccd4421a..e43d1918a9 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -4,7 +4,7 @@
 
 抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
-用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
+用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
 
diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
index b13c6ce917..f45602ce97 100644
--- a/packages/session/session-title/README.i18n.yaml
+++ b/packages/session/session-title/README.i18n.yaml
@@ -1,6 +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/session-title/session-title/README.md
-README.md: 9a5ec27c36f3411add37ebe231262eb5d205bc9e
-README.zh.md: 3960be40e74507279ed2f21927ee8ad4224fe138
+#   pnpm run verify-translation-pairing --write packages/session/session-title/README.md
+README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db
+README.zh.md: 9e271c044033ce17b5c8c744fe7a9cf433c7f473
diff --git a/packages/session/session-title/README.md b/packages/session/session-title/README.md
index 9a5ec27c36..13a2a1c298 100644
--- a/packages/session/session-title/README.md
+++ b/packages/session/session-title/README.md
@@ -31,7 +31,7 @@ All limits are required; the library supplies no defaults.
 
 A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and optional model provenance. The service normalizes and validates the result before it becomes durable.
 
-See the [session-title data structures](../../../docs/core-data-structures/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
+See the [session-title data structures](../../../docs/subsystems/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
 
 ## Model Experience
 
diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md
index 3960be40e7..9e271c0440 100644
--- a/packages/session/session-title/README.zh.md
+++ b/packages/session/session-title/README.zh.md
@@ -31,7 +31,7 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会
 
 提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。
 
-参见[会话标题数据结构](../../../docs/core-data-structures/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。
+参见[会话标题数据结构](../../../docs/subsystems/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。
 
 ## 模型体验
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index e67bf1a87f..86694c3c23 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: ec4a4e3328a5a600441d2e7983b3844f4ccc5e91
-README.zh.md: 3da79995fad9a2c8f2a6020ae18152a0e4459c71
+README.md: 6e4b9a9c50bc54a4752930ec14269d2c15233a76
+README.zh.md: d756cd9b7117d7ce9a2e79c6469d9fc188c9600b
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index ec4a4e3328..6e4b9a9c50 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -15,7 +15,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
-See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+See the [subprocess data-structure catalog](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 ## Model Experience
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 3da79995fa..d756cd9b71 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -15,7 +15,7 @@
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[子进程数据结构目录](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index 7ceb8ff432..1d803e486e 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/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/tasks/tasks/README.md
-README.md: 2f822bad139020f0ebae0165aa4e8893853f635d
-README.zh.md: fdc619fbb46267b2ae550c85cb14fcf8a916f638
+README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a
+README.zh.md: f2e4b10d30d81c840f5598141bbe246634bf2884
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 2f822bad13..b5a7380e0c 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -20,7 +20,7 @@ Owned access compares the task's `SessionId` with the caller's. Ids such as `bas
 
 Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and control-surface fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
 
-See the [task type catalog](../../../docs/core-data-structures/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
+See the [task type catalog](../../../docs/subsystems/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
 
 ## Model Experience
 
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index fdc619fbb4..f2e4b10d30 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -20,7 +20,7 @@
 
 实现还必须兑现契约的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
 
-参见[任务类型目录](../../../docs/core-data-structures/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
+参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
 
 ## 模型体验
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index e5c2c15a00..d62739acdd 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -701,7 +701,7 @@ function typeLinks(signature: string, linkedTypePages: Readonly<Record<string, s
     if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
   }
   if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../core-data-structures/${linkedTypePages[n]})`)
+  const links = [...seen].sort().map(n => `[${n}](../subsystems/${linkedTypePages[n]})`)
   return `Types: ${links.join(' · ')}`
 }
 
@@ -756,7 +756,7 @@ export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy):
     ...BANNER,
     '# Cordis Events Catalog',
     '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.',
+    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
     '',
     GATE_NOTICE,
     '',
@@ -796,7 +796,7 @@ export function renderServices(services: ServiceEntry[], policy: CordisCatalogPo
     ...BANNER,
     '# Cordis Services Catalog',
     '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
+    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
     '',
     GATE_NOTICE,
     '',
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index d920ea82ca..edf653c3f4 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -155,7 +155,7 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
       '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata outside the core catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
-    expect(renderEvents(events)).toContain('Types: [SessionEvent](../core-data-structures/core.md)')
+    expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
     expect(renderEvents(events)).not.toContain('[PresetSpec]')
   })
 
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index 920688df6d..ebceec916b 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -777,7 +777,7 @@ function requiresLine(inject: string[]): string {
 }
 
 /** Render one reference as a link: another plugin's config type → its section,
- * a curated core-data-structures name → its page, any other workspace type →
+ * a curated subsystems name → its page, any other workspace type →
  * its source file, an external type → named with its module, unlinked. */
 function refLink(ref: TypeRef, byName: Map<string, CatalogEntry>): string {
   const target = byName.get(ref.specifier)
@@ -785,7 +785,7 @@ function refLink(ref: TypeRef, byName: Map<string, CatalogEntry>): string {
     return `[\`${ref.alias}\`](#${slug(target.pkg)})`
   }
   const page = LINK_MAP[ref.imported]
-  if (page) return `[\`${ref.alias}\`](core-data-structures/${page})`
+  if (page) return `[\`${ref.alias}\`](subsystems/${page})`
   if (target) return `[\`${ref.alias}\`](../${target.entry})`
   return `\`${ref.alias}\` (\`${ref.specifier}\`)`
 }
@@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '# Plugin Config Catalog',
     '',
-    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md) documents the types these declarations reference.',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
     '',
     'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
     '',
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 302ec7fdd9..d9f3803547 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -18,7 +18,7 @@ const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
 const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** One primary core-data-structures page per project type used by a generated signature. */
+/** One primary subsystems page per project type used by a generated signature. */
 export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index e6d6acbdf2..4f72b1d953 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1344,7 +1344,7 @@ function renderIndex(docs: GraphDoc[]): string {
   const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
   return [
     ...generatedHeader('Documentation Graph Index'),
-    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).',
+    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).',
     '',
     'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
     '',
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 685e4b65ef..800497ddb7 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -31,7 +31,7 @@ const EVENT_ENVELOPE_TYPE_NAMES = [
 
 type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number]
 
-/** Primary core-data-structures page for linked payload types. */
+/** Primary subsystems page for linked payload types. */
 const LINK_MAP: Record<string, string> = {
   CallId: 'core.md',
   ContentBlock: 'core.md',
@@ -330,7 +330,7 @@ function typeLinks(payload: string): string {
     if (new RegExp(`\\b${name}\\b`).test(payload)) seen.add(name)
   }
   if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](core-data-structures/${LINK_MAP[n]})`)
+  const links = [...seen].sort().map(n => `[${n}](subsystems/${LINK_MAP[n]})`)
   return `Types: ${links.join(' · ')}`
 }
 
@@ -352,11 +352,11 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
-    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
     '',
     '## Event envelope',
     '',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 55ec5eb57f..39ed4d7620 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -608,7 +608,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 89e417558c..ebdce88f6d 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -271,7 +271,7 @@ describe('docsPages locale routes', () => {
 
   it('projects translated core-data pages while retaining explicit English fallbacks', () => {
     const rootPages = docsPages.filter(page => (
-      page.locale === 'root' && page.route.startsWith('reference/core-data-structures/')
+      page.locale === 'root' && page.route.startsWith('reference/subsystems/')
     ))
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
@@ -279,9 +279,9 @@ describe('docsPages locale routes', () => {
     expect(translated).toHaveLength(20)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks.map(page => page.source).sort()).toEqual([
-      'docs/core-data-structures/commands.md',
-      'docs/core-data-structures/goal.md',
-      'docs/core-data-structures/pty.md',
+      'docs/subsystems/commands.md',
+      'docs/subsystems/goal.md',
+      'docs/subsystems/pty.md',
     ])
   })
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 40b3f620e3..3d1ca11612 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 9180a3bd9a..56c1b094be 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -2,1566 +2,1566 @@
   "comment": "Maps each primary ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Paired `.zh.md` blocks are byte-identical derivatives checked through their unsuffixed sibling and have no duplicate entry. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence between primary blocks and entries. Add an entry when you add a primary source-equivalence block; remove it when you remove the block.",
   "entries": [
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "Branded",
       "source": "packages/util/brand/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContentBlockMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "AssistantProvenance",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "Message",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "MessageSourceMap",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContextForm",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContextSnapshotSection",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContextFormed",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "FinishReasonMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "AdapterRegistrationHandle",
       "source": "packages/llm/llm/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmProviderInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelDiscoveryRequest",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmDiscoveredModel",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelContext",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ReasoningEffortId",
       "source": "packages/llm/llm/src/brand.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmReasoningEffortInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelReasoningInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmResolvedModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "GenerateOptions",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ToolSchema",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmCallConfig",
       "source": "packages/llm/llm/src/call-config.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmCallConfigAdapterDefaults",
       "source": "packages/llm/llm/src/call-config.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
       "source": "packages/core/agent/src/inbox.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "CancelOptions",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "AgentCancelCause",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "Agent",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "PreStepDecision",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "RequestErrorAction",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "SessionStartSource",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "ScopeKey",
       "source": "packages/core/scope/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "Scoped",
       "source": "packages/core/scope/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "Scope",
       "source": "packages/core/scope/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "ScopeLayer",
       "source": "packages/core/scope/src/store.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalRef",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalPhase",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalBlockReason",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalSnapshot",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalView",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalSnapshotChangeMeta",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalClearChangeMeta",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalMessageSource",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "CreateGoalRequest",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "EditGoalRequest",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalChanged",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandInputDescriptor",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandDefinition",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandInvocation",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandResult",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandDescriptor",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "ParsedCommand",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "AssembleContext",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "PromptContext",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "PromptSection",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "ToolProviderResult",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "StreamChunk",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmFailure",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "TokenUsage",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContentBlockMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "AppIdentity",
       "source": "packages/llm/llm/src/attribution.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "BlockAssembler",
       "source": "packages/llm/llm/src/assembler.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "PreparedLlmCall",
       "source": "packages/llm/llm/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmAdapter",
       "source": "packages/llm/llm/src/index.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/token-meter.md",
+      "doc": "docs/subsystems/token-meter.md",
       "symbol": "TokenMeasurement",
       "source": "packages/llm/token-meter/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/token-meter.md",
+      "doc": "docs/subsystems/token-meter.md",
       "symbol": "TokenSurfaceNode",
       "source": "packages/llm/token-meter/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "UserMessage",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SessionEventMap",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "EpochHeader",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "RequestContext",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "TodoItem",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "TurnEndCancelCause",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "TurnEndReasonMap",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceEventType",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceOp",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceIntent",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SessionSurface",
       "source": "packages/core/session/src/surface.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceFoldReplacement",
       "source": "packages/core/session/src/surface.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceFoldResult",
       "source": "packages/core/session/src/surface.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "Session",
       "source": "packages/core/session/src/index.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionHeader",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "CreateSessionOptions",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "RestoredSessionOptions",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "PrepareSessionOptions",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPreparationOptions",
       "source": "packages/core/session/src/preparation.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPreparation",
       "source": "packages/core/session/src/preparation.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionInspection",
       "source": "packages/session/session-persistence/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionLocation",
       "source": "packages/session/session-persistence/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSurface",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionLogSnapshot",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSurfaceSnapshot",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionTitleObservation",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionTitleObservationResult",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionLineageNode",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionLineageTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionQueryErrorCode",
       "source": "packages/session-query/session-query/src/config.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventReadRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventWindow",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventTraceRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventTraceObservation",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProviderId",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleModelProvenance",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleSource",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleEventData",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleSnapshot",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleLlmRequestEventData",
       "source": "packages/session/session-title-llm/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleUserMessage",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleAutomaticMode",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProviderRequest",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProviderResult",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProvider",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "SessionReferenceInput",
       "source": "packages/context/session-reference/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "SessionReferenceCandidate",
       "source": "packages/context/session-reference/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "PreparedReferencedMessage",
       "source": "packages/context/session-reference/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "SessionReferenceErrorCode",
       "source": "packages/context/session-reference/src/config.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolOutputDefinition",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolDefinition",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ValueSchemaSpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ParameterPropertySpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ParameterSchemaSpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "InferValue",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "InferArgs",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionToken",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionInput",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecution",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolDispatchExecution",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionMode",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "CodeDispatchLog",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolRunContext",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolGuard",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolRestriction",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolFailure",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionSuccess",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionFailure",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionResult",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "PreToolDecision",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "PostToolDecision",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "JsonSchemaScalar",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "JsonSchemaType",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "JsonSchemaNode",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ObjectJsonSchema",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionOption",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionIntent",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionItem",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionRequest",
       "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionAnswerItem",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionAnswer",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "UserInteractionProvider",
       "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "UserInteractionError",
       "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalRequestId",
       "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalOutcome",
       "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalPolicy",
       "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalRequest",
       "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashExecRequest",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashExecSpec",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashRunResult",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashSandboxInfo",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashProcess",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashProcessRead",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskKindMap",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskStart",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskHooks",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskOutcome",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskSnapshot",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskRead",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtyWaitReason",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtySessionStatus",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtyBackend",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtyBackendSession",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtySendOperation",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtySendResult",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxMode",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "ConfinedSandboxMode",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxExecutionPolicy",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxEnforcement",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxPolicy",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxPolicyRequest",
       "source": "packages/sandbox/sandbox-policy/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "RunnerFailureRule",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "ConfinedArgv",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeJsonValue",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeRunRequest",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeRunResult",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeBindingNamespace",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeBindingErrorClass",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeBindingFunction",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeRunFailure",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsTarget",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsTargetKey",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsVersion",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsInfo",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsPathInfo",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsDirEntry",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsWriteIntent",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsWriteOutcome",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsEditRequest",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsEditOutcome",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsErrorCode",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsPolicyExec",
       "source": "packages/fs/fs-policy/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FileReadOutcome",
       "source": "packages/fs/tool-fs/src/read-render.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillSource",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillResourceBase",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillInvocationPolicy",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillSummary",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillCatalogSnapshot",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillCandidate",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillDefinition",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillRegistration",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillLookupOptions",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProviderObservation",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProvider",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProviderControl",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "Config",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "CompactionResult",
       "source": "packages/compact/compact/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "CompactionTrigger",
       "source": "packages/compact/compact/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "ManualCompactionErrorCode",
       "source": "packages/compact/compact/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "PrunedEntry",
       "source": "packages/compact/compact-tool-result-prune/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "PruneResult",
       "source": "packages/compact/compact-tool-result-prune/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentCapabilities",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentStartRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ResolvedSubagentStartRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "CoordinatorMessageSource",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportMessageSource",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportDelivery",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportOptions",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentFollowupOptions",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentInterruptAuthority",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentDescendantListEntry",
       "source": "packages/subagent/subagent/src/list-children.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ContinuableStart",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ContinuableCreateRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ContinuableCreateSpec",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentResult",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentStopReasonMap",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentRun",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentProvider",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebSearchRequest",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebSearchResult",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebSearchSource",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebFetchRequest",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebFetchResult",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebFetchBody",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SaveTextSpill",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillOwner",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillSource",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillRef",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillLocator",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowStartRequest",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowMeta",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowResult",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowRun",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspOperation",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspPosition",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspRange",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspQueryRequest",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspProviderQuery",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspLocation",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspHover",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspQueryResult",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspProvider",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspService",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPersistenceRevision",
       "source": "packages/session/session-persistence/src/revision.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPersistenceSnapshot",
       "source": "packages/session/session-persistence/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionResultFilter",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventResultFilter",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchDocument",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchCursor",
       "source": "packages/session-query/session-query/src/cursor.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchPage",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchPage",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchHit",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchHit",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessSpawnSpec",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessHandle",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutputReader",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutputRead",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutcome",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "DshEnvironmentKey",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "DshEnvironment",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "CollectedOutput",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessStdinMode",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessCollect",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutputMode",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessStdio",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessCollectedOutputs",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsNamespace",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsRegisterOptions",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsApplies",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsScope",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsDescriptor",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsUpdateSource",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/credentials.md",
+      "doc": "docs/subsystems/credentials.md",
       "symbol": "CredentialRef",
       "source": "packages/credentials/credentials/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/credentials.md",
+      "doc": "docs/subsystems/credentials.md",
       "symbol": "ResolvedCredential",
       "source": "packages/credentials/credentials/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/credentials.md",
+      "doc": "docs/subsystems/credentials.md",
       "symbol": "CredentialInfo",
       "source": "packages/credentials/credentials/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsDescribeOptions",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmConfigurableProvider",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsPathOp",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTLookupMap",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTContextMap",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTLookupDefinition",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTCodec",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "InvocationParameterDescriptor",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "InvocationDescriptor",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTService",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTRemoteNamespaceMap",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "InvokeRemoteRequest",
       "source": "packages/api/gateway/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypertGatewayErrorCode",
       "source": "packages/api/gateway/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypertGateway",
       "source": "packages/api/gateway/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
     }
diff --git a/website/docs.ts b/website/docs.ts
index 8db7951dbb..07f470319b 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -279,13 +279,13 @@ const coreDataReference = pairedPages(([
   ['settings.md', '用户设置', 'User settings', 21],
   ['credentials.md', '用户凭据', 'User credentials', 22],
 ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
-  source: `docs/core-data-structures/${file}`,
-  route: `reference/core-data-structures/${file}`,
+  source: `docs/subsystems/${file}`,
+  route: `reference/subsystems/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-reference', en: 'en-reference' },
   section: { root: '数据结构', en: 'Data structures' },
   order,
-  ...(file === 'core.md' ? { sourceAliases: ['docs/core-data-structures'] } : {}),
+  ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
 
 const reference = mirroredPages([
@@ -339,8 +339,8 @@ const reference = mirroredPages([
     ['pty.md', 'PTY 会话', 'PTY sessions', 8],
     ['commands.md', '命令', 'Human commands', 17],
   ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
-    source: `docs/core-data-structures/${file}`,
-    route: `reference/core-data-structures/${file}`,
+    source: `docs/subsystems/${file}`,
+    route: `reference/subsystems/${file}`,
     contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },

From cf5e53e051bf34cfad9a47789a18dd0fa3224410 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:37:05 +0800
Subject: [PATCH 155/262] docs: fix stale package README claims found while
 writing subsystem pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- dsh-host-webserver: the service is HttpServerService under ctx.httpServer
  (README said WebServerService/ctx.webServer, matching no symbol in source),
  and the dev-mode bundle-watch paragraph described machinery that moved to
  dsh-client-modules/dsh-client-hmr in the webserver rewrite — removed; those
  packages' READMEs already document the current pipeline.
- dsh-workspace: ctx.workspace.touchSession(id) does not exist; the
  activity-pinning chain was replaced by Workspace.insertSessionBefore
  (2026-07-25 session-list note) — the bullet now documents the real method.
- packages/storage group table: the domain package directory is
  storage-domain/, not domain/.

All three pairs updated on both sides and re-recorded.
---
 packages/host/webserver/README.i18n.yaml      | 4 ++--
 packages/host/webserver/README.md             | 2 --
 packages/host/webserver/README.zh.md          | 2 --
 packages/workspace/workspace/README.i18n.yaml | 2 +-
 packages/workspace/workspace/README.md        | 1 +
 5 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index 56fd0e7694..bd80f27f3e 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/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/host/webserver/README.md
-README.md: b6dccf2f81c9e2f0b9f53264eafe724edb560f07
-README.zh.md: dbfe420013ed67c48e47048341f020864aeef16a
+README.md: 569c3f0c19db2c308beaef35baaf915fd39768cd
+README.zh.md: b311ebffa3fb067e684e9e443c2ac02dab917d61
diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md
index b6dccf2f81..569c3f0c19 100644
--- a/packages/host/webserver/README.md
+++ b/packages/host/webserver/README.md
@@ -8,8 +8,6 @@ The package knows no harness concepts and serves no files: the `/api` HTTP bridg
 
 A listen failure (EADDRINUSE…) throws out of activation and rejects Loader composition with the bind diagnostic; the failed candidate fiber is disposed. An HTTP request whose handling throws (a fallback owner's `decodeURIComponent` on a malformed %-escape, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and logged as a warning; it never exits the process. An upgrade-handler exception or upgraded-socket transport error is logged as a warning and destroys its socket. Disposal starts `close()` and `closeAllConnections()`, destroys every tracked upgraded socket, and returns only after the HTTP server and those sockets have closed.
 
-In development, the client-plugin registry synchronously captures each built bundle's stat baseline before it returns, then polls those baselines and re-hashes changed content. Each rescan stages its candidate table, graph, and watch map before publishing them, so a baseline failure preserves the prior graph. An immediate rebuild therefore cannot disappear into an asynchronously established watch baseline; a rename window marks the path dirty, retains the last successful baseline, and forces a re-hash when the bundle reappears even with identical metadata.
-
 ## Model Experience
 
 None, as the package is a Web carrier between the browser and the HTTP/upgrade routes other plugins register; nothing here reaches a model request.
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index dbfe420013..b311ebffa3 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -8,8 +8,6 @@ Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配
 
 监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合 reject；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 `decodeURIComponent` 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 `close()` 与 `closeAllConnections()`，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
 
-在开发环境中，客户端插件注册表会在返回前同步捕获每个已构建 bundle 的 stat 基线，随后轮询这些基线，并在内容变化后重新计算哈希。每次重新扫描都会先暂存候选表、图和监听 map，再统一发布，因此基线失败会保留先前的图。这样，即时重建不会消失在异步建立的监听基线中；重命名窗口会把路径标记为脏，保留最近一次成功基线，并在 bundle 重新出现时强制重新计算哈希，即使其元数据完全相同也不例外。
-
 ## 模型体验
 
 无。该包只是浏览器与其他插件所注册 HTTP／upgrade route 之间的 Web 载体，其中没有任何内容会进入模型请求。
diff --git a/packages/workspace/workspace/README.i18n.yaml b/packages/workspace/workspace/README.i18n.yaml
index aa3db1bef6..7ba60b4109 100644
--- a/packages/workspace/workspace/README.i18n.yaml
+++ b/packages/workspace/workspace/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/workspace/workspace/README.md
-README.md: bfa044de50fc71dca95637487df50dc551d40e1b
+README.md: 057765e38de9cc700210eb8edeb1ddc7ffc861ff
 README.zh.md: f3be9611eba45db3719ce76ad6625f4787fab9ac
diff --git a/packages/workspace/workspace/README.md b/packages/workspace/workspace/README.md
index bfa044de50..057765e38d 100644
--- a/packages/workspace/workspace/README.md
+++ b/packages/workspace/workspace/README.md
@@ -12,6 +12,7 @@ The entity/storage rationale lives in the [domain Agent Note](../../../.agents/n
 - `ctx.workspace.get(id)` / `list()` / `resolveByPath(path)` — cache-served lookups. `list()` is synchronous and follows durable registry order; `resolveByPath` is async because it applies the same `realpath` canon and rejects a missing path rather than creating it.
 - `ctx.workspace.delete(id)` — removes only the Workspace registration, its durable order entry, and its session account. Unknown ids return `false`; a removed record returns `true`. The directory, user files, live Sessions, and persisted session logs are never touched, so those Sessions become Ungrouped. A table-write failure restores the prior order and published entity.
 - `Workspace.attachSession(id)` — validates a live or persisted session header cwd against the workspace path and prepends a new id. Unknown sessions, absent/unresolvable/non-directory cwd values, and mismatches reject without writing. `detachSession` removes only the candidate index entry.
+- `Workspace.insertSessionBefore(id, before?)` — moves an accounted session within the manual order, DOM-insertBefore-like: before the anchor, or appended when the anchor is omitted. A session or anchor absent from the account rejects without writing; a move to the current position resolves without writing. Workspace order never changes.
 - `ctx.workspace.archiveSession(id)` / `archivedSessionIds` — the registry-global archive set, layered over workspace accounting: an archived session disappears from grouping surfaces but keeps its session log and its `sessionIds` slot, so a future unarchive restores its position. Archiving accepts any live or persisted session (accounted or Ungrouped), resolves without writing for an already archived id, and rejects an unknown id. State written before the field existed parses with an empty set.
 - `Workspace.sessionIds` — synchronous id-plus-canonical-cwd membership projection in durable candidate order. Missing headers, invalid cwd values, and mismatches are filtered; the next workspace mutation prunes them. A medium indexing one session under two workspaces, claiming one path from two records, or diverging from durable workspace order rejects at startup.
 - `Workspace.status()` — uncached directory check, `'ok' | 'missing-dir'`; a missing directory never mutates the record.

From e3af8d2ed247d5440c931973e3b33613568e5ed1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:48:20 +0800
Subject: [PATCH 156/262] docs: add eight lean subsystem pages covering every
 remaining service

permission, plan, invariants, http-server, storage (hub + backend seam +
domain form + domain/changed), workspace, tui, and client-modules complete
the docs/subsystems tier: every ctx service and event scope now has one
owning page, the precondition for generating per-subsystem service/event
reference into these pages. 25 new type-equiv manifest entries; 16 types
move from TYPE_LINK_EXEMPTIONS to LINK_MAP now that they have catalog
homes (dead InvariantRegistration exemption removed; catalogs
regenerated); core.md's sub-page table gains the eight rows in both
languages; the owning subsystems-catalog Agent Note records the coverage
extension. Chinese counterparts and pair records follow in the next
commit.
---
 ...2026-06-20-core-data-structures-catalog.md |   1 +
 ...6-06-20-core-data-structures-catalog.zh.md |   1 +
 docs/cordis-catalog/events.md                 |   2 +
 docs/subsystems/client-modules.md             |  63 +++
 docs/subsystems/core.md                       |   8 +
 docs/subsystems/core.zh.md                    |   8 +
 docs/subsystems/http-server.md                |  49 ++
 docs/subsystems/invariants.md                 |  59 ++
 docs/subsystems/permission.md                 |  63 +++
 docs/subsystems/plan.md                       |  39 ++
 docs/subsystems/storage.md                    | 125 +++++
 docs/subsystems/workspace.md                  | 121 ++++
 .../tests/cordis-catalog-contract.spec.ts     |   4 +-
 scripts/gen-cordis-catalog.ts                 | 521 +++++++++++++++---
 scripts/type-equiv.manifest.json              | 123 +++++
 15 files changed, 1104 insertions(+), 83 deletions(-)
 create mode 100644 docs/subsystems/client-modules.md
 create mode 100644 docs/subsystems/http-server.md
 create mode 100644 docs/subsystems/invariants.md
 create mode 100644 docs/subsystems/permission.md
 create mode 100644 docs/subsystems/plan.md
 create mode 100644 docs/subsystems/storage.md
 create mode 100644 docs/subsystems/workspace.md

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 57433fdcb3..025cbd7ab7 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -58,3 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
+- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the eight `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 3956839c82..de644e8567 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -58,3 +58,4 @@ Status: implemented
 - 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
+- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的八个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index dd9cf5bfa5..6d060cf26b 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -389,6 +389,8 @@ A domain record or the global singleton changed, emitted once per write strictly
 'domain/changed'(change: DomainChanged): void
 ```
 
+Types: [DomainChanged](../subsystems/storage.md)
+
 Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
 
 ## `fs/*`
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
new file mode 100644
index 0000000000..bd5ecdc85e
--- /dev/null
+++ b/docs/subsystems/client-modules.md
@@ -0,0 +1,63 @@
+# Client Modules
+
+English | [中文](client-modules.zh.md)
+
+The web plugin table: the Node half of the client module system in [dsh-client-modules](../../packages/client/modules), provided as `ctx.clientModuleHost` (`ClientModuleHostService`). It scans the host Loader's entries for `dshClient` packages, composes the `window.__DSH_BOOT__` entry graph, serves each bundle at `/plugins/<id>/client.js`, and taps the index render to inject the boot manifest — the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of [dsh-host-webserver](../../packages/host/webserver): the carrier described in [http-server.md](http-server.md) supplies the prefix route and index tap this service registers. The same package's browser half (`ctx.modules`, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the [package README](../../packages/client/modules/README.md), not here.
+
+Source: [`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
+
+## The wire
+
+The graph is the wire single source between the Node and browser halves: the host composes `WebBootEntry` rows from scanned packages, injects the graph as the first script in `<head>` (`window.__DSH_BOOT__`, with `<` escaped so plugin-controlled strings cannot break out of the script element), and the shell parses it before booting anything. A page without a valid manifest cannot boot — the browser-side parser throws loud on a missing or malformed graph.
+
+```ts type-equiv
+/**
+ * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's dshClient
+ * declaration and reach fibers through entry creation).
+ */
+interface WebBootEntry {
+  /** Entry name == package name. */
+  id: string
+  /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+  url: string
+  /** Bundle content hash (cache-busting consistency anchor). */
+  rev: string
+  /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+  inject?: string[]
+  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  immediately?: boolean
+}
+```
+
+```ts type-equiv
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
+interface WebBootGraph {
+  /** Consistency anchor over the whole graph (content + bundle hashes). */
+  rev: string
+  /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
+  entries: WebBootEntry[]
+}
+```
+
+Each row's `rev` is the bundle's content hash and rides the URL as a cache-busting query; the graph `rev` hashes the composed rows, so any row change changes it. `immediately` marks the stage-one prefetch tier (fetch and execute during module-face boot, registration only); a lazy row is fetched on first import.
+
+## The scan
+
+A package joins the table by declaring `dshClient` (`platform: 'web'`, optional `inject` edges, optional `immediately`) in its package.json and exporting its built bundle at `exports["./client"]`. Package resolution anchors at the config tree's `ctx.baseUrl` — the cordis.yml directory, whose package declares every composed plugin as a dependency — and construction throws when that anchor is unset.
+
+Scanning is incremental per package; there is no full-rescan code path. Every cordis `internal/plugin` emission (fiber construction or disposal) marks the fiber's entry name dirty, and a microtask flush reconciles each dirty name against the live loader entries. The activation pass seeds the same dirty set with all current entries and flushes synchronously, so first scan and steady state share one implementation — with opposite failure postures. At activation, a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud `AggregateError` listing every broken package: the fiber FAILS and the boot's fail-loud sweep reports it. In steady state, a broken package logs a warning and must not poison the others.
+
+Package metadata — including the negative "not a client package" verdict — is cached per name and never expires: plugin-set changes take effect on restart. A fiber restart reuses its row and rev untouched; bundle content changes reach the graph only through `rebuilt()`.
+
+## The bundle route and index tap
+
+`GET`/`HEAD /plugins/<id>/client.js` serves the registered bundle from disk with `no-cache` (the rev query, not HTTP caching, anchors consistency); other methods are 405. An unknown id — or a registered row whose bundle is unreadable because it has not been built yet — answers a loud 404 rather than letting the carrier's SPA fallback ship HTML as JavaScript. The index tap injects the current graph on every index render, so a reload always boots against the live composition.
+
+## The service
+
+`ClientModuleHostService` (`ctx.clientModuleHost`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice). `graph()` returns the current composed graph (a stable object between changes) and `clientPath(id)` the bundle's absolute path. `rebuilt(id)` is the only entry point through which bundle content reaches the graph: it re-hashes the file, and only a real rev change recomposes the graph and notifies. `onRebuilt` fires per changed bundle with the new rev; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt rev change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
+
+In development, [dsh-client-hmr](../../packages/client/hmr/README.md) is the registry's watch driver: its node half stat-polls every graph row's bundle from a synchronously captured baseline, calls `rebuilt(id)` on change, resyncs its watch set through `onGraphChanged`, and broadcasts rev changes to the browser half over SSE. Production graphs omit the HMR row entirely; the module host itself never watches files.
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 8f413a7a06..bde64a39e4 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -46,6 +46,14 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
 | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
 | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
+| [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
+| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
+| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
+| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
+| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
+| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
+| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
+| [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 
 > Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index d0f02f0cfc..1f21785cad 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -46,6 +46,14 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
+| [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
+| [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空伴随插件契约 |
+| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
+| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
+| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
+| [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
+| [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
 
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
new file mode 100644
index 0000000000..565df72f27
--- /dev/null
+++ b/docs/subsystems/http-server.md
@@ -0,0 +1,49 @@
+# HTTP Server
+
+English | [中文](http-server.zh.md)
+
+[dsh-host-webserver](../../packages/host/webserver) is the web-shape HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.httpServer`, a named-route registry plus index.html transform taps over a static dist fallback. It is not part of the agent-loop spine and not a capability seam — it knows no harness concepts, and every feature surface (the `/api` bridge, plugin bundles, the HMR event stream) is a route some other plugin registers ([layering note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). Web (browser) shape only: Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server.
+
+Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
+
+## Routes
+
+```ts type-equiv
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+type WebRouteKind = 'exact' | 'prefix'
+```
+
+```ts type-equiv
+/** One named route registration. */
+interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+```
+
+Match order is fixed: exact table first, then longest matching prefix, then the static dist fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback answers anything not yet claimed during the boot window. The fallback keeps locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream ([`static.ts`](../../packages/host/webserver/src/static.ts)).
+
+## Config
+
+```ts type-equiv
+/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
+  distIndex: string
+}
+```
+
+`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. `distIndex` is an assembly fact the composing app resolves and injects.
+
+## The service
+
+`HttpServerService` (`ctx.httpServer`) listens immediately on activation; a listen failure (EADDRINUSE…) throws out of init — a FAILED fiber the boot's fail-loud sweep reports. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws, because route patterns are a composition-level contract and a collision is a misconfiguration. `tapIndex(transform)` adds a pure html-to-html transform applied to every index response — `/` and each SPA fallback — in registration order; [dsh-client-modules](../../packages/client/modules) uses it to inject the boot manifest. `port` reads the listening port, the OS-assigned value when `config.port` is 0.
+
+A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 — or the socket destroyed when headers are already out — never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](../../packages/host/webserver/README.md).
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
new file mode 100644
index 0000000000..143a7feabb
--- /dev/null
+++ b/docs/subsystems/invariants.md
@@ -0,0 +1,59 @@
+# Runtime Invariants
+
+English | [中文](invariants.zh.md)
+
+[dsh-invariants](../../packages/support/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the seam design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).
+
+Source: [`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
+
+## Selection
+
+```ts type-equiv
+/** Runtime invariant selection configured on the service plugin. */
+interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
+}
+```
+
+A package is selected when the service is enabled, the allowlist is empty or at least one pattern matches its full npm name, and no blocklist pattern matches — a blocklist match overrides an allowlist match. Entries compile with `new RegExp(source)`: matching is unanchored unless the source supplies `^` and `$`, and `/pattern/flags` syntax is not parsed. Validation fails loud at service startup: a blank, whitespace-padded, duplicate, or invalid entry throws instead of being skipped. A valid pattern may match no currently loaded package, so later loading and HMR stay deterministic; filters are fixed for the service lifetime ([README](../../packages/support/invariants/README.md)).
+
+## The installer
+
+```ts type-equiv
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+type InvariantFailure = (message: string) => never
+```
+
+```ts type-equiv
+/** Install one package's checks into the registration's child context. */
+interface InvariantInstaller {
+  /**
+   * Install the package contribution.
+   * @param ctx - child context owned by this invariant registration.
+   * @param fail - reporter bound to the registering package name.
+   * @returns nothing, or a promise settling after asynchronous checks finish.
+   */
+  (ctx: Context, fail: InvariantFailure): void | Promise<void>
+  /** Services the child installer fiber may access. */
+  readonly inject?: Inject
+}
+```
+
+An enabled installer runs in a dedicated child Cordis fiber; `installer.inject` declares the services that fiber may access, and synchronous or asynchronous installer completion is joined before the registration succeeds. `fail(message)` throws `InvariantError` — `extends Error` with stable `code: 'INVARIANT'`, the owning `packageName`, and a message prefixed `invariant violated by "<package>": …` — so a violation is attributable without the registry importing any product package.
+
+## The service
+
+`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name and returns its effect-scoped disposer. The reservation holds even when filters keep the installer inactive, so two plugins can never silently claim the same package name; a duplicate, blank, or whitespace-containing name throws. An installer failure disposes the child fiber and releases the reservation atomically. The service owns every registration fiber while the returned disposer also belongs to the companion fiber: unloading either side removes listeners, trace state, and the reservation, so a companion can reload and register the same name again without retained state.
+
+## The companion contract
+
+Every workspace package owns a `./invariant` companion ([package contract](../../packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](../../packages/support/invariants/README.md).
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
new file mode 100644
index 0000000000..49dd51ff86
--- /dev/null
+++ b/docs/subsystems/permission.md
@@ -0,0 +1,63 @@
+# Permission Presets
+
+English | [中文](permission.zh.md)
+
+The permission-preset layer of [dsh-permission](../../packages/ui/permission) (`ctx.permission`, `PermissionService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/ui/permission/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
+
+Source: [`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+
+## The preset table
+
+A preset is a table key mapping to one sandbox/approval bundle plus optional client presentation; the default table ships `workspace-write` (`workspace-write` + `ask`) and `danger-full-access` (`danger-full-access` + `never`).
+
+```ts type-equiv
+/** One preset's sandbox/approval bundle and optional client presentation. */
+interface PresetSpec {
+  /** The `sandbox/mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** The {@link PermissionService} config: the deployment's preset table. */
+interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `workspace-write`
+   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
+   * never). The name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+}
+```
+
+The service requires a confining `ctx.bash` executor and `ctx.approval`, and misconfiguration fails at plugin load: a table entry named `custom` throws (the name is reserved for the derived not-a-preset state), and composing over a bash executor that does not confine (no `sandboxMode` capability fact) throws, because presets bundle a sandbox mode.
+
+## Current preset and the derived `custom`
+
+`current(events)` derives the effective preset from the knobs, not from its own event alone: it folds the session's effective sandbox mode (falling back to the executor's configured mode) and effective approval policy (falling back to the approval service config, then `ask`), prefers a still-matching recorded selection, then the first matching table entry in declaration order, and otherwise returns `CUSTOM_PRESET` (`'custom'`). `custom` is derived-only: clients may display it as the current value, but it is never a switch target or an event payload.
+
+`names` lists the switchable presets in table declaration order; `optionOf(name)` builds the option a client renders for a table key (label falls back to the key) or for `custom`, and throws for any other name.
+
+```ts type-equiv
+/** The select-option shape a presentation layer advertises for one preset (or for the derived `custom` state). */
+interface PresetOption {
+  /** Stable option value: the table key, or `custom`. */
+  value: string
+  /** The display label. */
+  name: string
+  /** One user-facing sentence on what the value means. */
+  description?: string
+}
+```
+
+## Switching and the `permission/preset` event
+
+`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/ui/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
+
+`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxpermission--permissionservice).
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
new file mode 100644
index 0000000000..f67e7734ca
--- /dev/null
+++ b/docs/subsystems/plan.md
@@ -0,0 +1,39 @@
+# Plan Mode
+
+English | [中文](plan.zh.md)
+
+Plan mode is logged per-agent collaboration state owned by [dsh-plan-mode](../../packages/plan/plan-mode) (`ctx.planMode`, `PlanModeService`): while active, a deployment-owned guidance section shapes each model request. It is **soft guidance**, deliberately independent of the [sandbox mode](sandbox.md) and [approval policy](approval.md) enforcement axes — those knobs never read or write plan state, and deployments needing a hard boundary combine them separately. The package is one optional capability, not part of the agent-loop spine; its surfaces are the `plan:policy` prompt section, the always-registered `exit_plan_mode` tool, and the `/plan` command. The [design note](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) owns the rationale; the [package README](../../packages/plan/plan-mode/README.md) owns the model-experience and limitation detail.
+
+Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
+
+## Logged state and recovery
+
+`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. `foldPlanMode(events, end?)` returns the last logged value in the prefix, or `false` when there is none — the state in force is always a pure fold of the session log, so resume, fork, and compaction recover it with no live mirror, and UIs observe committed flips through `session/event`. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
+
+## Pending intent and the turn-boundary flush
+
+Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
+
+The service flushes one pending selection before the affected request assembly at three boundaries: prompt submission, ordinary turn continuation, and request-recovery retry. The flush runs after the downstream listener chain, so a selection arriving while an async listener awaits still shapes the request that boundary precedes. A flush failure is contained — plan policy can never block a prompt or turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+
+## Configuration
+
+```ts type-equiv
+/** Deployment-owned plan guidance. */
+interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than silently shaping nothing. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](system-prompt.md) at order 50; inactive plan mode contributes no text.
+
+## The exit tool and the `/plan` command
+
+[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) stays registered while plan mode is inactive, so crossing the boundary changes only the prompt section, never the request tool catalog; execution outside plan mode fails. In plan mode it requires a complete markdown plan starting with a `#` heading and presents it for review through the [user-interaction seam](user-interaction.md). Approval returns `{ approved: true }` and records a silent (non-narrated) pending exit that flushes after the step — plan guidance holds for the rest of the assistant's tool batch, and the tool result itself narrates the transition. Keep-planning is a failed call carrying the user's feedback, so the model revises and presents again; a missing interaction channel and a service reload during review also fail the call rather than silently leaving plan mode.
+
+When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off|message]`: bare `/plan` selects plan mode, any other non-empty message selects it and then submits the text through `agent.steer()` so it becomes the next step's ordinary logged user message under plan guidance, and the exact argument `off` selects inactive — which also cancels a not-yet-flushed pending entry before plan mode ever reaches a request.
+
+## The service
+
+`ctx.planMode` owns the logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxplanmode--planmodeservice).
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
new file mode 100644
index 0000000000..5d54d7337b
--- /dev/null
+++ b/docs/subsystems/storage.md
@@ -0,0 +1,125 @@
+# Storage
+
+English | [中文](storage.zh.md)
+
+The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and backend interface ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the backend implementations ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the domain data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend seam's only consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
+
+Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
+
+## The hub: `ctx.storage`
+
+`Storage` ([signatures](../cordis-catalog/services.md#ctxstorage--storage)) is a meeting point, not a store. `ctx.storage.backend` is a name → backend table: multiple backends stay mounted side by side, and which backend serves which consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register(name, backend)` returns the disposer; duplicate names and unknown lookups throw `StorageError`. Disposal only unregisters the name — the owning plugin closes the backend after unregistering. Each backend plugin also publishes a lifecycle-only service key (`storageBackendServiceKey(name)`), which form providers inject so their activation cannot race backend registration.
+
+Data forms mount on the hub under a merge-extensible key map:
+
+```ts type-equiv
+/**
+ * Data forms mountable on the hub, keyed by form name. Form owners extend
+ * this map via declaration merging (the domain layer merges
+ * `domain: DomainFacility`) and mount the facility in their `apply`.
+ */
+interface StorageForms {}
+```
+
+`mount(form, facility)` is an effect whose disposer unmounts; a second mount of the same key throws `duplicate-mount`. `form(form)` resolves a mounted facility and throws `form-not-mounted` until the owning plugin loads — assemblies order plugins accordingly rather than silently deferring. The domain layer merges `domain: DomainFacility`, so `ctx.storage.domain` and `ctx.storageDomain` are the same object.
+
+## The backend seam
+
+```ts type-equiv
+/**
+ * One registered backend. A backend owns exactly one medium and shares its
+ * lifecycle across all facets; facets are optional members — a backend that
+ * cannot serve a shape simply omits it, and resolution fails loud instead.
+ */
+interface StorageBackend {
+  /** Key-value data shape; absent when this backend cannot serve it. */
+  readonly kv?: KvFacet
+
+  /**
+   * Drain in-flight writes across all open units and release the medium.
+   * Idempotent; concurrent and repeated calls resolve once teardown finishes.
+   * @returns resolution after the medium is released.
+   */
+  close(): Promise<void>
+}
+```
+
+A backend owns one medium (a file-tree root, a database file) and exposes optional data-shape facets; `kv` is the only facet today. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, format version, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are arbitrary strings that never reach file paths. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium and durable once resolved. A medium stamped with a different version rejects `version-mismatch`; one that cannot be parsed as the unit rejects `malformed-medium` (no migration, pre-release stance). [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) asserts every clause against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores document-per-row in one database, the route for high-churn domains.
+
+## Declaring a domain
+
+A domain is declared once by its owning package as a spec object — the single source of the domain's identity, layout, and record schemas (zod, so `z.infer` keeps consumer types un-duplicated):
+
+```ts type-equiv
+/** Static declaration of one domain: identity, version, and record layout. */
+interface DomainSpec {
+  /** Domain name; must match `UNIT_NAME_RE` (doubles as the backend unit name). */
+  readonly name: string
+  /** Domain format version; a medium stamped with a different version rejects at open. */
+  readonly version: number
+  /** Optional global singleton slot. */
+  readonly global?: DomainGlobalSpec<unknown>
+  /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */
+  readonly tables: Record<string, DomainTableSpec>
+}
+```
+
+`defineDomain(spec)` pins the spec's literal types and fails loud at the owner's module load, before any medium is touched: a domain or table name outside `UNIT_NAME_RE`, a version that is not a non-negative integer, or a global schema that accepts `null` all throw (`null` is the medium's "never written" sentinel, so a stored nullable global could not round-trip). `domainTable<K, V>(schema)` declares one table with a phantom compile-time key type (typically a [branded id](core.md#branded-ids)); `descriptorOf(spec)` projects the backend-facing unit descriptor.
+
+## The open domain
+
+```ts type-equiv
+/** One open domain, typed by its spec. */
+interface Domain<S extends DomainSpec> {
+  /** Domain name from the spec. */
+  readonly name: string
+  /** Global singleton handle; a spec without `global` has no usable handle (`never`). */
+  readonly global: DomainGlobalHandleOf<S>
+  /**
+   * Resolve one declared table handle. Handles are stable — repeated calls
+   * return the same instance.
+   * @param name - Declared table name.
+   * @returns the typed table handle.
+   */
+  table<N extends keyof S['tables'] & string>(name: N): KvTable<TableKeyOf<S, N>, TableValueOf<S, N>>
+
+  /**
+   * Close this domain: reject new writes immediately, drain already-queued
+   * writes (their events still emit), release the backend unit, then free
+   * the domain name for a later open. Idempotent — repeated calls share one
+   * teardown. The consumer owns this call (typically as its own `ctx.effect`
+   * disposer); the facility closes any domain left open when it unmounts.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void>
+}
+```
+
+Reads are synchronous from authoritative in-memory state: `KvTable` exposes `get`/`entries`/`keys`/`size` (snapshot iterators that stay stable while queued writes land), and the global handle's `get()` serves the spec's `initial` until the first `set` materializes the slot on the medium. Every write — `put`, `delete`, `update`, `global.set` — queues on one per-domain chain and reaches backend durability first, then mutates memory, then emits `domain/changed`; a rejected backend write leaves memory untouched, so reads never diverge from the medium. `update(key, fn)` is an atomic read-modify-write at its chain slot (a missing key rejects `missing-key`); `delete` of an absent key resolves `false` with no write and no event. Returned records are the stored objects themselves, not copies — replace via `put`/`update`, never mutate in place.
+
+## The domain facility: `ctx.storageDomain`
+
+`DomainFacility` ([signatures](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)) opens declared domains over routed backends. Routing is the domain plugin's configuration, never the hub's: `backend` names the required default route and `routes` overrides it per domain name. `open(spec)` runs a strict sequence, each step failing the whole call: it rejects a name already open or still closing (`already-open`), resolves the route (`backend-not-found`), requires the backend's `kv` facet (`facet-unsupported`), opens the unit (backend `version-mismatch`/`malformed-medium` pass through), and validates every stored record and global against the spec's zod schemas (`invalid-record` with the offending table and key). The caller owns the returned handle and releases it with `Domain.close()`; domains still open when the plugin unmounts are closed by the facility, and a closed domain's name frees for reopening only after teardown fully completes. `get(name)` is an untyped diagnostic lookup onto the package-private `DomainImpl` runtime behind every typed handle; `closeAll()` is the unmount path.
+
+## The change event: `domain/changed`
+
+Every durable write emits one event strictly after the backend acknowledged durability, in the domain's write-chain order ([event entry](../cordis-catalog/events.md#domainchanged--emit)):
+
+```ts type-equiv
+/** Shared location fields of one durable domain change. */
+interface DomainChangedBase {
+  /** Owning domain name. */
+  readonly domain: string
+  /** Table name; `''` for a global-singleton write. */
+  readonly table: string
+  /** Record key; `''` for a global-singleton write. */
+  readonly key: string
+}
+```
+
+```ts type-equiv
+/** One durable domain change; a closed union — switch on `operation`. */
+type DomainChanged = DomainChangedPut | DomainChangedDeleted
+```
+
+`put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is deferred work recorded in the [package README](../../packages/storage/storage-domain/README.md).
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
new file mode 100644
index 0000000000..2726115457
--- /dev/null
+++ b/docs/subsystems/workspace.md
@@ -0,0 +1,121 @@
+# Workspaces
+
+English | [中文](workspace.zh.md)
+
+A workspace is the persistent record of a directory the user works in: a stable id over a canonical path, a display title, and the ordered account of sessions that belong to it. The subsystem is one package ([dsh-workspace](../../packages/workspace/workspace), `ctx.workspace`) — an optional host-side capability, not part of the agent-loop spine, and invisible to models (no tools, no prompt text, no session events). It stores its records through the [storage domain form](storage.md) and validates session membership against [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log), so `storageDomain` and `sessionPersistence` are mandatory startup dependencies: an unavailable persistence peer leaves the plugin pending rather than being mistaken for an empty history. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md); bootstrap and GUI ordering: [Workspace UI product-flow Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md).
+
+Source: [`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
+
+## Identity
+
+```ts type-equiv
+/**
+ * Identifies one workspace record. A generated uuid, never the path: path
+ * normalization rewrites paths, and a reference anchor must stay stable.
+ */
+type WorkspaceId = Branded<'WorkspaceId'>
+```
+
+`WorkspaceId` is a [branded id](core.md#branded-ids). Path identity is separate: `realpathNormalize` (`fs.realpath`; trailing slashes, `..`, and symlinks resolved) is the one uniqueness canon — workspace paths are stored canonicalized, uniqueness is string equality of canonical paths (a symlink to an owned directory collides), and attach-time session cwd checks go through the same canon.
+
+## The workspace entity
+
+Consumers see only the `Workspace` interface; the implementation stays package-private.
+
+```ts type-equiv
+/**
+ * One workspace: a stable id over an existing directory, a display title, and
+ * an ordered candidate account of sessions. Membership requires both an id in
+ * that account and a session header whose canonical cwd equals the workspace
+ * path. Consumers only see this interface; the implementation stays private.
+ */
+interface Workspace {
+  /** Stable record id (generated uuid). */
+  readonly id: WorkspaceId
+
+  /**
+   * Canonical directory path: the `fs.realpath` of the path given at create
+   * time (trailing slashes, `..`, and symlinks all resolved). Never rewritten
+   * afterwards, even when the directory disappears (see {@link status}).
+   */
+  readonly path: string
+
+  /** Display title. Defaults to `basename(path)` at create; duplicates are allowed. */
+  readonly title: string
+
+  /** ISO-8601 creation instant, stamped at create and never rewritten. */
+  readonly createdAt: string
+
+  /** ISO-8601 instant of the last durable mutation (create counts as one). */
+  readonly updatedAt: string
+
+  /**
+   * Header-validated sessions in manually owned order: a new session is
+   * prepended at attach, explicit reordering goes through
+   * `insertSessionBefore`, and activity never reorders. The durable candidate
+   * account is filtered synchronously: missing headers, invalid cwd values,
+   * and canonical cwd mismatches are never returned. A subsequent workspace
+   * mutation prunes those filtered candidates durably.
+   */
+  readonly sessionIds: readonly SessionId[]
+
+  /**
+   * Replace the display title durably.
+   * @param title - New title; any string, duplicates across workspaces allowed.
+   * @returns resolution after durability.
+   */
+  setTitle(title: string): Promise<void>
+
+  /**
+   * Prepend a session to this workspace's candidate account. An already
+   * accounted id resolves without writing. A new id's live or persisted
+   * header cwd must resolve to an existing directory equal to {@link path};
+   * unknown ids, missing or invalid cwd values, and mismatches reject without
+   * writing.
+   * @param sessionId - The session to record.
+   * @returns resolution after durability.
+   */
+  attachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Move an accounted session within the manual order, DOM-insertBefore-like:
+   * with an anchor the session lands before it, without one it appends to the
+   * end. Only the moved id changes position. A session or anchor absent from
+   * the account rejects without writing; a move to the current position
+   * resolves without writing (decided on the domain write chain).
+   * @param sessionId - The accounted session to move.
+   * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
+   * @returns resolution after durability.
+   */
+  insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>
+
+  /**
+   * Remove a session from this workspace's account. Idempotent: an id not on
+   * the account resolves without writing (decided on the domain write chain,
+   * like attach). Never touches the session's own stored log.
+   * @param sessionId - The session to remove.
+   * @returns resolution after durability.
+   */
+  detachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Live directory check, uncached: whether {@link path} currently exists and
+   * is a directory. A missing directory never mutates the record — the
+   * directory may only be temporarily moved.
+   * @returns `'ok'` when the directory exists, `'missing-dir'` otherwise.
+   */
+  status(): Promise<'ok' | 'missing-dir'>
+}
+```
+
+Ownership truth is the record's ordered `sessionIds`, never derived from session cwd — but membership requires both: an id on the account and a header whose canonical cwd equals the workspace path, so one session structurally belongs to at most one workspace. Failed writes reject (`insertSessionBefore` account errors as `WorkspaceMoveInvalidError`, storage failures as plain errors); every accepted mutation stamps `updatedAt` and durably prunes candidates that no longer pass the membership check.
+
+## The registry: `ctx.workspace`
+
+`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup completes exactly the marked mutation, and an unmarked order/table mismatch fails loud as corruption.
+
+Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
+
+## Consumers
+
+[dsh-host-apiproxy](../../packages/host/apiproxy) is the product consumer: it serves workspace CRUD to GUI clients over `ctx.workspace` and performs the create-session-then-attach flow above. [dsh-workspace-context](../../packages/context/workspace-context) is **not** a consumer despite the name: it discovers AGENTS.md-style instruction files under an agent's own cwd and never touches `ctx.workspace` — the shared word refers to the user's working directory, not to this registry's entities.
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index edf653c3f4..30ef60e8fe 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -152,11 +152,11 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
 
   it('accepts linked, foundation, generic-parameter, and explicitly exempt signature types', () => {
     const events = collectEvents(make(
-      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata outside the core catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
+      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param assembly - assembly result documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, assembly: PromptAssembly, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
     expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
-    expect(renderEvents(events)).not.toContain('[PresetSpec]')
+    expect(renderEvents(events)).not.toContain('[PromptAssembly]')
   })
 
   it('aggregates every unclassified signature type with its source and remediation', () => {
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index d9f3803547..b710bebe76 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,25 +1,32 @@
 /**
- * Generate committed Cordis artifacts from the Typert catalog projector and
- * the independent vendored-core projector.
+ * Generate the Cordis event and service catalogs from static declarations.
+ * The walk enforces event modes, JSDoc parameter/return completeness, and
+ * signature type-link coverage; inherited Cordis services come from the
+ * curated table below. `--check` verifies both committed artifacts.
  */
 
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
-import {
-  projectCordisCatalog,
-  renderEvents,
-  renderServices,
-} from '@deepseek-ai/dsh-typert-generator'
-import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
+import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve, sep } from 'node:path'
+import ts from 'typescript'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
+import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
+import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
-const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** One primary subsystems page per project type used by a generated signature. */
-export const LINK_MAP: Readonly<Record<string, string>> = {
+/** The fenced-block info string for generated signature blocks (skipped by
+ * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
+const FENCE = 'ts cordis-catalog'
+
+/**
+ * One primary subsystems page per project type used by a generated
+ * signature. This stays curated because union names intentionally do not
+ * reuse the type-equivalence manifest's map-symbol entries and some symbols
+ * appear on more than one page.
+ */
+export const LINK_MAP: Record<string, string> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
@@ -28,6 +35,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  InboxPlacement: 'core.md',
   MessageId: 'core.md',
   HookContext: 'core.md',
   SettleReason: 'core.md',
@@ -49,7 +57,9 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
+  PromptDecision: 'core.md',
   RequestErrorAction: 'core.md',
+  RequestError: 'core.md',
   RequestFailureContext: 'core.md',
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
@@ -106,7 +116,6 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PreparedLlmCall: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
   StreamChunk: 'llm-streaming.md',
-  SkillProviderControl: 'skills.md',
   CreateSessionOptions: 'persistence.md',
   PrepareSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
@@ -159,11 +168,9 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SessionTitleObservationResult: 'session-query.md',
   SessionTitleProvider: 'session-title.md',
   SessionTitleSnapshot: 'session-title.md',
-  SkillCatalogSnapshot: 'skills.md',
   SkillDefinition: 'skills.md',
   SkillLookupOptions: 'skills.md',
   SkillProvider: 'skills.md',
-  SkillProviderObservation: 'skills.md',
   SkillRegistration: 'skills.md',
   SkillSummary: 'skills.md',
   SaveTextSpill: 'spill.md',
@@ -232,15 +239,27 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   WorkflowRun: 'workflow.md',
   WorkflowRunInfo: 'workflow.md',
   WorkflowStartRequest: 'workflow.md',
+  PresetOption: 'permission.md',
+  PresetSpec: 'permission.md',
+  InvariantInstaller: 'invariants.md',
+  WebRoute: 'http-server.md',
+  StorageBackend: 'storage.md',
+  StorageForms: 'storage.md',
+  Domain: 'storage.md',
+  DomainSpec: 'storage.md',
+  DomainChanged: 'storage.md',
+  DomainFacility: 'storage.md',
+  Workspace: 'workspace.md',
+  WorkspaceId: 'workspace.md',
+  WebBootGraph: 'client-modules.md',
 }
 
-/** TypeScript lib and pinned framework types with no repository-owned data page. */
-export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
+/** TypeScript lib and pinned framework types that have no repository-owned data page. */
+const FOUNDATION_TYPE_NAMES = new Set([
   'AbortSignal',
   'AsyncIterable',
   'Context',
   'Error',
-  'Map',
   'Partial',
   'Pick',
   'Promise',
@@ -248,8 +267,8 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'Readonly',
 ])
 
-/** Project types deliberately documented outside the core-data catalog. */
-export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+/** Project types deliberately documented outside the subsystems catalog. */
+const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
@@ -261,15 +280,8 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
-  DirectoryPickerCapability: 'picker interaction contract is owned by packages/host/directory-picker/README.md',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
-  Domain: 'domain interface is owned by packages/storage/storage-domain/README.md',
-  DomainChanged: 'event-local snapshot is owned by packages/storage/storage-domain/src/events.ts',
-  DomainFacility: 'domain form facility is owned by packages/storage/storage-domain/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
-  DomainSpec: 'domain declaration contract is owned by packages/storage/storage-domain/README.md',
-  StorageBackend: 'backend contract is owned by packages/storage/storage/src/backend.ts',
-  StorageForms: 'merge-extensible form map is owned by packages/storage/storage/src/index.ts',
   ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
   SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session/session-projection/src/types.ts',
   ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
@@ -285,18 +297,13 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
   'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
-  InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
   LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
-  WebBootGraph: 'web boot graph wire shape is owned by packages/client/modules/src/client/index.ts',
-  WebRoute: 'route registration contract is owned by packages/host/webserver/src/index.ts',
-  WebUpgradeRoute:
-    'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
+  WebUpgradeRoute:
+    'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
   InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
-  PresetOption: 'deployment menu metadata is owned by packages/interaction/permission/README.md',
-  PresetSpec: 'deployment preset composition is owned by packages/interaction/permission/README.md',
   KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
@@ -309,56 +316,403 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
-  Workspace: 'workspace entity contract is owned by packages/workspace/workspace/README.md',
-  WorkspaceId: 'branded id is owned by packages/workspace/workspace/README.md',
 }
 
-/** Repository data policy consumed by the Cordis catalog projector. */
-export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
-  linkedTypePages: LINK_MAP,
-  foundationTypeNames: FOUNDATION_TYPE_NAMES,
-  typeLinkExemptions: TYPE_LINK_EXEMPTIONS,
-  inheritedEvents: [
-    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
-    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
-    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
-    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
-    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
-    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
-    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
-    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
-    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
-    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:22' },
-    { name: 'hmr/config-update-failed', summary: 'A watched config-file refresh failed.', source: 'vendor/hmr/src/index.ts:29' },
-    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
-    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
-    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
-    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
-    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
-  ],
-  inheritedServices: [
-    { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
-    { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
-    { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
-    { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
-    { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
-    { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
-    { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
-    { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
-    { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
-  ],
+/** Collect named references from parameter, generic-constraint/default, and return types. */
+function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
+  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
+  const referenced = new Set<string>()
+  const visit = (node: ts.Node): void => {
+    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
+    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
+    ts.forEachChild(node, visit)
+  }
+  for (const parameter of member.typeParameters ?? []) {
+    if (parameter.constraint) visit(parameter.constraint)
+    if (parameter.default) visit(parameter.default)
+  }
+  for (const parameter of member.parameters) {
+    if (parameter.type) visit(parameter.type)
+  }
+  if (member.type) visit(member.type)
+  return [...referenced].filter(name => !declared.has(name)).sort()
 }
 
-/** CLI entry: default writes every artifact; `--check` reports stale files.
- * @returns nothing; writes files or reports freshness through the process.
+/** Append fail-closed signature type-link violations with actionable ownership choices. */
+function checkTypeLinks(
+  where: string,
+  member: ts.MethodSignature | ts.MethodDeclaration,
+  sf: ts.SourceFile,
+  violations: string[],
+): void {
+  for (const name of signatureTypeNames(member, sf)) {
+    if (Object.hasOwn(LINK_MAP, name)
+      || FOUNDATION_TYPE_NAMES.has(name)
+      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
+    violations.push(
+      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its subsystems page, `
+      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
+      + 'the non-catalog documentation owner.',
+    )
+  }
+}
+
+/** Throw one aggregated diagnostic for every unclassified signature type. */
+function reportTypeLinkViolations(gate: string, violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
+    + violations.map(violation => `  ${violation}`).join('\n'),
+  )
+}
+
+/** One harness event, extracted from an `interface Events` block. */
+interface EventEntry {
+  /** Scoped name, e.g. `agent/request`. */
+  name: string
+  /** The scope prefix, e.g. `agent` (everything before the first `/`). */
+  scope: string
+  /** Full signature text (the method-signature member, JSDoc stripped). */
+  signature: string
+  /** Original declaration JSDoc, dedented from its containing interface. */
+  jsDoc: string
+  /** Dispatch mode from the `@mode` tag. */
+  mode: Mode
+  /** Description prose (JSDoc minus the `@mode` tag), one line per paragraph. */
+  doc: string
+  /** Source pointer `packages/…/file.ts:line` of the declaration. */
+  source: string
+}
+
+/** One public service method and the source contract attached to it. */
+interface ServiceMethodEntry {
+  /** Public method signature (body stripped). */
+  signature: string
+  /** Original method JSDoc, dedented from its containing class. */
+  jsDoc: string
+}
+
+/** One harness service, extracted from an `interface Context` block. */
+interface ServiceEntry {
+  /** The `ctx.<key>` name, e.g. `llm`. */
+  key: string
+  /** The service class/interface name, e.g. `LlmService`. */
+  type: string
+  /** Whether the service class is abstract (a seam interface). */
+  abstract: boolean
+  /** Class-level JSDoc prose, one line per paragraph. */
+  doc: string
+  /** Public methods (bodies stripped), in source order. */
+  methods: ServiceMethodEntry[]
+  /** Source pointer of the class declaration. */
+  source: string
+}
+
+/** A terse inherited-tier entry (pinned vendor surface). */
+interface InheritedEntry {
+  name: string
+  summary: string
+  /** Source pointer `vendor/…:line`. */
+  source: string
+}
+
+// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts.
+
+/** The signature text of a method-signature member (everything but a body). */
+function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
+  const full = member.getText(sf)
+  const body = (member as { body?: ts.Node }).body
+  const sig = body ? full.slice(0, full.length - body.getText(sf).length) : full
+  return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Copy a node's original JSDoc while removing only the indentation imposed by
+ * its containing interface or class.
  */
-export function main(): void {
-  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
+function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  if (!raw) return ''
+  const start = text.lastIndexOf(raw, node.getStart(sf))
+  const { line } = sf.getLineAndCharacterOfPosition(start)
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, start)
+  return raw.split('\n')
+    .map((lineText, index) => index > 0 && lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
+    .join('\n')
+}
+
+/** Walk every harness `interface Events` block and extract its events, hard-
+ * erroring (aggregated) on any JSDoc-completeness violation: a missing/
+ * contradicted `@mode`, missing description prose, or an undocumented payload
+ * parameter. `scanRoot` defaults to the repo root; tests pass a fixture dir. */
+export function collectEvents(scanRoot: string = root): EventEntry[] {
+  const entries: EventEntry[] = []
+  const violations: string[] = []
+  const typeLinkViolations: string[] = []
+  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!text.includes('interface Events')) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    for (const { name, member } of eventMembers(body, sf)) {
+      const signature = memberSignature(member, sf)
+      const raw = rawJsDoc(text, member)
+      const { doc, mode } = parseJsDoc(raw)
+      const src = pointer(rel, sf, member)
+      const where = `event '${name}' (${src})`
+      checkTypeLinks(where, member, sf, typeLinkViolations)
+      if (!mode) {
+        violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial|bail' to its JSDoc (see AGENTS.md).`)
+      }
+      // Conclusive structural check: a trailing `next: () => …` parameter is a
+      // waterfall. (emit vs parallel vs serial is not structurally
+      // distinguishable, so it is trusted from the tag.)
+      const last = member.parameters.at(-1)
+      const hasNext = !!last && last.name.getText(sf) === 'next'
+      if (mode && hasNext && mode !== 'waterfall') {
+        violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
+      }
+      if (mode && !hasNext && mode === 'waterfall') {
+        violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
+      }
+      if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
+      // Payload parameters need a non-empty @param. The `this` receiver is not
+      // payload, and a waterfall's trailing `next` is covered by its mode.
+      const { params } = parseTags(raw)
+      checkParams(where, 'event', member.parameters, params, sf,
+        p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
+      if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, jsDoc: jsDocText(text, sf, member), mode, doc, source: src })
+    }
+  }
+  reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
+  return entries
+}
+
+/** Walk every harness `interface Context` block + its service class, hard-
+ * erroring (aggregated) on any JSDoc-completeness violation: a class or public
+ * method without JSDoc prose, an undocumented parameter, a stale `@param`, a
+ * missing `@returns` on a non-void method, or an inferred (unannotated) return
+ * type the pure-AST walk cannot classify.
+ * `scanRoot` defaults to the repo root; tests pass a fixture dir. */
+export function collectServices(scanRoot: string = root): ServiceEntry[] {
+  const entries: ServiceEntry[] = []
+  const violations: string[] = []
+  const typeLinkViolations: string[] = []
+  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!text.includes('interface Context')) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    // Resolve each ctx key to its service class (shared walk) and emit an entry.
+    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
+      const methods: ServiceMethodEntry[] = []
+      for (const member of cls.members) {
+        if (!ts.isMethodDeclaration(member)) continue
+        // Only instance methods callable through `ctx.<key>` are surface;
+        // private, protected, and static methods are not.
+        const nonPublic = member.modifiers?.some(m =>
+          m.kind === ts.SyntaxKind.PrivateKeyword
+          || m.kind === ts.SyntaxKind.ProtectedKeyword
+          || m.kind === ts.SyntaxKind.StaticKeyword)
+          || ts.isPrivateIdentifier(member.name)
+        if (nonPublic) continue
+        const memberName = member.name.getText(sf)
+        if (memberName.startsWith('[')) continue // computed/symbol members
+        const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
+        checkTypeLinks(where, member, sf, typeLinkViolations)
+        const raw = rawJsDoc(text, member)
+        methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
+        if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
+        if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
+        const { params, returns } = parseTags(raw)
+        // Every parameter needs a non-empty @param (`this` receiver exempt),
+        // and a non-void ANNOTATED result needs a non-empty @returns — the
+        // shared checkers carry the exact contract.
+        checkParams(where, 'service', member.parameters, params, sf,
+          p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
+        checkReturns(where, member.type, returns, sf, violations)
+      }
+      entries.push({
+        key,
+        type,
+        abstract,
+        doc: clsDoc,
+        methods,
+        source: pointer(rel, sf, cls),
+      })
+    }
+  }
+  reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
+  return entries.sort((a, b) => a.key.localeCompare(b.key))
+}
+
+/**
+ * The inherited tier — cordis core + loader/hmr/timer. Curated, terse, and
+ * hand-summarized because (a) it is pinned vendor source that changes only on a
+ * deliberate vendor sync, (b) the cordis-core `Context` mixes true ctx members
+ * with non-service fields (`root`, `baseUrl`, `logger`) that a blind walk would
+ * wrongly surface as services, and (c) the internal/* events carry no JSDoc to
+ * render. Source pointers are verified against vendor by `verify-md-links`'
+ * sibling check is N/A; keep them current on a vendor bump.
+ */
+const INHERITED_EVENTS: InheritedEntry[] = [
+  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
+  { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
+  { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+  { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
+  { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
+  { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
+  { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
+  { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+]
+
+export const INHERITED_SERVICES: InheritedEntry[] = [
+  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
+  { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
+  { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
+  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
+  { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
+  { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
+  { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
+  { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
+]
+
+/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
+function typeLinks(signature: string): string {
+  const seen = new Set<string>()
+  for (const name of Object.keys(LINK_MAP)) {
+    if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
+  }
+  if (seen.size === 0) return ''
+  const links = [...seen].sort().map(n => `[${n}](../subsystems/${LINK_MAP[n]})`)
+  return `Types: ${links.join(' · ')}`
+}
+
+/** Render one harness event entry. */
+function renderEvent(e: EventEntry): string[] {
+  const out = [`### \`${e.name}\` — ${e.mode}`, '']
+  if (e.doc) out.push(e.doc, '')
+  out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
+  const links = typeLinks(e.signature)
+  if (links) out.push(links, '')
+  out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
+  return out
+}
+
+/** Render one harness service entry. */
+function renderService(s: ServiceEntry): string[] {
+  const kind = s.abstract ? ' (abstract seam)' : ''
+  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  if (s.doc) out.push(s.doc, '')
+  if (s.methods.length) {
+    const declarations = s.methods.flatMap((method, index) => [
+      ...(index > 0 ? [''] : []),
+      method.jsDoc,
+      method.signature,
+    ])
+    out.push('```' + FENCE, ...declarations, '```', '')
+    const links = typeLinks(s.methods.map(method => method.signature).join('\n'))
+    if (links) out.push(links, '')
+  }
+  out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
+  return out
+}
+
+/** The shared generated-file banner comment. */
+const BANNER = [
+  '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
+  '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
+  '',
+]
+
+/** The shared GENERATED + freshness-gate + fence notice paragraph. */
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
+
+/** Render the events catalog (pure, deterministic given sorted inputs). */
+export function renderEvents(events: EventEntry[]): string {
+  const lines: string[] = [
+    ...BANNER,
+    '# Cordis Events Catalog',
+    '',
+    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
+    '',
+    GATE_NOTICE,
+    '',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
+    '',
+    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`), **bail** (synchronous in-order dispatch until one listener returns a bail value; the scoped input-mutation events use it for an applied/not-applied answer).',
+    '',
+  ]
+  const scopes = [...new Set(events.map(e => e.scope))].sort()
+  for (const scope of scopes) {
+    lines.push(`## \`${scope}/*\``, '')
+    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
+      lines.push(...renderEvent(e))
+    }
+  }
+  lines.push(
+    '## Inherited events (cordis core + loader/hmr/timer)',
+    '',
+    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
+    '',
+  )
+  for (const e of INHERITED_EVENTS) {
+    lines.push(`- \`${e.name}\` — ${e.summary} ([\`${e.source}\`](../../${e.source.split(':')[0]}))`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/** Render the services catalog (pure, deterministic given sorted inputs). */
+export function renderServices(services: ServiceEntry[]): string {
+  const lines: string[] = [
+    ...BANNER,
+    '# Cordis Services Catalog',
+    '',
+    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
+    '',
+    GATE_NOTICE,
+    '',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
+    '',
+  ]
+  for (const s of services) lines.push(...renderService(s))
+  lines.push(
+    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
+    '',
+    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
+    '',
+  )
+  for (const s of INHERITED_SERVICES) {
+    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/** CLI entry: `--write` (default) writes both catalogs, `--check` fails if
+ * either is stale. Guarded behind an entry-point check so importing this module
+ * for tests neither regenerates the committed files nor calls process.exit. */
+function main(): void {
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
-    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
-    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
+    [OUT_EVENTS, renderEvents(collectEvents())],
+    [OUT_SERVICES, renderServices(collectServices())],
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -368,7 +722,9 @@ export function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT is expected; either read failure has the same remedy.
+        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+        // file is not a state this repo produces. Either way the remedy is the
+        // same — regenerate — so treat a read failure as "stale".
         committed = null
       }
       if (committed !== content) stale.push(out)
@@ -389,4 +745,7 @@ export function main(): void {
   console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
 }
 
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
+// Run only when invoked as a script, not when imported by a test.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 56c1b094be..b53ff60989 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1564,6 +1564,129 @@
       "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "PresetSpec",
+      "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "Config",
+      "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "PresetOption",
+      "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/plan.md",
+      "symbol": "PlanModeConfig",
+      "source": "packages/plan/plan-mode/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/invariants.md",
+      "symbol": "Config",
+      "source": "packages/support/invariants/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/invariants.md",
+      "symbol": "InvariantFailure",
+      "source": "packages/support/invariants/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/invariants.md",
+      "symbol": "InvariantInstaller",
+      "source": "packages/support/invariants/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/http-server.md",
+      "symbol": "WebRouteKind",
+      "source": "packages/host/webserver/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/http-server.md",
+      "symbol": "WebRoute",
+      "source": "packages/host/webserver/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/http-server.md",
+      "symbol": "Config",
+      "source": "packages/host/webserver/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "StorageForms",
+      "source": "packages/storage/storage/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "StorageBackend",
+      "source": "packages/storage/storage/src/backend.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "DomainSpec",
+      "source": "packages/storage/storage-domain/src/spec.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "Domain",
+      "source": "packages/storage/storage-domain/src/domain.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "DomainChangedBase",
+      "source": "packages/storage/storage-domain/src/events.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "DomainChanged",
+      "source": "packages/storage/storage-domain/src/events.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayRequest",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayHost",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlaySession",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayCloseReason",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayOutcome",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/workspace.md",
+      "symbol": "WorkspaceId",
+      "source": "packages/workspace/workspace/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/workspace.md",
+      "symbol": "Workspace",
+      "source": "packages/workspace/workspace/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/client-modules.md",
+      "symbol": "WebBootEntry",
+      "source": "packages/client/modules/src/client/manifest.ts"
+    },
+    {
+      "doc": "docs/subsystems/client-modules.md",
+      "symbol": "WebBootGraph",
+      "source": "packages/client/modules/src/client/manifest.ts"
     }
   ]
 }

From 3f9c58855b0c11e6edf0385d49f8cf1cf491edf3 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 23:29:15 +0800
Subject: [PATCH 157/262] docs: telemetry subsystem page and Chinese
 counterparts for the nine new pages

telemetry.md joins the eight pages after the OTel telemetry seam landed
on master (ctx.telemetry + telemetry/record were the one service and
event scope still without a page). All nine pages gain zh counterparts
translated whole-document per dsh-translate-docs; the eleven touched
pairs (nine new + core + the subsystems-catalog note) are recorded;
TelemetryRecord moves from TYPE_LINK_EXEMPTIONS to LINK_MAP and the
catalogs are regenerated.
---
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   2 +-
 ...6-06-20-core-data-structures-catalog.zh.md |   2 +-
 docs/subsystems/client-modules.i18n.yaml      |   6 +
 docs/subsystems/client-modules.zh.md          |  63 ++++++++
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |   1 +
 docs/subsystems/core.zh.md                    |   1 +
 docs/subsystems/http-server.i18n.yaml         |   6 +
 docs/subsystems/http-server.zh.md             |  49 ++++++
 docs/subsystems/invariants.i18n.yaml          |   6 +
 docs/subsystems/invariants.zh.md              |  59 +++++++
 docs/subsystems/permission.i18n.yaml          |   6 +
 docs/subsystems/permission.zh.md              |  63 ++++++++
 docs/subsystems/plan.i18n.yaml                |   6 +
 docs/subsystems/plan.zh.md                    |  39 +++++
 docs/subsystems/storage.i18n.yaml             |   6 +
 docs/subsystems/storage.zh.md                 | 125 +++++++++++++++
 docs/subsystems/telemetry.i18n.yaml           |   6 +
 docs/subsystems/telemetry.md                  | 109 +++++++++++++
 docs/subsystems/telemetry.zh.md               | 109 +++++++++++++
 docs/subsystems/workspace.i18n.yaml           |   6 +
 docs/subsystems/workspace.zh.md               | 121 ++++++++++++++
 scripts/gen-cordis-catalog.ts                 |   2 +-
 scripts/type-equiv.manifest.json              | 149 +++++++++---------
 25 files changed, 872 insertions(+), 78 deletions(-)
 create mode 100644 docs/subsystems/client-modules.i18n.yaml
 create mode 100644 docs/subsystems/client-modules.zh.md
 create mode 100644 docs/subsystems/http-server.i18n.yaml
 create mode 100644 docs/subsystems/http-server.zh.md
 create mode 100644 docs/subsystems/invariants.i18n.yaml
 create mode 100644 docs/subsystems/invariants.zh.md
 create mode 100644 docs/subsystems/permission.i18n.yaml
 create mode 100644 docs/subsystems/permission.zh.md
 create mode 100644 docs/subsystems/plan.i18n.yaml
 create mode 100644 docs/subsystems/plan.zh.md
 create mode 100644 docs/subsystems/storage.i18n.yaml
 create mode 100644 docs/subsystems/storage.zh.md
 create mode 100644 docs/subsystems/telemetry.i18n.yaml
 create mode 100644 docs/subsystems/telemetry.md
 create mode 100644 docs/subsystems/telemetry.zh.md
 create mode 100644 docs/subsystems/workspace.i18n.yaml
 create mode 100644 docs/subsystems/workspace.zh.md

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 13c54fa458..5bc51a4e7d 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 57433fdcb3c77976c4ba0cfe7d157f94dff331dd
-2026-06-20-core-data-structures-catalog.zh.md: 3956839c8211e294280805d9b6993e5607bfe04f
+2026-06-20-core-data-structures-catalog.md: 718045bf7ce511a0b766e69e64ef7657eb221189
+2026-06-20-core-data-structures-catalog.zh.md: 1e8473a373c212fa08b171719edd5803e5aa3b05
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 025cbd7ab7..718045bf7c 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -58,4 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the eight `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the nine `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules, telemetry) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index de644e8567..1e8473a373 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -58,4 +58,4 @@ Status: implemented
 - 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
-- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的八个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
+- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的九个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块、遥测）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
new file mode 100644
index 0000000000..a9a68fd065
--- /dev/null
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
+client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
+client-modules.zh.md: bbcdb04cdce8a0d5256d2490deb238812e9a47fc
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
new file mode 100644
index 0000000000..bbcdb04cdc
--- /dev/null
+++ b/docs/subsystems/client-modules.zh.md
@@ -0,0 +1,63 @@
+# Client 模块
+
+[English](client-modules.md) | 中文
+
+Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 模块系统的 Node 半，以 `ctx.clientModuleHost`（`ClientModuleHostService`）形式提供。它扫描宿主 Loader 的 entry 找出 `dshClient` 包（package），组合出 `window.__DSH_BOOT__` entry 图，在 `/plugins/<id>/client.js` 提供各个 bundle，并经 index 转换（index tap）注入启动 manifest（元数据清单）——这是同一个服务的四个面。它是 Web GUI 栈的一项可选能力，不属于 agent loop（智能体循环）主干，并且是 [dsh-host-webserver](../../packages/host/webserver) 的消费方：[http-server.md](http-server.md) 所述的载体提供本服务注册的前缀路由与 index 转换。同一个包的浏览器半（`ctx.modules`，即拉取并物化这些 bundle 的 lazy CJS 模块表）属于内核机件，记录在[包 README](../../packages/client/modules/README.md)中，不在本页。
+
+源码：[`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
+
+## wire
+
+图是 Node 半与浏览器半之间的线上单源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
+
+```ts type-equiv
+/**
+ * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's dshClient
+ * declaration and reach fibers through entry creation).
+ */
+interface WebBootEntry {
+  /** Entry name == package name. */
+  id: string
+  /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+  url: string
+  /** Bundle content hash (cache-busting consistency anchor). */
+  rev: string
+  /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+  inject?: string[]
+  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  immediately?: boolean
+}
+```
+
+```ts type-equiv
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
+interface WebBootGraph {
+  /** Consistency anchor over the whole graph (content + bundle hashes). */
+  rev: string
+  /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
+  entries: WebBootEntry[]
+}
+```
+
+每一行的 `rev` 是该 bundle 的内容哈希，并作为使缓存失效的查询参数附在 URL 上；图的 `rev` 对组合后的各行做哈希，因此任何一行的变化都会改变它。`immediately` 标记第一阶段预取档位（在模块面启动期间 fetch 并执行，只做工厂登记）；惰性行在首次 import 时才拉取。
+
+## 扫描
+
+包加入这张表的方式，是在自己的 package.json 中声明 `dshClient`（`platform: 'web'`、可选的 `inject` 边、可选的 `immediately`），并在 `exports["./client"]` 导出构建好的 bundle。包解析锚定在配置树的 `ctx.baseUrl`——即 cordis.yml 所在目录，该目录的包把每个被组合的插件声明为依赖——这一锚点未设置时，构造即抛错。
+
+扫描是单包增量的；不存在全量重扫代码路径。每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
+
+包元数据——包括「非 client 包」这一否定结论——按名缓存且永不过期：插件集合的变更在重启后生效。fiber 重启原样复用其行与 rev；bundle 内容变更只经 `rebuilt()` 到达图。
+
+## 路由
+
+`GET`/`HEAD /plugins/<id>/client.js` 以 `no-cache` 从磁盘提供已注册的 bundle（锚定一致性的是 rev 查询参数，而非 HTTP 缓存）；其他方法返回 405。未知 id——或已注册、但 bundle 因尚未构建而不可读的行——回应一个大声的 404，而不是让载体的 SPA 回退把 HTML 当作 JavaScript 发出。index 转换在每次 index 渲染时注入当前图，因此刷新页面总是针对实时组合启动。
+
+## 服务
+
+`ClientModuleHostService`（`ctx.clientModuleHost`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回该 bundle 的绝对路径。`rebuilt(id)` 是 bundle 内容到达图的唯一入口：它对文件重新哈希，只有 rev 真正变化才会重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 rev；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 rev 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
+
+开发环境下，[dsh-client-hmr](../../packages/client/hmr/README.md) 是注册表的监视驱动：它的 Node 半从同步取得的基线出发，对图中每一行的 bundle 做 stat 轮询，变化时调用 `rebuilt(id)`，经 `onGraphChanged` 重新同步监视集合，并通过 SSE（Server-Sent Events）把 rev 变化广播给浏览器半。生产环境的图完全不含 HMR（热模块替换）行；模块宿主自身从不监视文件。
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 3057ee36ee..d0188cb2f3 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 8f413a7a064ad6f63e0caec31354869e51139020
-core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5
+core.md: 1d0bf6c61500817860dfdd452bddc25adbbeffcc
+core.zh.md: 06fd3b5a48d5267c9856c20589772047b6105b2c
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index bde64a39e4..1d0bf6c615 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -54,6 +54,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
+| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
 
 > Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 1f21785cad..06fd3b5a48 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -54,6 +54,7 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
 
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
new file mode 100644
index 0000000000..cb2c734255
--- /dev/null
+++ b/docs/subsystems/http-server.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 docs/subsystems/http-server.md
+http-server.md: 565df72f2720a1211f50650d4b1bc8d6df4a007a
+http-server.zh.md: 93b056648f044f6c79b85a6069deb3123f9a7a3e
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
new file mode 100644
index 0000000000..fc5e18414b
--- /dev/null
+++ b/docs/subsystems/http-server.zh.md
@@ -0,0 +1,49 @@
+# HTTP 服务器
+
+[English](http-server.md) | 中文
+
+[dsh-host-webserver](../../packages/host/webserver) 是 GUI 宿主 web 形态的 HTTP 载体：单个提供 `ctx.httpServer` 的 `node:http` 插件，由具名路由注册表加 index.html 转换挂点组成，兜底是静态 dist 回退。它不属于 agent loop（智能体循环）主干，也不是能力 seam：它不了解任何 harness 概念，每个功能表面（`/api` 桥接、插件 bundle、HMR（热模块替换）事件流）都是由其他插件注册的一条路由（[分层说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)）。仅限 web（浏览器）形态：Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，不经过本服务器。
+
+源码：[`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
+
+## 路由
+
+```ts type-equiv
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+type WebRouteKind = 'exact' | 'prefix'
+```
+
+```ts type-equiv
+/** One named route registration. */
+interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+```
+
+匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退保持锁定语义：非 GET/HEAD 返回 405，越出 dist 根目录的路径穿越返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 交付（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
+
+## 配置
+
+```ts type-equiv
+/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
+  distIndex: string
+}
+```
+
+`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（刻意的网络暴露）；没有 TLS、认证或 origin 策略，因此绑定到非回环地址会把服务器暴露给该网络。`distIndex` 是组合应用解析后注入的组装事实。
+
+## 服务
+
+`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动阶段的大声失败巡检报告。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层面的契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
+
+处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能保持响应打开（如 SSE（Server-Sent Events）），而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
new file mode 100644
index 0000000000..dc5a8a6d0d
--- /dev/null
+++ b/docs/subsystems/invariants.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 docs/subsystems/invariants.md
+invariants.md: 143a7feabbab18556f595a78c7aef17caa6d3028
+invariants.zh.md: ab7aa0221101400d552ff47e1cfa3275d99a0b6d
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
new file mode 100644
index 0000000000..ab7aa02211
--- /dev/null
+++ b/docs/subsystems/invariants.zh.md
@@ -0,0 +1,59 @@
+# 运行时不变式
+
+[English](invariants.md) | 中文
+
+[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 伴随插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
+
+源码：[`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
+
+## 选择
+
+```ts type-equiv
+/** Runtime invariant selection configured on the service plugin. */
+interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
+}
+```
+
+一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时大声失败：空白、带空白填充、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/support/invariants/README.md)）。
+
+## 安装器
+
+```ts type-equiv
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+type InvariantFailure = (message: string) => never
+```
+
+```ts type-equiv
+/** Install one package's checks into the registration's child context. */
+interface InvariantInstaller {
+  /**
+   * Install the package contribution.
+   * @param ctx - child context owned by this invariant registration.
+   * @param fail - reporter bound to the registering package name.
+   * @returns nothing, or a promise settling after asynchronous checks finish.
+   */
+  (ctx: Context, fail: InvariantFailure): void | Promise<void>
+  /** Services the child installer fiber may access. */
+  readonly inject?: Inject
+}
+```
+
+被启用的安装器在专属的子 Cordis fiber 中运行；`installer.inject` 声明该 fiber 可以访问的服务，注册成功之前会先等待安装器同步或异步地执行完毕。`fail(message)` 抛出 `InvariantError`（`extends Error`，带稳定的 `code: 'INVARIANT'`、所属 `packageName`，以及前缀为 `invariant violated by "<package>": …` 的消息），因此违规可归因，而注册表无需导入任何产品包。
+
+## 服务
+
+`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于伴随插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此伴随插件可以重载并再次注册同一名称，不留残余状态。
+
+## 伴随插件契约
+
+每个工作区包都拥有一个 `./invariant` 伴随插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但断言刻意不为凑数而虚构。只有当包对某个可观察事件或可变数据拥有所有权关系时，伴随插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行伴随插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
new file mode 100644
index 0000000000..f800d4ff08
--- /dev/null
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
+permission.md: 49dd51ff86d0dbce26fca0ed21527f71bb144dec
+permission.zh.md: 5fb93e9f923582e6c530bac4a22e2ce62cff156d
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
new file mode 100644
index 0000000000..5fb93e9f92
--- /dev/null
+++ b/docs/subsystems/permission.zh.md
@@ -0,0 +1,63 @@
+# 权限预设
+
+[English](permission.md) | 中文
+
+[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮，即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
+
+源码：[`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+
+## 预设表
+
+预设是一个表键，映射到一组沙箱／审批组合，外加可选的客户端展示信息；默认预设表自带 `workspace-write`（`workspace-write` + `ask`）和 `danger-full-access`（`danger-full-access` + `never`）。
+
+```ts type-equiv
+/** One preset's sandbox/approval bundle and optional client presentation. */
+interface PresetSpec {
+  /** The `sandbox/mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** The {@link PermissionService} config: the deployment's preset table. */
+interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `workspace-write`
+   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
+   * never). The name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+}
+```
+
+该服务要求一个施加沙箱隔离的 `ctx.bash` 执行器和 `ctx.approval`，配置错误在插件加载时即失败：名为 `custom` 的表项会抛出异常（该名称保留给派生的「非预设」状态）；在不施加隔离的 bash 执行器（没有 `sandboxMode` 能力事实）之上组合同样抛出异常，因为预设捆绑了一个沙箱模式。
+
+## 当前预设与派生的 `custom`
+
+`current(events)` 从旋钮派生实际生效的预设，而不是只看自身事件：它折叠会话的生效沙箱模式（回退到执行器配置的模式）与生效审批策略（先回退到审批服务配置，再回退到 `ask`），优先取仍然匹配的已记录选择，其次取声明顺序中第一个匹配的表项，否则返回 `CUSTOM_PRESET`（`'custom'`）。`custom` 只是派生值：客户端可以把它显示为当前值，但它绝不是切换目标，也绝不出现在事件 payload 中。
+
+`names` 按预设表声明顺序列出可切换的预设；`optionOf(name)` 为某个表键（label 回退为该键）或 `custom` 构建客户端渲染的选项，传入其他任何名称都会抛出异常。
+
+```ts type-equiv
+/** The select-option shape a presentation layer advertises for one preset (or for the derived `custom` state). */
+interface PresetOption {
+  /** Stable option value: the table key, or `custom`. */
+  value: string
+  /** The display label. */
+  name: string
+  /** One user-facing sentence on what the value means. */
+  description?: string
+}
+```
+
+## 切换与 `permission/preset` 事件
+
+`set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/ui/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
+
+`permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](../cordis-catalog/services.md#ctxpermission--permissionservice)。
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
new file mode 100644
index 0000000000..3ae156615f
--- /dev/null
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
+plan.md: f67e7734ca3fd55c284d3d41227f8241de7b9f5f
+plan.zh.md: 565cf2016636acb6c26d20c731b9e6e374cee1da
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
new file mode 100644
index 0000000000..af21a6d027
--- /dev/null
+++ b/docs/subsystems/plan.zh.md
@@ -0,0 +1,39 @@
+# 计划模式
+
+[English](plan.md) | 中文
+
+计划模式是 [dsh-plan-mode](../../packages/plan/plan-mode) 拥有的、记录到日志的逐 agent（智能体）协作状态（`ctx.planMode`，`PlanModeService`）：激活期间，一段部署持有的指引段落会影响每个模型请求。它是**软性指引**，有意独立于[沙箱模式](sandbox.md)与[审批策略](approval.md)这两条强制执行轴：那些旋钮（knob）从不读写计划状态，需要硬边界的部署另行组合两者。该包（package）是一项可选能力，不属于 agent loop（智能体循环）主干；它的对外表面是 `plan:policy` 提示词段落、始终保持注册的 `exit_plan_mode` 工具和 `/plan` 命令。[设计说明](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)负责决策依据；[包 README](../../packages/plan/plan-mode/README.md) 负责模型体验与限制细节。
+
+源码：[`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
+
+## 已记录状态与恢复
+
+`plan/mode`（`{ active: boolean }`）是仅记日志、整值替换的[会话事件](session.md)：持久且可回放，绝不进入模型 transcript（文本记录）。`foldPlanMode(events, end?)` 返回前缀中最后一条已记录值，没有时返回 `false`：生效状态始终是会话日志的纯折叠，因此恢复、fork 与压缩（compaction）无需实时镜像即可将其复原，UI 通过 `session/event` 观察已提交的切换。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)。
+
+## 待定意图与轮次边界冲刷
+
+由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
+
+服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响该边界紧接其后的那个请求。冲刷失败会被隔离（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+
+## 配置
+
+```ts type-equiv
+/** Deployment-owned plan guidance. */
+interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地什么都不影响。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.md)；未激活的计划模式不贡献任何文本。
+
+## 退出工具与 `/plan` 命令
+
+[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) 在计划模式未激活时仍保持注册，因此跨越边界只改变提示词段落，绝不改变请求的工具目录；在计划模式之外执行会失败。在计划模式中，它要求一份以 `#` 标题开头的完整 markdown 计划，并通过[用户交互 seam](user-interaction.md) 呈交评审。批准返回 `{ approved: true }`，并记录一个静默（不叙述）的待定退出，在该步骤之后冲刷：计划指引在 assistant 本批工具调用的剩余部分继续生效，而工具结果本身叙述这次转换。「继续规划」则是一次携带用户反馈的失败调用，模型据此修订并再次呈交；评审期间交互通道缺失或服务重载同样使调用失败，而不是静默离开计划模式。
+
+当 [`ctx.commands`](commands.md) 被组合时，插件注册 `/plan [off|message]`：单独的 `/plan` 选择计划模式；任何其他非空消息先选择计划模式，再通过 `agent.steer()` 提交该文本，使其在计划指引下成为下一步骤的普通已记录用户消息；确切参数 `off` 选择未激活，这还会在计划模式尚未进入任何请求之前，取消尚未冲刷的待定条目。
+
+## 服务
+
+`ctx.planMode` 拥有已记录的计划状态、边界处的应用与叙述、`plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](../cordis-catalog/services.md#ctxplanmode--planmodeservice)。
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
new file mode 100644
index 0000000000..92387332f0
--- /dev/null
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
+storage.md: 5d54d7337b5ef52e24179758130b9fa8cd196376
+storage.zh.md: c575f989fe4b3536ce3c8d3b3af08ebda418166d
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
new file mode 100644
index 0000000000..c575f989fe
--- /dev/null
+++ b/docs/subsystems/storage.zh.md
@@ -0,0 +1,125 @@
+# 存储
+
+[English](storage.md) | 中文
+
+存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)拆分：枢纽（hub）与后端接口（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、后端实现（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及领域数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端 seam 的唯一消费方，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包（package）绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
+
+源码：[`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
+
+## 枢纽：`ctx.storage`
+
+`Storage`（[签名](../cordis-catalog/services.md#ctxstorage--storage)）是汇合点，不是存储本体。`ctx.storage.backend` 是一张名称 → 后端的表：多个后端并排保持挂载，哪个后端服务哪个消费方由该消费方自己的配置决定（即领域层的路由表），绝不是枢纽全局的选择。`register(name, backend)` 返回 disposer；重复名称与查找未知名称都抛出 `StorageError`。dispose（资源释放）只注销名称——由拥有插件在注销之后自行关闭后端。每个后端插件还会发布一个仅用于生命周期的服务键（`storageBackendServiceKey(name)`），数据形式提供方注入它，使自身激活不会与后端注册发生竞态。
+
+数据形式以一张可合并扩展的键 map 挂载到枢纽上：
+
+```ts type-equiv
+/**
+ * Data forms mountable on the hub, keyed by form name. Form owners extend
+ * this map via declaration merging (the domain layer merges
+ * `domain: DomainFacility`) and mount the facility in their `apply`.
+ */
+interface StorageForms {}
+```
+
+`mount(form, facility)` 是一个 effect，其 disposer 负责卸载；对同一键的第二次挂载抛出 `duplicate-mount`。`form(form)` 解析已挂载的 facility，在拥有插件加载之前抛出 `form-not-mounted`——组合方应据此安排插件顺序，而不是静默推迟。领域层合并 `domain: DomainFacility`，因此 `ctx.storage.domain` 与 `ctx.storageDomain` 是同一个对象。
+
+## 后端 seam
+
+```ts type-equiv
+/**
+ * One registered backend. A backend owns exactly one medium and shares its
+ * lifecycle across all facets; facets are optional members — a backend that
+ * cannot serve a shape simply omits it, and resolution fails loud instead.
+ */
+interface StorageBackend {
+  /** Key-value data shape; absent when this backend cannot serve it. */
+  readonly kv?: KvFacet
+
+  /**
+   * Drain in-flight writes across all open units and release the medium.
+   * Idempotent; concurrent and repeated calls resolve once teardown finishes.
+   * @returns resolution after the medium is released.
+   */
+  close(): Promise<void>
+}
+```
+
+一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性契约，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
+
+## 声明领域
+
+领域由其拥有包声明一次，形式是一个 spec 对象——它是该领域的身份、布局和记录 schema 的单一来源（schema 用 zod 编写，因此 `z.infer` 让消费方类型无需重复声明）：
+
+```ts type-equiv
+/** Static declaration of one domain: identity, version, and record layout. */
+interface DomainSpec {
+  /** Domain name; must match `UNIT_NAME_RE` (doubles as the backend unit name). */
+  readonly name: string
+  /** Domain format version; a medium stamped with a different version rejects at open. */
+  readonly version: number
+  /** Optional global singleton slot. */
+  readonly global?: DomainGlobalSpec<unknown>
+  /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */
+  readonly tables: Record<string, DomainTableSpec>
+}
+```
+
+`defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就大声失败：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable<K, V>(schema)` 声明一张表，其键类型是编译期的幻影类型（通常是[品牌化 id](core.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。
+
+## 打开的领域
+
+```ts type-equiv
+/** One open domain, typed by its spec. */
+interface Domain<S extends DomainSpec> {
+  /** Domain name from the spec. */
+  readonly name: string
+  /** Global singleton handle; a spec without `global` has no usable handle (`never`). */
+  readonly global: DomainGlobalHandleOf<S>
+  /**
+   * Resolve one declared table handle. Handles are stable — repeated calls
+   * return the same instance.
+   * @param name - Declared table name.
+   * @returns the typed table handle.
+   */
+  table<N extends keyof S['tables'] & string>(name: N): KvTable<TableKeyOf<S, N>, TableValueOf<S, N>>
+
+  /**
+   * Close this domain: reject new writes immediately, drain already-queued
+   * writes (their events still emit), release the backend unit, then free
+   * the domain name for a later open. Idempotent — repeated calls share one
+   * teardown. The consumer owns this call (typically as its own `ctx.effect`
+   * disposer); the facility closes any domain left open when it unmounts.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void>
+}
+```
+
+读取是同步的，来自权威的内存态：`KvTable` 暴露 `get`/`entries`/`keys`/`size`（快照迭代器，在排队写入落地期间保持稳定），global 句柄的 `get()` 在第一次 `set` 将槽位物化到介质之前一直返回 spec 的 `initial`。每次写入——`put`、`delete`、`update`、`global.set`——都在同一条逐领域写链上排队，先到达后端持久性，再更新内存，最后发出 `domain/changed`；后端写入被拒时内存原样不动，因此读取绝不会偏离介质。`update(key, fn)` 在其写链槽位上是一次原子的读-改-写（键缺失时拒绝 `missing-key`）；`delete` 一个不存在的键 resolve 为 `false`，不产生写入也不产生事件。返回的记录就是存储的对象本身，不是副本——请经 `put`/`update` 整体替换，绝不要就地修改。
+
+## 领域 facility：`ctx.storageDomain`
+
+`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 逐步执行，任一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找；`closeAll()` 是卸载路径。
+
+## 变更事件：`domain/changed`
+
+每次持久写入都发出一个事件，严格发生在后端确认持久性之后，顺序遵循该领域的写链（[事件条目](../cordis-catalog/events.md#domainchanged--emit)）：
+
+```ts type-equiv
+/** Shared location fields of one durable domain change. */
+interface DomainChangedBase {
+  /** Owning domain name. */
+  readonly domain: string
+  /** Table name; `''` for a global-singleton write. */
+  readonly table: string
+  /** Record key; `''` for a global-singleton write. */
+  readonly key: string
+}
+```
+
+```ts type-equiv
+/** One durable domain change; a closed union — switch on `operation`. */
+type DomainChanged = DomainChangedPut | DomainChangedDeleted
+```
+
+`put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是延后工作，记录在[包 README](../../packages/storage/storage-domain/README.md)中。
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
new file mode 100644
index 0000000000..9f6fdb3af3
--- /dev/null
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
+telemetry.md: 4942a402dacb40ed64070c2b7824bfea7a14c872
+telemetry.zh.md: c99b287fd4cb4e9bc585ffe365ca08df37f6ccd1
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
new file mode 100644
index 0000000000..4942a402da
--- /dev/null
+++ b/docs/subsystems/telemetry.md
@@ -0,0 +1,109 @@
+# Telemetry
+
+English | [中文](telemetry.zh.md)
+
+Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/telemetry/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/telemetry/session-telemetry/README.md).
+
+Source: [`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+
+## The logical record
+
+```ts type-equiv
+/**
+ * Severity of a telemetry record, pre-mapped at capture so a receiver can
+ * alert with zero configuration: `error` for events whose own outcome flag
+ * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * `agent-error` operational records. Captured events otherwise default to
+ * `info`; `warn` remains available to `telemetry/record` policies and
+ * backends.
+ */
+type TelemetrySeverity = 'info' | 'warn' | 'error'
+```
+
+```ts type-equiv
+/**
+ * One logical record handed to a backend — the seam's whole outbound
+ * vocabulary. Ledger records mirror session-log events one-to-one;
+ * operational records (`channel: 'ops'`) carry the two signals with no log
+ * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
+ * identity so they can never be mistaken for ledger rows.
+ */
+interface TelemetryRecord {
+  /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+  channel: 'ledger' | 'ops'
+  /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+  time: number
+  /** Pre-mapped alerting severity; see {@link TelemetrySeverity}. */
+  severity: TelemetrySeverity
+  /**
+   * Identity attributes, deliberately minimal: ledger records carry
+   * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
+   * `session.parent_id` when the header has them; ops records carry
+   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
+   * `turn`, `step`, `error.name`. Anything recoverable from the body is
+   * intentionally NOT duplicated here.
+   */
+  attributes: Record<string, string | number>
+  /**
+   * The complete payload: a deep copy of the session event's `data` for
+   * ledger records (JSON-serializable by `Session.append`'s own
+   * validation), or the op payload for ops records. Never mutated after
+   * handoff.
+   */
+  body: unknown
+}
+```
+
+Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is at-most-once downstream of the handoff; receivers dedupe on `(session.id, event.seq)`.
+
+## The backend contract
+
+```ts type-equiv
+/**
+ * The backend contract the coordinator hands records to — the minimum any
+ * reporting SDK satisfies with zero bending. {@link Telemetry} is its
+ * service-registered form; tests compose the coordinator with a bare
+ * implementation of this interface.
+ */
+interface TelemetryBackend {
+  /**
+   * Hand one record to the backend's pipeline. MUST be a non-blocking
+   * enqueue — the coordinator calls this synchronously from the
+   * `session/event` hot path, so anything slower than a queue push would tax
+   * the agent loop. Errors thrown here are contained by the coordinator and
+   * logged; they never reach the loop.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  emit(record: TelemetryRecord): void
+  /**
+   * Optional hint that a natural boundary (turn end) passed — a backend may
+   * forward it to its SDK's flush so records land at turn boundaries. Called
+   * fire-and-forget; implementations must not block and must not throw
+   * meaningfully (the coordinator contains exceptions). Most backends should
+   * leave this unimplemented and let their SDK's own batching cadence govern
+   * export timing: a backend that does implement it owns the interaction
+   * between its concurrent flushes and {@link shutdown}'s drain (the OTel
+   * backend removed its implementation for exactly that hazard — see the
+   * revival Agent Note).
+   */
+  flush?(): void
+  /**
+   * Forward the fiber's disposal to the SDK: flush whatever is queued and
+   * reach quiescence, per the SDK's own shutdown contract. Everything
+   * emitted before this call must still be delivered — including records
+   * enqueued while a {@link flush} hint is in flight, so a backend whose SDK
+   * guards against concurrent flushes orders behind the outstanding one (the
+   * coordinator emits its dispose-time `shutdown` markers immediately before
+   * calling this). Awaited by the coordinator's dispose; a rejection is
+   * logged as a warning and never fails application teardown.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  shutdown(): Promise<void>
+}
+```
+
+`Telemetry` (`ctx.telemetry`, [signatures](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+
+## The redact waterfall: `telemetry/record`
+
+Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between projection and `emit()` ([event entry](../cordis-catalog/events.md#telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
new file mode 100644
index 0000000000..c99b287fd4
--- /dev/null
+++ b/docs/subsystems/telemetry.zh.md
@@ -0,0 +1,109 @@
+# 遥测（telemetry）
+
+[English](telemetry.md) | 中文
+
+对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/telemetry/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/telemetry/session-telemetry/README.md)。
+
+源码：[`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+
+## 逻辑记录
+
+```ts type-equiv
+/**
+ * Severity of a telemetry record, pre-mapped at capture so a receiver can
+ * alert with zero configuration: `error` for events whose own outcome flag
+ * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * `agent-error` operational records. Captured events otherwise default to
+ * `info`; `warn` remains available to `telemetry/record` policies and
+ * backends.
+ */
+type TelemetrySeverity = 'info' | 'warn' | 'error'
+```
+
+```ts type-equiv
+/**
+ * One logical record handed to a backend — the seam's whole outbound
+ * vocabulary. Ledger records mirror session-log events one-to-one;
+ * operational records (`channel: 'ops'`) carry the two signals with no log
+ * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
+ * identity so they can never be mistaken for ledger rows.
+ */
+interface TelemetryRecord {
+  /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+  channel: 'ledger' | 'ops'
+  /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+  time: number
+  /** Pre-mapped alerting severity; see {@link TelemetrySeverity}. */
+  severity: TelemetrySeverity
+  /**
+   * Identity attributes, deliberately minimal: ledger records carry
+   * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
+   * `session.parent_id` when the header has them; ops records carry
+   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
+   * `turn`, `step`, `error.name`. Anything recoverable from the body is
+   * intentionally NOT duplicated here.
+   */
+  attributes: Record<string, string | number>
+  /**
+   * The complete payload: a deep copy of the session event's `data` for
+   * ledger records (JSON-serializable by `Session.append`'s own
+   * validation), or the op payload for ops records. Never mutated after
+   * handoff.
+   */
+  body: unknown
+}
+```
+
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。交接下游的投递为至多一次（at-most-once）；接收端基于 `(session.id, event.seq)` 去重。
+
+## 后端契约
+
+```ts type-equiv
+/**
+ * The backend contract the coordinator hands records to — the minimum any
+ * reporting SDK satisfies with zero bending. {@link Telemetry} is its
+ * service-registered form; tests compose the coordinator with a bare
+ * implementation of this interface.
+ */
+interface TelemetryBackend {
+  /**
+   * Hand one record to the backend's pipeline. MUST be a non-blocking
+   * enqueue — the coordinator calls this synchronously from the
+   * `session/event` hot path, so anything slower than a queue push would tax
+   * the agent loop. Errors thrown here are contained by the coordinator and
+   * logged; they never reach the loop.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  emit(record: TelemetryRecord): void
+  /**
+   * Optional hint that a natural boundary (turn end) passed — a backend may
+   * forward it to its SDK's flush so records land at turn boundaries. Called
+   * fire-and-forget; implementations must not block and must not throw
+   * meaningfully (the coordinator contains exceptions). Most backends should
+   * leave this unimplemented and let their SDK's own batching cadence govern
+   * export timing: a backend that does implement it owns the interaction
+   * between its concurrent flushes and {@link shutdown}'s drain (the OTel
+   * backend removed its implementation for exactly that hazard — see the
+   * revival Agent Note).
+   */
+  flush?(): void
+  /**
+   * Forward the fiber's disposal to the SDK: flush whatever is queued and
+   * reach quiescence, per the SDK's own shutdown contract. Everything
+   * emitted before this call must still be delivered — including records
+   * enqueued while a {@link flush} hint is in flight, so a backend whose SDK
+   * guards against concurrent flushes orders behind the outstanding one (the
+   * coordinator emits its dispose-time `shutdown` markers immediately before
+   * calling this). Awaited by the coordinator's dispose; a rejection is
+   * logged as a warning and never fails application teardown.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  shutdown(): Promise<void>
+}
+```
+
+`Telemetry`（`ctx.telemetry`，[签名](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+
+## 脱敏 waterfall：`telemetry/record`
+
+每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics)（[事件条目](../cordis-catalog/events.md#telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
new file mode 100644
index 0000000000..5540d00aab
--- /dev/null
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
+workspace.md: 2726115457905687e3c2cfc35a7a3f7251e6347c
+workspace.zh.md: 190c44b2d73f9e123242c34b5429839abe3b9297
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
new file mode 100644
index 0000000000..190c44b2d7
--- /dev/null
+++ b/docs/subsystems/workspace.zh.md
@@ -0,0 +1,121 @@
+# 工作区
+
+[English](workspace.md) | 中文
+
+工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（[dsh-workspace](../../packages/workspace/workspace)，`ctx.workspace`）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过[存储领域数据形式](storage.md)存储自己的记录，并对照 [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log) 校验会话成员资格，因此 `storageDomain` 与 `sessionPersistence` 是必需的启动依赖：持久化这一侧不可用时插件保持 pending，而不会被误认为历史为空。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；引导与 GUI 顺序：[Workspace UI 产品流程 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
+
+源码：[`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
+
+## 标识
+
+```ts type-equiv
+/**
+ * Identifies one workspace record. A generated uuid, never the path: path
+ * normalization rewrites paths, and a reference anchor must stay stable.
+ */
+type WorkspaceId = Branded<'WorkspaceId'>
+```
+
+`WorkspaceId` 是[品牌化 id](core.md#branded-ids)。路径标识与之分离：`realpathNormalize`（`fs.realpath`；尾部斜杠、`..` 与符号链接全部解析）是唯一的一套唯一性规范——工作区路径以规范化形式存储，唯一性即规范路径的字符串相等（指向已被拥有目录的符号链接会与之冲突），attach 时的会话 cwd 检查也走同一套规范。
+
+## 工作区实体
+
+消费方只看到 `Workspace` 接口；实现保持包内私有。
+
+```ts type-equiv
+/**
+ * One workspace: a stable id over an existing directory, a display title, and
+ * an ordered candidate account of sessions. Membership requires both an id in
+ * that account and a session header whose canonical cwd equals the workspace
+ * path. Consumers only see this interface; the implementation stays private.
+ */
+interface Workspace {
+  /** Stable record id (generated uuid). */
+  readonly id: WorkspaceId
+
+  /**
+   * Canonical directory path: the `fs.realpath` of the path given at create
+   * time (trailing slashes, `..`, and symlinks all resolved). Never rewritten
+   * afterwards, even when the directory disappears (see {@link status}).
+   */
+  readonly path: string
+
+  /** Display title. Defaults to `basename(path)` at create; duplicates are allowed. */
+  readonly title: string
+
+  /** ISO-8601 creation instant, stamped at create and never rewritten. */
+  readonly createdAt: string
+
+  /** ISO-8601 instant of the last durable mutation (create counts as one). */
+  readonly updatedAt: string
+
+  /**
+   * Header-validated sessions in manually owned order: a new session is
+   * prepended at attach, explicit reordering goes through
+   * `insertSessionBefore`, and activity never reorders. The durable candidate
+   * account is filtered synchronously: missing headers, invalid cwd values,
+   * and canonical cwd mismatches are never returned. A subsequent workspace
+   * mutation prunes those filtered candidates durably.
+   */
+  readonly sessionIds: readonly SessionId[]
+
+  /**
+   * Replace the display title durably.
+   * @param title - New title; any string, duplicates across workspaces allowed.
+   * @returns resolution after durability.
+   */
+  setTitle(title: string): Promise<void>
+
+  /**
+   * Prepend a session to this workspace's candidate account. An already
+   * accounted id resolves without writing. A new id's live or persisted
+   * header cwd must resolve to an existing directory equal to {@link path};
+   * unknown ids, missing or invalid cwd values, and mismatches reject without
+   * writing.
+   * @param sessionId - The session to record.
+   * @returns resolution after durability.
+   */
+  attachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Move an accounted session within the manual order, DOM-insertBefore-like:
+   * with an anchor the session lands before it, without one it appends to the
+   * end. Only the moved id changes position. A session or anchor absent from
+   * the account rejects without writing; a move to the current position
+   * resolves without writing (decided on the domain write chain).
+   * @param sessionId - The accounted session to move.
+   * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
+   * @returns resolution after durability.
+   */
+  insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>
+
+  /**
+   * Remove a session from this workspace's account. Idempotent: an id not on
+   * the account resolves without writing (decided on the domain write chain,
+   * like attach). Never touches the session's own stored log.
+   * @param sessionId - The session to remove.
+   * @returns resolution after durability.
+   */
+  detachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Live directory check, uncached: whether {@link path} currently exists and
+   * is a directory. A missing directory never mutates the record — the
+   * directory may only be temporarily moved.
+   * @returns `'ok'` when the directory exists, `'missing-dir'` otherwise.
+   */
+  status(): Promise<'ok' | 'missing-dir'>
+}
+```
+
+所有权的真源是记录中有序的 `sessionIds`，绝不从会话 cwd 派生——但成员资格要求两者同时成立：账本上有其 id，且 header 的规范 cwd 等于工作区路径，因此一个会话在结构上至多属于一个工作区。失败的写入会拒绝（`insertSessionBefore` 的账本错误以 `WorkspaceMoveInvalidError` 拒绝，存储失败以普通错误拒绝）；每次被接受的变更都盖上 `updatedAt` 时间戳，并持久修剪不再通过成员资格检查的候选项。
+
+## 注册表：`ctx.workspace`
+
+`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样抛出 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
+
+会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑，而没有 cwd 的历史遗留会话保持 Ungrouped。
+
+## 消费方
+
+[dsh-host-apiproxy](../../packages/host/apiproxy) 是产品消费方：它经 `ctx.workspace` 向 GUI 客户端提供工作区的 CRUD，并执行上文「先建会话再 attach」的流程。[dsh-workspace-context](../../packages/context/workspace-context) 尽管名字如此，却**不是**消费方：它在 agent 自己的 cwd 下发现 AGENTS.md 风格的指令文件，从不触碰 `ctx.workspace`——两者共用的这个词指的是用户的工作目录，而非本注册表的实体。
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b710bebe76..b3fdfb7546 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -252,6 +252,7 @@ export const LINK_MAP: Record<string, string> = {
   Workspace: 'workspace.md',
   WorkspaceId: 'workspace.md',
   WebBootGraph: 'client-modules.md',
+  TelemetryRecord: 'telemetry.md',
 }
 
 /** TypeScript lib and pinned framework types that have no repository-owned data page. */
@@ -312,7 +313,6 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
-  TelemetryRecord: 'seam-local record contract is owned by packages/session/session-telemetry/src/index.ts',
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b53ff60989..4650150a7d 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -199,7 +199,7 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "GoalView",
-      "source": "packages/goal/goal/src/types.ts"
+      "source": "packages/goal/goal/src/domain.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -219,12 +219,12 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "CreateGoalRequest",
-      "source": "packages/goal/goal/src/types.ts"
+      "source": "packages/goal/goal/src/domain.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "EditGoalRequest",
-      "source": "packages/goal/goal/src/types.ts"
+      "source": "packages/goal/goal/src/domain.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -1475,11 +1475,6 @@
       "symbol": "SettingsUpdateSource",
       "source": "packages/settings/settings/src/index.ts"
     },
-    {
-      "doc": "docs/subsystems/credentials.md",
-      "symbol": "CredentialRef",
-      "source": "packages/credentials/credentials/src/index.ts"
-    },
     {
       "doc": "docs/subsystems/credentials.md",
       "symbol": "ResolvedCredential",
@@ -1505,69 +1500,6 @@
       "symbol": "SettingsPathOp",
       "source": "packages/settings/settings/src/index.ts"
     },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTLookupMap",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTContextMap",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTLookupDefinition",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTCodec",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "InvocationParameterDescriptor",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "InvocationDescriptor",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTService",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTRemoteNamespaceMap",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "InvokeRemoteRequest",
-      "source": "packages/api/gateway/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypertGatewayErrorCode",
-      "source": "packages/api/gateway/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypertGateway",
-      "source": "packages/api/gateway/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTClientRemote",
-      "source": "packages/typert/type-meta/src/types.ts"
-      "doc": "docs/subsystems/permission.md",
-      "symbol": "PresetSpec",
-      "source": "packages/interaction/permission/src/index.ts"
-    },
     {
       "doc": "docs/subsystems/permission.md",
       "symbol": "Config",
@@ -1687,6 +1619,81 @@
       "doc": "docs/subsystems/client-modules.md",
       "symbol": "WebBootGraph",
       "source": "packages/client/modules/src/client/manifest.ts"
+    },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetrySeverity",
+      "source": "packages/telemetry/session-telemetry/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetryRecord",
+      "source": "packages/telemetry/session-telemetry/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetryBackend",
+      "source": "packages/telemetry/session-telemetry/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTLookupMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTContextMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTLookupDefinition",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTCodec",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "InvocationParameterDescriptor",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "InvocationDescriptor",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTService",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTRemoteNamespaceMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "InvokeRemoteRequest",
+      "source": "packages/api/gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypertGatewayErrorCode",
+      "source": "packages/api/gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypertGateway",
+      "source": "packages/api/gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTClientRemote",
+      "source": "packages/typert/type-meta/src/types.ts"
     }
   ]
 }

From a8cf78630cbff2d1ea40128dfbfa1ace4e7b8b15 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 23:52:35 +0800
Subject: [PATCH 158/262] docs: align zh subsystem pages with late en-side
 precision edits

The translators' clause-by-clause verification pass caught the English
pages' final wording refinements (tui built-in dialogs enumeration and
display()'s line-feed exception, invariants whitespace-padded/companion
phrasing, client-modules fiber-lifecycle parenthetical, storage strict
sequence, workspace first-successful-start) landing after the initial
zh versions; this aligns the eight pages and re-records their pairs.
---
 docs/subsystems/client-modules.i18n.yaml |  2 +-
 docs/subsystems/client-modules.zh.md     |  6 +++---
 docs/subsystems/core.i18n.yaml           |  2 +-
 docs/subsystems/core.zh.md               |  2 +-
 docs/subsystems/http-server.i18n.yaml    |  2 +-
 docs/subsystems/http-server.zh.md        |  6 +++---
 docs/subsystems/invariants.i18n.yaml     |  2 +-
 docs/subsystems/invariants.zh.md         | 10 +++++-----
 docs/subsystems/permission.i18n.yaml     |  2 +-
 docs/subsystems/permission.zh.md         |  6 +++---
 docs/subsystems/plan.i18n.yaml           |  2 +-
 docs/subsystems/plan.zh.md               |  4 ++--
 docs/subsystems/storage.i18n.yaml        |  2 +-
 docs/subsystems/storage.zh.md            |  4 ++--
 docs/subsystems/workspace.i18n.yaml      |  2 +-
 docs/subsystems/workspace.zh.md          |  6 +++---
 16 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index a9a68fd065..9c30e276d4 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/client-modules.md
 client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
-client-modules.zh.md: bbcdb04cdce8a0d5256d2490deb238812e9a47fc
+client-modules.zh.md: e04bd8ac0c6a1566307559f02fc8075c907c0a7f
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index bbcdb04cdc..e04bd8ac0c 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -42,17 +42,17 @@ interface WebBootGraph {
 }
 ```
 
-每一行的 `rev` 是该 bundle 的内容哈希，并作为使缓存失效的查询参数附在 URL 上；图的 `rev` 对组合后的各行做哈希，因此任何一行的变化都会改变它。`immediately` 标记第一阶段预取档位（在模块面启动期间 fetch 并执行，只做工厂登记）；惰性行在首次 import 时才拉取。
+每一行的 `rev` 是该 bundle 的内容哈希，并作为使缓存失效的查询参数附在 URL 上；图的 `rev` 对组合后的各行做哈希，因此任何一行的变化都会改变它。`immediately` 标记第一阶段预取档位（在模块面启动期间 fetch 并执行，只做登记）；惰性行在首次 import 时才拉取。
 
 ## 扫描
 
 包加入这张表的方式，是在自己的 package.json 中声明 `dshClient`（`platform: 'web'`、可选的 `inject` 边、可选的 `immediately`），并在 `exports["./client"]` 导出构建好的 bundle。包解析锚定在配置树的 `ctx.baseUrl`——即 cordis.yml 所在目录，该目录的包把每个被组合的插件声明为依赖——这一锚点未设置时，构造即抛错。
 
-扫描是单包增量的；不存在全量重扫代码路径。每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
+扫描是单包增量的；不存在全量重扫代码路径。fiber 构造或 dispose（资源释放）时的每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
 
 包元数据——包括「非 client 包」这一否定结论——按名缓存且永不过期：插件集合的变更在重启后生效。fiber 重启原样复用其行与 rev；bundle 内容变更只经 `rebuilt()` 到达图。
 
-## 路由
+## bundle 路由与 index 转换
 
 `GET`/`HEAD /plugins/<id>/client.js` 以 `no-cache` 从磁盘提供已注册的 bundle（锚定一致性的是 rev 查询参数，而非 HTTP 缓存）；其他方法返回 405。未知 id——或已注册、但 bundle 因尚未构建而不可读的行——回应一个大声的 404，而不是让载体的 SPA 回退把 HTML 当作 JavaScript 发出。index 转换在每次 index 渲染时注入当前图，因此刷新页面总是针对实时组合启动。
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index d0188cb2f3..8bf98e026d 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: 1d0bf6c61500817860dfdd452bddc25adbbeffcc
-core.zh.md: 06fd3b5a48d5267c9856c20589772047b6105b2c
+core.zh.md: 2b4766dcfcf1901de2bb8a8f9168888a67af7fba
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 06fd3b5a48..2b4766dcfc 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -48,7 +48,7 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空伴随插件契约 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index cb2c734255..8369b94dac 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
 http-server.md: 565df72f2720a1211f50650d4b1bc8d6df4a007a
-http-server.zh.md: 93b056648f044f6c79b85a6069deb3123f9a7a3e
+http-server.zh.md: 69e4a0bd7a1576737583625b23fac2ed05d8ca61
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index fc5e18414b..69e4a0bd7a 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -24,7 +24,7 @@ interface WebRoute {
 }
 ```
 
-匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退保持锁定语义：非 GET/HEAD 返回 405，越出 dist 根目录的路径穿越返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 交付（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
+匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退遵循固定语义：非 GET/HEAD 返回 405，越出 dist 根目录的遍历返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
 
 ## 配置
 
@@ -44,6 +44,6 @@ interface Config {
 
 ## 服务
 
-`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动阶段的大声失败巡检报告。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层面的契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
+`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
 
-处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能保持响应打开（如 SSE（Server-Sent Events）），而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
+处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包（package）从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index dc5a8a6d0d..27b6ac8e87 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/invariants.md
 invariants.md: 143a7feabbab18556f595a78c7aef17caa6d3028
-invariants.zh.md: ab7aa0221101400d552ff47e1cfa3275d99a0b6d
+invariants.zh.md: fb497857c02202544edf44ccfe3a2935a988e30e
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index ab7aa02211..fb497857c0 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -2,7 +2,7 @@
 
 [English](invariants.md) | 中文
 
-[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 伴随插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
+[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
 
 源码：[`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
 
@@ -20,7 +20,7 @@ interface Config {
 }
 ```
 
-一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时大声失败：空白、带空白填充、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/support/invariants/README.md)）。
+一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时大声失败：空白、首尾带空白、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/support/invariants/README.md)）。
 
 ## 安装器
 
@@ -52,8 +52,8 @@ interface InvariantInstaller {
 
 ## 服务
 
-`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于伴随插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此伴随插件可以重载并再次注册同一名称，不留残余状态。
+`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默地认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于配套插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此配套插件可以重载并再次注册同一名称，不留残余状态。
 
-## 伴随插件契约
+## 配套插件契约
 
-每个工作区包都拥有一个 `./invariant` 伴随插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但断言刻意不为凑数而虚构。只有当包对某个可观察事件或可变数据拥有所有权关系时，伴随插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行伴随插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
+每个工作区包都拥有一个 `./invariant` 配套插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index f800d4ff08..284f29bb62 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/permission.md
 permission.md: 49dd51ff86d0dbce26fca0ed21527f71bb144dec
-permission.zh.md: 5fb93e9f923582e6c530bac4a22e2ce62cff156d
+permission.zh.md: c2ab6ecdfb4b80511107bee41e080b06fae45f2c
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index 5fb93e9f92..c2ab6ecdfb 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -2,13 +2,13 @@
 
 [English](permission.md) | 中文
 
-[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮，即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
+[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮（knob），即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
 
 源码：[`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
 
 ## 预设表
 
-预设是一个表键，映射到一组沙箱／审批组合，外加可选的客户端展示信息；默认预设表自带 `workspace-write`（`workspace-write` + `ask`）和 `danger-full-access`（`danger-full-access` + `never`）。
+预设是一个表键，映射到一个沙箱／审批组合，外加可选的客户端展示信息；默认预设表自带 `workspace-write`（`workspace-write` + `ask`）和 `danger-full-access`（`danger-full-access` + `never`）。
 
 ```ts type-equiv
 /** One preset's sandbox/approval bundle and optional client presentation. */
@@ -36,7 +36,7 @@ interface Config {
 }
 ```
 
-该服务要求一个施加沙箱隔离的 `ctx.bash` 执行器和 `ctx.approval`，配置错误在插件加载时即失败：名为 `custom` 的表项会抛出异常（该名称保留给派生的「非预设」状态）；在不施加隔离的 bash 执行器（没有 `sandboxMode` 能力事实）之上组合同样抛出异常，因为预设捆绑了一个沙箱模式。
+该服务要求一个施加隔离的 `ctx.bash` 执行器和 `ctx.approval`，配置错误在插件加载时即失败：名为 `custom` 的表项会抛出异常（该名称保留给派生的「非预设」状态）；在不施加隔离的 bash 执行器（没有 `sandboxMode` 能力事实）之上组合同样抛出异常，因为预设捆绑了一个沙箱模式。
 
 ## 当前预设与派生的 `custom`
 
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index 3ae156615f..c73912c178 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/plan.md
 plan.md: f67e7734ca3fd55c284d3d41227f8241de7b9f5f
-plan.zh.md: 565cf2016636acb6c26d20c731b9e6e374cee1da
+plan.zh.md: 27114c3c1c2acae3868b9c5bff37485b6da85377
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index af21a6d027..27114c3c1c 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -14,7 +14,7 @@
 
 由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
-服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响该边界紧接其后的那个请求。冲刷失败会被隔离（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响紧随该边界的那个请求。冲刷失败会被收容（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
 ## 配置
 
@@ -26,7 +26,7 @@ interface PlanModeConfig {
 }
 ```
 
-`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地什么都不影响。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.md)；未激活的计划模式不贡献任何文本。
+`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地不产生任何指引。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.md)；未激活的计划模式不贡献任何文本。
 
 ## 退出工具与 `/plan` 命令
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 92387332f0..6560eed831 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/storage.md
 storage.md: 5d54d7337b5ef52e24179758130b9fa8cd196376
-storage.zh.md: c575f989fe4b3536ce3c8d3b3af08ebda418166d
+storage.zh.md: 46346b64351322d40de166a71f7a3204c8902b2d
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index c575f989fe..46346b6435 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -64,7 +64,7 @@ interface DomainSpec {
 }
 ```
 
-`defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就大声失败：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable<K, V>(schema)` 声明一张表，其键类型是编译期的幻影类型（通常是[品牌化 id](core.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。
+`defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就大声失败：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable<K, V>(schema)` 声明一张表，其键类型是仅存在于编译期的 phantom 类型（通常是[品牌化 id](core.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。
 
 ## 打开的领域
 
@@ -99,7 +99,7 @@ interface Domain<S extends DomainSpec> {
 
 ## 领域 facility：`ctx.storageDomain`
 
-`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 逐步执行，任一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找；`closeAll()` 是卸载路径。
+`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 按严格顺序执行，每一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找，命中的是每个类型化句柄背后包内私有的 `DomainImpl` 运行时；`closeAll()` 是卸载路径。
 
 ## 变更事件：`domain/changed`
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 5540d00aab..16ad3b95a3 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/workspace.md
 workspace.md: 2726115457905687e3c2cfc35a7a3f7251e6347c
-workspace.zh.md: 190c44b2d73f9e123242c34b5429839abe3b9297
+workspace.zh.md: 3a752617a58e4c9b62ec4084d2dc518015030952
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 190c44b2d7..3a752617a5 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -2,7 +2,7 @@
 
 [English](workspace.md) | 中文
 
-工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（[dsh-workspace](../../packages/workspace/workspace)，`ctx.workspace`）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过[存储领域数据形式](storage.md)存储自己的记录，并对照 [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log) 校验会话成员资格，因此 `storageDomain` 与 `sessionPersistence` 是必需的启动依赖：持久化这一侧不可用时插件保持 pending，而不会被误认为历史为空。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；引导与 GUI 顺序：[Workspace UI 产品流程 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
+工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（[dsh-workspace](../../packages/workspace/workspace)，`ctx.workspace`）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过[存储领域数据形式](storage.md)存储自己的记录，并对照 [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log) 校验会话成员资格，因此 `storageDomain` 与 `sessionPersistence` 是必需的启动依赖：持久化这一依赖不可用时，插件保持 pending，而不是把这种不可用误当作空历史。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；引导与 GUI 顺序：[Workspace UI 产品流程 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
 
 源码：[`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
 
@@ -112,9 +112,9 @@ interface Workspace {
 
 ## 注册表：`ctx.workspace`
 
-`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样抛出 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
+`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
 
-会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑，而没有 cwd 的历史遗留会话保持 Ungrouped。
+会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
 ## 消费方
 

From 061100f6f2cc1608a2c73811d74382f9d92b27d7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 00:20:38 +0800
Subject: [PATCH 159/262] docs: fix four factual errors found by Codex review
 round 1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- plan.md/.zh.md (+ plan-mode module JSDoc and README pair): the sole
  flush point is the prepended agent/step listener; prompt admission is
  pre-turn and never flushes — the pages had it backwards.
- workspace.md/.zh.md: pending-mutation recovery deletes the marked
  table row — completing an interrupted delete but rolling back an
  interrupted create; 'completes exactly the marked mutation' oversold.
- telemetry.md/.zh.md: delivery is best-effort with possible loss AND
  duplication, not at-most-once; TelemetryRecord.attributes JSDoc (source
  + both fences) now lists session.seed_length, which the coordinator
  emits for forked sessions.
- Agent Note consequence bullet: nine pages cover ten services (storage
  owns two keys); client-modules.zh.md wire-single-source phrasing.

Pairs re-recorded; plan-mode and telemetry suites green.
---
 .../2026-06-20-core-data-structures-catalog.i18n.yaml  |  4 ++--
 .../process/2026-06-20-core-data-structures-catalog.md |  2 +-
 .../2026-06-20-core-data-structures-catalog.zh.md      |  2 +-
 docs/subsystems/client-modules.i18n.yaml               |  2 +-
 docs/subsystems/client-modules.zh.md                   |  2 +-
 docs/subsystems/plan.i18n.yaml                         |  4 ++--
 docs/subsystems/plan.md                                |  2 +-
 docs/subsystems/plan.zh.md                             |  2 +-
 docs/subsystems/telemetry.i18n.yaml                    |  4 ++--
 docs/subsystems/telemetry.md                           | 10 +++++-----
 docs/subsystems/telemetry.zh.md                        | 10 +++++-----
 docs/subsystems/workspace.i18n.yaml                    |  4 ++--
 docs/subsystems/workspace.md                           |  2 +-
 docs/subsystems/workspace.zh.md                        |  2 +-
 packages/session/session-telemetry/src/index.ts        |  8 ++++----
 15 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 5bc51a4e7d..0883a5e9ab 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 718045bf7ce511a0b766e69e64ef7657eb221189
-2026-06-20-core-data-structures-catalog.zh.md: 1e8473a373c212fa08b171719edd5803e5aa3b05
+2026-06-20-core-data-structures-catalog.md: a8de47a462da13f316236fb7da3f4bfb57edae21
+2026-06-20-core-data-structures-catalog.zh.md: d84c2befaee4c2032b358ed1a7949ac0151ae74c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 718045bf7c..a8de47a462 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -58,4 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the nine `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules, telemetry) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 1e8473a373..d84c2befae 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -58,4 +58,4 @@ Status: implemented
 - 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
-- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的九个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块、遥测）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
+- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：九个精简页面（权限预设、计划模式、运行时不变式、HTTP 载体、存储——同时拥有 `ctx.storage` 与 `ctx.storageDomain`——终端扩展、工作区、客户端模块、遥测）覆盖了原先没有页面的十个 `ctx` 服务，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 9c30e276d4..8988609cdf 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/client-modules.md
 client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
-client-modules.zh.md: e04bd8ac0c6a1566307559f02fc8075c907c0a7f
+client-modules.zh.md: 5da7740e4c9272a3516f1a28712be7c95f29a6b3
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index e04bd8ac0c..5da7740e4c 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -8,7 +8,7 @@ Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 
 
 ## wire
 
-图是 Node 半与浏览器半之间的线上单源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
+图是 Node 半与浏览器半之间协议层的唯一事实来源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index c73912c178..7c20a42864 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: f67e7734ca3fd55c284d3d41227f8241de7b9f5f
-plan.zh.md: 27114c3c1c2acae3868b9c5bff37485b6da85377
+plan.md: eb88047573536cd15be587b1419271bfbd93e9f1
+plan.zh.md: 5a838a045d63f2cabad80cad8af12df5da7e87f3
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index f67e7734ca..eb88047573 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -14,7 +14,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
-The service flushes one pending selection before the affected request assembly at three boundaries: prompt submission, ordinary turn continuation, and request-recovery retry. The flush runs after the downstream listener chain, so a selection arriving while an async listener awaits still shapes the request that boundary precedes. A flush failure is contained — plan policy can never block a prompt or turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
 ## Configuration
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 27114c3c1c..5a838a045d 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -14,7 +14,7 @@
 
 由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
-服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响紧随该边界的那个请求。冲刷失败会被收容（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
 ## 配置
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 9f6fdb3af3..d7544c7ddf 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: 4942a402dacb40ed64070c2b7824bfea7a14c872
-telemetry.zh.md: c99b287fd4cb4e9bc585ffe365ca08df37f6ccd1
+telemetry.md: cf6d3556a638375d939b29cc28941bf9c9ec7ea4
+telemetry.zh.md: 95eadb26581a6a96ce208d7c3b265d89455de4ba
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 4942a402da..cf6d3556a6 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -38,10 +38,10 @@ interface TelemetryRecord {
   /**
    * Identity attributes, deliberately minimal: ledger records carry
    * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
-   * `session.parent_id` when the header has them; ops records carry
-   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
-   * `turn`, `step`, `error.name`. Anything recoverable from the body is
-   * intentionally NOT duplicated here.
+   * `session.parent_id` / `session.seed_length` when the header has them;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
    */
   attributes: Record<string, string | number>
   /**
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is at-most-once downstream of the handoff; receivers dedupe on `(session.id, event.seq)`.
+Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is best-effort: the cursor marks handed-off, not delivered, records can be lost (crash, reload window) and duplicated (cursor-less re-adoption, SDK retries), so receivers dedupe on `(session.id, event.seq)`.
 
 ## The backend contract
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index c99b287fd4..95eadb2658 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -38,10 +38,10 @@ interface TelemetryRecord {
   /**
    * Identity attributes, deliberately minimal: ledger records carry
    * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
-   * `session.parent_id` when the header has them; ops records carry
-   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
-   * `turn`, `step`, `error.name`. Anything recoverable from the body is
-   * intentionally NOT duplicated here.
+   * `session.parent_id` / `session.seed_length` when the header has them;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
    */
   attributes: Record<string, string | number>
   /**
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。交接下游的投递为至多一次（at-most-once）；接收端基于 `(session.id, event.seq)` 去重。
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端基于 `(session.id, event.seq)` 去重。
 
 ## 后端契约
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 16ad3b95a3..a50df35f91 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: 2726115457905687e3c2cfc35a7a3f7251e6347c
-workspace.zh.md: 3a752617a58e4c9b62ec4084d2dc518015030952
+workspace.md: bade3526964055d5bf4448265c5898f1e66a1fce
+workspace.zh.md: b0437e42b644c1ce11d9a667972f7b236cf4caa1
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 2726115457..bade352696 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -112,7 +112,7 @@ Ownership truth is the record's ordered `sessionIds`, never derived from session
 
 ## The registry: `ctx.workspace`
 
-`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup completes exactly the marked mutation, and an unmarked order/table mismatch fails loud as corruption.
+`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
 
 Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 3a752617a5..b0437e42b6 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -112,7 +112,7 @@ interface Workspace {
 
 ## 注册表：`ctx.workspace`
 
-`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
+`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好解决被标记的那次变更——通过删除被标记的表行：这会补完被中断的 delete，并回滚被中断的 create（注册可以重建，因此回滚是安全方向）——而没有标记的顺序/表不一致则作为损坏大声失败。
 
 会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 0198df3140..6a8e9ed2ad 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -71,10 +71,10 @@ export interface TelemetryRecord {
   /**
    * Identity attributes, deliberately minimal: ledger records carry
    * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
-   * `session.parent_id` when the header has them; ops records carry
-   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
-   * `turn`, `step`, `error.name`. Anything recoverable from the body is
-   * intentionally NOT duplicated here.
+   * `session.parent_id` / `session.seed_length` when the header has them;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
    */
   attributes: Record<string, string | number>
   /**

From 0dd3ac14eb177fe1fb3802497846b847686c4249 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 00:36:30 +0800
Subject: [PATCH 160/262] docs: regenerate catalogs after the plan-mode JSDoc
 expansion shifted source lines

Codex round-2: the two-line module-JSDoc fix moved every later
declaration in packages/plan/plan-mode/src/index.ts, so the three
generated catalogs' source-line links went stale. Three one-line
regenerated updates; doc-sync back to 25/25.
---
 scripts/type-equiv.manifest.json | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 4650150a7d..e1f80b96b6 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1694,6 +1694,16 @@
       "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/credentials.md",
+      "symbol": "CredentialRef",
+      "source": "packages/credentials/credentials/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "PresetSpec",
+      "source": "packages/interaction/permission/src/index.ts"
     }
   ]
 }

From bd62b6c0322c5eaa5ce10d54351f211352fb22f5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 11:20:22 +0800
Subject: [PATCH 161/262] docs: qualify the telemetry dedupe key as ledger-only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot: ops records deliberately omit event.seq, so the
(session.id, event.seq) dedupe advice cannot apply to them — they are
alert signals that tolerate duplicates. Both language sides; pair
re-recorded.
---
 docs/subsystems/telemetry.i18n.yaml | 4 ++--
 docs/subsystems/telemetry.md        | 2 +-
 docs/subsystems/telemetry.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index d7544c7ddf..e97a6f2e27 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: cf6d3556a638375d939b29cc28941bf9c9ec7ea4
-telemetry.zh.md: 95eadb26581a6a96ce208d7c3b265d89455de4ba
+telemetry.md: 92235a26fe278dfd6ac2b2ea5703b5c0d837b336
+telemetry.zh.md: e076abd90bd5054ddbfd6fbe7b725ee45d50a038
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index cf6d3556a6..92235a26fe 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is best-effort: the cursor marks handed-off, not delivered, records can be lost (crash, reload window) and duplicated (cursor-less re-adoption, SDK retries), so receivers dedupe on `(session.id, event.seq)`.
+Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is best-effort: the cursor marks handed-off, not delivered, records can be lost (crash, reload window) and duplicated (cursor-less re-adoption, SDK retries), so receivers dedupe ledger records on `(session.id, event.seq)`; ops records deliberately omit that identity — they are signals to alert on, not entries to sum, and tolerate duplicates instead.
 
 ## The backend contract
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 95eadb2658..e076abd90b 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端基于 `(session.id, event.seq)` 去重。
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端对 ledger 记录基于 `(session.id, event.seq)` 去重；ops 记录刻意省略这类标识——它们是用于告警的信号，而非用于累加的条目，重复被容忍而非被去重。
 
 ## 后端契约
 

From 3e1c7351bef4202a65c5f739254dce8a68212695 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 12:04:21 +0800
Subject: [PATCH 162/262] docs: state the plan-mode flush as a step boundary

ds-review-bot round 2: set() during an open multi-step turn applies at
the next request derivation in that same turn, so 'next turn boundary'
misstated the public timing contract (and propagated into the generated
catalogs). set()'s JSDoc, the module JSDoc, the pending-intent field
comment, and the subsystem page (both languages) now say step boundary;
catalogs regenerated; plan pair re-recorded.
---
 docs/subsystems/plan.i18n.yaml | 4 ++--
 docs/subsystems/plan.md        | 4 ++--
 docs/subsystems/plan.zh.md     | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index 7c20a42864..3295167755 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: eb88047573536cd15be587b1419271bfbd93e9f1
-plan.zh.md: 5a838a045d63f2cabad80cad8af12df5da7e87f3
+plan.md: c8bb6c9b6a0bcfd20ed6eadece4552d49f3c757c
+plan.zh.md: c8acedaef0724581227b57afbf81418a7e538aed
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index eb88047573..c8bb6c9b6a 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -10,9 +10,9 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 `plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. `foldPlanMode(events, end?)` returns the last logged value in the prefix, or `false` when there is none — the state in force is always a pure fold of the session log, so resume, fork, and compaction recover it with no live mirror, and UIs observe committed flips through `session/event`. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
 
-## Pending intent and the turn-boundary flush
+## Pending intent and the step-boundary flush
 
-Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
+Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — within the same turn when one is open. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
 The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 5a838a045d..c8acedaef0 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -10,9 +10,9 @@
 
 `plan/mode`（`{ active: boolean }`）是仅记日志、整值替换的[会话事件](session.md)：持久且可回放，绝不进入模型 transcript（文本记录）。`foldPlanMode(events, end?)` 返回前缀中最后一条已记录值，没有时返回 `false`：生效状态始终是会话日志的纯折叠，因此恢复、fork 与压缩（compaction）无需实时镜像即可将其复原，UI 通过 `session/event` 观察已提交的切换。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)。
 
-## 待定意图与轮次边界冲刷
+## 待定意图与步骤边界冲刷
 
-由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
+由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——已有轮次开启时即在同一轮次之内。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
 唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 

From 44b035c711482016e91438a163234ecdb8efbfe6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 14:11:18 +0800
Subject: [PATCH 163/262] docs: qualify plan-mode timing and workspace no-write
 claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot round 3:
- set() after a turn's final step lands in a later turn (selection
  never forces continuation) — the same-turn phrasing overstated the
  guarantee; set() JSDoc + subsystem page (both languages).
- Workspace attach/insert/detach no-op claims now carry the
  filtered-candidate-prune caveat: mutate() durably prunes stale
  candidates even when the requested change is a no-op, a state the
  sessionIds contract explicitly permits; Workspace fence re-synced on
  both page sides; catalogs regenerated.
---
 docs/AGENTS.md                                |   4 +-
 docs/cordis-catalog/events.md                 |   5 +-
 docs/cordis-catalog/services.md               |  16 +-
 docs/subsystems/client-modules.i18n.yaml      |   4 +-
 docs/subsystems/client-modules.md             |   2 +-
 docs/subsystems/client-modules.zh.md          |   2 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |   1 -
 docs/subsystems/core.zh.md                    |   1 -
 docs/subsystems/http-server.i18n.yaml         |   4 +-
 docs/subsystems/http-server.md                |  10 +-
 docs/subsystems/http-server.zh.md             |   8 +-
 docs/subsystems/permission.i18n.yaml          |   4 +-
 docs/subsystems/permission.md                 |  15 +-
 docs/subsystems/permission.zh.md              |  15 +-
 docs/subsystems/plan.i18n.yaml                |   4 +-
 docs/subsystems/plan.md                       |   2 +-
 docs/subsystems/plan.zh.md                    |   2 +-
 docs/subsystems/telemetry.i18n.yaml           |   4 +-
 docs/subsystems/telemetry.md                  |  15 +-
 docs/subsystems/telemetry.zh.md               |  15 +-
 docs/subsystems/workspace.i18n.yaml           |   4 +-
 docs/subsystems/workspace.md                  |  13 +-
 docs/subsystems/workspace.zh.md               |  13 +-
 .../tests/cordis-catalog-contract.spec.ts     |   4 +-
 packages/workspace/workspace/README.i18n.yaml |   2 +-
 packages/workspace/workspace/README.zh.md     |   1 +
 packages/workspace/workspace/src/types.ts     |  13 +-
 scripts/gen-cordis-catalog.ts                 | 492 +++---------------
 scripts/type-equiv.manifest.json              |  39 +-
 30 files changed, 187 insertions(+), 531 deletions(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 3bbd4f330d..488a7a1dd6 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -20,7 +20,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 |---|---|---|
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
 | [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
@@ -37,7 +37,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The [core-data-structures catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
+- **The [subsystems catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 6d060cf26b..fb05eaa8e6 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -824,6 +824,8 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```
 
+Types: [TelemetryRecord](../subsystems/telemetry.md)
+
 Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `tools/*`
@@ -1090,8 +1092,7 @@ The framework events every plugin also sees, beyond the harness vocabulary above
 - `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
 - `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
 - `hmr/change` — A watched source file changed on disk. ([`vendor/hmr/src/index.ts:20`](../../vendor/hmr/src/index.ts))
-- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:22`](../../vendor/hmr/src/index.ts))
-- `hmr/config-update-failed` — A watched config-file refresh failed. ([`vendor/hmr/src/index.ts:29`](../../vendor/hmr/src/index.ts))
+- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:21`](../../vendor/hmr/src/index.ts))
 - `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
 - `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
 - `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index dbab056105..88f1762cff 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -377,6 +377,8 @@ onRebuilt(listener: (id: string, rev: string) => void): () => void
 onGraphChanged(listener: () => void): () => void
 ```
 
+Types: [WebBootGraph](../subsystems/client-modules.md)
+
 Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
 
 ## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
@@ -866,6 +868,8 @@ tapIndex(transform: (html: string) => string): () => void
 applyIndexTaps(html: string): string
 ```
 
+Types: [WebRoute](../subsystems/http-server.md)
+
 Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
 
 ## `ctx.invariants` — `InvariantService`
@@ -884,6 +888,8 @@ Package-owned invariant registry with global and regex-based selection.
 register(packageName: string, installer: InvariantInstaller): () => void
 ```
 
+Types: [InvariantInstaller](../subsystems/invariants.md)
+
 Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
 
 ## `ctx.llm` — `LlmService`
@@ -1060,7 +1066,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
+Types: [PresetOption](../subsystems/permission.md) · [PresetSpec](../subsystems/permission.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 
@@ -2036,6 +2042,8 @@ mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => v
 form<K extends keyof StorageForms>(form: K): StorageForms[K]
 ```
 
+Types: [StorageForms](../subsystems/storage.md)
+
 Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
 
 ## `ctx.storageDomain` — `DomainFacility`
@@ -2079,6 +2087,8 @@ get(name: string): DomainImpl | undefined
 async closeAll(): Promise<void>
 ```
 
+Types: [Domain](../subsystems/storage.md) · [DomainSpec](../subsystems/storage.md)
+
 Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
 
 ## `ctx.subagents` — `SubagentService`
@@ -2473,6 +2483,8 @@ flush?(): void
 abstract shutdown(): Promise<void>
 ```
 
+Types: [TelemetryRecord](../subsystems/telemetry.md)
+
 Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `ctx.tokenMeter` — `TokenMeterService`
@@ -2885,7 +2897,7 @@ archiveSession(sessionId: SessionId): Promise<void>
 async resolveByPath(path: string): Promise<Workspace | undefined>
 ```
 
-Types: [SessionId](../subsystems/core.md)
+Types: [SessionId](../subsystems/core.md) · [Workspace](../subsystems/workspace.md) · [WorkspaceId](../subsystems/workspace.md)
 
 Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
 
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 8988609cdf..f0df40a866 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
-client-modules.zh.md: 5da7740e4c9272a3516f1a28712be7c95f29a6b3
+client-modules.md: 5dc89a87db7e79e4a297002fa059fdeffcceda20
+client-modules.zh.md: b3aa9c2aecf8e051a41b7b05f05d364b9ff8d2a6
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index bd5ecdc85e..5dc89a87db 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -27,7 +27,7 @@ interface WebBootEntry {
   rev: string
   /** Package-name dependency edges, informational (preflight display / HMR diffing). */
   inject?: string[]
-  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
   immediately?: boolean
 }
 ```
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index 5da7740e4c..b3aa9c2aec 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -27,7 +27,7 @@ interface WebBootEntry {
   rev: string
   /** Package-name dependency edges, informational (preflight display / HMR diffing). */
   inject?: string[]
-  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
   immediately?: boolean
 }
 ```
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 8bf98e026d..a2af261bc6 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 1d0bf6c61500817860dfdd452bddc25adbbeffcc
-core.zh.md: 2b4766dcfcf1901de2bb8a8f9168888a67af7fba
+core.md: 3a8ccbef4163eabba1cd287284eda68135f2db13
+core.zh.md: 0cd6a57971ee98c75b52dd45b6f648632dab8a90
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 1d0bf6c615..3a8ccbef41 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -51,7 +51,6 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
 | [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
 | [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
-| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 2b4766dcfc..0cd6a57971 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -51,7 +51,6 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
-| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 8369b94dac..6f1facfad7 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.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 docs/subsystems/http-server.md
-http-server.md: 565df72f2720a1211f50650d4b1bc8d6df4a007a
-http-server.zh.md: 69e4a0bd7a1576737583625b23fac2ed05d8ca61
+http-server.md: 200d3eed683f203b65824ea3f62cf56ce3df912f
+http-server.zh.md: 9a12d3769a93270810927075be5f236875688b91
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
index 565df72f27..200d3eed68 100644
--- a/docs/subsystems/http-server.md
+++ b/docs/subsystems/http-server.md
@@ -2,7 +2,7 @@
 
 English | [中文](http-server.zh.md)
 
-[dsh-host-webserver](../../packages/host/webserver) is the web-shape HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.httpServer`, a named-route registry plus index.html transform taps over a static dist fallback. It is not part of the agent-loop spine and not a capability seam — it knows no harness concepts, and every feature surface (the `/api` bridge, plugin bundles, the HMR event stream) is a route some other plugin registers ([layering note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). Web (browser) shape only: Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server.
+[dsh-host-webserver](../../packages/host/webserver) is the web-shape HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.httpServer`, a named-route registry, index.html transform taps, and a single claimable fallback seat. It is not part of the agent-loop spine and not a capability seam — it knows no harness concepts, and every feature surface (the `/api` bridge, plugin bundles, the HMR event stream) is a route some other plugin registers ([layering note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). Web (browser) shape only: Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server.
 
 Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
 
@@ -24,23 +24,21 @@ interface WebRoute {
 }
 ```
 
-Match order is fixed: exact table first, then longest matching prefix, then the static dist fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback answers anything not yet claimed during the boot window. The fallback keeps locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream ([`static.ts`](../../packages/host/webserver/src/static.ts)).
+Match order is fixed: exact table first, then longest matching prefix, then the registered fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback seat answers anything no named route claims; one owner only, a second registration throws. The shipped Web composition claims the seat with [`dsh-frontend-static`](../../packages/host/frontend-static/src/index.ts), the SPA dist server with locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream.
 
 ## Config
 
 ```ts type-equiv
-/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+/** Gateway config: the listen address. */
 interface Config {
   /** Listen host; the two supported values are loopback and all-interfaces. */
   host: '127.0.0.1' | '0.0.0.0'
   /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
-  distIndex: string
 }
 ```
 
-`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. `distIndex` is an assembly fact the composing app resolves and injects.
+`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. The dist location is an assembly fact of the frontend plugin that claims the seat.
 
 ## The service
 
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index 69e4a0bd7a..9a12d3769a 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -24,23 +24,21 @@ interface WebRoute {
 }
 ```
 
-匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退遵循固定语义：非 GET/HEAD 返回 405，越出 dist 根目录的遍历返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
+匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到已注册的回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，任何未被具名路由认领的请求都由回退席位应答；席位只有一个所有者，第二次注册会抛出异常。发布的 Web 组合用 [`dsh-frontend-static`](../../packages/host/frontend-static/src/index.ts) 认领席位，即遵循固定语义的 SPA dist 服务器：非 GET/HEAD 返回 405，越出 dist 根目录的遍历返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 发送。
 
 ## 配置
 
 ```ts type-equiv
-/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+/** Gateway config: the listen address. */
 interface Config {
   /** Listen host; the two supported values are loopback and all-interfaces. */
   host: '127.0.0.1' | '0.0.0.0'
   /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
-  distIndex: string
 }
 ```
 
-`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（刻意的网络暴露）；没有 TLS、认证或 origin 策略，因此绑定到非回环地址会把服务器暴露给该网络。`distIndex` 是组合应用解析后注入的组装事实。
+`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（刻意的网络暴露）；没有 TLS、认证或 origin 策略，因此绑定到非回环地址会把服务器暴露给该网络。dist 位置是认领席位的前端插件的组装事实。
 
 ## 服务
 
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index 284f29bb62..c63da5efdc 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
-permission.md: 49dd51ff86d0dbce26fca0ed21527f71bb144dec
-permission.zh.md: c2ab6ecdfb4b80511107bee41e080b06fae45f2c
+permission.md: ec8cd4a923b617934f1612c31284103266aea4ef
+permission.zh.md: 4534c33e2715e4a500344f547c7895128877f4fb
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index 49dd51ff86..ec8cd4a923 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -2,9 +2,9 @@
 
 English | [中文](permission.zh.md)
 
-The permission-preset layer of [dsh-permission](../../packages/ui/permission) (`ctx.permission`, `PermissionService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/ui/permission/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
+The permission-preset layer of [dsh-permission](../../packages/interaction/permission) (`ctx.permission`, `PermissionService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/interaction/permission/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
 
-Source: [`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts`](../../packages/interaction/permission/src/index.ts)
 
 ## The preset table
 
@@ -25,7 +25,7 @@ interface PresetSpec {
 ```
 
 ```ts type-equiv
-/** The {@link PermissionService} config: the deployment's preset table. */
+/** The {@link PermissionService} config: preset table and composition default. */
 interface Config {
   /**
    * The preset table: name → knob bundle. Defaults to `workspace-write`
@@ -33,6 +33,11 @@ interface Config {
    * never). The name `custom` is reserved for the derived not-a-preset state.
    */
   presets?: Record<string, PresetSpec>
+  /**
+   * Default for new sessions. When omitted, the preset matching the composed
+   * sandbox and approval defaults is used.
+   */
+  defaultPreset?: string
 }
 ```
 
@@ -51,13 +56,13 @@ interface PresetOption {
   value: string
   /** The display label. */
   name: string
-  /** One user-facing sentence on what the value means. */
+  /** One user-facing sentence on what the value means; omitted when not configured. */
   description?: string
 }
 ```
 
 ## Switching and the `permission/preset` event
 
-`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/ui/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
+`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
 
 `permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxpermission--permissionservice).
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index c2ab6ecdfb..4534c33e27 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -2,9 +2,9 @@
 
 [English](permission.md) | 中文
 
-[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮（knob），即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
+[dsh-permission](../../packages/interaction/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮（knob），即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/interaction/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
 
-源码：[`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+源码：[`packages/interaction/permission/src/index.ts`](../../packages/interaction/permission/src/index.ts)
 
 ## 预设表
 
@@ -25,7 +25,7 @@ interface PresetSpec {
 ```
 
 ```ts type-equiv
-/** The {@link PermissionService} config: the deployment's preset table. */
+/** The {@link PermissionService} config: preset table and composition default. */
 interface Config {
   /**
    * The preset table: name → knob bundle. Defaults to `workspace-write`
@@ -33,6 +33,11 @@ interface Config {
    * never). The name `custom` is reserved for the derived not-a-preset state.
    */
   presets?: Record<string, PresetSpec>
+  /**
+   * Default for new sessions. When omitted, the preset matching the composed
+   * sandbox and approval defaults is used.
+   */
+  defaultPreset?: string
 }
 ```
 
@@ -51,13 +56,13 @@ interface PresetOption {
   value: string
   /** The display label. */
   name: string
-  /** One user-facing sentence on what the value means. */
+  /** One user-facing sentence on what the value means; omitted when not configured. */
   description?: string
 }
 ```
 
 ## 切换与 `permission/preset` 事件
 
-`set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/ui/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
+`set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/interaction/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
 
 `permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](../cordis-catalog/services.md#ctxpermission--permissionservice)。
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index 3295167755..f82002420b 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: c8bb6c9b6a0bcfd20ed6eadece4552d49f3c757c
-plan.zh.md: c8acedaef0724581227b57afbf81418a7e538aed
+plan.md: 661a393b18f9154771c0b9358ad7f016a4fdec17
+plan.zh.md: 068b63fd9f3bf46b7962031bba154cc7fc7daafd
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index c8bb6c9b6a..661a393b18 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -12,7 +12,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 ## Pending intent and the step-boundary flush
 
-Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — within the same turn when one is open. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
+Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — the next request derivation, in whichever turn it occurs (selection never forces continuation, so an intent recorded after a turn's final step lands in a later turn). `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
 The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index c8acedaef0..068b63fd9f 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -12,7 +12,7 @@
 
 ## 待定意图与步骤边界冲刷
 
-由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——已有轮次开启时即在同一轮次之内。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
+由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——即下一次请求派生，落在哪个轮次就在哪个轮次生效（选择绝不强制续行，因此在某轮最后一步之后记录的意图会在之后的轮次落地）。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
 唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index e97a6f2e27..2eb634bb2d 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: 92235a26fe278dfd6ac2b2ea5703b5c0d837b336
-telemetry.zh.md: e076abd90bd5054ddbfd6fbe7b725ee45d50a038
+telemetry.md: cf570723650c32f048ee797923a58f09c777455d
+telemetry.zh.md: 1bcaa86264e3afd741d66d6ee718946e6151496f
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 92235a26fe..cf57072365 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -2,9 +2,9 @@
 
 English | [中文](telemetry.zh.md)
 
-Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/telemetry/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/telemetry/session-telemetry/README.md).
+Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/session/session-telemetry/README.md).
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
 ## The logical record
 
@@ -12,7 +12,7 @@ Source: [`packages/telemetry/session-telemetry/src/index.ts`](../../packages/tel
 /**
  * Severity of a telemetry record, pre-mapped at capture so a receiver can
  * alert with zero configuration: `error` for events whose own outcome flag
- * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * says so (the tool-result block's `isError`, `turn/end` error reasons) and for
  * `agent-error` operational records. Captured events otherwise default to
  * `info`; `warn` remains available to `telemetry/record` policies and
  * backends.
@@ -69,9 +69,10 @@ interface TelemetryBackend {
   /**
    * Hand one record to the backend's pipeline. MUST be a non-blocking
    * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, so anything slower than a queue push would tax
-   * the agent loop. Errors thrown here are contained by the coordinator and
-   * logged; they never reach the loop.
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   emit(record: TelemetryRecord): void
@@ -96,6 +97,8 @@ interface TelemetryBackend {
    * coordinator emits its dispose-time `shutdown` markers immediately before
    * calling this). Awaited by the coordinator's dispose; a rejection is
    * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
    * @returns resolves when the backend's pipeline has quiesced.
    */
   shutdown(): Promise<void>
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index e076abd90b..1bcaa86264 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -2,9 +2,9 @@
 
 [English](telemetry.md) | 中文
 
-对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/telemetry/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/telemetry/session-telemetry/README.md)。
+对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/session/session-telemetry/README.md)。
 
-源码：[`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
 ## 逻辑记录
 
@@ -12,7 +12,7 @@
 /**
  * Severity of a telemetry record, pre-mapped at capture so a receiver can
  * alert with zero configuration: `error` for events whose own outcome flag
- * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * says so (the tool-result block's `isError`, `turn/end` error reasons) and for
  * `agent-error` operational records. Captured events otherwise default to
  * `info`; `warn` remains available to `telemetry/record` policies and
  * backends.
@@ -69,9 +69,10 @@ interface TelemetryBackend {
   /**
    * Hand one record to the backend's pipeline. MUST be a non-blocking
    * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, so anything slower than a queue push would tax
-   * the agent loop. Errors thrown here are contained by the coordinator and
-   * logged; they never reach the loop.
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   emit(record: TelemetryRecord): void
@@ -96,6 +97,8 @@ interface TelemetryBackend {
    * coordinator emits its dispose-time `shutdown` markers immediately before
    * calling this). Awaited by the coordinator's dispose; a rejection is
    * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
    * @returns resolves when the backend's pipeline has quiesced.
    */
   shutdown(): Promise<void>
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index a50df35f91..6a6488206c 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: bade3526964055d5bf4448265c5898f1e66a1fce
-workspace.zh.md: b0437e42b644c1ce11d9a667972f7b236cf4caa1
+workspace.md: 5614631e828e51f3b515ae4af17451bd9eda1dbb
+workspace.zh.md: 11e8f0207a8db8b7612d6672cfe744523490aef7
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index bade352696..5614631e82 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -68,7 +68,9 @@ interface Workspace {
 
   /**
    * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing. A new id's live or persisted
+   * accounted id resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs. A new id's
+   * live or persisted
    * header cwd must resolve to an existing directory equal to {@link path};
    * unknown ids, missing or invalid cwd values, and mismatches reject without
    * writing.
@@ -82,7 +84,9 @@ interface Workspace {
    * with an anchor the session lands before it, without one it appends to the
    * end. Only the moved id changes position. A session or anchor absent from
    * the account rejects without writing; a move to the current position
-   * resolves without writing (decided on the domain write chain).
+   * resolves without writing, aside from the durable filtered-candidate
+   * prune every accepted mutation performs; decided on the domain write
+   * chain.
    * @param sessionId - The accounted session to move.
    * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
    * @returns resolution after durability.
@@ -91,8 +95,9 @@ interface Workspace {
 
   /**
    * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing (decided on the domain write chain,
-   * like attach). Never touches the session's own stored log.
+   * the account resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs; decided on
+   * the domain write chain like attach. Never touches the session's own stored log.
    * @param sessionId - The session to remove.
    * @returns resolution after durability.
    */
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index b0437e42b6..11e8f0207a 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -68,7 +68,9 @@ interface Workspace {
 
   /**
    * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing. A new id's live or persisted
+   * accounted id resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs. A new id's
+   * live or persisted
    * header cwd must resolve to an existing directory equal to {@link path};
    * unknown ids, missing or invalid cwd values, and mismatches reject without
    * writing.
@@ -82,7 +84,9 @@ interface Workspace {
    * with an anchor the session lands before it, without one it appends to the
    * end. Only the moved id changes position. A session or anchor absent from
    * the account rejects without writing; a move to the current position
-   * resolves without writing (decided on the domain write chain).
+   * resolves without writing, aside from the durable filtered-candidate
+   * prune every accepted mutation performs; decided on the domain write
+   * chain.
    * @param sessionId - The accounted session to move.
    * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
    * @returns resolution after durability.
@@ -91,8 +95,9 @@ interface Workspace {
 
   /**
    * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing (decided on the domain write chain,
-   * like attach). Never touches the session's own stored log.
+   * the account resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs; decided on
+   * the domain write chain like attach. Never touches the session's own stored log.
    * @param sessionId - The session to remove.
    * @returns resolution after durability.
    */
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index 30ef60e8fe..1b6589b6cf 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -152,11 +152,11 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
 
   it('accepts linked, foundation, generic-parameter, and explicitly exempt signature types', () => {
     const events = collectEvents(make(
-      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param assembly - assembly result documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, assembly: PromptAssembly, signal: AbortSignal): Promise<T>',
+      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
     expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
-    expect(renderEvents(events)).not.toContain('[PromptAssembly]')
+    expect(renderEvents(events)).not.toContain('[PresetSpec]')
   })
 
   it('aggregates every unclassified signature type with its source and remediation', () => {
diff --git a/packages/workspace/workspace/README.i18n.yaml b/packages/workspace/workspace/README.i18n.yaml
index 7ba60b4109..63d5ce0e8e 100644
--- a/packages/workspace/workspace/README.i18n.yaml
+++ b/packages/workspace/workspace/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/workspace/workspace/README.md
 README.md: 057765e38de9cc700210eb8edeb1ddc7ffc861ff
-README.zh.md: f3be9611eba45db3719ce76ad6625f4787fab9ac
+README.zh.md: 7416875dbf2ee1652f6e1fa1663144d7407a1ae7
diff --git a/packages/workspace/workspace/README.zh.md b/packages/workspace/workspace/README.zh.md
index f3be9611eb..7416875dbf 100644
--- a/packages/workspace/workspace/README.zh.md
+++ b/packages/workspace/workspace/README.zh.md
@@ -12,6 +12,7 @@ DeepSeek Harness 的 Workspace 实体注册表（`ctx.workspace`）：通过领
 - `ctx.workspace.get(id)`/`list()`/`resolveByPath(path)`：由缓存提供的查找。`list()` 为同步操作，并遵循持久注册表顺序；`resolveByPath` 为异步操作，因为它采用相同的 `realpath` 规范化方式，并会拒绝缺失路径，而不是创建路径。
 - `ctx.workspace.delete(id)`：只移除 Workspace 注册记录、对应的持久顺序条目及会话归属记录。未知 id 返回 `false`，成功移除记录则返回 `true`。目录、用户文件、活跃会话和持久化会话日志绝不受影响，因此相关会话会进入 Ungrouped。表写入失败时会恢复原顺序和此前发布的实体。
 - `Workspace.attachSession(id)`：对照 workspace 路径验证实时或已持久化的会话头 cwd，并将新 id 前置。未知会话、缺失／无法解析／非目录的 cwd 值和不匹配情况都会在不写入的前提下被拒绝。`detachSession` 只移除候选索引条目。
+- `Workspace.insertSessionBefore(id, before?)`：在手动顺序内移动一个已记账的会话，语义类似 DOM 的 insertBefore：插到锚点之前，省略锚点则追加到末尾。会话或锚点不在记账中时拒绝且不写入；移动到当前位置时直接完成且不写入。Workspace 顺序绝不改变。
 - `ctx.workspace.archiveSession(id)`/`archivedSessionIds`：覆盖在 workspace 记账之上的注册表级全局归档集合：被归档的会话从各分组视图中消失，但其会话日志和 `sessionIds` 席位保持不变，未来取消归档时可恢复原位置。归档接受任何实时或已持久化的会话（无论已记账还是 Ungrouped），对已归档的 id 直接完成而不写入，并拒绝未知 id。在该字段出现之前写入的状态解析为一个空集合。
 - `Workspace.sessionIds`：按持久候选顺序提供同步 id 加规范 cwd 成员投影。缺失头部、无效 cwd 值和不匹配情况都被过滤；下一次 workspace 变更会剪除它们。如果同一存储介质将一个会话索引到两个 workspace 下、用两条记录声明同一路径，或偏离持久 workspace 顺序，启动会被拒绝。
 - `Workspace.status()`：未缓存的目录检查，返回 `'ok' | 'missing-dir'`；目录缺失绝不会改动记录。
diff --git a/packages/workspace/workspace/src/types.ts b/packages/workspace/workspace/src/types.ts
index 09d37213cc..555e94d45d 100644
--- a/packages/workspace/workspace/src/types.ts
+++ b/packages/workspace/workspace/src/types.ts
@@ -59,7 +59,9 @@ export interface Workspace {
 
   /**
    * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing. A new id's live or persisted
+   * accounted id resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs. A new id's
+   * live or persisted
    * header cwd must resolve to an existing directory equal to {@link path};
    * unknown ids, missing or invalid cwd values, and mismatches reject without
    * writing.
@@ -73,7 +75,9 @@ export interface Workspace {
    * with an anchor the session lands before it, without one it appends to the
    * end. Only the moved id changes position. A session or anchor absent from
    * the account rejects without writing; a move to the current position
-   * resolves without writing (decided on the domain write chain).
+   * resolves without writing, aside from the durable filtered-candidate
+   * prune every accepted mutation performs; decided on the domain write
+   * chain.
    * @param sessionId - The accounted session to move.
    * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
    * @returns resolution after durability.
@@ -82,8 +86,9 @@ export interface Workspace {
 
   /**
    * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing (decided on the domain write chain,
-   * like attach). Never touches the session's own stored log.
+   * the account resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs; decided on
+   * the domain write chain like attach. Never touches the session's own stored log.
    * @param sessionId - The session to remove.
    * @returns resolution after durability.
    */
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b3fdfb7546..3cc277152e 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,32 +1,25 @@
 /**
- * Generate the Cordis event and service catalogs from static declarations.
- * The walk enforces event modes, JSDoc parameter/return completeness, and
- * signature type-link coverage; inherited Cordis services come from the
- * curated table below. `--check` verifies both committed artifacts.
+ * Generate committed Cordis artifacts from the Typert catalog projector and
+ * the independent vendored-core projector.
  */
 
-import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve, sep } from 'node:path'
-import ts from 'typescript'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import {
+  projectCordisCatalog,
+  renderEvents,
+  renderServices,
+} from '@deepseek-ai/dsh-typert-generator'
+import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
-import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
-import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
+const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** The fenced-block info string for generated signature blocks (skipped by
- * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
-const FENCE = 'ts cordis-catalog'
-
-/**
- * One primary subsystems page per project type used by a generated
- * signature. This stays curated because union names intentionally do not
- * reuse the type-equivalence manifest's map-symbol entries and some symbols
- * appear on more than one page.
- */
-export const LINK_MAP: Record<string, string> = {
+/** One primary subsystems page per project type used by a generated signature. */
+export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
@@ -35,6 +28,7 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  InboxItem: 'core.md',
   InboxPlacement: 'core.md',
   MessageId: 'core.md',
   HookContext: 'core.md',
@@ -57,9 +51,7 @@ export const LINK_MAP: Record<string, string> = {
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
-  PromptDecision: 'core.md',
   RequestErrorAction: 'core.md',
-  RequestError: 'core.md',
   RequestFailureContext: 'core.md',
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
@@ -116,6 +108,7 @@ export const LINK_MAP: Record<string, string> = {
   PreparedLlmCall: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
   StreamChunk: 'llm-streaming.md',
+  SkillProviderControl: 'skills.md',
   CreateSessionOptions: 'persistence.md',
   PrepareSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
@@ -168,9 +161,11 @@ export const LINK_MAP: Record<string, string> = {
   SessionTitleObservationResult: 'session-query.md',
   SessionTitleProvider: 'session-title.md',
   SessionTitleSnapshot: 'session-title.md',
+  SkillCatalogSnapshot: 'skills.md',
   SkillDefinition: 'skills.md',
   SkillLookupOptions: 'skills.md',
   SkillProvider: 'skills.md',
+  SkillProviderObservation: 'skills.md',
   SkillRegistration: 'skills.md',
   SkillSummary: 'skills.md',
   SaveTextSpill: 'spill.md',
@@ -237,8 +232,6 @@ export const LINK_MAP: Record<string, string> = {
   WebSearchRequest: 'web.md',
   WebSearchResult: 'web.md',
   WorkflowRun: 'workflow.md',
-  WorkflowRunInfo: 'workflow.md',
-  WorkflowStartRequest: 'workflow.md',
   PresetOption: 'permission.md',
   PresetSpec: 'permission.md',
   InvariantInstaller: 'invariants.md',
@@ -253,14 +246,17 @@ export const LINK_MAP: Record<string, string> = {
   WorkspaceId: 'workspace.md',
   WebBootGraph: 'client-modules.md',
   TelemetryRecord: 'telemetry.md',
+  WorkflowRunInfo: 'workflow.md',
+  WorkflowStartRequest: 'workflow.md',
 }
 
-/** TypeScript lib and pinned framework types that have no repository-owned data page. */
-const FOUNDATION_TYPE_NAMES = new Set([
+/** TypeScript lib and pinned framework types with no repository-owned data page. */
+export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'AbortSignal',
   'AsyncIterable',
   'Context',
   'Error',
+  'Map',
   'Partial',
   'Pick',
   'Promise',
@@ -269,7 +265,7 @@ const FOUNDATION_TYPE_NAMES = new Set([
 ])
 
 /** Project types deliberately documented outside the subsystems catalog. */
-const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
@@ -281,6 +277,7 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
+  DirectoryPickerCapability: 'picker interaction contract is owned by packages/host/directory-picker/README.md',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
   ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
@@ -318,401 +315,51 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
 }
 
-/** Collect named references from parameter, generic-constraint/default, and return types. */
-function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
-  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
-  const referenced = new Set<string>()
-  const visit = (node: ts.Node): void => {
-    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
-    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
-    ts.forEachChild(node, visit)
-  }
-  for (const parameter of member.typeParameters ?? []) {
-    if (parameter.constraint) visit(parameter.constraint)
-    if (parameter.default) visit(parameter.default)
-  }
-  for (const parameter of member.parameters) {
-    if (parameter.type) visit(parameter.type)
-  }
-  if (member.type) visit(member.type)
-  return [...referenced].filter(name => !declared.has(name)).sort()
+/** Repository data policy consumed by the Cordis catalog projector. */
+export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
+  linkedTypePages: LINK_MAP,
+  foundationTypeNames: FOUNDATION_TYPE_NAMES,
+  typeLinkExemptions: TYPE_LINK_EXEMPTIONS,
+  inheritedEvents: [
+    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
+    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
+    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
+    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
+    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
+    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
+    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+  ],
+  inheritedServices: [
+    { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
+    { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
+    { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
+    { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
+    { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
+    { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
+    { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
+    { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
+  ],
 }
 
-/** Append fail-closed signature type-link violations with actionable ownership choices. */
-function checkTypeLinks(
-  where: string,
-  member: ts.MethodSignature | ts.MethodDeclaration,
-  sf: ts.SourceFile,
-  violations: string[],
-): void {
-  for (const name of signatureTypeNames(member, sf)) {
-    if (Object.hasOwn(LINK_MAP, name)
-      || FOUNDATION_TYPE_NAMES.has(name)
-      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
-    violations.push(
-      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its subsystems page, `
-      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
-      + 'the non-catalog documentation owner.',
-    )
-  }
-}
-
-/** Throw one aggregated diagnostic for every unclassified signature type. */
-function reportTypeLinkViolations(gate: string, violations: string[]): void {
-  if (violations.length === 0) return
-  throw new Error(
-    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
-    + violations.map(violation => `  ${violation}`).join('\n'),
-  )
-}
-
-/** One harness event, extracted from an `interface Events` block. */
-interface EventEntry {
-  /** Scoped name, e.g. `agent/request`. */
-  name: string
-  /** The scope prefix, e.g. `agent` (everything before the first `/`). */
-  scope: string
-  /** Full signature text (the method-signature member, JSDoc stripped). */
-  signature: string
-  /** Original declaration JSDoc, dedented from its containing interface. */
-  jsDoc: string
-  /** Dispatch mode from the `@mode` tag. */
-  mode: Mode
-  /** Description prose (JSDoc minus the `@mode` tag), one line per paragraph. */
-  doc: string
-  /** Source pointer `packages/…/file.ts:line` of the declaration. */
-  source: string
-}
-
-/** One public service method and the source contract attached to it. */
-interface ServiceMethodEntry {
-  /** Public method signature (body stripped). */
-  signature: string
-  /** Original method JSDoc, dedented from its containing class. */
-  jsDoc: string
-}
-
-/** One harness service, extracted from an `interface Context` block. */
-interface ServiceEntry {
-  /** The `ctx.<key>` name, e.g. `llm`. */
-  key: string
-  /** The service class/interface name, e.g. `LlmService`. */
-  type: string
-  /** Whether the service class is abstract (a seam interface). */
-  abstract: boolean
-  /** Class-level JSDoc prose, one line per paragraph. */
-  doc: string
-  /** Public methods (bodies stripped), in source order. */
-  methods: ServiceMethodEntry[]
-  /** Source pointer of the class declaration. */
-  source: string
-}
-
-/** A terse inherited-tier entry (pinned vendor surface). */
-interface InheritedEntry {
-  name: string
-  summary: string
-  /** Source pointer `vendor/…:line`. */
-  source: string
-}
-
-// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts.
-
-/** The signature text of a method-signature member (everything but a body). */
-function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
-  const full = member.getText(sf)
-  const body = (member as { body?: ts.Node }).body
-  const sig = body ? full.slice(0, full.length - body.getText(sf).length) : full
-  return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
-}
-
-/**
- * Copy a node's original JSDoc while removing only the indentation imposed by
- * its containing interface or class.
+/** CLI entry: default writes every artifact; `--check` reports stale files.
+ * @returns nothing; writes files or reports freshness through the process.
  */
-function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
-  const raw = rawJsDoc(text, node)
-  if (!raw) return ''
-  const start = text.lastIndexOf(raw, node.getStart(sf))
-  const { line } = sf.getLineAndCharacterOfPosition(start)
-  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
-  const indent = text.slice(lineStart, start)
-  return raw.split('\n')
-    .map((lineText, index) => index > 0 && lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
-    .join('\n')
-}
-
-/** Walk every harness `interface Events` block and extract its events, hard-
- * erroring (aggregated) on any JSDoc-completeness violation: a missing/
- * contradicted `@mode`, missing description prose, or an undocumented payload
- * parameter. `scanRoot` defaults to the repo root; tests pass a fixture dir. */
-export function collectEvents(scanRoot: string = root): EventEntry[] {
-  const entries: EventEntry[] = []
-  const violations: string[] = []
-  const typeLinkViolations: string[] = []
-  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Events')) continue
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    for (const { name, member } of eventMembers(body, sf)) {
-      const signature = memberSignature(member, sf)
-      const raw = rawJsDoc(text, member)
-      const { doc, mode } = parseJsDoc(raw)
-      const src = pointer(rel, sf, member)
-      const where = `event '${name}' (${src})`
-      checkTypeLinks(where, member, sf, typeLinkViolations)
-      if (!mode) {
-        violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial|bail' to its JSDoc (see AGENTS.md).`)
-      }
-      // Conclusive structural check: a trailing `next: () => …` parameter is a
-      // waterfall. (emit vs parallel vs serial is not structurally
-      // distinguishable, so it is trusted from the tag.)
-      const last = member.parameters.at(-1)
-      const hasNext = !!last && last.name.getText(sf) === 'next'
-      if (mode && hasNext && mode !== 'waterfall') {
-        violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
-      }
-      if (mode && !hasNext && mode === 'waterfall') {
-        violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
-      }
-      if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
-      // Payload parameters need a non-empty @param. The `this` receiver is not
-      // payload, and a waterfall's trailing `next` is covered by its mode.
-      const { params } = parseTags(raw)
-      checkParams(where, 'event', member.parameters, params, sf,
-        p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
-      if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, jsDoc: jsDocText(text, sf, member), mode, doc, source: src })
-    }
-  }
-  reportViolations('gen-cordis-catalog', violations)
-  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
-  return entries
-}
-
-/** Walk every harness `interface Context` block + its service class, hard-
- * erroring (aggregated) on any JSDoc-completeness violation: a class or public
- * method without JSDoc prose, an undocumented parameter, a stale `@param`, a
- * missing `@returns` on a non-void method, or an inferred (unannotated) return
- * type the pure-AST walk cannot classify.
- * `scanRoot` defaults to the repo root; tests pass a fixture dir. */
-export function collectServices(scanRoot: string = root): ServiceEntry[] {
-  const entries: ServiceEntry[] = []
-  const violations: string[] = []
-  const typeLinkViolations: string[] = []
-  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Context')) continue
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    // Resolve each ctx key to its service class (shared walk) and emit an entry.
-    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
-      const methods: ServiceMethodEntry[] = []
-      for (const member of cls.members) {
-        if (!ts.isMethodDeclaration(member)) continue
-        // Only instance methods callable through `ctx.<key>` are surface;
-        // private, protected, and static methods are not.
-        const nonPublic = member.modifiers?.some(m =>
-          m.kind === ts.SyntaxKind.PrivateKeyword
-          || m.kind === ts.SyntaxKind.ProtectedKeyword
-          || m.kind === ts.SyntaxKind.StaticKeyword)
-          || ts.isPrivateIdentifier(member.name)
-        if (nonPublic) continue
-        const memberName = member.name.getText(sf)
-        if (memberName.startsWith('[')) continue // computed/symbol members
-        const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
-        checkTypeLinks(where, member, sf, typeLinkViolations)
-        const raw = rawJsDoc(text, member)
-        methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
-        if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
-        if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
-        const { params, returns } = parseTags(raw)
-        // Every parameter needs a non-empty @param (`this` receiver exempt),
-        // and a non-void ANNOTATED result needs a non-empty @returns — the
-        // shared checkers carry the exact contract.
-        checkParams(where, 'service', member.parameters, params, sf,
-          p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
-        checkReturns(where, member.type, returns, sf, violations)
-      }
-      entries.push({
-        key,
-        type,
-        abstract,
-        doc: clsDoc,
-        methods,
-        source: pointer(rel, sf, cls),
-      })
-    }
-  }
-  reportViolations('gen-cordis-catalog', violations)
-  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
-  return entries.sort((a, b) => a.key.localeCompare(b.key))
-}
-
-/**
- * The inherited tier — cordis core + loader/hmr/timer. Curated, terse, and
- * hand-summarized because (a) it is pinned vendor source that changes only on a
- * deliberate vendor sync, (b) the cordis-core `Context` mixes true ctx members
- * with non-service fields (`root`, `baseUrl`, `logger`) that a blind walk would
- * wrongly surface as services, and (c) the internal/* events carry no JSDoc to
- * render. Source pointers are verified against vendor by `verify-md-links`'
- * sibling check is N/A; keep them current on a vendor bump.
- */
-const INHERITED_EVENTS: InheritedEntry[] = [
-  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
-  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
-  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
-  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
-  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
-  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
-  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
-  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
-  { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
-  { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
-  { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
-  { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
-  { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
-  { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
-  { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
-]
-
-export const INHERITED_SERVICES: InheritedEntry[] = [
-  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
-  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
-  { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
-  { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
-  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
-  { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
-  { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
-  { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
-  { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
-]
-
-/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
-function typeLinks(signature: string): string {
-  const seen = new Set<string>()
-  for (const name of Object.keys(LINK_MAP)) {
-    if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
-  }
-  if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../subsystems/${LINK_MAP[n]})`)
-  return `Types: ${links.join(' · ')}`
-}
-
-/** Render one harness event entry. */
-function renderEvent(e: EventEntry): string[] {
-  const out = [`### \`${e.name}\` — ${e.mode}`, '']
-  if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
-  const links = typeLinks(e.signature)
-  if (links) out.push(links, '')
-  out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
-  return out
-}
-
-/** Render one harness service entry. */
-function renderService(s: ServiceEntry): string[] {
-  const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
-  if (s.doc) out.push(s.doc, '')
-  if (s.methods.length) {
-    const declarations = s.methods.flatMap((method, index) => [
-      ...(index > 0 ? [''] : []),
-      method.jsDoc,
-      method.signature,
-    ])
-    out.push('```' + FENCE, ...declarations, '```', '')
-    const links = typeLinks(s.methods.map(method => method.signature).join('\n'))
-    if (links) out.push(links, '')
-  }
-  out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
-  return out
-}
-
-/** The shared generated-file banner comment. */
-const BANNER = [
-  '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
-  '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
-  '',
-]
-
-/** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
-
-/** Render the events catalog (pure, deterministic given sorted inputs). */
-export function renderEvents(events: EventEntry[]): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Events Catalog',
-    '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
-    '',
-    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`), **bail** (synchronous in-order dispatch until one listener returns a bail value; the scoped input-mutation events use it for an applied/not-applied answer).',
-    '',
-  ]
-  const scopes = [...new Set(events.map(e => e.scope))].sort()
-  for (const scope of scopes) {
-    lines.push(`## \`${scope}/*\``, '')
-    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(...renderEvent(e))
-    }
-  }
-  lines.push(
-    '## Inherited events (cordis core + loader/hmr/timer)',
-    '',
-    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const e of INHERITED_EVENTS) {
-    lines.push(`- \`${e.name}\` — ${e.summary} ([\`${e.source}\`](../../${e.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
-
-/** Render the services catalog (pure, deterministic given sorted inputs). */
-export function renderServices(services: ServiceEntry[]): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Services Catalog',
-    '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
-    '',
-  ]
-  for (const s of services) lines.push(...renderService(s))
-  lines.push(
-    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
-    '',
-    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const s of INHERITED_SERVICES) {
-    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
-
-/** CLI entry: `--write` (default) writes both catalogs, `--check` fails if
- * either is stale. Guarded behind an entry-point check so importing this module
- * for tests neither regenerates the committed files nor calls process.exit. */
-function main(): void {
+export function main(): void {
+  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents(collectEvents())],
-    [OUT_SERVICES, renderServices(collectServices())],
+    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
+    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
+    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -722,9 +369,7 @@ function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
-        // file is not a state this repo produces. Either way the remedy is the
-        // same — regenerate — so treat a read failure as "stale".
+        // Only ENOENT is expected; either read failure has the same remedy.
         committed = null
       }
       if (committed !== content) stale.push(out)
@@ -745,7 +390,4 @@ function main(): void {
   console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
-  main()
-}
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index e1f80b96b6..2bc097c88c 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -199,7 +199,7 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "GoalView",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -219,12 +219,12 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "CreateGoalRequest",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "EditGoalRequest",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -1508,7 +1508,7 @@
     {
       "doc": "docs/subsystems/permission.md",
       "symbol": "PresetOption",
-      "source": "packages/interaction/permission/src/index.ts"
+      "source": "packages/interaction/permission/src/types.ts"
     },
     {
       "doc": "docs/subsystems/plan.md",
@@ -1575,31 +1575,6 @@
       "symbol": "DomainChanged",
       "source": "packages/storage/storage-domain/src/events.ts"
     },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayRequest",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayHost",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlaySession",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayCloseReason",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayOutcome",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
     {
       "doc": "docs/subsystems/workspace.md",
       "symbol": "WorkspaceId",
@@ -1623,17 +1598,17 @@
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetrySeverity",
-      "source": "packages/telemetry/session-telemetry/src/index.ts"
+      "source": "packages/session/session-telemetry/src/index.ts"
     },
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetryRecord",
-      "source": "packages/telemetry/session-telemetry/src/index.ts"
+      "source": "packages/session/session-telemetry/src/index.ts"
     },
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetryBackend",
-      "source": "packages/telemetry/session-telemetry/src/index.ts"
+      "source": "packages/session/session-telemetry/src/index.ts"
     },
     {
       "doc": "docs/subsystems/typert.md",

From f7323354bb9be166620fb47d106afb8abc53c315 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 21:40:58 +0800
Subject: [PATCH 164/262] docs: generate each subsystem's cordis surface into
 its own page; delete the flat catalogs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rebuild of the region machinery (PR3) on the post-#904 Typert projection:
renderPageRegion/renderInheritedPage live in dsh-typert-generator beside the
projection; scripts/gen-cordis-catalog.ts owns the curated SERVICE_PAGE /
EVENT_SCOPE_PAGE / SERVICE_WALK_EXEMPTIONS / LINK_MAP partition (fail-loud in
both directions, with the independent Context-merge scan backstopping the
projection's blind spot), spliceRegion, and the guarded pair auto-record.
docs/cordis-catalog/ is deleted: the flat events/services catalogs dissolve
into per-page regions and docs/cordis-catalog/core moves to docs/cordis-api/
with the inherited tier as its own generated page. The partition absorbs the
post-regrouping surface: ctx.typert → invariants.md, ctx.directoryPicker →
workspace.md, skills/* events → skills.md, and the four launcher-provided tui
accessor values join the named exemptions.
---
 ...bagent-provider-lifecycle-events.i18n.yaml |    4 +-
 ...7-05-subagent-provider-lifecycle-events.md |    2 +-
 ...5-subagent-provider-lifecycle-events.zh.md |    2 +-
 .../2026-07-08-agent-scope-contexts.i18n.yaml |    4 +-
 .../2026-07-08-agent-scope-contexts.md        |    2 +-
 .../2026-07-08-agent-scope-contexts.zh.md     |    2 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |    4 +-
 .../feature/2026-07-05-skill-system.md        |    2 +-
 .../feature/2026-07-05-skill-system.zh.md     |    2 +-
 ...subsystem-cordis-surface-regions.i18n.yaml |    6 +
 ...28-per-subsystem-cordis-surface-regions.md |   36 +
 ...per-subsystem-cordis-surface-regions.zh.md |   36 +
 docs/AGENTS.md                                |    2 +-
 docs/architecture.i18n.yaml                   |    4 +-
 docs/architecture.md                          |    2 +-
 docs/architecture.zh.md                       |    2 +-
 docs/config-catalog.md                        |    2 +-
 .../core => cordis-api}/context.md            |   40 +-
 .../core => cordis-api}/events.md             |   20 +-
 .../core => cordis-api}/fiber.md              |   44 +-
 docs/cordis-api/inherited.md                  |   39 +
 .../core => cordis-api}/registry.md           |    8 +-
 .../core => cordis-api}/service.md            |   18 +-
 docs/cordis-catalog/events.md                 | 1100 -------
 docs/cordis-catalog/services.md               | 2917 -----------------
 docs/cordis-primer.i18n.yaml                  |    4 +-
 docs/cordis-primer.md                         |    2 +-
 docs/cordis-primer.zh.md                      |    2 +-
 docs/cordis-tutorial/03-services.i18n.yaml    |    4 +-
 docs/cordis-tutorial/03-services.md           |    2 +-
 docs/cordis-tutorial/03-services.zh.md        |    2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |    4 +-
 docs/cordis-tutorial/04-events.md             |    4 +-
 docs/cordis-tutorial/04-events.zh.md          |    4 +-
 .../07-into-the-harness.i18n.yaml             |    4 +-
 docs/cordis-tutorial/07-into-the-harness.md   |    2 +-
 .../cordis-tutorial/07-into-the-harness.zh.md |    2 +-
 docs/cordis-tutorial/index.i18n.yaml          |    4 +-
 docs/cordis-tutorial/index.md                 |    2 +-
 docs/cordis-tutorial/index.zh.md              |    2 +-
 docs/graph-atlas.md                           |    2 +-
 docs/i18n/style-samples.md                    |    4 +-
 docs/persistence-catalog.md                   |    2 +-
 docs/subsystems/approval.i18n.yaml            |    4 +-
 docs/subsystems/approval.md                   |   82 +
 docs/subsystems/approval.zh.md                |   82 +
 docs/subsystems/bash.i18n.yaml                |    6 +-
 docs/subsystems/bash.md                       |   82 +
 docs/subsystems/bash.zh.md                    |   82 +
 docs/subsystems/client-modules.i18n.yaml      |    4 +-
 docs/subsystems/client-modules.md             |   57 +-
 docs/subsystems/client-modules.zh.md          |   57 +-
 docs/subsystems/code-runtime.i18n.yaml        |    6 +-
 docs/subsystems/code-runtime.md               |   30 +
 docs/subsystems/code-runtime.zh.md            |   30 +
 docs/subsystems/commands.i18n.yaml            |    4 +-
 docs/subsystems/commands.md                   |   86 +
 docs/subsystems/commands.zh.md                |   86 +
 docs/subsystems/compaction.i18n.yaml          |    4 +-
 docs/subsystems/compaction.md                 |  116 +
 docs/subsystems/compaction.zh.md              |  116 +
 docs/subsystems/core.i18n.yaml                |    4 +-
 docs/subsystems/core.md                       |  546 ++-
 docs/subsystems/core.zh.md                    |  546 ++-
 docs/subsystems/credentials.i18n.yaml         |    4 +-
 docs/subsystems/credentials.md                |   83 +
 docs/subsystems/credentials.zh.md             |   83 +
 docs/subsystems/filesystem.i18n.yaml          |    6 +-
 docs/subsystems/filesystem.md                 |  208 +-
 docs/subsystems/filesystem.zh.md              |  208 +-
 docs/subsystems/goal.i18n.yaml                |    6 +-
 docs/subsystems/goal.md                       |  132 +
 docs/subsystems/goal.zh.md                    |  132 +
 docs/subsystems/http-server.i18n.yaml         |    4 +-
 docs/subsystems/http-server.md                |   61 +
 docs/subsystems/http-server.zh.md             |   61 +
 docs/subsystems/invariants.i18n.yaml          |    4 +-
 docs/subsystems/invariants.md                 |   29 +
 docs/subsystems/invariants.zh.md              |   29 +
 docs/subsystems/llm-streaming.i18n.yaml       |    4 +-
 docs/subsystems/llm-streaming.md              |  188 ++
 docs/subsystems/llm-streaming.zh.md           |  188 ++
 docs/subsystems/permission.i18n.yaml          |    4 +-
 docs/subsystems/permission.md                 |   65 +-
 docs/subsystems/permission.zh.md              |   65 +-
 docs/subsystems/persistence.i18n.yaml         |    4 +-
 docs/subsystems/persistence.md                |  132 +
 docs/subsystems/persistence.zh.md             |  132 +
 docs/subsystems/plan.i18n.yaml                |    4 +-
 docs/subsystems/plan.md                       |   49 +-
 docs/subsystems/plan.zh.md                    |   49 +-
 docs/subsystems/pty.i18n.yaml                 |    6 +-
 docs/subsystems/pty.md                        |   93 +
 docs/subsystems/pty.zh.md                     |   93 +
 docs/subsystems/sandbox.i18n.yaml             |    6 +-
 docs/subsystems/sandbox.md                    |   62 +
 docs/subsystems/sandbox.zh.md                 |   62 +
 docs/subsystems/session-projection.i18n.yaml  |    6 +
 docs/subsystems/session-projection.md         |  262 ++
 docs/subsystems/session-projection.zh.md      |  262 ++
 docs/subsystems/session-query.i18n.yaml       |    6 +-
 docs/subsystems/session-query.md              |  138 +
 docs/subsystems/session-query.zh.md           |  138 +
 docs/subsystems/session-reference.i18n.yaml   |    4 +-
 docs/subsystems/session-reference.md          |   41 +
 docs/subsystems/session-reference.zh.md       |   41 +
 docs/subsystems/session-title.i18n.yaml       |    4 +-
 docs/subsystems/session-title.md              |   58 +
 docs/subsystems/session-title.zh.md           |   58 +
 docs/subsystems/session.i18n.yaml             |    4 +-
 docs/subsystems/session.md                    |  246 +-
 docs/subsystems/session.zh.md                 |  246 +-
 docs/subsystems/settings.i18n.yaml            |    4 +-
 docs/subsystems/settings.md                   |  148 +
 docs/subsystems/settings.zh.md                |  148 +
 docs/subsystems/skills.i18n.yaml              |    4 +-
 docs/subsystems/skills.md                     |   90 +
 docs/subsystems/skills.zh.md                  |   90 +
 docs/subsystems/spill.i18n.yaml               |    6 +-
 docs/subsystems/spill.md                      |   32 +
 docs/subsystems/spill.zh.md                   |   32 +
 docs/subsystems/storage.i18n.yaml             |    4 +-
 docs/subsystems/storage.md                    |  110 +-
 docs/subsystems/storage.zh.md                 |  110 +-
 docs/subsystems/subagent.i18n.yaml            |    6 +-
 docs/subsystems/subagent.md                   |  266 ++
 docs/subsystems/subagent.zh.md                |  266 ++
 docs/subsystems/subprocess.i18n.yaml          |    6 +-
 docs/subsystems/subprocess.md                 |   77 +-
 docs/subsystems/subprocess.zh.md              |   77 +-
 docs/subsystems/system-prompt.i18n.yaml       |    4 +-
 docs/subsystems/system-prompt.md              |  110 +
 docs/subsystems/system-prompt.zh.md           |  110 +
 docs/subsystems/tasks.i18n.yaml               |    6 +-
 docs/subsystems/tasks.md                      |  106 +
 docs/subsystems/tasks.zh.md                   |  106 +
 docs/subsystems/telemetry.i18n.yaml           |    4 +-
 docs/subsystems/telemetry.md                  |   72 +-
 docs/subsystems/telemetry.zh.md               |   72 +-
 docs/subsystems/token-meter.i18n.yaml         |    6 +-
 docs/subsystems/token-meter.md                |   47 +
 docs/subsystems/token-meter.zh.md             |   47 +
 docs/subsystems/tools.i18n.yaml               |    4 +-
 docs/subsystems/tools.md                      |  238 ++
 docs/subsystems/tools.zh.md                   |  238 ++
 docs/subsystems/typert.i18n.yaml              |    6 +-
 docs/subsystems/typert.md                     |   93 +
 docs/subsystems/typert.zh.md                  |   93 +
 docs/subsystems/user-interaction.i18n.yaml    |    4 +-
 docs/subsystems/user-interaction.md           |   44 +
 docs/subsystems/user-interaction.zh.md        |   44 +
 docs/subsystems/web.i18n.yaml                 |    6 +-
 docs/subsystems/web.md                        |   67 +
 docs/subsystems/web.zh.md                     |   67 +
 docs/subsystems/workflow.i18n.yaml            |    6 +-
 docs/subsystems/workflow.md                   |  152 +-
 docs/subsystems/workflow.zh.md                |  152 +-
 docs/subsystems/workspace.i18n.yaml           |    4 +-
 docs/subsystems/workspace.md                  |   95 +-
 docs/subsystems/workspace.zh.md               |   95 +-
 docs/tool-catalog.md                          |    2 +-
 docs/user/develop/framework/events.i18n.yaml  |    4 +-
 docs/user/develop/framework/events.md         |    2 +-
 docs/user/develop/framework/events.zh.md      |    2 +-
 docs/user/develop/framework/service.i18n.yaml |    4 +-
 docs/user/develop/framework/service.md        |    2 +-
 docs/user/develop/framework/service.zh.md     |    2 +-
 packages/core/agent-loop/README.i18n.yaml     |    4 +-
 packages/core/agent-loop/README.md            |    2 +-
 packages/core/agent-loop/README.zh.md         |    2 +-
 packages/core/agent/README.i18n.yaml          |    4 +-
 packages/core/agent/README.md                 |    2 +-
 packages/core/agent/README.zh.md              |    2 +-
 packages/core/session/README.i18n.yaml        |    4 +-
 packages/core/session/README.md               |    2 +-
 packages/core/session/README.zh.md            |    2 +-
 packages/core/system-prompt/README.i18n.yaml  |    4 +-
 packages/core/system-prompt/README.md         |    2 +-
 packages/core/system-prompt/README.zh.md      |    2 +-
 packages/core/tools/README.i18n.yaml          |    4 +-
 packages/core/tools/README.md                 |    4 +-
 packages/core/tools/README.zh.md              |    4 +-
 packages/fs/fs/README.i18n.yaml               |    4 +-
 packages/fs/fs/README.md                      |    2 +-
 packages/fs/fs/README.zh.md                   |    2 +-
 packages/goal/goal/README.i18n.yaml           |    4 +-
 packages/goal/goal/README.md                  |    2 +-
 packages/goal/goal/README.zh.md               |    2 +-
 .../user-approval/README.i18n.yaml            |    4 +-
 packages/interaction/user-approval/README.md  |    2 +-
 .../interaction/user-approval/README.zh.md    |    2 +-
 .../tool-cordis/README.i18n.yaml              |    4 +-
 .../self-modification/tool-cordis/README.md   |    2 +-
 .../tool-cordis/README.zh.md                  |    2 +-
 .../typert/generator/src/cordis-catalog.ts    |  145 +-
 .../tests/cordis-catalog-contract.spec.ts     |   14 +-
 .../generator/tests/cordis-catalog.spec.ts    |   24 +-
 scripts/cordis-core-api.spec.ts               |   14 +-
 scripts/cordis-core-api.ts                    |   14 +-
 scripts/cordis-walk.ts                        |   53 +-
 scripts/gen-config-catalog.ts                 |    2 +-
 scripts/gen-cordis-catalog-record.spec.ts     |  144 +
 scripts/gen-cordis-catalog.ts                 |  378 ++-
 scripts/gen-doc-graphs.ts                     |    2 +-
 scripts/gen-persistence-catalog.ts            |    2 +-
 scripts/gen-tool-catalog.ts                   |    2 +-
 scripts/project-doc-site.spec.ts              |    6 +-
 scripts/project-doc-site.ts                   |    6 +
 scripts/translation-pairing.manifest.json     |    2 +-
 scripts/translation-pairing.spec.ts           |   41 +
 scripts/translation-pairing.ts                |  109 +
 scripts/type-equiv.manifest.json              |   15 +
 scripts/verify-translation-pairing.ts         |   22 +
 website/docs.ts                               |   66 +-
 214 files changed, 10434 insertions(+), 4447 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
 create mode 100644 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
 rename docs/{cordis-catalog/core => cordis-api}/context.md (91%)
 rename docs/{cordis-catalog/core => cordis-api}/events.md (92%)
 rename docs/{cordis-catalog/core => cordis-api}/fiber.md (90%)
 create mode 100644 docs/cordis-api/inherited.md
 rename docs/{cordis-catalog/core => cordis-api}/registry.md (95%)
 rename docs/{cordis-catalog/core => cordis-api}/service.md (82%)
 delete mode 100644 docs/cordis-catalog/events.md
 delete mode 100644 docs/cordis-catalog/services.md
 create mode 100644 docs/subsystems/session-projection.i18n.yaml
 create mode 100644 docs/subsystems/session-projection.md
 create mode 100644 docs/subsystems/session-projection.zh.md
 create mode 100644 scripts/gen-cordis-catalog-record.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml
index efeb9d72f3..336d9669ed 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.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 .agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
-2026-07-05-subagent-provider-lifecycle-events.md: afd45027e8b56cbf1d17e6dec749d8602c81124d
-2026-07-05-subagent-provider-lifecycle-events.zh.md: 01e12946c74fc4fb33c96e047d2030e99b692f47
+2026-07-05-subagent-provider-lifecycle-events.md: 503c0d638785e3a4944c8903b8d7d469c68b1881
+2026-07-05-subagent-provider-lifecycle-events.zh.md: e7d1d8c398a6d77efb2dbccc365e0040f38f2d33
diff --git a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
index afd45027e8..503c0d6387 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
@@ -31,6 +31,6 @@ The events also complete the seam's vocabulary: `ctx.subagents` is a named regis
 ## Consequences
 
 - Consumers deriving state from a named provider react to `subagent/provider-added`/`-removed` instead of reading the registry at `apply` time; `dsh-tool-subagent` is the reference implementation.
-- **Addition fails loud; removal is contained per listener.** An addition listener may unwind registration. Removal runs during disposal, so one throwing listener is logged without starving later mirrors or disrupting teardown. `start()` still resolves the provider by name for every run, preventing stale tools from calling a removed backend. See the [events catalog](../../../../docs/cordis-catalog/events.md) and [producer/consumer map](../../../../docs/event-producer-consumer.md).
+- **Addition fails loud; removal is contained per listener.** An addition listener may unwind registration. Removal runs during disposal, so one throwing listener is logged without starving later mirrors or disrupting teardown. `start()` still resolves the provider by name for every run, preventing stale tools from calling a removed backend. See the [events catalog](../../../../docs/subsystems/subagent.md#cordis-surface) and [producer/consumer map](../../../../docs/event-producer-consumer.md).
 - **A window where the tool is absent.** Between backend disposal and re-registration (an HMR reload), the model sees no subagent tool. This is the honest state — the alternative is a tool that dispatches into nothing — and the tool registry's `tools/change` emit keeps prompt assembly current.
 - **Two waiting fibers sharing a `toolName` is an invalid config caught late.** If two loads of `dsh-tool-subagent` name different providers but the same `toolName`, both wait, and whichever provider arrives first registers; the second registration throws only when ITS provider arrives. `TODO(subagent-dup-toolname)` in the plugin records this blast radius; the tool registry's duplicate-name rejection remains the backstop.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
index 01e12946c7..e7d1d8c398 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
@@ -31,6 +31,6 @@ Status: implemented
 ## 后果
 
 - 从命名提供方派生状态的消费方响应 `subagent/provider-added`/`-removed` 事件，而非在 `apply` 时读取注册表；`dsh-tool-subagent` 是参考实现。
-- **添加时大声失败；移除时按监听器隔离。** 添加监听器可以回滚注册。移除在 disposal 期间运行，因此单个监听器抛异常只会被记录到日志中，不会阻止后续镜像运行或干扰拆解流程。`start()` 仍在每次运行时按名称解析提供方，防止陈旧工具调用已移除的后端。见[事件目录](../../../../docs/cordis-catalog/events.md)与[生产者/消费方映射](../../../../docs/event-producer-consumer.md)。
+- **添加时大声失败；移除时按监听器隔离。** 添加监听器可以回滚注册。移除在 disposal 期间运行，因此单个监听器抛异常只会被记录日志，不会饿死后续镜像或干扰拆解流程。`start()` 仍在每次运行时按名称解析提供方，防止陈旧工具调用已移除的后端。见[事件目录](../../../../docs/subsystems/subagent.md#cordis-surface)与[生产者/消费方映射](../../../../docs/event-producer-consumer.md)。
 - **工具不存在的窗口期。** 在后端 disposal 与重新注册之间（HMR 重载期间），模型看不到 subagent 工具。这是诚实的状态——替代方案是一个向空处分发的工具——工具注册表发出的 `tools/change` 事件会使提示词组装保持最新状态。
 - **两个等待中的 fiber 共享同一 `toolName` 是无效配置，被延迟捕获。** 如果两个 `dsh-tool-subagent` 加载实例分别指定了不同的提供方但相同的 `toolName`，两者都会等待，先到达的提供方先注册；第二次注册仅在其提供方到达时才抛异常。插件中的 `TODO(subagent-dup-toolname)` 记录了这一影响范围；工具注册表的重名拒绝机制仍是最终防线。
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
index cdee6ab259..215f612f5e 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.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 .agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
-2026-07-08-agent-scope-contexts.md: 5e09bdbcae1e57e6b65eb7d1720a6e7a7f758a9f
-2026-07-08-agent-scope-contexts.zh.md: 4714045f28e0386a3a53b53437d063462e75a9f1
+2026-07-08-agent-scope-contexts.md: eb3f6f247bac1a1d81aa2644132c7b9cc04d602c
+2026-07-08-agent-scope-contexts.zh.md: 673dd8578bf545b1f14f3b7e7b89874d804e4ae9
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
index 5e09bdbcae..eb3f6f247b 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
@@ -104,7 +104,7 @@ An event about Agent A normally reaches unscoped listeners and A-scoped listener
 
 At the Cordis level, `Scoped<T>` is an opaque routing receiver. It carries the filter used to choose listeners but is not the domain object. Event signatures therefore keep the real `Agent`, tool execution, approval request, or other subject as an explicit argument that listeners can inspect.
 
-A listener registered with `{ global: true }` deliberately bypasses contextual audience filtering while its cleanup still follows the registering context. Registry-membership notifications remain unfiltered because they describe shared registry state rather than one agent's operation. The generated [event catalog](../../../../docs/cordis-catalog/events.md) is the exhaustive event reference.
+A listener registered with `{ global: true }` deliberately bypasses contextual audience filtering while its cleanup still follows the registering context. Registry-membership notifications remain unfiltered because they describe shared registry state rather than one agent's operation. The exhaustive event reference is the set of generated `cordis-surface` regions across the [subsystem pages](../../../../docs/subsystems/core.md) — each event scope on its owning page (`agent/*` and `agent-loop/*` on core.md itself).
 
 ### Creation publishes last and disposal revokes last
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
index 4714045f28..673dd8578b 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -104,7 +104,7 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 在 Cordis 层面，`Scoped<T>` 是一个不透明的路由接收器。它携带用于选择监听器的过滤器，但本身不是领域对象。因此事件签名将真实的 `Agent`、工具执行、审批请求或其他主体作为显式参数保留，供监听器检查。
 
-以 `{ global: true }` 注册的监听器有意绕过上下文受众过滤，但其清理仍跟随注册上下文。注册表成员变更通知保持不过滤，因为它们描述的是共享注册表状态而非某个 agent 的操作。生成的[事件目录](../../../../docs/cordis-catalog/events.md)是详尽的事件参考。
+以 `{ global: true }` 注册的监听器有意绕过上下文受众过滤，但其清理仍跟随注册上下文。注册表成员变更通知保持不过滤，因为它们描述的是共享注册表状态而非某个 agent 的操作。详尽的事件参考是各[子系统页面](../../../../docs/subsystems/core.md)上生成的 `cordis-surface` 区块的集合——每个事件作用域在其所属页面上（`agent/*` 与 `agent-loop/*` 在 core.md 本页）。
 
 ### 创建最后发布，dispose 最后撤销
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index 6fff14bc85..e0f79bacb0 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: bb7c03a64a3d0d0f700e21bc96633f1c3ea181b9
-2026-07-05-skill-system.zh.md: 8e26e52d3366505a958dd4b19461edf8bf740b00
+2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
+2026-07-05-skill-system.zh.md: 05bd880ecbd46f2b472eb2cc5442f11c07f89b4e
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index bb7c03a64a..5961c535a1 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -28,7 +28,7 @@ Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is lo
 
 The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path.
 
-The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md).
+The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/subsystems/skills.md#cordis-surface).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 8e26e52d33..05bd880ecb 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -28,7 +28,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
+数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
new file mode 100644
index 0000000000..102b0ce5fe
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.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 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
+2026-07-28-per-subsystem-cordis-surface-regions.md: ef65bfc4c7dadd7dafe1a38f41656e6ecc61ea50
+2026-07-28-per-subsystem-cordis-surface-regions.zh.md: 1df18d7260800b89c95a9d4aeb0301adb0ee56f6
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
new file mode 100644
index 0000000000..ef65bfc4c7
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
@@ -0,0 +1,36 @@
+# Agent Note: Per-subsystem generated cordis-surface regions
+
+Status: implemented
+
+English | [中文](2026-07-28-per-subsystem-cordis-surface-regions.zh.md)
+
+## Problem
+
+One subsystem's documentation was split across three homes: its hand-written subsystems page (introduction, data structures, verbs), its `ctx.<key>` slice of the flat generated `docs/cordis-catalog/services.md`, and its event scope's slice of the flat `docs/cordis-catalog/events.md`. A reader of bash.md had to open two more documents to see the service interface and events the page was describing, and nothing tied the three views together beyond hand-maintained links. The flat catalogs also sat outside the bilingual corpus (excluded from pairing because generated output is English-only), so the reference surface had no Chinese route at all.
+
+The [generated-catalog decision](../../archived/process/2026-06-20-generated-cordis-catalog.md) — generate from source, `@mode` tags cross-checked, fail-closed type-link coverage, the `ts cordis-catalog` fence — is not in question; what changed is WHERE the generated output lands.
+
+## Decision
+
+`gen-cordis-catalog.ts` injects each subsystem's service and event reference INTO its own page, between `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` markers, and the flat services/events catalogs are deleted. One page per subsystem now carries introduction, data structures, and the generated wiring surface.
+
+- **Curated fail-loud partition.** `SERVICE_PAGE` maps every discovered `ctx.<key>` to exactly one page; `EVENT_SCOPE_PAGE` maps every event scope. The generator hard-errors in both directions — an unmapped discovered service/scope, and a mapped key/scope the walk no longer discovers — so the partition cannot drift from the source surface. An independent scan of EVERY `declare module 'cordis'` Context merge backstops the rendering walk's blind spot (it only sees a root `index.ts` with a same-named service class): a declared key the walk cannot render must carry a named `SERVICE_WALK_EXEMPTIONS` reason (today: the `ctx.agent` DX accessor, plus the interface-typed or non-index-declared lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost), and stale exemptions hard-error; a `TODO(cordis-catalog-interface-services)` marks teaching the walk to render them.
+- **Byte-identical regions across the pair.** The generator writes the SAME English region bytes into `foo.md` and `foo.zh.md`, extending the existing rule that verbatim code fences match across a pair. `verify-translation-pairing` gained a dedicated region-identity check (`partitionGeneratedRegions` in `translation-pairing.ts` owns the marker grammar) that names a divergent or malformed region precisely; the whole-document structural signature still covers the region content a second time.
+- **Guarded pair auto-record.** A regeneration that changes region bytes would leave every touched pair out-of-sync, so the generator re-records a pair's `.i18n.yaml` itself — but ONLY when the write is region-confined: both sides' recorded blob hashes must match the pre-write bytes, and the region-STRIPPED content must be unchanged on both sides. Human-prose drift leaves the record stale so the pairing gate still forces the normal translation flow; a brand-new pair is never auto-recorded (the author's reviewed `--write` owns that). This keeps `.i18n.yaml` as plain `git hash-object` values — no stripped-hash semantics change.
+- **The inherited tier moved, not died.** The vendor `ctx` members and `internal/*`/loader/hmr/timer events render to `docs/cordis-api/inherited.md`, next to the relocated Cordis core API pages (`docs/cordis-catalog/core/` → `docs/cordis-api/`). Framework surface lives under a framework home; the harness pages stay repository-owned vocabulary.
+- **In-page links.** Signature `Types:` lines link sibling pages (`core.md`, `bash.md`); a type whose primary page is the rendering page is dropped from the line instead of self-linking. Pages reference their own region with `#cordis-surface` or a `#ctx<key>--<class>` anchor — every generated heading is preceded by an explicit `<a id>` carrying the GitHub slug (the historical flat-catalog anchor), so the fragments resolve identically on GitHub and the VitePress site, whose own slugger treats the punctuation-heavy headings differently.
+
+## Alternatives considered
+
+- **Keep the flat catalogs alongside the regions, both generated** — rejected: every JSDoc edit would produce double diff noise, and the scattering (one subsystem, three documents) this change exists to remove would survive.
+- **Generator-owned whole pages with hand-written intros in fragment files** — rejected: the narrative prose is the majority of every existing page and belongs in the reviewed document itself; markers cost one grammar rule and keep authors editing the real file.
+- **Localized regions (generator emits Chinese too)** — deferred, same status as the i18n README's long-standing note for the remaining generated docs: teaching the generator zh output means translating source JSDoc, which is machinery this change does not need. English regions inside zh pages match the existing status quo of English JSDoc inside verbatim fences.
+- **Hashing region-stripped content in `.i18n.yaml`** — rejected: the record would stop being `git hash-object` of the file, breaking the recover-last-confirmed-text property and every consumer that recomputes hashes.
+
+## Consequences
+
+- A subsystem's whole story is one page: `docs/subsystems/<name>.md` (and its pair) carries introduction, data structures/verbs, and the generated service/event surface; `docs/cordis-catalog/` no longer exists.
+- A new service or event scope cannot ship undocumented or unmapped: the generator fails until `SERVICE_PAGE`/`EVENT_SCOPE_PAGE` names its owning page, and the page must already exist with markers in both language sides.
+- Regeneration after a source-JSDoc change touches the affected pages in both languages plus (when region-confined) their pair records — a mechanical, reviewable diff; prose edits keep demanding the translation flow because the auto-record guard refuses them.
+- The website's subsystem nav lists every page (38 routes per locale: 35 translated pairs plus the three still-English-mirrored goal/pty/commands), replacing the two flat catalog nav entries; the Cordis API section gained `inherited.md`.
+- `packages/typert/generator/tests/cordis-catalog-contract.spec.ts` pins the region renderer (`renderPageRegion`), the same-page link-drop rule, and the fail-loud JSDoc/type-link validation; `scripts/translation-pairing.spec.ts` pins the marker grammar and blob-hash primitive; `scripts/gen-cordis-catalog-record.spec.ts` proves the auto-record guard refuses every invalid state (stale record, malformed or renamed-key sidecar, extra entries, prose drift, missing record, missing snapshot).
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
new file mode 100644
index 0000000000..1df18d7260
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 按子系统生成的 cordis-surface 区块
+
+Status: implemented
+
+[English](2026-07-28-per-subsystem-cordis-surface-regions.md) | 中文
+
+## 问题
+
+一个子系统的文档过去分散在三个归属：手写的 subsystems 页面（介绍、数据结构、动词）、平铺生成的 `docs/cordis-catalog/services.md` 中属于它的 `ctx.<key>` 切片，以及平铺的 `docs/cordis-catalog/events.md` 中属于其事件作用域的切片。bash.md 的读者必须再打开两份文档，才能看到该页面正在描述的服务接口与事件；除了手工维护的链接，没有任何机制把这三个视图联系在一起。平铺目录还游离在双语语料之外（生成输出只有英文，故被排除在配对之外），于是这个参考面完全没有中文入口。
+
+[生成式目录决策](../../archived/process/2026-06-20-generated-cordis-catalog.md)本身（从源码生成、`@mode` 标签交叉校验、失败关闭的类型链接覆盖、`ts cordis-catalog` 围栏）不在质疑之列；改变的只是生成输出「落在哪里」。
+
+## 决策
+
+`gen-cordis-catalog.ts` 把每个子系统的服务与事件参考注入到该子系统自己的页面内部，置于 `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` 标记之间；平铺的 services/events 目录随之删除。现在每个子系统由一个页面同时承载介绍、数据结构和生成的接线表面。
+
+- **人工维护、响亮失败的划分。** `SERVICE_PAGE` 把发现的每个 `ctx.<key>` 映射到恰好一个页面；`EVENT_SCOPE_PAGE` 映射每个事件作用域。生成器在两个方向上都会直接报错（既有被发现却未映射的服务或作用域，也有已映射但遍历不再发现的键或作用域），因此划分不可能相对源码表面发生漂移。一个独立扫描会读取每一处 `declare module 'cordis'` 的 Context 合并，为渲染遍历的盲区（它只看得到根 `index.ts` 中同名服务类）兜底：遍历渲染不了的已声明键必须在 `SERVICE_WALK_EXEMPTIONS` 中带着点名理由（目前是 `ctx.agent` 这一 DX 访问器字段，加上接口类型或不在 index 声明的 lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost），陈旧豁免同样直接报错；教会遍历渲染它们的后续工作由 `TODO(cordis-catalog-interface-services)` 标记。
+- **区块在配对两侧按字节一致。** 生成器把同一份英文区块字节写入 `foo.md` 和 `foo.zh.md`，是对「围栏代码块在配对两侧逐字节一致」这一既有规则的延伸。`verify-translation-pairing` 新增了专门的区块一致性检查（标记语法归 `translation-pairing.ts` 中的 `partitionGeneratedRegions` 所有），能精确点名出现分歧或格式错误的区块；整篇文档的结构签名仍会把区块内容再覆盖一遍。
+- **带防护的配对自动记录。** 一次改变区块字节的重新生成会让每个被触及的配对失去同步，因此生成器会自行重新记录配对的 `.i18n.yaml`，但仅限本次写入完全限定在区块内的情况：两侧记录的 blob hash 必须与写入前的字节相符，且两侧剥离区块后的内容必须没有变化。人工行文若有漂移，记录就保持陈旧，配对门禁因此仍会强制走正常翻译流程；全新的配对绝不自动记录（那归作者经评审的 `--write` 所有）。这样 `.i18n.yaml` 保持为纯粹的 `git hash-object` 值：不引入任何「剥离后 hash」的语义变化。
+- **继承层搬了家，而非消亡。** vendor 的 `ctx` 成员与 `internal/*`/loader/hmr/timer 事件渲染到 `docs/cordis-api/inherited.md`，紧邻迁移后的 Cordis 核心 API 页面（`docs/cordis-catalog/core/` → `docs/cordis-api/`）。框架表面落在框架自己的归属之下；harness 页面仍是仓库自有的词汇。
+- **页内链接。** 签名的 `Types:` 行链接到兄弟页面（`core.md`、`bash.md`）；若某个类型的主要页面就是正在渲染的页面，该类型会从该行去掉，而不是链接到自身。页面用 `#cordis-surface` 或 `#ctx<key>--<class>` 锚点引用自己的区块：每个生成标题前都有一个显式 `<a id>`，携带 GitHub slug（即平铺目录时期的历史锚点），因此这些片段在 GitHub 与 VitePress 站点上解析一致——后者自带的 slugger 对含大量标点的标题会得出不同结果。
+
+## 曾考虑的替代方案
+
+- **平铺目录与区块并存、两者都生成**：否决。每次 JSDoc 编辑都会产生双份 diff 噪音，而本次变更本要消除的分散状况（一个子系统、三份文档）也将延续。
+- **整页归生成器所有、手写介绍放进片段文件**：否决。叙述性行文占每个现有页面的大部分，应当留在被评审的文档本身；标记只花一条语法规则的成本，还让作者继续编辑真实文件。
+- **本地化区块（生成器同时输出中文）**：推迟，与 i18n README 中针对其余生成文档的长期备注同属一个状态：教会生成器输出中文意味着要翻译源码 JSDoc，而那是本次变更并不需要的机制。zh 页面里的英文区块，与「英文 JSDoc 出现在逐字节一致的围栏代码块内」这一既有现状相符。
+- **在 `.i18n.yaml` 中对剥离区块后的内容做 hash**：否决。记录将不再是文件的 `git hash-object`，这会破坏「还原上次确认文本」的性质，也会破坏每个自行重算 hash 的消费方。
+
+## 后果
+
+- 一个子系统的完整故事就在一个页面上：`docs/subsystems/<name>.md`（及其配对文件）承载介绍、数据结构／动词，以及生成的服务／事件表面；`docs/cordis-catalog/` 不复存在。
+- 新的服务或事件作用域无法在未记录、未映射的状态下落地：在 `SERVICE_PAGE`/`EVENT_SCOPE_PAGE` 点名其所属页面之前，生成器一直失败，而且该页面必须已经存在，并在两个语言侧都带有标记。
+- 源码 JSDoc 变更后的重新生成会触及两种语言的受影响页面，外加（当写入限定在区块内时）它们的配对记录：一份机械、可评审的 diff。行文编辑仍然要走翻译流程，因为自动记录防护会拒绝它们。
+- 网站的子系统导航列出每个页面（每个 locale 38 条路由：35 个已翻译配对，加上仍为英文镜像的 goal/pty/commands 三页），取代两个平铺目录导航项；Cordis API 一节新增 `inherited.md`。
+- `packages/typert/generator/tests/cordis-catalog-contract.spec.ts` 固定区块渲染器（`renderPageRegion`）、同页链接去除规则，以及响亮失败的 JSDoc 与类型链接校验；`scripts/translation-pairing.spec.ts` 固定标记语法与 blob hash 原语；`scripts/gen-cordis-catalog-record.spec.ts` 证明自动重录守卫拒绝每一种非法状态（陈旧记录、格式错误或键被改名的伴随记录、多余条目、行文漂移、记录缺失、快照缺失）。
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 488a7a1dd6..5194544f95 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -28,7 +28,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
 | Package README | Per-package config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc or catalog restatement, other packages' concerns |
 | [development.md](development.md) | Contributor onboarding: setup, daily workflow, and CI shape at summary level | Runtime rationale (→ Agent Notes), drifting gate inventories |
-| Generated catalogs: [cordis events](cordis-catalog/events.md), [cordis services](cordis-catalog/services.md), [Cordis core API](cordis-catalog/core/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/core.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind (regions included) |
 | Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
 
 ## Writing rules
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 15a6ba3fb5..2436ff9027 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 7baf550128fe83528ce12bf2f9b40cfc8f78e322
-architecture.zh.md: 076edd0549fb7f648a7a1b06d7027a1e6eca735f
+architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
+architecture.zh.md: 5780d54aad6085ef7811dfa94377a4c2478bfb99
diff --git a/docs/architecture.md b/docs/architecture.md
index 7baf550128..f593ee5c54 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -53,7 +53,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 
 ## Event
 
-Events are the service extension API ([catalog](cordis-catalog/events.md), [producer/consumer map](event-producer-consumer.md)).
+Events are the service extension API ([subsystems](subsystems/core.md), [producer/consumer map](event-producer-consumer.md)).
 
 ### Event Domains
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 076edd0549..5780d54aad 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -53,7 +53,7 @@
 
 ## 事件
 
-事件就是服务的扩展 API（[目录](cordis-catalog/events.md)、[生产方与消费方映射](event-producer-consumer.md)）。
+事件就是服务的扩展 API（[子系统](subsystems/core.md)、[生产方与消费方映射](event-producer-consumer.md)）。
 
 ### 事件域
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 850f4731e2..eb4472d629 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -3,7 +3,7 @@
 
 # Plugin Config Catalog
 
-Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
+Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
 
 This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.
 
diff --git a/docs/cordis-catalog/core/context.md b/docs/cordis-api/context.md
similarity index 91%
rename from docs/cordis-catalog/core/context.md
rename to docs/cordis-api/context.md
index c0c1690c8f..320b23de1c 100644
--- a/docs/cordis-catalog/core/context.md
+++ b/docs/cordis-api/context.md
@@ -9,7 +9,7 @@ Root and child dependency containers for Cordis plugins.
 
 A context is a proxy: normal property reads go through the service resolver, while `extend()`, `isolate()`, and `intercept()` create scoped child contexts without mutating their parent.
 
-[Source](../../../vendor/cordis/src/context.ts#L42)
+[Source](../../vendor/cordis/src/context.ts#L42)
 
 ### ctx.extend(meta?)
 
@@ -34,7 +34,7 @@ The child prototypally inherits every property of this context; own properties o
 
 **Returns** a child context inheriting from this one.
 
-[Source](../../../vendor/cordis/src/context.ts#L99)
+[Source](../../vendor/cordis/src/context.ts#L99)
 
 ### ctx.isolate(name, label?)
 
@@ -63,7 +63,7 @@ Below the returned context, reads and writes of the service `name` resolve again
 
 **Returns** a child context whose `name` service resolves in the new scope.
 
-[Source](../../../vendor/cordis/src/context.ts#L121)
+[Source](../../vendor/cordis/src/context.ts#L121)
 
 ### ctx.intercept(name, config)
 
@@ -93,7 +93,7 @@ Plugins loaded under the returned context see `config` merged into the service's
 
 **Returns** a child context carrying the additional intercept entry.
 
-[Source](../../../vendor/cordis/src/context.ts#L139)
+[Source](../../vendor/cordis/src/context.ts#L139)
 
 ### ctx.root
 
@@ -104,7 +104,7 @@ root: this
 
 The root context of the application (every child context shares it). @experimental
 
-[Source](../../../vendor/cordis/src/context.ts#L22)
+[Source](../../vendor/cordis/src/context.ts#L22)
 
 ### ctx.baseUrl
 
@@ -115,7 +115,7 @@ baseUrl?: string
 
 Base URL used to resolve relative plugin/module specifiers, if the runtime sets one.
 
-[Source](../../../vendor/cordis/src/context.ts#L24)
+[Source](../../vendor/cordis/src/context.ts#L24)
 
 ### ctx.events
 
@@ -126,7 +126,7 @@ events: EventsService
 
 The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...).
 
-[Source](../../../vendor/cordis/src/context.ts#L26)
+[Source](../../vendor/cordis/src/context.ts#L26)
 
 ### ctx.logger
 
@@ -137,7 +137,7 @@ logger: LoggerService
 
 The logging service. Call `ctx.logger(name)` for a named logger.
 
-[Source](../../../vendor/cordis/src/context.ts#L28)
+[Source](../../vendor/cordis/src/context.ts#L28)
 
 ### ctx.reflect
 
@@ -148,7 +148,7 @@ reflect: ReflectService
 
 The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...).
 
-[Source](../../../vendor/cordis/src/context.ts#L30)
+[Source](../../vendor/cordis/src/context.ts#L30)
 
 ### ctx.registry
 
@@ -159,7 +159,7 @@ registry: RegistryService
 
 The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`).
 
-[Source](../../../vendor/cordis/src/context.ts#L32)
+[Source](../../vendor/cordis/src/context.ts#L32)
 
 ## Static members
 
@@ -172,7 +172,7 @@ static readonly effect: unique symbol
 
 Symbol key under which a disposer exposes its EffectMeta diagnostics tree.
 
-[Source](../../../vendor/cordis/src/context.ts#L44)
+[Source](../../vendor/cordis/src/context.ts#L44)
 
 ### Context.filter
 
@@ -183,7 +183,7 @@ static readonly filter: unique symbol
 
 Symbol key for a context's listener filter, consulted on every event dispatch.
 
-[Source](../../../vendor/cordis/src/context.ts#L46)
+[Source](../../vendor/cordis/src/context.ts#L46)
 
 ### Context.isolate
 
@@ -194,7 +194,7 @@ static readonly isolate: unique symbol
 
 Symbol key of the isolation map (see the `Context[symbols.isolate]` property).
 
-[Source](../../../vendor/cordis/src/context.ts#L48)
+[Source](../../vendor/cordis/src/context.ts#L48)
 
 ### Context.intercept
 
@@ -205,7 +205,7 @@ static readonly intercept: unique symbol
 
 Symbol key of the intercept map (see the `Context[symbols.intercept]` property).
 
-[Source](../../../vendor/cordis/src/context.ts#L50)
+[Source](../../vendor/cordis/src/context.ts#L50)
 
 ### Context.is(value)
 
@@ -230,7 +230,7 @@ Works across realms and across multiple copies of cordis, because the brand is k
 
 **Returns** `true` if `value` is a Cordis context, narrowing its type.
 
-[Source](../../../vendor/cordis/src/context.ts#L61)
+[Source](../../vendor/cordis/src/context.ts#L61)
 
 ## Service store and mixins
 
@@ -256,7 +256,7 @@ Read a service from the store without the inject requirement.
 
 **Returns** the service value, or `undefined` when not (yet) provided.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L17)
+[Source](../../vendor/cordis/src/reflect.ts#L17)
 
 ### ctx.set(name, value)
 
@@ -281,7 +281,7 @@ Only the fiber that provided the service may set it; setting an unprovided name
 - `name` — the service name.
 - `value` — the new service value.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L29)
+[Source](../../vendor/cordis/src/reflect.ts#L29)
 
 ### ctx.provide(name, value)
 
@@ -311,7 +311,7 @@ The service becomes visible to dependents in the same isolation scope once the f
 
 **Returns** a disposer that unregisters the service.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L44)
+[Source](../../vendor/cordis/src/reflect.ts#L44)
 
 ### ctx.accessor(name, options)
 
@@ -335,7 +335,7 @@ The accessor is removed when the current fiber unloads. Throws if the name is al
 - `name` — the context property name.
 - `options` — the `get` hook and optional `set` hook.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L56)
+[Source](../../vendor/cordis/src/reflect.ts#L56)
 
 ### ctx.mixin(name, mixins)
 
@@ -361,4 +361,4 @@ Each mixed-in key becomes an accessor that forwards to the service (binding meth
 - `name` — the context property holding the source service.
 - `mixins` — keys to forward, or a source-key → ctx-key map.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L67)
+[Source](../../vendor/cordis/src/reflect.ts#L67)
diff --git a/docs/cordis-catalog/core/events.md b/docs/cordis-api/events.md
similarity index 92%
rename from docs/cordis-catalog/core/events.md
rename to docs/cordis-api/events.md
index 68cd109e8e..8b8eb2358e 100644
--- a/docs/cordis-catalog/core/events.md
+++ b/docs/cordis-api/events.md
@@ -3,7 +3,7 @@
 
 # Events
 
-The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated separately in the [Cordis events catalog](../events.md).
+The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated into each owning [subsystem page](../subsystems/core.md).
 
 ### ctx.parallel(name, ...args)
 
@@ -26,7 +26,7 @@ Dispatch an event, running all listeners concurrently.
 
 **Returns** a promise resolving once every listener has settled.
 
-[Source](../../../vendor/cordis/src/events.ts#L44)
+[Source](../../vendor/cordis/src/events.ts#L44)
 
 ### ctx.emit(name, ...args)
 
@@ -46,7 +46,7 @@ Dispatch an event synchronously, ignoring listener return values.
 - `name` — the event name.
 - `args` — arguments passed to every listener.
 
-[Source](../../../vendor/cordis/src/events.ts#L53)
+[Source](../../vendor/cordis/src/events.ts#L53)
 
 ### ctx.serial(name, ...args)
 
@@ -69,7 +69,7 @@ Dispatch an event, awaiting listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](../../../vendor/cordis/src/events.ts#L63)
+[Source](../../vendor/cordis/src/events.ts#L63)
 
 ### ctx.bail(name, ...args)
 
@@ -92,7 +92,7 @@ Dispatch an event, calling listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](../../../vendor/cordis/src/events.ts#L73)
+[Source](../../vendor/cordis/src/events.ts#L73)
 
 ### ctx.waterfall(name, ...args)
 
@@ -120,7 +120,7 @@ Each listener wraps the rest of the chain: calling `next()` invokes the next lis
 
 **Returns** the outermost listener's return value.
 
-[Source](../../../vendor/cordis/src/events.ts#L86)
+[Source](../../vendor/cordis/src/events.ts#L86)
 
 ### ctx.on(name, listener, options?)
 
@@ -144,7 +144,7 @@ Register an event listener owned by the current fiber.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](../../../vendor/cordis/src/events.ts#L97)
+[Source](../../vendor/cordis/src/events.ts#L97)
 
 ### ctx.once(name, listener, options?)
 
@@ -168,7 +168,7 @@ Same as `on()`, but the listener disposes itself after its first call.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](../../../vendor/cordis/src/events.ts#L106)
+[Source](../../vendor/cordis/src/events.ts#L106)
 
 ## EventOptions
 
@@ -184,7 +184,7 @@ interface EventOptions {
 }
 ```
 
-[Source](../../../vendor/cordis/src/events.ts#L112)
+[Source](../../vendor/cordis/src/events.ts#L112)
 
 ## DispatchMode
 
@@ -204,4 +204,4 @@ Event dispatch strategy used by the event service.
 type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
 ```
 
-[Source](../../../vendor/cordis/src/events.ts#L32)
+[Source](../../vendor/cordis/src/events.ts#L32)
diff --git a/docs/cordis-catalog/core/fiber.md b/docs/cordis-api/fiber.md
similarity index 90%
rename from docs/cordis-catalog/core/fiber.md
rename to docs/cordis-api/fiber.md
index 35a991f789..36d2861ac6 100644
--- a/docs/cordis-catalog/core/fiber.md
+++ b/docs/cordis-api/fiber.md
@@ -34,7 +34,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L420)
+[Source](../../vendor/cordis/src/fiber.ts#L420)
 
 ### ctx.fiber
 
@@ -45,7 +45,7 @@ fiber: Fiber
 
 The fiber (plugin runtime instance) that owns this context.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L12)
+[Source](../../vendor/cordis/src/fiber.ts#L12)
 
 ## The Fiber class
 
@@ -53,7 +53,7 @@ Runtime instance of one plugin application.
 
 A fiber tracks dependency state, validated config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L184)
+[Source](../../vendor/cordis/src/fiber.ts#L184)
 
 ### fiber.uid
 
@@ -64,7 +64,7 @@ public uid: number | null
 
 Unique id within the registry; 0 for the root fiber, `null` once disposed.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L186)
+[Source](../../vendor/cordis/src/fiber.ts#L186)
 
 ### fiber.ctx
 
@@ -75,7 +75,7 @@ public readonly ctx: Context
 
 The context this fiber's plugin runs in (extends the parent context).
 
-[Source](../../../vendor/cordis/src/fiber.ts#L188)
+[Source](../../vendor/cordis/src/fiber.ts#L188)
 
 ### fiber.config
 
@@ -86,7 +86,7 @@ public config: any
 
 The validated plugin config (updated by `update()`).
 
-[Source](../../../vendor/cordis/src/fiber.ts#L190)
+[Source](../../vendor/cordis/src/fiber.ts#L190)
 
 ### fiber.state
 
@@ -97,7 +97,7 @@ public state
 
 Current lifecycle state; transitions emit `internal/status`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L192)
+[Source](../../vendor/cordis/src/fiber.ts#L192)
 
 ### fiber.dispose
 
@@ -108,7 +108,7 @@ public readonly dispose: () => Promise<void>
 
 Dispose this fiber: unload the plugin, then settle once cleanup finished.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L194)
+[Source](../../vendor/cordis/src/fiber.ts#L194)
 
 ### fiber.store
 
@@ -119,7 +119,7 @@ public store: Dict<Impl> | undefined
 
 Snapshot of required service implementations while loaded; `undefined` otherwise.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L196)
+[Source](../../vendor/cordis/src/fiber.ts#L196)
 
 ### fiber.inertia
 
@@ -130,7 +130,7 @@ public inertia: Promise<void> | undefined
 
 The in-flight load/unload transition, if one is currently running.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L198)
+[Source](../../vendor/cordis/src/fiber.ts#L198)
 
 ### fiber.name
 
@@ -141,7 +141,7 @@ get name()
 
 The plugin's display name, inherited from the nearest named ancestor, else `'root'`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L341)
+[Source](../../vendor/cordis/src/fiber.ts#L341)
 
 ### fiber.assertActive()
 
@@ -159,7 +159,7 @@ Throw if the fiber has already been disposed.
 
 **Returns** nothing when the fiber is still active.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L356)
+[Source](../../vendor/cordis/src/fiber.ts#L356)
 
 ### fiber.effect(execute, label?)
 
@@ -190,7 +190,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L420)
+[Source](../../vendor/cordis/src/fiber.ts#L420)
 
 ### fiber.getEffects()
 
@@ -207,7 +207,7 @@ Return metadata for currently registered effects.
 
 **Returns** one `EffectMeta` tree per labeled live effect.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L573)
+[Source](../../vendor/cordis/src/fiber.ts#L573)
 
 ### fiber.await()
 
@@ -225,7 +225,7 @@ Wait for current lifecycle work and rethrow startup errors.
 
 **Returns** this fiber, once it has settled into a stable state.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L702)
+[Source](../../vendor/cordis/src/fiber.ts#L702)
 
 ### fiber.restart()
 
@@ -243,7 +243,7 @@ Dispose and immediately reload this plugin with its current config.
 
 **Returns** a promise resolving once the reload settled.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L716)
+[Source](../../vendor/cordis/src/fiber.ts#L716)
 
 ### fiber.update(config, noSave?)
 
@@ -271,7 +271,7 @@ Runs the `internal/update` waterfall first, so update hooks (and HMR) can veto o
 
 **Returns** the update waterfall result; the default restart returns a promise.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L734)
+[Source](../../vendor/cordis/src/fiber.ts#L734)
 
 ## Effect
 
@@ -292,7 +292,7 @@ type Effect<T = any> =
   | AsyncEffect<T>
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L83)
+[Source](../../vendor/cordis/src/fiber.ts#L83)
 
 ## Disposable
 
@@ -310,7 +310,7 @@ Disposers run in reverse registration order when the owning fiber unloads; they
 type Disposable<T = any> = () => T
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L74)
+[Source](../../vendor/cordis/src/fiber.ts#L74)
 
 ## EffectMeta
 
@@ -326,7 +326,7 @@ interface EffectMeta {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L96)
+[Source](../../vendor/cordis/src/fiber.ts#L96)
 
 ## CordisError
 
@@ -352,7 +352,7 @@ namespace CordisError {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L157)
+[Source](../../vendor/cordis/src/fiber.ts#L157)
 
 ## ValidationError
 
@@ -372,4 +372,4 @@ class ValidationError extends TypeError {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L19)
+[Source](../../vendor/cordis/src/fiber.ts#L19)
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
new file mode 100644
index 0000000000..5582bdd1ac
--- /dev/null
+++ b/docs/cordis-api/inherited.md
@@ -0,0 +1,39 @@
+<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
+     Run `pnpm run gen-cordis-catalog` to regenerate. -->
+
+# Inherited Cordis Surface
+
+The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
+
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
+
+## Inherited `ctx` members (cordis core + loader/hmr/timer)
+
+- `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
+- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
+- `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:164`](../../vendor/cordis/src/registry.ts))
+- `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
+- `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
+- `ctx.extend / ctx.isolate / ctx.intercept` — Derive a child context (scoped services / isolation / interception). ([`vendor/cordis/src/context.ts:42`](../../vendor/cordis/src/context.ts))
+- `ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger` — Ambient handles onto the running context graph. ([`vendor/cordis/src/context.ts:16`](../../vendor/cordis/src/context.ts))
+- `ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)` — Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick). ([`vendor/timer/src/index.ts:4`](../../vendor/timer/src/index.ts))
+- `ctx.loader` — The config Loader that booted the app (present under the loader). ([`vendor/loader/src/index.ts:30`](../../vendor/loader/src/index.ts))
+- `ctx.hmr` — The hot-module-reload watcher (present under the hmr plugin). ([`vendor/hmr/src/index.ts:15`](../../vendor/hmr/src/index.ts))
+
+## Inherited events (cordis core + loader/hmr/timer)
+
+- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:328`](../../vendor/cordis/src/events.ts))
+- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:330`](../../vendor/cordis/src/events.ts))
+- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:332`](../../vendor/cordis/src/events.ts))
+- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:334`](../../vendor/cordis/src/events.ts))
+- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:336`](../../vendor/cordis/src/events.ts))
+- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:338`](../../vendor/cordis/src/events.ts))
+- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
+- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
+- `hmr/change` — A watched source file changed on disk. ([`vendor/hmr/src/index.ts:20`](../../vendor/hmr/src/index.ts))
+- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:21`](../../vendor/hmr/src/index.ts))
+- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
+- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
+- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
+- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
+- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-catalog/core/registry.md b/docs/cordis-api/registry.md
similarity index 95%
rename from docs/cordis-catalog/core/registry.md
rename to docs/cordis-api/registry.md
index 6b2e298c72..e6ddce5700 100644
--- a/docs/cordis-catalog/core/registry.md
+++ b/docs/cordis-api/registry.md
@@ -30,7 +30,7 @@ Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloade
 
 **Returns** the fiber; awaiting it settles once loading finished.
 
-[Source](../../../vendor/cordis/src/registry.ts#L176)
+[Source](../../vendor/cordis/src/registry.ts#L176)
 
 ### ctx.plugin(plugin, ...args)
 
@@ -53,7 +53,7 @@ Load a plugin in the current context.
 
 **Returns** the fiber; awaiting it settles once loading finished (rejecting on config or startup errors).
 
-[Source](../../../vendor/cordis/src/registry.ts#L185)
+[Source](../../vendor/cordis/src/registry.ts#L185)
 
 ## Plugin
 
@@ -118,7 +118,7 @@ namespace Plugin {
 }
 ```
 
-[Source](../../../vendor/cordis/src/registry.ts#L92)
+[Source](../../vendor/cordis/src/registry.ts#L92)
 
 ## Inject
 
@@ -149,4 +149,4 @@ namespace Inject {
 }
 ```
 
-[Source](../../../vendor/cordis/src/registry.ts#L19)
+[Source](../../vendor/cordis/src/registry.ts#L19)
diff --git a/docs/cordis-catalog/core/service.md b/docs/cordis-api/service.md
similarity index 82%
rename from docs/cordis-catalog/core/service.md
rename to docs/cordis-api/service.md
index 84b74f98df..d4b0f06da1 100644
--- a/docs/cordis-catalog/core/service.md
+++ b/docs/cordis-api/service.md
@@ -9,7 +9,7 @@ Base class for services that expose a named API on `ctx`.
 
 Subclasses call `super(ctx, name)` from their constructor. The service is registered immediately and is automatically removed with the owning fiber.
 
-[Source](../../../vendor/cordis/src/service.ts#L11)
+[Source](../../vendor/cordis/src/service.ts#L11)
 
 ### service.name
 
@@ -20,7 +20,7 @@ public name!: string
 
 The service name this instance is registered under.
 
-[Source](../../../vendor/cordis/src/service.ts#L30)
+[Source](../../vendor/cordis/src/service.ts#L30)
 
 ## Static members
 
@@ -33,7 +33,7 @@ static readonly init: unique symbol
 
 Symbol key of an instance method run after construction (class plugins).
 
-[Source](../../../vendor/cordis/src/service.ts#L13)
+[Source](../../vendor/cordis/src/service.ts#L13)
 
 ### Service.check
 
@@ -44,7 +44,7 @@ static readonly check: unique symbol
 
 Symbol key of the availability predicate passed to `ctx.provide()`.
 
-[Source](../../../vendor/cordis/src/service.ts#L15)
+[Source](../../vendor/cordis/src/service.ts#L15)
 
 ### Service.config
 
@@ -55,7 +55,7 @@ static readonly config: unique symbol
 
 Symbol key of the phantom intercept-config type parameter.
 
-[Source](../../../vendor/cordis/src/service.ts#L17)
+[Source](../../vendor/cordis/src/service.ts#L17)
 
 ### Service.invoke
 
@@ -66,7 +66,7 @@ static readonly invoke: unique symbol
 
 Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
 
-[Source](../../../vendor/cordis/src/service.ts#L19)
+[Source](../../vendor/cordis/src/service.ts#L19)
 
 ### Service.extend
 
@@ -77,7 +77,7 @@ static readonly extend: unique symbol
 
 Symbol key of the helper deriving an extended service instance.
 
-[Source](../../../vendor/cordis/src/service.ts#L21)
+[Source](../../vendor/cordis/src/service.ts#L21)
 
 ### Service.tracker
 
@@ -88,7 +88,7 @@ static readonly tracker: unique symbol
 
 Symbol key of the tracker metadata used for context tracing.
 
-[Source](../../../vendor/cordis/src/service.ts#L23)
+[Source](../../vendor/cordis/src/service.ts#L23)
 
 ### Service.resolveConfig
 
@@ -99,4 +99,4 @@ static readonly resolveConfig: unique symbol
 
 Symbol key of the intercept-config resolution helper below.
 
-[Source](../../../vendor/cordis/src/service.ts#L25)
+[Source](../../vendor/cordis/src/service.ts#L25)
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
deleted file mode 100644
index fb05eaa8e6..0000000000
--- a/docs/cordis-catalog/events.md
+++ /dev/null
@@ -1,1100 +0,0 @@
-<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
-     Run `pnpm run gen-cordis-catalog` to regenerate. -->
-
-# Cordis Events Catalog
-
-Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.
-
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
-
-The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).
-
-Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).
-
-## `agent/*`
-
-### `agent/created` — emit
-
-A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
-
-```ts cordis-catalog
-/**
- * A fully configured agent and live session were published. Setup is
- * composition-only; `agent/session-start` is the first startup-driving seam.
- * Synchronous listener failure vetoes publication, while returned-promise
- * rejection is reported. Detach requested during dispatch waits until every
- * creation listener has observed the stable entry.
- * @param payload.agent - the newly registered agent with its live session and completed setup.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
-
-### `agent/disposed` — emit
-
-An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
-
-```ts cordis-catalog
-/**
- * An agent left the registry; AgentLoop emits this after driver quiescence
- * and scoped-registration unwind, but before session detachment. Custom
- * registry users own their driver-ordering contract.
- * @param payload.agent - the exact agent removed from the registry.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
-
-### `agent/error` — emit
-
-A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
-
-```ts cordis-catalog
-/**
- * A step or turn errored. The machine reports a failure here even when
- * the error has no in-turn position for a durable record.
- * @param payload.agent - the agent whose turn errored.
- * @param payload.turn - the turn in which the failure surfaced.
- * @param payload.step - the step at which the failure surfaced.
- * @param payload.error - the failure, verbatim.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
-
-### `agent/inbox/claimed` — emit
-
-One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
-
-```ts cordis-catalog
-/**
- * One message left the inbox inside its open turn. If the proposed step
- * is rejected, the claimed message ends here: it is neither discarded nor
- * re-emitted as a user/message, and the turn closes without a step.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the claimed message.
- * @param payload.turn - the owning turn.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
-
-### `agent/inbox/discarded` — emit
-
-One message was discarded from the live inbox.
-
-```ts cordis-catalog
-/**
- * One message was discarded from the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the discarded message.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
-
-### `agent/inbox/inserted` — emit
-
-One message entered the live inbox.
-
-```ts cordis-catalog
-/**
- * One message entered the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the inserted message.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
-
-### `agent/pre-step` — waterfall
-
-Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
-
-```ts cordis-catalog
-/**
- * Reject a proposed step or replace the messages that enter it. Calling
- * `next()` preserves the current messages.
- * @param payload.agent - the agent proposing the step.
- * @param payload.messages - messages removed from the inbox for this step.
- * @param payload.turn - the turn that will own the step.
- * @param payload.step - the step proposed by the loop.
- * @param payload.signal - the current turn's cancellation signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode waterfall
- */
-'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
-```
-
-Types: [Agent](../subsystems/core.md) · [PreStepDecision](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
-
-### `agent/request` — waterfall
-
-Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
-
-```ts cordis-catalog
-/**
- * Replace the frozen call configuration. `await next()` yields the config
- * the machine would use (agent options on the first request, the logged
- * header afterwards); return a replacement to switch. Model-visible
- * content must use logged channels; this seam cannot mutate messages.
- * @param payload.agent - the agent making the model call.
- * @param payload.turn - the open turn number.
- * @param payload.step - the step whose request this is.
- * @param payload.signal - the current turn's explicit abort signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode waterfall
-*/
-'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
-```
-
-Types: [Agent](../subsystems/core.md) · [LlmCallConfig](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
-
-### `agent/request-error` — waterfall
-
-Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
-
-```ts cordis-catalog
-/**
- * Handle one failed model-request attempt before the loop retries or closes
- * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
- * when it owns recovery, or calls `next()` to delegate. The default
- * `undefined` leaves the failure terminal.
- * @param payload.agent - the agent whose request failed.
- * @param payload.turn - the turn containing the failed request.
- * @param payload.step - the step containing the failed request attempt.
- * @param payload.provider - the provider selected for the failed request.
- * @param payload.failure - serializable facts normalized at the final adapter boundary.
- * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
- * @param payload.signal - the turn abort signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode waterfall
- */
-'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
-```
-
-Types: [Agent](../subsystems/core.md) · [LlmFailure](../subsystems/llm-streaming.md) · [RequestErrorAction](../subsystems/core.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
-
-### `agent/session-start` — emit
-
-The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.
-
-```ts cordis-catalog
-/**
- * The session lifecycle began, once before the first turn. Use
- * `agent.inject()` to seed model-facing context. This is a notification, not
- * a veto; disposal requested by a lifecycle owner is rechecked before the
- * driver starts.
- * @param payload.agent - the agent whose session lifecycle began.
- * @param payload.source - why the session started (fresh startup, resume, …).
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [SessionStartSource](../subsystems/core.md)
-
-Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
-
-### `agent/status` — emit
-
-Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
-
-```ts cordis-catalog
-/**
- * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
- * `running` synchronously after reserving cancellation; `idle` means no
- * driver remains scheduled or active.
- * @param payload.agent - the agent whose status flipped.
- * @param payload.status - the status just entered (the transition's destination).
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [AgentStatus](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
-
-### `agent/turn-stopping` — serial
-
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
-
-```ts cordis-catalog
-/**
- * The turn is about to close: the model owes no response (no live tool
- * calls, no fresh steering). Awaited before the boundary commits — a
- * listener that objects steers (`agent.steer(...)`) and the machine
- * re-reads its inbox: fresh steering runs another step, none closes the
- * turn. Data decides, so listener order cannot change the outcome. The
- * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step. The conclusion
- * never short-circuits already-submitted next-step work: same-step
- * `additionalContexts` or racing steering still runs, and the turn
- * closes only when that inbox drains.
- * @param payload.agent - the agent whose turn is at its stop boundary.
- * @param payload.turn - the turn about to close.
- * @param payload.signal - the current turn's explicit abort signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode serial
- */
-'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
-
-## `agent-loop/*`
-
-### `agent-loop/config-start-failed` — emit
-
-A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
-
-```ts cordis-catalog
-/**
- * A declarative agent entry failed before it could publish a live agent.
- * Consumers that buffer work for the configured identity use this
- * transient signal to reject that work instead of waiting forever. Normal
- * factory teardown suppresses failures from the cancelled startup attempt.
- * @param payload.sessionId - exact shared agent/session identity that failed startup.
- * @param payload.error - persistence, setup, or publication failure.
- * @mode emit
- */
-'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
-```
-
-Types: [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
-
-## `approval/*`
-
-### `approval/request` — waterfall
-
-Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Ask composed answerers for one decision. Return an outcome to claim the
- * request or call `next()`; failure yields the fail-closed default.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param req - the pending decision (agent, tool identity, reason, signal).
- * @mode waterfall
- */
-'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
-```
-
-Types: [ApprovalOutcome](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [ApprovalService](../subsystems/approval.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
-
-## `commands/*`
-
-### `commands/change` — emit
-
-A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
-
-```ts cordis-catalog
-/**
- * A command was registered or unregistered. This is an unfiltered registry
- * notification because a global or scoped change may affect any UI view.
- * Observer failures are contained and cannot veto the registry mutation.
- * @mode emit
- */
-'commands/change'(): void
-```
-
-Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
-
-## `credentials/*`
-
-### `credentials/updated` — emit
-
-Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
-
-```ts cordis-catalog
-/**
- * Committed change to a provider-managed credential source: a `set`, an
- * `unset`, or an external edit observed in storage. Ambient
- * process-environment changes are not observable and never emit. Listener
- * failures are contained and logged — a sync throw and an async rejection
- * alike — without changing the committed operation's outcome, except
- * `INVARIANT`-coded failures, which rethrow after every listener ran;
- * that rethrow reaches the emitter only from synchronous listeners, so
- * invariant checks on this event must not be async functions.
- * @param ref - the reference whose stored value changed.
- * @mode emit
- */
-'credentials/updated'(ref: CredentialRef): void
-```
-
-Types: [CredentialRef](../subsystems/credentials.md)
-
-Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
-
-## `domain/*`
-
-### `domain/changed` — emit
-
-A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability. Events of one domain arrive in its write-chain order.
-
-```ts cordis-catalog
-/**
- * A domain record or the global singleton changed, emitted once per write
- * strictly after the backend acknowledged durability. Events of one
- * domain arrive in its write-chain order.
- * @param change - domain, table (`''` for global), key (`''` for global),
- * operation discriminant, and on `put` the new snapshot.
- * @mode emit
- */
-'domain/changed'(change: DomainChanged): void
-```
-
-Types: [DomainChanged](../subsystems/storage.md)
-
-Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
-
-## `fs/*`
-
-### `fs/edit-intent` — waterfall
-
-Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
-
-```ts cordis-catalog
-/**
- * Single-slot decision for the next {@link FileSystem.editText}. Calling
- * `next()` yields an unconditional edit; the first returned guard wins.
- * @param target - the resolved target about to be edited.
- * @param actor - the opaque tool-execution context the decider keys off.
- * @mode waterfall
- */
-'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
-```
-
-Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
-
-### `fs/observed` — emit
-
-Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
-
-```ts cordis-catalog
-/**
- * Record a successful observation. Listeners must be synchronous recorders:
- * throws fail the tool call and returned promises are not awaited.
- * @param target - the target that was read/written/edited.
- * @param version - the version the actor now holds as its observation.
- * @param actor - the observing tool-execution context; undefined records nothing useful.
- * @mode emit
- */
-'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
-```
-
-Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
-
-### `fs/write-intent` — waterfall
-
-Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
-
-```ts cordis-catalog
-/**
- * Single-slot decision for the next {@link FileSystem.writeText}. Calling
- * `next()` yields the bare provider's unconditional write; the first listener
- * that returns an intent owns the decision rather than composing with peers.
- * @param target - the resolved target about to be written.
- * @param actor - the opaque tool-execution context the decider keys off.
- * @mode waterfall
- */
-'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
-```
-
-Types: [FsTarget](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
-
-## `goal/*`
-
-### `goal/changed` — emit
-
-Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Goal mutation accepted by one live agent. The matching `goal/change`
- * session event has already committed. Listener failures are contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param payload.agent - agent whose session owns the goal.
- * @param payload.change - fresh current projection or clear tombstone.
- * @mode emit
- */
-'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [GoalChanged](../subsystems/goal.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
-
-## `llm/*`
-
-### `llm/adapters-updated` — emit
-
-The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This is a payload-free registry notification fired at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.
-
-```ts cordis-catalog
-/**
- * The provider topology changed: an adapter registered or unregistered
- * routes, or the configurable-provider directory gained or lost entries.
- * This is a payload-free registry notification fired at each commit point
- * (including registration disposal); consumers re-read `listProviders()`,
- * `listModels()`, or `listConfigurableProviders()` for the new state.
- * Observer failures are contained and cannot veto the registry mutation.
- * @mode emit
- */
-'llm/adapters-updated'(): void
-```
-
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
-
-### `llm/stream` — waterfall
-
-Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.
-
-```ts cordis-catalog
-/**
- * Waterfall around every streaming model call (retry, replay, routing).
- * Bound to the {@link LlmService}; call `next()` to reach the resolved
- * adapter's stream, or yield your own chunks to short-circuit.
- * @param options - the full request. A LOOP-built request carries the
- *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
- *   (mutation throws): its content is a pure function of the session log (the
- *   reconstructability Agent Note), so listeners read it, never rewrite it.
- *   Hand-built calls do not carry that marker; their messages already obey
- *   the immutable creation contract.
- * @mode waterfall
- */
-'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
-```
-
-Types: [GenerateOptions](../subsystems/core.md) · [LlmService](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
-
-Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
-
-## `session/*`
-
-### `session/created` — emit
-
-Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
-
-```ts cordis-catalog
-/**
- * Creation announcement during session publication. A synchronous throw vetoes and rolls
- * back with a paired disposal; detach requested during dispatch is deferred.
- * A returned-promise rejection is logged but cannot retroactively veto this
- * synchronous boundary.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
- * receive only sessions entered through that agent's context.
- * @param session - the session just entered and announced.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'session/created'(this: Scoped<Session>, session: Session): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
-
-### `session/disposed` — emit
-
-Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
-
-```ts cordis-catalog
-/**
- * Emitted once when an announced session leaves the store, including
- * publication rollback, but never for an entry whose creation announcement
- * did not begin. Listener failures are logged and contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
- * @param session - the session that is no longer live in the store.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'session/disposed'(this: Scoped<Session>, session: Session): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
-
-### `session/event` — emit
-
-Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
-
-```ts cordis-catalog
-/**
- * Post-commit, fire-and-forget append feed. The listener snapshot resolves
- * before the log push, but callbacks run after it; observer failures are
- * logged and contained without making the committed append fail.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
- * receive only events from sessions entered through that agent's context.
- * @param session - the session whose log grew.
- * @param event - the appended event, exactly as recorded.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
-
-Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
-
-### `session/flush` — parallel
-
-Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
-
-```ts cordis-catalog
-/**
- * Awaited parallel durability checkpoint: every listener runs and the
- * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
- * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
- * @param session - the session whose buffered events must reach durable storage.
- * @dshScopeScan unsupported
- * @mode parallel
- */
-'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
-
-## `settings/*`
-
-### `settings/document-updated` — emit
-
-One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
-
-```ts cordis-catalog
-/**
- * One registered namespace's RAW user section changed, whether or not the
- * resolved value did. `settings/updated` is the consumer-facing event and
- * stays deep-equal-gated; this one exists for configuration surfaces,
- * which must learn that a field went from inherited to overridden (same
- * resolved value, different meaning) and that their held revision is
- * stale. Listener containment matches `settings/updated`.
- * @param ns - the namespace whose stored section changed.
- * @param revision - the namespace's new revision.
- * @mode emit
- */
-'settings/document-updated'(ns: SettingsNamespace, revision: number): void
-```
-
-Types: [SettingsNamespace](../subsystems/settings.md)
-
-Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
-
-### `settings/updated` — emit
-
-Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
-
-```ts cordis-catalog
-/**
- * Committed change to one registered namespace's resolved value. Emitted
- * after the provider persisted (for `update`) or published (`provider`)
- * the change; never emitted when the resolved value is deep-equal.
- * Listener failures are contained and logged — a sync throw and an async
- * rejection alike — except `INVARIANT`-coded failures, which rethrow
- * after every listener ran; that rethrow reaches the emitter only from
- * synchronous listeners, so invariant checks on this event must not be
- * async functions.
- * @param ns - the namespace whose resolved value changed.
- * @param next - the new resolved value.
- * @param prev - the previous resolved value.
- * @param source - whether the change entered through `update()` or the provider.
- * @mode emit
- */
-'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
-```
-
-Types: [SettingsNamespace](../subsystems/settings.md) · [SettingsUpdateSource](../subsystems/settings.md)
-
-Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
-
-## `skills/*`
-
-### `skills/change` — emit
-
-A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
-
-```ts cordis-catalog
-/**
- * A skill provider, runtime contribution, or provider-backed catalog may
- * have changed. This is an unfiltered invalidation notification; consumers
- * refetch the catalog for their own lookup options. Listener failures are
- * contained and cannot veto the registry mutation.
- * @mode emit
- */
-'skills/change'(): void
-```
-
-Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
-
-## `subagent/*`
-
-### `subagent/end` — emit
-
-A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
-
-```ts cordis-catalog
-/**
- * A published child settled. Scope-filtered dispatch uses the same delegating
- * parent carrier as `subagent/start`, so the lifecycle pair reaches the
- * same scoped audience.
- * @param info - the run identity and terminal outcome.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
-
-### `subagent/provider-added` — emit
-
-A provider became resolvable in the registry.
-
-```ts cordis-catalog
-/**
- * A provider became resolvable in the registry.
- * @param provider - the registered provider.
- * @mode emit
- */
-'subagent/provider-added'(provider: SubagentProvider): void
-```
-
-Types: [SubagentProvider](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
-
-### `subagent/provider-removed` — emit
-
-A provider left the registry. Accepted runs remain holder-owned.
-
-```ts cordis-catalog
-/**
- * A provider left the registry. Accepted runs remain holder-owned.
- * @param name - the provider name that no longer resolves.
- * @mode emit
- */
-'subagent/provider-removed'(name: string): void
-```
-
-Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
-
-### `subagent/start` — emit
-
-A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
-
-```ts cordis-catalog
-/**
- * A provider established a published child. For in-process providers,
- * `ctx.agents.get(info.id)` resolves during this notification.
- * Scope-filtered dispatch keys the carrier by the delegating parent, so a
- * parent-scoped listener observes only its own delegations. Paired with
- * `subagent/end`.
- * @param info - the provider and published child identity.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
-
-## `system-prompt/*`
-
-### `system-prompt/assemble` — waterfall
-
-Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
-
-```ts cordis-catalog
-/**
- * Expert waterfall over the assembled sections, contexts, tools, and variables.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
- * receive only that scope's assemblies. The returned value is authoritative.
- * A supplied signal controls only this explicit assembly request and must not
- * be retained to control later turns.
- * @param assembly - the mutable assembly built from registered providers.
- * @param context - the caller's per-assembly context.
- * @mode waterfall
- */
-'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
-```
-
-Types: [AssembleContext](../subsystems/system-prompt.md) · [Scoped](../subsystems/scope.md) · [SystemPrompt](../subsystems/system-prompt.md)
-
-Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
-
-### `system-prompt/change` — emit
-
-Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
-
-```ts cordis-catalog
-/**
- * Emitted when any prompt provider changes. This registry notification is
- * unfiltered because a global change affects every scope.
- * @mode emit
- */
-'system-prompt/change'(): void
-```
-
-Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
-
-## `telemetry/*`
-
-### `telemetry/record` — waterfall
-
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
-
-```ts cordis-catalog
-/**
- * Transform one outbound record before it reaches the backend. This
- * waterfall is the seam's redaction extension point. It ships NO rules
- * of its own: the
- * innermost `next()` passes the record through unchanged, and with no
- * listener mounted records reach the backend as captured, so exported
- * data is exactly as clean as the rules a deployment mounts. Listeners
- * stack by transforming `next()`'s return value; returning without
- * `next()` replaces everything beneath. Dispatched synchronously on the
- * capture hot path inside the coordinator's containment: a throwing
- * listener withholds that one record (fail-closed) and never reaches the
- * agent loop. Live capture dispatches at append time; on-demand capture
- * dispatches while reading the canonical log. Redaction applies to the
- * exported copy only; the canonical session log is never rewritten.
- * @param record - the candidate record, already the coordinator's own deep
- *   copy; listeners return a (possibly new) record and must not mutate it.
- * @mode waterfall
- */
-'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
-```
-
-Types: [TelemetryRecord](../subsystems/telemetry.md)
-
-Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
-
-## `tools/*`
-
-### `tools/change` — emit
-
-A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
-
-```ts cordis-catalog
-/**
- * A tool was registered or unregistered, or a scoped restriction changed
- * (the available tool set changed — possibly for one scope only). An
- * UNFILTERED registry-subject notification, deliberately not scope-filtered
- * dispatch: a global change concerns every agent's next assembly, so a
- * scoped listener subscribing here sees every change, not just its own
- * scope's.
- * @mode emit
- */
-'tools/change'(): void
-```
-
-Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
-
-### `tools/code-dispatch-log` — waterfall
-
-Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/code-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected — the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the unshaped content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
-
-```ts cordis-catalog
-/**
- * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
- * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
- * content unchanged; a listener may return replacement blocks (e.g. the
- * spill policy's preview + locator for an oversized text result). Only the
- * logged copy is affected — the program already received the complete
- * value, and the model sees neither. A throwing listener is contained:
- * the bridge falls back to logging the unshaped content.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
- * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
- * @mode waterfall
- */
-'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
-```
-
-Types: [CodeDispatchLog](../subsystems/tools.md) · [ContentBlock](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
-
-### `tools/execute` — waterfall
-
-Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
-
-```ts cordis-catalog
-/**
- * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
- * a normalized result; wrappers may change only `exec.signal`, while call
- * identity remains immutable. The registry re-fuses the original caller
- * signal before the body, so replacement cannot detach caller cancellation;
- * wrappers must still restore their signal and reach quiescence.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
- * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
- * @mode waterfall
- */
-'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
-```
-
-Types: [Scoped](../subsystems/scope.md) · [ToolDispatchExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
-
-### `tools/post-execute` — waterfall
-
-Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
-
-```ts cordis-catalog
-/**
- * Accept, replace, enrich, or block a normalized dispatch result. `next()`
- * accepts it unchanged; thrown tools still reach this seam as errors. Async
- * listeners must observe `exec.signal`; after they settle, caller
- * cancellation replaces only a successful accepted outcome with the code
- * selected by whether the tool body was invoked.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
- * @param exec - the call that just ran (name, parsed arguments, caller agent).
- * @param result - the dispatch outcome a listener may accept, replace, or block.
- * @mode waterfall
- */
-'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
-```
-
-Types: [PostToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
-
-### `tools/pre-execute` — waterfall
-
-Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
-
-```ts cordis-catalog
-/**
- * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
- * approval support turns `ask` into denial. Async gates must observe
- * `exec.signal`; the registry rechecks cancellation after they settle but
- * never abandons their promise.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
- * @param exec - the pending call (name, parsed arguments, caller agent).
- * @mode waterfall
- */
-'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
-```
-
-Types: [PreToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
-
-### `tools/result` — emit
-
-Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
-
-```ts cordis-catalog
-/**
- * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
- * @param exec - the execution object that traversed the pipeline.
- * @param result - a deep-frozen snapshot of the final returned result.
- * @mode emit
- */
-'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
-```
-
-Types: [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
-
-## `workflow/*`
-
-### `workflow/agent-end` — emit
-
-One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
-
-```ts cordis-catalog
-/**
- * One `agent()` call settled (clean result, child failure, or run
- * cancellation). Paired with {@link Events['workflow/agent-start']} by
- * `agent.seq`, exactly once per started call on every stop path — on an
- * engine termination path (a worker killed past its grace) the end is
- * engine-synthesized with outcome `'cancelled'`.
- * @param info - the run's identity snapshot.
- * @param agent - the call identity plus its outcome.
- * @mode emit
- */
-'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/agent-start` — emit
-
-One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
-
-```ts cordis-catalog
-/**
- * One `agent()` call established a published child run. Paired with
- * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
- * receives a published run from the provider emits neither
- * event in this pair.
- * @param info - the run's identity snapshot.
- * @param agent - the call's sequence number, label, phase, and child id.
- * @mode emit
- */
-'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/end` — emit
-
-A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
-
-```ts cordis-catalog
-/**
- * A workflow run settled (any stop reason). Fired when
- * {@link WorkflowRun.result} resolves. Paired with
- * {@link Events['workflow/start']}.
- * @param info - the run's identity snapshot.
- * @param result - the outcome data (stop reason, error, agent count) —
- *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
- * @mode emit
- */
-'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/log` — emit
-
-The script emitted a narration line (a `log(message)` call).
-
-```ts cordis-catalog
-/**
- * The script emitted a narration line (a `log(message)` call).
- * @param info - the run's identity snapshot.
- * @param message - the logged message, verbatim.
- * @mode emit
- */
-'workflow/log'(info: WorkflowRunInfo, message: string): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/phase` — emit
-
-The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
-
-```ts cordis-catalog
-/**
- * The script entered a phase (a `phase(title)` call) — progress grouping
- * for observers; no execution semantics.
- * @param info - the run's identity snapshot.
- * @param title - the phase title, verbatim.
- * @mode emit
- */
-'workflow/phase'(info: WorkflowRunInfo, title: string): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/start` — emit
-
-A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
-
-```ts cordis-catalog
-/**
- * A workflow run started — the script's meta block validated, the body
- * about to execute. Paired with {@link Events['workflow/end']}.
- * @param info - the run's identity snapshot (id + meta).
- * @mode emit
- */
-'workflow/start'(info: WorkflowRunInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
-
-## Inherited events (cordis core + loader/hmr/timer)
-
-The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier's prominence.
-
-- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:328`](../../vendor/cordis/src/events.ts))
-- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:330`](../../vendor/cordis/src/events.ts))
-- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:332`](../../vendor/cordis/src/events.ts))
-- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:334`](../../vendor/cordis/src/events.ts))
-- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:336`](../../vendor/cordis/src/events.ts))
-- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:338`](../../vendor/cordis/src/events.ts))
-- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
-- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
-- `hmr/change` — A watched source file changed on disk. ([`vendor/hmr/src/index.ts:20`](../../vendor/hmr/src/index.ts))
-- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:21`](../../vendor/hmr/src/index.ts))
-- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
-- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
-- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
-- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
-- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
deleted file mode 100644
index 88f1762cff..0000000000
--- a/docs/cordis-catalog/services.md
+++ /dev/null
@@ -1,2917 +0,0 @@
-<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
-     Run `pnpm run gen-cordis-catalog` to regenerate. -->
-
-# Cordis Services Catalog
-
-Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
-
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
-
-The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).
-
-## `ctx.agentLoop` — `AgentLoop`
-
-Concrete agent factory and driver service.
-
-```ts cordis-catalog
-/**
- * Create an agent and session under one caller-supplied identity, owned by
- * the accessing fiber. Constructor-driven config calls mint a fresh combined
- * id before entering this boundary.
- * @param id - shared agent/session identity.
- * @param options - concrete loop options.
- * @param meta - optional fresh-session workspace metadata.
- * @returns the published running agent.
- */
-create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
-
-/**
- * Create an owned agent on a caller-supplied session id.
- * @param ownerCtx - caller context that structurally owns the lifecycle.
- * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
- * @returns the published handle.
- */
-async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
-
-/**
- * Resume an owned agent from the configured persistence service.
- * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
- * @param options - persisted identity, loop options, setup, and cancellation.
- * @returns the published handle.
- */
-async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
-```
-
-Types: [Agent](../subsystems/core.md) · [AgentOptions](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
-
-## `ctx.agents` — `AgentRegistry`
-
-Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
-
-Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
-
-```ts cordis-catalog
-/**
- * Read the Agent that initiated the inherited asynchronous driver chain.
- * Use this optional form for logging, tracing, metrics, or host attribution
- * that also supports agentless calls. When a parent creates a child, setup
- * reports the causal parent while `agentCtx.agent` identifies the child.
- * @returns the inherited Agent, or `undefined` outside an initiator boundary
- *   and inside an explicit clearing boundary.
- * @throws when this service instance has been disposed.
- */
-currentInitiator(): Agent | undefined
-
-/**
- * Read the initiating Agent and fail when no initiator boundary is active.
- * Use this for private helpers contractually below a driver, or for a
- * deployment-owned outbound request whose contract forbids agentless calls.
- * Generic or direct-call seams use optional lookup or explicit request fields.
- * @returns the inherited Agent.
- * @throws when no initiator is active or this service instance has been disposed.
- */
-requireInitiator(): Agent
-
-/**
- * Run an operation with one exact Agent as its process-local initiator. The
- * exact synchronous value or Promise returned by the operation is preserved.
- * Custom drivers and test harnesses wrap their complete returned foreground
- * lifetime.
- * A queue or wire receiver may establish this boundary only after validating
- * explicit identity and resolving the exact live Agent; this method does neither.
- * Detached work remains owned by the subsystem that starts it.
- * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
- * @param operation - synchronous or asynchronous operation to invoke.
- * @returns the exact value returned by `operation`.
- * @throws when the initiator scope is closing/disposed, or when `operation` throws.
- */
-withInitiator<T>(agent: Agent, operation: () => T): T
-
-/**
- * Run an operation inside a boundary that hides any inherited initiating
- * Agent. The exact synchronous value or Promise is preserved.
- * Use this while creating lazy shared timers, queue pumps, pool maintenance,
- * watchers, or exporters so they do not inherit the first Agent that happens
- * to initialize them. It clears only initiator attribution, not explicit
- * fields, and does not own or drain detached resources.
- * @param operation - synchronous or asynchronous operation to invoke without an initiator.
- * @returns the exact value returned by `operation`.
- * @throws when the initiator scope is closing/disposed, or when `operation` throws.
- */
-withoutInitiator<T>(operation: () => T): T
-
-/**
- * Register the agent-creation factory (the loop calls this on construction,
- * effect-scoped). A traced Cordis service is canonicalized to its concrete
- * target; each create/resume call is then traced through that caller's
- * context so ownership follows the caller without stacking proxy layers.
- * Throws if a factory is already registered. Returns the disposer; on
- * dispose the factory slot is cleared.
- * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
- * @returns the disposer that clears the factory slot. The exact
- *   Cordis effect disposer (single-shot): composite (generator) effects may
- *   yield it directly — exact identity nests the teardown in order.
- */
-setFactory(factory: AgentFactory): () => void
-
-/**
- * Create and publish a new agent through the registered factory.
- * Distinct from {@link register} (which records an already-constructed
- * agent): this constructs the agent and its session. Rejects if no factory is
- * registered or creation/setup fails. The resolved {@link AgentHandle} lets
- * the owner tear down exactly this agent.
- * @param options - shared identity, session seed/metadata, and agent options.
- * @returns the handle after setup, rollback-covered publication, and loop start complete.
- */
-async create(options: CreateAgentOptions): Promise<AgentHandle>
-
-/**
- * Load a persisted session and resume an agent on it through the registered
- * factory. Rejects if no factory is registered; the factory rejects if
- * session persistence is not configured or persistence/setup fails.
- * @param options - persisted identity, configuration, and optional setup.
- * @returns the handle after setup, rollback-covered publication, and loop start complete.
- */
-async resume(options: ResumeAgentOptions): Promise<AgentHandle>
-
-/**
- * Register a live agent. Throws if an agent with the same id is already
- * registered. Emits `agent/created` on registration and `agent/disposed`
- * when the calling fiber is disposed — both with the agent's scope carrier
- * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
- * emits are scope-filtered regardless of which context invoked `register`
- * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
- * requires passing the carrier). Returns the disposer.
- * @param agent - the already-constructed agent to record in the store.
- * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
- *   returns undefined without awaiting an in-flight teardown). Exact
- *   identity is load-bearing: a composite (generator) effect that owns a
- *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
- *   function so Cordis nests the unregistration at that yield position;
- *   yielding a wrapper would leave it disposing as a concurrent sibling on
- *   owner unload, unregistering the agent (and emitting `agent/disposed`)
- *   while its final turn is still draining.
- */
-register(agent: Agent): () => void
-
-/**
- * Insert an already-constructed agent without announcing it. This is the
- * advanced ordered-lifecycle primitive used by the async agent factory: it
- * first completes setup while the agent is unpublished, then assigns the
- * returned detach closure into its pre-installed composite teardown before
- * calling {@link announce}. Ordinary callers use {@link register}.
- * @param agent - the prepared, unpublished agent.
- * @param owner - live agent whose scoped context created this agent, or
- *   undefined for a top-level runtime root. This is runtime ownership, not
- *   the resumed session's durable parent lineage.
- * @returns an idempotent closure that removes this exact entry and emits
- *   `agent/disposed` with listener failures contained. When called from a
- *   synchronous `agent/created` listener, removal and disposal wait until
- *   that creation dispatch unwinds.
- */
-enter(agent: Agent, owner: Agent | undefined): () => void
-
-/**
- * Announce an agent previously inserted with {@link enter}.
- * @param agent - the live inserted agent to announce.
- * @throws if `agent` is not the exact live registry entry for its id, or its
- *   creation announcement already began (including a reentrant call from a
- *   creation listener).
- */
-announce(agent: Agent): void
-
-/**
- * Look up a live agent.
- * @param id - the shared agent/session id to look up.
- * @returns the agent, or undefined when no live agent has that id.
- */
-get(id: SessionId): Agent | undefined
-
-/**
- * Test whether a live agent was created through one exact parent agent's
- * scoped context. Runtime ownership is independent of durable session
- * lineage and remains unambiguous when unrelated providers reuse an id.
- * @param id - the candidate child agent's shared agent/session id.
- * @param owner - the expected runtime creator agent.
- * @returns true only while the exact child entry is live under that owner.
- */
-isOwnedBy(id: SessionId, owner: Agent): boolean
-
-/**
- * All live agents, in registration order.
- * @returns a fresh array; mutating it does not affect the registry.
- */
-list(): Agent[]
-
-/**
- * All live top-level agents in registration order. A top-level agent was
- * created without an owning agent context; durable session lineage does not
- * affect this runtime relation, so a resumed fork may still be a root.
- * @returns a fresh array; mutating it does not affect the registry.
- */
-roots(): Agent[]
-```
-
-Types: [Agent](../subsystems/core.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
-
-## `ctx.approval` — `ApprovalService`
-
-Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
-
-```ts cordis-catalog
-/**
- * Switch one live agent's policy and queue the transition for its next model
- * step. Session initialization uses {@link setApprovalPolicy} directly
- * because there is no previously visible policy to change.
- * @param agent - the live agent whose policy is changing.
- * @param policy - the new effective policy.
- */
-setPolicy(agent: Agent, policy: ApprovalPolicy): void
-
-/**
- * Ask the composed answerers to decide one readonly same-process request.
- * The service borrows the request, agent, session, and live signal directly.
- * The request requires an open turn because the audit pair must be enclosed
- * by the durable log's commit/replay boundary; an idle ask rejects before
- * appending anything. The answerer phase always produces an outcome: an
- * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
- * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
- * normalized to `'unavailable'`. A failure that prevents either audit append
- * from committing still rejects because returning an unlogged decision would
- * violate the pair. Session contains post-commit observer failures, so an
- * authoritative append cannot reject the request or suppress its matching
- * audit event.
- * @param req - the pending decision (agent, tool identity, reason, signal).
- * @returns the closed outcome; `'allowed-once'` is the only grant.
- * @throws when no turn is open or either audit event fails before the session
- *   append commit point.
- */
-async request(req: ApprovalRequest): Promise<ApprovalOutcome>
-
-/**
- * Read the session override without applying the configured default.
- * @param session - session whose log supplies the override.
- * @returns the last logged policy, or `undefined` without one.
- */
-overrideOf(session: Session): ApprovalPolicy | undefined
-```
-
-Types: [Agent](../subsystems/core.md) · [ApprovalOutcome](../subsystems/approval.md) · [ApprovalPolicy](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
-
-## `ctx.bash` — `BashExecutor` (abstract seam)
-
-Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
-- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
-- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
-- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
-
-```ts cordis-catalog
-/**
- * Apply implementation-owned defaults and caps to a request before execution.
- * @param request - the caller's request; omitted fields get this
- *   implementation's defaults, capped fields are clamped.
- * @returns the fully-specified spec to hand to {@link run}/{@link start}.
- */
-abstract resolve(request: BashExecRequest): BashExecSpec
-
-/**
- * Run a command in the foreground; resolves when it finishes.
- * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the outcome; nonzero exits, timeout kills, and abort kills
- *   resolve with a descriptive result rather than reject.
- */
-abstract run(spec: BashExecSpec): Promise<BashRunResult>
-
-/**
- * Start a background process and return its handle immediately.
- * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the live process handle (reads, kill, quiescence promise).
- */
-abstract start(spec: BashExecSpec): BashProcess
-```
-
-Types: [BashExecRequest](../subsystems/bash.md) · [BashExecSpec](../subsystems/bash.md) · [BashProcess](../subsystems/bash.md) · [BashRunResult](../subsystems/bash.md)
-
-Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
-
-## `ctx.bashEnv` — `BashEnvRegistry`
-
-Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
-
-```ts cordis-catalog
-/**
- * Register one environment contributor. Names and keys are unique; built-in
- * keys are reserved. Registration is disposed with the calling plugin fiber.
- * @param contributor - declared key ownership and per-execution resolver.
- * @returns the disposer that unregisters the contribution.
- */
-register(contributor: BashEnvContributor): () => void
-
-/**
- * Build the trusted `DSH_*` snapshot for one shell tool execution.
- * @param execution - the current tool execution.
- * @returns an immutable environment overlay containing built-ins and current contributions.
- */
-collect(execution: ToolExecution): DshEnvironment
-
-/**
- * Enumerate plugin-contributed variables without executing their resolvers.
- * @returns declarations sorted by environment variable name.
- */
-list(): BashEnvVariableInfo[]
-```
-
-Types: [DshEnvironment](../subsystems/subprocess.md) · [ToolExecution](../subsystems/tools.md)
-
-Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
-
-## `ctx.clientModuleHost` — `ClientModuleHostService`
-
-The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
-
-```ts cordis-catalog
-/**
- * Current composed entry graph (stable object between changes).
- * @returns the graph served as `window.__DSH_BOOT__`.
- */
-graph(): WebBootGraph
-
-/**
- * Absolute path of an entry's client bundle.
- * @param id - entry id (package name).
- * @returns the path, or undefined for an unknown id.
- */
-clientPath(id: string): string | undefined
-
-/**
- * Re-hash one bundle (the HMR watch's registration hook — the only entry
- * point through which bundle content changes reach the graph).
- * @param id - entry id (package name).
- * @returns the new rev, or undefined for an unknown id.
- */
-rebuilt(id: string): string | undefined
-
-/**
- * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
- * @param listener - receives the entry id and its new bundle rev.
- * @returns the unsubscriber.
- */
-onRebuilt(listener: (id: string, rev: string) => void): () => void
-
-/**
- * Fires after any flush that recomposed the graph (row added/removed, or a
- * rebuilt rev change). Pull model: listeners re-read {@link graph}.
- * @param listener - notified with no payload.
- * @returns the unsubscriber.
- */
-onGraphChanged(listener: () => void): () => void
-```
-
-Types: [WebBootGraph](../subsystems/client-modules.md)
-
-Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
-
-## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
-
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
-
-```ts cordis-catalog
-/**
- * Execute one program against the request's bindings and capture what it
- * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means seam misuse only).
- * @param request - the program, its bindings, and the abort signal; the
- *   request carries everything the runtime acts on, with no hidden defaults.
- * @returns the run's outcome: completion value (when transferable), the
- *   ordered log capture, and the failure (if any).
- */
-abstract run(request: CodeRunRequest): Promise<CodeRunResult>
-```
-
-Types: [CodeRunRequest](../subsystems/code-runtime.md) · [CodeRunResult](../subsystems/code-runtime.md)
-
-Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
-
-## `ctx.commands` — `CommandService`
-
-Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
-
-```ts cordis-catalog
-/**
- * Register a global or calling-agent-scoped command.
- * @param definition - discovery metadata and direct UI handler.
- * @returns the exact effect disposer that unregisters this definition.
- */
-register(definition: CommandDefinition): () => void
-
-/**
- * List the effective immutable command descriptors for one agent.
- * @param agent - exact receiving agent and scoped-layer key.
- * @returns name-sorted descriptors after scoped shadowing.
- */
-list(agent: Agent): readonly CommandDescriptor[]
-
-/**
- * Resolve one effective command definition.
- * @param agent - exact receiving agent and scoped-layer key.
- * @param name - command name without a slash.
- * @returns the scoped shadow or global definition.
- */
-find(agent: Agent, name: string): CommandDefinition | undefined
-
-/**
- * Parse and execute a known command without sending it to the model.
- *
- * A resolved command's lifecycle is logged: `command/run` is appended
- * before the handler is invoked and `command/done` after settlement (a
- * thrown or aborted handler settles as `kind: 'error'`). Both are direct
- * log-only appends — no turn wraps them, and persistence drains them at
- * ordinary checkpoints. Admission misses (syntax or unknown name) log
- * nothing — they never entered a handler. A `command/run` append failure
- * fails the execution loud; a `command/done` append failure on the
- * handler-failure path is contained so the handler's own error stays the
- * reported failure.
- *
- * @param agent - exact receiving agent.
- * @param line - complete slash-command line.
- * @param signal - cancellation signal owned by the UI request.
- * @returns the settled execution (result + lifecycle pairing id), or
- *   `undefined` when syntax or name does not resolve.
- */
-async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
-```
-
-Types: [Agent](../subsystems/core.md) · [CommandDefinition](../subsystems/commands.md) · [CommandDescriptor](../subsystems/commands.md)
-
-Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
-
-## `ctx.compact` — `CompactService` (abstract seam)
-
-Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
-
-```ts cordis-catalog
-/**
- * Consider automatic compaction for one explicit trigger. Pressure policy
- * uses the latest durable routed request, while context-overflow policy may
- * force a useful balanced reduction even below the normal threshold. Return
- * `null` when no safe range can be compacted. A single oversized retained
- * unit or request envelope cannot be repaired through surface compaction.
- *
- * @param agent - agent context owning the session surface and routing options.
- * @param trigger - normal pressure or provider-confirmed context overflow.
- * @param signal - cancellation signal; model-backed implementations must forward it.
- * @returns the compaction result, or `null` if no compaction was needed.
- */
-abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
-
-/**
- * Explicitly compact useful history even below automatic pressure thresholds.
- * Implementations synchronously start an idle task before any asynchronous
- * work, select a useful range without writing on a no-op, then
- * append a standalone `compact/start` before summarization. That durable
- * marker is the compaction lock until one `compact/end` attempt. Later waking
- * prompts remain accepted in FIFO order and start only after the optional
- * durability checkpoint and idle-task settlement. Context injected while the
- * summary runs may sit between the marker pair; only the selected span must
- * remain stable.
- *
- * @param agent - idle agent whose durable history should be compacted.
- * @param signal - cancellation scoped to this compaction request.
- * @returns the compaction result, or `null` when no safe useful range exists.
- * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
- * changed-span, summarization/shrink, commit-stage, or persistence failures;
- * an aborted request preserves its exact abort reason. Failed attempts remain
- * visible in the log.
- */
-abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
-
-/**
- * Forcibly compact a range of surface nodes into a single summary node.
- * `start` and `end` name an inclusive span by surface position, not numeric seq
- * order; replacements can make visible seqs non-monotonic. Both edges must be
- * balanced so assistant tool calls remain paired with their results. A model-
- * backed implementation forwards cancellation and rejects active, missing,
- * reversed, or unbalanced ranges. The target session is `agent.session`.
- * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
- * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
- * for the edge checks.
- *
- * @param start - first surface seq, inclusive.
- * @param end - last surface seq, inclusive.
- * @param agent - context whose session is mutated and whose routing options guide summarization.
- * @param signal - optional cancellation; model-backed implementations must forward it.
- * @throws when compaction is active or the range is missing, reversed, or unbalanced.
- * @returns the appended event seqs, summary, replaced range, and token accounting.
- */
-abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
-```
-
-Types: [CompactionResult](../subsystems/compaction.md) · [CompactionTrigger](../subsystems/compaction.md)
-
-Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
-
-## `ctx.credentials` — `Credentials` (abstract seam)
-
-Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
-
-```ts cordis-catalog
-/**
- * Resolve one reference to its current value. Resolution is per call:
- * consumers re-resolve at each operation and must not cache across
- * operations — that per-operation read is what makes a changed credential
- * reach the next operation without a restart.
- * @param ref - the reference to resolve.
- * @returns the value and its source, or `undefined` while unconfigured.
- */
-abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
-
-/**
- * Describe one reference for configuration surfaces without exposing the
- * value.
- * @param ref - the reference to describe.
- * @returns configured state, supplying source, and writability.
- */
-abstract describe(ref: CredentialRef): Promise<CredentialInfo>
-
-/**
- * Durably store one value in the provider-managed writable source. Rejects
- * while a read-only source shadows the reference — the write would appear
- * to succeed while resolution keeps returning the shadowing value — and
- * rejects an empty value (use {@link unset}).
- * @param ref - the reference to store.
- * @param value - the non-empty secret value.
- */
-abstract set(ref: CredentialRef, value: string): Promise<void>
-
-/**
- * Remove one reference from the provider-managed writable source; removing
- * an absent reference is a no-op. Rejects while a read-only source shadows
- * the reference, like {@link set}.
- * @param ref - the reference to remove.
- */
-abstract unset(ref: CredentialRef): Promise<void>
-```
-
-Types: [CredentialInfo](../subsystems/credentials.md) · [CredentialRef](../subsystems/credentials.md) · [ResolvedCredential](../subsystems/credentials.md)
-
-Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
-
-## `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
-
-Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
-
-```ts cordis-catalog
-/**
- * The backend's interaction capability.
- * @returns the discriminated capability consumers switch on.
- */
-abstract capability(): DirectoryPickerCapability
-```
-
-Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
-
-## `ctx.e2b` — `E2BSandboxService`
-
-Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
-
-```ts cordis-catalog
-/**
- * Return the shared live SDK handle.
- * @returns the created sandbox after the configured cwd exists.
- * @throws when E2B rejects creation or the service is disposing.
- */
-async getSandbox(): Promise<Sandbox>
-```
-
-Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
-
-## `ctx.fs` — `FileSystem` (abstract seam)
-
-Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
-
-```ts cordis-catalog
-/**
- * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
- * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
- * async even though the local backend only normalizes + realpaths.
- *
- * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
- * @param opts - optional cwd override and cancellation signal.
- * @returns the stable target; the same file yields the same `targetKey`.
- */
-abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
-
-/**
- * Return the canonical absolute path a subprocess in this filesystem's
- * execution world can open. The path is deliberately separate from
- * {@link FsTarget.targetKey}: consumers may pass this value to another OS
- * capability, but must continue treating the target key as opaque.
- * @param target - the resolved target whose process path is required.
- * @returns an absolute path in the backend's execution world.
- */
-abstract processPath(target: FsTarget): string
-
-/**
- * Return the canonical `file:` URI for a target in this filesystem's
- * execution world. Backends own URI encoding because the host platform may
- * differ from the execution platform.
- * @param target - the resolved target to encode.
- * @returns the target's canonical file URI.
- */
-abstract fileUrl(target: FsTarget): string
-
-/**
- * Test canonical containment without exposing or parsing backend target
- * keys. Both targets must come from this provider.
- * @param parent - canonical directory target.
- * @param child - canonical candidate target.
- * @returns true when `child` is `parent` or a descendant of it.
- */
-abstract contains(parent: FsTarget, child: FsTarget): boolean
-
-/**
- * Return target metadata, or `undefined` when the target does not exist.
- * @param target - the resolved target to stat.
- * @param signal - aborts the metadata round-trip.
- * @returns metadata only, never content; undefined for an absent target.
- */
-abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
-
-/**
- * Return path metadata without following the final path component when it is a
- * symbolic link. This is intentionally path-shaped, not target-shaped:
- * {@link resolve} follows symlinks to produce the stable identity used by
- * normal reads/writes, while `lstat` lets a consumer reject the path itself
- * before that follow happens.
- *
- * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
- * absent.
- * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
- * @param opts - `cwd` overrides the backend's default base for relative paths.
- * @param signal - aborts the metadata round-trip.
- * @returns metadata only, never content; undefined for an absent path.
- */
-abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
-
-/**
- * Read the whole regular text file as a single decoded string.
- * @param target - the resolved target to read.
- * @param signal - aborts the read.
- * @returns the full decoded UTF-8 content.
- */
-abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
-
-/**
- * Stream the whole regular text file as decoded text chunks (same text
- * semantics as {@link readText}, for large files). The backend owns
- * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
- * touches raw bytes.
- * @param target - the resolved target to read.
- * @param signal - aborts the stream, including between chunks.
- * @returns the chunk iterable, decoded and validated like {@link readText}.
- */
-abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
-
-/**
- * List direct children of a directory in stable name order. Returns resolved
- * child targets plus cheap metadata only; never reads file contents.
- * @param target - the resolved directory target.
- * @param signal - aborts the listing.
- * @returns one entry per direct child, in stable name order.
- */
-abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
-
-/**
- * Atomically create or replace UTF-8 text. `expected` guards intent and
- * staleness; omission allows unconditional overwrite.
- * @param target - the resolved target to write.
- * @param content - the full new file content.
- * @param expected - the write intent guarding the write; omit for unconditional.
- * @param signal - aborts before the atomic rename takes effect.
- * @param sandboxPolicy - the per-call mode and workspace root this write
- *   runs under; a sandboxing backend fences the write by it, the bare backend
- *   ignores it. Omit to leave the backend its own default.
- * @returns the outcome, including the version the write produced.
- */
-abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
-
-/**
- * Atomically edit literal text. When supplied, the version guard is checked
- * before matching so stale content reports `FS_STALE_VERSION`; omission edits
- * the current content without a freshness precondition.
- * @param target - the resolved target to edit.
- * @param edit - the literal search/replace request.
- * @param expected - the version guard; omit for an unconditional edit.
- * @param signal - aborts before the atomic rename takes effect.
- * @param sandboxPolicy - the per-call mode and workspace root this edit runs
- *   under; a sandboxing backend fences the edit by it, the bare backend
- *   ignores it. Omit to leave the backend its own default.
- * @returns the outcome, including the version the edit produced.
- */
-abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
-```
-
-Types: [FsDirEntry](../subsystems/filesystem.md) · [FsEditOutcome](../subsystems/filesystem.md) · [FsEditRequest](../subsystems/filesystem.md) · [FsInfo](../subsystems/filesystem.md) · [FsPathInfo](../subsystems/filesystem.md) · [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md) · [FsWriteOutcome](../subsystems/filesystem.md) · [SandboxExecutionPolicy](../subsystems/sandbox.md)
-
-Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
-
-## `ctx.goals` — `GoalService`
-
-Goal service (`ctx.goals`) backed exclusively by the owning session log.
-
-```ts cordis-catalog
-/**
- * Read the current goal for one exact live agent.
- * @param agent - owning live agent.
- * @returns a fresh view or `undefined` when no goal is current.
- * @throws {@link GoalError} when the agent is not the registry's live instance.
- */
-get(agent: Agent): GoalView | undefined
-
-/**
- * Remove process-local continuation authority without changing durable goal
- * phase or revision. Lifecycle owners use this before unloading a driver;
- * a later human-authorized {@link resume} records the new activation edge.
- * @param agent - owning live agent.
- * @returns a fresh disarmed view, or `undefined` when no goal is current.
- */
-disarm(agent: Agent): GoalView | undefined
-
-/**
- * Create and arm a goal. A completed goal may be replaced; every other
- * current phase must be cleared or resumed instead.
- * @param agent - owning live agent.
- * @param request - objective and optional round cap.
- * @returns the created live view.
- */
-create(agent: Agent, request: CreateGoalRequest): GoalView
-
-/**
- * Edit objective and/or round cap without changing phase.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @param request - at least one replacement field.
- * @returns the edited view.
- */
-@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
-
-/**
- * Pause an active goal and disarm automatic continuation.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the paused view.
- */
-@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Resume and arm a stopped goal, or rearm an active goal after a
- * session-start edge, while its round budget still has capacity.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the active view.
- */
-@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Mark a current non-complete goal complete and disarm it.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the completed view.
- */
-@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Mark an active goal blocked and disarm it.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @param reason - policy-owned stable code and human-readable explanation.
- * @returns the blocked view with its durable reason.
- */
-block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
-
-/**
- * Clear the current goal while retaining a durable tombstone and history.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the tombstone ref whose revision is one past the cleared snapshot.
- */
-@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
-
-/**
- * Create one Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param request - objective and optional round cap.
- * @returns the created Goal identity.
- */
-@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
-```
-
-Types: [Agent](../subsystems/core.md) · [CreateGoalRequest](../subsystems/goal.md) · [CreateGoalResult](../subsystems/goal.md) · [EditGoalRequest](../subsystems/goal.md) · [GoalBlockReason](../subsystems/goal.md) · [GoalRef](../subsystems/goal.md) · [GoalView](../subsystems/goal.md)
-
-Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
-
-## `ctx.httpServer` — `HttpServerService`
-
-The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
-
-```ts cordis-catalog
-/**
- * Register a named route. Duplicate (kind, path) throws — route patterns are
- * a composition-level contract, so a collision is a misconfiguration.
- * @param route - kind, path, and the owning handler.
- * @returns the disposer removing the route.
- */
-register(route: WebRoute): () => void
-
-/**
- * Register an exact-path HTTP upgrade route. Duplicate paths throw because
- * one socket can have only one protocol owner.
- * @param route - pathname and handler owning negotiation plus socket use.
- * @returns the disposer removing the route.
- */
-registerUpgrade(route: WebUpgradeRoute): () => void
-
-/**
- * Claim the fallback seat: the handler answering every request no named
- * route matches (the SPA dist server in the shipped Web composition). One
- * owner only — a second registration throws, because two fallbacks cannot
- * compose.
- * @param handler - owns the full response lifecycle of unmatched requests.
- * @returns the disposer releasing the seat.
- */
-registerFallback(handler: WebRoute['handler']): () => void
-
-/**
- * Register an index.html transform, applied by the fallback owner to every
- * index response ({@link applyIndexTaps}) in registration order.
- * @param transform - pure html-to-html function.
- * @returns the disposer removing the transform.
- */
-tapIndex(transform: (html: string) => string): () => void
-
-/**
- * Run an index.html body through the registered taps in registration order
- * — called by the fallback owner on every index response it renders.
- * @param html - the raw index.html body.
- * @returns the transformed body.
- */
-applyIndexTaps(html: string): string
-```
-
-Types: [WebRoute](../subsystems/http-server.md)
-
-Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
-
-## `ctx.invariants` — `InvariantService`
-
-Package-owned invariant registry with global and regex-based selection.
-
-```ts cordis-catalog
-/**
- * Register one package's invariant installer. The package name is reserved
- * even when filtering disables its checks. Enabled installers run in a child
- * fiber; failure disposes that fiber and releases the reservation.
- * @param packageName - full npm package name that owns the contribution.
- * @param installer - listener or startup-check installer for the child context.
- * @returns an effect-scoped disposer for the registration.
- */
-register(packageName: string, installer: InvariantInstaller): () => void
-```
-
-Types: [InvariantInstaller](../subsystems/invariants.md)
-
-Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
-
-## `ctx.llm` — `LlmService`
-
-The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
-
-```ts cordis-catalog
-/**
- * Register an adapter for the given provider routes. Throws `LlmError` with code
- * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
- * Disposed with the fiber.
- * @param providers - every provider route this adapter should serve.
- * @param adapter - the adapter that streams calls for those providers.
- * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
- */
-registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
-
-/**
- * Describe provider routes with a registered adapter.
- * @returns detached provider metadata in registration order.
- */
-listProviders(): LlmProviderInfo[]
-
-/**
- * Declare provider routes an adapter plugin can activate through
- * configuration. Registration is all-or-nothing: an empty list, invalid
- * entry, or a provider already declared by any registration throws
- * `LlmError` without registering the rest. Disposed with the fiber.
- * @param entries - every configurable provider this plugin owns.
- * @returns a handle that withdraws all of them, and can atomically replace them.
- */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
-
-/**
- * List every declared configurable provider, registered or dormant.
- * @returns detached directory entries in declaration order.
- */
-listConfigurableProviders(): LlmConfigurableProvider[]
-
-/**
- * Offer to interrogate provider endpoints on behalf of the settings
- * namespace this plugin owns. The namespace is the key because that is what
- * a configuration surface already holds from the configurable-provider
- * directory, and because a provider being *added* has no route to name yet.
- * Disposed with the fiber.
- * @param settingsNs - the namespace whose profiles this discovery serves.
- * @param discover - interrogates one endpoint; must honor `request.signal`.
- * @returns the disposer that withdraws the offer.
- */
-registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
-
-/**
- * Interrogate one provider endpoint for the models it advertises. The
- * request describes a draft, not a stored route, so nothing here reads or
- * writes settings or credentials — the caller owns both, and the reply is
- * candidate metadata a surface may offer for adoption.
- * @param settingsNs - namespace whose registered discovery serves this draft.
- * @param request - the endpoint, protocol, and one-shot credential to use.
- * @returns the advertised models, deduplicated in endpoint order.
- */
-async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
-
-/**
- * Resolve the retry policy captured when one provider route was registered.
- * @param provider - registered provider route to inspect.
- * @returns the provider-owned policy, with normal defaults already resolved.
- */
-providerRetryPolicy(provider: string): ResolvedRetryPolicy
-
-/**
- * Discover models advertised by one registered provider. Catalog membership
- * is advisory and never changes routing or request validation.
- * @param provider - registered provider route to inspect.
- * @returns detached model metadata in adapter-preferred order.
- */
-async listModels(provider: string): Promise<LlmModelInfo[]>
-
-/**
- * Resolve and validate all metadata from the adapter that owns one exact
- * route. The result is detached from adapter-owned objects; catalog
- * membership remains advisory and does not control request routing.
- * @param provider - registered provider route to inspect.
- * @param model - exact model id passed to the adapter.
- * @param signal - optional cancellation for adapter-owned asynchronous lookup.
- * @returns exact model identity plus available context and reasoning metadata.
- */
-async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>
-
-/**
- * Validate a conversation call config against its exact model capability and
- * materialize adapter-configured defaults. Unsupported explicit efforts
- * reject before provider I/O; no clamping or aliasing is performed. This
- * standalone query does not bind a later dispatch; use {@link prepareCall}
- * when logging and streaming must share one adapter registration.
- * @param config - provider/model route and optional request controls.
- * @param signal - optional cancellation for adapter-owned capability lookup.
- * @returns a detached config only when a default must be materialized.
- */
-async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>
-
-/**
- * Resolve one call under its current adapter registration. The returned
- * one-shot handle keeps that registration across header logging and dispatch,
- * so HMR cannot combine one adapter's capability result with another adapter.
- * @param config - provider/model route and optional request controls.
- * @param signal - optional cancellation for adapter-owned capability lookup.
- * @returns a prepared config and its registration-bound stream entry point.
- */
-async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
-
-/**
- * Stream one model call as raw chunks (token-level deltas). Replay state is
- * retained only when the same adapter instance owns its historical provider
- * and the target provider. Final adapter selection remains fixed through
- * asynchronous exact-model resolution and dispatch. Adapter selection,
- * dispatch, and iteration failures become terminal `error` or `aborted`
- * finish chunks; middleware, nested-call, cleanup, and consumer failures
- * remain thrown.
- * @param options - the full request; `options.provider` selects the adapter.
- * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
- */
-stream(options: GenerateOptions): AsyncIterable<StreamChunk>
-```
-
-Types: [AdapterRegistrationHandle](../subsystems/core.md) · [DirectoryRegistrationHandle](../subsystems/core.md) · [GenerateOptions](../subsystems/core.md) · [LlmAdapter](../subsystems/llm-streaming.md) · [LlmCallConfig](../subsystems/core.md) · [LlmConfigurableProvider](../subsystems/core.md) · [LlmDiscoveredModel](../subsystems/core.md) · [LlmModelDiscoveryRequest](../subsystems/core.md) · [LlmModelInfo](../subsystems/core.md) · [LlmProviderInfo](../subsystems/core.md) · [LlmResolvedModelInfo](../subsystems/core.md) · [PreparedLlmCall](../subsystems/llm-streaming.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
-
-Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
-
-## `ctx.permission` — `PermissionService`
-
-Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
-
-```ts cordis-catalog
-/**
- * Resolve the preset matching the effective knob values. A still-matching
- * last selection wins shared-bundle ties; otherwise the first table match
- * wins, or {@link CUSTOM_PRESET} when no entry matches.
- * @param events - the session's events in log order.
- * @returns the effective preset name, or `custom` when nothing matches.
- */
-current(events: readonly SessionEvent[]): string
-
-/**
- * Build the whole select value for one folded knob state: every table
- * option in declaration order, `custom` appended exactly while derived.
- * @param state - the folded knob overrides.
- * @returns the `permissions` projection payload.
- */
-selectFor(state: KnobState): PermissionSelect
-
-/**
- * Resolve a preset's knob bundle.
- * @param name - the preset name to resolve.
- * @returns the configured bundle.
- * @throws when `name` is not in the table.
- */
-resolve(name: string): PresetSpec
-
-/**
- * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
- * missing label falls back to the table key.
- * @param name - a table key, or `custom`.
- * @returns the option a client renders.
- * @throws when `name` is neither a table key nor `custom`.
- */
-optionOf(name: string): PresetOption
-
-/**
- * Record a changed preset, then update each changed knob through its own
- * setter. Selecting the effective preset again appends nothing.
- * @param session - the session the switch belongs to.
- * @param name - the preset to switch to; unknown names throw.
- */
-set(session: Session, name: string): void
-```
-
-Types: [PresetOption](../subsystems/permission.md) · [PresetSpec](../subsystems/permission.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
-
-Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
-
-## `ctx.planMode` — `PlanModeService`
-
-`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
-
-```ts cordis-catalog
-/**
- * Read the logged plan state and any selected state awaiting a boundary.
- *
- * @param agent The agent to read.
- * @returns Current logged state plus a pending selection, when present.
- */
-get(agent: Agent): { active: boolean; pending?: boolean }
-
-/**
- * Select whether plan mode should be active. Between turns the change
- * commits immediately — no request boundary would arrive until the next
- * prompt, so a queued intent would hang (the open-turn fold is the idle
- * signal: agent status stays `running` through post-turn checkpointing,
- * where a boundary equally never comes). During an open turn the
- * selection is held as pending intent for the next in-turn request
- * boundary. Repeated selection of the current or already-pending state is
- * a no-op.
- *
- * @param agent The agent to switch.
- * @param active Whether plan mode should be active.
- * @returns what happened: `committed` (logged now), `queued` (awaiting the
- * next boundary), `cancelled` (an opposite pending selection was cleared;
- * the logged state already matches), or `noop` (already in that state).
- */
-set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
-```
-
-Types: [Agent](../subsystems/core.md)
-
-Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
-
-## `ctx.pty` — `PtyService`
-
-In-process registry for replaceable PTY backends and exact-Agent sessions.
-
-```ts cordis-catalog
-/**
- * Register one backend type for this effect scope.
- * @param backend - provider with a non-empty unique type.
- * @returns disposer that removes exactly this contribution.
- */
-registerBackend(backend: PtyBackend): () => void
-
-/**
- * List registered backend types in registration order.
- * @returns fresh backend type names.
- */
-listBackends(): string[]
-
-/**
- * Create and publish one owner-scoped session after backend setup succeeds.
- * @param owner - exact registered Agent that owns access and cleanup.
- * @param request - backend type plus optional owner-local name and cwd.
- * @param signal - cancellation of unpublished setup.
- * @returns published identity, metadata, status, and MOTD.
- */
-async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
-
-/**
- * Test whether an exact owner has a published session or unpublished spawn.
- * @param owner - exact live owner to inspect.
- * @returns true across the entire spawn-to-close interval, with no publication gap.
- */
-hasOwnerActivity(owner: Agent): boolean
-
-/**
- * Start one exclusive interactive send.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - explicit text, submit behavior, and cancellation.
- * @returns live operation handle for foreground await or task registration.
- */
-startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
-
-/**
- * Read one bounded scrollback page from an owned session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - optional newest-relative offset and line count.
- * @returns bounded retained text and pagination metadata.
- */
-read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
-
-/**
- * Deliver an allowed signal through an owned backend session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param signal - allowed POSIX signal name.
- * @returns delivered foreground process-group identity.
- */
-signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
-
-/**
- * Close one owned session and remove it only after quiescent backend cleanup.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param reason - diagnostic cleanup reason.
- * @returns true for a newly closed session, false when the same close is already in flight.
- */
-async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
-
-/**
- * List fresh snapshots for exactly one owner.
- * @param owner - exact owner whose sessions are visible.
- * @returns owner-visible snapshots in publication order.
- */
-list(owner: Agent): PtySessionSnapshot[]
-```
-
-Types: [Agent](../subsystems/core.md) · [PtyBackend](../subsystems/pty.md) · [PtyReadRequest](../subsystems/pty.md) · [PtyReadResult](../subsystems/pty.md) · [PtySendOperation](../subsystems/pty.md) · [PtySendRequest](../subsystems/pty.md) · [PtySessionId](../subsystems/pty.md) · [PtySessionSnapshot](../subsystems/pty.md) · [PtySignal](../subsystems/pty.md) · [PtySignalResult](../subsystems/pty.md) · [PtySpawnRequest](../subsystems/pty.md) · [PtySpawnResult](../subsystems/pty.md)
-
-Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
-
-## `ctx.sandbox` — `SandboxProvider` (abstract seam)
-
-Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
-
-```ts cordis-catalog
-/**
- * Wrap `argv` so it executes confined under `policy` on this host; the
- * caller spawns the returned argv in place of its own.
- * @param argv - the exact argv the caller is about to spawn (program plus
- *   arguments), NOT a shell string — a shell-shaped consumer passes
- *   `['bash', '-c', command]`.
- * @param policy - the file-effect policy this execution runs under,
- *   carried per call (see {@link SandboxPolicy}).
- * @returns the argv to spawn instead, plus the enforcement completeness
- *   the selected backend achieves for it.
- */
-abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
-```
-
-Types: [ConfinedArgv](../subsystems/sandbox.md) · [SandboxPolicy](../subsystems/sandbox.md)
-
-Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
-
-## `ctx.sandboxPolicy` — `SandboxPolicyService`
-
-The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
-
-```ts cordis-catalog
-/**
- * Resolve the complete policy for one capability call. An approved explicit
- * mode outranks the session's last `sandbox/mode` event, which outranks the
- * deployment default. A session cwd is its workspace-write boundary; the
- * configured root is the fallback for agentless calls and sessions without a
- * cwd.
- * @param request - optional session and approved mode override.
- * @returns the fully resolved per-call mode and absolute workspace root.
- */
-resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
-
-/**
- * Read the session override without applying the deployment default.
- * @param session - session whose log supplies the override.
- * @returns the last logged mode, or `undefined` without one.
- */
-overrideOf(session: Session): SandboxMode | undefined
-```
-
-Types: [SandboxExecutionPolicy](../subsystems/sandbox.md) · [SandboxMode](../subsystems/sandbox.md) · [SandboxPolicyRequest](../subsystems/sandbox.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
-
-## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
-
-Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
-
-```ts cordis-catalog
-/**
- * Resolve this backend's independent local artifact for a session without
- * reading, creating, flushing, or otherwise materializing it. Backends such
- * as SQLite that do not own one artifact per session return `undefined`.
- * @param meta - the immutable session header whose artifact is requested.
- * @returns the backend-specific absolute location, when one exists.
- */
-abstract locate(meta: SessionHeader): SessionLocation | undefined
-
-/**
- * Register a new session's metadata. A backend MAY defer the physical write
- * until the first {@link append} (lazy materialization), in which case a
- * created-but-never-appended session is absent from {@link list}
- * — abandoned sessions leave nothing behind.
- * @param meta - the immutable header (id, version, cwd, lineage) to record.
- */
-abstract create(meta: SessionHeader): Promise<void>
-
-/**
- * Durably persist a batch of events. Honors the append-only and contiguous-
- * seq contracts: the first event's `seq` MUST equal the stored next-seq
- * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
- * serializable `event.data` with an error naming the offending event type.
- * @param id - the session the batch belongs to.
- * @param events - the contiguous batch to persist, in seq order.
- */
-abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
-
-/**
- * Prepare the exact unpublished Session used by resume. Implementations may
- * reuse object graphs retained by an earlier {@link inspect} after confirming
- * their durable revision is still current; disposal releases an unpublished
- * reservation. Revision retries require the durable log to remain unchanged
- * for one read/check round trip; continuous external writers may delay completion.
- * @param id - persisted session to prepare.
- * @param signal - optional cancellation for preparation work.
- * @returns one owned unpublished Session preparation.
- */
-async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
-
-/**
- * Load an immutable balanced logical view and commit any required cold
- * recovery. A complete interrupted final turn is preserved and durably
- * closed with missing tool errors plus any open step and turn boundaries;
- * only a torn final record is discarded. Unknown versions and corruption in
- * the committed prefix reject. Implementations MUST NOT crash-repair an
- * identity still bound to a live Session: a balanced live log may return as a
- * durable snapshot, while an open live turn rejects. Returned values may be
- * shared with immutable live or prepared state and must not be mutated.
- * Revision-based implementations may wait for one stable read/check round trip.
- * @param id - the persisted session to reload.
- * @returns the header and a log ending on a balanced `turn/end`.
- */
-abstract load(id: SessionId): Promise<SessionInspection>
-
-/**
- * Inspect an immutable logical session without committing recovery or
- * publishing it. A cold complete interrupted turn receives synthetic closers
- * in memory and a torn physical tail remains untouched. An already-live
- * Session instead yields its current immutable snapshot, which may contain an
- * open turn and its `session/end-seed` boundary. Coordinator-backed
- * implementations retain the exact cold unpublished Session for bounded
- * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
- * already committing or reserved for resume remains exclusive, and inspection
- * may borrow its immutable view. Callers borrow only the immutable header and
- * log. Continuous external writers may delay revision convergence.
- * @param id - the persisted session to inspect.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the validated header and current logical event log.
- */
-abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
-
-/**
- * Read the stored events from `fromSeq` onward — the read-from-seq
- * primitive for read models that resume from a watermark (e.g. a persisted
- * projection cache folding only the tail past its checkpoint). Unlike
- * {@link inspect}, it is a detached physical suffix read: no preparation
- * cache, torn-tail truncation, synthetic closers, or coordinator-state
- * publication. Only events from the valid contiguous stored prefix are
- * returned, so a torn fragment never reaches the caller. `fromSeq` at or
- * beyond the stored prefix returns an empty event list (never an error).
- * Backends whose medium can seek by seq
- * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
- * still parse the whole artifact and skip forward — the primitive bounds
- * what is RETURNED and refolded, not every backend's physical read.
- * @param id - the persisted session to read.
- * @param fromSeq - first event seq to include; a non-negative safe integer.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the header and the stored events with `seq >= fromSeq`.
- */
-abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
-
-/**
- * Lightweight listing from metadata, without a full-log parse.
- * @param signal - optional cancellation for backend listing work.
- * @returns one header per materialized session.
- */
-abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
-
-/**
- * List materialized sessions with cheap per-log change tokens.
- *
- * Repeated observations of an unchanged log return the same revision. A
- * successful mutating {@link load} repair changes the next listed revision.
- * Revisions also distinguish independently backed stores so backend-local
- * counters cannot compare equal across different persistence sources.
- * @param signal - optional cancellation for backend snapshot-listing work.
- * @returns one header and opaque revision per materialized session without loading full logs.
- */
-abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
-```
-
-Types: [SessionEvent](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) · [SessionInspection](../subsystems/persistence.md) · [SessionLocation](../subsystems/persistence.md) · [SessionPersistenceSnapshot](../subsystems/persistence.md) · [SessionPreparation](../subsystems/persistence.md)
-
-Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
-
-## `ctx.sessionProjectionCache` — `SessionProjectionCache`
-
-The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
-
-```ts cordis-catalog
-/**
- * The zero-I/O listing read: whole values viewed straight from the stored
- * rows (version-matching keys only), each cut carried with its watermark
- * so a client value store can seed under its higher-seq-wins rule — as
- * stale as the last durable checkpoint but never wrong, and never from an
- * unrelated log (the caller's header is the identity witness). Fresher
- * paths (the history tail baseline, {@link coldSnapshot}) supersede these
- * values whenever a session is actually opened.
- * @param meta - the listed session's header (identity witness; no log read).
- * @returns the cut (`asOfSeq` = lowest served-row watermark), or
- *   `undefined` when no usable row exists for this lifecycle.
- */
-cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
-
-/**
- * Durably checkpoint one live session NOW (both mandatory points call
- * this; tests and carriers may too). The registry cut is snapshotted at
- * this boundary (states are live references), then the whole record is
- * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
- * @param session - the live session to checkpoint.
- * @returns resolution after durability and event emission.
- */
-async write(session: Session): Promise<void>
-
-/**
- * Cold-read one persisted session's projections with zero full-log load:
- * cached rows + a persistence `readFrom` tail from the registry's restore
- * floor, refolded by the registry and written back (fail-soft) so the next
- * cold read starts closer. A cache row invalidated by a shrunk log
- * (crash-repair truncation) triggers one full re-read from seq 0 — the
- * ladder's slow rung, still no crash. Rejects when the session has no
- * persisted log (`not found` from the persistence seam).
- * @param id - the persisted session to read.
- * @param signal - optional cancellation for the persistence reads.
- * @returns the snapshot cut at the stored log end.
- */
-async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
-```
-
-Types: [Session](../subsystems/session.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
-
-## `ctx.sessionProjections` — `SessionProjectionRegistry`
-
-`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
-
-```ts cordis-catalog
-/**
- * Register one domain's unit. The registration is an effect on the calling
- * context's fiber: disposing the fiber (or calling the returned disposer)
- * removes the key — and the unit's cached cells — from subsequent drives
- * and snapshots.
- * @param definition - key, boundary schema, pure unit functions, and stateVersion.
- * @returns the exact disposer that unregisters this unit.
- */
-register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
-
-/**
- * Subscribe to the change feed. The registration is an effect on the
- * calling context's fiber.
- * @param listener - called once per unit whose state reference changed, per committed event.
- * @returns the exact disposer that unsubscribes.
- */
-onChanged(listener: ProjectionChangeListener): () => void
-
-/**
- * One consistent cut over every registered unit for one session, read from
- * the watermark cache (missing cells fold lazily over the in-memory log).
- * Fully synchronous — every value and `asOfSeq` reflect the same log
- * position. Each value passes its unit's schema before leaving.
- * @param session - the session whose projection values are read.
- * @returns the snapshot; `values` is empty when no unit is registered.
- */
-snapshot(session: Session): ProjectionSnapshot
-
-/**
- * State-level checkpoint of every registered unit for one session, read
- * from the watermark cache (missing cells fold lazily over the in-memory
- * log). This is the write side of the persisted projection cache: the
- * returned rows are the `(key → {ver, seq, val})` part of the durable
- * `(sessionId, key, ver, seq, val)`
- * rows. Every `val` is a DETACHED structured clone — never the live
- * cell reference: the watermark cache is this registry's authoritative
- * mutable state, and a caller reaching the live reference could corrupt
- * every subsequent snapshot and frame through it (plain JSON by the unit
- * contract, so the clone is total).
- * @param session - the session whose unit states are checkpointed.
- * @returns one row per registered key; empty when no unit is registered.
- */
-checkpoint(session: Session): ProjectionCheckpoint
-
-/**
- * The stored seq a {@link restore} tail read over `checkpoint` must start
- * at: one event BELOW the lowest usable watermark (a row is usable when
- * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
- * pulls the floor to `0` — that key must refold the full log). The
- * one-below anchor is load-bearing: the tail then proves how far the
- * stored log still extends, so {@link restore} can detect a log that
- * shrank below a row's watermark (crash-repair truncation) instead of
- * serving the stale row as current — an empty tail read from the anchor
- * yields an end below every watermark and the restore rejects for a full
- * re-read.
- * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @returns the seq to hand the persistence `readFrom`, or `undefined`
- *   when no unit is registered (no read needed — {@link restore} would
- *   serve empty values regardless).
- */
-restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
-
-/**
- * View a checkpoint's rows without any log read: for every registered
- * unit whose row's `ver` matches, serve the schema-validated
- * `view` of the stored state; mismatched or absent rows leave their key
- * absent (a cold or listing consumer treats it as not-yet-available and a
- * fuller read path refolds it). The zero-I/O rung of the read ladder —
- * values are as stale as their rows, never wrong.
- * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @returns whole values per key with a usable row; empty when none.
- */
-viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
-
-/**
- * Cold read: fold every registered unit over a stored log suffix, seeding
- * each from its checkpoint row when usable — the one read recipe (cached
- * state + forward tail replay + `view`) applied without a live `Session`.
- * Call with the events returned by a persistence
- * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
- * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
- * so a shrunk log is detected here. A row is usable iff its
- * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
- * (`seq >= baseSeq - 1`), and it does not claim events past the
- * supplied end (`seq <= endSeq`); an unusable row is discarded
- * and its key refolds from `init` — which is only sound over the full
- * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
- * from seq 0, e.g. after a crash-repair truncation shrank the log below
- * a row's watermark).
- * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @param events - the stored events with `seq >= baseSeq`, in seq order.
- * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
- * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
- *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
- *   refreshed checkpoint rows at that cut, ready for a durable write-back.
- */
-restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
-```
-
-Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
-
-Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
-
-## `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
-
-Unified live-preferred session query service.
-
-Exact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.
-
-```ts cordis-catalog
-/**
- * Search the live-preferred logical corpus and group by session.
- * @param request - query text, metadata filters, page size, and cursor.
- * @param exec - optional cancellation control.
- * @returns session hits ranked by their strongest matching event.
- */
-abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>
-
-/**
- * Search events within one live-preferred logical session.
- * @param request - target session, query text, filters, page size, and cursor.
- * @param exec - optional cancellation control.
- * @returns matching event hits and their target header from one indexed generation.
- */
-abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>
-
-/**
- * List the complete logical corpus using live-preferred records.
- * @param signal - optional cancellation for persistence listing.
- * @returns deterministic newest-first cloned session records.
- */
-listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
-
-/**
- * Read and replay-validate one complete logical session log without making it live.
- * @param sessionId - live or persisted session id to read.
- * @returns cloned header and complete raw event log from one observation.
- * @throws when persistence, header compatibility, or replay validation fails.
- */
-async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
-
-/**
- * Filter the complete logical corpus with provider-independent predicates.
- * @param filters - ANDed session metadata and availability clauses.
- * @param signal - optional cancellation for persistence listing.
- * @returns matching cloned records in deterministic newest-first order.
- */
-async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>
-
-/**
- * Fold the latest log-backed title from one live-preferred logical session.
- * @param sessionId - live or persisted session id to read.
- * @param signal - optional cancellation for source resolution and title folding.
- * @returns latest title snapshot, or `undefined` when the log has no title event.
- */
-async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
-
-/**
- * Fold the latest title and return its source header from one corpus observation.
- * @param sessionId - live or persisted session id to read.
- * @param signal - optional cancellation for source resolution and title folding.
- * @returns cloned source header and optional latest title snapshot.
- */
-async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
-
-/**
- * Fold titles for unique sessions from one cancellable corpus observation.
- *
- * Results preserve first-occurrence input order. Operational failures stay
- * isolated per session, while cancellation rejects the complete operation.
- * @param sessionIds - live or persisted session ids to observe.
- * @param signal - optional cancellation shared by all source reads.
- * @returns one fulfilled or rejected result per unique requested id.
- */
-async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>
-
-/**
- * List lightweight raw-log event records for one logical session.
- * @param sessionId - live-preferred session id to read.
- * @returns event records in ascending seq order.
- */
-async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
-
-/**
- * Scan first-party semantic event documents with provider-independent filters.
- * @param sessionId - live-preferred session id to scan.
- * @param filters - ANDed metadata and literal-text predicates.
- * @returns matching semantic documents in ascending seq order.
- */
-async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>
-
-/**
- * Read one session's complete current model surface from one corpus observation.
- * @param sessionId - live-preferred session id to read.
- * @returns cloned header, current surface, and raw-log capture boundary.
- * @throws when source resolution fails or the session surface is invalid.
- */
-async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
-
-/**
- * Trace known ancestry and descendants from one corpus observation.
- * @param sessionId - logical session id to trace.
- * @param signal - optional cancellation for persistence listing.
- * @returns a complete lineage or an explicit unresolved parent boundary.
- * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
- */
-async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
-
-/**
- * Trace one event's direct positional and provenance relationships.
- * @param request - target session id and event seq.
- * @param signal - optional cancellation for persisted source resolution.
- * @returns source header, direct links, and the target's positional replacement chain.
- * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
- */
-async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
-
-/**
- * Read one full event plus a bounded raw-log context window.
- * @param request - target session/seq and context sizes.
- * @param signal - optional cancellation for persisted source resolution.
- * @returns cloned target and neighboring events.
- */
-async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
-```
-
-Types: [SessionEventReadRequest](../subsystems/session-query.md) · [SessionEventRecord](../subsystems/session-query.md) · [SessionEventResultFilter](../subsystems/session-query.md) · [SessionEventSearchDocument](../subsystems/session-query.md) · [SessionEventSearchPage](../subsystems/session-query.md) · [SessionEventSearchRequest](../subsystems/session-query.md) · [SessionEventTraceObservation](../subsystems/session-query.md) · [SessionEventTraceRequest](../subsystems/session-query.md) · [SessionEventWindow](../subsystems/session-query.md) · [SessionId](../subsystems/core.md) · [SessionLineageTrace](../subsystems/session-query.md) · [SessionLogSnapshot](../subsystems/session-query.md) · [SessionRecord](../subsystems/session-query.md) · [SessionResultFilter](../subsystems/session-query.md) · [SessionSearchExecContext](../subsystems/session-query.md) · [SessionSearchHit](../subsystems/session-query.md) · [SessionSearchPage](../subsystems/session-query.md) · [SessionSearchRequest](../subsystems/session-query.md) · [SessionSurfaceSnapshot](../subsystems/session-query.md) · [SessionTitleObservation](../subsystems/session-query.md) · [SessionTitleObservationResult](../subsystems/session-query.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
-
-Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
-
-## `ctx.sessionReferences` — `SessionReferenceService`
-
-Exact-read consumer that prepares immutable cross-session message context.
-
-```ts cordis-catalog
-/**
- * List reference candidates, ranked by working-directory affinity.
- * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd/title substring.
- * @param limit - optional positive result cap.
- * @param signal - optional cancellation boundary for host autocomplete teardown.
- * @returns candidates labeled by latest title or, when absent, session id.
- */
-async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
-
-/**
- * Snapshot all references before enqueue and return one aggregated durable context.
- * @param agent - target agent; references to it are rejected.
- * @param content - already host-normalized readable message content.
- * @param references - structured source sessions in mention order.
- * @param signal - optional cancellation boundary for host request teardown.
- * @returns detached content and optional referenced-session context.
- */
-async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
-```
-
-Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [PreparedReferencedMessage](../subsystems/session-reference.md) · [SessionReferenceCandidate](../subsystems/session-reference.md) · [SessionReferenceInput](../subsystems/session-reference.md)
-
-Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
-
-## `ctx.sessions` — `SessionStore`
-
-In-memory session store (`ctx.sessions`).
-
-Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
-
-```ts cordis-catalog
-/**
- * Create a session owned by the calling fiber: disposing that fiber stops
- * event notification and removes the session from the store. `options.seed`
- * populates the session with a copy of those events (replay/fork);
- * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
- * and parent lineage, and delegation depth) as the immutable
- * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
- *
- * For an agent whose session must be torn down IN ORDER with its loop (so the
- * loop's final events are published before the store attachment ends), do NOT use this
- * — fold the session lifecycle into the agent's own effect via
- * {@link prepare} + {@link enter} + {@link announce} (see
- * `dsh-agent-loop`'s creation transaction).
- *
- * @param id - the session id; omitted, the store mints `session-<n>`.
- * @param options - seed events and/or creation metadata for the header.
- * @returns the live session, already entered and announced.
- * @throws if a session with `id` already exists, metadata is not a plain
- *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
- *   non-absolute path (storage backends key directories off it).
- */
-create(id?: SessionId, options?: CreateSessionOptions): Session
-
-/**
- * Build a session WITHOUT entering it into the store — validate the id/cwd and
- * construct the {@link Session} (with its immutable {@link SessionHeader}).
- * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
- * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
- * effect so a fiber unload tears the session + agent down as a single ORDERED
- * chain rather than as racing sibling effects — which would remove the publication hooks
- * before the driver's closing events commit, dropping them.
- *
- * @param id - the session id; omitted, the store mints `session-<n>`.
- * @param options - seed events and/or creation metadata for the header. With
- *   `seedSource: 'persistence'`, metadata and events must be fresh detached
- *   graphs whose ownership transfers to this call: they are validated and
- *   frozen in place through {@link Session.fromRestore}, so the caller must
- *   retain no mutable aliases.
- * @returns the constructed session, NOT yet in the store.
- * @throws if a session with `id` already exists, metadata is not a plain
- *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
- *   non-absolute path.
- */
-prepare(id?: SessionId, options?: PrepareSessionOptions): Session
-
-/**
- * Enter a {@link prepare}d session into the store: install the module-private
- * append publication hooks and add it to the store. Returns the DETACH
- * disposer (hooks + store removal). Does NOT emit `session/created` —
- * the caller yields this disposer inside its effect and THEN calls
- * {@link announce}, so a throwing `session/created` listener rolls the attach
- * back instead of leaking it.
- *
- * Re-checks the id for a duplicate: `prepare` and `enter` are public
- * cross-package primitives and a caller may interleave arbitrary work (or
- * another create) between them, so a stale prepared session must NOT overwrite
- * a live store entry of the same id — its detach disposer would later delete
- * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public seam cannot
- * assume that.
- *
- * @param session - a {@link prepare}d session not yet in the store.
- * @returns the detach disposer (publication hooks + store removal). When called from
- *   a synchronous `session/created` listener, removal and disposal wait until
- *   that creation dispatch unwinds.
- * @throws if a session with this id is already in the store.
- */
-enter(session: Session): () => void
-
-/** Emit `session/created` exactly once for an {@link enter}ed session (with
- * the carrier {@link enter} captured). Separate from {@link enter} so the
- * caller can yield the detach disposer first (rollback safety — see
- * {@link enter}).
- * @param session - the entered session to announce to listeners.
- * @throws if the session is not live or its announcement already began,
- *   including a reentrant call from a creation listener. */
-announce(session: Session): void
-
-/**
- * Dispatch the awaited `session/flush` durability checkpoint for `session`,
- * with the carrier captured at {@link enter}. THE flush entry point: the
- * store owns the carrier, so callers (the checkpoint policy's per-request
- * barrier, goal-session's idle checkpoint, teardown drains, and consumers
- * that flush themselves before reading storage) must come through here
- * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
- * one spelling, and the scoped-dispatch invariant can pin it.
- * @param session - the session whose buffered events must reach durable storage.
- * @returns whether at least one durability listener participated, after every
- *   listener has settled successfully.
- * @throws the first registered listener failure after every listener settles.
- */
-async flush(session: Session): Promise<boolean>
-
-/**
- * Look up a live session.
- * @param id - the session id to look up.
- * @returns the session, or undefined when no live session has that id.
- */
-get(id: SessionId): Session | undefined
-
-/**
- * All live sessions, in creation order.
- * @returns a fresh array; mutating it does not affect the store.
- */
-list(): Session[]
-
-/**
- * Create a live child session from a stable prefix of a live source.
- * `boundary` is an inclusive source event seq; omitted means the source's
- * current last event. The selected slice may end with a between-turn event
- * but must not end inside an open turn.
- *
- * @param source - Live source session object or id.
- * @param boundary - Inclusive source event seq to fork through; omitted means
- *   the source's current last event, and omitted on an empty source forks an
- *   empty child.
- * @param childSessionId - Optional child session id; omitted delegates to
- *   `SessionStore`'s id policy.
- * @returns The created live child session.
- */
-fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
-```
-
-Types: [CreateSessionOptions](../subsystems/persistence.md) · [PrepareSessionOptions](../subsystems/persistence.md) · [Session](../subsystems/session.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
-
-## `ctx.sessionTitle` — `SessionTitleService`
-
-Log-backed title fold plus asynchronous fallback generation.
-
-```ts cordis-catalog
-/**
- * Read the latest folded title from one live or replayed session.
- * @param session - session whose log is the title source of truth.
- * @returns latest title snapshot, or `undefined` before eligible input.
- */
-get(session: Session): SessionTitleSnapshot | undefined
-
-/**
- * Accept an explicit user title. Appends a `session/title` event with the
- * `user` source, which pins the title: in-flight automatic generation is
- * superseded and later user messages schedule none (an explicit
- * {@link SessionTitleService.refresh} remains the deliberate unpin).
- * @param session - exact live session to rename.
- * @param title - raw user input; normalized before acceptance.
- * @returns the accepted title snapshot.
- * @throws {SessionTitleInvalidError} when the title normalizes to empty.
- * @throws {Error} when the session is not live or the service is disposed.
- */
-rename(session: Session, title: string): SessionTitleSnapshot
-
-/**
- * Explicitly retry the registered provider, or materialize the built-in
- * fallback when no provider is registered.
- * @param session - exact live session to refresh.
- * @param signal - optional caller cancellation.
- * @returns latest accepted title, or `undefined` when no eligible text exists.
- */
-async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
-
-/**
- * Register the sole optional title provider. Disposal aborts its pending and
- * active work before another provider may register.
- * @param provider - provider identity, cadence, and generation function.
- * @returns exact Cordis effect disposer, which settles after active calls quiesce.
- */
-register(provider: SessionTitleProvider): () => Promise<void>
-```
-
-Types: [Session](../subsystems/session.md) · [SessionTitleProvider](../subsystems/session-title.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
-
-Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
-
-## `ctx.settings` — `Settings` (abstract seam)
-
-Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
-
-```ts cordis-catalog
-/**
- * Prepare the provider's user-editable document for a native editor. File
- * providers may materialize an absent document before returning its path;
- * non-file providers return undefined.
- * @returns the absolute local document path, or undefined for non-file storage.
- */
-prepareDocument(): Promise<string | undefined>
-
-/**
- * Register a namespace schema and receive its owner scope. The registration
- * is an effect on the calling plugin's fiber: disposing that fiber removes
- * the namespace and its observers. An invalid stored section fails the
- * registration itself — the earliest point where the schema can judge it.
- * @param ns - unique namespace; duplicate registration fails loud.
- * @param schema - schemastery schema resolving this namespace's value.
- * @param options - composition `base` layer and effect timing.
- * @returns the owner scope for reads, observation, and updates.
- */
-register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
-
-/**
- * Describe every registered namespace for configuration surfaces, including
- * the composition `base` and raw user layers so a form can mark which fields
- * the user overrode (presence in `user`) and what a reset returns to.
- * @param options - redaction switch; wire surfaces must redact.
- * @returns one descriptor per registered namespace, in registration order.
- */
-describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
-
-/**
- * Read one registered namespace's resolved value.
- * @param ns - the namespace to read.
- * @returns the resolved value, or `undefined` while unregistered.
- */
-get(ns: SettingsNamespace): unknown
-
-/**
- * Merge a patch into one registered namespace's user layer, validate the
- * resolved candidate, persist through the provider, then commit and emit.
- * A validation failure rejects before anything is persisted. Writes to one
- * namespace are serialized: concurrent updates apply in call order, each
- * merging over the previous write's committed section.
- * @param ns - the registered namespace to update.
- * @param patch - plain-object patch over the user section.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- */
-async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
-
-/**
- * Replace one registered namespace's user section wholesale, validate,
- * persist, then commit and emit. Keys absent from `section` fall back to the
- * composition `base` and schema defaults — this is the removal/reset path a
- * merge-only patch cannot express (`replace({})` re-inherits everything).
- * @param ns - the registered namespace to replace.
- * @param section - the complete next user section.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- */
-async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
-
-/**
- * Apply path-addressed edits to one registered namespace's user section,
- * validate, persist, then commit and emit. The ops are applied to the
- * section as it stands when the write reaches the front of the queue, so a
- * caller never has to restate fields it did not touch — and, crucially,
- * cannot delete fields it never saw. This is the write path for any caller
- * holding a redacted view; `replace` remains the wholesale reset.
- * @param ns - the registered namespace to edit.
- * @param ops - ordered path edits; later ops observe earlier ones.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- */
-async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
-```
-
-Types: [SettingsDescribeOptions](../subsystems/settings.md) · [SettingsDescriptor](../subsystems/settings.md) · [SettingsNamespace](../subsystems/settings.md) · [SettingsPathOp](../subsystems/settings.md) · [SettingsRegisterOptions](../subsystems/settings.md) · [SettingsScope](../subsystems/settings.md)
-
-Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
-
-## `ctx.skills` — `SkillService`
-
-Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted invocation-neutral summaries, and loads full skill bodies on demand.
-
-```ts cordis-catalog
-/**
- * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
- * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
- * the provider and invalidates catalog caches.
- * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
- * @returns the exact Cordis effect disposer that unregisters this provider;
- *   composite effects may yield it directly to preserve teardown ordering.
- */
-registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
-
-/**
- * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
- * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
- * receives a no-op disposer so it cannot remove the winner.
- * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
- * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
- */
-register(skill: SkillRegistration): () => void
-
-/**
- * List invocation-neutral skill summaries for a workspace. Consumers apply
- * model or user invocation policy at their operational boundary. Lookup
- * options and provider candidates are readonly same-process values borrowed
- * throughout discovery.
- * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
- * @returns all sorted winning summaries.
- */
-async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
-
-/**
- * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
- * Incomplete observations are never cached, allowing consumers to retain last-good state and
- * retry on their next request boundary.
- * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
- * @returns sorted summaries plus discovery-completeness state.
- */
-async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
-
-/**
- * Load and validate the winning candidate, passing its opaque discovery locator back to the
- * provider. Cancellation is rechecked after selection, including cache hits, and raced against
- * loading so an uncooperative provider cannot hang the caller.
- * @param name - kebab-case skill name.
- * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
- * @returns the full skill, including body content, or `undefined`.
- */
-async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
-```
-
-Types: [SkillCatalogSnapshot](../subsystems/skills.md) · [SkillDefinition](../subsystems/skills.md) · [SkillLookupOptions](../subsystems/skills.md) · [SkillProvider](../subsystems/skills.md) · [SkillProviderControl](../subsystems/skills.md) · [SkillRegistration](../subsystems/skills.md) · [SkillSummary](../subsystems/skills.md)
-
-Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
-
-## `ctx.spillStore` — `SpillStore` (abstract seam)
-
-Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
-
-Semantics every implementation must honor:
-
-- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
-- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
-- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
-
-```ts cordis-catalog
-/**
- * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, provenance, suggested name, and full text to save.
- * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
- */
-abstract saveText(input: SaveTextSpill): Promise<SpillRef>
-```
-
-Types: [SaveTextSpill](../subsystems/spill.md) · [SpillRef](../subsystems/spill.md)
-
-Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
-
-## `ctx.storage` — `Storage`
-
-The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
-
-```ts cordis-catalog
-/**
- * Mount a data-form facility on the hub. Mounting is an effect: the
- * returned disposer unmounts the form.
- * @param form - Form key declared in {@link StorageForms}.
- * @param facility - The facility instance to expose.
- * @returns the disposer that unmounts the form.
- */
-mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void
-
-/**
- * Resolve a mounted data form.
- * @param form - Form key declared in {@link StorageForms}.
- * @returns the mounted facility.
- */
-form<K extends keyof StorageForms>(form: K): StorageForms[K]
-```
-
-Types: [StorageForms](../subsystems/storage.md)
-
-Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
-
-## `ctx.storageDomain` — `DomainFacility`
-
-The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.
-
-```ts cordis-catalog
-/**
- * Open one declared domain. Steps, each failing the whole call: reject a
- * name that is already open (`already-open`); resolve the backend route
- * (`backend-not-found` passes through from the hub); require its `kv` facet
- * (`facet-unsupported`); open the unit projected from the spec (backend
- * `version-mismatch`/`malformed-medium` pass through); load and validate
- * every stored record against the spec's zod schemas (`invalid-record`
- * with the offending table and key); construct the domain.
- *
- * Lifecycle: the CALLER owns the returned handle and closes it via
- * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
- * facility does not tie the domain to any consumer fiber. Domains still
- * open when the facility unmounts are closed by the plugin disposer.
- * @param spec - The domain declaration, typically from `defineDomain`.
- * @returns the opened domain handle, typed by the spec.
- */
-async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>
-
-/**
- * Look up an open domain by name, untyped. Diagnostic surface (the package
- * invariant cross-checks change events against live domain state); typed
- * consumers hold the handle returned by {@link open}.
- * @param name - Domain name.
- * @returns the open domain runtime, or `undefined` when not open.
- */
-get(name: string): DomainImpl | undefined
-
-/**
- * Close every domain still open on this facility. The unmount path for
- * consumers that never called `Domain.close()` themselves; closing is
- * idempotent, so double-closing an already-closed domain is harmless.
- * @returns resolution after every unit is released.
- */
-async closeAll(): Promise<void>
-```
-
-Types: [Domain](../subsystems/storage.md) · [DomainSpec](../subsystems/storage.md)
-
-Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
-
-## `ctx.subagents` — `SubagentService`
-
-Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
-
-```ts cordis-catalog
-/**
- * Establish one durable continuable child and deliver its initial prompt.
- * Resolves when the child's inbox accepts that prompt, without waiting for the
- * turn to start or for the message to reach the Session log; any earlier
- * failure rejects with no ids and rolls back the child entirely.
- * @param spec - provider, delegation request, and caller cancellation.
- * @returns the durable child id and the accepted prompt's message id.
- * @throws when continuation services are unavailable or materialization fails.
- */
-async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
-
-/**
- * Deliver one later message to a continuable child as its next FIFO turn. A
- * resident child's Agent inbox accepts it directly (waking a `waiting`
- * Activation), while an absent one is cold-resumed from its persisted
- * Session. The Agent inbox is the only queue, so every accepted message has
- * one observable order.
- * @param parent - the exact live direct parent authorizing this delivery.
- * @param childId - durable child session id.
- * @param content - user-role content to deliver.
- * @param options - durable provenance and caller cancellation, which stops the
- *   operation only before inbox acceptance.
- * @returns the accepted message's inbox id.
- * @throws when continuation services are unavailable, parent authority is
- *   rejected, or the message was not admitted.
- */
-async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
-
-/**
- * Interrupt one live continuable child's current turn under a human parent
- * address or an exact live ancestor Agent. Fire-and-return: the cancel
- * signal is issued before this returns, but the target may keep running
- * until it observes the signal. Unclaimed pending inbox work, the Activation,
- * and published descendants are preserved; claimed work is not requeued.
- * Once the interrupted driver is idle, a waking send resumes the parked FIFO
- * queue. An absent target — including a one-shot or unknown id —
- * is an accepted no-op, as is a manager-less composition, which cannot own a
- * live Activation.
- * @param targetSessionId - the durable child session id to interrupt.
- * @param authority - the human parent address or exact live ancestor Agent.
- * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
- *   live target.
- */
-interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
-
-/**
- * Deliver selected content from one live continuable child to its durable
- * direct parent. The child is the authority credential; callers cannot name a
- * recipient. Reporting does not conclude the child's turn or Activation.
- * @param child - exact live reporting child.
- * @param content - selected model-facing content.
- * @param options - parent scheduling and pre-acceptance cancellation.
- * @returns the stable identity of the parent-accepted message.
- * @throws when continuation services are unavailable, sender authorization
- *   fails, or the direct parent is not live.
- */
-async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>
-
-/**
- * Compose one deployment capability into every continuable child's
- * unpublished creation context on fresh creation and cold resume. Grants wait
- * for the next Activation; removing the contribution revokes every resident
- * installation immediately.
- * @param contribution - synchronous child-scope installer.
- * @returns the exact Cordis effect disposer.
- */
-registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
-
-/**
- * Close continuable admission below exact live parent Agents, stop only their
- * visible descendant Activations synchronously, then await admitted scoped
- * materializations and release those forests child-first. The scoped cutoff
- * lasts until each exact parent leaves the registry; unrelated parent trees
- * remain live.
- * @param parents - exact host-owned parent Agents entering teardown.
- * @returns once every retained descendant Activation released its `AgentHandle`.
- * @throws an aggregate error after all branches settle when any failed.
- */
-async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
-
-/**
- * Enumerate the parent's direct session-backed subagents without loading or
- * resuming an Agent and without any query seam: the listing merges the live
- * session store with optional session persistence (live-preferred) and
- * serves each child's durable mode/label from the registered `subagent`
- * projection unit down a three-rung ladder — the registry's watermark
- * snapshot for a live child; for a cold one, a durable projection-cache
- * row when the optional cache serves an own-suffix identity (its `seq`
- * gate proves the value postdates the fork seed, where a child's own
- * descriptor is immutable once appended), else one persistence inspection
- * folded through the registry. The
- * projection fold is the single classification authority; per-child
- * diagnostics relay a fold that served no identity or a failed inspection,
- * never a list-time descriptor parse. Absent persistence, enumeration is
- * live-only (a cold child cannot be resumed then either, so its absence is
- * capability absence, not an error). This service consults no Agent
- * registrations, Activations, or providers.
- *
- * Every persistence read receives `signal`, and the listing rechecks
- * cancellation around each of those awaits. Read rejections that settle
- * after an abort become a stable `SubagentError` with code `CANCELLED`.
- * @param parentSessionId - parent session whose direct children are listed.
- * @param signal - caller-owned cancellation forwarded to persistence reads
- *   and observed around every read await.
- * @returns children and per-child diagnostics ordered by `createdAt`, then id.
- * @throws {@link SubagentError} when the projection registry or the session
- *   store is not mounted, or the caller cancels the listing.
- */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
-
-/**
- * Enumerate the root's complete session-backed subagent tree in stable
- * pre-order from one live-preferred corpus, without loading or resuming an
- * Agent. Ordinary sessions and one-shot children remain traversal nodes so
- * continuable descendants below them are discovered; each returned entry
- * adds its durable `parentId` and root-relative `depth`. Identity resolution,
- * diagnostics, optional persistence, and cancellation follow the same
- * projection-backed contract as {@link listChildren}.
- * @param rootSessionId - session whose complete descendant tree is listed.
- * @param signal - caller-owned cancellation forwarded to persistence reads
- *   and observed around every read await.
- * @returns children and per-candidate diagnostics with tree position, in
- *   stable pre-order.
- * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
- */
-listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
-
-/**
- * Register a provider under its name. Registration is effect-scoped and HMR
- * safe; removing a provider blocks new starts but does not revoke runs that
- * were already returned to their holders.
- * @param provider - the trusted provider implementation.
- * @returns the exact Cordis effect disposer.
- */
-registerProvider(provider: SubagentProvider): () => void
-
-/**
- * Look up a provider by name.
- * @param name - the provider name.
- * @returns the provider, or undefined when absent.
- */
-getProvider(name: string): SubagentProvider | undefined
-
-/**
- * List registered provider names in insertion order.
- * @returns the registered names.
- */
-list(): string[]
-
-/**
- * Establish a published child on the named provider. Capability and semantic
- * checks run before delegation. Provider ownership lasts until its promise
- * fulfills; a rejection therefore has no run for the caller to dispose and
- * emits no run lifecycle events. Post-publication turn and infrastructure
- * failures settle through the returned run.
- * @param name - the provider to use.
- * @param request - child label, prompt, parent, signal, and optional capabilities.
- * @returns the published holder-owned run.
- */
-async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
-```
-
-Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [ContinuableSetupContribution](../subsystems/subagent.md) · [ContinuableStart](../subsystems/subagent.md) · [ContinuableStartSpec](../subsystems/subagent.md) · [MessageId](../subsystems/core.md) · [SessionId](../subsystems/core.md) · [SubagentDescendantListEntry](../subsystems/subagent.md) · [SubagentFollowupOptions](../subsystems/subagent.md) · [SubagentInterruptAuthority](../subsystems/subagent.md) · [SubagentListEntry](../subsystems/subagent.md) · [SubagentProvider](../subsystems/subagent.md) · [SubagentReportOptions](../subsystems/subagent.md) · [SubagentRun](../subsystems/subagent.md) · [SubagentStartRequest](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
-
-## `ctx.subprocess` — `SubprocessService` (abstract seam)
-
-Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Executable paths belong to one execution world shared with the mounted filesystem provider.
-- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
-- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
-- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
-- Disposal of the service terminates all still-running managed processes and awaits their exit.
-- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
-
-```ts cordis-catalog
-/**
- * Resolve one configured executable in this provider's execution world.
- * Absolute paths are verified; bare names use the provider's scrubbed PATH
- * plus explicit environment overrides. Relative paths containing separators
- * are rejected: no current consumer defines which directory they would
- * resolve against, so providers fail loud instead of guessing.
- * @param command - absolute executable path or bare PATH name.
- * @param env - explicit environment entries used for lookup.
- * @param signal - aborts remote or local lookup.
- * @returns a canonical executable path.
- */
-abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
-
-/**
- * Start one managed child process from a fully-specified spec; this seam
- * applies no defaults.
- * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
- * @returns the live process handle (streams/readers, signalling, outcome promise).
- */
-abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
-
-/**
- * Allocate a real terminal and start one owned process session. This is the
- * only non-pipe process primitive: implementations own terminal byte I/O,
- * foreground groups, signals, and complete session-tree cleanup.
- * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
- * @returns the live terminal handle after allocation succeeds.
- */
-abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
-```
-
-Types: [SubprocessHandle](../subsystems/subprocess.md) · [SubprocessSpawnSpec](../subsystems/subprocess.md) · [SubprocessTerminalHandle](../subsystems/subprocess.md) · [SubprocessTerminalSpawnSpec](../subsystems/subprocess.md)
-
-Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
-
-## `ctx.systemPrompt` — `SystemPrompt`
-
-Registry service for the prompt inputs assembled before each model step.
-
-```ts cordis-catalog
-/**
- * Register an ordered prompt section in the calling context's scope. A scoped
- * section shadows a global section with the same name; duplicates within one
- * layer and non-finite orders throw. Registration and disposal emit
- * `system-prompt/change`.
- * @param section - the section to register.
- * @returns the exact Cordis effect disposer.
- */
-section(section: PromptSection): () => void
-
-/**
- * Register ordered dynamic context in the calling context's scope. Scoped
- * entries shadow global entries with the same name.
- * @param context - the context contribution to register.
- * @returns the exact Cordis effect disposer.
- */
-context(context: PromptContext): () => void
-
-/**
- * Register a tool-schema provider in the calling context's scope. Global and
- * matching scoped providers both contribute; returning the reserved
- * {@link TOOL_ORDER_REST} name makes assembly fail.
- * @param provider - evaluated for each assembly with its context.
- * @returns the exact Cordis effect disposer.
- */
-tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
-
-/**
- * Register a prompt variable in the calling context's scope. Scoped values
- * shadow globals; invalid or duplicate names throw. A provider may return
- * `undefined`, but rendering a section that references that value then fails.
- * @param name - the `[a-z][a-z0-9_]*` reference name.
- * @param provider - evaluated for each assembly.
- * @returns the exact Cordis effect disposer.
- */
-variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
-
-/**
- * Assemble global and scoped providers, detach tool parameters, apply
- * canonical ordering, then run the assembly waterfall. Scoped sections and
- * variables shadow globals; the returned waterfall value is authoritative.
- * @param context - the optional scope and plugin-defined assembly fields.
- * @returns the authoritative post-waterfall assembly.
- */
-async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
-```
-
-Types: [AssembleContext](../subsystems/system-prompt.md) · [PromptContext](../subsystems/system-prompt.md) · [PromptSection](../subsystems/system-prompt.md) · [ToolProviderResult](../subsystems/system-prompt.md)
-
-Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
-
-## `ctx.tasks` — `TaskService` (abstract seam)
-
-Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
-- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
-- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
-- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
-
-```ts cordis-catalog
-/**
- * Preflight access, validation, and owner cleanup before starting and
- * atomically registering work. A throwing starter leaves nothing registered;
- * after it returns, registration cannot fail. Settlement records the outcome,
- * notifies listeners, and releases waiters.
- * @param spec - task identity, owner, and synchronous starter.
- * @returns the registry-issued `<kind>-N` id.
- */
-abstract start(spec: TaskStart): TaskId
-
-/**
- * List caller-owned and unowned tasks in registration order without exposing
- * another session's labels.
- * @param caller - reading agent; a non-agent caller sees only unowned tasks.
- * @returns fresh snapshots.
- */
-abstract list(caller?: Agent): TaskSnapshot[]
-
-/**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign task.
- * @param id - task to look up.
- * @param caller - reading agent checked against the owner.
- * @returns a fresh snapshot.
- */
-abstract get(id: TaskId, caller?: Agent): TaskSnapshot
-
-/**
- * Read the next stream delta, or the idempotent final output after settlement.
- * A terminal read marks the task reported. Throws for an unknown or foreign
- * task.
- * @param id - task to read.
- * @param caller - reading agent checked against the owner.
- * @returns output text and the post-read snapshot.
- */
-abstract read(id: TaskId, caller?: Agent): TaskRead
-
-/**
- * Request cancellation, then mark the task stopping and reported. A producer
- * throw propagates without changing task state. Throws for an unknown or
- * foreign task.
- * @param id - task to cancel.
- * @param caller - killing agent checked against the owner.
- * @param reason - logged reason forwarded to the producer.
- * @returns `requested` for live work, otherwise `already-finished`.
- */
-abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
-
-/**
- * Wait for settlement or timeout without cancelling the task. Caller abort
- * rejects only while the task is live; after settlement the terminal
- * snapshot wins so a notice suppressed for this waiter is still delivered.
- * Throws for invalid, unknown, or foreign input.
- * @param id - task to wait for.
- * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
- * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
- */
-abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
-
-/**
- * Register an effect-scoped completion listener. Each listener is contained;
- * returned promises are observed but not awaited. No listener runs after
- * service disposal.
- * @param listener - receives each terminal snapshot and its exact owner.
- * @returns disposer that unregisters the listener.
- */
-abstract onTaskDone(listener: TaskDoneListener): () => void
-
-/**
- * Attach an effect-scoped surface that can read and stop tasks. {@link start}
- * refuses work while none is attached.
- * @param name - diagnostic label; duplicate names remain independent.
- * @returns disposer that detaches this surface.
- */
-abstract attachSurface(name: string): () => void
-```
-
-Types: [Agent](../subsystems/core.md) · [TaskDoneListener](../subsystems/tasks.md) · [TaskId](../subsystems/tasks.md) · [TaskRead](../subsystems/tasks.md) · [TaskSnapshot](../subsystems/tasks.md) · [TaskStart](../subsystems/tasks.md)
-
-Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
-
-## `ctx.telemetry` — `Telemetry` (abstract seam)
-
-The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
-
-```ts cordis-catalog
-/**
- * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
- * @param record - the logical record to report; owned by the backend after the call.
- */
-abstract emit(record: TelemetryRecord): void
-
-/** See {@link TelemetryBackend.flush}. */
-flush?(): void
-
-/**
- * See {@link TelemetryBackend.shutdown}.
- * @returns resolves when the backend's pipeline has quiesced.
- */
-abstract shutdown(): Promise<void>
-```
-
-Types: [TelemetryRecord](../subsystems/telemetry.md)
-
-Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
-
-## `ctx.tokenMeter` — `TokenMeterService`
-
-Replay owner for one service-wide estimator and isolated per-session folds.
-
-```ts cordis-catalog
-/**
- * Measure current request pressure and surface through the durable tail.
- *
- * Provider usage is reused only when the latest successful call's canonical
- * request envelope matches `requestHeader` and its total is no lower than
- * that call's full heuristic anchor; otherwise the complete envelope and
- * surface are heuristically repriced.
- *
- * `requestHeader` affects request pressure only; surface fields always
- * describe the current session surface. Every call clones those positional
- * nodes, so measurement is O(surface).
- *
- * @param session - session to replay through its current durable tail.
- * @param requestHeader - optional effective request envelope replacing the latest logged header.
- * @returns a detached deeply immutable pressure and surface measurement.
- */
-measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
-
-/**
- * Heuristically price one model-visible message (instance face of the pure
- * `estimateMessage` export from `estimate.ts`).
- * @param message - message to price without mutation.
- * @returns content and role-framing tokens under the fixed service heuristic.
- */
-estimateMessage(message: Message): number
-```
-
-Types: [EpochHeader](../subsystems/session.md) · [Message](../subsystems/core.md) · [Session](../subsystems/session.md) · [TokenMeasurement](../subsystems/token-meter.md)
-
-Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
-
-## `ctx.toolResultPrune` — `ToolResultPruneService`
-
-Deterministic head/middle/tail pruning for current tool-result surface nodes.
-
-```ts cordis-catalog
-/**
- * Measure text content in Unicode code points; non-text blocks cost zero.
- * @param blocks - tool-result content to measure.
- * @returns total Unicode code points across text blocks.
- */
-measureContent(blocks: readonly ContentBlock[]): number
-
-/**
- * Replace an over-budget text middle while retaining rich-block order.
- * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
- * boundary cannot split a surrogate pair. Grapheme clusters may still split.
- * @param blocks - original tool-result content.
- * @returns pruned content, or `null` when the text is within budget.
- */
-pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
-
-/**
- * Prune every over-budget tool result from one stable current-surface snapshot.
- * Each replacement preserves the complete event data except for `content`,
- * points at the shadowed node for durable provenance and replay, and is
- * immediately preceded by a `compact/prune` shadow-price event pricing the
- * shadowed node through the injected token meter, so pure consumers can
- * subtract it without per-node state.
- * @param session - session whose current surface is rewritten.
- * @returns landed replacements and aggregate Unicode-code-point savings.
- * @throws when the session rejects a replacement; replacements committed
- * earlier in the pass remain durable.
- */
-pruneSession(session: Session): PruneResult
-```
-
-Types: [ContentBlock](../subsystems/core.md) · [PruneResult](../subsystems/compaction.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
-
-## `ctx.tools` — `ToolRegistry`
-
-Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
-
-```ts cordis-catalog
-/**
- * Register globally or in the calling agent scope. Scoped tools shadow
- * globals; duplicates within one layer and the reserved `run_code` name fail.
- * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
- * @returns the exact disposer that unregisters the tool.
- */
-register(definition: ToolDefinition): () => void
-
-/**
- * Restrict global tools for the calling agent scope. Empty filters, unknown
- * names, scope-local names, and reserved transport names fail. Restrictions
- * intersect; scoped registrations remain visible.
- * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
- * @returns the exact disposer that lifts this restriction.
- */
-restrict(filter: ToolRestriction): () => void
-
-/**
- * Register a monotonic guard after the extensible `tools/pre-execute`
- * waterfall. A plain-context guard applies globally; one registered through
- * `agent.ctx` applies only to that agent. Any matching guard may deny by
- * returning a reason, while no guard can force-allow a call another guard
- * denied. The exact effect disposer is returned for ordered ownership and
- * HMR cleanup.
- * @param guard - synchronous check; a returned string denies the execution.
- * @returns the exact disposer that unregisters the guard.
- */
-guard(guard: ToolGuard): () => void
-
-/**
- * Look up a tool as one scope sees it (scoped
- * shadows global; a restricted-away global reads as absent). Presenters pass
- * the calling agent so the rendered card matches the definition that
- * actually executed.
- * @param name - the tool name as registered.
- * @param scope - the viewing scope (the agent); omitted = the global view.
- * @returns the definition the scope resolves, or undefined when none is visible.
- */
-get(name: string, scope?: ScopeKey): ToolDefinition | undefined
-
-/**
- * Project visible definitions onto the allowlisted model-facing schema fields,
- * excluding execution and presentation callbacks.
- * @param scope - the viewing scope (the agent); omitted = the global view.
- * @returns one deep-cloned schema per visible tool.
- */
-schemas(scope?: ScopeKey): ToolSchema[]
-
-/**
- * Classify a pending call through the caller's visible tool definition. Only
- * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
- * throwing classifiers are exclusive.
- * @param exec - call name, parsed arguments, and optional agent scope.
- * @returns the fail-closed scheduling mode.
- */
-executionMode(exec: ToolExecutionInput): ToolExecutionMode
-
-/**
- * Execute through pre-policy, guards, around-dispatch, post-policy,
- * definition-owned content finalization, and final notification. Tool and
- * listener failures resolve as materialized error results; an invisible tool
- * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
- * snapshot final observers receive. Cancellation
- * arriving after entry and before final result materialization skips a
- * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
- * successful started outcome with `ABORTED`; already-started work is still
- * drained and may retain a tool-owned structured error.
- * @param exec - the typed same-process call input. The registry assigns its
- *   correlation token before policy begins.
- * @returns the materialized final result.
- */
-async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
-```
-
-Types: [ScopeKey](../subsystems/scope.md) · [ToolDefinition](../subsystems/tools.md) · [ToolExecutionInput](../subsystems/tools.md) · [ToolExecutionMode](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolGuard](../subsystems/tools.md) · [ToolRestriction](../subsystems/tools.md) · [ToolSchema](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
-
-## `ctx.typert` — `TypertRegistry`
-
-Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
-
-```ts cordis-catalog
-/**
- * Register one generated contribution atomically for the calling fiber.
- * Duplicate package-face identities, schemas, invocation ids, or endpoints
- * reject the whole batch.
- * @param contribution - generated schemas, reflection, and Host invocations.
- * @returns the exact effect disposer that removes this contribution.
- */
-register(contribution: TypertContribution): TypeRTDisposer
-
-/**
- * Look up one schema by `<package>#<name>`.
- * @param key - global schema key.
- * @returns the live schema record, or `undefined` when absent.
- */
-get(key: string): TypertSchemaRecord | undefined
-
-/**
- * Resolve one required schema.
- * @param key - global schema key.
- * @returns the live schema record.
- * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
- */
-resolve(key: string): TypertSchemaRecord
-
-/**
- * Enumerate live schemas in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching schema records.
- */
-list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
-
-/**
- * Look up generated reflection for one package face.
- * @param packageName - exact npm package name.
- * @param face - face to query; defaults to the host runtime.
- * @returns the live package record, or `undefined` when absent.
- */
-getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
-
-/**
- * Enumerate generated package reflection in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching package records.
- */
-listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
-
-/**
- * Project a live Zod schema to JSON Schema without caching the result.
- * @param key - global schema key.
- * @param params - Zod projection parameters.
- * @returns a fresh JSON Schema document.
- */
-toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
-```
-
-Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
-
-## `ctx.typertGateway` — `TypertGatewayService`
-
-Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
-
-```ts cordis-catalog
-/**
- * Invoke one live Remote method through strict generated reflection or SRC markers.
- * @param request - decoded endpoint and exact named wire arguments.
- * @returns the validated business result.
- * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
- */
-async invoke(request: InvokeRemoteRequest): Promise<unknown>
-```
-
-Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
-
-## `ctx.userInteraction` — `UserInteractionService`
-
-`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
-
-```ts cordis-catalog
-/**
- * Register the UI provider. Only one provider may be active in a context.
- *
- * @param provider UI-side implementation that collects answers.
- * @returns Disposer that unregisters this provider.
- */
-registerProvider(provider: UserInteractionProvider): () => void
-
-/**
- * Ask the active UI provider and wait for the user's answer.
- *
- * When a caller supplies an agent, human interaction is valid only for the
- * exact live runtime root. Runtime ownership, not durable session lineage,
- * decides this boundary: an owned child has no human answerer and would
- * block forever, while a lineage-bearing session resumed as a new runtime
- * root may ask normally.
- *
- * @param request Questions, owner agent, and abort signal.
- * @returns The answer chosen or typed by the human.
- * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
- *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
- *   when that live agent is owned by another agent.
- */
-async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
-```
-
-Types: [AskUserQuestionAnswer](../subsystems/user-interaction.md) · [AskUserQuestionRequest](../subsystems/user-interaction.md) · [UserInteractionProvider](../subsystems/user-interaction.md)
-
-Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
-
-## `ctx.web` — `WebService`
-
-The web access service. Registered as `ctx.web` (one instance per context).
-
-Selection semantics (resolved at execution time, never order-dependent):
-
-- A configured id that is registered and `available()` → that provider.
-- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
-- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
-- No id configured, exactly one registered usable provider → that provider.
-- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
-- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
-
-```ts cordis-catalog
-/**
- * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
- * if its id is already registered for search. Returns a disposer; disposed
- * with the calling fiber.
- * @param provider - the provider; its `id` is the registry key.
- * @returns the disposer that unregisters the provider.
- */
-registerSearchProvider(provider: WebSearchProvider): () => void
-
-/**
- * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
- * if its id is already registered for fetch. Returns a disposer; disposed
- * with the calling fiber.
- * @param provider - the provider; its `id` is the registry key.
- * @returns the disposer that unregisters the provider.
- */
-registerFetchProvider(provider: WebFetchProvider): () => void
-
-/**
- * Run one search through the selected provider. Resolves the provider at call
- * time with the selection rules above; throws {@link WebError} when the
- * capability cannot run. The seam enforces `request.maxResults` on the result:
- * if the provider over-returns, `sources[]` is truncated and `truncated` set.
- * @param request - the query plus result-shaping options.
- * @param signal - optional cancellation signal forwarded to the provider.
- * @returns the provider's results, capped to `request.maxResults`.
- */
-async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
-
-/**
- * Retrieve one URL through the selected provider. Resolves the provider at
- * call time with the selection rules above; throws {@link WebError} when the
- * capability cannot run. A non-2xx response is a result, not a throw.
- * @param request - the URL plus retrieval options.
- * @param signal - optional cancellation signal forwarded to the provider.
- * @returns the retrieval outcome; non-2xx responses resolve descriptively.
- */
-async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
-```
-
-Types: [WebFetchProvider](../subsystems/web.md) · [WebFetchRequest](../subsystems/web.md) · [WebFetchResult](../subsystems/web.md) · [WebSearchProvider](../subsystems/web.md) · [WebSearchRequest](../subsystems/web.md) · [WebSearchResult](../subsystems/web.md)
-
-Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
-
-## `ctx.workflows` — `WorkflowService` (abstract seam)
-
-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
-
-```ts cordis-catalog
-/**
- * Parse and execute a workflow script.
- * @param request - the script, its `args`, the parent agent, and an
- *   optional cancel signal.
- * @returns the live run; its `result` resolves when the script settles.
- */
-abstract start(request: WorkflowStartRequest): WorkflowRun
-```
-
-Types: [WorkflowRun](../subsystems/workflow.md) · [WorkflowStartRequest](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
-
-## `ctx.workspace` — `WorkspaceRegistry`
-
-Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
-
-```ts cordis-catalog
-/**
- * Create or reuse a workspace for an existing directory. The path is
- * canonicalized through `fs.realpath`; a nonexistent path rejects with the
- * original error and a non-directory rejects. Repeated calls for the same
- * canonical path return the existing entity without changing its title.
- * A newly created workspace is prepended to the durable registry order.
- * Different canonical paths may share a display title.
- * @param path - Existing directory to own, in any path spelling.
- * @param title - Display title used only when a new record is created.
- * @returns the existing or newly durable workspace.
- */
-async create(path: string, title?: string): Promise<Workspace>
-
-/**
- * Look up a workspace by id.
- * @param id - Workspace id.
- * @returns the workspace, or `undefined` when unknown.
- */
-get(id: WorkspaceId): Workspace | undefined
-
-/**
- * Synchronous workspace projection in durable registry order. Every
- * entity's `sessionIds` getter is already filtered by the startup/live
- * canonical-cwd header index; this method performs no persistence reads.
- * @returns a fresh ordered array of workspace entities.
- */
-list(): Workspace[]
-
-/**
- * Delete one workspace registration while retaining its directory and every
- * session log. The durable order is updated before the table deletion; a
- * failed table write restores the prior order and keeps the entity
- * published. Unknown ids are an idempotent no-op for domain callers.
- * @param id - Workspace registration to remove.
- * @returns `true` when a record was deleted, `false` when it was unknown.
- */
-delete(id: WorkspaceId): Promise<boolean>
-
-/**
- * Archive one session durably. The session must exist (live or in session
- * persistence); its workspace accounting — or lack of one — is irrelevant.
- * An already archived id resolves without writing.
- * @param sessionId - The session to archive.
- * @returns resolution after durability.
- */
-archiveSession(sessionId: SessionId): Promise<void>
-
-/**
- * Resolve by canonical directory path without creating or mutating a
- * workspace. A missing path rejects during `realpath`; an existing unowned
- * directory returns `undefined`.
- * @param path - Existing directory path in any spelling.
- * @returns the workspace owning the canonical path, when one exists.
- */
-async resolveByPath(path: string): Promise<Workspace | undefined>
-```
-
-Types: [SessionId](../subsystems/core.md) · [Workspace](../subsystems/workspace.md) · [WorkspaceId](../subsystems/workspace.md)
-
-Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
-
-## Inherited `ctx` members (cordis core + loader/hmr/timer)
-
-The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier's prominence.
-
-- `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
-- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
-- `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:164`](../../vendor/cordis/src/registry.ts))
-- `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
-- `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
-- `ctx.extend / ctx.isolate / ctx.intercept` — Derive a child context (scoped services / isolation / interception). ([`vendor/cordis/src/context.ts:42`](../../vendor/cordis/src/context.ts))
-- `ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger` — Ambient handles onto the running context graph. ([`vendor/cordis/src/context.ts:16`](../../vendor/cordis/src/context.ts))
-- `ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)` — Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick). ([`vendor/timer/src/index.ts:4`](../../vendor/timer/src/index.ts))
-- `ctx.loader` — The config Loader that booted the app (present under the loader). ([`vendor/loader/src/index.ts:30`](../../vendor/loader/src/index.ts))
-- `ctx.hmr` — The hot-module-reload watcher (present under the hmr plugin). ([`vendor/hmr/src/index.ts:15`](../../vendor/hmr/src/index.ts))
diff --git a/docs/cordis-primer.i18n.yaml b/docs/cordis-primer.i18n.yaml
index 856ea2302b..ec67982eb5 100644
--- a/docs/cordis-primer.i18n.yaml
+++ b/docs/cordis-primer.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 docs/cordis-primer.md
-cordis-primer.md: ee65e6e702ecaeb506ce7334032c38e09c936cda
-cordis-primer.zh.md: 051dd7c956a4db107a4ef7d1414435f9c2b2603d
+cordis-primer.md: 4bcb2c9979994ca70f92031cbdc5dd22df9c1977
+cordis-primer.zh.md: d84beac54463ec193f009f506a4c9b1bda02c243
diff --git a/docs/cordis-primer.md b/docs/cordis-primer.md
index ee65e6e702..4bcb2c9979 100644
--- a/docs/cordis-primer.md
+++ b/docs/cordis-primer.md
@@ -2,7 +2,7 @@
 
 English | [中文](cordis-primer.zh.md)
 
-Cordis is the vendored plugin framework underneath the DeepSeek Harness SDK. This primer teaches the Cordis ideas a harness plugin author needs before reading the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs; the [Cordis tutorial](cordis-tutorial/index.md) walks the same ideas hands-on. The vendored source and sync procedure live in [vendor/README.md](../vendor/README.md).
+Cordis is the vendored plugin framework underneath the DeepSeek Harness SDK. This primer teaches the Cordis ideas a harness plugin author needs before reading the generated service/event reference on the [subsystem pages](subsystems/core.md); the [Cordis tutorial](cordis-tutorial/index.md) walks the same ideas hands-on. The vendored source and sync procedure live in [vendor/README.md](../vendor/README.md).
 
 ## Cordis In Five Ideas
 
diff --git a/docs/cordis-primer.zh.md b/docs/cordis-primer.zh.md
index 051dd7c956..d84beac544 100644
--- a/docs/cordis-primer.zh.md
+++ b/docs/cordis-primer.zh.md
@@ -2,7 +2,7 @@
 
 [English](cordis-primer.md) | 中文
 
-Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读生成的[事件](cordis-catalog/events.md)与[服务](cordis-catalog/services.md)目录之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](../vendor/README.md)。
+Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读[子系统页面](subsystems/core.md)上生成的服务/事件参考之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](../vendor/README.md)。
 
 ## 五个核心概念
 
diff --git a/docs/cordis-tutorial/03-services.i18n.yaml b/docs/cordis-tutorial/03-services.i18n.yaml
index 2849ed8858..bdb7e19387 100644
--- a/docs/cordis-tutorial/03-services.i18n.yaml
+++ b/docs/cordis-tutorial/03-services.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 docs/cordis-tutorial/03-services.md
-03-services.md: 562b49ede0aa4cc1d58c4d6af7c7d5d1ebb2e4b1
-03-services.zh.md: 964f7e3654614d136b8765bb727f85a5a05587a8
+03-services.md: 82b08b7b8a2ec8a6b340dd1fdc7fa3de98cedff9
+03-services.zh.md: ba4152454eb79a21b183b867c0ba2ef32cd43923
diff --git a/docs/cordis-tutorial/03-services.md b/docs/cordis-tutorial/03-services.md
index 562b49ede0..82b08b7b8a 100644
--- a/docs/cordis-tutorial/03-services.md
+++ b/docs/cordis-tutorial/03-services.md
@@ -91,7 +91,7 @@ export function apply(ctx: Context) {
 
 ## Naming
 
-Service names live in one flat namespace per application. Prefix or namespace your own services distinctively (the harness claims plain names like `tools` and `llm`); the generated [services catalog](../cordis-catalog/services.md) lists every name the harness registers.
+Service names live in one flat namespace per application. Prefix or namespace your own services distinctively (the harness claims plain names like `tools` and `llm`); the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) list every name the harness registers.
 
 Next: [Events](04-events.md) — communication without a shared service.
 
diff --git a/docs/cordis-tutorial/03-services.zh.md b/docs/cordis-tutorial/03-services.zh.md
index 964f7e3654..ba4152454e 100644
--- a/docs/cordis-tutorial/03-services.zh.md
+++ b/docs/cordis-tutorial/03-services.zh.md
@@ -91,7 +91,7 @@ export function apply(ctx: Context) {
 
 ## 命名
 
-每个应用中的服务名称共用一个扁平命名空间。请为自有服务添加有辨识度的前缀或命名空间（harness 已占用 `tools` 和 `llm` 等普通名称）；生成的[服务目录](../cordis-catalog/services.md)列出 harness 注册的每个名称。
+每个应用中的服务名称共用一个扁平命名空间。请为自有服务添加有辨识度的前缀或命名空间（harness 已占用 `tools` 和 `llm` 等普通名称）；[子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块列出 harness 注册的每个名称。
 
 下一章：[事件](04-events.md)：无需共享服务即可通信。
 
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index e7dc182114..a78b8f690c 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.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 docs/cordis-tutorial/04-events.md
-04-events.md: 28ccb85d657afaabb5c6b4b1e9b10d6cf8710918
-04-events.zh.md: f78c971dcd9674d2a256c41000b627aecb2a572a
+04-events.md: b0563c71fada3efc760ff7183bc7a82e7e86934e
+04-events.zh.md: 0999cbf116eca452e54418132fbaefe3622b2c26
diff --git a/docs/cordis-tutorial/04-events.md b/docs/cordis-tutorial/04-events.md
index 28ccb85d65..b0563c71fa 100644
--- a/docs/cordis-tutorial/04-events.md
+++ b/docs/cordis-tutorial/04-events.md
@@ -89,7 +89,7 @@ Because `ctx.on()` is an effect, the listener disappears with the plugin — no
 | bail | `ctx.bail(name, ...args)` | Synchronous version of serial. |
 | waterfall | `ctx.waterfall(name, ...args, next)` | Around-middleware; see below. |
 
-Every harness event documents its mode in the generated [events catalog](../cordis-catalog/events.md).
+Every harness event documents its mode in the generated reference on its owning [subsystem page](../subsystems/core.md).
 
 ## Waterfall: transform or short-circuit
 
@@ -137,7 +137,7 @@ Walk through the second line: listener 1 runs first, calls `next()`, which invok
 
 The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. This is important enough that it is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
 
-The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../cordis-catalog/events.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../cordis-catalog/events.md#approvalrequest--waterfall) lets a policy answer instead of the user.
+The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../subsystems/core.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) lets a policy answer instead of the user.
 
 Next: [Configuration](05-config.md) — plugin options from `cordis.yml`.
 
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index f78c971dcd..0999cbf116 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -89,7 +89,7 @@ export function apply(ctx: Context) {
 | bail | `ctx.bail(name, ...args)` | serial 的同步版本。 |
 | waterfall（瀑布式事件） | `ctx.waterfall(name, ...args, next)` | 环绕中间件，见下文。 |
 
-每个 harness 事件都会在生成的[事件目录](../cordis-catalog/events.md)中记录其模式。
+每个 harness 事件都会在其所属[子系统页面](../subsystems/core.md)的生成参考中记录其模式。
 
 ## waterfall：转换或短路
 
@@ -137,7 +137,7 @@ HELLO
 
 由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这一点极其重要，已成为本仓库的常设规则（[waterfall 语义](../cordis-primer.md#cordis-waterfall-semantics)）。
 
-harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../cordis-catalog/events.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../cordis-catalog/events.md#approvalrequest--waterfall) 允许策略代替用户作答。
+harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) 允许策略代替用户作答。
 
 下一章：[配置](05-config.md)：来自 `cordis.yml` 的插件选项。
 
diff --git a/docs/cordis-tutorial/07-into-the-harness.i18n.yaml b/docs/cordis-tutorial/07-into-the-harness.i18n.yaml
index f3dde47f3a..fd29baab75 100644
--- a/docs/cordis-tutorial/07-into-the-harness.i18n.yaml
+++ b/docs/cordis-tutorial/07-into-the-harness.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 docs/cordis-tutorial/07-into-the-harness.md
-07-into-the-harness.md: e02f8f8d55b3fbe9087d46f8f50baeecb592c1c6
-07-into-the-harness.zh.md: 5f770267e8f3db04cd9cb0e92b6a6278cf05d5e4
+07-into-the-harness.md: 38483b5c4993a44562970782dca5f676e4cb84f6
+07-into-the-harness.zh.md: 59ce716bdace894682bc1c8e6e00cf174008c26c
diff --git a/docs/cordis-tutorial/07-into-the-harness.md b/docs/cordis-tutorial/07-into-the-harness.md
index e02f8f8d55..38483b5c49 100644
--- a/docs/cordis-tutorial/07-into-the-harness.md
+++ b/docs/cordis-tutorial/07-into-the-harness.md
@@ -101,7 +101,7 @@ Where to go next:
 
 - [Build a tool](../user/develop/basic/tool.md) — more of `defineTool`, including presentation and richer schemas.
 - [Three-layer capability design](../user/develop/practice/index.md) — how the harness structures replaceable capabilities.
-- The generated [services](../cordis-catalog/services.md) and [events](../cordis-catalog/events.md) catalogs — everything you can inject and listen to.
+- The generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) — everything you can inject and listen to, each on its owning page.
 - [Architecture](../architecture.md) — the system map these plugins live in.
 
 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/07-into-the-harness.zh.md b/docs/cordis-tutorial/07-into-the-harness.zh.md
index 5f770267e8..59ce716bda 100644
--- a/docs/cordis-tutorial/07-into-the-harness.zh.md
+++ b/docs/cordis-tutorial/07-into-the-harness.zh.md
@@ -101,7 +101,7 @@ logger 会先触发：`tools/result` 在结果物化过程中发出，发生在
 
 - [构建工具](../user/develop/basic/tool.md)：深入了解 `defineTool`，包括呈现和更丰富的 schema。
 - [三层能力设计](../user/develop/practice/index.md)：harness 如何组织可替换能力。
-- 生成的[服务](../cordis-catalog/services.md)与[事件](../cordis-catalog/events.md)目录：可以注入和监听的所有内容。
+- [子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块：可以注入和监听的所有内容，各在其所属页面上。
 - [架构](../architecture.md)：这些插件所处的系统地图。
 
 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/index.i18n.yaml b/docs/cordis-tutorial/index.i18n.yaml
index 496a3fffa5..fa810d635f 100644
--- a/docs/cordis-tutorial/index.i18n.yaml
+++ b/docs/cordis-tutorial/index.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 docs/cordis-tutorial/index.md
-index.md: a20976706f520416236ca759ee33649d1601eaa9
-index.zh.md: f6989521d4b7dffac6114867cc12371af4e4316f
+index.md: 7a0bb6f8c736bf31d655a7763cfb7039c343d1a2
+index.zh.md: e6f6dc0cccef3f44273655b98b695bdc4632e95a
diff --git a/docs/cordis-tutorial/index.md b/docs/cordis-tutorial/index.md
index a20976706f..7a0bb6f8c7 100644
--- a/docs/cordis-tutorial/index.md
+++ b/docs/cordis-tutorial/index.md
@@ -6,7 +6,7 @@ Cordis is the plugin framework underneath the DeepSeek Harness SDK: a small runt
 
 The audience is agent developers. You do not need deep TypeScript experience; the [TypeScript notes](#typescript-notes) below explain the syntax that may be unfamiliar, and every chapter shows the exact commands and expected output.
 
-If you want the condensed concept reference instead of a walkthrough, read the [Cordis primer](../cordis-primer.md). The exhaustive API reference lives in the generated [events](../cordis-catalog/events.md) and [services](../cordis-catalog/services.md) catalogs and the [Cordis core API](../cordis-catalog/core/context.md) pages.
+If you want the condensed concept reference instead of a walkthrough, read the [Cordis primer](../cordis-primer.md). The exhaustive API reference lives in the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) and the [Cordis core API](../cordis-api/context.md) pages.
 
 ## Setup
 
diff --git a/docs/cordis-tutorial/index.zh.md b/docs/cordis-tutorial/index.zh.md
index f6989521d4..e6f6dc0ccc 100644
--- a/docs/cordis-tutorial/index.zh.md
+++ b/docs/cordis-tutorial/index.zh.md
@@ -6,7 +6,7 @@ Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行
 
 本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 [TypeScript 说明](#typescript-notes)会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。
 
-如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见生成的[事件](../cordis-catalog/events.md)与[服务](../cordis-catalog/services.md)目录，以及 [Cordis 核心 API](../cordis-catalog/core/context.md) 页面。
+如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见[子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块，以及 [Cordis 核心 API](../cordis-api/context.md)页面。
 
 ## 准备工作
 
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index 0c955c9480..5b831520fb 100644
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -3,7 +3,7 @@
 
 # Documentation Graph Index
 
-These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).
+These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).
 
 The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).
 
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index b9a330f21d..432c95e684 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -14,9 +14,9 @@
 
 依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-spine-demo`，它的职责是组装整套实体主干。
 
-> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
+> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the generated regions of [subsystems/](../subsystems/core.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 04f992e536..04c3a492fe 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -3,7 +3,7 @@
 
 # Session Persistence Event Catalog
 
-Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
diff --git a/docs/subsystems/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
index a3447601a4..93c56707bf 100644
--- a/docs/subsystems/approval.i18n.yaml
+++ b/docs/subsystems/approval.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 docs/subsystems/approval.md
-approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069
-approval.zh.md: c19285572b667512427b71d4af214acbc2baf334
+approval.md: 2045f2073b72fa265728cbf77b673053a2eaf371
+approval.zh.md: c021db14c4925acaeef5d984d9dfa88ad55bd8dd
diff --git a/docs/subsystems/approval.md b/docs/subsystems/approval.md
index 8f17f98101..2045f2073b 100644
--- a/docs/subsystems/approval.md
+++ b/docs/subsystems/approval.md
@@ -87,3 +87,85 @@ interface ApprovalRequest {
 `ctx.approval.request(req)` requires the requesting session to be inside an open turn. It appends `approval/asked`, obtains one outcome, appends the matching `approval/decided`, and resolves with that outcome. The `never` policy is enforced inside the service before waterfall dispatch, so even an answerer registered later with `prepend` cannot bypass it. Answerers return an outcome when they own the request or call `next()` to delegate; the first answer occupies the single decision slot.
 
 The audit events are log-only and do not enter the model transcript. Model-visible behavior is the caller's derived tool result plus the current runtime-context snapshot. Service disposal removes its context contribution; answerer listeners are independently effect-bound to their owning plugins.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxapproval--approvalservice"></a>
+
+### `ctx.approval` — `ApprovalService`
+
+Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
+
+```ts cordis-catalog
+/**
+ * Switch one live agent's policy and queue the transition for its next model
+ * step. Session initialization uses {@link setApprovalPolicy} directly
+ * because there is no previously visible policy to change.
+ * @param agent - the live agent whose policy is changing.
+ * @param policy - the new effective policy.
+ */
+setPolicy(agent: Agent, policy: ApprovalPolicy): void
+
+/**
+ * Ask the composed answerers to decide one readonly same-process request.
+ * The service borrows the request, agent, session, and live signal directly.
+ * The request requires an open turn because the audit pair must be enclosed
+ * by the durable log's commit/replay boundary; an idle ask rejects before
+ * appending anything. The answerer phase always produces an outcome: an
+ * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+ * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+ * normalized to `'unavailable'`. A failure that prevents either audit append
+ * from committing still rejects because returning an unlogged decision would
+ * violate the pair. Session contains post-commit observer failures, so an
+ * authoritative append cannot reject the request or suppress its matching
+ * audit event.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @returns the closed outcome; `'allowed-once'` is the only grant.
+ * @throws when no turn is open or either audit event fails before the session
+ *   append commit point.
+ */
+async request(req: ApprovalRequest): Promise<ApprovalOutcome>
+
+/**
+ * Read the session override without applying the configured default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged policy, or `undefined` without one.
+ */
+overrideOf(session: Session): ApprovalPolicy | undefined
+```
+
+Types: [Agent](core.md) · [Session](session.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+
+<a id="approval-events"></a>
+
+### `approval/*` events
+
+<a id="approvalrequest--waterfall"></a>
+
+#### `approval/request` — waterfall
+
+Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
+'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/approval.zh.md b/docs/subsystems/approval.zh.md
index c19285572b..c021db14c4 100644
--- a/docs/subsystems/approval.zh.md
+++ b/docs/subsystems/approval.zh.md
@@ -87,3 +87,85 @@ interface ApprovalRequest {
 `ctx.approval.request(req)` 要求发起请求的会话处于一个尚未结束的轮次内。它追加 `approval/asked`，获取一个结果，追加对应的 `approval/decided`，然后以该结果完成。`never` 策略在服务内部、waterfall 分发之前强制执行，因此即使后来以 `prepend` 注册的应答者也无法绕过它。应答者在拥有该请求时返回结果，否则调用 `next()` 委托；第一个应答占据唯一的决策槽位。
 
 审计事件仅写入日志，不进入模型 transcript（文本记录）。模型可见的行为是调用方派生的工具结果与当前运行时上下文快照。服务 dispose（资源释放）时会移除其上下文贡献；应答者监听器独立地通过 effect 绑定到其所属插件。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxapproval--approvalservice"></a>
+
+### `ctx.approval` — `ApprovalService`
+
+Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
+
+```ts cordis-catalog
+/**
+ * Switch one live agent's policy and queue the transition for its next model
+ * step. Session initialization uses {@link setApprovalPolicy} directly
+ * because there is no previously visible policy to change.
+ * @param agent - the live agent whose policy is changing.
+ * @param policy - the new effective policy.
+ */
+setPolicy(agent: Agent, policy: ApprovalPolicy): void
+
+/**
+ * Ask the composed answerers to decide one readonly same-process request.
+ * The service borrows the request, agent, session, and live signal directly.
+ * The request requires an open turn because the audit pair must be enclosed
+ * by the durable log's commit/replay boundary; an idle ask rejects before
+ * appending anything. The answerer phase always produces an outcome: an
+ * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+ * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+ * normalized to `'unavailable'`. A failure that prevents either audit append
+ * from committing still rejects because returning an unlogged decision would
+ * violate the pair. Session contains post-commit observer failures, so an
+ * authoritative append cannot reject the request or suppress its matching
+ * audit event.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @returns the closed outcome; `'allowed-once'` is the only grant.
+ * @throws when no turn is open or either audit event fails before the session
+ *   append commit point.
+ */
+async request(req: ApprovalRequest): Promise<ApprovalOutcome>
+
+/**
+ * Read the session override without applying the configured default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged policy, or `undefined` without one.
+ */
+overrideOf(session: Session): ApprovalPolicy | undefined
+```
+
+Types: [Agent](core.md) · [Session](session.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+
+<a id="approval-events"></a>
+
+### `approval/*` events
+
+<a id="approvalrequest--waterfall"></a>
+
+#### `approval/request` — waterfall
+
+Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
+'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 30e15dbacc..f6ed20cace 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/bash.md
-bash.md: f83a133c8e049bc111cfabd2b59def18a1b2d607
-bash.zh.md: 27ca9f6e5a8e05cd4ffa86e72d433b6f22005f09
+#   pnpm run verify-translation-pairing --write docs/subsystems/bash.md
+bash.md: dd7649ce46bea5642270fa553eb3d82f2dc33e9b
+bash.zh.md: bba9ece2955cee66e941aa878299cff6c06a97a0
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index f83a133c8e..dd7649ce46 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -219,3 +219,85 @@ interface BashProcessRead {
 ## The service
 
 `BashExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns command defaulting, timeout/abort classification, the terminal environment, and the background read merge; process groups, bounded collectors, spill files, credential scrubbing, and disposal quiescence are the [subprocess service](subprocess.md)'s. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic task runtime](tasks.md). `dsh-bash` owns the shell tools' shared exit-status contract: the exported `parseExitStatus`/`ParsedExitStatus` inverts the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append, and both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
+
+### `ctx.bash` — `BashExecutor` (abstract seam)
+
+Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
+- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
+- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
+
+```ts cordis-catalog
+/**
+ * Apply implementation-owned defaults and caps to a request before execution.
+ * @param request - the caller's request; omitted fields get this
+ *   implementation's defaults, capped fields are clamped.
+ * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+ */
+abstract resolve(request: BashExecRequest): BashExecSpec
+
+/**
+ * Run a command in the foreground; resolves when it finishes.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the outcome; nonzero exits, timeout kills, and abort kills
+ *   resolve with a descriptive result rather than reject.
+ */
+abstract run(spec: BashExecSpec): Promise<BashRunResult>
+
+/**
+ * Start a background process and return its handle immediately.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the live process handle (reads, kill, quiescence promise).
+ */
+abstract start(spec: BashExecSpec): BashProcess
+```
+
+Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
+
+<a id="ctxbashenv--bashenvregistry"></a>
+
+### `ctx.bashEnv` — `BashEnvRegistry`
+
+Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
+
+```ts cordis-catalog
+/**
+ * Register one environment contributor. Names and keys are unique; built-in
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
+ * @param contributor - declared key ownership and per-execution resolver.
+ * @returns the disposer that unregisters the contribution.
+ */
+register(contributor: BashEnvContributor): () => void
+
+/**
+ * Build the trusted `DSH_*` snapshot for one shell tool execution.
+ * @param execution - the current tool execution.
+ * @returns an immutable environment overlay containing built-ins and current contributions.
+ */
+collect(execution: ToolExecution): DshEnvironment
+
+/**
+ * Enumerate plugin-contributed variables without executing their resolvers.
+ * @returns declarations sorted by environment variable name.
+ */
+list(): BashEnvVariableInfo[]
+```
+
+Types: [DshEnvironment](subprocess.md) · [ToolExecution](tools.md)
+
+Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index 27ca9f6e5a..bba9ece295 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -219,3 +219,85 @@ interface BashProcessRead {
 ## 服务
 
 `BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[进程管理器](subprocess.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。`dsh-bash` 拥有 shell 工具共享的退出状态契约：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
+
+### `ctx.bash` — `BashExecutor` (abstract seam)
+
+Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
+- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
+- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
+
+```ts cordis-catalog
+/**
+ * Apply implementation-owned defaults and caps to a request before execution.
+ * @param request - the caller's request; omitted fields get this
+ *   implementation's defaults, capped fields are clamped.
+ * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+ */
+abstract resolve(request: BashExecRequest): BashExecSpec
+
+/**
+ * Run a command in the foreground; resolves when it finishes.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the outcome; nonzero exits, timeout kills, and abort kills
+ *   resolve with a descriptive result rather than reject.
+ */
+abstract run(spec: BashExecSpec): Promise<BashRunResult>
+
+/**
+ * Start a background process and return its handle immediately.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the live process handle (reads, kill, quiescence promise).
+ */
+abstract start(spec: BashExecSpec): BashProcess
+```
+
+Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
+
+<a id="ctxbashenv--bashenvregistry"></a>
+
+### `ctx.bashEnv` — `BashEnvRegistry`
+
+Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
+
+```ts cordis-catalog
+/**
+ * Register one environment contributor. Names and keys are unique; built-in
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
+ * @param contributor - declared key ownership and per-execution resolver.
+ * @returns the disposer that unregisters the contribution.
+ */
+register(contributor: BashEnvContributor): () => void
+
+/**
+ * Build the trusted `DSH_*` snapshot for one shell tool execution.
+ * @param execution - the current tool execution.
+ * @returns an immutable environment overlay containing built-ins and current contributions.
+ */
+collect(execution: ToolExecution): DshEnvironment
+
+/**
+ * Enumerate plugin-contributed variables without executing their resolvers.
+ * @returns declarations sorted by environment variable name.
+ */
+list(): BashEnvVariableInfo[]
+```
+
+Types: [DshEnvironment](subprocess.md) · [ToolExecution](tools.md)
+
+Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index f0df40a866..ae61603169 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: 5dc89a87db7e79e4a297002fa059fdeffcceda20
-client-modules.zh.md: b3aa9c2aecf8e051a41b7b05f05d364b9ff8d2a6
+client-modules.md: 19bcc6304e9d917c3950fd9857e7b2c2b3c16e73
+client-modules.zh.md: b0ad293cad2f67de1982ef271308b2a7f06ebaf4
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 5dc89a87db..19bcc6304e 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -58,6 +58,61 @@ Package metadata — including the negative "not a client package" verdict — i
 
 ## The service
 
-`ClientModuleHostService` (`ctx.clientModuleHost`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice). `graph()` returns the current composed graph (a stable object between changes) and `clientPath(id)` the bundle's absolute path. `rebuilt(id)` is the only entry point through which bundle content reaches the graph: it re-hashes the file, and only a real rev change recomposes the graph and notifies. `onRebuilt` fires per changed bundle with the new rev; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt rev change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
+`ClientModuleHostService` (`ctx.clientModuleHost`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](#ctxclientmodulehost--clientmodulehostservice). `graph()` returns the current composed graph (a stable object between changes) and `clientPath(id)` the bundle's absolute path. `rebuilt(id)` is the only entry point through which bundle content reaches the graph: it re-hashes the file, and only a real rev change recomposes the graph and notifies. `onRebuilt` fires per changed bundle with the new rev; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt rev change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
 
 In development, [dsh-client-hmr](../../packages/client/hmr/README.md) is the registry's watch driver: its node half stat-polls every graph row's bundle from a synchronously captured baseline, calls `rebuilt(id)` on change, resyncs its watch set through `onGraphChanged`, and broadcasts rev changes to the browser half over SSE. Production graphs omit the HMR row entirely; the module host itself never watches files.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxclientmodulehost--clientmodulehostservice"></a>
+
+### `ctx.clientModuleHost` — `ClientModuleHostService`
+
+The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
+
+```ts cordis-catalog
+/**
+ * Current composed entry graph (stable object between changes).
+ * @returns the graph served as `window.__DSH_BOOT__`.
+ */
+graph(): WebBootGraph
+
+/**
+ * Absolute path of an entry's client bundle.
+ * @param id - entry id (package name).
+ * @returns the path, or undefined for an unknown id.
+ */
+clientPath(id: string): string | undefined
+
+/**
+ * Re-hash one bundle (the HMR watch's registration hook — the only entry
+ * point through which bundle content changes reach the graph).
+ * @param id - entry id (package name).
+ * @returns the new rev, or undefined for an unknown id.
+ */
+rebuilt(id: string): string | undefined
+
+/**
+ * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+ * @param listener - receives the entry id and its new bundle rev.
+ * @returns the unsubscriber.
+ */
+onRebuilt(listener: (id: string, rev: string) => void): () => void
+
+/**
+ * Fires after any flush that recomposed the graph (row added/removed, or a
+ * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+ * @param listener - notified with no payload.
+ * @returns the unsubscriber.
+ */
+onGraphChanged(listener: () => void): () => void
+```
+
+Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index b3aa9c2aec..b0ad293cad 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -58,6 +58,61 @@ interface WebBootGraph {
 
 ## 服务
 
-`ClientModuleHostService`（`ctx.clientModuleHost`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回该 bundle 的绝对路径。`rebuilt(id)` 是 bundle 内容到达图的唯一入口：它对文件重新哈希，只有 rev 真正变化才会重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 rev；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 rev 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
+`ClientModuleHostService`（`ctx.clientModuleHost`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](#ctxclientmodulehost--clientmodulehostservice)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回该 bundle 的绝对路径。`rebuilt(id)` 是 bundle 内容到达图的唯一入口：它对文件重新哈希，只有 rev 真正变化才会重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 rev；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 rev 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
 
 开发环境下，[dsh-client-hmr](../../packages/client/hmr/README.md) 是注册表的监视驱动：它的 Node 半从同步取得的基线出发，对图中每一行的 bundle 做 stat 轮询，变化时调用 `rebuilt(id)`，经 `onGraphChanged` 重新同步监视集合，并通过 SSE（Server-Sent Events）把 rev 变化广播给浏览器半。生产环境的图完全不含 HMR（热模块替换）行；模块宿主自身从不监视文件。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxclientmodulehost--clientmodulehostservice"></a>
+
+### `ctx.clientModuleHost` — `ClientModuleHostService`
+
+The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
+
+```ts cordis-catalog
+/**
+ * Current composed entry graph (stable object between changes).
+ * @returns the graph served as `window.__DSH_BOOT__`.
+ */
+graph(): WebBootGraph
+
+/**
+ * Absolute path of an entry's client bundle.
+ * @param id - entry id (package name).
+ * @returns the path, or undefined for an unknown id.
+ */
+clientPath(id: string): string | undefined
+
+/**
+ * Re-hash one bundle (the HMR watch's registration hook — the only entry
+ * point through which bundle content changes reach the graph).
+ * @param id - entry id (package name).
+ * @returns the new rev, or undefined for an unknown id.
+ */
+rebuilt(id: string): string | undefined
+
+/**
+ * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+ * @param listener - receives the entry id and its new bundle rev.
+ * @returns the unsubscriber.
+ */
+onRebuilt(listener: (id: string, rev: string) => void): () => void
+
+/**
+ * Fires after any flush that recomposed the graph (row added/removed, or a
+ * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+ * @param listener - notified with no payload.
+ * @returns the unsubscriber.
+ */
+onGraphChanged(listener: () => void): () => void
+```
+
+Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 02bbc9587a..05e7e67ed1 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/code-runtime.md
-code-runtime.md: fbce7d812b7609716fb43ae01610253008e0a92c
-code-runtime.zh.md: 700146cfaa9cfab37ec4d85e550020acf1d9f294
+#   pnpm run verify-translation-pairing --write docs/subsystems/code-runtime.md
+code-runtime.md: 12779f1aafc8930410ae0d695e3f617caafcf607
+code-runtime.zh.md: de563dd3430348f5cf3675d4bf124adeba170559
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index fbce7d812b..12779f1aaf 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -159,3 +159,33 @@ interface CodeRunFailure {
 ## The service
 
 `CodeRuntime` (`ctx.codeRuntime`, abstract — defined in [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)) is `run(request)` plus two readonly descriptors: `language` (what the program must be written in — `'typescript'` and `'python'` are the well-known values, those `dsh-tools` presents, and only `'typescript'` has a published backend; a consumer generating language-specific presentation switches on it and fails loud on one it cannot present) and `isolation` (the execution substrate — `'worker-thread'`, `'process'`, `'container'`; a diagnostic label, **not a security claim**). Implementations must keep runs isolated from each other (no cross-run state) and dispose to quiescence: in-flight runs are terminated and awaited before teardown completes.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+
+```ts cordis-catalog
+/**
+ * Execute one program against the request's bindings and capture what it
+ * emitted. See the class doc for the resolution contract (error is a result
+ * field; rejection means seam misuse only).
+ * @param request - the program, its bindings, and the abort signal; the
+ *   request carries everything the runtime acts on, with no hidden defaults.
+ * @returns the run's outcome: completion value (when transferable), the
+ *   ordered log capture, and the failure (if any).
+ */
+abstract run(request: CodeRunRequest): Promise<CodeRunResult>
+```
+
+Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 700146cfaa..de563dd343 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -159,3 +159,33 @@ interface CodeRunFailure {
 ## 服务
 
 `CodeRuntime`（`ctx.codeRuntime`，抽象服务，定义于 [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)）由 `run(request)` 加两个只读描述符组成：`language`（程序必须使用的语言，已知值为 `'typescript'` 与 `'python'`，即 `dsh-tools` 能呈现的那些，其中只有 `'typescript'` 有已发布的后端；生成语言相关展示的消费方据此切换，遇到无法展示的语言时应显式报错）和 `isolation`（执行基底，`'worker-thread'`、`'process'`、`'container'`；仅为诊断标签，**不构成安全承诺**）。实现必须保证各次运行彼此隔离（无跨运行状态），并在 dispose（资源释放）时等待系统完全停稳：teardown 要等到所有进行中的运行均已终止并结算后才完成。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+
+```ts cordis-catalog
+/**
+ * Execute one program against the request's bindings and capture what it
+ * emitted. See the class doc for the resolution contract (error is a result
+ * field; rejection means seam misuse only).
+ * @param request - the program, its bindings, and the abort signal; the
+ *   request carries everything the runtime acts on, with no hidden defaults.
+ * @returns the run's outcome: completion value (when transferable), the
+ *   ordered log capture, and the failure (if any).
+ */
+abstract run(request: CodeRunRequest): Promise<CodeRunResult>
+```
+
+Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index a741971a9a..3bd5420573 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c
-commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb
+commands.md: c1ab6d9782f515321104d0cf4d9e037c6a68a18d
+commands.zh.md: 3b3d8def042b107c5098e76c511424f023975e77
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index 83ce9c2498..c1ab6d9782 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -97,3 +97,89 @@ interface ParsedCommand {
   readonly rawInput: string
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcommands--commandservice"></a>
+
+### `ctx.commands` — `CommandService`
+
+Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
+
+```ts cordis-catalog
+/**
+ * Register a global or calling-agent-scoped command.
+ * @param definition - discovery metadata and direct UI handler.
+ * @returns the exact effect disposer that unregisters this definition.
+ */
+register(definition: CommandDefinition): () => void
+
+/**
+ * List the effective immutable command descriptors for one agent.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @returns name-sorted descriptors after scoped shadowing.
+ */
+list(agent: Agent): readonly CommandDescriptor[]
+
+/**
+ * Resolve one effective command definition.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @param name - command name without a slash.
+ * @returns the scoped shadow or global definition.
+ */
+find(agent: Agent, name: string): CommandDefinition | undefined
+
+/**
+ * Parse and execute a known command without sending it to the model.
+ *
+ * A resolved command's lifecycle is logged: `command/run` is appended
+ * before the handler is invoked and `command/done` after settlement (a
+ * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+ * log-only appends — no turn wraps them, and persistence drains them at
+ * ordinary checkpoints. Admission misses (syntax or unknown name) log
+ * nothing — they never entered a handler. A `command/run` append failure
+ * fails the execution loud; a `command/done` append failure on the
+ * handler-failure path is contained so the handler's own error stays the
+ * reported failure.
+ *
+ * @param agent - exact receiving agent.
+ * @param line - complete slash-command line.
+ * @param signal - cancellation signal owned by the UI request.
+ * @returns the settled execution (result + lifecycle pairing id), or
+ *   `undefined` when syntax or name does not resolve.
+ */
+async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+
+<a id="commands-events"></a>
+
+### `commands/*` events
+
+<a id="commandschange--emit"></a>
+
+#### `commands/change` — emit
+
+A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A command was registered or unregistered. This is an unfiltered registry
+ * notification because a global or scoped change may affect any UI view.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'commands/change'(): void
+```
+
+Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index c486f48017..3b3d8def04 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -97,3 +97,89 @@ interface ParsedCommand {
   readonly rawInput: string
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcommands--commandservice"></a>
+
+### `ctx.commands` — `CommandService`
+
+Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
+
+```ts cordis-catalog
+/**
+ * Register a global or calling-agent-scoped command.
+ * @param definition - discovery metadata and direct UI handler.
+ * @returns the exact effect disposer that unregisters this definition.
+ */
+register(definition: CommandDefinition): () => void
+
+/**
+ * List the effective immutable command descriptors for one agent.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @returns name-sorted descriptors after scoped shadowing.
+ */
+list(agent: Agent): readonly CommandDescriptor[]
+
+/**
+ * Resolve one effective command definition.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @param name - command name without a slash.
+ * @returns the scoped shadow or global definition.
+ */
+find(agent: Agent, name: string): CommandDefinition | undefined
+
+/**
+ * Parse and execute a known command without sending it to the model.
+ *
+ * A resolved command's lifecycle is logged: `command/run` is appended
+ * before the handler is invoked and `command/done` after settlement (a
+ * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+ * log-only appends — no turn wraps them, and persistence drains them at
+ * ordinary checkpoints. Admission misses (syntax or unknown name) log
+ * nothing — they never entered a handler. A `command/run` append failure
+ * fails the execution loud; a `command/done` append failure on the
+ * handler-failure path is contained so the handler's own error stays the
+ * reported failure.
+ *
+ * @param agent - exact receiving agent.
+ * @param line - complete slash-command line.
+ * @param signal - cancellation signal owned by the UI request.
+ * @returns the settled execution (result + lifecycle pairing id), or
+ *   `undefined` when syntax or name does not resolve.
+ */
+async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+
+<a id="commands-events"></a>
+
+### `commands/*` events
+
+<a id="commandschange--emit"></a>
+
+#### `commands/change` — emit
+
+A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A command was registered or unregistered. This is an unfiltered registry
+ * notification because a global or scoped change may affect any UI view.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'commands/change'(): void
+```
+
+Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 7dc00cebfc..5481b2feb1 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: f1df5b83bd43136af60988dabd9dc68fe32467a2
-compaction.zh.md: 52540250d466f81f51cf7c681bb6f1436e29a12d
+compaction.md: 126c6c7c7df125cf991ea074e0165481c09455dc
+compaction.zh.md: 9fb01a41a92367b9bb3f4586f35b5d0baf613bbc
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index f1df5b83bd..126c6c7c7d 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -112,3 +112,119 @@ interface PruneResult {
   readonly charsRemoved: number
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcompact--compactservice-abstract-seam"></a>
+
+### `ctx.compact` — `CompactService` (abstract seam)
+
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+
+```ts cordis-catalog
+/**
+ * Consider automatic compaction for one explicit trigger. Pressure policy
+ * uses the latest durable routed request, while context-overflow policy may
+ * force a useful balanced reduction even below the normal threshold. Return
+ * `null` when no safe range can be compacted. A single oversized retained
+ * unit or request envelope cannot be repaired through surface compaction.
+ *
+ * @param agent - agent context owning the session surface and routing options.
+ * @param trigger - normal pressure or provider-confirmed context overflow.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
+abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Explicitly compact useful history even below automatic pressure thresholds.
+ * Implementations synchronously start an idle task before any asynchronous
+ * work, select a useful range without writing on a no-op, then
+ * append a standalone `compact/start` before summarization. That durable
+ * marker is the compaction lock until one `compact/end` attempt. Later waking
+ * prompts remain accepted in FIFO order and start only after the optional
+ * durability checkpoint and idle-task settlement. Context injected while the
+ * summary runs may sit between the marker pair; only the selected span must
+ * remain stable.
+ *
+ * @param agent - idle agent whose durable history should be compacted.
+ * @param signal - cancellation scoped to this compaction request.
+ * @returns the compaction result, or `null` when no safe useful range exists.
+ * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
+ * changed-span, summarization/shrink, commit-stage, or persistence failures;
+ * an aborted request preserves its exact abort reason. Failed attempts remain
+ * visible in the log.
+ */
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
+abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+```
+
+Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+
+<a id="ctxtoolresultprune--toolresultpruneservice"></a>
+
+### `ctx.toolResultPrune` — `ToolResultPruneService`
+
+Deterministic head/middle/tail pruning for current tool-result surface nodes.
+
+```ts cordis-catalog
+/**
+ * Measure text content in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content to measure.
+ * @returns total Unicode code points across text blocks.
+ */
+measureContent(blocks: readonly ContentBlock[]): number
+
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
+ * boundary cannot split a surrogate pair. Grapheme clusters may still split.
+ * @param blocks - original tool-result content.
+ * @returns pruned content, or `null` when the text is within budget.
+ */
+pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
+
+/**
+ * Prune every over-budget tool result from one stable current-surface snapshot.
+ * Each replacement preserves the complete event data except for `content`,
+ * points at the shadowed node for durable provenance and replay, and is
+ * immediately preceded by a `compact/prune` shadow-price event pricing the
+ * shadowed node through the injected token meter, so pure consumers can
+ * subtract it without per-node state.
+ * @param session - session whose current surface is rewritten.
+ * @returns landed replacements and aggregate Unicode-code-point savings.
+ * @throws when the session rejects a replacement; replacements committed
+ * earlier in the pass remain durable.
+ */
+pruneSession(session: Session): PruneResult
+```
+
+Types: [ContentBlock](core.md) · [Session](session.md)
+
+Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 52540250d4..9fb01a41a9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -112,3 +112,119 @@ interface PruneResult {
   readonly charsRemoved: number
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcompact--compactservice-abstract-seam"></a>
+
+### `ctx.compact` — `CompactService` (abstract seam)
+
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+
+```ts cordis-catalog
+/**
+ * Consider automatic compaction for one explicit trigger. Pressure policy
+ * uses the latest durable routed request, while context-overflow policy may
+ * force a useful balanced reduction even below the normal threshold. Return
+ * `null` when no safe range can be compacted. A single oversized retained
+ * unit or request envelope cannot be repaired through surface compaction.
+ *
+ * @param agent - agent context owning the session surface and routing options.
+ * @param trigger - normal pressure or provider-confirmed context overflow.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
+abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Explicitly compact useful history even below automatic pressure thresholds.
+ * Implementations synchronously start an idle task before any asynchronous
+ * work, select a useful range without writing on a no-op, then
+ * append a standalone `compact/start` before summarization. That durable
+ * marker is the compaction lock until one `compact/end` attempt. Later waking
+ * prompts remain accepted in FIFO order and start only after the optional
+ * durability checkpoint and idle-task settlement. Context injected while the
+ * summary runs may sit between the marker pair; only the selected span must
+ * remain stable.
+ *
+ * @param agent - idle agent whose durable history should be compacted.
+ * @param signal - cancellation scoped to this compaction request.
+ * @returns the compaction result, or `null` when no safe useful range exists.
+ * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
+ * changed-span, summarization/shrink, commit-stage, or persistence failures;
+ * an aborted request preserves its exact abort reason. Failed attempts remain
+ * visible in the log.
+ */
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
+abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+```
+
+Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+
+<a id="ctxtoolresultprune--toolresultpruneservice"></a>
+
+### `ctx.toolResultPrune` — `ToolResultPruneService`
+
+Deterministic head/middle/tail pruning for current tool-result surface nodes.
+
+```ts cordis-catalog
+/**
+ * Measure text content in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content to measure.
+ * @returns total Unicode code points across text blocks.
+ */
+measureContent(blocks: readonly ContentBlock[]): number
+
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
+ * boundary cannot split a surrogate pair. Grapheme clusters may still split.
+ * @param blocks - original tool-result content.
+ * @returns pruned content, or `null` when the text is within budget.
+ */
+pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
+
+/**
+ * Prune every over-budget tool result from one stable current-surface snapshot.
+ * Each replacement preserves the complete event data except for `content`,
+ * points at the shadowed node for durable provenance and replay, and is
+ * immediately preceded by a `compact/prune` shadow-price event pricing the
+ * shadowed node through the injected token meter, so pure consumers can
+ * subtract it without per-node state.
+ * @param session - session whose current surface is rewritten.
+ * @returns landed replacements and aggregate Unicode-code-point savings.
+ * @throws when the session rejects a replacement; replacements committed
+ * earlier in the pass remain durable.
+ */
+pruneSession(session: Session): PruneResult
+```
+
+Types: [ContentBlock](core.md) · [Session](session.md)
+
+Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index a2af261bc6..48d6fc9c71 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 3a8ccbef4163eabba1cd287284eda68135f2db13
-core.zh.md: 0cd6a57971ee98c75b52dd45b6f648632dab8a90
+core.md: 7e62de88519e5c0bf3a1a0b94de93635767f9f7b
+core.zh.md: ef5b70ae336d55fd25c2251372705912473d07f7
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 3a8ccbef41..7e62de8851 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -53,9 +53,10 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
+| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
 | [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
 
-> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
+> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](#cordis-surface).
 
 ## The `…Map → derived-union` pattern
 
@@ -780,3 +781,546 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional final-content and UI callbacks. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through.
 
 Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxagentloop--agentloop"></a>
+
+### `ctx.agentLoop` — `AgentLoop`
+
+Concrete agent factory and driver service.
+
+```ts cordis-catalog
+/**
+ * Create an agent and session under one caller-supplied identity, owned by
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
+ * id before entering this boundary.
+ * @param id - shared agent/session identity.
+ * @param options - concrete loop options.
+ * @param meta - optional fresh-session workspace metadata.
+ * @returns the published running agent.
+ */
+create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
+
+/**
+ * Create an owned agent on a caller-supplied session id.
+ * @param ownerCtx - caller context that structurally owns the lifecycle.
+ * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Resume an owned agent from the configured persistence service.
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+ * @param options - persisted identity, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
+```
+
+Types: [SessionHeader](persistence.md)
+
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+
+<a id="ctxagents--agentregistry"></a>
+
+### `ctx.agents` — `AgentRegistry`
+
+Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
+
+```ts cordis-catalog
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ *   and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+requireInitiator(): Agent
+
+/**
+ * Run an operation with one exact Agent as its process-local initiator. The
+ * exact synchronous value or Promise returned by the operation is preserved.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+ * @param operation - synchronous or asynchronous operation to invoke.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withInitiator<T>(agent: Agent, operation: () => T): T
+
+/**
+ * Run an operation inside a boundary that hides any inherited initiating
+ * Agent. The exact synchronous value or Promise is preserved.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @param operation - synchronous or asynchronous operation to invoke without an initiator.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withoutInitiator<T>(operation: () => T): T
+
+/**
+ * Register the agent-creation factory (the loop calls this on construction,
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
+ * target; each create/resume call is then traced through that caller's
+ * context so ownership follows the caller without stacking proxy layers.
+ * Throws if a factory is already registered. Returns the disposer; on
+ * dispose the factory slot is cleared.
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+ * @returns the disposer that clears the factory slot. The exact
+ *   Cordis effect disposer (single-shot): composite (generator) effects may
+ *   yield it directly — exact identity nests the teardown in order.
+ */
+setFactory(factory: AgentFactory): () => void
+
+/**
+ * Create and publish a new agent through the registered factory.
+ * Distinct from {@link register} (which records an already-constructed
+ * agent): this constructs the agent and its session. Rejects if no factory is
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+ * the owner tear down exactly this agent.
+ * @param options - shared identity, session seed/metadata, and agent options.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async create(options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Load a persisted session and resume an agent on it through the registered
+ * factory. Rejects if no factory is registered; the factory rejects if
+ * session persistence is not configured or persistence/setup fails.
+ * @param options - persisted identity, configuration, and optional setup.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async resume(options: ResumeAgentOptions): Promise<AgentHandle>
+
+/**
+ * Register a live agent. Throws if an agent with the same id is already
+ * registered. Emits `agent/created` on registration and `agent/disposed`
+ * when the calling fiber is disposed — both with the agent's scope carrier
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+ * emits are scope-filtered regardless of which context invoked `register`
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+ * requires passing the carrier). Returns the disposer.
+ * @param agent - the already-constructed agent to record in the store.
+ * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+ *   returns undefined without awaiting an in-flight teardown). Exact
+ *   identity is load-bearing: a composite (generator) effect that owns a
+ *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+ *   function so Cordis nests the unregistration at that yield position;
+ *   yielding a wrapper would leave it disposing as a concurrent sibling on
+ *   owner unload, unregistering the agent (and emitting `agent/disposed`)
+ *   while its final turn is still draining.
+ */
+register(agent: Agent): () => void
+
+/**
+ * Insert an already-constructed agent without announcing it. This is the
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
+ * first completes setup while the agent is unpublished, then assigns the
+ * returned detach closure into its pre-installed composite teardown before
+ * calling {@link announce}. Ordinary callers use {@link register}.
+ * @param agent - the prepared, unpublished agent.
+ * @param owner - live agent whose scoped context created this agent, or
+ *   undefined for a top-level runtime root. This is runtime ownership, not
+ *   the resumed session's durable parent lineage.
+ * @returns an idempotent closure that removes this exact entry and emits
+ *   `agent/disposed` with listener failures contained. When called from a
+ *   synchronous `agent/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ */
+enter(agent: Agent, owner: Agent | undefined): () => void
+
+/**
+ * Announce an agent previously inserted with {@link enter}.
+ * @param agent - the live inserted agent to announce.
+ * @throws if `agent` is not the exact live registry entry for its id, or its
+ *   creation announcement already began (including a reentrant call from a
+ *   creation listener).
+ */
+announce(agent: Agent): void
+
+/**
+ * Look up a live agent.
+ * @param id - the shared agent/session id to look up.
+ * @returns the agent, or undefined when no live agent has that id.
+ */
+get(id: SessionId): Agent | undefined
+
+/**
+ * Test whether a live agent was created through one exact parent agent's
+ * scoped context. Runtime ownership is independent of durable session
+ * lineage and remains unambiguous when unrelated providers reuse an id.
+ * @param id - the candidate child agent's shared agent/session id.
+ * @param owner - the expected runtime creator agent.
+ * @returns true only while the exact child entry is live under that owner.
+ */
+isOwnedBy(id: SessionId, owner: Agent): boolean
+
+/**
+ * All live agents, in registration order.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+list(): Agent[]
+
+/**
+ * All live top-level agents in registration order. A top-level agent was
+ * created without an owning agent context; durable session lineage does not
+ * affect this runtime relation, so a resumed fork may still be a root.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+roots(): Agent[]
+```
+
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+
+<a id="agent-events"></a>
+
+### `agent/*` events
+
+<a id="agentcreated--emit"></a>
+
+#### `agent/created` — emit
+
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+
+```ts cordis-catalog
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+
+<a id="agentdisposed--emit"></a>
+
+#### `agent/disposed` — emit
+
+An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
+
+```ts cordis-catalog
+/**
+ * An agent left the registry; AgentLoop emits this after driver quiescence
+ * and scoped-registration unwind, but before session detachment. Custom
+ * registry users own their driver-ordering contract.
+ * @param payload.agent - the exact agent removed from the registry.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+
+<a id="agenterror--emit"></a>
+
+#### `agent/error` — emit
+
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+
+```ts cordis-catalog
+/**
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxclaimed--emit"></a>
+
+#### `agent/inbox/claimed` — emit
+
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+
+```ts cordis-catalog
+/**
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxdiscarded--emit"></a>
+
+#### `agent/inbox/discarded` — emit
+
+One message was discarded from the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxinserted--emit"></a>
+
+#### `agent/inbox/inserted` — emit
+
+One message entered the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+
+<a id="agentpre-step--waterfall"></a>
+
+#### `agent/pre-step` — waterfall
+
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+
+```ts cordis-catalog
+/**
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest--waterfall"></a>
+
+#### `agent/request` — waterfall
+
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+
+```ts cordis-catalog
+/**
+ * Replace the frozen call configuration. `await next()` yields the config
+ * the machine would use (agent options on the first request, the logged
+ * header afterwards); return a replacement to switch. Model-visible
+ * content must use logged channels; this seam cannot mutate messages.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+*/
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest-error--waterfall"></a>
+
+#### `agent/request-error` — waterfall
+
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+
+```ts cordis-catalog
+/**
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+```
+
+Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+
+<a id="agentsession-start--emit"></a>
+
+#### `agent/session-start` — emit
+
+The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.
+
+```ts cordis-catalog
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+
+<a id="agentstatus--emit"></a>
+
+#### `agent/status` — emit
+
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+
+```ts cordis-catalog
+/**
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+
+<a id="agentturn-stopping--serial"></a>
+
+#### `agent/turn-stopping` — serial
+
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+
+```ts cordis-catalog
+/**
+ * The turn is about to close: the model owes no response (no live tool
+ * calls, no fresh steering). Awaited before the boundary commits — a
+ * listener that objects steers (`agent.steer(...)`) and the machine
+ * re-reads its inbox: fresh steering runs another step, none closes the
+ * turn. Data decides, so listener order cannot change the outcome. The
+ * inverse control (stop a tool loop early) is data too: a tool result
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+
+<a id="agent-loop-events"></a>
+
+### `agent-loop/*` events
+
+<a id="agent-loopconfig-start-failed--emit"></a>
+
+#### `agent-loop/config-start-failed` — emit
+
+A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
+
+```ts cordis-catalog
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
+ * @mode emit
+ */
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+```
+
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 0cd6a57971..ef5b70ae33 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -53,9 +53,10 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
+| [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
 | [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
 
-> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
+> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](#cordis-surface)。
 
 <a id="the-map--derived-union-pattern"></a>
 
@@ -788,3 +789,546 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
 
 其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxagentloop--agentloop"></a>
+
+### `ctx.agentLoop` — `AgentLoop`
+
+Concrete agent factory and driver service.
+
+```ts cordis-catalog
+/**
+ * Create an agent and session under one caller-supplied identity, owned by
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
+ * id before entering this boundary.
+ * @param id - shared agent/session identity.
+ * @param options - concrete loop options.
+ * @param meta - optional fresh-session workspace metadata.
+ * @returns the published running agent.
+ */
+create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
+
+/**
+ * Create an owned agent on a caller-supplied session id.
+ * @param ownerCtx - caller context that structurally owns the lifecycle.
+ * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Resume an owned agent from the configured persistence service.
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+ * @param options - persisted identity, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
+```
+
+Types: [SessionHeader](persistence.md)
+
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+
+<a id="ctxagents--agentregistry"></a>
+
+### `ctx.agents` — `AgentRegistry`
+
+Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
+
+```ts cordis-catalog
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ *   and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+requireInitiator(): Agent
+
+/**
+ * Run an operation with one exact Agent as its process-local initiator. The
+ * exact synchronous value or Promise returned by the operation is preserved.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+ * @param operation - synchronous or asynchronous operation to invoke.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withInitiator<T>(agent: Agent, operation: () => T): T
+
+/**
+ * Run an operation inside a boundary that hides any inherited initiating
+ * Agent. The exact synchronous value or Promise is preserved.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @param operation - synchronous or asynchronous operation to invoke without an initiator.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withoutInitiator<T>(operation: () => T): T
+
+/**
+ * Register the agent-creation factory (the loop calls this on construction,
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
+ * target; each create/resume call is then traced through that caller's
+ * context so ownership follows the caller without stacking proxy layers.
+ * Throws if a factory is already registered. Returns the disposer; on
+ * dispose the factory slot is cleared.
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+ * @returns the disposer that clears the factory slot. The exact
+ *   Cordis effect disposer (single-shot): composite (generator) effects may
+ *   yield it directly — exact identity nests the teardown in order.
+ */
+setFactory(factory: AgentFactory): () => void
+
+/**
+ * Create and publish a new agent through the registered factory.
+ * Distinct from {@link register} (which records an already-constructed
+ * agent): this constructs the agent and its session. Rejects if no factory is
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+ * the owner tear down exactly this agent.
+ * @param options - shared identity, session seed/metadata, and agent options.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async create(options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Load a persisted session and resume an agent on it through the registered
+ * factory. Rejects if no factory is registered; the factory rejects if
+ * session persistence is not configured or persistence/setup fails.
+ * @param options - persisted identity, configuration, and optional setup.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async resume(options: ResumeAgentOptions): Promise<AgentHandle>
+
+/**
+ * Register a live agent. Throws if an agent with the same id is already
+ * registered. Emits `agent/created` on registration and `agent/disposed`
+ * when the calling fiber is disposed — both with the agent's scope carrier
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+ * emits are scope-filtered regardless of which context invoked `register`
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+ * requires passing the carrier). Returns the disposer.
+ * @param agent - the already-constructed agent to record in the store.
+ * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+ *   returns undefined without awaiting an in-flight teardown). Exact
+ *   identity is load-bearing: a composite (generator) effect that owns a
+ *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+ *   function so Cordis nests the unregistration at that yield position;
+ *   yielding a wrapper would leave it disposing as a concurrent sibling on
+ *   owner unload, unregistering the agent (and emitting `agent/disposed`)
+ *   while its final turn is still draining.
+ */
+register(agent: Agent): () => void
+
+/**
+ * Insert an already-constructed agent without announcing it. This is the
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
+ * first completes setup while the agent is unpublished, then assigns the
+ * returned detach closure into its pre-installed composite teardown before
+ * calling {@link announce}. Ordinary callers use {@link register}.
+ * @param agent - the prepared, unpublished agent.
+ * @param owner - live agent whose scoped context created this agent, or
+ *   undefined for a top-level runtime root. This is runtime ownership, not
+ *   the resumed session's durable parent lineage.
+ * @returns an idempotent closure that removes this exact entry and emits
+ *   `agent/disposed` with listener failures contained. When called from a
+ *   synchronous `agent/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ */
+enter(agent: Agent, owner: Agent | undefined): () => void
+
+/**
+ * Announce an agent previously inserted with {@link enter}.
+ * @param agent - the live inserted agent to announce.
+ * @throws if `agent` is not the exact live registry entry for its id, or its
+ *   creation announcement already began (including a reentrant call from a
+ *   creation listener).
+ */
+announce(agent: Agent): void
+
+/**
+ * Look up a live agent.
+ * @param id - the shared agent/session id to look up.
+ * @returns the agent, or undefined when no live agent has that id.
+ */
+get(id: SessionId): Agent | undefined
+
+/**
+ * Test whether a live agent was created through one exact parent agent's
+ * scoped context. Runtime ownership is independent of durable session
+ * lineage and remains unambiguous when unrelated providers reuse an id.
+ * @param id - the candidate child agent's shared agent/session id.
+ * @param owner - the expected runtime creator agent.
+ * @returns true only while the exact child entry is live under that owner.
+ */
+isOwnedBy(id: SessionId, owner: Agent): boolean
+
+/**
+ * All live agents, in registration order.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+list(): Agent[]
+
+/**
+ * All live top-level agents in registration order. A top-level agent was
+ * created without an owning agent context; durable session lineage does not
+ * affect this runtime relation, so a resumed fork may still be a root.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+roots(): Agent[]
+```
+
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+
+<a id="agent-events"></a>
+
+### `agent/*` events
+
+<a id="agentcreated--emit"></a>
+
+#### `agent/created` — emit
+
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+
+```ts cordis-catalog
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+
+<a id="agentdisposed--emit"></a>
+
+#### `agent/disposed` — emit
+
+An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
+
+```ts cordis-catalog
+/**
+ * An agent left the registry; AgentLoop emits this after driver quiescence
+ * and scoped-registration unwind, but before session detachment. Custom
+ * registry users own their driver-ordering contract.
+ * @param payload.agent - the exact agent removed from the registry.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+
+<a id="agenterror--emit"></a>
+
+#### `agent/error` — emit
+
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+
+```ts cordis-catalog
+/**
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxclaimed--emit"></a>
+
+#### `agent/inbox/claimed` — emit
+
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+
+```ts cordis-catalog
+/**
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxdiscarded--emit"></a>
+
+#### `agent/inbox/discarded` — emit
+
+One message was discarded from the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxinserted--emit"></a>
+
+#### `agent/inbox/inserted` — emit
+
+One message entered the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+
+<a id="agentpre-step--waterfall"></a>
+
+#### `agent/pre-step` — waterfall
+
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+
+```ts cordis-catalog
+/**
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest--waterfall"></a>
+
+#### `agent/request` — waterfall
+
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+
+```ts cordis-catalog
+/**
+ * Replace the frozen call configuration. `await next()` yields the config
+ * the machine would use (agent options on the first request, the logged
+ * header afterwards); return a replacement to switch. Model-visible
+ * content must use logged channels; this seam cannot mutate messages.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+*/
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest-error--waterfall"></a>
+
+#### `agent/request-error` — waterfall
+
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+
+```ts cordis-catalog
+/**
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+```
+
+Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+
+<a id="agentsession-start--emit"></a>
+
+#### `agent/session-start` — emit
+
+The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.
+
+```ts cordis-catalog
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+
+<a id="agentstatus--emit"></a>
+
+#### `agent/status` — emit
+
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+
+```ts cordis-catalog
+/**
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+
+<a id="agentturn-stopping--serial"></a>
+
+#### `agent/turn-stopping` — serial
+
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+
+```ts cordis-catalog
+/**
+ * The turn is about to close: the model owes no response (no live tool
+ * calls, no fresh steering). Awaited before the boundary commits — a
+ * listener that objects steers (`agent.steer(...)`) and the machine
+ * re-reads its inbox: fresh steering runs another step, none closes the
+ * turn. Data decides, so listener order cannot change the outcome. The
+ * inverse control (stop a tool loop early) is data too: a tool result
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+
+<a id="agent-loop-events"></a>
+
+### `agent-loop/*` events
+
+<a id="agent-loopconfig-start-failed--emit"></a>
+
+#### `agent-loop/config-start-failed` — emit
+
+A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
+
+```ts cordis-catalog
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
+ * @mode emit
+ */
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+```
+
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index f7899eaf6e..7028d71f8d 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e
-credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8
+credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
+credentials.zh.md: 6f5ccd1572885434257d39eb0f659fcc7371ad1d
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index ef74ddeb43..0bc2224ac0 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -48,3 +48,86 @@ interface CredentialInfo {
 ## Change commits
 
 `credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcredentials--credentials-abstract-seam"></a>
+
+### `ctx.credentials` — `Credentials` (abstract seam)
+
+Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+```ts cordis-catalog
+/**
+ * Resolve one reference to its current value. Resolution is per call:
+ * consumers re-resolve at each operation and must not cache across
+ * operations — that per-operation read is what makes a changed credential
+ * reach the next operation without a restart.
+ * @param ref - the reference to resolve.
+ * @returns the value and its source, or `undefined` while unconfigured.
+ */
+abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+/**
+ * Describe one reference for configuration surfaces without exposing the
+ * value.
+ * @param ref - the reference to describe.
+ * @returns configured state, supplying source, and writability.
+ */
+abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+/**
+ * Durably store one value in the provider-managed writable source. Rejects
+ * while a read-only source shadows the reference — the write would appear
+ * to succeed while resolution keeps returning the shadowing value — and
+ * rejects an empty value (use {@link unset}).
+ * @param ref - the reference to store.
+ * @param value - the non-empty secret value.
+ */
+abstract set(ref: CredentialRef, value: string): Promise<void>
+
+/**
+ * Remove one reference from the provider-managed writable source; removing
+ * an absent reference is a no-op. Rejects while a read-only source shadows
+ * the reference, like {@link set}.
+ * @param ref - the reference to remove.
+ */
+abstract unset(ref: CredentialRef): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="credentials-events"></a>
+
+### `credentials/*` events
+
+<a id="credentialsupdated--emit"></a>
+
+#### `credentials/updated` — emit
+
+Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to a provider-managed credential source: a `set`, an
+ * `unset`, or an external edit observed in storage. Ambient
+ * process-environment changes are not observable and never emit. Listener
+ * failures are contained and logged — a sync throw and an async rejection
+ * alike — without changing the committed operation's outcome, except
+ * `INVARIANT`-coded failures, which rethrow after every listener ran;
+ * that rethrow reaches the emitter only from synchronous listeners, so
+ * invariant checks on this event must not be async functions.
+ * @param ref - the reference whose stored value changed.
+ * @mode emit
+ */
+'credentials/updated'(ref: CredentialRef): void
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 09cf374a23..6f5ccd1572 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -48,3 +48,86 @@ interface CredentialInfo {
 ## 变更提交
 
 `credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcredentials--credentials-abstract-seam"></a>
+
+### `ctx.credentials` — `Credentials` (abstract seam)
+
+Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+```ts cordis-catalog
+/**
+ * Resolve one reference to its current value. Resolution is per call:
+ * consumers re-resolve at each operation and must not cache across
+ * operations — that per-operation read is what makes a changed credential
+ * reach the next operation without a restart.
+ * @param ref - the reference to resolve.
+ * @returns the value and its source, or `undefined` while unconfigured.
+ */
+abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+/**
+ * Describe one reference for configuration surfaces without exposing the
+ * value.
+ * @param ref - the reference to describe.
+ * @returns configured state, supplying source, and writability.
+ */
+abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+/**
+ * Durably store one value in the provider-managed writable source. Rejects
+ * while a read-only source shadows the reference — the write would appear
+ * to succeed while resolution keeps returning the shadowing value — and
+ * rejects an empty value (use {@link unset}).
+ * @param ref - the reference to store.
+ * @param value - the non-empty secret value.
+ */
+abstract set(ref: CredentialRef, value: string): Promise<void>
+
+/**
+ * Remove one reference from the provider-managed writable source; removing
+ * an absent reference is a no-op. Rejects while a read-only source shadows
+ * the reference, like {@link set}.
+ * @param ref - the reference to remove.
+ */
+abstract unset(ref: CredentialRef): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="credentials-events"></a>
+
+### `credentials/*` events
+
+<a id="credentialsupdated--emit"></a>
+
+#### `credentials/updated` — emit
+
+Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to a provider-managed credential source: a `set`, an
+ * `unset`, or an external edit observed in storage. Ambient
+ * process-environment changes are not observable and never emit. Listener
+ * failures are contained and logged — a sync throw and an async rejection
+ * alike — without changing the committed operation's outcome, except
+ * `INVARIANT`-coded failures, which rethrow after every listener ran;
+ * that rethrow reaches the emitter only from synchronous listeners, so
+ * invariant checks on this event must not be async functions.
+ * @param ref - the reference whose stored value changed.
+ * @mode emit
+ */
+'credentials/updated'(ref: CredentialRef): void
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 2f9478a7ba..cadc2b92d8 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/filesystem.md
-filesystem.md: addded9f673ed435e95109d4fb772967514c0b87
-filesystem.zh.md: 1e378928ed570b97dbec73b836a7e6ff18726ff8
+#   pnpm run verify-translation-pairing --write docs/subsystems/filesystem.md
+filesystem.md: 1999399254fa5d72ab222a42a2fa8f4b890da50a
+filesystem.zh.md: 044a1c5be91ed8bec5d0442cc6f7edfde6870785
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index addded9f67..1999399254 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -181,7 +181,7 @@ interface FsEditOutcome {
 
 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
-`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated catalog shows the exact signatures on [events.md](../cordis-catalog/events.md).
+`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
 
 ## Execution context (policy plugin)
 
@@ -258,4 +258,208 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxfs--filesystem-abstract-seam"></a>
+
+### `ctx.fs` — `FileSystem` (abstract seam)
+
+Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
+
+```ts cordis-catalog
+/**
+ * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+ * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+ * async even though the local backend only normalizes + realpaths.
+ *
+ * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+ * @param opts - optional cwd override and cancellation signal.
+ * @returns the stable target; the same file yields the same `targetKey`.
+ */
+abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
+
+/**
+ * Return the canonical absolute path a subprocess in this filesystem's
+ * execution world can open. The path is deliberately separate from
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+ * capability, but must continue treating the target key as opaque.
+ * @param target - the resolved target whose process path is required.
+ * @returns an absolute path in the backend's execution world.
+ */
+abstract processPath(target: FsTarget): string
+
+/**
+ * Return the canonical `file:` URI for a target in this filesystem's
+ * execution world. Backends own URI encoding because the host platform may
+ * differ from the execution platform.
+ * @param target - the resolved target to encode.
+ * @returns the target's canonical file URI.
+ */
+abstract fileUrl(target: FsTarget): string
+
+/**
+ * Test canonical containment without exposing or parsing backend target
+ * keys. Both targets must come from this provider.
+ * @param parent - canonical directory target.
+ * @param child - canonical candidate target.
+ * @returns true when `child` is `parent` or a descendant of it.
+ */
+abstract contains(parent: FsTarget, child: FsTarget): boolean
+
+/**
+ * Return target metadata, or `undefined` when the target does not exist.
+ * @param target - the resolved target to stat.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent target.
+ */
+abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
+
+/**
+ * Return path metadata without following the final path component when it is a
+ * symbolic link. This is intentionally path-shaped, not target-shaped:
+ * {@link resolve} follows symlinks to produce the stable identity used by
+ * normal reads/writes, while `lstat` lets a consumer reject the path itself
+ * before that follow happens.
+ *
+ * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+ * absent.
+ * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+ * @param opts - `cwd` overrides the backend's default base for relative paths.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent path.
+ */
+abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+
+/**
+ * Read the whole regular text file as a single decoded string.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the read.
+ * @returns the full decoded UTF-8 content.
+ */
+abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
+
+/**
+ * Stream the whole regular text file as decoded text chunks (same text
+ * semantics as {@link readText}, for large files). The backend owns
+ * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+ * touches raw bytes.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the stream, including between chunks.
+ * @returns the chunk iterable, decoded and validated like {@link readText}.
+ */
+abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
+
+/**
+ * List direct children of a directory in stable name order. Returns resolved
+ * child targets plus cheap metadata only; never reads file contents.
+ * @param target - the resolved directory target.
+ * @param signal - aborts the listing.
+ * @returns one entry per direct child, in stable name order.
+ */
+abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
+
+/**
+ * Atomically create or replace UTF-8 text. `expected` guards intent and
+ * staleness; omission allows unconditional overwrite.
+ * @param target - the resolved target to write.
+ * @param content - the full new file content.
+ * @param expected - the write intent guarding the write; omit for unconditional.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this write
+ *   runs under; a sandboxing backend fences the write by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the write produced.
+ */
+abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
+
+/**
+ * Atomically edit literal text. When supplied, the version guard is checked
+ * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+ * the current content without a freshness precondition.
+ * @param target - the resolved target to edit.
+ * @param edit - the literal search/replace request.
+ * @param expected - the version guard; omit for an unconditional edit.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+ *   under; a sandboxing backend fences the edit by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the edit produced.
+ */
+abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
+```
+
+Types: [SandboxExecutionPolicy](sandbox.md)
+
+Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+
+<a id="fs-events"></a>
+
+### `fs/*` events
+
+<a id="fsedit-intent--waterfall"></a>
+
+#### `fs/edit-intent` — waterfall
+
+Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+
+<a id="fsobserved--emit"></a>
+
+#### `fs/observed` — emit
+
+Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+
+```ts cordis-catalog
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
+'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+```
+
+Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+
+<a id="fswrite-intent--waterfall"></a>
+
+#### `fs/write-intent` — waterfall
+
+Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 1e378928ed..044a1c5be9 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -181,7 +181,7 @@ interface FsEditOutcome {
 
 `dsh-fs` 拥有三个事件，由工具分发、策略插件监听，使发射方（`dsh-tool-fs`）与监听方（`dsh-fs-policy`）共享词汇，而发射方无需依赖策略插件。它们只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不含面向模型的概念，也不含 agent/会话所有者结构。
 
-`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方会导致工具为一次已经成功的变更返回 `isError` 结果。生成的目录在 [events.md](../cordis-catalog/events.md) 中展示确切签名。
+`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方会导致工具为一次已经成功的变更返回 `isError` 结果。下方生成的 [cordis surface](#cordis-surface) 展示确切签名。
 
 ## 执行上下文（策略插件）
 
@@ -258,4 +258,208 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxfs--filesystem-abstract-seam"></a>
+
+### `ctx.fs` — `FileSystem` (abstract seam)
+
+Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
+
+```ts cordis-catalog
+/**
+ * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+ * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+ * async even though the local backend only normalizes + realpaths.
+ *
+ * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+ * @param opts - optional cwd override and cancellation signal.
+ * @returns the stable target; the same file yields the same `targetKey`.
+ */
+abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
+
+/**
+ * Return the canonical absolute path a subprocess in this filesystem's
+ * execution world can open. The path is deliberately separate from
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+ * capability, but must continue treating the target key as opaque.
+ * @param target - the resolved target whose process path is required.
+ * @returns an absolute path in the backend's execution world.
+ */
+abstract processPath(target: FsTarget): string
+
+/**
+ * Return the canonical `file:` URI for a target in this filesystem's
+ * execution world. Backends own URI encoding because the host platform may
+ * differ from the execution platform.
+ * @param target - the resolved target to encode.
+ * @returns the target's canonical file URI.
+ */
+abstract fileUrl(target: FsTarget): string
+
+/**
+ * Test canonical containment without exposing or parsing backend target
+ * keys. Both targets must come from this provider.
+ * @param parent - canonical directory target.
+ * @param child - canonical candidate target.
+ * @returns true when `child` is `parent` or a descendant of it.
+ */
+abstract contains(parent: FsTarget, child: FsTarget): boolean
+
+/**
+ * Return target metadata, or `undefined` when the target does not exist.
+ * @param target - the resolved target to stat.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent target.
+ */
+abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
+
+/**
+ * Return path metadata without following the final path component when it is a
+ * symbolic link. This is intentionally path-shaped, not target-shaped:
+ * {@link resolve} follows symlinks to produce the stable identity used by
+ * normal reads/writes, while `lstat` lets a consumer reject the path itself
+ * before that follow happens.
+ *
+ * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+ * absent.
+ * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+ * @param opts - `cwd` overrides the backend's default base for relative paths.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent path.
+ */
+abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+
+/**
+ * Read the whole regular text file as a single decoded string.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the read.
+ * @returns the full decoded UTF-8 content.
+ */
+abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
+
+/**
+ * Stream the whole regular text file as decoded text chunks (same text
+ * semantics as {@link readText}, for large files). The backend owns
+ * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+ * touches raw bytes.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the stream, including between chunks.
+ * @returns the chunk iterable, decoded and validated like {@link readText}.
+ */
+abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
+
+/**
+ * List direct children of a directory in stable name order. Returns resolved
+ * child targets plus cheap metadata only; never reads file contents.
+ * @param target - the resolved directory target.
+ * @param signal - aborts the listing.
+ * @returns one entry per direct child, in stable name order.
+ */
+abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
+
+/**
+ * Atomically create or replace UTF-8 text. `expected` guards intent and
+ * staleness; omission allows unconditional overwrite.
+ * @param target - the resolved target to write.
+ * @param content - the full new file content.
+ * @param expected - the write intent guarding the write; omit for unconditional.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this write
+ *   runs under; a sandboxing backend fences the write by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the write produced.
+ */
+abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
+
+/**
+ * Atomically edit literal text. When supplied, the version guard is checked
+ * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+ * the current content without a freshness precondition.
+ * @param target - the resolved target to edit.
+ * @param edit - the literal search/replace request.
+ * @param expected - the version guard; omit for an unconditional edit.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+ *   under; a sandboxing backend fences the edit by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the edit produced.
+ */
+abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
+```
+
+Types: [SandboxExecutionPolicy](sandbox.md)
+
+Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+
+<a id="fs-events"></a>
+
+### `fs/*` events
+
+<a id="fsedit-intent--waterfall"></a>
+
+#### `fs/edit-intent` — waterfall
+
+Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+
+<a id="fsobserved--emit"></a>
+
+#### `fs/observed` — emit
+
+Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+
+```ts cordis-catalog
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
+'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+```
+
+Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+
+<a id="fswrite-intent--waterfall"></a>
+
+#### `fs/write-intent` — waterfall
+
+Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
index 625556f99a..945ed658d2 100644
--- a/docs/subsystems/goal.i18n.yaml
+++ b/docs/subsystems/goal.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/goal.md
-goal.md: fc6a7e63e58fc7cd4bc524be1e66515593680d95
-goal.zh.md: c584cb375bd55c13c158e7ee22d7721040dffa05
+#   pnpm run verify-translation-pairing --write docs/subsystems/goal.md
+goal.md: 6f54a5261cb44c3fda389e37cb689a00061ab241
+goal.zh.md: 043263f3231b4c727f21ca0b8fc07d8adffa0559
diff --git a/docs/subsystems/goal.md b/docs/subsystems/goal.md
index fc6a7e63e5..6f54a5261c 100644
--- a/docs/subsystems/goal.md
+++ b/docs/subsystems/goal.md
@@ -143,3 +143,135 @@ interface GoalChanged {
 ## Service behavior
 
 [`GoalService`](../../packages/goal/goal/src/index.ts) resolves creation defaults, folds strict replay from durable `goal/change` events, enforces exact-live-agent identity and compare-and-set mutations, and emits contained `goal/changed` notifications. The package [README](../../packages/goal/goal/README.md) owns the callable and model-visible contract.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxgoals--goalservice"></a>
+
+### `ctx.goals` — `GoalService`
+
+Goal service (`ctx.goals`) backed exclusively by the owning session log.
+
+```ts cordis-catalog
+/**
+ * Read the current goal for one exact live agent.
+ * @param agent - owning live agent.
+ * @returns a fresh view or `undefined` when no goal is current.
+ * @throws {@link GoalError} when the agent is not the registry's live instance.
+ */
+get(agent: Agent): GoalView | undefined
+
+/**
+ * Remove process-local continuation authority without changing durable goal
+ * phase or revision. Lifecycle owners use this before unloading a driver;
+ * a later human-authorized {@link resume} records the new activation edge.
+ * @param agent - owning live agent.
+ * @returns a fresh disarmed view, or `undefined` when no goal is current.
+ */
+disarm(agent: Agent): GoalView | undefined
+
+/**
+ * Create and arm a goal. A completed goal may be replaced; every other
+ * current phase must be cleared or resumed instead.
+ * @param agent - owning live agent.
+ * @param request - objective and optional round cap.
+ * @returns the created live view.
+ */
+create(agent: Agent, request: CreateGoalRequest): GoalView
+
+/**
+ * Edit objective and/or round cap without changing phase.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param request - at least one replacement field.
+ * @returns the edited view.
+ */
+@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
+
+/**
+ * Pause an active goal and disarm automatic continuation.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the paused view.
+ */
+@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Resume and arm a stopped goal, or rearm an active goal after a
+ * session-start edge, while its round budget still has capacity.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the active view.
+ */
+@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark a current non-complete goal complete and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the completed view.
+ */
+@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark an active goal blocked and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param reason - policy-owned stable code and human-readable explanation.
+ * @returns the blocked view with its durable reason.
+ */
+block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
+
+/**
+ * Clear the current goal while retaining a durable tombstone and history.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the tombstone ref whose revision is one past the cleared snapshot.
+ */
+@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
+
+/**
+ * Create one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param request - objective and optional round cap.
+ * @returns the created Goal identity.
+ */
+@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
+
+<a id="goal-events"></a>
+
+### `goal/*` events
+
+<a id="goalchanged--emit"></a>
+
+#### `goal/changed` — emit
+
+Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Goal mutation accepted by one live agent. The matching `goal/change`
+ * session event has already committed. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param payload.agent - agent whose session owns the goal.
+ * @param payload.change - fresh current projection or clear tombstone.
+ * @mode emit
+ */
+'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
+```
+
+Types: [Agent](core.md) · [Scoped](scope.md)
+
+Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/goal.zh.md b/docs/subsystems/goal.zh.md
index c584cb375b..043263f323 100644
--- a/docs/subsystems/goal.zh.md
+++ b/docs/subsystems/goal.zh.md
@@ -143,3 +143,135 @@ interface GoalChanged {
 ## 服务行为
 
 [`GoalService`](../../packages/goal/goal/src/index.ts) 解析创建默认值、从持久 `goal/change` 事件执行严格回放折叠、校验确切的活跃 agent 身份、以比较并设置方式执行变更，并发出 `goal/changed` 通知；监听器故障会被隔离。包 [README](../../packages/goal/goal/README.md) 负责记录可调用契约和面向模型的契约。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxgoals--goalservice"></a>
+
+### `ctx.goals` — `GoalService`
+
+Goal service (`ctx.goals`) backed exclusively by the owning session log.
+
+```ts cordis-catalog
+/**
+ * Read the current goal for one exact live agent.
+ * @param agent - owning live agent.
+ * @returns a fresh view or `undefined` when no goal is current.
+ * @throws {@link GoalError} when the agent is not the registry's live instance.
+ */
+get(agent: Agent): GoalView | undefined
+
+/**
+ * Remove process-local continuation authority without changing durable goal
+ * phase or revision. Lifecycle owners use this before unloading a driver;
+ * a later human-authorized {@link resume} records the new activation edge.
+ * @param agent - owning live agent.
+ * @returns a fresh disarmed view, or `undefined` when no goal is current.
+ */
+disarm(agent: Agent): GoalView | undefined
+
+/**
+ * Create and arm a goal. A completed goal may be replaced; every other
+ * current phase must be cleared or resumed instead.
+ * @param agent - owning live agent.
+ * @param request - objective and optional round cap.
+ * @returns the created live view.
+ */
+create(agent: Agent, request: CreateGoalRequest): GoalView
+
+/**
+ * Edit objective and/or round cap without changing phase.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param request - at least one replacement field.
+ * @returns the edited view.
+ */
+@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
+
+/**
+ * Pause an active goal and disarm automatic continuation.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the paused view.
+ */
+@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Resume and arm a stopped goal, or rearm an active goal after a
+ * session-start edge, while its round budget still has capacity.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the active view.
+ */
+@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark a current non-complete goal complete and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the completed view.
+ */
+@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark an active goal blocked and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param reason - policy-owned stable code and human-readable explanation.
+ * @returns the blocked view with its durable reason.
+ */
+block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
+
+/**
+ * Clear the current goal while retaining a durable tombstone and history.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the tombstone ref whose revision is one past the cleared snapshot.
+ */
+@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
+
+/**
+ * Create one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param request - objective and optional round cap.
+ * @returns the created Goal identity.
+ */
+@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
+
+<a id="goal-events"></a>
+
+### `goal/*` events
+
+<a id="goalchanged--emit"></a>
+
+#### `goal/changed` — emit
+
+Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Goal mutation accepted by one live agent. The matching `goal/change`
+ * session event has already committed. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param payload.agent - agent whose session owns the goal.
+ * @param payload.change - fresh current projection or clear tombstone.
+ * @mode emit
+ */
+'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
+```
+
+Types: [Agent](core.md) · [Scoped](scope.md)
+
+Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 6f1facfad7..3674a95c44 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.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 docs/subsystems/http-server.md
-http-server.md: 200d3eed683f203b65824ea3f62cf56ce3df912f
-http-server.zh.md: 9a12d3769a93270810927075be5f236875688b91
+http-server.md: b9795fe98b432b6ef5f7d01a4d3e115c809fe642
+http-server.zh.md: c3ba02dce5c58f491921f1fb31f999f9da808bc5
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
index 200d3eed68..b9795fe98b 100644
--- a/docs/subsystems/http-server.md
+++ b/docs/subsystems/http-server.md
@@ -45,3 +45,64 @@ interface Config {
 `HttpServerService` (`ctx.httpServer`) listens immediately on activation; a listen failure (EADDRINUSE…) throws out of init — a FAILED fiber the boot's fail-loud sweep reports. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws, because route patterns are a composition-level contract and a collision is a misconfiguration. `tapIndex(transform)` adds a pure html-to-html transform applied to every index response — `/` and each SPA fallback — in registration order; [dsh-client-modules](../../packages/client/modules) uses it to inject the boot manifest. `port` reads the listening port, the OS-assigned value when `config.port` is 0.
 
 A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 — or the socket destroyed when headers are already out — never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](../../packages/host/webserver/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxhttpserver--httpserverservice"></a>
+
+### `ctx.httpServer` — `HttpServerService`
+
+The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
+
+```ts cordis-catalog
+/**
+ * Register a named route. Duplicate (kind, path) throws — route patterns are
+ * a composition-level contract, so a collision is a misconfiguration.
+ * @param route - kind, path, and the owning handler.
+ * @returns the disposer removing the route.
+ */
+register(route: WebRoute): () => void
+
+/**
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
+ * one socket can have only one protocol owner.
+ * @param route - pathname and handler owning negotiation plus socket use.
+ * @returns the disposer removing the route.
+ */
+registerUpgrade(route: WebUpgradeRoute): () => void
+
+/**
+ * Claim the fallback seat: the handler answering every request no named
+ * route matches (the SPA dist server in the shipped Web composition). One
+ * owner only — a second registration throws, because two fallbacks cannot
+ * compose.
+ * @param handler - owns the full response lifecycle of unmatched requests.
+ * @returns the disposer releasing the seat.
+ */
+registerFallback(handler: WebRoute['handler']): () => void
+
+/**
+ * Register an index.html transform, applied by the fallback owner to every
+ * index response ({@link applyIndexTaps}) in registration order.
+ * @param transform - pure html-to-html function.
+ * @returns the disposer removing the transform.
+ */
+tapIndex(transform: (html: string) => string): () => void
+
+/**
+ * Run an index.html body through the registered taps in registration order
+ * — called by the fallback owner on every index response it renders.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+applyIndexTaps(html: string): string
+```
+
+Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index 9a12d3769a..c3ba02dce5 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -45,3 +45,64 @@ interface Config {
 `HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
 
 处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包（package）从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxhttpserver--httpserverservice"></a>
+
+### `ctx.httpServer` — `HttpServerService`
+
+The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
+
+```ts cordis-catalog
+/**
+ * Register a named route. Duplicate (kind, path) throws — route patterns are
+ * a composition-level contract, so a collision is a misconfiguration.
+ * @param route - kind, path, and the owning handler.
+ * @returns the disposer removing the route.
+ */
+register(route: WebRoute): () => void
+
+/**
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
+ * one socket can have only one protocol owner.
+ * @param route - pathname and handler owning negotiation plus socket use.
+ * @returns the disposer removing the route.
+ */
+registerUpgrade(route: WebUpgradeRoute): () => void
+
+/**
+ * Claim the fallback seat: the handler answering every request no named
+ * route matches (the SPA dist server in the shipped Web composition). One
+ * owner only — a second registration throws, because two fallbacks cannot
+ * compose.
+ * @param handler - owns the full response lifecycle of unmatched requests.
+ * @returns the disposer releasing the seat.
+ */
+registerFallback(handler: WebRoute['handler']): () => void
+
+/**
+ * Register an index.html transform, applied by the fallback owner to every
+ * index response ({@link applyIndexTaps}) in registration order.
+ * @param transform - pure html-to-html function.
+ * @returns the disposer removing the transform.
+ */
+tapIndex(transform: (html: string) => string): () => void
+
+/**
+ * Run an index.html body through the registered taps in registration order
+ * — called by the fallback owner on every index response it renders.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+applyIndexTaps(html: string): string
+```
+
+Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 27b6ac8e87..8ef657b3a4 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.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 docs/subsystems/invariants.md
-invariants.md: 143a7feabbab18556f595a78c7aef17caa6d3028
-invariants.zh.md: fb497857c02202544edf44ccfe3a2935a988e30e
+invariants.md: 184d982bb27ab3ff98f715f0751c8bfcc1d08bea
+invariants.zh.md: bd2f83a018642832fe50ba5cca6dd82e2bd7d59b
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
index 143a7feabb..184d982bb2 100644
--- a/docs/subsystems/invariants.md
+++ b/docs/subsystems/invariants.md
@@ -57,3 +57,32 @@ An enabled installer runs in a dedicated child Cordis fiber; `installer.inject`
 ## The companion contract
 
 Every workspace package owns a `./invariant` companion ([package contract](../../packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](../../packages/support/invariants/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxinvariants--invariantservice"></a>
+
+### `ctx.invariants` — `InvariantService`
+
+Package-owned invariant registry with global and regex-based selection.
+
+```ts cordis-catalog
+/**
+ * Register one package's invariant installer. The package name is reserved
+ * even when filtering disables its checks. Enabled installers run in a child
+ * fiber; failure disposes that fiber and releases the reservation.
+ * @param packageName - full npm package name that owns the contribution.
+ * @param installer - listener or startup-check installer for the child context.
+ * @returns an effect-scoped disposer for the registration.
+ */
+register(packageName: string, installer: InvariantInstaller): () => void
+```
+
+Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index fb497857c0..bd2f83a018 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -57,3 +57,32 @@ interface InvariantInstaller {
 ## 配套插件契约
 
 每个工作区包都拥有一个 `./invariant` 配套插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxinvariants--invariantservice"></a>
+
+### `ctx.invariants` — `InvariantService`
+
+Package-owned invariant registry with global and regex-based selection.
+
+```ts cordis-catalog
+/**
+ * Register one package's invariant installer. The package name is reserved
+ * even when filtering disables its checks. Enabled installers run in a child
+ * fiber; failure disposes that fiber and releases the reservation.
+ * @param packageName - full npm package name that owns the contribution.
+ * @param installer - listener or startup-check installer for the child context.
+ * @returns an effect-scoped disposer for the registration.
+ */
+register(packageName: string, installer: InvariantInstaller): () => void
+```
+
+Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 1ff1a1d42b..bd1d833f51 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 5c90b3ce4ac65a99997f6ba7ad5deac494b7f772
-llm-streaming.zh.md: 7fd0043234cb40d6b21cec6ff101993164785a6e
+llm-streaming.md: fe4a831660dd81b33a1cd7dc9a9d7026f3831991
+llm-streaming.zh.md: a10b696ec0887e139785fc7e95d8641e6496de79
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 5c90b3ce4a..fe4a831660 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -255,3 +255,191 @@ interface ContentBlockMap {
 ```
 
 See [core.md § Content blocks and messages](core.md#content-blocks-and-messages) for the block interfaces.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxllm--llmservice"></a>
+
+### `ctx.llm` — `LlmService`
+
+The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+
+```ts cordis-catalog
+/**
+ * Register an adapter for the given provider routes. Throws `LlmError` with code
+ * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+ * Disposed with the fiber.
+ * @param providers - every provider route this adapter should serve.
+ * @param adapter - the adapter that streams calls for those providers.
+ * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+ */
+registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
+
+/**
+ * Describe provider routes with a registered adapter.
+ * @returns detached provider metadata in registration order.
+ */
+listProviders(): LlmProviderInfo[]
+
+/**
+ * Declare provider routes an adapter plugin can activate through
+ * configuration. Registration is all-or-nothing: an empty list, invalid
+ * entry, or a provider already declared by any registration throws
+ * `LlmError` without registering the rest. Disposed with the fiber.
+ * @param entries - every configurable provider this plugin owns.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
+ */
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+
+/**
+ * List every declared configurable provider, registered or dormant.
+ * @returns detached directory entries in declaration order.
+ */
+listConfigurableProviders(): LlmConfigurableProvider[]
+
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
+/**
+ * Resolve the retry policy captured when one provider route was registered.
+ * @param provider - registered provider route to inspect.
+ * @returns the provider-owned policy, with normal defaults already resolved.
+ */
+providerRetryPolicy(provider: string): ResolvedRetryPolicy
+
+/**
+ * Discover models advertised by one registered provider. Catalog membership
+ * is advisory and never changes routing or request validation.
+ * @param provider - registered provider route to inspect.
+ * @returns detached model metadata in adapter-preferred order.
+ */
+async listModels(provider: string): Promise<LlmModelInfo[]>
+
+/**
+ * Resolve and validate all metadata from the adapter that owns one exact
+ * route. The result is detached from adapter-owned objects; catalog
+ * membership remains advisory and does not control request routing.
+ * @param provider - registered provider route to inspect.
+ * @param model - exact model id passed to the adapter.
+ * @param signal - optional cancellation for adapter-owned asynchronous lookup.
+ * @returns exact model identity plus available context and reasoning metadata.
+ */
+async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>
+
+/**
+ * Validate a conversation call config against its exact model capability and
+ * materialize adapter-configured defaults. Unsupported explicit efforts
+ * reject before provider I/O; no clamping or aliasing is performed. This
+ * standalone query does not bind a later dispatch; use {@link prepareCall}
+ * when logging and streaming must share one adapter registration.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a detached config only when a default must be materialized.
+ */
+async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>
+
+/**
+ * Resolve one call under its current adapter registration. The returned
+ * one-shot handle keeps that registration across header logging and dispatch,
+ * so HMR cannot combine one adapter's capability result with another adapter.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a prepared config and its registration-bound stream entry point.
+ */
+async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
+
+/**
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
+ * @param options - the full request; `options.provider` selects the adapter.
+ * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+ */
+stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+```
+
+Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+
+<a id="llm-events"></a>
+
+### `llm/*` events
+
+<a id="llmadapters-updated--emit"></a>
+
+#### `llm/adapters-updated` — emit
+
+The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This is a payload-free registry notification fired at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * The provider topology changed: an adapter registered or unregistered
+ * routes, or the configurable-provider directory gained or lost entries.
+ * This is a payload-free registry notification fired at each commit point
+ * (including registration disposal); consumers re-read `listProviders()`,
+ * `listModels()`, or `listConfigurableProviders()` for the new state.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'llm/adapters-updated'(): void
+```
+
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+
+<a id="llmstream--waterfall"></a>
+
+#### `llm/stream` — waterfall
+
+Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.
+
+```ts cordis-catalog
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request carries the
+ *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
+ *   (mutation throws): its content is a pure function of the session log (the
+ *   reconstructability Agent Note), so listeners read it, never rewrite it.
+ *   Hand-built calls do not carry that marker; their messages already obey
+ *   the immutable creation contract.
+ * @mode waterfall
+ */
+'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
+```
+
+Types: [GenerateOptions](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 7fd0043234..a10b696ec0 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -255,3 +255,191 @@ interface ContentBlockMap {
 ```
 
 块接口详见 [core.md § Content blocks and messages](core.md#content-blocks-and-messages)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxllm--llmservice"></a>
+
+### `ctx.llm` — `LlmService`
+
+The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+
+```ts cordis-catalog
+/**
+ * Register an adapter for the given provider routes. Throws `LlmError` with code
+ * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+ * Disposed with the fiber.
+ * @param providers - every provider route this adapter should serve.
+ * @param adapter - the adapter that streams calls for those providers.
+ * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+ */
+registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
+
+/**
+ * Describe provider routes with a registered adapter.
+ * @returns detached provider metadata in registration order.
+ */
+listProviders(): LlmProviderInfo[]
+
+/**
+ * Declare provider routes an adapter plugin can activate through
+ * configuration. Registration is all-or-nothing: an empty list, invalid
+ * entry, or a provider already declared by any registration throws
+ * `LlmError` without registering the rest. Disposed with the fiber.
+ * @param entries - every configurable provider this plugin owns.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
+ */
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+
+/**
+ * List every declared configurable provider, registered or dormant.
+ * @returns detached directory entries in declaration order.
+ */
+listConfigurableProviders(): LlmConfigurableProvider[]
+
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
+/**
+ * Resolve the retry policy captured when one provider route was registered.
+ * @param provider - registered provider route to inspect.
+ * @returns the provider-owned policy, with normal defaults already resolved.
+ */
+providerRetryPolicy(provider: string): ResolvedRetryPolicy
+
+/**
+ * Discover models advertised by one registered provider. Catalog membership
+ * is advisory and never changes routing or request validation.
+ * @param provider - registered provider route to inspect.
+ * @returns detached model metadata in adapter-preferred order.
+ */
+async listModels(provider: string): Promise<LlmModelInfo[]>
+
+/**
+ * Resolve and validate all metadata from the adapter that owns one exact
+ * route. The result is detached from adapter-owned objects; catalog
+ * membership remains advisory and does not control request routing.
+ * @param provider - registered provider route to inspect.
+ * @param model - exact model id passed to the adapter.
+ * @param signal - optional cancellation for adapter-owned asynchronous lookup.
+ * @returns exact model identity plus available context and reasoning metadata.
+ */
+async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>
+
+/**
+ * Validate a conversation call config against its exact model capability and
+ * materialize adapter-configured defaults. Unsupported explicit efforts
+ * reject before provider I/O; no clamping or aliasing is performed. This
+ * standalone query does not bind a later dispatch; use {@link prepareCall}
+ * when logging and streaming must share one adapter registration.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a detached config only when a default must be materialized.
+ */
+async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>
+
+/**
+ * Resolve one call under its current adapter registration. The returned
+ * one-shot handle keeps that registration across header logging and dispatch,
+ * so HMR cannot combine one adapter's capability result with another adapter.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a prepared config and its registration-bound stream entry point.
+ */
+async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
+
+/**
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
+ * @param options - the full request; `options.provider` selects the adapter.
+ * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+ */
+stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+```
+
+Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+
+<a id="llm-events"></a>
+
+### `llm/*` events
+
+<a id="llmadapters-updated--emit"></a>
+
+#### `llm/adapters-updated` — emit
+
+The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This is a payload-free registry notification fired at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * The provider topology changed: an adapter registered or unregistered
+ * routes, or the configurable-provider directory gained or lost entries.
+ * This is a payload-free registry notification fired at each commit point
+ * (including registration disposal); consumers re-read `listProviders()`,
+ * `listModels()`, or `listConfigurableProviders()` for the new state.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'llm/adapters-updated'(): void
+```
+
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+
+<a id="llmstream--waterfall"></a>
+
+#### `llm/stream` — waterfall
+
+Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.
+
+```ts cordis-catalog
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request carries the
+ *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
+ *   (mutation throws): its content is a pure function of the session log (the
+ *   reconstructability Agent Note), so listeners read it, never rewrite it.
+ *   Hand-built calls do not carry that marker; their messages already obey
+ *   the immutable creation contract.
+ * @mode waterfall
+ */
+'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
+```
+
+Types: [GenerateOptions](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index c63da5efdc..6f6ba3b3c3 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
-permission.md: ec8cd4a923b617934f1612c31284103266aea4ef
-permission.zh.md: 4534c33e2715e4a500344f547c7895128877f4fb
+permission.md: 60ed88a79d0e51922f4cdffafa8b547669b49f5d
+permission.zh.md: c06714fc6a111f56af680c3dea1764c90f09998d
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index ec8cd4a923..60ed88a79d 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -65,4 +65,67 @@ interface PresetOption {
 
 `set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
 
-`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxpermission--permissionservice).
+`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](#ctxpermission--permissionservice).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpermission--permissionservice"></a>
+
+### `ctx.permission` — `PermissionService`
+
+Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
+
+```ts cordis-catalog
+/**
+ * Resolve the preset matching the effective knob values. A still-matching
+ * last selection wins shared-bundle ties; otherwise the first table match
+ * wins, or {@link CUSTOM_PRESET} when no entry matches.
+ * @param events - the session's events in log order.
+ * @returns the effective preset name, or `custom` when nothing matches.
+ */
+current(events: readonly SessionEvent[]): string
+
+/**
+ * Build the whole select value for one folded knob state: every table
+ * option in declaration order, `custom` appended exactly while derived.
+ * @param state - the folded knob overrides.
+ * @returns the `permissions` projection payload.
+ */
+selectFor(state: KnobState): PermissionSelect
+
+/**
+ * Resolve a preset's knob bundle.
+ * @param name - the preset name to resolve.
+ * @returns the configured bundle.
+ * @throws when `name` is not in the table.
+ */
+resolve(name: string): PresetSpec
+
+/**
+ * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
+ * missing label falls back to the table key.
+ * @param name - a table key, or `custom`.
+ * @returns the option a client renders.
+ * @throws when `name` is neither a table key nor `custom`.
+ */
+optionOf(name: string): PresetOption
+
+/**
+ * Record a changed preset, then update each changed knob through its own
+ * setter. Selecting the effective preset again appends nothing.
+ * @param session - the session the switch belongs to.
+ * @param name - the preset to switch to; unknown names throw.
+ */
+set(session: Session, name: string): void
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index 4534c33e27..c06714fc6a 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -65,4 +65,67 @@ interface PresetOption {
 
 `set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/interaction/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
 
-`permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](../cordis-catalog/services.md#ctxpermission--permissionservice)。
+`permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](#ctxpermission--permissionservice)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpermission--permissionservice"></a>
+
+### `ctx.permission` — `PermissionService`
+
+Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
+
+```ts cordis-catalog
+/**
+ * Resolve the preset matching the effective knob values. A still-matching
+ * last selection wins shared-bundle ties; otherwise the first table match
+ * wins, or {@link CUSTOM_PRESET} when no entry matches.
+ * @param events - the session's events in log order.
+ * @returns the effective preset name, or `custom` when nothing matches.
+ */
+current(events: readonly SessionEvent[]): string
+
+/**
+ * Build the whole select value for one folded knob state: every table
+ * option in declaration order, `custom` appended exactly while derived.
+ * @param state - the folded knob overrides.
+ * @returns the `permissions` projection payload.
+ */
+selectFor(state: KnobState): PermissionSelect
+
+/**
+ * Resolve a preset's knob bundle.
+ * @param name - the preset name to resolve.
+ * @returns the configured bundle.
+ * @throws when `name` is not in the table.
+ */
+resolve(name: string): PresetSpec
+
+/**
+ * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
+ * missing label falls back to the table key.
+ * @param name - a table key, or `custom`.
+ * @returns the option a client renders.
+ * @throws when `name` is neither a table key nor `custom`.
+ */
+optionOf(name: string): PresetOption
+
+/**
+ * Record a changed preset, then update each changed knob through its own
+ * setter. Selecting the effective preset again appends nothing.
+ * @param session - the session the switch belongs to.
+ * @param name - the preset to switch to; unknown names throw.
+ */
+set(session: Session, name: string): void
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 697094b490..808abb402a 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6
-persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad
+persistence.md: 1edf3c88fbabe55058bbf94ed8f31decf47cb84a
+persistence.zh.md: dbebd9ff819c8d50cfa9748678dac09c86adde6d
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 177d596d3d..1edf3c88fb 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -204,3 +204,135 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+
+Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
+
+```ts cordis-catalog
+/**
+ * Resolve this backend's independent local artifact for a session without
+ * reading, creating, flushing, or otherwise materializing it. Backends such
+ * as SQLite that do not own one artifact per session return `undefined`.
+ * @param meta - the immutable session header whose artifact is requested.
+ * @returns the backend-specific absolute location, when one exists.
+ */
+abstract locate(meta: SessionHeader): SessionLocation | undefined
+
+/**
+ * Register a new session's metadata. A backend MAY defer the physical write
+ * until the first {@link append} (lazy materialization), in which case a
+ * created-but-never-appended session is absent from {@link list}
+ * — abandoned sessions leave nothing behind.
+ * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ */
+abstract create(meta: SessionHeader): Promise<void>
+
+/**
+ * Durably persist a batch of events. Honors the append-only and contiguous-
+ * seq contracts: the first event's `seq` MUST equal the stored next-seq
+ * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
+ * serializable `event.data` with an error naming the offending event type.
+ * @param id - the session the batch belongs to.
+ * @param events - the contiguous batch to persist, in seq order.
+ */
+abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
+
+/**
+ * Prepare the exact unpublished Session used by resume. Implementations may
+ * reuse object graphs retained by an earlier {@link inspect} after confirming
+ * their durable revision is still current; disposal releases an unpublished
+ * reservation. Revision retries require the durable log to remain unchanged
+ * for one read/check round trip; continuous external writers may delay completion.
+ * @param id - persisted session to prepare.
+ * @param signal - optional cancellation for preparation work.
+ * @returns one owned unpublished Session preparation.
+ */
+async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
+
+/**
+ * Load an immutable balanced logical view and commit any required cold
+ * recovery. A complete interrupted final turn is preserved and durably
+ * closed with missing tool errors plus any open step and turn boundaries;
+ * only a torn final record is discarded. Unknown versions and corruption in
+ * the committed prefix reject. Implementations MUST NOT crash-repair an
+ * identity still bound to a live Session: a balanced live log may return as a
+ * durable snapshot, while an open live turn rejects. Returned values may be
+ * shared with immutable live or prepared state and must not be mutated.
+ * Revision-based implementations may wait for one stable read/check round trip.
+ * @param id - the persisted session to reload.
+ * @returns the header and a log ending on a balanced `turn/end`.
+ */
+abstract load(id: SessionId): Promise<SessionInspection>
+
+/**
+ * Inspect an immutable logical session without committing recovery or
+ * publishing it. A cold complete interrupted turn receives synthetic closers
+ * in memory and a torn physical tail remains untouched. An already-live
+ * Session instead yields its current immutable snapshot, which may contain an
+ * open turn and its `session/end-seed` boundary. Coordinator-backed
+ * implementations retain the exact cold unpublished Session for bounded
+ * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
+ * already committing or reserved for resume remains exclusive, and inspection
+ * may borrow its immutable view. Callers borrow only the immutable header and
+ * log. Continuous external writers may delay revision convergence.
+ * @param id - the persisted session to inspect.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the validated header and current logical event log.
+ */
+abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
+
+/**
+ * Read the stored events from `fromSeq` onward — the read-from-seq
+ * primitive for read models that resume from a watermark (e.g. a persisted
+ * projection cache folding only the tail past its checkpoint). Unlike
+ * {@link inspect}, it is a detached physical suffix read: no preparation
+ * cache, torn-tail truncation, synthetic closers, or coordinator-state
+ * publication. Only events from the valid contiguous stored prefix are
+ * returned, so a torn fragment never reaches the caller. `fromSeq` at or
+ * beyond the stored prefix returns an empty event list (never an error).
+ * Backends whose medium can seek by seq
+ * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+ * still parse the whole artifact and skip forward — the primitive bounds
+ * what is RETURNED and refolded, not every backend's physical read.
+ * @param id - the persisted session to read.
+ * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the header and the stored events with `seq >= fromSeq`.
+ */
+abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
+/**
+ * Lightweight listing from metadata, without a full-log parse.
+ * @param signal - optional cancellation for backend listing work.
+ * @returns one header per materialized session.
+ */
+abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
+
+/**
+ * List materialized sessions with cheap per-log change tokens.
+ *
+ * Repeated observations of an unchanged log return the same revision. A
+ * successful mutating {@link load} repair changes the next listed revision.
+ * Revisions also distinguish independently backed stores so backend-local
+ * counters cannot compare equal across different persistence sources.
+ * @param signal - optional cancellation for backend snapshot-listing work.
+ * @returns one header and opaque revision per materialized session without loading full logs.
+ */
+abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+```
+
+Types: [SessionEvent](core.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 6582c0d7d0..dbebd9ff81 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -204,3 +204,135 @@ interface SessionPersistenceSnapshot {
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+
+Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
+
+```ts cordis-catalog
+/**
+ * Resolve this backend's independent local artifact for a session without
+ * reading, creating, flushing, or otherwise materializing it. Backends such
+ * as SQLite that do not own one artifact per session return `undefined`.
+ * @param meta - the immutable session header whose artifact is requested.
+ * @returns the backend-specific absolute location, when one exists.
+ */
+abstract locate(meta: SessionHeader): SessionLocation | undefined
+
+/**
+ * Register a new session's metadata. A backend MAY defer the physical write
+ * until the first {@link append} (lazy materialization), in which case a
+ * created-but-never-appended session is absent from {@link list}
+ * — abandoned sessions leave nothing behind.
+ * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ */
+abstract create(meta: SessionHeader): Promise<void>
+
+/**
+ * Durably persist a batch of events. Honors the append-only and contiguous-
+ * seq contracts: the first event's `seq` MUST equal the stored next-seq
+ * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
+ * serializable `event.data` with an error naming the offending event type.
+ * @param id - the session the batch belongs to.
+ * @param events - the contiguous batch to persist, in seq order.
+ */
+abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
+
+/**
+ * Prepare the exact unpublished Session used by resume. Implementations may
+ * reuse object graphs retained by an earlier {@link inspect} after confirming
+ * their durable revision is still current; disposal releases an unpublished
+ * reservation. Revision retries require the durable log to remain unchanged
+ * for one read/check round trip; continuous external writers may delay completion.
+ * @param id - persisted session to prepare.
+ * @param signal - optional cancellation for preparation work.
+ * @returns one owned unpublished Session preparation.
+ */
+async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
+
+/**
+ * Load an immutable balanced logical view and commit any required cold
+ * recovery. A complete interrupted final turn is preserved and durably
+ * closed with missing tool errors plus any open step and turn boundaries;
+ * only a torn final record is discarded. Unknown versions and corruption in
+ * the committed prefix reject. Implementations MUST NOT crash-repair an
+ * identity still bound to a live Session: a balanced live log may return as a
+ * durable snapshot, while an open live turn rejects. Returned values may be
+ * shared with immutable live or prepared state and must not be mutated.
+ * Revision-based implementations may wait for one stable read/check round trip.
+ * @param id - the persisted session to reload.
+ * @returns the header and a log ending on a balanced `turn/end`.
+ */
+abstract load(id: SessionId): Promise<SessionInspection>
+
+/**
+ * Inspect an immutable logical session without committing recovery or
+ * publishing it. A cold complete interrupted turn receives synthetic closers
+ * in memory and a torn physical tail remains untouched. An already-live
+ * Session instead yields its current immutable snapshot, which may contain an
+ * open turn and its `session/end-seed` boundary. Coordinator-backed
+ * implementations retain the exact cold unpublished Session for bounded
+ * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
+ * already committing or reserved for resume remains exclusive, and inspection
+ * may borrow its immutable view. Callers borrow only the immutable header and
+ * log. Continuous external writers may delay revision convergence.
+ * @param id - the persisted session to inspect.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the validated header and current logical event log.
+ */
+abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
+
+/**
+ * Read the stored events from `fromSeq` onward — the read-from-seq
+ * primitive for read models that resume from a watermark (e.g. a persisted
+ * projection cache folding only the tail past its checkpoint). Unlike
+ * {@link inspect}, it is a detached physical suffix read: no preparation
+ * cache, torn-tail truncation, synthetic closers, or coordinator-state
+ * publication. Only events from the valid contiguous stored prefix are
+ * returned, so a torn fragment never reaches the caller. `fromSeq` at or
+ * beyond the stored prefix returns an empty event list (never an error).
+ * Backends whose medium can seek by seq
+ * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+ * still parse the whole artifact and skip forward — the primitive bounds
+ * what is RETURNED and refolded, not every backend's physical read.
+ * @param id - the persisted session to read.
+ * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the header and the stored events with `seq >= fromSeq`.
+ */
+abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
+/**
+ * Lightweight listing from metadata, without a full-log parse.
+ * @param signal - optional cancellation for backend listing work.
+ * @returns one header per materialized session.
+ */
+abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
+
+/**
+ * List materialized sessions with cheap per-log change tokens.
+ *
+ * Repeated observations of an unchanged log return the same revision. A
+ * successful mutating {@link load} repair changes the next listed revision.
+ * Revisions also distinguish independently backed stores so backend-local
+ * counters cannot compare equal across different persistence sources.
+ * @param signal - optional cancellation for backend snapshot-listing work.
+ * @returns one header and opaque revision per materialized session without loading full logs.
+ */
+abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+```
+
+Types: [SessionEvent](core.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index f82002420b..efe9e376c6 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: 661a393b18f9154771c0b9358ad7f016a4fdec17
-plan.zh.md: 068b63fd9f3bf46b7962031bba154cc7fc7daafd
+plan.md: ee4b911050863765960ba46952ba923a7115e129
+plan.zh.md: 0481bdf76adf2f00fe18073fe8daa5ba172bbfe1
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index 661a393b18..ee4b911050 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -36,4 +36,51 @@ When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off
 
 ## The service
 
-`ctx.planMode` owns the logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxplanmode--planmodeservice).
+`ctx.planMode` owns the logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](#ctxplanmode--planmodeservice).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxplanmode--planmodeservice"></a>
+
+### `ctx.planMode` — `PlanModeService`
+
+`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
+
+```ts cordis-catalog
+/**
+ * Read the logged plan state and any selected state awaiting a boundary.
+ *
+ * @param agent The agent to read.
+ * @returns Current logged state plus a pending selection, when present.
+ */
+get(agent: Agent): { active: boolean; pending?: boolean }
+
+/**
+ * Select whether plan mode should be active. Between turns the change
+ * commits immediately — no request boundary would arrive until the next
+ * prompt, so a queued intent would hang (the open-turn fold is the idle
+ * signal: agent status stays `running` through post-turn checkpointing,
+ * where a boundary equally never comes). During an open turn the
+ * selection is held as pending intent for the next in-turn request
+ * boundary. Repeated selection of the current or already-pending state is
+ * a no-op.
+ *
+ * @param agent The agent to switch.
+ * @param active Whether plan mode should be active.
+ * @returns what happened: `committed` (logged now), `queued` (awaiting the
+ * next boundary), `cancelled` (an opposite pending selection was cleared;
+ * the logged state already matches), or `noop` (already in that state).
+ */
+set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 068b63fd9f..0481bdf76a 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -36,4 +36,51 @@ interface PlanModeConfig {
 
 ## 服务
 
-`ctx.planMode` 拥有已记录的计划状态、边界处的应用与叙述、`plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](../cordis-catalog/services.md#ctxplanmode--planmodeservice)。
+`ctx.planMode` 拥有已记录的计划状态、边界处的应用与叙述、`plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](#ctxplanmode--planmodeservice)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxplanmode--planmodeservice"></a>
+
+### `ctx.planMode` — `PlanModeService`
+
+`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
+
+```ts cordis-catalog
+/**
+ * Read the logged plan state and any selected state awaiting a boundary.
+ *
+ * @param agent The agent to read.
+ * @returns Current logged state plus a pending selection, when present.
+ */
+get(agent: Agent): { active: boolean; pending?: boolean }
+
+/**
+ * Select whether plan mode should be active. Between turns the change
+ * commits immediately — no request boundary would arrive until the next
+ * prompt, so a queued intent would hang (the open-turn fold is the idle
+ * signal: agent status stays `running` through post-turn checkpointing,
+ * where a boundary equally never comes). During an open turn the
+ * selection is held as pending intent for the next in-turn request
+ * boundary. Repeated selection of the current or already-pending state is
+ * a no-op.
+ *
+ * @param agent The agent to switch.
+ * @param active Whether plan mode should be active.
+ * @returns what happened: `committed` (logged now), `queued` (awaiting the
+ * next boundary), `cancelled` (an opposite pending selection was cleared;
+ * the logged state already matches), or `noop` (already in that state).
+ */
+set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/pty.i18n.yaml b/docs/subsystems/pty.i18n.yaml
index 11788e8e76..76b4500aea 100644
--- a/docs/subsystems/pty.i18n.yaml
+++ b/docs/subsystems/pty.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/pty.md
-pty.md: 97e1e662d1128ab0555e34f8284cf69d7d9d0d1a
-pty.zh.md: a57f7448274de583dbb110ba9499e15dfb4de5f9
+#   pnpm run verify-translation-pairing --write docs/subsystems/pty.md
+pty.md: 45b157c73926d85d5fc2bb037d3954da7bf75063
+pty.zh.md: 4409ef0b0504780b0b5564a34b61d4f1b2c02775
diff --git a/docs/subsystems/pty.md b/docs/subsystems/pty.md
index 97e1e662d1..45b157c739 100644
--- a/docs/subsystems/pty.md
+++ b/docs/subsystems/pty.md
@@ -89,3 +89,96 @@ interface PtySendResult {
 ## Ownership and durability
 
 `PtyService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpty--ptyservice"></a>
+
+### `ctx.pty` — `PtyService`
+
+In-process registry for replaceable PTY backends and exact-Agent sessions.
+
+```ts cordis-catalog
+/**
+ * Register one backend type for this effect scope.
+ * @param backend - provider with a non-empty unique type.
+ * @returns disposer that removes exactly this contribution.
+ */
+registerBackend(backend: PtyBackend): () => void
+
+/**
+ * List registered backend types in registration order.
+ * @returns fresh backend type names.
+ */
+listBackends(): string[]
+
+/**
+ * Create and publish one owner-scoped session after backend setup succeeds.
+ * @param owner - exact registered Agent that owns access and cleanup.
+ * @param request - backend type plus optional owner-local name and cwd.
+ * @param signal - cancellation of unpublished setup.
+ * @returns published identity, metadata, status, and MOTD.
+ */
+async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
+
+/**
+ * Test whether an exact owner has a published session or unpublished spawn.
+ * @param owner - exact live owner to inspect.
+ * @returns true across the entire spawn-to-close interval, with no publication gap.
+ */
+hasOwnerActivity(owner: Agent): boolean
+
+/**
+ * Start one exclusive interactive send.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - explicit text, submit behavior, and cancellation.
+ * @returns live operation handle for foreground await or task registration.
+ */
+startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
+
+/**
+ * Read one bounded scrollback page from an owned session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - optional newest-relative offset and line count.
+ * @returns bounded retained text and pagination metadata.
+ */
+read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
+
+/**
+ * Deliver an allowed signal through an owned backend session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param signal - allowed POSIX signal name.
+ * @returns delivered foreground process-group identity.
+ */
+signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
+
+/**
+ * Close one owned session and remove it only after quiescent backend cleanup.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param reason - diagnostic cleanup reason.
+ * @returns true for a newly closed session, false when the same close is already in flight.
+ */
+async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
+
+/**
+ * List fresh snapshots for exactly one owner.
+ * @param owner - exact owner whose sessions are visible.
+ * @returns owner-visible snapshots in publication order.
+ */
+list(owner: Agent): PtySessionSnapshot[]
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/pty.zh.md b/docs/subsystems/pty.zh.md
index a57f744827..4409ef0b05 100644
--- a/docs/subsystems/pty.zh.md
+++ b/docs/subsystems/pty.zh.md
@@ -89,3 +89,96 @@ interface PtySendResult {
 ## 归属与持久性
 
 `PtyService` 会将一项等待完成的清理附加到确切的拥有者作用域，拒绝其他拥有者的操作，并让会话在后端或工具插件重载期间保持存活。PTY 状态与原始字节仍局限在进程内。模型输入与有界返回输出通过现有 `tool/call`、`tool/result` 和任务结果路径持久保存，而不是重复记录 PTY 会话事件。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpty--ptyservice"></a>
+
+### `ctx.pty` — `PtyService`
+
+In-process registry for replaceable PTY backends and exact-Agent sessions.
+
+```ts cordis-catalog
+/**
+ * Register one backend type for this effect scope.
+ * @param backend - provider with a non-empty unique type.
+ * @returns disposer that removes exactly this contribution.
+ */
+registerBackend(backend: PtyBackend): () => void
+
+/**
+ * List registered backend types in registration order.
+ * @returns fresh backend type names.
+ */
+listBackends(): string[]
+
+/**
+ * Create and publish one owner-scoped session after backend setup succeeds.
+ * @param owner - exact registered Agent that owns access and cleanup.
+ * @param request - backend type plus optional owner-local name and cwd.
+ * @param signal - cancellation of unpublished setup.
+ * @returns published identity, metadata, status, and MOTD.
+ */
+async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
+
+/**
+ * Test whether an exact owner has a published session or unpublished spawn.
+ * @param owner - exact live owner to inspect.
+ * @returns true across the entire spawn-to-close interval, with no publication gap.
+ */
+hasOwnerActivity(owner: Agent): boolean
+
+/**
+ * Start one exclusive interactive send.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - explicit text, submit behavior, and cancellation.
+ * @returns live operation handle for foreground await or task registration.
+ */
+startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
+
+/**
+ * Read one bounded scrollback page from an owned session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - optional newest-relative offset and line count.
+ * @returns bounded retained text and pagination metadata.
+ */
+read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
+
+/**
+ * Deliver an allowed signal through an owned backend session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param signal - allowed POSIX signal name.
+ * @returns delivered foreground process-group identity.
+ */
+signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
+
+/**
+ * Close one owned session and remove it only after quiescent backend cleanup.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param reason - diagnostic cleanup reason.
+ * @returns true for a newly closed session, false when the same close is already in flight.
+ */
+async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
+
+/**
+ * List fresh snapshots for exactly one owner.
+ * @param owner - exact owner whose sessions are visible.
+ * @returns owner-visible snapshots in publication order.
+ */
+list(owner: Agent): PtySessionSnapshot[]
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index 34691ad25b..efbd158e18 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/sandbox.md
-sandbox.md: 9e5feafe046f18dad49aeaf281793f0b8e03c240
-sandbox.zh.md: a1314d1b78eb0d46ea4c8ca5aa330ee83bf89132
+#   pnpm run verify-translation-pairing --write docs/subsystems/sandbox.md
+sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
+sandbox.zh.md: f526982a782144a0bf58abcde5d883e9dc813369
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index 9e5feafe04..dd960b3021 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -146,3 +146,65 @@ The [local provider](../../packages/sandbox/sandbox-local/README.md) owns operat
 `ctx.sandbox.confine(argv, policy)` returns a `ConfinedArgv` or throws `SandboxUnavailableError` with code `SANDBOX_UNAVAILABLE` when no usable backend exists. Consumers may also classify a failure while spawning or observing the returned argv; that attribution belongs to the consumer contract. Silent unconfined passthrough is never legal for a confined policy.
 
 Provider selection, probing, caching, and backend-specific enforcement reports belong to the [local provider](../../packages/sandbox/sandbox-local/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+
+Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
+
+```ts cordis-catalog
+/**
+ * Wrap `argv` so it executes confined under `policy` on this host; the
+ * caller spawns the returned argv in place of its own.
+ * @param argv - the exact argv the caller is about to spawn (program plus
+ *   arguments), NOT a shell string — a shell-shaped consumer passes
+ *   `['bash', '-c', command]`.
+ * @param policy - the file-effect policy this execution runs under,
+ *   carried per call (see {@link SandboxPolicy}).
+ * @returns the argv to spawn instead, plus the enforcement completeness
+ *   the selected backend achieves for it.
+ */
+abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
+```
+
+Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
+
+<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
+
+### `ctx.sandboxPolicy` — `SandboxPolicyService`
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
+
+```ts cordis-catalog
+/**
+ * Resolve the complete policy for one capability call. An approved explicit
+ * mode outranks the session's last `sandbox/mode` event, which outranks the
+ * deployment default. A session cwd is its workspace-write boundary; the
+ * configured root is the fallback for agentless calls and sessions without a
+ * cwd.
+ * @param request - optional session and approved mode override.
+ * @returns the fully resolved per-call mode and absolute workspace root.
+ */
+resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
+
+/**
+ * Read the session override without applying the deployment default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged mode, or `undefined` without one.
+ */
+overrideOf(session: Session): SandboxMode | undefined
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index a1314d1b78..f526982a78 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -146,3 +146,65 @@ interface ConfinedArgv {
 `ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。消费方也可以在 spawn 或观察所返回的 argv 时对失败进行分类；该归因属于消费方契约。对于受限策略，静默的无隔离透传永远不合法。
 
 提供方选择、探测、缓存和后端专有的强制执行报告归[本地提供方](../../packages/sandbox/sandbox-local/README.md)所有。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+
+Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
+
+```ts cordis-catalog
+/**
+ * Wrap `argv` so it executes confined under `policy` on this host; the
+ * caller spawns the returned argv in place of its own.
+ * @param argv - the exact argv the caller is about to spawn (program plus
+ *   arguments), NOT a shell string — a shell-shaped consumer passes
+ *   `['bash', '-c', command]`.
+ * @param policy - the file-effect policy this execution runs under,
+ *   carried per call (see {@link SandboxPolicy}).
+ * @returns the argv to spawn instead, plus the enforcement completeness
+ *   the selected backend achieves for it.
+ */
+abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
+```
+
+Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
+
+<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
+
+### `ctx.sandboxPolicy` — `SandboxPolicyService`
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
+
+```ts cordis-catalog
+/**
+ * Resolve the complete policy for one capability call. An approved explicit
+ * mode outranks the session's last `sandbox/mode` event, which outranks the
+ * deployment default. A session cwd is its workspace-write boundary; the
+ * configured root is the fallback for agentless calls and sessions without a
+ * cwd.
+ * @param request - optional session and approved mode override.
+ * @returns the fully resolved per-call mode and absolute workspace root.
+ */
+resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
+
+/**
+ * Read the session override without applying the deployment default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged mode, or `undefined` without one.
+ */
+overrideOf(session: Session): SandboxMode | undefined
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
new file mode 100644
index 0000000000..24b1c7b234
--- /dev/null
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
+session-projection.md: 56f9fb43dddc482264aab52ceeb9b9920df148cd
+session-projection.zh.md: 4a2310fed4af6f018af07b5f2b46d3c28aa361a4
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
new file mode 100644
index 0000000000..56f9fb43dd
--- /dev/null
+++ b/docs/subsystems/session-projection.md
@@ -0,0 +1,262 @@
+# Session Projections
+
+English | [中文](session-projection.zh.md)
+
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the interface and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+
+Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
+
+## The unit
+
+`SessionProjectionMap` is the merge-extensible type table for the whole chain (host unit, wire block, client hook); values are wire-JSON whole values, and rendering belongs to the slot system, never this layer. A domain contributes one `ProjectionDefinition` per key:
+
+```ts type-equiv
+/**
+ * One domain's state-driven computation unit: three pure synchronous
+ * functions plus declarations — never an opaque getter. The framework drives
+ * `apply` on every committed session event; the domain holds no
+ * subscriptions and owns only the mathematics. All three functions MUST be
+ * synchronous (an async unit would tear the carriers' consistency cut) and
+ * `state` MUST be plain JSON (the persisted-cache precondition).
+ */
+interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {
+  /** The projection key this unit owns (its `SessionProjectionMap` entry). */
+  key: K
+  /** Validates the wire payload (`view` output) before it leaves the host. */
+  schema: ZodType<SessionProjectionMap[K]>
+  /**
+   * State for the empty log.
+   * @returns the initial state.
+   */
+  init(): S
+  /**
+   * Pure transition: previous state + one committed event → next state. A
+   * unit uninterested in an event MUST return the same state reference — an
+   * unchanged reference (`Object.is`) produces zero downstream work.
+   * @param state - the state covering all prior events.
+   * @param event - the next committed session event.
+   * @returns the next state (same reference when the event is not the unit's).
+   */
+  apply(state: S, event: SessionEvent): S
+  /**
+   * State → wire payload (the read-side projection).
+   * @param state - the current state.
+   * @returns the whole current value for this unit's key.
+   */
+  view(state: S): SessionProjectionMap[K]
+  /**
+   * Persisted-cache invalidation anchor: bump whenever the state shape or the
+   * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+   * rows from an older unit are discarded instead of being forward-applied
+   * into garbage. Non-negative integer.
+   */
+  stateVersion: number
+}
+```
+
+The whole-value event rule is load-bearing: a state-carrying log event carries the complete post-change state, never a bare delta — it keeps every transition trivially cheap and every served value self-describing (last-wins for consumers).
+
+## The snapshot and the change feed
+
+```ts type-equiv
+/**
+ * One consistent read cut over every registered unit for one session.
+ * `asOfSeq` is the shared watermark — the seq of the last event every value
+ * reflects (`-1` for an empty log, mirroring `session/subscribed.lastSeq`).
+ */
+interface ProjectionSnapshot {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered key. */
+  values: Partial<SessionProjectionMap>
+}
+```
+
+```ts type-equiv
+/**
+ * Change-feed listener: one unit's value changed for one session. `value` is
+ * the schema-validated `view` output; `seq` is the unit's watermark at
+ * emission (the seq of the event that caused the change).
+ */
+type ProjectionChangeListener = (
+  session: Session,
+  key: Extract<keyof SessionProjectionMap, string>,
+  value: unknown,
+  seq: number,
+) => void
+```
+
+`snapshot(session)` is fully synchronous — a carrier reads it in the same tick as its page slice, which is what makes `asOfSeq` one consistent cut — and every value passes its unit's schema before leaving (an accidentally-async `view` returns a Promise, which fails that boundary parse loudly). The change feed fires once per unit whose state *reference* changed, per committed event: the same-reference discipline in `apply` is the gate.
+
+## The registry: `ctx.sessionProjections`
+
+`SessionProjectionRegistry` ([signatures](#ctxsessionprojections--sessionprojectionregistry)) owns the drive: one `session/event` subscription, eager `apply` over every registered unit, and per-session per-unit watermark cells. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect whose disposer rides the calling fiber: an unloaded domain plugin's key (with its cached cells) disappears from subsequent drives and snapshots, and clients read that as capability absence; duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
+
+### `ctx.sessionProjectionCache` — `SessionProjectionCache`
+
+The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
+
+```ts cordis-catalog
+/**
+ * The zero-I/O listing read: whole values viewed straight from the stored
+ * rows (version-matching keys only), each cut carried with its watermark
+ * so a client value store can seed under its higher-seq-wins rule — as
+ * stale as the last durable checkpoint but never wrong, and never from an
+ * unrelated log (the caller's header is the identity witness). Fresher
+ * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+ * values whenever a session is actually opened.
+ * @param meta - the listed session's header (identity witness; no log read).
+ * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+ *   `undefined` when no usable row exists for this lifecycle.
+ */
+cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
+
+/**
+ * Durably checkpoint one live session NOW (both mandatory points call
+ * this; tests and carriers may too). The registry cut is snapshotted at
+ * this boundary (states are live references), then the whole record is
+ * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+ * @param session - the live session to checkpoint.
+ * @returns resolution after durability and event emission.
+ */
+async write(session: Session): Promise<void>
+
+/**
+ * Cold-read one persisted session's projections with zero full-log load:
+ * cached rows + a persistence `readFrom` tail from the registry's restore
+ * floor, refolded by the registry and written back (fail-soft) so the next
+ * cold read starts closer. A cache row invalidated by a shrunk log
+ * (crash-repair truncation) triggers one full re-read from seq 0 — the
+ * ladder's slow rung, still no crash. Rejects when the session has no
+ * persisted log (`not found` from the persistence seam).
+ * @param id - the persisted session to read.
+ * @param signal - optional cancellation for the persistence reads.
+ * @returns the snapshot cut at the stored log end.
+ */
+async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
+```
+
+Types: [Session](session.md) · [SessionHeader](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
+
+<a id="ctxsessionprojections--sessionprojectionregistry"></a>
+
+### `ctx.sessionProjections` — `SessionProjectionRegistry`
+
+`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+```ts cordis-catalog
+/**
+ * Register one domain's unit. The registration is an effect on the calling
+ * context's fiber: disposing the fiber (or calling the returned disposer)
+ * removes the key — and the unit's cached cells — from subsequent drives
+ * and snapshots.
+ * @param definition - key, boundary schema, pure unit functions, and stateVersion.
+ * @returns the exact disposer that unregisters this unit.
+ */
+register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
+
+/**
+ * Subscribe to the change feed. The registration is an effect on the
+ * calling context's fiber.
+ * @param listener - called once per unit whose state reference changed, per committed event.
+ * @returns the exact disposer that unsubscribes.
+ */
+onChanged(listener: ProjectionChangeListener): () => void
+
+/**
+ * One consistent cut over every registered unit for one session, read from
+ * the watermark cache (missing cells fold lazily over the in-memory log).
+ * Fully synchronous — every value and `asOfSeq` reflect the same log
+ * position. Each value passes its unit's schema before leaving.
+ * @param session - the session whose projection values are read.
+ * @returns the snapshot; `values` is empty when no unit is registered.
+ */
+snapshot(session: Session): ProjectionSnapshot
+
+/**
+ * State-level checkpoint of every registered unit for one session, read
+ * from the watermark cache (missing cells fold lazily over the in-memory
+ * log). This is the write side of the persisted projection cache: the
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
+ * `(sessionId, key, ver, seq, val)`
+ * rows. Every `val` is a DETACHED structured clone — never the live
+ * cell reference: the watermark cache is this registry's authoritative
+ * mutable state, and a caller reaching the live reference could corrupt
+ * every subsequent snapshot and frame through it (plain JSON by the unit
+ * contract, so the clone is total).
+ * @param session - the session whose unit states are checkpointed.
+ * @returns one row per registered key; empty when no unit is registered.
+ */
+checkpoint(session: Session): ProjectionCheckpoint
+
+/**
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
+ * at: one event BELOW the lowest usable watermark (a row is usable when
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+ * pulls the floor to `0` — that key must refold the full log). The
+ * one-below anchor is load-bearing: the tail then proves how far the
+ * stored log still extends, so {@link restore} can detect a log that
+ * shrank below a row's watermark (crash-repair truncation) instead of
+ * serving the stale row as current — an empty tail read from the anchor
+ * yields an end below every watermark and the restore rejects for a full
+ * re-read.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns the seq to hand the persistence `readFrom`, or `undefined`
+ *   when no unit is registered (no read needed — {@link restore} would
+ *   serve empty values regardless).
+ */
+restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+
+/**
+ * View a checkpoint's rows without any log read: for every registered
+ * unit whose row's `ver` matches, serve the schema-validated
+ * `view` of the stored state; mismatched or absent rows leave their key
+ * absent (a cold or listing consumer treats it as not-yet-available and a
+ * fuller read path refolds it). The zero-I/O rung of the read ladder —
+ * values are as stale as their rows, never wrong.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns whole values per key with a usable row; empty when none.
+ */
+viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
+
+/**
+ * Cold read: fold every registered unit over a stored log suffix, seeding
+ * each from its checkpoint row when usable — the one read recipe (cached
+ * state + forward tail replay + `view`) applied without a live `Session`.
+ * Call with the events returned by a persistence
+ * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+ * so a shrunk log is detected here. A row is usable iff its
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
+ * and its key refolds from `init` — which is only sound over the full
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
+ * a row's watermark).
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+ *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+ *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+ */
+restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
new file mode 100644
index 0000000000..4a2310fed4
--- /dev/null
+++ b/docs/subsystems/session-projection.zh.md
@@ -0,0 +1,262 @@
+# 会话投影
+
+[English](session-projection.md) | 中文
+
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流契约：[包（package）README](../../packages/session/session-projection/README.md)。
+
+源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
+
+## 投影单元
+
+`SessionProjectionMap` 是整条链路（host 侧单元、协议块、客户端钩子）的 merge-extensible 类型表；值是协议层 JSON 全量值，渲染归 slot 体系管，永远不归本层。领域为每个 key 贡献一个 `ProjectionDefinition`：
+
+```ts type-equiv
+/**
+ * One domain's state-driven computation unit: three pure synchronous
+ * functions plus declarations — never an opaque getter. The framework drives
+ * `apply` on every committed session event; the domain holds no
+ * subscriptions and owns only the mathematics. All three functions MUST be
+ * synchronous (an async unit would tear the carriers' consistency cut) and
+ * `state` MUST be plain JSON (the persisted-cache precondition).
+ */
+interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {
+  /** The projection key this unit owns (its `SessionProjectionMap` entry). */
+  key: K
+  /** Validates the wire payload (`view` output) before it leaves the host. */
+  schema: ZodType<SessionProjectionMap[K]>
+  /**
+   * State for the empty log.
+   * @returns the initial state.
+   */
+  init(): S
+  /**
+   * Pure transition: previous state + one committed event → next state. A
+   * unit uninterested in an event MUST return the same state reference — an
+   * unchanged reference (`Object.is`) produces zero downstream work.
+   * @param state - the state covering all prior events.
+   * @param event - the next committed session event.
+   * @returns the next state (same reference when the event is not the unit's).
+   */
+  apply(state: S, event: SessionEvent): S
+  /**
+   * State → wire payload (the read-side projection).
+   * @param state - the current state.
+   * @returns the whole current value for this unit's key.
+   */
+  view(state: S): SessionProjectionMap[K]
+  /**
+   * Persisted-cache invalidation anchor: bump whenever the state shape or the
+   * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+   * rows from an older unit are discarded instead of being forward-applied
+   * into garbage. Non-negative integer.
+   */
+  stateVersion: number
+}
+```
+
+全量值事件规则是承重结构：携带状态的日志事件携带的是变更后的完整状态，绝不是裸增量——这让每次状态转移始终足够廉价，也让每个被供给的值自描述（对消费方即 last-wins）。
+
+## 快照与变更流
+
+```ts type-equiv
+/**
+ * One consistent read cut over every registered unit for one session.
+ * `asOfSeq` is the shared watermark — the seq of the last event every value
+ * reflects (`-1` for an empty log, mirroring `session/subscribed.lastSeq`).
+ */
+interface ProjectionSnapshot {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered key. */
+  values: Partial<SessionProjectionMap>
+}
+```
+
+```ts type-equiv
+/**
+ * Change-feed listener: one unit's value changed for one session. `value` is
+ * the schema-validated `view` output; `seq` is the unit's watermark at
+ * emission (the seq of the event that caused the change).
+ */
+type ProjectionChangeListener = (
+  session: Session,
+  key: Extract<keyof SessionProjectionMap, string>,
+  value: unknown,
+  seq: number,
+) => void
+```
+
+`snapshot(session)` 是完全同步的：载体在切出页面切片的同一 tick 内读取它，`asOfSeq` 之所以是一个一致切面正系于此；且每个值在离开前都要经过其单元的 schema 校验（误写成异步的 `view` 会返回 Promise，让这道边界解析当场大声失败）。变更流对每个已提交事件、每个状态*引用*发生变化的单元各触发一次：`apply` 的同引用纪律就是那道闸门。
+
+## 注册表：`ctx.sessionProjections`
+
+`SessionProjectionRegistry`（[签名](#ctxsessionprojections--sessionprojectionregistry)）拥有驱动权：一份 `session/event` 订阅、对每个已注册单元的正向 `apply`，以及每会话每单元的水位线（watermark）cell。cell 惰性构建：在事件流过之后才注册的单元，或比注册表更早的会话，都在首次触达（事件或读取）时从 `init` 出发在内存日志上折叠。注册是一个 effect，其 disposer 随调用方 fiber 走：领域插件卸载后，其 key（连同缓存的 cell）从后续驱动与快照中消失，客户端将其读作能力缺失；key 重复直接 throw。领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
+
+### `ctx.sessionProjectionCache` — `SessionProjectionCache`
+
+The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
+
+```ts cordis-catalog
+/**
+ * The zero-I/O listing read: whole values viewed straight from the stored
+ * rows (version-matching keys only), each cut carried with its watermark
+ * so a client value store can seed under its higher-seq-wins rule — as
+ * stale as the last durable checkpoint but never wrong, and never from an
+ * unrelated log (the caller's header is the identity witness). Fresher
+ * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+ * values whenever a session is actually opened.
+ * @param meta - the listed session's header (identity witness; no log read).
+ * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+ *   `undefined` when no usable row exists for this lifecycle.
+ */
+cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
+
+/**
+ * Durably checkpoint one live session NOW (both mandatory points call
+ * this; tests and carriers may too). The registry cut is snapshotted at
+ * this boundary (states are live references), then the whole record is
+ * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+ * @param session - the live session to checkpoint.
+ * @returns resolution after durability and event emission.
+ */
+async write(session: Session): Promise<void>
+
+/**
+ * Cold-read one persisted session's projections with zero full-log load:
+ * cached rows + a persistence `readFrom` tail from the registry's restore
+ * floor, refolded by the registry and written back (fail-soft) so the next
+ * cold read starts closer. A cache row invalidated by a shrunk log
+ * (crash-repair truncation) triggers one full re-read from seq 0 — the
+ * ladder's slow rung, still no crash. Rejects when the session has no
+ * persisted log (`not found` from the persistence seam).
+ * @param id - the persisted session to read.
+ * @param signal - optional cancellation for the persistence reads.
+ * @returns the snapshot cut at the stored log end.
+ */
+async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
+```
+
+Types: [Session](session.md) · [SessionHeader](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
+
+<a id="ctxsessionprojections--sessionprojectionregistry"></a>
+
+### `ctx.sessionProjections` — `SessionProjectionRegistry`
+
+`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+```ts cordis-catalog
+/**
+ * Register one domain's unit. The registration is an effect on the calling
+ * context's fiber: disposing the fiber (or calling the returned disposer)
+ * removes the key — and the unit's cached cells — from subsequent drives
+ * and snapshots.
+ * @param definition - key, boundary schema, pure unit functions, and stateVersion.
+ * @returns the exact disposer that unregisters this unit.
+ */
+register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
+
+/**
+ * Subscribe to the change feed. The registration is an effect on the
+ * calling context's fiber.
+ * @param listener - called once per unit whose state reference changed, per committed event.
+ * @returns the exact disposer that unsubscribes.
+ */
+onChanged(listener: ProjectionChangeListener): () => void
+
+/**
+ * One consistent cut over every registered unit for one session, read from
+ * the watermark cache (missing cells fold lazily over the in-memory log).
+ * Fully synchronous — every value and `asOfSeq` reflect the same log
+ * position. Each value passes its unit's schema before leaving.
+ * @param session - the session whose projection values are read.
+ * @returns the snapshot; `values` is empty when no unit is registered.
+ */
+snapshot(session: Session): ProjectionSnapshot
+
+/**
+ * State-level checkpoint of every registered unit for one session, read
+ * from the watermark cache (missing cells fold lazily over the in-memory
+ * log). This is the write side of the persisted projection cache: the
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
+ * `(sessionId, key, ver, seq, val)`
+ * rows. Every `val` is a DETACHED structured clone — never the live
+ * cell reference: the watermark cache is this registry's authoritative
+ * mutable state, and a caller reaching the live reference could corrupt
+ * every subsequent snapshot and frame through it (plain JSON by the unit
+ * contract, so the clone is total).
+ * @param session - the session whose unit states are checkpointed.
+ * @returns one row per registered key; empty when no unit is registered.
+ */
+checkpoint(session: Session): ProjectionCheckpoint
+
+/**
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
+ * at: one event BELOW the lowest usable watermark (a row is usable when
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+ * pulls the floor to `0` — that key must refold the full log). The
+ * one-below anchor is load-bearing: the tail then proves how far the
+ * stored log still extends, so {@link restore} can detect a log that
+ * shrank below a row's watermark (crash-repair truncation) instead of
+ * serving the stale row as current — an empty tail read from the anchor
+ * yields an end below every watermark and the restore rejects for a full
+ * re-read.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns the seq to hand the persistence `readFrom`, or `undefined`
+ *   when no unit is registered (no read needed — {@link restore} would
+ *   serve empty values regardless).
+ */
+restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+
+/**
+ * View a checkpoint's rows without any log read: for every registered
+ * unit whose row's `ver` matches, serve the schema-validated
+ * `view` of the stored state; mismatched or absent rows leave their key
+ * absent (a cold or listing consumer treats it as not-yet-available and a
+ * fuller read path refolds it). The zero-I/O rung of the read ladder —
+ * values are as stale as their rows, never wrong.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns whole values per key with a usable row; empty when none.
+ */
+viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
+
+/**
+ * Cold read: fold every registered unit over a stored log suffix, seeding
+ * each from its checkpoint row when usable — the one read recipe (cached
+ * state + forward tail replay + `view`) applied without a live `Session`.
+ * Call with the events returned by a persistence
+ * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+ * so a shrunk log is detected here. A row is usable iff its
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
+ * and its key refolds from `init` — which is only sound over the full
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
+ * a row's watermark).
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+ *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+ *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+ */
+restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index eca4715ba9..728a6cf8db 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/session-query.md
-session-query.md: e7514dd6c3bc20a07395663bff40ce65e1363b78
-session-query.zh.md: 4c3dd4d435dbd8a20fbd4db5da1a7d649c2e6d0b
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-query.md
+session-query.md: 54ae1eaf34a17d4979a621e4fc310780b425364e
+session-query.zh.md: b770514757c30aa5d87b25e5d280b1ce6710cd9c
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index e7514dd6c3..54ae1eaf34 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -354,3 +354,141 @@ type SessionQueryErrorCode =
   | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+
+Unified live-preferred session query service.
+
+Exact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.
+
+```ts cordis-catalog
+/**
+ * Search the live-preferred logical corpus and group by session.
+ * @param request - query text, metadata filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns session hits ranked by their strongest matching event.
+ */
+abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>
+
+/**
+ * Search events within one live-preferred logical session.
+ * @param request - target session, query text, filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns matching event hits and their target header from one indexed generation.
+ */
+abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>
+
+/**
+ * List the complete logical corpus using live-preferred records.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns deterministic newest-first cloned session records.
+ */
+listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
+
+/**
+ * Read and replay-validate one complete logical session log without making it live.
+ * @param sessionId - live or persisted session id to read.
+ * @returns cloned header and complete raw event log from one observation.
+ * @throws when persistence, header compatibility, or replay validation fails.
+ */
+async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
+
+/**
+ * Filter the complete logical corpus with provider-independent predicates.
+ * @param filters - ANDed session metadata and availability clauses.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns matching cloned records in deterministic newest-first order.
+ */
+async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>
+
+/**
+ * Fold the latest log-backed title from one live-preferred logical session.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns latest title snapshot, or `undefined` when the log has no title event.
+ */
+async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Fold the latest title and return its source header from one corpus observation.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns cloned source header and optional latest title snapshot.
+ */
+async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
+
+/**
+ * Fold titles for unique sessions from one cancellable corpus observation.
+ *
+ * Results preserve first-occurrence input order. Operational failures stay
+ * isolated per session, while cancellation rejects the complete operation.
+ * @param sessionIds - live or persisted session ids to observe.
+ * @param signal - optional cancellation shared by all source reads.
+ * @returns one fulfilled or rejected result per unique requested id.
+ */
+async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>
+
+/**
+ * List lightweight raw-log event records for one logical session.
+ * @param sessionId - live-preferred session id to read.
+ * @returns event records in ascending seq order.
+ */
+async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
+
+/**
+ * Scan first-party semantic event documents with provider-independent filters.
+ * @param sessionId - live-preferred session id to scan.
+ * @param filters - ANDed metadata and literal-text predicates.
+ * @returns matching semantic documents in ascending seq order.
+ */
+async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>
+
+/**
+ * Read one session's complete current model surface from one corpus observation.
+ * @param sessionId - live-preferred session id to read.
+ * @returns cloned header, current surface, and raw-log capture boundary.
+ * @throws when source resolution fails or the session surface is invalid.
+ */
+async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
+
+/**
+ * Trace known ancestry and descendants from one corpus observation.
+ * @param sessionId - logical session id to trace.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns a complete lineage or an explicit unresolved parent boundary.
+ * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
+ */
+async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
+
+/**
+ * Trace one event's direct positional and provenance relationships.
+ * @param request - target session id and event seq.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns source header, direct links, and the target's positional replacement chain.
+ * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ */
+async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
+
+/**
+ * Read one full event plus a bounded raw-log context window.
+ * @param request - target session/seq and context sizes.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns cloned target and neighboring events.
+ */
+async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
+```
+
+Types: [SessionId](core.md) · [SessionTitleSnapshot](session-title.md)
+
+Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 4c3dd4d435..b770514757 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -354,3 +354,141 @@ type SessionQueryErrorCode =
   | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+
+Unified live-preferred session query service.
+
+Exact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.
+
+```ts cordis-catalog
+/**
+ * Search the live-preferred logical corpus and group by session.
+ * @param request - query text, metadata filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns session hits ranked by their strongest matching event.
+ */
+abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>
+
+/**
+ * Search events within one live-preferred logical session.
+ * @param request - target session, query text, filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns matching event hits and their target header from one indexed generation.
+ */
+abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>
+
+/**
+ * List the complete logical corpus using live-preferred records.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns deterministic newest-first cloned session records.
+ */
+listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
+
+/**
+ * Read and replay-validate one complete logical session log without making it live.
+ * @param sessionId - live or persisted session id to read.
+ * @returns cloned header and complete raw event log from one observation.
+ * @throws when persistence, header compatibility, or replay validation fails.
+ */
+async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
+
+/**
+ * Filter the complete logical corpus with provider-independent predicates.
+ * @param filters - ANDed session metadata and availability clauses.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns matching cloned records in deterministic newest-first order.
+ */
+async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>
+
+/**
+ * Fold the latest log-backed title from one live-preferred logical session.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns latest title snapshot, or `undefined` when the log has no title event.
+ */
+async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Fold the latest title and return its source header from one corpus observation.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns cloned source header and optional latest title snapshot.
+ */
+async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
+
+/**
+ * Fold titles for unique sessions from one cancellable corpus observation.
+ *
+ * Results preserve first-occurrence input order. Operational failures stay
+ * isolated per session, while cancellation rejects the complete operation.
+ * @param sessionIds - live or persisted session ids to observe.
+ * @param signal - optional cancellation shared by all source reads.
+ * @returns one fulfilled or rejected result per unique requested id.
+ */
+async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>
+
+/**
+ * List lightweight raw-log event records for one logical session.
+ * @param sessionId - live-preferred session id to read.
+ * @returns event records in ascending seq order.
+ */
+async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
+
+/**
+ * Scan first-party semantic event documents with provider-independent filters.
+ * @param sessionId - live-preferred session id to scan.
+ * @param filters - ANDed metadata and literal-text predicates.
+ * @returns matching semantic documents in ascending seq order.
+ */
+async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>
+
+/**
+ * Read one session's complete current model surface from one corpus observation.
+ * @param sessionId - live-preferred session id to read.
+ * @returns cloned header, current surface, and raw-log capture boundary.
+ * @throws when source resolution fails or the session surface is invalid.
+ */
+async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
+
+/**
+ * Trace known ancestry and descendants from one corpus observation.
+ * @param sessionId - logical session id to trace.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns a complete lineage or an explicit unresolved parent boundary.
+ * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
+ */
+async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
+
+/**
+ * Trace one event's direct positional and provenance relationships.
+ * @param request - target session id and event seq.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns source header, direct links, and the target's positional replacement chain.
+ * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ */
+async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
+
+/**
+ * Read one full event plus a bounded raw-log context window.
+ * @param request - target session/seq and context sizes.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns cloned target and neighboring events.
+ */
+async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
+```
+
+Types: [SessionId](core.md) · [SessionTitleSnapshot](session-title.md)
+
+Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index f119c67913..980c1a1a2d 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.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 docs/subsystems/session-reference.md
-session-reference.md: 5375677f6a1748909743ca76d5191cb9e736a40a
-session-reference.zh.md: 3ff4a1719926bda0a9111482a7778a8c94553370
+session-reference.md: 60e29c56ea372e100009b94caedea5327308432a
+session-reference.zh.md: 3ae9264abc15848646e5397dfcbeff764c038918
diff --git a/docs/subsystems/session-reference.md b/docs/subsystems/session-reference.md
index 5375677f6a..60e29c56ea 100644
--- a/docs/subsystems/session-reference.md
+++ b/docs/subsystems/session-reference.md
@@ -65,3 +65,44 @@ type SessionReferenceErrorCode =
   | 'SESSION_REFERENCE_BUDGET_EXCEEDED'
   | 'SESSION_REFERENCE_CANCELLED'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionreferences--sessionreferenceservice"></a>
+
+### `ctx.sessionReferences` — `SessionReferenceService`
+
+Exact-read consumer that prepares immutable cross-session message context.
+
+```ts cordis-catalog
+/**
+ * List reference candidates, ranked by working-directory affinity.
+ * @param agent - target agent; self is excluded and its cwd drives ranking.
+ * @param query - optional case-insensitive session-id/cwd/title substring.
+ * @param limit - optional positive result cap.
+ * @param signal - optional cancellation boundary for host autocomplete teardown.
+ * @returns candidates labeled by latest title or, when absent, session id.
+ */
+async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
+
+/**
+ * Snapshot all references before enqueue and return one aggregated durable context.
+ * @param agent - target agent; references to it are rejected.
+ * @param content - already host-normalized readable message content.
+ * @param references - structured source sessions in mention order.
+ * @param signal - optional cancellation boundary for host request teardown.
+ * @returns detached content and optional referenced-session context.
+ */
+async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md)
+
+Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 3ff4a17199..3ae9264abc 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -65,3 +65,44 @@ type SessionReferenceErrorCode =
   | 'SESSION_REFERENCE_BUDGET_EXCEEDED'
   | 'SESSION_REFERENCE_CANCELLED'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionreferences--sessionreferenceservice"></a>
+
+### `ctx.sessionReferences` — `SessionReferenceService`
+
+Exact-read consumer that prepares immutable cross-session message context.
+
+```ts cordis-catalog
+/**
+ * List reference candidates, ranked by working-directory affinity.
+ * @param agent - target agent; self is excluded and its cwd drives ranking.
+ * @param query - optional case-insensitive session-id/cwd/title substring.
+ * @param limit - optional positive result cap.
+ * @param signal - optional cancellation boundary for host autocomplete teardown.
+ * @returns candidates labeled by latest title or, when absent, session id.
+ */
+async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
+
+/**
+ * Snapshot all references before enqueue and return one aggregated durable context.
+ * @param agent - target agent; references to it are rejected.
+ * @param content - already host-normalized readable message content.
+ * @param references - structured source sessions in mention order.
+ * @param signal - optional cancellation boundary for host request teardown.
+ * @returns detached content and optional referenced-session context.
+ */
+async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md)
+
+Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
index c85d4dfac1..8b58415234 100644
--- a/docs/subsystems/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.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 docs/subsystems/session-title.md
-session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e
-session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e
+session-title.md: 3a2df284f2af14def284e502f4e37daaf4d7a262
+session-title.zh.md: 3a74baa9005459b35b658df95bdd7b57256b3e2e
diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md
index 7bced67f07..3a2df284f2 100644
--- a/docs/subsystems/session-title.md
+++ b/docs/subsystems/session-title.md
@@ -144,3 +144,61 @@ interface SessionTitleProvider {
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessiontitle--sessiontitleservice"></a>
+
+### `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Accept an explicit user title. Appends a `session/title` event with the
+ * `user` source, which pins the title: in-flight automatic generation is
+ * superseded and later user messages schedule none (an explicit
+ * {@link SessionTitleService.refresh} remains the deliberate unpin).
+ * @param session - exact live session to rename.
+ * @param title - raw user input; normalized before acceptance.
+ * @returns the accepted title snapshot.
+ * @throws {SessionTitleInvalidError} when the title normalizes to empty.
+ * @throws {Error} when the session is not live or the service is disposed.
+ */
+rename(session: Session, title: string): SessionTitleSnapshot
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work before another provider may register.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md
index e8e501d3aa..3a74baa900 100644
--- a/docs/subsystems/session-title.zh.md
+++ b/docs/subsystems/session-title.zh.md
@@ -144,3 +144,61 @@ interface SessionTitleProvider {
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessiontitle--sessiontitleservice"></a>
+
+### `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Accept an explicit user title. Appends a `session/title` event with the
+ * `user` source, which pins the title: in-flight automatic generation is
+ * superseded and later user messages schedule none (an explicit
+ * {@link SessionTitleService.refresh} remains the deliberate unpin).
+ * @param session - exact live session to rename.
+ * @param title - raw user input; normalized before acceptance.
+ * @returns the accepted title snapshot.
+ * @throws {SessionTitleInvalidError} when the title normalizes to empty.
+ * @throws {Error} when the session is not live or the service is disposed.
+ */
+rename(session: Session, title: string): SessionTitleSnapshot
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work before another provider may register.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index dd7135e8d3..a7e81056e5 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 5d54b03df8ec3345e8bf04702f242e3aacf8ec39
-session.zh.md: 5a867cfe302bf02994bfe5a5a704bed55222e8ea
+session.md: 28b3f959b47a24373860c2334f9273286d072c95
+session.zh.md: 5870265f55892231700b65ac6ed69d827a0ab1ec
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 5d54b03df8..28b3f959b4 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -343,7 +343,7 @@ interface SurfaceFoldResult {
 
 ## `Session` public API
 
-The body-stripped declaration keeps the plain class's detached factory, state accessors, append boundary, and history projections synchronized with source. Store operations remain in the generated [`ctx.sessions` service catalog](../cordis-catalog/services.md#ctxsessions--sessionstore).
+The body-stripped declaration keeps the plain class's detached factory, state accessors, append boundary, and history projections synchronized with source. Store operations remain in the generated [`ctx.sessions` section](#ctxsessions--sessionstore).
 
 ```ts public-api
 /**
@@ -586,3 +586,247 @@ The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepse
 What a persistence backend relies on: the durable log persists every event losslessly, **including** `assistant/chunk` — `seq` must stay contiguous, so chunks cannot be filtered out of the canonical log. A backend may choose its own storage encoding for an event batch as long as `load` returns the exact appended events (the JSONL backend's default packed chunk rows are such an encoding — see [persistence.md](persistence.md)). All `event.data` must be JSON-serializable; `Session.append` enforces this at the source (throwing on non-serializable data), so a bad event never enters the log and `session.events` always equals what a backend can persist. Adding an event type that carries non-serializable data, corrupts core execution nesting, or violates its owner's declared relation is a breaking change to the on-disk format.
 
 The backends that consume this contract are on [persistence.md](persistence.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessions--sessionstore"></a>
+
+### `ctx.sessions` — `SessionStore`
+
+In-memory session store (`ctx.sessions`).
+
+Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+
+```ts cordis-catalog
+/**
+ * Create a session owned by the calling fiber: disposing that fiber stops
+ * event notification and removes the session from the store. `options.seed`
+ * populates the session with a copy of those events (replay/fork);
+ * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
+ * and parent lineage, and delegation depth) as the immutable
+ * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
+ *
+ * For an agent whose session must be torn down IN ORDER with its loop (so the
+ * loop's final events are published before the store attachment ends), do NOT use this
+ * — fold the session lifecycle into the agent's own effect via
+ * {@link prepare} + {@link enter} + {@link announce} (see
+ * `dsh-agent-loop`'s creation transaction).
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header.
+ * @returns the live session, already entered and announced.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path (storage backends key directories off it).
+ */
+create(id?: SessionId, options?: CreateSessionOptions): Session
+
+/**
+ * Build a session WITHOUT entering it into the store — validate the id/cwd and
+ * construct the {@link Session} (with its immutable {@link SessionHeader}).
+ * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
+ * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
+ * effect so a fiber unload tears the session + agent down as a single ORDERED
+ * chain rather than as racing sibling effects — which would remove the publication hooks
+ * before the driver's closing events commit, dropping them.
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header. With
+ *   `seedSource: 'persistence'`, metadata and events must be fresh detached
+ *   graphs whose ownership transfers to this call: they are validated and
+ *   frozen in place through {@link Session.fromRestore}, so the caller must
+ *   retain no mutable aliases.
+ * @returns the constructed session, NOT yet in the store.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path.
+ */
+prepare(id?: SessionId, options?: PrepareSessionOptions): Session
+
+/**
+ * Enter a {@link prepare}d session into the store: install the module-private
+ * append publication hooks and add it to the store. Returns the DETACH
+ * disposer (hooks + store removal). Does NOT emit `session/created` —
+ * the caller yields this disposer inside its effect and THEN calls
+ * {@link announce}, so a throwing `session/created` listener rolls the attach
+ * back instead of leaking it.
+ *
+ * Re-checks the id for a duplicate: `prepare` and `enter` are public
+ * cross-package primitives and a caller may interleave arbitrary work (or
+ * another create) between them, so a stale prepared session must NOT overwrite
+ * a live store entry of the same id — its detach disposer would later delete
+ * the REAL session. The {@link create} convenience and the agent factory call
+ * the two back-to-back so they never trip this, but the public seam cannot
+ * assume that.
+ *
+ * @param session - a {@link prepare}d session not yet in the store.
+ * @returns the detach disposer (publication hooks + store removal). When called from
+ *   a synchronous `session/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ * @throws if a session with this id is already in the store.
+ */
+enter(session: Session): () => void
+
+/** Emit `session/created` exactly once for an {@link enter}ed session (with
+ * the carrier {@link enter} captured). Separate from {@link enter} so the
+ * caller can yield the detach disposer first (rollback safety — see
+ * {@link enter}).
+ * @param session - the entered session to announce to listeners.
+ * @throws if the session is not live or its announcement already began,
+ *   including a reentrant call from a creation listener. */
+announce(session: Session): void
+
+/**
+ * Dispatch the awaited `session/flush` durability checkpoint for `session`,
+ * with the carrier captured at {@link enter}. THE flush entry point: the
+ * store owns the carrier, so callers (the checkpoint policy's per-request
+ * barrier, goal-session's idle checkpoint, teardown drains, and consumers
+ * that flush themselves before reading storage) must come through here
+ * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
+ * one spelling, and the scoped-dispatch invariant can pin it.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @returns whether at least one durability listener participated, after every
+ *   listener has settled successfully.
+ * @throws the first registered listener failure after every listener settles.
+ */
+async flush(session: Session): Promise<boolean>
+
+/**
+ * Look up a live session.
+ * @param id - the session id to look up.
+ * @returns the session, or undefined when no live session has that id.
+ */
+get(id: SessionId): Session | undefined
+
+/**
+ * All live sessions, in creation order.
+ * @returns a fresh array; mutating it does not affect the store.
+ */
+list(): Session[]
+
+/**
+ * Create a live child session from a stable prefix of a live source.
+ * `boundary` is an inclusive source event seq; omitted means the source's
+ * current last event. The selected slice may end with a between-turn event
+ * but must not end inside an open turn.
+ *
+ * @param source - Live source session object or id.
+ * @param boundary - Inclusive source event seq to fork through; omitted means
+ *   the source's current last event, and omitted on an empty source forks an
+ *   empty child.
+ * @param childSessionId - Optional child session id; omitted delegates to
+ *   `SessionStore`'s id policy.
+ * @returns The created live child session.
+ */
+fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+```
+
+Types: [CreateSessionOptions](persistence.md) · [PrepareSessionOptions](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
+
+<a id="session-events"></a>
+
+### `session/*` events
+
+<a id="sessioncreated--emit"></a>
+
+#### `session/created` — emit
+
+Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/created'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
+
+<a id="sessiondisposed--emit"></a>
+
+#### `session/disposed` — emit
+
+Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+
+```ts cordis-catalog
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/disposed'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
+
+<a id="sessionevent--emit"></a>
+
+#### `session/event` — emit
+
+Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
+```
+
+Types: [Scoped](scope.md) · [SessionEvent](core.md)
+
+Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
+
+<a id="sessionflush--parallel"></a>
+
+#### `session/flush` — parallel
+
+Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+
+```ts cordis-catalog
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
+'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 5a867cfe30..5870265f55 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -345,7 +345,7 @@ interface SurfaceFoldResult {
 
 ## `Session` 公共 API
 
-去除方法体的声明与源码中的普通类保持同步，覆盖其脱离态工厂、状态访问器、追加边界和历史投影。存储操作仍由生成的 [`ctx.sessions` 服务目录](../cordis-catalog/services.md#ctxsessions--sessionstore)记录。
+去除方法体的声明与源码中的普通类保持同步，覆盖其脱离态工厂、状态访问器、追加边界和历史投影。存储操作仍由生成的 [`ctx.sessions` 小节](#ctxsessions--sessionstore)记录。
 
 ```ts public-api
 /**
@@ -590,3 +590,247 @@ interface TurnEndReasonMap {
 持久化后端依赖的契约如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.events` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
 
 消费此契约的后端见 [persistence.md](persistence.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessions--sessionstore"></a>
+
+### `ctx.sessions` — `SessionStore`
+
+In-memory session store (`ctx.sessions`).
+
+Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+
+```ts cordis-catalog
+/**
+ * Create a session owned by the calling fiber: disposing that fiber stops
+ * event notification and removes the session from the store. `options.seed`
+ * populates the session with a copy of those events (replay/fork);
+ * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
+ * and parent lineage, and delegation depth) as the immutable
+ * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
+ *
+ * For an agent whose session must be torn down IN ORDER with its loop (so the
+ * loop's final events are published before the store attachment ends), do NOT use this
+ * — fold the session lifecycle into the agent's own effect via
+ * {@link prepare} + {@link enter} + {@link announce} (see
+ * `dsh-agent-loop`'s creation transaction).
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header.
+ * @returns the live session, already entered and announced.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path (storage backends key directories off it).
+ */
+create(id?: SessionId, options?: CreateSessionOptions): Session
+
+/**
+ * Build a session WITHOUT entering it into the store — validate the id/cwd and
+ * construct the {@link Session} (with its immutable {@link SessionHeader}).
+ * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
+ * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
+ * effect so a fiber unload tears the session + agent down as a single ORDERED
+ * chain rather than as racing sibling effects — which would remove the publication hooks
+ * before the driver's closing events commit, dropping them.
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header. With
+ *   `seedSource: 'persistence'`, metadata and events must be fresh detached
+ *   graphs whose ownership transfers to this call: they are validated and
+ *   frozen in place through {@link Session.fromRestore}, so the caller must
+ *   retain no mutable aliases.
+ * @returns the constructed session, NOT yet in the store.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path.
+ */
+prepare(id?: SessionId, options?: PrepareSessionOptions): Session
+
+/**
+ * Enter a {@link prepare}d session into the store: install the module-private
+ * append publication hooks and add it to the store. Returns the DETACH
+ * disposer (hooks + store removal). Does NOT emit `session/created` —
+ * the caller yields this disposer inside its effect and THEN calls
+ * {@link announce}, so a throwing `session/created` listener rolls the attach
+ * back instead of leaking it.
+ *
+ * Re-checks the id for a duplicate: `prepare` and `enter` are public
+ * cross-package primitives and a caller may interleave arbitrary work (or
+ * another create) between them, so a stale prepared session must NOT overwrite
+ * a live store entry of the same id — its detach disposer would later delete
+ * the REAL session. The {@link create} convenience and the agent factory call
+ * the two back-to-back so they never trip this, but the public seam cannot
+ * assume that.
+ *
+ * @param session - a {@link prepare}d session not yet in the store.
+ * @returns the detach disposer (publication hooks + store removal). When called from
+ *   a synchronous `session/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ * @throws if a session with this id is already in the store.
+ */
+enter(session: Session): () => void
+
+/** Emit `session/created` exactly once for an {@link enter}ed session (with
+ * the carrier {@link enter} captured). Separate from {@link enter} so the
+ * caller can yield the detach disposer first (rollback safety — see
+ * {@link enter}).
+ * @param session - the entered session to announce to listeners.
+ * @throws if the session is not live or its announcement already began,
+ *   including a reentrant call from a creation listener. */
+announce(session: Session): void
+
+/**
+ * Dispatch the awaited `session/flush` durability checkpoint for `session`,
+ * with the carrier captured at {@link enter}. THE flush entry point: the
+ * store owns the carrier, so callers (the checkpoint policy's per-request
+ * barrier, goal-session's idle checkpoint, teardown drains, and consumers
+ * that flush themselves before reading storage) must come through here
+ * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
+ * one spelling, and the scoped-dispatch invariant can pin it.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @returns whether at least one durability listener participated, after every
+ *   listener has settled successfully.
+ * @throws the first registered listener failure after every listener settles.
+ */
+async flush(session: Session): Promise<boolean>
+
+/**
+ * Look up a live session.
+ * @param id - the session id to look up.
+ * @returns the session, or undefined when no live session has that id.
+ */
+get(id: SessionId): Session | undefined
+
+/**
+ * All live sessions, in creation order.
+ * @returns a fresh array; mutating it does not affect the store.
+ */
+list(): Session[]
+
+/**
+ * Create a live child session from a stable prefix of a live source.
+ * `boundary` is an inclusive source event seq; omitted means the source's
+ * current last event. The selected slice may end with a between-turn event
+ * but must not end inside an open turn.
+ *
+ * @param source - Live source session object or id.
+ * @param boundary - Inclusive source event seq to fork through; omitted means
+ *   the source's current last event, and omitted on an empty source forks an
+ *   empty child.
+ * @param childSessionId - Optional child session id; omitted delegates to
+ *   `SessionStore`'s id policy.
+ * @returns The created live child session.
+ */
+fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+```
+
+Types: [CreateSessionOptions](persistence.md) · [PrepareSessionOptions](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
+
+<a id="session-events"></a>
+
+### `session/*` events
+
+<a id="sessioncreated--emit"></a>
+
+#### `session/created` — emit
+
+Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/created'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
+
+<a id="sessiondisposed--emit"></a>
+
+#### `session/disposed` — emit
+
+Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+
+```ts cordis-catalog
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/disposed'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
+
+<a id="sessionevent--emit"></a>
+
+#### `session/event` — emit
+
+Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
+```
+
+Types: [Scoped](scope.md) · [SessionEvent](core.md)
+
+Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
+
+<a id="sessionflush--parallel"></a>
+
+#### `session/flush` — parallel
+
+Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+
+```ts cordis-catalog
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
+'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index f4518f4414..5c40419366 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/subsystems/settings.md
-settings.md: bd01c1d28407af9cab26f624a054a010e25a3ddd
-settings.zh.md: 1cb7f8b507f29f2b6876fd48b4c37284df235e53
+settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
+settings.zh.md: f6d662ebaf35eeb9d046353ea1087b0eb86e7068
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index bd01c1d284..9256bf9436 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -160,3 +160,151 @@ Every committed change — an in-process write or an externally observed provide
 /** Origin of one committed settings change. */
 type SettingsUpdateSource = 'update' | 'provider'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsettings--settings-abstract-seam"></a>
+
+### `ctx.settings` — `Settings` (abstract seam)
+
+Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
+
+```ts cordis-catalog
+/**
+ * Prepare the provider's user-editable document for a native editor. File
+ * providers may materialize an absent document before returning its path;
+ * non-file providers return undefined.
+ * @returns the absolute local document path, or undefined for non-file storage.
+ */
+prepareDocument(): Promise<string | undefined>
+
+/**
+ * Register a namespace schema and receive its owner scope. The registration
+ * is an effect on the calling plugin's fiber: disposing that fiber removes
+ * the namespace and its observers. An invalid stored section fails the
+ * registration itself — the earliest point where the schema can judge it.
+ * @param ns - unique namespace; duplicate registration fails loud.
+ * @param schema - schemastery schema resolving this namespace's value.
+ * @param options - composition `base` layer and effect timing.
+ * @returns the owner scope for reads, observation, and updates.
+ */
+register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
+
+/**
+ * Describe every registered namespace for configuration surfaces, including
+ * the composition `base` and raw user layers so a form can mark which fields
+ * the user overrode (presence in `user`) and what a reset returns to.
+ * @param options - redaction switch; wire surfaces must redact.
+ * @returns one descriptor per registered namespace, in registration order.
+ */
+describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
+
+/**
+ * Read one registered namespace's resolved value.
+ * @param ns - the namespace to read.
+ * @returns the resolved value, or `undefined` while unregistered.
+ */
+get(ns: SettingsNamespace): unknown
+
+/**
+ * Merge a patch into one registered namespace's user layer, validate the
+ * resolved candidate, persist through the provider, then commit and emit.
+ * A validation failure rejects before anything is persisted. Writes to one
+ * namespace are serialized: concurrent updates apply in call order, each
+ * merging over the previous write's committed section.
+ * @param ns - the registered namespace to update.
+ * @param patch - plain-object patch over the user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Replace one registered namespace's user section wholesale, validate,
+ * persist, then commit and emit. Keys absent from `section` fall back to the
+ * composition `base` and schema defaults — this is the removal/reset path a
+ * merge-only patch cannot express (`replace({})` re-inherits everything).
+ * @param ns - the registered namespace to replace.
+ * @param section - the complete next user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Apply path-addressed edits to one registered namespace's user section,
+ * validate, persist, then commit and emit. The ops are applied to the
+ * section as it stands when the write reaches the front of the queue, so a
+ * caller never has to restate fields it did not touch — and, crucially,
+ * cannot delete fields it never saw. This is the write path for any caller
+ * holding a redacted view; `replace` remains the wholesale reset.
+ * @param ns - the registered namespace to edit.
+ * @param ops - ordered path edits; later ops observe earlier ones.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
+```
+
+Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
+
+<a id="settings-events"></a>
+
+### `settings/*` events
+
+<a id="settingsdocument-updated--emit"></a>
+
+#### `settings/document-updated` — emit
+
+One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
+
+```ts cordis-catalog
+/**
+ * One registered namespace's RAW user section changed, whether or not the
+ * resolved value did. `settings/updated` is the consumer-facing event and
+ * stays deep-equal-gated; this one exists for configuration surfaces,
+ * which must learn that a field went from inherited to overridden (same
+ * resolved value, different meaning) and that their held revision is
+ * stale. Listener containment matches `settings/updated`.
+ * @param ns - the namespace whose stored section changed.
+ * @param revision - the namespace's new revision.
+ * @mode emit
+ */
+'settings/document-updated'(ns: SettingsNamespace, revision: number): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
+
+<a id="settingsupdated--emit"></a>
+
+#### `settings/updated` — emit
+
+Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to one registered namespace's resolved value. Emitted
+ * after the provider persisted (for `update`) or published (`provider`)
+ * the change; never emitted when the resolved value is deep-equal.
+ * Listener failures are contained and logged — a sync throw and an async
+ * rejection alike — except `INVARIANT`-coded failures, which rethrow
+ * after every listener ran; that rethrow reaches the emitter only from
+ * synchronous listeners, so invariant checks on this event must not be
+ * async functions.
+ * @param ns - the namespace whose resolved value changed.
+ * @param next - the new resolved value.
+ * @param prev - the previous resolved value.
+ * @param source - whether the change entered through `update()` or the provider.
+ * @mode emit
+ */
+'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 1cb7f8b507..f6d662ebaf 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -160,3 +160,151 @@ interface SettingsDescribeOptions {
 /** Origin of one committed settings change. */
 type SettingsUpdateSource = 'update' | 'provider'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsettings--settings-abstract-seam"></a>
+
+### `ctx.settings` — `Settings` (abstract seam)
+
+Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
+
+```ts cordis-catalog
+/**
+ * Prepare the provider's user-editable document for a native editor. File
+ * providers may materialize an absent document before returning its path;
+ * non-file providers return undefined.
+ * @returns the absolute local document path, or undefined for non-file storage.
+ */
+prepareDocument(): Promise<string | undefined>
+
+/**
+ * Register a namespace schema and receive its owner scope. The registration
+ * is an effect on the calling plugin's fiber: disposing that fiber removes
+ * the namespace and its observers. An invalid stored section fails the
+ * registration itself — the earliest point where the schema can judge it.
+ * @param ns - unique namespace; duplicate registration fails loud.
+ * @param schema - schemastery schema resolving this namespace's value.
+ * @param options - composition `base` layer and effect timing.
+ * @returns the owner scope for reads, observation, and updates.
+ */
+register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
+
+/**
+ * Describe every registered namespace for configuration surfaces, including
+ * the composition `base` and raw user layers so a form can mark which fields
+ * the user overrode (presence in `user`) and what a reset returns to.
+ * @param options - redaction switch; wire surfaces must redact.
+ * @returns one descriptor per registered namespace, in registration order.
+ */
+describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
+
+/**
+ * Read one registered namespace's resolved value.
+ * @param ns - the namespace to read.
+ * @returns the resolved value, or `undefined` while unregistered.
+ */
+get(ns: SettingsNamespace): unknown
+
+/**
+ * Merge a patch into one registered namespace's user layer, validate the
+ * resolved candidate, persist through the provider, then commit and emit.
+ * A validation failure rejects before anything is persisted. Writes to one
+ * namespace are serialized: concurrent updates apply in call order, each
+ * merging over the previous write's committed section.
+ * @param ns - the registered namespace to update.
+ * @param patch - plain-object patch over the user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Replace one registered namespace's user section wholesale, validate,
+ * persist, then commit and emit. Keys absent from `section` fall back to the
+ * composition `base` and schema defaults — this is the removal/reset path a
+ * merge-only patch cannot express (`replace({})` re-inherits everything).
+ * @param ns - the registered namespace to replace.
+ * @param section - the complete next user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Apply path-addressed edits to one registered namespace's user section,
+ * validate, persist, then commit and emit. The ops are applied to the
+ * section as it stands when the write reaches the front of the queue, so a
+ * caller never has to restate fields it did not touch — and, crucially,
+ * cannot delete fields it never saw. This is the write path for any caller
+ * holding a redacted view; `replace` remains the wholesale reset.
+ * @param ns - the registered namespace to edit.
+ * @param ops - ordered path edits; later ops observe earlier ones.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
+```
+
+Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
+
+<a id="settings-events"></a>
+
+### `settings/*` events
+
+<a id="settingsdocument-updated--emit"></a>
+
+#### `settings/document-updated` — emit
+
+One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
+
+```ts cordis-catalog
+/**
+ * One registered namespace's RAW user section changed, whether or not the
+ * resolved value did. `settings/updated` is the consumer-facing event and
+ * stays deep-equal-gated; this one exists for configuration surfaces,
+ * which must learn that a field went from inherited to overridden (same
+ * resolved value, different meaning) and that their held revision is
+ * stale. Listener containment matches `settings/updated`.
+ * @param ns - the namespace whose stored section changed.
+ * @param revision - the namespace's new revision.
+ * @mode emit
+ */
+'settings/document-updated'(ns: SettingsNamespace, revision: number): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
+
+<a id="settingsupdated--emit"></a>
+
+#### `settings/updated` — emit
+
+Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to one registered namespace's resolved value. Emitted
+ * after the provider persisted (for `update`) or published (`provider`)
+ * the change; never emitted when the resolved value is deep-equal.
+ * Listener failures are contained and logged — a sync throw and an async
+ * rejection alike — except `INVARIANT`-coded failures, which rethrow
+ * after every listener ran; that rethrow reaches the emitter only from
+ * synchronous listeners, so invariant checks on this event must not be
+ * async functions.
+ * @param ns - the namespace whose resolved value changed.
+ * @param next - the new resolved value.
+ * @param prev - the previous resolved value.
+ * @param source - whether the change entered through `update()` or the provider.
+ * @mode emit
+ */
+'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 6ab9693cca..84628f50b7 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/subsystems/skills.md
-skills.md: d862cbc07135680c2377b4c8c82c80d055344221
-skills.zh.md: 3f8c034ec2aa24b4acdbbc1e2ac27717c21649d5
+skills.md: 78d510fafca0017b9528a215270172a74e9b0de1
+skills.zh.md: e88c9f1ba190eb1e90966d35c7dcc2eb86ecd6cc
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index d862cbc071..78d510fafc 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -218,3 +218,93 @@ interface Config {
 Before each later model step, the consumer applies exact tool visibility and digests the exact rendered entries between the `<available_skills>` tags from a complete snapshot. It derives the comparison baseline from the same entries in the newest recognizable visible catalog message sourced by the plugin. A changed digest appends a durable full replacement through `agent.inject()`; deleting every skill appends an explicit empty replacement. Incomplete snapshots preserve the last-good model view. If compaction hides every historical catalog message, the next complete snapshot re-establishes the current catalog; an empty view with no prior catalog emits nothing. These catalog messages are session history, not World State.
 
 The model-facing `skill({ name })` tool validates the kebab-case name, finds the summary in the invocation-neutral catalog, rejects it before loading unless `isModelInvocable` permits access, then rereads the complete definition for the calling agent cwd and rechecks the policy before returning content. It reports an unresolved skill as unknown or no longer available and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. Body-only edits therefore change later tool calls without producing catalog messages or rewriting earlier tool results.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxskills--skillservice"></a>
+
+### `ctx.skills` — `SkillService`
+
+Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted invocation-neutral summaries, and loads full skill bodies on demand.
+
+```ts cordis-catalog
+/**
+ * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
+ * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+ * the provider and invalidates catalog caches.
+ * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
+ * @returns the exact Cordis effect disposer that unregisters this provider;
+ *   composite effects may yield it directly to preserve teardown ordering.
+ */
+registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
+
+/**
+ * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
+ * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
+ * receives a no-op disposer so it cannot remove the winner.
+ * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
+ * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+ */
+register(skill: SkillRegistration): () => void
+
+/**
+ * List invocation-neutral skill summaries for a workspace. Consumers apply
+ * model or user invocation policy at their operational boundary. Lookup
+ * options and provider candidates are readonly same-process values borrowed
+ * throughout discovery.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns all sorted winning summaries.
+ */
+async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
+
+/**
+ * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+ * Incomplete observations are never cached, allowing consumers to retain last-good state and
+ * retry on their next request boundary.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns sorted summaries plus discovery-completeness state.
+ */
+async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
+
+/**
+ * Load and validate the winning candidate, passing its opaque discovery locator back to the
+ * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+ * loading so an uncooperative provider cannot hang the caller.
+ * @param name - kebab-case skill name.
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+ * @returns the full skill, including body content, or `undefined`.
+ */
+async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
+```
+
+Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+
+<a id="skills-events"></a>
+
+### `skills/*` events
+
+<a id="skillschange--emit"></a>
+
+#### `skills/change` — emit
+
+A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A skill provider, runtime contribution, or provider-backed catalog may
+ * have changed. This is an unfiltered invalidation notification; consumers
+ * refetch the catalog for their own lookup options. Listener failures are
+ * contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'skills/change'(): void
+```
+
+Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index 3f8c034ec2..e88c9f1ba1 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -218,3 +218,93 @@ interface Config {
 在后续每个模型步骤之前，消费方都会应用精确的工具可见性，并对完整快照中 `<available_skills>` 标签之间精确渲染的条目计算 digest。它以该插件所发布、最新一条可识别且仍可见的目录消息中的相同条目作为比较基线。digest 发生变化时，会通过 `agent.inject()` 追加一条持久的完整目录替换；删除所有 skill 时会追加一条显式的空替换。不完整快照会保留上一份可用模型视图。如果压缩（compaction）隐藏了所有历史目录消息，下一份完整快照会重新建立当前目录；如果视图为空且从未发布目录，则不发送任何内容。这些目录消息属于会话历史，而非 World State。
 
 面向模型的 `skill({ name })` 工具校验 kebab-case 名称，在与调用策略无关的目录中查找摘要，并在加载前通过 `isModelInvocable` 拒绝无权访问的 skill；随后它根据调用方 agent 的 cwd 重新读取完整定义，并在返回内容前再次检查策略。该工具将无法解析的 skill 报告为未知或已不可用，并返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 仅按需解析显式引用的脚本、参考资料和资产；加载结果不枚举 skill 目录。因此，仅修改正文会改变后续工具调用，而不会生成目录消息或改写先前工具结果。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxskills--skillservice"></a>
+
+### `ctx.skills` — `SkillService`
+
+Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted invocation-neutral summaries, and loads full skill bodies on demand.
+
+```ts cordis-catalog
+/**
+ * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
+ * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+ * the provider and invalidates catalog caches.
+ * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
+ * @returns the exact Cordis effect disposer that unregisters this provider;
+ *   composite effects may yield it directly to preserve teardown ordering.
+ */
+registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
+
+/**
+ * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
+ * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
+ * receives a no-op disposer so it cannot remove the winner.
+ * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
+ * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+ */
+register(skill: SkillRegistration): () => void
+
+/**
+ * List invocation-neutral skill summaries for a workspace. Consumers apply
+ * model or user invocation policy at their operational boundary. Lookup
+ * options and provider candidates are readonly same-process values borrowed
+ * throughout discovery.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns all sorted winning summaries.
+ */
+async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
+
+/**
+ * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+ * Incomplete observations are never cached, allowing consumers to retain last-good state and
+ * retry on their next request boundary.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns sorted summaries plus discovery-completeness state.
+ */
+async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
+
+/**
+ * Load and validate the winning candidate, passing its opaque discovery locator back to the
+ * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+ * loading so an uncooperative provider cannot hang the caller.
+ * @param name - kebab-case skill name.
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+ * @returns the full skill, including body content, or `undefined`.
+ */
+async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
+```
+
+Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+
+<a id="skills-events"></a>
+
+### `skills/*` events
+
+<a id="skillschange--emit"></a>
+
+#### `skills/change` — emit
+
+A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A skill provider, runtime contribution, or provider-backed catalog may
+ * have changed. This is an unfiltered invalidation notification; consumers
+ * refetch the catalog for their own lookup options. Listener failures are
+ * contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'skills/change'(): void
+```
+
+Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index 17f210bc85..67b938a93a 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/spill.md
-spill.md: a798d8143b2849dc0cf49d04e7019ce796cdee45
-spill.zh.md: 1167c6f985dbc204dc7166b0fb5854dcf55bc72f
+#   pnpm run verify-translation-pairing --write docs/subsystems/spill.md
+spill.md: 41a3fdaf7d9b15fbc6d479724f77f579b8a98738
+spill.zh.md: 02a6fc4e88dfcfdb47f7639d988fc09c6bc42c69
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index a798d8143b..41a3fdaf7d 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -83,3 +83,35 @@ type SpillLocator = Branded<'SpillLocator'>
 `SpillStore` (`ctx.spillStore`, defined in [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)) is a one-method abstract service: `saveText(input) → Promise<SpillRef>`. It persists the FULL `content` and REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable). The seam owns storage only: no retention policy, no tool-result replacement, no retrieval/search API.
 
 The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes under `<root>/session-<hash>/<random>-<safeName>` — a configured or lazily-created private (0700) root, a `sha256(sessionId)` session subdir, and an exclusive owner-only (`open(path, 'wx', 0o600)`) write so a planted symlink cannot redirect it. Its `locator` is the local path and its `retrievalHint` tells the model to use `read` or `grep` on that path. The policy consumer ([dsh-spill-policy](../../packages/spill/spill-policy)) replaces an over-`maxInlineBytes` plain-text final result with a retention-library head/tail preview plus the spill reference, best-effort: a save failure keeps the original inline result rather than turning a successful call into an `isError`.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
+
+### `ctx.spillStore` — `SpillStore` (abstract seam)
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+```ts cordis-catalog
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, provenance, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 1167c6f985..02a6fc4e88 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -83,3 +83,35 @@ type SpillLocator = Branded<'SpillLocator'>
 `SpillStore`（`ctx.spillStore`，定义于 [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)）是只有一个方法的抽象服务：`saveText(input) → Promise<SpillRef>`。它持久保存完整的 `content`，并在实际存储失败（权限、ENOSPC、后端不可用）时拒绝。该 seam 只负责存储：不负责保留策略、工具结果替换或检索／搜索 API。
 
 本地后端（[dsh-spill-local](../../packages/spill/spill-local)）写入 `<root>/session-<hash>/<random>-<safeName>`：根目录是已配置或延迟创建的私有（0700）目录，会话子目录采用 `sha256(sessionId)`，并通过排他的仅所有者可访问写入（`open(path, 'wx', 0o600)`）防止预先植入的符号链接重定向写入。其 `locator` 是本地路径，`retrievalHint` 则告知模型在该路径上使用 `read` 或 `grep`。策略消费方（[dsh-spill-policy](../../packages/spill/spill-policy)）会把超过 `maxInlineBytes` 的纯文本最终结果替换为保留库生成的首尾预览和落盘引用；该过程尽力而为：保存失败时保留原始内联结果，而不会把成功的调用变成 `isError`。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
+
+### `ctx.spillStore` — `SpillStore` (abstract seam)
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+```ts cordis-catalog
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, provenance, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 6560eed831..98092af5b3 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
-storage.md: 5d54d7337b5ef52e24179758130b9fa8cd196376
-storage.zh.md: 46346b64351322d40de166a71f7a3204c8902b2d
+storage.md: 52dc84b699921e911276ce5214bc975abfd22fa4
+storage.zh.md: f614b77153e835264e1650515946a9d2acf70e57
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index 5d54d7337b..52dc84b699 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -8,7 +8,7 @@ Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/stora
 
 ## The hub: `ctx.storage`
 
-`Storage` ([signatures](../cordis-catalog/services.md#ctxstorage--storage)) is a meeting point, not a store. `ctx.storage.backend` is a name → backend table: multiple backends stay mounted side by side, and which backend serves which consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register(name, backend)` returns the disposer; duplicate names and unknown lookups throw `StorageError`. Disposal only unregisters the name — the owning plugin closes the backend after unregistering. Each backend plugin also publishes a lifecycle-only service key (`storageBackendServiceKey(name)`), which form providers inject so their activation cannot race backend registration.
+`Storage` ([signatures](#ctxstorage--storage)) is a meeting point, not a store. `ctx.storage.backend` is a name → backend table: multiple backends stay mounted side by side, and which backend serves which consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register(name, backend)` returns the disposer; duplicate names and unknown lookups throw `StorageError`. Disposal only unregisters the name — the owning plugin closes the backend after unregistering. Each backend plugin also publishes a lifecycle-only service key (`storageBackendServiceKey(name)`), which form providers inject so their activation cannot race backend registration.
 
 Data forms mount on the hub under a merge-extensible key map:
 
@@ -99,11 +99,11 @@ Reads are synchronous from authoritative in-memory state: `KvTable` exposes `get
 
 ## The domain facility: `ctx.storageDomain`
 
-`DomainFacility` ([signatures](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)) opens declared domains over routed backends. Routing is the domain plugin's configuration, never the hub's: `backend` names the required default route and `routes` overrides it per domain name. `open(spec)` runs a strict sequence, each step failing the whole call: it rejects a name already open or still closing (`already-open`), resolves the route (`backend-not-found`), requires the backend's `kv` facet (`facet-unsupported`), opens the unit (backend `version-mismatch`/`malformed-medium` pass through), and validates every stored record and global against the spec's zod schemas (`invalid-record` with the offending table and key). The caller owns the returned handle and releases it with `Domain.close()`; domains still open when the plugin unmounts are closed by the facility, and a closed domain's name frees for reopening only after teardown fully completes. `get(name)` is an untyped diagnostic lookup onto the package-private `DomainImpl` runtime behind every typed handle; `closeAll()` is the unmount path.
+`DomainFacility` ([signatures](#ctxstoragedomain--domainfacility)) opens declared domains over routed backends. Routing is the domain plugin's configuration, never the hub's: `backend` names the required default route and `routes` overrides it per domain name. `open(spec)` runs a strict sequence, each step failing the whole call: it rejects a name already open or still closing (`already-open`), resolves the route (`backend-not-found`), requires the backend's `kv` facet (`facet-unsupported`), opens the unit (backend `version-mismatch`/`malformed-medium` pass through), and validates every stored record and global against the spec's zod schemas (`invalid-record` with the offending table and key). The caller owns the returned handle and releases it with `Domain.close()`; domains still open when the plugin unmounts are closed by the facility, and a closed domain's name frees for reopening only after teardown fully completes. `get(name)` is an untyped diagnostic lookup onto the package-private `DomainImpl` runtime behind every typed handle; `closeAll()` is the unmount path.
 
 ## The change event: `domain/changed`
 
-Every durable write emits one event strictly after the backend acknowledged durability, in the domain's write-chain order ([event entry](../cordis-catalog/events.md#domainchanged--emit)):
+Every durable write emits one event strictly after the backend acknowledged durability, in the domain's write-chain order ([event entry](#domainchanged--emit)):
 
 ```ts type-equiv
 /** Shared location fields of one durable domain change. */
@@ -123,3 +123,107 @@ type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
 `put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is deferred work recorded in the [package README](../../packages/storage/storage-domain/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxstorage--storage"></a>
+
+### `ctx.storage` — `Storage`
+
+The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+
+```ts cordis-catalog
+/**
+ * Mount a data-form facility on the hub. Mounting is an effect: the
+ * returned disposer unmounts the form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @param facility - The facility instance to expose.
+ * @returns the disposer that unmounts the form.
+ */
+mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void
+
+/**
+ * Resolve a mounted data form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @returns the mounted facility.
+ */
+form<K extends keyof StorageForms>(form: K): StorageForms[K]
+```
+
+Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
+
+<a id="ctxstoragedomain--domainfacility"></a>
+
+### `ctx.storageDomain` — `DomainFacility`
+
+The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.
+
+```ts cordis-catalog
+/**
+ * Open one declared domain. Steps, each failing the whole call: reject a
+ * name that is already open (`already-open`); resolve the backend route
+ * (`backend-not-found` passes through from the hub); require its `kv` facet
+ * (`facet-unsupported`); open the unit projected from the spec (backend
+ * `version-mismatch`/`malformed-medium` pass through); load and validate
+ * every stored record against the spec's zod schemas (`invalid-record`
+ * with the offending table and key); construct the domain.
+ *
+ * Lifecycle: the CALLER owns the returned handle and closes it via
+ * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
+ * facility does not tie the domain to any consumer fiber. Domains still
+ * open when the facility unmounts are closed by the plugin disposer.
+ * @param spec - The domain declaration, typically from `defineDomain`.
+ * @returns the opened domain handle, typed by the spec.
+ */
+async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>
+
+/**
+ * Look up an open domain by name, untyped. Diagnostic surface (the package
+ * invariant cross-checks change events against live domain state); typed
+ * consumers hold the handle returned by {@link open}.
+ * @param name - Domain name.
+ * @returns the open domain runtime, or `undefined` when not open.
+ */
+get(name: string): DomainImpl | undefined
+
+/**
+ * Close every domain still open on this facility. The unmount path for
+ * consumers that never called `Domain.close()` themselves; closing is
+ * idempotent, so double-closing an already-closed domain is harmless.
+ * @returns resolution after every unit is released.
+ */
+async closeAll(): Promise<void>
+```
+
+Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
+
+<a id="domain-events"></a>
+
+### `domain/*` events
+
+<a id="domainchanged--emit"></a>
+
+#### `domain/changed` — emit
+
+A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability. Events of one domain arrive in its write-chain order.
+
+```ts cordis-catalog
+/**
+ * A domain record or the global singleton changed, emitted once per write
+ * strictly after the backend acknowledged durability. Events of one
+ * domain arrive in its write-chain order.
+ * @param change - domain, table (`''` for global), key (`''` for global),
+ * operation discriminant, and on `put` the new snapshot.
+ * @mode emit
+ */
+'domain/changed'(change: DomainChanged): void
+```
+
+Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index 46346b6435..f614b77153 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -8,7 +8,7 @@
 
 ## 枢纽：`ctx.storage`
 
-`Storage`（[签名](../cordis-catalog/services.md#ctxstorage--storage)）是汇合点，不是存储本体。`ctx.storage.backend` 是一张名称 → 后端的表：多个后端并排保持挂载，哪个后端服务哪个消费方由该消费方自己的配置决定（即领域层的路由表），绝不是枢纽全局的选择。`register(name, backend)` 返回 disposer；重复名称与查找未知名称都抛出 `StorageError`。dispose（资源释放）只注销名称——由拥有插件在注销之后自行关闭后端。每个后端插件还会发布一个仅用于生命周期的服务键（`storageBackendServiceKey(name)`），数据形式提供方注入它，使自身激活不会与后端注册发生竞态。
+`Storage`（[签名](#ctxstorage--storage)）是汇合点，不是存储本体。`ctx.storage.backend` 是一张名称 → 后端的表：多个后端并排保持挂载，哪个后端服务哪个消费方由该消费方自己的配置决定（即领域层的路由表），绝不是枢纽全局的选择。`register(name, backend)` 返回 disposer；重复名称与查找未知名称都抛出 `StorageError`。dispose（资源释放）只注销名称——由拥有插件在注销之后自行关闭后端。每个后端插件还会发布一个仅用于生命周期的服务键（`storageBackendServiceKey(name)`），数据形式提供方注入它，使自身激活不会与后端注册发生竞态。
 
 数据形式以一张可合并扩展的键 map 挂载到枢纽上：
 
@@ -99,11 +99,11 @@ interface Domain<S extends DomainSpec> {
 
 ## 领域 facility：`ctx.storageDomain`
 
-`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 按严格顺序执行，每一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找，命中的是每个类型化句柄背后包内私有的 `DomainImpl` 运行时；`closeAll()` 是卸载路径。
+`DomainFacility`（[签名](#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 按严格顺序执行，每一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找，命中的是每个类型化句柄背后包内私有的 `DomainImpl` 运行时；`closeAll()` 是卸载路径。
 
 ## 变更事件：`domain/changed`
 
-每次持久写入都发出一个事件，严格发生在后端确认持久性之后，顺序遵循该领域的写链（[事件条目](../cordis-catalog/events.md#domainchanged--emit)）：
+每次持久写入都发出一个事件，严格发生在后端确认持久性之后，顺序遵循该领域的写链（[事件条目](#domainchanged--emit)）：
 
 ```ts type-equiv
 /** Shared location fields of one durable domain change. */
@@ -123,3 +123,107 @@ type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
 `put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是延后工作，记录在[包 README](../../packages/storage/storage-domain/README.md)中。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxstorage--storage"></a>
+
+### `ctx.storage` — `Storage`
+
+The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+
+```ts cordis-catalog
+/**
+ * Mount a data-form facility on the hub. Mounting is an effect: the
+ * returned disposer unmounts the form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @param facility - The facility instance to expose.
+ * @returns the disposer that unmounts the form.
+ */
+mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void
+
+/**
+ * Resolve a mounted data form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @returns the mounted facility.
+ */
+form<K extends keyof StorageForms>(form: K): StorageForms[K]
+```
+
+Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
+
+<a id="ctxstoragedomain--domainfacility"></a>
+
+### `ctx.storageDomain` — `DomainFacility`
+
+The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.
+
+```ts cordis-catalog
+/**
+ * Open one declared domain. Steps, each failing the whole call: reject a
+ * name that is already open (`already-open`); resolve the backend route
+ * (`backend-not-found` passes through from the hub); require its `kv` facet
+ * (`facet-unsupported`); open the unit projected from the spec (backend
+ * `version-mismatch`/`malformed-medium` pass through); load and validate
+ * every stored record against the spec's zod schemas (`invalid-record`
+ * with the offending table and key); construct the domain.
+ *
+ * Lifecycle: the CALLER owns the returned handle and closes it via
+ * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
+ * facility does not tie the domain to any consumer fiber. Domains still
+ * open when the facility unmounts are closed by the plugin disposer.
+ * @param spec - The domain declaration, typically from `defineDomain`.
+ * @returns the opened domain handle, typed by the spec.
+ */
+async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>
+
+/**
+ * Look up an open domain by name, untyped. Diagnostic surface (the package
+ * invariant cross-checks change events against live domain state); typed
+ * consumers hold the handle returned by {@link open}.
+ * @param name - Domain name.
+ * @returns the open domain runtime, or `undefined` when not open.
+ */
+get(name: string): DomainImpl | undefined
+
+/**
+ * Close every domain still open on this facility. The unmount path for
+ * consumers that never called `Domain.close()` themselves; closing is
+ * idempotent, so double-closing an already-closed domain is harmless.
+ * @returns resolution after every unit is released.
+ */
+async closeAll(): Promise<void>
+```
+
+Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
+
+<a id="domain-events"></a>
+
+### `domain/*` events
+
+<a id="domainchanged--emit"></a>
+
+#### `domain/changed` — emit
+
+A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability. Events of one domain arrive in its write-chain order.
+
+```ts cordis-catalog
+/**
+ * A domain record or the global singleton changed, emitted once per write
+ * strictly after the backend acknowledged durability. Events of one
+ * domain arrive in its write-chain order.
+ * @param change - domain, table (`''` for global), key (`''` for global),
+ * operation discriminant, and on `put` the new snapshot.
+ * @mode emit
+ */
+'domain/changed'(change: DomainChanged): void
+```
+
+Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 57b960da91..e6ead80f87 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/subagent.md
-subagent.md: b26a12d1d50305d86d7ada29cac83474009d81ce
-subagent.zh.md: 6c4c64ff22050b73699a97093acd0032668fde3d
+#   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
+subagent.md: cbf9043b36a5cb2ab37bb99c6dbbf5a18d1e0288
+subagent.zh.md: ffd8fefd8b9d128c21e1b91ee0ba1fb706638fa9
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index b26a12d1d5..cbf9043b36 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -433,3 +433,269 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses `CreateAgentOptions.seed` (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/support/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsubagents--subagentservice"></a>
+
+### `ctx.subagents` — `SubagentService`
+
+Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
+
+```ts cordis-catalog
+/**
+ * Establish one durable continuable child and deliver its initial prompt.
+ * Resolves when the child's inbox accepts that prompt, without waiting for the
+ * turn to start or for the message to reach the Session log; any earlier
+ * failure rejects with no ids and rolls back the child entirely.
+ * @param spec - provider, delegation request, and caller cancellation.
+ * @returns the durable child id and the accepted prompt's message id.
+ * @throws when continuation services are unavailable or materialization fails.
+ */
+async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
+
+/**
+ * Deliver one later message to a continuable child as its next FIFO turn. A
+ * resident child's Agent inbox accepts it directly (waking a `waiting`
+ * Activation), while an absent one is cold-resumed from its persisted
+ * Session. The Agent inbox is the only queue, so every accepted message has
+ * one observable order.
+ * @param parent - the exact live direct parent authorizing this delivery.
+ * @param childId - durable child session id.
+ * @param content - user-role content to deliver.
+ * @param options - durable provenance and caller cancellation, which stops the
+ *   operation only before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ * @throws when continuation services are unavailable, parent authority is
+ *   rejected, or the message was not admitted.
+ */
+async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
+
+/**
+ * Interrupt one live continuable child's current turn under a human parent
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
+ * signal is issued before this returns, but the target may keep running
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
+ * and published descendants are preserved; claimed work is not requeued.
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+ * queue. An absent target — including a one-shot or unknown id —
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
+ * live Activation.
+ * @param targetSessionId - the durable child session id to interrupt.
+ * @param authority - the human parent address or exact live ancestor Agent.
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+ *   live target.
+ */
+interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
+
+/**
+ * Deliver selected content from one live continuable child to its durable
+ * direct parent. The child is the authority credential; callers cannot name a
+ * recipient. Reporting does not conclude the child's turn or Activation.
+ * @param child - exact live reporting child.
+ * @param content - selected model-facing content.
+ * @param options - parent scheduling and pre-acceptance cancellation.
+ * @returns the stable identity of the parent-accepted message.
+ * @throws when continuation services are unavailable, sender authorization
+ *   fails, or the direct parent is not live.
+ */
+async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>
+
+/**
+ * Compose one deployment capability into every continuable child's
+ * unpublished creation context on fresh creation and cold resume. Grants wait
+ * for the next Activation; removing the contribution revokes every resident
+ * installation immediately.
+ * @param contribution - synchronous child-scope installer.
+ * @returns the exact Cordis effect disposer.
+ */
+registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
+
+/**
+ * Close continuable admission below exact live parent Agents, stop only their
+ * visible descendant Activations synchronously, then await admitted scoped
+ * materializations and release those forests child-first. The scoped cutoff
+ * lasts until each exact parent leaves the registry; unrelated parent trees
+ * remain live.
+ * @param parents - exact host-owned parent Agents entering teardown.
+ * @returns once every retained descendant Activation released its `AgentHandle`.
+ * @throws an aggregate error after all branches settle when any failed.
+ */
+async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
+
+/**
+ * Enumerate the parent's direct session-backed subagents without loading or
+ * resuming an Agent and without any query seam: the listing merges the live
+ * session store with optional session persistence (live-preferred) and
+ * serves each child's durable mode/label from the registered `subagent`
+ * projection unit down a three-rung ladder — the registry's watermark
+ * snapshot for a live child; for a cold one, a durable projection-cache
+ * row when the optional cache serves an own-suffix identity (its `seq`
+ * gate proves the value postdates the fork seed, where a child's own
+ * descriptor is immutable once appended), else one persistence inspection
+ * folded through the registry. The
+ * projection fold is the single classification authority; per-child
+ * diagnostics relay a fold that served no identity or a failed inspection,
+ * never a list-time descriptor parse. Absent persistence, enumeration is
+ * live-only (a cold child cannot be resumed then either, so its absence is
+ * capability absence, not an error). This service consults no Agent
+ * registrations, Activations, or providers.
+ *
+ * Every persistence read receives `signal`, and the listing rechecks
+ * cancellation around each of those awaits. Read rejections that settle
+ * after an abort become a stable `SubagentError` with code `CANCELLED`.
+ * @param parentSessionId - parent session whose direct children are listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
+ */
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
+
+/**
+ * Enumerate the root's complete session-backed subagent tree in stable
+ * pre-order from one live-preferred corpus, without loading or resuming an
+ * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+ * continuable descendants below them are discovered; each returned entry
+ * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+ * diagnostics, optional persistence, and cancellation follow the same
+ * projection-backed contract as {@link listChildren}.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-candidate diagnostics with tree position, in
+ *   stable pre-order.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
+
+/**
+ * Register a provider under its name. Registration is effect-scoped and HMR
+ * safe; removing a provider blocks new starts but does not revoke runs that
+ * were already returned to their holders.
+ * @param provider - the trusted provider implementation.
+ * @returns the exact Cordis effect disposer.
+ */
+registerProvider(provider: SubagentProvider): () => void
+
+/**
+ * Look up a provider by name.
+ * @param name - the provider name.
+ * @returns the provider, or undefined when absent.
+ */
+getProvider(name: string): SubagentProvider | undefined
+
+/**
+ * List registered provider names in insertion order.
+ * @returns the registered names.
+ */
+list(): string[]
+
+/**
+ * Establish a published child on the named provider. Capability and semantic
+ * checks run before delegation. Provider ownership lasts until its promise
+ * fulfills; a rejection therefore has no run for the caller to dispose and
+ * emits no run lifecycle events. Post-publication turn and infrastructure
+ * failures settle through the returned run.
+ * @param name - the provider to use.
+ * @param request - child label, prompt, parent, signal, and optional capabilities.
+ * @returns the published holder-owned run.
+ */
+async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagent-events"></a>
+
+### `subagent/*` events
+
+<a id="subagentend--emit"></a>
+
+#### `subagent/end` — emit
+
+A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
+
+```ts cordis-catalog
+/**
+ * A published child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-added--emit"></a>
+
+#### `subagent/provider-added` — emit
+
+A provider became resolvable in the registry.
+
+```ts cordis-catalog
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
+'subagent/provider-added'(provider: SubagentProvider): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-removed--emit"></a>
+
+#### `subagent/provider-removed` — emit
+
+A provider left the registry. Accepted runs remain holder-owned.
+
+```ts cordis-catalog
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
+'subagent/provider-removed'(name: string): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentstart--emit"></a>
+
+#### `subagent/start` — emit
+
+A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
+
+```ts cordis-catalog
+/**
+ * A provider established a published child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and published child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 6c4c64ff22..ffd8fefd8b 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -435,3 +435,269 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 `CreateAgentOptions.seed`（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsubagents--subagentservice"></a>
+
+### `ctx.subagents` — `SubagentService`
+
+Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
+
+```ts cordis-catalog
+/**
+ * Establish one durable continuable child and deliver its initial prompt.
+ * Resolves when the child's inbox accepts that prompt, without waiting for the
+ * turn to start or for the message to reach the Session log; any earlier
+ * failure rejects with no ids and rolls back the child entirely.
+ * @param spec - provider, delegation request, and caller cancellation.
+ * @returns the durable child id and the accepted prompt's message id.
+ * @throws when continuation services are unavailable or materialization fails.
+ */
+async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
+
+/**
+ * Deliver one later message to a continuable child as its next FIFO turn. A
+ * resident child's Agent inbox accepts it directly (waking a `waiting`
+ * Activation), while an absent one is cold-resumed from its persisted
+ * Session. The Agent inbox is the only queue, so every accepted message has
+ * one observable order.
+ * @param parent - the exact live direct parent authorizing this delivery.
+ * @param childId - durable child session id.
+ * @param content - user-role content to deliver.
+ * @param options - durable provenance and caller cancellation, which stops the
+ *   operation only before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ * @throws when continuation services are unavailable, parent authority is
+ *   rejected, or the message was not admitted.
+ */
+async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
+
+/**
+ * Interrupt one live continuable child's current turn under a human parent
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
+ * signal is issued before this returns, but the target may keep running
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
+ * and published descendants are preserved; claimed work is not requeued.
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+ * queue. An absent target — including a one-shot or unknown id —
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
+ * live Activation.
+ * @param targetSessionId - the durable child session id to interrupt.
+ * @param authority - the human parent address or exact live ancestor Agent.
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+ *   live target.
+ */
+interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
+
+/**
+ * Deliver selected content from one live continuable child to its durable
+ * direct parent. The child is the authority credential; callers cannot name a
+ * recipient. Reporting does not conclude the child's turn or Activation.
+ * @param child - exact live reporting child.
+ * @param content - selected model-facing content.
+ * @param options - parent scheduling and pre-acceptance cancellation.
+ * @returns the stable identity of the parent-accepted message.
+ * @throws when continuation services are unavailable, sender authorization
+ *   fails, or the direct parent is not live.
+ */
+async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>
+
+/**
+ * Compose one deployment capability into every continuable child's
+ * unpublished creation context on fresh creation and cold resume. Grants wait
+ * for the next Activation; removing the contribution revokes every resident
+ * installation immediately.
+ * @param contribution - synchronous child-scope installer.
+ * @returns the exact Cordis effect disposer.
+ */
+registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
+
+/**
+ * Close continuable admission below exact live parent Agents, stop only their
+ * visible descendant Activations synchronously, then await admitted scoped
+ * materializations and release those forests child-first. The scoped cutoff
+ * lasts until each exact parent leaves the registry; unrelated parent trees
+ * remain live.
+ * @param parents - exact host-owned parent Agents entering teardown.
+ * @returns once every retained descendant Activation released its `AgentHandle`.
+ * @throws an aggregate error after all branches settle when any failed.
+ */
+async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
+
+/**
+ * Enumerate the parent's direct session-backed subagents without loading or
+ * resuming an Agent and without any query seam: the listing merges the live
+ * session store with optional session persistence (live-preferred) and
+ * serves each child's durable mode/label from the registered `subagent`
+ * projection unit down a three-rung ladder — the registry's watermark
+ * snapshot for a live child; for a cold one, a durable projection-cache
+ * row when the optional cache serves an own-suffix identity (its `seq`
+ * gate proves the value postdates the fork seed, where a child's own
+ * descriptor is immutable once appended), else one persistence inspection
+ * folded through the registry. The
+ * projection fold is the single classification authority; per-child
+ * diagnostics relay a fold that served no identity or a failed inspection,
+ * never a list-time descriptor parse. Absent persistence, enumeration is
+ * live-only (a cold child cannot be resumed then either, so its absence is
+ * capability absence, not an error). This service consults no Agent
+ * registrations, Activations, or providers.
+ *
+ * Every persistence read receives `signal`, and the listing rechecks
+ * cancellation around each of those awaits. Read rejections that settle
+ * after an abort become a stable `SubagentError` with code `CANCELLED`.
+ * @param parentSessionId - parent session whose direct children are listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
+ */
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
+
+/**
+ * Enumerate the root's complete session-backed subagent tree in stable
+ * pre-order from one live-preferred corpus, without loading or resuming an
+ * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+ * continuable descendants below them are discovered; each returned entry
+ * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+ * diagnostics, optional persistence, and cancellation follow the same
+ * projection-backed contract as {@link listChildren}.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-candidate diagnostics with tree position, in
+ *   stable pre-order.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
+
+/**
+ * Register a provider under its name. Registration is effect-scoped and HMR
+ * safe; removing a provider blocks new starts but does not revoke runs that
+ * were already returned to their holders.
+ * @param provider - the trusted provider implementation.
+ * @returns the exact Cordis effect disposer.
+ */
+registerProvider(provider: SubagentProvider): () => void
+
+/**
+ * Look up a provider by name.
+ * @param name - the provider name.
+ * @returns the provider, or undefined when absent.
+ */
+getProvider(name: string): SubagentProvider | undefined
+
+/**
+ * List registered provider names in insertion order.
+ * @returns the registered names.
+ */
+list(): string[]
+
+/**
+ * Establish a published child on the named provider. Capability and semantic
+ * checks run before delegation. Provider ownership lasts until its promise
+ * fulfills; a rejection therefore has no run for the caller to dispose and
+ * emits no run lifecycle events. Post-publication turn and infrastructure
+ * failures settle through the returned run.
+ * @param name - the provider to use.
+ * @param request - child label, prompt, parent, signal, and optional capabilities.
+ * @returns the published holder-owned run.
+ */
+async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagent-events"></a>
+
+### `subagent/*` events
+
+<a id="subagentend--emit"></a>
+
+#### `subagent/end` — emit
+
+A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
+
+```ts cordis-catalog
+/**
+ * A published child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-added--emit"></a>
+
+#### `subagent/provider-added` — emit
+
+A provider became resolvable in the registry.
+
+```ts cordis-catalog
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
+'subagent/provider-added'(provider: SubagentProvider): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-removed--emit"></a>
+
+#### `subagent/provider-removed` — emit
+
+A provider left the registry. Accepted runs remain holder-owned.
+
+```ts cordis-catalog
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
+'subagent/provider-removed'(name: string): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentstart--emit"></a>
+
+#### `subagent/start` — emit
+
+A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
+
+```ts cordis-catalog
+/**
+ * A provider established a published child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and published child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index b2d38854b2..a3071e98a9 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/subprocess.md
-subprocess.md: 023b122218ad1caa2b8e16c26b0bc8b0d4183c28
-subprocess.zh.md: 5ee9c782c0ce73ca9a2e694450ed38b8d548dc09
+#   pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md
+subprocess.md: 0bc2bf86518bcc60bef02554b94471425f2ac433
+subprocess.zh.md: 5d6425707edcf1952c25dbdc91dbf7aab3779350
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index 023b122218..0bc2bf8651 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -242,8 +242,83 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice-abstract-seam).
 
 ## Service behavior
 
 The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxe2b--e2bsandboxservice"></a>
+
+### `ctx.e2b` — `E2BSandboxService`
+
+Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
+
+```ts cordis-catalog
+/**
+ * Return the shared live SDK handle.
+ * @returns the created sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation or the service is disposing.
+ */
+async getSandbox(): Promise<Sandbox>
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
+
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
+
+Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Executable paths belong to one execution world shared with the mounted filesystem provider.
+- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
+- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
+- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
+- Disposal of the service terminates all still-running managed processes and awaits their exit.
+- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
+
+```ts cordis-catalog
+/**
+ * Resolve one configured executable in this provider's execution world.
+ * Absolute paths are verified; bare names use the provider's scrubbed PATH
+ * plus explicit environment overrides. Relative paths containing separators
+ * are rejected: no current consumer defines which directory they would
+ * resolve against, so providers fail loud instead of guessing.
+ * @param command - absolute executable path or bare PATH name.
+ * @param env - explicit environment entries used for lookup.
+ * @param signal - aborts remote or local lookup.
+ * @returns a canonical executable path.
+ */
+abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
+
+/**
+ * Start one managed child process from a fully-specified spec; this seam
+ * applies no defaults.
+ * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
+ * @returns the live process handle (streams/readers, signalling, outcome promise).
+ */
+abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+/**
+ * Allocate a real terminal and start one owned process session. This is the
+ * only non-pipe process primitive: implementations own terminal byte I/O,
+ * foreground groups, signals, and complete session-tree cleanup.
+ * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+ * @returns the live terminal handle after allocation succeeds.
+ */
+abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
+```
+
+Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 5ee9c782c0..5d6425707e 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -242,8 +242,83 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice-abstract-seam)中。
 
 ## 服务行为
 
 抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxe2b--e2bsandboxservice"></a>
+
+### `ctx.e2b` — `E2BSandboxService`
+
+Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
+
+```ts cordis-catalog
+/**
+ * Return the shared live SDK handle.
+ * @returns the created sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation or the service is disposing.
+ */
+async getSandbox(): Promise<Sandbox>
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
+
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
+
+Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Executable paths belong to one execution world shared with the mounted filesystem provider.
+- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
+- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
+- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
+- Disposal of the service terminates all still-running managed processes and awaits their exit.
+- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
+
+```ts cordis-catalog
+/**
+ * Resolve one configured executable in this provider's execution world.
+ * Absolute paths are verified; bare names use the provider's scrubbed PATH
+ * plus explicit environment overrides. Relative paths containing separators
+ * are rejected: no current consumer defines which directory they would
+ * resolve against, so providers fail loud instead of guessing.
+ * @param command - absolute executable path or bare PATH name.
+ * @param env - explicit environment entries used for lookup.
+ * @param signal - aborts remote or local lookup.
+ * @returns a canonical executable path.
+ */
+abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
+
+/**
+ * Start one managed child process from a fully-specified spec; this seam
+ * applies no defaults.
+ * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
+ * @returns the live process handle (streams/readers, signalling, outcome promise).
+ */
+abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+/**
+ * Allocate a real terminal and start one owned process session. This is the
+ * only non-pipe process primitive: implementations own terminal byte I/O,
+ * foreground groups, signals, and complete session-tree cleanup.
+ * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+ * @returns the live terminal handle after allocation succeeds.
+ */
+abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
+```
+
+Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
index 5c39e3cbcb..a1e14385f4 100644
--- a/docs/subsystems/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.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 docs/subsystems/system-prompt.md
-system-prompt.md: 59193c1881abcadbc8a1778cde92f5a6572eee24
-system-prompt.zh.md: 41e45417817895ccf6def70e510eca7422a65e41
+system-prompt.md: 94ce40f8bf98dd4efe3514879c2527c2a7bd3b21
+system-prompt.zh.md: 37d366774089f91756433602a719e99b57747c17
diff --git a/docs/subsystems/system-prompt.md b/docs/subsystems/system-prompt.md
index 59193c1881..94ce40f8bf 100644
--- a/docs/subsystems/system-prompt.md
+++ b/docs/subsystems/system-prompt.md
@@ -76,3 +76,113 @@ interface PromptContext {
   readonly text: string | ((context: AssembleContext) => string)
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsystemprompt--systemprompt"></a>
+
+### `ctx.systemPrompt` — `SystemPrompt`
+
+Registry service for the prompt inputs assembled before each model step.
+
+```ts cordis-catalog
+/**
+ * Register an ordered prompt section in the calling context's scope. A scoped
+ * section shadows a global section with the same name; duplicates within one
+ * layer and non-finite orders throw. Registration and disposal emit
+ * `system-prompt/change`.
+ * @param section - the section to register.
+ * @returns the exact Cordis effect disposer.
+ */
+section(section: PromptSection): () => void
+
+/**
+ * Register ordered dynamic context in the calling context's scope. Scoped
+ * entries shadow global entries with the same name.
+ * @param context - the context contribution to register.
+ * @returns the exact Cordis effect disposer.
+ */
+context(context: PromptContext): () => void
+
+/**
+ * Register a tool-schema provider in the calling context's scope. Global and
+ * matching scoped providers both contribute; returning the reserved
+ * {@link TOOL_ORDER_REST} name makes assembly fail.
+ * @param provider - evaluated for each assembly with its context.
+ * @returns the exact Cordis effect disposer.
+ */
+tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
+
+/**
+ * Register a prompt variable in the calling context's scope. Scoped values
+ * shadow globals; invalid or duplicate names throw. A provider may return
+ * `undefined`, but rendering a section that references that value then fails.
+ * @param name - the `[a-z][a-z0-9_]*` reference name.
+ * @param provider - evaluated for each assembly.
+ * @returns the exact Cordis effect disposer.
+ */
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
+
+/**
+ * Assemble global and scoped providers, detach tool parameters, apply
+ * canonical ordering, then run the assembly waterfall. Scoped sections and
+ * variables shadow globals; the returned waterfall value is authoritative.
+ * @param context - the optional scope and plugin-defined assembly fields.
+ * @returns the authoritative post-waterfall assembly.
+ */
+async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-prompt-events"></a>
+
+### `system-prompt/*` events
+
+<a id="system-promptassemble--waterfall"></a>
+
+#### `system-prompt/assemble` — waterfall
+
+Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
+
+```ts cordis-catalog
+/**
+ * Expert waterfall over the assembled sections, contexts, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * A supplied signal controls only this explicit assembly request and must not
+ * be retained to control later turns.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
+'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-promptchange--emit"></a>
+
+#### `system-prompt/change` — emit
+
+Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
+
+```ts cordis-catalog
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
+'system-prompt/change'(): void
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
index 41e4541781..37d3667740 100644
--- a/docs/subsystems/system-prompt.zh.md
+++ b/docs/subsystems/system-prompt.zh.md
@@ -76,3 +76,113 @@ interface PromptContext {
   readonly text: string | ((context: AssembleContext) => string)
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsystemprompt--systemprompt"></a>
+
+### `ctx.systemPrompt` — `SystemPrompt`
+
+Registry service for the prompt inputs assembled before each model step.
+
+```ts cordis-catalog
+/**
+ * Register an ordered prompt section in the calling context's scope. A scoped
+ * section shadows a global section with the same name; duplicates within one
+ * layer and non-finite orders throw. Registration and disposal emit
+ * `system-prompt/change`.
+ * @param section - the section to register.
+ * @returns the exact Cordis effect disposer.
+ */
+section(section: PromptSection): () => void
+
+/**
+ * Register ordered dynamic context in the calling context's scope. Scoped
+ * entries shadow global entries with the same name.
+ * @param context - the context contribution to register.
+ * @returns the exact Cordis effect disposer.
+ */
+context(context: PromptContext): () => void
+
+/**
+ * Register a tool-schema provider in the calling context's scope. Global and
+ * matching scoped providers both contribute; returning the reserved
+ * {@link TOOL_ORDER_REST} name makes assembly fail.
+ * @param provider - evaluated for each assembly with its context.
+ * @returns the exact Cordis effect disposer.
+ */
+tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
+
+/**
+ * Register a prompt variable in the calling context's scope. Scoped values
+ * shadow globals; invalid or duplicate names throw. A provider may return
+ * `undefined`, but rendering a section that references that value then fails.
+ * @param name - the `[a-z][a-z0-9_]*` reference name.
+ * @param provider - evaluated for each assembly.
+ * @returns the exact Cordis effect disposer.
+ */
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
+
+/**
+ * Assemble global and scoped providers, detach tool parameters, apply
+ * canonical ordering, then run the assembly waterfall. Scoped sections and
+ * variables shadow globals; the returned waterfall value is authoritative.
+ * @param context - the optional scope and plugin-defined assembly fields.
+ * @returns the authoritative post-waterfall assembly.
+ */
+async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-prompt-events"></a>
+
+### `system-prompt/*` events
+
+<a id="system-promptassemble--waterfall"></a>
+
+#### `system-prompt/assemble` — waterfall
+
+Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
+
+```ts cordis-catalog
+/**
+ * Expert waterfall over the assembled sections, contexts, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * A supplied signal controls only this explicit assembly request and must not
+ * be retained to control later turns.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
+'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-promptchange--emit"></a>
+
+#### `system-prompt/change` — emit
+
+Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
+
+```ts cordis-catalog
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
+'system-prompt/change'(): void
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index 58920a53df..d28dcc2781 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/tasks.md
-tasks.md: a38055d3ef7aa18e62678f92eb5ac5ae2a09c205
-tasks.zh.md: f34d42e713c3a0c11cbf88d52e573bb100c52493
+#   pnpm run verify-translation-pairing --write docs/subsystems/tasks.md
+tasks.md: 6237607307cbab8511f968ed591e3e3b8b845c6a
+tasks.zh.md: 99a6fcc4f54c1b52e5c6fd393327cc768f064297
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index a38055d3ef..6237607307 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -152,3 +152,109 @@ interface TaskRead {
 ## Service behavior
 
 The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defines atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local implementation. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the seam contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtasks--taskservice-abstract-seam"></a>
+
+### `ctx.tasks` — `TaskService` (abstract seam)
+
+Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
+- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
+- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
+
+```ts cordis-catalog
+/**
+ * Preflight access, validation, and owner cleanup before starting and
+ * atomically registering work. A throwing starter leaves nothing registered;
+ * after it returns, registration cannot fail. Settlement records the outcome,
+ * notifies listeners, and releases waiters.
+ * @param spec - task identity, owner, and synchronous starter.
+ * @returns the registry-issued `<kind>-N` id.
+ */
+abstract start(spec: TaskStart): TaskId
+
+/**
+ * List caller-owned and unowned tasks in registration order without exposing
+ * another session's labels.
+ * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+ * @returns fresh snapshots.
+ */
+abstract list(caller?: Agent): TaskSnapshot[]
+
+/**
+ * Return a non-consuming snapshot without changing its read cursor or notice
+ * state. Throws for an unknown or foreign task.
+ * @param id - task to look up.
+ * @param caller - reading agent checked against the owner.
+ * @returns a fresh snapshot.
+ */
+abstract get(id: TaskId, caller?: Agent): TaskSnapshot
+
+/**
+ * Read the next stream delta, or the idempotent final output after settlement.
+ * A terminal read marks the task reported. Throws for an unknown or foreign
+ * task.
+ * @param id - task to read.
+ * @param caller - reading agent checked against the owner.
+ * @returns output text and the post-read snapshot.
+ */
+abstract read(id: TaskId, caller?: Agent): TaskRead
+
+/**
+ * Request cancellation, then mark the task stopping and reported. A producer
+ * throw propagates without changing task state. Throws for an unknown or
+ * foreign task.
+ * @param id - task to cancel.
+ * @param caller - killing agent checked against the owner.
+ * @param reason - logged reason forwarded to the producer.
+ * @returns `requested` for live work, otherwise `already-finished`.
+ */
+abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+
+/**
+ * Wait for settlement or timeout without cancelling the task. Caller abort
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * Throws for invalid, unknown, or foreign input.
+ * @param id - task to wait for.
+ * @param timeoutMs - positive finite wait bound in milliseconds.
+ * @param caller - waiting agent checked against the owner.
+ * @param signal - optional cancellation of the wait itself.
+ * @returns snapshot at settlement or timeout.
+ */
+abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+
+/**
+ * Register an effect-scoped completion listener. Each listener is contained;
+ * returned promises are observed but not awaited. No listener runs after
+ * service disposal.
+ * @param listener - receives each terminal snapshot and its exact owner.
+ * @returns disposer that unregisters the listener.
+ */
+abstract onTaskDone(listener: TaskDoneListener): () => void
+
+/**
+ * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+ * refuses work while none is attached.
+ * @param name - diagnostic label; duplicate names remain independent.
+ * @returns disposer that detaches this surface.
+ */
+abstract attachSurface(name: string): () => void
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index f34d42e713..99a6fcc4f5 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -152,3 +152,109 @@ interface TaskRead {
 ## 服务行为
 
 抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 契约见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtasks--taskservice-abstract-seam"></a>
+
+### `ctx.tasks` — `TaskService` (abstract seam)
+
+Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
+- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
+- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
+
+```ts cordis-catalog
+/**
+ * Preflight access, validation, and owner cleanup before starting and
+ * atomically registering work. A throwing starter leaves nothing registered;
+ * after it returns, registration cannot fail. Settlement records the outcome,
+ * notifies listeners, and releases waiters.
+ * @param spec - task identity, owner, and synchronous starter.
+ * @returns the registry-issued `<kind>-N` id.
+ */
+abstract start(spec: TaskStart): TaskId
+
+/**
+ * List caller-owned and unowned tasks in registration order without exposing
+ * another session's labels.
+ * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+ * @returns fresh snapshots.
+ */
+abstract list(caller?: Agent): TaskSnapshot[]
+
+/**
+ * Return a non-consuming snapshot without changing its read cursor or notice
+ * state. Throws for an unknown or foreign task.
+ * @param id - task to look up.
+ * @param caller - reading agent checked against the owner.
+ * @returns a fresh snapshot.
+ */
+abstract get(id: TaskId, caller?: Agent): TaskSnapshot
+
+/**
+ * Read the next stream delta, or the idempotent final output after settlement.
+ * A terminal read marks the task reported. Throws for an unknown or foreign
+ * task.
+ * @param id - task to read.
+ * @param caller - reading agent checked against the owner.
+ * @returns output text and the post-read snapshot.
+ */
+abstract read(id: TaskId, caller?: Agent): TaskRead
+
+/**
+ * Request cancellation, then mark the task stopping and reported. A producer
+ * throw propagates without changing task state. Throws for an unknown or
+ * foreign task.
+ * @param id - task to cancel.
+ * @param caller - killing agent checked against the owner.
+ * @param reason - logged reason forwarded to the producer.
+ * @returns `requested` for live work, otherwise `already-finished`.
+ */
+abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+
+/**
+ * Wait for settlement or timeout without cancelling the task. Caller abort
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * Throws for invalid, unknown, or foreign input.
+ * @param id - task to wait for.
+ * @param timeoutMs - positive finite wait bound in milliseconds.
+ * @param caller - waiting agent checked against the owner.
+ * @param signal - optional cancellation of the wait itself.
+ * @returns snapshot at settlement or timeout.
+ */
+abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+
+/**
+ * Register an effect-scoped completion listener. Each listener is contained;
+ * returned promises are observed but not awaited. No listener runs after
+ * service disposal.
+ * @param listener - receives each terminal snapshot and its exact owner.
+ * @returns disposer that unregisters the listener.
+ */
+abstract onTaskDone(listener: TaskDoneListener): () => void
+
+/**
+ * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+ * refuses work while none is attached.
+ * @param name - diagnostic label; duplicate names remain independent.
+ * @returns disposer that detaches this surface.
+ */
+abstract attachSurface(name: string): () => void
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 2eb634bb2d..19cd6f6851 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: cf570723650c32f048ee797923a58f09c777455d
-telemetry.zh.md: 1bcaa86264e3afd741d66d6ee718946e6151496f
+telemetry.md: 131c5814f29d70c356989e62fda1db5c1c5448d6
+telemetry.zh.md: 5d4a9d9994457bc06a9e4194c4807f88789a3cf0
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index cf57072365..131c5814f2 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -105,8 +105,76 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry` (`ctx.telemetry`, [signatures](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
 
 ## The redact waterfall: `telemetry/record`
 
-Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between projection and `emit()` ([event entry](../cordis-catalog/events.md#telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
+Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between projection and `emit()` ([event entry](#telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+
+### `ctx.telemetry` — `Telemetry` (abstract seam)
+
+The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
+
+```ts cordis-catalog
+/**
+ * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * @param record - the logical record to report; owned by the backend after the call.
+ */
+abstract emit(record: TelemetryRecord): void
+
+/** See {@link TelemetryBackend.flush}. */
+flush?(): void
+
+/**
+ * See {@link TelemetryBackend.shutdown}.
+ * @returns resolves when the backend's pipeline has quiesced.
+ */
+abstract shutdown(): Promise<void>
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
+
+<a id="telemetry-events"></a>
+
+### `telemetry/*` events
+
+<a id="telemetryrecord--waterfall"></a>
+
+#### `telemetry/record` — waterfall
+
+Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+
+```ts cordis-catalog
+/**
+ * Transform one outbound record before it reaches the backend. This
+ * waterfall is the seam's redaction extension point. It ships NO rules
+ * of its own: the
+ * innermost `next()` passes the record through unchanged, and with no
+ * listener mounted records reach the backend as captured, so exported
+ * data is exactly as clean as the rules a deployment mounts. Listeners
+ * stack by transforming `next()`'s return value; returning without
+ * `next()` replaces everything beneath. Dispatched synchronously on the
+ * capture hot path inside the coordinator's containment: a throwing
+ * listener withholds that one record (fail-closed) and never reaches the
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
+ * @param record - the candidate record, already the coordinator's own deep
+ *   copy; listeners return a (possibly new) record and must not mutate it.
+ * @mode waterfall
+ */
+'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 1bcaa86264..5d4a9d9994 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -105,8 +105,76 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
-每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics)（[事件条目](../cordis-catalog/events.md#telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics)（[事件条目](#telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+
+### `ctx.telemetry` — `Telemetry` (abstract seam)
+
+The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
+
+```ts cordis-catalog
+/**
+ * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * @param record - the logical record to report; owned by the backend after the call.
+ */
+abstract emit(record: TelemetryRecord): void
+
+/** See {@link TelemetryBackend.flush}. */
+flush?(): void
+
+/**
+ * See {@link TelemetryBackend.shutdown}.
+ * @returns resolves when the backend's pipeline has quiesced.
+ */
+abstract shutdown(): Promise<void>
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
+
+<a id="telemetry-events"></a>
+
+### `telemetry/*` events
+
+<a id="telemetryrecord--waterfall"></a>
+
+#### `telemetry/record` — waterfall
+
+Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+
+```ts cordis-catalog
+/**
+ * Transform one outbound record before it reaches the backend. This
+ * waterfall is the seam's redaction extension point. It ships NO rules
+ * of its own: the
+ * innermost `next()` passes the record through unchanged, and with no
+ * listener mounted records reach the backend as captured, so exported
+ * data is exactly as clean as the rules a deployment mounts. Listeners
+ * stack by transforming `next()`'s return value; returning without
+ * `next()` replaces everything beneath. Dispatched synchronously on the
+ * capture hot path inside the coordinator's containment: a throwing
+ * listener withholds that one record (fail-closed) and never reaches the
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
+ * @param record - the candidate record, already the coordinator's own deep
+ *   copy; listeners return a (possibly new) record and must not mutate it.
+ * @mode waterfall
+ */
+'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
index 3f58d10153..e348aca7a0 100644
--- a/docs/subsystems/token-meter.i18n.yaml
+++ b/docs/subsystems/token-meter.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/token-meter.md
-token-meter.md: 05784e294485a11acf0e4c8972e4083b1786c943
-token-meter.zh.md: 0474d86188a111014e6d72e9962121c08a228d73
+#   pnpm run verify-translation-pairing --write docs/subsystems/token-meter.md
+token-meter.md: 0f53955b3e6afce84520314f4de453edaa897158
+token-meter.zh.md: 3ba22c54d599982d3f7bdbcb9160b6ffc3255e07
diff --git a/docs/subsystems/token-meter.md b/docs/subsystems/token-meter.md
index 05784e2944..0f53955b3e 100644
--- a/docs/subsystems/token-meter.md
+++ b/docs/subsystems/token-meter.md
@@ -41,3 +41,50 @@ interface TokenSurfaceNode {
 ```
 
 Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtokenmeter--tokenmeterservice"></a>
+
+### `ctx.tokenMeter` — `TokenMeterService`
+
+Replay owner for one service-wide estimator and isolated per-session folds.
+
+```ts cordis-catalog
+/**
+ * Measure current request pressure and surface through the durable tail.
+ *
+ * Provider usage is reused only when the latest successful call's canonical
+ * request envelope matches `requestHeader` and its total is no lower than
+ * that call's full heuristic anchor; otherwise the complete envelope and
+ * surface are heuristically repriced.
+ *
+ * `requestHeader` affects request pressure only; surface fields always
+ * describe the current session surface. Every call clones those positional
+ * nodes, so measurement is O(surface).
+ *
+ * @param session - session to replay through its current durable tail.
+ * @param requestHeader - optional effective request envelope replacing the latest logged header.
+ * @returns a detached deeply immutable pressure and surface measurement.
+ */
+measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
+
+/**
+ * Heuristically price one model-visible message (instance face of the pure
+ * `estimateMessage` export from `estimate.ts`).
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed service heuristic.
+ */
+estimateMessage(message: Message): number
+```
+
+Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+
+Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
index 0474d86188..3ba22c54d5 100644
--- a/docs/subsystems/token-meter.zh.md
+++ b/docs/subsystems/token-meter.zh.md
@@ -41,3 +41,50 @@ interface TokenSurfaceNode {
 ```
 
 表层顺序具有权威性；替换节点的持久 seq 可能高于位置排在其后的节点。该快照不可变，不会随底层回放折叠推进而增长。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtokenmeter--tokenmeterservice"></a>
+
+### `ctx.tokenMeter` — `TokenMeterService`
+
+Replay owner for one service-wide estimator and isolated per-session folds.
+
+```ts cordis-catalog
+/**
+ * Measure current request pressure and surface through the durable tail.
+ *
+ * Provider usage is reused only when the latest successful call's canonical
+ * request envelope matches `requestHeader` and its total is no lower than
+ * that call's full heuristic anchor; otherwise the complete envelope and
+ * surface are heuristically repriced.
+ *
+ * `requestHeader` affects request pressure only; surface fields always
+ * describe the current session surface. Every call clones those positional
+ * nodes, so measurement is O(surface).
+ *
+ * @param session - session to replay through its current durable tail.
+ * @param requestHeader - optional effective request envelope replacing the latest logged header.
+ * @returns a detached deeply immutable pressure and surface measurement.
+ */
+measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
+
+/**
+ * Heuristically price one model-visible message (instance face of the pure
+ * `estimateMessage` export from `estimate.ts`).
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed service heuristic.
+ */
+estimateMessage(message: Message): number
+```
+
+Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+
+Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index a30f122038..8b0aa47c9a 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 853eed16cff451edcc32bc3aa5c6bc7cabb0f518
-tools.zh.md: ec8809f6bebd185404828c5c5879f8eff832ea9a
+tools.md: 5d72bd54f0dc5995218087030f24c467c8ccbb38
+tools.zh.md: 2340d4c2d92c51aa9cc89f4694b626c76d05140b
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 853eed16cf..5d72bd54f0 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -455,3 +455,241 @@ How a tool wants its call shown in a UI (an editor tool-call card, a CLI log lin
 `ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon on a generic card. `FileLocation` (`{ path, line? }`), `FileDiff` (`{ path, oldText, newText }`), and `ReadFileLine` (`{ number, text }`, one 1-based numbered line of a read window) are the shared file-card vocabulary. The design is pinned in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); host/client runtimes project this neutral vocabulary into their own views.
 
 The full presentation field docs live in [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts). The `bash` schema and executor are on [bash.md](bash.md); generic background controls are on [tasks.md](tasks.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtools--toolregistry"></a>
+
+### `ctx.tools` — `ToolRegistry`
+
+Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
+
+```ts cordis-catalog
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+ * @returns the exact disposer that unregisters the tool.
+ */
+register(definition: ToolDefinition): () => void
+
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
+restrict(filter: ToolRestriction): () => void
+
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
+guard(guard: ToolGuard): () => void
+
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
+get(name: string, scope?: ScopeKey): ToolDefinition | undefined
+
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
+schemas(scope?: ScopeKey): ToolSchema[]
+
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
+executionMode(exec: ToolExecutionInput): ToolExecutionMode
+
+/**
+ * Execute through pre-policy, guards, around-dispatch, post-policy,
+ * definition-owned content finalization, and final notification. Tool and
+ * listener failures resolve as materialized error results; an invisible tool
+ * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+ * snapshot final observers receive. Cancellation
+ * arriving after entry and before final result materialization skips a
+ * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
+ * successful started outcome with `ABORTED`; already-started work is still
+ * drained and may retain a tool-owned structured error.
+ * @param exec - the typed same-process call input. The registry assigns its
+ *   correlation token before policy begins.
+ * @returns the materialized final result.
+ */
+async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
+```
+
+Types: [ScopeKey](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+
+<a id="tools-events"></a>
+
+### `tools/*` events
+
+<a id="toolschange--emit"></a>
+
+#### `tools/change` — emit
+
+A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
+
+```ts cordis-catalog
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
+'tools/change'(): void
+```
+
+Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+
+<a id="toolscode-dispatch-log--waterfall"></a>
+
+#### `tools/code-dispatch-log` — waterfall
+
+Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/code-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected — the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the unshaped content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+
+```ts cordis-catalog
+/**
+ * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
+ * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
+ * content unchanged; a listener may return replacement blocks (e.g. the
+ * spill policy's preview + locator for an oversized text result). Only the
+ * logged copy is affected — the program already received the complete
+ * value, and the model sees neither. A throwing listener is contained:
+ * the bridge falls back to logging the unshaped content.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+ * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
+ * @mode waterfall
+ */
+'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
+```
+
+Types: [ContentBlock](core.md) · [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsexecute--waterfall"></a>
+
+#### `tools/execute` — waterfall
+
+Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable. The registry re-fuses the original caller
+ * signal before the body, so replacement cannot detach caller cancellation;
+ * wrappers must still restore their signal and reach quiescence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
+'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspost-execute--waterfall"></a>
+
+#### `tools/post-execute` — waterfall
+
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * listeners must observe `exec.signal`; after they settle, caller
+ * cancellation replaces only a successful accepted outcome with the code
+ * selected by whether the tool body was invoked.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
+'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspre-execute--waterfall"></a>
+
+#### `tools/pre-execute` — waterfall
+
+Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial. Async gates must observe
+ * `exec.signal`; the registry rechecks cancellation after they settle but
+ * never abandons their promise.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
+'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsresult--emit"></a>
+
+#### `tools/result` — emit
+
+Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+
+```ts cordis-catalog
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
+'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index ec8809f6be..2340d4c2d9 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -455,3 +455,241 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 `ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）、`FileDiff`（`{ path, oldText, newText }`）与 `ReadFileLine`（`{ number, text }`，读取窗口中一行带 1-based 行号的内容）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；host/client 运行时将这套中性词汇投影为各自的视图。
 
 完整的展示字段文档见 [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)。`bash` schema 与执行器见 [bash.md](bash.md)；通用后台控制见 [tasks.md](tasks.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtools--toolregistry"></a>
+
+### `ctx.tools` — `ToolRegistry`
+
+Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
+
+```ts cordis-catalog
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+ * @returns the exact disposer that unregisters the tool.
+ */
+register(definition: ToolDefinition): () => void
+
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
+restrict(filter: ToolRestriction): () => void
+
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
+guard(guard: ToolGuard): () => void
+
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
+get(name: string, scope?: ScopeKey): ToolDefinition | undefined
+
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
+schemas(scope?: ScopeKey): ToolSchema[]
+
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
+executionMode(exec: ToolExecutionInput): ToolExecutionMode
+
+/**
+ * Execute through pre-policy, guards, around-dispatch, post-policy,
+ * definition-owned content finalization, and final notification. Tool and
+ * listener failures resolve as materialized error results; an invisible tool
+ * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+ * snapshot final observers receive. Cancellation
+ * arriving after entry and before final result materialization skips a
+ * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
+ * successful started outcome with `ABORTED`; already-started work is still
+ * drained and may retain a tool-owned structured error.
+ * @param exec - the typed same-process call input. The registry assigns its
+ *   correlation token before policy begins.
+ * @returns the materialized final result.
+ */
+async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
+```
+
+Types: [ScopeKey](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+
+<a id="tools-events"></a>
+
+### `tools/*` events
+
+<a id="toolschange--emit"></a>
+
+#### `tools/change` — emit
+
+A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
+
+```ts cordis-catalog
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
+'tools/change'(): void
+```
+
+Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+
+<a id="toolscode-dispatch-log--waterfall"></a>
+
+#### `tools/code-dispatch-log` — waterfall
+
+Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/code-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected — the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the unshaped content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+
+```ts cordis-catalog
+/**
+ * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
+ * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
+ * content unchanged; a listener may return replacement blocks (e.g. the
+ * spill policy's preview + locator for an oversized text result). Only the
+ * logged copy is affected — the program already received the complete
+ * value, and the model sees neither. A throwing listener is contained:
+ * the bridge falls back to logging the unshaped content.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+ * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
+ * @mode waterfall
+ */
+'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
+```
+
+Types: [ContentBlock](core.md) · [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsexecute--waterfall"></a>
+
+#### `tools/execute` — waterfall
+
+Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable. The registry re-fuses the original caller
+ * signal before the body, so replacement cannot detach caller cancellation;
+ * wrappers must still restore their signal and reach quiescence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
+'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspost-execute--waterfall"></a>
+
+#### `tools/post-execute` — waterfall
+
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * listeners must observe `exec.signal`; after they settle, caller
+ * cancellation replaces only a successful accepted outcome with the code
+ * selected by whether the tool body was invoked.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
+'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspre-execute--waterfall"></a>
+
+#### `tools/pre-execute` — waterfall
+
+Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial. Async gates must observe
+ * `exec.signal`; the registry rechecks cancellation after they settle but
+ * never abandons their promise.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
+'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsresult--emit"></a>
+
+#### `tools/result` — emit
+
+Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+
+```ts cordis-catalog
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
+'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index 75b7837687..b8fdb092f2 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/typert.md
-typert.md: c70e50e2fea8455eb75dfdf8c309f659ab9cb2f9
-typert.zh.md: 2cd1636d4cc8dbcfa009073b4a8e1dcc8d5897e4
+#   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
+typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
+typert.zh.md: ff6b45a517c75392ee87fa348d72bfae6cdf1efb
diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md
index c70e50e2fe..8ce52837ce 100644
--- a/docs/subsystems/typert.md
+++ b/docs/subsystems/typert.md
@@ -201,3 +201,96 @@ interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtypert--typertregistry"></a>
+
+### `ctx.typert` — `TypertRegistry`
+
+Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
+
+```ts cordis-catalog
+/**
+ * Register one generated contribution atomically for the calling fiber.
+ * Duplicate package-face identities, schemas, invocation ids, or endpoints
+ * reject the whole batch.
+ * @param contribution - generated schemas, reflection, and Host invocations.
+ * @returns the exact effect disposer that removes this contribution.
+ */
+register(contribution: TypertContribution): TypeRTDisposer
+
+/**
+ * Look up one schema by `<package>#<name>`.
+ * @param key - global schema key.
+ * @returns the live schema record, or `undefined` when absent.
+ */
+get(key: string): TypertSchemaRecord | undefined
+
+/**
+ * Resolve one required schema.
+ * @param key - global schema key.
+ * @returns the live schema record.
+ * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+ */
+resolve(key: string): TypertSchemaRecord
+
+/**
+ * Enumerate live schemas in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching schema records.
+ */
+list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
+
+/**
+ * Look up generated reflection for one package face.
+ * @param packageName - exact npm package name.
+ * @param face - face to query; defaults to the host runtime.
+ * @returns the live package record, or `undefined` when absent.
+ */
+getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
+
+/**
+ * Enumerate generated package reflection in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching package records.
+ */
+listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
+
+/**
+ * Project a live Zod schema to JSON Schema without caching the result.
+ * @param key - global schema key.
+ * @param params - Zod projection parameters.
+ * @returns a fresh JSON Schema document.
+ */
+toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
+```
+
+Types: [TypertContribution](invariants.md) · [TypertFace](invariants.md) · [TypertPackageFilter](invariants.md) · [TypertPackageRecord](invariants.md) · [TypertSchemaFilter](invariants.md) · [TypertSchemaRecord](invariants.md)
+
+Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
+
+<a id="ctxtypertgateway--typertgatewayservice"></a>
+
+### `ctx.typertGateway` — `TypertGatewayService`
+
+Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
+
+```ts cordis-catalog
+/**
+ * Invoke one live Remote method through strict generated reflection or SRC markers.
+ * @param request - decoded endpoint and exact named wire arguments.
+ * @returns the validated business result.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+ */
+async invoke(request: InvokeRemoteRequest): Promise<unknown>
+```
+
+Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index 2cd1636d4c..ff6b45a517 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -201,3 +201,96 @@ interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtypert--typertregistry"></a>
+
+### `ctx.typert` — `TypertRegistry`
+
+Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
+
+```ts cordis-catalog
+/**
+ * Register one generated contribution atomically for the calling fiber.
+ * Duplicate package-face identities, schemas, invocation ids, or endpoints
+ * reject the whole batch.
+ * @param contribution - generated schemas, reflection, and Host invocations.
+ * @returns the exact effect disposer that removes this contribution.
+ */
+register(contribution: TypertContribution): TypeRTDisposer
+
+/**
+ * Look up one schema by `<package>#<name>`.
+ * @param key - global schema key.
+ * @returns the live schema record, or `undefined` when absent.
+ */
+get(key: string): TypertSchemaRecord | undefined
+
+/**
+ * Resolve one required schema.
+ * @param key - global schema key.
+ * @returns the live schema record.
+ * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+ */
+resolve(key: string): TypertSchemaRecord
+
+/**
+ * Enumerate live schemas in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching schema records.
+ */
+list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
+
+/**
+ * Look up generated reflection for one package face.
+ * @param packageName - exact npm package name.
+ * @param face - face to query; defaults to the host runtime.
+ * @returns the live package record, or `undefined` when absent.
+ */
+getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
+
+/**
+ * Enumerate generated package reflection in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching package records.
+ */
+listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
+
+/**
+ * Project a live Zod schema to JSON Schema without caching the result.
+ * @param key - global schema key.
+ * @param params - Zod projection parameters.
+ * @returns a fresh JSON Schema document.
+ */
+toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
+```
+
+Types: [TypertContribution](invariants.md) · [TypertFace](invariants.md) · [TypertPackageFilter](invariants.md) · [TypertPackageRecord](invariants.md) · [TypertSchemaFilter](invariants.md) · [TypertSchemaRecord](invariants.md)
+
+Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
+
+<a id="ctxtypertgateway--typertgatewayservice"></a>
+
+### `ctx.typertGateway` — `TypertGatewayService`
+
+Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
+
+```ts cordis-catalog
+/**
+ * Invoke one live Remote method through strict generated reflection or SRC markers.
+ * @param request - decoded endpoint and exact named wire arguments.
+ * @returns the validated business result.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+ */
+async invoke(request: InvokeRemoteRequest): Promise<unknown>
+```
+
+Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
index 80ebb810c8..342cf9b9f7 100644
--- a/docs/subsystems/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.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 docs/subsystems/user-interaction.md
-user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014
-user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b
+user-interaction.md: a19155ae06af0133ae468c004b2e3b66f1de3fb8
+user-interaction.zh.md: dc5845a976068981b2761e26502eaf7dd95dcb01
diff --git a/docs/subsystems/user-interaction.md b/docs/subsystems/user-interaction.md
index ec22eb28e9..a19155ae06 100644
--- a/docs/subsystems/user-interaction.md
+++ b/docs/subsystems/user-interaction.md
@@ -132,3 +132,47 @@ class UserInteractionError extends HarnessError {
   }
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxuserinteraction--userinteractionservice"></a>
+
+### `ctx.userInteraction` — `UserInteractionService`
+
+`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
+
+```ts cordis-catalog
+/**
+ * Register the UI provider. Only one provider may be active in a context.
+ *
+ * @param provider UI-side implementation that collects answers.
+ * @returns Disposer that unregisters this provider.
+ */
+registerProvider(provider: UserInteractionProvider): () => void
+
+/**
+ * Ask the active UI provider and wait for the user's answer.
+ *
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live runtime root. Runtime ownership, not durable session lineage,
+ * decides this boundary: an owned child has no human answerer and would
+ * block forever, while a lineage-bearing session resumed as a new runtime
+ * root may ask normally.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
+ *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+ *   when that live agent is owned by another agent.
+ */
+async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+```
+
+Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
index 814f8911e4..dc5845a976 100644
--- a/docs/subsystems/user-interaction.zh.md
+++ b/docs/subsystems/user-interaction.zh.md
@@ -132,3 +132,47 @@ class UserInteractionError extends HarnessError {
   }
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxuserinteraction--userinteractionservice"></a>
+
+### `ctx.userInteraction` — `UserInteractionService`
+
+`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
+
+```ts cordis-catalog
+/**
+ * Register the UI provider. Only one provider may be active in a context.
+ *
+ * @param provider UI-side implementation that collects answers.
+ * @returns Disposer that unregisters this provider.
+ */
+registerProvider(provider: UserInteractionProvider): () => void
+
+/**
+ * Ask the active UI provider and wait for the user's answer.
+ *
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live runtime root. Runtime ownership, not durable session lineage,
+ * decides this boundary: an owned child has no human answerer and would
+ * block forever, while a lineage-bearing session resumed as a new runtime
+ * root may ask normally.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
+ *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+ *   when that live agent is owned by another agent.
+ */
+async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+```
+
+Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index e8ae658d3a..f3f0ab9758 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/web.md
-web.md: 20d07240c9d9fea2f1f5abbac810f349a3e81f9b
-web.zh.md: e2982ba571353752e3a7d10130599e8c8fe941f8
+#   pnpm run verify-translation-pairing --write docs/subsystems/web.md
+web.md: f300bf2daef172fe4a69c00f36c804cf874c189d
+web.zh.md: 0c72e343c1b6ea5de8e7c296014da35b0291a33b
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index 20d07240c9..f300bf2dae 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -133,3 +133,70 @@ Selection never depends on registration, config, or HMR order: a capability has
 ## The service
 
 `WebService` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. Private-network blocking is deferred, so do not enable `web_fetch` where it can reach sensitive internal targets.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxweb--webservice"></a>
+
+### `ctx.web` — `WebService`
+
+The web access service. Registered as `ctx.web` (one instance per context).
+
+Selection semantics (resolved at execution time, never order-dependent):
+
+- A configured id that is registered and `available()` → that provider.
+- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+- No id configured, exactly one registered usable provider → that provider.
+- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+
+```ts cordis-catalog
+/**
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for search. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerSearchProvider(provider: WebSearchProvider): () => void
+
+/**
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for fetch. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerFetchProvider(provider: WebFetchProvider): () => void
+
+/**
+ * Run one search through the selected provider. Resolves the provider at call
+ * time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+ * @param request - the query plus result-shaping options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the provider's results, capped to `request.maxResults`.
+ */
+async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+
+/**
+ * Retrieve one URL through the selected provider. Resolves the provider at
+ * call time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. A non-2xx response is a result, not a throw.
+ * @param request - the URL plus retrieval options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+ */
+async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+```
+
+Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index e2982ba571..0c72e343c1 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -133,3 +133,70 @@ type WebFetchBody =
 ## 服务
 
 `WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码正文；展示由工具负责。SSRF／私有网络防护尚未实现，因此在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxweb--webservice"></a>
+
+### `ctx.web` — `WebService`
+
+The web access service. Registered as `ctx.web` (one instance per context).
+
+Selection semantics (resolved at execution time, never order-dependent):
+
+- A configured id that is registered and `available()` → that provider.
+- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+- No id configured, exactly one registered usable provider → that provider.
+- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+
+```ts cordis-catalog
+/**
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for search. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerSearchProvider(provider: WebSearchProvider): () => void
+
+/**
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for fetch. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerFetchProvider(provider: WebFetchProvider): () => void
+
+/**
+ * Run one search through the selected provider. Resolves the provider at call
+ * time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+ * @param request - the query plus result-shaping options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the provider's results, capped to `request.maxResults`.
+ */
+async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+
+/**
+ * Retrieve one URL through the selected provider. Resolves the provider at
+ * call time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. A non-2xx response is a result, not a throw.
+ * @param request - the URL plus retrieval options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+ */
+async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+```
+
+Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index 7f996a1c8e..4f581d8bae 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/workflow.md
-workflow.md: 8d271b89e71de6f6bef548aa8da61402ef9ada6e
-workflow.zh.md: 91a4902bbc004e911c8aa84adb6a4abeda9dd59f
+#   pnpm run verify-translation-pairing --write docs/subsystems/workflow.md
+workflow.md: 53cb8be2c975fba396c3d2023c60fc1da2ed9c8a
+workflow.zh.md: 652b68c833f7f20fe72307946d02f89558be2c2b
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index 8d271b89e7..53cb8be2c9 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -129,4 +129,154 @@ Hook misuse inside a script — bad arguments, unknown/deferred `agent()` option
 
 ## Events
 
-The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](../cordis-catalog/events.md)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — and every listener receives its own payload clone, so mutating it corrupts neither the engine nor other listeners; the containment mirrors `subagent/start`/`subagent/end`.
+The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](#cordis-surface)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — and every listener receives its own payload clone, so mutating it corrupts neither the engine nor other listeners; the containment mirrors `subagent/start`/`subagent/end`.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+
+### `ctx.workflows` — `WorkflowService` (abstract seam)
+
+Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+
+```ts cordis-catalog
+/**
+ * Parse and execute a workflow script.
+ * @param request - the script, its `args`, the parent agent, and an
+ *   optional cancel signal.
+ * @returns the live run; its `result` resolves when the script settles.
+ */
+abstract start(request: WorkflowStartRequest): WorkflowRun
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflow-events"></a>
+
+### `workflow/*` events
+
+<a id="workflowagent-end--emit"></a>
+
+#### `workflow/agent-end` — emit
+
+One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
+'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowagent-start--emit"></a>
+
+#### `workflow/agent-start` — emit
+
+One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call established a published child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a published run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
+'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowend--emit"></a>
+
+#### `workflow/end` — emit
+
+A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
+
+```ts cordis-catalog
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
+'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowlog--emit"></a>
+
+#### `workflow/log` — emit
+
+The script emitted a narration line (a `log(message)` call).
+
+```ts cordis-catalog
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
+'workflow/log'(info: WorkflowRunInfo, message: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowphase--emit"></a>
+
+#### `workflow/phase` — emit
+
+The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
+
+```ts cordis-catalog
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
+'workflow/phase'(info: WorkflowRunInfo, title: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowstart--emit"></a>
+
+#### `workflow/start` — emit
+
+A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
+
+```ts cordis-catalog
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
+'workflow/start'(info: WorkflowRunInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 91a4902bbc..652b68c833 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -129,4 +129,154 @@ interface WorkflowRun {
 
 ## 事件
 
-`workflow/*` 事件（`workflow/start`、`workflow/phase`、`workflow/log`、`workflow/agent-start`、`workflow/agent-end`、`workflow/end`，见[事件目录](../cordis-catalog/events.md)）是**仅供观察**的 emit，携带数据快照：每个 payload 以 `WorkflowRunInfo`（id + meta）开头，而非活跃的 `WorkflowRun`，因此订阅者无法获得 `cancel`/`dispose`；`workflow/end` 刻意省略 result value（观察结果的监听器不得收到调用方 result 的可变别名）。每次 emit 对每个监听器隔离：抛出异常的订阅者被记录日志但不传播，不会饿死在它之后注册的监听器；每个监听器收到自己的 payload 克隆，因此修改它既不会损坏引擎也不会影响其他监听器。这种隔离方式与 `subagent/start`/`subagent/end` 一致。
+`workflow/*` 事件（`workflow/start`、`workflow/phase`、`workflow/log`、`workflow/agent-start`、`workflow/agent-end`、`workflow/end`，见[事件目录](#cordis-surface)）是**仅供观察**的 emit，携带数据快照：每个 payload 以 `WorkflowRunInfo`（id + meta）开头，而非活跃的 `WorkflowRun`，因此订阅者无法获得 `cancel`/`dispose`；`workflow/end` 刻意省略 result value（观察结果的监听器不得收到调用方 result 的可变别名）。每次 emit 对每个监听器隔离：抛出异常的订阅者被记录日志但不传播，不会饿死在它之后注册的监听器；每个监听器收到自己的 payload 克隆，因此修改它既不会损坏引擎也不会影响其他监听器。这种隔离方式与 `subagent/start`/`subagent/end` 一致。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+
+### `ctx.workflows` — `WorkflowService` (abstract seam)
+
+Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+
+```ts cordis-catalog
+/**
+ * Parse and execute a workflow script.
+ * @param request - the script, its `args`, the parent agent, and an
+ *   optional cancel signal.
+ * @returns the live run; its `result` resolves when the script settles.
+ */
+abstract start(request: WorkflowStartRequest): WorkflowRun
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflow-events"></a>
+
+### `workflow/*` events
+
+<a id="workflowagent-end--emit"></a>
+
+#### `workflow/agent-end` — emit
+
+One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
+'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowagent-start--emit"></a>
+
+#### `workflow/agent-start` — emit
+
+One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call established a published child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a published run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
+'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowend--emit"></a>
+
+#### `workflow/end` — emit
+
+A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
+
+```ts cordis-catalog
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
+'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowlog--emit"></a>
+
+#### `workflow/log` — emit
+
+The script emitted a narration line (a `log(message)` call).
+
+```ts cordis-catalog
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
+'workflow/log'(info: WorkflowRunInfo, message: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowphase--emit"></a>
+
+#### `workflow/phase` — emit
+
+The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
+
+```ts cordis-catalog
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
+'workflow/phase'(info: WorkflowRunInfo, title: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowstart--emit"></a>
+
+#### `workflow/start` — emit
+
+A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
+
+```ts cordis-catalog
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
+'workflow/start'(info: WorkflowRunInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 6a6488206c..b2c2248876 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: 5614631e828e51f3b515ae4af17451bd9eda1dbb
-workspace.zh.md: 11e8f0207a8db8b7612d6672cfe744523490aef7
+workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
+workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 5614631e82..ca088a2091 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -117,10 +117,103 @@ Ownership truth is the record's ordered `sessionIds`, never derived from session
 
 ## The registry: `ctx.workspace`
 
-`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
+`WorkspaceRegistry` ([signatures](#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
 
 Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
 
 ## Consumers
 
 [dsh-host-apiproxy](../../packages/host/apiproxy) is the product consumer: it serves workspace CRUD to GUI clients over `ctx.workspace` and performs the create-session-then-attach flow above. [dsh-workspace-context](../../packages/context/workspace-context) is **not** a consumer despite the name: it discovers AGENTS.md-style instruction files under an agent's own cwd and never touches `ctx.workspace` — the shared word refers to the user's working directory, not to this registry's entities.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+
+Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
+
+```ts cordis-catalog
+/**
+ * The backend's interaction capability.
+ * @returns the discriminated capability consumers switch on.
+ */
+abstract capability(): DirectoryPickerCapability
+```
+
+Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
+
+<a id="ctxworkspace--workspaceregistry"></a>
+
+### `ctx.workspace` — `WorkspaceRegistry`
+
+Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
+
+```ts cordis-catalog
+/**
+ * Create or reuse a workspace for an existing directory. The path is
+ * canonicalized through `fs.realpath`; a nonexistent path rejects with the
+ * original error and a non-directory rejects. Repeated calls for the same
+ * canonical path return the existing entity without changing its title.
+ * A newly created workspace is prepended to the durable registry order.
+ * Different canonical paths may share a display title.
+ * @param path - Existing directory to own, in any path spelling.
+ * @param title - Display title used only when a new record is created.
+ * @returns the existing or newly durable workspace.
+ */
+async create(path: string, title?: string): Promise<Workspace>
+
+/**
+ * Look up a workspace by id.
+ * @param id - Workspace id.
+ * @returns the workspace, or `undefined` when unknown.
+ */
+get(id: WorkspaceId): Workspace | undefined
+
+/**
+ * Synchronous workspace projection in durable registry order. Every
+ * entity's `sessionIds` getter is already filtered by the startup/live
+ * canonical-cwd header index; this method performs no persistence reads.
+ * @returns a fresh ordered array of workspace entities.
+ */
+list(): Workspace[]
+
+/**
+ * Delete one workspace registration while retaining its directory and every
+ * session log. The durable order is updated before the table deletion; a
+ * failed table write restores the prior order and keeps the entity
+ * published. Unknown ids are an idempotent no-op for domain callers.
+ * @param id - Workspace registration to remove.
+ * @returns `true` when a record was deleted, `false` when it was unknown.
+ */
+delete(id: WorkspaceId): Promise<boolean>
+
+/**
+ * Archive one session durably. The session must exist (live or in session
+ * persistence); its workspace accounting — or lack of one — is irrelevant.
+ * An already archived id resolves without writing.
+ * @param sessionId - The session to archive.
+ * @returns resolution after durability.
+ */
+archiveSession(sessionId: SessionId): Promise<void>
+
+/**
+ * Resolve by canonical directory path without creating or mutating a
+ * workspace. A missing path rejects during `realpath`; an existing unowned
+ * directory returns `undefined`.
+ * @param path - Existing directory path in any spelling.
+ * @returns the workspace owning the canonical path, when one exists.
+ */
+async resolveByPath(path: string): Promise<Workspace | undefined>
+```
+
+Types: [SessionId](core.md)
+
+Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 11e8f0207a..e414c759a0 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -117,10 +117,103 @@ interface Workspace {
 
 ## 注册表：`ctx.workspace`
 
-`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好解决被标记的那次变更——通过删除被标记的表行：这会补完被中断的 delete，并回滚被中断的 create（注册可以重建，因此回滚是安全方向）——而没有标记的顺序/表不一致则作为损坏大声失败。
+`WorkspaceRegistry`（[签名](#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好解决被标记的那次变更——通过删除被标记的表行：这会补完被中断的 delete，并回滚被中断的 create（注册可以重建，因此回滚是安全方向）——而没有标记的顺序/表不一致则作为损坏大声失败。
 
 会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
 ## 消费方
 
 [dsh-host-apiproxy](../../packages/host/apiproxy) 是产品消费方：它经 `ctx.workspace` 向 GUI 客户端提供工作区的 CRUD，并执行上文「先建会话再 attach」的流程。[dsh-workspace-context](../../packages/context/workspace-context) 尽管名字如此，却**不是**消费方：它在 agent 自己的 cwd 下发现 AGENTS.md 风格的指令文件，从不触碰 `ctx.workspace`——两者共用的这个词指的是用户的工作目录，而非本注册表的实体。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+
+Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
+
+```ts cordis-catalog
+/**
+ * The backend's interaction capability.
+ * @returns the discriminated capability consumers switch on.
+ */
+abstract capability(): DirectoryPickerCapability
+```
+
+Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
+
+<a id="ctxworkspace--workspaceregistry"></a>
+
+### `ctx.workspace` — `WorkspaceRegistry`
+
+Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
+
+```ts cordis-catalog
+/**
+ * Create or reuse a workspace for an existing directory. The path is
+ * canonicalized through `fs.realpath`; a nonexistent path rejects with the
+ * original error and a non-directory rejects. Repeated calls for the same
+ * canonical path return the existing entity without changing its title.
+ * A newly created workspace is prepended to the durable registry order.
+ * Different canonical paths may share a display title.
+ * @param path - Existing directory to own, in any path spelling.
+ * @param title - Display title used only when a new record is created.
+ * @returns the existing or newly durable workspace.
+ */
+async create(path: string, title?: string): Promise<Workspace>
+
+/**
+ * Look up a workspace by id.
+ * @param id - Workspace id.
+ * @returns the workspace, or `undefined` when unknown.
+ */
+get(id: WorkspaceId): Workspace | undefined
+
+/**
+ * Synchronous workspace projection in durable registry order. Every
+ * entity's `sessionIds` getter is already filtered by the startup/live
+ * canonical-cwd header index; this method performs no persistence reads.
+ * @returns a fresh ordered array of workspace entities.
+ */
+list(): Workspace[]
+
+/**
+ * Delete one workspace registration while retaining its directory and every
+ * session log. The durable order is updated before the table deletion; a
+ * failed table write restores the prior order and keeps the entity
+ * published. Unknown ids are an idempotent no-op for domain callers.
+ * @param id - Workspace registration to remove.
+ * @returns `true` when a record was deleted, `false` when it was unknown.
+ */
+delete(id: WorkspaceId): Promise<boolean>
+
+/**
+ * Archive one session durably. The session must exist (live or in session
+ * persistence); its workspace accounting — or lack of one — is irrelevant.
+ * An already archived id resolves without writing.
+ * @param sessionId - The session to archive.
+ * @returns resolution after durability.
+ */
+archiveSession(sessionId: SessionId): Promise<void>
+
+/**
+ * Resolve by canonical directory path without creating or mutating a
+ * workspace. A missing path rejects during `realpath`; an existing unowned
+ * directory returns `undefined`.
+ * @param path - Existing directory path in any spelling.
+ * @returns the workspace owning the canonical path, when one exists.
+ */
+async resolveByPath(path: string): Promise<Workspace | undefined>
+```
+
+Types: [SessionId](core.md)
+
+Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index a100469102..8986847d1e 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -3,7 +3,7 @@
 
 # Tool Schema Catalog
 
-Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
+Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page's generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.
 
 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).
 
diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml
index 769556da41..37dd601646 100644
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/docs/user/develop/framework/events.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 docs/user/develop/framework/events.md
-events.md: fcbdb5f39bf2078032affbc6469f7eecc795d3ba
-events.zh.md: 1979e0bc1dbb71e46f50a051dacee8ae3a1172a7
+events.md: c70150b4d9070063513021e420f253ff6d4e5de1
+events.zh.md: 813dc3631e0c776ad9c8763db65eebc3f2167578
diff --git a/docs/user/develop/framework/events.md b/docs/user/develop/framework/events.md
index fcbdb5f39b..c70150b4d9 100644
--- a/docs/user/develop/framework/events.md
+++ b/docs/user/develop/framework/events.md
@@ -101,7 +101,7 @@ declare module 'cordis' {
 
 ## Cordis events and session records
 
-Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated [event catalog](../../../cordis-catalog/events.md) records complete signatures and modes.
+Harness Cordis events use `namespace/action` names, including `agent/step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
 
 `turn/*`, `step/*`, `tool/call`, `tool/result`, and `compact/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
 
diff --git a/docs/user/develop/framework/events.zh.md b/docs/user/develop/framework/events.zh.md
index 1979e0bc1d..813dc3631e 100644
--- a/docs/user/develop/framework/events.zh.md
+++ b/docs/user/develop/framework/events.zh.md
@@ -101,7 +101,7 @@ declare module 'cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[Events 目录](../../../cordis-catalog/events.md)。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.md)上生成的 `cordis-surface` 区块。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compact/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 
diff --git a/docs/user/develop/framework/service.i18n.yaml b/docs/user/develop/framework/service.i18n.yaml
index ade6b8dc08..7cb2f4ff88 100644
--- a/docs/user/develop/framework/service.i18n.yaml
+++ b/docs/user/develop/framework/service.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 docs/user/develop/framework/service.md
-service.md: 1bf28cb3c7dfdfbd6d0babfa3b1688ac65eea01e
-service.zh.md: 78b9887a734b235bcff1d94a623e37cfeb2f41e3
+service.md: 040b1388cc431c30045e05f7d372ab5885bb3f9d
+service.zh.md: 0786b684c1688440a24cc729288835ad636f8ff7
diff --git a/docs/user/develop/framework/service.md b/docs/user/develop/framework/service.md
index 1bf28cb3c7..040b1388cc 100644
--- a/docs/user/develop/framework/service.md
+++ b/docs/user/develop/framework/service.md
@@ -140,7 +140,7 @@ This prevents a plugin from calling a service that no longer exists.
 
 ## Built-in Harness services
 
-The repository generates the service names, public methods, and source locations in the [service catalog](../../../cordis-catalog/services.md). Use that catalog and the service's TypeScript interface while developing a plugin; do not maintain a second static list.
+The repository generates the service names, public methods, and source locations into each service's [subsystem page](../../../subsystems/core.md). Use those generated regions and the service's TypeScript interface while developing a plugin; do not maintain a second static list.
 
 ## Next steps
 
diff --git a/docs/user/develop/framework/service.zh.md b/docs/user/develop/framework/service.zh.md
index 78b9887a73..0786b684c1 100644
--- a/docs/user/develop/framework/service.zh.md
+++ b/docs/user/develop/framework/service.zh.md
@@ -140,7 +140,7 @@ export function apply(ctx: Context) {
 
 ## Harness 内置服务
 
-仓库会自动生成[服务目录](../../../cordis-catalog/services.md)，其中包含服务名、公开方法和源码位置。开发插件时应以该目录和服务的 TypeScript 接口为准，不要维护另一份静态清单。
+服务名、公开方法和源码位置由仓库自动生成到各服务的[子系统页面](../../../subsystems/core.md)。开发插件时应以这些生成区块和服务接口的 TypeScript 类型为准，不要复制一份静态清单。
 
 ## 下一步
 
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 2f165e76e4..fb18353290 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: 2fdc60086bebc924089b5b8bd12f4b4456b1ead5
-README.zh.md: df0ba44ec5b010666737c0568bc5eeb220ff0d96
+README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
+README.zh.md: c190171513e17777ebaadda0d279487876a412b4
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 2fdc60086b..81bc441197 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -74,7 +74,7 @@ Within a step, exclusive calls form barriers; parallel-safe calls use a bounded
 ### What belongs to plugins
 
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
-- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result` pipeline; exact event signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
+- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result` pipeline; exact event signatures and modes live in the generated regions of [core.md](../../../docs/subsystems/core.md#cordis-surface) and [tools.md](../../../docs/subsystems/tools.md#cordis-surface)
 - Compaction: pressure on `agent/pre-step`; canonical overflow repair on `agent/request-error`
 - Model-request recovery: `dsh-llm-retry` records and waits exact-provider normal or unbounded backoff on `agent/request-error`, emits non-surface `llm/retry` status, then returns a retry action
 - Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index df0ba44ec5..c190171513 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -74,7 +74,7 @@ interface Config {
 ### 插件负责的内容
 
 超出「调用模型、运行工具、重复」的所有内容，都属于监听事件分类体系的插件：
-- 钩子与策略：相关的 `agent/*` 检查点，加上受守卫保护的 `tools/pre-execute` → `tools/execute` → `tools/post-execute` → 定义拥有的 `finalizeContent` → `tools/result` 流水线；确切事件签名与 mode 位于生成的[事件目录](../../../docs/cordis-catalog/events.md)
+- 钩子与策略：相关的 `agent/*` 检查点，加上受守卫保护的 `tools/pre-execute` → `tools/execute` → `tools/post-execute` → 定义拥有的 `finalizeContent` → `tools/result` 流水线；确切事件签名与 mode 位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 与 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块
 - 压缩（compaction）：在 `agent/pre-step` 上观测压力；在 `agent/request-error` 上进行规范的溢出修复
 - 模型请求恢复：`dsh-llm-retry` 在 `agent/request-error` 上记录并等待按确切提供方配置的 normal 或无界退避，发出不进入表层的 `llm/retry` 状态，然后返回重试动作
 - 沙箱、权限、计划模式：使用 `tools/pre-execute` 提供可扩展的拒绝／询问，使用 `tools.guard()` 提供单调拥有方策略，使用 `tools/post-execute` 处理结果决定，并使用 `tools/result` 进行最终观测
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 5c03669baf..4c6009d3b0 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: 2a69ab380eaad3929e27039582807037969eba64
-README.zh.md: 176f3f75cf0f6e3309b2f5d34afb4d562105608e
+README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
+README.zh.md: 8164829e18ddd89fd84c0c2b5e033fd69241b9aa
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 2a69ab380e..3a3bdf6a4b 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -46,7 +46,7 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age
 
 ### Live events
 
-`dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.
+`dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated region of [core.md](../../../docs/subsystems/core.md#cordis-surface); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.
 
 The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 176f3f75cf..8164829e18 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -46,7 +46,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 ### 实时事件
 
-`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 契约位于生成的 [Cordis 事件目录](../../../docs/cordis-catalog/events.md)；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
+`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 契约位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 的生成区块；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index c30b37e549..8b1e462166 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 07ee53006b390e5ad3979502b2f1aa24f5a6ce7a
-README.zh.md: d4a90de10b92a489f8f575b926d758b45d8f5051
+README.md: 00e007ee6064f485bf80dfda0227ab6e834f6414
+README.zh.md: 5f06fee5d50bc2c9dc333874a8354fbf19d5248b
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 07ee53006b..00e007ee60 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -30,7 +30,7 @@ Use the split lifecycle only when teardown must be ordered with another resource
 
 ### Live service events
 
-The store pairs announced creation with disposal, publishes post-commit append notifications with per-listener containment, and provides an awaited durability checkpoint. Exact signatures and scope behavior live in the generated [event catalog](../../../docs/cordis-catalog/events.md); payloads live in the [persistence catalog](../../../docs/persistence-catalog.md).
+The store pairs announced creation with disposal, publishes post-commit append notifications with per-listener containment, and provides an awaited durability checkpoint. Exact signatures and scope behavior live in the generated region of [session.md](../../../docs/subsystems/session.md#cordis-surface); payloads live in the [persistence catalog](../../../docs/persistence-catalog.md).
 
 ### Class: `Session`
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index d4a90de10b..5f06fee5d5 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -30,7 +30,7 @@
 
 ### 实时服务事件
 
-会话存储会将已通知的创建与释放配对，在提交后发布追加通知并逐个监听器收容失败，同时提供受等待的持久性检查点。确切签名和作用域行为见生成的[事件目录](../../../docs/cordis-catalog/events.md)；载荷见[持久化目录](../../../docs/persistence-catalog.md)。
+会话存储会将已通知的创建与释放配对，在提交后发布追加通知并逐个监听器收容失败，同时提供受等待的持久性检查点。确切签名和作用域行为见 [session.md](../../../docs/subsystems/session.md#cordis-surface) 的生成区块；载荷见[持久化目录](../../../docs/persistence-catalog.md)。
 
 ### 类：`Session`
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index 36f166dd86..c94d1722dc 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
-README.md: 23bc0e8177ad2a778df9522e254bfd5e03a9871f
-README.zh.md: b442239a50d539a8f079aa692c433d9defe57295
+README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
+README.zh.md: 5b9e2feaf82866a52cd8197ff5e800decdf3ee7e
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index 23bc0e8177..e98c45a882 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -23,7 +23,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem
 
 ### Live events
 
-`system-prompt/assemble` is authoritative; listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated [event catalog](../../../docs/cordis-catalog/events.md) owns signatures and dispatch contracts.
+`system-prompt/assemble` is authoritative; listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated region of [system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) owns signatures and dispatch contracts.
 
 ### Key types
 
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index b442239a50..5b9e2feaf8 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -23,7 +23,7 @@
 
 ### 实时事件
 
-`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。生成的[事件目录](../../../docs/cordis-catalog/events.md) 拥有签名与分发契约。
+`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发契约。
 
 ### 关键类型
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index e8157eed7e..b19e86ce84 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: fd5cb85540e42e62de28f96bf59890da9561f51e
-README.zh.md: 5911b25b1d77710077063a643a29e500e4da8e95
+README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
+README.zh.md: 796ee8e1aa8de88f979d825df5e0b4f39ab7bcf1
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index fd5cb85540..f3f25f908a 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -35,7 +35,7 @@ Cancellation is cooperative and quiescent. Every typed invocation supplies a cal
 
 ### Live events
 
-The live registry pipeline has three transformable waterfalls, then the definition-owned content finalizer, then the observe-only `tools/result` boundary; registry changes are deliberately unfiltered shared-state notifications. Exact signatures, dispatch modes, scope filtering, and failure-containment contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md), while the complete ordering is visualized in the generated [tool execution pipeline](../../../docs/tool-execution-pipeline.md). `tools/result` is live; the similarly named `tool/result` is the durable session event the agent loop appends afterwards.
+The live registry pipeline has three transformable waterfalls, then the definition-owned content finalizer, then the observe-only `tools/result` boundary; registry changes are deliberately unfiltered shared-state notifications. Exact signatures, dispatch modes, scope filtering, and failure-containment contracts live in the generated region of [tools.md](../../../docs/subsystems/tools.md#cordis-surface), while the complete ordering is visualized in the generated [tool execution pipeline](../../../docs/tool-execution-pipeline.md). `tools/result` is live; the similarly named `tool/result` is the durable session event the agent loop appends afterwards.
 
 ### Key types
 
@@ -56,7 +56,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 - `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
 - `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Canonical-result provenance belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
 - `tools/post-execute` may replace presentation content, replace the canonical value, block with feedback, or attach ordered contexts. A definition's optional `finalizeContent` then owns its last content-only invariant across normal results and outer pipeline failures; `tools/result` observes the immutable final outcome. Content replacement is not a confidentiality boundary: block or replace the value when programmatic consumers must not receive it.
-- Exact signatures and ordering live in the generated [event catalog](../../../docs/cordis-catalog/events.md) and [pipeline](../../../docs/tool-execution-pipeline.md).
+- Exact signatures and ordering live in the generated region of [tools.md](../../../docs/subsystems/tools.md#cordis-surface) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
 
 ### Typed tool parameter schemas
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 5911b25b1d..796ee8e1aa 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -35,7 +35,7 @@ tools:
 
 ### 实时事件
 
-实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发模式、作用域筛选和故障收容契约位于生成的 [Cordis 事件目录](../../../docs/cordis-catalog/events.md)，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
+实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发 mode、作用域筛选和故障收容契约位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
 
 ### 关键类型
 
@@ -56,7 +56,7 @@ tools:
 - `tools/pre-execute` 是可重排的允许／拒绝／询问门禁；`ctx.tools.guard()` 在其后添加单调的拥有方策略。
 - `tools/execute` 会环绕包装规范化后的规范分发，以支持超时、重试或指标采集。包装层只能替换操作信号；包装层生成的成功结果会根据已解析工具的输出声明进行规范化。规范结果的来源属于一个不可变分发 token，因此，来自其他调用或工具的缓存结果会根据当前声明重新验证。
 - `tools/post-execute` 可以替换呈现内容、替换规范值、通过反馈阻止，或附加有序上下文。随后，定义可选的 `finalizeContent` 会在普通结果和外层流水线失败中维护其最终、仅涉及内容的不变式；`tools/result` 观测不可变的最终结果。内容替换不是保密边界：当编程消费方不得接收某个值时，应阻止或替换该值。
-- 确切签名与顺序位于生成的[事件目录](../../../docs/cordis-catalog/events.md)和[流水线](../../../docs/tool-execution-pipeline.md)中。
+- 确切签名与顺序位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块和[流水线](../../../docs/tool-execution-pipeline.md)中。
 - MCP 服务器：每个服务器使用一个插件；发现工具后，使用服务器的 schema 调用 `ctx.tools.register()`。
 
 ### 类型化工具参数 schema
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index d9b5f0ebc0..d9b0010670 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: bf1dd1c1eb65146258cd64e450749845522e7057
-README.zh.md: f3fcc0c3794b972233dc418e93bdd80b1cc8570a
+README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
+README.zh.md: 97d7104f3c4c0beca408397f9cb1cead39b0a76e
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index bf1dd1c1eb..5c58fc476b 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -37,7 +37,7 @@ The mutation runs inside the backend's per-target lock either way, so an uncondi
 
 ## The `fs/*` policy events
 
-This package declares three events (see the generated [events catalog](../../../docs/cordis-catalog/events.md)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
+This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
 ## A provider seam, not the policy layer
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index f3fcc0c379..97d7104f3c 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -37,7 +37,7 @@
 
 ## `fs/*` 政策事件
 
-本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
 ## 提供方 seam，不是政策层
 
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index 6362a6d1e9..d8fbf8fc29 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/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/goal/goal/README.md
-README.md: fc2fd8791096bcc9077ef7972da86b0e07c6f18e
-README.zh.md: 311ec1d03436cc45bbea28df96e66579852058b0
+README.md: 98765a809820bcd4aeba31e1dd4ef6e92eb30760
+README.zh.md: dbc499104bac6cf09f9b1c871143da8781a8f082
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index fc2fd87910..98765a8098 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -17,7 +17,7 @@ Event-sourced same-session goal state. The service retains one current completio
 
 ## Service contract
 
-`ctx.goals` accepts only the exact live `Agent` instance registered under its id. `get()` returns a detached `GoalView`; mutations use a `GoalRef { id, revision }` compare-and-set fence and reject stale refs. The service exposes create, edit, pause, resume, complete, block, and clear verbs through the generated [service catalog](../../../docs/cordis-catalog/services.md). Creation default resolution is internal. `disarm()` is the lifecycle-only exception: it removes process-local continuation authority without writing a revision or emitting a mutation.
+`ctx.goals` accepts only the exact live `Agent` instance registered under its id. `get()` returns a detached `GoalView`; mutations use a `GoalRef { id, revision }` compare-and-set fence and reject stale refs. The service exposes create, edit, pause, resume, complete, block, and clear verbs through the generated region of [goal.md](../../../docs/subsystems/goal.md#cordis-surface). Creation default resolution is internal. `disarm()` is the lifecycle-only exception: it removes process-local continuation authority without writing a revision or emitting a mutation.
 
 At most one goal is current. Creation produces an active revision-one goal and arms it. A non-complete goal must be edited, transitioned, or cleared; a completed goal may be replaced by a globally fresh id. Edits retain phase, blocker reason, and activation. Pause, completion, blocking, and clear disarm activation. A block records a policy-owned lower-kebab-case code plus a normalized free-form explanation; provider limits, configured budgets, execution errors, and requests for human input all use this one durable phase rather than multiplying lifecycle states. Resume accepts a stopped phase or a disarmed active goal only while the configured round cap has remaining capacity; it clears any former blocker reason. An active armed goal rejects the redundant operation.
 
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index 311ec1d034..dbc499104b 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -17,7 +17,7 @@
 
 ## 服务契约
 
-`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更通过 `GoalRef { id, revision }` 比较并设置屏障，并拒绝陈旧引用。服务通过生成的[服务目录](../../../docs/cordis-catalog/services.md)公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更。
+`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回分离的 `GoalView`；变更通过 `GoalRef { id, revision }` 比较并设置限制，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发送变更事件。
 
 最多只有一个当前目标。创建操作会生成 revision 为 1、phase 为 active 的目标并启用续行。未完成的目标必须编辑、转换或清除；已完成目标可以由拥有全局未使用过的 id 的目标替换。编辑会保留 phase、blocker reason 与 activation。暂停、完成、阻塞和清除都会停用续行。阻塞会记录策略自有的 lower-kebab-case 代码和规范化的自由文本说明；提供方限制、配置预算、执行错误与请求人工输入都使用这一种持久 phase，不会扩增生命周期状态。只有配置的 Round 上限仍有剩余容量时，resume 才接受已停止 phase 或 phase 为 active 但已停用续行的目标；它会清除原 blocker reason。phase 为 active 且已启用续行的目标会拒绝冗余操作。
 
diff --git a/packages/interaction/user-approval/README.i18n.yaml b/packages/interaction/user-approval/README.i18n.yaml
index 36188334e7..2122c0d101 100644
--- a/packages/interaction/user-approval/README.i18n.yaml
+++ b/packages/interaction/user-approval/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/interaction/user-approval/README.md
-README.md: 7b87a75d1c7c43874c484bc11f8deed45cb523ce
-README.zh.md: 3c02f8d673a62c3ee954da26f6341b433032a88c
+README.md: 0cf5d458863194e29f8c84168a6f089baabbf3d2
+README.zh.md: a48e4ff4650fbd90744c9d7c41878b6e0487127c
diff --git a/packages/interaction/user-approval/README.md b/packages/interaction/user-approval/README.md
index 7b87a75d1c..0cf5d45886 100644
--- a/packages/interaction/user-approval/README.md
+++ b/packages/interaction/user-approval/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Channel-neutral one-shot approval seam. `ctx.approval.request(req)` returns `allowed-once`, `rejected`, `cancelled`, or `unavailable`; missing or failing answerers fail closed, and a grant applies only to the requested action. Exact event signatures live in the generated [Cordis catalog](../../../docs/cordis-catalog/events.md).
+Channel-neutral one-shot approval seam. `ctx.approval.request(req)` returns `allowed-once`, `rejected`, `cancelled`, or `unavailable`; missing or failing answerers fail closed, and a grant applies only to the requested action. Exact event signatures live in the generated region of [approval.md](../../../docs/subsystems/approval.md#cordis-surface).
 
 Each request must belong to an open agent turn. The service appends a paired `approval/asked` and `approval/decided` audit record, while the model sees only the resulting logged tool outcome. An aborted request resolves `cancelled`; an audit append that fails before commit rejects rather than returning an unlogged decision.
 
diff --git a/packages/interaction/user-approval/README.zh.md b/packages/interaction/user-approval/README.zh.md
index 3c02f8d673..a48e4ff465 100644
--- a/packages/interaction/user-approval/README.zh.md
+++ b/packages/interaction/user-approval/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-与通道无关的一次性审批 seam。`ctx.approval.request(req)` 返回 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`；应答者缺失或失败时会以拒绝方式关闭，授权也只适用于所请求的操作。确切事件签名见生成的 [Cordis 目录](../../../docs/cordis-catalog/events.md)。
+与通道无关的一次性审批 seam。`ctx.approval.request(req)` 返回 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`；应答者缺失或失败时会以拒绝方式关闭，授权也只适用于所请求的操作。确切事件签名见 [approval.md](../../../docs/subsystems/approval.md#cordis-surface) 的生成区块。
 
 每个请求都必须属于一个尚未结束的 agent（智能体）轮次。服务会追加一对 `approval/asked` 与 `approval/decided` 审计记录，而模型只会看到由此产生且已写入日志的工具结果。已中止的请求会解析为 `cancelled`；如果审计记录的追加在提交前失败，Promise 会被拒绝，而不会返回一项未记录的决定。
 
diff --git a/packages/self-modification/tool-cordis/README.i18n.yaml b/packages/self-modification/tool-cordis/README.i18n.yaml
index c25dda28e3..ef1f441711 100644
--- a/packages/self-modification/tool-cordis/README.i18n.yaml
+++ b/packages/self-modification/tool-cordis/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/self-modification/tool-cordis/README.md
-README.md: 9986310160c2b56126155a4c3ef84d66018d31c2
-README.zh.md: d955306e1e5d4154f58c771704782ece44a15c99
+README.md: f2a65043a1d2f74553e98caf59ed3d38b5a70b7c
+README.zh.md: 66742094992d219ccfbd60b935dcd10e48cb12b8
diff --git a/packages/self-modification/tool-cordis/README.md b/packages/self-modification/tool-cordis/README.md
index 9986310160..f2a65043a1 100644
--- a/packages/self-modification/tool-cordis/README.md
+++ b/packages/self-modification/tool-cordis/README.md
@@ -28,7 +28,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 ## The generated API catalog
 
-`src/api-catalog.ts` is generated from the same Typert `FaceModel` projection as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `scripts/gen-cordis-api.ts` is a compatibility entry point for that unified projection, not a second collector. `cordis_inspect` intersects the committed catalog with the live service store at call time; it has no runtime Typert dependency. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
+`src/api-catalog.ts` is generated from the same Typert `FaceModel` projection as the [subsystem pages' generated regions](../../../docs/subsystems/core.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `scripts/gen-cordis-api.ts` is a compatibility entry point for that unified projection, not a second collector. `cordis_inspect` intersects the committed catalog with the live service store at call time; it has no runtime Typert dependency. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
 
 ## Rendering
 
diff --git a/packages/self-modification/tool-cordis/README.zh.md b/packages/self-modification/tool-cordis/README.zh.md
index d955306e1e..6674209499 100644
--- a/packages/self-modification/tool-cordis/README.zh.md
+++ b/packages/self-modification/tool-cordis/README.zh.md
@@ -28,7 +28,7 @@
 
 ## 生成的 API 目录
 
-`src/api-catalog.ts` 与 [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) 由同一个 Typert `FaceModel` 投影生成，并由 `pnpm run verify-cordis-api`（位于 `doc-sync` 中）实施新鲜度门禁，绝不可手工编辑。`scripts/gen-cordis-api.ts` 是该统一投影的兼容入口，而非第二套收集器。`cordis_inspect` 在调用时把已提交的目录与存活服务 store 取交集；它在运行时不依赖 Typert。宽泛的 `api`／`events` 报告只渲染摘要与签名；精确 `name` 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会高声失败。
+`src/api-catalog.ts` 与[子系统页面的生成区块](../../../docs/subsystems/core.md)由同一个 Typert `FaceModel` 投影生成，并由 `pnpm run verify-cordis-api`（位于 `doc-sync` 中）实施新鲜度门禁，绝不可手工编辑。`scripts/gen-cordis-api.ts` 是该统一投影的兼容入口，而非第二套收集器。`cordis_inspect` 在调用时把已提交的目录与存活服务 store 取交集；它在运行时不依赖 Typert。宽泛的 `api`／`events` 报告只渲染摘要与签名；精确 `name` 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会高声失败。
 
 ## 渲染
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index d62739acdd..1950c255cb 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -694,32 +694,61 @@ function renderRuntimeApi(
   lines.push(']', '')
   return lines.join('\n')
 }
-/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
-function typeLinks(signature: string, linkedTypePages: Readonly<Record<string, string>>): string {
+/** Opening region delimiter; injected content lives between the pair and the page owns everything outside. */
+export const REGION_BEGIN = '<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->'
+/** Closing region delimiter matching {@link REGION_BEGIN}. */
+export const REGION_END = '<!-- END GENERATED cordis-surface -->'
+
+/**
+ * Render the cross-link "Types:" line for a signature relative to one
+ * subsystems page, or '' if none apply. A type whose primary page IS the
+ * rendering page would link as a fragmentless self-link readers already sit
+ * on, so it is dropped instead.
+ */
+function typeLinks(signature: string, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string {
   const seen = new Set<string>()
   for (const name of Object.keys(linkedTypePages)) {
     if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
   }
-  if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../subsystems/${linkedTypePages[n]})`)
+  const links = [...seen].sort()
+    .filter(name => linkedTypePages[name] !== onPage)
+    .map(name => `[${name}](${linkedTypePages[name]})`)
+  if (links.length === 0) return ''
   return `Types: ${links.join(' · ')}`
 }
 
-/** Render one harness event entry. */
-function renderEvent(e: EventEntry, linkedTypePages: Readonly<Record<string, string>>): string[] {
-  const out = [`### \`${e.name}\` — ${e.mode}`, '']
+/**
+ * GitHub's heading-slug algorithm (lowercase; drop everything but letters,
+ * numbers, spaces, hyphens; spaces become hyphens). Region headings carry
+ * backticks and em-dashes, which VitePress slugifies differently, so each
+ * generated heading is preceded by an explicit `<a id>` carrying this slug —
+ * the historical flat-catalog anchor — making `#ctx<key>--<class>` fragments
+ * resolve identically on GitHub and the published site.
+ */
+function githubSlug(heading: string): string {
+  return heading.toLowerCase().replace(/[^\p{L}\p{N} -]/gu, '').replaceAll(' ', '-')
+}
+
+/** The explicit-anchor line emitted before one generated heading. */
+function anchorFor(headingText: string): string[] {
+  return [`<a id="${githubSlug(headingText)}"></a>`, '']
+}
+
+/** Render one harness event entry onto its owning page, nested under its scope heading. */
+function renderEvent(e: EventEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
+  const out = [...anchorFor(`${e.name} — ${e.mode}`), `#### \`${e.name}\` — ${e.mode}`, '']
   if (e.doc) out.push(e.doc, '')
   out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
-  const links = typeLinks(e.signature, linkedTypePages)
+  const links = typeLinks(e.signature, onPage, linkedTypePages)
   if (links) out.push(links, '')
   out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
   return out
 }
 
-/** Render one harness service entry. */
-function renderService(s: ServiceEntry, linkedTypePages: Readonly<Record<string, string>>): string[] {
+/** Render one harness service entry onto its owning page. */
+function renderService(s: ServiceEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
   const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  const out = [...anchorFor(`ctx.${s.key} — ${s.type}${kind}`), `### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
     const declarations = s.methods.flatMap((method, index) => [
@@ -728,7 +757,7 @@ function renderService(s: ServiceEntry, linkedTypePages: Readonly<Record<string,
       method.signature,
     ])
     out.push('```' + FENCE, ...declarations, '```', '')
-    const links = typeLinks(s.methods.map(method => method.signature).join('\n'), linkedTypePages)
+    const links = typeLinks(s.methods.map(method => method.signature).join('\n'), onPage, linkedTypePages)
     if (links) out.push(links, '')
   }
   out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
@@ -746,36 +775,62 @@ const BANNER = [
 const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
 
 /**
- * Render the events catalog deterministically.
- * @param events - validated event entries to render.
- * @param policy - type links and inherited events supplied by the caller.
+ * Render one page's generated `cordis-surface` region: the services mapped to
+ * the page, then the event scopes mapped to it, markers included. Pure and
+ * deterministic given sorted inputs; identical bytes land in both pair sides.
+ * @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.
+ * @param services - validated services mapped to this page.
+ * @param events - validated events whose scopes map to this page.
+ * @param policy - type links supplied by the caller.
+ * @returns the complete marker-delimited region text.
+ */
+export function renderPageRegion(page: string, services: ServiceEntry[], events: EventEntry[], policy: CordisCatalogPolicy): string {
+  const lines: string[] = [
+    REGION_BEGIN,
+    '',
+    '<a id="cordis-surface"></a>',
+    '',
+    '## Cordis surface',
+    '',
+    'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
+    '',
+  ]
+  for (const s of services) lines.push(...renderService(s, page, policy.linkedTypePages))
+  const scopes = [...new Set(events.map(e => e.scope))].sort()
+  for (const scope of scopes) {
+    lines.push(...anchorFor(`${scope}/* events`), `### \`${scope}/*\` events`, '')
+    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
+      lines.push(...renderEvent(e, page, policy.linkedTypePages))
+    }
+  }
+  while (lines.at(-1) === '') lines.pop()
+  lines.push(REGION_END)
+  return lines.join('\n')
+}
+
+/**
+ * Render the inherited (pinned vendor) tier as its own generated page.
+ * @param policy - inherited events and services supplied by the caller.
  * @returns the complete generated Markdown document.
  */
-export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy): string {
+export function renderInheritedPage(policy: CordisCatalogPolicy): string {
   const lines: string[] = [
     ...BANNER,
-    '# Cordis Events Catalog',
+    '# Inherited Cordis Surface',
     '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
+    'The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).',
     '',
     GATE_NOTICE,
     '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
-    '',
-    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).',
+    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
     '',
   ]
-  const scopes = [...new Set(events.map(e => e.scope))].sort()
-  for (const scope of scopes) {
-    lines.push(`## \`${scope}/*\``, '')
-    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(...renderEvent(e, policy.linkedTypePages))
-    }
+  for (const s of policy.inheritedServices) {
+    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
   }
   lines.push(
-    '## Inherited events (cordis core + loader/hmr/timer)',
     '',
-    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
+    '## Inherited events (cordis core + loader/hmr/timer)',
     '',
   )
   for (const e of policy.inheritedEvents) {
@@ -784,35 +839,3 @@ export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy):
   lines.push('')
   return lines.join('\n')
 }
-
-/**
- * Render the services catalog deterministically.
- * @param services - validated service entries to render.
- * @param policy - type links and inherited services supplied by the caller.
- * @returns the complete generated Markdown document.
- */
-export function renderServices(services: ServiceEntry[], policy: CordisCatalogPolicy): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Services Catalog',
-    '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
-    '',
-  ]
-  for (const s of services) lines.push(...renderService(s, policy.linkedTypePages))
-  lines.push(
-    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
-    '',
-    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const s of policy.inheritedServices) {
-    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index 1b6589b6cf..bde52505dc 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -10,8 +10,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import {
   collectEvents as collectEventsWithPolicy,
   collectServices as collectServicesWithPolicy,
-  renderEvents as renderEventsWithPolicy,
-  renderServices as renderServicesWithPolicy,
+  renderPageRegion,
 } from '../src/cordis-catalog.ts'
 import type {
   CordisCatalogPolicy,
@@ -35,12 +34,12 @@ function collectServices(root: string): ServiceEntry[] {
   return collectServicesWithPolicy(root, TEST_POLICY)
 }
 
-function renderEvents(events: EventEntry[]): string {
-  return renderEventsWithPolicy(events, TEST_POLICY)
+function renderEvents(events: EventEntry[], onPage = 'bash.md'): string {
+  return renderPageRegion(onPage, [], events, TEST_POLICY)
 }
 
-function renderServices(services: ServiceEntry[]): string {
-  return renderServicesWithPolicy(services, TEST_POLICY)
+function renderServices(services: ServiceEntry[], onPage = 'bash.md'): string {
+  return renderPageRegion(onPage, services, [], TEST_POLICY)
 }
 
 const TYPE_FIXTURES = [
@@ -155,7 +154,8 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
       '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
-    expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
+    expect(renderEvents(events)).toContain('Types: [SessionEvent](core.md)')
+    expect(renderEvents(events, 'core.md')).not.toContain('Types: [SessionEvent]')
     expect(renderEvents(events)).not.toContain('[PresetSpec]')
   })
 
diff --git a/packages/typert/generator/tests/cordis-catalog.spec.ts b/packages/typert/generator/tests/cordis-catalog.spec.ts
index 644bb28de2..9474c15145 100644
--- a/packages/typert/generator/tests/cordis-catalog.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog.spec.ts
@@ -3,10 +3,10 @@ import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
   projectCordisCatalog,
-  renderEvents,
-  renderServices,
+  renderInheritedPage,
+  renderPageRegion,
 } from '../src/cordis-catalog.ts'
-import { CORDIS_CATALOG_POLICY } from '../../../../scripts/gen-cordis-catalog.ts'
+import { CORDIS_CATALOG_POLICY, EVENT_SCOPE_PAGE, REGION_BEGIN, REGION_END, SERVICE_PAGE } from '../../../../scripts/gen-cordis-catalog.ts'
 
 const workspaceRoot = resolve(import.meta.dirname, '../../../..')
 
@@ -15,8 +15,22 @@ describe('Typert-backed Cordis catalog', () => {
     const { projector, model } = projectCordisCatalog(workspaceRoot, CORDIS_CATALOG_POLICY)
     const expected = (path: string): string => readFileSync(join(workspaceRoot, path), 'utf8')
 
-    expect(renderEvents([...model.events], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/events.md'))
-    expect(renderServices([...model.services], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/services.md'))
+    expect(renderInheritedPage(CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-api/inherited.md'))
+    for (const page of [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])].sort()) {
+      const region = renderPageRegion(
+        page,
+        [...model.services].filter(s => SERVICE_PAGE[s.key] === page),
+        [...model.events].filter(e => EVENT_SCOPE_PAGE[e.scope] === page),
+        CORDIS_CATALOG_POLICY,
+      )
+      for (const side of [page, page.replace(/\.md$/, '.zh.md')]) {
+        const committed = expected(`docs/subsystems/${side}`)
+        const begin = committed.indexOf(REGION_BEGIN)
+        const end = committed.indexOf(REGION_END)
+        expect(begin, `docs/subsystems/${side} carries the region`).toBeGreaterThanOrEqual(0)
+        expect(committed.slice(begin, end + REGION_END.length)).toBe(region)
+      }
+    }
     expect(projector.renderRuntimeApi(model)).toBe(
       expected('packages/self-modification/tool-cordis/src/api-catalog.ts'),
     )
diff --git a/scripts/cordis-core-api.spec.ts b/scripts/cordis-core-api.spec.ts
index d35899553c..8aef4041a1 100644
--- a/scripts/cordis-core-api.spec.ts
+++ b/scripts/cordis-core-api.spec.ts
@@ -21,13 +21,13 @@ describe('Cordis core API generation', () => {
   it('renders the five detailed pages from pinned vendor declarations', () => {
     const pages = renderCordisCoreApiPages()
     expect([...pages.keys()]).toEqual(CORDIS_CORE_API_PAGES.map(page => page.out))
-    expect(pages.get('docs/cordis-catalog/core/context.md')).toContain('### ctx.extend(meta?)')
-    expect(pages.get('docs/cordis-catalog/core/events.md')).toContain('## DispatchMode')
-    expect(pages.get('docs/cordis-catalog/core/fiber.md')).toContain('## EffectMeta')
-    expect(pages.get('docs/cordis-catalog/core/registry.md')).toContain('## Plugin')
-    expect(pages.get('docs/cordis-catalog/core/service.md')).toContain('### Service.resolveConfig')
+    expect(pages.get('docs/cordis-api/context.md')).toContain('### ctx.extend(meta?)')
+    expect(pages.get('docs/cordis-api/events.md')).toContain('## DispatchMode')
+    expect(pages.get('docs/cordis-api/fiber.md')).toContain('## EffectMeta')
+    expect(pages.get('docs/cordis-api/registry.md')).toContain('## Plugin')
+    expect(pages.get('docs/cordis-api/service.md')).toContain('### Service.resolveConfig')
 
-    const fiber = pages.get('docs/cordis-catalog/core/fiber.md') ?? ''
+    const fiber = pages.get('docs/cordis-api/fiber.md') ?? ''
     expect(fiber).toContain('```\n\nRegister a cleanup-aware effect on this fiber.')
     expect(fiber).toContain('- `execute` — the effect body; see `Effect` for accepted shapes.')
     expect(fiber).toContain('**Returns** a disposer that tears the effect down and settles once done.')
@@ -39,7 +39,7 @@ describe('Cordis core API generation', () => {
     mkdirSync(join(root, 'vendor/cordis/src'), { recursive: true })
     writeFileSync(join(root, 'vendor/cordis/src/service.ts'), 'export class Service {\n  run(): string { return "ok" }\n}\n')
     const page: CordisCoreApiPage = {
-      out: 'docs/cordis-catalog/core/service.md',
+      out: 'docs/cordis-api/service.md',
       title: 'Service',
       intro: 'Service API.',
       sections: [{ kind: 'class', file: 'vendor/cordis/src/service.ts', symbol: 'Service' }],
diff --git a/scripts/cordis-core-api.ts b/scripts/cordis-core-api.ts
index a2400fdb54..a32c1ce8fa 100644
--- a/scripts/cordis-core-api.ts
+++ b/scripts/cordis-core-api.ts
@@ -26,7 +26,7 @@ export interface CordisCoreApiPage {
 /** Explicit editorial grouping for the pinned Cordis core surface. */
 export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
   {
-    out: 'docs/cordis-catalog/core/context.md',
+    out: 'docs/cordis-api/context.md',
     title: 'Context',
     intro: 'The context is the core Cordis object: every service, event, and lifecycle API is reached through `ctx`. Event methods are documented on [Events](events.md), effects and the current fiber on [Fiber](fiber.md), and plugin loading on [Registry](registry.md).',
     sections: [
@@ -35,9 +35,9 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/events.md',
+    out: 'docs/cordis-api/events.md',
     title: 'Events',
-    intro: 'The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated separately in the [Cordis events catalog](../events.md).',
+    intro: 'The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated into each owning [subsystem page](../subsystems/core.md).',
     sections: [
       { kind: 'context-merge', file: 'vendor/cordis/src/events.ts' },
       { kind: 'decl', file: 'vendor/cordis/src/events.ts', symbol: 'EventOptions' },
@@ -45,7 +45,7 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/fiber.md',
+    out: 'docs/cordis-api/fiber.md',
     title: 'Fiber',
     intro: 'A fiber is one loaded plugin instance: its lifecycle state, validated config, and registered effects. `ctx.fiber` is the current fiber, and `ctx.effect()` delegates to it.',
     sections: [
@@ -59,7 +59,7 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/registry.md',
+    out: 'docs/cordis-api/registry.md',
     title: 'Registry',
     intro: 'Plugin loading and dependency injection.',
     sections: [
@@ -69,7 +69,7 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/service.md',
+    out: 'docs/cordis-api/service.md',
     title: 'Service',
     intro: 'The base class for context services. A subclass loaded as a plugin registers itself as `ctx.<name>`.',
     sections: [
@@ -357,7 +357,7 @@ function declarationPaste(ctx: RenderContext, rel: string, symbol: string): { do
 
 function sourceLink(source: string): string {
   const [file, line] = source.split(':')
-  return `[Source](../../../${file}${line === undefined ? '' : `#L${line}`})`
+  return `[Source](../../${file}${line === undefined ? '' : `#L${line}`})`
 }
 
 function unlink(text: string): string {
diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index e414b572d3..0111d1d042 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -1,7 +1,39 @@
-/** Locate the Cordis module merge used by the vendored core API projector. */
+/**
+ * AST helpers shared by the Cordis generators: locate the Cordis module merge
+ * in a source file and enumerate the `interface Context` keys it declares.
+ * The vendored core API projector consumes the merge body; the per-subsystem
+ * region generator's exhaustiveness backstop consumes the key scan.
+ */
 
+import { globSync, readFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 
+/**
+ * Parse every file matching `pattern` (repo-relative, sorted, `/`-normalized)
+ * that textually mentions `interface Context`, yielding each file's cordis
+ * module-merge body. Files without a merge are skipped.
+ * @param scanRoot - Repository root the pattern is resolved against.
+ * @param pattern - Glob selecting the TypeScript files to scan.
+ * @returns One entry per file with a cordis module merge, in path order.
+ */
+export function contextMergeFiles(
+  scanRoot: string,
+  pattern: string,
+): { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] {
+  const out: { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] = []
+  for (const rel of globSync(pattern, { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!text.includes('interface Context')) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    out.push({ rel, sf, text, body })
+  }
+  return out
+}
+
 /** The body of the cordis module merge in `sf`: `declare module 'cordis'`
  * (harness packages) or `declare module './context.ts'` (vendor core), or
  * null when the file has neither. */
@@ -13,3 +45,22 @@ export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
   }
   return null
 }
+
+/**
+ * Every `key: Type` property a `declare module 'cordis'` Context merge
+ * declares in one module body.
+ * @param body - The cordis module augmentation block.
+ * @param sf - Owning source file (for text extraction).
+ * @returns key → declared type-name text, in declaration order.
+ */
+export function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<string, string> {
+  const keyToType = new Map<string, string>()
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
+    for (const member of stmt.members) {
+      if (!ts.isPropertySignature(member) || !member.type) continue
+      keyToType.set(member.name.getText(sf), member.type.getText(sf))
+    }
+  }
+  return keyToType
+}
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index ebceec916b..a79ffdd47f 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '# Plugin Config Catalog',
     '',
-    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
     '',
     'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
     '',
diff --git a/scripts/gen-cordis-catalog-record.spec.ts b/scripts/gen-cordis-catalog-record.spec.ts
new file mode 100644
index 0000000000..73720e8be8
--- /dev/null
+++ b/scripts/gen-cordis-catalog-record.spec.ts
@@ -0,0 +1,144 @@
+/**
+ * Negative-path coverage for the guarded pair auto-record
+ * (`maybeRecordPair`): the safety property is that regeneration re-records a
+ * pair's `.i18n.yaml` ONLY for a region-confined write over a well-formed,
+ * previously-consistent record — every other state is left for the pairing
+ * gate to report.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { maybeRecordPair, REGION_BEGIN, REGION_END, spliceRegion } from './gen-cordis-catalog.ts'
+import { blobHash, renderPairMeta } from './translation-pairing.ts'
+
+const PAGE = 'docs/subsystems/fix.md'
+const ZH = 'docs/subsystems/fix.zh.md'
+const META = 'docs/subsystems/fix.i18n.yaml'
+
+function page(prose: string, region: string): string {
+  return `# Fix\n\n${prose}\n\n${REGION_BEGIN}\n${region}\n${REGION_END}\n`
+}
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+/** Lay out a pair on disk and return { root, before } for a regeneration that already wrote `current`. */
+function setup(options: {
+  beforeEn: string
+  beforeZh: string
+  currentEn: string
+  currentZh: string
+  meta?: string | null
+  omitZhSnapshot?: boolean
+}): { root: string; before: Map<string, Buffer> } {
+  const root = mkdtempSync(join(tmpdir(), 'record-guard-'))
+  roots.push(root)
+  mkdirSync(join(root, 'docs/subsystems'), { recursive: true })
+  writeFileSync(join(root, PAGE), options.currentEn)
+  writeFileSync(join(root, ZH), options.currentZh)
+  const meta = options.meta === undefined
+    ? renderPairMeta(PAGE, blobHash(Buffer.from(options.beforeEn)), ZH, blobHash(Buffer.from(options.beforeZh)))
+    : options.meta
+  if (meta !== null) writeFileSync(join(root, META), meta)
+  const before = new Map<string, Buffer>([[PAGE, Buffer.from(options.beforeEn)]])
+  if (!options.omitZhSnapshot) before.set(ZH, Buffer.from(options.beforeZh))
+  return { root, before }
+}
+
+describe('maybeRecordPair', () => {
+  const beforeEn = page('prose.', 'old region')
+  const beforeZh = page('散文。', 'old region')
+  const currentEn = page('prose.', 'new region')
+  const currentZh = page('散文。', 'new region')
+
+  it('re-records a region-confined write over a consistent record', () => {
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(true)
+    expect(readFileSync(join(root, META), 'utf8'))
+      .toBe(renderPairMeta(PAGE, blobHash(Buffer.from(currentEn)), ZH, blobHash(Buffer.from(currentZh))))
+  })
+
+  it('refuses when the pair was already out of sync before the run', () => {
+    const stale = renderPairMeta(PAGE, blobHash(Buffer.from('drifted long ago\n')), ZH, blobHash(Buffer.from(beforeZh)))
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: stale })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+    expect(readFileSync(join(root, META), 'utf8')).toBe(stale)
+  })
+
+  it('refuses a malformed record even when its hashes are current', () => {
+    // A renamed key with preserved hashes must stay the pairing gate's error,
+    // never become valid through regeneration.
+    const renamedKeys = [
+      '# comment',
+      `fixXmd: ${blobHash(Buffer.from(beforeEn))}`,
+      `fix.zh.md: ${blobHash(Buffer.from(beforeZh))}`,
+      '',
+    ].join('\n')
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: renamedKeys })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+    expect(readFileSync(join(root, META), 'utf8')).toBe(renamedKeys)
+  })
+
+  it('refuses a record with extra entries', () => {
+    const extra = renderPairMeta(PAGE, blobHash(Buffer.from(beforeEn)), ZH, blobHash(Buffer.from(beforeZh)))
+      + `other.md: ${blobHash(Buffer.from(beforeEn))}\n`
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: extra })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+
+  it('refuses a record with a duplicated expected key', () => {
+    // Map#set would collapse the duplicate back to size 2; the parser must
+    // reject the repeat instead of letting the guard accept the record.
+    const duplicated = [
+      `fix.md: ${blobHash(Buffer.from(beforeEn))}`,
+      `fix.md: ${blobHash(Buffer.from(beforeEn))}`,
+      `fix.zh.md: ${blobHash(Buffer.from(beforeZh))}`,
+      '',
+    ].join('\n')
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: duplicated })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+    expect(readFileSync(join(root, META), 'utf8')).toBe(duplicated)
+  })
+
+  it('refuses when prose drifted alongside the region write', () => {
+    const proseDrift = page('prose, edited by a human.', 'new region')
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn: proseDrift, currentZh })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+
+  it('refuses a brand-new pair with no record', () => {
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: null })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+
+  it('refuses when a side has no pre-write snapshot', () => {
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, omitZhSnapshot: true })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+})
+
+describe('spliceRegion', () => {
+  it('replaces exactly the cordis-surface region', () => {
+    const doc = `# T\n\nprose\n\n${REGION_BEGIN}\nold\n${REGION_END}\ntail\n`
+    expect(spliceRegion(doc, `${REGION_BEGIN}\nnew\n${REGION_END}`))
+      .toBe(`# T\n\nprose\n\n${REGION_BEGIN}\nnew\n${REGION_END}\ntail\n`)
+  })
+
+  it('fails loud on a page carrying only some other generator\'s region', () => {
+    // Another generator's markers satisfy the generic region grammar but must
+    // never be overwritten by THIS generator's splice.
+    const foreign = '# T\n\n<!-- BEGIN GENERATED other-surface (other-gen.ts) — do not edit between markers -->\ntheirs\n<!-- END GENERATED other-surface -->\n'
+    expect(() => spliceRegion(foreign, `${REGION_BEGIN}\nnew\n${REGION_END}`))
+      .toThrow('expected exactly 1 cordis-surface region, found 0 BEGIN/0 END')
+  })
+
+  it('fails loud on duplicate cordis-surface markers', () => {
+    const doubled = `${REGION_BEGIN}\na\n${REGION_END}\n${REGION_BEGIN}\nb\n${REGION_END}\n`
+    expect(() => spliceRegion(doubled, `${REGION_BEGIN}\nnew\n${REGION_END}`))
+      .toThrow('found 2 BEGIN/2 END')
+  })
+})
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 3cc277152e..120904d4b5 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,24 +1,156 @@
 /**
- * Generate committed Cordis artifacts from the Typert catalog projector and
- * the independent vendored-core projector.
+ * Generate the per-subsystem Cordis service/event reference regions from the
+ * Typert catalog projection. Every harness `ctx.<key>` service and event scope
+ * maps to exactly one `docs/subsystems/` page through the curated tables below;
+ * the generator injects each page's surface between its GENERATED markers —
+ * byte-identically into both language sides of the pair — and re-records a
+ * pair's `.i18n.yaml` only when nothing outside the region changed. The
+ * projection enforces event modes, JSDoc parameter/return completeness, and
+ * signature type-link coverage; the inherited (vendor) tier renders to
+ * `docs/cordis-api/inherited.md`. `--check` verifies every generated artifact.
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import {
   projectCordisCatalog,
-  renderEvents,
-  renderServices,
+  renderInheritedPage,
+  renderPageRegion,
+  REGION_BEGIN,
+  REGION_END,
 } from '@deepseek-ai/dsh-typert-generator'
 import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
+import { contextKeyMap, contextMergeFiles } from './cordis-walk.ts'
+import {
+  blobHash,
+  parsePairMeta,
+  partitionGeneratedRegions,
+  renderPairMeta,
+} from './translation-pairing.ts'
 
 const root = resolve(import.meta.dirname, '..')
-const OUT_EVENTS = 'docs/cordis-catalog/events.md'
-const OUT_SERVICES = 'docs/cordis-catalog/services.md'
+const SUBSYSTEMS_DIR = 'docs/subsystems'
+const OUT_INHERITED = 'docs/cordis-api/inherited.md'
 const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** One primary subsystems page per project type used by a generated signature. */
+export { REGION_BEGIN, REGION_END }
+
+/**
+ * The owning subsystems page for every harness `ctx.<key>` service the
+ * projection discovers. Fail-closed both ways: a discovered key absent here
+ * and an entry whose key the projection no longer discovers are both hard
+ * errors, so the partition can never silently drift from the service surface.
+ */
+export const SERVICE_PAGE: Record<string, string> = {
+  agentLoop: 'core.md',
+  agents: 'core.md',
+  approval: 'approval.md',
+  bash: 'bash.md',
+  bashEnv: 'bash.md',
+  clientModuleHost: 'client-modules.md',
+  codeRuntime: 'code-runtime.md',
+  commands: 'commands.md',
+  compact: 'compaction.md',
+  credentials: 'credentials.md',
+  directoryPicker: 'workspace.md',
+  e2b: 'subprocess.md',
+  fs: 'filesystem.md',
+  goals: 'goal.md',
+  httpServer: 'http-server.md',
+  invariants: 'invariants.md',
+  llm: 'llm-streaming.md',
+  permission: 'permission.md',
+  planMode: 'plan.md',
+  pty: 'pty.md',
+  sandbox: 'sandbox.md',
+  sandboxPolicy: 'sandbox.md',
+  sessionPersistence: 'persistence.md',
+  sessionQuery: 'session-query.md',
+  sessionReferences: 'session-reference.md',
+  sessionProjectionCache: 'session-projection.md',
+  sessionProjections: 'session-projection.md',
+  sessions: 'session.md',
+  settings: 'settings.md',
+  sessionTitle: 'session-title.md',
+  skills: 'skills.md',
+  spillStore: 'spill.md',
+  storage: 'storage.md',
+  storageDomain: 'storage.md',
+  subagents: 'subagent.md',
+  subprocess: 'subprocess.md',
+  systemPrompt: 'system-prompt.md',
+  tasks: 'tasks.md',
+  telemetry: 'telemetry.md',
+  tokenMeter: 'token-meter.md',
+  toolResultPrune: 'compaction.md',
+  tools: 'tools.md',
+  typert: 'typert.md',
+  typertGateway: 'typert.md',
+  userInteraction: 'user-interaction.md',
+  web: 'web.md',
+  workflows: 'workflow.md',
+  workspace: 'workspace.md',
+}
+
+/**
+ * Context keys declared in `interface Context` merges that the rendering
+ * projection cannot see, each with the reason and its documentation owner.
+ * The scan that enforces this list reads EVERY `declare module 'cordis'`
+ * Context merge under `packages/x/x/src/*.ts` — not only root `index.ts`
+ * files with a same-named service class — so a new service can never silently
+ * join this blind spot: it either enters {@link SERVICE_PAGE} or names itself
+ * here.
+ * TODO(cordis-catalog-interface-services): the interface-typed and
+ * non-index-declared entries would all render once the projection resolves a
+ * Context key through its declaring file's imports to the class declaration.
+ */
+export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
+  agent: 'not a service: the DX accessor field on Agent.ctx (root accessor defaulting to undefined) — docs/subsystems/core.md owns the Agent handle',
+  configuredAgentIdentities: 'not a service: launcher-provided boot-context value (ConfiguredAgentIdentities | undefined) — packages/core/agent-loop/README.md owns the launcher contract',
+  launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns the launcher contract',
+  dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
+  headlessIo: 'not a service: launcher-provided root accessor value (HeadlessIo | undefined) for the headless bundle runner — packages/bundle/headless/README.md owns the launcher contract',
+  launcherEnvironment: 'not a service: launcher-provided root accessor value (EnvironmentSnapshot | undefined) — packages/util/environment/README.md owns the launcher contract',
+  lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the surface',
+  apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the surface',
+  appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the surface',
+  connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the surface',
+}
+
+/**
+ * The owning subsystems page for every harness event scope (the segment
+ * before the first `/`). Fail-closed exactly like {@link SERVICE_PAGE}.
+ * `slash` lives with the human-command surface: the client slash-input
+ * protocol parses toward command invocation and `dsh-ui-slash` owns the
+ * declarations, but commands.md owns the cross-package command story.
+ */
+export const EVENT_SCOPE_PAGE: Record<string, string> = {
+  'agent': 'core.md',
+  'agent-loop': 'core.md',
+  'approval': 'approval.md',
+  'commands': 'commands.md',
+  'credentials': 'credentials.md',
+  'domain': 'storage.md',
+  'fs': 'filesystem.md',
+  'goal': 'goal.md',
+  'llm': 'llm-streaming.md',
+  'session': 'session.md',
+  'settings': 'settings.md',
+  'skills': 'skills.md',
+  'subagent': 'subagent.md',
+  'system-prompt': 'system-prompt.md',
+  'telemetry': 'telemetry.md',
+  'tools': 'tools.md',
+  'workflow': 'workflow.md',
+}
+
+/**
+ * One primary subsystems page per project type used by a generated
+ * signature. This stays curated because union names intentionally do not
+ * reuse the type-equivalence manifest's map-symbol entries and some symbols
+ * appear on more than one page.
+ */
 export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
@@ -94,12 +226,12 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   FsWriteIntent: 'filesystem.md',
   FsWriteOutcome: 'filesystem.md',
   CreateGoalRequest: 'goal.md',
-  CreateGoalResult: 'goal.md',
   EditGoalRequest: 'goal.md',
   GoalBlockReason: 'goal.md',
   GoalChanged: 'goal.md',
   GoalRef: 'goal.md',
   GoalView: 'goal.md',
+  CreateGoalResult: 'goal.md',
   CommandDefinition: 'commands.md',
   CommandDescriptor: 'commands.md',
   CommandResult: 'commands.md',
@@ -248,6 +380,18 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   TelemetryRecord: 'telemetry.md',
   WorkflowRunInfo: 'workflow.md',
   WorkflowStartRequest: 'workflow.md',
+  ProjectionDefinition: 'session-projection.md',
+  SessionProjectionMap: 'session-projection.md',
+  ProjectionChangeListener: 'session-projection.md',
+  ProjectionSnapshot: 'session-projection.md',
+  ProjectionCheckpoint: 'session-projection.md',
+  DirectoryPickerCapability: 'workspace.md',
+  TypertContribution: 'invariants.md',
+  TypertFace: 'invariants.md',
+  TypertPackageFilter: 'invariants.md',
+  TypertPackageRecord: 'invariants.md',
+  TypertSchemaFilter: 'invariants.md',
+  TypertSchemaRecord: 'invariants.md',
 }
 
 /** TypeScript lib and pinned framework types with no repository-owned data page. */
@@ -277,31 +421,19 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
-  DirectoryPickerCapability: 'picker interaction contract is owned by packages/host/directory-picker/README.md',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
-  ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
-  SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session/session-projection/src/types.ts',
-  ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
-  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session/session-projection/src/index.ts',
-  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session/session-projection/src/index.ts',
   CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
-  TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
-  TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
-  TypertPackageFilter: 'registry package query filter is owned by packages/typert/registry/README.md',
-  TypertPackageRecord: 'registry package record is owned by packages/typert/registry/README.md',
-  TypertSchemaFilter: 'registry schema query filter is owned by packages/typert/registry/README.md',
-  TypertSchemaRecord: 'registry schema record is owned by packages/typert/registry/README.md',
-  TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
   'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
+  TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
+  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
   LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   WebUpgradeRoute:
     'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
-  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
   KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
@@ -351,15 +483,171 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
   ],
 }
 
-/** CLI entry: default writes every artifact; `--check` reports stale files.
+
+/**
+ * Splice a page's generated cordis-surface region into its Markdown content.
+ * The page must contain exactly one cordis-surface region (the markers are
+ * part of the hand-owned page skeleton once, then owned by the generator);
+ * zero or several is a partition error the caller reports with the page path.
+ * The match is on THIS generator's exact markers, not the generic region
+ * grammar, so a page carrying only some other generator's region fails loud
+ * instead of having that region overwritten.
+ * @param content - the page's current full Markdown text.
+ * @param region - the freshly rendered marker-delimited region.
+ * @returns the page text with the region replaced.
+ */
+export function spliceRegion(content: string, region: string): string {
+  const lines = content.split('\n')
+  const begins = lines.flatMap((line, index) => (line === REGION_BEGIN ? [index] : []))
+  const ends = lines.flatMap((line, index) => (line === REGION_END ? [index] : []))
+  if (begins.length !== 1 || ends.length !== 1) {
+    throw new Error(`expected exactly 1 cordis-surface region, found ${begins.length} BEGIN/${ends.length} END; add the BEGIN/END cordis-surface markers once`)
+  }
+  const begin = begins[0] ?? -1
+  const end = ends[0] ?? -1
+  if (end < begin) throw new Error('cordis-surface END marker precedes its BEGIN')
+  return [...lines.slice(0, begin), ...region.split('\n'), ...lines.slice(end + 1)].join('\n')
+}
+
+/**
+ * Compute every generated artifact: the inherited-tier page, the model-facing
+ * runtime API module, plus, per mapped subsystems page, the pair's two updated
+ * documents with the injected region. Fail-loud partition checks live here: an
+ * unmapped service/event scope, a mapping whose page file does not exist, a
+ * curated entry whose key/scope the projection no longer discovers, and a
+ * mapped page missing its markers are all aggregated errors.
+ * @returns `[repo-relative path, exact content]` for every generated artifact.
+ */
+export function computeOutputs(): [string, string][] {
+  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
+  const services = [...model.services]
+  const events = [...model.events]
+  const problems: string[] = []
+
+  const discoveredKeys = new Set(services.map(s => s.key))
+  const discoveredScopes = new Set(events.map(e => e.scope))
+  for (const s of services) {
+    if (!Object.hasOwn(SERVICE_PAGE, s.key)) problems.push(`service ctx.${s.key} (${s.source}) has no SERVICE_PAGE entry; every service maps to exactly one subsystems page.`)
+  }
+  for (const scope of discoveredScopes) {
+    if (!Object.hasOwn(EVENT_SCOPE_PAGE, scope)) problems.push(`event scope '${scope}/*' has no EVENT_SCOPE_PAGE entry; every event scope maps to exactly one subsystems page.`)
+  }
+  for (const key of Object.keys(SERVICE_PAGE)) {
+    if (!discoveredKeys.has(key)) problems.push(`SERVICE_PAGE maps 'ctx.${key}' but the projection discovers no such service; remove the stale entry.`)
+  }
+  for (const scope of Object.keys(EVENT_SCOPE_PAGE)) {
+    if (!discoveredScopes.has(scope)) problems.push(`EVENT_SCOPE_PAGE maps '${scope}/*' but the projection discovers no such scope; remove the stale entry.`)
+  }
+  // The rendering projection only sees a Context key it can resolve to a
+  // documented service class. This independent scan reads EVERY Context merge
+  // so a key the projection cannot render must either be rendered (mapped) or
+  // carry a named SERVICE_WALK_EXEMPTIONS reason — never vanish silently.
+  const declaredKeys = new Map<string, string>()
+  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/*.ts')) {
+    for (const key of contextKeyMap(body, sf).keys()) {
+      if (!declaredKeys.has(key)) declaredKeys.set(key, rel)
+    }
+  }
+  for (const [key, rel] of declaredKeys) {
+    const rendered = discoveredKeys.has(key)
+    const exempt = Object.hasOwn(SERVICE_WALK_EXEMPTIONS, key)
+    if (!rendered && !exempt) {
+      problems.push(`ctx.${key} (${rel}) is declared in a Context merge but invisible to the rendering projection; map it in SERVICE_PAGE (after making it renderable) or name it in SERVICE_WALK_EXEMPTIONS with its documentation owner.`)
+    }
+    if (rendered && exempt) problems.push(`ctx.${key} is rendered by the projection but still listed in SERVICE_WALK_EXEMPTIONS; remove the stale exemption.`)
+  }
+  for (const key of Object.keys(SERVICE_WALK_EXEMPTIONS)) {
+    if (!declaredKeys.has(key)) problems.push(`SERVICE_WALK_EXEMPTIONS names 'ctx.${key}' but no Context merge declares it; remove the stale exemption.`)
+  }
+  if (problems.length > 0) throw new Error(`gen-cordis-catalog: ${problems.length} partition violation(s):\n${problems.map(p => `  ${p}`).join('\n')}`)
+
+  const pages = [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])].sort()
+  const outputs: [string, string][] = [
+    [OUT_INHERITED, renderInheritedPage(CORDIS_CATALOG_POLICY)],
+    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
+  ]
+  for (const page of pages) {
+    const region = renderPageRegion(
+      page,
+      services.filter(s => SERVICE_PAGE[s.key] === page),
+      events.filter(e => EVENT_SCOPE_PAGE[e.scope] === page),
+      CORDIS_CATALOG_POLICY,
+    )
+    for (const side of [page, page.replace(/\.md$/, '.zh.md')]) {
+      const rel = `${SUBSYSTEMS_DIR}/${side}`
+      let current: string
+      try {
+        current = readFileSync(resolve(root, rel), 'utf8')
+      } catch {
+        // Both pair sides must exist before a region can be injected; the
+        // pairing gate owns pair completeness, this generator names the miss.
+        problems.push(`${rel}: mapped subsystems page does not exist.`)
+        continue
+      }
+      try {
+        outputs.push([rel, spliceRegion(current, region)])
+      } catch (error) {
+        problems.push(`${rel}: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
+  if (problems.length > 0) throw new Error(`gen-cordis-catalog: ${problems.length} page violation(s):\n${problems.map(p => `  ${p}`).join('\n')}`)
+  return outputs
+}
+
+/**
+ * Re-record a pair's `.i18n.yaml` after a region write ONLY when the write is
+ * region-confined: both sides' region-stripped content must be byte-equal to
+ * the region-stripped previous content whose hashes the record holds. The
+ * caller supplies the previous bytes (read before writing); human-content
+ * drift leaves the record untouched so the pairing gate still demands the
+ * normal translation flow.
+ * @param pageRel - repo-relative English page path (`docs/subsystems/x.md`).
+ * @param before - pre-write bytes per repo-relative path.
+ * @param scanRoot - repository root override for tests.
+ * @returns true when the record was refreshed.
+ */
+export function maybeRecordPair(pageRel: string, before: Map<string, Buffer>, scanRoot: string = root): boolean {
+  const zhRel = pageRel.replace(/\.md$/, '.zh.md')
+  const metaRel = pageRel.replace(/\.md$/, '.i18n.yaml')
+  const metaAbs = resolve(scanRoot, metaRel)
+  let meta: string
+  try {
+    meta = readFileSync(metaAbs, 'utf8')
+  } catch {
+    // No record yet: a brand-new pair is recorded by the author's --write
+    // after review, never silently by regeneration.
+    return false
+  }
+  // The record must be exactly the well-formed two-entry shape for THIS pair;
+  // a malformed or renamed-key sidecar is the pairing gate's problem to
+  // report, never something regeneration silently repairs into validity.
+  const recorded = parsePairMeta(meta)
+  const names = [pageRel, zhRel].map(rel => rel.split('/').at(-1) ?? rel)
+  if (!recorded || recorded.size !== 2 || !names.every(name => recorded.has(name))) return false
+  for (const rel of [pageRel, zhRel]) {
+    const previous = before.get(rel)
+    if (!previous) return false
+    if (recorded.get(rel.split('/').at(-1) ?? rel) !== blobHash(previous)) return false
+    const current = readFileSync(resolve(scanRoot, rel))
+    const strippedBefore = partitionGeneratedRegions(previous.toString('utf8')).stripped
+    const strippedAfter = partitionGeneratedRegions(current.toString('utf8')).stripped
+    if (strippedBefore !== strippedAfter) return false
+  }
+  const source = readFileSync(resolve(scanRoot, pageRel))
+  const zh = readFileSync(resolve(scanRoot, zhRel))
+  writeFileSync(metaAbs, renderPairMeta(pageRel, blobHash(source), zhRel, blobHash(zh)))
+  return true
+}
+
+/** CLI entry: default regenerates every artifact, `--check` fails if any is
+ * stale. Guarded behind an entry-point check so importing this module for
+ * tests neither regenerates the committed files nor calls process.exit.
  * @returns nothing; writes files or reports freshness through the process.
  */
 export function main(): void {
-  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
-    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
-    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
+    ...computeOutputs(),
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -369,25 +657,51 @@ export function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT is expected; either read failure has the same remedy.
+        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+        // file is not a state this repo produces. Either way the remedy is the
+        // same — regenerate — so treat a read failure as "stale".
         committed = null
       }
       if (committed !== content) stale.push(out)
     }
     if (stale.length === 0) {
-      console.log(`gen-cordis-catalog: ${outputs.length} generated file(s) are up to date.`)
+      console.log(`gen-cordis-catalog: ${outputs.length} generated file(s)/region(s) are up to date.`)
       process.exit(0)
     }
-    console.error(`gen-cordis-catalog: ${stale.join(' and ')} ${stale.length === 1 ? 'is' : 'are'} stale. Run \`pnpm run gen-cordis-catalog\` and commit the result.`)
+    console.error(`gen-cordis-catalog: stale — ${stale.join(', ')}. Run \`pnpm run gen-cordis-catalog\` and commit the result.`)
     process.exit(1)
   }
 
+  const before = new Map<string, Buffer>()
+  for (const [out] of outputs) {
+    try {
+      before.set(out, readFileSync(resolve(root, out)))
+    } catch {
+      // First generation of this artifact; nothing to guard, nothing to record.
+    }
+  }
+  let changedPages = 0
+  let recorded = 0
   for (const [out, content] of outputs) {
     const destination = resolve(root, out)
+    if (before.get(out)?.toString('utf8') === content) continue
     mkdirSync(dirname(destination), { recursive: true })
     writeFileSync(destination, content)
+    changedPages++
   }
-  console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
+  for (const page of [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])]) {
+    const rel = `${SUBSYSTEMS_DIR}/${page}`
+    const zhRel = rel.replace(/\.md$/, '.zh.md')
+    const wroteEither = [rel, zhRel].some((side) => {
+      const previous = before.get(side)
+      return previous !== undefined && previous.toString('utf8') !== readFileSync(resolve(root, side), 'utf8')
+    })
+    if (wroteEither && maybeRecordPair(rel, before)) recorded++
+  }
+  console.log(`gen-cordis-catalog: ${outputs.length} artifact(s) computed, ${changedPages} written, ${recorded} pair record(s) refreshed.`)
 }
 
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
+// Run only when invoked as a script, not when imported by a test.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 4f72b1d953..1c4cce0fa3 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1344,7 +1344,7 @@ function renderIndex(docs: GraphDoc[]): string {
   const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
   return [
     ...generatedHeader('Documentation Graph Index'),
-    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).',
+    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).',
     '',
     'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
     '',
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 800497ddb7..5294242e27 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -352,7 +352,7 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 39ed4d7620..a68ab874f0 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -608,7 +608,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page\'s generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index ebdce88f6d..c2ca4136d3 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -276,7 +276,7 @@ describe('docsPages locale routes', () => {
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(20)
+    expect(translated).toHaveLength(37)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks.map(page => page.source).sort()).toEqual([
       'docs/subsystems/commands.md',
@@ -286,11 +286,11 @@ describe('docsPages locale routes', () => {
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
-    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md']
+    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md', 'inherited.md']
     for (const file of files) {
       const root = docsPages.find(page => page.route === `reference/cordis-api/${file}`)
       const english = docsPages.find(page => page.route === `en/reference/cordis-api/${file}`)
-      expect(root?.source).toBe(`docs/cordis-catalog/core/${file}`)
+      expect(root?.source).toBe(`docs/cordis-api/${file}`)
       expect(root?.section).toBe('Cordis API')
       expect(english?.source).toBe(root?.source)
       expect(english?.section).toBe('Cordis Core API')
diff --git a/scripts/project-doc-site.ts b/scripts/project-doc-site.ts
index e3397237a3..55c7204d78 100644
--- a/scripts/project-doc-site.ts
+++ b/scripts/project-doc-site.ts
@@ -131,6 +131,12 @@ function destinationRange(rawNode: string, type: 'link' | 'image' | 'definition'
   return { start, end: rawNode.length }
 }
 
+// `#fragment` suffixes pass through verbatim. Generated cordis-surface
+// headings carry explicit `<a id>` anchors with the GitHub slug, so those
+// fragments resolve on the published site too; hand-written headings rely on
+// VitePress's own slugger, which differs from GitHub's for punctuation-heavy
+// text — hand-authored cross-page fragments should prefer plain-text headings
+// or explicit anchors.
 function splitTarget(url: string): { path: string; suffix: string } {
   const boundary = url.search(/[?#]/)
   if (boundary === -1) return { path: url, suffix: '' }
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index 7c77929ba3..112cd3ae4d 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -7,7 +7,7 @@
     "docs/agent-lifecycle.md",
     "docs/capability-seams.md",
     "docs/config-catalog.md",
-    "docs/cordis-catalog/",
+    "docs/cordis-api/",
     "docs/event-producer-consumer.md",
     "docs/graph-atlas.md",
     "docs/i18n/style-samples.md",
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index 1073495d08..b89df38f52 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -12,11 +12,13 @@ import {
   translationPairPaths,
 } from './translation-pairing-record.ts'
 import {
+  blobHash,
   isTranslationScopeFile,
   pairAnchorOfArgument,
   parseTranslationMarkdown,
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
+  partitionGeneratedRegions,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -292,3 +294,42 @@ describe('pair CLI arguments', () => {
     expect(() => parseTranslationPairingCliArgs(['--cached', '--write', 'docs/foo.md'])).toThrow('read-only')
   })
 })
+
+describe('generated regions', () => {
+  const BEGIN = '<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->'
+  const END = '<!-- END GENERATED cordis-surface -->'
+
+  it('partitions marker-delimited regions from the hand-owned remainder', () => {
+    const doc = `# T\n\nprose\n\n${BEGIN}\ninjected\n${END}\ntail\n`
+    const { regions, stripped } = partitionGeneratedRegions(doc)
+    expect(regions).toEqual([`${BEGIN}\ninjected\n${END}`])
+    expect(stripped).toBe('# T\n\nprose\n\ntail\n')
+  })
+
+  it('treats a document without markers as one hand-owned remainder', () => {
+    const { regions, stripped } = partitionGeneratedRegions('# T\n\nprose\n')
+    expect(regions).toEqual([])
+    expect(stripped).toBe('# T\n\nprose\n')
+  })
+
+  it('rejects unbalanced or nested markers', () => {
+    expect(() => partitionGeneratedRegions(`${END}\n`)).toThrow('without a BEGIN')
+    expect(() => partitionGeneratedRegions(`${BEGIN}\n`)).toThrow('without an END')
+    expect(() => partitionGeneratedRegions(`${BEGIN}\n${BEGIN}\n${END}\n`)).toThrow('nested')
+  })
+
+  it('rejects mismatched slugs and malformed marker lines', () => {
+    expect(() => partitionGeneratedRegions('<!-- BEGIN GENERATED a -->\nx\n<!-- END GENERATED b -->\n'))
+      .toThrow("END slug 'b' does not match its BEGIN slug 'a'")
+    expect(() => partitionGeneratedRegions('<!-- BEGIN GENERATED a --> trailing\nx\n<!-- END GENERATED a -->\n'))
+      .toThrow('malformed generated region marker line')
+    expect(() => partitionGeneratedRegions('x\n<!-- END GENERATED a --> tail\n'))
+      .toThrow('malformed generated region marker line')
+  })
+
+  it('computes the exact git blob hash', () => {
+    // `git hash-object` of the empty file and of "x\n" — pinned upstream values.
+    expect(blobHash(Buffer.from(''))).toBe('e69de29bb2d1d6434b8b29ae775ad8c2e48c5391')
+    expect(blobHash(Buffer.from('x\n'))).toBe('587be6b4c3f93f93c489c0111bba5596147a26cb')
+  })
+})
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 6d6893f843..417e836578 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -2,13 +2,122 @@
  * Pure parsing and structural helpers for the bilingual-document pairing
  * gate. Kept separate from the CLI so corpus discovery and signature behavior
  * can be regression-tested without reading or mutating the repository tree.
+ * Also the one home of the generated-region grammar and the pair-record
+ * primitives, shared by the pairing gate and the region-injecting generators.
  */
 
+import { createHash } from 'node:crypto'
+import { basename } from 'node:path'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
 import type { Nodes } from 'mdast'
 
+/** Complete opening marker line: `<!-- BEGIN GENERATED <slug> … -->` (slug captured). */
+const GENERATED_REGION_BEGIN_LINE = /^<!-- BEGIN GENERATED (\S+)(?: [^>]*)? -->$/
+/** Complete closing marker line: `<!-- END GENERATED <slug> -->` (slug captured). */
+const GENERATED_REGION_END_LINE = /^<!-- END GENERATED (\S+) -->$/
+/** Loose marker detector: any line that LOOKS like a region marker must parse as one. */
+const GENERATED_REGION_MARKER_HINT = /^<!-- (?:BEGIN|END) GENERATED /
+
+/**
+ * Extract every generated region (markers included) and the document with
+ * those regions removed. Regions are line-delimited: a marker occupies its
+ * whole line, must be a complete well-formed marker, and the closing slug
+ * must match the opener. The stripped form is what "human content" means for
+ * the region-aware pair-record guard.
+ *
+ * @param content - Full Markdown document text.
+ * @returns The regions in document order and the region-free remainder.
+ * @throws Error on an unopened END, unclosed BEGIN, nested BEGIN, malformed
+ *   marker line, or a closing slug that does not match its opener.
+ */
+export function partitionGeneratedRegions(content: string): { regions: string[]; stripped: string } {
+  const lines = content.split('\n')
+  const regions: string[] = []
+  const kept: string[] = []
+  let open: { slug: string; lines: string[] } | null = null
+  for (const line of lines) {
+    const begin = GENERATED_REGION_BEGIN_LINE.exec(line)
+    if (begin?.[1]) {
+      if (open) throw new Error('generated region BEGIN marker nested inside an open region')
+      open = { slug: begin[1], lines: [line] }
+      continue
+    }
+    const end = GENERATED_REGION_END_LINE.exec(line)
+    if (end?.[1]) {
+      if (!open) throw new Error('generated region END marker without a BEGIN')
+      if (end[1] !== open.slug) throw new Error(`generated region END slug '${end[1]}' does not match its BEGIN slug '${open.slug}'`)
+      open.lines.push(line)
+      regions.push(open.lines.join('\n'))
+      open = null
+      continue
+    }
+    if (GENERATED_REGION_MARKER_HINT.test(line)) {
+      throw new Error(`malformed generated region marker line: ${JSON.stringify(line)}`)
+    }
+    if (open) open.lines.push(line)
+    else kept.push(line)
+  }
+  if (open) throw new Error('generated region BEGIN marker without an END')
+  return { regions, stripped: kept.join('\n') }
+}
+
+/**
+ * Full git blob hash of file content (what `git hash-object` prints).
+ * @param content - Exact file bytes.
+ * @returns The 40-hex-digit SHA-1 blob hash.
+ */
+export function blobHash(content: Buffer): string {
+  const hash = createHash('sha1')
+  hash.update(`blob ${content.byteLength}\0`)
+  hash.update(content)
+  return hash.digest('hex')
+}
+
+const PAIR_META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
+
+/**
+ * Parse a `foo.i18n.yaml` consistency record into basename → recorded blob
+ * hash, or undefined when any non-comment line deviates from the exact
+ * `<basename>.md: <40-hex>` shape or repeats a key. Consumers must
+ * additionally require exactly the two expected basenames — a renamed key is
+ * a malformed record, never a silently-missing entry.
+ * @param content - Sidecar file text.
+ * @returns The recorded map, or undefined for a malformed record.
+ */
+export function parsePairMeta(content: string): Map<string, string> | undefined {
+  const out = new Map<string, string>()
+  for (const line of content.split('\n')) {
+    if (line === '' || line.startsWith('#')) continue
+    const match = PAIR_META_LINE.exec(line)
+    if (!match?.[1] || !match[2]) return undefined
+    if (out.has(match[1])) return undefined
+    out.set(match[1], match[2])
+  }
+  return out
+}
+
+/**
+ * Render a `foo.i18n.yaml` consistency record.
+ * @param source - Repo-relative English path.
+ * @param sourceHash - Blob hash of the English side.
+ * @param zh - Repo-relative Chinese path.
+ * @param zhHash - Blob hash of the Chinese side.
+ * @returns The exact sidecar file content.
+ */
+export function renderPairMeta(source: string, sourceHash: string, zh: string, zhHash: string): string {
+  return [
+    '# 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 ${source}`,
+    `${basename(source)}: ${sourceHash}`,
+    `${basename(zh)}: ${zhHash}`,
+    '',
+  ].join('\n')
+}
+
 /** Validated shape of `scripts/translation-pairing.manifest.json`. */
 export interface TranslationPairingManifest {
   /** Source documents exempt from pairing because they are generated, instructional, or bilingual by construction. */
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 2bc097c88c..317ddec122 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1679,6 +1679,21 @@
       "doc": "docs/subsystems/permission.md",
       "symbol": "PresetSpec",
       "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/session-projection.md",
+      "symbol": "ProjectionDefinition",
+      "source": "packages/session/session-projection/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/session-projection.md",
+      "symbol": "ProjectionSnapshot",
+      "source": "packages/session/session-projection/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/session-projection.md",
+      "symbol": "ProjectionChangeListener",
+      "source": "packages/session/session-projection/src/index.ts"
     }
   ]
 }
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index 59818183e3..be5c1816ae 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -23,6 +23,7 @@ import {
   parseTranslationMarkdown,
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
+  partitionGeneratedRegions,
   isTranslationScopeFile,
   TRANSLATION_SCOPE_GLOB_EXCLUDES,
   translationStructureDiff,
@@ -227,6 +228,27 @@ for (const source of [...pairAnchors].sort()) {
     continue
   }
 
+  // Generated regions are language-invariant: the exact same generator output
+  // (markers included) must appear in both sides, in the same order. The
+  // structural signature below compares the region content again as part of
+  // the whole document; this dedicated check exists to name the divergence
+  // precisely and to reject a region grammar violation on either side.
+  let sourceRegions: { regions: string[]; stripped: string }
+  let zhRegions: { regions: string[]; stripped: string }
+  try {
+    sourceRegions = partitionGeneratedRegions(sourceContent.toString('utf8'))
+    zhRegions = partitionGeneratedRegions(zhContent.toString('utf8'))
+  } catch (error) {
+    errors.push(`${source} ↔ ${zh}: ${error instanceof Error ? error.message : String(error)}`)
+    state.set(source, 'out-of-sync')
+    continue
+  }
+  if (sourceRegions.regions.length !== zhRegions.regions.length
+    || sourceRegions.regions.some((region, index) => region !== zhRegions.regions[index])) {
+    errors.push(`${source} ↔ ${zh}: generated regions differ between the pair — regenerate (the generator writes both sides byte-identically)`)
+    state.set(source, 'out-of-sync')
+  }
+
   const sourceTree = parseTranslationMarkdown(sourceContent.toString('utf8'))
   const zhTree = parseTranslationMarkdown(zhContent.toString('utf8'))
   if (!linksTo(zhTree, basename(source))) {
diff --git a/website/docs.ts b/website/docs.ts
index 07f470319b..551224edaa 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -261,29 +261,46 @@ const coreDataReference = pairedPages(([
   ['core.md', '核心数据结构', 'Core data structures', 0],
   ['scope.md', '作用域', 'Scopes', 1],
   ['session.md', '会话', 'Sessions', 2],
-  ['system-prompt.md', '系统提示词', 'System prompts', 4],
-  ['tools.md', '工具', 'Tools', 5],
-  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 6],
-  ['bash.md', 'Bash 执行', 'Bash execution', 7],
-  ['filesystem.md', '文件系统', 'Filesystem', 9],
-  ['code-runtime.md', '代码运行时', 'Code runtime', 10],
-  ['compaction.md', '上下文压缩', 'Compaction', 11],
-  ['subagent.md', '子代理', 'Subagents', 12],
-  ['workflow.md', '工作流', 'Workflows', 13],
-  ['skills.md', '技能', 'Skills', 14],
-  ['approval.md', '审批', 'Approvals', 15],
-  ['user-interaction.md', '用户交互', 'User interaction', 16],
-  ['sandbox.md', '沙箱', 'Sandboxing', 18],
-  ['web.md', 'Web 访问', 'Web access', 19],
-  ['persistence.md', '会话持久化', 'Session persistence', 20],
-  ['settings.md', '用户设置', 'User settings', 21],
-  ['credentials.md', '用户凭据', 'User credentials', 22],
+  ['session-query.md', '会话查询', 'Session query', 3],
+  ['session-reference.md', '会话引用', 'Session references', 4],
+  ['session-title.md', '会话标题', 'Session titles', 5],
+  ['settings.md', '用户设置', 'User settings', 6],
+  ['credentials.md', '用户凭据', 'User credentials', 7],
+  ['system-prompt.md', '系统提示词', 'System prompts', 8],
+  ['tools.md', '工具', 'Tools', 9],
+  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 10],
+  ['token-meter.md', 'Token 计量', 'Token metering', 11],
+  ['bash.md', 'Bash 执行', 'Bash execution', 12],
+  ['subprocess.md', '子进程', 'Subprocesses', 13],
+  ['tasks.md', '后台任务', 'Background tasks', 14],
+  ['filesystem.md', '文件系统', 'Filesystem', 15],
+  ['lsp.md', 'LSP 导航', 'LSP navigation', 16],
+  ['code-runtime.md', '代码运行时', 'Code runtime', 17],
+  ['compaction.md', '上下文压缩', 'Compaction', 18],
+  ['subagent.md', '子代理', 'Subagents', 19],
+  ['workflow.md', '工作流', 'Workflows', 20],
+  ['skills.md', '技能', 'Skills', 21],
+  ['approval.md', '审批', 'Approvals', 22],
+  ['permission.md', '权限预设', 'Permission presets', 23],
+  ['plan.md', '计划模式', 'Plan mode', 24],
+  ['user-interaction.md', '用户交互', 'User interaction', 25],
+  ['sandbox.md', '沙箱', 'Sandboxing', 26],
+  ['web.md', 'Web 访问', 'Web access', 27],
+  ['spill.md', 'Spill 存储', 'Spill storage', 28],
+  ['persistence.md', '会话持久化', 'Session persistence', 29],
+  ['storage.md', '存储', 'Storage', 30],
+  ['workspace.md', '工作区', 'Workspaces', 31],
+  ['http-server.md', 'HTTP 服务器', 'HTTP server', 32],
+  ['client-modules.md', '客户端模块', 'Client modules', 33],
+  ['invariants.md', '运行时不变式', 'Runtime invariants', 35],
+  ['session-projection.md', '会话投影', 'Session projections', 36],
+  ['telemetry.md', '遥测', 'Telemetry', 37],
 ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
   source: `docs/subsystems/${file}`,
   route: `reference/subsystems/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-reference', en: 'en-reference' },
-  section: { root: '数据结构', en: 'Data structures' },
+  section: { root: '子系统', en: 'Subsystems' },
   order,
   ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
@@ -306,8 +323,6 @@ const reference = mirroredPages([
   ...([
     ['docs/config-catalog.md', 'reference/config-catalog.md', '插件配置', 'Plugin configuration'],
     ['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
-    ['docs/cordis-catalog/services.md', 'reference/cordis-catalog/services.md', '服务', 'Services'],
-    ['docs/cordis-catalog/events.md', 'reference/cordis-catalog/events.md', '事件', 'Events'],
     ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'],
   ] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({
     source,
@@ -325,8 +340,9 @@ const reference = mirroredPages([
     ['fiber.md', 'Fiber', 'Fiber'],
     ['registry.md', 'Plugin Registry', 'Plugin Registry'],
     ['service.md', 'Service', 'Service'],
+    ['inherited.md', '继承接口面', 'Inherited surface'],
   ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
-    source: `docs/cordis-catalog/core/${file}`,
+    source: `docs/cordis-api/${file}`,
     route: `reference/cordis-api/${file}`,
     contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
@@ -335,16 +351,16 @@ const reference = mirroredPages([
     order,
   })),
   ...([
-    ['goal.md', '目标', 'Goals', 3],
-    ['pty.md', 'PTY 会话', 'PTY sessions', 8],
-    ['commands.md', '命令', 'Human commands', 17],
+    ['goal.md', '目标', 'Goals', 13],
+    ['pty.md', 'PTY 会话', 'PTY sessions', 25],
+    ['commands.md', '命令', 'Human commands', 37],
   ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
     source: `docs/subsystems/${file}`,
     route: `reference/subsystems/${file}`,
     contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
-    section: { root: '数据结构', en: 'Data structures' },
+    section: { root: '子系统', en: 'Subsystems' },
     order,
   })),
   ...([

From 2886ba45db2a144d711fa3f009598d98aec0efe5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 03:48:16 +0800
Subject: [PATCH 165/262] docs: give subsystems/ its own README index; retire
 the data-structures-catalog framing

core.md doubled as the folder index: its intro claimed "this folder catalogs the data structures" and carried the 38-row page table, wording that predates the one-page-per-subsystem shape where every page also carries its generated Cordis surface. The folder index now lives in docs/subsystems/README.md (page table plus the type-equiv note), and core.md is one subsystem page among siblings: the spine vocabulary. Structural referents move with it: the docs/AGENTS.md tier table and update rule, development.md's type-equiv pointer, the dsh-code-review skill, the two owning catalog Agent Notes, and website/docs.ts (README projects as reference/subsystems/index.md and takes the docs/subsystems folder alias; sidebar orders shift by one). Remaining "data-structure catalog" / "sub-page" phrasing in active notes and READMEs is reworded to subsystem-page terms in both languages; touched pairs re-recorded; translation-prompt snapshot re-recorded (its example embeds development.md).
---
 ...eneric-long-running-tool-runtime.i18n.yaml |  4 +-
 ...06-20-generic-long-running-tool-runtime.md |  2 +-
 ...20-generic-long-running-tool-runtime.zh.md |  2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  2 +-
 ...2026-06-20-core-data-structures-catalog.md | 12 +--
 .../2026-07-02-tool-schema-catalog.i18n.yaml  |  4 +-
 .../process/2026-07-02-tool-schema-catalog.md |  2 +-
 .../2026-07-02-tool-schema-catalog.zh.md      |  2 +-
 .agents/skills/dsh-code-review/SKILL.md       |  2 +-
 docs/AGENTS.md                                | 14 +--
 docs/development.i18n.yaml                    |  4 +-
 docs/development.md                           |  2 +-
 docs/development.zh.md                        |  2 +-
 docs/subsystems/README.i18n.yaml              |  6 ++
 docs/subsystems/README.md                     | 50 +++++++++++
 docs/subsystems/README.zh.md                  | 50 +++++++++++
 docs/subsystems/compaction.i18n.yaml          |  4 +-
 docs/subsystems/compaction.md                 |  2 +-
 docs/subsystems/compaction.zh.md              |  2 +-
 docs/subsystems/core.i18n.yaml                |  4 +-
 docs/subsystems/core.md                       | 57 +-----------
 docs/subsystems/core.zh.md                    | 57 +-----------
 .../subprocess/subprocess/README.i18n.yaml    |  4 +-
 packages/subprocess/subprocess/README.md      |  2 +-
 packages/subprocess/subprocess/README.zh.md   |  2 +-
 scripts/project-doc-site.spec.ts              |  4 +-
 website/docs.ts                               | 90 ++++++++++---------
 27 files changed, 198 insertions(+), 190 deletions(-)
 create mode 100644 docs/subsystems/README.i18n.yaml
 create mode 100644 docs/subsystems/README.md
 create mode 100644 docs/subsystems/README.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index cb9ed4275a..863045f2ce 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: 90100ea8f146e505c4fbb95760781839bd4bd34a
-2026-06-20-generic-long-running-tool-runtime.zh.md: bdcd8e8fe2a50033177354ce5ce043c4b5264621
+2026-06-20-generic-long-running-tool-runtime.md: 8cf6a34c3e4fc042bd73c147d83838734dfc9585
+2026-06-20-generic-long-running-tool-runtime.zh.md: 5af06b78e97980822687cdc82d9b0672a42b6fc2
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 90100ea8f1..8cf6a34c3e 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -23,7 +23,7 @@ Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into in
 
 ## Runtime contract
 
-The literal types live in the [task data-structure catalog](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
+The literal types live on the [tasks subsystem page](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
 `outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control surfaces apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing surface behavior, so the runtime does not impose a hidden default on unrelated producer families.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index bdcd8e8fe2..5af06b78e9 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 运行时契约
 
-字面类型见[任务数据结构目录](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
+字面类型见[任务子系统页面](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
 `outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 0883a5e9ab..1b1a93fc99 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: a8de47a462da13f316236fb7da3f4bfb57edae21
+2026-06-20-core-data-structures-catalog.md: b358ad54652e5b16ae90037c128cf756bcfdaed3
 2026-06-20-core-data-structures-catalog.zh.md: d84c2befaee4c2032b358ed1a7949ac0151ae74c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index a8de47a462..b358ad5465 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -16,16 +16,16 @@ A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type
 
 ### What counts as "core" — the spine-vs-seam line
 
-The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on a sub-page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
+The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own seam page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
-The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.*** Worked through:
+The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a seam-page detail.*** Worked through:
 
 - A data structure is **core** if it flows through the agent-loop spine — the loop holds, derives, streams, or logs it on every turn regardless of which plugins load (`Message`, `StreamChunk`, `SessionEvent`, the `Agent` handle) — **or** it is the single headline type a plugin author writes against a pipeline (`ToolDefinition`).
-- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a sub-page detail. That is the spine-vs-seam line made sharp.
+- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a seam-page detail. That is the spine-vs-seam line made sharp.
 - `ToolSchema` is core (it is a field of `GenerateOptions`, the model request that flows through every step) even though it is conceptually part of the tool pipeline — *flows through the spine* wins over *conceptual home* when they conflict.
-- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are sub-pages.
+- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are seam pages.
 
-`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sub-pages for the per-seam detail. The sub-pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
+`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sibling seam pages for the per-seam detail; the folder's [README](../../../../docs/subsystems/README.md) indexes every page. The original seam pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
 
 ### The `ts type-equiv` mechanism — literal AND drift-proof
 
@@ -58,4 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the seam-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
index b1098546b7..d97c4dd0b7 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.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 .agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
-2026-07-02-tool-schema-catalog.md: c8cc69df428f6eee0f66ed976865afe2a0702448
-2026-07-02-tool-schema-catalog.zh.md: a1af928cc799974b93d2c8e29792790bc1f4e9e6
+2026-07-02-tool-schema-catalog.md: 673b51831512662c4e2cc3b79cd85b149c78f585
+2026-07-02-tool-schema-catalog.zh.md: 8e47d807a2490e362bb3db6d1d634c75c60997e3
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
index c8cc69df42..673b518315 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-02-tool-schema-catalog.zh.md)
 
 ## Problem
 
-The repository had no single reference for the names, descriptions, and JSON Schemas actually exposed to the model. Source declarations are scattered and runtime-composed, while the existing Cordis and data-structure catalogs cover wiring and vocabulary rather than tools.
+The repository had no single reference for the names, descriptions, and JSON Schemas actually exposed to the model. Source declarations are scattered and runtime-composed, while the existing Cordis reference and subsystem pages cover wiring and vocabulary rather than tools.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
index a1af928cc7..8e47d807a2 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-仓库此前没有一份统一的参考文档来记录实际暴露给模型的工具名称、描述与 JSON Schema。源码声明分散各处且在运行时组合，而既有的 Cordis 目录和数据结构目录覆盖的是接线与词汇，而非工具。
+仓库此前没有一份统一的参考文档来记录实际暴露给模型的工具名称、描述与 JSON Schema。源码声明分散各处且在运行时组合，而既有的 Cordis 参考和子系统页面覆盖的是接线与词汇，而非工具。
 
 ## 决策
 
diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 81f63fac2f..c8a52f5d50 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -21,7 +21,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
 1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
 2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
-3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
+3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/README.md) page and any `type-equiv` entry. Internal types need no catalog entry.
 4. **Registrations clean up.** Verify each new registry contribution satisfies the disposal-test contract in [packages/AGENTS.md](../../../packages/AGENTS.md).
 5. **Invariant companions are semantic.** For every touched `./invariant`, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness ([repository rule](../../../AGENTS.md#conventions); [package contract](../../../packages/AGENTS.md)).
 6. **Required evidence exists.** Verify the author ran the [relevant local checks](../../../AGENTS.md#run-relevant-checks-locally) for the diff and that CI covers the exhaustive matrix; review the semantic gaps neither can detect.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 5194544f95..88c90678de 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -21,23 +21,25 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
 | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
-| [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: literal type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and concise verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
-| Package README | Per-package config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc or catalog restatement, other packages' concerns |
-| [development.md](development.md) | Contributor onboarding: setup, daily workflow, and CI shape at summary level | Runtime rationale (→ Agent Notes), drifting gate inventories |
-| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/core.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind (regions included) |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | First-stop contributor onboarding: local setup, daily workflow, and CI shape at summary level; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), gate-by-gate enumerations that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind (regions included) |
 | Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
 
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type shapes → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
 ## Writing rules
 
 - **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The [subsystems catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 13c766cc80..00673a9415 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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 docs/development.md
-development.md: 134109fd2a09dfa36aaf2ccdba14daccf896da60
-development.zh.md: 741a860770ee3b20fe94cb0b4993bb281b605b26
+development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
+development.zh.md: 9d3606cf741f25318c630e08e8ac84ad5ee8d345
diff --git a/docs/development.md b/docs/development.md
index 134109fd2a..f7084403b3 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -156,7 +156,7 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel
 
 ### Documenting types verbatim (`ts type-equiv`)
 
-The [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
+The [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 741a860770..9d3606cf74 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -156,7 +156,7 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
new file mode 100644
index 0000000000..ec72119627
--- /dev/null
+++ b/docs/subsystems/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 docs/subsystems/README.md
+README.md: 59e5a4db09d114e96c19dc0fe29a5ebe8d8c8d32
+README.zh.md: 6b5fa58bf45654708b08d780aa0e17a8d90b7e17
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
new file mode 100644
index 0000000000..59e5a4db09
--- /dev/null
+++ b/docs/subsystems/README.md
@@ -0,0 +1,50 @@
+# Subsystems
+
+English | [中文](README.zh.md)
+
+One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis surface** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.
+
+| Page | Owns |
+|---|---|
+| [core.md](core.md) | the spine vocabulary every turn traffics in — `Message`/`ContentBlock`, `StreamChunk`, `SessionEvent`, the `Agent` handle, `ToolDefinition`, branded ids, the `…Map → derived-union` pattern |
+| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
+| [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
+| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
+| [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
+| [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
+| [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
+| [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
+| [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
+| [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
+| [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
+| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
+| [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
+| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
+| [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
+| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit and answerer contracts |
+| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashProcess` handles |
+| [subprocess.md](subprocess.md) | the subprocess seam: fully-explicit `SubprocessSpawnSpec`, offset-based output readers, unclassified `SubprocessOutcome`, and the managed `DSH_*` environment vocabulary |
+| [pty.md](pty.md) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
+| [sandbox.md](sandbox.md) | per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, `ConfinedArgv`, enforcement and fail-closed errors |
+| [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
+| [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
+| [lsp.md](lsp.md) | the LSP navigation seam: `LspQueryRequest`/`Result`, `LspProvider`/`Service`, four operations, `LspError` |
+| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading |
+| [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
+| [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
+| [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
+| [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
+| [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
+| [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
+| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
+| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
+| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
+| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
+| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
+| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
+| [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
+| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
+| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
+
+> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section.
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
new file mode 100644
index 0000000000..6b5fa58bf4
--- /dev/null
+++ b/docs/subsystems/README.zh.md
@@ -0,0 +1,50 @@
+# 子系统
+
+[English](README.md) | 中文
+
+每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 `ctx` 服务或事件作用域支撑时——一段生成的 **Cordis surface** 小节，承载其服务与事件参考。本目录与 [architecture.md](../architecture.md) 互补：后者描述跨子系统的*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。
+
+| 页面 | 负责内容 |
+|---|---|
+| [core.md](core.md) | 每个轮次都在使用的主干词汇——`Message`/`ContentBlock`、`StreamChunk`、`SessionEvent`、`Agent` 句柄、`ToolDefinition`、品牌化 id，以及 `…Map → 派生联合` 模式 |
+| [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
+| [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
+| [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
+| [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
+| [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
+| [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
+| [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` |
+| [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
+| [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
+| [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
+| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
+| [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
+| [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
+| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
+| [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
+| [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
+| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
+| [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
+| [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
+| [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
+| [lsp.md](lsp.md) | LSP 导航 seam：`LspQueryRequest`/`Result`、`LspProvider`/`Service`、四种操作、`LspError` |
+| [skills.md](skills.md) | skill（技能）服务：发现优先级、`SkillSummary`/`SkillDefinition`、会话前缀目录、面向模型的 `skill` 加载 |
+| [compaction.md](compaction.md) | 压缩（compaction）seam：`compact/*` 会话事件、`CompactionResult`、`CompactService` 接口 |
+| [subagent.md](subagent.md) | subagent seam：命名提供方注册表、`SubagentStartRequest`/`Result`/`Run`、启动时与运行时能力拆分 |
+| [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
+| [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
+| [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
+| [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
+| [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
+| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
+| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
+| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
+| [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
+| [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
+| [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
+
+> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 5481b2feb1..eb2332a715 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 126c6c7c7df125cf991ea074e0165481c09455dc
-compaction.zh.md: 9fb01a41a92367b9bb3f4586f35b5d0baf613bbc
+compaction.md: eeea249fa7a9f95e607edb10e6a8c93a24162b64
+compaction.zh.md: 24c55f062404ff827292f324392347ad59bb7846
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 126c6c7c7d..eeea249fa7 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -20,7 +20,7 @@ The lock brackets the **whole** operation: `compact/start` is appended first, th
 
 The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
 
-These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other sub-pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
+These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other subsystem pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
 
 ## `CompactionResult`
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 9fb01a41a9..24c55f0624 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -20,7 +20,7 @@
 
 这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。
 
-这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
+这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子系统页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
 
 ## `CompactionResult`
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 48d6fc9c71..0994de32ec 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 7e62de88519e5c0bf3a1a0b94de93635767f9f7b
-core.zh.md: ef5b70ae336d55fd25c2251372705912473d07f7
+core.md: 8f27727d63e598fbf31b09a87ab53ad686155b4f
+core.zh.md: fff5bd502cbed6f2167eb23731fb5c3825efb7af
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 7e62de8851..8f27727d63 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -2,7 +2,7 @@
 
 English | [中文](core.zh.md)
 
-This folder catalogs the **data structures** of the DeepSeek Harness — what each core type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around.
+This page catalogs the **core** data structures of the DeepSeek Harness — what each spine type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around. The sibling subsystem pages are indexed in the [folder README](README.md).
 
 ## What counts as "core"
 
@@ -13,50 +13,8 @@ Precisely, a data structure is **core** if either:
 1. it flows through the agent-loop spine — the loop holds it, derives it, streams it, or logs it on every turn (a `Message`, a `StreamChunk`, a `SessionEvent`, the `Agent` handle itself), independent of which plugins are present; **or**
 2. it is the single headline type a plugin author writes against a pipeline — `ToolDefinition` (what every tool *is*).
 
-Everything else is documented on a **sub-page**, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.* So `ToolDefinition` is core, but the `ValueSchemaSpec`/`ParameterSchemaSpec` inference machinery that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on the sub-pages below.
+Everything else is documented on its own subsystem page, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is another page’s detail.* So `ToolDefinition` is core, but the `ValueSchemaSpec`/`ParameterSchemaSpec` inference machinery that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on their own pages ([index](README.md)).
 
-| Sub-page | Owns |
-|---|---|
-| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
-| [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
-| [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
-| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
-| [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
-| [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
-| [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
-| [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
-| [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
-| [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
-| [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
-| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
-| [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
-| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
-| [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
-| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit and answerer contracts |
-| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashProcess` handles |
-| [subprocess.md](subprocess.md) | the subprocess seam: fully-explicit `SubprocessSpawnSpec`, offset-based output readers, unclassified `SubprocessOutcome`, and the managed `DSH_*` environment vocabulary |
-| [pty.md](pty.md) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
-| [sandbox.md](sandbox.md) | per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, `ConfinedArgv`, enforcement and fail-closed errors |
-| [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
-| [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
-| [lsp.md](lsp.md) | the LSP navigation seam: `LspQueryRequest`/`Result`, `LspProvider`/`Service`, four operations, `LspError` |
-| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading |
-| [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
-| [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
-| [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
-| [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
-| [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
-| [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
-| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
-| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
-| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
-| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
-| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
-| [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
-| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
-| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
-
-> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](#cordis-surface).
 
 ## The `…Map → derived-union` pattern
 
@@ -323,15 +281,6 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
-  /**
-   * Whether the owning adapter knows this route only because configuration
-   * declared it — a gateway or self-hosted server it ships nothing about.
-   * Absent means the adapter draws no such distinction; false means it does
-   * and this route is one of its own. Only the adapter can answer: a stored
-   * profile is how a user-added route AND a corrected shipped one both look
-   * from outside.
-   */
-  declared?: boolean
 }
 ```
 
@@ -999,7 +948,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index ef5b70ae33..fff5bd502c 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,7 +2,7 @@
 
 [English](core.md) | 中文
 
-本目录编目 DeepSeek Harness 的**数据结构**：每个核心类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。
+本页编目 DeepSeek Harness 的**核心**数据结构：每个主干类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。同级的各子系统页面见[目录 README](README.md)。
 
 ## 什么算"核心"
 
@@ -13,50 +13,8 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 1. 它流经 agent loop 主干——循环在每个轮次中持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄本身），与当前加载了哪些插件无关；**或者**
 2. 它是插件作者面向某条流水线编写的代表性类型——`ToolDefinition`（每个工具*是什么*）。
 
-其他一切都记录在**子页面**上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是子页面细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们分别在下列子页面中。
+其他一切都记录在各自的子系统页面上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是其他页面的细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们各有自己的页面（[目录](README.md)）。
 
-| 子页面 | 负责内容 |
-|---|---|
-| [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
-| [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
-| [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
-| [typert.md](typert.md) | Remote 调用 descriptor、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
-| [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
-| [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
-| [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
-| [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` |
-| [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
-| [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
-| [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
-| [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
-| [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
-| [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
-| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
-| [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
-| [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
-| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
-| [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
-| [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
-| [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
-| [lsp.md](lsp.md) | LSP 导航 seam：`LspQueryRequest`/`Result`、`LspProvider`/`Service`、四种操作、`LspError` |
-| [skills.md](skills.md) | skill（技能）服务：发现优先级、`SkillSummary`/`SkillDefinition`、会话前缀目录、面向模型的 `skill` 加载 |
-| [compaction.md](compaction.md) | 压缩（compaction）seam：`compact/*` 会话事件、`CompactionResult`、`CompactService` 接口 |
-| [subagent.md](subagent.md) | subagent seam：命名提供方注册表、`SubagentStartRequest`/`Result`/`Run`、启动时与运行时能力拆分 |
-| [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
-| [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
-| [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
-| [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
-| [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
-| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
-| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
-| [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
-| [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
-| [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
-
-> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](#cordis-surface)。
 
 <a id="the-map--derived-union-pattern"></a>
 
@@ -329,15 +287,6 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
-  /**
-   * Whether the owning adapter knows this route only because configuration
-   * declared it — a gateway or self-hosted server it ships nothing about.
-   * Absent means the adapter draws no such distinction; false means it does
-   * and this route is one of its own. Only the adapter can answer: a stored
-   * profile is how a user-added route AND a corrected shipped one both look
-   * from outside.
-   */
-  declared?: boolean
 }
 ```
 
@@ -1007,7 +956,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 86694c3c23..7a33a31d0c 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 6e4b9a9c50bc54a4752930ec14269d2c15233a76
-README.zh.md: d756cd9b7117d7ce9a2e79c6469d9fc188c9600b
+README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
+README.zh.md: 3ad73bdea3b137f1c9139fdb1b52c49eb10b5500
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 6e4b9a9c50..c28361f5e7 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -15,7 +15,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
-See the [subprocess data-structure catalog](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+See the [subprocess subsystem page](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 ## Model Experience
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index d756cd9b71..3ad73bdea3 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -15,7 +15,7 @@
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[子进程数据结构目录](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[子进程子系统页面](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index c2ca4136d3..750b1935de 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -269,14 +269,14 @@ describe('docsPages locale routes', () => {
     }
   })
 
-  it('projects translated core-data pages while retaining explicit English fallbacks', () => {
+  it('projects translated subsystem pages while retaining explicit English fallbacks', () => {
     const rootPages = docsPages.filter(page => (
       page.locale === 'root' && page.route.startsWith('reference/subsystems/')
     ))
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(37)
+    expect(translated).toHaveLength(39)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks.map(page => page.source).sort()).toEqual([
       'docs/subsystems/commands.md',
diff --git a/website/docs.ts b/website/docs.ts
index 551224edaa..9a28aeea4d 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -257,52 +257,54 @@ const cordisPrimerReference = pairedPages([
   },
 ])
 
-const coreDataReference = pairedPages(([
-  ['core.md', '核心数据结构', 'Core data structures', 0],
-  ['scope.md', '作用域', 'Scopes', 1],
-  ['session.md', '会话', 'Sessions', 2],
-  ['session-query.md', '会话查询', 'Session query', 3],
-  ['session-reference.md', '会话引用', 'Session references', 4],
-  ['session-title.md', '会话标题', 'Session titles', 5],
-  ['settings.md', '用户设置', 'User settings', 6],
-  ['credentials.md', '用户凭据', 'User credentials', 7],
-  ['system-prompt.md', '系统提示词', 'System prompts', 8],
-  ['tools.md', '工具', 'Tools', 9],
-  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 10],
-  ['token-meter.md', 'Token 计量', 'Token metering', 11],
-  ['bash.md', 'Bash 执行', 'Bash execution', 12],
-  ['subprocess.md', '子进程', 'Subprocesses', 13],
-  ['tasks.md', '后台任务', 'Background tasks', 14],
-  ['filesystem.md', '文件系统', 'Filesystem', 15],
-  ['lsp.md', 'LSP 导航', 'LSP navigation', 16],
-  ['code-runtime.md', '代码运行时', 'Code runtime', 17],
-  ['compaction.md', '上下文压缩', 'Compaction', 18],
-  ['subagent.md', '子代理', 'Subagents', 19],
-  ['workflow.md', '工作流', 'Workflows', 20],
-  ['skills.md', '技能', 'Skills', 21],
-  ['approval.md', '审批', 'Approvals', 22],
-  ['permission.md', '权限预设', 'Permission presets', 23],
-  ['plan.md', '计划模式', 'Plan mode', 24],
-  ['user-interaction.md', '用户交互', 'User interaction', 25],
-  ['sandbox.md', '沙箱', 'Sandboxing', 26],
-  ['web.md', 'Web 访问', 'Web access', 27],
-  ['spill.md', 'Spill 存储', 'Spill storage', 28],
-  ['persistence.md', '会话持久化', 'Session persistence', 29],
-  ['storage.md', '存储', 'Storage', 30],
-  ['workspace.md', '工作区', 'Workspaces', 31],
-  ['http-server.md', 'HTTP 服务器', 'HTTP server', 32],
-  ['client-modules.md', '客户端模块', 'Client modules', 33],
-  ['invariants.md', '运行时不变式', 'Runtime invariants', 35],
-  ['session-projection.md', '会话投影', 'Session projections', 36],
-  ['telemetry.md', '遥测', 'Telemetry', 37],
+const subsystemsReference = pairedPages(([
+  ['README.md', '子系统', 'Subsystems', 0],
+  ['core.md', '核心数据结构', 'Core data structures', 1],
+  ['scope.md', '作用域', 'Scopes', 2],
+  ['session.md', '会话', 'Sessions', 3],
+  ['session-query.md', '会话查询', 'Session query', 4],
+  ['session-reference.md', '会话引用', 'Session references', 5],
+  ['session-title.md', '会话标题', 'Session titles', 6],
+  ['settings.md', '用户设置', 'User settings', 7],
+  ['credentials.md', '用户凭据', 'User credentials', 8],
+  ['system-prompt.md', '系统提示词', 'System prompts', 9],
+  ['tools.md', '工具', 'Tools', 10],
+  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 11],
+  ['token-meter.md', 'Token 计量', 'Token metering', 12],
+  ['bash.md', 'Bash 执行', 'Bash execution', 13],
+  ['subprocess.md', '子进程', 'Subprocesses', 14],
+  ['tasks.md', '后台任务', 'Background tasks', 15],
+  ['filesystem.md', '文件系统', 'Filesystem', 16],
+  ['lsp.md', 'LSP 导航', 'LSP navigation', 17],
+  ['code-runtime.md', '代码运行时', 'Code runtime', 18],
+  ['compaction.md', '上下文压缩', 'Compaction', 19],
+  ['subagent.md', '子代理', 'Subagents', 20],
+  ['workflow.md', '工作流', 'Workflows', 21],
+  ['skills.md', '技能', 'Skills', 22],
+  ['approval.md', '审批', 'Approvals', 23],
+  ['permission.md', '权限预设', 'Permission presets', 24],
+  ['plan.md', '计划模式', 'Plan mode', 25],
+  ['user-interaction.md', '用户交互', 'User interaction', 26],
+  ['sandbox.md', '沙箱', 'Sandboxing', 27],
+  ['web.md', 'Web 访问', 'Web access', 28],
+  ['spill.md', 'Spill 存储', 'Spill storage', 29],
+  ['persistence.md', '会话持久化', 'Session persistence', 30],
+  ['storage.md', '存储', 'Storage', 31],
+  ['workspace.md', '工作区', 'Workspaces', 32],
+  ['http-server.md', 'HTTP 服务器', 'HTTP server', 33],
+  ['client-modules.md', '客户端模块', 'Client modules', 34],
+  ['tui.md', 'TUI 扩展', 'TUI extensions', 35],
+  ['invariants.md', '运行时不变式', 'Runtime invariants', 36],
+  ['session-projection.md', '会话投影', 'Session projections', 37],
+  ['telemetry.md', '遥测', 'Telemetry', 38],
 ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
   source: `docs/subsystems/${file}`,
-  route: `reference/subsystems/${file}`,
+  route: file === 'README.md' ? 'reference/subsystems/index.md' : `reference/subsystems/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-reference', en: 'en-reference' },
   section: { root: '子系统', en: 'Subsystems' },
   order,
-  ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
+  ...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
 
 const reference = mirroredPages([
@@ -351,9 +353,9 @@ const reference = mirroredPages([
     order,
   })),
   ...([
-    ['goal.md', '目标', 'Goals', 13],
-    ['pty.md', 'PTY 会话', 'PTY sessions', 25],
-    ['commands.md', '命令', 'Human commands', 37],
+    ['goal.md', '目标', 'Goals', 14],
+    ['pty.md', 'PTY 会话', 'PTY sessions', 26],
+    ['commands.md', '命令', 'Human commands', 38],
   ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
     source: `docs/subsystems/${file}`,
     route: `reference/subsystems/${file}`,
@@ -385,6 +387,6 @@ export const docsPages: DocsPage[] = [
   ...develop,
   ...cordisTutorial,
   ...cordisPrimerReference,
-  ...coreDataReference,
+  ...subsystemsReference,
   ...reference,
 ]

From aa0ca6c8367488c21cd0666e389ca7424be81653 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 05:54:15 +0800
Subject: [PATCH 166/262] docs: anchor each subsystem page to its package
 group; make group READMEs thin tables
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.

Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
---
 ...-14-provider-routed-llm-adapters.i18n.yaml |   4 +-
 ...2026-07-14-provider-routed-llm-adapters.md |   2 +-
 ...6-07-14-provider-routed-llm-adapters.zh.md |  26 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |   4 +-
 .../2026-07-16-persistent-pty-sessions.md     |   2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |   2 +-
 docs/subsystems/README.i18n.yaml              |   4 +-
 docs/subsystems/README.md                     |   4 +-
 docs/subsystems/README.zh.md                  |   4 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |   2 +-
 docs/subsystems/compaction.zh.md              |   2 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       | 937 +++++++----------
 docs/subsystems/core.zh.md                    | 939 +++++++-----------
 docs/subsystems/filesystem.i18n.yaml          |   4 +-
 docs/subsystems/filesystem.md                 |   4 +
 docs/subsystems/filesystem.zh.md              |   4 +
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              | 417 ++++++--
 docs/subsystems/llm-streaming.zh.md           | 427 ++++++--
 docs/subsystems/session-reference.i18n.yaml   |   4 +-
 docs/subsystems/session-reference.md          |   2 +-
 docs/subsystems/session-reference.zh.md       |   2 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   2 +-
 docs/subsystems/subagent.zh.md                |   2 +-
 docs/subsystems/token-meter.i18n.yaml         |   4 +-
 docs/subsystems/token-meter.md                |   2 +-
 docs/subsystems/token-meter.zh.md             |   2 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |   2 +-
 docs/subsystems/tools.zh.md                   |   2 +-
 packages/acp/README.i18n.yaml                 |   4 +-
 packages/acp/README.md                        |   4 +-
 packages/acp/README.zh.md                     |   4 +-
 packages/bash/README.i18n.yaml                |   4 +-
 packages/bash/README.md                       |   2 +
 packages/bash/README.zh.md                    |   2 +
 packages/boot/README.i18n.yaml                |   4 +-
 packages/boot/README.md                       |   4 +-
 packages/boot/README.zh.md                    |   4 +-
 packages/client/README.i18n.yaml              |   4 +-
 packages/client/README.md                     |   2 +
 packages/client/README.zh.md                  |   2 +
 packages/code-runtime/README.i18n.yaml        |   4 +-
 packages/code-runtime/README.md               |   2 +
 packages/code-runtime/README.zh.md            |   2 +
 packages/compact/README.i18n.yaml             |   4 +-
 packages/compact/README.md                    |   2 +
 packages/compact/README.zh.md                 |   2 +
 packages/context/README.i18n.yaml             |   4 +-
 packages/context/README.md                    |   2 +
 packages/context/README.zh.md                 |   2 +
 packages/core/README.i18n.yaml                |   4 +-
 packages/core/README.md                       |   2 +
 packages/core/README.zh.md                    |   2 +
 packages/credentials/README.i18n.yaml         |   4 +-
 packages/credentials/README.md                |   2 +
 packages/credentials/README.zh.md             |   2 +
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   2 +
 packages/fs/README.zh.md                      |   2 +
 packages/goal/README.i18n.yaml                |   4 +-
 packages/goal/README.md                       |   4 +-
 packages/goal/README.zh.md                    |   4 +-
 packages/guard/README.i18n.yaml               |   4 +-
 packages/guard/README.md                      |   2 +
 packages/guard/README.zh.md                   |   2 +
 packages/host/README.i18n.yaml                |   4 +-
 packages/host/README.md                       |   2 +
 packages/host/README.zh.md                    |   2 +
 packages/interaction/README.i18n.yaml         |   4 +-
 packages/interaction/README.md                |   2 +
 packages/interaction/README.zh.md             |   2 +
 packages/llm/README.i18n.yaml                 |   4 +-
 packages/llm/README.md                        |   2 +
 packages/llm/README.zh.md                     |   2 +
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |   2 +
 packages/lsp/README.zh.md                     |   2 +
 packages/plan/README.i18n.yaml                |   4 +-
 packages/plan/README.md                       |   2 +
 packages/plan/README.zh.md                    |   2 +
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |   2 +
 packages/pty/README.zh.md                     |   2 +
 packages/sandbox/README.i18n.yaml             |   4 +-
 packages/sandbox/README.md                    |   2 +
 packages/sandbox/README.zh.md                 |   2 +
 packages/self-modification/README.i18n.yaml   |   2 +-
 packages/self-modification/README.zh.md       |   4 +-
 packages/session-query/README.i18n.yaml       |   4 +-
 packages/session-query/README.md              |   2 +
 packages/session-query/README.zh.md           |   2 +
 packages/session/README.i18n.yaml             |   4 +-
 packages/session/README.md                    |   2 +
 packages/session/README.zh.md                 |   2 +
 packages/settings/README.i18n.yaml            |   4 +-
 packages/settings/README.md                   |   2 +
 packages/settings/README.zh.md                |   2 +
 packages/skill/README.i18n.yaml               |   4 +-
 packages/skill/README.md                      |   2 +
 packages/skill/README.zh.md                   |   2 +
 packages/spill/README.i18n.yaml               |   4 +-
 packages/spill/README.md                      |   2 +
 packages/spill/README.zh.md                   |   2 +
 packages/storage/README.i18n.yaml             |   4 +-
 packages/storage/README.md                    |   2 +
 packages/storage/README.zh.md                 |   2 +
 packages/subagent/README.i18n.yaml            |   4 +-
 packages/subagent/README.md                   |   2 +
 packages/subagent/README.zh.md                |   2 +
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   2 +
 packages/subprocess/README.zh.md              |   2 +
 packages/support/README.i18n.yaml             |   4 +-
 packages/support/README.md                    |   2 +
 packages/support/README.zh.md                 |   2 +
 packages/tasks/README.i18n.yaml               |   4 +-
 packages/tasks/README.md                      |   2 +
 packages/tasks/README.zh.md                   |   2 +
 packages/todo/README.i18n.yaml                |   4 +-
 packages/todo/README.md                       |   2 +
 packages/todo/README.zh.md                    |   2 +
 packages/web/README.i18n.yaml                 |   4 +-
 packages/web/README.md                        |   2 +
 packages/web/README.zh.md                     |   2 +
 packages/workflow/README.i18n.yaml            |   4 +-
 packages/workflow/README.md                   |   2 +
 packages/workflow/README.zh.md                |   2 +
 packages/workspace/README.i18n.yaml           |   4 +-
 packages/workspace/README.md                  |   2 +
 packages/workspace/README.zh.md               |   2 +
 scripts/gen-cordis-catalog.ts                 |  32 +-
 scripts/type-equiv.manifest.json              |  39 +-
 website/docs.ts                               |   2 +-
 137 files changed, 1680 insertions(+), 1507 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index 465a658ca8..2d39db2332 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.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 .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: 27277280e423553f79d5a34f512b673413f495ff
-2026-07-14-provider-routed-llm-adapters.zh.md: aeb09a500d5750ef2793bc9a7fc09834055a56a4
+2026-07-14-provider-routed-llm-adapters.md: 9039334370ba5d71eb71879970c2e572a5b023df
+2026-07-14-provider-routed-llm-adapters.zh.md: eff33496e1a61472534009533270f8f943ccc1f8
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index 27277280e4..9039334370 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -84,7 +84,7 @@ The on-disk session format remains the pre-release pinned version `0`, with no c
 
 - Unit coverage exercises registry conflicts, request reconstruction, session validation, profile resolution, single-attempt option forwarding, native API selection including OpenAI Responses, conversion, replay validation, error mapping, caller cancellation, idle-timeout transport termination, content rewrites, and same-instance versus different-instance replay dispatch.
 - Keyless loop/session tests and ACP snapshots exercise durable provider/model metadata, resume and fork propagation, workflow/subagent overrides, and unchanged user-visible transcripts; the key-gated DeepSeek e2e retains real provider streaming and tool follow-up coverage.
-- Public JSDoc, package READMEs, architecture and core-data-structure docs, generated catalogs, examples, session fixtures, and Python SDK pairs use provider/model targets consistently and are checked by the repository documentation and type-equivalence gates.
+- Public JSDoc, package READMEs, architecture and subsystem docs, generated catalogs, examples, session fixtures, and Python SDK pairs use provider/model targets consistently and are checked by the repository documentation and type-equivalence gates.
 
 ## Risks
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index aeb09a500d..eff33496e1 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -8,9 +8,9 @@ Status: implemented
 
 `dsh-llm` 按精确模型名称注册适配器。插件在 Cordis 启动时提供模型列表，`LlmService` 为列表中的每个字符串保存一个适配器，`GenerateOptions.model` 同时选择适配器与提供方模型。两个正式适配器都只面向相同的两个 DeepSeek 模型时，这种方式可以工作，但它混淆了两个独立决策：由哪个上游提供方承接请求，以及该提供方应运行哪个模型。
 
-这种混淆使提供方网关无法提供开放的模型目录。例如，OpenRouter 是一个包含大量模型 ID 的提供方，私有 OpenAI 兼容端点也可能在不修改 harness 插件树的情况下增加模型。目前，每个新选择的模型都必须在插件启动期间完成注册。同一个模型 ID 还可能存在于多个提供方中，因此仅按模型注册无法表达调用方预期使用的提供方。
+这种混淆使提供方网关无法提供开放的模型目录。例如，OpenRouter 是一个包含大量模型 ID 的提供方，私有 OpenAI 兼容端点也可能在不修改 Harness 插件树的情况下增加模型。目前，每个新选择的模型都必须在插件启动期间完成注册。同一个模型 ID 还可能存在于多个提供方中，因此仅按模型注册无法表达调用方预期使用的提供方。
 
-`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用载荷补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理（reasoning）和工具签名。harness 转换丢弃了这些来源信息，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
+`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用的 payload 补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理和工具签名。Harness 转换丢弃了这些来源信息，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
 
 适配器配置同样假定只存在一个 DeepSeek API 密钥和端点。通用后端需要为各提供方分别配置凭据和端点覆盖，同时继续由 pi-ai 处理 AWS、Google ADC、OAuth 等环境认证机制。
 
@@ -18,9 +18,9 @@ Status: implemented
 
 ### 提供方作为适配器注册键
 
-`GenerateOptions` 与 `LlmCallConfig` 在 `model: string` 之外携带 `provider: string`，`AgentOptions` 则携带对应的可选创建字段。只有两个值都非空时，agent loop（智能体循环）请求才有效；两个值也都是已记录请求头的一部分。`agent/request` 可以在任意步骤返回替换后的字段组合，因此会话可以切换提供方与模型，无需改变 Cordis 插件生命周期。
+`GenerateOptions` 与 `LlmCallConfig` 在 `model: string` 之外携带 `provider: string`，`AgentOptions` 则携带对应的可选创建字段。只有两个值都非空时，agent loop（智能体循环）请求才有效；两个值也都会写入请求头日志。`agent/request` 可以在任意步骤返回替换后的字段组合，因此会话可以切换提供方与模型，无需改变 Cordis 插件生命周期。
 
-`LlmService` 按提供方注册和解析适配器。`registerAdapter(providers, adapter)` 在修改注册表前检查整个提供方列表，遇到重复项时以 `DUPLICATE_ADAPTER` 拒绝注册，并将整组注册作为一个 effect 统一 dispose（资源释放）。模型 ID 不作为注册键；仍由选中的适配器负责验证或转发。后续的 [LLM 目录与 ACP（Agent Client Protocol）模型选择 Agent Note](2026-07-15-llm-model-catalog-and-acp-selection.md) 增加了建议性的 `listProviders()` / `listModels()` 发现接口，但不会把目录成员关系变成请求校验规则。
+`LlmService` 按提供方注册和解析适配器。`registerAdapter(providers, adapter)` 在修改注册表前检查整个提供方列表，遇到重复项时返回 `DUPLICATE_ADAPTER`，并将整组注册作为一个 effect 释放。模型 ID 不作为注册键；仍由选中的适配器负责验证或转发。后续的 [LLM 目录与 ACP 模型选择 Agent Note](2026-07-15-llm-model-catalog-and-acp-selection.md) 增加了建议性的 `listProviders()` / `listModels()` 发现接口，但不会把目录成员关系变成请求校验规则。
 
 在一个 Cordis 上下文中，一个提供方只能有一个适配器所有者。`dsh-llm-deepseek` 注册 `deepseek`；`dsh-llm-pi-ai` 也可以注册 `deepseek`，但同时加载两个所有者属于配置错误，不采用顺序规则或回退行为。若部署选择手写的 DeepSeek 实现，需从 pi-ai 配置中排除 `deepseek`；若部署选择 pi-ai 的 DeepSeek 实现，则不挂载 `dsh-llm-deepseek`。
 
@@ -28,29 +28,29 @@ Status: implemented
 
 ### 显式 pi-ai 提供方配置
 
-`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤 seam 上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
+`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、Harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤 seam 上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
 
 插件通过一次全有或全无调用，将所有已配置的提供方名称注册到同一个 `PiAiAdapter`。请求按 provider 选择对应配置，并在 `getModels(provider)` 中查找模型以取得目录描述符。未知提供方会在插件加载时失败；未知模型会在网络 I/O 前以 `UNKNOWN_MODEL` 失败。适配器不会修改目录对象。当配置提供 `baseURL` 时，适配器复制选中的描述符，仅覆盖 `baseUrl`，使私有端点保留 pi-ai 的 API、能力、兼容标志、上下文限制与推理映射。私有端点必须实现所选提供方的协议，模型 ID 也仍须存在于已安装的 pi-ai 目录中。
 
-适配器调用 pi-ai 的 `streamSimple()`，因此每个目录模型会选择其注册的 API 实现；描述符为 `openai-responses` 时使用 OpenAI Responses，而非 Chat Completions。harness 的 temperature、最大 token 数、signal、session ID，以及提供方配置中的通用流选项均直接传递。配置 headers 与 harness 强制归因 headers 合并；发生保留名称冲突时，以 harness 归因为准。适配器不再维护 DeepSeek 专用载荷重写或提供方协议矩阵。
+适配器调用 pi-ai 的 `streamSimple()`，因此每个目录模型会选择其注册的 API 实现；描述符为 `openai-responses` 时使用 OpenAI Responses，而非 Chat Completions。Harness 的 temperature、最大 token 数、signal、session ID，以及提供方配置中的通用流选项均直接传递。配置 headers 与 Harness 强制归因 headers 合并；发生保留名称冲突时，以 Harness 归因为准。适配器不再维护 DeepSeek 专用 payload 重写或提供方协议矩阵。
 
-pi-ai 的通用流选项不支持停止序列。若 harness `stop` 选项已定义，`dsh-llm-pi-ai` 会以 `UNSUPPORTED_OPTION` 拒绝请求，不会静默忽略，也不会增加第二套提供方专用 payload 实现。`dsh-llm-deepseek` 继续通过原生请求序列化器支持 `stop`。
+pi-ai 的通用流选项不支持停止序列。若 Harness `stop` 选项已定义，`dsh-llm-pi-ai` 会以 `UNSUPPORTED_OPTION` 拒绝请求，不会静默忽略，也不会增加第二套提供方专用 payload 实现。`dsh-llm-deepseek` 继续通过原生请求序列化器支持 `stop`。
 
 ### 持久化助手来源信息与回放状态
 
 助手消息携带提供方无关的来源信息，其中包含请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些来源信息，`deriveMessages()` 返回助手消息时也会包含这些信息。用户、system、context 与工具结果消息不携带助手来源信息。provider/model 字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。
 
-成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。agent loop 会把该状态附加到组装后的助手来源信息，不再暴露响应改写 hook。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
+成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。只有当 `agent/step-result` 处理后的内容与提供方组装输出在结构上相等时，agent loop 才会把回放状态附加到助手来源信息。监听器重写内容后，provider/model 来源信息仍会保留，但已经陈旧的回放状态会被移除。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
 
-pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容与来源信息。
+pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容与来源信息。
 
 该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 来源信息中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。
 
 ### 在所有请求生产方中传播目标
 
-每个模型选择接口都同时携带 provider 与 model：声明式 agent、ACP 和 stdio 应用配置、JSON-RPC initialize 请求、subagent 覆盖与继承、工作流子 agent 覆盖，以及直接压缩摘要。subagent 先从父 agent 继承两个字段，再应用请求覆盖。系统提示词变量集合在 `model` 之外增加 `provider`。
+每个模型选择接口都同时携带 provider 与 model：声明式 agent、ACP（Agent Client Protocol）和 stdio 应用配置、JSON-RPC initialize 请求、subagent 覆盖与继承、工作流子 agent 覆盖，以及直接压缩摘要。subagent 先从父 agent 继承两个字段，再应用请求覆盖。系统提示词变量集合在 `model` 之外增加 `provider`。
 
-压缩配置在 `summarizationModel` 之外增加 `summarizationProvider`。两个值均为空时继承，均非空时选择显式目标；只配置其中一个会导致加载失败。继承优先使用最近一次记录的请求目标，没有时回退到 agent 创建选项。`compact/summary` 使用现有模型调用封装记录两个字段。
+压缩配置在 `summarizationModel` 之外增加 `summarizationProvider`。两个值均为空时继承，均非空时选择显式目标；只配置其中一个会导致加载失败。继承优先使用最近一次记录的请求目标，没有时回退到 agent 创建选项。`compact/summary` 使用现有模型调用 envelope 记录两个字段。
 
 JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方没有注册所有者时，其便利回退才会挂载 `dsh-llm-deepseek`；其他缺失的提供方会直接失败，不会猜测适配器。
 
@@ -68,7 +68,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 
 **每个提供方挂载一个 pi-ai 插件实例。** 独立实例可以隔离配置，但会重复插件声明，也无法实现配置注册的原子性。每个请求本就向同一个适配器提供 provider，因此经过验证的配置映射具有更小的生命周期接口。
 
-**接受任意内联 pi-ai 模型描述符。** 这种方式可支持目录外的私有模型 ID，但会将 pi-ai 的模型与兼容性 schema 暴露为 harness 配置，并要求适配器验证协议专用组合。当前版本通过覆盖目录模型的 `baseURL` 支持自定义端点；只有实际出现目录外部署需求后，才会另行决策是否支持自定义描述符。
+**接受任意内联 pi-ai 模型描述符。** 这种方式可支持目录外的私有模型 ID，但会将 pi-ai 的模型与兼容性 schema 暴露为 Harness 配置，并要求适配器验证协议专用组合。当前版本通过覆盖目录模型的 `baseURL` 支持自定义端点；只有实际出现目录外部署需求后，才会另行决策是否支持自定义描述符。
 
 ## 影响
 
@@ -84,7 +84,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 
 - 单元测试覆盖注册表冲突、请求重建、会话验证、配置解析、单次请求的选项转发、包括 OpenAI Responses 在内的原生 API 选择、转换、回放验证、错误映射、调用方取消、空闲超时导致的传输终止、内容重写，以及同一实例与不同实例间的回放分发。
 - 无密钥的 agent loop/会话测试和 ACP 快照覆盖持久化 provider/model 元数据、恢复与 fork 传播、工作流/subagent 覆盖，以及不变的用户可见 transcript（文本记录）；密钥门控的 DeepSeek e2e 测试保留真实提供方的流式输出与工具后续调用覆盖率。
-- 公共 JSDoc、包的 README、架构与核心数据结构文档、生成目录、示例、会话 fixture（测试前置数据）和 Python SDK 配对文档统一使用 provider/model 目标，并由仓库文档与类型等价门禁校验。
+- 公共 JSDoc、package README、架构与子系统文档、生成目录、示例、会话 fixture（测试前置数据）和 Python SDK 配对文档统一使用 provider/model 目标，并由仓库文档与类型等价门禁校验。
 
 ## 风险
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 72944d7433..7756f7803c 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 88296a9318b2c398fead382153bd2c652dbd9e68
-2026-07-16-persistent-pty-sessions.zh.md: 40f26c67fe046ad292f05919501600bd2e146c62
+2026-07-16-persistent-pty-sessions.md: 219f48235d527cffbf66020ceb22e80ca473093d
+2026-07-16-persistent-pty-sessions.zh.md: 18b81cd6a8d3f9cdbaa8566e1b166c3877ae8742
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 88296a9318..219f48235d 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -160,7 +160,7 @@ The package ships concise tool guidance explaining persistent state, owner isola
 - Subprocess process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
 - Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
-- Package contracts, the architecture map, core data structures, generated catalogs, and the website API describe the same shipped surface.
+- Package contracts, the architecture map, subsystem pages, generated catalogs, and the website API describe the same shipped surface.
 - The repository CI-equivalent sequence owns type, lint, coverage, snapshot, documentation, build, hygiene, demo, and built-entry verification.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 40f26c67fe..18b81cd6a8 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -160,7 +160,7 @@ plugins:
 - 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
-- 包契约、架构图、核心数据结构、生成目录和 website API 描述同一个已发布接口。
+- 包契约、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
 
 ## 后果
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index ec72119627..3303bcb935 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: 59e5a4db09d114e96c19dc0fe29a5ebe8d8c8d32
-README.zh.md: 6b5fa58bf45654708b08d780aa0e17a8d90b7e17
+README.md: d225e5f4eeb31d1e6c71cbd8311e28bae1e8b3a5
+README.zh.md: 9f78ac3e1c79440b053ee4e344dbdba2c11b3dfc
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 59e5a4db09..d225e5f4ee 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -6,8 +6,8 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 
 | Page | Owns |
 |---|---|
-| [core.md](core.md) | the spine vocabulary every turn traffics in — `Message`/`ContentBlock`, `StreamChunk`, `SessionEvent`, the `Agent` handle, `ToolDefinition`, branded ids, the `…Map → derived-union` pattern |
-| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, the `Agent` handle with its delivery/cancellation/interception contracts, the `SessionEvent` envelope, branded ids, the `…Map → derived-union` pattern |
+| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
 | [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 6b5fa58bf4..9f78ac3e1c 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,8 +6,8 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | 每个轮次都在使用的主干词汇——`Message`/`ContentBlock`、`StreamChunk`、`SessionEvent`、`Agent` 句柄、`ToolDefinition`、品牌化 id，以及 `…Map → 派生联合` 模式 |
-| [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、`Agent` 句柄及其投递/取消/拦截契约、`SessionEvent` 信封、品牌化 id，以及 `…Map → 派生联合` 模式 |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
 | [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index eb2332a715..86348bad3a 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: eeea249fa7a9f95e607edb10e6a8c93a24162b64
-compaction.zh.md: 24c55f062404ff827292f324392347ad59bb7846
+compaction.md: 5aef839192ea6f67bb409622187fe65fed795e73
+compaction.zh.md: 63b28518e68f71cc648d2f4e78a82bc5beafb621
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index eeea249fa7..5aef839192 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -224,7 +224,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 pruneSession(session: Session): PruneResult
 ```
 
-Types: [ContentBlock](core.md) · [Session](session.md)
+Types: [ContentBlock](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 24c55f0624..63b28518e6 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -224,7 +224,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 pruneSession(session: Session): PruneResult
 ```
 
-Types: [ContentBlock](core.md) · [Session](session.md)
+Types: [ContentBlock](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 0994de32ec..16c8e29cf2 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 8f27727d63e598fbf31b09a87ab53ad686155b4f
-core.zh.md: fff5bd502cbed6f2167eb23731fb5c3825efb7af
+core.md: ba9319d377cf250148a145ba3f1fa1baa967c858
+core.zh.md: 276dc4f99f1f802e66aca050b2fbcdc178931611
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 8f27727d63..ba9319d377 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -1,20 +1,29 @@
-# Core Data Structures
+# Core
 
 English | [中文](core.zh.md)
 
-This page catalogs the **core** data structures of the DeepSeek Harness — what each spine type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around. The sibling subsystem pages are indexed in the [folder README](README.md).
+The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns the spine's shared vocabulary — the `Agent` handle, its delivery and interception contracts, and the repo-wide type patterns — and orients to the group's dedicated pages; the folder is indexed in the [subsystems README](README.md).
 
-## What counts as "core"
+## The spine, package by package
 
-The harness is a microkernel: a tiny core plus many plugins. Most types belong to one plugin or one capability. A handful, though, are the **spine** — the language the agent loop and its events traffic in on *every* turn, no matter which optional plugins are loaded. Those are "core".
+A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it.
 
-Precisely, a data structure is **core** if either:
+| Package | Owns | Page |
+|---|---|---|
+| `session/` | The append-only `SessionEvent` log and in-memory store — the single source of truth (`ctx.sessions`) | [session.md](session.md) |
+| `system-prompt/` | Prompt-section and tool-schema assembly (`ctx.systemPrompt`) | [system-prompt.md](system-prompt.md) |
+| `tools/` | The scoped tool registry and guarded execution pipeline (`ctx.tools`) | [tools.md](tools.md) |
+| `agent/` | The `Agent` interface, live registry, initiator scope, and `agent/*` event vocabulary (`ctx.agents`) | this page |
+| `agent-loop/` | The concrete driver implementing the public `Agent` contract (`ctx.agentLoop`) | this page |
+| `scope/` | The scoped-registration primitive the registries and loop build per-agent scoping on | [scope.md](scope.md) |
 
-1. it flows through the agent-loop spine — the loop holds it, derives it, streams it, or logs it on every turn (a `Message`, a `StreamChunk`, a `SessionEvent`, the `Agent` handle itself), independent of which plugins are present; **or**
-2. it is the single headline type a plugin author writes against a pipeline — `ToolDefinition` (what every tool *is*).
+`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
 
-Everything else is documented on its own subsystem page, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is another page’s detail.* So `ToolDefinition` is core, but the `ValueSchemaSpec`/`ParameterSchemaSpec` inference machinery that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on their own pages ([index](README.md)).
+<a id="what-counts-as-core"></a>
 
+## What this page owns
+
+The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md); the session-event, prompt-assembly, and tool vocabularies live on this group's dedicated pages above. What remains here is the vocabulary shared by everything: the `Agent` handle and its delivery, cancellation, and interception contracts (declared by `packages/core/agent`), the `SessionEvent` envelope, and the two type patterns every subsystem follows. The scoping rule is recorded in the [subsystems-catalog Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md): the type you write, hold, or receive is documented where its declaring subsystem is; the machinery that types, renders, or persists it stays on that machinery's page.
 
 ## The `…Map → derived-union` pattern
 
@@ -37,13 +46,14 @@ declare module '@deepseek-ai/dsh-llm' {
 }
 ```
 
-Five canonical maps use this pattern; a plugin author extends these:
+Six canonical maps use this pattern; a plugin author extends these:
 
 | Map | Package | Derives | Catalog |
 |---|---|---|---|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [below](#content-blocks-and-messages) |
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [below](#content-blocks-and-messages) |
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [below](#the-model-request-and-result) |
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
 | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
 | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
 
@@ -64,458 +74,6 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
 
-## Content blocks and messages
-
-A conversation is `Message`s; a message is an array of typed **content blocks**. The block union derives from `ContentBlockMap`.
-
-Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ToolCallBlock` (`id: CallId`, `name`, raw-JSON `arguments`), `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the merge-extensible map together with the adapter/UI/compaction support that honors it.
-
-Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
-
-A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:
-
-```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
-interface AssistantProvenance {
-  /** Provider route that produced the message. */
-  provider: string
-  /** Provider model id that produced the message. */
-  model: string
-  /**
-   * Lossless-JSON adapter state needed to replay the provider response.
-   * `LlmService` exposes it to a target adapter only when that adapter instance
-   * currently owns both this historical provider and the target provider.
-   */
-  replayState?: unknown
-}
-```
-
-```ts type-equiv
-/** One immutable message representation shared by delivery, durable history, and model requests. */
-interface Message {
-  /** Stable identity preserved across every representation boundary. */
-  readonly id: MessageId
-  /** Provider-neutral conversation role. */
-  readonly role: 'system' | 'user' | 'assistant'
-  /** Exact model-facing blocks. */
-  readonly content: ContentBlock[]
-  /** Required producer provenance. */
-  readonly source: MessageSource
-}
-```
-
-Where a message came from is itself a merge-extensible sum type:
-
-```ts type-equiv
-/**
- * Where a message (or injected content) came from.
- * Merge-extensible sum type — plugins add their own `kind`s.
- */
-interface MessageSourceMap {
-  user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
-  model: ModelMessageSource
-  tool: ToolMessageSource
-}
-```
-
-Provenance and shape are two independent axes. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
-
-```ts type-equiv
-/**
- * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
- *
- * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
- * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
- *
- * The vocabulary is SEMANTIC, never visual: a value states that the content is
- * a file's instructions or a catalog of available items, and a consumer decides
- * what that looks like. Colors, icons, ordering, and collapse defaults are the
- * consumer's business and must not enter this union. It grows one value at a
- * time as producers gain the structured fields their form needs; an absent or
- * unknown value is the documented default, presented as opaque content.
- */
-type ContextForm =
-  /** Instructions read out of workspace files the model is expected to follow. */
-  | 'instructions'
-  /** A catalog of items available in this session, republished as it changes. */
-  | 'catalog'
-  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
-  | 'snapshot'
-  /** A one-off account of something that just happened; it supersedes nothing. */
-  | 'notice'
-  /** A message another agent addressed to this one. */
-  | 'relay'
-  /** Material lifted out of another session's log, possibly reduced on the way in. */
-  | 'recall'
-```
-
-```ts type-equiv
-/** One named contribution to a `snapshot`-form context, in assembly order. */
-interface ContextSnapshotSection {
-  /** The contributing subsystem's name. */
-  readonly name: string
-  /** That contribution's model-facing text, exactly as assembled. */
-  readonly text: string
-}
-```
-
-```ts type-equiv
-/**
- * Producer-declared {@link ContextForm} and the fields that form requires,
- * mixed into the source shapes that carry one.
- *
- * Discriminated by `form` so a producer cannot declare a shape without the
- * facts that shape is presented from: a `notice` must record its one-line
- * account, a `snapshot` its sections. Omitting `form` stays valid — an
- * undeclared context is the documented default.
- */
-type ContextFormed =
-  | { readonly form?: never }
-  | { readonly form: 'instructions' }
-  | { readonly form: 'catalog' }
-  | {
-    readonly form: 'snapshot'
-    /** The named contributions this snapshot assembled, in order. */
-    readonly sections: readonly ContextSnapshotSection[]
-  }
-  | {
-    readonly form: 'notice'
-    /** One-line account of what happened, shown without expanding the row. */
-    readonly summary: string
-  }
-  | { readonly form: 'relay' }
-  | { readonly form: 'recall' }
-```
-
-## Streaming
-
-Adapters emit a raw **chunk** protocol; the loop logs the chunks (replay fidelity) while feeding the same chunks through a `BlockAssembler` to rebuild blocks and messages. `StreamChunk` is a closed discriminated union over `type` — `block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`.
-
-The full union, the adapter contract (usage-before-finish, raw-JSON tool arguments, the two sanctioned error paths), and `BlockAssembler` live on **[llm-streaming.md](llm-streaming.md)**.
-
-<a id="the-model-request-and-result"></a>
-
-## The model request
-
-One model call is a fully-assembled `GenerateOptions`. The adapter answers with a raw `StreamChunk` stream; the consumer assembles it with `BlockAssembler` (see [llm-streaming.md](llm-streaming.md)).
-
-Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-Provider and model discovery uses small provider-neutral descriptors. A model catalog is advisory: routing still keys on a registered provider, and an adapter may accept unlisted model ids.
-
-Registering an adapter returns a handle: the disposer, plus the atomic route replacement a plugin whose route set is user-configurable needs.
-
-```ts type-equiv
-/**
- * What {@link LlmService.registerAdapter} returns: the disposer, plus an
- * atomic route replacement for the same adapter instance.
- */
-interface AdapterRegistrationHandle {
-  /** Release every route this registration currently holds. */
-  (): void
-  /**
-   * Replace this registration's routes with `providers`, keeping the same
-   * adapter instance. The candidate set is validated in full first — a
-   * conflict with another adapter, an invalid name, or bad provider metadata
-   * throws and leaves the current routes untouched — and the swap itself is
-   * one synchronous section, so no request can observe a gap. An empty array
-   * is legal here (a settings section that emptied holds zero routes while
-   * staying registered), unlike an empty initial registration.
-   *
-   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
-   * has been released: its routes are gone and its disposer has already run,
-   * so anything registered afterwards would have no owner left to release it.
-   * @param providers - the complete next route set for this registration.
-   */
-  replace(providers: string[]): void
-}
-```
-
-```ts type-equiv
-/** Display metadata for one registered provider route. */
-interface LlmProviderInfo {
-  /** Provider route key used by {@link GenerateOptions.provider}. */
-  id: string
-  /** Human-readable provider name for selectors and diagnostics. */
-  name: string
-}
-```
-
-Adapter plugins additionally declare which routes *could* run through `registerConfigurableProviders()`, addressing each one's user-settings section, so configuration surfaces can offer dormant providers before any route registers.
-
-```ts type-equiv
-/**
- * One provider route an adapter plugin can activate through configuration,
- * whether or not the route is currently registered. Configuration surfaces
- * merge this directory with `listProviders()` to offer every configurable
- * provider alongside its live/dormant state.
- */
-interface LlmConfigurableProvider {
-  /** Provider route key this entry activates when configured. */
-  provider: string
-  /** Human-readable provider name for configuration surfaces. */
-  displayName: string
-  /** User-settings namespace whose section configures this provider. */
-  settingsNs: string
-  /**
-   * Path from that namespace's section root to this provider's profile
-   * object; empty when the whole section is the profile.
-   */
-  settingsPath: readonly string[]
-}
-```
-
-```ts type-equiv
-/** One adapter-discovered model; catalog membership is advisory, not request validation. */
-interface LlmModelInfo {
-  /** Provider route that owns this model entry. */
-  provider: string
-  /** Model id passed to {@link GenerateOptions.model}. */
-  id: string
-  /** Human-readable model name for selectors. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar models. */
-  description?: string
-}
-```
-
-A provider a surface is still drafting has no route and no catalog, so interrogation is described separately: the request carries the draft the user is editing, and the reply is candidates a surface may adopt rather than a catalog it must serve.
-
-```ts type-equiv
-/**
- * One interrogation of a provider endpoint that configuration has not stored
- * yet. Configuration surfaces send the draft a user is still editing, so the
- * request carries the endpoint and credential directly instead of naming a
- * route: a provider being added has no route to name.
- */
-interface LlmModelDiscoveryRequest {
-  /**
-   * Route the draft is editing, when it edits an existing one. A route whose
-   * adapter already knows its models answers from that knowledge instead of
-   * asking the endpoint — the adapter's own registry is the better answer, and
-   * it costs no network call.
-   */
-  provider?: string
-  /**
-   * Endpoint to interrogate. Optional because a route the adapter already
-   * describes needs none; a route it does not must supply one.
-   */
-  baseURL?: string
-  /** Wire protocol the endpoint speaks, when the draft names one. */
-  api?: string
-  /** Credential for this interrogation alone; the harness never stores it. */
-  apiKey?: string
-  /** Caller cancellation; implementations must settle promptly after it aborts. */
-  signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/**
- * One model an endpoint reports about itself. Every field but the id is
- * optional because most provider listings disclose an id and nothing else;
- * a surface adopting one of these still owes the capacities its adapter needs.
- */
-interface LlmDiscoveredModel {
-  /** Model id the endpoint accepts. */
-  id: string
-  /** Human-readable name when the endpoint supplies one. */
-  name?: string
-  /** Maximum combined request and response context, when disclosed. */
-  contextWindow?: number
-  /** Maximum output tokens, when disclosed. */
-  maxTokens?: number
-}
-```
-
-Correctness-sensitive metadata is resolved separately from the advisory catalog and is owned by the adapter serving the exact route. Context capacity, adapter call defaults, and reasoning choices share one exact-model result so consumers do not repeat authoritative model resolution.
-
-```ts type-equiv
-/** Provider-owned context capacity for one exact provider/model route. */
-interface LlmModelContext {
-  /** Maximum combined request and response context in tokens. */
-  contextWindow: number
-}
-```
-
-Reasoning effort is another exact-route capability. The core brands identifiers but does not enumerate their values; each adapter owns the ordered set, display names, and optional deployment default.
-
-```ts type-equiv
-/** Adapter-owned identifier for one model's selectable reasoning effort. */
-type ReasoningEffortId = Branded<'ReasoningEffortId'>
-```
-
-```ts type-equiv
-/** Display metadata for one adapter-owned reasoning effort. */
-interface LlmReasoningEffortInfo {
-  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
-  id: ReasoningEffortId
-  /** Human-readable effort name for selectors and diagnostics. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar efforts. */
-  description?: string
-}
-```
-
-```ts type-equiv
-/** Selectable reasoning efforts for one exact provider/model route. */
-interface LlmModelReasoningInfo {
-  /** Supported efforts in adapter-preferred display order. */
-  efforts: readonly LlmReasoningEffortInfo[]
-  /**
-   * Adapter-configured default materialized into requests when callers omit
-   * an effort. Absence preserves the provider's own default.
-   */
-  defaultEffort?: ReasoningEffortId
-}
-```
-
-```ts type-equiv
-/** Exact-route model metadata resolved by its owning adapter. */
-interface LlmResolvedModelInfo extends LlmModelInfo {
-  /** Provider-owned context capacity when known. */
-  context?: LlmModelContext
-  /** Adapter-configured per-request output cap materialized when callers omit one. */
-  defaultMaxTokens?: number
-  /** Adapter-owned selectable reasoning levels when exposed. */
-  reasoning?: LlmModelReasoningInfo
-}
-```
-
-```ts type-equiv
-/** A single model request, fully assembled. */
-interface GenerateOptions {
-  /** Registered provider route selecting the adapter instance. */
-  provider: string
-  model: string
-  /** Adapter-owned reasoning effort selected for this exact model. */
-  reasoningEffort?: ReasoningEffortId
-  /**
-   * Ordered conversation messages, exactly as the provider sees them (after
-   * the `system` slot). A loop-built request assembles them as
-   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
-   */
-  messages: Message[]
-  /** System prompt text (adapters map to the provider's system slot). */
-  system?: string
-  /** Tool schemas (adapters map to the provider's `tools` field). */
-  tools?: ToolSchema[]
-  temperature?: number
-  maxTokens?: number
-  /**
-   * Stop sequences: generation halts as soon as the model produces any one of
-   * these strings (adapters map to the provider's stop field, e.g. OpenAI
-   * `stop`). The stop string itself is not included in the output.
-   */
-  stop?: string[]
-  signal?: AbortSignal
-  /**
-   * Session identity stamped by the loop for listener routing. Adapters ignore
-   * it; replay uses it to keep concurrent parent and child cursors independent.
-   */
-  sessionId?: Branded<'SessionId'>
-  /**
-   * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata or purpose-specific
-   * generation policy. Ordinary conversation requests leave it unset.
-   */
-  purpose?: 'compaction' | 'session-title'
-}
-```
-
-Why a model response stopped is a merge-extensible reason. Terminal provider failures carry the streaming contract's [`LlmFailure`](llm-streaming.md#llmfailure):
-
-```ts type-equiv
-/**
- * Why a model response stopped.
- * Merge-extensible so adapters can surface provider-specific reasons.
- */
-interface FinishReasonMap {
-  'stop': { kind: 'stop' }
-  'tool-calls': { kind: 'tool-calls' }
-  'max-tokens': { kind: 'max-tokens' }
-  'aborted': { kind: 'aborted'; failure: LlmFailure }
-  'error': { kind: 'error'; failure: LlmFailure }
-}
-```
-
-`FinishReason = FinishReasonMap[keyof FinishReasonMap]`. `TokenUsage` (per-call accounting with disjoint cache fields) is detailed on [llm-streaming.md](llm-streaming.md).
-
-`GenerateOptions.tools` carries `ToolSchema` — the JSON-schema description of a tool, as sent to the model. It is declared in dsh-llm (not dsh-tools) precisely because it is part of the request the loop assembles every step:
-
-```ts type-equiv
-/**
- * JSON-schema description of a tool, as sent to the model.
- *
- * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
- * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
- * it from this package.
- */
-interface ToolSchema {
-  name: string
-  description: string
-  /** JSON Schema object for the arguments. */
-  parameters: Record<string, unknown>
-}
-```
-
-The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
-
-### The request envelope: `LlmCallConfig` and the logged header
-
-The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
-
-`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus provenance under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
-
-On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
-
-```ts type-equiv
-/**
- * Provider, model, reasoning effort, and sampling scalars of one conversation's
- * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
- * the loop builds requests from the logged header rather than accepting these
- * per call.
- */
-interface LlmCallConfig {
-  provider: string
-  model: string
-  reasoningEffort?: ReasoningEffortId
-  temperature?: number
-  maxTokens?: number
-  stop?: string[]
-}
-```
-
-```ts type-equiv
-/**
- * Effective config fields supplied by exact-model adapter resolution rather
- * than by the caller's request proposal.
- */
-interface LlmCallConfigAdapterDefaults {
-  reasoningEffort?: true
-  maxTokens?: true
-}
-```
-
 ## Sessions
 
 A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. The event vocabulary derives from `SessionEventMap`:
@@ -531,7 +89,7 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`).
+ * `assistant/message`, `tool/result`, `steering/message`).
  * Non-surface events (boundary markers, chunks, usage, errors) never carry
  * surface metadata — the compiler enforces this at `Session.append()`
  * call sites.
@@ -559,7 +117,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-The session event variants, `deriveMessages()` projection rules, `TurnEndReason` vocabulary, and execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
 
 ## The agent handle
 
@@ -568,11 +126,72 @@ The session event variants, `deriveMessages()` projection rules, `TurnEndReason`
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
-/** One of the two ordered pending-message lists owned by an agent. */
-type InboxTarget = 'next-turn' | 'next-step'
+/**
+ * Which inbox queue a {@link Agent.send} item joins:
+ * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
+ * - `next-step` — during prompt admission or an open turn, the item stages for
+ *   the next safe step boundary; otherwise it is promoted per its `wakeup`
+ *   flag.
+ */
+type SendTarget = 'next-turn' | 'next-step'
 ```
 
-Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. `Inbox.append`, `prepend`, `replace`, `remove`, `clear`, `splice`, and `claim` record normalized durable `agent/inbox/spliced` mutations and reject duplicate pending ids. `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists; replacement may change identity and emits the old message as discarded followed by the new message as inserted. Ordinary removals and `clear()` are cancellations. `claim(target)` removes the proposed step batch — all `next-step` input plus, at a turn boundary, one `next-turn` message — through pure deletion splices without emitting discarded notifications, and the loop separately emits per-message claimed notifications. Whole-queue consumers such as UI projections reconstruct `nextTurn` and `nextStep` from the durable splices, while consumers following one message use the exact `agent/inbox/inserted`, `claimed`, and `discarded` notifications.
+```ts type-equiv
+/** Resolved inbox placement reported when an accepted message is enqueued. */
+type InboxPlacement = 'queued' | 'steering'
+```
+
+`InboxItemId` is a process-local branded string minted for each accepted FIFO occurrence. It is intentionally distinct from `MessageId`: sending the same immutable message twice creates two independently addressable pending items.
+
+```ts type-equiv
+/** One independently addressable accepted occurrence in an agent inbox. */
+interface InboxItem {
+  /** Agent-loop-minted occurrence identity. */
+  readonly id: InboxItemId
+  /** Identified message delivered by the caller. */
+  readonly message: UserMessage
+  /** Acceptance-time FIFO classification. */
+  readonly placement: InboxPlacement
+}
+```
+
+```ts type-equiv
+/** A user-requested mutation of one still-pending queued occurrence. */
+type InboxAction =
+  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
+  | { readonly kind: 'remove' }
+  | { readonly kind: 'steer' }
+```
+
+```ts type-equiv
+/** Result of applying an inbox action at the synchronous ownership boundary. */
+type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
+```
+
+```ts type-equiv
+/**
+ * Options for the unified {@link Agent.send} primitive over the
+ * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
+ * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
+ * {@link Agent.inject} (`next-step`/no-wakeup).
+ *
+ * The object is complete so routing policy is explicit.
+ */
+interface SendOptions {
+  /** Queue the item joins. */
+  target: SendTarget
+  /**
+   * Whether this item makes the model run: wake a parked driver (`next-turn`)
+   * or force a continuation step (`next-step` while running). A `false`
+   * `next-turn` item queues without waking; a `false`
+   * `next-step` item attaches durable context without forcing another step
+   * (the injection preset).
+   */
+  wakeup: boolean
+}
+```
+
+The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable when an edit replaces content or strict steer transfers the immutable message. The original queued occurrence ends and strict steer accepts a new steering occurrence with a distinct `InboxItemId`. Injection bypasses the FIFOs and never appears on inbox lifecycle events.
 
 ```ts type-equiv
 /** Options for {@link Agent.cancel}. */
@@ -580,25 +199,28 @@ interface CancelOptions {
   /**
    * Preserve queued and steering inbox items instead of discarding them. The
    * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no canceled inbox splice is logged.
+   * later turn and no `agent/inbox/discard` fires.
    */
-  keepInbox?: boolean | undefined
+  keepInbox?: boolean
 }
 ```
 
+`SteeringReceipt.outcome` always resolves. `admitted` identifies the turn and step whose immutable request history contains that exact message; `rejected` means lifecycle or terminal policy discarded it first. Synchronous input validation still throws from `steer()`.
+
 ```ts type-equiv
-/** Why an active agent driver was cancelled. */
+/** Stable runtime cause accepted by {@link Agent.cancel}. */
 type AgentCancelCause =
   | { readonly kind: 'user' }
   | { readonly kind: 'parent' }
-  | { readonly kind: 'hook'; readonly reason: string }
-  | { readonly kind: 'disposed' }
 ```
 
-`Agent` is an interface over the public live-agent contract. Its unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases.
+`Agent` is an interface over the public live-agent contract. Concrete drivers own the `followup`/`steer`/`inject` aliases and route them through `send`'s (`target` × `wakeup`) matrix.
 
 ```ts type-equiv
-/** Public live-agent handle. */
+/**
+ * Public live-agent handle with aliases over the unified delivery primitive.
+ * @typert object
+ */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -606,28 +228,78 @@ interface Agent {
   readonly options: AgentOptions
   /** The live session this agent drives; its log is the durable source of truth. */
   readonly session: Session
-  /** The agent-owned projection of durable pending work. */
-  readonly inbox: Inbox
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
+  /**
+   * Whether a `next-step` send currently stages for prompt admission or the
+   * open turn. Unlike {@link status}, this excludes admission exit and turn
+   * settlement, when a waking `next-step` send becomes a queued follow-up.
+   */
+  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
+  /**
+   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
+   * It routes the caller's typed content and source as follows:
+   *
+   * - `next-turn` queues an item that becomes the sole ordinary message of its
+   *   own FIFO-ordered turn; `wakeup:true` wakes a
+   *   parked driver, while `wakeup:false` queues without waking.
+   * - `next-step` with `wakeup:true` stages steering during prompt admission
+   *   or an open turn; outside that window it falls back to a woken
+   *   `next-turn`.
+   * - `next-step` with `wakeup:false` injects durable model-facing context
+   *   without running the model: admission or an open turn stages it for the
+   *   next safe log position, while an injection outside that window appends
+   *   immediately without opening a turn. If admission closes without a turn,
+   *   a context-only boundary appends immediately; context staged beside
+   *   steering remains pending with it.
+   * The agent publishes or queues the identified frozen message as-is.
+   * @param message - identified model-facing content and its producer provenance.
+   * @param options - target queue and wakeup decision.
+   */
+  send(message: UserMessage, options: SendOptions): void
+
+  /**
+   * Reserve admission of the next ordinary turn while this agent is idle, so an
+   * operation can mutate durable history before any queued prompt derives a
+   * request from it. Already-accepted waking work has right of way, including a
+   * send whose wake is still a pending microtask. Later sends keep their
+   * ordinary placement, FIFO order, and `wakeup` facts, and
+   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
+   * a queued follow-up rather than steering; cancellation and disposal may
+   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
+   * a live reservation as activity, while lifecycle teardown does not await it.
+   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
+   */
+  reserveTurnAdmission(): (() => void) | undefined
+
+  /**
+   * Mutate one still-pending queued occurrence synchronously. Editing preserves
+   * the message identity and queue position; removal publishes its terminal
+   * discard. Steer strictly transfers the message into the current next-step
+   * window, or returns `steer-unavailable` without changing the queued
+   * occurrence. Steering occurrences and driver-claimed items return
+   * `not-found`.
+   * @param id - independently addressable queued occurrence.
+   * @param action - edit, remove, or strict steer operation.
+   * @returns the applied outcome or the reason no mutation occurred.
+   */
+  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
+
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn or between-turn task. The first cause wins for that activity. With no
-   * active activity, cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the active operation signal.
+   * turn. An effective call first emits `agent/cancel-requested` with the
+   * resolved typed cause. The first cause wins for the active turn, and
+   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
+   * cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the current turn signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /**
-   * Resolve after the current whole-agent activity reaches quiescence. This
-   * follows replacement work started before the observed driver retires,
-   * but does not identify the settlement of any particular message.
-   * @returns fulfillment after no active driver or maintenance task remains.
-   */
+  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
   whenIdle(): Promise<void>
 
   /**
@@ -662,29 +334,35 @@ interface Agent {
   followup(message: UserMessage): void
 
   /**
-   * Submit steering for the nearest step. An idle driver starts a turn;
-   * a running driver consumes it at its next step boundary.
-   * A rejected step leaves steering parked in the inbox until the next
-   * wake; cancellation or disposal may discard pending steering.
+   * Submit steering with a message-owned admission receipt — the
+   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
+   * open turn, the message waits in the steering FIFO until a committed step
+   * snapshots it; outside that window it enters the ordinary queued FIFO. The
+   * receipt resolves `admitted` only after the message joins that step's
+   * immutable request history, or `rejected` when terminal policy,
+   * cancellation, or disposal discards it first. A non-terminal turn close may
+   * leave it staged for a later admitted prompt without settling the receipt.
    * @param message - identified steering content and its producer provenance.
+   * @returns the receipt for this exact message's eventual admission outcome.
    */
-  steer(message: UserMessage): void
+  steer(message: UserMessage): SteeringReceipt
 
   /**
-   * Queue model-facing context for the next pre-step without waking the
-   * driver. A running driver claims it at the nearest later step boundary;
-   * idle drivers leave it pending until follow-up or steering
-   * wakes them. It may miss a request whose pre-step already claimed its
-   * batch. Cancellation or disposal may discard pending context.
+   * Append model-facing context without running the model — the
+   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
+   * stages it at the next safe log position; outside that window it appends
+   * immediately without opening a turn. If admission closes without a turn,
+   * a context-only boundary appends immediately; context staged beside
+   * steering remains pending with it.
    * @param message - identified injected context and its producer provenance.
    */
   inject(message: UserMessage): void
 }
 ```
 
-`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox insertion, claim, and discard facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
+`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. A live turn-admission reservation is quiescence-relevant without changing `status` or turning later queue entries into steering; its only authority is to defer the next driver claim until release. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
 
-The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
+The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
@@ -694,19 +372,22 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
+Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
-`agent/pre-step` receives one payload carrying the exclusive claimed batch (`messages`), the proposed step's coordinates (`turn`, `step`), and the current turn's cancellation `signal`. The initial proposal runs inside an open turn before any step; a tool continuation may submit an empty claimed batch between steps:
-
-It returns a `PreStepDecision`. Reject opens no step. Enter supplies the complete message batch appended after `step/start`; claimed messages omitted by the final decision remain removed, while input inserted after the claim stays pending:
+`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow may rewrite the claimed prompt or attach `additionalContexts`; block rejects admission without creating turn events:
 
 ```ts type-equiv
-/** Whether and with which messages the loop enters a proposed step. */
-type PreStepDecision =
-  | { kind: 'reject' }
-  | { kind: 'enter'; messages: UserMessage[] }
+/**
+ * Prompt interception result. `allow.content` replaces the prompt, while
+ * `additionalContexts` appends model-facing context before the turn starts.
+ * An `allow` returned by a listener is authoritative: a listener wrapping
+ * `next()` preserves both fields unless it intentionally replaces them.
+ */
+type PromptDecision =
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
+  | { kind: 'block'; reason: string }
 ```
 
 `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal.
@@ -716,7 +397,12 @@ type PreStepDecision =
 type RequestErrorAction = { kind: 'retry' } | undefined
 ```
 
-`agent/pre-step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
+```ts type-equiv
+/** Model-request failure with an optional machine-routable provider code. */
+type RequestError = Error & { code?: string }
+```
+
+`agent/step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
 
 `agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
 
@@ -776,7 +462,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -954,6 +640,29 @@ Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/i
 
 ### `agent/*` events
 
+<a id="agentcancel-requested--emit"></a>
+
+#### `agent/cancel-requested` — emit
+
+Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
+
+```ts cordis-catalog
+/**
+ * Effective broad cancellation was requested, before queued/outbox work
+ * is cleared or the active turn is aborted. This observe-only notification
+ * cannot veto cancellation; listener failures are contained.
+ * @param agent - the agent whose current work is being cancelled.
+ * @param cause - the explicit typed cancellation cause.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
+
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -967,11 +676,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * @param agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -989,11 +698,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param payload.agent - the exact agent removed from the registry.
+ * @param agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1004,111 +713,138 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here even when
- * the error has no in-turn position for a durable record.
- * @param payload.agent - the agent whose turn errored.
- * @param payload.turn - the turn in which the failure surfaced.
- * @param payload.step - the step at which the failure surfaced.
- * @param payload.error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here (plus the
+ * logger) even when the error has no in-turn position for a durable record.
+ * @param agent - the agent whose turn errored.
+ * @param turn - the turn in which the failure surfaced.
+ * @param step - the step at which the failure surfaced.
+ * @param error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxclaimed--emit"></a>
+<a id="agentinboxdequeue--emit"></a>
 
-#### `agent/inbox/claimed` — emit
+#### `agent/inbox/dequeue` — emit
 
-One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
 
 ```ts cordis-catalog
 /**
- * One message left the inbox inside its open turn. If the proposed step
- * is rejected, the claimed message ends here: it is neither discarded nor
- * re-emitted as a user/message, and the turn closes without a step.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the claimed message.
- * @param payload.turn - the owning turn.
+ * The driver claimed one item out of the inbox: a queued item at a turn
+ * boundary, or steering drained between steps. Fires after the item leaves
+ * its FIFO and before it becomes a durable message.
+ * @param agent - the agent whose inbox item was claimed.
+ * @param item - the exact claimed occurrence.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscarded--emit"></a>
+<a id="agentinboxdiscard--emit"></a>
 
-#### `agent/inbox/discarded` — emit
+#### `agent/inbox/discard` — emit
 
-One message was discarded from the live inbox.
+Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
 
 ```ts cordis-catalog
 /**
- * One message was discarded from the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the discarded message.
+ * Pending inbox items were dropped without delivering them, so every
+ * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
+ * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
+ * emits this after `agent/cancel-requested` when applicable and before
+ * aborting the active work. Fires once per drop with every dropped item.
+ * @param agent - the agent whose inbox items were dropped.
+ * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxinserted--emit"></a>
+<a id="agentinboxenqueue--emit"></a>
 
-#### `agent/inbox/inserted` — emit
+#### `agent/inbox/enqueue` — emit
 
-One message entered the live inbox.
+An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
 
 ```ts cordis-catalog
 /**
- * One message entered the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the inserted message.
+ * An item entered the queued or steering inbox. `placement` is the
+ * acceptance-time routing result; listeners must not reconstruct it from
+ * later agent or session state.
+ * @param agent - the owning agent.
+ * @param item - accepted occurrence, message, and resolved placement.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentpre-step--waterfall"></a>
+<a id="agentinboxupdate--emit"></a>
 
-#### `agent/pre-step` — waterfall
+#### `agent/inbox/update` — emit
 
-Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
 
 ```ts cordis-catalog
 /**
- * Reject a proposed step or replace the messages that enter it. Calling
- * `next()` preserves the current messages.
- * @param payload.agent - the agent proposing the step.
- * @param payload.messages - messages removed from the inbox for this step.
- * @param payload.turn - the turn that will own the step.
- * @param payload.step - the step proposed by the loop.
- * @param payload.signal - the current turn's cancellation signal.
+ * A still-pending queued item changed content. The item id, placement, and
+ * position remain stable while the event carries the replacement message.
+ * @param agent - the owning agent.
+ * @param item - the complete post-update occurrence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
+
+<a id="agentprompt-submit--waterfall"></a>
+
+#### `agent/prompt-submit` — waterfall
+
+Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
+
+```ts cordis-catalog
+/**
+ * Allow, rewrite, or block one claimed prompt before it becomes a user
+ * message or opens a turn. Call `next()` for the unchanged default. The
+ * signal controls only this admission attempt; listeners may cooperate with
+ * it but must not retain it for a later attempt or turn.
+ * @param agent - the agent whose turn claimed the message.
+ * @param message - the frozen claimed message, including identity and source.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -1127,17 +863,17 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param payload.agent - the agent making the model call.
- * @param payload.turn - the open turn number.
- * @param payload.step - the step whose request this is.
- * @param payload.signal - the current turn's explicit abort signal.
+ * @param agent - the agent making the model call.
+ * @param turn - the open turn number.
+ * @param step - the step whose request this is.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Scoped](scope.md)
+Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
@@ -1145,25 +881,28 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle one failed model-request attempt before the loop retries or closes
- * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
- * when it owns recovery, or calls `next()` to delegate. The default
- * `undefined` leaves the failure terminal.
- * @param payload.agent - the agent whose request failed.
- * @param payload.turn - the turn containing the failed request.
- * @param payload.step - the step containing the failed request attempt.
- * @param payload.provider - the provider selected for the failed request.
- * @param payload.failure - serializable facts normalized at the final adapter boundary.
- * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
- * @param payload.signal - the turn abort signal.
+ * Handle a model-request failure after its failed step has closed but
+ * before the failed turn closes. A listener returns `{ kind: 'retry' }`
+ * without calling `next()` when it owns the error, or calls `next()` to
+ * delegate. The default `undefined` leaves the failure terminal.
+ * @param agent - the agent whose request failed.
+ * @param turn - the open turn number.
+ * @param step - the failed step number.
+ * @param error - the original model-request failure.
+ * @param failure - serializable facts normalized at the final adapter boundary.
+ * @param priorFailures - immutable failures that already authorized another
+ * retry turn in this consecutive sequence.
+ * @param retryPolicy - immutable policy of the adapter registration that served
+ * the failed request, or `undefined` if no final adapter served it.
+ * @param signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -1182,12 +921,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param payload.agent - the agent whose session lifecycle began.
- * @param payload.source - why the session started (fresh startup, resume, …).
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1198,19 +937,18 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
- * `running` synchronously after reserving cancellation; `idle` means no
- * driver remains scheduled or active.
- * @param payload.agent - the agent whose status flipped.
- * @param payload.status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
+ * `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1221,7 +959,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
 
 ```ts cordis-catalog
 /**
@@ -1231,17 +969,14 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step. The conclusion
- * never short-circuits already-submitted next-step work: same-step
- * `additionalContexts` or racing steering still runs, and the turn
- * closes only when that inbox drains.
- * @param payload.agent - the agent whose turn is at its stop boundary.
- * @param payload.turn - the turn about to close.
- * @param payload.signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step.
+ * @param agent - the agent whose turn is at its stop boundary.
+ * @param turn - the turn about to close.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -1264,12 +999,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param payload.sessionId - exact shared agent/session identity that failed startup.
- * @param payload.error - persistence, setup, or publication failure.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index fff5bd502c..276dc4f99f 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -1,22 +1,29 @@
-# 核心数据结构
+# 核心
 
 [English](core.md) | 中文
 
-本页编目 DeepSeek Harness 的**核心**数据结构：每个主干类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。同级的各子系统页面见[目录 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有主干的共享词汇——`Agent` 句柄及其投递与拦截契约，以及全仓通用的类型模式——并指引到该组的专属页面；目录索引见[子系统 README](README.md)。
 
-## 什么算"核心"
+## 主干逐包速览
 
-harness 是一个微内核：一个极小的核心加上众多插件。大多数类型属于某一个插件或某一项能力。但有少数类型构成**主干**——agent loop（智能体循环）及其事件在*每一个*轮次中使用的语言，无论加载了哪些可选插件。这些就是"核心"。
+一个轮次按同一条循环流经六个包：[`agent-loop`](../../packages/core/agent-loop) 中的 driver 认领一条排队的 prompt，在[会话日志](session.md)（`ctx.sessions`）上开启轮次，通过 [system-prompt](system-prompt.md)（`ctx.systemPrompt`）组装请求前缀并从日志派生历史，经 [LLM seam](llm-streaming.md) 流式获取模型响应，经[工具注册表](tools.md)（`ctx.tools`）分发工具调用，并把每个模型可见的事实追加回日志，供下一步派生。
 
-精确地说，一个数据结构是**核心**的，当且仅当满足以下条件之一：
+| 包 | 负责内容 | 页面 |
+|---|---|---|
+| `session/` | 只追加的 `SessionEvent` 日志与内存 store——唯一事实来源（`ctx.sessions`） | [session.md](session.md) |
+| `system-prompt/` | 提示词段落与工具 schema 组装（`ctx.systemPrompt`） | [system-prompt.md](system-prompt.md) |
+| `tools/` | 带作用域的工具注册表与受保护的执行流水线（`ctx.tools`） | [tools.md](tools.md) |
+| `agent/` | `Agent` 接口、实时注册表、发起者作用域与 `agent/*` 事件词汇（`ctx.agents`） | 本页 |
+| `agent-loop/` | 实现公开 `Agent` 契约的具体 driver（`ctx.agentLoop`） | 本页 |
+| `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
-1. 它流经 agent loop 主干——循环在每个轮次中持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄本身），与当前加载了哪些插件无关；**或者**
-2. 它是插件作者面向某条流水线编写的代表性类型——`ToolDefinition`（每个工具*是什么*）。
+`scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
 
-其他一切都记录在各自的子系统页面上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是其他页面的细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们各有自己的页面（[目录](README.md)）。
+<a id="what-counts-as-core"></a>
 
+## 本页拥有什么
 
-<a id="the-map--derived-union-pattern"></a>
+循环搬运的对话词汇——`Message`、`ContentBlock`、`StreamChunk`、模型请求——由 [`packages/llm`](../../packages/llm/README.md) 声明，记录在 [llm-streaming.md](llm-streaming.md)；会话事件、提示词组装与工具词汇在上表该组的专属页面。留在本页的是所有部分共享的词汇：`Agent` 句柄及其投递、取消与拦截契约（由 `packages/core/agent` 声明）、`SessionEvent` 信封，以及每个子系统都遵循的两个类型模式。范围界定规则记录在[子系统目录 Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md)：你编写、持有或接收的类型记录在其声明子系统所在之处；为它提供类型推导、渲染或持久化的机制留在该机制自己的页面。
 
 ## `…Map → derived-union` 模式
 
@@ -39,13 +46,14 @@ declare module '@deepseek-ai/dsh-llm' {
 }
 ```
 
-五个规范 map 使用此模式；插件作者扩展它们：
+六个规范 map 使用此模式；插件作者扩展它们：
 
 | Map | 包 | 派生 | 目录 |
 |---|---|---|---|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [下文](#content-blocks-and-messages) |
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [下文](#content-blocks-and-messages) |
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [下文](#the-model-request-and-result) |
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
 | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
 | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
 
@@ -68,460 +76,6 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 两个核心 ID 是 `CallId`（关联工具调用及其结果；dsh-llm）和 `SessionId`（活跃 agent 与持久会话共享的标识；dsh-session）。能力包也会品牌化各自的 id，例如 [tasks.md](tasks.md) 中的 `TaskId`。
 
-<a id="content-blocks-and-messages"></a>
-
-## 内容块与消息
-
-一段对话由 `Message` 组成；一条消息是一个类型化**内容块**的数组。块的联合类型从 `ContentBlockMap` 派生。
-
-源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-各块接口（完整字段见源码）：`TextBlock`（`text`）、`ReasoningBlock`（thinking，区别于可见文本）、`ToolCallBlock`（`id: CallId`、`name`、原始 JSON `arguments`）、`ToolResultBlock`（`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`）。`ContentBlock = ContentBlockMap[ContentBlockType]`。核心集仅限于每条交付路径都尊重的块——多模态内容（图像、音频等）没有核心块类型；需要的功能通过可合并扩展的 map 添加，同时提供适配器/UI/压缩支持。
-
-源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
-
-`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：
-
-```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
-interface AssistantProvenance {
-  /** Provider route that produced the message. */
-  provider: string
-  /** Provider model id that produced the message. */
-  model: string
-  /**
-   * Lossless-JSON adapter state needed to replay the provider response.
-   * `LlmService` exposes it to a target adapter only when that adapter instance
-   * currently owns both this historical provider and the target provider.
-   */
-  replayState?: unknown
-}
-```
-
-```ts type-equiv
-/** One immutable message representation shared by delivery, durable history, and model requests. */
-interface Message {
-  /** Stable identity preserved across every representation boundary. */
-  readonly id: MessageId
-  /** Provider-neutral conversation role. */
-  readonly role: 'system' | 'user' | 'assistant'
-  /** Exact model-facing blocks. */
-  readonly content: ContentBlock[]
-  /** Required producer provenance. */
-  readonly source: MessageSource
-}
-```
-
-消息来源本身也是一个可合并扩展的和类型：
-
-```ts type-equiv
-/**
- * Where a message (or injected content) came from.
- * Merge-extensible sum type — plugins add their own `kind`s.
- */
-interface MessageSourceMap {
-  user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
-  model: ModelMessageSource
-  tool: ToolMessageSource
-}
-```
-
-溯源与形态是相互独立的两根轴。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
-
-```ts type-equiv
-/**
- * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
- *
- * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
- * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
- *
- * The vocabulary is SEMANTIC, never visual: a value states that the content is
- * a file's instructions or a catalog of available items, and a consumer decides
- * what that looks like. Colors, icons, ordering, and collapse defaults are the
- * consumer's business and must not enter this union. It grows one value at a
- * time as producers gain the structured fields their form needs; an absent or
- * unknown value is the documented default, presented as opaque content.
- */
-type ContextForm =
-  /** Instructions read out of workspace files the model is expected to follow. */
-  | 'instructions'
-  /** A catalog of items available in this session, republished as it changes. */
-  | 'catalog'
-  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
-  | 'snapshot'
-  /** A one-off account of something that just happened; it supersedes nothing. */
-  | 'notice'
-  /** A message another agent addressed to this one. */
-  | 'relay'
-  /** Material lifted out of another session's log, possibly reduced on the way in. */
-  | 'recall'
-```
-
-```ts type-equiv
-/** One named contribution to a `snapshot`-form context, in assembly order. */
-interface ContextSnapshotSection {
-  /** The contributing subsystem's name. */
-  readonly name: string
-  /** That contribution's model-facing text, exactly as assembled. */
-  readonly text: string
-}
-```
-
-```ts type-equiv
-/**
- * Producer-declared {@link ContextForm} and the fields that form requires,
- * mixed into the source shapes that carry one.
- *
- * Discriminated by `form` so a producer cannot declare a shape without the
- * facts that shape is presented from: a `notice` must record its one-line
- * account, a `snapshot` its sections. Omitting `form` stays valid — an
- * undeclared context is the documented default.
- */
-type ContextFormed =
-  | { readonly form?: never }
-  | { readonly form: 'instructions' }
-  | { readonly form: 'catalog' }
-  | {
-    readonly form: 'snapshot'
-    /** The named contributions this snapshot assembled, in order. */
-    readonly sections: readonly ContextSnapshotSection[]
-  }
-  | {
-    readonly form: 'notice'
-    /** One-line account of what happened, shown without expanding the row. */
-    readonly summary: string
-  }
-  | { readonly form: 'relay' }
-  | { readonly form: 'recall' }
-```
-
-## 流式输出
-
-适配器发出原始**分片**协议；循环记录分片（回放保真度），同时将同一批分片送入 `BlockAssembler` 以重建块和消息。`StreamChunk` 是基于 `type` 的封闭判别联合——`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`。
-
-完整联合类型、适配器契约（usage-before-finish、原始 JSON 工具参数、两条认可的错误路径）和 `BlockAssembler` 在 **[llm-streaming.md](llm-streaming.md)** 中。
-
-<a id="the-model-request-and-result"></a>
-
-## 模型请求
-
-一次模型调用是一个完全组装好的 `GenerateOptions`。适配器以原始 `StreamChunk` 流作答；消费方用 `BlockAssembler` 组装它（见 [llm-streaming.md](llm-streaming.md)）。
-
-源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-提供方与模型发现使用小型、提供方无关的描述符。模型目录仅供参考：路由仍以已注册提供方为键，适配器也可以接受未列出的模型 id。
-
-注册适配器会返回一个句柄：既是释放器，也带有原子的路由替换——路由集合由用户配置决定的插件正需要它。
-
-```ts type-equiv
-/**
- * What {@link LlmService.registerAdapter} returns: the disposer, plus an
- * atomic route replacement for the same adapter instance.
- */
-interface AdapterRegistrationHandle {
-  /** Release every route this registration currently holds. */
-  (): void
-  /**
-   * Replace this registration's routes with `providers`, keeping the same
-   * adapter instance. The candidate set is validated in full first — a
-   * conflict with another adapter, an invalid name, or bad provider metadata
-   * throws and leaves the current routes untouched — and the swap itself is
-   * one synchronous section, so no request can observe a gap. An empty array
-   * is legal here (a settings section that emptied holds zero routes while
-   * staying registered), unlike an empty initial registration.
-   *
-   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
-   * has been released: its routes are gone and its disposer has already run,
-   * so anything registered afterwards would have no owner left to release it.
-   * @param providers - the complete next route set for this registration.
-   */
-  replace(providers: string[]): void
-}
-```
-
-```ts type-equiv
-/** Display metadata for one registered provider route. */
-interface LlmProviderInfo {
-  /** Provider route key used by {@link GenerateOptions.provider}. */
-  id: string
-  /** Human-readable provider name for selectors and diagnostics. */
-  name: string
-}
-```
-
-适配器插件还会通过 `registerConfigurableProviders()` 声明哪些路由*可以*运行，并指明每条路由的用户设置分节，使配置界面能在任何路由注册之前就呈现休眠的提供方。
-
-```ts type-equiv
-/**
- * One provider route an adapter plugin can activate through configuration,
- * whether or not the route is currently registered. Configuration surfaces
- * merge this directory with `listProviders()` to offer every configurable
- * provider alongside its live/dormant state.
- */
-interface LlmConfigurableProvider {
-  /** Provider route key this entry activates when configured. */
-  provider: string
-  /** Human-readable provider name for configuration surfaces. */
-  displayName: string
-  /** User-settings namespace whose section configures this provider. */
-  settingsNs: string
-  /**
-   * Path from that namespace's section root to this provider's profile
-   * object; empty when the whole section is the profile.
-   */
-  settingsPath: readonly string[]
-}
-```
-
-```ts type-equiv
-/** One adapter-discovered model; catalog membership is advisory, not request validation. */
-interface LlmModelInfo {
-  /** Provider route that owns this model entry. */
-  provider: string
-  /** Model id passed to {@link GenerateOptions.model}. */
-  id: string
-  /** Human-readable model name for selectors. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar models. */
-  description?: string
-}
-```
-
-界面正在起草的提供方既没有路由也没有 catalog，因此询问被单独描述：请求携带用户正在编辑的草稿，回复是界面可以采纳的候选，而不是它必须服务的 catalog。
-
-```ts type-equiv
-/**
- * One interrogation of a provider endpoint that configuration has not stored
- * yet. Configuration surfaces send the draft a user is still editing, so the
- * request carries the endpoint and credential directly instead of naming a
- * route: a provider being added has no route to name.
- */
-interface LlmModelDiscoveryRequest {
-  /**
-   * Route the draft is editing, when it edits an existing one. A route whose
-   * adapter already knows its models answers from that knowledge instead of
-   * asking the endpoint — the adapter's own registry is the better answer, and
-   * it costs no network call.
-   */
-  provider?: string
-  /**
-   * Endpoint to interrogate. Optional because a route the adapter already
-   * describes needs none; a route it does not must supply one.
-   */
-  baseURL?: string
-  /** Wire protocol the endpoint speaks, when the draft names one. */
-  api?: string
-  /** Credential for this interrogation alone; the harness never stores it. */
-  apiKey?: string
-  /** Caller cancellation; implementations must settle promptly after it aborts. */
-  signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/**
- * One model an endpoint reports about itself. Every field but the id is
- * optional because most provider listings disclose an id and nothing else;
- * a surface adopting one of these still owes the capacities its adapter needs.
- */
-interface LlmDiscoveredModel {
-  /** Model id the endpoint accepts. */
-  id: string
-  /** Human-readable name when the endpoint supplies one. */
-  name?: string
-  /** Maximum combined request and response context, when disclosed. */
-  contextWindow?: number
-  /** Maximum output tokens, when disclosed. */
-  maxTokens?: number
-}
-```
-
-对正确性敏感的元数据与参考目录分开解析，并归服务该确切路由的适配器所有。上下文容量、适配器调用默认值和推理选项共用同一个确切模型结果，消费方因而无需重复执行权威模型解析。
-
-```ts type-equiv
-/** Provider-owned context capacity for one exact provider/model route. */
-interface LlmModelContext {
-  /** Maximum combined request and response context in tokens. */
-  contextWindow: number
-}
-```
-
-推理强度是另一项针对确切路由的能力。核心为标识符添加品牌类型，但不枚举其值；有序集合、展示名称和可选的部署默认值均由各适配器持有。
-
-```ts type-equiv
-/** Adapter-owned identifier for one model's selectable reasoning effort. */
-type ReasoningEffortId = Branded<'ReasoningEffortId'>
-```
-
-```ts type-equiv
-/** Display metadata for one adapter-owned reasoning effort. */
-interface LlmReasoningEffortInfo {
-  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
-  id: ReasoningEffortId
-  /** Human-readable effort name for selectors and diagnostics. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar efforts. */
-  description?: string
-}
-```
-
-```ts type-equiv
-/** Selectable reasoning efforts for one exact provider/model route. */
-interface LlmModelReasoningInfo {
-  /** Supported efforts in adapter-preferred display order. */
-  efforts: readonly LlmReasoningEffortInfo[]
-  /**
-   * Adapter-configured default materialized into requests when callers omit
-   * an effort. Absence preserves the provider's own default.
-   */
-  defaultEffort?: ReasoningEffortId
-}
-```
-
-```ts type-equiv
-/** Exact-route model metadata resolved by its owning adapter. */
-interface LlmResolvedModelInfo extends LlmModelInfo {
-  /** Provider-owned context capacity when known. */
-  context?: LlmModelContext
-  /** Adapter-configured per-request output cap materialized when callers omit one. */
-  defaultMaxTokens?: number
-  /** Adapter-owned selectable reasoning levels when exposed. */
-  reasoning?: LlmModelReasoningInfo
-}
-```
-
-```ts type-equiv
-/** A single model request, fully assembled. */
-interface GenerateOptions {
-  /** Registered provider route selecting the adapter instance. */
-  provider: string
-  model: string
-  /** Adapter-owned reasoning effort selected for this exact model. */
-  reasoningEffort?: ReasoningEffortId
-  /**
-   * Ordered conversation messages, exactly as the provider sees them (after
-   * the `system` slot). A loop-built request assembles them as
-   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
-   */
-  messages: Message[]
-  /** System prompt text (adapters map to the provider's system slot). */
-  system?: string
-  /** Tool schemas (adapters map to the provider's `tools` field). */
-  tools?: ToolSchema[]
-  temperature?: number
-  maxTokens?: number
-  /**
-   * Stop sequences: generation halts as soon as the model produces any one of
-   * these strings (adapters map to the provider's stop field, e.g. OpenAI
-   * `stop`). The stop string itself is not included in the output.
-   */
-  stop?: string[]
-  signal?: AbortSignal
-  /**
-   * Session identity stamped by the loop for listener routing. Adapters ignore
-   * it; replay uses it to keep concurrent parent and child cursors independent.
-   */
-  sessionId?: Branded<'SessionId'>
-  /**
-   * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata or purpose-specific
-   * generation policy. Ordinary conversation requests leave it unset.
-   */
-  purpose?: 'compaction' | 'session-title'
-}
-```
-
-模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](llm-streaming.md#llmfailure)：
-
-```ts type-equiv
-/**
- * Why a model response stopped.
- * Merge-extensible so adapters can surface provider-specific reasons.
- */
-interface FinishReasonMap {
-  'stop': { kind: 'stop' }
-  'tool-calls': { kind: 'tool-calls' }
-  'max-tokens': { kind: 'max-tokens' }
-  'aborted': { kind: 'aborted'; failure: LlmFailure }
-  'error': { kind: 'error'; failure: LlmFailure }
-}
-```
-
-`FinishReason = FinishReasonMap[keyof FinishReasonMap]`。`TokenUsage`（逐调用计量，含不相交的缓存字段）详见 [llm-streaming.md](llm-streaming.md)。
-
-`GenerateOptions.tools` 携带 `ToolSchema`——工具的 JSON Schema 描述，发送给模型。它声明在 dsh-llm（而非 dsh-tools）中，正是因为它是循环每一步组装请求的一部分：
-
-```ts type-equiv
-/**
- * JSON-schema description of a tool, as sent to the model.
- *
- * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
- * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
- * it from this package.
- */
-interface ToolSchema {
-  name: string
-  description: string
-  /** JSON Schema object for the arguments. */
-  parameters: Record<string, unknown>
-}
-```
-
-面向模型的 `ToolSchema` 是协议格式；产出它的已注册 `ToolDefinition`（schema + `execute`）在 [tools.md](tools.md) 中。
-
-### 请求信封：`LlmCallConfig` 与记录的 header
-
-循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
-
-`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置及其来源。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
-
-在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
-
-```ts type-equiv
-/**
- * Provider, model, reasoning effort, and sampling scalars of one conversation's
- * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
- * the loop builds requests from the logged header rather than accepting these
- * per call.
- */
-interface LlmCallConfig {
-  provider: string
-  model: string
-  reasoningEffort?: ReasoningEffortId
-  temperature?: number
-  maxTokens?: number
-  stop?: string[]
-}
-```
-
-```ts type-equiv
-/**
- * Effective config fields supplied by exact-model adapter resolution rather
- * than by the caller's request proposal.
- */
-interface LlmCallConfigAdapterDefaults {
-  reasoningEffort?: true
-  maxTokens?: true
-}
-```
-
 ## 会话
 
 `Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。事件词汇从 `SessionEventMap` 派生：
@@ -537,7 +91,7 @@ interface LlmCallConfigAdapterDefaults {
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`).
+ * `assistant/message`, `tool/result`, `steering/message`).
  * Non-surface events (boundary markers, chunks, usage, errors) never carry
  * surface metadata — the compiler enforces this at `Session.append()`
  * call sites.
@@ -565,7 +119,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-会话事件变体、`deriveMessages()` 投影规则、`TurnEndReason` 词汇以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
+十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
 
 <a id="the-agent-handle"></a>
 
@@ -576,11 +130,72 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
-/** One of the two ordered pending-message lists owned by an agent. */
-type InboxTarget = 'next-turn' | 'next-step'
+/**
+ * Which inbox queue a {@link Agent.send} item joins:
+ * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
+ * - `next-step` — during prompt admission or an open turn, the item stages for
+ *   the next safe step boundary; otherwise it is promoted per its `wakeup`
+ *   flag.
+ */
+type SendTarget = 'next-turn' | 'next-step'
 ```
 
-每个待处理入队项就是其 `UserMessage`；`MessageId` 是唯一标识。`Inbox.append`、`prepend`、`replace`、`remove`、`clear`、`splice` 与 `claim` 会记录规范化的持久 `agent/inbox/spliced` 变更，并拒绝重复的待处理 id。`replace(messageId, newMessage)` 与 `remove(messageId)` 通过 `MessageId` 跨两份列表定位待处理消息；替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。普通删除和 `clear()` 都表示取消。`claim(target)` 通过无 outcome 的纯删除 splice 移除拟进入步骤的批次——全部 `next-step` 输入，外加轮次边界上的一条 `next-turn` 消息——且不发出 discarded 通知；循环另行逐条发出 claimed 通知。UI 投影等整体队列消费方通过持久 splice 重建 `nextTurn` 与 `nextStep`，而跟踪单条消息的消费方使用精确的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知。
+```ts type-equiv
+/** Resolved inbox placement reported when an accepted message is enqueued. */
+type InboxPlacement = 'queued' | 'steering'
+```
+
+`InboxItemId` 是为每次获准进入 FIFO 的项铸造的进程本地品牌字符串。它有意区别于 `MessageId`：同一条不可变消息发送两次，会创建两个可独立寻址的待处理项。
+
+```ts type-equiv
+/** One independently addressable accepted occurrence in an agent inbox. */
+interface InboxItem {
+  /** Agent-loop-minted occurrence identity. */
+  readonly id: InboxItemId
+  /** Identified message delivered by the caller. */
+  readonly message: UserMessage
+  /** Acceptance-time FIFO classification. */
+  readonly placement: InboxPlacement
+}
+```
+
+```ts type-equiv
+/** A user-requested mutation of one still-pending queued occurrence. */
+type InboxAction =
+  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
+  | { readonly kind: 'remove' }
+  | { readonly kind: 'steer' }
+```
+
+```ts type-equiv
+/** Result of applying an inbox action at the synchronous ownership boundary. */
+type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
+```
+
+```ts type-equiv
+/**
+ * Options for the unified {@link Agent.send} primitive over the
+ * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
+ * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
+ * {@link Agent.inject} (`next-step`/no-wakeup).
+ *
+ * The object is complete so routing policy is explicit.
+ */
+interface SendOptions {
+  /** Queue the item joins. */
+  target: SendTarget
+  /**
+   * Whether this item makes the model run: wake a parked driver (`next-turn`)
+   * or force a continuation step (`next-step` while running). A `false`
+   * `next-turn` item queues without waking; a `false`
+   * `next-step` item attaches durable context without forcing another step
+   * (the injection preset).
+   */
+  wakeup: boolean
+}
+```
+
+固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。编辑替换内容或严格 steering（中途引导）转移不可变消息时，其 `MessageId` 都保持稳定。原 queued 单次入队项会结束，严格 steering 则接受一个具有不同 `InboxItemId` 的新 steering 单次入队项。注入绕过两个 FIFO，从不出现在 inbox 生命周期事件中。
 
 ```ts type-equiv
 /** Options for {@link Agent.cancel}. */
@@ -588,25 +203,28 @@ interface CancelOptions {
   /**
    * Preserve queued and steering inbox items instead of discarding them. The
    * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no canceled inbox splice is logged.
+   * later turn and no `agent/inbox/discard` fires.
    */
-  keepInbox?: boolean | undefined
+  keepInbox?: boolean
 }
 ```
 
+`SteeringReceipt.outcome` 始终会解析。`admitted` 标识其不可变请求历史包含该确切消息的轮次与步骤；`rejected` 表示生命周期或终止策略先丢弃了该消息。同步输入校验仍会从 `steer()` 抛出异常。
+
 ```ts type-equiv
-/** Why an active agent driver was cancelled. */
+/** Stable runtime cause accepted by {@link Agent.cancel}. */
 type AgentCancelCause =
   | { readonly kind: 'user' }
   | { readonly kind: 'parent' }
-  | { readonly kind: 'hook'; readonly reason: string }
-  | { readonly kind: 'disposed' }
 ```
 
-`Agent` 是覆盖公开活跃 agent 契约的接口。它的统一 `send` 方法直接公开目标与唤醒路由；`followup`、`steer` 和 `inject` 是固定预设别名。
+`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器拥有 `followup`/`steer`/`inject` 别名方法，并将它们经由 `send` 的（`target` × `wakeup`）矩阵路由。
 
 ```ts type-equiv
-/** Public live-agent handle. */
+/**
+ * Public live-agent handle with aliases over the unified delivery primitive.
+ * @typert object
+ */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -614,28 +232,78 @@ interface Agent {
   readonly options: AgentOptions
   /** The live session this agent drives; its log is the durable source of truth. */
   readonly session: Session
-  /** The agent-owned projection of durable pending work. */
-  readonly inbox: Inbox
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
+  /**
+   * Whether a `next-step` send currently stages for prompt admission or the
+   * open turn. Unlike {@link status}, this excludes admission exit and turn
+   * settlement, when a waking `next-step` send becomes a queued follow-up.
+   */
+  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
+  /**
+   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
+   * It routes the caller's typed content and source as follows:
+   *
+   * - `next-turn` queues an item that becomes the sole ordinary message of its
+   *   own FIFO-ordered turn; `wakeup:true` wakes a
+   *   parked driver, while `wakeup:false` queues without waking.
+   * - `next-step` with `wakeup:true` stages steering during prompt admission
+   *   or an open turn; outside that window it falls back to a woken
+   *   `next-turn`.
+   * - `next-step` with `wakeup:false` injects durable model-facing context
+   *   without running the model: admission or an open turn stages it for the
+   *   next safe log position, while an injection outside that window appends
+   *   immediately without opening a turn. If admission closes without a turn,
+   *   a context-only boundary appends immediately; context staged beside
+   *   steering remains pending with it.
+   * The agent publishes or queues the identified frozen message as-is.
+   * @param message - identified model-facing content and its producer provenance.
+   * @param options - target queue and wakeup decision.
+   */
+  send(message: UserMessage, options: SendOptions): void
+
+  /**
+   * Reserve admission of the next ordinary turn while this agent is idle, so an
+   * operation can mutate durable history before any queued prompt derives a
+   * request from it. Already-accepted waking work has right of way, including a
+   * send whose wake is still a pending microtask. Later sends keep their
+   * ordinary placement, FIFO order, and `wakeup` facts, and
+   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
+   * a queued follow-up rather than steering; cancellation and disposal may
+   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
+   * a live reservation as activity, while lifecycle teardown does not await it.
+   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
+   */
+  reserveTurnAdmission(): (() => void) | undefined
+
+  /**
+   * Mutate one still-pending queued occurrence synchronously. Editing preserves
+   * the message identity and queue position; removal publishes its terminal
+   * discard. Steer strictly transfers the message into the current next-step
+   * window, or returns `steer-unavailable` without changing the queued
+   * occurrence. Steering occurrences and driver-claimed items return
+   * `not-found`.
+   * @param id - independently addressable queued occurrence.
+   * @param action - edit, remove, or strict steer operation.
+   * @returns the applied outcome or the reason no mutation occurred.
+   */
+  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
+
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn or between-turn task. The first cause wins for that activity. With no
-   * active activity, cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the active operation signal.
+   * turn. An effective call first emits `agent/cancel-requested` with the
+   * resolved typed cause. The first cause wins for the active turn, and
+   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
+   * cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the current turn signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /**
-   * Resolve after the current whole-agent activity reaches quiescence. This
-   * follows replacement work started before the observed driver retires,
-   * but does not identify the settlement of any particular message.
-   * @returns fulfillment after no active driver or maintenance task remains.
-   */
+  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
   whenIdle(): Promise<void>
 
   /**
@@ -670,29 +338,35 @@ interface Agent {
   followup(message: UserMessage): void
 
   /**
-   * Submit steering for the nearest step. An idle driver starts a turn;
-   * a running driver consumes it at its next step boundary.
-   * A rejected step leaves steering parked in the inbox until the next
-   * wake; cancellation or disposal may discard pending steering.
+   * Submit steering with a message-owned admission receipt — the
+   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
+   * open turn, the message waits in the steering FIFO until a committed step
+   * snapshots it; outside that window it enters the ordinary queued FIFO. The
+   * receipt resolves `admitted` only after the message joins that step's
+   * immutable request history, or `rejected` when terminal policy,
+   * cancellation, or disposal discards it first. A non-terminal turn close may
+   * leave it staged for a later admitted prompt without settling the receipt.
    * @param message - identified steering content and its producer provenance.
+   * @returns the receipt for this exact message's eventual admission outcome.
    */
-  steer(message: UserMessage): void
+  steer(message: UserMessage): SteeringReceipt
 
   /**
-   * Queue model-facing context for the next pre-step without waking the
-   * driver. A running driver claims it at the nearest later step boundary;
-   * idle drivers leave it pending until follow-up or steering
-   * wakes them. It may miss a request whose pre-step already claimed its
-   * batch. Cancellation or disposal may discard pending context.
+   * Append model-facing context without running the model — the
+   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
+   * stages it at the next safe log position; outside that window it appends
+   * immediately without opening a turn. If admission closes without a turn,
+   * a context-only boundary appends immediately; context staged beside
+   * steering remains pending with it.
    * @param message - identified injected context and its producer provenance.
    */
   inject(message: UserMessage): void
 }
 ```
 
-`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 的插入、领取与丢弃事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[决策](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
+`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。活动的轮次接纳预留与完全停稳相关，但不会改变 `status`，也不会把之后的队列项变成 steering；它的唯一权限是将驱动器的下一次认领延迟到释放时。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
 
-cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
+cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。只有 loop 会在结算时从自己机器私有的 signal 上读回 cause（`user`、`parent` 或仅用于生命周期的 `disposed`）——不存在公开的读取器，signal 也不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
 [事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
@@ -702,19 +376,22 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有
 
 ## 拦截决策
 
-pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。
+提示词决策与工具后决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的标识与 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。
 
 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
-`agent/pre-step` 接收一个 payload，携带独占的已领取批次（`messages`）、拟进入步骤的坐标（`turn`、`step`）与当前轮次的取消 `signal`。首次提案在已打开的轮次内、任何步骤开始前运行；工具 continuation 可以在步骤之间提交空的已领取批次：
-
-它返回 `PreStepDecision`。reject 不会打开步骤。enter 提供在 `step/start` 后追加的完整消息批次；最终决策省略的已领取消息保持已删除，而领取后插入的输入仍留待后续处理：
+`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 可以改写已领取的提示词或附加 `additionalContexts`；block 拒绝准入且不产生任何轮次事件：
 
 ```ts type-equiv
-/** Whether and with which messages the loop enters a proposed step. */
-type PreStepDecision =
-  | { kind: 'reject' }
-  | { kind: 'enter'; messages: UserMessage[] }
+/**
+ * Prompt interception result. `allow.content` replaces the prompt, while
+ * `additionalContexts` appends model-facing context before the turn starts.
+ * An `allow` returned by a listener is authoritative: a listener wrapping
+ * `next()` preserves both fields unless it intentionally replaces them.
+ */
+type PromptDecision =
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
+  | { kind: 'block'; reason: string }
 ```
 
 `agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。
@@ -724,7 +401,12 @@ type PreStepDecision =
 type RequestErrorAction = { kind: 'retry' } | undefined
 ```
 
-`agent/pre-step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
+```ts type-equiv
+/** Model-request failure with an optional machine-routable provider code. */
+type RequestError = Error & { code?: string }
+```
+
+`agent/step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
 
 `agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）：
 
@@ -784,7 +466,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -962,6 +644,29 @@ Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/i
 
 ### `agent/*` events
 
+<a id="agentcancel-requested--emit"></a>
+
+#### `agent/cancel-requested` — emit
+
+Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
+
+```ts cordis-catalog
+/**
+ * Effective broad cancellation was requested, before queued/outbox work
+ * is cleared or the active turn is aborted. This observe-only notification
+ * cannot veto cancellation; listener failures are contained.
+ * @param agent - the agent whose current work is being cancelled.
+ * @param cause - the explicit typed cancellation cause.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
+
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -975,11 +680,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * @param agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -997,11 +702,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param payload.agent - the exact agent removed from the registry.
+ * @param agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1012,111 +717,138 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here even when
- * the error has no in-turn position for a durable record.
- * @param payload.agent - the agent whose turn errored.
- * @param payload.turn - the turn in which the failure surfaced.
- * @param payload.step - the step at which the failure surfaced.
- * @param payload.error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here (plus the
+ * logger) even when the error has no in-turn position for a durable record.
+ * @param agent - the agent whose turn errored.
+ * @param turn - the turn in which the failure surfaced.
+ * @param step - the step at which the failure surfaced.
+ * @param error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxclaimed--emit"></a>
+<a id="agentinboxdequeue--emit"></a>
 
-#### `agent/inbox/claimed` — emit
+#### `agent/inbox/dequeue` — emit
 
-One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
 
 ```ts cordis-catalog
 /**
- * One message left the inbox inside its open turn. If the proposed step
- * is rejected, the claimed message ends here: it is neither discarded nor
- * re-emitted as a user/message, and the turn closes without a step.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the claimed message.
- * @param payload.turn - the owning turn.
+ * The driver claimed one item out of the inbox: a queued item at a turn
+ * boundary, or steering drained between steps. Fires after the item leaves
+ * its FIFO and before it becomes a durable message.
+ * @param agent - the agent whose inbox item was claimed.
+ * @param item - the exact claimed occurrence.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscarded--emit"></a>
+<a id="agentinboxdiscard--emit"></a>
 
-#### `agent/inbox/discarded` — emit
+#### `agent/inbox/discard` — emit
 
-One message was discarded from the live inbox.
+Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
 
 ```ts cordis-catalog
 /**
- * One message was discarded from the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the discarded message.
+ * Pending inbox items were dropped without delivering them, so every
+ * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
+ * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
+ * emits this after `agent/cancel-requested` when applicable and before
+ * aborting the active work. Fires once per drop with every dropped item.
+ * @param agent - the agent whose inbox items were dropped.
+ * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxinserted--emit"></a>
+<a id="agentinboxenqueue--emit"></a>
 
-#### `agent/inbox/inserted` — emit
+#### `agent/inbox/enqueue` — emit
 
-One message entered the live inbox.
+An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
 
 ```ts cordis-catalog
 /**
- * One message entered the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the inserted message.
+ * An item entered the queued or steering inbox. `placement` is the
+ * acceptance-time routing result; listeners must not reconstruct it from
+ * later agent or session state.
+ * @param agent - the owning agent.
+ * @param item - accepted occurrence, message, and resolved placement.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentpre-step--waterfall"></a>
+<a id="agentinboxupdate--emit"></a>
 
-#### `agent/pre-step` — waterfall
+#### `agent/inbox/update` — emit
 
-Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
 
 ```ts cordis-catalog
 /**
- * Reject a proposed step or replace the messages that enter it. Calling
- * `next()` preserves the current messages.
- * @param payload.agent - the agent proposing the step.
- * @param payload.messages - messages removed from the inbox for this step.
- * @param payload.turn - the turn that will own the step.
- * @param payload.step - the step proposed by the loop.
- * @param payload.signal - the current turn's cancellation signal.
+ * A still-pending queued item changed content. The item id, placement, and
+ * position remain stable while the event carries the replacement message.
+ * @param agent - the owning agent.
+ * @param item - the complete post-update occurrence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
+
+<a id="agentprompt-submit--waterfall"></a>
+
+#### `agent/prompt-submit` — waterfall
+
+Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
+
+```ts cordis-catalog
+/**
+ * Allow, rewrite, or block one claimed prompt before it becomes a user
+ * message or opens a turn. Call `next()` for the unchanged default. The
+ * signal controls only this admission attempt; listeners may cooperate with
+ * it but must not retain it for a later attempt or turn.
+ * @param agent - the agent whose turn claimed the message.
+ * @param message - the frozen claimed message, including identity and source.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -1135,17 +867,17 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param payload.agent - the agent making the model call.
- * @param payload.turn - the open turn number.
- * @param payload.step - the step whose request this is.
- * @param payload.signal - the current turn's explicit abort signal.
+ * @param agent - the agent making the model call.
+ * @param turn - the open turn number.
+ * @param step - the step whose request this is.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Scoped](scope.md)
+Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
@@ -1153,25 +885,28 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle one failed model-request attempt before the loop retries or closes
- * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
- * when it owns recovery, or calls `next()` to delegate. The default
- * `undefined` leaves the failure terminal.
- * @param payload.agent - the agent whose request failed.
- * @param payload.turn - the turn containing the failed request.
- * @param payload.step - the step containing the failed request attempt.
- * @param payload.provider - the provider selected for the failed request.
- * @param payload.failure - serializable facts normalized at the final adapter boundary.
- * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
- * @param payload.signal - the turn abort signal.
+ * Handle a model-request failure after its failed step has closed but
+ * before the failed turn closes. A listener returns `{ kind: 'retry' }`
+ * without calling `next()` when it owns the error, or calls `next()` to
+ * delegate. The default `undefined` leaves the failure terminal.
+ * @param agent - the agent whose request failed.
+ * @param turn - the open turn number.
+ * @param step - the failed step number.
+ * @param error - the original model-request failure.
+ * @param failure - serializable facts normalized at the final adapter boundary.
+ * @param priorFailures - immutable failures that already authorized another
+ * retry turn in this consecutive sequence.
+ * @param retryPolicy - immutable policy of the adapter registration that served
+ * the failed request, or `undefined` if no final adapter served it.
+ * @param signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -1190,12 +925,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param payload.agent - the agent whose session lifecycle began.
- * @param payload.source - why the session started (fresh startup, resume, …).
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1206,19 +941,18 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
- * `running` synchronously after reserving cancellation; `idle` means no
- * driver remains scheduled or active.
- * @param payload.agent - the agent whose status flipped.
- * @param payload.status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
+ * `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1229,7 +963,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
 
 ```ts cordis-catalog
 /**
@@ -1239,17 +973,14 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step. The conclusion
- * never short-circuits already-submitted next-step work: same-step
- * `additionalContexts` or racing steering still runs, and the turn
- * closes only when that inbox drains.
- * @param payload.agent - the agent whose turn is at its stop boundary.
- * @param payload.turn - the turn about to close.
- * @param payload.signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step.
+ * @param agent - the agent whose turn is at its stop boundary.
+ * @param turn - the turn about to close.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -1272,12 +1003,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param payload.sessionId - exact shared agent/session identity that failed startup.
- * @param payload.error - persistence, setup, or publication failure.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index cadc2b92d8..e57b2aef45 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 1999399254fa5d72ab222a42a2fa8f4b890da50a
-filesystem.zh.md: 044a1c5be91ed8bec5d0442cc6f7edfde6870785
+filesystem.md: 591f1b4d4b1177ccbe7c2280d2054da5d4be8b99
+filesystem.zh.md: d599e48c1fba2d564a544f628ca3475b781e5cd5
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 1999399254..591f1b4d4b 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -256,6 +256,10 @@ type FsErrorCode =
 
 `FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) — the mode fence denied a write/edit — distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_STALE_VERSION` means the backend version no longer matches the observed one (or an edit hit a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
 
+## No timeouts on file IO
+
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+
 ## The service and the plugin
 
 `FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 044a1c5be9..d599e48c1f 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -256,6 +256,10 @@ type FsErrorCode =
 
 目录列表使用 `FS_NOT_DIRECTORY`、`FS_PERMISSION_DENIED` 与 `FS_IO_ERROR` 区分已存在但并非目录的目标、被拒绝的列表操作和意外的后端 I/O 失败。`FS_SANDBOX_DENIED` 是强制执行沙箱的后端（`dsh-fs-sandbox`）所作的策略拒绝——模式边界拒绝了写入/编辑——与 `FS_PERMISSION_DENIED`（宿主内核拒绝）不同。`FS_NOT_OBSERVED` 表示策略插件没有此所有者的先前观察记录（或 `createIfAbsent` 遇到了现有文件）。`FS_STALE_VERSION` 表示后端版本不再与观察到的版本匹配（或编辑操作遇到缺失目标）。新鲜度授权没有部分/完整之分，因此不存在 `FS_PARTIAL_OBSERVATION`。
 
+## 文件 IO 不设超时
+
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方 seam 也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+
 ## 服务与插件
 
 `FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index bd1d833f51..f6ce932ad9 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: fe4a831660dd81b33a1cd7dc9a9d7026f3831991
-llm-streaming.zh.md: a10b696ec0887e139785fc7e95d8641e6496de79
+llm-streaming.md: b3f850f4d07ad9e36d0e0db71dd9e0498e468767
+llm-streaming.zh.md: bb31c14b9bd0453399d83968b1062f67819caca3
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index fe4a831660..b3f850f4d0 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -2,10 +2,82 @@
 
 English | [中文](llm-streaming.zh.md)
 
-The wire-level streaming vocabulary of [dsh-llm](../../packages/llm/llm). [core.md](core.md) introduces `StreamChunk`, `Message`, and `ContentBlock`; this page owns the full chunk protocol, the adapter contract every adapter must obey, and the shared assembler.
+The conversation and streaming vocabulary of [`packages/llm`](../../packages/llm/README.md): the `Message`/`ContentBlock` shapes every request and durable history share, the fully-assembled model request, the raw `StreamChunk` protocol, the adapter contract every adapter must obey, and the shared assembler. The [core spine](core.md) holds and logs these values on every turn; this page declares them.
 
 Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
+<a id="content-blocks-and-messages"></a>
+
+## Content blocks and messages
+
+A conversation is `Message`s; a message is an array of typed **content blocks**. The block union derives from `ContentBlockMap`.
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+```ts type-equiv
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
+interface ContentBlockMap {
+  'text': TextBlock
+  'reasoning': ReasoningBlock
+  'tool-call': ToolCallBlock
+  'tool-result': ToolResultBlock
+}
+```
+
+The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ToolCallBlock` (`id: CallId`, `name`, raw-JSON `arguments`), `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the merge-extensible map together with the adapter/UI/compaction support that honors it.
+
+Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
+
+A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:
+
+```ts type-equiv
+/** Provider ownership and adapter-private replay data for an assistant message. */
+interface AssistantProvenance {
+  /** Provider route that produced the message. */
+  provider: string
+  /** Provider model id that produced the message. */
+  model: string
+  /**
+   * Lossless-JSON adapter state needed to replay the provider response.
+   * `LlmService` exposes it to a target adapter only when that adapter instance
+   * currently owns both this historical provider and the target provider.
+   */
+  replayState?: unknown
+}
+```
+
+```ts type-equiv
+/** One immutable message representation shared by delivery, durable history, and model requests. */
+interface Message {
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant'
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[]
+  /** Required producer provenance. */
+  readonly source: MessageSource
+}
+```
+
+Where a message came from is itself a merge-extensible sum type:
+
+```ts type-equiv
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
+interface MessageSourceMap {
+  user: { kind: 'user' }
+  plugin: { kind: 'plugin'; plugin: string }
+  model: ModelMessageSource
+  tool: ToolMessageSource
+}
+```
+
 ## `StreamChunk` — the raw protocol
 
 A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it.
@@ -15,9 +87,8 @@ A streaming response interleaves several typed blocks (text, reasoning, multiple
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. An adapter implementation
- * may throw, but `LlmService.stream()` normalizes that failure to a terminal
- * `error` or `aborted` finish before exposing it to consumers.
+ * afterward; tool arguments remain raw JSON strings. Failures either throw or
+ * end with `error`/`aborted`, and consumers must handle both paths.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -65,10 +136,10 @@ Every adapter MUST obey these, and every consumer may rely on them:
 - **Provider stalls are bounded at the transport.** Both shipping remote adapters expose positive finite `streamIdleTimeoutMs` with a five-minute default. The watchdog arms only while iterator `next()` is outstanding, uses one stable signal for the whole request, maps its own expiry to `TIMEOUT`, and keeps an earlier caller abort as `ABORTED`.
 - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
 - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
-- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below), the `User-Agent` baseline.
+- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
 - **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content and provenance without the private state.
 
-Two independent implementations obey this contract: `dsh-llm-deepseek` uses direct fetch with SSE framing through `eventsource-parser`, while `dsh-llm-pi-ai` provides a generic multi-provider adapter through `@earendil-works/pi-ai`. Both carry cancellation and the idle watchdog to the provider request.
+This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
 
 ## `ResolvedRetryPolicy`
 
@@ -142,9 +213,8 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index, except that max-token truncation drops
-   *   tool calls that cannot be executed safely; an open block assembles from
-   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -162,6 +232,263 @@ declare class BlockAssembler {
 }
 ```
 
+<a id="the-model-request-and-result"></a>
+
+## The model request
+
+One model call is a fully-assembled `GenerateOptions`. The adapter answers with a raw [`StreamChunk`](#streamchunk--the-raw-protocol) stream; the consumer assembles it with [`BlockAssembler`](#blockassembler).
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+Provider and model discovery uses small provider-neutral descriptors. A model catalog is advisory: routing still keys on a registered provider, and an adapter may accept unlisted model ids.
+
+Registering an adapter returns a handle: the disposer, plus the atomic route replacement a plugin whose route set is user-configurable needs.
+
+```ts type-equiv
+/**
+ * What {@link LlmService.registerAdapter} returns: the disposer, plus an
+ * atomic route replacement for the same adapter instance.
+ */
+interface AdapterRegistrationHandle {
+  /** Release every route this registration currently holds. */
+  (): void
+  /**
+   * Replace this registration's routes with `providers`, keeping the same
+   * adapter instance. The candidate set is validated in full first — a
+   * conflict with another adapter, an invalid name, or bad provider metadata
+   * throws and leaves the current routes untouched — and the swap itself is
+   * one synchronous section, so no request can observe a gap. An empty array
+   * is legal here (a settings section that emptied holds zero routes while
+   * staying registered), unlike an empty initial registration.
+   *
+   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+   * has been released: its routes are gone and its disposer has already run,
+   * so anything registered afterwards would have no owner left to release it.
+   * @param providers - the complete next route set for this registration.
+   */
+  replace(providers: string[]): void
+}
+```
+
+```ts type-equiv
+/** Display metadata for one registered provider route. */
+interface LlmProviderInfo {
+  /** Provider route key used by {@link GenerateOptions.provider}. */
+  id: string
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string
+}
+```
+
+Adapter plugins additionally declare which routes *could* run through `registerConfigurableProviders()`, addressing each one's user-settings section, so configuration surfaces can offer dormant providers before any route registers.
+
+```ts type-equiv
+/**
+ * One provider route an adapter plugin can activate through configuration,
+ * whether or not the route is currently registered. Configuration surfaces
+ * merge this directory with `listProviders()` to offer every configurable
+ * provider alongside its live/dormant state.
+ */
+interface LlmConfigurableProvider {
+  /** Provider route key this entry activates when configured. */
+  provider: string
+  /** Human-readable provider name for configuration surfaces. */
+  displayName: string
+  /** User-settings namespace whose section configures this provider. */
+  settingsNs: string
+  /**
+   * Path from that namespace's section root to this provider's profile
+   * object; empty when the whole section is the profile.
+   */
+  settingsPath: readonly string[]
+}
+```
+
+```ts type-equiv
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+interface LlmModelInfo {
+  /** Provider route that owns this model entry. */
+  provider: string
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string
+  /** Human-readable model name for selectors. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string
+}
+```
+
+Correctness-sensitive metadata is resolved separately from the advisory catalog and is owned by the adapter serving the exact route. Context capacity, adapter call defaults, and reasoning choices share one exact-model result so consumers do not repeat authoritative model resolution.
+
+```ts type-equiv
+/** Provider-owned context capacity for one exact provider/model route. */
+interface LlmModelContext {
+  /** Maximum combined request and response context in tokens. */
+  contextWindow: number
+}
+```
+
+Reasoning effort is another exact-route capability. The core brands identifiers but does not enumerate their values; each adapter owns the ordered set, display names, and optional deployment default.
+
+```ts type-equiv
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+type ReasoningEffortId = Branded<'ReasoningEffortId'>
+```
+
+```ts type-equiv
+/** Display metadata for one adapter-owned reasoning effort. */
+interface LlmReasoningEffortInfo {
+  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+  id: ReasoningEffortId
+  /** Human-readable effort name for selectors and diagnostics. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar efforts. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** Selectable reasoning efforts for one exact provider/model route. */
+interface LlmModelReasoningInfo {
+  /** Supported efforts in adapter-preferred display order. */
+  efforts: readonly LlmReasoningEffortInfo[]
+  /**
+   * Adapter-configured default materialized into requests when callers omit
+   * an effort. Absence preserves the provider's own default.
+   */
+  defaultEffort?: ReasoningEffortId
+}
+```
+
+```ts type-equiv
+/** Exact-route model metadata resolved by its owning adapter. */
+interface LlmResolvedModelInfo extends LlmModelInfo {
+  /** Provider-owned context capacity when known. */
+  context?: LlmModelContext
+  /** Adapter-configured per-request output cap materialized when callers omit one. */
+  defaultMaxTokens?: number
+  /** Adapter-owned selectable reasoning levels when exposed. */
+  reasoning?: LlmModelReasoningInfo
+}
+```
+
+```ts type-equiv
+/** A single model request, fully assembled. */
+interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string
+  model: string
+  /** Adapter-owned reasoning effort selected for this exact model. */
+  reasoningEffort?: ReasoningEffortId
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
+   */
+  messages: Message[]
+  /** System prompt text (adapters map to the provider's system slot). */
+  system?: string
+  /** Tool schemas (adapters map to the provider's `tools` field). */
+  tools?: ToolSchema[]
+  temperature?: number
+  maxTokens?: number
+  /**
+   * Stop sequences: generation halts as soon as the model produces any one of
+   * these strings (adapters map to the provider's stop field, e.g. OpenAI
+   * `stop`). The stop string itself is not included in the output.
+   */
+  stop?: string[]
+  signal?: AbortSignal
+  /**
+   * Session identity stamped by the loop for listener routing. Adapters ignore
+   * it; replay uses it to keep concurrent parent and child cursors independent.
+   */
+  sessionId?: Branded<'SessionId'>
+  /**
+   * Provider-neutral classification for an auxiliary model call. Adapters may
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
+   */
+  purpose?: 'compaction' | 'session-title'
+}
+```
+
+Why a model response stopped is a merge-extensible reason. Terminal provider failures carry the streaming contract's [`LlmFailure`](#llmfailure):
+
+```ts type-equiv
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
+interface FinishReasonMap {
+  'stop': { kind: 'stop' }
+  'tool-calls': { kind: 'tool-calls' }
+  'max-tokens': { kind: 'max-tokens' }
+  'aborted': { kind: 'aborted'; failure: LlmFailure }
+  'error': { kind: 'error'; failure: LlmFailure }
+}
+```
+
+`FinishReason = FinishReasonMap[keyof FinishReasonMap]`. `TokenUsage` (per-call accounting with disjoint cache fields) is detailed [below](#tokenusage).
+
+`GenerateOptions.tools` carries `ToolSchema` — the JSON-schema description of a tool, as sent to the model. It is declared in dsh-llm (not dsh-tools) precisely because it is part of the request the loop assembles every step:
+
+```ts type-equiv
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
+ * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
+interface ToolSchema {
+  name: string
+  description: string
+  /** JSON Schema object for the arguments. */
+  parameters: Record<string, unknown>
+}
+```
+
+The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
+
+### The request envelope: `LlmCallConfig` and the logged header
+
+The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
+
+`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus provenance under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
+
+On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
+
+FIXME(call-config-shape): revisit which remaining fields are genuinely epoch-level for cache purposes (`model` and the model-owned reasoning effort are explicit; the sampling scalars sit here out of caution).
+
+```ts type-equiv
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+interface LlmCallConfig {
+  provider: string
+  model: string
+  reasoningEffort?: ReasoningEffortId
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+}
+```
+
+```ts type-equiv
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+interface LlmCallConfigAdapterDefaults {
+  reasoningEffort?: true
+  maxTokens?: true
+}
+```
+
 ## The seam
 
 `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
@@ -171,8 +498,6 @@ declare class BlockAssembler {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
-  /** Immutable retry policy captured with the adapter registration. */
-  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -239,22 +564,7 @@ declare abstract class LlmAdapter {
 }
 ```
 
-`ContentBlockType` (the key set the `index`-correlated blocks carry) derives from `ContentBlockMap`:
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-See [core.md § Content blocks and messages](core.md#content-blocks-and-messages) for the block interfaces.
+`ContentBlockType` (the key set the `index`-correlated blocks carry) derives from [`ContentBlockMap`](#content-blocks-and-messages) above.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -293,9 +603,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns a handle that withdraws all of them, and can atomically replace them.
+ * @returns the disposer that withdraws all of them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -303,29 +613,6 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): Dire
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
-/**
- * Offer to interrogate provider endpoints on behalf of the settings
- * namespace this plugin owns. The namespace is the key because that is what
- * a configuration surface already holds from the configurable-provider
- * directory, and because a provider being *added* has no route to name yet.
- * Disposed with the fiber.
- * @param settingsNs - the namespace whose profiles this discovery serves.
- * @param discover - interrogates one endpoint; must honor `request.signal`.
- * @returns the disposer that withdraws the offer.
- */
-registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
-
-/**
- * Interrogate one provider endpoint for the models it advertises. The
- * request describes a draft, not a stored route, so nothing here reads or
- * writes settings or credentials — the caller owns both, and the reply is
- * candidate metadata a surface may offer for adoption.
- * @param settingsNs - namespace whose registered discovery serves this draft.
- * @param request - the endpoint, protocol, and one-shot credential to use.
- * @returns the advertised models, deduplicated in endpoint order.
- */
-async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
-
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -375,22 +662,22 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Replay state is
- * retained only when the same adapter instance owns its historical provider
- * and the target provider. Final adapter selection remains fixed through
- * asynchronous exact-model resolution and dispatch. Adapter selection,
- * dispatch, and iteration failures become terminal `error` or `aborted`
- * finish chunks; middleware, nested-call, cleanup, and consumer failures
- * remain thrown.
+ * Stream one model call as raw chunks (token-level deltas). Throws
+ * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
+ * `options.provider`. Replay state is retained only when the same adapter
+ * instance owns its historical provider and the target provider. Final
+ * adapter selection remains fixed through asynchronous exact-model resolution
+ * and dispatch. Selection, dispatch, and iteration failures retain their
+ * original Error identity and are tagged in a call-local scope for narrow
+ * agent-loop request recovery; middleware and nested-call failures remain
+ * untagged for the outer call.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -415,7 +702,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -439,7 +726,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index a10b696ec0..bb31c14b9b 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -2,10 +2,84 @@
 
 [English](llm-streaming.md) | 中文
 
-[dsh-llm](../../packages/llm/llm) 的协议格式（wire format）级流式输出词汇。[core.md](core.md) 介绍了 `StreamChunk`、`Message` 与 `ContentBlock`；本页拥有完整的分片协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。
+[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
 
 源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
+<a id="content-blocks-and-messages"></a>
+
+## 内容块与消息
+
+一段对话由 `Message` 组成；一条消息是一个类型化**内容块**的数组。块的联合类型从 `ContentBlockMap` 派生。
+
+源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+```ts type-equiv
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
+interface ContentBlockMap {
+  'text': TextBlock
+  'reasoning': ReasoningBlock
+  'tool-call': ToolCallBlock
+  'tool-result': ToolResultBlock
+}
+```
+
+各块接口（完整字段见源码）：`TextBlock`（`text`）、`ReasoningBlock`（thinking，区别于可见文本）、`ToolCallBlock`（`id: CallId`、`name`、原始 JSON `arguments`）、`ToolResultBlock`（`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`）。`ContentBlock = ContentBlockMap[ContentBlockType]`。核心集仅限于每条交付路径都尊重的块——多模态内容（图像、音频等）没有核心块类型；需要的功能通过可合并扩展的 map 添加，同时提供适配器/UI/压缩支持。
+
+源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
+
+`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：
+
+```ts type-equiv
+/** Provider ownership and adapter-private replay data for an assistant message. */
+interface AssistantProvenance {
+  /** Provider route that produced the message. */
+  provider: string
+  /** Provider model id that produced the message. */
+  model: string
+  /**
+   * Lossless-JSON adapter state needed to replay the provider response.
+   * `LlmService` exposes it to a target adapter only when that adapter instance
+   * currently owns both this historical provider and the target provider.
+   */
+  replayState?: unknown
+}
+```
+
+```ts type-equiv
+/** One immutable message representation shared by delivery, durable history, and model requests. */
+interface Message {
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant'
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[]
+  /** Required producer provenance. */
+  readonly source: MessageSource
+}
+```
+
+消息来源本身也是一个可合并扩展的和类型：
+
+```ts type-equiv
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
+interface MessageSourceMap {
+  user: { kind: 'user' }
+  plugin: { kind: 'plugin'; plugin: string }
+  model: ModelMessageSource
+  tool: ToolMessageSource
+}
+```
+
+<a id="streamchunk--the-raw-protocol"></a>
+
 ## `StreamChunk`：原始协议
 
 一个流式响应交错包含多种类型的块（文本、推理（reasoning）、多个工具调用）。`index` 将每个 delta 关联到其所属块；`block-end` 携带完整组装好的 `ContentBlock`，消费方无需自行重新组装 delta。这是一个**封闭的**可辨识联合类型：对 `type` 的 `switch` 以 `assertNever` 结尾，因此新增变体会在每个必须处理它的消费方处触发编译错误。
@@ -15,9 +89,8 @@
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. An adapter implementation
- * may throw, but `LlmService.stream()` normalizes that failure to a terminal
- * `error` or `aborted` finish before exposing it to consumers.
+ * afterward; tool arguments remain raw JSON strings. Failures either throw or
+ * end with `error`/`aborted`, and consumers must handle both paths.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -34,6 +107,8 @@ type StreamChunk =
   }
 ```
 
+<a id="llmfailure"></a>
+
 ## `LlmFailure`
 
 每个抛出的失败或最终适配器的带内失败都会规范化为一种可序列化、提供方无关的 payload。`providerRetryAfterMs` 是经校验、由提供方请求的正数延迟，而不是重试决策；`ProviderRequestId` 是用于诊断的不透明品牌字符串。
@@ -65,10 +140,10 @@ interface LlmFailure {
 - **提供方停顿在传输层受到时限约束。** 两个已交付的远程适配器都暴露正数且有限的 `streamIdleTimeoutMs`，默认五分钟。watchdog 只在 iterator `next()` 尚未完成时启动，整个请求使用同一个稳定 signal，把自身到期映射为 `TIMEOUT`，并把更早发生的调用方中止保留为 `ABORTED`。
 - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
-- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送下文的 `attributionHeaders()`，即 `User-Agent` 基线。
+- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
 
-两个彼此独立的实现遵循该契约：`dsh-llm-deepseek` 使用直接 fetch，并通过 `eventsource-parser` 进行 SSE（Server-Sent Events）分帧；`dsh-llm-pi-ai` 则通过 `@earendil-works/pi-ai` 提供通用多提供方适配器。两者都会把取消与空闲 watchdog 传递至提供方请求。
+该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
 ## `ResolvedRetryPolicy`
 
@@ -76,7 +151,7 @@ interface LlmFailure {
 
 ## `AppIdentity`：应用归属
 
-每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包 manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
 ```ts type-equiv
 /**
@@ -96,6 +171,8 @@ interface AppIdentity {
 }
 ```
 
+<a id="tokenusage"></a>
+
 ## `TokenUsage`
 
 逐调用 token 记账。各计数**互不重叠**：`inputTokens` 只包含未缓存输入；缓存输入单独报告，计费输入是三者之和。若提供方把缓存命中折入单一提示词总数（如 DeepSeek 的 `prompt_tokens`），适配器会再将其扣除。`reasoningTokens` 存在时只是信息性细节，已经包含在 `outputTokens` 中；汇总时不得重复相加。
@@ -118,6 +195,8 @@ interface TokenUsage {
 }
 ```
 
+<a id="blockassembler"></a>
+
 ## `BlockAssembler`
 
 `BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同其提供方/模型 provenance 一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
@@ -142,9 +221,8 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index, except that max-token truncation drops
-   *   tool calls that cannot be executed safely; an open block assembles from
-   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -162,6 +240,263 @@ declare class BlockAssembler {
 }
 ```
 
+<a id="the-model-request-and-result"></a>
+
+## 模型请求
+
+一次模型调用是一个完全组装好的 `GenerateOptions`。适配器以原始 [`StreamChunk`](#streamchunk--the-raw-protocol) 流作答；消费方用 [`BlockAssembler`](#blockassembler) 组装它。
+
+源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+提供方与模型发现使用小型、提供方无关的描述符。模型目录仅供参考：路由仍以已注册提供方为键，适配器也可以接受未列出的模型 id。
+
+注册适配器会返回一个句柄：既是释放器，也带有原子的路由替换——路由集合由用户配置决定的插件正需要它。
+
+```ts type-equiv
+/**
+ * What {@link LlmService.registerAdapter} returns: the disposer, plus an
+ * atomic route replacement for the same adapter instance.
+ */
+interface AdapterRegistrationHandle {
+  /** Release every route this registration currently holds. */
+  (): void
+  /**
+   * Replace this registration's routes with `providers`, keeping the same
+   * adapter instance. The candidate set is validated in full first — a
+   * conflict with another adapter, an invalid name, or bad provider metadata
+   * throws and leaves the current routes untouched — and the swap itself is
+   * one synchronous section, so no request can observe a gap. An empty array
+   * is legal here (a settings section that emptied holds zero routes while
+   * staying registered), unlike an empty initial registration.
+   *
+   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+   * has been released: its routes are gone and its disposer has already run,
+   * so anything registered afterwards would have no owner left to release it.
+   * @param providers - the complete next route set for this registration.
+   */
+  replace(providers: string[]): void
+}
+```
+
+```ts type-equiv
+/** Display metadata for one registered provider route. */
+interface LlmProviderInfo {
+  /** Provider route key used by {@link GenerateOptions.provider}. */
+  id: string
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string
+}
+```
+
+适配器插件还会通过 `registerConfigurableProviders()` 声明哪些路由*可以*运行，并指明每条路由的用户设置分节，使配置界面能在任何路由注册之前就呈现休眠的提供方。
+
+```ts type-equiv
+/**
+ * One provider route an adapter plugin can activate through configuration,
+ * whether or not the route is currently registered. Configuration surfaces
+ * merge this directory with `listProviders()` to offer every configurable
+ * provider alongside its live/dormant state.
+ */
+interface LlmConfigurableProvider {
+  /** Provider route key this entry activates when configured. */
+  provider: string
+  /** Human-readable provider name for configuration surfaces. */
+  displayName: string
+  /** User-settings namespace whose section configures this provider. */
+  settingsNs: string
+  /**
+   * Path from that namespace's section root to this provider's profile
+   * object; empty when the whole section is the profile.
+   */
+  settingsPath: readonly string[]
+}
+```
+
+```ts type-equiv
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+interface LlmModelInfo {
+  /** Provider route that owns this model entry. */
+  provider: string
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string
+  /** Human-readable model name for selectors. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string
+}
+```
+
+对正确性敏感的元数据与参考目录分开解析，并归服务该确切路由的适配器所有。上下文容量、适配器调用默认值和推理选项共用同一个确切模型结果，消费方因而无需重复执行权威模型解析。
+
+```ts type-equiv
+/** Provider-owned context capacity for one exact provider/model route. */
+interface LlmModelContext {
+  /** Maximum combined request and response context in tokens. */
+  contextWindow: number
+}
+```
+
+推理强度是另一项针对确切路由的能力。核心为标识符添加品牌类型，但不枚举其值；有序集合、展示名称和可选的部署默认值均由各适配器持有。
+
+```ts type-equiv
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+type ReasoningEffortId = Branded<'ReasoningEffortId'>
+```
+
+```ts type-equiv
+/** Display metadata for one adapter-owned reasoning effort. */
+interface LlmReasoningEffortInfo {
+  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+  id: ReasoningEffortId
+  /** Human-readable effort name for selectors and diagnostics. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar efforts. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** Selectable reasoning efforts for one exact provider/model route. */
+interface LlmModelReasoningInfo {
+  /** Supported efforts in adapter-preferred display order. */
+  efforts: readonly LlmReasoningEffortInfo[]
+  /**
+   * Adapter-configured default materialized into requests when callers omit
+   * an effort. Absence preserves the provider's own default.
+   */
+  defaultEffort?: ReasoningEffortId
+}
+```
+
+```ts type-equiv
+/** Exact-route model metadata resolved by its owning adapter. */
+interface LlmResolvedModelInfo extends LlmModelInfo {
+  /** Provider-owned context capacity when known. */
+  context?: LlmModelContext
+  /** Adapter-configured per-request output cap materialized when callers omit one. */
+  defaultMaxTokens?: number
+  /** Adapter-owned selectable reasoning levels when exposed. */
+  reasoning?: LlmModelReasoningInfo
+}
+```
+
+```ts type-equiv
+/** A single model request, fully assembled. */
+interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string
+  model: string
+  /** Adapter-owned reasoning effort selected for this exact model. */
+  reasoningEffort?: ReasoningEffortId
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
+   */
+  messages: Message[]
+  /** System prompt text (adapters map to the provider's system slot). */
+  system?: string
+  /** Tool schemas (adapters map to the provider's `tools` field). */
+  tools?: ToolSchema[]
+  temperature?: number
+  maxTokens?: number
+  /**
+   * Stop sequences: generation halts as soon as the model produces any one of
+   * these strings (adapters map to the provider's stop field, e.g. OpenAI
+   * `stop`). The stop string itself is not included in the output.
+   */
+  stop?: string[]
+  signal?: AbortSignal
+  /**
+   * Session identity stamped by the loop for listener routing. Adapters ignore
+   * it; replay uses it to keep concurrent parent and child cursors independent.
+   */
+  sessionId?: Branded<'SessionId'>
+  /**
+   * Provider-neutral classification for an auxiliary model call. Adapters may
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
+   */
+  purpose?: 'compaction' | 'session-title'
+}
+```
+
+模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](#llmfailure)：
+
+```ts type-equiv
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
+interface FinishReasonMap {
+  'stop': { kind: 'stop' }
+  'tool-calls': { kind: 'tool-calls' }
+  'max-tokens': { kind: 'max-tokens' }
+  'aborted': { kind: 'aborted'; failure: LlmFailure }
+  'error': { kind: 'error'; failure: LlmFailure }
+}
+```
+
+`FinishReason = FinishReasonMap[keyof FinishReasonMap]`。`TokenUsage`（逐调用计量，含不相交的缓存字段）详见[下文](#tokenusage)。
+
+`GenerateOptions.tools` 携带 `ToolSchema`——工具的 JSON Schema 描述，发送给模型。它声明在 dsh-llm（而非 dsh-tools）中，正是因为它是循环每一步组装请求的一部分：
+
+```ts type-equiv
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
+ * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
+interface ToolSchema {
+  name: string
+  description: string
+  /** JSON Schema object for the arguments. */
+  parameters: Record<string, unknown>
+}
+```
+
+面向模型的 `ToolSchema` 是协议格式；产出它的已注册 `ToolDefinition`（schema + `execute`）在 [tools.md](tools.md) 中。
+
+### 请求信封：`LlmCallConfig` 与记录的 header
+
+循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
+
+`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置及其来源。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
+
+在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
+
+FIXME(call-config-shape)：重新审视其余哪些字段出于缓存目的确实属于 epoch 层级（`model` 和模型持有的推理强度已明确属于；采样标量目前出于谨慎保留在此）。
+
+```ts type-equiv
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+interface LlmCallConfig {
+  provider: string
+  model: string
+  reasoningEffort?: ReasoningEffortId
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+}
+```
+
+```ts type-equiv
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+interface LlmCallConfigAdapterDefaults {
+  reasoningEffort?: true
+  maxTokens?: true
+}
+```
+
 ## seam
 
 `LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#content-blocks-and-streaming-dsh-llm)。
@@ -171,8 +506,6 @@ declare class BlockAssembler {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
-  /** Immutable retry policy captured with the adapter registration. */
-  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -239,22 +572,7 @@ declare abstract class LlmAdapter {
 }
 ```
 
-`ContentBlockType`（`index` 关联块所携带的键集合）派生自 `ContentBlockMap`：
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-块接口详见 [core.md § Content blocks and messages](core.md#content-blocks-and-messages)。
+`ContentBlockType`（带 `index` 关联的块所携带的键集合）从上文的 [`ContentBlockMap`](#content-blocks-and-messages) 派生。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -293,9 +611,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns a handle that withdraws all of them, and can atomically replace them.
+ * @returns the disposer that withdraws all of them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -303,29 +621,6 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): Dire
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
-/**
- * Offer to interrogate provider endpoints on behalf of the settings
- * namespace this plugin owns. The namespace is the key because that is what
- * a configuration surface already holds from the configurable-provider
- * directory, and because a provider being *added* has no route to name yet.
- * Disposed with the fiber.
- * @param settingsNs - the namespace whose profiles this discovery serves.
- * @param discover - interrogates one endpoint; must honor `request.signal`.
- * @returns the disposer that withdraws the offer.
- */
-registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
-
-/**
- * Interrogate one provider endpoint for the models it advertises. The
- * request describes a draft, not a stored route, so nothing here reads or
- * writes settings or credentials — the caller owns both, and the reply is
- * candidate metadata a surface may offer for adoption.
- * @param settingsNs - namespace whose registered discovery serves this draft.
- * @param request - the endpoint, protocol, and one-shot credential to use.
- * @returns the advertised models, deduplicated in endpoint order.
- */
-async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
-
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -375,22 +670,22 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Replay state is
- * retained only when the same adapter instance owns its historical provider
- * and the target provider. Final adapter selection remains fixed through
- * asynchronous exact-model resolution and dispatch. Adapter selection,
- * dispatch, and iteration failures become terminal `error` or `aborted`
- * finish chunks; middleware, nested-call, cleanup, and consumer failures
- * remain thrown.
+ * Stream one model call as raw chunks (token-level deltas). Throws
+ * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
+ * `options.provider`. Replay state is retained only when the same adapter
+ * instance owns its historical provider and the target provider. Final
+ * adapter selection remains fixed through asynchronous exact-model resolution
+ * and dispatch. Selection, dispatch, and iteration failures retain their
+ * original Error identity and are tagged in a call-local scope for narrow
+ * agent-loop request recovery; middleware and nested-call failures remain
+ * untagged for the outer call.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -415,7 +710,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -439,7 +734,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index 980c1a1a2d..c1466bdcfc 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.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 docs/subsystems/session-reference.md
-session-reference.md: 60e29c56ea372e100009b94caedea5327308432a
-session-reference.zh.md: 3ae9264abc15848646e5397dfcbeff764c038918
+session-reference.md: f539a59b8d26182aff9746b6d6a39a86ba15cb45
+session-reference.zh.md: 82b6a6c5ec5c91372fc6a43b73ad1572fccf5b3a
diff --git a/docs/subsystems/session-reference.md b/docs/subsystems/session-reference.md
index 60e29c56ea..f539a59b8d 100644
--- a/docs/subsystems/session-reference.md
+++ b/docs/subsystems/session-reference.md
@@ -102,7 +102,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con
 async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
 
 Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 3ae9264abc..82b6a6c5ec 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -102,7 +102,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con
 async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
 
 Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index e6ead80f87..a58335b9f1 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: cbf9043b36a5cb2ab37bb99c6dbbf5a18d1e0288
-subagent.zh.md: ffd8fefd8b9d128c21e1b91ee0ba1fb706638fa9
+subagent.md: c132c073459642b133e0d7e662ee98a8c9dfb694
+subagent.zh.md: e46f9aa98389842918ae37dda1477ef1b565e774
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index cbf9043b36..c132c07345 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -611,7 +611,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md) · [MessageId](llm-streaming.md) · [SessionId](core.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ffd8fefd8b..e46f9aa983 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -613,7 +613,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md) · [MessageId](llm-streaming.md) · [SessionId](core.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
diff --git a/docs/subsystems/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
index e348aca7a0..17bbb937cc 100644
--- a/docs/subsystems/token-meter.i18n.yaml
+++ b/docs/subsystems/token-meter.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 docs/subsystems/token-meter.md
-token-meter.md: 0f53955b3e6afce84520314f4de453edaa897158
-token-meter.zh.md: 3ba22c54d599982d3f7bdbcb9160b6ffc3255e07
+token-meter.md: 8a01980191bf29b1fbc0f8b1d0b33d1fb149319c
+token-meter.zh.md: 7411ce26cb75697607a706469d7923d46ff3f421
diff --git a/docs/subsystems/token-meter.md b/docs/subsystems/token-meter.md
index 0f53955b3e..8a01980191 100644
--- a/docs/subsystems/token-meter.md
+++ b/docs/subsystems/token-meter.md
@@ -84,7 +84,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
index 3ba22c54d5..7411ce26cb 100644
--- a/docs/subsystems/token-meter.zh.md
+++ b/docs/subsystems/token-meter.zh.md
@@ -84,7 +84,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 8b0aa47c9a..003e175399 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 5d72bd54f0dc5995218087030f24c467c8ccbb38
-tools.zh.md: 2340d4c2d92c51aa9cc89f4694b626c76d05140b
+tools.md: b63014d1c2058c8fc7e96817d4bca858a1954482
+tools.zh.md: 2dc5802efce25a732a60c660191cd584ede623bb
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 5d72bd54f0..b63014d1c2 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -596,7 +596,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
 ```
 
-Types: [ContentBlock](core.md) · [Scoped](scope.md)
+Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
 
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 2340d4c2d9..2dc5802efc 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -596,7 +596,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
 ```
 
-Types: [ContentBlock](core.md) · [Scoped](scope.md)
+Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
 
diff --git a/packages/acp/README.i18n.yaml b/packages/acp/README.i18n.yaml
index ca4ec66f67..cd4555752b 100644
--- 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: 3ba247598f29f2244456061fe7f9a3282086148f
-README.zh.md: c13bc05b12fff2ef97b4d547936aa14a6556430a
+README.md: 97af6d164b265bf0e98e3c9f5a444cffad4face5
+README.zh.md: 266b108c108b9f543d93cbb727ddbc01ab4bef36
diff --git a/packages/acp/README.md b/packages/acp/README.md
index 3ba247598f..97af6d164b 100644
--- a/packages/acp/README.md
+++ b/packages/acp/README.md
@@ -2,10 +2,10 @@
 
 English | [中文](README.zh.md)
 
-The ACP group exposes harness agents to programmatic clients. It is an interoperability transport, not a presentation or human-interaction layer.
+The ACP group exposes harness agents to programmatic clients over the Agent Client Protocol. It is an interoperability transport, not a presentation or human-interaction layer; the matching out-of-process subagent *client* lives in [`subagent/subagent-acp`](../subagent/subagent-acp/README.md) because it implements the subagent provider interface.
 
 | Package | Role |
 |---|---|
 | [`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.
+The server contract is documented in [`acp/README.md`](acp/README.md).
diff --git a/packages/acp/README.zh.md b/packages/acp/README.zh.md
index c13bc05b12..266b108c10 100644
--- a/packages/acp/README.zh.md
+++ b/packages/acp/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-ACP（Agent Client Protocol）组将 harness 中的 agent（智能体）公开给程序化客户端。它是互操作传输层，而非展示层或人机交互层。
+ACP 组通过 Agent Client Protocol 把 harness agent 暴露给编程客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
 
 | 包 | 职责 |
 |---|---|
 | [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器。 |
 
-与之匹配的进程外 subagent 客户端仍位于 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现 subagent 提供方接口；任意 ACP 客户端都可以按照同一服务器契约驱动该服务器。
+服务器契约见 [`acp/README.md`](acp/README.md)。
diff --git a/packages/bash/README.i18n.yaml b/packages/bash/README.i18n.yaml
index 4c4a2c6180..00321c8ab0 100644
--- 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: 601782caad24d3555a206365a3f1954d81af1cf0
-README.zh.md: 8b96c4f80ba8776bfd8bdde178178cea946ff36c
+README.md: 7395a051742af24b96842966b71297dc01853dca
+README.zh.md: 1d5825e077c46284dbd4895e285cda8f39c252a3
diff --git a/packages/bash/README.md b/packages/bash/README.md
index 601782caad..7395a05174 100644
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -15,3 +15,5 @@ The capability family spans the canonical executor seam, its implementations, th
 | [`tool-pwsh/`](tool-pwsh/README.md) | Exposes PowerShell execution to the model. | (registers on `ctx.tools`) |
 
 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.
+
+The subsystem reference — request/spec vocabulary, results, background processes, the service, and events — is [docs/subsystems/bash.md](../../docs/subsystems/bash.md).
diff --git a/packages/bash/README.zh.md b/packages/bash/README.zh.md
index 8b96c4f80b..1d5825e077 100644
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -15,3 +15,5 @@
 | [`tool-pwsh/`](tool-pwsh/README.md) | 向模型公开 PowerShell 执行。 | （注册到 `ctx.tools`） |
 
 叶节点 `cordis.yml` 选择一个执行器实现和所需的面向模型工具。沙箱化组合还会选择一个 `ctx.sandbox` 提供方；[ACP（Agent Client Protocol）示例](../../examples/acp-agent/)展示一套完整接线。
+
+子系统参考——请求/spec 词汇、结果、后台进程、服务与事件——见 [docs/subsystems/bash.md](../../docs/subsystems/bash.md)。
diff --git a/packages/boot/README.i18n.yaml b/packages/boot/README.i18n.yaml
index 151e5e5c08..8f691dd089 100644
--- a/packages/boot/README.i18n.yaml
+++ b/packages/boot/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/boot/README.md
-README.md: 7727f4fbab62a930051fd3b92d04513ac9f5d218
-README.zh.md: aa9a56619ee55c3be8feb58881f77c460861b1ac
+README.md: 5e4e483b60adab0b22ddb5279f4cd8fb699b9c35
+README.zh.md: d49afa45b9fb93f6fa83944167057f0c933cd05d
diff --git a/packages/boot/README.md b/packages/boot/README.md
index 7727f4fbab..5e4e483b60 100644
--- a/packages/boot/README.md
+++ b/packages/boot/README.md
@@ -2,8 +2,10 @@
 
 English | [中文](README.zh.md)
 
-The channel-neutral boot library the app bins share. A role-complete single-package group: it belongs to no channel and no assembly — `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
+The channel-neutral boot library the app bins share: `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
 
 | Package | Role | ctx key |
 |---|---|---|
 | `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
+
+The boot sequence and personal-config contract are documented in [`app-boot/README.md`](app-boot/README.md).
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
index aa9a56619e..d49afa45b9 100644
--- a/packages/boot/README.zh.md
+++ b/packages/boot/README.zh.md
@@ -2,8 +2,10 @@
 
 [English](README.md) | 中文
 
-各 app bin 共享、与通道无关的启动库。一个角色完备的单包组：它不归属任何通道也不归属任何组装——`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器和 [`examples/`](../examples/README.md) 各演示 bin 都消费它。
+各 app bin 共享的、与渠道无关的启动库：`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器与 [`examples/`](../examples/README.md) demo bin 都消费它。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
+
+启动序列与个人配置契约见 [`app-boot/README.md`](app-boot/README.md)。
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index e65d5246a4..2ce3e44fa7 100644
--- 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: b6fa426fbe541e2b22d2bf5f19d4397361cf0899
-README.zh.md: 5a55bb8c2c31b5215fc73e75e1c4f3aca79add64
+README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
+README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139
diff --git a/packages/client/README.md b/packages/client/README.md
index b6fa426fbe..56b9363cc7 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -38,3 +38,5 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha
 | [`ui-models/`](ui-models/README.md) | Provides model-provider configuration and DeepSeek onboarding. |
 
 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.
+
+The subsystem reference is [client-modules.md](../../docs/subsystems/client-modules.md); the [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) is the definitive slot model, and the [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) owns the loading chain and object layer.
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index 5a55bb8c2c..edd378bf80 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -38,3 +38,5 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
 
 每个子文档负责自身的契约和详细行为。[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)负责跨包组合与加载决策。
+
+子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 3eb462d513..1f9b94c59b 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
-README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
+README.md: 45dd55b8609fd33b7116f6b2ea36df3b3332e419
+README.zh.md: ebf288a49f87ad01b1ec80c3843c87c91206af26
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index f20a287419..45dd55b860 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -10,3 +10,5 @@ The code-execution capability seam (see [capability seams](../../.agents/notes/i
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
 
 Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
+
+The subsystem reference — run requests/results, binding namespaces, the failure taxonomy — is [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index f5cd4c9949..ebf288a49f 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -10,3 +10,5 @@
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
 
 后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
+
+子系统参考——运行请求/结果、绑定命名空间、失败分类体系——见 [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md)。
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index 17357bea7b..bb5922ee75 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/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/compact/README.md
-README.md: 509ea2764250f42e492f787deba959a8dd9967b7
-README.zh.md: adc52690dbe9e904d8f24199cb78493dab3333a4
+README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
+README.zh.md: cba53ee7bb917a981a0fd4b77d833b8fb7dd2c3f
diff --git a/packages/compact/README.md b/packages/compact/README.md
index 509ea27642..0a83b87f57 100644
--- a/packages/compact/README.md
+++ b/packages/compact/README.md
@@ -12,3 +12,5 @@ A compaction capability family (see [capability seams](../../.agents/notes/imple
 | [`command-compact/`](command-compact/README.md) | Human compaction command | registers on `ctx.commands` |
 
 The backend, optional pruner, and human command compose through the seam; token measurement remains a separate LLM-family service. The [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) owns the dependency rationale.
+
+The subsystem reference — the `compact/*` events, `CompactionResult`, the service, pruning outcomes — is [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md); the seam's deliberate `dsh-session`/`dsh-llm` dependency is recorded in the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index adc52690db..cba53ee7bb 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -12,3 +12,5 @@
 | [`command-compact/`](command-compact/README.md) | 用户压缩命令 | 注册到 `ctx.commands` |
 
 后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)负责依赖关系的设计原理。
+
+子系统参考——`compact/*` 事件、`CompactionResult`、服务、剪除结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
diff --git a/packages/context/README.i18n.yaml b/packages/context/README.i18n.yaml
index f3acd7f2bf..efb18426a4 100644
--- a/packages/context/README.i18n.yaml
+++ b/packages/context/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/context/README.md
-README.md: a0b5eef51740b3aa67b9e158a00357f849b8bf57
-README.zh.md: d6ed8050f3a64f740a951883f0dc321ac08e978a
+README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
+README.zh.md: 7c55dd91dbf7e3fca222e4b6f6bed2769f5c253c
diff --git a/packages/context/README.md b/packages/context/README.md
index a0b5eef517..237f619132 100644
--- a/packages/context/README.md
+++ b/packages/context/README.md
@@ -12,3 +12,5 @@ Product plugins that add model-visible request context without defining a tool.
 | [`workspace-context/`](workspace-context/README.md) | Workspace-instruction context | — |
 
 The [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.
+
+Session references are documented in [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md); the [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) owns its per-agent/session isolation and lifecycle split.
diff --git a/packages/context/README.zh.md b/packages/context/README.zh.md
index d6ed8050f3..7c55dd91db 100644
--- a/packages/context/README.zh.md
+++ b/packages/context/README.zh.md
@@ -12,3 +12,5 @@
 | [`workspace-context/`](workspace-context/README.md) | workspace 指令上下文 | — |
 
 [`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
+
+会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent/会话隔离与生命周期拆分。
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index d43caa011e..aa542fe885 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
-README.md: d51ef73f7f545920f8cd527b2b0d597305ae86d0
-README.zh.md: 729f41fafb6b9585a66e58fe8d6ac63c1f235acc
+README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
+README.zh.md: 496d547a173a63ac9d8d2ce0f005877dab92d358
diff --git a/packages/core/README.md b/packages/core/README.md
index d51ef73f7f..40a888183a 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -16,3 +16,5 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 `scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable.
 
 Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
+
+The subsystem reference — the package-by-package loop map, the `Agent` handle and its delivery/interception contracts — is [docs/subsystems/core.md](../../docs/subsystems/core.md); the default runnable composition is [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md).
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index 729f41fafb..496d547a17 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -16,3 +16,5 @@
 `scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
+
+子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截契约——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。
diff --git a/packages/credentials/README.i18n.yaml b/packages/credentials/README.i18n.yaml
index 04f14e8e75..38cbbb2968 100644
--- a/packages/credentials/README.i18n.yaml
+++ b/packages/credentials/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/credentials/README.md
-README.md: c08831c90333f8515bf86a5af717c38c50b50817
-README.zh.md: c9756c010af5d2db0fc41f3108eabdc7f1161293
+README.md: 75e3941ff6421ca7e41a71ab2bfe8b30209ce598
+README.zh.md: d7c958689fdffc82830a82b04e2a06802bc81634
diff --git a/packages/credentials/README.md b/packages/credentials/README.md
index c08831c903..75e3941ff6 100644
--- a/packages/credentials/README.md
+++ b/packages/credentials/README.md
@@ -10,3 +10,5 @@ The credential capability family separates reference resolution from its provide
 | [`credentials-local/`](credentials-local/README.md) | Environment and local-file provider | registers `ctx.credentials` |
 
 Configuration carries references, not secret values. Consumers resolve those references at their operation boundary; the child READMEs own mutation, precedence, and storage semantics.
+
+The subsystem reference — `CredentialRef`, per-operation resolution, UI-safe `CredentialInfo`, provider layers — is [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md).
diff --git a/packages/credentials/README.zh.md b/packages/credentials/README.zh.md
index c9756c010a..d7c958689f 100644
--- a/packages/credentials/README.zh.md
+++ b/packages/credentials/README.zh.md
@@ -10,3 +10,5 @@
 | [`credentials-local/`](credentials-local/README.md) | 环境与本地文件提供方 | 注册 `ctx.credentials` |
 
 配置携带引用而非机密值。消费方在其操作边界解析这些引用；变更、优先级与存储语义由子级 README 负责。
+
+子系统参考——`CredentialRef`、按操作解析、对 UI 安全的 `CredentialInfo`、提供方层——见 [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md)。
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index f4719447aa..b1e493f3c8 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: b15012e882b60847e1ad22edf08d1202ba64fe5b
-README.zh.md: 628f6c74894bc67559d49f7cf5d1378d0ece2382
+README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
+README.zh.md: b2929b17be6ce90051f0808c2cdf4bbf643f8f13
diff --git a/packages/fs/README.md b/packages/fs/README.md
index b15012e882..162e2c75e9 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -19,3 +19,5 @@ The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesyst
 ## No timeouts on file IO
 
 `read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+
+The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 628f6c7489..b2929b17be 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -19,3 +19,5 @@
 ## 文件 I/O 不设超时
 
 `read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
+
+子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/goal/README.i18n.yaml b/packages/goal/README.i18n.yaml
index 4238bac3c4..d2a6bf0248 100644
--- a/packages/goal/README.i18n.yaml
+++ b/packages/goal/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/goal/README.md
-README.md: 9fc6b0c18b1862a8be08275785ea3b6185e9bdbc
-README.zh.md: 08f15bcc4e405e25d4dfd5981bbc99408833403c
+README.md: 9d307278b39ecee61df9feace9fec4235b45d794
+README.zh.md: 7217c174ba5382c53204ae3678be42375fc63db5
diff --git a/packages/goal/README.md b/packages/goal/README.md
index 9fc6b0c18b..9d307278b3 100644
--- a/packages/goal/README.md
+++ b/packages/goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The goal family owns durable objective state independently of the model-facing tools and continuation policy that consume it.
+Durable objective state for an agent session, owned independently of the model-facing tools and continuation policy that consume it. Goal state is part of the owning session log; consumers depend on `dsh-goal`, never on the concrete agent loop.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -11,4 +11,4 @@ The goal family owns durable objective state independently of the model-facing t
 | [`tool-goal/`](tool-goal/README.md) | Model-facing goal tools | — |
 | [`command-goal/`](command-goal/README.md) | Human-facing goal command | — |
 
-Goal state is part of the owning session log. Consumers depend on `dsh-goal`, not on the concrete agent loop; continuation behavior belongs in a separate plugin on the public agent seams.
+The subsystem reference — goal identity, lifecycle snapshots, activation, change records — is [docs/subsystems/goal.md](../../docs/subsystems/goal.md).
diff --git a/packages/goal/README.zh.md b/packages/goal/README.zh.md
index 08f15bcc4e..7217c174ba 100644
--- a/packages/goal/README.zh.md
+++ b/packages/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-goal 家族负责持久目标状态，与消费该状态的面向模型工具和续行策略相互独立。
+agent 会话的持久目标状态，独立于消费它的模型工具与续跑策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体 agent loop。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
@@ -11,4 +11,4 @@ goal 家族负责持久目标状态，与消费该状态的面向模型工具和
 | [`tool-goal/`](tool-goal/README.md) | 面向模型的目标工具 | 无 |
 | [`command-goal/`](command-goal/README.md) | 面向用户的目标命令 | 无 |
 
-目标状态是其所属会话日志的一部分。消费方依赖 `dsh-goal`，而不是具体的 agent loop（智能体循环）；续行行为由基于公开 agent seam 的独立插件负责。
+子系统参考——goal 标识、生命周期快照、激活、变更记录——见 [docs/subsystems/goal.md](../../docs/subsystems/goal.md)。
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index 8251a76ed5..b99cec734b 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
-README.md: 5791474a2fd6aeda728d4c335c930069ade6e023
-README.zh.md: 82d779d2f1834317672b8fb03f2a4a875bb566fc
+README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
+README.zh.md: c7747e2febcb1656925fd556743eb2dd28090e37
diff --git a/packages/guard/README.md b/packages/guard/README.md
index 5791474a2f..f0a80b1f49 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -8,3 +8,5 @@ Behavioral guard plugins watch the agent loop for unproductive patterns and enfo
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | Advisory reminders for repeated tool calls | listens on tool and agent events |
 | [`timeout-policy/`](timeout-policy/README.md) | Arms per-call tool deadlines as deployment policy | registers a `tools/execute` listener |
+
+Reminders travel as `additionalContexts` on the `tools/post-execute` decision and are appended as logged plugin-sourced `user/message` events ([tools](../../docs/subsystems/tools.md)); the timeout split across `dsh-timeout`, capability termination, and this policy layer is recorded in the [timeout-library Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md).
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index 82d779d2f1..c7747e2feb 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -8,3 +8,5 @@
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | 针对重复工具调用的建议性提醒 | 监听工具和 agent 事件 |
 | [`timeout-policy/`](timeout-policy/README.md) | 以部署策略形式设置单次工具调用截止时间 | 注册 `tools/execute` 监听器 |
+
+提醒作为 `additionalContexts` 随 `tools/post-execute` 决策传递，并以插件来源的 `user/message` 事件记录（[工具](../../docs/subsystems/tools.md)）；跨 `dsh-timeout`、能力方终止与本策略层的超时拆分记录在[超时库 Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)。
diff --git a/packages/host/README.i18n.yaml b/packages/host/README.i18n.yaml
index 1aaacd7ecb..0859a2571d 100644
--- a/packages/host/README.i18n.yaml
+++ b/packages/host/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/host/README.md
-README.md: 269a27f51c842f13bc11c175916b7be22db72bd2
-README.zh.md: 559bf785eb45d59a30f676b98c14143c69d57edd
+README.md: 926cb0b6b87a8ee76cb2dab745a31f620f4e7f5c
+README.zh.md: dc617084c756b80716f9a02bd2d22ba6954030f6
diff --git a/packages/host/README.md b/packages/host/README.md
index 269a27f51c..926cb0b6b8 100644
--- a/packages/host/README.md
+++ b/packages/host/README.md
@@ -15,3 +15,5 @@ The host side of the dsh web GUI: the API gateway every client shape shares, and
 | [`directory-picker-auto/`](directory-picker-auto/README.md) | Host-adaptive picker composition | mounts a backend |
 
 `apiproxy` remains transport-independent; [`client/connection`](../client/connection/README.md) supplies the browser/HTTP carrier. Picker implementations replace one another behind the shared seam.
+
+The subsystem references: [http-server.md](../../docs/subsystems/http-server.md) and [workspace.md](../../docs/subsystems/workspace.md) (the picker seam).
diff --git a/packages/host/README.zh.md b/packages/host/README.zh.md
index 559bf785eb..dc617084c7 100644
--- a/packages/host/README.zh.md
+++ b/packages/host/README.zh.md
@@ -15,3 +15,5 @@ dsh Web GUI 的宿主侧：所有客户端形态共享的 API 网关，以及承
 | [`directory-picker-auto/`](directory-picker-auto/README.md) | 宿主自适应选择器组合 | 挂载一个后端 |
 
 `apiproxy` 保持传输无关；[`client/connection`](../client/connection/README.md) 提供浏览器／HTTP 载体。选择器实现可在共享 seam 后互相替换。
+
+子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（挑选 seam）。
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index 2555e896a1..77539b60fb 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
-README.md: 506b47753fc9250f9f7bd971265421ad46a106b2
-README.zh.md: 34d336f3d3c10deab166d5c13bb86c13ee9bced0
+README.md: 31a306cb08fe69297b0d0843b57b5e491c0bbe44
+README.zh.md: 6eafe8726ba59edd3a6bf739deacc037a9b56b76
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index 506b47753f..31a306cb08 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -13,3 +13,5 @@ The seams through which a human collaborates with a running agent — questions,
 | [`tool-ask-user/`](tool-ask-user/README.md) | Exposes human questions to the model. | (registers on `ctx.tools`) |
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
+
+The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), [commands.md](../../docs/subsystems/commands.md), and [tui.md](../../docs/subsystems/tui.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 34d336f3d3..6eafe8726b 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -13,3 +13,5 @@
 | [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
 
 这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
+
+子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)、[commands.md](../../docs/subsystems/commands.md) 与 [tui.md](../../docs/subsystems/tui.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index 3c4ae19900..a35bf870d4 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/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/llm/README.md
-README.md: 92d9fbfa2b8c8db4700562009db49229b2189ab3
-README.zh.md: 5c6e7aad1db6511bdb660b86e257652128db131f
+README.md: 077ae600c89cff80cd71830e37bda00707c1d837
+README.zh.md: e2bdad7fd0b33116498b50bfa6527974fa140fc9
diff --git a/packages/llm/README.md b/packages/llm/README.md
index 92d9fbfa2b..077ae600c8 100644
--- a/packages/llm/README.md
+++ b/packages/llm/README.md
@@ -13,3 +13,5 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 | [`llm-pi-ai/`](llm-pi-ai/README.md) | Multi-provider pi-ai adapter | registers on `ctx.llm` |
 
 Adapters register provider routes on the seam; retry and token measurement remain separate consumers. The child READMEs own routing, metadata, replay, and provider-wire details; the [LLM architecture decisions](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) own the rationale.
+
+The subsystem reference — messages and blocks, the model request, the `StreamChunk` protocol, the adapter contract — is [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md) (token measurement: [token-meter.md](../../docs/subsystems/token-meter.md)); see the [twin adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md), [replay token meter](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md), and [routed model context](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Notes.
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index 5c6e7aad1d..e2bdad7fd0 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -13,3 +13,5 @@ LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负
 | [`llm-pi-ai/`](llm-pi-ai/README.md) | 多提供方 pi-ai 适配器 | 注册到 `ctx.llm` |
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
+
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器契约——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index 9919cdaba5..be1dc838ff 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
-README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
+README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
+README.zh.md: fa7dddeb011bd34c1f9cbe3a9dbf746d7f163897
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 7fbdf07173..01c464c999 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -13,3 +13,5 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
 See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
+
+The subsystem reference — operations, coordinates, requests/results, `LspError` — is [docs/subsystems/lsp.md](../../docs/subsystems/lsp.md); design rationale in the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md).
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index e059dbd80b..fa7dddeb01 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -13,3 +13,5 @@
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
 设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
+
+子系统参考——操作、坐标、请求/结果、`LspError`——见 [docs/subsystems/lsp.md](../../docs/subsystems/lsp.md)；设计依据见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)。
diff --git a/packages/plan/README.i18n.yaml b/packages/plan/README.i18n.yaml
index 3ae6755be6..4e34bac80c 100644
--- a/packages/plan/README.i18n.yaml
+++ b/packages/plan/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/plan/README.md
-README.md: 598974e105aaeaf3c35418aec0655de2a5ba6888
-README.zh.md: 0f54299af5d34555d86d82e83b92d185045e770f
+README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
+README.zh.md: f068bf37b44daa0d724fbb85ad85a4d62883e847
diff --git a/packages/plan/README.md b/packages/plan/README.md
index 598974e105..535a2b02e2 100644
--- a/packages/plan/README.md
+++ b/packages/plan/README.md
@@ -9,3 +9,5 @@ Plan mode is logged, per-agent collaboration state rather than a generic mode re
 | [`plan-mode/`](plan-mode/README.md) | Owns plan-mode state, guidance, commands, and review flow | `ctx.planMode` |
 
 The [plan-specific collaboration state](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) decision records the family design.
+
+The subsystem reference — the `plan/mode` fold, the step-boundary flush, configuration, the exit tool — is [docs/subsystems/plan.md](../../docs/subsystems/plan.md); design in [plan-specific collaboration state](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).
diff --git a/packages/plan/README.zh.md b/packages/plan/README.zh.md
index 0f54299af5..f068bf37b4 100644
--- a/packages/plan/README.zh.md
+++ b/packages/plan/README.zh.md
@@ -9,3 +9,5 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
 | [`plan-mode/`](plan-mode/README.md) | 负责 plan mode 状态、指引、命令和评审流程 | `ctx.planMode` |
 
 [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
+
+子系统参考——`plan/mode` 折叠、步边界冲刷、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 65d541a7c1..7f4c7f1f21 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: a4f743056b4a524be9623b0f700f37e0534b463f
-README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
+README.md: 2afb3cd61ef4bfba460716549d41f799e419ff46
+README.zh.md: 57a5c93047ccb970f499f02c0168db7e9f71b622
diff --git a/packages/pty/README.md b/packages/pty/README.md
index a4f743056b..2afb3cd61e 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -11,3 +11,5 @@ English | [中文](README.zh.md)
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
 The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
+
+The subsystem reference — ids, backend/session contracts, send readiness, bounded reads — is [docs/subsystems/pty.md](../../docs/subsystems/pty.md); design and deferred boundaries in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index c84ad3f1b5..57a5c93047 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -11,3 +11,5 @@
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
 设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
+
+子系统参考——id、后端/会话契约、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与延后边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
diff --git a/packages/sandbox/README.i18n.yaml b/packages/sandbox/README.i18n.yaml
index c851d420ae..ab79d37170 100644
--- a/packages/sandbox/README.i18n.yaml
+++ b/packages/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/sandbox/README.md
-README.md: 1ba56d22330c26302c9283b2319d983ebf902219
-README.zh.md: 5daf830854297fe14c6560dbcde8a380ad079a0e
+README.md: 61127118c895cce728ab0b4eed387f51054a83f1
+README.zh.md: 984a677aad6ab97579abf861ea8b99f149c07d08
diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md
index 1ba56d2233..61127118c8 100644
--- a/packages/sandbox/README.md
+++ b/packages/sandbox/README.md
@@ -11,3 +11,5 @@ This family applies per-session confinement policy to process execution. It cove
 | [`sandbox-policy/`](sandbox-policy/README.md) | Resolves durable per-session sandbox policy | `ctx.sandboxPolicy` |
 
 See the [sandbox decision](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) for the capability boundary and the [filesystem integration decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) for cross-family policy use.
+
+The subsystem reference — modes and enforcement, per-call policy, wrapped-argv dialects, fail-closed errors — is [docs/subsystems/sandbox.md](../../docs/subsystems/sandbox.md); the boundary and the cross-family phase live in the [sandbox](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) and [cross-family fs sandbox](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) Agent Notes.
diff --git a/packages/sandbox/README.zh.md b/packages/sandbox/README.zh.md
index 5daf830854..984a677aad 100644
--- a/packages/sandbox/README.zh.md
+++ b/packages/sandbox/README.zh.md
@@ -11,3 +11,5 @@
 | [`sandbox-policy/`](sandbox-policy/README.md) | 解析持久的逐会话沙箱策略 | `ctx.sandboxPolicy` |
 
 [沙箱决策](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)记录了能力边界，[文件系统集成决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)记录了跨家族策略的使用方式。
+
+子系统参考——模式与强制执行、按调用策略、包装 argv 方言、故障关闭错误——见 [docs/subsystems/sandbox.md](../../docs/subsystems/sandbox.md)；边界与跨家族阶段见[沙箱](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)与[跨家族 fs 沙箱](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) Agent Note。
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 9a6a070b95..53bbf9cdbb 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/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/self-modification/README.md
 README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
-README.zh.md: 9874ead263e9860b94992cb176be3c6f8c454ece
+README.zh.md: 90030cda33f47d128041b7619546ac1309b8465a
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
index 9874ead263..90030cda33 100644
--- a/packages/self-modification/README.zh.md
+++ b/packages/self-modification/README.zh.md
@@ -2,9 +2,11 @@
 
 [English](README.md) | 中文
 
-这些面向模型的工具作用于 agent（智能体）自身所在的实时 Cordis 运行时，可检查已加载的插件和服务接口、挂载模型编写的插件，并将其 dispose（资源释放）——外加受限 repository Plugin 运行时。该组也是未来自我修改类包的落点。设计说明见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。该组是未来自我修改类包的落点。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
 
 | 包（package） | 角色 | ctx 键 |
 |---|---|---|
 | [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
 | [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
+
+工具契约见 [`tool-cordis/README.md`](tool-cordis/README.md) 与 [`repository-plugin/README.md`](repository-plugin/README.md)。
diff --git a/packages/session-query/README.i18n.yaml b/packages/session-query/README.i18n.yaml
index 3911bf76a0..2922f4eb88 100644
--- a/packages/session-query/README.i18n.yaml
+++ b/packages/session-query/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/session-query/README.md
-README.md: a9c9f33e2dc67e837c2be728d2b1a937ce50f13d
-README.zh.md: a29dedba09271baa5836cb2d9d57c753ee41c660
+README.md: 3d5db8da74cb825c701fe50cf518505e9e6bcad9
+README.zh.md: fc430cbdc4130f77eb8857c4d88a2435ad0cc97f
diff --git a/packages/session-query/README.md b/packages/session-query/README.md
index a9c9f33e2d..3d5db8da74 100644
--- a/packages/session-query/README.md
+++ b/packages/session-query/README.md
@@ -9,3 +9,5 @@ This family provides authorized retrieval over live and durable session logs, in
 | [`session-query/`](session-query/README.md) | Defines trusted reads, relationship queries, and search operations | `ctx.sessionQuery` |
 | [`session-query-sqlite/`](session-query-sqlite/README.md) | Implements session queries with SQLite full-text search | `ctx.sessionQuery` |
 | [`tool-session-query/`](tool-session-query/README.md) | Exposes workspace-authorized session queries to the model | registers on `ctx.tools` |
+
+The subsystem reference — logical records, bounded reads, traces, filters, result pages — is [docs/subsystems/session-query.md](../../docs/subsystems/session-query.md).
diff --git a/packages/session-query/README.zh.md b/packages/session-query/README.zh.md
index a29dedba09..fc430cbdc4 100644
--- a/packages/session-query/README.zh.md
+++ b/packages/session-query/README.zh.md
@@ -9,3 +9,5 @@
 | [`session-query/`](session-query/README.md) | 定义可信读取、关系查询和搜索操作 | `ctx.sessionQuery` |
 | [`session-query-sqlite/`](session-query-sqlite/README.md) | 使用 SQLite 全文搜索实现会话查询 | `ctx.sessionQuery` |
 | [`tool-session-query/`](tool-session-query/README.md) | 向模型公开经过工作区授权的会话查询 | 注册到 `ctx.tools` |
+
+子系统参考——逻辑记录、有界读取、追踪、筛选器、结果页——见 [docs/subsystems/session-query.md](../../docs/subsystems/session-query.md)。
diff --git a/packages/session/README.i18n.yaml b/packages/session/README.i18n.yaml
index b500a64611..3829d946f0 100644
--- a/packages/session/README.i18n.yaml
+++ b/packages/session/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/session/README.md
-README.md: 45eff16ad57ec1ccc8ebdd55db82f41b5adfc111
-README.zh.md: 2d67e28ef169f4e4376b2a644a3b842e5835df04
+README.md: 586d1be0286a0de935b0b08313e6965452b85376
+README.zh.md: 60e58e6d471a48d3ced03a518e96aeeae79110e8
diff --git a/packages/session/README.md b/packages/session/README.md
index 45eff16ad5..586d1be028 100644
--- a/packages/session/README.md
+++ b/packages/session/README.md
@@ -47,3 +47,5 @@ Projects session activity into outbound telemetry and delegates delivery to a co
 |---|---|
 | [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
 | [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
+
+The subsystem references: [persistence.md](../../docs/subsystems/persistence.md), [session-projection.md](../../docs/subsystems/session-projection.md), [session-title.md](../../docs/subsystems/session-title.md), and [telemetry.md](../../docs/subsystems/telemetry.md). Only one title provider may register at a time; the demo spine mounts the fallback service and leaves both model providers out of default composition.
diff --git a/packages/session/README.zh.md b/packages/session/README.zh.md
index 2d67e28ef1..60e58e6d47 100644
--- a/packages/session/README.zh.md
+++ b/packages/session/README.zh.md
@@ -47,3 +47,5 @@
 |---|---|
 | [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
 | [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
+
+子系统参考：[persistence.md](../../docs/subsystems/persistence.md)、[session-projection.md](../../docs/subsystems/session-projection.md)、[session-title.md](../../docs/subsystems/session-title.md) 与 [telemetry.md](../../docs/subsystems/telemetry.md)。同一时间只允许一个标题提供方注册；demo 主干挂载回退服务，两个模型提供方都留在默认组合之外。
diff --git a/packages/settings/README.i18n.yaml b/packages/settings/README.i18n.yaml
index ec2d2124a3..146f0ad32e 100644
--- a/packages/settings/README.i18n.yaml
+++ b/packages/settings/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/settings/README.md
-README.md: 3f43647f0558abf53c373ef7d97af16c0e17d2fe
-README.zh.md: b5779bfe5da4cae148bcc6515ef13790f78bca7a
+README.md: 6f3719c58564a90fec3bd9f305cfaeb2b7bf0bf4
+README.zh.md: 0efb16dd4e5d5faa5f16814b94d55a20dc4c06c3
diff --git a/packages/settings/README.md b/packages/settings/README.md
index 3f43647f05..6f3719c585 100644
--- a/packages/settings/README.md
+++ b/packages/settings/README.md
@@ -8,3 +8,5 @@ This family resolves user-editable configuration through registered namespaces a
 |---|---|---|
 | [`settings/`](settings/README.md) | Defines namespace registration, layered resolution, and commits | `ctx.settings` |
 | [`settings-local/`](settings-local/README.md) | Stores settings in a local file and observes external edits | registers on `ctx.settings` |
+
+The subsystem reference — namespaces, owner scopes, resolution order, hot commits — is [docs/subsystems/settings.md](../../docs/subsystems/settings.md).
diff --git a/packages/settings/README.zh.md b/packages/settings/README.zh.md
index b5779bfe5d..0efb16dd4e 100644
--- a/packages/settings/README.zh.md
+++ b/packages/settings/README.zh.md
@@ -8,3 +8,5 @@
 |---|---|---|
 | [`settings/`](settings/README.md) | 定义命名空间注册、分层解析与提交 | `ctx.settings` |
 | [`settings-local/`](settings-local/README.md) | 在本地文件中存储设置并观察外部编辑 | 注册到 `ctx.settings` |
+
+子系统参考——命名空间、owner scope、解析顺序、热提交——见 [docs/subsystems/settings.md](../../docs/subsystems/settings.md)。
diff --git a/packages/skill/README.i18n.yaml b/packages/skill/README.i18n.yaml
index 74875f2aa3..758d0552f9 100644
--- a/packages/skill/README.i18n.yaml
+++ b/packages/skill/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/skill/README.md
-README.md: 533904859ad998de4f371a073fde98b68660097b
-README.zh.md: 1fad581cc61a05251f671577dcb7edab37281283
+README.md: cd606e778335249bf8ecc876d3b1a4e5feb79448
+README.zh.md: 4db7e2524596f4c62144ec7eabe7c6af63e2e270
diff --git a/packages/skill/README.md b/packages/skill/README.md
index 533904859a..cd606e7783 100644
--- a/packages/skill/README.md
+++ b/packages/skill/README.md
@@ -12,3 +12,5 @@ This family discovers reusable agent instructions and exposes them to the model
 | [`tool-skill/`](tool-skill/README.md) | Publishes the skill catalog and model-facing loader | registers on `ctx.tools` |
 
 This capability remains outside the core control spine and can use local, embedded, or remote providers without changing the model-facing contract.
+
+The subsystem reference — discovery priority, catalog snapshots, the `skill` loader — is [docs/subsystems/skills.md](../../docs/subsystems/skills.md).
diff --git a/packages/skill/README.zh.md b/packages/skill/README.zh.md
index 1fad581cc6..4db7e25245 100644
--- a/packages/skill/README.zh.md
+++ b/packages/skill/README.zh.md
@@ -12,3 +12,5 @@
 | [`tool-skill/`](tool-skill/README.md) | 发布 skill 目录和面向模型的 loader | 注册到 `ctx.tools` |
 
 该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的契约。
+
+子系统参考——发现优先级、目录快照、`skill` 加载器——见 [docs/subsystems/skills.md](../../docs/subsystems/skills.md)。
diff --git a/packages/spill/README.i18n.yaml b/packages/spill/README.i18n.yaml
index 95800ac03e..62ed26a59b 100644
--- a/packages/spill/README.i18n.yaml
+++ b/packages/spill/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/spill/README.md
-README.md: b96375b1a332cd6e3e4da9c8b1c98011aa97c8bc
-README.zh.md: c8495068edf1035937c99198dfdb5db65c9a9e59
+README.md: 74fd4837cb23767754174df168f2f4ba71c2b938
+README.zh.md: 16d677719a9c3f4245a2f446017641ff6b50ffa8
diff --git a/packages/spill/README.md b/packages/spill/README.md
index b96375b1a3..74fd4837cb 100644
--- a/packages/spill/README.md
+++ b/packages/spill/README.md
@@ -11,3 +11,5 @@ This family persists oversized tool output and replaces the inline result with a
 | [`spill-policy/`](spill-policy/README.md) | Applies the post-execution spill policy | listens on `ctx.tools` |
 
 See the [tool-output spill decision](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the boundary between storage, retention, and tool-owned output handling.
+
+The subsystem reference — `SaveTextSpill`, owners/sources, the branded locator — is [docs/subsystems/spill.md](../../docs/subsystems/spill.md); rationale in the [tool output spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md).
diff --git a/packages/spill/README.zh.md b/packages/spill/README.zh.md
index c8495068ed..16d677719a 100644
--- a/packages/spill/README.zh.md
+++ b/packages/spill/README.zh.md
@@ -11,3 +11,5 @@
 | [`spill-policy/`](spill-policy/README.md) | 应用执行后 spill 策略 | 监听 `ctx.tools` |
 
 参见[工具输出 spill 决策](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中记录了存储、保留和工具自有输出处理之间的边界。
+
+子系统参考——`SaveTextSpill`、owner/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
diff --git a/packages/storage/README.i18n.yaml b/packages/storage/README.i18n.yaml
index 58fc19a4f8..ef32481991 100644
--- a/packages/storage/README.i18n.yaml
+++ b/packages/storage/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/storage/README.md
-README.md: a5f9d0204b93445699d28b1285a4a18f0408930e
-README.zh.md: 0710dfb57f96011755b253ad95a0f9d2c0923a70
+README.md: a178495fca5cc433182b8e75f20d479cb7c5bc99
+README.zh.md: 1a08f1676e5c699a55f9956a42059d1f5acf7e8d
diff --git a/packages/storage/README.md b/packages/storage/README.md
index a5f9d0204b..a178495fca 100644
--- a/packages/storage/README.md
+++ b/packages/storage/README.md
@@ -12,3 +12,5 @@ This family persists application data other than session event logs through name
 | [`storage-domain/`](storage-domain/README.md) | Provides validated domain-record storage | `ctx.storageDomain` |
 
 Consumers use a data form rather than accessing a backend directly. The [domain storage decision](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the family design.
+
+The subsystem reference — the backend seam, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).
diff --git a/packages/storage/README.zh.md b/packages/storage/README.zh.md
index 0710dfb57f..1a08f1676e 100644
--- a/packages/storage/README.zh.md
+++ b/packages/storage/README.zh.md
@@ -12,3 +12,5 @@
 | [`storage-domain/`](storage-domain/README.md) | 提供经过验证的领域记录存储 | `ctx.storageDomain` |
 
 消费方使用数据形式，而不是直接访问后端。[领域存储决策](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了该家族的设计。
+
+子系统参考——后端 seam、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index 11357c76d2..fe76e74a77 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/README.md
-README.md: 0a342569e66539e4987710b2e56f2946c97b1ac1
-README.zh.md: 5d2f7beef478b8bfd27b4772c7a951ea62cb10ef
+README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
+README.zh.md: fb18afba5d8680408f0f37ab75056a3fb0ef660a
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index 0a342569e6..c8969ad313 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -19,3 +19,5 @@ This family lets an agent delegate work to child agents. Multiple named provider
 | [`tool-subagent-report/`](tool-subagent-report/README.md) | Provides the child-to-parent report channel | registers in child scopes |
 
 See the decisions for the [capability family](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable children](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [control tools](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+
+The subsystem reference — start requests, results, live runs, the provider seam, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index 5d2f7beef4..fb18afba5d 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -19,3 +19,5 @@
 | [`tool-subagent-report/`](tool-subagent-report/README.md) | 提供从子级到父级的报告通道 | 注册到子级作用域 |
 
 参见[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)决策。
+
+子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 0ebb5bd4af..2088cbdb6b 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: f2b19436da40feb14d067e2cfc706222625680b5
-README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
+README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
+README.zh.md: d2c539fb1c66a914aa5f758d928fba01b5600d15
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index f2b19436da..9a8628e2b6 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -10,3 +10,5 @@ The shared process substrate for one execution world: executable lookup, fully-s
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
+
+The subsystem reference — spawn specs, output readers, outcomes, the `DSH_*` environment — is [docs/subsystems/subprocess.md](../../docs/subsystems/subprocess.md); the seam decision in the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 938312448d..d2c539fb1c 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -10,3 +10,5 @@
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
+
+子系统参考——spawn spec、输出读取器、结果、`DSH_*` 环境——见 [docs/subsystems/subprocess.md](../../docs/subsystems/subprocess.md)；seam 决定见 [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
diff --git a/packages/support/README.i18n.yaml b/packages/support/README.i18n.yaml
index 1b392a1729..824f20ae7e 100644
--- a/packages/support/README.i18n.yaml
+++ b/packages/support/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/support/README.md
-README.md: 15cb82d3d76a1241af8b40e1c8536292618409a9
-README.zh.md: ff8595b47f1a1220912dc77a072463adf74f7bf9
+README.md: bf0bba1ea7d21700a6743195ec966512c20e01bc
+README.zh.md: 47eba4d51c66914f388ba4a5925323173d5ed7e2
diff --git a/packages/support/README.md b/packages/support/README.md
index 15cb82d3d7..bf0bba1ea7 100644
--- a/packages/support/README.md
+++ b/packages/support/README.md
@@ -14,3 +14,5 @@ These packages support repository development, tests, and examples rather than p
 | [`llm-replay/`](llm-replay/README.md) | Replays recorded model responses for keyless tests and demos |
 
 A package moves out of `support/` when it gains a product contract and product consumers.
+
+The invariants contract is documented in [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md).
diff --git a/packages/support/README.zh.md b/packages/support/README.zh.md
index ff8595b47f..47eba4d51c 100644
--- a/packages/support/README.zh.md
+++ b/packages/support/README.zh.md
@@ -14,3 +14,5 @@
 | [`llm-replay/`](llm-replay/README.md) | 为无密钥测试和演示回放已记录的模型响应 |
 
 当一个包获得产品契约和产品消费方时，它会移出 `support/`。
+
+不变式契约记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。
diff --git a/packages/tasks/README.i18n.yaml b/packages/tasks/README.i18n.yaml
index 38cd47299c..d5df91be62 100644
--- a/packages/tasks/README.i18n.yaml
+++ b/packages/tasks/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/tasks/README.md
-README.md: 05ed9c439684337c45abe11f03c861a1b795b2ac
-README.zh.md: 16fe6c0a2b183b719cb6aa8ac068e34d51832a2b
+README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
+README.zh.md: d030081470a503fb52fd72dcc6f89f4c535dc38c
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index 05ed9c4396..e0b6769cd1 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -11,3 +11,5 @@ This family gives long-running tools one owner-isolated background-task protocol
 | [`tool-tasks/`](tool-tasks/README.md) | Exposes task control and completion notices to the model | registers on `ctx.tools` |
 
 See the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) decisions.
+
+The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.
diff --git a/packages/tasks/README.zh.md b/packages/tasks/README.zh.md
index 16fe6c0a2b..d030081470 100644
--- a/packages/tasks/README.zh.md
+++ b/packages/tasks/README.zh.md
@@ -11,3 +11,5 @@
 | [`tool-tasks/`](tool-tasks/README.md) | 向模型公开任务控制和完成通知 | 注册到 `ctx.tools` |
 
 参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
+
+子系统参考——id 方案、拥有者围栏契约、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
diff --git a/packages/todo/README.i18n.yaml b/packages/todo/README.i18n.yaml
index c75e09350a..57a1538b78 100644
--- a/packages/todo/README.i18n.yaml
+++ b/packages/todo/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/todo/README.md
-README.md: 66abf18131ee53d87e933757c40117841e94b07f
-README.zh.md: 38a6b3c22653b8e22cc0b693eb666620513a3d8c
+README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
+README.zh.md: 3c1c35187b5111f1fdb607d70b980be57e3e79c1
diff --git a/packages/todo/README.md b/packages/todo/README.md
index 66abf18131..6c7dccbbfb 100644
--- a/packages/todo/README.md
+++ b/packages/todo/README.md
@@ -9,3 +9,5 @@ The model-facing todo capability. It is a single **product** package because one
 | [`tool-todo/`](tool-todo/README.md) | Stores and exposes the session's todo list. | (registers on `ctx.tools`) |
 
 The child README owns the tool, persistence, and rendering contract.
+
+The event payload is documented on [docs/subsystems/session.md](../../docs/subsystems/session.md).
diff --git a/packages/todo/README.zh.md b/packages/todo/README.zh.md
index 38a6b3c226..3c1c35187b 100644
--- a/packages/todo/README.zh.md
+++ b/packages/todo/README.zh.md
@@ -9,3 +9,5 @@
 | [`tool-todo/`](tool-todo/README.md) | 存储并公开会话的 todo 列表。 | （注册到 `ctx.tools`） |
 
 子级 README 负责工具、持久化和渲染契约。
+
+事件载荷记录在 [docs/subsystems/session.md](../../docs/subsystems/session.md)。
diff --git a/packages/web/README.i18n.yaml b/packages/web/README.i18n.yaml
index cd412d1a99..87177273da 100644
--- a/packages/web/README.i18n.yaml
+++ b/packages/web/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/web/README.md
-README.md: 65b3dde1e2f9c35c308a10ca80245064f7a0361e
-README.zh.md: 43b8b7d9c53336e984d9c61fa9b612fc1733e31f
+README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
+README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc
diff --git a/packages/web/README.md b/packages/web/README.md
index 65b3dde1e2..811c8b3439 100644
--- a/packages/web/README.md
+++ b/packages/web/README.md
@@ -14,3 +14,5 @@ This family provides provider-neutral web search and fetch operations plus the m
 | [`tool-web/`](tool-web/README.md) | Exposes web search and fetch to the model | registers on `ctx.tools` |
 
 The [web capability decision](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) records why search and fetch share one provider-selection service.
+
+The subsystem reference — search/fetch requests and results, availability, `WebError` — is [docs/subsystems/web.md](../../docs/subsystems/web.md); rationale (including deferred SSRF protection) in the [web capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md).
diff --git a/packages/web/README.zh.md b/packages/web/README.zh.md
index 43b8b7d9c5..e328447d5d 100644
--- a/packages/web/README.zh.md
+++ b/packages/web/README.zh.md
@@ -14,3 +14,5 @@
 | [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
 
 [web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
+
+子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。
diff --git a/packages/workflow/README.i18n.yaml b/packages/workflow/README.i18n.yaml
index f02915a31d..05ad673c61 100644
--- a/packages/workflow/README.i18n.yaml
+++ b/packages/workflow/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/workflow/README.md
-README.md: 2416e26e73340a6d8624b8e77681dfc9f55fe7c5
-README.zh.md: a5c94a0a9799d78e5cca72394385b38d2fb2ba70
+README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
+README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
diff --git a/packages/workflow/README.md b/packages/workflow/README.md
index 2416e26e73..7b19cfd37f 100644
--- a/packages/workflow/README.md
+++ b/packages/workflow/README.md
@@ -12,3 +12,5 @@ This family runs model-authored orchestration workflows over subagents and expos
 | [`tool-ralph/`](tool-ralph/README.md) | Exposes the fixed fresh-agent Ralph workflow | registers on `ctx.tools` |
 
 Worker threads isolate workflow execution from the host event loop but are not a security boundary. See the [dynamic-workflow](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) and [Ralph tool](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) decisions.
+
+The subsystem reference — start requests, `WorkflowMeta`, results, live runs, `workflow/*` events — is [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md); decisions in the [dynamic-workflows](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) and [Ralph consumer](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Notes.
diff --git a/packages/workflow/README.zh.md b/packages/workflow/README.zh.md
index a5c94a0a97..33b3f26780 100644
--- a/packages/workflow/README.zh.md
+++ b/packages/workflow/README.zh.md
@@ -12,3 +12,5 @@
 | [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
 
 worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
+
+子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
diff --git a/packages/workspace/README.i18n.yaml b/packages/workspace/README.i18n.yaml
index 93dea4b3f0..c7723f6c56 100644
--- a/packages/workspace/README.i18n.yaml
+++ b/packages/workspace/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/workspace/README.md
-README.md: 9f6ead776c1e5d36af5b6917ad8f27725b11e6a0
-README.zh.md: aa691ec681112f4c25a6391c33eabd2711c7abfc
+README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
+README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29
diff --git a/packages/workspace/README.md b/packages/workspace/README.md
index 9f6ead776c..7e30f26a98 100644
--- a/packages/workspace/README.md
+++ b/packages/workspace/README.md
@@ -9,3 +9,5 @@ This family owns persistent workspaces: user directories with titles and ordered
 | [`workspace/`](workspace/README.md) | Registers workspaces and accounts for their sessions | `ctx.workspace` |
 
 The [workspace package reference](workspace/README.md) owns lifecycle, persistence, and deletion semantics.
+
+The subsystem reference — the entity, realpath canon, registration/resolution — is [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md); storage design in the [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
diff --git a/packages/workspace/README.zh.md b/packages/workspace/README.zh.md
index aa691ec681..6315ccb6b3 100644
--- a/packages/workspace/README.zh.md
+++ b/packages/workspace/README.zh.md
@@ -9,3 +9,5 @@
 | [`workspace/`](workspace/README.md) | 注册 workspace 并记录其会话归属 | `ctx.workspace` |
 
 [workspace 包参考](workspace/README.md)负责生命周期、持久化和删除语义。
+
+子系统参考——实体、realpath 规范、注册/解析——见 [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md)；存储设计见 [domain KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 120904d4b5..35fef7beaf 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -156,30 +156,30 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
-  ContentBlock: 'core.md',
+  ContentBlock: 'llm-streaming.md',
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
-  GenerateOptions: 'core.md',
+  GenerateOptions: 'llm-streaming.md',
   InboxItem: 'core.md',
   InboxPlacement: 'core.md',
-  MessageId: 'core.md',
+  MessageId: 'llm-streaming.md',
   HookContext: 'core.md',
   SettleReason: 'core.md',
-  AdapterRegistrationHandle: 'core.md',
-  DirectoryRegistrationHandle: 'core.md',
-  LlmCallConfig: 'core.md',
-  LlmModelContext: 'core.md',
-  LlmModelReasoningInfo: 'core.md',
-  LlmResolvedModelInfo: 'core.md',
+  AdapterRegistrationHandle: 'llm-streaming.md',
+  DirectoryRegistrationHandle: 'llm-streaming.md',
+  LlmCallConfig: 'llm-streaming.md',
+  LlmModelContext: 'llm-streaming.md',
+  LlmModelReasoningInfo: 'llm-streaming.md',
+  LlmResolvedModelInfo: 'llm-streaming.md',
   LlmFailure: 'llm-streaming.md',
-  LlmModelInfo: 'core.md',
-  LlmProviderInfo: 'core.md',
-  LlmConfigurableProvider: 'core.md',
-  LlmModelDiscoveryRequest: 'core.md',
-  LlmDiscoveredModel: 'core.md',
+  LlmModelInfo: 'llm-streaming.md',
+  LlmProviderInfo: 'llm-streaming.md',
+  LlmConfigurableProvider: 'llm-streaming.md',
+  LlmModelDiscoveryRequest: 'llm-streaming.md',
+  LlmDiscoveredModel: 'llm-streaming.md',
   ResolvedRetryPolicy: 'llm-streaming.md',
-  Message: 'core.md',
-  MessageSource: 'core.md',
+  Message: 'llm-streaming.md',
+  MessageSource: 'llm-streaming.md',
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 317ddec122..b3bf8eaec4 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -7,22 +7,17 @@
       "source": "packages/util/brand/src/index.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
-      "symbol": "ContentBlockMap",
-      "source": "packages/llm/llm/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "AssistantProvenance",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "Message",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "MessageSourceMap",
       "source": "packages/llm/llm/src/message.ts"
     },
@@ -42,22 +37,22 @@
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "FinishReasonMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "AdapterRegistrationHandle",
       "source": "packages/llm/llm/src/index.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmProviderInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
@@ -72,47 +67,47 @@
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelContext",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ReasoningEffortId",
       "source": "packages/llm/llm/src/brand.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmReasoningEffortInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelReasoningInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmResolvedModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "GenerateOptions",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ToolSchema",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmCallConfig",
       "source": "packages/llm/llm/src/call-config.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmCallConfigAdapterDefaults",
       "source": "packages/llm/llm/src/call-config.ts"
     },
@@ -1491,7 +1486,7 @@
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmConfigurableProvider",
       "source": "packages/llm/llm/src/types.ts"
     },
diff --git a/website/docs.ts b/website/docs.ts
index 9a28aeea4d..1f7fa316a5 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -259,7 +259,7 @@ const cordisPrimerReference = pairedPages([
 
 const subsystemsReference = pairedPages(([
   ['README.md', '子系统', 'Subsystems', 0],
-  ['core.md', '核心数据结构', 'Core data structures', 1],
+  ['core.md', '核心', 'Core', 1],
   ['scope.md', '作用域', 'Scopes', 2],
   ['session.md', '会话', 'Sessions', 3],
   ['session-query.md', '会话查询', 'Session query', 4],

From a2aa567371026f23ad1d20236f19c8e97be8cf29 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 3 Aug 2026 16:34:00 +0800
Subject: [PATCH 167/262] docs(subsystems): open core.md on agent
 creation/ownership and the Agent contract; enforce a complete folder index

core.md claimed to be the packages/core reference but opened on repo-wide type patterns and never documented the ownership vocabulary: AgentHandle, CreateAgentOptions, ResumeAgentOptions, and AgentFactory were TYPE_LINK_EXEMPTIONS pointing at a package README, invisible to the folder that calls itself the type reference. The page now reads spine map -> creation and ownership (AgentHandle pasted; the options and factory summarized with links into the generated registry section) -> the Agent handle (AgentStatus, AgentOptions, SteeringOutcome, SteeringReceipt, and SettleReason now pasted; the one settlement prose wall split by topic; delivery vocabulary ordered as a message travels) -> initiator -> interception -> a Sessions summary -> the ToolDefinition pointer -> an explicitly framed repo-wide patterns tail (the ...Map pattern, branded ids). The duplicate SessionEvent paste is gone -- session.md owns it and LINK_MAP follows -- the four ownership types moved from TYPE_LINK_EXEMPTIONS into LINK_MAP -> core.md, and three dead LINK_MAP entries (ContinuationDecision, ContinuationStop, HookContext) no longer name types absent from the source tree. The "what this page owns" meta-section folds into the intro.

The subsystems README index silently lost tasks.md and session-reference.md on both language sides during a base absorption; the rows are restored and scripts/project-doc-site.spec.ts now fails when any page misses either side of the index (proven red on a removed row). tools.md links ToolSchema to its llm-streaming.md declaration instead of calling it core; subagent.md links AgentHandle and CreateAgentOptions.seed to the new section. A new Agent Note records the package-anchored page-scoping decision; the 2026-06-20 catalog note marks its spine-vs-seam rule superseded as the page-scoping rule while keeping the type-equiv mechanism current, and docs/AGENTS.md cites the new note.
---
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   2 +
 ...6-06-20-core-data-structures-catalog.zh.md |   4 +-
 ...package-anchored-subsystem-pages.i18n.yaml |   6 +
 ...-08-03-package-anchored-subsystem-pages.md |  34 +
 ...-03-package-anchored-subsystem-pages.zh.md |  34 +
 docs/AGENTS.md                                |   6 +-
 docs/subsystems/README.i18n.yaml              |   4 +-
 docs/subsystems/README.md                     |   7 +-
 docs/subsystems/README.zh.md                  |   7 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       | 692 ++++++---------
 docs/subsystems/core.zh.md                    | 832 +++++++-----------
 docs/subsystems/http-server.i18n.yaml         |   2 +-
 docs/subsystems/http-server.zh.md             |   2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              | 193 +++-
 docs/subsystems/llm-streaming.zh.md           | 193 +++-
 docs/subsystems/permission.i18n.yaml          |   4 +-
 docs/subsystems/permission.md                 |   2 +-
 docs/subsystems/permission.zh.md              |   2 +-
 docs/subsystems/persistence.i18n.yaml         |   4 +-
 docs/subsystems/persistence.md                |   2 +-
 docs/subsystems/persistence.zh.md             |   2 +-
 docs/subsystems/session-projection.i18n.yaml  |   4 +-
 docs/subsystems/session-projection.md         |   2 +-
 docs/subsystems/session-projection.zh.md      |   2 +-
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   2 +-
 docs/subsystems/session.zh.md                 |   2 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   4 +-
 docs/subsystems/subagent.zh.md                |   4 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |   2 +-
 docs/subsystems/tools.zh.md                   |   2 +-
 packages/interaction/README.i18n.yaml         |   4 +-
 packages/interaction/README.md                |   2 +-
 packages/interaction/README.zh.md             |   2 +-
 packages/self-modification/README.i18n.yaml   |   2 +-
 packages/self-modification/README.zh.md       |   2 -
 scripts/gen-cordis-catalog.ts                 |  13 +-
 scripts/project-doc-site.spec.ts              |  17 +-
 .../request-response.expected.json            |   4 +-
 scripts/type-equiv.manifest.json              |  30 +-
 website/docs.ts                               |   2 +-
 46 files changed, 1126 insertions(+), 1034 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
 create mode 100644 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 1b1a93fc99..def34cdfbd 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: b358ad54652e5b16ae90037c128cf756bcfdaed3
-2026-06-20-core-data-structures-catalog.zh.md: d84c2befaee4c2032b358ed1a7949ac0151ae74c
+2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
+2026-06-20-core-data-structures-catalog.zh.md: 96c606a3d65a67e757960c5cbc997e717f11e8d5
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index b358ad5465..9a3f80df59 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -16,6 +16,8 @@ A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type
 
 ### What counts as "core" — the spine-vs-seam line
 
+> **Superseded as the page-scoping rule** by [package-anchored subsystem pages](2026-08-03-package-anchored-subsystem-pages.md): each page now anchors to the package group that declares its vocabulary. The `ts type-equiv` mechanism below remains current.
+
 The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own seam page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
 The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a seam-page detail.*** Worked through:
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index d84c2befae..96c606a3d6 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -16,6 +16,8 @@ Status: implemented
 
 ### 何为「核心」——主干与 seam 的分界线
 
+> **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
+
 范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入子页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
 确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子页面细节。*** 逐一验证如下：
@@ -25,7 +27,7 @@ Status: implemented
 - `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
 - 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇是子页面。
 
-`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到子页面获取各 seam 的细节。子页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
+`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级 seam 页面获取各 seam 的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的 seam 页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
 
 ### `ts type-equiv` 机制——既逐字又防漂移
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
new file mode 100644
index 0000000000..7bc08eb82d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.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 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
+2026-08-03-package-anchored-subsystem-pages.md: 5ba7937f0c142727d343a107a3ff87f5f337931e
+2026-08-03-package-anchored-subsystem-pages.zh.md: 27d56158a69a8144b0915054032fb3b54493bd0b
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
new file mode 100644
index 0000000000..5ba7937f0c
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
@@ -0,0 +1,34 @@
+# Agent Note: Package-anchored subsystem pages and thin group READMEs
+
+Status: implemented
+
+English | [中文](2026-08-03-package-anchored-subsystem-pages.zh.md)
+
+## Problem
+
+The [subsystems catalog](2026-06-20-core-data-structures-catalog.md) scoped its front page by the spine-vs-seam rule: a type was "core" if the loop holds, derives, streams, or logs it on every turn. That rule selected types, not packages, so as the folder grew to forty-plus pages the front page became a cross-package grab-bag: LLM conversation vocabulary sat above the agent contracts, the creation/ownership vocabulary (`AgentHandle`, `CreateAgentOptions`, `ResumeAgentOptions`, `AgentFactory`) was documented nowhere in the folder because the generator exempted it to a package README, and a reader could not predict which page documents a type from where the type lives. Package-group READMEs meanwhile had no common shape — some carried sectioned tables, stray design essays, or trailing paragraphs that belonged on a subsystem page.
+
+## Decision
+
+Every `docs/subsystems/` page anchors to the package or package group that declares its vocabulary, and page membership follows the repository layout: [core.md](../../../../docs/subsystems/core.md) is the `packages/core` page (creation and ownership, the `Agent` handle with its delivery/cancellation/interception contracts, pointers to the group's dedicated pages), [llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) owns `packages/llm` end-to-end, and so on. Repo-wide type patterns (`…Map → derived-union`, branded ids) stay on core.md in an explicitly framed closing section rather than interleaved with the package content. This supersedes the spine-vs-seam rule *as the page-scoping rule*; the placement heuristic that survives is simpler: a type is documented where its declaring package's page is, and machinery keeps living with its machinery.
+
+Every type a generated signature references must resolve somewhere in the folder: the agent ownership vocabulary moved from the generator's `TYPE_LINK_EXEMPTIONS` into `LINK_MAP → core.md`, so exemptions are reserved for genuinely service-local or vendored shapes. Each pasted declaration has one home (`SessionEvent` lives on [session.md](../../../../docs/subsystems/session.md); core.md summarizes and links).
+
+Every `packages/<group>/README.md` pair is a thin front door in one shape: a why-first intro paragraph, a package table (Package / Role / ctx key), and a closing pointer to the owning subsystems page. Load-bearing prose that outgrows that shape relocates to the owning subsystems page rather than being deleted.
+
+The [subsystems README](../../../../docs/subsystems/README.md) indexes every page in the folder on both language sides; `scripts/project-doc-site.spec.ts` enforces one table row per page, so a page added by a later PR (or absorbed in a merge) cannot silently miss the index.
+
+## Alternatives considered
+
+**Keep the spine-vs-seam scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
+
+**A flat single-document catalog.** Already rejected in the [original catalog note](2026-06-20-core-data-structures-catalog.md); the growth to forty-one pages confirmed that verdict.
+
+**Document ownership vocabulary only in package READMEs (the exemption status quo).** This left `AgentHandle` and the create/resume options invisible to the folder that claims to be the type reference, and the generated `Types:` footers could not link them.
+
+## Consequences
+
+- Which page documents a type is predictable from `packages/<group>/`; the subsystems README is a complete index enforced by test.
+- Generated signature footers link the agent ownership vocabulary instead of silently exempting it.
+- `verify-type-equiv`'s 1:1 manifest keeps each paste single-homed; the duplicate `SessionEvent` paste is gone.
+- The [original catalog note](2026-06-20-core-data-structures-catalog.md) remains the owner of the `ts type-equiv` drift-gate mechanism; only its page-scoping rule is superseded here.
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
new file mode 100644
index 0000000000..27d56158a6
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
@@ -0,0 +1,34 @@
+# Agent Note：按包锚定的子系统页面与轻薄的分组 README
+
+Status: implemented
+
+[English](2026-08-03-package-anchored-subsystem-pages.md) | 中文
+
+## Problem
+
+[子系统目录](2026-06-20-core-data-structures-catalog.md)最初用主干-vs-seam 规则界定首页范围：如果循环在每个轮次都持有、派生、流式传输或记录某个类型，它就是「核心」。该规则选择的是类型而非包，因此当目录增长到四十多页后，首页变成了跨包大杂烩：LLM 对话词汇排在 agent 契约之前，创建/所有权词汇（`AgentHandle`、`CreateAgentOptions`、`ResumeAgentOptions`、`AgentFactory`）在目录中无处记录（生成器把它们豁免给了某个包 README），读者无法根据类型所在位置预测哪一页记录它。与此同时，各包分组 README 没有统一形状——有的带分节表格、游离的设计短文，或本应属于子系统页面的尾部段落。
+
+## Decision
+
+每个 `docs/subsystems/` 页面锚定到声明其词汇的包或包分组，页面归属跟随仓库布局：[core.md](../../../../docs/subsystems/core.md) 是 `packages/core` 的页面（创建与所有权、`Agent` 句柄及其投递/取消/拦截契约、指向该组专属页面的指针），[llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) 端到端拥有 `packages/llm`，依此类推。全仓通用类型模式（`…Map → 派生联合`、品牌化 id）保留在 core.md 一个明确标注的收尾小节中，而不是与包内容交错。这在*页面范围界定规则*的意义上取代了主干-vs-seam 规则；存活下来的放置启发式更简单：类型记录在其声明包对应的页面，机制仍与其机制放在一起。
+
+生成签名引用的每个类型都必须能在目录中某处解析：agent 所有权词汇从生成器的 `TYPE_LINK_EXEMPTIONS` 移入 `LINK_MAP → core.md`，因此豁免只留给真正服务本地或 vendored 的形状。每个粘贴的声明只有一个家（`SessionEvent` 位于 [session.md](../../../../docs/subsystems/session.md)；core.md 概括并链接）。
+
+每个 `packages/<group>/README.md` 配对都是统一形状的轻薄门面：一段以「为什么」开头的介绍、一张包表格（包 / 角色 / ctx 键）、一个指向拥有方子系统页面的收尾指针。超出该形状的承重散文迁移到拥有方子系统页面，而非删除。
+
+[子系统 README](../../../../docs/subsystems/README.md) 在两个语言侧索引目录中的每一页；`scripts/project-doc-site.spec.ts` 强制每页一行表格，因此后续 PR 新增（或合并吸收）的页面无法悄悄缺席索引。
+
+## Alternatives considered
+
+**保留主干-vs-seam 界定规则。**它逐类型回答「这个类型是核心吗？」，这正是首页积累了四个包的类型、却缺失 `packages/core/agent` 一半公开 surface 的原因。按仓库布局可预测性胜出。
+
+**扁平的单文档目录。**在[原目录 note](2026-06-20-core-data-structures-catalog.md) 中已被否决；增长到四十一页证实了该结论。
+
+**只在包 README 中记录所有权词汇（豁免的现状）。**这让 `AgentHandle` 与 create/resume 选项在自称类型参考的目录中不可见，生成的 `Types:` 页脚也无法链接它们。
+
+## Consequences
+
+- 哪一页记录某类型可由 `packages/<group>/` 预测；子系统 README 是由测试强制的完整索引。
+- 生成的签名页脚链接 agent 所有权词汇，而不是静默豁免。
+- `verify-type-equiv` 的 1:1 manifest 保证每个粘贴单一归属；重复的 `SessionEvent` 粘贴已移除。
+- [原目录 note](2026-06-20-core-data-structures-catalog.md) 仍拥有 `ts type-equiv` 漂移检查机制；此处仅取代其页面范围界定规则。
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 88c90678de..a5eca656db 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -21,8 +21,8 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
 | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [subsystems/](subsystems/README.md) | One reference page per subsystem: literal type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
-| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and concise verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
@@ -39,7 +39,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index 3303bcb935..f1636e0191 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: d225e5f4eeb31d1e6c71cbd8311e28bae1e8b3a5
-README.zh.md: 9f78ac3e1c79440b053ee4e344dbdba2c11b3dfc
+README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
+README.zh.md: dda61d86c4d00117af851b4a55d16b97c6bc2f10
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index d225e5f4ee..1c3d14aeb4 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -6,7 +6,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 
 | Page | Owns |
 |---|---|
-| [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, the `Agent` handle with its delivery/cancellation/interception contracts, the `SessionEvent` envelope, branded ids, the `…Map → derived-union` pattern |
+| [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, agent creation and ownership (`AgentHandle`), the `Agent` handle with its delivery/cancellation/interception contracts, and the repo-wide type patterns (`…Map → derived-union`, branded ids) |
 | [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
@@ -19,6 +19,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
 | [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
 | [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
+| [session-reference.md](session-reference.md) | structured cross-session references: `SessionReferenceInput`/`Candidate`, prepared message contexts, the stable error taxonomy |
 | [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
 | [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
@@ -36,12 +37,12 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
 | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
 | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
+| [tasks.md](tasks.md) | the background-task runtime: branded `TaskId`s, the producer contract, consumer views, `ctx.tasks` service behavior |
 | [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
 | [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
 | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
-| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
+| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the claimable fallback seat, index taps |
 | [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
-| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 9f78ac3e1c..dda61d86c4 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,7 +6,7 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、`Agent` 句柄及其投递/取消/拦截契约、`SessionEvent` 信封、品牌化 id，以及 `…Map → 派生联合` 模式 |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截契约，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
 | [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
@@ -19,6 +19,7 @@
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
 | [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
 | [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
@@ -36,12 +37,12 @@
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
+| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 契约、consumer 视图、`ctx.tasks` 服务行为 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
 | [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
-| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
+| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
-| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 16c8e29cf2..caf9356ee9 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: ba9319d377cf250148a145ba3f1fa1baa967c858
-core.zh.md: 276dc4f99f1f802e66aca050b2fbcdc178931611
+core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
+core.zh.md: 6878300dc2cbd82d220e17d2d6f5e1009f41c48f
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index ba9319d377..cc9cc30677 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -2,11 +2,11 @@
 
 English | [中文](core.zh.md)
 
-The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns the spine's shared vocabulary — the `Agent` handle, its delivery and interception contracts, and the repo-wide type patterns — and orients to the group's dedicated pages; the folder is indexed in the [subsystems README](README.md).
+The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns what the `agent`/`agent-loop` pair declares — how an agent is created and owned, and the `Agent` handle with its delivery, cancellation, and interception contracts — plus the two type patterns every subsystem follows; the group's dedicated pages and the rest of the folder are indexed in the [subsystems README](README.md).
 
 ## The spine, package by package
 
-A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it.
+A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it. The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md).
 
 | Package | Owns | Page |
 |---|---|---|
@@ -19,208 +19,45 @@ A turn flows through the six packages in one loop: the driver in [`agent-loop`](
 
 `scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
 
-<a id="what-counts-as-core"></a>
+## Creation and ownership
 
-## What this page owns
+Consumers create agents through `ctx.agents` — `create()` builds a fresh session and agent under one caller-supplied `SessionId`, `resume()` loads a persisted session first — or declaratively through the loop's config entries. Programmatic creation returns the owner's handle:
 
-The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md); the session-event, prompt-assembly, and tool vocabularies live on this group's dedicated pages above. What remains here is the vocabulary shared by everything: the `Agent` handle and its delivery, cancellation, and interception contracts (declared by `packages/core/agent`), the `SessionEvent` envelope, and the two type patterns every subsystem follows. The scoping rule is recorded in the [subsystems-catalog Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md): the type you write, hold, or receive is documented where its declaring subsystem is; the machinery that types, renders, or persists it stays on that machinery's page.
-
-## The `…Map → derived-union` pattern
-
-Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
-
-```ts ignore-check
-// The pattern, schematically:
-interface ThingMap {
-  'a': { kind: 'a'; /* … */ }
-  'b': { kind: 'b'; /* … */ }
-}
-type ThingKind = keyof ThingMap          // 'a' | 'b'
-type Thing = ThingMap[keyof ThingMap]    // the discriminated union
-
-// A plugin extends it without touching the source package:
-declare module '@deepseek-ai/dsh-llm' {
-  interface ThingMap {
-    'c': { kind: 'c'; /* … */ }
-  }
-}
-```
-
-Six canonical maps use this pattern; a plugin author extends these:
-
-| Map | Package | Derives | Catalog |
-|---|---|---|---|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
-| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
-| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
-| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
-
-Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
-
-## Branded IDs
-
-IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
-
-The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
-
-Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
-
-```ts type-equiv
-/** A string carrying a compile-time-only brand `B`. */
-type Branded<B extends string> = string & { readonly [BRAND]: B }
-```
-
-The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
-
-## Sessions
-
-A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. The event vocabulary derives from `SessionEventMap`:
-
-Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
 
 ```ts type-equiv
 /**
- * One immutable entry in the session log.
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
+ * only the holder can tear this agent down. The registered factory provider is
+ * also a structural owner because the scoped agent depends on that provider's
+ * service surface; provider unload stops and drains every live handle it made.
+ * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
+ * its session from the store, and finally unwinds its scoped world.
  *
- * A proper discriminated union over `type` (not independent `type`/`data`
- * unions), so `switch (event.type)` narrows `event.data` without casts.
- *
- * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `steering/message`).
- * Non-surface events (boundary markers, chunks, usage, errors) never carry
- * surface metadata — the compiler enforces this at `Session.append()`
- * call sites.
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
+ * exposed only to the consumer owner that created it; the structural provider
+ * reaches the same teardown internally. Config-created agents (the loop's own
+ * startup) are owned by the loop fiber and never need a handle.
  */
-type SessionEvent<T extends SessionEventType = SessionEventType> = {
-  [K in SessionEventType]: {
-    type: K
-    /** Monotonic sequence number within the session. */
-    seq: number
-    /** Unix epoch milliseconds. */
-    time: number
-    data: SessionEventMap[K]
-  } & (K extends SurfaceEventType ? {
-    /**
-     * Seq numbers of events that are provenance sources of this event
-     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node). An
-     * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
-     */
-    sourceEventSeqs?: number[]
-    /** How this event entered the surface; absent for non-surface events. */
-    surfaceOp?: SurfaceOp
-  } : object)
-}[T]
+interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
 ```
 
-The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+`CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, seed boundary, origin classification, delegation depth), an optional `seed` replay prefix for forks, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
+
+`AgentFactory` is the creation seam behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
 
 ## The agent handle
 
-`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it.
+`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against; `ctx.agents.get(id)` returns it, and the [initiator scope](#initiating-agent) carries it. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it. The unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
-/**
- * Which inbox queue a {@link Agent.send} item joins:
- * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
- * - `next-step` — during prompt admission or an open turn, the item stages for
- *   the next safe step boundary; otherwise it is promoted per its `wakeup`
- *   flag.
- */
-type SendTarget = 'next-turn' | 'next-step'
-```
-
-```ts type-equiv
-/** Resolved inbox placement reported when an accepted message is enqueued. */
-type InboxPlacement = 'queued' | 'steering'
-```
-
-`InboxItemId` is a process-local branded string minted for each accepted FIFO occurrence. It is intentionally distinct from `MessageId`: sending the same immutable message twice creates two independently addressable pending items.
-
-```ts type-equiv
-/** One independently addressable accepted occurrence in an agent inbox. */
-interface InboxItem {
-  /** Agent-loop-minted occurrence identity. */
-  readonly id: InboxItemId
-  /** Identified message delivered by the caller. */
-  readonly message: UserMessage
-  /** Acceptance-time FIFO classification. */
-  readonly placement: InboxPlacement
-}
-```
-
-```ts type-equiv
-/** A user-requested mutation of one still-pending queued occurrence. */
-type InboxAction =
-  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
-  | { readonly kind: 'remove' }
-  | { readonly kind: 'steer' }
-```
-
-```ts type-equiv
-/** Result of applying an inbox action at the synchronous ownership boundary. */
-type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
-```
-
-```ts type-equiv
-/**
- * Options for the unified {@link Agent.send} primitive over the
- * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
- * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
- * {@link Agent.inject} (`next-step`/no-wakeup).
- *
- * The object is complete so routing policy is explicit.
- */
-interface SendOptions {
-  /** Queue the item joins. */
-  target: SendTarget
-  /**
-   * Whether this item makes the model run: wake a parked driver (`next-turn`)
-   * or force a continuation step (`next-step` while running). A `false`
-   * `next-turn` item queues without waking; a `false`
-   * `next-step` item attaches durable context without forcing another step
-   * (the injection preset).
-   */
-  wakeup: boolean
-}
-```
-
-The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable when an edit replaces content or strict steer transfers the immutable message. The original queued occurrence ends and strict steer accepts a new steering occurrence with a distinct `InboxItemId`. Injection bypasses the FIFOs and never appears on inbox lifecycle events.
-
-```ts type-equiv
-/** Options for {@link Agent.cancel}. */
-interface CancelOptions {
-  /**
-   * Preserve queued and steering inbox items instead of discarding them. The
-   * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no `agent/inbox/discard` fires.
-   */
-  keepInbox?: boolean
-}
-```
-
-`SteeringReceipt.outcome` always resolves. `admitted` identifies the turn and step whose immutable request history contains that exact message; `rejected` means lifecycle or terminal policy discarded it first. Synchronous input validation still throws from `steer()`.
-
-```ts type-equiv
-/** Stable runtime cause accepted by {@link Agent.cancel}. */
-type AgentCancelCause =
-  | { readonly kind: 'user' }
-  | { readonly kind: 'parent' }
-```
-
-`Agent` is an interface over the public live-agent contract. Concrete drivers own the `followup`/`steer`/`inject` aliases and route them through `send`'s (`target` × `wakeup`) matrix.
-
-```ts type-equiv
-/**
- * Public live-agent handle with aliases over the unified delivery primitive.
- * @typert object
- */
+/** Public live-agent handle. */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -228,78 +65,28 @@ interface Agent {
   readonly options: AgentOptions
   /** The live session this agent drives; its log is the durable source of truth. */
   readonly session: Session
+  /** The agent-owned projection of durable pending work. */
+  readonly inbox: Inbox
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
-  /**
-   * Whether a `next-step` send currently stages for prompt admission or the
-   * open turn. Unlike {@link status}, this excludes admission exit and turn
-   * settlement, when a waking `next-step` send becomes a queued follow-up.
-   */
-  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
-  /**
-   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
-   * It routes the caller's typed content and source as follows:
-   *
-   * - `next-turn` queues an item that becomes the sole ordinary message of its
-   *   own FIFO-ordered turn; `wakeup:true` wakes a
-   *   parked driver, while `wakeup:false` queues without waking.
-   * - `next-step` with `wakeup:true` stages steering during prompt admission
-   *   or an open turn; outside that window it falls back to a woken
-   *   `next-turn`.
-   * - `next-step` with `wakeup:false` injects durable model-facing context
-   *   without running the model: admission or an open turn stages it for the
-   *   next safe log position, while an injection outside that window appends
-   *   immediately without opening a turn. If admission closes without a turn,
-   *   a context-only boundary appends immediately; context staged beside
-   *   steering remains pending with it.
-   * The agent publishes or queues the identified frozen message as-is.
-   * @param message - identified model-facing content and its producer provenance.
-   * @param options - target queue and wakeup decision.
-   */
-  send(message: UserMessage, options: SendOptions): void
-
-  /**
-   * Reserve admission of the next ordinary turn while this agent is idle, so an
-   * operation can mutate durable history before any queued prompt derives a
-   * request from it. Already-accepted waking work has right of way, including a
-   * send whose wake is still a pending microtask. Later sends keep their
-   * ordinary placement, FIFO order, and `wakeup` facts, and
-   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
-   * a queued follow-up rather than steering; cancellation and disposal may
-   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
-   * a live reservation as activity, while lifecycle teardown does not await it.
-   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
-   */
-  reserveTurnAdmission(): (() => void) | undefined
-
-  /**
-   * Mutate one still-pending queued occurrence synchronously. Editing preserves
-   * the message identity and queue position; removal publishes its terminal
-   * discard. Steer strictly transfers the message into the current next-step
-   * window, or returns `steer-unavailable` without changing the queued
-   * occurrence. Steering occurrences and driver-claimed items return
-   * `not-found`.
-   * @param id - independently addressable queued occurrence.
-   * @param action - edit, remove, or strict steer operation.
-   * @returns the applied outcome or the reason no mutation occurred.
-   */
-  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
-
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn. An effective call first emits `agent/cancel-requested` with the
-   * resolved typed cause. The first cause wins for the active turn, and
-   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
-   * cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the current turn signal.
+   * turn or between-turn task. The first cause wins for that activity. With no
+   * active activity, cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the active operation signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
+  /**
+   * Resolve after the current whole-agent activity reaches quiescence. This
+   * follows replacement work started before the observed driver retires,
+   * but does not identify the settlement of any particular message.
+   * @returns fulfillment after no active driver or maintenance task remains.
+   */
   whenIdle(): Promise<void>
 
   /**
@@ -334,35 +121,86 @@ interface Agent {
   followup(message: UserMessage): void
 
   /**
-   * Submit steering with a message-owned admission receipt — the
-   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
-   * open turn, the message waits in the steering FIFO until a committed step
-   * snapshots it; outside that window it enters the ordinary queued FIFO. The
-   * receipt resolves `admitted` only after the message joins that step's
-   * immutable request history, or `rejected` when terminal policy,
-   * cancellation, or disposal discards it first. A non-terminal turn close may
-   * leave it staged for a later admitted prompt without settling the receipt.
+   * Submit steering for the nearest step. An idle driver starts a turn;
+   * a running driver consumes it at its next step boundary.
+   * A rejected step leaves steering parked in the inbox until the next
+   * wake; cancellation or disposal may discard pending steering.
    * @param message - identified steering content and its producer provenance.
-   * @returns the receipt for this exact message's eventual admission outcome.
    */
-  steer(message: UserMessage): SteeringReceipt
+  steer(message: UserMessage): void
 
   /**
-   * Append model-facing context without running the model — the
-   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
-   * stages it at the next safe log position; outside that window it appends
-   * immediately without opening a turn. If admission closes without a turn,
-   * a context-only boundary appends immediately; context staged beside
-   * steering remains pending with it.
+   * Queue model-facing context for the next pre-step without waking the
+   * driver. A running driver claims it at the nearest later step boundary;
+   * idle drivers leave it pending until follow-up or steering
+   * wakes them. It may miss a request whose pre-step already claimed its
+   * batch. Cancellation or disposal may discard pending context.
    * @param message - identified injected context and its producer provenance.
    */
   inject(message: UserMessage): void
 }
 ```
 
-`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. A live turn-admission reservation is quiescence-relevant without changing `status` or turning later queue entries into steering; its only authority is to defer the next driver claim until release. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
+```ts type-equiv
+/**
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
+ * `idle` means no driver is active; `running` begins when waking input starts
+ * cancellable pre-step processing and lasts while the driver drains,
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
+ * it is not a third observable status.
+ */
+type AgentStatus = 'idle' | 'running'
+```
 
-The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
+`running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `followup()` returns no handle: its `MessageId` identifies durable inbox insertion, claim, and discard facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
+
+```ts type-equiv
+/** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
+interface AgentOptions {
+  /** Provider route (must have a registered adapter at call time). */
+  provider?: string
+  /** Model id interpreted by the selected provider adapter. */
+  model?: string
+  /** Maximum output tokens for each conversation-model request. */
+  maxTokens?: number
+}
+```
+
+Dispatch requires `provider` and `model` after `agent/request`. When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. An agent-scoped `deployment:persona` prompt section may shadow the global default persona.
+
+The inbox is the delivery vocabulary — two ordered pending-message lists the agent owns as a durable projection:
+
+```ts type-equiv
+/** One of the two ordered pending-message lists owned by an agent. */
+type InboxTarget = 'next-turn' | 'next-step'
+```
+
+Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. `Inbox.append`, `prepend`, `replace`, `remove`, `clear`, `splice`, and `claim` record normalized durable `agent/inbox/spliced` mutations and reject duplicate pending ids. `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists; replacement may change identity and emits the old message as discarded followed by the new message as inserted. Ordinary removals and `clear()` are cancellations. `claim(target)` removes the proposed step batch — all `next-step` input plus, at a turn boundary, one `next-turn` message — through pure deletion splices without emitting discarded notifications, and the loop separately emits per-message claimed notifications. Whole-queue consumers such as UI projections reconstruct `nextTurn` and `nextStep` from the durable splices, while consumers following one message use the exact `agent/inbox/inserted`, `claimed`, and `discarded` notifications.
+
+Cancellation:
+
+```ts type-equiv
+/** Options for {@link Agent.cancel}. */
+interface CancelOptions {
+  /**
+   * Preserve queued and steering inbox items instead of discarding them. The
+   * active turn is still aborted, but un-started and pending work survives for a
+   * later turn and no canceled inbox splice is logged.
+   */
+  keepInbox?: boolean | undefined
+}
+```
+
+```ts type-equiv
+/** Why an active agent driver was cancelled. */
+type AgentCancelCause =
+  | { readonly kind: 'user' }
+  | { readonly kind: 'parent' }
+  | { readonly kind: 'hook'; readonly reason: string }
+  | { readonly kind: 'disposed' }
+```
+
+The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
@@ -372,22 +210,19 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results.
+Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
-`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow may rewrite the claimed prompt or attach `additionalContexts`; block rejects admission without creating turn events:
+`agent/pre-step` receives one payload carrying the exclusive claimed batch (`messages`), the proposed step's coordinates (`turn`, `step`), and the current turn's cancellation `signal`. The initial proposal runs inside an open turn before any step; a tool continuation may submit an empty claimed batch between steps:
+
+It returns a `PreStepDecision`. Reject opens no step. Enter supplies the complete message batch appended after `step/start`; claimed messages omitted by the final decision remain removed, while input inserted after the claim stays pending:
 
 ```ts type-equiv
-/**
- * Prompt interception result. `allow.content` replaces the prompt, while
- * `additionalContexts` appends model-facing context before the turn starts.
- * An `allow` returned by a listener is authoritative: a listener wrapping
- * `next()` preserves both fields unless it intentionally replaces them.
- */
-type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
-  | { kind: 'block'; reason: string }
+/** Whether and with which messages the loop enters a proposed step. */
+type PreStepDecision =
+  | { kind: 'reject' }
+  | { kind: 'enter'; messages: UserMessage[] }
 ```
 
 `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal.
@@ -397,12 +232,7 @@ type PromptDecision =
 type RequestErrorAction = { kind: 'retry' } | undefined
 ```
 
-```ts type-equiv
-/** Model-request failure with an optional machine-routable provider code. */
-type RequestError = Error & { code?: string }
-```
-
-`agent/step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
+`agent/pre-step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
 
 `agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
 
@@ -411,12 +241,71 @@ type RequestError = Error & { code?: string }
 type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 ```
 
+## Sessions
+
+A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants additionally carry `sourceEventSeqs` provenance and a `surfaceOp`.
+
+The `SessionEvent` envelope's exact conditional shape, the twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+
 ## `ToolDefinition`
 
 The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional final-content and UI callbacks. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through.
 
 Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.
 
+## Repo-wide type patterns
+
+Two patterns recur across every subsystem and are documented once, here.
+
+### The `…Map → derived-union` pattern
+
+Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
+
+```ts ignore-check
+// The pattern, schematically:
+interface ThingMap {
+  'a': { kind: 'a'; /* … */ }
+  'b': { kind: 'b'; /* … */ }
+}
+type ThingKind = keyof ThingMap          // 'a' | 'b'
+type Thing = ThingMap[keyof ThingMap]    // the discriminated union
+
+// A plugin extends it without touching the source package:
+declare module '@deepseek-ai/dsh-llm' {
+  interface ThingMap {
+    'c': { kind: 'c'; /* … */ }
+  }
+}
+```
+
+Six canonical maps use this pattern; a plugin author extends these:
+
+| Map | Package | Derives | Catalog |
+|---|---|---|---|
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
+| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
+| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
+
+Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
+
+### Branded IDs
+
+IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
+
+The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
+
+Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
+
+```ts type-equiv
+/** A string carrying a compile-time-only brand `B`. */
+type Branded<B extends string> = string & { readonly [BRAND]: B }
+```
+
+The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
+
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -462,7 +351,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -634,35 +523,12 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
 ### `agent/*` events
 
-<a id="agentcancel-requested--emit"></a>
-
-#### `agent/cancel-requested` — emit
-
-Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
-
-```ts cordis-catalog
-/**
- * Effective broad cancellation was requested, before queued/outbox work
- * is cleared or the active turn is aborted. This observe-only notification
- * cannot veto cancellation; listener failures are contained.
- * @param agent - the agent whose current work is being cancelled.
- * @param cause - the explicit typed cancellation cause.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
-
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -676,11 +542,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param agent - the newly registered agent with its live session and completed setup.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, agent: Agent): void
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -698,11 +564,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param agent - the exact agent removed from the registry.
+ * @param payload.agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -713,138 +579,111 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here (plus the
- * logger) even when the error has no in-turn position for a durable record.
- * @param agent - the agent whose turn errored.
- * @param turn - the turn in which the failure surfaced.
- * @param step - the step at which the failure surfaced.
- * @param error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdequeue--emit"></a>
+<a id="agentinboxclaimed--emit"></a>
 
-#### `agent/inbox/dequeue` — emit
+#### `agent/inbox/claimed` — emit
 
-The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
 
 ```ts cordis-catalog
 /**
- * The driver claimed one item out of the inbox: a queued item at a turn
- * boundary, or steering drained between steps. Fires after the item leaves
- * its FIFO and before it becomes a durable message.
- * @param agent - the agent whose inbox item was claimed.
- * @param item - the exact claimed occurrence.
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscard--emit"></a>
+<a id="agentinboxdiscarded--emit"></a>
 
-#### `agent/inbox/discard` — emit
+#### `agent/inbox/discarded` — emit
 
-Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
+One message was discarded from the live inbox.
 
 ```ts cordis-catalog
 /**
- * Pending inbox items were dropped without delivering them, so every
- * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
- * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
- * emits this after `agent/cancel-requested` when applicable and before
- * aborting the active work. Fires once per drop with every dropped item.
- * @param agent - the agent whose inbox items were dropped.
- * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxenqueue--emit"></a>
+<a id="agentinboxinserted--emit"></a>
 
-#### `agent/inbox/enqueue` — emit
+#### `agent/inbox/inserted` — emit
 
-An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
+One message entered the live inbox.
 
 ```ts cordis-catalog
 /**
- * An item entered the queued or steering inbox. `placement` is the
- * acceptance-time routing result; listeners must not reconstruct it from
- * later agent or session state.
- * @param agent - the owning agent.
- * @param item - accepted occurrence, message, and resolved placement.
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxupdate--emit"></a>
+<a id="agentpre-step--waterfall"></a>
 
-#### `agent/inbox/update` — emit
+#### `agent/pre-step` — waterfall
 
-A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
 
 ```ts cordis-catalog
 /**
- * A still-pending queued item changed content. The item id, placement, and
- * position remain stable while the event carries the replacement message.
- * @param agent - the owning agent.
- * @param item - the complete post-update occurrence.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
-
-<a id="agentprompt-submit--waterfall"></a>
-
-#### `agent/prompt-submit` — waterfall
-
-Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
-
-```ts cordis-catalog
-/**
- * Allow, rewrite, or block one claimed prompt before it becomes a user
- * message or opens a turn. Call `next()` for the unchanged default. The
- * signal controls only this admission attempt; listeners may cooperate with
- * it but must not retain it for a later attempt or turn.
- * @param agent - the agent whose turn claimed the message.
- * @param message - the frozen claimed message, including identity and source.
- * @param signal - the current turn's explicit abort signal.
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -863,14 +702,14 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param agent - the agent making the model call.
- * @param turn - the open turn number.
- * @param step - the step whose request this is.
- * @param signal - the current turn's explicit abort signal.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
@@ -881,28 +720,25 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle a model-request failure after its failed step has closed but
- * before the failed turn closes. A listener returns `{ kind: 'retry' }`
- * without calling `next()` when it owns the error, or calls `next()` to
- * delegate. The default `undefined` leaves the failure terminal.
- * @param agent - the agent whose request failed.
- * @param turn - the open turn number.
- * @param step - the failed step number.
- * @param error - the original model-request failure.
- * @param failure - serializable facts normalized at the final adapter boundary.
- * @param priorFailures - immutable failures that already authorized another
- * retry turn in this consecutive sequence.
- * @param retryPolicy - immutable policy of the adapter registration that served
- * the failed request, or `undefined` if no final adapter served it.
- * @param signal - the turn abort signal.
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -921,12 +757,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param agent - the agent whose session lifecycle began.
- * @param source - why the session started (fresh startup, resume, …).
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -937,18 +773,19 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
- * `running` synchronously; drive lifecycle from this event.
- * @param agent - the agent whose status flipped.
- * @param status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -959,7 +796,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
 
 ```ts cordis-catalog
 /**
@@ -969,14 +806,17 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step.
- * @param agent - the agent whose turn is at its stop boundary.
- * @param turn - the turn about to close.
- * @param signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -999,12 +839,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param sessionId - exact shared agent/session identity that failed startup.
- * @param error - persistence, setup, or publication failure.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 276dc4f99f..6878300dc2 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,11 +2,11 @@
 
 [English](core.md) | 中文
 
-**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有主干的共享词汇——`Agent` 句柄及其投递与拦截契约，以及全仓通用的类型模式——并指引到该组的专属页面；目录索引见[子系统 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截契约——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
 
 ## 主干逐包速览
 
-一个轮次按同一条循环流经六个包：[`agent-loop`](../../packages/core/agent-loop) 中的 driver 认领一条排队的 prompt，在[会话日志](session.md)（`ctx.sessions`）上开启轮次，通过 [system-prompt](system-prompt.md)（`ctx.systemPrompt`）组装请求前缀并从日志派生历史，经 [LLM seam](llm-streaming.md) 流式获取模型响应，经[工具注册表](tools.md)（`ctx.tools`）分发工具调用，并把每个模型可见的事实追加回日志，供下一步派生。
+一个轮次按同一条循环流经六个包：[`agent-loop`](../../packages/core/agent-loop) 中的 driver 认领一条排队的 prompt，在[会话日志](session.md)（`ctx.sessions`）上开启轮次，通过 [system-prompt](system-prompt.md)（`ctx.systemPrompt`）组装请求前缀并从日志派生历史，经 [LLM seam](llm-streaming.md) 流式获取模型响应，经[工具注册表](tools.md)（`ctx.tools`）分发工具调用，并把每个模型可见的事实追加回日志，供下一步派生。循环搬运的对话词汇——`Message`、`ContentBlock`、`StreamChunk`、模型请求——由 [`packages/llm`](../../packages/llm/README.md) 声明，记录在 [llm-streaming.md](llm-streaming.md)。
 
 | 包 | 负责内容 | 页面 |
 |---|---|---|
@@ -19,13 +19,251 @@
 
 `scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
 
-<a id="what-counts-as-core"></a>
+<a id="creation-and-ownership"></a>
 
-## 本页拥有什么
+## 创建与所有权
 
-循环搬运的对话词汇——`Message`、`ContentBlock`、`StreamChunk`、模型请求——由 [`packages/llm`](../../packages/llm/README.md) 声明，记录在 [llm-streaming.md](llm-streaming.md)；会话事件、提示词组装与工具词汇在上表该组的专属页面。留在本页的是所有部分共享的词汇：`Agent` 句柄及其投递、取消与拦截契约（由 `packages/core/agent` 声明）、`SessionEvent` 信封，以及每个子系统都遵循的两个类型模式。范围界定规则记录在[子系统目录 Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md)：你编写、持有或接收的类型记录在其声明子系统所在之处；为它提供类型推导、渲染或持久化的机制留在该机制自己的页面。
+消费方通过 `ctx.agents` 创建 agent——`create()` 在一个调用方提供的 `SessionId` 下构建全新会话与 agent，`resume()` 先加载持久会话——或者通过循环的声明式配置条目创建。编程式创建返回归属所有者的句柄：
 
-## `…Map → derived-union` 模式
+源码：[`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
+
+```ts type-equiv
+/**
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
+ * only the holder can tear this agent down. The registered factory provider is
+ * also a structural owner because the scoped agent depends on that provider's
+ * service surface; provider unload stops and drains every live handle it made.
+ * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
+ * its session from the store, and finally unwinds its scoped world.
+ *
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
+ * exposed only to the consumer owner that created it; the structural provider
+ * reaches the same teardown internally. Config-created agents (the loop's own
+ * startup) are owned by the loop fiber and never need a handle.
+ */
+interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
+```
+
+`CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
+
+`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚契约见下方[生成区块](#ctxagents--agentregistry)。
+
+<a id="the-agent-handle"></a>
+
+## Agent 句柄
+
+`Agent` 是每个插件（UI、钩子、orchestrator）面向编程的 surface；`ctx.agents.get(id)` 返回它，[发起者作用域](#initiating-agent)携带它。具体实现为 dsh-agent-loop 包内部细节；循环外没有任何组件依赖它。统一的 `send` 方法直接暴露 target 与 wakeup 路由；`followup`、`steer` 与 `inject` 是固定预设的别名方法。
+
+源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
+
+```ts type-equiv
+/** Public live-agent handle. */
+interface Agent {
+  /** The single identity shared with {@link session}. */
+  readonly id: SessionId
+  /** The provider route and model this agent's requests use. */
+  readonly options: AgentOptions
+  /** The live session this agent drives; its log is the durable source of truth. */
+  readonly session: Session
+  /** The agent-owned projection of durable pending work. */
+  readonly inbox: Inbox
+  /** The current lifecycle state, mirrored on every `agent/status` transition. */
+  readonly status: AgentStatus
+  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
+  readonly ctx: Context
+
+  /**
+   * Clear queued and steering work — unless `keepInbox` — and abort the active
+   * turn or between-turn task. The first cause wins for that activity. With no
+   * active activity, cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the active operation signal.
+   * @param options - cancellation options; `keepInbox` preserves pending work.
+   */
+  cancel(cause: AgentCancelCause, options?: CancelOptions): void
+
+  /**
+   * Resolve after the current whole-agent activity reaches quiescence. This
+   * follows replacement work started before the observed driver retires,
+   * but does not identify the settlement of any particular message.
+   * @returns fulfillment after no active driver or maintenance task remains.
+   */
+  whenIdle(): Promise<void>
+
+  /**
+   * Run one non-turn maintenance task from the true idle phase. The task starts
+   * synchronously after claiming that phase; later waking input remains in the
+   * inbox until the task settles, while public status stays `idle`.
+   * `whenIdle()` follows both the task and any waking work released behind it.
+   * @param task - operation whose fulfillment or rejection is preserved, with a signal aborted by {@link cancel}.
+   * @throws synchronously when turn-driving or another maintenance task already owns the agent.
+   * @returns the task promise.
+   */
+  runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>
+
+  /**
+   * Route identified input to an inbox boundary and optionally wake the driver.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
+   * @param message - identified content and its producer provenance.
+   * @param target - the preferred next-turn or next-step inbox boundary.
+   * @param wakeup - whether delivery may wake the driver.
+   */
+  send(message: UserMessage, target: InboxTarget, wakeup: boolean): void
+
+  /**
+   * Queue an ordinary follow-up turn and wake the driver. The item becomes the
+   * sole ordinary message of its own turn.
+   * @param message - identified prompt content and its producer provenance.
+   */
+  followup(message: UserMessage): void
+
+  /**
+   * Submit steering for the nearest step. An idle driver starts a turn;
+   * a running driver consumes it at its next step boundary.
+   * A rejected step leaves steering parked in the inbox until the next
+   * wake; cancellation or disposal may discard pending steering.
+   * @param message - identified steering content and its producer provenance.
+   */
+  steer(message: UserMessage): void
+
+  /**
+   * Queue model-facing context for the next pre-step without waking the
+   * driver. A running driver claims it at the nearest later step boundary;
+   * idle drivers leave it pending until follow-up or steering
+   * wakes them. It may miss a request whose pre-step already claimed its
+   * batch. Cancellation or disposal may discard pending context.
+   * @param message - identified injected context and its producer provenance.
+   */
+  inject(message: UserMessage): void
+}
+```
+
+```ts type-equiv
+/**
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
+ * `idle` means no driver is active; `running` begins when waking input starts
+ * cancellable pre-step processing and lasts while the driver drains,
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
+ * it is not a third observable status.
+ */
+type AgentStatus = 'idle' | 'running'
+```
+
+`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`followup()` 不返回句柄：其 `MessageId` 标识的是持久的 inbox 插入、认领与丢弃事实，而非之后的助手输出或轮次结束。`whenIdle()` 观察的是整个 agent，因此只有当调用方明确拥有从回执到空闲的这段区间时，才能把它称为一次 run（[决策](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
+
+```ts type-equiv
+/** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
+interface AgentOptions {
+  /** Provider route (must have a registered adapter at call time). */
+  provider?: string
+  /** Model id interpreted by the selected provider adapter. */
+  model?: string
+  /** Maximum output tokens for each conversation-model request. */
+  maxTokens?: number
+}
+```
+
+在 `agent/request` 之后，分发要求 `provider` 与 `model` 都存在。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。agent 作用域的 `deployment:persona` 提示词段落可以遮蔽全局默认 persona。
+
+inbox 即投递词汇——agent 以持久投影形式拥有的两条有序待处理消息列表：
+
+```ts type-equiv
+/** One of the two ordered pending-message lists owned by an agent. */
+type InboxTarget = 'next-turn' | 'next-step'
+```
+
+每个待处理入队项就是其 `UserMessage`；`MessageId` 是唯一标识。`Inbox.append`、`prepend`、`replace`、`remove`、`clear`、`splice` 与 `claim` 会记录规范化的持久 `agent/inbox/spliced` 变更，并拒绝重复的待处理 id。`replace(messageId, newMessage)` 与 `remove(messageId)` 通过 `MessageId` 跨两份列表定位待处理消息；替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。普通删除和 `clear()` 都表示取消。`claim(target)` 通过无 outcome 的纯删除 splice 移除拟进入步骤的批次——全部 `next-step` 输入，外加轮次边界上的一条 `next-turn` 消息——且不发出 discarded 通知；循环另行逐条发出 claimed 通知。UI 投影等整体队列消费方通过持久 splice 重建 `nextTurn` 与 `nextStep`，而跟踪单条消息的消费方使用精确的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知。
+
+取消：
+
+```ts type-equiv
+/** Options for {@link Agent.cancel}. */
+interface CancelOptions {
+  /**
+   * Preserve queued and steering inbox items instead of discarding them. The
+   * active turn is still aborted, but un-started and pending work survives for a
+   * later turn and no canceled inbox splice is logged.
+   */
+  keepInbox?: boolean | undefined
+}
+```
+
+```ts type-equiv
+/** Why an active agent driver was cancelled. */
+type AgentCancelCause =
+  | { readonly kind: 'user' }
+  | { readonly kind: 'parent' }
+  | { readonly kind: 'hook'; readonly reason: string }
+  | { readonly kind: 'disposed' }
+```
+
+cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
+
+[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
+
+<a id="initiating-agent"></a>
+
+## 发起 Agent
+
+`ctx.agents` 携带的进程本地 initiator 就是上面的确切 `Agent`，不是单独的 frame 或复制的标识。环境中存在该值既不能证明存活，也不代表授权；其生命周期与边界规则由 [initiator 作用域决策](../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)规定。
+
+## 拦截决策
+
+pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。
+
+源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
+
+`agent/pre-step` 接收一个 payload，携带独占的已领取批次（`messages`）、拟进入步骤的坐标（`turn`、`step`）与当前轮次的取消 `signal`。首次提案在已打开的轮次内、任何步骤开始前运行；工具 continuation 可以在步骤之间提交空的已领取批次：
+
+它返回 `PreStepDecision`。reject 不会打开步骤。enter 提供在 `step/start` 后追加的完整消息批次；最终决策省略的已领取消息保持已删除，而领取后插入的输入仍留待后续处理：
+
+```ts type-equiv
+/** Whether and with which messages the loop enters a proposed step. */
+type PreStepDecision =
+  | { kind: 'reject' }
+  | { kind: 'enter'; messages: UserMessage[] }
+```
+
+`agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。
+
+```ts type-equiv
+/** Action returned by a listener that owns model-request recovery. */
+type RequestErrorAction = { kind: 'retry' } | undefined
+```
+
+`agent/pre-step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
+
+`agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）：
+
+```ts type-equiv
+/** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
+type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
+```
+
+## 会话
+
+`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。每个条目携带单调的 `seq`、`time` 与按 `type` 判别的 `data` payload；surface 变体还额外携带 `sourceEventSeqs` provenance 与 `surfaceOp`。
+
+`SessionEvent` 信封的确切条件形状、十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
+
+## `ToolDefinition`
+
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+
+其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
+
+## 全仓通用类型模式
+
+两个模式在每个子系统中反复出现，只在此处记录一次。
+
+### `…Map → derived-union` 模式
 
 harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包（package）。
 
@@ -61,7 +299,7 @@ declare module '@deepseek-ai/dsh-llm' {
 
 <a id="branded-ids"></a>
 
-## 品牌化 ID
+### 品牌化 ID
 
 跨越包边界的 ID 都经过**品牌化**——结构上是字符串，但在类型层面不可互换（不能把 `SessionId` 传给需要 `CallId` 的位置）。每种类型通过各自的工厂构造；比较、日志记录和 JSON 行为与普通字符串相同。
 
@@ -76,351 +314,6 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 两个核心 ID 是 `CallId`（关联工具调用及其结果；dsh-llm）和 `SessionId`（活跃 agent 与持久会话共享的标识；dsh-session）。能力包也会品牌化各自的 id，例如 [tasks.md](tasks.md) 中的 `TaskId`。
 
-## 会话
-
-`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。事件词汇从 `SessionEventMap` 派生：
-
-源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
-
-```ts type-equiv
-/**
- * One immutable entry in the session log.
- *
- * A proper discriminated union over `type` (not independent `type`/`data`
- * unions), so `switch (event.type)` narrows `event.data` without casts.
- *
- * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `steering/message`).
- * Non-surface events (boundary markers, chunks, usage, errors) never carry
- * surface metadata — the compiler enforces this at `Session.append()`
- * call sites.
- */
-type SessionEvent<T extends SessionEventType = SessionEventType> = {
-  [K in SessionEventType]: {
-    type: K
-    /** Monotonic sequence number within the session. */
-    seq: number
-    /** Unix epoch milliseconds. */
-    time: number
-    data: SessionEventMap[K]
-  } & (K extends SurfaceEventType ? {
-    /**
-     * Seq numbers of events that are provenance sources of this event
-     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node). An
-     * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
-     */
-    sourceEventSeqs?: number[]
-    /** How this event entered the surface; absent for non-surface events. */
-    surfaceOp?: SurfaceOp
-  } : object)
-}[T]
-```
-
-十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
-
-<a id="the-agent-handle"></a>
-
-## Agent 句柄
-
-`Agent` 是每个插件（UI、钩子、orchestrator）面向编程的 surface。具体实现为 dsh-agent-loop 包内部细节；循环外没有任何组件依赖它。
-
-源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
-
-```ts type-equiv
-/**
- * Which inbox queue a {@link Agent.send} item joins:
- * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
- * - `next-step` — during prompt admission or an open turn, the item stages for
- *   the next safe step boundary; otherwise it is promoted per its `wakeup`
- *   flag.
- */
-type SendTarget = 'next-turn' | 'next-step'
-```
-
-```ts type-equiv
-/** Resolved inbox placement reported when an accepted message is enqueued. */
-type InboxPlacement = 'queued' | 'steering'
-```
-
-`InboxItemId` 是为每次获准进入 FIFO 的项铸造的进程本地品牌字符串。它有意区别于 `MessageId`：同一条不可变消息发送两次，会创建两个可独立寻址的待处理项。
-
-```ts type-equiv
-/** One independently addressable accepted occurrence in an agent inbox. */
-interface InboxItem {
-  /** Agent-loop-minted occurrence identity. */
-  readonly id: InboxItemId
-  /** Identified message delivered by the caller. */
-  readonly message: UserMessage
-  /** Acceptance-time FIFO classification. */
-  readonly placement: InboxPlacement
-}
-```
-
-```ts type-equiv
-/** A user-requested mutation of one still-pending queued occurrence. */
-type InboxAction =
-  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
-  | { readonly kind: 'remove' }
-  | { readonly kind: 'steer' }
-```
-
-```ts type-equiv
-/** Result of applying an inbox action at the synchronous ownership boundary. */
-type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
-```
-
-```ts type-equiv
-/**
- * Options for the unified {@link Agent.send} primitive over the
- * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
- * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
- * {@link Agent.inject} (`next-step`/no-wakeup).
- *
- * The object is complete so routing policy is explicit.
- */
-interface SendOptions {
-  /** Queue the item joins. */
-  target: SendTarget
-  /**
-   * Whether this item makes the model run: wake a parked driver (`next-turn`)
-   * or force a continuation step (`next-step` while running). A `false`
-   * `next-turn` item queues without waking; a `false`
-   * `next-step` item attaches durable context without forcing another step
-   * (the injection preset).
-   */
-  wakeup: boolean
-}
-```
-
-固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。编辑替换内容或严格 steering（中途引导）转移不可变消息时，其 `MessageId` 都保持稳定。原 queued 单次入队项会结束，严格 steering 则接受一个具有不同 `InboxItemId` 的新 steering 单次入队项。注入绕过两个 FIFO，从不出现在 inbox 生命周期事件中。
-
-```ts type-equiv
-/** Options for {@link Agent.cancel}. */
-interface CancelOptions {
-  /**
-   * Preserve queued and steering inbox items instead of discarding them. The
-   * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no `agent/inbox/discard` fires.
-   */
-  keepInbox?: boolean
-}
-```
-
-`SteeringReceipt.outcome` 始终会解析。`admitted` 标识其不可变请求历史包含该确切消息的轮次与步骤；`rejected` 表示生命周期或终止策略先丢弃了该消息。同步输入校验仍会从 `steer()` 抛出异常。
-
-```ts type-equiv
-/** Stable runtime cause accepted by {@link Agent.cancel}. */
-type AgentCancelCause =
-  | { readonly kind: 'user' }
-  | { readonly kind: 'parent' }
-```
-
-`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器拥有 `followup`/`steer`/`inject` 别名方法，并将它们经由 `send` 的（`target` × `wakeup`）矩阵路由。
-
-```ts type-equiv
-/**
- * Public live-agent handle with aliases over the unified delivery primitive.
- * @typert object
- */
-interface Agent {
-  /** The single identity shared with {@link session}. */
-  readonly id: SessionId
-  /** The provider route and model this agent's requests use. */
-  readonly options: AgentOptions
-  /** The live session this agent drives; its log is the durable source of truth. */
-  readonly session: Session
-  /** The current lifecycle state, mirrored on every `agent/status` transition. */
-  readonly status: AgentStatus
-  /**
-   * Whether a `next-step` send currently stages for prompt admission or the
-   * open turn. Unlike {@link status}, this excludes admission exit and turn
-   * settlement, when a waking `next-step` send becomes a queued follow-up.
-   */
-  readonly acceptsNextStep: boolean
-  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
-  readonly ctx: Context
-
-  /**
-   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
-   * It routes the caller's typed content and source as follows:
-   *
-   * - `next-turn` queues an item that becomes the sole ordinary message of its
-   *   own FIFO-ordered turn; `wakeup:true` wakes a
-   *   parked driver, while `wakeup:false` queues without waking.
-   * - `next-step` with `wakeup:true` stages steering during prompt admission
-   *   or an open turn; outside that window it falls back to a woken
-   *   `next-turn`.
-   * - `next-step` with `wakeup:false` injects durable model-facing context
-   *   without running the model: admission or an open turn stages it for the
-   *   next safe log position, while an injection outside that window appends
-   *   immediately without opening a turn. If admission closes without a turn,
-   *   a context-only boundary appends immediately; context staged beside
-   *   steering remains pending with it.
-   * The agent publishes or queues the identified frozen message as-is.
-   * @param message - identified model-facing content and its producer provenance.
-   * @param options - target queue and wakeup decision.
-   */
-  send(message: UserMessage, options: SendOptions): void
-
-  /**
-   * Reserve admission of the next ordinary turn while this agent is idle, so an
-   * operation can mutate durable history before any queued prompt derives a
-   * request from it. Already-accepted waking work has right of way, including a
-   * send whose wake is still a pending microtask. Later sends keep their
-   * ordinary placement, FIFO order, and `wakeup` facts, and
-   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
-   * a queued follow-up rather than steering; cancellation and disposal may
-   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
-   * a live reservation as activity, while lifecycle teardown does not await it.
-   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
-   */
-  reserveTurnAdmission(): (() => void) | undefined
-
-  /**
-   * Mutate one still-pending queued occurrence synchronously. Editing preserves
-   * the message identity and queue position; removal publishes its terminal
-   * discard. Steer strictly transfers the message into the current next-step
-   * window, or returns `steer-unavailable` without changing the queued
-   * occurrence. Steering occurrences and driver-claimed items return
-   * `not-found`.
-   * @param id - independently addressable queued occurrence.
-   * @param action - edit, remove, or strict steer operation.
-   * @returns the applied outcome or the reason no mutation occurred.
-   */
-  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
-
-  /**
-   * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn. An effective call first emits `agent/cancel-requested` with the
-   * resolved typed cause. The first cause wins for the active turn, and
-   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
-   * cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the current turn signal.
-   * @param options - cancellation options; `keepInbox` preserves pending work.
-   */
-  cancel(cause: AgentCancelCause, options?: CancelOptions): void
-
-  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
-  whenIdle(): Promise<void>
-
-  /**
-   * Run one non-turn maintenance task from the true idle phase. The task starts
-   * synchronously after claiming that phase; later waking input remains in the
-   * inbox until the task settles, while public status stays `idle`.
-   * `whenIdle()` follows both the task and any waking work released behind it.
-   * @param task - operation whose fulfillment or rejection is preserved, with a signal aborted by {@link cancel}.
-   * @throws synchronously when turn-driving or another maintenance task already owns the agent.
-   * @returns the task promise.
-   */
-  runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>
-
-  /**
-   * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next
-   * turn and runs when the aborted activity converges to idle; a `disposed`
-   * cancel leaves it parked. A wake submitted while already idle always opens
-   * its turn boundary, even when its message is cleared before the driver
-   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
-   * @param target - the preferred next-turn or next-step inbox boundary.
-   * @param wakeup - whether delivery may wake the driver.
-   */
-  send(message: UserMessage, target: InboxTarget, wakeup: boolean): void
-
-  /**
-   * Queue an ordinary follow-up turn and wake the driver. The item becomes the
-   * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
-   */
-  followup(message: UserMessage): void
-
-  /**
-   * Submit steering with a message-owned admission receipt — the
-   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
-   * open turn, the message waits in the steering FIFO until a committed step
-   * snapshots it; outside that window it enters the ordinary queued FIFO. The
-   * receipt resolves `admitted` only after the message joins that step's
-   * immutable request history, or `rejected` when terminal policy,
-   * cancellation, or disposal discards it first. A non-terminal turn close may
-   * leave it staged for a later admitted prompt without settling the receipt.
-   * @param message - identified steering content and its producer provenance.
-   * @returns the receipt for this exact message's eventual admission outcome.
-   */
-  steer(message: UserMessage): SteeringReceipt
-
-  /**
-   * Append model-facing context without running the model — the
-   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
-   * stages it at the next safe log position; outside that window it appends
-   * immediately without opening a turn. If admission closes without a turn,
-   * a context-only boundary appends immediately; context staged beside
-   * steering remains pending with it.
-   * @param message - identified injected context and its producer provenance.
-   */
-  inject(message: UserMessage): void
-}
-```
-
-`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。活动的轮次接纳预留与完全停稳相关，但不会改变 `status`，也不会把之后的队列项变成 steering；它的唯一权限是将驱动器的下一次认领延迟到释放时。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
-
-cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。只有 loop 会在结算时从自己机器私有的 signal 上读回 cause（`user`、`parent` 或仅用于生命周期的 `disposed`）——不存在公开的读取器，signal 也不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
-
-[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
-
-## 发起 Agent
-
-`ctx.agents` 携带的进程本地 initiator 就是上面的确切 `Agent`，不是单独的 frame 或复制的标识。环境中存在该值既不能证明存活，也不代表授权；其生命周期与边界规则由 [initiator 作用域决策](../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)规定。
-
-## 拦截决策
-
-提示词决策与工具后决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的标识与 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。
-
-源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
-
-`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 可以改写已领取的提示词或附加 `additionalContexts`；block 拒绝准入且不产生任何轮次事件：
-
-```ts type-equiv
-/**
- * Prompt interception result. `allow.content` replaces the prompt, while
- * `additionalContexts` appends model-facing context before the turn starts.
- * An `allow` returned by a listener is authoritative: a listener wrapping
- * `next()` preserves both fields unless it intentionally replaces them.
- */
-type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
-  | { kind: 'block'; reason: string }
-```
-
-`agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。
-
-```ts type-equiv
-/** Action returned by a listener that owns model-request recovery. */
-type RequestErrorAction = { kind: 'retry' } | undefined
-```
-
-```ts type-equiv
-/** Model-request failure with an optional machine-routable provider code. */
-type RequestError = Error & { code?: string }
-```
-
-`agent/step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
-
-`agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）：
-
-```ts type-equiv
-/** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
-type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
-```
-
-## `ToolDefinition`
-
-唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
-
-其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
-
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -466,7 +359,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -638,35 +531,12 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
 ### `agent/*` events
 
-<a id="agentcancel-requested--emit"></a>
-
-#### `agent/cancel-requested` — emit
-
-Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
-
-```ts cordis-catalog
-/**
- * Effective broad cancellation was requested, before queued/outbox work
- * is cleared or the active turn is aborted. This observe-only notification
- * cannot veto cancellation; listener failures are contained.
- * @param agent - the agent whose current work is being cancelled.
- * @param cause - the explicit typed cancellation cause.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
-
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -680,11 +550,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param agent - the newly registered agent with its live session and completed setup.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, agent: Agent): void
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -702,11 +572,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param agent - the exact agent removed from the registry.
+ * @param payload.agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -717,138 +587,111 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here (plus the
- * logger) even when the error has no in-turn position for a durable record.
- * @param agent - the agent whose turn errored.
- * @param turn - the turn in which the failure surfaced.
- * @param step - the step at which the failure surfaced.
- * @param error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdequeue--emit"></a>
+<a id="agentinboxclaimed--emit"></a>
 
-#### `agent/inbox/dequeue` — emit
+#### `agent/inbox/claimed` — emit
 
-The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
 
 ```ts cordis-catalog
 /**
- * The driver claimed one item out of the inbox: a queued item at a turn
- * boundary, or steering drained between steps. Fires after the item leaves
- * its FIFO and before it becomes a durable message.
- * @param agent - the agent whose inbox item was claimed.
- * @param item - the exact claimed occurrence.
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscard--emit"></a>
+<a id="agentinboxdiscarded--emit"></a>
 
-#### `agent/inbox/discard` — emit
+#### `agent/inbox/discarded` — emit
 
-Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
+One message was discarded from the live inbox.
 
 ```ts cordis-catalog
 /**
- * Pending inbox items were dropped without delivering them, so every
- * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
- * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
- * emits this after `agent/cancel-requested` when applicable and before
- * aborting the active work. Fires once per drop with every dropped item.
- * @param agent - the agent whose inbox items were dropped.
- * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxenqueue--emit"></a>
+<a id="agentinboxinserted--emit"></a>
 
-#### `agent/inbox/enqueue` — emit
+#### `agent/inbox/inserted` — emit
 
-An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
+One message entered the live inbox.
 
 ```ts cordis-catalog
 /**
- * An item entered the queued or steering inbox. `placement` is the
- * acceptance-time routing result; listeners must not reconstruct it from
- * later agent or session state.
- * @param agent - the owning agent.
- * @param item - accepted occurrence, message, and resolved placement.
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxupdate--emit"></a>
+<a id="agentpre-step--waterfall"></a>
 
-#### `agent/inbox/update` — emit
+#### `agent/pre-step` — waterfall
 
-A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
 
 ```ts cordis-catalog
 /**
- * A still-pending queued item changed content. The item id, placement, and
- * position remain stable while the event carries the replacement message.
- * @param agent - the owning agent.
- * @param item - the complete post-update occurrence.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
-
-<a id="agentprompt-submit--waterfall"></a>
-
-#### `agent/prompt-submit` — waterfall
-
-Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
-
-```ts cordis-catalog
-/**
- * Allow, rewrite, or block one claimed prompt before it becomes a user
- * message or opens a turn. Call `next()` for the unchanged default. The
- * signal controls only this admission attempt; listeners may cooperate with
- * it but must not retain it for a later attempt or turn.
- * @param agent - the agent whose turn claimed the message.
- * @param message - the frozen claimed message, including identity and source.
- * @param signal - the current turn's explicit abort signal.
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -867,14 +710,14 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param agent - the agent making the model call.
- * @param turn - the open turn number.
- * @param step - the step whose request this is.
- * @param signal - the current turn's explicit abort signal.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
@@ -885,28 +728,25 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle a model-request failure after its failed step has closed but
- * before the failed turn closes. A listener returns `{ kind: 'retry' }`
- * without calling `next()` when it owns the error, or calls `next()` to
- * delegate. The default `undefined` leaves the failure terminal.
- * @param agent - the agent whose request failed.
- * @param turn - the open turn number.
- * @param step - the failed step number.
- * @param error - the original model-request failure.
- * @param failure - serializable facts normalized at the final adapter boundary.
- * @param priorFailures - immutable failures that already authorized another
- * retry turn in this consecutive sequence.
- * @param retryPolicy - immutable policy of the adapter registration that served
- * the failed request, or `undefined` if no final adapter served it.
- * @param signal - the turn abort signal.
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -925,12 +765,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param agent - the agent whose session lifecycle began.
- * @param source - why the session started (fresh startup, resume, …).
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -941,18 +781,19 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
- * `running` synchronously; drive lifecycle from this event.
- * @param agent - the agent whose status flipped.
- * @param status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -963,7 +804,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
 
 ```ts cordis-catalog
 /**
@@ -973,14 +814,17 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step.
- * @param agent - the agent whose turn is at its stop boundary.
- * @param turn - the turn about to close.
- * @param signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -1003,12 +847,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param sessionId - exact shared agent/session identity that failed startup.
- * @param error - persistence, setup, or publication failure.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 3674a95c44..572039f635 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
 http-server.md: b9795fe98b432b6ef5f7d01a4d3e115c809fe642
-http-server.zh.md: c3ba02dce5c58f491921f1fb31f999f9da808bc5
+http-server.zh.md: b84ea457bcd37eed361fde88fbf680d189aeebfb
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index c3ba02dce5..b84ea457bc 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -2,7 +2,7 @@
 
 [English](http-server.md) | 中文
 
-[dsh-host-webserver](../../packages/host/webserver) 是 GUI 宿主 web 形态的 HTTP 载体：单个提供 `ctx.httpServer` 的 `node:http` 插件，由具名路由注册表加 index.html 转换挂点组成，兜底是静态 dist 回退。它不属于 agent loop（智能体循环）主干，也不是能力 seam：它不了解任何 harness 概念，每个功能表面（`/api` 桥接、插件 bundle、HMR（热模块替换）事件流）都是由其他插件注册的一条路由（[分层说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)）。仅限 web（浏览器）形态：Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，不经过本服务器。
+[dsh-host-webserver](../../packages/host/webserver) 是 GUI 宿主 web 形态的 HTTP 载体：单个提供 `ctx.httpServer` 的 `node:http` 插件，由具名路由注册表、index.html 转换挂点与单一可认领的回退席位组成。它不属于 agent loop（智能体循环）主干，也不是能力 seam：它不了解任何 harness 概念，每个功能表面（`/api` 桥接、插件 bundle、HMR（热模块替换）事件流）都是由其他插件注册的一条路由（[分层说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)）。仅限 web（浏览器）形态：Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，不经过本服务器。
 
 源码：[`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index f6ce932ad9..f807656000 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: b3f850f4d07ad9e36d0e0db71dd9e0498e468767
-llm-streaming.zh.md: bb31c14b9bd0453399d83968b1062f67819caca3
+llm-streaming.md: c65416f449d1783f398cdd81b0d6987de83a6141
+llm-streaming.zh.md: ce79ecca53edf7213853df118489817451baa7b0
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index b3f850f4d0..c65416f449 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -72,12 +72,84 @@ Where a message came from is itself a merge-extensible sum type:
  */
 interface MessageSourceMap {
   user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string }
+  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
   model: ModelMessageSource
   tool: ToolMessageSource
 }
 ```
 
+Provenance and shape are two independent axes. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
+
+```ts type-equiv
+/**
+ * What SHAPE of information a producer-supplied context carries, declared by
+ * the producer beside its provenance.
+ *
+ * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
+ * of thing it is*, and the two axes are deliberately independent — several
+ * producers share one form (three snapshot producers today), and one producer
+ * may emit more than one form over a session.
+ *
+ * The vocabulary is SEMANTIC, never visual: a value states that the content is
+ * a file's instructions or a catalog of available items, and a consumer decides
+ * what that looks like. Colors, icons, ordering, and collapse defaults are the
+ * consumer's business and must not enter this union. It grows one value at a
+ * time as producers gain the structured fields their form needs; an absent or
+ * unknown value is the documented default, presented as opaque content.
+ */
+type ContextForm =
+  /** Instructions read out of workspace files the model is expected to follow. */
+  | 'instructions'
+  /** A catalog of items available in this session, republished as it changes. */
+  | 'catalog'
+  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
+  | 'snapshot'
+  /** A one-off account of something that just happened; it supersedes nothing. */
+  | 'notice'
+  /** A message another agent addressed to this one. */
+  | 'relay'
+  /** Material lifted out of another session's log, possibly reduced on the way in. */
+  | 'recall'
+```
+
+```ts type-equiv
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+interface ContextSnapshotSection {
+  /** The contributing subsystem's name. */
+  readonly name: string
+  /** That contribution's model-facing text, exactly as assembled. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source shapes that carry one.
+ *
+ * Discriminated by `form` so a producer cannot declare a shape without the
+ * facts that shape is presented from: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+type ContextFormed =
+  | { readonly form?: never }
+  | { readonly form: 'instructions' }
+  | { readonly form: 'catalog' }
+  | {
+    readonly form: 'snapshot'
+    /** The named contributions this snapshot assembled, in order. */
+    readonly sections: readonly ContextSnapshotSection[]
+  }
+  | {
+    readonly form: 'notice'
+    /** One-line account of what happened, shown without expanding the row. */
+    readonly summary: string
+  }
+  | { readonly form: 'relay' }
+  | { readonly form: 'recall' }
+```
+
 ## `StreamChunk` — the raw protocol
 
 A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it.
@@ -87,8 +159,9 @@ A streaming response interleaves several typed blocks (text, reasoning, multiple
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. Failures either throw or
- * end with `error`/`aborted`, and consumers must handle both paths.
+ * afterward; tool arguments remain raw JSON strings. An adapter implementation
+ * may throw, but `LlmService.stream()` normalizes that failure to a terminal
+ * `error` or `aborted` finish before exposing it to consumers.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -213,8 +286,9 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index; an open block assembles from its
-   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index, except that max-token truncation drops
+   *   tool calls that cannot be executed safely; an open block assembles from
+   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -301,6 +375,15 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 ```
 
@@ -451,6 +534,55 @@ interface ToolSchema {
 
 The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
 
+A provider a surface is still drafting has no route and no catalog, so interrogation is described separately: the request carries the draft the user is editing, and the reply is candidates a surface may adopt rather than a catalog it must serve.
+
+```ts type-equiv
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
+}
+```
+
 ### The request envelope: `LlmCallConfig` and the logged header
 
 The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
@@ -498,6 +630,8 @@ interface LlmCallConfigAdapterDefaults {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
+  /** Immutable retry policy captured with the adapter registration. */
+  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -603,9 +737,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns the disposer that withdraws all of them.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -613,6 +747,29 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () =
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -662,22 +819,20 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Throws
- * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
- * `options.provider`. Replay state is retained only when the same adapter
- * instance owns its historical provider and the target provider. Final
- * adapter selection remains fixed through asynchronous exact-model resolution
- * and dispatch. Selection, dispatch, and iteration failures retain their
- * original Error identity and are tagged in a call-local scope for narrow
- * agent-loop request recovery; middleware and nested-call failures remain
- * untagged for the outer call.
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -702,7 +857,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -726,5 +881,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index bb31c14b9b..ce79ecca53 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -72,12 +72,84 @@ interface Message {
  */
 interface MessageSourceMap {
   user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string }
+  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
   model: ModelMessageSource
   tool: ToolMessageSource
 }
 ```
 
+溯源与形态是相互独立的两根轴。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
+
+```ts type-equiv
+/**
+ * What SHAPE of information a producer-supplied context carries, declared by
+ * the producer beside its provenance.
+ *
+ * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
+ * of thing it is*, and the two axes are deliberately independent — several
+ * producers share one form (three snapshot producers today), and one producer
+ * may emit more than one form over a session.
+ *
+ * The vocabulary is SEMANTIC, never visual: a value states that the content is
+ * a file's instructions or a catalog of available items, and a consumer decides
+ * what that looks like. Colors, icons, ordering, and collapse defaults are the
+ * consumer's business and must not enter this union. It grows one value at a
+ * time as producers gain the structured fields their form needs; an absent or
+ * unknown value is the documented default, presented as opaque content.
+ */
+type ContextForm =
+  /** Instructions read out of workspace files the model is expected to follow. */
+  | 'instructions'
+  /** A catalog of items available in this session, republished as it changes. */
+  | 'catalog'
+  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
+  | 'snapshot'
+  /** A one-off account of something that just happened; it supersedes nothing. */
+  | 'notice'
+  /** A message another agent addressed to this one. */
+  | 'relay'
+  /** Material lifted out of another session's log, possibly reduced on the way in. */
+  | 'recall'
+```
+
+```ts type-equiv
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+interface ContextSnapshotSection {
+  /** The contributing subsystem's name. */
+  readonly name: string
+  /** That contribution's model-facing text, exactly as assembled. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source shapes that carry one.
+ *
+ * Discriminated by `form` so a producer cannot declare a shape without the
+ * facts that shape is presented from: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+type ContextFormed =
+  | { readonly form?: never }
+  | { readonly form: 'instructions' }
+  | { readonly form: 'catalog' }
+  | {
+    readonly form: 'snapshot'
+    /** The named contributions this snapshot assembled, in order. */
+    readonly sections: readonly ContextSnapshotSection[]
+  }
+  | {
+    readonly form: 'notice'
+    /** One-line account of what happened, shown without expanding the row. */
+    readonly summary: string
+  }
+  | { readonly form: 'relay' }
+  | { readonly form: 'recall' }
+```
+
 <a id="streamchunk--the-raw-protocol"></a>
 
 ## `StreamChunk`：原始协议
@@ -89,8 +161,9 @@ interface MessageSourceMap {
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. Failures either throw or
- * end with `error`/`aborted`, and consumers must handle both paths.
+ * afterward; tool arguments remain raw JSON strings. An adapter implementation
+ * may throw, but `LlmService.stream()` normalizes that failure to a terminal
+ * `error` or `aborted` finish before exposing it to consumers.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -221,8 +294,9 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index; an open block assembles from its
-   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index, except that max-token truncation drops
+   *   tool calls that cannot be executed safely; an open block assembles from
+   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -309,6 +383,15 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 ```
 
@@ -459,6 +542,55 @@ interface ToolSchema {
 
 面向模型的 `ToolSchema` 是协议格式；产出它的已注册 `ToolDefinition`（schema + `execute`）在 [tools.md](tools.md) 中。
 
+界面正在起草的提供方既没有路由也没有 catalog，因此询问被单独描述：请求携带用户正在编辑的草稿，回复是界面可以采纳的候选，而不是它必须服务的 catalog。
+
+```ts type-equiv
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
+}
+```
+
 ### 请求信封：`LlmCallConfig` 与记录的 header
 
 循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
@@ -506,6 +638,8 @@ interface LlmCallConfigAdapterDefaults {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
+  /** Immutable retry policy captured with the adapter registration. */
+  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -611,9 +745,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns the disposer that withdraws all of them.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -621,6 +755,29 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () =
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -670,22 +827,20 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Throws
- * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
- * `options.provider`. Replay state is retained only when the same adapter
- * instance owns its historical provider and the target provider. Final
- * adapter selection remains fixed through asynchronous exact-model resolution
- * and dispatch. Selection, dispatch, and iteration failures retain their
- * original Error identity and are tagged in a call-local scope for narrow
- * agent-loop request recovery; middleware and nested-call failures remain
- * untagged for the outer call.
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -710,7 +865,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -734,5 +889,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index 6f6ba3b3c3..3f9c9b533c 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
-permission.md: 60ed88a79d0e51922f4cdffafa8b547669b49f5d
-permission.zh.md: c06714fc6a111f56af680c3dea1764c90f09998d
+permission.md: 6f9a37dbb784ccbaea74056519992e40f9c07c6d
+permission.zh.md: 8eda50fae09a67c41003d7a914fb139c4132a900
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index 60ed88a79d..6f9a37dbb7 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -125,7 +125,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index c06714fc6a..8eda50fae0 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -125,7 +125,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 808abb402a..295e5392ca 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 1edf3c88fbabe55058bbf94ed8f31decf47cb84a
-persistence.zh.md: dbebd9ff819c8d50cfa9748678dac09c86adde6d
+persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
+persistence.zh.md: 6676bf26e6eb0fb8f7dd9a94d17d4d70d1d1b271
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 1edf3c88fb..580ec250eb 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -332,7 +332,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](core.md) · [SessionId](core.md)
+Types: [SessionEvent](session.md) · [SessionId](core.md)
 
 Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index dbebd9ff81..6676bf26e6 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -332,7 +332,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](core.md) · [SessionId](core.md)
+Types: [SessionEvent](session.md) · [SessionId](core.md)
 
 Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 24b1c7b234..fc603d658d 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: 56f9fb43dddc482264aab52ceeb9b9920df148cd
-session-projection.zh.md: 4a2310fed4af6f018af07b5f2b46d3c28aa361a4
+session-projection.md: 64351195028c62f623b32cbeb80c952795c1e9e6
+session-projection.zh.md: cf9036e6db3f82d84ffa3b8aa809c5617409659a
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index 56f9fb43dd..6435119502 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -256,7 +256,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
 restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index 4a2310fed4..cf9036e6db 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -256,7 +256,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
 restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index a7e81056e5..2389cc806c 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 28b3f959b47a24373860c2334f9273286d072c95
-session.zh.md: 5870265f55892231700b65ac6ed69d827a0ab1ec
+session.md: 7735e90807f6fce1b3645096437b3e86189dc8ec
+session.zh.md: 09f34ac19c2f685bf5f8e5b11355b4c642c584d0
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 28b3f959b4..7735e90807 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -804,7 +804,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [Scoped](scope.md) · [SessionEvent](core.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 5870265f55..09f34ac19c 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -808,7 +808,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [Scoped](scope.md) · [SessionEvent](core.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index a58335b9f1..994c04eaa5 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: c132c073459642b133e0d7e662ee98a8c9dfb694
-subagent.zh.md: e46f9aa98389842918ae37dda1477ef1b565e774
+subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
+subagent.zh.md: ddc3a715fbb6589dffc38f0e0c8b23bf35dddf6e
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index c132c07345..3bf3ac7c48 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -133,7 +133,7 @@ persisted Session
 | `waiting` | wake the same Activation |
 | no Activation | cold-resume a new Activation |
 
-`running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the `AgentHandle` and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine.
+`running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine.
 
 The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/enqueue`, `agent/inbox/dequeue`, and `agent/inbox/discard` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
 
@@ -432,7 +432,7 @@ Provider `start()` fulfills with a published run. The service mints a unique `ru
 The spawn and fork backends create an ordinary one-shot agent through `parent.ctx`, pass cancellation into core creation, and dispose through `AgentHandle`; a continuable child is instead created by the continuation manager through its own activation-owner scope. Provider removal blocks new starts without revoking accepted runs. Each child gets a new flat scope rather than inheriting parent registrations. Depth and fork seeding reuse existing agent and session vocabulary:
 
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
-- **Fork seeding** uses `CreateAgentOptions.seed` (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/support/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
+- **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/support/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index e46f9aa983..ddc3a715fb 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -133,7 +133,7 @@ persisted Session
 | `waiting` | 唤醒同一 Activation |
 | 无 Activation | 冷恢复一个新的 Activation |
 
-`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose `AgentHandle` 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
+`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose [`AgentHandle`](core.md#creation-and-ownership) 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
 
 Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/enqueue`、`agent/inbox/dequeue` 与 `agent/inbox/discard` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
 
@@ -434,7 +434,7 @@ interface SubagentProvider {
 spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将取消信号传入核心创建流程，并通过 `AgentHandle` 进行 dispose；而可继续子 agent 则由继续执行管理器通过其自己的 activation-owner 作用域创建。移除提供方会阻止新的 start，但不会撤销已接受的 run。每个子 agent 获得一个新的扁平作用域，而非继承父级注册。深度与 fork 种子注入复用既有的 agent 和会话词汇：
 
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
-- **Fork 种子注入**使用 `CreateAgentOptions.seed`（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
+- **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.md#creation-and-ownership)（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 003e175399..21003bb796 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: b63014d1c2058c8fc7e96817d4bca858a1954482
-tools.zh.md: 2dc5802efce25a732a60c660191cd584ede623bb
+tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
+tools.zh.md: 50843b07f1d98b1c9d9222288b1273b34bee1e4a
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index b63014d1c2..0551ee1c9d 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -2,7 +2,7 @@
 
 English | [中文](tools.zh.md)
 
-The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine and `ToolSchema` as the model-facing wire shape. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the guarded execution shapes, and the UI-presentation vocabulary.
+The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine; the model-facing [`ToolSchema`](llm-streaming.md#the-model-request-and-result) wire shape is declared with the model request. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the guarded execution shapes, and the UI-presentation vocabulary.
 
 Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
 
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 2dc5802efc..50843b07f1 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -2,7 +2,7 @@
 
 [English](tools.md) | 中文
 
-[dsh-tools](../../packages/core/tools) 的工具流水线。[core.md](core.md) 介绍了 `ToolDefinition`（唯一被提升到主干的流水线编写类型）和 `ToolSchema`（面向模型的协议格式（wire format）形状）。本页拥有完整的 `ToolDefinition`、用于构建它的类型化 schema DSL、受保护的执行形状，以及 UI 展示词汇。
+[dsh-tools](../../packages/core/tools) 的工具流水线。[core.md](core.md) 介绍了 `ToolDefinition`（唯一被提升到主干的流水线编写类型）；面向模型的 [`ToolSchema`](llm-streaming.md#the-model-request-and-result) 协议格式（wire format）形状与模型请求一起声明。本页拥有完整的 `ToolDefinition`、用于构建它的类型化 schema DSL、受保护的执行形状，以及 UI 展示词汇。
 
 源码：[`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
 
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index 77539b60fb..f2321e732a 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
-README.md: 31a306cb08fe69297b0d0843b57b5e491c0bbe44
-README.zh.md: 6eafe8726ba59edd3a6bf739deacc037a9b56b76
+README.md: a72cd48bb1d3ec15b1116d576fac86619df59528
+README.zh.md: 170a557e40befaa0f7073f25e8a2b372958a6ec1
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index 31a306cb08..a72cd48bb1 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -14,4 +14,4 @@ The seams through which a human collaborates with a running agent — questions,
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
 
-The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), [commands.md](../../docs/subsystems/commands.md), and [tui.md](../../docs/subsystems/tui.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
+The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), and [commands.md](../../docs/subsystems/commands.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 6eafe8726b..170a557e40 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -14,4 +14,4 @@
 
 这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
 
-子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)、[commands.md](../../docs/subsystems/commands.md) 与 [tui.md](../../docs/subsystems/tui.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
+子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)与 [commands.md](../../docs/subsystems/commands.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 53bbf9cdbb..5a2f02826c 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/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/self-modification/README.md
 README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
-README.zh.md: 90030cda33f47d128041b7619546ac1309b8465a
+README.zh.md: 18e03798b90e73f1d7e61ecf7010b8c472454a08
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
index 90030cda33..18e03798b9 100644
--- a/packages/self-modification/README.zh.md
+++ b/packages/self-modification/README.zh.md
@@ -8,5 +8,3 @@ agent 修改自身运行时：检查已加载的插件与服务接口、挂载
 |---|---|---|
 | [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
 | [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
-
-工具契约见 [`tool-cordis/README.md`](tool-cordis/README.md) 与 [`repository-plugin/README.md`](repository-plugin/README.md)。
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 35fef7beaf..b053efe789 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -154,16 +154,17 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
 export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
+  AgentFactory: 'core.md',
+  AgentHandle: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
   ContentBlock: 'llm-streaming.md',
-  ContinuationDecision: 'core.md',
-  ContinuationStop: 'core.md',
+  CreateAgentOptions: 'core.md',
   GenerateOptions: 'llm-streaming.md',
   InboxItem: 'core.md',
   InboxPlacement: 'core.md',
   MessageId: 'llm-streaming.md',
-  HookContext: 'core.md',
+  ResumeAgentOptions: 'core.md',
   SettleReason: 'core.md',
   AdapterRegistrationHandle: 'llm-streaming.md',
   DirectoryRegistrationHandle: 'llm-streaming.md',
@@ -188,7 +189,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
   SessionReferenceInput: 'session-reference.md',
-  SessionEvent: 'core.md',
+  SessionEvent: 'session.md',
   SessionId: 'core.md',
   SessionStartSource: 'core.md',
   SessionLogSnapshot: 'session-query.md',
@@ -410,18 +411,15 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
 
 /** Project types deliberately documented outside the subsystems catalog. */
 export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
-  AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   ConsumeTokenRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   InsertTextRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
-  AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
   BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
-  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
   CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
@@ -437,7 +435,6 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
-  ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
   Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 750b1935de..5d8f68f4cd 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -1,9 +1,9 @@
 /** Tests for the documentation website projection adapter. */
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, globSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { docsPages, type DocsPage } from '../website/docs.ts'
 import {
@@ -269,6 +269,19 @@ describe('docsPages locale routes', () => {
     }
   })
 
+  it('indexes every subsystem page in both sides of the folder README', () => {
+    const pages = globSync(join(repositoryRoot, 'docs/subsystems/*.md'))
+      .map(page => basename(page))
+      .filter(page => !page.endsWith('.zh.md') && page !== 'README.md')
+      .sort()
+    expect(pages.length).toBeGreaterThan(0)
+    for (const readme of ['README.md', 'README.zh.md']) {
+      const rows = readFileSync(join(repositoryRoot, 'docs/subsystems', readme), 'utf8')
+      const missing = pages.filter(page => !rows.includes(`| [${page}](${page}) |`))
+      expect(missing, `${readme} must carry one table row per subsystem page`).toEqual([])
+    }
+  })
+
   it('projects translated subsystem pages while retaining explicit English fallbacks', () => {
     const rootPages = docsPages.filter(page => (
       page.locale === 'root' && page.route.startsWith('reference/subsystems/')
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 3d1ca11612..137315cf39 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b3bf8eaec4..5f57b5167d 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -22,17 +22,17 @@
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContextForm",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContextSnapshotSection",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContextFormed",
       "source": "packages/llm/llm/src/message.ts"
     },
@@ -57,12 +57,12 @@
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelDiscoveryRequest",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmDiscoveredModel",
       "source": "packages/llm/llm/src/types.ts"
     },
@@ -111,11 +111,6 @@
       "symbol": "LlmCallConfigAdapterDefaults",
       "source": "packages/llm/llm/src/call-config.ts"
     },
-    {
-      "doc": "docs/subsystems/core.md",
-      "symbol": "SessionEvent",
-      "source": "packages/core/session/src/types.ts"
-    },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
@@ -1689,6 +1684,21 @@
       "doc": "docs/subsystems/session-projection.md",
       "symbol": "ProjectionChangeListener",
       "source": "packages/session/session-projection/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/core.md",
+      "symbol": "AgentHandle",
+      "source": "packages/core/agent/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/core.md",
+      "symbol": "AgentStatus",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/core.md",
+      "symbol": "AgentOptions",
+      "source": "packages/core/agent/src/types.ts"
     }
   ]
 }
diff --git a/website/docs.ts b/website/docs.ts
index 1f7fa316a5..3a31bf4baf 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -261,6 +261,7 @@ const subsystemsReference = pairedPages(([
   ['README.md', '子系统', 'Subsystems', 0],
   ['core.md', '核心', 'Core', 1],
   ['scope.md', '作用域', 'Scopes', 2],
+  ['typert.md', 'TypeRT', 'TypeRT', 39],
   ['session.md', '会话', 'Sessions', 3],
   ['session-query.md', '会话查询', 'Session query', 4],
   ['session-reference.md', '会话引用', 'Session references', 5],
@@ -293,7 +294,6 @@ const subsystemsReference = pairedPages(([
   ['workspace.md', '工作区', 'Workspaces', 32],
   ['http-server.md', 'HTTP 服务器', 'HTTP server', 33],
   ['client-modules.md', '客户端模块', 'Client modules', 34],
-  ['tui.md', 'TUI 扩展', 'TUI extensions', 35],
   ['invariants.md', '运行时不变式', 'Runtime invariants', 36],
   ['session-projection.md', '会话投影', 'Session projections', 37],
   ['telemetry.md', '遥测', 'Telemetry', 38],

From 0fb062d85e0854d7e4b6f925029699a9bcf1a303 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 02:39:12 +0800
Subject: [PATCH 168/262] feat(doc-gates): backstop every declared cordis
 event; deepen the Context scan to src/**

The rendering projection walks only files reachable from host-face package
exports, so client-face Events merges vanished silently (12 events) and the
services backstop's top-level glob missed 13 nested client Context keys.
Events now get the exact mirror of the service backstop (EVENT_WALK_EXEMPTIONS,
name-keyed because client events share scopes with rendered host events), both
scans read packages/*/*/src/**/*.ts, and the partition judgment is the pure
walkPartitionProblems() so every acceptance path is unit-provable.
---
 ...08-09-cordis-event-walk-backstop.i18n.yaml |   6 +
 .../2026-08-09-cordis-event-walk-backstop.md  |  38 ++++
 ...026-08-09-cordis-event-walk-backstop.zh.md |  38 ++++
 scripts/cordis-walk.ts                        |  27 ++-
 scripts/gen-cordis-catalog-partition.spec.ts  | 147 ++++++++++++++
 scripts/gen-cordis-catalog.ts                 | 188 ++++++++++++++----
 6 files changed, 401 insertions(+), 43 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
 create mode 100644 scripts/gen-cordis-catalog-partition.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
new file mode 100644
index 0000000000..e968e7b54e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.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 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
+2026-08-09-cordis-event-walk-backstop.md: 59aeb06149925dc93839df64145555f27257d7be
+2026-08-09-cordis-event-walk-backstop.zh.md: 4549e9d382e5ff17ddff30eafad8d6c7e66d61ed
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
new file mode 100644
index 0000000000..59aeb06149
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
@@ -0,0 +1,38 @@
+# Agent Note: An independent Events backstop closes the cordis-surface exhaustiveness gap
+
+Status: implemented
+
+English | [中文](2026-08-09-cordis-event-walk-backstop.zh.md)
+
+## Problem
+
+`gen-cordis-catalog` renders every service and event the Typert host-face projection discovers, and fail-closed page maps (`SERVICE_PAGE`, `EVENT_SCOPE_PAGE`) guarantee each discovered key or scope lands on exactly one `docs/subsystems/` page. Discovery itself was only backstopped for services: an independent AST scan read every `declare module 'cordis'` Context merge and demanded each declared key be rendered or carry a named `SERVICE_WALK_EXEMPTIONS` reason.
+
+Events had no such backstop. The projection walks only files reachable from host-face package exports, so an `interface Events` merge in client-face code — or in any file the host analyzer cannot reach — vanished with no trace: 12 declared events (`slash/input-*`, `theme/change`, `locale/change`, and the client runtime's `*/changed` invalidation signals) were documented nowhere generated and nothing would ever notice a thirteenth. The services scan also globbed only `packages/*/*/src/*.ts`, so 13 client-face Context keys declared in nested files (`src/client/**`) were invisible to the very scan meant to prevent silent vanishing.
+
+## Decision
+
+Events get the exact mirror of the services backstop, and both scans read the full package source tree.
+
+`scripts/cordis-walk.ts` gains `eventNameList` (every member name of an `interface Events` merge, read from method and property members alike so a shape the projector would reject still enters the scan) and its merge-file prefilter matches the `declare module` heads instead of the literal text `interface Context`, so an Events-only merge file is not skipped. The scan glob in `gen-cordis-catalog` deepens from `packages/*/*/src/*.ts` to `packages/*/*/src/**/*.ts`.
+
+A new curated `EVENT_WALK_EXEMPTIONS` map names every declared event the projection cannot see, with the reason and the package README that owns its surface. Keys are full event names, not scopes: client-face events share scopes with rendered host events (`commands/changed` beside the host `commands/*` family), so a scope-level exemption would mask a host-face regression. The partition check is fail-closed in both directions, exactly like the service maps: an unexempted invisible event, an exemption for an event that renders, and an exemption no merge declares are all hard errors.
+
+The partition judgment moved out of `computeOutputs` into the pure `walkPartitionProblems(input, maps)` so every acceptance path is provable by unit test without running the Typert projection; `computeOutputs` feeds it the rendered model plus the independent scan and keeps aggregating page-splice errors as before.
+
+The audit that motivated this found the host face already complete: 48 rendered services + 10 walk exemptions covered all 58 host-visible Context keys, all 49 host events rendered, and every type name in every rendered signature is classified by the existing fail-closed `LINK_MAP`/`FOUNDATION_TYPE_NAMES`/`TYPE_LINK_EXEMPTIONS` check. The 25 findings (12 events, 13 keys) were all client-face; each now carries a named exemption pointing at its owning README, consistent with the existing `appShell`/`connection` precedent.
+
+## Verification
+
+`scripts/gen-cordis-catalog-partition.spec.ts` proves each acceptance path: the green partition, an invisible unexempted event (named with its declaring file), a stale rendered-event exemption, a stale never-declared exemption, the service mirror of each, unmapped rendered surface in both page maps, and the scan reaching a nested Events-only merge file. Deleting one live exemption from the real tree makes `gen-cordis-catalog` fail loud with the event's name and declaring file; restoring it returns the generator to a byte-identical no-op regeneration (85 artifacts, 0 written), which also proves the new exemptions exactly cover today's surface. `verify-cordis-catalog` in doc-sync executes the partition on every run.
+
+## Alternatives considered
+
+- **Render the client face instead of exempting it.** Analyzing `faces: ['host', 'client']` and giving client services/events generated regions is the real fix for the underlying blind spot, but it changes what the subsystems catalog IS (host-tier reference) and requires page decisions for browser-only surfaces; the existing `TODO(cordis-catalog-interface-services)` already tracks widening the projection. The backstop is the guarantee; rendering is an upgrade behind it.
+- **Scope-level event exemptions.** Smaller map, but `commands/changed` (client) shares the `commands` scope with rendered host events, so exempting a scope would swallow a future host-face event silently — the exact failure mode this note removes.
+- **Deriving exhaustiveness from Typert instead of a raw AST scan.** The projection and the backstop must fail independently: a Typert reachability bug is precisely what the backstop exists to catch, so the scan deliberately stays a plain `ts.createSourceFile` walk with no shared machinery.
+- **Gating the transitive type closure of rendered signatures.** Measured before deciding: every type name reachable in rendered signatures is already classified, and deeper field-of-field types are owned by the pages' hand-curated `type-equiv` pastes and package READMEs; a closure gate would force page homes for internals without a reader-facing need.
+
+## Consequences
+
+A new cordis event — host or client, any file depth — must either render onto a subsystems page or name itself in `EVENT_WALK_EXEMPTIONS` with its documentation owner; deleting one must retire its exemption. The same now holds for Context keys declared anywhere under `src/`. The curated maps grew by 25 client-face entries whose reasons all point at package READMEs, keeping the subsystems catalog a host-tier reference. `walkPartitionProblems` is the single home of the partition judgment; future backstop dimensions (e.g. rendering the client face, schema surfaces) extend it and its spec rather than re-inlining checks into `computeOutputs`.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
new file mode 100644
index 0000000000..4549e9d382
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
@@ -0,0 +1,38 @@
+# Agent Note（agent 决策记录）：独立的 Events 兜底扫描补上 cordis 表面完备性缺口
+
+Status: implemented
+
+[English](2026-08-09-cordis-event-walk-backstop.md) | 中文
+
+## Problem
+
+`gen-cordis-catalog` 渲染 Typert host face 投影发现的每个服务与事件，fail-closed 的页面映射（`SERVICE_PAGE`、`EVENT_SCOPE_PAGE`）保证每个被发现的 key 或 scope 恰好落在一个 `docs/subsystems/` 页面上。但"发现"本身此前只对服务有兜底：一条独立的 AST 扫描读取每个 `declare module 'cordis'` Context merge，要求每个声明的 key 要么被渲染、要么在 `SERVICE_WALK_EXEMPTIONS` 中给出具名理由。
+
+事件没有这样的兜底。投影只遍历从 host face 包导出可达的文件，因此 client face 代码——或 host 分析器无法触及的任何文件——里的 `interface Events` merge 会无声消失：12 个已声明事件（`slash/input-*`、`theme/change`、`locale/change`，以及 client runtime 的 `*/changed` 失效信号）不出现在任何生成文档中，而且再多一个也不会有任何机制察觉。服务扫描的 glob 也只有 `packages/*/*/src/*.ts`，于是声明在嵌套文件（`src/client/**`）中的 13 个 client face Context key 恰恰对这条为防止无声消失而存在的扫描不可见。
+
+## Decision
+
+事件获得与服务兜底完全对称的机制，且两条扫描都读取完整的包源码树。
+
+`scripts/cordis-walk.ts` 新增 `eventNameList`（`interface Events` merge 的每个成员名，方法与属性成员一并读取，使投影器会拒绝的形状也进入扫描），其 merge 文件预过滤改为匹配 `declare module` 头部而非字面文本 `interface Context`，从而不再跳过只含 Events 的 merge 文件。`gen-cordis-catalog` 的扫描 glob 从 `packages/*/*/src/*.ts` 加深为 `packages/*/*/src/**/*.ts`。
+
+新的人工维护映射 `EVENT_WALK_EXEMPTIONS` 为投影看不到的每个已声明事件命名，附理由与拥有其表面的包 README。键是完整事件名而非 scope：client face 事件与已渲染的 host 事件共享 scope（`commands/changed` 与 host 的 `commands/*` 家族并存），scope 级豁免会无声吞掉未来的 host face 回归。分区检查与服务映射一样双向 fail-closed：未豁免的不可见事件、已渲染事件的豁免、无任何 merge 声明的豁免，皆为硬错误。
+
+分区判定从 `computeOutputs` 中提取为纯函数 `walkPartitionProblems(input, maps)`，使每条验收路径都能以单元测试证明而无需运行 Typert 投影；`computeOutputs` 向它馈送渲染模型加独立扫描结果，页面拼接错误的聚合方式保持不变。
+
+促成本决定的审计发现 host face 本已完备：48 个渲染服务 + 10 条 walk 豁免覆盖全部 58 个 host 可见 Context key，49 个 host 事件全部渲染，且每个渲染签名中的每个类型名都已被既有的 fail-closed `LINK_MAP`/`FOUNDATION_TYPE_NAMES`/`TYPE_LINK_EXEMPTIONS` 检查分类。25 条发现（12 事件、13 key）全部在 client face；现在每条都带指向其所属 README 的具名豁免，与既有的 `appShell`/`connection` 先例一致。
+
+## Verification
+
+`scripts/gen-cordis-catalog-partition.spec.ts` 证明每条验收路径：绿色分区、不可见且未豁免的事件（报出声明文件）、已渲染事件的陈旧豁免、从未声明的陈旧豁免、服务侧的对称路径、两个页面映射中未映射的已渲染表面，以及扫描触达嵌套的仅含 Events 的 merge 文件。在真实源码树上删除一条现役豁免会让 `gen-cordis-catalog` 以事件名与声明文件大声失败；恢复后生成器回到字节相同的 no-op 再生成（85 个 artifact，0 写入），这同时证明新豁免恰好覆盖当下表面。doc-sync 中的 `verify-cordis-catalog` 每次运行都会执行该分区检查。
+
+## Alternatives considered
+
+- **渲染 client face 而非豁免。** 以 `faces: ['host', 'client']` 分析并给 client 服务/事件生成区块才是对盲区的根治，但它改变子系统目录的定位（host 层参考），并要求为纯浏览器表面做页面归属决策；既有的 `TODO(cordis-catalog-interface-services)` 已跟踪拓宽投影。兜底是保证，渲染是其上的升级。
+- **scope 级事件豁免。** 映射更小，但 `commands/changed`（client）与已渲染的 host 事件共享 `commands` scope，豁免整个 scope 会无声吞掉未来的 host face 事件——正是本决定要消除的失败模式。
+- **用 Typert 推导完备性而非原始 AST 扫描。** 投影与兜底必须独立失败：Typert 的可达性 bug 恰是兜底要捕获的对象，因此扫描刻意保持为不共享机制的朴素 `ts.createSourceFile` 遍历。
+- **对渲染签名的传递类型闭包设门。** 决定前先测量：渲染签名中可达的每个类型名都已分类，更深的字段套字段类型由页面手工维护的 `type-equiv` 粘贴与包 README 拥有；闭包门会在没有读者需求的情况下强迫内部类型认领页面。
+
+## Consequences
+
+新的 cordis 事件——host 或 client、任意文件深度——必须渲染到某个子系统页面，或在 `EVENT_WALK_EXEMPTIONS` 中以其文档所有者具名；删除事件时必须一并退役其豁免。声明在 `src/` 下任意位置的 Context key 现在同样如此。人工维护映射增加了 25 条 client face 条目，理由全部指向包 README，使子系统目录保持 host 层参考的定位。`walkPartitionProblems` 是分区判定的唯一居所；未来的兜底维度（如渲染 client face、schema 表面）应扩展它及其 spec，而非把检查重新内联进 `computeOutputs`。
diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index 0111d1d042..a7c22bea02 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -11,7 +11,7 @@ import ts from 'typescript'
 
 /**
  * Parse every file matching `pattern` (repo-relative, sorted, `/`-normalized)
- * that textually mentions `interface Context`, yielding each file's cordis
+ * that textually contains a cordis module merge, yielding each file's
  * module-merge body. Files without a merge are skipped.
  * @param scanRoot - Repository root the pattern is resolved against.
  * @param pattern - Glob selecting the TypeScript files to scan.
@@ -25,7 +25,7 @@ export function contextMergeFiles(
   for (const rel of globSync(pattern, { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Context')) continue
+    if (!text.includes("declare module 'cordis'") && !text.includes("declare module './context.ts'")) continue
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
     const body = cordisModuleBody(sf)
     if (!body) continue
@@ -64,3 +64,26 @@ export function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<stri
   }
   return keyToType
 }
+
+/**
+ * Every event name a `declare module 'cordis'` Events merge declares in one
+ * module body. Names are the literal member keys (`'agent/created'`), read
+ * from method and property members alike so a declaration shape the projector
+ * would reject still enters the exhaustiveness scan.
+ * @param body - The cordis module augmentation block.
+ * @param sf - Owning source file (for computed-name text extraction).
+ * @returns Declared event names, in declaration order.
+ */
+export function eventNameList(body: ts.ModuleBlock, sf: ts.SourceFile): string[] {
+  const names: string[] = []
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
+    for (const member of stmt.members) {
+      if (!member.name) continue
+      names.push(ts.isStringLiteral(member.name) || ts.isIdentifier(member.name)
+        ? member.name.text
+        : member.name.getText(sf))
+    }
+  }
+  return names
+}
diff --git a/scripts/gen-cordis-catalog-partition.spec.ts b/scripts/gen-cordis-catalog-partition.spec.ts
new file mode 100644
index 0000000000..7de64fffde
--- /dev/null
+++ b/scripts/gen-cordis-catalog-partition.spec.ts
@@ -0,0 +1,147 @@
+/**
+ * Acceptance-path coverage for the cordis-surface partition backstops
+ * (`walkPartitionProblems` + the AST scan helpers): a declared Context key or
+ * Events member the rendering projection cannot see must carry a named walk
+ * exemption, an exemption must stay live in both directions, and the scan
+ * itself must reach nested (`src/**`) and Events-only merge files.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import ts from 'typescript'
+import { contextKeyMap, contextMergeFiles, eventNameList } from './cordis-walk.ts'
+import { walkPartitionProblems } from './gen-cordis-catalog.ts'
+import type { WalkPartitionInput, WalkPartitionMaps } from './gen-cordis-catalog.ts'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+/** A consistent baseline the red cases mutate one facet at a time. */
+function baseline(): { input: WalkPartitionInput; maps: WalkPartitionMaps } {
+  return {
+    input: {
+      renderedKeys: new Map([['llm', 'packages/llm/llm/src/index.ts:10']]),
+      renderedScopes: new Set(['llm']),
+      renderedEventNames: new Set(['llm/request']),
+      declaredKeys: new Map([
+        ['llm', 'packages/llm/llm/src/index.ts'],
+        ['theme', 'packages/client/ui-theme/src/client/index.ts'],
+      ]),
+      declaredEvents: new Map([
+        ['llm/request', 'packages/llm/llm/src/index.ts'],
+        ['theme/change', 'packages/client/ui-theme/src/client/index.ts'],
+      ]),
+    },
+    maps: {
+      servicePage: { llm: 'llm-streaming.md' },
+      serviceWalkExemptions: { theme: 'client-side — packages/client/ui-theme/README.md owns the surface' },
+      eventScopePage: { llm: 'llm-streaming.md' },
+      eventWalkExemptions: { 'theme/change': 'client-face — packages/client/ui-theme/README.md owns the surface' },
+    },
+  }
+}
+
+describe('walkPartitionProblems', () => {
+  it('accepts a partition where every declared key and event is rendered or exempted', () => {
+    const { input, maps } = baseline()
+    expect(walkPartitionProblems(input, maps)).toEqual([])
+  })
+
+  it('rejects a declared event that is neither rendered nor exempted, naming its file', () => {
+    const { input, maps } = baseline()
+    const problems = walkPartitionProblems(input, { ...maps, eventWalkExemptions: {} })
+    expect(problems).toEqual([
+      expect.stringContaining("event 'theme/change' (packages/client/ui-theme/src/client/index.ts) is declared in an Events merge but invisible"),
+    ])
+  })
+
+  it('rejects an event exemption whose event the projection renders', () => {
+    const { input, maps } = baseline()
+    const rendered = { ...input, renderedEventNames: new Set(['llm/request', 'theme/change']) }
+    expect(walkPartitionProblems(rendered, maps)).toEqual([
+      expect.stringContaining("event 'theme/change' is rendered by the projection but still listed in EVENT_WALK_EXEMPTIONS"),
+    ])
+  })
+
+  it('rejects an event exemption no Events merge declares', () => {
+    const { input, maps } = baseline()
+    const stale = { ...maps, eventWalkExemptions: { ...maps.eventWalkExemptions, 'gone/away': 'nothing owns this' } }
+    expect(walkPartitionProblems(input, stale)).toEqual([
+      expect.stringContaining("EVENT_WALK_EXEMPTIONS names 'gone/away' but no Events merge declares it"),
+    ])
+  })
+
+  it('rejects a declared Context key that is neither rendered nor exempted', () => {
+    const { input, maps } = baseline()
+    const problems = walkPartitionProblems(input, { ...maps, serviceWalkExemptions: {} })
+    expect(problems).toEqual([
+      expect.stringContaining('ctx.theme (packages/client/ui-theme/src/client/index.ts) is declared in a Context merge but invisible'),
+    ])
+  })
+
+  it('rejects an unmapped rendered service with its source pointer, and stale page maps both ways', () => {
+    const { input, maps } = baseline()
+    const problems = walkPartitionProblems(input, {
+      ...maps,
+      servicePage: { ghost: 'core.md' },
+      eventScopePage: { specter: 'core.md' },
+    })
+    expect(problems).toEqual(expect.arrayContaining([
+      expect.stringContaining('service ctx.llm (packages/llm/llm/src/index.ts:10) has no SERVICE_PAGE entry'),
+      expect.stringContaining("event scope 'llm/*' has no EVENT_SCOPE_PAGE entry"),
+      expect.stringContaining("SERVICE_PAGE maps 'ctx.ghost' but the projection discovers no such service"),
+      expect.stringContaining("EVENT_SCOPE_PAGE maps 'specter/*' but the projection discovers no such scope"),
+    ]))
+    expect(problems).toHaveLength(4)
+  })
+})
+
+describe('cordis-walk scan reach', () => {
+  it('finds Context keys and Events names in nested Events-only merge files', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cordis-walk-'))
+    roots.push(root)
+    const dir = join(root, 'packages/client/ui-x/src/client')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'index.ts'), [
+      "declare module 'cordis' {",
+      '  interface Events {',
+      "    'x/changed'(): void",
+      '  }',
+      '}',
+      'export {}',
+      '',
+    ].join('\n'))
+    const merges = contextMergeFiles(root, 'packages/*/*/src/**/*.ts')
+    expect(merges.map(m => m.rel)).toEqual(['packages/client/ui-x/src/client/index.ts'])
+    const only = merges[0]
+    if (!only) throw new Error('scan returned no merge')
+    expect(eventNameList(only.body, only.sf)).toEqual(['x/changed'])
+    expect([...contextKeyMap(only.body, only.sf).keys()]).toEqual([])
+  })
+
+  it('reads string-literal and identifier member names from an Events merge', () => {
+    const sf = ts.createSourceFile('x.ts', [
+      "declare module 'cordis' {",
+      '  interface Events {',
+      "    'scope/list'(items: string[]): void",
+      '    plain(): void',
+      '  }',
+      '  interface Context {',
+      '    thing: ThingService',
+      '  }',
+      '}',
+      '',
+    ].join('\n'), ts.ScriptTarget.Latest, true)
+    const body = sf.statements[0] && ts.isModuleDeclaration(sf.statements[0]) && sf.statements[0].body
+      && ts.isModuleBlock(sf.statements[0].body)
+      ? sf.statements[0].body
+      : null
+    if (!body) throw new Error('fixture did not parse to a module block')
+    expect(eventNameList(body, sf)).toEqual(['scope/list', 'plain'])
+    expect([...contextKeyMap(body, sf)]).toEqual([['thing', 'ThingService']])
+  })
+})
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b053efe789..ef2b6c0ed5 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -21,7 +21,7 @@ import {
 } from '@deepseek-ai/dsh-typert-generator'
 import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
-import { contextKeyMap, contextMergeFiles } from './cordis-walk.ts'
+import { contextKeyMap, contextMergeFiles, eventNameList } from './cordis-walk.ts'
 import {
   blobHash,
   parsePairMeta,
@@ -97,10 +97,11 @@ export const SERVICE_PAGE: Record<string, string> = {
  * Context keys declared in `interface Context` merges that the rendering
  * projection cannot see, each with the reason and its documentation owner.
  * The scan that enforces this list reads EVERY `declare module 'cordis'`
- * Context merge under `packages/x/x/src/*.ts` — not only root `index.ts`
- * files with a same-named service class — so a new service can never silently
- * join this blind spot: it either enters {@link SERVICE_PAGE} or names itself
- * here.
+ * Context merge under `packages/x/x/src/**` — any depth, not only root
+ * `index.ts` files with a same-named service class — so a new service can
+ * never silently join this blind spot: it either enters {@link SERVICE_PAGE}
+ * or names itself here. Client-face keys (the projection analyzes the host
+ * face only) name the package README that owns their surface.
  * TODO(cordis-catalog-interface-services): the interface-typed and
  * non-index-declared entries would all render once the projection resolves a
  * Context key through its declaring file's imports to the class declaration.
@@ -116,14 +117,27 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the surface',
   appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the surface',
   connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the surface',
+  chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the surface',
+  command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the surface',
+  conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the surface',
+  layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the surface',
+  locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the surface',
+  models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the surface',
+  modules: 'client-side interface-typed browser service — packages/client/modules/README.md owns the surface',
+  remote: 'client-side interface-typed gateway accessor (ClientRemote) — packages/api/gateway/README.md owns the surface',
+  sessionHistory: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
+  slash: 'client-side interface-typed browser service — packages/client/ui-slash/README.md owns the surface',
+  slots: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
+  theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the surface',
+  workspaces: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
 }
 
 /**
  * The owning subsystems page for every harness event scope (the segment
- * before the first `/`). Fail-closed exactly like {@link SERVICE_PAGE}.
- * `slash` lives with the human-command surface: the client slash-input
- * protocol parses toward command invocation and `dsh-ui-slash` owns the
- * declarations, but commands.md owns the cross-package command story.
+ * before the first `/`) the projection renders. Fail-closed exactly like
+ * {@link SERVICE_PAGE}. Client-face events (`slash/*`, `theme/change`, …) are
+ * invisible to the host-face projection and therefore never reach this map;
+ * {@link EVENT_WALK_EXEMPTIONS} names each one with its documentation owner.
  */
 export const EVENT_SCOPE_PAGE: Record<string, string> = {
   'agent': 'core.md',
@@ -145,6 +159,32 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
   'workflow': 'workflow.md',
 }
 
+/**
+ * Event names declared in `interface Events` merges that the rendering
+ * projection cannot see, each with the reason and its documentation owner.
+ * The mirror of {@link SERVICE_WALK_EXEMPTIONS} for events: an independent
+ * scan reads EVERY `declare module 'cordis'` Events merge under
+ * `packages/x/x/src/**`, so a declared event either renders onto a subsystems
+ * page (via {@link EVENT_SCOPE_PAGE}) or names itself here — never vanishes
+ * silently. Keys are full event names, not scopes: client-face events share
+ * scopes with rendered host events (`commands/changed` beside `commands/*`),
+ * so a scope-level exemption would mask a host-face regression.
+ */
+export const EVENT_WALK_EXEMPTIONS: Record<string, string> = {
+  'commands/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'connection/reset': 'client-face transport signal — packages/client/runtime/README.md owns the surface',
+  'credentials/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'locale/change': 'client-face locale switch signal — packages/client/locale/README.md owns the surface',
+  'models/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'settings/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'slash/input-begin-command': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slash/input-consume-token': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slash/input-insert-reference': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slash/input-insert-text': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slots/changed': 'client-face slot invalidation signal — packages/client/runtime/README.md owns the surface',
+  'theme/change': 'client-face theme switch signal — packages/client/ui-theme/README.md owns the surface',
+}
+
 /**
  * One primary subsystems page per project type used by a generated
  * signature. This stays curated because union names intentionally do not
@@ -506,56 +546,122 @@ export function spliceRegion(content: string, region: string): string {
   return [...lines.slice(0, begin), ...region.split('\n'), ...lines.slice(end + 1)].join('\n')
 }
 
+/** The declared-vs-rendered inputs {@link walkPartitionProblems} judges. */
+export interface WalkPartitionInput {
+  /** Service key → source pointer, as the rendering projection produced them. */
+  readonly renderedKeys: ReadonlyMap<string, string>
+  /** Event scopes the rendering projection produced. */
+  readonly renderedScopes: ReadonlySet<string>
+  /** Event names the rendering projection produced. */
+  readonly renderedEventNames: ReadonlySet<string>
+  /** Context key → first declaring file, from the independent AST scan. */
+  readonly declaredKeys: ReadonlyMap<string, string>
+  /** Event name → first declaring file, from the independent AST scan. */
+  readonly declaredEvents: ReadonlyMap<string, string>
+}
+
+/** The curated partition maps {@link walkPartitionProblems} enforces. */
+export interface WalkPartitionMaps {
+  readonly servicePage: Readonly<Record<string, string>>
+  readonly serviceWalkExemptions: Readonly<Record<string, string>>
+  readonly eventScopePage: Readonly<Record<string, string>>
+  readonly eventWalkExemptions: Readonly<Record<string, string>>
+}
+
+/**
+ * Judge the rendered surface and the independent AST scan against the curated
+ * partition maps, fail-closed in both directions for services AND events: a
+ * rendered key/scope must be mapped to a page, a mapped key/scope must still
+ * render, and — the backstop — a DECLARED key/event the projection cannot see
+ * must carry a named walk exemption (a rendered one must not). Pure so the
+ * acceptance paths are provable without running the projection.
+ * @param input - rendered surface plus the declared-key/event scans.
+ * @param maps - the curated page maps and walk exemptions.
+ * @returns one message per violation, empty when the partition holds.
+ */
+export function walkPartitionProblems(input: WalkPartitionInput, maps: WalkPartitionMaps): string[] {
+  const problems: string[] = []
+  for (const [key, source] of input.renderedKeys) {
+    if (!Object.hasOwn(maps.servicePage, key)) problems.push(`service ctx.${key} (${source}) has no SERVICE_PAGE entry; every service maps to exactly one subsystems page.`)
+  }
+  for (const scope of [...input.renderedScopes].sort()) {
+    if (!Object.hasOwn(maps.eventScopePage, scope)) problems.push(`event scope '${scope}/*' has no EVENT_SCOPE_PAGE entry; every event scope maps to exactly one subsystems page.`)
+  }
+  for (const key of Object.keys(maps.servicePage)) {
+    if (!input.renderedKeys.has(key)) problems.push(`SERVICE_PAGE maps 'ctx.${key}' but the projection discovers no such service; remove the stale entry.`)
+  }
+  for (const scope of Object.keys(maps.eventScopePage)) {
+    if (!input.renderedScopes.has(scope)) problems.push(`EVENT_SCOPE_PAGE maps '${scope}/*' but the projection discovers no such scope; remove the stale entry.`)
+  }
+  // The rendering projection only sees a Context key it can resolve to a
+  // documented service class. The independent scan reads EVERY Context merge
+  // so a key the projection cannot render must either be rendered (mapped) or
+  // carry a named SERVICE_WALK_EXEMPTIONS reason — never vanish silently.
+  for (const [key, rel] of input.declaredKeys) {
+    const rendered = input.renderedKeys.has(key)
+    const exempt = Object.hasOwn(maps.serviceWalkExemptions, key)
+    if (!rendered && !exempt) {
+      problems.push(`ctx.${key} (${rel}) is declared in a Context merge but invisible to the rendering projection; map it in SERVICE_PAGE (after making it renderable) or name it in SERVICE_WALK_EXEMPTIONS with its documentation owner.`)
+    }
+    if (rendered && exempt) problems.push(`ctx.${key} is rendered by the projection but still listed in SERVICE_WALK_EXEMPTIONS; remove the stale exemption.`)
+  }
+  for (const key of Object.keys(maps.serviceWalkExemptions)) {
+    if (!input.declaredKeys.has(key)) problems.push(`SERVICE_WALK_EXEMPTIONS names 'ctx.${key}' but no Context merge declares it; remove the stale exemption.`)
+  }
+  // The event mirror of the service backstop: the projection walks only files
+  // reachable from host-face package exports, so a client-face or unreachable
+  // Events merge would otherwise vanish without a trace.
+  for (const [name, rel] of input.declaredEvents) {
+    const rendered = input.renderedEventNames.has(name)
+    const exempt = Object.hasOwn(maps.eventWalkExemptions, name)
+    if (!rendered && !exempt) {
+      problems.push(`event '${name}' (${rel}) is declared in an Events merge but invisible to the rendering projection; make it renderable (mapped via EVENT_SCOPE_PAGE) or name it in EVENT_WALK_EXEMPTIONS with its documentation owner.`)
+    }
+    if (rendered && exempt) problems.push(`event '${name}' is rendered by the projection but still listed in EVENT_WALK_EXEMPTIONS; remove the stale exemption.`)
+  }
+  for (const name of Object.keys(maps.eventWalkExemptions)) {
+    if (!input.declaredEvents.has(name)) problems.push(`EVENT_WALK_EXEMPTIONS names '${name}' but no Events merge declares it; remove the stale exemption.`)
+  }
+  return problems
+}
+
 /**
  * Compute every generated artifact: the inherited-tier page, the model-facing
  * runtime API module, plus, per mapped subsystems page, the pair's two updated
  * documents with the injected region. Fail-loud partition checks live here: an
  * unmapped service/event scope, a mapping whose page file does not exist, a
- * curated entry whose key/scope the projection no longer discovers, and a
- * mapped page missing its markers are all aggregated errors.
+ * curated entry whose key/scope the projection no longer discovers, a declared
+ * Context key or Events member the projection cannot see without a named walk
+ * exemption, and a mapped page missing its markers are all aggregated errors.
  * @returns `[repo-relative path, exact content]` for every generated artifact.
  */
 export function computeOutputs(): [string, string][] {
   const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const services = [...model.services]
   const events = [...model.events]
-  const problems: string[] = []
 
-  const discoveredKeys = new Set(services.map(s => s.key))
-  const discoveredScopes = new Set(events.map(e => e.scope))
-  for (const s of services) {
-    if (!Object.hasOwn(SERVICE_PAGE, s.key)) problems.push(`service ctx.${s.key} (${s.source}) has no SERVICE_PAGE entry; every service maps to exactly one subsystems page.`)
-  }
-  for (const scope of discoveredScopes) {
-    if (!Object.hasOwn(EVENT_SCOPE_PAGE, scope)) problems.push(`event scope '${scope}/*' has no EVENT_SCOPE_PAGE entry; every event scope maps to exactly one subsystems page.`)
-  }
-  for (const key of Object.keys(SERVICE_PAGE)) {
-    if (!discoveredKeys.has(key)) problems.push(`SERVICE_PAGE maps 'ctx.${key}' but the projection discovers no such service; remove the stale entry.`)
-  }
-  for (const scope of Object.keys(EVENT_SCOPE_PAGE)) {
-    if (!discoveredScopes.has(scope)) problems.push(`EVENT_SCOPE_PAGE maps '${scope}/*' but the projection discovers no such scope; remove the stale entry.`)
-  }
-  // The rendering projection only sees a Context key it can resolve to a
-  // documented service class. This independent scan reads EVERY Context merge
-  // so a key the projection cannot render must either be rendered (mapped) or
-  // carry a named SERVICE_WALK_EXEMPTIONS reason — never vanish silently.
   const declaredKeys = new Map<string, string>()
-  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/*.ts')) {
+  const declaredEvents = new Map<string, string>()
+  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/**/*.ts')) {
     for (const key of contextKeyMap(body, sf).keys()) {
       if (!declaredKeys.has(key)) declaredKeys.set(key, rel)
     }
-  }
-  for (const [key, rel] of declaredKeys) {
-    const rendered = discoveredKeys.has(key)
-    const exempt = Object.hasOwn(SERVICE_WALK_EXEMPTIONS, key)
-    if (!rendered && !exempt) {
-      problems.push(`ctx.${key} (${rel}) is declared in a Context merge but invisible to the rendering projection; map it in SERVICE_PAGE (after making it renderable) or name it in SERVICE_WALK_EXEMPTIONS with its documentation owner.`)
+    for (const name of eventNameList(body, sf)) {
+      if (!declaredEvents.has(name)) declaredEvents.set(name, rel)
     }
-    if (rendered && exempt) problems.push(`ctx.${key} is rendered by the projection but still listed in SERVICE_WALK_EXEMPTIONS; remove the stale exemption.`)
-  }
-  for (const key of Object.keys(SERVICE_WALK_EXEMPTIONS)) {
-    if (!declaredKeys.has(key)) problems.push(`SERVICE_WALK_EXEMPTIONS names 'ctx.${key}' but no Context merge declares it; remove the stale exemption.`)
   }
+  const problems = walkPartitionProblems({
+    renderedKeys: new Map(services.map(s => [s.key, s.source])),
+    renderedScopes: new Set(events.map(e => e.scope)),
+    renderedEventNames: new Set(events.map(e => e.name)),
+    declaredKeys,
+    declaredEvents,
+  }, {
+    servicePage: SERVICE_PAGE,
+    serviceWalkExemptions: SERVICE_WALK_EXEMPTIONS,
+    eventScopePage: EVENT_SCOPE_PAGE,
+    eventWalkExemptions: EVENT_WALK_EXEMPTIONS,
+  })
   if (problems.length > 0) throw new Error(`gen-cordis-catalog: ${problems.length} partition violation(s):\n${problems.map(p => `  ${p}`).join('\n')}`)
 
   const pages = [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])].sort()

From bd659179f66ee397e6bcd9dcadede06c1eb192e4 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 03:20:17 +0800
Subject: [PATCH 169/262] docs(i18n): reproofread updated Chinese documentation

---
 ...26-06-11-content-block-vocabulary.i18n.yaml |  2 +-
 .../2026-06-11-content-block-vocabulary.zh.md  |  2 +-
 ...2026-06-11-event-sourced-sessions.i18n.yaml |  2 +-
 .../2026-06-11-event-sourced-sessions.zh.md    |  2 +-
 ...-06-11-microkernel-event-taxonomy.i18n.yaml |  2 +-
 ...2026-06-11-microkernel-event-taxonomy.zh.md |  2 +-
 .../2026-06-14-session-persistence.i18n.yaml   |  2 +-
 .../2026-06-14-session-persistence.zh.md       |  8 ++++----
 ...red-persistence-write-coordinator.i18n.yaml |  2 +-
 ...-shared-persistence-write-coordinator.zh.md |  6 +++---
 ...6-21-bounded-llm-request-recovery.i18n.yaml |  2 +-
 ...26-06-21-bounded-llm-request-recovery.zh.md |  8 ++++----
 ...2026-06-30-event-domain-semantics.i18n.yaml |  2 +-
 .../2026-06-30-event-domain-semantics.zh.md    |  2 +-
 ...26-07-05-reconstructable-requests.i18n.yaml |  2 +-
 .../2026-07-05-reconstructable-requests.zh.md  |  6 +++---
 ...on-pressure-and-overflow-recovery.i18n.yaml |  2 +-
 ...action-pressure-and-overflow-recovery.zh.md |  8 ++++----
 ...-send-and-coalesced-user-messages.i18n.yaml |  2 +-
 ...fied-send-and-coalesced-user-messages.zh.md |  6 +++---
 .../2026-07-23-toolview-dissolution.i18n.yaml  |  2 +-
 .../2026-07-23-toolview-dissolution.zh.md      |  8 ++++----
 ...ext-injection-from-turn-execution.i18n.yaml |  2 +-
 ...context-injection-from-turn-execution.zh.md |  4 ++--
 ...session-scope-and-provide-channel.i18n.yaml |  2 +-
 ...ent-session-scope-and-provide-channel.zh.md |  4 ++--
 ...-07-27-dispose-ladder-to-consumer.i18n.yaml |  2 +-
 ...2026-07-27-dispose-ladder-to-consumer.zh.md |  4 ++--
 ...6-07-29-dsh-source-launch-tsx-esm.i18n.yaml |  2 +-
 .../2026-07-29-dsh-source-launch-tsx-esm.zh.md |  2 +-
 ...uest-level-llm-config-credentials.i18n.yaml |  2 +-
 ...-request-level-llm-config-credentials.zh.md |  2 +-
 ...oundaries-and-atomic-registration.i18n.yaml |  2 +-
 ...al-boundaries-and-atomic-registration.zh.md |  2 +-
 .../2026-07-30-web-config-plane.i18n.yaml      |  2 +-
 .../2026-07-30-web-config-plane.zh.md          |  2 +-
 ...action-summary-prefix-cache-reuse.i18n.yaml |  2 +-
 ...compaction-summary-prefix-cache-reuse.zh.md |  2 +-
 ...7-21-semantic-session-checkpoints.i18n.yaml |  2 +-
 ...26-07-21-semantic-session-checkpoints.zh.md |  2 +-
 .../feature/2026-06-15-code-mode.i18n.yaml     |  2 +-
 .../feature/2026-06-15-code-mode.zh.md         |  4 ++--
 ...-06-18-compaction-capability-seam.i18n.yaml |  2 +-
 ...2026-06-18-compaction-capability-seam.zh.md |  2 +-
 .../2026-06-24-workspace-context.i18n.yaml     |  2 +-
 .../feature/2026-06-24-workspace-context.zh.md |  4 ++--
 .../2026-06-29-todo-write-tool.i18n.yaml       |  2 +-
 .../feature/2026-06-29-todo-write-tool.zh.md   |  4 ++--
 .../feature/2026-06-30-hook-bridges.i18n.yaml  |  2 +-
 .../feature/2026-06-30-hook-bridges.zh.md      |  2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml     |  2 +-
 .../feature/2026-06-30-hook-protocol-lib.zh.md |  2 +-
 ...-16-durable-per-step-time-context.i18n.yaml |  2 +-
 ...6-07-16-durable-per-step-time-context.zh.md |  6 +++---
 .../2026-07-19-human-goal-command.i18n.yaml    |  2 +-
 .../2026-07-19-human-goal-command.zh.md        |  2 +-
 ...ersisted-same-session-goal-domain.i18n.yaml |  2 +-
 ...19-persisted-same-session-goal-domain.zh.md |  8 ++++----
 ...19-same-session-goal-round-driver.i18n.yaml |  2 +-
 ...-07-19-same-session-goal-round-driver.zh.md | 12 ++++++------
 ...26-07-21-cross-session-references.i18n.yaml |  2 +-
 .../2026-07-21-cross-session-references.zh.md  |  2 +-
 ...-07-24-web-session-model-selector.i18n.yaml |  2 +-
 ...2026-07-24-web-session-model-selector.zh.md |  2 +-
 ...6-07-28-tool-call-file-open-in-os.i18n.yaml |  2 +-
 .../2026-07-28-tool-call-file-open-in-os.zh.md |  2 +-
 ...ersistent-bash-str-replace-editor.i18n.yaml |  2 +-
 ...29-persistent-bash-str-replace-editor.zh.md |  2 +-
 .../2026-07-04-doc-tiers-and-budgets.i18n.yaml |  2 +-
 .../2026-07-04-doc-tiers-and-budgets.zh.md     | 12 ++++++------
 .../2026-07-22-fast-local-git-hooks.i18n.yaml  |  2 +-
 .../2026-07-22-fast-local-git-hooks.zh.md      |  4 ++--
 ...-27-wine-windows-gates-experiment.i18n.yaml |  2 +-
 ...6-07-27-wine-windows-gates-experiment.zh.md |  4 ++--
 ...6-06-20-public-agent-stop-surface.i18n.yaml |  2 +-
 .../2026-06-20-public-agent-stop-surface.zh.md |  2 +-
 .../2026-07-17-one-send-one-turn.i18n.yaml     |  2 +-
 .../2026-07-17-one-send-one-turn.zh.md         |  8 ++++----
 ...plan-specific-collaboration-state.i18n.yaml |  2 +-
 ...-22-plan-specific-collaboration-state.zh.md |  2 +-
 ...-collapse-persistence-flush-state.i18n.yaml |  2 +-
 ...7-23-collapse-persistence-flush-state.zh.md |  6 +++---
 ...ent-loop-observable-state-machine.i18n.yaml |  2 +-
 ...4-agent-loop-observable-state-machine.zh.md |  2 +-
 ...7-25-client-settings-locale-theme.i18n.yaml |  2 +-
 ...26-07-25-client-settings-locale-theme.zh.md |  6 +++---
 docs/cookbook/adding-an-llm-adapter.i18n.yaml  |  2 +-
 docs/cookbook/adding-an-llm-adapter.zh.md      |  2 +-
 docs/defensive-patterns.i18n.yaml              |  2 +-
 docs/defensive-patterns.zh.md                  |  4 ++--
 docs/user/develop/basic/config.i18n.yaml       |  2 +-
 docs/user/develop/basic/config.zh.md           |  2 +-
 docs/user/develop/basic/tool.i18n.yaml         |  2 +-
 docs/user/develop/basic/tool.zh.md             |  2 +-
 examples/acp-agent/README.i18n.yaml            |  2 +-
 examples/acp-agent/README.zh.md                |  2 +-
 examples/jsonrpc-agent/README.i18n.yaml        |  2 +-
 examples/jsonrpc-agent/README.zh.md            |  6 +++---
 native/README.i18n.yaml                        |  2 +-
 native/README.zh.md                            |  4 ++--
 native/landlock-run/README.i18n.yaml           |  2 +-
 native/landlock-run/README.zh.md               |  2 +-
 packages/acp/acp/README.i18n.yaml              |  2 +-
 packages/acp/acp/README.zh.md                  |  4 ++--
 packages/bash/bash-sandbox/README.i18n.yaml    |  2 +-
 packages/bash/bash-sandbox/README.zh.md        |  2 +-
 packages/client/hmr/README.i18n.yaml           |  2 +-
 packages/client/hmr/README.zh.md               |  2 +-
 packages/client/modules/README.i18n.yaml       |  2 +-
 packages/client/modules/README.zh.md           |  2 +-
 packages/client/runtime/README.i18n.yaml       |  2 +-
 packages/client/runtime/README.zh.md           | 10 +++++-----
 packages/client/schema-form/README.i18n.yaml   |  2 +-
 packages/client/schema-form/README.zh.md       |  2 +-
 packages/client/ui-layout/README.i18n.yaml     |  2 +-
 packages/client/ui-layout/README.zh.md         |  2 +-
 packages/client/ui-model/README.i18n.yaml      |  2 +-
 packages/client/ui-model/README.zh.md          |  2 +-
 packages/client/ui-models/README.i18n.yaml     |  2 +-
 packages/client/ui-models/README.zh.md         |  4 ++--
 packages/client/ui-settings/README.i18n.yaml   |  2 +-
 packages/client/ui-settings/README.zh.md       |  2 +-
 packages/client/ui-sidebar/README.i18n.yaml    |  2 +-
 packages/client/ui-sidebar/README.zh.md        |  2 +-
 packages/client/ui-skill/README.i18n.yaml      |  2 +-
 packages/client/ui-skill/README.zh.md          |  4 ++--
 packages/client/ui-slots/README.i18n.yaml      |  2 +-
 packages/client/ui-slots/README.zh.md          |  2 +-
 packages/client/ui-theme/README.i18n.yaml      |  2 +-
 packages/client/ui-theme/README.zh.md          |  4 ++--
 packages/client/web/README.i18n.yaml           |  2 +-
 packages/client/web/README.zh.md               |  2 +-
 .../code-runtime-worker/README.i18n.yaml       |  2 +-
 .../code-runtime-worker/README.zh.md           |  2 +-
 .../code-runtime/code-runtime/README.i18n.yaml |  2 +-
 .../code-runtime/code-runtime/README.zh.md     |  2 +-
 packages/context/time-context/README.i18n.yaml |  2 +-
 packages/context/time-context/README.zh.md     |  6 +++---
 packages/context/tmux-context/README.i18n.yaml |  2 +-
 packages/context/tmux-context/README.zh.md     |  2 +-
 .../context/workspace-context/README.i18n.yaml |  2 +-
 .../context/workspace-context/README.zh.md     |  6 +++---
 packages/examples/README.i18n.yaml             |  2 +-
 packages/examples/README.zh.md                 |  8 ++++----
 .../examples/agent-spine-demo/README.i18n.yaml |  2 +-
 .../examples/agent-spine-demo/README.zh.md     |  2 +-
 packages/goal/goal-session/README.i18n.yaml    |  2 +-
 packages/goal/goal-session/README.zh.md        |  2 +-
 packages/hooks/README.i18n.yaml                |  2 +-
 packages/hooks/README.zh.md                    |  2 +-
 packages/hooks/hook-protocol/README.i18n.yaml  |  2 +-
 packages/hooks/hook-protocol/README.zh.md      |  2 +-
 packages/host/apiproxy/README.i18n.yaml        |  2 +-
 packages/host/apiproxy/README.zh.md            | 18 +++++++++---------
 .../interaction/tool-ask-user/README.i18n.yaml |  2 +-
 .../interaction/tool-ask-user/README.zh.md     |  2 +-
 .../user-interaction/README.i18n.yaml          |  2 +-
 .../interaction/user-interaction/README.zh.md  |  2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml        |  2 +-
 packages/llm/llm-pi-ai/README.zh.md            |  2 +-
 packages/llm/llm/README.i18n.yaml              |  2 +-
 packages/llm/llm/README.zh.md                  |  4 ++--
 packages/llm/token-meter/README.i18n.yaml      |  2 +-
 packages/llm/token-meter/README.zh.md          |  4 ++--
 packages/mcp/mcp-client/README.i18n.yaml       |  2 +-
 packages/mcp/mcp-client/README.zh.md           |  4 ++--
 .../sandbox/sandbox-local/README.i18n.yaml     |  2 +-
 packages/sandbox/sandbox-local/README.zh.md    |  4 ++--
 .../sandbox/sandbox-policy/README.i18n.yaml    |  2 +-
 packages/sandbox/sandbox-policy/README.zh.md   |  4 ++--
 .../repository-plugin/README.i18n.yaml         |  2 +-
 .../repository-plugin/README.zh.md             |  4 ++--
 .../session-persistence-jsonl/README.i18n.yaml |  4 ++--
 .../session-persistence-jsonl/README.zh.md     |  2 +-
 .../README.i18n.yaml                           |  4 ++--
 .../session-persistence-sqlite/README.zh.md    |  4 ++--
 .../session-persistence/README.i18n.yaml       |  4 ++--
 .../session/session-persistence/README.zh.md   | 16 ++++++++--------
 .../session-projection/README.i18n.yaml        |  4 ++--
 .../session/session-projection/README.zh.md    |  2 +-
 .../session-telemetry-otel/README.i18n.yaml    |  4 ++--
 .../session-telemetry-otel/README.zh.md        |  2 +-
 .../session/session-telemetry/README.i18n.yaml |  4 ++--
 .../session/session-telemetry/README.zh.md     |  2 +-
 packages/skill/tool-skill/README.i18n.yaml     |  2 +-
 packages/skill/tool-skill/README.zh.md         |  6 +++---
 packages/storage/storage/README.i18n.yaml      |  2 +-
 packages/storage/storage/README.zh.md          |  2 +-
 .../subagent-inprocess/README.i18n.yaml        |  2 +-
 .../subagent/subagent-inprocess/README.zh.md   |  6 +++---
 packages/support/llm-replay/README.i18n.yaml   |  2 +-
 packages/support/llm-replay/README.zh.md       |  4 ++--
 packages/support/loader-smoke/README.i18n.yaml |  2 +-
 packages/support/loader-smoke/README.zh.md     |  2 +-
 packages/tasks/tool-tasks/README.i18n.yaml     |  2 +-
 packages/tasks/tool-tasks/README.zh.md         |  2 +-
 packages/typert/README.i18n.yaml               |  2 +-
 packages/typert/README.zh.md                   |  2 +-
 packages/typert/generator/README.i18n.yaml     |  2 +-
 packages/typert/generator/README.zh.md         |  4 ++--
 packages/typert/registry/README.i18n.yaml      |  2 +-
 packages/typert/registry/README.zh.md          |  4 ++--
 packages/util/README.i18n.yaml                 |  2 +-
 packages/util/README.zh.md                     |  4 ++--
 packages/util/native-command/README.i18n.yaml  |  2 +-
 packages/util/native-command/README.zh.md      |  2 +-
 packages/util/retention/README.i18n.yaml       |  2 +-
 packages/util/retention/README.zh.md           |  2 +-
 python/README.i18n.yaml                        |  2 +-
 python/README.zh.md                            |  2 +-
 python/sdk/README.i18n.yaml                    |  2 +-
 python/sdk/README.zh.md                        |  2 +-
 212 files changed, 315 insertions(+), 315 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
index 66dddfd425..0b150d8090 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md
 2026-06-11-content-block-vocabulary.md: 5228724bb9101307db9929aaf7831b477c2a6022
-2026-06-11-content-block-vocabulary.zh.md: ffcbbc13dfe9176941f4838b0078d3850403a16c
+2026-06-11-content-block-vocabulary.zh.md: b43de335917c6b5304a94b296fcb8253827b0600
diff --git a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
index ffcbbc13df..b43de33591 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
@@ -12,7 +12,7 @@ harness 需要一套统一的内部消息语言，供 agent loop（智能体循
 
 自主拥有词汇：消息是类型化内容块的数组（`text`、`reasoning`、`tool-call`、`tool-result`），其联合类型派生自可合并扩展的 `ContentBlockMap`，插件通过声明合并添加新的块类型。同一可合并扩展映射模式为所有「字符串化」字段提供类型（`MessageSource`、`FinishReason`、`TurnTrigger`、`TurnEndReason`）。流式输出采用原始分片协议；`BlockAssembler` 是唯一的共享组装实现。适配器负责转换为提供方的协议格式（wire format）——映射成本留在适配器中，正是它该在的地方。
 
-会话内上下文注入（`context/message`）和轮次中途 steering 最初渲染为带标签的 user-role 信封（system-reminder 模式），而非引入新角色，因此适配器无需承担额外负担。如今两者都投影为无包装的普通用户内容；见[注入内容信封 Agent Note](../simplification/2026-07-20-unwrap-injected-content-envelopes.md)。实际适配器验证已确认此渲染方式符合当前 DeepSeek 的行为；如果未来某提供方出现不兼容，应在该适配器内处理，而非引入新的规范角色。
+会话内上下文注入（`context/message`）和轮次中途 steering（中途引导）最初渲染为带标签的 user-role 信封（system-reminder 模式），而非引入新角色，因此适配器无需承担额外负担。如今两者都投影为无包装的普通用户内容；见[注入内容信封 Agent Note](../simplification/2026-07-20-unwrap-injected-content-envelopes.md)。实际适配器验证已确认此渲染方式符合当前 DeepSeek 的行为；如果未来某提供方出现不兼容，应在该适配器内处理，而非引入新的规范角色。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
index d224676be3..0eb64b3107 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
 2026-06-11-event-sourced-sessions.md: 01f9628c1cfc000aca8654caf5edeff09411fdcc
-2026-06-11-event-sourced-sessions.zh.md: ec5c3e766dfa97c5612827023c5cc66bf01a8e6c
+2026-06-11-event-sourced-sessions.zh.md: 5de230de9e9f1303943b43f6fdeefaf8264aa3bf
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
index ec5c3e766d..5de230de9e 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
@@ -14,7 +14,7 @@ MVP 要求严格的基于事件的追踪，以及完全可回放的会话（严
 
 追加操作是同步的（热路径从不阻塞于 I/O）；`session/event` 是同步通知；持久化插件在后台缓冲写入，并在每个轮次结束时触发的 `session/flush` 检查点处等待排空。
 
-顺序契约：agent loop（智能体循环）先领取 inbox 消息，再运行 `agent/pre-step`；只有 enter 决策才打开 `step/start`，随后在请求派生前追加返回的 `user/message` 批次。提供方输出组装并以 `assistant/message` 追加后才分派工具，因此持久日志记录工具实际遵循的确切消息。回归测试固定了这一顺序。
+顺序约定：agent loop（智能体循环）先领取 inbox 消息，再运行 `agent/pre-step`；只有 enter 决策才打开 `step/start`，随后在请求派生前追加返回的 `user/message` 批次。提供方输出组装并以 `assistant/message` 追加后才分派工具，因此持久日志记录工具实际遵循的确切消息。回归测试固定了这一顺序。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
index 3f1b629bc5..1d561dd14a 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
 2026-06-11-microkernel-event-taxonomy.md: 202595fed125966a5d77920536e7f4ee88f875fe
-2026-06-11-microkernel-event-taxonomy.zh.md: 899c96d86cb7e37d90df349ce5f3f932e0a72f95
+2026-06-11-microkernel-event-taxonomy.zh.md: 1365910157c36699bfe1fdb3a10aa0785948e0fa
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
index 899c96d86c..1365910157 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 - **waterfall（瀑布式事件）**（around-middleware）：插件可变换、否决、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
 - **serial**（按监听器顺序依次 await）：用于 `agent/turn-stopping` 等有序检查点。
 - **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
-- **emit**（同步 fire-and-forget）：用于 inbox 转换、生命周期、错误，以及包含不可变 `tools/result` 观测的事件。轮次与步骤边界由持久会话事件拥有。
+- **emit**（同步 fire-and-forget）：用于通知：inbox 转换、生命周期、错误，以及受错误隔离的 `tools/result` 观测；该观测接收不可变的最终结果。轮次与步骤边界由持久会话事件拥有。
 
 事件词汇定义在接口包中（dsh-agent 声明 agent/* 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index c3f4068862..6737b3f490 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
 2026-06-14-session-persistence.md: 00e129e57c7144fd62eec26f5854ee21dec4e964
-2026-06-14-session-persistence.zh.md: 1c98d5771819e8776d9f5cae4a147d2016ee5978
+2026-06-14-session-persistence.zh.md: 6e4e9ece56332ce74b01d60a111617c70e2a874a
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index 1c98d57718..6e4e9ece56 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -19,11 +19,11 @@ Status: implemented
 
 以下关键选择记录于此，因为它们长期有效、存在争议且出人意料：
 
-- **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏契约和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
-- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些 closer；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
-- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 契约的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该契约以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
+- **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
+- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些收尾事件；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
+- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 约定成立的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该约定以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
 - **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header，SQLite 则将其存入严格的 `INTEGER` 列。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header seam 是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.md)。）
-- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得精确的未发布 Session，以持久化 id 发布它，并继续其投影。[Session 准备阶段决策](2026-08-05-session-preparation.md)定义历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
+- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得原本那个尚未发布的会话，以持久化 id 发布该会话，并延续其投影。[会话准备决策](2026-08-05-session-preparation.md)负责历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index d1ae953836..77c706518c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
 2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
-2026-06-18-shared-persistence-write-coordinator.zh.md: a11926b602651d8a7dc641f61371e882685b508b
+2026-06-18-shared-persistence-write-coordinator.zh.md: 7c04ee921c9b3f965ef6bd6d2d203cf4cbd50ea2
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index a11926b602..7c04ee921c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
 
-组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不修改状态的逻辑检查，以及通过 `load` 实现的默认准备回退。
 
 协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
@@ -35,7 +35,7 @@ Status: implemented
 
 ## 测试
 
-共享的 `runPersistenceContract`（公开 API 契约）为每个后端运行，并证明 `inspect` 会配平被中断的逻辑视图但不改变存储或修订版本，随后由 `prepare` 或 `load` 提交恢复。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空和崩溃尾部修复。`persistence.spec.ts`、`preparations.spec.ts` 与 `write-behind.spec.ts` 覆盖准备复用与预留、有界准备状态淘汰、固定窗口后续批次、存活控制器清理、同 id 链尾竞态、失败批次重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为契约中的崩溃用例会产生合成 closers，却不会产生 torn marker。
+共享的 `runPersistenceContract`（公开 API 约定）为每个后端运行，并证明 `inspect` 会配平被中断的逻辑视图但不改变存储或修订版本，随后由 `prepare` 或 `load` 提交恢复。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空和崩溃尾部修复。`persistence.spec.ts`、`preparations.spec.ts` 与 `write-behind.spec.ts` 覆盖准备复用与预留、有界准备状态淘汰、固定窗口后续批次、存活控制器清理、同 id 链尾竞态、失败批次重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为约定中的崩溃用例会产生合成 closers，却不会产生 torn marker。
 
 ## 曾考虑的替代方案
 
@@ -44,4 +44,4 @@ Status: implemented
 
 ## 后果
 
-协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不可变检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
+协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不修改状态的检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index dc841c67bd..b038b0e02d 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
 2026-06-21-bounded-llm-request-recovery.md: 587f2d26eee922e91c8797018964f983890eb8ec
-2026-06-21-bounded-llm-request-recovery.zh.md: be52ece63ce794cb13cdf657b73bae6e9f42cf6d
+2026-06-21-bounded-llm-request-recovery.zh.md: 4efe4f946dac90f65f5b8af4a7c36037413616b6
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index be52ece63c..4efe4f946d 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-06-21-bounded-llm-request-recovery.md) | 中文
 
-[按提供方配置的请求重试策略](../feature/2026-07-24-provider-retry-policies.md)在此基础上增加了确切提供方配置与显式无界 mode。本说明继续负责结构化失败事实、已关闭步骤的恢复边界、normal mode 的暂时性默认值、可见的单次尝试和持久重试状态。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)取代了其中关于抛出错误身份和 stream sidecar 的机制。
+[按提供方配置的请求重试策略](../feature/2026-07-24-provider-retry-policies.md)在此基础上增加了确切提供方配置与显式无界 mode。本说明继续负责结构化失败事实、已关闭步骤的恢复边界、normal mode 的暂时性默认值、可见的单次尝试和持久重试状态。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)取代了其中关于抛出错误身份和流伴随状态的机制。
 
 ## 问题
 
-提供方适配器可能在分发或迭代时抛出异常，也可能以 `finish { kind: 'error' | 'aborted' }` 结束。最终适配器边界会在 `dsh-agent-loop` 接收前把抛出值规范化为该终止 finish 协议；middleware 与结果处理缺陷仍会抛出。loop 会将终止模型请求失败交给 `agent/request-error`。未被处理的失败是终态；处理失败的监听器修复策略自有状态，返回 `{ kind: 'retry' }`，并停止 waterfall 委托。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回契约。
+提供方适配器可能在分发或迭代时抛出异常，也可能以 `finish { kind: 'error' | 'aborted' }` 结束。最终适配器边界会在 `dsh-agent-loop` 接收前把抛出值规范化为该终止 finish 协议；middleware 与结果处理缺陷仍会抛出。loop 会将终止模型请求失败交给 `agent/request-error`。未被处理的失败是终态；处理失败的监听器修复策略自有状态，返回 `{ kind: 'retry' }`，并停止 waterfall（瀑布式事件）委托。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回约定。
 
 该边界已能安全地再次发起请求。原始 `assistant/chunk` 事件携带失败的 `turn` 和 `step`；除非某条成功的 `assistant/message` 引用这些事件，否则消息派生会忽略它们。只有终止性 finish 成功且组装完成后，系统才会分发工具调用；重试则会从持久日志开启新的编号轮次。因此，harness 无需引入第二套响应生命周期或暂定输出协议，即可分隔两次尝试。
 
@@ -40,7 +40,7 @@ interface LlmFailure {
 
 `code` 仍是 `HarnessError` 建立的提供方无关机器路由分类体系；新字段是在提供方边界观测到的事实。`ProviderRequestId` 由 `dsh-llm` 拥有并构造，序列化后为提供方发放的字符串。该载荷有意不包含 `retryable`、`failover`、`partialOutput`、提供方、模型、阶段或路由 id 字段。是否可重试属于策略，提供方／模型已位于持久请求头中，部分输出则从失败步骤的 `assistant/chunk` 事件派生。
 
-`LlmError` 携带 `failure: LlmFailure`，并保持 `failure.code === error.code`。`FinishReasonMap.error` 和 `FinishReasonMap.aborted` 携带同一载荷，而不是并行的失败形状。最终适配器边界会从适配器抛出值中分离这些事实，并发出相应的终止 finish；未知 SDK 异常会获得 `UNKNOWN` 载荷。精确的抛出对象身份不会跨越 LLM stream seam。
+`LlmError` 携带 `failure: LlmFailure`，并保持 `failure.code === error.code`。`FinishReasonMap.error` 和 `FinishReasonMap.aborted` 携带同一载荷，而不是并行的失败形状。最终适配器边界会从适配器抛出值中分离这些事实，并发出相应的终止 finish；未知 SDK 异常会获得 `UNKNOWN` 载荷。精确的抛出对象身份不会跨越 LLM 流 seam。
 
 agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agent/request-error`，并在记录未恢复的 `turn/end.reason` 时使用同一载荷。
 
@@ -107,7 +107,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 ## 验证
 
 - `LlmFailure` 是适配器抛出、错误 finish 和中止 finish 使用的唯一可序列化载荷；在可用时，规范化保留稳定 code、状态、重试延迟、品牌化的提供方请求 id，以及调用方中止与适配器超时之间的分类。
-- 适配器抛出值会在抵达消费方前成为终止失败 chunk；middleware 与消费方异常仍在模型请求恢复之外抛出。
+- 适配器抛出值会在抵达消费方前成为终止失败分片；middleware 与消费方异常仍在模型请求恢复之外抛出。
 - DeepSeek 和 pi-ai 适配器测试覆盖具有代表性的 400、401/403、429、5xx、连接、格式错误／截断流、超时、中止、Retry-After 秒数／日期、请求 id 和未知 SDK 错误路径，恢复策略无需解析消息文本。
 - pi-ai 将 SDK 选项固定为零次重试，并针对可重试的提供方响应执行一次可观测的线路请求尝试；独立测试确保移除任一边界都会失败。
 - `agent/request-error` 携带当前失败事实、不可变的先前已重试失败事实，以及实际服务注册所对应的不可变重试策略；成功会清除历史，暂时性失败／上下文溢出交替发生的集成测试证明两种策略只消耗各自的有限预算。
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index 2317a5a14e..2e69991c33 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
 2026-06-30-event-domain-semantics.md: 14102b105e7bcaa6a00ac9c406933f772fc45a6f
-2026-06-30-event-domain-semantics.zh.md: 91e490b57bcdc1ed95f0b8b40cc9e16ef4d36f29
+2026-06-30-event-domain-semantics.zh.md: 2607e59490d8ba139bb1289d0f2941894281f6c6
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
index 91e490b57b..2607e59490 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -21,7 +21,7 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 **三个域，各司其职，以一条边界规则统一。**
 
 - **`session/*`——持久的、可回放的事实日志。** 拥有 `SessionEventMap`；每条记录仅含 JSON（无活对象）。每次追加触发一次 `session/event` emit，加上 `session/flush` 并行持久性检查点。它同时也是实时 transcript（文本记录）源：想渲染或响应已发生事件的消费方在此订阅，因此实时渲染与回放投影共享同一路径。
-- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和中途 steering（以 `user/message` 呈现）同理。
+- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和作为一条 `user/message` 的轮次中途 steering（中途引导）同理。
 - **`tools/*`——工具注册表与执行 seam。**
 
 **边界规则：** 持久的、可回放的事实是 `SessionEvent`；实时拦截或瞬态/活对象信号是 `agent`/`tools` Cordis 事件。轮次或步骤边界是持久事实，因此存在于会话日志中并从 `session/event` 源读取——不会被镜像为 `agent/*` emit。
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 2926746ee1..1b5962f672 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
 2026-07-05-reconstructable-requests.md: ebca9b99cad791159302da9c2bbce9f4df147aab
-2026-07-05-reconstructable-requests.zh.md: 91ef3fd04502f2c2f092da60a8bd909cf7fa25df
+2026-07-05-reconstructable-requests.zh.md: e7ed83bbc553e86d53d88e442b0fd8992973c9e7
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index 91ef3fd045..e7ed83bbc5 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -47,9 +47,9 @@ Status: implemented
 ## 后果
 
 - 一个日志无法解释的请求不可能被意外构造——无论是循环还是监听器；变异已构建的请求会抛异常；每个 header 变更都是持久的、可 diff 的日志事件。
-- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价并在后续成为可缓存前缀，代价是会在历史中累积直至压缩。
-- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
+- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价，此后即被前缀缓存，代价是会在历史中累积直至压缩。
+- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身对思考内容的排除由服务端管理。
 - `agent/pre-step` 是当前请求的消息 seam；直接修改 inbox 则是最终进入后续请求的 seam。
-- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
+- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存失效由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index cefb0b0dd2..03acf306b4 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
 2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6fbd5e2c9d57da3f25c72c652ca50eb45b84323c
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: c46b3eeeb446165192ef44de938c9a5a657a02f8
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 8a480999038cf892842290e3ea3902683d87e431
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index c46b3eeeb4..8a48099903 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -22,9 +22,9 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 ### 请求恢复只覆盖最终模型边界
 
-`agent/request-error` 表示来自最终适配器边界的终止失败。适配器选择、分发、iterator 构造与迭代抛出会在 agent loop 消费前成为终止 `error` 或 `aborted` finish；适配器直接发出的终止 finish 进入同一路径。提示词装配、请求 middleware、请求日志、结果处理、工具、step 监听器与清理仍属于普通失败。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)规定这一规范化边界。
+`agent/request-error` 表示来自最终适配器边界的终止失败。适配器选择、分发、iterator 构造与迭代抛出会在 agent loop（智能体循环）消费前成为终止 `error` 或 `aborted` finish；适配器直接发出的终止 finish 进入同一路径。提示词装配、请求 middleware、请求日志、结果处理、工具、step 监听器与清理仍属于普通失败。[LLM（大语言模型）流的终止失败](2026-07-29-terminal-llm-stream-failures.md)规定这一规范化边界。
 
-恢复运行前，失败 step 已经关闭。负责处理的监听器修复持久状态、返回 `{ kind: 'retry' }`，并停止 waterfall 委托。循环随后关闭失败 turn，并从持久日志开启一个重试 turn，中间不发布空闲通知。重试策略与尝试计数由插件自己拥有；compact-basic 在链路到达终态 `agent/settled` 时清除对应 agent 的溢出计数。两个 DeepSeek 适配器都把识别出的提供方上下文限制错误规范化为 `CONTEXT_WINDOW_EXCEEDED`。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回边界。
+恢复运行前，失败 step 已经关闭。负责处理的监听器修复持久状态、返回 `{ kind: 'retry' }`，并停止 waterfall（瀑布式事件）委托。循环随后关闭失败 turn，并从持久日志开启一个重试 turn，中间不发布空闲通知。重试策略与尝试计数由插件自己拥有；compact-basic 在链路到达终态 `agent/settled` 时清除对应 agent 的溢出计数。两个 DeepSeek 适配器都把识别出的提供方上下文限制错误规范化为 `CONTEXT_WINDOW_EXCEEDED`。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回边界。
 
 如果取消发生在 assistant 工具调用已经持久化之后、所有调用完成分发之前，循环会为每个尚未分发的调用记录一对合成的 `tool/call` 与 aborted `tool/result`，随后进入正常中止路径。因此，表层不会仅因取消赢得竞态而留下孤立的持久工具调用。
 
@@ -42,7 +42,7 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 ## 测试
 
-单元测试覆盖最终适配器规范化边界、已关闭 turn 的重试编号与重置、取消与销毁、step 边界顺序、已路由信封压力、压力门控剪枝、剪枝独立解除压力、从已剪枝输入生成摘要、平衡溢出缩减、后续失败前已落盘的剪枝进展、generation 证明、上限、委托与辅助调用路由。真实循环测试覆盖抛出式和带内溢出，并验证剪枝或摘要压缩后的重试请求从替换表层重建。
+单元测试覆盖最终适配器规范化边界、已关闭 turn 的重试编号与重置、取消与销毁、step 边界顺序、已路由信封压力、压力门控剪枝、剪枝独立解除压力、从已剪枝输入生成摘要、平衡溢出缩减、后续失败前已落盘的剪枝进展、generation 证明、上限、委托与辅助调用路由。真实循环测试覆盖抛出式和带内溢出在经剪枝或摘要压缩后重建重试请求的过程。
 
 ## 考虑过的替代方案
 
@@ -58,4 +58,4 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 代价是在共享 pre-step waterfall 中执行压力工作，并需要适配器持续维护溢出分类。提供方措辞与启发式字符密度仍是维护风险。表层压缩依然无法修复仅信封本身就超出窗口的情况，也不能拆分不可分割的非工具节点，或修复非可剪枝剩余部分仍然过大的工具单元。若可移除的文本工具结果是主要体积，可选剪枝器仍可修复原本不可分割的工具配对。
 
-[已领取 pre-step 生命周期](2026-07-31-claimed-pre-step-inbox-lifecycle.md)取代了本记录原先的 post-step 触发方式。服务拆分、独立 token meter、平衡范围契约、日志记录锁、摘要替换与唯一 `summarize()` 子类 hook 均保持不变。
+[已领取 pre-step 生命周期](2026-07-31-claimed-pre-step-inbox-lifecycle.md)取代了本记录原先的 post-step 触发方式。服务拆分、独立 token meter、平衡范围约定、日志记录锁、摘要替换与唯一 `summarize()` 子类 hook 均保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
index e1d9a10415..831d3c790f 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
 2026-07-22-unified-send-and-coalesced-user-messages.md: f32d6ca65d5236e1fabdd177cdf54e36929c853f
-2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 7647742166bb760139506f93af672f323b3b7b97
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: af829714276b1a77b8147d89a9be1c9ff6a007a5
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
index 7647742166..af82971427 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -18,13 +18,13 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 
 **context/message 已移除。** 注入的上下文在 inbox 中使用同一个 `UserMessage` 值，并在获准时成为 `user/message` 事件；上下文生产方显式提供合适的非 `user` 类别 `source`，类型化 source 变体携带所有特定于领域的持久来源信息。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。
 
-**Goal 继续执行归属使用正数 Round。** Goal 生命周期状态通过后续 [Goal 自有持久事件决策](2026-07-31-goal-owned-durable-events.md)定义的领域自有 `goal/change` 事件提交。正数 Round 只从已准入的继续执行 `user/message` 推进；goal 持久化不使用注入或 inbox 状态。
+**Goal 继续执行归属使用正数 Round。** Goal 生命周期状态通过后续的[Goal 自有持久事件决策](2026-07-31-goal-owned-durable-events.md)所定义的领域自有 `goal/change` 事件提交。正数 Round 只从已准入的继续执行 `user/message` 推进；goal 持久化不使用注入或 inbox 状态。
 
 **`send` 不返回标识。** 调用方已经持有完整消息及其不透明的 `MessageId`；消息的创建与冻结由[带标识的不可变消息值决策](2026-07-28-identified-immutable-message-values.md)负责，而不是由路由负责。
 
 **Inbox 变更只有一份持久投影和三种最小实时通知。** 每次 append、prepend、编辑、删除、取消与领取都会记录规范化的 `agent/inbox/spliced` 坐标。插入会发出 `agent/inbox/inserted { message }`；普通删除携带持久 `outcome: 'canceled'`，并发出 `agent/inbox/discarded { message }`；循环的原子 `claim()` 会记录纯删除 splice，随后发出 `agent/inbox/claimed { message, turn }`。`MessageId` 是唯一的单次出现标识，并在两个待处理列表间保持唯一。实时载荷刻意不携带 placement、outcome 或批次封套，因为这些事实由持久 splice 持有。
 
-**pre-step 会领取 next-step 输入，但不会为它单独创建轮次。** steering 和注入始终进入同一个 next-step inbox；steering 会唤醒驱动器，注入则不会。在轮次边界，驱动器会原子领取待处理的 next-step 输入，再领取一条排队提示词；在步骤之间则只领取 next-step 输入。领取会记录纯删除 splice，并针对每条消息发出一次 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 会拒绝拟议步骤，或返回进入步骤的完整批次。reject 与监听器失败都会让已领取批次保持已删除；领取后才到达的输入会等待后续边界。
+**pre-step 会领取 next-step 输入，但不会为它单独创建轮次。** steering 和注入始终进入同一个 next-step inbox；steering 会唤醒驱动器，注入则不会。在轮次边界，驱动器会原子领取待处理的 next-step 输入，再领取一条排队提示词；在步骤之间则只领取 next-step 输入。领取会记录纯删除 splice，并针对每条消息发出一次 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 会拒绝拟议步骤，或返回进入步骤的完整批次。拒绝与监听器失败都会让已领取批次保持已删除；领取后才到达的输入会等待后续边界。
 
 **一条已接受消息只保留一种表示。** 持久的用户角色输入和附加的模型可见上下文都直接使用带标识且冻结的 `UserMessage`。循环把该值与私有路由状态存放在一起，不会将其标识、内容或来源复制到另一种公开形状中。steering、注入和工具产生的上下文都会在 next-step inbox 中保留各自带标识的消息。[带标识的不可变消息值决策](2026-07-28-identified-immutable-message-values.md)取代了本记录此前的 `UserMessageData`/`AgentMessage` 层级，并将这一表示扩展到 assistant 消息和工具结果消息。
 
@@ -41,7 +41,7 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 
 ## 后果
 
-投递接口现在是一个原语加三个自解释的预设，(`target` × `wakeup`) 矩阵把此前无法表达的组合显式化。同一个带标识消息值同时服务提示词、注入的上下文和 Goal Round，因此每一处“是否人类提示词？”检查都简化为一次 `source` 判断。`Agent` 契约仍是接口，因此其他实现和对象字面量形式的测试替身只需实现同一个最小结构接口。正数 Goal Round 从已准入的 `user/message` 事件折叠，而 goal 生命周期状态位于投递接口之外。空闲注入会保持待处理，不打开轮次也不运行模型；后续会唤醒的投递在 pre-step 将其放入进入步骤的批次时，它才成为 `user/message`。
+投递接口现在是一个原语加三个自解释的预设，(`target` × `wakeup`) 矩阵把此前无法表达的组合显式化。同一个带标识消息值同时服务提示词、注入的上下文和 Goal Round，因此每一处“是否人类提示词？”检查都简化为一次 `source` 判断。`Agent` 约定仍是接口，因此其他实现和对象字面量形式的测试替身只需实现同一个最小结构接口。正数 Goal Round 从已准入的 `user/message` 事件折叠，而 goal 生命周期状态位于投递接口之外。空闲注入会保持待处理，不打开轮次也不运行模型；后续会唤醒的投递在 pre-step 将其放入进入步骤的批次时，它才成为 `user/message`。
 
 `wakeup` 是“模型是否应当运行”的信号，因此 inbox 会区分能唤醒的排队工作与任何可领取的项：一个孤立的 `next-turn`/no-wakeup 队列项会停泊在空闲状态，并随下一次唤醒 send 一同带出，而 `whenIdle`/`cancel` 依据唤醒信号来结算完全停稳。每次插入与退出都会发布对应的实时通知，特定于领域的持久事实则通过类型化消息 source 传递，而非通过平行的元数据通道。直接使用待处理消息的表示方式，使持久 splice 与实时事件保持可关联，既无需维护第二个 steering 包装层，也避免数据发生分歧。后续的[已领取 pre-step inbox 生命周期](2026-07-31-claimed-pre-step-inbox-lifecycle.md)决策保留通过 `MessageId` 寻址的实时队列变更，并把单消息生命周期通知与持久的整体队列 splice 投影分离。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
index 09f0c27732..0c59d69ead 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
 2026-07-23-toolview-dissolution.md: be1bd9d161714194855988d76a632c667fae8c84
-2026-07-23-toolview-dissolution.zh.md: afe5e03e8345fca2a0f097d86873974f6d417ff2
+2026-07-23-toolview-dissolution.zh.md: c3f301002aac4c443dedc76fa747d8b45be6577a
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
index afe5e03e83..c3f301002a 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-23-toolview-dissolution.md) | 中文
 
-> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md)所有。后续的 [Client Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)决策仅取代本篇的 per-view 放置方式：Tool 名称分发仍使用 keyed slot，而非平行注册表。
+> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 所有。后续的 [Client Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md) 决策仅取代本篇的 per-view 放置方式：Tool 名称分发仍使用 keyed slot，而非平行注册表。
 
 ## Problem
 
@@ -14,15 +14,15 @@ Status: implemented
 
 工具环作为独立基础设施已消失：工具行是**各视图为自己声明的 keyed 子槽**，client 全域只剩一种注册模型。上述理由是空的——keyed slot 的 *key 空间*本就运行时开放（SlotMap 声明槽、从不声明 key；ask-user composer 的 `key: 'question'` 即先例），开放的 tool 名集合天然适配 `entryKey` 分发。
 
-本决策最初把 `'conversation.chat.toolview'` 放在 chat 条目下，由 chat 渲染点逐行分发。后续的 [Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)引入整体 Tool 席位，并让 `ui-tool` 拥有唯一的 keyed `'tool.call.toolview'` 子 slot。后续决策改变的是展示所有者，而非本决策的核心约束：Tool 注册继续使用普通 keyed-slot 机制，激活、替换、缓存、错误隔离、版本与 fallback 行为仍归框架所有。
+本决策最初把 `'conversation.chat.toolview'` 放在 chat 条目下，由 chat 渲染点逐行分发。后续的 [Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md) 将该放置方式移入整体 Tool 席位，并让 `ui-tool` 拥有一个 keyed `'tool.call.toolview'` 子 slot。后续决策改变的是展示所有者，而非本决策的核心约束：Tool 注册继续使用普通 keyed-slot 机制，激活、替换、缓存、错误隔离、版本与 fallback 行为仍归框架所有。
 
 ## 接受的语义变化
 
-四项行为增量是刻意接受而非疏漏。跨视图出场最初采用逐视图注册；后续 Note 记录了 root/subcall 编排为何足以支持一个 Tool 级展示所有者。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
+四项行为增量是刻意接受而非疏漏。跨视图出场最初采用逐视图注册；后续 Note 记录了为何 root/subcall 编排后来证明由一个 Tool 级展示所有者统一负责是合理的。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
 
 ## Alternatives considered
 
-**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——展示所有权归显式声明的子 slot，会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。
+**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——展示所有权归显式声明的子 slot，会话维归已持有标配 kit 的组件内部。剩下的只是一份没有任何独有能力的 slot 机器副本。
 
 **把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：Tool 展示是 Client UI 词汇；上提进 runtime 会把展示概念泄漏进数据对象层，且依然留着两套注册模型。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
index ae7f689398..4be81330b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
 2026-07-24-separate-context-injection-from-turn-execution.md: bb28d96cf1494d94ad7a7d4a4714e536c7072d2f
-2026-07-24-separate-context-injection-from-turn-execution.zh.md: fa9b9275cae67f4d5a34dac8a0236558596ab28f
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 6debc6cf5e8fb7358ca8697fa64f175fb700d991
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
index fa9b9275ca..6debc6cf5e 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -68,7 +68,7 @@ enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。wate
 
 ## 后果
 
-- idle 注入要到后续 pre-step 让它进入步骤后才会对模型可见，并可能被取消或 dispose 丢弃，而其持久 inbox 生命周期仍会保留记录。
+- idle 注入只有在后续 pre-step 接纳它后才会对模型可见，并可能被取消或 dispose 丢弃，而其持久 inbox 生命周期仍会保留记录。
 - 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器会保留这一顺序。
-- 必须影响当前请求的上下文要从 `agent/pre-step` 返回；普通注入只保证由最近的后续边界交付。
+- 必须影响当前请求的上下文要从 `agent/pre-step` 返回；普通注入只支持在最近的后续边界交付。
 - 公共投递契约和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 9c8308be74..7e3c02691b 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
 2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 06fc1005785d9d11b52839f91c3bb4b99cad7d63
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 1319a0d5a4eba4d70b0268605a0957c9a2eca7a9
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 06fc100578..1319a0d5a4 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-25-web-client-session-scope-and-provide-channel.md) | 中文
 
-> 范围：client Agent scope（actx）与定向事件、client/host 实体化对等模型、空会话 blank 位与复用（`connectWorkspace`）、per-session 供数通道（`sessions.provide`），以及承载这些能力的 host wire 小件（summary `blank` 列、`host/session-added` 帧字段、`host/commands-changed` 帧）。输入状态机与 slash 管线见[输入状态机 note](2026-07-25-web-input-machine-and-slash-pipeline.md)；命令业务面见[命令业务面 note](2026-07-25-web-command-surfaces-and-assembly.md)。
+> 范围：client Agent scope（actx）与定向事件、client/host 实体化对等模型、空会话 blank 位与复用（`connectWorkspace`）、逐会话供数通道（`sessions.provide`），以及承载这些能力的 host wire 小件（summary `blank` 列、`host/session-added` 帧字段、`host/commands-changed` 帧）。输入状态机与 slash 管线见[输入状态机 note](2026-07-25-web-input-machine-and-slash-pipeline.md)；命令业务面见[命令业务面 note](2026-07-25-web-command-surfaces-and-assembly.md)。
 
 ## 问题
 
@@ -74,7 +74,7 @@ Session 实例与 scope 同生命周期，存活资格 = host listed（一个判
 
 `workspaces.connectWorkspace(workspaceId): Promise<SessionId>`（归属 WorkspacesService——它同时持有 workspace 规范 path 与 sessions 引用）：
 
-- 复用臂：list mirror 中找 `blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd。没有账户槽位的 cwd 匹配（CLI/TUI 在 host cwd 创建的会话，或已删除/重建的注册）会打开一个任何分组表面都无法显示在该工作区下的会话，因此落到新建臂（见[成员复用修复](../bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md)）；命中直接返回该 id，不新建。
+- 复用臂：list mirror 中找 `blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd。没有账户槽位的 cwd 匹配（CLI（命令行界面）/TUI 在 host cwd 创建的会话，或已删除/重建的注册）会打开一个任何分组表面都无法显示在该工作区下的会话，因此落到新建臂（见[成员复用修复](../bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md)）；命中直接返回该 id，不新建。
 - 新建臂：未命中则 `session.create({workspaceId})`，返回新 id。
 - 未知 workspaceId fail loud（不静默创建到别处）。
 - 解析保证（两臂同契约）：promise resolve 时返回的 id 已在 list store 且 `sessions.binding(id)` 同步可解析——`SessionsService.create` 在 RPC 成功后同步投影列表再 resolve，使 draft 搬运方可以在 open 之前往新 scope 的 machine 写文本，不等 notifier flush。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 9994bcb3b9..1f44d8b4b7 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
 2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
-2026-07-27-dispose-ladder-to-consumer.zh.md: 89f8e107c56d42787c59bc6f8fa8fc7b3ef73208
+2026-07-27-dispose-ladder-to-consumer.zh.md: 74cbc624e9153637dcdceb521c04af811799fdb0
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 89f8e107c5..74cbc624e9 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程责任方证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
+阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程所有者证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的完全停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
 
 ## 曾考虑的替代方案
 
@@ -20,4 +20,4 @@ Status: implemented
 
 ## 后果
 
-买到的：seam 少了一个方法和一个类型；实现只欠四个动词，不欠拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程责任方拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
+换来的是：seam 少了一个方法和一个类型；实现只需提供四个动词，无需提供拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程所有者拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
index 92a30e931c..fd4c24db70 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
 2026-07-29-dsh-source-launch-tsx-esm.md: aabe6c2d6a92b5cc6568eee1d42df3a6998cf0ca
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: fdeb8a976e02bb9311a6ec9d097d09151a998a04
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: ecda8b273b3efc4773dbe3ed25a9ef0572b79ce4
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
index fdeb8a976e..ecda8b273b 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-29-dsh-source-launch-tsx-esm.md) | 中文
 
-> 取代[已归档的原生 TypeScript 源码启动](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md)：Node 移除了该决策所依赖的能力。
+> 取代[原生 TypeScript 源码启动](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md)：Node 移除了该决策所依赖的能力。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index 5524e0d54d..ae2347a7be 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
 2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
-2026-07-29-request-level-llm-config-credentials.zh.md: b0d04d4303bf0ccf5ebc74af8c4a3e493f861d63
+2026-07-29-request-level-llm-config-credentials.zh.md: b2075798c9eb77d8fd8baecbbea77993ccda328f
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index b0d04d4303..b2075798c9 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **按请求解析，而非重建 fiber。**适配器改为接收一个 options thunk（外加按流调用的凭据解析器），不再持有冻结的构造期事实，每个操作解析一次——即 Pi 的模式，连同其经测试固定的语义：跨越一次变更的两个请求看到两份配置，一个请求恰好解析一次，进行中的流保持其起始事实。这删掉了重建式设计所需的整套切换机制（`DUPLICATE_ADAPTER` 顺序问题、`NO_ADAPTER` 窗口、延迟激活状态机），并把密钥缺失变成*请求时*可行动的失败（`MISSING_CREDENTIAL` 点名每个配置入口），同时路由保持注册、catalog 保持可浏览。唯一在注册期捕获的事实——`ctx.llm` 注册表在 `registerAdapter` 时快照的重试策略（外加 pi-ai 的路由*集合*）——在其变化时于一个同步区段内原地重新注册同一适配器实例。
 
-**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在 provider 管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器通过 seam 解析该引用；仅在未挂载 seam 时，才通过各环境层解析。
+**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在提供方管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器通过 seam 解析该引用；仅在未挂载 seam 时，才通过各环境层解析。
 
 **按插件划分 namespace，schema ≡ `Config`。**每个适配器注册自己的 namespace（`llm-deepseek`、`llm-pi-ai`），schema 用其插件 `Config` schema，组合 `base` 用其 `cordis.yml` 条目——settings 分节与 entry 配置是同一种 YAML 形状，`resolveAdapterOptions`/`resolveProfiles` 对两者仍是唯一的显式 resolve 步骤。存活快照若违反 schema 之外的约束，则保留最后可用事实（seam 的最后可用值哲学向上延伸一层）；entry 配置本身仍会加载失败。pi-ai 的 `providers` 改为以路由为键的字典，base 层与用户层因此按提供方合并，路由集合也由结构直接表达；数组形状响亮失败并给出迁移指引，而空字典是合法的休眠姿态——组合可以裸挂该适配器，把每一条路由都留给用户面决定。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 4becd41658..15189e7387 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
 2026-07-30-credential-boundaries-and-atomic-registration.md: 94b32c3cfaa3e1c5059573881a2f393d29aed3ac
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2506ce391c9125323faf107e3c04c52785e0cc98
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 088e24cbfd7db9da73c2ed3e3d11fdef24249c37
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 2506ce391c..088e24cbfd 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 决策
 
-**凭据文档只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。当时该文档是 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，因此如今被加载的正是那条旧路径——作为用户的普通环境层，其中不含任何 provider 管理的密钥。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
+**凭据文档只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。当时该文档是 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，因此如今被加载的正是那条旧路径——作为用户的普通环境层，其中不含任何提供方管理的密钥。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
 
 **存下的凭据对模型没有边界，而 README 就是这么写的。**`0700` 目录下的 `0600` 挡得住其他 OS 用户；模型的 bash 与文件系统工具正是以同一用户身份运行，而已交付的默认值不约束任何东西。harness 真正守住的更窄，也就照这个宽度写下来：没有任何一个面会把该文档提升进 `process.env`，模型也从不会拿到它的解析后路径，因此要拿到这个值，需要刻意去读一条并未交给它的路径。OS 钥匙串（keychain）提供方——一个模型的进程根本读不到的存储——被记录为真正的答案，而不是靠一个残缺的方案去暗示它。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 1c04f72d28..6c9f7d8ce0 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
 2026-07-30-web-config-plane.md: 483058c8a24ad8c414278eba84f4226e973f2923
-2026-07-30-web-config-plane.zh.md: 9247aac52401cd570d37f4aad47d9da6bb194d19
+2026-07-30-web-config-plane.zh.md: 840ac7f2e46c82e7b858c353086e1a9541db563e
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index 9247aac524..840ac7f2e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -12,7 +12,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 ## 决策
 
-**wire 领域挂上编译期 RPC 映射，拒绝落为错误码，失效落为帧。**`settings.describe/openDocument/update/replace/mutate`、`credentials.describe/set/unset`、`llm.providers` 与 `llm.models`（认领预留的 `host.listModels` 面）一同加入 `RpcMethodMap`，七处由编译器锁定的接线位点因此让契约、schema、处理器与客户端保持步调一致。seam 侧的拒绝折叠为 `settings-rejected {ns}`/`credential-rejected {ref}` 业务错误（HTTP 仍只是载体），三个 `HostFrame`——`host/settings-changed {ns}`、`host/credentials-changed {ref}`、`host/models-changed`——沿用 `host/commands-changed` 的形状，因此每个客户端都无需轮询即可收敛。settings 读取、原生操作与写入和 `pickDirectory`/`openPath` 一起进入连接守卫的特权集合：回环 + 同源，否则 403，因为暴露在局域网上的 dsh web 绝不能接受来自其他源的配置访问。
+**wire 领域挂上编译期 RPC 映射，拒绝落为错误码，失效落为帧。**`settings.describe/openDocument/update/replace/mutate`、`credentials.describe/set/unset`、`llm.providers` 与 `llm.models`（认领预留的 `host.listModels` 面）一同加入 `RpcMethodMap`，七处由编译器锁定的接线位点因此让约定、schema、处理器与客户端保持步调一致。seam 侧的拒绝折叠为 `settings-rejected {ns}`/`credential-rejected {ref}` 业务错误（HTTP 仍只是载体），三个 `HostFrame`——`host/settings-changed {ns}`、`host/credentials-changed {ref}`、`host/models-changed`——沿用 `host/commands-changed` 的形状，因此每个客户端都无需轮询即可收敛。settings 读取、原生操作与写入和 `pickDirectory`/`openPath` 一起进入连接守卫的特权集合：回环 + 同源，否则 403，因为暴露在局域网上的 dsh web 绝不能接受来自其他源的配置访问。
 
 **`describe()` 增加分层与结构化 secret 脱敏。**`SettingsDescriptor` 在生效值之外携带 `base`/`user`，表单据此按「字段是否出现在用户层」来标记「已覆盖」，而非按值是否不等（与 base *相等*的覆盖仍然是覆盖）。`describe({ redactSecrets: true })`——在每个 wire 面都强制启用——经由对 schema 的纯结构遍历（object/dict/array 容器；secret 角色子树整体是一个不透明叶节点）从全部三层剥除 `role('secret')` 子树，并把剥除的槽位枚举为 `{path, set}`，页面因此不必收到任何值就能渲染只写输入框。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
index 2ede6629d7..2930ae70e4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md
 2026-07-21-compaction-summary-prefix-cache-reuse.md: fb6524846f837b783423b3ed0e043cd4e1f7849d
-2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: e6072313b7089b9dda14c298fcb94db786220501
+2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: 96adc31d6d6c50b4e6bfee32a5b89388a33a6939
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
index e6072313b7..96adc31d6d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
@@ -42,4 +42,4 @@ Status: implemented
 
 - **单元：** `compact-basic.spec.ts` 断言辅助调用转发 `system`/`tools`/前导消息，并把压缩指令作为最后一条消息追加，且 `compactRegion` 回放最新的已路由 header 前缀。现有的内容断言通过回放的消息而非 transcript 字符串来读取摘要器输入。
 - **循环：** `compact-loop-repro.spec.ts` 依据摘要请求尾部 user 消息中的压缩指令对其分类，溢出恢复测试则继续在真实循环中固定对话请求与摘要请求的数量。
-- **快照：** 无密钥回放会从带标记的 `compact/summary` 重建一条规范成功流；[compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 负责持久标记契约。
+- **快照：** 无密钥回放会从带标记的 `compact/summary` 重建一条规范成功流；[compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 负责持久标记约定。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
index 3021149a93..05d9cfd033 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md
 2026-07-21-semantic-session-checkpoints.md: 697d878dccbfab1ded9f73e134d594ba6f0665e1
-2026-07-21-semantic-session-checkpoints.zh.md: c6184b0b00db16f9e318f4cbd148b1f0525f03a5
+2026-07-21-semantic-session-checkpoints.zh.md: e4d432cfa4655fcf6b010ab944dc12095eca009c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
index c6184b0b00..e4d432cfa4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`dsh-session-checkpoint-policy` 以零配置插件的形式与持久化后端共同加载，并负责语义持久性屏障。在 `agent/pre-step` 时，该插件会在推导下一个请求前刷新待持久化的提示词输入或前一批响应/结果。该插件惰性包装 `llm/stream`，在记录 `request/header` 之后、构造适配器流之前，刷新活动会话。该插件还在有序的执行前策略之后包装顶层 `tools/execute`，在进入工具主体前刷新已记录的 `tool/call`；嵌套分发则复用外层模型可见调用。循环的最终 `turn/end` 检查点仍是轮次的收尾边界，并会在处理另一个已排队轮次或观察到空闲状态之前完成。
+`dsh-session-checkpoint-policy` 以零配置插件的形式与持久化后端共同加载，并负责语义持久性屏障。在 `agent/pre-step` 时，该插件会在推导下一个请求前刷新待持久化的提示词输入或前一批响应/结果。该插件惰性包装 `llm/stream`，在记录 `request/header` 之后、构造适配器流之前，刷新当前会话。该插件还在有序的执行前策略之后包装顶层 `tools/execute`，在进入工具主体前刷新已记录的 `tool/call`；嵌套分发则复用外层模型可见调用。循环的最终 `turn/end` 检查点仍是轮次的收尾边界，并会在处理另一个已排队轮次或观察到空闲状态之前完成。
 
 持久化与检查点调度仍是相互独立的 Cordis 插件。后端使请求的 `session/flush` 边界持久化，但不选择边界；只加载后端而不加载本策略仍是有效组合，并保留循环提供的较粗检查点。第一方持久化应用与运行时会显式加载两者，专用部署则可以有意省略或替换本策略。注册顺序决定其他 `agent/pre-step` 监听器追加的事件是否先于本检查点；提示词输入以及前一批由循环自身记录的助手消息与有序结果都已在日志中。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index bc05e497c5..684b2510f0 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-15-code-mode.md
 2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: ca1bbe9ed3e412186763d1ed4fca9ed06669d4c3
+2026-06-15-code-mode.zh.md: d6f0887f421296818b6bba7a26fc662c246cc28a
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index ca1bbe9ed3..d6f0887f42 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -48,7 +48,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
 
-**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 契约相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 约定相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
 **呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
 
@@ -85,7 +85,7 @@ worker 运行时只能约束程序的运行，而不构成安全边界：模型
 
 ### 模型看到的内容
 
-SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一契约：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
+SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一约定：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 1917b118da..230bcb69f5 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
 2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
-2026-06-18-compaction-capability-seam.zh.md: d72793e6adde911a8623ac1c6b65df899381923e
+2026-06-18-compaction-capability-seam.zh.md: 59eb899acae0352a019cfc5252365e0116f84597
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index d72793e6ad..59eb899aca 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -33,7 +33,7 @@ Status: implemented
 
 早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
-`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
+`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV Cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
 ### 成功的持久步骤工作完成后运行自动压力检查
 
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
index 0369670aea..f17347689c 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-24-workspace-context.md
 2026-06-24-workspace-context.md: 53a580aee50752b7c6daeff5caa42ba6409c8885
-2026-06-24-workspace-context.zh.md: dc1d6b5dc2c9f576e7298c891a3a1145f123a8db
+2026-06-24-workspace-context.zh.md: 79e5b0014801878595d3a5d71b8c4b23c5aad996
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
index dc1d6b5dc2..79e5b00148 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-该实现在 `packages/context/workspace-context` 中，包（package）名为 `@deepseek-ai/dsh-workspace-context`。它是请求上下文扩展，不是核心服务或文件系统后端。共享 demo 主干与 Host Runtime 根据显式的 `{ maxBytes } | false` 部署选择挂载它；`dsh web` 启用 65,536 字节预算，Host Runtime 的 headless 消费方则禁用它。该插件使用 `agent/pre-step`、不可变的 `tools/result` 结果、`session/event` 边界和可选的 `ctx.fs` 功能。
+该实现在 `packages/context/workspace-context` 中，包名为 `@deepseek-ai/dsh-workspace-context`。它是请求上下文扩展，不是核心服务或文件系统后端。共享 demo 主干与 Host Runtime 根据显式的 `{ maxBytes } | false` 部署选择挂载它；`dsh web` 启用 65,536 字节预算，Host Runtime 的 headless 消费方则禁用它。该插件使用 `agent/pre-step`、不可变的 `tools/result` 结果、`session/event` 边界和可选的 `ctx.fs` 功能。
 
 插件不会静态注入 `fs`。因此，不带提供方的产品树仍能正常启动；在文件系统提供方出现之前，插件保持无操作。所有生产读取都通过该提供方完成。候选项探测会解析每个路径并对结果执行 stat，因此会跟随最终路径组件的符号链接至其目标：指向普通文件的链接会被加载，缺失路径或非文件目标则确认为不存在。允许仓库拥有的链接跨越信任边界，是对最初不跟随探测方式的刻意反转；[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明该决策及其残余风险。步骤信号与动态工具执行信号会贯穿解析、元数据探测和流式读取，因此取消不会等待无关的文件系统扫描。解析或 stat 异常归类为不可用：它只跳过该候选项，绝不被解释为已经加载的作用域被删除。
 
@@ -78,7 +78,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 ## 后果
 
-工作区指引按会话隔离，并由 demo 入口、Web Host 与每一种工具展示模式共享。初始、嵌套与变更指令都保持持久且可回放。通用的会话／agent 上下文契约通过先在 inbox 中暂存、再持久进入的 user 消息携带带类型的来源数据，而不会把条目展平。
+工作区指引按会话隔离，并由 demo 入口、Web Host 与每一种工具展示模式共享。初始、嵌套与变更指令都保持持久且可回放。通用的会话／agent 上下文约定通过先在 inbox 中暂存、再持久进入的 user 消息携带带类型的来源数据，而不会把条目展平。
 
 仓库文本仍是不受信任的输入。低权威 user 角色框架、显式优先级说明和分隔符转义可以降低风险，但无法消除提示词注入。跟随候选符号链接到目标，会把该攻击面扩大至树外内容；因此，把 `ctx.fs` 限制在可信根目录内的权限与沙箱层才是真正的边界，它们让系统把工作区文件当作数据而不是权威（[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明残余风险）。
 
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index 5ea74ca411..fa5b21ccac 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
 2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
-2026-06-29-todo-write-tool.zh.md: 1f797c5517df8affd66addecf2a8db43c1da3332
+2026-06-29-todo-write-tool.zh.md: 5efcaf1f6e7ea69b1dd8cd0fd31b9cbd931666db
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 1f797c5517..5efcaf1f6e 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体），包括 claude-code、opencode、codex、oh-my-pi 和 pi，都提供了某种形式的此功能；本 harness 此前没有。
+harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃工作明确；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体），包括 claude-code、opencode、codex、oh-my-pi 和 pi，都提供了某种形式的此功能；本 harness 此前没有。
 
 ## 决策
 
@@ -34,7 +34,7 @@ claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）
 
 ### 校验：低成本的中间路线
 
-schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，并在 `allowParallelInProgress` 为 `false` 时拒绝超过一个活跃任务。排序和保持列表最新仍通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。必填的部署策略及持久日志不变式独立于该策略这一约定，由[并行 in-progress Agent Note](2026-07-26-todo-parallel-in-progress.md) 负责。
+schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，并在 `allowParallelInProgress` 为 `false` 时拒绝超过一个活跃任务。排序和保持列表最新仍通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。必须采用的部署策略，以及持久不变式独立于该策略这一点，均由[并行 in-progress Agent Note](2026-07-26-todo-parallel-in-progress.md)负责。
 
 ## 为何没有 cordis-catalog 条目 / 没有 `@mode`
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
index 3b7a2c32a6..de978c055c 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-bridges.md
 2026-06-30-hook-bridges.md: a31116818c57e18d04e656f371efd1101a63b6af
-2026-06-30-hook-bridges.zh.md: 8827408b67e2dd19f867a8658309f00231ba06c5
+2026-06-30-hook-bridges.zh.md: 0fa76c0cee0f74101e70f44d442daa2fb46e6649
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
index 8827408b67..0fa76c0cee 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
@@ -37,7 +37,7 @@ CC 桥接的 `ask` 结果是一条真正的权限路径，而非终态桥接决
 
 每个桥接的 `inject()` 和 additional-context 输入都显式传入 `{ kind: 'plugin', plugin: 'hooks-claude' | 'hooks-codex' }`。单元测试固定验证结果中的 `user/message.source` 为插件而非用户。
 
-`UserPromptSubmit` 在 `turn/start` 之后的 pre-step 运行，因此每次调用都会写入轮次范围的 `hook/invoked` / `hook/result` 对。reject 会让已领取输入保持删除，将轮次关闭为 blocked 且不包含步骤，并保留该 hook 对作为持久决策证据。Codex payload 会收到这个已打开轮次的 `turn_id`。
+`UserPromptSubmit` 在 `turn/start` 之后的 pre-step 运行，因此每次调用都会写入轮次范围的 `hook/invoked` / `hook/result` 对。拒绝会使已领取的输入维持移除状态，将轮次关闭为已阻止状态且不包含步骤，并保留该钩子对作为持久决策证据。Codex payload 会收到这个已打开轮次的 `turn_id`。
 
 ### 添加上下文不是否决——先 delegate，再 prepend
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index 4a599f3310..9a76a6024c 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
 2026-06-30-hook-protocol-lib.md: 2edff0d501cd7695873c68054eeb3a1e9942eced
-2026-06-30-hook-protocol-lib.zh.md: 42e526fdf8073465d5f6faf99a6c92fbe09505f5
+2026-06-30-hook-protocol-lib.zh.md: e9ae51f5d7697017ecc153866bbb8c3f6fd34eb6
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index 42e526fdf8..e9ae51f5d7 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 - **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
 
-**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 无替换（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
+**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 两者皆无（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
index 536f913800..3975b65602 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md
 2026-07-16-durable-per-step-time-context.md: e1a5c65894913ad93f46db8ae45e5ef5ead215f3
-2026-07-16-durable-per-step-time-context.zh.md: 9cbf653f5d43060e99502b640eed7907ffbd3840
+2026-07-16-durable-per-step-time-context.zh.md: d353d2b4535cd2f6153adad084b4ca056f68dc8c
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
index 9cbf653f5d..d353d2b453 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 分组容纳有界的请求上下文增强，这些增强既不定义工具也不定义服务；已交付示例不挂载此插件，因为时区披露与 token 成本属于部署策略。它注册一个前置的 `agent/pre-step` 监听器；需要读数且下游决策 enter 时，返回一条额外的 `UserMessage`。该消息携带来源 `{ kind: 'plugin', plugin: 'time-context' }`；受间隔抑制、reject 或失败的尝试不会追加任何内容。
+`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 分组容纳有界的请求上下文增强，这些增强既不定义工具也不定义服务；已交付示例不挂载此插件，因为时区披露与 token 成本属于部署策略。它注册一个前置的 `agent/pre-step` 监听器；当应生成读数且下游决策为进入时，返回一条额外的 `UserMessage`。该消息携带来源 `{ kind: 'plugin', plugin: 'time-context' }`；被抑制、被拒绝或失败的尝试不会追加任何内容。
 
-监听器在 `step/start` 之前采样，并只在最终 enter 决策中结算读数。AgentLoop 会在 `step/start` 之后、请求派生之前记录它。因此，下游 reject 或失败会阻止读数进入持久历史。
+监听器在 `step/start` 之前采样，并仅在最终决定进入时确定该读数。AgentLoop 会在 `step/start` 之后、请求派生之前记录它。因此，下游拒绝或失败会阻止读数进入持久历史。
 
 省略可选配置 `timeZone` 时，插件在加载时解析一次 Node 进程的 IANA 时区；显式值由 `Intl.DateTimeFormat` 校验。时间戳包含数字 UTC 偏移和解析后的 IANA 时区。
 
@@ -44,7 +44,7 @@ Elapsed since the preceding step context: <duration-or-unavailable>.
 
 每个读数都作为普通表层节点保留，直至压缩将其隐藏；正数间隔调度绝不会移除已有读数。因此，后续请求会看到影响先前准备过程和步骤且尚未被隐藏的累计读数，而不是一个被原地改写的系统提示词值。
 
-插件不向系统提示词组装贡献任何内容。`request/header` 不包含时间上下文文本；请求重建从每个 `step/start` 取得完整的持久表层前缀。读数与请求无需一一对应，因为间隔抑制可以让请求进入步骤而不追加读数，reject 或失败则两者都不追加。插件通过 agent 注册表使用生命周期监听器，运行时不需要系统提示词服务。
+插件不向系统提示词组装贡献任何内容。`request/header` 不包含时间上下文文本；请求重建从每个 `step/start` 取得完整的持久表层前缀。读数与请求无需一一对应，因为间隔抑制可以让请求进入步骤而不追加读数，拒绝或失败则两者都不追加。插件通过 agent 注册表使用生命周期监听器，运行时不需要系统提示词服务。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
index 60cf540d45..689b04ef55 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-human-goal-command.md
 2026-07-19-human-goal-command.md: 5fdd80f7423b80e84e58f7379130ee59a2e8a723
-2026-07-19-human-goal-command.zh.md: 74dd0a2bec923687c91ddf4ce7efe4cc5b25bfc9
+2026-07-19-human-goal-command.zh.md: 841e7195454b2e0cfc6f74fb28369022b84c5780
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
index 74dd0a2bec..841e719545 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
@@ -34,7 +34,7 @@ Status: implemented
 
 预期的 `GoalError` 失败会变为一个稳定且不含品牌化 id 的 `CommandResult.error`，使领域诊断不会向面向人类的界面泄露比较并交换内部细节，非法操作也绝不会进入模型历史。当前状态负责提供针对具体状态且可执行的恢复路径。其他异常仍是适配器可见的命令失败；若把程序缺陷当成普通领域错误，就会隐藏问题。命令处理器只执行同步领域变更，因此请求取消会在变更开始前由命令注册表决定，不存在需要回滚的外逸异步副作用。
 
-通用斜杠输入、状态文本与错误不会持久化。成功的 goal 变更会追加领域自有的 `goal/change` 事件，而且不会把模型上下文排队。该命令不会引入可能与领域事件不一致的第二份审计记录。
+通用斜杠输入、状态文本与错误不会持久化。成功的目标变更会追加领域自有的 `goal/change` 事件，而且不会将模型上下文加入队列。该命令不会引入可能与领域事件不一致的第二份审计记录。
 
 ### 应用组合
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
index 14c92dfce8..578218ce21 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
 2026-07-19-persisted-same-session-goal-domain.md: ce93a652f3910912fbf6afc28061de4d13eb2de2
-2026-07-19-persisted-same-session-goal-domain.zh.md: 7fb8dc3a6c76b91e0abf495782d51b30d3cd5b53
+2026-07-19-persisted-same-session-goal-domain.zh.md: ddb4fdedafbacbfec355a7a1c912a5f9545e208a
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
index 7fb8dc3a6c..ddb4fdedaf 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
@@ -18,9 +18,9 @@ Status: implemented
 
 ### 持久记录与回放
 
-每次变更都会追加带版本的 `goal/change` 会话事件，其中包含完整快照；clear 则包含带修订号的墓碑。会话日志是唯一的持久真源，因此持久化和 fork 会继承 goal 记录，而无需另设数据库或头字段。[Goal 自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)负责 goal 状态与 inbox 状态、模型上下文之间的职责分离。
+每次变更都会追加带版本的 `goal/change` 会话事件，其中包含完整快照；清除时则包含带修订号的墓碑。会话日志是唯一的持久真源，因此持久化和 fork 会继承目标记录，而无需另设数据库或头字段。[目标自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)负责将目标持久事件与收件箱状态和模型上下文分离。
 
-回放折叠只从 `goal/change` 派生生命周期变更，并校验 JSON 形状、新 id、修订连续性、生命周期转换、计数器以及单个 goal 内单调递增的时间戳。只有当前活跃修订上带正数且连续编号、已准入的 `user/message` 来源才会推进 Goal Round，且不能超过 `maxGoalRounds`；普通会话轮次不会影响该计数器。当前格式的畸形记录会使回放失败，而不会被忽略或修复。
+回放折叠只从 `goal/change` 派生生命周期变更，并校验 JSON 形状、新 id、修订连续性、生命周期转换、计数器以及单个目标内单调递增的时间戳。只有当前活跃修订上带正数且连续编号、已接纳的 `user/message` 来源才会推进 Goal Round，且不能超过 `maxGoalRounds`；普通会话轮次不会影响该计数器。当前格式的畸形记录会使回放失败，而不会被忽略或修复。
 
 增量回放会在每个有效事件后推进游标，并停留在首个损坏事件处，因此后续读取会报告同一个持久故障。重启后仍以持久日志为准。
 
@@ -36,12 +36,12 @@ Status: implemented
 
 ## 测试
 
-单元测试固定创建默认值、精确实时 agent 校验、比较并交换拒绝、所有生命周期转换、阻塞原因校验与保留、恢复时的上限执行、清除与替换、种子回放和 `SessionStore.fork()` 继承、会话启动与生命周期所有者解除激活、活跃目标重新激活、持久事件折叠、inbox 独立性、损坏事件的稳定回放、服务与监听器销毁、监听器隔离、挂钟后退钳制、严格记录解码、生命周期连续性，以及连续 Goal Round 归属。无密钥 Loader/stdio 进程测试通过测试专用 `cordis.yml` 挂载服务与生命周期消费方，再从外部读取持久 JSONL，以验证 goal 记录以及不存在未经请求的 Goal Round。包源码受仓库逐文件 100% 覆盖率门禁约束。
+单元测试固定创建默认值、精确实时 agent 校验、比较并交换拒绝、所有生命周期转换、阻塞原因校验与保留、恢复时的上限执行、清除与替换、种子回放和 `SessionStore.fork()` 继承、会话启动与生命周期所有者解除激活、活跃目标重新激活、持久事件折叠、收件箱独立性、损坏事件的稳定回放、服务与监听器销毁、监听器隔离、挂钟后退钳制、严格记录解码、生命周期连续性，以及连续 Goal Round 归属。无密钥 Loader/stdio 进程测试通过测试专用 `cordis.yml` 挂载服务与生命周期消费方，再从外部读取持久 JSONL，以验证目标记录以及不存在未经请求的 Goal Round。包源码受仓库逐文件 100% 覆盖率门禁约束。
 
 ## 考虑过的替代方案
 
 - **把目标存入独立数据库或会话头**——不予采纳，因为会话日志已经提供顺序、持久化、fork 前缀与可重建性；第二份存储会引入原子性和谱系问题。
-- **把每次持久变更与排队的模型上下文绑定。** 后续的 [Goal 自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)不采用这一方案：goal 工具与已调度的继续执行提示词会在需要时暴露状态，而领域持久化不依赖队列结果。
+- **把每次持久变更与排队的模型上下文绑定。** 后续的 [Goal 自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)不采用这一方案：目标工具与已调度的继续执行提示词会在需要时暴露状态，而领域持久化不依赖队列结果。
 - **持久化激活态并自动重启**——不予采纳，因为打开或恢复会话时必须等待人类输入；持久阶段记录状态，而不是再次消耗资源的授权。
 - **把所有会话轮次都计为 Goal Round**——不予采纳，因为同一会话可以包含人类澄清、检查和无关工作；只有归属于目标的继续执行轮次才消耗该预算。
 - **向 `dsh-agent-loop` 添加目标状态或通用循环抽象**——不予采纳，因为状态与继续执行策略可以通过现有插件、`Agent` 动词和事件组合，而无需赋予默认循环实现特权。
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
index 2f06720c93..4fd53a1941 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
 2026-07-19-same-session-goal-round-driver.md: a989b9d3487ebbf8ff11a4e34cb08029f1e4ace4
-2026-07-19-same-session-goal-round-driver.zh.md: b49a759c8f3577db30b8ab45449bb7faed85a7da
+2026-07-19-same-session-goal-round-driver.zh.md: 309b5ce45c2edb516a329f9992cea5558a2aeb8c
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
index b49a759c8f..309b5ce45c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
@@ -20,15 +20,15 @@ Status: implemented
 
 ### 预留与接纳
 
-当 agent 空闲、没有竞争中的排队工作，且当前目标为 `active` 加 `armed` 时，驱动器会先检查点持久化待处理的目标变更，并在等待之后重新校验所有条件。若 `roundsStarted` 已等于 `maxGoalRounds`，它会记录代码为 `round-limit` 的 `blocked`；否则，它会先预留精确身份 `{ goalId, revision, round: roundsStarted + 1 }` 和完整渲染提示词，再以 `GoalMessageSource` 调用 `Agent.followup()`。提示词用 JSON 引号编码目标描述，使多行或类似标签的文本在熟悉框架中仍是无歧义的数据值。
+当 agent 空闲、没有竞争中的排队工作，且当前目标为 `active` 加 `armed` 时，驱动器会先将待处理的目标变更持久化到检查点，并在等待完成后重新校验所有条件。若 `roundsStarted` 已等于 `maxGoalRounds`，它会记录代码为 `round-limit` 的 `blocked`；否则，它会先预留精确身份 `{ goalId, revision, round: roundsStarted + 1 }` 和完整渲染提示词，再以 `GoalMessageSource` 调用 `Agent.followup()`。提示词用 JSON 引号编码目标描述，使多行或类似标签的文本在熟悉框架中仍是无歧义的数据值。
 
-`agent/pre-step` 瀑布是进入栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会进入步骤。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步监听器编辑或暂停目标后，旧提示词仍进入步骤。
+`agent/pre-step` waterfall（瀑布式事件）是进入栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会进入。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步监听器编辑或暂停目标后，旧提示词仍会进入。
 
-只有最终产生的 `user/message` 才是进入步骤的目标回合，并推进目标折叠。陈旧预留会关闭一个 blocked 的无步骤轮次；驱动器会把它标记为陈旧，不消耗回合数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
+只有最终产生的 `user/message` 才是已进入的目标回合，并推进目标折叠。陈旧预留会关闭一个被阻塞的零步骤轮次；驱动器会把它标记为陈旧，不消耗回合数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
 
 ### 人类工作与修订竞争
 
-预留的 `MessageId` 会区分驱动器自己的完整记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合的已领取批次会 reject 自动提案。目标回合已经进入步骤后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
+预留的 `MessageId` 会区分驱动器自己的完整记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合的已领取批次会拒绝自动提案。目标回合进入后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
 
 目标在回合内发生变更时会推进持久修订号。旧修订的结算不得覆盖该变更。驱动器会丢弃旧尝试的结果、读取新投影，并且只在新修订仍为 active 与 armed 时继续。因此，模型记录的完成、暂停、阻塞和编辑相对于物理轮次稍后的关闭原因具有最终权威。
 
@@ -53,9 +53,9 @@ Status: implemented
 
 每次 `goal/changed` 通知都会产生一个检查点义务。驱动器在预留工作前等待 `ctx.sessions.flush(session)`，随后检查是否出现了更新的变更、agent 生命周期变化或竞争提示词。轮次结束时的 flush 失败会在 `turn/end` 之后通过现有 `agent/error` 通知报告；即使并发的一次性注入已追加后续轮次，驱动器仍会找到对应的同一个已关闭轮次，把失败关联到对应的同一次尝试，并在下一次空闲决策前解除激活。
 
-广义取消会清除待处理 inbox 工作，并中止活跃 loop 阶段。目标驱动器通过 inbox 的领取／丢弃事件和持久的 aborted 轮次结束来跟踪预留消息。由于轮次现在会在首次领取前打开，取消可以关闭已领取的无步骤尝试；驱动器会把该尝试标记为已取消，并让随后的 idle 边沿暂停目标，与已准入尝试的处理方式相同。没有匹配目标尝试的取消只会移除进程内激活态。若暂停变更抛错，驱动器会回退到解除激活，避免已取消的自动工作重新启动。
+广义取消会清除待处理的收件箱工作，并中止活跃的循环阶段。目标驱动器通过收件箱领取／丢弃事件和持久化的 aborted 轮次结束事件来跟踪预留消息。由于轮次现在会在首次领取前打开，取消可以关闭已领取的零步骤尝试；驱动器会把该尝试标记为已取消，并让随后的空闲边沿暂停目标，与已接纳尝试的处理方式相同。没有匹配目标尝试的取消只会移除进程内激活态。若暂停变更抛错，驱动器会回退到解除激活，避免已取消的自动工作重新启动。
 
-`Agent.cancel()` 仍是唯一的公共广义取消动词。若消费方依赖其顺序，实现该接口的自定义 `Agent` 必须遵守 inbox、轮次结束、status 与完全停稳的顺序。
+`Agent.cancel()` 仍是唯一的公共广义取消动词。若消费方依赖这些顺序，实现该接口的自定义 `Agent` 必须遵守收件箱、轮次结束、状态与完全停稳的顺序。
 
 ### 进程生命周期
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
index e852c240f7..c5d0cab7a1 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
 2026-07-21-cross-session-references.md: b2d428e0937fdd881720720401948a1c3e7ef1f6
-2026-07-21-cross-session-references.zh.md: a59657bfcd46393a5cd1c5a5076a6eddd5d065ff
+2026-07-21-cross-session-references.zh.md: e242e159329a5f1446b08547cd0f176b6c1af3f7
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
index a59657bfcd..e242e15932 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
@@ -26,7 +26,7 @@ TUI 用户需要把另一场对话中的相关工作带入一条新消息，但
 
 ## 消息所有权
 
-TUI 负责快照／直接消息事务，不扩展通用收件箱记录。agent 空闲时，它会在调用 `followup()` 前安装一次性的外层 `agent/pre-step` 监听器；enter 决策会把快照作为另一条消息接收，而 reject 或更早的普通丢弃会释放监听器，并且不写入任何消息。agent 运行时，TUI 会依次调用 `inject(snapshot)` 和 `steer(prompt)`，把两者放入 next-step inbox，等待后续同一次领取。pre-step reject 或失败会让这对已领取消息保持删除；领取后插入的消息继续等待。这一通用交付边界由[上下文分离决策](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md)规定。
+TUI 负责快照／直接消息事务，不扩展通用收件箱记录。agent 空闲时，它会在调用 `followup()` 前安装一次性的外层 `agent/pre-step` 监听器；enter 决策会把快照作为另一条消息接收，而 reject 或更早的普通丢弃会释放监听器，并且不写入任何消息。agent 运行时，TUI 会依次调用 `inject(snapshot)` 和 `steer(prompt)`，把两者放入 next-step inbox，等待后续同一次领取。pre-step reject 或失败会使这对已领取消息维持已移除状态；领取后插入的消息继续等待。这一通用交付边界由[上下文分离决策](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md)规定。
 
 引用准备过程不是新的 steering 协议，本身也不会创建轮次。空闲交付使用 `followup()` 和 pre-step 进入决策；运行期间的交付使用共享 next-step inbox，并保持快照顺序。
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
index 37839002ae..77104f258e 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
 2026-07-24-web-session-model-selector.md: 05e923fb3b5df72485ffb8d6ff5aa0104b19a8a0
-2026-07-24-web-session-model-selector.zh.md: bdfa2f856a799cc86600650829a2df62a7dfdc18
+2026-07-24-web-session-model-selector.zh.md: c1fd59ada0340a984ddf4a9dcc4c357f9609acb1
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
index bdfa2f856a..c1fd59ada0 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
@@ -40,4 +40,4 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm
 
 ## 测试
 
-Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、建议性的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
+Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
index 5f2f7bc9ae..b91d68b90f 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md
 2026-07-28-tool-call-file-open-in-os.md: 499d3caa11e1f2c17d96e43b7846df72a31c0eb1
-2026-07-28-tool-call-file-open-in-os.zh.md: a658a7b55d2575ad1a5d8baccb80f0a8444d6db9
+2026-07-28-tool-call-file-open-in-os.zh.md: f5fdad90041915171dceab33ea77b2187419dc31
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
index a658a7b55d..f5fdad9004 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 文件工具的路径摘要（`read`／`write`／`edit` 参数中的 `path` 或 `file_path`）渲染为静止状态下即带下划线的链接，并使用 pointer 光标。点击路径会经 `WorkspacesService.openPath` 调用 `host.openPath`，相对路径以会话 cwd 为基准解析。带文件链接的行关闭参数展开（左侧图标不可点）；工具行（含 bash 与 todo 注册）去掉整行点击、整行悬停底色，以及点击打开 details 的手势。details 面板及其 inject 面仍保留供程序化选择；工具行不再驱动它们。
 
-`host.openPath` 是特权一元 RPC，仅接受来自回环地址且同源的浏览器请求（与 `host.pickDirectory` 相同的载体守卫）。平台适配器不经 shell 打开：macOS 为 `open`，Windows 为 PowerShell `Invoke-Item`，桌面 Linux 为 `xdg-open`；浏览器可渲染的文档会在 macOS 与桌面 Linux 上优先使用能够确定的默认浏览器。尽管 Node 将 WSL 报告为 `linux`，WSL 仍是一种独立的宿主形态：适配器根据其环境或 Microsoft 内核 release 识别它，用 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给同一 PowerShell 交接。打开器的平台信息和命令运行器可在测试中注入。仅含 URL 的 read 参数（`web_fetch`）不是文件链接。
+`host.openPath` 是特权一元 RPC，仅接受来自回环地址且同源的浏览器请求（与 `host.pickDirectory` 相同的载体守卫）。平台适配器不经 shell 打开：macOS 为 `open`，Windows 为 PowerShell `Invoke-Item`，桌面 Linux 为 `xdg-open`；浏览器可渲染的文档会在 macOS 与桌面 Linux 上优先使用指定的默认浏览器。尽管 Node 将 WSL 报告为 `linux`，WSL 仍是一种独立的宿主形态：适配器根据其环境或 Microsoft 内核 release 识别它，用 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给同一 PowerShell 交接。打开器的平台信息和命令运行器可在测试中注入。仅含 URL 的 read 参数（`web_fetch`）不是文件链接。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
index d5dbd53881..243eed83f8 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
 2026-07-29-persistent-bash-str-replace-editor.md: c4750e30370bfd253064c39cb1adc0f5b2baa60d
-2026-07-29-persistent-bash-str-replace-editor.zh.md: 62073571ce2164d88897d4959caafd9cb1dbdd93
+2026-07-29-persistent-bash-str-replace-editor.zh.md: 14c52fc90d8619d63ca3acab2d85447fab5eb735
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
index 62073571ce..14c52fc90d 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 两个插件都进入 Python runtime 闭包。持久 Bash 的闭包还包含 PTY 服务／本地后端，以及该后端要求的沙箱服务。由于 `node-pty` 在 macOS 上会执行原生 `spawn-helper`，每个打包后的 macOS 运行时可执行文件都会携带一个 `-spawn-helper` 伴随文件；Linux 直接使用 `forkpty`。固定版本的 `node-pty` 补丁会先检查 `DSH_NODE_PTY_SPAWN_HELPER`，因此对当前提供非伴随 helper 的外部消费方而言，该变量仍是真正的覆盖项。未设置该覆盖时，补丁会在打包可执行文件的伴随文件存在时解析它，否则在普通 Node 运行中保留上游查找方式。若 helper 缺失或不可执行，macOS 构建器会在发布前失败。
 
-已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay 会在常规 Web 界面之上组合这两个插件，以满足与 Claude SWE 兼容的 RL 契约。它固定使用原生工具模式；完整的系统提示词在设置 `DSH_SYSTEM_PROMPT` 时采用其值，否则采用 `You are a helpful software engineer assistant.`，且不包含 harness 身份、源码 checkout 提示词段、Web 界面定位、Workspace 指令或工具模式指引。它会禁用其他所有面向模型的消费方，使模型恰好只收到持久 `bash` 和 `str_replace_editor` 两个 schema，同时保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
+已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay 会在常规 Web 界面之上组合这两个插件，以满足与 Claude SWE 兼容的 RL 约定。它固定使用原生工具模式；完整的系统提示词在设置 `DSH_SYSTEM_PROMPT` 时采用其值，否则采用 `You are a helpful software engineer assistant.`，且不包含 harness 身份、源码 checkout 提示词段、Web 界面定位、Workspace 指令或工具模式指引。它会禁用其他所有面向模型的消费方，使模型恰好只收到持久 `bash` 和 `str_replace_editor` 两个 schema，同时保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
index ff01e8a69a..dec5dcfafd 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
 2026-07-04-doc-tiers-and-budgets.md: e7b3421d09a1ae5ab9a9373e8040832c1b0d4b97
-2026-07-04-doc-tiers-and-budgets.zh.md: 18bf98777c87512e6161a4529db66030ced47bfd
+2026-07-04-doc-tiers-and-budgets.zh.md: 157ad13f521d2a497180e25b70e3537a4afbc099
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
index 18bf98777c..157ad13f52 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
@@ -6,15 +6,15 @@ Status: implemented
 
 ## 问题
 
-尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事件、重复的包（package）映射，以及陈旧的 Agent Note（agent 决策记录）摘要。该指导也未明确文档在层级中的位置如何限定其内容范围，以及按顺序引导读者学习的内容与面向查阅的材料有何不同。仅靠评审无法阻止这种增长，因此仓库需要在文档分类之外再配一套机械预算。
+尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事故、重复的包映射，以及陈旧的 Agent Note 摘要。该指导也未明确文档在层级中的位置如何限定其内容范围，以及按顺序引导读者学习的内容与面向查阅的材料有何不同。仅靠评审无法阻止这种增长，因此仓库需要在文档分类体系之外再配一套可自动执行的预算。
 
 ## 决策
 
-- **结构遵循文档树。**[docs/AGENTS.md](../../../../docs/AGENTS.md) 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。[Agent Note](../../README.md) 仍不受这一结构契约约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；[事故复盘（postmortem）](../../../../docs/postmortem/README.md) 是范围限定于单个事件的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。
+- **结构遵循文档树。**[docs/AGENTS.md](../../../../docs/AGENTS.md) 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。[Agent Note](../../README.md) 仍不受这一结构约定约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；[事故复盘（postmortem）](../../../../docs/postmortem/README.md) 是范围限定于单起事故的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。
 - **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。
-- **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其字数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
+- **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其词数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
 - **上限是只进不退的执行红线。** 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根 `AGENTS.md` ≤ 1,600 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600，但 `packages/AGENTS.md` ≤ 650、`docs/AGENTS.md` ≤ 1,250；`packages/README.md` ≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。
-- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载放置/审计/红灯门禁工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
+- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
 
 ## 曾考虑的替代方案
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 后果
 
-- 向受预算约束的文档添加内容需要置换：将新增内容迁移到其分类体系归属地并留下指针，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
+- 向受预算约束的文档添加内容需要腾挪空间：将新增内容迁移到其分类体系归属地并留下链接，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
 - 结构评审先检查归属关系和文档形式，再进行句子层面的编辑，使较低层级的细节迁移到其归属文档，而不是在错误的位置加以润色。
 - 仍高于目标的受预算约束文档不得增长；达到目标后，将恢复 5% 的工作余量。
-- 字数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。
+- 词数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
index e7f76356e2..0121a65219 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
 2026-07-22-fast-local-git-hooks.md: af8a9380fc3cbf4f672ca0b32faa7b187522cf11
-2026-07-22-fast-local-git-hooks.zh.md: 04f3a407e421c4d585b8b78b16b9055fd19ac756
+2026-07-22-fast-local-git-hooks.zh.md: 1b2c3bf42a65f35d96c266f5f3afb63f26039388
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
index 04f3a407e4..1b2c3bf42a 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
@@ -12,9 +12,9 @@ agent（智能体）已经会运行能够覆盖自身改动的测试和检查，
 
 ## 决策
 
-[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 契约，再运行 Client 增量类型检查。
+[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 约定，再运行 Client 增量类型检查。
 
-Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 契约构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
+Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 约定构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
 
 agent 检查待推送的 diff，并仅运行一次能够覆盖其行为的最小范围测试和检查。CI 负责全量覆盖率门禁、构建产物检查与平台矩阵。只有在明确要求、诊断 CI，或涉及全仓库的改动无法由范围更窄的证据得到可信验证时，才完整运行一遍本地检查矩阵。
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index 19945a6580..cd55f494d7 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
 2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
-2026-07-27-wine-windows-gates-experiment.zh.md: b50739f5b63c5836248c94927037e38900abc84f
+2026-07-27-wine-windows-gates-experiment.zh.md: 3145a4aa6a06cacbab96dd37714617aeecdfdde0
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
index b50739f5b6..3145a4aa6a 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -14,7 +14,7 @@ Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 wo
 
 [ci.yml](../../../../.github/workflows/ci.yml) 中必需的 pull request `windows` 作业（`windows node 24 / wine blocking`）在 `ubuntu-latest` 上通过 Wine 用真实 Windows 二进制运行阻断门禁命令：校验和验证过的 win-x64 Node.js 执行 `tsc -b`、`tsdown` 与 VitePress 生产构建，因此工具链的 win32 分支——反斜杠路径处理、`CreateProcess` 派生语义、`@esbuild/win32-x64` 的 PE 加载、以及 rolldown/rollup 的 MSVC `.node` 插件——都真正执行。master 的 `serial-windows` 作业原封不动：完整的原生内核清单，包括本通道不运行的观察性可移植性门禁，仍在每次 master push 时于真实 `windows-2025` 上执行。
 
-依赖在 Linux 上原生安装，`supportedArchitectures` 扩展到 win32-x64，使 Windows 平台包物化进同一个 store；通过直接调用各工具的 JavaScript 入口绕开 cmd-shim 层，这正是 `run-gates` 最终派生的那些进程。`nodeLinker: hoisted` 是承重的，不是风格问题：一个独立原型保留了 pnpm 默认的 isolated 布局——包括在 Linux 预取的 store 上忠实地用 Windows pnpm 离线重装——而 Wine 下的 Windows Node 依然无法穿过 isolated 符号链接链解析 `@esbuild/win32-x64` 或加载 koffi 预编译产物，在任何仓库门禁运行前就失败了。扁平的真实文件布局才让门禁变得可达；本通道采纳了该原型的校验和固定，同时明确放弃其「Windows pnpm 安装依赖树」的目标（安装契约在此仍由 Linux 侧验证）。
+依赖在 Linux 上原生安装，`supportedArchitectures` 扩展到 win32-x64，使 Windows 平台包物化进同一个 store；通过直接调用各工具的 JavaScript 入口绕开 cmd-shim 层，这正是 `run-gates` 最终派生的那些进程。`nodeLinker: hoisted` 是承重的，不是风格问题：一个独立原型保留了 pnpm 默认的 isolated 布局——包括在 Linux 预取的 store 上忠实地用 Windows pnpm 离线重装——而 Wine 下的 Windows Node 依然无法穿过 isolated 符号链接链解析 `@esbuild/win32-x64` 或加载 koffi 预编译产物，在任何仓库门禁运行前就失败了。扁平的真实文件布局才让门禁变得可达；本通道采纳了该原型的校验和固定，同时明确放弃其「Windows pnpm 安装依赖树」的目标（安装约定在此仍由 Linux 侧验证）。
 
 该通道靠四个杠杆把墙钟时间保持在与 Linux CI 作业相当的水平：master 刷新的 pnpm store 缓存（只恢复，与 Linux 作业同键）、Wine 供给（apt 安装、Windows Node 下载、`wineboot`）与 `pnpm install` 并发运行、两个阻断表面并发运行——与 `run-gates` 在原生 Windows 上给它们的形状相同——以及按 runner 镜像为键的 apt 归档缓存，由 master 的 `wine apt cache` 作业播种，使每个 pull request 都能从默认分支作用域恢复。
 
@@ -32,7 +32,7 @@ Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 wo
 
 **在 Linux runner 内用 QEMU/KVM 跑完整 Windows 客户机。** 真实 NT 内核，保真度完整，包括大小写不敏感的 NTFS 与 ConPTY——但首个门禁运行前要花数十分钟下载镜像并做无人值守安装（兄弟实验分支 `exp/kvm-windows-ci` 实测端到端 40 分 19 秒）。只有配上会挤压 Actions 缓存预算的磁盘镜像缓存才可投入使用。
 
-**在 Wine 下由 Windows pnpm 执行安装。** 同一想法的更高保真度变体：把 MinGit 与 pnpm 放进 prefix，用 Linux 预取填充 store，再由 Windows Node 运行 `pnpm install --offline`，让安装契约本身以 win32 身份执行。它到达了安装但没到达门禁——Wine 的网络无法直接访问 registry，且 isolated 的 `node_modules` 布局即便在干净的离线安装后也挫败了 Windows 平台包的解析。本通道牺牲这份保真度（hoisted 布局、Linux 侧安装）来换取门禁可达；两份记录是同一裁决互补的两半。
+**在 Wine 下由 Windows pnpm 执行安装。** 同一想法的更高保真度变体：把 MinGit 与 pnpm 放进 prefix，用 Linux 预取填充 store，再由 Windows Node 运行 `pnpm install --offline`，让安装约定本身以 win32 身份执行。它到达了安装但没到达门禁——Wine 的网络无法直接访问 registry，且 isolated 的 `node_modules` 布局即便在干净的离线安装后也挫败了 Windows 平台包的解析。本通道牺牲这份保真度（hoisted 布局、Linux 侧安装）来换取门禁可达；两份记录是同一裁决互补的两半。
 
 **Linux 上的文件系统语义通道（casefold ext4、文件名 lint）。** 以近零成本捕获最高频的 Windows 故障类别，但对 win32 二进制什么也证明不了。作为兄弟实验分支 `exp/casefold-windows-ci` 探索；与本通道互补而非竞争。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index 451ffb98ca..3b50695584 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
 2026-06-20-public-agent-stop-surface.md: e9c713c7ba8c784d3d66fe8f391e1b197f7394d2
-2026-06-20-public-agent-stop-surface.zh.md: 5c1eb0ec8245c60613d6d4d7c1d105b5243bc938
+2026-06-20-public-agent-stop-surface.zh.md: 217c898eec6b9e232f2cf3982b2bec411e8d91ab
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index 5c1eb0ec82..217c898eec 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -36,4 +36,4 @@ Status: implemented
 
 ## 相关
 
-本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终交付接口包括 `followup()`、`steer()` 和 `inject()`；停止与观察仍通过 `cancel()` 和 `whenIdle()` 完成。
+本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终的消息投递接口包括 `followup()`、`steer()` 和 `inject()`；停止与观察仍通过 `cancel()` 和 `whenIdle()` 完成。
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
index 3b9345a404..af534f7b4b 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
 2026-07-17-one-send-one-turn.md: 834eb2b3aace0a0aa5f86f483e7b7d7aabbe467e
-2026-07-17-one-send-one-turn.zh.md: d22893b912462cffffb0d6ecd81811e9cb5c523d
+2026-07-17-one-send-one-turn.zh.md: d05ce63c404ce4d10ac098e3a3c9617443cc278b
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
index d22893b912..d05ce63c40 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
@@ -16,11 +16,11 @@ Status: implemented
 
 规则很简单：一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。
 
-消息插入之前，`send()` 会检查 agent 状态，并接受已有标识且经过深度冻结的值。持久 splice 与 `agent/inbox/inserted { message }` 会保留其 `MessageId`；在驱动器领取或丢弃该消息之前，可以通过 `Inbox.replace()` 与 `Inbox.remove()` 寻址。当前生命周期由[已领取 pre-step inbox 决策](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md)规定。
+消息插入之前，`send()` 会检查 agent 状态，并接受已有标识且经过深度冻结的值。持久化 splice 与 `agent/inbox/inserted { message }` 会保留其 `MessageId`；在驱动器领取或丢弃该消息之前，可以通过 `Inbox.replace()` 与 `Inbox.remove()` 寻址。当前生命周期由[已领取 pre-step inbox 决策](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md)规定。
 
 如果消息 A、B 都进入处理，B 的轮次只能在 A 记录 `turn/end` 且 A 的持久性检查点处理结束后开始。因此，B 的请求能看到 A 在同一会话日志中留下的已关闭结果。检查点错误会照常报告，但处理结束只表示解除这道顺序屏障，不表示失败的写入已经持久化。面向整个 agent 的 `cancel()`、dispose（资源释放）或 `turn/start` 之前的失败也可能丢弃尚未启动的队列项，而不打开一个空轮次。
 
-轮次边界上，循环会先打开轮次，再在待处理 next-step 输入之后领取一条 follow-up。`agent/pre-step` 要么拒绝提案，要么返回进入步骤的完整批次。被拒绝的 follow-up 保持已删除，并关闭一个 blocked 的无步骤轮次，不写入模型可见历史。实现中不存在混合普通 follow-up 分支。
+轮次边界上，循环会先打开轮次，再在待处理 next-step 输入之后领取一条 follow-up。`agent/pre-step` 要么拒绝提案，要么返回进入步骤的完整批次。被拒绝的 follow-up 保持已删除，并关闭一个受阻的无步骤轮次，不写入模型可见历史。实现中不存在混合普通 follow-up 分支。
 
 上述不合批规则只适用于普通 follow-up 输入。`steer()` 会把输入放入 next-step inbox 并唤醒驱动器。在轮次期间，循环可以在后续步骤边界领取它；agent 空闲时，这个会唤醒的 next-step 批次会启动一个新轮次。批次被领取后才到达的输入会等待后续边界，而取消或 dispose 可以将其丢弃。
 
@@ -35,11 +35,11 @@ Status: implemented
 - 单元测试和基于属性的测试从同一调用栈、相邻微任务、不同生产方和重入回调提交 send；每条消息都会得到一个按 FIFO 排序的独立轮次。
 - stdio 构建产物测试提交两行输入，并观察到两个模型请求和两个轮次边界。
 - 延迟和拒绝第一个轮次的检查点，都能让下一个轮次保持等待，并证明其请求可以看到前一条助手结果。
-- 失败路径测试覆盖 pre-step reject、监听器失败、广义取消、dispose 和 `turn/start` 之前的失败；首次 pre-step 的各种退出都会关闭边界平衡的无步骤轮次，消息不会合并，之后仍需处理的工作也能继续清空。
+- 失败路径测试覆盖 pre-step 拒绝、监听器失败、面向整个 agent 的取消、dispose 和 `turn/start` 之前的失败；首次 pre-step 的各种退出都会关闭边界平衡的无步骤轮次，消息不会合并，之后仍需处理的工作也能继续清空。
 - 其他测试分别覆盖轮次打开时、轮次失败后和空闲时的 `steer()`，以及待处理的 `inject()`、面向整个 agent 的状态和 `whenIdle()`。
 
 ## 后果
 
-普通轮次的边界可预测：消息 A、B 始终分开，B 只能在 A 关闭并到达检查点后运行。调用方仍然拿不到逐次 send 的完成句柄；待处理消息可通过其 `MessageId` 移除，广义取消可以丢弃整个尚未启动的队尾，而状态与完全停稳仍是面向整个 agent 的观察。
+普通轮次的边界可预测：消息 A、B 始终分开，B 只能在 A 关闭并到达检查点后运行。调用方仍然拿不到逐次 send 的完成句柄；待处理消息可通过其 `MessageId` 移除，面向整个 agent 的取消可以丢弃整个尚未启动的队尾，而状态与完全停稳仍是面向整个 agent 的观察。
 
 代价是模型请求和检查点都会增加。繁忙队列可能需要更长时间才能清空；如果生产方持续提交消息，队列也可能增长。只有建立显式且经过测量的契约后，才能重新引入普通 send 批处理。
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
index fbca845408..b6ef95a950 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
 2026-07-22-plan-specific-collaboration-state.md: d139f3d861244c80acfb604d17172461bbf0cd57
-2026-07-22-plan-specific-collaboration-state.zh.md: a11ed1f270f58fc49a41be0e475889f84fa7cd40
+2026-07-22-plan-specific-collaboration-state.zh.md: dbf90357e4c4967d9665533c9abd2b4e1838da27
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
index a11ed1f270..dbf90357e4 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
@@ -24,7 +24,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 ### 边界与模型契约
 
-`plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩都能恢复该状态，无需实时镜像。spawn 出的 agent 初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step、或请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。
+`plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩（compaction）都能恢复该状态，无需实时镜像。spawn 出的 agent（智能体）初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step 时，或在请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。
 
 激活状态在提示词顺序 50 处贡献部署提供的区段。未激活状态不贡献区段，但 `exit_plan_mode` 在两种状态下都保持注册，因此状态转换会改变已记录的请求头，却不改变原生工具 schema 或 Code Mode SDK。用户发起的转换只会在上一条请求头描述相反状态时追加一条来源为插件的通知；第一次请求前的选择或最终状态未变化的选择不会追加通知，经批准的工具退出则依赖其工具结果，不再追加第二条通知。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index 45d89e4af1..1bd3e02df3 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
 2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
-2026-07-23-collapse-persistence-flush-state.zh.md: dfc8fc9576416b1f51f4f9c978f49aee4f39f938
+2026-07-23-collapse-persistence-flush-state.zh.md: d5b02ebc545a32fbdb44feed04ec2afbbafeff4b
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index dfc8fc9576..d5b02ebc54 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享 flush 屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
+每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享刷新屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
 
-`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式 flush、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
+`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式刷新、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
 
 初始化只进入现有的按 id 操作链一次，并在占有该轮执行权时调用未串行化的核心操作。该操作链与活跃控制器保持分离，因为公共 `create`、`append`、`load` 调用即使没有 `Session` 对象仍可能发生竞态，依然需要按标识串行执行。
 
@@ -44,6 +44,6 @@ Status: implemented
 
 ## 后果
 
-活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和 flush 屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
+活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和刷新屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
 
 `session/flush` 不再决定普通持久化何时开始。它仍是循环和检查点策略使用的顺序与错误观测边界，因此检查点成功仍表示在其完成前接纳的每个事件都已持久化。
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
index 507c607217..5067b15402 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
 2026-07-24-agent-loop-observable-state-machine.md: b1773fdf7fd3bcbea9c6b9a4a0ce37c715bce4ca
-2026-07-24-agent-loop-observable-state-machine.zh.md: a4ed98117b965b445ec0888c55a1b1b27887532a
+2026-07-24-agent-loop-observable-state-machine.zh.md: f47e5901ec97a44efa00cf79ef8ce52fdcac9878
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
index a4ed98117b..f47e5901ec 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
@@ -21,7 +21,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 - 待处理消息插入时会发出 `agent/inbox/inserted`，随后要么在原子纯删除领取后发出 `agent/inbox/claimed`，要么在普通删除后发出 `agent/inbox/discarded`。`MessageId` 关联确切消息；持久 splice 坐标保留 placement 与取消信息。inbox 事件描述插入、领取和丢弃，而不是轮次完成。
 - 已领取的轮次经过 pre-step 进入决策和零个或多个请求步骤。自动重试会关闭失败轮次并立即开启另一个轮次；`agent/settled` 只报告该重试链的终态轮次，且仍不同于 agent 整体转换到 `status === 'idle'`。
 
-循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering，循环在所有监听器完成后根据这份数据作出决定。
+循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering（中途引导），循环在所有监听器完成后根据这份数据作出决定。
 
 是否继续和终止执行由数据表达，不再由返回的控制枚举表达。工具调用和已接受的 steering 要求再执行一个步骤。携带 `concludesTurn` 的工具结果会在其所属步骤终止工具循环。循环不再暴露通用的 `ContinuationDecision` 或终止返回通道。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
index 1e375b34d3..c0bccacb78 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
 2026-07-25-client-settings-locale-theme.md: fdcdcff92fa324803d5f2343f3fc3d9dcca069c7
-2026-07-25-client-settings-locale-theme.zh.md: b1536a1515fa7022320934dfdabf94c815e8ba04
+2026-07-25-client-settings-locale-theme.zh.md: 9cf973aee29cc1072c2fdaf1ce67e0b8395f1d90
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
index b1536a1515..9cf973aee2 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
@@ -55,11 +55,11 @@ root
             └─ models (order 10)         ui-models 注册
 ```
 
-section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest 的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings contract（消费者 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的 contract 对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export seam 消费。
+section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest（元数据清单）的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings 约定（消费方 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的约定对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export seam 消费。
 
 ### slot 声明是一等可注入等待对象
 
-`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明折叠与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会大声失败。这删除了陈旧 disposer 判在位机器和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败契约见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明撤销与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会显式报错。这移除了陈旧 disposer 的在位判定机制和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ### 服务契约
 
@@ -127,4 +127,4 @@ Locale 内置中文和 English；`setLocale`/`setTheme` 是唯一写入口，未
 
 ## 风险
 
-slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。service event 可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR 后残留。
+slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。服务事件可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR（热模块替换）后残留。
diff --git a/docs/cookbook/adding-an-llm-adapter.i18n.yaml b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
index 13827c2b60..199a870ac9 100644
--- a/docs/cookbook/adding-an-llm-adapter.i18n.yaml
+++ b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-an-llm-adapter.md
 adding-an-llm-adapter.md: 4fcc646ed2eea8a6170027d01761887aa28b0045
-adding-an-llm-adapter.zh.md: 35a671416f8160a6187a06f3dbd614dfe4faa778
+adding-an-llm-adapter.zh.md: eeeb84583fb9951745083b60385547d14f461266
diff --git a/docs/cookbook/adding-an-llm-adapter.zh.md b/docs/cookbook/adding-an-llm-adapter.zh.md
index 35a671416f..eeeb84583f 100644
--- a/docs/cookbook/adding-an-llm-adapter.zh.md
+++ b/docs/cookbook/adding-an-llm-adapter.zh.md
@@ -36,7 +36,7 @@ export function apply(ctx: Context, config: Config) {
 
 ## 实现结构
 
-让协议类型、请求序列化、传输解析、分片转换和适配器类分别承担独立职责；[`llm-deepseek`](../../packages/llm/llm-deepseek/README.md) 是参考布局。
+让协议格式（wire format）类型、请求序列化、传输解析、分片转换和适配器类分别承担独立职责；[`llm-deepseek`](../../packages/llm/llm-deepseek/README.md) 是参考布局。
 
 ## 验证
 
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
index 539a3f396e..a00432f1d5 100644
--- a/docs/defensive-patterns.i18n.yaml
+++ b/docs/defensive-patterns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/defensive-patterns.md
 defensive-patterns.md: 6dc1708f0b9bbcb00ad4774006d6d60059accf6a
-defensive-patterns.zh.md: 4c376f1a5f2f6d5fbe85124ce473bc7af5ad4c8d
+defensive-patterns.zh.md: 2ff5cba2a94c5149f2b92b37845d23211ee7989d
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
index 4c376f1a5f..2ff5cba2a9 100644
--- a/docs/defensive-patterns.zh.md
+++ b/docs/defensive-patterns.zh.md
@@ -10,11 +10,11 @@
 
 ## 跨 seam 契约两侧都要遵守
 
-当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止 finish chunk 暴露模型请求失败；middleware 与消费方缺陷仍会抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化契约；通过真实消费方覆盖每种来源形式。
+当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
 
 ## 异步状态不是同步状态
 
-`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent 下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
+`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
 
 ## Dispose 必须达到完全停稳，而不仅仅是请求停止
 
diff --git a/docs/user/develop/basic/config.i18n.yaml b/docs/user/develop/basic/config.i18n.yaml
index 6bf0ddea72..2887d77209 100644
--- a/docs/user/develop/basic/config.i18n.yaml
+++ b/docs/user/develop/basic/config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/config.md
 config.md: 02998c32415b5ba7acf82700034cabc1f7314f33
-config.zh.md: 42af432b36d8f82871aa7d7b6a3a2eaf7427cdae
+config.zh.md: 161af5d6703b4cc77d63443a5a80846593d1c7fd
diff --git a/docs/user/develop/basic/config.zh.md b/docs/user/develop/basic/config.zh.md
index 42af432b36..161af5d670 100644
--- a/docs/user/develop/basic/config.zh.md
+++ b/docs/user/develop/basic/config.zh.md
@@ -93,7 +93,7 @@ export interface Config {
 
 ### 配置错误要响亮
 
-在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.md)会介绍这项契约。
+在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.md) 会介绍这项约定。
 
 ## 配合 HMR
 
diff --git a/docs/user/develop/basic/tool.i18n.yaml b/docs/user/develop/basic/tool.i18n.yaml
index 467ab841d6..cb9759860e 100644
--- a/docs/user/develop/basic/tool.i18n.yaml
+++ b/docs/user/develop/basic/tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/tool.md
 tool.md: 8505bdaf6fcece3235b0302d54e82ee8aed3cbab
-tool.zh.md: 1831afa9be74756cb9bb1e96515fefd3685ee4c2
+tool.zh.md: c6c579c5da9dc545c2795e65331810528c37219f
diff --git a/docs/user/develop/basic/tool.zh.md b/docs/user/develop/basic/tool.zh.md
index 1831afa9be..c6c579c5da 100644
--- a/docs/user/develop/basic/tool.zh.md
+++ b/docs/user/develop/basic/tool.zh.md
@@ -1,4 +1,4 @@
-# 构建工具
+# 开发一个工具
 
 [English](tool.md) | 中文
 
diff --git a/examples/acp-agent/README.i18n.yaml b/examples/acp-agent/README.i18n.yaml
index 0bfa1735ce..cf9fee7334 100644
--- a/examples/acp-agent/README.i18n.yaml
+++ b/examples/acp-agent/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 examples/acp-agent/README.md
 README.md: 61c6efafe9dde4f91385beebdfd426c57006187b
-README.zh.md: 343e55722a4dda7c5cc5e0de6b5fecf250b9ab13
+README.zh.md: 6eaf9fb5a91c737254e785d8601961b547e4e9ca
diff --git a/examples/acp-agent/README.zh.md b/examples/acp-agent/README.zh.md
index 343e55722a..6eaf9fb5a9 100644
--- a/examples/acp-agent/README.zh.md
+++ b/examples/acp-agent/README.zh.md
@@ -9,7 +9,7 @@ pnpm run demo:acp             # needs DEEPSEEK_API_KEY (repo-root .env or env)
 pnpm run demo:code-mode       # same protocol with the Code Mode tool transport
 ```
 
-该叶节点加载 ACP 应用、DeepSeek 适配器、受沙箱限制的 bash 与文件系统栈、一次性批准策略、压缩（compaction）、subagent、工作流、钩子、派生会话查询索引和重复守卫。应用为每次 `session/new` 创建一个新 agent，将会话持久化到 JSONL，并保持 stdout 只含协议内容。可选 overlay 可添加会话查询、文件系统溢出存储、Code Mode 或 Web 抓取。
+该叶节点加载 ACP 应用、DeepSeek 适配器、受沙箱限制的 bash 与文件系统栈、一次性批准策略、压缩（compaction）、subagent、工作流、钩子、派生会话查询索引和重复守卫。应用为每次 `session/new` 创建一个新 agent，将会话持久化到 JSONL，并保持 stdout 只含协议内容。可选 overlay 可添加会话查询、文件系统 spill 存储、Code Mode 或 Web 抓取。
 
 ## 协议通道
 
diff --git a/examples/jsonrpc-agent/README.i18n.yaml b/examples/jsonrpc-agent/README.i18n.yaml
index ce35a749a0..e1c36e959c 100644
--- a/examples/jsonrpc-agent/README.i18n.yaml
+++ b/examples/jsonrpc-agent/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 examples/jsonrpc-agent/README.md
 README.md: bcc1027d2edb30ab374dfa2ed13ad8e6360d923b
-README.zh.md: 197c25d7b4f5645aeb7e92d8c36ef4a423beb2e8
+README.zh.md: ce255e4dd70bf8c5c6edc51afbe03bb4c66560a0
diff --git a/examples/jsonrpc-agent/README.zh.md b/examples/jsonrpc-agent/README.zh.md
index 197c25d7b4..ce255e4dd7 100644
--- a/examples/jsonrpc-agent/README.zh.md
+++ b/examples/jsonrpc-agent/README.zh.md
@@ -26,11 +26,11 @@
 
 通过 Python SDK 的 `cordis` 选项或 `DSH_CORDIS_CONFIG` 传入配置路径。内置可执行文件已携带此文件中指定的每个插件；目标机器无需 Node.js。
 
-## 持久工具变体
+## 持久化工具变体
 
 [`persistent-tools.cordis.yml`](persistent-tools.cordis.yml) 是一个最小可运行变体，面向模型的能力严格只有：
 
-- agent 独占、状态持久的 `bash`
+- 所有者作用域内持久化的 `bash`
 - 提供 `view`、`create`、`str_replace` 与 `insert` 的 `str_replace_editor`
 
-它组合本地 PTY、文件系统 intent 策略与会话沙箱策略。
+它组合了本地 PTY、文件系统意图策略与会话沙箱策略。
diff --git a/native/README.i18n.yaml b/native/README.i18n.yaml
index 31a86ebe73..258111fbdb 100644
--- a/native/README.i18n.yaml
+++ b/native/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 native/README.md
 README.md: 51c8da7b57df15e65b8e431ee18ce6cebb89d54b
-README.zh.md: baf530157c6731893a66aea301c6dd962592defc
+README.zh.md: 55dd5eb0a197bd970b33f7943877fb3826858128
diff --git a/native/README.zh.md b/native/README.zh.md
index baf530157c..55dd5eb0a1 100644
--- a/native/README.zh.md
+++ b/native/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-与 DeepSeek Harness 一同维护的原生源码和公开包。[`landlock-run/` workspace](landlock-run/README.md)负责 harness 使用的 Landlock 自限后执行启动器，包括其架构、由三个包组成的 npm 包家族、平台支持、开发工作流和[发布流程](landlock-run/docs/release.md)。
+与 DeepSeek Harness 一同维护的原生源码和公开包。[`landlock-run/` workspace](landlock-run/README.md) 负责 harness 使用的 Landlock 自限后执行启动器，包括其架构、由三个包组成的 npm 包家族、平台支持、开发工作流和[发布流程](landlock-run/docs/release.md)。
 
 ## Workspace 与发布边界
 
-`landlock-run/` 及其包属于仓库根 pnpm workspace，并共用根锁文件。开发和 CI 中的 harness 消费方直接使用当前 workspace 的入口包，因此启动器契约变更与消费方更新可以在同一个改动中落地并一起测试。
+`landlock-run/` 及其包属于仓库根 pnpm workspace，并共用根锁文件。开发和 CI 中的 harness 消费方直接使用当前 workspace 的入口包，因此启动器约定变更与消费方更新可以在同一个改动中落地并一起测试。
 
 主仓库的 `Landlock Run` 工作流为每个受支持架构构建并测试。`Landlock Run Release` 汇集这些原生产物，打包并验证三个 npm tarball，随后可选择以同一个启动器版本发布。入口包继续将平台包声明为 npm 可选依赖，因此 npm 仍然只会安装与用户操作系统和 CPU 匹配的包。
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index c204d571cf..2189d62b3c 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/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 native/landlock-run/README.md
 README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
-README.zh.md: 8206ab8074d8d80fb9b11cff436bbd10e6dc34dd
+README.zh.md: c994087317be54d522d965de3e120da6fabb7ded
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index 8206ab8074..c994087317 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -39,7 +39,7 @@ if (probe(launcher) !== 'unusable') {
 - `launcherPath()`：当前宿主启动器的绝对路径（有意不检查是否存在；探测结果才是可用性信号）。
 - `probe(launcher?, { timeoutMs? })`：功能性强制执行探测，返回 `'full' | 'partial' | 'unusable'`。
 - `grantArgs({ readOnly?, readWrite? })`：启动器的授权 argv；未授予的一切都被拒绝。
-- `LAUNCHER_BIN` 和 `LAUNCHER_FAILURE_EXIT`（125）：契约常量。成功完成 exec 的子进程也可能返回 125，因此消费者必须同时看到致命诊断和该状态，才能将结果归因为 launcher 失败。
+- `LAUNCHER_BIN` 和 `LAUNCHER_FAILURE_EXIT`（125）：约定常量。成功完成 exec 的子进程也可能返回 125，因此消费方必须同时看到致命诊断和该状态，才能将结果归因为启动器失败。
 
 完整的二进制契约（argv 语法、退出码、报告行）锁定在 [docs/cli-contract.md](docs/cli-contract.md) 中。
 
diff --git a/packages/acp/acp/README.i18n.yaml b/packages/acp/acp/README.i18n.yaml
index e0353e1ff7..1c8c175eb0 100644
--- a/packages/acp/acp/README.i18n.yaml
+++ b/packages/acp/acp/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/acp/acp/README.md
 README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
-README.zh.md: 82aa5df2c7d87312d4b619a09582cc0c2d884398
+README.zh.md: 4856b44683b5594ad0211af907d1a12ce814d492
diff --git a/packages/acp/acp/README.zh.md b/packages/acp/acp/README.zh.md
index 82aa5df2c7..4856b44683 100644
--- a/packages/acp/acp/README.zh.md
+++ b/packages/acp/acp/README.zh.md
@@ -24,7 +24,7 @@
 | `initialize` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
 | `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
 | `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
-| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入 idle。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（turnless 槽位）时报告 `cancelled`。 |
+| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入空闲状态。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（无轮次槽位）时报告 `cancelled`。 |
 | `session/cancel` | 仅取消指定的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 |
 | `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 |
 | `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
@@ -37,7 +37,7 @@
 
 客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
 
-ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入 idle 前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即 reject 提示词。
+ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入空闲状态前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即拒绝该提示词。
 
 ## 运行
 
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index 2de1c468b8..b4eb8c4869 100644
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/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-sandbox/README.md
 README.md: 74c1e28f76db35603bb9f72e0522e16ece5589f7
-README.zh.md: 2593049ce09c7bc1ae0a996321bb27cbac449977
+README.zh.md: 34ad936f31bf4ce11e175653a3a895a56e4822cc
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index 2593049ce0..34ad936f31 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -18,7 +18,7 @@
 
 - **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
 - **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 工具描述则单独负责拒绝与升级引导。
+- **部署回退，每次调用策略。** [`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/)。
 
diff --git a/packages/client/hmr/README.i18n.yaml b/packages/client/hmr/README.i18n.yaml
index 86859e79f6..f9ce3024f1 100644
--- a/packages/client/hmr/README.i18n.yaml
+++ b/packages/client/hmr/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/client/hmr/README.md
 README.md: 454c03cc3cd11722943efd025d164d9ca8233d25
-README.zh.md: fc4100c48e5db9ed6781117dd652232bbd7c7aaa
+README.zh.md: ea62600911458556a3dcc7c46854e97db751c3ef
diff --git a/packages/client/hmr/README.zh.md b/packages/client/hmr/README.zh.md
index fc4100c48e..ea62600911 100644
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为通过外部脚本加载的客户端插件提供热重载。该静态加载配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略该项，因此打包进 shell 的代码保持不活动。
+为通过脚本加载的客户端插件提供热重载。该静态加载配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略该项，因此打包进 shell 的代码保持不活动。
 
 浏览器侧订阅系统 SSE（Server-Sent Events）通道（`GET /plugins/events`），每个 `rebuilt` 帧重载一个插件，并通过队列串行执行。每帧的顺序是：`invalidate`、`prefetch`（旧 fiber 仍在服务时加载并注册新组合包）、`registry.delete`（在 fiber dispose（资源释放）之前执行：仅 dispose fiber 会触发 vendored Loader 的 self-dispose 分支，把配置项标为禁用）、排空旧 fiber、删除 `entry.fiber`、移除自身拥有的 `<style data-plugin>` 标签、通过 `entry.refresh()` 重新导入并挂载、通过 `fiber.await()` 直接重新抛出启动失败。依赖方由 Cordis 自身重载：fiber 的激活 epoch 会串联其服务提供方的 uid，因此替换提供方 fiber 会级联所有依赖方，无需客户端图分析。node 侧使用一个 interval 检测重建：从同步基线开始 stat-poll 每个图组合包；新增一行后立即重新计算 hash；缺失行保持 dirty；只广播真实 rev 变更。因此，任何生成组合包的 tsdown watch 进程都能触发 HMR（热模块替换），无需 builder→host 通道。
 
diff --git a/packages/client/modules/README.i18n.yaml b/packages/client/modules/README.i18n.yaml
index fa284aabd7..2f7278eae2 100644
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/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/client/modules/README.md
 README.md: 7d661c806955d0fac021dd6620994aab83c0f773
-README.zh.md: a1da42a552dbe8770fcb78bf458c01a0057ce8dd
+README.zh.md: aec59474fbf01857380709ebecb6ae99a6ca8174
diff --git a/packages/client/modules/README.zh.md b/packages/client/modules/README.zh.md
index a1da42a552..aec59474fb 100644
--- a/packages/client/modules/README.zh.md
+++ b/packages/client/modules/README.zh.md
@@ -8,7 +8,7 @@
 
 解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 表层；外壳自身的静态注册表（`registerStatic`，app-shell）→ 模块；已注册 factory → 物化；模块图记录（`window.__DSH_BOOT__`）→ 加载外部 classic script + 物化；其他情况一律抛出异常。这是构建时组合包纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含异步加载分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达钩子（只加载脚本并注册 factory；并发调用共享一个进行中的任务）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新加载脚本；它是 HMR（热模块替换）钩子。
 
-Node 侧会扫描已启用的 Loader 配置项以发现 web `dshClient` 包，解析每个 `exports["./client"]`，把构建后的组合包哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费客户端导出的构建产物；缺失文件共享一条构建要求，随后以 package/path list 列出各项，而无关的文件系统错误仍是独立故障。
+Node 侧会扫描已启用的 Loader 配置项以发现 web `dshClient` 包，解析每个 `exports["./client"]`，把构建后的组合包哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以 package/path list 列出各项，而无关的文件系统错误仍是独立故障。
 
 ## 模型体验
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 1edac07d5e..92b9e2abfc 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
 README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
-README.zh.md: 6eee14bdbe7a9fb86b0a12355e7d0a45cd500774
+README.zh.md: 8ee06e93b475398750ee74d4900a8c6917cf71f5
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 6eee14bdbe..8ee06e93b4 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -8,7 +8,7 @@
 
 `ctx.slots.inject(name, callback)` 将完整的 `SlotMap` key 作为贡献项的依赖，适用于贡献方插件可独立于声明条目激活的情形。声明存在时，它会同步运行 `callback`，否则等待；声明折叠会 dispose（资源释放）回调 effect，重新声明则会再次运行回调。控制器归调用方的插件 fiber 所有，因此卸载贡献方会取消等待或移除其活跃注册项。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常。
 
-回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的 effect，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的注册项，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ## Workspace 与 Session 列表
 
@@ -18,7 +18,7 @@ Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线
 
 `WorkspacesService.delete(workspaceId)` 在一元响应成功后从客户端投影中移除注册记录；对应的 `host/workspace-removed` 帧具有幂等性，并负责同步其他标签页。Session 状态与当前 Session selection 相互独立，因此 Workspace 消失后，其已纳入客户端投影的 Session 会立即投影到 Ungrouped 下。
 
-`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影层在当前 selection 落入归档集合时统一清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
+`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影扫描在当前 selection 落入归档集合时将其清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
 
 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建钩子。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
 
@@ -36,9 +36,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
 ## 请求检查
 
@@ -54,7 +54,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 模型重试投影
 
-Session 对象会在事件 wire 边界依据生产方的完整字段契约，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
+Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括对计时器、整数、状态、提供方延迟和非空诊断字段的约束。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
 
 ## 会话 fork
 
diff --git a/packages/client/schema-form/README.i18n.yaml b/packages/client/schema-form/README.i18n.yaml
index 1c3c759ceb..73ec057a53 100644
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/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/client/schema-form/README.md
 README.md: 716cc7ba3c24f3a4de081e2d26f803b905235fac
-README.zh.md: 65b8767df84f90eedd70e9f8ac27d7d419f06f46
+README.zh.md: 61fff15ca6a21e6267da158640e3782422e865c3
diff --git a/packages/client/schema-form/README.zh.md b/packages/client/schema-form/README.zh.md
index 65b8767df8..61fff15ca6 100644
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -20,4 +20,4 @@
 
 - **重建 schema 会执行所收到的信封**——`rehydrateSchema` 会重建一个活的 schemastery 校验器，而 schemastery 通过 `new Function` 复活序列化过的 callback，因此 schema 信封是可执行内容，而非惰性数据。只有信封来自提供该页面的同一受信任 host 时才安全；该协议没有跨信任边界使用的惰性表示。
 - **校验是草稿级的，而非逐字段**——`validateDraft` 报告 schemastery 的第一条失败消息及其 `$.path`；它不会把错误映射到各个控件。
-- **没有通用渲染器**——消费方在这些辅助函数上构建功能专用表单。[Web 配置面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)记录该权衡。
+- **没有通用渲染器**——消费方在这些辅助函数上构建功能专用表单。[Web 配置面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md) 记录该权衡。
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index d04c06b3da..613876693a 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/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/client/ui-layout/README.md
 README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
-README.zh.md: 6ca04c56c29a55f84fc7a6399a7feeb81d249899
+README.zh.md: dd23550cc8f0134ed1231c86d88825dab96e8e79
diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
index 6ca04c56c2..dd23550cc8 100644
--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景保持为唯一颜色真源；呈现器在资源释放时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
+外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景成为唯一的颜色依据；呈现器在 dispose（资源释放）时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
 
 AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用契约默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
 
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index 25020ab686..9f6db24bba 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/client/ui-model/README.md
 README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
-README.zh.md: 2bb22c55f1ae5af59f21e254804329d288806a90
+README.zh.md: 09fee7a2cfd22b773be569e37c4c31f8c299d707
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 2bb22c55f1..09fee7a2cf 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -6,7 +6,7 @@
 
 Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择事实，但只有当该精确路由仍在已公布分组中时才会回显；删除该目录行会保留仍可路由的目标，但触发器会提示 `Select model`，系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。
 
-当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 抬起一个编辑器 block，输入框随之变为惰性并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来能用的编辑器；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
+当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 注册一个 composer 阻塞块，输入框随之停用并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来可用的 composer；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
 
 目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 5e7b29d244..ce82152632 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
 README.md: 66f23d3f77adae23fcebd3adbb6c5c47ce16ae2f
-README.zh.md: dcb35c624aca73b558532210750f684e5cc54e85
+README.zh.md: d0a5ad465e713680757a3e3734fc97dc31280a2e
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index dcb35c624a..d0a5ad465e 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上以一条用户无从下手的原始正则失败。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个标识唯一的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上抛出原始正则表达式错误。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
 
 ## 模型体验
 
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index 5871fb996f..5954e72809 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/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/client/ui-settings/README.md
 README.md: 785f0417f00ec8eb1f8c9273b4d81f8ca5ca1810
-README.zh.md: 8e7bd7325b78416345985ee25a56a5eb8b382478
+README.zh.md: 239987e379aaabd2edbfc9e09cd2fc8cef7a685e
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index 8e7bd7325b..239987e379 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -4,7 +4,7 @@
 
 设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、显示在全视口展示层中的有序页面）。外壳不自带文案：所有文本都来自注册方（ui-settings-general 拥有界面框架、「通用」分区和产品声明；各功能拥有各自的操作、分区、行和条件式首次使用引导页面）。导航 label 可以是跟随语言的 thunk，因此导航投影经 `resolveSlotLabel` 解析，并在分区账本更新或 locale revision 变化时重新渲染（`ctx.get('locale')` 可选读取，无硬 locale 依赖）。
 
-外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及页面的外层包裹均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
+外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及展示层包装均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
 
 ## 模型体验
 
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index cc563215dc..9b00e02b2a 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/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/client/ui-sidebar/README.md
 README.md: 45ae267d98b17bbc612cf932f5b95b42ba6ff4bf
-README.zh.md: 436baf0b2d50934ce4813ac53c532006d9d0d4fb
+README.zh.md: c0bae62de0811874a94810bd18c78378441db8a3
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index 436baf0b2d..c0bae62de0 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -12,7 +12,7 @@ New Session 会启动运行时的页面局部前端 Session Intent；真实 Work
 
 页脚承载 `sidebar.settings`：侧边栏只渲染固定在底部的布局 slot，并共享其栏状态（`wide`）；ui-settings 在此注册触发行和设置面板。
 
-`/client` 导出表层只包含插件主体（`apply`／`inject`）及契约类型；SidebarRoot、行组件和树派生仍由 slot 注册封装在包内。
+`/client` 导出表层只包含插件主体（`apply`／`inject`）及约定类型；SidebarRoot、行组件和树派生仍由 slot 注册封装在包内。
 
 ## 模型体验
 
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 5aa997d003..b7c737a98f 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
 README.md: 44953fe36ad337d0dd70e4d8c0cc2372b8924c9b
-README.zh.md: 8c21ef35eded61324d139dd32b7c1e38f8709d55
+README.zh.md: 3a8ac86d13114bdbbb78c33d907aba7bb1a10fc2
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 8c21ef35ed..3a8ac86d13 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -4,7 +4,7 @@
 
 skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
 
-pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP 提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
+pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP（Agent Client Protocol）提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
@@ -32,6 +32,6 @@ pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文
 
 ## 已知限制与暂缓事项
 
-- **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于 runtime 窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议契约。
+- **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于运行时窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议约定。
 - **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用，宿主手势边界评判的是发出的文本，而不是菜单交互。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份、位置跟踪，也没有提示词协议上的结构化引用载荷（两者都是台账事项）。
 - **预热落定之前打开的菜单**：在那次击键下不显示 skill 候选；下一次击键会重新轮询已落定的缓存。
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index dd103f395a..7b67f66d3b 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/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/client/ui-slots/README.md
 README.md: bb489dea0c3848cf3d501dcf095a65fe1cef9ef6
-README.zh.md: b4a2915b9d85c45ef7c6dccf27761794e21aa65f
+README.zh.md: 91e4f817c414e11645aa4d3a1b9bcf94f9678805
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index b4a2915b9d..91e4f817c4 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -19,7 +19,7 @@ chain-kind slot 会反转键控路由：条目自行提名，而不是由分发
 
 store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 契约。引擎产物与 renderer host 契约携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 契约 hook 类型（`SnapshotSelectorHook`）位于这里。
 
-`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与折叠时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
+`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
 ## 模型体验
 
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index eb915bff8d..6ca3d905b4 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/client/ui-theme/README.md
 README.md: 648213b258169b2e8869a93d058fcc65aece175e
-README.zh.md: b807ebd66253c91dc8b79f01ac4d3b2335682001
+README.zh.md: 02481badc816e0eb42c0d2496c9a096d2dbdbccb
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index b807ebd662..02481badc8 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -6,7 +6,7 @@
 
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
-滚动条重新绑定契约：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，两条渲染路径都读取这一组变量。高层级表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为引擎实际走的那条路径换色。这组变量另一个合法的目标是 `transparent`，即完全不绘制滑块——[ui-sidebar](../ui-sidebar/README.md) 在指针不在栏内时就这样重新绑定自己的列。绑回 l1 那组不算重新绑定，它只是重述基础表面的默认值。
+滚动条重新绑定约定：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，两条渲染路径都读取这一组变量。高层级表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为引擎实际走的那条路径换色。这组变量的另一个合法目标是 `transparent`，即完全不绘制滑块——[ui-sidebar](../ui-sidebar/README.md) 在指针不在栏内时就这样重新绑定自己的列。绑回 l1 那组不算重新绑定，它只是重述基础表面的默认值。
 
 两条路径在构造上互斥。`scrollbar-width`／`scrollbar-color` 写在 `@supports not selector(::-webkit-scrollbar)` 之内，因为这两个属性中的任一个只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中——若无条件地同时声明，`--dsh-scrollbar-thumb-hover` 在任何引擎上都不会被渲染。因此 Firefox 走标准属性，WebKit 系引擎走伪元素，hover token 只经由伪元素这条路径渲染。推理过程与实测计算值见[滚动条 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)。
 
@@ -21,4 +21,4 @@
 ## 已知限制与暂缓事项
 
 - **第三方主题是表层，不是产品**：注册主题意味着覆盖同名别名变量；目前不会验证一组覆盖是否完整。
-- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个 static 梯度值加一个语义 alias 的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
+- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个静态尺度层级与一个语义别名的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
diff --git a/packages/client/web/README.i18n.yaml b/packages/client/web/README.i18n.yaml
index 9b652b3110..cf0e86691f 100644
--- a/packages/client/web/README.i18n.yaml
+++ b/packages/client/web/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/client/web/README.md
 README.md: 74c481d573fb716e624e639c74b35c82e6894f63
-README.zh.md: 08c69665a00377ff4bb11eee90031a45b3901753
+README.zh.md: 0e36107e50b2e22d65c126a4fd8873a89b0bb687
diff --git a/packages/client/web/README.zh.md b/packages/client/web/README.zh.md
index 08c69665a0..0e36107e50 100644
--- a/packages/client/web/README.zh.md
+++ b/packages/client/web/README.zh.md
@@ -23,4 +23,4 @@ Web 外壳内核：`new AppWebEntry(el, seams?).run()` 通过两阶段启动（w
 ## 已知限制与暂缓事项
 
 - **有意采用一次性渲染**：UI 等待启动 settle；只要一个配置项失败，加载页面就会保留并逐项显示醒目的报告，不提供部分可用性（渐进式渲染将作为独立项目恢复）。
-- **窄窗口外壳行为缺少组装后演练**：ui-layout 已实现让步链，但该包没有外壳级窄 viewport 验收用例。
+- **窄窗口外壳行为缺少组装后演练**：ui-layout 已实现让步链，但该包没有外壳级窄视口验收用例。
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index 8d3568e82e..adddfd119a 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
 README.md: 590b79dcd1bc322350060b55767b09c6305edacc
-README.zh.md: 12c25f892bd20892cb47e593f16b6aadd9ffa84c
+README.zh.md: e45aa484c0935d5b4b1626f5c4c7c72482cd5b5d
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index 12c25f892b..e45aa484c0 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -32,7 +32,7 @@
 
 ## 未构建与已构建的 worker 入口
 
-源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口周围展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。演练这个已发布入口路径的仓库级要求由[测试策略](../../../docs/testing.md)规定。
+源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口两侧展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。对这个已发布入口路径进行测试的仓库级要求由[测试策略](../../../docs/testing.md)规定。
 
 SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Config`。运行所用的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
 
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index a6bd209c7b..3f2ea68116 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
 README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: 15fbcecf77b2318acf3b09101802cd032ae426d2
+README.zh.md: fff62b97b8ef76901e4680fb6c6c8ff4820ba35d
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index 15fbcecf77..fff62b97b8 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -20,7 +20,7 @@
 
 `CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
 
-binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
+binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
 ## 模型体验
 
diff --git a/packages/context/time-context/README.i18n.yaml b/packages/context/time-context/README.i18n.yaml
index 3ddda9bc7b..8e67848c71 100644
--- a/packages/context/time-context/README.i18n.yaml
+++ b/packages/context/time-context/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/context/time-context/README.md
 README.md: 9956918c63b49de8ec5e739bc3d9887e269930a8
-README.zh.md: fd338cc192c2168915017dd22ac6a1631d8cc21b
+README.zh.md: 3a9bb1012fc0639d9c3f6b104cea5a64d4b187d6
diff --git a/packages/context/time-context/README.zh.md b/packages/context/time-context/README.zh.md
index fd338cc192..3a9bb1012f 100644
--- a/packages/context/time-context/README.zh.md
+++ b/packages/context/time-context/README.zh.md
@@ -16,17 +16,17 @@
 
 省略 `timeZone` 时，插件会在加载时解析一次 Node 进程的系统时区。Node 遵循 `TZ`；如果没有该覆盖，时区由宿主或容器提供。显式 `timeZone` 必须是 IANA 标识符，并在插件加载时验证。
 
-`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，会为每次信号尚未中止且返回 enter 的合格 pre-step 添加上下文。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时添加上下文。
+`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，会为每次信号尚未中止且会进入步骤的合格步骤前处理添加上下文。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时添加上下文。
 
 ## 时序语义
 
-该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次中添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后、普通自动压缩（compaction）之前记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制、reject 或失败的 pre-step 不会记录任何内容。
+该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次中添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后、普通自动压缩（compaction）之前记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制、拒绝或失败的步骤前处理不会记录任何内容。
 
 正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的时间读数。因此，调度可以跨轮次以及进程恢复持续生效，不需要进程本地缓存状态。它会降低追加频率与历史增长，但绝不移除现有时间读数，且每个会话独立调度。
 
 第 1 步从前一条模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；挂钟时间倒退时，经过时长限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次时间读数，则报告 `unavailable`。
 
-时间读数记录的是一个已进入步骤的 pre-step 批次，不是已完成步骤或已传输请求。后续请求准备失败时，该读数可能已留在历史中；但下游 pre-step 监听器 reject 或失败时，该读数不会被记录。
+时间读数记录的是一个已进入步骤的步骤前批次，不是已完成步骤或已传输请求。后续请求准备失败时，该读数可能已留在历史中；但下游步骤前监听器拒绝或失败时，该读数不会被记录。
 
 单独发布的 `./invariant` 配套模块会根据当前未结束的轮次、下一个步骤前位置、经过时长基线与持久事件时间检查每个归因于插件的时间读数。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使时间读数失效。
 
diff --git a/packages/context/tmux-context/README.i18n.yaml b/packages/context/tmux-context/README.i18n.yaml
index c0446d8dfe..0e3f1898ad 100644
--- a/packages/context/tmux-context/README.i18n.yaml
+++ b/packages/context/tmux-context/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/context/tmux-context/README.md
 README.md: 26eff205b399bfcd20f55e91ef46cadbd70ae604
-README.zh.md: 6950443ce7ce9c46a605ef70500dd4f63c44163b
+README.zh.md: 7f256a829860df3f39e913d003b4e53d09243365
diff --git a/packages/context/tmux-context/README.zh.md b/packages/context/tmux-context/README.zh.md
index 6950443ce7..7f256a8298 100644
--- a/packages/context/tmux-context/README.zh.md
+++ b/packages/context/tmux-context/README.zh.md
@@ -33,7 +33,7 @@ exec tmux display-message -t "$TMUX_PANE" -p '<format>'
 
 ## 时序语义
 
-该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次前添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'tmux-context' }`。变化抑制与间隔调度会扫描原始持久会话事件中该来源的最近一次注入，因此调度可跨压缩与恢复的进程存续，无需进程内缓存状态；各会话独立调度。下游 pre-step 监听器 reject 或失败时，该读数不会被记录。
+该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会向返回的批次前置添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'tmux-context' }`。变化抑制与间隔调度会扫描原始持久会话事件中该来源的最近一次注入，因此调度可跨压缩与恢复的进程存续，无需进程内缓存状态；各会话独立调度。下游 pre-step 监听器拒绝或失败时，该读数不会被记录。
 
 ## 模型体验
 
diff --git a/packages/context/workspace-context/README.i18n.yaml b/packages/context/workspace-context/README.i18n.yaml
index 08b1d7a675..3cf32ff662 100644
--- a/packages/context/workspace-context/README.i18n.yaml
+++ b/packages/context/workspace-context/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/context/workspace-context/README.md
 README.md: 7ab21bbf8c72f8424bc8d4fdad9153c7ed8bb7e9
-README.zh.md: 7ad68759ab811cdc5e848fd686c7fad612c9b6d9
+README.zh.md: eb807bfc0611854d54eda3ff26c97c6af51da529
diff --git a/packages/context/workspace-context/README.zh.md b/packages/context/workspace-context/README.zh.md
index 7ad68759ab..eb807bfc06 100644
--- a/packages/context/workspace-context/README.zh.md
+++ b/packages/context/workspace-context/README.zh.md
@@ -6,9 +6,9 @@
 
 ## 生命周期
 
-每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。reject 或空的第一步决策会将基线留在 agent 的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。恢复后的会话会保留一条兼容的可见基线，并只追加当前文件的转换；如果发现、优先级、项目根目录或预算标识发生变化，则会将一条明确取代旧基线的完整基线折入进入步骤的批次。
+每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。被拒绝或为空的第一步决策会将基线留在 agent（智能体）的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。恢复后的会话会保留一条兼容的可见基线，并只追加当前文件的转换；如果发现、优先级、项目根目录或预算标识发生变化，则会将一条明确取代旧基线的完整基线折入进入步骤的批次。
 
-该插件还会观察第一方 `read`、`write` 和 `edit` 调用成功后产生的不可变 `tools/result`。每个已接受的 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件会在 agent inbox 中排入一项新增；已改变文件会排入一项替换；文件消失或成为同一目录中较早候选文件的重复项时，会排入一则移除通知。原生调用与 Code Mode 子分派共享该路径：嵌套 touch 会沿不透明的父级执行 token 逐层上浮，直到顶层结果落定；在 agent loop 步骤内产生的 touch，须等持久 `step/end` 后才开始异步投影。打开的步骤之外直接执行工具时，则立即投影。这样无需依赖文件系统时序，也能保持工具调用／结果／步骤的相邻关系。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
+该插件还会观察第一方 `read`、`write` 和 `edit` 调用成功后产生的不可变 `tools/result`。每个已接受的 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件会在 agent inbox 中排入一项新增；已改变文件会排入一项替换；文件消失或成为同一目录中较早候选文件的重复项时，会排入一则移除通知。原生调用与 Code Mode 子分派共享该路径：嵌套 touch 会沿不透明的父级执行 token 逐层上浮，直到顶层结果落定；在 agent loop（智能体循环）步骤内产生的 touch，须等持久 `step/end` 后才开始异步投影。打开的步骤之外直接执行工具时，则立即投影。这样无需依赖文件系统时序，也能保持工具调用／结果／步骤的相邻关系。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
 
 指令读取使用可选 `ctx.fs` 提供方。该插件不会静态注入 `fs`，因此没有提供方的产品树仍可启动，指令加载在提供方出现前不执行任何操作。它会解析每个候选文件并对解析结果执行 stat，因此会跟随路径最后一段的 symlink 到其目标：指向常规文件的链接会加载目标内容，缺失路径或非文件目标（包括指向目录的链接）则已确认不存在。resolve 或 stat 异常会改为将该候选文件的 scope 标记为暂时不可用。前缀取消与动态工具取消会传播到解析、元数据探测与流式读取。文件加载后的提供方失败会视为暂时不可用，而非文件已删除的证据。
 
@@ -48,7 +48,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 ## 状态与刷新
 
-模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会等待所有已排队投影完成，再把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；reject 则让当前上下文继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。即使后续复合结果被拦截，成功的嵌套文件 touch 也会聚合到父级执行 token 下；顶层结果会将这些 touch 交给当前打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界进入持久历史后释放其暂存的 touch；串行投影会根据可见会话事件和当前 inbox 协调状态，再替换唯一一条待处理工作区上下文。
+模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会等待所有已排队投影完成，再把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；若被拒绝，当前上下文则继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。即使后续复合结果被拦截，成功的嵌套文件 touch 也会聚合到父级执行 token 下；顶层结果会将这些 touch 交给当前打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界进入持久历史后释放其暂存的 touch；串行投影会根据可见会话事件和当前 inbox 协调状态，再替换唯一一条待处理工作区上下文。
 
 路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。
 
diff --git a/packages/examples/README.i18n.yaml b/packages/examples/README.i18n.yaml
index 506e867ef5..e77a9283b2 100644
--- a/packages/examples/README.i18n.yaml
+++ b/packages/examples/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/examples/README.md
 README.md: 2d672dcc307bb280cf3803f29128eba4988a8da0
-README.zh.md: e827e7cff4ff9d6521e5889e48270e06641ef38c
+README.zh.md: 24f64096dda0ccdac51afb90754ae25950750b89
diff --git a/packages/examples/README.zh.md b/packages/examples/README.zh.md
index e827e7cff4..24f64096dd 100644
--- a/packages/examples/README.zh.md
+++ b/packages/examples/README.zh.md
@@ -6,12 +6,12 @@
 
 | 包 | npm 名称 | 角色 |
 |---|---|---|
-| [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | 可复用的 agent 主干组合包 |
-| [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP 自动化应用组合包 |
+| [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | 可复用的 agent（智能体）主干组合包 |
+| [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP（Agent Client Protocol）自动化应用组合包 |
 | [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | 外部配置 JSON-RPC 运行时 |
 
-`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行归 `dsh run` 所有；本目录没有任何包提供该功能。
+`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行由 `dsh run` 提供；本目录没有任何包提供该功能。
 
-这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包只选择具体组合。
+这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包选择具体组合。
 
 不要将此组与仓库根目录的 [`examples/`](../../examples/AGENTS.md) 混淆：该目录存放可运行的 `cordis.yml` **叶节点**；此组存放这些叶节点加载的 **组合包**。
diff --git a/packages/examples/agent-spine-demo/README.i18n.yaml b/packages/examples/agent-spine-demo/README.i18n.yaml
index 3398b7296d..43cdef4af8 100644
--- a/packages/examples/agent-spine-demo/README.i18n.yaml
+++ b/packages/examples/agent-spine-demo/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/examples/agent-spine-demo/README.md
 README.md: d1c3c28183956b4f66db7ed4a6f3a08588b5352c
-README.zh.md: 936a317d23bf942802ecdd87f5ea4005974e4125
+README.zh.md: cf372a428c16893b1d328ea60ad70c09d6d9725c
diff --git a/packages/examples/agent-spine-demo/README.zh.md b/packages/examples/agent-spine-demo/README.zh.md
index 936a317d23..cf372a428c 100644
--- a/packages/examples/agent-spine-demo/README.zh.md
+++ b/packages/examples/agent-spine-demo/README.zh.md
@@ -59,7 +59,7 @@ import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```
 
-组合包将每个字段转发给拥有它的子节点。应用包提供预创建的 agent：无头和 JSON-RPC 组合会创建 `main`，ACP 应用则在 `session/new` 按需创建 agent。提示词、工具、标题、skill、workspace context、不变式、goal 和任务设置沿用其所属包记录的 schema 与默认值。`pickSpineConfig()` 只复制该组合包拥有的字段，`dshHome` 值冲突会在组合时失败。
+组合包将每个字段转发给拥有它的子节点。应用包提供预创建的 agent：无头和 JSON-RPC 组合会创建 `main`，ACP 应用则在 `session/new` 按需创建 agent。提示词、工具、标题、skill、工作区上下文、不变式、目标和任务设置沿用其所属包记录的 schema 与默认值。`pickSpineConfig()` 只复制该组合包拥有的字段，`dshHome` 值冲突会在组合时失败。
 
 例如，`{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` 会让包拥有的配套插件保持挂载，但抑制被阻止的拥有者。Blocklist 匹配优先于 allowlist 匹配；正则表达式与生命周期规则见 [`dsh-invariants`](../../support/invariants/README.md)。
 
diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml
index 0c44b4b476..686f8aaa3f 100644
--- a/packages/goal/goal-session/README.i18n.yaml
+++ b/packages/goal/goal-session/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/goal/goal-session/README.md
 README.md: 89413062de8cbb49d7066ec3ae42769a99c939a2
-README.zh.md: 45f61f2ea02b4a8112a88a3425ef3893128b3098
+README.zh.md: 075592e4e77e3336c1e2c08769ee255569e53360
diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md
index 45f61f2ea0..075592e4e7 100644
--- a/packages/goal/goal-session/README.zh.md
+++ b/packages/goal/goal-session/README.zh.md
@@ -23,7 +23,7 @@
 
 当对应的活跃 agent 实例处于 idle 状态，且目标 phase 为 active、已启用续行并有剩余容量时，驱动器先为待处理 goal 变更创建检查点，再预留 `roundsStarted + 1`，对应当前 `{ goalId, revision }`。它会排入一条 `<goal_round>` 提示词，并携带 `GoalMessageSource`。`agent/pre-step` 监听器会在下游监听器前后验证完整的已领取记录与当前 goal；只有进入步骤的 `user/message` 才会增加 `roundsStarted`。因陈旧而被拒绝的预留不会消耗 Round 编号。
 
-`MessageId` 通过持久 inbox 插入和领取来标识预留消息；它不标识轮次结果。用户消息不消耗 goal 上限。如果用户工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到 agent 进入 idle；混合批次中的待处理自动提示词会被拒绝，只有完成该检查点后才重新预留。
+`MessageId` 通过持久 inbox 插入和领取来标识预留消息；它不标识轮次结果。用户消息不消耗 goal 上限。如果用户工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到 agent 进入 idle；混合批次中的待处理自动提示词会被拒绝，只有在该检查点之后才重新预留。
 
 保留的提示词会点明经过 JSON 引用的目标与 `round/maxGoalRounds`，将当前工作区、工具结果和持久会话状态视为权威信息，要求在完成前提供证据，并要求在工作仍未完成时保持目标 active。引用可将多行或形似标签的目标文本保留为数据。goal 生命周期变更仍必须通过 `dsh-tool-goal` 的独立权限检查。
 
diff --git a/packages/hooks/README.i18n.yaml b/packages/hooks/README.i18n.yaml
index 6000d1396f..3aff382ea6 100644
--- a/packages/hooks/README.i18n.yaml
+++ b/packages/hooks/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/hooks/README.md
 README.md: 35989292313c6cef47c02041eb671a73ff7c5786
-README.zh.md: b5187fed159b0eaf5b2bace192152e612a85bc55
+README.zh.md: 3d169d1286f38658d98f4c5f8d016ef77e1b6517
diff --git a/packages/hooks/README.zh.md b/packages/hooks/README.zh.md
index b5187fed15..3d169d1286 100644
--- a/packages/hooks/README.zh.md
+++ b/packages/hooks/README.zh.md
@@ -10,4 +10,4 @@ hooks 子系统让用户像使用 Claude Code 和 Codex 一样，在生命周期
 | [`hooks-claude/`](hooks-claude/README.md) | Claude Code 钩子桥接 | 插件 |
 | [`hooks-codex/`](hooks-codex/README.md) | Codex 钩子桥接 | 插件 |
 
-共享库负责通用协议行为；各桥接负责自身方言的事件映射。子 README 记录这些契约。
+共享库负责通用协议行为；各桥接负责自身方言的事件映射。子 README 记录这些约定。
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index dda161c2d7..ae64984c31 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
 README.md: e807d9597eb5f811195bab9a0ad2b30b545e1205
-README.zh.md: f9990c046d4e52a2fa911776e92fcf397d159633
+README.zh.md: b77c8d658eddf7ce60faaf171e6f41e09b8ef333
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index f9990c046d..b77c8d658e 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -19,7 +19,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 
 ## 原语
 
-- **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`**：缺失、`''` 或 `'*'` 时匹配全部；`claude` mode 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符 = 精确匹配多选），其他 pattern 视为正则；`codex` mode 始终使用未锚定正则。桥接解析器会丢弃没有 matcher 匹配对象的事件所带字段，再用 `matcherDiagnostic` 拒绝事件实际使用的无效正则，并在注册任何钩子之前给出稳定诊断。运行时谓词仍会将无效 pattern 隔离为不匹配，因此直接调用本库不会向 agent loop（智能体循环）抛异常。
+- **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`**：缺失、`''` 或 `'*'` 时匹配全部；`claude` mode 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符 = 精确匹配交替），其他 pattern 视为正则；`codex` mode 始终使用未锚定正则。桥接解析器会丢弃没有 matcher 匹配对象的事件所带的 matcher 字段，再用 `matcherDiagnostic` 拒绝事件实际使用的无效正则，并在注册任何钩子之前给出稳定诊断。运行时谓词仍会将无效 pattern 隔离为不匹配，因此直接调用本库不会向 agent loop（智能体循环）抛异常。
 - **`runHook(bash, hook, options, now)`**：要求并转发调用方拥有的 `options.signal`，将 `options.payload` 序列化到 hook stdin（当且仅当 `options.trailingNewline` 时添加尾随换行符），在执行器凭证清理后合并 `options.env`（`dsh-bash` 受信任插件接口），遵循 hook 的 `timeoutSec`（否则使用 `options.defaultTimeoutMs`；默认值属于桥接，其配置默认为 lib 的 `DEFAULT_HOOK_TIMEOUT_MS` 10 分钟参考值），再解码结果（将 `options.expectedEventName` 传递给 codec）。因此取消会到达执行器的进程组终止与 join 边界。它绝不抛出异常：执行器拒绝（基础设施故障）会变为 `HookOutput`，其 `exitCode: undefined`（非阻塞错误）。`now` 会被注入，以便测试持续时间。
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** 解码退出状态与结构化 stdout。退出码为 2 时，会以 stderr 内容阻止执行；其他失败不阻塞。匹配的 hook 特定权限决策会覆盖遗留顶层决策；事件判别字段不匹配或缺失只会抑制事件特定字段。顶层字段仍与事件无关，成功但非 JSON 的输出会留给桥接处理。
 - **`mergeHookOutputs(outputs)`**：折叠在一个点上匹配的每个 hook 结果：权限优先级为 **deny > ask > allow**，从首个 `continue:false` 起，halt 状态保持不变，阻塞原因用 `\n\n` 连接，`additionalContext`／`systemMessages` 按顺序累积。
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 627f624235..1f02adea1d 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
 README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
-README.zh.md: aeaf1b29e5a71674c9feedb30b67f9ce11c47340
+README.zh.md: 4de15316fe31d75361fd3b8655c7c1f7d5fa4a02
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index aeaf1b29e5..4de15316fe 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+所有客户端形态共用的 API 网关：TS 约定（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
 
 ## 默认路由（`api-gateway` 设置段）
 
@@ -10,9 +10,9 @@
 
 会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
 
-`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不支持推理的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不带推理等级的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
 
-设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不支持推理的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
+设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不带推理等级的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
 
 存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
 
@@ -24,7 +24,7 @@
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent（智能体），然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
@@ -32,9 +32,9 @@
 
 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
-会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
+会话模型路由属于会话领域约定。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
 
-待处理的 queued 输入属于实时控制平面契约，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
+待处理的 queued 输入属于实时控制平面约定，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
 
 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create({ name })` 会在配置根目录下创建显示标题唯一的目录，而 `workspace.create({ path })` 会接纳已有的规范目录，并允许由 basename 派生的标题重复。`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。`workspace.archiveSession` 向注册表级全局归档集合添加一个会话，并应答完整的更新后集合；`workspace.list` 携带该集合作为重连基线，`host/archived-sessions-changed` 在每次持久变更后推送完整快照。归档只把会话从各分组视图中隐藏，不触碰其日志和 workspace 记账；既非实时也未持久化的会话以 `session-not-found` 失败。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
 
@@ -46,9 +46,9 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。对于 `.html`、`.htm`、`.xhtml` 与 `.svg`，macOS 和桌面 Linux 会优先使用能够确定的默认浏览器；无法确定时回退到上述应用交接。WSL 会通过 `wslpath -w` 转换每个 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，浏览器可渲染的文档也不例外，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
 
-`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的入口。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此每一种前端（web、TUI、ACP、手动键入的文本）共享同一条确定性路径，没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和 skill（技能）目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的入口。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此每一种前端（web、TUI、ACP（Agent Client Protocol）、手动键入的文本）共享同一条确定性路径，没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
-`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
+`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
 ## 载体层（`/client` + 根路径）
 
@@ -69,4 +69,4 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 - **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。
 - **搜索失败会包含提供方诊断信息**：网关是单用户本地服务。将其暴露给多名用户的载体必须用可安全公开的诊断信息替代内部搜索细节。
 - **Linux 原生选择器依赖桌面工具**：在 `native` 能力下，Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；组合层面的回退是 browse 后端（见 [native 后端 README](../directory-picker-native/README.md)）。
-- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会按晚于其最后一次真实活动的时间排序。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note（agent 决策记录）](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。
+- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会按晚于其最后一次真实活动的时间排序。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。
diff --git a/packages/interaction/tool-ask-user/README.i18n.yaml b/packages/interaction/tool-ask-user/README.i18n.yaml
index f88c303525..4feb6f3b0f 100644
--- a/packages/interaction/tool-ask-user/README.i18n.yaml
+++ b/packages/interaction/tool-ask-user/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/interaction/tool-ask-user/README.md
 README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
-README.zh.md: 3f7b814b83c8c6957a4b2574ee69e87d45f65ae6
+README.zh.md: 5e5e8f2a8208c003c68ce1f3992c0bd34f2cb552
diff --git a/packages/interaction/tool-ask-user/README.zh.md b/packages/interaction/tool-ask-user/README.zh.md
index 3f7b814b83..5e5e8f2a82 100644
--- a/packages/interaction/tool-ask-user/README.zh.md
+++ b/packages/interaction/tool-ask-user/README.zh.md
@@ -54,5 +54,5 @@
 ## 已知限制与暂缓事项
 
 - **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
-- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝由另一个 agent 所有的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久化会话谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
+- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝归属于另一个 agent 的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
 - **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index aafe594c7e..6326ea0dee 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
 README.md: cba015e782623b3a5adf018303823577a0b96774
-README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
+README.zh.md: acfacd1cef8150d6995d5c6285b5a331310fb89b
diff --git a/packages/interaction/user-interaction/README.zh.md b/packages/interaction/user-interaction/README.zh.md
index a5f944850c..acfacd1cef 100644
--- a/packages/interaction/user-interaction/README.zh.md
+++ b/packages/interaction/user-interaction/README.zh.md
@@ -22,7 +22,7 @@
 
 对于单选题，`custom` 会覆盖选中的选项，且 `selected` 为空。对于多选题，`custom` 可以补充 `selected` 中的标签。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。
 
-请求包含 agent 时，`ask()` 会通过当前 `AgentRegistry` 验证该 agent 与注册表中的存活实例是同一对象，并且只允许运行时根调用。持久化会话谱系不构成权限依据：带有历史委托深度的会话恢复为新的运行时根后可以提问；由另一个 agent 所有的存活子级即使持久化深度为零也会被拒绝。不含 agent 的程序化请求继续沿用现有提供方路径。
+请求包含 agent 时，`ask()` 会通过当前 `AgentRegistry` 验证该 agent 与注册表中的存活实例是同一对象，并且只允许运行时根调用。持久谱系不构成权限依据：带有历史委托深度的会话恢复为新的运行时根后可以提问；归属于另一个 agent 的存活子级即使持久化记录的委托深度为零也会被拒绝。不含 agent 的程序化请求继续沿用现有提供方路径。
 
 ### 呈现意图
 
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 790989c5d6..37ea49150b 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
 README.md: eb67ce889193aadbd694d7aae53e47c7d20703be
-README.zh.md: b4b3e3c208702fa10e5f434a70608702d0576fbd
+README.zh.md: 8b8e5e6a219841d700db7161a7352a1880c41165
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index b4b3e3c208..8b8e5e6a21 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -4,7 +4,7 @@
 
 基于 [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) 的 harness LLM（大语言模型）seam 通用多提供方适配器。一个插件实例拥有一份以路由为键的提供方 profile 字典；每个请求使用 `GenerateOptions.provider` 选择 profile，并针对该路由已配置的 catalog 解析 `GenerateOptions.model`。点名了已安装 pi-ai 提供方的路由会继承其端点、协议格式与模型 catalog 作为默认值，并逐字段覆盖；pi-ai 未提供的路由则整体声明出来，因此接入 OpenAI 兼容网关、自建服务，或比已安装 catalog 更新的提供方，都属于配置而非改代码。
 
-包（package）根入口导出 Cordis 插件契约、`PiAiAdapter` 与 `supportedProtocols()`；profile 解析、catalog 物化、提供方构造、回放转换和流转换保留在包内部。
+包根入口导出 Cordis 插件约定、`PiAiAdapter` 与 `supportedProtocols()`；profile 解析、catalog 物化、提供方构造、回放转换和流转换保留在包内部。
 
 ## 配置
 
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 30660e1032..4b1eda16c0 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
 README.md: ddbc2ea482ca0848fb0ee0813839cf5ff1829bcc
-README.zh.md: 7a3b615d134e27d7c9892d6f411066d89938175b
+README.zh.md: 0ebb99c6e3743b881905110985575d348f1c7601
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 7a3b615d13..0ebb99c6e3 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -26,7 +26,7 @@
 
 `LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
 
-询问端点属于配置期针对**草稿**的操作，因此以 settings namespace 而非提供方路由为键：界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器应当用自己的知识作答——元数据更好，且无需联网——这正是 `baseURL` 可选、两者必居其一的原因。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
+询问端点属于配置期针对**草稿**的操作，因此以 settings namespace 而非提供方路由为键：界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器应当用自己的知识作答——元数据更好，且无需联网——这正是 `baseURL` 可选、两者至少要有一个的原因。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
 
 提供方与模型元数据是发现接口，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。
 
@@ -97,5 +97,5 @@
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **受产生方约束的变体在实际产生前不会加入**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。
-- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：该公开主页必须在首次发布前可访问。
+- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：该公开主页必须在发布前可访问。
 - **`GenerateOptions.sessionId` 是本地声明的品牌类型**：导入 dsh-session 的 `SessionId` 会产生循环；未来拥有 id 的包可以消除该权宜之计。
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index 5c5a597802..a174ba4233 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/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/llm/token-meter/README.md
 README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
-README.zh.md: 3621105ff35606b62b0587063038116b4772c6cf
+README.zh.md: 8bdf86517abaff79b78346549ff79b2fff93486a
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index 3621105ff3..8bdf86517a 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -29,9 +29,9 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 
 `contextPressure` 携带可选的 `pressureTokens`（提供方报告的最新提示词规模，为未缓存输入加缓存读取与写入之和）、可选的 `projectedTokens`，以及来自最新一条 `request/context` 记录的可选 `contextWindow`。提供方报告用量前两个数字都保持缺失；路由适配器未公布容量时容量也保持缺失。输出不计入其中，因此轮次流式输出期间 `pressureTokens` 保持不动，等到下一个请求报告用量时才前进。
 
-`projectedTokens` 是「下一个请求的提示词要花多少」：在该样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零，折叠走的是测量服务重放的同一份 `surface-fold.ts`。只有增量部分是估算的，因此这个数字既锚定在提供方读数上，又能在内容落地——或压缩遮蔽一段区间——的瞬间做出反应。最后这种情况正是该字段存在的理由：压缩通过直连的 `ctx.llm.stream()` 调用生成摘要，自身不追加任何用量，所以仅凭 `pressureTokens` 会一直报告压缩前的提示词规模，直到又跑完一整轮为止。占用率展示读取 `projectedTokens`。
+`projectedTokens` 是「下一个请求的提示词要花多少」：在该样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零，折叠走的是测量服务重放的同一份 `surface-fold.ts`。只有增量部分是估算的，因此这个数字既锚定在提供方读数上，又能在内容落地——或压缩遮蔽一段区间——的瞬间做出反应。最后这种情况正是该字段存在的理由：压缩通过直连的 `ctx.llm.stream()` 调用生成摘要，自身不追加任何用量，所以仅凭 `pressureTokens` 会一直报告压缩前的提示词规模，直到再完成一整个轮次为止。占用率展示读取 `projectedTokens`。
 
-`contextBreakdown` 携带启发式的 `systemTokens`、`toolsTokens` 与 `messageTokens`，描述上下文的组成而非提供方计费规模。envelope 数字在每条 `request/header` 上按后者胜重新计价；消息数字重放 `surface-fold.ts`——与 `measure()` 运行的位置折叠是同一份——因此它在每个事件边界上都等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。三个数字都使用测量服务的固定启发式规则，属于估算值：它们加起来不等于 `projectedTokens`——后者的提供方锚点恰好把这些明细行仍然带着的误差排除在外（按「4 字符 ≈ 1 token」计价，CJK 文本与 JSON schema 会被严重低估）。请把它们当作近似的**组成**呈现，而不是总量。
+`contextBreakdown` 携带启发式的 `systemTokens`、`toolsTokens` 与 `messageTokens`，描述上下文的组成而非提供方计费规模。envelope 数字在每条 `request/header` 上按后者胜重新计价；消息数字重放 `surface-fold.ts`——也就是 `measure()` 运行的同一个带位置 fold——因此它在每个事件边界上都等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。三个数字都使用测量服务的固定启发式规则，属于估算值：它们加起来不等于 `projectedTokens`——后者的提供方锚点所体现的恰好是这些明细行仍然带着的误差（按「4 字符 ≈ 1 token」计价，CJK 文本与 JSON schema 会被严重低估）。请把它们当作近似的**组成**呈现，而不是总量。
 
 三个单元都使用标准的投影基线、实时帧、seq 高者胜值仓和 JSON 检查点路径。卸载 token-meter 会移除这三个键。不带投影 seam 的组合会保留测量服务的既有行为。
 
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 9fa4504cca..ff00f20c67 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/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/mcp/mcp-client/README.md
 README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: eb9e0dbdb48423cc4bc698fda355e973e42bc7a3
+README.zh.md: 6537e52eaaea9193d2d95fd0ddf1b4202e5ace38
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index eb9e0dbdb4..6537e52eaa 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -61,7 +61,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
 - Native／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
-- 断开／崩溃时：不自动重新连接。已注册工具会一直保留到插件完成资源释放或成功重新同步，针对已关闭传输的调用可能失败；请通过 HMR 重新加载或重启 Host 来重新连接。
+- 断开／崩溃时：不自动重新连接。已注册工具会一直保留到对插件执行 dispose（资源释放）或成功重新同步，针对已关闭传输的调用可能失败；请通过 HMR 重新加载或重启 Host 来重新连接。
 
 ## 消费的服务
 
@@ -75,7 +75,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 #### 模型看到的内容
 
-初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步会替换整个世代；对插件执行 dispose（资源释放）会移除该世代。
+初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步会替换整个世代；对插件执行 dispose 会移除该世代。
 
 #### Token 影响
 
diff --git a/packages/sandbox/sandbox-local/README.i18n.yaml b/packages/sandbox/sandbox-local/README.i18n.yaml
index cbc1e9ad55..13fa52ce9d 100644
--- a/packages/sandbox/sandbox-local/README.i18n.yaml
+++ b/packages/sandbox/sandbox-local/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/sandbox/sandbox-local/README.md
 README.md: 23d3a32451c105c71c0a7399ed051288b70753f3
-README.zh.md: 165a6fc88a9fdd219c3ddb016cdf415504556d8c
+README.zh.md: 1890771faf8cab6b1842f973a999c7a9cf2dbb11
diff --git a/packages/sandbox/sandbox-local/README.zh.md b/packages/sandbox/sandbox-local/README.zh.md
index 165a6fc88a..1890771faf 100644
--- a/packages/sandbox/sandbox-local/README.zh.md
+++ b/packages/sandbox/sandbox-local/README.zh.md
@@ -8,11 +8,11 @@
 
 不受支持的平台和不可用 runner 会以 `SANDBOX_UNAVAILABLE` 拒绝执行；执行绝不会静默回退为不受限制。每次包装都携带结构化 runner 失败规则，使消费方能够区分损坏的沙箱与命令失败。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择依据与 profile 差异。
 
-策略逐调用传入；提供方只存储机制与缓存的 runner 结论。每次包装都会报告强制执行完整度，以及后端专用的拒绝签名和 runner 失败规则。Landlock 只有在退出码为 125，且排除唯一精确匹配的部分强制执行通知后仍存在一行 `landlock-run:` 致命诊断时，才判定 runner 失败；携带该通知的子进程即使以 1、2 或 125 退出，也仍按子进程结果处理。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开契约均未保留 launcher 失败状态。消费方会直接 spawn 返回的 argv，因此 runner 缺失或不可执行属于带外 spawn 失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。`runnerCommand` 会跳过探测，并要求为自定义 runner 自身的致命方言提供一个或多个非空、单行、不区分大小写的 `runnerFailureSignatures` 条目。由于其机制未知，它会同时携带两种 Linux 拒绝方言。`probeTimeoutMs` 限制功能探测。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择与失败语义。
+策略逐调用传入；提供方只存储机制与缓存的 runner 结论。每次包装都会报告强制执行完整度，以及后端专用的拒绝签名和 runner 失败规则。Landlock 只有在退出码为 125，且仅排除完全匹配的部分强制执行通知后仍存在一行 `landlock-run:` 致命诊断时，才判定 runner 失败；携带该通知的子进程即使以 1、2 或 125 退出，也仍按子进程结果处理。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开约定均未保留 launcher 失败状态。消费方会直接 spawn 返回的 argv，因此 runner 缺失或不可执行属于带外 spawn 失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。`runnerCommand` 会跳过探测，并要求为自定义 runner 自身的致命方言提供一个或多个非空、单行、不区分大小写的 `runnerFailureSignatures` 条目。由于其机制未知，它会同时携带两种 Linux 拒绝方言。`probeTimeoutMs` 限制功能探测。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择与失败语义。
 
 Seatbelt profile 默认允许，但带 `(deny file-write*)` 和写入 allow-list，因此恰好约束相应模式承诺的文件操作：`read-only` 只授予 `/dev/null` 字面路径；`workspace-write` 另加工作区根目录、`/tmp` 和逐用户 darwin 临时目录（`os.tmpdir()`，即平台供 mkstemp 家族工具使用的真实临时区域）。每个根目录都经过规范化，因为 Seatbelt 匹配解析后的路径（`/tmp` 就是 `/private/tmp`）。Apple 将 `sandbox-exec` CLI（命令行界面）标为 deprecated，但所有 macOS 系统仍会提供它；若情况发生变化，功能探测会使执行被拒绝。
 
-[`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run)提供平台 launcher、功能探测和 CLI 参数词汇。该提供方只负责模式到授权的映射与 runner 选择。把路径解析和探测解析保留在带版本的 binary 中，可防止契约漂移。
+[`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run)提供平台 launcher、功能探测和 CLI 参数词汇。该提供方只负责模式到授权的映射与 runner 选择。把路径解析和探测解析保留在带版本的 binary 中，可防止约定漂移。
 
 ```yaml
 - id: sandbox
diff --git a/packages/sandbox/sandbox-policy/README.i18n.yaml b/packages/sandbox/sandbox-policy/README.i18n.yaml
index 0b626d5343..27bcc3b85f 100644
--- a/packages/sandbox/sandbox-policy/README.i18n.yaml
+++ b/packages/sandbox/sandbox-policy/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/sandbox/sandbox-policy/README.md
 README.md: b2512790c5cf5b3a06523cf91b50dd5d288b1522
-README.zh.md: dda98b7aa4775ac2453704295df87c3c92025093
+README.zh.md: 58354adf55a55951cad1ea9adb88aea2457c7f7b
diff --git a/packages/sandbox/sandbox-policy/README.zh.md b/packages/sandbox/sandbox-policy/README.zh.md
index dda98b7aa4..58354adf55 100644
--- a/packages/sandbox/sandbox-policy/README.zh.md
+++ b/packages/sandbox/sandbox-policy/README.zh.md
@@ -17,7 +17,7 @@
 
 - `ctx.sandboxPolicy.resolve({ session?, mode? })`：解析一项完整的逐调用策略。显式批准的模式优先于会话最后一条 `sandbox/mode` 事件，后者又优先于 `defaultMode`；会话不可变的 `cwd` 会先按文件系统语义规范化，再成为 `workspaceRoot`，否则使用配置的回退值。规范化先于词法归一化，因此 `symlink/..` 与进程工作目录解析保持一致。
 - `ctx.sandboxPolicy.defaultMode`／`ctx.sandboxPolicy.workspaceRoot`：`resolve()` 使用的部署默认值与回退根目录。
-- `sandbox:policy`：直接派生自 `resolve({ session })` 的请求时缓存安全上下文贡献。它说明该模式中与具体能力无关的文件效果契约，以及 `workspace-write` 下规范化的会话工作区；工具归属方仍负责操作特定的拒绝与升权引导。
+- `sandbox:policy`：直接派生自 `resolve({ session })` 的请求时缓存安全上下文贡献。它说明该模式中与具体能力无关的文件操作约定，以及 `workspace-write` 下规范化的会话工作区；工具归属方仍负责特定于操作的拒绝与升权引导。
 - `effectiveSandboxMode(events)`：会话 `sandbox/mode` 事件的纯 fold（最后一次切换胜出，没有则为 `undefined`），在 `resolve()` 内使用。
 - `setSandboxMode(session, mode)`：逐会话覆盖的唯一写入路径：恰好追加一条 `sandbox/mode` 事件。切换本身就是事件；不会在带外修改模式。
 - `SANDBOX_MODES`：所有模式，用于选项展示与运行时验证。
@@ -34,7 +34,7 @@
 
 #### 模型看到的内容
 
-每个 agent 会话的当前运行时上下文快照中都有一项 `sandbox:policy` 贡献。它不枚举已装载的能力。工具插件继续负责操作与升级引导，批准策略单独贡献给同一份快照，计划引导仍由 `dsh-plan-mode` 的系统段落管理。
+每个 agent 会话的当前运行时上下文快照中都有一项 `sandbox:policy` 贡献。它不枚举已装载的能力。工具插件继续负责操作与升权引导，批准策略单独贡献给同一份快照，计划引导仍由 `dsh-plan-mode` 的系统段落管理。
 
 ##### 只读
 
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index e0ce60a641..5d9e9eabd2 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
 README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
-README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b
+README.zh.md: 3cb2cadffdacd037486223793604127f10b162bb
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 903dfbe601..3cb2cadffd 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 独立应用配置
 
-每个 profile 都以之为起点的随附 `dsh-base` 组合包包含一个空 `repository-plugins` 配置项。用户可在用户 patch 层中替换该配置项的配置来启用精确指定的 GitHub generation：写入 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，或写入各 profile 共享的 home 级 `$DSH_HOME/cordis.patch.yml`；`--patch` overlay 则只为单次运行 patch 同一配置项：
+随附的 `dsh-base` 组合包是每个 profile 的起点，其中包含一个空 `repository-plugins` 配置项。用户可在用户 patch 层中替换该配置项的配置来启用精确指定的 GitHub generation：写入 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，或写入各 profile 共享的 home 级 `$DSH_HOME/cordis.patch.yml`；`--patch` overlay 则只为单次运行 patch 同一配置项：
 
 ```yaml
 - id: repository-plugins
@@ -43,7 +43,7 @@
 
 每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为精确配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
 
-长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套 repository Plugin generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入 repository Plugin 的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
+长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套仓库插件 generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入仓库插件的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
 
 ## 准备阶段
 
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 2ab76b4da9..5a4c078a55 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-persistence-jsonl/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
 README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
-README.zh.md: 59d21c6171e857849c4ab48940d66962fffbfdeb
+README.zh.md: e260c7671a1f60eec23852ac27ee5da38425b5fd
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 59d21c6171..e260c7671a 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -26,7 +26,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 | `root` | `string`（必需） | 所有会话文件的根目录。**无默认值**：`process.cwd()` 默认值会随进程 cwd 变更（bash 调用、子进程）而分散文件。现有根必须是可读目录；缺失根在第一次实体化时创建。 |
 | `packChunks` | `boolean`（默认 `true`） | 将符合条件的 delta 分片连续段写为打包行（在真实编码会话上测得逻辑日志约小 60%）。设为 `false` 可用于每事件一行诊断；无论该写入侧开关如何，都能读取打包行。 |
 | `compression` | `'zstd' \| 'none'` | 默认 `'zstd'`；`'none'` 保留换行分隔 UTF-8 文本。 |
-| `preparedSessionCacheSize` | 正整数（默认 `5`） | 冷历史检查后保留、供恢复复用的未发布 Session 数量上限。 |
+| `preparedSessionCacheSize` | 正整数（默认 `5`） | 冷历史检查后保留、供恢复复用的未发布会话数量上限。 |
 | `writeBatchMaxDelayMs` | 正整数（默认 `200`） | 空闲的活动事件队列收到待写入事件后开启的固定合并窗口。后续事件不会重置窗口；flush 与 teardown 会绕过它。该值不限制事件循环、串行化操作或后端延迟。最大值为 Node 计时器上限 `2_147_483_647` ms。 |
 
 `locate(meta)` 返回已解析项目/会话目录内固定 transcript 的 `{ kind: 'jsonl', path }`。它不执行文件系统 I/O：可以在目录或文件存在前返回目标，现有文件也只包含最近一次 flush 完成的前缀。
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index f6d2d2926b..bb8335b826 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-persistence-sqlite/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-sqlite/README.md
 README.md: 4961f62bf6854c343d35b8406c9d721590274534
-README.zh.md: 8610ef56f737bac8781536ea26a5b48dbf67ed48
+README.zh.md: 237352d1661f505ec0352dfc3eae48d9b636e44a
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index 8610ef56f7..237352d166 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -22,7 +22,7 @@ SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[
 - **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
 - **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会删除撕裂尾部行、追加恢复行或更改轻量修订。
-- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该 revision 及其事件行，`readStoredRevision()` 则只查询 session 行来校验保留的 preparation。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
+- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该修订及其事件行，`readStoredRevision()` 则只查询会话行来校验保留的准备结果。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
 
 ## 配置（schemastery）
 
@@ -37,7 +37,7 @@ interface Config {
 
 ## 写入路径
 
-与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订版本递增。
+与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订递增。
 
 ## 模型体验
 
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 5b131371b8..b6c2b25e6f 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-persistence/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence/README.md
 README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
-README.zh.md: 1ef7eb6c6c507167f61bb5df7c4ce8183aac5d0d
+README.zh.md: 6b02f37343da07a80953ecb9d05e5903bd42d95c
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index 1ef7eb6c6c..6b02f37343 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -8,14 +8,14 @@
 
 ## 服务 API（`ctx.sessionPersistence`）
 
-| 方法 | 契约 |
+| 方法 | 约定 |
 |---|---|
 | `locate(meta): SessionLocation \| undefined` | 在不执行 I/O 或实体化的情况下解析绝对的每会话产物目标。没有独立本地产物的后端返回 `undefined`。 |
 | `create(meta): Promise<void>` | 注册新会话元数据。可以将物理写入延迟到第一次 `append`（延迟实体化）。 |
 | `append(id, events): Promise<void>` | 持久保存一个批次。仅追加；任何修复后，第一个事件 `seq` == 已存储 next-seq；非 JSON 可序列化数据会被拒绝，并命名违规类型。 |
-| `prepare(id, signal?): Promise<SessionPreparation>` | 预留恢复使用的精确未发布 Session。协调器会尽可能复用之前的检查结果、提交待处理恢复，并在 dispose 时将未发布 reservation 释放回有界缓存。 |
+| `prepare(id, signal?): Promise<SessionPreparation>` | 预留恢复所使用的那个未发布 Session。协调器会尽可能复用之前的检查结果、提交待处理恢复，并在 dispose 时将未发布 reservation 释放回有界缓存。 |
 | `load(id): Promise<{ meta; events }>` | 在升级受支持的同版本形状后返回不可变、平衡的逻辑日志，并提交冷恢复。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result`/`step/end?`/`turn/end {interrupted}` 事件持久关闭它。只丢弃撕裂尾部碎片；已提交损坏、格式错误的形状和未知 `version` 会被拒绝。 |
-| `inspect(id, signal?): Promise<{ meta; events }>` | 返回已经升级、验证和深度冻结的逻辑视图，但不提交恢复或发布 Session。冷视图会获得仅存在于内存的合成恢复 closer，物理撕裂尾部保持不变；已经实时存在的视图则是当前不可变快照，可能包含打开的 turn。基于协调器的实现会在有界 LRU 中保留精确的冷未发布 Session，供后续 `prepare` 使用，但已存储 revision 变化后会丢弃并重新读取。同 id 检查共享进行中的读取。 |
+| `inspect(id, signal?): Promise<{ meta; events }>` | 返回已经升级、验证和深度冻结的逻辑视图，但不提交恢复或发布 Session。冷视图会获得仅存在于内存的合成恢复 closer，物理撕裂尾部保持不变；实时状态下的视图则是当前不可变快照，可能包含开放的轮次。基于协调器的实现会在有界 LRU 中保留该冷状态下未发布的 Session 本身，供后续 `prepare` 使用，但已存储修订值变化后会丢弃并重新读取。同 id 检查共享进行中的读取。 |
 | `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | 脱离的物理后缀原语：返回 `seq >= fromSeq` 的有效已存储事件，不进入 preparation 缓存、不截断、不合成 closer，也不发布协调器状态。`fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（SQLite）只读后缀，除非受支持的旧形状需要前缀上下文才能完成规范化；顺序后端（JSONL）解析整个产物并向前跳过。用于只续折水位之后尾部的 checkpoint 消费方。 |
 | `list(signal?): Promise<SessionHeader[]>` | 从元数据轻量列出，不解析完整日志。可选信号取消后端列表工作。零事件延迟实体化会话不在 `list` 中。 |
 | `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | 返回轻量元数据和每份日志一个不透明、带品牌类型的修订值，不加载事件日志。日志及其后端存储不变时，修订保持相等；append 或变更性 load 修复后会改变；不会仅因两个存储使用相同本地计数器而冲突。可选信号请求取消后端发现工作；第一方后端会先等待所有已启动的列出工作结束，再予以拒绝，因此调用返回拒绝时，相关工作已完全停稳。 |
@@ -33,13 +33,13 @@
 
 每个 `session/event` 将事件复制到会话 controller。第一个待处理事件会开启固定批处理窗口；后续事件会加入该批次，但不会重置截止时间。配置的 `writeBatchMaxDelayMs` 只限制这段有意等待，而不限制事件循环、初始化、串行化操作或后端延迟。写入期间接纳的事件会形成一个新的有界批次。`session/flush` 会取消等待，并作为共享的完全停稳屏障，排空屏障运行期间接纳的事件。后台写入失败只记录一次日志，保留顺序不变的批次，并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 或后端拆卸会立即重试，并在失败再次发生时向调用方暴露失败。
 
-崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源 revision 仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留精确 Session，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
+崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源修订值仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留该 Session 本身，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
 
-后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 重构前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构无法获得的取消来源的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无 owner 状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 重构前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
+后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 引入前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构无法获得的取消来源的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无所有者状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
 
 实时会话发出 `session/disposed` 时，协调器等待其 controller，串行化最终 drain，然后释放该精确 `Session` 对象拥有的状态。失败退役会将 controller 保留在实时会话 map 中，使后端拆卸可重试。后端拆卸先停止事件接纳，flush 每个剩余 controller，等待每 id 操作，最后才关闭存储句柄。
 
-无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和 revision 身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
+无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
 
 `PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一 seam）：
 
@@ -47,14 +47,14 @@
 |---|---|
 | `name` | dispose 失败 `AggregateError` 的后端标签。 |
 | `loadStored(id, signal?)` | 在全部存储范围中按 id 读取已存储前缀。用于恢复／加载、非修改式 inspect、实时接管和 create 冲突探测。可选信号属于仅观察读取。返回元数据标识 `id`；`revision` 精确标识返回的 header 和事件；当且仅当必须截断撕裂尾部时才存在不透明 `tornMarker`。 |
-| `readStoredRevision(id, signal?)` | 在不加载事件日志的情况下读取一个 id 当前的来源限定 revision。它使用与 `loadStored` 相同的 revision 表示；id 不存在时返回 `undefined`。 |
+| `readStoredRevision(id, signal?)` | 在不加载事件日志的情况下读取一个 id 当前的来源限定修订值。它使用与 `loadStored` 相同的修订值表示；id 不存在时返回 `undefined`。 |
 | `loadStoredFrom?(id, fromSeq, signal?)` | 服务 `readFrom` 背后的可选可寻址后缀读取：返回 header 和 `seq >= fromSeq` 的已存储事件，非变更、无撕裂标记。SQLite 实现它（`WHERE seq >= ?`）；不实现的后端使用协调器回退——`loadStored` 加向前跳过。 |
 | `appendBatch(meta, events, isMaterialized)` | 持久追加连续批次；尚未实体化时以原子方式延迟实体化。 |
 | `commitRepair(meta, tornMarker, closers)` | 使崩溃修复持久：截断撕裂尾部（当且仅当 `tornMarker !== undefined`；标记可为 falsy，例如 seq/offset `0`），并追加 `closers`。不要求原子性。由 load（截断 + closer）和实时接管（仅截断）使用。 |
 | `list(signal?)` | 列出全部已存储元数据，并遵循可选的取消信号。 |
 | `close?()` | 可选生命周期拆卸（例如关闭 db 句柄），在 dispose drain 后等待。 |
 
-协调器断言已存储 id，并在修复或实时接管前比较已存储/实时 cwd。其 `inspect()` 路径取得新鲜后端值的所有权，只验证和冻结一次，并在不调用 `commitRepair` 的情况下最多保留配置数量的未发布 Session。只有保留源的 revision 仍等于 `readStoredRevision` 时，系统才会复用或修复它；否则协调器会重新读取。该新鲜性校验不会增加跨进程写入排他。持久日志在一次读取与复核往返内保持不变时，revision 重试才能收敛；持续的外部写入可能延迟 `load`、`inspect` 或 `prepare`。`tornMarker` 完全不透明：协调器只测试 `!== undefined`，并将其原样往返给 `commitRepair`，绝不检查值（JSONL 后端使用待截断字节偏移，SQLite 后端使用待删除 seq）。第三方后端可以不用协调器直接实现抽象服务，但必须提供相同非变更检查和可信轻量快照修订。详见[写入协调器 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)。
+协调器断言已存储 id，并在修复或实时接管前比较已存储/实时 cwd。其 `inspect()` 路径取得新鲜后端值的所有权，只验证和冻结一次，并在不调用 `commitRepair` 的情况下最多保留配置数量的未发布 Session。只有保留源的修订值仍等于 `readStoredRevision` 时，系统才会复用或修复它；否则协调器会重新读取。该新鲜性校验不会增加跨进程写入排他。持久日志在一次读取与复核往返内保持不变时，修订值重试才能收敛；持续的外部写入可能延迟 `load`、`inspect` 或 `prepare`。`tornMarker` 完全不透明：协调器只测试 `!== undefined`，并将其原样往返给 `commitRepair`，绝不检查值（JSONL 后端使用待截断字节偏移，SQLite 后端使用待删除 seq）。第三方后端可以不用协调器直接实现抽象服务，但必须提供相同非变更检查和可信轻量快照修订。详见[写入协调器 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)。
 
 ## 元数据与位置类型
 
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 34c1910b16..746d64865d 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/README.i18n.yaml
@@ -1,6 +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/session-projection/session-projection/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection/README.md
 README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
-README.zh.md: f60a48bd41f0c33edb85a495ada9b6818ec46ee5
+README.zh.md: 02f1876fc95b5e400f63ae6a0dd1910da4f63c3b
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index f60a48bd41..02f1876fc9 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-会话投影 seam。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)记录了设计理由。
+会话投影 seam。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) 记录了设计理由。
 
 ## 服务：`SessionProjectionRegistry`（ctx 键：`sessionProjections`）
 
diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
index 0424414fac..f3a790b362 100644
--- a/packages/session/session-telemetry-otel/README.i18n.yaml
+++ b/packages/session/session-telemetry-otel/README.i18n.yaml
@@ -1,6 +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/telemetry/session-telemetry-otel/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry-otel/README.md
 README.md: 585995ce409255df9608bc33b76625374bc67669
-README.zh.md: 6d2cfa4d492cee7f90d557c83f5c1ab3c730c6e5
+README.zh.md: 889e46c24785c21cbb19e980291310ad096e761f
diff --git a/packages/session/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md
index 6d2cfa4d49..889e46c247 100644
--- a/packages/session/session-telemetry-otel/README.zh.md
+++ b/packages/session/session-telemetry-otel/README.zh.md
@@ -29,7 +29,7 @@
 
 上传授权采用显式许可，且为 fail-closed。通过直接构造传入未知模式时，会在读取传输配置前失败。只有 `FULL` 接受对 `ctx.telemetry.emit()` 的直接调用。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力，并且仅在 `feedback/record` 对象已经存储于 `session.events[event.seq]` 且对象身份完全相同时，才将其视为同意；独立发出的总线值会被忽略。即使存在导出器选项，`DISABLED` 也绝不会构造 SDK 流水线。
 
-`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。在上传模式中，`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。关闭期间，OTel 会先等待 `exporter.forceFlush()`，再进入受处理器 `exportTimeoutMillis` 限制的完成 promise；如果该传输 promise 始终不结算，本包会在 `shutdownTimeoutMillis` 到期时放弃等待，通过协调器记录已隔离的关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。
+`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。在上传模式中，`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。关闭期间，OTel 会先等待 `exporter.forceFlush()`，再等待受处理器 `exportTimeoutMillis` 限制的完成 promise；如果该传输 promise 始终不结算，本包会在 `shutdownTimeoutMillis` 到期时放弃等待，通过协调器记录已隔离的关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。
 
 ## 哪些数据会离开本机
 
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index ee9c7288b1..3d7e51ebe9 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/README.i18n.yaml
@@ -1,6 +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/telemetry/session-telemetry/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
 README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
-README.zh.md: 1ee0e0eb14bb06c8ac669cd417f2ee2ce46ca430
+README.zh.md: cb251587fc1ce651fe45e1961770a29508f6a1e6
diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
index 1ee0e0eb14..cb251587fc 100644
--- a/packages/session/session-telemetry/README.zh.md
+++ b/packages/session/session-telemetry/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
+遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
 ## 后端契约
 
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index b9aa148fd1..58ae7e6afd 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/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/skill/tool-skill/README.md
 README.md: b7309657d85a3d2a19de78a4ee6173d742519daa
-README.zh.md: f430f4027c917c5c9b97a56d1a7d7a617670b25c
+README.zh.md: 10834e13b4bfb745b4cd084ce41f616a8dd95807
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index f430f4027c..10834e13b4 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个分支——包括清空后的目录——都携带同一句话。
 
 ##### Skill 目录模板
 
@@ -149,11 +149,11 @@ Load referenced resources only as needed.
 
 #### 模型看到的内容
 
-已认领用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
+已认领的用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
 
 #### Token 影响
 
-每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——尺寸与同一 skill 的工具结果相同，按用户的请求确定性地支付，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
+每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——其大小与同一 skill 的工具结果相同；这项成本会在用户请求时确定产生，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
 
 #### KV Cache 影响
 
diff --git a/packages/storage/storage/README.i18n.yaml b/packages/storage/storage/README.i18n.yaml
index 4378ae55ad..09fa051bac 100644
--- a/packages/storage/storage/README.i18n.yaml
+++ b/packages/storage/storage/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/storage/storage/README.md
 README.md: bf827220afe0d8b1cbc53b3a12e6d0034004e1d2
-README.zh.md: 6c1a5b4c05f665cdedd16fa67b47c87a04737e7b
+README.zh.md: 86b6994d74a727275e0bcaea2a83bd51f93b6ca1
diff --git a/packages/storage/storage/README.zh.md b/packages/storage/storage/README.zh.md
index 6c1a5b4c05..86b6994d74 100644
--- a/packages/storage/storage/README.zh.md
+++ b/packages/storage/storage/README.zh.md
@@ -8,7 +8,7 @@
 
 - `ctx.storage.backend`：名称 → 后端表。多个后端并排保持挂载（`json`、`sqlite`）；为消费方提供服务的后端由该消费方自身的配置决定（领域层的路由表），绝非中心的全局选择。`register()` 返回资源释放函数；注册重复名称或查找未知名称时都会明确报错。
 - `ctx.storage.mount(form, facility)`／`ctx.storage.form(form)`：数据形式挂载。`StorageForms` 可通过合并扩展；领域层合并 `domain`，并通过 `ctx.storage.domain` 访问。
-- 后端拥有一种介质，并公开其支持的数据形状**分面**。当前分面为 `kv`；其确切契约由 `src/backend.ts` 负责。
+- 后端拥有一种介质，并公开其支持的数据形状**分面**。当前分面为 `kv`；`src/backend.ts` 负责定义其确切约定。
 
 ## 模型体验
 
diff --git a/packages/subagent/subagent-inprocess/README.i18n.yaml b/packages/subagent/subagent-inprocess/README.i18n.yaml
index d2e12854be..9bfe1023ee 100644
--- a/packages/subagent/subagent-inprocess/README.i18n.yaml
+++ b/packages/subagent/subagent-inprocess/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/subagent/subagent-inprocess/README.md
 README.md: 67f0cf5dd1ecb18542af56953a0eaa40988aca0d
-README.zh.md: 7536d265584f1f6c69027cda6bc4d81ad88b7c7c
+README.zh.md: 0cb9008e52088c2a3c554a4ab6a45e2345b34a08
diff --git a/packages/subagent/subagent-inprocess/README.zh.md b/packages/subagent/subagent-inprocess/README.zh.md
index 7536d26558..0cb9008e52 100644
--- a/packages/subagent/subagent-inprocess/README.zh.md
+++ b/packages/subagent/subagent-inprocess/README.zh.md
@@ -4,7 +4,7 @@
 
 本包是两个进程内提供方共用的运行驱动器。spawn 不传入会话初始内容；fork 传入父 agent（智能体）已完成轮次的前缀。其余机制，包括深度、子 agent 创建、可选的子 agent 定制、结果读取、取消和 dispose（资源释放），都在此共用同一套实现。
 
-## 启动契约
+## 启动约定
 
 `startInProcessRun(request, options): Promise<SubagentRun>` 只在子 agent 发布到 `ctx.agents` 后才兑现。启动被拒绝时，agent 工厂的未发布创建事务已经完全停稳，因此调用方绝不会收到创建到一半的句柄。
 
@@ -14,7 +14,7 @@
 2. 直接调用 `parent.ctx.agents.create`，把必需的请求信号传入工厂的创建事务。
 3. 在该事务未发布的设置窗口中，安装请求的 persona、工具限制和结构化输出运行时。
 4. 发布子 agent，保留返回的 `AgentHandle`，并通过先调用 `child.followup(prompt)`、再调用 `child.whenIdle()` 来驱动一项任务。
-5. 从完整的自有子运行中读取子 agent 自身最后一条 assistant 消息和最终持久轮次原因，并排除任何 fork 初始内容。
+5. 从完整的自有子运行中读取子 agent 自身最后一条 assistant 消息和最终持久化的轮次原因，并排除任何 fork 初始内容。
 
 子 agent 会获得父 agent 的工作目录／会话谱系；除非 `request.agentOptions` 覆盖，否则还会继承父 agent 的提供方、模型和输出 token 上限。它获得全新的扁平注册作用域：父级所有权不会导入父 agent 的工具限制，也不会建立权限子集。
 
@@ -26,7 +26,7 @@
 
 必需的请求信号同时覆盖启动阶段和实时运行。发布前，`AgentCreationTransaction` 会观察该信号、回滚并拒绝。工厂返回前会移除仅用于创建阶段的监听器；驱动器随即再次检查信号，然后安装最小化的实时运行监听器，从而消除交接竞态。发布后，中止会取消子 agent。
 
-兑现后，调用方拥有该运行。提供方插件卸载不会撤销它。`dispose()` 会移除实时中止监听器、记录取消，并委托给返回的 `AgentHandle.dispose()`；后者通过可复用的完全停稳事务停止循环、移除 agent 和会话，并展开有作用域的注册。取消决定所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。
+兑现后，调用方拥有该运行。提供方插件卸载不会撤销它。`dispose()` 会移除实时中止监听器、记录取消，并委托给返回的 `AgentHandle.dispose()`；后者通过经记忆化的完全停稳事务停止循环、移除 agent 和会话，并撤销作用域内的注册。取消流程会接管所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。
 
 ## spawn 与 fork 输入
 
diff --git a/packages/support/llm-replay/README.i18n.yaml b/packages/support/llm-replay/README.i18n.yaml
index e120b5007b..47650ae4de 100644
--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/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/support/llm-replay/README.md
 README.md: a6c087778b8e64124590fb6be7a652b58e1b6343
-README.zh.md: 241edb9c9b2400519155ccd7161eb7f34b9f5bbe
+README.zh.md: 05dcf994962ba37b58cfb18a68f0d3819d34db0a
diff --git a/packages/support/llm-replay/README.zh.md b/packages/support/llm-replay/README.zh.md
index 241edb9c9b..05dcf99496 100644
--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -8,7 +8,7 @@
 
 ## fixture 的工作方式
 
-fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent-loop `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带 `llmStreamCall: true` 和完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的 usage（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带该标记的 `rawOutput` 并不意味着发生了本地 LLM 调用，因为模板摘要器和远程摘要器即使未使用此上下文的适配器，也可能保留完整输出。
+fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent loop（智能体循环）的 `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带 `llmStreamCall: true` 和完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的用量（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带该标记的 `rawOutput` 并不意味着发生了本地 LLM 调用，因为模板摘要器和远程摘要器即使未使用此上下文的适配器，也可能保留完整输出。
 
 因此，录制就是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 和 `compact/summary` 事件以及第 0 行的会话 header。
 
@@ -20,7 +20,7 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 
 父 agent 委托给进程内 subagent 的场景会记录多个日志：父会话使用 `session.jsonl`，每个子会话各使用一个日志（`session.1.jsonl` 等）。每个 agent 都在同一上下文中作为独立的 `Session` 运行，因此回放必须为每个 agent 提供各自的脚本。
 
-回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop（智能体循环）写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
+回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
 
 ## 配置
 
diff --git a/packages/support/loader-smoke/README.i18n.yaml b/packages/support/loader-smoke/README.i18n.yaml
index 4e49d185bc..3860dd6af7 100644
--- a/packages/support/loader-smoke/README.i18n.yaml
+++ b/packages/support/loader-smoke/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/support/loader-smoke/README.md
 README.md: e5a33beb95f4e5940364cf309c8ea5fea60686f1
-README.zh.md: 1f3c6235175b3cfdcefec111eac39b2361b0e05b
+README.zh.md: 32c7af5bef050d6d46e91783468bdd0aa66e5ca0
diff --git a/packages/support/loader-smoke/README.zh.md b/packages/support/loader-smoke/README.zh.md
index 1f3c623517..32c7af5bef 100644
--- a/packages/support/loader-smoke/README.zh.md
+++ b/packages/support/loader-smoke/README.zh.md
@@ -12,7 +12,7 @@
 
 ## 模型体验
 
-无，因为测试 harness 仅提交调用方测试的普通用户任务，并将提示词和工具组装交由已加载的插件树负责。
+无，因为测试 harness 仅提交调用方测试的普通用户任务，并将提示词和工具组装交由已加载的树负责。
 
 #### KV Cache 影响
 
diff --git a/packages/tasks/tool-tasks/README.i18n.yaml b/packages/tasks/tool-tasks/README.i18n.yaml
index bdd840f0bd..65b1128efb 100644
--- a/packages/tasks/tool-tasks/README.i18n.yaml
+++ b/packages/tasks/tool-tasks/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/tasks/tool-tasks/README.md
 README.md: 6e8e889c2330d6991cb384674b011e4d2e988268
-README.zh.md: 9e54e2de69f36d5d5b70094cab12e5503eaeb5fd
+README.zh.md: 3b9dbd4f895eb38f0ffc7951169ff292da8603f1
diff --git a/packages/tasks/tool-tasks/README.zh.md b/packages/tasks/tool-tasks/README.zh.md
index 9e54e2de69..3b9dbd4f89 100644
--- a/packages/tasks/tool-tasks/README.zh.md
+++ b/packages/tasks/tool-tasks/README.zh.md
@@ -18,7 +18,7 @@
 
 ## 完成通知
 
-一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到精确 owner 的 next-step inbox。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
+一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step 收件箱。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
 
 ## 配置
 
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index cf44d9aace..3a061e43fd 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/typert/README.md
 README.md: ad9f843e48be0e3be85921ed8fd3ca4e2c327160
-README.zh.md: 0d4be016b766178b54f7e269583fa4200e3eb24b
+README.zh.md: aae74bf89f657f50f4519b2f8a0628fd391f8de3
diff --git a/packages/typert/README.zh.md b/packages/typert/README.zh.md
index 0d4be016b7..aae74bf89f 100644
--- a/packages/typert/README.zh.md
+++ b/packages/typert/README.zh.md
@@ -7,5 +7,5 @@ Typert 将源代码分析、运行时存储和 Loader 发现机制分离。
 | 包 | 职责 | Cordis 键 |
 |---|---|---|
 | [`registry/`](registry/README.md) | 存储运行时包反射和 schema | `ctx.typert` |
-| [`loader/`](loader/README.md) | 发现 Loader 条目并注册生成的宿主产物 | 消费 `ctx.loader` 和 `ctx.typert` |
+| [`loader/`](loader/README.md) | 发现 Loader 条目并注册生成的宿主产物 | 使用 `ctx.loader`、`ctx.typert` |
 | [`generator/`](generator/README.md) | 从源代码类型生成运行时产物 | 构建时库 |
diff --git a/packages/typert/generator/README.i18n.yaml b/packages/typert/generator/README.i18n.yaml
index 583835a63b..55fa47ebc9 100644
--- a/packages/typert/generator/README.i18n.yaml
+++ b/packages/typert/generator/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/typert/generator/README.md
 README.md: 38030c2b7e07c70ab79001086640b6581943dbd9
-README.zh.md: afa45820b7c7fba77704b86902c8752cd45777e6
+README.zh.md: 0cf0a365785775a9461e9744d29a0da482e54d14
diff --git a/packages/typert/generator/README.zh.md b/packages/typert/generator/README.zh.md
index afa45820b7..0cf0a36578 100644
--- a/packages/typert/generator/README.zh.md
+++ b/packages/typert/generator/README.zh.md
@@ -4,7 +4,7 @@
 
 TypeScript 项目分析器和模型驱动的 Typert 生成器。在生成任何产物之前，它会先将开发者编写的源类型树转换为独立于编译器的 `FaceModel` 和 `TypeGraph` 数据。静态分析无需 Cordis 即可消费该模型；各产物生成组件均不会接收 TypeScript 抽象语法树（AST）或类型检查器对象。
 
-分析器可以分别使用由 `tsconfig.host.json` 或 `tsconfig.client.json` 初始化的独立 `ts.Program`。直接 Project Reference 确定 compiler project 成员关系；带 `dshClient` 的普通单 project package 可按公开 subpath 同时贡献 Host 与 Client 运行时 face，显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 的拆分 project 则只贡献所选 face。`package.json#exports` 确定所有跨包公开边界，跨 face 的边只能来自源码导入或重新导出。NPM 依赖拥有的类型（包括 `@types` 包中的全局声明）继续以 `external` 引用表示，不会被展开。
+分析器可以分别使用由 `tsconfig.host.json` 或 `tsconfig.client.json` 初始化的独立 `ts.Program`。直接项目引用确定编译器 face 的成员归属，而包子路径确定 TypeRT 运行时 face 的贡献：带 `dshClient` 的普通单项目包可以同时贡献 Host 与 Client 运行时模型；只有通过 `tsconfig.host.json` 或 `tsconfig.client.json` 显式引用的拆分项目，才会被限制在相应 face。`package.json#exports` 确定所有跨包公开边界，跨 face 的边只能来自源码导入或重新导出。NPM 依赖拥有的类型（包括 `@types` 包中的全局声明）继续以 `external` 引用表示，不会被展开。
 
 ## 分析模型
 
@@ -18,7 +18,7 @@ TypeScript 项目分析器和模型驱动的 Typert 生成器。在生成任何
 
 `WorkspaceTypertGenerator` 会遍历从 Cordis `Context` 或 `Events` 扩充声明及显式 `@typert` 声明可达的包公开导出，以发现贡献方。发布产物时，它要求宿主侧产物位于 `lib/typert.host.{js,d.ts}` 并以 `package/typert` 暴露，客户端侧产物位于 `lib/typert.client.{js,d.ts}` 并以 `package/client/typert` 暴露。生成的声明将 `TYPERT` 暴露为 `unknown`，因此参与贡献的业务包无需依赖运行时注册表。
 
-各包可自行选择是否发布，未提供对应公开入口的业务包无需生成 Typert 产物。仓库的 Host tsdown 会以 `tsconfig.host.json` 为唯一 program 种子运行 workspace TypeRT 生成；它既生成 Host 反射产物，也把 Host Remote 契约投影为 Client 使用的 `typert.remote-client.*`。后续 Client tsdown 不启动 TypeRT，也不分析 `tsconfig.client.json`。静态消费方仍可直接调用 `WorkspaceAnalyzer`，显式选择 face 与包子集，并在不发布或加载运行时产物的情况下分批处理包。
+各包可自行选择是否发布，未提供对应公开入口的业务包无需生成 Typert 产物。仓库的 Host tsdown 会以 `tsconfig.host.json` 为唯一 program 种子运行 workspace TypeRT 生成；它既生成 Host 反射产物，也把 Host Remote 约定投影为 Client 使用的 `typert.remote-client.*`。后续 Client tsdown 不启动 TypeRT，也不分析 `tsconfig.client.json`。静态消费方仍可直接调用 `WorkspaceAnalyzer`，显式选择 face 与包子集，并在不发布或加载运行时产物的情况下分批处理包。
 
 ## 本仓库的 Cordis 投影
 
diff --git a/packages/typert/registry/README.i18n.yaml b/packages/typert/registry/README.i18n.yaml
index 011834c52d..f7193bdd9f 100644
--- a/packages/typert/registry/README.i18n.yaml
+++ b/packages/typert/registry/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/typert/registry/README.md
 README.md: fa227b1c8faf1abd5a6492d4b8fe7d0c51ceeef1
-README.zh.md: 343e43aaca6ddaa0bb5e8d3130c85f37e4b4cb93
+README.zh.md: b3dd820c9a4f23917e85631bedaf68e4fc5803c1
diff --git a/packages/typert/registry/README.zh.md b/packages/typert/registry/README.zh.md
index 343e43aaca..b3dd820c9a 100644
--- a/packages/typert/registry/README.zh.md
+++ b/packages/typert/registry/README.zh.md
@@ -9,8 +9,8 @@
 ## 公开 API
 
 - `TypertRegistry` 是默认插件，并提供 `ctx.typert`。
-- `ctx.typert.lookups.register()` 注册业务包拥有的 wire 声明和默认 resolver；`configure()` 注册 Host 组合拥有、可异步执行的 resolver。两者生命周期独立，配置可以先于 provider，卸载配置会恢复默认策略。
-- `ctx.typert.contexts.registerHost()` 和 `configureHost()` 将同一所有权拆分应用于 scoped Context 身份；`registerClient()` 提供对应的 Client Context binder。
+- `ctx.typert.lookups.register()` 注册由业务包拥有的协议声明和默认解析器；`configure()` 注册由宿主组合拥有且可异步执行的解析器。两者的生命周期相互独立：配置可以先于提供方注册，卸载配置会恢复默认策略。
+- `ctx.typert.contexts.registerHost()` 和 `configureHost()` 对具作用域的上下文身份采用同样的所有权划分；`registerClient()` 提供对应的客户端上下文绑定器。
 - `register(contribution)` 会在提交任何内容之前拒绝格式错误的标识，以及重复的包与 face 组合键或 schema 键，随后返回 Cordis effect 提供的同一资源释放函数。
 - `get(key)`、`resolve(key)` 和 `list(filter?)` 查询当前有效的 schema。`resolve()` 能区分格式错误的键、未注册的包，以及已注册但未以该名称提供 schema 的包。
 - `getPackage(packageName, face?)` 和 `listPackages(filter?)` 查询生成的服务、事件和对象反射信息；默认 face 为 `host`。
diff --git a/packages/util/README.i18n.yaml b/packages/util/README.i18n.yaml
index 82e5f323d8..69dbd9afbb 100644
--- a/packages/util/README.i18n.yaml
+++ b/packages/util/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/util/README.md
 README.md: b84f2cbb88981aa2edbde65d8a711b28cc5b48e9
-README.zh.md: 44834041aad8d891b5dcaf63e02be5641e878cdc
+README.zh.md: b1d7ccf14059892d57fb01502f177e0e618058b1
diff --git a/packages/util/README.zh.md b/packages/util/README.zh.md
index 44834041aa..b1d7ccf140 100644
--- a/packages/util/README.zh.md
+++ b/packages/util/README.zh.md
@@ -7,8 +7,8 @@
 | 包 | 职责 |
 |---|---|
 | [`brand/`](brand/README.md) | 提供带名义品牌的类型 |
-| [`paths/`](paths/README.md) | 解析 Harness 数据根目录和共享路径 |
+| [`paths/`](paths/README.md) | 解析 harness（智能体框架）数据根目录和共享路径 |
 | [`timeout/`](timeout/README.md) | 提供截止时间和超时分类原语 |
-| [`retention/`](retention/README.md) | 限制保留文本和项目集合的大小 |
+| [`retention/`](retention/README.md) | 限制保留文本和项集合的大小 |
 | [`atomic-write/`](atomic-write/README.md) | 以原子方式替换文件 |
 | [`native-command/`](native-command/README.md) | 不经 shell 运行宿主原生命令 |
diff --git a/packages/util/native-command/README.i18n.yaml b/packages/util/native-command/README.i18n.yaml
index 237ad82299..50116d2ef0 100644
--- a/packages/util/native-command/README.i18n.yaml
+++ b/packages/util/native-command/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/util/native-command/README.md
 README.md: dd9d1ddaf817b2ff77ec0cd01710053e918b4296
-README.zh.md: 3ff8a392f2c511295adb0bf5f62b6e0527cbaea6
+README.zh.md: 339db7f3adb402193ef14247413b02f80b6f728d
diff --git a/packages/util/native-command/README.zh.md b/packages/util/native-command/README.zh.md
index 3ff8a392f2..339db7f3ad 100644
--- a/packages/util/native-command/README.zh.md
+++ b/packages/util/native-command/README.zh.md
@@ -8,7 +8,7 @@
 
 它是**库，不是服务或插件**：没有 `ctx`、不注册任何东西、不持有状态、不发事件。
 
-## 接口面
+## Surface
 
 ```ts
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
diff --git a/packages/util/retention/README.i18n.yaml b/packages/util/retention/README.i18n.yaml
index b9ba96e765..62be2bd3ea 100644
--- a/packages/util/retention/README.i18n.yaml
+++ b/packages/util/retention/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/util/retention/README.md
 README.md: 45c88e9fc2d8df98f935fd1c3b43c4622802bd2a
-README.zh.md: 0fcb76a8ae381d3e3da54e90640a38cba9de12e8
+README.zh.md: 9419245908d7331c9db24019f1181fcaed848060
diff --git a/packages/util/retention/README.zh.md b/packages/util/retention/README.zh.md
index 0fcb76a8ae..9419245908 100644
--- a/packages/util/retention/README.zh.md
+++ b/packages/util/retention/README.zh.md
@@ -57,7 +57,7 @@ import type {
 | `web_fetch` | `TextRetainer`，`head` 或 `headTail` | 提供方/资源上限保留为提供方事实；retainer 只提供保留文本和省略元数据。 |
 | `web_search` | `ItemRetainer<WebSearchSource>`，`head` | 当提供方返回的来源超过面向模型的结果应包含的数量时，标准化「来源已达上限」通知。 |
 
-`read` 仍不属于这个通用库。其 `read-render` 辅助工具负责文件专用的分页契约：`offset`/`limit`、行号、`totalLines`、偏移越界错误、每行预览截断，以及所选窗口的字节上限。这是行窗口渲染器。单个 `Omitted` 数量无法表示该窗口两侧。
+`read` 仍不属于这个通用库。其 `read-render` 辅助工具负责文件专用的分页约定：`offset`/`limit`、行号、`totalLines`、偏移越界错误、每行预览截断，以及所选窗口的字节上限。这是行窗口渲染器。单个 `Omitted` 数量无法表示该窗口两侧。
 
 ## 使用形态
 
diff --git a/python/README.i18n.yaml b/python/README.i18n.yaml
index 8dadf07570..249bf6bb76 100644
--- a/python/README.i18n.yaml
+++ b/python/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 python/README.md
 README.md: 27637edb9d4d5e8714fe379a00b6aae3af1a541f
-README.zh.md: dd020aa507de965815fc05f8423b87e766a2fb42
+README.zh.md: 9eed37aa10cc1bc1265938968d8084ce1ef840ce
diff --git a/python/README.zh.md b/python/README.zh.md
index dd020aa507..9eed37aa10 100644
--- a/python/README.zh.md
+++ b/python/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 行为
 
-除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置契约分别见 [SDK 参考](sdk/README.md)和[运行时载体参考](sdk-runtime/README.md)。
+除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置约定分别由 [SDK 参考](sdk/README.md) 和 [运行时载体参考](sdk-runtime/README.md) 定义。
 
 ## 贡献者工作流
 
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 7b3bd7895f..081b8eb17e 100644
--- a/python/sdk/README.i18n.yaml
+++ b/python/sdk/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 python/sdk/README.md
 README.md: 2d545688c58a2f1b755e647d7cda9555249e41c4
-README.zh.md: 653256584f06c0e63b725953f7f27bc91fc198cc
+README.zh.md: 3f1e15bf8a148efd18fe66272bec2e0b28de8d21
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 653256584f..3f1e15bf8a 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -31,7 +31,7 @@ with DeepSeekHarness(
 
 `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
 
-`Session.run()` 拥有一个从提示词的持久 inbox 回执开始、到整个 agent 下一次进入 idle 为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。
+`Session.run()` 拥有一个从收件箱持久接收该提示词时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
 
 `HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
 

From ffb1f187ee4b49e3d7f190424ecc3ea0ff3f2552 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 06:21:41 +0800
Subject: [PATCH 170/262] ci: keep Wine required beside native Windows

---
 ...rial-cross-platform-ci-reference.i18n.yaml |   4 +-
 ...7-21-serial-cross-platform-ci-reference.md |   6 +-
 ...1-serial-cross-platform-ci-reference.zh.md |   6 +-
 ...ortable-required-pull-request-ci.i18n.yaml |   4 +-
 ...07-23-portable-required-pull-request-ci.md |   8 +-
 ...23-portable-required-pull-request-ci.zh.md |   8 +-
 ...n-setup-for-symmetric-ci-caching.i18n.yaml |   4 +-
 ...m-action-setup-for-symmetric-ci-caching.md |   4 +-
 ...ction-setup-for-symmetric-ci-caching.zh.md |   4 +-
 ...8-native-windows-pull-request-ci.i18n.yaml |   4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  28 +-
 ...08-08-native-windows-pull-request-ci.zh.md |  28 +-
 .github/AGENTS.md                             |   2 +-
 .github/workflows/ci.yml                      | 126 ++++++++-
 AGENTS.md                                     |   1 +
 package.json                                  |   1 +
 scripts/ci-workflow.spec.ts                   |  40 ++-
 scripts/wine-windows-gates.sh                 | 247 ++++++++++++++++++
 18 files changed, 451 insertions(+), 74 deletions(-)
 create mode 100755 scripts/wine-windows-gates.sh

diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index dcb6e18e88..67b965e4aa 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.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 .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
-2026-07-21-serial-cross-platform-ci-reference.md: dfd762ad4d4eec61bc3a17d96865ccc4ac936ab3
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 580340db2fbfc14458a4bbfbfa157db75e74e027
+2026-07-21-serial-cross-platform-ci-reference.md: dd41cdb51bd226b19bc6aca498c7713a3cc9a6b7
+2026-07-21-serial-cross-platform-ci-reference.zh.md: c72872d77f5d821b0fc203bda8bc1944e6929d73
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index dfd762ad4d..dd41cdb51b 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -16,7 +16,7 @@ Real-kernel sandbox proofs require specific hosted operating systems and archite
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity. A push to `master` skips those jobs and runs four explicit references: `serial / linux`, `serial / macos`, and `serial / windows` on standard hosted runners, plus `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
+[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Wine-hosted Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity; an independent native Windows job reports the complete Windows inventory without participating in the required aggregate. A push to `master` skips those jobs and runs four explicit references: `serial / linux`, `serial / macos`, and `serial / windows` on standard hosted runners, plus `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
 
 Each reference job runs `pnpm run check:ci` without any shard selector. `DSH_GATE_CONCURRENCY=1` makes the top-level aggregate execute one ready gate at a time; coverage, snapshot replay, built-bin smoke, and publication validation also receive worker counts of one. The reference jobs may run beside one another, but each host's repository gates are serial and complete. Linux installs bubblewrap before replaying snapshots, and Windows enables Developer Mode before installing the symlinked workspace.
 
@@ -28,13 +28,13 @@ The standalone [Sandbox](../../../../.github/workflows/sandbox.yml) workflow bel
 
 Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. The CI and Sandbox workflows keep their cross-platform references on master pushes. Performance is evaluated from completed hosted-job timestamps and reported as a measurement; it is not encoded as a `timeout-minutes` value.
 
-The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. The required pull-request Windows job also runs on standard `windows-2025` under the [native Windows decision](2026-08-08-native-windows-pull-request-ci.md); when enabled, `serial / windows` remains a second complete, unsharded native-kernel oracle. Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
+The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. The required pull-request Windows job runs under Wine on `ubuntu-latest`, while the independent pull-request native job uses standard `windows-2025` under the [dual Windows decision](2026-08-08-native-windows-pull-request-ci.md); when enabled, `serial / windows` remains a second complete, unsharded native-kernel oracle. Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
 
 ## Alternatives considered
 
 - **Set each timeout equal to its latency target** - rejected because scheduling variance would cancel correct work and suppress the evidence needed to diagnose a regression.
 - **Trust only the concurrent primary inventory** - rejected because scheduling and validation share implementation assumptions; a serial aggregate is an independent completeness check.
-- **Run the serial references on every pull request** - rejected because they duplicate complete cross-platform aggregates and add macOS work to every change; the required jobs already execute the blocking Linux and Windows contracts.
+- **Run the serial references on every pull request** - rejected because they duplicate complete cross-platform aggregates and add macOS work to every change; the required jobs already execute the blocking Linux and Wine-hosted Windows contracts, and the independent native job supplies the complete Windows result.
 - **Run the real-kernel Sandbox matrix on every pull request** - rejected because its four statuses do not participate in branch protection, while repeated installs, Landlock builds, and macOS unit parity consume runner capacity without changing the merge verdict. The master run retains the platform and installed-launcher signal.
 - **Use one operating-system matrix** - rejected because three named jobs make the reference surface visible without another selection mechanism.
 - **Run the serial reference on larger runners** - rejected because both required CI and its independent reference must remain runnable when organization-owned pools cannot allocate jobs.
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 580340db2f..c72872d77f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 契约。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和由 Wine 承载的 Windows 作业，以及 Node 兼容性与 Python 契约；一个独立的原生 Windows 作业会报告完整的 Windows 清单，但不参与必需聚合流程。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
@@ -28,13 +28,13 @@ macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上
 
 master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。CI 与 Sandbox 工作流把跨平台参考流程保留在 master 推送上。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。
 
-可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。依据[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)，拉取请求必需的 Windows 作业也在标准 `windows-2025` 上运行；`serial / windows` 启用时，仍作为第二个完整且未分片的原生内核标尺。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
+可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。拉取请求必需的 Windows 作业在 `ubuntu-latest` 上通过 Wine 运行，而独立的拉取请求原生作业依据[双 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)使用标准 `windows-2025`；`serial / windows` 启用时，仍作为第二个完整且未分片的原生内核标尺。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
 
 ## 曾考虑的替代方案
 
 - **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。
 - **仅信任并发执行的主门禁清单**：不予采纳，因为调度逻辑与校验逻辑共享实现假设；串行聚合流程是一项独立的完整性检查。
-- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 契约。
+- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和由 Wine 承载的 Windows 契约，而独立原生作业提供完整的 Windows 结果。
 - **在每个拉取请求上运行真实内核 Sandbox 矩阵**：不予采纳，因为它的四个状态不参与分支保护，而重复安装、Landlock 构建以及为保持平台一致而运行的 macOS 单元测试会消耗运行器容量，却不会改变合并裁决。master 上的运行保留平台与已安装 launcher 的信号。
 - **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。
 - **在大型运行器上运行串行参考流程**：不予采纳，因为当组织自有运行器池无法分配作业时，必需 CI 及其独立参考流程都必须仍可运行。
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
index 768e4298c7..d5368b8b45 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.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 .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
-2026-07-23-portable-required-pull-request-ci.md: 11de2b1dcbbdbdd7f9423131cd84c2940ac9218d
-2026-07-23-portable-required-pull-request-ci.zh.md: 02f5d758e1259d6a8e7cba70e439775bd1df2b28
+2026-07-23-portable-required-pull-request-ci.md: b7c637408afa32611c4e70073ddec9aaabfba7f5
+2026-07-23-portable-required-pull-request-ci.zh.md: 78cf1cce55920f7153f6a9ca6673dd172174d8dc
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
index 11de2b1dcb..b7c637408a 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
@@ -12,9 +12,9 @@ Billing health, a runner definition's `Ready` state, and a large autoscaling cei
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs on standard `windows-2025` under native Windows for the blocking surfaces and broader observational inventory ([native Windows decision](2026-08-08-native-windows-pull-request-ci.md)). Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and the serial references remain the complete unsharded cross-platform definitions. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
+[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs Windows Node under Wine on standard `ubuntu-latest` for the blocking surfaces; an independent native `windows-2025` job starts automatically but does not participate in the aggregate ([dual Windows decision](2026-08-08-native-windows-pull-request-ci.md)). Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and the serial references remain the complete unsharded cross-platform definitions. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
 
-The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / native complete` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
+The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / wine blocking` remain dependencies of `all checks passed`; `windows node 24 / native complete` is deliberately absent. Branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
 
 The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md) owns the current primary topology and its measurements. The [serial cross-platform reference](2026-07-21-serial-cross-platform-ci-reference.md) remains the independent standard-hosted completeness check, and the manual larger-runner suites retain size comparisons without expanding the ordinary required matrix.
 
@@ -30,6 +30,6 @@ The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md)
 
 ## Consequences
 
-Ordinary pull requests spend enterprise capacity on the Linux critical path while the native Windows job uses standard Windows allocation. A live exact-head run proves the same commands that branch protection consumes; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
+Ordinary pull requests spend enterprise capacity on the Linux critical path while the Wine job keeps the required Windows verdict on standard Linux allocation. The independent native job uses standard Windows allocation without delaying or changing the aggregate. A live exact-head run distinguishes the commands branch protection consumes from the separate diagnostic contract; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
 
-Standard compatibility and required Windows jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required Linux job or aggregate green. Recovering Linux availability may require restoring the complete standard-hosted topology; changing a pool definition's status alone is insufficient evidence that it can receive work.
+Standard compatibility, required Wine, and diagnostic native Windows jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required Linux job or aggregate green. Recovering Linux availability may require restoring the complete standard-hosted topology; changing a pool definition's status alone is insufficient evidence that it can receive work.
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
index 02f5d758e1..78cf1cce55 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `windows-2025` 上以原生 Windows 环境运行，覆盖阻断性检查范围和更广泛的观测性清单（[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)）。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，串行参考流程仍是完整且未分片的跨平台定义。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node，覆盖阻断性检查范围；一个独立的原生 `windows-2025` 作业会自动启动，但不参与聚合流程（[双 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)）。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，串行参考流程仍是完整且未分片的跨平台定义。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / native complete` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；`windows node 24 / native complete` 被刻意排除。分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
 
 当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而原生 Windows 作业使用标准 Windows 运行器容量。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
+普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而 Wine 作业让必需的 Windows 判定继续使用标准 Linux 运行器容量。独立原生作业使用标准 Windows 运行器容量，不会延迟或改变聚合流程。一次实际的分支头精确运行会区分分支保护采用的命令与单独的诊断契约；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
 
-企业级运行器分配能力下降时，标准兼容性作业和必需的 Windows 作业仍能提供有用证据，但无法让受阻的必需 Linux 作业或聚合流程变绿。恢复 Linux 可用性时，可能需要恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
+企业级运行器分配能力下降时，标准兼容性作业、必需的 Wine 作业与诊断性原生 Windows 作业仍能提供有用证据，但无法让受阻的必需 Linux 作业或聚合流程变绿。恢复 Linux 可用性时，可能需要恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
index 224544c058..86a1e15688 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.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 .agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 6fba2ce3b508d9d6fc879460a63c0e12673bd866
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: d9da8a4abe13772f3cc282392c03cdea54726c01
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 3d35d532216c1644f0d65039574453752e9be7ac
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 9e74a0149c9dcd17a88e9ff74a4b29fdc8916f32
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
index 6fba2ce3b5..3d35d53221 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
@@ -13,8 +13,8 @@ Outside `landlock-run.yml`, each workflow that installed pnpm hand-provisioned i
 `pnpm/action-setup@v4` is the only pnpm provisioning mechanism in CI: no workflow runs `corepack enable`. The root dev dependency on `@yarnpkg/cli-dist` separately supplies the modern Yarn CLI exercised by the generated-project e2e; package-manager coverage therefore does not inherit the runner image's Yarn Classic. Caching remains per-job policy on top of pnpm provisioning, in three deliberate shapes:
 
 - **Symmetric cache** (restore and save): `actions/setup-node` with `cache: pnpm` — `e2e.yml`, `docs-pages.yml`, `pi-ai-provider-e2e.yml`, `build-exe-for-python-sdk.yml`, and the node-compat and two benchmark jobs of `ci.yml`. The larger-runner benchmark keeps its store cache Linux-only through a conditional `cache:` input; the consolidated benchmark caches on both platforms.
-- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
-- **Cache-less or persistent** (no store-cache action): the required native Windows job, native serial-windows and serial-macos, plus `sandbox.yml` install from a cold or runner-local store. Extracting the many-file pnpm store costs more than a clean Windows install; the self-hosted standby and failover jobs instead reuse their VM's persistent pnpm store without transferring a hosted cache archive.
+- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs and the Wine-based required Windows job restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
+- **Cache-less or persistent** (no store-cache action): the independent native Windows job, native serial-windows and serial-macos, plus `sandbox.yml` install from a cold or runner-local store. Extracting the many-file pnpm store costs more than a clean Windows install; the self-hosted standby and failover jobs instead reuse their VM's persistent pnpm store without transferring a hosted cache archive.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
index d9da8a4abe..9e74a0149c 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
@@ -13,8 +13,8 @@ Status: implemented
 `pnpm/action-setup@v4` 是 CI 中提供 pnpm 的唯一机制：没有任何工作流运行 `corepack enable`。根目录的 `@yarnpkg/cli-dist` 开发依赖另行提供 generated-project e2e 所运行的现代 Yarn CLI（命令行界面）；因此，用于包管理器覆盖率的 Yarn 不会沿用 runner 镜像里的 Yarn Classic。缓存仍是叠加在 pnpm 提供机制上的按作业政策，保持三种刻意的形态：
 
 - **对称缓存**（既恢复也保存）：带 `cache: pnpm` 的 `actions/setup-node`——`e2e.yml`、`docs-pages.yml`、`pi-ai-provider-e2e.yml`、`build-exe-for-python-sdk.yml`，以及 `ci.yml` 的 node-compat 与两个 benchmark 作业。larger-runner benchmark 通过条件化的 `cache:` 输入让 store 缓存仅限 Linux；consolidated benchmark 在两个平台上都启用缓存。
-- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
-- **无缓存或持久化**（不使用 store 缓存 action）：必需的原生 Windows 作业、原生 serial-windows 和 serial-macos，以及 `sandbox.yml` 均从冷 store 或 runner 本地 store 安装。解压含有大量文件的 pnpm store，成本高于在 Windows 上进行一次全新安装；自托管热备与故障切换作业则复用其 VM 的持久 pnpm store，不传输托管缓存归档。
+- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业和基于 Wine 的必需 Windows 作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
+- **无缓存或持久化**（不使用 store 缓存 action）：独立的原生 Windows 作业、原生 serial-windows 和 serial-macos，以及 `sandbox.yml` 均从冷 store 或 runner 本地 store 安装。解压含有大量文件的 pnpm store，成本高于在 Windows 上进行一次全新安装；自托管热备与故障切换作业则复用其 VM 的持久 pnpm store，不传输托管缓存归档。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index b1b0079115..8cc2763444 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 80fccabdc9ddebba2204732677da31363b74a184
-2026-08-08-native-windows-pull-request-ci.zh.md: 9d00f4fad6eb817968609c3af1f278cc6794e7c7
+2026-08-08-native-windows-pull-request-ci.md: e98de723dfe118a297a2e9074d94d52dd6dddc47
+2026-08-08-native-windows-pull-request-ci.zh.md: 02ad94b095c8fd1361c4b113d486f8091bb9cf5a
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 80fccabdc9..e98de723df 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -1,4 +1,4 @@
-# Agent Note: Native Windows pull-request CI
+# Agent Note: Dual Wine and native Windows pull-request CI
 
 Status: implemented
 
@@ -6,34 +6,36 @@ English | [中文](2026-08-08-native-windows-pull-request-ci.zh.md)
 
 ## Problem
 
-The required pull-request Windows verdict must protect behavior that depends on the operating system, not only toolchain branches selected by `process.platform`. The Wine lane executed Windows Node and PE binaries over a Linux kernel and case-sensitive ext4, required a hoisted dependency layout and host-created symlinks, and omitted NTFS, DACL, ConPTY, crash-durability, and the broader observational Windows inventory. With the native serial references disabled, ordinary CI had no real Windows-kernel signal.
+The required pull-request Windows verdict needs a fast win32 toolchain signal without making the aggregate wait for scarce Windows capacity. The Wine lane provides that critical-path signal but executes over a Linux kernel and case-sensitive ext4, requires a hoisted dependency layout and host-created symlinks, and cannot prove NTFS, DACL, ConPTY, crash-durability, or native process behavior. With the native serial references disabled, ordinary CI also needs an automatic real Windows-kernel result on every pull-request head even when that result is not part of branch protection.
 
 ## Decision
 
-The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) runs on GitHub's standard `windows-2025` image under native PowerShell. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete`. The stable `windows` job id remains a dependency of `all checks passed`; its display name is `windows node 24 / native complete`.
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that run the workspace build and production site. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
 
-The aggregate keeps workspace build and production-site failures blocking while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
+Every pull request also starts an independent `windows-native` job named `windows node 24 / native complete` on GitHub's standard `windows-2025` image. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. The job is deliberately absent from `all-checks-passed.needs`: the aggregate neither waits for it nor changes conclusion because of it, while the native job retains its own unmasked success or failure result.
+
+The native gate keeps workspace build and production-site failures blocking inside its own job while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
 The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
 
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
-Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
-
 ## Alternatives considered
 
-**Keep Wine on the required path.** Its warm wall clock was close to Linux CI and it selected win32 toolchain branches, but the compatibility-specific layout and kernel gaps could report green while supported native behavior was broken. Latency no longer outweighs that missing signal.
+**Make native Windows a dependency of `all checks passed`.** This gives the aggregate the highest-fidelity Windows verdict, but makes every merge wait for the longest hosted job and for Windows capacity. The independent result keeps that signal automatic without changing the existing required path.
 
-**Restore the pre-Wine workflow verbatim.** The old definition captured the right runner boundary but also carried then-current provisioning and topology assumptions. Reconstructing the native job against the current actions, pnpm setup, gate graph, and aggregate dependency avoids reviving obsolete machinery.
+**Run only Wine on pull requests.** Wine reaches the blocking win32 toolchain branches quickly, but can report green while a real NT, NTFS, PowerShell, process, or addon contract is broken.
 
-**Run native Windows only after merge.** A post-merge reference diagnoses portability regressions after they enter `master`; it cannot protect a pull request while those references are disabled or delayed.
+**Mark the native job `continue-on-error`.** That would make its check appear successful after a gate failure. Keeping an ordinary independent job preserves the diagnostic conclusion; omission from aggregate `needs` is the only non-blocking mechanism.
 
-**Use an organization-owned larger Windows runner.** Larger images can reduce wall clock, but a required correctness path would then depend on repository-external labels and allocation. Standard `windows-2025` is the portable recovery boundary; larger runners remain benchmark targets.
+**Run native Windows only after merge.** A post-merge reference diagnoses portability regressions after they enter `master`; it does not give reviewers an exact-head native result.
+
+**Use an organization-owned larger Windows runner.** Larger images can reduce wall clock, but the diagnostic path would then depend on repository-external labels and allocation. Standard `windows-2025` is portable; larger runners remain benchmark targets.
 
 ## Consequences
 
-Pull requests receive a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal before the aggregate can pass. The job is slower than the Wine compatibility lane and can queue on Windows capacity, but its green result now describes the supported host rather than an approximation.
+Wine preserves the required aggregate's existing critical path and job identity. Native Windows can still be pending or red when `all checks passed` turns green, so branch protection consumes Wine while reviewers and follow-up automation consume the separate native result.
 
-The native lane is also a portability inventory: its exact-head acceptance requires every blocking gate to pass and the final summary to contain no non-blocking failure. That distinction caught path contracts which a successful wrapper conclusion alone would have concealed.
+Every pull request nevertheless receives a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal. The native job is slower than Wine and duplicates setup plus the two blocking builds, but it also executes the portability inventory that exposed path, watcher, and lifecycle defects hidden by the compatibility lane.
 
-Removing the Wine cache producer and local script deletes a separate install topology and its recurring compatibility failures. Native coverage and snapshots remain a named gap rather than being implied by the job name; they require their own tested contract before becoming part of this required lane.
+Maintainers must preserve two intentional execution topologies: the Wine snapshot uses Linux installation plus a hoisted layout to reach win32 binaries, while the native job uses the immutable workspace on Windows. A failure unique to either job must be classified against that boundary rather than weakened or silently skipped.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 9d00f4fad6..02ad94b095 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 原生 Windows 拉取请求 CI
+# Agent Note: Wine 与原生 Windows 双通道拉取请求 CI
 
 Status: implemented
 
@@ -6,34 +6,36 @@ Status: implemented
 
 ## 问题
 
-拉取请求必需的 Windows 判定必须为依赖操作系统的行为提供保障，而不能只覆盖由 `process.platform` 选择的工具链分支。Wine 通道在 Linux 内核与区分大小写的 ext4 之上执行 Windows Node 和 PE 二进制文件，要求采用 hoisted 依赖布局和由宿主侧创建的符号链接，也没有覆盖 NTFS、DACL、ConPTY、崩溃持久性与更广泛的观测性 Windows 清单。原生串行参考流程停用期间，常规 CI 没有任何真实的 Windows 内核信号。
+拉取请求必需的 Windows 判定既需要快速的 win32 工具链信号，也不能让聚合流程等待稀缺的 Windows 容量。Wine 通道提供这项关键路径信号，但它运行在 Linux 内核与区分大小写的 ext4 之上，要求采用 hoisted 依赖布局和由宿主侧创建的符号链接，且无法证明 NTFS、DACL、ConPTY、崩溃持久性或原生进程行为。原生串行参考流程停用期间，即使真实 Windows 内核结果不属于分支保护，常规 CI 也需要针对每个拉取请求分支头自动产出该结果。
 
 ## 决策
 
-[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业在 GitHub 标准 `windows-2025` 镜像上使用原生 PowerShell 运行。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并运行 `pnpm run check:ci:windows-complete`。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项；其显示名称为 `windows node 24 / native complete`。
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
 
-聚合作业继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
+每个拉取请求还会在 GitHub 标准 `windows-2025` 镜像上启动一个独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。该作业被刻意排除在 `all-checks-passed.needs` 之外：聚合流程既不等待它，也不会因它改变结论；原生作业则保留自身未被掩盖的成功或失败结果。
+
+原生门禁在其自身作业内继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
 首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
 
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
-受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
-
 ## 曾考虑的替代方案
 
-**在必需路径上保留 Wine。** 其热运行墙钟时间接近 Linux CI，也会选择 win32 工具链分支；但兼容性专属布局和内核缺口可能在受支持的原生行为已经损坏时仍报告绿灯。这项延迟收益不足以抵消该信号缺失的代价。
+**让原生 Windows 成为 `all checks passed` 的依赖项。** 这会为聚合流程提供保真度最高的 Windows 判定，但也会让每次合并等待最长的托管作业与 Windows 容量。独立结果能让该信号保持自动产生，而不改变现有必需路径。
 
-**逐字恢复 Wine 之前的工作流。** 旧定义确实捕获了正确的运行器边界，但也携带了当时的供应方式与拓扑假设。按照当前 action、pnpm 设置、门禁图和聚合依赖关系重新构建原生作业，可以避免重新引入过时机制。
+**只在拉取请求上运行 Wine。** Wine 能快速触达阻断性的 win32 工具链分支，但即使真实 NT、NTFS、PowerShell、进程或原生插件契约已经损坏，也可能报告绿灯。
 
-**只在合并后运行原生 Windows。** 合并后的参考流程只能在可移植性回归进入 `master` 后进行诊断；当这些参考流程被停用或延迟时，无法在拉取请求阶段提供保护。
+**将原生作业标记为 `continue-on-error`。** 门禁失败后，该设置会让其检查显示为成功。保留普通独立作业可维持诊断结论；仅从聚合流程的 `needs` 中省略它，才是不阻断的机制。
 
-**使用组织自有的大型 Windows 运行器。** 更大规格的运行器镜像可以缩短墙钟时间，但必需的正确性路径将因此依赖仓库外部的运行器标签与分配能力。标准 `windows-2025` 是可移植恢复边界；大型运行器仍作为基准测试目标。
+**只在合并后运行原生 Windows。** 合并后的参考流程只能在可移植性回归进入 `master` 后进行诊断；它无法向评审者提供分支头精确的原生结果。
+
+**使用组织自有的大型 Windows 运行器。** 更大规格的运行器镜像可以缩短墙钟时间，但诊断路径将因此依赖仓库外部的运行器标签与分配能力。标准 `windows-2025` 具备可移植性；大型运行器仍作为基准测试目标。
 
 ## 后果
 
-在聚合作业通过之前，拉取请求会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。该作业比 Wine 兼容性通道更慢，也可能因 Windows 容量而排队，但其绿灯结果描述的是受支持的宿主，而非近似环境。
+Wine 保留必需聚合流程现有的关键路径和作业身份。`all checks passed` 变绿时，原生 Windows 仍可能处于待处理或红灯状态，因此分支保护采用 Wine 结果，而评审者和后续自动化采用独立的原生结果。
 
-原生通道也是一份可移植性清单：其分支头精确验收要求每个阻断门禁都通过，且最终汇总中不包含任何非阻断失败。这一区分发现了路径契约问题；若只看包装层的成功结论，这些问题本会被掩盖。
+尽管如此，每个拉取请求都会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。原生作业比 Wine 更慢，并重复执行设置流程和两项阻断构建，但它也会运行那份可移植性清单；兼容性通道隐藏的路径、watcher 与生命周期缺陷正是由该清单暴露。
 
-移除 Wine 缓存生产者和本地脚本后，独立的安装拓扑及其反复出现的兼容性故障也随之消失。原生 Windows 覆盖率与快照仍是明确列出的缺口，不会仅由作业名称暗示已经纳入；二者都必须先建立各自经过测试的契约，才能成为该必需通道的一部分。
+维护者必须保留两种有意设计的执行拓扑：Wine 快照使用 Linux 安装加 hoisted 布局来触达 win32 二进制文件，而原生作业在 Windows 上使用不可变工作区。任一作业独有的失败都必须依据该边界分类，不得削弱或静默跳过。
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index c95b85e8e2..c18f5b5948 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — GitHub Actions
 
-Run jobs on Windows runners (`windows-*` labels) under native `pwsh`.
+Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. The pull-request `windows` job is the deliberate exception: it runs Windows Node under Wine on hosted Linux and blocks `all checks passed`; `windows-native` runs automatically on `windows-2025` but reports independently — see the [dual-lane Agent Note](../.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md).
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0e96d50e50..c6e015da60 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -300,12 +300,121 @@ jobs:
       - name: Run complete keyless Python suite
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
-  # One standard Windows box shares setup across the required build/site checks
-  # and the observational portability inventory. Serial worker bounds keep this
-  # recovery path portable; Linux owns duplicate lint, coverage, and snapshots.
-  # See the native-Windows pull-request CI decision:
+  # The required pull-request Windows signal: the two blocking win32 surfaces
+  # (workspace build, production site) execute with real, checksum-verified
+  # Windows Node under Wine on standard hosted Linux. The independent
+  # windows-native job below keeps the complete native-kernel inventory —
+  # including the observational portability gates this lane does not run —
+  # on real windows-2025. This job only provisions runner state (caches,
+  # apt); scripts/wine-windows-gates.sh owns the gate logic and is the same
+  # script the optional local gate `pnpm run check:windows-wine` runs.
+  # Current topology and fidelity limits live in
   # .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
   windows:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    name: windows node 24 / wine blocking
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Configure pnpm store path
+        id: pnpm-store
+        run: |
+          store_root="$HOME/.local/share/pnpm/store"
+          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
+          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
+          echo "path=$store_path" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache/restore@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+      # Master's wine-apt-cache job seeds the default-branch scope every pull
+      # request can read; a save from this job only reaches reruns of the
+      # same merge ref.
+      - name: Compose Wine apt cache key
+        id: wine-cache-key
+        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/wine-debs
+          key: ${{ steps.wine-cache-key.outputs.key }}
+
+      # Runner provisioning only — a developer machine installs Wine through
+      # its own package manager; the gate script assumes a wine binary and
+      # fails loud without one. Wine from the apt cache when present; else
+      # download the full dependency closure once and keep it for the next
+      # run. The `wine` dispatcher package (not bare `wine64`) is what puts a
+      # binary on PATH.
+      - name: Install Wine
+        run: |
+          if compgen -G "$HOME/wine-debs/*.deb" > /dev/null; then
+            sudo apt-get install -y --no-install-recommends "$HOME"/wine-debs/*.deb
+          else
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends --download-only wine
+            mkdir -p "$HOME/wine-debs"
+            cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" 2>/dev/null || true
+            sudo apt-get install -y --no-install-recommends wine
+          fi
+
+      - name: Run the Wine Windows gates
+        run: bash scripts/wine-windows-gates.sh
+
+      - name: Shut down wineserver
+        if: always()
+        run: wineserver -k 2>/dev/null || true
+
+  # Master seeds the Wine apt-archive cache in the default-branch scope,
+  # which every pull request's windows job can restore; saves from
+  # pull-request runs are scoped to their own merge ref and help nobody
+  # else. Runs in seconds when the image version already has a cache.
+  wine-apt-cache:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    name: wine apt cache
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Compose Wine apt cache key
+        id: wine-cache-key
+        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v4
+        id: wine-cache
+        with:
+          path: ~/wine-debs
+          key: ${{ steps.wine-cache-key.outputs.key }}
+
+      - name: Download the Wine dependency closure
+        if: steps.wine-cache.outputs.cache-hit != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends --download-only wine
+          mkdir -p "$HOME/wine-debs"
+          cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/"
+          du -sh "$HOME/wine-debs"
+
+  # Every pull request also gets a real Windows-kernel signal. This job keeps
+  # its own unmasked conclusion but is deliberately absent from
+  # all-checks-passed.needs, so it never delays or changes that required verdict.
+  # See the dual Wine/native pull-request CI decision:
+  # .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+  windows-native:
     if: github.event_name == 'pull_request'
     runs-on: windows-2025
     name: windows node 24 / native complete
@@ -337,7 +446,7 @@ jobs:
         shell: pwsh
         run: pnpm install --frozen-lockfile
 
-      - name: Run blocking and observational Windows gates concurrently
+      - name: Run complete native Windows gate inventory
         shell: pwsh
         run: pnpm run check:ci:windows-complete
 
@@ -742,9 +851,10 @@ jobs:
   # Single stable required check for branch protection: require "all checks
   # passed" instead of enumerating matrix legs whose names change as lanes and
   # node versions evolve. Every blocking job in THIS workflow must be listed in
-  # `needs`; observational Windows gates share the required Windows job but are
-  # marked non-blocking inside run-gates. (`needs` cannot reach across workflow
-  # files; e2e.yml stays its own check.)
+  # `needs`. The required Wine job is listed as `windows`; `windows-native` is
+  # deliberately absent so its independent result never delays or changes this
+  # verdict. (`needs` cannot reach across workflow files; e2e.yml stays its own
+  # check.)
   # `if: always()` is load-bearing: without it a failed dependency
   # would SKIP this job, and GitHub counts a skipped required check as passing
   # — so this job always runs and fails on any non-success result, including
diff --git a/AGENTS.md b/AGENTS.md
index ed9212b6d4..dcb001768e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -68,6 +68,7 @@ pnpm run typecheck
 pnpm run lint
 pnpm run duplication    # cross-file TypeScript clone detection
 pnpm run build          # tsc emits lib/types, tsdown bundles runtime
+pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
 pnpm run hygiene        # knip + publint + workspace constraints + NodeNext consumer check
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
diff --git a/package.json b/package.json
index ed6d915d6e..864814ffe6 100644
--- a/package.json
+++ b/package.json
@@ -57,6 +57,7 @@
     "check:ci:windows-blocking": "tsx scripts/run-gates.ts ci-windows-blocking",
     "check:ci:windows-complete": "tsx scripts/run-gates.ts ci-windows-complete",
     "check:ci:windows-observational": "tsx scripts/run-gates.ts ci-windows-observational",
+    "check:windows-wine": "bash scripts/wine-windows-gates.sh",
     "check:node-compat": "tsx scripts/run-gates.ts node-compat",
     "knip": "knip --treat-config-hints-as-errors",
     "publint": "tsx scripts/publint-all.ts",
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 558dc15548..05edaaef55 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -27,26 +27,40 @@ describe('CI workflow', () => {
     }
   })
 
-  it('runs the required Windows contract on a native hosted runner', () => {
+  it('keeps Wine blocking while native Windows reports independently', () => {
     const workflow = loadWorkflow('.github/workflows/ci.yml')
-    if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.windows)) {
-      throw new TypeError('CI workflow must define the windows job')
+    if (!isRecord(workflow.jobs)
+      || !isRecord(workflow.jobs.windows)
+      || !isRecord(workflow.jobs['windows-native'])
+      || !isRecord(workflow.jobs['all-checks-passed'])) {
+      throw new TypeError('CI workflow must define Wine, native Windows, and aggregate jobs')
     }
 
     const windows = workflow.jobs.windows
-    if (!Array.isArray(windows.steps)) throw new TypeError('windows job must define steps')
-    const steps: unknown[] = windows.steps
-    const commandSteps = steps.filter((step): step is Record<string, unknown> & { run: string } => (
+    const windowsNative = workflow.jobs['windows-native']
+    const aggregate = workflow.jobs['all-checks-passed']
+    if (!Array.isArray(windows.steps) || !Array.isArray(windowsNative.steps) || !Array.isArray(aggregate.needs)) {
+      throw new TypeError('Windows jobs must define steps and the aggregate must define needs')
+    }
+    const nativeCommandSteps = windowsNative.steps.filter((step): step is Record<string, unknown> & { run: string } => (
       isRecord(step) && typeof step.run === 'string'
     ))
 
-    expect(windows['runs-on']).toBe('windows-2025')
-    expect(windows.name).toBe('windows node 24 / native complete')
-    expect(commandSteps).toHaveLength(3)
-    expect(commandSteps.every(step => step.shell === 'pwsh')).toBe(true)
-    expect(commandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
-    expect(JSON.stringify(windows)).not.toMatch(/wine/i)
-    expect(workflow.jobs).not.toHaveProperty('wine-apt-cache')
+    expect(windows['runs-on']).toBe('ubuntu-latest')
+    expect(windows.name).toBe('windows node 24 / wine blocking')
+    expect(windows.if).toBe("github.event_name == 'pull_request'")
+    expect(JSON.stringify(windows)).toContain('bash scripts/wine-windows-gates.sh')
+    expect(workflow.jobs).toHaveProperty('wine-apt-cache')
+    expect(windowsNative['runs-on']).toBe('windows-2025')
+    expect(windowsNative.name).toBe('windows node 24 / native complete')
+    expect(windowsNative.if).toBe("github.event_name == 'pull_request'")
+    expect(windowsNative).not.toHaveProperty('continue-on-error')
+    expect(nativeCommandSteps).toHaveLength(3)
+    expect(nativeCommandSteps.every(step => step.shell === 'pwsh')).toBe(true)
+    expect(nativeCommandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
+    expect(JSON.stringify(windowsNative)).not.toMatch(/wine/i)
+    expect(aggregate.needs).toContain('windows')
+    expect(aggregate.needs).not.toContain('windows-native')
   })
 })
 
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
new file mode 100755
index 0000000000..9bf904a767
--- /dev/null
+++ b/scripts/wine-windows-gates.sh
@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Run the blocking Windows gates (workspace build, production site) with real
+# win-x64 Node.js under Wine — the same script the pull-request `windows` job
+# in ci.yml executes and the optional local gate `pnpm run check:windows-wine`
+# wraps. Owning rationale and fidelity limits:
+# .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+#
+# The working tree is never mutated: tracked plus untracked-unignored files
+# are snapshotted into a scratch directory, the Wine-specific pnpm overrides
+# (hoisted layout, win32-x64 platform packages) are appended to the SNAPSHOT's
+# pnpm-workspace.yaml, and the install and gates run there against the shared
+# pnpm store. The Wine prefix and the checksum-verified Windows Node zip
+# persist in .cache/wine-windows/ so reruns skip provisioning.
+#
+# Environment: DSH_WINE_NODE_MAJOR (default $PRIMARY_NODE_VERSION, then 24)
+# picks the Windows Node line; DSH_WINE_GATE_CACHE_DIR relocates the cache;
+# DSH_WINE_GATE_KEEP=1 preserves the scratch tree for inspection.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+node_major="${DSH_WINE_NODE_MAJOR:-${PRIMARY_NODE_VERSION:-24}}"
+cache_dir="${DSH_WINE_GATE_CACHE_DIR:-$repo_root/.cache/wine-windows}"
+
+export WINEDEBUG='-all'
+export WINEARCH=win64
+# Skip Wine Mono / Gecko installers: Node needs neither.
+export WINEDLLOVERRIDES='mscoree,mshtml='
+export WINEPREFIX="$cache_dir/prefix"
+
+# ---- preflight: fail loud before any expensive work --------------------
+wine_bin=''
+for candidate in "$(command -v wine || true)" "$(command -v wine64 || true)" /usr/lib/wine/wine64; do
+  if [ -n "$candidate" ] && [ -x "$candidate" ]; then wine_bin="$candidate"; break; fi
+done
+# GNU coreutils sha256sum on Linux; perl shasum ships with macOS. Both
+# accept the same "<hash>  <file>" --check input.
+checksum_tool=''
+if command -v sha256sum > /dev/null; then
+  checksum_tool='sha256sum'
+elif command -v shasum > /dev/null; then
+  checksum_tool='shasum'
+fi
+missing=()
+[ -n "$wine_bin" ] || missing+=('wine (apt: wine | brew: wine-stable)')
+command -v curl > /dev/null || missing+=('curl')
+command -v unzip > /dev/null || missing+=('unzip')
+[ -n "$checksum_tool" ] || missing+=('sha256sum or shasum (apt: coreutils | macOS ships shasum)')
+if ! command -v pnpm > /dev/null; then corepack enable > /dev/null 2>&1 || true; fi
+command -v pnpm > /dev/null || missing+=('pnpm (corepack enable)')
+if (( ${#missing[@]} > 0 )); then
+  printf 'wine-windows-gates: missing required tool: %s\n' "${missing[@]}" >&2
+  exit 1
+fi
+
+# Verify file $2 against SHA-256 hex $1 with whichever tool preflight found.
+verify_sha256() {
+  case "$checksum_tool" in
+    sha256sum) printf '%s  %s\n' "$1" "$2" | sha256sum --check - > /dev/null ;;
+    shasum) printf '%s  %s\n' "$1" "$2" | shasum -a 256 --check - > /dev/null ;;
+  esac
+}
+
+scratch="$(mktemp -d "${TMPDIR:-/tmp}/dsh-wine-gates.XXXXXX")"
+cleanup() {
+  wineserver -k > /dev/null 2>&1 || true
+  if [ "${DSH_WINE_GATE_KEEP:-0}" = '1' ]; then
+    echo "wine-windows-gates: scratch tree kept at $scratch"
+  else
+    rm -rf "$scratch"
+  fi
+}
+trap cleanup EXIT
+mkdir -p "$cache_dir" "$scratch/logs"
+
+# ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
+provision_node() {
+  # Latest release of the primary line, checksum-verified against the same
+  # dist directory. Offline runs fall back to the newest cached zip, loudly.
+  local version zip
+  version="$(curl -fsSL --max-time 30 https://nodejs.org/dist/index.json 2> /dev/null \
+    | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
+    || true)"
+  if [ -n "$version" ]; then
+    zip="$cache_dir/node-$version-win-x64.zip"
+    if [ ! -f "$zip" ]; then
+      curl -fsSL -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
+      local expected
+      expected="$(curl -fsSL "https://nodejs.org/dist/$version/SHASUMS256.txt" \
+        | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
+      [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
+      verify_sha256 "$expected" "$zip.tmp"
+      mv "$zip.tmp" "$zip"
+    fi
+  else
+    zip="$(ls -t "$cache_dir"/node-v"$node_major".*-win-x64.zip 2> /dev/null | head -1 || true)"
+    [ -n "$zip" ] || { echo "wine-windows-gates: nodejs.org unreachable and no cached Windows Node v$node_major zip in $cache_dir" >&2; exit 1; }
+    echo "wine-windows-gates: nodejs.org unreachable; using cached $(basename "$zip")" >&2
+  fi
+  unzip -q -o "$zip" -d "$scratch/node-win"
+  echo "$scratch/node-win/$(basename "$zip" .zip)/node.exe" > "$scratch/node-win-path"
+}
+
+boot_wine() {
+  "$wine_bin" wineboot --init > /dev/null 2>&1 || true
+  wineserver -w || true
+}
+
+snapshot_and_install() {
+  # Tracked + untracked-unignored files, minus agent-session litter; the
+  # existence filter drops paths staged as deleted. Then the Wine-specific
+  # install-time overrides go on the SNAPSHOT only: hoisted because Windows
+  # Node under Wine does not realpath pnpm's isolated-layout symlinks, and
+  # win32-x64 so the Windows esbuild/rolldown/rollup binaries materialize.
+  # Neither is recorded in the lockfile, so --frozen-lockfile stays valid;
+  # --ignore-scripts skips host lifecycle scripts no gate loads.
+  git -C "$repo_root" ls-files -z --cached --others --exclude-standard -- . ':!:.claude' ':!:.codex' \
+    | while IFS= read -r -d '' file; do [ -e "$repo_root/$file" ] && printf '%s\0' "$file"; done \
+    | tar -C "$repo_root" --null --files-from=- -cf - \
+    | tar -C "$scratch/tree" -xf -
+  cat >> "$scratch/tree/pnpm-workspace.yaml" << 'EOF'
+
+nodeLinker: hoisted
+supportedArchitectures:
+  os: [current, win32]
+  cpu: [current, x64]
+EOF
+  # The hoisted linker — used only by this lane — has an upstream rename
+  # race (pnpm/pnpm#12880): parallel linkers staging a nested package copy
+  # (observed on the tree's nested esbuild versions) rename their _tmp_*
+  # directory onto a path another racer already claimed, and the loser
+  # exits ERR_PNPM_ENOENT although an identical re-install succeeds.
+  # Exactly that signature earns up to two retries on a clean tree — the
+  # snapshot contains no node_modules, so wiping them restores the
+  # pre-install state; any other failure, or the race still standing after
+  # the final attempt, fails loud with the log tail.
+  local attempt
+  for attempt in 1 2 3; do
+    (cd "$scratch/tree" && pnpm install --frozen-lockfile --ignore-scripts > "$scratch/logs/install.log" 2>&1) \
+      && return 0
+    grep -q 'ERR_PNPM_ENOENT.*rename.*_tmp_' "$scratch/logs/install.log" || break
+    (( attempt < 3 )) || break
+    echo "wine-windows-gates: pnpm hoisted-linker rename race (pnpm/pnpm#12880) on install attempt $attempt; retrying on a clean tree" >&2
+    find "$scratch/tree" -name node_modules -type d -prune -exec rm -rf {} +
+  done
+  tail -40 "$scratch/logs/install.log" >&2
+  return 1
+}
+
+mkdir "$scratch/tree"
+start=$SECONDS
+provision_node & node_pid=$!
+boot_wine & wine_pid=$!
+snapshot_and_install & install_pid=$!
+# Wait for EVERY child before judging any: a bare `wait` under set -e would
+# exit on the first failure and let the EXIT trap delete $scratch while the
+# other children still run inside it. Named statuses also make the report
+# point at the root cause instead of a downstream symptom.
+node_status=0; wait "$node_pid" || node_status=$?
+wine_status=0; wait "$wine_pid" || wine_status=$?
+install_status=0; wait "$install_pid" || install_status=$?
+provision_failed=0
+report_provision() {
+  if (( $2 != 0 )); then
+    echo "wine-windows-gates: FAILED $1 (exit $2)" >&2
+    provision_failed=$2
+  fi
+}
+report_provision 'Windows Node provisioning' "$node_status"
+report_provision 'wineboot' "$wine_status"
+report_provision 'workspace snapshot + pnpm install' "$install_status"
+if (( provision_failed != 0 )); then exit "$provision_failed"; fi
+node_win="$(cat "$scratch/node-win-path")"
+echo "wine-windows-gates: provisioned in $((SECONDS - start))s (wine $("$wine_bin" --version 2> /dev/null), node $(basename "$(dirname "$node_win")"))"
+
+# ---- resolve entrypoints, lay the vue link, smoke ------------------------
+# Node under Wine cannot attach stdio to pipes the caller owns (Socket open
+# EBADF at bootstrap), so every invocation routes stdio through a file.
+wine_node() {
+  local log="$1"
+  shift
+  local status=0
+  "$wine_bin" "$node_win" "$@" < /dev/null > "$log" 2>&1 || status=$?
+  return "$status"
+}
+
+cd "$scratch/tree"
+tsc_js='node_modules/typescript/bin/tsc'
+tsdown_js='node_modules/tsdown/dist/run.mjs'
+vitepress_js='node_modules/vitepress/bin/vitepress.js'
+[ -f "$vitepress_js" ] || vitepress_js='website/node_modules/vitepress/bin/vitepress.js'
+for entry in "$tsc_js" "$tsdown_js" "$vitepress_js"; do
+  [ -f "$entry" ] || { echo "wine-windows-gates: expected entrypoint missing after hoisted install: $entry" >&2; exit 1; }
+done
+# VitePress links vue into the site's node_modules at build time; Wine cannot
+# CREATE Windows symlinks (ENOTSUP) but follows pre-existing Unix ones.
+if [ -d node_modules/vue ] && [ ! -e website/node_modules/vue ]; then
+  mkdir -p website/node_modules
+  ln -s ../../node_modules/vue website/node_modules/vue
+fi
+
+wine_node "$scratch/logs/smoke.log" -p "'smoke: ' + process.platform + ' ' + process.arch + ' ' + process.version"
+cat "$scratch/logs/smoke.log"
+grep -q '^smoke: win32 x64' "$scratch/logs/smoke.log" || { echo 'wine-windows-gates: Windows Node smoke did not report win32 x64' >&2; exit 1; }
+
+# ---- the two blocking surfaces, concurrently ------------------------------
+# The build preserves the face order from package.json: compile and bundle the
+# Host face before compiling and bundling the Client face.
+# Both statuses are captured so one failure cannot hide the other's result.
+build_gate() {
+  wine_node "$scratch/logs/host-tsc.log" "$tsc_js" -b tsconfig.host.json --pretty false || return $?
+  wine_node "$scratch/logs/host-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE host || return $?
+  wine_node "$scratch/logs/client-tsc.log" "$tsc_js" -b tsconfig.client.json --pretty false || return $?
+  wine_node "$scratch/logs/client-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE client
+}
+site_gate() {
+  cd website
+  wine_node "$scratch/logs/site.log" "../$vitepress_js" build .
+}
+
+start=$SECONDS
+build_gate & build_pid=$!
+site_gate & site_pid=$!
+build_status=0
+wait "$build_pid" || build_status=$?
+site_status=0
+wait "$site_pid" || site_status=$?
+elapsed=$((SECONDS - start))
+
+report() {
+  local label="$1" status="$2"
+  shift 2
+  if (( status == 0 )); then
+    echo "wine-windows-gates: PASS $label (${elapsed}s window)"
+  else
+    echo "== FAILED $label (exit $status) ==" >&2
+    for log in "$@"; do tail -n 200 "$log" >&2 || true; done
+  fi
+}
+report 'build (Host tsc/tsdown, Client tsc/tsdown)' "$build_status" \
+  "$scratch/logs/host-tsc.log" \
+  "$scratch/logs/host-tsdown.log" \
+  "$scratch/logs/client-tsc.log" \
+  "$scratch/logs/client-tsdown.log"
+report 'production site (vitepress build)' "$site_status" "$scratch/logs/site.log"
+if (( build_status != 0 )); then exit "$build_status"; fi
+exit "$site_status"

From 5d46c11784f3582ccde015d7c648bba8e653caf9 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 10:24:11 +0800
Subject: [PATCH 171/262] docs(i18n): reconcile source-drifted translations

---
 ...andatory-app-attribution-headers.i18n.yaml |  2 +-
 ...21-mandatory-app-attribution-headers.zh.md |  4 ++--
 ...cutable-sdk-runtime-distribution.i18n.yaml |  2 +-
 ...-executable-sdk-runtime-distribution.zh.md |  2 +-
 ...07-16-explicit-turn-cancellation.i18n.yaml |  2 +-
 ...026-07-16-explicit-turn-cancellation.zh.md |  4 ++--
 .../2026-06-30-interception-seams.i18n.yaml   |  2 +-
 .../2026-06-30-interception-seams.zh.md       |  6 ++---
 .../feature/2026-07-06-sandbox.i18n.yaml      |  2 +-
 .../feature/2026-07-06-sandbox.zh.md          |  4 ++--
 .../2026-07-16-harness-level-loop.i18n.yaml   |  2 +-
 .../2026-07-16-harness-level-loop.zh.md       |  8 +++----
 ...3-session-telemetry-otel-revival.i18n.yaml |  2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |  2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  2 +-
 ...6-06-20-core-data-structures-catalog.zh.md | 10 ++++----
 ...ssion-projection-and-command-log.i18n.yaml |  2 +-
 ...7-session-projection-and-command-log.zh.md |  2 +-
 examples/headless-agent/README.i18n.yaml      |  2 +-
 examples/headless-agent/README.zh.md          |  4 ++--
 packages/acp/README.i18n.yaml                 |  2 +-
 packages/acp/README.zh.md                     |  4 ++--
 packages/bash/README.i18n.yaml                |  2 +-
 packages/bash/README.zh.md                    |  8 +++----
 packages/bash/bash/README.i18n.yaml           |  2 +-
 packages/bash/bash/README.zh.md               |  2 +-
 .../client/ui-primitives/README.i18n.yaml     |  2 +-
 packages/client/ui-primitives/README.zh.md    | 12 +++++-----
 packages/compact/README.i18n.yaml             |  2 +-
 packages/compact/README.zh.md                 |  4 ++--
 packages/context/README.i18n.yaml             |  2 +-
 packages/context/README.zh.md                 |  2 +-
 packages/core/README.i18n.yaml                |  2 +-
 packages/core/README.zh.md                    |  2 +-
 packages/core/agent-loop/README.i18n.yaml     |  2 +-
 packages/core/agent-loop/README.zh.md         | 10 ++++----
 packages/core/agent/README.i18n.yaml          |  2 +-
 packages/core/agent/README.zh.md              |  2 +-
 packages/core/session/README.i18n.yaml        |  2 +-
 packages/core/session/README.zh.md            |  4 ++--
 packages/core/system-prompt/README.i18n.yaml  |  2 +-
 packages/core/system-prompt/README.zh.md      |  2 +-
 packages/core/tools/README.i18n.yaml          |  2 +-
 packages/core/tools/README.zh.md              |  4 ++--
 .../examples/jsonrpc-demo/README.i18n.yaml    |  2 +-
 packages/examples/jsonrpc-demo/README.zh.md   |  2 +-
 packages/fs/README.i18n.yaml                  |  2 +-
 packages/fs/README.zh.md                      | 12 +++++-----
 packages/fs/fs/README.i18n.yaml               |  2 +-
 packages/fs/fs/README.zh.md                   | 24 +++++++++----------
 packages/goal/README.i18n.yaml                |  2 +-
 packages/goal/README.zh.md                    |  2 +-
 packages/goal/command-goal/README.i18n.yaml   |  2 +-
 packages/goal/command-goal/README.zh.md       |  4 ++--
 packages/goal/goal/README.i18n.yaml           |  2 +-
 packages/goal/goal/README.zh.md               |  6 ++---
 packages/guard/README.i18n.yaml               |  2 +-
 packages/guard/README.zh.md                   |  4 ++--
 packages/host/README.i18n.yaml                |  2 +-
 packages/host/README.zh.md                    |  6 ++---
 packages/llm/README.i18n.yaml                 |  2 +-
 packages/llm/README.zh.md                     |  6 ++---
 packages/lsp/README.i18n.yaml                 |  2 +-
 packages/lsp/README.zh.md                     |  4 ++--
 packages/lsp/lsp-local/README.i18n.yaml       |  2 +-
 packages/lsp/lsp-local/README.zh.md           |  2 +-
 packages/plan/README.i18n.yaml                |  2 +-
 packages/plan/README.zh.md                    |  2 +-
 packages/plan/plan-mode/README.i18n.yaml      |  2 +-
 packages/plan/plan-mode/README.zh.md          |  2 +-
 packages/pty/README.i18n.yaml                 |  2 +-
 packages/pty/README.zh.md                     |  4 ++--
 packages/pty/pty-local/README.i18n.yaml       |  2 +-
 packages/pty/pty-local/README.zh.md           |  4 ++--
 packages/sandbox/sandbox/README.i18n.yaml     |  2 +-
 packages/sandbox/sandbox/README.zh.md         |  4 ++--
 packages/skill/README.i18n.yaml               |  2 +-
 packages/skill/README.zh.md                   |  2 +-
 packages/spill/README.i18n.yaml               |  2 +-
 packages/spill/README.zh.md                   |  2 +-
 packages/subagent/README.i18n.yaml            |  2 +-
 packages/subagent/README.zh.md                |  2 +-
 .../subagent-dsh-sdk/README.i18n.yaml         |  2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |  2 +-
 packages/subagent/subagent/README.i18n.yaml   |  2 +-
 packages/subagent/subagent/README.zh.md       |  8 +++----
 .../tool-subagent-control/README.i18n.yaml    |  2 +-
 .../tool-subagent-control/README.zh.md        |  2 +-
 packages/subprocess/README.i18n.yaml          |  2 +-
 packages/subprocess/README.zh.md              |  2 +-
 .../subprocess/subprocess/README.i18n.yaml    |  2 +-
 packages/subprocess/subprocess/README.zh.md   |  2 +-
 packages/tasks/README.i18n.yaml               |  2 +-
 packages/tasks/README.zh.md                   |  4 ++--
 packages/todo/README.i18n.yaml                |  2 +-
 packages/todo/README.zh.md                    |  2 +-
 packages/web/README.i18n.yaml                 |  2 +-
 packages/web/README.zh.md                     |  2 +-
 packages/workflow/README.i18n.yaml            |  2 +-
 packages/workflow/README.zh.md                |  6 ++---
 packages/workspace/README.i18n.yaml           |  2 +-
 packages/workspace/README.zh.md               |  2 +-
 102 files changed, 165 insertions(+), 165 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 3db3ea7fa4..b3db1ae497 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
 2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: cdada9cb235d57ad5cac98ebe0572013cac728ef
+2026-06-21-mandatory-app-attribution-headers.zh.md: a10abff8d6e2addf196bf48e2634110aa5e13b3b
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index cdada9cb23..a10abff8d6 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -49,9 +49,9 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 ## 验证
 
-已落地的契约：
+已落地的约定：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器契约（adapter contract）章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index 08d8319d33..aa1d2c9d6f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
 2026-07-10-single-file-executable-sdk-runtime-distribution.md: fe09e1b83f4f0a9f867f78351f643b1bd26d7c9d
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: ee49d7ea8fade9d3e323e8c6921479b8053809af
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 0279e0cf032928e96bad9da02340cae753a0927f
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index ee49d7ea8f..0279e0cf03 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -27,7 +27,7 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 确定性协议实现（`server.ts` / `transport.ts`）按 `acp/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件：
 
-- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
+- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并确保 `shutdown` 响应发送完毕后，对根运行时执行 dispose（资源释放），让待处理的持久化操作完成，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
 - [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
 
 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——「实际启动的插件由外部 `cordis.yml` 决定」是硬语义。
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index 2f7893a09f..d7f1670f34 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
 2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
-2026-07-16-explicit-turn-cancellation.zh.md: 68089e2c48d239afbff4c10cba5a202b4b6ff262
+2026-07-16-explicit-turn-cancellation.zh.md: 729997d48df79bad9fa52cd76ec7fa1fab281ae3
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index 68089e2c48..729997d48d 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -20,7 +20,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它
 
 对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
-显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
+显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。步骤前处理入口、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
 `ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
 
@@ -30,7 +30,7 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 ## 验证
 
-契约测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
+约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在步骤前处理、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
 
 发起方作用域测试断言所有钩子仍观察到同一个 Agent 且没有环境中的轮次 signal，并发 Agent 保持独立的身份与 signal，嵌套子驱动只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的完全停稳。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
index 8481cc20d5..3adc8a826f 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-seams.md
 2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
-2026-06-30-interception-seams.zh.md: 4e7b6a5ac9ca88919246508cf86c486b06888417
+2026-06-30-interception-seams.zh.md: 40989aa6bd6f2c103312c01fb4efbab21487adea
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
index 4e7b6a5ac9..40989aa6bd 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -16,7 +16,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 **Agent 事件**（`dsh-agent`）：
 - `agent/session-start({ agent, source })` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
-- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步会收到空批次。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持已删除。
+- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步中，`messages` 为空。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持移除状态。
 
 **`agent/turn-stopping`** 是自然停止边界上的一次 awaited 通知。需要再执行一步的监听器调用 `agent.steer()`，传入来源显式的 steering（中途引导）内容供模型使用；循环随后重新读取 outbox，继续执行或关闭轮次。
 
@@ -35,7 +35,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 三个承重的循环决策
 
-1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把带日志的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
+1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把会记录到日志中的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
 
 2. **工具执行后的 `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是一条独立的带来源 `user/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用／工具结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，在所有已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
 
@@ -56,4 +56,4 @@ seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；
 
 ## 后果
 
-规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的约定记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP（Agent Client Protocol）桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 00f475040c..755c076bca 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md
 2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
-2026-07-06-sandbox.zh.md: 8f575e3cd14973aaaaf9254337b985110bc99d6b
+2026-07-06-sandbox.zh.md: 9f55626a8fd12782249284c83f1e76e1d2f89724
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 8f575e3cd1..9f55626a8f 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -60,9 +60,9 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 #### 本地后端与随附 launcher
 
-`dsh-sandbox-local` 在提供方生命周期内选择一个平台 runner 并缓存结论。Linux 功能性探测 `bwrap` 然后 Landlock；macOS 使用 Seatbelt。不支持的平台和不可用的 runner 失败关闭。每次包装携带后端特定的拒绝签名和 runner 失败规则，以便 `dsh-bash-sandbox` 区分被拒绝的文件操作与损坏的沙箱。Landlock runner 失败需要退出码 125，加上一行不是通知的 `landlock-run:` 诊断；即使子进程以 1、2 或 125 退出，精确匹配的部分强制执行通知仍只是信息。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开契约均未保留 launcher 失败状态。`runnerCommand` 保留面向运维人员的 `runnerFailureSignatures` 配置，要求其中条目均为非空单行，并将它们映射为一条内部致命规则。消费方会直接 spawn 每个返回的 argv，因此缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本会通过可归因的 `ENOENT`／`EACCES` spawn 通道失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。运维人员配置的脚本必然要先启动解释器，再应用自身 profile。
+`dsh-sandbox-local` 在提供方生命周期内选择一个平台 runner 并缓存结论。Linux 功能性探测 `bwrap` 然后 Landlock；macOS 使用 Seatbelt。不支持的平台和不可用的 runner 失败关闭。每次包装携带后端特定的拒绝签名和 runner 失败规则，以便 `dsh-bash-sandbox` 区分被拒绝的文件操作与损坏的沙箱。Landlock runner 失败需要退出码 125，加上一行不是通知的 `landlock-run:` 诊断；即使子进程以 1、2 或 125 退出，精确匹配的部分强制执行通知仍只是信息。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开约定均未保留 launcher 失败状态。`runnerCommand` 保留面向运维人员的 `runnerFailureSignatures` 配置，要求其中条目均为非空单行，并将它们映射为一条内部致命规则。消费方会直接 spawn 每个返回的 argv，因此缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本会通过可归因的 `ENOENT`／`EACCES` spawn 通道失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。运维人员配置的脚本必然要先启动解释器，再应用自身 profile。
 
-launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 契约）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它为自身安装规则集并执行 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；所有 launcher 失败都会以 125 退出且不运行子进程，并打印一行致命的 `landlock-run:` 诊断。成功完成 exec 的子进程也可能返回 125，因此仅凭退出状态不能作为 launcher 失败的证据。较旧的 ABI 会在执行子进程之前打印精确的 `landlock-run: partial enforcement (older Landlock ABI)` 通知，因此该行不是致命证据。
+launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 约定）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它为自身安装规则集并执行 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；所有 launcher 失败都会以 125 退出且不运行子进程，并打印一行致命的 `landlock-run:` 诊断。成功完成 exec 的子进程也可能返回 125，因此仅凭退出状态不能作为 launcher 失败的证据。较旧的 ABI 会在执行子进程之前打印精确的 `landlock-run: partial enforcement (older Landlock ABI)` 通知，因此该行不是致命证据。
 
 Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 消费方同仓，并属于根 pnpm workspace。[仓库内 Landlock 发布决策](../process/2026-08-06-in-repository-landlock-release.md)负责共享锁文件、原生构建、打包演练和 npm 发布边界。平台二进制由 npm 选择，入口包拥有路径解析、探测、CLI 参数、致命前缀和部分强制执行通知，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index a54f2e9496..15d82777e1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
 2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
-2026-07-16-harness-level-loop.zh.md: 0ec2dc2294c1adf8b7f6f810bfaffa7e08c19ed2
+2026-07-16-harness-level-loop.zh.md: 10f4cd2ac4991361261dd652d5d99dcb15d459be
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 0ec2dc2294..10f4cd2ac4 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -42,11 +42,11 @@ Status: implemented
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`，人类命令生产方 | 为 TUI 注册构建在目标领域之上的 `/goal` 状态、创建、编辑、暂停、恢复与清除。 |
 | `@deepseek-ai/dsh-tool-ralph` | `packages/workflow/tool-ralph/`，固定工作流消费方 | 注册 `ralph({ objective, maxRounds? })`，验证全新结构化 provider 与有界 `RalphRoundReport`，并返回 `complete`、`blocked` 或 `budget-limited`。 |
 
-详细契约分别由[目标领域](2026-07-19-persisted-same-session-goal-domain.md)、[Goal 自有事件](../architecture/2026-07-31-goal-owned-durable-events.md)、[模型目标工具](2026-07-19-model-facing-goal-tools.md)、[目标回合驱动器](2026-07-19-same-session-goal-round-driver.md)、[命令注册表](2026-07-19-plugin-command-registration.md)、[人类目标命令](2026-07-19-human-goal-command.md)与 [Ralph 工作流工具](2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note 拥有。
+详细约定分别由[目标领域](2026-07-19-persisted-same-session-goal-domain.md)、[目标自有事件](../architecture/2026-07-31-goal-owned-durable-events.md)、[模型目标工具](2026-07-19-model-facing-goal-tools.md)、[目标回合驱动器](2026-07-19-same-session-goal-round-driver.md)、[命令注册表](2026-07-19-plugin-command-registration.md)、[人类目标命令](2026-07-19-human-goal-command.md)与 [Ralph 工作流工具](2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note 拥有。
 
 ### 持久目标状态与实时权限
 
-一个会话至多有一个当前 goal。每次变更都通过持久 `goal/change` 事件提交，并携带带版本的完整快照或带修订号的 clear 墓碑；inbox 状态不参与其中。会话日志是唯一持久真源，因此普通持久化、恢复与 `SessionStore.fork()` 会携带 goal，无需第二个数据库或人为取消记录。
+一个会话至多有一个当前目标。每次变更都通过持久的 `goal/change` 事件提交；该事件携带带版本的完整快照或带修订号的清除墓碑，收件箱状态不参与其中。会话日志是唯一持久真源，因此普通持久化、恢复与 `SessionStore.fork()` 会携带目标，无需第二个数据库或人为取消记录。
 
 持久阶段只有 `active`、`paused`、`blocked` 与 `complete`。阻塞目标必须携带 `GoalBlockReason`，其中包含稳定的小写 kebab-case `code` 与非空的人类可读 `message`；用量限制、Round 耗尽、模型失败与策略拒绝都是原因代码，而不是额外生命周期阶段。独立激活态是 `armed` 或 `disarmed`，且永不持久化。创建与显式恢复会激活目标；停止转换、会话启动、fork 回放、驱动器替换和驱动器拆卸都会让目标保持未激活。
 
@@ -58,9 +58,9 @@ fork 会话会继承持久目标前缀，因为这是自然的重放结果。for
 
 ### 同会话续行
 
-Goal Round 驱动器为每个准确实时 agent 至多拥有一个待定预留。只有 goal 处于活跃且已激活状态、agent 空闲、不存在竞争性人类工作、最新变更已经通过持久性检查点、准确 goal id／revision／Round 仍匹配，并且下游 pre-step 策略接受时，它才会接纳预留。其 `agent/pre-step` 围栏会在下游监听器前后检查这些事实，防止编辑、暂停、人类消息或卸载竞争接纳陈旧工作。
+Goal Round 驱动器为每个特定的实时 agent 至多拥有一个待定预留。只有目标处于活跃且已激活状态、agent 空闲、不存在竞争性人类工作、最新变更已经通过持久性检查点、确切的目标 id／修订号／Round 仍匹配，并且下游 pre-step 策略接受时，它才会接纳预留。其 `agent/pre-step` 围栏会在下游监听器前后检查这些事实，防止编辑、暂停、人类消息或卸载竞争接纳过时工作。
 
-只有已准入、Round 为正数且来源为 goal 的 `user/message` 会计入一个 Round。陈旧预留会关闭一个 blocked 的无步骤轮次，不会消耗上限。并发 goal revision 会胜过旧 Round 的结算。
+只有已接纳、Round 为正数且带目标来源的 `user/message` 会计入一个 Round。陈旧预留会结束一个阻塞的零步骤轮次，不会消耗上限。并发目标修订会胜过旧 Round 的结算。
 
 普通 Turn 完成后，只有目标仍活跃、已激活且低于上限时才会安排另一个 Round。取消会暂停。速率限制或配额耗尽以代码 `usage-limited` 阻塞；上限耗尽使用 `round-limit`；队列失败使用 `queue-failed`；Turn 错误、max-token 停止、策略拒绝与未知终止结果使用各自对应的阻塞代码。独立组合的请求恢复插件可以在同一个 Turn 内重试暂时性 provider 失败；目标驱动器绝不会在异常终止结果后凭空发起另一个 Round。人类随后可以通过普通语言或 `/goal resume` 授权恢复。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index 58b5371ba2..be9c014650 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
 2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
-2026-07-23-session-telemetry-otel-revival.zh.md: 4e834f8b129e2062064cf3497370fecf6f88db29
+2026-07-23-session-telemetry-otel-revival.zh.md: 1d607ce9a3b77ae96664af72599beacb34fd9b47
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index 4e834f8b12..1d607ce9a3 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `packages/session/`（原 `telemetry/`）以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
 
-- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时收养与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
+- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时纳管与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
 - **`telemetry/record` waterfall（瀑布式事件）** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何后端前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
 - **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考后端：OTel JS SDK 日志流水线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。其默认 `FULL` 模式要求 `exporter.url`；后续的[反馈门控遥测决策](2026-08-05-feedback-gated-session-telemetry.md)增加了 `FEEDBACK_ONLY` 与 `DISABLED` 投递模式，但未移动脱敏或后端边界，而[无缓冲反馈回放](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)避免在内存中创建会话前缀的第二份副本。
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index def34cdfbd..6f51f73b00 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
 2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
-2026-06-20-core-data-structures-catalog.zh.md: 96c606a3d65a67e757960c5cbc997e717f11e8d5
+2026-06-20-core-data-structures-catalog.zh.md: 895f639446bc6c4e0fecbf1085197ba8b1810282
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 96c606a3d6..895f639446 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 核心数据结构目录与 `ts type-equiv` 漂移门禁
+# Agent Note: 子系统目录与 `ts type-equiv` 漂移门禁
 
 Status: implemented
 
@@ -18,14 +18,14 @@ Status: implemented
 
 > **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
 
-范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入子页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入自己的 seam 页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
-确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子页面细节。*** 逐一验证如下：
+确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是 seam 页面细节。*** 逐一验证如下：
 
 - 一个数据结构是**核心**的，如果它流经 agent loop 主干——无论加载了哪些插件，循环在每个轮次都会持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄）——**或者**它是插件作者面对某条流水线时编写的唯一标志性类型（`ToolDefinition`）。
-- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是子页面细节。这就是主干与 seam 分界线的精确表述。
+- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是 seam 页面细节。这就是主干与 seam 分界线的精确表述。
 - `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
-- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇是子页面。
+- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇属于 seam 页面。
 
 `core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级 seam 页面获取各 seam 的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的 seam 页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index 0fe388a3dc..d4aa713b5c 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
 2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
-2026-07-27-session-projection-and-command-log.zh.md: 89877d3aabcd074863f912b334c927268014e4d8
+2026-07-27-session-projection-and-command-log.zh.md: 0cc82d1aa65dc2b99882875d655ddbe17073354a
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index 89877d3aab..0cc82d1aa6 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -58,7 +58,7 @@ declare module 'cordis' {
 
 ### 已交付的消费方：subagent 身份单元
 
-注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久化 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位缓存，零日志读），对 cold child 则用一次持久化整读的结果调用 `restore({}, events, 0)` 读取。注册表契约不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
+注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久的 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位线缓存，零日志读），对 cold child 则对一次持久化读取所得的事件调用 `restore({}, events, 0)` 读取。注册表约定不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
 
 ### 协议层：历史尾页上的 projections 块
 
diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index 4a71194e5f..07a1dc582a 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/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 examples/headless-agent/README.md
 README.md: 6e80e56dec70c2be341ae5dfbad70e13a5109715
-README.zh.md: ea8c41b9ae75f0cee3edd78e59408f37c19182d3
+README.zh.md: 9e409735f03afc62cd788fa2a5d1afdef0fa6c2a
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index ea8c41b9ae..9e409735f0 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -19,13 +19,13 @@ pnpm run dsh run "fix the failing test in this workspace"
 
 ## E2B POC overlay
 
-[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行凭据门控的实机组合测试；它在同一个沙箱中驱动 FS、Bash、PTY 和 LSP，并证明沙箱最终被删除：
+[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与子进程提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行凭据门控的实机组合测试；它在同一个沙箱中驱动 FS、Bash、PTY 和 LSP，并证明沙箱最终被删除：
 
 ```sh
 pnpm exec vitest run --config vitest.e2e.config.ts packages/e2b/e2b/tests/composition.e2e.ts
 ```
 
-该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。该组合会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
+该 overlay 会在沙箱中创建相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。该组合会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
 
 ## 高级配置
 
diff --git a/packages/acp/README.i18n.yaml b/packages/acp/README.i18n.yaml
index cd4555752b..08fe41b6ab 100644
--- a/packages/acp/README.i18n.yaml
+++ b/packages/acp/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/acp/README.md
 README.md: 97af6d164b265bf0e98e3c9f5a444cffad4face5
-README.zh.md: 266b108c108b9f543d93cbb727ddbc01ab4bef36
+README.zh.md: fb9f419e23aef5b3bdf0bdd486b331eb2f3f236a
diff --git a/packages/acp/README.zh.md b/packages/acp/README.zh.md
index 266b108c10..fb9f419e23 100644
--- a/packages/acp/README.zh.md
+++ b/packages/acp/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-ACP 组通过 Agent Client Protocol 把 harness agent 暴露给编程客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
+ACP（Agent Client Protocol）组通过该协议将 harness 中的 agent（智能体）公开给程序化客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
 
 | 包 | 职责 |
 |---|---|
 | [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器。 |
 
-服务器契约见 [`acp/README.md`](acp/README.md)。
+服务器约定见 [`acp/README.md`](acp/README.md)。
diff --git a/packages/bash/README.i18n.yaml b/packages/bash/README.i18n.yaml
index 00321c8ab0..a55672b9e1 100644
--- a/packages/bash/README.i18n.yaml
+++ b/packages/bash/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/README.md
 README.md: 7395a051742af24b96842966b71297dc01853dca
-README.zh.md: 1d5825e077c46284dbd4895e285cda8f39c252a3
+README.zh.md: 043394f429d406a6d14f00b6d8a0384bd022abe0
diff --git a/packages/bash/README.zh.md b/packages/bash/README.zh.md
index 1d5825e077..043394f429 100644
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-该能力家族涵盖规范执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
+该能力家族涵盖规范的执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`bash/`](bash/README.md) | 定义实现与消费方共享的执行器契约。 | `ctx.bash` |
+| [`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` |
+| [`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`） |
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index eee269c121..169a45d5cd 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/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/README.md
 README.md: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee
-README.zh.md: c343e17bfd97eaf17316c034c263b0c71bb8327a
+README.zh.md: f8bcfce06a406eb94a2486e9825f2beb11b8fd5e
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index c343e17bfd..f8bcfce06a 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -35,7 +35,7 @@
 
 `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 契约上漂移。
+导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的一部分：它对 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]`／`[killed by signal: X]` marker 进行逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与退出状态 pill；它位于 seam 上，因此两个工具的 marker 约定不会发生偏离。
 
 ## 模型体验
 
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 42211f6d7a..5c8e7eaab6 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
 README.md: 098a202a4ac9ee263ce1beaaee7a8624ebf26b80
-README.zh.md: 2b33af3316dede35cb5a226e41365f692a8b25d3
+README.zh.md: def1907f81d06b5afdf19af5f19ba17a269ed3c1
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 2b33af3316..def1907f81 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。约定：api-contracts v3 §8。
 
 ## 悬浮卡片
 
-`HoverCard` 通过指针离开宽限期，让采用 portal 渲染的预览在跨越与锚点之间的间隙时仍可抵达。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。历史依据见[已归档的悬浮卡片复制 Agent Note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md)。
+`HoverCard` 通过指针离开宽限期，使采用 portal 渲染的预览在跨过与锚点之间的间隙时仍可触及。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。历史依据见[已归档的悬浮卡片复制 Agent Note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md)。
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有视图把命名真实文件的行内代码变成链接：token 保留代码样式并获得接到所解析 opener 的按钮，带解析器给出的无障碍标签与完整路径 `title`。渲染器绝不猜测什么长得像路径——未解析的 token 保持原样，提及只作用于已定稿的渲染（流式缓存不能烘进可能过期的 handler），锚点内部的 token 也保持原样，因为按钮不能嵌套在链接里。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
@@ -22,7 +22,7 @@
 
 ## Diff 渲染
 
-`DiffBlock` 将一次文件改动渲染为内联 diff 表层：每个文件一个粗体路径头、删除行（`- `，error token）在新增行（`+ `，success token）之上、同文件第二个 hunk 前一个 `⋯` gap，以及暗色 `└ +A -R · N file(s)` 页脚。各行使用 `white-space: pre` 并横向滚动，因此源码行保留其缩进而不软换行；超过 `maxLines`（默认 16，与 `TerminalBlock` 相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。新建（`oldText: null`）没有删除侧。复制控件写入带前缀的 diff 文本（路径头、`- `/`+ ` 行、gap），使多文件复制保持可归属，并浮在右上角而非占据自己的 banner 行。几何镜像 `CodeBlock`/`TerminalBlock`。原理：[Web diff 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)。
+`DiffBlock` 将一次文件改动渲染为内联 diff 表层：每个文件一个粗体路径头、删除行（`- `，error token）在新增行（`+ `，success token）之上、同文件第二个 hunk 前一个 `⋯` gap，以及暗色 `└ +A -R · N file(s)` 页脚。各行使用 `white-space: pre` 并横向滚动，因此源码行保留其缩进而不软换行；超过 `maxLines`（默认 16，与 `TerminalBlock` 相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。新建（`oldText: null`）没有删除侧。复制控件写入带前缀的 diff 文本（路径头、`- `/`+ ` 行、gap），使多文件复制保持可归属，并浮在右上角而非占据自己的 banner 行。几何结构与 `CodeBlock`/`TerminalBlock` 一致。原理：[Web diff 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)。
 
 ## 搜索结果
 
@@ -30,7 +30,7 @@
 
 ## Web 检索
 
-`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的 provider answer（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。整份列表渲染在一个定高滚动容器里（`max-height: 320px`、`overflow-y: auto`），因此超出该高度的列表在原地纵向滚动，而不是把卡片撑高；`<li value>` 固定每个 source 的引用编号，从 1 起连续，而不依赖 `<ol>` 的隐式计数。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 `<ol>`（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)与[来源滚动笔记](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)。
+`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的提供方回答（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。整份列表渲染在一个定高滚动容器里（`max-height: 320px`、`overflow-y: auto`），因此超出该高度的列表在原地纵向滚动，而不是把卡片撑高；`<li value>` 固定每个 source 的引用编号，从 1 起连续，而不依赖 `<ol>` 的隐式计数。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 `<ol>`（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)与[来源滚动笔记](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)。
 
 ## 模型体验
 
@@ -46,5 +46,5 @@
 - **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
 - **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
 - **StateDot 没有 `Active` 变体**：支持的状态为 done、warning、ongoing 和 error。
-- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
+- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表截断提示与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
 - **`TerminalBlock` 不是终端模拟器**：它渲染已结束或仍在运行的命令输出，而不是交互式会话：SGR 颜色与属性会被遵循，进度行所用的行内光标移动同样被遵循——回车、退格、行内擦除、制表位与字符宽度。绝对光标定位、清屏与备用屏幕序列会被剥离。基础 16 色中的洋红与青色没有对应 token，保持字面 rgb。
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index bb5922ee75..bdbb81127c 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/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/compact/README.md
 README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
-README.zh.md: cba53ee7bb917a981a0fd4b77d833b8fb7dd2c3f
+README.zh.md: 431e84ec645ae08da203e2d68e1f6813dd7ded2d
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index cba53ee7bb..431e84ec64 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -11,6 +11,6 @@
 | [`compact-tool-result-prune/`](compact-tool-result-prune/README.md) | 可选的无模型工具结果修剪 | `ctx.toolResultPrune` |
 | [`command-compact/`](command-compact/README.md) | 用户压缩命令 | 注册到 `ctx.commands` |
 
-后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)负责依赖关系的设计原理。
+后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 负责说明依赖关系的设计依据。
 
-子系统参考——`compact/*` 事件、`CompactionResult`、服务、剪除结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
+子系统参考——`compact/*` 事件、`CompactionResult`、服务、修剪结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在 [压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
diff --git a/packages/context/README.i18n.yaml b/packages/context/README.i18n.yaml
index efb18426a4..b8025ef2bd 100644
--- a/packages/context/README.i18n.yaml
+++ b/packages/context/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/context/README.md
 README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
-README.zh.md: 7c55dd91dbf7e3fca222e4b6f6bed2769f5c253c
+README.zh.md: 653fd971a884e1b356e5a366d91f81caefd681c5
diff --git a/packages/context/README.zh.md b/packages/context/README.zh.md
index 7c55dd91db..653fd971a8 100644
--- a/packages/context/README.zh.md
+++ b/packages/context/README.zh.md
@@ -9,7 +9,7 @@
 | [`session-reference/`](session-reference/README.md) | 其他会话的有界快照 | `ctx.sessionReferences` |
 | [`time-context/`](time-context/README.md) | 当前时间与耗时上下文 | — |
 | [`tmux-context/`](tmux-context/README.md) | tmux 位置上下文 | — |
-| [`workspace-context/`](workspace-context/README.md) | workspace 指令上下文 | — |
+| [`workspace-context/`](workspace-context/README.md) | 工作区指令上下文 | — |
 
 [`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
 
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index aa542fe885..ff41da1511 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
 README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
-README.zh.md: 496d547a173a63ac9d8d2ce0f005877dab92d358
+README.zh.md: c0a24d78cb8ff2a2b2ccc2d2a2f4294424be55b0
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index 496d547a17..c0a24d78cb 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -17,4 +17,4 @@
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
 
-子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截契约——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。
+子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截约定——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index fb18353290..f80bc0cc79 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
 README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
-README.zh.md: c190171513e17777ebaadda0d279487876a412b4
+README.zh.md: f14810ecf56f80c1f2a768aaf315415159e2c021
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index c190171513..f14810ecf5 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -10,7 +10,7 @@
 
 ### 公开 API
 
-创建与恢复属于同一个受回滚保护的事务：构造私有会话、实体 agent 和带作用域的上下文；等待可选 setup；进入两个注册表；依次宣告 `session/created` 和 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 接收完整的带作用域 `Context`，作为受信任的同进程组合代码，并且不得驱动尚未发布的 agent。普通的类型化身份与选项输入遵循只读契约以借用方式传入；seed 事件与会话元数据会跨越持久会话边界，因此系统会验证并快照它们。可选的 `AbortSignal` 只取消加载／setup／发布，并在返回的 handle 可见前分离。
+创建与恢复属于同一个受回滚保护的事务：构造私有会话、具体 agent 和带作用域的上下文；等待可选 setup；进入两个注册表；依次宣告 `session/created` 和 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 接收完整的带作用域 `Context`，作为受信任的同进程组合代码，并且不得驱动尚未发布的 agent。普通的类型化身份与选项输入遵循只读约定以借用方式传入；seed 事件与会话元数据会跨越持久会话边界，因此系统会验证并快照它们。可选的 `AbortSignal` 只取消加载／setup／发布，并在返回的 handle 可见前分离。
 
 调用方 fiber 与 AgentLoop 提供方共同拥有 agent。`AgentFactory.createAgent(ownerCtx, options)` 与 `resume(ownerCtx, options)` 显式接收调用方所有权，而工厂为 `sessions`/`llm`/`tools`/`systemPrompt` 保留自身的依赖上下文；这样，调用方可以只注入 `agents`，而不会缩减新 agent 的服务接口。调用方卸载、handle dispose（资源释放）或提供方卸载都会汇合到同一个记忆化的完全停稳边界。提供方关闭会同时等待资源 teardown，以及已经观测到停用的公开 create/resume 包装层，因此依赖消失后，任何 continuation 都无法继续发布。
 
@@ -53,11 +53,11 @@ interface Config {
 
 ### 包内部具体驱动器
 
-实体 `ReactLoopAgent`、其 inbox 与运行控制均为包内部实现。包根只导出插件／服务／配置契约，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个实体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。
+具体 `ReactLoopAgent`、其 inbox 与运行控制均为包内部实现。包根只导出插件／服务／配置约定，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个具体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。
 
-统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`followup()` 追加到 `next-turn` FIFO 并唤醒驱动器，`steer()` 追加到 `next-step` inbox 并唤醒驱动器，`inject()` 则追加到同一个 `next-step` inbox，但不唤醒驱动器。在轮次边界，驱动器会先打开持久轮次，再原子领取待处理的 next-step 输入和一条排队提示词；在步骤之间则只领取 next-step 输入。领取通过纯删除 splice 移除批次，并针对每条消息发出 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 返回 reject，或返回拟进入步骤的完整消息。reject 后已领取批次保持已删除，并关闭不含步骤的轮次；领取后插入的输入仍等待后续处理，而空闲注入会一直等待，直到 follow-up 或 steering 唤醒驱动器。
+统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`followup()` 追加到 `next-turn` FIFO 并唤醒驱动器，`steer()` 追加到 `next-step` inbox 并唤醒驱动器，`inject()` 则追加到同一个 `next-step` inbox，但不唤醒驱动器。在轮次边界，驱动器会先打开持久轮次，再原子领取待处理的 next-step 输入和一条排队提示词；在步骤之间则只领取 next-step 输入。领取通过纯删除 splice 移除批次，并针对每条消息发出 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 返回拒绝结果，或返回将进入拟议步骤的完整消息。拒绝后，已领取批次保持已删除，并关闭不含步骤的轮次；领取后插入的输入仍等待后续处理，而空闲注入会一直等待，直到 follow-up 或 steering 唤醒驱动器。
 
-每次 inbox 变更都会先发布一条规范化的 `agent/inbox/spliced` 事件，再修改实时投影。因此，插入、编辑、移除、领取与取消都通过同一组标准 splice 坐标回放。普通删除携带 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`；领取使用不带 outcome 的纯删除，随后由循环发出 `agent/inbox/claimed`。每次插入都会发出 `agent/inbox/inserted { message }`。`MessageId` 在两个待处理列表之间保持唯一，同步持久事件观察方可以从 splice 前投影重建被移除的值。
+每次 inbox 变更都会先发布一条规范化的 `agent/inbox/spliced` 事件，再修改实时投影。因此，插入、编辑、移除、领取与取消都通过同一组标准 splice 坐标回放。普通删除携带 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`；领取使用不带 outcome 的纯删除，随后由循环发出 `agent/inbox/claimed`。每次插入都会发出 `agent/inbox/inserted { message }`。`MessageId` 在两个待处理列表之间保持唯一，持久事件的同步观察方可以从 splice 前投影重建被移除的值。
 
 ### 循环生命周期（`agent.ts`）
 
@@ -67,7 +67,7 @@ interface Config {
 
 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。
 
-插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态契约。
+插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会以终止错误或中止结束的形式由 `ctx.llm` 传来，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose 则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态约定。
 
 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。内部调度器故障会停止新的分发，等待已启动的分发，然后在不虚构工具结果的情况下到达轮次错误边界。
 
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 4c6009d3b0..b2d54ebc66 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
 README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
-README.zh.md: 8164829e18ddd89fd84c0c2b5e033fd69241b9aa
+README.zh.md: 4295c15923f6a5c6132369bfe2137e3d34dec6b1
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 8164829e18..4295c15923 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
 
-大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
+大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
 `PreStepDecision` 要么是 `{ kind: 'reject' }`，要么是 `{ kind: 'enter', messages }`。enter 分支是拟进入步骤的完整、带标识且冻结的批次。包装下游 enter 的监听器会保留该批次，除非有意替换它；新增消息遵循 waterfall 的自然返回顺序。领取操作已经把候选消息从 inbox 删除，因此 reject 不会保留它们；领取后插入的消息仍等待后续边界。
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 8b1e462166..abb9bfc6f2 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
 README.md: 00e007ee6064f485bf80dfda0227ab6e834f6414
-README.zh.md: 5f06fee5d50bc2c9dc333874a8354fbf19d5248b
+README.zh.md: e9d074f52db46cb42e497ad1ef49c2b37a6ec7d8
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index 5f06fee5d5..e9d074f52d 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -62,7 +62,7 @@
 
 `request/header` 记录非历史请求封装的完整规范快照，其原因为 `initial`、`resume` 或 `change`。其可选 `adapterDefaults` 映射会标记由精确模型解析填入的生效 `reasoningEffort` 或 `maxTokens` 值，使下一次请求提议能够将它们与显式对话设置区分开。`foldRequestHeader()` 选择最新快照；旧版增量事件和已移除的 `fallback` 原因会被拒绝。详见[可重建请求 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
 
-`user/message` 会直接存储完整的 `UserMessage`，其中包括路由或 pre-step 领取前创建的标识。无论它是直接人类提示词、合成注入，还是进入步骤的 Goal Round，都会原样呈现其 `content`；带类型的 `source` 是区分三者的唯一通道，并携带各领域专有的持久事实。`assistant/message` 和 `tool/result` 也会存储完整的消息值。轮次执行仍由 `turn/start` 与 `turn/end` 包围；`agent.inject()` 会把输入排队，直到某次 pre-step 返回 enter 并在轮次内记录它。
+`user/message` 会直接存储完整的 `UserMessage`，其中包括收件箱路由或进入步骤前创建的标识。无论它是直接人类提示词、合成注入，还是已进入的 Goal Round，都会原样呈现其 `content`；带类型的 `source` 是区分三者的唯一通道，并携带各领域专有的持久事实。`assistant/message` 和 `tool/result` 也会存储完整的消息值。轮次执行仍由 `turn/start` 与 `turn/end` 包围；`agent.inject()` 会把输入排队，直到后续某次 pre-step 领取它，并在 enter 决策中返回它。
 
 `tool/result` 持久保存一条带标识、user-role 的工具结果消息，以及可选内部失败标识和可选呈现元数据。工具成功时的规范 `value` 和便于人类阅读的规范失败消息只存在于执行本地；渲染后的错误内容是回放权威消息。
 
@@ -72,7 +72,7 @@
 
 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。
 
-此包还定义 `TurnEndReasonMap`，即用于轮次结束、可合并扩展且以 `kind` 为标签的和类型。`turn/start` 只携带轮次编号；之后进入步骤的 `user/message` 批次记录其输入，`llm/retry` 则记录请求恢复。
+此包还定义 `TurnEndReasonMap`，即用于轮次结束、可合并扩展且以 `kind` 为标签的和类型。`turn/start` 只携带轮次编号；随后已进入的 `user/message` 批次记录其输入，`llm/retry` 则记录请求恢复。
 
 被中断的实时轮次以 `{ kind: 'aborted', reason: AgentCancelCause }` 结束，在持久 transcript（文本记录）中保留类型化取消原因。持久化会将受支持旧格式中的粗粒度中止结果导入为 `{ kind: 'aborted', reason: { kind: 'legacy' } }`，因为该记录没有保留调用方。轮次失败携带 `{ kind: 'error', error }`；只有崩溃恢复会合成 `{ kind: 'interrupted' }`。
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index c94d1722dc..e4caa9b815 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
 README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5b9e2feaf82866a52cd8197ff5e800decdf3ee7e
+README.zh.md: 5a838f4ed3cb1f57ecd9f41325e1612afaf5103a
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5b9e2feaf8..5a838f4ed3 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -36,7 +36,7 @@
 
 ### 扩展点
 
-- 段提供方：工具包（package）拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
+- 段提供方：工具包拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
 - 变量提供方：agent loop（智能体循环）注册 `model` 与 `cwd`；任何插件都可以注册自己拥有的事实（未来的 `date`、git 状态等）。
 - 工具 schema 提供方：`ToolRegistry` 自动将自身注册为工具提供方。
 - [`system-prompt/assemble` waterfall](#live-events)：按调用方协作式修改或替换组装结果。
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index b19e86ce84..b257ecbfa6 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
 README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
-README.zh.md: 796ee8e1aa8de88f979d825df5e0b4f39ab7bcf1
+README.zh.md: 675d9299037bc5225fcd117148c574eb646cf680
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 796ee8e1aa..675d929903 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -13,7 +13,7 @@ tools:
   mode: native   # native (default) | code | both
 ```
 
-`native` 以函数定义的形式贡献可见工具。`code` 贡献保留的 `run_code` 传输和生成的 `tools:sdk` 段；`both` 同时贡献两种形式。不能注册、遮蔽、限制或移除该保留传输。非原生模式要求所加载 `ctx.codeRuntime` 的 `language` 有已注册的 SDK 渲染器——TypeScript 经 [`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md) 交付；Python 渲染器内置，驱动任何报告 `language: 'python'` 的运行时（第一方 `dsh-code-runtime-python` 后端另行交付）。没有渲染器的运行时语言会让提示词组装响亮失败；如果 `systemPrompt.toolOrder` 条目指向当前模式未贡献的工具，系统会拒绝组装提示词。`system-prompt/assemble` 监听器可以替换注册表贡献；它返回的组装结果具有权威性，因此该监听器负责保留可用的 Code Mode 协议。
+`native` 以函数定义的形式贡献可见工具。`code` 贡献保留的 `run_code` 传输和生成的 `tools:sdk` 段；`both` 同时贡献两种形式。不能注册、遮蔽、限制或移除该保留传输。非原生模式要求所加载 `ctx.codeRuntime` 的 `language` 有已注册的 SDK 渲染器——TypeScript 经 [`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md) 交付；Python 渲染器内置，驱动任何报告 `language: 'python'` 的运行时（第一方 `dsh-code-runtime-python` 后端另行交付）。没有渲染器的运行时语言会导致提示词组装明确失败；如果 `systemPrompt.toolOrder` 条目指向当前模式未贡献的工具，系统会拒绝组装提示词。`system-prompt/assemble` 监听器可以替换注册表贡献；它返回的组装结果具有权威性，因此该监听器负责保留可用的 Code Mode 协议。
 
 ### 公开 API
 
@@ -114,7 +114,7 @@ ctx.tools.register(defineTool({
 
 ### Code Mode
 
-在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度契约下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 契约之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回契约](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
+在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度约定下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 约定之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回契约](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
 
 - **SDK 段**（`tools:sdk`，顺序 150）：一个惰性提示词段，每次组装时都会重新生成与所加载运行时语言相符的 SDK 文本。TypeScript 形态发出 `JsonValue`、精确的 `ToolArgsMap` / `ToolOutputMap`、`ToolName`、`ToolCallError` 声明、面向调用作用域可见最终能力的映射 `tools` 命名空间（特殊名称使用带引号的键），以及固定用法说明；Python 形态（`ctx.codeRuntime.language === 'python'`）发出等价的具名 `TypedDict` 与一个带相同用法说明的 `tools` 对象。其输出具有确定性：工具按字典序排列；工具集合不变时，文本逐字节相同（有利于前缀 cache）。两个代码生成器都已导出，且绝不会在提示词组装期间抛出：`jsonSchemaToTs` 处理统一 schema 的每种构造并将不受支持的原始构造降级为 `unknown`；`jsonSchemaToPy` 同理，降级为 `Any`（当某字段名不是合法的 `TypedDict` 属性时，或在 SDK 渲染之外被调用时——`TypedDict` 声明所需的命名上下文由该渲染提供——整个对象降级为 `dict[str, Any]`）。
 - **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发契约的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联让以提交为语义的观察器能够把内部成功延迟到最终 `run_code` 结果，而无需公开实时外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系，并且即使程序后来失败，也会保留各自的来源／元数据。
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index c47938ce3b..5660d73494 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/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/examples/jsonrpc-demo/README.md
 README.md: fff8e78698cd3d6320606084ef5c533be7c52633
-README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
+README.zh.md: 207717c27ac7a0f91eaf888d7aed4ded1adef67c
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 75382b97ea..207717c27a 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 交付。
 
 ## 配置发现
 
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index b1e493f3c8..aa010c33f2 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
 README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
-README.zh.md: b2929b17be6ce90051f0808c2cdf4bbf643f8f13
+README.zh.md: 196a2aad89203905148581d6364be7f02e2f4e35
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index b2929b17be..196a2aad89 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -2,22 +2,22 @@
 
 [English](README.md) | 中文
 
-文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
+文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、策略门禁插件（已观察状态、编辑前读取、版本防护的写入／编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品**包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
-| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
+| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 策略事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
 | [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
-| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
-| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `fs-sandbox/` | 强制实施沙箱约束的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根策略约束写入／编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 策略门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、策略门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。策略（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去策略，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
 `read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
 
-子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
+子系统参考——目标、结果、守卫、策略事件、错误分类体系，以及文件 I/O 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index d9b0010670..8141819240 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
 README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
-README.zh.md: 97d7104f3c4c0beca408397f9cb1cead39b0a76e
+README.zh.md: 32faf67d6ed97914704ea5683f1fd987e2e64a93
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 97d7104f3c..32faf67d6e 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,18 +2,18 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
 
 本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
 | 层 | 包 | 角色 |
 |---|---|---|
 | 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
-| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 策略 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
 | 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
 
-未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
+未来的沙箱化、虚拟或远程后端只需实现该接口，策略层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
@@ -26,7 +26,7 @@
 | `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
 | `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
@@ -35,15 +35,15 @@
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 政策事件
+## `fs/*` 策略事件
 
-本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是政策层
+## 提供方 seam，不是策略层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
@@ -55,11 +55,11 @@
 
 #### KV Cache 影响
 
-不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
+不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
-- **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
+- **约定只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
 - **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
 - **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/goal/README.i18n.yaml b/packages/goal/README.i18n.yaml
index d2a6bf0248..db694ef162 100644
--- a/packages/goal/README.i18n.yaml
+++ b/packages/goal/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/goal/README.md
 README.md: 9d307278b39ecee61df9feace9fec4235b45d794
-README.zh.md: 7217c174ba5382c53204ae3678be42375fc63db5
+README.zh.md: fec870751b1f331bf4d09dcbee04d977183064ad
diff --git a/packages/goal/README.zh.md b/packages/goal/README.zh.md
index 7217c174ba..fec870751b 100644
--- a/packages/goal/README.zh.md
+++ b/packages/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-agent 会话的持久目标状态，独立于消费它的模型工具与续跑策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体 agent loop。
+agent 会话的持久目标状态，独立于消费它的面向模型工具与续行策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体的 agent loop（智能体循环）。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 8f238d7429..90285c2860 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/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/goal/command-goal/README.md
 README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
-README.zh.md: cc5f7ba9bd3c5e50d3b7ce204d8d8c400e4f0955
+README.zh.md: 82750a102784fad7da1038a97478880f60001bdf
diff --git a/packages/goal/command-goal/README.zh.md b/packages/goal/command-goal/README.zh.md
index cc5f7ba9bd..82750a1027 100644
--- a/packages/goal/command-goal/README.zh.md
+++ b/packages/goal/command-goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md)负责用户体验与组合决策。
+面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) 负责用户体验与组合决策。
 
 ## 命令契约
 
@@ -40,7 +40,7 @@
 
 #### 模型看到的内容
 
-斜杠输入、变更以及直接状态／错误输出不会进入模型请求。Goal 领域把变更记录为 `goal/change`；已启用的同会话驱动器可以在后续继续执行提示词中暴露结果状态。呈现文本绝不会记录到日志中。
+斜杠输入、变更以及直接状态／错误输出不会进入模型请求。goal 领域把变更记录为 `goal/change`；已启用的同会话驱动器可以在后续继续执行提示词中暴露结果状态。呈现文本绝不会记录到日志中。
 
 #### Token 影响
 
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index d8fbf8fc29..5593953d89 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/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/goal/goal/README.md
 README.md: 98765a809820bcd4aeba31e1dd4ef6e92eb30760
-README.zh.md: dbc499104bac6cf09f9b1c871143da8781a8f082
+README.zh.md: 7f59fc4b538ad68bfcf0686b7651d0ec64470c2e
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index dbc499104b..7f59fc4b53 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。
+事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前待完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。
 
 ## 配置
 
@@ -17,7 +17,7 @@
 
 ## 服务契约
 
-`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回分离的 `GoalView`；变更通过 `GoalRef { id, revision }` 比较并设置限制，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发送变更事件。
+`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更以 `GoalRef { id, revision }` 作为比较并设置防护，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更。
 
 最多只有一个当前目标。创建操作会生成 revision 为 1、phase 为 active 的目标并启用续行。未完成的目标必须编辑、转换或清除；已完成目标可以由拥有全局未使用过的 id 的目标替换。编辑会保留 phase、blocker reason 与 activation。暂停、完成、阻塞和清除都会停用续行。阻塞会记录策略自有的 lower-kebab-case 代码和规范化的自由文本说明；提供方限制、配置预算、执行错误与请求人工输入都使用这一种持久 phase，不会扩增生命周期状态。只有配置的 Round 上限仍有剩余容量时，resume 才接受已停止 phase 或 phase 为 active 但已停用续行的目标；它会清除原 blocker reason。phase 为 active 且已启用续行的目标会拒绝冗余操作。
 
@@ -43,7 +43,7 @@ Goal 变更不会注入模型上下文。`get_goal` 等工具返回当前状态
 
 #### Token 影响
 
-Goal 变更事件本身不增加模型 token。工具结果与已调度的继续执行提示词分别计入其自身暴露的状态。
+Goal 变更事件本身不增加模型 token。工具结果和续行调度提示词各自暴露的状态会分别计入 token 用量。
 
 #### KV Cache 影响
 
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index b99cec734b..3097eeba3b 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
 README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
-README.zh.md: c7747e2febcb1656925fd556743eb2dd28090e37
+README.zh.md: 43f60599b737d66578b463386b872ca9cc3108e4
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index c7747e2feb..43f60599b7 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -1,8 +1,8 @@
-# guard/ — 循环卫生 guard 家族
+# guard/ — 循环健康 guard 家族
 
 [English](README.md) | 中文
 
-行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是 core seam 的自包含消费方，而非可替换能力。
+行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是核心 seam 的自包含消费方，而非可替换能力。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/host/README.i18n.yaml b/packages/host/README.i18n.yaml
index 0859a2571d..3eb8fe7eb8 100644
--- a/packages/host/README.i18n.yaml
+++ b/packages/host/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/host/README.md
 README.md: 926cb0b6b87a8ee76cb2dab745a31f620f4e7f5c
-README.zh.md: dc617084c756b80716f9a02bd2d22ba6954030f6
+README.zh.md: 7ef057ee56e56ddc2baa7092ccbe44fb161b7448
diff --git a/packages/host/README.zh.md b/packages/host/README.zh.md
index dc617084c7..7ef057ee56 100644
--- a/packages/host/README.zh.md
+++ b/packages/host/README.zh.md
@@ -6,14 +6,14 @@ dsh Web GUI 的宿主侧：所有客户端形态共享的 API 网关，以及承
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`apiproxy/`](apiproxy/README.md) | 共享宿主 API 网关和协议契约 | `ctx.apiProxy` |
+| [`apiproxy/`](apiproxy/README.md) | 共享宿主 API 网关和协议约定 | `ctx.apiProxy` |
 | [`webserver/`](webserver/README.md) | HTTP 路由载体 | `ctx.httpServer` |
 | [`frontend-static/`](frontend-static/README.md) | 占据 webserver 回退席位的 SPA dist 服务器 | 消费 `ctx.httpServer` |
-| [`directory-picker/`](directory-picker/README.md) | workspace 目录选择 seam | `ctx.directoryPicker` |
+| [`directory-picker/`](directory-picker/README.md) | 工作区目录选择 seam | `ctx.directoryPicker` |
 | [`directory-picker-native/`](directory-picker-native/README.md) | 原生目录选择器后端和浏览器交互 | 注册 `ctx.directoryPicker` |
 | [`directory-picker-browse/`](directory-picker-browse/README.md) | 应用内目录浏览器后端和交互 | 注册 `ctx.directoryPicker` |
 | [`directory-picker-auto/`](directory-picker-auto/README.md) | 宿主自适应选择器组合 | 挂载一个后端 |
 
 `apiproxy` 保持传输无关；[`client/connection`](../client/connection/README.md) 提供浏览器／HTTP 载体。选择器实现可在共享 seam 后互相替换。
 
-子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（挑选 seam）。
+子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（选择器 seam）。
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index a35bf870d4..a3ccfcf944 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/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/llm/README.md
 README.md: 077ae600c89cff80cd71830e37bda00707c1d837
-README.zh.md: e2bdad7fd0b33116498b50bfa6527974fa140fc9
+README.zh.md: 95355d34c014a1b442da1028251301d6d4202c6b
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index e2bdad7fd0..95355d34c0 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -1,8 +1,8 @@
-# llm/ — LLM 能力家族
+# llm/ — LLM（大语言模型）能力家族
 
 [English](README.md) | 中文
 
-LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内容块词汇和流式分片组装器；适配器是注册到 `ctx.llm` 的具体实现。这些全是**产品**包。
+LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内容块词汇和流式分片组装器；适配器是注册到 `ctx.llm` 的具体实现。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -14,4 +14,4 @@ LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
 
-子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器契约——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index be1dc838ff..abe4d95c7e 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
 README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
-README.zh.md: fa7dddeb011bd34c1f9cbe3a9dbf746d7f163897
+README.zh.md: 7a24bffa0e92f30c16a3307357ba7f1aa295ef52
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index fa7dddeb01..7a24bffa0e 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
+语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -10,7 +10,7 @@
 | `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力**而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
 设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
 
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 03487d5719..116b0ae54e 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/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/lsp/lsp-local/README.md
 README.md: 661c27d3326adfc3408b33550a63fe3ebe183a39
-README.zh.md: 83f0eaa1fb4caccc381a1623b791355b2f5c5b65
+README.zh.md: 9bc66ee00ff2f21df66b88aa607a555fd56e974b
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 83f0eaa1fb..9bc66ee00f 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -9,7 +9,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。服务器仍存活时返回的错误不会触发重试；如果选中的池化传输在只读查询之前或期间发生故障，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
 - 每次查询都使用兼容性优先的**临时打开**序列：通过 `ctx.fs` 流式读取源文件，同时解析并限制其字节数；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，再执行位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方 dispose 会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找完成，随后排空每条队列与每个服务器。
 - 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
diff --git a/packages/plan/README.i18n.yaml b/packages/plan/README.i18n.yaml
index 4e34bac80c..8291b525f1 100644
--- a/packages/plan/README.i18n.yaml
+++ b/packages/plan/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/plan/README.md
 README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
-README.zh.md: f068bf37b44daa0d724fbb85ad85a4d62883e847
+README.zh.md: 1b28af328f6da5cfabb09093c339f6504316f0e7
diff --git a/packages/plan/README.zh.md b/packages/plan/README.zh.md
index f068bf37b4..1b28af328f 100644
--- a/packages/plan/README.zh.md
+++ b/packages/plan/README.zh.md
@@ -10,4 +10,4 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
 
 [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
 
-子系统参考——`plan/mode` 折叠、步边界冲刷、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
+子系统参考——`plan/mode` 折叠、步骤边界刷新、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index 86afdb6310..7d4217d3d4 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/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/plan/plan-mode/README.md
 README.md: 6c8ba23b76e83665d4f8dcb5ecb41689347f6423
-README.zh.md: b306d5562af21dd9a95bb68c9acfc3f40c52136f
+README.zh.md: 275a87669802f38cd98886236ca63a09ffb3e410
diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md
index b306d5562a..275a876698 100644
--- a/packages/plan/plan-mode/README.zh.md
+++ b/packages/plan/plan-mode/README.zh.md
@@ -8,7 +8,7 @@
 
 `plan/mode`（`{ active: boolean }`）是一个仅存在于日志中、每次以完整值替换的 `SessionEventMap` 成员。`foldPlanMode(events)` 返回最后记录的值，如果没有则返回 `false`，因此恢复、fork 和压缩（compaction）都能直接从会话日志恢复 plan 状态。UI 通过 `session/event` 观察已提交的切换。
 
-`ctx.planMode.set(agent, active)` 在 agent 空闲时立即提交——下一个 prompt 之前不会有任何边界到来，因此独立的 `plan/mode` 事件当场落账——在 agent 运行中则持有待生效选择、等下一个被接受的轮内 pre-step；返回值说明发生了哪种（`committed`/`queued`）、一次 `cancelled` 反转或 `noop`。`get(agent)` 返回 `{ active, pending? }`，将塑造当前步骤的日志状态与用户的轮中选择分开。初始与续步 pre-step 边界都在覆盖范围内；同一步骤的请求恢复重试会复用已冻结的 assembly，并将该选择保留到下一个 pre-step。当最后记录的请求头描述了另一状态时，用户选择的变更会贡献一条插件来源的 `user/message` 通知（两条提交路径皆然）。
+`ctx.planMode.set(agent, active)` 在 agent 空闲时立即提交——下一个 prompt 之前不会有任何边界到来，因此独立的 `plan/mode` 事件当场落账——在 agent 运行中则持有待生效选择，并等待下一个被接受的轮内 pre-step；返回值区分 `committed`、`queued`、表示反转的 `cancelled` 和 `noop`。`get(agent)` 返回 `{ active, pending? }`，将塑造当前步骤的日志状态与用户的轮中选择分开。初始与续步 pre-step 边界都在覆盖范围内；同一步骤的请求恢复重试会复用已冻结的 assembly，并将该选择保留到下一个 pre-step。当最后记录的请求头描述了另一状态时，用户选择的变更会贡献一条插件来源的 `user/message` 通知（两条提交路径皆然）。
 
 ## 模型与人类交互
 
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 7f4c7f1f21..a5d814f00d 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
 README.md: 2afb3cd61ef4bfba460716549d41f799e419ff46
-README.zh.md: 57a5c93047ccb970f499f02c0168db7e9f71b622
+README.zh.md: e0871e23b954b5e611670d0519b938c9fcb28e43
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index 57a5c93047..e0871e23b9 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作契约。
+`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作约定。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
@@ -12,4 +12,4 @@
 
 设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
 
-子系统参考——id、后端/会话契约、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与延后边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
+子系统参考——id、后端/会话约定、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与暂缓边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index bd835a091d..238e2aa749 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
 README.md: 5acc92853e6e8fcb8938c48e391559bf4a28fb75
-README.zh.md: 353c2a4bdac7e8402fc63071dfb6fb85dcff66d5
+README.zh.md: 7d070a9a4aceab921264f020716fbdf16fdd57ff
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 353c2a4bda..7d070a9a4a 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
@@ -32,5 +32,5 @@
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
 - 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
-- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的契约，而非这个 PTY 消费方。
+- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的约定，而非这个 PTY 消费方。
 - harness 进程退出后，会话无法继续存在。
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 99a5265418..72a03cbfdd 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/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/sandbox/sandbox/README.md
 README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
-README.zh.md: e43d1918a99fa96688632551a8f861c2c91f9c2a
+README.zh.md: 1e9ecee967bfc3621d6fb441f405e84896fa7863
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index e43d1918a9..1e9ecee967 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -4,7 +4,7 @@
 
 抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
-用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
+用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
 
@@ -39,5 +39,5 @@ sandbox mode "<mode>" is requested but no sandbox backend is usable on this host
 - **文件操作是完整的策略词汇**：该 seam 不表达网络、进程、系统调用、设备或凭据限制。
 - **只支持与宿主共享文件系统和内核的限制**：容器、microVM 与远程执行需要替换能力实现，而不是在此处增加提供方。
 - **拒绝报告是一种 stderr 方言**：该 seam 返回后端签名，而非类型化运行时拒绝通道，因此需要分类的消费方必须从子进程输出推断。
-- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过约束；带外 runner 状态通道暂缓实现。
+- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过限制；带外 runner 状态通道暂缓实现。
 - **每个上下文只有一个提供方**：同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。
diff --git a/packages/skill/README.i18n.yaml b/packages/skill/README.i18n.yaml
index 758d0552f9..f782f16c34 100644
--- a/packages/skill/README.i18n.yaml
+++ b/packages/skill/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/skill/README.md
 README.md: cd606e778335249bf8ecc876d3b1a4e5feb79448
-README.zh.md: 4db7e2524596f4c62144ec7eabe7c6af63e2e270
+README.zh.md: ec43a531033799e5e5e920c1b2212f39a5699e81
diff --git a/packages/skill/README.zh.md b/packages/skill/README.zh.md
index 4db7e25245..ec43a53103 100644
--- a/packages/skill/README.zh.md
+++ b/packages/skill/README.zh.md
@@ -11,6 +11,6 @@
 | [`skill-local/`](skill-local/README.md) | 从本地文件系统发现 skill | 注册到 `ctx.skills` |
 | [`tool-skill/`](tool-skill/README.md) | 发布 skill 目录和面向模型的 loader | 注册到 `ctx.tools` |
 
-该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的契约。
+该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的约定。
 
 子系统参考——发现优先级、目录快照、`skill` 加载器——见 [docs/subsystems/skills.md](../../docs/subsystems/skills.md)。
diff --git a/packages/spill/README.i18n.yaml b/packages/spill/README.i18n.yaml
index 62ed26a59b..1d1ace946c 100644
--- a/packages/spill/README.i18n.yaml
+++ b/packages/spill/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/spill/README.md
 README.md: 74fd4837cb23767754174df168f2f4ba71c2b938
-README.zh.md: 16d677719a9c3f4245a2f446017641ff6b50ffa8
+README.zh.md: 2417bb793dca1cb10ead6208cb6ad896c18cdf03
diff --git a/packages/spill/README.zh.md b/packages/spill/README.zh.md
index 16d677719a..2417bb793d 100644
--- a/packages/spill/README.zh.md
+++ b/packages/spill/README.zh.md
@@ -12,4 +12,4 @@
 
 参见[工具输出 spill 决策](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中记录了存储、保留和工具自有输出处理之间的边界。
 
-子系统参考——`SaveTextSpill`、owner/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+子系统参考——`SaveTextSpill`、所有者/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index fe76e74a77..c7d3ce46ee 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/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/subagent/README.md
 README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
-README.zh.md: fb18afba5d8680408f0f37ab75056a3fb0ef660a
+README.zh.md: 04351f26721849de730db6083f55abc8e8571ce4
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index fb18afba5d..04351f2672 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -18,6 +18,6 @@
 | [`tool-subagent-control/`](tool-subagent-control/README.md) | 向模型公开子级消息发送和列举操作 | 注册到 `ctx.tools` |
 | [`tool-subagent-report/`](tool-subagent-report/README.md) | 提供从子级到父级的报告通道 | 注册到子级作用域 |
 
-参见[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)决策。
+参见有关[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)的决策。
 
 子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 246d702892..3973b5dd92 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/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/subagent/subagent-dsh-sdk/README.md
 README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
-README.zh.md: ffb1b8f4cddca4566a20593bdac54801ad8db38f
+README.zh.md: 5b196da8f11d71b065ee8111cec010b62edd896c
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index ffb1b8f4cd..5b196da8f1 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -16,7 +16,7 @@ SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepS
 
 ## 停止原因映射
 
-SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个持久 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 契约禁止 `result` 被拒绝。
+SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个已持久化的 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 约定禁止 `result` 被拒绝。
 
 ## 能力与上下文
 
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 1025b0e342..23ed818ebb 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
 README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
-README.zh.md: 05b1e4dd4c74b6d62df8b0a310534fc9476f3ade
+README.zh.md: b385182f032da17e7326ac265f47a2a5046f918a
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 05b1e4dd4c..b385182f03 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方使用统一的服务 API（`ctx.subagents`）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。
 
-[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和结果契约、持久描述符以及可继续子级编排。多个具名提供方可以在该契约背后共存。
+[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享的请求与结果约定、持久描述符以及可继续子级编排。多个具名提供方可以在该约定背后共存。
 
 ## 服务 API
 
@@ -23,7 +23,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
-| `listDescendants(rootSessionId, signal?)` | 从同一份实时优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消契约均沿用 `listChildren()`。 |
+| `listDescendants(rootSessionId, signal?)` | 从同一份在线优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消约定均沿用 `listChildren()`。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -80,13 +80,13 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
-当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
+当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使消费方替换陈旧身份而不是将其保留——绝不抛错。
 
 `registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 明确报错，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 明确报错。完整约定见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index 367a73fd1f..d25adaad9d 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/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/subagent/tool-subagent-control/README.md
 README.md: 4d9991b720bbbff8862e693b6aaed332f414af0e
-README.zh.md: dc1c81fc3313a8dfa277f33ae745702ed5b9d34b
+README.zh.md: 6f7138571fa7f8cb500df1a513f92d1f7f2b82e6
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index dc1c81fc33..6f7138571f 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -6,7 +6,7 @@
 
 本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
-`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标静止；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
+`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
 
 `list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）、`complete`（仅存于存储）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
 
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 2088cbdb6b..c90e0949bd 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
 README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
-README.zh.md: d2c539fb1c66a914aa5f758d928fba01b5600d15
+README.zh.md: 734a2a5a27f0337a3015989556e571f4d18228e0
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index d2c539fb1c..734a2a5a27 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完全明确指定的受管子进程树，以及一项底层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 7a33a31d0c..e81656d84a 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
 README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
-README.zh.md: 3ad73bdea3b137f1c9139fdb1b52c49eb10b5500
+README.zh.md: 828e8818ce3366bd955d83f7ccb5dab0f0379c46
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 3ad73bdea3..828e8818ce 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -11,7 +11,7 @@
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；存活传输失败会拒绝 `done`。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；仍处于活动状态的传输若发生故障，会使 `done` 拒绝。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
diff --git a/packages/tasks/README.i18n.yaml b/packages/tasks/README.i18n.yaml
index d5df91be62..bf9be6a596 100644
--- a/packages/tasks/README.i18n.yaml
+++ b/packages/tasks/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/tasks/README.md
 README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
-README.zh.md: d030081470a503fb52fd72dcc6f89f4c535dc38c
+README.zh.md: 97d258ffdc88b728ecabd9d20afaf228d620d8a4
diff --git a/packages/tasks/README.zh.md b/packages/tasks/README.zh.md
index d030081470..97d258ffdc 100644
--- a/packages/tasks/README.zh.md
+++ b/packages/tasks/README.zh.md
@@ -6,10 +6,10 @@
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`tasks/`](tasks/README.md) | 定义任务注册表和生命周期契约 | `ctx.tasks` |
+| [`tasks/`](tasks/README.md) | 定义任务注册表和生命周期约定 | `ctx.tasks` |
 | [`tasks-local/`](tasks-local/README.md) | 实现进程本地任务注册表 | 注册到 `ctx.tasks` |
 | [`tool-tasks/`](tool-tasks/README.md) | 向模型公开任务控制和完成通知 | 注册到 `ctx.tools` |
 
 参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
 
-子系统参考——id 方案、拥有者围栏契约、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
+子系统参考——id 方案、拥有者围栏约定、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
diff --git a/packages/todo/README.i18n.yaml b/packages/todo/README.i18n.yaml
index 57a1538b78..b9f4c9fef1 100644
--- a/packages/todo/README.i18n.yaml
+++ b/packages/todo/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/todo/README.md
 README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
-README.zh.md: 3c1c35187b5111f1fdb607d70b980be57e3e79c1
+README.zh.md: 9c5d6a9cc3f6078d5609aea668684ea0e4275835
diff --git a/packages/todo/README.zh.md b/packages/todo/README.zh.md
index 3c1c35187b..9c5d6a9cc3 100644
--- a/packages/todo/README.zh.md
+++ b/packages/todo/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | [`tool-todo/`](tool-todo/README.md) | 存储并公开会话的 todo 列表。 | （注册到 `ctx.tools`） |
 
-子级 README 负责工具、持久化和渲染契约。
+子级 README 负责工具、持久化和渲染约定。
 
 事件载荷记录在 [docs/subsystems/session.md](../../docs/subsystems/session.md)。
diff --git a/packages/web/README.i18n.yaml b/packages/web/README.i18n.yaml
index 87177273da..0eaedfb018 100644
--- a/packages/web/README.i18n.yaml
+++ b/packages/web/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/web/README.md
 README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
-README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc
+README.zh.md: c7c0546c6a2527ba04bd802945c0dd4ee4353a37
diff --git a/packages/web/README.zh.md b/packages/web/README.zh.md
index e328447d5d..c7c0546c6a 100644
--- a/packages/web/README.zh.md
+++ b/packages/web/README.zh.md
@@ -13,6 +13,6 @@
 | [`web-fetch-local/`](web-fetch-local/README.md) | 抓取公共 HTTP 和 HTTPS 资源 | 注册到 `ctx.web` |
 | [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
 
-[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
+[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) 记录了搜索和抓取共用一项提供方选择服务的原因。
 
 子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。
diff --git a/packages/workflow/README.i18n.yaml b/packages/workflow/README.i18n.yaml
index 05ad673c61..1d87cec1bf 100644
--- a/packages/workflow/README.i18n.yaml
+++ b/packages/workflow/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/workflow/README.md
 README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
-README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
+README.zh.md: 8460e22347a6c24b84f12f641479edb78bf1ed1e
diff --git a/packages/workflow/README.zh.md b/packages/workflow/README.zh.md
index 33b3f26780..8460e22347 100644
--- a/packages/workflow/README.zh.md
+++ b/packages/workflow/README.zh.md
@@ -1,4 +1,4 @@
-# workflow/：动态工作流能力家族
+# workflow/：动态工作流能力族
 
 [English](README.md) | 中文
 
@@ -11,6 +11,6 @@
 | [`tool-workflow/`](tool-workflow/README.md) | 向模型公开通用工作流执行 | 注册到 `ctx.tools` |
 | [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
 
-worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
+worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) 和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) 决策。
 
-子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
+子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
diff --git a/packages/workspace/README.i18n.yaml b/packages/workspace/README.i18n.yaml
index c7723f6c56..427a7aac69 100644
--- a/packages/workspace/README.i18n.yaml
+++ b/packages/workspace/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/workspace/README.md
 README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
-README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29
+README.zh.md: e59f54ad3d22201304a8126e0b0fbcab79fd17a7
diff --git a/packages/workspace/README.zh.md b/packages/workspace/README.zh.md
index 6315ccb6b3..e59f54ad3d 100644
--- a/packages/workspace/README.zh.md
+++ b/packages/workspace/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | [`workspace/`](workspace/README.md) | 注册 workspace 并记录其会话归属 | `ctx.workspace` |
 
-[workspace 包参考](workspace/README.md)负责生命周期、持久化和删除语义。
+[workspace 包参考](workspace/README.md) 负责生命周期、持久化和删除语义。
 
 子系统参考——实体、realpath 规范、注册/解析——见 [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md)；存储设计见 [domain KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。

From c9205901ecd6ef51ca06ecba0d5c49b124ebcc08 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 10:29:13 +0800
Subject: [PATCH 172/262] =?UTF-8?q?fix(doc-gates):=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20scan=20every=20merge=20block,=20any=20quote=20style?=
 =?UTF-8?q?,=20.tsx=20too;=20self-check=20the=20scan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot round: the backstop stopped at a file's first declare-module
block while the projection it guards reads them all; the textual prefilter
matched only single quotes; .tsx sources escaped the glob. All three are the
silent-vanish class the scan exists to prevent. contextMergeFiles now yields
one entry per block (quote-agnostic prefilter, ts+tsx patterns), and a third
partition direction requires everything rendered to be scan-visible, so a
future scan regression is a hard error. Spec fixture made projection-
consistent; the partially superseded 2026-07-28 regions note is rewritten to
the current mechanism and cross-linked both ways.
---
 ...08-09-cordis-event-walk-backstop.i18n.yaml |  4 +-
 .../2026-08-09-cordis-event-walk-backstop.md  |  6 +-
 ...026-08-09-cordis-event-walk-backstop.zh.md |  6 +-
 ...subsystem-cordis-surface-regions.i18n.yaml |  4 +-
 ...28-per-subsystem-cordis-surface-regions.md |  2 +-
 ...per-subsystem-cordis-surface-regions.zh.md |  2 +-
 scripts/cordis-walk.ts                        | 48 ++++++++-----
 scripts/gen-cordis-catalog-partition.spec.ts  | 68 ++++++++++++++++++-
 scripts/gen-cordis-catalog.ts                 | 17 ++++-
 9 files changed, 123 insertions(+), 34 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
index e968e7b54e..5747d0da3f 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.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 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
-2026-08-09-cordis-event-walk-backstop.md: 59aeb06149925dc93839df64145555f27257d7be
-2026-08-09-cordis-event-walk-backstop.zh.md: 4549e9d382e5ff17ddff30eafad8d6c7e66d61ed
+2026-08-09-cordis-event-walk-backstop.md: 1d833858f9471c98f54b3793edd12e4710b8c0fc
+2026-08-09-cordis-event-walk-backstop.zh.md: 0cb0f3bd738b6cee703cee71f1c24741554df87a
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
index 59aeb06149..1d833858f9 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-09-cordis-event-walk-backstop.zh.md)
 
 ## Problem
 
-`gen-cordis-catalog` renders every service and event the Typert host-face projection discovers, and fail-closed page maps (`SERVICE_PAGE`, `EVENT_SCOPE_PAGE`) guarantee each discovered key or scope lands on exactly one `docs/subsystems/` page. Discovery itself was only backstopped for services: an independent AST scan read every `declare module 'cordis'` Context merge and demanded each declared key be rendered or carry a named `SERVICE_WALK_EXEMPTIONS` reason.
+`gen-cordis-catalog` renders every service and event the Typert host-face projection discovers, and fail-closed page maps (`SERVICE_PAGE`, `EVENT_SCOPE_PAGE`) guarantee each discovered key or scope lands on exactly one `docs/subsystems/` page ([per-subsystem regions decision](../process/2026-07-28-per-subsystem-cordis-surface-regions.md) owns the page-region mechanism). Discovery itself was only backstopped for services: an independent AST scan read every `declare module 'cordis'` Context merge and demanded each declared key be rendered or carry a named `SERVICE_WALK_EXEMPTIONS` reason.
 
 Events had no such backstop. The projection walks only files reachable from host-face package exports, so an `interface Events` merge in client-face code — or in any file the host analyzer cannot reach — vanished with no trace: 12 declared events (`slash/input-*`, `theme/change`, `locale/change`, and the client runtime's `*/changed` invalidation signals) were documented nowhere generated and nothing would ever notice a thirteenth. The services scan also globbed only `packages/*/*/src/*.ts`, so 13 client-face Context keys declared in nested files (`src/client/**`) were invisible to the very scan meant to prevent silent vanishing.
 
@@ -14,7 +14,7 @@ Events had no such backstop. The projection walks only files reachable from host
 
 Events get the exact mirror of the services backstop, and both scans read the full package source tree.
 
-`scripts/cordis-walk.ts` gains `eventNameList` (every member name of an `interface Events` merge, read from method and property members alike so a shape the projector would reject still enters the scan) and its merge-file prefilter matches the `declare module` heads instead of the literal text `interface Context`, so an Events-only merge file is not skipped. The scan glob in `gen-cordis-catalog` deepens from `packages/*/*/src/*.ts` to `packages/*/*/src/**/*.ts`.
+`scripts/cordis-walk.ts` gains `eventNameList` (every member name of an `interface Events` merge, read from method and property members alike so a shape the projector would reject still enters the scan); the scan yields every `declare module 'cordis'` block in a file (the Typert analyzer reads them all, so stopping at the first would hide a second block's face), and its quote-agnostic prefilter matches the `declare module` heads instead of the literal text `interface Context`, so an Events-only or double-quoted merge file is not skipped. The scan glob in `gen-cordis-catalog` deepens from `packages/*/*/src/*.ts` to `packages/*/*/src/**/*.{ts,tsx}` (two patterns). A third partition direction guards the scan itself: every rendered service key and event name must also be visible to the scan, so a scan regression (glob, prefilter, block walk) is a hard error rather than a silent backstop decay.
 
 A new curated `EVENT_WALK_EXEMPTIONS` map names every declared event the projection cannot see, with the reason and the package README that owns its surface. Keys are full event names, not scopes: client-face events share scopes with rendered host events (`commands/changed` beside the host `commands/*` family), so a scope-level exemption would mask a host-face regression. The partition check is fail-closed in both directions, exactly like the service maps: an unexempted invisible event, an exemption for an event that renders, and an exemption no merge declares are all hard errors.
 
@@ -24,7 +24,7 @@ The audit that motivated this found the host face already complete: 48 rendered
 
 ## Verification
 
-`scripts/gen-cordis-catalog-partition.spec.ts` proves each acceptance path: the green partition, an invisible unexempted event (named with its declaring file), a stale rendered-event exemption, a stale never-declared exemption, the service mirror of each, unmapped rendered surface in both page maps, and the scan reaching a nested Events-only merge file. Deleting one live exemption from the real tree makes `gen-cordis-catalog` fail loud with the event's name and declaring file; restoring it returns the generator to a byte-identical no-op regeneration (85 artifacts, 0 written), which also proves the new exemptions exactly cover today's surface. `verify-cordis-catalog` in doc-sync executes the partition on every run.
+`scripts/gen-cordis-catalog-partition.spec.ts` proves each acceptance path: the green partition, an invisible unexempted event (named with its declaring file), a stale rendered-event exemption, a stale never-declared exemption, the service mirror of each, unmapped rendered surface in both page maps, rendered surface the scan cannot see (the third direction), and the scan reaching nested Events-only merges, every block of a multi-block file, double-quoted heads, and `.tsx` sources. Deleting one live exemption from the real tree makes `gen-cordis-catalog` fail loud with the event's name and declaring file; restoring it returns the generator to a byte-identical no-op regeneration (85 artifacts, 0 written), which also proves the new exemptions exactly cover today's surface. `verify-cordis-catalog` in doc-sync executes the partition on every run.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
index 4549e9d382..0cb0f3bd73 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`gen-cordis-catalog` 渲染 Typert host face 投影发现的每个服务与事件，fail-closed 的页面映射（`SERVICE_PAGE`、`EVENT_SCOPE_PAGE`）保证每个被发现的 key 或 scope 恰好落在一个 `docs/subsystems/` 页面上。但"发现"本身此前只对服务有兜底：一条独立的 AST 扫描读取每个 `declare module 'cordis'` Context merge，要求每个声明的 key 要么被渲染、要么在 `SERVICE_WALK_EXEMPTIONS` 中给出具名理由。
+`gen-cordis-catalog` 渲染 Typert host face 投影发现的每个服务与事件，fail-closed 的页面映射（`SERVICE_PAGE`、`EVENT_SCOPE_PAGE`）保证每个被发现的 key 或 scope 恰好落在一个 `docs/subsystems/` 页面上（页面区块机制归[按子系统区块决定](../process/2026-07-28-per-subsystem-cordis-surface-regions.md)所有）。但"发现"本身此前只对服务有兜底：一条独立的 AST 扫描读取每个 `declare module 'cordis'` Context merge，要求每个声明的 key 要么被渲染、要么在 `SERVICE_WALK_EXEMPTIONS` 中给出具名理由。
 
 事件没有这样的兜底。投影只遍历从 host face 包导出可达的文件，因此 client face 代码——或 host 分析器无法触及的任何文件——里的 `interface Events` merge 会无声消失：12 个已声明事件（`slash/input-*`、`theme/change`、`locale/change`，以及 client runtime 的 `*/changed` 失效信号）不出现在任何生成文档中，而且再多一个也不会有任何机制察觉。服务扫描的 glob 也只有 `packages/*/*/src/*.ts`，于是声明在嵌套文件（`src/client/**`）中的 13 个 client face Context key 恰恰对这条为防止无声消失而存在的扫描不可见。
 
@@ -14,7 +14,7 @@ Status: implemented
 
 事件获得与服务兜底完全对称的机制，且两条扫描都读取完整的包源码树。
 
-`scripts/cordis-walk.ts` 新增 `eventNameList`（`interface Events` merge 的每个成员名，方法与属性成员一并读取，使投影器会拒绝的形状也进入扫描），其 merge 文件预过滤改为匹配 `declare module` 头部而非字面文本 `interface Context`，从而不再跳过只含 Events 的 merge 文件。`gen-cordis-catalog` 的扫描 glob 从 `packages/*/*/src/*.ts` 加深为 `packages/*/*/src/**/*.ts`。
+`scripts/cordis-walk.ts` 新增 `eventNameList`（`interface Events` merge 的每个成员名，方法与属性成员一并读取，使投影器会拒绝的形状也进入扫描）；扫描产出文件中每一个 `declare module 'cordis'` 块（Typert 分析器读取全部块，止步于第一个会藏起第二个块的表面），其对引号风格不敏感的预过滤匹配 `declare module` 头部而非字面文本 `interface Context`，从而不再跳过只含 Events 或使用双引号的 merge 文件。`gen-cordis-catalog` 的扫描 glob 从 `packages/*/*/src/*.ts` 加深为 `packages/*/*/src/**/*.{ts,tsx}`（两个 pattern）。分区新增第三个方向守住扫描自身：投影渲染的每个服务 key 与事件名也必须对扫描可见，使扫描回归（glob、预过滤、块遍历）成为硬错误而非兜底的无声退化。
 
 新的人工维护映射 `EVENT_WALK_EXEMPTIONS` 为投影看不到的每个已声明事件命名，附理由与拥有其表面的包 README。键是完整事件名而非 scope：client face 事件与已渲染的 host 事件共享 scope（`commands/changed` 与 host 的 `commands/*` 家族并存），scope 级豁免会无声吞掉未来的 host face 回归。分区检查与服务映射一样双向 fail-closed：未豁免的不可见事件、已渲染事件的豁免、无任何 merge 声明的豁免，皆为硬错误。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ## Verification
 
-`scripts/gen-cordis-catalog-partition.spec.ts` 证明每条验收路径：绿色分区、不可见且未豁免的事件（报出声明文件）、已渲染事件的陈旧豁免、从未声明的陈旧豁免、服务侧的对称路径、两个页面映射中未映射的已渲染表面，以及扫描触达嵌套的仅含 Events 的 merge 文件。在真实源码树上删除一条现役豁免会让 `gen-cordis-catalog` 以事件名与声明文件大声失败；恢复后生成器回到字节相同的 no-op 再生成（85 个 artifact，0 写入），这同时证明新豁免恰好覆盖当下表面。doc-sync 中的 `verify-cordis-catalog` 每次运行都会执行该分区检查。
+`scripts/gen-cordis-catalog-partition.spec.ts` 证明每条验收路径：绿色分区、不可见且未豁免的事件（报出声明文件）、已渲染事件的陈旧豁免、从未声明的陈旧豁免、服务侧的对称路径、两个页面映射中未映射的已渲染表面、扫描看不到的已渲染表面（第三方向），以及扫描触达嵌套的仅含 Events 的 merge、多块文件的每个块、双引号头部与 `.tsx` 源文件。在真实源码树上删除一条现役豁免会让 `gen-cordis-catalog` 以事件名与声明文件大声失败；恢复后生成器回到字节相同的 no-op 再生成（85 个 artifact，0 写入），这同时证明新豁免恰好覆盖当下表面。doc-sync 中的 `verify-cordis-catalog` 每次运行都会执行该分区检查。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
index 102b0ce5fe..c343571dba 100644
--- a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.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 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
-2026-07-28-per-subsystem-cordis-surface-regions.md: ef65bfc4c7dadd7dafe1a38f41656e6ecc61ea50
-2026-07-28-per-subsystem-cordis-surface-regions.zh.md: 1df18d7260800b89c95a9d4aeb0301adb0ee56f6
+2026-07-28-per-subsystem-cordis-surface-regions.md: f6d4494d4195ba27f2898eecb27af32b433af88b
+2026-07-28-per-subsystem-cordis-surface-regions.zh.md: ee2a3c9730e6259e9f53d1b722b04b99819af65b
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
index ef65bfc4c7..f6d4494d41 100644
--- a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
@@ -14,7 +14,7 @@ The [generated-catalog decision](../../archived/process/2026-06-20-generated-cor
 
 `gen-cordis-catalog.ts` injects each subsystem's service and event reference INTO its own page, between `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` markers, and the flat services/events catalogs are deleted. One page per subsystem now carries introduction, data structures, and the generated wiring surface.
 
-- **Curated fail-loud partition.** `SERVICE_PAGE` maps every discovered `ctx.<key>` to exactly one page; `EVENT_SCOPE_PAGE` maps every event scope. The generator hard-errors in both directions — an unmapped discovered service/scope, and a mapped key/scope the walk no longer discovers — so the partition cannot drift from the source surface. An independent scan of EVERY `declare module 'cordis'` Context merge backstops the rendering walk's blind spot (it only sees a root `index.ts` with a same-named service class): a declared key the walk cannot render must carry a named `SERVICE_WALK_EXEMPTIONS` reason (today: the `ctx.agent` DX accessor, plus the interface-typed or non-index-declared lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost), and stale exemptions hard-error; a `TODO(cordis-catalog-interface-services)` marks teaching the walk to render them.
+- **Curated fail-loud partition.** `SERVICE_PAGE` maps every discovered `ctx.<key>` to exactly one page; `EVENT_SCOPE_PAGE` maps every event scope. The generator hard-errors in both directions — an unmapped discovered service/scope, and a mapped key/scope the walk no longer discovers — so the partition cannot drift from the source surface. Independent AST scans of every `declare module 'cordis'` merge block under `packages/*/*/src/**` backstop the projection's blind spots for services AND events: a declared Context key or Events member the projection cannot render must carry a named `SERVICE_WALK_EXEMPTIONS`/`EVENT_WALK_EXEMPTIONS` reason, stale exemptions hard-error, and everything rendered must also be visible to the scan ([events-backstop decision](../architecture/2026-08-09-cordis-event-walk-backstop.md) owns the scan contract); a `TODO(cordis-catalog-interface-services)` marks teaching the projection to render the interface-typed entries.
 - **Byte-identical regions across the pair.** The generator writes the SAME English region bytes into `foo.md` and `foo.zh.md`, extending the existing rule that verbatim code fences match across a pair. `verify-translation-pairing` gained a dedicated region-identity check (`partitionGeneratedRegions` in `translation-pairing.ts` owns the marker grammar) that names a divergent or malformed region precisely; the whole-document structural signature still covers the region content a second time.
 - **Guarded pair auto-record.** A regeneration that changes region bytes would leave every touched pair out-of-sync, so the generator re-records a pair's `.i18n.yaml` itself — but ONLY when the write is region-confined: both sides' recorded blob hashes must match the pre-write bytes, and the region-STRIPPED content must be unchanged on both sides. Human-prose drift leaves the record stale so the pairing gate still forces the normal translation flow; a brand-new pair is never auto-recorded (the author's reviewed `--write` owns that). This keeps `.i18n.yaml` as plain `git hash-object` values — no stripped-hash semantics change.
 - **The inherited tier moved, not died.** The vendor `ctx` members and `internal/*`/loader/hmr/timer events render to `docs/cordis-api/inherited.md`, next to the relocated Cordis core API pages (`docs/cordis-catalog/core/` → `docs/cordis-api/`). Framework surface lives under a framework home; the harness pages stay repository-owned vocabulary.
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
index 1df18d7260..ee2a3c9730 100644
--- a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 `gen-cordis-catalog.ts` 把每个子系统的服务与事件参考注入到该子系统自己的页面内部，置于 `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` 标记之间；平铺的 services/events 目录随之删除。现在每个子系统由一个页面同时承载介绍、数据结构和生成的接线表面。
 
-- **人工维护、响亮失败的划分。** `SERVICE_PAGE` 把发现的每个 `ctx.<key>` 映射到恰好一个页面；`EVENT_SCOPE_PAGE` 映射每个事件作用域。生成器在两个方向上都会直接报错（既有被发现却未映射的服务或作用域，也有已映射但遍历不再发现的键或作用域），因此划分不可能相对源码表面发生漂移。一个独立扫描会读取每一处 `declare module 'cordis'` 的 Context 合并，为渲染遍历的盲区（它只看得到根 `index.ts` 中同名服务类）兜底：遍历渲染不了的已声明键必须在 `SERVICE_WALK_EXEMPTIONS` 中带着点名理由（目前是 `ctx.agent` 这一 DX 访问器字段，加上接口类型或不在 index 声明的 lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost），陈旧豁免同样直接报错；教会遍历渲染它们的后续工作由 `TODO(cordis-catalog-interface-services)` 标记。
+- **人工维护、响亮失败的划分。** `SERVICE_PAGE` 把发现的每个 `ctx.<key>` 映射到恰好一个页面；`EVENT_SCOPE_PAGE` 映射每个事件作用域。生成器在两个方向上都会直接报错（既有被发现却未映射的服务或作用域，也有已映射但遍历不再发现的键或作用域），因此划分不可能相对源码表面发生漂移。独立的 AST 扫描读取 `packages/*/*/src/**` 下每一个 `declare module 'cordis'` merge 块，为投影在服务与事件两侧的盲区兜底：投影渲染不了的已声明 Context key 或 Events 成员必须在 `SERVICE_WALK_EXEMPTIONS`/`EVENT_WALK_EXEMPTIONS` 中带着点名理由，陈旧豁免直接报错，且投影渲染的一切也必须对扫描可见（扫描契约归[事件兜底决定](../architecture/2026-08-09-cordis-event-walk-backstop.md)所有）；教会投影渲染接口类型条目的后续工作由 `TODO(cordis-catalog-interface-services)` 标记。
 - **区块在配对两侧按字节一致。** 生成器把同一份英文区块字节写入 `foo.md` 和 `foo.zh.md`，是对「围栏代码块在配对两侧逐字节一致」这一既有规则的延伸。`verify-translation-pairing` 新增了专门的区块一致性检查（标记语法归 `translation-pairing.ts` 中的 `partitionGeneratedRegions` 所有），能精确点名出现分歧或格式错误的区块；整篇文档的结构签名仍会把区块内容再覆盖一遍。
 - **带防护的配对自动记录。** 一次改变区块字节的重新生成会让每个被触及的配对失去同步，因此生成器会自行重新记录配对的 `.i18n.yaml`，但仅限本次写入完全限定在区块内的情况：两侧记录的 blob hash 必须与写入前的字节相符，且两侧剥离区块后的内容必须没有变化。人工行文若有漂移，记录就保持陈旧，配对门禁因此仍会强制走正常翻译流程；全新的配对绝不自动记录（那归作者经评审的 `--write` 所有）。这样 `.i18n.yaml` 保持为纯粹的 `git hash-object` 值：不引入任何「剥离后 hash」的语义变化。
 - **继承层搬了家，而非消亡。** vendor 的 `ctx` 成员与 `internal/*`/loader/hmr/timer 事件渲染到 `docs/cordis-api/inherited.md`，紧邻迁移后的 Cordis 核心 API 页面（`docs/cordis-catalog/core/` → `docs/cordis-api/`）。框架表面落在框架自己的归属之下；harness 页面仍是仓库自有的词汇。
diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index a7c22bea02..98763c0adf 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -9,41 +9,53 @@ import { globSync, readFileSync } from 'node:fs'
 import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 
+/** Cheap textual prefilter for a cordis module merge, quote-style agnostic
+ * (the AST match below reads `stmt.name.text` and never sees the quotes). */
+const MERGE_HEAD = /declare module ['"](?:cordis|\.\/context\.ts)['"]/
+
 /**
- * Parse every file matching `pattern` (repo-relative, sorted, `/`-normalized)
- * that textually contains a cordis module merge, yielding each file's
- * module-merge body. Files without a merge are skipped.
- * @param scanRoot - Repository root the pattern is resolved against.
- * @param pattern - Glob selecting the TypeScript files to scan.
- * @returns One entry per file with a cordis module merge, in path order.
+ * Parse every file matching `patterns` (repo-relative, sorted, `/`-normalized)
+ * that textually contains a cordis module merge, yielding one entry per merge
+ * BLOCK — a file may legally hold several `declare module 'cordis'` blocks
+ * (the Typert analyzer reads them all), so the exhaustiveness scan must too.
+ * Files without a merge are skipped.
+ * @param scanRoot - Repository root the patterns are resolved against.
+ * @param patterns - Glob(s) selecting the TypeScript files to scan.
+ * @returns One entry per cordis module block, in path then source order.
  */
 export function contextMergeFiles(
   scanRoot: string,
-  pattern: string,
+  patterns: string | readonly string[],
 ): { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] {
   const out: { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] = []
-  for (const rel of globSync(pattern, { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+  const rels = [...new Set(globSync(patterns as string | string[], { cwd: scanRoot }).map(s => s.split(sep).join('/')))].sort()
+  for (const rel of rels) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
-    if (!text.includes("declare module 'cordis'") && !text.includes("declare module './context.ts'")) continue
+    if (!MERGE_HEAD.test(text)) continue
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    out.push({ rel, sf, text, body })
+    for (const body of cordisModuleBodies(sf)) out.push({ rel, sf, text, body })
   }
   return out
 }
 
-/** The body of the cordis module merge in `sf`: `declare module 'cordis'`
- * (harness packages) or `declare module './context.ts'` (vendor core), or
- * null when the file has neither. */
-export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
+/** Every cordis module-merge body in `sf`: `declare module 'cordis'` (harness
+ * packages) or `declare module './context.ts'` (vendor core), in source order. */
+export function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
+  const bodies: ts.ModuleBlock[] = []
   for (const stmt of sf.statements) {
     if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue
     if (stmt.name.text !== 'cordis' && stmt.name.text !== './context.ts') continue
-    if (stmt.body && ts.isModuleBlock(stmt.body)) return stmt.body
+    if (stmt.body && ts.isModuleBlock(stmt.body)) bodies.push(stmt.body)
   }
-  return null
+  return bodies
+}
+
+/** The FIRST cordis module-merge body in `sf`, or null without one — for the
+ * vendor core-API renderer whose input files carry exactly one merge; the
+ * exhaustiveness scan uses {@link cordisModuleBodies} to read them all. */
+export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
+  return cordisModuleBodies(sf)[0] ?? null
 }
 
 /**
diff --git a/scripts/gen-cordis-catalog-partition.spec.ts b/scripts/gen-cordis-catalog-partition.spec.ts
index 7de64fffde..2c6ef2584d 100644
--- a/scripts/gen-cordis-catalog-partition.spec.ts
+++ b/scripts/gen-cordis-catalog-partition.spec.ts
@@ -61,12 +61,33 @@ describe('walkPartitionProblems', () => {
 
   it('rejects an event exemption whose event the projection renders', () => {
     const { input, maps } = baseline()
-    const rendered = { ...input, renderedEventNames: new Set(['llm/request', 'theme/change']) }
-    expect(walkPartitionProblems(rendered, maps)).toEqual([
+    // A projection that renders theme/change necessarily renders the theme
+    // scope too; the fixture models that and maps the scope so the only
+    // violation is the stale exemption.
+    const rendered = {
+      ...input,
+      renderedScopes: new Set(['llm', 'theme']),
+      renderedEventNames: new Set(['llm/request', 'theme/change']),
+    }
+    const mapped = { ...maps, eventScopePage: { llm: 'llm-streaming.md', theme: 'client-modules.md' } }
+    expect(walkPartitionProblems(rendered, mapped)).toEqual([
       expect.stringContaining("event 'theme/change' is rendered by the projection but still listed in EVENT_WALK_EXEMPTIONS"),
     ])
   })
 
+  it('rejects rendered surface the independent scan cannot see, naming the scan as the defect', () => {
+    const { input, maps } = baseline()
+    const blind = {
+      ...input,
+      declaredKeys: new Map([['theme', 'packages/client/ui-theme/src/client/index.ts']]),
+      declaredEvents: new Map([['theme/change', 'packages/client/ui-theme/src/client/index.ts']]),
+    }
+    expect(walkPartitionProblems(blind, maps)).toEqual([
+      expect.stringContaining('ctx.llm is rendered by the projection but the independent scan finds no Context merge declaring it'),
+      expect.stringContaining("event 'llm/request' is rendered by the projection but the independent scan finds no Events merge declaring it"),
+    ])
+  })
+
   it('rejects an event exemption no Events merge declares', () => {
     const { input, maps } = baseline()
     const stale = { ...maps, eventWalkExemptions: { ...maps.eventWalkExemptions, 'gone/away': 'nothing owns this' } }
@@ -123,6 +144,49 @@ describe('cordis-walk scan reach', () => {
     expect([...contextKeyMap(only.body, only.sf).keys()]).toEqual([])
   })
 
+  it('yields every merge block of a multi-block file, double-quoted heads, and .tsx sources', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cordis-walk-'))
+    roots.push(root)
+    const dir = join(root, 'packages/client/ui-x/src')
+    mkdirSync(dir, { recursive: true })
+    // The Typert analyzer reads every cordis module block in a file; the
+    // backstop must not stop at the first one, skip the double-quoted legal
+    // form, or ignore .tsx sources.
+    writeFileSync(join(dir, 'split.ts'), [
+      "declare module 'cordis' {",
+      '  interface Context {',
+      '    first: FirstService',
+      '  }',
+      '}',
+      'declare module "cordis" {',
+      '  interface Events {',
+      "    'second/changed'(): void",
+      '  }',
+      '}',
+      'export {}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'view.tsx'), [
+      "declare module 'cordis' {",
+      '  interface Context {',
+      '    fromTsx: TsxService',
+      '  }',
+      '}',
+      'export {}',
+      '',
+    ].join('\n'))
+    const merges = contextMergeFiles(root, ['packages/*/*/src/**/*.ts', 'packages/*/*/src/**/*.tsx'])
+    expect(merges.map(m => m.rel)).toEqual([
+      'packages/client/ui-x/src/split.ts',
+      'packages/client/ui-x/src/split.ts',
+      'packages/client/ui-x/src/view.tsx',
+    ])
+    const keys = merges.flatMap(m => [...contextKeyMap(m.body, m.sf).keys()])
+    const events = merges.flatMap(m => eventNameList(m.body, m.sf))
+    expect(keys).toEqual(['first', 'fromTsx'])
+    expect(events).toEqual(['second/changed'])
+  })
+
   it('reads string-literal and identifier member names from an Events merge', () => {
     const sf = ts.createSourceFile('x.ts', [
       "declare module 'cordis' {",
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index ef2b6c0ed5..aaae6f7649 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -573,7 +573,9 @@ export interface WalkPartitionMaps {
  * partition maps, fail-closed in both directions for services AND events: a
  * rendered key/scope must be mapped to a page, a mapped key/scope must still
  * render, and — the backstop — a DECLARED key/event the projection cannot see
- * must carry a named walk exemption (a rendered one must not). Pure so the
+ * must carry a named walk exemption (a rendered one must not). A third
+ * direction guards the scan itself: everything rendered must also be declared
+ * to the scan, so a scan blind spot cannot decay silently. Pure so the
  * acceptance paths are provable without running the projection.
  * @param input - rendered surface plus the declared-key/event scans.
  * @param maps - the curated page maps and walk exemptions.
@@ -622,6 +624,17 @@ export function walkPartitionProblems(input: WalkPartitionInput, maps: WalkParti
   for (const name of Object.keys(maps.eventWalkExemptions)) {
     if (!input.declaredEvents.has(name)) problems.push(`EVENT_WALK_EXEMPTIONS names '${name}' but no Events merge declares it; remove the stale exemption.`)
   }
+  // Self-check the scan itself: everything the projection renders is declared
+  // in a Context/Events merge the scan must also reach, so a rendered key or
+  // event the scan cannot see means the SCAN regressed (glob, prefilter, or
+  // block walk) — a partial blind spot that exemption staleness alone would
+  // never surface.
+  for (const key of input.renderedKeys.keys()) {
+    if (!input.declaredKeys.has(key)) problems.push(`ctx.${key} is rendered by the projection but the independent scan finds no Context merge declaring it; the scan has a blind spot (glob, prefilter, or module-block walk) — fix the scan, not the maps.`)
+  }
+  for (const name of input.renderedEventNames) {
+    if (!input.declaredEvents.has(name)) problems.push(`event '${name}' is rendered by the projection but the independent scan finds no Events merge declaring it; the scan has a blind spot (glob, prefilter, or module-block walk) — fix the scan, not the maps.`)
+  }
   return problems
 }
 
@@ -642,7 +655,7 @@ export function computeOutputs(): [string, string][] {
 
   const declaredKeys = new Map<string, string>()
   const declaredEvents = new Map<string, string>()
-  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/**/*.ts')) {
+  for (const { rel, sf, body } of contextMergeFiles(root, ['packages/*/*/src/**/*.ts', 'packages/*/*/src/**/*.tsx'])) {
     for (const key of contextKeyMap(body, sf).keys()) {
       if (!declaredKeys.has(key)) declaredKeys.set(key, rel)
     }

From 80019566f217c0fed069d419d283d8059236a1a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 10:56:05 +0800
Subject: [PATCH 173/262] =?UTF-8?q?chore(doc-gates):=20keep=20cordisModule?=
 =?UTF-8?q?Bodies=20module-local=20=E2=80=94=20knip=20flags=20the=20unused?=
 =?UTF-8?q?=20export?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/cordis-walk.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index 98763c0adf..3f878be13c 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -40,8 +40,9 @@ export function contextMergeFiles(
 }
 
 /** Every cordis module-merge body in `sf`: `declare module 'cordis'` (harness
- * packages) or `declare module './context.ts'` (vendor core), in source order. */
-export function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
+ * packages) or `declare module './context.ts'` (vendor core), in source order.
+ * Module-local: consumers walk blocks through {@link contextMergeFiles}. */
+function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
   const bodies: ts.ModuleBlock[] = []
   for (const stmt of sf.statements) {
     if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue

From 10ef3d4924925a1c77372a6b8707c7c0b4b79f29 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 03:05:29 +0800
Subject: [PATCH 174/262] docs,feat(doc-gates): fix 15 dead anchor fragments;
 verify-md-links now validates fragments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A corpus sweep under the doc/prose standards found 15 links whose #fragment
named no anchor in its target — reworded headings, one relocated contract
(tool-fs → the group README's no-timeout rule), and zh sides citing English
slugs their Chinese headings never produce. Fixed all 15 (zh sides get the
conventional explicit <a id> + English fragment), fixed the one generator-owned
instance at its source (gen-doc-graphs), and extended verify-md-links to
resolve fragments onto Markdown targets — same-file anchors included — against
heading slugs and explicit <a id>, so the class is gated instead of manually
grepped. Remaining probes (narrated history, duplication shingles, comment
transcripts, budgets) came back clean; sibling-adapter README symmetry and
implemented-note contrasts are deliberate keeps.
---
 .../2026-06-24-web-capability-seam.i18n.yaml  |   2 +-
 .../2026-06-24-web-capability-seam.zh.md      |   2 +
 ...26-08-09-md-fragment-anchor-gate.i18n.yaml |   6 +
 .../2026-08-09-md-fragment-anchor-gate.md     |  32 ++++
 .../2026-08-09-md-fragment-anchor-gate.zh.md  |  32 ++++
 .agents/skills/dsh-doc-standards/SKILL.md     |   2 +-
 docs/AGENTS.md                                |   2 +-
 docs/agent-lifecycle.md                       |   2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              |   2 +-
 docs/subsystems/llm-streaming.zh.md           |   2 +-
 packages/boot/app-boot/README.i18n.yaml       |   2 +-
 packages/boot/app-boot/README.zh.md           |   2 +
 packages/core/scope/README.i18n.yaml          |   4 +-
 packages/core/scope/README.md                 |   2 +-
 packages/core/scope/README.zh.md              |   2 +-
 packages/core/system-prompt/README.i18n.yaml  |   2 +-
 packages/core/system-prompt/README.zh.md      |   2 +
 packages/core/tools/README.i18n.yaml          |   4 +-
 packages/core/tools/README.md                 |   2 +-
 packages/core/tools/README.zh.md              |   2 +-
 .../credentials-local/README.i18n.yaml        |   2 +-
 .../credentials-local/README.zh.md            |   2 +
 packages/fs/tool-fs/README.i18n.yaml          |   4 +-
 packages/fs/tool-fs/README.md                 |   2 +-
 packages/fs/tool-fs/README.zh.md              |   2 +-
 scripts/gen-doc-graphs.ts                     |   2 +-
 scripts/verify-md-links.spec.ts               |  83 ++++++++++
 scripts/verify-md-links.ts                    | 148 ++++++++++++++----
 29 files changed, 304 insertions(+), 53 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
 create mode 100644 scripts/verify-md-links.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index fc370429b6..331aff7916 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
 2026-06-24-web-capability-seam.md: b705236690859961ed69b307dbb59ebefcbd65ac
-2026-06-24-web-capability-seam.zh.md: e3dc836004bf785c6811e4c4014e105266dbaade
+2026-06-24-web-capability-seam.zh.md: 15a16b12119f69cec632e219585600d261fda54f
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index e3dc836004..15a16b1211 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -322,6 +322,8 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 **大量 web 内容可能损害上下文质量。** 提供方强制执行字节/字符上限并报告 `truncated`；`tool-web` 格式化有界的模型输出，附带清晰的继续或后续引导。
 
+<a id="deferred-work"></a>
+
 ## 推迟工作
 
 - `web_fetch` 的 SSRF/私有网络防护：阻断私有、回环、链路本地、多播及其他非公开目的地，使 `web_fetch` 不再是 SSRF 原语。正确实现不仅仅是 URL 字符串检查——需要先 DNS 解析再连接到已验证的 IP（防御 DNS rebinding/TOCTOU）、跨重定向的每跳重新验证，以及 IPv6 边缘处理（私有范围、IPv4 映射地址）。所调研的参考实现均未做 IP 级阻断（OpenCode 做前缀检查后直接 fetch；Claude Code 依赖集中式主机名黑名单加「私有 URL 会失败」的提示词），因此没有可复制的实现，且这是 harness 唯一的 SSRF 防线——值得一次专门的设计/spike。在其落地之前，`web_fetch` 只能在无法触达敏感内部目标的部署中启用。
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
new file mode 100644
index 0000000000..734da74005
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.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 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
+2026-08-09-md-fragment-anchor-gate.md: 190ecb0ed07152761377961ca6221c25908082b0
+2026-08-09-md-fragment-anchor-gate.zh.md: ab08609d8b1410ccf0f36a6ced68729ac20c7658
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
new file mode 100644
index 0000000000..190ecb0ed0
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
@@ -0,0 +1,32 @@
+# Agent Note: verify-md-links validates fragment anchors, closing the last dead-link class
+
+Status: implemented
+
+English | [中文](2026-08-09-md-fragment-anchor-gate.zh.md)
+
+## Problem
+
+`verify-md-links` proved a relative link's target file exists but never looked at the `#fragment`, and the documentation standard compensated with a manual rule: grep anchors yourself before renaming a heading. A corpus sweep found 15 links whose fragments named no anchor in their target — three distinct decay modes: a heading reworded after the link was written (`#security-and-authority-are-explicit-non-goals` vs the note's current `Security and authority are non-goals`), a contract relocated to a different owning document (`tool-fs` linking the seam README for the no-timeout rule that now lives in the group README), and zh pair sides linking English slugs their Chinese headings never produce (`#deferred-work` against `## 推迟工作`). None of these fail any gate, and each silently strands the reader at the top of the target page.
+
+## Decision
+
+`verify-md-links` now resolves fragments too. For every relative link whose target is a Markdown file — same-file `#anchor` links included, which the old checker skipped entirely — the fragment must name a real anchor in the target: a heading's GitHub slug (repeated headings get the renderer's `-1`, `-2`, … suffixes) or an explicit `<a id>`. Fragments onto non-Markdown targets (`file.ts#L10`) carry renderer-owned semantics and stay out of scope, as do external and root-absolute URLs. Anchor sets are collected lazily for any existing target, so links INTO archived notes and vendor documents are validated without making those files sources.
+
+The slug function is GitHub's algorithm, duplicated from `gen-cordis-catalog`'s region-anchor renderer rather than shared across the script/package boundary; the corpus passing this gate is what keeps the two in sync. Chinese pair sides follow the existing repository convention (`docs/glossary.zh.md`, `docs/cordis-primer.zh.md`): keep the English fragment in the link and place an explicit `<a id>` before the Chinese heading, so both language sides expose identical anchors.
+
+The 15 broken fragments are fixed in the same change: stale slugs retargeted to the current headings, the relocated no-timeout contract now linked at its owning group README, and four zh documents given explicit anchors. `docs/AGENTS.md` and the `dsh-doc-standards` skill no longer prescribe the manual anchor grep for Markdown links; anchors cited from TypeScript strings still need one.
+
+## Verification
+
+`scripts/verify-md-links.spec.ts` proves the acceptance paths: slugging (backticks, punctuation, repeat suffixes, explicit `<a id>`), a resolving mixed-link document, a dead same-file fragment, a dead cross-file fragment, and a missing target still reported as `target` rather than `anchor`. The gate runs over the full corpus in doc-sync (`verify-md-links`, 1613 files) and passes only after the 15 fixes — the corpus itself is the red-to-green evidence for each decay mode.
+
+## Alternatives considered
+
+- **Keep the manual-grep rule.** It demonstrably did not hold: the 15 fragments decayed under a gate-driven maintenance culture, because heading rewrites happen in PRs that never look at inbound links. A mechanical invariant belongs in an executed gate.
+- **Point zh links at Chinese-slug anchors.** GitHub slugs CJK headings fine, but the corpus convention is already explicit `<a id>` + English fragments (glossary, primer), which also survives renderers that strip non-ASCII; adopting a second convention would split the corpus.
+- **Share `githubSlug` with the typert generator.** A one-function import would couple a doc gate to a package build; the algorithm is three lines and the corpus gate itself detects divergence (a generator anchor the gate cannot resolve fails the build the moment a page links it).
+- **Validate VitePress slugs as well.** The published site's dead-link check already runs in `website:build`; generated regions carry explicit anchors precisely so the two renderers agree, and hand headings that diverge would fail there.
+
+## Consequences
+
+Renaming a heading now breaks the build wherever a Markdown link cites its anchor, instead of stranding readers; authors fix the inbound links in the same change, exactly as they already must for file renames. Same-file anchors are no longer a blind spot, so zh pages must anchor any English fragment they use. The manual pre-rename grep survives only for anchors cited from TypeScript string literals.
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
new file mode 100644
index 0000000000..ab08609d8b
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
@@ -0,0 +1,32 @@
+# Agent Note（agent 决策记录）：verify-md-links 校验 fragment 锚点，关闭最后一类死链
+
+Status: implemented
+
+[English](2026-08-09-md-fragment-anchor-gate.md) | 中文
+
+## Problem
+
+`verify-md-links` 只证明相对链接的目标文件存在，从不检查 `#fragment`，文档标准以一条人工规则补偿：重命名标题前自己 grep 锚点。一次语料扫描发现 15 条链接的 fragment 在目标中没有对应锚点——三种衰变模式：链接写下后标题被改写（`#security-and-authority-are-explicit-non-goals` 对 note 现在的 `Security and authority are non-goals`）、契约搬迁到另一份属主文档（`tool-fs` 链到 seam README，而无超时规则现居 group README）、zh 侧链接其中文标题永远不会生成的英文 slug（`#deferred-work` 对 `## 推迟工作`）。这些都不触发任何 gate，且每条都把读者悄悄丢在目标页顶部。
+
+## Decision
+
+`verify-md-links` 现在也解析 fragment。对每条目标为 Markdown 文件的相对链接——包括旧检查器完全跳过的同文件 `#anchor` 链接——fragment 必须命名目标中的真实锚点：标题的 GitHub slug（重复标题获得渲染器的 `-1`、`-2`……后缀）或显式 `<a id>`。指向非 Markdown 目标的 fragment（`file.ts#L10`）语义归渲染器所有，不在范围内；外部与根绝对 URL 同样不检查。锚点集合对任意存在的目标惰性收集，因此链入归档 note 与 vendor 文档的链接照常校验，而这些文件不会因此成为扫描源。
+
+slug 函数是 GitHub 的算法，从 `gen-cordis-catalog` 的区块锚点渲染器复制而来，而非跨脚本/包边界共享；语料通过本 gate 即是两者保持同步的机制。中文侧沿用既有语料惯例（`docs/glossary.zh.md`、`docs/cordis-primer.zh.md`）：链接保留英文 fragment，在中文标题前放置显式 `<a id>`，使两个语言侧暴露相同的锚点。
+
+15 条坏 fragment 在同一变更中修复：陈旧 slug 重定向到当前标题，搬迁的无超时契约改链其属主 group README，四份中文文档补上显式锚点。`docs/AGENTS.md` 与 `dsh-doc-standards` skill 不再为 Markdown 链接开人工 grep 锚点的处方；从 TypeScript 字符串引用的锚点仍需人工 grep。
+
+## Verification
+
+`scripts/verify-md-links.spec.ts` 证明各验收路径：slug 化（反引号、标点、重复后缀、显式 `<a id>`）、全部可解析的混合链接文档、死的同文件 fragment、死的跨文件 fragment、以及缺失目标仍报 `target` 而非 `anchor`。gate 在 doc-sync 中跑完整语料（`verify-md-links`，1613 个文件），且只有在 15 条修复之后才通过——语料本身就是每种衰变模式由红转绿的证据。
+
+## Alternatives considered
+
+- **保留人工 grep 规则。** 它被证明守不住：15 条 fragment 在 gate 驱动的维护文化下仍然衰变，因为改写标题的 PR 从不会去看入链。可机械检查的不变式应进入被执行的 gate。
+- **让中文链接指向中文 slug 锚点。** GitHub 对 CJK 标题的 slug 没问题，但语料惯例已是显式 `<a id>` + 英文 fragment（glossary、primer），且它在剥离非 ASCII 的渲染器下也存活；引入第二种惯例会割裂语料。
+- **与 typert 生成器共享 `githubSlug`。** 为一个函数引入包构建耦合不值得；算法只有三行，语料 gate 本身能探测分歧（生成器产出而 gate 无法解析的锚点，在任何页面链接它的那一刻即失败）。
+- **同时校验 VitePress slug。** 发布站点的死链检查已在 `website:build` 中运行；生成区块正是为两种渲染器一致而携带显式锚点，手写标题若有分歧会在那里失败。
+
+## Consequences
+
+重命名标题现在会在任何 Markdown 链接引用其锚点处使构建失败，而非把读者丢在页顶；作者须在同一变更中修复入链，与文件重命名的既有义务完全一致。同文件锚点不再是盲区，中文页面使用英文 fragment 时必须补锚点。人工的重命名前 grep 只对 TypeScript 字符串字面量中的锚点保留。
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 020768c200..49ab835752 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -29,7 +29,7 @@ Then check constraints that make placement expensive or wrong:
 
 - Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
-- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown links, `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments, but nothing catches heading-anchor fragments — grep `#the-heading` across the repo yourself (one anchor is hardcoded in `scripts/gen-cordis-catalog.ts`).
+- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings (one lives in `scripts/gen-cordis-catalog.ts`) still need a manual grep.
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
 
 ## Audit the corpus
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index a5eca656db..8d019fce08 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -72,6 +72,6 @@ Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standar
 
 ## Cross-reference with machine-checkable links, never free prose
 
-Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` catches missing targets; the [cross-link Agent Note](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md) owns the rationale.
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).
 
 The gate checks file existence, not `#anchor` validity — verify anchors yourself when linking to one.
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 5bf2c4454c..8690c792be 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -3,7 +3,7 @@
 
 # Agent Turn And Step Lifecycle
 
-This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+This sequence is the visual companion to [architecture.md](architecture.md#default-loop-lifecycle). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
 
 ```mermaid
 sequenceDiagram
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index f807656000..0945fee0a3 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: c65416f449d1783f398cdd81b0d6987de83a6141
-llm-streaming.zh.md: ce79ecca53edf7213853df118489817451baa7b0
+llm-streaming.md: 1705c45697df98b51ba9f69c8c91b3a8a18dea76
+llm-streaming.zh.md: 591326582c96023df5a184e19e3e4fc812187fb4
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index c65416f449..1705c45697 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -623,7 +623,7 @@ interface LlmCallConfigAdapterDefaults {
 
 ## The seam
 
-`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
+`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#model-content).
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index ce79ecca53..591326582c 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -631,7 +631,7 @@ interface LlmCallConfigAdapterDefaults {
 
 ## seam
 
-`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#content-blocks-and-streaming-dsh-llm)。
+`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#model-content)。
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 3ae6f5427c..fd61b9bec2 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
+README.zh.md: 454d504be72c2120ec4aeaa1b22545e7d6ba2fee
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 88d1c4ad0c..454d504be7 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -31,6 +31,8 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
 
+<a id="profiles"></a>
+
 ## Profile
 
 profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
diff --git a/packages/core/scope/README.i18n.yaml b/packages/core/scope/README.i18n.yaml
index c9212a3998..5db40dd188 100644
--- a/packages/core/scope/README.i18n.yaml
+++ b/packages/core/scope/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/core/scope/README.md
-README.md: 4f32573779a15e8c34b4936bfe75549dfc86d9f6
-README.zh.md: 16ec60a5489f909a46fd5f803dbf08490cd07988
+README.md: ecb442e39e40d5b97a07ccf8a71a190c4009ede8
+README.zh.md: f223d339129bcbef5c5f19ba6d0b453874944c4b
diff --git a/packages/core/scope/README.md b/packages/core/scope/README.md
index 4f32573779..ecb442e39e 100644
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -23,7 +23,7 @@ The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime asse
 
 ## Design contract
 
-The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) for rationale and security non-goals.
+The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals) for rationale and security non-goals.
 
 Scope-aware services define a concrete `ScopeLayer` that aggregates their heterogeneous tables and domain helpers. `ScopedLayers.effect()` accepts one synchronous action returning one synchronous undo, installs that undo before optional notification, and reclaims an exact-scope layer only when the complete aggregate is empty. `notify` defaults to `true`; the supplied callback owns whether observer failures throw or are contained. `EntryValues` remains internal, the storage classes are imported from the package root rather than a `/store` subpath, and the shared storage does not define registry-specific filtering or iteration policy. See the [shared scoped-layer storage Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md).
 
diff --git a/packages/core/scope/README.zh.md b/packages/core/scope/README.zh.md
index 16ec60a548..f223d33912 100644
--- a/packages/core/scope/README.zh.md
+++ b/packages/core/scope/README.zh.md
@@ -23,7 +23,7 @@
 
 ## 设计契约
 
-注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
+注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。
 
 感知作用域的服务会定义具体 `ScopeLayer`，聚合各自不同的表与领域辅助函数。`ScopedLayers.effect()` 接受一个返回同步撤销函数的同步动作，在可选通知前安装该撤销函数，并且只有在完整聚合为空时才回收精确作用域层。`notify` 默认为 `true`；由所提供的回调决定观测方失败是向外抛出还是在内部处理。`EntryValues` 保持内部可见；存储类从包根而非 `/store` 子路径导入；共享存储不定义注册表专属的筛选或迭代策略。详见[共享作用域层存储 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)。
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index c94d1722dc..6d56bec297 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
 README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5b9e2feaf82866a52cd8197ff5e800decdf3ee7e
+README.zh.md: bf659ea9961a9bb796c1ee1045ac7dad22bb997f
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5b9e2feaf8..bf659ea996 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -21,6 +21,8 @@
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void`：贡献提示词变量，在段文本中以 `{{name}}` 引用。带作用域变量会为该 agent 遮蔽同名全局变量。同层重复或无法引用的名称会抛出；`undefined` 表示「本次组装没有值」。随调用 fiber 一并 dispose。
 - `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 seam 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
 
+<a id="live-events"></a>
+
 ### 实时事件
 
 `system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发契约。
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index b19e86ce84..19d71e4dff 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
-README.zh.md: 796ee8e1aa8de88f979d825df5e0b4f39ab7bcf1
+README.md: 97aa97c6ca7675ff5b891e62224a4d1d7780ef42
+README.zh.md: f402722c81e1c7be9f45202a7bc79bfc85a41512
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index f3f25f908a..97aa97c6ca 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -18,7 +18,7 @@ tools:
 ### Public API
 
 - `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition with a mandatory canonical `output` declaration. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Missing or unsupported output declarations and a non-positive or non-finite `timeoutMs` fail at registration. The optional synchronous `finalizeContent` callback is snapshotted when a call starts and may replace only final model-facing content after every pipeline outcome is normalized, including an error discovered while materializing another result field. Disposed with the calling fiber.
-- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
+- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed.
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 796ee8e1aa..f402722c81 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -18,7 +18,7 @@ tools:
 ### 公开 API
 
 - `ctx.tools.register(definition: ToolDefinition): () => void`：注册一个受信任、带类型的同进程定义，其中必须包含规范的 `output` 声明。所在层由调用上下文的作用域决定：普通插件上下文会全局注册；agent 的 `agent.ctx` 只为该 agent 注册，并在此处遮蔽同名全局工具。同一层内名称重复会抛出；非原生模式还会拒绝保留的 `run_code` 传输名称。缺失或不受支持的输出声明，以及非正数或非有限的 `timeoutMs`，都会使注册失败。可选的同步 `finalizeContent` 回调会在调用开始时创建快照；在所有流水线结果规范化之后，它只能替换最终面向模型的内容，包括实体化其他结果字段时发现的错误。随调用 fiber dispose（资源释放）。
-- `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
+- `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined`：按某个作用域所见的结果解析（应用遮蔽；被限制掉的全局工具视为不存在）。呈现器会传入发起调用的 agent，使卡片与实际执行内容一致。
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]`：返回该作用域可见的所有 schema（不含 `execute` 函数）。已交付工具的 schema 收录在 [docs/tool-catalog.md](../../../docs/tool-catalog.md) 中；该目录通过启动每个工具插件并采集此方法的结果生成（参见[工具 schema 目录 Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)）。
 - `ctx.tools.guard(guard: ToolGuard): () => void`：在 `tools/pre-execute` 之后注册单调同步执行守卫：返回理由会拒绝调用，返回 `undefined` 则保持原决定。普通上下文守卫全局生效；`agent.ctx` 守卫只对该 agent 生效。后续 waterfall（瀑布式事件）监听器无法将守卫的拒绝重新变为允许。随调用 fiber dispose。
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 182ac31809..f0971f5d17 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/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/credentials/credentials-local/README.md
 README.md: 6051c07628c0214f9396d12554719c5614610826
-README.zh.md: c6f3901af925d4bd31d2dcfbf5f5f65de62dac81
+README.zh.md: 23f48080136b5d212bef34d931a74773c5da4fd3
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index c6f3901af9..23f4808013 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -49,6 +49,8 @@ OPENAI_API_KEY: sk-…
 
 外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
 
+<a id="security-boundary"></a>
+
 ## 安全边界
 
 文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../boot/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index e9000e3500..301816a56e 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: 28880860dc6c89745eb21fbf732d04f596f9b07f
-README.zh.md: 8af0aec51e71681211bbd5a4f582be8b8b0271b8
+README.md: 6f96970d8194c0992f9b955b95aec092185054b2
+README.zh.md: 2de8b02cd47f07af5a04a85694aec05214772a7f
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 28880860dc..6f96970d81 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -150,4 +150,4 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam.
 - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
-- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../fs/README.md#no-io-deadline)).
+- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../README.md#no-timeouts-on-file-io)).
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 8af0aec51e..2de8b02cd4 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -150,4 +150,4 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 - **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 bash 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。
-- **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../fs/README.md#no-io-deadline)）。
+- **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../README.md#no-timeouts-on-file-io)）。
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 1c4cce0fa3..cc26b6b0af 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1154,7 +1154,7 @@ function renderLifecycle(): string {
   const maintenance = 'curated Mermaid sequence; exact event signatures live in the generated Cordis catalog'
   return [
     ...generatedHeader('Agent Turn And Step Lifecycle'),
-    'This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
+    'This sequence is the visual companion to [architecture.md](architecture.md#default-loop-lifecycle). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
     '',
     '```mermaid',
     'sequenceDiagram',
diff --git a/scripts/verify-md-links.spec.ts b/scripts/verify-md-links.spec.ts
new file mode 100644
index 0000000000..4578583472
--- /dev/null
+++ b/scripts/verify-md-links.spec.ts
@@ -0,0 +1,83 @@
+/**
+ * Acceptance-path coverage for fragment validation in `verify-md-links`: a
+ * `#fragment` onto a Markdown target — same-file anchors included — must name
+ * a real heading slug or explicit `<a id>`, while non-Markdown fragments and
+ * external targets stay out of scope.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { documentAnchors, findViolations, githubSlug } from './verify-md-links.ts'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function layout(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'md-links-'))
+  roots.push(root)
+  for (const [rel, content] of Object.entries(files)) {
+    mkdirSync(join(root, rel, '..'), { recursive: true })
+    writeFileSync(join(root, rel), content)
+  }
+  return root
+}
+
+function violationsIn(root: string, rel: string): { url: string; reason: string }[] {
+  const cache = new Map<string, Set<string>>()
+  const anchorsOf = (abs: string): Set<string> => {
+    const hit = cache.get(abs)
+    if (hit) return hit
+    const anchors = documentAnchors(readFileSync(abs, 'utf8'))
+    cache.set(abs, anchors)
+    return anchors
+  }
+  return findViolations(join(root, rel), anchorsOf, root).map(({ url, reason }) => ({ url, reason }))
+}
+
+describe('documentAnchors', () => {
+  it('slugs headings, suffixes repeats, and reads explicit <a id> anchors', () => {
+    const anchors = documentAnchors([
+      '# My Doc',
+      '## Live `events` — mode!',
+      '## Repeat',
+      '## Repeat',
+      '<a id="hand-anchor"></a>',
+      '',
+    ].join('\n'))
+    expect(anchors).toEqual(new Set(['my-doc', 'live-events--mode', 'repeat', 'repeat-1', 'hand-anchor']))
+    expect(githubSlug('Security and authority are non-goals')).toBe('security-and-authority-are-non-goals')
+  })
+})
+
+describe('findViolations fragments', () => {
+  it('accepts resolving same-file and cross-file fragments, non-md fragments, and externals', () => {
+    const root = layout({
+      'a.md': '# A\n\n## Deferred work\n\n[self](#deferred-work) [b](b.md#part-two) [code](x.ts#L10) [ext](https://x.example/#frag)\n',
+      'b.md': '# B\n\n## Part two\n',
+      'x.ts': 'export {}\n',
+    })
+    expect(violationsIn(root, 'a.md')).toEqual([])
+  })
+
+  it('rejects a same-file fragment that names no heading or <a id>', () => {
+    const root = layout({ 'a.md': '# A\n\n[gone](#deferred-work)\n' })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: '#deferred-work', reason: 'anchor' }])
+  })
+
+  it('rejects a cross-file fragment missing from the target document', () => {
+    const root = layout({
+      'a.md': '# A\n\n[stale](b.md#old-heading)\n',
+      'b.md': '# B\n\n## New heading\n',
+    })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: 'b.md#old-heading', reason: 'anchor' }])
+  })
+
+  it('still rejects a missing target file, reported as target not anchor', () => {
+    const root = layout({ 'a.md': '# A\n\n[ghost](missing.md#anything)\n' })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: 'missing.md#anything', reason: 'target' }])
+  })
+})
diff --git a/scripts/verify-md-links.ts b/scripts/verify-md-links.ts
index 969b0f5e44..0286f6d516 100644
--- a/scripts/verify-md-links.ts
+++ b/scripts/verify-md-links.ts
@@ -1,8 +1,10 @@
 /**
- * Verify that relative Markdown links, images, and definitions resolve. URL,
- * root-absolute, and in-page targets are excluded; query strings and fragments
- * do not affect resolution against the source file. The checker never rewrites,
- * and symlinked instruction files are deduped.
+ * Verify that relative Markdown links, images, and definitions resolve — the
+ * target file must exist AND a `#fragment` onto a Markdown target (including
+ * a same-file `#anchor`) must name a real heading slug or explicit `<a id>`.
+ * URL and root-absolute targets are excluded; query strings do not affect
+ * resolution against the source file. The checker never rewrites, and
+ * symlinked instruction files are deduped.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -28,21 +30,22 @@ const PATTERNS = [
   'skills/**/*.md',
 ]
 
-/** A broken relative link: a target path that does not resolve to a file. */
+/** A broken relative link: a missing target path or a missing anchor on it. */
 interface Violation {
   file: string
   /** 1-based line where the link/image/definition node starts. */
   line: number
   url: string
+  /** What failed: the target file or the fragment onto it. */
+  reason: 'target' | 'anchor'
 }
 
 /**
  * True for targets this gate must NOT check: scheme-qualified URLs (`https:`,
- * `mailto:`, …), protocol-relative (`//host`), root-absolute (`/path`), and
- * pure in-page anchors (`#frag`). Everything else is a relative path we own.
+ * `mailto:`, …), protocol-relative (`//host`), and root-absolute (`/path`).
+ * Pure in-page anchors (`#frag`) ARE checked, against the source file itself.
  */
-function isExternalOrAnchor(url: string): boolean {
-  if (url.startsWith('#')) return true
+function isExternal(url: string): boolean {
   if (url.startsWith('//')) return true
   if (url.startsWith('/')) return true
   // A scheme like `https:` / `mailto:` — a colon before any slash, dot, or hash.
@@ -69,22 +72,105 @@ function pathPart(url: string): string {
   }
 }
 
-/** Find every broken relative cross-link in one Markdown file via its AST. */
-function findViolations(absPath: string): Violation[] {
-  const file = relative(root, absPath)
+/** The percent-decoded `#fragment` of a link target, or null when it has none. */
+function fragmentPart(url: string): string | null {
+  const hash = url.indexOf('#')
+  if (hash === -1) return null
+  const raw = url.slice(hash + 1).replace(/\?.*$/, '')
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    // Same stance as pathPart: a malformed escape names no anchor anyone
+    // meant, so the raw text flows into the lookup and is reported missing.
+    return raw
+  }
+}
+
+/**
+ * GitHub's heading-slug algorithm (lowercase; drop everything but letters,
+ * numbers, spaces, hyphens; spaces become hyphens) — the same rule
+ * `gen-cordis-catalog`'s region anchors are built from, kept in sync by the
+ * corpus passing this gate rather than by a shared import across the
+ * script/package boundary.
+ * @param heading - the rendered heading text.
+ * @returns the anchor GitHub assigns the first occurrence of the heading.
+ */
+export function githubSlug(heading: string): string {
+  return heading.toLowerCase().replace(/[^\p{L}\p{N} -]/gu, '').replaceAll(' ', '-')
+}
+
+/**
+ * Every anchor one Markdown document exposes: each heading's GitHub slug
+ * (repeated headings get the renderer's `-1`, `-2`, … suffixes) plus every
+ * explicit `<a id="…">`. Lowercased for case-insensitive fragment matching.
+ * @param source - the document's full Markdown text.
+ * @returns the set of valid fragments for links into this document.
+ */
+export function documentAnchors(source: string): Set<string> {
+  const anchors = new Set<string>()
+  const seen = new Map<string, number>()
+  const tree = parseMarkdown(source)
+  visitMarkdown(tree, (node: Nodes): void => {
+    if (node.type === 'heading') {
+      const text = source.slice(node.position?.start.offset ?? 0, node.position?.end.offset ?? 0)
+        .replace(/^#{1,6}\s+/, '')
+        .replace(/[`*_]/g, '')
+      const base = githubSlug(text)
+      const bump = seen.get(base) ?? 0
+      seen.set(base, bump + 1)
+      anchors.add(bump === 0 ? base : `${base}-${bump}`)
+    }
+  })
+  for (const match of source.matchAll(/<a id="([^"]+)"/g)) anchors.add((match[1] ?? '').toLowerCase())
+  return anchors
+}
+
+/** Lazily collect and cache the anchor set of any existing Markdown file. */
+function anchorCache(): (absPath: string) => Set<string> {
+  const cache = new Map<string, Set<string>>()
+  return (absPath) => {
+    const hit = cache.get(absPath)
+    if (hit) return hit
+    const anchors = documentAnchors(readFileSync(absPath, 'utf8'))
+    cache.set(absPath, anchors)
+    return anchors
+  }
+}
+
+/**
+ * Find every broken relative cross-link in one Markdown file via its AST: a
+ * relative target that does not exist, or a fragment onto a Markdown file
+ * (same-file `#anchor` links included) that names no heading slug or explicit
+ * `<a id>` there. Fragments onto non-Markdown targets (`file.ts#L10`) carry
+ * renderer-owned semantics and are not judged.
+ * @param absPath - absolute path of the Markdown source to scan.
+ * @param anchorsOf - anchor lookup shared across files for cross-link checks.
+ * @param scanRoot - repository root violations are reported relative to.
+ * @returns one entry per broken link, in document order.
+ */
+export function findViolations(
+  absPath: string,
+  anchorsOf: (abs: string) => Set<string>,
+  scanRoot: string = root,
+): Violation[] {
+  const file = relative(scanRoot, absPath)
   const dir = dirname(absPath)
   const source = readFileSync(absPath, 'utf8')
   const tree = parseMarkdown(source)
   const out: Violation[] = []
 
   const check = (url: string, node: Nodes): void => {
-    if (isExternalOrAnchor(url)) return
+    if (isExternal(url)) return
     const target = pathPart(url)
-    // A bare `#anchor` reduced to empty path is a same-file anchor — skip.
-    if (target === '') return
-    const resolved = resolve(dir, target)
+    const resolved = target === '' ? absPath : resolve(dir, target)
     if (!existsSync(resolved)) {
-      out.push({ file, line: node.position?.start.line ?? 0, url })
+      out.push({ file, line: node.position?.start.line ?? 0, url, reason: 'target' })
+      return
+    }
+    const fragment = fragmentPart(url)
+    if (fragment === null || !resolved.endsWith('.md')) return
+    if (!anchorsOf(resolved).has(fragment.toLowerCase())) {
+      out.push({ file, line: node.position?.start.line ?? 0, url, reason: 'anchor' })
     }
   }
 
@@ -96,18 +182,22 @@ function findViolations(absPath: string): Violation[] {
   return out
 }
 
-// Archived notes remain valid link targets, but their historical outbound links are frozen.
-const files = uniqueRepoFiles(root, PATTERNS, isArchivedAgentNotePath)
-const all = files.flatMap(file => findViolations(file.abs))
-const checked = files.length
+// Run only when invoked as a script, not when imported by the spec.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  // Archived notes remain valid link targets, but their historical outbound links are frozen.
+  const files = uniqueRepoFiles(root, PATTERNS, isArchivedAgentNotePath)
+  const anchorsOf = anchorCache()
+  const all = files.flatMap(file => findViolations(file.abs, anchorsOf))
+  const checked = files.length
 
-if (all.length === 0) {
-  console.log(`verify-md-links: ${checked} file(s) checked, all relative cross-links resolve.`)
-  process.exit(0)
-}
+  if (all.length === 0) {
+    console.log(`verify-md-links: ${checked} file(s) checked, all relative cross-links and fragments resolve.`)
+    process.exit(0)
+  }
 
-console.error('verify-md-links: broken relative cross-links found (target does not exist):')
-for (const v of all) {
-  console.error(`  ${v.file}:${v.line}  ${v.url}`)
+  console.error('verify-md-links: broken relative cross-links found:')
+  for (const v of all) {
+    console.error(`  ${v.file}:${v.line}  ${v.url}  (${v.reason === 'target' ? 'target does not exist' : 'no such anchor in target'})`)
+  }
+  process.exit(1)
 }
-process.exit(1)

From dad596348419e15a3f93943d0ea89410b6fe9e03 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 10:39:11 +0800
Subject: [PATCH 175/262] =?UTF-8?q?fix(doc-gates):=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20GitHub-slugger=20parity=20and=20the=20surviving=20o?=
 =?UTF-8?q?ld-rule=20prose?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot round: slugs now come from RENDERED heading text (links,
inline code, emphasis) with underscores kept and GitHub's occupied-set
repeat suffixes; explicit <a id> anchors register only from real HTML flow
(fences, inline code, and comments no longer produce phantoms); fragment
matching is exact-case since element ids are. anchorCache is exported and
the spec reuses it. The contradicting 'gate checks file existence, not
#anchor validity' sentence in docs/AGENTS.md is gone; the dsh-doc-standards
residual caveat names the real TS-string anchor homes; the 2026-06-18
cross-link note is updated to shipped behavior and cross-linked with the
fragment-gate note.
---
 ...6-06-18-markdown-cross-link-lint.i18n.yaml |  4 +-
 .../2026-06-18-markdown-cross-link-lint.md    |  4 +-
 .../2026-06-18-markdown-cross-link-lint.zh.md |  4 +-
 ...26-08-09-md-fragment-anchor-gate.i18n.yaml |  4 +-
 .../2026-08-09-md-fragment-anchor-gate.md     | 12 ++--
 .../2026-08-09-md-fragment-anchor-gate.zh.md  | 12 ++--
 .agents/skills/dsh-doc-standards/SKILL.md     |  2 +-
 docs/AGENTS.md                                |  2 -
 scripts/verify-md-links.spec.ts               | 49 ++++++++++----
 scripts/verify-md-links.ts                    | 64 +++++++++++--------
 10 files changed, 97 insertions(+), 60 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
index bc6582cb20..e5112c08e1 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.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 .agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
-2026-06-18-markdown-cross-link-lint.md: b8b1337e9d758da6a4cc0bb46a6b37906357f877
-2026-06-18-markdown-cross-link-lint.zh.md: 9b627ebb17a0567424ca0caaeac8edd9b36917f2
+2026-06-18-markdown-cross-link-lint.md: 21c6884d3fd891794a11125a9aa51ac2bcb29059
+2026-06-18-markdown-cross-link-lint.zh.md: 444cf6eb97d95049d4e6b7bb5f44138051f6577a
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
index b8b1337e9d..21c6884d3f 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
@@ -20,11 +20,11 @@ A fourth `doc-sync` gate, `verify-md-links` (`scripts/verify-md-links.ts`), mirr
 
 Scope matches the other gates plus the AGENTS.md pair and the repo-authored agent-skill Markdown under `.agents/skills/` (those skill files cross-link into the docs tree, so this reorg rewrote links in them too): `README.md`, `docs/**/*.md`, `packages/*/README.md`, `AGENTS.md`, `packages/AGENTS.md`, `.agents/skills/**/*.md`, deduped by real path (the `CLAUDE.md` symlinks resolve onto the AGENTS.md files). It is wired into `doc-sync`, so relevant documentation changes and CI exercise the same broken-link check.
 
-This gate checks *existence*, not anchor validity: a link to a real file with a `#wrong-heading` fragment still passes (the file resolves; the fragment is stripped).
+The gate now also checks `#fragment` anchors on Markdown targets — same-file anchors included — against heading slugs and explicit `<a id>`; the [fragment-anchor decision](2026-08-09-md-fragment-anchor-gate.md) owns that mechanism and the slug rules.
 
 ## Alternatives considered
 
-**Anchor-level validity checking** — heavier and lower-value; file-level dead links are the failure that actually bit. The scope cut is deliberate: authors verify `#fragment` anchors themselves when linking to one.
+**Anchor-level validity checking** — deferred here as heavier and lower-value (file-level dead links were the failure that had actually bit), leaving authors to verify `#fragment` anchors themselves. That manual rule did not hold; the [fragment-anchor decision](2026-08-09-md-fragment-anchor-gate.md) later added the check.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
index 9b627ebb17..444cf6eb97 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
@@ -20,11 +20,11 @@ Status: implemented
 
 检查范围与其他门禁一致，并额外包含 AGENTS.md 文件对以及 `.agents/skills/` 下仓库自有的 agent skill（技能）Markdown（这些 skill 文件会交叉链接到 docs 目录树，因此本次重组也改写了其中的链接）：`README.md`、`docs/**/*.md`、`packages/*/README.md`、`AGENTS.md`、`packages/AGENTS.md`、`.agents/skills/**/*.md`。系统按真实路径去重（`CLAUDE.md` symlink 会解析到 AGENTS.md 文件）。该检查接入 `doc-sync`，因此相关文档变更与 CI 执行同一套断链检查。
 
-本门禁检查的是*文件存在性*，而非锚点有效性：指向一个真实文件但带有 `#wrong-heading` 片段的链接仍会通过（文件路径可解析；片段被剥除）。
+本门禁现在也检查 Markdown 目标上的 `#fragment` 锚点——包括同文件锚点——对照标题 slug 与显式 `<a id>`；该机制与 slug 规则归 [fragment 锚点决定](2026-08-09-md-fragment-anchor-gate.md)所有。
 
 ## 曾考虑的替代方案
 
-**锚点级有效性检查**：更重且价值更低；实际造成问题的是文件级死链。这一范围裁剪是有意为之：作者在链接到某个锚点时自行验证 `#fragment`。
+**锚点级有效性检查**：当时以更重且价值更低为由推迟（实际咬过人的是文件级死链），把 `#fragment` 验证留给作者人工完成。该人工规则没有守住；[fragment 锚点决定](2026-08-09-md-fragment-anchor-gate.md)后来补上了这项检查。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
index 734da74005..842fd1f468 100644
--- a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.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 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
-2026-08-09-md-fragment-anchor-gate.md: 190ecb0ed07152761377961ca6221c25908082b0
-2026-08-09-md-fragment-anchor-gate.zh.md: ab08609d8b1410ccf0f36a6ced68729ac20c7658
+2026-08-09-md-fragment-anchor-gate.md: e02a917bedd9649a2326e3fb1f53072ac05c88a8
+2026-08-09-md-fragment-anchor-gate.zh.md: dcc0644ae064c161ef5232654993f0e6c872064c
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
index 190ecb0ed0..e02a917bed 100644
--- a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
@@ -10,23 +10,23 @@ English | [中文](2026-08-09-md-fragment-anchor-gate.zh.md)
 
 ## Decision
 
-`verify-md-links` now resolves fragments too. For every relative link whose target is a Markdown file — same-file `#anchor` links included, which the old checker skipped entirely — the fragment must name a real anchor in the target: a heading's GitHub slug (repeated headings get the renderer's `-1`, `-2`, … suffixes) or an explicit `<a id>`. Fragments onto non-Markdown targets (`file.ts#L10`) carry renderer-owned semantics and stay out of scope, as do external and root-absolute URLs. Anchor sets are collected lazily for any existing target, so links INTO archived notes and vendor documents are validated without making those files sources.
+`verify-md-links` now resolves fragments too (superseding the deferred scope cut in the [cross-link decision](2026-06-18-markdown-cross-link-lint.md)). For every relative link whose target is a Markdown file — same-file `#anchor` links included, which the old checker skipped entirely — the fragment must name a real anchor in the target: a heading's GitHub slug or an explicit `<a id>` in real HTML flow (code samples and commented-out anchors register nothing). Slugs are computed from the RENDERED heading text via the repository's own `markdownHeadingLines`, so links, inline code, and emphasis inside a heading slug as GitHub renders them; underscores survive (`#showcase-web_fetch`); repeated slugs get GitHub's occupied-set `-1`, `-2`, … suffixes; matching is exact-case, since element ids are case-sensitive. Fragments onto non-Markdown targets (`file.ts#L10`) carry renderer-owned semantics and stay out of scope, as do external and root-absolute URLs. Anchor sets are collected lazily for any existing target (`anchorCache`), so links INTO archived notes and vendor documents are validated without making those files sources.
 
-The slug function is GitHub's algorithm, duplicated from `gen-cordis-catalog`'s region-anchor renderer rather than shared across the script/package boundary; the corpus passing this gate is what keeps the two in sync. Chinese pair sides follow the existing repository convention (`docs/glossary.zh.md`, `docs/cordis-primer.zh.md`): keep the English fragment in the link and place an explicit `<a id>` before the Chinese heading, so both language sides expose identical anchors.
+The slug function differs from `gen-cordis-catalog`'s region-anchor slugger (which drops underscores): the generator's headings are always reachable through its explicit `<a id>` anchors, so the two need not share one rule. Chinese pair sides follow the existing repository convention (`docs/glossary.zh.md`, `docs/cordis-primer.zh.md`): keep the English fragment in the link and place an explicit `<a id>` before the Chinese heading, so both language sides expose identical anchors.
 
-The 15 broken fragments are fixed in the same change: stale slugs retargeted to the current headings, the relocated no-timeout contract now linked at its owning group README, and four zh documents given explicit anchors. `docs/AGENTS.md` and the `dsh-doc-standards` skill no longer prescribe the manual anchor grep for Markdown links; anchors cited from TypeScript strings still need one.
+The 15 broken fragments are fixed in the same change: stale slugs retargeted to the current headings, the relocated no-timeout contract now linked at its owning group README, and four zh documents given explicit anchors. `docs/AGENTS.md` and the `dsh-doc-standards` skill no longer prescribe the manual anchor grep for Markdown links; it survives only for anchors cited from TypeScript strings whose output never reaches gate-scanned Markdown (today's three all render into scanned pages, so the gate covers them through the committed output).
 
 ## Verification
 
-`scripts/verify-md-links.spec.ts` proves the acceptance paths: slugging (backticks, punctuation, repeat suffixes, explicit `<a id>`), a resolving mixed-link document, a dead same-file fragment, a dead cross-file fragment, and a missing target still reported as `target` rather than `anchor`. The gate runs over the full corpus in doc-sync (`verify-md-links`, 1613 files) and passes only after the 15 fixes — the corpus itself is the red-to-green evidence for each decay mode.
+`scripts/verify-md-links.spec.ts` proves the acceptance paths: rendered-text slugging (backticks, punctuation, a linked heading, kept underscores), occupied-set repeat suffixes, `<a id>` ignored inside fences/inline code/comments, a resolving mixed-link document, dead same-file and cross-file fragments, a case-variant fragment, and a missing target still reported as `target` rather than `anchor`. The gate runs over the full corpus in doc-sync (`verify-md-links`) and passes only after the 15 fixes — the corpus itself is the red-to-green evidence for each decay mode.
 
 ## Alternatives considered
 
 - **Keep the manual-grep rule.** It demonstrably did not hold: the 15 fragments decayed under a gate-driven maintenance culture, because heading rewrites happen in PRs that never look at inbound links. A mechanical invariant belongs in an executed gate.
 - **Point zh links at Chinese-slug anchors.** GitHub slugs CJK headings fine, but the corpus convention is already explicit `<a id>` + English fragments (glossary, primer), which also survives renderers that strip non-ASCII; adopting a second convention would split the corpus.
-- **Share `githubSlug` with the typert generator.** A one-function import would couple a doc gate to a package build; the algorithm is three lines and the corpus gate itself detects divergence (a generator anchor the gate cannot resolve fails the build the moment a page links it).
+- **Share `githubSlug` with the typert generator.** A one-function import would couple a doc gate to a package build, and the two rules genuinely differ (the generator strips underscores; its anchors are explicit `<a id>`s the gate reads directly), so divergence is by design, not drift.
 - **Validate VitePress slugs as well.** The published site's dead-link check already runs in `website:build`; generated regions carry explicit anchors precisely so the two renderers agree, and hand headings that diverge would fail there.
 
 ## Consequences
 
-Renaming a heading now breaks the build wherever a Markdown link cites its anchor, instead of stranding readers; authors fix the inbound links in the same change, exactly as they already must for file renames. Same-file anchors are no longer a blind spot, so zh pages must anchor any English fragment they use. The manual pre-rename grep survives only for anchors cited from TypeScript string literals.
+Renaming a heading now breaks the build wherever a Markdown link cites its anchor, instead of stranding readers; authors fix the inbound links in the same change, exactly as they already must for file renames. Same-file anchors are no longer a blind spot, so zh pages must anchor any English fragment they use. The manual pre-rename grep survives only for anchors cited from TypeScript strings whose output never reaches gate-scanned Markdown.
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
index ab08609d8b..dcc0644ae0 100644
--- a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
@@ -10,23 +10,23 @@ Status: implemented
 
 ## Decision
 
-`verify-md-links` 现在也解析 fragment。对每条目标为 Markdown 文件的相对链接——包括旧检查器完全跳过的同文件 `#anchor` 链接——fragment 必须命名目标中的真实锚点：标题的 GitHub slug（重复标题获得渲染器的 `-1`、`-2`……后缀）或显式 `<a id>`。指向非 Markdown 目标的 fragment（`file.ts#L10`）语义归渲染器所有，不在范围内；外部与根绝对 URL 同样不检查。锚点集合对任意存在的目标惰性收集，因此链入归档 note 与 vendor 文档的链接照常校验，而这些文件不会因此成为扫描源。
+`verify-md-links` 现在也解析 fragment（取代[跨链接决定](2026-06-18-markdown-cross-link-lint.md)中被推迟的范围裁剪）。对每条目标为 Markdown 文件的相对链接——包括旧检查器完全跳过的同文件 `#anchor` 链接——fragment 必须命名目标中的真实锚点：标题的 GitHub slug，或真实 HTML 流中的显式 `<a id>`（代码示例与注释掉的锚点不注册任何东西）。slug 由仓库自有的 `markdownHeadingLines` 从**渲染后**的标题文本计算，因此标题内的链接、行内代码与强调都按 GitHub 的渲染结果 slug；下划线保留（`#showcase-web_fetch`）；重复 slug 获得 GitHub 的占用集 `-1`、`-2`……后缀；匹配区分大小写，因为元素 id 本就区分大小写。指向非 Markdown 目标的 fragment（`file.ts#L10`）语义归渲染器所有，不在范围内；外部与根绝对 URL 同样不检查。锚点集合对任意存在的目标惰性收集（`anchorCache`），因此链入归档 note 与 vendor 文档的链接照常校验，而这些文件不会因此成为扫描源。
 
-slug 函数是 GitHub 的算法，从 `gen-cordis-catalog` 的区块锚点渲染器复制而来，而非跨脚本/包边界共享；语料通过本 gate 即是两者保持同步的机制。中文侧沿用既有语料惯例（`docs/glossary.zh.md`、`docs/cordis-primer.zh.md`）：链接保留英文 fragment，在中文标题前放置显式 `<a id>`，使两个语言侧暴露相同的锚点。
+slug 函数与 `gen-cordis-catalog` 的区块锚点 slugger 不同（后者丢弃下划线）：生成器的标题总能通过其显式 `<a id>` 锚点到达，两者无需共享一条规则。中文侧沿用既有语料惯例（`docs/glossary.zh.md`、`docs/cordis-primer.zh.md`）：链接保留英文 fragment，在中文标题前放置显式 `<a id>`，使两个语言侧暴露相同的锚点。
 
-15 条坏 fragment 在同一变更中修复：陈旧 slug 重定向到当前标题，搬迁的无超时契约改链其属主 group README，四份中文文档补上显式锚点。`docs/AGENTS.md` 与 `dsh-doc-standards` skill 不再为 Markdown 链接开人工 grep 锚点的处方；从 TypeScript 字符串引用的锚点仍需人工 grep。
+15 条坏 fragment 在同一变更中修复：陈旧 slug 重定向到当前标题，搬迁的无超时契约改链其属主 group README，四份中文文档补上显式锚点。`docs/AGENTS.md` 与 `dsh-doc-standards` skill 不再为 Markdown 链接开人工 grep 锚点的处方；人工 grep 只对输出从不进入受检 Markdown 的 TypeScript 字符串锚点保留（当下三处全部渲染进受检页面，gate 经由提交的产物覆盖它们）。
 
 ## Verification
 
-`scripts/verify-md-links.spec.ts` 证明各验收路径：slug 化（反引号、标点、重复后缀、显式 `<a id>`）、全部可解析的混合链接文档、死的同文件 fragment、死的跨文件 fragment、以及缺失目标仍报 `target` 而非 `anchor`。gate 在 doc-sync 中跑完整语料（`verify-md-links`，1613 个文件），且只有在 15 条修复之后才通过——语料本身就是每种衰变模式由红转绿的证据。
+`scripts/verify-md-links.spec.ts` 证明各验收路径：渲染文本 slug 化（反引号、标点、含链接标题、保留下划线）、占用集重复后缀、围栏/行内代码/注释中的 `<a id>` 不注册、全部可解析的混合链接文档、死的同文件与跨文件 fragment、大小写变体 fragment、以及缺失目标仍报 `target` 而非 `anchor`。gate 在 doc-sync 中跑完整语料（`verify-md-links`），且只有在 15 条修复之后才通过——语料本身就是每种衰变模式由红转绿的证据。
 
 ## Alternatives considered
 
 - **保留人工 grep 规则。** 它被证明守不住：15 条 fragment 在 gate 驱动的维护文化下仍然衰变，因为改写标题的 PR 从不会去看入链。可机械检查的不变式应进入被执行的 gate。
 - **让中文链接指向中文 slug 锚点。** GitHub 对 CJK 标题的 slug 没问题，但语料惯例已是显式 `<a id>` + 英文 fragment（glossary、primer），且它在剥离非 ASCII 的渲染器下也存活；引入第二种惯例会割裂语料。
-- **与 typert 生成器共享 `githubSlug`。** 为一个函数引入包构建耦合不值得；算法只有三行，语料 gate 本身能探测分歧（生成器产出而 gate 无法解析的锚点，在任何页面链接它的那一刻即失败）。
+- **与 typert 生成器共享 `githubSlug`。** 为一个函数引入包构建耦合不值得，且两条规则确实不同（生成器剥离下划线；其锚点是 gate 直接读取的显式 `<a id>`），分歧是设计使然而非漂移。
 - **同时校验 VitePress slug。** 发布站点的死链检查已在 `website:build` 中运行；生成区块正是为两种渲染器一致而携带显式锚点，手写标题若有分歧会在那里失败。
 
 ## Consequences
 
-重命名标题现在会在任何 Markdown 链接引用其锚点处使构建失败，而非把读者丢在页顶；作者须在同一变更中修复入链，与文件重命名的既有义务完全一致。同文件锚点不再是盲区，中文页面使用英文 fragment 时必须补锚点。人工的重命名前 grep 只对 TypeScript 字符串字面量中的锚点保留。
+重命名标题现在会在任何 Markdown 链接引用其锚点处使构建失败，而非把读者丢在页顶；作者须在同一变更中修复入链，与文件重命名的既有义务完全一致。同文件锚点不再是盲区，中文页面使用英文 fragment 时必须补锚点。人工的重命名前 grep 只对输出从不进入受检 Markdown 的 TypeScript 字符串锚点保留。
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 49ab835752..2df8d3774f 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -29,7 +29,7 @@ Then check constraints that make placement expensive or wrong:
 
 - Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
-- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings (one lives in `scripts/gen-cordis-catalog.ts`) still need a manual grep.
+- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown (today's three — `scripts/gen-doc-graphs.ts`, `scripts/gen-persistence-catalog.ts`, `packages/typert/generator/src/cordis-catalog.ts` — all render into scanned pages, so the gate catches them via the committed output).
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
 
 ## Audit the corpus
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 8d019fce08..672f6ba6f6 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -73,5 +73,3 @@ Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standar
 ## Cross-reference with machine-checkable links, never free prose
 
 Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).
-
-The gate checks file existence, not `#anchor` validity — verify anchors yourself when linking to one.
diff --git a/scripts/verify-md-links.spec.ts b/scripts/verify-md-links.spec.ts
index 4578583472..5be9231a3e 100644
--- a/scripts/verify-md-links.spec.ts
+++ b/scripts/verify-md-links.spec.ts
@@ -5,11 +5,11 @@
  * external targets stay out of scope.
  */
 
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { documentAnchors, findViolations, githubSlug } from './verify-md-links.ts'
+import { anchorCache, documentAnchors, findViolations, githubSlug } from './verify-md-links.ts'
 
 const roots: string[] = []
 afterEach(() => {
@@ -27,19 +27,11 @@ function layout(files: Record<string, string>): string {
 }
 
 function violationsIn(root: string, rel: string): { url: string; reason: string }[] {
-  const cache = new Map<string, Set<string>>()
-  const anchorsOf = (abs: string): Set<string> => {
-    const hit = cache.get(abs)
-    if (hit) return hit
-    const anchors = documentAnchors(readFileSync(abs, 'utf8'))
-    cache.set(abs, anchors)
-    return anchors
-  }
-  return findViolations(join(root, rel), anchorsOf, root).map(({ url, reason }) => ({ url, reason }))
+  return findViolations(join(root, rel), anchorCache(), root).map(({ url, reason }) => ({ url, reason }))
 }
 
 describe('documentAnchors', () => {
-  it('slugs headings, suffixes repeats, and reads explicit <a id> anchors', () => {
+  it('slugs rendered heading text, suffixes repeats, and reads explicit <a id> anchors', () => {
     const anchors = documentAnchors([
       '# My Doc',
       '## Live `events` — mode!',
@@ -51,6 +43,34 @@ describe('documentAnchors', () => {
     expect(anchors).toEqual(new Set(['my-doc', 'live-events--mode', 'repeat', 'repeat-1', 'hand-anchor']))
     expect(githubSlug('Security and authority are non-goals')).toBe('security-and-authority-are-non-goals')
   })
+
+  it('keeps underscores the way GitHub does', () => {
+    expect(githubSlug('Showcase: web_fetch')).toBe('showcase-web_fetch')
+    expect(documentAnchors('## Showcase: web_fetch\n')).toEqual(new Set(['showcase-web_fetch']))
+  })
+
+  it('slugs a heading containing a link from its rendered text', () => {
+    expect(documentAnchors('## [Install](setup.md)\n')).toEqual(new Set(['install']))
+  })
+
+  it('bumps repeat suffixes past occupied slugs, matching GitHub', () => {
+    const anchors = documentAnchors(['## Repeat', '## Repeat-1', '## Repeat', ''].join('\n'))
+    expect(anchors).toEqual(new Set(['repeat', 'repeat-1', 'repeat-2']))
+  })
+
+  it('ignores <a id> inside code fences, inline code, and HTML comments', () => {
+    const anchors = documentAnchors([
+      '# Doc',
+      '```md',
+      '<a id="fenced"></a>',
+      '```',
+      'Inline `<a id="inline"></a>` sample.',
+      '<!-- <a id="commented"></a> -->',
+      '<a id="real"></a>',
+      '',
+    ].join('\n'))
+    expect(anchors).toEqual(new Set(['doc', 'real']))
+  })
 })
 
 describe('findViolations fragments', () => {
@@ -68,6 +88,11 @@ describe('findViolations fragments', () => {
     expect(violationsIn(root, 'a.md')).toEqual([{ url: '#deferred-work', reason: 'anchor' }])
   })
 
+  it('rejects a case-variant fragment: element ids are case-sensitive', () => {
+    const root = layout({ 'a.md': '# A\n\n## Default Loop\n\n[case](#Default-Loop)\n' })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: '#Default-Loop', reason: 'anchor' }])
+  })
+
   it('rejects a cross-file fragment missing from the target document', () => {
     const root = layout({
       'a.md': '# A\n\n[stale](b.md#old-heading)\n',
diff --git a/scripts/verify-md-links.ts b/scripts/verify-md-links.ts
index 0286f6d516..8d4b99fe5d 100644
--- a/scripts/verify-md-links.ts
+++ b/scripts/verify-md-links.ts
@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import type { Nodes } from 'mdast'
-import { parseMarkdown, visitMarkdown } from './markdown.ts'
+import { markdownHeadingLines, parseMarkdown, visitMarkdown } from './markdown.ts'
 import { isArchivedAgentNotePath, uniqueRepoFiles } from './repo-files.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -88,45 +88,59 @@ function fragmentPart(url: string): string | null {
 
 /**
  * GitHub's heading-slug algorithm (lowercase; drop everything but letters,
- * numbers, spaces, hyphens; spaces become hyphens) — the same rule
- * `gen-cordis-catalog`'s region anchors are built from, kept in sync by the
- * corpus passing this gate rather than by a shared import across the
- * script/package boundary.
- * @param heading - the rendered heading text.
+ * numbers, underscores, spaces, hyphens; spaces become hyphens). Underscores
+ * survive (`## Showcase: web_fetch` → `#showcase-web_fetch`), unlike
+ * `gen-cordis-catalog`'s region-anchor slugs — the generator's headings are
+ * always reachable through its explicit `<a id>` anchors, so the two need not
+ * share one rule.
+ * @param heading - the RENDERED heading text (Markdown syntax already gone).
  * @returns the anchor GitHub assigns the first occurrence of the heading.
  */
 export function githubSlug(heading: string): string {
-  return heading.toLowerCase().replace(/[^\p{L}\p{N} -]/gu, '').replaceAll(' ', '-')
+  return heading.toLowerCase().replace(/[^\p{L}\p{N}_ -]/gu, '').replaceAll(' ', '-')
 }
 
 /**
- * Every anchor one Markdown document exposes: each heading's GitHub slug
- * (repeated headings get the renderer's `-1`, `-2`, … suffixes) plus every
- * explicit `<a id="…">`. Lowercased for case-insensitive fragment matching.
+ * Every anchor one Markdown document exposes: each heading's GitHub slug —
+ * computed from the RENDERED heading text, so links, images, inline code, and
+ * emphasis inside a heading slug the way GitHub renders them — plus every
+ * explicit `<a id="…">` that appears in real HTML flow (a fenced or inline
+ * code sample and a commented-out anchor register nothing). Repeated slugs
+ * get GitHub's occupied-set `-1`, `-2`, … suffixes: each collision bumps the
+ * ORIGINAL slug's counter until a free name is found, so `Repeat`, `Repeat-1`,
+ * `Repeat` yields `repeat`, `repeat-1`, `repeat-2`. Matching is exact —
+ * element ids are case-sensitive.
  * @param source - the document's full Markdown text.
  * @returns the set of valid fragments for links into this document.
  */
 export function documentAnchors(source: string): Set<string> {
   const anchors = new Set<string>()
-  const seen = new Map<string, number>()
-  const tree = parseMarkdown(source)
-  visitMarkdown(tree, (node: Nodes): void => {
-    if (node.type === 'heading') {
-      const text = source.slice(node.position?.start.offset ?? 0, node.position?.end.offset ?? 0)
-        .replace(/^#{1,6}\s+/, '')
-        .replace(/[`*_]/g, '')
-      const base = githubSlug(text)
-      const bump = seen.get(base) ?? 0
-      seen.set(base, bump + 1)
-      anchors.add(bump === 0 ? base : `${base}-${bump}`)
+  const occurrences = new Map<string, number>()
+  for (const heading of markdownHeadingLines(source)) {
+    const base = githubSlug(heading.text)
+    let result = base
+    let bump = occurrences.get(base) ?? 0
+    while (anchors.has(result)) {
+      bump += 1
+      result = `${base}-${bump}`
     }
+    occurrences.set(base, bump)
+    anchors.add(result)
+  }
+  visitMarkdown(parseMarkdown(source), (node: Nodes): void => {
+    if (node.type !== 'html') return
+    const html = node.value.replace(/<!--[\s\S]*?-->/g, '')
+    for (const match of html.matchAll(/<a id="([^"]+)"/g)) anchors.add(match[1] ?? '')
   })
-  for (const match of source.matchAll(/<a id="([^"]+)"/g)) anchors.add((match[1] ?? '').toLowerCase())
   return anchors
 }
 
-/** Lazily collect and cache the anchor set of any existing Markdown file. */
-function anchorCache(): (absPath: string) => Set<string> {
+/**
+ * Lazily collect and cache the anchor set of any existing Markdown file —
+ * shared across all scanned sources so a target parses once.
+ * @returns the memoized absolute-path → anchor-set lookup.
+ */
+export function anchorCache(): (absPath: string) => Set<string> {
   const cache = new Map<string, Set<string>>()
   return (absPath) => {
     const hit = cache.get(absPath)
@@ -169,7 +183,7 @@ export function findViolations(
     }
     const fragment = fragmentPart(url)
     if (fragment === null || !resolved.endsWith('.md')) return
-    if (!anchorsOf(resolved).has(fragment.toLowerCase())) {
+    if (!anchorsOf(resolved).has(fragment)) {
       out.push({ file, line: node.position?.start.line ?? 0, url, reason: 'anchor' })
     }
   }

From 7ff0cbcb7e37e95a865db9f4a2f0eb6389a57953 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 11:02:16 +0800
Subject: [PATCH 176/262] docs: complete Chinese proofreading and generated
 reference pairing

---
 ...026-06-11-runtime-arg-validation.i18n.yaml |    4 +-
 .../2026-06-11-runtime-arg-validation.zh.md   |    4 +-
 .../2026-07-08-agent-scope-contexts.i18n.yaml |    2 +-
 .../2026-07-08-agent-scope-contexts.zh.md     |   20 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |    2 +-
 ...026-07-12-agent-scope-runtime-design.zh.md |   66 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |    2 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |   64 +-
 ...7-19-gui-web-client-architecture.i18n.yaml |    2 +-
 ...26-07-19-gui-web-client-architecture.zh.md |   30 +-
 ...-19-zstandard-jsonl-session-logs.i18n.yaml |    2 +-
 ...6-07-19-zstandard-jsonl-session-logs.zh.md |    8 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |    2 +-
 ...26-07-23-client-plugin-loading-model.zh.md |   18 +-
 ...ompiler-independent-typert-model.i18n.yaml |    2 +-
 ...27-compiler-independent-typert-model.zh.md |   24 +-
 ...directory-picker-capability-seam.i18n.yaml |    2 +-
 ...-28-directory-picker-capability-seam.zh.md |   46 +-
 ...-29-terminal-llm-stream-failures.i18n.yaml |    2 +-
 ...6-07-29-terminal-llm-stream-failures.zh.md |   20 +-
 ...adapter-owned-max-token-defaults.i18n.yaml |    2 +-
 ...-30-adapter-owned-max-token-defaults.zh.md |    2 +-
 ...07-30-client-locale-full-rollout.i18n.yaml |    2 +-
 ...026-07-30-client-locale-full-rollout.zh.md |   22 +-
 ...-07-30-command-row-copy-contract.i18n.yaml |    2 +-
 ...2026-07-30-command-row-copy-contract.zh.md |   20 +-
 ...-followup-enqueue-and-owned-runs.i18n.yaml |    2 +-
 ...7-30-followup-enqueue-and-owned-runs.zh.md |    4 +-
 ...-manager-native-repository-cache.i18n.yaml |    2 +-
 ...kage-manager-native-repository-cache.zh.md |    4 +-
 ...30-session-end-seed-log-boundary.i18n.yaml |    2 +-
 ...-07-30-session-end-seed-log-boundary.zh.md |   12 +-
 ...-static-repository-plugin-format.i18n.yaml |    2 +-
 ...7-30-static-repository-plugin-format.zh.md |   24 +-
 ...claimed-pre-step-inbox-lifecycle.i18n.yaml |    2 +-
 ...-31-claimed-pre-step-inbox-lifecycle.zh.md |   18 +-
 ...runtime-portable-identifier-seam.i18n.yaml |    2 +-
 ...ode-runtime-portable-identifier-seam.zh.md |   18 +-
 ...-07-31-goal-owned-durable-events.i18n.yaml |    2 +-
 ...2026-07-31-goal-owned-durable-events.zh.md |    6 +-
 ...26-08-01-packaged-ripgrep-search.i18n.yaml |    2 +-
 .../2026-08-01-packaged-ripgrep-search.zh.md  |   14 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |    2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |   36 +-
 ...-pi-ai-declared-provider-catalog.i18n.yaml |    2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |   16 +-
 ...4-configuration-source-ownership.i18n.yaml |    2 +-
 ...08-04-configuration-source-ownership.zh.md |   14 +-
 ...-yaml-and-user-environment-layer.i18n.yaml |    2 +-
 ...ials-yaml-and-user-environment-layer.zh.md |   14 +-
 ...-a-provider-from-the-models-page.i18n.yaml |    2 +-
 ...ring-a-provider-from-the-models-page.zh.md |    2 +-
 ...-provider-endpoint-interrogation.i18n.yaml |    2 +-
 ...raft-provider-endpoint-interrogation.zh.md |   10 +-
 ...08-04-websocket-downlink-carrier.i18n.yaml |    2 +-
 ...026-08-04-websocket-downlink-carrier.zh.md |   12 +-
 ...e-session-jsonl-restore-pipeline.i18n.yaml |    2 +-
 ...large-session-jsonl-restore-pipeline.zh.md |    8 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |    2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |    4 +-
 .../2026-08-05-session-preparation.i18n.yaml  |    2 +-
 .../2026-08-05-session-preparation.zh.md      |    6 +-
 ...08-05-slot-declaration-injection.i18n.yaml |    2 +-
 ...026-08-05-slot-declaration-injection.zh.md |   10 +-
 ...8-06-agent-event-payload-objects.i18n.yaml |    2 +-
 ...26-08-06-agent-event-payload-objects.zh.md |    6 +-
 ...ubagent-list-identity-projection.i18n.yaml |    2 +-
 ...06-subagent-list-identity-projection.zh.md |   20 +-
 ...arkdown-incremental-ast-renderer.i18n.yaml |    2 +-
 ...eb-markdown-incremental-ast-renderer.zh.md |   12 +-
 ...8-06-web-shell-dist-chunk-layout.i18n.yaml |    2 +-
 ...26-08-06-web-shell-dist-chunk-layout.zh.md |   22 +-
 ...ssion-persistence-write-batching.i18n.yaml |    2 +-
 ...d-session-persistence-write-batching.zh.md |   10 +-
 ...ient-tool-presentation-ownership.i18n.yaml |    2 +-
 ...8-client-tool-presentation-ownership.zh.md |   26 +-
 ...-20-config-hot-reload-resilience.i18n.yaml |    2 +-
 ...6-07-20-config-hot-reload-resilience.zh.md |    4 +-
 .../2026-07-27-glob-sampling.i18n.yaml        |    2 +-
 .../bug-fix/2026-07-27-glob-sampling.zh.md    |   16 +-
 ...d-scrollbars-and-reserved-gutter.i18n.yaml |    2 +-
 ...hemed-scrollbars-and-reserved-gutter.zh.md |    8 +-
 ...-07-28-web-agent-runtime-context.i18n.yaml |    2 +-
 ...2026-07-28-web-agent-runtime-context.zh.md |   12 +-
 ...2026-07-28-web-gui-feedback-loop.i18n.yaml |    2 +-
 .../2026-07-28-web-gui-feedback-loop.zh.md    |   10 +-
 ...9-human-transcript-append-origin.i18n.yaml |    2 +-
 ...07-29-human-transcript-append-origin.zh.md |   38 +-
 ...7-29-pnpm-setup-runner-isolation.i18n.yaml |    2 +-
 ...26-07-29-pnpm-setup-runner-isolation.zh.md |    4 +-
 ...cky-composer-conversation-scroll.i18n.yaml |    2 +-
 ...-sticky-composer-conversation-scroll.zh.md |   16 +-
 ...29-web-details-session-lifecycle.i18n.yaml |    2 +-
 ...-07-29-web-details-session-lifecycle.zh.md |    4 +-
 ...07-30-approval-panel-command-cap.i18n.yaml |    2 +-
 ...026-07-30-approval-panel-command-cap.zh.md |   18 +-
 ...-30-composer-context-stack-order.i18n.yaml |    2 +-
 ...6-07-30-composer-context-stack-order.zh.md |    8 +-
 ...-07-30-hover-popup-pointer-grace.i18n.yaml |    2 +-
 ...2026-07-30-hover-popup-pointer-grace.zh.md |    8 +-
 ...select-custom-answer-composition.i18n.yaml |    2 +-
 ...lti-select-custom-answer-composition.zh.md |    4 +-
 ...rce-checkout-workdir-distinction.i18n.yaml |    2 +-
 ...-source-checkout-workdir-distinction.zh.md |   18 +-
 ...ranscript-log-ordered-projection.i18n.yaml |    2 +-
 ...eb-transcript-log-ordered-projection.zh.md |   40 +-
 ...text-layers-share-one-scrollport.i18n.yaml |    2 +-
 ...ser-text-layers-share-one-scrollport.zh.md |   12 +-
 ...1-english-compaction-checkpoints.i18n.yaml |    2 +-
 ...07-31-english-compaction-checkpoints.zh.md |    4 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |    2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |   18 +-
 ...-fork-anchor-floors-to-event-seq.i18n.yaml |    2 +-
 ...7-31-fork-anchor-floors-to-event-seq.zh.md |    6 +-
 ...6-07-31-web-stop-preserves-queue.i18n.yaml |    2 +-
 .../2026-07-31-web-stop-preserves-queue.zh.md |    4 +-
 ...-ask-user-delegated-caller-guard.i18n.yaml |    2 +-
 ...8-01-ask-user-delegated-caller-guard.zh.md |    4 +-
 ...-08-02-goal-round-wrapup-message.i18n.yaml |    2 +-
 ...2026-08-02-goal-round-wrapup-message.zh.md |   20 +-
 ...ions-require-completed-turn-tail.i18n.yaml |    2 +-
 ...-actions-require-completed-turn-tail.zh.md |    2 +-
 ...odo-first-composer-context-order.i18n.yaml |    2 +-
 ...02-todo-first-composer-context-order.zh.md |    2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |    2 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |    6 +-
 ...3-hmr-initial-scan-boot-deadlock.i18n.yaml |    2 +-
 ...08-03-hmr-initial-scan-boot-deadlock.zh.md |   18 +-
 ...-composer-tab-gutter-reservation.i18n.yaml |    2 +-
 ...8-04-composer-tab-gutter-reservation.zh.md |   18 +-
 ...versation-column-one-axis-scroll.i18n.yaml |    2 +-
 ...-conversation-column-one-axis-scroll.zh.md |   12 +-
 ...-04-load-pre-react-loop-sessions.i18n.yaml |    2 +-
 ...6-08-04-load-pre-react-loop-sessions.zh.md |   10 +-
 ...ontext-meter-blind-to-compaction.i18n.yaml |    2 +-
 ...05-context-meter-blind-to-compaction.zh.md |   16 +-
 ...actions-require-a-completed-turn.i18n.yaml |    2 +-
 ...ail-actions-require-a-completed-turn.zh.md |    6 +-
 ...e-blank-session-reuse-membership.i18n.yaml |    2 +-
 ...space-blank-session-reuse-membership.zh.md |   16 +-
 ...-08-06-api-key-format-validation.i18n.yaml |    2 +-
 ...2026-08-06-api-key-format-validation.zh.md |   30 +-
 ...rding-step-owned-takeover-chrome.i18n.yaml |    2 +-
 ...nboarding-step-owned-takeover-chrome.zh.md |   22 +-
 ...06-provider-credential-lifecycle.i18n.yaml |    2 +-
 ...-08-06-provider-credential-lifecycle.zh.md |   10 +-
 ...-attribution-observed-top-ledger.i18n.yaml |    2 +-
 ...roll-attribution-observed-top-ledger.zh.md |    8 +-
 ...e-unpriced-replace-compatibility.i18n.yaml |    2 +-
 ...rface-unpriced-replace-compatibility.zh.md |    8 +-
 ...6-06-21-subagent-capability-seam.i18n.yaml |    2 +-
 .../2026-06-21-subagent-capability-seam.zh.md |   24 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |    2 +-
 .../feature/2026-07-05-skill-system.zh.md     |   22 +-
 ...-07-08-background-subagent-tasks.i18n.yaml |    2 +-
 ...2026-07-08-background-subagent-tasks.zh.md |   16 +-
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |    2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |   32 +-
 ...continuable-background-subagents.i18n.yaml |    2 +-
 ...-21-continuable-background-subagents.zh.md |   40 +-
 ...subagent-catalog-and-list-agents.i18n.yaml |    2 +-
 ...ble-subagent-catalog-and-list-agents.zh.md |   30 +-
 ...026-07-23-web-assistant-markdown.i18n.yaml |    2 +-
 .../2026-07-23-web-assistant-markdown.zh.md   |    8 +-
 ...7-23-web-permission-and-approval.i18n.yaml |    2 +-
 ...26-07-23-web-permission-and-approval.zh.md |   16 +-
 ...model-facing-session-query-tools.i18n.yaml |    2 +-
 ...-24-model-facing-session-query-tools.zh.md |   20 +-
 ...n-list-browsing-and-manual-order.i18n.yaml |    2 +-
 ...ssion-list-browsing-and-manual-order.zh.md |   40 +-
 ...-07-25-workspace-ui-product-flow.i18n.yaml |    2 +-
 ...2026-07-25-workspace-ui-product-flow.zh.md |   36 +-
 ...-07-26-todo-parallel-in-progress.i18n.yaml |    2 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |   14 +-
 ...ative-workspace-directory-picker.i18n.yaml |    2 +-
 ...27-native-workspace-directory-picker.zh.md |    4 +-
 ...-07-27-skill-catalog-hot-refresh.i18n.yaml |    2 +-
 ...2026-07-27-skill-catalog-hot-refresh.zh.md |   12 +-
 ...-27-trajectory-inspection-ledger.i18n.yaml |    2 +-
 ...6-07-27-trajectory-inspection-ledger.zh.md |   16 +-
 ...6-07-27-web-session-fork-actions.i18n.yaml |    2 +-
 .../2026-07-27-web-session-fork-actions.zh.md |   20 +-
 .../2026-07-27-web-session-search.i18n.yaml   |    2 +-
 .../2026-07-27-web-session-search.zh.md       |   14 +-
 ...07-27-web-subagent-conversations.i18n.yaml |    2 +-
 ...026-07-27-web-subagent-conversations.zh.md |   26 +-
 ...ntinuable-subagent-conversations.i18n.yaml |    2 +-
 ...8-continuable-subagent-conversations.zh.md |   16 +-
 ...026-07-28-cross-workspace-resume.i18n.yaml |    2 +-
 .../2026-07-28-cross-workspace-resume.zh.md   |   10 +-
 .../2026-07-28-feedback-command.i18n.yaml     |    2 +-
 .../feature/2026-07-28-feedback-command.zh.md |    6 +-
 ...26-07-28-skill-invocation-policy.i18n.yaml |    2 +-
 .../2026-07-28-skill-invocation-policy.zh.md  |   10 +-
 .../2026-07-28-web-terminal-card.i18n.yaml    |    2 +-
 .../2026-07-28-web-terminal-card.zh.md        |   14 +-
 ...0-config-only-repository-plugins.i18n.yaml |    2 +-
 ...07-30-config-only-repository-plugins.zh.md |   12 +-
 ...continuable-subagent-report-tool.i18n.yaml |    2 +-
 ...-30-continuable-subagent-report-tool.zh.md |   20 +-
 ...0-current-sandbox-policy-context.i18n.yaml |    2 +-
 ...07-30-current-sandbox-policy-context.zh.md |   10 +-
 ...seek-onboarding-credential-setup.i18n.yaml |    2 +-
 ...deepseek-onboarding-credential-setup.zh.md |    8 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |    2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |    8 +-
 .../2026-07-30-search-render-card.i18n.yaml   |    2 +-
 .../2026-07-30-search-render-card.zh.md       |   10 +-
 ...versioned-gui-welcome-onboarding.i18n.yaml |    2 +-
 ...-30-versioned-gui-welcome-onboarding.zh.md |    8 +-
 .../2026-07-30-web-diff-card.i18n.yaml        |    2 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |   24 +-
 ...026-07-30-web-queue-steer-action.i18n.yaml |    2 +-
 .../2026-07-30-web-queue-steer-action.zh.md   |   18 +-
 .../2026-07-30-web-read-card.i18n.yaml        |    2 +-
 .../feature/2026-07-30-web-read-card.zh.md    |   18 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |    2 +-
 .../2026-07-30-web-result-card-frontend.zh.md |   24 +-
 .../2026-07-30-web-result-card.i18n.yaml      |    2 +-
 .../feature/2026-07-30-web-result-card.zh.md  |   16 +-
 ...l-row-unified-expand-and-inspect.i18n.yaml |    2 +-
 ...-tool-row-unified-expand-and-inspect.zh.md |   16 +-
 ...1-browser-derived-initial-locale.i18n.yaml |    2 +-
 ...07-31-browser-derived-initial-locale.zh.md |    8 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |    2 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |   14 +-
 ...31-even-out-shipped-tool-rosters.i18n.yaml |    2 +-
 ...-07-31-even-out-shipped-tool-rosters.zh.md |   18 +-
 ...-31-gui-full-access-confirmation.i18n.yaml |    2 +-
 ...6-07-31-gui-full-access-confirmation.zh.md |   20 +-
 ...mission-default-for-new-sessions.i18n.yaml |    2 +-
 ...-permission-default-for-new-sessions.zh.md |    6 +-
 ...07-31-session-archive-global-set.i18n.yaml |    2 +-
 ...026-07-31-session-archive-global-set.zh.md |   18 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |    2 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |   14 +-
 .../2026-07-31-web-default-search.i18n.yaml   |    2 +-
 .../2026-07-31-web-default-search.zh.md       |    2 +-
 ...7-31-web-telemetry-default-mount.i18n.yaml |    2 +-
 ...26-07-31-web-telemetry-default-mount.zh.md |   24 +-
 ...6-07-31-web-workspace-file-links.i18n.yaml |    2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |   16 +-
 ...-workspace-write-surface-default.i18n.yaml |    2 +-
 ...7-31-workspace-write-surface-default.zh.md |    6 +-
 ...026-08-01-pwsh-tool-and-executor.i18n.yaml |    2 +-
 .../2026-08-01-pwsh-tool-and-executor.zh.md   |   22 +-
 ...2026-08-02-pwsh-tool-bash-parity.i18n.yaml |    2 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md    |   20 +-
 ...ssion-search-not-shipped-default.i18n.yaml |    2 +-
 ...2-session-search-not-shipped-default.zh.md |   14 +-
 ...6-08-02-web-thinking-tail-scroll.i18n.yaml |    2 +-
 .../2026-08-02-web-thinking-tail-scroll.zh.md |   16 +-
 ...2-win32-in-process-folder-dialog.i18n.yaml |    2 +-
 ...08-02-win32-in-process-folder-dialog.zh.md |   18 +-
 .../2026-08-03-fs-tool-error-remedy.i18n.yaml |    2 +-
 .../2026-08-03-fs-tool-error-remedy.zh.md     |   24 +-
 ...6-08-03-web-search-source-scroll.i18n.yaml |    2 +-
 .../2026-08-03-web-search-source-scroll.zh.md |   24 +-
 ...code-and-codex-subagent-backends.i18n.yaml |    2 +-
 ...ude-code-and-codex-subagent-backends.zh.md |    8 +-
 ...nter-revealed-sidebar-scrollbars.i18n.yaml |    2 +-
 ...-pointer-revealed-sidebar-scrollbars.zh.md |   30 +-
 ...4-web-composer-shared-width-axis.i18n.yaml |    2 +-
 ...08-04-web-composer-shared-width-axis.zh.md |   14 +-
 ...b-context-source-and-steer-marks.i18n.yaml |    2 +-
 ...4-web-context-source-and-steer-marks.zh.md |   14 +-
 ...4-web-latency-throughput-metrics.i18n.yaml |    2 +-
 ...08-04-web-latency-throughput-metrics.zh.md |    8 +-
 ...eb-slash-command-fuzzy-discovery.i18n.yaml |    2 +-
 ...04-web-slash-command-fuzzy-discovery.zh.md |   12 +-
 ...composer-context-meter-breakdown.i18n.yaml |    2 +-
 ...-05-composer-context-meter-breakdown.zh.md |   10 +-
 ...26-08-05-context-form-vocabulary.i18n.yaml |    2 +-
 .../2026-08-05-context-form-vocabulary.zh.md  |   28 +-
 ...feedback-gated-session-telemetry.i18n.yaml |    2 +-
 ...-05-feedback-gated-session-telemetry.zh.md |    2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |    2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |   10 +-
 ...-08-05-web-preview-product-badge.i18n.yaml |    2 +-
 ...2026-08-05-web-preview-product-badge.zh.md |    4 +-
 ...26-08-06-bundled-dsh-badge-skill.i18n.yaml |    2 +-
 .../2026-08-06-bundled-dsh-badge-skill.zh.md  |    2 +-
 ...06-resolved-theme-color-metadata.i18n.yaml |    2 +-
 ...-08-06-resolved-theme-color-metadata.zh.md |    4 +-
 ...08-06-session-completed-done-dot.i18n.yaml |    2 +-
 ...026-08-06-session-completed-done-dot.zh.md |   12 +-
 .../2026-08-06-web-install-manifest.i18n.yaml |    2 +-
 .../2026-08-06-web-install-manifest.zh.md     |    6 +-
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |    2 +-
 .../2026-08-06-web-skill-tool-row.zh.md       |    8 +-
 ...default-model-follows-the-picker.i18n.yaml |    2 +-
 ...-07-default-model-follows-the-picker.zh.md |   14 +-
 ...6-08-08-dsh-run-headless-command.i18n.yaml |    2 +-
 .../2026-08-08-dsh-run-headless-command.zh.md |    2 +-
 ...8-user-explicit-skill-invocation.i18n.yaml |    2 +-
 ...08-08-user-explicit-skill-invocation.zh.md |   12 +-
 ...26-06-11-vendor-cordis-as-source.i18n.yaml |    2 +-
 .../2026-06-11-vendor-cordis-as-source.zh.md  |    6 +-
 .../2026-06-17-ts-build-config.i18n.yaml      |    2 +-
 .../process/2026-06-17-ts-build-config.zh.md  |   10 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |    4 +-
 ...6-07-02-bilingual-docs-and-pairing-gate.md |    2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |    2 +-
 ...fig-solution-root-two-aggregates.i18n.yaml |    2 +-
 ...sconfig-solution-root-two-aggregates.zh.md |    6 +-
 ...-incremental-pr-base-retargeting.i18n.yaml |    2 +-
 ...7-26-incremental-pr-base-retargeting.zh.md |    2 +-
 ...30-generated-third-party-notices.i18n.yaml |    2 +-
 ...-07-30-generated-third-party-notices.zh.md |   26 +-
 ...30-independent-ci-consumer-build.i18n.yaml |    2 +-
 ...-07-30-independent-ci-consumer-build.zh.md |    2 +-
 ...-31-coverage-exempt-heavy-suites.i18n.yaml |    2 +-
 ...6-07-31-coverage-exempt-heavy-suites.zh.md |   12 +-
 ...staller-adopts-existing-checkout.i18n.yaml |    2 +-
 ...1-installer-adopts-existing-checkout.zh.md |   22 +-
 ...thub-stacks-and-optional-rebases.i18n.yaml |    2 +-
 ...e-github-stacks-and-optional-rebases.zh.md |    2 +-
 ...-04-forward-only-pr-issue-status.i18n.yaml |    2 +-
 ...6-08-04-forward-only-pr-issue-status.zh.md |    4 +-
 ...-06-coverage-uncovered-locations.i18n.yaml |    2 +-
 ...6-08-06-coverage-uncovered-locations.zh.md |   24 +-
 ...8-06-doc-site-carries-its-images.i18n.yaml |    2 +-
 ...26-08-06-doc-site-carries-its-images.zh.md |   20 +-
 ...6-in-repository-landlock-release.i18n.yaml |    2 +-
 ...08-06-in-repository-landlock-release.zh.md |    4 +-
 ...remotes-generated-contract-build.i18n.yaml |    2 +-
 ...api-remotes-generated-contract-build.zh.md |   26 +-
 ...08-08-browser-gif-evidence-chain.i18n.yaml |    2 +-
 ...026-08-08-browser-gif-evidence-chain.zh.md |   10 +-
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |    2 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |   16 +-
 ...6-merge-subagent-control-service.i18n.yaml |    2 +-
 ...07-26-merge-subagent-control-service.zh.md |   12 +-
 ...subagent-continuation-operations.i18n.yaml |    2 +-
 ...med-subagent-continuation-operations.zh.md |    2 +-
 ...-remove-synthetic-log-only-turns.i18n.yaml |    2 +-
 ...7-28-remove-synthetic-log-only-turns.zh.md |    6 +-
 ...7-29-shared-base-config-overlays.i18n.yaml |    2 +-
 ...26-07-29-shared-base-config-overlays.zh.md |   14 +-
 .../2026-07-30-private-agent-send.i18n.yaml   |    2 +-
 .../2026-07-30-private-agent-send.zh.md       |    6 +-
 ...y-neutral-sandbox-policy-context.i18n.yaml |    2 +-
 ...ility-neutral-sandbox-policy-context.zh.md |    4 +-
 ...7-31-drop-user-message-edit-stub.i18n.yaml |    2 +-
 ...26-07-31-drop-user-message-edit-stub.zh.md |    6 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |    2 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |   36 +-
 ...t-invariants-from-shipped-config.i18n.yaml |    2 +-
 ...-omit-invariants-from-shipped-config.zh.md |    2 +-
 ...ndows-powershell-picker-fallback.i18n.yaml |    2 +-
 ...p-windows-powershell-picker-fallback.zh.md |   30 +-
 .../2026-08-04-remove-tui-package.i18n.yaml   |    2 +-
 .../2026-08-04-remove-tui-package.zh.md       |    8 +-
 ...r-bubbles-drop-the-branch-action.i18n.yaml |    2 +-
 ...-user-bubbles-drop-the-branch-action.zh.md |    6 +-
 .../2026-08-08-remove-cli-demo.i18n.yaml      |    2 +-
 .../2026-08-08-remove-cli-demo.zh.md          |    6 +-
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |    2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |   40 +-
 ...itest-jsdom-webstorage-ownership.i18n.yaml |    2 +-
 ...30-vitest-jsdom-webstorage-ownership.zh.md |    4 +-
 ...-30-web-browser-snapshot-ci-gate.i18n.yaml |    2 +-
 ...6-07-30-web-browser-snapshot-ci-gate.zh.md |   12 +-
 ...n-reasoning-chunk-browser-stress.i18n.yaml |    2 +-
 ...pt-in-reasoning-chunk-browser-stress.zh.md |   12 +-
 ...7-29-durable-last-activity-index.i18n.yaml |    2 +-
 ...26-07-29-durable-last-activity-index.zh.md |   32 +-
 ...8-semantic-composer-chain-phases.i18n.yaml |    2 +-
 ...08-08-semantic-composer-chain-phases.zh.md |    8 +-
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |    2 +-
 ...026-07-17-sdk-follow-up-capabilities.zh.md |   48 +-
 .../2026-08-01-windows-pwsh-default.i18n.yaml |    2 +-
 .../2026-08-01-windows-pwsh-default.zh.md     |   18 +-
 ...t-first-npm-baseline-publication.i18n.yaml |    2 +-
 ...ifact-first-npm-baseline-publication.zh.md |   26 +-
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |    2 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |   14 +-
 README.i18n.yaml                              |    2 +-
 README.zh.md                                  |    6 +-
 apps/cli/README.i18n.yaml                     |    2 +-
 apps/cli/README.zh.md                         |    2 +-
 apps/cli/reference/README.i18n.yaml           |    2 +-
 apps/cli/reference/README.zh.md               |   12 +-
 docs/agent-lifecycle.i18n.yaml                |    6 +
 docs/agent-lifecycle.zh.md                    |   84 +
 docs/api-gateway.i18n.yaml                    |    2 +-
 docs/api-gateway.zh.md                        |   50 +-
 docs/architecture.i18n.yaml                   |    2 +-
 docs/architecture.zh.md                       |   38 +-
 docs/capability-seams.i18n.yaml               |    6 +
 docs/capability-seams.zh.md                   |  425 +++
 docs/config-catalog.i18n.yaml                 |    6 +
 docs/config-catalog.zh.md                     | 2684 +++++++++++++++++
 docs/cookbook/adding-a-package.i18n.yaml      |    2 +-
 docs/cookbook/adding-a-package.zh.md          |   20 +-
 docs/cookbook/adding-a-tool.i18n.yaml         |    2 +-
 docs/cookbook/adding-a-tool.zh.md             |   18 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |    2 +-
 docs/cookbook/extension-cookbook.zh.md        |   28 +-
 ...sponding-to-pr-review-on-a-stack.i18n.yaml |    2 +-
 .../responding-to-pr-review-on-a-stack.zh.md  |    4 +-
 docs/cordis-api/context.i18n.yaml             |    6 +
 docs/cordis-api/context.zh.md                 |  366 +++
 docs/cordis-api/events.i18n.yaml              |    6 +
 docs/cordis-api/events.zh.md                  |  209 ++
 docs/cordis-api/fiber.i18n.yaml               |    6 +
 docs/cordis-api/fiber.zh.md                   |  377 +++
 docs/cordis-api/registry.i18n.yaml            |    6 +
 docs/cordis-api/registry.zh.md                |  154 +
 docs/cordis-api/service.i18n.yaml             |    6 +
 docs/cordis-api/service.zh.md                 |  104 +
 .../cordis-tutorial/01-first-plugin.i18n.yaml |    2 +-
 docs/cordis-tutorial/01-first-plugin.zh.md    |    4 +-
 docs/development.i18n.yaml                    |    2 +-
 docs/development.zh.md                        |   28 +-
 docs/event-producer-consumer.i18n.yaml        |    6 +
 docs/event-producer-consumer.zh.md            |   83 +
 docs/graph-atlas.i18n.yaml                    |    6 +
 docs/graph-atlas.zh.md                        |   26 +
 docs/i18n/README.i18n.yaml                    |    4 +-
 docs/i18n/README.md                           |    4 +-
 docs/i18n/README.zh.md                        |   14 +-
 docs/i18n/terminology.md                      |    4 +-
 docs/i18n/translation-rules.i18n.yaml         |    2 +-
 docs/module-graph.i18n.yaml                   |    6 +
 docs/module-graph.zh.md                       | 1370 +++++++++
 docs/persistence-catalog.i18n.yaml            |    6 +
 docs/persistence-catalog.zh.md                |  775 +++++
 ...0003-web-agent-gui-feedback-loop.i18n.yaml |    2 +-
 .../0003-web-agent-gui-feedback-loop.zh.md    |   12 +-
 ...ice-misclassified-child-failures.i18n.yaml |    2 +-
 ...-notice-misclassified-child-failures.zh.md |    6 +-
 docs/subsystems/core.i18n.yaml                |    2 +-
 docs/subsystems/core.zh.md                    |   12 +-
 docs/subsystems/credentials.i18n.yaml         |    2 +-
 docs/subsystems/credentials.zh.md             |   10 +-
 docs/subsystems/lsp.i18n.yaml                 |    2 +-
 docs/subsystems/persistence.i18n.yaml         |    2 +-
 docs/subsystems/persistence.zh.md             |    4 +-
 docs/subsystems/scope.i18n.yaml               |    2 +-
 docs/subsystems/settings.i18n.yaml            |    2 +-
 docs/subsystems/settings.zh.md                |   14 +-
 docs/subsystems/subagent.i18n.yaml            |    2 +-
 docs/subsystems/subagent.zh.md                |   26 +-
 docs/subsystems/tools.i18n.yaml               |    2 +-
 docs/subsystems/tools.zh.md                   |    6 +-
 docs/subsystems/typert.i18n.yaml              |    2 +-
 docs/subsystems/typert.zh.md                  |   12 +-
 docs/subsystems/user-interaction.i18n.yaml    |    2 +-
 docs/subsystems/user-interaction.zh.md        |    4 +-
 docs/testing.i18n.yaml                        |    2 +-
 docs/testing.zh.md                            |   12 +-
 docs/tool-catalog.i18n.yaml                   |    6 +
 docs/tool-catalog.zh.md                       | 1553 ++++++++++
 docs/tool-execution-pipeline.i18n.yaml        |    6 +
 docs/tool-execution-pipeline.zh.md            |   64 +
 docs/user/develop/basic/publish.i18n.yaml     |    2 +-
 docs/user/develop/basic/publish.zh.md         |   14 +-
 docs/user/guide/config.i18n.yaml              |    2 +-
 docs/user/guide/config.zh.md                  |    4 +-
 docs/user/guide/index.i18n.yaml               |    2 +-
 docs/user/guide/index.zh.md                   |   26 +-
 docs/user/guide/providers.i18n.yaml           |    2 +-
 docs/user/guide/providers.zh.md               |    8 +-
 docs/user/guide/quickstart.i18n.yaml          |    2 +-
 docs/user/guide/quickstart.zh.md              |   14 +-
 docs/web-styling.i18n.yaml                    |    2 +-
 docs/web-styling.zh.md                        |    6 +-
 examples/web-cordis/README.i18n.yaml          |    2 +-
 examples/web-cordis/README.zh.md              |    2 +-
 packages/README.i18n.yaml                     |    2 +-
 packages/README.zh.md                         |   78 +-
 packages/api/README.i18n.yaml                 |    2 +-
 packages/api/README.zh.md                     |    4 +-
 packages/api/gateway/README.i18n.yaml         |    2 +-
 packages/api/gateway/README.zh.md             |    4 +-
 packages/api/remotes/README.i18n.yaml         |    2 +-
 packages/api/remotes/README.zh.md             |    2 +-
 packages/bash/bash-env/README.i18n.yaml       |    2 +-
 packages/bash/bash-env/README.zh.md           |   24 +-
 packages/bash/pwsh-local/README.i18n.yaml     |    2 +-
 packages/bash/pwsh-local/README.zh.md         |    4 +-
 packages/bash/tool-bash/README.i18n.yaml      |    2 +-
 packages/bash/tool-bash/README.zh.md          |   10 +-
 packages/bash/tool-pwsh/README.i18n.yaml      |    2 +-
 packages/bash/tool-pwsh/README.zh.md          |   46 +-
 packages/boot/app-boot/README.i18n.yaml       |    2 +-
 packages/boot/app-boot/README.zh.md           |   30 +-
 packages/bundle/README.i18n.yaml              |    2 +-
 packages/bundle/README.zh.md                  |    2 +-
 packages/bundle/headless/README.i18n.yaml     |    2 +-
 packages/bundle/headless/README.zh.md         |    2 +-
 packages/bundle/web-app/README.i18n.yaml      |    2 +-
 packages/bundle/web-app/README.zh.md          |    4 +-
 packages/client/README.i18n.yaml              |    2 +-
 packages/client/README.zh.md                  |   10 +-
 packages/client/connection/README.i18n.yaml   |    2 +-
 packages/client/connection/README.zh.md       |    4 +-
 packages/client/test-runtime/README.i18n.yaml |    2 +-
 packages/client/test-runtime/README.zh.md     |   10 +-
 .../client/ui-conversation/README.i18n.yaml   |    2 +-
 packages/client/ui-conversation/README.zh.md  |   12 +-
 .../client/ui-deliverables/README.i18n.yaml   |    2 +-
 packages/client/ui-deliverables/README.zh.md  |   10 +-
 .../ui-settings-general/README.i18n.yaml      |    2 +-
 .../client/ui-settings-general/README.zh.md   |    4 +-
 packages/client/ui-tool/README.i18n.yaml      |    2 +-
 packages/client/ui-tool/README.zh.md          |   32 +-
 packages/client/ui-workspace/README.i18n.yaml |    2 +-
 packages/client/ui-workspace/README.zh.md     |   12 +-
 .../credentials/credentials/README.i18n.yaml  |    2 +-
 packages/credentials/credentials/README.zh.md |   20 +-
 packages/feedback/README.i18n.yaml            |    2 +-
 packages/feedback/README.zh.md                |    4 +-
 .../command-feedback/README.i18n.yaml         |    2 +-
 .../feedback/command-feedback/README.zh.md    |   14 +-
 .../tool-str-replace-editor/README.i18n.yaml  |    2 +-
 .../fs/tool-str-replace-editor/README.zh.md   |   10 +-
 .../directory-picker-native/README.i18n.yaml  |    2 +-
 .../host/directory-picker-native/README.zh.md |    6 +-
 .../host/frontend-static/README.i18n.yaml     |    2 +-
 packages/host/frontend-static/README.zh.md    |    2 +-
 packages/host/webserver/README.i18n.yaml      |    2 +-
 packages/host/webserver/README.zh.md          |    8 +-
 .../pty/tool-bash-persistent/README.i18n.yaml |    2 +-
 .../pty/tool-bash-persistent/README.zh.md     |   14 +-
 .../README.i18n.yaml                          |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../session-persistence/README.i18n.yaml      |    2 +-
 .../session-projection-cache/README.i18n.yaml |    2 +-
 .../session-projection/README.i18n.yaml       |    2 +-
 .../session-telemetry-otel/README.i18n.yaml   |    2 +-
 .../session-telemetry/README.i18n.yaml        |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../session-title-llm/README.i18n.yaml        |    2 +-
 packages/settings/README.i18n.yaml            |    2 +-
 packages/settings/README.zh.md                |    2 +-
 .../settings/settings-local/README.i18n.yaml  |    2 +-
 packages/settings/settings-local/README.zh.md |   20 +-
 packages/settings/settings/README.i18n.yaml   |    2 +-
 packages/settings/settings/README.zh.md       |   16 +-
 packages/skill/skill-badge/README.i18n.yaml   |    2 +-
 packages/skill/skill-badge/README.zh.md       |    2 +-
 .../subagent-claude-code/README.i18n.yaml     |    2 +-
 .../subagent-claude-code/README.zh.md         |   10 +-
 .../subagent/subagent-codex/README.i18n.yaml  |    2 +-
 packages/subagent/subagent-codex/README.zh.md |   14 +-
 .../support/acp-snapshot/README.i18n.yaml     |    2 +-
 packages/support/acp-snapshot/README.zh.md    |   12 +-
 packages/typert/type-meta/README.i18n.yaml    |    2 +-
 packages/typert/type-meta/README.zh.md        |   16 +-
 packages/util/atomic-write/README.i18n.yaml   |    2 +-
 packages/util/atomic-write/README.zh.md       |    8 +-
 packages/util/environment/README.i18n.yaml    |    2 +-
 packages/util/environment/README.zh.md        |    8 +-
 python/development.i18n.yaml                  |    2 +-
 python/development.zh.md                      |   12 +-
 scripts/project-doc-site.spec.ts              |   42 +-
 scripts/translation-pairing.manifest.json     |   13 +-
 scripts/translation-pairing.spec.ts           |   11 +
 scripts/translation-pairing.ts                |   21 +
 scripts/verify-translation-pairing.ts         |    3 +-
 website/docs.ts                               |   53 +-
 565 files changed, 10606 insertions(+), 2171 deletions(-)
 create mode 100644 docs/agent-lifecycle.i18n.yaml
 create mode 100644 docs/agent-lifecycle.zh.md
 create mode 100644 docs/capability-seams.i18n.yaml
 create mode 100644 docs/capability-seams.zh.md
 create mode 100644 docs/config-catalog.i18n.yaml
 create mode 100644 docs/config-catalog.zh.md
 create mode 100644 docs/cordis-api/context.i18n.yaml
 create mode 100644 docs/cordis-api/context.zh.md
 create mode 100644 docs/cordis-api/events.i18n.yaml
 create mode 100644 docs/cordis-api/events.zh.md
 create mode 100644 docs/cordis-api/fiber.i18n.yaml
 create mode 100644 docs/cordis-api/fiber.zh.md
 create mode 100644 docs/cordis-api/registry.i18n.yaml
 create mode 100644 docs/cordis-api/registry.zh.md
 create mode 100644 docs/cordis-api/service.i18n.yaml
 create mode 100644 docs/cordis-api/service.zh.md
 create mode 100644 docs/event-producer-consumer.i18n.yaml
 create mode 100644 docs/event-producer-consumer.zh.md
 create mode 100644 docs/graph-atlas.i18n.yaml
 create mode 100644 docs/graph-atlas.zh.md
 create mode 100644 docs/module-graph.i18n.yaml
 create mode 100644 docs/module-graph.zh.md
 create mode 100644 docs/persistence-catalog.i18n.yaml
 create mode 100644 docs/persistence-catalog.zh.md
 create mode 100644 docs/tool-catalog.i18n.yaml
 create mode 100644 docs/tool-catalog.zh.md
 create mode 100644 docs/tool-execution-pipeline.i18n.yaml
 create mode 100644 docs/tool-execution-pipeline.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
index 0697332171..b18ca244be 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
@@ -1,6 +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
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
 2026-06-11-runtime-arg-validation.md: e0bca0ff24c5adc7ca58007932dff6580694b01d
-2026-06-11-runtime-arg-validation.zh.md: 09958147766b4015d6bebf786c4947b9d2941f74
+2026-06-11-runtime-arg-validation.zh.md: c98bde0ed2dd568a394aae74fb9f5549c3f61105
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
index 0995814776..c98bde0ed2 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-`defineTool`（[统一 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)）为工具作者的 `execute(args)` 提供了经 `InferArgs<S>` 映射的类型化参数。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 JSON：没有任何机制强制模型遵守 schema，因此畸形调用（缺少必需键、声明为数字的位置传入字符串，或字面量超出声明的集合）会以「仅名义类型化」的状态到达 `execute`。工具函数体随后要么在错误形状上崩溃，要么静默地行为异常。
+`defineTool`（[统一 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)）为工具作者的 `execute(args)` 提供了经 `InferArgs<S>` 映射的类型化参数。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 JSON：没有任何机制强制模型遵守 schema，因此畸形调用（缺少必需键、声明为数字的位置传入字符串，或字面量超出声明的集合）会以「仅在名义上类型化」的状态到达 `execute`。工具函数体随后要么在错误形状上崩溃，要么静默地行为异常。
 
 ## 决策
 
 `validateArgs(spec, args): string[]` 编译 `ParameterSchemaSpec`，并委托共享的 `validateJsonSchemaValue()` 遍历器，对格式正确的声明返回可读的违规列表。`defineTool` 在定义时对编译后的参数 schema 创建快照，并在调用类型化函数体之前执行校验；存在违规时会抛出 `ToolArgsError`（`INVALID_ARGS`），注册表将其作为模型可据以修正的错误结果返回。
 
-校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。原始注册的工具自行负责输入校验。
+校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。直接注册的工具自行负责输入校验。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
index 215f612f5e..efed9ca5ea 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
 2026-07-08-agent-scope-contexts.md: eb3f6f247bac1a1d81aa2644132c7b9cc04d602c
-2026-07-08-agent-scope-contexts.zh.md: 673dd8578bf545b1f14f3b7e7b89874d804e4ae9
+2026-07-08-agent-scope-contexts.zh.md: fe82ac18d07de97330e86461e6bdf86edc37d2ae
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
index 673dd8578b..fe82ac18d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -18,14 +18,14 @@ Status: implemented
 
 Cordis 是 SDK 底层的插件框架。Cordis **上下文**是插件用来访问服务和注册效果的对象，效果的清理跟随该上下文。[Cordis 入门](../../../../docs/cordis-primer.md)对该框架有更详细的说明。
 
-对大多数贡献者而言，完整契约是四条规则：
+对大多数贡献者而言，完整约定是四条规则：
 
 | 问题 | 规则 |
 |---|---|
 | 在哪里为某个 agent 注册行为？ | 通过 `agent.ctx` 调用普通注册 API |
 | 某个 agent 的操作能看到什么？ | 部署全局加上该 agent 的层，按所属服务的合并规则 |
 | 哪些作用域监听器会运行？ | 无作用域监听器加上为该操作所属 agent 注册的监听器 |
-| 该层存在多久？ | setup 在发布前完成；dispose 保留该层直到工作完全停稳 |
+| 该层存在多久？ | setup 在发布前完成；dispose（资源释放）保留该层直到工作完全停稳 |
 
 作用域是扁平的。解析永远不会遍历父级或兄弟作用域，生命周期所有权也不意味着注册继承。
 
@@ -49,14 +49,14 @@ flowchart LR
 
 ### 注册来源决定可见性与清理
 
-通过普通插件上下文进行的注册是部署全局的，随该插件一起 dispose（资源释放）。同一方法通过 `agent.ctx` 调用则贡献给一个 agent，随该 agent 的作用域一起 dispose。
+通过普通插件上下文进行的注册是部署全局的，随该插件一起 dispose。同一方法通过 `agent.ctx` 调用则贡献给一个 agent，随该 agent 的作用域一起 dispose。
 
 | 注册来源 | 默认可见性 | 随谁 dispose |
 |---|---|---|
 | 普通插件上下文 | 每个符合条件的 agent 视图 | 注册插件 |
 | `agent.ctx` | 仅该 agent 的视图 | agent 作用域 |
 
-工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此契约。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
+工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此约定。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
 
 普通贡献者的模式是在 agent setup 期间注册完整的本地世界：
 
@@ -88,7 +88,7 @@ await handle.dispose()
 ctx.tools.get('review_summary', handle.agent)  // undefined: scope is gone
 ```
 
-setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其契约仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
+setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其约定仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
 
 ### 操作选择视图
 
@@ -96,7 +96,7 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 工具查找与执行接收其所服务的 agent。提示词组装接收正在构建请求的 agent 的组装上下文。事件分发接收其领域主体。这使共享服务实例可在多个 agent 间复用，同时让每个操作的视图保持显式。
 
-只有采纳了作用域契约的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
+只有采纳了作用域约定的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
 
 ### 作用域事件将路由与事件数据分离
 
@@ -108,13 +108,13 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 ### 创建最后发布，dispose 最后撤销
 
-`ctx.agents.create()` 和 `resume()` 构建未发布的会话、作用域、agent 和驱动器。它们等待 `setup`，同步调用其可选的 `AgentSetupCommit`，准入最终的会话和 agent 条目，按序公告，启动循环，然后才返回 handle。该提交操作让可变的配置状态在所有 setup 的 await 均结算后，于确切的发布边界重新校验；若其抛出异常，则会在公告任何一个身份前回滚私有事务，而成功提交后的撤销属于普通的实时拆卸。
+`ctx.agents.create()` 和 `resume()` 构建未发布的会话、作用域、agent 和驱动器。它们等待 `setup`，同步调用其可选的 `AgentSetupCommit`，准入最终的会话和 agent 条目，按序公告，启动循环，然后才返回 handle。该提交操作让可变的配置状态在所有 setup 的 await 均结算后，于确切的发布边界重新校验；若其抛出异常，则会在公告任何一个身份前回滚私有事务，而成功提交后的撤销属于普通的存活期拆除。
 
 可选的创建信号仅在创建或恢复挂起期间取消工作。promise resolve 后，返回的 `AgentHandle` 拥有显式 dispose 权。
 
 如果加载、setup、可选的 setup 提交、准入或发布失败，私有事务回滚其准备的一切。使用同一个调用方提供的存活 ID 的并发操作可能都到达 setup，但最终注册表条目只准入一个；每个失败者拒绝并清理其私有资源。在等待 dispose 完成后的顺序复用仍然有效。
 
-`AgentHandle.dispose()` 反转边界。它停用创建或驱动，等待同步发布解除，停止并排空驱动器和最终会话刷写，分离 agent 和会话，最后 dispose 作用域。重复或竞争的 dispose 请求合并为一个完成 promise。
+`AgentHandle.dispose()` 反转边界。它停用创建或驱动，等待同步发布完成退栈，停止并排空驱动器和最终会话刷写，分离 agent 和会话，最后 dispose 作用域。重复或竞争的 dispose 请求合并为一个完成 promise。
 
 调用方的 Cordis 上下文和具体的 AgentLoop 工厂是结构性共同所有者。卸载任一方都会 dispose 事务或存活 agent。
 
@@ -152,7 +152,7 @@ agent 作用域组合的是受信的同进程注册。它不沙箱化插件、
 
 ### 向每个注册传递 agent 选项
 
-类似 `tools.register(definition, { agent })` 的 API 在每个注册表中重复作用域管道，且允许可见性所有权与清理所有权漂移。通过 `agent.ctx` 注册使两个事实跟随同一个 Cordis effect owner。
+类似 `tools.register(definition, { agent })` 的 API 在每个注册表中重复作用域传递逻辑，且允许可见性所有权与清理所有权漂移。通过 `agent.ctx` 注册使两个事实跟随同一个 Cordis effect owner。
 
 ### 过滤事件但保持注册表全局
 
@@ -160,7 +160,7 @@ agent 作用域组合的是受信的同进程注册。它不沙箱化插件、
 
 ### 为每个 agent 创建独立的服务图
 
-所需的视图是共享部署服务加上一个本地注册层。每 agent 一个图会重复适配器，并使共享持久化、提供方注册表和应用启动复杂化。
+所需的视图是共享部署服务加上一个本地注册层。每个 agent 一个服务图会重复适配器，并使共享持久化、提供方注册表和应用启动复杂化。
 
 ### 继承父级注册作用域
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index dbdc4347f6..527ac2d6b3 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
 2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: 8b1332c23ce3b6c0332fcde40b4f4ac8dd20aa45
+2026-07-12-agent-scope-runtime-design.zh.md: 2dbdcab2ce3a7f92bf537d93a65dfe44374ec07c
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index 8b1332c23c..2dbdcab2ce 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Agent 作用域运行时设计与正确性
+# Agent Note: agent 作用域运行时设计与正确性
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[agent 作用域契约](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份契约。
+[agent（智能体）作用域约定](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份约定。
 
 主要的设计风险是为每个竞态条件引入第二套机制。独立的预留、就绪哨兵、取消中继、快照层和保护注册表可能镜像同一个事实，直到没有读者能分辨哪个才是权威的。这些机制还会诱使运行时把可信的类型化调用当作敌对的序列化边界来处理。
 
@@ -23,18 +23,18 @@ Status: implemented
 | 选择全局加某个 agent 的注册 | 不透明作用域键、路由载体与共享 layer store |
 | 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表条目 |
 | 协调创建/恢复 | 单个 `AgentCreationTransaction` |
-| 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 |
-| 在同一进程内传递类型化值 | Readonly 借用契约 |
-| 组合模型可见的提示词与工具表面 | 单个共享工具视图加权威的 assembly-waterfall 结果 |
+| 保护持久化、队列、模型或协议格式（wire format）数据 | 在该边界处一次性物化 |
+| 在同一进程内传递类型化值 | Readonly 借用约定 |
+| 组合模型可见的提示词与工具表面 | 单个共享工具视图加 assembly waterfall（瀑布式事件）的权威结果 |
 | 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/完全停稳态事实 |
 
 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与提示词、subagent 与工作流，最后是可执行检查。
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者契约。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
-理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或否决一个操作。
+理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall 让监听器按顺序变换或否决一个操作。
 
 ### 上下文是贯穿单个服务图的所有权路径
 
@@ -56,7 +56,7 @@ Cordis 使用 dispatch receiver（`this`）过滤监听器，而 harness 的监
 
 因此，产品辅助函数构造载体并单独传递领域主体。这防止监听器路由变成另一套对象模型，并使事件签名在不了解载体内部的情况下也可理解。
 
-Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
+Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
 
 ## 作用域路由：一个不透明键选择一层
 
@@ -82,7 +82,7 @@ Receiver 是一个小型载体而非领域对象的透明代理。需要 agent 
 
 类型标记拒绝普通的裸 receiver 误用，开发环境不变式覆盖直接 JavaScript 或强制转换的 dispatch。主体保持显式，因为路由正确性和有用的事件数据是不同的关注点。
 
-## Agent 创建：一个事务拥有完整操作
+## agent 创建：一个事务拥有完整操作
 
 创建和恢复是一个具有多个阶段的异步生命周期，而非多个生命周期。`AgentCreationTransaction` 拥有调用方和工厂的活跃性、可选取消、私有资源、发布、回滚，以及每个所有者观察到的记忆化拆除。
 
@@ -104,7 +104,7 @@ detach 闭包捕获其确切注册表条目。它仅在映射仍指向该注册
 
 ### Setup 是私有世界内的可信组合
 
-Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开契约不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
+Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开约定不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
 
 事务将异步加载和 setup 与停用进行竞争，而非无限等待外部代码拥有的 promise。如果取消或所有者卸载获胜，即使外部 promise 永不结算，公开创建也会在事务拥有的清理之后拒绝。
 
@@ -120,7 +120,7 @@ Setup 接收完整的子上下文，可以等待插件激活。它可以注册
 6. 发射 `agent/session-start`。
 7. 启动 driver。
 
-Agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。
+agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。
 
 以下序列图隔离了非显而易见的竞态：同步创建监听器可以在发布调用栈仍拥有两个注册表条目时请求 dispose。拆除必须立即停用，但要等待该栈展开后才停止和分离任何东西。
 
@@ -172,7 +172,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 追加遵循一个序列：
 
-1. 物化持久化事件和表面意图。
+1. 物化持久化事件和呈现意图。
 2. 取得 SessionEntry 的独占所有权，并拒绝该注册表条目上的重入追加。
 3. 解析作用域回调并运行内部不变式验证。
 4. 恰好推送一次；这是提交点。
@@ -185,7 +185,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 ## 信任边界：仅在所有权真正变更时复制
 
-运行时区分类型化的进程内契约与序列化及持久化边界。这是值和回调的主要简化规则。
+运行时区分类型化的进程内约定与序列化及持久化边界。这是值和回调的主要简化规则。
 
 | 边界 | 所有权规则 |
 |---|---|
@@ -196,9 +196,9 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 | 持久化会话或持久化数据 | 在提交前物化并验证 |
 | Worker、进程或协议格式消息 | 序列化、验证并拥有解码后的值 |
 
-测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产契约。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
+测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产约定。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
 
-回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件契约隔离失败。
+回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件约定隔离失败。
 
 ## 工具与提示词：单一视图、权威组装、已提交的结果
 
@@ -206,7 +206,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 ### 一个解析器定义工具视图
 
-私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。Schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
+私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
 
 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule)拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
 
@@ -216,7 +216,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 注册表为每次执行分配一个新的带品牌的 `Symbol` token。嵌套的 Code Mode 调用将外层 token 作为 `parent` 携带，因此结构化输出可以通过标识将内层捕获与其外层 `run_code` 结果关联。
 
-注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化契约，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
+注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化约定，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
 
 参数在模型/工具 JSON 进入流水线时一次性物化。Pre-、around- 和 post-execute 监听器操作类型化的 execution 和决策。Call ID 关联、审批、单调守卫和 Code Mode 嵌套仍然是显式的关系检查。
 
@@ -238,7 +238,7 @@ Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子
 
 对于 Code Mode SDK 调用，内层成功结果记录 `{ parentToken, value }` 而非提交。观察者等待 token 匹配 `parentToken` 的 `run_code` 执行，仅在该外层最终结果也成功时才提交。程序失败、运行时中止或外层 post-policy 拒绝会丢弃待定值。
 
-一旦值处于待定或已提交状态，作用域单调守卫拒绝后续工具调用。成功的结构化输出执行会调用 `exec.concludeTurn()`，因此其自身不可变结果携带 `concludesTurn: true`，循环在该步骤结束工具循环。Schema 验证失败仍然是普通的 `INVALID_ARGS` 工具错误，子级可以在同一轮次内重试。
+一旦值处于待定或已提交状态，作用域单调守卫拒绝后续工具调用。成功的结构化输出执行会调用 `exec.concludeTurn()`，因此其自身不可变结果携带 `concludesTurn: true`，循环在该步骤结束工具循环。schema 验证失败仍然是普通的 `INVALID_ARGS` 工具错误，子级可以在同一轮次内重试。
 
 纯 Code Mode 的注册表贡献从原生 wire schema 中省略 `structured_output`，并通过生成的 SDK 暴露它。Assembly waterfall 可以有意改变该展示；执行仍然针对子作用域定义进行验证，监听器拥有其创建的任何替代模型可见路由的一致性。
 
@@ -252,21 +252,21 @@ Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子
 | 工具结果 | 观察不可变的已提交结果 | 结构化输出必须仅提交实际逃出流水线的结果 |
 | 轮次 continuation | 通过已提交工具结果终止 | 已提交的终端输出必须结束轮次 |
 
-`ToolGuard` 是单调策略注册表。已提交的工具观察是上述被隔离的 `tools/result` 点。终端结构化输出在自身执行上标记 `concludesTurn`，因此终止性成为权威结果上的数据，而不是独立 hook 决策。
+`ToolGuard` 是单调策略注册表。已提交的工具观察是上述被隔离的 `tools/result` 点。终端结构化输出在自身执行上标记 `concludesTurn`，因此终止性成为权威结果上的数据，而不是独立钩子决策。
 
-### Skill 和 approval 服务信任类型化调用方
+### skill（技能）和 approval 服务信任类型化调用方
 
-Skill 注册表定义和 approval 策略是 readonly 的同进程契约。它们的服务不克隆回调对象，也不防御交接后的回调替换。
+skill 注册表定义和 approval 策略是 readonly 的同进程约定。它们的服务不克隆回调对象，也不防御交接后的回调替换。
 
-Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
+skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
 
 ## Subagent：发布即 start promise
 
 Subagent 启动有一次所有权转移。提供方拥有未发布资源，直到其 start promise 以一个已发布 run 兑现；调用方拥有返回的 run 并必须 dispose 它。
 
-### 服务契约有一个取消通道
+### 服务约定有一个取消通道
 
-`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的契约。
+`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的约定。
 
 `SubagentStartRequest.signal` 是必需的。中止它会在启动期间，以及已发布 run 的剩余就绪或轮次工作中请求取消。`SubagentRun.dispose()` 也请求取消并等待完全停稳。没有单独的公开 `run.cancel()` 通道。
 
@@ -314,11 +314,11 @@ Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲
 
 ## 正确性强制
 
-该设计通过类型、运行时逃逸点、生成的契约和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
+该设计通过类型、运行时逃逸点、生成的约定和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
 
 ### 类型使常规路径难以误用
 
-Readonly 契约描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
+Readonly 约定描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
 
 TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进程消息或持久化文件，因此运行时强制保留在这些逃逸点。
 
@@ -326,9 +326,9 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 `dsh-scope/invariant` 配套插件在被选用时验证每个声明的作用域事件使用带标记的载体，以及暴露主体的事件族使用匹配的键。独立的 `dsh-session/invariant` 贡献在追加提交前暂存 trace 验证，并在同一事件提交后推进；二者都通过 `ctx.invariants` 注册。
 
-该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合契约变成推测性的运行时机制，却不保护真实的外部边界。
+该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合约定变成推测性的运行时机制，却不保护真实的外部边界。
 
-### 生成的产物使公开契约保持对齐
+### 生成的产物使公开约定保持对齐
 
 事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。
 
@@ -336,7 +336,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ## 曾考虑的替代方案
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域契约的替代方案。此处的替代方案关注实现形态。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
 
 ### 使用透明代理作为作用域载体
 
@@ -348,7 +348,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 对每个类型化的同进程参数做快照
 
-通用复制防御有状态 getter 和违反 readonly 契约的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
+通用复制防御有状态 getter 和违反 readonly 约定的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
 
 ### 为就绪、取消和 dispose 提供独立控制器
 
@@ -375,10 +375,10 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 - 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。
 - 创建和恢复不暴露部分配置的句柄；最终写入注册表时的失败者和发布失败清理每个已准备的资源。
 - Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。
-- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。
+- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 约定。
 - ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。
 - 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。
-- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳契约。
+- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳约定。
 - Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。
 
 ### 代价与局限
@@ -387,6 +387,6 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 
 可信的 `system-prompt/assemble` 监听器可以移除或替换 Code Mode 和结构化输出协议片段。这是有意为之：监听器拥有最终组合，必须保持部署期望仍可用的任何协议。
 
-该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 契约的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
+该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 约定的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
 
 [安全与权限非目标](2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)仍然是根本性的。这些机制证明注册组合、发布和生命期所有权；它们不证明隔离或父到子的非升权。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 65cbe478ae..76877fd12c 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 55fa8084083aa83fbb4a38f8e41d2e5624b6e58e
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 06b861ef61e83985b5c3640ff8eddfa5f6845c81
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 55fa808408..06b861ef61 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -1,4 +1,4 @@
-# RFC: GUI 分层与 RPC 协议——host/client 按能力支持方分层、四象限消息模型与 fetch 载体
+# Agent Note: GUI 分层与 RPC 协议——host/client 按能力提供方分层、四象限消息模型与 fetch 载体
 
 Status: implemented
 
@@ -8,20 +8,20 @@ Status: implemented
 
 ## Problem
 
-需要提供 UI 对接层，除已有 ACP/stdio基础版本外，还需要 Web(server) 、 Electron 、等其他产品 UI 形态。我们把这些形态统一称为 Client。希望有如下能力支持:
-- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh run`(headless) ，一个进程两种模式（设计预留）
+需要提供 UI 对接层，除已有 ACP（Agent Client Protocol）/stdio 基线外，还需要 Web（server）、Electron 等其他产品 UI 形态。我们把这些形态统一称为 Client。希望具备以下能力：
+- 一个 `dsh` 进程同时支持 `dsh web`（启动）和 `dsh run`（headless），一个进程两种模式（设计预留）
 - 以与 `dsh web` 同构的 Web 技术形态，在 Electron 中启动
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
 
-同时各消费端的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE、将来 IPC），还需要一个通道无关的消息模型和单一契约事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
+同时各消费方的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE（Server-Sent Events）、将来 IPC），还需要一个通道无关的消息模型和约定的单一真源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
 
 ## Decision
 
 ### 分层
 
-目录按照如下分层:
-- `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
+目录按照如下分层：
+- `packages/host/*`：包只提供 Host 侧能力（代表了基于现有 harness 插件系统的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
 - `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）：
     - **纯库**（`ui-slots`、`web-react`、`ui-primitives`，外加内核包 `loader`）：普通根入口包，静态打包进壳；前三者播种进模块表。
@@ -49,7 +49,7 @@ harness core packages ──────────────────┘
 
 - `runtime → apiproxy` 单向；apiproxy 仅依赖类型定义。
 - client 侧包**永不 import** host 侧包的运行时（只吃 `/api`、`/client` 两个浏览器安全子路径）。
-- `webserver` 不依赖 `runtime`：它提供 `{ fetch }` 特定实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
+- `webserver` 不依赖 `runtime`：它提供一个 `{ fetch }` 形状的实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
 - client 侧跨包 import 插件包一律走 `/client` 子路径，且插件包之间只限类型 import——跨插件值 import 在 tsdown 纯度门禁处即构建错误（值层面的协作走 cordis 服务；边规则归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）。
 
 TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.json` = solution；`tsconfig.host.json` = host 侧 + 测试，排除 `packages/client`；`tsconfig.client.json` = client 各包及其测试）：两侧在相同键（`sessions`、`loader`）下以不同服务合并 cordis `Context` 接口，单一 program 会同时看到两份声明合并而报冲突。共享叶子包（session/llm/tools/apiproxy 等）只构建一次，由两个 program 共同引用（[拓扑](../process/2026-07-22-tsconfig-solution-root-two-aggregates.md)）。
@@ -60,11 +60,11 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 
 | 层 | 包 | 职责 | 关键纪律 |
 |---|---|---|---|
-| 前置层 | `dsh-host-apiproxy` | TS/zod 定义 (api/)+ fetch 抽象 (fetch/：handler + 客户端基类) | 做简单、所有接入方都要；Node/浏览器皆可 import；协议内容见下文「消息协议」起各节；client 不得经 ctx 绕开 api |
+| 前置层 | `dsh-host-apiproxy` | TS/zod 定义 (api/)+ fetch 抽象 (fetch/：handler + 客户端基类) | 保持简单——每个消费方都需要它；Node/浏览器皆可 import；协议内容见下文「消息协议」起各节；client 不得经 ctx 绕开 api |
 | 装配层 | `dsh-host-runtime` | 插件组合 + ApiProxy 集成 + web UI 插件挂载（覆盖八个 dshClient 包的内存 Loader 树）；host 级配置归属地（defaults/persistenceRoot，将来用户 profile） | 装什么插件、给什么默认值只在这里定；壳不得改装配 |
 | 承载层 | `dsh-host-webserver` | Web 形态 HTTP 与 upgrade：静态服务 + `/api/*`→handler 转发 + WebSocket upgrade route + close 语义；插件 bundle 端点 + `__DSH_BOOT__` manifest（元数据清单）注入（由 web 插件注册表供给） | Web（浏览器访问）专用；零 workspace 依赖（注册表经结构注入到达）；Electron 不复用它 |
 | client 库 | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | slot 注册表核心 / ctx↔React 胶合 / 纯 React 原子组件 | 组件零 cordis 运行时依赖；由壳播种进 loader 模块表 |
-| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
+| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费方、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
 | 应用态 | `@deepseek-ai/dsh`（apps/cli）+ `dsh-frontend`（apps/web，vite 应用） | bin 粗分发 + 每形态一个拼装模块（web.ts / headless.ts）；vite 应用是 `dsh-client-web` 壳表面之上的薄 main | 形态间动态 import 互不加载；dist 定位等 workspace 知识留在 app |
 
 #### 命名规则
@@ -116,7 +116,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 
 `ClientResponse` 的 HTTP 应答体是 `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }`——载体层回执，**不是** RpcMessage（response 不再有 response）；迟到/重复应答收 `not-pending`，逻辑收敛面是 `*/resolved` 帧。
 
-## 类型体系：函数签名即事实源
+## 类型体系：函数签名即真源
 
 ### RpcMethodMap 与派生泛型（`api/rpc-map.ts`）
 
@@ -151,7 +151,7 @@ export type ResponseValue<K> =
 - **锚定**：schema 统一 `satisfies z.ZodType<Wire<T>>`（`api/rpc.schema.ts`）。`Wire<T>` 是深度「| undefined」宽化——仓库开 `exactOptionalPropertyTypes` 而 zod `.optional()` 输出 `T | undefined`，直接锚原类型全线不可用；JSON wire 上缺席与 undefined 同形，宽化不损失校验语义。透传宽分支（`SessionEvent`/`ContentBlock`/帧 union/`RpcError`）与 brand id schema 用显式 cast + 注释。
 - brand cast 单点：每个 schema 文件的 id cast 收口一处（`rpcIdSchema` 是 rpc.schema.ts 唯一 cast 点）。
 
-## 契约面（ApiProxy）
+## 约定面（ApiProxy）
 
 根接口 `ApiProxy = { sessions, host, events, respond }`（`api/index.ts`）。新 client-request 域 = 新的一对文件（`<域>.ts` + `<域>.schema.ts`）+ 根接口一个字段 + map 加行。
 
@@ -163,7 +163,7 @@ export type ResponseValue<K> =
 |---|---|---|---|
 | `session.list` | `{ cursor?: string }`（cursor 留座不实现） | `{ items: SessionSummary[] }` | 已持久化 session，updatedAt 倒序；v1 不建索引 |
 
-其余方法（`session.create`/`session.history`/`session.rename`/`session.prompt`/`session.cancel`/`host.describe`）的参数与返回不在此复写——签名即事实源，见 `api/sessions.ts`、`api/host.ts` 与 `RpcMethodMap`。
+其余方法（`session.create`/`session.history`/`session.rename`/`session.prompt`/`session.cancel`/`host.describe`）的参数与返回不在此复写——签名即真源，见 `api/sessions.ts`、`api/host.ts` 与 `RpcMethodMap`。
 
 ### 帧（server→client，具名 union）
 
@@ -173,7 +173,7 @@ export type ResponseValue<K> =
 |---|---|---|
 | `session/event` | `{ sessionId; event: SessionEvent }` | 核心透传：core 事件原样过，`assistant/chunk` 即 token 流，无独立 delta 帧 |
 
-其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缝竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
+其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缺口竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
 
 **透传纪律**：wire 上的事件/消息/内容块就是 core 类型（`SessionEvent`/`ContentBlock`），不造第二套 DTO；类型经 `import type` 依赖链直达浏览器。`SessionEventMap` merge-extensible：client 对未知 type documented-default（忽略），事件 schema 留「合法信封+未知类型」分支——信封仍严格，不是字段级 passthrough。
 
@@ -181,11 +181,11 @@ export type ResponseValue<K> =
 
 - **历史 = 事件重放**：一套 fold（client 侧），历史分页与 live 增量同一条代码路径；server 不做物化快照第二套。history **页边界对齐消息边界**（绝不从消息中间截断；chunk 随定稿消息归组），尾页含进行中 partial 的 chunk。
 - **prompt 关联**：prompt 的 rpcId 经 MessageSource（`'user-rpc'`）透传进 `user/message` 事件，client 以此把乐观回显转正。
-- **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，有缝再补拉一次。
-- **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 Agent 的情况下检查持久化存储，而绑定到 Agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
-- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：契约与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
+- **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，如有缺口，再补拉一次。
+- **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 agent（智能体） 的情况下检查持久化存储，而绑定到 agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
+- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：约定与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
 - **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
-- **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
+- **预留 seam纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
 
 ## 客户端载体：AbstractApiClient 类体系（`fetch/client.ts`）
 
@@ -193,7 +193,7 @@ export type ResponseValue<K> =
 
 ### IApiClient：caller 视图
 
-与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名契约，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
+与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名约定，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
 
 ### 基类持有的协议路径
 
@@ -207,47 +207,47 @@ export type ResponseValue<K> =
 
 ### 实例级 envelope 观测切面
 
-四象限全形均过 `onEnvelope`；基类实现是**实例持有的微任务合批缓冲**（帧风暴不逐帧惊扰消费者；模块级状态会跨实例/测试泄漏，故实例持有）。观测者经 `subscribeEnvelopes(listener)` 订阅（收整批 `readonly RpcMessage[]`，返回退订函数）；listener 抛异常被隔离（观测不得反噬载体）。无订阅者时零缓冲成本。当前没有任何现役消费者订阅——该切面是 wire 诊断的预留位（已退役的 RPC 调试面板是它的首个消费者，将来的诊断消费者接入时不动载体）。
+四象限全形均过 `onEnvelope`；基类实现是**实例持有的微任务合批缓冲**（帧风暴不逐帧惊扰消费方；模块级状态会跨实例/测试泄漏，故实例持有）。观测者经 `subscribeEnvelopes(listener)` 订阅（收整批 `readonly RpcMessage[]`，返回退订函数）；listener 抛异常被隔离（观测不得反噬载体）。无订阅者时零缓冲成本。当前没有任何现役消费方订阅——该切面是 wire 诊断的预留位（已退役的 RPC 调试面板是它的首个消费方，将来的诊断消费方接入时不动载体）。
 
 ### 子类表（传输承载）
 
 | 子类 | 所在包 | doFetch | 用途 |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二个真正的消费方 |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，契约/基类零改 |
+| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
-**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
+**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一真源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
 
 **加一个帧型（3 步）**：①`MuxFrame`/`HostFrame` union 加一支（可应答帧须注明 rpcId 稳定语义）；②帧 schema 加一支；③消费端 fold/路由的 documented-default 已兜底未知型，按需加显式分支。
 
 **加一个错误码（2 步）**：①`RpcErrorDetailsMap` 加一行（details 必填）；②`rpcErrorSchema` discriminatedUnion 加一支。
 
-**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。契约与基类零改。
+**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。约定与基类零改。
 
-**升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
+**升格一个预留 seam**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
 
 ## Consequences
 
-所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留 seam（fork/inject/task.list/listModels/hostInstanceId）在真正的消费方出现前保持休眠。
 
 ## Alternatives considered
 
 | 放弃项 | 一句话理由 |
 |---|---|
-| 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
-| 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开契约，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力提供方分层让新形态零新包 |
+| 混合体建包（如 headless 独立包） | 混合体只有一个消费方（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
+| 作为消费方的 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
-| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、契约双份人肉对齐、命名无 convention 自然漂移 |
+| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |
 | 三信封模型（Request/Response/Frame 各一信封，签名不感知方向） | rpcId 是逻辑层关联，帧与应答的方向语义靠通道推断在换载体时即失效 |
-| 具名 Request/Response 类型对为事实源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
-| REST 风格路径 | 消费者是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
+| 具名 Request/Response 类型对为真源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
+| REST 风格路径 | 消费方是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
 | DTO 层（wire 专用第二套结构） | core 类型 type-only 直达浏览器零成本；DTO 是永久的双向同步税 |
-| cursor 续传（mux since 实装） | 重连=重建（opencode 同款）覆盖 v1 全部需求；签名留座，实装等真实消费者 |
+| cursor 续传（mux since 实装） | 重连=重建（opencode 同款）覆盖 v1 全部需求；签名留座，实装等真正的消费方 |
 | createApiClient 工厂函数（原实现） | 平台差异（传输/观测）是继承切面不是参数；类体系让 fixture 在协议层替换而不是包一层假信封 |
 | 对 `command.execute` 应用 30 秒传输时限 | 命令耗时属于操作本身，而非传输健康预算；该时限会终止本应继续运行的长时处理器，调用方／连接取消已提供所需的停止路径 |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index d3bbc7da9d..7a82202c72 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
 2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
-2026-07-19-gui-web-client-architecture.zh.md: cf31220aad61e4845f7fe90b73bf5da4432e53de
+2026-07-19-gui-web-client-architecture.zh.md: 78a212dc18c1f553a6f782ed60822e36a622bda3
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index cf31220aad..78a212dc18 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -1,10 +1,10 @@
-# RFC: Web 客户端架构——client cordis 插件树、slot 体系与 React-free 对象层
+# Agent Note: Web 客户端架构——client cordis 插件树、slot 体系与 React-free 对象层
 
 Status: implemented
 
 [English](2026-07-19-gui-web-client-architecture.md) | 中文
 
-> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/契约面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
 
 ## Problem
 
@@ -30,27 +30,27 @@ Status: implemented
 
 ## client cordis 树与装载链
 
-装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` seam；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
+装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双阶段 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` seam；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一阶段预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE（Server-Sent Events）帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
 类型宇宙在聚合层拆分——`tsconfig.host.json` 是 host program、`tsconfig.client.json` 是 client program，二者由 solution 根 `tsconfig.json` 引用，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
 
 ## slot 体系：页面怎么拼
 
-slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占坑、声明并授权子坑（`children` spec 对象）、声明 store、注入业务面；组件 props 分四份额自动推导到达（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
+slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占用一个 slot、声明并授权其子 slot（`children` spec 对象）、声明 store、注入业务面；组件 props 以四个自动推导的份额传入（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
 
 实现的家：注册表核心与 props 份额类型在 `packages/client/ui-slots`，出口组件/渲染器/uSES 桥在 `packages/client/web-react`。
 
 ## 服务与 scope 寻址
 
-服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
+服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图 slot 注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装 seam）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list slot 的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
-**scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
+**scope 寻址**与 host 侧 agent（智能体） scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
 ## 数据对象层（`packages/client/runtime/src/client/sessions/`）
 
-帧从这里进、快照从这里出、fold 坐在中间——React-free（零 React import，grep 可断言）：
+帧从这里进、快照从这里出、投影坐在中间——React-free（零 React import，grep 可断言）：
 
 ```
 mux/host 帧（ConnectionController 泵入，sinks 注入）
@@ -69,24 +69,24 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 ```
 
 - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
-- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
+- **ConversationSnapshot**（conversation.ts）：不可变快照约定——`nodes`（供用户阅读的 transcript（文本记录），日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
-- **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
+- **TranscriptAdapter / PartialAccumulator**：transcript 是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩（compaction）检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
 - **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层 RFC 属地。
 
 ## React 面（`packages/client/web-react`）
 
 胶水包就是整条 ctx↔React 边界；组件保持零框架依赖。
 
-- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据契约合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
-- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 契约四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
+- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据约定合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
+- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 约定四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
 - `useInvoke(fn)`：把异步动作包成引用恒定的触发器加 pending 标志；pending 走 per-hook 外部 store 经 uSES 读出（渲染路径零 setState），并发调用计数，invoke 引用永不变。
-- 相等性协议，全链一致：生产端结构共享；消费端以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
+- 相等性协议，全链一致：生产端结构共享；消费方以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
 
 ## 目录形态
 
-Client 包位于 `packages/client/*`，`apps/web` 是壳 boot 导出之上的薄 Vite 应用。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。`ui-slots`、web-react 与 runtime 构成基础设施方向；功能插件通过 service 与 slot 协作，不导入展示实现。
+Client 包位于 `packages/client/*`，`apps/web` 是壳 boot 导出之上的薄 Vite 应用。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。`ui-slots`、web-react 与 runtime 构成基础设施方向；功能插件通过服务与 slot 协作，不导入展示实现。
 
 多域插件包的 client 半边还按未来包边界再拆——ui-conversation 即样板：
 
@@ -108,7 +108,7 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
 - **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
index acb9d72ef1..91f2d8742b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
 2026-07-19-zstandard-jsonl-session-logs.md: 93fc20f931c75552352834b9340e7d38680d4254
-2026-07-19-zstandard-jsonl-session-logs.zh.md: 061d7fcb55c775eed10e99bae47777d32cc8eee1
+2026-07-19-zstandard-jsonl-session-logs.zh.md: 48dde6018bc022c90735ca351207be46cd0956a2
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
index 061d7fcb55..48dde6018b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量庞大的 `assistant/chunk` 记录。原始文本便于检查，但重复的 JSON 键和模型文本会增加存储与 I/O 开销。压缩编码必须保留既有的 append/fsync 提交边界、首次物化时的无冲突发布、崩溃修复以及仅元数据列举；如果每轮都重写整个压缩文件，就会失去这些属性。
 
-编码还必须在部署边界上保持显式。快照 fixture 与外部逐行读取器需要原始 JSONL，而后端无法在同一根目录中安全猜测压缩产物与原始产物，也不能静默迁移预发布会话数据。
+编码还必须在部署边界上保持显式。快照 fixture（测试前置数据）与外部逐行读取器需要原始 JSONL，而后端无法在同一根目录中安全猜测压缩产物与原始产物，也不能静默迁移预发布会话数据。
 
 ## 决策
 
@@ -20,7 +20,7 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 ### 帧与写入路径
 
-压缩产物是标准独立 [Zstandard 帧](https://datatracker.ietf.org/doc/html/rfc8878)的串联：第一个带校验和的帧只包含头部行，后续每个持久追加批次各占一个带校验和的帧。正常 agent loop 批次就是轮次提交，因此帧边界保留既有持久化检查点，同时不让存储层依赖轮次事件类型。
+压缩产物是标准独立 [Zstandard 帧](https://datatracker.ietf.org/doc/html/rfc8878)的串联：第一个带校验和的帧只包含头部行，后续每个持久追加批次各占一个带校验和的帧。正常 agent loop（智能体循环）批次就是轮次提交，因此帧边界保留既有持久化检查点，同时不让存储层依赖轮次事件类型。
 
 压缩使用 Node 内置的 [`zstdCompress` 与 `zstdDecompress`](https://nodejs.org/download/release/v22.19.0/docs/api/zlib.html)，仓库最低支持的 Node 22.19 已提供这些 API。后端启用 `ZSTD_c_checksumFlag`，其余采用 Node 默认值，不公开压缩级别调节项，也不增加依赖。Node 将该 API 标记为实验性，因此 Node 22.19、24 与 26 兼容性门禁会执行同一个辅助实现。
 
@@ -36,9 +36,9 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 ### 消费方与验证
 
-CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
+CLI（命令行界面）、ACP（Agent Client Protocol）与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
 
-共享持久化契约与协调器契约会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
+共享持久化约定与协调器约定会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index f8a9c8c260..33ff739db9 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
 2026-07-23-client-plugin-loading-model.md: 2dc0c68e5f20bd790c2362f92c16dece171babf5
-2026-07-23-client-plugin-loading-model.zh.md: ce7850e37b9ae2735565a35ce3de28f4f290ed04
+2026-07-23-client-plugin-loading-model.zh.md: abe62f4c03147cc4716103e531adb812f073e622
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index ce7850e37b..abe62f4c03 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: client 插件装载——普通包、dshClient 插件与双层 boot
+# Agent Note: client 插件装载——普通包、dshClient 插件与双阶段 boot
 
 Status: implemented
 
@@ -31,7 +31,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 - **普通包**是模块系统自身所需的绝对基座，加上尚未转成 DI 的库：react 家族、cordis、`@deepseek-ai/dsh-client-modules`（模块系统本身——它永远不可能是插件，因为模块先于一切模块）、web 壳内核，以及——暂时——ui-slots、web-react、ui-primitives。普通包打进壳 bundle、播种进模块表、对 host 图不可见。
 - **插件包**是其余一切。每个都携带 `dshClient` manifest（元数据清单）声明（`{ platform, inject, immediately? }`）和同一种统一形态：共享 tsdown 预设产出 `lib/client.js`，`exports["./client"]` 指向该 bundle。每个都是 host 独家撰写的图里受治理的 entry。当前包括：connection、runtime、ui-theme、i18n、hmr（仅进 dev 图）、ui-layout、ui-sidebar、ui-conversation、ui-model-selector、ui-question、ui-trajectory。
 
-manifest 拥有包的装载契约：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
+manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
@@ -72,21 +72,21 @@ vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点
 
 为什么名册是 yml 行而不是扫描？因为哪些插件组合进一次部署是组合决策，不是包属性——一个 dshClient 包存在于仓库里，不代表这次部署要挂载它，扫描发现无从替人做这个决定；node 半只扫描配置树实际挂载了的东西。
 
-**第一层——模块面。**壳在图之上建起模块系统，然后并行预取每个 `immediately` 行。预取即加载外部脚本，只登记工厂。单行预取失败在这里被吞下：第二层 import 时会重试加载并拥有那次大声失败，因此一个坏行藏不住其他行。`immediately` 是预取标记——不是屏障，不是身份。包声明它，注册表把它带进图行。基础设施插件（connection、runtime、ui-theme、i18n，外加 hmr）声明它；UI 插件则径直按需到达。
+**第一阶段——模块面。**壳在图之上建起模块系统，然后并行预取每个 `immediately` 行。预取即加载外部脚本，只登记工厂。单行预取失败在这里被吞下：第二阶段 import 时会重试加载并拥有那次大声失败，因此一个坏行藏不住其他行。`immediately` 是预取标记——不是屏障，不是身份。包声明它，注册表把它带进图行。基础设施插件（connection、runtime、ui-theme、i18n，外加 hmr）声明它；UI 插件则径直按需到达。
 
-**第二层——插件面。**
+**第二阶段——插件面。**
 
 1. 内核挂载 vendored Loader，在任何 entry 存在之前就把模块系统注入为 `internal`。顺序有讲究：`tree.import` 的裸 import 兜底分支在浏览器里绝不能跑到。
 2. 它为图中每一行创建 entry，外加 app-shell 伪行。装配 entry 是内核自己追加的壳自有代码——向模块系统静态登记，绝不进 host 图——因此与其余一切共乘同一套 entry 生命周期与状态覆盖。
 3. 创建顺序不携带任何语义；fiber 经服务等待激活。
-4. `settled` = 每个 entry 已创建 + `loader.await()` 停稳 + 一次全 ACTIVE 扫描。扫描列出每个 import 失败、FAILED 或 PENDING 的 fiber 及其缺失的服务。它存在的理由：cordis 的 inject 等待没有超时——这次扫描就是大声失败的兜底线。
+4. `settled` = 每个 entry 已创建 + `loader.await()` 完全停稳 + 一次全 ACTIVE 扫描。扫描列出每个 import 失败、FAILED 或 PENDING 的 fiber 及其缺失的服务。它存在的理由：cordis 的 inject 等待没有超时——这次扫描就是大声失败的兜底线。
 5. loading 页的启动状态是经 `internal/status` 对真实 fiber 状态的投影。settled 翻转即一次性切换到真实 UI。
 
 ### 热重载：一个驱动插件，自行监视的 bundle
 
-热重载是否启用是一项组合决策：dev 组合挂载 `client-hmr` 行（一个常规的插件包，由 `--dev` 追加），其 node 半带来 bundle 监视与 SSE 通道；prod 组合不挂载，两者皆无。
+热重载是否启用是一项组合决策：dev 组合挂载 `client-hmr` 行（一个常规的插件包，由 `--dev` 追加），其 node 半带来 bundle 监视与 SSE（Server-Sent Events）通道；prod 组合不挂载，两者皆无。
 
-重建好的 bundle 怎么变成重载信号？hmr 的 node 半自己观察——没有构建器来通知它。它从 `ctx.clientModuleHost.clientPath(id)` 读取图上各行的 bundle 路径，由 HMR 自持的单个定时器对当前图上的每一行做 stat 轮询。新增图行时，顺序固定为先同步取得 stat 基线，再立即调用 `clientModuleHost.rebuilt(id)`：在模块 host 算出图哈希之后、取得基线之前发生的写入会被这次立即重哈希捕获；取得基线之后发生的写入则会留下 stat 差异，供下一次轮询捕获。这避开了 `fs.watchFile`：它以异步首次 stat 建立基线，可能把构造期间的重建静默吸收进基线。监视集合的成员随 `onGraphChanged` 更新；消失的行撤下监视，轮询时缺失的 bundle 则让对应行保持标脏状态，文件重现时即使元数据相同也强制重哈希。mtime/size 变化或行处于标脏状态时，`clientModuleHost.rebuilt(id)` 是重哈希的唯一入口；当 `rev` 真的变了，node 半才在 `GET /plugins/events` 上广播 `rebuilt` 帧——这是一条系统级 SSE（Server-Sent Events）通道，连接即发全量图，变更时发 `rebuilt` 帧，仅供呈现的 wire，永不进会话日志。轮询是刻意选择：inotify 在 weka 网络挂载上不触发，构建侧监视器需要 `--poll` 也是同一原因；轮询间隔是一个经校验的配置字段（默认 500ms），dispose（资源释放）会清掉那一个定时器。重建 bundle 则是任意一个 tsdown watch 进程的事——`scripts/dev-web.ts` 仍作为 watch 构建入口保留，其包清单在启动时扫描 `packages/*/*/package.json` 按 dshClient 发现——构建器与 host 共享零协议。写一半的 bundle 被撕裂读取会自愈：写入完成期间 stat 持续变化，下一个轮询节拍会再次重哈希并广播最终的 rev。
+重建好的 bundle 怎么变成重载信号？hmr 的 node 半自己观察——没有构建器来通知它。它从 `ctx.clientModuleHost.clientPath(id)` 读取图上各行的 bundle 路径，由 HMR 自持的单个定时器对当前图上的每一行做 stat 轮询。新增图行时，顺序固定为先同步取得 stat 基线，再立即调用 `clientModuleHost.rebuilt(id)`：在模块 host 算出图哈希之后、取得基线之前发生的写入会被这次立即重哈希捕获；取得基线之后发生的写入则会留下 stat 差异，供下一次轮询捕获。这避开了 `fs.watchFile`：它以异步首次 stat 建立基线，可能把构造期间的重建静默吸收进基线。监视集合的成员随 `onGraphChanged` 更新；消失的行撤下监视，轮询时缺失的 bundle 则让对应行保持标脏状态，文件重现时即使元数据相同也强制重哈希。mtime/size 变化或行处于标脏状态时，`clientModuleHost.rebuilt(id)` 是重哈希的唯一入口；当 `rev` 真的变了，node 半才在 `GET /plugins/events` 上广播 `rebuilt` 帧——这是一条系统级 SSE 通道，连接即发全量图，变更时发 `rebuilt` 帧，仅供呈现的 wire，永不进会话日志。轮询是刻意选择：inotify 在 weka 网络挂载上不触发，构建侧监视器需要 `--poll` 也是同一原因；轮询间隔是一个经校验的配置字段（默认 500ms），dispose（资源释放）会清掉那一个定时器。重建 bundle 则是任意一个 tsdown watch 进程的事——`scripts/dev-web.ts` 仍作为 watch 构建入口保留，其包清单在启动时扫描 `packages/*/*/package.json` 按 dshClient 发现——构建器与 host 共享零协议。写一半的 bundle 被撕裂读取会自愈：写入完成期间 stat 持续变化，下一个轮询节拍会再次重哈希并广播最终的 rev。
 
 浏览器侧，驱动插件每帧重载一个插件，串行执行：
 
@@ -108,7 +108,7 @@ vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点
 |---|---|---|---|
 | react 家族 / cordis | 平台单例 | 打进壳，已播种 | 永为普通包（绝对基座） |
 | vendored `@cordisjs/plugin-loader` | entry 治理（两侧同一份代码） | 编译期浏览器化，内核挂载 | 不动（vendor 政策） |
-| `dsh-client-modules` | client 模块系统 | lazy CJS 模块表；双层 boot | 永为普通包（模块先于模块） |
+| `dsh-client-modules` | client 模块系统 | lazy CJS 模块表；双阶段 boot | 永为普通包（模块先于模块） |
 | `dsh-client-web` | 壳内核 + AppRoot + app-shell 装配 | 自足（手写状态 store，零插件值 import） | 持续缩小 |
 | `dsh-client-ui-slots` | slot 注册表核心 | 普通包，已播种 | 升格为插件；接收 runtime 的 slots 机件 |
 | `dsh-client-web-react` | ctx↔React 胶水 | 普通包，已播种 | 升格为插件；渲染器安装移入其 apply |
@@ -126,7 +126,7 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
-名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册住 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE 通道迁到 hmr 的 node 半。
+名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册位于 `apps/cli/config/web.cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE（Server-Sent Events）通道迁到 hmr 的 node 半。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
index 1c6a23eec8..d4ff0f5d44 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
 2026-07-27-compiler-independent-typert-model.md: 15641e5f785c5d2daecbfc2d5cffedd64d8384a7
-2026-07-27-compiler-independent-typert-model.zh.md: 7bddd3ffde343346c163f55ef493c32bad1e8314
+2026-07-27-compiler-independent-typert-model.zh.md: acc7be0a5f747dea1ce2fe7497575e50494fd754
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
index 7bddd3ffde..acc7be0a5f 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-直接从 TypeScript AST 拼接 Zod 和反射文本，会把类型分析、业务语义识别与单个生成目标绑在一起。这样的生成器只能回答“这段语法能否生成”，无法提供包、face、公开导出、service、event、对象及其类型关系的标准表示，也无法供静态检查和后续生成目标复用。
+直接从 TypeScript AST 拼接 Zod 和反射文本，会把类型分析、业务语义识别与单个生成目标绑在一起。这样的生成器只能回答「这段语法能否生成」，无法提供包、face、公开导出、服务、事件、对象及其类型关系的标准表示，也无法供静态检查和后续生成目标复用。
 
 host 与 client 属于独立 TypeScript project；把两者放进同一个 `ts.Program` 会合并冲突的 Cordis `Context` 与 `Events` 声明。与此同时，client 类型仍需显式引用 host 类型，因此完全隔离或在两边复制类型都不能表达真实依赖。
 
@@ -16,38 +16,38 @@ host 与 client 属于独立 TypeScript project；把两者放进同一个 `ts.P
 
 TypeGraph 保存开发者写下的计算前类型结构，包括泛型参数与应用、显式继承、conditional、mapped、递归引用和 JSDoc。无法无损表示的可达类型使分析失败；某个 emitter 无法处理已经建模的节点时由该 emitter 失败，而不是把类型展平或降级为 `unknown`。
 
-每个 face 独立拥有 PackageModel 和 TypeGraph。`tsconfig.host.json` 与 `tsconfig.client.json` 的直接 project references 决定 package 的 face 归属，`package.json#exports` 决定公开边界。跨 face 关系只来自源码中的显式 import 或 re-export，并作为独立 link 保留；外部 npm 类型记录为 External，不读取或复制其声明。
+每个 face 独立拥有 PackageModel 和 TypeGraph。`tsconfig.host.json` 与 `tsconfig.client.json` 的直接 project references 决定包的 face 归属，`package.json#exports` 决定公开边界。跨 face 关系只来自源码中的显式 import 或 re-export，并作为独立 link 保留；外部 npm 类型记录为 External，不读取或复制其声明。
 
-PackageModel 识别 Cordis service、event、`@typert object` 引用对象和 `@typert schema` 数据根。service 与 object 只暴露 public instance member，排除 constructor、static、private 和 protected；继承边保留在 TypeGraph 中，不复制为扁平成员。缺少 public property、parameter 或 return 类型标注时，`check` 模式报错，`write` 模式写入 checker 推断结果后重建 project 并再次以严格模式分析。
+PackageModel 识别 Cordis 服务、事件、`@typert object` 引用对象和 `@typert schema` 数据根。服务与 object 只暴露 public instance member，排除 constructor、static、private 和 protected；继承边保留在 TypeGraph 中，不复制为扁平成员。缺少 public property、parameter 或 return 类型标注时，`check` 模式报错，`write` 模式写入 checker 推断结果后重建 project 并再次以严格模式分析。
 
-[`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带 package-face reflection 与可选 Zod schema，并随 Cordis effect 撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
+[`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带包-face reflection 与可选 Zod schema，并在 Cordis effect 执行 dispose（资源释放）时将其撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
 
-包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 契约 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 契约。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
+包产物发布仍通过包导出采用显式 opt-in。`WorkspaceTypertGenerator` 被调用时，会逐一校验请求的 face：host face 必须通过面向用户的 subpath `package/typert` 暴露根产物 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露根产物 `package/lib/typert.client.{js,d.ts}`；它绝不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、类型检查、lint 与文档类型检查增加了全仓 Host 约定检查。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 约定。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
 
 构建期的 `CordisCatalogProjector` 一次消费分析后的 `FaceModel` 与 `TypeGraph`，生成 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md`，以及为 `tool-cordis` 提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` catalog。`tool-cordis` 读取该静态 catalog，运行时不依赖 `ctx.typert`。[`dsh-typert-loader`](../../../../packages/typert/loader/README.md) 与注册表仍是独立的运行时路径：loader 监听 Cordis Loader 配置项生命周期事件，导入显式发布的 `./typert` host 产物，并通过 `ctx.typert` 注册；两者都不是当前 `cordis_inspect` catalog 的数据源。
 
 ## Verification contract
 
-提交内的小型双 face project 对完整类型模型及其源码声明索引做 snapshot。全仓分批分析与直接聚焦分析必须为相同 face 生成模型等价的 `FaceModel` 与 `TypeGraph`。类型级全集和运行时集合比较保证每种 node、target、declaration 与 member discriminant 都来自真实 TypeScript syntax；字段语义矩阵覆盖所有 keyword、type operator、literal value 类目，以及泛型、参数、tuple、mapped modifier、import attributes、abstract、predicate 和 enum initializer 的各个状态。
+仓库内的小型双 face project 对完整类型模型及其源码声明索引做快照。全仓分批分析与直接聚焦分析必须为相同 face 生成模型等价的 `FaceModel` 与 `TypeGraph`。编译期穷尽映射和运行时集合比较保证每种 node、target、declaration 与 member discriminant 都由源码编写的 TypeScript syntax 覆盖；字段语义矩阵覆盖所有 keyword、type operator、literal value 类目，以及泛型、参数、tuple、mapped modifier、import attributes、abstract、predicate 和 enum initializer 的各个状态。
 
 `SyntaxZoo` 中每个 property 的源码类型经 TypeScript printer 标准化后，必须与 TypeGraph 渲染结果逐项相等，随后所有渲染 declaration 再交给 TypeScript 编译。这一层检查节点内部信息是否无损，包括无插值 template literal、带 type argument 的 type query 和受约束 `infer`，不以 discriminant 覆盖或代码覆盖率代替结构等价。
 
-边界用例固定同 face 与跨 face 的显式包导入、跨 face 命名 re-export、精确 export alias、qualified `import()` link 和全局 `@types` External 归属，并拒绝 package 自有 TypeScript 诊断、相对路径越界、`package.json#exports` 之外的引用，以及尚无模型 target 的跨 face namespace re-export。interface declaration merging 显式保留每个 authored part，无法无损表示的其他 merge 失败。
+边界用例固定同 face 与跨 face 的显式包导入、跨 face 命名 re-export、精确 export alias、qualified `import()` link 和全局 `@types` External 归属，并拒绝源自包自有文件的 TypeScript 诊断、相对路径越界、`package.json#exports` 之外的引用，以及尚无模型 target 的跨 face namespace re-export。interface declaration merging 显式保留每个 authored part，无法无损表示的其他 merge 失败。
 
-Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 parse，对不支持的节点逐类断言明确的 `TypertEmitError`。Emitter fixture 对生成的 Zod JavaScript 与 `.d.ts` 文本做快照，执行 JavaScript，并对声明做类型检查。`dsh-typert-registry` 测试固定原子注册、查询、JSON Schema 和 effect 撤销，`dsh-typert-loader` 测试还证明延迟挂载、卸载及未完成 dynamic import 的释放行为。真实 `dsh-tools` 纵切从模型生成 contribution，经运行时注册表加载后，将其服务、事件与关联类型记录同已提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` 对照。全仓 projector 测试重新生成两份 Cordis catalog 文档与 `tool-cordis` API catalog，并要求三份文本同已提交产物逐字节一致。
+Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 parse，对不支持的节点逐类断言明确的 `TypertEmitError`。Emitter fixture（测试前置数据）对生成的 Zod JavaScript 与 `.d.ts` 文本做快照，执行 JavaScript，并对声明做类型检查。`dsh-typert-registry` 测试固定原子注册、查询、JSON Schema 和 effect dispose，`dsh-typert-loader` 测试还证明 dynamic import 仍处于等待状态时的延迟挂载、卸载和 dispose。真实 `dsh-tools` 纵切从模型生成 contribution，经运行时注册表加载后，将其服务、事件与关联类型记录同已提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` 对照。全仓 projector 测试重新生成两份 Cordis catalog 文档与 `tool-cordis` API catalog，并要求三份文本同已提交产物逐字节一致。
 
 ## Alternatives considered
 
-**直接保存 TypeScript AST。** AST 能保留源码写法，但会让每个消费者依赖 compiler 生命周期、node identity 和 checker 上下文，无法形成稳定的架构边界，因此只在提取阶段使用。
+**直接保存 TypeScript AST。** AST 能保留源码写法，但会让每个消费方依赖 compiler 生命周期、node identity 和 checker 上下文，无法形成稳定的架构边界，因此只在提取阶段使用。
 
 **基于 checker 的最终类型生成。** 展平后的 `ts.Type` 便于直接遍历，却丢失泛型、conditional、mapped 和 alias application 的开发者表达，无法满足反射与后续生成需要。
 
-**合并 host/client project 或复制 host 类型。** 合并会污染 Cordis declaration merging；复制会产生第二份类型事实源。独立 face 加显式 cross-face link 保留了 project 隔离与真实引用关系。
+**合并 host/client project 或复制 host 类型。** 合并会污染 Cordis declaration merging；复制会产生第二个类型真源。独立 face 加显式 cross-face link 保留了 project 隔离与真实引用关系。
 
 **让 `dsh-typert-registry` 承担类型解析和跨包合成。** 这会把 TypeScript compiler、Cordis 生命周期和具体 schema 策略重新耦合。注册表保持为生成 artifact 的生命周期容器，复杂分析留在构建期模型。
 
 ## Consequences
 
-新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围并对缺失能力失败。
+新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围，并在缺少相应能力时失败。
 
-包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 契约 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
+包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 约定检查；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 048536527a..3cd70dd035 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
 2026-07-28-directory-picker-capability-seam.md: 01968990db81852dbf965a90fc151bab357ecb55
-2026-07-28-directory-picker-capability-seam.zh.md: ffbb939eabcca3e16711a4cadcadad50660a9e04
+2026-07-28-directory-picker-capability-seam.zh.md: 063ac7b0220c07d5b7caa3d892b7ec17e7e117ee
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index ffbb939eab..063ac7b022 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -1,48 +1,48 @@
-# Agent Note：web GUI 宿主的能力可辨识目录选择 seam
+# Agent Note: web GUI 宿主的能力可辨识目录选择 seam
 
-状态：已实现
+Status: implemented
 
 [English](2026-07-28-directory-picker-capability-seam.md) | 中文
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互契约**，不是同一契约的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的「打开本地文件夹」流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅用于测试的注入 seam）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是另一种交互约定，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库「一切皆插件」的立场。
 
 ## 决策
 
-在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一契约方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
+在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在*交互形态*——压平成统一方法集会逼每个后端伪装另一方的形态。
 
-**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 契约相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
+**client 侧靠 slot 组合，而非按声明分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 约定相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 声明与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的协议信息不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
 
 并入本决策的位置与策略裁决：
 
-- **不用 `ctx.fs` seam。** `packages/fs/` 是面向模型／会话的存储栈（policy 事件、sandbox 可换后端）。骑上去会把 GUI 浏览耦合进模型的限制后端——为模型换 `fs-sandbox` 绝不能改变 GUI 行为——而 OS 事实（home 锚定、隐藏约定）也不是存储原语。picker seam 保持无展示、无模型；`packages/host/` 是它消费方域的家。
-- **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的 provider）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配。
-- **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，"显示隐藏"开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。
-- **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的线上字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。
-- **路径编辑器自我点明，各栏跟随草稿。** 点击即编辑的区域不再是隐形的：栏右端坐着一枚铅笔图标，悬停／聚焦时**整条栏**以编辑器自身的那只框亮起——轮廓与内边距在两种模式下都由栏承载，于是悬停预览的正是点击后出现的那只输入框，区域与输入框互换时也没有任何尺寸变化。编辑器打开期间，各栏跟随草稿，而不是停在它打开那一刻恰好列出的层级——末段对其目录部分所指的层级做前缀过滤，无一匹配的末段解除过滤（还在拼写中的名字不该把正在拼写它的那一栏清空），而其余任何目录部分都会在停顿 250ms 后被扫描，并经由每次导航共用的那套以选中项为锚的双栏落地落定，于是键入路径移动 Miller 视图的方式与 crumb 跳转完全一致——继续键入即下潜、删掉末段即上退——全程不必离开编辑器。**分栏个数才是不变量**：最后一栏永远是路径所指的那一层，其上一层在它旁边，只有展示根会独占一栏。"只要任意一栏碰巧列出了该目录就跳过扫描"是更省事、也是错的规则——删掉一段之后，正在键入的那一层会留在左栏，而它自己的子栏仍立在右边，于是两栏不再读作"我在哪儿、我从哪儿来"。只有最后一栏自己的末段不需要扫描。一种落地形态、两个调用方：提交的路径关闭编辑器并呈现失败，草稿跟随扫描则两者都不做。该扫描是推测性的——键入到一半的目录多数时候读不出来——因此失败时保留最后一次可读的分栏并保持沉默。Enter 仍是权威提交：自提交至落地由它独占视图（同一批按键武装的防抖计时器会被扣住，而不是顶掉这次导航；提交被拒后仍扣住，直到下一次编辑），也只有它把失败呈现出来。有两点是刻意为之。等待以草稿为键，而非以它指名的目录部分为键，于是顶掉在飞扫描的那次按键会重新武装等待，被拒提交之后的编辑也能释放那道扣留；而它读取的分栏是 ref 而非依赖，否则落地会重新武装等待，遇到以不同拼写作答的宿主便会永远扫描下去。以及，走过的路不回退：关闭编辑器——包括取消——都把分栏留在草稿带到的地方，由面包屑指明、Open 的兜底目标随之而动，因为操作者亲眼看着它们移动。若落地卸载了键盘操作者 Tab 停留的那一行，焦点会被重新停回编辑器——Modal 并没有焦点陷阱。另有两条规则保证一次按键只让视图移动一次：这段行走会**等齐两程**，而不套用提交导航的等待上限（推测性扫描没有任何东西在等它，先落单栏再升级恰恰就是它要避免的那次闪动，而且一旦末段按键中止了缓慢的父层级这一程，双栏视图就会永久丢失）；末段也只过滤**最后一栏**——去收窄一个草稿已经走开的分栏，会让视图先因收窄动一次、再因它自己的落地动一次。此外，层级会持续应答产生它的那段目录文本（`scanned`），因为宿主会规范化它收到的东西：`..` 段与 Windows 的正斜杠都会抵达一个自身路径拼写不同的层级；没有这份记忆，这类草稿会每敲一键就重扫一次，而且永远过滤不了。
-- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容右下角（绝不是会挪动布局的一行；截断／错误行占据左下角，并在扫描期间持续渲染），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。行选取被刻意豁免于同一帧规则：选取后立即分栏本身就是其选中态反馈（aria-current、crumb 跟随），而导航除了换栏本身没有任何东西可确认这次点击。三个时序常量——200ms 父层级上限、300ms 静默窗口，以及编辑器的 250ms 草稿停顿——都按本地列举校准；远程部署（每层级一次 RPC，通常 100–400ms）会落在静默窗口之内、crumb 上却没有按下态，而且要先付停顿再付 RPC 分栏才跟上——待远程消费方落地时，三者一并重新审视。
+- **不用 `ctx.fs` seam。** `packages/fs/` 是面向模型／会话的存储栈（policy 事件、沙箱可换后端）。骑上去会把 GUI 浏览耦合进模型的限制后端——为模型换 `fs-sandbox` 绝不能改变 GUI 行为——而 OS 事实（home 锚定、隐藏约定）也不是存储原语。picker seam 保持无展示、无模型；`packages/host/` 是它消费方域的家。
+- **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的提供方）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配器。
+- **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，「显示隐藏」开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。
+- **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的协议字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。
+- **路径编辑器自我点明，各栏跟随草稿。** 点击即编辑的区域不再是隐形的：栏右端坐着一枚铅笔图标，悬停／聚焦时**整条栏**以编辑器自身的那只框亮起——轮廓与内边距在两种模式下都由栏承载，于是悬停预览的正是点击后出现的那只输入框，区域与输入框互换时也没有任何尺寸变化。编辑器打开期间，各栏跟随草稿，而不是停在它打开那一刻恰好列出的层级——末段对其目录部分所指的层级做前缀过滤，无一匹配的末段解除过滤（还在拼写中的名字不该把正在拼写它的那一栏清空），而其余任何目录部分都会在停顿 250ms 后被扫描，并经由每次导航共用的那套以选中项为锚的双栏落地落定，于是键入路径移动 Miller 视图的方式与 crumb 跳转完全一致——继续键入即下潜、删掉末段即上退——全程不必离开编辑器。**分栏个数才是不变量**：最后一栏永远是路径所指的那一层，其上一层在它旁边，只有展示根会独占一栏。「只要任意一栏碰巧列出了该目录就跳过扫描」是更省事、也是错的规则——删掉一段之后，正在键入的那一层会留在左栏，而它自己的子栏仍立在右边，于是两栏不再读作「我在哪儿、我从哪儿来」。只有最后一栏自己的末段不需要扫描。一种落地形态、两个调用方：提交的路径关闭编辑器并呈现失败，草稿跟随扫描则两者都不做。该扫描是推测性的——键入到一半的目录多数时候读不出来——因此失败时保留最后一次可读的分栏并保持沉默。Enter 仍是权威提交：自提交至落地由它独占视图（同一批按键武装的防抖计时器会被扣住，而不是顶掉这次导航；提交被拒后仍扣住，直到下一次编辑），也只有它把失败呈现出来。有两点是刻意为之。等待以草稿为键，而非以它指名的目录部分为键，于是顶掉在飞扫描的那次按键会重新武装等待，被拒提交之后的编辑也能释放那道扣留；而它读取的分栏是 ref 而非依赖，否则落地会重新武装等待，遇到以不同拼写作答的宿主便会永远扫描下去。以及，走过的路不回退：关闭编辑器——包括取消——都把分栏留在草稿带到的地方，由面包屑指明、Open 的兜底目标随之而动，因为操作者亲眼看着它们移动。若落地卸载了键盘操作者 Tab 停留的那一行，焦点会被重新停回编辑器——Modal 并没有焦点陷阱。另有两条规则保证一次按键只让视图移动一次：这段行走会**等齐两程**，而不套用提交导航的等待上限（推测性扫描没有任何东西在等它，先落单栏再升级恰恰就是它要避免的那次闪动，而且一旦末段按键中止了缓慢的父层级这一程，双栏视图就会永久丢失）；末段也只过滤**最后一栏**——去收窄一个草稿已经走开的分栏，会让视图先因收窄动一次、再因它自己的落地动一次。此外，层级会持续应答产生它的那段目录文本（`scanned`），因为宿主会解析它收到的东西：`..` 段与 Windows 的正斜杠都会抵达一个自身路径拼写不同的层级；没有这份记忆，这类草稿会每敲一键就重扫一次，而且永远过滤不了。
+- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会通过协议将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容右下角（绝不是会挪动布局的一行；截断／错误行占据左下角，并在扫描期间持续渲染），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。行选取被刻意豁免于同一帧规则：选取后立即分栏本身就是其选中态反馈（aria-current、crumb 跟随），而导航除了换栏本身没有任何东西可确认这次点击。三个时序常量——200ms 父层级上限、300ms 静默窗口，以及编辑器的 250ms 草稿停顿——都按本地列举校准；远程部署（每层级一次 RPC，通常 100–400ms）会落在静默窗口之内、crumb 上却没有按下态，而且要先付停顿再付 RPC 分栏才跟上——待远程消费方落地时，三者一并重新审视。
 - **符号链接：为可进入性而跟随。** 用 `stat` 探测符号链接（断链／循环→跳过）；面包屑保留操作者导航的逻辑路径，`workspace.create` 在接纳时本就做 realpath 规范化。
-- **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；线上 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口插入为二分查找、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。
-- **全盘可浏览，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。
-- **native 后端保留。** 插件化正是目的：多方都能提供该 seam（Electron 壳可以经自己的对话框 API 提供 `native` 交互）。kind 命名：最初选了 `dialog` 后被放弃——browse 交互同样以对话框呈现（应用内弹窗），这个词起不到判别作用；`native` 命名的是选择器运行的位置。
+- **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；协议中的 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口以二分查找确定插入位置、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。
+- **全文件系统范围，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。
+- **native 后端保留。** 插件化正是目的：多个提供方都能提供该 seam（Electron 壳可以经自己的对话框 API 提供 `native` 交互）。kind 命名：最初选了 `dialog` 后被放弃——browse 交互同样以对话框呈现（应用内弹窗），这个词起不到判别作用；`native` 命名的是选择器运行的位置。
 
 ## 曾考虑的替代方案
 
-- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举契约（hidden 标志、面包屑、home 锚点）不属于存储 seam。
-- **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
-- **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture／测试后端，与促成这项工作的插件教义相悖。
+- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举约定（hidden 标志、面包屑、home 锚点）不属于存储 seam。
+- **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而原生选择器无法实现这些原语。交互差异不可约，故用判别标签。
+- **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture（测试前置数据）／测试后端，与促成这项工作的插件教义相悖。
 - **引入文件管理器／盘符枚举依赖。** 按上文调研否决；依赖政策要求记录于此。
-- **动作标签随状态翻转的"显示隐藏"开关（"隐藏隐藏文件"）。** 否决：会翻转的动作标签在状态与动作之间有歧义，还把否定叠了两层；固定标签加按下态呈现一次说清两者。
+- **动作标签随状态翻转的「显示隐藏」开关（「隐藏隐藏文件」）。** 否决：会翻转的动作标签在状态与动作之间有歧义，还把否定叠了两层；固定标签加按下态呈现一次说清两者。
 - **纯 relatedTarget 失焦取消（不做 mousedown 抑制）。** 否决：Safari 在指针按下时不给按钮聚焦，点击触发的 focusout 因而携带空 `relatedTarget`，会在点击落地前就取消编辑器；编辑期作用的 mousedown 抑制加上锚定卡片的 relatedTarget 守卫才能同时覆盖指针与键盘路径。
-- **在 Miller 视图上方常驻一个路径输入框。** 否决：面包屑本就在回答"我在哪儿"，再常驻一个字段是重复回答，还要从 500px 卡片里挪走一行——那是列需要的高度。图标加悬停亮起的区域，把这个入口放在了已经回答该问题的那一栏上。
-- **每敲一个键就扫描草稿，或只在 Enter 时扫描。** 每键扫描：走完一段路径就是每个字符一次列举，其中多数目录操作者只是路过而非停留。只在 Enter 时扫描（最初落地的行为）：整个编辑过程中各栏与所键入文本各说各话——正是本条所回应的抱怨。250ms 的停顿把扫描收敛为"键入真正停下来的每个目录一次"。
-- **前缀无一匹配时清空该栏（最初落地的行为）。** 否决：名字敲到一半时"无匹配"才是常态，于是恰恰在操作者需要它确认名字时把栏清空了；解除过滤保住了层级的可读性，代价只是短暂的宽松。
-- **在 `DirectoryListing` 上增设线上 `separator` 字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 seam 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排线上变更。
+- **在 Miller 视图上方常驻一个路径输入框。** 否决：面包屑本就在回答「我在哪儿」，再常驻一个字段是重复回答，还要从 500px 卡片里挪走一行——那是列需要的高度。图标加悬停亮起的区域，把这个入口放在了已经回答该问题的那一栏上。
+- **每敲一个键就扫描草稿，或只在 Enter 时扫描。** 每键扫描：走完一段路径就是每个字符一次列举，其中多数次列举针对的目录，操作者只是在键入时经过，并未停驻。只在 Enter 时扫描（最初落地的行为）：整个编辑过程中各栏与所键入文本各说各话——正是本条所回应的抱怨。250ms 的停顿把扫描收敛为「键入真正停下来的每个目录一次」。
+- **前缀无一匹配时清空该栏（最初落地的行为）。** 否决：名字敲到一半时「无匹配」才是常态，于是恰恰在操作者需要它确认名字时把栏清空了；解除过滤保住了层级的可读性，代价只是短暂的宽松。
+- **在 `DirectoryListing` 上增设 `separator` 协议字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 seam 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排协议变更。
 
 ## 后果
 
 - `cordis.yml` 决定交互形态；`apps/cli` 挂 [`-auto` 选择器](../feature/2026-07-29-directory-picker-adaptive-default.md)，它在启动时判定宿主处境并自行挂载 `-native` 或 `-browse`，一行仍同时切换后端与 UI；直接组合某个后端行即固定交互。
 - 协议新增 `host.listDirectory`／`host.createDirectory` 与四个错误码；connection fixture 提供确定性浏览树与确定性 `pickDirectory` 路径供无密钥组装测试使用。
-- 未来的新交互（或提供 `native` 交互的 Electron 实现）只是一个双面后端包——无需网关手术，也不动 ui-workspace。
+- 未来的新交互（或提供 `native` 交互的 Electron 提供方）只是一个双面后端包——无需网关手术，也不动 ui-workspace。
 - `ApiProxyDefaults.pickDirectory`（仅测试注入）删除；测试像提供其他服务一样提供 stub `ctx.directoryPicker`。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
index 2bef24442d..dba9bcbee1 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
 2026-07-29-terminal-llm-stream-failures.md: 1e26973360f07c212016c6a44103448a3510a75b
-2026-07-29-terminal-llm-stream-failures.zh.md: d3eeb0534f6cb8d4d1ad167cca089314eb02b513
+2026-07-29-terminal-llm-stream-failures.zh.md: f4fd4e0e2a555d87394aa43d8b3a9712ee369eb2
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
index d3eeb0534f..f4fd4e0e2a 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
@@ -4,34 +4,34 @@ Status: implemented
 
 [English](2026-07-29-terminal-llm-stream-failures.md) | 中文
 
-本说明仅取代[有界 LLM 请求恢复](2026-06-21-bounded-llm-request-recovery.md)与[调用后上下文溢出恢复](2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)中关于抛出错误身份和调用局部 sidecar 的机制。上述说明继续规定结构化失败事实、重试策略、持久尝试与压缩恢复。
+本说明仅取代[有界 LLM（大语言模型）请求恢复](2026-06-21-bounded-llm-request-recovery.md)与[调用后上下文溢出恢复](2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)中关于抛出错误身份和调用局部 sidecar 的机制。上述说明继续规定结构化失败事实、重试策略、持久尝试与压缩（compaction）恢复。
 
 ## Problem
 
-适配器失败曾有两种公共表示：选择、分发、iterator 构造或迭代抛出的异常，以及带内的 `finish { kind: 'error' | 'aborted' }`。`LlmService` 会在以 stream 为 key 的 sidecar 中标记抛出对象，使 agent loop 能将其与 middleware 和消费方失败区分开。消费方仍需用 catch 包围迭代、signal 检查、chunk 日志记录和组装；正确性因此取决于证明是哪条语句抛错，并查询附着于精确返回 iterable 的元数据。
+适配器失败曾有两种公共表示：选择、分发、iterator 构造或迭代抛出的异常，以及带内的 `finish { kind: 'error' | 'aborted' }`。`LlmService` 会在以流为键的 sidecar 中标记抛出对象，使 agent loop（智能体循环）能将其与 middleware 和消费方失败区分开。消费方仍需用 catch 包围迭代、signal 检查、分片日志记录和组装；正确性因此取决于证明是哪条语句抛错，并查询附着于所返回的那个 iterable 的元数据。
 
-重试策略也采用同样的间接归属。尽管 `prepareCall()` 已捕获服务注册，策略仍要在分发后通过 stream sidecar 查找。因此，由 wrapper 提供服务的路由与由适配器提供服务的路由共用一个不透明查询 API，尽管两者的权威不同。
+重试策略也采用同样的间接归属。尽管 `prepareCall()` 已捕获服务注册，策略仍要在分发后通过流 sidecar 查找。因此，由包装层提供服务的路由与由适配器提供服务的路由共用一个不透明查询 API，尽管两者的权威不同。
 
 ## Decision
 
-`LlmService` 是一次适配器尝试的规范化边界。它只捕获最终适配器选择、同步分发、iterator 构造与 `next()` 失败，将抛出值转换为不可变 `LlmFailure`，并发出一个终止 `finish`。调用方取消或 `ABORTED` 失败选择 aborted reason；其他适配器失败选择 error。适配器也可以直接发出这两种终止 reason。
+`LlmService` 是一次适配器尝试的规范化边界。它只捕获最终适配器选择、同步分发、iterator 构造与 `next()` 失败，将抛出值转换为不可变 `LlmFailure`，并发出一个终止 `finish`。调用方取消或 `ABORTED` 失败选择 aborted 结束原因；其他适配器失败选择 error 结束原因。适配器也可以直接发出任一终止原因。
 
-适配器所属的 catch 会在每个 chunk 被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、chunk 消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能留下未关闭块，因此流 invariant 只允许终止 error 或 aborted finish 带有未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。
+适配器所属的 catch 会在每个分片被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、分片消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能留下未关闭块，因此流 invariant 只允许在终止 finish 的结束原因为 error 或 aborted 时存在未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。
 
 `PreparedLlmCall` 公开随其配置和注册捕获的不可变重试策略。一次性句柄复用与配置不匹配仍是同步的 `INVALID_PREPARED_CALL` 误用错误。完全由 `llm/stream` middleware 提供服务的路由没有准备完成的注册，因此也没有服务策略。
 
-agent loop 只消费一种失败表示。它不再使用分类 catch，而是直接迭代并记录 chunk、检查终止 finish，再把其中的失败事实与准备完成的策略传给 `agent/request-error`。公共的 `isLlmAdapterFailure`、`llmFailureOf` 和 `llmRetryPolicyOf` sidecar API 不再存在。
+agent loop 只消费一种失败表示。它不再使用分类 catch，而是直接迭代并记录分片、检查终止 finish，再把其中的失败事实与准备完成的策略传给 `agent/request-error`。公共的 `isLlmAdapterFailure`、`llmFailureOf` 和 `llmRetryPolicyOf` sidecar API 不再存在。
 
 ## Alternatives considered
 
-**保留调用局部错误标记。** 这会保留抛出对象身份，但要求每个消费方捕获一段包含自身易失败工作的区域，并让分类依赖 iterable wrapper 的身份。原始错误对象在持久恢复中没有作用；规范化事实才是有用的边界值。
+**保留调用局部错误标记。** 这会保留抛出对象身份，但要求每个消费方捕获一段包含自身易失败工作的区域，并让分类依赖 iterable 包装层的身份。原始错误对象无法在恢复中发挥持久作用；规范化事实才是有用的边界值。
 
-**要求所有适配器发出失败 chunk，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会重复归属，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。
+**要求所有适配器发出失败分片，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会造成职责重复，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。
 
-**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。
+**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、会话追加、取消或组装失败。分类属于发起适配器调用的边界。
 
 **在流式输出前返回 `Result`。** 流前结果无法表示部分输出之后的传输失败，除非增加第二套响应生命周期。现有终止 chunk 已能表示早期和后期尝试结果。
 
 ## Consequences
 
-所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。
+所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以流为键的元数据。准备完成的调用显式携带策略，而仅由 middleware 提供服务的路由仍明确没有策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
index 752dc0f1aa..5c0849d9f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
 2026-07-30-adapter-owned-max-token-defaults.md: a522848fd4482f84859e587505b6a5e6f5c72d60
-2026-07-30-adapter-owned-max-token-defaults.zh.md: 8db6a06199fc1c4e73c86492d12dc86edafe8c7e
+2026-07-30-adapter-owned-max-token-defaults.zh.md: 5d5b4007d124028f1703fb34a7b50815cbc0a99a
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
index 8db6a06199..5d5b4007d1 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
@@ -10,7 +10,7 @@ LLM（大语言模型）适配器可以序列化显式的 `GenerateOptions.maxTo
 
 ## Decision
 
-`LlmResolvedModelInfo.defaultMaxTokens` 携带一条确切提供方／模型路由的可选单次请求输出上限，该值由适配器配置。`LlmService` 将其校验为正安全整数，并且仅在调用方省略值时才填入 `LlmCallConfig.maxTokens`。准备后的调用会将已填入的 `maxTokens` 和 `reasoningEffort` 字段标记为适配器默认值；显式请求值或 Agent 选项不带该标记，因此优先且不会被自动调整。
+`LlmResolvedModelInfo.defaultMaxTokens` 携带一条确切提供方／模型路由的可选单次请求输出上限，该值由适配器配置。`LlmService` 将其校验为正的安全整数，并且仅在调用方省略值时才填入 `LlmCallConfig.maxTokens`。准备后的调用会将已填入的 `maxTokens` 和 `reasoningEffort` 字段标记为适配器默认值；显式请求值或 agent 选项不带该标记，因此优先且不会被自动调整。
 
 agent loop 仍在记录 `request/header` 前准备调用，因此生效配置及其适配器默认值来源会在分派前成为持久请求事实。下一次 `agent/request` waterfall（瀑布式事件）前，agent loop 会从提议中移除带标记字段，随后精确模型解析会再次填入当前路由的默认值。因此，切换提供方／模型不会把前一个适配器的默认值误当成显式覆盖，而显式对话值则会保留。直接调用 `LlmService.stream()` 时，也会在最终适配器边界解析同一默认值。该字段是请求默认值，而非模型输出硬上限；保留提供方持有默认值的适配器会省略它。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
index 2efe235e28..7254478110 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.md
 2026-07-30-client-locale-full-rollout.md: 09baf5876029295f7a80b6a0fe6a6395d98f406c
-2026-07-30-client-locale-full-rollout.zh.md: 806916aea15a21fd24fdfc4654976b3c4577a675
+2026-07-30-client-locale-full-rollout.zh.md: a2f9b619be9928a713d5dbf527d7c2278e84bd1f
diff --git a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
index 806916aea1..a2f9b619be 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`）落地后，只有四个先行包接入；其余 client 包的文案仍是硬编码的中英混杂字面量。全量迁移需要几个先行包没有触及的机制与边界决定：注册期文本（导航行、视图 tab 的 label）在语言切换时如何刷新；zero-cordis 的 ui-primitives 原子组件如何拿到文案；哪些字符串**刻意不**本地化——没有记录的边界会诱使后来者"补完"翻译。
+typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`）落地后，只有四个先行包接入；其余 client 包的文案仍是硬编码的中英混杂字面量。全量迁移需要几个先行包没有触及的机制与边界决定：注册期文本（导航行、视图 tab 的 label）在语言切换时如何刷新；zero-cordis 的 ui-primitives 原子组件如何拿到文案；哪些字符串**刻意不**本地化——没有记录的边界会诱使未来的 agent（智能体）「补完」翻译。
 
 ## Decision
 
@@ -14,32 +14,32 @@ typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`
 
 **组件文案走标准 `t` 席位；深层子组件用 prop 下传**，类型写 `XxxProps['t']`。字典规范形态不变：`zh satisfies Record<string, string>` 为 key 源、`en satisfies Record<XxxKey, string>` 锁双语平衡。
 
-**zero-cordis 原子组件（ui-primitives）文案 props 化**：`HoverCard` 的 `copyLabel`/`copiedLabel`、`TerminalBlock`/`JsonTree` 的 `labels`、`CodeBlock` 的 `copyLabel`/`copiedLabel`、`MarkdownText` 的 `codeLabels`、`JsonBlock` 的 `truncatedLabel`、`ConnectionBanner` 的 `label`、`Modal` 的 `closeLabel`——默认值即原硬编码字符串，不传 props 的消费者渲染逐字节不变。已本地化的插件从自己的 `t` 席位传字典驱动的 label；传对象 props 的调用点按 `t` 身份 memo（`MarkdownText` 的组件表按 `codeLabels` 身份缓存）。
+**zero-cordis 原子组件（ui-primitives）文案 props 化**：`HoverCard` 的 `copyLabel`/`copiedLabel`、`TerminalBlock`/`JsonTree` 的 `labels`、`CodeBlock` 的 `copyLabel`/`copiedLabel`、`MarkdownText` 的 `codeLabels`、`JsonBlock` 的 `truncatedLabel`、`ConnectionBanner` 的 `label`、`Modal` 的 `closeLabel`——默认值即原硬编码字符串，不传 props 的消费方渲染逐字节不变。已本地化的插件从自己的 `t` 席位传字典驱动的 label；传对象 props 的调用点按 `t` 身份 memo（`MarkdownText` 的组件表按 `codeLabels` 身份缓存）。
 
 **不翻译边界（刻意决定，不是欠账）：**
 
-- **错误/失败类字符串一律英文**：client 自产的兜底串（`command failed`、plan 切换失败）、RpcError message、wire 透出的 `error.message (code)` 原样呈现。
-- **设计字面量不进字典**：tool 行 variant 标题（Think/Bash/…）、SYSTEM/USER 类 kind 徽标、Plan chip 字标、StatsLine 全部指标——中英界面显示一致。
+- **错误/失败类字符串一律英文**：client 自产的兜底串（`command failed`、plan 切换失败）、RpcError 消息、wire 透出的 `error.message (code)` 原样呈现。
+- **设计字面量不进字典**：工具行 variant 标题（Think/Bash/…）、SYSTEM/USER 类 kind 徽标、Plan chip 字标、整个 StatsLine——中英界面显示一致。
 - **ui-trajectory 整包缓做**（开发者检查面，术语密集，单独裁决）。
 - **boot 文案保持硬编码**（AppRoot 渲染早于 locale 服务可用）。
 
 **派生层保持纯函数，本地化只在渲染层**：ui-workspace 的 `relativeTime` 返回结构化 `{unit, n}` 由渲染组合字典模板；blank 会话/未分组桶的存储标题不变，渲染按 `blank` 标志/`workspaceId` 缺席替换本地化文案；**搜索态 blank 行一律排除**（双语标题无法与单语查询稳定匹配）。日期不引 Intl：格式模板进字典（消息时钟 `clock.md`/`clock.ymd`，workspace hover `date.ymd`），格式化函数吃 `t` 参数保持纯。
 
-**测试与 e2e 口径**：`makeTranslate(...dicts)`（dsh-client-test-runtime）镜像服务查找链（首个命中字典胜出、key 兜底、`{name}` 插值），组件测试的 `t` 桩统一用它并以真实 props 席位定型。web e2e 统一 `newEnglishPage`（boot 前钉 `dsh.locale=en`），built-boot snapshot 同样钉 en——golden 对语言迁移免疫；settings 语言切换用例绕开该 helper 并开启 `zh-CN` 浏览器，因为初始 locale 跟随 `navigator`（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)）。
+**测试与 e2e 口径**：`makeTranslate(...dicts)`（dsh-client-test-runtime）镜像服务查找链（首个命中字典胜出、key 兜底、`{name}` 插值），组件测试的 `t` 桩统一用它并以真实 props 席位定型。web e2e 统一通过 `newEnglishPage` 打开（boot 前钉 `dsh.locale=en`），built-boot 快照同样钉 en——预期输出不受本地化迁移影响；settings 语言切换用例绕开该 helper 并开启 `zh-CN` 浏览器，因为初始 locale 跟随 `navigator`（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)）。
 
-[settings/locale/theme 分层 Note](../../proposed/architecture/2026-07-25-client-settings-locale-theme.md) 中"apply 层订阅 `locale/change` 重注册刷新 label"的机制已被本决定取代（thunk + revision 生命周期）。
+[settings/locale/theme 分层 Note](../../proposed/architecture/2026-07-25-client-settings-locale-theme.md) 中「apply 层订阅 `locale/change` 重注册刷新 label」的机制已被本决定取代（thunk + revision 生命周期）。
 
 ## Alternatives considered
 
-- **label 保持 string、语言切换时重注册**（先行包的旧形态）：boot 每包一次注册已很重，`locale/change` 监听者重注册会放大成风暴；ledger version 抖动还会击穿一切按 version 缓存的投影。thunk 把刷新成本移到读取点，读取点本来就跟随 revision。
-- **给 ui-primitives 造 locale context/注入通道**：破坏 zero-cordis 边界（原子组件从此依赖运行时），且强迫未本地化消费者（ui-trajectory）陪跑。props 化让每个消费者独立决定。
+- **label 保持 string、语言切换时重注册**（先行包的旧形态）：boot 已经为每个包注册一次，`locale/change` 监听者重注册会放大成风暴；ledger version 抖动还会击穿一切按 version 缓存的投影。thunk 把刷新成本移到读取点，读取点本来就跟随 revision。
+- **给 ui-primitives 造 locale 上下文/注入通道**：破坏 zero-cordis 边界（原子组件从此依赖运行时），且强迫未本地化消费方（ui-trajectory）陪跑。props 化让每个消费方独立决定。
 - **错误串进字典**：错误面是排障面，英文原样最利于搜索与上报比对；且 wire 透出串本就不可译，半译反而制造混合语言。
 - **日期用 `toLocaleString()`/Intl**：跟随浏览器/OS 语言而非应用语言，切换后必然产生混合文本；字典模板量小且与消息时钟同构。
-- **blank 行参与搜索（匹配本地化标题或存储标题）**：任一选择都在某个语言下"看得见搜不到"；占位行本无信息量，整体排除语义最稳。
+- **blank 行参与搜索（匹配本地化标题或存储标题）**：任一选择都在某个语言下「看得见搜不到」；占位行本无信息量，整体排除语义最稳。
 
 ## Consequences
 
 - 语言切换全 UI 即时刷新且零重注册；新包接入 = 字典 + declare-merge + `locale: NS` 三步，无手写胶水。
-- 代价：list label 的消费方必须知道 `resolveSlotLabel`（裸读 `options.label` 拿到函数）；类型上 `SlotLabel` 已挡住多数误用。
-- ui-primitives 的中文默认值在英文语言下依旧是中文，**直到消费点传 label**——未迁移包（ui-trajectory 的 JsonTree）显示英文默认恰好符合其整包英文现状。
+- 代价：list label 的消费方必须知道 `resolveSlotLabel`（裸读 `options.label` 现在可能拿到函数）；类型上 `SlotLabel` 已挡住多数误用。
+- ui-primitives 的中文默认值在英文语言下依旧是中文，**直到消费方传入 labels**——未迁移的 JsonTree 消费方（ui-trajectory）显示其英文默认值，恰好符合其整包英文现状。
 - e2e 英文钉死意味着 zh 默认态主要靠包级组件测试与 settings 语言切换用例覆盖，浏览器 e2e 不再验证 zh 文案。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml
index 330a279b35..3b769c20db 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.md
 2026-07-30-command-row-copy-contract.md: f6d5199389b3907780c501894e2861e6add85e77
-2026-07-30-command-row-copy-contract.zh.md: 4afaf31640c07e88765060681739f262f322769e
+2026-07-30-command-row-copy-contract.zh.md: 250c8090e357c02b68bdf9b75efac0cd163c6343
diff --git a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md
index 4afaf31640..250c8090e3 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md
@@ -1,16 +1,16 @@
-# Agent Note: Command row copy is split between the row and the handler
+# Agent Note: 命令条目文案分别由条目与 handler 负责
 
 Status: implemented
 
 [English](2026-07-30-command-row-copy-contract.md) | 中文
 
-## Problem
+## 问题
 
-Web 命令行由一对落库的[命令生命周期事件](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)渲染出 `标题 · 摘要`：标题是由 `command/run` 重建的分派命令行（`/permission workspace-write`），摘要是 `command/done` 的原样 `text`（`Permission preset: workspace-write.`）。两半各自成文、互不知情，于是一行里命令名出现两次、参数也出现两次——最糟的一例正是用户每次用 Access chip 切换权限时得到的那一行。
+Web 命令条目由一对落库的[命令生命周期事件](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)渲染出 `标题 · 摘要`：标题是由 `command/run` 重建的分派命令行（`/permission workspace-write`），摘要是 `command/done` 的原样 `text`（`Permission preset: workspace-write.`）。两半各自成文、互不知情，于是一行里命令名出现两次、参数也出现两次——最糟的一例正是用户每次用 Access chip 切换权限时得到的那一行。
 
-## Decision
+## 决策
 
-命令行两半的职责互不重叠，各自只按自己那一半来写。
+命令条目两半的职责互不重叠，各自只按自己那一半来写。
 
 行标题就是裸命令名——没有 `/`，也没有参数。`/` 属于编辑器的输入语法，不属于一条已落定的记录；参数也不该由这一行来报告：摘要已经说清了这条命令做了什么。对于 `command/run` 那一页已滑出客户端窗口的跨窗口节点，`GenericCommandCard` 仍保留 `命令` 兜底标题。
 
@@ -18,9 +18,9 @@ Web 命令行由一对落库的[命令生命周期事件](../../proposed/archite
 
 这条规则禁的是*标签*，不是用词。`Permission preset: workspace-write.` 之所以出局，是因为 `Permission preset:` 是给一个值加的题头，而这个题头正是标题本身。恰好含有命令名的领域名词不是题头，因此保留：`/plan` 仍返回 `Plan mode off.` 与 `Plan mode on. Use /plan off to leave.`（`plan · Plan mode off.` 说的是那个模式，句尾是一条指引，不是回声），`/goal` 仍返回 `Goal cleared.`。真正被这条规则拦下的，是 handler 在自己的值前面写出 `<命令名> <名词>：` 的那一类。
 
-日志本身未变：`command/run` 保留结构化的 `name`／`args` 拆分，因此更丰富的已注册命令行仍可从同一个节点渲染参数，无需第二条数据通道。
+日志本身未变：`command/run` 保留结构化的 `name`／`args` 拆分，因此更丰富的已注册命令条目仍可从同一个节点渲染参数，无需第二条数据通道。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **保留分派命令行作标题，只缩短落定文案。** 参数仍会出现在分隔点两侧（`permission workspace-write · preset workspace-write`），而这正是被指出的重复。
 
@@ -28,8 +28,8 @@ Web 命令行由一对落库的[命令生命周期事件](../../proposed/archite
 
 **由这一行从落定文案里剥掉开头的命令名。** 呈现层会悄悄改写 handler 写就的文案，而任何换一种措辞表达结果的 handler 都会让这套启发式失效。
 
-**彻底禁止命令名出现在自己的落定文案里，并把 `/plan`、`/goal` 一并改写。** 这种更宽的禁令代价大于收益：无论在行上还是作为独立的 TUI 通知，`Plan mode off.` 与 `Goal cleared.` 都是这些结果最清楚的句子，而满足"禁名字"所需的缩写（`off.`、`cleared.`）读起来只是残句。值得去掉的冗余是题头。
+**彻底禁止命令名出现在自己的落定文案里，并把 `/plan`、`/goal` 一并改写。** 这种更宽的禁令代价大于收益：无论在行上还是作为独立的 TUI 通知，`Plan mode off.` 与 `Goal cleared.` 都是这些结果最清楚的句子，而满足「禁名字」所需的缩短形式（`off.`、`cleared.`）读起来只是残句。值得去掉的冗余是题头。
 
-## Consequences
+## 后果
 
-每一条命令行都变短了，而且这条规则可扩展：新命令的作者写结果时无需知道由哪个界面渲染，任何界面也都不必再去重。代价是分派参数离开了折叠行——命令仍在执行时，行上只有名字和 `执行中…`——以及"不加题头"这条规则是靠评审执行的约定，而非门禁。`/permission` 的文案由 permission 包的命令测试钉住，装配后的行文案由 [seeded-history](../../../../apps/web/tests/snapshots/seeded-history/command-row.expected.md) web 预期输出钉住：因为 `/permission` 完全在 host 上执行，它能无密钥地抵达一条真实的落定命令行。
+每一条命令条目都变短了，而且这条规则可扩展：新命令的作者写结果时无需知道由哪个界面渲染，任何界面也都不必再去重。代价是分派参数离开了折叠行——命令仍在执行时，行上只有名字和 `执行中…`——以及「不加题头」这条规则是靠评审执行的约定，而非门禁。`/permission` 的文案由 permission 包的命令测试钉住，装配后的行文案由 [seeded-history](../../../../apps/web/tests/snapshots/seeded-history/command-row.expected.md) web 预期输出钉住：由于 `/permission` 完全在 host 上执行，该预期输出无需密钥即可覆盖一条真实的已落定命令条目。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index 2b16888d38..b4863f08b5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
 2026-07-30-followup-enqueue-and-owned-runs.md: 54f4af75eeb29b06504fa2629b0665f3e5f4c4ee
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: 62c0d998a8bf94df8cabfccf23ea8b2a4da92c4d
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: 51f82b7c703be13165e0cd7d7b354ea14e3a965e
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index 62c0d998a8..51f82b7c70 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -14,11 +14,11 @@ Status: implemented
 
 保留 `Agent.followup(message): void`，使其仅执行入队。`Agent.whenIdle()` 和 `agent/status` 仍用于观察整个 agent 的生命周期；二者都不结算单条消息。Inbox 持久性会记录已标识消息及其准入或取消，但不会把后续输出归属于该消息。
 
-底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
+底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 流式传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
 
 只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
 
-ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误 reject 提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或资源释放并列。
+ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或dispose（资源释放）并列。
 
 Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index e556108299..53eb3cefe5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
 2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
-2026-07-30-package-manager-native-repository-cache.zh.md: ac72e5dc4ffa764e1dc430764a6f52fc083d32a4
+2026-07-30-package-manager-native-repository-cache.zh.md: a4ad07c42eec7b05f51b18aaf54fcfedaa4d4b3c
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index ac72e5dc4f..a4ad07c42e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-独立运行的 Harness 应用不能依赖开发者自有的 SDK 工程来声明并安装仓库依赖。因此，加载配置中的 GitHub 仓库需要一道持久的获取、准备与缓存边界；但如果在 DSH 内实现 Git 传输、托管来源语法、包（package）准备流程和内容存储，就会重复实现包管理器。若要求用户另行安装包管理器，则只需修改配置即可使用的功能还会依赖宿主环境的额外配置。
+独立运行的 Harness 应用不能依赖开发者自有的 SDK 工程来声明并安装仓库依赖。因此，加载配置中的 GitHub 仓库需要一道持久的获取、准备与缓存边界；但如果在 DSH 内实现 Git 传输、托管来源语法、包准备流程和内容存储，就会重复实现包管理器。若要求用户另行安装包管理器，则只需修改配置即可使用的功能还会依赖宿主环境的额外配置。
 
 缓存还需要明确更新标识。若没有独立的刷新协议，可变分支名无法既永久缓存，又反映后续 commit。
 
@@ -16,7 +16,7 @@ vendor 中的 `@cordisjs/plugin-loader/repository` 导出 `RepositoryCache`：
 
 Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前 Node 可执行文件调用该包的 JavaScript 入口。它绝不探测全局可执行文件，也不经 Corepack 调用。每次缓存未命中都会创建一个隔离工程，其中只有一个名为 `repository` 的依赖；Git 与 GitHub 来源的解析和获取、pnpm 自身的内容寻址 store、依赖安装，以及仓库依赖图中的生命周期脚本均由 pnpm 负责。
 
-隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证契约。
+隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证约定。
 
 缓存项以精确 specifier 的 SHA-256 命名。同一进程内针对相同 specifier 的并发请求共享一项任务。安装在同级临时目录中进行；只有安装成功且存在包目录和标记时，系统才会把暂存目录原子重命名为最终键对应的目录。失败的暂存目录会被删除；如果另一进程已发布有效项，则以该项为准。后续进程会先校验标记与包目录，再返回稳定的 `node_modules/repository` 路径。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
index 7665dc3290..0bb3092b67 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
 2026-07-30-session-end-seed-log-boundary.md: 26cd67ccbfdf5dfc62e44a53c877acf6d2fee34a
-2026-07-30-session-end-seed-log-boundary.zh.md: 5ce12681da3ee46cc7c69aa6d432d25712db17fd
+2026-07-30-session-end-seed-log-boundary.zh.md: 70391ba8b629694cc83f1960ea3fdd94cd32f032
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
index 5ce12681da..70391ba8b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-拥有独立开／闭括号的插件无法区分一个已死的标记和一个存活的标记。`compact/start` … `compact/end` 就是已发布的实例：当接手一份日志、而它最后的压缩事件是一个未配对的 `compact/start` 时，"上一个写入方在压缩中途死掉了"与"此刻正有一次压缩在运行"在存储历史中是逐字节相同的。所有方只能二选一：拒绝压缩一份其实空闲的日志（把会话卡死），或者在一份确实繁忙的日志上继续压缩。
+在会话日志中拥有独立开／闭括号的插件无法区分一个已死的标记和一个存活的标记。`compact/start` … `compact/end` 就是已发布的实例：当接手一份日志、而它最后的压缩（compaction）事件是一个未配对的 `compact/start` 时，「上一个写入方在压缩中途死掉了」与「此刻正有一次压缩在运行」在存储历史中是逐字节相同的。该括号所有方只能二选一：拒绝压缩一份其实空闲的日志（把会话卡死），或者在一份确实繁忙的日志上继续压缩。
 
 日志中没有任何东西标出继承历史在哪里结束。`session/created`、`session/disposed` 与 `session/flush` 是 cordis 运行时信号，不是日志事件；`agent/session-start` 只发射不落盘。`Session.firstLiveSeq` 本来就精确地持有这个答案——本生命周期第一次自有写入的 seq——但只存在于内存中，因此读取存储字节的消费方看不到它。
 
@@ -14,13 +14,13 @@ Status: implemented
 
 ## Decision
 
-`Session` 的构造函数紧接显式传入的构造种子（包括空种子）之后追加仅日志事件 `session/end-seed`，作为带种子会话的第一次实时写入，位置正是 `firstLiveSeq` 指出的 seq。该事件是那个字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答本生命周期的写入从哪里开始，`session/end-seed` 则为只持有存储字节的消费方回答同一问题。它的 payload 为空——位置与 `time` 承载全部含义——并且不是 `SurfaceEventType`，因此不产生消息，也无法扰动派生历史。这个 seq-0 标记把从空日志恢复的会话与真正的全新会话区分开来，从而防止恢复期间应用新会话默认值。
+`Session` 的构造函数紧接显式传入的构造种子（包括空种子）之后追加仅日志事件 `session/end-seed`，作为带种子会话的第一次自有写入，位置正是 `firstLiveSeq` 指出的 seq。该事件是那个字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答本生命周期的写入从哪里开始，`session/end-seed` 则为只持有存储字节的消费方回答同一问题。它的 payload 为空——位置与 `time` 承载全部含义——并且不是 `SurfaceEventType`，因此不产生消息，也无法扰动派生历史。这个 seq-0 标记把从空日志恢复的会话与真正的全新会话区分开来，从而防止恢复期间应用新会话默认值。
 
 括号所有方按位置读取它：在 `session/end-seed` 之前的未配对开启标记具有更小的 seq，来自构造种子，并且属于一个已结束的生命周期。核心写入该边界但不从中读取任何内容；每个括号的词汇表仍归其所属插件，因此在没有消费方来塑形之前，核心不会先发布谓词辅助函数。
 
-选择构造函数，是因为它是每一个带种子会话都必经的唯一收窄处。全部六个入口都会到达它：`agents.resume()`、在已持久化 id 上的配置驱动启动（`restoreOrCreateConfigured`）、`sessions.fork()`、子代理 fork 子会话、`coordinator.adopt()` 的实时前缀路径，以及裸的 `sessions.create(id, {seed})`。在持久化加载时写入的边界会漏掉两条 fork 路径——而一个继承了仍在运行的父会话开放 `compact/start` 的 fork 子会话，恰恰是必须可判定的场景。在 loop 启动时写入的边界会漏掉 `fork()` 与 `adopt()`，并且不得不在 `SessionStartSource: 'startup'` 上触发——那正是 fork 子会话发布的取值，于是该字段将不再具有区分力。
+选择构造函数，是因为它是每一个带种子会话都必经的唯一收窄处。全部六个入口都会到达它：`agents.resume()`、在已持久化 id 上的配置驱动启动（`restoreOrCreateConfigured`）、`sessions.fork()`、subagent fork 子会话、`coordinator.adopt()` 的实时前缀路径，以及裸的 `sessions.create(id, {seed})`。在持久化加载时写入的边界会漏掉两条 fork 路径——而一个继承了仍在运行的父会话开放 `compact/start` 的 fork 子会话，恰恰是必须可判定的场景。在 loop 启动时写入的边界会漏掉 `fork()` 与 `adopt()`，并且不得不在 `SessionStartSource: 'startup'` 上触发——那正是 fork 子会话发布的取值，于是该字段将不再具有区分力。
 
-两条守卫让这个标记保持精确。省略种子时不写入任何内容，因为这是全新会话。种子本身已以该事件结尾时不会重复标记，这让写入具备幂等性。幂等性是承重的，而不是为了整洁：每次绑定到 Agent 的冷会话接手都会经过 `agentFor()`；没有这条守卫，重复的控件操作即使没有执行任何工作，也会让日志增长。只执行检查的 `session.history` 与 `session.fork` 源端路径不会在源会话中创建这条边界。
+两条守卫让这个标记保持精确。省略种子时不写入任何内容，因为这是全新会话。种子本身已以该事件结尾时不会重复标记，这让写入具备幂等性。幂等性是承重的，而不是为了整洁：每次绑定到 Agent 的冷会话接手都会经过 `agentFor()`；没有这条守卫，重复的控制操作即使没有执行任何工作，也会让日志增长。只执行检查的 `session.history` 与 `session.fork` 源端路径不会在源会话中创建这条边界。
 
 ## 持久化无需任何改动
 
@@ -48,8 +48,8 @@ Status: implemented
 
 买到的：一条边界，在一处写入，对全部六条带种子启动路径都正确——包括持久化层方案触及不到的 fork 缺口。持久化各包保留纯读取路径。`firstLiveSeq` 获得一个持久孪生体，而不是关于同一边界的第二套彼此竞争的概念。
 
-代价：带种子会话的日志长了一个事件，空日志恢复也包括在内。seq 期望会随这条边界移动。两处更新是承重的而非机械的：telemetry 的收养测试断言该边界*会*被导出，因为它是本生命周期的自有写入；属性测试套件的回放不变式则是"种子逐字节复现，外加一个仅日志边界"，并把幂等性作为独立属性。
+代价：带种子会话的日志长了一个事件，空日志恢复也包括在内。seq 期望会随这条边界移动。两处更新是承重的而非机械的：telemetry 的接管测试断言该边界*会*被导出，因为它是本生命周期的自有写入；属性测试套件的回放不变式则是「种子逐字节复现，外加一个仅日志边界」，并把幂等性作为独立属性。
 
 `session/end-seed` 加入了落盘词汇表。在预发布立场下（`SESSION_FORMAT_VERSION` 固定为 `0`，不作兼容承诺），更旧的日志只是没有它，而没有边界的日志会正确地判定没有任何内容属于构造种子历史。
 
-[排队手动压缩决策](../feature/2026-07-30-queued-manual-compaction.md)如今提供了第一个消费方。其尾部扫描会分别查找未匹配的 `compact/start` 与最新 end-seed，只把位于该边界之后的 start 视为活动锁，并在同一个回放转换上清除不变量追踪状态。该谓词仍位于压缩包中，不会成为通用核心辅助函数。
+[排队手动压缩决策](../feature/2026-07-30-queued-manual-compaction.md)如今提供了第一个消费方。其尾部扫描会分别查找未匹配的 `compact/start` 与最新 end-seed，只把位于该边界之后的 start 视为存活，并在同一个回放转换上清除不变量追踪状态。该谓词仍位于压缩功能所在的包中，不会成为通用核心辅助函数。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 6319b99fb2..5938463c32 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
 2026-07-30-static-repository-plugin-format.md: c9d755b925a6ea05eed71e75803397d2672df9f4
-2026-07-30-static-repository-plugin-format.zh.md: 361de64d2e98b9fb4ac42963e4ae48e77fbc7016
+2026-07-30-static-repository-plugin-format.zh.md: f747ffeb6d763412dbd6d161e474da35eb7ce5a0
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index 361de64d2e..f747ffeb6d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -1,28 +1,28 @@
-# Agent Note：静态 repository Plugin 格式
+# Agent Note: 静态 repository 插件格式
 
-状态：已实现
+Status: implemented
 
 [English](2026-07-30-static-repository-plugin-format.md) | 中文
 
 ## 问题
 
-一个已经包含可复用 skills 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。与此同时，如果把任意仓库入口都当作 Cordis Plugin，就会让每个仓库成为新的无限制运行时扩展表面，并绕过现有的 skill 与 MCP 生命周期所有者。
+一个已经包含可复用 skill（技能） 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。与此同时，如果把任意仓库入口都当作 Cordis Plugin，就会让每个仓库成为新的无限制运行时扩展面，并绕过现有的 skill 与 MCP 生命周期所有者。
 
-[Package-manager-native repository cache](2026-07-30-package-manager-native-repository-cache.md) 会准备一个精确 package source，但有意不了解任何 DSH 格式。因此本层需要一种兼容 package manager 的创作格式、确定性的已准备产物，以及在 Loader dispose 和替换期间仍保持事务性的 Cordis 组合。
+[包管理器原生仓库缓存](2026-07-30-package-manager-native-repository-cache.md) 会准备一个精确 package source，但有意不了解任何 DSH 格式。因此本层需要一种兼容 package manager 的创作格式、确定性的已准备产物，以及在 Loader dispose（资源释放）和替换期间仍保持事务性的 Cordis 组合。
 
 ## 决策
 
-`@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` package 格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
+`@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` 包格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
 
-`.dsh-plugin` package 把 `dsh-plugin-prepare` 声明为普通 package-manager `prepare` 脚本。Helper 会校验 metadata 与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。`.mjs` 扩展名避免强迫仓库作者在 package metadata 中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。
+`.dsh-plugin` package 把 `dsh-plugin-prepare` 声明为普通 package-manager `prepare` 脚本。Helper 会校验 metadata 与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。`.mjs` 扩展名避免强迫仓库作者在 package metadata 中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest（元数据清单）、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。
 
-加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
+加载 DSH 包会将该 builtin 注册为 effect。生成的包装层使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
 每份已准备 skill 集合都会挂载 `dsh-skill-local`，使用唯一的 `repository:<package-name>` 提供方名称、仅包含复制后的自定义根，并禁用监视。因此 `dsh-skill-local` 新增两个通用配置字段：`providerName` 和 `includeDefaultRoots`。默认值保持原有单一本地提供方行为；repository 实例设置不同名称并排除项目／用户根，使多个实例既不冲突，也不会重复宿主本地发现。
 
-`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
+`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配器接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。形如 `${NAME}` 的完整进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用「Plugin 成功但不注册工具」的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
 
-未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
+未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容约定。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
 
 ## 考虑过的替代方案
 
@@ -39,11 +39,11 @@
 ## 后果
 
 - 现有 skill／MCP 仓库可以新增一个很小的 `.dsh-plugin/package.json`，无需移动资源或采用 SDK 项目。
-- 已准备输出是确定性的静态胶水；已配置仓库及其依赖生命周期仍是受信任的可执行 package-manager 输入，而非 sandbox。
-- 多个 repository Plugin 通过提供方名称和普通 MCP server-name 唯一性共存；重复名称经现有 registry 失败，并参与 Loader 回滚。
+- 已准备输出是确定性的静态胶水；已配置仓库及其依赖生命周期仍是受信任的可执行 package-manager 输入，而非沙箱。
+- 多个 repository Plugin 通过提供方名称和普通 MCP server-name 唯一性共存；重复名称会由现有注册表判定为失败，并参与 Loader 回滚。
 - Cache 内的源码编辑不会实时出现；必须选择另一个精确 source／ref／path／config。
 - 新增贡献类型必须提供显式格式和 DSH 自有运行时消费方；它不能意外以 repository JavaScript 形式进入。
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。Keyless headless 示例通过真实 `cordis.yml` 加载一份签入的已准备包装模块，并快照 repository skill 写入日志的模型目录行。
+聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP、DataJunction 风格 stdio 及环境变量值，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。Keyless headless 示例通过真实 `cordis.yml` 加载一份签入的已准备包装模块，并对 repository skill 写入日志的模型目录行生成快照。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
index 3128996f1e..18e7911025 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
 2026-07-31-claimed-pre-step-inbox-lifecycle.md: 5184c00335b3084a8eb6d58fa33a0af8d3a16ed6
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4966ccc8a3a7535022c04f9445ca75102ccca71e
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 461d926b5143c9bb76dcb07a96315083d599a1f8
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
index 4966ccc8a3..461d926b51 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：在单一 pre-step 决策前领取 inbox 输入
+# Agent Note: 在单一 pre-step 决策前领取 inbox 输入
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-循环此前把一个步骤边界拆成提示词准备、提示词准入与串行 step hook。准入结果可以保留或丢弃已领取输入，实时队列事件还携带了与持久 inbox 状态重复的形状。插件不得不在修改 inbox、改写已提交批次与直接追加会话历史之间选择，而观察方无法依赖一套明确顺序。
+agent loop（智能体循环）此前把一个步骤边界拆成提示词准备、提示词准入与串行步骤钩子。准入结果可以保留或丢弃已领取输入，实时队列事件还携带了与持久 inbox 状态重复的数据结构。插件不得不在修改 inbox、改写已提交批次与直接追加会话历史之间选择，而观察方无法依赖一套明确顺序。
 
 单次出现专属的 inbox wrapper 也重复了每个 `UserMessage` 已有的标识。它把插入、编辑、领取、取消、重连投影与步骤进入合并成一套协议，但仅追加会话本就拥有持久队列投影。
 
@@ -16,9 +16,9 @@ Status: implemented
 
 `PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` seam。
 
-持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此循环可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
+持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此 agent loop 可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
 
-两类事件表面服务不同消费方。跟踪单条消息的观察方使用 `agent/inbox/inserted`、`claimed` 与 `discarded`。包括 Web 队列投影和重连基线在内的整体队列消费方使用持久 `agent/inbox/spliced` 流；UI 编辑与移除经 `Inbox.splice()` 或其他 Inbox 变更方法进入，从而让同一投影记录所有变化。
+两类事件接口服务于不同消费方。跟踪单条消息的观察方使用 `agent/inbox/inserted`、`claimed` 与 `discarded`。包括 Web 队列投影和重连基线在内的整体队列消费方使用持久 `agent/inbox/spliced` 流；UI 编辑与移除经 `Inbox.splice()` 或其他 Inbox 变更方法进入，从而让同一投影记录所有变化。
 
 必须对当前步骤进行原子改写的插件从 `agent/pre-step` 返回消息。只需要稍后上下文的插件可以直接修改 `agent.inbox`。Workspace context 同时使用两条路径：异步文件系统投影会暂存一条可替换的 `next-step` 消息，而下一次进入步骤的 pre-step 会把该消息或新组合的基线折入最终批次，并移除仍待处理的副本。reject 会让该条目继续排队。
 
@@ -26,16 +26,16 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**保留分离的 prepare 与 admit hook。** 这样准备阶段可以在领取前修改 inbox，准入阶段可以在领取后改写，但同一边界会出现两个顺序表面，取消归属也会变得模糊。
+**保留分离的 prepare 与 admit hook。** 这样准备阶段可以在领取前修改 inbox，准入阶段可以在领取后改写，但同一边界会出现两套顺序机制，取消归属也会变得模糊。
 
-**reject 时把已领取批次重新入队。** 这看似保留重试行为，却会让否决隐式修改队列；若不为每个竞态加围栏，还会复制后续工作，并使 claim 无法成为原子所有权转移。
+**reject 时把已领取批次重新入队。** 这看似保留重试行为，却会让否决隐式修改队列；若不为每个竞态加围栏，还会导致后续工作重复，并使 claim 无法成为原子所有权转移。
 
-**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二份契约，而持有确切消息标识的消费方并不需要这些字段。
+**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二套约定，而持有确切消息标识的消费方并不需要这些字段。
 
 ## 验证
 
-Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 seam 与载荷。
+Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩（compaction）、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 seam 与载荷。
 
 ## 后果
 
-循环在每个步骤前只有一个需等待的决策，对输入也只有一次所有权转移。已领取消息不会隐式返回 inbox；后续插入保持独立。实时事件与其他 inbox 通知保持对称，但不镜像持久元数据；插件可以显式选择精确的当前步骤改写，或普通的后续 inbox 投递。
+循环在每个步骤前只有一个需等待的决策，对输入也只有一次所有权转移。已领取消息不会隐式返回 inbox；后续插入保持独立。实时事件与其他 inbox 通知保持对称，但不镜像持久元数据；插件可以显式选择仅针对当前步骤的改写，或普通的后续 inbox 投递。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 45436c96e6..0a3ec9f475 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
 2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 31d2410ee4809d0693f2e7897e61c50163bb0758
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: 62880dc3920af470fae8d54fe9bd061d7e7b54b3
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 31d2410ee4..62880dc392 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：code-runtime seam 拥有可移植标识符排除集
+# Agent Note: code-runtime seam 拥有可移植标识符排除集
 
 Status: implemented
 
@@ -6,13 +6,13 @@ Status: implemented
 
 ## Problem
 
-code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性契约。
+code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
-一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
+一个针对不同语言（CPython，将在本 stack 后续 PR（Pull Request） 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
-seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除契约，每个后端导入它们而非重新声明：
+seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个后端导入它们而非重新声明：
 
 - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。
 - `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。
@@ -21,24 +21,24 @@ seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移
 
 seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以 seam 名消费这些共享常量——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该契约与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看「可移植」含义的地方。
 
 ## Scope
 
 本 PR 只交付 seam 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。seam README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
-`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本契约要防止的可移植性分裂。
+`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
 ## Alternatives considered
 
 **每个后端声明自己的排除集。** 拒绝：这让可移植承诺变成逐后端成立。调用方在 worker 上测过的绑定列表可能被 Python 拒绝，而这正是 seam 存在要防止的分裂。
 
-**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的契约伸手进入兄弟实现。契约属于二者之上，即 seam。
+**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
 
 **在可移植标识符子集中保留 `$`。** 拒绝：`$` 是 JS 专有拼写。允许它会让 `$tools` 通过 worker 却在每个非 JS 后端上失败，为纯粹表面的好处破坏可移植性。
 
 ## Consequences
 
-获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一契约。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
+获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
 
-代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
+代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是修正后的基础，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，证明 worker 侧会依据共享集合执行排除规则。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml
index 589ecbf5fd..f12335047c 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.md
 2026-07-31-goal-owned-durable-events.md: ac0358469958319f7629adb5e96845b7e0013297
-2026-07-31-goal-owned-durable-events.zh.md: 9b45cdd7990bfc1fdfbb63650e40b41e5ba2918d
+2026-07-31-goal-owned-durable-events.zh.md: b4b1e3709cca6044a35d59185f8e15a93edb7590
diff --git a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md
index 9b45cdd799..b4b1e3709c 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md
@@ -16,7 +16,7 @@ Goal 领域需要持久状态，但不需要拥有待处理的模型输入。继
 
 `GoalMessageSource` 只标识已准入且为正数的继续执行 Round。匹配的 `user/message` 会推进 `roundsStarted`；普通用户消息与 inbox splice 事件不会改变 goal 状态。Goal 包不会插入、领取、移除或检查 inbox 消息。`@deepseek-ai/dsh-goal-session` 仍通过公开 inbox 生命周期负责排队和跟踪自己的继续执行提示词。
 
-激活态仍只存在于进程中。服务在缓存观察事件时，将同步追加的事件序号与目标激活态关联；回放或外部追加的变更默认处于 `disarmed`。会话日志仍是唯一的持久权威。
+激活态仍只存在于进程中。服务在缓存观察事件时，将同步追加的事件序号与所请求的激活状态关联；回放或外部追加的变更默认处于 disarmed 状态。会话日志仍是唯一的持久权威。
 
 该领域不会自动把每次变更投影为模型输入。Goal 工具返回当前状态；真正调度工作时，继续执行提示词包含目标描述与 Round 状态。未来如果需要始终可见的 goal 上下文，应由独立上下文插件拥有其 inbox 消息，而不是把它作为持久化副作用。
 
@@ -28,6 +28,6 @@ Goal 领域需要持久状态，但不需要拥有待处理的模型输入。继
 
 ## 后果
 
-Goal 状态不依赖 inbox 放置与准入。回放只有一条变更路径，投影直接由 `goal/change` 推进，继续执行消息只携带 Round 归属。模型不会收到仅用于变更的 `<goal_state>` 消息；模型可见状态来自 goal 工具与已调度的继续执行提示词。直接写入会话的插件仍受信任，并且可以追加畸形变更；严格折叠与 invariant 配套模块会拒绝这些变更。
+Goal 状态不依赖 inbox 放置与准入。回放只有一条变更路径，投影直接由 `goal/change` 推进，继续执行消息只携带 Round 归属。模型不会收到仅用于变更的 `<goal_state>` 消息；模型可见状态来自 goal 工具与已调度的继续执行提示词。直接写入会话的写入方仍受信任，并且可以追加畸形变更；严格折叠与 invariant 配套模块会拒绝这些变更。
 
-聚焦的 goal、goal-session、command、TUI 与 client fixture 测试固定持久回放、正数 Round 计数、inbox 独立性、投影更新和恢复会话行为。无密钥进程测试检查持久的 `goal/change` 事件，并验证仅创建 goal 不会启动继续执行 Round。
+聚焦的 goal、goal-session、command、TUI 与 client fixture（测试前置数据）测试固定持久回放、正数 Round 计数、inbox 独立性、投影更新和恢复会话行为。无密钥进程测试检查持久的 `goal/change` 事件，并验证仅创建 goal 不会启动继续执行 Round。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
index f63372c8b4..262b57e436 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
 2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
-2026-08-01-packaged-ripgrep-search.zh.md: f2b1a12c737f772bff6a6c91c17f7453dbc89748
+2026-08-01-packaged-ripgrep-search.zh.md: 4acf4eeb6f9153b8181ba493bf566cd7387a1984
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
index f2b1a12c73..4acf4eeb6f 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -12,19 +12,19 @@ Status: implemented
 
 ## 决策
 
-`@deepseek-ai/dsh-tool-fs-search` 现在运行 PACKAGED（打包的）ripgrep 二进制（`@vscode/ripgrep`，一个 npm 依赖，其可选平台包随附二进制），经由 `ctx.subprocess` seam：`runRipgrep()` 以纯 argv 向量 spawn `rgPath`，向量前缀 `--no-config`，配以 collect 模式 stdout/stderr、`graceMs` 与转发的 `exec.signal`。`rgPath` 在首次调用时懒解析（进程内 memoize）：`@vscode/ripgrep` 在模块求值阶段解析其平台包，静态导入会把平台包缺失/损坏（`--omit=optional`、安装不全）变成 Loader 组合加载失败——这正是本次改动要消除的加载期失败模式。不再有 shell 层，执行路径上的 shell 引号边界随之消失；`singleQuote` 工具与其 shell spawn 测试一并删除。原始流使用 seam 的诊断尾部 collect 形态（无 spill 文件——工具从不读取原始 spill 路径；lossy stdout 读取以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败）。终止宽限与 stderr 尾部预算成为经校验的 `Config` 字段（`graceMs` 默认 3000，`stderrMaxBytes` 默认 64 KiB），不再继承自 bash-local 的配置。注册变为无条件——加载期 `command -v rg` 探针与条件注册决策被删除，连同那条 "rg not found" 警告。本包注入 `tools`、`systemPrompt` 与 `subprocess`。
+`@deepseek-ai/dsh-tool-fs-search` 现在运行 PACKAGED（打包的）ripgrep 二进制（`@vscode/ripgrep`，一个 NPM 依赖，其可选平台包随附二进制），经由 `ctx.subprocess` seam：`runRipgrep()` 以纯 argv 向量 spawn `rgPath`，向量前缀 `--no-config`，配以 collect 模式 stdout/stderr、`graceMs` 与转发的 `exec.signal`。`rgPath` 在首次调用时懒解析（进程内 memoize）：`@vscode/ripgrep` 在模块求值阶段解析其平台包，静态导入会把平台包缺失/损坏（`--omit=optional`、安装不全）变成 loader 组合失败——这正是本次改动要消除的加载期失败模式。不再有 shell 层，执行路径上的 shell 引号边界随之消失；`singleQuote` 工具与其 shell spawn 测试一并删除。原始流使用 seam 的诊断尾部 collect 形态（无 spill 文件——工具从不读取原始 spill 路径；lossy stdout 读取以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败）。终止宽限与 stderr 尾部预算成为经校验的 `Config` 字段（`graceMs` 默认 3000，`stderrMaxBytes` 默认 64 KiB），不再继承自 bash-local 的配置。注册变为无条件——加载期 `command -v rg` 探针与条件注册决策被删除，连同那条 "rg not found" 警告。本包注入 `tools`、`systemPrompt` 与 `subprocess`。
 
 退出语义仍由工具拥有：退出码 0 为有结果的成功，1 为成功的空搜索，其余归入既有 `SEARCH_*` 词汇（无效模式、启动失败、信号杀死、原始输出溢出）。超时是挂在工具定义上的协作式工具调用预算：`@deepseek-ai/dsh-timeout-policy` 中止 `exec.signal`，subprocess seam 的终止升级提供硬终止，工具报告 `SEARCH_ABORTED`。工作目录为会话 header cwd（存在时），否则为 `process.cwd()`——不再有执行器配置可供默认化，因此回退由工具自己拥有。
 
-`fs-glob-sampling` ACP 快照场景改为执行真实的打包二进制，作用于一个用固定 mtime 钉住 `--sort=modified` 顺序的预制工作区，取代 PATH 注入的 `rg` 替身（仅 POSIX：展示路径携带 `/` 分隔符，会话日志比较无法归一化）。
+`fs-glob-sampling` ACP（Agent Client Protocol）快照场景改为执行真实的打包二进制，作用于一个用固定 mtime 钉住 `--sort=modified` 顺序的预制工作区，取代 PATH 注入的 `rg` 替身（仅 POSIX：展示路径携带 `/` 分隔符，会话日志比较无法归一化）。
 
 ## 备选方案
 
 **保留 bash seam 与探针，仅把 `rg` 记为必需宿主依赖。** 否决：宿主依赖正是本次改动要消除的失败模式，而让发现工具支持 Windows 正是此举的目的；写进文档的依赖仍是依赖。
 
-**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
+**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture（测试前置数据）的 mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
 
-**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具契约。
+**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于「不存在 glob 引擎」的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具约定。
 
 ## 后果
 
@@ -33,6 +33,6 @@ Status: implemented
 - spawn 不受沙箱约束（普通的 `ctx.subprocess` 调用），因此前缀 `--no-config`：宿主的 `RIPGREP_CONFIG_PATH`（或二进制旁的 `rg.conf`）否则可注入 `--pre` 预处理器，对每个匹配文件执行任意命令。加上 `--no-config` 后，任何配置文件——因而任何预处理器——都无法触及搜索。
 - 原始输出溢出路径的形态改变：旧的 bash 承载路径继承了 bash-local 常开的 spill，可能留下没人读的多 MB 临时文件；subprocess seam 现在无 spill 收集，溢出是纯粹的错误（`SEARCH_RAW_OUTPUT_OVERFLOW`，"narrow pattern, path, or include and retry"），不返回任何内容。
 - 加载期失败模式改变：subprocess seam 损坏现在让首次搜索调用失败（`SEARCH_FAILED`），而非通过探针使插件加载失败；二进制缺失是带打包路径的启动失败，而不是 PATH 问题。
-- 集成套件的 fixture 去掉了 Windows 无法表示的文件名（名称含 `"`），保证套件在每个平台都能重放。
-- 重新生成 `THIRD_PARTY_NOTICES.md` 暴露了一个由新依赖带出的潜在生成器 bug：Node 的 `fs.globSync` 返回操作系统原生分隔符，因此在 Windows 上 notices 分层中带 `/` 后缀的 dev 区前缀永远匹配不上，dev-only 包（测试工具、support 叶子）被错分为 runtime。生成器现在在入口处归一化清单路径，notices 与平台无关。
-- `@vscode/ripgrep` 依赖为 runtime 层增加其 MIT 行；pnpm 11 截断的虚拟存储目录名需要在 notices 生成器的元数据查找中增加内容扫描回退。
+- 集成套件的 fixture 去掉了 Windows 无法表示的文件名（名称含 `"`），保证套件在每个平台都能回放。
+- 重新生成 `THIRD_PARTY_NOTICES.md` 暴露了一个由新依赖带出的潜在生成器 bug：Node 的 `fs.globSync` 返回操作系统原生分隔符，因此在 Windows 上 notices 分层中带 `/` 后缀的 dev 区前缀永远匹配不上，dev-only 包（测试工具、support 叶子）被错分到运行时层。生成器现在在入口处归一化 manifest（元数据清单）路径，notices 与平台无关。
+- `@vscode/ripgrep` 依赖为运行时层增加其 MIT 行；pnpm 11 截断的虚拟存储目录名需要在 notices 生成器的元数据查找中增加内容扫描回退。
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index d3f73c3b5c..dfe291e9d0 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
 2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
-2026-08-02-typert-remote-method-calls.zh.md: da4459432e8c9e08821bcded2921cbd33fc5e8c8
+2026-08-02-typert-remote-method-calls.zh.md: 2290b701eff7ca601b500efbfcf7bdc59c01bcba
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index da4459432e..2290b701ef 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -10,7 +10,7 @@ Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事
 
 本决策只涵盖一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流仍采用独立设计。
 
-直接方法调用的契约属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
+直接方法调用的约定属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
 
 Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以不同类型合并同名 Cordis `Context`。Remote 投影不能把完整 Host 声明导入消费端，也不能依赖 Browser 专属类型；未来 TUI 若复用这套编程界面，也只能看到 Remote 标记的方法。本期不实现 TUI 接入，但实现边界不得阻断这种同构复用。
 
@@ -18,11 +18,11 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteScope()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
-Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
+Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一约定的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
 
 `@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.remote`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
 
-`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 契约，而不导入具体 Gateway 实现。
+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 约定，而不导入具体 Gateway 实现。
 
 ## 组件和 Cordis 服务
 
@@ -42,7 +42,7 @@ Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.http
 
 ## 业务声明
 
-普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 契约时，直接装饰该方法，不为此重命名。只有 wire 契约需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
+普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 约定时，直接装饰该方法，不为此重命名。只有 wire 约定需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
 
 ```text
 export class GoalService extends GatewayService {
@@ -87,7 +87,7 @@ export class ScopedGoalService extends GatewayService {
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
+Decorator 只表达“该方法参与 Remote 约定”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
@@ -147,7 +147,7 @@ InvocationDescriptor {
 
 参数顺序来自方法签名，HTTP 字段来自参数名或 lookup 声明。取消 descriptor 只保留最后一个 `signal` 位置，并使其不进入具名 `args`；实际 signal 由 Connection 或直接调用 Gateway 的调用方提供。Gateway 不根据请求内容推断可选字段、Context 类型、lookup 类型或缺失参数，也不会合成业务默认值。
 
-LIB codec 带有 Zod schema 和“package + 公共 subpath + export name”的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
+LIB codec 带有 Zod schema 和「package + 公共 subpath + export name」的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
 
 descriptor 只存在于两端本地 registry。wire 上只有 `/api` channel、endpoint 和 `{ args }` payload；Host 用自己的 descriptor 解码和调用，Client 用自己的对应 descriptor 编码参数和验证结果。
 
@@ -217,7 +217,7 @@ Host lib build
 
 现有顶层 `build` 仍表现为先 `build:lib`、再 `build:web`，但 `build:lib` 内部必须先完成 Host 与 Remote artifact，再启动 Client TypeScript 编译。一次干净构建不能依赖上次残留的 `.d.ts`。
 
-即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 契约 pass。门禁调度器仅可在显式的 TypeRT 契约依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
+即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 约定 pass。门禁调度器仅可在显式的 TypeRT 约定依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
 
 ## `/remote` 包入口
 
@@ -236,7 +236,7 @@ Host lib build
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 ```
 
-该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一契约的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
+该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一约定的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
 
 业务 package 的发布文件必须同时包含 `lib/typert.remote-client.d.ts.map` 和 map 指向的 `src` 文件。生成 DTS 以 `//# sourceMappingURL=typert.remote-client.d.ts.map` 引用相邻 map；map 中的 source 从 `lib` 相对指向业务源码，例如 `../src/index.ts`。`/remote` export 不单独列出 map，package `files` 负责把它与源码一起发布。
 
@@ -309,7 +309,7 @@ await ctx.remote.$mount(goalsRemote)
 await ctx.remote.$mount(sessionsRemote)
 ```
 
-Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 契约和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 约定和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
 
 `ctx.remote.$mount()` 把 contribution 注册到 `TypeRT.remotes`，安装它的 namespace Service 和具体方法，并在它们就绪后才 resolve。调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
@@ -343,7 +343,7 @@ Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote
 
 TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
 
-Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
+Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 约定变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
 ## SRC 与 LIB 运行模式
 
@@ -454,7 +454,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
 - `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
-- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 契约向业务包暴露合并后的 Remote 类型。
+- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 约定向业务包暴露合并后的 Remote 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
@@ -474,7 +474,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 **让 decorator 在运行时完成严格反射。** JavaScript decorator 无法恢复擦除后的 TypeScript 类型、公共符号身份和完整 Zod codec；向 constructor 注入 compiler 私有 symbol 又会隐藏业务类的真实依赖，因此严格信息由 TypeRT compiler 生成。
 
-**SRC 启动时使用 preload、loader hook 或完整 `ts.Program`。** 这能复用 LIB 分析，但增加所有源码启动入口的要求。SRC 只需要可用的弱 descriptor，因此采用 decorator 标记、函数参数名和显式 provider；严格检查留给 LIB contract pass。
+**SRC 启动时使用 preload、loader hook 或完整 `ts.Program`。** 这能复用 LIB 分析，但增加所有源码启动入口的要求。SRC 只需要可用的弱 descriptor，因此采用 decorator 标记、函数参数名和显式 provider；严格检查留给 LIB 约定 pass。
 
 **手写 Client interface。** 手写接口不能保证只包含 Remote 标记的方法，也会与 Host 签名、lookup ID 和 Zod schema 漂移，因此 Client 类型从 Host Program 自动投影。
 
@@ -490,9 +490,9 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 验证
 
-- Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
+- Goal Service 直接装饰业务签名已经符合 Remote 约定的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
-- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 契约；pre-push 钩子使用同一个已包含契约准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的契约 pass。
+- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 约定；pre-push 钩子使用同一个已包含约定准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的约定 pass。
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
@@ -504,19 +504,19 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 后果
 
-Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 契约 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
+Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 约定 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
 
-源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
+源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布约定。
 
 SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费方必须重新执行 lib build，因为系统没有增量 contract watcher。
 
 公共类型唯一性要求业务 DTO 具有纯类型出口，可能暴露现有包中 Host 类型与实现入口混杂的问题。构建会拒绝这些边界，而不是复制类型掩盖问题。
 
-类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface；真实调用环境遗漏 value contribution 时，Client Remote Service 必须以明确的“Remote 未挂载”错误失败。
+类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface；真实调用环境遗漏 value contribution 时，Client Remote Service 必须以明确的「Remote 未挂载」错误失败。
 
 Browser 与 Host 各自持有 Zod 实例，不能依赖对象 identity 跨 realm 比较；一致性只由规范 symbol key、同一生成模型和 wire 行为保证。
 
-消费端可以导入 Host 当前未挂载的 Remote contract。类型表示“该协议能力已被消费端选择”，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
+消费端可以导入 Host 当前未挂载的 Remote contract。类型表示「该协议能力已被消费端选择」，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
 
 Connection 的通用 channel API 必须同时适合当前 HTTP carrier 和后续 WebSocket carrier。若 Client Remote 或 Gateway 暴露 `fetch`、HTTP request 或 route handle，WebSocket 迁移会再次穿透 Remote 层，因此这些物理对象必须留在 Connection 内部。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 2969995da6..fb4922d5c5 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
 2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: ce91abd6dc71f790c72766cd3f819096d596182c
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: 9ed1abc5cedbba637466531f7fc48f73c1e18a0d
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index ce91abd6dc..9ed1abc5ce 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -14,14 +14,14 @@ Status: implemented
 
 提供方路由是一份**声明**，已安装 catalog 是它的默认值。`resolveProfiles` 不再拿路由键去核对 `getBuiltinProviders()`，而是把每条路由解析成一份物化模型列表，外加服务它的 pi-ai `Provider`：
 
-- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
+- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理（reasoning）沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
 - `provider.ts` 构造路由的 `Provider`。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换 `getModels()`；其余路由都由 `createProvider()` 基于一张协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的 `@earendil-works/pi-ai/api/*.lazy` factory。该表刻意窄于 pi-ai 的完整 API 集合——只保留 profile 能用密钥、端点与标头完整描述的协议，因此 Bedrock（SigV4 加 region）、Vertex（project、location、ADC）、Azure（提供方环境加 api-version）与 Codex（OAuth）不在其中，而不是被当作无法认证的路由提供出去。catalog 路由仍可经自己的 provider 抵达它们；被拒的只有显式覆盖。
 - `adapter.ts` 把每次解析变成一份**不可变快照**——profiles 加上持有这些 provider 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份。
-- 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出**能力**，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
+- 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出*能力*，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
 
 ### 快照，而不是共享集合
 
-`Models.streamSimple()` 惰性解析 provider——在返回的流首次被消费时，而那已在适配器 await 路由凭据之后。因此就地改动的单一集合，会让一个在旧配置下开始的请求在新配置下结束，或者撞上一个已不存在的 provider，尽管 `llm.prepareCall()` 早已冻结了该步的 config 并捕获了其适配器注册。配置变化改为构造**新**集合，正在被使用的那个原封不动，于是 seam 的每步冻结得以贯通到底：回复途中切换模型在下一步生效，绝不影响在途的那一步。
+`Models.streamSimple()` 惰性解析 provider——在返回的流首次被消费时，而那已在适配器 await 路由凭据之后。因此就地改动的单一集合，会让一个在旧配置下开始的请求在新配置下结束，或者撞上一个已不存在的 provider，尽管 `llm.prepareCall()` 早已冻结了该步的 config 并捕获了其适配器注册。配置变化改为构造*新*集合，正在被使用的那个原封不动，于是 seam 的每步冻结得以贯通到底：回复途中切换模型在下一步生效，绝不影响在途的那一步。
 
 ### 目录原子替换
 
@@ -39,11 +39,11 @@ pi-ai 把没有推理元数据的模型报告为只支持 `off` 一档，而适
 
 ### 凭据留在 pi-ai 之外
 
-pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `CredentialStore`，配合 `envApiKeyAuth` 解析 `credential.key ?? env(VAR)`。采用它会在 `ctx.credentials` 之外制造第二个凭据事实源，更糟的是会把 harness 明确禁止的环境回落重新引进来：点名了却取不到的 `apiKeyEnv` 必须以 `MISSING_CREDENTIAL` 失败，而不是用环境里恰好持有的某个无关密钥完成认证。
+pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `CredentialStore`，配合 `envApiKeyAuth` 解析 `credential.key ?? env(VAR)`。采用它会在 `ctx.credentials` 之外制造第二个凭据真源，更糟的是会把 harness 明确禁止的环境回落重新引进来：点名了却取不到的 `apiKeyEnv` 必须以 `MISSING_CREDENTIAL` 失败，而不是用环境里恰好持有的某个无关密钥完成认证。
 
 `ModelsImpl.applyAuth` 会把 `options.apiKey` 当作该请求的密钥，但这条路必须经由一个声明了 api-key 方法的提供方：`resolveProviderAuth` 在覆盖存在时短路到该方法，否则依次落到凭据存储与环境发现；若提供方压根没有 api-key 方法，它返回空，请求随即以 `Provider is not configured` 失败。因此 harness 一如既往经自身 seam 解析路由密钥，并把结果作为请求的 `apiKey` 传入；该集合构造时不带任何凭据存储。
 
-路由的 auth 由此推出。catalog 路由保留已安装提供方自己的 `auth`，从而为不点名凭据的 profile 保住其提供方原生环境发现，且在 `api` 覆盖之下同样保留：提供方读哪个环境是提供方自身的属性，而非其模型所讲协议格式的属性。例外是没有 api-key 方法的 catalog 提供方——`openai-codex` 只走 OAuth——此时点名了凭据的 profile 会在提供方原有 auth 之外再获得 harness 的方法，否则它配置的密钥会在任何请求发出之前被拒。这类路由上不点名凭据的 profile 什么也不加、并保留那句诚实的拒绝：本适配器没有可供解析的 OAuth 存储。手工声明的路由则获得一个 harness 自有的 `ApiKeyAuth`，它报告「已配置但无密钥」而非「未配置」，把该要求留给协议——那才是它真正所在的位置：pi-ai 的 OpenAI 兼容实现仍要求密钥或 `Authorization` 标头，并且会自己说出来。
+路由的 auth 由此推出。catalog 路由保留已安装提供方自己的 `auth`，从而为不点名凭据的 profile 保住其提供方原生环境发现，且在 `api` 覆盖之下同样保留：提供方读哪个环境是提供方自身的属性，而非其模型所讲协议格式（wire format）的属性。例外是没有 api-key 方法的 catalog 提供方——`openai-codex` 只走 OAuth——此时点名了凭据的 profile 会在提供方原有 auth 之外再获得 harness 的方法，否则它配置的密钥会在任何请求发出之前被拒。这类路由上不点名凭据的 profile 什么也不加、并保留那句诚实的拒绝：本适配器没有可供解析的 OAuth 存储。手工声明的路由则获得一个 harness 自有的 `ApiKeyAuth`，它报告「已配置但无密钥」而非「未配置」，把该要求留给协议——那才是它真正所在的位置：pi-ai 的 OpenAI 兼容实现仍要求密钥或 `Authorization` 标头，并且会自己说出来。
 
 ## Alternatives considered
 
@@ -54,14 +54,14 @@ pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `Cred
 
 - **保留单个可变 `Models` 集合并重新同步。** 分配更少，且对每个同步完成解析的操作都是正确的；唯独对那个不同步的操作恰恰是错的：`stream()` 会在捕获模型与派发模型之间 await 一次凭据。
 - **用「先 dispose 再注册」模拟目录原子替换。** 无需改 seam，且在新集合有效时确实可用——而那正是从不需要原子性的那种情形。
-- **运行时动态 catalog**——`fetchModels` 加 `ModelsStore`，后台刷新。本次变更拒绝：它把模型列表变成需要缓存、失效与离线路径的外部可变状态，而产品需求是一次性的发现动作、其结果由用户采纳进 `settings.yaml`。该动作属于配置界面，与之一并暂缓；`settings.yaml` 始终是「路由服务什么」的唯一事实源。
+- **运行时动态 catalog**——`fetchModels` 加 `ModelsStore`，后台刷新。本次变更拒绝：它把模型列表变成需要缓存、失效与离线路径的外部可变状态，而产品需求是一次性的发现动作、其结果由用户采纳进 `settings.yaml`。该动作属于配置界面，与之一并暂缓；`settings.yaml` 始终是「路由服务什么」的唯一真源。
 
 ## Consequences
 
-配置一个提供方不再取决于 pi-ai 的发布节奏。网关、自建服务，或比锁定 catalog 更新的模型，都是一次 `settings.yaml` 编辑，过期的上下文窗口也能就地更正。废弃的 `/compat` 导入已经消失，因此 pi-ai 删除它不再是破坏性事件。`defaultMaxTokens` 现在只在部署明确给出时才自配置流出，不会从 catalog 元数据里发明一个上限。
+配置一个提供方不再取决于 pi-ai 的发布节奏。网关、自建服务，或比锁定 catalog 更新的模型，都是一次 `settings.yaml` 编辑，过期的上下文窗口也能就地更正。废弃的 `/compat` 导入已经消失，因此 pi-ai 删除它不再是破坏性事件。`defaultMaxTokens` 现在会在部署明确给出时从配置中传入，不会从 catalog 元数据里发明一个上限。
 
 代价是：声明式路由会让 `settings.yaml` 变长，因为它必须自报端点、协议与模型 id。`api` 作用于整条路由，因此混合协议的 catalog 路由无法承载另一种协议的模型——把它拆成两个路由键是变通办法。没有任何环节查询提供方的 `/models`，因此模型列表的新鲜度只到最近一次编辑为止。有一种情形下报错形状发生变化：auth 解析不出任何值的路由，现在会在任何网络调用之前把 pi-ai 自己的诊断作为错误 `finish` 分片呈现，而此前的适配器会发出无密钥请求并呈现提供方的 401。
 
 ## Testing
 
-`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该契约：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项契约：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
+`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该约定：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项约定：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 22935b42ca..6e2e6e1453 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
 2026-08-04-configuration-source-ownership.md: ef30a22c120af1437f348e52843e1dd45c9837ae
-2026-08-04-configuration-source-ownership.zh.md: c1567c6e823a0bc8ed8d1f9ed50a11a5d204ede8
+2026-08-04-configuration-source-ownership.zh.md: ef352ce4c7b8eef8fc2dcd3aa7154bda770ffd4e
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index c1567c6e82..ef352ce4c7 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -16,7 +16,7 @@ endpoint 可以被项目重定向。调用目录的 `.env` 和其他层一样会
 
 ## Decision
 
-**非密钥值走同一条顺序。** 每个本身不是凭据的可配置值都按同一顺序解析；各领域的差别只在于哪些层存在。
+**非机密值走同一条顺序。** 每个本身不是凭据的可配置值都按同一顺序解析；各领域的差别只在于哪些层存在。
 
 ```text
 explicit for this run     per-operation override, CLI argument
@@ -29,7 +29,7 @@ explicit for this run     per-operation override, CLI argument
 
 自上而下依次是：本次运行的显式意图、用户 settings、composition、本次启动的 shell、被发现的文件、默认值。
 
-settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是 profile 的 bundle 设的，还是它的用户 patch 层或某个 `--patch` overlay 设的——它们都以 entry config 的形式抵达。产品 CLI（命令行界面）没有高于已存 settings 的手段，因此需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应自带 bin 或 loader 配置树，或者干脆不挂载 settings provider。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
+settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是 profile 的 bundle 设的，还是它的用户 patch 层或某个 `--patch` overlay 设的——它们都以 entry config 的形式抵达。产品 CLI（命令行界面）没有高于已存 settings 的手段，因此需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应自带 bin 或 loader 配置树，或者干脆不挂载 settings 提供方。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
 
 **凭据保留一条更窄的独立顺序**，本 Note 不把它并入上表：
 
@@ -40,13 +40,13 @@ inherited process environment      (read-only, wins)
 > $DSH_HOME/.env
 ```
 
-继承环境优先，因为 `DEEPSEEK_API_KEY=… dsh`、CI 机密与容器 `-e` 是运维必须能按次施加、且无需改动机器状态的那一种覆盖；而它无法从进程内部修改，就必须*可见地*只读。配置本应只携带*引用*——解析哪个名字——该名字本身遵循上面的非密钥顺序。
+继承环境优先，因为 `DEEPSEEK_API_KEY=… dsh`、CI 机密与容器 `-e` 是运维必须能按次施加、且无需改动机器状态的那一种覆盖；而它无法从进程内部修改，就必须*可见地*只读。配置本应只携带*引用*——解析哪个名字——该名字本身遵循上面的非机密顺序。
 
 **harness 被启动于其中的项目默认可信，且不做询问。** 一个 checkout 可以携带自己的 endpoint、自己的普通变量和自己的密钥；密钥排在受管存储之下，因此通过 Models 页存下的密钥绝不会被 checkout 中恰好带有的那一个顶掉。`EnvironmentSnapshot.getFrom(name, sources)` 仍然只搜索调用方点名的层，省略某层仍是拒绝而不是降级——该机制是为「某一层必须不可达」的那些决策准备的，而项目层今天不在其列。
 
-**信任不延伸到改变 harness 本身。** `loadLayeredEnv` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+**信任不延伸到改变 harness 本身。** `loadLayeredEnv` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何访问以及如何建立信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
 
-这条界线在于：它们无需任何用户动作、在任何一轮开始之前、且在权限策略与沙箱之外就生效。`DSH_PERMISSION_MODE` 会关掉让「信任项目」根本成立的那道审批，而 `BASH_ENV` 会在 bash 工具发出的每一次 `bash -c` 上执行项目指定的文件——项目的代码在 agent 的策略下运行是约定，项目改写那份策略不是。一个变量一个变量地枚举是必输的游戏，所以整个 `DSH_*` 命名空间被拒绝而不是只拒绝一份经审查的子集，也所以这份清单是按变量*做什么*而不是按哪个运行时拥有它来组织的。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
+这条界线在于：它们无需任何用户动作、在任何轮次开始之前、且在权限策略与沙箱之外就生效。`DSH_PERMISSION_MODE` 会关掉让「信任项目」根本成立的那道审批，而 `BASH_ENV` 会在 bash 工具每次发出 `bash -c` 时执行项目指定的文件——项目的代码在 agent（智能体）的策略下运行是约定，项目改写那份策略不是。一个变量一个变量地枚举是必输的游戏，所以整个 `DSH_*` 命名空间被拒绝而不是只拒绝一份经审查的子集，也所以这份清单是按变量*做什么*而不是按哪个运行时拥有它来组织的。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
 
 **`packages/util/environment` 拥有该快照**，刻意做成 utility 而不是三包能力 seam。快照在 Cordis 启动前就冻结，并由启动器一次性注入，因此不存在需要切换的运行时实现；消费方需要的只是类型和纯函数，而 `util/` 包能提供这些且不必依赖 UI 包。`environmentOf(ctx)` 返回启动器的快照，或者返回只含继承环境的那一层——SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，它那唯一一层确实就是它被启动时的环境，因此同样的受信查询在那里原样继续工作。
 
@@ -57,12 +57,12 @@ inherited process environment      (read-only, wins)
 - Web 凭据表单现在能压过用户 `.env` 里更旧的密钥；只有在启动 shell 里 export 的密钥才会让它变成只读，诊断信息也会这么说。
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - composition 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
-- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；其余变量抵达子进程的限制记录在环境包中。
+- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；环境包将其余变量仍可抵达子进程这一点记录为一项限制。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
 
 ## Alternatives considered
 
-**按「来源由谁书写」把凭据并入非密钥顺序。** 尝试过并放弃：它读起来很顺，但 settings seam 已经把 composition 固定在用户 section *之下*，因此「部署授权」根本不是该 seam 能表达的一层；而把 `.credentials.yaml` 抬到启动环境之上，会夺走 CI、容器和一次性 `DEEPSEEK_API_KEY=…` 所依赖的那唯一一种覆盖。两条各自说清自身形状成因的顺序，好过一条两边都描述不准的顺序。
+**按「来源由谁书写」把凭据并入非机密顺序。** 尝试过并放弃：它读起来很顺，但 settings seam 已经把 composition 固定在用户 section *之下*，因此「由部署方写入」根本不是该 seam 能表达的一层；而把 `.credentials.yaml` 抬到启动环境之上，会夺走 CI、容器和一次性 `DEEPSEEK_API_KEY=…` 所依赖的那唯一一种覆盖。两条各自说清自身形状成因的顺序，好过一条两边都描述不准的顺序。
 
 **在项目被显式信任之前，不给它路由与凭据能力。** 作为产品立场被否决：checkout 默认可信，不询问，也不存储信任记录。残留风险是真实的、值得写明——克隆一个携带 `.env`、其中指定了另一个 endpoint 或密钥的仓库，会让该会话经由它——处理它的地方是日后的 project trust 门禁，而不是一条让常见情形都要走仪式的规则。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
index e083adcca5..dffcbad0af 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
 2026-08-04-credentials-yaml-and-user-environment-layer.md: 44bdea243671093b34a6338ed1c95bf25bcc78f4
-2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 5f724c7a12365e6e87e03b5926f837a5251b6118
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 3772c1b5cfe6e644490bae927acf5b043572435e
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
index 5f724c7a12..3772c1b5cf 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -6,22 +6,22 @@ Status: implemented
 
 ## Problem
 
-`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 Models 页轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非密钥值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
+`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 Models 页轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非机密值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
 
-一个文件无法既是由 Harness 拥有并隔离的存储，又是按普通环境规则传播的层。[请求级凭据决策](2026-07-29-request-level-llm-config-credentials.md)当初选择 dotenv 是为了对齐同类产品的 home `.env`，而这种混同直到有非密钥值需要用同一个文件时才暴露出来。
+一个文件无法既是由 Harness 拥有并隔离的存储，又是按普通环境规则传播的层。[请求级凭据决策](2026-07-29-request-level-llm-config-credentials.md)当初选择 dotenv 是为了对齐同类产品的 home `.env`，而这种混同直到有非机密值需要用同一个文件时才暴露出来。
 
 ## Decision
 
 两件工作在 Harness home 下拆成两个文件。
 
-**`.credentials.yaml` 是 provider 管理的存储。** 一个从 `CredentialRef` 到非空字符串的严格 YAML mapping，没有 `version` 字段，也没有包装层：
+**`.credentials.yaml` 是 provider 管理的存储。** 一份从 `CredentialRef` 到非空字符串的严格 YAML 映射，没有 `version` 字段，也没有包装层：
 
 ```yaml
 DEEPSEEK_API_KEY: sk-…
 OPENAI_API_KEY: sk-…
 ```
 
-因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
+因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：根节点不是映射、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
 
 **`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/boot/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
 
@@ -32,9 +32,9 @@ OPENAI_API_KEY: sk-…
 ## Consequences
 
 - 放弃的：留在 `$DSH_HOME/.env` 里的密钥会被物化进 `process.env`，因而会按[子进程凭据清洗](../../../../packages/subprocess/subprocess/README.md)的规则抵达子进程，而不再留在 provider 内部。它仍是 `.credentials.yaml` 之下的可写后备值；需要由 Harness 拥有并隔离的密钥属于受管文档，后者永不物化。
-- 换来的：用户 `.env` 里的非密钥值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
-- provider 写入时用的 `0600` 同样约束它读取的内容：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在读取内容之前让启动失败——启动时与每次 reload 都检查，诊断里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode（其 ACL 无法在此表达），因此跳过该检查而不是伪造它。
-- `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain provider 的延后项归 [provider README](../../../../packages/credentials/credentials-local/README.md) 所有。
+- 换来的：用户 `.env` 里的非机密值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
+- 提供方写入时使用的 `0600` 同样约束它读取的内容：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在读取内容之前让启动失败——启动时与每次 reload 都检查，诊断里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode（其 ACL 无法在此表达），因此跳过该检查而不是伪造它。
+- `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain 提供方的延后项归 [提供方 README](../../../../packages/credentials/credentials-local/README.md) 所有。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index 4c5c87821f..141a08a5b6 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
 2026-08-04-declaring-a-provider-from-the-models-page.md: 53996e488c467e00754837b83b7a33994d4813ee
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: fa61c48492eabf51f3d325078ceffa84ac52d12c
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 3a952aa0a02e0b2906bf16bcc46d14a8f7f71bc4
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index fa61c48492..3a952aa0a0 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-下面两层已经让 pi-ai 路由变成[一份声明](2026-08-03-pi-ai-declared-provider-catalog.md)，并给了 host [询问草稿端点](2026-08-04-draft-provider-endpoint-interrogation.md)的能力。但两者都没有抵达不编辑 YAML 的人：Models 页仍然只为每个提供方提供一个 API 密钥输入框和一个装着 API 地址的折叠区，因此接入一个网关意味着打开 `$DSH_HOME/settings.yaml` 并知道 profile 的形状，更正一个过期的上下文窗口也是如此。能力已经存在，界面却没有暴露它。
+下面两层已经让 pi-ai 路由变成[一份声明](2026-08-03-pi-ai-declared-provider-catalog.md)，并给了 host [询问草稿端点](2026-08-04-draft-provider-endpoint-interrogation.md)的能力。但两者都没有抵达不编辑 YAML 的人：Models 页仍然只为每个提供方提供一个 API 密钥输入框和一个装着 API 地址的折叠区，因此接入一个网关意味着打开 `$DSH_HOME/settings.yaml` 并知道 profile 的形状，更正一个陈旧的上下文窗口也是如此。能力已经存在，界面却没有暴露它。
 
 缺的是两件事，而它们的形状并不相同。编辑既有路由的模型，是一张已经存在的卡片上的一个*字段*；声明一条路由则是一次*创建*：路由 id 正在此处被选定，而在选定之前根本没有可编辑的 settings 地址。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
index ae96598b48..9b8339d0e2 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
 2026-08-04-draft-provider-endpoint-interrogation.md: 65545098cd1063c40081481c1ac8f0afdb4fb390
-2026-08-04-draft-provider-endpoint-interrogation.zh.md: cb09042904f4ab1558c0c214d275a934234955ac
+2026-08-04-draft-provider-endpoint-interrogation.zh.md: 6300e357182e0e81028c6d01026ea93c4fc5202f
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
index cb09042904..6300e35718 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 当 pi-ai 路由变成[一份声明而非 catalog 查表](2026-08-03-pi-ai-declared-provider-catalog.md)之后，要接入一个 OpenAI 兼容网关的人，必须先知道它的模型 id 才能完成配置。适配器不再把人限制在已安装 catalog 里——这正是那次改动的目的——但也意味着没有任何东西告诉用户该端点究竟服务什么，而这类端点大多在 `GET /models` 上公布了这份列表。
 
-显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是**只问一次**，其答案由用户采纳进 `settings.yaml`——从而让 `settings.yaml` 始终是唯一决定路由服务什么的东西。
+显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是*只问一次*，其答案由用户采纳进 `settings.yaml`，从而让 `settings.yaml` 始终是决定路由服务内容的唯一真源。
 
 麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 seam 操作都以已注册的提供方路由为键，因此没有一个能承载它。
 
@@ -19,13 +19,13 @@ Status: implemented
 - `ctx.llm.registerModelDiscovery(settingsNs, discover)` 让适配器插件为自己拥有的 namespace 提供「询问端点」的能力，`ctx.llm.discoverModels(settingsNs, request)` 发起询问。没有任何办法枚举哪些 namespace 注册过：询问不了的界面会从那句拒绝里知道，而一份无人消费的列表只会变成一个什么都不做的必填协议字段。以 namespace 为键是对的，因为配置界面已经从可配置提供方目录里拿到了它，也因为正在新增的提供方没有路由可点名。
 - `LlmModelDiscoveryRequest` 携带草稿——可选的 `provider`、可选的 `baseURL`、可选的 `api`、可选的 `apiKey`，以及一个 signal——且 `provider` 与 `baseURL` 至少要有一个，才有东西可答。`provider` 之所以存在，是因为适配器已经描述过的路由直接由它自己的注册表作答、完全不联网；只有它未描述的路由才会抵达某个端点。这条路径不写 settings 与 credentials。唯一的读取是请求所点名路由的凭据：配置界面拿到的是脱敏描述符而非已存的机密，因此草稿里的 `apiKey` 只在用户正键入时才存在；没有这次读取，已配置好的路由就会被不带认证地询问，只换回一个 401。键入的密钥优先，因为那正是被测试的那一把。
 - `LlmDiscoveredModel` 除 `id` 外每个字段都可选，因为大多数列表只公布 id。回复是候选而非 catalog：采纳其中一条的界面仍要补上适配器所需的容量。
-- `llm.discoverModels` 把同一份草稿送过协议层。它的 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。它确实会像其他承载机密的载荷一样随客户端外发信封同行，`subscribeEnvelopes()` 观察者看得到；把那个抽头脱敏是整个配置面的改动，不该由这一个方法独自决定。除密钥之外它被钉在回环还有第二个理由：它让宿主向调用方选定的 URL 发起 GET 并回报结果，这是匿名 LAN 调用者不该拥有的探测能力。每一种拒绝都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。
+- `llm.discoverModels` 把同一份草稿送过协议层。它的 `apiKey` 是可承载机密的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。它确实会像其他承载机密的载荷一样随客户端外发信封同行，`subscribeEnvelopes()` 观察者看得到；把那个抽头脱敏是整个配置面的改动，不该由这一个方法独自决定。除密钥之外它被钉在回环还有第二个理由：它让宿主向调用方选定的 URL 发起 GET 并回报结果，这是匿名 LAN 调用者不该拥有的探测能力。每一种拒绝都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。
 
 `dsh-llm-pi-ai` 的实现只是一次朴素的 `GET {baseURL}/models`，且仅限 OpenAI 兼容协议。它们的列表形状是网关、自建服务与官方端点三方一致认可的那一种，而这正是该动作存在的场景。其余协议一律以 `DISCOVERY_UNSUPPORTED` 回答，让界面回退到手工填写，而不是把猜错的响应形状报成一个空提供方。`baseURL` 按前缀而非待解析 URL 处理，因此 `https://gateway.example/openai/v1` 这类部署路径会保留其路径段。回复在四兆字节上限下读取，且上限落在实际收到的字节上——端点是用户自己填的 URL，因此会先看声明的 `content-length` 作为善意提示，但绝不把它当作边界；这与 `dsh-web-fetch` 面对自己的调用方提供 URL 时所用的两段式形状一致。
 
 ### 为什么不用 pi-ai 自己的 refresh 机制
 
-pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与 `ModelsStore`，而下层本来就在构造 pi-ai `Provider` 对象。把询问接到它们上面，意味着每问一次就要构造一个用完即弃的 provider 与集合，而那个 store 的全部目的——跨运行持久化 catalog——恰恰与「`settings.yaml` 拥有 catalog」的决定相抵触。而且它什么也换不来：**没有任何一个 pi-ai 内置 provider 实现了 `fetchModels`**，因此 HTTP 调用及其响应解析无论如何都是本包的代码。直接 fetch 才如实说出正在发生的事。路由已存的凭据由本插件自己那套逐请求解析器取出，且只在真正要联网的那条分支上进行，因此 catalog 路由作答时既不触碰凭据，也不会因为一把这次询问根本用不上的密钥而失败。
+pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与 `ModelsStore`，而下层本来就在构造 pi-ai `Provider` 对象。把询问接到它们上面，意味着每问一次就要构造一个用完即弃的提供方与集合，而那个 store 的全部目的——跨运行持久化 catalog——恰恰与「`settings.yaml` 拥有 catalog」的决定相抵触。而且它什么也换不来：**没有任何一个 pi-ai 内置提供方实现了 `fetchModels`**，因此 HTTP 调用及其响应解析无论如何都是本包的代码。直接 fetch 才如实说出正在发生的事。路由已存的凭据由本插件自己那套逐请求解析器取出，且只在真正要联网的那条分支上进行，因此 catalog 路由作答时既不触碰凭据，也不会因为一把这次询问根本用不上的密钥而失败。
 
 ## Alternatives considered
 
@@ -33,7 +33,7 @@ pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与
 
 **把能力挂在 `LlmAdapter` 上。** 适配器要经由路由注册才能抵达，因此问题相同；而且这会让一个适配器实例去回答它并不服务的端点的问题。
 
-**让 host 读已存 profile，而不是接受草稿。** 对已配置好的提供方来说，不会有 secret 跨越协议层。但这样一来新增提供方就必须先保存一份不可用的配置，而端点已改却尚未保存的表单会静默地去询问旧地址。接受草稿让用户看见的与被询问的保持一致——凭据是唯一的例外，因为它是界面从不被展示、因而永远无法放进草稿的那个字段。
+**让 host 读已存 profile，而不是接受草稿。** 对已配置好的提供方来说，不会有机密跨越协议层。但这样一来新增提供方就必须先保存一份不可用的配置，而端点已改却尚未保存的表单会静默地去询问旧地址。接受草稿让用户看见的与被询问的保持一致——凭据是唯一的例外，因为它是界面从不被展示、因而永远无法放进草稿的那个字段。
 
 **询问 pi-ai 的每一种协议。** Anthropic 的列表恰好与 OpenAI 共用同一层信封，而 Google 的不是。只支持容易的那几种会让覆盖范围变得任意；更糟的是，猜错的响应形状会与「该提供方没有模型」无法区分。一个明说自己无法被询问的协议，会把用户送去手工填写——那正是既定的回退路径。
 
@@ -43,7 +43,7 @@ pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与
 
 接入网关的人可以直接问它服务什么，而不必去翻它的文档；答案以候选形式抵达，由用户自己挑选，而不是被背着写进配置。seam 因此多了一个刻意保持很小的注册表：每个 namespace 一份、不存储、除 fiber 外没有生命周期。
 
-代价是：协议层多了第三个承载 secret 的载荷，配置面的只写接口从两个方法变成三个。发现能力按协议而非按提供方划分——一个 Anthropic 兼容网关即便其列表能被解析，也仍须手工填写。而且由于没有任何环节会重跑该询问，模型列表的新鲜度依旧只到最近一次编辑为止；这与下层刻意做出的取舍是同一个。
+代价是：协议层多了第三个承载机密的载荷，配置面的只写接口从两个方法变成三个。发现能力按协议而非按提供方划分——一个 Anthropic 兼容网关即便其列表能被解析，也仍须手工填写。而且由于没有任何环节会重跑该询问，模型列表的新鲜度依旧只到最近一次编辑为止；这与下层刻意做出的取舍是同一个。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
index 2a4879b6aa..8596301883 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
 2026-08-04-websocket-downlink-carrier.md: b41ad687725c55acb8517fe7e93d645f007a0453
-2026-08-04-websocket-downlink-carrier.zh.md: 568240ec14592fba8444e5cc0a3bae2b35c45b94
+2026-08-04-websocket-downlink-carrier.zh.md: 054b91d6b5b8c061eab32e79c4353f6183bd200f
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
index 568240ec14..054b91d6b5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
@@ -12,17 +12,17 @@ Status: implemented
 
 浏览器真实载体为两类下行流各开一条独立 WebSocket：`/api/events.mux` 只发送 `MuxFrame`，`/api/events.host` 只发送 `HostFrame`。每条 text message 是一份完整的 `ServerRequest` JSON；客户端继续先校验信封，再按路径校验具体 frame union，并把窄形 `RpcRequest<Frame>` 交给既有 `ConnectionController`。两条流保持独立生命周期和无跨流顺序保证，任一条结束仍使整个 connection generation 失败并按既有退避策略重建。
 
-WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和对 server request 的 `respond` 继续使用既有 `POST /api/*`；不在 WebSocket 上接收任何客户端业务 message。`WebApiClient` 因而同时持有 HTTP `fetch` 上行与 WebSocket 下行，而 fixture 和 `InProcessApiClient(toFetchHandler(api))` 继续实现同一 `IApiClient` 双流抽象。进程内 fetch 载体保留 SSE 编解码来检验通道无关的协议同构，但网络 `/api/events.*` GET 只回答 upgrade required，不作为浏览器兼容回退。
+WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和对 server request 的 `respond` 继续使用既有 `POST /api/*`；不在 WebSocket 上接收任何客户端业务消息。`WebApiClient` 因而同时持有 HTTP `fetch` 上行与 WebSocket 下行，而 fixture（测试前置数据）和 `InProcessApiClient(toFetchHandler(api))` 继续实现同一 `IApiClient` 双流抽象。进程内 fetch 载体保留 SSE 编解码来检验通道无关的协议同构，但网络 `/api/events.*` GET 只回答 upgrade required，不作为浏览器兼容回退。
 
 ## Upgrade 与生命周期边界
 
-`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册缝，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket message。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和 stream cancellation，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
+`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册 seam，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket 消息。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和流取消，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
 
-浏览器 abort 或 socket close 会取消对应的 host stream；plugin teardown 还会等待该 source iterator 完成清理。host stream 中途抛错时，载体发送一份现有的 `stream/error` frame 后关闭 socket；客户端把该 frame 收敛为连接丢失，不投递给业务 sink。每条 WebSocket 独立报告 open，既有 readiness handshake 仍等待 mux、host 都 open 且 `host.describe` HTTP 调用成功后才发布 connected。
+浏览器 abort 或 socket close 会取消对应的 host 流；插件 teardown 还会等待该 source iterator 完成清理。host 流中途抛错时，载体发送一份现有的 `stream/error` frame 后关闭 socket；客户端把该 frame 收敛为连接丢失，不投递给业务 sink。每条 WebSocket 独立报告 open，既有 readiness handshake 仍等待 mux、host 都 open 且 `host.describe` HTTP 调用成功后才发布 connected。
 
 ## Verification
 
-webserver 契约测试钉住 upgrade pathname 分发、重复注册拒绝、disposer 与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、stream error 与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
+webserver 约定测试钉住 upgrade pathname 分发、重复注册拒绝、资源释放与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、流错误与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
 
 ## Alternatives considered
 
@@ -32,8 +32,8 @@ webserver 契约测试钉住 upgrade pathname 分发、重复注册拒绝、disp
 
 **保留网络 SSE 回退。** 双载体会让生产浏览器路径可因代理或握手差异静默分叉，并让连接上限问题继续存在于一个受支持分支；预发布阶段只交付 WebSocket 下行，失败由既有重连与连接状态显式呈现。
 
-**依赖 HTTP/2 扩大并发连接能力。** 内置开发服务器是明文 Node HTTP/1.1，部署前置代理也不是产品可依赖的不变式；物理下行应直接使用不受该连接池限制的浏览器原语。
+**依赖 HTTP/2 扩大并发连接能力。** 内置开发服务器是明文 Node HTTP/1.1，部署前置代理也不是产品可依赖的不变式；物理下行直接使用不受该连接池限制的浏览器原语。
 
 ## Consequences
 
-每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；runtime 继续消费原有双流并保留所有重连、补缝和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection host 半依赖 WebSocket 实现，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套业务协议。
+每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；运行时继续消费原有双流并保留所有重连、seam 修复和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection 包的 host 半部新增 WebSocket 实现依赖，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套应用协议。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
index 8a4b3606a8..a38ac586f7 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md
 2026-08-05-large-session-jsonl-restore-pipeline.md: eab53c683880ef7095233ed8122e532eb5add547
-2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 039e0c193179677b57e742d55f4c7df6bdff852f
+2026-08-05-large-session-jsonl-restore-pipeline.zh.md: e334afde3eacda4ab3c838eaae114acdfeb9bae8
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
index 039e0c1931..e334afde3e 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解码专用首帧并将其解析为会话头部，后续明文帧则按顺序产出并送入 JSONL 扫描器。
 
-`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误契约。迭代器产出的临时视图会在进入下一次迭代前被消费。
+`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持的 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误约定。迭代器产出的临时视图会在进入下一次迭代前被消费。
 
 累计帧处理时间约达 500 ms 后，异步读取器会在下一帧边界让出事件循环，并在继续前观察取消信号。单个帧仍是不可分割的同步操作。完整帧必须通过帧结束与校验和验证；只有结构上不完整的最终帧才使用既有前缀解码器进行恢复。
 
@@ -32,7 +32,7 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 
 持久化层把刚物化的 JSON 值转移给 `Session.fromRestore`。这些值是已分离且无环的树，打包的分片行也会展开成新分配的事件。因此，恢复专用路径使用一次 `for...in` 与 `switch` 校验固定事件信封，按事件判别字段执行当前数据形状检查，并通过显式 `pending` 数组迭代冻结所拥有的对象图，不使用循环跟踪集合。`surface` 校验会记录一次转换计划；当同一个候选事件进入日志时，系统直接提交该计划，不再对同一事件规划两次。
 
-普通创建与 fork 路径使用的借用 `seed` 仍会创建 JSON 快照，并使用支持循环检测的通用深度冻结。因此，这项特化仅改变持久恢复，不会放宽调用方所有值的准入要求。
+普通创建与 fork 路径使用的借用 `seed` 仍会创建 JSON 快照，并使用支持循环检测的通用深度冻结。因此，这项特化仅改变持久恢复，不会放宽调用方拥有的值的准入要求。
 
 ## 考虑过的替代方案
 
@@ -41,7 +41,7 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 - **扫描前拼接全部明文**：不予采纳，因为该方案会同时保留压缩输入、完整明文、整份日志的 UTF-8 字符串、行元数据和解析记录，并会重新扫描撕裂帧前缀。
 - **实现流式 JSON 解析器**：不予采纳，因为 JSONL 已提供记录边界；使用原生换行搜索与 `JSON.parse` 就能移除大型中间结构，无需自行维护另一套解析器或改变 JSON 语义。
 - **冻结恢复事件时共享一个 `WeakSet`**：不予采纳，因为 JSON 物化不可能产生循环引用，而该集合会对每个对象增加一次查找，并在遍历期间保留完整对象图。
-- **跳过恢复值的校验或冻结**：不予采纳，因为持久存储属于运行时边界，而 `Session.events` 承诺已接受历史不可变。优化路径利用更强的所有权事实特化这些操作，而不是将其移除。
+- **跳过恢复值的校验或冻结**：不予采纳，因为持久存储属于运行时边界，而 `Session.events` 承诺已接受的历史不可变。优化路径利用更强的所有权事实特化这些操作，而不是将其移除。
 
 ## 后果
 
@@ -49,4 +49,4 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 
 快速解码器依赖运行时探测的 Node 内部接口，但接口不兼容时会改用公共实现，不会改变正确性。系统会在协作式帧边界让出点观察取消信号；截止时间并不是单个帧内部严格的挂钟时间上限。完整事件数组仍会驻留内存，因为它是活跃会话的权威日志；该流水线移除的是重复表示，并未对这份状态做分页。
 
-测试会强制执行两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性契约。
+测试会强制使用两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性约定。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index 3e1d038514..be4726cb54 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
 2026-08-05-profile-plugin-bundles.md: 8613e600ad633818abb4319e614230340c3b3876
-2026-08-05-profile-plugin-bundles.zh.md: 03a771364c4f3262801f28e68b96ec5de633e5ec
+2026-08-05-profile-plugin-bundles.zh.md: 3a35f944e115371b5f4702bbe81ec9bc3c314ef0
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 03a771364c..3a35f944e1 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
+一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
 已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 - **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
-- **在组合包 manifest（元数据清单）中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index 09e63a6a1c..d59721303b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
 2026-08-05-session-preparation.md: 69d39f552ed3041403a24b5aefb435e4e721b09c
-2026-08-05-session-preparation.zh.md: a0ca27eb63552566c918c299bd5fba976687812c
+2026-08-05-session-preparation.zh.md: 23681c7cb52d670482bc83e665ec7731dea98bbd
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index a0ca27eb63..23681c7cb5 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -14,13 +14,13 @@ Status: implemented
 
 `SessionPreparation` 持有一个精确的未发布 `Session`，直至发布或回滚。它属于 Session 生命周期，不属于 agent 生命周期或激活机制。新建流程包装 `SessionStore.prepare()` 的结果；持久化恢复则从 `SessionPersistence.prepare()` 取得准备对象。
 
-agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上 dispose 准备对象。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
+agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上对准备对象执行 dispose（资源释放）。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
 
 该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-seams.md)中的发布边界，但不替换其所有权模型。
 
 ## 持久化准备生命周期
 
-使用协调器的持久化实现会将一个冷源加载为准备完成的 Session。后端转移新鲜、彼此无别名的元数据和事件，以及标识这些精确值的来源限定 revision；Session 恢复路径直接验证并冻结这些对象图，不再复制。协调器计算中断轮次的 closer，并且只构造一次精确的未发布 Session。其不可变 header 与平衡逻辑事件日志构成读取方借用的 `SessionInspection`，revision 则保留在持久化内部。
+使用协调器的持久化实现会将一个冷源加载为准备完成的 Session。后端转移新鲜、彼此无别名的元数据和事件，以及标识这些精确值的来源限定 revision；Session 恢复路径直接验证并冻结这些对象图，不再复制。协调器计算中断轮次的 closer，并且只构造一次精确的未发布 Session。其不可变 header 与已配平的逻辑事件日志构成读取方借用的 `SessionInspection`，revision 则保留在持久化内部。
 
 `inspect(id, signal?)` 不修改存储。合成 closer 只存在于准备完成的内存视图中，撕裂的物理尾部保持不变。同 id 调用方共享进行中的冷读。准备完成后，该对象可以进入每个协调器自己的 LRU；第一方后端可配置容量，默认保留五个。协调器复用保留源之前会读取该 id 的当前 revision；如果不匹配，就淘汰处于就绪阶段的源并重新完成冷实体化。已经进入提交或为恢复而预留的源仍由其所有者独占，因此并发检查会借用该不可变视图，直至发布或释放。
 
@@ -47,7 +47,7 @@ agent loop（智能体循环）通过同一条设置与发布流水线消费这
 
 ## 验证
 
-共享持久化契约覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
+共享持久化约定覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
index 43c5433343..db32a6923b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md
 2026-08-05-slot-declaration-injection.md: cb15125977c060144553d7cf75e3c2c26fb1b23b
-2026-08-05-slot-declaration-injection.zh.md: 385cab875bb445ba1ca324fc9b45363b8daf50b6
+2026-08-05-slot-declaration-injection.zh.md: e93ba5e62bbfc76b242a7383bac0e93c1bcc8ff6
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
index 385cab875b..e93ba5e62b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：slot 声明注入与重载生命周期
+# Agent Note: slot 声明注入与重载生命周期
 
 Status: implemented
 
@@ -20,7 +20,7 @@ slot 级热替换还要求两个相互独立的所有者。移除声明方插件
 
 动态重载代码使用普通 Cordis 插件 fiber 作为替换单元：通过 `ctx.plugin()` 激活新模块；挂载替换模块之前，先 dispose 并等待旧 fiber；该 fiber 的 `slots.inject` 与 `slots.register` effect 会随之退出。renderer 订阅会观察到账本移除并卸载组件；无需建立 slot 自有的 fiber 树。
 
-## 失败与生命周期契约
+## 失败与生命周期约定
 
 如果注入创建时声明已经存在，回调 setup 失败会同步上报。延迟声明出现后发生的回调失败，会先取消订阅并回滚已收集的 effect，再在 slot 通知刷新之外上报，避免一个注册方使其他 listener 得不到执行机会。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常：注入是显式机制，不会削弱加载时验证。
 
@@ -28,11 +28,11 @@ slot 级热替换还要求两个相互独立的所有者。移除声明方插件
 
 ## 备选方案
 
-**将 `ConversationService` 或其他服务用作顺序屏障。** 服务存在并不能标识相应声明，也不会跟随声明的重载生命周期；只负责呈现的贡献方还会因此产生虚假的包（package）依赖。
+**将 `ConversationService` 或其他服务用作顺序屏障。** 服务存在并不能标识相应声明，也不会跟随声明的重载生命周期；只负责呈现的贡献方还会因此产生虚假的包依赖。
 
-**将每项声明桥接为 `slot:<name>` Cordis 服务。** 这会污染服务命名空间，使拼错的动态 key 变成静默的服务等待，并把账本状态伪装成业务 capability。原生 slot 注入无需改变 Cordis 拓扑，即可提供同样的等待能力。
+**将每项声明桥接为 `slot:<name>` Cordis 服务。** 这会污染服务命名空间，使拼错的动态 key 变成静默的服务等待，并把账本状态伪装成业务能力。原生 slot 注入无需改变 Cordis 拓扑，即可提供同样的等待能力。
 
-**为每个 slot 创建 Cordis 上下文或 fiber。** 贡献方需要的是自身插件生命周期与声明生命周期的交集，而不是声明方的 capability。slot 所有的上下文会引入 capability 继承和双父级拆卸问题，却无法改善账本所有权。
+**为每个 slot 创建 Cordis 上下文或 fiber。** 贡献方需要的是自身插件生命周期与声明生命周期的交集，而不是声明方的能力。slot 所有的上下文会引入 capability 继承和双父级拆卸问题，却无法改善账本所有权。
 
 **让 `register()` 隐式等待。** 对未声明目标立即失败是一项有价值的配置检查。显式注入能够区分有意独立排序的贡献与错误组合。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
index b6e58aabc7..177796eea6 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.md
 2026-08-06-agent-event-payload-objects.md: 470c8fb3f9282005829846307778d3d1088c3888
-2026-08-06-agent-event-payload-objects.zh.md: ff201a7c3134c0ef809c9a798d65412541f9f1e7
+2026-08-06-agent-event-payload-objects.zh.md: 4e76dd97552a7e3cedb68c0e6c17779e77d68d4d
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
index ff201a7c31..4e76dd9755 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Agent 作用域事件 dispatch 单个 payload 对象
+# Agent Note: agent 作用域事件 dispatch 单个 payload 对象
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，契约也一直分散在参数列表中，而不是集中在一个具名 payload 中。
+agent（智能体）作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，约定也一直分散在参数列表中，而不是集中在一个具名 payload 中。
 
 ## 决策
 
@@ -18,7 +18,7 @@ dispatch 是融合的：`agentEvents(ctx, agent)`（以及一次性 `emitAgentEv
 
 ## 考虑过的替代方案
 
-**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，契约也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
+**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，约定也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
 
 **在每个 dispatch 位置手工构造主体。** loop 的中间设计调用 `ctx.waterfall(this.carrier, …)`，传入手工构造的 `{ agent: this, … }` payload；它避免了每次 dispatch 的分配，却重复了主体注入，并让作用域键与 payload 主体分叉。融合的 dispatcher 是每种 dispatch 模式的唯一注入点。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 0168528557..39340b3b70 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
 2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
-2026-08-06-subagent-list-identity-projection.zh.md: 368a70f5b3e5a27e4e1c648e8819476d40a57709
+2026-08-06-subagent-list-identity-projection.zh.md: 778d69fefc55ebcd10b195e21cd7222959e095e8
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index 368a70f5b3..778d69fefc 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -10,19 +10,19 @@ Status: implemented
 
 同一根因还有第二个症状：host 侧的 `hasSubagentDescriptor()` 在每次 Agent 绑定 RPC 的属主判定上扫描目标会话的 own suffix，即便 `SessionHeader.origin` 已经回答了同一个问题的绝大部分。
 
-根因在于 [durable-subagent-catalog 决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)把描述符事件（`subagent/descriptor`）定为目录的唯一持久权威，却没有为描述符读取配任何缓存层，并把逐 child 双读明确接受为"无索引的正确性基线"。[web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)（#1569）已把"是不是 subagent"放进了 header（`SessionHeader.origin`），身份判定不再读日志；mode 与 label 仍然要扫。
+根因在于 [durable-subagent-catalog 决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)把描述符事件（`subagent/descriptor`）定为目录的唯一持久权威，却没有为描述符读取配任何缓存层，并把逐 child 双读明确接受为「无索引的正确性基线」。[web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)（#1569）已把「是不是 subagent」放进了 header（`SessionHeader.origin`），身份判定不再读日志；mode 与 label 仍然要扫。
 
 ## 决策
 
-mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级"算完即止"阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
+mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级「算完即止」阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
 
 消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"曾是本记录的定稿方向并一度施工，最终整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
 
 要点：
 
 - **subagent 列表不依赖 session-query**：枚举由 subagent 自管的 live-preferred 合并完成，mode/label 经 `ctx.sessionProjections` 取值；没有 query backend 的部署照常列表。
-- **取值三级"算完即止"阶梯**：live child 读 `sessionProjections.snapshot()`（注册表既有水位缓存，零日志读）；cold child 先读可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 且过 seq 门（`seq >= seedLength ?? 0`）的 `subagent` 身份即直接用；否则一次 `persistence.inspect` 整读加 `registry.restore({}, events, 0)` 折叠；再没有就没有——不自建缓存、无回写、无索引。
-- **`subagent` projection unit 是折叠规则唯一权威**：live snapshot、cold restore、GUI history 的 detached 折叠全部经 registry 计算，不存在第二份描述符解释逻辑。
+- **取值三级「算完即止」阶梯**：live child 读 `sessionProjections.snapshot()`（注册表既有水位缓存，零日志读）；cold child 先读可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 且过 seq 门（`seq >= seedLength ?? 0`）的 `subagent` 身份即直接用；否则一次 `persistence.inspect` 整读加 `registry.restore({}, events, 0)` 折叠；再没有就没有——不自建缓存、无回写、无索引。
+- **`subagent` projection unit 是折叠规则唯一权威**：live 快照、cold restore、GUI history 的 detached 折叠全部经注册表计算，不存在第二份描述符解释逻辑。
 - **header、描述符（v2）、session-persistence、session-projection(-cache)、session-query(-sqlite) 全部零改动**；存量数据第一次被列表时一次 `inspect` 现算获得精确值，无 unknown 降级态、无迁移。
 
 与既有记录的关系：
@@ -62,7 +62,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 - **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署，cold child 本就无法 resume，列出 live child 仍然有意义。（对照：旧实现在 sessionQuery 缺失时整体拒绝。）
 - persistence 列表失败使整次枚举失败；per-child 隔离只作用于逐 child 的冷读。
 
-### 取值：三级"算完即止"阶梯
+### 取值：三级「算完即止」阶梯
 
 对每个枚举出的 child，mode/label 取值走三级阶梯——算完即止，不自建缓存、无回写（第三级与 apiproxy `session.history` 的冷读同款）：
 
@@ -78,12 +78,12 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 - 冷路径的生命周期见证：preparation 的结果必须仍指向枚举时的那个生命周期——见证字段集与旧 SOURCE_CONFLICT 检查同款七字段（version、id、createdAt、cwd、parentSession、seedLength、delegationDepth）；同 id 删除后重新发布的会话对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
 - 冷读并发以常数 4 有界——它约束的是本地介质的一次只读扫描而非部署行为；出现联网 persistence backend 时提升为验证过的 `Config` 字段。
 - 冷读成本如实记录：cache 未挂载或未命中时，cold child 每次列表才付一次整读，成本与其 transcript 大小成正比；定案"算完即止"，不自建缓存。整读经 `inspect()` 走 [Session 准备阶段](2026-08-05-session-preparation.md)的冷读，同 id 短期重复读取可命中其 LRU 复用，但列表不依赖此。live child 全程零日志读。
-- 取消：每次 persistence 读前后检查调用方 signal，abort 之后才结算的读拒绝归一化为稳定错误码 `CANCELLED`。
+- 取消：每次持久化读前后检查调用方 signal，abort 之后才结算的读拒绝归一化为稳定错误码 `CANCELLED`。
 
 ### 权威模型
 
 - session log 是唯一权威；本方案不新增任何派生持久化——没有索引值、没有自己的 checkpoint、没有进程 memo；第二级读取的 `sessionProjectionCache` checkpoint 是既有组合项的派生数据，本方案只读不写。取值现算现弃，值的新鲜度就是读取时点的 live 状态或持久化 revision（own descriptor 一经追加不可变——缓存身份过 seq 门后无陈旧性问题，门防的是种子回放的祖先身份）。
-- Session 与 persistence 写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
+- Session 与持久化写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
 - 枚举与取值不构成第二个鉴权来源，也不让尚未发布的 child 可见——两个来源只见已发布的 live 记录与已落盘的持久化记录，与 durable-subagent-catalog 记录对派生读面立下的规则一致。
 
 ### `listChildren` 行形状与消费面
@@ -124,7 +124,7 @@ export type SubagentListEntry =
 已知边界偏差（有意接受，随本记录留档）：
 
 - 死于发布窗口的 fork child，seed 里若有祖先描述符，last-wins 会给出祖先身份，误现为 child 行；恢复仍按 own-suffix 折叠权威失败（`NOT_RESUMABLE`）。旧实现靠 `seedLength` 过滤将其 omit；projection unit 看不到 header，接受此残骸级偏差（`subagentTiming` 有同类既有暴露）。
-- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 契约本就保证恰一）。
+- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（提供方约定本就保证恰一）。
 - live/persisted header 冲突，旧实现是 per-child corrupt；现枚举 live 优先、不做一致性校验，冲突不再被察觉，以 live 记录成行。
 - 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child `corrupt`，现统一成 `unavailable` 行（读侧无从区分成因）。
 - 未知 parent，旧实现经 session-query 抛 not-found（'parent session … was not found'）；现自管合并对不存在的 parent 得到空子集，枚举返回空列表，wire 上后续操作落到 child 级 subagent-not-found——语义与文案的静默变化，显式接受。
@@ -147,13 +147,13 @@ export type SubagentListEntry =
 
 **mode/label 进 SessionHeader。** 零读保证最强——列表只看 header 就能成行。但 header 形状变更传导两个 persistence backend 与 header 兼容检查；SQLite 存量直接拒收，JSONL 存量只能 unknown 降级或 backfill。读时现算对存量的答案是"第一次列表一次 `inspect` 现算"，不碰持久格式。
 
-**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
+**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
 
 **给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
 **list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强契约加算不出即 omit 更干净。
 
-**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+**彻底删除 diagnostic 行（v5 一稿）。** 删除会让库损坏不再可见、让行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
 
 **registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
index 20d21565b5..bb791431f5 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md
 2026-08-06-web-markdown-incremental-ast-renderer.md: 3599bfcc78dc4eefe5e82f461a469bdba15f3aae
-2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 2e00977da58ef29a77c45abcecf0f3bb62737929
+2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 1934953a704319a5cde3f7bf2182982ecc5ea527
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
index 2e00977da5..1934953a70 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
@@ -6,19 +6,19 @@ Status: implemented
 
 ## Problem
 
-`MarkdownText` 在每次流式发布时都重新解析整个已累积的回复:react-markdown 的纯字符串 API 每次渲染都新建 unified processor,并对全文跑完 micromark → mdast → hast → React,因此每个 chunk 的主线程工作量随回复长度线性增长,整个流的累计成本随之二次增长。既有缓解手段(帧级合并、隔离的流式尾部、围栏 plain 臂)约束的是这份工作跑多频繁、波及多广,从未约束每次重新解析多少文本。修复它需要 AST 级输入——冻结已定型的块、只重新解析源文本尾部——这是纯字符串封装在结构上无法表达的。
+`MarkdownText` 在每次流式发布时都重新解析整个已累积的回复：react-markdown 的纯字符串 API 每次渲染都新建 unified processor，并对全文跑完 micromark → mdast → hast → React，因此每个分片的主线程工作量随回复长度线性增长，整个流的累计成本随之二次增长。既有缓解手段（帧级合并、隔离的流式尾部、纯文本围栏分支）约束的是这份工作跑多频繁、波及多广，从未约束每次重新解析多少文本。修复它需要 AST 级输入——冻结已定型的块、只重新解析源文本尾部——这是纯字符串包装层在结构上无法表达的。
 
 ## Decision
 
-`MarkdownText` 直接渲染 mdast,并在流式期间增量解析:
+`MarkdownText` 直接渲染 mdast，并在流式期间增量解析：
 
 - **语法**([parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts)):`parseGfm`(流式臂与 `extractMarkdownPlainText`)和 `parseGfmWithMath`(定稿臂)以被替换的 remark 插件所包装的同一组 micromark 扩展调用 `mdast-util-from-markdown`,因此各处块边界完全一致。`mathCompatibility`(原 `remarkMathCompatibility`)现在直接导出其 micromark 扩展。
 - **增量解析**([incremental.ts](../../../../packages/client/ui-primitives/src/markdown/incremental.ts)):CommonMark 块解析按行推进,追加文本只会重塑解析前沿。`IncrementalMarkdownParser` 保留末尾两个块不稳定(最后一块是前沿;倒数第二块是安全裕量),冻结其前的所有块,只从最后一个冻结块的 `position.end.offset` 起重新解析源尾部——用的是解析器自己的偏移量,没有任何自制源扫描。每个源区间在整个流中解析 O(1) 次而非每 chunk 一次;单个巨型块(未闭合围栏)退化为旧的全量重解析成本,不会更差。非追加输入在递增的 generation 下重置状态。
-- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性契约范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
+- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换流水线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性约定范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
 
-DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
+DOM 由 `tests/fixtures/markdown-dom` 钉死：fixture（测试前置数据）录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
 
-这推翻了[助手 Markdown Note](../feature/2026-07-23-web-assistant-markdown.md) 中被否决的备选("维护一个自定义 React walker"):增量需求是当时不存在的新证据,walker 的安全敏感分支(URL 白名单、图片策略、惰性 HTML)本就是产品自有函数,而该依赖不再删减自有代码——它阻塞了架构。该 Note 的不可信输出策略与渲染器选型不变。
+这推翻了[助手 Markdown Note](../feature/2026-07-23-web-assistant-markdown.md) 中被否决的备选（「维护一个自定义 React walker」）：增量需求是当时不存在的新证据,walker 的安全敏感分支(URL 白名单、图片策略、惰性 HTML)本就是产品自有函数,而该依赖不再删减自有代码——它阻塞了架构。该 Note 的不可信输出策略与渲染器选型不变。
 
 ## Alternatives considered
 
@@ -30,4 +30,4 @@ DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react
 
 ## Consequences
 
-流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 契约对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
+流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 约定对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
index 815f5eee75..3b80f87a89 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
 2026-08-06-web-shell-dist-chunk-layout.md: 1c7b4273dc243685317b149e2fd7fddf2a6c18d1
-2026-08-06-web-shell-dist-chunk-layout.zh.md: 6f4b94e0bd7412e480458e34922273b389aa8892
+2026-08-06-web-shell-dist-chunk-layout.zh.md: d1435215d3c077efc3afaac7b3a7a1c2e2ffdae7
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
index 6f4b94e0bd..d1435215d3 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web 壳产物的 chunk 切分与目录布局
+# Agent Note: Web 壳产物的分片拆分与目录布局
 
 Status: implemented
 
@@ -6,26 +6,26 @@ Status: implemented
 
 ## Problem
 
-apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其中约八成是 vendor 字节——KaTeX、boot 语法与 shiki 引擎、react-dom、markdown 管线——与全部 workspace 壳代码（约五分之一）熔在一起。任何一行壳代码改动都让整个 chunk 换哈希，回头客户端全量重新下载；`dist/assets/` 是 100 多个文件的单层平铺（主 chunk、23 个懒加载语法 chunk、59 个 KaTeX 字体面、sourcemap 混居），无从导航。
+apps/web 的壳此前打成单一约 1.2 MB（minified）的 index 分片，其中约八成是 vendor 字节——KaTeX、boot 语法与 shiki 引擎、react-dom、markdown 流水线——与全部 workspace 壳代码（约五分之一）熔在一起。任何一行壳代码改动都让整个 chunk 换哈希，再次访问的客户端全量重新下载；`dist/assets/` 是 100 多个文件的单层平铺（主分片、23 个懒加载语法 chunk、59 个 KaTeX 字体面、sourcemap 混居），无从导航。
 
 ## Decision
 
-`apps/web/vite.config.ts` 以 `manualChunks` 把壳切成两个初始 chunk，并以输出命名函数归类目录；整套配置零正则——精确包名 Set、文件名清单、扩展名清单。
+`apps/web/vite.config.ts` 以 `manualChunks` 把壳切成两个初始分片，并以输出命名函数归类目录；整套配置零正则——精确包名 Set、文件名清单、扩展名清单。
 
 **成员归属**（`VENDOR_PACKAGES`，按精确 npm 包名）：
 
-- `vendor` = 三个重渲染家族：math（katex）、highlight（shiki）、markdown（micromark/mdast 解析管线——其上的增量 React 渲染器是 workspace 代码，不在此列）。成员以 `VENDOR_PACKAGES` 为活口径，清单 = workspace 代码**直接 import** 的包：其余私有传递依赖（oniguruma 系、@shikijs/core、字符表等数十个）只被清单成员引用，rollup 的 chunk 着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
-- **vendor 全员必须 react-free（边界不变量）**：rollup 会把入口与 manual chunk 共享的模块并入 manual chunk——清单里出现任何 import react/jsx-runtime 的包，唯一一份 react 副本就会被拽进 vendor、脱离 index。markdown/math 的 React 渲染侧是 workspace 代码天然住 index，react 族因此全部钉在 index。
-- `index`（默认 chunk）= react 族（react、react-dom、scheduler、use-sync-external-store）、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
+- `vendor` = 三个重渲染家族：math（katex）、highlight（shiki）、markdown（micromark/mdast 解析流水线——其上的增量 React 渲染器是 workspace 代码，不在此列）。成员以 `VENDOR_PACKAGES` 为活口径，清单 = workspace 代码**直接 import** 的包：其余私有传递依赖（oniguruma 系、@shikijs/core、字符表等数十个）只被清单成员引用，rollup 的分片着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
+- **vendor 全员必须 react-free（边界不变量）**：rollup 会把入口与 manual chunk 共享的模块并入 manual chunk——清单里出现任何 import react/jsx-runtime 的包，唯一一份 react 副本就会被拽进 vendor、脱离 index。markdown/math 的 React 渲染侧是 workspace 代码，天然住 index，react 族因此全部钉在 index。
+- `index`（默认分片）= react 族（react、react-dom、scheduler、use-sync-external-store）、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
 - `@shikijs/langs` 特判：boot 语法（`BOOT_GRAMMAR_FILES`：typescript、shellscript、json——highlight.ts 静态 import 的三件，均为零内部 import 的自含数据模块）进 vendor；其余 23 个懒加载语法不做指派，各自保持按需 chunk。
-- `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两 chunk 并行拉取，无瀑布。
+- `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两个分片并行拉取，无串行加载瀑布。
 
 **目录布局**（`chunkFileNames` + `assetFileNames`）：
 
 - `assets/` 根只留 index 与 vendor 的 js（含随行 sourcemap）与 css。
 - 语法 chunk 归 `assets/langs/`。判据是 chunk 的 `moduleIds` 含 `@shikijs/langs` 成员，而非 facade：内嵌语法共享 chunk（php/ruby/mdx 内嵌 html+javascript，被 rollup 拆出共享）**没有 facade**，facade 判据会漏；index/vendor 按名排除，因 vendor 合法携带 boot 三语法。
-- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字面——katex.min.css 虽由 index 侧组件 import，css 模块同样经 manualChunks 归属、随 `katex` 落入 vendor.css；浏览器按需只拉 woff2，且仅在公式渲染时）。
-- sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，chunk 挪目录 map 自动跟随。
+- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字体面——katex.min.css 虽由 index 侧组件 import，css 模块同样经 manualChunks 归属、随 `katex` 落入 vendor.css；浏览器按需只拉 woff2，且仅在公式渲染时）。
+- sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，分片挪目录时 map 自动跟随。
 
 跨目录引用（index 的动态 import 指向 `langs/`、语法 chunk 间同目录相对引用、vendor.css 相对引用 `fonts/`）均由构建器生成，运行时零配套改动；host 侧 webserver 按静态前缀原样服务嵌套路径。
 
@@ -40,11 +40,11 @@ apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其
 
 ## Verification
 
-审计工具随库：`node scripts/attribute-chunk-bytes.mjs <chunk.js>`（零依赖 sourcemap VLQ 字节归属，按 npm 包/workspace 目录聚合）。以其复核：vendor 不含任何 workspace 字节、react 族（含 react/jsx-runtime）全量位于 index、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（本机环境性红除外），两 chunk 壳装载渲染无回归。
+审计工具随库：`node scripts/attribute-chunk-bytes.mjs <chunk.js>`（零依赖 sourcemap VLQ 字节归属，按 npm 包/workspace 目录聚合）。以其复核：vendor 不含任何 workspace 字节、react 族（含 react/jsx-runtime）全量位于 index、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（特定于本机环境的报红除外），双分片壳装载渲染无回归。
 
 ## Consequences
 
 - 壳代码改动只重哈希 index（约为产物三分之一）；vendor（约三分之二）跨壳版本缓存稳定，仅依赖升级时失效。
 - `dist/assets/` 可导航：根两对 js/css，`langs/` 按需语法，`fonts/` 字体。
 - 维护成本：workspace 代码新增对某渲染家族门面包的直接 import 时需同步 `VENDOR_PACKAGES`（漏列仅稀释 index，不致坏）；在 highlight.ts 扩 boot 语法集而未同步 `BOOT_GRAMMAR_FILES` 时，该语法静默落入 index，仅产物审计可见。
-- webserver 静态面尚无压缩，gzip 体量是潜在值；传输层压缩是另一项独立决策。
+- webserver 静态面尚无压缩，gzip 体积收益仍有待实现；传输层压缩是另一项独立决策。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index 05c9a1fdd2..0a84e714f2 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
 2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
-2026-08-08-bounded-session-persistence-write-batching.zh.md: 4aafdd652aad87cfe74a449428cdbbf13312d260
+2026-08-08-bounded-session-persistence-write-batching.zh.md: 1713dc0cf4280b12e1be871d5cecc64569276106
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index 4aafdd652a..1713dc0cf4 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -26,7 +26,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 `writeBatchMaxDelayMs` 只限制控制器为批处理而主动等待的时间。事件循环调度、初始化、此前的串行化操作和后端 I/O 都可能延后持久化完成时间，因此该选项并不对 fsync 完成时间或崩溃数据丢失提供硬性 SLA。
 
-`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。Session 退役与后端 dispose（资源释放）共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
+`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。会话退役与后端 dispose（资源释放）共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
 
 每个事件仍会按原有顺序和形态持久化。控制器会在接纳时复制每个事件；任何 `assistant/chunk`、`seq`、`time`、surface 元数据或存储记录都不会被删除或重写。因此，JSONL 可以在一个追加帧中编码更多事件，SQLite 可以在一个事务中插入更多事件行，而无需改变任一种磁盘格式或 schema 版本。
 
@@ -38,7 +38,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 **不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
 
-**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序契约。
+**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
 
 **按最新事件重置防抖窗口。** 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
 
@@ -46,14 +46,14 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 ## 验证
 
-控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化契约。
+控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化约定。
 
 ## 后果
 
 高频事件突发通常会减少持久化追加操作，同时保持逻辑事件数量完全不变。减少幅度取决于事件到达速率和后端延迟：位于同一 200 ms 窗口内的突发事件会成为一个批次，而强制 flush 与稀疏事件仍可能产生小批次。
 
-本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放契约，而不是再引入一条隐式计时器规则。
+本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放约定，而不是再引入一条隐式计时器规则。
 
 接纳后的事件在配置窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。部署可以选择较小的值以缩短普通丢失窗口，也可以选择较大的值以加强批处理。显式持久性边界保持不变，并会绕过等待。
 
-新的 deep module 让计时器、活跃写入、待处理前缀、重试暂停和屏障由一个所有方统一负责。`PersistenceCoordinator` 继续负责初始化和按标识串行化；后端仍只负责持久存储原语。`SESSION_FORMAT_VERSION` 与 SQLite `SCHEMA_VERSION` 均不变。
+新的 deep module 统一负责计时器、活跃写入、待处理前缀、重试暂停和屏障。`PersistenceCoordinator` 继续负责初始化和按标识串行化；后端仍只负责持久存储原语。`SESSION_FORMAT_VERSION` 与 SQLite `SCHEMA_VERSION` 均不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index e1beb13c2c..514f36ed36 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
 2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
-2026-08-08-client-tool-presentation-ownership.zh.md: 11a42ad69e4374afa6dccd3af74b8bd1b5e5c6f1
+2026-08-08-client-tool-presentation-ownership.zh.md: 18a6f5ba45f4ec470ea94c440ce4fa65c1bc6cdc
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 11a42ad69e..18a6f5ba45 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Client Tool 展示所有权
+# Agent Note: Client 工具展示所有权
 
 Status: implemented
 
@@ -6,25 +6,25 @@ Status: implemented
 
 ## Problem
 
-Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
+Client 运行时已经把工具调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
 
-这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排契约。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的工具专属编排约定。增加工具专属会话 projection 会重复运行时已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
 
 ## Decision
 
-Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Runtime 将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
+工具成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。运行时将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
 
-这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
+这里的「一级概念」只描述 UI 所有权，不增加运行时数据种类。`ConversationNode` 仍是 transcript（文本记录）projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
 
 `ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
 
 `ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
 
-业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。skill（技能）仍是普通工具，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
 
 details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
 
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
+运行时仍是工具生命周期与调用拓扑的权威。Code Dispatch 因会改变 parent/child identity 而成为官方顶级概念；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
 
 ## Runtime 与渲染链路
 
@@ -46,7 +46,7 @@ ConversationSnapshot.runningCalls     |
                                                                `- GenericToolCard fallback
 ```
 
-Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供 Live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
+Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供实时 [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
 
 [`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。selection 只传给包含该 call 的 root，`ToolCallTree` 再沿该 root 的局部树递归渲染。
 
@@ -54,19 +54,19 @@ Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sess
 
 | 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
 |---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、snapshot 结构共享 | Tool 名称对应的业务视图 |
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、快照结构共享 | Tool 名称对应的业务视图 |
 | `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
 | `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
 | 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
 | details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
 
-## Slot 与 owner 契约
+## Slot 与 owner 约定
 
 slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
 
 整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
 
-席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 契约：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
+席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 约定：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
 
 业务插件遵循同一个注册形态：
 
@@ -86,7 +86,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Verification
 
-测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主契约；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主约定；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
 
 ## Alternatives considered
 
@@ -94,7 +94,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 **只移动 Tool React 组件与 card model。** 拒绝：`ChatView` 仍会拥有 Tool 名称分发与 Code Dispatch 编排，只是改变文件路径，没有改变责任。
 
-**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
+**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的功能才应获得运行时级扩展。
 
 **让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。递归 root/child 编排统一归 `ui-tool` 的 `ToolCallTree`。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
index 6e2c9a635d..0d29db621d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
 2026-07-20-config-hot-reload-resilience.md: 2b98ee73e1c7734da9c0ae6df5e3de1af6a5cbeb
-2026-07-20-config-hot-reload-resilience.zh.md: 4ddf1f07f4ff5449f3bd91aa2b38f6045eb4e1c6
+2026-07-20-config-hot-reload-resilience.zh.md: 0a3652a7cac589b601d7fd30d0c713d4585be830
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
index 4ddf1f07f4..0a3652a7ca 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-无效的 `cordis.yml` 编辑不得杀死运行中的 agent（智能体）；但若一次看似有效的更新先部分替换 Loader 树，后续配置项才失败，仅仅保住进程仍不够。调用方还需要能观察到被拒绝的实时更新，同时不能让同一个错误被当作未处理的启动失败。个人配置还带来第二项要求：HMR（热模块替换）必须观察其模块根目录之外的一个确切文件，包括启动后才创建的文件或父目录。
+无效的 `cordis.yml` 编辑不得杀死运行中的 agent（智能体）；但若一次看似有效的更新先部分替换 Loader 树，后续配置项才失败，仅仅保住进程仍不够。调用方还需要能观察到被拒绝的实时更新，同时不能让同一个错误被当作未处理的启动失败。个人配置还带来第二项要求：HMR（热模块替换）必须观察其模块根目录之外的一个确切文件，即使该文件或其父目录在启动后才创建也不例外。
 
 ## Decision
 
@@ -16,7 +16,7 @@ vendor 中的 Cordis 生命周期和 Loader 插件提供可等待、带补偿的
 
 Loader 会先导入变化后的模块名，再 dispose（资源释放）活动 fiber。它会 await 候选项的应用；若失败，则 dispose 候选项的 effect，并恢复先前的插件或配置。组内对账会并发启动各候选项，等待每项结果，并会在拒绝前恢复已变更的配置项、添加项、移除项和移动项。只有程序化变更成功后才会持久化。这是一种补偿事务：生命周期 effect 可能短暂可见；回滚失败会报告为 `AggregateError`，而不会被误称为树已保留。
 
-Include 读取并校验尚未提交的候选内容，把补丁应用到其副本，对账 Loader 树，然后才提交缓存内容和解析数据。解析、校验、应用或回滚失败后，`refresh()` 会向调用方 reject。初始加载继续快速失败；只有文件不存在时才可以使用 `initial`。YAML/JSON 结果若不是数组即为无效；文件刷新和 Include 配置更新都会重新应用补丁，且不修改缓存的解析结果。
+Include 读取并校验尚未提交的候选内容，把补丁应用到其副本，对账 Loader 树，然后才提交缓存内容和解析数据。解析、校验、应用或回滚失败后，`refresh()` 会向调用方 reject。初始加载仍会明确报错；只有文件不存在时才可以使用 `initial`。YAML/JSON 结果若不是数组即为无效；文件刷新和 Include 配置更新都会重新应用补丁，且不修改缓存的解析结果。
 
 HMR 收容实时刷新 rejection。其 `registerConfig(filename, refresh)` 方法从最近的现有祖先目录开始监听一个确切路径，串行化并合并刷新，并返回一个异步 disposer；该 disposer 会关闭 watcher 并排空活跃工作。确切路径和普通配置文件的刷新都使用此队列。失败会被规范化为 `Error`、记入日志，并通过并行事件 `hmr/config-update-failed(filename, error)` 广播；发生 rejection 的观察者会被记录，但不会阻止后续刷新。创建、变更和移除均会被观察。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
index 6a898fa0a4..6b430602ec 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md
 2026-07-27-glob-sampling.md: 67912cf290b127a96819d57f30387197af68323d
-2026-07-27-glob-sampling.zh.md: e339a5f87b483849df60feb726b061fe85074300
+2026-07-27-glob-sampling.zh.md: 400df369e2a537abbd8c49e0df02cd0b80f86f1b
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
index e339a5f87b..400df369e2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
@@ -20,21 +20,21 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**只保留按修改时间排序的前部。** 测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
+**只保留按修改时间排序的前部。**测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
 
-**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式契约，因此每个组合都必须选择一种，配置错误则在加载时失败。
+**为采样选项提供默认值。**否决。没有全产品范围的证据支持把任一排序作为隐式约定，因此每个组合都必须选择一种，配置错误则在加载时失败。
 
-**对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
+**对所有结果采样。**否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
 
-**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先契约，也没有让受限页面更具代表性。
+**改为最新优先排序。**否决。这只会改变哪一棵结果密集的子树可能占据主导；既取消了现有的最旧优先约定，也没有让受限页面更具代表性。
 
-**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序契约。现有上限是可以清楚解释的切换点。
+**仅在偏斜超过阈值时采样。**否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序约定。现有上限是可以清楚解释的切换点。
 
-**在顶层以下递归平衡。** 暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。
+**在顶层以下递归平衡。**暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。
 
-**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照契约，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
+**新增面向模型的 `list` 工具。**实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照约定，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
 
-**拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。** 否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。
+**拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。**否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
index 7950dc88f3..1eb96e4d24 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
 2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 51d668f584ee254183d5d1cf709140df2556e8d0
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: c0577e158e111651c917a43b7aa65f1d904d7af1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
index 51d668f584..c0577e158e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
@@ -20,9 +20,9 @@ Status: implemented
 
 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。
 
-两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
+两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定约定，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 Agent Note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
 
-`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。
+`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
 
 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。
 
@@ -42,7 +42,7 @@ Status: implemented
 
 **把这两个属性绑定在 `html` 上。** 这是文档级皮肤最自然的落点，而它的失败是可测量的：规则挂在 `html` 上时，chromium 中滚动容器计算出的 `scrollbar-color` 为 `auto`，因为别名 token 在那个作用域内不存在。
 
-**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定契约——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
+**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定约定——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
 
 **不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 这正是本次变更最初提交的形态，被评审发现。在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
 
@@ -57,7 +57,7 @@ Status: implemented
 - 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。侧边栏内的滚动区域经由同一组间接变量，只在指针到达时才绘制滑块。
 - 两种渲染分别指定，因此改动滑块的几何或 hover 行为需要改两处：一处在 `scrollbar-width`／`scrollbar-color`，一处在伪元素。让两者都经由这组间接变量，把这份重复限制在 Firefox 与 WebKit 不共用的那些属性上。
 - hover token（`--dsw-alias-scrollbar-hover-l1`／`-l2`）只在伪元素路径上渲染。Firefox 通过 `scrollbar-color` 只表述一个滑块颜色，其 hover 表现由引擎自行推导，因此对 hover 颜色的设计改动在 Chromium 与 Safari 上可见，在 Firefox 上不可见。这是 `scrollbar-color` 本身的限制，不是这张样式表的限制。
-- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定契约。
+- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定约定。
 - 工作区列表在任何列表长度下都永久少了预留空位那一条宽度。这正是该修复换来的代价：以稳定的行几何，换掉只在列表较短时才可读的时间戳。
 - 调色板中没有轨道 token，因此日后若设计需要不透明轨道，要新增一个别名 token，而不是在这张样式表里写字面颜色。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
index 967a0ebcf4..d40bdb486e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
 2026-07-28-web-agent-runtime-context.md: 6c2bb8faf0db56d2a29b47726ab295c3501cce2d
-2026-07-28-web-agent-runtime-context.zh.md: 09cbbdeabc244c265381b1ad67c3629b4c0763f5
+2026-07-28-web-agent-runtime-context.zh.md: 810f5df6712116baf1d00a7040f6f7be9b73fea1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
index 09cbbdeabc..810f5df671 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
@@ -6,27 +6,27 @@ Status: implemented
 
 ## 问题
 
-CLI 共享 base 配置了空的部署 persona，Web overlay 没有替换它，而 Web 启动器既未添加源码提示词段，也未添加交互界面提示词段。会话 header 会记录工作目录，供工具与持久化使用，但模型提示词既不说明该目录，也不标识 DeepSeek Harness Web GUI。因此，当用户提出「修改这个页面的主题」之类的请求时，即使用户指的是承载当前会话的 GUI，agent 也只能在所选项目中搜索一个未明确说明的页面。
+CLI（命令行界面）共享 base 配置了空的部署 persona，Web overlay 没有替换它，而 Web 启动器既未添加源码提示词段，也未添加交互界面提示词段。会话 header 会记录工作目录，供工具与持久化使用，但模型提示词既不说明该目录，也不标识 DeepSeek Harness Web GUI。因此，当用户提出「修改这个页面的主题」之类的请求时，即使用户指的是承载当前会话的 GUI，agent（智能体）也会在所选项目中搜索一个未明确说明的页面。
 
 ## 决策
 
-Web profile 会组合 `dsh-base` 与 `dsh-web-app` 两个组合包。Web 组合包提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`；当 `surfaceContext` 为 true 时，其 `web-runtime` 插件会添加 `app:web-surface` 提示词段。挂载 profile 配置树前，`dsh web` 别名会读取组合后的同一项设置，并且仅在启用表层上下文时安装现有的 `harness:source` 提示词段。无头组合包和拥有完整提示词的 profile 都会设置 `surfaceContext: false`，从而抑制 Web 提示词与受管 shell 事实；Web 别名也会抑制源码提示词段，而无需检查 overlay 路径。每项已挂载的提示词贡献仍会在 agent loop（智能体循环）等消费方发出 request header 前激活。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
+Web profile 会组合 `dsh-base` 与 `dsh-web-app` 两个组合包。Web 组合包提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`；当 `surfaceContext` 为 true 时，其 `web-runtime` 插件会添加 `app:web-surface` 提示词段。挂载 profile 配置树前，`dsh web` 别名会读取组合后的同一项设置，并且仅在启用界面上下文时安装现有的 `harness:source` 提示词段。无头组合包和拥有完整提示词的 profile 都会设置 `surfaceContext: false`，从而抑制 Web 提示词与受管 shell 事实；Web 别名也会抑制源码提示词段，而无需检查 overlay 路径。每项已挂载的提示词贡献仍会在 agent loop（智能体循环）等消费方发出 request header 前激活。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
 
 Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应用」解释为 DeepSeek Harness Web GUI。同时，它会明确说明浏览器不会隐式提供 DOM、路由或截图上下文，使模型能够识别产品，但不会声称掌握未收到的视觉状态。组装后的文本会记录在 `request/header` 中，从而保持「模型可见内容必须有日志记录」这一不变量。
 
 ## 验证
 
-Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为，Web 别名单元测试则会固定组合后配置行对源码提示词段的默认启用与显式禁用门控。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web 组合包，通过 HTTP／SSE 应用运行一个真实会话，并在规范化源码路径与工作目录后对系统提示词前缀生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。Core Web 快照会应用 RL overlay，并固定不含源码提示词段或 Web 提示词段的完整系统提示词。
+Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为，Web 别名单元测试则会固定组合后配置行对源码提示词段的默认启用与显式禁用门控。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web 组合包，通过 HTTP／SSE（Server-Sent Events）应用运行一个真实会话，并在规范化源码路径与工作目录后对系统提示词前缀生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。Core Web 快照会应用 RL overlay，并固定不含源码提示词段或 Web 提示词段的完整系统提示词。
 
 ## 考虑过的替代方案
 
-**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息契约中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
+**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息约定中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
 
 **要求会话 Workspace 必须是 harness checkout。** Workspace cwd 是用户任务的目标，可以合理地指向空项目或其他仓库。将其与应用源码位置混为一谈会破坏这一边界，并且仍无法消除已安装版本或外部启动会话中的歧义。
 
-**把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
+**把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP（Agent Client Protocol）、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
 
-**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用契约，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
+**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用约定，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
index 0e8b50db1a..ba1531be74 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
 2026-07-28-web-gui-feedback-loop.md: aa488e1df087722c072d98c67d47cdf63a42f6b8
-2026-07-28-web-gui-feedback-loop.zh.md: d9de988e5a2cc57794ff628b65eb050dee610747
+2026-07-28-web-gui-feedback-loop.zh.md: 17d25eaf8ec49423b554b7993ff7f9e267f7c91c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
index d9de988e5a..17d25eaf8e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
@@ -8,21 +8,21 @@ Status: implemented
 
 Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道用户正在查看哪个 URL。[运行时上下文决策](2026-07-28-web-agent-runtime-context.md)提供前一项事实，但 GUI 编辑仍然没有可执行的验收目标：源码编辑、产物构建、监听中的进程与用户已打开的页面只是互不关联的观察结果。仓库提供的入口让错误的替代方案显得合理，因为 `apps/web/package.json` 将 `vite` 暴露为 `dev` 脚本，而裸 Vite 即使无法注入 `window.__DSH_BOOT__`，仍会返回 HTTP 200。
 
-[事故复盘](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)集中记录事件日志时间线，并解释原有检查为何会接受错误的页面、进程和端口。
+[事故复盘（postmortem）](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)集中记录事件日志时间线，并解释原有检查为何会接受错误的页面、进程和端口。
 
 ## 决策
 
 常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
 
-按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
+按模式区分的提示词让 agent 而非用户负责隐藏的启动约定。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
 
 `apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。
 
-静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
+静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务约定负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
 
 ## 验证
 
-无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发契约。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
+无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI（命令行界面）冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发约定。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
 
 ## 考虑过的替代方案
 
@@ -36,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 影响
 
-常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
+常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式约定会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index cbc9924c07..7bce30803e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
 2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: 909f0756dd29c9deddb840a188eb19a773f92d29
+2026-07-29-human-transcript-append-origin.zh.md: ad952b697a11bd8f2d72785ec013bcf3e973db04
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index 909f0756dd..ad952b697a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -1,53 +1,53 @@
-# Agent Note: 人类可读记录投影追加来源的事件
+# Agent Note: 人类 transcript 投影追加来源的事件
 
 Status: implemented
 
 [English](2026-07-29-human-transcript-append-origin.md) | 中文
 
-## Problem
+## 问题
 
-终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
+终端与宿主历史网关都把模型可见的 surface 当作人类 transcript（文本记录）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
 
 日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。
 
-## Decision
+## 决策
 
-模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是记录的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。
+模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是 transcript 的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。
 
-终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
+终端从追加来源的 surface 事件回放 transcript，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的 transcript。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
 
-检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+检查点通过压缩seam自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
 `session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
 
-持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
+已持久化事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
 
-## Deferred
+## 延后事项
 
-浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。
+浏览器客户端在[Web transcript 投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份追加来源 transcript并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝这个检查点。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，旧规则会把整段被遮蔽的范围一起拉到该页。
 
 终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的契约，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。seam已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
 
 **继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
 
-**持久化第二份展示用记录。** 被否决：仅追加的日志已经包含权威源材料，平行记录换不来任何东西，反而增加迁移与一致性工作。
+**持久化第二份展示用 transcript。** 被否决：仅追加的日志已经包含权威源材料，平行 transcript换不来任何东西，反而增加迁移与一致性工作。
 
-**用 `compact/*` 括号而不是检查点来推导标记。** 就记录而言被否决：括号是围绕一次操作的一对时间点标记，而记录需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
+**用 `compact/*` 括号而不是检查点来推导标记。** 就 transcript 而言被否决：括号是围绕一次操作的一对时间点标记，而 transcript 需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
 
 **像 `session-query` 为搜索所做的那样重新折叠日志来分类事件（`current`／`shadowed`／`log-only`）。** 被否决：折叠回答的是整份日志的问题，而投影问的是逐事件的问题，事件自身的标记已能以常数时间给出答案。
 
-## Consequences
+## 后果
 
 压缩不再抹掉终端历史；被压缩多次的会话会按日志顺序显示每次落地压缩对应的一行标记。分页的每一页可以携带比以前更多的原始事件，因为额度只花在人类或模型真正产生的消息上。
 
-`rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换 reasoning 时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。
+`rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换推理（reasoning）时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。
 
-`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` 接缝的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
+`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` seam的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
 
-两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（“隐藏被遮蔽的工具调用”），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture，以显示被保留的提示、完整的工具卡片和那行标记。
+两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（「隐藏被遮蔽的工具调用」），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture（测试前置数据），以显示被保留的提示、完整的工具卡片和那行标记。
 
-上文的实时／回放等价性由 fixture 钉住，而不只是在此断言：`surface-replayed-compaction` 在挂载时替换已经存在，其录制结果与实时路径的 `surface-after-compaction-wide` 逐字节一致。改动任一路径都会破坏这项相等——这正是要点：回放投影才是当初对用户造成回归的部分，两份 fixture 必须一起变动。
+上文的实时／回放等价性由 fixture 钉住，而不只是在此断言：`surface-replayed-compaction` 挂载时替换事件已存储，其录制结果与实时路径的 `surface-after-compaction-wide` 逐字节一致。改动任一路径都会破坏这项相等——这正是要点：回放投影才是当初对用户造成回归的部分，两份 fixture 必须一起变动。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
index b1bdfe74c2..11c7a8935a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.md
 2026-07-29-pnpm-setup-runner-isolation.md: 74b672b3f90ea445ad1a8e283a5904056059b2f8
-2026-07-29-pnpm-setup-runner-isolation.zh.md: 32c667dc09e561504e8e053bf2a338ed2190d9e8
+2026-07-29-pnpm-setup-runner-isolation.zh.md: fde4cb747e41ea7dafe87ca3ccd0e872c45dd3b1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
index 32c667dc09..fde4cb747e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[主 CI 工作流](../../../../.github/workflows/ci.yml)中的每个 `pnpm/action-setup` 步骤都设置 `dest: ${{ runner.temp }}/setup-pnpm`。每个 runner 服务独占自己的临时目录，因此一个设置过程无法替换另一个 runner 的安装目录。持久 store 的复用仍由 `PNPM_CONFIG_STORE_DIR` 独立处理，遵循 [pnpm 提供机制决策](../process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md)。
+[主 CI 工作流](../../../../.github/workflows/ci.yml)中的每个 `pnpm/action-setup` 步骤都设置 `dest: ${{ runner.temp }}/setup-pnpm`。每个 runner 服务独占自己的临时目录，因此一个设置过程无法替换另一个 runner 的安装目录。持久 store 的复用仍由 `PNPM_CONFIG_STORE_DIR` 独立处理，遵循 [pnpm 配置决策](../process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md)。
 
 [工作流回归测试](../../../../scripts/ci-workflow.spec.ts)会找出 `ci.yml` 中的每个 `pnpm/action-setup` 步骤，并拒绝缺少 runner 专属目标目录的步骤。这可确保后续新增的作业也处于同一隔离边界内。
 
@@ -24,4 +24,4 @@ Status: implemented
 
 ## 后果
 
-pnpm 可执行文件采用临时安装，并按 runner 隔离；包下载仍使用已配置的持久或缓存 store。托管作业使用相同的显式目标目录，不改变缓存政策。工作流中的每个设置步骤因此增加三行配置；只有在 pnpm 提供机制有意迁移到另一种隔离机制时，才需要更新回归测试。
+pnpm 可执行文件采用临时安装，并按 runner 隔离；包下载仍使用已配置的持久或缓存 store。托管作业使用相同的显式目标目录，不改变缓存政策。工作流中的每个设置步骤因此增加三行配置；只有在 pnpm 配置有意改用另一种隔离机制时，才需要更新回归测试。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
index fdb487f16b..373e0d70d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
 2026-07-29-sticky-composer-conversation-scroll.md: 8657080078e475d6e90f17a6c0f8cb5b2fb1555d
-2026-07-29-sticky-composer-conversation-scroll.zh.md: a588903adf51c6fcdd01f851d4f5e6570f695242
+2026-07-29-sticky-composer-conversation-scroll.zh.md: 7b9a59933d979577ea50d339f4bb276557e67081
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
index a588903adf..7b9a59933d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
@@ -1,22 +1,22 @@
-# Agent Note: 固定标题栏，sticky 编辑器位于 transcript 滚动容器内
+# Agent Note: 固定标题栏，sticky 编辑器位于 transcript（文本记录）滚动容器内
 
 Status: implemented
 
 [English](2026-07-29-sticky-composer-conversation-scroll.md) | 中文
 
-## Problem
+## 问题
 
 活跃会话列把滚动拆成两段：聊天（以及 trajectory）视图自有 `overflow-y: auto`，编辑器栈则作为该滚动容器的兄弟节点坐在下方。指针落在统计行或输入区上时，滚轮打在不可滚动区域上因而毫无效果——只有指针在消息列表上时 transcript 才会移动。草稿变长时更糟：textarea 本身也是滚动容器，编辑器上的滚轮可能被截在那里。会话标题栏必须以普通 chrome 占据列顶（不能在滚动容器内 `position: sticky`），而编辑器必须与 transcript 贴在同一滚动容器底部，使页脚上的滚轮能带动内容流动。
 
-## Decision
+## 决策
 
-`ConversationRoot` 始终拥有同一个 `data-conversation-scroll` 主体，其中严格 `conversation.session` view outlet 位于 `data-composer-seat` 之前；该 seat 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。独立的严格 `conversation.session.header` outlet 作为 `flex: none` 列 chrome 位于滚动容器上方，并在 Session 仍为 blank 时隐藏。固定的父级树让滚动主体与 composer seat 从无 session、blank Hero 到活跃对话始终保持挂载。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；Hero CSS 在滚动主体内居中 fallback 栈。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
+`ConversationRoot` 始终拥有同一个 `data-conversation-scroll` 主体，其中严格 `conversation.session` view outlet 位于 `data-composer-seat` 之前；该 seat 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。独立的严格 `conversation.session.header` outlet 作为 `flex: none` 列 chrome 位于滚动容器上方，并在 Session 仍为 blank 时隐藏。固定的父级树让滚动主体与 composer seat 从无会话、blank Hero 到活跃对话始终保持挂载。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；Hero CSS 在滚动主体内居中 fallback 栈。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
 
 会话统计挂在 `'conversation.composer.dock'`（位于 `'conversation.input.dock'` 之上）。InputBar 的 textarea 在宿主内以 `{ passive: false }` 链式处理 `wheel`：在限高 textarea 仍能沿该方向滚动时保留原生手势；仅在自身边缘才 `preventDefault` 并将 `deltaY` 施加到宿主。
 
-Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态；读者输入如何被识别——即以与设备无关的方式偏离由最近一次交付或写入的 `scrollTop` 构成的 observed-top ledger——由[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)负责。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个 chunk 不会触发第二次滚动写入。
+Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态；读者输入如何被识别——即以与设备无关的方式偏离由最近一次交付或写入的 `scrollTop` 构成的 observed-top ledger——由[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)负责。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个分片不会触发第二次滚动写入。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **标题栏与编辑器都在同一列滚动容器内 sticky。** 标题栏否决：它必须作为固定布局 chrome 占据顶部，而不是参与滚动容器的 sticky 层。
 
@@ -28,6 +28,6 @@ Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图
 
 **为每一种浏览器滚动输入来源建模。** 此次窄范围修复不采用：已复现的桌面端路径使用滚轮／触控板输入。指针／触控滚动、拖动原生滚动条、键盘滚动、焦点导航与嵌套 overflow 所有权当时被留在输入来源模型之外，也未为此新增通用输入状态机。[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)后来通过 observed-top ledger 泛化了归因，补上了这一延后事项，且仍未引入输入状态机。
 
-## Consequences
+## 后果
 
-在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留读者的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段的收缩钳制。贴底跟随所有权依据[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)扩展到每一种读者输入。无 session → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。
+在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky 轮次标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留读者的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段的收缩钳制。贴底跟随所有权依据[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)扩展到每一种读者输入。无会话 → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
index f314df3e08..e753a0e762 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
 2026-07-29-web-details-session-lifecycle.md: 41b89fc059a02e56f53b27e5a5b48fb9488b93d7
-2026-07-29-web-details-session-lifecycle.zh.md: 82fb5e0c2608cccbb786a21971a74958417b4f10
+2026-07-29-web-details-session-lifecycle.zh.md: 56be5f73874a72162f61f47539f041566f18aec3
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
index 82fb5e0c26..56be5f7387 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 **在 New Session 点击处理器中关闭详情栏。** 之所以否决：未选中表面没有会话作用域的详情，不得修改几何信息。详情栏是否关闭，应由随后对两个已定义会话 owner 的比较决定。
 
-**按会话持久化面板几何信息。** 之所以否决：产品契约需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
+**按会话持久化面板几何信息。** 之所以否决：产品约定需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
 
 **在会话基线就绪后保留持久化布局。** 之所以否决：这会仅为验证陈旧的查看状态，在呈现组件中重复实现启动生命周期。瞬时默认值无需就绪标志即可使重新加载具有确定性。
 
@@ -26,4 +26,4 @@ Status: implemented
 
 ## 后果
 
-详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用契约默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
+详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用约定的默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
index 77608b33f4..91dd4d352d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
 2026-07-30-approval-panel-command-cap.md: 1e4b75c106b71605a004ef35301445da76ec8cf0
-2026-07-30-approval-panel-command-cap.zh.md: aa9f708b78c8ace735e1c96c0ff9ab0a7a4d526a
+2026-07-30-approval-panel-command-cap.zh.md: 963dca00a6eda6c3bfd145828c8d7553625a4511
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
index aa9f708b78..963dca00a6 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 面板的理由与命令移入同一个滚动区域（`data-approval-scroll`），其高度上限与 composer 的草稿区完全相同；琥珀色状态条与操作按钮行位于该区域之外，因此无论内容多长，两个按钮都留在卡片内。
 
-这个上限是一个值、两个消费者，以 `--dsh-composer-text-max-height: 336px` 声明在 `ConversationRoot` 的 `.composerSeat` 上——它是 composer 链唯一的共同祖先，因为兜底的 InputBar 与被选中的接管面板是兄弟节点。`InputBar` 的草稿滚动容器与面板的滚动区域都读取它，于是同一个容器不可能给它的两种状态设出不同上限：设计同学要求的"可以跟输入框最大高度统一"，如今是样式表中的一个事实，而不是抄在两个文件里的一个数字。该区域取 `box-sizing: border-box`，因此上限指的是它的外框高度，与 composer 草稿区占据的是同一个盒子。
+这个上限是一个值、两个消费者，以 `--dsh-composer-text-max-height: 336px` 声明在 `ConversationRoot` 的 `.composerSeat` 上——它是 composer 链唯一的共同祖先，因为兜底的 InputBar 与被选中的接管面板是兄弟节点。`InputBar` 的草稿滚动容器与面板的滚动区域都读取它，于是同一个容器不可能给它的两种状态设出不同上限：设计同学要求的「可以跟输入框最大高度统一」，如今是样式表中的一个事实，而不是抄在两个文件里的一个数字。该区域取 `box-sizing: border-box`，因此上限指的是它的外框高度，与 composer 草稿区占据的是同一个盒子。
 
 该区域自身是一个 Tab 停靠点（`tabIndex={0}`，带名称的 `role="group"`）。提问 composer 的滚动体不需要这样做——它的选项行本身可聚焦，会把容器一起带过去；而这里除文本之外别无内容：没有自己的停靠点，仅用键盘的用户能走到按钮却走不到命令尾部，于是可能批准了自己没读完的东西。
 
@@ -22,31 +22,31 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**给整张卡片设上限，而不是给文本区域设。** 一条声明，不需要重构结构，而且它读起来就是字面意义上的"与输入框相同的最大高度"。之所以否决：卡片还装着状态条和操作按钮行——总高 336px 时，理由与命令只能分到约 250px，比它们所取代的草稿区更矮，而且两边数字能对上纯属状态条高度的巧合。给文本区域设上限，才能让两种状态在同一文本高度处收住，而这正是让底部不再跳动的那条性质。
+**给整张卡片设上限，而不是给文本区域设。** 一条声明，不需要重构结构，而且它读起来就是字面意义上的「与输入框相同的最大高度」。之所以否决：卡片还装着状态条和操作按钮行——总高 336px 时，理由与命令只能分到约 250px，比它们所取代的草稿区更矮，而且两边数字能对上纯属状态条高度的巧合。给文本区域设上限，才能让两种状态在同一文本高度处收住，而这正是让底部不再跳动的那条性质。
 
 **像提问 composer 那样按视口设上限（`min(60vh, 520px)`）。** 同为接管面板的兄弟组件已经这么做了，因此这是本地既有先例。之所以否决：设计同学的要求是与 InputBar 对齐，而两个接管面板形态并不相同——提问 composer 的滚动内容是一组需要用户互相比较的选项，能占多少视口就该占多少；审批面板的滚动内容则是一条命令，用户在决定之前扫读即可。按视口设上限还会让容器高度在被选中时再次跳动，只是方向相反。
 
-**对命令做省略号或截断处理。** 不需要滚动区域，不需要上限，按钮也不会移位。之所以否决：命令正是被审批的对象，隐去它的尾部等于要求用户为自己读不到的文本背书。在这里截断还是不可恢复的——面板就是审批的全部界面，没有"展开更多"的落脚处。
+**对命令做省略号或截断处理。** 不需要滚动区域，不需要上限，按钮也不会移位。之所以否决：命令正是被审批的对象，隐去它的尾部等于要求用户为自己读不到的文本背书。在这里截断还是不可恢复的——面板就是审批的全部界面，没有「展开更多」的落脚处。
 
 **把操作按钮行留在滚动区域内，只给该区域设上限。** 比把按钮行固定住少动几处。之所以否决：这会把缺陷搬进卡片内部——按钮滚出该区域，用户得先发现有滚动条才能碰到它们。
 
 ## 后果
 
 - 长命令在卡片内滚动，拒绝／允许按钮留在屏幕内。在构建产物客户端上于 900x1000 与 900x700 实测：该区域报告的 `scrollHeight` 超过 `clientHeight`，两个按钮都留在卡片内、也都留在视口内。
-- 选中接管面板不再改变 composer 容器能达到的高度，因此审批到来或解决时，上方的会话流不会有数百像素的重排。
+- 选中接管面板不再改变 composer 容器能达到的高度，因此审批到来或解决时，上方的 transcript（文本记录）不会有数百像素的重排。
 - InputBar 的 14 行上限现在通过一个自 `.composerSeat` 继承而来的自定义属性解析，且落在真正滚动草稿的那个盒子上（[两层文本共用同一个滚动容器](2026-07-31-composer-text-layers-share-one-scrollport.md)把该声明从自增高镜像层移了出去）。把输入栏渲染到该容器之外会丢掉这条声明（一个没有兜底值的未解析 `var()`），因此未来的 composer 宿主必须带上这个属性——这也正是它声明在共享容器上、而不是应用根节点上的原因。
-- 该场景录制的命令是一段 200 个 token 的字符块，远超一次往返所需。这个代价是有意付出的：没有能越过上限的内容，这个上限无法被证伪，而模型会把任何规整的载荷压缩掉（第一次录制时，模型把"alpha 重复 400 次"写成了 `printf 'alpha %.0s' {1..400}`，一条什么也证明不了的单行命令）。
+- 该场景录制的命令是一段 200 个 token 的字符块，远超一次往返所需。这个代价是有意付出的：没有能越过上限的内容，这个上限无法被证伪，而模型会把任何规整的载荷压缩掉（第一次录制时，模型把「alpha 重复 400 次」写成了 `printf 'alpha %.0s' {1..400}`，一条什么也证明不了的单行命令）。
 
 ## 验证
 
 `apps/web/tests/approval-composer.e2e.ts` 驱动的是真实组合：一个只读会话、一次被拒绝的写入、模型的越权重试，以及在面板上点击完成的回应。几何断言在两个视口高度上针对活动面板执行，并有守卫防止它空洞地成立——该区域必须确实处在滚动状态，且实测上限必须等于 composer 自身的上限，后者由测试在发送之前从活动的草稿滚动容器上读出，而不是把该像素值写死。
 
-在构建产物客户端上双向确认过。撤销上限后，该区域报告 `scrolls: false`，并长到命令的完整高度（900x1000 下，录制的字符块为 1798px，而设上限后为 336px）；在 900x700 下卡片高 680px、视口高 700px，操作按钮行底边落在 y=749——正在折叠之下，与设计同学的反馈完全一致。恢复上限后，该场景在回放模式下通过。
+在构建产物客户端上双向确认过。撤销上限后，该区域报告 `scrolls: false`，并长到命令的完整高度（900x1000 下，录制的字符块为 1798px，而设上限后为 336px）；在 900x700 下卡片高 680px、视口高 700px，操作按钮行底边落在 y=749——位于视口下方，与设计同学的反馈完全一致。恢复上限后，该场景在回放模式下通过。
 
-要复现按钮跑到屏幕外，需要的是比滚动视口更高的卡片，而不只是一张很高的卡片。composer 容器为 `position: sticky; bottom: 0`，因此在卡片尚能容纳时它会一直吸附在视口底部，按钮仍然可见——在 900x1000 下，未设上限的卡片吃掉了整个会话流，却仍把操作按钮行留在屏幕内。只有当卡片长过滚动视口，sticky 才再也无法守住底边，按钮行随之沉入折叠之下。
+要复现按钮跑到屏幕外，需要的是比滚动视口更高的卡片，而不只是一张很高的卡片。composer 容器为 `position: sticky; bottom: 0`，因此在滚动视口尚能容纳卡片时它会一直吸附在视口底部，按钮仍然可见——在 900x1000 下，未设上限的卡片吃掉了整个 transcript，却仍把操作按钮行留在屏幕内。只有当卡片长过滚动视口，sticky 才再也无法守住底边，按钮行随之沉入视口下方。
 
-几何断言块与 golden 仅在回放模式下执行，这样录制模式才能走到写入 fixture 那一步，而不是在布局检查处中断。
+几何断言块与 golden 仅在回放模式下执行，这样录制模式才能走到写入 fixture（测试前置数据）那一步，而不是在布局检查处中断。
 
-该场景只保留一份 golden —— 等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。最初还录了一份"已回应会话流"的 golden，它在 Linux CI 上失败了：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何会话流中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
+该场景只保留一份 golden——等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。最初还录了一份"已回应 transcript"的 golden，它在 Linux CI 上失败了：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何 transcript 中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
 
 该面板以客户端模组包的形式发布：单跑 `pnpm run build:web` 不会带上对 `ApprovalPanel.module.css` 的改动，也不会带上 `ApprovalPanel.tsx` 中新增的 `data-` 钩子——必须先执行包构建，否则浏览器测试通道会对着一个比工作树更旧的客户端做断言。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
index fa83836e46..8e8b4bcbf0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.md
 2026-07-30-composer-context-stack-order.md: 150225ce27fa8459703170622cef754b7694e2fc
-2026-07-30-composer-context-stack-order.zh.md: f13ffc3c1136707a86ba5636a5b69304a132df01
+2026-07-30-composer-context-stack-order.zh.md: dc9c75b35fb6a34c06326c916fd422483d57289c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
index f13ffc3c11..dc9c75b35f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
@@ -10,15 +10,15 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
 
 ## 决策
 
-[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈契约：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
+[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈约定：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
 
 `ConversationRoot` 负责独立上下文卡片之间的 6px 间距。Goal 是一张独立的 752×36px 卡片，折叠后的 Todo 是一张独立的 752×44px 卡片。Queue 是末端 dock 条目：其 776px 包装层包含相同的 752px 面板列，并减去共享间距与具名的 5px 布局重叠量，因此后渲染的 composer 卡片只覆盖 Queue 边缘。空条目渲染为 null，不占用间距。
 
-顺序与重叠是两项独立契约。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
+顺序与重叠是两项独立约定。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
 
 ## 验证
 
-注册测试固定了三个顺序值。无密钥 Queue 浏览器场景同时渲染 Todo、Goal 和 Queue，固定它们的无障碍顺序，并检查其可见卡片边缘；聚焦的 Goal 与 Queue 场景覆盖各自的独立状态。
+注册测试固定了三个顺序值。无密钥 Queue 浏览器场景同时渲染 Todo、Goal 和 Queue，固定它们的无障碍顺序，并检查其可见卡片边缘；分别针对 Goal 与 Queue 的场景覆盖各自的独立状态。
 
 ## 考虑过的替代方案
 
@@ -26,7 +26,7 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
 
 **在 `ConversationRoot` 中分别渲染每个已知 dock id。** 不予采纳，因为这会把可扩展的列表 slot 变成硬编码的组件清单，并迫使 owner 在每新增一个注册方时随之修改。
 
-**让最后一个 dock 条目贴卡。** 不予采纳，因为 Goal 和 Todo 是独立卡片；Goal 或 Todo 缺席时的组合不得改变剩余卡片的界面语义。
+**让最后一个 dock 条目与 composer 相接。** 不予采纳，因为 Goal 和 Todo 是独立卡片；Goal 或 Todo 缺席时的组合不得改变剩余卡片的界面语义。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml
index ed2f7646bc..6e364d9a3e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.md
 2026-07-30-hover-popup-pointer-grace.md: 3f60c98ec6453b633feebe408cbc0c0c49eedea1
-2026-07-30-hover-popup-pointer-grace.zh.md: db10e156103284383f911684b2c92977a0315275
+2026-07-30-hover-popup-pointer-grace.zh.md: f53d77bae7b7f223621c4c42779e1a6a616aa485
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md
index db10e15610..f53d77bae7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-工作区浏览器行弹出的两种弹层都处于指针无法抵达的位置。`HoverCard` 在指针离开锚点的第一个 `pointerleave` 上就关闭，其卡片还设置了 `pointer-events: none`；但卡片位于锚点右边缘外 8px 处，因此通往卡片的每条路径都要穿过既不属于锚点也不属于卡片的区域，卡片在指针抵达之前就已被销毁——它本应展示的完整工作区路径和会话标题只能匆匆一瞥。行操作菜单传入了 `closeOnPointerLeave`，而其处理器挂在传送后的列表上：把指针移回打开该列表的 `...` 触发按钮会关闭列表，越过列表边缘的任何一次抖动同样如此，且没有任何折返窗口。
+工作区浏览器行弹出的两种弹层都处于指针无法抵达的位置。`HoverCard` 在指针离开锚点的第一个 `pointerleave` 上就关闭，其卡片还设置了 `pointer-events: none`；但卡片位于锚点右边缘外 8px 处，因此通往卡片的每条路径都要穿过既不属于锚点也不属于卡片的区域，卡片在指针抵达之前就已被销毁——它本应展示的完整工作区路径和会话标题只能匆匆一瞥。行操作菜单传入了 `closeOnPointerLeave`，而其处理器挂在传送后的列表上：把指针移回打开该列表的 `...` 触发按钮会关闭列表，指针越过列表边缘同样会将其关闭，且没有任何折返窗口。
 
 ## 决策
 
 `usePointerGrace`（[packages/client/ui-primitives/src/pointer-grace.ts](../../../../packages/client/ui-primitives/src/pointer-grace.ts)）持有唯一一个可取消的延迟关闭，由两个原子组件共享，`POINTER_GRACE_MS` 为 200。离开会启动关闭，折返则取消它。因此指针可以安全穿越锚点与弹层之间的间隙，而真正移开的指针仍会关闭弹层。
 
-`HoverCard` 在离开时启动宽限期而不再立即关闭，其卡片也不再设置 `pointer-events: none`，因此指针停在卡片上即可让它保持打开。在已打开状态下重新进入只取消待执行的关闭，而不重启停留计时，从而避免指针穿越间隙时卡片闪烁。在卡片上按下指针用于开始文本选择，不会关闭卡片；只有锚点区域内的按下和所有者将 `disabled` 置真，才会抢在宽限期之前立即关闭卡片。
+`HoverCard` 在离开时启动宽限期而不再立即关闭，其卡片也不再设置 `pointer-events: none`，因此指针停在卡片上即可让它保持打开。在已打开状态下重新进入只取消待执行的关闭，而不重启停留计时，从而避免指针穿越间隙时卡片闪烁。在卡片上按下指针用于开始文本选择，不会关闭卡片；只有在锚点区域内发生按下操作，或所有者将 `disabled` 置真时，才会抢在宽限期之前立即关闭卡片。
 
 `Menu` 把指针离开关闭的处理从传送后的列表移到包裹 span 上。React 的 enter/leave 遍历基于 React 树进行，因此触发按钮与传送后的列表在这里属于同一区域：穿越两者之间 4px 的间隙、或把指针移回触发按钮，都不再算作离开。只有在列表打开时才会启动离开关闭；由所有者驱动的关闭（选择、Escape、外部点击）会在一个仅以 `open` 为依赖的 effect 中解除待执行的宽限关闭——若把它折叠进外部点击的 effect，则每次重新渲染都会取消宽限期，因为所有者每次都传入新的 `onClose` 闭包。
 
@@ -20,7 +20,7 @@ Status: implemented
 
 **仅通过外部点击和 Escape 关闭这两种弹层。** 之所以否决：两者都由悬停唤起，且没有可见的关闭标识；在指针已移到其他行之后仍让它们停留，会把卡片遗留在无关内容之上。
 
-**扩大锚点的命中区域，使其与弹层相接。** 之所以否决：8px 与 4px 的偏移来自设计稿，而一个不可见的桥接元素还必须跟随这两个固定定位弹层已经在滚动和缩放时执行的每一次重新定位。
+**扩大锚点的命中区域，使其与弹层相接。** 之所以否决：8px 与 4px 的偏移来自设计稿，而一个不可见的桥接元素还必须跟随这两个固定定位弹层已经在滚动和调整窗口大小时执行的每一次重新定位。
 
 **保留悬浮卡片的 `pointer-events: none`，只加入宽限期。** 之所以否决：那样指针停在卡片上时命中的是卡片背后的元素，宽限期仍会到期，并关闭用户刚刚够到的卡片。
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 后果
 
-悬浮卡片现在可被命中，显示期间会遮挡其覆盖区域的 244px——这是可抵达性的代价；它依然只在指针位于行或卡片上时存在。行菜单现在能承受触发按钮与列表之间的往返，而因自身原因关闭的菜单也不会被残留的待执行关闭重新关掉。未设置 `closeOnPointerLeave` 的菜单不受影响——只有设置该属性时才会挂上包裹层处理器。
+悬浮卡片现在可被命中，显示期间会遮挡其覆盖区域的 244px——这是可抵达性的代价；它依然只在指针位于行或卡片上时存在。行菜单现在能承受触发按钮与列表之间的往返，而因自身原因关闭的菜单重新打开后，也不会被残留的待执行关闭关掉。未设置 `closeOnPointerLeave` 的菜单不受影响——只有设置该属性时才会挂上包裹层处理器。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml
index 2f06390bdf..58e1d5691f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.md
 2026-07-30-multi-select-custom-answer-composition.md: 581beec89a0f0018ec2df687f5dfe1b1b5b86d22
-2026-07-30-multi-select-custom-answer-composition.zh.md: 5c9cb59822aca3fbf49fbbdf522c76f963df3480
+2026-07-30-multi-select-custom-answer-composition.zh.md: 796d379312483be5063a3a5d67dd6a0d0e37803e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md
index 5c9cb59822..796d379312 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md
@@ -18,8 +18,8 @@ Status: implemented
 
 **把自定义文本编码为另一个 `selected` 标签。** 不予采纳，因为这样会抹去调用方提供的选项标签与用户填写文本之间的区别，削弱校验，并迫使消费方推断哪个值属于自定义内容。
 
-**允许所有问题同时使用 `selected` 与 `custom`。** 不予采纳，因为单选题只表示一个回答；允许选中选项与自定义文本并存会使其基数含义模糊。组合形式仅适用于显式选择多项回答的问题。
+**允许所有问题同时使用 `selected` 与 `custom`。** 不予采纳，因为单选题只表示一个回答；允许选中选项与自定义文本并存会使其基数含义模糊。组合形式仅适用于显式启用多回答的问题。
 
 ## 后果
 
-多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web 组件与组装浏览器的覆盖率、TUI 覆盖率、宿主响应覆盖率和工具投影覆盖率共同固定组合结果。Web、TUI 与工具投影覆盖率还固定了仅含标签的回答形态；组装后的无密钥 TUI 覆盖率固定终端中的组合回答流程，单选题的宿主覆盖率则固定其余的互斥规则。
+多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web 组件与组装浏览器的测试覆盖、TUI 测试覆盖、宿主响应测试覆盖和工具投影测试覆盖共同固定组合结果。Web、TUI 与工具投影测试覆盖还固定了仅含标签的回答形态；组装后的无密钥 TUI 测试覆盖固定终端中的组合回答流程，单选题的宿主测试覆盖则固定其余的互斥规则。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
index 311c4971d3..527471cd2e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md
 2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd
-2026-07-30-source-checkout-workdir-distinction.zh.md: ffc2ac7baa2b1bb8ce54607638c35869fc338825
+2026-07-30-source-checkout-workdir-distinction.zh.md: 06b09f82f294a70795090a9aec1b2220bd6e7512
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md
index ffc2ac7baa..06b09f82f2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md
@@ -4,30 +4,30 @@ Status: implemented
 
 [English](2026-07-30-source-checkout-workdir-distinction.md) | 中文
 
-## Problem
+## 问题
 
-`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为“你自己的源代码”，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答“what's the workdir?”，而不是确定会话的当前工作目录。
+`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为「你自己的源代码」，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答「what's the workdir?」，而不是确定会话的当前工作目录。
 
 直接断言 checkout 不是工作目录同样不准确。`dsh meta` 会有意让源码 checkout 同时充当这两个值。
 
-## Decision
+## 决策
 
-该提示词段将路径标识为“DeepSeek Harness implementation checkout”。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
+该提示词段将路径标识为「DeepSeek Harness implementation checkout」。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
 
 路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。
 
-## Verification
+## 验证
 
-`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI 无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问“what's the workdir?”，并要求回放 transcript 运行 `pwd`，报告生成的 workspace 而不是 checkout。
+`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI（命令行界面）无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问「what's the workdir?」，并要求回放 transcript（文本记录）运行 `pwd`，报告生成的 workspace 而不是 checkout。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **声明 checkout 永远不是工作目录。**拒绝：`dsh meta` 会有意让它们指向同一路径。
 
-**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会重复 loop 对 `cwd` 的所有权，还会让稳定的源码事实随 agent 变化。
+**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会与 agent loop（智能体循环）对 `cwd` 的所有权重复，还会让稳定的源码事实随 agent 变化。
 
 **从提示词中删除源码路径。**拒绝：launcher 从无关项目启动时，自引用 DSH 工具仍需要可靠的 checkout 位置。
 
-## Consequences
+## 后果
 
 提示词会变长，直接询问工作目录时可能多花一次廉价的 `pwd` 工具调用。作为交换，模型不再把 harness 实现路径当作隐含的任务 workspace；当 meta 模式使两个值重合时，提示词仍然准确。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index cede7ea5d9..abed6fce03 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
 2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
-2026-07-30-web-transcript-log-ordered-projection.zh.md: acd198b6d3f3c5d57e233e09ee66f5d151e4f8f1
+2026-07-30-web-transcript-log-ordered-projection.zh.md: ec60a8cdb464ded8ddc2ec46f499fe4ccc4c2f8a
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index acd198b6d3..ec60a8cdb4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -1,18 +1,18 @@
-# Agent Note: 浏览器会话是按日志顺序投影的人类对话记录
+# Agent Note: 浏览器会话是按日志顺序投影的面向人的 transcript（文本记录）
 
 Status: implemented
 
 [English](2026-07-30-web-transcript-log-ordered-projection.md) | 中文
 
-## Problem
+## 问题
 
-浏览器客户端从模型可见的 surface 构建会话：`FoldAdapter` 在历史窗口上运行核心 `SurfaceManager` 并读取 `surface.nodes`。一次成功的压缩会用一个检查点节点替换一段 surface 范围，因此该替换一落地，Web 流就把它所遮蔽的每条消息折叠成一行灰暗的上下文——那是用户已经读过的对话。日志中什么都没丢失；缺陷完全在投影层，而[终端与宿主历史网关已按同一方式修复](2026-07-29-human-transcript-append-origin.md)，浏览器留给了本次变更。
+浏览器客户端从模型可见的 surface 构建会话：`FoldAdapter` 在历史窗口上运行核心 `SurfaceManager` 并读取 `surface.nodes`。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，Web 流就把它所遮蔽的每条消息折叠成一行灰暗的上下文——那是用户已经读过的对话。日志中什么都没丢失；缺陷完全在投影层，而[终端与宿主网关已按同一方式修复](2026-07-29-human-transcript-append-origin.md)，浏览器留给了本次变更。
 
 surface 顺序还让另外两个问题成为结构性的。一次替换之后它并非按 seq 升序——`SurfaceManager` 把高 seq 的检查点拼接到它所遮蔽范围的位置上——因此按数值 seq 归并进该数组的仅日志节点（斜杠命令行、被打断的冻结节点）可能被冲刷到检查点之前，再也无法交错回保留下来的尾部。而且由于分页不再为 replacement 副本消耗 `maxMessages` 额度，一页现在可以携带一个 `surfaceOp.start` 落在窗口之外的检查点；核心 fold 拒绝该范围，于是 `nodes()` 退回到一次宽容的线性扫描、打印一条 `console.error`，并发布一个描述该失败的 `foldDegraded` 标志。
 
-## Decision
+## 决策
 
-`TranscriptAdapter` 取代 `FoldAdapter`，并且从不查询 surface 顺序。它按日志顺序投影原始窗口：每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点一个 `CompactionSummaryNode` 标记。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话，标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不在对话中标记任何边界。凡必须发送模型所见内容的一切仍读 surface；这是人类投影，两者现在在两个前端上都已分离。
+`TranscriptAdapter` 取代 `FoldAdapter`，并且从不查询 surface 顺序。它按日志顺序投影原始窗口：每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点一个 `CompactionSummaryNode` 标记。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话，标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入 transcript：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不在对话中标记任何边界。凡必须发送模型所见内容的一切仍读 surface；这是人类投影，两者现在在两个前端上都已分离。
 
 节点顺序天然按 seq 单调，由此有三个结果。仅日志的 `command/run` / `command/done` 对折叠成 `CommandNode`，按 seq 插入一个本已单调的数组——无锚点，无重排。`Session` 保留被打断的冻结节点的归属，用一次普通排序按其分数 seq 归并，而这现在恰好就是流顺序。检查点所引被遮蔽范围落在窗口之外的窗口没有范围需要解析，因此标记正常渲染且不打印任何日志。
 
@@ -26,7 +26,7 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 
 ## 识别检查点：同一份声明，在编译期钉住
 
-识别需要三个条件同时成立，与终端一致：`event.type === 'user/message'`、压缩缝隙的检查点插件来源，**以及** `isReplacementSurfaceEvent(event)`。一条 append 的插件来源 `user/message` 是注入上下文——跨会话引用卡片——不是压缩。
+识别需要三个条件同时成立，与终端一致：`event.type === 'user/message'`、压缩 seam 的检查点插件来源，**以及** `isReplacementSurfaceEvent(event)`。一条 append 的插件来源 `user/message` 是注入上下文——跨会话引用卡片——不是压缩。
 
 从 `packages/client/*` 程序无法到达的是 `dsh-compact` 的**根部**，而不是这个包。根部会到达 `dsh-session` 的根部，后者的 cordis `Context` 合并声明了宿主侧 `sessions: SessionStore`，与客户端的 `sessions: ISessions` 冲突——`TS2717`，即 [development.md](../../../../docs/development.md#typescript-project-layout) 中每侧一个 program 的规则；这一点对仅类型导入同样成立，因为该冲突是编译器事实而非打包器事实。
 
@@ -37,7 +37,7 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 ```
 
-重命名缝隙的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
+重命名 seam 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
 
 `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。该测试以值导入方式从不含 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 叶子路径取得该值，并刻意不加载 compact 包根或经由它可达的宿主侧 `Context` 合并。
 
@@ -45,34 +45,34 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 ## #835 的位置锚点是为什么而存在，以及为什么它是被溶解而非丢失
 
-尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也不撰写它。
+尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。面向人的 transcript 永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也未实现它。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**从新叶子值导入该谓词**，并把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单。已拒绝：客户端需要的是插件 id，不是谓词——一个类型就够了，而被擦除的导入根本不会抵达纯度门禁，因此无需向它放行任何东西。白名单只在值导入时才有意义，而在那里它是笔糟糕的交换：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包会连它那个会导入 cordis 的根部一起放行。
+**从新叶子值导入该谓词**，并把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单。已拒绝：客户端需要的是插件 id，不是谓词——一个类型就够了，而被擦除的导入根本不会抵达纯度门禁，因此无需向它放行任何东西。白名单只在值导入时才有意义，而在那里这是一项糟糕的权衡：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包会连它那个会导入 cordis 的根部一起放行。
 
-**一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只花一个文件，就精确消除了这一风险。
+**一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只需一个文件，就精确消除了这一风险。
 
-**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议契约变更——为一个纯谓词付出的代价不成比例。
+**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合「经 cordis 服务协作」的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议约定变更——为一个纯谓词付出的代价不成比例。
 
-**把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的记录之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。
+**把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的 transcript 之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。
 
-**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假契约。
+**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假约定。
 
 **把最近的 `/compact` 行与下一个检查点配对。** 已拒绝：两者之间可能落入上下文注入，并发或格式异常的生命周期记录也必须降级而不误取其他检查点。命令结果则指明权威摘要事件；引用存在歧义时不配对任何内容。
 
-**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据契约。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
+**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据约定。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
 
-## Consequences
+## 后果
 
-压缩不再抹掉 Web 历史；一个被压缩多次的会话按日志顺序显示每次落地压缩一个标记，而同一窗口在实时与冷恢复之后渲染完全相同。分页缺口是被构造性闭合而非被防御，`ConversationSnapshot` 少了一个已发布字段，这触及十三个文件。
+压缩不再抹掉 Web 历史；一个被压缩多次的会话按日志顺序显示每次落地压缩一个标记，而同一窗口在实时与冷恢复之后渲染完全相同。分页缺口从设计上得以消除，而不是靠防御性处理来规避，`ConversationSnapshot` 少了一个已发布字段，这触及十三个文件。
 
-`ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的“无单元格”分支，使标记不贡献单元格但仍推进耗时游标。
+`ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的「无单元格」分支，使标记不贡献单元格但仍推进耗时游标。
 
-性能契约未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
+性能约定未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复有意作出的权衡；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
 
 Web e2e 场景现在围绕它录制的那一轮上的压缩事务播种一次真实的手动命令生命周期，因此 aria 基准经真实宿主与真实浏览器钉住完整行为：录制的提问与完整工具输出仍在屏幕上，其后恰好一条 `compact` 行报告规模，展开后会显示确切摘要。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出手动压缩。
 
-## Deferred
+## 延后事项
 
 终端的[已归档压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
index 6b8933a5f8..71f89e6866 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md
 2026-07-31-composer-text-layers-share-one-scrollport.md: ba11384409714d6a64a964d63197705acf39d213
-2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 9a4a2bcc9f947d385d1ff9fc6367b9a3eab17733
+2026-07-31-composer-text-layers-share-one-scrollport.zh.md: cf0ce7bc344f6566d56a9e3cd81a63be5f68d614
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
index 9a4a2bcc9f..cf0ce7bc34 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)）：`<textarea>` 持有取值、选区与光标，但它自己的字形以 `color: transparent` 渲染；用户看到的每一个字符都由其下的 `[data-input-backdrop]` 层绘制，该层同时承载 claim token 高亮、chip 与提示影子文本。这一拆分正是 chip 与高亮得以存在的前提——textarea 无法为自身文本的某个区间单独设置样式。草稿框的高度上限为 14 行，因此超过上限之后总得有东西滚动。
+composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)）：`<textarea>` 持有值、选区与光标，但它自己的字形以 `color: transparent` 渲染；用户看到的每一个字符都由其下的 `[data-input-backdrop]` 层绘制，该层同时承载 claim token 高亮、chip 与提示影子文本。这一拆分正是 chip 与高亮得以存在的前提——textarea 无法为自身文本的某个区间单独设置样式。草稿框的高度上限为 14 行，因此超过上限之后总得有东西滚动。
 
 两层各自持有一个滚动偏移，会分两个阶段失效，本次改动是其中的第二个。
 
 第一个阶段是静态的。backdrop 为 `position: absolute; inset: 0; overflow: hidden`——只裁剪、不滚动——浏览器也不会把它的偏移与 textarea 关联起来，于是超过上限之后光标在动而文字冻结在第 1 行。未达上限时这一点不可见，因为两层都停在 0；该缺陷与高度上限同龄，藏在所有截图所捕获的那个静止状态背后。当时的修复是用一个 `scroll` 监听把 textarea 的 `scrollTop` 镜像到 backdrop 上，这让两层在**静止时**保持一致。
 
-第二个阶段正是随后被用户报告的现象：从长草稿的顶部快速滑到底部时，光标像带着惯性一样从自己的文字里往上飞出去，过一会儿又落回原位。原因就是那个镜像。滚轮手势在合成线程上滚动 textarea，不经过主线程；而驱动赋值的 `scroll` 事件在其后才派发，因此中间这些帧里光标位于新偏移、每一个字形却仍位于旧偏移。在同一套几何的独立环境上实测：把偏移改变 200px 并在本任务结束之前读取光标与其字形之间的距离，chromium 分离 203px、firefox 202px、WebKit 203px，一两帧之后才收敛到固定的行盒常量（3/2/3）。每个引擎、每次手势都如此，且滑动越快分离越远。
+第二个阶段正是随后被用户报告的现象：从长草稿的顶部快速滑动时，光标像带着惯性一样从自己的文字里往上飞出去，过一会儿又落回原位。原因就是那个镜像。滚轮手势在合成线程上滚动 textarea，不经过主线程；而驱动赋值的 `scroll` 事件在其后才派发，因此中间这些帧里光标位于新偏移、每一个字形却仍位于旧偏移。在同一套几何的独立环境上实测：把偏移改变 200px 并在本任务结束之前读取光标与其字形之间的距离，chromium 分离 203px、firefox 202px、WebKit 203px，一两帧之后才收敛到固定的行盒常量（3/2/3）。每个引擎、每次手势都如此，且滑动越快分离越远。
 
 任何监听都无法消除这个间隙，因为这个间隙正是监听的定义：它在自己所响应的那件事之后才运行。凡是用 JavaScript 维持两个盒子相等的做法，都会落后于那个不经询问就搬动其中一个盒子的合成器一帧。
 
@@ -52,7 +52,7 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 
 **去掉 backdrop，直接给 textarea 自己的文本上样式。** 这会消除分层，也一并消除这一整类失步。被否决是因为它不可实现：textarea 只渲染一段统一的文本，claim token 高亮、chip 与提示影子文本——backdrop 存在的理由——无从表达。为修滚动而失去它们，是拿一个有界缺陷换一次功能删除。
 
-**用 `contenteditable` div 渲染草稿。** 一个元素、一个偏移、区间可上样式。因代价与缺陷严重不成比例被否决：`contenteditable` 会把输入法组合、撤销/重做、选区语义与粘贴规范化重新压回我们身上，而这些目前都由 textarea 加输入状态机处理，且状态机已经持有一份假定 textarea 取值语义的撤销日志。
+**用 `contenteditable` div 渲染草稿。** 一个元素、一个偏移、区间可上样式。因代价与缺陷严重不成比例被否决：`contenteditable` 会把输入法组合、撤销/重做、选区语义与粘贴规范化重新压回我们身上，而这些目前都由 textarea 加输入状态机处理，且状态机已经持有一份假定 textarea 值语义的撤销日志。
 
 **给三层都加 `scrollbar-gutter: stable`。** 在 textarea 还是滚动者时试过并已回退：WebKit 只对 `overflow-y: auto` 生效、不对 `overflow: hidden` 生效，那 8px 的差距原样留着，却让每个 chromium 用户无条件损失 8px 文本列宽。现在已无意义——三层共享同一包含块，没有什么需要预留。
 
@@ -63,9 +63,9 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 - 光标不可能离开自己的字形。浏览器滚动的是同一个盒子，因此「textarea 把某一行放在哪」与「backdrop 把这一行画在哪」之间的距离在任何偏移下都是一个固定的行盒常量，手势进行中也不例外。场景测试度量的正是这个数。
 - 滚动条从 textarea 移到了滚动容器上——视觉位置相同，只是外移了一层。`.card` 的 l2 token 绑定仍会继承下去。
 - chip、claim token 高亮与文本引用标记在滚动时仍与其字形对齐，因为它们定位在 backdrop 内部、随之移动。除去掉哨兵之外，装饰扫描没有变化。
-- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话记录滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到会话记录的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
+- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话 transcript（文本记录）滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到transcript 的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
 - 翻页与拖拽选区的行为未变，二者均做了新旧对照实测。`PageDown`/`PageUp` 本来就不会移动 textarea 的插入点——chromium 是滚动一页并保持 `selectionStart` 不变，新旧几何皆然，区别只在于滚的是哪个盒子。拖拽选区越过下边缘仍会自动滚动，且落点一致（chromium 628/628、firefox 625/620、WebKit 170/170——WebKit 自动滚动较慢，但改动前后一样慢）。
-- composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，否则第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
+- composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，因此如果没有这个独立 effect，第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
 - 撤销/重做可以在不恢复光标、也不回视的情况下改动草稿：状态机重放上一版草稿，DOM 选区停在浏览器钳位后的位置。这早于本次改动且未被改动——在此点名，是因为另外两处恢复都会回视，会让这处遗漏看起来像有意为之；真被报告时 helper 就在旁边。
 - 任何新增在 backdrop 旁边的层都属于滚动容器**内部**，并且必须与草稿等高，否则就会重新引入这一缺陷。这是 composer 长期存在的风险点：两层拆分对 chip 与高亮是承重的，因此耦合必须来自结构，而不是靠维护。
 
@@ -73,7 +73,7 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 
 [input-bar.spec.tsx](../../../../packages/client/ui-conversation/tests/input-bar.spec.tsx) 中的单元用例断言 jsdom 能看见的部分：同一个滚动盒同时包含 textarea 与 backdrop，backdrop 的文本现在就是草稿本身、不多不少，且渲染后才到达的持久化草稿会回视其光标，同时不从其他控件夺走焦点。jsdom 对任何元素都报告 `scrollHeight === clientHeight` 且从不滚动，因此几何属于浏览器场景；滚轮接力用例改为桩接滚动容器的度量，而非 textarea 的。
 
-[composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) 在 chromium 中针对构建产物度量其余部分：全新工作区空会话的 composer 中一份 40 行草稿，零模型调用。每个度量都在光标自己的坐标系里读取——即 textarea 把第 n 行放在哪，含其自身偏移——再与 backdrop 同一行文本上的 DOM Range 相比，因为这个差值正是用户看到的东西。决定性的用例改变偏移，并**在本任务结束之前**重新读取该差值，也就是在任何 `scroll` 监听可能运行之前：单一滚动容器下为 0，镜像方案下则是整个增量。空洞性保护先断言草稿确实超过了带上限的盒子；其余用例分别覆盖高度上限、三层同一折行宽度、滚轮手势、以换行结尾的草稿，以及过去由 textarea 自身滚动承担的光标回视路径——滚离光标后输入，必须把滚动容器带回光标处。
+[composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) 在 chromium 中针对构建产物度量其余部分：全新工作区的空白 composer 中一份 40 行草稿，零模型调用。每个度量都在光标自己的坐标系里读取——即 textarea 把第 n 行放在哪，含其自身偏移——再与 backdrop 同一行文本上的 DOM Range 相比，因为这个差值正是用户看到的东西。决定性的用例改变偏移，并**在本任务结束之前**重新读取该差值，也就是在任何 `scroll` 监听可能运行之前：单一滚动容器下为 0，镜像方案下则是整个增量。空洞性保护先断言草稿确实超过了带上限的盒子；其余用例分别覆盖高度上限、三层同一折行宽度、滚轮手势、以换行结尾的草稿，以及过去由 textarea 自身滚动承担的光标回视路径——滚离光标后输入，必须把滚动容器带回光标处。
 
 另有一个用例端到端覆盖粘贴路径：短草稿、光标停在末尾，然后派发一个携带真实剪贴板数据的 `paste` 事件——与 Cmd-V 送达的是同一个事件，走同一个处理器——再检查偏移与所粘内容的最后一行。它等待的是偏移而不是「草稿是否溢出」，因为恢复发生在状态机提交草稿之后的下一帧；没有这次回视的构建会卡在这个等待上失败。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
index 7d68e52c82..a972cf44ae 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.md
 2026-07-31-english-compaction-checkpoints.md: dc95ed187a6ba5b86800f06ebefb2776995f9421
-2026-07-31-english-compaction-checkpoints.zh.md: 7cd4179430ed775f3807af5a02e81838e495c81e
+2026-07-31-english-compaction-checkpoints.zh.md: 5b89dca449309abaefe3143f66a2878e2d9eea47
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
index 7cd4179430..5b89dca449 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
@@ -12,14 +12,14 @@ Status: implemented
 
 `COMPACTION_INSTRUCTION` 要求生成英语的内部工程检查点。它要求模型在必要时翻译叙述性源材料，同时保留精确的字面量；这包括路径、命令、错误、标识符、签名，以及精确性重要时的引用措辞。检查点的标题及简洁的工程项目符号仍沿用既有的结构化格式。
 
-这项要求被整合到尾部压缩指令的第一句话中。回放的系统提示词、工具和对话历史与已路由请求保持字节级一致，因此该变更保留 [compaction summary prefix-cache note](2026-07-21-compaction-summary-prefix-cache-reuse.md) 所确立的前缀缓存复用。
+这项要求被整合到尾部压缩指令的第一句话中。回放的系统提示词、工具和对话历史与已路由请求保持字节级一致，因此该变更保留 [压缩摘要前缀缓存说明](2026-07-21-compaction-summary-prefix-cache-reuse.md) 所确立的前缀缓存复用。
 
 ## 考虑过的替代方案
 
 - **让回放的对话决定检查点语言**——不采纳：检查点是持久的提示词前缀，保留短暂的对话文体可能在后续压缩中放大这种影响。
 - **约束对话模型的语言**——不采纳：该策略针对内部检查点，而不是用户可见的对话；对整个对话施加规则会不必要地改变正常交互。
 - **要求仅输出 ASCII**——不采纳：ASCII 是字符集约束，而非工程文体约束，并会不必要地扭曲合法的字面量和技术材料。
-- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出契约中说明该要求更简洁，也直接将其与所请求的检查点绑定。
+- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出约定中说明该要求更简洁，也直接将其与所请求的检查点绑定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index fda3830670..6bf16a8981 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
 2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: 64459614dc3376a1c773de72cd36aa455894a03c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: d5fdf72013259a60df64e8f79e64169770f3435c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index 64459614dc..d5fdf72013 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -1,10 +1,10 @@
-# Agent Note：fail-loud 在退出前释放终端
+# Agent Note: fail-loud 在退出前释放终端
 
 Status: implemented
 
 [English](2026-07-31-fail-loud-releases-the-terminal.md) | 中文
 
-## Problem
+## 问题
 
 配置校验失败的 `dsh` 启动会打印诊断信息，然后把用户丢回一个损坏的 shell：输入不可见，下一条命令还会被残留文本弄乱：
 
@@ -21,20 +21,20 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 `/exit` 路径从不受影响，因为它会释放整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
 
-## Decision
+## 决策
 
 `installFailLoud` 新增可选的 `release` 拆卸回调，在诊断信息与退出之间被等待：
 
 - 诊断信息在 release **之前**写出，因此卡住或失败的 disposer 无法吞掉失败原因。
 - 使用闩锁（latch）而非卸载监听器，来保证被报告的始终是第一个 rejection。若在拆卸期间移除监听器，第二个并发 rejection 就会变成未捕获错误，Node 会在拆卸中途杀死进程——恰好残留下本次要恢复的终端状态。后续 rejection（包括 release 自身的）都会落入已挂起的退出流程。
 - release 以 `FAIL_LOUD_RELEASE_TIMEOUT_MS`（2 秒）为上限，且其 rejection 被吞掉。卡住或失败的 disposer 只会延迟致命退出，绝不会取消它。该定时器保持 **referenced**：一旦 `unref()`，Node 就会在事件循环清空后、恰恰在报告这次失败时以 0 退出，因为 `unhandledRejection` 监听器抑制了默认的致命退出。
-- 不传 `release` 时行为与此前完全一致，因此 ACP、JSON-RPC 和各 demo bin 均无变化。
+- 不传 `release` 时行为与此前完全一致，因此 ACP（Agent Client Protocol）、JSON-RPC 和各 demo bin 均无变化。
 
 `dsh` 的 TUI 启动器传入的 release 会释放根上下文，从而执行 TUI 已有的 `shutdown()` 并把终端交还。
 
 启动器在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值。rejection 到达时 `boot()` 尚未结算，因此在 `await` 之后赋值的 `app.current` 恰好在回调需要它的那一刻仍是 `undefined`。`prepare` 在 Loader 安装之后、任何配置树条目挂载之前运行，覆盖了条目可能 rejection 的整个窗口。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **在 fail-loud 处理函数里直接重置终端**（写 `ESC [ ? 2004 l`、弹出键盘协议、清除 raw 模式）。这会在一个并不拥有终端的包里重复 pi-tui 的拆卸逻辑，并随 pi-tui 启动序列的变化而漂移。它同样无法吸收尚未返回的 Device Attributes 响应——而这正是弄乱下一个提示符的原因，只有在 stdin 仍处于 raw 模式时排空它才能解决。
 
@@ -44,16 +44,16 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 **调整配置顺序，让 `llm-pi-ai` 先于 `ui-tui` 挂载。** 顺序并不是 Loader 提供的保证，而且未来任何条目都可能在 TUI 挂载之后失败。
 
-## Consequences
+## 后果
 
 启动失败现在会在退出前多付出一次树释放的代价（上限 2 秒），退出码仍为 1。作为交换，配置错误的 `dsh` 会交还一个可用的 shell，而不是需要 `stty sane` 或 `reset` 才能恢复的终端。
 
 这项保证属于**拥有终端的那个 bin**：任何抢占终端状态却不传 `release` 的界面都会重新引入该缺陷。`installFailLoud` 自身无法察觉这一点，因为它看不到已挂载的插件对进程做了什么。
 
-## Testing
+## 测试
 
-`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 约定：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
 
-这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
+这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态未被恢复的 [HMR（热模块替换）初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
 测试规范要求：只要改动终端拆卸，就必须有 PTY 用例——这就是它。`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
index c4a5595fea..e2f3b7945f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.md
 2026-07-31-fork-anchor-floors-to-event-seq.md: 2cc8d66942442aca69c930be880cc41d56bced13
-2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 9f443f3d5165c01c6585d33bd6a37e90e9b3bf95
+2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 10a8a994f544834d31ec7b3b4ad7d08b4b7d731d
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
index 9f443f3d51..10a8a994f5 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
@@ -18,11 +18,11 @@ host 的切分规则从来不是障碍。被中止的轮次会记录一条 reaso
 
 向下取整落在锚点自身所在的轮次内，不会回退：每一轮都以 `turn/start` 开头，所以 `turnEnd.seq - 1` 不可能是上一轮的 `turn/end`。host 随后按「首个位于锚点或其之后的 `turn/end`」收口，命中的正是读者点击的那一轮，与消息级 fork 按钮在已完成轮次上一贯承诺的整轮语义一致。
 
-apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
+apiproxy 的 fork 用例固定了 host 这一侧的约定：落在被中止轮次内的取整锚点会将该轮纳入切分结果，并以该轮初始化子会话。
 
 ## 备选方案
 
-**让 wire 接受分数 `atSeq`。** 否决：host 契约要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
+**让 wire 接受分数 `atSeq`。** 否决：host 约定要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
 
 **在已中断的消息上隐藏 fork 按钮。** 否决：从读者主动叫停的那一轮分叉，恰恰是最需要 fork 的场景之一，而 host 侧这个能力一直是好的。
 
@@ -30,6 +30,6 @@ apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮
 
 ## 影响
 
-从已停止的轮次 fork 会得到一个种子切到该轮 `turn/end` 的子会话。被冻结的残缺文本是从 chunk 事件重建出来的，从未成为 `assistant/message`，因此它不会进入子会话的模型上下文——正如源会话恢复时它也不会进入一样，子会话拿到的上下文与源会话一致。
+从已停止的轮次 fork 会得到一个初始化内容截至该轮 `turn/end` 的子会话。被冻结的残缺文本是从分片事件重建出来的，从未成为 `assistant/message`，因此它不会进入子会话的模型 transcript（文本记录）——正如源会话恢复时它也不会进入一样，子会话拿到的上下文与源会话一致。
 
 fork 失败在 chat 入口仍然是静默的。这个 bug 能存活至今，正是因为该调用点丢弃了自己的 rejection；把 fork 错误呈现到 UI 上是另一件事。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
index c78049cc8d..7324984631 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md
 2026-07-31-web-stop-preserves-queue.md: b8bba45009c126495a8b03ee36d6eb2cccac9a93
-2026-07-31-web-stop-preserves-queue.zh.md: 0e1fffae8819bea81b91fae10c76dbadc78474fe
+2026-07-31-web-stop-preserves-queue.zh.md: dce4f431f1f433afce69689cd5220e36a68b85e2
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
index 0e1fffae88..dce4f431f1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
@@ -16,7 +16,7 @@ Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({
 
 AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。
 
-该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
+该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认约定仍为广义取消，ACP（Agent Client Protocol）和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
 
 ## 考虑过的替代方案
 
@@ -30,7 +30,7 @@ AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的
 
 ## 验证
 
-AgentLoop 覆盖会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP／SSE 驱动已组装组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。
+AgentLoop 覆盖测试会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP/SSE（Server-Sent Events）驱动已组装的组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
index 39bf79e628..746dd01ce0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
 2026-08-01-ask-user-delegated-caller-guard.md: 0350a7383f7ace6ecd742c98db18f8b977720cf9
-2026-08-01-ask-user-delegated-caller-guard.zh.md: 9c19722feb4586e07845fd20279574301267542d
+2026-08-01-ask-user-delegated-caller-guard.zh.md: 811a550bacc6f9019fdd08c7b555bc11753a9477
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
index 9c19722feb..811a550bac 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 以运行时所有权为权限依据。携带谱系的会话在无所有者的情况下恢复时就是运行时根，可以提问；存活子级即使持久化 `delegationDepth` 为零，仍无资格提问。不带 agent 的程序化调用继续沿用现有提供方路径。
 
-共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托契约本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
+共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托约定本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
 
 该安全边界与浏览器的 composer 选举相互独立。提议的[语义 composer 阶段](../../proposed/architecture/2026-08-08-semantic-composer-chain-phases.md)解决已有待处理交互与只读 subagent 界面的排序方式；它不会削弱此运行时守卫。
 
@@ -34,6 +34,6 @@ Status: implemented
 
 运行时中归属于其他 agent 的子级调用会以稳定的结构化错误快速失败，而不是挂起。注册表中的确切存活根和不带 agent 的程序化调用仍有资格提问，包括带有历史子级谱系的已恢复会话。`ask_user_question` 与 `exit_plan_mode` 会收到相同的中性纠正指引，而其模型可见 schema 和系统提示词前缀保持不变；只有追加的错误结果发生变化，因此现有 KV Cache 前缀仍可复用。
 
-## Testing
+## 测试
 
 服务测试覆盖持久化深度为零的存活子级、深度为一的已恢复运行时根、缺失注册表、仅 id 相同的陈旧对象，以及每次拒绝都不调用提供方。工具与 plan-mode 测试证明两个消费方都会呈现中性的 `DELEGATED_CALLER` 结果，且绝不触达提供方。无密钥组装快照委托一个尝试调用 `ask_user_question` 的子级，固定其错误工具结果和最终交接，并证明父级可以完成，而不是一直等待回答。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
index c8784f5991..8ee0551df5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.md
 2026-08-02-goal-round-wrapup-message.md: c6bc3d5912b0789efde55880c2be892e98e34a5b
-2026-08-02-goal-round-wrapup-message.zh.md: 0a504b4dcc61feb932775b3d9ffd8424f3b0597d
+2026-08-02-goal-round-wrapup-message.zh.md: 46876f09edfea631b9621caf417ecf4df4ccff2d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
index 0a504b4dcc..46876f09ed 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：Goal Round 收尾消息
+# Agent Note: Goal Round 收尾消息
 
 Status: implemented
 
@@ -6,26 +6,26 @@ Status: implemented
 
 ## 问题
 
-自主 Goal Round 报告 `update_goal` `complete` 或 `blocked` 时，物理轮次在工具结果处直接终结，模型在调用之后再无发言机会。会话终止在一张裸的 `update_goal` 卡片上，内测同学的观感是 agent 话说到一半戛然而止：模型调用前的文本通常预告了一份汇报（“目标达成，标记完成：”）却永远没有下文，因为标准 tool-use 预期是工具结果之后还有一条 assistant 消息，而 Goal Round 提示词与工具描述都没有说明这次调用是终点。硬停止来自 [goal 工具决策](../feature/2026-07-19-model-facing-goal-tools.md)，本 note 取代其中的轮次停止条款。
+自主 Goal Round 报告 `update_goal` `complete` 或 `blocked` 时，物理轮次在工具结果处直接终结，模型在调用之后再无发言机会。会话终止在一张裸的 `update_goal` 卡片上，内测同学的观感是 agent（智能体）话说到一半戛然而止：模型调用前的文本通常预告了一份汇报（「目标达成，标记完成：」）却永远没有下文，因为标准 tool-use 预期是工具结果之后还有一条 assistant 消息，而 Goal Round 提示词与工具描述都没有说明这次调用是终点。硬停止来自 [goal 工具决策](../feature/2026-07-19-model-facing-goal-tools.md)，本 Agent Note 取代其中的轮次停止条款。
 
 ## 决策
 
-Goal Round 的 `complete` 或 `blocked` 成功不再调用 `concludeTurn()`。工具改为在自己的结果上附带一条收尾上下文：以 `{ kind: 'plugin', plugin: 'tool-goal' }` 为 source 的 user 消息，携带 `<goal_complete>`/`<goal_blocked>` 指令，要求模型向用户写出有依据的收尾消息且不再调用工具。之后轮次经由 agent loop 常规的无工具调用停止路径结束，因此不存在新的 loop 原语，steering 语义不受影响。人类直接变更保持原样、不注入指令。代价是每个 goal 生命周期一次额外模型请求，而非每轮一次。
+Goal Round 的 `complete` 或 `blocked` 成功不再调用 `concludeTurn()`。工具改为在自己的结果上附带一条收尾上下文：以 `{ kind: 'plugin', plugin: 'tool-goal' }` 为 source 的 user 消息，携带 `<goal_complete>`/`<goal_blocked>` 指令，要求模型向用户写出有依据的收尾消息且不再调用工具。之后轮次经由 agent loop（智能体循环）常规的无工具调用停止路径结束，因此不存在新的 loop 原语，steering（中途引导）语义不受影响。人类直接变更保持原样、不注入指令。代价是每个 goal 生命周期一次额外模型请求，而非每个 Round 一次。
 
-指令措辞通过在 `deepseek-v4-pro` 上用重构的 Goal Round 转录做 A/B 采样选定：结构化指令（结果、验证、产物、后续）在完整度上稳定优于极简“总结一下”；补充“以会话内证据为准”的 grounding 条款让无依据细节从断言事实退为带保留的建议；而无指令对照组的收尾方差很大，包括言之凿凿的文件级细节编造。
+指令措辞通过在 `deepseek-v4-pro` 上用重构的 Goal Round transcript（文本记录）做 A/B 采样选定：结构化指令（结果、验证、产物、后续）在完整度上稳定优于极简「总结一下」；补充「以会话内证据为准」的 grounding 条款让无依据细节从断言事实退为带保留的建议；而无指令对照组的收尾方差很大，包括言之凿凿的文件级细节编造。
 
-为让 keyless 证明可脚本化，快照设施补了一项能力：`dsh-llm-replay` 会针对实时请求解析脚本条目中的 `{{fromRequest:<regex>}}` 占位符，因为静态伴随文件不可能预知模型必须回填进 `update_goal` 的随机生成 goal id。
+为让 keyless 证明可脚本化，快照 harness 补了一项能力：`dsh-llm-replay` 会针对实时请求解析脚本条目中的 `{{fromRequest:<regex>}}` 占位符，因为静态伴随文件不可能预知模型必须回填进 `update_goal` 的随机生成 goal id。
 
 ## 验证
 
-`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符契约：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一轮 → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同轮内的收尾 assistant 消息与 `completed` 轮次结束。
+`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符约定：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一个 Round → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同一轮次内的收尾 assistant 消息与 `completed` 轮次结束。
 
 ## 曾考虑的替代方案
 
 - **在 `update_goal` 的 UI 卡片上展示完成文本** — 拒绝：`complete` 如今不携带任何自由文本；新增 `summary` 参数会让面向用户的汇报走工具参数通道，而且依然砍掉了模型在结果之后的自然发言。
-- **保留 `concludeTurn()` 并新增“再多一步纯文本”的 loop 原语** — 拒绝：为常规停止路径已经能提供的行为（只要没有结果终结轮次）增加新的 `agent-loop` 机制。
-- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧契约和工具的可回放值搅在一起。
+- **保留 `concludeTurn()` 并新增「再多一步纯文本」的 loop 原语** — 拒绝：为常规停止路径已经能提供的行为（只要没有结果终结轮次）增加新的 `agent-loop` 机制。
+- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧约定和工具的可回放值搅在一起。
 
-## Consequences
+## 后果
 
-每个自主 goal 都以一条面向用户的收尾消息结束，而非一张裸工具卡片，代价是每个 goal 生命周期一次模型请求。`concludeTurn()` 保留其 loop 语义，但在 subagent 结构化输出之外失去了唯一的一方调用者。快照场景现在可以通过 `{{fromRequest:...}}` 脚本化只在运行时才存在的值，为任何“回显 id”类工具流程（不限于 goal）解锁 keyless 覆盖。
+每个自主 goal 都以一条面向用户的收尾消息结束，而非一张裸工具卡片，代价是每个 goal 生命周期一次模型请求。`concludeTurn()` 保留其 loop 语义，但在 subagent 结构化输出之外失去了唯一的第一方调用者。快照场景现在可以通过 `{{fromRequest:...}}` 脚本化只在运行时才存在的值，为任何「回显 id」类工具流程（不限于 goal）解锁 keyless 覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml
index 7f4b8c7824..f6e85d05e1 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md
 2026-08-02-message-fork-actions-require-completed-turn-tail.md: abdcbc79948c67619bb70a8a87741046f65b8838
-2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md: a93b572c6db3c76ce3869747fd9a7660bf3ea395
+2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md: 7df9b04e982e9d290030cb9be6c27bb68541aaeb
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md
index a93b572c6d..7df9b04e98 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md
@@ -12,7 +12,7 @@ Web 会话把分支操作挂到每个轮次中最后一个文本非空的 assist
 
 `ConversationSnapshot.turnEnds` 保留原始事件窗口中的已完成轮次边界。会话视图按各边界遍历 transcript（文本记录）节点，仅当边界的最后一个节点是用户消息、持久 steering（中途引导）消息或含内容的 assistant 消息时才启用分支操作。开放轮次没有符合条件的消息；如果后面还有工具结果、只有推理内容的中断、轮次错误或其他 transcript 节点，较早消息上的分支操作会保持不可用。不可用的控件仍然可见、可聚焦、可悬停；`aria-disabled`、tooltip 与 `aria-describedby` 会说明已完成尾部这一要求，且不会发送 Host 请求。复制和时钟仍可在既有消息 chrome 下使用，Host 按已完成轮次 fork 的语义保持不变。
 
-本资格判定中消息气泡的那一半已被 [user 气泡分支移除决策](../simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)取代：user 与 steering 气泡不再渲染该控件，因此只有内容 assistant 尾部可以 fork；assistant 侧门禁及其可见但不可用的呈现保持有效。
+本资格判定中消息气泡的那一半已被 [user 气泡分支移除决策](../simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)取代：user 与 steering 气泡不再渲染该控件，因此只有含内容的 assistant 尾部可以 fork；assistant 侧门禁及其可见但不可用的呈现保持有效。
 
 本决策收紧了较早的 [Web 会话 fork 操作决策](../feature/2026-07-27-web-session-fork-actions.md)所定义的消息资格。Session 行 fork 仍选择最新的已完成轮次；符合条件的消息操作仍通过共享 client 运行时操作传递其事件 seq。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
index eeac8a251c..c68279a2b4 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.md
 2026-08-02-todo-first-composer-context-order.md: 26962426c763c6911fc61acab09cdb96725922b1
-2026-08-02-todo-first-composer-context-order.zh.md: a81401ffeb8df5855b584a5727e24067d9fb1e70
+2026-08-02-todo-first-composer-context-order.zh.md: 2bd09a95832b22afc919a6f2d18bef94d4209c40
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
index a81401ffeb..2bd09a9583 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
@@ -14,7 +14,7 @@ composer 上下文堆栈将 Goal 渲染在 Todo 之前，但 Harness 设计稿
 
 Todo、Goal 与可见的 Queue 面板共用 800px composer 宽度上限内的 752px 卡片列。Queue 保留 776px 包装层，并在两侧各留 12px 透明内缩，因为该包装层负责与 composer 重叠。Todo 是独立卡片，而非包装层，因此其响应式宽度和最大宽度都会直接扣除两层内缩。Goal 使用相同的响应式卡片列，并将内层横条的宽度上限设为 752px，从而在低于桌面宽度上限时也保持边缘对齐。
 
-[composer 堆栈契约](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
+[composer 堆栈约定](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 36c7895ac2..5c7deb9700 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
 2026-08-03-cli-signal-shutdown-escalation.md: c8aac6e2be927bd1f4a445c00e0aaa870b10a465
-2026-08-03-cli-signal-shutdown-escalation.zh.md: 66fe7062ea35a6cc91dbdd6644088cb086a15439
+2026-08-03-cli-signal-shutdown-escalation.zh.md: 14e2149eb5153b3743e188c6b233d000b36d60db
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index 66fe7062ea..14e2149eb5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：Web 与 headless 的有界信号关闭和重复信号强制退出
+# Agent Note: Web 与 headless 的有界信号关闭和重复信号强制退出
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-03-cli-signal-shutdown-escalation.md) | 中文
 
@@ -39,7 +39,7 @@ headless 对完成的轮次仍以 0 退出，对其他轮次结束原因或 API
 
 ## 后果
 
-健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭契约已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
+健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭约定已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
 
 该控制器属于启动器基础设施，而不是 Cordis 插件：它不会声称 dispose 已经完成，也不会削弱普通 disposer 必须达到完全停稳状态的生命周期规则。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 51fbed7ba9..fad349792a 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
 2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 5f8d50c4c0103eb2209eafb89cf34233c4c1bc35
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: c52c2c2f4e7375e4c783e43c58e6fe0e3eb6b44b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index 5f8d50c4c0..c52c2c2f4e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：HMR 初始扫描使失败的启动死锁为静默的 exit 13
+# Agent Note: HMR（热模块替换）初始扫描使失败的启动陷入死锁，最终静默地以 13 退出
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-03-hmr-initial-scan-boot-deadlock.md) | 中文
 
@@ -11,16 +11,16 @@
 两个缺陷叠加：
 
 1. **并发的 Include apply 破坏事务化的 group update。** HMR 主 watcher 的 chokidar 初始扫描会把每个已存在的文件重新宣告为 `add`。其中配置文件的 `add` 在 Include 的首次 apply 尚未结束时触发了 `Include.refresh()`（内容去重键 `this.content` 只在 apply 完成后才提交）。同一 group 上两个并发的 `EntryGroup.update` 会在相同条目上交错执行 create 与回滚，导致 Include fiber 永远无法结算：`loader.create` 挂起，`boot()` 既不 resolve 也不 reject，事件循环排空后 Node 以 13 退出。
-2. **仅序列化 apply 会让失败回滚死锁。** 将 Include 的变更排入队列后，首次 apply 失败时的回滚会释放每个已挂载条目——包括 `hmr`，而它的拆卸会等待自身的 refresh 任务排空。扫描触发的 refresh 任务正排在 Include 队列中、位于正在回滚的那次 apply 之后：回滚等 HMR，HMR 等 refresh，refresh 等 apply。
+2. **仅序列化 apply 会让失败回滚死锁。** 将 Include 的变更排入队列后，首次 apply 失败时的回滚会对每个已挂载条目执行 dispose（资源释放）——包括 `hmr`，而它的拆卸会等待自身的 refresh 任务排空。扫描触发的 refresh 任务正排在 Include 队列中、位于正在回滚的那次 apply 之后：回滚等 HMR，HMR 等 refresh，refresh 等 apply。
 
-## 决定
+## 决策
 
 两处修复都落在 vendored 包中（记录于 `vendor/README.md`）：
 
-- `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 一条的 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
+- `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 各自的一条 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
 - `hmr/src/index.ts` 给主 watcher 传入 `ignoreInitial: true`。初始扫描只会重新宣告启动刚刚消费过的文件；抑制它同时消除了启动期 refresh 和对已加载模块的多余 `add` 事件。`registerConfig()` 保留自己 `ignoreInitial: false` 的 watcher，因为注册时已存在的个人配置必须恰好应用一次。
 
-两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚释放整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
+两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚对整棵树执行 dispose（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
 
 ## 曾考虑的替代方案
 
@@ -28,14 +28,14 @@
 
 **只做序列化。** 把破坏转化为上述回滚死锁；进程仍然静默地以 13 退出。
 
-**在 HMR 拆卸时取消排队中的 refresh。** 需要在 `refreshConfig` 的任务循环和 Include 队列中铺设取消机制，而 `ignoreInitial` 已把该场景从每次启动中移除；在真实触发条件出现之前不值得引入这套机构。
+**在 HMR 拆卸时取消排队中的 refresh。** 需要在 `refreshConfig` 的任务循环和 Include 队列中铺设取消机制，而 `ignoreInitial` 已把该场景从每次启动中移除；在真实触发条件出现之前不值得引入这套机制。
 
 ## 后果
 
 落在 watcher 启动扫描窗口内的配置文件编辑，现在由下一个 `change` 事件而非扫描本身拾取；稳态的重载行为不变。
 
-仍留有一个潜在缺口：在一次*失败的*首次 apply 期间进行的配置编辑，仍可能排入一个被回滚的 HMR 拆卸所等待的 refresh——同样的死锁形态，但触发窗口缩小到一次失败启动的人力尺度。若它真的发生，修复方向是在 HMR 拆卸时取消 refresh 任务。
+仍留有一个潜在缺口：在一次*失败的*首次 apply 期间进行的配置编辑，仍可能排入一个被回滚的 HMR 拆卸所等待的 refresh——同样的死锁形态，但触发窗口达到一次失败启动这样的人可操作时间尺度。若它真的发生，修复方向是在 HMR 拆卸时取消 refresh 任务。
 
 ## 测试
 
-`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端约定：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已完成 dispose 的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
index c4a8fd6268..64ec136c6d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md
 2026-08-04-composer-tab-gutter-reservation.md: 3b28c35c1f11676e41cabde76d1b0d16c688f034
-2026-08-04-composer-tab-gutter-reservation.zh.md: 26e8b6bff73a01e6518f3918d201330c1d029876
+2026-08-04-composer-tab-gutter-reservation.zh.md: 8c435d85a2a068684ac4781296963f822df43484
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
index 26e8b6bff7..8c435d85a2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
@@ -10,15 +10,15 @@ composer 座位在组件树中只有一个节点、一个位置，但它究竟
 
 在 Chat 中它是会话列滚动容器（`[data-conversation-scroll]`）的 sticky **子元素**，因而依附于该容器的 content box——而占布局宽度的滚动条会把这个盒子收窄一条滚动条的宽度。声明了 `data-conversation-composer-overlay` 的视图（Trajectory 即是其一）会把会话列的滚动搬进视图自身：以该属性为条件的那条分支把滚动容器留作 `overflow: hidden`，并把座位改为绝对定位——对齐的是 padding box，而滚动条从不收窄这个盒子。
 
-于是只要对话记录超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：对话增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
+于是只要transcript（文本记录）超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：transcript 增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
 
 ## 决策
 
 `.scrollBody` 无条件声明 `scrollbar-gutter: stable`，overlay 分支则把同一个盒子在两个轴向上都声明为滚动容器——`overflow-x: hidden; overflow-y: auto`——而不再是 `overflow: hidden`。
 
-这两半是同一处改动。预留使两种状态依附于同一个宽度；把 overlay 分支声明为滚动容器，才使这条预留真正抵达它。选 `stable` 而非 `auto`，是因为 `auto` 只在盒子确实溢出时才预留，而"溢出与否"恰恰就是两个标签页之间的那点差别——`auto` 的写法只是把缺陷重述一遍，并不能修掉它。
+这两半是同一处改动。预留使两种状态依附于同一个宽度；把 overlay 分支声明为滚动容器，才使这条预留真正抵达它。选 `stable` 而非 `auto`，是因为 `auto` 只在盒子确实溢出时才预留，而「溢出与否」恰恰就是两个标签页之间的那点差别——`auto` 的写法只是把缺陷重述一遍，并不能修掉它。
 
-overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图把它填满（`flex: 1 1 0`，且自带裁剪），座位不在常规流中，因此没有任何手势与裁剪行为发生变化。变化的是引擎会认哪些声明。WebKit 对 `overflow-y: auto` 的盒子应用 `scrollbar-gutter`，对 hidden 的盒子则忽略它——这是在本应用 composer 自身的图层上实测所得，并记录于 [composer 滚动容器记录](2026-07-31-composer-text-layers-share-one-scrollport.md)——所以把预留留在一个 hidden 盒子上，会在 Chromium 上成立，在 Safari 上悄无声息地不成立。
+overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图把它填满（`flex: 1 1 0`，且自带裁剪），座位不在常规流中，因此没有任何手势与裁剪行为发生变化。变化的是引擎会认哪些声明。WebKit 对 `overflow-y: auto` 的盒子应用 `scrollbar-gutter`，对 hidden 的盒子则忽略它——这是在本应用 composer 自身的图层上实测所得，并记录于 [composer 滚动视口记录](2026-07-31-composer-text-layers-share-one-scrollport.md)——所以把预留留在一个 hidden 盒子上，会在 Chromium 上成立，在 Safari 上悄无声息地不成立。
 
 横向轴是显式声明的，而不是交给推导：单轴滚动的盒子会把另一轴的 `visible` 计算为 `auto`，于是只要某个视图的内容第一次伸出列外，它就会长出自己的横向滚动条。
 
@@ -30,21 +30,21 @@ overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图
 
 **保留 `overflow: hidden`，只加 `scrollbar-gutter: stable`。** 单行版本。它能在浏览器车道所用的引擎上修掉可见症状，却把症状原封不动留在 Safari 上，而且任何测试都不会失败——这正是改动的后一半所要防的失效模式。
 
-**让 Chat 的 composer 座位也移出滚动容器，使 overlay 的几何成为唯一的几何。** 这是从根上删掉差异，而不是调和它，代价是放弃一项刻意的性质：sticky 座位位于滚动流之内，因此在 composer 上滚轮会带动对话记录（[sticky composer](2026-07-29-sticky-composer-conversation-scroll.md)），其上方的渐隐遮罩也由座位自身的背景绘制。两者都是有主、有覆盖的既有行为；为了消除 8px 的不对称而重建它们，是更大的改动而非更小的。
+**让 Chat 的 composer 座位也移出滚动容器，使 overlay 的几何成为唯一的几何。** 这是从根上删掉差异，而不是调和它，代价是放弃一项刻意的性质：sticky 座位位于滚动流之内，因此在 composer 上滚轮会带动对话记录（[sticky composer](2026-07-29-sticky-composer-conversation-scroll.md)），其上方的渐隐遮罩也由座位自身的背景绘制。两者都是已有明确归属且各有测试覆盖的行为；为了消除 8px 的不对称而重建它们，是更大的改动而非更小的。
 
 **给会话列加上一条滚动条宽度的内边距，而不是预留滚动条槽。** 内边距无论是否存在滚动条都会生效，因此在每种状态下都无条件付出这份宽度，而且它把一个由引擎在布局期决定的值钉死在样式表里。否决理由与侧边栏列表当初否决它时相同。
 
 ## 后果
 
-- Chat 的内容列永久变窄 8px——hero 态与对话记录尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
-- 一条声明覆盖三种切换，因为这三者本就是同一个差异：Chat ↔ Trajectory、Chat 内部的短对话 ↔ 可滚动对话，以及 hero ↔ 第一个可滚动轮次。
+- Chat 的内容列永久变窄 8px——hero 态与transcript 尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
+- 一条声明覆盖三种切换，因为这三者本就是同一个差异：Chat ↔ Trajectory、Chat 内部 transcript 较短 ↔ transcript 可滚动，以及 hero ↔ 第一个可滚动轮次。
 - overlay 状态现在是一个滚动容器。今天其中没有任何内容会溢出；将来若有视图允许自身内容超出会话列，这个盒子会滚动而不是裁剪，那个视图就需要像 Trajectory 视图那样自带裁剪。
-- 提交的 golden 记录了预留的带宽，因此样式表中 `::-webkit-scrollbar` 宽度的变化——决定这条预留有多宽的那个值——会在本场景中与在侧边栏场景中一样，以可评审的 diff 形式出现。
+- 提交的 golden 记录了预留条带，因此样式表中 `::-webkit-scrollbar` 宽度的变化——决定这条预留有多宽的那个值——会在本场景中与在侧边栏场景中一样，以可评审的 diff 形式出现。
 
 ## 测试
 
 `apps/web/tests/composer-tab-geometry.e2e.ts` 在两个标签页下测量输入卡片的矩形，分别取卡片处于宽度上限的视口与卡片随列收缩的视口，并断言这两个矩形是同一个矩形。只有真实引擎能报告这件事：jsdom 给每个元素的盒子尺寸都是零，也没有滚动条，因此单元测试只能断言那些声明存在，无法断言两种状态落在同一位置。出于同一原因，本次没有附带读取 CSS 文本的单元测试——它只会把声明复述一遍，并不会补上浏览器车道尚未确立的事实。
 
-该场景启动 chromium 时去掉了 Playwright 默认的 `--hide-scrollbars`，这一点是承重的：带上该参数时滚动条不占任何布局宽度，两个标签页在改动前后同样一致，文件中的每一处比较都会空洞地通过。实测：带上该参数时，改动前的层叠让两侧带宽都是 0；去掉它则是 8 与 0。
+该场景启动 chromium 时去掉了 Playwright 默认的 `--hide-scrollbars`，这一点是承重的：带上该参数时滚动条不占任何布局宽度，两个标签页在改动前后同样一致，文件中的每一处比较都会空洞地通过。实测：带上该参数时，改动前的层叠让两条预留带的宽度都是 0；去掉它则分别是 8 与 0。
 
-随后，改动前的层叠会被注入页面——滚动容器上 `scrollbar-gutter: auto`，overlay 分支上 `overflow: hidden`——并在其下测量同样的两个标签页，这正是把"卡片确实没动"与"标签页切换根本没到达布局"区分开的那一步。它把上报的症状复现为一个数字：每条边 4px，恰是 8px 带宽的一半。golden 把这份对照与修复后的状态并排记录，因此 fixture 承载的是这次改动所消除的那个差值，而不仅仅是它的缺席。
+随后，改动前的层叠会被注入页面——滚动容器上 `scrollbar-gutter: auto`，overlay 分支上 `overflow: hidden`——并在其下测量同样的两个标签页，这正是把「卡片确实没动」与「标签页切换根本没到达布局」区分开的那一步。它把上报的症状复现为一个数字：每条边 4px，恰是 8px 带宽的一半。golden 把这份对照与修复后的状态并排记录，因此 fixture（测试前置数据）承载的是这次改动所消除的那个差值，而不仅仅是它的缺席。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
index 754ca8bbd0..9f804b5ea9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
 2026-08-04-conversation-column-one-axis-scroll.md: 9a487c506a75033d0854f08e95da24704309003d
-2026-08-04-conversation-column-one-axis-scroll.zh.md: 23441a7c8655d1f19d3c0fe0f661f81f69b55dba
+2026-08-04-conversation-column-one-axis-scroll.zh.md: b86f86f55757dff4fddab4c4e2ac64fa7c19fe59
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
index 23441a7c86..b86f86f557 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：会话列只在一个轴上滚动
+# Agent Note: 会话列只在一个轴上滚动
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-04-conversation-column-one-axis-scroll.md) | 中文
 
@@ -10,7 +10,7 @@
 
 这处外溢是设计使然，保持不变。真正让它对用户可见的是它所处的滚动容器。`[data-conversation-scroll]` 只声明了 `overflow-y: auto`，另一个轴留在初始值 `visible`；而一个在某一轴上滚动的盒子，会把另一轴的 `visible` 计算为 `auto`。于是每一条比该椭圆窄的列都真的给出了一段横向滚动范围——在笔记本实际会产生的几档宽度上，实测为 24–95px。
 
-## 决定
+## 决策
 
 `.scrollBody` 声明 `overflow-x: hidden`。这条列明确声明自己是单轴滚动容器，而不是把第二个轴交给推导。
 
@@ -20,7 +20,7 @@
 
 **把椭圆缩到列内。** 否决。椭圆的宽度正是让它 `stdDeviation="50"` 的模糊随输入卡片缩放的依据（figma 313:14109）；约束宽度会使列越窄模糊越紧，等于为修一条滚动条而制造一处视觉回归。
 
-**给椭圆套一层裁剪盒。** 否决。这层盒子唯一的职责是抵消列本就会裁剪的溢出，而推导出的 `overflow-x: auto` 仍然留在原处，等着下一个外溢的元素——会话流里这样的候选者不少。
+**给椭圆套一层裁剪盒。** 否决。这层盒子唯一的职责是抵消列本就会裁剪的溢出，而推导出的 `overflow-x: auto` 仍然留在原处，等着下一个外溢的元素——transcript（文本记录）里这样的候选者不少。
 
 **依赖外框的 `.centerCol { overflow: hidden }`。** 它帮不上忙。那处裁剪在滚动容器之外，只能在列边界处遮住椭圆探出的部分，而里面的容器照样可以滚过去够到它。用户报告的那条滚动条属于内层容器。
 
@@ -28,9 +28,9 @@
 
 ## 测试
 
-[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) 扫过一组把椭圆宽度夹在中间的视口宽度，在每一档上向列横向滚轮并读取 `scrollLeft`。提交的 golden 逐档记录该关系；最宽的一档是椭圆根本不外溢的对照。
+[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) 扫过一组把椭圆宽度夹在中间的视口宽度，在每一档上于列上触发横向滚轮事件并读取 `scrollLeft`。提交的 golden 逐档记录该关系；最宽的一档是椭圆根本不外溢的对照。
 
-两道防线保证该场景不流于形式。空断言防线断言窄档上椭圆确实仍伸出列外，使这项主张不可能因为症状出于无关原因消失而通过。变异对照则在页面内把 `overflow-x: auto` 强制改回，证明同一手势在同一时序下能把列带到正向滚动边界。测试直接测量该边界，因为稳定的滚动条槽可能让部分外溢处于滚动原点的负向。没有这项对照，`scrollLeft` 读到 0 同样可以解释为滚轮根本没送达。
+两道防线保证该场景不流于形式。空断言防线断言窄档上椭圆确实仍伸出列外，使这项主张不可能因为症状出于无关原因消失而通过。变异对照则在页面内把 `overflow-x: auto` 强制改回，证明同一手势在同一时序下能把列带到正向滚动边界。测试直接测量该边界，因为稳定的滚动条槽可能让部分外溢处于滚动原点的负向。没有这项对照，`scrollLeft` 读到 0 同样可以解释为滚轮事件根本没送达。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
index 02ea7ca431..c4244fd963 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
 2026-08-04-load-pre-react-loop-sessions.md: b7dcad1ff7fe0aa8239ac03f52b50dfa55417515
-2026-08-04-load-pre-react-loop-sessions.zh.md: 14c6dcc7b4da016ebef424a66fae0b96fb469cd4
+2026-08-04-load-pre-react-loop-sessions.zh.md: 0bd4391fa09cf4c554e77fef03575f9f1788bc01
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
index 14c6dcc7b4..0bd4391fa0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
@@ -14,23 +14,23 @@ react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持
 
 `PersistenceCoordinator` 会在后端解码后识别 react-loop 重构前的确切形状，并将其投影为当前读取视图。它移除已废弃的 `turn/start.trigger`，把 `steering/message` 转换为同一条带标识的 `user/message`，将旧版失败事实映射为当前结构化错误，把 `disposed` 折叠为带 `disposed` 原因的已中止轮次，并用仅供持久化导入使用的 `{ kind: 'legacy' }` 原因表示粗粒度中止记录，因为无法获得其调用方。
 
-协调器会把该投影应用于 `load`、`inspect`、接管、HMR 前缀比较和 `readFrom`。可寻址的 `readFrom` 通常只读取后缀；如果后缀包含需要更早替换标识的旧版事件，协调器会先加载并规范化完整前缀，再返回所请求的 seq 范围。
+协调器会把该投影应用于 `load`、`inspect`、接管、HMR（热模块替换）前缀比较和 `readFrom`。可寻址的 `readFrom` 通常只读取后缀；如果后缀包含需要更早替换标识的旧版事件，协调器会先加载并规范化完整前缀，再返回所请求的 seq 范围。
 
-导入器不会合成 inbox splice。恢复后的 react-loop 重构前 agent 从空的待处理列表开始，这与基线运行时无法持久化待处理 inbox 工作的行为一致。已存储产物仍然仅追加，后续事件使用当前格式。
+导入器不会合成 inbox splice。恢复后的 react-loop 重构前 agent（智能体）从空的待处理列表开始，这与基线运行时无法持久化待处理 inbox 工作的行为一致。已存储产物仍然仅追加，后续事件使用当前格式。
 
 ## 考虑过的替代方案
 
-**将同版本记录视为不受支持。** 这符合预发布阶段的默认立场，但会使 PR 基线产生的会话无法恢复，尽管已移除的 steering 内容和终止事实都有完整映射。
+**将同版本记录视为不受支持。** 这符合预发布阶段的默认立场，但会使 PR（Pull Request）基线产生的会话无法恢复，尽管已移除的 steering 内容和终止事实都有完整映射。
 
 **将旧 inbox 通知回放为持久 splice。** 这些通知不是会话事件，也无法提供可信的待处理状态快照。如果无法获知每一次领取和丢弃，就推断插入操作，会让已消费的工作再次执行。
 
 **将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会虚构来源。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
 
-**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加契约，并要求为读取兼容边界建立后端专用的原子迁移机制。
+**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立后端专用的原子迁移机制。
 
 ## 后果
 
-以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器契约覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
+以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器约定覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
 
 此例外支持基线格式，不支持重构开发期间产生的中间格式。具体而言，它没有为更早的实验性 `agent/inbox/spliced` 载荷定义迁移。通过确切形状识别，当前格式外观相似但结构错误的记录仍会走拒绝路径，不会被猜测性地转换为有效记录。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
index dfaaea4ab7..21705c72ee 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
 2026-08-05-context-meter-blind-to-compaction.md: 8f4845c3c9bf52c5c3a2d39dee2ff25bda30c7bd
-2026-08-05-context-meter-blind-to-compaction.zh.md: 94ada0a9118db63876d5805ef5a8197d9c764102
+2026-08-05-context-meter-blind-to-compaction.zh.md: 7df587d61cc487497a3a95263e10e3aa6f65943b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
index 94ada0a911..7df587d61c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：上下文仪表看不见压缩
+# Agent Note: 上下文仪表看不见压缩
 
 Status: implemented
 
@@ -6,22 +6,22 @@ Status: implemented
 
 ## 问题
 
-composer 的[上下文仪表](../feature/2026-08-05-composer-context-meter-breakdown.md)的圆环、百分比与 `~已用 / 容量` 标题都取自 `contextPressure.pressureTokens`，即提供方报告的最新提示词规模。这个数字只在某个请求报告用量时才会移动，而压缩不报告用量：`compact-basic` 通过直连的 `ctx.llm.stream()` 调用生成摘要，只追加 `compact/start`、`compact/summary`、用作替换的 `user/message` 和 `compact/end`——没有 `assistant/message`，也没有用量分片。
+composer 的[上下文仪表](../feature/2026-08-05-composer-context-meter-breakdown.md)的圆环、百分比与 `~已用 / 容量` 标题都取自 `contextPressure.pressureTokens`，即提供方报告的最新提示词规模。这个数字只在某个请求报告用量时才会移动，而压缩（compaction）不报告用量：`compact-basic` 通过直连的 `ctx.llm.stream()` 调用生成摘要，只追加 `compact/start`、`compact/summary`、用作替换的 `user/message` 和 `compact/end`——没有 `assistant/message`，也没有用量分片。
 
-于是在唯一一个专门用来改变它的操作面前，这块仪表纹丝不动。通过真实 agent loop 驱动一次 `compactNow`：
+于是在唯一一个专门用来改变它的操作面前，这块仪表纹丝不动。通过真实的 agent loop（智能体循环）驱动一次 `compactNow`：
 
 ```
 BEFORE compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages 4365]
 AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages  286]
 ```
 
-折叠表层得出的组成明细行下降了 93%。而圆环——那个主要的可操作元素，也正是用户压缩完立刻会去点开面板的理由——完全没动，而且要等到又跑完一整轮才会动。此时面板上的标题与明细行相差一个数量级以上，恰恰发生在读者最可能去把明细行加总的时刻。
+折叠表层得出的组成明细行下降了 93%。而圆环——那个主要的可操作元素，也正是用户压缩完立刻会去点开面板的理由——完全没动，而且要等到又跑完一整个轮次才会动。此时面板上的标题与明细行相差一个数量级以上，恰恰发生在读者最可能去把明细行加总的时刻。
 
 ## 决策
 
 `contextPressure` 发布第二个分子 `projectedTokens`：在提供方样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零。该折叠通过共享的 `surface-fold.ts` 携带已计价的表层，并在用量样本落地时记下 `sampledSurfaceTokens`——记录时机在同一条事件加入表层**之前**，因此 `assistant/message` 锚定的正是它自己那次请求实际携带的表层。`stateVersion` 提升到 3。
 
-只有增量部分是估算的。锚点保持提供方精确值，从而把估算器对 CJK 文本与 JSON schema 的系统性低估挡在占用率数字之外，同时又让这个数字能在内容落地或某段区间被遮蔽的瞬间做出反应。`contextOccupancy` 读取 `projectedTokens`，并回退到裸样本，因此从不含该字段的检查点恢复出来的投影会退化为旧行为，而不是直接消失。
+只有增量部分是估算的。锚点保持提供方精确值，从而把估算器对 CJK 文本与 JSON Schema 的系统性低估挡在占用率数字之外，同时又让这个数字能在内容落地或某段区间被遮蔽的瞬间做出反应。`contextOccupancy` 读取 `projectedTokens`，并回退到裸样本，因此从不含该字段的检查点恢复出来的投影会退化为旧行为，而不是直接消失。
 
 这推翻了[上下文仪表决策](../feature/2026-08-05-composer-context-meter-breakdown.md)中「圆环、标题与进度条总长保持提供方精确值」的那一半。那条决策真正想守住的东西——不要把启发式明细行按比例缩放到提供方总量、从而伪造精度——依然守住了：明细行仍未被缩放，标题仍不等于它们之和。改变的是这样一个认识：「提供方精确、但描述的是两次压缩之前那个请求」并不是更真实的数字。
 
@@ -35,12 +35,12 @@ AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messag
 
 ## 影响
 
-占用率现在随每个表层事件推进，而不再是每轮跳一次，因此一轮中产生工具结果时圆环会持续爬升，而不是等到轮次结束才跳变——压缩落地的瞬间它也会掉下来。代价是线路上多了投影帧：`contextPressure` 每个表层事件推一帧，也就是 `contextBreakdown` 本来就在跑的频率。
+占用率现在随每个表层事件推进，而不再是每个轮次跳一次，因此一个轮次中产生工具结果时圆环会持续爬升，而不是等到轮次结束才跳变——压缩落地的瞬间它也会掉下来。代价是线路上多了投影帧：`contextPressure` 每个表层事件推一帧，也就是 `contextBreakdown` 本来就在跑的频率。
 
 面板的组成明细行仍然加不出标题数字，但现在只剩一个能讲清楚的原因，而不是两个：明细行带着估算器的误差，标题的锚点不带。剩下的抓手是估算精度（在 `estimate.ts` 里做 CJK 感知加权），它不改动任何 seam。
 
-`sampledSurfaceTokens` 依赖一个前提：在某个步骤的请求与它的用量报告之间，不会有新内容加入表层。循环在 `buildRequest` 之前接纳 steering 与 context，在 `assistant/message` 之后才排空工具结果，因此该前提成立；即便将来不再成立，误差也被限制在一条消息以内，并在下一个样本处自行纠正。
+`sampledSurfaceTokens` 依赖一个前提：在某个步骤的请求与它的用量报告之间，不会有新内容加入表层。agent loop 在 `buildRequest` 之前接纳 steering（中途引导）与上下文，在 `assistant/message` 之后才排空工具结果，因此该前提成立；即便将来不再成立，误差也被限制在一条消息以内，并在下一个样本处自行纠正。
 
 ## 测试
 
-`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。
+`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了投影值在表层增长与一次压缩期间的延续更新（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
index 0050d26e51..712163f307 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md
 2026-08-05-turn-tail-actions-require-a-completed-turn.md: 44a890c955089096204a5b2a2833905c9ef9f7ed
-2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md: 58ca9b2519101cae12121cd74e13bdaa90ce23cb
+2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md: afd7fbe5a0cdd097c919fb3457dfed1771d5651b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
index 58ca9b2519..afd7fbe5a0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
@@ -14,7 +14,7 @@ assistant IconActions 此前只从已定稿的 transcript（文本记录）推
 
 `assistantActionsSeqs` 接收 `ConversationSnapshot.turnEnds`，只在事件窗口中存在该轮次 `turn/end` 时才授予该行。已完成轮次内部的归属不变，仍是其最后一条含内容文本的 assistant。仍在产出步骤的轮次不授予任何座位，因此其叙述不会挂载该行；轮次关闭时，座位在已定稿答案下方一次性出现。
 
-这与分支控件和运行时长标签使用的完成事实相同，因此同一行的三个部分现在口径一致。轮次是否完成读自持久的 `turn/end` 事件，而不是从 `running`、流式 partial 或在途工具调用推断，与[已完成轮次尾部决策](2026-08-02-message-fork-actions-require-completed-turn-tail.md)一致。任何 reason 类别都会关闭轮次，因此已中止轮次冻结的尾部保留其操作栏，而崩溃遗留的开放轮次会在加载时由日志修复补上 `turn/end`。
+这与分支控件和运行时长标签使用的完成事实相同，因此同一行的三个部分现在口径一致。轮次是否完成读自持久的 `turn/end` 事件，而不是从 `running`、流式 partial 或在途工具调用推断，与[已完成轮次尾部决策](2026-08-02-message-fork-actions-require-completed-turn-tail.md)一致。任何结束原因类别都会关闭轮次，因此已中止轮次冻结的尾部保留其操作栏，而崩溃遗留的开放轮次会在加载时由日志修复补上 `turn/end`。
 
 `hasContentText` 移入 `chat-flow.ts`，由 `AssistantMarkdown` 导入，使归属门控与挂载门控无法各自漂移。
 
@@ -24,8 +24,8 @@ assistant IconActions 此前只从已定稿的 transcript（文本记录）推
 
 **轮次进行中保留该行，只把控件置为不可用。** 不予采纳：轮次中间的叙述不是一个降级的答案，它根本不是答案。复制仍然会写入一句中间文本，该行在轮次结束时仍然要移动到真正的尾部。
 
-**让每个已定稿的内容节点长期保留该行。** 在此重新否决，理由与最初的决策相同：在每一步下重复复制、分支和时钟会打乱流程。它也解决不了本次报告的问题，因为分支控件只有落在尾部才有意义。
+**让每个已定稿的内容节点长期保留该行。** 在此重新否决，理由与最初的决策相同：在每一步下重复复制、分支和时钟会使流程显得杂乱。它也解决不了本次报告的问题，因为分支控件只有落在尾部才有意义。
 
 ## 后果
 
-运行中的轮次在触发它的用户气泡之下不再有任何消息操作栏，而此前每个已完成轮次仍保留各自的座位；座位在 `turn/end` 到达时一次性出现，此刻已定稿答案下方会多出一行 28px。`turn/end` 落在加载窗口之外的轮次不授予座位，而翻页不会造成这种情况，因为一个轮次的结束事件排在它自己的节点之后。`apps/web/tests/turn-tail-actions.e2e.ts` 通过组装后的应用钉住两种状态：`hang` sidecar 作用在第二次模型调用上，把一个首步先叙述再调用 bash 的轮次挂住，两份 golden 分别记录挂起中的流程和停止之后的流程。包级测试直接覆盖该推导以及运行中轮次的渲染结果。
+运行中的轮次在触发它的用户气泡之下不再有任何消息操作栏，而更早的每个已完成轮次仍保留各自的座位；座位在 `turn/end` 到达时一次性出现，此刻已定稿答案下方会多出一行 28px。`turn/end` 落在加载窗口之外的轮次不授予座位，而翻页不会造成这种情况，因为一个轮次的结束事件排在它自己的节点之后。`apps/web/tests/turn-tail-actions.e2e.ts` 通过组装后的应用钉住两种状态：`hang` sidecar 作用在第二次模型调用上，把一个首步先叙述再调用 bash 的轮次挂住，两份预期输出分别记录挂起中的流程和停止之后的流程。包级测试直接覆盖该推导以及运行中轮次的渲染结果。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml
index 7737670466..e82314c28b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md
 2026-08-05-workspace-blank-session-reuse-membership.md: 910a10e9ada1a835df7a38a04fb04c504b0921df
-2026-08-05-workspace-blank-session-reuse-membership.zh.md: 7e7aa899f73955b3d34a1eff3d9fedde097a17f0
+2026-08-05-workspace-blank-session-reuse-membership.zh.md: 0581b768679d78716c1bf70cfffec825c7281783
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md
index 7e7aa899f7..0581b76867 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md
@@ -1,16 +1,16 @@
-# Agent Note：工作区新建会话复用了 cwd 匹配但未入账的空白会话
+# Agent Note: 工作区新建会话复用了 cwd 匹配但未入账的空白会话
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-05-workspace-blank-session-reuse-membership.md) | 中文
 
 ## 问题
 
-在侧边栏某个工作区分组的 `+` 上创建会话时，有时会进入一个新会话，但侧边栏把它显示在「未分组」而不是点击的那个工作区下——「进入了新会话，但工作区没有被选中」。故障只出现在注册在 CLI 运行目录（即 `defaults.cwd = process.cwd()`，实际场景里就是 harness 检出目录本身）上的工作区，并且一旦该目录下存在 CLI 创建的空白会话就会出现。
+在侧边栏某个工作区分组的 `+` 上创建会话时，有时会进入一个新会话，但侧边栏把它显示在「未分组」而不是点击的那个工作区下——「进入了新会话，但工作区没有被选中」。故障只出现在注册在 CLI（命令行界面）运行目录（即 `defaults.cwd = process.cwd()`，实际场景里就是 harness 检出目录本身）上的工作区，并且一旦该目录下存在 CLI 创建的空白会话就会出现。
 
-根因：`connectWorkspace` 的空白会话复用扫描只按 `cwd` 相等匹配会话列表镜像。host 自己的成员规则要求**同时**满足：会话 id 在工作区账户（`sessionIds`）中，**且**会话 header 的规范化 cwd 等于工作区路径（[Workspace UI product flow](../feature/2026-07-25-workspace-ui-product-flow.md)）；只有 cwd 匹配而没有账户槽位的恰恰就是「未分组」的情形。复用扫描忽略了账户槽位，因此任何 cwd 匹配的**在线空白**会话都会被选中——包括 CLI/TUI/headless 入口在 host cwd 创建的 `main-session-*` 会话（`session.create({})` 回退到 `defaults.cwd`，从不挂到任何工作区）。当这样的会话在线且空白（尚无 `turn/start`）时，下一次在该路径注册的工作区上点击 `+` 就会复用它，导航打开的是一个任何分组表面都无法显示在该工作区下的会话。其他路径的工作区不受影响，因为那里不会积累未入账的空白会话；而 host-cwd 工作区每次 CLI 运行都会积累一个。
+根因：`connectWorkspace` 的空白会话复用扫描只按 `cwd` 相等匹配会话列表镜像。host 自己的成员规则要求**同时**满足：会话 id 在工作区账户（`sessionIds`）中，**且**会话 header 的规范化 cwd 等于工作区路径（[Workspace UI product flow](../feature/2026-07-25-workspace-ui-product-flow.md)）；只有 cwd 匹配而没有账户槽位的恰恰就是「未分组」的情形。复用扫描忽略了账户槽位，因此任何 cwd 匹配的**在线空白**会话都会被选中——包括 CLI/TUI/headless 入口在 host cwd 创建的 `main-session-*` 会话（`session.create({})` 回退到 `defaults.cwd`，从不挂到任何工作区）。当这样的会话在线且空白（尚无 `turn/start`）时，下一次在该路径注册的工作区上点击 `+` 就会复用它，导航打开的是一个任何分组界面都无法显示在该工作区下的会话。其他路径的工作区不受影响，因为那里不会积累未入账的空白会话；而 host-cwd 工作区每次 CLI 运行都会积累一个。
 
-## 决定
+## 决策
 
 复用扫描现在要求工作区成员关系：`blank` 且 `summary.cwd === workspace.path` 且 `workspace.sessionIds.includes(summary.id)` 且未归档。仅 cwd 匹配的情况落到 `session.create({ workspaceId })`，创建并挂接新会话，使工作区拥有它——这与流程中「不存在空白会话」时的既有分支完全相同。
 
@@ -18,12 +18,12 @@
 
 **收养游离会话而不是新建。** 让 `session.create({ workspaceId })` 挂接一个 cwd 匹配但未入账的空白会话。否决：静默地把 CLI 创建的会话挂到工作区上，越过了账户边界，令人意外；而且客户端没有成员视图就无法区分「游离会话」与「工作区自己的空白会话」——而成员视图本身就是本次修复。
 
-**复用时就地挂接，新增一条 wire 操作。** 需要在导航热路径上新增 `workspace.attachSession` RPC，并且会话仍会有一帧显示在「未分组」；没有产品需求值得新增这个表面。
+**复用时就地挂接，新增一条 wire 操作。** 需要在导航热路径上新增 `workspace.attachSession` RPC，并且会话仍会有一帧显示在「未分组」；没有产品需求值得新增这个接口。
 
 ## 后果
 
-游离空白会话仍显示在「未分组」（用户仍可手动打开），但不再被某个工作区的新建会话流程劫持。成员校验是复用扫描的新增条件，有一个可观察的镜像滞后边界：在会话镜像已新而工作区账户帧滞后的窗口里，工作区自己的成员空白会话可能因成员校验失败而错过复用，多创建一个空白——表现为该工作区下出现第二个「新会话」行，与旧故障形态（打开一个任何分组表面都无法显示的会话）不同。两个窗口都是瞬态的，按工作区的合并逻辑仍然防止并发创建互相竞争。无 host、wire 或持久化格式变更。
+游离空白会话仍显示在「未分组」（用户仍可手动打开），但不再被某个工作区的新建会话流程劫持。成员校验是复用扫描的新增条件，有一个可观察的镜像滞后边界：在会话镜像已是最新而工作区账户帧滞后的窗口里，工作区自己的成员空白会话可能因成员校验失败而错过复用，多创建一个空白——表现为该工作区下出现第二个「新会话」行，与旧故障形态（打开一个任何分组界面都无法显示的会话）不同。两个窗口都是瞬态的，按工作区的合并逻辑仍然防止并发创建互相竞争。无 host、wire 或持久化格式变更。
 
 ## 测试
 
-`packages/client/runtime/tests/workspaces-service.spec.ts` 覆盖四种结果：成员空白会话被复用（无 create RPC）；cwd 匹配但非成员的游离空白会话**不被**复用、改为创建全新入账会话（回归用例）；已归档空白会话不被复用；首次 prompt 被拒后成员空白会话仍可复用。完整客户端套件（`pnpm run test:gui`）保持绿色。
+`packages/client/runtime/tests/workspaces-service.spec.ts` 覆盖四种结果：成员空白会话被复用（无 create RPC）；cwd 匹配但非成员的游离空白会话**不被**复用、改为创建全新入账会话（回归用例）；已归档空白会话不被复用；首次提示词被拒后成员空白会话仍可复用。完整客户端套件（`pnpm run test:gui`）保持绿色。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index f4f105e124..3a9d189fb5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
 2026-08-06-api-key-format-validation.md: 2174cb466c6af72f15005ce1ba3dec8100de6f2f
-2026-08-06-api-key-format-validation.zh.md: f9b7d6518fedc42e5264c46beaa1a78619139c58
+2026-08-06-api-key-format-validation.zh.md: 540239c34637eb5940be105127f3367e0969acfa
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index f9b7d6518f..540239c346 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -4,9 +4,9 @@ Status: implemented
 
 [English](2026-08-06-api-key-format-validation.md) | 中文
 
-## Problem
+## 问题
 
-一个含有 HTTP header value 无法承载的字符的 API Key，曾被每一层配置界面接受，直到构造请求时才失败——离引发它的那个字段已经很远。
+一个含有 HTTP header value 无法承载的字符的 API Key，曾被每个配置入口接受，直到构造请求时才失败——离引发它的那个字段已经很远。
 
 把含 emoji、中文或全角标点的 Key 粘进 Web 模型设置页，保存会报成功。第一轮对话随即失败于 `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255`——其中的下标与码点是 UTF-16 内部细节，不附带任何可执行动作，却泄露了 Key 中某一个字符的码点。`llm-deepseek` 之所以产出这句，是因为 `fetch` 在 [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts) 的 `try` 内部构造 `Bearer` header，而那个 `catch` 把一切失败都标为 `TRANSPORT`；该标签又在 `DEFAULT_RETRYABLE_CODES` 之中，于是一个永久且确定的故障还会被重试三次。
 
@@ -14,7 +14,7 @@ Status: implemented
 
 空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`，于是三个空格构成的 Key 会被存下，随后以 `Bearer` 加若干空格去认证。两个适配器都不检查来自凭据或环境的 Key——而那正是 Models 页写入的路径，也就是用户真正走的路径。
 
-## Decision
+## 决策
 
 一条规则定义什么是合法 Key：**trim 之后非空，且每个字符都落在 `[\x21-\x7E]`**——可打印 ASCII，不含空格。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ### 不变量属于每一层，启发式属于人所在的那一层
 
-字符集规则是不变量。非 ASCII 字符对任何 provider 都**不可能**在 header value 中传输，因此在浏览器、在各个 resolver、在每一次凭据读取上执行它，是结构上的一致而非约定上的一致。
+字符集规则是不变量。非 ASCII 字符对任何提供方都**不可能**在 header value 中传输，因此在浏览器、在各个 resolver、在每一次凭据读取上执行它，是结构上的一致而非约定上的一致。
 
 形状规则是对人如何粘贴的猜测，因此**只在浏览器中运行**。`llm-pi-ai` 前面挂着 OpenAI、Anthropic 以及任意手工声明的网关，本仓库并不掌握它们的 Key 格式；若这条规则运行在 resolver 中，一个签发形如 `TENANT1=abc` 的网关会让用户被彻底锁死、无路可走——设置页拒绝它，手写的 `.env` 在读取时同样被拒。把启发式限制在粘贴动作发生的那一层，环境变量便始终是那条出路。
 
@@ -32,7 +32,7 @@ Status: implemented
 
 规则作用于*已提供*的值；至于究竟有没有提供，由各个调用方自行判断。
 
-**未点名凭据。** 省略 `apiKeyEnv` 的 pi-ai profile 可以在 harness 持有的凭据路径之外鉴权。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权，正是为了让 provider 原生的 ambient 发现继续工作；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权。`namesCredential` 承载这一区分；省略不是需要校验的值。
+**未点名凭据。** 省略 `apiKeyEnv` 的 pi-ai profile 可以在 harness 持有的凭据路径之外鉴权。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog 提供方自身的鉴权，正是为了让 provider 原生的 ambient 发现继续工作；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权。`namesCredential` 承载这一区分；省略不是需要校验的值。
 
 **Web UI 中留空的输入框。** 即便某个 provider 的 Key 已经存好，该输入框也是空着打开的——`keyStored` 的文案写的是「已配置——输入新值以替换」——所以留空意味着*保持已存储的值*。`ProviderEditor` 在草稿为空时完全跳过 `credentials.set`，这一点保持不变：留空绝不拦截提交，否则改一个 base URL 都得重新输一遍 Key。
 
@@ -42,15 +42,15 @@ Status: implemented
 
 ### 规则住在哪里
 
-`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费者而非一个预设消费者。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
+`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费方而非一个预设消费方。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
 
 两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 seam 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
 
 客户端无法引入其中任何一个：client 包只 reference client 包，因此 `packages/client/ui-models` 在自己的 `apiKey.ts` 中镜像这个断言并持有本地化文案，正如 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
 
-### 各个界面各做什么
+### 各处分别做什么
 
-| 界面 | 行为 |
+| 位置 | 行为 |
 |---|---|
 | `dsh-llm` | 拥有 `normalizeApiKey`、`assertUsableApiKey` 与 `INVALID_CREDENTIAL_CODE`，后者刻意不进 `DEFAULT_RETRYABLE_CODES`。 |
 | `llm-deepseek` `resolveApiKey` | 归一化凭据 seam 或环境返回的值，以 `INVALID_CREDENTIAL` 拒绝，消息指明模型设置页，绝不回显 Key。 |
@@ -58,11 +58,11 @@ Status: implemented
 | `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化，使非法 Key 成为凭据故障而非端点不可达。不带 Key 的探测保持未鉴权。 |
 | `ui-models` | 镜像字符集规则，加入形状启发式，在探测与 `credentials.set` 之前 trim `keyDraft`，并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作；只含空白的输入框则是字段级失败。提交**与端点探测**同时受拦截，因此被拒绝的密钥不会白花一次往返去换取字段上已经写明的答案；失败呈现在字段上，与既有的 `modelFailure` 模式一致。 |
 
-`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局，因此一处客户端改动覆盖两个 provider。`CustomProviderCard` 为手工声明的路由承载同一套判定。
+`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局，因此一处客户端改动覆盖两个提供方。`CustomProviderCard` 为手工声明的路由承载同一套判定。
 
 `credentials-local` 刻意不动。它存储各类凭据，而可打印 ASCII 是 HTTP header 的约束而非凭据存储的约束；它既有的、拒绝任何 dotenv 样式都无法表示的值的行为保持原样。
 
-## Alternatives considered
+## 曾考虑的替代方案
 
 **由 client 与 host 共享一个校验模块。** 被 source plane 布局否决：client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`，把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试，是此处的既定形态。
 
@@ -74,15 +74,15 @@ Status: implemented
 
 **让形状启发式也在 resolver 中运行。** 更对称，且能拦住直接写进 `.env` 的整行环境变量。因上文所述的锁死风险而否决：resolver 中的一次误判会让用户无路可走，浏览器中的一次误判则仍留有环境变量这条路。
 
-**在保存时探测 provider 以证明 Key 可用。** 它能关掉最初报告的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些 provider，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
+**在保存时探测 provider 以证明 Key 可用。** 它能关掉最初报告的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些提供方，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
 
-## Consequences
+## 后果
 
 格式错误的 Key 在持有它的那个字段上就被拒绝；格式错误的已存储 Key 以 `INVALID_CREDENTIAL` 失败，消息指明修复位置且不含 Key 的任何片段。由于该 code 位于 `DEFAULT_RETRYABLE_CODES` 之外，一个确定性的凭据故障不再被当作瞬时传输抖动重试三次。`llm-pi-ai` 的探测把非法 Key 报为凭据故障，而非端点不可达。
 
-形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知 provider 不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知提供方不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
 
-限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个 provider 签发 latin-1 的 Key，这条规则需要放宽。
+限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个提供方签发 latin-1 的 Key，这条规则需要放宽。
 
 字符集断言存在两份，每个 source plane 一份。布局禁止共享它；两侧各自带测试并在注释中指名其孪生体。
 
@@ -90,7 +90,7 @@ Status: implemented
 
 把这件事做错的最大代价，会是把「未指定」当成「非法」：一条施加到 `undefined` 上的规则会打断每一条依赖 ambient 发现或 OAuth 鉴权的路由，而一个会拦截提交的空输入框，则会让改动任何其他设置都必须重新输入 Key。这两点都由测试钉住，而不是仅仰赖谨慎。
 
-## Testing
+## 测试
 
 `packages/llm/llm/tests/api-key.spec.ts` 以整张输入表驱动 `normalizeApiKey` 与 `assertUsableApiKey`——空值、纯空白、带首尾空白、含中间空格、C0 控制字符、emoji、中文、全角、latin-1，以及可打印 ASCII 的边界字符——并钉住一次拒绝携带 `INVALID_CREDENTIAL` 且不含 Key 的任何部分。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
index a08d6323dd..378358d0cb 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
 2026-08-06-onboarding-step-owned-takeover-chrome.md: 4b3bbbc03c4494359297ae6e54bcc9a74c387e80
-2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 548285d285939325a26df3b8d70c43fe952813a9
+2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 88e27649d719c0ef7cd2b4604c507c40845a715d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
index 548285d285..88e27649d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：首次使用引导的接管界面框架移入步骤自身
+# Agent Note: 首次使用引导的接管界面框架移入步骤自身
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-06-onboarding-step-owned-takeover-chrome.md) | 中文
 
@@ -10,26 +10,26 @@
 
 于是每次在 hero（空白或无会话）状态下刷新页面，会话列表一变 `ready` 就弹出整屏不透明层——亮色主题下是白色——并阻断全部交互，时长恰好等于一次凭据/设置 RPC 往返；之后已配置好的步骤自我完成，图层消失。用户看到的就是每次刷新在 workspace/会话列表落地的瞬间闪一下白屏。
 
-## 决定
+## 决策
 
-接管界面框架属于步骤，不属于外壳。新增零 cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
+接管界面框架属于步骤，不属于外壳。新增零 Cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
 
-`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 契约现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
+`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 约定现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
 
 ## 曾考虑的替代方案
 
-**条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／销毁在两个包里都变成响应式接线。对本缺陷而言过重，否决。
+**条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／dispose（资源释放）在两个包里都变成响应式接线。对本缺陷而言过重，否决。
 
-**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的契约变更。
+**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的约定变更。
 
-**在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法据步骤的 `null` 分支；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
+**在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法根据步骤的 `null` 进行分支判断；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
 
 ## 后果
 
-步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前是在不透明图层背后被置灰）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
+步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前在不透明图层背后处于 inert 状态）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
 
-未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 契约的 JSDoc 已把包裹写为注册方的义务。
+未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 约定的 JSDoc 已把包裹写为注册方的义务。
 
 ## 测试
 
-`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳契约：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
+`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：包裹内容的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳约定：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8 ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
index de0b20d867..c80c9a5d8d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
 2026-08-06-provider-credential-lifecycle.md: c28788921e8f1b233b44e19b29ad4d4acaa25022
-2026-08-06-provider-credential-lifecycle.zh.md: 2ea3b21fb6ceb4fa38a0cad0daf47c3b6a98a664
+2026-08-06-provider-credential-lifecycle.zh.md: d11aee5c5f014315c016e77f157cbac2624f844c
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
index 2ea3b21fb6..d11aee5c5f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
@@ -10,18 +10,18 @@ Models 编辑器横跨互相独立的 settings 与凭据 RPC 领域。之前它
 
 ## 决策
 
-提供方保存仍在现有 wire 领域上按先 settings、后凭据的两阶段顺序执行，但卡片会把成功的 settings 响应视为提交检查点。它会在尝试 `credentials.set` 之前，用返回的脱敏 descriptor 替换比较基准子树与预期 revision；如果第二阶段失败，草稿密钥与卡片会继续显示，重试不会产生 settings op，只会再次写入凭据。首次 settings 提交之前发生的真实并发变更仍会以 `settings-conflict` 失败。UI 与 DeepSeek 直连 resolver 边界均会去除所输密钥的首尾空白，且只有标准化密钥非空时，pi-ai 才会记录派生引用；留空密钥会具化一个空的、不带引用的 profile，以便使用提供方原生凭据发现。
+提供方保存仍在现有 wire 领域上按先 settings、后凭据的两阶段顺序执行，但卡片会把成功的 settings 响应视为提交检查点。它会在尝试 `credentials.set` 之前，用返回的脱敏 descriptor 替换比较基准子树与预期 revision；如果第二阶段失败，草稿密钥与卡片会继续显示，重试不会产生 settings op，只会再次写入凭据。首次 settings 提交之前发生的真实并发变更仍会以 `settings-conflict` 失败。UI 与 DeepSeek 直连 resolver 边界均会去除所输密钥的首尾空白，且只有标准化密钥非空时，pi-ai 才会记录派生引用；留空密钥会生成一个空的、不带引用的 profile，以便使用提供方原生凭据发现。
 
 只有当联接所得的行识别出该页面派生的精确 `<ROUTE>_API_KEY` 引用，并将其报告为已配置且可写时，删除操作才会清除该凭据。它会先取消设置该凭据，再取消设置用户层 profile；如果 settings 阶段失败，该行及其已冻结的目标仍可见，便于重试。两项 unset 都具备幂等性。自定义引用、环境凭据、缺失的凭据，以及联接无法识别目标的凭据均会保留。行的无障碍 Edit/Delete 名称以及破坏性对话框的标题、说明和最终操作都使用同一个稳定的 `Display Name (route-id)` 标识；当两个字符串相同时，标识会简化为路由 id。对话框会说明是否一并删除已存密钥，并在自身内显示操作失败，而不是用加载错误横幅替换整个页面。行只根据不含值的联接结果展示 API 密钥状态：确认已配置的引用凭据显示为绿色实心点，确认缺失的具名引用显示为红色实心点，无引用的提供方原生认证或无法取得凭据补充信息时则不显示状态点。每个状态点都有无障碍文案和工具提示；「应用」成功后的本地状态消息会使用同一个提供方标识，且绝不回显任何机密内容。
 
 ## 曾考虑的替代方案
 
-**添加跨领域事务 RPC。**settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置契约。
+**添加跨领域事务 RPC。** settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置约定。
 
-**删除被移除 profile 所指定的每一个凭据引用。**自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
+**删除被移除 profile 所指定的每一个凭据引用。** 自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
 
-**先删除 settings，再重建 profile 以作补偿。**浏览器只持有脱敏后的子树，无法忠实重建并发编辑。先删除凭据可以让权威 profile 在部分失败时仍然可见，并且无需合成配置就能安全重试。
+**先删除 settings，再重建 profile 以作补偿。** 浏览器只持有脱敏后的子树，无法忠实重建并发编辑。先删除凭据可以让权威 profile 在部分失败时仍然可见，并且无需合成配置就能安全重试。
 
 ## 后果
 
-Models 页可以从任一第二阶段失败中恢复，无需重新加载，也不会泄露机密或产生虚假的并发冲突；空密钥的 pi-ai profile 会保留 Bedrock、Vertex 与其他提供方原生认证。已确认的状态清晰可见，同时不会把路由存活状态、原生认证或凭据查询失败误报为错误；即使该行继续显示绿色，密钥替换成功也仍然可观察。删除由页面管理的提供方不再遗留可重用的本地密钥，而存在歧义的凭据会有意保留，交由手动管理。保存与删除在跨持久存储时仍非原子操作：进程可能在两个阶段之间崩溃，但它们的顺序与幂等性会留下可观察、可重试的状态。组件测试固定了部分成功后的重试、空密钥原生认证、密钥首尾空白处理、状态可见性、目标标识、清理所有权，以及凭据／settings 拒绝顺序；无密钥的浏览器场景固定了双语无障碍文案，并验证确认删除会同时清除 `settings.yaml` profile 与 `.credentials.yaml` 条目。此决策细化了 [web 配置平面 note](../architecture/2026-07-30-web-config-plane.md) 中记录的 Models 应用语义。
+Models 页可以从任一第二阶段失败中恢复，无需重新加载，也不会泄露机密或产生虚假的并发冲突；空密钥的 pi-ai profile 会保留 Bedrock、Vertex 与其他提供方原生认证。已确认的状态清晰可见，同时不会把路由存活状态、原生认证或凭据查询失败误报为错误；即使该行继续显示绿色，密钥替换成功也仍然可观察。删除由页面管理的提供方不再遗留可重用的本地密钥，而存在歧义的凭据会有意保留，交由手动管理。保存与删除在跨持久存储时仍非原子操作：进程可能在两个阶段之间崩溃，但它们的顺序与幂等性会留下可观察、可重试的状态。组件测试固定了部分成功后的重试、空密钥原生认证、密钥首尾空白处理、状态可见性、目标标识、清理所有权，以及凭据／settings 拒绝顺序；无密钥的浏览器场景固定了双语无障碍文案，并验证确认删除会同时清除 `settings.yaml` profile 与 `.credentials.yaml` 条目。此决策细化了 [web 配置平面 Agent Note](../architecture/2026-07-30-web-config-plane.md) 中记录的 Models 应用语义。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
index 1c861833cf..2982e05c65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
 2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
-2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: ffb03fdb68c9cb040e311077dd698b310a033fdd
+2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: 7a1142cdd793cfce46bfd3908ab28345701aec7a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
index ffb03fdb68..7a1142cdd7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
@@ -12,13 +12,13 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 读者输入不再依据设备来识别。ChatView 维护一份 observed-top ledger（`observedTopRef`）：即最近一次由主线程交付、或由组件自身写入的 `scrollTop`，并在每一个程序化写入点（贴底跟随、打开时恢复、前置锚定、尺寸变化跟随以及滚动交付本身）同步记录。滚动事件到达时，偏离 `min(ledger, floor)` 超过半像素的位置即为读者输入；落在 ledger 上的位置（迟到的程序化交付），或恰好落在收缩后底部上的位置（内容收缩后的浏览器钳制），则维持当前的所有权状态。此后所有权只经由读者输入、按既有阈值规则变化：位置距底部在 `FOLLOW_THRESHOLD` 以内则重新贴底，超出则释放跟随并显示「回到底部」。滚轮监听器及其 epoch 簿记已删除；组件只监听 `scroll`，因此滚轮、触控、滚动条、键盘以及未来任何输入来源都由同一条规则覆盖。
 
-## 契约变更：收缩与重新增长被合并的钳制
+## 约定变更：收缩与重新增长被合并的钳制
 
-如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试契约已在同一变更中改写为只吸收纯收缩的保证。
+如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试约定已在同一变更中改写为只吸收纯收缩的保证。
 
 ## 测试
 
-`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 契约：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
+`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 约定：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
 
 该车道的 Chromium 无法合成任何非滚轮的设备滚动，这限定了 e2e 能真实驱动的范围：触控来源的 `Input.synthesizeScrollGesture` 与手工构造的 `Input.dispatchTouchEvent` 序列都能交付 DOM 事件，却从不移动滚动容器（无头模式与 Xvfb 下的有头模式皆然）；`default` 手势来源合成的是滚轮事件；合成器滚动条则完全无视合成的鼠标输入，且只有移除 `--hide-scrollbars` 后才能看到滚动条槽。键盘是唯一可用的非滚轮原语，因此由它承担真实输入流水线的证明；快滑场景则把触控的特征（组件从未写入过的逐帧衰减位移）直接回放进滚动容器。
 
@@ -34,4 +34,4 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 ## 后果
 
-每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的契约变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言契约的前提下，把快滑模拟替换为真实的触控划动。
+每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的约定变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言约定的前提下，把快滑模拟替换为真实的触控划动。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
index bb344c5afe..d6caa87acb 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.md
 2026-08-06-token-surface-unpriced-replace-compatibility.md: 77b778fba695f560eb68af6da2f416e61ccff181
-2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: dd4c5883c4c6d37809c2f8100f266655d8ba600c
+2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: 1a18551b1e0c1e7e78f32d69caec1d0956a4075d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
index dd4c5883c4..1a18551b1e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
@@ -8,19 +8,19 @@ Status: implemented
 
 `contextPressure` 与 `contextBreakdown` 两个投影只维护一份滚动累计的表层 token 总量，外加至多一条待结算的影子价格（shadow price）声明，因此其持久化检查点在会话整个生命周期内保持 O(1)。当前的替换生产方会紧贴在替换之前追加一条 `compact/summary` 或 `compact/prune` 计量事件；其 `shadowedTokenCount` 对被替换区间精确计价，`foldSurfaceProjection` 再把它换算成有符号增量。
 
-影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作契约违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
+影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作约定违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
 
 ## 决策
 
 到达时没有已就位声明的替换以价格中性的方式折叠：`foldSurfaceProjection` 返回 `deltaTokens: 0`，相当于把被替换区间计价为恰好等于其替换内容的成本，回放随即继续。因中间插入的事件而过期的声明也走同一条中性路径，因为折叠无法把它与从未计量过的日志区分开。
 
-已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格契约的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
+已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格约定的违规，不是历史数据，必须明确报错，而不能任由总量悄然漂移。
 
 两个投影共用同一个折叠，因此二者都不新增状态字段，也不提升 `stateVersion`。`surface-fold.ts` 与 `ctx.tokenMeter.measure()` 不受影响：它们持有逐节点的已计价表层，本来就不需要声明协议。
 
 ## 备选方案
 
-**维持抛出异常。**保住了严格的生产方契约，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
+**维持抛出异常。**保住了严格的生产方约定，但协议之前的每个会话都将永远无法回放，而投影本就是为回放服务的。
 
 **在投影状态中持久化完整的已计价表层。**可以对任意被替换区间精确计价，但检查点会随每条模型可见消息各增加一个节点、无上限地增长，恰恰破坏了影子价格协议所要守住的 O(1) 约束（见[上下文仪表的 Agent Note](2026-08-05-context-meter-blind-to-compaction.md)）。
 
@@ -28,7 +28,7 @@ Status: implemented
 
 未计价的替换让总量保持不动而不是缩小，因此被压缩（compaction）掉的区段仍被计入：`contextBreakdown.messageTokens` 保留这部分多计的量；`contextPressure.projectedTokens` 会高估占用率，但只持续到下一个用量样本重新锚定为止，因为该数字追踪的是自样本以来的增减，而非绝对水平。误差方向是安全的：高估占用率最坏不过是招致一次更早的压缩。
 
-响亮失败保留在它仍有意义的地方：区间不匹配的相邻声明是现行生产方的缺陷，仍会抛出异常。
+明确报错机制仍保留在有意义的场景中：区间不匹配的相邻声明是现行生产方的缺陷，仍会抛出异常。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index 1884c12c93..45dc5edb5c 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
 2026-06-21-subagent-capability-seam.md: 752e639b09ea2ac0ba19841ddfe38b15b44d22e9
-2026-06-21-subagent-capability-seam.zh.md: 6009aeda6773357a4217f8956fb510c2116bbe3f
+2026-06-21-subagent-capability-seam.zh.md: f0b0ba2ab8b0bb7b611e995c56e30db68b21cfa7
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 6009aeda67..f0b0ba2ab8 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -1,37 +1,37 @@
-# Agent Note: Subagent 能力 seam
+# Agent Note: subagent 能力 seam
 
 Status: implemented
 
 [English](2026-06-21-subagent-capability-seam.md) | 中文
 
-> 完整 seam 已交付：`dsh-subagent` 接口与 `dsh-tool-subagent` 消费方；两个进程内后端（`dsh-subagent-spawn`、`dsh-subagent-fork`）；嵌套 agent 快照基础设施（[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)）；以及进程外的 ACP、Codex 与 Claude Code 后端（[ACP Agent Note](2026-06-22-acp-subagent-backend.md)、[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）。
+> 完整 seam 已交付：`dsh-subagent` 接口与 `dsh-tool-subagent` 消费方；两个进程内后端（`dsh-subagent-spawn`、`dsh-subagent-fork`）；嵌套 agent（智能体）快照基础设施（[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)）；以及进程外的 ACP（Agent Client Protocol）、Codex 与 Claude Code 后端（[ACP Agent Note](2026-06-22-acp-subagent-backend.md)、[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）。
 
 ## 问题
 
-harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent（智能体）将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。本 Agent Note 实现了这个 seam；上方横幅列出了已交付的内容。
+harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。本 Agent Note 实现了这个 seam；上方横幅列出了已交付的内容。
 
-决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP（Agent Client Protocol））。我们预见的传输方式：
+决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP）。我们预见的传输方式：
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
-- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性兄弟提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
+- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性同类提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
 - 后续：**A2A**，采用同样的进程外形态：「启动子 agent、发送提示词、结算、取消」。
 
 ## 曾考虑的替代方案
 
 ### 为何不采用 bash seam 的形状
 
-bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口 / 实现 / 消费方）；只是「一个 vs. 多个实现」这个维度不同。
+bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口、实现、消费方）；只是「一个 vs. 多个实现」这个维度不同。
 
 ## 决策
 
 ### 由三个包构成的 seam
 
-新建包（package）组 `packages/subagent/`：
+新建包组 `packages/subagent/`：
 
 | 包 | 角色 |
 |---|---|
-| `@deepseek-ai/dsh-subagent` | 接口：`SubagentService`（`ctx.subagents`）、`SubagentProvider`、`SubagentRun`、请求/结果/能力词汇、`subagent/*` 事件 |
+| `@deepseek-ai/dsh-subagent` | 接口：`SubagentService`（`ctx.subagents`）、`SubagentProvider`、`SubagentRun`、请求、结果、能力词汇、`subagent/*` 事件 |
 | `@deepseek-ai/dsh-subagent-spawn` | 实现：通过 `ctx.agents.create` 创建全新的进程内子 agent |
 | `@deepseek-ai/dsh-subagent-fork` | 实现：用父 agent 日志快照初始化的进程内子 agent |
 | `@deepseek-ai/dsh-subagent-acp` | 实现：作为 ACP 客户端驱动已配置的子进程 |
@@ -45,8 +45,8 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 两类可选能力，两种发现方式
 
-- **启动时功能**（`outputSchema`、`depthLimit`、`toolFilter`、`persona`）挂在静态的 `provider.capabilities` 描述符上。服务在委派之前检查每个被请求的功能，如果提供方不支持则**大声拒绝**（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不接受后静默忽略。这些功能必须在 run 存在之前检查，因此不能是运行时方法。
-- **可继续创建**使用可选的 `SubagentProvider.prepareContinuable` 方法；方法是否存在本身即为能力，TypeScript 类型收窄即为发现机制，因此不需要可能与实现失同步的独立 flag。继续执行管理器直接通过 `AgentHandle` 负责后续投递与从持久化存储恢复，而一次性 `SubagentRun` 没有 steering 或 resume 操作，具体由[可继续 subagent](2026-07-28-continuable-subagent-conversations.md)细化。
+- **启动时功能**（`outputSchema`、`depthLimit`、`toolFilter`、`persona`）挂在静态的 `provider.capabilities` 描述符上。服务在委派之前检查每个被请求的功能，如果提供方不支持则**明确拒绝**（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不接受后静默忽略。这些功能必须在 run 存在之前检查，因此不能是运行时方法。
+- **可继续创建**使用可选的 `SubagentProvider.prepareContinuable` 方法；方法是否存在本身即为能力，TypeScript 类型收窄即为发现机制，因此不需要可能与实现失同步的独立 flag。继续执行管理器直接通过 `AgentHandle` 负责后续投递与冷恢复，而一次性 `SubagentRun` 没有 steering 或 resume 操作，具体由[可继续 subagent](2026-07-28-continuable-subagent-conversations.md) 细化。
 
 ### Fork 与 fresh 是独立后端，而非一个 flag
 
@@ -58,7 +58,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 同步收集（首版）
 
-`dsh-tool-subagent` 将其执行信号传给 `start()`，等待子 agent 结果，并在报告前 dispose 该 run。非完成态的结果变为错误结果，而非成功的部分输出；相互独立的结果与 dispose rejection 会保留两项 diagnostic。
+`dsh-tool-subagent` 将其执行信号传给 `start()`，等待子 agent 结果，并在报告前 dispose 该 run。非完成态的结果变为错误结果，而非成功的部分输出；结果与 dispose 的拒绝相互独立，且两项诊断信息都会保留。
 
 ### 提供方选择是配置，不面向模型
 
@@ -66,7 +66,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ## 测试
 
-注册表与工具测试仅用包内脚本化提供方替换非确定性的子进程边界，同时运行真实的 `SubagentService`、生命周期、任务集成和面向模型的工具。提供方与消费方的 export 形状仍保留 Loader 回归覆盖，以防止[事后分析 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的失败。注册表测试覆盖重载安全性、重名和启动时能力拒绝；嵌套 agent 场景通过[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)进行无密钥回放；进程内后端还有真实循环的单元测试和带密钥的 e2e 测试。
+注册表与工具测试仅用包内脚本化提供方替换非确定性的子进程边界，同时运行真实的 `SubagentService`、生命周期、任务集成和面向模型的工具。提供方与消费方的 export 形状仍保留 Loader 回归覆盖，以防止[事故复盘（postmortem）0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的失败。注册表测试覆盖重载安全性、重名和启动时能力拒绝；嵌套 agent 场景通过[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)进行无密钥回放；进程内后端还有真实循环的单元测试和带密钥的 e2e 测试。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index e0f79bacb0..5229a4b034 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-skill-system.md
 2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
-2026-07-05-skill-system.zh.md: 05bd880ecbd46f2b472eb2cc5442f11c07f89b4e
+2026-07-05-skill-system.zh.md: fe3cf200278c2dd5449e1442228419845593056b
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 05bd880ecb..fe3cf20027 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Skill 系统——面向 agent 的渐进式指令披露
+# Agent Note: skill 系统——面向 agent 的渐进式指令披露
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Agent（智能体）产品已趋同于一种 skill（技能）模式：保持请求提示词精简，仅列出可用的指令包，当模型判定某任务匹配时再加载完整正文。Codex、Claude Code、OpenCode 与 Kimi Code 在细节上各有不同，但都将发现元数据与完整指令分离，使工作区能承载可复用的行为而无需在每个轮次支付全量提示词开销。
+agent（智能体）产品已趋同于一种 skill（技能）模式：保持请求提示词精简，仅列出可用的指令包，当模型判定某任务匹配时再加载完整正文。Codex、Claude Code、OpenCode 与 Kimi Code 在细节上各有不同，但都将发现元数据与完整指令分离，使工作区能承载可复用的行为而无需在每个轮次支付全量提示词开销。
 
 DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和工具使用指南存放在工作区或用户的 agent 配置旁，而非硬编码到 agent loop（智能体循环）中。
 
@@ -16,31 +16,31 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 专用的随包提供方可以贡献不可变的 skill，无需文件系统发现。交付的 CLI（命令行界面）默认将 `@deepseek-ai/dsh-skill-badge` 声明为禁用；启用其组合配置行，就会通过同一个注册表和消费方贡献官方徽章指令（见[决策](2026-08-06-bundled-dsh-badge-skill.md)）。
 
-提供方插件在 `apply()` 期间同步注册。提供方成员资格是由直接 effect 持有的状态：注册与 dispose（资源释放）同步地使已完成的目录失效，发现操作按需读取当前提供方映射而非监听注册表变更事件。提供方目录从等待的 `list()` 调用返回排序后的候选项，远程提供方在此过程中执行初始化、认证和发现，同时遵守查找的 abort 信号。注册表校验每个候选项，按排名、提供方注册顺序和提供方内部顺序以先到先得方式解决同名 skill 冲突，然后按 skill 名称排序摘要以保证消费方获得确定性结果。它仅缓存已完成的目录快照，并在发现过程中提供方/运行时修订版本发生变化时重试，因此卸载操作不会将一个陈旧且不可解析的 skill 冻结到会话目录中。运行时 `ctx.skills.register(...)` 仍作为嵌入式进程内 skill 的便捷方式保留，使用 project 优先于 user 的优先级；`runtime` 保留为注册表拥有的提供方名称。
+提供方插件在 `apply()` 期间同步注册。提供方成员资格是由 effect 直接持有的状态：注册与 dispose（资源释放）同步地使已完成的目录失效，发现操作按需读取当前提供方映射而非监听注册表变更事件。提供方目录从等待的 `list()` 调用返回排序后的候选项，远程提供方在此过程中执行初始化、认证和发现，同时遵守查找的 abort 信号。注册表校验每个候选项，按排名、提供方注册顺序和提供方内部顺序以先到先得方式解决同名 skill 冲突，然后按 skill 名称排序摘要以保证消费方获得确定性结果。它仅缓存已完成的目录快照，并在发现过程中提供方/运行时修订版本发生变化时重试，因此卸载操作不会将一个陈旧且不可解析的 skill 冻结到会话目录中。运行时 `ctx.skills.register(...)` 仍作为嵌入式进程内 skill 的便捷方式保留，使用 project 优先于 user 的优先级；`runtime` 保留为注册表拥有的提供方名称。
 
 本地提供方按先到先得的排名顺序扫描 cwd 敏感的项目根目录、自定义根目录和用户根目录：项目 `.dsh`、项目 `.agents`、`customSkillDirs`、用户 `.dsh`，然后是用户 `.agents`。用户 `.dsh/skills` 扫描跳过 `.system`，以免系统拥有的目录被当作普通用户内容处理。本地提供方不会合成内置系统 skill；已配置的 bundled 根目录和专用提供方会提供额外 skill。
 
-每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包（package）解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包有限 frontmatter 需求已声明的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
+每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包已声明用于满足有限 frontmatter 需求的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
 
-本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方契约。
+本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方约定。
 
 `dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
+数据结构与目录/工具约定记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
 
 ## 曾考虑的替代方案
 
 **将完整 skill 正文注入每条系统提示词。** 否决，因为这破坏了渐进式披露，使每个请求都为可能不适用的指令付出代价。
 
-**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；面向人类的命令广播不改变发现机制。
+**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；面向人类的命令展示不改变发现机制。
 
-**将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现拥有加载。
+**将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现负责加载。
 
 **使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条 user-role `<system-reminder>` 消息。[仅请求的会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）是最初的机制；统一带来源消息的决策移除该 seam 后，目录改为具有相同消息形状的持久化带来源注入。
 
-**在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不应在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
+**在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不会在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
 
 **递归发现嵌套的 `**/SKILL.md`。** 否决。扁平文件和一级目录包覆盖了配置的根目录，同时使重复处理和目录顺序易于推理。
 
@@ -48,10 +48,10 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 ## 后果
 
-agent-core 主干包含一个目录贡献者、一个本地提供方和一个面向模型的工具。Skill 发现是 cwd 敏感的，因此以不同会话 cwd 值创建 agent 的调用方可以按设计观察到不同的项目 skill 覆盖。
+agent-core 主干包含一个目录贡献者、一个本地提供方和一个面向模型的工具。skill 发现是 cwd 敏感的，因此以不同会话 cwd 值创建 agent 的调用方可以按设计观察到不同的项目 skill 覆盖。
 
 目录对于固定的根目录集合和运行时注册修订版本是确定性的。本地提供方会监视已配置的根目录，并在发生相关磁盘变化后使已完成的目录失效；运行时注册和提供方释放也会使其失效。
 
 ## 延后
 
-Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的契约范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
+fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的约定范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不强制执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
index d50b2323e3..0669efd1f4 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
 2026-07-08-background-subagent-tasks.md: 679c57c3173a32b8cfccc6611b4ba74487e7f7e3
-2026-07-08-background-subagent-tasks.zh.md: 487943ab5cfe78226cde912854099fc56a5833a6
+2026-07-08-background-subagent-tasks.zh.md: ebfbb85add2f73d62b680407a6277c71f01f318e
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
index 487943ab5c..ebfbb85add 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 [subagent seam](2026-06-21-subagent-capability-seam.md) 会返回 `SubagentRun`，但原先面向模型的工具会同步收集每一次运行。因此，各自独立的慢速委派要么一直占用父调用，要么按串行方式运行。
 
-subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者资源释放契约。
+subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者 dispose（资源释放）约定。
 
 ## 决策
 
@@ -16,7 +16,7 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 后台 subagent 使用[通用后台任务运行时](../architecture/2026-06-20-generic-long-running-tool-runtime.md)。`task_output`、`task_list` 和 `task_kill` 负责收集、列出、取消、完成通知和提示词引导；系统不提供 subagent 专用的配套工具。
 
-前台调用保留其同步契约：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
+前台调用保留其同步约定：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前对该运行执行 dispose。
 
 对于后台调用，工具会验证父级，并在调用 `ctx.tasks.start()` 前拒绝已中止的执行信号。任务运行时会在调用生产者启动器前，预检控制接口和拥有者清理。该启动器创建独立的 `AbortController` 并启动 `ctx.subagents.start()`；返回 id 之后，工具调用的信号不再拥有该子级。
 
@@ -24,14 +24,14 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 - `kind` 为 `subagent`，`label` 为模型提供的描述，`owner` 为父 agent（智能体）。
 - `cancel(reason?)` 中止任务自有的控制器。同一个信号同时覆盖尚未完成的提供方启动和已发布 run 的剩余工作。
-- `done` 等待提供方启动、子级结果和 `run.dispose()`。已完成的运行返回最终文本，已中止的运行变为 `killed`，其他停止原因变为 `failed`。启动、结果和资源释放失败会转换为失败结果，而不是被拒绝的任务 Promise。
+- `done` 等待提供方启动、子级结果和 `run.dispose()`。已完成的运行返回最终文本，已中止的运行变为 `killed`，其他停止原因变为 `failed`。启动、结果和 dispose 失败会转换为失败结果，而不是被拒绝的任务 Promise。
 - `readOutput` 不存在。任务存活期间，`task_output` 只返回状态；结算后，它以幂等方式返回最终输出。中间的子级活动仍保留在子会话中。
 
 ## 生命周期
 
-后台 subagent 归属于其父 agent，不会在拥有者关闭后持久存续。任务运行时将清理附加到对应拥有者的确切作用域。agent 资源释放会取消任务，并在 `AgentHandle.dispose()` 完成前等待启动回滚或子级资源释放，避免泄漏子 agent 和会话。
+后台 subagent 归属于其父 agent，不会在拥有者关闭后持久存续。任务运行时将清理附加到对应拥有者的确切作用域。agent dispose 会取消任务，并在 `AgentHandle.dispose()` 完成前等待启动回滚或子级 dispose，避免泄漏子 agent 和会话。
 
-完成通知会发送给启动时捕获的确切拥有者。如果拥有者清理过程已经释放了注入目标，该通知将被丢弃；生命周期保证是清理，而不是通知。
+完成通知会发送给启动时捕获的确切拥有者。如果拥有者清理过程已经对注入目标执行了 dispose，该通知将被丢弃；生命周期保证是清理，而不是通知。
 
 ## 模型引导
 
@@ -51,14 +51,14 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 agent 和日志可能以会话为作用域，但任务注册表和可预测 id 属于运行时全局范围。因此，通用拥有者防线同样适用于 subagent 和所有其他生产者。
 
-### 增量子 transcript 输出
+### 增量子 transcript（文本记录）输出
 
 将子级历史以流式方式写入父级，会模糊日志边界，并使提供方行为分化。此接口只公开最终输出；更丰富的观察应由会话或 UI 工具承担。
 
 ## 测试
 
-单元测试覆盖固定了停止原因映射、在报告前释放资源、启动与结果失败、对预中止的拒绝、从启动调用信号分离、在提供方发布前后取消、通过真实任务工具收集、无控制接口的预检防线、运行时缺失失败，以及每实例 schema 开关。快照覆盖固定了面向模型的 schema。
+单元测试锁定了停止原因映射、在报告前释放资源、启动与结果失败、对预中止的拒绝、从启动调用信号分离、在提供方发布前后取消、通过真实任务工具收集、无控制接口的预检防线、运行时缺失失败，以及每实例 schema 开关。快照测试锁定了面向模型的 schema。
 
 ## 影响
 
-父级可以并行分派慢速委派任务，并通过与 bash 共用的任务控制来收集结果。子级工作不再占用启动它的工具调用，但在收集、终止或拥有者释放之前可以继续消耗资源。提示词引导鼓励收集；拥有者清理则提供硬性生命周期边界。需要同步委派的部署可以按工具实例禁用后台模式。
+父级可以并行分派慢速委派任务，并通过与 bash 共用的任务控制来收集结果。子级工作不再占用启动它的工具调用，但在收集、终止或拥有者 dispose 之前可以继续消耗资源。提示词引导鼓励收集；拥有者清理则提供硬性生命周期边界。需要同步委派的部署可以按工具实例禁用后台模式。
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 0cf926921b..e9e90f0c4f 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
 2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
-2026-07-20-dsh-cli-personal-config.zh.md: b33a7fa321ca04f41e47386544ffc0f268a8b1b6
+2026-07-20-dsh-cli-personal-config.zh.md: b2fbd4b68acd92496ca2b087b172504dd93abd88
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index b33a7fa321..b2fbd4b68a 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -4,29 +4,29 @@ Status: implemented
 
 [English](2026-07-20-dsh-cli-personal-config.md) | 中文
 
-## Problem
+## 问题
 
-开发者自己的偏好——TUI 使用哪个提供方和模型、个人凭证、私有的适配器路由——除了改动已提交的文件之外无处安放。要把 TUI 示例指向个人的 Anthropic 代理 Opus 路由，只能在工作区里改 `examples/tui-agent/cordis.yml` 和 `.env`，既有提交密钥的风险，又要在每个 checkout 里重复一遍。也没有可安装的命令：想在任意项目目录里运行这个 agent，必须回到仓库根目录调用示例脚本。Loader 元数据是静态的，所以「条件组合使用 overlay」（AGENTS.md）——但 overlay 此前只以已提交的同级文件形式存在，没有机器级的层。
+开发者自己的偏好——TUI 使用哪个提供方和模型、个人凭证、私有的适配器路由——除了改动已提交的文件之外无处安放。要把 TUI 示例指向个人的 Anthropic 代理 Opus 路由，只能在工作区里改 `examples/tui-agent/cordis.yml` 和 `.env`，既有提交密钥的风险，又要在每个 checkout 里重复一遍。也没有可安装的命令：想在任意项目目录里运行这个 agent（智能体），必须回到仓库根目录调用示例脚本。Loader 元数据是静态的，所以「条件组合使用 overlay」（AGENTS.md）——但 overlay 此前只以已提交的同级文件形式存在，没有机器级的层。
 
-## Decision
+## 决策
 
-下文的各入口模式，以及个人文件的名称与位置，已被 [profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)取代：`dsh` 启动 profile，个人层变成逐 profile 与 home 级的 `cordis.patch.yml`。保留不变的是本笔记的实质：以 Harness home 作为机器级层的根目录、在随附组合之上使用 patch 语义，以及解析时的大声失败。
+下文的各入口模式，以及个人文件的名称与位置，已被 [profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)取代：`dsh` 启动 profile，个人层变成逐 profile 与 home 级的 `cordis.patch.yml`。保留不变的是本笔记的实质：以 Harness home 作为机器级层的根目录、在随附组合之上使用 patch 语义，以及解析失败时明确报错。
 
-两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
+两个耦合的部分，与 `dsh web` PR（Pull Request）#443提出的 `apps/` 装配层对齐：
 
-**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该契约由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
+**`dsh` CLI（命令行界面，`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该约定由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
 
-**个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skills、AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
+**个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skill（技能）和 AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 
 - `.env`——在调用目录的 `.env` 之后加载；`process.loadEnvFile` 从不覆盖已有值，因此优先级为环境变量 > 项目 `.env` > 个人 `.env`。
 - `config.yaml`——顶层 YAML 数组，元素为 `@cordisjs/plugin-include` 的 `PatchOptions`，用 include 自己的 `!!js` 方言解析（`loadPersonalPatches`）并传给 `boot()`，由它作为根 include 的 `patches` 转发。补丁语义与交付的 surface overlay 一致：按 id 定位的补丁替换该配置项的整个 `config`，`insert` 追加配置项，未匹配的 id 静默不执行任何操作。[仓库插件集成](2026-07-30-config-only-repository-plugins.md)通过一个已交付配置项，使精确 GitHub 源列表成为纯配置选择。
-- 文件缺失即无 overlay；文件存在但不可读、不可解析或非数组则在启动时抛出（配置错误响亮失败，绝不静默跳过）。
+- 文件缺失即无 overlay；文件存在但不可读、不可解析或非数组则在启动时抛出（配置错误会明确导致启动失败，绝不静默跳过）。
 
-PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录，与它已有的 `DSH_AGENTS_HOME` 隔离方式完全一致，开发者真实的个人 overlay 不可能泄漏进 fixture；只有 dsh CLI 读取个人配置，因此其他测试启动器无需改动。
+PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录，与它已有的 `DSH_AGENTS_HOME` 隔离方式完全一致，开发者真实的个人 overlay 不可能泄漏进 fixture（测试前置数据）；只有 dsh CLI 读取个人配置，因此其他测试启动器无需改动。
 
-TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人配置路径。每次新增、变更或移除都会以事务方式通过启动器自己的组合闭包重新组合完整 patch 列表，因此新的个人 patch 落在启动时相同的层次位置。YAML 无效或 Loader 候选被拒时，最后一个可用树保持活动状态，并广播 `hmr/config-update-failed(filename, Error)`；无头界面只在启动时读取该文件。Include 在已提交配置文件刷新时也会重新应用其 patch（见[配置热重载韧性 Agent Note](../bug-fix/2026-07-20-config-hot-reload-resilience.md)）。
+TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人配置路径。每次新增、变更或移除都会以事务方式通过启动器自己的组合闭包重新组合完整 patch 列表，因此新的个人 patch 落在启动时相同的层次位置。YAML 无效或 Loader 候选被拒时，最后一棵可用的配置树保持活动状态，并广播 `hmr/config-update-failed(filename, Error)`；无头界面只在启动时读取该文件。Include 在已提交配置文件刷新时也会重新应用其 patch（见[配置热重载韧性 Agent Note](../bug-fix/2026-07-20-config-hot-reload-resilience.md)）。
 
-## Alternatives considered
+## 曾考虑的替代方案
 
 **另设一个 `bin/dsh` 包装脚本并由其占用 `dsh` 名称。** 否决，因为 `apps/cli` 是统一的产品 CLI，负责分发默认 TUI、无头和 Web 界面。两个相互竞争的入口会在 `$PATH` 和产品身份上冲突。
 
@@ -34,11 +34,11 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 **个人完整 `cordis.yml` 去 include 请求的配置。** 否决：个人文件将不得不写死叶子配置的路径，而该路径随 checkout 变化；补丁反转了依赖方向，bin 仍然选择配置树，个人层只做修正。
 
-**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文契约。
+**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文约定。
 
-**用环境变量开关代替存在性判断。** 否决：默认关闭的个人配置永远不会被用起来；存在即生效加上每个测试的显式隔离，让实际运行获得 overlay、测试获得封闭性。
+**用环境变量开关代替存在性判断。** 否决：默认关闭的个人配置永远不会被用起来；存在即生效加上每个测试的显式隔离，让实际运行获得 overlay、测试保持隔离。
 
-## Consequences
+## 后果
 
 - 在任意目录运行 `dsh`（以及 `pnpm run demo:tui`），无需修改 checkout，即可应用个人提供方、模型、仓库插件和其他 Loader 配置项；已针对个人 Anthropic 代理与 Opus 4.8 端到端验证，包括一次 bash 工具往返。
 - 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](../../../../apps/cli/README.md#profiles)（打印这些补丁合成出的配置树）。
@@ -46,6 +46,6 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 - `dsh-app-boot` 依赖 `js-yaml`，并直接导入 include 的 `!!js` YAML 方言（`entryListSchema`）；与 `apps/cli` 一样依赖 `@deepseek-ai/dsh-paths` 以获取 `resolveDshHome`。
 - 只有长时间运行的 TUI 和 Web 进程进行实时监视。无头自动化使用确定性的启动配置，退出时不会保留 watcher。
 
-## Testing
+## 测试
 
-`packages/boot/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
+`packages/boot/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增、失败、恢复、移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 1d93b7f440..98d84c8e19 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
 2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
-2026-07-21-continuable-background-subagents.zh.md: 799e1914bdeb571dc697652081be6b0170768655
+2026-07-21-continuable-background-subagents.zh.md: 33bf9a1b7e4568ba0e4b2ea99ac590df9440c93f
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index 799e1914bd..33bf9a1b7e 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-21-continuable-background-subagents.md) | 中文
 
-本记录已由[可继续的 subagent](2026-07-28-continuable-subagent-conversations.md)取代——后者以一个持久 Session 加至多一个进程内 Activation（驻留期）替换了其基于 Task 的 activation 模型、路由、取消和持久性语义。其服务放置与提供方功能策略此前已由[将 subagent 控制合并到 subagent 服务](../simplification/2026-07-26-merge-subagent-control-service.md)和[以意图命名的 subagent 继续执行操作](../simplification/2026-07-27-intent-named-subagent-continuation-operations.md)取代。仅持久 child 会话与 descriptor 的设计依据仍然有效。
+本记录已由[可继续的 subagent](2026-07-28-continuable-subagent-conversations.md)取代——后者以一个持久会话加至多一个进程内 Activation（激活）替换了其基于 Task 的 activation 模型、路由、取消和持久性语义。其服务放置与提供方能力策略此前已由[将 subagent 控制合并到 subagent 服务](../simplification/2026-07-26-merge-subagent-control-service.md)和[以意图命名的 subagent 继续执行操作](../simplification/2026-07-27-intent-named-subagent-continuation-operations.md)取代。仅持久 child 会话与 descriptor 的设计依据仍然有效。
 
 ## 问题
 
@@ -14,9 +14,9 @@ Task、run 和 child 会话具有不同的生命周期。一个 Task 表示一
 
 ## 决策
 
-一个可继续的后台 subagent，是由一系列 Task 支撑的短期激活共同组成的持久化 child 会话。child session id、transcript（文本记录）、谱系及声明的组合配置均保留在持久化存储中。每次初始激活或恢复激活都会创建新的 Task、`AgentHandle` 和 `SubagentRun`，驱动一个轮次、收集结果，并在 Task 进入终态前 dispose 该 run。
+一个可继续的后台 subagent，是由一系列 Task 支撑的激活共同组成的持久化 child 会话。child 会话 id、transcript（文本记录）、谱系及声明的组合配置均保留在持久化存储中。每次初始激活或恢复激活都会创建新的 Task、`AgentHandle` 和 `SubagentRun`，驱动一个轮次、收集结果，并在 Task 进入终态前 dispose 该 run。
 
-Task 的结果和取消边界属于 child 激活，不属于为该激活提供第一条消息的调用方。Task 访问根据 parent session id 授权，而 Task 注册表仍保留当前存活的精确 parent Agent 实例，用于通知与资源清理。因此，只要 parent 仍是运行时 owner，parent 消息和用户消息便会共享同一个激活结果：
+Task 的结果和取消边界属于 child 激活，不属于为该激活提供第一条消息的调用方。Task 访问根据 parent 会话 id 授权，而 Task 注册表仍保留当前存活的精确 parent Agent 实例，用于通知与资源清理。因此，只要 parent 仍是运行时 owner，parent 消息和用户消息便会共享同一个激活结果：
 
 ```text
 durable child Session
@@ -25,35 +25,35 @@ durable child Session
   activation 3: Task 3 -> SubagentRun -> AgentHandle -> dispose
 ```
 
-前台委派保持一次性行为。继续执行覆盖后台的进程内 spawn 和 fork child。每个 `tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`；配置为可继续模式时，所挂载提供方必须具备 `resume` 功能，而可恢复的提供方仍可采用一次性后台策略。在下述 ACP（Agent Client Protocol）后续工作完成前，ACP child 仍保持一次性行为。
+前台委派保持一次性行为。继续执行覆盖后台的进程内 spawn 和 fork child。每个 `tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`；配置为可继续模式时，所挂载提供方必须具备 `resume` 能力，而可恢复的提供方仍可采用一次性后台策略。在下述 ACP（Agent Client Protocol）后续工作完成前，ACP child 仍保持一次性行为。
 
-`ctx.subagents` 是唯一的公开服务。普通 `start` 不感知 child 集合、Activation 与持久化：它校验提供方功能、解析一次性描述符、分发一个 run、观察 run 生命周期，并返回由持有方负责的 run。注入的内部继续执行管理器负责管理稳定的 child id、可继续描述符持久化与查找、Activation 生命周期，以及通过 `startContinuable` 和 `followup` 进行的路由；管理器自行组合 child 之前，提供方通过私有闭包提供准备数据。按提供方绑定的 `@deepseek-ai/dsh-tool-subagent` 插件及面向用户的适配器调用这些意图操作来处理可继续后台工作；前台和一次性后台委派使用普通 `start`。全局命名的模型工具是 `@deepseek-ai/dsh-tool-subagent-control` 中的可选轻量适配器，它是否存在不会决定是否启动可继续工作。parent 到 child 的枚举、一次性／可继续模式共享的描述符身份与 `list_agents` 属于[持久化 subagent 目录](2026-07-22-durable-subagent-catalog-and-list-agents.md)。
+`ctx.subagents` 是唯一的公开服务。普通 `start` 不感知 child 集合、Activation 与持久化：它校验提供方能力、解析一次性描述符、分发一个 run、观察 run 生命周期，并返回由持有方负责的 run。注入的内部继续执行管理器负责管理稳定的 child id、可继续描述符持久化与查找、Activation 生命周期，以及通过 `startContinuable` 和 `followup` 进行的路由；管理器自行组合 child 之前，提供方通过私有闭包提供准备数据。按提供方绑定的 `@deepseek-ai/dsh-tool-subagent` 插件及面向用户的适配器调用这些意图操作来处理可继续后台工作；前台和一次性后台委派使用普通 `start`。全局命名的模型工具是 `@deepseek-ai/dsh-tool-subagent-control` 中的可选轻量适配器，它是否存在不会决定是否启动可继续工作。parent 到 child 的枚举、一次性／可继续模式共享的描述符身份与 `list_agents` 属于[持久化 subagent 目录](2026-07-22-durable-subagent-catalog-and-list-agents.md)。
 
 ### Task 与取消的所有权
 
 初始后台委派请求 `ctx.subagents` 启动 child 并注册其 Task。可继续提供方只有在确认本次激活的最终会话状态已持久化后，才会返回成功的 run 结果。Task 结算流程等待该结果，通过继续执行管理器的结算路径调用 `run.dispose()`，然后才记录 `TaskOutcome`；`task_kill` 中止活跃 run，其结算路径仍会 dispose 该 run。因此，终态 Task 会留下持久化 child 会话，但不会留下存活的 child agent。必需的持久性检查点若没有已安装的监听器或任一监听器失败，run 会以稳定错误码 `DURABILITY_FAILED` 拒绝，并将检查点失败保留为失败原因；管理器会记录失败的 Task，其详情说明最新状态未确认已持久化，因此恢复时可能不可用或已陈旧。
 
-后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 契约，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
+后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 约定，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
 
 用户界面适配器打开 child 会话时，只读取持久化 transcript，不会仅为展示而恢复 agent。用户输入通过继续执行管理器，启动或加入与 parent 输入相同的 Task 激活。由用户启动的 Task 会保留当前加载的精确 parent Agent 作为通知目标，`task_output` 仍是唯一结果路径。只要 Task 尚未标记为已报告，现有完成监听器最多注入一条主动通知；`kill`、终态读取或终态等待都可能将其标记为已报告，并抑制这条通知。因此，仅允许在该 parent 实例保持存活时进行用户交互。可以比 parent 存活更久、并将结论显式合并回去的用户自有会话属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)，不属于这一由 Task 持有的生命周期。
 
 如果没有附加 Task 控制面，`TaskService.start()` 会拒绝 producer。因此，接受 child 输入的用户界面适配器必须附加 Task 控制面，或运行于加载了 `@deepseek-ai/dsh-tool-tasks` 的部署中；仅加载 Task 服务并不足够。SDK 生成的 spawn 与 fork 组合在挂载 subagent 工具时，也会挂载 `@deepseek-ai/dsh-tasks-local` 与 `@deepseek-ai/dsh-tool-tasks`。这项依赖是 parent 和用户启动的激活共用 Task 结果、取消和通知路径所付出的代价。
 
-取消始终作用于当前完整激活。如果用户消息和 parent 消息已经加入同一个轮次，任一调用方发起取消都会中止该轮次、dispose 其 run，并将对应 Task 结算为 `killed`；这些消息没有独立的结果或取消权。`followup()` 要求调用方提供信号；若在线 steering 正在等待请求准入时该信号被中止，激活自有的 controller 会被中止，以便提供方丢弃待处理消息，并且该调用仅在子 agent 完全停稳后结算。若需要独立取消，后续消息必须另起轮次，而不能加入当前轮次。
+取消始终作用于当前完整激活。如果用户消息和 parent 消息已经加入同一个轮次，任一调用方发起取消都会中止该轮次、dispose 其 run，并将对应 Task 结算为 `killed`；这些消息没有独立的结果或取消权。`followup()` 要求调用方提供信号；若在线 steering（中途引导）正在等待请求准入时该信号被中止，激活自有的 controller 会被中止，以便提供方丢弃待处理消息，并且该调用仅在子 agent 完全停稳后结算。若需要独立取消，后续消息必须另起轮次，而不能加入当前轮次。
 
 从持久化存储恢复的 Task 会在查找描述符或等待任何提供方操作之前，创建由本次激活持有的 `AbortController`；描述符查找、直接 parent 鉴权和描述符归并都在该 Task producer 内部执行，因此同一信号覆盖它们，其失败会将该 Task 结算为 `failed`。对于不接受信号的持久化调用，可以让底层 I/O 执行完毕；但继续执行管理器必须在每次这类 await 返回后重新检查取消状态，如已取消，之后不得开始或发布任何 child 工作。在 Agent 发布前收到中止信号时，提供方必须先回滚其创建事务并达到完全停稳状态，然后才让恢复调用以拒绝结束。Agent 发布后，提供方必须消除创建期间移交取消信号时的竞态，在返回前将同一信号附加到存活 run；之后取消会停止 child 轮次。即使提供方的恢复调用尚未返回 `SubagentRun`，`task_kill` 与对确切 owner 实例的 dispose 仍通过这条路径生效。Task 结算会等待回滚或 run dispose 完成，只有在激活完全停稳后才记录 `killed`。
 
 ### 活跃 run 关联
 
-继续执行管理器在进程内维护 child session id 到当前 Task 的关联，并在提供方发布后将 run 填入该关联。它会在等待提供方 start 或 resume 之前安装 Task 关联，填入返回的 run，并且只在 run dispose 完成且 Task 终态发布后才移除该关联。该关联只用于让 parent 发送方和用户发送方找到同一次激活；它不是持久化 child 目录、公开的 `ManagedSubagent`、准入预留或 run 状态机。
+继续执行管理器在进程内维护 child 会话 id 到当前 Task 的关联，并在提供方发布后将 run 填入该关联。它会在等待提供方 start 或 resume 之前安装 Task 关联，填入返回的 run，并且只在 run dispose 完成且 Task 终态发布后才移除该关联。该关联只用于让 parent 发送方和用户发送方找到同一次激活；它不是持久化 child 目录、公开的 `ManagedSubagent`、准入预留或 run 状态机。
 
-对于可继续 child 的初始激活，继续执行管理器会在创建 Task 前分配稳定的 child session id，并将其作为 `SubagentProviderStartRequest.continuation` 传递；进程内 spawn 和 fork 会发布这一确切 id，而不是在内部另行分配。普通 `SubagentStartRequest` 不含 continuation 字段。后台工具返回规范的 `{ kind: 'background', taskId, subagentId }`，渲染为 `started subagent <childId> as task <taskId>`。child id 在多次激活中始终指代同一个持久化对话，Task id 则只指代当前激活。初始 Task 失败，或进程在 child 首次 flush 之前退出，都可能留下一个 **unmaterialized child**：调用方持有 child id，但不存在持久化 header 和描述符。后续按 id 的操作会报告该 id 不可用（已启动的 Task 会带着该详情失败），持久化枚举也不会列出它。
+对于可继续 child 的初始激活，继续执行管理器会在创建 Task 前分配稳定的 child 会话 id，并将其作为 `SubagentProviderStartRequest.continuation` 传递；进程内 spawn 和 fork 会发布这一确切 id，而不是在内部另行分配。普通 `SubagentStartRequest` 不含 continuation 字段。后台工具返回规范的 `{ kind: 'background', taskId, subagentId }`，渲染为 `started subagent <childId> as task <taskId>`。child id 在多次激活中始终指代同一个持久化对话，Task id 则只指代当前激活。初始 Task 失败，或进程在 child 首次 flush 之前退出，都可能留下一个 **unmaterialized child**：调用方持有 child id，但不存在持久化 header 和描述符。后续按 id 的操作会报告该 id 不可用（已启动的 Task 会带着该详情失败），持久化枚举也不会列出它。
 
 每个可继续 child 轮次都通过这条由 Task 支撑的路径准入。非终态 Task 是唯一受支持的存活激活；不存在激活时，其 run 已被 dispose，持久化 child 可以恢复。在路由任何按 id 的操作之前，继续执行管理器会同步将自身关联与 `ctx.agents.get(childId)` 比较。如果注册表中的 Agent 没有关联，或者它与所关联的 `run.localAgent` 不同，就属于所有权冲突：管理器会失败，而不会接管 idle Agent 或附加未受跟踪的轮次。二者均不存在时，可以从持久化存储恢复；如果检查后又有竞争方发布，仍会在 Agent 注册表的冲突边界上失败。
 
-系统依据 Task 关联进行路由。运行中的 Task 通过 run 可选且提供确认语义的 `SubagentRun.steer` 功能接收在线消息。Task 不存在时，系统创建新 Task，并从持久化存储恢复 child。进程内 spawn 和 fork 会先同步要求 child 处于 `running` 状态，并拒绝已经提交结构化捕获的 child；随后调用 `Agent.steer()`，等待该消息专属的准入回执。默认循环会为每个 steering 项目提供一份归属于该消息的回执；只有在 `agent/step` 与异步提示词组装成功后，系统追加该消息、捕获不可变的请求历史并提交 `step/start`，回执才会解析为 `admitted`。终止型轮次策略、取消和 dispose（资源释放）会将待处理回执解析为 `rejected`。非终止型轮次关闭可以把待处理 steering 带入后续排队轮次，但不会确认其准入。提供方必须在调用 `Agent.steer()` 前检查存活状态，避免其 idle 路径在观察到的 run 之外启动轮次。如果查找关联之后、请求获准之前，Task 结算或终止策略率先完成，`steer()` 会拒绝，`send_message` 会报告消息未送达，而且该次调用不会改用从持久化存储恢复路径；在 Task 终态发布后重试，才可能启动下一次激活。
+系统依据 Task 关联进行路由。运行中的 Task 通过 run 可选且提供确认语义的 `SubagentRun.steer` 能力接收在线消息。Task 不存在时，系统创建新 Task，并从持久化存储恢复 child。进程内 spawn 和 fork 会先同步要求 child 处于 `running` 状态，并拒绝已经提交结构化捕获的 child；随后调用 `Agent.steer()`，等待该消息专属的准入回执。默认循环会为每个 steering 项目提供一份归属于该消息的回执；只有在 `agent/step` 与异步提示词组装成功后，系统追加该消息、捕获不可变的请求历史并提交 `step/start`，回执才会解析为 `admitted`。终止型轮次策略、取消和 dispose 会将待处理回执解析为 `rejected`。非终止型轮次关闭可以把待处理 steering 带入后续排队轮次，但不会确认其准入。提供方必须在调用 `Agent.steer()` 前检查存活状态，避免其 idle 路径在观察到的 run 之外启动轮次。如果查找关联之后、请求获准之前，Task 结算或终止策略率先完成，`steer()` 会拒绝，`send_message` 会报告消息未送达，而且该次调用不会改用从持久化存储恢复路径；在 Task 终态发布后重试，才可能启动下一次激活。
 
-继续执行管理器不会串行化两个通过其外部路径同时争抢已停止 child 的调用方，也不会为结果产生与 dispose 之间的阶段单独建立 settling 状态。在 producer 首次 await 之前同步安装的关联，使本进程内每个 child 只准入一次激活——resume 加载期间竞争的 `followup` 会观察到待处理的激活并显式失败——而绕开该关联的发布仍会在 Agent 注册表相同会话的冲突边界上失败。发送也可能因与启动、取消、完成或清理发生竞态而失败。这些限制是明确的，而非隐藏在更大的生命周期抽象之后。
+继续执行管理器不会串行化两个通过其外部路径同时争抢已停止 child 的调用方，也不会为结果产生与 dispose 之间的阶段单独建立 settling 状态。在 producer 首次 await 之前同步安装的关联，使本进程内每个 child 一次只准入一个激活——resume 加载期间竞争的 `followup` 会观察到待处理的激活并显式失败——而绕开该关联的发布仍会在 Agent 注册表相同会话的冲突边界上失败。发送也可能因与启动、取消、完成或清理发生竞态而失败。这些限制是明确的，而非隐藏在更大的生命周期抽象之后。
 
 ### 面向模型的 `send_message`
 
@@ -67,25 +67,25 @@ durable child Session
 
 发送到现有 run 的消息没有独立结果，其效果体现在当前 Task 的最终结果中。启动的后续轮次具有新 Task 的结果，并使用现有 `task_output` 读取路径。subagent 层不会再注入第二份完成通知。
 
-用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务契约，不建立彼此独立的执行路径。
+用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务约定，不建立彼此独立的执行路径。
 
 ### 持久化 child handle 与从持久化存储恢复
 
-继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/core/session/src/json.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
+继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/core/session/src/json.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩（compaction）替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
 
-版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果契约，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
+版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果约定，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
 
 从持久化存储恢复不能依赖 `SubagentRun` 的可选方法，因为该 run 已被 dispose，并且进程重启后不会保留。run 表示一次可 dispose 的激活，只暴露作用于当前激活的操作。`SubagentRun.steer?()` 这一名称明确指代提供确认语义且仅适用于在线消息的功能，以免该功能与服务编排或面向模型的工具混淆。
 
-内部继续执行管理器的恢复路径会加载已知 child 会话、归并其描述符、根据持久化的 `parentSession` 鉴权，并在其创建的 Task 内部运行。它通过私有服务闭包传递完全解析的 `SubagentProviderResumeRequest`，其中包含由 Task 持有的取消信号；该闭包只负责在检查提供方功能后进行分发，并执行 `start` 所使用的普通 run 生命周期观察。选中的 `SubagentProvider.resume?()` 负责传输相关的重建（进程内：在当前加载的 parent 作用域下执行 `parent.ctx.agents.resume`），并返回一个新 run。提供方是否存在该方法本身就是继续执行功能，无需额外功能标志。`SubagentService.followup()` 在关联 run 的 `steer?()` 操作与该持久化恢复路径之间做出选择。私有的提供方分发与提供方本身都不会枚举持久化 child 或关联 Task。
+内部继续执行管理器的恢复路径会加载已知 child 会话、归并其描述符、根据持久化的 `parentSession` 鉴权，并在其创建的 Task 内部运行。它通过私有服务闭包传递完全解析的 `SubagentProviderResumeRequest`，其中包含由 Task 持有的取消信号；该闭包只负责在检查提供方能力后进行分发，并执行 `start` 所使用的普通 run 生命周期观察。选中的 `SubagentProvider.resume?()` 负责传输相关的重建（进程内：在当前加载的 parent 作用域下执行 `parent.ctx.agents.resume`），并返回一个新 run。提供方是否存在该方法本身就是继续执行功能，无需额外功能标志。`SubagentService.followup()` 在关联 run 的 `steer?()` 操作与该持久化恢复路径之间做出选择。私有的提供方分发与提供方本身都不会枚举持久化 child 或关联 Task。
 
 后台工具会在调用 `TaskService.start()` 前校验描述符输入并建立快照。同步校验失败会拒绝工具调用，且不会创建 Task。除此之外，工具会立即返回 child id 和 Task id，不等待 child 发布或描述符持久化完成。进程内可继续提供方会在 child 进入 idle 后、读取结果之前执行最终的 `SessionStore.flush()`；返回 `true` 表示至少有一个持久性监听器参与，返回 `false` 表示必需的检查点失败，而拒绝则携带监听器失败。此操作会在 child 仍存活时重试循环中失败的检查点。如果最终确认失败，提供方会拒绝而不返回未经确认的输出，继续执行管理器会 dispose 该 run，已经创建的 Task 会结算为 `failed`，其详情包含持久性诊断。最终确认期间发生取消时，尚未发布的激活结果由取消操作接管；即使 child 轮次已记录为完成，或之后的检查点失败，也不能取代 Task 的 `killed` 结果。前台一次性运行仍保留循环仅尽力执行检查点的行为。进程内 spawn 和 fork 会在当前已加载的 parent 作用域下重建组合配置。恢复 fork 时只加载 child 自己的持久化 transcript，其中已经包含初始创建时捕获的已完成轮次前缀；系统绝不会再次 fork parent 更新后的历史。恢复 parent 不会立即恢复其 child。
 
-TODO（ACP 继续执行）：将远端 ACP session id 作为提供方专用描述符数据持久化，并实现 `AcpProvider.resume?()`，依次执行 spawn、initialize、`loadSession` 和 prompt。初始 ACP run 必须检查 `initialize.agentCapabilities.loadSession`，恢复后的每个进程必须使用同一个持久化后端；`loadSession` 回放的历史消息不得计入新激活的输出。由于 ACP 的加载支持是按 child 协商的，不能仅根据提供方是否存在该方法来确定，因此该后续工作还必须定义 start 结果如何声明单个 child 支持继续执行，之后才能将 ACP child 写入持久化目录。
+TODO（ACP 继续执行）：将远端 ACP 会话 id 作为提供方专用描述符数据持久化，并实现 `AcpProvider.resume?()`，依次执行 spawn、initialize、`loadSession` 和 prompt。初始 ACP run 必须检查 `initialize.agentCapabilities.loadSession`，恢复后的每个进程必须使用同一个持久化后端；`loadSession` 回放的历史消息不得计入新激活的输出。由于 ACP 的加载支持是按 child 协商的，不能仅根据提供方是否存在该方法来确定，因此该后续工作还必须定义 start 结果如何声明单个 child 支持继续执行，之后才能将 ACP child 写入持久化目录。
 
 ### 结果与通知所有权
 
-每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告契约最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
+每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告约定最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
 
 Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可在重启后恢复，但不会恢复中断的 Task、其结果或通知。持久化 Task 恢复属于另一个问题。
 
@@ -95,7 +95,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 **允许用户轮次不使用 Task。** parent 消息加入此类轮次后，没有对应的 Task 结果或完成通知；UI 取消对 parent 所发消息的影响也不明确。让每次激活都拥有一个 Task，可使完成与取消成为 child 轮次的属性，而不是初始调用方的属性。
 
-**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 契约。
+**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 约定。
 
 **为每条消息创建 Task。** 发送到现有 run 的消息会加入已有轮次，不产生独立的最终结果；为这类消息创建 Task，会重复当前 Task，或报告一个它并不拥有的结果。只有启动新激活的消息才会创建 Task。
 
@@ -109,7 +109,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 ## 测试
 
-- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述契约。
+- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop（智能体循环）、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述约定。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
 - `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
@@ -123,5 +123,5 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - 活跃 run 关联只能协调一个运行时。多个进程同时恢复时不会串行化；此类部署需要持久化层的租约或 compare-and-set 操作。
 - 用户交互要求作为 owner 的那个精确 parent Agent 实例保持存活，因为 dispose owner 会取消并移除其 Task。用户交互还要求附加 Task 控制面。若要单独与 child 交互，后续必须将 Task 访问所有权与持久化通知目标分离。
 - 后台工具会在 child 发布和描述符持久化之前返回 child id 和 Task id。启动失败、最终持久性确认失败，或进程在 child 首次 flush 之前退出，都会使 Task 失败，并可能留下 unmaterialized 或陈旧的 child id；按 id 的控制操作会将缺失状态报告为不可用，而不会追溯修改工具确认消息。
-- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性契约便成为恢复契约的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
+- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性约定便成为恢复约定的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
 - Task 记录和活跃 run 关联位于进程内，而 child 会话具有持久性。重启会恢复会话，但不会恢复进行中的工作或其 Task 通知。
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index e4df6863da..5e4e651093 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
 2026-07-22-durable-subagent-catalog-and-list-agents.md: 61bda2a52f2ea5db0a582fe668643a13b967f091
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a2bc36200d8c67b8da9dd3d55ea4179baa72e691
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: fb60e63f23fae3146963e0fe4a7df44d0b497281
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index a2bc36200d..fb60e63f23 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：持久化 subagent 目录与 list_agents
+# Agent Note: 持久化 subagent 目录与 list_agents
 
 Status: implemented
 
@@ -8,11 +8,11 @@ Status: implemented
 
 可继续的后台 subagent 会公开稳定的 child id，并将重建数据持久化在该 child 的会话中，因此 `send_message` 无需任何列表查询操作即可恢复已知 child。发现功能有两类需求不同的消费方：UI 可以同时展示一次性工作和可继续对话，而模型只应收到适合使用 `send_message` 的 child。[可继续 subagent](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)负责持久化 Session 与 Activation 设计；本记录负责共享的持久化清单及面向模型的投影。
 
-枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。契约还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载大量 child 日志会如何影响服务与工具消费方。
+枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。约定还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载 child 日志会如何影响服务与工具消费方。
 
 ## 决策
 
-**列表读路径已被取代。**[subagent 列表经投影单元读取身份](../architecture/2026-08-06-subagent-list-identity-projection.md)取代了本记录的枚举与逐 child 读取设计:`listChildren` 现在直接合并存活会话存储与可选的会话持久化,并从注册的 `subagent` projection unit 读取每个 child 的 mode/label——不依赖会话查询,也不在列表时扫描描述符;当前的列表语义(含 diagnostic 映射)以该记录为准。本记录仍是描述符持久化、以 mode 判别的描述符作为持久身份、直接 parent 鉴权与面向模型的 `list_agents` 投影的权威;下文基于追踪的读取机制是决策背景,不再是当前行为。
+**列表读路径已被取代。**[subagent 列表经投影单元读取身份](../architecture/2026-08-06-subagent-list-identity-projection.md)取代了本记录的枚举与逐 child 读取设计：`listChildren` 现在直接合并存活会话存储与可选的会话持久化，并从注册的 `subagent` projection unit 读取每个 child 的 mode/label——不依赖会话查询，也不在列表时扫描描述符；当前的列表语义（含 diagnostic 映射）以该记录为准。本记录仍是描述符持久化、以 mode 判别的描述符作为持久身份、直接 parent 鉴权与面向模型的 `list_agents` 投影的权威；下文基于追踪的读取机制是决策背景，不再是当前行为。
 
 parent 到 child 的枚举是一项带消费方专用投影的服务功能。`SubagentService.listChildren(parentSessionId: SessionId)`（[subagent/src/index.ts](../../../../packages/subagent/subagent/src/index.ts)）执行以下操作：
 
@@ -23,27 +23,27 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 - 将语料活动状态单独报告为 `running` 或 `inactive`，但不暗示已完成或可恢复；
 - 按 `createdAt` 升序、再按 child id 升序稳定返回所有结果 child。
 
-每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
+每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 约定负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
 
 ### 枚举决策
 
 第一版消费 `ctx.sessionQuery.traceSession(parentSessionId)`，并且只考虑追踪结果的第一层后代。目标可以存活，也可以只存在于持久化存储中；追踪逻辑语料不会加载或恢复 Agent。会话查询已经使用实时优先规则合并 `ctx.sessions` 与 `ctx.sessionPersistence`，保持不可变 header 一致性，根据 `SessionHeader.parentSession` 推导直接 child 谱系，并按 `createdAt` 升序、child id 升序排列 sibling。`listChildren()` 不会重复实现这套语料逻辑，也不会检查继续执行管理器的进程内 Activation map。
 
-语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 契约中的“损坏 child”是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
+语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 约定中的「损坏 child」是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
 
 会话谱系涵盖的范围比 subagent 身份更广：普通 `ctx.sessions.fork()` 也会创建直接 child。会话 header 不新增 `kind` 判别字段；每个候选必须改为在自身后缀中恰好包含一个有效的 `subagent/descriptor` 事件。`SubagentService.start()` 会在普通提供方分发前解析 `{ mode: 'one-shot', provider, label? }`，而继续执行管理器会在初始创建 child 时为 `{ mode: 'continuable', ...composition }` 建立快照并将其作为 seed。本地进程内的一次性驱动只在初始创建期间追加已解析的描述符，从持久化存储冷恢复时不会追加其他描述符；第二个事件属于损坏，而不是另一次 Activation 的证据。Agent 创建是一次性运行的发布边界：拒绝表示没有发布 child，而发布后的提示词、轮次、取消与基础设施结果会通过返回的 run 结算，且不会隐藏其 id。描述符事件是已追踪 child 属于由会话支撑的 subagent 的唯一证据。缺少该事件的候选属于普通 fork、没有本地会话记录的远端 child 或其他非 subagent 会话，系统会将其排除且不产生 diagnostic。
 
-已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose 或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
+已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose（资源释放）或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
 
-subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时契约。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
+subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时约定。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
 
 `listChildren(parentSessionId, signal?)` 会把调用方的取消信号转发给 `traceSession()` 和条件性精确 `readEvent()` 操作。`listEvents()` 不接受取消参数，因此列表查询路径会在等待该操作的前后，以及每个候选处理完成后检查信号。如果取消信号触发后有查询操作以拒绝结算，服务会将结果归一化为 `SubagentError`，并携带稳定错误码 `CANCELLED`；后端中止错误或可映射为 diagnostic 的查询错误均不会逃逸，也不会使调用以成功的部分列表返回。
 
-这条描述符读取路径是正确性基线，并不声称工作量只与直接 child 数量呈线性关系。令 D 为直接 child 候选数量，C 为每次持久化列表查询所扫描的持久化会话数量，L_i 为候选 i 的完整日志大小。一次语料追踪后，每个候选都会执行 `sessionQuery.listEvents(childId)`。没有描述符的候选会被排除；含有多个描述符的候选会直接产生 diagnostic，无需再次读取；只有恰好含有一个描述符的候选才会通过 `sessionQuery.readEvent({ sessionId: childId, seq })` 再次加载。此次读取返回的不可变会话 header 必须与追踪时观测到的相同，包括直接 parent 关系，并且读取目标仍必须是先前定位的描述符事件；任何不一致均视为该 child 损坏。对于只存在于持久化存储中的最坏情况，每次精确读取都会重复执行 `persistence.list()`、加载完整 child 日志并克隆其中的事件，因此忽略常数因子后的工作量为 O(D × C + Σ L_i)；恰好含有一个描述符的候选承担两次这类成本，其他候选只承担一次。存活候选同样会对其完整日志取得一份分离的内存快照；读取其描述符时则会取得两份。会话查询通过持久化 seam 的非变更 `inspect()` 读取解析持久化候选：它返回有效的已存储前缀，既不修复撕裂的尾部，也不关闭中断的 turn，因此列表查询是存储只读操作；修复仍是恢复路径的职责。第一版接受这些重复读取，将其作为无索引的正确性基线，但部署必须将语料总量和 child 日志大小，而不仅是直接 child 数量，视为容量约束。列表查询不会创建 Agent，也不会追加任何目录、描述符或修复事件。对模型隐藏的描述符始终位于对话 surface 之外，并且会在压缩后保留，因此经过压缩和未经压缩的 child 必须枚举出相同结果。
+这条描述符读取路径是正确性基线，并不声称工作量只与直接 child 数量呈线性关系。令 D 为直接 child 候选数量，C 为每次持久化列表查询所扫描的持久化会话数量，L_i 为候选 i 的完整日志大小。一次语料追踪后，每个候选都会执行 `sessionQuery.listEvents(childId)`。没有描述符的候选会被排除；含有多个描述符的候选会直接产生 diagnostic，无需再次读取；只有恰好含有一个描述符的候选才会通过 `sessionQuery.readEvent({ sessionId: childId, seq })` 再次加载。此次读取返回的不可变会话 header 必须与追踪时观测到的相同，包括直接 parent 关系，并且读取目标仍必须是先前定位的描述符事件；任何不一致均视为该 child 损坏。对于只存在于持久化存储中的最坏情况，每次精确读取都会重复执行 `persistence.list()`、加载完整 child 日志并克隆其中的事件，因此忽略常数因子后的工作量为 O(D × C + Σ L_i)；恰好含有一个描述符的候选承担两次这类成本，其他候选只承担一次。存活候选同样会对其完整日志取得一份分离的内存快照；读取其描述符时则会取得两份。会话查询通过持久化 seam 的非变更 `inspect()` 读取解析持久化候选：它返回有效的已存储前缀，既不修复撕裂的尾部，也不关闭中断的轮次，因此列表查询是存储只读操作；修复仍是恢复路径的职责。第一版接受这些重复读取，将其作为无索引的正确性基线，但部署必须将语料总量和 child 日志大小，而不仅是直接 child 数量，视为容量约束。列表查询不会创建 Agent，也不会追加任何目录、描述符或修复事件。对模型隐藏的描述符始终位于对话 surface 之外，并且会在压缩（compaction）后保留，因此经过压缩和未经压缩的 child 必须枚举出相同结果。
 
 如果实测规模日后需要索引，该索引属于派生状态：会话 header 和 child 描述符仍是权威信息，重建或损坏回退必须复现相同结果。索引不能成为第二个鉴权来源，也不能让尚未发布的 child 变得可见。
 
-### `list_agents` 契约
+### `list_agents` 约定
 
 `SubagentService.listChildren(parentSessionId: SessionId)` 返回 `Promise<SubagentListEntry[]>`，其中的单个数组不会将 child 与 diagnostic 分开，而是保留追踪结果中的候选顺序。`SubagentListEntry` 是一个由只读 `kind` 判别的封闭联合类型：
 
@@ -52,7 +52,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
 在已被取代的追踪读路径中，diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
@@ -80,23 +80,23 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 **持久化 parent 会话目录事件。** 直接 child header 已经提供持久化枚举种子，child 描述符则是重建的权威信息。第二份 parent 日志会重复状态，并造成跨会话顺序和陈旧条目行为，却无助于按 id 恢复。
 
-**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动契约。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
+**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动约定。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
 
 **某个 child 无法加载时让整次列表查询失败。** 这种做法不会让损坏问题被忽略，但一个损坏的 sibling 会让每个健康 child 都不再可见。逐 child diagnostic 在保持每次排除明确可见的同时，也保留了发现能力。
 
 **分别返回 child 和 diagnostic 数组。** 分离的数组会引入两个排序域，或者要求公开另一个排序键才能重建候选顺序。一个带判别字段的条目数组既能保留追踪顺序，也能保证 child 与 diagnostic 字段的类型安全。
 
-**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 契约，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
+**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 约定，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
 
 **立即为查询分页或设置上限（暂缓）。** 这可以限制一次结果的大小，但会使模型发现成为有状态操作，而且除非模型继续跟随 cursor，否则可能隐藏更早的 child。第一版没有 cursor、分页参数或候选数量上限配置，而是返回经稳定排序的完整集合；如果实测规模需要限制，服务级限制仍留待后续决策。
 
 ## 测试
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
-- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载契约，以及 HMR dispose。
+- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格（已随查询式读取路径一起退役）曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载约定，以及 HMR dispose。
 - 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
-- 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
+- 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的已结算 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
 
 ## 影响
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
index e78ab9abbd..7e50021fd6 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
 2026-07-23-web-assistant-markdown.md: ad86559e3b5294b6bd67d69ff5c6ce37a5172008
-2026-07-23-web-assistant-markdown.zh.md: b47375db843ea1c81b913e3f7ac8cd1bbc278830
+2026-07-23-web-assistant-markdown.zh.md: d1f06b4019812b0fee3c481efecaf214a137c8a7
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
index b47375db84..d1f06b4019 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
@@ -12,7 +12,7 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd
 
 `@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`，用作不受信任的 assistant 文本渲染器；`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`，因此无需更改事件或快照，它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`，并保持按字面渲染。
 
-`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性契约）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
+`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性约定）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
 
 视觉间距、表格、链接、引用块、行内代码与代码块外框遵循 deepsuite `@deepseek/md`（`markdown.css` / `code-block.css`），并使用同一套 `--dsw-alias-markdown-*`、`--dsw-font-markdown-*`、`--dsw-alias-border-l*` 与 `--dsw-alias-label-*` token。链接使用 `--dsw-alias-state-business-primary`（deepsuite 的样式表使用 `--dsw-alias-brand-text`，仅在 newDesign 下为蓝色；design-platform 将 brand-text 保持为近黑色，此处不做重新调色）。当单个行内代码 token 完全由绝对 HTTP(S) URL 构成时，其代码外框会包含一个与普通链接相同、可通过键盘聚焦的安全外链锚点；端口、路径与查询文本保持不变，而命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。`CodeBlock` 提供语言横幅与复制控件（`复制` / `复制成功`）。已完成的文本通过定稿语法的数学扩展渲染 KaTeX；`mathCompatibility` 将 `\(...\)`、`\[...\]` 和块级同一行 `$$...$$` 映射为同一套标准数学 AST 节点。这是一层小范围的解析器兼容层，不是正则重写，也不修复格式错误的模型输出。流式输出在完成前保持按字面渲染，避免不完整公式闪现错误。引用胶囊、标题锚点、thinking-small markdown 变体，以及自定义 □/☑ 任务标记仍不在范围内；GFM 任务列表继续使用原生复选框。
 
@@ -26,15 +26,15 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
 
 ## 考虑过的替代方案
 
-**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。*后因新证据被推翻——增量流式解析需要纯字符串封装无法提供的 AST 级输入；该决策由[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有。*
+**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。*后因新证据被推翻——增量流式解析需要仅接受字符串的包装层无法提供的 AST 级输入；该决策由[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有。*
 
 **将 `MessageText` 替换为 Markdown 渲染。**这会产生格式化用户提示词与 steering 的副作用。在产品明确选择此行为之前，这两类输入内容仍按字面渲染。
 
 **将 Markdown 解析为会话快照。**这会让 React 节点或呈现层 AST 成为持久的运行时状态，并重新引入最终输出与流式输出之间的模式边界。解析仍留在呈现层的叶节点中。
 
-**通过净化启用原始 HTML。** 原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。
+**通过净化启用原始 HTML。**原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。
 
-**移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 契约。
+**移植 deepsuite 的 Prism `highlight.css` 与 mdast 流水线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 约定。
 
 **为处理 CJK 标点边界而预处理 Markdown 源文本，或在解析后修复文本节点。**源文本重写必须在解析器掌握这些区别之前复现转义、代码、数学公式与定界符规则；文本节点修复则已经丢失部分源文本意图，也无法与已解析的行内节点组合。在分词器边界扩展 attention 可保留上游 resolver，并将差异限制在定界符的适用条件上。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
index 3c006bc9f1..7c8910602f 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.md
 2026-07-23-web-permission-and-approval.md: 06e184fe32ac684e3d8b0820d915ca7c372a5760
-2026-07-23-web-permission-and-approval.zh.md: b74e93006cb95c398eb464a9bd9a59e8c9cc57be
+2026-07-23-web-permission-and-approval.zh.md: 9c8718169b720f55065d5e4a416f65c94f83cc9c
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
index b74e93006c..9c8718169b 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
@@ -6,28 +6,28 @@ Status: implemented
 
 ## 问题
 
-Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议契约其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
+Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议约定其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
 
 ## 决策
 
 Web 承载层组合与 acp-agent 相同的沙箱化产品路径：`dsh-sandbox-local`、`dsh-sandbox-policy`、`dsh-bash-sandbox`、`dsh-fs-sandbox`、`dsh-user-approval` 与 `dsh-permission`，由 `BootHostOptions.sandbox` 提供部署默认值（`mode`，默认 `workspace-write`；`approvalPolicy`，默认 `ask`）。
 
-`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题 mint 一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是契约早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，解析应答者，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
+`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题生成一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是约定早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，调用应答者完成应答，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
 
-权限选择依托两个新的一元 RPC，`session.permissions` 与 `session.setPermission`，把 `ctx.permission` 投影为一个由协议拥有的 `PermissionOption` DTO（沿用 ACP bridge 的先例：每个协议拥有自己的呈现形状）。无权限的组合提供空的选择项，client 隐藏该控件。空闲期的切换以后写胜出（last-write-wins）的方式保存在 proxy 侧的 pending map 中，并在 `agent/pre-step` 时冲刷，因为旋钮事件必须保持轮次内闭合以支持持久回放；共享的 `hasOpenTurn` 折叠迁入 `dsh-session`，取代了 `dsh-user-approval`、ACP bridge 与 proxy 中各自的私有副本。
+权限选择依托两个新的一元 RPC，`session.permissions` 与 `session.setPermission`，把 `ctx.permission` 投影为一个由协议拥有的 `PermissionOption` DTO（沿用 ACP bridge 的先例：每个协议拥有自己的呈现形状）。无权限的组合提供空的权限选项列表，client 隐藏该控件。空闲期的切换以后写胜出（last-write-wins）的方式保存在 proxy 侧的 pending map 中，并在 `agent/pre-step` 时统一应用，因为旋钮事件必须保持轮次内闭合以支持持久回放；共享的 `hasOpenTurn` 折叠迁入 `dsh-session`，取代了 `dsh-user-approval`、ACP bridge 与 proxy 中各自的私有副本。
 
-在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 契约中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
+在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 约定中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
 
 ## 曾考虑的替代方案
 
-**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 契约的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
+**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 约定的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
 
 **用一个会话事件承载 pending 交互，而非实时注册表。** 不予采纳：可应答请求是瞬态的交互状态，而非持久的会话数据——审批的 `approval/asked`/`decided` 审计对已经记录了持久的那一半。持久化 requested 帧会在回放时重新问出已经作废的问题。
 
-**仅在存在 mux 订阅者时才注册应答者。** 不予采纳：pending 条目必须在 client 断连后依然存活（刷新恢复正是要点所在），因此注册表的生命周期长于任何单个流；一个受订阅者门控的应答者，会让在重载窗口期间关闭的 ask 落空。
+**仅在存在 mux 订阅者时才注册应答者。** 不予采纳：pending 条目必须在 client 断连后依然存活（刷新恢复正是要点所在），因此注册表的生命周期长于任何单个流；一个受订阅者门控的应答者，会导致重载窗口期间发起的 ask 以默认拒绝的方式失败。
 
-**点击即乐观移除卡片。** 不予采纳：广播的 resolved 帧才是真相；点击即移除会隐藏一个因拒绝回执或传输失败而仍然悬置的问题。面板改为在本地禁用其按钮，并在失败时重新启用。
+**点击即乐观移除卡片。** 不予采纳：广播的 resolved 帧才是真相；点击即移除会隐藏一个因回执被拒或传输失败而仍然悬置的问题。面板改为在本地禁用其按钮，并在失败时重新启用。
 
 ## 后果
 
-Web 会话从受限状态启动（默认 `workspace-write` + `ask`），一次沙箱拒绝的升级会以可应答的卡片形式抵达浏览器；部署方可以通过 `BootHostOptions.sandbox` 放宽或收紧默认值，无需触动装配。问题应答使用同一注册表模式（ui-question 基于问题 pending 表），Session 导航会在用户打开会话前识别审批、计划审阅与普通问题等待。权限选择在每次挂载时读取一次；来自另一个 client 切换的实时刷新暂缓实现。覆盖率：proxy 注册表与权限 RPC 的单元测试套件、会话对象与 fixture 的单元测试套件、针对 fixture 模式审批应答与预设切换的无密钥 Web 冒烟测试，以及真实组合的 plan-review 与问题快照；这些快照会固定 pending 侧边栏状态直至解决。
+Web 会话从受限状态启动（默认 `workspace-write` + `ask`），一次沙箱拒绝的升级会以可应答的卡片形式抵达浏览器；部署方可以通过 `BootHostOptions.sandbox` 放宽或收紧默认值，无需触动装配。问题应答使用同一注册表模式（ui-question 基于问题 pending 表），Session 导航会在用户打开会话前识别审批、计划审查与普通问题等待。权限选择在每次挂载时读取一次；来自另一个 client 切换的实时刷新暂缓实现。测试覆盖：proxy 注册表与权限 RPC 的单元测试套件、会话对象与 fixture 的单元测试套件、针对 fixture 模式审批应答与预设切换的无密钥 Web 冒烟测试，以及真实组合的 plan-review 与问题快照；这些快照会固定 pending 侧边栏状态直至解决。
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
index b11dc50cd6..c02bd6523c 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
 2026-07-24-model-facing-session-query-tools.md: 863f557f11f89ff8dfc121b7da0b653852528394
-2026-07-24-model-facing-session-query-tools.zh.md: d8deaba15f111537a16deafe73ed6dd708ea044a
+2026-07-24-model-facing-session-query-tools.zh.md: 584733de7b00f22f186838b058a24c31ff035905
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
index d8deaba15f..584733de7b 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-统一的 `ctx.sessionQuery` 服务对优先使用实时数据的会话日志提供精确读取、过滤、关系追踪与全文搜索，但模型无法直接使用该服务。若把提供方请求类型交给模型，还会暴露不稳定的分页游标、受信任的语料范围、存储形态的时间值，以及更适合程序化消费者而非模型推理的结果记录。大型追踪与事件负载另有输出大小问题，但若在该消费者内部解决，就会重复 harness 的通用 spill 机制，并使会话查询工具与其他工具的行为不一致。
+统一的 `ctx.sessionQuery` 服务对优先使用实时数据的会话日志提供精确读取、过滤、关系追踪与全文搜索，但模型无法直接使用该服务。若把提供方请求类型交给模型，还会暴露不稳定的分页游标、受信任的语料范围、存储形态的时间值，以及更适合程序化消费方而非模型推理的结果记录。大型追踪与事件负载另有输出大小问题，但若在该消费方内部解决，就会重复 harness 的通用 spill 机制，并使会话查询工具与其他工具的行为不一致。
 
 ## 决策
 
-`@deepseek-ai/dsh-tool-session-query` 是 `ctx.sessionQuery` 面向模型的消费者。它注册五个职责单一的只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`。该包依赖接口而非 SQLite 实现，负责模型参数校验与易读文本渲染，并贡献一个精简的提示词段，说明历史搜索以及从搜索转向追踪／读取的工作流。
+`@deepseek-ai/dsh-tool-session-query` 是 `ctx.sessionQuery` 面向模型的消费方。它注册五个职责单一的只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`。该包依赖接口而非 SQLite 实现，负责模型参数校验与易读文本渲染，并贡献一个精简的提示词段，说明历史搜索以及从搜索转向追踪／读取的工作流。
 
-该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包契约。
+该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包约定。
 
 `session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接来源关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 工作区权限
 
-每个执行器都从不可变的 `ToolExecution.exec.agent` 身份推导调用者，绝不接受模型提供的工作区。只有当目标观测中的 `cwd` 与调用者会话的 `cwd` 完全相同时，目标才获授权。跨会话搜索始终附加该工作区过滤条件。直接操作先预检目标，然后在渲染负载前，校验与每一页事件搜索结果、事件追踪、事件读取、谱系目标或折叠标题来自同一服务观测的会话头。这样，即使实时或持久化目标在检查与使用之间被替换，也无法跨越工作区边界。谱系渲染在遇到未授权的祖先或后代子树时停止，且不泄露被隐藏的会话 id。调用者会话没有 `cwd` 时只能检查自身会话；缺少 agent 身份时按失败关闭处理。
+每个执行器都从不可变的 `ToolExecution.exec.agent` 身份推导调用者，绝不接受模型提供的工作区。只有当目标观测中的 `cwd` 与调用者会话的 `cwd` 完全相同时，目标才获授权。跨会话搜索始终附加该工作区过滤条件。直接操作先预检目标，然后在渲染负载前，校验与每一页事件搜索结果、事件追踪、事件读取、谱系目标或折叠标题来自同一服务观测的会话头。这样，即使实时或持久化目标在检查与使用之间被替换，也无法跨越工作区边界。谱系渲染在遇到未授权的祖先或后代子树时停止，且不泄露被隐藏的会话 id。调用者会话没有 `cwd` 时只能检查自身会话；缺少 agent（智能体）身份时按失败关闭处理。
 
 每个受信任的 `ctx.sessionQuery` 调用都会经过同一个模型边界净化器。它首先检查执行信号，准确保留调用者取消。对于其他失败，它会尽力把可获得的语料或提供方诊断链写入内部日志；当值无法安全检查时，则改用固定占位符。诊断格式化与错误分类各自受到保护，因此无法打印的嵌套 cause 既不会逃逸，也不会阻止对外层错误进行安全分类；分类不安全或日志记录失败时，则返回固定的通用错误码 `SESSION_QUERY_TOOL_FAILED` 及其消息。逐标题失败也会先经过同一个净化器，再转为不可用标记。工具自身的输入校验与授权错误在该服务边界之外创建，因此仍保留精确消息。
 
@@ -28,11 +28,11 @@ Status: implemented
 
 ## 无游标结果与 spill
 
-两个搜索工具都不向模型公开游标、偏移量、页大小或模型可控的结果限制。一次执行会在观察到的代保持有效时持续跟随提供方游标，并收集不超过配置项 `maxSearchResults` 的结果，其默认值为 100。达到上限的结果会要求模型缩小查询或过滤范围；代发生变化时会报告必须重试完整搜索。搜索执行通过工具截止时间与服务中止信号传递可配置的 `searchTimeoutMs`，默认值为 30 秒。由于内部页面共享与代绑定的游标，两个搜索工具在 agent loop 调度器中都以独占方式执行；精确追踪与读取工具则允许和兄弟工具并行执行，因为其观测可以容忍期间发生的提交。
+两个搜索工具都不向模型公开游标、偏移量、页大小或模型可控的结果限制。一次执行会在观察到的代保持有效时持续跟随提供方游标，并收集不超过配置项 `maxSearchResults` 的结果，其默认值为 100。达到上限的结果会要求模型缩小查询或过滤范围；代发生变化时会报告必须重试完整搜索。搜索执行通过工具截止时间与服务中止信号传递可配置的 `searchTimeoutMs`，默认值为 30 秒。由于内部页面共享与代绑定的游标，两个搜索工具在 agent loop（智能体循环）调度器中都以独占方式执行；精确追踪与读取工具则允许和兄弟工具并行执行，因为其观测可以容忍期间发生的提交。
 
-追踪与读取工具同样不公开谱系分页或字符分页。规范结果采用纯文本，并在服务已有的事件窗口与搜索数量资源边界内保持完整。每个精确执行器都会将未经替换的工具执行信号传递给目标授权与服务追踪或读取。在服务解析过程中，已知实时事件追踪、事件读取与标题读取在遵循预中止的同时仍不访问持久化。会话谱系追踪会将该信号传递给全语料持久化列表；持久化事件追踪与读取则将其传递给目标列表和检查。每个已启动的后端调用都会等待清理完成后再保留准确的中止原因，即使该后端忽略了取消也不例外。通用的 `tools/post-execute` spill 策略负责行内字节保留：当已配置的部署收到过大的文本时，该策略会用有界预览、不可透明推导的定位符与读取提示替换文本，同时在 spill 存储中保留完整结果。会话查询消费者既不导入 `ctx.spillStore`，也不实现第二套截断格式。
+追踪与读取工具同样不公开谱系分页或字符分页。规范结果采用纯文本，并在服务已有的事件窗口与搜索数量资源边界内保持完整。每个精确执行器都会将未经替换的工具执行信号传递给目标授权与服务追踪或读取。在服务解析过程中，已知实时事件追踪、事件读取与标题读取在遵循预中止的同时仍不访问持久化。会话谱系追踪会将该信号传递给全语料持久化列举操作；持久化事件追踪与读取则将其传递给目标列举与检查操作。每个已启动的后端调用都会等待清理完成后再保留准确的中止原因，即使该后端忽略了取消也不例外。通用的 `tools/post-execute` spill 策略负责行内字节保留：当已配置的部署收到过大的文本时，该策略会用有界预览、不透明定位符与读取提示替换文本，同时在 spill 存储中保留完整结果。会话查询消费方既不导入 `ctx.spillStore`，也不实现第二套截断格式。
 
-会话级结果在可用时包含最新折叠标题。每次工具执行都会通过一次优先使用实时数据的语料观测批量读取唯一标题 id，最多使用服务通过 `persistedInspectConcurrency` 配置的持久化检查 worker，其默认值为 4，并将准确的工具执行信号传递给持久化列表与检查操作。实时来源会直接折叠；每个持久化 worker 都会把已完成的来源折叠为分离的会话头／标题观测，并在取出下一个 id 前释放完整日志，因此批次只保留小型投影值。对于搜索工具，该执行信号携带已配置的搜索截止时间。取消不会启动排队中的标题检查，并会在已经启动的检查全部完成后拒绝完整的工具执行；标题缺失、格式错误或发生操作性失败时，错误只影响对应 id，同时保留基础结果、渲染不可用标记并记录底层错误，而授权不匹配则按失败关闭处理。搜索结果包含最强匹配事件与提供方摘录，追踪包含完整的已授权关系，事件读取保持邻近事件表现易读，同时只为被请求的目标保留精确 JSON。
+会话级结果在可用时包含最新折叠标题。每次工具执行都会通过一次优先使用实时数据的语料观测批量读取唯一标题 id，最多使用服务通过 `persistedInspectConcurrency` 配置的持久化检查 worker，其默认值为 4，并将准确的工具执行信号传递给持久化列举与检查操作。实时来源会直接折叠；每个持久化 worker 都会把已完成的来源折叠为分离的会话头／标题观测，并在取出下一个 id 前释放完整日志，因此批次只保留小型投影值。对于搜索工具，该执行信号携带已配置的搜索截止时间。取消不会启动排队中的标题检查，并会在已经启动的检查全部完成后拒绝完整的工具执行；标题缺失、格式错误或发生操作性失败时，错误只影响对应 id，同时保留基础结果、渲染不可用标记并记录底层错误，而授权不匹配则按失败关闭处理。搜索结果包含最强匹配事件与提供方摘录，追踪包含完整的已授权关系，事件读取保持邻近事件表现易读，同时只为被请求的目标保留精确 JSON。
 
 ## 宿主组合
 
@@ -42,14 +42,14 @@ Status: implemented
 
 - **向模型公开提供方游标**：不予采纳，因为记录工具结果或开始下一个模型步骤会改变相关会话或全局代，导致游标通常在模型能够复用前就已过期。
 - **增加工具本地截断、偏移量或 spill 文件**：不予采纳，因为执行后 spill 策略已经统一负责各工具的完整结果保留与读取。
-- **允许访问所有持久化会话或由模型提供工作区过滤条件**：不予采纳，因为 `ctx.sessionQuery` 是受信任服务，面向模型的消费者必须执行调用者权限边界。
+- **允许访问所有持久化会话或由模型提供工作区过滤条件**：不予采纳，因为 `ctx.sessionQuery` 是受信任服务，面向模型的消费方必须执行调用者权限边界。
 - **把搜索、追踪与精确读取合并为一个带操作选择器的工具**：不予采纳，因为职责单一的名称能为模型提供更清晰的 schema、默认值、表现意图与后续选择。
 - **只返回一层谱系**：不予采纳，因为 spill 已消除行内大小方面的理由，而单层输出会遗漏关系且没有继续读取路径。
 
 ## 验证
 
-包级测试固定参数校验、过滤条件转换、时间戳规范化、精确工作区授权、父级过滤预授权与抵御预言机探测、变更观测拒绝、普通值与对抗性未知值的服务诊断脱敏、尽力记录循环 cause、日志失败隔离、身份缺失行为、隐藏边界裁剪、当前步骤排除、内部提供方翻页、搜索独占与精确读取并行分类、数量上限、精确信号传递、中止原因保留、持久化清理静止、单次扫描且并发有界的批量标题扩充、先投影再取出下一个任务的顺序、抑制排队工作、等待已启动 worker 静止、逐会话头校验、标题回退、代表性搜索／追踪／读取渲染、通用表现与可释放注册。集成覆盖使用真实 SQLite FTS 提供方查询实时与持久化会话。发布配置与 TUI/Web 组合测试证明面向模型的消费方不存在于 TUI、Web 与无头界面，而组装后的 ACP 请求头快照证明自动化界面默认不包含它。包自身的 Loader 冒烟测试与专用无密钥 ACP 快照显式挂载该消费方，并配套启用超时与 spill 支持，固定其提示词指引、schema 以及与路径无关的精确事件读取保留行为。
+包级测试固定参数校验、过滤条件转换、时间戳规范化、精确工作区授权、父级过滤预授权与抵御预言机探测、变更观测拒绝、普通值与对抗性未知值的服务诊断脱敏、尽力记录循环 cause、日志失败隔离、身份缺失行为、隐藏边界裁剪、当前步骤排除、内部提供方翻页、搜索独占与精确读取并行分类、数量上限、精确信号传递、中止原因保留、持久化清理完全停稳、单次扫描且并发有界的批量标题扩充、先投影再取出下一个任务的顺序、抑制排队工作、等待已启动 worker 完全停稳、逐会话头校验、标题回退、代表性搜索／追踪／读取渲染、通用表现与可释放注册。集成覆盖使用真实 SQLite FTS 提供方查询实时与持久化会话。发布配置与 TUI/Web 组合测试证明面向模型的消费方不存在于 TUI、Web 与无头界面，而组装后的 ACP 请求头快照证明自动化界面默认不包含它。包自身的 Loader 冒烟测试与专用无密钥 ACP 快照显式挂载该消费方，并配套启用超时与 spill 支持，固定其提示词指引、schema 以及与路径无关的精确事件读取保留行为。
 
 ## 后果
 
-模型无需获得存储权限或继续状态，即可通过与提供方无关的方式访问既往会话工作。搜索具有有限的单次调用工作边界，若要命中前 100 条以后的结果，可能需要缩小查询；搜索调用不能与兄弟工具重叠执行，而精确观测仍可并行调度。完整追踪与事件负载可能表现为 spill 引用而不是行内文本。严格的 `cwd` 字符串相等选择了保守安全边界，而不解析通过符号链接等价的路径。自定义组合可以在不挂载 spill 的情况下使用该工具，但这表示它们明确接受完整追踪与读取结果直接出现在行内。
+模型无需获得存储权限或继续状态，即可通过提供方无关的方式访问既往会话工作。搜索具有有限的单次调用工作边界，若要命中前 100 条以后的结果，可能需要缩小查询；搜索调用不能与兄弟工具重叠执行，而精确观测仍可并行调度。完整追踪与事件负载可能表现为 spill 引用而不是行内文本。严格的 `cwd` 字符串相等选择了保守安全边界，而不解析通过符号链接等价的路径。自定义组合可以在不挂载 spill 的情况下使用该工具，但这表示它们明确接受完整追踪与读取结果直接出现在行内。
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
index fe955d125d..746c8740b4 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
 2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9
-2026-07-25-session-list-browsing-and-manual-order.zh.md: 8ec5f71943a68a70f46fbd4c7702e4556b1892ec
+2026-07-25-session-list-browsing-and-manual-order.zh.md: 216ade7b723f82740d485a435d360a060a2b42d9
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
index 8ec5f71943..216ade7b72 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
@@ -6,55 +6,55 @@ Status: implemented
 
 ## Problem
 
-[Workspace UI 完整产品流](2026-07-25-workspace-ui-product-flow.md)交付了分组 session 列表的首个形态,并把 Rename、拖拽排序等操作明确划出当期范围。设计稿(figma 239-10458 及关联画面)随后补齐了这些交互:列表要能切换成不分组的平铺视图、session 行悬停要出详情卡与操作菜单、workspace 要能改名、组内 session 要能手动排序。
+[Workspace UI 完整产品流](2026-07-25-workspace-ui-product-flow.md)交付了分组会话列表的首个形态，并把 Rename、拖拽排序等操作明确划出当期范围。设计稿（figma 239-10458 及关联画面）随后补齐了这些交互：列表要能切换成不分组的平铺视图、会话行悬停要出详情卡与操作菜单、workspace 要能改名、组内会话要能手动排序。
 
-两条既有机制挡在前面。其一,host 在每条 `session/event` 上把活跃 session durable 地提到 workspace 账本最前(活动置顶),任何手动排序都会被下一次活动打乱——两种排序权威不可调和。其二,浏览区域被劈在两个包里:ui-sidebar 拥有列表、搜索和组头行,ui-workspace 只借一个 picker 坑放弹层;每加一个 workspace 域的对话框都要跨包接线,归属越来越拧。
+两条既有机制挡在前面。其一，host 在每条 `session/event` 上把活跃会话持久化地提到 workspace 账本最前（活动置顶），任何手动排序都会被下一次活动打乱——两种排序权威不可调和。其二，浏览区域被劈在两个包里：ui-sidebar 拥有列表、搜索和组头行，ui-workspace 只借一个 picker slot 放弹层；每加一个 workspace 域的对话框都要跨包接线，归属越来越拧。
 
 ## Decision
 
 ### 平铺行与浏览态
 
-group-by 菜单提供 WorkSpace / In one list 两种模式。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序在各组内展示同级 session 行；In one list 把所有 session 合并后严格按 `updatedAt` 新→旧排序。两种模式都不把 `parentId` 投影成列表层级，fork 谱系只保留为 session 数据；完整 fork 行为由 [Web session fork 操作](2026-07-27-web-session-fork-actions.md)定义。模式选择持久化在浏览器(`dsh.workspace.view`),刷新保持。
+group-by 菜单提供 WorkSpace / In one list 两种模式。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序在各组内展示同级会话行；In one list 把所有会话合并后严格按 `updatedAt` 新→旧排序。两种模式都不把 `parentId` 投影成列表层级，fork 谱系只保留为会话数据；完整 fork 行为由 [Web 会话 fork 操作](2026-07-27-web-session-fork-actions.md)定义。模式选择持久化在浏览器（`dsh.workspace.view`），刷新保持。
 
 ### 行交互
 
-- session 行悬停 500ms 出详情卡(全名/相对时间/状态行;状态本期只有 running/idle 两态,枚举扩展待 wire 增补 status 字段)。卡片与行菜单互斥:菜单开启或拖拽进行中不出卡。
-- session 行 … 菜单:Rename / Fork session / Delete session，其中 Rename 与 Fork 已接线，Delete 仍为纯视觉；workspace 组头 … 菜单的 Rename / Delete workspace 均已接线。菜单鼠标移出即关。
-- 支撑件:`Menu` 新增 label 条目、danger 行、`closeOnPointerLeave`;新增 `HoverCard`(portal 定位、开启延时、disabled 守卫)。
+- 会话行悬停 500ms 出详情卡（完整标题、相对时间、状态行；状态本期只有 running/idle 两态，枚举扩展待协议格式（wire format）增补 status 字段）。卡片与行菜单互斥：菜单开启或拖拽进行中不出卡。
+- 会话行 … 菜单：Rename / Fork session / Delete session，其中 Rename 与 Fork 已接线，Delete 仍为纯视觉；workspace 组头 … 菜单的 Rename / Delete workspace 均已接线。菜单鼠标移出即关。
+- 支撑件：`Menu` 新增 label 条目、danger 行、`closeOnPointerLeave`；新增 `HoverCard`（portal 定位、开启延时、disabled 守卫）。
 
 ### workspace.rename
 
 `workspace.rename({ workspaceId, title })`：title trim 后非空；同名 no-op 与重名查重都在 Host 的 Workspace 操作串行链内求值（与按名称创建共链，并发的显式命名操作不能穿插出重名或乱序假成功），冲突返回 `workspace-name-conflict`。按路径收编可以派生出已有 title，因为拥有身份的是 canonical path，而不是 title（见[身份决策](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)）。落盘经 `setTitle` 的 mutate 通道，`domain/changed` 监听自动广播 `host/workspace-changed` 帧。UI 为标准 Modal，client 侧另做重名预检。
 
-### 手动排序:insertSessionBefore 取代活动置顶
+### 手动排序：insertSessionBefore 取代活动置顶
 
-`session/event` → `touchSession` 活动置顶链整体删除;workspace 账本序改为纯手动拥有——新 session attach 时前插,显式重排走 `workspace.insertSessionBefore({ workspaceId, sessionId, beforeSessionId? })`(DOM insertBefore 语义:锚给了插锚前,缺省 append 到末尾)。实体只对不在账的 session/锚抛类型化的 `WorkspaceMoveInvalidError`,handler 仅把它映射为业务码 `workspace-move-invalid`,存储故障保持 internal。
+`session/event` → `touchSession` 活动置顶链整体删除；workspace 账本序改为纯手动拥有——新会话 attach 时前插，显式重排走 `workspace.insertSessionBefore({ workspaceId, sessionId, beforeSessionId? })`（DOM insertBefore 语义：有锚点时插到锚点前，省略时 append 到末尾）。实体只对不在账的会话/锚抛类型化的 `WorkspaceMoveInvalidError`，handler 仅把它映射为业务码 `workspace-move-invalid`，存储故障保持 internal。
 
-UI 为组内 session 行的 HTML5 拖拽(仅 workspace 分组、非搜索态；fork 子与源会话一样独立排序)。顺序权威完全在 host:drop 只发 RPC,client 零本地重排,视图靠响应体 upsert 与 changed 帧刷新;失败即无事发生。client 的 upsert 拒绝比已装载投影更旧(`updatedAt`)的快照,防迟到的一元响应回滚更新的帧。
+UI 为组内会话行的 HTML5 拖拽（仅 workspace 分组、非搜索态；fork 子会话及其源会话各自独立排序）。顺序权威完全在 host：drop 只发 RPC，client 零本地重排，视图靠响应体 upsert 与 changed 帧刷新；失败即无事发生。client 的 upsert 拒绝比已装载投影更旧（`updatedAt`）的快照，防迟到的一元响应回滚较新的帧。
 
 ### 壳/区域切分
 
-ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settings,以及一个 `sidebar.workspaces` 洞;壳与区域的契约只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域(section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽)及其 groupBy store;rail 态的搜索/添加工作区图标也归区域,经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`(区域内直接组件组合;在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`)与薄包装 `WorkspacePicker`(继续填 ui-conversation 的 hero 坑);原 `sidebar.workspace` picker 坑与声明感知延迟注册随之删除。
+ui-sidebar 缩为列几何壳：品牌行、折叠状态机、New Session、Settings，以及一个 `sidebar.workspaces` slot；壳与区域的约定只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域（section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽）及其 groupBy store；rail 态的搜索/添加工作区图标也归区域，经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`（区域内直接组件组合；在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`）与薄包装 `WorkspacePicker`（继续填 ui-conversation 的 hero slot）；原 `sidebar.workspace` picker slot 与声明感知延迟注册随之删除。
 
 ## Alternatives considered
 
-**保留活动置顶、拖拽仅作临时调整** —— 手动序在下一次 session 活动即被打乱,形同虚设;两种排序权威并存无法向用户解释。也考虑过「拖过一次即冻结该 workspace 的活动置顶」的折中,状态多一档、语义更难讲,直接删除更干净。
+**保留活动置顶、拖拽仅作临时调整**——手动序在下一次会话活动即被打乱，形同虚设；两种排序权威并存无法向用户解释。也考虑过「拖过一次即冻结该 workspace 的活动置顶」的折中，状态多一档、语义更难讲，直接删除更干净。
 
-**排序报文用数字下标** —— `{ index }` 在拖拽窗口期会漂移:host 前插新 session(如 Intent 材料化)后同一下标指向别的行。锚点式 insertBefore 对前插与过滤投影天然免疫。
+**排序报文用数字下标**——`{ index }` 在拖拽窗口期会漂移：host 前插新会话（如 Intent 材料化）后同一下标指向别的行。锚点式 insertBefore 对前插与过滤投影天然免疫。
 
-**drop 后乐观重排** —— client 先行重排需失败回滚,对象层多一块纠缠态;本地/局域网往返毫秒级,等 host 响应的简单方案肉眼无感。顺序权威单一化(完全信 host)后,前端永不发明顺序。
+**drop 后乐观重排**——client 先行重排需失败回滚，对象层多一块纠缠态；本地/局域网往返毫秒级，等 host 响应的简单方案肉眼无感。顺序权威单一化（完全信 host）后，前端永不发明顺序。
 
-**rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态,最终裁定整个浏览区域归 ui-workspace,壳只留几何。
+**rename 对话框留在 ui-sidebar（最小改动）**——正是问题本身：workspace 域的对话框散落在借来的位置里，每加一个（Delete 确认框将至）都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态，最终裁定整个浏览区域归 ui-workspace，壳只留几何。
 
-**WorkSpace 模式按 fork 谱系嵌套 session** —— 嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有 session 拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。
+**WorkSpace 模式按 fork 谱系嵌套会话**——嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有会话拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。
 
 ## Consequences
 
-- 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 契约随之改为手动序措辞。
-- 壳/区域两事实契约把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。
-- 平铺模式不支持排序与分组入口(建到指定 workspace 需切回分组视图),是拍板接受的范围收窄。
-- session Delete 的功能接线与状态枚举扩 wire,留待后续迭代。
+- 手动序是唯一的 workspace 账本序权威：用户排好的顺序不再被活动打乱；代价是「最近活跃浮到最上」的行为消失，活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的协议格式约定随之改为手动序措辞。
+- 壳/区域两事实约定把 workspace 域的后续功能（Delete 确认、跨组移动、Ungrouped 收编）全部收进 ui-workspace 单包；ui-sidebar 不再随会话列表功能演进。
+- 平铺模式不支持重排，也没有在 workspace 中创建会话的入口（建到指定 workspace 需切回分组视图），是拍板接受的范围收窄。
+- 会话 Delete 的功能接线与扩充协议格式中的状态枚举，留待后续迭代。
 
 ## Testing
 
-包级用例覆盖派生(deriveGroups/deriveFlat)、同级 session 行、两处 apply 注册与透传、host 实体移位语义、rename/insertSessionBefore 的 RPC 实现与 fixture 桩；`apps/web` keyless snapshot 回归覆盖装配后的应用，并钉住 fork 后没有 session 展开控件。
+包级用例覆盖派生（deriveGroups/deriveFlat）、同级会话行、两处 apply 注册与透传、host 实体移位语义、rename/insertSessionBefore 的 RPC 实现与 fixture（测试前置数据）桩；`apps/web` keyless 快照回归覆盖装配后的应用，并钉住 fork 后没有会话展开控件。
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
index d8232afa44..5fd9467179 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
 2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166
-2026-07-25-workspace-ui-product-flow.zh.md: a40f374fd794b11bff0de72cbc822fd638cd267c
+2026-07-25-workspace-ui-product-flow.zh.md: 14f33b0eebcf8885670e72cfb6e2c9a87b7a3432
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
index a40f374fd7..14f33b0eeb 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
@@ -1,9 +1,9 @@
 # Agent Note: Workspace UI 完整产品动线
 
-[English](2026-07-25-workspace-ui-product-flow.md) | 中文
-
 Status: implemented
 
+[English](2026-07-25-workspace-ui-product-flow.md) | 中文
+
 ## Problem
 
 [Domain KV storage 与 Workspace entity](../../proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)定义了 Workspace 的持久实体、路径规范和有序 Session 账本，但没有定义 Host 接线、历史数据初始化或 GUI 动线。GUI 同时呈现 Workspace 和 Session；用户进入 New Session 后必须立即输入，即使此时还没有 Host Session，甚至没有 Host Workspace。
@@ -25,11 +25,11 @@ Host 在 Workspace entity 上提供以下 GUI 接线：
 | `session.create({ workspaceId, sessionId? })` | 从 Workspace 解析 cwd，以可选预分配 id 幂等创建 Session 并 attach |
 | `session.create({ cwd })` | 保留给非 Workspace 调用方，创建 Ungrouped Session |
 
-`workspaceRoot` 是独立 Host 配置，未配置时回退到 Host cwd；它与保存 Workspace domain 数据的 `storageRoot` 无关。Host stream 推送 Workspace 与 Session 增量，包括 `host/workspace-removed`；Client 重连后分别刷新 `workspace.list` 与 `session.list` 基线。删除注册记录的所有权与安全边界由 [Workspace 注册记录删除 Agent Note](2026-07-27-workspace-registration-deletion.md)定义。
+`workspaceRoot` 是独立 Host 配置，未配置时回退到 Host cwd；它与保存 Workspace domain 数据的 `storageRoot` 无关。Host 流推送 Workspace 与 Session 增量，包括 `host/workspace-removed`；Client 重连后分别刷新 `workspace.list` 与 `session.list` 基线。删除注册记录的所有权与安全边界由 [Workspace 注册记录删除 Agent Note](2026-07-27-workspace-registration-deletion.md)定义。
 
-Workspace 的 `sessionIds` 是有序候选索引。成员投影同时要求 id 位于索引且对应 `SessionHeader.cwd` canonical 后等于 Workspace path；SessionHeader 不增加 `workspaceId`。cwd 匹配但未入索引的 Session 保持 Ungrouped，索引命中但 header 缺失、cwd 无效或 cwd 不匹配的 id 被过滤。同一 Session 被两个 Workspace 索引占用属于损坏状态并 fail loud。
+Workspace 的 `sessionIds` 是有序候选索引。成员投影同时要求 id 位于索引且对应 `SessionHeader.cwd` canonical 后等于 Workspace path；SessionHeader 不增加 `workspaceId`。cwd 匹配但未入索引的 Session 保持 Ungrouped，索引命中但 header 缺失、cwd 无效或 cwd 不匹配的 id 被过滤。同一 Session 被两个 Workspace 索引占用属于损坏状态并明确报错。
 
-Workspace domain 以 durable marker 区分“从未初始化”和“已初始化但为空”。marker 未设置时，Registry 只调用 `SessionPersistence.list()` 读取 header 元数据，不调用 `load`、`inspect`、history 或解析事件正文；有效 cwd 按 canonical path 分组，组内 Session 与 Workspace 组均按 header `createdAt` 降序初始化。Bootstrap 可重入，最后才写 marker；marker 写入后，绕过 `workspaceId` 的新 Session 不再被自动收编。
+Workspace domain 以 durable marker 区分「从未初始化」和「已初始化但为空」。marker 未设置时，注册表只调用 `SessionPersistence.list()` 读取 header 元数据，既不调用 `load` 或 `inspect`，也不读取历史数据或解析事件正文；有效 cwd 按 canonical path 分组，组内 Session 与 Workspace 组均按 header `createdAt` 降序初始化。Bootstrap 可重入，最后才写 marker；marker 写入后，绕过 `workspaceId` 的新 Session 不再被自动收编。
 
 ### Client 对象模型
 
@@ -56,15 +56,15 @@ Session 自己持有首条输入并驱动一条内部流水线：必要时以预
 
 ### 首次发送与恢复
 
-前端 Session 的 `pendingPrompt` 在 Host 接受消息前始终保留原文。首次发送按 Workspace materialize、Session attach、prompt send 顺序推进：
+前端 Session 的 `pendingPrompt` 在 Host 接受消息前始终保留原文。首次发送按 Workspace materialize、Session attach、提示词发送顺序推进：
 
 1. Workspace 创建失败时，Workspace Intent 保留输入与错误，Session 仍指向该对象。
 2. Session 创建在发布前失败时，Session Intent 回到可编辑状态，以同一预分配 SessionId 重试。
-3. `workspace-attach-failed` 证明 Session 已发布；同一 Session 对象进入真实列表并保留 prompt，后续重试 attach。
-4. prompt 失败时，Session 保留 prompt 并只重试 send，不重复创建 Workspace 或 Session。
-5. Session 创建期间若页面切换到另一个 Intent，旧 Session 即使随后发布也不自动发送；它保留原 prompt 和可见错误。
+3. `workspace-attach-failed` 证明 Session 已发布；同一 Session 对象进入真实列表并保留提示词，后续重试 attach。
+4. 提示词发送失败时，Session 保留提示词并只重试发送，不重复创建 Workspace 或 Session。
+5. Session 创建期间若页面切换到另一个 Intent，旧 Session 即使随后发布也不自动发送；它保留原提示词和可见错误。
 
-RPC lost response、Host frame 先于 completion 和 completion 先于 Host frame 都通过预分配 SessionId 与对象身份收敛。Manager 对 Host view 做有序 upsert，本地 materialize 时优先保留原对象身份，不生成同 id 的临时第二行。
+RPC 响应丢失、Host frame 先于 completion 和 completion 先于 Host frame 都通过预分配 SessionId 与对象身份收敛。Manager 对 Host view 做有序 upsert，本地 materialize 时优先保留原对象身份，不生成同 id 的临时第二行。
 
 ### Sidebar 与排序
 
@@ -72,7 +72,7 @@ Workspace 组严格使用 Host 返回的持久顺序。Bootstrap 一次性确定
 
 组内严格使用 `Workspace.sessionIds`。新 attach 的 Session 放在首位，后续某个 Session 活跃时 Host 只前移该 id 并持久化。Client 不在 Session list 到达后按时间整体重排，因此不会先显示一套 Workspace 顺序再因 hydration 瞬间跳动。
 
-前端 Session Intent 只有在目标是真实 Workspace 时才作为 “New session” 行显示，并临时计入该组 Session 数量；目标是 Workspace Intent 时，Workspace 与 Session 都不进入 sidebar。Intent 发布后由同一预分配 id 对应的真实行接替，刷新后 Intent 行和临时计数一起消失。搜索模式不保存或筛选 Intent 行。
+前端 Session Intent 只有在目标是真实 Workspace 时才作为 「New session」 行显示，并临时计入该组 Session 数量；目标是 Workspace Intent 时，Workspace 与 Session 都不进入 sidebar。Intent 发布后由同一预分配 id 对应的真实行接替，刷新后 Intent 行和临时计数一起消失。搜索模式不保存或筛选 Intent 行。
 
 无法归入任何 Workspace 的真实 Session 进入 Ungrouped。Host `session-added` 与 `workspace-changed` 可以任意顺序到达，列表合并不依赖 frame 顺序。
 
@@ -80,19 +80,19 @@ Workspace 组严格使用 Host 返回的持久顺序。Bootstrap 一次性确定
 
 ### React 与 slot 边界
 
-React 组件只消费 `useSessions`、`useWorkspaces` 与 session-scoped hooks，不拥有实体生命周期。Zustand store 只保留布局、当前 view、普通真实 Session 的 composer 文本和其他纯呈现状态；Session/Workspace Intent、materialize phase、错误和 retained prompt 位于 React-free runtime 对象层。
+React 组件只消费 `useSessions`、`useWorkspaces` 与 session-scoped 钩子，不拥有实体生命周期。Zustand store 只保留布局、当前 view、普通真实 Session 的 composer 文本和其他纯呈现状态；Session/Workspace Intent、materialize phase、错误和 retained prompt 位于 React-free 运行时对象层。
 
-Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` seam；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host event 只由 Host mutation 与 stream adapter 产生。
+Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` seam；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host 事件只由 Host mutation 与流适配器产生。
 
 ## Alternatives considered
 
 **为待创建 Workspace 与 Session 保存独立页面记录。** 该方案在 materialize 后需要替换身份并转交输入、错误、焦点和 sidebar 行；对象自身的 Intent 状态可以保持身份连续。
 
-**由呈现层或 root Zustand store 编排对象生命周期。** 该方案会重复 Manager/Service 的职责，并把领域状态带回 React。标准化动作由 runtime service 提供，slot 只注入呈现所需的窄接口。
+**由呈现层或 root Zustand store 编排对象生命周期。** 该方案会重复 Manager 与服务的职责，并把领域状态带回 React。标准化动作由 runtime service 提供，slot 只注入呈现所需的窄接口。
 
-**零态立即创建 Host Session 或 Host persistence intent。** 未输入页面会进入 Host 生命周期，并改变刷新语义；前端 Session 在首次发送前只保留 page-local Intent。
+**零态立即创建 Host Session 或 Host 持久化 Intent。** 未输入页面会进入 Host 生命周期，并改变刷新语义；前端 Session 在首次发送前只保留 page-local Intent。
 
-**显式 Create Workspace 延迟到首次发送。** 用户确认后 sidebar 仍看不到真实空 Workspace，“创建 Workspace”与“准备 Session”语义混合；只有系统自动产生的零 Workspace Intent 延迟 materialize。
+**显式 Create Workspace 延迟到首次发送。** 用户确认后 sidebar 仍看不到真实空 Workspace，「创建 Workspace」与「准备 Session」语义混合；只有系统自动产生的零 Workspace Intent 延迟 materialize。
 
 **持续按 cwd 动态派生 Workspace。** 该方案无法表达空 Workspace、稳定显示名和显式顺序，也会自动收编非 Workspace 调用方；cwd 只用于一次历史 bootstrap 与成员双向校验。
 
@@ -104,7 +104,7 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe
 
 - 完全无 Workspace 的零态不写 Host 且允许输入；显式 Create Workspace 立即创建并显示空 Workspace。
 - 前端 Session 与 Workspace 在 materialize 前后保持对象身份，输入、错误、焦点和 sidebar 投影始终来自对象层。
-- 首发按 Workspace、Session、prompt 顺序推进，各成功阶段不回滚，输入在 prompt 接受前不丢失，创建重试使用同一 SessionId。
+- 首发按 Workspace、Session、提示词顺序推进，各成功阶段不回滚，输入在提示词被接受前不丢失，创建重试使用同一 SessionId。
 - Workspace list 只读取 header 完成一次可重入 bootstrap；initialized 的空 registry 重启不重复初始化，成员读取同时校验索引与 canonical cwd。
 - 初始默认目标只在两份基线 ready 后确定一次；Workspace 组不因 hydration 或 Session 活跃整体重排，单个活跃 Session 只前移自身。
 - 真实 Workspace 下的前端 Session 临时计入 sidebar 数量，Workspace Intent 保持隐藏，发布与刷新都不会留下重复行或重复计数。
@@ -116,6 +116,6 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe
 
 - SessionHeader 不记录最后活跃时间，历史 bootstrap 只能按 `createdAt` 初始化；此后由真实 Session 活跃事件逐项前移。
 - 历史 cwd 缺失、目录无效或 realpath 失败的 Session 留在 Ungrouped；本期没有手动收编入口。
-- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 契约。
+- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 约定。
 - 显式 Create Workspace 立即落盘，用户不发送就离开也会留下空 Workspace。
 - Host Session 在首个事件前仍遵循现有懒持久化语义；前端 Intent 不改变 Host 重启后的空 Session 行为。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 8a92dd2fd1..43076fbfe4 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
 2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: 26b7081e7b4e3688a46a2857da91ba45328532a9
+2026-07-26-todo-parallel-in-progress.zh.md: 64047e8b27e779e6ca23ea6c435bcdfecf38066d
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 26b7081e7b..64047e8b27 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 把单一 `in_progress` 上限从固定规则改为部署策略，并要求每个组合都作出选择：
 
-- `packages/todo/tool-todo/src/index.ts` 新增必填的 `Config.allowParallelInProgress` 字段。为 `true` 时，`execute` 接受任意数量的活跃条目，描述指示模型把每个正在处理的任务标记为 `in_progress`（并行工作时可以有多个，顺序工作时只有一个），并在仍有工作未完成时至少保留一个；为 `false` 时，描述要求恰好一个，`execute` 拒绝标记更多的调用。
+- `packages/todo/tool-todo/src/index.ts` 新增必填的 `Config.allowParallelInProgress` 字段。为 `true` 时，`execute` 接受任意数量的活跃条目，描述指示模型把每个正在处理的任务标记为 `in_progress`（并行工作时可以有多个，顺序工作时只有一个），并在仍有工作未完成时至少保留一个；为 `false` 时，描述要求恰好一个，`execute` 拒绝标记多个活跃条目的调用。
 - `packages/todo/tool-todo/src/invariant.ts` 中的持久日志不变式不再拒绝含多个活跃条目的快照，且不跟随该配置，因此此前持久化的日志不受影响，并行快照在任一策略下都能干净回放。
 
 其余编码的不变式保持不变：`content` 去除首尾空白后非空且唯一、status 为合法枚举值。本决定取代[原始设计的校验决策](2026-06-29-todo-write-tool.md)中「至多一个活跃」的条款；该 Agent Note 的其余部分（整列表替换、日志支撑的状态、单一所有者）依然成立。
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 该策略是部署层的选择
 
-并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况——但一个部署的 agent 是否会并发展开工作，在组装期就是可知的。因此该策略是必填的 `Config` 字段，而非常量或默认值：每个 cordis.yml 组合都会有意设置 `allowParallelInProgress`，为可能并行展开工作的 agent 选择 `true`，或为单活跃项纪律选择 `false`。
+并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况——但一个部署的 agent（智能体）是否会并发展开工作，在组装期就是可知的。因此该策略是必填的 `Config` 字段，而非常量或默认值：每个 cordis.yml 组合都会有意设置 `allowParallelInProgress`，为可能并行展开工作的 agent 选择 `true`，或为单活跃项纪律选择 `false`。
 
 该开关会同时改变面向模型的指令与接受的输入。把两者拆开才是 bug：描述要求只保留一个活跃任务、而 `execute` 却接受多个，等于教给模型一条工具并不遵守的规则；反过来则会拒绝描述所邀请的调用。描述中只有活跃状态那一句会变化，因为这是该策略唯一改变的指令。
 
@@ -37,18 +37,18 @@ Status: implemented
 
 ## 展示面是本次改动的一部分
 
-解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR 的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
+解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR（Pull Request）的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
-`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的槽位；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
+`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的slot；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
 
-`summarySuffix` 是 `ToolRow` 上的槽位，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
+`summarySuffix` 是 `ToolRow` 上的slot，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
 
 ## 暂缓项
 
-两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试契约的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
 
 ## 后果
 
-现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照 sidecar。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Note 先前记过的两次点时刻计数都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些 sidecar —— 包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖 —— `pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture 的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP `todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
+现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照伴随文件。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Agent Note 先前记过的两次时点统计都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些伴随文件——包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖——`pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture（测试前置数据）的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP（Agent Client Protocol）`todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
index dade9b5d90..3d0e167856 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md
 2026-07-27-native-workspace-directory-picker.md: a36f7b239a9115fe5eb33472ec5084818a66e9f2
-2026-07-27-native-workspace-directory-picker.zh.md: bb3e2fc6f7c77c8ace97e53435297326f937e4e8
+2026-07-27-native-workspace-directory-picker.zh.md: e45d45a95b27b19d573d6bd709357d08a2e2f3fc
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
index bb3e2fc6f7..e45d45a95b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 工作区管理器必须在选择回调运行前插入或更新返回的工作区。因此，新纳入的目录会立即显示其 basename。再次打开已注册的路径时，则保留该工作区现有的标题。
 
-## 交互契约
+## 交互约定
 
 - 在 macOS、Windows 和 Linux 上，选择器一次只允许选择一个目录。
 - 取消系统对话框不会显示提示，并返回 `null`。
@@ -27,7 +27,7 @@ Status: implemented
 
 只有来自回环套接字、且携带同源浏览器元数据的请求才能调用原生对话框 RPC。该 RPC 不使用默认的 30 秒请求超时，因为系统对话框可能无限期保持打开；调用方中止或连接中止仍会传递至平台进程。
 
-平台适配器不经 shell 打开对话框——POSIX 上 spawn 原生工具，Windows 上是子进程 COM 会话：
+平台适配器不经 shell 打开对话框——POSIX 上 spawn 原生工具，Windows 上进行进程内 COM 交互：
 
 - macOS：`osascript` 和系统文件夹选择器。
 - Windows：koffi `IFileOpenDialog` 子进程，使用宿主接受的最佳线程 DPI 感知（可用时为 per-monitor-v2；不支持 PMv2 的主机级联到 per-monitor 或 system-aware）（见[进程内对话框 Note](2026-08-02-win32-in-process-folder-dialog.md)）；该层无回退——失败原样上报（见[PowerShell 链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
index b0e6012183..551a34b48f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md
 2026-07-27-skill-catalog-hot-refresh.md: 43c2da75aeb0031dffb5f47d7e76805baa2920e5
-2026-07-27-skill-catalog-hot-refresh.zh.md: 04d39dd767e5438c57d3eb29523a8ff26592465c
+2026-07-27-skill-catalog-hot-refresh.zh.md: 60b08cd7b82dfe4edc5f8136d756df2c9097b3fe
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
index 04d39dd767..60b08cd7b8 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
@@ -12,13 +12,13 @@ skill（技能）摘要是模型的路由输入，但本地 skill 可在会话
 
 ## 决策
 
-skill 服务将目录成员关系与指令正文加载分离。`ctx.skills.snapshot()` 返回摘要及一个完整性位。`ctx.skills.registerProvider(factory)` 会向同步工厂提供一项注册作用域内的 `{ signal, invalidate }` 控制能力：`invalidate()` 只会将该精确活动注册标记为脏，并丢弃已完成目录缓存；注册失败或释放时，信号会中止。提供方返回的数组是完整发现的简写形式；显式的不完整观测可以保留可读候选项供直接加载，但不能缓存，也不能作为面向模型消费方的权威结果。在发现期间，如果提供方或运行时 generation 发生变化，系统会重试一次；如果这次重试也被后续修订取代，则最新候选项会作为不完整且不缓存的观测返回。资源释放或替换后的延迟失效操作不会执行任何操作，因为该能力已被撤销。
+skill 能力将目录成员关系与指令正文加载分离。`ctx.skills.snapshot()` 返回摘要及一个完整性位。`ctx.skills.registerProvider(factory)` 会向同步工厂提供一项注册作用域内的 `{ signal, invalidate }` 控制能力：`invalidate()` 只会将该精确活动注册标记为脏，并丢弃已完成目录缓存；注册失败或 dispose（资源释放）时，信号会中止。提供方返回的数组是完整发现的简写形式；显式的不完整观测可以保留可读候选项供直接加载，但不能缓存，也不能作为面向模型消费方的权威结果。在发现期间，如果提供方或运行时 generation 发生变化，系统会重试一次；如果这次重试也被后续修订取代，则最新候选项会作为不完整且不缓存的观测返回。dispose 或替换后的延迟失效操作不会执行任何操作，因为该能力已被撤销。
 
 `@deepseek-ai/dsh-skill-local` 直接依赖 Chokidar，并观察与目录相关的宿主路径。已有根目录会监视其直属 skill bundle 目录、平铺的 Markdown 条目和直属 `SKILL.md` 条目文件。新增、移除和目录变更会使成员关系失效；文件变更还支持刷新 frontmatter 中的 `name` 和 `description`。bundle 内更深层的资源文件会被忽略。同一微任务批次中的事件会合并为一次失效。项目 watcher 使用有界集合，并按最久未观察顺序淘汰。
 
 系统从缺失根目录最近的现有祖先开始，使用 `fs.watchFile` 每次跟进一层缺失路径片段；真实根目录出现后，再交给 Chokidar。每次发现操作都会在扫描前重新探测所保留的根目录／祖先模式。即使子项移除在根目录 `unlinkDir` 事件之前就触发失效并发布权威空目录，或者该事件根本没有到达，这项独立探测也会在删除后重新建立祖先观察。Chokidar 配置公开原生事件或轮询模式、写入稳定性、轮询间隔、符号链接跟随选项和项目 watcher 容量。第一方 `write` 和 `edit` 工具观察会同步使相关提供方失效，因此下一个模型步骤无需等待宿主事件投递，就能看到自身改动。watcher 启动或运行失败会被记录并触发重试；发现过程仍会返回可读候选项供直接加载，但会报告不完整观测。资源销毁会关闭 watcher，并忽略延迟回调。
 
-`@deepseek-ai/dsh-tool-skill` 在首次观察到非空完整目录且返回 enter 的 `agent/pre-step` 中，贡献一条带来源的 `UserMessage`。每次 pre-step，它都会应用 `skill` 工具的精确可见性，对 `<available_skills>` 标签之间精确渲染的文本计算哈希，并从后向前扫描只读会话事件且不复制，以查找该插件发布的最新一条可识别且仍可见的目录。digest 变化时，插件会向 enter 决策贡献完整替换目录；所有 skill 消失时也包含显式空目录，reject 或监听器失败则不记录任何内容。如果没有目录仍然可见，但历史事件中存在可识别目录，则说明压缩（compaction）已将其遮蔽，下一次完整且进入步骤的观察会重新建立当前目录，包括空 tombstone。如果当前目录为空且历史上从未发布目录，则不发送任何内容；不完整快照则保留最后一次完整的模型视图。反向扫描通常在最新且仍可见的目录处停止；当压缩遮蔽所有目录时，它会以一次 O(session-events) 扫描的成本确认这一事实。
+`@deepseek-ai/dsh-tool-skill` 在首次观察到非空完整目录且返回 enter 的 `agent/pre-step` 中，贡献一条带来源的 `UserMessage`。每次 pre-step，它都会应用 `skill` 工具的精确可见性，对 `<available_skills>` 标签之间精确渲染的文本计算哈希，并从后向前扫描只读会话事件且不复制，以查找该插件发布的最新一条可识别且仍可见的目录。digest 变化时，插件会向 enter 决策贡献完整替换目录；所有 skill 消失时也包含显式空目录，reject 或监听器失败则不记录任何内容。如果没有目录仍然可见，但历史事件中存在可识别目录，则说明压缩（compaction）已将其遮蔽，下一次进入步骤时的完整观测会重新建立当前目录，包括空 tombstone。如果当前目录为空且历史上从未发布目录，则不发送任何内容；不完整快照则保留最后一次完整的模型视图。反向扫描通常在最新且仍可见的目录处停止；当压缩遮蔽所有目录时，它会以一次 O(session-events) 扫描的成本确认这一事实。
 
 TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills/change` 不携带 diff；TUI 会为活动会话的 cwd 重新获取 `snapshot()`，仅应用最新的完整结果，并在观测不完整时保留先前命令。完整的空结果会清除陈旧补全项。pi-tui 在其提供方被替换时会关闭自动补全，因此如果目录在用户输入斜杠命令名称期间到达，还会触发一次仅用于更新建议的当前草稿重查。
 
@@ -33,10 +33,10 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - **将实时目录放入 World State**：不予采纳，因为目录替换是模型可见的会话输入，必须能够从事件日志重建。持久注入历史已经提供回放、恢复、fork 和压缩语义，无需再引入一套可变状态层。
 - **只依赖 `fs/observed`**：不予采纳，因为 IDE、Git、shell 命令和外部进程都不会经过该 seam。该事件仍作为第一方工具的低延迟快速路径，宿主监视则补齐覆盖。
 - **为每个 `SKILL.md` 正文计算哈希或版本**：不予采纳，因为模型最初只看到名称和描述，提供方已经在每次工具调用时重新读取正文。正文修订会产生目录流量，却不会改变路由，也不足以成为改写历史工具结果的理由。
-- **监视每个 bundle 资源**：不予采纳，因为参考资料、脚本和产物都是按需加载的，不影响类别列表。宽泛的递归监视会增加失效、描述符压力和平台差异，却不能改善路由。
+- **监视每个 bundle 资源**：不予采纳，因为参考资料、脚本和资源都是按需加载的，不影响类别列表。宽泛的递归监视会增加失效、描述符压力和平台差异，却不能改善路由。
 - **将部分发现或失败发现发布为新目录**：不予采纳，因为暂时读取失败不能证明文件已删除。完整性位让面向模型的消费方保留最后一次完整目录，直到完整观察成功。
-- **保留公开的 `invalidateProvider(provider)`**：不予采纳，因为这会公开一项注册表变更方法，并要求调用方重复提供注册表已经持有的身份。发给工厂的闭包会将失效绑定到单个注册，并在释放后失去作用，因此观察方既不需要访问注册表，也不需要提供方身份。
-- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务契约。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
+- **保留公开的 `invalidateProvider(provider)`**：不予采纳，因为这会公开一项注册表变更方法，并要求调用方重复提供注册表已经持有的身份。发给工厂的闭包会将失效绑定到单个注册，并在 dispose 后失去作用，因此观察方既不需要访问注册表，也不需要提供方身份。
+- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务约定。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
 
 ## 影响
 
@@ -44,5 +44,5 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - TUI 的 `/skill:` 补全会收敛到同一份完整目录，而不会让每次按键都阻塞于发现；打开的斜杠命令名称草稿会在目录到达时刷新。
 - 目录消息采用仅追加、日志记录和全量列表快照。它们会保留较早的可重用 token；替换目录会显式停用陈旧名称，每次 digest 实际变化时，token 成本与当前目录大小成正比。
 - 仅修改正文不会产生目录消息。后续工具调用会看到当前内容，而先前工具结果仍准确记录模型之前加载的内容。
-- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁契约会限制这些成本。
+- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁约定会限制这些成本。
 - 远程或未来的可变提供方会保留各自注册作用域内的失效闭包，并通过自身观察机制调用它；注册表不会强制采用通用 watcher 或 TTL。
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
index 71c2325bb3..ba3cd5180e 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
 2026-07-27-trajectory-inspection-ledger.md: e3fc22234c1df449c99eac90af27de7da0b6f202
-2026-07-27-trajectory-inspection-ledger.zh.md: abf8fd3bcaeabba6061bd415acbe8ddefef7ac79
+2026-07-27-trajectory-inspection-ledger.zh.md: 736523ebb02b8ea3c6e4cdbf9bc27f67779c7426
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
index abf8fd3bca..736523ebb0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：轨迹检查记录表
+# Agent Note: 轨迹检查记录表
 
 Status: implemented
 
@@ -16,13 +16,13 @@ Status: implemented
 - 事件类型与内容构成两个稳定列。角色标签朝内容侧对齐，嵌套子工具略微缩进，内容预览使用 CSS 截断以适应可用宽度。token 用量和耗时留在检查器中。
 - 产品正文使用现有无衬线字体栈。轮次 id、token 数、耗时、工具调用、原始载荷和其他机器数据使用现有代码字体栈。
 - 现有主题 token 同时负责亮色和暗色渲染。中性边框与表面构成整体结构；区分度较低的角色色帮助扫读而不表达成功或失败语义，业务蓝色则标识选择状态、链接和焦点。
-- 客户端 runtime 提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费者承担这些结构。
-- 普通生成调用与压缩调用形成一条按时间排序的请求投影，以 purpose 区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
+- 客户端运行时提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费方承担这些结构。
+- 普通生成调用与压缩调用形成一条按时间排序的请求投影，以用途区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
 - 调用 schema 来自当前生效且已记录的请求头。无密钥快照 fixture（测试前置数据）有意将该目录替换为非数组 token `{{tools}}`，持久化检查边界会将其视为不可用，而不是尝试投影或虚构 schema。
-- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概览区域随实体类型变化：Markdown 消息提供渲染、源码、来源和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
-- 折叠轮次时保留其第一条记录，将后续行替换为紧凑的步骤和工具调用数量；折叠助手时对其工具调用后代应用相同交互。全局控件可以分别折叠或展开这两个层级。
+- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概述区域随实体类型变化：Markdown 消息提供渲染、源码、来源和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
+- 折叠轮次时保留其第一条记录，将后续行替换为紧凑的步骤数和工具调用数；折叠助手时对其工具调用后代应用相同交互。全局控件可同时折叠或展开这两个层级。
 - 长记录表初始时将已加载尾部置于底部，只挂载视口对应的行窗口及有界的额外缓冲行。仅含请求的分隔行并入下一个具备可测高度的虚拟项，末尾分隔行则保留固定留白，因此虚拟化器不会管理零高度项。可安全用于 DOM 的语义行键与 ARIA 索引使标识不依赖挂载位置。只要已知尾部之前仍有更早历史，即使当前已加载投影低于常规行数阈值，也会立即启用虚拟化。基于稳定键的虚拟化器锚定会在向前补页和尾部追加时保留当前可见项；只有分页完成导致虚拟化停用时，才使用手动滚动高度兜底。选择、时间线聚焦、折叠、搜索和末尾跟随均按稳定的事件或工具调用标识定位，不要求对应 DOM 行已存在。初始定位完成前以及更早页面仍在等待时，明确的加载行会遮住真实记录。原始窗口的基准序号即使在一页未增加任何 surface 可见节点时，也能检测到这次向前补页。
-- 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 `startedAt` 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间相交的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
+- 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 `startedAt` 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间任一边界重叠的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
 - 实时历史更新仅在用户已经跟随记录表末尾时保留底部位置。向上滚动会清除跟随状态，因此流式分块和新追加的记录不会打断对旧记录的检查。末尾跟随与虚拟化器测量仅响应行键和高度，而非内容标识，因此仅含文本的流式帧既不会丢弃测量缓存，也不会重复执行 DOM 滚动写入。
 - token 流式输出会复用已完成历史的检查结果、布局、请求编号、Overview 投影和搜索结果。每个帧只追加当前未完成助手的单元格，并在查询处于激活状态时搜索这部分内容；文本与推理（reasoning）增量不会重新折叠或扫描已加载前缀，而消息完成、工具生命周期、压缩、`rewrite` 及其他结构事件会重建受影响的投影。在这些投影重建前，检查记录表会丢弃已完成步骤中没有任何投影读取的 token 载荷，但会保留首个可见 token 用于计时、保留所有用量分片用于核算，并保留未完成或中断步骤的所有分片；独立历史数据源仍保留原始条目。
 - 历史折叠只把已加载的 surface 事件重新编号为紧凑连续的输入并交给规范 surface manager，再将其节点映射回会话绝对序号。因此，结构事件会保留规范的替换校验，而无需重放 token 分片，也不会为未加载的序号实体化合成事件。
@@ -45,7 +45,7 @@ Status: implemented
 
 **复用全局 Chat 详情栏。** 不予采纳：这会让局部检查与会话导航耦合，还会使行点击意外改变另一个视图的状态。
 
-**由 Trajectory CSS 覆盖 composer seat。** 不予采纳：跨包（package）选择器会依赖生成类选择器的优先级和样式表顺序。显式视图标记让 seat 几何形状和活跃阶段优先级留在 `ConversationRoot` 中，而 Trajectory 只负责自身内部的避让空间。
+**由 Trajectory CSS 覆盖 composer seat。** 不予采纳：跨包选择器会依赖生成类选择器的优先级和样式表顺序。显式视图标记让 seat 几何形状和活跃阶段优先级留在 `ConversationRoot` 中，而 Trajectory 只负责自身内部的避让空间。
 
 **将计时保留在独立的 waterfall 标签页中。** 不予采纳：占位实现汇总的是节点数而非记录计时，并迫使用户离开想要聚焦的记录。保留完整时间范围的 Overview 区域让计时和筛选后的记录处于同一视觉上下文中。
 
@@ -53,4 +53,4 @@ Status: implemented
 
 ## 后果
 
-轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表契约锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
+轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
index 5268ea62f9..228ee9daab 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md
 2026-07-27-web-session-fork-actions.md: 578e59ec92e003fe5c8cdfe951a595f3a7371ecf
-2026-07-27-web-session-fork-actions.zh.md: d90124f6e6e164b0a1e0fce734f52976630cd848
+2026-07-27-web-session-fork-actions.zh.md: 30c6fbbe7930ab17ca707d8a8fa0d4fc288d150e
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
index d90124f6e6..30c6fbbe79 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web session fork 操作
+# Agent Note: Web 会话 fork 操作
 
 Status: implemented
 
@@ -6,30 +6,30 @@ Status: implemented
 
 ## Problem
 
-Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互契约。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
+会话存储已提供按已完成轮次前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互约定。会话行菜单只能表达「从最新已完成轮次分支」，消息 IconActions 还需要表达「从这条消息所在轮次分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
 
 ## Decision
 
 本决策中的消息资格部分由[已完成轮次尾部决策](../bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)收紧；共享运行时操作、注入归属、标题处理和同级列表决策仍然有效。
 
-Web 的 session 行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。Session 行传 `{ sessionId, increaseTitle: true }`，因此在源会话最后一个已完成轮次处分支；符合条件且位于已完成轮次尾部的消息传 `{ sessionId, atSeq: node.seq, increaseTitle: true }`，因此在以该消息结束的轮次处分支。`increaseTitle` 只由 client 消费：子会话进入本地列表后，client 把源会话持久化标题尾部的 `(N)` 或 `（N）` 递增并保留括号样式，无编号时追加 ` (1)`，没有持久化标题时不改名；Host fork 请求仍只有 `sessionId` 与可选的 `atSeq`。改名成功后调用方才打开子会话；fork 或改名失败时保持源会话与当前选择不变，改名失败时已创建的子会话仍留在列表中。
+Web 的会话行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。会话行传 `{ sessionId, increaseTitle: true }`，因此在源会话最后一个已完成轮次处分支；符合条件且位于已完成轮次尾部的消息传 `{ sessionId, atSeq: node.seq, increaseTitle: true }`，因此在以该消息结束的轮次处分支。`increaseTitle` 只由 client 消费：子会话进入本地列表后，client 把源会话持久化标题尾部的 `(N)` 或 `（N）` 递增并保留括号样式，无编号时追加 ` (1)`，没有持久化标题时不改名；Host fork 请求仍只有 `sessionId` 与可选的 `atSeq`。改名成功后调用方才打开子会话；fork 或改名失败时保持源会话与当前选择不变，改名失败时已创建的子会话仍留在列表中。
 
-`forkAt(seq)` 只在 ui-conversation 的 apply 注入层接触 session 服务，消息组件只回传事件 `seq`。Session 行同理只通过 ui-workspace 的注入回调发起操作；两个呈现包都不持有 session mutation 状态，也不复制 host 的边界求值。
+`forkAt(seq)` 只在 ui-conversation 的 apply 注入层接触会话服务，消息组件只回传事件 `seq`。会话行同理只通过 ui-workspace 的注入回调发起操作；两个呈现包都不持有 session mutation 状态，也不复制 host 的边界求值。
 
-Session lineage 不投影成列表层级。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序把源会话与所有 fork 子会话显示为同级行，每行都可独立打开、搜索和拖拽；In one list 模式继续按 `updatedAt` 严格排序；Ungrouped 组在没有 workspace 账本时也按 recency 排序。`parentId` 仍用于 lineage 和后续查询，但不控制 session 列表可见性。
+会话 lineage 不投影成列表层级。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序把源会话与所有 fork 子会话显示为同级行，每行都可独立打开、搜索和拖拽；In one list 模式继续按 `updatedAt` 严格排序；Ungrouped 组在没有 workspace 账本时也按 recency 排序。`parentId` 仍用于 lineage 和后续查询，但不控制 session 列表可见性。
 
 ## Alternatives considered
 
-**只接 session 行菜单。** 否决：用户在消息处已经选择了更精确的上下文，强迫其回到列表只能退化为最新完成轮，且已展示的消息分支图标会成为无响应控件。
+**只接会话行菜单。** 否决：用户在消息处已经选择了更精确的上下文，强迫其回到列表只能退化为最新已完成轮次，且已展示的消息分支图标会成为无响应控件。
 
-**只允许用户消息分支。** 否决：已定稿 assistant 内容同样有稳定事件 `seq`，host 会把它归入所属完成轮；让两个外观相同的分支按钮只有一个可用会制造不可见的行为差异。
+**只允许用户消息分支。** 否决：已定稿 assistant 内容同样有稳定事件 `seq`，host 会把它归入所属已完成轮次；让两个外观相同的分支按钮只有一个可用会制造不可见的行为差异。
 
 **按 `parentId` 把 fork 子会话嵌套在源会话下。** 否决：lineage 不是导航所有权；嵌套要求自动展开祖先才能看见当前项，并让子会话无法参与 workspace 的同级手动排序。
 
-**由消息组件直接调用 session 服务。** 否决：client 组件不得接触 `ctx` 或业务服务；注入回调让 mutation 留在 apply 世界，组件保持纯 props。
+**由消息组件直接调用会话服务。** 否决：client 组件不得接触 `ctx` 或业务服务；注入回调让 mutation 留在 apply 世界，组件完全由 props 驱动。
 
 ## Consequences
 
-用户可从 session 行或符合条件的已完成轮次尾部消息创建分支，两处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新完成轮」快捷语义。连续 fork 的标题按 `(1)`、`(2)` 递增，而不是重复追加 `(1)`；全角括号标题保持全角样式。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。
+用户可从会话行或符合条件的已完成轮次尾部消息创建分支，两处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新已完成轮次」快捷语义。连续 fork 的标题按 `(1)`、`(2)` 递增，而不是重复追加 `(1)`；全角括号标题保持全角样式。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。
 
-Fork 与子会话改名失败都保持静默并保留源选择，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。包级测试固定符合条件的消息 `seq` 转发、标题递增与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。
+Fork 与子会话改名失败都保持静默并保留源会话的选中状态，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。包级测试固定符合条件的消息 `seq` 转发、标题递增与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
index 7701e5fcc7..d41e205703 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-session-search.md
 2026-07-27-web-session-search.md: 4c49c0e61ca1b15181e767e4f65353312f8a3e3f
-2026-07-27-web-session-search.zh.md: e9aa00656443e544bad623540d07ff785b1285ef
+2026-07-27-web-session-search.zh.md: 7f4cc9caf9738700ed5f24b3d0593f08d06117ac
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
index e9aa006564..7f4cc9caf9 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
@@ -10,17 +10,17 @@ Web 侧边栏会展示会话标题及其 Workspace 归属，但无法根据只
 
 ## 决策
 
-Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者契约，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
+Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者约定，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
 
 宿主网关通过现有的类型化 RPC 栈公开 `session.search`。它根据 `session.list` 使用的同一组可见摘要推导授权集合，向 `ctx.sessionQuery.searchSessions` 请求全局排序后的当前 surface `user/message` 和 `assistant/message` 匹配项，并持续消费提供方分页，直到获得 20 个已授权会话及一个前瞻项，或结果流耗尽。首个提供方页面请求 20 个命中；如果第一页返回 `SESSION_QUERY_INVALID_LIMIT`，页面大小会依次折半为 10、5、2、1，并在续传和陈旧世代重启中沿用探测所得的大小。每个命中的会话 id、最佳匹配会话 id、surface 和事件类型都会经过重新校验，其 snippet 才能离开宿主。发出的 snippet 最多包含 240 个 Unicode 码点；宿主与传输 schema 共用协议边界及码点安全的截断辅助函数，而传输 schema 会在客户端解析时独立强制执行 snippet 上限。将可能很大的授权集合排除在 SQLite 绑定之外，可避开可移植变量上限，同时保持全局排序。响应仍只有一个有界页面；`hasMore` 会指示 UI 提示用户缩小查询范围，而不是公开分页能力。陈旧的续传会丢弃当前尝试的部分结果、去重条目和游标，然后依据原始可见性快照从第一页重新开始。上限探测与陈旧重试共用 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果某页命中数超过其请求的上限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体信号会取消已被取代的工作，包括持久化列表枚举、分批受限执行的冷会话元数据 stat，以及每一次提供方调用；即使同时收到上限拒绝或陈旧拒绝，也以取消为准。查询服务缺失或索引／查询故障无法恢复时，仍作为业务错误处理，不会修改规范会话存储。
 
 [`WorkspaceBrowser`](../../../../packages/client/ui-workspace/README.md) 有意将元数据搜索与内容搜索保持独立。其默认界面文案为英文；输入框及防御性请求路径会移除 NUL，将查询限制在请求 schema 规定的 500 个 UTF-16 code unit 内且不会拆分 surrogate pair。非空白查询会立即从会话列表中计算不区分大小写的标题和 Workspace 子串匹配，在 250 ms 防抖后发起内容请求，在查询变化时中止前一请求，并忽略陈旧的完成结果。它先按新近程度排列本地匹配，再合并由后端排序且仅匹配内容的结果，按会话 id 去重；无论常规分组模式如何，最终都渲染为扁平列表。每一行显示标题、Workspace，并在存在时显示一行摘要片段。选择某一行只会打开对应会话，并保留查询条件；不会跳转至确切事件。
 
-结果上限是单一协议常量，而非逐连接状态。`SESSION_SEARCH_RESULT_LIMIT` 位于 `dsh-host-apiproxy` 中强制执行它的响应 schema 旁边，`SessionsService.searchResultLimit` 则把该常量重新公开给呈现插件。功能包要取用它，必须显式扩展 sessions 域的对外面：`ISessions`（即注入为 `ctx.sessions` 的那个面，也因此是测试运行时的 sessions 替身必须实现的面）在该上限旁声明了搜索动作。连接 handle 不携带它：逐连接字段会暗示该上限随传输层变化或由服务端协商，而 schema 固定的 `max` 恰恰禁止这一点，并且会让同一事实在同一模块内拥有两处归属。
+结果上限是单一协议常量，而非逐连接状态。`SESSION_SEARCH_RESULT_LIMIT` 位于 `dsh-host-apiproxy` 中强制执行它的响应 schema 旁边，`SessionsService.searchResultLimit` 则把该常量重新公开给呈现插件。功能要取用它，必须显式扩展 sessions 域的对外面：`ISessions`（即注入为 `ctx.sessions` 的那个面，也因此是测试运行时的 sessions 替身必须实现的面）在该上限旁声明了搜索动作。连接 handle 不携带它：逐连接字段会暗示该上限随传输层变化或由服务端协商，而 schema 固定的 `max` 恰恰禁止这一点，并且会让同一事实在同一模块内拥有两处归属。
 
-内容匹配沿用 SQLite 后端经过规范化的字面 token／短语语义。共享语义投影会排除推理（reasoning）块，因此 UI 搜索绝不会将模型的私有推理作为命中或 snippet 返回；派生索引的 schema 版本会随之前进，使现有持久化索引重建并移除先前的这些文档。FTS5 运算符只作为数据处理，此搜索界面不提供拼写错误纠正、模糊匹配、前缀匹配或任意子串扩展。特别是，`unicode61` 分词器可能将一段连续中文视作单个 token，因此不保证 `搜索` 之类的较短查询能匹配 `会话搜索功能` 的内部片段。标题与 Workspace 匹配仍采用普通的客户端子串匹配。
+内容匹配沿用 SQLite 后端经过规范化的字面 token／短语语义。共享语义投影会排除推理（reasoning）块，因此 UI 搜索绝不会将模型的私有推理作为命中或 snippet 返回；派生索引的 schema 版本会递增，使现有持久化索引重建并移除先前的这些文档。FTS5 运算符只作为数据处理，此搜索界面不提供拼写错误纠正、模糊匹配、前缀匹配或任意子串扩展。特别是，`unicode61` 分词器可能将一段连续中文视作单个 token，因此不保证 `搜索` 之类的较短查询能匹配 `会话搜索功能` 的内部片段。标题与 Workspace 匹配仍采用普通的客户端子串匹配。
 
-## 故障与可见性契约
+## 故障与可见性约定
 
 搜索绝不会扩大会话可见范围：没有可供服务的 cwd 的冷会话会被排除，原因与它们不出现在 `session.list` 中相同；只有 id 位于这条基线中的提供方命中才能离开宿主。被遮蔽事件和纯日志事件、消息内容之外的工具事件、错误、待办事项及其他追踪记录都不会产生 UI 命中结果。
 
@@ -29,8 +29,8 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 ## 曾考虑的替代方案
 
 - **在浏览器中扫描每个会话的历史记录**：不予采纳，因为这会让 UI 承担传输与折叠开销；除非加载冷态日志，否则还会漏掉这些日志；并会重复实现已经由 `ctx.sessionQuery` 负责的语义提取与源对齐。
-- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端契约，将召回扩展留作另一项基于度量结果的决策。
-- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 契约。会话级导航本身已有价值，无需让搜索与这项工作耦合。
+- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端约定，将召回扩展留作另一项基于度量结果的决策。
+- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 约定。会话级导航本身已有价值，无需让搜索与这项工作耦合。
 - **在侧边栏公开游标分页**：不予采纳，改为固定显示前 20 条结果并提示缩小查询范围；这样可使交互与取消状态保持有界。
 
 ## 后果
@@ -41,4 +41,4 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 
 ## 测试
 
-宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为契约。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的处置固定为契约；语义提取测试与 SQLite／fixture 搜索测试将排除仅存在于推理中的文本固定为契约。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose（资源释放）。fixture（测试前置数据）、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为契约。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
+宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为约定。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的 dispose（资源释放）固定为约定；语义提取测试与 SQLite／fixture（测试前置数据）搜索测试将排除仅存在于推理中的文本固定为约定。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose。fixture、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为约定。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 4453cca8eb..1c35cafbef 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
 2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
-2026-07-27-web-subagent-conversations.zh.md: 6b2d7bbec1133cdeb2d0cd31a6f9a43b068d21f5
+2026-07-27-web-subagent-conversations.zh.md: 4b5ff938550b6c452680e36331372db65bd6f3d7
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 6b2d7bbec1..4b5ff93855 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 由会话支撑的 subagent 具有持久化身份、持久化 transcript（文本记录）与直接 child 目录，但普通会话谱系无法将它们与 fork 区分开，也无法证明其描述符 mode 与继续执行授权。否则，绑定到 agent（智能体）的通用 Host 操作可能在其直接 parent 继续执行 owner 之外恢复或驱动 child。
 
-浏览器必须遵守[可继续 subagent 契约](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
+浏览器必须遵守[可继续 subagent 约定](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
 
 UI 还必须保留[持久化目录](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)的成员、mode 与 diagnostic。共享服务报告采用实时优先规则的语料活动状态，而 Web 投影会将其替换为确切 child Agent driver 的 `running` 或 `inactive` 状态。这两种活动状态都不是持久化结果，也不承诺继续执行会成功。
 
@@ -20,7 +20,7 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。
 
-停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)，该契约会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
+停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)，该约定会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
 
 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)。
 
@@ -28,14 +28,14 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-14602&p=f)、[层级展开](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-15917&p=f)与 [child 对话](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=388-18584&p=f)画框是非规范性的交互与视觉参考。本记录负责生命周期、协议与失败语义。
 
-| 设计意图 | 已交付契约 |
+| 设计意图 | 已交付约定 |
 | --- | --- |
 | 会话页头可打开紧凑的 child 列表。 | 触发器会汇总仅含 subagent 的完整后代谱系；树按服务顺序显示每个直接目录条目，包括已禁用的 diagnostic。 |
 | 选择一行会复用对话 UI。 | 已寻址历史绝不激活 child；只有 parent 存活的可继续行才保留普通输入框。 |
 | 嵌套 agent 会逐层展开。 | 每行携带一层 `hasChildren` 快照；展开时会立即预留已知直接后代行，随后仍只加载该行的直接目录，并保留其自身的 parent 地址。 |
-| 条目显示 label、状态、token 用量与活跃耗时，同时避免侧边栏条目重复。 | mode 与 `running`／`inactive` 活动状态会同时以文字和视觉呈现；可选 title、持久化 token 用量与活跃轮次耗时来自列表保留的投影值。紧凑耗时从一天起省略更小的单位，而悬停和无障碍名称仍保留精确的整秒数。`SessionHeader.origin` 会移除重复的导航条目，但不授予任何功能权限。 |
+| 条目显示 label、状态、token 用量与活跃耗时，同时避免侧边栏条目重复。 | mode 与 `running`／`inactive` 活动状态会同时以文字和视觉呈现；可选 title、持久化 token 用量与活跃轮次耗时来自列表保留的投影值。紧凑耗时从一天起省略更小的单位，而悬停和无障碍名称仍保留精确的整秒数。`SessionHeader.origin` 会移除重复的导航条目，但不授予任何能力。 |
 
-## 产品契约
+## 产品约定
 
 只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而后代活动则成为悬停与无障碍状态中的第二项。两者均不存在时，后代活动优先于未查看的完成提醒；最后一个运行中的后代停止后，该提醒会恢复。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
 
@@ -45,11 +45,11 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
-## 宿主适配器与协议契约
+## 宿主适配器与协议约定
 
 `@deepseek-ai/dsh-host-apiproxy` 拥有浏览器安全的 `subagents` 域：
 
@@ -63,7 +63,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 普通 `session.history` 路由对于普通会话和 subagent 会话同样只执行观察，但它既不携带目录地址，也不授予继续执行权限。每条需要 Agent 的普通路由都会在恢复冷会话前经过共享所有权栅栏；`session.cancel` 与 `session.updateQueue` 会直接执行同一检查，因为它们有意只查询已附加的 Agent。
 
-适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包（package）导入契约，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
+适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包导入约定，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
 
 ## 客户端对象层与呈现
 
@@ -83,19 +83,19 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **对已寻址 child 使用普通会话 API。** 不予采纳，因为通用历史不携带目录 mode 校验，而绑定到 Agent 的通用控件会有意拒绝 subagent，不会授予直接 parent 继续执行授权。
 
-**将适配器放入 webserver。** 不予采纳，因为目录与继续执行是通道无关的客户端功能；webserver 只承载已校验的消息。
+**将适配器放入 webserver。** 不予采纳，因为目录与继续执行是通道无关的客户端能力；webserver 只承载已校验的消息。
 
 **新建 UI 包。** 不予采纳，因为 `ui-subagent` 已经负责 Web subagent 引用，也是目录与已寻址 child 呈现的统一 owner。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
 **根据谱系推断 mode 或侧边栏过滤。** 不予采纳，因为普通 fork 共享 `parentSession`。由描述符支撑的目录负责提供 mode；单独的 `origin` 标记只是低成本的导航分类器。
 
-**构建预先加载的递归树或专用目录流。** 就当前规模而言不予采纳。只读 header 的一层可展开性预查会在不读取后代事件的情况下保证点击前的稳定性，而展开仍是懒加载式权威直接 child 读取；现有 Host 帧会更新活动状态、恢复 parent 行的可展开性，并触发有界的成员刷新。
+**构建预先加载的递归树或专用目录流。** 就当前规模而言不予采纳。仅基于 header 的一层可展开性预查会在不读取后代事件的情况下保证点击前的稳定性，而展开仍是懒加载式权威直接 child 读取；现有 Host 帧会更新活动状态、恢复 parent 行的可展开性，并触发有界的成员刷新。
 
 **让 child 在 parent 消失后仍能独立交互。** 不予采纳，因为独立生命周期与用户所有权需要 side session 语义。
 
@@ -111,7 +111,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 ## 后果
 
 - 目录读取可能重新扫描持久化谱系与每个直接候选的描述符日志，但可展开性只复用该追踪中已有的后代 header；Web 活动基线会为每个健康行增加一次 Agent 注册表查找，随后使用现有实时帧，而 token 用量与耗时会复用投影基线和推送，无需按行读取日志，成员刷新则保持去抖动和单次并发。
-- parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
+- parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose（资源释放）、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
 - child 可能在历史获取与 mux 订阅之间发布，因此现有序号归并也涵盖从冷态转为存活的已寻址路径。
 - 持久化 origin 会为 child header 与列表投影添加一个有意保持弱约束的产品分类字段；它不能变成授权捷径。
-- 除对正在运行的可继续 child 的当前轮次 Stop（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
+- 除对正在运行的可继续 child 的当前轮次 Stop（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 82639d4aa8..cd3cdfe70c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
 2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
-2026-07-28-continuable-subagent-conversations.zh.md: 77f497ceeef35dcc519242dca30c81759cc3b907
+2026-07-28-continuable-subagent-conversations.zh.md: 40b6cc3e4d1685192cbd29131ac6987df51a2aeb
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index 77f497ceee..40b6cc3e4d 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：可继续的 subagent
+# Agent Note: 可继续的 subagent
 
 Status: implemented
 
@@ -54,7 +54,7 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的
 
 空闲的历史会话没有 `AgentHandle`。第一条通过鉴权的 `next-turn` 投递会根据持久化会话恢复激活，并将消息提交到其 inbox。冷恢复使用经过身份认证的确切在线 parent Agent 执行鉴权；当该 parent 有激活时，还使用它建立所有权，但绝不使用 parent 执行重建。
 
-激活作为消费方会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权契约。激活 dispose 后，历史会话不消耗运行时内存。
+激活会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权约定。激活 dispose 后，历史会话不消耗运行时内存。
 
 ### 激活生命周期
 
@@ -77,7 +77,7 @@ settled
 no Activation
 ```
 
-`running` 表示 Agent 正在执行准入或轮次，或者 inbox 中存在会唤醒 Agent 的工作。`waiting` 表示 Agent 已经完全停稳，但激活仍持有至少一个尚未完成 dispose 的 child 激活。`settled` 表示 Agent 已经完全停稳且所有持有的 child 都已 dispose；随后管理器会 dispose `AgentHandle` 并移除激活。
+`running` 表示 Agent 有正在进行的准入或轮次，或者 inbox 中存在会唤醒 Agent 的工作。`waiting` 表示 Agent 已经完全停稳，但激活仍持有至少一个尚未完成 dispose 的 child 激活。`settled` 表示 Agent 已经完全停稳且所有持有的 child 都已 dispose；随后管理器会 dispose `AgentHandle` 并移除激活。
 
 管理器根据 Agent 是否完全停稳以及所持 child 集合派生这些状态，而不是维护第二套执行状态机。在 `running` 时投递的 `next-turn` 会进入 Agent inbox。在 `waiting` 时投递的 `next-turn` 会唤醒同一个 Agent，并使激活回到 `running`。在 dispose 完成后投递消息则会冷恢复新激活。
 
@@ -99,7 +99,7 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
 
 ### child 所有权
 
-每次激活都持有自身的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`。由于一个会话至多有一次在线激活，child 会话 id 足以标识在线 child，无需另一个运行时 incarnation 引用。`SessionHeader.parentSession` 记录持久化的直接 parent 身份，`ownedChildren` 中的成员关系则记录进程内所有权关系。
+每次激活都持有自身的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`。由于一个会话至多有一个在线激活，child 会话 id 足以标识在线 child，无需另一个运行时 incarnation 引用。`SessionHeader.parentSession` 记录持久化的直接 parent 身份，`ownedChildren` 中的成员关系则记录进程内所有权关系。
 
 当经过身份认证的 parent 自身是由继续执行管理器管理的激活时，启动 child 或提交由 parent 发起的工作，会在 child 可以运行或消息可以进入其 inbox 前，将 child 会话 id 加入该 parent 的 `ownedChildren`。该集合非空时，这个 parent 不能结算或 dispose。顶层 Agent 或其他非继续执行 Agent 没有激活，也不会加入该等待图。
 
@@ -109,11 +109,11 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
 
 顶层拆卸由宿主负责，而不表示为另一次激活。管理器卸载会调用其内部的管理器全局 drain，同步关闭准入，等待每个已获准的物化过程完成发布或回滚，停止稳定的在线森林，并按 child-first 顺序释放。拥有选定顶层 Agent 的宿主使用 `drainContinuableDescendants(parents)`：确切的 Agent 身份只关闭这些根之下的准入，直到每个身份离开注册表，而无关森林和管理器全局准入保持在线；管理器会在第一次 await 之前停止其可见后代，只等待这些根之下已获准的物化过程，并且只释放选定分支。每个已物化的 start 和在线投递都会在与 inbox 提交相同的同步区间内重新检查调用方取消、适用的 draining 作用域、Activation dispose 和确切的 parent 权限，因此只要拆卸或 parent 替换先于接受发生，就会阻止向正在关闭的 handle 投递。只有适用的 drain 结算后，宿主才能 dispose 自己的顶层 Agent；只有管理器全局 drain 会先于管理器作用域 dispose。
 
-activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 按注册逆序撤销，无法表达动态 child 图。管理器初始化时先注册私有作用域的结构化 disposer，再注册自身的 drain disposer，使逆序撤销先执行 drain、再释放该作用域；如果只在与后续 Agent handle 相同的作用域上注册 cleanup effect，结构化 handle dispose 就可能绕过 child-first 顺序。每个物化过程都会在启动内部事务前注册其屏障参与项，并对其确切的在线祖先建立快照，然后保持跟踪，直到安装 Activation 或完全回滚。Activation 会以弱引用方式记录其属于这组祖先，因此中间 Agent 即使离开注册表，也不会让仍在线的后代脱离宿主根节点的可见范围。每个 Activation 都会在取消或递归回调前安装一个记忆化的 dispose promise，使限定作用域的宿主关闭、全局管理器卸载、child 释放和正常结算能够汇合，而不会重复释放。取消会在等待缓慢的后代清理之前自顶向下传播；handle 释放仍是 child-first。同级分支独立 drain；系统会记录单次 dispose 失败，但仍会尝试其余选中 handle，聚合 drain 则在所有选中分支结算后报告失败。这次进程内拆卸不会销毁持久化 child 会话。
+activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 按注册逆序撤销，无法表达动态 child 图。管理器初始化时先注册私有作用域的结构化 disposer，再注册自身的 drain disposer，使逆序撤销先执行 drain、再释放该作用域；如果只在与后续 Agent handle 相同的作用域上注册 cleanup effect，结构化 handle dispose 就可能绕过 child-first 顺序。每个物化过程都会在启动内部事务前注册其屏障参与项，并对其确切的在线祖先建立快照，然后保持跟踪，直到安装 Activation 或完全回滚。Activation 会保留其在这组祖先中的弱成员关系，因此中间 Agent 即使离开注册表，也不会让仍在线的后代脱离宿主根节点的可见范围。每个 Activation 都会在取消或递归回调前安装一个记忆化的 dispose promise，使限定作用域的宿主关闭、全局管理器卸载、child 释放和正常结算能够汇合，而不会重复释放。取消会在等待缓慢的后代清理之前自顶向下传播；handle 释放仍是 child-first。同级分支独立 drain；系统会记录单次 dispose 失败，但仍会尝试其余选中 handle，聚合 drain 则在所有选中分支结算后报告失败。这次进程内拆卸不会销毁持久化 child 会话。
 
 ### 报告投递扩展
 
-可选的 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递契约。
+后来添加的可选 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递约定。
 
 ### 延后的 steering（中途引导）
 
@@ -143,7 +143,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 范围
 
-本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳契约，才能支持同样的行为。
+本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳约定，才能支持同样的行为。
 
 它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存；后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)在此生命周期之上补充了唯一的公开停止操作。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
 
@@ -169,7 +169,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，该 seam 只接受确切的在线 parent。
 
-**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 契约承载。
+**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 约定承载。
 
 **使用 child 引用计数。** 计数无法识别哪个 child 仍持有拆卸工作，也允许重复递减错误。身份集合会显式保留取消和 dispose 义务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml
index df8239ba4b..62a22d215c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.md
 2026-07-28-cross-workspace-resume.md: e8a8636911015a5b300b45a30e268ee1be5d47d1
-2026-07-28-cross-workspace-resume.zh.md: 9e5e126f4b204927d7fb134a196dd0d0a98468d4
+2026-07-28-cross-workspace-resume.zh.md: c56641be35bb37fb8aafb7613bdf8b8158e198d9
diff --git a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md
index 9e5e126f4b..c56641be35 100644
--- a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md
@@ -16,15 +16,15 @@ Status: implemented
 
 ## Decision
 
-共享 CLI 配置提供 Harness home 下的同一个会话根目录，选择器获得 workspace 范围，交接过程携带目标目录。
+共享 CLI（命令行界面）配置提供 Harness home 下的同一个会话根目录，选择器获得 workspace 范围，交接过程携带目标目录。
 
-**存储。** 共享 base 在 `apps/cli/config/base.cordis.yml` 中拥有默认值：其 `session-persistence-jsonl` 配置项调用由 app-boot 提供的 `dshHomePath('sessions')`，该函数使用规范的 `DSH_HOME` 解析器及其标准的 `~/.dsh` 回退值。因此 TUI、Web 与 headless 使用同一个默认值，无需针对会话的启动器补丁或槽位。若 overlay 或个人 patch 显式声明根目录，它会整体替换该配置项的 `config`，并继续作为部署的权威选择。
+**存储。** 共享 base 在 `apps/cli/config/base.cordis.yml` 中拥有默认值：其 `session-persistence-jsonl` 配置项调用由 app-boot 提供的 `dshHomePath('sessions')`，该函数使用规范的 `DSH_HOME` 解析器及其标准的 `~/.dsh` 回退值。因此 TUI、Web 与 headless 使用同一个默认值，无需针对会话的启动器补丁或 slot。若 overlay 或个人 patch 显式声明根目录，它会整体替换该配置项的 `config`，并继续作为部署的权威选择。
 
 **是范围，不是排除。** 当前 workspace 之外的 workspace 是一种展示范围，而不是禁用理由。`showResume()` 汇总每一条记录，`ResumePicker` 持有一个 `'workspace' | 'all'` 的 `scope`，默认为当前 workspace，因此常见场景毫无变化。Tab 切换范围；范围行会说明当前生效的范围，以及另一个范围下的数量；在全 workspace 范围中每一行都报告自己的 workspace，而该标签只在展示它的范围里才加入可搜索文本。切换范围会清空查询和选中项，使高亮行始终属于可见列表；而逐行的 workspace 行会让该范围下的每一行在终端里多占一行，可见条数预算已经把这一点计入。
 
 因此 `summarizeResumeCandidate` 去掉了 `'different workspace'`，并新增 `'session has no recorded workspace'`。这是一条真正新增的拒绝理由，而不是改名：没有 `cwd` 的头部没有指明任何目录供宿主进入，所以即便它的日志完好也无法完成交接。
 
-**交接。** `TuiResumeHost.handoff` 在 `SessionId` 之外还接收目标 `cwd`。`preflightResume` 把两者一起解析并一起返回，因此调用方无法从它展示过的那一行里重新推导出一个陈旧目录——在列表展示与预检之间 `cwd` 发生了移动的记录，会在*重新读取到的*目录中恢复，这也是原先「拒绝已移动的 cwd」的行为如今变成携带新路径完成交接的原因。已交付的宿主在释放应用之前切换目录：不可达的目录必须在调用方还能恢复终端时就拒绝，因为拆卸之后已经没有任何所有者可供汇报。恢复始终使用默认的 `dsh --resume` 界面，因为 `meta` 会拒绝父级选项；交接过程已经进入持久化保存的目标目录。
+**交接。** `TuiResumeHost.handoff` 在 `SessionId` 之外还接收目标 `cwd`。`preflightResume` 把两者一起解析并一起返回，因此调用方无法从它展示过的那一行里重新推导出一个陈旧目录——在列表展示与预检之间 `cwd` 发生了变化的记录，会在*重新读取到的*目录中恢复，这也是原先「拒绝发生变化的 cwd」的行为如今变成携带新路径完成交接的原因。已交付的宿主在 dispose（资源释放）应用之前切换目录：不可达的目录必须在调用方还能恢复终端时就拒绝，因为拆卸之后已经没有任何所有者可供汇报。恢复始终使用默认的 `dsh --resume` 接口，因为 `meta` 会拒绝父级选项；交接过程已经进入持久化保存的目标目录。
 
 ## Alternatives considered
 
@@ -36,7 +36,7 @@ Status: implemented
 
 **把所有 workspace 铺成一个扁平列表。** 否决：这会丢掉绝大多数场景想要的「本项目」默认值，而在一个繁忙的 home 目录里，当前项目的会话会和无关会话争夺注意力。
 
-**让宿主从还原后的会话头部推断目录。** 否决：会话头部是面向模型与提示词的状态，在启动*之后*才还原，而目录必须在 `execve` *之前*进入。显式传递它能让这个顺序在边界处保持可见。
+**让宿主从还原后的会话头部推断目录。** 否决：会话头部是面向模型与提示词的状态，在启动*之后*才还原，而目录必须在 `execve` *之前*进入。显式传递它能让这个顺序在 seam 处保持可见。
 
 ## Consequences
 
@@ -46,4 +46,4 @@ Status: implemented
 
 ## Testing
 
-TUI 测试覆盖默认范围隐藏其他 workspace 但报告其数量、Tab 显示它们并带上逐行 workspace 标签、再按 Tab 返回时清空查询与选中项、按 workspace 标签搜索、无 cwd 的记录仍可见但不可选，以及交接同时收到 id 和在预检时重新读取到的 workspace。原先「拒绝已移动的 cwd」的用例现在断言交接携带新目录。构建后的 CLI PTY 测试会运行共享配置默认值与每进程派生的查询索引。无密钥 TUI 快照固定选择器的两个范围，包括范围行、逐行 workspace 行，以及页脚中的 Tab 提示。手动执行的一次跨 workspace 恢复在进程层面验证了替换后进程的工作目录变为目标 workspace。
+TUI 测试覆盖默认范围隐藏其他 workspace 但报告其数量、Tab 显示它们并带上逐行 workspace 标签、再按 Tab 返回时清空查询与选中项、按 workspace 标签搜索、无 cwd 的记录仍可见但不可选，以及交接同时收到 id 和在预检时重新读取到的 workspace。原先「拒绝发生变化的 cwd」的用例现在断言交接携带新目录。构建后的 CLI PTY 测试会检验共享配置默认值与每进程派生的查询索引。无密钥 TUI 快照固定选择器的两个范围，包括范围行、逐行 workspace 行，以及页脚中的 Tab 提示。手动执行的一次跨 workspace 恢复在进程层面验证了替换后进程的工作目录变为目标 workspace。
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index 9f60321cc8..e0133df46f 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-feedback-command.md
 2026-07-28-feedback-command.md: 78cc9e89a5811b3f1520bae2bd971cbcf2522ede
-2026-07-28-feedback-command.zh.md: c8870ca2988501d7899ae826e1bbcbad0bef5678
+2026-07-28-feedback-command.zh.md: b0bba25ec3331123cb86066fc6c89186f2297cc9
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index c8870ca298..b0bba25ec3 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -14,11 +14,11 @@ Status: implemented
 
 位于 `packages/feedback/command-feedback/` 的 `@deepseek-ai/dsh-command-feedback` 通过 `ctx.commands` 注册一个全局 `feedback` 命令。`/feedback <text>` 给出确认；空输入或仅含空白的输入返回直接用法错误。处理器是同步的，只注入 `commands`，且没有任何配置。
 
-本包（package）声明仅写入日志的 `feedback/record { text }` 会话事件，并导出 `recordFeedback(session, text)`，作为不依赖命令的生产方。该生产方丢弃前后空白，拒绝空结果，并且恰好追加一个事件。`/feedback` 委托给它，因此其他 UI、钩子或 host 集成无需构造斜杠命令也能记录同一个领域事实。
+本包声明仅写入日志的 `feedback/record { text }` 会话事件，并导出 `recordFeedback(session, text)`，作为不依赖命令的生产方。该生产方丢弃前后空白，拒绝空结果，并且恰好追加一个事件。`/feedback` 委托给它，因此其他 UI、钩子或 host 集成无需构造斜杠命令也能记录同一个领域事实。
 
 `dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会进入持久化的常规有界写入路径；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。
 
-采集对正在运行的 agent 与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为本地警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。
+采集对正在运行的 agent（智能体）与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为仅限本地的警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。
 
 ### 为何反馈拥有自己的事件
 
@@ -34,7 +34,7 @@ Status: implemented
 
 ### 一个新的分组
 
-`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组只包含一个生产方包；跨领域的消费方留在各自所属的分组，而不是迫使这个包不断膨胀。
+`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组只包含一个生产方包；跨领域的消费方留在各自所属的分组，而不是迫使这个分组不断膨胀。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index ea1b12edeb..1f652e9eee 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
 2026-07-28-skill-invocation-policy.md: 9d34bcb77ab7933ef9bf4e9b5227dade39903667
-2026-07-28-skill-invocation-policy.zh.md: 4b190dbd095306d41837bd9734049f5e3d85da72
+2026-07-28-skill-invocation-policy.zh.md: f196bcb66b05d2c7ba4b82a4e1124e335ef8aeb1
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
index 4b190dbd09..f196bcb66b 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会移除禁止模型调用的 skill，而 `ctx.skills.get()` 仍是不过滤内容的可信 loader。该设计足以支持由模型发起的加载，却无法表示与 Claude 兼容的四类 skill：仅向用户公开、仅向模型公开、同时向两者公开，或者两者均不公开。TUI 从面向模型过滤后的列表中生成用户自动补全，并允许通过 `get()` 加载任意精确名称，这进一步放大了两类调用策略不匹配的问题。
 
-本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型契约。
+本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型约定。
 
 ## 决策
 
-`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行契约后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
+`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
 
 `ctx.skills.list()` 返回所有胜出的摘要，不再替任何调用接口选择策略。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 保持策略无关，因为可信内部调用方可能需要任意定义；对外消费方则必须在展示或加载 skill 之前执行自身对应的判定函数。模型工具和 TUI 会在调用 `get()` 前检查与调用策略无关的摘要，随后再次检查已加载的定义：被拒绝的名称绝不会进入定义加载流程，发现与加载之间发生策略变更也无法暴露该 skill 的正文。
 
 本地提供方只接受拼写完全一致的 kebab-case frontmatter 键 `disable-model-invocation` 和 `user-invocable`。它接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`，与 Claude skills 实际支持的布尔写法一致。它将 `disable-model-invocation` 映射为相反的正向字段，即使两个键都不存在，也会根据默认值填充两个正向字段。若使用外部驼峰式拼写或提供非布尔调用值，发现流程会丢弃整个 skill，并给出有针对性的警告；本仓库尚处于发布前阶段，因此不为磁盘格式保留兼容别名。调用数据校验遵循失败时默认拒绝原则，因为忽略这类数据会默认授予权限，可能使 skill 暴露在已禁用的接口上；与之不同，类型错误的可选 `whenToUse` 和 `metadata` 值会被省略，因为它们不参与调用判定。
 
-面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地执行用户字段，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill peer 变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。
+面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地根据用户字段执行策略，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill 对等依赖（peer dependency）变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。
 
 这些规则允许以下四种组合：
 
@@ -39,12 +39,12 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
 
 **在 `ctx.skills.get()` 内执行调用策略。** 不予采纳，因为 `get()` 无法判断调用方是模型工具、人类命令还是可信编排逻辑。在此处过滤还会使两个接口均禁止调用的组合无法被检查或管理。
 
-**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 契约，而本仓库尚未发布，无需承担兼容义务。快速失败可以避免暗中保留不符合标准的拼写。
+**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 约定，而本仓库尚未发布，无需承担兼容义务。显式失败可以避免暗中保留不符合标准的拼写。
 
 **增加由浏览器端直接调用 skill 的 RPC。** 本次改动不予采纳，因为现有浏览器流程插入的是模型引用，而非已经加载的指令正文。因此，该流程应当取模型与用户调用策略的交集；直接由用户加载的接口需要单独设计协议与日志记录方式。
 
 ## 后果
 
-提供方与运行时注册对外提供小而类型明确的调用契约，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
+提供方与运行时注册对外提供小而类型明确的调用约定，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
 
 无密钥 ACP（Agent Client Protocol）快照固定了模型目录的变更：其中包含仅允许模型调用的 skill，并排除仅允许用户调用的 skill。组装后的无密钥 TUI 快照按精确名称发现并加载一个仅允许用户调用的 skill，随后在加载正文前拒绝一个仅允许模型调用的 skill；真实 Loader/PTY 冒烟测试通过随产品交付的终端进程证明了同一条仅允许用户调用的路径。真实宿主上的 Chromium 快照固定了浏览器在全部四种策略组合下的交集行为。TUI 单元测试覆盖这些组合以及资源释放竞态；注册表、本地解析器、模型工具和 API 代理测试则覆盖默认值、支持的布尔写法、格式错误的值、旧键拒绝、精确名称加载时的策略执行，以及浏览器侧的策略交集。
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 53dba67c61..45bb845cd6 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
 2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
-2026-07-28-web-terminal-card.zh.md: 4c74d880c5795cf85f32391b27e6ffd2c5074870
+2026-07-28-web-terminal-card.zh.md: ff0b7f327560e9dba379a0d36596b267b739aaa7
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 4c74d880c5..ff0b7f3275 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,15 +12,15 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道 seam；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
-该组件的契约：
+该组件的约定：
 
 - **提示符行，每条命令行一行。** 命令的每一行各占一行：标签，其后原样跟随该行。因此一个在两行上承载两条 shell 命令的 `command` 就读作它本身的两条命令，而不是被压成一行并省略号截断。标签取 cwd 的最后一段路径，当 cwd 等于 `home` prop 时取 `~`——浏览器没有 `$HOME`，因此由调用方提供绝对家目录，不提供时该折叠不生效。视图不带 cwd 时渲染一个纯 `$`。末尾换行是终止符，不是一条空的末命令。只有**第一行**携带该标签：视图只知道一个工作目录——调用开始处的那个——而后面的行完全可能在别处运行，命令里一个 `cd` 就足以改变它。把标签在各行重复，等于陈述一个此处无人知晓的逐行目录，这与运行状态点只出现一次是同一个理由。其余行保留一个裸 `$`，因此它们仍读作提示符。
 - **整次调用一枚运行状态点，位于第一行。** 它是 `StateDot` 四种状态中的三种：运行期间为追逐动画，与渲染状态徽章相同的退出状态为红色，干净落定为绿色——与工具行行首图标使用同一个指示器，因此一行与其自身的卡片不可能对同一条命令产生分歧。该状态点存在的理由是：读者对一条 shell 命令的第一个问题就是它是否仍在运行；没有它时，这一点只能从「没有输出」推断，而一条落定后无输出的命令看起来也一样。它以脱离文档流的方式落在卡片以**自身左内边距**预留的落区里，因此既不会缩进其命令，也不依赖命令自身的文本度量来与之对齐。该预留用 padding 而非 margin，是因为每个渲染点都会整条重写 `margin` 来设定自己的缩进——那会静默取消基于 margin 的落区，并让容器把状态点裁掉。无论有多少行，都只有一枚：视图携带的退出状态属于整次调用，而 bash 不报告逐条命令的状态，因此每行一枚状态点就等于在断言——一条在失败调用中其实成功了的命令行自身失败了。那一处视觉隐藏的文本标签具有相同的作用域，因为 `StateDot` 是 `aria-hidden`，而每行一个标签会被辅助技术读成好几个各自独立的结果。
 - **不软换行。** 输出行使用 `white-space: pre`，置于横向滚动的容器内。列对齐得以保留；长行滚动，而非折行。
-- **高度上限与展开控件。** 输出超过 `DEFAULT_TERMINAL_MAX_LINES`（16）行时，显示 `ceil(max/2)` 行首部加余下的尾部行数，中间是一个按钮，报告被隐藏的行数并可展开。计数针对的是剥除输出末尾终止符之后解析出的行，因此以换行结尾的 N 行输出就是 N 行。切分算法保留原 TUI transcript 折叠卡片的行为，因此既有的首尾选择保持稳定。
-- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些用例都对照真实终端核实过，因为先前「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
+- **高度上限与展开控件。** 输出超过 `DEFAULT_TERMINAL_MAX_LINES`（16）行时，显示 `ceil(max/2)` 行首部加余下的尾部行数，中间是一个按钮，报告被隐藏的行数并可展开。计数针对的是剥除输出末尾终止符之后解析出的行，因此以换行结尾的 N 行输出就是 N 行。切分算法保留原 TUI transcript（文本记录）折叠卡片的行为，因此既有的首尾选择保持稳定。
+- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些用例都对照真实终端核实过，因为先前「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终触发 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
 - **退出状态与复制。** 非零退出码或信号渲染一枚状态徽章，与 bash 工具自身渲染器所作的退出状态区分一致；干净退出不渲染徽章，落定后的空输出渲染一处变暗的占位文字——该判定读的是卡片实际渲染的解析行，而非原始文本，因为只含转义或控制字节的输出能通过 `trim()` 却解析不出任何可见内容，否则就会画出一片空行外加一个把不可见字节写进剪贴板的复制控件。复制控件复制的是原始输出文本而非渲染后的树，因此提示符行与徽章不会进入剪贴板。
 
 几何尺寸、圆角与字体沿用 `CodeBlock`，因此终端卡片与围栏代码块在视觉上一致；`white-space: pre` 加横向滚动是有意的分歧。两个组件都需要的剪贴板写入从 `CodeBlock` 中提取到包内部的 `src/clipboard.ts`，不对外导出，因此它仍是这两个块的实现细节。
@@ -41,7 +41,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 **复用 `CodeBlock` 并传入 `console` 语言，而不新建组件。** 已否决：`CodeBlock` 会软换行，而软换行正是本次要修的缺陷，且它没有退出状态、没有 cwd 提示符行、没有高度上限、也不处理 ANSI。把四项终端专属关注点加进共享的代码围栏组件，等于把它们强加给每一个 markdown 围栏。两个组件改为共享几何与字体 token，那是唯一一处「一套实现对两者都正确」的部分。
 
-**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛如实陈述：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它清过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
+**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛如实陈述：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它通过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
 
 ## Consequences
 
@@ -49,7 +49,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `TerminalBlock` 只读取 terminal 视图携带的字段，因此它始终是渲染意图内容的纯函数——不查会话状态，与产出该视图的 presenter 一样可安全回放。不具备终端能力的 UI 仍从桥接层拿到围栏式回退；工具的结果形态未作任何改动。
 
-在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于那道接缝自身的改动。
+在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于那道 seam 自身的改动。
 
 内嵌渲染的许可仅授予 terminal 意图。将来想要内嵌的意图需要有自己的边界与自己的决定，且需针对此处记录的理由来论证，而不是仅针对「只在面板」这条约定本身。
 
@@ -59,7 +59,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `packages/client/ui-tool/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-tool/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。
 
-`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮改名为 `bash`、第 60 轮保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
+`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮次改名为 `bash`、第 60 轮次保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮次的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮次有意排在 todo 轮次**之前**：当前计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮次还承载第 60 轮次两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
 
 `apps/web/tests/navigation-panes.e2e.ts` 在其既有的 `echo NAVIGATION_OK` bash 调用上新增真实浏览器场景，断言 jsdom 无法计算的部分：把输出面板挤压到窄于内容宽度后，行仍保持单行且面板产生横向溢出；运行状态点解析为绿色的 success token，而不是字面颜色（没有真实主题样式表时，`--dsw-*` 变量根本不产生计算值），且它位于卡片盒之内、提示标签之左——这正是那道 gutter 内边距所拥有的不变量；复制控件走的是页面自身的异步 Clipboard API，而非 `execCommand` 兜底路径。其 `terminal-card.expected.md` 基准记录了提示行中已解析的 workspace——这正是不带 `workdir` 的 bash 调用应当显示的内容，而非一个裸 `$`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index 1491968f15..ee10e63c02 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
 2026-07-30-config-only-repository-plugins.md: 2057125fc78596dd4e5eb153f77b828f83d9ceff
-2026-07-30-config-only-repository-plugins.zh.md: 6e741b46be716e21a11c2f508fb5e6d0505c76d0
+2026-07-30-config-only-repository-plugins.zh.md: afda636c6592e26e80cd2f8f665f92d3010f28f7
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 6e741b46be..afda636c65 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -12,19 +12,19 @@ Status: implemented
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败契约和清理行为。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包，运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败约定和清理行为。
 
 ## 实时更新与失败
 
-`dsh-app-boot` 通过一个辅助函数挂载根 Include，并保留其确切的 Loader `Entry`。TUI 和 Web 通过 Cordis HMR（热模块替换）注册 `$DSH_HOME/config.yaml`；无头界面在启动时读取同一文件，但不保留监视器。监视器更新会重新构建 Include 补丁列表，先放置不可变的应用自有补丁，再放置新解析的个人补丁。因此，Web 生成的端口、会话根目录、信任和前端值会在每次个人编辑后保留，除非后续个人补丁有意替换相应配置项。
+`dsh-app-boot` 通过一个辅助函数挂载根 Include，并保留其确切的 Loader `Entry`。TUI 和 Web 通过 Cordis HMR（热模块替换）注册 `$DSH_HOME/config.yaml`；无头模式在启动时读取同一文件，但不保留监视器。监视器更新会重新构建 Include 补丁列表，先放置不可变的应用自有补丁，再放置新解析的个人补丁。因此，Web 生成的端口、会话根目录、信任和前端值会在每次个人编辑后保留，除非后续个人补丁有意替换相应配置项。
 
-Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装模块导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播并行的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。MCP 传输连接失败仍沿用现有 MCP 客户端所收束的「插件成功加载但无工具」结果，因此不会被重新分类为配置更新失败。
+Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装层导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播相应的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。MCP 传输连接失败仍沿用现有 MCP 客户端所收束的「插件成功加载但无工具」结果，因此不会被重新分类为配置更新失败。
 
 相同说明符会永久复用同一个缓存版本。HMR 监视配置，而非已缓存的仓库代码；用户必须改变 ref、路径或源列表，才能选择另一个版本。
 
 ## 信任边界
 
-配置仓库即授权该仓库及其依赖中的包管理器生命周期代码以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。固定的运行时包装模块会阻止仓库作者提供的 Cordis 入口成为受支持插件格式的一部分；它无法让包准备过程安全执行不受信任的代码。
+配置仓库即授权该仓库及其依赖中的包管理器生命周期代码以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。固定的运行时包装层会阻止仓库作者提供的 Cordis 入口成为受支持插件格式的一部分；它无法让包准备过程安全执行不受信任的代码。
 
 ## 考虑过的替代方案
 
@@ -36,7 +36,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 **监视缓存内容，或自动刷新相同 ref。** 否决，因为一个配置值必须标识一个不可变的已准备版本。后台远端解析会在没有配置差异的情况下改变可执行代码，并使回滚依赖可变的远端状态。
 
-**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定契约，并在需要时把原始值保留为错误原因。
+**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定约定，并在需要时把原始值保留为错误原因。
 
 ## 后果
 
@@ -47,4 +47,4 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 ## 测试
 
-仓库包测试固定源规范化、默认和嵌套 `.dsh-plugin` 路径、缓存根解析、重复项拒绝、已准备包装模块加载及资源释放。App-boot 测试通过真实 HMR／Include／Loader 路径驱动确切路径的新增、两类失败、恢复、移除、失败事件及生成补丁保留。一个无密钥 PTY 冒烟测试仅通过个人配置启动已交付的 `dsh` 组合，并从预置的不可变缓存版本中调用一个 skill。
+仓库包测试固定源规范化、默认和嵌套 `.dsh-plugin` 路径、缓存根解析、重复项拒绝、已准备包装层加载及资源释放。App-boot 测试通过真实 HMR／Include／Loader 路径驱动确切路径的新增、两类失败、恢复、移除、失败事件及生成补丁保留。一个无密钥 PTY 冒烟测试仅通过个人配置启动已交付的 `dsh` 组合，并从预置的不可变缓存版本中调用一个 skill。
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
index 54966549ba..0a06bb5f51 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
 2026-07-30-continuable-subagent-report-tool.md: 8324f1fa08f7dace6153712575e7e70a07ee9344
-2026-07-30-continuable-subagent-report-tool.zh.md: e7599c1d85328e83c7773718101b59e763a1e37f
+2026-07-30-continuable-subagent-report-tool.zh.md: 7adc4acc470bd701eee756e7d9ef89d287852a57
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
index e7599c1d85..7adc4acc47 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：可继续 subagent 报告工具
+# Agent Note: 可继续 subagent 报告工具
 
 Status: implemented
 
@@ -8,15 +8,15 @@ Status: implemented
 
 可继续的进程内 subagent 能够接收 parent 后续发来的消息、保留后代、结算并冷恢复，但基础生命周期无法让它们将选中内容发送给直接 parent。child 的完整输出已可从持久化会话中重建，因此缺失的能力是显式投递，而非结果存储。
 
-如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式契约。
+如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式约定。
 
 ## 决策
 
-新增可独立安装的 `@deepseek-ai/dsh-tool-subagent-report` 包（package）。它会向每个可继续进程内 child Activation 贡献一个普通的面向模型 `report` 工具。child 在一个轮次中可调用零次或多次。调用成功既不会结束该轮次或结算 Activation，也不会阻止 parent 之后继续 follow-up；完成轮次也绝不会自动报告。
+新增可独立安装的 `@deepseek-ai/dsh-tool-subagent-report` 包。它会向每个可继续进程内 child Activation 贡献一个普通的面向模型 `report` 工具。child 在一个轮次中可调用零次或多次。调用成功既不会结束该轮次或结算 Activation，也不会阻止 parent 之后继续 follow-up；完成轮次也绝不会自动报告。
 
 该功能是协作控制，不是承载结果的执行包装层。它不新增 Task、`SubagentRun`、结果 promise、Activation 状态、投递队列或回放路径。
 
-### 面向模型的契约
+### 面向模型的约定
 
 `report` 只接受 `{ output: string }`，也只返回 `{ messageId: string }`。它不接受 child id、接收方 id 或投递模式。`exec.agent` 将工具调用绑定到发送报告的 child；服务从持久化 `parentSession` 中推导唯一接收方，调度则由部署配置决定。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 工具描述会明确报告操作是显式、可重复、仅限直接 parent 且不会结束轮次的。它还会警告：发送被接受后，后续 `tools/post-execute` 失败可能替换工具结果，因此工具结果失败时内容仍可能已经送达。没有幂等键时，更强的表述会诱导调用方在结果不明确的失败后重复重试。
 
-该工具使用不带 location 的通用渲染，其确认中包含 `messageId`。作用域局部注册使呈现与执行保持一致：root、one-shot child、远程提供方、同级作用域和无 agent 执行既不能看到，也不能执行 `report`。它会在 child 的全局 `toolFilter` 之后安装，因此委派 allow-list 不会意外移除这条结构性返回通道；不需要返回通道的部署不安装该包。
+该工具使用不带 location 的通用渲染，其确认中包含 `messageId`。作用域局部注册使呈现与执行保持一致：root、one-shot child、远程提供方、同级作用域和无 agent（智能体）执行既不能看到，也不能执行 `report`。它会在 child 的全局 `toolFilter` 之后安装，因此委派 allow-list 不会意外移除这条结构性返回通道；不需要返回通道的部署不安装该包。
 
 ### 服务权限
 
@@ -40,7 +40,7 @@ root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以
 
 静默投递调用 `parent.inject()`。它会添加模型可见上下文，但不启动 parent 模型请求：若 parent 空闲，则在调用返回前追加消息；若 parent 正在准入或运行，则暂存报告，留到下一个安全日志位置。该模式不创建 inbox 条目实例，因此也不会产生虚构的继续执行管理器接受记录。
 
-唤醒投递调用 `parent.followup()`。它会创建一个普通的 FIFO parent 轮次，唤醒已驻留的 parent driver，且绝不 steering 已开始的轮次。当该 parent 本身也是可继续 Activation 时，发送会使用管理器现有的准入计数，防止 parent 在同步入队与准入微任务之间结算。
+唤醒投递调用 `parent.followup()`。它会创建一个普通的 FIFO parent 轮次，唤醒已停驻的 parent driver，且绝不 steering（中途引导）已开始的轮次。当该 parent 本身也是可继续 Activation 时，发送会使用管理器现有的准入计数，防止 parent 在同步入队与准入微任务之间结算。
 
 两种模式都会将一条用户角色消息封装为 `Background subagent <child-id> reported:`，后面跟随完全原样的 `output`。持久化来源信息为 `{ kind: 'subagent-report', senderSessionId: child.id }`。并发发送的顺序由 Agent 的常规规则决定；subagent 层不会创建第二条队列。
 
@@ -48,13 +48,13 @@ root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以
 
 成功表示确切的在线 parent 已同步接受该消息。空闲 parent 在接受静默注入时已经完成追加，而暂存的静默上下文只有到达正常日志边界后才可重建。唤醒投递包含一个 inbox 条目实例，其 id 与返回的稳定消息 id 保持分离。
 
-首个版本不提供持久化邮箱、幂等键、投递回执、重试协议或恰好一次保证。进程故障可能让调用方无法确定结果，在结果未知时重试则可能重复报告。parent 不可用时，持久化 child transcript 仍是恢复来源。
+首个版本不提供持久化邮箱、幂等键、投递回执、重试协议或恰好一次保证。进程故障可能让调用方无法确定结果，在结果未知时重试则可能重复报告。parent 不可用时，持久化 child transcript（文本记录）仍是恢复来源。
 
 ### 组合与生命周期
 
 subagent seam 新增 `registerContinuableSetup(contribution): () => void`，由 `SubagentActivationSetupRegistry` 支撑。每个同步贡献都会接收尚未发布的 child 上下文，并返回其安装的 disposer。继续执行管理器首先应用基础 child 组合，然后通过同一个用于首次创建与冷恢复的设置闭包，按注册顺序应用当前贡献。
 
-注册表负责注册、每个 child 的安装记录、设置回滚、child 作用域清理和立即撤销。应用一个批次会返回 Agent setup 提交对象，用于在所有 setup 的 await 均结算后、紧邻 Agent 发布前重新校验配置状态。因此，某项贡献抛出异常或被并发撤销时，会在 Agent 与 Session 发布前拒绝操作并回滚该批次。新注册项只会在驻留 child 的下一个 Activation 生效；移除注册项时，会先将它对新设置关闭，再立即撤销为正在配置或驻留的每个 child 安装的实例。注册 dispose 与 child 上下文 dispose 都是幂等的，两者都会先尝试每项释放，再聚合失败。
+注册表负责注册、每个 child 的安装记录、设置回滚、child 作用域清理和立即撤销。应用一个批次会返回 Agent setup 提交对象，用于在所有 setup 的 await 均结算后、紧邻 Agent 发布前重新校验配置状态。因此，某项贡献抛出异常或被并发撤销时，会在 Agent 与会话发布前拒绝操作并回滚该批次。新注册项只会在驻留 child 的下一个 Activation 生效；移除注册项时，会先将它对新设置关闭，再立即撤销为正在配置或驻留的每个 child 安装的实例。注册 dispose（资源释放）与 child 上下文 dispose 都是幂等的，两者都会先尝试每项释放，再聚合失败。
 
 该 seam 使继续执行管理器无需知道工具名。report 包只安装 `report`；`@deepseek-ai/dsh-tool-subagent-control` 则独立安装 parent 侧的 `send_message` 和 `list_agents`。部署时可安装任一方向、同时安装两者或两者均不安装。提供方仍只负责数据，持久化描述符不会对 report 可用性或投递模式建立快照，冷恢复则使用部署当前的贡献与策略。
 
@@ -96,7 +96,7 @@ ACP（Agent Client Protocol）快照 harness 新增 `waitForSubagentTurnEnd`，
 
 ### 在 Agent 创建后校验 setup
 
-创建完成后的撤销检查只能在 Agent 与 Session 均已发布后拒绝 Activation。对返回的 handle 执行 dispose 会移除实时对象，但当前 seam 无法删除持久化内容，因此会留下一个仍可恢复的 child，而继续执行管理器却判定它从未建立。改为返回 `AgentSetupCommit`，Agent 工厂便可在自身的发布边界同步执行同一项可变状态检查。
+创建完成后的撤销检查只能在 Agent 与会话均已发布后拒绝 Activation。对返回的 handle 执行 dispose 会移除实时对象，但当前 seam 无法删除持久化内容，因此会留下一个仍可恢复的 child，而继续执行管理器却判定它从未建立。改为返回 `AgentSetupCommit`，Agent 工厂便可在自身的发布边界同步执行同一项可变状态检查。
 
 ## 影响
 
@@ -115,4 +115,4 @@ ACP（Agent Client Protocol）快照 harness 新增 `waitForSubagentTurnEnd`，
 
 wakeup 模式可能在嵌套 child 频繁报告时放大模型工作量。由部署所有者控制并默认静默，可以限制该风险，但无法完全消除。
 
-注册表中的存在性就是 parent 在线信号。宿主拥有的 parent 如果已开始 `AgentHandle.dispose()` 但尚未展开其作用域，仍可能接受并追加一条本进程不会再处理的报告。要弥合这个缺口，需要 Agent 层面的 dispose 开始信号，不能由 subagent 层推断。
+注册表中的存在性就是 parent 在线信号。宿主拥有的 parent 如果已开始 `AgentHandle.dispose()` 但尚未完成其作用域清理，仍可能接受并追加一条本进程不会再处理的报告。要弥合这个缺口，需要 Agent 层面的 dispose 开始信号，不能由 subagent 层推断。
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
index 9e267e82a0..9ae0827be2 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
 2026-07-30-current-sandbox-policy-context.md: 093f9a8a0b58256bb4f2301cc62fa83629de4fbd
-2026-07-30-current-sandbox-policy-context.zh.md: 729ea9d50c7dbbfa027e1cad11929ae1c2b379b1
+2026-07-30-current-sandbox-policy-context.zh.md: ce7ff2d0cff0fc1068995fde174a4eb1df5343b7
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
index 729ea9d50c..ce7ff2d0cf 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 现有 `dsh-system-prompt` 组装在稳定系统段与工具 schema 之外，还包含有序的动态上下文。组装一个步骤后，agent loop（智能体循环）会将所有活动上下文渲染成一份带显式取代声明的完整快照。仅当不存在保留快照、字节发生变化、压缩（compaction）移除了保留消息，或最后一项贡献消失而需要一份清除快照时，它才会追加一条带来源的 `user/message`。快照追加在现有历史之后、`step/start` 之前，因此策略变化时仍会保留此前的系统与对话缓存前缀。会话事件本身可以重建确切的模型输入；只有策略上下文变化时，`request/header` 仍逐字节相同。
 
-归属范围保持收敛。批准策略会将其完整的当前 `ask` 或 `never` 事实贡献给同一份完整快照；只迁移沙箱无法保留缓存，因为 `/permission` 会同时改变两方。计划模式仍由 `plan:policy` 负责，工具插件也继续负责各自的 schema，以及尝试、拒绝与升级引导。上下文负责说明常驻策略；文件系统、一次性 bash 与终端后端仍是强制执行边界。
+归属范围仍然有限。批准策略会将其完整的当前 `ask` 或 `never` 事实贡献给同一份完整快照；只迁移沙箱无法保留缓存，因为 `/permission` 会同时改变两方。计划模式仍由 `plan:policy` 负责，工具插件也继续负责各自的 schema，以及尝试、拒绝与升权引导。上下文负责说明常驻策略；文件系统、一次性 bash 与终端后端仍是强制执行边界。
 
 缓存决策依据当前源码，而不只依靠类比。Codex 将权限建模为 developer 角色的 `WorldState` 段并保存其指纹；只有状态变化或保留的历史丢失该片段时才发出它，同时记录快照转换。Hermes 在会话期间保持系统提示词不变，并明确将不断变化的 skill（技能）、模型与语音通知前置到下一条用户消息，以免提示词缓存失效。Pi 没有可比的内置沙箱状态，Claude Code 当前的原生实现也无法公开检视；不过，Anthropic 的公开缓存指南仍将不断变化的逐请求上下文放在稳定缓存前缀之后。
 
@@ -26,7 +26,7 @@ Status: implemented
 
 ## 措辞证据
 
-措辞实验预先登记「预防性拒绝」为主要终点，并要求旧常驻句子在十二个 fresh session 中至少产生一次拒绝，之后才能评判任何替代措辞。2026-07-30，commit `2bf41990401b194bd8637f07bbd90c67a9eeac75` 通过已交付的 Web 组合运行 `deepseek-v4-flash`，使用精确的阳性对照句子 `Bash commands run under the "read-only" file sandbox.` 与当前工具归属方的尝试引导。对照组产生零次预防性拒绝和零次推测性升级；十二个会话全部先发起普通 bash 调用、观察到拒绝、在同一轮次升级、获得批准，并让所请求文件实际落盘。没有样本被排除。
+措辞实验预先登记「预防性拒绝」为主要终点，并要求旧常驻句子在十二个 fresh session 中至少产生一次拒绝，之后才能评判任何替代措辞。2026-07-30，commit `2bf41990401b194bd8637f07bbd90c67a9eeac75` 通过已交付的 Web 组合运行 `deepseek-v4-flash`，使用精确的阳性对照句子 `Bash commands run under the "read-only" file sandbox.` 与当前工具归属方的尝试引导。对照组产生零次预防性拒绝和零次推测性升权；十二个会话全部先发起普通 bash 调用、观察到拒绝、在同一轮次升权、获得批准，并让所请求文件实际落盘。没有样本被排除。
 
 缓存安全交付变更后，commit `10d4e0ff7b68d38fc4403403b644aac442b97a00` 通过新的尾部上下文通道重复了同一项十二会话阳性对照。结果再次为零次预防性拒绝和零次推测性升权；十二个会话的首次调用均为普通调用，随后观察到拒绝、在同一轮次升权并获得批准。其中八个会话让所请求文件按确切要求落盘，没有样本被排除。
 
@@ -42,7 +42,7 @@ Status: implemented
 
 **把当前策略放入动态系统段。** 不予采用，因为真实提供方证据显示，首次权限切换后缓存读取降至 256 个 token，而约 14.7k 个输入 token 未命中缓存。DeepSeek 匹配完整前缀；改变第一条 wire 消息会阻止复用更长的系统与历史前缀。
 
-**由每个策略归属方独立调用 `agent.inject()`。** 不予采用，因为同级监听器的顺序会决定模型所见顺序，分开的消息可能暴露不匹配的中间快照，并且每个归属方都需要各自扫描压缩后的保留状态。现有组装归属方可以对贡献排序，并具体化一份原子化的完整快照。
+**由每个策略归属方独立调用 `agent.inject()`。** 不予采用，因为同级监听器的顺序会决定模型所见顺序，分开的消息可能暴露不匹配的中间快照，并且每个归属方都需要各自扫描压缩后的保留状态。现有组装归属方可以对贡献排序，并生成一份原子化的完整快照。
 
 **通用运行时事实包。** 不予采用，因为现有系统提示词组装已经拥有段、schema、变量、作用域和权威的逐步骤 waterfall（瀑布式事件）。为该归属方增加有序上下文，无需新增包或第二个注册表服务。
 
@@ -50,7 +50,7 @@ Status: implemented
 
 **缓存安全迁移后仍保留 Candidate A。** 不予采用，因为中性的真实提供方任务中，尽管已有 bash 尝试引导，模型仍以纯文本拒绝，且没有调用工具。保留下来的反预防性拒绝原则本身不说明任何升权机制；它告诉模型不要从常驻标签推断操作不可能完成，然后把拒绝与升权行为交还给可用工具。
 
-**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具契约下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
+**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具约定下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
 
 **独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合 seam 和额外的文档／门禁表面。
 
@@ -60,4 +60,4 @@ Status: implemented
 
 模型在试探工具前就会收到常驻文件策略，且 `/permission` 后的下一个请求会反映已提交的模式。稳定的系统提示词不再随沙箱或批准状态变化；变化后的完整上下文快照会在保留的历史之后仅追加，状态不变时不增加消息。较旧的快照仍保留在历史中，但最新的完整快照会明确取代它们。该声明是引导，而不是强制执行护栏：运行时安全仍来自文件系统、一次性 bash 与终端后端消费同一项解析完成的策略。
 
-聚焦测试固定了所有模式、规范化根目录、切换时机、服务释放、上下文顺序、清除、稳定的请求 header、恢复，以及不同 `TMPDIR` 值下的字节稳定性。无密钥的组装快照通过真实 Loader 组合固定持久上下文消息。无密钥回放负责固定中性的拒绝到升级轨迹；它是结构回归证明，而不是措辞选型证据。
+聚焦测试固定了所有模式、规范化根目录、切换时机、服务释放、上下文顺序、清除、稳定的请求 header、恢复，以及不同 `TMPDIR` 值下的字节稳定性。无密钥的组装快照通过真实 Loader 组合固定持久上下文消息。无密钥回放负责固定中性的拒绝到升权轨迹；它是结构回归证明，而不是措辞选型证据。
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 418c81f17d..9a60eff44c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
 2026-07-30-deepseek-onboarding-credential-setup.md: 419ea0aea56e82e301189d90d5ca78495da2da71
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 936402c9ed83eccc3d5e78a57247f06347522c0f
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 46d23d40bc689a2827721e8b5cef47825355266f
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 936402c9ed..46d23d40bc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -12,15 +12,15 @@ Status: implemented
 
 **Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
 
-**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
+**设置外壳只贡献排序与导航，不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为约定；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
-**首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。
+**首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。设置或凭据能力不可用时，界面会保留相应的部署诊断，并将用户引导至同一页面；适配器缺失时则仍跳过该步骤，因为导航无法挂载 Cordis 插件。
 
-**不可用状态不会占住产品。** 可配置提供方条目缺失、路由不活跃、初始联接失败、部署只读或设置／凭据能力无法解析时，都会直接完成而不渲染该步骤，因为首次使用引导无法修复这些状态。Models 页仍是部署诊断与重试界面。「稍后配置」只会完成协调器当前这一次缺少凭据的步骤，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
+**不可用状态不会占住产品。**可配置提供方条目缺失、路由不活跃、初始联接失败、部署只读或设置／凭据能力无法解析时，都会直接完成而不渲染该步骤，因为首次使用引导无法修复这些状态。Models 页仍是部署诊断与重试界面。「稍后配置」只会完成协调器当前这一次缺少凭据的步骤，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
 
 ## 曾考虑的替代方案
 
-**为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 槽位的伴随信息、凭据引用及失效事件顺序。
+**为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 伴随文件、凭据引用及失效事件顺序。
 
 **在首次使用引导中增设第二个 API key 编辑器**：不予采用，因为 Models 页已为这一状态渲染 DeepSeek 设置卡片。复制其中的 secret 草稿、写入错误处理和已配置状态收敛会增加第二个安全敏感的 UI，却不会带来新的用户能力。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index 1ceb5a5213..a23468b591 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
 2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
-2026-07-30-queued-manual-compaction.zh.md: 29c3b921d0d59527aa1d8af1c91d085b52045377
+2026-07-30-queued-manual-compaction.zh.md: c995fc59fda83de639b6e1a603448243ba12c505
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index 29c3b921d0..c995fc59fd 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 维护阶段不会创建第二个队列。之后发送的项保留其 `MessageId`、位置、FIFO 顺序与唤醒信息。会唤醒的输入会保持排队，直至维护任务结算，再启动既有驱动器路径；`inject()` 仍然不会唤醒驱动器。
 
-`whenIdle()` 会把维护任务及其结算后释放的所有唤醒工作视为尚未完成的活动。取消会中止 agent 自有的维护信号，生命周期 teardown 则会在 dispose（资源释放）完成前排空同一个活动边界。
+`whenIdle()` 会把维护任务及其结算后释放的所有唤醒工作视为尚未完成的活动。取消会中止 agent（智能体）自有的维护信号，生命周期 teardown 则会在 dispose（资源释放）完成前排空同一个活动边界。
 
 ### 一个参数化事务拥有每一对标记
 
@@ -89,7 +89,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 **同时使用持久标记与进程本地 mutex。** 不予采用，因为两项权威在回放后可能产生分歧，还会要求用包装层分支处理标记对已经表达的状态。
 
-**与唤醒提示词一起阻塞注入。** 不予采用，因为按契约，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
+**与唤醒提示词一起阻塞注入。** 不予采用，因为按约定，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
 
 **要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
 
@@ -97,9 +97,9 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 ## 验证
 
-Agent loop 测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命周期、会唤醒和静默的排队工作、幂等释放、`whenIdle()`、取消与 teardown。压缩测试覆盖独立与数字形式的不变量 owner、end-seed 回放、活动与陈旧未匹配标记、listener 重入、所选 span 漂移、commit 与闭合失败、flush 顺序、原始取消原因、raw output 与 usage 保留，以及自动／手动互斥。
+agent loop（智能体循环）测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命周期、会唤醒和静默的排队工作、幂等释放、`whenIdle()`、取消与 teardown。压缩测试覆盖独立与数字形式的不变量 owner、end-seed 回放、活动与陈旧未匹配标记、listener 重入、所选 span 漂移、commit 与闭合失败、flush 顺序、原始取消原因、raw output 与 usage 保留，以及自动／手动互斥。
 
-命令包固定注册行为、Loader 组合、参数拒绝、精确的成功／失败文本、取消、不进入模型历史的保证，以及处置操作在中止使执行器停止等待处理器后，仍会跨越相互独立的闭合与 flush 边界等待该处理器结算。客户端运行时投影测试固定 end-seed 中断，以及随后一次独立尝试的完成。`queued-manual-compact` 终端快照通过已组装 TUI 驱动真实按键：`/help` 可发现该命令；被暂停的摘要会接纳一个排队提示词和即时注入；`turn: null` 标记与 flush 先于排队提示词轮次；命令生命周期保持纯日志；派生顺序固定为检查点 → 注入 → 排队提示词。
+命令包固定注册行为、Loader 组合、参数拒绝、精确的成功／失败文本、取消、不进入模型历史的保证，以及 dispose 在中止使执行器停止等待处理器后，仍会跨越相互独立的闭合与 flush 边界等待该处理器结算。客户端运行时投影测试固定 end-seed 中断，以及随后一次独立尝试的完成。`queued-manual-compact` 终端快照通过已组装 TUI 驱动真实按键：`/help` 可发现该命令；被暂停的摘要会接纳一个排队提示词和即时注入；`turn: null` 标记与 flush 先于排队提示词轮次；命令生命周期保持纯日志；派生顺序固定为检查点 → 注入 → 排队提示词。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index f26524cdc3..9f2a4c87ab 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md
 2026-07-30-search-render-card.md: 29544cb703f3ab048f4e7702935887ecf05179bf
-2026-07-30-search-render-card.zh.md: e0ae21924e82152ba629ab628476113ad9afe3d8
+2026-07-30-search-render-card.zh.md: e4cb39f562ea54b03e2b502ec19a90571c22e5e3
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index e0ae21924e..e4cb39f562 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：搜索渲染意图 —— grep 与 glob 产出结构化搜索卡片
+# Agent Note: 搜索渲染意图 —— grep 与 glob 产出结构化搜索卡片
 
 Status: implemented
 
@@ -8,7 +8,7 @@ Status: implemented
 
 `grep` 与 `glob` 返回结构化的 canonical 值 —— `grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`，`glob` 是 `{ paths: string[] }` —— 但每个 UI 只见过它们面向模型的渲染文本：`grep` 把匹配按文件头分组、每行 `Line N:`，`glob` 打印换行连接的路径列表，两者在内联上限（`grepMaxMatches`，默认 250；`globMaxResults`，默认 100）把后续结果落到 spill 文件时都追加一个 spill 脚注。想把搜索结果渲染成可展开的按文件匹配组、或可选择的路径列表的 web 前端，只能去重新解析那段文本。两个工具都已声明调用时的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)（`GenericCallView`，`kind: 'search'`），但没有结果时视图，所以已完成的调用回退到渲染原始文本的 generic 卡片。
 
-结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
+结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
 
 ## 决定
 
@@ -30,7 +30,7 @@ Status: implemented
 
 `SearchMeta` 的成员形状是对象字面量 `type` 别名，而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口，因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名；两者结构等价，所以投影值仍读回为 `SearchResultView`。
 
-没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端契约及其两个生产者。
+没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR（Pull Request）之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
 
 ## 考虑过的备选
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **把面向模型的文本作为视图的 `content` 附上。** 否决：对每个当前消费方是 no-op，且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状；文本回退读原始结果内容。
 
-**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策契约与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
+**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
 
 **镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决：搜索调用在 `execute` 前没有匹配或路径，视图只会携带 `GenericCallView` 已有的标题。
 
@@ -57,5 +57,5 @@ Status: implemented
 ## 相关
 
 - [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
-- [Canonical 工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
+- [Canonical 工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所依托的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片通过 `meta` 传输。
 - [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
index 10de05ea42..0762a4d131 100644
--- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
 2026-07-30-versioned-gui-welcome-onboarding.md: 4707769d4fa9fbf184e09a2e73087dfd326070be
-2026-07-30-versioned-gui-welcome-onboarding.zh.md: c9d2e6274c476c59abc077aa3255ffe57a8a48bc
+2026-07-30-versioned-gui-welcome-onboarding.zh.md: 002a04b1fc6acc4fc7cfee053bdbbb2abaef047e
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
index c9d2e6274c..002a04b1fc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
@@ -14,11 +14,11 @@ GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始，但内部测
 
 **不属于单一功能的产品引导由 `ui-settings-general` 持有。** `src/onboarding-copy.ts` 是完整通知、「继续」按钮文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文所有者文案。运行时 locale 字典从该文件派生欢迎文案，测试也导入同一个所有者，而不重复段落文本。该通知只存在于浏览器 UI：它不会创建会话事件，也不会贡献任何模型可见内容。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
 
-**loopback 确认状态按 Harness profile 持久化。** 宿主端在 user-settings seam 中注册 `ui-onboarding` 分节，并存入当前 `$DSH_HOME/settings.yaml`。connection 插件通过 `ctx.connection.isLoopback` 统一发布当前页面是否使用 loopback authority；hostname 判定函数留在 connection 包内，其他客户端插件只消费服务状态，不跨插件导入实现函数。除非 `welcomeNoticeVersion` 与文案所有者文件中的常量精确相等，否则 loopback 浏览器会显示通知。「继续」会以当前版本执行一次路径变更，并且仅在宿主端提交成功后调用 `complete()`；写入失败时通知保持打开，关闭页面或进程则不会写入任何内容。提升该常量会有意要求每个 profile 对修订后的文案重新确认一次。非 loopback 浏览器不能调用仅限 loopback 的 settings API；它仍显示同一通知，但显式点击「继续」只会在当前浏览器进程中完成该步骤，重新加载或新进程会再次显示通知。
+**loopback 确认状态按 Harness profile 持久化。** 宿主端在 user-settings seam 中注册 `ui-onboarding` 分节，并存入当前 `$DSH_HOME/settings.yaml`。connection 插件通过 `ctx.connection.isLoopback` 统一发布当前页面是否使用 loopback authority；hostname 判定留在 connection 包内，其他客户端插件只消费服务状态，而不导入其实现。除非 `welcomeNoticeVersion` 与文案所有者文件中的常量精确相等，否则 loopback 浏览器会显示通知。「继续」会以当前版本执行一次路径变更，并且仅在宿主端提交成功后调用 `complete()`；写入失败时通知保持打开，关闭页面或进程则不会写入任何内容。更新该常量会有意要求每个 profile 对修订后的文案重新确认一次。非 loopback 浏览器不能调用仅限 loopback 的 settings API；它仍显示同一通知，但显式点击「继续」只会在当前浏览器进程中完成该步骤，重新加载或新进程会再次显示通知。
 
-**并发 loopback 视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`：每个 loopback 标签页都向同一路径写入相同版本，因此该操作是幂等的，并会保留同级字段，而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`；另一个标签页或外部编辑器提交当前版本后，已挂载的 loopback 标签页会重新拉取状态并推进。API 网关在可配置提供方 namespace 之外，通过封闭的允许列表暴露这一个产品 namespace，同时不会把它的变更视为模型目录失效事件。
+**并发 loopback 视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`：每个 loopback 标签页都向同一路径写入相同版本，因此该操作是幂等的，并会保留同级字段，而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`；另一个标签页或外部编辑器提交当前版本后，已挂载的 loopback 标签页会重新拉取状态并推进。API Proxy（`@deepseek-ai/dsh-host-apiproxy`）在可配置提供方 namespace 之外，通过封闭的允许列表暴露这一个产品 namespace，同时不会把它的变更视为模型目录失效事件。
 
-**引导流程会暂时接管视口，形成一个连续阶段。** 纯色产品界面通过挂载到 `body` 的 portal 取代完整的应用视图，并将底层应用根节点标记为 inert；严格符合要求的遮罩仍挂载在该界面后方，并保留 `position:absolute`、left/right/bottom 偏移量为零、`top:80px`、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。欢迎页和按条件显示的凭据设置页在这一阶段中依次呈现，而不是各自作为独立的模态窗口。两个页面都复用 Web UI 的黑色 `BrandWordmark`。欢迎页在 `内测声明` 标题下逐字保留既定的四段文案；所有段落统一采用 16/28 的正文字号与行高，只有最后一段中指定的行动语句使用较为克制的 500 字重。短暂的错落式透明度与纵向位移动画营造出舒缓节奏，但不会阻碍交互，并会在用户启用减少动态效果时禁用。初始焦点落在标题上，「继续」是唯一按钮，且不存在关闭、Escape 或点击遮罩的退出路径。
+**引导流程会暂时接管视口，形成一个连续阶段。** 纯色产品界面通过挂载到 `body` 的 portal 取代完整的应用视图，并将底层应用根节点标记为 inert；严格符合要求的遮罩仍挂载在该界面后方，并保留 `position:absolute`、left/right/bottom 偏移量为零、`top:80px`、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。欢迎页和按条件显示的凭据设置页在这一阶段中依次呈现，而不是各自作为独立的模态窗口。两个页面都复用 Web UI 的黑色 `BrandWordmark`。欢迎页在 `内测声明` 标题下逐字保留既定的四段文案；所有段落统一采用 16/28 的正文字号与行高，只有最后一段中指定的行动语句使用较为克制的 500 字重。短暂的错落式透明度与纵向位移动画营造出节奏感，但不会阻碍交互，并会在用户启用减少动态效果时禁用。初始焦点落在标题上，「继续」是唯一按钮，且不存在关闭、Escape 或点击遮罩的退出路径。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始，但内部测
 
 **在渲染或窗口关闭时持久化**：不予采用，因为看见通知不等于确认，窗口关闭事件也无法可靠送达。只有显式提交「继续」才能阻止通知在下次启动时再次显示。
 
-**通用的公开设置暴露标志**：不予采用，因为一个产品 namespace 不足以证明应当扩大每个 settings 注册方的公开配置面。网关保留显式的封闭允许列表。
+**通用的公开设置暴露标志**：不予采用，因为一个产品 namespace 不足以证明应当扩大每个 settings 注册方的公开配置面。该 API Proxy 保留显式的封闭允许列表。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index d78733bb33..c848bc3822 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
 2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
-2026-07-30-web-diff-card.zh.md: a9c710df99c1060bbf50b591b2f62120dc7dcbef
+2026-07-30-web-diff-card.zh.md: bf9424a9baff7ec6d49949016be3e30d400f2dd1
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index a9c710df99..bf9424a9ba 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -6,15 +6,15 @@ Status: implemented
 
 ## Problem
 
-`write` 和 `edit` 工具为其 call 和 result 都声明了 `card: 'diff'`（[render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)）：call view 携带从参数推导的预期改动，result view 携带已应用的上下文 hunk（`FileDiff[]`，由 `packages/fs/tool-fs/src/diff.ts` 计算，并持久化在 result `meta` 中以便回放重建）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `callView`/`resultView` 投递到 `ConversationSnapshot` —— TUI 也已将其渲染为按文件分组的 `+`/`-` 块加 `+A -R · N file(s)` 页脚。
+`write` 和 `edit` 工具为其 call 和 result 都声明了 `card: 'diff'`（[render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)）：call view 携带从参数推导的预期改动，result view 携带已应用的上下文 hunk（`FileDiff[]`，由 `packages/fs/tool-fs/src/diff.ts` 计算，并持久化在 result `meta` 中以便回放重建该视图）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `callView`/`resultView` 投递到 `ConversationSnapshot` —— TUI 也已将其渲染为按文件分组的 `+`/`-` 块加 `+A -R · N file(s)` 页脚。
 
-Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行从原始工具参数推导，详情面板把 result 的 content block 摊平进一个 `<pre>`。`diffs` 载荷 —— result 的全部意义 —— 被丢弃，于是一次文件改动读起来只是一行确认、看不到任何改动。
+Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行从原始工具参数推导，详情面板把 result 的 content block 摊平进一个 `<pre>`。`diffs` 载荷 —— result 的关键所在 —— 被丢弃，于是一次文件改动读起来只是一行确认、看不到任何改动。
 
-这是把 [terminal 卡片](2026-07-28-web-terminal-card.md) 对 `diff` 这一支重做一遍：那次改动让 Web 客户端成为 `terminal` 渲染意图的消费者；这次让它成为 `diff` 渲染意图的消费者，复用同一套四层结构。
+这是把 [terminal 卡片](2026-07-28-web-terminal-card.md) 对 `diff` 这一支重做一遍：那次改动让 Web 客户端成为 `terminal` 渲染意图的消费方；这次让它成为 `diff` 渲染意图的消费方，复用同一套四层结构。
 
 ## Decision
 
-`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/tool/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
+`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/tool/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时（包括 `card` 值为本客户端版本所不认识的值），以及已结算调用的 result view 是 generic 时，它返回 null——走通用路径；write/edit 的执行错误正是这样留在通用路径上的。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
 该组件与 TUI 共用单栏框架、行终止符规则和去重路径计数。两者的行分类不同：Web 渲染完整的变更前后两侧，而 TUI 会在有界比较完成时派生中性上下文和精确变更行，并把整侧回退标记为近似结果。
 
@@ -24,23 +24,23 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 - **行终止符。** 每一侧的内容按 `TerminalBlock` 与 TUI 共用的终止符规则在 `\n` 上切分：空文本是零行（整文件删除的 `newText`、新建缺失的 `oldText` 侧），单个结尾换行终止其最后一行而非新增一条幻影空行，内部空行保留。
 - **页脚与复制。** 暗色 `└ +A -R · N file(s)` 页脚报告 Web 卡片完整新侧与旧侧的行数。TUI 页脚则在可用时报告精确变更行数，并把有界整侧回退标记为近似结果；两者使用相同的去重路径计数。复制控件复制带前缀的 Web diff 文本（路径头、`- `/`+ ` 行、`⋯` gap），使多文件复制保持可辨别归属。
 
-几何、圆角、字体镜像 `CodeBlock`/`TerminalBlock`，使 diff 卡片、terminal 卡片、代码块读起来是一家；`white-space: pre` 加横向滚动是刻意的分歧。复制控件浮在卡片右上角，而非占据自己的 banner 行，因为只放一个复制按钮的 banner 会在第一行 diff 上方画出一条空带 —— TUI 的 diff 卡片也没有 banner，只有页脚。
+几何、圆角、字体与 `CodeBlock`/`TerminalBlock` 保持一致，使 diff 卡片、terminal 卡片、代码块读起来是一家；`white-space: pre` 加横向滚动是刻意的分歧。复制控件浮在卡片右上角，而非占据自己的 banner 行，因为只放一个复制按钮的 banner 会在第一行 diff 上方画出一条空带 —— TUI 的 diff 卡片也没有 banner，只有页脚。
 
-chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX_LINES`（8），对应面板的 16 —— 与 [terminal 卡片](2026-07-28-web-terminal-card.md#inline-output-in-the-chat-row-reverses-a-stated-convention)记录的内联输出决策、以及流内表面对单调阅读表面的同一划分一致。write/edit 行是单文件的，所以它的摘要既是可打开的路径链接，其 diff 卡片又展开；两者共存，因为卡片不是路径的参数体。
+chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX_LINES`（8），对应面板的 16 —— 与 [terminal 卡片](2026-07-28-web-terminal-card.md#inline-output-in-the-chat-row-reverses-a-stated-convention)记录的内联输出决策、以及流内表面与阅读表面的同一划分一致。write/edit 行是单文件的，所以它的摘要既是可打开的路径链接，其 diff 卡片又展开；两者共存，因为卡片不是路径的参数体。
 
 ## Alternatives considered
 
 **并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
 
-**git 式行号槽。** `FileDiff` 契约只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端契约改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有契约的纯 Web 消费。
+**git 式行号栏。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号栏需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有约定的纯 Web 消费。
 
 **复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
 
 ## Consequences
 
-`DiffBlock` 只读 diff view 的字段，因此它是渲染意图所携带内容的纯函数 —— 与产出该视图的 presenter 一样回放安全。没有 diff 能力的 UI 仍得到 bridge 的通用回退；工具的 result 形状没有任何改变。无新增运行时依赖：不同于 terminal 卡片的 `anser`，diff 不需要解析器。
+`DiffBlock` 只读 diff view 的字段，因此它是渲染意图所携带内容的纯函数 —— 与产出该视图的 presenter 一样回放安全。没有 diff 能力的 UI 仍得到 bridge 的通用回退；工具结果的形状没有任何改变。无新增运行时依赖：不同于 terminal 卡片的 `anser`，diff 不需要解析器。
 
-`DiffBlock` 的多文件支路（一张卡、多个路径头）今天没有生产者：`write`/`edit` 每次调用各改一个文件，所以真实卡片显示一个文件带一个或多个 hunk。该支路为将来的多文件改动工具而构建并测试，不是为当前消费者。
+`DiffBlock` 的多文件支路（一张卡、多个路径头）今天没有生产者：`write`/`edit` 每次调用各改一个文件，所以真实卡片显示一个文件带一个或多个 hunk。该支路为将来的多文件改动工具而构建并测试，不是为当前消费方。
 
 ## Testing
 
@@ -48,10 +48,10 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 `packages/client/ui-tool/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。
+fixture（测试前置数据）（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot 快照（`apps/web/tests/built-boot.snapshot.ts`）是启动装配冒烟测试，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身约定它不带 diff 行为断言，那由接线套件负责。
 
 ## Related
 
-- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— `terminal` 支路的同一套四层结构；本 note 复用其内联输出决策与头尾上限算术。
-- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本改动消费的 `card` 标签词汇；Web 客户端现在也是 `diff` 支路的消费者。
+- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— `terminal` 支路的同一套四层结构；本文复用其内联输出决策与头尾上限算术。
+- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本改动消费的 `card` 标签词汇；Web 客户端现在也是 `diff` 支路的消费方。
 - [Web 客户端架构](../architecture/2026-07-19-gui-web-client-architecture.md) —— 两个渲染点所处的 slot 与快照分层。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
index 624da25dc2..d55bdac61c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.md
 2026-07-30-web-queue-steer-action.md: b04095b81f499982c8680a2d3627d8e98a70d8ac
-2026-07-30-web-queue-steer-action.zh.md: b04902b8a8a0d727b01aa6ba5562e12cc5d36c92
+2026-07-30-web-queue-steer-action.zh.md: 1b46ec90a27fbc3c8f3660a7cbdccb78a21a2cfa
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
index b04902b8a8..1b46ec90a2 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：将 Web 已排队消息转为活动轮次的 steering（中途引导）
+# Agent Note: 将 Web 已排队消息转为活动轮次的 steering（中途引导）
 
 Status: implemented
 
@@ -6,21 +6,21 @@ Status: implemented
 
 ## 问题
 
-Web composer 原本会在 agent 运行期间把所有 Enter 提交作为 Queue 入队。QueueDock 已经为每条待处理消息提供可寻址的行，持久 transcript（文本记录）也已能把消费后的 steer 事件渲染为用户样式气泡，但 Web 既没有连接这两个界面的操作，也没有让用户从 composer 直接选择当前轮次 steering 的手势。
+Web composer 原本会在 agent（智能体）运行期间把所有 Enter 提交作为 Queue 入队。QueueDock 已经为每条待处理消息提供可寻址的行，持久 transcript（文本记录）也已能把消费后的 steer 事件渲染为用户样式气泡，但 Web 既没有连接这两个界面的操作，也没有让用户从 composer 直接选择当前轮次 steering 的手势。
 
 如果 Web 先在客户端删除该行，再调用 `session.prompt(mode: 'steer')`，就会把用户的一次意图拆分到两个 RPC 中。驱动器可能在两次调用之间先认领该项，steering 投递也可能在删除后失败；现有尽力而为的 `agent.steer()` 回退还可能在原单次入队项被移除后，静默追加一个新的 Queue 项。因此，立即发送操作必须区分当前轮次 steering 与 Queue 前移，并在 steering 已不可用时保留原行。
 
 ## 决策
 
-### 产品契约
+### 产品约定
 
-普通会话中每个非编辑态的 QueueDock 行都会提供名为“插话发送”的向上箭头操作。仅当会话报告 agent 正在运行时，该操作才会启用；包含混合内容的消息仍可使用，因为 steering 会转发完整且不可变的 `UserMessage`，而非该行的文本投影。已寻址 subagent 的 Queue 投影保持只读，因为其继续执行传输不提供 Queue 变更。
+普通会话中每个非编辑态的 QueueDock 行都会提供名为「插话发送」的向上箭头操作。仅当会话报告 agent 正在运行时，该操作才会启用；包含混合内容的消息仍可使用，因为 steering 会转发完整且不可变的 `UserMessage`，而非该行的文本投影。已寻址 subagent 的 Queue 投影保持只读，因为其继续执行传输不提供 Queue 变更。
 
 触发该操作会针对对应的 `InboxItemId` 请求严格的当前轮次 steering。操作成功后，权威 Host 快照会移除 Queue 行，并在 `Deep diving...` 运行状态行之后立即投影同一条待处理 steering；该气泡提供复制，但消息尚无持久事件序号，因此不提供 fork。AgentLoop 排空该项后，现有持久 `user/message` 事件会接管同一个用户样式气泡，并恢复时钟、复制和 fork，无需另建持久展示路径。
 
 running 标志位只用于提示交互状态。在同步变更边界上，AgentLoop 的 `acceptsNextStep` 值才是权威依据。如果该窗口已经关闭，操作会保持 Queue 单次入队项不变并返回类型化的 `steer-unavailable` 错误，随后原唤醒单次入队项会经 Queue 继续执行。如果驱动器已经认领该项，则返回现有的 `queue-item-not-found` 错误，且独立轮次投递已经开始。UI 会把两种竞态都视为已收敛的 Queue 投递，不显示失败通知；传输和未知错误仍会显示。
 
-Composer 对新输入采用另一套尽力而为契约。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
+Composer 对新输入采用另一套尽力而为约定。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
 
 ### Agent 与生命周期边界
 
@@ -34,15 +34,15 @@ Composer 对新输入采用另一套尽力而为契约。所寻址会话空闲
 
 `session.updateQueue` 会携带 `steer` 操作，并把两种负面结果映射为类型化 RPC 错误。这项转换是一次同步 Agent 操作；Host 绝不会通过组合移除和提示词调用来重建它。
 
-Host 仍以现有 `queuedMirror` 作为唯一的瞬态 inbox 权威。`session/queue` 快照会携带所有存活单次入队项及其 `placement: 'queued' | 'steering'`：QueueDock 只渲染 queued 行，ChatView 则在会话流末尾、`Deep diving...` 运行状态行之后渲染待处理 steering，提供复制操作，但不提供 fork、编辑或删除操作。重连会重放同一份快照，因此这项可见性既不依赖客户端乐观展示，也不需要第二个 registry。
+Host 仍以现有 `queuedMirror` 作为唯一的瞬态 inbox 权威。`session/queue` 快照会携带所有存活单次入队项及其 `placement: 'queued' | 'steering'`：QueueDock 只渲染 queued 行，ChatView 则在会话流末尾、`Deep diving...` 运行状态行之后渲染待处理 steering，提供复制操作，但不提供 fork、编辑或删除操作。重连会重放同一份快照，因此这项可见性既不依赖客户端乐观展示，也不需要第二个注册表。
 
-AgentLoop 认领待处理 steering 时，会在同步追加持久 `user/message` 之前立即发出 `agent/inbox/dequeue`。Host 会等到下一个微任务才退役该 steering 行，让持久 session 事件先进入线性 mux 流。客户端 Session 接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史回放不会消费后来复用同一 `MessageId` 的单次入队项。因此，ChatView 无需扫描持久历史就能每次只渲染一份权威，持久投影则会根据已记录的事件时间与序号恢复时钟、复制与 fork 操作。追加失败时，已认领行仍会退役。
+AgentLoop 认领待处理 steering 时，会在同步追加持久 `user/message` 之前立即发出 `agent/inbox/dequeue`。Host 会等到下一个微任务才退役该 steering 行，让持久会话事件先进入线性 mux 流。客户端 Session 接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史回放不会消费后来复用同一 `MessageId` 的单次入队项。因此，ChatView 无需扫描持久历史就能每次只渲染一份权威，持久投影则会根据已记录的事件时间与序号恢复时钟、复制与 fork 操作。追加失败时，已认领行仍会退役。
 
-现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的契约：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该契约。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
+现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的约定：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该约定。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
 
 ### 验证
 
-AgentLoop 契约覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
+AgentLoop 约定覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
 
 Host schema 和代理测试覆盖新操作、两种类型化错误、带 placement 的快照与重连重放，以及先持久化再退役的顺序。客户端测试覆盖两种语义竞态的静默收敛、真实错误报告、只读 subagent 行和仅支持 Queue 的 subagent 手势。运行时与 ChatView 测试覆盖按单次入队项完成的待处理到持久交接，包括重复的 `MessageId` 值；Web ARIA 快照则覆盖位于运行状态行之后且仅有复制的待处理 steering，以及带时钟、复制和 fork 的持久节点。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
index 9bde6a14c7..66e7d02fab 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card.md
 2026-07-30-web-read-card.md: 26d1634b6be86666980e65f842de51c868c26efd
-2026-07-30-web-read-card.zh.md: 749177e93e8e3b2e34aed46d1fe99226395a6686
+2026-07-30-web-read-card.zh.md: f8d63cb8be8dc9e469aa6a29bdb7611634cbb861
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
index 749177e93e..f8d63cb8be 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`read` 工具返回规范化输出对象 `{ path, offset, lines: [{ number, text }], totalLines }`，但它的展示层把这个结构压平了。`presentCall` 声明为 `GenericCallView`（`kind: 'read'`，一个跟随定位），`presentResult` 返回 `GenericResultView`，其唯一内容是剥掉 `<path>…</path><type>file</type><content>…</content>` 信封后的面向模型文本。收到该视图的 UI 只看到一个压平的文本块：行号以 `N: ` 前缀烘焙进文本、文件语言未知、`totalLines` 丢失。capable 客户端无法像渲染 diff 那样渲染一次 read——即带行号、语法高亮、行号槽与内容分离的代码视图。
+`read` 工具返回规范化输出对象 `{ path, offset, lines: [{ number, text }], totalLines }`，但它的展示层把这个结构压平了。`presentCall` 声明为 `GenericCallView`（`kind: 'read'`，一个跟随定位），`presentResult` 返回 `GenericResultView`，其唯一内容是剥掉 `<path>…</path><type>file</type><content>…</content>` 信封后的面向模型文本。收到该视图的 UI 只看到一个压平的文本块：行号以 `N: ` 前缀烘焙进文本、文件语言未知、`totalLines` 丢失。具备相应能力的客户端无法像渲染 diff 那样渲染一次 read——即带行号、语法高亮、行号槽与内容分离的代码视图。
 
 结构化数据在下游无法恢复。线上（wire）的工具结果只携带面向模型的 `ContentBlock[]`（已渲染文本）加上一个不透明的 `meta`；规范化输出对象留在工具内，从不到达客户端或会话日志。因此想要行数组、总数和语言提示的客户端无法从 `N: text` 文本里解析回它们——工具必须把它们投影到一个会持久化的通道上。
 
@@ -14,13 +14,13 @@ Status: implemented
 
 给[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 新增第四个 `card` 标签 `read`——仅在结果侧。`ToolResultView` 增加 `ReadResultView { card: 'read'; title?; path; lines: ReadFileLine[]; totalLines; lang?; content? }`；`ReadFileLine { number; text }` 是共享的行单元。`ToolCallView` 不动：待定状态仍是 `GenericCallView`（`kind: 'read'`），因为一次调用在 `execute` 返回前不携带文件内容，调用时没有可展示的结构。这与 bash 终端 card 不同——终端 card 两侧都打标签，因为终端调用在调用时已携带命令和 cwd，而 read 调用既无内容也无总数，给调用侧打标签只会新增一个空变体。
 
-read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
+read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
 
-`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图契约的一部分。
+`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR（Pull Request）已重录全部已发布的 fixture（测试前置数据），且会话格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
 
 ### 语言提示推导
 
-`langFromPath`（在 `read-render.ts` 中）通过一张固定小表（`LANG_BY_EXTENSION`，覆盖常见源码、配置、标记扩展名）把文件扩展名映射到语法高亮语言 id。它读取最后一个路径段与最后一个点之后的扩展名，大小写不敏感，并对以下情况返回 `undefined`：dotfile（`.gitignore`）、无扩展名（`/etc/hosts`）、结尾的点、以及任何未知扩展名——此时 card 省略 `lang`，UI 渲染纯文本。该表不是可调项（tunable）：它是 UI 可忽略的展示提示，而非随部署变化的选择，未知扩展名降级为纯文本而非失败。它有意保持小规模而非穷尽的语言注册表；扩展它是一行表项新增。
+`langFromPath`（在 `read-render.ts` 中）通过一张固定小表（`LANG_BY_EXTENSION`，覆盖常见源码、配置、标记扩展名）把文件扩展名映射到语法高亮语言 id。它读取最后一个路径段与最后一个点之后的扩展名，大小写不敏感，并对以下情况返回 `undefined`：dotfile（`.gitignore`）、无扩展名（`/etc/hosts`）、结尾的点、以及任何未知扩展名——此时 card 省略 `lang`，UI 渲染纯文本。该表不是可调项（tunable）：它是 UI 可忽略的展示提示，而非随部署变化的选择，未知扩展名降级为纯文本而非失败。它有意保持小规模而非穷尽的语言注册表；扩展它只需新增一行表项。
 
 ## Alternatives considered
 
@@ -30,7 +30,7 @@ read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write
 
 **把结构化窗口放进新服务或旁路通道而非 `meta`。** 已否决：`meta` 是既有的持久化展示通道（write/edit 的应用 diff 就搭它），它随会话日志免费回放，无需新接线。服务会重新发明事件日志已提供的持久化与回放。
 
-**用 merge-extensible union 而非封闭标签。** 出于[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 封闭的相同理由否决：新 card 需要消费代码来渲染它，因此被消费者静默丢弃的变体比编译错误更糟。把 `read` 加入封闭 union 是扩展它的许可方式——每个在 `card` 上 switch 的消费者都继续编译，因为新成员落入其 generic default，而想要富视图的消费者新增自己的分支。
+**用 merge-extensible union 而非封闭标签。** 出于[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 封闭的相同理由否决：新 card 需要消费代码来渲染它，因此被消费方静默丢弃的变体比编译错误更糟。把 `read` 加入封闭 union 是扩展它的许可方式——每个在 `card` 上 switch 的消费方都继续编译，因为新成员落入其 generic default，而想要富视图的消费方新增自己的分支。
 
 ## Consequences
 
@@ -40,10 +40,10 @@ read 工具现在为每次顶层 read 计算 `presentationMeta`，这是对已
 
 ## Testing
 
-`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名的大小写不敏感、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的 opaque `meta` 边界——良构类型的回放 JSON 仍可能携带的语义无效路径：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本 PR 携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP session fixtures（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript 则属于消费它的前端变更。
+`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名（不区分大小写）、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的不透明 `meta` 边界——类型正确的回放 JSON 仍可能携带的语义无效情况：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本 PR 携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP（Agent Client Protocol）会话 fixture（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript（文本记录） 则属于消费它的前端变更。
 
 ## Related
 
-- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 Note 以 `read` 结果分支扩展的 `card` 标签词汇。
-- [Canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 拥有本 Note 用来投影 read 窗口的 `presentationMeta` 持久化通道。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 客户端消费结构化 card 的先例；read card 遵循相同的生产者模式，仅结果侧。
+- [工具调用展示的带标签渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 Note 以 `read` 结果分支扩展的 `card` 标签词汇。
+- [规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 拥有本 Note 用来投影 read 窗口的 `presentationMeta` 持久化通道。
+- [Web 终端 card](2026-07-28-web-terminal-card.md) —— 客户端消费结构化 card 的先例；read card 遵循相同的生产者模式，仅结果侧。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index 6f3a5d895b..04c1201f16 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
 2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
-2026-07-30-web-result-card-frontend.zh.md: 4cec11371e8d0848f2f03ded0b093d80cc25a7a5
+2026-07-30-web-result-card-frontend.zh.md: 6bb31797a7658adae267d034d0a6d9fa49dfe09f
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 4cec11371e..6bb31797a7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web result 卡片前端 —— 在浏览器渲染 web 渲染意图
+# Agent Note: Web result 卡片前端——在浏览器渲染 web 渲染意图
 
 Status: implemented
 
@@ -6,31 +6,31 @@ Status: implemented
 
 ## Problem
 
-`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个 `kind` 标签联合,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是契约笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
+`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个以 `kind` 为标签的联合类型,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是约定笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
 
 ## Decision
 
-`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
+`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它会在以下情况下返回 null，从而走通用路径：调用仍在运行（web 卡片是 result-only 的，因为工具保留 generic pending 视图）；调用已结算，但其 result view 不是 web 卡片，包括本客户端版本不认识的 `card` 值（它经 wire 抵达，因而不能被信任为已编译的变体）；result view 是 generic result view（web 工具的错误路径返回 generic 卡片，其文本由通用路径保留）；web 卡片的 `kind` 是本客户端版本不认识的值（更新的 host 经 wire 发来的值，读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
-一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
+一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是约定把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
-**链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集。** MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
+**链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集**。MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
 
-**几何镜像 CodeBlock/TerminalBlock**（12px 圆角、code-block 表面、16px 垂直外边距）,使 web 卡片与它们读作一家。整份 source 列表渲染在单个 `<ol>` 里,由 `max-height: 320px` 与 `overflow-y: auto` 约束,因此高于该值的列表在原地纵向滚动,而不是把卡片撑高（[来源滚动](2026-08-03-web-search-source-scroll.md)）。source 列表是散文而非按列对齐的输出,所以它正常换行,而不像终端卡片的输出那样横向滚动 —— 这是与 TerminalBlock 唯一刻意的分歧。
+**几何镜像 CodeBlock/TerminalBlock**（12px 圆角、code-block 表面、16px 垂直外边距）,使 web 卡片看起来与它们属于同一类。整份 source 列表渲染在单个 `<ol>` 里,由 `max-height: 320px` 与 `overflow-y: auto` 约束,因此高于该值的列表在原地纵向滚动,而不是把卡片撑高（[来源滚动](2026-08-03-web-search-source-scroll.md)）。source 列表是散文而非按列对齐的输出,所以它正常换行,而不像终端卡片的输出那样横向滚动 —— 这是与 TerminalBlock 唯一刻意的分歧。
 
 卡片在 chat 行中**常驻**于摘要行之下,与 `BashRow` 所用的同一常驻姿态。两个渲染点展示同一份完整的 source 列表,仅由卡片自身的滚动高度约束,而没有行与面板两级的 source 上限。键控行把一个 `WebRow` 组件注册在 `web_search` 与 `web_fetch` 两个键下;行仅根据工具名判别以选取其图标（search 对 browse）与标题（`Search`/`Fetch`）。没有自己键控行的 web 声明工具落到 `GenericToolCard`,它长出同一张常驻卡片。详情面板渲染该卡片,并在其下方渲染摊平的模型可见结果内容:`web_fetch` 卡片只携带 URL 与状态,因此其抓取正文只在此处可读。
 
 ## Consequences
 
-`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到契约的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
+`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到约定的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
 
 一条独立的后续 PR 会统一整行折叠/展开交互,并把每张常驻卡片（terminal、diff、web）一次性翻成 expand-gated;本卡片遵循当前的常驻约定,而非抢先做那次改动。
 
 ## Alternatives considered
 
-**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而契约已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
+**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而约定已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
 
-**重解析模型可见的渲染文本,而非消费结构化视图。** 因契约笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
+**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
 
 **不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此接缝处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
@@ -40,11 +40,11 @@ Status: implemented
 
 `packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
+fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配约定的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:当前计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
 ## Related
 
-- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费者。
+- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费方。
 - [Web search 来源卡片改为滚动而非折叠](2026-08-03-web-search-source-scroll.md) —— 用定高滚动容器替换本笔记的 source 列表头/尾折叠,并移除 `CHAT_WEB_MAX_SOURCES` 与原语自身的 source 上限;本笔记的其余决策依然成立。
 - [Web terminal card](2026-07-28-web-terminal-card.md) —— 本条所镜像的先例:一个 `ui-primitives` block、一处 card-model 派生、键控与兜底 chat 行、以及一个详情面板支路,用于 `terminal` 渲染意图。
-- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费者。
+- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费方。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index 0badfa2a55..9fb81dc9c3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card.md
 2026-07-30-web-result-card.md: 838b13a7f3240c753e5cd1af6909389055c6352d
-2026-07-30-web-result-card.zh.md: 6e5170fcad82d709b050fb05e8efcfe955f20391
+2026-07-30-web-result-card.zh.md: 9b0ad72aa6f152c8f7f4594dbe80532bf9722016
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index 6e5170fcad..9b0ad72aa6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web result card — a structured render intent for web_search and web_fetch
+# Agent Note: Web 结果卡片——用于 web_search 和 web_fetch 的结构化渲染意图
 
 Status: implemented
 
@@ -6,15 +6,15 @@ Status: implemented
 
 ## Problem
 
-`web_search` 与 `web_fetch` 工具各自声明了一个 generic 待定卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图契约（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
+`web_search` 与 `web_fetch` 工具各自声明了一个 generic 等待中卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图约定（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
 
 ## Decision
 
 向 `ToolResultView`（`packages/core/tools/src/presentation.ts`）新增一个 `card: 'web'` 结果分支，它是以 `kind: 'search' | 'fetch'` 字段作判别的联合 `WebResultView = WebSearchResultView | WebFetchResultView`，并附一个表示单个可引用来源的 `WebSource` 形状。两个工具现在都声明 `presentResult`。
 
-采用一个标签加 `kind` 判别，而非两个标签。两个调用都是 web 检索，web 前端会用同一族组件渲染它们（一个检索卡片，正文按 kind 不同），因此共用一个 `card` 让每个 card 消费者的 switch 只需新增一个分支，并让前端在其内部按 `kind` 分岔。两个标签会迫使当前及未来每个消费者为本属同一视觉族的东西添加两个分支。这两个 `kind` 取值与两个工具既有的 generic 调用视图 `kind` 一致，因此一个调用与它的结果读起来是同一类别。
+采用一个标签加 `kind` 判别，而非两个标签。两个调用都是 web 检索，web 前端会用同一族组件渲染它们（一个检索卡片，正文按 kind 不同），因此共用一个 `card` 让每个 card 消费方的 switch 只需新增一个分支，并让前端在其内部按 `kind` 分岔。两个标签会迫使当前及未来每个消费方为本属同一视觉族的东西添加两个分支。这两个 `kind` 取值与两个工具既有的 generic 调用视图 `kind` 一致，因此一个调用与它的结果读起来是同一类别。
 
-`presentationMeta` 携带 render 文本无法携带的东西。工具从 `execute` 返回的结构化结果对象**不会**经由 wire 抵达客户端——只有面向模型的 `render` 文本，以及（声明时）投影到 `tool/result` 事件 `meta` 上的 `output.presentationMeta` JSON 会。对 `web_search`，meta 是得到 `{url, title?, snippet?, publishedAt?}` 的**唯一**忠实途径：render 把这些字段压进一行有损的自由文本，消费者无法重新解析。对 `web_fetch`，meta 是更小但真实的收益：`url`/`statusCode` 可从确定格式的 `Fetched <url> (HTTP <n>)` header 行还原，但 `truncated` 是有效截断——provider cap、转换前源截断，或部署的 `fetchMaxOutputChars` 输出上限——客户端无法重算，因为它不知道那个上限。抓取卡片与面向模型的文本都从同一个 `renderFetchOutput(result, maxOutputChars)` helper 派生 `truncated`，因此卡片绝不会与模型看到的脚注分叉。这照搬 write/edit 的 diff 模板（`packages/fs/tool-fs/src/diff.ts`）：一个 `*MetaFromValue` 投影器喂给 `output.presentationMeta`，一个 `*MetaFromResult` 收窄器读回 `result.meta`，并在失败时防御性回退到 generic 卡片。`web_fetch` 的正文已是结果内容中的 markdown，因此不重复写入 meta。
+`presentationMeta` 携带 render 文本无法携带的东西。工具从 `execute` 返回的结构化结果对象**不会**经由 wire 抵达客户端——只有面向模型的 `render` 文本，以及（声明时）投影到 `tool/result` 事件 `meta` 上的 `output.presentationMeta` JSON 会抵达客户端。对 `web_search`，meta 是得到 `{url, title?, snippet?, publishedAt?}` 的**唯一**忠实途径：render 把这些字段压进一行有损的自由文本，消费方无法重新解析。对 `web_fetch`，meta 是更小但真实的收益：`url`/`statusCode` 可从确定格式的 `Fetched <url> (HTTP <n>)` header 行还原，但 `truncated` 是有效截断——提供方上限、转换前源截断，或部署的 `fetchMaxOutputChars` 输出上限——客户端无法重算，因为它不知道那个上限。抓取卡片与面向模型的文本都从同一个 `renderFetchOutput(result, maxOutputChars)` helper 派生 `truncated`，因此卡片绝不会与模型看到的脚注不一致。这照搬 write/edit 的 diff 模板（`packages/fs/tool-fs/src/diff.ts`）：一个 `*MetaFromValue` 投影器喂给 `output.presentationMeta`，一个 `*MetaFromResult` 收窄器读回 `result.meta`，并在失败时防御性回退到 generic 卡片。`web_fetch` 的正文已是结果内容中的 markdown，因此不重复写入 meta。
 
 两个结果视图都不携带 `content` 副本。不渲染结构化 `web` 卡片的 UI 回退到原始 `tool/result` 内容，这也是 generic 卡片消费的输入。把结果内容复制进视图会在同一投递帧上重复最多 `fetchMaxOutputChars` 个字符却毫无收益（与 meta 一节对抓取正文的否决同理），因此视图省略它，回退路径渲染完全相同的文本。每个视图从调用参数设置其结果期 `title`（`args.query`／`args.url`），因此丢掉了调用头的窗口截断重放仍有标题，与 write/edit 在结果期重设 title 的做法一致。
 
@@ -22,13 +22,13 @@ Status: implemented
 
 ## Consequences
 
-前端消费方由后续独立 PR 交付：本次生产者变更新增契约分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
+前端消费方由后续独立 PR 交付：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript（文本记录）快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
 
 未来想用此卡片的 web 工具，声明一个返回带自有 `kind` 的 `card: 'web'` 视图的 `presentResult`；新增第三个 `kind` 是一次联合类型编辑加前端的分岔，而非一个新的 card 标签。
 
 ## Alternatives considered
 
-**两个 card 标签（`web-search`、`web-fetch`）。** 否决：它在每个 card 消费者处为一个视觉族翻倍分支数，而两个形状已共享得够多（一个带回退内容的带标题检索卡片），`kind` 判别无需第二个标签即可表达差异。
+**两个 card 标签（`web-search`、`web-fetch`）。** 否决：它在每个 card 消费方处为一个视觉族翻倍分支数，而两个形状已共享得够多（一个带回退内容的带标题检索卡片），`kind` 判别无需第二个标签即可表达差异。
 
 **在 `presentResult` 里重新解析 render 文本，而非投影 meta。** 对 `web_search` 否决：render 的来源列表是有损的（title 或 hostname 标签，snippet 与日期拼进自由文本），因此重新解析无法忠实恢复结构化字段。`presentationMeta` 是唯一保留它们的途径。
 
@@ -36,9 +36,9 @@ Status: implemented
 
 ## Testing
 
-`packages/web/tool-web/tests/tool-web.spec.ts` 覆盖以下内容，满足按文件 100% 的门禁：`searchMetaFromValue`/`fetchMetaFromValue` 投影，含对缺席可选字段的省略，以及抓取 `truncated` 投影在仅输出上限截断正文时、以及在毫无截断时都与 render 脚注一致；`searchMetaFromResult`/`fetchMetaFromResult` 收窄，含一次往返与每种畸形形状的拒绝（非对象、字段类型错误、畸形来源条目）以及空来源列表的接受；`presentSearchResult`/`presentFetchResult` 类型化视图，含从参数派生的 title、无 `content` 副本、truncated 信号、错误结果回退与畸形 meta 回退；以及两次真实注册表执行，断言工具把 meta 投影到 `result.meta` 上，其注册的 `presentResult` 推导出 `card: 'web'` 视图。
+`packages/web/tool-web/tests/tool-web.spec.ts` 覆盖以下内容，满足按文件 100% 的门禁：`searchMetaFromValue`/`fetchMetaFromValue` 投影，含省略不存在的可选字段，以及抓取 `truncated` 投影在仅输出上限截断正文时以及在毫无截断时都与 render 脚注一致；`searchMetaFromResult`/`fetchMetaFromResult` 收窄，含一次往返与每种畸形形状的拒绝（非对象、字段类型错误、畸形来源条目）以及空来源列表的接受；`presentSearchResult`/`presentFetchResult` 类型化视图，含从参数派生的 title、无 `content` 副本、truncated 信号、错误结果回退与畸形 meta 回退；以及两次真实注册表执行，断言工具把 meta 投影到 `result.meta` 上，其注册的 `presentResult` 推导出 `card: 'web'` 视图。
 
 ## Related
 
 - [标签化的工具调用渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md) —— 本卡片以 `web` 分支扩展的 `card` 标签词汇表。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；本分支的 web 前端消费者是它的对应物，推迟到后续 PR。
+- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；本分支的 web 前端消费方是它的对应实现，推迟到后续 PR。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
index 255dd08832..b0f3852fa8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
 2026-07-30-web-tool-row-unified-expand-and-inspect.md: 4fcf1e9a567b73cd04f1bbed170c391aaedd9e73
-2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 92d70f5aa6bd09e6f9e54015dafc38d8d3690a9e
+2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 765cd058c99e53e5dea81f83c203a6d75d56f104
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
index 92d70f5aa6..765cd058c9 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
@@ -1,29 +1,29 @@
-# Agent Note：Web 工具行统一展开交互与 trajectory Inspect
+# Agent Note: Web 工具行统一展开交互与 trajectory Inspect
 
-状态：已实现
+Status: implemented
 
 [English](2026-07-30-web-tool-row-unified-expand-and-inspect.md) | 中文
 
 ## 问题
 
-聊天视图的工具行交互已经分裂成多种方言：ToolRow 通过前导图标切换展开、且仅限有 args body 的调用，bash 示例有自己的一套展开方式，todo / ask-question 行只能展开原始 args，单文件工具完全不可展开，而调用的 OUTPUT 只能通过右侧详情面板查看。失败的 bash 命令（exit≠0 但结算为 `isError:false`）在折叠行上没有任何失败信号。此外聊天行没有跳转到 trajectory 记录的入口，且 chat → trajectory → chat 切换会丢失阅读位置（标签环会卸载非活跃视图）。
+聊天视图的工具行交互已经分裂成多种方言：ToolRow 通过前导图标切换展开、且仅限有 args body 的调用，bash 示例有自己的一套展开方式，todo / ask-question 行只能展开原始 args，单文件工具完全不可展开，而调用的 OUTPUT 只能通过详情面板查看。失败的 bash 命令（exit≠0 但结算为 `isError:false`）在折叠行上没有任何失败信号。此外聊天行没有跳转到 trajectory 记录的入口，且 chat → trajectory → chat 切换会丢失阅读位置（标签环会卸载非活跃视图）。
 
 ## 决定
 
 **所有可展开工具行共享同一交互——整行即开关（点击 / Enter / 空格），图标 hover 时渐变为 chevron 预览——以及同一展开体：带 IN/OUT 侧栏标签的卡片，各分区独立滚动上限；hover 显示的 Inspect 胶囊通过 store 的一次性交接跳到该调用的 trajectory 记录；聊天视图用内存态的按会话 Map 在视图切换间保留语义阅读位置。**
 
-- `toolRowModel` 在 args 之外同时派生结果材料：`output`（`resultText` 拍平逻辑从 DetailsPanel 移入 contract）和 `errorSummary`（失败首行，以错误色作为折叠摘要）。有 body、output 或 terminal 材料的行即可展开；行本身是开关（`role="button"`、`aria-expanded`），文件路径摘要通过 `stopPropagation` 保持独立链接。
+- `toolRowModel` 在 args 之外同时派生结果材料：`output`（`resultText` 拍平逻辑从 DetailsPanel 移入 contract）和 `errorSummary`（失败首行，作为折叠摘要并以错误色显示）。有 body、output 或 terminal 材料的行即可展开；行本身是开关（`role="button"`、`aria-expanded`），文件路径摘要通过 `stopPropagation` 保持独立链接。
 - 展开卡片（figma 1249:35657）是 IN/OUT 分区列：每个分区是独立滚动区（max-height 150px），侧栏标签 sticky 固定，l2 分割线横贯整卡宽度。Think 的推理文本和 run_code 的 CodeBlock 保持非卡片体；上下文注入复用此行并以无标签的 `plainBody` 卡片展开。
 - `terminalFailed` 读取已结算 terminal 卡片的退出状态，让 BashRow 和 GenericToolCard 把失败命令显示为行的红色状态点——这是折叠行唯一的失败信号，因为调用本身结算为 `isError:false`。
 - TerminalBlock 的横幅并入同一阅读模型：与卡片共用同一表面（不再用 banner token），与正文之间是 l2 细线，命令列上限 150px 内部滚动，复制/状态控件 sticky 且顶对齐第一行提示符。
-- Inspect：`ToolCallOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角以真实布局位置渲染胶囊，hover 整个 tool call 任意位置显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
-- 滚动保留：每次非贴底滚动时，聊天视图把 `{ anchorKey, anchorTop, scrollTop }` 保存到 apply 作用域的按会话 Map，并经注入 props 的 `chatScroll` 暴露；重挂载时先用 `scrollTop` 到达近似窗口，再按稳定 node／call 锚点的矩形差值校正，因此宽度重排后仍把同一阅读行保持在原位。包括「回到底部」在内的每条贴底路径都会在切换 tab 或会话前同步清除该项。Map 仍刻意不持久化——新页面加载保持打开即贴底的默认行为。
+- Inspect：`ToolCallOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角的正常布局流中渲染胶囊，hover 到工具调用的任意位置时显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
+- 滚动保留：每次非贴底滚动时，聊天视图把 `{ anchorKey, anchorTop, scrollTop }` 保存到 apply 作用域的按会话 Map，并以 `chatScroll` 暴露；重挂载时先用 `scrollTop` 到达近似窗口，再按稳定 node／call 锚点的矩形差值校正，因此宽度重排后仍把同一阅读行保持在原位。包括「回到底部」在内的每条贴底路径都会在切换 tab 或会话前同步清除该项。Map 仍刻意不持久化——新页面加载保持打开即贴底的默认行为。
 
 ## 曾考虑的替代方案
 
-**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互契约本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
+**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互约定本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
 
-**通过 URL 或 trajectory 视图 prop 传递 Inspect。** 否决：视图环经由 slot 注册表渲染，两个视图没有可携带 prop 的共同父级；chat store 本就跨越该边界，一次性字段让交接可安全重放（字段出现之前的持久化快照以 `?? null` 复水）。
+**通过 URL 或 trajectory 视图 prop 传递 Inspect。** 否决：视图环经由 slot 注册表渲染，两个视图没有可携带 prop 的共同父级；chat store 本就跨越该边界，一次性字段让交接具备回放安全性（字段出现之前的持久化快照以 `?? null` 复水）。
 
 **持久化聊天滚动偏移。** 否决：把几天前的偏移恢复到已经增长的会话里读起来像 bug；内存 Map 把记忆精确限定在会丢位置的视图切换场景。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml
index d1fb6cb6c7..89af3af66d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.md
 2026-07-31-browser-derived-initial-locale.md: 0c49a6bbfec0ab33a5aa3ce53dde0cac747f3816
-2026-07-31-browser-derived-initial-locale.zh.md: c013d24dcd3bb49d176eaddd42ff41dde320ff1f
+2026-07-31-browser-derived-initial-locale.zh.md: ca8eeceae58e25836bb42f7c1cec0e61a232d921
diff --git a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md
index c013d24dcd..ca8eeceae5 100644
--- a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md
@@ -16,21 +16,21 @@ Status: implemented
 
 **判定浏览器用的是 `window` 而非 `navigator`。** Node ≥ 21 暴露全局 `navigator` 并报告机器自身语言（CI runner 上是 `en-US`），因此以 `navigator` 把关会让 node 启动客户端树时解析成 `en`，而非文档约定的回落值。以 `window` 把关可使所有非浏览器运行都停留在 `FALLBACK_LOCALE`。
 
-**显式选择是永久的。** `setLocale` 的持久化未作改动，且持久化值最先被查询，因此选过语言的用户即便在不同浏览器配置或系统语言之间辗转也保留原选择。没有任何代码把探测到的 locale 写回存储：探测在每次启动时重新推导，对"用户是否做过选择"这一问题始终不可见。
+**显式选择是永久的。** `setLocale` 的持久化未作改动，且持久化值最先被查询，因此选过语言的用户即便在不同浏览器配置文件或系统语言之间辗转也保留原选择。没有任何代码把探测到的 locale 写回存储：探测在每次启动时重新推导，对「用户是否做过选择」这一问题始终不可见。
 
 **浏览器 e2e 车道现在钉住浏览器语言，而不只是存储项。** 断言中文文案的场景（`access-confirmation`、`models-settings`、`onboarding-deepseek-config`、`settings-chrome`）以 `apps/web/tests/support.ts` 的 `locale: ZH_BROWSER_LOCALE` 打开页面；`newEnglishPage` 仍然钉 `dsh.locale=en`，它依旧压过任何浏览器语言。`settings-chrome.e2e.ts` 新增一个场景：另开一个存储项为空的 `en-US` 页面，断言设置界面以英文呈现——这是本功能在组装后应用中的证据。
 
 ## Alternatives considered
 
 - **`Intl.DateTimeFormat().resolvedOptions().locale` 或单读 `navigator.language`**：两者都把用户的有序偏好列表塌缩成一个标签，于是 `['de', 'en', 'zh']` 的读者拿到的是 zh 而非 en。列表恰恰是浏览器这份声明里最值得读的部分。
-- **首次启动即持久化探测结果**：那会把探测变成一次性事件，让一次陈旧的首访凌驾于此后改变的浏览器语言之上，也摧毁了整个解析顺序所依赖的区分——存储值将不再意味着"用户选了它"。
+- **首次启动即持久化探测结果**：那会把探测变成一次性事件，让一次陈旧的首访凌驾于此后改变的浏览器语言之上，也摧毁了整个解析顺序所依赖的区分——存储值将不再意味着「用户选了它」。
 - **完整的 BCP 47 协商（`Intl.LocaleMatcher` 式查找、地区与文字权重）**：在只提供两个语言互异的 locale 时，主子标签匹配就是正确答案的全部；协商层只会带来无行为支撑、也无从测试的表面积。
-- **为默认 locale 增加一个 cordis config key**：此处部署之间并无差异——回落值是产品对"完全没有信号"给出的答案，不是旋钮。仓库策略把 `Config` 字段留给有当前消费者、且随部署变化的选择。
+- **为默认 locale 增加一个 Cordis 配置键**：此处部署之间并无差异——回落值是产品对「完全没有信号」给出的答案，不是旋钮。仓库策略把 `Config` 字段留给有当前消费方、且随部署变化的选择。
 - **让 e2e 车道的中文场景继续钉存储项（`dsh.locale=zh`）**：那会让套件保持绿色，却抹掉浏览器推导路径在组装后应用中唯一的运行处；改钉浏览器语言才能端到端地演练新的解析过程。
 
 ## Consequences
 
 - 来自英文浏览器的首访落在英文界面，而语言行依然呈现同样两个以自身语言自述的选项，两个方向的脱身通道都未改变。
-- `FALLBACK_LOCALE` 收窄回它真正的职责——字典回落与无信号时的答案——不再兼职充当"用户尚未选择"。
+- `FALLBACK_LOCALE` 收窄回它真正的职责——字典回落与无信号时的答案——不再兼职充当「用户尚未选择」。
 - 在 jsdom 下构造 `LocaleService` 的测试现在依赖环境的 `navigator`：断言本地化文案的用例以一行套件级 `usePinnedBrowserLanguages('zh-CN')`（dsh-client-test-runtime）声明其浏览器，今后任何断言默认值的用例同样如此。本包自己的用例直接给全局打桩，因为它们需要该 helper 刻意不表达的形状（`languages` 缺失、列表与 `language` 解耦、完全没有 `window`）。
 - 探测的代价是每次服务构造遍历一次数组，且不写存储，因此启动行为与持久化状态面均无变化。
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index e6ca4048fd..358d7b2a7a 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
 2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
-2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db
+2026-07-31-code-mode-language-dispatch.zh.md: 3cbd587b52eb650b071fc072acd73780435dc91a
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index 1dbb3d889d..3cbd587b52 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -23,24 +23,24 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ### Python SDK 渲染器
 
-`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON-schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的契约一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
+`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON Schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的约定一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
 
 该上限服务的标准是**语法合法性**，这条边界是有意划定的：长的 `A | B | …` union 在任何长度下都是合法 Python，故不设上限——尽管 CPython 的 `compile()` 在沿左嵌套 `BinOp` 脊柱下降时会耗尽 C 递归（在 3.9 上实测：1,000 个分支可编译，5,000 个抛 `RecursionError`）。没有任何东西会编译这个块——它是提示词文本——所以那条限制在这里没有代价；而给 union 长度封顶会作废那几个钉住 walk 线性时间与类名传播上限的深链测试。将来若有渲染器确实需要可编译的输出，应当把 union 拍平，而不是截断。
 
-`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的契约是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
+`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-- **在 `ToolRegistry` 上加一个 `language` 配置字段。** 那样部署方就会有两处命名语言（所加载的运行时与 tools 配置）且可能相互矛盾；所加载的运行时是唯一真相来源，故注册表读取它而不复制它。
+- **在 `ToolRegistry` 上加一个 `language` 配置字段。** 那样部署方就会有两处命名语言（所加载的运行时与 tools 配置）且可能相互矛盾；所加载的运行时是真源，故注册表读取它而不复制它。
 - **把 Python 后端 import 进 `code-mode.ts` 来检测它。** 那会把工具层耦合到具体后端，并迫使协议/后端 PR 先落地。按 `language` 运行时分发使该层保持后端无关、可独立发布。
 - **为未知语言提供默认渲染器。** 静默回退会在比如 Ruby 运行时上发出 TypeScript SDK——模型会看到错误语言的指令。在装配处 fail loud 是本仓库对错误配置的立场。
 
-## Consequences
+## 后果
 
 新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
 
-代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
+代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture（测试前置数据）运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript（文本记录）。
 
-Python SDK 文本断言的两条运行时契约同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 契约填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
+Python SDK 文本断言的两条运行时约定同样归属那个后端 PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 约定填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
 
 其三，那个 PR 拥有 CPython 版本下限，连带拥有本渲染器的 Unicode 表偏斜。有四处表达式读所运行引擎的表（Node 22.23.1：Unicode 17.0），而解释器用它自己的表（CPython 3.9.6：13.0.0）：`isBareIdentifier` 的 `IDENTIFIER`，以及 `camelCase` 的切分集、头部测试与 `toUpperCase()`。解释器旧于引擎是会失败的那个方向——引擎发出的字符被其 tokenizer 拒收，整个块随之不可解析——而它经三条独立路径抵达。经判据抵达的是裸发的方法名或字段名，其中带有一个在两个版本之间新增的字符——首位加进 `XID_Start`，或尾部任意位置（含名字中部）加进 `XID_Continue`。经 `camelCase` 的 XID 读取抵达的是类名：只要工具 schema 中有任一对象形态声明 `TypedDict`，该类名就进入发出的文本，且判据对工具名的裁决并不对它设闸——工具名 `zz-` 加 U+1E4D0 因 `-` 被判据直接拒绝、从不触及那里的偏斜，却照样声明 `class Zz𞓐xArgs`。经大写映射抵达的是由判据已接受的工具派生出的类名——这是另一张表，窗口也比 XID 归属更宽：U+019B 既是 XID_Start 又 NFKC 稳定，故 `async def ƛ` 在 3.9.6 上可编译，但 Node 将其大写为 U+A7DC（在那里未分配；CPython 自己的 `.upper()` 在此是恒等），于是 `class ꟜArgs` 以 `invalid non-printable character U+A7DC` 失败。暴露窗口是两个版本之间发生变化的那些字符与映射，所以宣布支持某个 CPython 范围的那个 PR 必须在「接受该暴露」与「按该下限的表钉住全部四个读取点」之间显式作出决定——只钉判据会同时留下两条类名路径。此处无法决定：下限尚不存在，而按猜测钉死一张表会成为一个随部署而变、却没有可配置性支撑的常量。还有第二条轴随该下限一同确定，且不属于那四个读取点：本块在定义期会被求值的那些名字与语法。`TypedDict` 需要 3.8，PEP 585 的内建泛型 `dict[str, Any]` 与 `list[…]` 需要 3.9，`A | B` 形式的注解需要 3.10，`NotRequired` 需要 3.11。这些不是解析失败——本块在任何版本上都能解析，这正是 `MAX_LIST_NESTING` 上限所服务的标准——而是定义期求值失败，且产品中没有任何东西会求值这段文本。把它们与那四个读取点记在一起，可避免把「在所支持范围上可解析」读成「在其上可执行」。
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
index d1cef43cc1..151d74e3dc 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
 2026-07-31-even-out-shipped-tool-rosters.md: 0195620055da5e570d2f54792d950a88bab8d652
-2026-07-31-even-out-shipped-tool-rosters.zh.md: cc67f24720f650283daa4ee85a0a1af5358756a8
+2026-07-31-even-out-shipped-tool-rosters.zh.md: ab6982e33c4a0a25cbc2fde386456840ce99d9c5
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
index cc67f24720..ab6982e33c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
@@ -6,19 +6,19 @@ Status: implemented
 
 ## 问题
 
-两个交付的 `dsh` surface 提供着不同的工具,而没有任何记录说明为什么。会话检查点、工具结果裁剪、goal 工具和 Ralph 在 `tui.cordis.yml`;`tool-todo` 以及后来的 web 搜索在 `web.cordis.yml`。两个 surface 都没有会话搜索、字符串替换编辑器和重复工具守卫,尽管这三者都已成包存在,且没有一个是 surface 专属的。
+两个交付的 `dsh` surface 提供着不同的工具，而没有任何记录说明为什么。会话检查点、工具结果裁剪、goal 工具和 Ralph 在 `tui.cordis.yml`；`tool-todo` 以及后来的 web 搜索在 `web.cordis.yml`。两个 surface 都没有会话搜索、字符串替换编辑器和重复工具守卫，尽管这三者都已成包存在，且没有一个是 surface 专属的。
 
-结果是一处没人做过决定的用户可见差异:同一个模型、同一个请求,在终端上能定目标而在浏览器里不能,在浏览器里能搜网页而在终端上不能。
+结果是一处没人做过决定的用户可见差异：同一个模型、同一个请求，在终端上能定目标而在浏览器里不能，在浏览器里能搜网页而在终端上不能。
 
 ## 决策
 
-那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
+那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml)，另有三行加入：`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
 
-有两行仍是 surface 专属。`tmux-context` 只在 TUI,因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI,因为它以 launcher 的进程本地路径驱动共享的 session-query 索引,而浏览器侧边栏会在自己的首次搜索里重建该索引。
+有两行仍是 surface 专属。`tmux-context` 只在 TUI，因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI，因为它以 launcher 的进程本地路径驱动共享的 session-query 索引，而浏览器侧边栏会在自己的首次搜索里重建该索引。
 
 **本次工具清单决策当时只做加法。** 落地时两个 surface 均未移除任何工具行，目录对比只发现了新增，别无其他。这些新增中的一项 `tool-session-query` 随后被[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)移除。共享执行器、沙箱组合与访问默认值独立归属[workspace-write 默认值决策](2026-07-31-workspace-write-surface-default.md)。
 
-### 什么保持不挂,以及为什么
+### 什么保持不挂，以及为什么
 
 有三项能力基于其自身包所记录的证据保持在外,列在这里是为了让「我们忘了」和「我们决定不要」保持可区分。
 
@@ -26,13 +26,13 @@ Status: implemented
 
 **`dsh-web-fetch-local`** 保持不挂,`dsh-tool-web` 保持 `fetch: false`。SSRF 防护在实现中是 deferred 状态([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) 只校验协议、凭据与长度),包里也直说了:「this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets」([README](../../../../packages/web/web-fetch-local/README.md))。目标由模型选择,其中包括 harness 自己跑在环回地址上的网关、内网段和云元数据端点。
 
-弃用它收窄的是接触面而非可达性:`bash` 是挂着的,`curl` 照样能拿到同一个页面——一次真实运行确认了这点。这个缺席买到的是去掉一个无需 shell、以参数成形的请求原语,以及随之而来的那条意外路径:一次「帮我总结这个页面」悄悄打到环回地址。真要收住出站流量的部署需要的是网络层管控。
+不挂载它收窄的是接触面而非可达性：`bash` 是挂着的,`curl` 照样能拿到同一个页面——一次真实运行确认了这点。这个缺席买到的是去掉一个无需 shell、以参数成形的请求原语,以及随之而来的那条意外路径:一次「帮我总结这个页面」悄悄打到环回地址。真要收住出站流量的部署需要的是网络层管控。
 
 **LSP 三件套**留在外面是运维原因而非安全原因:`command` 在插件加载时从 `PATH` 解析,因此缺少语言服务器会让整次启动失败,而不只是失去一个工具。等到「缺失」退化为「跳过注册」之后,它就可以挂了。
 
 ### MCP 是依赖,不是配置行
 
-`@deepseek-ai/dsh-mcp-client` 成为本 CLI 的运行时依赖,但在任何交付配置里都没有对应的行。该插件每个实例只挂载一台服务器,且 `command` 是必填,因此一个默认值必须点名一台第三方服务器,并在每次启动时把它作为子进程 spawn——不经 `ctx.bash`,因而也在 Web surface 所组合的沙箱策略之外。
+`@deepseek-ai/dsh-mcp-client` 成为本 CLI（命令行界面）的运行时依赖,但在任何交付配置里都没有对应的行。该插件每个实例只挂载一台服务器,且 `command` 是必填,因此一个默认值必须点名一台第三方服务器,并在每次启动时把它作为子进程 spawn——不经 `ctx.bash`,因而也在 Web surface 所组合的沙箱策略之外。
 
 真正能让 MCP 成为默认的那一层,恰恰是本仓库尚未拥有的:一个读取用户服务器清单、按条目逐台挂载客户端的桥接,形态与 [`dsh-hooks-claude`](../../../../packages/hooks/hooks-claude/README.md) 读取 Claude Code 的 `hooks.json` 完全相同。交付这个依赖意味着已安装的 `dsh` 今天就能从 `$DSH_HOME/config.yaml` 挂载服务器;CLI README 里给了那段 YAML。
 
@@ -54,11 +54,11 @@ Status: implemented
 
 **把共享的行复制进两份 overlay,而不是提升到 base。** 基于「一处归属」原则否决:新增行里有三行会存在两份,而这些副本没有任何理由发生分歧,下一次改工具清单还得记着改两处。
 
-**在同一次改动里给 TUI 加沙箱。** 不予采纳，因为这是一个不属于工具清单改动的独立决定：TUI 挂的是不受限执行器，替换它们会改变一个既有 surface 做什么，而非它提供什么。这个决定需要自己的证据——尤其因为 TUI 没有 `approval/request` 的应答方，升级请求在那里会 fail-closed，而不是弹出提示。
+**在同一次改动里给 TUI 加沙箱。** 不予采纳，因为这是一个不属于工具清单改动的独立决定：TUI 挂的是不受限执行器，替换它们会改变一个既有 surface 做什么，而非它提供什么。这个决定需要自己的证据——尤其因为 TUI 没有 `approval/request` 的应答方，升权请求在那里会 fail-closed，而不是弹出提示。
 
 **开启 Code Mode。** 它的信任立场按设计与 bash 同级,工具调用要过与 bash 相同的 `tools/pre-execute` 闸门,所以它与上面那些模型写码工具不是同一个判断。在这里仍被否决:`both` 会改变两个 surface 上每一个模型可见请求,而 `code` 是把线路替换而非加一个——两者都是呈现方式的决定,不是工具清单的决定。
 
-**默认挂一台 MCP 服务器。** 否决,因为交付默认值必须点名一台,而任何选择都会在每个用户的机器上、在沙箱之外 spawn 一个第三方子进程。改为交付依赖。
+**默认挂一台 MCP 服务器。**否决，因为交付默认值必须点名一台，而任何选择都会在每个用户的机器上、在沙箱之外 spawn 一个第三方子进程。改为交付依赖。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
index 99ea335b59..fa5ea6f634 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.md
 2026-07-31-gui-full-access-confirmation.md: ca89ed23fb1b5c6ea438dd22fdf20d2b82af754c
-2026-07-31-gui-full-access-confirmation.zh.md: 0f487e41b544718bdf38de611a1ab2d59c44b063
+2026-07-31-gui-full-access-confirmation.zh.md: a31c1ee744b111dd6917f0d2ed7ba9988c2aee47
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
index 0f487e41b5..a31c1ee744 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
@@ -4,28 +4,28 @@ Status: implemented
 
 [English](2026-07-31-gui-full-access-confirmation.md) | 中文
 
-## Problem
+## 问题
 
-在 Web 客户端的权限选择器中切换到 `danger-full-access` 只需一次点击，且预设以 Title Case 机器名 `Danger Full Access` 展示。Full access 会减少确认步骤，允许智能体执行敏感操作、修改文件或运行外部命令，误点即在毫无刻意确认环节的情况下启用了最危险的预设。
+在 Web 客户端的权限选择器中切换到 `danger-full-access` 只需一次点击，且预设以 Title Case 机器名 `Danger Full Access` 展示。Full access 会减少确认步骤，允许 agent（智能体）执行敏感操作、修改文件或运行外部命令，误点即在毫无刻意确认环节的情况下启用了最危险的预设。
 
-## Decision
+## 决策
 
 **每个权限选择器都把 `danger-full-access` 关进共享的页面内 `RiskConfirmation` 对话框：启用按钮在用户勾选明确的风险确认复选框前保持禁用；预设以产品标签 `Full access` 展示；所有取消路径都不作任何提交。**
 
-- `RiskConfirmation`（ui-primitives）是受控的 Modal 组合：标题、说明、确认复选框、取消，以及 `acknowledged` 勾选前禁用的确认按钮。它始终是页面内对话框——Modal portal 到本文档 body，绝不打开可能落在另一块显示器上的原生或独立浏览器窗口。`Modal` 新增 `contentClassName` 座位，令警示正文在受限的移动端／横屏视口内滚动，动作行保持固定。
-- 编辑器 chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale 座位以 `access.confirm.*` 键供给。
-- `/permission` popup（ui-permission 骑在 ui-command 外壳上）以数据而非第二套对话框实现完成把关：`SelectOption` 新增可选的 `confirmation` 载荷，popup 控制器拥有 `confirming`/`acknowledged` 状态迁移，`PopupSelectView` 在门控选项未决期间把选择卡换成同一个 `RiskConfirmation`。
+- `RiskConfirmation`（ui-primitives）是受控的 Modal 组合：标题、说明、确认复选框、取消，以及 `acknowledged` 勾选前禁用的确认按钮。它始终是页面内对话框——Modal portal 到本文档 body，绝不打开可能落在另一块显示器上的原生或独立浏览器窗口。`Modal` 新增 `contentClassName` slot，令警示正文在受限的移动端／横屏视口内滚动，动作行保持固定。
+- composer chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale slot以 `access.confirm.*` 键供给。
+- `/permission` popup（ui-permission 构建于 ui-command 外壳之上）以数据而非第二套对话框实现完成把关：`SelectOption` 新增可选的 `confirmation` 载荷，popup 控制器拥有 `confirming`/`acknowledged` 状态迁移，`PopupSelectView` 在门控选项未决期间把选择卡换成同一个 `RiskConfirmation`。
 - 「通用」设置中的「权限」行在把 Full access 持久化为后续会话的默认值前，也使用同一个受控 `RiskConfirmation`。警示会明确说明该设置只影响后续会话；取消、Escape、关闭与点击遮罩均不会改动已存默认值。
 - `Full access` 在每个选择器中都有意覆盖 kebab 转 Title Case 的显示变换；命令与 Settings 写入在 wire 上保留机器名，每份警示正文都保持中英文 locale 感知。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **原生／操作系统或独立窗口确认。** 已拒：对话框必须留在当前 WebUI 窗口内；第二个窗口可能出现在另一块显示器上，使决策脱离其守护的页面状态。
 
-**每个面的安全文案共享一个 locale namespace。** 已拒：ui-permission bundle 与 ui-conversation 可独立加载，而 Settings 警示说明的是另一种只影响后续会话的生效周期。每个 bundle 各自拥有文案，ui-permission 也将 popup 与 Settings 词典分开，而非跨 bundle 边界 import。
+**每个界面的安全文案共享一个 locale namespace。**不予采用：ui-permission bundle 与 ui-conversation 可独立加载，而 Settings 警示说明的是另一种只影响后续会话的生效周期。每个 bundle 各自拥有文案，ui-permission 也将 popup 与 Settings 词典分开，而非跨 bundle 边界 import。
 
 **在 host／权限后端把关。** 设计上即出界：本变更只涉浏览器客户端确认流；后端权限语义、默认值与更安全预设的一键行为均不变。
 
-## Consequences
+## 后果
 
-进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 契约，以及组装态 Web 回放。
+进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 约定，以及组装态 Web 回放。
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
index 3227fac451..4970aa2c7d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.md
 2026-07-31-permission-default-for-new-sessions.md: ffa4c8a07bdd08ca52edbc14fe10372ad76e8cf8
-2026-07-31-permission-default-for-new-sessions.zh.md: 5fc42724754acc1653ed93b48644794a38f52ba7
+2026-07-31-permission-default-for-new-sessions.zh.md: c70d431ec9bbe8cdeabfdc8a0052a9c436844f02
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
index 5fc4272475..c70d431ec9 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web「通用」设置页将「权限」显示为禁用的骨架控件，尽管 `dsh-permission` 已经拥有 preset 表和当前会话的切换路径。Settings seam 可以持久化由插件拥有的值，但 Web Settings API 只暴露可配置 LLM 提供方的 namespace。更重要的是，如果把用户偏好当成实时生效的全局权限，现有会话的执行策略就会在其持久日志之外发生变化。
+Web「通用」设置页将「权限」显示为禁用的骨架控件，尽管 `dsh-permission` 已经拥有 preset 表和当前会话的切换路径。Settings seam 可以持久化由插件拥有的值，但 Web Settings API 只暴露可配置 LLM（大语言模型）提供方的 namespace。更重要的是，如果把用户偏好当成实时生效的全局权限，现有会话的执行策略就会在其持久日志之外发生变化。
 
 ## 决策
 
@@ -26,10 +26,10 @@ ApiProxy 在可配置提供方 namespace 之外，将 `permission` 显式加入
 
 ## 曾考虑的替代方案
 
-**将 Settings 值实时应用于每个会话。** 不予采纳，因为执行策略会在没有会话事件的情况下改变，重放也无法重建先前工具调用采用了哪种权限。
+**将 Settings 值实时应用于每个会话。** 不予采纳，因为执行策略会在没有会话事件的情况下改变，回放也无法重建先前工具调用采用了哪种权限。
 
 **创建时只记录 `permission/preset`。** 不予采纳，因为沙箱和审批是由不同组件独立拥有的全量值调节项；固定全部三个事实，可以让其消费方不依赖未来的组合默认值变化。
 
-**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 契约超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
+**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 约定超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
 
 **恢复带 seed 的会话时应用最新默认值。** 不予采纳，因为恢复操作必须保留会话先前的有效执行策略；缺失的旧版事实应从该策略中补齐。
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
index cca8f8a597..5565ea70b1 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-session-archive-global-set.md
 2026-07-31-session-archive-global-set.md: fab99a405a6f8264c36453473327e32905bac9c8
-2026-07-31-session-archive-global-set.zh.md: e33f3b5272a6d8fc90cfad247ba21d4d10afb045
+2026-07-31-session-archive-global-set.zh.md: b10440039f1c6a8ea2f89d9239a0285dd70cf9a2
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
index e33f3b5272..b10440039f 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
@@ -1,26 +1,26 @@
-# Agent Note: Session 归档（注册表级全局集合）
+# Agent Note: 会话归档（注册表级全局集合）
 
-状态：implemented
+Status: implemented
 
 [English](2026-07-31-session-archive-global-set.md) | 中文
 
 ## 问题
 
-Sidebar workspace 浏览区的 session 行菜单里，「Delete session」一直是纯视觉占位（无 handler）。产品口径定为**归档**而非删除：session 日志与 workspace 记账都不动，只把该 session 从所有分组视图（workspace 分组、Ungrouped、搜索、平铺列表）里隐藏。归档记录需要一个落点：Ungrouped 的 session 不属于任何 workspace 实体，per-workspace 字段放不下它。
+Sidebar workspace 浏览区的会话行菜单里，「Delete session」一直是纯视觉占位（无 handler）。产品口径定为**归档**而非删除：会话日志与 workspace 记账都不动，只把该会话从所有分组视图（workspace 分组、Ungrouped、搜索、平铺列表）里隐藏。归档记录需要一个落点：Ungrouped 的会话不属于任何 workspace 实体，per-workspace 字段放不下它。
 
 ## 决策
 
 **归档集合是 workspace domain 全局单例（`workspaceDomainState.archivedSessionIds`）上的一个新字段，覆盖在 workspace 记账之上；显示过滤全部收敛在 client 的 `tree.ts` 派生层；wire 面走全快照姿态。**
 
-- 存储：`archivedSessionIds: z.array(sessionId).default([])`，domain version 保持 2——纯增量字段，旧介质经 schema default 解析为空集合，无迁移代码。被归档的 session 保留其 `sessionIds` 席位（未来取消归档恢复原位置），因此与「一个 session 只被一个 workspace 记账」不变式零纠缠。
-- Registry：`ctx.workspace.archiveSession(id)` 走 `enqueueOperation` 与 create/delete 串行；未知 session（实时与持久化都查不到）抛 `WorkspaceUnknownSessionError`；已归档 id 不写盘不发事件。`archivedSessionIds` getter 暴露只读集合。
-- RPC：`workspace.archiveSession({sessionId}) → {archivedSessionIds}`（应答完整更新后集合）；`workspace.list` 响应携带集合作为重连基线；新 host 帧 `host/archived-sessions-changed` 在每次持久变更后推完整快照（与 `host/workspace-changed` 同姿态，从 `domain/changed` 的 global put 分支比对推帧）。未知 session 复用错误码 `session-not-found`。
-- client runtime：`WorkspaceListState.archivedSessionIds`（按 Host 顺序的 `readonly SessionId[]`，成员不变不换引用——公有快照状态保持 store 引擎的纯数据词汇：immer draft 不开 MapSet 插件就不接受 Set；membership 查询在派生函数内自建临时 Set，与 expandedProjects 同款）；list 基线、unary 回声、changed 帧三路都整体替换安装。投影层在当前 selection 落入归档集合时统一清空回 New Session 视图（用户拍板：归档当前打开的 session 主视图回 hero）——一条规则同时覆盖本地 unary 回声、其他标签页的 changed 帧、以及重连基线恢复出一个离线期间被归档的 selection；帧/回声落在 in-flight `workspace.list` 期间时还会屏蔽旧基线对新集合的回滚。
+- 存储：`archivedSessionIds: z.array(sessionId).default([])`，domain version 保持 2——纯新增字段，旧介质经 schema default 解析为空集合，无迁移代码。被归档的会话保留其 `sessionIds` slot（未来取消归档恢复原位置），因此与「一个会话只被一个 workspace 记账」不变式零纠缠。
+- 注册表：`ctx.workspace.archiveSession(id)` 走 `enqueueOperation` 与 create/delete 串行；未知会话（实时与持久化都查不到）抛 `WorkspaceUnknownSessionError`；已归档 id 不写盘不发事件。`archivedSessionIds` getter 暴露只读集合。
+- RPC：`workspace.archiveSession({sessionId}) → {archivedSessionIds}`（应答更新后的完整集合）；`workspace.list` 响应携带集合作为重连基线；新 host 帧 `host/archived-sessions-changed` 在每次持久变更后推完整快照（与 `host/workspace-changed` 同姿态，从 `domain/changed` 的 global put 分支比对推帧）。未知会话复用错误码 `session-not-found`。
+- client 运行时：`WorkspaceListState.archivedSessionIds`（按 Host 顺序的 `readonly SessionId[]`，成员不变不换引用——公有快照状态保持 store 引擎的纯数据词汇：immer draft 不开 MapSet 插件就不接受 Set；membership 查询在派生函数内自建临时 Set，与 expandedProjects 同款）；list 基线、unary 回声、changed 帧三路都会用完整集合整体替换现有值。投影层在当前 selection 落入归档集合时统一清空回 New Session 视图（用户拍板：归档当前打开的会话会使主视图回到 hero）——一条规则同时覆盖本地 unary 回声、其他标签页的 changed 帧、以及重连基线发现当前 selection 已在此 client 离线期间被归档的情形；帧/回声落在 in-flight `workspace.list` 期间时还会屏蔽旧基线对新集合的回滚。
 - UI：菜单项 `delete`（visual-only）改为 `archive`（label「Archive session」，非 danger 样式，无确认对话框——非破坏性操作，误触后果只是列表隐藏）；过滤实现为 `tree.ts` 的 `sessionVisible` 判据加一档，`deriveGroups`/`deriveFlat` 增加 `archived` 集合入参，四个视图（分组循环、stray 兜底、搜索、平铺）同源生效。
 
 ## 已考虑的替代方案
 
-**per-workspace archivedSessionIds（最初表述）。** 否决：Ungrouped session 无落点；用户改口全局。
+**per-workspace archivedSessionIds（最初表述）。** 否决：Ungrouped 会话无落点；用户改口全局。
 
 **SessionSummary 打 archived 标（session.list 层）。** 否决：要把 workspace domain 事实 join 进 sessions domain 投影，summary 无增量帧还得另发通知，跨域耦合大于收益。
 
@@ -30,4 +30,4 @@ Sidebar workspace 浏览区的 session 行菜单里，「Delete session」一直
 
 ## 后果
 
-归档后 UI 无查看/取消归档入口（本期口径，README Known Limitation 记账）；数据与席位完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
+归档后 UI 无查看/取消归档入口（本期口径，记录在 README 的 Known Limitation 中）；数据与slot完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 7bcfa9f599..e17ee5343c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
 2026-07-31-telemetry-anonymous-user-id.md: 3c8e3324cb418eac48cb5ae780c55bbcbaf3caa1
-2026-07-31-telemetry-anonymous-user-id.zh.md: 9ff6cf35a90d4087b4ab75987dc9244210e3d46a
+2026-07-31-telemetry-anonymous-user-id.zh.md: b8b90bbad64abc409d743f89fb156bb94d7f6a7f
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 9ff6cf35a9..b8b90bbad6 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -10,19 +10,19 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 
 ## Decision
 
-`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流，用户复议后收回：在有第二个真实消费者之前不抽公共包，回流关联需求出现时再议）。
+`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流，用户复议后收回：在有第二个真实消费方之前不抽公共包，回流关联需求出现时再议）。
 
 | 裁定 | 取值 | 理由 |
 |---|---|---|
 | id 来源 | 随机 UUID v4，绝不从 hostname/网络地址/git remote 派生 | 派生 id 可反查，「匿名」名不副实 |
 | 存储形态 | `.userid` 裸 UUID 行 + 换行，无 JSON 包装 | 身份是独立事实，不挂在某条 telemetry 链路的文件命名/格式下 |
 | 读写形态 | 同步 IO + 进程内按解析后文件路径 memo | `TelemetryOtel` 构造函数是同步的（async 迫使插件装载改形）；一进程一次盘 IO，运行中删文件不影响本进程 |
-| 并发首启 | `wx` 独占写裁决，落败方重读胜者 id | 覆盖常见并发（重读撞进胜者建档-写入微秒窗仍可能各持一 id 一次运行，下次启动收敛到落盘值——telemetry 级后果，接受） |
+| 并发首启 | `wx` 独占写裁决，落败方重读胜者 id | 覆盖常见并发（若重读恰好落在胜者创建文件至写入内容之间的微秒窗口内，该次运行中仍可能每个进程各持一个 id；下次启动时会收敛到已落盘的值——这是 telemetry 级后果，可以接受） |
 | 丢失语义 | 文件被删 → 下次启动换新 id，接受丢失 | 匿名身份无恢复价值；可恢复性要求派生材料，与匿名冲突 |
 | 写失败 | best-effort 返回内存 id | telemetry 永不因 home 只读被阻塞 |
-| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 契约且涨 wire 体积 |
+| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 约定且涨 wire 体积 |
 | semconv 依赖 | 不引 `@opentelemetry/semantic-conventions` 包 | 一个字符串常量不值一个依赖 |
-| 落点 | `session-telemetry-otel` 包内模块，非公共 util 包 | 仓规「有第二个真实消费者才拆包」；sdk launcher 回流保留自有存储，无现实关联需求 |
+| 落点 | `session-telemetry-otel` 包内模块，非公共 util 包 | 仓规「有第二个真实消费方才拆包」；sdk launcher 回流保留自有存储，无现实关联需求 |
 | 单独开关 | 无 | 身份跟随 telemetry 整体开关（`DSH_TELEMETRY_DISABLED`）；关 telemetry 即整体不报 |
 
 ## Alternatives considered
@@ -30,10 +30,10 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | 被拒 | 一句话理由 |
 |---|---|
 | hostname/IP 哈希派生 id（此前口径） | 可反查即非匿名；随机 UUID 语义干净，用户裁决取代 |
-| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 契约或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
-| 公用 util 包统一两条回流（初版实现） | 唯一现实消费者是 OTel backend；sdk launcher 换用它只是为统一而统一——用户复议收回，回流关联需求出现时再抽包 |
+| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 约定或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
+| 公用 util 包统一两条回流（初版实现） | 唯一现实消费方是 OTel backend；sdk launcher 换用它只是为统一而统一——用户复议收回，回流关联需求出现时再抽包 |
 | 复用 telemetry.json 不新建文件 | 文件名/JSON 格式把身份挂在 launcher 链路命名下；OTel 回流身份是独立事实 |
-| AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；config 里传运行时事实与部署配置混淆 |
+| AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；在 config 里传运行时事实，会混淆运行时事实与部署配置 |
 | 挂进 `@deepseek-ai/dsh-paths` | paths 是纯路径计算零 IO；带持久化的身份能力会污染包边界 |
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
index 1c04bc1d55..7c42b6c7dc 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-default-search.md
 2026-07-31-web-default-search.md: 8f2cc6f5d1a9ec9f33279ae8e5c992bdc660e7fa
-2026-07-31-web-default-search.zh.md: 7d528617143cb9756d0a4532bb1ed6a3a3e70ca8
+2026-07-31-web-default-search.zh.md: 46db167b84f8c1a10686a941b174008ebafc720d
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
index 7d52861714..46db167b84 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
@@ -16,7 +16,7 @@ DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据
 
 搜索端点与 chat completions 保持独立：`DEEPSEEK_SEARCH_BASE_URL` 覆盖 Anthropic 兼容基址，`DEEPSEEK_BASE_URL` 则继续配置会话请求。每次 `web_search` 都会发起一次辅助 DeepSeek Messages 调用，并携带原生搜索服务器工具。发出请求前一刻，提供方会向发起请求的 agent（智能体）会话追加仅用于日志的 LLM（大语言模型）请求事件 `web/deepseek-search-llm-request`，其中包含已解析端点、API 版本，以及不含密钥的精确 JSON 请求体。凭据预检仍留在提供方内部，并与调用方取消存在竞态；这两项关注点都不会扩展通用 Web seam 或凭据 seam。
 
-默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有契约。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
+默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有约定。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
index 743362fae1..5866d98309 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
 2026-07-31-web-telemetry-default-mount.md: c1525a44196991d5059969ea70af34501b199323
-2026-07-31-web-telemetry-default-mount.zh.md: f203ea1943387beda445bd81ac78fa2cc0471d45
+2026-07-31-web-telemetry-default-mount.zh.md: ef5f7e4500a1776e049ac27e0e64756e78725a61
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
index f203ea1943..ef5f7e4500 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-31-web-telemetry-default-mount.md) | 中文
 
-## Problem
+## 问题
 
-遥测 seam 与 OTel backend（[revival Note](2026-07-23-session-telemetry-otel-revival.md)）自完成以来从未接入任何部署组合：没有 roster 行、没有开关、没有节奏口径，内部部署对用户会话零可观测。需要一个部署决策：哪些 surface 上报、报到哪、什么节奏、怎么关、CI 怎么隔离。
+遥测 seam 与 OTel 后端（[revival Note](2026-07-23-session-telemetry-otel-revival.md)）自完成以来从未接入任何部署组合：没有 roster 行、没有开关、没有节奏口径，内部部署对用户会话的可观测性为零。需要一个部署决策：哪些 surface 上报、报到哪、什么节奏、怎么关、CI 怎么隔离。
 
-## Decision
+## 决策
 
 `dsh` 共享 base（`apps/cli/config/base.cordis.yml`）默认挂载 `telemetry-otel` 行，内置生产 endpoint，因此 Web 与 headless 都会上报；原始配置命令也会先挂载该行，再应用其必需的部署 overlay。这是**内部测试期的部署立场**——有 endpoint 就上报，用户可通过环境变量退出。Web 与 headless 在 SIGINT/SIGTERM 时使用[有界、可升级的进程关闭控制器](../bug-fix/2026-08-03-cli-signal-shutdown-escalation.md)，在启动器 5 秒上限到期前，先给后端 3 秒关闭截止时间完成排空。
 
@@ -17,23 +17,23 @@ Status: implemented
 | 挂载面 | base.cordis.yml（原始配置 + Web + headless） | 所有加载共享 base 的配置树采用同一个部署立场；原始配置 overlay 决定该部署是否创建会话 |
 | endpoint | `DSH_TELEMETRY_OTLP_URL`，缺省 `https://harness-telemetry.deepseeksvc.com/v1/logs` | 内部 collector；env 覆盖供本地/联调 |
 | 退出开关 | `DSH_TELEMETRY_DISABLED` 非空（含 `0`/`false`）即关 | 隐私向开关取「宁关勿误开」；行级 disable 只能在 AppCLIEntry 的 patch 层做（config 无 disable 语义，且必须先于 `exporter.url` 的加载期校验生效） |
-| 上报节奏 | `processor.scheduledDelayMillis: 10000`（10s/批） | 流式回流，非退出才报；崩溃至多丢最后一个未导出间隔 |
-| 退出 drain 上界 | `exporter.timeoutMillis: 1000` + `maxExportBatchSize: 2048（== maxQueueSize）` + `exportTimeoutMillis: 1500` + `shutdownTimeoutMillis: 3000` | collector 不可达的常规故障会在约 1s 内放行：timeoutMillis 是单次 socket 超时与重试 deadline，使用与队列等大的单批可避免依次排空导致耗时倍增。由 DSH 管理的 3s 外层上限覆盖 SDK 先执行的无界 `forceFlush()` 等待，即传输 Promise 始终无法取得 socket 的情况。 |
+| 上报节奏 | `processor.scheduledDelayMillis: 10000`（10s/批） | 流式回流，非退出才报；崩溃至多丢失最后一个尚未导出间隔内的数据 |
+| 退出 drain 上界 | `exporter.timeoutMillis: 1000` + `maxExportBatchSize: 2048`（与 maxQueueSize 相等） + `exportTimeoutMillis: 1500` + `shutdownTimeoutMillis: 3000` | collector 不可达的常规故障会在约 1s 内放行：timeoutMillis 是单次 socket 超时与重试 deadline，使用与队列等大的单批可避免依次排空导致耗时倍增。由 DSH 管理的 3s 外层上限覆盖 SDK 先执行的无界 `forceFlush()` 等待，即传输 Promise 始终无法取得 socket 的情况。 |
 | 压缩 | `compression: gzip` | 事件 body 含全文，跨机房带宽 |
-| CI 隔离 | 全部 8 个 GitHub workflow 顶层 `env: DSH_TELEMETRY_DISABLED: '1'` | CI 启动 web 组合的所有通道（e2e/snapshot/built smoke）不得向生产 endpoint 泄测试会话 |
+| CI 隔离 | 全部 8 个 GitHub 工作流顶层 `env: DSH_TELEMETRY_DISABLED: '1'` | CI 启动 web 组合的所有通道（e2e/快照/已构建版本的冒烟测试）不得向生产 endpoint 泄测试会话 |
 
-集成测试 `apps/cli/tests/telemetry-web.e2e.ts`（keyless）钉住部署级行为：测试内 OTLP collector + mock LLM，真启动 `dsh web`，断言 ledger 覆盖、seq 单调、chunk 首条投影、以及 SIGINT drain 后 ops `shutdown` 标记到达。
+集成测试 `apps/cli/tests/telemetry-web.e2e.ts`（keyless）钉住部署级行为：测试内 OTLP collector + mock LLM（大语言模型）服务器，真启动 `dsh web`，断言 ledger 覆盖、seq 单调、步骤首个分片投影、以及 SIGINT drain 后 ops `shutdown` 标记到达。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**默认不挂载，部署方自行加行（SDK 立场的延续）。** 否决于当前阶段：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 seam 包保持（不挂 = 零外发）。
+**默认不挂载，部署方自行加行（SDK 立场的延续）。** 当前阶段不采用：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 seam 包保持（不挂 = 零外发）。
 
 **开关做成 config 字段而非 env patch。** 不可行：cordis 行没有 config 层的 disable 语义，且 `exporter.url` 校验在插件构造期 fail-loud，开关必须在 Loader 之前生效——AppCLIEntry patch 层是唯一落点。
 
 **退出时 `Promise.race` 兜底超时。** 最初暂缓，是因为 SDK 参数看似已经将后端排空耗时限制在约 1.5-3s（通常 <100ms），实测 SIGINT 到退出耗时 110ms-1.1s。后来在 Linux 沙箱中复现并证明，`BatchLogRecordProcessor.shutdown()` 可能在 `exporter.forceFlush()` 中永久等待，无法进入受 `exportTimeoutMillis` 限制的完成 Promise。因此，[CLI 关闭修复](../bug-fix/2026-08-03-cli-signal-shutdown-escalation.md) 既为这一特定缺口增加 3 秒后端上限，也为整棵插件树增加 5 秒进程级上限和重复信号退出途径。
 
-## Consequences
+## 后果
 
 - 无本地 collector 的开发者跑 `dsh web` 会对生产 endpoint 每 10s 发一次 POST（联不通则静默失败，OTel diag logger 未注册）；本地开发设 `DSH_TELEMETRY_DISABLED=1` 或 `DSH_TELEMETRY_OTLP_URL` 指本地。
-- **当前零脱敏规则挂载**：导出即原始捕获副本（用户/助手消息全文、工具参数与结果、system prompt、`session.cwd` 本地路径）。跨信任边界前必须挂 `telemetry/record` 规则——脱敏规则、其余身份 Resource 维度（hostname/surface；匿名 user id 已由[匿名用户 id Note](2026-07-31-telemetry-anonymous-user-id.md)落地）、使用数据 metrics 轨是本决策明确的后续工作。
-- 复用这棵树的测试载具（如 `apps/web/tests/scaffold.ts`）须显式关停该行，否则 fixture 会话会流向 env 里碰巧存在的 collector。
+- **当前尚未挂载任何脱敏规则**：导出即原始捕获副本（用户/助手消息全文、工具参数与工具结果、系统提示词、`session.cwd` 本地路径）。跨信任边界前必须挂 `telemetry/record` 规则——脱敏规则、其余身份 Resource 属性（hostname/surface；匿名 user id 已由[匿名用户 id Note](2026-07-31-telemetry-anonymous-user-id.md)落地）、使用数据 metrics 轨是本决策明确的后续工作。
+- 复用这棵树的测试载具（如 `apps/web/tests/scaffold.ts`）须显式关停该行，否则 fixture（测试前置数据）会话会流向 env 里碰巧存在的 collector。
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index c1cc57b233..5cd3bd7aca 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
 2026-07-31-web-workspace-file-links.md: fe71a2d8caa4dc9cc732a250d7e388d1a3b44182
-2026-07-31-web-workspace-file-links.zh.md: 0f8c87822087169aad9ac4283f706fd8a8748be9
+2026-07-31-web-workspace-file-links.zh.md: a59ca5c6ba3a2c4aee9129deedfbb486cec082b2
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 0f8c878220..a59ca5c6ba 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -1,30 +1,30 @@
-# Agent Note：从 web UI 打开产出的文件
+# Agent Note: 从 web UI 打开产出的文件
 
 Status: implemented
 
 [English](2026-07-31-web-workspace-file-links.md) | 中文
 
-> 范围：完成的一轮以其产出文件收尾的那一行、读得出是链接的文件路径链接，以及 Host 打开器对浏览器可渲染文档优先选用默认浏览器。经决定不在范围内：以 HTTP 提供工作区文件，以及为不在 Host 机器上的客户端提供预览。
+> 范围：完成的轮次以其产出文件收尾的那一行、读得出是链接的文件路径链接，以及 Host 打开器对浏览器可渲染文档优先选用默认浏览器。经决定不在范围内：以 HTTP 提供工作区文件，以及为不在 Host 机器上的客户端提供预览。
 
 ## 问题
 
-一个产出了文件的 web 会话，没有办法看到那个文件。agent 写出了 `deepseek-homepage.html` 并如实告知，而用户唯一的办法是把 `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` 这样的绝对路径复制进终端。
+一个产出了文件的 web 会话，没有办法看到那个文件。agent（智能体）写出了 `deepseek-homepage.html` 并如实告知，而用户唯一的办法是把 `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` 这样的绝对路径复制进终端。
 
-这背后是两个不同的缺陷。转录从不说明一轮产出了什么：`ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方，因此读者对产出的唯一交代，就是收尾消息恰好拼出来的那点内容。而已经存在的那个交互是隐形的：`ToolRow` 早已把改写行或读取行的路径渲染成一个接到 `host.openPath` 的真按钮，但它的样式与周围正文一模一样、只有悬停才有下划线，于是没人发现。所报告的“做完了打不开”，是一个可发现性失败叠在一项本就可用的能力之上。
+这背后是两个不同的缺陷。transcript（文本记录）从不说明一个轮次产出了什么：`ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方，因此读者对产出的唯一交代，就是收尾消息恰好拼出来的那点内容。而已经存在的那个交互是隐形的：`ToolRow` 早已把变更行或读取行的路径渲染成一个接到 `host.openPath` 的真按钮，但它的样式与周围正文一模一样、只有悬停才有下划线，于是没人发现。所报告的“做完了打不开”，是一个可发现性失败叠在一项本就可用的能力之上。
 
 ## 决定
 
-**完成的一轮以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有空位与 owner 通货（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从改写工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
+**完成的轮次以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有该空位及其 owner 参数约定（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从变更工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，该轮次的产出都会被列出；新的变更工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一个轮次内按首见顺序只出现一次；累积在轮次边界重置，因此一个轮次若先变更文件、随后没有正文内容就结束，不会溢进下一轮的行里。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
 
 **路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
-**打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。
+**打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，否则，把 `.html` 绑给编辑器的开发者点开一个产出的页面，得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。
 
 **以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 更早的一版由 harness 自己提供文件——先是与 `/api` 同源，随后加上 `CSP: sandbox`，再后来交给一个以自身端口给所服务文档独立源的第二监听器。每一步都在回答一个真实问题，而整条线在产品范围定下之后被整体退役：不为“浏览器不在 Host 机器上”的场景提供预览。这一点定下之后，Host 打开器完整回答了受支持的场景，而那套 HTTP 机制回答的只是不受支持的那个。
 
 ## 考虑过的替代方案
 
-- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状契约。
+- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含通过双重 `realpath` 实现的路径约束、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状约定。
 - **同源 HTTP 提供且不加隔离**——经实测不安全，记录在此以免有人重试：与 `/api` 并排提供的文档把 `settings.describe` 打到 `200` 并拿到完整数据，把 `session.list` 打到 35 KB 的全部会话转录，而这个页面根本不必由 agent 撰写（一条 read 行就让 clone 下来的仓库里任何文件变得可打开）。
 - **在那套同源提供之上加 `Content-Security-Policy: sandbox`**——它以剥夺文档的源来堵住这个洞，而这经实测会破坏本功能存在的意义所在的那类页面：所报告的产物在加载时抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们渲染得完美无缺，所以这种破坏是看不见的。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它。
@@ -32,4 +32,4 @@ Status: implemented
 
 ## 影响
 
-现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接可见性修复与浏览器优先策略无需逐行改动即适用于全部。无密钥 web 通道（`apps/web/tests/produced-files.e2e.ts`）冷播种一段录制的 write 轮次，在组装后的应用中钉住该行；它刻意不点击，因为点击会把路径交给 Host 打开器，从而在跑测试的机器上启动一个真实应用。产出的文件以 `file://` 文档打开，它无法 `fetch` 自己的同级文件（一个加载 `./data.json` 的多文件产物会坏，而 `<script src>`、`<img>` 与 CSS `@import` 不受影响）——这是 HTTP 提供曾有、而此处没有的那一项能力。经网络访问的客户端点击后看不到任何东西：`host.openPath` 在 Host 上运行，且被 `/api` 信任 fence 钉在回环。那是范围决定的显现，不是缺陷，也正因如此该行把完整路径保留在 `title` 中，供只能复制它的读者使用。markdown 会由平台交给 `.md` 的默认处理程序打开，通常是编辑器而非渲染器；在产品内渲染它是另一个被推迟的交互面。
+现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接可见性修复与浏览器优先策略无需逐行改动即适用于全部。无密钥 web 通道（`apps/web/tests/produced-files.e2e.ts`）冷播种一段录制的 write 轮次，在组装后的应用中钉住该行；它刻意不点击，因为点击会把路径交给 Host 打开器，从而在跑测试的机器上启动一个真实应用。产出的文件以 `file://` 文档打开，它无法 `fetch` 自己的同级文件（一个加载 `./data.json` 的多文件产物会坏，而 `<script src>`、`<img>` 与 CSS `@import` 不受影响）——这是 HTTP 提供曾有、而此处没有的那一项能力。经网络访问的客户端点击后看不到任何东西：`host.openPath` 在 Host 上运行，且被 `/api` 信任 fence 钉在回环。那是范围决定的显现，不是缺陷，也正因如此该行把完整路径保留在 `title` 中，供只能复制它的读者使用。Markdown 会由平台交给 `.md` 的默认处理程序打开，通常是编辑器而非渲染器；在产品内渲染它是另一个被推迟的交互面。
diff --git a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml
index 1104d3f1d7..4f102704e0 100644
--- a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.md
 2026-07-31-workspace-write-surface-default.md: e6a36ad4ee7179cabf958114681728c3ac7340b4
-2026-07-31-workspace-write-surface-default.zh.md: 5ced928b167892d9abe1f4423da72a0243590735
+2026-07-31-workspace-write-surface-default.zh.md: fd18f2b69eb40df8392afb50892c7740d0e30af0
diff --git a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md
index 5ced928b16..fd18f2b69e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 真正的新会话会在执行前固定 `permission/preset: workspace-write`、`sandbox/mode: workspace-write` 和 `approval/policy: ask`。现有会话和恢复的会话保留日志中记录的权限，更改「通用」设置中的默认值只影响之后创建的会话。浏览器保留 Access 选择器、可应答的审批卡片，以及选择 Full access 时的风险确认。共享 Permission 服务在 TUI 中激活其命令子件，因此 TUI 会获得现有的 `/permission` 命令。
 
-该模式只管辖文件效果。受沙箱约束的 bash 与文件系统修改只允许写入会话工作区和平台临时根目录；读取、网络访问与进程可见性仍不受该策略约束。若没有平台 runner 能强制执行受限的 bash 调用，执行会以拒绝方式关闭，不会退回不受限命令。
+该模式只管辖文件效果。受沙箱约束的 bash 与文件系统修改只允许写入会话工作区和平台临时根目录；读取、网络访问与进程可见性仍不受该策略约束。若没有平台 runner 能强制执行受限的 bash 调用，执行会以拒绝告终，不会退回不受限命令。
 
 ## 测试
 
@@ -26,10 +26,10 @@ Status: implemented
 
 **保留不受限的 TUI，只更改浏览器回退值。** 不予采纳，因为这会保留无法解释的界面差异，并让全新的终端会话继续拥有本决策要移除的权限。
 
-**在同一次变更中添加终端审批对话框。** 不予采纳，因为这是另一个交互与生命周期决策。TUI 没有 `approval/request` 应答者，因此一次性自动升权当前会落定为不可用并以拒绝方式关闭；需要更宽权限的用户可以通过 `/permission` 主动选择其他 preset。
+**在同一次变更中添加终端审批对话框。** 不予采纳，因为这是另一个交互与生命周期决策。TUI 没有 `approval/request` 应答者，因此一次性自动升权当前会落定为不可用并以拒绝告终；需要更宽权限的用户可以通过 `/permission` 主动选择其他 preset。
 
 ## 后果
 
 全新的会话无需额外提示即可修改当前工作区与临时根目录，尝试修改其他位置则会在触及目标前被拒绝。Full access 仍可通过显式选择获得，浏览器选择时也仍会显示确认对话框。系统不会重写已存储的用户默认值和会话日志中记录的权限。
 
-由浏览器支撑的无头入口继承 Web 组合，因此默认值相同。TUI 缺少审批应答者是本次变更的明确限制：自动请求更宽权限的重试会在那里以拒绝方式关闭，而不会显示权限询问。
+由浏览器支撑的无头入口继承 Web 组合，因此默认值相同。TUI 缺少审批应答者是本次变更的明确限制：自动请求更宽权限的重试会在那里以拒绝告终，而不会显示权限询问。
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
index d4ec255235..a8bdc5b1d3 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.md
 2026-08-01-pwsh-tool-and-executor.md: 7206f8ffe6640f8499f8453c40ab5846b23112c6
-2026-08-01-pwsh-tool-and-executor.zh.md: 5a48adb79fed209d2d2ecb9514fd51538491f04c
+2026-08-01-pwsh-tool-and-executor.zh.md: bdc2563000a917cc1672a378c9e390354411c41c
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
index 5a48adb79f..bdc2563000 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
@@ -6,30 +6,30 @@ Status: implemented
 
 ## 问题
 
-harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能通过 WSL 或 Git-Bash 垫片运行它，而交付的 `dsh-bash-local` 执行器仅限 POSIX（硬编码 `bash`，进程组语义是 POSIX 的）。Windows 路线图——让主机默认 `pwsh`，之后再做 pwsh TUI/GUI 渲染——没有执行基础：既没有 bash 执行器 seam 的 PowerShell 实现，也没有教模型 PowerShell 方言的面向模型工具。bash 工具本身也远大于 Windows 优先画像所需：后台任务、沙箱升级与持久 PTY 孪生都是 bash 形状的表面，最小化的 `pwsh` 工具不该背负。
+harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能通过 WSL 或 Git-Bash 垫片运行它，而交付的 `dsh-bash-local` 执行器仅限 POSIX（硬编码 `bash`，进程组语义是 POSIX 的）。Windows 路线图——让主机默认 `pwsh`，之后再做 pwsh TUI/GUI 渲染——没有执行基础：既没有 bash 执行器 seam 的 PowerShell 实现，也没有教模型 PowerShell 方言的面向模型工具。bash 工具本身也远大于 Windows 优先配置所需：后台任务、沙箱升级与持久 PTY 对应工具都是针对 bash 设计的功能面，最小化的 `pwsh` 工具不该背负。
 
 ## 决策
 
 在 `packages/bash/` 下新增两个包：
 
-- **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 从配置默认化并设上限，`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为 ONE argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
-- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，契约是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
+- **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 根据配置设置默认值和上限，`run()` 通过一个 deadline 融合受配置上限约束的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为单个 argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
+- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，约定是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、不含沙箱功能面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染机制（正常退出不产生 marker）。parity 决策取代了本 Agent Note 的最小配置工具描述。
 
-Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
+Windows vitest 测试覆盖刻意不纳入本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
 
 本决策之后的路线图——让 Windows 主机默认 `pwsh`（关闭 bash）与 pwsh TUI/GUI 渲染——另行记录为[提案](../../proposed/feature/2026-08-01-windows-pwsh-default.md)。
 
 ## 备选方案
 
-**给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号实情、引号域）应各自归入自己包的文档。
+**给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号信息、引号域）应各自归入自己包的文档。
 
-**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型契约保持诚实。
+**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台任务与沙箱功能面都是针对 bash 设计的；`pwsh` 模式要么隐藏它（条件 schema 反复变动），要么继承它（把最小配置明确拒绝的功能面带进来）。精简版对应工具能让模型约定如实反映实际功能。
 
-**现在就接入交付的 CLI 组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接线点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
+**现在就接入交付的 CLI（命令行界面）组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接入点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
 
 ## 后果
 
-- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范契约一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
-- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 契约。
-- Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态实情仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
-- CLI 增加两个 workspace 依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
+- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范约定一致，因此 `tool-pwsh` 之外的面向模型消费方（钩子桥、进程内插件）无需方言垫片即可运行 PowerShell。
+- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（不含沙箱功能）上与 bash 工具行为可互换，提示词指导精确陈述 marker 约定。
+- Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态信息仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
+- CLI 增加两个工作区依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index 40e24e9ac2..174f5b98d1 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
 2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
-2026-08-02-pwsh-tool-bash-parity.zh.md: d7a68f0cab5281b25c3321e7ffff61c358b21a0a
+2026-08-02-pwsh-tool-bash-parity.zh.md: f4ee10484b6e49ebbaeb0b8ed4b0b30c5ac17e5c
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index d7a68f0cab..f4ee10484b 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -6,31 +6,31 @@ Status: implemented
 
 ## 问题
 
-首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见契约与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
+首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台（每次调用启动一个新进程；无持久 PTY 会话）、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（「恒打 `[exit code: N]`」）。对该变更的 review 发现模型可见约定与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
 
 ## 决策
 
-`dsh-tool-pwsh` 现在逐调用镜像 `dsh-tool-bash`，减去 sandbox 面，其模型可见文本精确描述这一行为：
+`dsh-tool-pwsh` 现在逐调用镜像 `dsh-tool-bash`，沙箱相关接口除外，其模型可见文本精确描述这一行为：
 
-- **渲染完全采用 bash 故事**：stdout、带标记的 `[stderr]` 段、带 spill 路径的截断通知、空体渲染 `(no output)`、退出 marker 仅限非零退出——干净退出不产生 marker。描述与 `tool:pwsh` prompt section 精确陈述这一点（"Non-zero exits are reported as `[exit code: N]` markers"），刻意不复制 bash prompt 中与其自身渲染矛盾的 "every result" 措辞。
+- **渲染完全采用 bash 故事**：stdout、带标记的 `[stderr]` 段、带 spill 路径的截断通知、空体渲染 `(no output)`、退出 marker 仅限非零退出——干净退出不产生 marker。描述与 `tool:pwsh` 提示词 section 精确陈述这一点（"Non-zero exits are reported as `[exit code: N]` markers"），刻意不复制 bash 提示词中与其自身渲染矛盾的 "every result" 措辞。
 - **`run_in_background` 经通用任务运行时接线**，与 bash 工具完全一致：预检、owner 注册、`task_output`/`task_kill` 控制与相同的结果映射。其背后是 `pwsh-local` 早已镜像好的 `start()` 句柄。
 - **`DSH_*` 环境共享而非复制**：`BashEnvRegistry` 从 `dsh-tool-bash` 迁入新的工具无关包 `@deepseek-ai/dsh-bash-env`（`ctx.bashEnv` + 内置事实 + session-persistence contributor），两个 shell 工具都注入它。contributor 对 pwsh 调用与 bash 调用一视同仁；因此，共享环境的所有权不属于任何一个面向模型的 shell 工具。
-- **Windows 现实在 bash 无对应处钉死**：每条命令都在 UTF-8 输出 preamble 下运行，使 Windows PowerShell 5.1 兜底无法经 UTF-8 解码的 collector 破坏非 ASCII 输出；prompt 教授 Windows 强制终止以无 signal 的 exit 1 结算。
-- **范围外，不变**：sandbox 升级（等待 Windows-confining 执行器）与持久 PTY shell（后端仅限 Linux/macOS；ConPTY 属路线图）。带退出 pill 的 pwsh 专属 terminal 卡已随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策另行交付。
+- **Windows 现实在 bash 无对应处钉死**：每条命令都在 UTF-8 输出 preamble 下运行，使 Windows PowerShell 5.1 兜底无法经 UTF-8 解码的 collector 破坏非 ASCII 输出；提示词说明：Windows 强制终止以 exit 1 结算，且不带 signal marker。
+- **范围外，不变**：沙箱升级（等待 Windows-confining 执行器）与持久 PTY shell（后端仅限 Linux/macOS；ConPTY 属路线图）。带退出 pill 的 pwsh 专属 terminal 卡已随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策另行交付。
 
 ## 备选方案
 
-**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本契约在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
+**保留最小画像，只修声明。** 否决：review 的核心发现是「从 bash 复制的文本约定在缺少对应实现时会漂移」；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
 
-**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对契约改由各工具 README 记录。
+**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对约定改由各工具 README 记录。
 
 **提取完全共享的工具实现基座（抽象 shell 方言，两个薄叶子）。** 考虑后推迟：bash-env 提取与结构镜像（`render.ts`/`background.ts` 孪生）是它要立足的基础；在出现第三种方言或持久 PTY 孪生、让抽象的形态可观察之前，不做完整基座。
 
 ## 后果
 
-- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书——reviewer 的“拿代码 grep 对证”检查通过。
-- 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture 钉住。
-- `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（spine bundle 已如此）。
+- bash 与 pwsh 工具在前台与后台 shell 工作（沙箱除外）上行为可互换，pwsh 的提示词/描述句每句都有渲染器背书——reviewer 的「拿代码 grep 对证」检查通过。
+- 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture（测试前置数据）钉住。
+- `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（主干组合包已如此）。
 - Windows 专属语义（CRLF 归一化、强制终止 exit-1/signal-null、仅 POSIX 的自信号）一如既往由测试钉住。
 - pwsh 工具的 per-file 覆盖门禁由可脚本化的 fake-executor 套件（`tests/tools.spec.ts`）承担；真实 pwsh 的集成与 Loader 组合套件在无 `pwsh` 的宿主自跳过，与 bash 套件的分工一致。
 - 路线图提案的 parity 阶段已交付；terminal 卡呈现阶段随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策交付（TUI 本身已移除），剩余阶段是 Windows 默认组合。
diff --git a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml
index d191e3926d..fd479c217e 100644
--- a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.md
 2026-08-02-session-search-not-shipped-default.md: 65bd72fff76210b726e7562fb8e88e5f8802434a
-2026-08-02-session-search-not-shipped-default.zh.md: 5e42a2c2323904117f9322b5c4a53c43c6ed3f2a
+2026-08-02-session-search-not-shipped-default.zh.md: 4eb0851c1e584b84847b6bb5118c8bb2f3156845
diff --git a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md
index 5e42a2c232..4eb0851c1e 100644
--- a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md
@@ -6,20 +6,20 @@ Status: implemented
 
 ## 问题
 
-[交付清单决策](2026-07-31-even-out-shipped-tool-rosters.md)把 `tool-session-query` 设为共享 [`cordis.patch.yml`](../../../../packages/bundle/base/cordis.patch.yml) 的默认行,于是交付的 TUI 与 Web surface 把这五个会话搜索工具(`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`)呈现给了模型。这与[面向模型的会话查询工具决策](2026-07-24-model-facing-session-query-tools.md)相抵触,该决策持需显式启用的立场,包 README 将其记录为「shipped host compositions do not mount it by default」。这份默认还交付了一个提示词段,向模型讲授一套既往工作搜索工作流,而没有任何用户要求过。
+[交付清单决策](2026-07-31-even-out-shipped-tool-rosters.md)把 `tool-session-query` 设为共享 [`cordis.patch.yml`](../../../../packages/bundle/base/cordis.patch.yml) 的默认行，于是交付的 TUI 与 Web surface 把这五个会话搜索工具（`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`）呈现给了模型。这与[面向模型的会话查询工具决策](2026-07-24-model-facing-session-query-tools.md)相抵触，该决策持需显式启用的立场，包 README 将其记录为「shipped host compositions do not mount it by default」。这项默认设置还交付了一个提示词段，向模型讲授一套既往工作搜索工作流，而没有任何用户要求过。
 
 ## 决策
 
-交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`:该行从共享的 `cordis.patch.yml` 移除,opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除,workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in,与面向模型的会话查询工具决策所述完全一致:ACP 示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考,自定义组合也可以连同超时与 spill 策略一起挂载该包。
+交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`：该行从共享的 `cordis.patch.yml` 移除，opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除，workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in，与面向模型的会话查询工具决策所述完全一致：ACP（Agent Client Protocol）示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考，自定义组合也可以连同超时与 spill 策略一起挂载该包。
 
-`ctx.sessionQuery` 服务本身保持挂载。`session-query-sqlite` 仍是 base 的一行,TUI 的 `session-reference` 消费它来实现 `/resume`,Web overlay 也继续把它 patch 成内存索引,供浏览器内容搜索使用。被移除的只有面向模型的消费方。
+`ctx.sessionQuery` 服务本身保持挂载。`session-query-sqlite` 仍是 base 的一行，TUI 的 `session-reference` 消费它来实现 `/resume`，Web overlay 也继续把它 patch 成内存索引，供浏览器内容搜索使用。被移除的只有面向模型的消费方。
 
 ## 曾考虑的替代方案
 
-- **把 `session-query-sqlite` 索引也一并移除**——否决,因为 `/resume` 和 Web 内容搜索框直接消费 `ctx.sessionQuery`;它们是宿主功能,不是模型工具,移除提供方会破坏它们。
-- **保留该行,但在每个 overlay 中禁用它**——否决,因为一条被禁用的 base 行仍会交付依赖,而且一行就能轻易重新启用;已记录的 opt-in 立场要求消费方不出现在交付的 surface 上,以 ACP 示例作为挂载参考。
-- **只在 TUI 上挂载**——否决,因为共享 base 是所有 surface 共用的一组行;surface 专属挂载会重新引入交付清单决策所消除的清单分裂。
+- **把 `session-query-sqlite` 索引也一并移除**——否决，因为 `/resume` 和 Web 内容搜索框直接消费 `ctx.sessionQuery`；它们是宿主功能，不是模型工具，移除提供方会破坏它们。
+- **保留该行，但在每个 overlay 中禁用它**——否决，因为一条被禁用的 base 行仍会交付依赖，而且一行就能轻易重新启用；已记录的 opt-in 立场要求消费方不出现在交付的 surface 上，以 ACP 示例作为挂载参考。
+- **只在 TUI 上挂载**——否决，因为共享 base 是所有 surface 共用的一组行；surface 专属挂载会重新引入交付清单决策所消除的清单分裂。
 
 ## 后果
 
-两个 surface 都回到同样的二十个无条件工具(ripgrep 可用时再加上 `glob`/`grep`),五个会话搜索 schema 及其提示词段也一并退出默认请求。两个 surface 上的交付组合测试都固定这份更小的目录,因此把会话搜索重新作为默认加回会触及同样的测试。想要会话搜索的用户从个人 overlay 或 ACP 示例挂载该消费方,并在挂载处添加依赖。
+两个 surface 都回到同样的二十个无条件工具（ripgrep 可用时再加上 `glob`/`grep`），五个会话搜索 schema 及其提示词段也一并退出默认请求。两个 surface 上的交付组合测试都固定这份更小的目录，因此把会话搜索重新作为默认加回会触及同样的测试。想要会话搜索的用户从个人 overlay 或 ACP 示例挂载该消费方，并在挂载处添加依赖。
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
index c12de68dc8..09ca7ae1aa 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
 2026-08-02-web-thinking-tail-scroll.md: 18e94b2e0075bf7099b9b48177de2e274896942a
-2026-08-02-web-thinking-tail-scroll.zh.md: 9b1428af7d3ab3c25509696619de75adc1cd7b7f
+2026-08-02-web-thinking-tail-scroll.zh.md: 494fc10c5a05e989fd5ea868bf6f2fd1e17c0add
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
index 9b1428af7d..494fc10c5a 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：Web 思考尾部滚动 —— 折叠态 reasoning 跟随实时输出
+# Agent Note: Web 思考尾部滚动——折叠态推理跟随实时输出
 
 Status: implemented
 
@@ -6,26 +6,26 @@ Status: implemented
 
 ## 问题
 
-Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠摘要。首行一旦出现，之后每个 reasoning delta 只会改变隐藏的正文。于是快速模型在思考时看起来静止，用户必须展开完整思维链才能确认输出仍在推进。产品事项表已经要求“thinking：滚动展示思维链更新、可展开”；当前行只满足了后半项。
+Web Think 行在已结算块和流式块中都把推理（reasoning）首行渲染成折叠摘要。首行一旦出现，之后每个推理 delta 只会改变隐藏的正文。于是快速模型在思考时看起来静止，用户必须展开完整思维链才能确认输出仍在推进。产品事项表已经要求“thinking：滚动展示思维链更新、可展开”；当前行只满足了后半项。
 
 ## 决策
 
-只有 reasoning block 是当前流式尾部、且仍处于折叠态的 Think 行会跟随实时输出。其摘要使用最新的非空行，而不是结算后的首行；已有单行摘要元素成为程序化横向滚动区，每次文本更新后钉到 `scrollWidth - clientWidth`。这里刻意直接赋值 `scrollLeft`，通过真实 delta 推进而不虚构独立的跑马灯速度：token 快则移动快，模型停顿则停止，短文本因滚动范围为零而保持静止。
+只有推理块是当前流式尾部、且仍处于折叠态的 Think 行会跟随实时输出。其摘要使用最新的非空行，而不是结算后的首行；已有单行摘要元素成为程序化横向滚动区，每次文本更新后钉到 `scrollWidth - clientWidth`。这里刻意直接赋值 `scrollLeft`，通过真实 delta 推进而不虚构独立的跑马灯速度：token 快则移动快，模型停顿则停止，短文本因滚动范围为零而保持静止。
 
-该行为由已有呈现组件拥有。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经拥有折叠／展开状态，因此由它决定摘要是否追随行内末端。不改变 session、wire、持久事件或模型可见契约。展开会移除折叠摘要，并让完整 reasoning 正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
+该行为由已有呈现组件负责。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经负责管理折叠、展开状态，因此由它决定摘要是否追随行内末端。不改变会话、协议格式（wire format）、持久事件或模型可见约定。展开会移除折叠摘要，并让完整推理正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
 
 ## 曾考虑的替代方案
 
 **播放与流式输出无关的 CSS 跑马灯。** 否决：它会在 provider 停顿时继续移动，让慢模型显得很快，破坏该交互本应暴露的吞吐信号。
 
-**始终显示完整 reasoning 字符串的固定后缀。** 否决：按字符切片可能截断单词或字素，在内容真正溢出前就丢掉当前行的开头，而且只会跳变，无法随每个 delta 移动。
+**始终显示完整推理字符串的固定后缀。** 否决：按字符切片可能截断单词或字素，在内容真正溢出前就丢掉当前行的开头，而且只会跳变，无法随每个 delta 移动。
 
-**自动滚动展开的 reasoning 正文或会话页面。** 否决：展开内容是阅读界面，强制跟随会与向上回看的用户争夺滚动；跟随器只属于折叠的单行摘要。
+**自动滚动展开的推理正文或会话页面。** 否决：展开内容是阅读界面，强制跟随会与向上回看的用户争夺滚动；跟随器只属于折叠的单行摘要。
 
 ## 后果
 
-折叠行现在会同时通过内容移动和已有扫光传达 provider 节奏，而结算后的 transcript 保持逐字节稳定。滚动更新只发生在流式累加器本就会触发的 React 渲染中；不会增加计时器、动画循环、订阅、持久状态或传输流量。较长的当前 reasoning 行仍会把完整文本留在 DOM 中，只以编程方式裁掉已经溢出的前缀，因此展开仍能显示完整 block，辅助技术读到的也仍是同一份当前摘要文本。
+折叠行现在会同时通过内容移动和已有扫光传达提供方节奏，而结算后的 transcript（文本记录）保持逐字节稳定。滚动更新只发生在流式累加器本就会触发的 React 渲染中；不会增加计时器、动画循环、订阅、持久状态或传输流量。较长的当前推理行仍会把完整文本留在 DOM 中，只以编程方式裁掉已经溢出的前缀，因此展开仍能显示完整 block，辅助技术读到的也仍是同一份当前摘要文本。
 
 ## 测试
 
-`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的无密钥场景会在 Chromium 中运行组装后的 Web 应用，以可观察的节奏回放真实录制的推理分片，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态回放的预期输出保持不变，证明历史摘要约定仍然稳定。
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
index b98c2bee56..97a03bb17b 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
 2026-08-02-win32-in-process-folder-dialog.md: 5389293605169ce5ca269a127de5f609b8b7dd11
-2026-08-02-win32-in-process-folder-dialog.zh.md: ef81bc1f65b2859de1eb60f74f79e4869da4746b
+2026-08-02-win32-in-process-folder-dialog.zh.md: db4a6503f37f4b9cc95ce79ab8f476aeedfe5a60
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
index ef81bc1f65..db4a6503f3 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：Win32 文件夹选择器迁至 koffi 子进程
+# Agent Note: Win32 文件夹选择器迁至 koffi 子进程
 
 Status: implemented
 
@@ -6,22 +6,22 @@ Status: implemented
 
 ## 问题
 
-Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` 的外部 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
+Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` spawn 出的 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
 
 ## 决策
 
-`packages/host/directory-picker-native` 现在经 koffi——它已是仓库其他 `win32.ts` 面的工作区依赖——在进程内打开 `IFileOpenDialog`（`FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_NOCHANGEDIR`），作为 win32 主层。COM 会话运行在 spawn 出的子进程中，模态 `Show` 永不阻塞宿主事件循环；子进程在阻塞前上报其原生线程 id，driver 通过向该线程的窗口反复投递 `WM_CLOSE`（`EnumThreadWindows`）来服务中止，关闭预算耗尽时 kill 子进程。对话框是子进程的第一个窗口，Windows 会自动激活它，无需手动前台调用。子进程线程启用宿主接受的最佳线程 DPI 感知（`SetThreadDpiAwarenessContext`，按 per-monitor-v2 → per-monitor → system-aware 级联并检查返回值），严格优于脚本的系统 DPI 上限；DPI 保持为纯外观的 best-effort——全部不被接受的宿主仍得到现代对话框，而不会降级。模块切分让覆盖率在任何主机上都诚实：`win32-dialog-logic.ts`（纯时序）与 `win32-dialog.ts`（driver）在任何平台对假件测试；`win32-dialog-bindings.ts` 对 mock 的 `koffi` COM 世界测试（`dsh-session-persistence-jsonl` 的技法）；POSIX 主机把真实 spawn 管道跑到 koffi 加载失败的拒绝；win32 主机跑真实的"打开并中止关闭"冒烟。先于本层存在的 PowerShell 链已被删除（见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）：该层无回退。
+`packages/host/directory-picker-native` 现在经 koffi——它已是仓库其他 `win32.ts` 代码的工作区依赖——在进程内打开 `IFileOpenDialog`（`FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_NOCHANGEDIR`），作为 win32 主层。COM 会话运行在 spawn 出的子进程中，模态 `Show` 永不阻塞宿主事件循环；子进程在阻塞前上报其原生线程 id，driver 通过向该线程的窗口反复投递 `WM_CLOSE`（`EnumThreadWindows`）来处理中止请求，关闭预算耗尽时 kill 子进程。对话框是子进程的第一个窗口，Windows 会自动激活它，无需手动前台调用。子进程线程启用宿主接受的最佳线程 DPI 感知（`SetThreadDpiAwarenessContext`，按 per-monitor-v2 → per-monitor → system-aware 级联并检查返回值），严格优于脚本的系统 DPI 上限；DPI 保持为纯外观的 best-effort——不接受其中任何一种的宿主仍得到现代对话框，而不会降级。模块切分让覆盖率在任何主机上都诚实：`win32-dialog-logic.ts`（纯时序）与 `win32-dialog.ts`（driver）在任何平台对假件测试；`win32-dialog-bindings.ts` 对 mock 的 `koffi` COM 世界测试（`dsh-session-persistence-jsonl` 的技法）；POSIX 主机运行真实的 spawn 管道，并验证其因 koffi 加载失败而拒绝；win32 主机跑真实的「打开并中止关闭」冒烟测试。先于本层存在的 PowerShell 链已被删除（见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）：该层无回退。
 
 ## 考虑过的替代方案
 
-- **预编译原生助手（`native/` 家族，如 `@deepseek-ai/node-addon-landlock-run`）。** 否决：再增加一个 npm 包家族、MSVC 供给和 Windows 构建／发布通道——只为交付约 150 行目前无法在 CI 中执行的 C（现有 CI 没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 面。
-- **N-API 进程内插件。** 否决：同样的 CI／工具链原因，另加需要自有 C++ 处理 STA 线程与消息泵，而子进程 + koffi 用 TypeScript 就能表达。
-- **保留 PowerShell 为主层并探测版本。** 否决：选择器仍被 shell 打包形态挟持（6 与 7、Store 别名、profile），且没有 pwsh 的机器地板仍是 5.1 的旧版对话框；仅把回退触发条件的拓宽吸收进回退层。
+- **预编译原生辅助程序（`native/` 家族，如 `@deepseek-ai/node-addon-landlock-run`）。** 否决：再增加一个 npm 包家族、MSVC 环境配置和 Windows 构建／发布通道——只为交付约 150 行仓库目前无法通过 CI 检验的 C 代码（现有 CI 没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 接口。
+- **N-API 进程内插件。** 否决：同样的 CI／工具链原因，还需自行维护处理 STA 线程与消息泵的 C++ 代码，而子进程 + koffi 用 TypeScript 就能表达。
+- **保留 PowerShell 为主层并探测版本。** 否决：选择器仍被 shell 打包形态挟持（6 与 7、Store 别名、profile），且没有 pwsh 的机器仍只能使用 5.1 的旧版对话框；只有拓宽回退触发条件这一项改动被纳入了回退层。
 - **在主线程上阻塞模态调用。** 直接否决：对话框打开期间 web 宿主必须继续服务 RPC。
 
 ## 后果
 
 - 每台 Windows 机器都得到带其所支持的最佳 DPI 感知（1703+ 为 per-monitor-v2）的现代对话框，无论是否安装 PowerShell。
-- 真实对话框渲染与选中路径仍是手动 Windows 检查（自动关闭冒烟证明打开／中止／收尾）。
-- 所用 COM vtable 槽位与 GUID 是冻结的 Windows ABI（Vista 起）；koffi 签名错误可能引发原生访问冲突，但被限制在对话框子进程内——宿主 Node 进程存活，失败原样上报（无回退层；见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。mocked-koffi 的 ABI 钉与真实 win32 冒烟正是为了在交付前捕获这类错误。
-- 打包二进制的臂——打包后的可执行文件以对话框入口形式自我 spawn——不受任何自动化测试覆盖：源码平面与普通 node 下构建出的 `lib/worker.cjs` 已被覆盖，打包 spawn 推迟到 Windows CI 路线图。
+- 真实对话框渲染与选中路径仍是手动 Windows 检查（自动关闭冒烟测试证明打开／中止／收尾）。
+- 所用 COM vtable 槽位与 GUID 是冻结的 Windows ABI（Vista 起）；koffi 签名错误可能引发原生访问冲突，但被限制在对话框子进程内——宿主 Node 进程存活，失败原样上报（无回退层；见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。mocked-koffi 的 ABI 钉与真实 win32 冒烟测试正是为了在交付前捕获这类错误。
+- 打包二进制路径——打包后的可执行文件以对话框入口形式自我 spawn——不受任何自动化测试覆盖：源码侧与普通 node 下构建出的 `lib/worker.cjs` 已被覆盖，打包 spawn 推迟到 Windows CI 路线图。
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index 98500c284e..f0dba56167 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
 2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
-2026-08-03-fs-tool-error-remedy.zh.md: 11acd0cf48924833ced91591d5ea1424735969cd
+2026-08-03-fs-tool-error-remedy.zh.md: ed3cbcf9c262db44321036fc1afcc829a5696b2f
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
index 11acd0cf48..ed3cbcf9c2 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -1,32 +1,32 @@
-# Agent Note: Guarded-mutation errors append the recovery instruction at the model boundary
+# Agent Note: 受防护变更错误在模型边界追加恢复指令
 
 Status: implemented
 
 [English](2026-08-03-fs-tool-error-remedy.md) | 中文
 
-## Problem
+## 问题
 
-受防护的 `write` 与 `edit` 失败以只陈述条件、不给出唯一正确恢复方式的消息到达模型：`FS_STALE_VERSION`（"file changed since it was read"）与 `FS_NOT_OBSERVED`（"edit requires reading … first"）。模型必须自行猜测恢复方式是重新读取（或首次读取）后重试，而基于结构化错误码路由的重试/权限/UI 层看到的也是同一段消息文本。提供方拥有的消息属于存储接缝的面向机器词汇（[filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)），因此恢复指令不能放在那里，否则会把面向模型的措辞泄漏给 `FsError` 的每个消费者。
+受防护的 `write` 与 `edit` 失败以只陈述条件、不给出唯一正确恢复方式的消息到达模型：`FS_STALE_VERSION`（"file changed since it was read"）与 `FS_NOT_OBSERVED`（"edit requires reading … first"）。模型必须自行猜测恢复方式是重新读取（或首次读取）后重试，而基于结构化错误码路由的重试/权限/UI 层看到的也是同一段消息文本。提供方拥有的消息属于存储 seam 的面向机器词汇（[文件系统能力 seam](../architecture/2026-06-17-filesystem-capability-seam.md)），因此恢复指令不能放在那里，否则会把面向模型的措辞泄漏给 `FsError` 的每个消费方。
 
-## Decision
+## 决策
 
-`dsh-tool-fs` 拥有一个面向模型的错误包装 `remediateFsError`（位于 `src/error.ts`），在 `write.ts` 与 `edit.ts` 中于沙箱拒绝映射之后应用。它为两个受防护变更错误码追加恢复指令，其余错误原样透传：
+`dsh-tool-fs` 拥有一个面向模型的错误包装层 `remediateFsError`（位于 `src/error.ts`），在 `write.ts` 与 `edit.ts` 中于沙箱拒绝映射之后应用。它为两个受防护变更错误码追加恢复指令，其余错误原样透传：
 
 - `FS_STALE_VERSION`（包括缺失的编辑目标——它与陈旧错误共用同一错误码）追加 `— re-read the file, then retry`。
 - `FS_NOT_OBSERVED` 追加 `— read the file, then retry`。
 
 结构化 `FsError` 错误码保持不变，使重试/权限/UI 层继续基于它路由；原始错误作为 `cause` 链入。提供方消息保持面向机器且不变。
 
-在 `edit.ts` 中，`fs/edit-intent` waterfall 现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent 槽抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
+在 `edit.ts` 中，`fs/edit-intent` waterfall（瀑布式事件）现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent slot抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-- **在 `dsh-fs` / `dsh-fs-local` 的提供方消息中追加恢复指令。** 被拒绝：这些消息是面向机器的接缝词汇，除模型表面外还被重试、权限与 UI 层消费；面向模型的措辞应位于模型边界，即 `dsh-tool-fs` 已经拥有结果格式化之处（[filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)）。
+- **在 `dsh-fs` / `dsh-fs-local` 的提供方消息中追加恢复指令。** 被拒绝：这些消息是面向机器的 seam 词汇，除面向模型的接口外还被重试、权限与 UI 层消费；面向模型的措辞应位于模型边界，即 `dsh-tool-fs` 已经拥有结果格式化之处（[文件系统能力 seam](../architecture/2026-06-17-filesystem-capability-seam.md)）。
 - **改为在提示词引导中加入恢复方式。** 被拒绝：失败发生在任务中途；静态指令无法可靠地影响重试决策，而错误消息恰好在模型必须行动时出现。
-- **用新的 `FsError` 错误码表达恢复指令。** 被拒绝：这两种失败本就是重试层已处理的相同条件；拆分错误码会让语义相同的路由分叉。
+- **用新的 `FsError` 错误码表达恢复指令。** 被拒绝：这两种失败对应的条件，重试层本就已经处理；拆分错误码会使相同语义采用不同路由。
 
-## Consequences
+## 后果
 
-两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装器（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
+两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装层（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
 
-恢复指令不是承诺：已删除的观察目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被新鲜观察之前，重试的变更以相同方式失败。
+恢复指令不是承诺：已观察但被删除的目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被重新观察之前，重试的变更以相同方式失败。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 2ba0af23c4..35628efcfe 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
 2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
-2026-08-03-web-search-source-scroll.zh.md: cf75a5e34632872d09a13e1667ecac5f01428e18
+2026-08-03-web-search-source-scroll.zh.md: 7d644b9e3950906b97d382e997eb3b204a577326
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index cf75a5e346..7d644b9e39 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -4,43 +4,43 @@ Status: implemented
 
 [English](2026-08-03-web-search-source-scroll.md) | 中文
 
-## Problem
+## 问题
 
-`web_search` 结果卡片（`WebBlock`，`packages/client/ui-primitives/src/WebBlock.tsx`）此前用首尾折叠渲染它的来源列表：超过 `maxSources` 数量（详情面板为 16，聊天行经由 `CHAT_WEB_MAX_SOURCES` 为 8）时，它画出前 `ceil(max/2)` 条来源、一个 `… 其余 N 条来源` 展开按钮，再画出末尾 `max - ceil(max/2)` 条，与 `TerminalBlock` 的输出上限一致。用户阅读该卡片时看到 `来源列表已截断`，会以为前端丢弃了它正持有的来源。
+`web_search` 结果卡片（`WebBlock`，`packages/client/ui-primitives/src/WebBlock.tsx`）此前用首尾折叠渲染它的来源列表：超过 `maxSources` 数量（详情面板为 16，聊天行经由 `CHAT_WEB_MAX_SOURCES` 为 8）时，它画出前 `ceil(max/2)` 条来源、一个 `… 其余 N 条来源` 展开按钮，再画出末尾 `max - ceil(max/2)` 条，仿照 `TerminalBlock` 的输出上限机制。用户阅读该卡片时看到 `来源列表已截断`，会以为前端丢弃了它正持有的来源。
 
 其实并没有。seam（`capSources`，`packages/web/web/src/index.ts`）把 provider 的来源裁剪到工具的 `searchMaxResults` 上限（默认 8）并置位 `truncated`，而这一份被裁剪过一次的列表同时喂给面向模型的 render 文本与卡片的 `presentationMeta`。卡片持有的来源绝不会多于这一次裁剪的产物。因此这个折叠隐藏的正是用户本有权完整查看的来源——并且在默认上限为 8、面板上限为 16 时，它几乎从不触发，只留下 `truncated` 提示，却无从展开任何内容。
 
-## Decision
+## 决策
 
 `WebBlock` 的 search 分支把它收到的每一条来源都渲染进单个 `<ol className={css.sources}>`，不做首尾切片、不设展开按钮、也不带 `maxSources` prop。`.sources`（`WebBlock.module.css`）获得一个固定的 `max-height` 与 `overflow-y: auto`，因此长于卡片高度的列表在原地滚动，而非撑大卡片或隐藏行。该高度是卡片几何形状的一个设计常量，因此放在 CSS 里，而非插件配置字段。
 
 模型侧不变：seam 仍在 `searchMaxResults` 处封顶来源，面向模型的 render 文本未动，`truncated` 标志及其 `来源列表已截断` 指示保留。卡片完整且可滚动地画出 seam 产出的这份列表，而非折叠其中段。
 
-只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的契约是它收到的 view，不是模型的上下文。
+只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的约定是它收到的 view，不是模型的上下文。
 
 `CHAT_WEB_MAX_SOURCES` 与该 primitive 的 `DEFAULT_WEB_MAX_SOURCES` 被移除：有了滚动，聊天行与详情面板展示同一份完整列表，仅以各自的容器高度区分。`<li value={ordinal}>` 仍钉住每条来源从 1 起算的引用序号；没有了折叠造成的间断，这些序号如今就是连续的。
 
 把列表变成滚动容器，也把它的 `padding-left` 从间距变成了正确性约束。滚动容器裁掉 inline-start 方向的溢出且无从滚回，而 `::marker` 右对齐到内容边缘，因此宽于 padding 的序号会静默丢掉前导数字——在列表原本的 20px 下，两位数序号被画成 `0.` 与 `1.`，而本该是 `10.` 与 `11.`。`searchMaxResults` 是无上界的正整数，因此该 padding 以 `em` 计量——相对列表自身的字体，也就是序号所继承的那个——装得下三位数序号（`999. ` 在应用字体栈下量得 2.35em），并保留一位数情形原有的间隙。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。指令很明确——保留上限与截断，加一个滚动条。
 
-**保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是死重；仅靠滚动即可约束高度。
+**保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是累赘；仅靠滚动即可约束高度。
 
 **把滚动高度做成插件配置字段。** 否决：该高度约束的是卡片在屏幕上的几何形状，而非部署策略，因此它属于 `WebBlock.module.css`，与 [Web result 卡片前端笔记](2026-07-30-web-result-card-frontend.md) 已作为本卡片几何固定在那里的圆角、表面与外边距并列。
 
-## Consequences
+## 后果
 
-工具返回的每一条来源始终存在于 DOM 中，因此 view 携带的来源没有一条被藏在交互之后。无论来源数量多少，卡片高度都受限；高于容器的列表在原地滚动。代价是滚动提示依赖平台的滚动条渲染：overlay 滚动条系统（macOS 默认）在指针离开时不显示常驻滚动条，因此被裁剪的列表依靠 `来源列表已截断` 提示加上被裁切的最后一行来表明还有更多内容。`WebSearchBlockProps`/`WebFetchBlockProps` 失去 `maxSources` prop，primitive 失去 `DEFAULT_WEB_MAX_SOURCES`，因此未来任何调用方都从构造上渲染完整列表，而不是靠传入一个很大的上限值。
+工具返回的每一条来源始终存在于 DOM 中，因此 view 携带的来源没有一条被藏在交互之后。无论来源数量多少，卡片高度都受限；高于容器的列表在原地滚动。代价是滚动提示依赖平台的滚动条渲染：overlay 滚动条系统（macOS 默认）在指针离开时不显示常驻滚动条，因此受高度限制的列表依靠 `来源列表已截断` 提示加上被裁切的最后一行来表明还有更多内容。`WebSearchBlockProps`/`WebFetchBlockProps` 失去 `maxSources` prop，primitive 失去 `DEFAULT_WEB_MAX_SOURCES`，因此未来任何调用方都从构造上渲染完整列表，而不是靠传入一个很大的上限值。
 
-## Testing
+## 测试
 
-`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一个 30 条来源的卡片渲染出全部 30 个 `<li>`，无 `[aria-expanded]`、无 `<button>`，每个 `<ol>` 子元素都是一条来源 `<li>`，且 `<li value>` 从 1 到 N 连续编号。`packages/client/ui-tool/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧未曾移动。
+`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一张含 30 条来源的卡片渲染出全部 30 个 `<li>`，无 `[aria-expanded]`、无 `<button>`，每个 `<ol>` 子元素都是一条来源 `<li>`，且 `<li value>` 从 1 到 N 连续编号。`packages/client/ui-tool/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧没有改动。
 
-jsdom 不解析 CSS Modules 布局，对任何元素都报 `scrollHeight === clientHeight`，因此它根本无从见证这次滚动。几何改由组装态浏览器钉住，位于 `apps/web/tests/web-search-round.e2e.ts`：其确定性 search double 返回 12 条 provider 结果，每条带标题、引用摘录与日期。这首先在真实组合里端到端钉住 seam 的裁剪——出厂 `searchMaxResults` 保留 8 条，面向模型的 render 文本含这 8 条标题、不含被丢弃的 4 条 URL，并含 `(Showing the first 8 sources. Refine the query for more.)`，`meta.truncated` 为 true。随后位于 aria golden 之后的一个用例展开 `web_search` 行，对卡片的 `<ol>` 断言：8 个 `<li>`、卡片内任何位置都没有 `<button>`、`来源列表已截断` 指示可见，以及计算样式 `max-height: 320px` 与 `overflow-y: auto`，`scrollHeight` 为 574、`clientHeight` 为 320。再后一个用例在列表自身继承的字体下量出 `999. ` 序号的宽度，要求计算后的 `padding-left` 不小于该宽度，从而把滚动容器无从滚回的那段序号空间钉在最宽序号上，而非钉在某一份 fixture 的来源条数上。录制的模型流与 aria golden 都未变动：replay 是对 fixture 中 `assistant/chunk` 条目的位置游标，而 search double 是 provider 经 `fetch` 抵达的另一个本地端点；捕获时卡片处于折叠状态，其 `<ol>` 不在 DOM 中，摘要行也不携带来源数量。
+jsdom 不解析 CSS Modules 布局，对任何元素都报 `scrollHeight === clientHeight`，因此它根本无从见证这次滚动。几何改由组装态浏览器钉住，位于 `apps/web/tests/web-search-round.e2e.ts`：其确定性 search double 返回 12 条提供方结果，每条带标题、引用摘录与日期。这首先在真实组合里端到端钉住 seam 的裁剪——出厂 `searchMaxResults` 保留 8 条，面向模型的 render 文本含这 8 条标题、不含被丢弃的 4 条 URL，并含 `(Showing the first 8 sources. Refine the query for more.)`，`meta.truncated` 为 true。随后位于 aria golden 之后的一个用例展开 `web_search` 行，对卡片的 `<ol>` 断言：8 个 `<li>`、卡片内任何位置都没有 `<button>`、`来源列表已截断` 指示可见，以及计算样式 `max-height: 320px` 与 `overflow-y: auto`，`scrollHeight` 为 574、`clientHeight` 为 320。再后一个用例在列表自身继承的字体下量出 `999. ` 序号的宽度，要求计算后的 `padding-left` 不小于该宽度，从而把滚动容器无从滚回的那段序号空间钉在最宽序号上，而非钉在某一份 fixture（测试前置数据）的来源条数上。录制的模型流与 aria golden 都未变动：回放是对 fixture 中 `assistant/chunk` 条目的位置游标，而 search double 是提供方经 `fetch` 抵达的另一个本地端点；捕获时卡片处于折叠状态，其 `<ol>` 不在 DOM 中，摘要行也不携带来源数量。
 
-## Related
+## 相关文档
 
 - [Web result card](2026-07-30-web-result-card.md) —— 本卡片消费的 `card: 'web'` 渲染意图分支与 `presentationMeta` 路由；那份裁剪过一次的列表的来源。
 - [Web result 卡片前端](2026-07-30-web-result-card-frontend.md) —— `WebBlock`、唯一的 `web-card-model` 派生，以及绘制该卡片的各渲染点由它拥有；本笔记替换掉它所规定的来源列表折叠，它的其余决策（一个组件绘制两种 kind、http(s) 链接 allowlist、单一派生、常驻姿态）依然成立。
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
index 4673ffaab7..7100fc33fc 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
 2026-08-04-claude-code-and-codex-subagent-backends.md: e81d1fb14f719331c503dba539d6a5ec0f1eed4f
-2026-08-04-claude-code-and-codex-subagent-backends.zh.md: 3c78e8d5a4ca1a86942971721ad05c631901f231
+2026-08-04-claude-code-and-codex-subagent-backends.zh.md: aa6d80e38c12a2808a27e93bde8aec5d71e6a509
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
index 3c78e8d5a4..aa6d80e38c 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 命名的 [`ctx.subagents`](2026-06-21-subagent-capability-seam.md) 注册表让父 agent（智能体）无需了解子级的运行方式即可委派工作，但 harness 需要通往真实 Codex 与 Claude Code 产品的第一方路径。每条路径都必须向产品交付一项自包含任务，让它在父会话的工作区中执行，返回最终回答或明确的失败或取消结果，并且不留下任何受管的产品进程。
 
-产品集成不得成为任务文本、cwd、取消、结果结算或进程树的第二责任方。因此，所需证据要区分三个事实：无密钥真实产品测试证明官方集成、原生身份验证形态、确定性答案与资源清理；Loader 组合测试证明公开包（package）和文档所示的工具配置无需启动产品即可加载；带密钥 e2e 证明生产提供方与真实产品能够从真实 DeepSeek 服务取得唯一答案。直接发起模型 HTTP 请求或使用产品替身无法取代上述任一产品运行层级；手工挂载插件无法取代 Loader 层级。
+产品集成不得成为任务文本、cwd、取消、结果结算或进程树的第二责任方。因此，所需证据要区分三个事实：无密钥真实产品测试证明官方集成、原生身份验证形态、确定性答案与资源清理；Loader 组合测试证明公开包和文档所示的工具配置无需启动产品即可加载；带密钥 e2e 证明生产提供方与真实产品能够从真实 DeepSeek 服务取得唯一答案。直接发起模型 HTTP 请求或使用产品替身无法取代上述任一产品运行层级；手工挂载插件无法取代 Loader 层级。
 
 ## 决策
 
@@ -55,7 +55,7 @@ Codex 0.146.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端
 
 启动回滚和已发布运行的资源释放都会关闭 SDK query、中止该次运行的控制器、调用共享的进程树终止机制，并等待整棵进程树退出。`Query.close()` 表达优雅的协议关闭意图，但不能取代子进程责任方的退出证明。Query 关闭失败、进程失败和清理失败仍可彼此独立地观察。
 
-带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 契约：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
+带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 约定：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
 
 ## 分发与证据
 
@@ -83,11 +83,11 @@ Claude Code 证据锁定 Agent SDK 0.3.220 及其平台分发的 Claude Code 2.1
 
 **由插件管理登录、产品主目录、模型、设置或权限。** 这些选择会在每个产品的原生配置之外建立另一套权威来源，并将一次性提供方扩张为账户管理功能。提供方只公开显式环境覆盖项和清理宽限期；无人值守交互会以默认拒绝方式失败。
 
-**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户契约，当前实现不会预先构建这些功能。
+**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户约定，当前实现不会预先构建这些功能。
 
 ## 后果
 
-用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 契约委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
+用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 约定委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
 
 每次委派都要承担新建产品进程和独立模型上下文的开销，且只有最终文本会到达父级。产品原生配置使行为取决于部署环境中安装的产品、账户状态和工作区设置。带密钥 e2e 运行还会消耗外部 API 配额，并依赖 DeepSeek 官方端点；对协议、失败、取消与审批的确定性覆盖仍由无密钥层级承担。提供方不会恢复会话、以流式方式传送进度、接受新的人工交互、回滚工具或文件副作用，也不会施加按实际经过时间触发的超时。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
index 86c05dc9bd..fa352e395b 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
 2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 598c10dc2373eeb821d05f349a662156b194c71b
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: f3a92d6645c7f98a60fd3c4431cdfb84babfd51b
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
index 598c10dc23..f3a92d6645 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
@@ -1,38 +1,38 @@
-# Agent Note：侧边栏的滚动条跟随指针
+# Agent Note: 侧边栏的滚动条跟随指针
 
 Status: implemented
 
 [English](2026-08-04-pointer-revealed-sidebar-scrollbars.md) | 中文
 
-## Problem
+## 问题
 
-侧边栏的会话列表只要有十来个会话就会溢出，从那一刻起它的滚动条就一直画在那里——所处的这一列大部分时间都是静止的，而列表行自己的操作按钮只在悬停时才出现。它是侧边栏里唯一始终常驻的构件，而在有人真的伸手去拖它之前，它不提供任何可操作性。产品诉求（2026-08-04）是只在指针位于侧边栏内时才绘制它，并留一小段拖尾，避免指针路过时它一闪而灭。
+侧边栏的会话列表只要有几个会话就会溢出，从那一刻起它的滚动条就一直画在那里——所处的这一列大部分时间都是静止的，而列表行自己的操作按钮只在悬停时才出现。它是侧边栏里唯一始终常驻的构件，而在有人真的伸手去操作它之前，它不提供任何可操作性。产品诉求（2026-08-04）是只在指针位于侧边栏内时才绘制它，并留一小段拖尾，避免指针路过时它一闪而灭。
 
-## Decision
+## 决策
 
 `SidebarRoot` 跟踪整列上的指针，只要指针不在列内就给根元素挂上 `quietBars` 类。该类选中的规则把 ui-theme 的那组间接变量——`--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`——重新绑定为 `transparent`，于是嵌套在这一列下的每个滚动区域都不绘制滑块。今天这样的区域只有会话列表；将来新增的区域会直接继承这一行为，而不需要逐个接入。
 
 拖尾是 `SCROLLBAR_LINGER_MS = 2000`：离开会启动一个定时器，进入会取消尚未触发的定时器，只有定时器真正触发才会把类加回去。指针越过列边界又折返时——绕过一个 portal 菜单，或是奔向某一行时冲过了头——不会看到滑块闪动。
 
-进入用的是列自身的 `pointerenter`；离开则按列的盒子判定，由一个只在滚动条可见期间存在的 `pointermove` 监听完成。DOM 包含关系无法判定离开：ui-settings 把整屏的设置面板渲染为这一列的 fixed 定位**后代**，指针移到该面板上——或在面板关闭后移到对话区——都不会在这里触发 `pointerleave`，滚动条就会继续画在一个没人指向的列上。元素自身的 leave 仍然保留，用于几何判定看不到的那一种情况：指针移出窗口后不再产生任何移动事件。
+进入用的是列自身的 `pointerenter`；离开则按列的盒子判定，由一个只在滚动条可见期间存在的 `pointermove` 监听完成。DOM 包含关系无法判定离开：ui-settings 把整屏的设置面板渲染为这一列的 fixed 定位*后代*，指针移到该面板上——或在面板关闭后移到对话区——都不会在这里触发 `pointerleave`，滚动条就会继续画在一个没人指向的列上。元素自身的 leave 仍然保留，用于几何判定看不到的那一种情况：指针移出窗口后不再产生任何移动事件。
 
 承载指针的是整列，而不是列表。奔向滚动条的指针会先经过 logo 行、New Session 胶囊和搜索框，所以只在列表上显示，会让滚动条等到指针已经落在行中间时才出现。
 
-`transparent` 正是让这次显示不触发任何布局的原因。列表上的 `scrollbar-gutter: stable` 存在的意义就是让行永不移动（见[空槽 Agent Note（agent 决策记录）](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)）；重新绑定的只是颜色，那份预留始终有效，所以滑块出现在列表本就为它留出的空间里。
+`transparent` 正是让这次显示不触发任何布局的原因。列表上的 `scrollbar-gutter: stable` 存在的意义就是让行永不移动（见[空槽 Agent Note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)）；重新绑定的只是颜色，那份预留始终有效，所以滑块出现在列表本就为它留出的空间里。
 
-选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定接缝：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
+选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定 seam：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
-这拓宽了重新绑定契约，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
+这拓宽了重新绑定约定，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
 
-隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何既滚动又绘制抬升表面的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
+隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何在抬升表面上滚动的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **只用列上的 CSS `:hover`，不引入 JavaScript 状态。** 整套机制只需一条规则，但它表达不出拖尾：指针越过边界的那一帧滑块就会消失，而那恰好是指针正奔向对话区或绕行 portal 菜单的时刻。诉求本身点名了拖尾，只有 hover 的版本读起来就是闪烁。
 
 **留在 CSS 里、用过渡拿到这段延迟**，即通过 `@property` 注册 `--dsh-scrollbar-thumb` 让该自定义属性可动画，再用 `transition-delay` 把颜色按住。因代价与作用范围被否决：这项注册对每个读取这组变量的表面都是全局的，却只为一列的时序服务；而且这套调色板实际渲染所走的 WebKit 滚动条伪元素并不可靠地支持过渡——延迟会被声明在观察不到它的地方。
 
-**直接把滚动条藏掉**——`scrollbar-width: none`，或对 `::-webkit-scrollbar` 用 `display: none`。被否决，因为这会连带取消那段预留：滚动条重新出现时要重新占走 8px，会把每一行都在显示它的那个指针底下横向推移，而这正是当初加入空槽预留所修掉的回归。
+**直接把滚动条藏掉**——`scrollbar-width: none`，或对 `::-webkit-scrollbar` 用 `display: none`。被否决，因为这会连带取消那段预留：滚动条重新出现时会重新占走 8px，使每一行都在触发其显示的指针下方横向移动，而这正是当初加入空槽预留所修掉的回归。
 
 **在应用内自绘一个覆盖式滑块**，并彻底隐藏原生滚动条，这是完全自定义淡入淡出所需要的做法。它换来任意样式，代价是命中测试、拖拽、滚轮、惯性以及两套调色板下的 hover 状态——在一个滚动条已由 token 统一主题化的客户端里，为观感付出的是一大片自持表面。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **滚动事件也触发显示**，让键盘或触摸驱动的滚动同样显示滚动条。被否决，因为那是在为触发它的输入方式画一个它用不上的可供性；行本身已经说明列表移动过了。
 
-## Consequences
+## 后果
 
 - 用键盘或触摸拖动滚动的列表，在拖尾结束后不显示滑块，因为这两种方式都不会把指针留在列上。e2e 会钉住这一点，而不只是把它写下来。
 - 拖动滑块本身移出列不会在拖动中途把它隐藏：滚动条会接管指针捕获，按住按键期间页面收不到 `pointermove`。已在 Chromium 实测——指针拖到列右侧 900px 处、超过拖尾窗口后，滚动条依然绘制并继续滚动。
@@ -48,15 +48,15 @@ Status: implemented
 - 嵌套在列内、为自身抬升层级把这组变量重新绑定到 l2 的抬升表面，会覆盖静默状态并继续绘制自己的滚动条。今天侧边栏内没有这样的表面。
 - 外壳的 DOM 现在带有一个状态类，因此 ui-sidebar 的外壳快照会钉住 `quietBars`，默认状态出现回归时表现为快照 diff，而不是需要有人从截图里看出来的东西。
 
-## Testing
+## 测试
 
 `packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx` 用假定时器把这个类走过各次跃迁：进入时显示，拖尾结束前 1 毫秒仍然显示，结束后 1 毫秒转为静默，以及窗口内折返会取消隐藏。另有两条覆盖几何判定的离开：落在列盒子之外的 `pointermove` 会在没有任何 DOM leave 的情况下隐藏滚动条（即设置面板那种形态），落回盒子之内的则取消待触发的隐藏。它还在拖尾进行中卸载组件并断言没有定时器存活——待触发的隐藏落到已销毁的组件上，正是这种写法容易犯的错。事件用的是带 `relatedTarget` 的 `pointerover`／`pointerout`，因为 React 由它们合成 enter 与 leave，而会忽略原生的那两个事件。
 
 `packages/client/ui-sidebar/tests/scrollbar-quiet-styles.spec.ts` 直接读样式表：该规则必须写出这组变量的两半——只重新绑定静止态滑块，会让指针一碰到滚动条就露出 hover 颜色——并且不得出现 `scrollbar-gutter`，那属于滚动区域自己。
 
-`apps/web/tests/sidebar-scrollbar.e2e.ts` 是两半在真实引擎里汇合的地方。它在每次读取颜色前先把指针停在列表上，因为一个从不移动鼠标的场景全程测到的都是静默状态，会变成空洞的绿。随后它自己的用例把指针移开，断言在 leave 当下滑块仍在绘制，轮询直到它解析为 `rgba(0, 0, 0, 0)`，在该状态下重新测量几何以证明滚动条隐藏期间那份预留依然生效，并以编程方式滚动列表——键盘或触摸拖动所做的事——来钉住无指针滚动不绘制任何滑块。提交的 golden 记录了两套调色板下、两个指针位置上的滑块颜色。
+`apps/web/tests/sidebar-scrollbar.e2e.ts` 是两半在真实引擎里汇合的地方。它在每次读取颜色前先把指针停在列表上，因为一个从不移动鼠标的场景全程测到的都是静默状态，会在未实际验证目标行为的情况下通过。随后它自己的用例把指针移开，断言在 leave 当下滑块仍在绘制，轮询直到它解析为 `rgba(0, 0, 0, 0)`，在该状态下重新测量几何以证明滚动条隐藏期间那份预留依然生效，并以编程方式滚动列表——键盘或触摸拖动所做的事——来钉住无指针滚动不绘制任何滑块。提交的 golden 记录了两套调色板下、两个指针位置上的滑块颜色。
 
-这条 e2e 的对照是一次 mutation，而它需要插件自己的产物：把 `quietBars` 从外壳中去掉，先重新构建 `@deepseek-ai/dsh-client-ui-sidebar`、之后再跑 `build:web`，该用例会因为滑块解析为 `rgb(229, 229, 229)`、而期望 `rgba(0, 0, 0, 0)` 而变红。只重跑 `build:web` 用的是过期产物，即使改动已被删除也照样通过，这正是[空槽 Agent Note（agent 决策记录）](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)记录过的陷阱。
+这条 e2e 的对照是一次 mutation，而它需要插件自己的产物：把 `quietBars` 从外壳中去掉，先重新构建 `@deepseek-ai/dsh-client-ui-sidebar`、之后再跑 `build:web`，该用例会因为滑块解析为 `rgb(229, 229, 229)`、而期望 `rgba(0, 0, 0, 0)` 而变红。只重跑 `build:web` 用的是陈旧产物，即使改动已被删除也照样通过，这正是[空槽 Agent Note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)记录过的陷阱。
 
 拓宽后的门禁也有自己的对照，每个都是对真实样式表的一处声明改动：把 `transparent` 与 l2 的 hover 混用，以及把 l2 token 包进 `color-mix(…)`，都会让这条成对断言变红。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
index b35cca4b38..17d590a110 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
 2026-08-04-web-composer-shared-width-axis.md: 96cddda25bf79e9f2df7a0298039c27f316befca
-2026-08-04-web-composer-shared-width-axis.zh.md: 9a9f5a513bbce8f3e97698d58ab48b0abdefb142
+2026-08-04-web-composer-shared-width-axis.zh.md: b5a455f9e8c561ae89faa9baf526fdbb263bc89a
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
index 9a9f5a513b..b5a455f9e8 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
@@ -4,19 +4,19 @@ Status: implemented
 
 [English](2026-08-04-web-composer-shared-width-axis.md) | 中文
 
-## Problem
+## 问题
 
-Web 会话列的各个界面各自独立设定尺寸：转录列、输入卡片、todo/goal/queue 停靠卡片、ask-question/approval/plan-review 接管卡片各自硬编码 max-width（736/752/776/800px 等变体）与各自的侧边内边距。这些界面在全宽下彼此漂移几个像素，在窄视口下偏差更大——有的面板保留了到屏幕边缘的间隙，有的却贴边。另外，输入卡片的控制行没有自适应行为——窄卡片下权限触发器的文字标签会挤压整行；锚定在卡片上的浮层菜单也可能渲染得比卡片更宽，越过其右边缘。
+Web 会话列的各个界面各自独立设定尺寸：transcript（文本记录）列、输入卡片、todo/goal/queue 停靠卡片、ask-question/approval/plan-review 接管卡片各自硬编码 max-width（736/752/776/800px 等变体）与各自的侧边内边距。这些界面在全宽下彼此漂移几个像素，在窄视口下偏差更大——有的面板保留了到屏幕边缘的间隙，有的却贴边。另外，输入卡片的控制行没有自适应行为——窄卡片下权限触发器的文字标签会挤压整行；锚定在卡片上的浮层菜单也可能渲染得比卡片更宽，越过其右边缘。
 
-## Decision
+## 决策
 
-一个内容宽度变量拥有整列。`--dsh-chat-content-width`（748px）声明在 ConversationRoot 的 `.root` 上——转录与 composer 座位是兄弟子树，声明必须放在共同祖先上，CSS 自定义属性才能通过继承同时到达两者。其他几何全部由它推导：输入卡片上限为 `content + 32px`（`--dsh-composer-card-max-width`），停靠卡片从卡片宽度中减去四个停靠 inset（4 × 8px）正好回到内容宽度，接管卡片直接使用内容宽度。窄视口不变式以结构而非数值表达：内容宽度的界面每侧 pad `calc(var(--dsh-composer-side-clearance) + 16px)`，而输入卡片只留裸 clearance（16px），因此"输入卡片 = 内容 + 32px"在任意视口宽度下都成立，而不只是在上限处。
+一个内容宽度变量控制整列。`--dsh-chat-content-width`（748px）声明在 ConversationRoot 的 `.root` 上——transcript 与 composer 座位是兄弟子树，声明必须放在共同祖先上，CSS 自定义属性才能通过继承同时到达两者。其他几何全部由它推导：输入卡片上限为 `content + 32px`（`--dsh-composer-card-max-width`），停靠卡片从卡片宽度中减去四个停靠 inset（4 × 8px）正好回到内容宽度，接管卡片直接使用内容宽度。窄视口不变式以结构而非数值表达：内容宽度的界面每侧 pad `calc(var(--dsh-composer-side-clearance) + 16px)`，而输入卡片只留裸 clearance（16px），因此「输入卡片 = 内容 + 32px」在任意视口宽度下都成立，而不只是在上限处。
 
 卡片内的控制行是一个 `container-type: inline-size` 容器，权限触发器在 460px 容器查询下收起文字标签（保留图标 + 下拉箭头）。查询刻意匿名：CSS modules 按模块哈希 `container-name`，InputBar 样式表里声明的名字永远无法匹配 PermissionSelect 样式表里写的查询——两个哈希后的名字悄然不同，查询永不触发。只有带模式图标的触发器才收起（`:has(.triggerIcon)`）；没有图标的宿主自定义模式保留文字作为其唯一标识。
 
-锚定在卡片上的浮层菜单（slash 菜单、command popupSelect）钳制到锚点宽度（`max-width: min(<设计上限>, 100%)`），过长的行以省略号截断而不是溢出卡片。Tooltip 气泡在钳制中保留 12px 的视口边缘安全距离（ui-primitives Tooltip）。
+锚定在卡片上的浮层菜单（slash 菜单、command popupSelect）钳制到锚点宽度（`max-width: min(<design cap>, 100%)`），过长的行以省略号截断而不是溢出卡片。Tooltip 气泡在钳制中保留 12px 的视口边缘安全距离（ui-primitives Tooltip）。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **保留各界面独立宽度，手工对齐数值。** 否决：本次改动消除的漂移正是手工对齐常量的残留；未来任何宽度调整都需要五处协同编辑，且没有任何机制强制这组关系。
 
@@ -26,6 +26,6 @@ Web 会话列的各个界面各自独立设定尺寸：转录列、输入卡片
 
 **用 JS ResizeObserver 实现标签收起。** 否决：容器查询是声明式的，无需监听器生命周期，而 460px 阈值无论哪种方案都是设计选择。
 
-## Consequences
+## 后果
 
 修改列宽现在是一行编辑，比例关系由构造保证——评审期间 736 → 748 的重调已经验证了这一点。代价是间接性：五个界面的宽度不再能从各自的样式表直接读出，需要沿变量链追到 ConversationRoot。容器查询收起增加了一个约束：InputBar 的行必须保持为尺寸容器；删掉那条声明会静默禁用权限触发器的自适应行为。匿名查询也意味着未来若在行与触发器之间出现第二个容器，它会截获该查询——届时查询必须迁移，或避免中间容器。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
index abb67be310..788e0c44fd 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
 2026-08-04-web-context-source-and-steer-marks.md: ca44702cf637c4250d141396ac22d206a16acc15
-2026-08-04-web-context-source-and-steer-marks.zh.md: 09cefd07e3b417b63f05ce430cfed7b30597452f
+2026-08-04-web-context-source-and-steer-marks.zh.md: da8b629da262ed462f84083030c4fdfb1083eb77
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
index 09cefd07e3..da8b629da2 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
@@ -1,16 +1,16 @@
-# Agent Note：Web transcript 标出上下文来源、召回与 steering
+# Agent Note: Web transcript 标出上下文来源、召回与 steering
 
 Status: implemented
 
 [English](2026-08-04-web-context-source-and-steer-marks.md) | 中文
 
-## Problem
+## 问题
 
-生产方向模型侧对话补充的一切内容，进入 Web transcript（文本记录）后只剩两种匿名形态。每一条已记录的非用户 `user/message`——skill 目录、运行时快照、经过对账的 `AGENTS.md` 指令、guard 提示、子 agent 汇报、跨会话快照——都塌缩成同一行 `上下文注入`，读者不逐行展开去读原始 JSON 就无从知道究竟注入了什么。steering（中途引导）的情况更糟：它渲染成与开轮提示完全相同的气泡，于是 transcript 无法说明哪一条消息打断了正在运行的轮次。
+生产方向模型侧对话补充的一切内容，进入 Web transcript（文本记录）后只剩两种匿名形态。每一条已记录的非用户 `user/message`——skill（技能）目录、运行时快照、经过对账的 `AGENTS.md` 指令、guard 提示、subagent 汇报、跨会话快照——都塌缩成同一行 `上下文注入`，读者不逐行展开去读原始 JSON 就无从知道究竟注入了什么。steering（中途引导）的情况更糟：它渲染成与开轮提示完全相同的气泡，于是 transcript 无法说明哪一条消息打断了正在运行的轮次。
 
 这些区分本来就是持久事实。`user/message.source` 是每个生产方都必须提供的可合并扩展来源，`agent/inbox/spliced` 则记录有身份的消息是从 `next-turn` 还是 `next-step` 进入和离开；把这些事实丢掉的只有呈现层。被这套 Web UI 取代的终端 transcript 本来会写出每张卡片的生产者，因此面对同一份日志，Web 侧是一次倒退。
 
-## Decision
+## 决策
 
 transcript 为非提示消息可能承担的三种角色分别命名：注入上下文、召回会话、steering。
 
@@ -22,7 +22,7 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 
 `MessageItem` 为持久与待处理的 steering 气泡加上 `插话` 标注。runtime 会重放持久 `agent/inbox/spliced` 事件；如果一条用户来源的消息以相同身份从 `next-step` 被领取，后续 `user/message` 就投影为 `SteeringMessageNode`。从排队轮次领取的消息仍是 `UserMessageNode`，非用户来源的 next-step 消息仍是上下文。这推翻了[已归档的取消 steer 入口与插话装饰决策](../../archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md)中的一条结论。当时移除徽章，是因为 composer 无法 steer，标签指向了用户做不到的动作。此后 composer 获得了 Steer 手势，却没有同步修订那份 note；本决策提供了它在「重新引入」条款中要求的产品决策，并订正了其中留下的过时事实。标注是这里唯一的 steering 装饰：composer 模式、Queue dock 的严格 steer 操作、待处理 steering 的生命周期仍归各自的所有者。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **在客户端本地化生产者名称。** 以插件 id 为键的字典读起来确实比 `@deepseek-ai/dsh-system-prompt` 好，但它会在每次重命名时悄悄失准，每新增一个生产者都要改客户端，而且对来自外部的日志根本无法命名。日志已经承载的来源，比客户端自己编出来的措辞更有价值。
 
@@ -34,13 +34,13 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 
 **把同一套名称扩展到 trajectory 表格。** 不在本次范围内：该表格的上下文单元格有自己的文本推导，而 issue 要求的是对话面。
 
-## Testing
+## 测试
 
 - `packages/client/runtime` 单元覆盖钉住每个来源分支、名称字段缺失／为空／类型不符时的回退、来源没有可读 kind 时的无名降级，以及 reset 和实时 append 路径上的 steering 重建。
 - `packages/client/ui-conversation` 的 jsdom 覆盖钉住角色标题、标题旁的生产者名称、展开后该名称的留存、无名时的标题形态，以及持久与待处理气泡上的 steering 标注。
 - 无密钥的组装 Web 黄金基线携带带名称的标题栏与 steering 标注，因此证明这些标识的是组装后的 transcript，而不只是组件测试。
 
-## Consequences
+## 后果
 
 - 读者一眼即可归因 transcript 中每一条非提示消息；即便面对本客户端版本从未见过其生产者的日志，标题栏依然如实。
 - 只要来源仅携带插件 id，UI 中的生产者名称就呈现为包名形态（`dsh-tool-skill`、`@deepseek-ai/dsh-system-prompt`）。这是拒绝客户端名称表的代价；想要更好名称的生产者应当记录更好的来源。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml
index 16ccf1cff3..54df52a8e9 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md
 2026-08-04-web-latency-throughput-metrics.md: 4d7627a9a38127259f1ba07121cea7282f794f2e
-2026-08-04-web-latency-throughput-metrics.zh.md: 09e59242b799a3f4d03b9e0259f1a5a0d85f6a53
+2026-08-04-web-latency-throughput-metrics.zh.md: f0089cb45775f2dc9701a7256119f04e4709dd76
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md
index 09e59242b7..f0089cb457 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-Web 聊天已经记录了逐步骤的 LLM 计时（`stepStartTime`／`firstTokenTime`／`completedTime`）和逐步骤 usage，trajectory 视图也按步骤展示它们，但聊天界面既回答不了「这一轮响应有多快」，也回答不了「这个会话跑得有多快」：assistant 页脚只显示轮次实际耗时，统计行也只折算墙钟时间总量。
+Web 聊天已经记录了逐步骤的 LLM（大语言模型）计时（`stepStartTime`／`firstTokenTime`／`completedTime`）和逐步骤 usage，trajectory 视图也按步骤展示它们，但聊天界面既回答不了「这一轮响应有多快」，也回答不了「这个会话跑得有多快」：assistant 页脚只显示轮次实际耗时，统计行也只折算墙钟时间总量。
 
 ## 决策
 
-包内折算 `ui-conversation` 的 `chat/turn-metrics.ts` 是从 assistant 节点推导延迟/吞吐读数的唯一位置。`assistantStepReading` 把一个节点转成一次步骤读数：TTFT（首 token 延迟）需要 `stepStartTime` 与 `firstTokenTime` 同时存在，解码时长需要 `firstTokenTime`，负时长收敛为零，输出 token 数只在不可信的 `usage` 值有限且非负时才采纳。`deriveTurnMetrics` 按轮次折算读数：编号最小的步骤拥有该轮次的 TTFT 槽位，吞吐用「同时携带两者的那些步骤」的输出 token 总和除以解码时长总和，因此缺采样的步骤直接退出而不是让比值失真；两个数字都没有的轮次不产生条目。
+`ui-conversation` 包内的折算逻辑 `chat/turn-metrics.ts` 是从 assistant 节点推导延迟/吞吐读数的唯一位置。`assistantStepReading` 把一个节点转成一次步骤读数：TTFT（首 token 延迟）需要 `stepStartTime` 与 `firstTokenTime` 同时存在，解码时长需要 `firstTokenTime`，负时长钳制为零，输出 token 数只在不可信的 `usage` 值有限且非负时才采纳。`deriveTurnMetrics` 按轮次折算读数：编号最小的步骤拥有该轮次的 TTFT 槽位，吞吐用「同时携带两者的那些步骤」的输出 token 总和除以解码时长总和，因此缺采样的步骤直接退出而不是让比值失真；两个数字都没有的轮次不产生条目。
 
 assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、`用时` 之后，形如 `首 token {s}秒 · {tps} tok/s`，未记录的数字各自省略。ChatView 仅在该轮次的 `turnTimings` 条目带有 `endTime` 时才显示读数：已加载窗口是日志的连续后缀，因此窗口内已结算的轮次必然带着它的全部步骤，首步 TTFT 是真实值而非窗口截断的产物。`formatLatencySeconds` 不带单位，各语言模板各自拥有秒后缀（`TTFT {seconds}s`／`首 token {seconds}秒`）。
 
@@ -18,7 +18,7 @@ assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、
 
 ## 考虑过的替代方案
 
-**持久的会话投影（token-meter 形态）。** 在 host 侧用 `ProjectionDefinition` 折算步骤计时可以跨越压缩与窗口分页、覆盖整个日志。是暂缓而非否决：投影状态必须保持 O(1)（只能均值，不能分位数），它需要 host 改动加 schema，而聊天统计行的耗时事实本就被记录为窗口作用域——新分组沿用该作用域。后续 PR 可以在不挪动这些读数的情况下补上持久投影。
+**持久的会话投影（token-meter 形态）。** 在 host 侧用 `ProjectionDefinition` 折算步骤计时可以跨越压缩（compaction）与窗口分页、覆盖整个日志。是暂缓而非否决：投影状态必须保持 O(1)（只能均值，不能分位数），它需要 host 改动加 schema，而聊天统计行的耗时事实本就被记录为窗口作用域——新分组沿用该作用域。后续 PR（Pull Request）可以在不挪动这些读数的情况下补上持久投影。
 
 **逐步骤页脚附属元素。** 让每条 assistant 消息显示自己的 TTFT，会给轮次中段的叙述节点挂上附属元素，而页脚设计刻意让它们保持无 chrome；trajectory 视图已经暴露逐步骤计时细节。
 
@@ -28,4 +28,4 @@ assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、
 
 窗口内已结算轮次的页脚在 hover 时于实际耗时之后显示 `首 token`／`tok/s`，统计行在墙钟时间旁以本地化标签显示窗口平均延迟与吞吐，全程不新增会话事件、不改 host。指标以省略的方式退化：没有计时或 usage 采样的提供方或步骤只是丢掉对应数字，而不会渲染成零。已加载窗口之外的更早历史仍不计入，已记录在包 README 的统计行限制中。
 
-两个读数都以实测墙钟时间作分母，因此都不可复现：同一个回放场景在本机连续两次跑出 69 与 70 tok/s，而一段 3 毫秒的回放流会读成 26333 tok/s。因此 Web aria golden 在既有的 `{{duration}}` 之外，把吞吐归一化为 `{{throughput}}`；页脚的装饰性分隔符也补上了两侧空格——没有它们，这些读数会连成一整串无障碍文本（`Ran for 13sTTFT 0.2s12 tok/s`），既让屏幕阅读器失去读数之间的边界，也让 `{{duration}}` 失去它赖以匹配的词边界。
+两个读数都来自实测墙钟时间，因此都不可复现：TTFT 是 `firstTokenTime - stepStartTime` 的时间差，吞吐则以 `completedTime - firstTokenTime` 的解码墙钟时长为分母。同一个回放场景在本机连续两次跑出 69 与 70 tok/s，而一段 3 毫秒的回放流会读成 26333 tok/s。因此 Web aria golden 在既有的 `{{duration}}` 之外，把吞吐归一化为 `{{throughput}}`；页脚的装饰性分隔符也补上了两侧空格——没有它们，这些读数会连成一整串无障碍文本（`Ran for 13sTTFT 0.2s12 tok/s`），既让屏幕阅读器失去读数之间的边界，也让 `{{duration}}` 失去它赖以匹配的词边界。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml
index 900bc3562d..1e3ada6894 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md
 2026-08-04-web-slash-command-fuzzy-discovery.md: 8d7fe88f8d19a6edc7b51e63578c468df085c238
-2026-08-04-web-slash-command-fuzzy-discovery.zh.md: d3efdc23351a1b50853ee76fb731aee046004750
+2026-08-04-web-slash-command-fuzzy-discovery.zh.md: a96f9c984e32dd777950b9f9d8594b3a9c8b7c17
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md
index d3efdc2335..a96f9c984e 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md
@@ -4,17 +4,17 @@ Status: implemented
 
 [English](2026-08-04-web-slash-command-fuzzy-discovery.md) | 中文
 
-## Problem
+## 问题
 
 Web 命令菜单要求按命令名前缀匹配，因此用户只记得关键字母却不记得其准确位置时，就无法发现命令。扩大菜单的匹配范围可使命令更易发现，但命令执行仍必须保持精确匹配和确定性：近似输入行绝不能执行相近命令。
 
-## Decision
+## 决策
 
 `/` 命令 source 将键入的查询作为不区分大小写的有序子序列，与命令名进行模糊匹配。精确前缀构成排名最高的一类匹配。在每类匹配中，对齐分数越高越优先：分隔符边界和相邻字符会提高分数，前导字符和间隔会降低分数；分数相同则保持 host 目录和 client contribution 的顺序。位置过滤仍会在排名前从行内菜单中移除接收参数的命令。
 
-评分器对每个候选项使用动态规划，时间复杂度为 `O(query length × name length)`，空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名；命令描述不影响匹配。菜单选择仍派发所选的精确名称，而 space 与 Enter 裁决继续要求命令 token 精确匹配。
+评分器对每个候选项使用动态规划，时间复杂度为 `O(query length × name length)`，空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名；命令描述不影响匹配。菜单选择仍派发所选的精确名称，而空格键和 Enter 键的判定逻辑仍要求命令 token 精确匹配。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **保留仅前缀匹配。** 否决，因为本功能要解决的用户无法准确回忆前缀的问题依然存在：`/cpt` 无法发现 `/compact`。
 
@@ -22,6 +22,6 @@ Web 命令菜单要求按命令名前缀匹配，因此用户只记得关键字
 
 **使用通用模糊搜索依赖。** 否决，因为该界面只需对小型命令目录使用一种受限的子序列规则；可配置搜索索引会增加 bundle 体积，并引入产品未使用的排名行为。
 
-## Consequences
+## 后果
 
-用户可以凭按顺序记得的字母发现命令；只要目录相同，排名就保持稳定。评分刻意采用启发式规则：与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。包（package）测试固定各项排名因素以及同分时的稳定顺序，组装后的 Web 回放快照固定 `/cpt` 解析为 `/compact` 的行为。精确执行语义保持不变。
+用户可以凭按顺序记得的字母发现命令；只要目录相同，排名就保持稳定。评分刻意采用启发式规则：与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。包测试固定各项排名因素以及同分时的稳定顺序，组装后的 Web 回放快照固定 `/cpt` 解析为 `/compact` 的行为。精确执行语义保持不变。
diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml
index 059f6d2a0e..7858bc5077 100644
--- a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md
 2026-08-05-composer-context-meter-breakdown.md: a757bcbc8bc57f4c3a16f663a9c922155b8bb575
-2026-08-05-composer-context-meter-breakdown.zh.md: 441fd3013f2db721527838955b5ce227865615f1
+2026-08-05-composer-context-meter-breakdown.zh.md: a6db86b437dedb848cb9bc9bf3bd1be23f2f355c
diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md
index 441fd3013f..a6db86b437 100644
--- a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N% of X`）挤在计费分组之间。它回答了「有多满」，却回答不了「被什么占满」：没有任何地方展示窗口在系统提示词、工具 schema 与对话之间如何分配，而单行统计行也容纳不下这种明细。可用的数字还分属两套口径——来自 `contextPressure` 的提供方精确计费 prompt 规模，与 token-meter 的固定字符启发式——没有任何既有界面能在不混淆两者的前提下展示组成。
+Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N% of X`）挤在计费分组之间。它回答了「有多满」，却回答不了「被什么占满」：没有任何地方展示窗口在系统提示词、工具 schema 与对话之间如何分配，而单行统计行也容纳不下这种明细。可用的数字还分属两套口径——来自 `contextPressure` 的提供方精确计费的提示词规模，与 token-meter 的固定字符启发式——没有任何既有界面能在不混淆两者的前提下展示组成。
 
 ## 决定
 
@@ -14,17 +14,17 @@ Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N
 
 `dsh-session` 导出纯函数 `deriveEventMessage(event)`（此前只能通过 `Session` 方法访问，该方法现在委托给它），使 host 侧 fold 无需 `Session` 实例即可为表层节点计价。
 
-`dsh-token-meter` 把计价启发式抽取到 `src/estimate.ts`、把位置表层折叠抽取到 `src/surface-fold.ts`（两者都与测量服务逐字共享），并注册第三个会话投影 `contextBreakdown`，携带 `systemTokens` / `toolsTokens` / `messageTokens`。envelope 数字在每条 `request/header` 上经 `canonicalHeader` 按后者胜重新计价；消息数字在逐节点 `{seq, tokens}` 列表上重放 `foldSurfaceTokens`，因此它在每个事件边界上按构造等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。这份共享折叠是全函数且总是新建数组——返回下一个表层而不是原地改写——从而保留了服务侧「先校验再提交」的重放事务：抛出时重放游标不前进，同一条畸形事件在重试时报同样的错。折叠表层中不存在的替换范围会直接抛出：已提交日志在追加时就经过表层校验，无法解析的范围是日志损坏，而不是可跳过的事件。
+`dsh-token-meter` 把计价启发式抽取到 `src/estimate.ts`、把位置表层折叠抽取到 `src/surface-fold.ts`（两者都与测量服务逐字共享），并注册第三个会话投影 `contextBreakdown`，携带 `systemTokens` / `toolsTokens` / `messageTokens`。envelope 数字在每条 `request/header` 上经 `canonicalHeader` 按后者胜重新计价；消息数字在逐节点 `{seq, tokens}` 列表上重放 `foldSurfaceTokens`，因此它在每个事件边界上按构造等于 `measure().surfaceTokens`，压缩（compaction）会像缩小下一个请求那样缩小它。这份共享折叠是全函数且总是新建数组——返回下一个表层而不是原地改写——从而保留了服务侧「先校验再提交」的重放事务：抛出时重放游标不前进，同一条畸形事件在重试时报同样的错。折叠表层中不存在的替换范围会直接抛出：已提交日志在追加时就经过表层校验，无法解析的范围是日志损坏，而不是可跳过的事件。
 
-`ui-conversation` 把上下文占用率从统计行移走（一个事实一个家），放到 composer 尾部的 `ContextMeter`：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，点击弹出的面板把提供方精确的百分比与 `~已用 / 容量` 标题，与 4px 分色分段进度条及带 `~` 前缀的组成明细行并列。两套口径刻意永不对账——启发式占比只用于切分进度条的彩色分段与明细行，且每个启发式数字都标 `~`，因为固定的「4 字符≈1 token」启发式会系统性低估 CJK 文本与代码。（本记录落地时，圆环、标题与进度条总长取的是提供方精确值；它们现在改读锚定在提供方读数上的 `projectedTokens`，因为裸样本看不见压缩——见[仪表对压缩的失明](../bug-fix/2026-08-05-context-meter-blind-to-compaction.md)。）标题是一整句本地化文案（`context.aria`，与圆环的无障碍名共用），在 `{percent}` 槽位处切开渲染，于是读数的位置由各语言自己决定——英文在前、中文在后——同时读数保留自己的字重；宽度算出为零的分段直接不渲染，否则 `.segment` 的 min-width 会在 0% 占用时画出一段填充色。
+`ui-conversation` 把上下文占用率从统计行移走（一个事实一个家），放到 composer 尾部的 `ContextMeter`：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，点击弹出的面板把提供方精确的百分比与 `~已用 / 容量` 标题与 4px 分色分段进度条及带 `~` 前缀的组成明细行并列。两套口径刻意永不对账——启发式数字只决定进度条各彩色分段之间的相对比例，并原样显示在明细行中；每个数字都标有 `~`，因为固定的「4 字符≈1 token」启发式会系统性低估 CJK 文本与代码。（本记录落地时，圆环、标题与进度条总长取的是提供方精确值；它们现在改读锚定在提供方读数上的 `projectedTokens`，因为裸样本看不见压缩——见[仪表对压缩的失明](../bug-fix/2026-08-05-context-meter-blind-to-compaction.md)。）标题是一整句本地化文案（`context.aria`，与圆环的无障碍名共用），在 `{percent}` 槽位处切开渲染，于是读数的位置由各语言自己决定——英文在前、中文在后——同时读数保留自身独立的强调样式；宽度算出为零的分段直接不渲染，否则 `.segment` 的 min-width 会在 0% 占用时画出一段填充色。
 
 ## 备选方案
 
 **在客户端从已加载窗口推导组成。** 窗口是日志的连续后缀：携带系统提示词与工具 schema 的 `request/header` 事件可能在窗口之外，翻页还会让数字悄悄变化。只有持久的 host 侧投影能在翻页与压缩后幸存，这正是数据以第三个投影而非聊天窗口 fold 的形式过线的原因。
 
-**把启发式明细行按比例缩放到与 `pressureTokens` 相加一致。** 强行对账是在捏造精度：压力滞后一个请求，还包含估算器从不建模的提供方封装开销，会让明细行在组成毫无变化时也跟着变动。最终选择以显式 `~` 展示估算器的真实口径。
+**把启发式明细行按比例缩放，使其总和等于 `pressureTokens`。** 强行对账是在捏造精度：压力滞后一个请求，还包含估算器从不建模的提供方封装开销，会让明细行在组成毫无变化时也跟着变动。最终选择以显式 `~` 展示估算器的真实口径。
 
-**更细的类别（rules、skills、MCP 工具，如 Claude Code 的 `/context`）。** 在这里不可分：harness 在请求标头存在之前就把这些贡献折入系统文本与工具列表，因此三个类别是诚实的分辨率。
+**更细的类别（rules、skill（技能）、MCP 工具，如 Claude Code 的 `/context`）。** 在这里不可分：harness 在请求标头存在之前就把这些贡献折入系统文本与工具列表，因此三个类别是诚实的分辨率。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 65d14e9aa4..2ce390fda0 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
 2026-08-05-context-form-vocabulary.md: 618c11b925208d09a62d10101656e3358e327ddb
-2026-08-05-context-form-vocabulary.zh.md: 66278b261f23601461c96f08e87ea58766b2bfc2
+2026-08-05-context-form-vocabulary.zh.md: b68672cd3338a11ea7b924198ce81380f99296fa
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 66278b261f..b68672cd33 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -1,41 +1,41 @@
-# Agent Note：由生产方声明的上下文形态
+# Agent Note: 由生产方声明的上下文形态
 
 Status: implemented
 
 [English](2026-08-05-context-form-vocabulary.md) | 中文
 
-## Problem
+## 问题
 
 每一条已记录的非用户 `user/message` 都通过同一个内容区渲染：把整条消息序列化成内联 JSON。读者展开一行，看到的是 `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`——转义把唯一值得读的东西（面向模型的散文）压成了一行，而来源信息又和它挤在同一坨里。
 
-在标题栏写出生产者（[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)）解决了「这是谁加的」。它解决不了「加进来的是什么东西」，因为日志里根本没有这句话。注入上下文不是一种形状：对账后的 `AGENTS.md`、可用 skill 的目录、运行时策略快照、子 agent 的汇报，彼此之间的差别不亚于终端卡片与 diff 卡片，然而这四者呈现出来是同一堵转义 JSON 的墙。
+在标题栏写出生产者（[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)）解决了「这是谁加的」。它解决不了「加进来的是什么东西」，因为日志里根本没有这句话。注入上下文不是一种形状：对账后的 `AGENTS.md`、可用 skill（技能）的目录、运行时策略快照、subagent 的汇报，彼此之间的差别不亚于终端卡片与 diff 卡片，然而这四者呈现出来是同一堵转义 JSON 的墙。
 
 工具面早就解决过同一个形状问题。`ToolCallView` 只有三种卡片，而不是每个工具一种，由工具自己声明本次调用属于哪一种。上下文没有对应物：既没有形状词汇表，生产方也无从声明自己发出的是哪一种。
 
-## Decision
+## 决策
 
 `MessageSource` 新增一个可选、由生产方声明的 `form: ContextForm`——一份关于信息**形状**的小型 tagged 词汇表，与 `kind` 相互独立：
 
 - `kind` 回答**由谁产生**，保持纯粹的溯源语义。
 - `form` 回答**这是何种形态的信息**。多个生产方可以共用一种形态，一个生产方在一次会话中也可以发出多种。
 
-该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。本次声明两个：
+该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。当前词汇表声明六种形态：
 
 **`instructions`**——从工作区文件中读出的指令。`workspace-context` 在启动基线与后续增量上都声明它；其既有的 `changes[]` 已经携带了呈现所需的路径、动作与 digest，因此没有新增字段。内容区在正文之上列出对账过的文件，并原样保留 `<system-reminder>` 包装：那层包装本就是模型读到的一部分，隐藏它会歪曲这次请求。
 
-**`catalog`**——本会话可用项的目录，随变化重新发布。`dsh-tool-skill` 从共享的 `plugin` kind 迁到自有的 `skill-catalog` 来源，携带 `entries`（本次发布的 `name`／`description` 对）与替换目录上的 `update`，后者由内容区渲染成替换提示。内容区直接列出这些条目，不再从散文里反解 `<available_skills>` 块。
+**`catalog`**——本会话可用项的目录，随变化重新发布。`dsh-tool-skill` 从共享的 `plugin` kind 迁到自有的 `skill-catalog` 来源，携带 `entries`（本次发布的 `name`／`description` 对）以及替换时的 `update`，后者由内容区渲染成替换提示。内容区直接列出这些条目，不再从散文里反解 `<available_skills>` 块。
 
 条目记录的是**未转义**的发布事实。伪 XML 转义属于 `<available_skills>` 这层为模型而设的框架，因此只在渲染该框架时施加、从不存储；否则消费方要正确展示含 `<` 的描述就得知道框架的编码方式，本决策刚移除的框架知识会换一种形式泄漏回来。`escapeText` 确定且单射，故对未转义条目取 digest 与此前完全等价，重新发布语义不变，面向模型的文本逐字节不变。
 
-这次迁移同时挪动了目录的**身份**：重新发布用的 digest 现在覆盖持久条目而非渲染文本，于是面向模型的包装再也无法左右是否需要重新发布，那段从已记录消息里切出条目的文本切分逻辑也随之删除。若恢复的会话中最新目录早于本次改动，会重新发布一次——发布前阶段的姿态允许这样做。有一种情形不会自愈：当那份旧格式目录是唯一的一份、且当前视图没有任何 skill 时，插件看不到已发布目录，也就不会发出 tombstone，模型手里会留着一份无人替换的过期目录。发布前阶段的姿态（「后端拒绝旧的磁盘格式」）允许这一点；此处如实记录，而不是只写乐观路径。
+这次迁移同时挪动了目录的**身份**：重新发布用的 digest 现在覆盖持久条目而非渲染文本，于是面向模型的包装再也无法左右是否需要重新发布，那段从已记录消息里切出条目的文本切分逻辑也随之删除。若恢复的会话中最新目录早于本次改动，会重新发布一次——发布前阶段的姿态允许这样做。有一种情形不会自愈：当那份旧格式目录是唯一的一份、且当前视图没有任何 skill 时，插件看不到已发布目录，也就不会发出 tombstone，模型手里会留着一份无人替换的陈旧目录。发布前阶段的姿态（「后端拒绝旧的磁盘格式」）允许这一点；此处如实记录，而不是只写乐观路径。
 
 **`snapshot`**——会被同一生产方后续快照取代的当前状态。运行时快照、`time-context`、`tmux-context` 声明它。`renderContextSections()` 暴露出装配时的具名贡献——`renderContextSnapshot()` 本来就是把它们拼给模型的——因此内容区能把每一段归属到产生它的子系统，而不必去切分已经拼好的散文。两个单贡献生产方各记录一段。运行时快照的「已清空」标记没有任何贡献可归属，因此不声明形态。
 
 **`notice`**——刚刚发生了什么的一次性说明。`tool-tasks`、`tool-goal` 收尾、`plan-mode` 切换与 `repeat-tool-guard` 提醒都带 `summary` 声明它，而该摘要出现在**折叠态**行上：notice 的全部意义就是不展开也能读完。摘要在其输入是调用方文本时自行封顶（任务的 label 与状态 detail 本身没有长度约束）。Goal 状态变更仍是由领域层持有的 `goal/change` 事件，而非模型上下文，因此不声明 form。
 
-**`relay`**——另一个 agent 发给本 agent 的消息。两个子 agent 定向来源都声明它；发送方以来源已记录的不透明会话 id 呈现，因为本客户端无法把它解析成标题。
+**`relay`**——另一个 agent（智能体）发给本 agent 的消息。两个 subagent 定向来源都声明它；发送方以来源已记录的不透明会话 id 呈现，因为本客户端无法把它解析成标题。
 
-**`recall`**——从另一个会话日志搬来的材料。`session-reference` 声明它，且不需要新增字段：其 references 已经记录了标题、保留与省略条数、截断标记，内容区把这些放在最前面——召回上下文在进入时是有界的，隐藏省略条数的卡片会夸大模型实际收到的内容。
+**`recall`**——从另一个会话日志搬来的材料。`session-reference` 声明它，且不需要新增字段：其 references 已经记录了标签、保留与省略条数、截断标记，内容区把这些放在最前面——召回上下文在进入时是有界的，隐藏省略条数的卡片会夸大模型实际收到的内容。
 
 两个读取器都是**全有或全无**：一条不可读的条目即判定整条记录不可用，而不是把它丢掉——会替换掉面向模型文本的内容区，不得给出自信但残缺的「模型读到了什么」。行上的形态标记报告的是实际渲染出的形态，而非声明的形态。
 
@@ -45,9 +45,9 @@ Status: implemented
 
 ## 为什么不做 presenter 注册表
 
-工具接缝把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
+工具 seam 把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **在客户端把来源 kind 映射到渲染器。** 写起来最省，也不用改格式，但它把生产方知识放回了客户端：此后每新增一个 kind 都要客户端发版才能渲染成 opaque 以外的东西，而外部日志根本无法分类。它还会重新引入[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)刚为名称去掉的那种耦合。
 
@@ -57,17 +57,17 @@ Status: implemented
 
 **把 instructions 渲染成 Markdown。** 正文本来就是 Markdown 文件，渲染出来更好读。但文本同时携带 `<system-reminder>` 包装，Markdown 渲染器会把它当原始 HTML 丢弃，于是 Markdown 内容区会悄悄隐藏模型读到的一部分。推迟到生产方按文件结构化记录内容之后再做。
 
-## Testing
+## 测试
 
 - `packages/client/runtime` 钉住形态投影，包括必须降级为 opaque 的未知值、空值、类型不符与缺失。
 - `packages/client/ui-conversation` 逐个钉住内容区：opaque 的换行留存与来源字段、instructions 的文件列表与原样包装、catalog 的条目列表，以及条目不可用的 catalog 回落到 opaque。
 - `packages/skill/tool-skill` 钉住首次发布与替换时的新来源、由持久条目驱动的重新发布行为，以及畸形持久目录不打断步骤观察。
 - 无密钥的组装 Web seeded-history 场景在 Chromium 中展开一条真实的 `instructions` 上下文，断言其文件列表、原样包装与未改动的展开项几何。`catalog` 没有组装态覆盖：隔离脚手架不发布任何 skill，因此没有目录能进入浏览器场景。
 
-## Consequences
+## 后果
 
 - 读者不展开就能知道加进来的是什么，展开之后读到的也不再是转义 JSON。
 - 持久 `MessageSource` 现在在溯源之外还承载一个语义分类。这条边界是承重的：只放事实与形状，绝不放呈现。想要更好卡片的生产方应当记录更好的事实。
 - 目录身份不再依赖面向模型的散文，删掉了那条可能把「改了措辞」误判为「改了内容」的文本切分路径。
-- 除两个 hook 桥接外，每个已发布的生产方现在都声明了形态。桥接按设计保持 opaque：其内容是外部程序打印出来的任意文本，无法承诺任何形状。未知 kind 与不可读记录同样落在这里。
+- 除两个钩子桥接外，每个已发布的生产方现在都声明了形态。桥接按设计保持 opaque：其内容是外部程序打印出来的任意文本，无法承诺任何形状。未知 kind 与不可读记录同样落在这里。
 - `ContextFormed` 按 `form` 判别，因此生产方无法在缺少该形态所需事实的情况下声明它——没有 summary 的 `notice`、没有 sections 的 `snapshot`，都会编译失败。
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
index 4255886987..63b0efa3aa 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
 2026-08-05-feedback-gated-session-telemetry.md: 7d923a7e4cf61e8d1119187564b87e4cbb2065b7
-2026-08-05-feedback-gated-session-telemetry.zh.md: 2862162c0c36e5194846c7e1c7bbc24230ce90aa
+2026-08-05-feedback-gated-session-telemetry.zh.md: e2fa6f9561de6e7295cbf860527c7d7915fec0bf
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
index 2862162c0c..e2fa6f9561 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：反馈门控的会话遥测
+# Agent Note: 反馈门控的会话遥测
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 51401adfdc..451f1aa092 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
 2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
-2026-08-05-pwsh-ui-bash-parity.zh.md: 967c5a9e1409028043dc5028fdca640ddfeb1acc
+2026-08-05-pwsh-ui-bash-parity.zh.md: 9ab4bc18f3f9d564e0f63ef326a6b11974322765
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 967c5a9e14..9ab4bc18f3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -6,23 +6,23 @@ Status: implemented
 
 ## Problem
 
-[pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 让 `dsh-tool-pwsh` 在执行、marker 与后台任务上行为可互换，但明确推迟了面向人类的一半：完成的 pwsh 前台调用呈现为通用 `console` 围栏卡片，而 bash 工具的完成调用呈现为带解析退出状态 pill 的 terminal 卡。拥有此缺口的路线图（[Windows 默认改用 pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)）把 "pwsh TUI/GUI 渲染" 列为阶段 2，但 TUI 包已被移除，使 Web 表面成为该缺口唯一影响的 UI。
+[pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 让 `dsh-tool-pwsh` 在执行、marker 与后台任务上行为可互换，但明确推迟了面向人类的一半：完成的 pwsh 前台调用呈现为通用 `console` 围栏卡片，而 bash 工具的完成调用呈现为带解析退出状态 pill 的 terminal 卡。拥有此缺口的路线图（[Windows 默认改用 pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)）把「pwsh TUI/GUI 渲染」列为阶段 2，但 TUI 包已被移除，使 Web 表面成为该缺口唯一影响的 UI。
 
 ## Decision
 
 `dsh-tool-pwsh` 的 `presentResult` 现在逐调用镜像 `dsh-tool-bash`：完成的前台结果是 `terminal` 卡，输出正文为去 marker 的渲染文本，退出状态 pill 为解析出的 `exitCode`/`signal`；后台 ack 与 `isError` 结果保持通用 `console` 围栏卡片；非单一文本块结果保持不变（`undefined`）。
 
-解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` seam 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 seam 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的 "共享而非复制" 形态。
+解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` seam 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 seam 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的「共享而非复制」形态。
 
-Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 terminal 卡桥接（`dsh-client-ui-conversation` 的 `terminal-card-model`）映射任意 `card: 'terminal'` 结果视图，因此 pwsh presenter 变更直接流经 bash 已有的同一渲染路径。折叠的工具行有一处客户端分类条目：`classifyTool('pwsh')` 现在归入 shell 家族行（`bash` variant，自有 `Pwsh` 标题），而非通用的 `others` "Tool call" 行。一条 keyless 浏览器通道（`apps/web/tests/pwsh-terminal.e2e.ts`）播种一个会话，其 pwsh 调用/结果在回放时由真实工具呈现（api-proxy 从已记录的 args/result 内容重新计算视图），并钉住 terminal 卡 golden，包括退出 pill 与运行状态点。
+Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 terminal 卡桥接（`dsh-client-ui-conversation` 的 `terminal-card-model`）映射任意 `card: 'terminal'` 结果视图，因此 pwsh presenter 变更直接流经 bash 已有的同一渲染路径。折叠的工具行有一处客户端分类条目：`classifyTool('pwsh')` 现在归入 shell 家族行（`bash` variant，自有 `Pwsh` 标题），而非通用的 `others`「Tool call」行。一条 keyless 浏览器通道（`apps/web/tests/pwsh-terminal.e2e.ts`）播种一个会话，其 pwsh 调用/结果在回放时由真实工具呈现（api-proxy 从已记录的 args/result 内容重新计算视图），并钉住 terminal 卡 golden，包括退出 pill 与运行状态点。
 
 ## Alternatives considered
 
-**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享契约放在两个工具本就依赖的包上。
+**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享约定放在两个工具本就依赖的包上。
 
 **新建专用呈现包（如 `@deepseek-ai/dsh-shell-present`）。** 否决：为一个纯函数新建包要付出 manifest、module-graph/目录再生成与 README 面的成本；`@deepseek-ai/dsh-bash` 已在两个工具的闭包中，且已拥有该解析重建的 `BashRunResult` 事实。
 
-**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本契约缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的契约。
+**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是「复制的文本约定缺少共享实现就会漂移」；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml
index 90d3d8e1f5..bd7c5a1cd6 100644
--- a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.md
 2026-08-05-web-preview-product-badge.md: c20dedf8caa497d17a577cf46261c6a24c09a1ce
-2026-08-05-web-preview-product-badge.zh.md: c428dabf2a9a2ece2f90b0c3a527835a494c7cb7
+2026-08-05-web-preview-product-badge.zh.md: 415a7cb3eb02030ef5481f4eba9110b56547ce64
diff --git a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md
index c428dabf2a..415a7cb3eb 100644
--- a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：Web 预览版产品徽标
+# Agent Note: Web 预览版产品徽标
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-05-web-preview-product-badge.md) | 中文
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
index 222ed1ebbe..d89233e8eb 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
 2026-08-06-bundled-dsh-badge-skill.md: 512f67ca347ca311a1f80fef932f6af8c91b0fe9
-2026-08-06-bundled-dsh-badge-skill.zh.md: 88fcadf66944cb91419441be3916ae04968be663
+2026-08-06-bundled-dsh-badge-skill.zh.md: cedb03325f3e963c3fa217b72dcfce31eb44bfe7
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
index 88fcadf669..cedb03325f 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 交付的 CLI 组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill（技能），也不会获得任何模型可见内容。
 
-该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级契约覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
+该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级约定覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
index 7550af746a..9b0e536dad 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
 2026-08-06-resolved-theme-color-metadata.md: 2f7a6f0bde5e75aeb6769939cae54d5319aa5bae
-2026-08-06-resolved-theme-color-metadata.zh.md: a6d530f841d5c744fc88831f9cb685d1ab5027b6
+2026-08-06-resolved-theme-color-metadata.zh.md: 30d5aa3c68db090ff33f8dde0e70804d0d699459
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
index a6d530f841..30d5aa3c68 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
@@ -10,13 +10,13 @@ Web 客户端可以独立于操作系统偏好解析主题，因此 manifest（
 
 ## 决策
 
-ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根元素上的 `color-scheme`、深色调色板属性和内联 token 写入并列。在应用解析后快照的调色板与 token 覆盖值之后，呈现器读取 body 计算样式中的 `background-color`，写入该元数据元素，再将该节点插入 document head。后续快照会更新同一节点，资源释放时则移除它。
+ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根元素上的 `color-scheme`、深色调色板属性和内联 token 写入并列。在应用解析后快照的调色板与 token 覆盖值之后，呈现器读取 body 计算样式中的 `background-color`，写入该元数据元素，再将该节点插入 document head。后续快照会更新同一节点，dispose（资源释放）时则移除它。
 
 渲染后的 body 背景仍是颜色真源。PWA manifest 不包含静态 `theme_color` 或 `background_color`，`ThemeDefinition` 也不新增可能与 token 调色板偏离的第二个颜色字段。这样一来，注册主题的基础背景 token 也能通过页面界面使用的同一条应用路径作用于浏览器界面。
 
 ## 验证
 
-呈现器的单元测试契约覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
+呈现器的单元测试约定覆盖浅色和深色模式下的计算颜色、节点复用及 dispose。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml
index eb0a37d991..6db5825af2 100644
--- a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.md
 2026-08-06-session-completed-done-dot.md: bd6911ce137f1272090c86c029710c9f4054ee6d
-2026-08-06-session-completed-done-dot.zh.md: 9ec2199a29d1307c3ebd0238e84d5f90d36fe21c
+2026-08-06-session-completed-done-dot.zh.md: 41da7d126a29a5f9341ca8b87da343fdbff7601c
diff --git a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md
index 9ec2199a29..41da7d126a 100644
--- a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md
@@ -6,20 +6,20 @@ Status: implemented
 
 ## Problem
 
-操作者派发任务后切换到其他会话，原会话完成时没有任何信号。运行指示停止后，该行与普通空闲会话看起来完全一样，操作者只能反复查看列表或很晚才发现工作已完成。等待交互的琥珀点只覆盖需要操作者输入的会话，不覆盖"只是干完了活"的会话。
+操作者派发任务后切换到其他会话，原会话完成时没有任何信号。运行指示停止后，该行与普通空闲会话看起来完全一样，操作者只能反复查看列表或很晚才发现工作已完成。等待交互的琥珀点只覆盖需要操作者输入的会话，不覆盖「只是干完了活」的会话。
 
 ## Decision
 
-`SessionManager` 持有客户端侧的完成提醒集合，与待交互位并列：非当前会话发生 running→idle 边沿时点亮其提醒；`select()`/`selectSubagent()` 消费掉提醒；重新开始一轮运行会熄灭提醒并在再次完成时重新点亮；会话被移除时清理提醒。该位经 `SessionListEntry` → `SessionSummary`（可选字段，缺省 = 无提醒）进入工作区浏览区，其会话行与搜索结果行渲染现有的 `StateDot` `done` 状态——运行中仍显示转圈，无提醒的空闲会话不显示任何点——悬停卡片将该提醒标注为"已完成 / Completed"。
+`SessionManager` 持有客户端侧的完成提醒集合，与待交互位并列：非当前会话发生 running→idle 边沿时点亮其提醒；`select()`/`selectSubagent()` 消费掉提醒；重新开始一轮运行会熄灭提醒并在再次完成时重新点亮；会话被移除时清理提醒。该位经 `SessionListEntry` → `SessionSummary`（可选字段，缺省 = 无提醒）进入工作区浏览区，其会话行与搜索结果行渲染现有的 `StateDot` `done` 状态——运行中仍显示转圈，无提醒的空闲会话不显示任何点——悬停卡片将该提醒标注为「已完成 / Completed」。
 
-提醒仅存在于内存中且按浏览器实例隔离。它跨连接代存活——传输抖动不会使"你还没回来看"失效——但页面刷新后重置。
+提醒仅存在于内存中且按浏览器实例隔离。它跨连接代存活——传输抖动不会使「你还没回来看」失效——但页面刷新后重置。
 
 ## Consequences
 
-侧边栏行状态成为三个互斥信号：绿 = 已完成且未查看，琥珀 = 等待操作者输入，蓝 = 运行中。无 wire、磁盘或配置格式变更：`SessionSummary.completed` 为可选字段，现有消费者与测试 fixture 保持有效，只有工作区浏览区读取它。完成边沿在每次列表变更与拉取时即时检测（仅在建快照时检测会把连续两个状态帧折叠为一次观察，从而漏掉完成事件）。
+侧边栏行状态成为三个互斥信号：绿 = 已完成且未查看，琥珀 = 等待操作者输入，蓝 = 运行中。协议格式（wire format）、磁盘格式或配置格式均无变更：`SessionSummary.completed` 为可选字段，现有消费方与 fixture（测试前置数据） 保持有效，只有工作区浏览区读取它。完成边沿在每次列表变更与拉取时即时检测（仅在建快照时检测会把连续两个状态帧折叠为一次观察，从而漏掉完成事件）。
 
 ## Alternatives considered
 
-- **组件本地 UI 状态。** 已拒绝：侧边栏折叠时会卸载，且多个界面（分组树、单列表、搜索）需要同一状态位；manager 本就持有运行状态迁移与选中状态，manager 持有的集合是所有界面都能投影的唯一事实源。
+- **组件本地 UI 状态。** 已拒绝：侧边栏折叠时会卸载，且多个界面（分组树、扁平列表、搜索）需要同一状态位；manager 本就持有运行状态迁移与选中状态，manager 持有的集合是所有界面都能投影的唯一真源。
 - **仅从状态帧做事件驱动点亮。** 已拒绝：列表拉取本身也可能携带 running→idle 迁移（刷新在途时会话已完成）；提醒需对每次变更与拉取做对账。
-- **持久化提醒。** 已拒绝：提醒的含义是"此浏览器里你还没查看该会话"；刷新会恢复选中状态且用户正看着列表，持久化位只会过期。
+- **持久化提醒。** 已拒绝：提醒的含义是「此浏览器里你还没查看该会话」；刷新会恢复选中状态且用户正看着列表，持久化位只会变得陈旧。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
index d13ede02d2..000c72f6ed 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
 2026-08-06-web-install-manifest.md: d400c6e586f4b735fa8e3dcc4899c97e45ac89c1
-2026-08-06-web-install-manifest.zh.md: a7fee0248261e8d0597bb773d4f390973147337b
+2026-08-06-web-install-manifest.zh.md: d32ccf25c7b0e13a4094af4364a97385032462b7
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
index a7fee02482..d32ccf25c7 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线契约，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
+Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线约定，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
 
 ## 决策
 
@@ -24,7 +24,7 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 曾考虑的替代方案
 
-**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线契约。
+**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线约定。
 
 **声明单一的 `lang`。** 不予采纳，因为没有任何一种语言足以描述双语产品界面；省略该字段可避免声称安装后的体验由某一种区域设置独占。
 
@@ -36,4 +36,4 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 后果
 
-支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物契约。
+支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物约定。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 7ea7b3b14f..5c5c945102 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
 2026-08-06-web-skill-tool-row.md: 04e8ffcd6e506142b569e60458af144233810bbd
-2026-08-06-web-skill-tool-row.zh.md: b96b3879f989f4f1934cdffaec83a283d74aa220
+2026-08-06-web-skill-tool-row.zh.md: ff1f068c87b8466609980a997b31e7ac666bcf47
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index b96b3879f9..ff1f068c87 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -10,20 +10,20 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 ## 决策
 
-`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 契约，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
+`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 约定，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
 
 收起的行使用 14 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
-该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议契约。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议格式约定。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
 ## 考虑过的替代方案
 
 - 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
-- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会增加协议和快照表层，却不会支持其他消费方。
+- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会扩大协议和快照的变更面，却不会支持其他消费方。
 - 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
 
 ## 后果
 
-除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
+除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 约定、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
 
 即使已安装的 skill 目录发生变化，冷回放仍保持确定性；在用户显式展开指令前，transcript 保持紧凑。仅含结果的 history 页有意使用通用后备路径；让这个边缘情况保持通用呈现，可以保留现有 history 协议，并将该功能限定在客户端呈现层。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
index f513e90666..b6c1d59a6f 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
 2026-08-07-default-model-follows-the-picker.md: d20f0ab8b8c8bd19f596e6ef73f0a58d96c24d38
-2026-08-07-default-model-follows-the-picker.zh.md: 0d2821cb63407fe766e6fe3d36de31d9fc6f1c13
+2026-08-07-default-model-follows-the-picker.zh.md: fd27a0ce67a8e7f41d1a6b397039014f0ddb4854
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
index 0d2821cb63..fd27a0ce67 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 ## 决定
 
-`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是镜像的一例：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
+`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是相反的情形：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
 
 `session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
 
-`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置这条缝的存在。
+`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置 seam 的存在。
 
-`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一轮的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
+`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一个轮次的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
 
 存下来的路由不做注册表校验。默认值指向一条模型页已经删除的路由时，它照样作为 `current` 送到 `session.models`，匹配不到任何已公布的分组——而这正是让输入框选择器已有的回退提示重新选择、而不是显示一个部署根本够不着的模型的原因。
 
@@ -26,18 +26,18 @@ Status: implemented
 
 ## 后续：让发不出消息的会话禁止输入
 
-默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后这一轮在适配器内部失败。两处改动关掉这个口子。
+默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后该轮次会在适配器内部进行到一半时失败。两处改动关掉这个口子。
 
 宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
 
-编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder——唯独模型 seat 被 block 刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
+编辑器停止接受消息。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个块；输入栏渲染的仍是它在没有工作区时就会渲染的那个禁用 textarea，只是把阻断方自己的本地化理由作为 placeholder——唯独模型 seat 被块刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
 
-闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计是咨询性的：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
+闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计只作参考：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
 
 ## 考虑过的替代方案
 
 - **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
-- **校验并清空失效的默认值。** 否决：目录成员关系按设计是咨询性的（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
+- **校验并清空陈旧的默认值。** 否决：目录成员关系按设计只作参考（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
 - **用 `settings.update` 合并补丁。** 否决：它清不掉 `reasoningEffort`，于是从推理模型切到普通模型会留下一个等级，让下一个会话在它上面失败。
 - **只在空白会话里持久化。** 否决：最有信息量的切换恰恰是对话到一半发现模型不行时做的那一次，而它永远存不下来。
 - **单独做一个「设为默认」的入口。** 目前否决：同类产品都从切换本身推断的事情，它却要多一个手势。代价是在老会话里的临时切换也会移动默认值。
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index bc2d1575ee..145c1cf619 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
 2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: 7b48dfd708efb197babcfcbeaf4f8a4ca76cde3f
+2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index 7b48dfd708..afb18fea6a 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -26,7 +26,7 @@ dsh run [--profile <name>] [--patch <path>...] <task...>
 
 `run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
 
-运行器面向用户的契约保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 契约。
+运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 3774ba6e69..51b05b277e 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
 2026-08-08-user-explicit-skill-invocation.md: d925938279923282170dc99934f4fa44d8ecf2b4
-2026-08-08-user-explicit-skill-invocation.zh.md: 64e23be0b42519fb9681adefcd0f05074d3aa35e
+2026-08-08-user-explicit-skill-invocation.zh.md: 2d6d7130a1e80e3e9dba2681815668b3510356ba
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index 64e23be0b4..2d6d7130a1 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -12,16 +12,16 @@ Status: implemented
 
 用户显式调用是一次宿主侧的 pre-step 注入，对每一个用户可调用的 skill 和每一种前端一致：
 
-- `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall 会把携带目录的列表交给它来扩展。
+- `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall（瀑布式事件）会把携带目录的列表交给它来扩展。
 - 精确性来自封闭集合匹配，与斜杠命令完全一致：`/goal` 对照命令注册表解析，`/name` 对照工作区的用户可调用 skill 目录解析；未命中即保持为普通行文，因此绝不猜测。只扫描 `source.kind === 'user'` 的消息——外部文本无法伪造手势。路径（`/usr/bin`）、分数（`5/8`）与带前缀的 token（`foo/name`）都会破坏该边界。
-- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，提示词将其原样发出；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——裁决在客户端把该行认领走，它尚未成为提示词。
-- 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，与 `skill` 工具结果逐字共享，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
+- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，该文本随提示词原样提交；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——客户端会在该行成为提示词之前完成裁决并将其认领。
+- 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，由注入和 `skill` 工具结果共用，二者内容逐字相同，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
 
 同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）一致表明：用户显式触发都是模型零参与的程序化注入；最终形态最接近 Codex 核心侧的 `$name` mention 扫描——它同样让每一种前端免于自行实现识别。
 
 ## 考虑过的替代方案
 
-- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP 不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
+- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP（Agent Client Protocol）不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
 - **从 RPC 处理器调用 `agent.inject()`**——inject 队列（`next-step`，不唤醒）会在 next-turn 提示词之前被认领，使注入在日志中排到手势之上；而与会唤醒的 `followup` 搭配又会重新引入同样的顺序耦合。pre-step 监听器在步骤组装内部注入，那里的顺序是显式的。
 - **宿主 `/skill <name>` 命令**（命令注册表，plan 模式先例）——两 token 的 UX、没有名称补全、仅限用户的 skill 在菜单里仍不可发现；按 cwd 的 skill 目录也与静态命令注册表格格不入。否决。
 - **客户端展开**（拉取正文、拼进提示词）——授权沦为可被绕过的客户端善意，日志失去调用语义，而且 Codex 已删除其等价机制（custom prompts）转向核心注入。否决。
@@ -30,7 +30,7 @@ Status: implemented
 
 ## 后果
 
-- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同等确定。
+- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同样具有确定性。
 - 每一次用户可调用 skill 的调用都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。在句子中间提到一个已知 skill 名称也会加载它；这就是 Codex 的 mention 语义，属于有意接受。
 - `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
-- 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空臂携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
+- 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空分支携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
diff --git a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
index 93cf9ec401..b75b7f8ac5 100644
--- a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md
 2026-06-11-vendor-cordis-as-source.md: ccc1289c8a0feadc08d80a3b6e8dc674c1b87bc4
-2026-06-11-vendor-cordis-as-source.zh.md: 9abea504d677ab71c62d24e2e4d9dfde4315802c
+2026-06-11-vendor-cordis-as-source.zh.md: 4b30ba7684c75bf5eadc0d7c58990ced5355e8f0
diff --git a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
index 9abea504d6..4b30ba7684 100644
--- a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 将 Cordis 以源码形式收录，而非作为 npm 依赖
+# Agent Note: 将 Cordis 以源码形式收录，而非作为 NPM 依赖
 
 Status: implemented
 
@@ -12,7 +12,7 @@ DeepSeek Harness SDK 构建于 Cordis 框架之上。本仓库启动时，Cordis
 
 将所需的 Cordis 包（core、loader、include、group、timer、hmr、logger-console）与 cordiverse 基础库（cosmokit、schemastery）以源码形式复制到 `vendor/`，扁平化放置，保留其原始 npm 包名以实现透明的 workspace 解析。`pnpm-workspace.yaml` 设置 `linkWorkspacePackages: true`，所以只要上游 semver 范围匹配，无论以源码执行还是以构建产物执行，依赖都会解析到这些固定版本的 workspace。真正的第三方依赖（js-yaml、chokidar、@standard-schema/spec 等）仍从 npm 获取。
 
-`vendor/README.md` 是 manifest（元数据清单）：记录每个包（package）的上游仓库 + commit SHA，以及一份详尽的本地修改日志。pre-commit 守卫（`scripts/check-vendor-manifest.sh`）会拒绝未在同一次提交中更新 manifest 的 vendor 源码变更。
+`vendor/README.md` 是 manifest（元数据清单）：记录每个包的上游仓库和 commit SHA，以及一份详尽的本地修改日志。pre-commit 守卫（`scripts/check-vendor-manifest.sh`）会拒绝未在同一次提交中更新 manifest 的 vendor 源码变更。
 
 ## 曾考虑的替代方案
 
@@ -21,7 +21,7 @@ DeepSeek Harness SDK 构建于 Cordis 框架之上。本仓库启动时，Cordis
 
 ## 后果
 
-- harness 完全持有其框架层：可审计、可打补丁、版本锁定。上游 RC 无法影响我们，框架 bug 可以在仓库内直接修复。
+- harness 完全持有其框架层：可审计、可打补丁、版本锁定。上游 RC 无法导致本项目故障，框架 bug 可以在仓库内直接修复。
 - 构建后的包与源码测试执行的是同一版收录的 Cordis；移除 workspace 链接后，构建后的包会在包名不变的情况下静默改用 npm 副本。
 - 上游同步是手动操作（流程记录在 manifest 中）。修改日志使 diff 范围始终可知。
 - 收录的包保留上游代码风格；lint 与严格性门禁将其排除（它们的 tsconfig 在本地放宽了我们较新的编译器选项）。
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index a126f8c0d0..8d5e491e49 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-17-ts-build-config.md
 2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
-2026-06-17-ts-build-config.zh.md: 41791129647b6a5bfeb966e05ee2c5b9132c45ef
+2026-06-17-ts-build-config.zh.md: f96187291ab89744d83908cfbe09d4f03f56577e
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 4179112964..f96187291a 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -4,14 +4,14 @@ Status: implemented
 
 [English](2026-06-17-ts-build-config.md) | 中文
 
-> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 契约后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
+> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 约定后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
 
 ## 问题
 
 此前的 TypeScript 构建与类型检查配置存在以下问题：
 
 - `build` 使用 `tsc` 将 `packages/<group>/<pkg>` 和 `vendor/*` 下的 `.ts` 转换为 `.d.ts` 文件，然后使用 `tsdown` 将 `.ts` 转换为打包后的 `.js` 文件。这导致两个工具各自执行 TypeScript 转换。
-- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包（package）、vendor 源码、示例、测试和脚本。
+- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包、vendor 源码、示例、测试和脚本。
 
 目标是让构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建应通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
 
@@ -76,14 +76,14 @@ tsx scripts/clean.ts
 
 构建职责更加清晰：
 
-- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成契约顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
-- `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布 runtime bundle。
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成约定的顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
+- `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布用的运行时 bundle。
     - `lib/types/*.d.ts` 是发布用的声明输出；`.d.ts.map` 只作为本地编译产物保留。
     - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
     - `lib/types/*.js` 通常仅作为打包器输入。只有显式运行时 export 指向该输出树时，才会发布这些文件。
     - `lib/index.*` 是发布用的运行时输出，由打包器（当前为 `tsdown`）生成。
 - `pnpm run verify-node-next-types` 扫描构建出的声明文件，检查是否存在缺少文件扩展名的相对说明符，然后以 `moduleResolution: "NodeNext"` 对构建出的 `types`/`exports` 接口进行临时外部 ESM 消费方的类型检查，确保声明说明符的回归在发布前被捕获。
 - `typecheck` 命令使用 `tsconfig.json`。示例、测试和脚本由根 no-emit 项目检查，包和 vendor 模块保持与 `build` 相同的输出行为。包和 vendor 源码始终处于 project-reference 边界之后。
-- 切换分支或更新工作副本后，如果其中删除了包，贡献者可在重新构建前运行 `pnpm run clean`，删除残留的包目录。不含 `package.json` 的包目录如果存在未知文件，必须手动判定其类别，不能直接删除。
+- 切换分支或更新工作副本后，如果其中删除了包，贡献者可在重新构建前运行 `pnpm run clean`，删除陈旧的包目录。不含 `package.json` 的包目录如果存在未知文件，必须手动判定其类别，不能直接删除。
 
 Cordis 的 vendor 副本现在与上游多了一处类型结构差异。在上游同步时，该差异必须被重新应用或明确废弃。
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 9e69041e2e..812256d0ae 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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 .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
-2026-07-02-bilingual-docs-and-pairing-gate.md: 8e9d0ab8653528517346b198c97814d8d8979440
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: e8f18ebb0d1620830116f6d5d9ffef29664a578e
+2026-07-02-bilingual-docs-and-pairing-gate.md: b462efd99c008a1e8254b6754a408e9e94e787d6
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 409177996d7ffc63a36c865cc00002a33fe538f1
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index 8e9d0ab865..b462efd99c 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -39,6 +39,6 @@ Paired sibling files with locale suffixes are the dominant Chinese big-tech conv
 - Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.
 - Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, "who confirmed these consistent, and when" is answerable from git blame on the yaml.
 - When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.
-- Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.
+- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.
 - The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.
 - The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index e8f18ebb0d..409177996d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -39,6 +39,6 @@ Status: implemented
 - 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。
 - 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。
 - 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。
-- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。
+- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。
 - 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。
 - 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
index 2a6cdcc2d0..4ff70e11e9 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
 2026-07-22-tsconfig-solution-root-two-aggregates.md: 6e8d192b5fea1c7045ade6935fd0e2dc8434c502
-2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 60581e3de55227a393e2528ce7d3c8fa1bf9c570
+2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 052f3fb92b7cc8e49eeb2e0b1133bb7bf201f26b
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
index 60581e3de5..052f3fb92b 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
@@ -27,7 +27,7 @@ GUI 拆分引入了第二个聚合 program（`tsconfig.client.json`，见[分层
 
 整个方案立足的原则：**cordis `Context` 的声明合并冲突只存在于同一个 `ts.Program` 内部，从不发生在模块解析中。** solution 文件不构成 program，因此从一个根文件同时引用两个聚合不会让两侧的声明合并相撞；vite-tsconfig-paths 只读取 `paths` 与 `include`、丢弃全部类型信息，因此一个门面可以横跨两侧。唯一会爆炸的做法是把两侧压平进同一个 program，由此推出两条派生纪律：`tsconfig.base.json` 永远不得添加 `include`/`files`（否则会泄漏进每个继承它的包，并收窄门面范围）；每个全仓级 `ts.Program` 消费方（`scripts/ts-project.ts`、doc-typecheck 独立模式）都显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子，绝不使用根 solution。基于 program 的生成器与语义门禁有意只留在宿主侧；客户端侧只有在真实需求出现时才引入基于 program 的门禁。
 
-根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 契约而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
+根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 约定而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md) 负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
 
 solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更近的 tsconfig，tsx（get-tsconfig）通过根文件解析它们的 workspace 导入。`extends` 把 `paths` 映射带回根文件，`files: []` 则让它始终不构成 program。这不影响两者的*类型检查*：examples、scripts 与 website 的文件由宿主聚合纳入。
 
@@ -41,5 +41,5 @@ solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更
 
 - `docs/development.md#typescript-project-layout` 是权威描述；根 `AGENTS.md` 以约定形式收录上述两条纪律。
 - [ts-build-config Agent Note](2026-06-17-ts-build-config.md) 继续拥有 tsc 先行的构建流水线（tsc 负责输出，tsdown 负责打包，`.ts` 说明符配合 `rewriteRelativeImportExtensions`）；其原先「单一根类型检查项目」的形态由本文取代。
-- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成契约与 Client 消费契约的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
-- Host 与 Client 构建阶段必须串行：Host tsdown 生成契约后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
+- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成约定与 Client 消费约定的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
+- Host 与 Client 构建阶段必须串行：Host tsdown 生成约定后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
diff --git a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml
index 8bb5febd69..4551666419 100644
--- a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md
 2026-07-26-incremental-pr-base-retargeting.md: b2e644d99877b4214b5a6edb2775b3962e6b7da2
-2026-07-26-incremental-pr-base-retargeting.zh.md: 5014fef644f9907c4d16a9a2a3767d6f55633688
+2026-07-26-incremental-pr-base-retargeting.zh.md: b97a0abe655e9f4e8ed911ae921bd2a6e5223379
diff --git a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md
index 5014fef644..b97a0abe65 100644
--- a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-选择 merge-forward 时，每次观察到的 base 分支顶端提交都保留为独立的合并检查点。如果处理期间 base 分支继续前移，先完成并验证正在进行的合并，再将其提交；任务授权推送时，还要完成推送。完成这些步骤后，才能拉取较新的 base，并通过单独的合并提交将其合入。在这条 merge-forward 序列中，不得放弃或重写任何检查点。
+选择 merge-forward 时，每次观察到的 base 分支顶端提交都保留为独立的合并检查点。如果处理期间 base 分支继续前移，先完成并验证正在进行的合并，再将其提交；任务授权推送时，还要完成推送。完成这些步骤后，才能获取较新的 base，并通过单独的合并提交将其合入。在这条 merge-forward 序列中，不得放弃或重写任何检查点。
 
 [原生堆叠与可选 rebase 决策](2026-08-02-native-github-stacks-and-optional-rebases.md)也允许独立或堆叠 PR 使用受 lease 保护的 rebase，评审后同样如此。本文只负责 merge-forward 路径。[堆叠 PR 落地 skill（技能）](../../../skills/dsh-merging-stacked-prs/SKILL.md)根据根 [AGENTS.md](../../../../AGENTS.md) 选择其中一种历史更新方式，[堆叠评审指南](../../../../docs/cookbook/responding-to-pr-review-on-a-stack.md)则负责说明如何在依赖层之间传播修复。
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 2589170fc0..907669edb8 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
 2026-07-30-generated-third-party-notices.md: f2591c8d0c7d4b83ecc96bf237ded667e322d55c
-2026-07-30-generated-third-party-notices.zh.md: 74c95cc4349e9d1288d6635b0ae8617e7b929115
+2026-07-30-generated-third-party-notices.zh.md: eef1e1f46bd9086ad0ccb1cf164330b3bbf601bb
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 74c95cc434..eef1e1f46b 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -8,41 +8,41 @@ Status: implemented
 
 本仓库开源需要披露所依赖的第三方软件及各自的许可证。这份披露必须完整，必须随依赖变化保持为真，还必须给出读者用得上的信息：哪些包最终会进到用户机器上，哪些只用于构建和测试。
 
-手写清单无法长期满足其中任何一条。约一百行从各清单文件推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而没有任何检查会察觉。
+手写清单无法长期满足其中任何一条。约一百行从各 manifest（元数据清单）推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而没有任何检查会察觉。
 
 ## Decision
 
-[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。
+[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区 manifest、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。
 
-**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何清单文件、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
+**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
-有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除**清单文件不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
+有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
 文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
-**分层依据是声明方所在区域，而非清单字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一清单——即根清单、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器 exec 经过的 `tsx`，根本没有任何清单把它声明为运行时依赖，只能由生成器显式标记。
+**分层依据是声明方所在区域，而非manifest 字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一 manifest——即根 manifest、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器通过 `tsx` 执行，根本没有任何 manifest 把它声明为运行时依赖，只能由生成器显式标记。
 
 运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。
 
-清单集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生，其中包括 Landlock 工作区及其公开包，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自根工作区已安装的 pnpm store 和包本地链接场；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
+manifest 集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生，其中包括 Landlock 工作区及其公开包，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自根工作区已安装的 pnpm store 和包本地链接场；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布 manifest 答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列入运行时表格，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
 
-项目所有者另行授权分发每个官方 `@anthropic-ai/claude-agent-sdk` 版本，以及该版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。生成器将其表示为一项精确匹配直接包身份的例外，而非宽松许可证覆盖项：`SEE LICENSE IN README.md` 与 `SEE LICENSE IN LICENSE.md` 仍归类为非宽松，所有无关的非宽松运行时依赖仍以默认拒绝方式失败。存在该 SDK 时，生成器会读取其已安装清单，拒绝不符合官方 SDK 载荷前缀的可选包身份，推导当前 SDK、CLI 与载荷版本，核验已安装宿主载荷的身份、版本和声明许可证字段，并在单独的声明章节中渲染 SDK 声明的完整载荷集合。版本、声明许可证和载荷集合发生变化时无需新的身份授权，但仍须经过常规的依赖、锁文件、兼容性、条款和声明评审。
+项目所有者另行授权分发每个官方 `@anthropic-ai/claude-agent-sdk` 版本，以及该版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。生成器将其表示为一项精确匹配直接包身份的例外，而非宽松许可证覆盖项：`SEE LICENSE IN README.md` 与 `SEE LICENSE IN LICENSE.md` 仍归类为非宽松，所有无关的非宽松运行时依赖仍以默认拒绝方式失败。存在该 SDK 时，生成器会读取其已安装 manifest，拒绝不符合官方 SDK 载荷前缀的可选包身份，推导当前 SDK、CLI 与载荷版本，核验已安装宿主载荷的身份、版本和声明许可证字段，并在单独的声明章节中渲染 SDK 声明的完整载荷集合。版本、声明许可证和载荷集合发生变化时无需新的身份授权，但仍须经过常规的依赖、锁文件、兼容性、条款和声明评审。
 
 ## Testing
 
-断言新鲜度的同一个 spec 也用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
+断言新鲜度的同一个 spec 也用fixture（测试前置数据）manifest钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
 
-Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK 清单，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
+Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK manifest，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
 
 ## Alternatives considered
 
 **保留手写文件，发版时人工过一遍。** 用肉眼审阅上百行推导数据，恰恰是生成器能做对的活；而且在两次发版之间，文件自称「列出全部直接依赖」这句话无人验证。
 
-**用专门的 `doc-sync` 门禁校验。** 仓库里其他生成产物都是这么把关的，本次改动最初也是这个形态。但它要在本已冗长的矩阵里再占一个门禁进程和一个调度位；更糟的是，它唯一的失败方式，就是在别人推完一个无关的依赖升级几分钟后，通知对方回去重跑一次生成器。改为提交时重新生成消除了这次打断，而把断言放进测试 lane 本就会跑的 spec 里，则以零额外 CI 成本保住了这项保证。
+**用专门的 `doc-sync`（文档同步门禁）校验。** 仓库里其他生成产物都是这么把关的，本次改动最初也是这个形态。但它要在本已冗长的矩阵里再占一个门禁进程和一个调度位；更糟的是，它唯一的失败方式，就是在别人推完一个无关的依赖升级几分钟后，通知对方回去重跑一次生成器。改为提交时重新生成消除了这次打断，而把断言放进测试 lane 本就会跑的 spec 里，则以零额外 CI 成本保住了这项保证。
 
 **列出完整传递闭包。** 闭包有数千个包，锁文件里已带精确版本，铺开只会淹没读者真正要评估的直接依赖。文件转而指向锁文件与 `pnpm licenses list`。
 
-**按清单字段分层（`dependencies` 与 `devDependencies`）。** 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。
+**按 manifest 字段分层（`dependencies` 与 `devDependencies`）。** 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。
 
 **只按已交付装配的可达性分层**（`apps/*` 加 `python/sdk-runtime`）。这样得到的运行时层更紧凑，但会把 MCP 客户端与 OpenTelemetry 导出器判为仅开发用途——而运行已安装仓库的用户完全可以挂载它们。这会低估披露，对法务通告来说错在了更危险的一侧。
 
@@ -52,9 +52,9 @@ Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通
 
 ## Consequences
 
-此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及清单文件的提交多付一次生成器运行——约一秒；其余提交不受影响。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。
+此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及 manifest 的提交多付一次生成器运行——约一秒；其余提交不受影响。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。
 
-生成器需要已安装的工作树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。
+生成器需要已安装的依赖树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。
 
 分层规则是编码在一个常量里的政策。若新增了不参与交付的工作区区域——第二层测试基础设施、另一个站点——就要同步扩展 `DEV_ONLY_AREAS`，否则其依赖会被当作运行时依赖披露出去。
 
diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml
index 663b074d59..bc066b13ef 100644
--- a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md
 2026-07-30-independent-ci-consumer-build.md: ea87d8051a30c282bdf57ddc3226072be8cb7f24
-2026-07-30-independent-ci-consumer-build.zh.md: 1b5faf73711bd522ddf0ae04f870e0401a481c0e
+2026-07-30-independent-ci-consumer-build.zh.md: b0aa6c453573e089d0352beaa74a6eab769453ae
diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md
index 1b5faf7371..b0aa6c4535 100644
--- a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 消费方独立构建
+# Agent Note: CI 消费方独立构建
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
index 9d3ac28ed2..6c4645c72f 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.md
 2026-07-31-coverage-exempt-heavy-suites.md: 7235a5193554947ecf71f62d522d09f4e21cb1da
-2026-07-31-coverage-exempt-heavy-suites.zh.md: b739e4494ae8d240b0e35109920a49876ebd222d
+2026-07-31-coverage-exempt-heavy-suites.zh.md: e3d6e335ecb069dadeebb06d760cf70c9b0c1fd4
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
index b739e4494a..e3d6e335ec 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试文件钉死：本地 6-worker 全量剖析中，555 个测试文件聚合 1595 秒，其中 `packages/typert/generator/tests/type-model.spec.ts` 一个文件占 885 秒，前 10 个文件占聚合时长的 84%。这类套件的共同点是每个用例都做全工作区编译器分析或真实子进程 fixture，v8 插桩把这类代码的运行时间放大数倍。
+CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试文件钉死：本地 6-worker 全量剖析中，555 个测试文件聚合 1595 秒，其中 `packages/typert/generator/tests/type-model.spec.ts` 一个文件占 885 秒，前 10 个文件占聚合时长的 84%。这类套件的共同点是每个用例都做全工作区编译器分析或真实子进程 fixture（测试前置数据），v8 插桩把这类代码的运行时间放大数倍。
 
 关键的浪费在于：这些套件缴纳的插桩税对 per-file 100% 阈值**没有任何贡献**——它们进程内执行的被度量代码，要么本来就不在阈值口径内，要么已由其他套件独立满覆盖。继续在插桩下运行它们，纯粹是用 lane 时长换零信息。
 
@@ -17,7 +17,7 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 - **插桩 gate**（`test:coverage`）：设 `DSH_COVERAGE_EXEMPT_HEAVY=1`，`vitest.config.ts` 据此从两个 project 的 exclude 中剔除豁免套件，其余全部文件照旧插桩并承担全部阈值证明。经 gate 自带 env 注入（既有 `Gate.env` 机制），不进 workflow 全局环境，因此并排的无插桩 gate 和本地直跑 `vitest run` 都看不到该变量、行为不变。
 - **无插桩 gate**（`test:coverage-exempt-heavy`）：用配对的 positional filter 恰好运行豁免套件，保证正确性信号不缩水。
 
-`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格契约与 filter/exclude 配对，防止两侧漂移。
+`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格约定与 filter/exclude 配对，防止两侧漂移。
 
 ### 豁免名单与逐项对账
 
@@ -29,18 +29,18 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 | 其中 tools-catalog.spec 额外 import | `typert-registry`、`tool-cordis` 的 src | 两包各自的测试独立满覆盖（focused coverage 实测无阈值错误） |
 | `scripts/install-lefthook.spec.ts`、`scripts/oxlint-contract.spec.ts`、`scripts/change-scope.spec.ts` | 无——被测对象是 `scripts/` 源码（从不在 coverage.include），执行方式是 spawn 子进程 | 无需接 |
 
-### 成员资格契约
+### 成员资格约定
 
-新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。契约文本随名单同文件维护。
+新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。约定文本随名单同文件维护。
 
 ### 门禁自动守卫名单正确性
 
 per-file 100% 阈值本身就是豁免名单的守卫，名单错误无法静默通过：
 
 - 若未来某个豁免套件实际独家覆盖着某个被度量文件，插桩 gate 当场红（该文件跌破 100%）；
-- 反向同理：出现"只有豁免套件才覆盖"的新代码，同样立刻红。
+- 反向同理：出现「只有豁免套件才覆盖」的新代码，同样立刻红。
 
-因此覆盖率结果的不变性不依赖人工维护名单，符合"misconfiguration fails loud"约定。唯一失去的是豁免套件自身的执行不再产出覆盖数据——由上表可知这些数据全部冗余，最终报告在阈值意义上逐文件相同。
+因此覆盖率结果的不变性不依赖人工维护名单，符合「misconfiguration fails loud」约定。唯一失去的是豁免套件自身的执行不再产出覆盖数据——由上表可知这些数据全部冗余，最终报告在阈值意义上逐文件相同。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index 77003539ac..0f350867a7 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
 2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
-2026-07-31-installer-adopts-existing-checkout.zh.md: 7cdcd5549fb2bca2a6cb11f0cf2867687565ae79
+2026-07-31-installer-adopts-existing-checkout.zh.md: a5f1c07e41ecb4e8d5b9a250ebd28d03e85b62be
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index 7cdcd5549f..a5f1c07e41 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -6,39 +6,39 @@ Status: implemented
 
 ## Problem
 
-`scripts/install.sh`会产生两种互不兼容的安装形态。`curl … | sh`安装会构建受管布局——`~/.dsh/source/master`处的 master 克隆、位于`dsh-staging/<时间戳>`分支上的 staging worktree，以及 PATH 启动器据以解析的稳定`current`符号链接。而从检出中运行同一脚本时，则依据此前的[检出内跳过克隆决策](../../archived/process/2026-07-22-installer-in-repo-skip-clone.md)，把`dsh`直接链接到该检出的`bin/dsh`。
+`scripts/install.sh` 会产生两种互不兼容的安装形态。`curl … | sh` 安装会构建受管布局——`~/.dsh/source/master` 处的 master 克隆、位于 `dsh-staging/<时间戳>` 分支上的 staging worktree，以及 PATH 启动器据以解析的稳定 `current` 符号链接。而从检出中运行同一脚本时，则依据此前的[检出内跳过克隆决策](../../archived/process/2026-07-22-installer-in-repo-skip-clone.md)，把 `dsh` 直接链接到该检出的 `bin/dsh`。
 
-这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级契约禁止作为启动器目标的情形。升级技能早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
+这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级约定禁止作为启动器目标的情形。升级 skill（技能）早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
 
 ## Decision
 
 检出内模式仍然绝不克隆、绝不修改工作树，但现在它会无条件地把该检出**接管**进受管布局。不存在退出选项：一套布局服务于所有安装。
 
-容器拥有 staging worktree 和`current`；仓库是被*发现*的，而非被拥有的。`git rev-parse --git-common-dir`会解析出该检出背后的共享 git 目录——对于 linked worktree，那是真正的克隆而非 worktree 自身——其父目录即是充当升级基础的仓库。随后以该检出的`HEAD`为起点，在`$DSH_SOURCE`下创建 staging worktree，并让`current`指向它。因此，磁盘上任意位置的克隆都会收敛到与`curl`安装相同的布局，且两条路径共用同一套 worktree/exclude/lock/link 流程：二者的唯一差别，只在于仓库是由`git clone`发现的，还是由`git rev-parse`发现的。
+容器拥有 staging worktree 和`current`；仓库是被*发现*的，而非被拥有的。`git rev-parse --git-common-dir`会解析出该检出背后的共享 git 目录——对于 linked worktree，那是真正的克隆而非 worktree 自身——其父目录即是充当升级基础的仓库。随后以该检出的 `HEAD` 为起点，在`$DSH_SOURCE`下创建 staging worktree，并让`current`指向它。因此，磁盘上任意位置的克隆都会收敛到与`curl`安装相同的布局，且两条路径共用同一套 worktree/exclude/lock/link 流程：二者的唯一差别，只在于仓库是由`git clone`发现的，还是由`git rev-parse`发现的。
 
 安装器不会记录该仓库位于何处。仓库位于容器之外时，容器就不是自包含的——每个 staging worktree 都持有指向该克隆的绝对 gitdir 指针，删除该克隆就会破坏它们——但这一事实本就由 git 自己掌握：worktree 的`.git`文件写明了该路径，而在该克隆中执行`git worktree list`会列出依赖于它的每一个 worktree。
 
-接管以`HEAD`为分支起点，因此运行的是已提交的内容，未提交的更改仍留在检出中。这一点既不提示也不警告：安装器构建好布局后便不再打扰。把`DSH_SOURCE`设为其他目录，仍是唯一有文档记载的、回到克隆另一棵树的方式。
+接管以`HEAD`为分支起点，因此运行的是已提交的内容，未提交的更改仍留在检出中。这一点既不提示也不警告：安装器构建好布局后便不再打扰。把`DSH_SOURCE`设为其他目录，仍是唯一有文档记载的、重新选择克隆一棵独立代码树的方式。
 
-所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
+所有路径比较都通过 `resolve_dir` 辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断「不存在」的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
 
-在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级契约。
+在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级约定。
 
 ## Alternatives considered
 
-**把`~/.dsh/source/master`做成指向该任意克隆的符号链接。** 已否决。Git 会解析该符号链接并记录*真实*路径：经由它创建的 worktree 会存储`gitdir: …/<克隆>/.git/worktrees/<名称>`，而`git worktree list`报告的是该克隆。因此这个符号链接纯属装饰——没有任何代码读取它——却又暗示容器拥有该仓库。它还会静默失效：移动克隆后，`master`看似仍在却已悬空，而每个 staging worktree 都会以`fatal: not a git repository`失败。最糟的是，它把两个名称别名到同一棵树上，于是"current 绝不能是 master 克隆"这项检查会在字符串比较下通过，实则为假。`~/.dsh/source/master`是位置而非名称，且只有位置具有权威性。
+**把`~/.dsh/source/master`做成指向该任意克隆的符号链接。** 已否决。Git 会解析该符号链接并记录*真实*路径：经由它创建的 worktree 会存储`gitdir: …/<克隆>/.git/worktrees/<名称>`，而`git worktree list`报告的是该克隆。因此这个符号链接纯属装饰——没有任何代码读取它——却又暗示容器拥有该仓库。它还会静默失效：移动克隆后，`master`看似仍在却已悬空，而每个 staging worktree 都会以`fatal: not a git repository`失败。最糟的是，它把两个名称别名到同一棵树上，于是「current 绝不能是 master 克隆」这项检查会在字符串比较下通过，实则为假。`~/.dsh/source/master`是位置而非名称，且只有位置具有权威性。
 
-**把检出自身提升为`current`的目标。** 已否决：升级契约要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
+**把检出自身提升为`current`的目标。** 已否决：升级约定要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
 
 **把就地链接保留在提示或`DSH_ADOPT`开关之后。** 已否决；本次变更的早期修订版本正是如此实现，之后被移除。分叉的形态本身就是缺陷，因此把它保留为一个选项等于保留了问题，并使此后每次改动需要推敲的状态翻倍——提示、开关、工作树不干净的警告，以及第二条链接路径，全都只为维持一种本不该产生的形态而存在。就地链接最初的动机——让脚本能针对本地源码进行测试——在接管方案下依然成立：以检出的`HEAD`为起点创建的 staging worktree 运行的是同一份代码。`DSH_SOURCE`仍是安装另一棵树的退路。
 
-**在工作树不干净时发出警告或提示。** 已否决：以`HEAD`为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该契约。
+**在工作树不干净时发出警告或提示。** 已否决：以 `HEAD` 为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该约定。
 
 **把被接管克隆的 staging worktree 放在该克隆旁边**（`~/src/staging-*`），而非放进`~/.dsh/source`。已否决：`current`和 PATH 启动器都是每用户唯一的，因此把 worktree 散落到各个克隆的父目录中，会重新引入 source 容器本就为之而设、意在杜绝的同级克隆蔓延问题。
 
 ## Consequences
 
-现在一套布局服务于所有安装，因此被接管的克隆无需该技能所述的一次性迁移，即可由`dsh-upgrade`升级，而且安装器不再有任何一条分支会产生无法升级的形态。检出内运行仍然绝不改动工作树。
+现在一套布局服务于所有安装，因此被接管的克隆无需该 skill 所述的一次性迁移，即可由`dsh-upgrade`升级，而且安装器不再有任何一条分支会产生无法升级的形态。检出内运行仍然绝不改动工作树。
 
 代价是：贡献者不能再把 PATH 指向某个检出、并让`dsh`随其切换分支而跟随该工作树；启动器现在解析到的是一个固定在安装时所接管`HEAD`上的 staging worktree。重新运行安装器会再次接管当前的`HEAD`。
 
@@ -48,4 +48,4 @@ Status: implemented
 
 `scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。curl 风格安装默认使用公开的 `deepseek-ai/deepseek-harness-sdk` 源，而以 pnpm/npx 替换安装器仍是另一项工作。
 
-验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
+验证是手工完成的，通过一个一次性 harness以打桩的 `pnpm` 驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式设置 `DSH_SOURCE` 仍会重新选择克隆一棵独立代码树；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
diff --git a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml
index 96754a36f3..0970b95acd 100644
--- a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md
 2026-08-02-native-github-stacks-and-optional-rebases.md: a349ed18a27ab006384310e4318f057dbf8873b1
-2026-08-02-native-github-stacks-and-optional-rebases.zh.md: 0205eb475bfe951f8382d61bf19df988027afb13
+2026-08-02-native-github-stacks-and-optional-rebases.zh.md: 21964e3c59719d63214cabeaa5339de9933c87b5
diff --git a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md
index 0205eb475b..21964e3c59 100644
--- a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md
+++ b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 「落地堆叠」通过 `gh stack merge <stack-number> --yes --merge` 合并整个官方堆叠。部分落地需要明确指定边界 PR，并合并从底部到该 PR 的前缀。工作流绝不回退到逐个执行 `gh pr merge` 和手动调整 base。原生直接合并要么全部成功，要么全部不合并；合并队列可能分组处理所选 PR，因此只有每个所选 PR 都分别达到 `MERGED`，落地才算完成。
 
-merge-forward 和 rebase 都可以作为独立 PR 与官方堆叠 PR 的历史刷新方式，包括评审后。改写远端历史时，必须使用精确 lease 或受 lease 保护的 `gh stack` 推送路径；如果远端已经前移，操作必须中止。禁止直接使用 `--force`。[增量更新 base 的决策](2026-07-26-incremental-pr-base-retargeting.md)仍负责 merge-forward 选项。
+merge-forward 和 rebase 都可以作为独立 PR 与官方堆叠 PR 的历史刷新方式，包括评审后。改写远端历史时，必须使用精确 lease 或受 lease 保护的 `gh stack` 推送路径；如果远端已经发生变化，操作必须中止。禁止直接使用 `--force`。[增量更新 base 的决策](2026-07-26-incremental-pr-base-retargeting.md)仍负责 merge-forward 选项。
 
 相关检查通常在发布前运行。`gh stack sync` 是明确的例外，因为它在一次操作中完成获取、级联 rebase 和推送：随后立即验证每个已改写的层；这些验证通过前，不得合并任何受影响的 PR。每次改写推送后，都要重新审计当前 head、未解决的评审线程、批准状态、可合并性和检查结果，因为先前的 commit OID 和内联锚点可能已经过时。
 
diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
index 1b704da8f1..b8e885d109 100644
--- a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.md
 2026-08-04-forward-only-pr-issue-status.md: dd567707bc7fccd0a631943ab3ffd2838a7f2f76
-2026-08-04-forward-only-pr-issue-status.zh.md: f19cceafbde074d298a7c7f27829c8ab919f00b6
+2026-08-04-forward-only-pr-issue-status.zh.md: f7fee58d6afb812f97569ae4d86c3d6504f35752
diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
index f19cceafbd..f7fee58d6a 100644
--- a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
@@ -10,7 +10,7 @@ Issue Project 状态表示工作所处阶段，同仓库内精确匹配的解决
 
 ## 决策
 
-PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内被精确引用的每个解决型 Issue。草稿 PR，或既没有评审请求也没有已提交评审的非草稿 PR，目标状态为 `In progress`。具备上述任一类评审活动的非草稿 PR，目标状态为 `In review`。
+PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内由解决型关键字精确引用的每个 Issue。草稿 PR，或既没有评审请求也没有已提交评审的非草稿 PR，目标状态为 `In progress`。具备上述任一类评审活动的非草稿 PR，目标状态为 `In review`。
 
 活跃状态依次为 `Inbox`、`Backlog`、`Ready`、`In progress` 和 `In review`。只有目标状态在该顺序中位于当前状态之后时，投射才会写入。投射不会把 Issue 状态向后移动，不会改动 `Done` 或 `No action`，也不会把没有 Project 状态的 Issue 加入 Project。生命周期路径独立于 PR 元数据校验；另行执行的必需 PR 政策检查继续强制落实标签、引用和优先级一致性。
 
@@ -32,7 +32,7 @@ PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内被精确
 
 ## 后果
 
-- PR 事件会自动纠正停留在 `Inbox`、`Backlog` 或 `Ready` 的解决型 Issue。
+- PR 事件会自动纠正由该 PR 解决但仍停留在 `Inbox`、`Backlog` 或 `Ready` 的 Issue。
 - 若 Issue 创建于最后一个相关 PR 事件之后，则必须等待后续 PR 事件或人工更新状态，因为系统不会反向查找或定时扫描。
 - 即使存在历史评审活动，草稿 PR 仍保持 `In progress`；只有非草稿 PR 才会以 `In review` 为目标状态。
 - 终态以及顺序中更靠后的活跃状态不会倒退。
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
index 7f9a5eee29..f742579d36 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
 2026-08-06-coverage-uncovered-locations.md: 27c466e7ae505a2d318f8b21d442c31619610f59
-2026-08-06-coverage-uncovered-locations.zh.md: 93eeb863e51679c60d9e0ccfc742156c098aeca4
+2026-08-06-coverage-uncovered-locations.zh.md: 482b17227c4198ee27411da16b047288b331af9c
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
index 93eeb863e5..482b17227c 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
@@ -4,13 +4,13 @@ Status: implemented
 
 [English](2026-08-06-coverage-uncovered-locations.md) | 中文
 
-## Problem
+## 问题
 
-per-file 100% 覆盖率门禁失败时，vitest 只输出文件级错误行（`ERROR: Coverage for lines (…) does not meet global threshold (100%) for <file>`）——知道哪个文件没达标，不知道差在哪几行。内置 `text` 报表虽有 Uncovered Line #s 列，但它是全仓几百个文件的大表：该列按表宽截断、只有行号没有列号、不区分语句/分支/函数，且达标文件同样占行。结果是 CI 上的覆盖率红报不可直接行动，定位具体缺口只能本地重跑一遍 html 报表。
+per-file 100% 覆盖率门禁失败时，vitest 只输出文件级错误行（`ERROR: Coverage for lines (…) does not meet global threshold (100%) for <file>`）——知道哪个文件没达标，不知道差在哪几行。内置 `text` 报表虽有 Uncovered Line #s 列，但它是全仓几百个文件的大表：该列按表宽截断、只有行号没有列号、不区分语句/分支/函数，且达标文件同样占行。结果是 CI 上的覆盖率红报无法直接据此处理，定位具体缺口只能本地重跑一遍 html 报表。
 
-## Decision
+## 决策
 
-`scripts/coverage-uncovered-locations.cjs` 是一个自定义 istanbul reporter（`ReportBase` 子类）：对每个低于 100% 的文件，按未覆盖语句、未走的分支路径、未调用函数各输出一条自含的单行记录 `<path>:<line>:<col> uncovered <kind> …`——terminal 与 CI 日志中可直接点击跳转，也便于 grep。全部文件达标时零输出。istanbul 报表生成先于 threshold 校验，因此记录恰好落在既有 ERROR 行上方。
+`scripts/coverage-uncovered-locations.cjs` 是一个自定义 istanbul reporter（`ReportBase` 子类）：对每个低于 100% 的文件，为每个未覆盖语句、每条未走的分支路径和每个未调用函数各输出一条自含的单行记录 `<path>:<line>:<col> uncovered <kind> …`——terminal 与 CI 日志中可直接点击跳转，也便于 grep。全部文件达标时零输出。istanbul 报表生成先于 threshold 校验，因此记录恰好落在既有 ERROR 行上方。
 
 接线是单点的：根 `vitest.config.ts` 的 coverage 块是全仓唯一覆盖率配置，CI lane（`run-gates ci-coverage`）、本地 `test:coverage` 与聚焦跑（`--coverage.include`）共用它。该 reporter 以绝对路径（`fileURLToPath`）加入 CI 与本地两个 reporter 数组——istanbul-reports 的 `create()` 对非内置名回退为裸 `require(name)`，相对路径会按 istanbul 自己的包目录解析。
 
@@ -18,24 +18,24 @@ per-file 100% 覆盖率门禁失败时，vitest 只输出文件级错误行（`E
 
 - istanbul 的 0 基列号转为 1 基（编辑器与终端链接的约定）。
 - v8 对整行语句给出 `end.column = Infinity`：跨行时降级为只带行号的 `(to <line>)` 后缀，单行时省略后缀。
-- 隐式分支臂（如缺省 else）可能不带位置，回退到分支自身的 span，保证记录仍可点击；分支记录标注类型与 `path k/n`。
+- 隐式分支臂（如缺省 else）可能不带位置，reporter 会回退到分支自身的 span，保证记录仍可点击；分支记录标注类型与 `path k/n`。
 - 同文件内记录按行、列排序；不设条数上限。
 
 配套两处：根 `package.json` 增补 devDependency `istanbul-lib-report`（pnpm 严格布局下 `scripts/` 摸不到嵌套依赖）；`knip.json` 根 workspace 的 entry/project 通配增加 `scripts/**/*.cjs`，使该文件及其依赖对 hygiene 门禁可见。
 
 CJS 是被迫的形态，也是 ESM-everywhere 纪律的一个有据例外：istanbul 在 tsx/Vite 管线之外用裸 `require()` 装载自定义 reporter，TypeScript 无法参与；`require(esm)` 返回的命名空间对象也过不了它的 `new Cons(cfg)` 构造，CommonJS 是唯一可靠形态。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-- **依赖内置 `text` 报表的 Uncovered Line #s 列。** 正是问题现状：全仓大表、列宽截断、只有行号、不分种类、达标文件同列——CI 日志里不可行动。
-- **加 `json` reporter，另写 wrapper 脚本失败后读 `coverage-final.json` 后处理。** 纯 ESM/TS 可行，但 wrapper 必须同时包住 `package.json` 的 `test:coverage` 与 run-gates 的 gate 两个入口，命令形状随之改变；自定义 reporter 路线只动一处配置，两个入口自动生效。
-- **用 TypeScript/ESM 写 reporter。** istanbul 的装载机制（管线外裸 `require`）决定了不可行，见上；为一个报表文件把装载机制换掉不成比例。
+- **依赖内置 `text` 报表的 Uncovered Line #s 列。** 正是问题现状：全仓大表、列宽截断、只有行号、不分种类、达标文件同列——无法直接根据 CI 日志处理。
+- **加 `json` reporter，另写包装脚本失败后读 `coverage-final.json` 后处理。** 纯 ESM/TS 可行，但包装脚本必须同时包住 `package.json` 的 `test:coverage` 与 run-gates 的 gate 两个入口，命令形状随之改变；自定义 reporter 路线只动一处配置，两个入口自动生效。
+- **用 TypeScript/ESM 写 reporter。** istanbul 的装载机制（管线外裸 `require`）决定了不可行，见上；为一个报表文件把装载机制换掉，代价不成比例。
 
-## Verification
+## 验证
 
-本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合现场只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方（证据链接见 PR #1716 描述）；演示提交在合并前已从分支撤除。
+本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合运行只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方（证据链接见 PR #1716 描述）；演示提交在合并前已从分支撤除。
 
-## Consequences
+## 后果
 
 - 覆盖率红报自足：日志直接给出精确行列号与缺口种类，不再需要本地重跑 html 报表定位。
 - 代价是一个 CJS 文件的纪律例外与一个根 devDependency；全绿运行零输出，不增加日志噪音。
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
index 8ba8380bf1..15045d2590 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
 2026-08-06-doc-site-carries-its-images.md: 4078a9b6251cf67456590ae25602a9f288c88dc1
-2026-08-06-doc-site-carries-its-images.zh.md: a9afb138d45d1ab991963b997e408477cf88110b
+2026-08-06-doc-site-carries-its-images.zh.md: 134bd20e628322dc9c6d95cb261648618fbdf7a7
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
index a9afb138d4..134bd20e62 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -4,17 +4,17 @@ Status: implemented
 
 [English](2026-08-06-doc-site-carries-its-images.md) | 中文
 
-## Problem
+## 问题
 
-`scripts/project-doc-site.ts` 会把发布清单未收录的仓库相对目标一律改写成 GitHub 地址，对图片而言就是 `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`。站点构建不拷贝任何文件：`srcDir` 是用完即弃的 `.generated` 树，VitePress 没有设置 `publicDir`（其默认值 `<srcDir>/public` 恰好位于投影每次运行时删除的那棵树里），而写进去的只有 Markdown。
+`scripts/project-doc-site.ts` 会把发布 manifest（元数据清单）未收录的仓库相对目标一律改写成 GitHub 地址，对图片而言就是 `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`。站点构建不拷贝任何文件：`srcDir` 是用完即弃的 `.generated` 树，VitePress 没有设置 `publicDir`（其默认值 `<srcDir>/public` 恰好位于投影每次运行时删除的那棵树里），而写进去的只有 Markdown。
 
 这只对公开仓库成立。本仓库是私有的，而 `raw.githubusercontent.com` 对未认证请求一律回 404——github.com 上的登录会话也不能认证它，因为 GitHub 自家界面是用另一套单独签名的地址提供私有 blob 的。于是站点上的每一张图片对每一位读者都是坏的，却没有任何门禁能说出来：`verify-md-links` 与投影校验的是目标文件**在仓库里是否存在**，那与站点读者能否取到它是两个问题。
 
-## Decision
+## 决策
 
-`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张清单未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
+`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张manifest 未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
 
-副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；清单撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
+副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；manifest 撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
 
 只有真实路径位于仓库内的普通文件才会被拷贝，其余一律让投影失败并点名页面与目标。链接改写只需要知道目标**存在**，但发布是把它的字节拷上站点，因此一个逃出仓库的引用——经由 `../..` 或指向树外的符号链接——会把构建机上的文件放到已发布页面上。引用自带的 `?query` 或 `#fragment` 会随安置后的 URL 一同保留，与 GitHub 分支一贯的做法一致；文件名做百分号编码，因为目标位于 Markdown 内联目标的位置。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 正本 Markdown 照旧写普通的仓库相对图片路径，因此同一份文件在 GitHub 上和站点上都能正常显示。没有任何文档为了迁就 VitePress 而写站内绝对 URL。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **把 `publicDir` 设到 `.generated` 之外，并使用站内绝对 URL。** 投影这边的活动部件更少，但同一份 Markdown 在仓库中阅读时，每一处图片引用都会是坏的，而正本文档是两种方式都要读的。
 
@@ -32,12 +32,12 @@ Status: implemented
 
 **等仓库转为公开。** 那只是消除症状，不会让站点自给自足，而且每一张图片都会让站点隐式依赖 GitHub 的可用性与限流。
 
-## Consequences
+## 后果
 
-已发布文档中的图片，现在无论谁在阅读、无论仓库是否公开都能显示，站点构建也不再为图片依赖 GitHub 的运行时可达性。生成树会为每个 locale 各增加一份被引用图片的副本——配置模型指南里的四张截图，每个 locale 约 270 KB。
+已发布文档中的图片，现在无论谁在阅读、无论仓库是否公开都能显示，站点构建也不再为图片依赖 GitHub 的运行时可达性。生成树会为每个 locale 各增加一份被引用图片的副本——模型提供方指南里的四张截图，每个 locale 约 270 KB。
 
 **未发布**文档引用的图片不受影响。纯文本投影会相对于公开源主页解析它们；不在站点上的文档没有站点构建可以承载其资源。
 
-## Testing
+## 测试
 
-`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、被安置的引用保留其 fragment、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`publishableImage` 另有直接覆盖：仓库内的普通文件被接受，而目标逃出仓库的符号链接、仓库外的路径与目录一律拒绝。`pnpm docs:check` 会带着配置模型指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
+`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、被安置的引用保留其 fragment、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`publishableImage` 另有直接覆盖：仓库内的普通文件被接受，而目标逃出仓库的符号链接、仓库外的路径与目录一律拒绝。`pnpm docs:check` 会带着模型提供方指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 2a4a389174..e42cc4e74a 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
 2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
-2026-08-06-in-repository-landlock-release.zh.md: 9f2233f6ae95620d7221f83648b5dc9b4cf8c7d2
+2026-08-06-in-repository-landlock-release.zh.md: b890346e861469eac9b7a08c14912be1a4f99ece
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index 9f2233f6ae..b890346e86 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
+`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器约定及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
 发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 ## 后果
 
-同一个 PR 可以同时修改启动器协议、TypeScript 入口代码、原生源码、harness 消费方式和发布路径测试，并从同一份锁文件解析这些内容。发布 tag 现在标识源码、消费方集成、构建指令，以及主仓库测试过的 tarball。第一次成功从本仓库发布后，独立镜像便不再属于发布路径，可以归档。
+同一个 PR 可以同时修改启动器协议、TypeScript 入口代码、原生源码、harness 消费方式和发布路径测试，并从同一份锁文件解析这些内容。发布 tag 现在标识源码、消费方集成、构建指令，以及主仓库测试过的 tarball。独立镜像已不再属于发布路径，可以在第一次成功从本仓库发布后归档。
 
 npm 消费方改为安装 `@deepseek-ai/node-addon-landlock-run`；原先的非 scoped 包名不会被静默重定向。受支持的 Linux 主机会下载 scoped 入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
index dec1b79d6a..4cb53f0740 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
 2026-08-08-api-remotes-generated-contract-build.md: 947465b19a7c399038ae8a3106f7563592365a8d
-2026-08-08-api-remotes-generated-contract-build.zh.md: 7b559cd966c4acc055d41379c15f46fdfc649a00
+2026-08-08-api-remotes-generated-contract-build.zh.md: 2aea51a72509dd486c557c9a322a1e8604b877c3
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
index 7b559cd966..2aea51a725 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时贡献，Client 的 `api-remotes/src/client/index.ts` 才能通过类型检查并打包这些贡献。若根构建先把 Host 与 Client 两张 Project Reference 图一起交给 tsc，Client 会在生成产物存在之前编译；若增加独立 contracts 预处理，又会让 generator 脱离正常 Host 图重复编译，并允许陈旧产物掩盖错误依赖。
+Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时贡献，Client 的 `api-remotes/src/client/index.ts` 才能通过类型检查并打包这些贡献。若根构建先把 Host 与 Client 两张 Project Reference 图一起交给 tsc，Client 会在生成产物存在之前编译；若增加独立契约生成预处理，又会让 generator 脱离正常 Host 图重复编译，并允许陈旧产物掩盖错误依赖。
 
-该顺序依赖不能改变仓库的普通 package 规则。正常 package 只属于一个 TypeScript face：Host package 登记在 `tsconfig.host.json`，Client package 登记在 `tsconfig.client.json`。一个 Client plugin 同时具有 Node loader 入口与 browser 入口，只是打包产物形态，不是拆分 TypeScript project 的理由。
+该顺序依赖不能改变仓库的普通包规则。正常包只属于一个 TypeScript face：Host 包登记在 `tsconfig.host.json`，Client 包登记在 `tsconfig.client.json`。一个 Client 插件同时具有 Node loader 入口与 browser 入口，只是打包产物形态，不是拆分 TypeScript project 的理由。
 
 ## 决策
 
@@ -26,9 +26,9 @@ Vite Web build
 
 每个 tsc 阶段都是唯一的 TypeScript 编译器路径，负责向 `lib/types` 发射 JavaScript、声明和增量状态。tsdown 只读取这些 JavaScript 并生成发布 bundle，不读取源码，也不生成声明。
 
-## 唯一的 package 特例
+## 唯一的包特例
 
-`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
+`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的包。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
 
 ~~~text
 packages/api/remotes/
@@ -45,27 +45,27 @@ packages/api/remotes/
 
 包根 `tsconfig.json` 是只引用两个具体 project 的 solution，不进入任何 aggregate 或直接消费方的依赖图。根 Host aggregate 与 `host/apiproxy` 引用 `api/remotes/tsconfig.host.json`；根 Client aggregate 与 `client/ui-goal` 引用 `api/remotes/tsconfig.client.json`。`ui-goal` 本身仍是普通的单一 Client project。workspace constraints 门禁遍历可达的 Project Reference 图；凡已声明 face 的 project 引用了拆分包的 solution 根或另一侧 leaf，门禁都会拒绝，而只有 `tsconfig.json` 的目标仍可由任一 face 引用。
 
-两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立 package，不能把同一源码同时交给两个 emitting project。
+两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立包，不能把同一源码同时交给两个 emitting project。
 
-这个例外由生成契约的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
+这个例外由生成契约的真实先后关系决定，不是可供普通包选择的模板。新增包仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
 
 ## TypeRT 与 tsdown
 
 Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 契约投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
 
-TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` package 即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口 package 的 Host 模型也不会丢失。
+TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` 包即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口包的 Host 模型也不会丢失。
 
-Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cli` 这组完整 workspace。根配置不扫描 `lib/types/client/index.js`，不维护 package 分类表，也不使用 tsdown filter；包内配置根据 `DSH_BUILD_FACE` 返回本阶段入口。
+Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cli` 这组完整 workspace。根配置不扫描 `lib/types/client/index.js`，不维护包分类表，也不使用 tsdown filter；包内配置根据 `DSH_BUILD_FACE` 返回本阶段入口。
 
-普通 Client plugin 在 Host pass 返回空配置，在 Client pass 同时生成 Node loader 入口与 browser bundle。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 是唯一阶段例外：Host pass 生成其 Host 入口，Client pass 只生成 browser bundle。未指定 `DSH_BUILD_FACE` 的 package-local tsdown 仍同时返回该 package 的正常入口，供本地单包开发使用。
+普通 Client 插件在 Host pass 返回空配置，在 Client pass 同时生成 Node loader 入口与 browser bundle。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 是唯一阶段例外：Host pass 生成其 Host 入口，Client pass 只生成 browser bundle。未指定 `DSH_BUILD_FACE` 的包内 tsdown 仍同时返回该包的正常入口，供本地单包开发使用。
 
 ## 考虑过的替代方案
 
-**保留独立 contracts 预处理。** 这会在正常 Host Project Reference 图之外额外编译 generator，并让残留生成物掩盖 Client 过早进入 Host 图的问题。
+**保留独立契约生成预处理。** 这会在正常 Host Project Reference 图之外额外编译 generator，并让残留生成物掩盖 Client 过早进入 Host 图的问题。
 
 **一次执行根 `tsc -b tsconfig.json` 后再运行 tsdown。** Client tsc 在 Host tsdown 之前发生，无法从干净工作树获得 `/remote` 声明。
 
-**拆分所有包含 `src/client/index.ts` 的 package。** Node 与 browser 双入口是普通 Client plugin 的打包约定，不形成编译顺序依赖；普遍拆分只会增加 references 和增量状态的维护成本。
+**拆分所有包含 `src/client/index.ts` 的包。** Node 与 browser 双入口是普通 Client 插件的打包约定，不形成编译顺序依赖；普遍拆分只会增加 references 和增量状态的维护成本。
 
 **扫描 Client 编译产物或维护两份 workspace 清单。** 产物扫描会让 package 是否参与构建取决于残留文件，手工清单和 package 名过滤则会随目录调整产生漂移。完整 workspace 加包内 face 选择已经提供确定行为。
 
@@ -75,6 +75,6 @@ Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cl
 
 干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成契约，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
 
-[TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通 package 单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
+[TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通包单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
 
-Client 的独立构建不再是干净工作树上的自足入口；仓库命令、CI 和发布流程必须先运行 Host lib 阶段。普通 package 的开发者无需理解或复制该例外，仍按所属运行环境选择一个 aggregate。
+Client 的独立构建不再是干净工作树上的自足入口；仓库命令、CI 和发布流程必须先运行 Host lib 阶段。普通包的开发者无需理解或复制该例外，仍按所属运行环境选择一个 aggregate。
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index 21006b51db..bd7ec32f75 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
 2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
-2026-08-08-browser-gif-evidence-chain.zh.md: 8aafc842e55775bade8885a792ce7b92dfc8df4e
+2026-08-08-browser-gif-evidence-chain.zh.md: 7b21abb23b5cb3a7b5dd8fd2accc561974008ad9
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index 8aafc842e5..7b21abb23b 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求worktree 干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器上下文时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 
@@ -22,16 +22,16 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**只要可见状态看起来等价，就允许使用不同运行的画面。**视觉相似不能证明各画面共享同一状态、具有因果顺序或来自同一次场景执行。重新录制需要再执行一次真实模型场景，但能维持整套分镜所表达的主张。
+**只要可见状态看起来等价，就允许使用不同运行的画面。**视觉相似不能证明各画面共享同一状态、具有因果顺序或来自同一次场景执行。重新录制需要再执行一次真实模型轮次，但能维持整套分镜所表达的主张。
 
 **将聊天 transcript 视为工具恢复的充分证据。**最终答案能证明任务已经完成，却可能隐藏调用了哪个工具、失败是否为结构化失败，以及模型是否从该失败中恢复。轨迹帧或详情帧可以直接承载这些事实。
 
 **使用 fixture 或测试钩子替换无法访问的原生 UI。**这种做法通过改变被观察的产品路径来简化自动化。通过正常配置选用官方生产后端，既能保持受测实现真实，也能明确表述所采用的较窄运行模式。
 
-**相信资产分支推送成功或匿名请求成功。**推送只能证明 git 接受了相应字节，而私有仓库会有意拒绝未经身份验证的原始内容请求。经身份验证的字节校验与 GitHub Markdown 渲染验证，覆盖了评审者实际使用的两道发布边界。
+**相信资产分支推送成功，或依赖匿名请求。**推送只能证明 git 接受了相应字节，而私有仓库会有意拒绝未经身份验证的原始内容请求。经身份验证的字节校验与 GitHub Markdown 渲染验证，覆盖了评审者实际使用的两道发布边界。
 
 ## 后果
 
-GUI 证据现在能证明一次具有因果关系的执行，而不是将若干可信状态拼成集合；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
+GUI 证据现在能证明一次具有因果关系的执行，而不是若干可信状态的拼贴；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
 
-该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
+该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次真实模型轮次；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index a21ac5cfe9..ced8e532bb 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
 2026-07-20-remove-stdio-and-echo-agents.md: 256e626f4ff41016d0227eef7cc3e4e51e15058b
-2026-07-20-remove-stdio-and-echo-agents.zh.md: bb7a2abd8be73ac3ea089121592b3f26162bf619
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 317f3f6f0910c963e22f2a2f7e33ba8666cf512d
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index bb7a2abd8b..317f3f6f09 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个重复的产品 agent（智能体）。面向行的 stdio agent 使用混合的提示符/输出协议，同时重复实现终端交互与非交互执行。Echo 则以无需联网的 mock 模型加一个教学工具重复实现 Headless，把测试 fixture（测试前置数据）变成面向用户的 agent 和默认快速上手路径。
+DeepSeek Harness 在 TUI 和 Headless coding agent（智能体）之外，还提供了两个重复的产品 agent。面向行的 stdio agent 使用混合的提示符/输出协议，同时重复实现终端交互与非交互执行。Echo 则以无需联网的 mock 模型加一个教学工具重复实现 Headless，把测试 fixture（测试前置数据）变成面向用户的 agent 和默认快速上手路径。
 
-两个 agent 的配套实现都不止叶节点配置。stdio 拥有 UI 插件、app 包（package）、SDK 接口、REPL 叶节点、提示符协议和 Loader 测试。Echo 拥有可运行命令、mock 适配器、工具、CI 演示门禁、图谱条目、教学引用和共享测试 fixture。保留其中任何产品路径，都会间接保留这个重复的 agent。
+两个 agent 的配套实现都不止叶节点配置。stdio 拥有 UI 插件、app 包、SDK 接口、REPL 叶节点、提示符协议和 Loader 测试。Echo 拥有可运行命令、mock 适配器、工具、CI 演示门禁、图谱条目、教学引用和共享测试 fixture。保留其中任何产品路径，都会间接保留这个重复的 agent。
 
-标准输入输出仍是 ACP、JSON-RPC、MCP 和子进程的协议边界。确定性模型适配器也仍可用于测试。这些机制不足以成为保留面向行或仅使用 mock 的产品 agent 的理由。
+标准输入输出仍是 ACP（Agent Client Protocol）、JSON-RPC、MCP 和子进程的协议边界。确定性模型适配器也仍可用于测试。这些机制不足以成为保留面向行或仅使用 mock 的产品 agent 的理由。
 
 ## 决策
 
@@ -22,20 +22,20 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个
 - [`dsh run`](../../../../apps/cli/README.md) 负责非交互式执行。其 `headless` profile 是产品组装；`examples/headless-agent` 负责回放快照、通用真实 agent 测试套件和未导出的无密钥 Loader driver。
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。
 
-SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
+SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复恰好一个会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
 
 无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；`dsh` built-bin 测试套件固定已发布的一次性入口和输出；产品 Headless 快照固定持久化；Headless PTY 关闭 e2e 固定信号升级。各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
 
 ## 验证
 
-TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
+TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果约定和工具调用约定。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口、输出和无效参数行为。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）约定。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 
-- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务契约、格式纯净的 stdout、持久完成边界和进程退出状态。
-- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的契约。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
+- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务约定、格式纯净的 stdout、持久完成边界和进程退出状态。
+- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的约定。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
 - **保留 Echo 作为无密钥快速上手路径**：不予采纳，因为首次产品体验应使用真实模型和受支持的 coding agent，而不是带专用工具的脚本化适配器。
 - **只为 CI 演示命令保留 Echo**：不予采纳，因为由测试持有的 Headless fixture 可以覆盖相同的 Loader 和构建产物边界，无需保留 mock 产品叶节点。
 - **移除所有 stdio 或 mock 机制**：不予采纳，因为分帧协议、进程 I/O 和确定性测试适配器是独立基础设施，并不是被移除的 agent。
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
index 2fb2e4cf9b..30b1700c63 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
 2026-07-26-merge-subagent-control-service.md: ae7214f7c8c28f8a4b7d754839acbc938270f125
-2026-07-26-merge-subagent-control-service.zh.md: dc05e03c5d38df0317291aee2ffc1395dab8e362
+2026-07-26-merge-subagent-control-service.zh.md: f1fe90e4d8f289d30a7d1c8623ea95931c029bf3
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
index dc05e03c5d..f1fe90e4d8 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 ## 问题
 
-可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排契约。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
+可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组能力，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
 
 ## 决策
 
-`SubagentService` 是唯一的公开服务。它公开普通的 `start(name, request)`、由 Task 支撑的 `startContinuable(spec)`，以及按意图命名的 `followup(...)`；提供方的 resume 分发仍封装在其继续执行管理器内部。独立的 `@deepseek-ai/dsh-subagent-control` 包（package）和 `ctx.subagentControl` 键均不存在；可选的 `@deepseek-ai/dsh-tool-subagent-control` 包则直接注入 `ctx.subagents`。
+`SubagentService` 是唯一的公开服务。它公开普通的 `start(name, request)`、由 Task 支撑的 `startContinuable(spec)`，以及按意图命名的 `followup(...)`；提供方的 resume 分发仍封装在其继续执行管理器内部。独立的 `@deepseek-ai/dsh-subagent-control` 包和 `ctx.subagentControl` 键均不存在；可选的 `@deepseek-ai/dsh-tool-subagent-control` 包则直接注入 `ctx.subagents`。
 
-合并后的服务及其提供方公开一套 `SubagentError` 分类体系。稳定错误码把提供方查找失败和功能检查失败，与继续执行路由、鉴权、取消、持久化和送达失败区分开来；已移除的服务不保留单独的错误类。
+合并后的服务及其提供方公开一套 `SubagentError` 分类体系。稳定错误码把提供方查找失败和能力检查失败，与继续执行路由、鉴权、取消、持久化和送达失败区分开来；已移除的服务不保留单独的错误类。
 
 继续执行的实现仍是内部管理器，不会扩展提供方注册表的核心状态。`SubagentService` 通过 `ctx.inject(['tasks', 'agents'], ...)` 创建该管理器，因此注入的 Cordis child fiber 拥有自身的 Task 完成监听器和拆卸 effect。加载提供方注册表不要求 Task 或持久化。只有 Task 和 Agent 可用时，该管理器才会存在；每项继续执行操作都在需要持久性时解析会话持久化服务。dispose（资源释放）该 fiber 会先取消并结算活跃的继续执行，再释放其关联。
 
-`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序契约不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层契约，改动反而多于保留现有的显式入口。
+`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序约定不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层约定，改动反而多于保留现有的显式入口。
 
 每个 `@deepseek-ai/dsh-tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`，默认值为 `one-shot`。这项配置表示策略；`provider.resume` 只用于检查所配置的可继续模式是否受提供方支持。因此，可恢复的提供方仍可执行一次性后台工作。`send_message` 工具是独立适配器：加载或省略该工具既不会启用也不会禁用 `startContinuable`。
 
@@ -26,11 +26,11 @@ Status: implemented
 
 **保留独立服务。** 这样能保持最严格的依赖分离，但每条生产环境中的可继续路径都要组合两个服务，而额外的公开键会暴露调用方并不需要的架构差异。内部管理器无需第二个服务，也能保留可选的 Task 和持久化依赖。
 
-**根据 `provider.resume` 推断可继续模式。** 方法是否存在可以准确表示从持久化存储恢复的功能，却不能表示部署策略。这会迫使每个可恢复的提供方都采用可继续后台语义，并使配套插件缺失成为运行时错误。显式的工具配置将选择与功能分离。
+**根据 `provider.resume` 推断可继续模式。** 方法是否存在可以准确表示从持久化存储恢复的能力，却不能表示部署策略。这会迫使每个可恢复的提供方都采用可继续后台语义，并使配套插件缺失成为运行时错误。显式的工具配置将选择与能力分离。
 
 **注册继续执行访问入口，或检查后续操作工具。** 注册表可以告诉委派工具继续执行接口是否存在，但启动具备持久性的工作不需要任何后续操作适配器。这样的注册表会把 UI 组合编码进执行策略，并以另一个名称重新建立插件间依赖关系。
 
-**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项契约。
+**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项约定。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml
index f0587a9b39..c251d969e1 100644
--- a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.md
 2026-07-27-intent-named-subagent-continuation-operations.md: e74d62b7582e92f8e5ce68327a677259c8453d24
-2026-07-27-intent-named-subagent-continuation-operations.zh.md: dae4dd37fa9950f0b8d1ba6ec5c46b99977a7201
+2026-07-27-intent-named-subagent-continuation-operations.zh.md: ae7b370441d8e0ee045f4d0fcf851d28d055b295
diff --git a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md
index dae4dd37fa..ae7b370441 100644
--- a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-`SubagentService` 分离四种执行意图：`start(name, request)` 返回普通的、由持有方负责的 one-shot run；`startContinuable(spec)` 建立持久化 child，并返回其 id 与已接受的初始 `MessageId`；`followup(parent, childId, content, { source, signal })` 发送后续 parent 内容；`reportFrom(child, content, { delivery, signal })` 将选定的 child 内容发送给其直接 parent。`followup` 与 `Agent.followup()` 一致，而 `SubagentRun.steer()` 仍是范围更窄的能力，仅向已确认仍在运行的 run 提供 steering。面向模型的工具保留稳定的 `send_message` 与 `report` 名称，并将路由委托给对应的意图方法。
+`SubagentService` 分离四种执行意图：`start(name, request)` 返回普通的、由持有方负责的 one-shot run；`startContinuable(spec)` 建立持久化 child，并返回其 id 与已接受的初始 `MessageId`；`followup(parent, childId, content, { source, signal })` 发送后续 parent 内容；`reportFrom(child, content, { delivery, signal })` 将选定的 child 内容发送给其直接 parent。`followup` 与 `Agent.followup()` 一致，而 `SubagentRun.steer()` 仍是范围更窄的能力，仅向已确认仍在运行的 run 提供 steering（中途引导）。面向模型的工具保留稳定的 `send_message` 与 `report` 名称，并将路由委托给对应的意图方法。
 
 调用方请求与提供方请求相互分离。`SubagentStartRequest` 包含调用方提供的 one-shot 数据；`ResolvedSubagentStartRequest` 会在调用 `SubagentProvider.start()` 前加入由服务解析的描述符。创建可继续 child 时，管理器将 `ContinuableCreateRequest` 传给可选的 `SubagentProvider.prepareContinuable()`，且只接收分离的创建数据。`SubagentService.resume()` 与提供方恢复分发均不存在：继续执行管理器加载描述符、对 parent 进行鉴权，并负责 Agent 实体化、提示词投递、冷恢复与 teardown。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
index 7b65dc0445..9d3eb4677f 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
 2026-07-28-remove-synthetic-log-only-turns.md: 61c1aa4b1599fe020e0cd96c32daea01d419e95a
-2026-07-28-remove-synthetic-log-only-turns.zh.md: 1661045ca9fb340ebffc9b749263262cb178eae4
+2026-07-28-remove-synthetic-log-only-turns.zh.md: 65281d8342997165b465a744bb08dd2d815e014e
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
index 1661045ca9..65281d8342 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
@@ -16,9 +16,9 @@ Status: implemented
 
 `SessionStore.appendOutOfBand()`、`OutOfBandSessionEventMap` 和 `OutOfBandSessionEventType` 均不再存在。拥有纯日志事件的插件通过 `Session` 追加该事件；当操作承诺持久性时，插件会显式等待 `ctx.sessions.flush(session)`。系统不会仅为获得该检查点而打开轮次。
 
-核心会话不变量继续强制核心所属的执行关系：轮次与步骤编号、steering、助手、工具、待办和请求头事件的封闭，以及同一步骤内的工具调用／结果配对。核心允许可合并扩展事件位于轮次之间，因为只有声明它们的插件知道这些事件受执行作用域约束，还是可以独立存在。插件的不变量配套组件仍负责其自身的事件关系。
+核心会话不变量继续强制核心所属的执行关系：轮次与步骤编号、steering（中途引导）、助手、工具、待办和请求头事件的封闭，以及同一步骤内的工具调用／结果配对。核心允许可合并扩展事件位于轮次之间，因为只有声明它们的插件知道这些事件受执行作用域约束，还是可以独立存在。插件的不变量配套组件仍负责其自身的事件关系。
 
-标题服务会在完成既有的服务状态、修订、取消和实时会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过有界 `session/event` 路径接纳两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在释放排队提示词接纳预留前完成持久化。
+标题服务会在完成既有的服务状态、修订、取消和活跃会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过有界 `session/event` 路径接纳两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在放行排队中的提示词前完成持久化。
 
 会话 fork 可以结束于开放轮次之外的任意稳定事件位置，而不限于 `turn/end`。这样，默认 fork 会保留独立标题和其他插件所属的纯日志记录，同时仍拒绝在活跃执行过程中截断前缀。
 
@@ -36,7 +36,7 @@ Status: implemented
 
 ## 验证
 
-核心不变量测试会接受轮次之间的未知插件事件，同时继续拒绝位于该处的内置执行事件。钩子、plan-mode、Code Mode 分发和审批的不变量配套组件会在没有开放轮次时拒绝其执行作用域事件；压缩配套组件则另外接受轮次之间平衡的 `turn: null` 手动标记对，并要求数字 owner 匹配一个开放轮次。会话标题服务测试会在并发刷新、会话脱离拒绝和最新修订接受场景下，固定一个直接追加的回退事件。JSONL 和 SQLite 往返测试会通过持久化生命周期排空保留追加在 `turn/end` 之后的标题；fork 测试会保留独立纯日志尾部，同时拒绝位于开放轮次内的边界。一个无密钥、经完整组装的 ACP（Agent Client Protocol）快照会将模型生成的标题延迟到 `turn/end` 之后，并固定一个不含合成轮次的独立提供方标题。生成的 API 和类型等价性目录不含任何已移除符号。
+核心不变量测试会接受轮次之间的未知插件事件，同时继续拒绝位于该处的内置执行事件。钩子、plan-mode、Code Mode 分发和审批的不变量配套组件会在没有开放轮次时拒绝其执行作用域事件；压缩配套组件则另外接受轮次之间平衡的 `turn: null` 手动标记对，并要求数字 owner 匹配一个开放轮次。会话标题服务测试会在并发刷新、拒绝已脱离会话和接受最新修订的场景下，固定一个直接追加的回退事件。JSONL 和 SQLite 往返测试会通过持久化生命周期排空保留追加在 `turn/end` 之后的标题；fork 测试会保留独立纯日志尾部，同时拒绝位于开放轮次内的边界。一个无密钥、经完整组装的 ACP（Agent Client Protocol）快照会将模型生成的标题延迟到 `turn/end` 之后，并固定一个不含合成轮次的独立提供方标题。生成的 API 和类型等价性目录不含任何已移除符号。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
index 4396748bc7..7c4e1fac3d 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
 2026-07-29-shared-base-config-overlays.md: b2ca5cc8d3a160dd09550827d5f8148c14048ea4
-2026-07-29-shared-base-config-overlays.zh.md: e14aa87bdd6ed3bd711bb9786220b5baf0566e8e
+2026-07-29-shared-base-config-overlays.zh.md: adec7c793839e84edb14173d71735d264cf2ec28
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
index e14aa87bdd..adec7c7938 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`dsh` 交付了两棵完整的配置树，其中 43 个配置项完全相同。`apps/cli/cordis.yml` 以 74 个平铺配置项组合 web surface，而 TUI 启动的是 `examples/tui-agent/cordis.yml`——其中单独一行 `@deepseek-ai/dsh-tui-demo` 挂载了十二个插件，并把它们的配置重新声明为自己那份二十个键、仅作透传的 `Config`。
+`dsh` 交付了两棵完整的配置树，其中有 43 个共享配置项。`apps/cli/cordis.yml` 以 74 个平铺配置项组合 web surface，而 TUI 启动的是 `examples/tui-agent/cordis.yml`——其中单独一行 `@deepseek-ai/dsh-tui-demo` 挂载了十二个插件，并把它们的配置重新声明为自己那份二十个键、仅作透传的 `Config`。
 
 这两份文件都名不副实。`examples/tui-agent` 并不是示例：`apps/cli/src/tui.ts` 把它硬编码为产品的默认配置；它还拥有 TUI 的 PTY 冒烟测试、八个终端快照场景，以及被 `cordis-agent` 叶节点 import 的 PTY harness。`dsh-tui-demo` 也不是 demo——它就是应用本身，由交付的二进制从 `packages/examples/` 中挂载。
 
@@ -20,11 +20,11 @@ Status: implemented
 
 优先级即列表顺序，逐配置项后写者胜：base，然后是 surface overlay，接着是 `--config` overlay 或个人 `~/.dsh/config.yaml`，最后是启动器自身的 flag 与 profile patch。
 
-`--config <path>` 现在应用一个 overlay 来**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。
+`--config <path>` 现在应用一个 overlay 来**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的提供方与 model。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则恢复时会静默更换 agent（智能体）。
 
 patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，正如启动器持有身份的记录所述。
 
-`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/self-modification/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP overlay。
+`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/self-modification/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP（Agent Client Protocol）overlay。
 
 ## 备选方案
 
@@ -38,16 +38,16 @@ patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆
 
 ## 影响
 
-指名 `@deepseek-ai/dsh-tui-demo`、或 patch `tui-agent` 配置项的 overlay 与 `--config` 树将不再可解析。overlay 现在要 patch 拥有对应键的那一行：模型路由在 `agent-loop`，人设在 `system-prompt`，呈现设置在 `tui`。
+指名 `@deepseek-ai/dsh-tui-demo` 或 patch `tui-agent` 配置项的 overlay 或 `--config` 树将不再可解析。overlay 现在要 patch 拥有对应键的那一行：模型路由在 `agent-loop`，人设在 `system-prompt`，呈现设置在 `tui`。
 
 若某个 patch 的 `id` 不匹配任何配置项，Loader 仍只告警而不报错。这是有意为之：同一份个人 overlay 会跨 surface 共用，而 `insert` 配置项按设计本就不匹配任何目标，因此仅在 `web` 下存在的配置项不能让 TUI 启动失败。
 
-`dsh web` 新增 `--config`，作为一份额外 overlay 传入 `AppCLIEntry`。Web 保留沙箱化 Bash 与文件系统提供方，以及审批、权限预设、目录选择和浏览器权限界面；覆盖层会禁用共享的本地提供方，因为补丁可以禁用条目但不能删除条目。TUI 查询索引使用进程唯一的临时数据库，因为 SQLite 后端要求单写入者所有权。该索引是每个进程重新构建的可丢弃派生数据；`/resume` 直接列出底层语料，不依赖索引复用。`AppCLIEntry` 在为自身 patch 合并恢复配置项默认值时会同时读取 base 与其 surface overlay，因为 flag 覆盖必须保留同一配置项上 overlay 的其他字段。
+`dsh web` 新增 `--config`，作为一份额外 overlay 传入 `AppCLIEntry`。Web 保留沙箱化 Bash 与文件系统提供方，以及审批、权限预设、目录选择和浏览器权限界面；覆盖层会禁用共享的本地提供方，因为补丁可以禁用条目但不能删除条目。TUI 查询索引使用每个进程独有的临时数据库，因为 SQLite 后端要求单写入者所有权。该索引是每个进程重新构建的可丢弃派生数据；`/resume` 直接列出底层语料，不依赖索引复用。`AppCLIEntry` 在为自身 patch 合并恢复配置项默认值时会同时读取 base 与其 surface overlay，因为 flag 覆盖必须保留同一配置项上 overlay 的其他字段。
 
 ## 验证
 
-组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：两个界面都能稳定完成且没有未加载项；Web 会以沙箱化 Bash 与文件系统提供方启动 `httpServer`。Code Mode 继续由 ACP overlay 与程序化 TUI 快照覆盖，而不再维护独立交付的 TUI 应用。
+组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：两个界面都能完全就绪，且没有未加载项；Web 会以沙箱化 Bash 与文件系统提供方启动 `httpServer`。Code Mode 继续由 ACP overlay 与程序化 TUI 快照覆盖，而不再维护独立交付的 TUI 应用。
 
 全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/boot/app-boot/tests/config-reload.spec.ts` 覆盖）。
 
-平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在 resume 交接中被丢弃。
+平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在恢复交接中被丢弃。
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
index 3245b307e5..8547475c03 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-30-private-agent-send.md
 2026-07-30-private-agent-send.md: 43353c309f98eab1bff91b8fbe0c9cfaa2bbc69b
-2026-07-30-private-agent-send.zh.md: 49f7c999ec60c7305bdca570a4d59039c7c1923b
+2026-07-30-private-agent-send.zh.md: a475c39fc378bca609f747795e185d25accf4489
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
index 49f7c999ec..a475c39fc3 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-公开的 `Agent.send()` 方法暴露了实体循环的路由矩阵，但生产调用方只使用语义明确的 `followup()`、`steer()` 和 `inject()` 操作。第四种组合，即 `next-turn` 配合 `wakeup: false`，除测试外没有消费方。将这项潜在能力保留为公开接口，还会迫使其他 `Agent` 实现和测试替身接受实现层的路由策略。
+公开的 `Agent.send()` 方法暴露了具体循环实现的路由矩阵，但生产调用方只使用语义明确的 `followup()`、`steer()` 和 `inject()` 操作。第四种组合，即 `next-turn` 配合 `wakeup: false`，除测试外没有消费方。将这项潜在能力保留为公开接口，还会迫使其他 `Agent` 实现和测试替身接受实现层的路由策略。
 
 ## 决策
 
-`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付契约公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
+`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付约定公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
 
 公开接口无法在不唤醒驱动器的情况下让一个轮次入队。`followup()` 始终请求执行，`steer()` 请求最近的步骤，`inject()` 则提供面向模型的上下文而不请求执行。本决策部分取代[统一交付决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)中关于公开接口的内容，同时保留其内部路由与统一的 `user/message` 表示。
 
@@ -22,6 +22,6 @@ Status: implemented
 
 ## 后果
 
-插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的契约，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
+插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的约定，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
 
 只有出现明确的消费方并定义显式的生命周期语义后，才能恢复已移除的无唤醒排队能力。`cancel({ keepInbox: true })` 仍会保留已通过受支持交付路径进入待处理状态的工作。
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
index f690cc7a95..86f1fc7bb4 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.md
 2026-07-31-capability-neutral-sandbox-policy-context.md: d45c6c652fb7a061c2f92b7e03c41cce39da2a30
-2026-07-31-capability-neutral-sandbox-policy-context.zh.md: 9a1bb7a13d934826dddf89b409b25ba892a31ea3
+2026-07-31-capability-neutral-sandbox-policy-context.zh.md: fb030e8cd77ceb9935dd9d8f9bd9de2ce2c0fdbc
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
index 9a1bb7a13d..fb030e8cd7 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 当前策略上下文最初通过受强制执行家族与可升权家族两个独立注册表来映射运行时组合。后端、工具与示例中的六个调用点会贡献 `filesystem`、`bash` 或 `terminal`；策略服务保留 token 集合，以便独立释放各项注册，对两个注册表的内容求交集并排序，在每次生命周期变化时使提示词组装失效，并且需要测试覆盖所有家族组合。
 
-这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期契约。
+这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期约定。
 
 ## 决策
 
@@ -18,7 +18,7 @@ Status: implemented
 
 哪些操作可用仍以工具 schema 为准。针对具体操作的拒绝以及获批后的更宽松模式重试，仍以工具结果为准。文件系统、一次性 bash 与终端实现继续解析并强制执行相同的逐调用策略；移除的只有面向模型的冗余能力清单。
 
-本决策取代了[当前沙箱策略上下文决策](../feature/2026-07-30-current-sandbox-policy-context.md)中关于家族注册与按组合条件化措辞的部分内容。缓存安全的上下文交付、持久快照具体化、措辞证据，以及引导与强制执行之间的边界，仍以该 Agent Note 为归属文档。
+本决策取代了[当前沙箱策略上下文决策](../feature/2026-07-30-current-sandbox-policy-context.md)中关于家族注册与按组合条件化措辞的部分内容。缓存安全的上下文交付、持久快照物化、措辞证据，以及引导与强制执行之间的边界，仍以该 Agent Note 为归属文档。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml
index 8cfbcd08c3..e23f925416 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.md
 2026-07-31-drop-user-message-edit-stub.md: 5a34be1dd285f4aced9e6cfb2e324b20ec734bed
-2026-07-31-drop-user-message-edit-stub.zh.md: 768cb4618b4a85f61e6348f8c6fb6a93d686e7d3
+2026-07-31-drop-user-message-edit-stub.zh.md: 288f2bda5d41cf0a331f69f134c8cf1e61a801ef
diff --git a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md
index 768cb4618b..288f2bda5d 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md
@@ -10,7 +10,7 @@ user 气泡的 IconActions 行在复制和分支旁边还有一个编辑按钮
 
 ## 决策
 
-`MessageIconActions` 只渲染时钟／复制／分支，其 `edit` prop 随按钮一并删除；`MessageItem` 不再传入该 prop。现在 user 气泡与 assistant chrome 只在时钟位置上不同。包 README 在 Known Limitations 中记录这项缺失的能力，web 的 message-actions 金样固定了不含该控件的动作行。
+`MessageIconActions` 只渲染时钟／复制／分支，其 `edit` prop 随按钮一并删除；`MessageItem` 不再传入该 prop。现在 user 气泡与 assistant chrome 只在时钟位置上不同。包 README 在 Known Limitations 中记录这项缺失的能力，web 的 message-actions 预期输出固定了不含该控件的动作行。
 
 公共 locale 保留通用的 `edit` 词条：它是共享词汇，而非本组件的文案。
 
@@ -20,8 +20,8 @@ user 气泡的 IconActions 行在复制和分支旁边还有一个编辑按钮
 
 **把按钮置灰并加提示。** 一个可见但无效的控件仍在宣告可以编辑，解释成本相同；直接移除才是诚实的状态。
 
-**接到队列编辑器上。** 队列编辑的是尚未发送的消息。已定稿的 user 消息已经进入转录和模型上下文，复用该编辑器会让同一个动作悄悄变成另一件事。
+**接到队列编辑器上。** 队列编辑的是尚未发送的消息。已定稿的 user 消息已经进入 transcript（文本记录）和模型上下文，复用该编辑器会让同一个动作悄悄变成另一件事。
 
 ## 后果
 
-Web 没有任何途径修正已发送的消息；从该消息分支是最接近的现有手势。由于动作行的内容完全由 props 组合而来，能力就绪后重新引入只是一次纯 UI 改动。
+Web 没有任何途径修正已发送的消息；从该消息分支是最接近的现有手势。由于动作行的内容完全由 props 组合而来，client 变更就绪后重新引入只是一次纯 UI 改动。
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 1c0cc5644d..7f9f5d6665 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
 2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856
-2026-07-31-one-route-to-add-a-workspace.zh.md: 0a59d3a505eb921b4ec980abaefedfcad8a3c294
+2026-07-31-one-route-to-add-a-workspace.zh.md: 6f2d41ca51c544e484c711e8488456b04d206528
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 0a59d3a505..6f2d41ca51 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -1,18 +1,18 @@
-# Agent Note: One route to add a Workspace
+# Agent Note: 一条添加 Workspace 的路径
 
 Status: implemented
 
 [English](2026-07-31-one-route-to-add-a-workspace.md) | 中文
 
-## Problem
+## 问题
 
-两处 Workspace 表层——侧边栏区头的 `+` 与会话主视觉区的 chip——都提供了两条获得 Workspace 的路径：**打开本地文件夹…** 拉起组合的目录流程，**新建工作区** 接收一个名称并创建 `<workspaceRoot>/<name>`。两者重叠：浏览占用者自带 **新建文件夹** 能力，因此"选一个目录"本就覆盖了"建一个目录"。两个入口意味着同一结果有两套词汇、一个自带重名规则的名称对话框，以及一个操作者既看不到也选不了的创建位置。
+两处 Workspace 表层——侧边栏区头的 `+` 与会话主视觉区的 chip——都提供了两条获得 Workspace 的路径：**打开本地文件夹…** 拉起组合的目录流程，**新建工作区** 接收一个名称并创建 `<workspaceRoot>/<name>`。两者重叠：浏览占用者自带 **新建文件夹** 能力，因此「选一个目录」本就覆盖了「建一个目录」。两个入口意味着同一结果有两套词汇、一个自带重名规则的名称对话框，以及一个操作者既看不到也选不了的创建位置。
 
 删掉较弱的那个入口后，侧边栏区头只剩一个动作，于是引出了本 Note 一并裁定的展示问题：只有一行的浮层应该长什么样。
 
-## Decision
+## 决策
 
-添加 Workspace 只有一条路径：通过组合的目录流程选一个宿主机目录，新建的或已存在的都可以。入口是 `menu.addWorkspace`（"添加工作区…" / "Add workspace…"）；按名称创建的对话框及其 `create.*`／`menu.createWorkspace`／`workspace.new` 文案全部删除。标签命名的是结果而非机制，因为它现在是通往该结果的唯一一扇门——找"新建"的用户必须能找到它。
+添加 Workspace 只有一条路径：通过组合的目录流程选一个宿主机目录，新建的或已存在的都可以。入口是 `menu.addWorkspace`（「添加工作区…」/「Add workspace…」）；按名称创建的对话框及其 `create.*`／`menu.createWorkspace`／`workspace.new` 文案全部删除。标签命名的是结果而非机制，因为它现在是通往该结果的唯一一扇门——找「新建」的用户必须能找到它。
 
 **菜单的存在是为了在多个目标之间消歧。** 当只剩添加这一个入口时——仅添加的侧边栏表层，或列表为空的主视觉区——锚点手势*就是*该动作：直接拉起流程，不渲染浮层。只有一行的浮层多花一次点击，却没有任何可选项。这条规则是一个谓词（`addIsTheOnlyEntry`）覆盖两处表层，而不是逐表层特判。
 
@@ -21,37 +21,37 @@ Status: implemented
 - **列表为空只有在基线落地后才算最终结果。** `phase` 仍为 `pending` 时，主视觉区保留菜单与加载状态，而不是跳进一个即将到达的 workspace 会使其变得多余的流程。仅添加表层不列任何东西，因此从不等待。
 - **目录流程的洞没有占用者时，就没有任何可添加的手段。** 此时侧边栏区头干脆不渲染按钮，而不是留下一个点了没反应的按钮；主视觉区的菜单则继续作为选择器工作，列出已有内容——而当同样没有内容可列时，它什么也不弹：空浮层会宣称一个并不存在的选择。这是 seam 文档化的无流程默认行为走到它的结论：占用者不在，唯一的创建能力也就不在。主视觉区的锚点 chip 归 ui-conversation 所有，因此本包能压掉浮层，却无法隐藏该 chip。
 
-直接拉起的这条路径同样遵守菜单项声明的 busy 规则：某次选取仍在接纳中（`flowBusy`）时，锚点手势会被按住，正如该菜单项会被禁用，从而使迟到的结果无法抢开第二个流程。
+直接拉起的这条路径同样遵守菜单项声明的 busy 规则：某次选取仍在接纳中（`flowBusy`）时，锚点手势会被拦住，正如该菜单项会被禁用，从而使迟到的结果无法抢开第二个流程。
 
 `WorkspaceCreateFlow` 现更名为 `WorkspacePickFlow`，其 `createOnly` prop 更名为 `addOnly`；注入的 `createWorkspace` 从 `{ name } | { path }` 收窄为 `{ path }`。
 
-## Wire and CLI residue
+## Wire 与 CLI（命令行界面）残留
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一契约。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端 seam 同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中「workspaceRoot 下的 name」这一约定。`apps/cli/README.md` 及其中文对侧文件也仍把 `--workspace-root` 记为「创建具名 Workspace」。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨后端、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、运行时 workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
-## Testing
+## 测试
 
-`connectFreshWorkspace`——所有 web e2e 场景启动时都会走的辅助函数——会预先备好 `<root>/workspace`，再经对话框的路径编辑器接纳它，因此产出的会话 cwd 与按名称创建时完全一致，场景 golden 保持有效。选择预先备好而不是在对话框内新建，是为了让该辅助函数在一个场景可能发生的多次连接之间保持幂等（第二次创建同名文件夹会失败，而创建对话框会在失败时把流程停在原地）。在选择器内新建文件夹——同一条路径的另一半——由 `workspace-management.e2e.ts` 覆盖，它承担针对性覆盖：在对话框自己创建的文件夹上添加两个 workspace、接纳 basename 相同的不同目录并保持彼此独立、在另一个目录上复用已删除的标题、以及浏览对话框的 aria golden。
+`connectFreshWorkspace`——所有 web e2e 场景启动时都会走的辅助函数——会预先备好 `<root>/workspace`，再经对话框的路径编辑器接纳它，因此产出的会话 cwd 与按名称创建时完全一致，场景预期输出保持有效。选择预先备好而不是在对话框内新建，是为了让该辅助函数在一个场景可能发生的多次连接之间保持幂等（第二次创建同名文件夹会失败，而创建对话框会在失败时把流程停在原地）。在选择器内新建文件夹——同一条路径的另一半——由 `workspace-management.e2e.ts` 覆盖，它承担针对性覆盖：在对话框自己创建的文件夹上添加两个 workspace、接纳 basename 相同的不同目录并保持彼此独立、在另一个目录上复用已删除的标题、以及浏览对话框的 aria 预期输出。
 
 `smoke-real.e2e.ts` 是唯一启动未打补丁的出厂配置树的场景，其中 `-auto` 行会按宿主机解析；它现在通过 `--config` overlay 钉死 `-browse`，使开发机的显示环境无法决定选择器是否可被驱动。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**保留 `打开本地文件夹…` 作为标签。** 否决：合并后该入口既能打开也能创建，用机制命名会恰好对那些入口被我们删掉的用户隐藏创建这一半。反方理由——"本地"二字有效区分了浏览器所在机器与 harness 所在机器——在下一步就由对话框自身的标题和面包屑回答了。
+**保留 `打开本地文件夹…` 作为标签。** 否决：合并后该入口既能打开也能创建，用机制命名会恰好对那些入口被我们删掉的用户隐藏创建这一半。反方理由——「本地」二字有效区分了浏览器所在机器与 harness 所在机器——在下一步就由对话框自身的标题和面包屑回答了。
 
 **保留双入口菜单，让 `新建工作区` 也打开同一个流程。** 否决：同一动作两个标签正是我们被要求消除的混淆，而不是它的缩小版。
 
 **为了与主视觉区菜单保持一致而保留只有一行的浮层。** 否决：不提供选择的浮层是一次浪费的点击，读起来像半成品。这里要一致的是*规则*（有菜单 ⇔ 存在选择），不是控件。
 
-**为将来可能新增的入口（克隆仓库、远程目录）保留菜单壳。** 否决，依据"require a current owner and need"：这样的入口目前并不存在，而等它到来时再恢复菜单，比现在就发一个空壳的改动更小。
+**为将来可能新增的入口（克隆仓库、远程目录）保留菜单壳。** 否决，依据「require a current owner and need」：这样的入口目前并不存在，而等它到来时再恢复菜单，比现在就发一个空壳的改动更小。
 
-**在同一改动中删除 wire 的按名称创建分支。** 本 PR 否决：那是 backend/CLI 面，reviewer 不同、测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
+**在同一改动中删除 wire 的按名称创建分支。** 本 PR（Pull Request）不采纳：那是后端/CLI 面，reviewer 不同、测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
 
-**在 e2e scaffold 中经 host 注册 workspace，而不驱动对话框。** 否决：那会让全部 15 个场景与选择器解耦，整条 lane 将无法证明幸存的这条路径能走到可用的 composer。现在每个场景都会走真实对话框来接纳自己的目录；只有"新建文件夹"那一半集中在一个场景里，因为处处重复只会让共享辅助函数失去幂等性，却换不来额外信号。
+**在 e2e scaffold 中经 host 注册 workspace，而不驱动对话框。** 否决：那会让全部 15 个场景与选择器解耦，整条 lane 将无法证明幸存的这条路径能走到可用的 composer。现在每个场景都会走真实对话框来接纳自己的目录；只有「新建文件夹」那一半集中在一个场景里，因为处处重复只会让共享辅助函数失去幂等性，却换不来额外信号。
 
-## Consequences
+## 后果
 
 - 从 UI 已无法在操作者选定目录之外创建 Workspace；服务端控制的 `--workspace-root` 目标曾是约束新 workspace 文件夹落点的唯一手段，现在没有替代品。需要该约束的部署必须有意识地重新引入它。
-- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的契约，本改动使它成为唯一的契约。
+- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的约定，本改动使它成为唯一的约定。
 - 挂载了 `ui-workspace` 但未挂任何 directory-picker 包的组合，已完全无法添加 Workspace；现在它通过不渲染按钮来说明这一点，而不是提供一个按名称创建的兜底。
-- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让它如实，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 契约上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
+- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让该声明与实际相符，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 约定上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
index 91b9e6a0c0..11967309d5 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
 2026-08-03-omit-invariants-from-shipped-config.md: ff9a3b0ab2b4797ca4e96bea9e6b961b2e38501f
-2026-08-03-omit-invariants-from-shipped-config.zh.md: 526ce0756e69b36b6f54b46b23e1814322d6a1fd
+2026-08-03-omit-invariants-from-shipped-config.zh.md: 26835d0ad8cd380c13aea21f3090d284330820d6
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
index 526ce0756e..26835d0ad8 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`@deepseek-ai/dsh-invariants` 与各包（package）拥有的 `./invariant` 伴随插件是可选的开发诊断。交付的 TUI 挂载了该服务和四个有状态伴随插件，而交付的 Web 配置树省略了这些条目，导致两个产品 surface 的诊断成本和失败行为不同。即使始终启用的产品边界仍负责会话验证与不可变历史，关系断言失败也可能终止普通的 TUI 运行。
+`@deepseek-ai/dsh-invariants` 与各包拥有的 `./invariant` 伴随插件是可选的开发诊断。交付的 TUI 挂载了该服务和四个有状态伴随插件，而交付的 Web 配置树省略了这些条目，导致两个产品 surface 的诊断成本和失败行为不同。即使始终启用的产品边界仍负责会话验证与不可变历史，关系断言失败也可能终止普通的 TUI 运行。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml
index 344dd2bf6c..e17f8c3824 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.md
 2026-08-04-drop-windows-powershell-picker-fallback.md: 619afd31d9ec78cdb8565e29fa942b7db8749365
-2026-08-04-drop-windows-powershell-picker-fallback.zh.md: e14904db46a955d4cf40da195a39bf62cbef96ff
+2026-08-04-drop-windows-powershell-picker-fallback.zh.md: 14716f405e98385b7277ce0814adf32190be36b7
diff --git a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md
index e14904db46..14716f405e 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md
@@ -1,38 +1,38 @@
-# Agent Note：删除 Windows PowerShell 选择器回退
+# Agent Note: 删除 Windows PowerShell 选择器回退
 
 Status: implemented
 
 [English](2026-08-04-drop-windows-powershell-picker-fallback.md) | 中文
 
-## Problem
+## 问题
 
-原生目录选择器的 win32 分支在 koffi `IFileOpenDialog` 子进程之下保留了一条两级 PowerShell 回退：先 `pwsh.exe`，再 `powershell.exe`（Windows PowerShell 5.1），两者运行同一个带 `SetProcessDPIAware` 开关的 WinForms 脚本。该链的存在是为了在 koffi 层"不可用"时仍能给出一个可用的选择器，但它可能保护的每一个触发条件都是我们自己打包或部署的失败，而不是操作系统的：
+原生目录选择器的 win32 分支在 koffi `IFileOpenDialog` 子进程之下保留了一条两级 PowerShell 回退：先 `pwsh.exe`，再 `powershell.exe`（Windows PowerShell 5.1），两者运行同一个主动启用 `SetProcessDPIAware` 的 WinForms 脚本。该链的存在是为了在 koffi 层「不可用」时仍能给出一个可用的选择器，但它可能保护的每一个触发条件都是我们自己打包或部署的失败，而不是操作系统的：
 
-- koffi 的原生二进制作为普通 optional 依赖（`@koromix/koffi-win32-x64`，无 install script）分发；能装上该包的宿主就一定有二进制，装不上的宿主会在安装期大声失败——回退代码同样不会加载。
-- "上古 Windows"不可能出现：本仓库支持的 Node 版本运行在远比 Vista 时代 `IFileOpenDialog` ABI 新的 Windows 世代上。
+- koffi 的原生二进制作为普通的可选 NPM 依赖（`@koromix/koffi-win32-x64`，无 install script）分发；能装上该包的宿主就一定有二进制，装不上的宿主会在安装期明确报错——回退代码也根本不会得到加载。
+- 「上古 Windows」不可能出现：本仓库支持的 Node 版本运行在远比 Vista 时代 `IFileOpenDialog` ABI 新的 Windows 世代上。
 - koffi/COM 缺陷只崩对话框子进程（crash isolation）；对我们自己 bug 的正确反应是上报失败，而不是静默降级到旧版对话框。
 
-这条链还付出了真实的复杂度：两个 spawn 层运行同一脚本、把回退触发从 `ENOENT` 拓宽为 pwsh 的任何失败以关闭 PowerShell 6（无 WinForms）回归、携带全部三个原因的三连败 `AggregateError`，以及每层的 abort 重检。seam 早已拥有唯一重要的回退——组合层面的 `browse` 后端，由 `directory-picker-auto` 在启动时选择一次。
+这条链还付出了真实的复杂度：两个 spawn 层运行同一脚本、把回退触发从 `ENOENT` 拓宽为 pwsh 的任何失败以修复 PowerShell 6（无 WinForms）回归问题、携带全部三个原因的三连败 `AggregateError`，以及每层的 abort 重检。seam 早已拥有唯一重要的回退——组合层面的 `browse` 后端，由 `directory-picker-auto` 在启动时选择一次。
 
-## Decision
+## 决策
 
 win32 层恰好就是 koffi `IFileOpenDialog` 子进程；任何失败原样上报，无回退。PowerShell 链——`pwsh` → Windows PowerShell 5.1 级联、DPI 修正的 WinForms 脚本、`AggregateError` 聚合——被删除，`pickNativeDirectory` 的 win32 分支成为单次调用。`dsh-native-command` 仍为 POSIX 层保留依赖。
 
-本包其余部分早已遵循的回退判据现在统一适用：回退层只存在于操作系统/桌面环境提供且可能缺失的工具（Linux 的 `zenity` → `kdialog`，启动探针同样采样它们）；我们自己打包的工具（`koffi`）失败即大声报错。macOS `osascript` 与之前一样保持无回退。
+本包其余部分早已遵循的回退判据现在统一适用：回退层只存在于操作系统/桌面环境提供且可能缺失的工具（Linux 的 `zenity` → `kdialog`，启动探针同样采样它们）；我们自己打包的工具（`koffi`）失败即明确报错。macOS `osascript` 与之前一样保持无回退。
 
-本次变更合并并删除了 pwsh 优先的 DPI 选择器修复 Note：其决策在此被完全反转，其保留的 rationale 对只含 koffi 的层不再指导未来工作。其中真实的部分：PowerShell 7 呈现基于 `IFileDialog` 的现代文件夹选择器，而 5.1 的 `FolderBrowserDialog` 被硬连到旧版 `SHBrowseForFolder` 树；脚本的 `SetProcessDPIAware` 修正了 spawn 的系统 DPI 上限；pwsh→5.1 的跳转存在是因为可解析的 PowerShell 6 没有 WinForms（退出码 1，而非 `ENOENT`）。其被拒绝的替代方案（要求 PowerShell 7、导入 `resolvePwshPath`、在 harness 进程设置 DPI 感知）随链删除而失去意义。
+本次变更合并并删除了 pwsh 优先的 DPI 选择器修复 Agent Note：其决策在此被完全反转，其保留的理由对只含 koffi 的层不再指导未来工作。其中真实的部分：PowerShell 7 呈现基于 `IFileDialog` 的现代文件夹选择器，而 5.1 的 `FolderBrowserDialog` 被硬连到旧版 `SHBrowseForFolder` 树；脚本的 `SetProcessDPIAware` 修正了 spawn 的系统 DPI 上限；pwsh→5.1 的跳转存在是因为可解析的 PowerShell 6 没有 WinForms（退出码 1，而非 `ENOENT`）。其被拒绝的替代方案（要求 PowerShell 7、导入 `resolvePwshPath`、在 harness 进程设置 DPI 感知）随链删除而失去意义。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**保留链但去掉 pwsh 质量层（`koffi` → Windows PowerShell 5.1）。** 拒绝：剩下的层仍在为我们自己打包的依赖辩护，仍要付出脚本、拓宽的触发与聚合的代价，仍会把我们自己的 vtable/COM 缺陷藏到旧版对话框后面。"仅对外部提供的工具回退"的判据不接受任何 Windows 层。
+**保留链但去掉 pwsh 质量层（`koffi` → Windows PowerShell 5.1）。**拒绝：剩下的层仍在防范我们自己打包的依赖发生故障，仍要付出脚本、拓宽的触发与聚合的代价，仍会把我们自己的 vtable/COM 缺陷藏到旧版对话框后面。「仅对外部提供的工具回退」的判据不接受任何 Windows 层。
 
-**原样保留链。** 拒绝：它是选择器面上唯一的二级运行时回退，其触发条件是本就大声失败的部署侧失败，并且它把失败的 pick 降级成一个最具可操作性的条目是 PowerShell 宿主的 `AggregateError`。
+**原样保留链。**拒绝：它是选择器中唯一的二级运行时回退，其触发条件是本就会明确报错的部署侧失败，并且它把一次失败的选择操作降级为 `AggregateError`，其中最具可操作性的条目却指向 PowerShell 宿主。
 
-**原生 pick 失败时在运行时回退到 `browse`。** 拒绝：seam 的流程洞是 `single` kind，`-auto` 组合已在启动时选择一个后端；运行时跨 kind 跳转会双挂两个后端并模糊能力边界。
+**原生 pick 失败时在运行时回退到 `browse`。**拒绝：seam 的流程洞属于 `single` 类型，`-auto` 组合已在启动时选择一个后端；运行时跨类型跳转会同时挂载两个后端并模糊能力边界。
 
-## Consequences
+## 后果
 
 - win32 选择器的失败面是来自单一层的一个错误；调用方看到真实原因（koffi 加载失败、COM 拒绝、对话框崩溃），而不是链式聚合的错误。
 - 本包不再调用 `pwsh`/`powershell.exe`；WinForms 脚本、其 `SetProcessDPIAware` 修正与 `-STA` 标志随之消失。
-- 测试相应缩减：pwsh/5.1 级联与三连败用例被一个"失败原样上报、无回退"用例取代；默认适配器测试改驱动 Linux 层。
+- 测试相应缩减：pwsh/5.1 级联与三连败用例被一个「失败原样上报、无回退」用例取代；默认适配器测试改驱动 Linux 层。
 - 重新引入条件：未来出现在我们打包链之外的 win32 机制（我们不随包分发的系统提供的对话框宿主）才值得在同一判据下保留一层回退。
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
index e71be9bcf0..b688f011de 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
 2026-08-04-remove-tui-package.md: 1057243c70f6f2775a5d0c5f5eddcb72cbad699e
-2026-08-04-remove-tui-package.zh.md: 0e03d6913aafaa3ce01c0f5732935d2c304c8e0e
+2026-08-04-remove-tui-package.zh.md: 17a75921f3e8f227772133243bc0ea5b8ba927a7
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
index 0e03d6913a..17a75921f3 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 移除 TUI 包（package）
+# Agent Note: 移除 TUI 包
 
 Status: implemented
 
@@ -12,17 +12,17 @@ Status: implemented
 
 ## 决策
 
-删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent-loop 能力保持不变。
+删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent loop（智能体循环）能力保持不变。
 
 SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现 seam。
 
 本决策取代[显式配置 `dsh` 入口决策](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
 
-本记录汇总了删除后无法继续保持当前状态的仅限包记录。终端 UI 曾在长对话期间保持会话身份可见、移除重复模型标签、为消息附加耗时与阶段状态、在提示词旁显示 workspace 与分支上下文，并保守地解析完整 XML 包装层，以生成人类可读的回退输出。这些选择改善了一个终端前端，但没有部署时不足以证明应保留它。未来的 XML 回退仍必须使用真实解析器而非正则表达式。
+本记录汇总了因移除该包而无法继续保持现行有效、现已删除的仅涉及该包的记录。终端 UI 曾在长对话期间保持会话身份可见、移除重复模型标签、为消息附加耗时与阶段状态、在提示词旁显示 workspace 与分支上下文，并保守地解析完整 XML 包装层，以生成人类可读的回退输出。这些选择改善了一个终端前端，但在没有部署的情况下，并不足以证明应保留它。未来的 XML 回退仍必须使用真正的解析器而非正则表达式。
 
 ## 验证
 
-仓库搜索结果与生成目录中不再包含 TUI 包、依赖补丁、SDK 接口选项、服务键或包链接。聚焦的 SDK 测试覆盖 ACP 与嵌入式创建、配置、模板和快照。常规源码构建、类型检查、lint、hygiene、文档门禁以及其余组装快照测试套件均可在没有已删除 workspace 的情况下运行。
+仓库搜索结果与生成的服务目录中不再包含 TUI 包、依赖补丁、SDK 接口选项、服务键或包链接。专项 SDK 测试覆盖 ACP 和嵌入式两种模式的创建、配置、模板与快照。常规源码构建、类型检查、lint、hygiene、文档门禁以及其余组装快照测试套件均可在没有已删除 workspace 的情况下运行。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml
index 36404ebcdd..b34924d341 100644
--- a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md
 2026-08-06-user-bubbles-drop-the-branch-action.md: 817b5e72b7e18b03ddb3a160e6f7a86b04f02764
-2026-08-06-user-bubbles-drop-the-branch-action.zh.md: dab3890818d872d7bbb3ac9bcab014ce9b829a61
+2026-08-06-user-bubbles-drop-the-branch-action.zh.md: a80f723242383cc9a35b9933dcc9c63ebeacd9d8
diff --git a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md
index dab3890818..a80f723242 100644
--- a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：user 与 steering 气泡移除分支操作
+# Agent Note: user 与 steering 气泡移除分支操作
 
 Status: implemented
 
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-每个 user 气泡和已消费的 steering（中途引导）气泡都渲染分支控件，受[已完成轮次尾部决策](../bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)的门禁约束。在这些气泡上，该门禁实际上是永久性的：开轮的 user 消息后面必然跟着本轮自己的节点，已消费的 steering 消息按构造就处在轮次中间，因此只有当轮次结束时该消息之后一个节点都没有——即在第一个模型事件之前就取消——控件才可能启用。读者因此看到一个永远不会启用的控件，tooltip 许诺的是这个按钮到达不了的状态。这个操作入口本身也有误导：在消息 seq 处 fork 会切在所在轮次的 `turn/end`，"在我的消息处分支"实际会把下方的回答一并带走，与在自己气泡上看到分支时"分叉重问"的直觉预期恰好相反。
+每个 user 气泡和已消费的 steering（中途引导）气泡都渲染分支控件，受[已完成轮次尾部决策](../bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)的门禁约束。在这些气泡上，该门禁实际上是永久性的：开轮的 user 消息后面必然跟着本轮自己的节点，已消费的 steering 消息按构造就处在轮次中间，因此只有当轮次结束时该消息之后一个节点都没有——即在第一个模型事件之前就取消——控件才可能启用。读者因此看到一个永远不会启用的控件，tooltip 许诺的是这个按钮到达不了的状态。这个操作入口本身也有误导：在消息 seq 处 fork 会切在所在轮次的 `turn/end`，「在我的消息处分支」实际会把下方的回答一并带走，与在自己气泡上看到分支时「分叉重问」的直觉预期恰好相反。
 
 ## 决策
 
-user 与 steering 气泡不再渲染分支操作。`MessageItem` 移除其 fork props，`PendingSteeringBubble` 移除其 `showBranch` 特例，`messageBranchSeqs` 收窄为 `assistantBranchSeqs`：只有已完成轮次的 transcript 尾部、且该尾部是本轮自己的带 text 内容 assistant 节点才可 fork。分支入口只存在于已定稿的回答之下。
+user 与 steering 气泡不再渲染分支操作。`MessageItem` 移除其 fork props，`PendingSteeringBubble` 移除其 `showBranch` 特例，`messageBranchSeqs` 收窄为 `assistantBranchSeqs`：只有已完成轮次的 transcript（文本记录）尾部、且该尾部是本轮自己的带 text 内容 assistant 节点才可 fork。分支入口只存在于已定稿的回答之下。
 
 含有 steer 的轮次的 fork 点保持不变：fork 是切在 `turn/end` 上的日志前缀，steer 是子会话必须继承的模型可见历史，因此被引导过的轮次的已定稿回答与其他轮次一样可以 fork。assistant 侧的门禁及其可见但不可用的呈现也保持不变——在回答之下，不可用是一个短暂且可到达的状态（当前尾部被后续工具行或错误行占据），这正是 tooltip 的用武之地。
 
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
index cd43c3a27b..9a88d14722 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
 2026-08-08-remove-cli-demo.md: c1153f5e9fcc89585e926f8f088829c849d1f6c1
-2026-08-08-remove-cli-demo.zh.md: 1f9719b176c05009900a268a5bb2d2d7fcc79df3
+2026-08-08-remove-cli-demo.zh.md: 7f11e0c17a15454b99b32d14ea6eda177f4b01f6
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
index 1f9719b176..7f11e0c17a 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出契约、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
+在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出约定、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
 
-回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性契约。
+回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性约定。
 
 ## 决策
 
@@ -19,7 +19,7 @@ Status: implemented
 ## 考虑过的替代方案
 
 - **保留 `dsh-cli-demo` 作为 `dsh run` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
-- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）契约。
+- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）约定。
 - **随包一并删除规范事件快照。** 不予采纳：这些快照固定了模型可见的组装行为，而只检查最终文本的产品验收无法观察这些行为。
 - **保留应用插件，只删除它的 bin。** 不予采纳：隐藏的组装仍会重复显式的 headless profile，并掩盖测试叶节点挂载了哪些服务。
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index 5f9a220dc5..882684d786 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
 2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
-2026-07-24-web-gui-browser-e2e-lane.zh.md: eb20ee378eb5154bafcb7a448202c66dacda9199
+2026-07-24-web-gui-browser-e2e-lane.zh.md: 7c9b97da1810a81a0b7574c50b819892f9686695
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index eb20ee378e..7c9b97da18 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -6,29 +6,29 @@ Status: implemented
 
 ## 问题
 
-Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bundle → HTTP 单次 RPC + 两条 SSE（Server-Sent Events）流 → `toFetchHandler`/apiproxy → host 端的 agent loop（智能体循环）、工具与 JSONL 持久化——却没有任何测试无密钥且确定性地检验这条链。[GUI 测试体系](../process/2026-07-20-gui-testing-system.md)覆盖第 1 层（Node 中的协议同构）、第 2 层（对象层状态机）与第 3 层冒烟测试，但无密钥冒烟驱动的是 `FixtureApiClient`——没有 host、没有 wire、没有 agent loop——而全链路冒烟需要 `DEEPSEEK_API_KEY` 和真实模型，因此不确定、在无密钥 CI 中自行跳过。[docs/testing.md](../../../../docs/testing.md) 的快照哲学——带密钥录制一次、永久无密钥回放、格式变动时刷新——已覆盖 ACP（Agent Client Protocol）、headless `stream-json` 与 TUI 三个文本记录（transcript）表面；web 表面是唯一没有这层保障的组装形态。而缺口恰恰是两起已实证 GUI P0 藏身之处：fixture（测试前置数据）客户端短路掉的 wire 承载链。
+Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bundle → HTTP 单次 RPC + 两条 SSE（Server-Sent Events）流 → `toFetchHandler`/apiproxy → host 端的 agent loop（智能体循环）、工具与 JSONL 持久化——却没有任何测试无密钥且确定性地检验这条链。[GUI 测试体系](../process/2026-07-20-gui-testing-system.md)覆盖第 1 层（Node 中的协议同构）、第 2 层（对象层状态机）与第 3 层冒烟测试，但无密钥冒烟驱动的是 `FixtureApiClient`——没有 host、没有 wire、没有 agent loop——而全链路冒烟需要 `DEEPSEEK_API_KEY` 和真实模型，因此不确定、在无密钥 CI 中自行跳过。[docs/testing.md](../../../../docs/testing.md) 的快照哲学——带密钥录制一次、永久无密钥回放、格式变动时刷新——已覆盖 ACP（Agent Client Protocol）、headless `stream-json` 与 TUI 三个 transcript（文本记录）表面；web 表面是唯一没有这层保障的组装形态。而缺口恰恰是两起已实证 GUI P0 藏身之处：fixture（测试前置数据）客户端短路掉的 wire 承载链。
 
 ## 决策
 
-`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品契约包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
+`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品约定包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
 
 ### Scaffold：`apps/web/tests/scaffold.ts`
 
 一个普通的共享 fixture 模块（[测试政策认可的形态](../../../../docs/testing.md)），不是包：值得门禁把守的逻辑——回放推导、会话解析、日志脱敏、持久化——都在已受门禁的包 `dsh-llm-replay`、`dsh-acp-snapshot`、`dsh-session-persistence-jsonl` 中；剩下的只是启动接线和浏览器胶水，而驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100% 覆盖率。
 
-`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
+`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI（命令行界面）冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
 
-无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
+无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步骤后的压力检查会在每个步骤都告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
 
-`seedSession()` 通过真实持久化 API 播种冷会话——一次性 `Context` 挂载 `SessionStore` + `SessionPersistenceJsonl` 指向 host 的根目录，`create()` + `append()`，一次 `utimes` 回拨保证侧栏顺序确定（`semantic-checkpoint.snapshot.ts` 先例）——绝不裸写文件，因此播种器对桶哈希、文件名编码、压缩一无所知，host 的 zstd 默认值也无需任何启动开关。种子在播种时即校验（可解析、以 `turn/end` 结尾——未闭合的最终轮次会被恢复（resume）的崩溃修复改写）。
+`seedSession()` 通过真实持久化 API 播种冷会话——一次性 `Context` 挂载 `SessionStore` + `SessionPersistenceJsonl` 指向 host 的根目录，`create()` + `append()`，一次 `utimes` 回拨保证侧栏顺序确定（`semantic-checkpoint.snapshot.ts` 先例）——绝不裸写文件，因此播种器对桶哈希、文件名编码、压缩一无所知，host 的 zstd 默认值也无需任何启动开关。种子在播种时即校验（可解析、以 `turn/end` 结尾——未闭合的最终轮次会被恢复的崩溃修复改写）。
 
 ### 确定性规则
 
-回放模式下浏览器断言的屏障栈，按序：（1）host 侧 `await agent.whenIdle()` 加超时，以进程内 `turn/end` 为锚——空闲翻转发生在持久化落盘之后，一次等待同时覆盖轮次完成与持久性；（2）浏览器安定轮询（流式输出节点已卸载、最终文本可见）。录制模式下，日志采收在 `whenIdle()` 之后、scaffold 释放之前进行，此时运行中的会话仍然可用。单独监听进程内 `turn/end` 是错误屏障（它先于 SSE 帧到达浏览器、先于 fsync 触发）；禁止轮询持久化文件来充当轮次完成或持久性屏障（NFS 上慢，且被 `whenIdle` 取代），但工具控制的临时就绪标记可以仅作为该完成屏障之前的交互门控进行轮询；`networkidle` 被彻底禁止（SSE 流保持打开时它永不解析）。导航断言会在页面加载前同时监听 `session.list` 和 `workspace.list` 的初始响应，随后等待播种数据投影到 DOM；仅凭 shell 已挂载不能判定就绪，因为较晚完成的 bootstrap 可能替换受控状态。
+回放模式下浏览器断言的屏障栈，按序：（1）host 侧 `await agent.whenIdle()` 加超时，以进程内 `turn/end` 为锚——空闲翻转发生在持久化落盘之后，一次等待同时覆盖轮次完成与持久性；（2）浏览器安定轮询（流式输出节点已卸载、最终文本可见）。录制模式下，日志采收在 `whenIdle()` 之后、scaffold 释放之前进行，此时运行中的会话仍然可用。单独监听进程内 `turn/end` 是错误屏障（它先于 SSE 帧到达浏览器、先于 fsync 触发）；禁止轮询持久化文件来充当轮次完成或持久性屏障（NFS 上慢，且被 `whenIdle` 取代），但工具控制的临时就绪标记可以仅作为该完成屏障之前的交互门控进行轮询；`networkidle` 被彻底禁止（SSE 流保持打开时永远不会达到该状态）。导航断言会在页面加载前同时监听 `session.list` 和 `workspace.list` 的初始响应，随后等待播种数据投影到 DOM；仅凭 shell 已挂载不能判定就绪，因为较晚完成的 bootstrap 可能替换受控状态。
 
 不做单次瞬态 DOM 断言：从回放产出到 React 提交的每一跳都可能合并分片，采样 `[data-streaming]` 天然就是竞态。流式输出的增量性由持久化的 `assistant/chunk` 事件断言（模型可见 ⟺ 已记录，使日志成为权威证据）。`dsh-llm-replay` 的可选 `paceMs`（默认缺省 = 突发）只是让浏览器观察到真正增量 SSE 的真实感旋钮；正确性绝不依赖它，且节奏等待期间中止会即时取消。
 
-每个场景都会因任何 pageerror 或客户端的连接丢失/间隙修复控制台警告而失败：否则重连机制加历史重同步会把一条死掉的 SSE 通路自愈掉，套件反而认证了坏 wire。Scaffold 的 `close()` 调用 `ReplayHandle.assertConsumed()` 收尾检查（每个已录脚本都被绑定、每个游标都耗尽），把静默的少放与错绑变成清晰诊断。车道不设 vitest 重试；每文件一个 chromium、每场景一个新 context、每场景一个 host；视口固定；交互选择器锚定 role、`data-*` 属性和可见文本，而 frame 与会话区采集则使用既有的 CSS 模块局部类名锚点。常规场景在客户端启动前设置 `dsh.locale=en`，使本地化的 role 定位器和预期输出统一采用明确指定的语言；断言中文文案的场景则不预设该存储项，改为开启 `zh-CN` 浏览器，因为客户端的初始 locale 由 `navigator` 推导（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)），而 `settings-chrome.e2e.ts` 还额外覆盖双向切换与英文浏览器默认态。
+每个场景都会因任何 pageerror 或客户端的连接丢失/间隙修复控制台警告而失败：否则重连机制加历史重同步会把一条死掉的 SSE 通路自愈掉，套件反而认证了坏 wire。Scaffold 的 `close()` 调用 `ReplayHandle.assertConsumed()` 收尾检查（每个已录脚本都被绑定、每个游标都耗尽），把静默的消费不足与错绑变成清晰诊断。车道不设 vitest 重试；每文件一个 chromium、每场景一个新 context、每场景一个 host；视口固定；交互选择器锚定 role、`data-*` 属性和可见文本，而 frame 与会话区采集则使用既有的 CSS 模块局部类名锚点。常规场景在客户端启动前设置 `dsh.locale=en`，使本地化的 role 定位器和预期输出统一采用明确指定的语言；断言中文文案的场景则不预设该存储项，改为开启 `zh-CN` 浏览器，因为客户端的初始 locale 由 `navigator` 推导（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)），而 `settings-chrome.e2e.ts` 还额外覆盖双向切换与英文浏览器默认态。
 
 ### 预期输出
 
@@ -40,19 +40,19 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 `DSH_SNAPSHOT` 选择 replay（默认，无密钥）、record（带密钥）或 refresh（无密钥）。发起提示的 spec 将所有模式共用的驱动步骤与仅供 replay/refresh 使用的断言分开；record 模式驱动真实输入框，采收内存中的会话 header 与事件，脱敏请求头，并 token 化当次运行的会话、cwd 与 RPC 标识。随后一次无密钥 refresh 重新生成 aria 预期输出。每条提示词都会与 fixture 中录制的 `user/message` 核对；每个场景目录都采用封闭清单，其中每个 JSONL 都是脱敏不动点。Web fixture 全部脱敏请求头且不钉任何 header 类别；见「暂缓」。
 
-### 覆盖契约
+### 覆盖约定
 
-该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动契约，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一契约可以验收虚拟化实现。另一份基于同一 fixture 的交互契约钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史契约从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
+该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering（中途引导）；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 waterfall（瀑布式事件）视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 个轮次的 Chat 滚动约定，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一约定可以验收虚拟化实现。另一份基于同一 fixture 的交互约定钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史约定从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每个轮次的事件精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
 
 ### CI 立场
 
-根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动契约](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
+根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux PR（Pull Request）必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动约定](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，常驻自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
 
-高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两轮执行真实 `bash` 调用并断言其持久化结果，最后一轮则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 轮，每第 10 轮执行一次 `bash` 调用并产生结果，每 10 轮强制执行一次 GC，并报告每 10 轮的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。逐轮诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性契约。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
+高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两个轮次执行真实 `bash` 调用并断言其持久化结果，最后一个轮次则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 个轮次，每 10 个轮次执行一次 `bash` 调用并产生结果，每 10 个轮次强制执行一次 GC，并报告每 10 个轮次的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。各轮次诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性约定。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
 
 ## 业界先例
 
-调研了 AI 聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端 seam 后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
+调研了 AI（人工智能）聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端 seam 后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
 
 ## 曾考虑的替代方案
 
@@ -62,15 +62,15 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **扩展 `?fixture` 客户端。** 已否决：分层纪律——`FixtureApiClient` 的存在意义就是脱离服务器测试客户端 shell；client API seam 以下按构造即失测。
 
-**用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它用谎言满足 `llm-deepseek` 的快速失败密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）是诚实的无密钥，并在最早可解析点快速失败。
+**用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它以谎言绕过 `llm-deepseek` 会明确报错的密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）才是真正的无密钥方案，并会在最早可判定点明确失败。
 
-**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器契约。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该契约后，再重新考虑。
+**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器约定。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该约定后，再重新考虑。
 
 **第二份提交的规范化会话日志预期输出。** 已否决：日志表面已由 ACP/headless/TUI 套件经同一循环与持久化钉住；在此只会翻倍刷新成本并重复测试下层。内联在根上下文事件上的世界状态断言保住了验证世界的义务。
 
 **以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
 
-**为可测试性改 wire 协议。** 已否决：契约已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
+**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
 **以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
 
@@ -78,18 +78,18 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **客户端 `data-dsh-busy` 安定信号。** 暂缓：host 侧 `whenIdle` 屏障配合稳定 DOM 轮询，足以覆盖当前场景。第一次安定轮询抖动，或必要状态在 DOM 中不可观察时，再重新考虑。
 
-## Testing
+## 测试
 
-`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`pnpm run test:web:perf` 构建并运行手动性能清单；`test:web:perf:built` 复用现有产物。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。live-interactions AUTH 场景会把不可重试的终态失败钉为 Chat 内联状态，其中携带适合展示的消息与错误码，并验证提供方回显的凭据片段不会出现在 Chat 或 Trajectory 中；该场景同时覆盖输入框恢复与 `turn/end` 错误。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。
+`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`pnpm run test:web:perf` 构建并运行手动性能清单；`test:web:perf:built` 复用现有产物。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。live-interactions AUTH 场景会把不可重试的终态失败钉为 Chat 内联状态，其中携带适合展示的消息与错误码，并验证提供方回显的凭据片段不会出现在 Chat 或 Trajectory 中；该场景同时覆盖输入框恢复与 `turn/end` 错误。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、伴随文件校验、按索引替换与唯一的追加位置。
 
 ## 暂缓
 
-- **Web 头类别钉住**：web fixture 处处 token 化 `{{system}}`/`{{tools}}`，没有场景钉住 web 组合的提示词/工具 schema（`TODO(web-header-pin)`——scaffold 的 `recordFixture` JSDoc 有标记）。沿用 TUI 处处脱敏先例；当 web 组装的请求头与其镜像的 repl 组合进一步分叉时重审。
+- **Web 头类别钉住**：web fixture 处处 token 化 `{{system}}`/`{{tools}}`，没有场景钉住 web 组合的提示词/工具 schema（`TODO(web-header-pin)`——scaffold 的 `recordFixture` JSDoc 有标记）。沿用 TUI 处处脱敏先例；当 web 组装的请求头与其镜像的 repl 组合发生分叉时重审。
 - **恢复后追问场景**：真实 wire 上的历史/实时缝合路径；当该代码变更或回归时作为独立场景补充。
 - **输入框 steering 手势**：输入在运行期间锁定（只能停止或等待），因此 steering 场景从页面走 wire 做 steer；`TODO(web-steer-composer)` 待产品长出真实的输入框手势后，把驱动步骤升级为该手势。
 - **拖拽会话重排**：`workspace.insertSessionBefore` 尚无浏览器场景；它需要在同一个工作区里物化两个会话，并合成 HTML5 拖拽事件。当该表面变更或回归时再补充。无行为的会话 Rename/Fork/Delete 和工作区 Delete 菜单行待获得行为后再补充场景。
-- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互契约不包含这项交接。
+- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互约定不包含这项交接。
 
 ## 后果
 
-Web 表面获得了录制一次/永久回放的层级：真实 chromium → SSE → apiproxy → 循环 → 工具 → 持久化的链路以约 10-30 秒无密钥运行，重复运行结果确定，fixture 由车道自身持有并可重录。接受的成本：每次有意的会话 UI 变更都以一次无密钥 `DSH_SNAPSHOT=refresh` 收尾（预期输出变动是受评审的 diff，锚断言保住语义绿色）；aria 格式归 Playwright 所有——仓库唯一不受自己控制的提交快照格式——因此 playwright 版本升级必须是刻意的升级加刷新提交（依赖在 `apps/web/package.json` 中浮动为 `^1.49.0`；若变动伤人则改为精确锁定）；回放的首次调用顺序绑定把每个场景限制为至多一个发起提示的会话，消费断言是绊线；`compact-basic` 与会话共享回放游标，仅在发布的 128k 目录窗口下保持闲置；必需的消费方任务承担 Chromium 供给与一次浏览器运行的成本，使改动组装后 UI 的 PR（Pull Request）持有相应的预期输出 diff。按需启用的性能车道保留了可重复的诊断工作负载，又不会向 CI 添加受 host 差异影响的时长或内存预期；在仓库拥有经校准的基准测试环境之前，性能回归仍是需要人工解读的信号。
+Web 表面获得了录制一次/永久回放的层级：真实 chromium → SSE → apiproxy → 循环 → 工具 → 持久化的链路以约 10-30 秒无密钥运行，重复运行结果确定，fixture 由车道自身持有并可重录。接受的成本：每次有意的会话 UI 变更都以一次无密钥 `DSH_SNAPSHOT=refresh` 收尾（预期输出变动是受评审的 diff，锚断言保住语义绿色）；aria 格式归 Playwright 所有——仓库唯一不受自己控制的提交快照格式——因此 playwright 版本升级必须是刻意的升级加刷新提交（依赖在 `apps/web/package.json` 中浮动为 `^1.49.0`；若变动伤人则改为精确锁定）；回放的首次调用顺序绑定把每个场景限制为至多一个发起提示的会话，消费断言是绊线；`compact-basic` 与会话共享回放游标，仅在目录中公布的 128k 窗口下保持闲置；必需的消费方任务承担 Chromium 供给与一次浏览器运行的成本，使改动组装后 UI 的 PR 持有相应的预期输出 diff。按需启用的性能车道保留了可重复的诊断工作负载，又不会向 CI 添加受 host 差异影响的时长或内存预期；在仓库拥有经校准的基准测试环境之前，性能回归仍是需要人工解读的信号。
diff --git a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml
index e829874e9d..697b8abe36 100644
--- a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.md
 2026-07-30-vitest-jsdom-webstorage-ownership.md: 3956a7566fa1c79a767636bce9a19f16588126e2
-2026-07-30-vitest-jsdom-webstorage-ownership.zh.md: 9080ee2762b74bf2efdaccd7a5905672001bc0e8
+2026-07-30-vitest-jsdom-webstorage-ownership.zh.md: bd01ffdc68a45802ae403bdf44533d39126b021a
diff --git a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md
index 9080ee2762..bd01ffdc68 100644
--- a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-受支持的 Node 版本范围包含会预留进程级 `globalThis.localStorage` 的版本。未设置 `--localstorage-file` 时，Node 26 将该属性暴露为 `undefined`；Vitest 检测到这个预留键后，不会用 jsdom 的隔离 `Storage` 对象覆盖该属性。因此，组件测试套件尚未验证产品行为便会失败，而主要的 Node 24 覆盖率分支仍能通过，因为该运行时默认不会预留此键。
+受支持的 Node 版本范围包含会预留进程级 `globalThis.localStorage` 的版本。未设置 `--localstorage-file` 时，Node 26 将该属性暴露为 `undefined`；Vitest 检测到这个预留键后，不会用 jsdom 的隔离 `Storage` 对象覆盖该属性。因此，组件测试套件尚未验证产品行为便会失败，而主要的 Node 24 覆盖率通道仍能通过，因为该运行时默认不会预留此键。
 
 ## 决策
 
@@ -23,4 +23,4 @@ Node 兼容性汇总任务会在每条声明支持的兼容版本线上运行专
 
 ## 后果
 
-同一条 `pnpm test` 命令在有无内置 Web Storage 的 Node 版本上均可运行。测试 worker 被有意禁止使用 Node 的进程级 Web Storage；未来若产品需要该 API，必须使用独立且显式的测试配置，而不能削弱 jsdom 隔离。兼容性分支只增加一个专项 Vitest 进程，无需在每个 Node 版本上重复整套单元测试。
+同一条 `pnpm test` 命令在有无内置 Web Storage 的 Node 版本上均可运行。测试 worker 被有意禁止使用 Node 的进程级 Web Storage；未来若产品需要该 API，必须使用独立且显式的测试配置，而不能削弱 jsdom 隔离。兼容性通道只增加一个专项 Vitest 进程，无需在每个 Node 版本上重复整套单元测试。
diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
index 2e8e53fdd7..227135714f 100644
--- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md
 2026-07-30-web-browser-snapshot-ci-gate.md: 14402485034cd85ec5781477ce67481165d47e62
-2026-07-30-web-browser-snapshot-ci-gate.zh.md: f214c524253d2ad8a43e8543dc65ddfcfd7c065c
+2026-07-30-web-browser-snapshot-ci-gate.zh.md: 28a7ef9a7046516a853b3e18a44163c01d43a318
diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
index f214c52425..28a7ef9a70 100644
--- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
@@ -14,22 +14,22 @@ Linux PR 的 `node 24 / snapshots and artifacts` 必须运行完整 Web 浏览
 
 消费方 job 在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，因此 `apps/web/dist` 和包的 `lib/` 目录会保留在其工作区中，供浏览器套件使用。在托管运行器上，CI 按锁文件中的 Playwright 版本安装 Chromium 及其系统依赖。在持久化故障切换 VM 上，镜像负责预装 Linux 系统软件包，CI 只安装 Chromium，避免每次运行都通过 `apt` 改动系统。托管的默认分支 Linux 串行 job 运行该套件，并生成以操作系统和锁文件为键的浏览器缓存；PR 恢复该缓存，使必需路径无需承担压缩和上传开销，并可在锁文件变化时按操作系统前缀回退。自托管热备运行相同的比较，但不执行托管缓存操作。
 
-本地 `pnpm run test:web` 仍先构建再运行浏览器全集；`test:web:built` 是已有构建产物的执行入口。开发者只在确认用户可见输出有意变化后显式运行 `DSH_SNAPSHOT=refresh pnpm run test:web`，评审每一处 expected diff，再以 replay 模式复验不再写文件。
+本地 `pnpm run test:web` 仍先构建再运行完整的浏览器套件；`test:web:built` 是已有构建产物的执行入口。开发者只在确认用户可见输出有意变化后显式运行 `DSH_SNAPSHOT=refresh pnpm run test:web`，评审每一处预期输出 diff，再以 replay 模式复验不再写文件。
 
-对 PR 而言，门禁仅在 Linux 消费方 job 中运行：这些场景面向 POSIX，其他 PR job 不供给 Chromium。托管和自托管的默认分支 Linux 串行聚合作业也包含该比较，而 macOS 和 Windows 串行 job 仍不使用浏览器。PR 的 `all checks passed` 已依赖消费方 job，因此浏览器比较失败会阻止合并，无需新增 branch-protection check 名称。
+对 PR 而言，门禁仅在 Linux 消费方 job 中运行：这些场景面向 POSIX，其他 PR job 不安装 Chromium。托管和自托管的默认分支 Linux 串行聚合作业也包含该比较，而 macOS 和 Windows 串行 job 仍不使用浏览器。PR 的 `all checks passed` 已依赖消费方 job，因此浏览器比较失败会阻止合并，无需新增 branch-protection check 名称。
 
 一次自托管消费方运行中，`web-snapshot` 实测耗时 112.15 秒，完整消费方聚合实测耗时 114.97 秒。gate 调度器会在 `built-package-invariants` 成功后立即启动它，并发运行彼此独立的 gate，因此既不需要专用 job 超时，也不需要手动制定 YAML 顺序规则。
 
 ## 曾考虑的替代方案
 
-**继续只要求本地运行。** 已否决：执行依赖开发者记忆，正是旧 golden 跨 PR 漂移的原因，不能保证产生行为变化的 PR 自己携带 expected diff。
+**继续只要求本地运行。** 已否决：执行依赖开发者记忆，正是陈旧 golden 跨 PR 漂移的原因，不能保证产生行为变化的 PR 自己携带预期输出 diff。
 
-**让 CI 以 `refresh` 模式运行后检查工作树。** 已否决：写后比较把断言机制变成生成器，若工作树检查接线失效就会把回归更新成绿色；replay 直接比较已有 golden，失败面更小。
+**让 CI 以 `refresh` 模式运行后检查工作树。** 已否决：写后比较把断言机制变成生成器，若工作树检查接入有误，就可能把回归变成能够通过的预期输出更新；replay 直接比较已有 golden，失败面更小。
 
 **新建独立 browser job 并重新构建全仓。** 已否决：它会重复依赖安装和发布构建。现有 Linux 消费方 job 已负责该构建，并已被统一的 required verdict 聚合。
 
-**用 jsdom 快照代替真实 Chromium。** 已否决：jsdom 不覆盖浏览器、HTTP/SSE 承载及真实 client plugin bundle 组合；它保留为快速的下层反馈，不能替代 assembled browser chain。
+**用 jsdom 快照代替真实 Chromium。** 已否决：jsdom 不覆盖浏览器、HTTP/SSE 承载及真实客户端插件包的组合；它仍可用于快速的下层反馈，但不能替代组装后的浏览器链路。
 
 ## 后果
 
-每个 PR 都在合并前证明当前 Web 组装与所有已提交的浏览器 expected 一致，漏刷从“后续 PR 的无关变化”变成引入 PR 自己的失败。成本是消费方 job 需要供给 Chromium，并串行运行一轮浏览器场景；消费方独立构建与浏览器缓存避免重跑时重复构建和下载。门禁仍不声称跨平台浏览器一致性，Playwright/Chromium 升级若改变 aria 格式，升级 PR 必须显式 refresh 并评审 churn。
+每个 PR 都在合并前证明当前 Web 组装与所有已提交的浏览器预期输出一致，漏刷从“后续 PR 的无关变化”变成引入 PR 自己的失败。成本是消费方 job 需要安装 Chromium，并串行运行一轮浏览器场景；消费方独立构建与浏览器缓存避免重跑时重复构建和下载。门禁仍不声称跨平台浏览器一致性，Playwright/Chromium 升级若改变 ARIA 格式，升级 PR 必须显式 refresh 并评审 churn。
diff --git a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml
index 052d177aad..5f5facd8d7 100644
--- a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.md
 2026-08-03-opt-in-reasoning-chunk-browser-stress.md: 70c200c7ade6ef995c68b68ddc21e4c85edf0da8
-2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md: aa1d29bffd3dcba54925b43eab13ef4d9a4f7cff
+2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md: 9fb4be27369d4489fc90a6151fcbd0861ef83f2c
diff --git a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md
index aa1d29bffd..9fb4be2736 100644
--- a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 推理分片的逐帧累计发布与浏览器压力验证
+# Agent Note: 推理（reasoning）分片的逐帧累计发布与浏览器压力验证
 
 Status: implemented
 
@@ -12,15 +12,15 @@ Status: implemented
 
 ## 决策
 
-`Session.acceptLiveEvent()` 立即追加每个原始事件，并同步更新 transcript、`PartialAccumulator` 及其他会话派生状态。可见的 `block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta` 和 `block-end` 分片通过 `Notifier.markFrameDirty()` 发布：第一项变化调度一次 `requestAnimationFrame`，后续分片只继续更新累积器；帧回调从最新状态重建一个累计快照并通知订阅者一次。`usage`、`finish` 及未知的不可见分片保留在事件窗口中，但不触发无效的 React 通知。会话与历史检查共用同一可见分片分类。
+`Session.acceptLiveEvent()` 立即追加每个原始事件，并同步更新 transcript（文本记录）、`PartialAccumulator` 及其他会话派生状态。可见的 `block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta` 和 `block-end` 分片通过 `Notifier.markFrameDirty()` 发布：第一项变化调度一次 `requestAnimationFrame`，后续分片只继续更新累积器；帧回调从最新状态重建一个累计快照并通知订阅者一次。`usage`、`finish` 及未知的不可见分片保留在事件窗口中，但不触发无效的 React 通知。会话与历史检查共用同一可见分片分类。
 
-`Notifier` 用调度种类和代际标记管理待发布工作。普通结构事件继续通过 `markDirty()` 在微任务发布；如果定稿消息、工具事件或错误到达时仍有待执行的帧发布，微任务会取代它，旧帧回调因代际不匹配而失效。`notifyNow()` 同样使旧调度失效，以保留受控输入的同步回响。没有 `requestAnimationFrame` 的环境退回微任务合批。定稿事件可以跳过一次尚未显示的中间 partial，但发布的定稿内容和原始事件序列保持完整。
+`Notifier` 用调度种类和代际标记管理待发布工作。普通结构事件继续通过 `markDirty()` 在微任务中发布；如果定稿消息、工具事件或错误到达时仍有待执行的帧发布，微任务会取代它，旧帧回调因代际不匹配而失效。`notifyNow()` 同样使旧调度失效，以保留受控输入的同步回响。没有 `requestAnimationFrame` 的环境退回微任务合批。定稿事件可以跳过一次尚未显示的中间 partial，但发布的定稿内容和原始事件序列保持完整。
 
 实时 Think 行对累计文本的横向跟尾属于纯视觉对齐，不需要在每次 React 提交中同步读取布局。组件内调度器将连续请求合并为每三帧一次，从最新 DOM 读取 `scrollWidth` 和 `clientWidth` 并将 `scrollLeft` 直接更新到最新位置；固定的视觉节奏让摘要变化可读，又不会积压浏览器平滑滚动动画。该节流只作用于 Think 的横向摘要，不延迟 Chat 正文滚动、历史 prepend 锚定或用户触发的 `scrollIntoView`。
 
-`pnpm run test:web:stress` 保留为无密钥、需显式启用的浏览器性能证据。确定性的 `?fixture` 会话以独立于绘制的节奏发出 100,000 个 `reasoning-delta`，结尾标记证明事件经过生产会话归并并到达实时 Think 行；50 毫秒心跳和预先调度的 DOM 事件分别测量主线程停顿与交互延迟，250 毫秒预算用于识别明显回归。`DSH_WEB_STRESS_HEADFUL=1` 允许开发者在可见浏览器中使用 Performance 面板分析同一场景。该压力车道是手动性能诊断与修复验收证据，不是默认 CI 门禁，也不替代确定性的调度单元测试。
+`pnpm run test:web:stress` 保留为无密钥、需显式启用的浏览器性能证据。确定性的 `?fixture` 会话以独立于绘制的节奏发出 100,000 个 `reasoning-delta`，结尾标记证明事件经过生产会话归并并到达实时 Think 行；50 毫秒心跳和预先调度的 DOM 事件分别测量主线程停顿与交互延迟，250 毫秒预算用于识别明显回归。`DSH_WEB_STRESS_HEADFUL=1` 允许开发者在可见浏览器中使用 Performance 面板分析同一场景。该压力车道是手动性能诊断与修复验收的证据，不是默认 CI 门禁，也不替代确定性的调度单元测试。
 
-聚焦测试固定 `Notifier` 的逐帧合并、结构事件抢占、失效回调和无 rAF 回退，并在 `Session` 层证明一帧只发布一次最新累计文本且定稿不会被旧帧回调重复通知。fixture 的小型单元测试继续固定输入校验、外部到达节奏、并发拒绝、精确事件数和结尾标记交付，无需把 100,000 分片工作负载带入默认测试套件。
+聚焦测试固定 `Notifier` 的逐帧合并、结构事件抢占、失效回调和无 rAF 回退，并在 `Session` 层证明一帧只发布一次最新累计文本且定稿不会被旧帧回调重复通知。fixture（测试前置数据）的小型单元测试继续固定输入校验、外部到达节奏、并发拒绝、精确事件数和结尾标记交付，无需把 100,000 分片工作负载带入默认测试套件。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ Status: implemented
 
 **在接收或日志层丢弃、抽样或拼接原始分片。** 不予采纳：原始 `assistant/chunk` 是可重放的会话事实，改变它会损失诊断与 UI 保真度，并把展示频率策略混入数据权威层。
 
-**只使用微任务合批。** 不予采纳：连续异步 `yield` 会在相邻分片间排空微任务队列，使一个微任务调度近似退化为一次分片一次通知。
+**只使用微任务合批。** 不予采纳：连续异步 `yield` 会在相邻分片间排空微任务队列，使微任务合批近似退化为每个分片通知一次。
 
 **按动画帧控制测试生产方节奏。** 不予采纳：生产方会在渲染变慢时同步减速，使页面获得真实网络流不存在的隐式背压，并掩盖主线程饥饿。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
index e4acea8bc5..ba673b6d6d 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
 2026-07-29-durable-last-activity-index.md: 0e441f54a719b29a1a450c133e08cdf7d2c82e9e
-2026-07-29-durable-last-activity-index.zh.md: 9557da0a186084499dfb0f3e8d36016d5b216ae7
+2026-07-29-durable-last-activity-index.zh.md: d66fc9a53700988976acea2f040f1aa886ea9e4f
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
index 9557da0a18..d66fc9a537 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
@@ -8,38 +8,38 @@ Status: proposed
 
 一个冷会话（已持久化、未附加）对「上次是什么时候在这里面工作过」没有任何已存储的答案。因此 `dsh-host-apiproxy` 的 `summarizeCold()` 在存在日志文件时用它的 mtime 来近似它——`locate()` 为 JSONL 解析出一个逐会话产物，为 SQLite 解析出 `undefined`，而 SQLite 的冷会话会回退到 `createdAt`——而 web 客户端就按由此得到的 `updatedAt` 为自己的会话树排序。这两个后端错的方向正好相反：JSONL 读出来偏新，SQLite 偏旧。
 
-mtime 回答的是另一个问题：这份产物上次是什么时候被写入的。每一次持久写入都会刷新它，包括那些并不是活动的写入：一次对撕裂尾部的截断修复、用来平衡被中断的轮次的那些合成 closer，以及带种子的会话会追加的 [`session/end-seed` 边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)。（没有待处理内容的 `flush` 不在其中：协调器在到达后端之前就返回了。）用户可见的后果是稳定的，而且只朝一个方向错：一个被触碰过却没有在里面工作过的会话，会把自己排到用户此后真正工作过的那些会话之前，而且每次触碰都会重新把它排上去一次。`dsh-host-apiproxy` 让 `session.history` 保持只执行检查，但任何绑定到 Agent 的普通会话控件都会通过 `agentFor()` 恢复会话，足以把冷态产物排到前面。
+mtime 回答的是另一个问题：这份产物上次是什么时候被写入的。每一次持久写入都会刷新它，包括那些并不是活动的写入：一次对撕裂尾部的截断修复、用来平衡被中断的轮次的那些合成 closer，以及带种子的会话会追加的 [`session/end-seed` 边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)。（没有待处理内容的 `flush` 不在其中：协调器在到达后端之前就返回了。）用户可见的后果是稳定的，而且只朝一个方向错：一个被触碰过却没有在里面工作过的会话，会把自己排到用户此后真正工作过的那些会话之前，而且每次触碰都会重新把它排上去一次。`dsh-host-apiproxy` 让 `session.history` 保持只用于检查，但任何绑定到 agent（智能体）的普通会话控件都会通过 `agentFor()` 恢复会话，足以把冷态产物排到前面。
 
-已附加会话的那个投影有真正的修复办法（`lastActivityTime()` 会跳过边界），但它需要事件日志，而冷路径有意不去读日志。为计算 `updatedAt` 而读取日志，会让只读 header 的列举失去意义，而正是它让 `list()` 的开销随会话数量而非日志体量增长。
+已附加会话的那个投影有真正的修复办法（`lastActivityTime()` 会跳过边界），但它需要事件日志，而冷路径有意不去读日志。为计算 `updatedAt` 而读取日志，会让仅读取 header 的列举失去意义，而正是它让 `list()` 的开销随会话数量而非日志体量增长。
 
 [边界那次变更](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)提高了这个缺陷的出现频率，因为一次拾起如今会在此前完全无写入的路径上产生写入；`dsh-host-apiproxy` 的 README 已在 Known Limitations 中记录该项。它并没有引入这套近似做法，而移除这套近似是一项持久格式决策，因此它的范围划在本文，而不是那里。
 
 ## 提案
 
-把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每 id 状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 契约中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
+把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每个 id 的状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 约定中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
 
 两个已交付的后端受到的约束正好相反，本提案对它们有意采取不对称的处理：
 
 - **SQLite** 在 `sessions` 表上得到一列，与 `appendBatch` 在同一个事务中写入，代价是一次单调的 `SCHEMA_VERSION` 递增。
-- **JSONL 无法承载一个可变的 header 字段。** header 就是第 1 行，在物化时一次写就，此后这份日志永远以追加方式打开；`jsonl.spec.ts` 钉住了「已提交的字节绝不重写」。一个每次追加都要改的 header 字段，违反的是一条被断言的持久性不变式，而不只是让写入方变复杂。要与「让 JSONL 保持近似」相比较的形态，是每会话一个伴随文件。
+- **JSONL 无法承载一个可变的 header 字段。**header 就是第 1 行，在物化时一次写就，此后这份日志永远以追加方式打开；`jsonl.spec.ts` 钉住了「已提交的字节绝不重写」。一个每次追加都要改的 header 字段，违反的是一条被断言的持久性不变式，而不只是让写入方变复杂。要与「让 JSONL 保持近似」相比较的形态，是每会话一个伴随文件。
 
 实现之前必须回答三个问题，本文对它们都没有定论：
 
-**哪些事件算作活动？** 对日志而言，`lastActivityTime()` 通过排除 `session/end-seed` 回答了这个问题。一个已存储字段是在写入时编码这条规则的，而写入方在那里只看到一个批次，不是整份日志。两者不得发生漂移，否则已附加表层与冷表层会对同一个会话给出彼此矛盾的答案。
+**哪些事件算作活动？**对日志而言，`lastActivityTime()` 通过排除 `session/end-seed` 回答了这个问题。一个已存储字段是在写入时编码这条规则的，而写入方在那里只看到一个批次，不是整份日志。两者不得发生漂移，否则已附加表层与冷表层会对同一个会话给出彼此矛盾的答案。
 
-**该字段引入之前的日志表现如何？** 既有产物里没有这个值。回退到 mtime 能让它们保持今天的准确度；回退到 `createdAt` 是诚实的，但会把选择器和会话树里每一个既有会话都重新排一次序。
+**该字段引入之前的日志表现如何？**既有产物里没有这个值。回退到 mtime 能让它们保持当前的准确度；回退到 `createdAt` 是诚实的，但会把选择器和会话树里每一个既有会话都重新排一次序。
 
-**对 JSONL 来说伴随文件可以接受吗？** 它重新引入了每会话第二个文件，而该文件可能与日志不一致，这正是单产物设计所避开的。
+**对 JSONL 来说伴随文件可以接受吗？**它重新引入了每会话第二个文件，而该文件可能与日志不一致，这正是单产物设计所避开的。
 
 ## 考虑过的替代方案
 
-**在冷路径上读取日志。** 它按构造就是正确的，也不需要改动格式，但会让只读 header 的列举失去意义：`list()` 的开销将随日志总体量增长，而 web 会话树会扇出到存储中的每一个会话。mtime 近似的存在，正是为了避开这个选项。
+**在冷路径上读取日志。**它按构造就是正确的，也不需要改动格式，但会让仅读取 header 的列举失去意义：`list()` 的开销将随日志总体量增长，而 web 会话树会扇出到存储中的每一个会话。mtime 近似的存在，正是为了避开这个选项。
 
-**保留 mtime，但把边界的写入排除在它之外。** 否决的理由是做不到，而不是不合意：mtime 属于文件系统，不属于后端。除了在每次边界写入之后把时间戳复原，没有别的办法能保住它，而那样做会与任何并发读取方产生竞态，也会对这份产物撒谎。
+**保留 mtime，但把边界的写入排除在它之外。**否决的理由是做不到，而不是不合意：mtime 属于文件系统，不属于后端。除了在每次边界写入之后把时间戳复原，没有别的办法能保住它，而那样做会与任何并发读取方产生竞态，也会对这份产物撒谎。
 
-**仅在确实发生了修复时才写入边界。** 这能降低出现频率，而[边界 Agent Note](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)已经否决过它：谓词对有序重启同样必须成立。用一条正确性不变式去换时间戳的准确度，方向是错的。
+**仅在确实发生了修复时才写入边界。**这能降低出现频率，而[边界 Agent Note](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)已经否决过它：谓词对有序重启同样必须成立。用一条正确性不变式去换时间戳的准确度，方向是错的。
 
-**从投影缓存派生活动时间。** `session-projection-cache` 本就会折叠水位线之后的尾部，因此一个最后活动单元可以搭乘既有机制。它作为主形态被否决，因为该缓存是一个可选的组合项；只有挂载了缓存插件才提供的列举，会让排序取决于如何组合。
+**从投影缓存派生活动时间。**`session-projection-cache` 本就会折叠水位线之后的尾部，因此一个最后活动单元可以搭乘既有机制。它作为主形态被否决，因为该缓存是一个可选的组合项；只有挂载了缓存插件才提供的列举，会让排序取决于如何组合。
 
 ## 验收标准
 
@@ -47,17 +47,17 @@ mtime 回答的是另一个问题：这份产物上次是什么时候被写入
 - 在 web 会话树和 TUI 恢复选择器中，一个恢复后即被弃置的会话不会排到此后工作过的会话之前；由一份组装后的快照钉住，而不是只靠单元测试。
 - 活动规则只有一个定义：一个测试证明，在一份同时包含边界、closer 和一个普通轮次的日志上，已存储字段与 `lastActivityTime()` 的结果一致。
 - 在选定的回退方案下，该字段引入之前的产物能够无错误地加载和列举，并且该回退在排序上的后果有断言覆盖。
-- 按本仓库不做迁移的立场，SQLite 的 `SCHEMA_VERSION` 递增会拒绝旧的磁盘版本。
+- 按本仓库不做迁移的立场，SQLite 的 `SCHEMA_VERSION` 递增会拒绝磁盘上的旧版本。
 
 ## 风险
 
-**「活动」的两个定义发生漂移。** 已存储字段按批次计算，而投影在整份日志上计算。一种新事件类型若在写入时按一种方式归类、在读取时按另一种方式归类，就会产生一个冷排序与已附加排序彼此矛盾的会话；这个缺陷只在重启之后才显现，而那正是最难被注意到的地方。
+**「活动」的两个定义发生漂移。**已存储字段按批次计算，而投影在整份日志上计算。一种新事件类型若在写入时按一种方式归类、在读取时按另一种方式归类，就会产生一个冷排序与已附加排序彼此矛盾的会话；这个缺陷只在重启之后才显现，而那正是最难被注意到的地方。
 
-**JSONL 的伴随文件可能与它的日志不一致。** 在日志追加与伴随文件写入之间发生崩溃，会留下一个陈旧的值，而且没有撕裂尾部标记可用来修复它。每个消费方都得把伴随文件当作一条提示来对待，而这与 mtime 今天的地位已经很接近了。
+**JSONL 的伴随文件可能与它的日志不一致。**在日志追加与伴随文件写入之间发生崩溃，会留下一个陈旧的值，而且没有撕裂尾部标记可用来修复它。每个消费方都得把伴随文件当作一条提示来对待，而这与 mtime 目前的地位已经很接近了。
 
-**回退方案会让既有会话重新排序。** 无论选定哪种回退，持有既有日志的用户都会在升级时看到自己的选择器和会话树重新排一次序。选 `createdAt` 会让这次重排的幅度很大。
+**回退方案会让既有会话重新排序。**无论选定哪种回退，持有既有日志的用户都会在升级时看到自己的选择器和会话树重新排一次序。选 `createdAt` 会让这次重排的幅度很大。
 
-**代价可能超过这个缺陷本身。** 该缺陷是被弃置会话的排序出错。如果对 JSONL 来说诚实的答案是「保留这套近似」，那么本文的结局可能是记录下这个决定，而不是实现一个字段，而这也是一个可以接受的结局。
+**代价可能超过这个缺陷本身。**该缺陷是被弃置会话的排序出错。如果对 JSONL 来说诚实的答案是「保留这套近似」，那么本文的结局可能是记录下这个决定，而不是实现一个字段，而这也是一个可以接受的结局。
 
 ## 相关
 
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
index c70cbb870b..cac60421b6 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
 2026-08-08-semantic-composer-chain-phases.md: 7d85518e9d5e5aa3e44e443cb1b90b325b0ffc6a
-2026-08-08-semantic-composer-chain-phases.zh.md: a202b9bfeb9276cdccaa7b438036cd1236a33317
+2026-08-08-semantic-composer-chain-phases.zh.md: 860676a0c83d76e2bd4b8f8f63ca7d025b91c3ff
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
index a202b9bfeb..860676a0c8 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 
 阶段词汇归声明该 slot 的领域所有，而不属于全局 slot 框架。`SlotMap` 携带确切的阶段元组，用于编译期注册；运行时 `SlotSpec` 重复该元组，作为排序依据。其他链不会获得任何 composer 术语，也无需迁移，除非它们主动声明阶段。
 
-本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)契约，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
+本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)约定，但不取代其中任何一项。[运行时负责的子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
 
 ## 备选方案
 
@@ -26,7 +26,7 @@ Status: proposed
 
 **当 `interactions` 非空时，让只读选择器拒绝匹配。** 这可以修复当前这一对组件，但会迫使限制插件理解每个可操作领域，并在各选择器中重复选举策略。每新增一种交互类型，都需要修改与其无关的限制项。
 
-**只依赖运行时子级守卫。** 该守卫可以修复新的模型调用，但无法定义浏览器对已有待处理等待、滚动升级中的版本重叠或审批等其他交互类型的排序。运行时权限与呈现选举是两项独立的不变量。
+**只依赖运行时子级守卫。** 该守卫可以修复新的模型调用，但无法定义浏览器对已有待处理等待、滚动升级中的版本重叠或审批等其他交互类型的排序。运行时权威机制与呈现选举是两项独立的不变量。
 
 **把所有匹配的接管界面渲染成一个栈。** composer 只有一个操作席位。同时堆叠问题、审批和只读界面，会使键盘焦点与回答所有权含混不清，而不是选出一个当前操作。
 
@@ -36,11 +36,11 @@ Status: proposed
 - Composer 测试覆盖问题加只读项、审批加只读项、问题加审批加只读项、解决后回到只读项，以及所有选择器均拒绝匹配时回退到 InputBar。问题在 `interaction` 内仍排在审批之前。
 - dispose（资源释放）、HMR（热模块替换）重新注册和重新连接回放均不能留下陈旧的当选阶段；选举仍是当前所有者 props 与当前注册项的纯函数。
 - 一项无密钥组装 Web 快照固定已寻址的 one-shot 对话及其待处理交互：交互界面胜出，解决该交互后，只读界面再次出现。
-- slot、conversation、question、permission 和 subagent 的 README／JSDoc 契约共同描述阶段所有权以及交互先于限制的规则。
+- slot、conversation、question、permission 和 subagent 的 README／JSDoc 约定共同描述阶段所有权以及交互先于限制的规则。
 - 该变更不修改任何模型可见的工具定义、系统提示词章节、请求路由或会话事件。因此，浏览器选举既不产生 token 开销，也不会使 KV Cache 失效；测试会比较仅在客户端发生状态转换前后的模型请求 header。
 
 ## 风险
 
 阶段名称可能沦为含混的设计替代品。因此，每个分阶段 slot 都要拥有一条简短的排序规则，并拒绝无法说明自身归属哪一侧的注册项。未来如有必须优先于回答操作的硬性安全界面，不应将其误标为 `restriction`；它需要一个显式排在更前的阶段，或位于该 composer 链以外的边界。
 
-通用 slot 类型与已存储条目形态会增加一个条件字段，因此迁移不完整时，代码可能在一个 face 中通过编译，却在运行时失败。之所以在运行时声明中重复确切元组，正是为了让系统能以机械方式拒绝这种漂移。并发问题与审批仍采用单界面策略；本提案保留其当前顺序，不解决多交互排队问题。
+通用 slot 类型与已存储条目形态会增加一个条件字段，因此迁移不完整时，代码可能在一个 compiler face 中通过编译，却在运行时失败。之所以在运行时声明中重复确切元组，正是为了让系统能以机械方式拒绝这种漂移。并发问题与审批仍采用单界面策略；本提案保留其当前顺序，不解决多交互排队问题。
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
index fab3ecc2b1..494cdc8ec9 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
 2026-07-17-sdk-follow-up-capabilities.md: 88d5d2f9bd1ce01c20177bcaee5bbe6b434bb978
-2026-07-17-sdk-follow-up-capabilities.zh.md: 998b7ec3cfddafe40537908fb61aa6d7e6f90418
+2026-07-17-sdk-follow-up-capabilities.zh.md: 083890a88fbb580aafe2e71bef9202f037089d1f
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
index 998b7ec3cf..083890a88f 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: SDK 后续功能
+# Agent Note: SDK 后续能力
 
 Status: proposed
 
@@ -8,13 +8,13 @@ Status: proposed
 
 首个 SDK 版本通过[开发者工程 Agent Note](2026-07-14-sdk-developer-projects.md) 和 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md)定义的共享模型创建和编辑开发者拥有的 Cordis 工程。create 和 config 工作流仅支持交互调用，接入外部 Cordis 插件需要手工修改依赖和配置，命令行遥测没有明确的所属边界，交互分支也缺少稳定的测试策略。
 
-这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品契约。
+这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品约定。
 
 ## 提案
 
 SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；交互测试主要通过注入的提示词输入输出流完成。
 
-| 功能 | 产品入口 | 所属机制 | 必须达到的结果 |
+| 能力 | 产品入口 | 所属机制 | 必须达到的结果 |
 |---|---|---|---|
 | Headless 工程创建 | `create-sdk --config <file>` 或 `--config-json <json>`，可搭配 `--json` | `HeadlessPromptPort`、结构化工程答案和完整功能计划 | 不阻塞等待终端；明确报告缺失的必答输入 |
 | 外部 Cordis 插件安装 | `dsh-sdk create <source>` | 包管理器原生 `add` 加 `ProjectEditSession` | 依赖和 `cordis.yml` 配置项指向包管理器解析出的包 |
@@ -27,25 +27,25 @@ SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非
 
 Headless create 通过 `--config-json` 接收内联 JSON 对象，或通过 `--config` 从文件读取。标量字段提供普通 create 答案，`features` 提供完整的已选功能、功能选项、secret（密钥）和专用值。只有所属问题明确声明的默认值才有效；headless 路径绝不为必答问题臆造答案。
 
-使用 `--json` 时，stdout 是 NDJSON 事件流。`done` 表示创建及要求执行的安装和构建均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr，确保 stdout 每一行都能解析成一个事件。调用方收到 `action-required` 后补充缺失值，再次运行命令。
+使用 `--json` 时，stdout 是 NDJSON 事件流。`done` 表示创建及任何请求的设置均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr，确保 stdout 每一行都能解析成一个事件。调用方收到 `action-required` 后补充缺失值，再次运行命令。
 
 Create 和 config 使用相同的功能计划形状。create 通过上述命令行输入公开该形状；config 在共享工作流边界使用同一形状，使后续自动化入口无需另建功能选择模型。
 
-### Prompt 与工程编辑边界
+### 提示词与工程编辑边界
 
-`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题契约公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
+`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题约定公开的默认值，否则会因问题未回答而失败；预填值通常会让流程根本不调用该 port。
 
 两条路径使用相同的 `Question` 对象、`FeatureConfigurator`、`SdkProject` 和 `ProjectEditSession`。因此，headless 路径只改变答案的到达方式，不改变功能解释或文件提交方式。
 
-### Agent skill
+### agent skill（智能体技能）
 
-仓库提供一份轻量 `SKILL.md`，指导 agent skill（智能体技能）构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI，不导入 SDK 内部 API，也不引入另一套工程规格。
+仓库提供一份轻量 `SKILL.md`，指导 agent skill 构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI（命令行界面），不导入 SDK 内部 API，也不引入另一套工程规格。
 
 ## 外部 Cordis 插件安装
 
 `dsh-sdk create <source>` 接受包管理器原生的 npm package specifier，例如 `pkg@version`，也接受 `github:owner/repo#ref` 等 GitHub package specifier。用户确认后，命令要求工程包管理器添加来源，对比操作前后的直接依赖名，重新打开工程，再通过 `ProjectEditSession` 把每个新增且已解析的包挂载进 `cordis.yml`。
 
-包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不再通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
+包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不会通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
 
 本提案只涉及开发者自有 SDK 工程的依赖。独立应用的仓库缓存、随应用捆绑 pnpm 的政策和显式的准备流程信任边界，均由[包管理器原生仓库缓存](../../implemented/architecture/2026-07-30-package-manager-native-repository-cache.md)负责。
 
@@ -78,43 +78,43 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
 
 ## 曾考虑的替代方案
 
-**另建 headless 创建引擎。** 该方案会复制问题、功能依赖、配置行为和工程编辑规则。复用提示词与编辑会话边界，可以保证工程语义只有一份实现。
+**另建 headless 创建引擎。**该方案会复制问题、功能依赖、配置行为和工程编辑规则。复用提示词与编辑会话边界，可以保证工程语义只有一份实现。
 
-**把规格文件作为主要自动化接口。** Agent 可以内联传入相同的类型化 JSON 对象，人和 CI 仍可选用文件。文件专用协议会增加持久化与清理工作，却不增加语义。
+**把规格文件作为主要自动化接口。**Agent 可以内联传入相同的类型化 JSON 对象，人和 CI 仍可选用文件。文件专用协议会增加持久化与清理工作，却不增加语义。
 
-**使用 `npx skills add` 创建工程。** Skills CLI 只安装 Markdown skill，不创建 SDK 工程，也不安装 npm 包。因此，agent skill 驱动 SDK 初始化命令，而不是取代它。
+**使用 `npx skills add` 创建工程。**Skills CLI 只安装 Markdown skill，不创建 SDK 工程，也不安装 npm 包。因此，agent skill 驱动 SDK 初始化命令，而不是取代它。
 
-**通过 giget 或 pacote 获取 GitHub 与 npm 来源。** 第二套获取层会复制包管理器的解析、完整性、lockfile 和生命周期策略。原生 package specifier 让这些决策留在所选包管理器中。
+**通过 giget 或 pacote 获取 GitHub 与 npm 来源。**第二套获取层会复制包管理器的解析、完整性、lockfile 和生命周期策略。原生 package specifier 让这些决策留在所选包管理器中。
 
-**把遥测实现成 Cordis 运行时插件。** Create 和 build 不一定启动 Cordis，因此运行时插件无法观察完整的开发命令周期。Launcher 是这些命令共用的边界。
+**把遥测实现成 Cordis 运行时插件。**Create 和 build 不一定启动 Cordis，因此运行时插件无法观察完整的开发命令周期。Launcher 是这些命令共用的边界。
 
-**从 git 元数据派生匿名标识符。** 仓库的 git remote 可能识别工程或组织。随机的用户级标识符能够支持聚合，同时不编码仓库身份。
+**从 git 元数据派生匿名标识符。**仓库的 git remote 可能识别工程或组织。随机的用户级标识符能够支持聚合，同时不编码仓库身份。
 
-**只采集聚合计数。** 仅聚合事件可以降低暴露，但无法回答开发者实际使用哪些插件、依赖和配置形状。本提案接受采集脱敏后的工程文本，并明确记录这项暴露。
+**只采集聚合计数。**仅聚合事件可以降低暴露，但无法回答开发者实际使用哪些插件、依赖和配置形状。本提案接受采集脱敏后的工程文本，并明确记录这项暴露。
 
-**把真实 PTY 和 transcript（文本记录）快照作为主要测试策略。** 原生 PTY 依赖与终端重绘序列会带来平台和渲染不稳定性，而且主要是在测试 clack。注入交互并断言生成文件，可以直接测试 SDK 拥有的行为。
+**把真实 PTY 和 transcript（文本记录）快照作为主要测试策略。**原生 PTY 依赖与终端重绘序列会带来平台和渲染不稳定性，而且主要是在测试 clack。注入交互并断言生成文件，可以直接测试 SDK 拥有的行为。
 
 ## 验收标准
 
 - Create 能依据完整结构化输入在没有 TTY 时运行；使用 `--json` 时 stdout 只输出 NDJSON；缺少必答输入时通过 `action-required` 报告，且不写入部分工程。
-- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划契约。
-- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时快速失败。
+- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划约定。
+- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时明确报错。
 - 初始化命令与每个 `dsh-sdk` 命令都进入同一条尽力而为的遥测收尾路径；明确禁用的配置项、`DO_NOT_TRACK` 或 CI 会阻止传输，遥测失败绝不改变命令结果。
 - 遥测绝不读取 `.env`；没有 `cordis.yml` 时不发送无关的 `package.json` 内容；两个符合条件的文本都经过脱敏；匿名标识符与 git 元数据无关。
 - 交互测试通过注入交互覆盖 create 和 config 决策，并断言已提交的工程文件；真实 PTY 覆盖只作为窄范围冒烟层。
-- Agent skill 说明公开的结构化输入与事件契约，不依赖包的私有导出。
+- Agent skill 说明公开的结构化输入与事件约定，不依赖包的私有导出。
 
 ## 风险
 
 - 即使经过脱敏，完整的 `cordis.yml` 与 `package.json` 文本仍会向 endpoint 运营方暴露插件名、依赖名、URL、路径和配置值；启发式脱敏也可能漏掉 secret。
 - 没有遥测配置项时默认上报可能让开发者意外；发布前 CLI 必须让关闭方法易于发现。
-- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败会留下需要手工恢复的依赖改动。
+- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败可能留下需要手工恢复的依赖改动。
 - GitHub 依赖可能按包管理器策略执行 preparation 或 lifecycle script；尚未解决的构建策略会带来供应链与可复现性风险。
-- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余契约。
+- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余约定。
 
 ## 参考资料
 
 - [Vercel Eve](https://github.com/vercel/eve) 与 [Vercel Labs Skills](https://github.com/vercel-labs/skills) 用于区分 headless 初始化命令与 skill 分发。
-- [npm package specifications](https://docs.npmjs.com/cli/v11/using-npm/package-spec)、[pnpm add](https://pnpm.io/cli/add)和 [Yarn add](https://yarnpkg.com/cli/add)说明包管理器原生来源。
-- [`DO_NOT_TRACK`](https://donottrack.sh/)定义环境级关闭约定。
+- [npm package specifications](https://docs.npmjs.com/cli/v11/using-npm/package-spec)、[pnpm add](https://pnpm.io/cli/add) 和 [Yarn add](https://yarnpkg.com/cli/add)说明包管理器原生来源。
+- [`DO_NOT_TRACK`](https://donottrack.sh/) 定义环境级关闭约定。
 - [Clack](https://github.com/bombshell-dev/clack) 和 [Vitest snapshots](https://vitest.dev/guide/snapshot) 说明注入提示词交互与生成文件断言。
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
index fa7ea8e141..f364456257 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
 2026-08-01-windows-pwsh-default.md: 1c3ccef23bb5cd9bc37237bd69aac2e2c56649a8
-2026-08-01-windows-pwsh-default.zh.md: 3958d21eb8a9d306009b11d6e9806a1654a8958e
+2026-08-01-windows-pwsh-default.zh.md: d9fcc50a36a86b356fdf8507f53226d87dddc7bc
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
index 3958d21eb8..d9fcc50a36 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
@@ -6,14 +6,14 @@ Status: proposed
 
 ## 问题
 
-harness 交付的执行画像在每个平台都是 bash 优先。Windows 主机必须安装 bash 垫片（WSL 或 Git-Bash），或退回到仅 POSIX 的 `dsh-bash-local` 行为；面向模型的 bash 工具教的是 bash 方言，TUI/Web 表面以 bash 形状的预期渲染终端输出。第一块 Windows 原生基础已随 [pwsh 执行器与工具决策](../../implemented/feature/2026-08-01-pwsh-tool-and-executor.md) 交付：`ctx.bash` seam 的 PowerShell 实现与对等的 `pwsh` 工具——但还没有任何东西让 Windows 主机默认使用它们。
+harness 交付的执行配置在每个平台都是 bash 优先。Windows 主机必须安装 bash 垫片（WSL 或 Git-Bash），或退回到仅 POSIX 的 `dsh-bash-local` 行为；面向模型的 bash 工具教的是 bash 方言，TUI/Web 界面按照 bash 风格的预期渲染终端输出。第一块 Windows 原生基础已随 [pwsh 执行器与工具决策](../../implemented/feature/2026-08-01-pwsh-tool-and-executor.md) 交付：`ctx.bash` seam 的 PowerShell 实现与对等的 `pwsh` 工具——但还没有任何东西让 Windows 主机默认使用它们。
 
 ## 提案
 
-两个阶段，各自可独立交付。原阶段 2（bash 工具对等孪生）已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在在前台与后台工作（减 sandbox 面）上镜像 `tool-bash`，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装表面的 keyless 应用快照。
+两个阶段，各自可独立交付。原阶段 2（bash 工具对等孪生）已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在除 sandbox 接口外，在前台与后台工作方面均与 `tool-bash` 对齐，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装后形态的 keyless 应用快照。
 
-1. **Windows 默认组合**——交付的 CLI 组合在 Windows 主机上挂载 `dsh-pwsh-local` 作为 `ctx.bash` 执行器、`dsh-tool-pwsh` 作为面向模型的 shell 工具（那里不挂载 bash），POSIX 主机保持 bash 栈。这是 `base.cordis.yml` 与 surface 覆盖层里按平台门控的组合/清单决策；它让交付的 Windows 体验端到端 PowerShell 原生。
-2. **pwsh GUI 渲染**——Web 表面以 bash 形状的终端呈现渲染 pwsh 调用（带退出状态 pill 的 terminal 卡），即 bash 终端卡片的对应物。已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 及 keyless web 通道交付；TUI 已移除，不再有终端孪生。超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 实情）仍无人认领。
+1. **Windows 默认组合**——交付的 CLI（命令行界面）组合在 Windows 主机上挂载 `dsh-pwsh-local` 作为 `ctx.bash` 执行器、`dsh-tool-pwsh` 作为面向模型的 shell 工具（那里不挂载 bash），POSIX 主机保持 bash 栈。这是 `base.cordis.yml` 与 surface 覆盖层里按平台门控的组合/清单决策；它让交付的 Windows 体验端到端 PowerShell 原生。
+2. **pwsh GUI 渲染**——Web 界面使用 bash 风格的终端呈现来渲染 pwsh 调用（带胶囊状退出状态标签的终端卡片），与 bash 终端卡片相对应。已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 及 keyless web 通道交付；TUI 已移除，不再有对应的终端界面。超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 信息）仍无人认领。
 
 各阶段仅在有依赖关系时排序：渲染阶段已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 先行交付（平台无关，其 keyless web 通道可在任意宿主运行），而 Windows 默认组合仍是唯一未交付的阶段。本提案不改变任何 POSIX 行为。
 
@@ -21,7 +21,7 @@ harness 交付的执行画像在每个平台都是 bash 优先。Windows 主机
 
 **在 `dsh-bash-local` 内部让 Windows 默认 pwsh（一个执行器，方言开关）。** 否决，理由与执行器决策否决模式开关相同：执行器的身份就是它 spawn 的 shell，而按平台门控的组合是部署选择，不是执行器配置。
 
-**把 Windows 默认与执行器/工具一起交付。** 否决：清单变更需要自己的证据（交付的 Windows 树停挂 bash 后什么会坏、哪些工具依赖 bash 语义），并且它属于带批准/PTY 表面可见的组合决策。
+**把 Windows 默认与执行器/工具一起交付。** 否决：清单变更需要自己的证据（交付的 Windows 树停挂 bash 后什么会坏、哪些工具依赖 bash 语义），并且它属于会在审批／PTY 界面上显现的组合决策。
 
 **用垫片在 Windows 上保留 bash，跳过 PowerShell 默认。** 否决：这延续了安装税与路线图要消除的方言错配；垫片是部署要求，不是产品行为。
 
@@ -30,10 +30,10 @@ harness 交付的执行画像在每个平台都是 bash 优先。Windows 主机
 - 运行交付版 `dsh` TUI/Web 的 Windows 主机无需配置即获得 `pwsh` 作为其 shell 工具、PowerShell 作为 `ctx.bash` 执行器，且那里的模型可见清单中没有 `bash`。
 - POSIX 主机逐字节不受影响（清单相同，执行器相同）。
 - 交付组合 e2e 在两个平台族上断言按平台门控的清单。
-- 阶段 1 落地时，parity 变更带来的 keyless pwsh 工具快照已经就位；阶段 2 已随 web `pwsh-terminal` 渲染通道落地（TUI 的移除让终端表面无快照可做）。
+- 阶段 1 落地时，parity 变更带来的 keyless pwsh 工具快照已经就位；阶段 2 已随 web `pwsh-terminal` 渲染通道落地（TUI 的移除意味着不再有可供快照测试的终端界面）。
 
 ## 风险
 
-- **依赖 bash 的组合行**——任何假设 bash 语义的交付插件（执行 shell hooks 的 hooks 桥、工作区工具）必须按阶段审计；审计可能迫使分阶段推出而非一次切换。
-- **Windows CI 覆盖缺口**——单元覆盖在 Linux 上运行；pwsh 栈里仅 Windows 的回归通过 Windows 构建/静态通道与 e2e 浮出，必须按阶段扩展而不是想当然。
-- **渲染约定**——bash 形状的终端孪生已随 web 通道交付；超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 实情）仍是带快照表面的 UI 设计决策，随阶段 1 一起延期。
+- **依赖 bash 的组合行**——任何假设 bash 语义的交付插件（执行 shell 钩子的钩子桥接、工作区工具）必须按阶段审计；审计可能迫使分阶段推出而非一次切换。
+- **Windows CI 覆盖缺口**——单元覆盖在 Linux 上运行；pwsh 栈里仅 Windows 的回归通过 Windows 构建/静态通道与 e2e 暴露出来；这些覆盖必须按阶段扩展，不能想当然地认为已经具备。
+- **渲染约定**——与 bash 风格一致的终端呈现已随 web 通道交付；超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 信息）仍是一项需要快照覆盖的 UI 设计决策，随阶段 1 一起延期。
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
index 5418a920e5..c0a2063391 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md
 2026-08-04-artifact-first-npm-baseline-publication.md: e79a988531ac266d72f7d2c036bdd10f3e4520a9
-2026-08-04-artifact-first-npm-baseline-publication.zh.md: d7322547c665700aeffce77ea0bb39f622220fe3
+2026-08-04-artifact-first-npm-baseline-publication.zh.md: e071704741fed58e83325bbc2765fe248ef113c7
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
index d7322547c6..e071704741 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
@@ -23,7 +23,7 @@ monorepo 中可运行的源码并不能证明发布后的包可运行。workspac
 pack 阶段按以下顺序执行：
 
 1. 将 ref 解析成不可变 commit，采集 UTC 时间戳，从该 commit 的根 manifest 派生版本，并显示 commit、时间戳、版本、tag、注册表和输出路径。`pack` 与 `release` 此时都会在昂贵操作开始前等待 Enter；自动化可用 `--yes` 跳过该确认。
-2. 在隔离的 detached worktree 中安装 frozen lockfile，并在暂存发布 manifest 之前运行源码 manifest 发布约束；调用方工作树中的未提交文件和旧构建输出不得参与发布。
+2. 在隔离的 detached worktree 中安装 frozen lockfile，并在暂存前运行源码 manifest 发布约束；调用方工作树中的未提交文件和旧构建输出不得参与发布。
 3. 将所有目标 manifest 暂存为派生版本，移除发布时的 `private` 标记，并把 `dependencies`、`devDependencies`、`optionalDependencies` 与 `peerDependencies` 中的内部 workspace 依赖全部改写为同一精确版本。
 4. 完整构建目标 commit，再运行 publint 和已构建包不变式。
 5. 为目标集合中的每个包执行 pack，但不执行任何注册表写入。
@@ -38,13 +38,13 @@ pack 阶段按以下顺序执行：
 
 已提交的 pack 命令实现了固定 commit 暂存、内部依赖精确固化、静态与 tarball payload 检查、不可变 manifest，以及把每个发布 tarball 都作为本地顶层依赖的隔离 npm 安装。它在输出 publish 命令前，用普通 Node 运行安装后的 `dsh --version` 与 `dsh --dump-default-config` 入口，再在 POSIX PTY 中启动安装后的默认 TUI，等待其 `main-session-` 就绪信号，并通过 `/exit` 退出。Publish 支持按 integrity 恢复，将只读注册表验证与认证身份检查分离，并以完整的远端 integrity 和 dist-tag 验证结束。
 
-拉取请求 CI 不会调用 pack 命令；安装态入口探测属于本地发布检查，而不是合并门禁。免凭据 CI 执行、其他每个 bin 与公开运行时入口的包自有探测、workflow artifact 传递及受保护 publish job 仍属于提案范围。
+PR（Pull Request） CI 不会调用 pack 命令；安装态入口探测属于本地发布检查，而不是合并门禁。免凭据 CI 执行、其他每个 bin 与公开运行时入口的包自有探测、workflow artifact 传递及受保护 publish job 仍属于提案范围。
 
-## 发布 payload 契约
+## 发布 payload 约定
 
 发布包只携带消费方需要的构建产物。`package.json#files` 禁止包含 `src` 和 `lib/types/**/*.d.ts.map`；tarball 内容门禁还要独立确认不存在任何 `package/src/**` 与 `package/**/*.d.ts.map`，避免 manifest pattern 或 pack 行为绕过静态约束。运行时 JS、声明文件 `.d.ts`、配置、资源、worker 文件和 bundle 动态 chunk 必须按实际入口闭包收齐。
 
-源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方契约。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
+源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方约定。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
 
 每个 tarball 必须不含 `workspace:` specifier，并且所有指向本次发布集合的内部依赖与对等依赖（peer dependency）都必须精确等于本次派生版本，禁止使用 `^`、`~` 或其他 semver 范围跨越 commit 基线。除了明确仅供源码平面使用的 `exports["./src/*"]`，package manifest 中声明的每个消费方入口都必须指向 tarball 内存在的文件；动态 import、运行时拼接路径和非 export 资源不能只靠 manifest 检查，必须由安装后执行覆盖。
 
@@ -52,7 +52,7 @@ pack 阶段按以下顺序执行：
 
 集成测试在全部 tarball 生成后、任何 publish 之前运行。它在 monorepo 外创建一个全新临时项目，通过本次 release manifest 中的本地 `.tgz` 文件安装声明依赖闭包，并从安装目录执行。测试必须使用普通 Node 与包管理器生成的 `node_modules`；禁止 tsx、tsconfig paths、workspace link、仓库源码路径、工作树 `lib/` 和已发布注册表中的同版本包参与解析。测试还要断言关键模块与 bin 的真实路径位于临时消费方内。
 
-安装使用本次发布选择的客户端行为。注册表上传必须使用 `npm` CLI，以满足私有注册表只接受 npm 客户端的策略；构建编排仍可使用 pnpm。tarball 测试不得先把这些包发布到真实注册表，也不得在测试后重新 pack。
+安装使用本次发布选择的客户端行为。注册表上传必须使用 `npm` CLI（命令行界面），以满足私有注册表只接受 npm 客户端的策略；构建编排仍可使用 pnpm。tarball 测试不得先把这些包发布到真实注册表，也不得在测试后重新 pack。
 
 测试至少覆盖以下执行面：
 
@@ -73,13 +73,13 @@ npm 不提供多包原子事务，上传仍会逐包发生。编排器通过幂
 
 ## GitHub Actions 集成
 
-GitHub Actions 分为无凭据的 pack-and-test job 与受保护的 publish job。前者检出精确 commit，调用与本地相同的 pack 入口，运行 tarball 消费方测试，并上传完整 release bundle 作为 workflow artifact。后者依赖前者成功，从 workflow artifact 下载 bundle、重新校验 manifest 和校验和，再调用同一个 publish 入口；它不能检出后重新构建。
+GitHub Actions 分为无凭据的 pack-and-test job 与受保护的 publish job。前者检出精确 commit，调用与本地相同的 pack 入口，运行 tarball 消费方测试，并上传完整 release bundle 作为工作流产物。后者依赖前者成功，从工作流产物下载 bundle、重新校验 manifest 和校验和，再调用同一个 publish 入口；它不能检出后重新构建。
 
 PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合并前发现 payload 回归。实际私有注册表发布先通过 `workflow_dispatch` 提供，输入只包括目标 ref；UTC 时间戳由 pack job 生成，基础版本、短 SHA、tag、注册表和包清单都由仓库状态或受版本控制的配置派生。稳定发布触发方式不在本基线提案范围内。
 
-注册表 token 只注入 publish job，并由受保护 GitHub Environment 控制人工批准、允许的分支或 tag 以及并发。pack-and-test job 不得读取发布凭据。workflow artifact 的保留期可以较短，但 publish job 必须使用同一 workflow run 生成的 bundle，不能按版本号从不受信任的位置寻找 tarball。
+注册表 token 只注入 publish job，并由受保护 GitHub Environment 控制人工批准、允许的分支或 tag 以及并发。pack-and-test job 不得读取发布凭据。工作流产物的保留期可以较短，但 publish job 必须使用同一 workflow run 生成的 bundle，不能按版本号从不受信任的位置寻找 tarball。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **从 workspace 直接递归 publish。** 不采用，因为命令会把 pack 与注册表写入交错，无法在第一次写入前证明整个集合完整，也容易让 workspace 解析与调用方工作树状态影响发布结果。
 
@@ -87,13 +87,13 @@ PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合
 
 **只运行 `dsh --help`。** 不采用，因为 Commander 可以在加载 TUI、Web 或 headless 动态入口之前输出帮助并退出。它无法证明默认生产启动路径完整。
 
-**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布契约。
+**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布约定。
 
 **要求真正的跨包原子发布。** 不采用，因为 npm 注册表没有相应事务。不可变 release bundle、发布前全量验证、integrity 比对与幂等恢复提供可实现的边界，同时明确保留部分上传短暂可见的限制。
 
-**在批准后由发布 job 重新构建。** 不采用，因为测试通过的 tarball 与实际上传的 tarball 将不再具有内容身份。workflow artifact 与校验和必须把测试输入直接传给发布步骤。
+**在批准后由发布 job 重新构建。** 不采用，因为测试通过的 tarball 与实际上传的 tarball 将不再具有内容身份。工作流产物与校验和必须把测试输入直接传给发布步骤。
 
-## Acceptance criteria
+## 验收标准
 
 - 一个 pack 入口从确定 commit 发现 `packages/*/*` 和 `apps/*` 的全部目标包，以 UTC 秒级时间戳与短 commit 生成并显示版本，再等待 Enter；它在任何注册表写入前生成完整 release bundle，并输出一个可复制的 publish 命令；`release` 在 pack 后再次等待，`--yes` 跳过两次确认。
 - 静态 manifest 门禁和 tarball 内容门禁都拒绝发布 `src` 与 `.d.ts.map`，同时保留源码 manifest 中的 `exports["./src/*"]`。
@@ -103,9 +103,9 @@ PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合
 - publish 可在部分成功后用同一 manifest 安全重跑；相同 integrity 被跳过，不同 integrity 被拒绝，最终验证要求所有版本与 tag 一致。
 - GitHub Actions 的无凭据 job 生成并测试 bundle，受保护 job 上传完全相同的 bundle，发布 token 只存在于后者。
 
-## Risks
+## 风险
 
-全量 pack、安装和启动会增加 CI 时间与 workflow artifact 体积。实现应缓存外部依赖和 pnpm store，但不得缓存或复用目标包的已安装 workspace 输出；并行执行安全的消费方 probe 可以降低时延。
+全量 pack、安装和启动会增加 CI 时间与工作流产物体积。实现应缓存外部依赖和 pnpm store，但不得缓存或复用目标包的已安装 workspace 输出；并行执行安全的消费方 probe 可以降低时延。
 
 把所有 tarball 都安装为临时项目的顶层依赖可能掩盖未声明的内部依赖。测试生成器应按被测应用的声明式递归闭包安装，并结合现有依赖门禁；对依赖面接近全集的 `@deepseek-ai/dsh`，仍需依靠 package manifest 与静态图检查发现未声明边。
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index 0f5dedddd2..4a13087f8e 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
 2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: b3f7a1d9717397ee9ed50890bc024fba7d79fa9a
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: a625c6eb2253098da3f20cd07523c926add4b32d
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index b3f7a1d971..a625c6eb22 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -6,7 +6,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 
 ## 问题
 
-一次仓库级的「Not Invented Here（非我发明）」审计（2026-07-26，十路并行普查，覆盖每个包（package）分组、scripts/、native/、vendor/ 边界、python/、测试基础设施与 CI）对每一处手写接口面追问同一个问题：在[依赖政策](../../implemented/process/2026-07-26-dependencies-over-hand-rolling.md)之下，是否有持续维护的外部包或 Node 内置能力能以净收益把它删除？得出肯定结论的发现已各自写成独立的提案 Agent Note（agent 决策记录）。否定裁定的价值不相上下——每一条都点名了一个看似可行、实则手写形态在承重的替换——但否则它们只会留存在某个 PR（Pull Request）正文里。本 note 将它们固化在案。
+一次仓库级的「Not Invented Here（非我发明）」审计（2026-07-26，十路并行普查，覆盖每个包分组、scripts/、native/、vendor/ 边界、python/、测试基础设施与 CI）对每一处手写接口面追问同一个问题：在[依赖政策](../../implemented/process/2026-07-26-dependencies-over-hand-rolling.md)之下，是否有持续维护的外部包或 Node 内置能力能以净收益把它删除？得出肯定结论的发现已各自写成独立的提案 Agent Note。否定裁定的价值不相上下——每一条都点名了一个看似可行、实则手写形态在承重的替换——但否则它们只会留存在某个 PR（Pull Request）正文里。本 Agent Note 将它们固化在案。
 
 ## 提案
 
@@ -24,7 +24,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 
 - **以 `p-retry`/`exponential-backoff` 替换 `llm-retry`**：执行模型不对——该插件是一个返回决策的 waterfall（瀑布式事件）监听器，重新执行由 agent loop（智能体循环）依据持久日志负责；根本不存在可供重新调用的函数，而那恰是这些库的全部 API。提供方 `Retry-After` 覆写、依据先前失败代码计算预算、持久化的 `llm/retry` 事件、HMR（热模块替换）完全停稳式中止，全都无从覆盖。[LLM（大语言模型）请求受限恢复决策](../../implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)已经否决了由 SDK 持有的重试。
 - **以 `p-timeout`/`AbortSignal.timeout` 替换 `dsh-timeout`**：内置能力无法提前解除，抛出的是通用 `TimeoutError`，而不是能区分嵌套截止时限、按能力编码的 `TimeoutReason`；`idleWatchdog` 按需逐次重新装定的能力没有等价物。设计归[超时库决策](../../implemented/architecture/2026-07-06-timeout-deadline-library.md)所有。
-- **以 `p-limit`/`p-queue` 替换 agent-loop 的工具调用池**：池的簿记只有约 25 行；实质部分（按模型顺序提交、组中途重新分类、排他屏障、带合成持久结果的中止排空）根本不是并发限制器的形状。
+- **以 `p-limit`/`p-queue` 替换 agent loop 的工具调用池**：池的簿记只有约 25 行；实质部分（按模型顺序提交、组中途重新分类、排他屏障、带合成持久结果的中止排空）根本不是并发限制器的形状。
 - **以 `p-queue`/`async-mutex` 替换按 key 的 promise 链串行器**（`fs-local`、`storage-domain`）：串行器只有 8–14 行；这些包严格大于它们所能删除的代码。
 - **以 `events.once` + `AbortSignal.timeout` 替换 subagent-subprocess 的 `exitsWithin`**：`error` 先触发时 `events.once` 会 reject，而手写实现有意忽略 `error`（由 spawn 失败路径单独捕获）；这次替换恰恰会在语义本身就是拆除竞态的那段代码里改变拆除竞态行为。
 
@@ -35,7 +35,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `fast-deep-equal` 替换会话接口面的 `isDeepEqualJson`**、**以 `safe-stable-stringify` 承担 repeat-tool-guard 的规范化**：两项替换在机械层面都可行，但每一项都是拿约 17–20 行带注释、有测试的代码，去换一个核心包的第一个外部运行时依赖——在这个体量上是净亏损。
 - **以 zod/valibot 承担持久事件的严格解码器**（goal fold、tool-ralph、session）：它们是位于持久化边界、键集精确匹配、失败即大声报错、带事件专属报错信息的解码器；在仓库标准 schemastery 之外再放一个 schema 库是政策变更，不是删除。
 - **以 `gpt-tokenizer`/tiktoken 替换 token-meter**：[回放 token 计量决策](../../implemented/architecture/2026-07-15-replay-token-meter-service.md)已明确否决分词器后端；GPT 的 BPE 对 DeepSeek 模型来说也是错误的分词器，而且这个包约 350 行是回放折叠簿记，任何分词器都覆盖不了。
-- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的契约，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
+- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的约定，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
 
 **文件系统、子进程与终端：**
 
@@ -46,14 +46,14 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `shell-quote` 承担 POSIX 单引号包裹**：两个各 1 行、测试详尽的引号辅助函数，对上一个处于维护模式、有 CVE 历史、转义输出还不一样的包——安全边界不是省一行代码的地方。
 - **以 `strip-ansi` 承担 pty 净化**：pty 净化器是一台流式状态机，带跨分片的断裂序列续接和 OSC `133;D` 提示符标记提取（shell 就绪信号）；无状态的剥离器只能替掉约 20 行内层代码，全部状态机构件原样保留。`stripVTControlCharacters` 还被实证会泄漏未终止的 OSC 载荷，会话标题归一化器必须剥除它们（反欺骗）。
 - **以 `pidtree`/`ps-tree` 承担 pty 进程巡检器**：它们只给裸 PID 树；这段代码需要对抗 PID 复用的启动时间身份校验，加上 `/proc` stdin 等待检测，没有包做这些。
-- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」契约；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
+- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」约定；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
 - **以 `tree-kill` 承担 acp-snapshot 拆除与 lsp 进程终止**：那些代码行做的是排空顺序与错误传播，不是进程树遍历；lsp/bash 已经使用分离的进程组加 taskkill。
 - **在 TUI 测试驱动器上到处使用 node-pty**：已归档的 [Windows TUI 决策](../../archived/feature/2026-07-20-windows-tui-support.md)明确否决了在每个宿主上都使用 node-pty；它当时已经是 Windows 那一条腿。
 
 **服务器与 HTTP：**
 
 - **以 `msw` 替换 llm-mock-server**：这个服务器的存在意义就是在线路上制造故障——socket 销毁、SSE（Server-Sent Events）中途断连、停滞、监听前拒绝——服务对象是真实的 HTTP 适配器和子进程；进程内拦截一样都表达不了。设计归[线路故障服务器决策](../../implemented/testing/2026-07-25-scriptable-llm-wire-fault-server.md)所有。
-- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」契约、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
+- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」约定、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
 - **以 `@mozilla/readability`/`iconv-lite` 承担 web-fetch-local**：该提供方返回原始 HTML；字符集处理已经是内置的 `TextDecoder`；MIME 解析约 11 行；重定向跟随是同源安全策略。
 
 **SQLite 与存储：**
@@ -74,5 +74,5 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 ## 曾考虑的替代方案
 
 - **什么都不记录，让 PR 正文承载这些裁定。** 不予采纳：PR 正文不属于受维护的记录，而普查的全部意义就在于下一次审计从这些裁定出发，而不是重新推导。
-- **每一项各写一份 rejected note。** 不予采纳：为共享同一套证据标准、同一种命运的裁定制造约 30 个文件的仪式感；只有当某一项带着新证据被重新提出时，逐项 note 才有必要。
-- **把每条裁定并入拥有该 seam 的 implemented note。** 部分已做——凡是持有方 note 已经否决过该替代方案的（重试、token 计量、schema DSL、zstd、沙箱、node-pty），本 note 一律援引而不重复。其余各项没有持有方 note，这正是它们记录于此的原因。
+- **每一项各写一份 rejected note。** 不予采纳：为共享同一套证据标准、同一种命运的裁定制造约 30 个文件的仪式感；只有当某一项带着新证据被重新提出时，逐项 Agent Note 才有必要。
+- **把每条裁定并入拥有该 seam 的 implemented note。** 部分已做——凡是持有方 Agent Note 已经否决过该替代方案的（重试、token 计量、schema DSL、zstd、沙箱、node-pty），本 note 一律援引而不重复。其余各项没有持有方 note，这正是它们记录于此的原因。
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 077f5fa7f2..695f81e459 100644
--- a/README.i18n.yaml
+++ b/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 README.md
 README.md: ff4cf661a060772973629844d43758d26ac1be02
-README.zh.md: 977de7f22244ff49579393edcce66d02c5782de4
+README.zh.md: a11834c590a3930e881447d79bbfeb7a10ee3a92
diff --git a/README.zh.md b/README.zh.md
index 977de7f222..a11834c590 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。
+DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。
 
 它采用了**一切皆插件**的架构。
 
@@ -49,7 +49,7 @@ dsh plugin --profile tui add <package>  # install a plugin into a custom profile
 dsh --profile tui                       # boot it
 ```
 
-profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。
+profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。
 
 ### Headless
 
@@ -73,7 +73,7 @@ pnpm run demo:acp
 
 内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。
 
-- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
+- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
 - **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。
 - **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。
 - **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 801560e7d7..162ea534b7 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
 README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 9518feed1d5d40c3e5ec2d346b929118ccc08810
+README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 9518feed1d..37967973ed 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -23,4 +23,4 @@ profile 目录包含一个 `package.json`（树外插件依赖，加上 profile
 
 ## 开发
 
-生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。
+生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析约定。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 325de8db4e..12dbcaaa86 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
 README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: a65140e6dc9374e21bdd3018bce45432794a7b10
+README.zh.md: 74fa00cbf4dc31f29e0113be500a825520abb553
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a65140e6dc..74fa00cbf4 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -31,7 +31,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 ## 插件管理
 
-`dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，`dsh.profile.bundles` 都会与已安装状态对齐：每个解析到 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的包的依赖加入层栈（因此让包获得该声明的 `update` 会将其激活），没有组合包声明的依赖保持为普通依赖并给出一次性警告，已移除的依赖则退出层栈。
+`dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，`dsh.profile.bundles` 都会与已安装状态对齐：解析结果为某个包、且该包的 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的每个依赖都会加入层栈（因此让包获得该声明的 `update` 会将其激活），没有组合包声明的依赖保持为普通依赖并给出一次性警告，已移除的依赖则退出层栈。
 
 ```sh
 dsh plugin --profile tui add github:deepseek-harness/turtle-ui
@@ -51,7 +51,7 @@ dsh web --patch ./extra.cordis.yml
 dsh web --dump-config
 ```
 
-生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
+生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有网络接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
 
 进程关闭时会给插件树最多 5 秒完成 dispose。第一次 `SIGINT`/`SIGTERM` 启动该优雅排空；第二次信号强制立即退出。如果一次性运行正常结束时已经卡在 dispose 中，第一次 `Ctrl+C` 就会升格并立即退出，而不会被吞掉。
 
@@ -61,15 +61,15 @@ dsh web --dump-config
 
 `DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 RL 兼容 `--patch` overlay：它固定使用 `native` 模式，仅将 `DSH_SYSTEM_PROMPT` 或 `You are a helpful software engineer assistant.` 渲染为系统提示词，禁用 Workspace 指令与所有 Web 运行时提示词贡献，并且在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，仅暴露持久 `bash` 和 `str_replace_editor`。
 
-`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该契约的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
+`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该约定的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
 
 ## 共享部署行为
 
-基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository Plugin 支持和会话遥测。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
+基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository 插件支持和会话遥测。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
 
-会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
+会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md) 负责。
 
-空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository 插件 generation。参见 [repository 插件约定](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 
diff --git a/docs/agent-lifecycle.i18n.yaml b/docs/agent-lifecycle.i18n.yaml
new file mode 100644
index 0000000000..c299e9c728
--- /dev/null
+++ b/docs/agent-lifecycle.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 docs/agent-lifecycle.md
+agent-lifecycle.md: 5bf2c4454ce2fac31dfd35218f2bc3c3318b18b6
+agent-lifecycle.zh.md: b7cf8a0e36ee08d52e71e5bc439bcf1815b0a467
diff --git a/docs/agent-lifecycle.zh.md b/docs/agent-lifecycle.zh.md
new file mode 100644
index 0000000000..b7cf8a0e36
--- /dev/null
+++ b/docs/agent-lifecycle.zh.md
@@ -0,0 +1,84 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
+
+# Agent 轮次与步骤生命周期
+
+[English](agent-lifecycle.md) | 中文
+
+此时序图是 [architecture.md](architecture.md#loop-lifecycle-session--turn--step) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, no turn opens
+  else enter proposed step
+  Driver->>Session: <code>turn/start</code>
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver->>Session: <code>assistant/chunk</code>*
+  Session-->>SDK: <code>session/event</code> <code>assistant/chunk</code>*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  end
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+`assistant/message` 这条边会记录每次成功的提供方调用，包括无内容的调用和以 `max-tokens` 结束的调用。空内容不会进入派生历史记录，但持久锚点仍会保留 token 用量以及各分片的确切来源信息，其中包括显式的空来源集合。
+
+`dsh-compact-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
+
+以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息，除非有意替换这些消息。steering（中途引导）和注入的上下文在后续边界认领其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
+
+需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求整形、steering、继续执行和错误处理的实时协调接口。
+
+维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 360e4b32e4..b1f78b85e4 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
 api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: 92681b72ffc573cde834cece19568ec3f1d515ce
+api-gateway.zh.md: f77a3e2675cc8ee6d27a8f6c9cbeb39609a9c282
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 92681b72ff..f77a3e2675 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -2,17 +2,17 @@
 
 [English](api-gateway.md) | 中文
 
-本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 契约，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
+本文是 TypeRT API Gateway 的当前状态参考。它描述业务服务如何声明一元 Remote 方法、构建如何生成 Host 与 Client 约定产物，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
 
 ## 编程模型
 
-业务 Service 通过 `@Remote` 或 `@RemoteScope` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
+业务服务通过 `@Remote` 或 `@RemoteScope` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
 
-`@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
+`@Remote` 表示调用根 Host 上下文中注册的 Cordis 服务。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
 
-`@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得 Service 并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
+`@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域上下文，再从该上下文取得服务并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
 
-Service 通常继承 `GatewayService`，让 Cordis service key 与默认 Remote namespace 在构造器中显式绑定。已有其他基类的 Service 可以改为声明 `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
+服务通常继承 `GatewayService`，让 Cordis 服务键与默认 Remote namespace 在构造器中显式绑定。已有其他基类的服务可以改为声明 `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
 
 ```ts
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
 
-Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层 runtime，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。
+Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子服务；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层运行时，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用接口。
 
 ```ts ignore-check
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -75,28 +75,28 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 约定，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
 
 ## 组件职责
 
 | 位置 | 包或入口 | 职责 |
 |---|---|---|
-| 共享 | `@deepseek-ai/dsh-type-meta` | 声明 decorator、Gateway binding、可合并协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 |
-| 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、Context 与源码位置，并生成 Host 和 Host-for-Client 产物 |
-| Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与 Context 提供方 |
+| 共享 | `@deepseek-ai/dsh-type-meta` | 声明 decorator、Gateway binding、可通过合并扩展的协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 |
+| 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、上下文与源码位置，并生成 Host 和 Host-for-Client 产物 |
+| Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与上下文提供方 |
 | Host | `@deepseek-ai/dsh-api-remotes` | 负责应用的 Agent/Session 身份策略，并配置对应的 TypeRT lookup |
-| Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
-| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子 Service，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
+| Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或上下文，调用当前有效的 Cordis 服务并校验边界 |
+| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子服务，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
 | 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
 
 API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
 
-## 严格生成链路
+## 严格生成流水线
 
 根构建依次执行 `build:lib:host`、`build:lib:client` 与 `build:web`。Host lib 阶段先运行 `tsc -b tsconfig.host.json`，再运行 `tsdown --env.DSH_BUILD_FACE host`；TypeRT generator 由正常 Host Project Reference 图编译，并在这次 tsdown 中以 Host aggregate 为唯一 `ts.Program` 种子运行。Client lib 阶段随后运行 `tsc -b tsconfig.client.json` 与 `tsdown --env.DSH_BUILD_FACE client`，使用刚生成的 Remote Client 声明和运行时贡献，但不再次启动 TypeRT。
 
-两次 tsdown 都接收完整 workspace，且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按 package 名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client plugin 在 Client 阶段一起生成 Node loader 入口与 browser bundle。
+两次 tsdown 都接收完整 workspace，且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按包名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client 插件在 Client 阶段一起生成 Node loader 入口与 browser bundle。
 
 `api-remotes` 是唯一拆分 TypeScript face 的 package 特例。它的 Host project 负责 Agent/Session lookup 策略，Client project 则依赖业务包在 Host tsdown 中生成的 `/remote` 声明；根 aggregate 与直接消费方必须分别引用 `api/remotes/tsconfig.host.json` 或 `api/remotes/tsconfig.client.json`。包内 `clientBundle(..., { hostPhase: true })` 让 Host 入口在 Host tsdown 中生成，让 Client tsdown 只生成 browser 入口。其他 package 仍只登记在一个 aggregate 中。
 
@@ -114,31 +114,31 @@ API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对
 
 Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则引用原业务包导出的 Client-safe 类型。声明 map 把 `ctx.remote.goals.create` 最终解析到的生成属性映射到带 `@Remote` 的 Host 源方法，因此支持 declaration-map 的编辑器可以从 Client 调用跳到真实实现，而不是停在生成的 `.d.ts`。
 
-严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 TypeRT 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypeRTLookupMap` 声明。lookup 与 Context 包同时负责静态声明合并和运行时提供方注册，缺少任一侧都会在构建或最早可解析的运行时边界报错。
+严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 TypeRT 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypeRTLookupMap` 声明。lookup 与上下文包同时负责静态声明合并和运行时提供方注册，缺少任一侧都会在构建或最早可解析的运行时边界报错。
 
 ## 运行时调用
 
 当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
 
-Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和 request cancellation，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程界面。
+Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和请求取消，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。
 
-Gateway 每次调用都从当前注册表解析描述符和实时 Service，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context provider 解析对象或接收者，最后调用 binding 指向的 Service 方法并校验返回值。缺少 provider、identity 未命中、binding 不一致、参数多缺、schema 失败和方法不存在都在进入或离开业务边界时失败。
+Gateway 每次调用都从当前注册表解析描述符和当前有效的服务，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或上下文提供方解析对象或接收者，最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数多缺、schema 失败或方法不存在时，都会在边界处失败：要么发生在进入业务代码之前，要么发生在离开业务代码之后。
 
-lookup provider 的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有 provider 时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复 provider 默认策略。API Remotes 负责 `agent` 与 `session` 的标准 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。Web API Proxy 提供 Agent 默认值与 scope 设置，再让旧方法使用同一个 resolver。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
+lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有提供方时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复提供方默认策略。API Remotes 负责 `agent` 与 `session` 的标准 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。Web API Proxy 提供 Agent 默认值与 scope 设置，再让旧方法使用同一个 resolver。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
 
-Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
+Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的陈旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
 
 ## SRC 开发回退
 
 Host 通过 `node --import tsx/esm` 从源码启动时不会执行 TypeRT 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到模块私有 `WeakMap`，`GatewayService` 或 `bindTypeRTGateway()` 则提供显式 service binding；Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。
 
-SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host Context provider 的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
+SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host 上下文提供方的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
 
 SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client Remote 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。
 
 ## 开发模式
 
-完整构建会先生成 Host 契约，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
+完整构建会先生成 Host 约定产物，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
 
 ```sh
 pnpm run build
@@ -153,18 +153,18 @@ pnpm run dev:web
 
 `dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dshClient` 声明的 Client plugin 并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
 
-只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格契约，再让 Client 编译并打包新的贡献：
+只修改 Remote 方法实现体而不改变约定时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、上下文或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定产物，再让 Client 编译并打包新的贡献：
 
 ```sh
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 契约，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定产物，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净的 worktree不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
-Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
+Remote 只处理有单个请求与单个结果的一元方法调用。会话事件流、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务契约允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务约定允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
 
 当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 2436ff9027..c9279c45a8 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/architecture.md
 architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
-architecture.zh.md: 5780d54aad6085ef7811dfa94377a4c2478bfb99
+architecture.zh.md: 9a4fb8ec88ad93fa2d3f474ec4f2eb59b678216f
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 5780d54aad..9a4fb8ec88 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -6,7 +6,7 @@
 
 ## 概览
 
-每个 harness 都是 [Cordis](cordis-primer.md) 上下文；各包（package）贡献服务、类型化事件和可释放的注册项。`packages/core/` 汇集默认流程；各项功能仍以插件形式存在。
+每个 harness 都是 [Cordis](cordis-primer.md) 上下文；各包贡献服务、类型化事件和可释放的注册项。`packages/core/` 汇集默认流程；各项能力仍以插件形式存在。
 
 ### 默认服务
 
@@ -17,18 +17,18 @@
 | `ctx.systemPrompt` | `dsh-system-prompt` | 有序的提示词片段、工具 schema 和变量 |
 | `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | 活跃 agent（智能体）、委托创建、`agent/*` 事件、进程内发起方作用域 |
-| `ctx.agentLoop` | `dsh-agent-loop` | 实体 `Agent` 驱动器 |
+| `ctx.agentLoop` | `dsh-agent-loop` | 具体 `Agent` 驱动器 |
 
-### 功能服务
+### 能力服务
 
 | ctx 键 | 包族 | 职责 |
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
-| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
+| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的请求压力与表面压力 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
 | `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
-| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 通过 argv 包装和逐调用策略限制同一执行环境内的进程 |
+| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 通过 argv 包装和逐调用策略限制与宿主共享文件系统和内核的进程 |
 | `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | 共享沙箱策略归属点 |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | 执行模型编写的程序 |
 | `ctx.fs` | [`fs/`](../packages/fs/README.md) | 执行世界路径、有界 I/O 和策略事件 |
@@ -59,7 +59,7 @@
 
 - **会话事件**是通过 `session/event` 发出的持久日志事实。
 - **Agent 事件**携带活跃 `Agent`，用于 inbox、步骤、状态、请求、验证和续跑。
-- **功能事件**无需导入循环即可附加策略和适配器。
+- **能力事件**无需导入循环即可附加策略和适配器。
 
 ### 拦截语义
 
@@ -115,19 +115,19 @@ idle inject:
 
 `inject()` 将不会唤醒驱动器的上下文排入 `next-step`；空闲驱动器会让它保持待处理，直至 `followup()` 或 `steer()` 唤醒。工具执行后的 `additionalContexts` 使用同一个 inbox。`agent/pre-step` 的 payload 携带独占的已领取批次，以及即将使用的轮次、步骤和信号。拒绝则不进入步骤；进入则提供在 `step/start` 后追加的完整批次。空的工具续跑仍会经过 waterfall，其最终值一次性结算所有改写。
 
-裁剪先于摘要；溢出重试必须取得持久进展。`agent/request-error` 可以授权使用冻结提示词进行同步骤重试；取消优先。适配器的 `retryPolicy` 使 normal mode 保持有界，always mode 则在专门恢复后重试（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试基础](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)、[提供方策略](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)）。精确事件顺序由生成的 [agent 生命周期](agent-lifecycle.md)定义；队列、steering、重试与取消机制由 [agent-loop README](../packages/core/agent-loop/README.md)定义。
+裁剪先于摘要；溢出重试必须取得持久进展。`agent/request-error` 可以授权使用冻结提示词进行同步骤重试；取消优先。适配器的 `retryPolicy` 使 normal mode 保持有界，always mode 则在专门恢复后重试（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试基础](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)、[提供方策略](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)）。精确事件顺序由生成的 [agent 生命周期](agent-lifecycle.md)定义；队列、steering（中途引导）、重试与取消机制由 [agent-loop README](../packages/core/agent-loop/README.md)定义。
 
 ### 失败边界
 
 适配器选择、分发与迭代失败会成为 error 或 aborted 类型的终止 `finish` 分片。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用的重试策略和信号；middleware 与消费方错误仍在恢复之外。失败分片既不提交消息，也不提交工具调用。
 
-其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
+其他故障使用 `agent/error`；取消和 dispose（资源释放）优先于恢复。在提交请求头之前，轮次信号会取消能力准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久性以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
 轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap)。
 
 ### Agent 句柄
 
-`ctx.agents` 拥有 agent 并返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`，或使用其 `followup()`、`steer()` 和 `inject()` 预设。`cancel()` 与 `whenIdle()` 控制生命周期，需等待完成的资源释放则负责拆卸。后续消息的 `MessageId` 跟踪持久 inbox 的插入、领取与丢弃通知，而不标识提示词输出或轮次结束；只有完整活动区间的所有方才能将其概括为一次运行结果（[决策](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
+`ctx.agents` 拥有 agent 并返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`，或使用其 `followup()`、`steer()` 和 `inject()` 预设。`cancel()` 与 `whenIdle()` 控制生命周期，拆卸由需等待完成的 dispose 负责。后续消息的 `MessageId` 跟踪持久 inbox 的插入、领取与丢弃通知，而不标识提示词输出或轮次结束；只有完整活动区间的所有者才能将其概括为一次运行结果（[决策](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
 
 ### Agent 作用域
 
@@ -141,23 +141,23 @@ idle inject:
 
 **模型可见 ⟺ 已记录**：在 `step/start` 进入的消息加上折叠后的 `request/header` 可以重建每个请求。该 header 会标记适配器默认值，使后续提议丢弃这些值并重新解析路由，同时不丢失显式设置。`request/context` 会在路由变化时另行记录与注册项绑定的提供方、模型及容量元数据；它不参与请求重建或 header 相等性判断。`dsh-agent-loop/invariant` 通过 `ctx.invariants` 断言可重建性（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
 
-持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
+持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一约定（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
-在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
+在轮次之间，事件所有者通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
 ### 模型内容
 
 消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
-### 功能模式
+### 能力模式
 
-能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。
+能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[能力图](capability-seams.md)。
 
-例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
+例外情况包括 LLM（大语言模型）接口／消费方合并、文件系统策略、web 注册表，以及具名 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
 
 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
@@ -172,13 +172,13 @@ idle inject:
 | 目标 | 机制 |
 |---|---|
 | 添加模型提供方 | 在 `ctx.llm` 上注册其适配器 |
-| 添加面向模型的功能 | 在 `ctx.tools` 上注册；schema 加入提示词组装 |
-| 添加 shell 执行 | 实现并注册 `ctx.bash` 后端；本地后端通过 `ctx.subprocess` 生成进程 |
+| 添加面向模型的能力 | 在 `ctx.tools` 上注册；schema 加入提示词组装 |
+| 添加 shell 执行 | 实现并注册 `ctx.bash` 后端；本地后端通过 `ctx.subprocess` spawn 进程 |
 | 添加持久化终端执行 | 注册 `ctx.pty` 后端和 `dsh-tool-pty` |
 | 添加用户命令 | 在 `ctx.commands` 上注册；适配器无需模型轮次即可发现并分派 |
 | 添加后台工作 | 在 `ctx.tasks` 上注册；通用 `task_*` 工具负责收集或停止 |
 | 添加文件系统访问或策略 | 实现 `ctx.fs` 提供方，或监听 `fs/*` 策略事件 |
-| 限制生成的进程 | 使用 `ctx.sandbox` 后端；消费方在生成前包装 argv |
+| 限制 spawn 出的进程 | 使用 `ctx.sandbox` 后端；消费方在 spawn 前包装 argv |
 | 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stopping` 是停止边界 |
 | 添加模型可见上下文 | 调用 `agent.inject()`，将带来源的上下文排入下一次获准请求 |
 | 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
@@ -188,4 +188,4 @@ idle inject:
 | fork 活跃会话 | 调用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 将注册项限定到单个 agent | 使用其 `agent.ctx`（参见 Agent 作用域） |
 
-[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到服务边界的映射；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到 seam 的映射；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
new file mode 100644
index 0000000000..ca5caccff2
--- /dev/null
+++ b/docs/capability-seams.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 docs/capability-seams.md
+capability-seams.md: 4b46a6566ba795d89d6fdf7261c42574af286faf
+capability-seams.zh.md: 23f270c7463a45b5892ead8e34260b375a9fe3e5
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
new file mode 100644
index 0000000000..23f270c746
--- /dev/null
+++ b/docs/capability-seams.zh.md
@@ -0,0 +1,425 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/capability-seams.md` 重新记录配对。 -->
+
+# 能力 Seams 与核心服务
+
+[English](capability-seams.md) | 中文
+
+服务可以是核心主干服务、可替换的能力 seam，也可以是组合包／组合点。下图展示了拥有服务声明的包、已知实现包，以及直接消费该服务的包。
+
+```mermaid
+flowchart LR
+  pkg_llm["llm"]
+  svc_llm["ctx.llm<br/>LLM adapter registry"]
+  pkg_llm_deepseek["llm-deepseek"]
+  pkg_llm_pi_ai["llm-pi-ai"]
+  pkg_llm_replay["llm-replay"]
+  pkg_agent_loop["agent-loop"]
+  pkg_compact_basic["compact-basic"]
+  pkg_token_meter["token-meter"]
+  svc_tokenMeter["ctx.tokenMeter<br/>Replay token measurement"]
+  pkg_compact_tool_result_prune["compact-tool-result-prune"]
+  svc_toolResultPrune["ctx.toolResultPrune<br/>Model-free tool-result pruning"]
+  pkg_session["session"]
+  svc_sessions["ctx.sessions<br/>In-memory session store"]
+  pkg_agent["agent"]
+  pkg_session_persistence["session-persistence"]
+  pkg_session_query["session-query"]
+  pkg_session_query_sqlite["session-query-sqlite"]
+  pkg_subagent_inprocess["subagent-inprocess"]
+  pkg_invariants["invariants"]
+  svc_invariants["ctx.invariants<br/>Package-owned invariant registry"]
+  pkg_scope["scope"]
+  pkg_typert_registry["typert-registry"]
+  svc_typert["ctx.typert<br/>Runtime type registry"]
+  pkg_typert_loader["typert-loader"]
+  pkg_api_gateway["api-gateway"]
+  svc_typertGateway["ctx.typertGateway<br/>TypeRT Host invocation gateway"]
+  svc_sessionPersistence["ctx.sessionPersistence<br/>Durable session persistence seam"]
+  pkg_session_persistence_jsonl["session-persistence-jsonl"]
+  pkg_session_persistence_sqlite["session-persistence-sqlite"]
+  pkg_tool_bash["tool-bash"]
+  pkg_hooks_claude["hooks-claude"]
+  pkg_hooks_codex["hooks-codex"]
+  pkg_settings["settings"]
+  svc_settings["ctx.settings<br/>User-settings seam"]
+  pkg_settings_local["settings-local"]
+  pkg_apiproxy["apiproxy"]
+  pkg_credentials["credentials"]
+  svc_credentials["ctx.credentials<br/>Credential seam"]
+  pkg_credentials_local["credentials-local"]
+  pkg_session_telemetry["session-telemetry"]
+  svc_telemetry["ctx.telemetry<br/>Session telemetry seam"]
+  pkg_session_telemetry_otel["session-telemetry-otel"]
+  pkg_storage["storage"]
+  svc_storage["ctx.storage<br/>Non-session storage hub"]
+  pkg_storage_json["storage-json"]
+  pkg_storage_sqlite["storage-sqlite"]
+  pkg_storage_domain["storage-domain"]
+  svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
+  pkg_workspace["workspace"]
+  svc_workspace["ctx.workspace<br/>Workspace entity registry"]
+  svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
+  pkg_session_reference["session-reference"]
+  pkg_tool_session_query["tool-session-query"]
+  svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
+  pkg_session_title["session-title"]
+  svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
+  pkg_session_title_first_message_llm["session-title-first-message-llm"]
+  pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+  pkg_system_prompt["system-prompt"]
+  svc_systemPrompt["ctx.systemPrompt<br/>System prompt assembly registry"]
+  pkg_tools["tools"]
+  pkg_tool_fs["tool-fs"]
+  pkg_tool_pty["tool-pty"]
+  pkg_tool_web["tool-web"]
+  svc_tools["ctx.tools<br/>Tool registry and guarded execution pipeline"]
+  pkg_tool_ask_user["tool-ask-user"]
+  pkg_tool_cordis["tool-cordis"]
+  pkg_tool_skill["tool-skill"]
+  pkg_tool_subagent["tool-subagent"]
+  pkg_tool_todo["tool-todo"]
+  pkg_user_interaction["user-interaction"]
+  svc_userInteraction["ctx.userInteraction<br/>Human question/answer seam"]
+  pkg_plan_mode["plan-mode"]
+  svc_planMode["ctx.planMode<br/>Plan collaboration state"]
+  pkg_commands["commands"]
+  svc_commands["ctx.commands<br/>Human command registry"]
+  pkg_session_projection["session-projection"]
+  svc_sessionProjections["ctx.sessionProjections<br/>Session projection units"]
+  pkg_host_apiproxy["host-apiproxy"]
+  pkg_session_projection_cache["session-projection-cache"]
+  svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
+  pkg_skill["skill"]
+  svc_skills["ctx.skills<br/>Skill provider registry"]
+  pkg_skill_badge["skill-badge"]
+  pkg_skill_local["skill-local"]
+  svc_agents["ctx.agents<br/>Agent service"]
+  pkg_acp["acp"]
+  svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
+  pkg_agent_spine_demo["agent-spine-demo"]
+  pkg_goal["goal"]
+  svc_goals["ctx.goals<br/>Same-session goal domain"]
+  pkg_e2b["e2b"]
+  svc_e2b["ctx.e2b<br/>E2B sandbox lifecycle owner"]
+  pkg_fs_e2b["fs-e2b"]
+  pkg_subprocess_e2b["subprocess-e2b"]
+  pkg_subprocess["subprocess"]
+  svc_subprocess["ctx.subprocess<br/>Subprocess seam"]
+  pkg_subprocess_local["subprocess-local"]
+  pkg_bash_local["bash-local"]
+  pkg_bash_sandbox["bash-sandbox"]
+  pkg_pty_local["pty-local"]
+  pkg_lsp_local["lsp-local"]
+  pkg_subagent_acp["subagent-acp"]
+  pkg_subagent_codex["subagent-codex"]
+  pkg_subagent_claude_code["subagent-claude-code"]
+  pkg_bash["bash"]
+  svc_bash["ctx.bash<br/>Bash executor seam"]
+  pkg_pwsh_local["pwsh-local"]
+  pkg_tool_pwsh["tool-pwsh"]
+  pkg_bash_env["bash-env"]
+  svc_bashEnv["ctx.bashEnv<br/>Managed bash environment registry"]
+  pkg_pty["pty"]
+  svc_pty["ctx.pty<br/>Persistent PTY session registry"]
+  pkg_sandbox["sandbox"]
+  svc_sandbox["ctx.sandbox<br/>Process-sandbox seam"]
+  pkg_sandbox_local["sandbox-local"]
+  pkg_sandbox_policy["sandbox-policy"]
+  svc_sandboxPolicy["ctx.sandboxPolicy<br/>Sandbox policy home"]
+  pkg_fs_sandbox["fs-sandbox"]
+  pkg_approval["approval"]
+  svc_approval["ctx.approval<br/>Approval seam"]
+  pkg_permission["permission"]
+  svc_permission["ctx.permission<br/>Permission presets"]
+  pkg_code_runtime["code-runtime"]
+  svc_codeRuntime["ctx.codeRuntime<br/>Code-execution seam"]
+  pkg_code_runtime_worker["code-runtime-worker"]
+  pkg_fs["fs"]
+  svc_fs["ctx.fs<br/>Filesystem provider seam"]
+  pkg_fs_local["fs-local"]
+  pkg_fs_policy["fs-policy"]
+  pkg_compact["compact"]
+  svc_compact["ctx.compact<br/>Compaction seam"]
+  pkg_subagent["subagent"]
+  svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
+  pkg_subagent_spawn["subagent-spawn"]
+  pkg_subagent_fork["subagent-fork"]
+  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
+  pkg_tool_subagent_control["tool-subagent-control"]
+  pkg_tool_ralph["tool-ralph"]
+  pkg_tasks["tasks"]
+  svc_tasks["ctx.tasks<br/>Background task registry"]
+  pkg_tasks_local["tasks-local"]
+  pkg_tool_tasks["tool-tasks"]
+  pkg_web["web"]
+  svc_web["ctx.web<br/>Web access provider registry"]
+  pkg_web_search_exa["web-search-exa"]
+  pkg_web_search_perplexity["web-search-perplexity"]
+  pkg_web_search_deepseek["web-search-deepseek"]
+  pkg_web_fetch_local["web-fetch-local"]
+  pkg_spill["spill"]
+  svc_spillStore["ctx.spillStore<br/>Spill storage seam"]
+  pkg_spill_local["spill-local"]
+  pkg_spill_policy["spill-policy"]
+  pkg_directory_picker["directory-picker"]
+  svc_directoryPicker["ctx.directoryPicker<br/>Workspace-directory picking seam"]
+  pkg_directory_picker_native["directory-picker-native"]
+  pkg_directory_picker_browse["directory-picker-browse"]
+  pkg_webserver["webserver"]
+  svc_httpServer["ctx.httpServer<br/>HTTP route registration"]
+  pkg_connection["connection"]
+  pkg_modules["modules"]
+  pkg_hmr["hmr"]
+  svc_clientModuleHost["ctx.clientModuleHost<br/>Client plugin graph host"]
+  pkg_workflow["workflow"]
+  svc_workflows["ctx.workflows<br/>Workflow script engine"]
+  pkg_workflow_workerthread["workflow-workerthread"]
+  pkg_tool_workflow["tool-workflow"]
+  pkg_acp --> svc_approval
+  pkg_agent --> svc_agents
+  pkg_agent_loop --> svc_agentLoop
+  pkg_api_gateway --> svc_typertGateway
+  pkg_approval --> svc_approval
+  pkg_bash --> svc_bash
+  pkg_bash_env --> svc_bashEnv
+  pkg_bash_local --> svc_bash
+  pkg_bash_sandbox --> svc_bash
+  pkg_code_runtime --> svc_codeRuntime
+  pkg_code_runtime_worker --> svc_codeRuntime
+  pkg_commands --> svc_commands
+  pkg_compact --> svc_compact
+  pkg_compact_basic --> svc_compact
+  pkg_compact_tool_result_prune --> svc_toolResultPrune
+  pkg_credentials --> svc_credentials
+  pkg_credentials_local --> svc_credentials
+  pkg_directory_picker --> svc_directoryPicker
+  pkg_directory_picker_browse --> svc_directoryPicker
+  pkg_directory_picker_native --> svc_directoryPicker
+  pkg_e2b --> svc_e2b
+  pkg_fs --> svc_fs
+  pkg_fs_e2b --> svc_fs
+  pkg_fs_local --> svc_fs
+  pkg_fs_sandbox --> svc_fs
+  pkg_goal --> svc_goals
+  pkg_invariants --> svc_invariants
+  pkg_llm --> svc_llm
+  pkg_llm_deepseek --> svc_llm
+  pkg_llm_pi_ai --> svc_llm
+  pkg_llm_replay --> svc_llm
+  pkg_modules --> svc_clientModuleHost
+  pkg_permission --> svc_permission
+  pkg_plan_mode --> svc_planMode
+  pkg_pty --> svc_pty
+  pkg_pty_local --> svc_pty
+  pkg_pwsh_local --> svc_bash
+  pkg_sandbox --> svc_sandbox
+  pkg_sandbox_local --> svc_sandbox
+  pkg_sandbox_policy --> svc_sandboxPolicy
+  pkg_session --> svc_sessions
+  pkg_session_persistence --> svc_sessionPersistence
+  pkg_session_persistence_jsonl --> svc_sessionPersistence
+  pkg_session_persistence_sqlite --> svc_sessionPersistence
+  pkg_session_projection --> svc_sessionProjections
+  pkg_session_projection_cache --> svc_sessionProjectionCache
+  pkg_session_query --> svc_sessionQuery
+  pkg_session_query_sqlite --> svc_sessionQuery
+  pkg_session_reference --> svc_sessionReferences
+  pkg_session_telemetry --> svc_telemetry
+  pkg_session_telemetry_otel --> svc_telemetry
+  pkg_session_title --> svc_sessionTitle
+  pkg_session_title_all_messages_llm --> svc_sessionTitle
+  pkg_session_title_first_message_llm --> svc_sessionTitle
+  pkg_settings --> svc_settings
+  pkg_settings_local --> svc_settings
+  pkg_skill --> svc_skills
+  pkg_skill_badge --> svc_skills
+  pkg_skill_local --> svc_skills
+  pkg_spill --> svc_spillStore
+  pkg_spill_local --> svc_spillStore
+  pkg_storage --> svc_storage
+  pkg_storage_domain --> svc_storageDomain
+  pkg_storage_json --> svc_storage
+  pkg_storage_sqlite --> svc_storage
+  pkg_subagent --> svc_subagents
+  pkg_subagent_acp --> svc_subagents
+  pkg_subagent_claude_code --> svc_subagents
+  pkg_subagent_codex --> svc_subagents
+  pkg_subagent_dsh_sdk --> svc_subagents
+  pkg_subagent_fork --> svc_subagents
+  pkg_subagent_spawn --> svc_subagents
+  pkg_subprocess --> svc_subprocess
+  pkg_subprocess_e2b --> svc_subprocess
+  pkg_subprocess_local --> svc_subprocess
+  pkg_system_prompt --> svc_systemPrompt
+  pkg_tasks --> svc_tasks
+  pkg_tasks_local --> svc_tasks
+  pkg_token_meter --> svc_tokenMeter
+  pkg_tools --> svc_tools
+  pkg_typert_registry --> svc_typert
+  pkg_user_interaction --> svc_userInteraction
+  pkg_web --> svc_web
+  pkg_web_fetch_local --> svc_web
+  pkg_web_search_deepseek --> svc_web
+  pkg_web_search_exa --> svc_web
+  pkg_web_search_perplexity --> svc_web
+  pkg_webserver --> svc_httpServer
+  pkg_workflow --> svc_workflows
+  pkg_workflow_workerthread --> svc_workflows
+  pkg_workspace --> svc_workspace
+  svc_agentLoop --> pkg_agent_spine_demo
+  svc_agents --> pkg_acp
+  svc_agents --> pkg_agent_loop
+  svc_agents --> pkg_subagent_inprocess
+  svc_approval --> pkg_tool_bash
+  svc_approval --> pkg_tools
+  svc_bash --> pkg_hooks_claude
+  svc_bash --> pkg_hooks_codex
+  svc_bash --> pkg_tool_bash
+  svc_bash --> pkg_tool_pwsh
+  svc_bashEnv --> pkg_tool_bash
+  svc_bashEnv --> pkg_tool_pwsh
+  svc_clientModuleHost --> pkg_hmr
+  svc_codeRuntime --> pkg_tools
+  svc_compact --> pkg_compact_basic
+  svc_credentials --> pkg_apiproxy
+  svc_credentials --> pkg_llm_deepseek
+  svc_credentials --> pkg_llm_pi_ai
+  svc_directoryPicker --> pkg_apiproxy
+  svc_e2b --> pkg_fs_e2b
+  svc_e2b --> pkg_subprocess_e2b
+  svc_fs --> pkg_tool_fs
+  svc_httpServer --> pkg_connection
+  svc_httpServer --> pkg_hmr
+  svc_httpServer --> pkg_modules
+  svc_invariants --> pkg_agent
+  svc_invariants --> pkg_agent_loop
+  svc_invariants --> pkg_scope
+  svc_invariants --> pkg_session
+  svc_llm --> pkg_agent_loop
+  svc_llm --> pkg_compact_basic
+  svc_pty --> pkg_tool_pty
+  svc_sandbox --> pkg_bash_sandbox
+  svc_sandbox --> pkg_pty_local
+  svc_sandboxPolicy --> pkg_bash_sandbox
+  svc_sandboxPolicy --> pkg_fs_sandbox
+  svc_sandboxPolicy --> pkg_pty_local
+  svc_sessionPersistence --> pkg_agent_loop
+  svc_sessionPersistence --> pkg_hooks_claude
+  svc_sessionPersistence --> pkg_hooks_codex
+  svc_sessionPersistence --> pkg_session_query
+  svc_sessionPersistence --> pkg_session_query_sqlite
+  svc_sessionPersistence --> pkg_tool_bash
+  svc_sessionProjectionCache --> pkg_host_apiproxy
+  svc_sessionProjections --> pkg_host_apiproxy
+  svc_sessionProjections --> pkg_session_title
+  svc_sessionProjections --> pkg_tool_todo
+  svc_sessionQuery --> pkg_session_reference
+  svc_sessionQuery --> pkg_tool_session_query
+  svc_sessions --> pkg_agent
+  svc_sessions --> pkg_agent_loop
+  svc_sessions --> pkg_invariants
+  svc_sessions --> pkg_session_persistence
+  svc_sessions --> pkg_session_query
+  svc_sessions --> pkg_session_query_sqlite
+  svc_sessions --> pkg_subagent_inprocess
+  svc_settings --> pkg_apiproxy
+  svc_settings --> pkg_llm_deepseek
+  svc_settings --> pkg_llm_pi_ai
+  svc_skills --> pkg_tool_skill
+  svc_spillStore --> pkg_spill_policy
+  svc_storage --> pkg_storage_domain
+  svc_storageDomain --> pkg_workspace
+  svc_subagents --> pkg_tool_ralph
+  svc_subagents --> pkg_tool_subagent
+  svc_subagents --> pkg_tool_subagent_control
+  svc_subprocess --> pkg_bash_local
+  svc_subprocess --> pkg_bash_sandbox
+  svc_subprocess --> pkg_lsp_local
+  svc_subprocess --> pkg_pty_local
+  svc_subprocess --> pkg_subagent_acp
+  svc_subprocess --> pkg_subagent_claude_code
+  svc_subprocess --> pkg_subagent_codex
+  svc_systemPrompt --> pkg_agent_loop
+  svc_systemPrompt --> pkg_tool_fs
+  svc_systemPrompt --> pkg_tool_pty
+  svc_systemPrompt --> pkg_tool_web
+  svc_systemPrompt --> pkg_tools
+  svc_tasks --> pkg_tool_bash
+  svc_tasks --> pkg_tool_pty
+  svc_tasks --> pkg_tool_subagent
+  svc_tasks --> pkg_tool_tasks
+  svc_tokenMeter --> pkg_compact_basic
+  svc_toolResultPrune --> pkg_compact_basic
+  svc_tools --> pkg_agent_loop
+  svc_tools --> pkg_tool_ask_user
+  svc_tools --> pkg_tool_bash
+  svc_tools --> pkg_tool_cordis
+  svc_tools --> pkg_tool_fs
+  svc_tools --> pkg_tool_pty
+  svc_tools --> pkg_tool_skill
+  svc_tools --> pkg_tool_subagent
+  svc_tools --> pkg_tool_todo
+  svc_tools --> pkg_tool_web
+  svc_typert --> pkg_api_gateway
+  svc_typert --> pkg_typert_loader
+  svc_userInteraction --> pkg_tool_ask_user
+  svc_web --> pkg_tool_web
+  svc_workflows --> pkg_tool_ralph
+  svc_workflows --> pkg_tool_workflow
+  svc_workspace --> pkg_apiproxy
+  svc_fs -. event gate .-> pkg_fs_policy
+```
+
+| ctx 键 | 角色 | 所属包 | 实现 | 直接消费方 | 配套插件 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek)、[`llm-pi-ai`](../packages/llm/llm-pi-ai)、[`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop)、[`compact-basic`](../packages/compact/compact-basic) | - | 适配器注册提供方实现；agent loop（智能体循环）与压缩功能调用提供方无关的流服务。 |
+| `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | 拥有按会话隔离的回放折叠区；压力消费方共享不可变且带修订版本的测量结果。 |
+| `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | 在摘要压缩前，通过可回放的单节点表层替换来改写过大的当前工具结果。 |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop)、[`agent`](../packages/core/agent)、[`session-persistence`](../packages/session/session-persistence)、[`session-query`](../packages/session-query/session-query)、[`session-query-sqlite`](../packages/session-query/session-query-sqlite)、[`subagent-inprocess`](../packages/subagent/subagent-inprocess)、[`invariants`](../packages/support/invariants) | - | 拥有仅追加的 Session 实例，并发出持久的会话事件流。 |
+| `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session)、[`agent`](../packages/core/agent)、[`scope`](../packages/core/scope)、[`agent-loop`](../packages/core/agent-loop) | - | 配套子路径注册所属包本地的检查；该服务负责选择、唯一性、子 fiber，以及标明所属包的失败。 |
+| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader)、[`api-gateway`](../packages/api/gateway) | - | 插件直接或通过 dsh-typert-loader 注册实时 zod 贡献；API 网关消费调用描述符和提供方，其他运行时消费方则在各自边界查询 schema 与反射元数据。 |
+| `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | 将生成的 Remote 描述符与实时 Cordis 服务关联，解析已注册的身份，并通过共享的 Connection RPC 载体提供一元调用。 |
+| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl)、[`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop)、[`tool-bash`](../packages/bash/tool-bash)、[`hooks-claude`](../packages/hooks/hooks-claude)、[`hooks-codex`](../packages/hooks/hooks-codex)、[`session-query`](../packages/session-query/session-query)、[`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | 各后端持久化同一套 SessionEvent 词汇；应用在组合时选择后端。 |
+| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek)、[`llm-pi-ai`](../packages/llm/llm-pi-ai)、`apiproxy` | - | 插件注册命名空间 schema 并解析分层值；提供方存储原始文档。LLM（大语言模型）适配器在用户分区下将其入口配置注册为组合基础；Web 网关提供经过脱敏的分层描述符，并写入用户层。 |
+| `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek)、[`llm-pi-ai`](../packages/llm/llm-pi-ai)、`apiproxy` | - | 配置携带对机密信息的引用；提供方拥有实际值。消费方按操作解析，因此轮换后的凭据会在紧接着的下一次请求中生效；Web 网关提供不含实际值的视图和只写存储。 |
+| `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | 该 seam 捕获会话记录、进行脱敏并交给一个后端；没有其他组件消费该服务，其输出会离开当前进程。 |
+| `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json)、[`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | 各后端以不同名称并列注册；数据形态（领域优先）挂载到枢纽上，并将类型化操作转换为不透明的 KV 单元原语。 |
+| `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 |
+| `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | 通过领域设施拥有带 WorkspaceId 品牌类型的记录；稳定的 sessionIds 账户驱动 Host RPC 与 GUI 投影。 |
+| `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference)、[`tool-session-query`](../packages/session-query/tool-session-query) | - | 该接口提供精确读取、过滤和追踪；具体后端还提供全文协调、排序、摘要片段和游标世代，而模型消费方负责工作区权限与不含游标的渲染。 |
+| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | 将当前表层中有界的对话快照投影为持久但不可信的消息上下文；Host 适配器负责提及语法。 |
+| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm)、[`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | 负责确定性回退、最新标题折叠区，以及唯一的可选异步提供方注册。 |
+| `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop)、[`tools`](../packages/core/tools)、[`tool-fs`](../packages/fs/tool-fs)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-web`](../packages/web/tool-web) | - | 为每个步骤收集提示词各部分和面向模型的工具 schema。 |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop)、[`tool-ask-user`](../packages/interaction/tool-ask-user)、[`tool-bash`](../packages/bash/tool-bash)、[`tool-cordis`](../packages/self-modification/tool-cordis)、[`tool-fs`](../packages/fs/tool-fs)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-skill`](../packages/skill/tool-skill)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-todo`](../packages/todo/tool-todo)、[`tool-web`](../packages/web/tool-web) | - | 注册能力，负责 Code Mode 传输，并让调用依次经过策略前处理、单调守卫、环绕分派、策略后处理和最终结果观测。 |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/interaction/user-interaction) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI 入口提供当前生效的人工回答提供方；tool-ask-user 在提供方无关的 ask() promise 上暂停工具调用。 |
+| `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | 折叠已记录的计划／模式状态，在轮次边界刷新用户选择，渲染由部署方拥有的指导信息，注册 /plan，并在状态转换期间保持计划退出 schema 稳定。 |
+| `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | 插件注册直接面向人的命令，而不会把调用发送给模型。 |
+| `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo)、[`session-title`](../packages/session/session-title)、[`host-apiproxy`](../packages/host/apiproxy) | - | 各领域注册由状态驱动的折叠单元；主动驱动过程维护每个会话的水位状态，api-proxy 提供基线并推送发生变化的值。 |
+| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | 按会话持久保存投影单元状态的检查点（节流检查点，以及轮次／结束／分离时的必选检查点），并提供冷读取阶梯：缓存行加持久化尾部回放，因此列表读取永远不需要加载完整日志。 |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge)、[`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | 合并提供方的 skill（技能）目录；tool-skill 渲染会话前缀目录，并加载完整的 skill 正文。 |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop)、[`acp`](../packages/acp/acp)、[`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | 拥有实时 Agent 句柄、创建／恢复工厂 seam，以及进程本地的发起方传播。 |
+| `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | 唯一的具体循环插件；扩展包依赖 dsh-agent 的事件和服务，而不依赖此包。 |
+| `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | 从会话日志折叠带修订版本的目标状态，并将实时延续激活保留在进程本地。 |
+| `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b)、[`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | 拥有一个共享的 E2B SDK 句柄、远程工作目录和最终沙箱处置，使两个基础 E2B 提供方处于同一个 Linux 运行时中。 |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local)、[`subprocess-e2b`](../packages/e2b/subprocess-e2b) | [`bash-local`](../packages/bash/bash-local)、[`bash-sandbox`](../packages/bash/bash-sandbox)、[`pty-local`](../packages/pty/pty-local)、[`lsp-local`](../packages/lsp/lsp-local)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | Bash 执行器、PTY shell 后端、LSP Host，以及进程外 ACP、Codex 和 Claude Code subagent 后端都通过 ctx.subprocess 执行 spawn；该服务负责进程坐标、进程树／会话生命周期、stdio 处置、终端机制和 kill 升级。 |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local)、[`bash-sandbox`](../packages/bash/bash-sandbox)、[`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pwsh`](../packages/bash/tool-pwsh)、[`hooks-claude`](../packages/hooks/hooks-claude)、[`hooks-codex`](../packages/hooks/hooks-codex) | - | 面向模型的 shell 工具和钩子桥接消费此 seam；沙箱、远程或 PowerShell 执行器可以替换 bash-local，而无需改动这些消费方。 |
+| `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pwsh`](../packages/bash/tool-pwsh) | - | 插件声明限定于 effect 作用域的 DSH_* 事实；每个 shell 工具在每次执行时收集一份可信快照，其执行器据此重建命名空间。 |
+| `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | 注册表负责精确到 Agent 的会话身份和清理；后端负责终端机制，tool-pty 则提供限定于所有者作用域的模型接口。 |
+| `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox)、[`pty-local`](../packages/pty/pty-local) | - | 消费方交出即将执行 spawn 的确切 argv；与宿主共享文件系统和内核的后端按每次调用的策略包装该 argv，并报告强制执行情况。 |
+| `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`pty-local`](../packages/pty/pty-local) | - | 统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取该服务（工具层使用它同时导出的纯 `sandbox/mode` 折叠区）。两类强制执行组件都读取该服务，因此 bash 与 fs 不会限制到不同的根目录。 |
+| `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools)、[`tool-bash`](../packages/bash/tool-bash) | - | 一次性权限决策通过 `approval/request` waterfall（瀑布式事件）分派；回答方是监听器（即 ACP 为自身 agent 提供的桥接），没有回答方时以 `unavailable` 关闭失败。 |
+| `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 |
+| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 Code Mode 下消费该服务）。 |
+| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；面向模型的压缩工具仍处于暂缓状态。 |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn)、[`subagent-fork`](../packages/subagent/subagent-fork)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code)、[`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-subagent-control`](../packages/subagent/tool-subagent-control)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |
+| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制接口，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 |
+| `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa)、[`web-search-perplexity`](../packages/web/web-search-perplexity)、[`web-search-deepseek`](../packages/web/web-search-deepseek)、[`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 |
+| `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本，并返回面向模型的定位信息和取回提示；spill-policy 是 tools/post-execute 消费方，负责决定何时 spill。 |
+| `ctx.directoryPicker` | `seam` | `directory-picker` | `directory-picker-native`、`directory-picker-browse` | `apiproxy` | - | 带判别标记的交互能力：原生后端在 Host 显示设备上打开一个操作系统选择器，浏览后端为应用内浏览器提供列表与创建原语；双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot（不通过协议发布）。 |
+| `ctx.httpServer` | `core` | `webserver` | - | `connection`、`modules`、`hmr` | - | 普通的 node:http 载体：具名路由注册表、索引转换 tap，以及静态 dist 回退；Web 传输插件注册自己的路由。 |
+| `ctx.clientModuleHost` | `core` | `modules` | - | `hmr` | - | 通过增量 dshClient 扫描组合 __DSH_BOOT__ 入口图，提供插件组合包，并通知重建／图变更订阅方。 |
+| `ctx.workflows` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | [`tool-workflow`](../packages/workflow/tool-workflow)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 每个上下文使用一个引擎（bash 形态，无具名提供方注册表）；通用工作流与固定 Ralph 消费方启动运行，其中的 agent() 调用通过 ctx.subagents 扇出。 |
+
+维护模式：混合模式。服务从 Cordis 声明中发现；接口、实现和消费方角色在 `scripts/gen-doc-graphs.ts` 中分类，并设有完整性守卫。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
new file mode 100644
index 0000000000..bff77bc092
--- /dev/null
+++ b/docs/config-catalog.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 docs/config-catalog.md
+config-catalog.md: eb4472d629e41f154384549245ecce1c8ec266e2
+config-catalog.zh.md: 42c1f6e85c416c68f18b8b2976300dec7e32dbc4
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
new file mode 100644
index 0000000000..42c1f6e85c
--- /dev/null
+++ b/docs/config-catalog.zh.md
@@ -0,0 +1,2684 @@
+<!-- 英文源文件由 scripts/gen-config-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-config-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/config-catalog.md` 重新记录配对。 -->
+
+# 插件配置目录
+
+[English](config-catalog.md) | 中文
+
+`cordis.yml` 条目可以设置的每个 `config:` 块：针对每个可加载的运行框架包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.md)，而 [subsystems/](subsystems/core.md) 则记录了这些声明所引用的类型。
+
+英文源文件由源代码（`scripts/gen-config-catalog.ts`）生成，并通过 `pnpm run verify-config-catalog`（`doc-sync` 的一部分）验证为最新；本中文文件作为经评审对侧通过双语配对维护。声明块使用 `ts config-catalog` 围栏（doc-typecheck 会跳过它，因为单独引用导入项的声明无法独立编译）。英文生成器还会将运行时 schemastery schema 与粘贴的声明进行交叉核对——每个经 schema 验证的键（包括嵌套键）都必须能在声明的配置类型中找到——因此，粘贴内容无法隐藏加载器接受的字段。
+
+`Requires:` 行列出插件通过 `inject` 注入的服务键：其 `cordis.yml` 树还必须加载这些服务的提供者。范围限定为运行框架层级（`packages/`）；配置树还可能加载的 vendored cordis 插件（`hmr`、控制台日志记录器等）固定为上游源代码（参见 [vendoring policy](../vendor/README.md)），未收录于此目录。
+
+## `@deepseek-ai/dsh-acp`
+
+需要：`agents`
+
+```ts config-catalog
+/** Plugin config: the provider/model target used for each ACP-created agent. */
+export interface AcpConfig {
+  /** Provider route for created agents. */
+  provider?: string
+  /** Model name for created agents. */
+  model?: string
+  /** Runtime-only transport override; production uses stdio. */
+  stream?: Stream
+}
+```
+
+依赖：`Stream`（`@agentclientprotocol/sdk`）
+
+来源：[`packages/acp/acp/src/index.ts:70`](../packages/acp/acp/src/index.ts)
+
+## `@deepseek-ai/dsh-acp-demo`
+
+```ts config-catalog
+/**
+ * App config: the swappable per-deployment values. `provider` and `model` configure
+ * each agent the ACP bridge creates at `session/new`; `persona` is the
+ * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
+ * the explicit model-facing tool order (forwarded to the system-prompt plugin);
+ * `tools` is the tool registry's config (its presentation `mode`, forwarded
+ * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
+ */
+export interface Config {
+  /** Provider route for ACP-created agents. */
+  provider: string
+  /** Model name for ACP-created agents (must have a registered adapter). */
+  model: string
+  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
+  maxParallelToolCalls?: number
+  /** Deployment persona (the system-prompt plugin's `persona` config). */
+  persona?: string
+  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
+  toolOrder?: string[]
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
+  tools?: ToolsConfig
+  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
+  dshHome?: string
+  /** Fallback session-title limits forwarded through agent-spine-demo. */
+  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /** Write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`). Defaults to `true`. */
+  packChunks?: boolean
+  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
+  persistenceCompression?: JsonlCompression
+  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
+  workspaceContext: agentCore.Config['workspaceContext']
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
+  skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
+  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
+  goals?: agentCore.GoalConfig | false
+}
+```
+
+依赖：[`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+
+来源：[`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
+
+## `@deepseek-ai/dsh-agent-loop`
+
+需要：`agents` · `sessions` · `llm` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Agent-loop plugin configuration. */
+export interface Config {
+  /**
+   * Maximum parallel-safe calls in flight per agent step. `1` is serial;
+   * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}.
+   */
+  maxParallelToolCalls?: number
+  /** Agents created or resumed at plugin startup. */
+  agents: (AgentOptions & {
+    /** Stable config label used in logs and as the fresh combined-id prefix. */
+    id: string
+    /** Optional stable identity; remounts resume its materialized history, while first use creates it fresh. */
+    sessionId?: SessionId
+    /** Optional workspace for a fresh session. */
+    cwd?: string
+    /** Persisted session to resume instead of creating a fresh session. */
+    resumeSessionId?: SessionId
+  })[]
+}
+```
+
+依赖：[`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md)
+
+来源：[`packages/core/agent-loop/src/index.ts:236`](../packages/core/agent-loop/src/index.ts)
+
+## `@deepseek-ai/dsh-agent-spine-demo`
+
+```ts config-catalog
+/**
+ * Bundle config: each field forwarded verbatim to the child that owns it —
+ * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
+ * bridge, simply omits it), `includeHarnessIdentity`, `persona`, and `toolOrder`
+ * to the system-prompt plugin (the fixed opener, deployment persona, and explicit
+ * model-facing tool order), the `tools` object to the tool registry (its presentation `mode`),
+ * `dshHome` to bash environment and local skill discovery, `sessionTitle` to
+ * the fallback title service, `skills` to the
+ * skill registry/local provider/tool consumer, `workspaceContext` to the
+ * workspace-context loader, and `toolBash`/`toolTasks` to the model-facing tool
+ * plugins this bundle owns. Provider adapters own their `retryPolicy`; this
+ * bundle always mounts its executor.
+ * `goals` opts into and configures the persisted goal domain plus its model tool
+ * and same-session driver; `invariants` configures global and package-filtered
+ * relational checks. Owner schemas supply defaults for optional input;
+ * workspace context instead requires an explicit byte budget or `false` because
+ * it changes model-visible input. Producer opt-in stays producer-local:
+ * `toolBash` configures bash only; independently composed producers keep their
+ * own config. Set `toolBash: false` when another plugin owns the model-facing
+ * `bash` name.
+ */
+export interface Config {
+  /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
+  agents?: AgentLoopConfig['agents']
+  /** Agent-loop concurrency cap; `1` is serial. */
+  maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
+  /** Whether the system prompt includes the fixed Harness identity (default true). */
+  includeHarnessIdentity?: SystemPromptConfig['includeHarnessIdentity']
+  /** The deployment persona (see dsh-system-prompt's `Config`). */
+  persona?: SystemPromptConfig['persona']
+  /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
+  toolOrder?: SystemPromptConfig['toolOrder']
+  /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */
+  tools?: ToolsConfig
+  /** DeepSeek Harness home directory shared by shell context and local skill discovery. */
+  dshHome?: string
+  /** Deterministic fallback and accepted-title limits; omission uses the bundle's example policy. */
+  sessionTitle?: SessionTitleConfig
+  /** Workspace-context loader controls with an explicit byte budget; set `false` for hermetic prompts. */
+  workspaceContext: workspaceContext.Config | false
+  /**
+   * Skill registry, local provider, and model-facing consumer config.
+   * Skills use `enabled` because one nested config controls a provider stack;
+   * single model-tool plugins use `Config | false` to disable that one consumer.
+   */
+  skills?: SkillConfig
+  /** Model-facing bash tool config, or false when another plugin owns `bash`. */
+  toolBash?: toolBash.Config | false
+  /** Generic background-task controls; set false to keep the task service without model-facing task tools. */
+  toolTasks?: toolTasks.Config | false
+  /** Global enablement and package-name filters for invariant companions. */
+  invariants?: InvariantConfig
+  /** Opt-in persisted same-session goal stack; set false or omit to leave it unmounted. */
+  goals?: GoalConfig | false
+}
+
+/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
+export interface SkillConfig {
+  /** Mount the bundled local skill provider and model-facing skill tool (default true). */
+  enabled?: boolean
+  /** Registry-level discovery cache settings. */
+  registry?: SkillRegistryConfig
+  /** Local filesystem skill provider settings. */
+  local?: SkillLocal.Config
+  /** Model-facing skill catalog and tool settings. */
+  tool?: toolSkill.Config
+}
+
+/** Persisted goal domain, model-tool policy, and same-session driver config. */
+export interface GoalConfig {
+  /** Goal-domain creation defaults. */
+  domain?: GoalDomainConfig
+  /** Model-facing goal-tool authority policy. */
+  tool?: toolGoal.Config
+}
+```
+
+依赖：[`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`GoalDomainConfig`](#deepseek-aidsh-goal) · [`InvariantConfig`](#deepseek-aidsh-invariants) · [`SessionTitleConfig`](#deepseek-aidsh-session-title) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`toolGoal`](../packages/goal/tool-goal/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts) · [`workspaceContext`](../packages/context/workspace-context/src/index.ts)
+
+来源：[`packages/examples/agent-spine-demo/src/index.ts:90`](../packages/examples/agent-spine-demo/src/index.ts)
+
+## `@deepseek-ai/dsh-bash-env`
+
+```ts config-catalog
+/** Plugin config (all optional — the built-in facts resolve without defaults). */
+export interface Config {
+  /** DeepSeek Harness home directory exposed as `DSH_HOME`; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+}
+```
+
+来源：[`packages/bash/bash-env/src/index.ts:29`](../packages/bash/bash-env/src/index.ts)
+
+## `@deepseek-ai/dsh-bash-local`
+
+需要：`subprocess`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** Default working directory for commands (default: process.cwd()). */
+  cwd?: string
+  /** Default foreground timeout in milliseconds. */
+  timeoutMs?: number
+  /** Upper bound for per-call timeout overrides. */
+  maxTimeoutMs?: number
+  /** Per-stream in-memory output cap; overflow spills to a temp file. */
+  maxOutputBytes?: number
+  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
+  maxSpillBytes?: number
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
+  graceMs?: number
+}
+```
+
+来源：[`packages/bash/bash-local/src/index.ts:40`](../packages/bash/bash-local/src/index.ts)
+
+## `@deepseek-ai/dsh-bash-sandbox`
+
+需要：`subprocess` · `sandbox` · `sandboxPolicy`
+
+```ts config-catalog
+/**
+ * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
+ * the default mode and fallback `workspace-write` root — is NOT here: it lives
+ * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves
+ * each calling session's mode and cwd for every enforcing capability. The runner
+ * choice is likewise the `ctx.sandbox` provider's config, not this executor's.
+ */
+export type Config = LocalConfig
+```
+
+依赖：[`LocalConfig`](#deepseek-aidsh-bash-local)
+
+来源：[`packages/bash/bash-sandbox/src/index.ts:35`](../packages/bash/bash-sandbox/src/index.ts)
+
+## `@deepseek-ai/dsh-client-connection`
+
+需要：`httpServer`
+
+```ts config-catalog
+/** Plugin config: the deployment's non-loopback serving authorities. */
+export interface ConnectionConfig {
+  /**
+   * Authorities this deployment serves beyond loopback: exact `host:port`, or
+   * port-less `host` matching any port. The /api trust fence refuses any
+   * request whose Host is neither loopback nor listed here, so a
+   * non-loopback (`0.0.0.0`) deployment must declare the names it is reached
+   * by (the dsh CLI derives the machine's LAN IP literals itself). An entry
+   * that is not a bare, canonical authority fails the plugin load.
+   */
+  trustedHosts?: string[]
+}
+```
+
+来源：[`packages/client/connection/src/index.ts:32`](../packages/client/connection/src/index.ts)
+
+## `@deepseek-ai/dsh-client-hmr`
+
+需要：`clientModuleHost` · `httpServer`
+
+```ts config-catalog
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+  /** Bundle stat-poll interval in milliseconds (default 500, the build-side watcher's polling default). */
+  pollIntervalMs?: number
+}
+```
+
+来源：[`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
+
+## `@deepseek-ai/dsh-code-runtime-worker`
+
+```ts config-catalog
+/** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
+export interface Config {
+  /**
+   * Busy-time budget in milliseconds: the run fails with kind `'timeout'`
+   * once the worker's MEASURED event-loop active time
+   * (`worker.performance.eventLoopUtilization()`) exceeds this. Metering
+   * measured busy time — not wall time, not host-side pending-call
+   * bookkeeping — is what makes the budget both fair (a program awaiting a
+   * slow tool accrues nothing) and ungameable (a hot loop accrues whether
+   * or not a decoy dispatch is in flight).
+   */
+  computeMs?: number
+  /**
+   * Wall-clock ceiling in milliseconds; never pauses for anything. The
+   * backstop for what busy-time cannot see (a program awaiting a promise
+   * nobody will resolve). At most `2_147_483_647` (Node's maximum
+   * `setTimeout` delay, about 24.9 days): a longer value is rejected at load
+   * because `setTimeout` would clamp it to 1 ms.
+   */
+  maxWallMs?: number
+  /**
+   * Hard cap for serialized log-array, completion-value, and failure-message payloads;
+   * fixed result-envelope syntax is excluded.
+   */
+  maxOutputBytes?: number
+  /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */
+  maxOldGenerationSizeMb?: number
+}
+```
+
+来源：[`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+
+## `@deepseek-ai/dsh-compact-basic`
+
+需要：`llm` · `tokenMeter` · `sessions`
+
+```ts config-catalog
+/** Basic compaction configuration with an optional exact-target policy table. */
+export interface BasicCompactConfig extends CompactPolicyConfig {
+  /** Exact provider/model overrides; duplicate targets fail plugin load. */
+  modelPolicies?: ModelCompactPolicyConfig[]
+  /** Enable automatic step-boundary pressure and overflow-recovery listeners. Defaults to `true`. */
+  auto?: boolean
+}
+
+/** Policy fields shared by the default policy and exact model overrides. */
+export interface CompactPolicyConfig {
+  /** Compact at this fraction of the model's context window. Defaults to `0.8`. */
+  thresholdRatio?: number
+  /** Recent context retained as a fraction of the model's window. Defaults to `0.16`. */
+  retainRatio?: number
+  /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */
+  retainTokens?: number
+  /** Summary provider; set together with `summarizationModel`, or inherit the conversation target. */
+  summarizationProvider?: string
+  /** Summary model; set together with `summarizationProvider`, or inherit the conversation target. */
+  summarizationModel?: string
+  /** Provider generation cap for summarization. Defaults to `8192`. */
+  maxTokens?: number
+  /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
+  compactionRetries?: number
+  /** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */
+  maxOverflowRetries?: number
+}
+
+/** Exact provider/model override merged over the default compaction policy. */
+export interface ModelCompactPolicyConfig extends CompactPolicyConfig {
+  /** Registered provider route to match. */
+  provider: string
+  /** Exact routed model id to match within `provider`. */
+  model: string
+}
+```
+
+来源：[`packages/compact/compact-basic/src/types.ts:38`](../packages/compact/compact-basic/src/types.ts)
+
+## `@deepseek-ai/dsh-compact-tool-result-prune`
+
+需要：`tokenMeter`
+
+```ts config-catalog
+/** Character-budget policy for deterministic tool-result pruning. */
+export interface ToolResultPruneConfig {
+  /** Prune when total text exceeds this many Unicode code points. Defaults to `8192`. */
+  thresholdChars?: number
+  /** Maximum leading Unicode code points retained. Defaults to `4096`. */
+  headChars?: number
+  /** Maximum trailing Unicode code points retained. Defaults to `1024`. */
+  tailChars?: number
+}
+```
+
+来源：[`packages/compact/compact-tool-result-prune/src/types.ts:4`](../packages/compact/compact-tool-result-prune/src/types.ts)
+
+## `@deepseek-ai/dsh-credentials-local`
+
+```ts config-catalog
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+  /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */
+  path?: string
+  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Watch the document and hot-publish external edits; defaults to true. */
+  watch?: boolean
+  /** Watcher write-settle window in milliseconds; defaults to 100. */
+  debounceMs?: number
+}
+```
+
+来源：[`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+
+## `@deepseek-ai/dsh-e2b`
+
+```ts config-catalog
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
+  timeoutMs?: number
+}
+```
+
+来源：[`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts)
+
+## `@deepseek-ai/dsh-frontend-static`
+
+需要：`httpServer`
+
+```ts config-catalog
+/** Plugin config: the dist anchor. */
+export interface Config {
+  /** Absolute path of index.html inside the dist root. */
+  distIndex: string
+}
+```
+
+来源：[`packages/host/frontend-static/src/index.ts:28`](../packages/host/frontend-static/src/index.ts)
+
+## `@deepseek-ai/dsh-fs-local`
+
+```ts config-catalog
+/** Configuration for the local filesystem backend. */
+export interface Config {
+  /** Base directory for relative paths. Defaults to `process.cwd()`. */
+  cwd?: string
+}
+```
+
+来源：[`packages/fs/fs-local/src/index.ts:39`](../packages/fs/fs-local/src/index.ts)
+
+## `@deepseek-ai/dsh-fs-sandbox`
+
+需要：`sandboxPolicy`
+
+```ts config-catalog
+/**
+ * Plugin config: the local backend's knobs, verbatim (only `cwd`, the resolve
+ * base for relative paths). The sandbox default (mode + `workspace-write`
+ * fallback root) is NOT here — `ctx.sandboxPolicy` resolves each calling
+ * session for every enforcing capability.
+ */
+export type Config = LocalConfig
+```
+
+依赖：[`LocalConfig`](#deepseek-aidsh-fs-local)
+
+来源：[`packages/fs/fs-sandbox/src/index.ts:49`](../packages/fs/fs-sandbox/src/index.ts)
+
+## `@deepseek-ai/dsh-goal`
+
+需要：`agents`
+
+```ts config-catalog
+/** Deployment defaults for goal creation. */
+export interface Config {
+  /** Total rounds used when a create request omits its own cap. */
+  defaultMaxGoalRounds?: number
+}
+```
+
+来源：[`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.ts)
+
+## `@deepseek-ai/dsh-headless`
+
+需要：`apiProxy` · `httpServer`
+
+```ts config-catalog
+/** Plugin config: the task, patched in by the launcher. */
+export interface Config {
+  /** The prompt text for the single turn. */
+  task: string
+}
+```
+
+来源：[`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
+
+## `@deepseek-ai/dsh-hooks-claude`
+
+需要：`bash`
+
+```ts config-catalog
+/** Plugin config: where the CC hook config lives + substitution roots. */
+export interface Config {
+  /**
+   * Path to a `hooks.json` or a settings file whose `hooks` key holds the config.
+   * Process-level: read once at load, a relative path resolves against the process
+   * launch cwd, so one config applies to the whole process.
+   * TODO(per-session-hook-config): per-session discovery of a project-local
+   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   */
+  configPath: string
+  /**
+   * Replaces `${CLAUDE_PLUGIN_ROOT}` in command strings (the plugin's root dir).
+   */
+  pluginRoot?: string
+  /**
+   * Replaces `${CLAUDE_PROJECT_DIR}` in command strings AND is exported as the
+   * `CLAUDE_PROJECT_DIR` env var for hook processes. When omitted, the env var
+   * defaults per-run to the agent's session workspace (`session.header.cwd`, the
+   * same dir the hook runs in) — Claude Code always exports this var, and common
+   * unmodified hooks reference `$CLAUDE_PROJECT_DIR` for project-relative paths.
+   */
+  projectDir?: string
+  /** Default per-hook timeout in ms when a hook sets none (CC default: 600000). */
+  defaultTimeoutMs?: number
+  /** Character cap for the `hook/result` event's persisted stderr summary. */
+  stderrSummaryMaxChars?: number
+}
+```
+
+来源：[`packages/hooks/hooks-claude/src/index.ts:45`](../packages/hooks/hooks-claude/src/index.ts)
+
+## `@deepseek-ai/dsh-hooks-codex`
+
+需要：`bash`
+
+```ts config-catalog
+/** Plugin config: where the Codex hooks.json lives + the model name for payloads. */
+export interface Config {
+  /**
+   * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
+   * path resolves against the process launch cwd.
+   * TODO(per-session-hook-config): per-session project-local discovery from each
+   * `session/new.cwd` is not yet implemented.
+   */
+  configPath: string
+  /** The model name stamped on every payload (Codex includes `model` on each event). */
+  model?: string
+  /** Default per-hook timeout in ms when a hook sets none (Codex default: 600000). */
+  defaultTimeoutMs?: number
+  /** Character cap for the `hook/result` event's persisted stderr summary. */
+  stderrSummaryMaxChars?: number
+}
+```
+
+来源：[`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-codex/src/index.ts)
+
+## `@deepseek-ai/dsh-host-apiproxy`
+
+需要：`agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
+
+```ts config-catalog
+/**
+ * Gateway plugin config: host-level agent routing and Workspace creation root.
+ *
+ * `reasoningEffort` is deliberately absent, so the section carries one field
+ * the composition cannot. The seam resolves a section by MERGING the user
+ * layer over the composition entry per field, and an absent key cannot
+ * override a present one — so a composition-set effort would survive every
+ * later switch to a model that has none, and strand it for the next session
+ * to fail on. Effort is a per-model fact anyway: a deployment default belongs
+ * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
+ * which resolves per model rather than per gateway.
+ */
+export interface Config {
+  /** Default provider route for created agents. */
+  provider: string
+  /** Default model id. */
+  model: string
+  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
+  workspaceRoot?: string
+}
+```
+
+来源：[`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
+
+## `@deepseek-ai/dsh-host-directory-picker-browse`
+
+```ts config-catalog
+/** Validated plugin configuration. */
+export interface Config {
+  /** Complete-result bound of one listing level; see {@link BrowseDirectoryPicker.Config}. */
+  maxEntries: number
+}
+```
+
+来源：[`packages/host/directory-picker-browse/src/index.ts:181`](../packages/host/directory-picker-browse/src/index.ts)
+
+## `@deepseek-ai/dsh-host-webserver`
+
+```ts config-catalog
+/** Gateway config: the listen address. */
+export interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+}
+```
+
+来源：[`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
+
+## `@deepseek-ai/dsh-invariants`
+
+```ts config-catalog
+/** Runtime invariant selection configured on the service plugin. */
+export interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
+}
+```
+
+来源：[`packages/support/invariants/src/index.ts:15`](../packages/support/invariants/src/index.ts)
+
+## `@deepseek-ai/dsh-jsonrpc`
+
+需要：`agents`
+
+```ts config-catalog
+/** JSON-RPC deployment config plus runtime-only test seams. */
+export interface JsonRpcConfig {
+  /** Report max-token turn/subagent termination as a successful SDK result. */
+  maxTokensAsSuccess?: boolean
+  /** Transport input override; production uses `process.stdin`. */
+  input?: Readable
+  /** Transport output override; production uses `process.stdout`. */
+  output?: Writable
+  /** Process-exit override; production uses `process.exit`. */
+  exit?: (code: number) => void
+}
+```
+
+依赖：`Readable`（`node:stream`）· `Writable`（`node:stream`）
+
+来源：[`packages/scaffold/server/src/index.ts:25`](../packages/scaffold/server/src/index.ts)
+
+## `@deepseek-ai/dsh-llm-deepseek`
+
+需要：`llm`
+
+```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema and doubling
+ * as the `llm-deepseek` settings-section shape. Every field is optional in
+ * yml: a missing API key resolves through {@link Config.apiKeyEnv} at each
+ * request (a request without any key fails with `MISSING_CREDENTIAL`, not at
+ * plugin load), omitted thinking mode uses the provider default, and omitted
+ * reasoning effort resolves to `high`.
+ */
+export interface Config {
+  /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
+  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
+  baseURL?: string
+  /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
+  thinking?: 'enabled' | 'disabled'
+  /** Default thinking effort (default `high`); `off` disables thinking per request. */
+  reasoningEffort?: 'off' | 'high' | 'max'
+  /** Default per-request output cap (default 256,000); a model's own cap and explicit request values win. */
+  maxTokens?: number
+  /** Positive context capacity used when the selected model has no exact value (default 1,000,000). */
+  defaultContextWindow?: number
+  /** Advisory models shown by discovery consumers; defaults to V4 Flash and V4 Pro. */
+  models?: DeepSeekCatalogModel[]
+  /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
+  streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
+}
+
+/** One optional model entry advertised by the direct-fetch adapter. */
+export interface DeepSeekCatalogModel {
+  /** Wire model id accepted by the configured endpoint. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Optional selector detail for deployments with similar model variants. */
+  description?: string
+  /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */
+  contextWindow?: number
+  /** Per-request output cap for this model; omission falls back to the profile's {@link DeepSeekConnectionOptions.maxTokens}. */
+  maxTokens?: number
+}
+```
+
+依赖：[`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
+
+来源：[`packages/llm/llm-deepseek/src/index.ts:61`](../packages/llm/llm-deepseek/src/index.ts)
+
+## `@deepseek-ai/dsh-llm-pi-ai`
+
+需要：`llm`
+
+```ts config-catalog
+/** Plugin configuration: the provider routes this instance owns. */
+export interface Config {
+  /**
+   * pi-ai provider routes, keyed by provider. An empty (or omitted) dict is
+   * the dormant settings-driven posture: the adapter mounts with no routes
+   * and registers them the moment a settings section supplies profiles.
+   */
+  providers?: Record<string, PiAiProviderProfile>
+}
+
+/** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
+export interface PiAiProviderProfile {
+  /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
+  apiKeyEnv?: string
+  /** Name shown by configuration surfaces; defaults to the route key. */
+  displayName?: string
+  /**
+   * Wire protocol every model on this route speaks. Omission keeps each
+   * installed catalog model's own protocol, which is why a catalog route needs
+   * no protocol at all; a route the catalog does not ship must name one.
+   */
+  api?: string
+  /** Endpoint for this route's models; defaults to the installed catalog's endpoint. */
+  baseURL?: string
+  /**
+   * This route's model catalog. Omission serves the installed catalog for the
+   * route unchanged; an explicit list replaces it, each entry defaulting its
+   * unset fields from the installed model of the same id.
+   */
+  models?: PiAiModelProfile[]
+  /**
+   * Installed-catalog customizations by model id: each entry reshapes that
+   * one model with the same fields a {@link models} entry takes, while the
+   * rest of the catalog keeps serving untouched. Only meaningful on a catalog
+   * route with no `models` list — `models` already replaces the catalog, so
+   * an override beside it, on a route the catalog does not ship, or naming a
+   * model the catalog does not describe is refused rather than skipped.
+   */
+  modelOverrides?: Record<string, PiAiModelOverride>
+  /**
+   * Reasoning-dispatch switches for every `openai-completions` model on this
+   * route; each model's own `compat` overrides per field. What neither sets
+   * keeps the installed catalog entry's value, then pi-ai's baseURL-derived
+   * detection.
+   */
+  compat?: PiAiCompatProfile
+  /**
+   * Context capacity for a model this route lists that neither the entry nor
+   * the installed catalog sizes (default 262,144). A guess by construction, so
+   * a deployment whose gateway serves smaller models corrects it here.
+   */
+  defaultContextWindow?: number
+  /**
+   * Output capability for a model this route lists that neither the entry nor
+   * the installed catalog sizes (default 32,768). This sizes the model; it
+   * never becomes a per-request cap on its own.
+   */
+  defaultMaxTokens?: number
+  /** Provider request headers; Harness attribution wins reserved names. */
+  headers?: Record<string, string>
+  /** Provider-neutral pi-ai reasoning level. */
+  reasoning?: ModelThinkingLevel
+  /** Token budgets used by reasoning providers that support them. */
+  thinkingBudgets?: ThinkingBudgets
+  /** Prompt-cache retention preference. */
+  cacheRetention?: CacheRetention
+  /** Streaming transport preference. */
+  transport?: Transport
+  /** HTTP/provider SDK timeout in milliseconds. */
+  timeoutMs?: number
+  /** WebSocket connection timeout in milliseconds. */
+  websocketConnectTimeoutMs?: number
+  /** Maximum provider idle time while one stream read is outstanding. */
+  streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
+}
+
+/** One configured model entry: an id plus the catalog fields it overrides. */
+export interface PiAiModelProfile {
+  /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */
+  id: string
+  /** Display name for selectors; defaults to the catalog name, then the id. */
+  name?: string
+  /** Maximum combined request and response context in tokens. */
+  contextWindow?: number
+  /**
+   * Maximum output tokens. Configuring one also makes it this model's
+   * per-request default; a value inherited from the installed catalog, or the
+   * route's fallback, is the model's capability and never becomes a request
+   * default on its own.
+   */
+  maxTokens?: number
+  /**
+   * Selectable reasoning efforts. Absent inherits the installed catalog
+   * entry's capability (a hand-declared model has none and does not reason);
+   * `false` declares a non-reasoning model, which is how a profile strips
+   * reasoning from a catalog model its gateway cannot serve; a non-empty dict
+   * declares the offered levels and their wire spellings.
+   */
+  reasoningEfforts?: false | PiAiReasoningEfforts
+  /** Reasoning-dispatch switches for this model, winning over the route's. */
+  compat?: PiAiCompatProfile
+}
+
+/**
+ * Customization of one installed catalog model, keyed by its id in the
+ * route's `modelOverrides` dict — the same fields a `models` entry may set,
+ * with the id living in the key. Unlike a `models` list, overrides leave the
+ * rest of the catalog serving untouched, which is what makes "correct one
+ * model, keep the other thirty-seven" a three-line edit.
+ */
+export type PiAiModelOverride = Omit<PiAiModelProfile, 'id'>
+
+/**
+ * Reasoning-dispatch compatibility switches, set on the route (its models'
+ * default) or per model (winning over the route). Only the switches pi-ai's
+ * reasoning dispatch reads are offered; the rest of pi-ai's compat surface
+ * keeps its baseURL-derived auto-detection. pi-ai types both fields only on
+ * `OpenAICompletionsCompat` — the other wire protocols carry their reasoning
+ * shape in the protocol itself — so resolution rejects a model-level switch
+ * anywhere else, while a route-level default skips past models it cannot fit.
+ */
+export interface PiAiCompatProfile {
+  /** Reasoning parameter shape the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  thinkingFormat?: PiAiThinkingFormat
+  /** Whether the endpoint accepts `reasoning_effort`; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  supportsReasoningEffort?: boolean
+}
+
+/**
+ * Selectable reasoning efforts for one model: each key is a level the model
+ * offers (and selectors show), and its value is the wire spelling dispatch
+ * sends for it. `off` alone may leave its value empty — "supported, send
+ * nothing" — because for most providers not thinking is the parameter's
+ * absence; every other declared level must name a wire value. A level absent
+ * from the dict is not offered.
+ */
+export type PiAiReasoningEfforts = Partial<Record<ModelThinkingLevel, string | null>>
+
+/** One reasoning-dispatch wire format a profile may name. */
+export type PiAiThinkingFormat = Exclude<PiThinkingFormat, WithheldThinkingFormat>
+
+/** The `compat.thinkingFormat` spellings pi-ai accepts on an `openai-completions` model. */
+type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
+
+/**
+ * pi-ai thinking formats a profile cannot name: both drive the request through
+ * `chatTemplateKwargs`, which this configuration does not expose, so offering
+ * them would hand back a format with nothing to say.
+ */
+type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
+```
+
+依赖：`CacheRetention`（`@earendil-works/pi-ai`）· `ModelThinkingLevel`（`@earendil-works/pi-ai`）· `OpenAICompletionsCompat`（`@earendil-works/pi-ai`）· [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets`（`@earendil-works/pi-ai`）· `Transport`（`@earendil-works/pi-ai`）
+
+来源：[`packages/llm/llm-pi-ai/src/config.ts:142`](../packages/llm/llm-pi-ai/src/config.ts)
+
+## `@deepseek-ai/dsh-llm-replay`
+
+需要：`llm`
+
+```ts config-catalog
+/** Plugin config: the {@link ReplayConfig} inputs, each defaulting to its `DSH_SNAPSHOT_*` env var in `apply`. */
+export interface Config {
+  /** Override the fixture path; defaults to `$DSH_SNAPSHOT_FILE`. */
+  file?: string
+  /** Override the sidecar path; defaults to `$DSH_SNAPSHOT_OVERRIDE`. */
+  overrideFile?: string
+  /**
+   * Override the child-log paths; defaults to `$DSH_SNAPSHOT_CHILD_FILES` (a
+   * path-separator-delimited list). Each is a recorded subagent session log for
+   * a nested-agent scenario; absent/empty for a single-session scenario.
+   */
+  childFiles?: string[]
+  /** Optional replay-only provider catalog; absent or empty selects catch-all waterfall replay. */
+  providers?: ReplayProviderConfig[]
+  /** Optional per-chunk pacing delay in ms (see {@link ReplayConfig.paceMs}); absent keeps burst yield. */
+  paceMs?: number
+}
+
+/** One provider route exposed by the replay adapter. */
+export interface ReplayProviderConfig {
+  /** Provider route used for replay requests. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Advisory models exposed to replay scenarios that exercise discovery. */
+  models?: ReplayModelConfig[]
+  /** Optional provider-owned retry policy used by assembled recovery snapshots. */
+  retryPolicy?: RetryPolicyConfig
+}
+
+/** One model exposed by a replay-only provider catalog. */
+export interface ReplayModelConfig {
+  /** Model id used for replay requests. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Optional selector description. */
+  description?: string
+  /** Optional positive integer context capacity published by the replay adapter. */
+  contextWindow?: number
+}
+```
+
+依赖：[`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
+
+来源：[`packages/support/llm-replay/src/index.ts:744`](../packages/support/llm-replay/src/index.ts)
+
+## `@deepseek-ai/dsh-llm-retry`
+
+需要：`agents`
+
+```ts config-catalog
+/** This policy executor has no config; providers own `retryPolicy`. */
+export type Config = Readonly<Record<string, never>>
+```
+
+来源：[`packages/llm/llm-retry/src/index.ts:46`](../packages/llm/llm-retry/src/index.ts)
+
+## `@deepseek-ai/dsh-lsp-local`
+
+需要：`fs` · `lsp` · `subprocess`
+
+```ts config-catalog
+/** Plugin configuration: provider id → local language-server configuration. */
+export interface Config {
+  /** Non-empty table of stable provider ids to independent local server configurations. */
+  servers: Record<string, LspLocalServerConfig>
+}
+
+/** One configured local language server and its host bounds. */
+export interface LspLocalServerConfig {
+  /** Executable to spawn (absolute, or resolved on PATH at load). */
+  command: string
+  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
+  extensionToLanguage: Record<string, string>
+  /** Arguments passed to the executable (no shell). Default `[]`. */
+  args?: string[]
+  /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */
+  env?: Record<string, string>
+  /** Static `initialize` options forwarded to the server. Default `null`. */
+  initializationOptions?: unknown
+  /** Static answer to every `workspace/configuration` item. Default `null`. */
+  configuration?: unknown
+  /** Largest single framed message accepted from the server (bytes). Default 16000000. */
+  maxMessageBytes?: number
+  /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */
+  maxStderrBytes?: number
+  /** Largest source file this host will open (bytes). Default 4000000. */
+  maxDocumentBytes?: number
+  /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */
+  shutdownTimeoutMs?: number
+  /** Request-cancel and SIGTERM→SIGKILL grace (ms). Default 2000. */
+  killGraceMs?: number
+}
+```
+
+来源：[`packages/lsp/lsp-local/src/index.ts:82`](../packages/lsp/lsp-local/src/index.ts)
+
+## `@deepseek-ai/dsh-mcp-client`
+
+需要：`tools`
+
+```ts config-catalog
+/** Configuration for one stdio or Streamable HTTP MCP server. */
+export type Config = StdioConfig | StreamableHttpConfig
+
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+  /** Selects child-process stdio transport. */
+  transport: 'stdio'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** Executable used to start the server. */
+  command: string
+  /** Arguments passed directly, without shell interpolation. */
+  args: string[]
+  /** Extra env vars merged on top of scrubbed ambient env. */
+  env: Record<string, string>
+  /** Working directory for the child process. */
+  cwd: string
+  /** Per-tool-call timeout in milliseconds. */
+  toolCallTimeoutMs: number
+}
+
+/** Config for connecting to an MCP server over Streamable HTTP (SSE). */
+export interface StreamableHttpConfig {
+  /** Selects Streamable HTTP transport. */
+  transport: 'streamable-http'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** MCP endpoint URL. */
+  url: string
+  /** Additional headers attached to MCP requests. */
+  headers: Record<string, string>
+  /** Per-tool-call timeout in milliseconds. */
+  toolCallTimeoutMs: number
+}
+```
+
+来源：[`packages/mcp/mcp-client/src/index.ts:96`](../packages/mcp/mcp-client/src/index.ts)
+
+## `@deepseek-ai/dsh-permission`
+
+需要：`bash` · `approval` · `sessions`
+
+```ts config-catalog
+/** The {@link PermissionService} config: preset table and composition default. */
+export interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `workspace-write`
+   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
+   * never). The name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+  /**
+   * Default for new sessions. When omitted, the preset matching the composed
+   * sandbox and approval defaults is used.
+   */
+  defaultPreset?: string
+}
+
+/** One preset's sandbox/approval bundle and optional client presentation. */
+export interface PresetSpec {
+  /** The `sandbox/mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+```
+
+依赖：[`ApprovalPolicy`](subsystems/approval.md) · [`SandboxMode`](subsystems/sandbox.md)
+
+来源：[`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts)
+
+## `@deepseek-ai/dsh-plan-mode`
+
+需要：`tools` · `systemPrompt`
+
+```ts config-catalog
+/** Deployment-owned plan guidance. */
+export interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+来源：[`packages/plan/plan-mode/src/index.ts:69`](../packages/plan/plan-mode/src/index.ts)
+
+## `@deepseek-ai/dsh-pty-local`
+
+需要：`pty` · `sandboxPolicy` · `subprocess`
+
+```ts config-catalog
+/** Public plugin configuration. */
+export interface Config {
+  /** Backend registry type (default: `shell`). */
+  backendType?: string
+  /** Interactive shell executable (default: `/bin/bash`). */
+  shellPath?: string
+  /** Shell arguments (default: `--noprofile --norc -i`). */
+  shellArgs?: string[]
+  /** Terminal rows. */
+  rows?: number
+  /** Terminal columns. */
+  cols?: number
+  /** Maximum retained logical lines. */
+  scrollbackLines?: number
+  /** Maximum retained UTF-8 bytes. */
+  scrollbackMaxBytes?: number
+  /** Maximum bytes returned by one read or settled viewport. */
+  maxReadBytes?: number
+  /** Readiness polling interval. */
+  pollIntervalMs?: number
+  /** Delay before Linux exact syscall probes. */
+  exactProbeAfterMs?: number
+  /** Silence duration that yields `inferred_idle`. */
+  idleSilenceMs?: number
+  /**
+   * Extra wait beyond `idleSilenceMs`, once a prompt marker was seen, for the shell to
+   * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`.
+   */
+  handoffGraceMs?: number
+  /** Absolute send wait bound. */
+  timeoutMs?: number
+  /** Grace before teardown escalates to `SIGKILL`. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/pty/pty-local/src/config.ts:6`](../packages/pty/pty-local/src/config.ts)
+
+## `@deepseek-ai/dsh-pwsh-local`
+
+需要：`subprocess`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** Default working directory for commands (default: process.cwd()). */
+  cwd?: string
+  /** Default foreground timeout in milliseconds. */
+  timeoutMs?: number
+  /** Upper bound for per-call timeout overrides. */
+  maxTimeoutMs?: number
+  /** Per-stream in-memory output cap; overflow spills to a temp file. */
+  maxOutputBytes?: number
+  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
+  maxSpillBytes?: number
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
+  graceMs?: number
+  /**
+   * Explicit pwsh executable. When omitted, well-known Windows install
+   * locations and PATH entries are probed in order (PowerShell 7 install,
+   * PATH entries such as the Microsoft Store install, then Windows
+   * PowerShell 5.1), falling back to a bare `pwsh` resolved through PATH.
+   */
+  pwshPath?: string
+}
+```
+
+来源：[`packages/bash/pwsh-local/src/index.ts:54`](../packages/bash/pwsh-local/src/index.ts)
+
+## `@deepseek-ai/dsh-repeat-tool-guard`
+
+```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema plus the
+ * load-time checks in `apply` (misconfiguration fails loud: an empty
+ * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at
+ * plugin load, never a silent fall-back). `include`/`exclude` entries are
+ * `*`-wildcard predicates over tool names at call time, not references to
+ * registry entries — a pattern matching no currently registered tool is valid
+ * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools).
+ */
+export interface Config {
+  /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */
+  thresholds?: number[]
+  /** Tool-name patterns to track; empty means every tool is tracked. */
+  include?: string[]
+  /** Tool-name patterns transparent to the chain (neither count nor reset). */
+  exclude?: string[]
+  /**
+   * Maximum characters of canonical arguments quoted in the DETAILED reminder
+   * (default 500). Large payloads (a `write` body, a long command) would
+   * otherwise ride into the next request unbounded — precisely in a loop
+   * scenario; the cap bounds the reminder, never the detection (the chain key
+   * always compares the FULL canonical string).
+   */
+  argumentsPreviewChars?: number
+}
+```
+
+来源：[`packages/guard/repeat-tool-guard/src/index.ts:28`](../packages/guard/repeat-tool-guard/src/index.ts)
+
+## `@deepseek-ai/dsh-repository-plugin`
+
+需要：`loader`
+
+```ts config-catalog
+/** Repository Plugin runtime and source-list configuration. */
+export interface Config {
+  /** GitHub repository sources with explicit refs and optional `.dsh-plugin` subpaths. */
+  repositories?: string[]
+  /** Persistent generation cache; defaults to `$DSH_HOME/cache/repository-plugins`. */
+  cacheDir?: string
+}
+```
+
+来源：[`packages/self-modification/repository-plugin/src/index.ts:42`](../packages/self-modification/repository-plugin/src/index.ts)
+
+## `@deepseek-ai/dsh-sandbox-local`
+
+```ts config-catalog
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+  /**
+   * Override the runner argv; bwrap-shaped profile arguments are appended. A
+   * non-empty override asserts full enforcement and skips built-in selection and
+   * probing. A runner that starts but refuses its profile must be identifiable by
+   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
+   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * infrastructure failure.
+   */
+  runnerCommand?: string[]
+  /**
+   * Case-insensitive stderr substrings emitted when a configured
+   * {@link runnerCommand} refuses its profile before executing the wrapped
+   * command. Required and non-empty with `runnerCommand`; rejected without
+   * it. Each entry is a non-empty, single-line, case-insensitive substring
+   * covering the executable runner's own failure dialect.
+   */
+  runnerFailureSignatures?: string[]
+  /** Positive timeout for each functional probe; zero would mean unbounded to Node. */
+  probeTimeoutMs?: number
+}
+```
+
+来源：[`packages/sandbox/sandbox-local/src/index.ts:24`](../packages/sandbox/sandbox-local/src/index.ts)
+
+## `@deepseek-ai/dsh-sandbox-policy`
+
+```ts config-catalog
+/**
+ * Plugin config: the deployment's sandbox default. All optional — `Config`
+ * supplies the defaults (`mode: 'read-only'` is the fail-safe default; a
+ * deployment that wants a workspace-writable agent opts in explicitly). The
+ * runner choice is NOT here (it is the `ctx.sandbox` provider's config), nor
+ * is any per-family knob: this is the one shared policy home.
+ */
+export interface Config {
+  /** File-sandbox mode a session starts from (default: `read-only`). */
+  mode?: SandboxMode
+  /**
+   * Fallback root for agentless calls and sessions without a cwd (default:
+   * `process.cwd()`). Normal agent calls use their session cwd instead.
+   */
+  workspaceRoot?: string
+}
+```
+
+依赖：[`SandboxMode`](subsystems/sandbox.md)
+
+来源：[`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts)
+
+## `@deepseek-ai/dsh-session-persistence-jsonl`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Plugin config: where the JSONL backend keeps its session logs, and the packed-row write switch. */
+export interface Config {
+  /**
+   * Root directory for all session files. Required (no default): a default of
+   * `process.cwd()` would scatter session files as the process's cwd changes
+   * (bash calls, subprocesses). Sessions group under human-readable project
+   * directories, then per-session directories. An existing root must be a
+   * readable directory; an absent root is created on first materialization.
+   */
+  root: string
+  /**
+   * Write runs of consecutive `assistant/chunk` delta events as packed
+   * `text-chunks`/`reasoning-chunks`/`tool-call-chunks` rows (lossless,
+   * ~60% smaller logs measured on a real session). Defaults to true; false
+   * keeps one `SessionEvent` per line for diagnostics. Reading packed rows is
+   * unconditional: a log's layout never depends on this switch.
+   */
+  packChunks?: boolean
+  /** Physical encoding; defaults to checksummed Zstandard frames. */
+  compression?: JsonlCompression
+  /** Maximum cold Session preparations retained for history-to-resume reuse. */
+  preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
+}
+
+/** Physical encoding selected for JSONL session artifacts. */
+export type JsonlCompression = 'zstd' | 'none'
+```
+
+来源：[`packages/session/session-persistence-jsonl/src/index.ts:59`](../packages/session/session-persistence-jsonl/src/index.ts)
+
+## `@deepseek-ai/dsh-session-persistence-sqlite`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved. Filesystem setup errors other than an existing database
+   * fail initialization. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
+   */
+  path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) is the recorded
+   * durability model; pick a rollback-journal mode (`delete`/`truncate`/
+   * `persist`) on filesystems where WAL's shared-memory files do not work
+   * (network mounts). See {@link JournalMode}.
+   */
+  journalMode?: JournalMode
+  /** Maximum cold Session preparations retained for history-to-resume reuse. */
+  preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
+}
+
+/**
+ * Journal modes the backend will run under. `wal` is the default and the
+ * durability model the persistence ADR records; the rollback-journal modes
+ * (`delete`/`truncate`/`persist`) exist for filesystems where WAL's
+ * shared-memory files do not work (network mounts). `memory`/`off` are
+ * excluded: dropping journal durability silently contradicts what this
+ * backend promises.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+```
+
+来源：[`packages/session/session-persistence-sqlite/src/index.ts:67`](../packages/session/session-persistence-sqlite/src/index.ts)
+
+## `@deepseek-ai/dsh-session-projection-cache`
+
+需要：`storageDomain` · `sessionProjections` · `sessionPersistence` · `sessions`
+
+```ts config-catalog
+/**
+ * Plugin config. Both throttle triggers are deployment choices with no
+ * universally correct value, so the composition states them explicitly
+ * (cordis.yml); the two mandatory write points (`turn/end` and session
+ * disposal) are policy, not tunables, and always fire.
+ */
+export interface Config {
+  /** Committed events per session that force a durable checkpoint write between mandatory points. */
+  writeEveryEvents: number
+  /** Longest time (milliseconds) a dirty checkpoint may stay unwritten between mandatory points. */
+  writeIntervalMs: number
+}
+```
+
+来源：[`packages/session/session-projection-cache/src/index.ts:42`](../packages/session/session-projection-cache/src/index.ts)
+
+## `@deepseek-ai/dsh-session-query-sqlite`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Combined session-query configuration backed by SQLite full-text search. */
+export interface Config extends SessionQueryConfig {
+  /**
+   * Dedicated derived-index path; `:memory:` is supported for ephemeral
+   * indexes. Missing directories and database files are created owner-only on
+   * POSIX filesystems; existing modes are preserved.
+   */
+  path: string
+  /** Open the SQLite module and handle at service activation or the first search. Defaults to `startup`. */
+  openAt?: OpenAt
+  /** SQLite journal mode. Defaults to `wal`. */
+  journalMode?: JournalMode
+  /** Page size when a request omits `limit`. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 20. */
+  defaultLimit?: number
+  /** Largest accepted page size. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 100. */
+  maxLimit?: number
+  /** Maximum snippet length in Unicode code points. Defaults to 240. */
+  snippetChars?: number
+  /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
+  persistedInspectConcurrency?: number
+}
+
+/** SQLite module/handle opening phase. */
+export type OpenAt = 'startup' | 'first-search'
+
+/** Supported SQLite journal modes. */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+```
+
+依赖：[`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
+
+来源：[`packages/session-query/session-query-sqlite/src/index.ts:89`](../packages/session-query/session-query-sqlite/src/index.ts)
+
+## `@deepseek-ai/dsh-session-reference`
+
+需要：`sessionQuery`
+
+```ts config-catalog
+/** Session-reference service configuration. */
+export interface Config {
+  /** Maximum distinct source sessions referenced by one message, from one to three. */
+  maxReferences?: number
+  /** Default host candidate-list limit. */
+  candidateLimit?: number
+  /** Maximum rendered UTF-8 bytes for one source snapshot. */
+  maxReferenceBytes?: number
+}
+```
+
+来源：[`packages/context/session-reference/src/config.ts:11`](../packages/context/session-reference/src/config.ts)
+
+## `@deepseek-ai/dsh-session-telemetry-otel`
+
+需要：`sessions`
+
+```ts config-catalog
+/**
+ * Plugin configuration: one sharing policy, two verbatim SDK option shapes,
+ * and one DSH-owned shutdown bound. Uploading modes validate their endpoint
+ * and shutdown deadline at plugin load; `DISABLED` reads neither.
+ */
+export interface Config {
+  /** Sharing policy; defaults to immediate `FULL` delivery. */
+  mode?: TelemetryMode
+  /**
+   * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
+   * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
+   * `compression`, `keepAlive`, …), owned and documented by the SDK. `url`
+   * is the one field this package requires and validates itself.
+   */
+  exporter?: OTLPExporterNodeConfigBase & {
+    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
+    url?: string
+  }
+  /**
+   * Passed verbatim to `BatchLogRecordProcessor` (minus the exporter slot,
+   * which this plugin fills); the SDK owns and documents these knobs.
+   */
+  processor?: Omit<BatchLogRecordProcessorOptions, 'exporter'>
+  /** Maximum time spent awaiting the SDK provider's complete shutdown path. */
+  shutdownTimeoutMillis?: number
+}
+
+/** Session-sharing policy selected by {@link Config.mode}. */
+export enum TelemetryMode {
+  FULL = 'FULL',
+  FEEDBACK_ONLY = 'FEEDBACK_ONLY',
+  DISABLED = 'DISABLED',
+}
+```
+
+依赖：`BatchLogRecordProcessorOptions`（`@opentelemetry/sdk-logs`）· `OTLPExporterNodeConfigBase`（`@opentelemetry/otlp-exporter-base`）
+
+来源：[`packages/session/session-telemetry-otel/src/index.ts:80`](../packages/session/session-telemetry-otel/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Required deterministic fallback and accepted-title limits. */
+export interface Config {
+  /** Maximum whitespace-delimited words in the built-in fallback. */
+  readonly fallbackMaxWords: number
+  /** Maximum UTF-8 bytes in the built-in fallback. */
+  readonly fallbackMaxBytes: number
+  /** Maximum UTF-8 bytes in any accepted title. */
+  readonly maxTitleBytes: number
+}
+```
+
+来源：[`packages/session/session-title/src/index.ts:79`](../packages/session/session-title/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title-all-messages-llm`
+
+需要：`sessionTitle` · `llm` · `sessions`
+
+```ts config-catalog
+/** Required LLM policy; this plugin adds no defaults. */
+export type Config = SessionTitleLlmConfig
+```
+
+依赖：[`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
+
+来源：[`packages/session/session-title-all-messages-llm/src/index.ts:15`](../packages/session/session-title-all-messages-llm/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title-first-message-llm`
+
+需要：`sessionTitle` · `llm` · `sessions`
+
+```ts config-catalog
+/** Required LLM policy; this plugin adds no defaults. */
+export type Config = SessionTitleLlmConfig
+```
+
+依赖：[`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
+
+来源：[`packages/session/session-title-first-message-llm/src/index.ts:15`](../packages/session/session-title-first-message-llm/src/index.ts)
+
+## `@deepseek-ai/dsh-settings-local`
+
+```ts config-catalog
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+  /** Settings document path; defaults to `settings.yaml` under the harness home. */
+  path?: string
+  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Watch the document and hot-publish external edits; defaults to true. */
+  watch?: boolean
+  /** Watcher write-settle window in milliseconds; defaults to 100. */
+  debounceMs?: number
+}
+```
+
+来源：[`packages/settings/settings-local/src/index.ts:21`](../packages/settings/settings-local/src/index.ts)
+
+## `@deepseek-ai/dsh-skill`
+
+```ts config-catalog
+/** Skill registry configuration. */
+export interface Config {
+  /** Maximum number of completed cwd/provider catalogs kept in memory. */
+  readonly collectCacheMaxEntries?: number
+}
+```
+
+来源：[`packages/skill/skill/src/index.ts:265`](../packages/skill/skill/src/index.ts)
+
+## `@deepseek-ai/dsh-skill-local`
+
+需要：`skills`
+
+```ts config-catalog
+/** Local filesystem skill provider configuration. */
+export interface Config {
+  /** Unique provider name. Defaults to `local`. */
+  providerName?: string
+  /** Whether project and user roots are included around custom roots. */
+  includeDefaultRoots?: boolean
+  /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */
+  agentsHome?: string
+  /** Additional skill roots scanned after project roots and before user roots. */
+  customSkillDirs?: string[]
+  /** Whether host-local skill roots are watched for catalog changes. */
+  watch?: boolean
+  /** Whether Chokidar uses polling instead of native filesystem events. */
+  watchUsePolling?: boolean
+  /** Milliseconds a changed skill entry must remain stable before it is observed. */
+  watchStabilityThresholdMs?: number
+  /** Milliseconds between Chokidar stability or polling probes. */
+  watchPollIntervalMs?: number
+  /** Maximum distinct project roots whose skill directories remain watched. */
+  watchMaxProjects?: number
+  /** Whether watched symbolic links follow their target files. */
+  watchFollowSymlinks?: boolean
+  /** Bundled skill root; defaults to `$DSH_BUNDLED_SKILL_DIR` when default roots are included, otherwise mounts none. */
+  bundledSkillDir?: string
+}
+```
+
+来源：[`packages/skill/skill-local/src/index.ts:49`](../packages/skill/skill-local/src/index.ts)
+
+## `@deepseek-ai/dsh-spill-local`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /**
+   * Root directory for spill files. Omitted uses a lazily-created private
+   * (0700) per-process directory under the OS temp dir — the safe default for
+   * a local deployment. Set it to keep spill files under a known location.
+   */
+  root?: string
+}
+```
+
+来源：[`packages/spill/spill-local/src/index.ts:22`](../packages/spill/spill-local/src/index.ts)
+
+## `@deepseek-ai/dsh-spill-policy`
+
+需要：`tools`
+
+```ts config-catalog
+/** Plugin config. */
+export interface Config {
+  /**
+   * The model-facing context cap for a plain-text tool result, in UTF-8 bytes.
+   * Omitted disables the policy entirely (no-op). When set, a result larger than
+   * this is spilled and replaced with a preview derived from this same budget.
+   */
+  maxInlineBytes?: number
+}
+```
+
+来源：[`packages/spill/spill-policy/src/index.ts:60`](../packages/spill/spill-policy/src/index.ts)
+
+## `@deepseek-ai/dsh-storage-domain`
+
+需要：`storage`
+
+```ts config-catalog
+/**
+ * Plugin config. Which backend serves which domain is decided here, not
+ * globally on the hub: `backend` is the default route and `routes` overrides
+ * it per domain name. A route naming an unregistered backend fails loud at
+ * `open` with `backend-not-found`.
+ */
+export interface Config {
+  /** Default backend name for every domain without an explicit route. Required: there is no universally correct medium. */
+  backend: string
+  /** Per-domain overrides: domain name → backend name. */
+  routes?: Record<string, string>
+}
+```
+
+来源：[`packages/storage/storage-domain/src/index.ts:52`](../packages/storage/storage-domain/src/index.ts)
+
+## `@deepseek-ai/dsh-storage-json`
+
+需要：`storage`
+
+```ts config-catalog
+/**
+ * Plugin configuration.
+ * `root` has NO default on purpose: a `process.cwd()` fallback would scatter
+ * unit files wherever the process happens to start; assemblies state the
+ * location explicitly.
+ */
+export interface Config {
+  /** Directory holding one `<unit>.json` file per unit. */
+  root: string
+}
+```
+
+来源：[`packages/storage/storage-json/src/index.ts:27`](../packages/storage/storage-json/src/index.ts)
+
+## `@deepseek-ai/dsh-storage-sqlite`
+
+需要：`storage`
+
+```ts config-catalog
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved. Filesystem setup errors other than an existing
+   * database fail the open. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
+   */
+  path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick
+   * a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems
+   * where WAL's shared-memory files do not work (network mounts). See
+   * {@link JournalMode}.
+   */
+  journalMode?: JournalMode
+}
+
+/**
+ * Journal modes the backend will run under. `wal` is the default; the
+ * rollback-journal modes (`delete`/`truncate`/`persist`) exist for
+ * filesystems where WAL's shared-memory files do not work (network mounts).
+ * `memory`/`off` are excluded: dropping journal durability silently
+ * contradicts the durability clause of the KV backend contract.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+```
+
+来源：[`packages/storage/storage-sqlite/src/index.ts:24`](../packages/storage/storage-sqlite/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-acp`
+
+需要：`subagents` · `subprocess`
+
+```ts config-catalog
+/** Config: how to spawn and drive the child ACP agent process. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `acp`). */
+  providerName: string
+  /** The executable to spawn for each run (the child ACP agent). */
+  command: string
+  /** Arguments passed to {@link command}. */
+  args: string[]
+  /**
+   * Working directory override for the child process and its ACP session.
+   * Must be non-empty; a relative path resolves against the harness launch
+   * directory at load, and the result must be an existing directory. When
+   * omitted, each child inherits its delegating parent session's cwd — and
+   * starting one from a parent session that has no cwd fails.
+   */
+  cwd?: string
+  /**
+   * How to auto-answer the child's `session/request_permission` prompts:
+   * `reject` (default — decline every prompt) or `allow` (approve via the first
+   * allow-shaped option). The first cut surfaces no prompt to a human.
+   */
+  permission: PermissionPolicy
+  /**
+   * Extra environment variables for the child process — e.g. the child
+   * harness's own `DEEPSEEK_API_KEY`. Forwarded on top of a credential-scrubbed
+   * copy of the parent env, so an explicit key here reaches the child while
+   * ambient secrets do not leak implicitly.
+   */
+  env: Record<string, string>
+  /**
+   * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
+   * window to flush persistence and tear down its own nested subprocesses
+   * before the parent escalates to a signal. Must not exceed
+   * `MAX_TIMER_DELAY_MS`.
+   */
+  disposeEofGraceMs?: number
+  /** Termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
+  disposeGraceMs?: number
+}
+
+/** Fixed response to child permission requests: reject by default, or select the first allow option. */
+export type PermissionPolicy = 'allow' | 'reject'
+```
+
+来源：[`packages/subagent/subagent-acp/src/index.ts:27`](../packages/subagent/subagent-acp/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-claude-code`
+
+需要：`subagents` · `subprocess`
+
+```ts config-catalog
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for Claude Code process-tree termination. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/subagent/subagent-claude-code/src/index.ts:32`](../packages/subagent/subagent-claude-code/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-codex`
+
+需要：`subagents` · `subprocess`
+
+```ts config-catalog
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for app-server process-tree termination. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/subagent/subagent-codex/src/index.ts:30`](../packages/subagent/subagent-codex/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-dsh-sdk`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Config: how to spawn and drive the child SDK runtime process. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `dsh-sdk`). */
+  providerName: string
+  /** The executable to spawn for each run (the child runtime bin or packaged exe). */
+  command: string
+  /** Arguments passed to {@link command} (typically the child's `cordis.yml` path). */
+  args: string[]
+  /**
+   * Working directory override for the child process and its SDK session
+   * workspace. Must be non-empty; a relative path resolves against the
+   * harness launch directory at load, and the result must be an existing
+   * directory. When omitted, each child inherits its delegating parent
+   * session's cwd — and starting one from a parent session that has no cwd
+   * fails.
+   */
+  cwd?: string
+  /** Provider route the child runtime initializes with (default `deepseek-official`). */
+  provider: string
+  /** Model the child runtime initializes with (default `deepseek-v4-flash`). */
+  model: string
+  /** Optional per-request output-token cap for the child runtime. */
+  maxTokens?: number
+  /**
+   * Extra environment variables for the child process — e.g. the child
+   * runtime's own `DEEPSEEK_API_KEY`, or `DSH_CORDIS_CONFIG` naming its
+   * config. Forwarded on top of a credential-scrubbed copy of the parent
+   * env, so an explicit key here reaches the child while ambient secrets do
+   * not leak implicitly.
+   */
+  env: Record<string, string>
+  /** Bound (ms) on the protocol `shutdown` exchange during dispose. */
+  shutdownTimeoutMs?: number
+  /**
+   * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
+   * window to flush persistence and tear down its own nested subprocesses
+   * before the parent escalates to a signal.
+   */
+  disposeEofGraceMs?: number
+  /** Termination confirmation window (ms), including forced exit on every platform. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/subagent/subagent-dsh-sdk/src/index.ts:29`](../packages/subagent/subagent-dsh-sdk/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-fork`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Config: the registry name to register the provider under. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `fork`). */
+  providerName: string
+}
+```
+
+来源：[`packages/subagent/subagent-fork/src/index.ts:31`](../packages/subagent/subagent-fork/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-spawn`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Config: the registry name to register the provider under. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `spawn`). */
+  providerName: string
+}
+```
+
+来源：[`packages/subagent/subagent-spawn/src/index.ts:25`](../packages/subagent/subagent-spawn/src/index.ts)
+
+## `@deepseek-ai/dsh-subprocess-e2b`
+
+需要：`e2b`
+
+```ts config-catalog
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+```
+
+来源：[`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts)
+
+## `@deepseek-ai/dsh-system-prompt`
+
+```ts config-catalog
+/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.persona} for its contract). */
+export interface Config {
+  /** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */
+  includeHarnessIdentity?: boolean
+  /**
+   * Deployment-wide order-0 persona template. A scoped section named
+   * `deployment:persona` shadows it; `{{variable}}` references are strict.
+   */
+  persona?: string
+  /**
+   * Model-facing tool names in order, with {@link TOOL_ORDER_REST} exactly once.
+   * Shape errors fail at load and unknown names fail at assembly; known names
+   * hidden in one scope may be absent there. Omitted means lexicographic order.
+   */
+  toolOrder?: string[]
+}
+```
+
+来源：[`packages/core/system-prompt/src/index.ts:166`](../packages/core/system-prompt/src/index.ts)
+
+## `@deepseek-ai/dsh-time-context`
+
+需要：`agents`
+
+```ts config-catalog
+/** Request-preparation clock formatting and append scheduling. Invalid values fail plugin load. */
+export interface Config {
+  /** IANA time zone used for the rendered timestamp. Omit to resolve the Node process's system zone at plugin load. */
+  timeZone?: string
+  /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject at every eligible step. */
+  refreshIntervalMs?: number
+}
+```
+
+来源：[`packages/context/time-context/src/index.ts:20`](../packages/context/time-context/src/index.ts)
+
+## `@deepseek-ai/dsh-tmux-context`
+
+需要：`agents`
+
+```ts config-catalog
+/** Per-turn tmux-location scheduling. Invalid values fail plugin load. */
+export interface Config {
+  /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject on every eligible change. */
+  refreshIntervalMs?: number
+}
+```
+
+来源：[`packages/context/tmux-context/src/index.ts:34`](../packages/context/tmux-context/src/index.ts)
+
+## `@deepseek-ai/dsh-token-meter`
+
+```ts config-catalog
+/** Token-meter plugin configuration; the fixed estimator has no settings. */
+export type TokenMeterConfig = Record<string, never>
+```
+
+来源：[`packages/llm/token-meter/src/types.ts:12`](../packages/llm/token-meter/src/types.ts)
+
+## `@deepseek-ai/dsh-tool-bash`
+
+需要：`tools` · `bash` · `systemPrompt` · `bashEnv`
+
+```ts config-catalog
+/** Configuration for the bash tool. */
+export interface Config {
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+  enableRunInBackground?: boolean
+}
+```
+
+来源：[`packages/bash/tool-bash/src/index.ts:34`](../packages/bash/tool-bash/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-bash-persistent`
+
+需要：`tools` · `pty`
+
+```ts config-catalog
+/** Configuration for the persistent Bash tool. */
+export interface Config {
+  /** PTY backend used for each owner-isolated persistent shell (default `shell`). */
+  backendType?: string
+  /** Wall-clock limit for one command (default 300000). */
+  timeoutMs?: number
+  /** Maximum returned command-output characters before clipping (default 16000). */
+  maxOutputChars?: number
+  /** Model-facing tool description; deployments may describe their environment. */
+  description?: string
+}
+```
+
+来源：[`packages/pty/tool-bash-persistent/src/index.ts:405`](../packages/pty/tool-bash-persistent/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-cordis`
+
+需要：`tools`
+
+```ts config-catalog
+/** Config for the tool-cordis plugin: the sandbox evaluation bound. */
+export interface Config {
+  /**
+   * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm
+   * before evaluation is aborted (default 5000). An async body escapes this
+   * bound — see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance.
+   */
+  vmTimeoutMs?: number
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts:25`](../packages/self-modification/tool-cordis/src/index.ts)
+## `@deepseek-ai/dsh-tool-fs`
+
+需要：`tools` · `fs` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin config (all optional — `Config` supplies the defaults). */
+export interface Config {
+  /** Default and maximum number of lines returned by one `read` call. */
+  readLimit?: number
+  /** Maximum characters returned for a single line before truncation. */
+  readMaxLineLength?: number
+  /** Maximum bytes returned for the selected lines of one `read` call. */
+  readMaxBytes?: number
+  /** Files at or above this size stream instead of loading whole into memory. */
+  readStreamMinSize?: number
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts:24`](../packages/fs/tool-fs/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-fs-search`
+
+需要：`tools` · `systemPrompt` · `subprocess`
+
+```ts config-catalog
+/** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */
+export interface Config {
+  /** Whether an over-cap `glob` page is sampled across top-level entries instead of taking the modification-time head. */
+  sampleOverCapGlobResults: boolean
+  /** Max paths one `glob` call retains inline; later paths go to the formatted spill file. */
+  globMaxResults?: number
+  /** Max flat matches one `grep` call retains inline; later matches go to the formatted spill file. */
+  grepMaxMatches?: number
+  /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */
+  grepMaxLineBytes?: number
+  /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted card stays bounded. */
+  searchMetaMaxBytes?: number
+  /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
+  rawOutputMaxBytes?: number
+  /** Terminate-escalation grace (ms), handed to the subprocess seam and bounded by `MAX_TIMER_DELAY_MS`. */
+  graceMs?: number
+  /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */
+  stderrMaxBytes?: number
+  /** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
+  timeoutMs?: number
+}
+```
+
+来源：[`packages/fs/tool-fs-search/src/index.ts:73`](../packages/fs/tool-fs-search/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-goal`
+
+需要：`agents` · `goals` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Model policy and hard lower bounds for goal-state updates. */
+export interface Config {
+  /** Minimum admitted goal rounds before the model may self-report `blocked`. */
+  blockedAfterConsecutiveRounds?: number
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts:26`](../packages/goal/tool-goal/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-lsp`
+
+需要：`tools` · `lsp` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin configuration: result caps and the timeout budget. */
+export interface Config {
+  /** Largest number of rendered locations before an omission marker (default 100). */
+  maxLocations?: number
+  /** Largest complete rendered result in characters, including truncation metadata (default 16000). */
+  maxResultChars?: number
+  /** Tool-call timeout budget in ms (default 60000). */
+  timeoutMs?: number
+}
+```
+
+来源：[`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-pty`
+
+需要：`pty` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Model-facing terminal tool configuration. */
+export interface Config {
+  /** Expose `run_in_background` and accept background sends (default true). */
+  enableRunInBackground?: boolean
+  /** Maximum UTF-8 bytes in one complete terminal or task-output result. */
+  maxResultBytes?: number
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts:35`](../packages/pty/tool-pty/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-pwsh`
+
+需要：`tools` · `bash` · `systemPrompt` · `bashEnv`
+
+```ts config-catalog
+/** Configuration for the pwsh tool. */
+export interface Config {
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+  enableRunInBackground?: boolean
+}
+```
+
+来源：[`packages/bash/tool-pwsh/src/index.ts:43`](../packages/bash/tool-pwsh/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-ralph`
+
+需要：`tools` · `workflows` · `subagents` · `systemPrompt`
+
+```ts config-catalog
+/** Deployment policy for the fixed Ralph workflow. */
+export interface Config {
+  /** Fresh structured-output provider used for every round (default `spawn`). */
+  subagentProvider?: string
+  /** Default and deployment ceiling for one call's round count (default 256). */
+  maxRounds?: number
+  /** Maximum serialized characters in one structured handoff (default 16384). */
+  maxHandoffChars?: number
+  /** Maximum characters in a successful parent-facing terminal text (default 16384). */
+  maxResultChars?: number
+}
+```
+
+来源：[`packages/workflow/tool-ralph/src/index.ts:23`](../packages/workflow/tool-ralph/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-session-query`
+
+需要：`tools` · `systemPrompt` · `sessionQuery`
+
+```ts config-catalog
+/** Deployment-owned search count and timeout bounds. */
+export interface Config {
+  /** Maximum authorized hits returned by one search call. Defaults to 100. */
+  maxSearchResults?: number
+  /** Cooperative full-text search deadline in milliseconds. Defaults to 30000. */
+  searchTimeoutMs?: number
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts:29`](../packages/session-query/tool-session-query/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-skill`
+
+需要：`agents` · `tools` · `skills`
+
+```ts config-catalog
+/** Model-facing skill catalog configuration. */
+export interface Config {
+  /** Maximum normalized description length rendered in the session catalog; minimum 3. */
+  catalogDescriptionMaxLength?: number
+}
+```
+
+来源：[`packages/skill/tool-skill/src/index.ts:61`](../packages/skill/tool-skill/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-str-replace-editor`
+
+需要：`tools` · `fs`
+
+```ts config-catalog
+/** Configuration for the string-replacement editor tool. */
+export interface Config {
+  /** Maximum returned view characters before clipping (default 16000). */
+  maxOutputChars?: number
+  /** Model-facing tool description. */
+  description?: string
+}
+```
+
+来源：[`packages/fs/tool-str-replace-editor/src/index.ts:496`](../packages/fs/tool-str-replace-editor/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-subagent`
+
+需要：`tools` · `subagents`
+
+```ts config-catalog
+/** Config: which registered provider this tool delegates to, plus child defaults. */
+export interface Config {
+  /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
+  provider: string
+  /**
+   * Model-facing tool name (default `subagent`). Each loaded instance must use
+   * a distinct name.
+   */
+  toolName?: string
+  /**
+   * Expose `run_in_background` (default true). Disabled instances omit the
+   * parameter and reject forced background calls.
+   */
+  enableRunInBackground?: boolean
+  /**
+   * Background execution policy (default `one-shot`). `continuable` requires a
+   * provider with the `prepareContinuable` capability and returns the durable
+   * child id; follow-up adapters remain independently optional.
+   */
+  backgroundMode?: 'one-shot' | 'continuable'
+  /**
+   * Agent options applied to every child; omitted fields use child-loop defaults.
+   */
+  agentOptions?: AgentOptions
+  /**
+   * Per-child persona that shadows `deployment:persona`. Requires the
+   * provider's `persona` capability; omission preserves the deployment persona.
+   */
+  persona?: string
+  /**
+   * Tool filter applied to every child. Filtered tools disappear from its
+   * prompt and reject execution. Requires the provider's `toolFilter`
+   * capability; unknown names fail startup.
+   */
+  toolFilter?: {
+    /** Global tool names the child keeps; everything else is removed. */
+    allow?: string[]
+    /** Global tool names removed from the child. */
+    deny?: string[]
+  }
+  /**
+   * Maximum child depth: a non-negative safe integer (default `3`; `0` forbids
+   * delegation entirely), or `'provider-managed'` to send no cap. A numeric cap
+   * requires the provider's `depthLimit` capability (mount fails loud
+   * otherwise). The provider checks the calling agent's current depth at every
+   * start; the tool remains model-visible so runtime policy owns rejection.
+   * `'provider-managed'` is for an out-of-process provider whose recursion
+   * budget belongs to the child runtime or its own deployment.
+   */
+  maxDepth?: number | 'provider-managed'
+}
+```
+
+依赖：[`AgentOptions`](subsystems/core.md)
+
+来源：[`packages/subagent/tool-subagent/src/index.ts:25`](../packages/subagent/tool-subagent/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-subagent-report`
+
+需要：`subagents` · `tools`
+
+```ts config-catalog
+/** Config: how accepted reports are scheduled on the parent. */
+export interface Config {
+  /**
+   * Parent scheduling (default `quiet`). `quiet` adds context without waking;
+   * `wakeup` creates one ordinary later parent turn.
+   */
+  reportDelivery?: SubagentReportDelivery
+}
+```
+
+依赖：[`SubagentReportDelivery`](subsystems/subagent.md)
+
+来源：[`packages/subagent/tool-subagent-report/src/index.ts:22`](../packages/subagent/tool-subagent-report/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-tasks`
+
+需要：`tools` · `tasks` · `systemPrompt`
+
+```ts config-catalog
+/** Configures bounded `task_output` waits. */
+export interface Config {
+  /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
+  waitTimeoutMs?: number
+  /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */
+  maxWaitTimeoutMs?: number
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts:23`](../packages/tasks/tool-tasks/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-todo`
+
+需要：`tools`
+
+```ts config-catalog
+/** Model-facing todo tool configuration. */
+export interface Config {
+  /**
+   * Required deployment choice for whether several todos may be `in_progress` at once. True suits
+   * agents that run work concurrently — subagents, background commands, workflow fan-out — and the
+   * description then instructs the model to mark every actively worked task. False restores the
+   * single-active discipline: the description asks for exactly one, and a call marking more is
+   * rejected.
+   */
+  allowParallelInProgress: boolean
+}
+```
+
+来源：[`packages/todo/tool-todo/src/index.ts:29`](../packages/todo/tool-todo/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-web`
+
+需要：`tools` · `web` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin config: which web tools to register, the source cap, per-tool budgets, and the fetch output cap. */
+export interface Config {
+  /** Register `web_search`. Defaults to true. */
+  search?: boolean
+  /** Register `web_fetch`. Defaults to true. */
+  fetch?: boolean
+  /** Upper bound on sources returned by one `web_search` call. */
+  searchMaxResults?: number
+  /** Cooperative timeout budget (ms) for `web_fetch`. Defaults to 30000. */
+  fetchTimeoutMs?: number
+  /** Cooperative timeout budget (ms) for `web_search`. Defaults to 30000. */
+  searchTimeoutMs?: number
+  /** Cap on source characters converted and complete `web_fetch` output characters. Defaults to 200000. */
+  fetchMaxOutputChars?: number
+}
+```
+
+来源：[`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-workflow`
+
+需要：`tools` · `workflows` · `systemPrompt`
+
+```ts config-catalog
+/** Config: the model-facing tool name plus result rendering caps. */
+export interface Config {
+  /** The model-facing tool name to register (default `workflow`). */
+  toolName?: string
+  /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */
+  maxResultChars?: number
+}
+```
+
+来源：[`packages/workflow/tool-workflow/src/index.ts:27`](../packages/workflow/tool-workflow/src/index.ts)
+
+## `@deepseek-ai/dsh-tools`
+
+需要：`systemPrompt`
+
+```ts config-catalog
+/** Plugin config: how the registered tools are presented to the model. */
+export interface Config {
+  /**
+   * Model presentation. `native` (default) sends every visible schema; `code`
+   * sends only `run_code` plus a generated SDK prompt; `both` sends both forms.
+   * Code modes require a `ctx.codeRuntime` whose `language` has a registered
+   * SDK renderer (TypeScript or Python) and fail prompt assembly when it is
+   * absent or has no renderer. Under `code`, native names in `toolOrder` are invalid.
+   */
+  mode?: ToolPresentationMode
+  /**
+   * Concurrency cap for a `run_code` program's overlapping sub-calls
+   * (default 10, the loop scheduler's own default). Sub-calls follow the
+   * native scheduling contract — only calls whose tools classify
+   * concurrency-safe overlap; exclusive calls form barriers — so `1`
+   * restores strictly serial dispatch. Must be a positive integer.
+   */
+  maxParallelSubCalls?: number
+}
+
+/** How the registry presents its tools to the model (see {@link Config.mode}). */
+export type ToolPresentationMode = 'native' | 'code' | 'both'
+```
+
+来源：[`packages/core/tools/src/index.ts:616`](../packages/core/tools/src/index.ts)
+
+## `@deepseek-ai/dsh-typert-loader`
+
+需要：`typert` · `loader`
+
+```ts config-catalog
+/** Additional package artifacts whose owning plugins are nested behind another Loader entry. */
+export interface Config {
+  /** Exact npm package names that must resolve and export `./typert`. */
+  packages?: string[]
+}
+```
+
+来源：[`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
+
+## `@deepseek-ai/dsh-user-approval`
+
+```ts config-catalog
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+  /**
+   * The deployment's default {@link ApprovalPolicy} for sessions without an
+   * `approval/policy` override — `'ask'` delegates to the composed answerers
+   * (fail-closed with none); `'never'` auto-rejects every ask without
+   * prompting (the deterministic CI/unattended stance).
+   */
+  readonly policy?: ApprovalPolicy
+}
+
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`
+ *   (exactly today's behavior).
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the policy whose outcome is knowable without asking.
+ */
+export type ApprovalPolicy = 'ask' | 'never'
+```
+
+来源：[`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
+
+## `@deepseek-ai/dsh-web`
+
+```ts config-catalog
+/**
+ * Config for the web seam. `searchProvider` / `fetchProvider` pin which provider
+ * wins for each capability; both are optional (a single registered usable
+ * provider auto-selects). Operational overrides such as environment variables
+ * must feed these same fields rather than introduce a hidden priority chain.
+ */
+export interface WebServiceConfig {
+  /** Explicit search provider id. Omitted = auto-select when exactly one usable. */
+  readonly searchProvider?: string
+  /** Explicit fetch provider id. Omitted = auto-select when exactly one usable. */
+  readonly fetchProvider?: string
+}
+```
+
+来源：[`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts)
+
+## `@deepseek-ai/dsh-web-app`
+
+需要：`httpServer`
+
+```ts config-catalog
+/** 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[]
+}
+
+/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
+export type WebMode = 'production' | 'development'
+```
+
+来源：[`packages/bundle/web-app/src/index.ts:32`](../packages/bundle/web-app/src/index.ts)
+
+## `@deepseek-ai/dsh-web-fetch-local`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
+export interface Config {
+  /** Maximum accepted request URL length. */
+  maxUrlLength?: number
+  /** Maximum response body size in bytes. */
+  maxResponseBytes?: number
+  /** Maximum decoded body length in characters. */
+  maxBodyChars?: number
+  /** Default fetch timeout in milliseconds, within Node's timer range. */
+  timeoutMs?: number
+  /** Maximum number of same-origin redirect hops to follow. */
+  maxRedirects?: number
+  /** `User-Agent` header sent on every request. */
+  userAgent?: string
+}
+```
+
+来源：[`packages/web/web-fetch-local/src/index.ts:34`](../packages/web/web-fetch-local/src/index.ts)
+
+## `@deepseek-ai/dsh-web-search-deepseek`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+  /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+  apiKey?: string
+  /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
+  /** Anthropic-compatible endpoint base; `/messages` is appended. */
+  baseURL?: string
+  /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */
+  model?: string
+  /** `anthropic-version` header value. Defaults to `2023-06-01`. */
+  apiVersion?: string
+  /** Upper bound on generated tokens for the Messages request. Defaults to 4096. */
+  maxTokens?: number
+  /** Maximum `web_search` server-tool uses per request. Defaults to 5. */
+  maxUses?: number
+}
+```
+
+来源：[`packages/web/web-search-deepseek/src/index.ts:44`](../packages/web/web-search-deepseek/src/index.ts)
+
+## `@deepseek-ai/dsh-web-search-exa`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+  /** Exa API key. Falls back to `$EXA_API_KEY`. Empty → provider unavailable. */
+  apiKey?: string
+  /** Endpoint base; `/search` is appended. Defaults to the public API. */
+  baseURL?: string
+  /** Retrieval mode sent as Exa's `type`. Defaults to `auto`. */
+  searchType?: 'auto' | 'keyword' | 'neural'
+  /** Default result count when a request carries no `maxResults`. Omitted = none. */
+  numResults?: number
+  /** Highlight sentences requested per result. Defaults to 1. */
+  highlightsPerResult?: number
+}
+```
+
+来源：[`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
+
+## `@deepseek-ai/dsh-web-search-perplexity`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+  /** Perplexity API key. Falls back to `$PERPLEXITY_API_KEY`. Empty → unavailable. */
+  apiKey?: string
+  /** Endpoint base; `/chat/completions` is appended. Defaults to the public API. */
+  baseURL?: string
+  /** Search model name. Defaults to `sonar`. */
+  model?: string
+  /** Upper bound on generated answer tokens. Defaults to 1024. */
+  maxTokens?: number
+  /** Recency window sent as `search_recency_filter`. Omitted = no filter. */
+  searchRecency?: 'day' | 'week' | 'month' | 'year'
+}
+```
+
+来源：[`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
+
+## `@deepseek-ai/dsh-workflow-workerthread`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** The `ctx.subagents` provider children run on (default `spawn`). */
+  provider?: string
+  /** Concurrent `agent()` ceiling; `0` (the default) auto-resolves to `min(16, max(1, cores - 2))`. */
+  maxConcurrentAgents?: number
+  /** Total `agent()` calls one run may start — the runaway-loop backstop (default 1000). */
+  maxTotalAgents?: number
+  /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */
+  maxItemsPerCall?: number
+  /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */
+  syncTimeoutMs?: number
+  /**
+   * How long after a cancellation an unsettled script may keep running before
+   * the run force-settles `cancelled` and its worker is TERMINATED (default
+   * 5000 ms); also bounds `dispose()`.
+   */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/workflow/workflow-workerthread/src/index.ts:32`](../packages/workflow/workflow-workerthread/src/index.ts)
+
+## `@deepseek-ai/dsh-workspace-context`
+
+```ts config-catalog
+/** User-facing workspace instruction loader configuration. */
+export interface Config {
+  /** Harness home containing the fixed user-global `AGENTS.md`; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Directory entries that identify the project root while walking upward from the session cwd. */
+  projectRootMarkers?: string[]
+  /** UTF-8 byte cap for one rendered baseline or dynamic batch; non-positive or non-finite disables loading. */
+  maxBytes: number
+  /** Maximum UTF-8 bytes read from one instruction file; larger files are ignored. */
+  maxSourceBytes?: number
+  /**
+   * Ordered same-directory project candidates; every existing file loads, with
+   * per-directory trimmed-content duplicates collapsed to the earliest candidate.
+   */
+  instructionFileCandidates?: string[]
+  /**
+   * Ordered same-directory local-overlay candidates loaded after the base files
+   * under the same per-directory trimmed-content dedup; empty disables the overlay.
+   */
+  localInstructionFileCandidates?: string[]
+}
+```
+
+来源：[`packages/context/workspace-context/src/config.ts:18`](../packages/context/workspace-context/src/config.ts)
+
+## 无配置的可加载插件
+
+这些插件通过不含 `config:` 块的 `cordis.yml` 条目加载；它们未声明任何配置接口。
+
+- `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)）
+- `@deepseek-ai/dsh-api-gateway` — 需要 `typert`（[`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts)）
+- `@deepseek-ai/dsh-api-remotes`（[`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts)）
+- `@deepseek-ai/dsh-client-locale`（[`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)）
+- `@deepseek-ai/dsh-client-modules` — 需要 `httpServer` · `loader`（[`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)）
+- `@deepseek-ai/dsh-client-runtime`（[`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-command`（[`packages/client/ui-command/src/index.ts`](../packages/client/ui-command/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-conversation`（[`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-deliverables`（[`packages/client/ui-deliverables/src/index.ts`](../packages/client/ui-deliverables/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-goal`（[`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-layout`（[`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-model`（[`packages/client/ui-model/src/index.ts`](../packages/client/ui-model/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-models`（[`packages/client/ui-models/src/index.ts`](../packages/client/ui-models/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-permission`（[`packages/client/ui-permission/src/index.ts`](../packages/client/ui-permission/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-plan`（[`packages/client/ui-plan/src/index.ts`](../packages/client/ui-plan/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-question` — 需要 `tools` · `userInteraction`（[`packages/client/ui-question/src/index.ts`](../packages/client/ui-question/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-settings`（[`packages/client/ui-settings/src/index.ts`](../packages/client/ui-settings/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-settings-general`（[`packages/client/ui-settings-general/src/index.ts`](../packages/client/ui-settings-general/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-sidebar`（[`packages/client/ui-sidebar/src/index.ts`](../packages/client/ui-sidebar/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-skill`（[`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-slash`（[`packages/client/ui-slash/src/index.ts`](../packages/client/ui-slash/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-subagent`（[`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-theme`（[`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-tool`（[`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-trajectory`（[`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-workspace`（[`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts)）
+- `@deepseek-ai/dsh-command-compact` — 需要 `commands` · `compact`（[`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts)）
+- `@deepseek-ai/dsh-command-feedback` — 需要 `commands`（[`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts)）
+- `@deepseek-ai/dsh-command-goal` — 需要 `commands` · `goals`（[`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts)）
+- `@deepseek-ai/dsh-commands`（[`packages/interaction/commands/src/index.ts`](../packages/interaction/commands/src/index.ts)）
+- `@deepseek-ai/dsh-fs-e2b` — 需要 `e2b`（[`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts)）
+- `@deepseek-ai/dsh-fs-policy`（[`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts)）
+- `@deepseek-ai/dsh-goal-session` — 需要 `agents` · `goals` · `sessions`（[`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts)）
+- `@deepseek-ai/dsh-host-directory-picker-auto` — 需要 `httpServer` · `loader`（[`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts)）
+- `@deepseek-ai/dsh-host-directory-picker-native`（[`packages/host/directory-picker-native/src/index.ts`](../packages/host/directory-picker-native/src/index.ts)）
+- `@deepseek-ai/dsh-llm`（[`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts)）
+- `@deepseek-ai/dsh-lsp`（[`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts)）
+- `@deepseek-ai/dsh-pty`（[`packages/pty/pty/src/index.ts`](../packages/pty/pty/src/index.ts)）
+- `@deepseek-ai/dsh-session`（[`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts)）
+- `@deepseek-ai/dsh-session-checkpoint-policy` — 需要 `llm` · `sessionPersistence` · `sessions` · `tools`（[`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts)）
+- `@deepseek-ai/dsh-session-projection`（[`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts)）
+- `@deepseek-ai/dsh-skill-badge` — 需要 `skills`（[`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts)）
+- `@deepseek-ai/dsh-storage`（[`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts)）
+- `@deepseek-ai/dsh-subagent`（[`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)）
+- `@deepseek-ai/dsh-subprocess-local`（[`packages/subprocess/subprocess-local/src/index.ts`](../packages/subprocess/subprocess-local/src/index.ts)）
+- `@deepseek-ai/dsh-tasks-local`（[`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts)）
+- `@deepseek-ai/dsh-timeout-policy` — 需要 `tools`（[`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts)）
+- `@deepseek-ai/dsh-tool-ask-user` — 需要 `tools` · `userInteraction`（[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)）
+- `@deepseek-ai/dsh-tool-subagent-control` — 需要 `tools` · `subagents`（[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)）
+- `@deepseek-ai/dsh-user-interaction`（[`packages/interaction/user-interaction/src/index.ts`](../packages/interaction/user-interaction/src/index.ts)）
+- `@deepseek-ai/dsh-workspace` — 需要 `storageDomain` · `sessionPersistence`（[`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts)）
+
+## Seam 包（不可直接加载）
+
+抽象服务类——部署时应改为加载具体的实现包（参见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）。
+
+- `@deepseek-ai/dsh-bash` — 抽象 `BashExecutor`（[`packages/bash/bash/src/index.ts`](../packages/bash/bash/src/index.ts)）
+- `@deepseek-ai/dsh-code-runtime` — 抽象 `CodeRuntime`（[`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)）
+- `@deepseek-ai/dsh-compact` — 抽象 `CompactService`（[`packages/compact/compact/src/index.ts`](../packages/compact/compact/src/index.ts)）
+- `@deepseek-ai/dsh-credentials` — 抽象 `Credentials`（[`packages/credentials/credentials/src/index.ts`](../packages/credentials/credentials/src/index.ts)）
+- `@deepseek-ai/dsh-fs` — 抽象 `FileSystem`（[`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts)）
+- `@deepseek-ai/dsh-host-directory-picker` — 抽象 `DirectoryPicker`（[`packages/host/directory-picker/src/index.ts`](../packages/host/directory-picker/src/index.ts)）
+- `@deepseek-ai/dsh-sandbox` — 抽象 `SandboxProvider`（[`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts)）
+- `@deepseek-ai/dsh-session-persistence` — 抽象 `SessionPersistence`（[`packages/session/session-persistence/src/index.ts`](../packages/session/session-persistence/src/index.ts)）
+- `@deepseek-ai/dsh-session-query` — 抽象 `SessionQueryService`（[`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts)）
+- `@deepseek-ai/dsh-settings` — 抽象 `Settings`（[`packages/settings/settings/src/index.ts`](../packages/settings/settings/src/index.ts)）
+- `@deepseek-ai/dsh-spill` — 抽象 `SpillStore`（[`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts)）
+- `@deepseek-ai/dsh-subprocess` — 抽象 `SubprocessService`（[`packages/subprocess/subprocess/src/index.ts`](../packages/subprocess/subprocess/src/index.ts)）
+- `@deepseek-ai/dsh-tasks` — 抽象 `TaskService`（[`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts)）
+- `@deepseek-ai/dsh-workflow` — 抽象 `WorkflowService`（[`packages/workflow/workflow/src/index.ts`](../packages/workflow/workflow/src/index.ts)）
+## 库包（无插件入口）
+
+由其他包作为库导入；`cordis.yml` 无法加载它们。
+
+- `@deepseek-ai/create-sdk`（[`packages/scaffold/create-sdk/src/index.ts`](../packages/scaffold/create-sdk/src/index.ts)）
+- `@deepseek-ai/dsh-acp-snapshot`（[`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts)）
+- `@deepseek-ai/dsh-agent-loop-testkit`（[`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts)）
+- `@deepseek-ai/dsh-app-boot`（[`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts)）
+- `@deepseek-ai/dsh-atomic-write`（[`packages/util/atomic-write/src/index.ts`](../packages/util/atomic-write/src/index.ts)）
+- `@deepseek-ai/dsh-base`（[`packages/bundle/base/src/index.ts`](../packages/bundle/base/src/index.ts)）
+- `@deepseek-ai/dsh-brand`（[`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts)）
+- `@deepseek-ai/dsh-client-schema-form`（[`packages/client/schema-form/src/index.ts`](../packages/client/schema-form/src/index.ts)）
+- `@deepseek-ai/dsh-client-test-runtime`（[`packages/client/test-runtime/src/index.ts`](../packages/client/test-runtime/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-primitives`（[`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-slots`（[`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts)）
+- `@deepseek-ai/dsh-client-web`（[`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)）
+- `@deepseek-ai/dsh-client-web-react`（[`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts)）
+- `@deepseek-ai/dsh-environment`（[`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts)）
+- `@deepseek-ai/dsh-helper`（[`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts)）
+- `@deepseek-ai/dsh-hook-protocol`（[`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)）
+- `@deepseek-ai/dsh-jsonrpc-demo`（[`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts)）
+- `@deepseek-ai/dsh-llm-mock-server`（[`packages/support/llm-mock-server/src/index.ts`](../packages/support/llm-mock-server/src/index.ts)）
+- `@deepseek-ai/dsh-loader-smoke`（[`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts)）
+- `@deepseek-ai/dsh-native-command`（[`packages/util/native-command/src/index.ts`](../packages/util/native-command/src/index.ts)）
+- `@deepseek-ai/dsh-paths`（[`packages/util/paths/src/index.ts`](../packages/util/paths/src/index.ts)）
+- `@deepseek-ai/dsh-retention`（[`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts)）
+- `@deepseek-ai/dsh-scope`（[`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts)）
+- `@deepseek-ai/dsh-scripts`（[`packages/scaffold/scripts/src/index.ts`](../packages/scaffold/scripts/src/index.ts)）
+- `@deepseek-ai/dsh-sdk-client`（[`packages/scaffold/client/src/index.ts`](../packages/scaffold/client/src/index.ts)）
+- `@deepseek-ai/dsh-sdk-protocol`（[`packages/scaffold/protocol/src/index.ts`](../packages/scaffold/protocol/src/index.ts)）
+- `@deepseek-ai/dsh-session-telemetry`（[`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts)）
+- `@deepseek-ai/dsh-session-title-llm`（[`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts)）
+- `@deepseek-ai/dsh-subagent-inprocess`（[`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts)）
+- `@deepseek-ai/dsh-telemetry`（[`packages/scaffold/telemetry/src/index.ts`](../packages/scaffold/telemetry/src/index.ts)）
+- `@deepseek-ai/dsh-timeout`（[`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts)）
+- `@deepseek-ai/dsh-type-meta`（[`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts)）
+- `@deepseek-ai/dsh-typert-generator`（[`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts)）
+- `@deepseek-ai/dsh-typert-registry`（[`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts)）
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 0c26b8be17..53970e8479 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
 adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
-adding-a-package.zh.md: 8c0bc9dbd02b18a388f8e6ce91af10753c0210a2
+adding-a-package.zh.md: c076a58280aef8b218bc16af33eab233724bd57f
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 8c0bc9dbd0..c076a58280 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -1,8 +1,8 @@
-# 实操手册：添加 workspace 包（package）
+# 实操手册：添加 workspace 包
 
 [English](adding-a-package.md) | 中文
 
-为新建 `@deepseek-ai/dsh-<name>` 包提供的逐文件清单。本清单以 bash 和 adapter 这两个包为模板进行验证；如果清单与模板有出入，请在此修正。
+为新建 `@deepseek-ai/dsh-<name>` 包提供的逐文件清单。本清单以 bash 和适配器这两个包为模板进行验证；如果清单与模板有出入，请在此修正。
 
 ## 1. 创建包
 
@@ -22,7 +22,7 @@ packages/<group>/<pkg>/
 
 当已有分组与包的角色匹配时，选择该分组（`core`、`llm`、`bash`、`compact`、`subagent`、`todo`、`session-persistence`、`ui`、`util` 或 `support`）。允许新建分组，但分组只是纯容器：没有 `package.json`，没有源文件，包仍然恰好位于其下一层。
 
-package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表精确包含 `lib/index.js`、`lib/invariant.js`、`lib/types/**/*.d.ts` 以及门禁认可的包专用运行时产物；如果包的运行时 export 指向输出树，还要包含 `lib/types/**/*.js`。不要发布 `src`、声明映射、JS map 或陈旧的根声明文件。带有 `bin` 的 CLI 应用包在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。
+package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表精确包含 `lib/index.js`、`lib/invariant.js`、`lib/types/**/*.d.ts` 以及门禁认可的包专用运行时产物；如果包的运行时 export 指向输出树，还要包含 `lib/types/**/*.js`。不要发布 `src`、声明映射、JS map 或陈旧的根声明文件。带有 `bin` 的 CLI（命令行界面）应用包在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。
 
 包内的相对导入在源码中使用显式 `.ts` 后缀（例如 `export * from './types.ts'`）。编译器在输出的 JS 中将其重写为 `.js`，在声明文件中保留显式 `.ts` 后缀；标准的 NodeNext/Node16 TypeScript 消费方会将其解析到同目录的 `.d.ts` 文件。
 
@@ -31,16 +31,16 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 | 文件 | 变更 |
 |---|---|
 | `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
-| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成契约与 Client 消费契约之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
+| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成的契约产物要到后续阶段才由 Client 消费而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
 | `knip.json` | 仅当包有仓库发现机制尚未覆盖的入口时需要 |
 
-`packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
+`packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧约定见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
 
-以下内容由 glob 或包 manifest 发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`.oxlintrc.json`、`scripts/check-workspace-constraints.ts`。
+以下内容由 glob 或包 manifest（元数据清单）发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`.oxlintrc.json`、`scripts/check-workspace-constraints.ts`。
 
 ## 3. 确定包拓扑
 
-对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
+对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md §「能力 seam」——bash 三组件是模板）。单一用途的插件保持为一个包。
 
 ## 4. 编写包 README
 
@@ -74,9 +74,9 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.
 ````
 
-根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包契约。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
+根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。工具 schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏提示词或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。「不使缓存失效」仅表示本包保留了已有的可复用前缀；提供方缓存是否可用以及何时淘汰不属于本包约定。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
 
-没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
+没有上下文效果或仅有一条由消费方拥有的路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
 
 ## 5. 验证
 
@@ -87,4 +87,4 @@ pnpm run constraints && pnpm run typecheck && pnpm run lint
 pnpm run build && pnpm run hygiene
 ```
 
-请遵循[仓库测试政策](../testing.md)，为新包运行行为所需的专项检查并达到相应覆盖率。
+请遵循[仓库测试政策](../testing.md)，执行新包所需的针对具体行为的检查，并达到相应覆盖率。
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index ca64363bd6..018f97fc45 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-tool.md
 adding-a-tool.md: cb418a9118901cc6572fb17125351bdda922434b
-adding-a-tool.zh.md: d8b73a51d1dde8647e7a032648f8a6344fcc83eb
+adding-a-tool.zh.md: adf4422688498341343e3317cb36aa23ece72734
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index d8b73a51d1..adf4422688 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -2,7 +2,7 @@
 
 [English](adding-a-tool.md) | 中文
 
-面向模型的工具必须满足哪些契约，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
+面向模型的工具必须满足哪些约定，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
 
 ## 最小形态
 
@@ -37,7 +37,7 @@ export function apply(ctx: Context) {
 
 注册基于副作用：dispose（资源释放）插件 fiber 即注销该工具。schema 会自动流入系统提示词的组装过程。
 
-## execute() 契约的规则
+## execute() 约定的规则
 
 - **参数已为你校验。** `defineTool` 在 `execute` 运行前，会根据统一的 `ParameterSchemaSpec` 校验模型生成的 `arguments`（类型、必填键、字面量约束、恰好匹配一个分支的联合以及嵌套值——见[运行时参数校验](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)），因此 `execute` 内的 args 会匹配 `InferArgs`。显式对象节点必须声明 `additionalProperties: true | false`；隐式参数根对象保持开放。你仍需手动检查 schema DSL 无法表达的约束，例如非空字符串、正数或跨字段规则。直接注册的原始 JSON Schema 工具自行负责输入校验。
 - **注册借用你的只读定义。** 类型化的同进程贡献不是序列化边界；注册后不要修改其 schema 或替换回调。`schemas()` 只物化显式的模型可见投影。如需热替换工具，请 dispose 其所属副作用并注册替代品；回调闭包内的可变状态仍是普通的插件状态。
@@ -52,17 +52,17 @@ export function apply(ctx: Context) {
 
 通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', taskId }`；其 Native 渲染器可以保留 `started background task bash-1` 这类供人阅读的自然语言，但 Code Mode 绝不能通过解析该文本取得 id。
 
-producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整契约见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
+producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
 ## 执行策略与观测
 
-尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
+尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切约定见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
 
 ## Code Mode 自动触达你的工具
 
 在 [Code Mode](../../packages/core/tools/README.md) 中，每个可见的已注册工具都可通过 `await tools.<name>(args)` 调用，无需额外集成。生成的 `ToolArgsMap` 和 `ToolOutputMap` 会根据同一组 schema 分别派生精确的参数类型与规范返回类型，调用则重新进入正常的执行流水线。成功调用会解析为策略处理后的最终规范 JSON 值，而不是渲染后的 Native 内容。失败调用会以真正的 `ToolCallError` reject；程序只能检查其 `name`、`toolName` 和可供人阅读的 `message`，无法取得内部错误代码或失败联合。
 
-请把 `output.schema` 设计为实用的程序化 API：直接返回句柄与字段；当标量、数组或 null 确实就是结果时，允许采用相应的根类型；将面向人类的解释放入 `output.render`。中间值只存在于执行期间，不会被持久化或按提示词上限截断，也不设字节上限，因此生产方如实声明的采集边界和进程内存仍然重要。只有外层 `run_code` 日志／结果会受到可配置输出上限和面向模型的输出落盘流水线约束。
+请把 `output.schema` 设计为实用的程序化 API：直接返回句柄与字段；当标量、数组或 null 确实就是结果时，允许采用相应的根类型；将面向人类的解释放入 `output.render`。中间值只存在于执行期间，不会被持久化或按提示词上限截断，也不设字节上限，因此生产方如实声明的采集边界和进程内存仍然重要。只有外层 `run_code` 日志／结果会受到可配置输出上限和面向模型的 spill 流水线约束。
 
 ## 工具在 UI 中的渲染方式
 
@@ -71,19 +71,19 @@ producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的
 两个方法都返回一个 **`card` 标签的渲染意图**——选择与你的工具行为匹配的卡片类型：
 
 - `presentCall(args)` → 一个 `ToolCallView`（PENDING 卡片）：
-  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`——默认。设置 `kind` 获取图标（`read`/`search`/…）；设置 `locations: [{ path, line? }]` 标注工具涉及的文件，使有能力的编辑器跟随/跳转。
+  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`——默认。设置 `kind` 获取图标（`read`／`search`／…）；设置 `locations: [{ path, line? }]` 标注工具涉及的文件，使有能力的编辑器跟随／跳转。
   - `{ card: 'terminal', title, description?, cwd? }`——你的调用本身就是 shell 命令。`title` 是命令，`description` 渲染在终端卡片上方。（tool-bash。）
-  - `{ card: 'diff', title, diffs, locations? }`——你的调用创建或修改文件。`diffs: [{ path, oldText, newText }]`（新文件时 `oldText: null`）渲染为内联 diff 卡片。（tool-fs `write`/`edit`。）
+  - `{ card: 'diff', title, diffs, locations? }`——你的调用创建或修改文件。`diffs: [{ path, oldText, newText }]`（新文件时 `oldText: null`）渲染为内联 diff 卡片。（tool-fs `write`／`edit`。）
 - `presentResult(args, { content, isError, meta? })` 返回完成后的卡片：
   - `generic` 提供可选的标题和内容。
   - `terminal` 提供原始输出和可选的退出元数据；各 UI 根据自身能力渲染对应视图或回退视图。
   - `diff` 提供已应用的 hunk，通常由 `output.presentationMeta` 派生并通过持久化的 `result.meta` 携带，使回放能重现它们。变更类工具保留 diff 结果，因为完成后的视图会替换 pending 卡片。
-  - `search` 提供从持久化 `result.meta` 重建的发现型结果：按文件分组的匹配（`shape: 'matches'`，grep）或扁平路径列表（`shape: 'paths'`，glob），外加 `truncated`/`total` 使 UI 永不把被截断的结果当作完整结果呈现。该视图不携带结果文本（无 search 卡片的 UI 回退到原始结果内容），也没有 `search` 调用视图——发现型调用的 pending 状态保持为 generic 卡片，因为匹配只在 `execute` 之后才存在。（tool-fs-search 的 `grep`/`glob`。）
+  - `search` 提供从持久化 `result.meta` 重建的发现型结果：按文件分组的匹配（`shape: 'matches'`，grep）或扁平路径列表（`shape: 'paths'`，glob），外加 `truncated`／`total` 使 UI 永不把被截断的结果当作完整结果呈现。该视图不携带结果文本（无 search 卡片的 UI 回退到原始结果内容），也没有 `search` 调用视图——发现型调用的 pending 状态保持为 generic 卡片，因为匹配只在 `execute` 之后才存在。（tool-fs-search 的 `grep`／`glob`。）
   - `web` 提供已完成的 web 检索，以 `kind: 'search' | 'fetch'` 区分（结构化的搜索来源或抓取摘要），由 `result.meta` 派生；它不携带正文副本，因此不具备 `web` 能力的 UI 回退到原始结果内容。（tool-web `web_search`／`web_fetch`。）
 
 硬性规则（违反会出问题）：
 
-- **纯函数。** 这些方法在实时流式输出和会话日志回放时都会运行，因此必须是 `args`（加 result）的纯函数——不做 I/O、不读会话状态、不用时钟/随机数。diff 从 args 派生（`write` 使用 `oldText: null`，因为调用时的展示器没有文件先前内容）；会话上下文由 UI 适配器而非工具提供。如果你发现自己想在 `presentCall` 内获取文件旧内容或工作目录，请停下：那属于持久结果元数据或适配器，不属于展示器。
+- **纯函数。** 这些方法在实时流式输出和会话日志回放时都会运行，因此必须是 `args`（加 result）的纯函数——不做 I/O、不读会话状态、不用时钟／随机数。diff 从 args 派生（`write` 使用 `oldText: null`，因为调用时的展示器没有文件先前内容）；会话上下文由 UI 适配器而非工具提供。如果你发现自己想在 `presentCall` 内获取文件旧内容或工作目录，请停下：那属于持久结果元数据或适配器，不属于展示器。
 - **UI 格式不进入模型结果。** 围栏 ` ```console ` 块、diff、相对化路径均不应仅为服务 UI 而进入规范值或 Native 内容。`output.render` 负责模型可见的自然语言；`presentationMeta` 和卡片展示器负责可回放的 UI 状态。`terminal` 结果视图携带原始输出，由适配器按需添加回退格式。
 - **`defineTool` 对展示路径做软校验。** 格式错误或旧版日志中的 arg 形态会使包装器返回 `undefined`（通用回退）而非抛异常——展示绝不能导致回放崩溃。
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index e341244f40..c053132c54 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
 extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
-extension-cookbook.zh.md: c2fa2f83c39ca0eb93397f39c88265c028224c7a
+extension-cookbook.zh.md: 83521cd348c68ba6f20f5beecfbcde51b0f2fb02
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index c2fa2f83c3..83521cd348 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -6,7 +6,7 @@ harness 扩展表面的参考形态。代码片段省略了 import 和辅助实
 
 ## 工具插件
 
-工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON-Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。
+工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。
 
 ## 钩子插件（以权限门禁为例）
 
@@ -64,7 +64,7 @@ export function apply(ctx: Context) {
 
 *协议驱动*将协议对端接入 `ctx.agents`；它可以服务于 UI 或自动化客户端。stdio 驱动拥有 stdout，通过工厂创建或恢复 agent（智能体），并将协议请求映射为 `followup()` 或 `cancel()`。底层提示词请求返回其持久入队回执；它不会通过关联 `MessageId` 与 `turn/end` 获得结果。整个 agent 的状态应单独发布。自动化方法可以从回执等待到下一次 idle，并概括这一显式拥有的区间；UI 通常则会持续观察开放式事件流。通过 `AgentHandle.dispose()` 拆除 agent，以使 dispose（资源释放）达到完全停稳。
 
-[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期契约。
+[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期约定。
 
 ```ts
 import type { Context } from 'cordis'
@@ -100,29 +100,29 @@ export function apply(ctx: Context) {
 
 | 产品功能 | 插件机制 |
 |---|---|
-| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall seam 返回类型化决策，`agent/turn-stopping` 则可通过 steering 触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
-| `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话回合，独立的命令/工具生产方分别提供人类/模型控制 |
+| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall seam 返回类型化决策，`agent/turn-stopping` 则可通过 steering（中途引导）触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
+| `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话 Round，独立的命令/工具生产方分别提供人类/模型控制 |
 | `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
-| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的 prompt/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
-| 排队消息 + steering（中途引导） | 核心 `Agent.followup()` / `Agent.steer()` |
+| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
+| 排队消息 + steering | 核心 `Agent.followup()` / `Agent.steer()` |
 | 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/pre-step`，规范化溢出恢复运行在 `agent/request-error`，手动调用方使用同一个压缩服务（[压缩 Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)——面向模型的 `/compact` 消费方工具已推迟） |
 | 系统提示词可配置性 | `ctx.systemPrompt.section()`，支持排序与作用域局部覆盖 |
-| AGENTS.md（根目录） | 一个读取该文件的 section provider |
-| AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / tool-result 监听器调用 `agent.inject()` |
+| AGENTS.md（根目录） | 一个读取该文件的 section 提供方 |
+| AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / 工具结果监听器调用 `agent.inject()` |
 | 内置工具 | `ctx.tools.register()`；schema 自动流入装配——`dsh-tool-*` 系列（bash、fs、web、subagent、todo）是已交付的示例 |
 | ToolSearch / 渐进式披露 | 当可见集变化时替换一个作用域化的 `ctx.tools.restrict()` 注册；注册表保持展示、查找和执行三者对齐 |
-| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装器可替换 `exec.signal`、委托执行，并在同一词法生命周期内检视规范化结果 |
+| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装层可替换 `exec.signal`、委托执行，并在同一词法生命周期内检视规范化结果 |
 | 最终工具结果指标 / 审计 / 捕获 | 用 `tools/result` 观察不可变的权威结果；仅当插件需要变换结果或附加上下文时才使用 `tools/post-execute` |
 | 单调终端轮次策略 | 从成功的终端工具调用 `ToolExecution.concludeTurn()`；同一响应中后续工具调用仍可由守卫阻止，循环在该步骤后停止 |
 | 子进程沙箱（landlock / sandbox-exec） | 通过 `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
 | 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
-| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — 落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
-| 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
+| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md)：落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
+| subagent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
 | MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
-| Skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
-| 记忆 | section provider + 工具 |
+| skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
+| 记忆 | section 提供方 + 工具 |
 | 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `followup(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
 | UI（GUI；CLI（命令行界面）输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `followup()` |
 | 遥测 / 可回放 trace | `session/event` → JSONL；回放 = `sessions.create(id, { seed })` |
 | 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek`、`dsh-llm-pi-ai`） |
-| 插件热重载 | 每个注册都是一个 `ctx.effect` → vendor 的 HMR（热模块替换）直接生效 |
+| 插件热重载 | 每个注册都是一个 `ctx.effect` → 随仓库提供的 HMR（热模块替换）直接生效 |
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
index 86a72161b2..7757b8419d 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/responding-to-pr-review-on-a-stack.md
 responding-to-pr-review-on-a-stack.md: 6bb7be3daf8613666f02f21e96bf7b1ac8cb3606
-responding-to-pr-review-on-a-stack.zh.md: 94c2bd2cdd03b9eeca1e180b09bb71471db91c0a
+responding-to-pr-review-on-a-stack.zh.md: 7567220096bb9dd6f3f68c16c08493ffb7529de7
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
index 94c2bd2cdd..7567220096 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
@@ -15,11 +15,11 @@
 ## 沿堆叠解决评审意见
 
 1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。
-2. 将每个被接受的发现映射到其发起 PR，并在那里修复。
+2. 将每个被接受的发现映射到引入该问题的 PR，并在那里修复。
 3. 将修复后的层按顺序传播到每个受影响的子 PR：
    - **Merge-forward：** 将修复后的父分支合并到其子分支，验证子分支，然后继续沿堆叠向上传播。依照[增量更新 base 的决策](../../.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)，保留每个正在处理的检查点。
    - **原生级联 rebase：** 使用 `gh stack rebase`，验证所有已改写的层，然后通过 `gh stack push` 发布；也可以使用 `gh stack sync`，该命令可能先发布，因此必须按照 [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md) 在同步后立即验证。
-4. 委派的修复需要信任但验证：子 agent（智能体）的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。子 agent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
+4. 委派的修复需要信任但验证：subagent的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
 5. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及当前承载修复的 commit 或 head。
 6. 每次改写推送后，都要重新读取未解决线程、批准状态、可合并性和检查结果。经 force-push 改写的 commit OID 或已过时的内联锚点，都不足以证明该发现当前仍处于已解决状态。
 7. 仅可通过官方堆叠流程落地。如果这些 PR 尚未关联，落地 skill 会自动关联作者相同的链；如果作者不同，则先询问用户；如果原生堆叠支持不可用，则硬性停止流程。
diff --git a/docs/cordis-api/context.i18n.yaml b/docs/cordis-api/context.i18n.yaml
new file mode 100644
index 0000000000..618b112792
--- /dev/null
+++ b/docs/cordis-api/context.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 docs/cordis-api/context.md
+context.md: 320b23de1c8d19e2dacdf0ec9f2361037bcf8048
+context.zh.md: 2e4cdc1d2822d6cc19bf1907a44cc31c429016ea
diff --git a/docs/cordis-api/context.zh.md b/docs/cordis-api/context.zh.md
new file mode 100644
index 0000000000..2e4cdc1d28
--- /dev/null
+++ b/docs/cordis-api/context.zh.md
@@ -0,0 +1,366 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/context.md` 重新记录配对。 -->
+
+# 上下文
+
+[English](context.md) | 中文
+
+上下文是 Cordis 的核心对象：所有服务、事件和生命周期 API 都通过 `ctx` 访问。事件方法见[事件](events.md)，副作用与当前 fiber 见 [Fiber](fiber.md)，插件加载见[注册表](registry.md)。
+
+Cordis 插件的根依赖容器和子依赖容器。
+
+上下文是一个代理：普通属性读取通过服务解析器进行，而 `extend()`、`isolate()` 和 `intercept()` 会创建有作用域的子上下文，且不修改其父上下文。
+
+[源码](../../vendor/cordis/src/context.ts#L42)
+
+### ctx.extend(meta?)
+
+```ts cordis-catalog
+/**
+ * Create a child context with extra metadata on top of the current scope.
+ *
+ * The child prototypally inherits every property of this context; own
+ * properties of `meta` shadow the inherited ones. The parent is not mutated.
+ *
+ * @param meta — own properties (including symbol keys) to define on the child.
+ * @returns a child context inheriting from this one.
+ */
+extend(meta = {}): this
+```
+
+在当前作用域之上创建一个带有额外元数据的子上下文。
+
+子上下文通过原型继承当前上下文的所有属性；`meta` 的自有属性会遮蔽继承的同名属性。父上下文不会被修改。
+
+- `meta`：要在子上下文上定义的自有属性，包括以 symbol 为键的属性。
+
+**返回**继承自当前上下文的子上下文。
+
+[源码](../../vendor/cordis/src/context.ts#L99)
+
+### ctx.isolate(name, label?)
+
+```ts cordis-catalog
+/**
+ * Create a child context with an independent service scope for `name`.
+ *
+ * Below the returned context, reads and writes of the service `name`
+ * resolve against the new label instead of the parent's, so a different
+ * implementation can be provided without affecting the parent scope.
+ * Passing the same `label` to two `isolate()` calls joins their scopes.
+ *
+ * @param name — the service name to isolate.
+ * @param label — scope label to join; defaults to a fresh unique symbol.
+ * @returns a child context whose `name` service resolves in the new scope.
+ */
+isolate(name: string, label?: symbol)
+```
+
+创建一个子上下文，使 `name` 拥有独立的服务作用域。
+
+在返回的上下文之下，对服务 `name` 的读写会根据新标签解析，而不再根据父上下文的标签解析，因此可以提供不同的实现而不影响父作用域。向两次 `isolate()` 调用传入相同的 `label`，可使二者加入同一作用域。
+
+- `name`：要隔离的服务名称。
+- `label`：要加入的作用域标签；默认为一个新建的唯一 symbol。
+
+**返回**一个子上下文，其 `name` 服务在新作用域中解析。
+
+[源码](../../vendor/cordis/src/context.ts#L121)
+
+### ctx.intercept(name, config)
+
+```ts cordis-catalog
+/**
+ * Add service-specific intercept config for plugins started below this
+ * context.
+ *
+ * Plugins loaded under the returned context see `config` merged into the
+ * service's resolved config (ancestor entries first; see
+ * `Service[symbols.resolveConfig]`). The parent context is not affected.
+ *
+ * @param name — the service name whose config to intercept.
+ * @param config — the intercept config to merge for that service.
+ * @returns a child context carrying the additional intercept entry.
+ */
+intercept<K extends InjectKey>(name: K, config: Context[K] extends { [symbols.config]: infer T } ? T : never): this
+intercept(name: string, config: any): this
+```
+
+为在此上下文之下启动的插件添加服务专属的拦截配置。
+
+在返回的上下文下加载的插件会看到 `config` 已合并到服务解析后的配置中（祖先条目在前；见 `Service[symbols.resolveConfig]`）。父上下文不受影响。
+
+- `name`：要拦截其配置的服务名称。
+- `config`：要为该服务合并的拦截配置。
+
+**返回**一个携带额外拦截条目的子上下文。
+
+[源码](../../vendor/cordis/src/context.ts#L139)
+
+### ctx.root
+
+```ts cordis-catalog
+/** The root context of the application (every child context shares it). @experimental */
+root: this
+```
+
+应用的根上下文，所有子上下文均共享它。@experimental
+
+[源码](../../vendor/cordis/src/context.ts#L22)
+
+### ctx.baseUrl
+
+```ts cordis-catalog
+/** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
+baseUrl?: string
+```
+
+用于解析相对插件／模块说明符的基础 URL，前提是运行时设置了该值。
+
+[源码](../../vendor/cordis/src/context.ts#L24)
+
+### ctx.events
+
+```ts cordis-catalog
+/** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */
+events: EventsService
+```
+
+事件总线。它的方法也会混入 `ctx`（`ctx.on`、`ctx.emit` 等）。
+
+[源码](../../vendor/cordis/src/context.ts#L26)
+
+### ctx.logger
+
+```ts cordis-catalog
+/** The logging service. Call `ctx.logger(name)` for a named logger. */
+logger: LoggerService
+```
+
+日志服务。调用 `ctx.logger(name)` 可获取具名 logger。
+
+[源码](../../vendor/cordis/src/context.ts#L28)
+
+### ctx.reflect
+
+```ts cordis-catalog
+/** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */
+reflect: ReflectService
+```
+
+为上下文代理提供支持的反射层（`ctx.get`、`ctx.provide` 等）。
+
+[源码](../../vendor/cordis/src/context.ts#L30)
+
+### ctx.registry
+
+```ts cordis-catalog
+/** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */
+registry: RegistryService
+```
+
+插件注册表。它的方法会混入 `ctx`（`ctx.plugin`、`ctx.inject`）。
+
+[源码](../../vendor/cordis/src/context.ts#L32)
+
+## 静态成员
+
+### Context.effect
+
+```ts cordis-catalog
+/** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */
+static readonly effect: unique symbol
+```
+
+资源释放函数用于公开其 EffectMeta 诊断树的 symbol 键。
+
+[源码](../../vendor/cordis/src/context.ts#L44)
+
+### Context.filter
+
+```ts cordis-catalog
+/** Symbol key for a context's listener filter, consulted on every event dispatch. */
+static readonly filter: unique symbol
+```
+
+上下文监听器过滤器的 symbol 键，每次分派事件时都会查询该过滤器。
+
+[源码](../../vendor/cordis/src/context.ts#L46)
+
+### Context.isolate
+
+```ts cordis-catalog
+/** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */
+static readonly isolate: unique symbol
+```
+
+隔离映射的 symbol 键（见 `Context[symbols.isolate]` 属性）。
+
+[源码](../../vendor/cordis/src/context.ts#L48)
+
+### Context.intercept
+
+```ts cordis-catalog
+/** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */
+static readonly intercept: unique symbol
+```
+
+拦截映射的 symbol 键（见 `Context[symbols.intercept]` 属性）。
+
+[源码](../../vendor/cordis/src/context.ts#L50)
+
+### Context.is(value)
+
+```ts cordis-catalog
+/**
+ * Returns true for Cordis context proxies and context prototypes.
+ *
+ * Works across realms and across multiple copies of cordis, because the
+ * brand is keyed by a global symbol rather than by `instanceof`.
+ *
+ * @param value — the value to test.
+ * @returns `true` if `value` is a Cordis context, narrowing its type.
+ */
+static is(value: any): value is Context
+```
+
+对于 Cordis 上下文代理和上下文原型，返回 true。
+
+此方法可跨 realm 和多个 cordis 副本工作，因为其品牌标识以全局 symbol 为键，而不是通过 `instanceof` 判断。
+
+- `value`：要测试的值。
+
+如果 `value` 是 Cordis 上下文，**返回** `true`，并收窄其类型。
+
+[源码](../../vendor/cordis/src/context.ts#L61)
+
+## 服务存储与混入
+
+### ctx.get(name, strict?)
+
+```ts cordis-catalog
+/**
+ * Read a service from the store without the inject requirement.
+ *
+ * @param name — the service name.
+ * @param strict — when `true` (default), only return implementations
+ * whose providing fiber is currently active.
+ * @returns the service value, or `undefined` when not (yet) provided.
+ */
+get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
+get(name: string, strict?: boolean): any
+```
+
+从存储中读取服务，无需满足注入要求。
+
+- `name`：服务名称。
+- `strict`：设为 `true`（默认值）时，仅返回其提供方 fiber 当前处于活动状态的实现。
+
+**返回**服务值；如果尚未提供，则返回 `undefined`。
+
+[源码](../../vendor/cordis/src/reflect.ts#L17)
+
+### ctx.set(name, value)
+
+```ts cordis-catalog
+/**
+ * Overwrite a provided service's value.
+ *
+ * Only the fiber that provided the service may set it; setting an
+ * unprovided name throws.
+ *
+ * @param name — the service name.
+ * @param value — the new service value.
+ */
+set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
+set(name: string, value: any): void
+```
+
+覆盖已提供服务的值。
+
+只有提供该服务的 fiber 才能设置它；设置尚未提供的名称会抛出异常。
+
+- `name`：服务名称。
+- `value`：新的服务值。
+
+[源码](../../vendor/cordis/src/reflect.ts#L29)
+
+### ctx.provide(name, value)
+
+```ts cordis-catalog
+/**
+ * Register a service implementation owned by the current fiber.
+ *
+ * The service becomes visible to dependents in the same isolation scope
+ * once the fiber is active; it is unregistered (waking dependents) when
+ * the returned disposer runs or the fiber unloads. Throws if the name is
+ * already provided in this scope or declared as an accessor.
+ *
+ * @param name — the service name.
+ * @param value — the service value.
+ * @returns a disposer that unregisters the service.
+ */
+provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
+provide(name: string, value?: any): () => void
+```
+
+注册一个归当前 fiber 所有的服务实现。
+
+fiber 激活后，该服务对同一隔离作用域内的依赖方可见；当返回的资源释放函数运行或 fiber 卸载时，该服务会被取消注册，并唤醒依赖方。如果该名称已在此作用域中被提供，或已声明为访问器，则抛出异常。
+
+- `name`：服务名称。
+- `value`：服务值。
+
+**返回**一个用于取消注册该服务的资源释放函数。
+
+[源码](../../vendor/cordis/src/reflect.ts#L44)
+
+### ctx.accessor(name, options)
+
+```ts cordis-catalog
+/**
+ * Define a computed context property backed by get/set hooks.
+ *
+ * The accessor is removed when the current fiber unloads. Throws if the
+ * name is already declared.
+ *
+ * @param name — the context property name.
+ * @param options — the `get` hook and optional `set` hook.
+ */
+accessor(name: string, options: Omit<Property.Accessor, 'type'>): void
+```
+
+定义一个由 get/set 钩子支持的计算型上下文属性。
+
+当前 fiber 卸载时会移除该访问器。如果该名称已被声明，则抛出异常。
+
+- `name`：上下文属性名称。
+- `options`：`get` 钩子和可选的 `set` 钩子。
+
+[源码](../../vendor/cordis/src/reflect.ts#L56)
+
+### ctx.mixin(name, mixins)
+
+```ts cordis-catalog
+/**
+ * Expose selected members of a service directly on `ctx`.
+ *
+ * Each mixed-in key becomes an accessor that forwards to the service
+ * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
+ * Mixins are removed when the current fiber unloads.
+ *
+ * @param name — the context property holding the source service.
+ * @param mixins — keys to forward, or a source-key → ctx-key map.
+ */
+mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
+mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void
+```
+
+直接在 `ctx` 上公开服务的指定成员。
+
+每个混入的键都会成为一个转发到该服务的访问器，并将方法绑定到该服务。例如，`ctx.on` 会转发到 `ctx.events.on`。当前 fiber 卸载时会移除这些混入。
+
+- `name`：存放源服务的上下文属性。
+- `mixins`：要转发的键，或从源键到 ctx 键的映射。
+
+[源码](../../vendor/cordis/src/reflect.ts#L67)
diff --git a/docs/cordis-api/events.i18n.yaml b/docs/cordis-api/events.i18n.yaml
new file mode 100644
index 0000000000..bcdc34be76
--- /dev/null
+++ b/docs/cordis-api/events.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 docs/cordis-api/events.md
+events.md: 8b8eb2358e10a250f581aecc725ba32360d338d3
+events.zh.md: 366f78fbe5d9bb5ff6f95c79c307237aaa97967a
diff --git a/docs/cordis-api/events.zh.md b/docs/cordis-api/events.zh.md
new file mode 100644
index 0000000000..366f78fbe5
--- /dev/null
+++ b/docs/cordis-api/events.zh.md
@@ -0,0 +1,209 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/events.md` 重新记录配对。 -->
+
+# 事件
+
+[English](events.md) | 中文
+
+每个上下文中都混入了事件分发 API。Harness 事件声明及其分发模式会生成到各自所属的[子系统页面](../subsystems/core.md)。
+
+### ctx.parallel(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event, running all listeners concurrently.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to every listener.
+ * @returns a promise resolving once every listener has settled.
+ */
+parallel<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promise<void>
+parallel<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promise<void>
+```
+
+分发一个事件，并发运行所有监听器。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+**返回值**：一个 Promise，在所有监听器均已完成后兑现。
+
+[源码](../../vendor/cordis/src/events.ts#L44)
+
+### ctx.emit(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event synchronously, ignoring listener return values.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to every listener.
+ */
+emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void
+emit<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): void
+```
+
+同步分发一个事件，忽略监听器的返回值。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+[源码](../../vendor/cordis/src/events.ts#L53)
+
+### ctx.serial(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event, awaiting listeners in order until one bails.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to each listener.
+ * @returns the first bail value (non-null, non-false, non-undefined), if any.
+ */
+serial<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
+serial<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
+```
+
+分发一个事件，依次等待各监听器，直到其中一个提前终止分发。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+**返回值**：第一个提前终止值（非 null、非 false 且非 undefined）；如果没有，则不返回此类值。
+
+[源码](../../vendor/cordis/src/events.ts#L63)
+
+### ctx.bail(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event, calling listeners in order until one bails.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to each listener.
+ * @returns the first bail value (non-null, non-false, non-undefined), if any.
+ */
+bail<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+bail<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+```
+
+分发一个事件，依次调用各监听器，直到其中一个提前终止分发。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+**返回值**：第一个提前终止值（非 null、非 false 且非 undefined）；如果没有，则不返回此类值。
+
+[源码](../../vendor/cordis/src/events.ts#L73)
+
+### ctx.waterfall(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event whose last argument is a `next` continuation.
+ *
+ * Each listener wraps the rest of the chain: calling `next()` invokes the
+ * next listener (finally the built-in behavior); not calling it vetoes.
+ *
+ * @param name — the event name.
+ * @param args — listener arguments; the final one is the innermost `next`.
+ * @returns the outermost listener's return value.
+ */
+waterfall<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+waterfall<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+```
+
+分发一个事件，其最后一个参数是续接执行的 `next` 回调。
+
+每个监听器都会包装调用链的其余部分：调用 `next()` 会执行下一个监听器，最终执行内置行为；不调用则会否决后续执行。
+
+- `name`：事件名称。
+- `args`：监听器参数；最后一个参数是最内层的 `next`。
+
+**返回值**：最外层监听器的返回值。
+
+[源码](../../vendor/cordis/src/events.ts#L86)
+
+### ctx.on(name, listener, options?)
+
+```ts cordis-catalog
+/**
+ * Register an event listener owned by the current fiber.
+ *
+ * @param name — the event name to listen for.
+ * @param listener — called with the dispatch arguments.
+ * @param options — listener options; a boolean is shorthand for `prepend`.
+ * @returns a disposer removing the listener; `true` if it was still registered.
+ */
+on<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
+```
+
+注册一个归当前 fiber 所有的事件监听器。
+
+- `name`：要监听的事件名称。
+- `listener`：使用分发参数调用的监听器。
+- `options`：监听器选项；布尔值可作为 `prepend` 的简写。
+
+**返回值**：一个用于移除监听器的资源释放函数；如果调用该函数时监听器仍处于注册状态，则返回 `true`。
+
+[源码](../../vendor/cordis/src/events.ts#L97)
+
+### ctx.once(name, listener, options?)
+
+```ts cordis-catalog
+/**
+ * Same as `on()`, but the listener disposes itself after its first call.
+ *
+ * @param name — the event name to listen for.
+ * @param listener — called at most once with the dispatch arguments.
+ * @param options — listener options; a boolean is shorthand for `prepend`.
+ * @returns a disposer removing the listener; `true` if it was still registered.
+ */
+once<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
+```
+
+与 `on()` 相同，但监听器在首次调用后会自行注销。
+
+- `name`：要监听的事件名称。
+- `listener`：使用分发参数调用，最多调用一次。
+- `options`：监听器选项；布尔值可作为 `prepend` 的简写。
+
+**返回值**：一个用于移除监听器的资源释放函数；如果调用该函数时监听器仍处于注册状态，则返回 `true`。
+
+[源码](../../vendor/cordis/src/events.ts#L106)
+
+## EventOptions
+
+`ctx.on()` 和 `ctx.once()` 接受的选项。
+
+```ts cordis-catalog
+/** Options accepted by `ctx.on()` and `ctx.once()`. */
+interface EventOptions {
+  /** Add the listener before existing listeners for the same event. */
+  prepend?: boolean
+  /** Receive the event regardless of context filter checks. */
+  global?: boolean
+}
+```
+
+[源码](../../vendor/cordis/src/events.ts#L112)
+
+## DispatchMode
+
+事件服务使用的事件分发策略。
+
+`emit` 运行同步监听器但不等待它们，`parallel` 同时等待所有监听器，`serial` 依次等待监听器直至其中一个提前终止分发，`bail` 遇到第一个同步提前终止值时停止，`waterfall` 则围绕最终的 `next` 回调组合监听器。
+
+```ts cordis-catalog
+/**
+ * Event dispatch strategy used by the event service.
+ *
+ * `emit` runs synchronous listeners without awaiting them, `parallel` awaits
+ * all listeners together, `serial` awaits them in order until one bails,
+ * `bail` stops on the first synchronous bail value, and `waterfall` composes
+ * listeners around a final `next` callback.
+ */
+type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
+```
+
+[源码](../../vendor/cordis/src/events.ts#L32)
diff --git a/docs/cordis-api/fiber.i18n.yaml b/docs/cordis-api/fiber.i18n.yaml
new file mode 100644
index 0000000000..0c45c03f5f
--- /dev/null
+++ b/docs/cordis-api/fiber.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 docs/cordis-api/fiber.md
+fiber.md: 36d2861ac6a53e8186a92d86c65ba228d4b59ee5
+fiber.zh.md: 8fbc10c9870106f3fc7dfabe9725581898d9ef22
diff --git a/docs/cordis-api/fiber.zh.md b/docs/cordis-api/fiber.zh.md
new file mode 100644
index 0000000000..8fbc10c987
--- /dev/null
+++ b/docs/cordis-api/fiber.zh.md
@@ -0,0 +1,377 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md` 重新记录配对。 -->
+
+# Fiber
+
+[English](fiber.md) | 中文
+
+fiber 是一个已加载的插件实例，包含其生命周期状态、经过校验的配置以及已注册的作用。`ctx.fiber` 是当前 fiber，`ctx.effect()` 会将调用委托给它。
+
+### ctx.effect(execute, label?)
+
+```ts cordis-catalog
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
+effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
+effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
+```
+
+在此 fiber 上注册一个支持清理的作用。
+
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+
+- `execute`：作用主体；可接受的结构见 `Effect`。
+- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
+
+**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
+
+[源码](../../vendor/cordis/src/fiber.ts#L420)
+
+### ctx.fiber
+
+```ts cordis-catalog
+/** The fiber (plugin runtime instance) that owns this context. */
+fiber: Fiber
+```
+
+拥有此上下文的 fiber（插件运行时实例）。
+
+[源码](../../vendor/cordis/src/fiber.ts#L12)
+
+## Fiber 类
+
+单次插件应用的运行时实例。
+
+fiber 会跟踪 `ctx.plugin()` 返回的插件上下文所对应的依赖状态、经过校验的配置、生命周期作用和清理操作。
+
+[源码](../../vendor/cordis/src/fiber.ts#L184)
+
+### fiber.uid
+
+```ts cordis-catalog
+/** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
+public uid: number | null
+```
+
+在注册表中的唯一 id；根 fiber 的 id 为 0，dispose 后为 `null`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L186)
+
+### fiber.ctx
+
+```ts cordis-catalog
+/** The context this fiber's plugin runs in (extends the parent context). */
+public readonly ctx: Context
+```
+
+此 fiber 的插件运行所在的上下文（扩展自父上下文）。
+
+[源码](../../vendor/cordis/src/fiber.ts#L188)
+
+### fiber.config
+
+```ts cordis-catalog
+/** The validated plugin config (updated by `update()`). */
+public config: any
+```
+
+经过校验的插件配置（由 `update()` 更新）。
+
+[源码](../../vendor/cordis/src/fiber.ts#L190)
+
+### fiber.state
+
+```ts cordis-catalog
+/** Current lifecycle state; transitions emit `internal/status`. */
+public state
+```
+
+当前生命周期状态；状态转换会发出 `internal/status`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L192)
+
+### fiber.dispose
+
+```ts cordis-catalog
+/** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
+public readonly dispose: () => Promise<void>
+```
+
+dispose 此 fiber：卸载插件，并在清理完成后结算。
+
+[源码](../../vendor/cordis/src/fiber.ts#L194)
+
+### fiber.store
+
+```ts cordis-catalog
+/** Snapshot of required service implementations while loaded; `undefined` otherwise. */
+public store: Dict<Impl> | undefined
+```
+
+加载期间所需服务实现的快照；其他情况下为 `undefined`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L196)
+
+### fiber.inertia
+
+```ts cordis-catalog
+/** The in-flight load/unload transition, if one is currently running. */
+public inertia: Promise<void> | undefined
+```
+
+当前正在进行的加载或卸载转换；如果没有此类转换，则为 `undefined`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L198)
+
+### fiber.name
+
+```ts cordis-catalog
+/** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
+get name()
+```
+
+插件的显示名称，继承自最近的具名祖先；如果不存在，则为 `'root'`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L341)
+
+### fiber.assertActive()
+
+```ts cordis-catalog
+/**
+ * Throw if the fiber has already been disposed.
+ *
+ * @returns nothing when the fiber is still active.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber's uid has been cleared.
+ */
+assertActive()
+```
+
+如果 fiber 已经 dispose，则抛出异常。
+
+**返回**：fiber 仍处于活动状态时不返回任何内容。
+
+[源码](../../vendor/cordis/src/fiber.ts#L356)
+
+### fiber.effect(execute, label?)
+
+```ts cordis-catalog
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
+effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
+effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
+```
+
+在此 fiber 上注册一个支持清理的作用。
+
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+
+- `execute`：作用主体；可接受的结构见 `Effect`。
+- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
+
+**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
+
+[源码](../../vendor/cordis/src/fiber.ts#L420)
+
+### fiber.getEffects()
+
+```ts cordis-catalog
+/**
+ * Return metadata for currently registered effects.
+ *
+ * @returns one {@link EffectMeta} tree per labeled live effect.
+ */
+getEffects()
+```
+
+返回当前已注册作用的元数据。
+
+**返回**：每个带标签的活动作用对应一棵 `EffectMeta` 树。
+
+[源码](../../vendor/cordis/src/fiber.ts#L573)
+
+### fiber.await()
+
+```ts cordis-catalog
+/**
+ * Wait for current lifecycle work and rethrow startup errors.
+ *
+ * @returns this fiber, once it has settled into a stable state.
+ * @throws the config-validation or plugin-startup error, if any.
+ */
+async await()
+```
+
+等待当前生命周期工作完成，并重新抛出启动错误。
+
+**返回**：进入稳定状态后的此 fiber。
+
+[源码](../../vendor/cordis/src/fiber.ts#L702)
+
+### fiber.restart()
+
+```ts cordis-catalog
+/**
+ * Dispose and immediately reload this plugin with its current config.
+ *
+ * @returns a promise resolving once the reload settled.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber is already disposed.
+ */
+async restart()
+```
+
+dispose 此插件，并立即使用其当前配置重新加载。
+
+**返回**一个在重新加载完成后兑现的 promise。
+
+[源码](../../vendor/cordis/src/fiber.ts#L716)
+
+### fiber.update(config, noSave?)
+
+```ts cordis-catalog
+/**
+ * Validate and apply new config, then restart the plugin.
+ *
+ * Runs the `internal/update` waterfall first, so update hooks (and HMR)
+ * can veto or replace the restart.
+ *
+ * @param config — the new raw config; validated before anything restarts.
+ * @param noSave — hint for persistence hooks not to write the change back.
+ * @returns the update waterfall result; the default restart returns a promise.
+ * @throws when validation, an update listener, or the restarted plugin fails.
+ */
+update(config: any, noSave = false)
+```
+
+校验并应用新配置，然后重新启动插件。
+
+首先运行 `internal/update` waterfall（瀑布式事件），因此更新钩子（以及 HMR（热模块替换））可以否决或取代重新启动操作。
+
+- `config`：新的原始配置；在任何内容重新启动前进行校验。
+- `noSave`：提示持久化钩子不要写回此变更。
+
+**返回**更新 waterfall 的结果；默认的重新启动操作返回一个 promise。
+
+[源码](../../vendor/cordis/src/fiber.ts#L734)
+
+## Effect
+
+`ctx.effect()` 和插件启动所接受的作用主体结果。
+
+可以是单个清理函数、兑现为清理函数的 promise，或生成多个清理函数的（可能为异步的）可迭代对象。生成器作用会在每个清理函数产生时将其注册。
+
+```ts cordis-catalog
+/**
+ * Effect body result accepted by `ctx.effect()` and plugin startup.
+ *
+ * Either a single disposer, a promise of one, or a (possibly async) iterable
+ * yielding several — generator effects register each yielded disposer as it
+ * is produced.
+ */
+type Effect<T = any> =
+  | SyncEffect<T>
+  | AsyncEffect<T>
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L83)
+
+## Disposable
+
+作用返回的函数，用于在资源释放期间释放资源。
+
+拥有该函数的 fiber 卸载时，清理函数会按注册的相反顺序运行；清理函数可以是异步的，此时卸载过程会等待其完成。
+
+```ts cordis-catalog
+/**
+ * Function returned by an effect to release resources during disposal.
+ *
+ * Disposers run in reverse registration order when the owning fiber unloads;
+ * they may be async, in which case unloading awaits them.
+ */
+type Disposable<T = any> = () => T
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L74)
+
+## EffectMeta
+
+用于在诊断信息中公开嵌套作用标签的树节点。
+
+```ts cordis-catalog
+/** Tree node used to expose nested effect labels for diagnostics. */
+interface EffectMeta {
+  /** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
+  label: string
+  /** Metadata of nested effects registered while this effect ran. */
+  children: EffectMeta[]
+}
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L96)
+
+## CordisError
+
+具有稳定机器可读错误码的框架错误。
+
+```ts cordis-catalog
+/** Framework error with a stable machine-readable code. */
+class CordisError extends Error {
+  /**
+   * @param code — the stable error code; also the default message.
+   * @param message — optional human-readable override.
+   */
+  constructor(public code: CordisError.Code, message?: string)
+}
+
+/** Cordis error code definitions. */
+namespace CordisError {
+  export type Code = keyof typeof Code
+
+  export const Code = {
+    INACTIVE_EFFECT: 'cannot create effect on inactive context',
+  } as const
+}
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L157)
+
+## ValidationError
+
+插件配置未通过 standard-schema 校验时抛出的错误。
+
+```ts cordis-catalog
+/** Error raised when plugin configuration fails standard-schema validation. */
+class ValidationError extends TypeError {
+  name = 'ValidationError'
+
+  /**
+   * Build the aggregated message from schema issues.
+   *
+   * @param issues — the standard-schema issues, one message line each.
+   */
+  constructor(issues: readonly StandardSchemaV1.Issue[])
+}
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L19)
diff --git a/docs/cordis-api/registry.i18n.yaml b/docs/cordis-api/registry.i18n.yaml
new file mode 100644
index 0000000000..31cafb4ace
--- /dev/null
+++ b/docs/cordis-api/registry.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 docs/cordis-api/registry.md
+registry.md: e6ddce5700ab071c2a4fedae19d99e2cb6e994ec
+registry.zh.md: c10509f569adfe65b4dbee4ca5b7139085dce1f7
diff --git a/docs/cordis-api/registry.zh.md b/docs/cordis-api/registry.zh.md
new file mode 100644
index 0000000000..c10509f569
--- /dev/null
+++ b/docs/cordis-api/registry.zh.md
@@ -0,0 +1,154 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/registry.md` 重新记录配对。 -->
+
+# 注册表
+
+[English](registry.md) | 中文
+
+插件加载与依赖注入。
+
+### ctx.inject(deps, callback)
+
+```ts cordis-catalog
+/**
+ * Run a callback once the requested services are available.
+ *
+ * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
+ * is unloaded and re-run whenever a required service changes.
+ *
+ * @param deps — required services, as an array or a name → config map.
+ * @param callback — plugin body called with `(ctx, config)`.
+ * @returns the fiber; awaiting it settles once loading finished.
+ */
+inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
+```
+
+当请求的服务可用后，运行一次回调。
+
+这是 `ctx.plugin({ inject, apply: callback })` 的简写形式：每当某个必需服务发生变化时，系统都会卸载并重新运行该回调。
+
+- `deps`：必需服务，形式可以是数组，也可以是从名称到配置的映射。
+- `callback`：以 `(ctx, config)` 调用的插件主体。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待。
+
+[源码](../../vendor/cordis/src/registry.ts#L176)
+
+### ctx.plugin(plugin, ...args)
+
+```ts cordis-catalog
+/**
+ * Load a plugin in the current context.
+ *
+ * @param plugin — a function, class, or `{ apply }` object plugin.
+ * @param args — the plugin config, validated against its `Config` schema.
+ * @returns the fiber; awaiting it settles once loading finished
+ * (rejecting on config or startup errors).
+ */
+plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
+```
+
+在当前上下文中加载插件。
+
+- `plugin`：函数、类或 `{ apply }` 对象形式的插件。
+- `args`：插件配置，会根据其 `Config` schema 进行校验。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待（如果发生配置错误或启动错误，则会被拒绝）。
+
+[源码](../../vendor/cordis/src/registry.ts#L185)
+
+## Plugin
+
+支持的插件入口点形式。
+
+```ts cordis-catalog
+/** Supported plugin entrypoint shapes. */
+type Plugin<T = any> =
+  | Plugin.Function<T>
+  | Plugin.Constructor<T>
+  | Plugin.Object<T>
+
+/** Types associated with plugin entrypoints and runtime records. */
+namespace Plugin {
+  /** Shared metadata understood by the plugin registry and related tooling. */
+  export interface Base<T = any> {
+    /** Display name used for fiber diagnostics and logger names. */
+    name?: string
+    /** Standard-schema validator applied to config before the plugin starts. */
+    Config?: StandardSchemaV1<any, T>
+    /** Services the plugin requires; it only loads while all are available. */
+    inject?: Inject
+    /** Service name(s) the plugin provides (read by `Service` and by loaders). */
+    provide?: string | string[]
+    /** Service names whose intercept config the plugin declares it consumes. */
+    intercept?: Dict<boolean>
+  }
+
+  export interface Transform<S, T> {
+    /** Marks the transform object as a schema/config transform. */
+    schema?: true
+    /** Convert user-facing config to runtime config. */
+    Config: (config: S) => T
+  }
+
+  /** Function plugin called with `(ctx, config)`. */
+  export interface Function<T = any> extends Base<T> {
+    (ctx: Context, config: T): any
+  }
+
+  /** Class plugin constructed with `(ctx, config)`. */
+  export interface Constructor<T = any> extends Base<T> {
+    new (ctx: Context, config: T): any
+  }
+
+  /** Object plugin with an `apply(ctx, config)` method. */
+  export interface Object<T = any> extends Base<T> {
+    apply(ctx: Context, config: T): any
+  }
+
+  /** Mutable registry record shared by all fibers of one plugin callback. */
+  export interface Runtime {
+    /** Display name copied from the first registered plugin shape. */
+    name?: string
+    /** Every live fiber of this plugin (one per `ctx.plugin()` call). */
+    fibers: DisposableList<Fiber>
+    /** The executable entrypoint all fibers share (registry identity key). */
+    callback: globalThis.Function
+    /** Standard-schema validator applied to each fiber's config. */
+    Config?: StandardSchemaV1
+  }
+}
+```
+
+[源码](../../vendor/cordis/src/registry.ts#L92)
+
+## Inject
+
+插件和 `@Inject` 装饰器接受的服务依赖声明。
+
+数组形式请求不带拦截配置的服务。对象形式将每个服务名称映射到插件上下文中可选的拦截配置。
+
+```ts cordis-catalog
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
+type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
+
+/** Utilities for normalizing plugin dependency declarations. */
+namespace Inject {
+  /**
+   * Convert array/object/class-inherited inject metadata into a plain map.
+   *
+   * @param inject — the declaration to normalize; `null`/`undefined` add nothing.
+   * @param result — the map to fill (service name → intercept config or `null`).
+   * @returns `result`.
+   */
+  export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
+}
+```
+
+[源码](../../vendor/cordis/src/registry.ts#L19)
diff --git a/docs/cordis-api/service.i18n.yaml b/docs/cordis-api/service.i18n.yaml
new file mode 100644
index 0000000000..7779d5fef6
--- /dev/null
+++ b/docs/cordis-api/service.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 docs/cordis-api/service.md
+service.md: d4b0f06da16decf31e0d348a88e0360b46ee9d35
+service.zh.md: ec0b443a0eae2787e0a3db919583d8092414c52d
diff --git a/docs/cordis-api/service.zh.md b/docs/cordis-api/service.zh.md
new file mode 100644
index 0000000000..ec0b443a0e
--- /dev/null
+++ b/docs/cordis-api/service.zh.md
@@ -0,0 +1,104 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/service.md` 重新记录配对。 -->
+
+# Service
+
+[English](service.md) | 中文
+
+上下文服务的基类。以插件形式加载的子类会将自身注册为 `ctx.<name>`。
+
+用于在 `ctx` 上公开具名 API 的服务基类。
+
+子类在构造函数中调用 `super(ctx, name)`。服务会立即注册，并随所属 fiber 自动移除。
+
+[源码](../../vendor/cordis/src/service.ts#L11)
+
+### service.name
+
+```ts cordis-catalog
+/** The service name this instance is registered under. */
+public name!: string
+```
+
+此实例注册时使用的服务名称。
+
+[源码](../../vendor/cordis/src/service.ts#L30)
+
+## 静态成员
+
+### Service.init
+
+```ts cordis-catalog
+/** Symbol key of an instance method run after construction (class plugins). */
+static readonly init: unique symbol
+```
+
+构造完成后运行的实例方法所使用的符号键（类插件）。
+
+[源码](../../vendor/cordis/src/service.ts#L13)
+
+### Service.check
+
+```ts cordis-catalog
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
+static readonly check: unique symbol
+```
+
+传给 `ctx.provide()` 的可用性谓词所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L15)
+
+### Service.config
+
+```ts cordis-catalog
+/** Symbol key of the phantom intercept-config type parameter. */
+static readonly config: unique symbol
+```
+
+虚设拦截配置类型参数所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L17)
+
+### Service.invoke
+
+```ts cordis-catalog
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+static readonly invoke: unique symbol
+```
+
+使服务可被调用的调用体所使用的符号键（例如 `ctx.logger()`）。
+
+[源码](../../vendor/cordis/src/service.ts#L19)
+
+### Service.extend
+
+```ts cordis-catalog
+/** Symbol key of the helper deriving an extended service instance. */
+static readonly extend: unique symbol
+```
+
+用于派生扩展服务实例的辅助方法所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L21)
+
+### Service.tracker
+
+```ts cordis-catalog
+/** Symbol key of the tracker metadata used for context tracing. */
+static readonly tracker: unique symbol
+```
+
+上下文追踪所用跟踪器元数据的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L23)
+
+### Service.resolveConfig
+
+```ts cordis-catalog
+/** Symbol key of the intercept-config resolution helper below. */
+static readonly resolveConfig: unique symbol
+```
+
+下述拦截配置解析辅助方法所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L25)
diff --git a/docs/cordis-tutorial/01-first-plugin.i18n.yaml b/docs/cordis-tutorial/01-first-plugin.i18n.yaml
index 29e0266689..1fe3585ba1 100644
--- a/docs/cordis-tutorial/01-first-plugin.i18n.yaml
+++ b/docs/cordis-tutorial/01-first-plugin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/01-first-plugin.md
 01-first-plugin.md: 4359dfe4883f12e9cb242cf3009827fd7864768c
-01-first-plugin.zh.md: 62ccb7e5d37beb5b9636439e563cea6eaa1044a0
+01-first-plugin.zh.md: 9965f4ddb75fa338ba7fd9d564bd4a32fced7b93
diff --git a/docs/cordis-tutorial/01-first-plugin.zh.md b/docs/cordis-tutorial/01-first-plugin.zh.md
index 62ccb7e5d3..9965f4ddb7 100644
--- a/docs/cordis-tutorial/01-first-plugin.zh.md
+++ b/docs/cordis-tutorial/01-first-plugin.zh.md
@@ -28,7 +28,7 @@ export function apply(ctx: Context) {
 - name: './hello.ts'
 ```
 
-该文件是一组 Cordis 配置项的列表。`name` 是模块指定符，可以是相对路径或 NPM 包（package）名；loader 会挂载每个配置项。各项会并发启动，因此它们在列表中的位置不保证插件的加载先后；顺序由服务依赖（`inject`，参见[第 3 章](03-services.md)）决定，而非文件中的位置。
+该文件是一组 Cordis 配置项的列表。`name` 是模块指定符，可以是相对路径或 NPM 包名；loader 会挂载每个配置项。各项会并发启动，因此它们在列表中的位置不保证插件的加载先后；顺序由服务依赖（`inject`，参见[第 3 章](03-services.md)）决定，而非文件中的位置。
 
 ## 运行
 
@@ -86,7 +86,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-再次运行：进程会因该错误而终止。插件加载失败必须明确报错，不会仅跳过该配置项。
+再次运行：进程会因该错误而终止。插件加载失败会明确报错，不会仅跳过该配置项。
 
 还需要尽早了解一个例外：如果某个配置项的模块无法被 **解析**，例如路径或包名拼写错误，Cordis 会通过 logger 服务报告错误，而不会使进程崩溃。在启动阶段，这条报告可能在 console 导出器开始观察之前丢失。如果新增配置项似乎没有任何效果，请先检查拼写。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 00673a9415..d6d5d3dcc3 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
 development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 9d3606cf741f25318c630e08e8ac84ad5ee8d345
+development.zh.md: 60a4660f5d6be48fd4d0d8f30777ae37495d6296
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 9d3606cf74..60a4660f5d 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -43,21 +43,21 @@ pnpm run typecheck
 
 ### TypeScript 项目布局
 
-仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。
+仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。
 
 | 文件 | 角色 | 是否构成 program？ |
 |---|---|---|
 | `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |
-| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |
-| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |
+| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |
+| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |
 | `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |
-| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |
+| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |
 
 Host 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：
 
 - `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。
 - 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。
-- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。
+- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。
 
 `api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。
 
@@ -71,13 +71,13 @@ tsdown --env.DSH_BUILD_FACE client
 pnpm run build:web
 ```
 
-两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
+两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
 
-TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
+TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
 
-业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
+业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
 如果相关的本地检查需要使用构建后的包产物，请先构建一次：
 
@@ -85,7 +85,7 @@ TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分
 pnpm run build
 ```
 
-`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。
+`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。
 
 ### 环境变量
 
@@ -108,7 +108,7 @@ lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
-- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
+- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
@@ -122,7 +122,7 @@ keyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若
 
 ### 日常命令
 
-根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。
+根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。
 
 ### 演示
 
@@ -156,10 +156,10 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
new file mode 100644
index 0000000000..ee00d76a88
--- /dev/null
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
+event-producer-consumer.md: f5ea3eba36f46b87d9a8f5fc9537c40622da8cc9
+event-producer-consumer.zh.md: e2bb889d5a4319fc31c1ed0b3e06b68e320081f5
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
new file mode 100644
index 0000000000..e2bb889d5a
--- /dev/null
+++ b/docs/event-producer-consumer.zh.md
@@ -0,0 +1,83 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/event-producer-consumer.md` 重新记录配对。 -->
+
+# 事件生产方与消费方矩阵
+
+[English](event-producer-consumer.md) | 中文
+
+本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。这里特意采用表格而非一张大型关系图：事件之间存在多对多关系，以表格逐行呈现密集的关系数据更便于评审。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。
+
+| 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
+| --- | --- | --- | --- | --- |
+| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
+| `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/support/loader-smoke), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
+| `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
+| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
+| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
+| `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
+| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
+| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:60`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
+| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:53`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
+| `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:45`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+
+## 包源码中出现的非 harness 或未声明事件字符串
+
+| 事件字符串 | 派发方 | 监听方 |
+| --- | --- | --- |
+| `commands/changed` | `runtime` (`emit`) | `ui-command` |
+| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
+| `credentials/changed` | `runtime` (`emit`) | `ui-models` |
+| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
+| `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
+| `internal/service` | - | `gateway` |
+| `internal/status` | - | [`agent`](../packages/core/agent) |
+| `locale/change` | `locale` (`emit`) | `locale` |
+| `models/changed` | `runtime` (`emit`) | `ui-models` |
+| `settings/changed` | `runtime` (`emit`) | `ui-models`, `ui-permission`, `ui-settings-general` |
+| `slash/input-begin-command` | - | `ui-conversation` |
+| `slash/input-consume-token` | - | `ui-conversation` |
+| `slash/input-insert-reference` | - | `ui-conversation` |
+| `slash/input-insert-text` | - | `ui-conversation` |
+| `slots/changed` | `runtime` (`emit`) | - |
+| `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` |
+
+维护模式：英文源文件是生成内容，Cordis 事件声明及生产方／监听方的关系边由仓库的 TypeScript Program 解析；本中文文件作为经评审对侧通过双语配对维护。
diff --git a/docs/graph-atlas.i18n.yaml b/docs/graph-atlas.i18n.yaml
new file mode 100644
index 0000000000..0cd73d4f39
--- /dev/null
+++ b/docs/graph-atlas.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 docs/graph-atlas.md
+graph-atlas.md: 5b831520fb4e1c5d49d83738ba979ce04ce4f69f
+graph-atlas.zh.md: 1f9a30124284549248bbb21f926772d5cdc2598a
diff --git a/docs/graph-atlas.zh.md b/docs/graph-atlas.zh.md
new file mode 100644
index 0000000000..1f9a301242
--- /dev/null
+++ b/docs/graph-atlas.zh.md
@@ -0,0 +1,26 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/graph-atlas.md` 重新记录配对。 -->
+
+# 文档图索引
+
+[English](graph-atlas.md) | 中文
+
+这些图构成生成目录之上的关系层。你可以借助它们了解包拓扑、能力 seam、事件流、面向模型的工具、应用组合以及运行时生命周期路径。精确签名和类型结构仍以[子系统页面](subsystems/core.md)（类型和生成的 `cordis-surface` 区域）及[工具目录](tool-catalog.md)为准。
+
+本索引背后的流程决策记录在[文档图 Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md)中。
+
+| 图 | 模式 |
+| --- | --- |
+| [模块依赖图](module-graph.md) | `generated` |
+| [工具 schema 目录与包映射](tool-catalog.md) | `generated` |
+| [能力 seam 与核心服务](capability-seams.md) | `hybrid generated` |
+| [dsh 共享基础组合](../apps/cli/composition.md) | `hybrid generated` |
+| [headless-agent 应用组合](../examples/headless-agent/composition.md) | `hybrid generated` |
+| [acp-agent 应用组合](../examples/acp-agent/composition.md) | `hybrid generated` |
+| [事件生产方／消费方矩阵](event-producer-consumer.md) | `hybrid generated` |
+| [agent（智能体）轮次与步骤生命周期](agent-lifecycle.md) | `curated` |
+| [工具执行流水线](tool-execution-pipeline.md) | `curated` |
+
+运行 `pnpm run gen-doc-graphs` 可重新生成英文源文件；运行 `pnpm run verify-doc-graphs` 可验证英文源的新鲜度，中文对侧则通过双语配对维护。
+
+英文源文件的维护模式为混合。每个链接页面都会声明其英文源模式为生成、混合或人工编写；本中文文件是通过双语配对维护的经评审对侧。
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index c62de565e7..c10cab36cb 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: 30f56eeebf15a3edec559e3080247dab9ab14178
-README.zh.md: 91d5b35a00994beea70f2bbd674cfb557d6f834d
+README.md: b6190e7dd84ae5f159fd452f093bf37f24edfda9
+README.zh.md: f1c808442efe3ca7da87c30ba22d3560bcf125e9
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 30f56eeebf..b6190e7dd8 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -43,9 +43,11 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
 
 **Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.
 
+Generated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.
+
 **Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):
 
-- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.
+- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.
 - `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.
 - `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.
 - [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 91d5b35a00..f1c808442e 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
 
-## 配对契约
+## 配对约定
 
 - **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
 - **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
@@ -23,7 +23,7 @@
 
 ## 门禁：verify-translation-pairing
 
-`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：
+`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：
 
 1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。
 2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
@@ -37,15 +37,17 @@
 
 这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
 
-把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
+把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
 
 ## 范围与排除
 
 **范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。
 
+有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。
+
 **排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：
 
-- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。
+- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。
 - `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。
 - `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。
 - [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
@@ -55,4 +57,4 @@
 
 ## 分工
 
-这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
+这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 299f7db46f..846ade98b9 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -74,7 +74,7 @@
 | English | 中文 | 首次出现 | 不要译作 | 备注 |
 |---|---|---|---|---|
 | adapter | 适配器 | | | |
-| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |
+| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |
 | append-only | 仅追加 | | | |
 | artifact | 产物 | | 制品 | |
 | backend | 后端 | | | |
@@ -101,7 +101,7 @@
 | counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
 | configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |
 | context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
-| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| contract | 约定 | | | 如：`pairing contract` →`配对约定` |
 | Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
 | Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
 | crash recovery | 崩溃恢复 | | | |
diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index dea0883a4b..e8e4d8f801 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.i18n.yaml
@@ -1,6 +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
+#   pnpm run verify-translation-pairing --write docs/i18n/translation-rules.md
 translation-rules.md: fb6aa9ac05bebe68ff9213af99f64457bdb1ad6f
 translation-rules.zh.md: 04dd0a704e19502c676ea0966437870c5af0624f
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
new file mode 100644
index 0000000000..212b107093
--- /dev/null
+++ b/docs/module-graph.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 docs/module-graph.md
+module-graph.md: 6f47c36e970009838e1ab921f4abe013eaeded5f
+module-graph.zh.md: 5da7bc962e1c38e3febfbca59e6bb11b014ecc7f
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
new file mode 100644
index 0000000000..5da7bc962e
--- /dev/null
+++ b/docs/module-graph.zh.md
@@ -0,0 +1,1370 @@
+<!-- 英文源文件由 scripts/gen-module-graph.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-module-graph` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/module-graph.md` 重新记录配对。 -->
+
+# 模块依赖关系图
+
+[English](module-graph.md) | 中文
+
+`@deepseek-ai/dsh-*` harness 包之间的依赖关系。该关系图根据各包的 `peerDependencies`（规范的运行时依赖信号）生成，并按 `packages/<group>/<pkg>` 层级分组。边 `a --> b` 表示包 `a` 依赖包 `b`。名称中的 `@deepseek-ai/dsh-` 前缀已移除。
+
+```mermaid
+flowchart TD
+  subgraph group_util["packages/util"]
+    pkg_atomic_write["atomic-write"]
+    pkg_brand["brand"]
+    pkg_environment["environment"]
+    pkg_native_command["native-command"]
+    pkg_paths["paths"]
+    pkg_retention["retention"]
+    pkg_timeout["timeout"]
+  end
+  subgraph group_llm["packages/llm"]
+    pkg_llm["llm"]
+    pkg_llm_deepseek["llm-deepseek"]
+    pkg_llm_pi_ai["llm-pi-ai"]
+    pkg_llm_retry["llm-retry"]
+    pkg_token_meter["token-meter"]
+  end
+  subgraph group_core["packages/core"]
+    pkg_agent["agent"]
+    pkg_agent_loop["agent-loop"]
+    pkg_scope["scope"]
+    pkg_session["session"]
+    pkg_system_prompt["system-prompt"]
+    pkg_tools["tools"]
+  end
+  subgraph group_goal["packages/goal"]
+    pkg_command_goal["command-goal"]
+    pkg_goal["goal"]
+    pkg_goal_session["goal-session"]
+    pkg_tool_goal["tool-goal"]
+  end
+  subgraph group_bash["packages/bash"]
+    pkg_bash["bash"]
+    pkg_bash_env["bash-env"]
+    pkg_bash_local["bash-local"]
+    pkg_bash_sandbox["bash-sandbox"]
+    pkg_pwsh_local["pwsh-local"]
+    pkg_tool_bash["tool-bash"]
+    pkg_tool_pwsh["tool-pwsh"]
+  end
+  subgraph group_fs["packages/fs"]
+    pkg_fs["fs"]
+    pkg_fs_local["fs-local"]
+    pkg_fs_policy["fs-policy"]
+    pkg_fs_sandbox["fs-sandbox"]
+    pkg_tool_fs["tool-fs"]
+    pkg_tool_fs_search["tool-fs-search"]
+    pkg_tool_str_replace_editor["tool-str-replace-editor"]
+  end
+  subgraph group_skill["packages/skill"]
+    pkg_skill["skill"]
+    pkg_skill_badge["skill-badge"]
+    pkg_skill_local["skill-local"]
+    pkg_tool_skill["tool-skill"]
+  end
+  subgraph group_compact["packages/compact"]
+    pkg_command_compact["command-compact"]
+    pkg_compact["compact"]
+    pkg_compact_basic["compact-basic"]
+    pkg_compact_tool_result_prune["compact-tool-result-prune"]
+  end
+  subgraph group_subagent["packages/subagent"]
+    pkg_subagent["subagent"]
+    pkg_subagent_acp["subagent-acp"]
+    pkg_subagent_claude_code["subagent-claude-code"]
+    pkg_subagent_codex["subagent-codex"]
+    pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
+    pkg_subagent_fork["subagent-fork"]
+    pkg_subagent_inprocess["subagent-inprocess"]
+    pkg_subagent_spawn["subagent-spawn"]
+    pkg_tool_subagent["tool-subagent"]
+    pkg_tool_subagent_control["tool-subagent-control"]
+    pkg_tool_subagent_report["tool-subagent-report"]
+  end
+  subgraph group_web["packages/web"]
+    pkg_tool_web["tool-web"]
+    pkg_web["web"]
+    pkg_web_fetch_local["web-fetch-local"]
+    pkg_web_search_deepseek["web-search-deepseek"]
+    pkg_web_search_exa["web-search-exa"]
+    pkg_web_search_perplexity["web-search-perplexity"]
+  end
+  subgraph group_spill["packages/spill"]
+    pkg_spill["spill"]
+    pkg_spill_local["spill-local"]
+    pkg_spill_policy["spill-policy"]
+  end
+  subgraph group_todo["packages/todo"]
+    pkg_tool_todo["tool-todo"]
+  end
+  subgraph group_plan["packages/plan"]
+    pkg_plan_mode["plan-mode"]
+  end
+  subgraph group_hooks["packages/hooks"]
+    pkg_hook_protocol["hook-protocol"]
+    pkg_hooks_claude["hooks-claude"]
+    pkg_hooks_codex["hooks-codex"]
+  end
+  subgraph group_session_query["packages/session-query"]
+    pkg_session_query["session-query"]
+    pkg_session_query_sqlite["session-query-sqlite"]
+    pkg_tool_session_query["tool-session-query"]
+  end
+  subgraph group_support["packages/support"]
+    pkg_acp_snapshot["acp-snapshot"]
+    pkg_agent_loop_testkit["agent-loop-testkit"]
+    pkg_invariants["invariants"]
+    pkg_llm_mock_server["llm-mock-server"]
+    pkg_llm_replay["llm-replay"]
+    pkg_loader_smoke["loader-smoke"]
+  end
+  subgraph group_acp["packages/acp"]
+    pkg_acp["acp"]
+  end
+  subgraph group_api["packages/api"]
+    pkg_api_gateway["api-gateway"]
+    pkg_api_remotes["api-remotes"]
+  end
+  subgraph group_boot["packages/boot"]
+    pkg_app_boot["app-boot"]
+  end
+  subgraph group_bundle["packages/bundle"]
+    pkg_base["base"]
+    pkg_headless["headless"]
+    pkg_web_app["web-app"]
+  end
+  subgraph group_client["packages/client"]
+    pkg_client_connection["client-connection"]
+    pkg_client_hmr["client-hmr"]
+    pkg_client_locale["client-locale"]
+    pkg_client_modules["client-modules"]
+    pkg_client_runtime["client-runtime"]
+    pkg_client_schema_form["client-schema-form"]
+    pkg_client_test_runtime["client-test-runtime"]
+    pkg_client_ui_command["client-ui-command"]
+    pkg_client_ui_conversation["client-ui-conversation"]
+    pkg_client_ui_deliverables["client-ui-deliverables"]
+    pkg_client_ui_goal["client-ui-goal"]
+    pkg_client_ui_layout["client-ui-layout"]
+    pkg_client_ui_model["client-ui-model"]
+    pkg_client_ui_models["client-ui-models"]
+    pkg_client_ui_permission["client-ui-permission"]
+    pkg_client_ui_plan["client-ui-plan"]
+    pkg_client_ui_primitives["client-ui-primitives"]
+    pkg_client_ui_question["client-ui-question"]
+    pkg_client_ui_settings["client-ui-settings"]
+    pkg_client_ui_settings_general["client-ui-settings-general"]
+    pkg_client_ui_sidebar["client-ui-sidebar"]
+    pkg_client_ui_skill["client-ui-skill"]
+    pkg_client_ui_slash["client-ui-slash"]
+    pkg_client_ui_slots["client-ui-slots"]
+    pkg_client_ui_subagent["client-ui-subagent"]
+    pkg_client_ui_theme["client-ui-theme"]
+    pkg_client_ui_tool["client-ui-tool"]
+    pkg_client_ui_trajectory["client-ui-trajectory"]
+    pkg_client_ui_workspace["client-ui-workspace"]
+    pkg_client_web["client-web"]
+    pkg_client_web_react["client-web-react"]
+  end
+  subgraph group_code_runtime["packages/code-runtime"]
+    pkg_code_runtime["code-runtime"]
+    pkg_code_runtime_worker["code-runtime-worker"]
+  end
+  subgraph group_context["packages/context"]
+    pkg_session_reference["session-reference"]
+    pkg_time_context["time-context"]
+    pkg_tmux_context["tmux-context"]
+    pkg_workspace_context["workspace-context"]
+  end
+  subgraph group_credentials["packages/credentials"]
+    pkg_credentials["credentials"]
+    pkg_credentials_local["credentials-local"]
+  end
+  subgraph group_e2b["packages/e2b"]
+    pkg_e2b["e2b"]
+    pkg_fs_e2b["fs-e2b"]
+    pkg_subprocess_e2b["subprocess-e2b"]
+  end
+  subgraph group_examples["packages/examples"]
+    pkg_acp_demo["acp-demo"]
+    pkg_agent_spine_demo["agent-spine-demo"]
+    pkg_jsonrpc_demo["jsonrpc-demo"]
+  end
+  subgraph group_feedback["packages/feedback"]
+    pkg_command_feedback["command-feedback"]
+  end
+  subgraph group_guard["packages/guard"]
+    pkg_repeat_tool_guard["repeat-tool-guard"]
+    pkg_timeout_policy["timeout-policy"]
+  end
+  subgraph group_host["packages/host"]
+    pkg_frontend_static["frontend-static"]
+    pkg_host_apiproxy["host-apiproxy"]
+    pkg_host_directory_picker["host-directory-picker"]
+    pkg_host_directory_picker_auto["host-directory-picker-auto"]
+    pkg_host_directory_picker_browse["host-directory-picker-browse"]
+    pkg_host_directory_picker_native["host-directory-picker-native"]
+    pkg_host_webserver["host-webserver"]
+  end
+  subgraph group_interaction["packages/interaction"]
+    pkg_commands["commands"]
+    pkg_permission["permission"]
+    pkg_tool_ask_user["tool-ask-user"]
+    pkg_user_approval["user-approval"]
+    pkg_user_interaction["user-interaction"]
+  end
+  subgraph group_lsp["packages/lsp"]
+    pkg_lsp["lsp"]
+    pkg_lsp_local["lsp-local"]
+    pkg_tool_lsp["tool-lsp"]
+  end
+  subgraph group_mcp["packages/mcp"]
+    pkg_mcp_client["mcp-client"]
+  end
+  subgraph group_pty["packages/pty"]
+    pkg_pty["pty"]
+    pkg_pty_local["pty-local"]
+    pkg_tool_bash_persistent["tool-bash-persistent"]
+    pkg_tool_pty["tool-pty"]
+  end
+  subgraph group_sandbox["packages/sandbox"]
+    pkg_sandbox["sandbox"]
+    pkg_sandbox_local["sandbox-local"]
+    pkg_sandbox_policy["sandbox-policy"]
+  end
+  subgraph group_scaffold["packages/scaffold"]
+    pkg_helper["helper"]
+    pkg_jsonrpc["jsonrpc"]
+    pkg_scripts["scripts"]
+    pkg_sdk_client["sdk-client"]
+    pkg_sdk_protocol["sdk-protocol"]
+    pkg_telemetry["telemetry"]
+  end
+  subgraph group_self_modification["packages/self-modification"]
+    pkg_repository_plugin["repository-plugin"]
+    pkg_tool_cordis["tool-cordis"]
+  end
+  subgraph group_session["packages/session"]
+    pkg_session_checkpoint_policy["session-checkpoint-policy"]
+    pkg_session_persistence["session-persistence"]
+    pkg_session_persistence_jsonl["session-persistence-jsonl"]
+    pkg_session_persistence_sqlite["session-persistence-sqlite"]
+    pkg_session_projection["session-projection"]
+    pkg_session_projection_cache["session-projection-cache"]
+    pkg_session_telemetry["session-telemetry"]
+    pkg_session_telemetry_otel["session-telemetry-otel"]
+    pkg_session_title["session-title"]
+    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+    pkg_session_title_first_message_llm["session-title-first-message-llm"]
+    pkg_session_title_llm["session-title-llm"]
+  end
+  subgraph group_settings["packages/settings"]
+    pkg_settings["settings"]
+    pkg_settings_local["settings-local"]
+  end
+  subgraph group_storage["packages/storage"]
+    pkg_storage["storage"]
+    pkg_storage_domain["storage-domain"]
+    pkg_storage_json["storage-json"]
+    pkg_storage_sqlite["storage-sqlite"]
+  end
+  subgraph group_subprocess["packages/subprocess"]
+    pkg_subprocess["subprocess"]
+    pkg_subprocess_local["subprocess-local"]
+  end
+  subgraph group_tasks["packages/tasks"]
+    pkg_tasks["tasks"]
+    pkg_tasks_local["tasks-local"]
+    pkg_tool_tasks["tool-tasks"]
+  end
+  subgraph group_typert["packages/typert"]
+    pkg_type_meta["type-meta"]
+    pkg_typert_generator["typert-generator"]
+    pkg_typert_loader["typert-loader"]
+    pkg_typert_registry["typert-registry"]
+  end
+  subgraph group_workflow["packages/workflow"]
+    pkg_tool_ralph["tool-ralph"]
+    pkg_tool_workflow["tool-workflow"]
+    pkg_workflow["workflow"]
+    pkg_workflow_workerthread["workflow-workerthread"]
+  end
+  subgraph group_workspace["packages/workspace"]
+    pkg_workspace["workspace"]
+  end
+  pkg_atomic_write --> pkg_invariants
+  pkg_brand --> pkg_invariants
+  pkg_environment --> pkg_invariants
+  pkg_native_command --> pkg_invariants
+  pkg_paths --> pkg_invariants
+  pkg_retention --> pkg_invariants
+  pkg_timeout --> pkg_invariants
+  pkg_scope --> pkg_invariants
+  pkg_llm_mock_server --> pkg_invariants
+  pkg_base --> pkg_invariants
+  pkg_client_modules --> pkg_invariants
+  pkg_client_schema_form --> pkg_invariants
+  pkg_client_ui_primitives --> pkg_invariants
+  pkg_client_ui_slots --> pkg_invariants
+  pkg_client_web --> pkg_invariants
+  pkg_client_web_react --> pkg_invariants
+  pkg_code_runtime --> pkg_invariants
+  pkg_e2b --> pkg_invariants
+  pkg_jsonrpc_demo --> pkg_invariants
+  pkg_host_apiproxy --> pkg_invariants
+  pkg_host_directory_picker --> pkg_invariants
+  pkg_host_webserver --> pkg_invariants
+  pkg_storage --> pkg_invariants
+  pkg_subprocess --> pkg_invariants
+  pkg_type_meta --> pkg_invariants
+  pkg_typert_generator --> pkg_invariants
+  pkg_typert_registry --> pkg_invariants
+  pkg_llm --> pkg_brand
+  pkg_llm --> pkg_invariants
+  pkg_llm --> pkg_timeout
+  pkg_client_connection --> pkg_host_webserver
+  pkg_client_connection --> pkg_invariants
+  pkg_client_hmr --> pkg_client_modules
+  pkg_client_hmr --> pkg_host_webserver
+  pkg_client_hmr --> pkg_invariants
+  pkg_client_runtime --> pkg_invariants
+  pkg_client_runtime --> pkg_type_meta
+  pkg_client_runtime --> pkg_typert_registry
+  pkg_credentials --> pkg_brand
+  pkg_credentials --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_e2b
+  pkg_subprocess_e2b --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_subprocess
+  pkg_subprocess_e2b --> pkg_timeout
+  pkg_frontend_static --> pkg_host_webserver
+  pkg_frontend_static --> pkg_invariants
+  pkg_helper --> pkg_brand
+  pkg_helper --> pkg_invariants
+  pkg_helper --> pkg_subprocess
+  pkg_telemetry --> pkg_brand
+  pkg_telemetry --> pkg_invariants
+  pkg_telemetry --> pkg_paths
+  pkg_settings --> pkg_brand
+  pkg_settings --> pkg_invariants
+  pkg_storage_domain --> pkg_invariants
+  pkg_storage_domain --> pkg_storage
+  pkg_storage_json --> pkg_invariants
+  pkg_storage_json --> pkg_storage
+  pkg_storage_sqlite --> pkg_invariants
+  pkg_storage_sqlite --> pkg_storage
+  pkg_subprocess_local --> pkg_invariants
+  pkg_subprocess_local --> pkg_subprocess
+  pkg_subprocess_local --> pkg_timeout
+  pkg_typert_loader --> pkg_invariants
+  pkg_typert_loader --> pkg_typert_registry
+  pkg_llm_deepseek --> pkg_credentials
+  pkg_llm_deepseek --> pkg_environment
+  pkg_llm_deepseek --> pkg_invariants
+  pkg_llm_deepseek --> pkg_llm
+  pkg_llm_deepseek --> pkg_settings
+  pkg_llm_deepseek --> pkg_timeout
+  pkg_llm_pi_ai --> pkg_credentials
+  pkg_llm_pi_ai --> pkg_environment
+  pkg_llm_pi_ai --> pkg_invariants
+  pkg_llm_pi_ai --> pkg_llm
+  pkg_llm_pi_ai --> pkg_settings
+  pkg_llm_pi_ai --> pkg_timeout
+  pkg_session --> pkg_brand
+  pkg_session --> pkg_invariants
+  pkg_session --> pkg_llm
+  pkg_session --> pkg_scope
+  pkg_session --> pkg_type_meta
+  pkg_system_prompt --> pkg_invariants
+  pkg_system_prompt --> pkg_llm
+  pkg_system_prompt --> pkg_scope
+  pkg_skill --> pkg_invariants
+  pkg_skill --> pkg_llm
+  pkg_web --> pkg_invariants
+  pkg_web --> pkg_llm
+  pkg_api_gateway --> pkg_client_connection
+  pkg_api_gateway --> pkg_invariants
+  pkg_api_gateway --> pkg_typert_registry
+  pkg_client_locale --> pkg_client_runtime
+  pkg_client_locale --> pkg_client_ui_primitives
+  pkg_client_locale --> pkg_client_ui_slots
+  pkg_client_locale --> pkg_invariants
+  pkg_client_test_runtime --> pkg_client_runtime
+  pkg_client_test_runtime --> pkg_client_ui_slots
+  pkg_client_test_runtime --> pkg_client_web_react
+  pkg_client_test_runtime --> pkg_host_apiproxy
+  pkg_client_test_runtime --> pkg_invariants
+  pkg_client_ui_models --> pkg_client_connection
+  pkg_client_ui_models --> pkg_client_runtime
+  pkg_client_ui_models --> pkg_client_schema_form
+  pkg_client_ui_models --> pkg_client_ui_primitives
+  pkg_client_ui_models --> pkg_client_ui_slots
+  pkg_client_ui_models --> pkg_client_web_react
+  pkg_client_ui_models --> pkg_invariants
+  pkg_client_ui_settings --> pkg_client_runtime
+  pkg_client_ui_settings --> pkg_client_ui_primitives
+  pkg_client_ui_settings --> pkg_client_ui_slots
+  pkg_client_ui_settings --> pkg_invariants
+  pkg_client_ui_trajectory --> pkg_client_runtime
+  pkg_client_ui_trajectory --> pkg_client_ui_primitives
+  pkg_client_ui_trajectory --> pkg_invariants
+  pkg_credentials_local --> pkg_atomic_write
+  pkg_credentials_local --> pkg_credentials
+  pkg_credentials_local --> pkg_environment
+  pkg_credentials_local --> pkg_invariants
+  pkg_credentials_local --> pkg_paths
+  pkg_lsp --> pkg_brand
+  pkg_lsp --> pkg_invariants
+  pkg_lsp --> pkg_llm
+  pkg_sandbox --> pkg_invariants
+  pkg_sandbox --> pkg_llm
+  pkg_settings_local --> pkg_atomic_write
+  pkg_settings_local --> pkg_invariants
+  pkg_settings_local --> pkg_paths
+  pkg_settings_local --> pkg_settings
+  pkg_agent --> pkg_invariants
+  pkg_agent --> pkg_llm
+  pkg_agent --> pkg_scope
+  pkg_agent --> pkg_session
+  pkg_agent --> pkg_system_prompt
+  pkg_agent --> pkg_type_meta
+  pkg_bash --> pkg_invariants
+  pkg_bash --> pkg_sandbox
+  pkg_bash --> pkg_subprocess
+  pkg_fs --> pkg_brand
+  pkg_fs --> pkg_invariants
+  pkg_fs --> pkg_llm
+  pkg_fs --> pkg_sandbox
+  pkg_skill_badge --> pkg_invariants
+  pkg_skill_badge --> pkg_skill
+  pkg_compact --> pkg_invariants
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
+  pkg_web_fetch_local --> pkg_invariants
+  pkg_web_fetch_local --> pkg_timeout
+  pkg_web_fetch_local --> pkg_web
+  pkg_web_search_exa --> pkg_environment
+  pkg_web_search_exa --> pkg_invariants
+  pkg_web_search_exa --> pkg_web
+  pkg_web_search_perplexity --> pkg_environment
+  pkg_web_search_perplexity --> pkg_invariants
+  pkg_web_search_perplexity --> pkg_web
+  pkg_spill --> pkg_brand
+  pkg_spill --> pkg_invariants
+  pkg_spill --> pkg_llm
+  pkg_spill --> pkg_session
+  pkg_acp_snapshot --> pkg_invariants
+  pkg_acp_snapshot --> pkg_session
+  pkg_app_boot --> pkg_environment
+  pkg_app_boot --> pkg_invariants
+  pkg_app_boot --> pkg_paths
+  pkg_app_boot --> pkg_system_prompt
+  pkg_client_ui_question --> pkg_client_locale
+  pkg_client_ui_question --> pkg_invariants
+  pkg_client_ui_settings_general --> pkg_client_connection
+  pkg_client_ui_settings_general --> pkg_client_locale
+  pkg_client_ui_settings_general --> pkg_client_runtime
+  pkg_client_ui_settings_general --> pkg_client_ui_primitives
+  pkg_client_ui_settings_general --> pkg_client_ui_settings
+  pkg_client_ui_settings_general --> pkg_client_ui_slots
+  pkg_client_ui_settings_general --> pkg_client_web_react
+  pkg_client_ui_settings_general --> pkg_invariants
+  pkg_client_ui_sidebar --> pkg_client_locale
+  pkg_client_ui_sidebar --> pkg_client_runtime
+  pkg_client_ui_sidebar --> pkg_client_ui_primitives
+  pkg_client_ui_sidebar --> pkg_client_ui_slots
+  pkg_client_ui_sidebar --> pkg_invariants
+  pkg_client_ui_slash --> pkg_client_locale
+  pkg_client_ui_slash --> pkg_client_runtime
+  pkg_client_ui_slash --> pkg_client_ui_primitives
+  pkg_client_ui_slash --> pkg_client_ui_slots
+  pkg_client_ui_slash --> pkg_invariants
+  pkg_client_ui_theme --> pkg_client_locale
+  pkg_client_ui_theme --> pkg_client_runtime
+  pkg_client_ui_theme --> pkg_client_ui_primitives
+  pkg_client_ui_theme --> pkg_client_ui_slots
+  pkg_client_ui_theme --> pkg_invariants
+  pkg_client_ui_workspace --> pkg_client_locale
+  pkg_client_ui_workspace --> pkg_client_runtime
+  pkg_client_ui_workspace --> pkg_client_ui_primitives
+  pkg_client_ui_workspace --> pkg_client_ui_slots
+  pkg_client_ui_workspace --> pkg_invariants
+  pkg_code_runtime_worker --> pkg_code_runtime
+  pkg_code_runtime_worker --> pkg_invariants
+  pkg_code_runtime_worker --> pkg_session
+  pkg_code_runtime_worker --> pkg_timeout
+  pkg_sandbox_local --> pkg_invariants
+  pkg_sandbox_local --> pkg_llm
+  pkg_sandbox_local --> pkg_sandbox
+  pkg_session_persistence --> pkg_brand
+  pkg_session_persistence --> pkg_invariants
+  pkg_session_persistence --> pkg_session
+  pkg_session_persistence --> pkg_timeout
+  pkg_session_projection --> pkg_invariants
+  pkg_session_projection --> pkg_session
+  pkg_llm_retry --> pkg_agent
+  pkg_llm_retry --> pkg_invariants
+  pkg_llm_retry --> pkg_llm
+  pkg_llm_retry --> pkg_session
+  pkg_llm_retry --> pkg_timeout
+  pkg_token_meter --> pkg_compact
+  pkg_token_meter --> pkg_invariants
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
+  pkg_token_meter --> pkg_session_projection
+  pkg_goal --> pkg_agent
+  pkg_goal --> pkg_brand
+  pkg_goal --> pkg_invariants
+  pkg_goal --> pkg_llm
+  pkg_goal --> pkg_scope
+  pkg_goal --> pkg_session
+  pkg_goal --> pkg_session_projection
+  pkg_goal --> pkg_type_meta
+  pkg_bash_local --> pkg_bash
+  pkg_bash_local --> pkg_invariants
+  pkg_bash_local --> pkg_subprocess
+  pkg_bash_local --> pkg_timeout
+  pkg_pwsh_local --> pkg_bash
+  pkg_pwsh_local --> pkg_invariants
+  pkg_pwsh_local --> pkg_subprocess
+  pkg_pwsh_local --> pkg_timeout
+  pkg_fs_local --> pkg_fs
+  pkg_fs_local --> pkg_invariants
+  pkg_fs_policy --> pkg_fs
+  pkg_fs_policy --> pkg_invariants
+  pkg_skill_local --> pkg_fs
+  pkg_skill_local --> pkg_invariants
+  pkg_skill_local --> pkg_paths
+  pkg_skill_local --> pkg_skill
+  pkg_web_search_deepseek --> pkg_agent
+  pkg_web_search_deepseek --> pkg_credentials
+  pkg_web_search_deepseek --> pkg_environment
+  pkg_web_search_deepseek --> pkg_invariants
+  pkg_web_search_deepseek --> pkg_session
+  pkg_web_search_deepseek --> pkg_web
+  pkg_spill_local --> pkg_invariants
+  pkg_spill_local --> pkg_spill
+  pkg_hook_protocol --> pkg_bash
+  pkg_hook_protocol --> pkg_invariants
+  pkg_hook_protocol --> pkg_session
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
+  pkg_loader_smoke --> pkg_agent
+  pkg_loader_smoke --> pkg_invariants
+  pkg_loader_smoke --> pkg_llm
+  pkg_loader_smoke --> pkg_session
+  pkg_headless --> pkg_agent
+  pkg_headless --> pkg_host_apiproxy
+  pkg_headless --> pkg_host_webserver
+  pkg_headless --> pkg_invariants
+  pkg_headless --> pkg_session
+  pkg_client_ui_layout --> pkg_client_runtime
+  pkg_client_ui_layout --> pkg_client_ui_slots
+  pkg_client_ui_layout --> pkg_client_ui_theme
+  pkg_client_ui_layout --> pkg_invariants
+  pkg_time_context --> pkg_agent
+  pkg_time_context --> pkg_invariants
+  pkg_time_context --> pkg_session
+  pkg_tmux_context --> pkg_agent
+  pkg_tmux_context --> pkg_bash
+  pkg_tmux_context --> pkg_invariants
+  pkg_tmux_context --> pkg_session
+  pkg_fs_e2b --> pkg_e2b
+  pkg_fs_e2b --> pkg_fs
+  pkg_fs_e2b --> pkg_invariants
+  pkg_host_directory_picker_browse --> pkg_client_locale
+  pkg_host_directory_picker_browse --> pkg_client_runtime
+  pkg_host_directory_picker_browse --> pkg_client_ui_primitives
+  pkg_host_directory_picker_browse --> pkg_client_ui_slots
+  pkg_host_directory_picker_browse --> pkg_client_ui_workspace
+  pkg_host_directory_picker_browse --> pkg_invariants
+  pkg_host_directory_picker_native --> pkg_client_runtime
+  pkg_host_directory_picker_native --> pkg_client_ui_slots
+  pkg_host_directory_picker_native --> pkg_client_ui_workspace
+  pkg_host_directory_picker_native --> pkg_invariants
+  pkg_commands --> pkg_agent
+  pkg_commands --> pkg_brand
+  pkg_commands --> pkg_invariants
+  pkg_commands --> pkg_scope
+  pkg_commands --> pkg_session
+  pkg_user_approval --> pkg_agent
+  pkg_user_approval --> pkg_brand
+  pkg_user_approval --> pkg_invariants
+  pkg_user_approval --> pkg_llm
+  pkg_user_approval --> pkg_scope
+  pkg_user_approval --> pkg_session
+  pkg_user_approval --> pkg_system_prompt
+  pkg_user_interaction --> pkg_agent
+  pkg_user_interaction --> pkg_invariants
+  pkg_user_interaction --> pkg_llm
+  pkg_lsp_local --> pkg_brand
+  pkg_lsp_local --> pkg_fs
+  pkg_lsp_local --> pkg_invariants
+  pkg_lsp_local --> pkg_llm
+  pkg_lsp_local --> pkg_lsp
+  pkg_lsp_local --> pkg_subprocess
+  pkg_lsp_local --> pkg_timeout
+  pkg_pty --> pkg_agent
+  pkg_pty --> pkg_brand
+  pkg_pty --> pkg_invariants
+  pkg_sandbox_policy --> pkg_agent
+  pkg_sandbox_policy --> pkg_invariants
+  pkg_sandbox_policy --> pkg_sandbox
+  pkg_sandbox_policy --> pkg_session
+  pkg_sandbox_policy --> pkg_system_prompt
+  pkg_scripts --> pkg_app_boot
+  pkg_scripts --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_session
+  pkg_session_persistence_jsonl --> pkg_session_persistence
+  pkg_session_persistence_sqlite --> pkg_invariants
+  pkg_session_persistence_sqlite --> pkg_session
+  pkg_session_persistence_sqlite --> pkg_session_persistence
+  pkg_session_projection_cache --> pkg_invariants
+  pkg_session_projection_cache --> pkg_session
+  pkg_session_projection_cache --> pkg_session_persistence
+  pkg_session_projection_cache --> pkg_session_projection
+  pkg_session_projection_cache --> pkg_storage_domain
+  pkg_session_telemetry --> pkg_agent
+  pkg_session_telemetry --> pkg_invariants
+  pkg_session_telemetry --> pkg_session
+  pkg_session_title --> pkg_brand
+  pkg_session_title --> pkg_invariants
+  pkg_session_title --> pkg_llm
+  pkg_session_title --> pkg_session
+  pkg_session_title --> pkg_session_projection
+  pkg_tasks --> pkg_agent
+  pkg_tasks --> pkg_brand
+  pkg_tasks --> pkg_invariants
+  pkg_tasks --> pkg_session
+  pkg_workflow --> pkg_agent
+  pkg_workflow --> pkg_brand
+  pkg_workflow --> pkg_invariants
+  pkg_workflow --> pkg_llm
+  pkg_workflow --> pkg_session
+  pkg_workspace --> pkg_brand
+  pkg_workspace --> pkg_invariants
+  pkg_workspace --> pkg_session
+  pkg_workspace --> pkg_session_persistence
+  pkg_workspace --> pkg_storage
+  pkg_workspace --> pkg_storage_domain
+  pkg_tools --> pkg_agent
+  pkg_tools --> pkg_code_runtime
+  pkg_tools --> pkg_invariants
+  pkg_tools --> pkg_llm
+  pkg_tools --> pkg_scope
+  pkg_tools --> pkg_session
+  pkg_tools --> pkg_system_prompt
+  pkg_tools --> pkg_user_approval
+  pkg_command_goal --> pkg_commands
+  pkg_command_goal --> pkg_goal
+  pkg_command_goal --> pkg_invariants
+  pkg_goal_session --> pkg_agent
+  pkg_goal_session --> pkg_goal
+  pkg_goal_session --> pkg_invariants
+  pkg_goal_session --> pkg_llm
+  pkg_goal_session --> pkg_session
+  pkg_bash_sandbox --> pkg_bash
+  pkg_bash_sandbox --> pkg_bash_local
+  pkg_bash_sandbox --> pkg_invariants
+  pkg_bash_sandbox --> pkg_sandbox
+  pkg_bash_sandbox --> pkg_sandbox_policy
+  pkg_fs_sandbox --> pkg_fs
+  pkg_fs_sandbox --> pkg_fs_local
+  pkg_fs_sandbox --> pkg_invariants
+  pkg_fs_sandbox --> pkg_sandbox
+  pkg_fs_sandbox --> pkg_sandbox_policy
+  pkg_command_compact --> pkg_commands
+  pkg_command_compact --> pkg_compact
+  pkg_command_compact --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
+  pkg_session_query --> pkg_brand
+  pkg_session_query --> pkg_invariants
+  pkg_session_query --> pkg_llm
+  pkg_session_query --> pkg_session
+  pkg_session_query --> pkg_session_persistence
+  pkg_session_query --> pkg_session_title
+  pkg_acp --> pkg_agent
+  pkg_acp --> pkg_invariants
+  pkg_acp --> pkg_session
+  pkg_acp --> pkg_user_approval
+  pkg_api_remotes --> pkg_agent
+  pkg_api_remotes --> pkg_goal
+  pkg_api_remotes --> pkg_invariants
+  pkg_api_remotes --> pkg_session
+  pkg_api_remotes --> pkg_session_persistence
+  pkg_api_remotes --> pkg_typert_registry
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_token_meter
+  pkg_command_feedback --> pkg_commands
+  pkg_command_feedback --> pkg_invariants
+  pkg_command_feedback --> pkg_session
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
+  pkg_host_directory_picker_auto --> pkg_host_webserver
+  pkg_host_directory_picker_auto --> pkg_invariants
+  pkg_permission --> pkg_bash
+  pkg_permission --> pkg_commands
+  pkg_permission --> pkg_invariants
+  pkg_permission --> pkg_sandbox
+  pkg_permission --> pkg_sandbox_policy
+  pkg_permission --> pkg_session
+  pkg_permission --> pkg_session_projection
+  pkg_permission --> pkg_settings
+  pkg_permission --> pkg_user_approval
+  pkg_pty_local --> pkg_agent
+  pkg_pty_local --> pkg_invariants
+  pkg_pty_local --> pkg_pty
+  pkg_pty_local --> pkg_sandbox
+  pkg_pty_local --> pkg_sandbox_policy
+  pkg_pty_local --> pkg_session
+  pkg_pty_local --> pkg_subprocess
+  pkg_session_title_llm --> pkg_invariants
+  pkg_session_title_llm --> pkg_llm
+  pkg_session_title_llm --> pkg_session
+  pkg_session_title_llm --> pkg_session_title
+  pkg_session_title_llm --> pkg_timeout
+  pkg_tasks_local --> pkg_agent
+  pkg_tasks_local --> pkg_invariants
+  pkg_tasks_local --> pkg_tasks
+  pkg_tasks_local --> pkg_timeout
+  pkg_agent_loop --> pkg_agent
+  pkg_agent_loop --> pkg_invariants
+  pkg_agent_loop --> pkg_llm
+  pkg_agent_loop --> pkg_scope
+  pkg_agent_loop --> pkg_session
+  pkg_agent_loop --> pkg_session_persistence
+  pkg_agent_loop --> pkg_system_prompt
+  pkg_agent_loop --> pkg_tools
+  pkg_tool_goal --> pkg_agent
+  pkg_tool_goal --> pkg_goal
+  pkg_tool_goal --> pkg_invariants
+  pkg_tool_goal --> pkg_llm
+  pkg_tool_goal --> pkg_session
+  pkg_tool_goal --> pkg_system_prompt
+  pkg_tool_goal --> pkg_tools
+  pkg_bash_env --> pkg_bash
+  pkg_bash_env --> pkg_invariants
+  pkg_bash_env --> pkg_paths
+  pkg_bash_env --> pkg_session_persistence
+  pkg_bash_env --> pkg_tools
+  pkg_tool_fs --> pkg_fs
+  pkg_tool_fs --> pkg_invariants
+  pkg_tool_fs --> pkg_llm
+  pkg_tool_fs --> pkg_sandbox
+  pkg_tool_fs --> pkg_sandbox_policy
+  pkg_tool_fs --> pkg_session
+  pkg_tool_fs --> pkg_system_prompt
+  pkg_tool_fs --> pkg_tools
+  pkg_tool_fs --> pkg_user_approval
+  pkg_tool_fs_search --> pkg_invariants
+  pkg_tool_fs_search --> pkg_llm
+  pkg_tool_fs_search --> pkg_retention
+  pkg_tool_fs_search --> pkg_session
+  pkg_tool_fs_search --> pkg_spill
+  pkg_tool_fs_search --> pkg_subprocess
+  pkg_tool_fs_search --> pkg_system_prompt
+  pkg_tool_fs_search --> pkg_timeout
+  pkg_tool_fs_search --> pkg_tools
+  pkg_tool_str_replace_editor --> pkg_fs
+  pkg_tool_str_replace_editor --> pkg_invariants
+  pkg_tool_str_replace_editor --> pkg_sandbox
+  pkg_tool_str_replace_editor --> pkg_sandbox_policy
+  pkg_tool_str_replace_editor --> pkg_tools
+  pkg_tool_skill --> pkg_agent
+  pkg_tool_skill --> pkg_invariants
+  pkg_tool_skill --> pkg_llm
+  pkg_tool_skill --> pkg_skill
+  pkg_tool_skill --> pkg_tools
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
+  pkg_subagent --> pkg_agent
+  pkg_subagent --> pkg_brand
+  pkg_subagent --> pkg_invariants
+  pkg_subagent --> pkg_llm
+  pkg_subagent --> pkg_scope
+  pkg_subagent --> pkg_session
+  pkg_subagent --> pkg_session_persistence
+  pkg_subagent --> pkg_session_projection
+  pkg_subagent --> pkg_session_projection_cache
+  pkg_subagent --> pkg_tasks
+  pkg_subagent --> pkg_tools
+  pkg_tool_web --> pkg_invariants
+  pkg_tool_web --> pkg_llm
+  pkg_tool_web --> pkg_system_prompt
+  pkg_tool_web --> pkg_tools
+  pkg_tool_web --> pkg_web
+  pkg_spill_policy --> pkg_invariants
+  pkg_spill_policy --> pkg_llm
+  pkg_spill_policy --> pkg_retention
+  pkg_spill_policy --> pkg_session
+  pkg_spill_policy --> pkg_spill
+  pkg_spill_policy --> pkg_tools
+  pkg_tool_todo --> pkg_agent
+  pkg_tool_todo --> pkg_invariants
+  pkg_tool_todo --> pkg_session
+  pkg_tool_todo --> pkg_session_projection
+  pkg_tool_todo --> pkg_tools
+  pkg_plan_mode --> pkg_agent
+  pkg_plan_mode --> pkg_commands
+  pkg_plan_mode --> pkg_invariants
+  pkg_plan_mode --> pkg_llm
+  pkg_plan_mode --> pkg_session
+  pkg_plan_mode --> pkg_session_projection
+  pkg_plan_mode --> pkg_system_prompt
+  pkg_plan_mode --> pkg_tools
+  pkg_plan_mode --> pkg_user_interaction
+  pkg_hooks_codex --> pkg_agent
+  pkg_hooks_codex --> pkg_hook_protocol
+  pkg_hooks_codex --> pkg_invariants
+  pkg_hooks_codex --> pkg_llm
+  pkg_hooks_codex --> pkg_session
+  pkg_hooks_codex --> pkg_session_persistence
+  pkg_hooks_codex --> pkg_tools
+  pkg_session_query_sqlite --> pkg_invariants
+  pkg_session_query_sqlite --> pkg_session
+  pkg_session_query_sqlite --> pkg_session_persistence
+  pkg_session_query_sqlite --> pkg_session_query
+  pkg_tool_session_query --> pkg_invariants
+  pkg_tool_session_query --> pkg_llm
+  pkg_tool_session_query --> pkg_session
+  pkg_tool_session_query --> pkg_session_query
+  pkg_tool_session_query --> pkg_system_prompt
+  pkg_tool_session_query --> pkg_timeout
+  pkg_tool_session_query --> pkg_tools
+  pkg_agent_loop_testkit --> pkg_agent
+  pkg_agent_loop_testkit --> pkg_invariants
+  pkg_agent_loop_testkit --> pkg_llm
+  pkg_agent_loop_testkit --> pkg_session
+  pkg_agent_loop_testkit --> pkg_system_prompt
+  pkg_agent_loop_testkit --> pkg_tools
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
+  pkg_session_reference --> pkg_agent
+  pkg_session_reference --> pkg_compact
+  pkg_session_reference --> pkg_invariants
+  pkg_session_reference --> pkg_llm
+  pkg_session_reference --> pkg_retention
+  pkg_session_reference --> pkg_session
+  pkg_session_reference --> pkg_session_query
+  pkg_workspace_context --> pkg_agent
+  pkg_workspace_context --> pkg_fs
+  pkg_workspace_context --> pkg_invariants
+  pkg_workspace_context --> pkg_llm
+  pkg_workspace_context --> pkg_paths
+  pkg_workspace_context --> pkg_session
+  pkg_workspace_context --> pkg_tools
+  pkg_repeat_tool_guard --> pkg_agent
+  pkg_repeat_tool_guard --> pkg_invariants
+  pkg_repeat_tool_guard --> pkg_tools
+  pkg_timeout_policy --> pkg_invariants
+  pkg_timeout_policy --> pkg_llm
+  pkg_timeout_policy --> pkg_timeout
+  pkg_timeout_policy --> pkg_tools
+  pkg_tool_ask_user --> pkg_agent
+  pkg_tool_ask_user --> pkg_invariants
+  pkg_tool_ask_user --> pkg_tools
+  pkg_tool_ask_user --> pkg_user_interaction
+  pkg_tool_lsp --> pkg_invariants
+  pkg_tool_lsp --> pkg_llm
+  pkg_tool_lsp --> pkg_lsp
+  pkg_tool_lsp --> pkg_system_prompt
+  pkg_tool_lsp --> pkg_timeout
+  pkg_tool_lsp --> pkg_tools
+  pkg_mcp_client --> pkg_invariants
+  pkg_mcp_client --> pkg_llm
+  pkg_mcp_client --> pkg_subprocess
+  pkg_mcp_client --> pkg_tools
+  pkg_tool_bash_persistent --> pkg_agent
+  pkg_tool_bash_persistent --> pkg_invariants
+  pkg_tool_bash_persistent --> pkg_pty
+  pkg_tool_bash_persistent --> pkg_timeout
+  pkg_tool_bash_persistent --> pkg_tools
+  pkg_tool_pty --> pkg_agent
+  pkg_tool_pty --> pkg_invariants
+  pkg_tool_pty --> pkg_llm
+  pkg_tool_pty --> pkg_pty
+  pkg_tool_pty --> pkg_retention
+  pkg_tool_pty --> pkg_system_prompt
+  pkg_tool_pty --> pkg_tasks
+  pkg_tool_pty --> pkg_tools
+  pkg_tool_cordis --> pkg_invariants
+  pkg_tool_cordis --> pkg_scope
+  pkg_tool_cordis --> pkg_tools
+  pkg_session_checkpoint_policy --> pkg_agent
+  pkg_session_checkpoint_policy --> pkg_invariants
+  pkg_session_checkpoint_policy --> pkg_llm
+  pkg_session_checkpoint_policy --> pkg_session
+  pkg_session_checkpoint_policy --> pkg_session_persistence
+  pkg_session_checkpoint_policy --> pkg_tools
+  pkg_session_telemetry_otel --> pkg_brand
+  pkg_session_telemetry_otel --> pkg_command_feedback
+  pkg_session_telemetry_otel --> pkg_invariants
+  pkg_session_telemetry_otel --> pkg_llm
+  pkg_session_telemetry_otel --> pkg_paths
+  pkg_session_telemetry_otel --> pkg_session
+  pkg_session_telemetry_otel --> pkg_session_telemetry
+  pkg_session_title_all_messages_llm --> pkg_invariants
+  pkg_session_title_all_messages_llm --> pkg_llm
+  pkg_session_title_all_messages_llm --> pkg_session
+  pkg_session_title_all_messages_llm --> pkg_session_title
+  pkg_session_title_all_messages_llm --> pkg_session_title_llm
+  pkg_session_title_first_message_llm --> pkg_invariants
+  pkg_session_title_first_message_llm --> pkg_llm
+  pkg_session_title_first_message_llm --> pkg_session
+  pkg_session_title_first_message_llm --> pkg_session_title
+  pkg_session_title_first_message_llm --> pkg_session_title_llm
+  pkg_tool_tasks --> pkg_agent
+  pkg_tool_tasks --> pkg_invariants
+  pkg_tool_tasks --> pkg_llm
+  pkg_tool_tasks --> pkg_retention
+  pkg_tool_tasks --> pkg_system_prompt
+  pkg_tool_tasks --> pkg_tasks
+  pkg_tool_tasks --> pkg_tools
+  pkg_tool_workflow --> pkg_agent
+  pkg_tool_workflow --> pkg_invariants
+  pkg_tool_workflow --> pkg_llm
+  pkg_tool_workflow --> pkg_system_prompt
+  pkg_tool_workflow --> pkg_tools
+  pkg_tool_workflow --> pkg_workflow
+  pkg_tool_bash --> pkg_agent
+  pkg_tool_bash --> pkg_bash
+  pkg_tool_bash --> pkg_bash_env
+  pkg_tool_bash --> pkg_invariants
+  pkg_tool_bash --> pkg_llm
+  pkg_tool_bash --> pkg_sandbox
+  pkg_tool_bash --> pkg_sandbox_policy
+  pkg_tool_bash --> pkg_system_prompt
+  pkg_tool_bash --> pkg_tasks
+  pkg_tool_bash --> pkg_tools
+  pkg_tool_bash --> pkg_user_approval
+  pkg_tool_pwsh --> pkg_agent
+  pkg_tool_pwsh --> pkg_bash
+  pkg_tool_pwsh --> pkg_bash_env
+  pkg_tool_pwsh --> pkg_invariants
+  pkg_tool_pwsh --> pkg_llm
+  pkg_tool_pwsh --> pkg_system_prompt
+  pkg_tool_pwsh --> pkg_tasks
+  pkg_tool_pwsh --> pkg_tools
+  pkg_subagent_acp --> pkg_agent
+  pkg_subagent_acp --> pkg_invariants
+  pkg_subagent_acp --> pkg_llm
+  pkg_subagent_acp --> pkg_session
+  pkg_subagent_acp --> pkg_subagent
+  pkg_subagent_acp --> pkg_subprocess
+  pkg_subagent_acp --> pkg_timeout
+  pkg_subagent_claude_code --> pkg_invariants
+  pkg_subagent_claude_code --> pkg_llm
+  pkg_subagent_claude_code --> pkg_session
+  pkg_subagent_claude_code --> pkg_subagent
+  pkg_subagent_claude_code --> pkg_subprocess
+  pkg_subagent_claude_code --> pkg_timeout
+  pkg_subagent_inprocess --> pkg_agent
+  pkg_subagent_inprocess --> pkg_invariants
+  pkg_subagent_inprocess --> pkg_llm
+  pkg_subagent_inprocess --> pkg_sandbox_policy
+  pkg_subagent_inprocess --> pkg_session
+  pkg_subagent_inprocess --> pkg_subagent
+  pkg_subagent_inprocess --> pkg_system_prompt
+  pkg_subagent_inprocess --> pkg_tools
+  pkg_subagent_inprocess --> pkg_user_approval
+  pkg_tool_subagent --> pkg_agent
+  pkg_tool_subagent --> pkg_invariants
+  pkg_tool_subagent --> pkg_llm
+  pkg_tool_subagent --> pkg_subagent
+  pkg_tool_subagent --> pkg_tasks
+  pkg_tool_subagent --> pkg_tools
+  pkg_tool_subagent_control --> pkg_invariants
+  pkg_tool_subagent_control --> pkg_llm
+  pkg_tool_subagent_control --> pkg_session
+  pkg_tool_subagent_control --> pkg_subagent
+  pkg_tool_subagent_control --> pkg_tools
+  pkg_tool_subagent_report --> pkg_invariants
+  pkg_tool_subagent_report --> pkg_llm
+  pkg_tool_subagent_report --> pkg_subagent
+  pkg_tool_subagent_report --> pkg_tools
+  pkg_hooks_claude --> pkg_agent
+  pkg_hooks_claude --> pkg_hook_protocol
+  pkg_hooks_claude --> pkg_invariants
+  pkg_hooks_claude --> pkg_llm
+  pkg_hooks_claude --> pkg_session
+  pkg_hooks_claude --> pkg_session_persistence
+  pkg_hooks_claude --> pkg_subagent
+  pkg_hooks_claude --> pkg_tools
+  pkg_web_app --> pkg_bash_env
+  pkg_web_app --> pkg_invariants
+  pkg_web_app --> pkg_system_prompt
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_sdk_protocol --> pkg_invariants
+  pkg_sdk_protocol --> pkg_llm
+  pkg_sdk_protocol --> pkg_session
+  pkg_sdk_protocol --> pkg_subagent
+  pkg_repository_plugin --> pkg_invariants
+  pkg_repository_plugin --> pkg_mcp_client
+  pkg_repository_plugin --> pkg_paths
+  pkg_repository_plugin --> pkg_skill_local
+  pkg_tool_ralph --> pkg_agent
+  pkg_tool_ralph --> pkg_invariants
+  pkg_tool_ralph --> pkg_llm
+  pkg_tool_ralph --> pkg_subagent
+  pkg_tool_ralph --> pkg_system_prompt
+  pkg_tool_ralph --> pkg_tools
+  pkg_tool_ralph --> pkg_workflow
+  pkg_workflow_workerthread --> pkg_agent
+  pkg_workflow_workerthread --> pkg_brand
+  pkg_workflow_workerthread --> pkg_invariants
+  pkg_workflow_workerthread --> pkg_llm
+  pkg_workflow_workerthread --> pkg_session
+  pkg_workflow_workerthread --> pkg_subagent
+  pkg_workflow_workerthread --> pkg_tools
+  pkg_workflow_workerthread --> pkg_workflow
+  pkg_subagent_codex --> pkg_invariants
+  pkg_subagent_codex --> pkg_llm
+  pkg_subagent_codex --> pkg_sdk_protocol
+  pkg_subagent_codex --> pkg_session
+  pkg_subagent_codex --> pkg_subagent
+  pkg_subagent_codex --> pkg_subprocess
+  pkg_subagent_codex --> pkg_timeout
+  pkg_subagent_fork --> pkg_agent
+  pkg_subagent_fork --> pkg_invariants
+  pkg_subagent_fork --> pkg_session
+  pkg_subagent_fork --> pkg_subagent
+  pkg_subagent_fork --> pkg_subagent_inprocess
+  pkg_subagent_spawn --> pkg_invariants
+  pkg_subagent_spawn --> pkg_subagent
+  pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_agent_spine_demo --> pkg_agent
+  pkg_agent_spine_demo --> pkg_agent_loop
+  pkg_agent_spine_demo --> pkg_bash_env
+  pkg_agent_spine_demo --> pkg_goal
+  pkg_agent_spine_demo --> pkg_goal_session
+  pkg_agent_spine_demo --> pkg_invariants
+  pkg_agent_spine_demo --> pkg_llm
+  pkg_agent_spine_demo --> pkg_llm_retry
+  pkg_agent_spine_demo --> pkg_paths
+  pkg_agent_spine_demo --> pkg_scope
+  pkg_agent_spine_demo --> pkg_session
+  pkg_agent_spine_demo --> pkg_session_title
+  pkg_agent_spine_demo --> pkg_skill
+  pkg_agent_spine_demo --> pkg_skill_local
+  pkg_agent_spine_demo --> pkg_system_prompt
+  pkg_agent_spine_demo --> pkg_tasks_local
+  pkg_agent_spine_demo --> pkg_tool_bash
+  pkg_agent_spine_demo --> pkg_tool_goal
+  pkg_agent_spine_demo --> pkg_tool_skill
+  pkg_agent_spine_demo --> pkg_tool_tasks
+  pkg_agent_spine_demo --> pkg_tools
+  pkg_agent_spine_demo --> pkg_workspace_context
+  pkg_jsonrpc --> pkg_agent
+  pkg_jsonrpc --> pkg_invariants
+  pkg_jsonrpc --> pkg_llm
+  pkg_jsonrpc --> pkg_llm_deepseek
+  pkg_jsonrpc --> pkg_scope
+  pkg_jsonrpc --> pkg_sdk_protocol
+  pkg_jsonrpc --> pkg_session
+  pkg_jsonrpc --> pkg_subagent
+  pkg_sdk_client --> pkg_invariants
+  pkg_sdk_client --> pkg_llm
+  pkg_sdk_client --> pkg_sdk_protocol
+  pkg_sdk_client --> pkg_session
+  pkg_subagent_dsh_sdk --> pkg_agent
+  pkg_subagent_dsh_sdk --> pkg_invariants
+  pkg_subagent_dsh_sdk --> pkg_llm
+  pkg_subagent_dsh_sdk --> pkg_sdk_client
+  pkg_subagent_dsh_sdk --> pkg_session
+  pkg_subagent_dsh_sdk --> pkg_subagent
+  pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_acp_demo --> pkg_acp
+  pkg_acp_demo --> pkg_agent_spine_demo
+  pkg_acp_demo --> pkg_app_boot
+  pkg_acp_demo --> pkg_invariants
+  pkg_acp_demo --> pkg_session_checkpoint_policy
+  pkg_acp_demo --> pkg_session_persistence_jsonl
+  pkg_acp_demo --> pkg_session_query
+  pkg_acp_demo --> pkg_session_query_sqlite
+  pkg_acp_demo --> pkg_tools
+  pkg_acp_demo --> pkg_workspace_context
+```
+
+| 包 | 分组 | 依赖项 |
+| --- | --- | --- |
+| [`invariants`](../packages/support/invariants) | `support` | — |
+| [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/support/invariants) |
+| [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/support/invariants) |
+| [`environment`](../packages/util/environment) | `util` | [`invariants`](../packages/support/invariants) |
+| [`native-command`](../packages/util/native-command) | `util` | [`invariants`](../packages/support/invariants) |
+| [`paths`](../packages/util/paths) | `util` | [`invariants`](../packages/support/invariants) |
+| [`retention`](../packages/util/retention) | `util` | [`invariants`](../packages/support/invariants) |
+| [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
+| [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
+| [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
+| [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
+| [`client-modules`](../packages/client/modules) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-schema-form`](../packages/client/schema-form) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-web-react`](../packages/client/web-react) | `client` | [`invariants`](../packages/support/invariants) |
+| [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/support/invariants) |
+| [`e2b`](../packages/e2b/e2b) | `e2b` | [`invariants`](../packages/support/invariants) |
+| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | [`invariants`](../packages/support/invariants) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker`](../packages/host/directory-picker) | `host` | [`invariants`](../packages/support/invariants) |
+| [`host-webserver`](../packages/host/webserver) | `host` | [`invariants`](../packages/support/invariants) |
+| [`storage`](../packages/storage/storage) | `storage` | [`invariants`](../packages/support/invariants) |
+| [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`invariants`](../packages/support/invariants) |
+| [`type-meta`](../packages/typert/type-meta) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
+| [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
+| [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`helper`](../packages/scaffold/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`telemetry`](../packages/scaffold/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
+| [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
+| [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
+| [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
+| [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
+| [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
+| [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
+| [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
+| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`settings-local`](../packages/settings/settings-local) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`settings`](../packages/settings/settings) |
+| [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`type-meta`](../packages/typert/type-meta) |
+| [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
+| [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
+| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
+| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/support/acp-snapshot) | `session-persistence` | [`brand`](../packages/support/invariants), [`invariants`](../packages/core/session), [`session`](../packages/boot/app-boot), [`timeout`](../packages/util/environment) |
+| [`acp-snapshot`](../packages/support/invariants) | `support` | [`invariants`](../packages/util/paths), [`session`](../packages/core/system-prompt) |
+| [`app-boot`](../packages/client/ui-question) | `ui` | [`environment`](../packages/client/locale), [`invariants`](../packages/support/invariants), [`paths`](../packages/client/ui-settings-general), [`system-prompt`](../packages/client/connection) |
+| [`client-ui-question`](../packages/client/locale) | `client` | [`client-locale`](../packages/client/runtime), [`invariants`](../packages/client/ui-primitives) |
+| [`client-ui-settings-general`](../packages/client/ui-settings) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/web-react), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-sidebar), [`client-ui-settings`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-web-react`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-sidebar`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-slash`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-theme), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-theme`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-workspace), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-workspace`](../packages/support/invariants) | `client` | [`client-locale`](../packages/code-runtime/code-runtime-worker), [`client-runtime`](../packages/code-runtime/code-runtime), [`client-ui-primitives`](../packages/support/invariants), [`client-ui-slots`](../packages/core/session), [`invariants`](../packages/util/timeout) |
+| [`code-runtime-worker`](../packages/sandbox/sandbox-local) | `code-runtime` | [`code-runtime`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`session`](../packages/sandbox/sandbox), [`timeout`](../packages/session/session-persistence) |
+| [`sandbox-local`](../packages/util/brand) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/core/session), [`sandbox`](../packages/util/timeout) |
+| [`session-projection`](../packages/session/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
+| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`skill`](../packages/skill/skill) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
+| [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
+| [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-persistence-jsonl`](../packages/support/llm-replay) | `session-persistence` | [`invariants`](../packages/compact/compact), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm) |
+| [`session-persistence-sqlite`](../packages/core/session) | `session-persistence` | [`invariants`](../packages/support/loader-smoke), [`session`](../packages/core/agent), [`session-persistence`](../packages/support/invariants) |
+| [`session-title`](../packages/llm/llm) | `session-title` | [`brand`](../packages/core/session), [`invariants`](../packages/bundle/headless), [`llm`](../packages/core/agent), [`session`](../packages/host/apiproxy), [`session-projection`](../packages/host/webserver) |
+| [`llm-replay`](../packages/support/invariants) | `support` | [`compact`](../packages/core/session), [`invariants`](../packages/client/ui-layout), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-slots) |
+| [`loader-smoke`](../packages/client/ui-theme) | `support` | [`agent`](../packages/support/invariants), [`invariants`](../packages/context/time-context), [`llm`](../packages/core/agent), [`session`](../packages/support/invariants) |
+| [`commands`](../packages/core/session) | `ui` | [`agent`](../packages/context/tmux-context), [`brand`](../packages/core/agent), [`invariants`](../packages/bash/bash), [`scope`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`user-approval`](../packages/e2b/fs-e2b) | `ui` | [`agent`](../packages/e2b/e2b), [`brand`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-browse), [`scope`](../packages/client/locale), [`session`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-primitives) |
+| [`user-interaction`](../packages/client/ui-slots) | `ui` | [`agent`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-native) |
+| [`headless`](../packages/client/runtime) | `bundle` | [`agent`](../packages/client/ui-slots), [`host-apiproxy`](../packages/client/ui-workspace), [`host-webserver`](../packages/support/invariants), [`invariants`](../packages/interaction/commands), [`session`](../packages/core/agent) |
+| [`client-ui-layout`](../packages/util/brand) | `client` | [`client-runtime`](../packages/support/invariants), [`client-ui-slots`](../packages/core/scope), [`client-ui-theme`](../packages/core/session), [`invariants`](../packages/interaction/user-approval) |
+| [`time-context`](../packages/core/agent) | `context` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/llm/llm) |
+| [`tmux-context`](../packages/core/scope) | `context` | [`agent`](../packages/core/session), [`bash`](../packages/core/system-prompt), [`invariants`](../packages/interaction/user-interaction), [`session`](../packages/core/agent) |
+| [`fs-e2b`](../packages/support/invariants) | `e2b` | [`e2b`](../packages/llm/llm), [`fs`](../packages/lsp/lsp-local), [`invariants`](../packages/util/brand) |
+| [`host-directory-picker-browse`](../packages/fs/fs) | `host` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/llm/llm), [`client-ui-primitives`](../packages/lsp/lsp), [`client-ui-slots`](../packages/subprocess/subprocess), [`client-ui-workspace`](../packages/util/timeout), [`invariants`](../packages/pty/pty) |
+| [`host-directory-picker-native`](../packages/core/agent) | `host` | [`client-runtime`](../packages/util/brand), [`client-ui-slots`](../packages/support/invariants), [`client-ui-workspace`](../packages/sandbox/sandbox-policy), [`invariants`](../packages/core/agent) |
+| [`lsp-local`](../packages/support/invariants) | `lsp` | [`brand`](../packages/sandbox/sandbox), [`fs`](../packages/core/session), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/scaffold/scripts), [`lsp`](../packages/boot/app-boot), [`subprocess`](../packages/support/invariants), [`timeout`](../packages/session/session-persistence-jsonl) |
+| [`pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/core/session), [`brand`](../packages/session/session-persistence), [`invariants`](../packages/session/session-persistence-sqlite) |
+| [`sandbox-policy`](../packages/support/invariants) | `sandbox` | [`agent`](../packages/core/session), [`invariants`](../packages/session/session-persistence), [`sandbox`](../packages/session/session-projection-cache), [`session`](../packages/support/invariants), [`system-prompt`](../packages/core/session) |
+| [`scripts`](../packages/session/session-persistence) | `sdk` | [`app-boot`](../packages/session/session-projection), [`invariants`](../packages/storage/storage-domain) |
+| [`session-projection-cache`](../packages/session/session-telemetry) | `session-projection` | [`invariants`](../packages/core/agent), [`session`](../packages/support/invariants), [`session-persistence`](../packages/core/session), [`session-projection`](../packages/session/session-title), [`storage-domain`](../packages/util/brand) |
+| [`tasks`](../packages/support/invariants) | `tasks` | [`agent`](../packages/llm/llm), [`brand`](../packages/core/session), [`invariants`](../packages/session/session-projection), [`session`](../packages/tasks/tasks) |
+| [`session-telemetry`](../packages/core/agent) | `telemetry` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
+| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
+| [`session-title-llm`](../packages/acp/acp) | `session-title` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`session`](../packages/core/session), [`session-title`](../packages/interaction/user-approval), [`timeout`](../packages/api/remotes) |
+| [`acp`](../packages/core/agent) | `acp` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/session/session-persistence) |
+| [`permission`](../packages/typert/registry) | `ui` | [`bash`](../packages/client/ui-conversation), [`commands`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`sandbox`](../packages/client/ui-primitives), [`sandbox-policy`](../packages/client/ui-slash), [`session`](../packages/client/ui-slots), [`session-projection`](../packages/support/invariants), [`settings`](../packages/llm/token-meter), [`user-approval`](../packages/feedback/command-feedback) |
+| [`api-remotes`](../packages/interaction/commands) | `api` | [`agent`](../packages/support/invariants), [`goal`](../packages/core/session), [`invariants`](../packages/host/directory-picker-auto), [`session`](../packages/host/directory-picker-browse), [`session-persistence`](../packages/host/directory-picker-native), [`typert-registry`](../packages/host/webserver) |
+| [`client-ui-conversation`](../packages/support/invariants) | `client` | [`client-locale`](../packages/interaction/permission), [`client-runtime`](../packages/bash/bash), [`client-ui-primitives`](../packages/interaction/commands), [`client-ui-slash`](../packages/support/invariants), [`client-ui-slots`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy), [`token-meter`](../packages/core/session) |
+| [`command-feedback`](../packages/session/session-projection) | `feedback` | [`commands`](../packages/settings/settings), [`invariants`](../packages/interaction/user-approval), [`session`](../packages/pty/pty-local) |
+| [`host-directory-picker-auto`](../packages/core/agent) | `host` | [`host-directory-picker-browse`](../packages/support/invariants), [`host-directory-picker-native`](../packages/pty/pty), [`host-webserver`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy) |
+| [`pty-local`](../packages/core/session) | `pty` | [`agent`](../packages/subprocess/subprocess), [`invariants`](../packages/session/session-title-llm), [`pty`](../packages/support/invariants), [`sandbox`](../packages/llm/llm), [`sandbox-policy`](../packages/core/session), [`session`](../packages/session/session-title), [`subprocess`](../packages/util/timeout) |
+| [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
+| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
+| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
+| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/todo/tool-todo) | `timeout` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`timeout`](../packages/core/session), [`tools`](../packages/session/session-projection) |
+| [`tool-todo`](../packages/core/tools) | `todo` | [`agent`](../packages/plan/plan-mode), [`invariants`](../packages/core/agent), [`session`](../packages/interaction/commands), [`session-projection`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
+| [`plan-mode`](../packages/core/session) | `plan` | [`agent`](../packages/session/session-projection), [`commands`](../packages/core/system-prompt), [`invariants`](../packages/core/tools), [`llm`](../packages/interaction/user-interaction), [`session`](../packages/hooks/hooks-codex), [`session-projection`](../packages/core/agent), [`system-prompt`](../packages/hooks/hook-protocol), [`tools`](../packages/support/invariants), [`user-interaction`](../packages/llm/llm) |
+| [`tool-cordis`](../packages/core/session) | `cordis` | [`invariants`](../packages/session/session-persistence), [`scope`](../packages/core/tools), [`tools`](../packages/session-query/session-query-sqlite) |
+| [`hooks-codex`](../packages/support/invariants) | `hooks` | [`agent`](../packages/core/session), [`hook-protocol`](../packages/session/session-persistence), [`invariants`](../packages/session-query/session-query), [`llm`](../packages/session-query/tool-session-query), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm), [`tools`](../packages/core/session) |
+| [`session-checkpoint-policy`](../packages/session-query/session-query) | `session-persistence` | [`agent`](../packages/core/system-prompt), [`invariants`](../packages/util/timeout), [`llm`](../packages/core/tools), [`session`](../packages/support/agent-loop-testkit), [`session-persistence`](../packages/core/agent), [`tools`](../packages/support/invariants) |
+| [`session-query-sqlite`](../packages/llm/llm) | `session-query` | [`invariants`](../packages/core/session), [`session`](../packages/core/system-prompt), [`session-persistence`](../packages/core/tools), [`session-query`](../packages/client/ui-command) |
+| [`tool-session-query`](../packages/client/connection) | `session-query` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-query`](../packages/client/ui-primitives), [`system-prompt`](../packages/client/ui-slash), [`timeout`](../packages/client/ui-slots), [`tools`](../packages/support/invariants) |
+| [`session-title-all-messages-llm`](../packages/client/ui-deliverables) | `session-title` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-title`](../packages/client/ui-slots), [`session-title-llm`](../packages/support/invariants) |
+| [`session-title-first-message-llm`](../packages/client/ui-goal) | `session-title` | [`invariants`](../packages/api/remotes), [`llm`](../packages/client/locale), [`session`](../packages/client/runtime), [`session-title`](../packages/client/ui-conversation), [`session-title-llm`](../packages/client/ui-primitives) |
+| [`agent-loop-testkit`](../packages/client/ui-slots) | `support` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/client/ui-tool), [`session`](../packages/client/locale), [`system-prompt`](../packages/client/runtime), [`tools`](../packages/client/ui-conversation) |
+| [`tool-ask-user`](../packages/client/ui-primitives) | `ui` | [`agent`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`tools`](../packages/context/session-reference), [`user-interaction`](../packages/core/agent) |
+| [`client-ui-command`](../packages/compact/compact) | `client` | [`client-connection`](../packages/support/invariants), [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/retention), [`client-ui-conversation`](../packages/core/session), [`client-ui-primitives`](../packages/session-query/session-query), [`client-ui-slash`](../packages/context/workspace-context), [`client-ui-slots`](../packages/core/agent), [`invariants`](../packages/fs/fs) |
+| [`client-ui-deliverables`](../packages/support/invariants) | `client` | [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/paths), [`client-ui-conversation`](../packages/core/session), [`client-ui-slots`](../packages/core/tools), [`invariants`](../packages/guard/repeat-tool-guard) |
+| [`client-ui-goal`](../packages/core/agent) | `client` | [`api-remotes`](../packages/support/invariants), [`client-locale`](../packages/core/tools), [`client-runtime`](../packages/guard/timeout-policy), [`client-ui-conversation`](../packages/support/invariants), [`client-ui-primitives`](../packages/llm/llm), [`client-ui-slots`](../packages/util/timeout), [`goal`](../packages/core/tools), [`invariants`](../packages/interaction/tool-ask-user) |
+| [`client-ui-tool`](../packages/core/agent) | `client` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/core/tools), [`client-ui-conversation`](../packages/interaction/user-interaction), [`client-ui-primitives`](../packages/lsp/tool-lsp), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm) |
+| [`session-reference`](../packages/lsp/lsp) | `context` | [`agent`](../packages/core/system-prompt), [`compact`](../packages/util/timeout), [`invariants`](../packages/core/tools), [`llm`](../packages/mcp/mcp-client), [`retention`](../packages/support/invariants), [`session`](../packages/llm/llm), [`session-query`](../packages/subprocess/subprocess) |
+| [`workspace-context`](../packages/core/tools) | `context` | [`agent`](../packages/pty/tool-bash-persistent), [`fs`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/pty/pty), [`paths`](../packages/util/timeout), [`session`](../packages/core/tools), [`tools`](../packages/pty/tool-pty) |
+| [`repeat-tool-guard`](../packages/core/agent) | `guard` | [`agent`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`tools`](../packages/pty/pty) |
+| [`tool-lsp`](../packages/util/retention) | `lsp` | [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks), [`lsp`](../packages/core/tools), [`system-prompt`](../packages/self-modification/tool-cordis), [`timeout`](../packages/support/invariants), [`tools`](../packages/core/scope) |
+| [`mcp-client`](../packages/core/tools) | `mcp` | [`invariants`](../packages/session/session-checkpoint-policy), [`llm`](../packages/core/agent), [`subprocess`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
+| [`tool-bash-persistent`](../packages/core/session) | `pty` | [`agent`](../packages/session/session-persistence), [`invariants`](../packages/core/tools), [`pty`](../packages/session/session-telemetry-otel), [`timeout`](../packages/util/brand), [`tools`](../packages/feedback/command-feedback) |
+| [`tool-pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/llm/llm), [`invariants`](../packages/util/paths), [`llm`](../packages/core/session), [`pty`](../packages/session/session-telemetry), [`retention`](../packages/session/session-title-all-messages-llm), [`system-prompt`](../packages/support/invariants), [`tasks`](../packages/llm/llm), [`tools`](../packages/core/session) |
+| [`tool-tasks`](../packages/session/session-title) | `tasks` | [`agent`](../packages/session/session-title-llm), [`invariants`](../packages/session/session-title-first-message-llm), [`llm`](../packages/support/invariants), [`retention`](../packages/llm/llm), [`system-prompt`](../packages/core/session), [`tasks`](../packages/session/session-title), [`tools`](../packages/session/session-title-llm) |
+| [`session-telemetry-otel`](../packages/tasks/tool-tasks) | `telemetry` | [`brand`](../packages/core/agent), [`command-feedback`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`llm`](../packages/util/retention), [`paths`](../packages/core/system-prompt), [`session`](../packages/tasks/tasks), [`session-telemetry`](../packages/core/tools) |
+| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`repository-plugin`](../packages/hooks/hooks-claude) | `cordis` | [`invariants`](../packages/core/agent), [`mcp-client`](../packages/hooks/hook-protocol), [`paths`](../packages/support/invariants), [`skill-local`](../packages/llm/llm) |
+| [`hooks-claude`](../packages/core/session) | `hooks` | [`agent`](../packages/session/session-persistence), [`hook-protocol`](../packages/subagent/subagent), [`invariants`](../packages/core/tools), [`llm`](../packages/bundle/web-app), [`session`](../packages/bash/bash-env), [`session-persistence`](../packages/support/invariants), [`subagent`](../packages/core/system-prompt), [`tools`](../packages/client/ui-model) |
+| [`web-app`](../packages/client/connection) | `bundle` | [`bash-env`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-command) |
+| [`client-ui-model`](../packages/client/ui-conversation) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-ui-command`](../packages/support/invariants), [`client-ui-conversation`](../packages/client/ui-permission), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`invariants`](../packages/client/schema-form) |
+| [`client-ui-permission`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-schema-form`](../packages/support/invariants), [`client-ui-command`](../packages/interaction/permission), [`client-ui-primitives`](../packages/client/ui-plan), [`client-ui-slash`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`permission`](../packages/client/ui-conversation) |
+| [`client-ui-plan`](../packages/client/ui-primitives) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/plan/plan-mode), [`client-ui-conversation`](../packages/client/ui-skill), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`plan-mode`](../packages/client/ui-primitives) |
+| [`client-ui-skill`](../packages/client/ui-slash) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/ui-tool), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-subagent), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-ui-tool`](../packages/client/ui-conversation), [`invariants`](../packages/client/ui-primitives) |
+| [`client-ui-subagent`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/ui-slots), [`client-runtime`](../packages/support/invariants), [`client-ui-conversation`](../packages/subagent/subagent), [`client-ui-primitives`](../packages/llm/token-meter), [`client-ui-slash`](../packages/scaffold/protocol), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`subagent`](../packages/core/session), [`token-meter`](../packages/subagent/subagent) |
+| [`sdk-protocol`](../packages/self-modification/repository-plugin) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/mcp/mcp-client), [`session`](../packages/util/paths), [`subagent`](../packages/skill/skill-local) |
+| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`jsonrpc`](../packages/examples/agent-spine-demo) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/core/agent-loop), [`llm`](../packages/bash/bash-env), [`llm-deepseek`](../packages/goal/goal), [`scope`](../packages/goal/goal-session), [`sdk-protocol`](../packages/support/invariants), [`session`](../packages/llm/llm), [`subagent`](../packages/llm/llm-retry) |
+| [`agent-spine-demo`](../packages/util/paths) | `examples` | [`agent`](../packages/core/scope), [`agent-loop`](../packages/core/session), [`bash-env`](../packages/session/session-title), [`goal`](../packages/skill/skill), [`goal-session`](../packages/skill/skill-local), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks-local), [`llm-retry`](../packages/bash/tool-bash), [`paths`](../packages/goal/tool-goal), [`scope`](../packages/skill/tool-skill), [`session`](../packages/tasks/tool-tasks), [`session-title`](../packages/core/tools), [`skill`](../packages/context/workspace-context), [`skill-local`](../packages/scaffold/server), [`system-prompt`](../packages/core/agent), [`tasks-local`](../packages/support/invariants), [`tool-bash`](../packages/llm/llm), [`tool-goal`](../packages/llm/llm-deepseek), [`tool-skill`](../packages/core/scope), [`tool-tasks`](../packages/scaffold/protocol), [`tools`](../packages/core/session), [`workspace-context`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/scaffold/client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
+| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
new file mode 100644
index 0000000000..49f2c2a45e
--- /dev/null
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
+persistence-catalog.md: 04c3a492fe837f7acc102901a289bf74f0cecf3f
+persistence-catalog.zh.md: 3f75cb55e2771b27e494aca9ea81ffeba3e69064
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
new file mode 100644
index 0000000000..3f75cb55e2
--- /dev/null
+++ b/docs/persistence-catalog.zh.md
@@ -0,0 +1,775 @@
+<!-- 英文源文件由 scripts/gen-persistence-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-persistence-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/persistence-catalog.md` 重新记录配对。 -->
+
+# 会话持久化事件目录
+
+[English](persistence-catalog.md) | 中文
+
+会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
+
+英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（`doc-typecheck` 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
+
+以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。
+
+## 事件信封
+
+```ts persistence-catalog
+/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
+export type SessionEventType = keyof SessionEventMap
+
+/**
+ * The subset of {@link SessionEventType} values whose events produce LLM
+ * messages and are eligible to appear on the ordered surface. Only these
+ * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ */
+export type SurfaceEventType =
+  | 'user/message'
+  | 'assistant/message'
+  | 'tool/result'
+
+/**
+ * How a session event entered the ordered surface. Only valid on
+ * {@link SurfaceEventType} events.
+ *
+ * - `'append'`: added to the tail — normal path for user/assistant/tool
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction and possible other manipulations.
+ */
+export type SurfaceOp =
+  | 'append'
+  | { op: 'replace'; start: number; end: number }
+
+/**
+ * One immutable entry in the session log.
+ *
+ * A proper discriminated union over `type` (not independent `type`/`data`
+ * unions), so `switch (event.type)` narrows `event.data` without casts.
+ *
+ * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
+ * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * `assistant/message`, `tool/result`).
+ * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * surface metadata — the compiler enforces this at `Session.append()`
+ * call sites.
+ */
+export type SessionEvent<T extends SessionEventType = SessionEventType> = {
+  [K in SessionEventType]: {
+    type: K
+    /** Monotonic sequence number within the session. */
+    seq: number
+    /** Unix epoch milliseconds. */
+    time: number
+    data: SessionEventMap[K]
+  } & (K extends SurfaceEventType ? {
+    /**
+     * Seq numbers of events that are provenance sources of this event
+     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
+     * or the surface nodes shadowed by a compaction replace node). An
+     * `assistant/message` may carry a present empty array for a known empty
+     * provider stream; omission means unrecorded provenance.
+     */
+    sourceEventSeqs?: number[]
+    /** How this event entered the surface; absent for non-surface events. */
+    surfaceOp?: SurfaceOp
+  } : object)
+}[T]
+```
+
+来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts)
+
+## 事件
+
+### `agent/*`
+
+#### `agent/inbox/spliced` — log-only
+
+```ts persistence-catalog
+/**
+ * One normalized mutation of an agent's durable pending-message lists.
+ * Live dispatch precedes projection mutation, so synchronous observers may
+ * read the pre-splice inbox to recover the removed messages.
+ */
+'agent/inbox/spliced': {
+  target: InboxTarget
+  start: number
+  removedCount?: number
+  inserted: UserMessage[]
+  outcome?: 'canceled'
+}
+```
+
+来源：[`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
+
+### `approval/*`
+
+#### `approval/asked` — log-only
+
+```ts persistence-catalog
+/**
+ * An approval question was put to the answerer chain — log-only audit
+ * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs
+ * it with the `approval/decided` that always follows; `toolName` is the
+ * tool the question is about, `callId` the exact tool call when the asker
+ * had one, `reason` the asker's human-readable explanation (e.g. a hook's
+ * permission-decision reason).
+ */
+'approval/asked': {
+  id: ApprovalRequestId
+  toolName: string
+  callId?: CallId
+  reason?: string
+}
+```
+
+类型：[CallId](subsystems/core.md)
+
+来源：[`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
+
+#### `approval/decided` — log-only
+
+```ts persistence-catalog
+/**
+ * The outcome of a prior `approval/asked` (same `id`) — log-only audit.
+ * Exactly one per ask, appended when the outcome is known: a decision, a
+ * cancellation, or the fail-closed `'unavailable'`.
+ */
+'approval/decided': {
+  id: ApprovalRequestId
+  outcome: ApprovalOutcome
+}
+```
+
+来源：[`packages/interaction/user-approval/src/index.ts:55`](../packages/interaction/user-approval/src/index.ts)
+
+#### `approval/policy` — log-only
+
+```ts persistence-catalog
+/**
+ * The session's approval policy was switched — log-only, durable,
+ * replayable, never in the model transcript (the model learns the policy
+ * from the runtime-context snapshot and live switch notices). The LAST
+ * such event is the session's override ({@link effectiveApprovalPolicy}).
+ * `source: 'delegation'` marks an override seeded into a child; an absent
+ * source is a runtime switch.
+ */
+'approval/policy': {
+  policy: ApprovalPolicy
+  /** Marks an override seeded into a child at delegation. */
+  source?: 'delegation'
+}
+```
+
+来源：[`packages/interaction/user-approval/src/index.ts:67`](../packages/interaction/user-approval/src/index.ts)
+
+### `assistant/*`
+
+#### `assistant/chunk` — log-only
+
+```ts persistence-catalog
+/** Raw stream chunk — token-level replay fidelity. */
+'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
+```
+
+类型：[StreamChunk](subsystems/llm-streaming.md)
+
+来源：[`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts)
+
+#### `assistant/message` — surface
+
+```ts persistence-catalog
+/**
+ * Assembled assistant message for one step (derived history uses this).
+ * Carries the step's `usage` when the adapter reported token accounting, so
+ * the model output and its accounting travel together (there is no separate
+ * usage record). `usage` is absent when the adapter reported none.
+ */
+'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage }
+```
+
+类型：[TokenUsage](subsystems/llm-streaming.md)
+
+来源：[`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts)
+
+### `command/*`
+
+#### `command/done` — log-only
+
+```ts persistence-catalog
+/**
+ * The paired command settled. `kind`/`text` carry the handler's verbatim
+ * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
+ * rendered failure). A successful command may identify the earlier
+ * authoritative domain event for a richer client-computed presentation.
+ */
+'command/done': {
+  commandId: CommandId
+  kind: 'success' | 'error'
+  text?: string
+  sourceEventSeq?: number
+}
+```
+
+来源：[`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
+
+#### `command/run` — log-only
+
+```ts persistence-catalog
+/**
+ * A resolved slash command entered its handler. Log-only (never model
+ * surface); paired with `command/done` by `commandId`, mirroring the
+ * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
+ * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
+ * separator whitespace included), so a consumer (a projection unit
+ * folding its own command records, a rich command card) never re-parses
+ * a line. `args` is absent when the definition sets `recordInput: false`
+ * because an authoritative domain event owns the input payload.
+ */
+'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
+```
+
+来源：[`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
+
+### `compact/*`
+
+#### `compact/end` — log-only
+
+```ts persistence-catalog
+/**
+ * Marks the end of a compaction — log-only, releases the lock. Its owner
+ * matches `compact/start`; `error` records an unsuccessful attempt.
+ */
+'compact/end': { turn: number | null; error?: string }
+```
+
+来源：[`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
+
+#### `compact/prune` — log-only
+
+```ts persistence-catalog
+/**
+ * Shadow price of one model-free prune replacement — log-only, no
+ * surfaceOp. The shared shadow-price protocol: a surface `replace` event
+ * is priced by the metering event immediately before it (`compact/summary`
+ * for a summarizing compaction, this event for a prune), which states the
+ * heuristic token price of the exact replaced range so a pure consumer
+ * can subtract it without retaining per-node prices. The replacement MUST
+ * be appended synchronously right after this event.
+ */
+'compact/prune': {
+  /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
+  shadowedRange: { start: number; end: number }
+  /** The seqs of all shadowed surface nodes, in surface order. */
+  shadowedSeqs: number[]
+  /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
+  shadowedTokenCount: number
+}
+```
+
+来源：[`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
+
+#### `compact/start` — log-only
+
+```ts persistence-catalog
+/**
+ * Marks the start of a compaction — log-only, holds the lock until
+ * `compact/end`. A numbered owner is strictly enclosed by that open turn;
+ * `null` identifies a standalone manual transaction between turns.
+ */
+'compact/start': { turn: number | null }
+```
+
+来源：[`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts)
+
+#### `compact/summary` — log-only
+
+```ts persistence-catalog
+/**
+ * Provenance record of a completed summarization — log-only, no surfaceOp.
+ * The summary content is in `data.summary`; the actual surface replacement
+ * is performed by the immediately following `user/message` event that
+ * shadows the compacted range. That adjacency is contractual — the
+ * shadowed pricing fields are the replacement's shadow price, so a
+ * consumer may pair a replacement with the metering event directly
+ * before it (`compact/prune` documents the shared protocol).
+ */
+'compact/summary': {
+  summary: ContentBlock[]
+  shadowedRange: { start: number; end: number }
+  shadowedSeqs: number[]
+  shadowedTokenCount: number
+  /** The provider route that wrote the summary. */
+  provider: string
+  /**
+   * The model that wrote the summary — the summarize call's envelope,
+   * reported by the backend that made the call, logged so the one-shot
+   * request is reconstructable from log + code and "which model wrote
+   * this summary" has a durable answer (the reconstructability Agent Note).
+   */
+  model: string
+  /** The generation cap the summarize call sent, when one applied. */
+  maxTokens?: number
+  /** Provider-reported token usage for the summarization request, when emitted. */
+  usage?: TokenUsage
+} & (
+  | {
+    /** Complete provider output before the backend's safe summary projection. */
+    rawOutput: ContentBlock[]
+    /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+    llmStreamCall: true
+  }
+  | {
+    /** Optional complete output from an unmarked template, remote, or other summarizer. */
+    rawOutput?: ContentBlock[]
+    /** An unmarked summary does not identify a call through this context's LLM seam. */
+    llmStreamCall?: never
+  }
+)
+```
+
+类型：[ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
+
+来源：[`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
+
+### `feedback/*`
+
+#### `feedback/record` — log-only
+
+```ts persistence-catalog
+/**
+ * One recorded human remark about this session. Log-only and independent
+ * of its trigger; it never enters the model surface or derived history.
+ */
+'feedback/record': { text: string }
+```
+
+来源：[`packages/feedback/command-feedback/src/index.ts:24`](../packages/feedback/command-feedback/src/index.ts)
+
+### `goal/*`
+
+#### `goal/change` — log-only
+
+```ts persistence-catalog
+/**
+ * Complete post-mutation goal state or clear tombstone.
+ */
+'goal/change': GoalChangeMeta
+```
+
+来源：[`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain.ts)
+
+### `hook/*`
+
+#### `hook/invoked` — log-only
+
+```ts persistence-catalog
+/**
+ * A hook command was invoked at a hook point — log-only provenance (like
+ * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
+ * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
+ * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
+ * pattern that selected it (absent for match-all), `handlerId` a stable id
+ * for the command (so an invoked/result pair correlates). `turn` is the open
+ * turn the invocation lives inside.
+ */
+'hook/invoked': {
+  turn: number
+  point: string
+  dialect: HookDialect
+  matcher?: string
+  handlerId: string
+}
+```
+
+来源：[`packages/hooks/hook-protocol/src/types.ts:19`](../packages/hooks/hook-protocol/src/types.ts)
+
+#### `hook/result` — log-only
+
+```ts persistence-catalog
+/**
+ * Log-only outcome paired to `hook/invoked` by `handlerId`. Decision is the
+ * parsed permission result, `stop` for `continue:false`, or `pass`; exit code
+ * may be absent, stderr is bounded, and duration is wall-clock runtime.
+ */
+'hook/result': {
+  turn: number
+  point: string
+  handlerId: string
+  decision: string
+  exitCode?: number
+  stderrSummary?: string
+  durationMs: number
+}
+```
+
+来源：[`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-protocol/src/types.ts)
+
+### `llm/*`
+
+#### `llm/retry` — log-only
+
+```ts persistence-catalog
+/** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
+'llm/retry': {
+  turn: number
+  step: number
+  provider: string
+  mode: 'normal'
+  policyKey: string
+  retry: number
+  maxRetries: number
+  delayMs: number
+  failure: LlmFailure
+} | {
+  turn: number
+  step: number
+  provider: string
+  mode: 'always'
+  policyKey: string
+  retry: number
+  delayMs: number
+  failure: LlmFailure
+}
+```
+
+来源：[`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts)
+
+### `permission/*`
+
+#### `permission/preset` — log-only
+
+```ts persistence-catalog
+/**
+ * Records the selected preset as durable, log-only user intent. The knob
+ * events follow in the same turn and control execution; this event stays
+ * out of the model transcript and lets {@link effectivePermissionPreset}
+ * preserve a selection when bundles match.
+ */
+'permission/preset': { preset: string }
+```
+
+来源：[`packages/interaction/permission/src/index.ts:50`](../packages/interaction/permission/src/index.ts)
+
+### `plan/*`
+
+#### `plan/mode` — log-only
+
+```ts persistence-catalog
+/**
+ * Whether plan mode is in force from this point on: log-only, non-surface,
+ * whole-value replace. The last `plan/mode` wins; a log with none folds to
+ * inactive through {@link foldPlanMode}.
+ */
+'plan/mode': { active: boolean }
+```
+
+来源：[`packages/plan/plan-mode/src/index.ts:52`](../packages/plan/plan-mode/src/index.ts)
+
+### `request/*`
+
+#### `request/context` — log-only
+
+```ts persistence-catalog
+/**
+ * Route metadata for the next request, logged only when the route or capacity
+ * changes. It does not participate in request reconstruction or header equality.
+ */
+'request/context': RequestContext
+```
+
+来源：[`packages/core/session/src/types.ts:281`](../packages/core/session/src/types.ts)
+
+#### `request/header` — log-only
+
+```ts persistence-catalog
+/**
+ * Full header for the next request, appended inside its step before dispatch.
+ * It is log-only; the latest snapshot reconstructs the request header.
+ */
+'request/header': { header: EpochHeader; reason: RequestHeaderReason }
+```
+
+来源：[`packages/core/session/src/types.ts:276`](../packages/core/session/src/types.ts)
+
+### `sandbox/*`
+
+#### `sandbox/mode` — log-only
+
+```ts persistence-catalog
+/**
+ * The session's sandbox mode was switched — log-only (like `approval/*`;
+ * NOT a surface event, carries no `surfaceOp`): durable and replayable,
+ * never in the model transcript. The LAST such event is the session's
+ * override ({@link effectiveSandboxMode}). `source: 'delegation'` marks
+ * an override seeded into a child; an absent source is a runtime switch.
+ */
+'sandbox/mode': {
+  mode: SandboxMode
+  /** Marks an override seeded into a child at delegation. */
+  source?: 'delegation'
+}
+```
+
+来源：[`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
+
+### `session/*`
+
+#### `session/end-seed` — log-only
+
+```ts persistence-catalog
+/**
+ * Marks the end of a constructor seed. Events before it have smaller seq
+ * values and came from the seed (resume, fork, or replay); this lifecycle
+ * produced none of them. This log-only event is the durable projection of
+ * {@link Session.firstLiveSeq}. Its payload is empty — position and `time`
+ * carry the meaning.
+ *
+ * Locate the LAST one in stored history. A seed already ending in one is not
+ * re-marked, so reopening an untouched session does not grow its log per
+ * pickup and the event need not be at the current `firstLiveSeq`.
+ *
+ * `Session`'s constructor is the only legitimate writer. The invariant
+ * companion deliberately constrains nothing here, so a plugin appending one
+ * would silently classify every live bracket before it as seed history.
+ *
+ * An owner of a standalone open/close bracket (`compact/start` …
+ * `compact/end`) reads it because seed history and live work are otherwise
+ * byte-identical: an unmatched opening marker before this event belongs to
+ * an ended lifecycle, whatever ended it. NOT a liveness signal about other
+ * writers — a concurrently live session holds its own boundary elsewhere,
+ * so tolerating concurrent writers needs a signal beyond the log.
+ */
+'session/end-seed': Record<string, never>
+```
+
+来源：[`packages/core/session/src/types.ts:304`](../packages/core/session/src/types.ts)
+
+#### `session/title` — log-only
+
+```ts persistence-catalog
+/**
+ * Latest-wins session title snapshot. Log-only: it never enters the model
+ * surface or derived history.
+ */
+'session/title': SessionTitleEventData
+```
+
+类型：[SessionTitleEventData](subsystems/session-title.md)
+
+来源：[`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
+
+#### `session/title-llm-request` — log-only
+
+```ts persistence-catalog
+/** Log-only pre-dispatch record of one session-title model request. */
+'session/title-llm-request': SessionTitleLlmRequestEventData
+```
+
+类型：[SessionTitleLlmRequestEventData](subsystems/session-title.md)
+
+来源：[`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
+
+### `step/*`
+
+#### `step/end` — log-only
+
+```ts persistence-catalog
+/** Closes step `step` of turn `turn`. */
+'step/end': { turn: number; step: number }
+```
+
+来源：[`packages/core/session/src/types.ts:228`](../packages/core/session/src/types.ts)
+
+#### `step/start` — log-only
+
+```ts persistence-catalog
+/** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */
+'step/start': { turn: number; step: number }
+```
+
+来源：[`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts)
+
+### `subagent/*`
+
+#### `subagent/descriptor` — log-only
+
+```ts persistence-catalog
+/**
+ * Durable identity and lifecycle mode of a session-backed subagent child,
+ * appended once by the establishing provider inside the child's initial
+ * turn, before its first request. Continuable records also carry their
+ * resumable composition. Log-only: it carries no `surfaceOp`, never enters
+ * model history, and survives compaction.
+ */
+'subagent/descriptor': SubagentDescriptorData
+```
+
+来源：[`packages/subagent/subagent/src/descriptor.ts:37`](../packages/subagent/subagent/src/descriptor.ts)
+
+### `todo/*`
+
+#### `todo/write` — log-only
+
+```ts persistence-catalog
+/** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
+'todo/write': { todos: TodoItem[] }
+```
+
+类型：[TodoItem](subsystems/session.md)
+
+来源：[`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts)
+
+### `tool/*`
+
+#### `tool/call` — log-only
+
+```ts persistence-catalog
+/**
+ * The model requested one tool invocation: `name` with the raw `arguments`
+ * JSON string exactly as the model produced it (unparsed). `callId` pairs the
+ * call with its `tool/result`.
+ */
+'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
+```
+
+类型：[CallId](subsystems/core.md)
+
+来源：[`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts)
+
+#### `tool/code-dispatch` — log-only
+
+```ts persistence-catalog
+/**
+ * One bridged sub-dispatch SETTLING: the pairing ids (matching the
+ * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
+ * with the same JSON-normalized `arguments`, and the sub-call's complete
+ * model-facing outcome in `tool/result`'s own vocabulary
+ * (`content` + `isError`), so UIs render a sub-call through the exact
+ * code path that renders a native call. Every started sub-call settles
+ * with exactly one of these (abort included: the aborted pipeline result
+ * is an `isError` outcome).
+ * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+ * model context; persistence and UIs get every call. Appended inside the
+ * parent `run_code`'s execution (the bridge drains in-flight dispatches
+ * before returning), so its execution-enclosure relation holds by
+ * construction.
+ */
+'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+```
+
+类型：[CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
+
+来源：[`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
+
+#### `tool/code-dispatch-start` — log-only
+
+```ts persistence-catalog
+/**
+ * One sub-dispatch STARTING inside a `run_code` program: the parent
+ * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
+ * numbered in submission order), and the tool `name` with its
+ * JSON-normalized `arguments` — the exact value dispatched, normalized
+ * BEFORE dispatch, so this append can never fail on payload shape.
+ * Appended when the scheduler actually starts the call (not at
+ * submission), so a start means the tool body pipeline was entered; a
+ * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
+ * ignores it; UIs use it for live per-sub-call running state and pair it
+ * with `tool/code-dispatch` by `subCallId` (timing = the two events'
+ * `time` fields).
+ */
+'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+```
+
+类型：[CallId](subsystems/core.md)
+
+来源：[`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
+
+#### `tool/result` — surface
+
+```ts persistence-catalog
+/**
+ * A completed tool call's model-facing result, optional internal failure
+ * identity, and optional tool-private `meta` presentation payload. `meta` is
+ * opaque to the core (the producing tool owns its shape and reads it back in
+ * `presentResult`) but MUST be JSON-serializable: `Session.append`
+ * runtime-validates all event data with `isJsonValue`, so a non-serializable
+ * `meta` is rejected at the source, and the durable log reproduces the
+ * identical card on replay. Absent
+ * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time
+ * contextual diff here).
+ */
+'tool/result': {
+  turn: number
+  step: number
+  message: ToolResultMessage
+  error?: { name: string; code: string }
+  meta?: JsonValue
+}
+```
+
+来源：[`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
+
+### `turn/*`
+
+#### `turn/end` — log-only
+
+```ts persistence-catalog
+/**
+ * Closes turn `turn` with the {@link TurnEndReason} that ended it. A turn
+ * with no entered step has no `step/start` or `step/end`. The loop does not await a
+ * flush at turn boundaries: `dsh-session-checkpoint-policy` owns the
+ * per-request durability checkpoint, and consumers that read storage after
+ * `whenIdle()` flush themselves. Success commits the turn; rejection is
+ * reported live and does not prevent later work.
+ */
+'turn/end': { turn: number; reason: TurnEndReason }
+```
+
+类型：[TurnEndReason](subsystems/session.md)
+
+来源：[`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts)
+
+#### `turn/start` — log-only
+
+```ts persistence-catalog
+/**
+ * Opens turn `turn` before the loop claims queued input or runs pre-step.
+ * Rejection, empty input, cancellation, or failure may close it with no
+ * step; otherwise the following identified `user/message` event or batch
+ * records the messages entering the step.
+ */
+'turn/start': { turn: number }
+```
+
+来源：[`packages/core/session/src/types.ts:215`](../packages/core/session/src/types.ts)
+
+### `user/*`
+
+#### `user/message` — surface
+
+```ts persistence-catalog
+/**
+ * A user-role message on the model-visible surface: a direct human prompt
+ * (the queued message claimed for this turn), a synthetic `agent.inject()`
+ * context (file-change notices, subdir AGENTS.md, skill content, cron
+ * notifications, …), or an entered goal continuation round. All three
+ * project their `content` verbatim; `source` tells them apart.
+ */
+'user/message': UserMessage
+```
+
+来源：[`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
+
+### `web/*`
+
+#### `web/deepseek-search-llm-request` — log-only
+
+```ts persistence-catalog
+/** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
+'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest
+```
+
+来源：[`packages/web/web-search-deepseek/src/provider.ts:83`](../packages/web/web-search-deepseek/src/provider.ts)
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
index a32bb0e3e6..ed77fc2f2e 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0003-web-agent-gui-feedback-loop.md
 0003-web-agent-gui-feedback-loop.md: 13d13a607babfe7f5ddfdb6773c94f973bbef0db
-0003-web-agent-gui-feedback-loop.zh.md: f80530605ef9274638c6848bf5a256f76057915c
+0003-web-agent-gui-feedback-loop.zh.md: 44d4febc30344135932aad2394b3054587feca1d
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
index f80530605e..44d4febc30 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
@@ -18,20 +18,20 @@ Web agent 修改了 GUI 源码，却不知道由哪个 URL 和进程承载当前
 
 ## 影响
 
-用户不得不连续指出三个错误：agent 把验收交还给用户；建议预览的页面一片空白；报告成功的 URL 并不是用户正在使用的页面。一个不受管理的替代服务器还持续运行到下一轮，直到用户提出质疑。
+用户不得不连续指出三个错误：agent 把验收交还给用户；建议预览的页面一片空白；报告成功的 URL 并不是用户正在使用的页面。一个不受管理的替代服务器还持续运行到下一个轮次，直到用户提出质疑。
 
 本次调查没有重启或修改只读的 3081 和 3082 试验服务。
 
 ## 时间线
 
-- 在第 2 轮中，agent 修改主题后，在序列 30939 的消息中让用户运行 `pnpm run demo:tui` 或打开一个未明确指定的 Web 应用。它没有对组装后的 Web 应用执行任何验收。
-- 在第 3 轮中，agent 读取 `apps/web/package.json`，在序列 31865 于端口 5173 上启动裸 Vite，观察到 HTTP 200 后便宣布成功。浏览器却抛出 `client-modules: window.__DSH_BOOT__ is missing or not an object`，并显示白屏。
-- 在第 4 轮中，agent 找到了完整的 `dsh web` 启动路径，重新构建 shell，在序列 34309 于端口 3334 上启动一个不受管理的进程，并且只在序列 34441 检查了这个替代服务是否返回 200 和启动 manifest。它从未探测端口 3081。
-- 在第 5 轮中，用户在序列 34556 报告 3081 已经显示新主题。直到序列 34681，agent 才检查既有进程并移除冗余服务器。
+- 在第 2 个轮次中，agent 修改主题后，在序列 30939 的消息中让用户运行 `pnpm run demo:tui` 或打开一个未明确指定的 Web 应用。它没有对组装后的 Web 应用执行任何验收。
+- 在第 3 个轮次中，agent 读取 `apps/web/package.json`，在序列 31865 于端口 5173 上启动裸 Vite，观察到 HTTP 200 后便宣布成功。浏览器却抛出 `client-modules: window.__DSH_BOOT__ is missing or not an object`，并显示白屏。
+- 在第 4 个轮次中，agent 找到了完整的 `dsh web` 启动路径，重新构建 shell，在序列 34309 于端口 3334 上启动一个不受管理的进程，并且只在序列 34441 检查了这个替代服务是否返回 200 和启动 manifest。它从未探测端口 3081。
+- 在第 5 个轮次中，用户在序列 34556 报告 3081 已经显示新主题。直到序列 34681，agent 才检查既有进程并移除冗余服务器。
 
 ## 根因
 
-Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久契约将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
+Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久约定将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
 
 裸 Vite 返回 HTTP 200，使错误的启动路径看似合理。`window.__DSH_BOOT__` 只由完整宿主注入，因此传输层就绪不代表应用已就绪。首个回归测试以另一种方式重复了同样的错误：超时机制终止 Vite 后，非零退出断言仍会通过。真实复现暴露了这一误报。
 
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
index b54453f3c4..8c66e9464c 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
 0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198
-0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231
+0004-landlock-partial-notice-misclassified-child-failures.zh.md: 55b462a4fe90b5d5c98bf846cad55e1fe4d6a4b0
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
index 5cf3e4422a..55b462a4fe 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
@@ -10,7 +10,7 @@ Status: resolved
 
 ## 概述
 
-原生 launcher 契约区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
+原生 launcher 约定区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
 
 harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情况。消费方只要发现非零退出同时携带该子串，就会归类为 runner 失败。因此，子进程的退出状态被错误地关联到 launcher 的信息性行：`false`、ripgrep 无匹配时的退出码 1、无效 pattern 的退出码 2，乃至由子进程自行选择的退出码 125，都可能在约束与执行均成功的情况下被错误归因为沙箱故障。
 
@@ -24,8 +24,8 @@ harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情
 
 ## 时间线
 
-- 原生 launcher 契约规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
-- 沙箱提供方把该契约简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
+- 原生 launcher 约定规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
+- 沙箱提供方把该约定简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
 - 单元测试覆盖了无诊断的成功、拒绝诊断和致命 runner 前缀。真实 runner 测试在没有可用内核时会自行跳过，也没有强制构造「部分强制执行通知后跟非零子进程退出」的情况。
 - 一个最小 POSIX 包装脚本会打印该通知并 `exec` 其负载；它通过 `false` 与 ripgrep 无匹配场景复现了故障。
 - 结构化规则、前台与后台共享的分类逻辑和组装后的回放覆盖共同弥补了仍然存在的沙箱归因缺口。文件系统搜索通过 `ctx.subprocess` 运行打包的 ripgrep；本修复让该路径继续位于沙箱化 bash 之外。
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index caf9356ee9..e1ab1ef65b 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 6878300dc2cbd82d220e17d2d6f5e1009f41c48f
+core.zh.md: 60d363f9421b846ccc8096ef38861a8fdea255c0
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 6878300dc2..60d363f942 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,7 +2,7 @@
 
 [English](core.md) | 中文
 
-**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截契约——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截约定——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
 
 ## 主干逐包速览
 
@@ -14,7 +14,7 @@
 | `system-prompt/` | 提示词段落与工具 schema 组装（`ctx.systemPrompt`） | [system-prompt.md](system-prompt.md) |
 | `tools/` | 带作用域的工具注册表与受保护的执行流水线（`ctx.tools`） | [tools.md](tools.md) |
 | `agent/` | `Agent` 接口、实时注册表、发起者作用域与 `agent/*` 事件词汇（`ctx.agents`） | 本页 |
-| `agent-loop/` | 实现公开 `Agent` 契约的具体 driver（`ctx.agentLoop`） | 本页 |
+| `agent-loop/` | 实现公开 `Agent` 约定的具体 driver（`ctx.agentLoop`） | 本页 |
 | `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
 `scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
@@ -50,7 +50,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
 
-`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚契约见下方[生成区块](#ctxagents--agentregistry)。
+`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
 <a id="the-agent-handle"></a>
 
@@ -206,7 +206,7 @@ type AgentCancelCause =
 
 cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
-[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
+[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
 <a id="initiating-agent"></a>
 
@@ -255,7 +255,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## `ToolDefinition`
 
-唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的约定。
 
 其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
 
@@ -265,7 +265,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ### `…Map → derived-union` 模式
 
-harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包（package）。
+harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包。
 
 ```ts ignore-check
 // The pattern, schematically:
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 7028d71f8d..7e9e057c75 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
 credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
-credentials.zh.md: 6f5ccd1572885434257d39eb0f659fcc7371ad1d
+credentials.zh.md: f236b0b2daef85784308f10dbcfc67db84c42234
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 6f5ccd1572..f236b0b2da 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -2,9 +2,9 @@
 
 [English](credentials.md) | 中文
 
-[dsh-credentials](../../packages/credentials/credentials) 的凭据 seam 把机密挡在配置之外：settings 分节与 `cordis.yml` 条目携带的是*引用*（环境变量名），值归 [dsh-credentials-local](../../packages/credentials/credentials-local) 这类 provider 所有，消费方每个操作解析一次引用——LLM 适配器每次模型请求解析一次，因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。一条 seam 级规则约束每个 provider：空的存储值在任何地方都视为不存在。
+[dsh-credentials](../../packages/credentials/credentials) 的凭据 seam 把机密挡在配置之外：settings 分节与 `cordis.yml` 条目携带的是*引用*（环境变量名），值归 [dsh-credentials-local](../../packages/credentials/credentials-local) 这类提供方所有，消费方每个操作解析一次引用——LLM（大语言模型）适配器每次模型请求解析一次，因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。一条 seam 级规则约束每个提供方：空的存储值在任何地方都视为不存在。
 
-Source: [`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
+来源：[`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
 
 ## 标识
 
@@ -17,7 +17,7 @@ type CredentialRef = Branded<'CredentialRef'>
 
 ## 解析
 
-`resolve(ref)` 返回值，连同供出该值、由 provider 定义的来源层；未配置期间返回 `undefined`。消费方在每个操作中重新解析，绝不跨操作缓存——这次按操作进行的读取正是热更新机制。
+`resolve(ref)` 返回值，连同提供该值、由提供方定义的来源层；未配置期间返回 `undefined`。消费方在每个操作中重新解析，绝不跨操作缓存——这种按操作进行的读取正是热更新机制。
 
 ```ts type-equiv
 /** One resolved credential value and the source layer that supplied it. */
@@ -31,7 +31,7 @@ interface ResolvedCredential {
 
 ## 描述
 
-`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地 provider 把由活跃进程环境供值的引用报告为 `writable: false`——那样的写入会表面成功而解析持续返回遮蔽值，因此 seam 直接拒绝，界面也得以提前把该引用渲染为只读。
+`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地提供方把由当前进程环境供值的引用报告为 `writable: false`——那样的写入会表面成功而解析持续返回遮蔽值，因此 seam 直接拒绝，界面也得以提前把该引用渲染为只读。
 
 ```ts type-equiv
 /** Source and writability facts for one reference, safe for configuration UIs — never the value. */
@@ -47,7 +47,7 @@ interface CredentialInfo {
 
 ## 变更提交
 
-`credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
index 25b54df775..eb3a5e36ba 100644
--- a/docs/subsystems/lsp.i18n.yaml
+++ b/docs/subsystems/lsp.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/lsp.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/lsp.md
 lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
 lsp.zh.md: d428f2b5f9568b231b0b50a13bd4a41f7ea81346
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 295e5392ca..ae2ef3a216 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
 persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
-persistence.zh.md: 6676bf26e6eb0fb8f7dd9a94d17d4d70d1d1b271
+persistence.zh.md: 8785ca9c7dad562e6b27261920ab48c72c607121
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 6676bf26e6..8785ca9c7d 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
@@ -16,7 +16,7 @@
 
 修复仅适用于冷会话。对于活跃 id，`SessionPersistence.load(id)` 会等待权威内存快照完成持久化，并且只在日志平衡时返回；若活跃轮次仍未闭合，则拒绝操作，而不是添加合成的中断边界。HMR 会接管活跃前缀，而不会关闭其中正在进行的轮次。
 
-`SessionPersistence.inspect(id)` 会构造一个不可变的逻辑 Session，但不发布它，也不写入恢复内容。冷检查会在内存中配平中断的 turn，同时保持撕裂的物理尾部不变；检查已经实时存在的 Session 则借用其当前不可变快照，因此可能包含打开的 turn。使用协调器的实现会在有界 LRU 中保留这个精确的冷未发布 Session，因此重复历史读取与后续 `prepare(id)` 可复用同一次读取、解压、验证、冻结及 Session 构造。`prepare(id)` 会预留该 Session、提交待处理修复并返回可 dispose 的发布句柄；`load(id)` 使用相同机制提交修复，但不会发布 Session。该生命周期由 [Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md)定义。
+`SessionPersistence.inspect(id)` 会构造一个不可变的逻辑 Session，但不发布它，也不写入恢复内容。冷检查会在内存中配平中断的轮次，同时保持撕裂的物理尾部不变；检查已经实时存在的 Session 则借用其当前不可变快照，因此可能包含打开的 turn。使用协调器的实现会在有界 LRU 中保留这个精确的冷未发布 Session，因此重复历史读取与后续 `prepare(id)` 可复用同一次读取、解压、验证、冻结及 Session 构造。`prepare(id)` 会预留该 Session、提交待处理修复并返回可 dispose 的发布句柄；`load(id)` 使用相同机制提交修复，但不会发布 Session。该生命周期由 [Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md)定义。
 
 ## `SessionLocation`——可选的逐会话产物目标
 
diff --git a/docs/subsystems/scope.i18n.yaml b/docs/subsystems/scope.i18n.yaml
index aef528553d..db073233b5 100644
--- a/docs/subsystems/scope.i18n.yaml
+++ b/docs/subsystems/scope.i18n.yaml
@@ -1,6 +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 docs/core-data-structures/scope.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/scope.md
 scope.md: 73a697f2843293daffff85dabf4656346f7dcd04
 scope.zh.md: 06e2528eca958102110caa3a7d370e0778c0f7b2
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index 5c40419366..a257e0e33e 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/settings.md
 settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
-settings.zh.md: f6d662ebaf35eeb9d046353ea1087b0eb86e7068
+settings.zh.md: 720eb9c2718c1fa14a148cced806c224634dba69
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index f6d662ebaf..720eb9c271 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -2,13 +2,13 @@
 
 [English](settings.md) | 中文
 
-[dsh-settings](../../packages/settings/settings) 的用户设置 seam 持有一份按 namespace 分节的用户文档，并把每个已注册 namespace 解析为：schema 默认值，然后注册方的组合 `base`，最后用户分节。[dsh-settings-local](../../packages/settings/settings-local) 这类 provider 存储原始文档并推送外部编辑；消费插件注册 schema 后读取或观察解析值。组合配置仍留在 `cordis.yml`——namespace 只承载用户可编辑子集。
+[dsh-settings](../../packages/settings/settings) 的用户设置 seam 持有一份按 namespace 分节的用户文档，并把每个已注册 namespace 解析为：schema 默认值，然后注册方的组合 `base`，最后用户分节。[dsh-settings-local](../../packages/settings/settings-local) 这类提供方存储原始文档并推送外部编辑；消费方插件注册 schema 后读取或观察解析值。组合配置仍留在 `cordis.yml`——namespace 只承载用户可编辑子集。
 
-Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
+来源：[`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
 
 ## 标识
 
-namespace 命名用户文档中一个插件所有的分节。brand 使其不与其他跨边界 id 混用；构造时校验小写 kebab-case 形态。
+namespace 命名用户文档中一个归插件所有的分节。brand 使其不与其他跨边界 id 混用；构造时校验小写 kebab-case 形态。
 
 ```ts type-equiv
 /** Nominal id of one registered settings namespace. */
@@ -17,7 +17,7 @@ type SettingsNamespace = Branded<'SettingsNamespace'>
 
 ## 注册
 
-注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose 该 fiber 即移除 namespace 及其观察者。options 携带组合层、owner 的生效时机，以及一个可选的、用于校验 schema 表达不了的约束的钩子。
+注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose（资源释放）该 fiber 即移除 namespace 及其观察者。options 携带组合层、owner 的生效时机，以及一个可选的、用于校验 schema 表达不了的约束的钩子。
 
 ```ts type-equiv
 /** Registration options beyond the namespace schema. */
@@ -49,7 +49,7 @@ interface SettingsRegisterOptions<T> {
 }
 ```
 
-`validate` 在 schema 接纳该值之后运行，因此它看到的默认值与组合 base 与 owner 将看到的完全一致。`dsh-llm-pi-ai` 用它在写入处拒绝自己无法服务的提供方 profile，而不是先存下来、再让该 namespace 下每条路由失效。
+`validate` 在 schema 接纳该值之后运行，因此它看到的默认值和组合 base 与 owner 实际看到的完全一致。`dsh-llm-pi-ai` 用它在写入处拒绝自己无法服务的提供方 profile，而不是先存下来、再让该 namespace 下每条路由失效。
 
 `applies` 是 UI 提示而非机制：`restart` 的 owner 只是从不 watch，其值在构造期读取一次，配置界面可为待生效变更加标。
 
@@ -95,7 +95,7 @@ interface SettingsScope<T> {
 
 ## 描述符
 
-`describe()` 为配置界面序列化每个已注册 namespace：schemastery 的 `toJSON()` 信封驱动 schema 渲染的表单，解析值填充表单，分离出的 `base`/`user` 层让表单按字段是否出现在 user 层标注「用户已覆盖」。`describe({ redactSecrets: true })`——每个 wire 面都必须传入——从三层剥离 `role('secret')` 字段并枚举其 `{path, set}` 槽位，页面因此能渲染只写输入框而永远收不到机密值。
+`describe()` 为配置界面序列化每个已注册 namespace：schemastery 的 `toJSON()` 封装结构驱动 schema 渲染的表单，解析值填充表单，分离出的 `base`/`user` 层让表单按字段是否出现在 user 层标注「用户已覆盖」。`describe({ redactSecrets: true })`——每个对外传输接口都必须传入——从三层剥离 `role('secret')` 字段并枚举其 `{path, set}` slot，页面因此能渲染只写输入框而永远收不到机密值。
 
 ```ts type-equiv
 /** One registered namespace as surfaced to configuration UIs. */
@@ -154,7 +154,7 @@ interface SettingsDescribeOptions {
 
 ## 变更提交
 
-每次提交的变更——进程内写入或 provider 观察到的外部编辑——在新值成为权威值之后发出 `settings/updated (ns, next, prev, source)`，解析值深相等时绝不发出。source 标记区分两条入口路径。
+每次提交的变更——进程内写入或提供方观察到的外部编辑——在新值成为权威值之后发出 `settings/updated (ns, next, prev, source)`，解析值深相等时绝不发出。source 标记区分两条入口路径。
 
 ```ts type-equiv
 /** Origin of one committed settings change. */
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 994c04eaa5..f080915228 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
 subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
-subagent.zh.md: ddc3a715fbb6589dffc38f0e0c8b23bf35dddf6e
+subagent.zh.md: 65ea762fcddb0f7b4ef5ec977cc14f13c8bf4589
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ddc3a715fb..65ea762fcd 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -4,13 +4,13 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
 ## 两类能力，两种发现方式
 
-提供方通过一个静态描述符公布其**启动时**特性，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的特性，会被大声拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-seam-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider)。
+提供方通过一个静态描述符公布其**启动时**功能，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的功能，会被明确拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-seam-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider)。
 
 ```ts type-equiv
 /**
@@ -98,7 +98,7 @@ interface SubagentStartRequest {
 
 `signal` 是就绪前后唯一的取消通道。[subagent 组合控制 Agent Note](../../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)规定 persona、live 全局工具过滤、绝对深度以及「可见性而非权限」的设计理由。
 
-面向调用方的请求不携带目录格式细节或继续执行状态。`SubagentService.start()` 会在功能检查后解析分离的一次性描述符，再将以下面向提供方的请求传给所选传输；可继续子 agent 绝不会到达 `SubagentProvider.start()`：
+面向调用方的请求不携带目录格式细节或继续执行状态。`SubagentService.start()` 会在能力检查后解析分离的一次性描述符，再将以下面向提供方的请求传给所选传输；可继续子 agent 绝不会到达 `SubagentProvider.start()`：
 
 ```ts type-equiv
 /**
@@ -123,7 +123,7 @@ persisted Session
        -> zero or more owned child Activations
 ```
 
-`SubagentService.startContinuable()` 会预留稳定的子 agent id，对版本化的 `subagent/descriptor` payload 建立快照，向指定提供方索取其分离的 `ContinuableCreateSpec`，通过私有的 activation-owner 作用域创建子 Agent，建立任何可继续父级的所有权，并提交初始 prompt。当收件箱（inbox）准入产出消息 id 时，它以 `{ childId, messageId }` resolve——无需等待轮次开始，也无需等待消息进入会话日志。在该准入之前的任何失败都会以两个 id 都不返回的方式 reject，并 dispose 任何已创建的 handle，回滚 Activation 与父级所有权。
+`SubagentService.startContinuable()` 会预留稳定的子 agent id，对版本化的 `subagent/descriptor` payload 建立快照，向指定提供方索取其分离的 `ContinuableCreateSpec`，通过私有的 activation-owner 作用域创建子 Agent，建立任何可继续父级的所有权，并提交初始提示词。当收件箱（inbox）准入产出消息 id 时，它以 `{ childId, messageId }` resolve——无需等待轮次开始，也无需等待消息进入会话日志。在该准入之前的任何失败都会以两个 id 都不返回的方式 reject，并 dispose（资源释放）任何已创建的 handle，回滚 Activation 与父级所有权。
 
 `SubagentService.followup()` 是唯一的继续执行消息操作，其路由仅取决于 Activation 的驻留状态：
 
@@ -133,15 +133,15 @@ persisted Session
 | `waiting` | 唤醒同一 Activation |
 | 无 Activation | 冷恢复一个新的 Activation |
 
-`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose [`AgentHandle`](core.md#creation-and-ownership) 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
+`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已完全停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已完全停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose [`AgentHandle`](core.md#creation-and-ownership) 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
 
-Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/enqueue`、`agent/inbox/dequeue` 与 `agent/inbox/discard` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
+Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/inserted`、`agent/inbox/claimed` 与 `agent/inbox/discarded` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
 
 后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 在准入之后是持久的来源凭据，不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
 
 对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
 
-`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。
+`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待完全停稳即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；陈旧的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。
 
 ```ts type-equiv
 /**
@@ -154,7 +154,7 @@ type SubagentInterruptAuthority =
   | { readonly kind: 'ancestor'; readonly agent: Agent }
 ```
 
-每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
+每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已完全停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
 
 最终结算会等待 `ctx.sessions.flush(session)`，但会忽略其参与布尔值，因为任意 listener 都无法证明某个持久化后端已存储该状态。rejection 会被记录，但不会使 Activation 失败；管理器仍会 dispose 该 handle 并释放所有权，此后持久化的子 agent 状态在后续恢复时可能缺失或陈旧。管理器卸载会调用内部的管理器全局 drain，关闭准入并 dispose 每片在线森林；`drainContinuableDescendants(parents)` 只关闭由 host 确切拥有的在线 Agent 之下的准入，并 dispose 其可继续后代，而无关森林保持在线。两者都会等待各自作用域内已获准的物化过程，自顶向下传播取消，按 child-first 顺序释放 handle，并且即使个别分支失败也会等待所有选中分支。持久化子会话不受该进程内拆卸的影响。
 
@@ -219,7 +219,7 @@ interface SubagentReportOptions {
 }
 ```
 
-提供方只参与准备初始创建 spec，`spawn` 与 `fork` 在此有所不同。其返回的 spec 只携带分离的、提供方专属的创建输入——目前是可选的父级历史种子——不含 Agent、`AgentHandle`、prompt 投递、结果、dispose 或 resume 操作。冷恢复根本不经由提供方分发：管理器折叠通用描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，并提交等待中的轮次。
+提供方只参与准备初始创建 spec，`spawn` 与 `fork` 在此有所不同。其返回的 spec 只携带分离的、提供方专属的创建输入——目前是可选的父级历史种子——不含 Agent、`AgentHandle`、提示词投递、结果、dispose 或恢复操作。冷恢复根本不经由提供方分发：管理器折叠通用描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，并提交等待中的轮次。
 
 ```ts type-equiv
 /**
@@ -259,13 +259,13 @@ interface ContinuableCreateSpec {
 }
 ```
 
-描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果契约，而非持久化身份）。
+描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果约定，而非持久化身份）。
 
-本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
+本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始提示词获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -333,7 +333,7 @@ interface SubagentStopReasonMap {
 
 ## 单次 run：`SubagentRun`
 
-`SubagentRun` 是消费方持有的、指向一个已发布单次子 agent 的句柄——一次可 dispose 的前台委派，只有一个结果，绝不是持久化子 agent handle。发布后的提示词提交、轮次工作与基础设施故障归 `result` 所有。消费方 await 该结果并始终 dispose 该 run，直至完全停稳。子 agent 失败时以非 completed 的 stop reason resolve；只有无法表示的基础设施故障才会 reject。run 没有 steering，也没有 resume：可继续对话根本没有 run，因为继续执行管理器直接持有它们的 `AgentHandle`，并通过子 agent 自己的收件箱为每个轮次排序。
+`SubagentRun` 是消费方持有的、指向一个已发布单次子 agent 的句柄——一次可 dispose 的前台委派，只有一个结果，绝不是持久化子 agent handle。发布后的提示词提交、轮次工作与基础设施故障归 `result` 所有。消费方 await 该结果并始终 dispose 该 run，直至完全停稳。子 agent 失败时以非 completed 的 stop reason resolve；只有无法表示的基础设施故障才会 reject。run 没有 steering，也没有恢复：可继续对话根本没有 run，因为继续执行管理器直接持有它们的 `AgentHandle`，并通过子 agent 自己的收件箱为每个轮次排序。
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 21003bb796..b12daefe88 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
 tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
-tools.zh.md: 50843b07f1d98b1c9d9222288b1273b34bee1e4a
+tools.zh.md: acdf10a0140e81dada9104653dee92dc9cb6f50d
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 50843b07f1..acdf10a014 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -148,7 +148,7 @@ type InferArgs<S> = InferProperties<S, []>
 
 `defineTool({ name, description, parameters, output, execute, … })` 将参数推导与 `parameterSchemaSpecToJsonSchema()` 和 `validateArgs()` 绑定，并将 `execute`/`render`/`presentationMeta` 与 `InferValue<OutputSchema>` 绑定。Schema 记录只包含自有且可枚举的字符串键，schema 数组是稠密的内建数组，因此推导、编译与校验观察到的是同一份声明。精确推导保持到 16 层容器，之后放宽为 `JsonValue`；运行时校验仍会继续遍历完整 schema。`valueSchemaSpecToJsonSchema()` 通过同一套已强制执行的原始子集编译输出声明。参数不匹配时抛出 `ToolArgsError`（`INVALID_ARGS`）；函数体或后置策略产生的值无效时抛出 `ToolOutputError`（`INVALID_TOOL_OUTPUT`）。两者都经由常规工具错误路径处理。原始 JSON Schema 默认保持开放；不支持的关键字会被拒绝，而不会在未强制执行的情况下获准进入。
 
-注册是一个受信任的同进程契约。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
+注册是一个受信任的同进程约定。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
 
 ## `ToolRestriction` — 单个作用域的实时全局过滤器
 
@@ -243,7 +243,7 @@ type ToolExecutionMode =
   | { kind: 'exclusive' }
 ```
 
-Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型契约均不受影响）：
+Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型约定均不受影响）：
 
 ```ts type-equiv
 /**
@@ -452,7 +452,7 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 - `ToolCallView`（待执行）：`{ card: 'generic', title, kind?, rawInput?, content?, locations? }`（默认卡片；`locations` 是 `{ path, line? }[]`，表示调用读取/修改的文件，供编辑器跟随）、`{ card: 'terminal', title, description?, cwd? }`（shell 命令→终端卡片）、或 `{ card: 'diff', title, diffs, locations? }`（文件创建/修改→行内 diff 卡片；`diffs` 是 `{ path, oldText, newText }[]`，新文件时 `oldText: null`）。
 - `ToolResultView`（已完成）：`{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`（捕获的运行输出 + 退出状态；有能力的 UI 显示退出状态标签，其他 UI 可以派生围栏 ` ```console ` 回退）、`{ card: 'diff', title?, diffs }`（已完成的文件变更→要展示的变更，通常是从变更前后内容计算出带上下文行的已应用 hunk，或在没有前像时的整文件 diff）、`{ card: 'search', shape, title?, truncated, total, … }`（已完成的发现型搜索→`shape: 'matches'`（grep）为按文件分组的匹配，`shape: 'paths'`（glob）为扁平路径列表；`truncated`/`total` 报告内联结果是否被截断，使 UI 永不把部分结果当作完整结果呈现；该视图不携带结果文本——无 search 卡片的 UI 回退到原始结果内容）、`{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }`（已完成的文件读取→带行号、可选语法高亮的代码视图；`offset` 是窗口请求的 1-based 起始行，即使 `lines` 为空也保留；`lang` 是从扩展名推得的语言提示，`content` 是无读取能力的 UI 回退时使用的去信封文本）、或 `{ card: 'web', kind: 'search' | 'fetch', title?, … }`（已完成的 web 检索；`kind: 'search'` 携带结构化的 `sources`/`answer?`/`truncated`，`kind: 'fetch'` 携带 `url`/`statusCode`/`truncated`，不具备 `web` 能力的 UI 回退到原始结果内容——正文不会重复进视图）。已完成视图会替换待执行视图，因此变更工具即使与调用时的片段重复也要返回 diff 结果；搜索和 web 检索都没有 `card` 的调用时对应视图（其 pending 状态保持为 generic 卡片，因为结构化结果只在 `execute` 之后才存在）。
 
-`ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）、`FileDiff`（`{ path, oldText, newText }`）与 `ReadFileLine`（`{ number, text }`，读取窗口中一行带 1-based 行号的内容）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；host/client 运行时将这套中性词汇投影为各自的视图。
+`ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）、`FileDiff`（`{ path, oldText, newText }`）与 `ReadFileLine`（`{ number, text }`，读取窗口中一行带 1-based 行号的内容）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；host/client 运行时将这套中性词汇投影为各自的视图。
 
 完整的展示字段文档见 [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)。`bash` schema 与执行器见 [bash.md](bash.md)；通用后台控制见 [tasks.md](tasks.md)。
 
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index b8fdb092f2..d58e6036ab 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
 typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
-typert.zh.md: ff6b45a517c75392ee87fa348d72bfae6cdf1efb
+typert.zh.md: a025716dad9a9279a45530a0a9109a13a2c34b0c
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index ff6b45a517..a025716dad 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -2,11 +2,11 @@
 
 [English](typert.md) | 中文
 
-以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共契约的字面定义。
+以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共约定的字面定义。
 
-## Lookup 与 Context 声明
+## Lookup 与上下文声明
 
-业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；Context 声明将一种 scoped Context 类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
+业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；上下文声明将一种作用域上下文类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
 
 ```ts type-equiv
 /** Merge-extensible Host object lookup declarations. */
@@ -114,7 +114,7 @@ interface InvocationDescriptor {
 
 ## TypeRT 注册表
 
-`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与 scoped Context 提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
+`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与作用域上下文提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
 
 ```ts type-equiv
 /** Minimal TypeRT runtime consumed through dependency inversion. */
@@ -135,7 +135,7 @@ interface TypeRTRemoteNamespaceMap {}
 
 ## Host Gateway
 
-Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，普通异常由 RPC 适配器折叠为传输层的 `internal` 错误码，lookup 策略通过 `TypeRTLookupFailure` 携带的既有 RPC error 则原样返回。
+Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，普通异常由 RPC 适配器归并为传输层的 `internal` 错误码，lookup 策略通过 `TypeRTLookupFailure` 携带的既有 RPC error 则原样返回。
 
 ```ts type-equiv
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -188,7 +188,7 @@ interface TypertGateway {
 
 ## 消费方 Remote
 
-`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子 Service，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务 Service 类型都不会进入消费方。
+`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子服务，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务服务类型都不会进入消费方。
 
 ```ts type-equiv
 /** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
diff --git a/docs/subsystems/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
index 342cf9b9f7..296bc8b766 100644
--- a/docs/subsystems/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/user-interaction.md
 user-interaction.md: a19155ae06af0133ae468c004b2e3b66f1de3fb8
-user-interaction.zh.md: dc5845a976068981b2761e26502eaf7dd95dcb01
+user-interaction.zh.md: c7aa9cafc9865191cda4089ad2beb214a33b00ef
diff --git a/docs/subsystems/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
index dc5845a976..c7aa9cafc9 100644
--- a/docs/subsystems/user-interaction.zh.md
+++ b/docs/subsystems/user-interaction.zh.md
@@ -2,7 +2,7 @@
 
 [English](user-interaction.md) | 中文
 
-[dsh-user-interaction](../../packages/interaction/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给它连接的客户端。
+[dsh-user-interaction](../../packages/interaction/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI 界面提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给其连接的客户端。
 
 源码：[`packages/interaction/user-interaction/src/index.ts`](../../packages/interaction/user-interaction/src/index.ts)
 
@@ -70,7 +70,7 @@ interface AskUserQuestionItem {
 
 ## 提问请求
 
-`AskUserQuestionRequest` 是跨包（package）的请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。如提供 `agent`，它必须与存活调用方是同一实例；只有当当前注册表将该实例识别为运行时根时，交互 seam 才会接纳该 agent。
+`AskUserQuestionRequest` 是跨包请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。如提供 `agent`，它必须与存活调用方是同一实例；只有当当前注册表将该实例识别为运行时根时，交互 seam 才会接纳该 agent。
 
 ```ts type-equiv
 /** Request for a human answer. */
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 0b7cdfdc76..4e9f1cb635 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/testing.md
 testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
-testing.zh.md: e9182495fbdbb1458c9ff5b30a9591f8b70f27c5
+testing.zh.md: 1d87309872d31a2779f3a411ce09e60db2416efd
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index e9182495fb..1d87309872 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -2,15 +2,15 @@
 
 [English](testing.md) | 中文
 
-本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note（agent 决策记录）承载设计动机。
+本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note承载设计动机。
 
 ## 层级
 
-- **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性契约回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
+- **单元测试**（`pnpm run test`）：vitest 运行包和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性约定回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/bash/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其 executor 套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。
 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。
-- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输契约与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
-- **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
+- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 通道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
 签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
 
@@ -42,8 +42,8 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个示例或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。
 - 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。
-- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一契约。
+- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一约定。
 
 ## 何时需要快照测试
 
-每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有内部规范事件 JSONL 快照与回放 fixture。`pwsh-tool-turn` ACP 场景启动真实 `pwsh`，在无 `pwsh` 的主机上跳过。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
+每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有内部规范事件 JSONL 快照与回放 fixture。`pwsh-tool-turn` ACP 场景启动真实 `pwsh`，在无 `pwsh` 的主机上跳过。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；浏览器渲染的 Web GUI 旅程使用 `apps/web/tests/snapshots/`；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
new file mode 100644
index 0000000000..8eecc6cc4a
--- /dev/null
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
+tool-catalog.md: 8986847d1ed2fe9d64ada0c71f34700ff95fb364
+tool-catalog.zh.md: ed78883f74a7d245de97bc45d7125e6245e140ce
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
new file mode 100644
index 0000000000..ed78883f74
--- /dev/null
+++ b/docs/tool-catalog.zh.md
@@ -0,0 +1,1553 @@
+<!-- 英文源文件由 scripts/gen-tool-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-tool-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-catalog.md` 重新记录配对。 -->
+
+# 工具 Schema 目录
+
+[English](tool-catalog.md) | 中文
+
+已发布插件向 `ctx.tools` 提供的所有面向模型的工具：模型通过系统提示词组装获得的 `name`、`description` 和 JSON Schema `parameters`。本目录是[子系统页面](subsystems/core.md)（类型及每页生成的 `cordis-surface` 接线区域）的补充；本页列出的是向 agent（智能体）提供的*工具*。
+
+英文源文件由系统**生成**，并通过 `pnpm run verify-tool-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。与 Cordis 目录（纯源码 AST 处理）不同，英文生成器会在真实上下文中**启动**每个工具插件并读取 `ctx.tools.schemas()`，因为工具 schema 无法通过静态分析完全确定，例如运行时展开的枚举、拼接的描述、由配置决定的名称以及使用原始 JSON Schema 的 MCP 工具。完整性守卫会 glob 匹配 `packages/*/tool-*`；如果生成器的启动 manifest（元数据清单）遗漏任何包，检查就会失败，因此新工具不会在无人察觉的情况下缺少文档。参见[工具 schema 目录 Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)。
+
+范围：`packages/*/tool-*` 下已发布的产品工具，每个工具均使用其**默认**配置启动；但如果某个 Config 字段是**必填项**且没有默认值，生成器就必须作出选择，对应包的说明会记录本页展示的是哪个分支。注册的工具**名称**可以是加载时配置，例如 `tool-subagent` 的 `toolName`，因此部署可能以不同名称或额外名称提供某个包；如果存在随产品发布的别名，对应包的说明会予以记录。`examples/` 中的演示工具（例如 `echo`）不在范围内，这与 Cordis 目录仅涵盖包的范围一致。
+
+## 工具包映射
+
+下表将模型可见的工具名称与其背后的插件包和服务 seam 对应起来。各包章节随后给出确切的 JSON Schema。
+
+| 工具包 | 模型可见名称 | 依赖 | 写入／影响 | 随产品发布的别名 | 部署说明 |
+| --- | --- | --- | --- | --- | --- |
+| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userInteraction` | `tool/call`、`UI/provider 回答问题后的 tool/result` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 |
+| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`每个桥接子调用对应的一组 tool/code-dispatch-start + tool/code-dispatch`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
+| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`获批评审后的 plan/mode inactive`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
+| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
+| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`进程本地临时 Plugin 生命周期` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
+| `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`变更对应的 fs/write-intent 或 fs/edit-intent`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
+| `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
+| `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
+| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`变更对应的 goal/change`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
+| `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`、`ctx.lsp`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 |
+| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`执行期间的工作流与子会话事件` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
+| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`通过 agent.inject() 注入的 user/message 替换目录` | - | - |
+| `@deepseek-ai/dsh-tool-session-query` | `session_event_read`、`session_event_search`、`session_event_trace`、`session_search`、`session_trace` | `ctx.tools`、`ctx.systemPrompt`、`ctx.sessionQuery`、`a calling Agent for workspace authority` | `tool/call`、`tool/result` | - | 这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 |
+| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`经所选提供方产生的子会话事件` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
+| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`经 ctx.subagents 产生的子会话事件` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
+| `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`直接父会话中的 user 角色消息` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。 |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`通过 agent.inject() 发送后台完成通知的 user/message` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
+| `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 |
+| `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflows`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
+| `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 |
+
+## `@deepseek-ai/dsh-tool-ask-user`
+
+### `ask_user_question`
+
+继续操作前，如果需要确认、选择或缺失的信息，请向用户提出简明问题。发送一个或多个问题，每个问题都带一个稳定 id，该 id 会在答案中原样返回。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "questions": {
+      "type": "array",
+      "description": "Questions to ask the user before continuing.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable id for this question; echoed in the answer."
+          },
+          "question": {
+            "type": "string",
+            "description": "The specific question to ask the user."
+          },
+          "header": {
+            "type": "string",
+            "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."
+          },
+          "options": {
+            "type": "array",
+            "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true,
+              "properties": {
+                "label": {
+                  "type": "string",
+                  "description": "Short user-facing option label."
+                },
+                "description": {
+                  "type": "string",
+                  "description": "One sentence explaining the tradeoff or impact."
+                }
+              },
+              "required": [
+                "label"
+              ]
+            }
+          },
+          "multi_select": {
+            "type": "boolean",
+            "description": "Whether the user may select more than one option. Defaults to false."
+          }
+        },
+        "required": [
+          "id",
+          "question"
+        ]
+      }
+    }
+  },
+  "required": [
+    "questions"
+  ]
+}
+```
+
+来源：[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)
+
+ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。
+
+## `@deepseek-ai/dsh-tools`
+
+### `run_code`
+
+针对可用工具执行 TypeScript 程序。请编写异步函数的**函数体**（仅使用可擦除语法；支持顶层 `await` 和 `return`），并根据系统提示词中的声明，以 `await tools.name(args)` 形式调用工具。只有打印或返回的内容会传回，请谨慎筛选。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "The program: the body of an async TypeScript function."
+    },
+    "description": {
+      "type": "string",
+      "description": "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."
+    }
+  },
+  "required": [
+    "code",
+    "description"
+  ]
+}
+```
+
+来源：[`packages/core/tools/src/code-mode.ts`](../packages/core/tools/src/code-mode.ts)
+
+在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。
+
+## `@deepseek-ai/dsh-plan-mode`
+
+### `exit_plan_mode`
+
+仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 `#` 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "plan": {
+      "type": "string",
+      "description": "The complete plan, as markdown, starting with a # heading that names it."
+    }
+  },
+  "required": [
+    "plan"
+  ]
+}
+```
+
+来源：[`packages/plan/plan-mode/src/index.ts`](../packages/plan/plan-mode/src/index.ts)
+
+规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。
+
+## `@deepseek-ai/dsh-tool-bash`
+
+### `bash`
+
+执行 bash 命令（`bash -c`）并返回 stdout/stderr。每次调用都在新 shell 中运行：调用之间不保留任何状态（cwd、变量、函数），请传入 `workdir`，不要使用 `cd`。非零退出会报告为 `[exit code: N]`。当前 harness 环境信息通过托管的 `$DSH_*` 变量公开，需要时请检查这些变量。命令可能在文件沙箱中运行；被阻止的文件操作报告为 `[sandbox: file access denied under <mode> mode]`，这是策略拒绝，而不是命令缺陷，请勿换一种方式重试。较长的输出会截断，只保留尾部；如可用，完整输出会保存到文件并报告其路径。对于长时间运行的命令，请设置 `run_in_background: true`：调用会立即返回 task id；使用 `task_output` 读取输出，使用 `task_kill` 停止任务。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The bash command to execute."
+    },
+    "description": {
+      "type": "string",
+      "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
+    },
+    "timeoutMs": {
+      "type": "number",
+      "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+    },
+    "workdir": {
+      "type": "string",
+      "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
+    }
+  },
+  "required": [
+    "command",
+    "description"
+  ]
+}
+```
+
+来源：[`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
+
+bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
+
+## `@deepseek-ai/dsh-tool-pwsh`
+
+### `pwsh`
+
+执行 PowerShell 命令（`pwsh -Command`）并返回 stdout/stderr。每次调用都在新的 pwsh 进程中运行：调用之间不保留任何状态（cwd、变量、函数），请传入 `workdir`，不要使用 `cd`。路径采用 Windows 原生形式（`C:\...`）；使用 `$env:NAME` 读取环境变量。非零退出会报告为 `[exit code: N]`。当前 harness 环境信息通过托管的 `$env:DSH_*` 变量公开，需要时请检查这些变量。较长的输出会截断，只保留尾部；如可用，完整输出会保存到文件并报告其路径。在 Windows 上，被强制终止的命令会以 `[exit code: 1]` 结算且不带信号标记，请将其视为中断，而不是命令失败。对于长时间运行的命令，请设置 `run_in_background: true`：调用会立即返回 task id；使用 `task_output` 读取输出，使用 `task_kill` 停止任务。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The PowerShell command to execute."
+    },
+    "description": {
+      "type": "string",
+      "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"Get-Process\" → \"List running processes\"."
+    },
+    "timeoutMs": {
+      "type": "number",
+      "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+    },
+    "workdir": {
+      "type": "string",
+      "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
+    }
+  },
+  "required": [
+    "command",
+    "description"
+  ]
+}
+```
+
+来源：[`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
+
+pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
+
+## `@deepseek-ai/dsh-tool-cordis`
+
+### `cordis_inspect`
+
+检查当前 DSH 进程中的实时 Cordis 运行时。只读。章节包括：`services`（所有已提供的 ctx 服务及拥有它的插件 fiber）、`plugins`（所有实时插件 fiber 及其生命周期状态）、`tools`（当前注册的模型可见工具，即你可以调用的工具）、`temporary`（仅由 cordis_mount 创建的临时 Plugin：id、名称、状态、提供的服务、等待的服务和存续期）、`api`（每个**实时**服务的方法签名以及参数／返回值类型形状；编写调用服务的插件代码前请先阅读）、`events`（每个 harness 事件的分派模式和确切签名；在此选择监听目标）。临时 Plugin 仅存在于内存中，会在后续轮次中保持活动，并在 cordis_unmount、工具集卸载或 DSH 重启后消失；不会自动恢复。`temporary` 是 `plugins` 的子集。省略 `what` 可获取全部 6 个章节。使用 `what:"api"` 或 `what:"events"` 时，可传入确切的 `name`，将范围缩小到一个服务／事件，并包含其原始源码 JSDoc。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "what": {
+      "type": "string",
+      "description": "Limit the report to one section. Omit for all sections.",
+      "enum": [
+        "services",
+        "plugins",
+        "tools",
+        "temporary",
+        "api",
+        "events"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."
+    }
+  }
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
+
+### `cordis_mount`
+
+在当前 DSH 进程中挂载临时 Cordis Plugin。它创建的是内存中的运行时 Plugin，而不是已安装或已配置的 Plugin。该插件会在后续轮次中保持活动，直到执行 cordis_unmount、工具集卸载或 DSH 重启。它不会创建文件、安装包、修改 cordis.yml 或个人／项目配置、在重启后保留，也不会自动转为永久插件。若要保留，请让 Agent 通过常规开发工作流实现普通的本地、项目或仓库 Plugin。它可能影响同一进程中的其他会话；沙箱不是安全边界，注入的服务会访问真实运行时。`code` 会立即作为异步 JavaScript 函数的函数体在隔离沙箱中运行，并且**必须** `return` 一个插件。支持两种形式：函数形式 `return (ctx) => { … }`，它不声明 inject，因此可以注册工具、监听事件和提供服务，但访问**任何**服务（例如 ctx.bash）都会抛出异常；仅在不需要服务时使用。对象形式 `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }`，它声明依赖，Cordis 只在服务存在后激活插件；**优先使用**这种形式。你只能访问 inject 中列出的服务：即使未声明的服务存在，访问它也会抛出异常，因为如果提供方被卸载，未声明的依赖将无法清理。代码调用服务**之前**，请读取 cordis_inspect 的 what:"api"；它会列出方法签名以及参数／返回值的类型形状，不要猜测字段类型，例如 bash 运行的 stdout 是对象而非字符串。在 `apply` 内，请使用标准 Cordis API：通过 `ctx.on(event, listener)` 观察事件（见 cordis_inspect 的 what:"events"），或调用 `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` 为自己提供新工具；该工具会在你的**下一步骤**可调用。工具参数：每个键**就是**一个属性，即 { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }；每个直接 DSL 对象都声明 additionalProperties: true|false，而 oneOf: [schema, schema, ...] 会取代 type，表示恰好匹配一个成员的联合。也接受原始 JSON Schema { type: 'object', properties, required?: […] } 包装层，其中对象默认开放。工具的 `execute` **必须**返回 `output.schema` 声明的无损 JSON 值；`output.render(args, value)` 单独返回 Native／模型内容块。临时 Plugin 可以**组合**：一个 Plugin 可以通过 `ctx.provide('name', value)` 提供服务，另一个则可声明 `inject: ['name']` 来消费它；消费方会在提供方出现前保持等待，提供方卸载后重新回到等待状态。在 `apply` 中注册的一切都会由 cordis_unmount 自动清理。沙箱全局对象：`console`（带 `[cordis:<id>]` 标签，写入 harness 终端）、`harness.defineTool`、`harness.registerTool`、`btoa`、`atob`、`TextEncoder`、`TextDecoder`。Node API 已**禁用**：文件系统／网络／定时工作必须通过 Cordis 服务完成，绝不能使用 Node 内置能力；`require`、`setTimeout`／`setInterval` 和 `fetch` 会抛出重定向错误，`process` 和 `Buffer` 未定义。应改用 inject: ['fs'] + ctx.fs 处理文件、inject: ['web'] + ctx.web 处理 HTTP、inject: ['bash'] + ctx.bash 处理进程、inject: ['timer'] + ctx.setTimeout/ctx.setInterval 处理定时（这些是 fiber effect，卸载时自动清理）；cordis_inspect 的 what:"api" 会展示**当前**运行时提供的能力。请编写**纯** JavaScript，不要使用 TypeScript（不得使用 `as` 或类型注解）。注意事项：(1) waterfall（瀑布式事件）事件（例如 tools/pre-execute）会向监听器传入最后一个 `next` 回调，该回调**必须**被调用；不调用 `next()` 就返回会**否决**此次调用。除非你有意拦截，否则请优先使用普通通知事件。(2) 切勿等待只能在当前轮次之后解析的内容；你的代码运行在该轮次的工具调用**内部**，否则会死锁。(3) 你的 `ctx` 是受限门面：可以注册工具、观察事件、提供／消费服务和使用定时器，但不会提供框架内部能力（ctx.root、ctx.fiber、ctx.extend、ctx.plugin 等）。不过，它并非安全边界：你注入的服务（例如 ctx.bash）会访问真实运行时。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."
+    }
+  },
+  "required": [
+    "code"
+  ]
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
+
+### `cordis_unmount`
+
+卸载当前进程中由 cordis_mount 创建的临时 Plugin。它会等待该插件的工具、监听器、服务、定时器及其他自有效果全部清理完成。只接受 `dyn-N` 临时 id；无法移除 Loader、已配置或已安装的 Plugin。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."
+    }
+  },
+  "required": [
+    "id"
+  ]
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
+
+不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。
+
+## `@deepseek-ai/dsh-tool-bash-persistent`
+
+### `bash`
+
+在持久 bash shell 中运行命令。包括当前目录和已导出环境变量在内的状态会在此 agent 的多次调用之间保留。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The bash command to run. Relative path is preferred in the command."
+    }
+  },
+  "required": [
+    "command"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-bash-persistent/src/index.ts`](../packages/pty/tool-bash-persistent/src/index.ts)
+
+一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。
+
+## `@deepseek-ai/dsh-tool-str-replace-editor`
+
+### `str_replace_editor`
+
+用于查看、创建和编辑文件的自定义编辑工具：
+
+* 状态会在命令调用以及与用户的讨论之间持久保留
+* 如果 `path` 是文件，`view` 会显示应用 `cat -n` 后的结果。如果 `path` 是目录，`view` 会列出最多向下 2 层的非隐藏文件和目录
+* 如果指定的 `path` 已作为文件存在，则不能使用 `create` 命令
+* 如果 `command` 产生较长输出，输出会被截断并标记为 `<response clipped>`
+
+使用 `str_replace` 命令时请注意：
+
+* `old_str` 参数应与原文件中一行或多行连续内容**完全**匹配。请留意空白字符！
+* 如果 `old_str` 参数在文件中不唯一，则不会执行替换。请确保在 `old_str` 中包含足够的上下文，使其唯一
+* `new_str` 参数应包含用于替换 `old_str` 的已编辑行
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`.",
+      "enum": [
+        "view",
+        "create",
+        "str_replace",
+        "insert"
+      ]
+    },
+    "path": {
+      "type": "string",
+      "description": "Absolute path to file or directory, e.g. `/repo/file.py` or `/repo`."
+    },
+    "file_text": {
+      "type": "string",
+      "description": "Required parameter of `create` command, with the content of the file to be created."
+    },
+    "insert_line": {
+      "type": "integer",
+      "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`."
+    },
+    "new_str": {
+      "type": "string",
+      "description": "Optional parameter of `str_replace` command containing the new string (if not given, no string will be added). Required parameter of `insert` command containing the string to insert."
+    },
+    "old_str": {
+      "type": "string",
+      "description": "Required parameter of `str_replace` command containing the string in `path` to replace."
+    },
+    "view_range": {
+      "type": "array",
+      "description": "Optional parameter of `view` command when `path` points to a file. If none is given, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file.",
+      "items": {
+        "type": "integer"
+      }
+    }
+  },
+  "required": [
+    "command",
+    "path"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-str-replace-editor/src/index.ts`](../packages/fs/tool-str-replace-editor/src/index.ts)
+
+基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。
+
+## `@deepseek-ai/dsh-tool-fs`
+
+### `edit`
+
+通过替换字面量文本来编辑现有 UTF-8 文本文件。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_path": {
+      "type": "string",
+      "description": "Path to edit, resolved by the filesystem backend."
+    },
+    "old_string": {
+      "type": "string",
+      "description": "Literal text to replace. Must match exactly."
+    },
+    "new_string": {
+      "type": "string",
+      "description": "Literal replacement text. Use an empty string to delete the match."
+    },
+    "replace_all": {
+      "type": "boolean",
+      "description": "Replace all matches. Defaults to false; when false, old_string must appear exactly once."
+    }
+  },
+  "required": [
+    "file_path",
+    "old_string",
+    "new_string"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts)
+
+### `read`
+
+读取 UTF-8 文本文件，并返回带行号的内容。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_path": {
+      "type": "string",
+      "description": "Path to read, resolved by the filesystem backend."
+    },
+    "offset": {
+      "type": "number",
+      "description": "1-based first line to return. Defaults to 1."
+    },
+    "limit": {
+      "type": "number",
+      "description": "Maximum number of lines to return. Defaults to 2000."
+    }
+  },
+  "required": [
+    "file_path"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts)
+
+### `write`
+
+创建或完全替换 UTF-8 文本文件。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_path": {
+      "type": "string",
+      "description": "Path to write, resolved by the filesystem backend."
+    },
+    "content": {
+      "type": "string",
+      "description": "Full UTF-8 text content to write."
+    }
+  },
+  "required": [
+    "file_path",
+    "content"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts)
+
+先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。
+
+## `@deepseek-ai/dsh-tool-fs-search`
+
+### `glob`
+
+查找路径匹配 glob 模式的文件。只返回匹配的文件路径，绝不返回目录；包括隐藏文件和被忽略的文件，但排除 VCS 元数据目录。最多按修改时间顺序返回 100 条路径；如果结果更多，则改为返回从顶层条目中抽样的 100 条路径，说明已抽样，并报告完整排序列表的保存位置。该工具不枚举目录条目。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "pattern": {
+      "type": "string",
+      "description": "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\"). A pattern with no \"/\" matches the basename at any depth, so \"*\" and \"*.ts\" both search the whole tree; include a separator to anchor the depth."
+    },
+    "path": {
+      "type": "string",
+      "description": "Directory to search in. Defaults to the session workspace; a relative path resolves against it."
+    }
+  },
+  "required": [
+    "pattern"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts)
+
+### `grep`
+
+使用 ripgrep 正则表达式搜索文件内容。返回带行号的匹配行，并按文件分组。前 250 条匹配会直接返回；结果达到上限时会报告完整匹配列表的保存位置。如需周边上下文，请对匹配的文件使用 read。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "pattern": {
+      "type": "string",
+      "description": "Regular expression to search for (ripgrep syntax)."
+    },
+    "path": {
+      "type": "string",
+      "description": "File or directory to search. Defaults to the session workspace; a relative path resolves against it."
+    },
+    "include": {
+      "type": "string",
+      "description": "One glob filter for which files to search (e.g. \"*.ts\", \"*.{js,jsx}\"). Not a list; negation is not supported."
+    }
+  },
+  "required": [
+    "pattern"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts)
+
+glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。
+
+## `@deepseek-ai/dsh-tool-pty`
+
+### `terminal_close`
+
+关闭一个持久终端，并等待其捕获且所有的进程树完全退出。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id."
+    }
+  },
+  "required": [
+    "sessionId"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_list`
+
+列出当前 agent 所有的持久终端会话。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_open`
+
+通过已注册的后端类型创建按所有者隔离的持久终端会话。需要在多次工具调用之间保留 shell 或 REPL 状态时，请使用此工具。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Registered terminal backend type, usually \"shell\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Optional owner-local display name such as \"main\" or \"gdb\"."
+    },
+    "cwd": {
+      "type": "string",
+      "description": "Initial working directory. Defaults to the deployment workspace root."
+    }
+  },
+  "required": [
+    "type"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_read`
+
+从持久终端读取一页有界的保留输出，不发送输入。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id."
+    },
+    "offset": {
+      "type": "number",
+      "description": "Newest-relative line offset (default 0)."
+    },
+    "count": {
+      "type": "number",
+      "description": "Requested line count (default 500; backend caps apply)."
+    }
+  },
+  "required": [
+    "sessionId"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_send`
+
+向持久终端发送文本。默认会提交 Enter，并等待提示符、stdin 等待、输出静默、超时或会话退出。后台模式会返回供 task_output／task_kill 使用的 task id。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id returned by terminal_open or terminal_list."
+    },
+    "text": {
+      "type": "string",
+      "description": "UTF-8 text to write to the terminal."
+    },
+    "submit": {
+      "type": "boolean",
+      "description": "Submit Enter after text (default true). Set false for control characters or incomplete REPL input."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Return a task id immediately; collect with task_output or stop with task_kill."
+    }
+  },
+  "required": [
+    "sessionId",
+    "text"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_signal`
+
+向持久终端当前的前台进程组发送允许的信号。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id."
+    },
+    "signal": {
+      "type": "string",
+      "description": "Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.",
+      "enum": [
+        "SIGINT",
+        "SIGTERM",
+        "SIGKILL",
+        "SIGTSTP",
+        "SIGHUP"
+      ]
+    }
+  },
+  "required": [
+    "sessionId",
+    "signal"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。
+
+## `@deepseek-ai/dsh-tool-goal`
+
+### `create_goal`
+
+当当前直接人类请求是需要跨自主 Goal Round 持续推进的长期目标时，创建一个持久化的同会话完成目标。即使用户没有明确说「创建目标」，你也可以推断其意图。不要用于简单的单轮工作。执行时会拒绝非人类权限和 subagent 权限。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "objective": {
+      "type": "string",
+      "description": "The concrete completion objective inferred from the direct human request."
+    },
+    "max_goal_rounds": {
+      "type": "number",
+      "description": "Optional positive safe-integer limit on automatic continuation rounds."
+    }
+  },
+  "required": [
+    "objective"
+  ]
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts)
+
+### `get_goal`
+
+读取当前的同会话目标，包括确切的 id／revision、目标、阶段、已完成的延续 Round 数、Round 上限、存在时的阻塞原因，以及是否已准备下一次延续。更新目标前请先调用此工具。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts)
+
+### `update_goal`
+
+更新确切的当前目标 revision。edit、pause 和 resume 要求直接的顶层人类请求。在自动延续当前目标期间，也允许 complete 和 blocked。在达到配置的最小 Round 数之前会拒绝 blocked；模型仍须判断相同条件是否在这些 Round 中持续存在，并在 blocked_reason 中予以说明。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "goal_id": {
+      "type": "string",
+      "description": "Exact id returned by get_goal."
+    },
+    "revision": {
+      "type": "number",
+      "description": "Exact positive revision returned by get_goal."
+    },
+    "action": {
+      "type": "string",
+      "description": "edit | pause | resume | complete | blocked",
+      "enum": [
+        "edit",
+        "pause",
+        "resume",
+        "complete",
+        "blocked"
+      ]
+    },
+    "objective": {
+      "type": "string",
+      "description": "Replacement objective; valid only with action edit."
+    },
+    "max_goal_rounds": {
+      "type": "number",
+      "description": "Replacement cap; valid only with action edit."
+    },
+    "blocked_reason": {
+      "type": "string",
+      "description": "Concrete blocking condition; required only with action blocked."
+    }
+  },
+  "required": [
+    "goal_id",
+    "revision",
+    "action"
+  ]
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts)
+
+create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。
+
+## `@deepseek-ai/dsh-tool-lsp`
+
+### `lsp`
+
+查询语言服务器，以精确导航代码。operation 可取 goToDefinition、findReferences、goToImplementation 或 hover。line 和 character 是从 1 开始的 UTF-16 光标坐标。findReferences 包含声明。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "operation": {
+      "type": "string",
+      "description": "goToDefinition, findReferences, goToImplementation, or hover.",
+      "enum": [
+        "goToDefinition",
+        "findReferences",
+        "goToImplementation",
+        "hover"
+      ]
+    },
+    "file_path": {
+      "type": "string",
+      "description": "The source file to query, relative to the workspace or absolute."
+    },
+    "line": {
+      "type": "number",
+      "description": "One-based line of the cursor."
+    },
+    "character": {
+      "type": "number",
+      "description": "One-based UTF-16 column of the cursor."
+    }
+  },
+  "required": [
+    "operation",
+    "file_path",
+    "line",
+    "character"
+  ]
+}
+```
+
+来源：[`packages/lsp/tool-lsp/src/index.ts`](../packages/lsp/tool-lsp/src/index.ts)
+
+lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。
+
+## `@deepseek-ai/dsh-tool-ralph`
+
+### `ralph`
+
+围绕一个不可变目标运行使用全新 agent 的前台 Ralph 循环。仅当直接人类明确要求 Ralph 或使用全新 agent 迭代时使用。每个 Round 都会启动一个全新子级，该子级看不到父级对话或先前子会话；共享工作区充当长期记忆，Round 之间只传递有界的结构化报告。当工作进程报告完成、报告具体阻塞项或达到 Round 上限时，调用返回。普通的长期同会话工作应使用 goal 工具。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "objective": {
+      "type": "string",
+      "description": "The immutable completion objective for every fresh Ralph round."
+    },
+    "maxRounds": {
+      "type": "number",
+      "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling."
+    }
+  },
+  "required": [
+    "objective"
+  ]
+}
+```
+
+来源：[`packages/workflow/tool-ralph/src/index.ts`](../packages/workflow/tool-ralph/src/index.ts)
+
+固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。
+
+## `@deepseek-ai/dsh-tool-skill`
+
+### `skill`
+
+加载可用 skill（技能）的完整说明。在执行点名某项 skill 或与其明确匹配的任务前，请使用会话 skill 目录中的确切名称调用此工具。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The exact skill name from the available skills list."
+    }
+  },
+  "required": [
+    "name"
+  ]
+}
+```
+
+来源：[`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-session-query`
+
+### `session_event_read`
+
+从一个已获授权的会话中读取一个完整且未删节的事件，以及可选的相邻原始事件概述。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    },
+    "seq": {
+      "type": "integer",
+      "description": "Target event sequence number."
+    },
+    "before": {
+      "type": "integer",
+      "description": "Number of preceding raw events to summarize. Omit for none."
+    },
+    "after": {
+      "type": "integer",
+      "description": "Number of following raw events to summarize. Omit for none."
+    }
+  },
+  "required": [
+    "seq"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_event_search`
+
+在一个已获授权的会话中搜索先前事件；如果搜索当前会话，则排除执行此次调用的步骤。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    },
+    "query": {
+      "type": "string",
+      "description": "Literal full-text query over the target session."
+    },
+    "seq_from": {
+      "type": "integer",
+      "description": "Inclusive event sequence lower bound."
+    },
+    "seq_to": {
+      "type": "integer",
+      "description": "Inclusive event sequence upper bound."
+    },
+    "time_from": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time lower bound."
+    },
+    "time_to": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time upper bound."
+    },
+    "event_types": {
+      "type": "array",
+      "description": "Event types to include.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "surfaces": {
+      "type": "array",
+      "description": "Event surfaces to include.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "current",
+          "shadowed",
+          "log-only"
+        ]
+      }
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_event_trace`
+
+读取一个已获授权会话中某个事件的每项直接替换关系和来源关系。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    },
+    "seq": {
+      "type": "integer",
+      "description": "Target event sequence number."
+    }
+  },
+  "required": [
+    "seq"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_search`
+
+搜索调用方工作区中的先前会话，并从每个会话返回匹配度最高的事件。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Literal full-text query over prior session history."
+    },
+    "session_ids": {
+      "type": "array",
+      "description": "Optional session ids to include.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "created_at_from": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 creation-time lower bound."
+    },
+    "created_at_to": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 creation-time upper bound."
+    },
+    "parent_session_ids": {
+      "type": "array",
+      "description": "Optional direct parent session ids.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "include_root_sessions": {
+      "type": "boolean",
+      "description": "Include sessions with no parent in the parent filter."
+    },
+    "availability": {
+      "type": "array",
+      "description": "Require at least one selected source availability.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "live",
+          "persisted"
+        ]
+      }
+    },
+    "event_seq_from": {
+      "type": "integer",
+      "description": "Inclusive event sequence lower bound."
+    },
+    "event_seq_to": {
+      "type": "integer",
+      "description": "Inclusive event sequence upper bound."
+    },
+    "event_time_from": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time lower bound."
+    },
+    "event_time_to": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time upper bound."
+    },
+    "event_types": {
+      "type": "array",
+      "description": "Event types to include.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "event_surfaces": {
+      "type": "array",
+      "description": "Event surfaces to include.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "current",
+          "shadowed",
+          "log-only"
+        ]
+      }
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_trace`
+
+读取围绕一个会话的已授权会话谱系，包括完整可见的祖先和后代关系。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    }
+  }
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。
+
+## `@deepseek-ai/dsh-tool-subagent`
+
+### `subagent`
+
+将一项自包含任务委派给 subagent（在自身上下文中工作的独立 agent），并返回其最终结果。可用它卸载聚焦且独立的工作，例如研究、限定范围的实现或分析，以免消耗当前对话的上下文。subagent 会运行到完成；你只会收到最终答案，而看不到中间步骤。请提供完整、独立的提示词，因为它看不到当前对话。设置 `run_in_background: true` 可返回 task id；使用 `task_output` 收集结果，使用 `task_kill` 停止任务。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string",
+      "description": "A short (3-5 word) description of the delegated task, for display."
+    },
+    "prompt": {
+      "type": "string",
+      "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
+    }
+  },
+  "required": [
+    "description",
+    "prompt"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/tool-subagent/src/index.ts)
+
+注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。
+
+## `@deepseek-ai/dsh-tool-subagent-control`
+
+### `interrupt_agent`
+
+根据 agent id 请求取消后台 agent 的当前轮次。目标可以是你的直接子级，也可以是在你下方创建的更深层 agent。只有当前轮次会停止：已经排队发给该 agent 的消息会一直搁置到后续的 send_message；它启动的 agent 会继续运行；该 agent 本身仍可接受后续操作。停止请求被接受后，此调用立即返回，因此目标可能还会短暂运行；中断一个已经完成的 agent 是可接受的空操作。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "agent_id": {
+      "type": "string",
+      "description": "The agent id of the running agent to interrupt."
+    }
+  },
+  "required": [
+    "agent_id"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
+
+### `list_agents`
+
+按持久 id 和标签列出你的可继续后台 subagent。状态来自实时注册表：running 表示 agent 此刻正在工作；idle 表示已加载但处于轮次之间，可能正在等待它启动的 agent；complete 表示它只存在于存储中。无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法读取的子级会作为诊断信息报告，而不会被静默丢弃。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "scope": {
+      "type": "string",
+      "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+      "enum": [
+        "children",
+        "descendants"
+      ]
+    }
+  }
+}
+```
+
+来源：[`packages/subagent/tool-subagent-control/src/list-agents.ts`](../packages/subagent/tool-subagent-control/src/list-agents.ts)
+
+### `send_message`
+
+根据 subagent id 向后台 subagent 发送消息，继续同一段对话。该消息会成为 subagent 的下一轮次：如果它仍在工作，消息会等待当前轮次结束，因此无法改变已经开始的工作方向。此调用不会返回 subagent 的答案，只会确认消息已投递，因此请用它分派更多工作。调用失败表示消息**未**投递。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "subagent_id": {
+      "type": "string",
+      "description": "The subagent id returned when the background subagent was started."
+    },
+    "message": {
+      "type": "string",
+      "description": "The message to deliver to the subagent."
+    }
+  },
+  "required": [
+    "subagent_id",
+    "message"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
+
+这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。
+
+## `@deepseek-ai/dsh-tool-subagent-report`
+
+### `report`
+
+向启动你的 agent 报告选定内容。你可以调用 0 次或多次，以报告进度、发现或最终答案。报告不会结束你的轮次或完成你的工作，且只有直接父级会收到。失败的调用仍可能已经送达，因此不要盲目重复。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "output": {
+      "type": "string",
+      "description": "Self-contained content for your parent; it does not see your private work."
+    }
+  },
+  "required": [
+    "output"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent-report/src/index.ts`](../packages/subagent/tool-subagent-report/src/index.ts)
+
+按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。
+
+## `@deepseek-ai/dsh-tool-tasks`
+
+### `task_kill`
+
+根据 task id 请求取消正在运行的后台任务。此调用立即返回；任务的工作真正停止后，会以 killed 状态结算。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Task id returned by the tool that started the background work."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Optional short reason, recorded in the log and forwarded to the task."
+    }
+  },
+  "required": [
+    "task_id"
+  ]
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_list`
+
+列出你的后台任务（包括正在运行和已完成的任务）及其 id、种类和状态。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_output`
+
+读取后台任务。流式任务只返回自上次读取以来的输出；最终输出任务会在结算后返回结果。每个响应都以 `[status: ...]` 结尾。读取默认不阻塞；设置 `wait: true` 后，最长等待到配置的上限。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Task id returned by the tool that started the background work."
+    },
+    "wait": {
+      "type": "boolean",
+      "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."
+    },
+    "timeout_ms": {
+      "type": "number",
+      "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+    }
+  },
+  "required": [
+    "task_id"
+  ]
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。
+
+## `@deepseek-ai/dsh-tool-todo`
+
+### `todo_write`
+
+记录并更新当前工作的结构化任务列表。每次调用都要发送**完整列表**，它会**替换**之前的列表，不支持局部更新或逐项编辑。请用它规划多步骤工作并展示进度：开始前为每个具体步骤添加一项 todo。将当前正在处理的每项 todo 标记为 `in_progress`；确实并行运行时（例如并发 subagent 或后台命令）可同时标记多项，顺序工作则标记 1 项。只要工作尚未完成，就应至少有一项任务为 `in_progress`。某项 todo 完成后立即标记为 `completed`，不要批量标记完成；只有全部工作完成后，才可以没有 `in_progress` 项。简单的单步骤任务无需使用列表。状态：`pending`（未开始）、`in_progress`（正在处理）、`completed`（已完成）。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "todos": {
+      "type": "array",
+      "description": "The COMPLETE task list, replacing any previous list.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "content": {
+            "type": "string",
+            "description": "What the task is — a short imperative line."
+          },
+          "status": {
+            "type": "string",
+            "description": "pending (not started) | in_progress (now) | completed (done).",
+            "enum": [
+              "pending",
+              "in_progress",
+              "completed"
+            ]
+          }
+        },
+        "required": [
+          "content",
+          "status"
+        ]
+      }
+    }
+  },
+  "required": [
+    "todos"
+  ]
+}
+```
+
+来源：[`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts)
+
+todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。
+
+## `@deepseek-ai/dsh-tool-workflow`
+
+### `workflow`
+
+运行用于大规模编排 subagent 的 JavaScript 工作流脚本。当工作会分散到许多相互独立的部分时，请使用此工具，例如审查大量文件、执行迁移、开展多角度研究或对发现进行对抗式验证；此时应将编排写成脚本，而不是逐轮委派。
+
+工作流的身份通过 `meta` 参数以 JSON 形式传入：必填的 `name`（简短 kebab-case）和 `description` 字符串，以及可选的 `whenToUse` 字符串和 `phases` 数组（`{title, detail?, provider?, model?}`）。`script` 参数只能是纯 JavaScript **函数体**，不能是 TypeScript，也不能包含 `export const meta` 语句；meta 是参数而非代码。脚本支持顶层 await；请以 `return <value>` 结尾，该值必须可以 JSON 序列化，并作为此工具的结果。
+
+脚本函数体提供以下钩子：
+
+- `agent(prompt, opts?): Promise<any>`：运行一个 subagent 直至完成。不提供 `opts.schema` 时，解析为子级最终文本；提供 `opts.schema` 时，它必须是以对象为根、且**只能**使用 type/properties/required/additionalProperties/items/enum/const/oneOf 的 JSON Schema，不支持 pattern/format/数值边界，此时解析为通过校验的对象。子级失败时解析为 `null`，可使用 `.filter(Boolean)` 过滤。其他选项包括 `label`（显示名称）、`phase`（进度组），以及相互独立的 `provider`／`model` LLM（大语言模型）目标覆盖项，两者可单独提供。其他任何选项（`effort`／`isolation`／`agentType`）都会明确报错。
+- `pipeline(items, ...stages): Promise<any[]>`：让每个条目分别经过各阶段，阶段之间**没有**屏障；多阶段工作优先使用它。每个阶段接收 `(prev, item, index)`。普通的阶段异常会将该**条目**变为 `null`，并跳过它的剩余阶段。
+- `parallel(thunks): Promise<any[]>`：并发运行零参数函数并等待**全部**完成。它会形成屏障，仅当某个阶段确实需要汇总全部先前结果时使用。抛出异常的 thunk 解析为 `null`。
+- `phase(title)`：开始一个进度阶段；`log(message)`：说明进度；`args`：工具调用的 `args` 输入，原样提供。
+
+如果误用钩子（参数错误、未知选项、不受支持的 schema、触发上限），抛出的错误**总会**终止脚本，绝不会退化为单个条目的 `null`。
+
+约束：并发上限和 agent 总数上限均会生效；不提供文件系统、网络、定时器或 Node.js API。具体工作由 agent 完成，脚本只负责编排。该运行在前台执行：整个脚本完成后，调用才会返回。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "script": {
+      "type": "string",
+      "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."
+    },
+    "meta": {
+      "type": "object",
+      "description": "The workflow identity block (plain JSON — never code).",
+      "additionalProperties": true,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Short kebab-case workflow name."
+        },
+        "description": {
+          "type": "string",
+          "description": "One-line description of what the workflow does."
+        },
+        "whenToUse": {
+          "type": "string",
+          "description": "Optional guidance on when this workflow applies."
+        },
+        "phases": {
+          "type": "array",
+          "description": "Optional phase declarations matched by phase() calls.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "The phase title phase() calls match by exact string."
+              },
+              "detail": {
+                "type": "string",
+                "description": "Optional one-line description of the phase."
+              },
+              "provider": {
+                "type": "string",
+                "description": "Optional provider override this phase is expected to use."
+              },
+              "model": {
+                "type": "string",
+                "description": "Optional model override this phase is expected to use."
+              }
+            },
+            "required": [
+              "title"
+            ]
+          }
+        }
+      },
+      "required": [
+        "name",
+        "description"
+      ]
+    },
+    "args": {
+      "type": "object",
+      "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "script",
+    "meta"
+  ]
+}
+```
+
+来源：[`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-web`
+
+### `web_fetch`
+
+获取指定 HTTP(S) URL 的内容，并将其解码为文本后返回。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "url": {
+      "type": "string",
+      "description": "The HTTP(S) URL to fetch."
+    }
+  },
+  "required": [
+    "url"
+  ]
+}
+```
+
+来源：[`packages/web/tool-web/src/index.ts`](../packages/web/tool-web/src/index.ts)
+
+### `web_search`
+
+在 Web 上搜索最新信息。返回可选的摘要答案和源 URL 列表。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "The search query."
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+来源：[`packages/web/tool-web/src/index.ts`](../packages/web/tool-web/src/index.ts)
+
+web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。
diff --git a/docs/tool-execution-pipeline.i18n.yaml b/docs/tool-execution-pipeline.i18n.yaml
new file mode 100644
index 0000000000..037e063125
--- /dev/null
+++ b/docs/tool-execution-pipeline.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 docs/tool-execution-pipeline.md
+tool-execution-pipeline.md: 16a4461b6c995f666882635dddb25e1a6cf79c73
+tool-execution-pipeline.zh.md: 3b5226c5ea8038c0fc5154cd37a77d92f6e3d0e1
diff --git a/docs/tool-execution-pipeline.zh.md b/docs/tool-execution-pipeline.zh.md
new file mode 100644
index 0000000000..3b5226c5ea
--- /dev/null
+++ b/docs/tool-execution-pipeline.zh.md
@@ -0,0 +1,64 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md` 重新记录配对。 -->
+
+# 工具执行流水线
+
+[English](tool-execution-pipeline.md) | 中文
+
+此图展示了策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染如何在不改变循环的前提下各就其位。可转换的扩展点是 `tools/pre-execute`、`tools/execute` 和 `tools/post-execute` waterfall（瀑布式事件）；围绕这些扩展点的边界则由所有者强制执行，包括单调守卫、由定义自身控制的 `finalizeContent`，以及 `tools/result`。
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
+  denied["denied or approval refused<br/>tool body skipped"]
+  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
+  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
+  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
+  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  allResults["Tool batch settled<br/>recorded tool/result events complete"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| guards
+  guards -->|allow| around
+  guards -->|deny| denied
+  guards -.->|throw| normalized
+  around --> toolBody
+  pre -->|deny| denied
+  pre -->|ask| approval
+  approval -->|allowed-once| guards
+  approval -->|rejected, cancelled, unavailable| denied
+  approval -.->|throw| normalized
+  denied --> post
+  pre -.->|throw| normalized
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> around
+  around --> post
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
+  final --> toolResult
+  toolResult --> presentResult
+  toolResult --> allResults
+  allResults --> context
+```
+
+文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。Code Mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/code-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。
+
+维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。
diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml
index da74ce8d7c..b387f7a0b6 100644
--- a/docs/user/develop/basic/publish.i18n.yaml
+++ b/docs/user/develop/basic/publish.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md
 publish.md: 1d1179a78c4d3a7e9e7055e3f5ee41381e28147e
-publish.zh.md: 26d1c2b737a3498bce0757d5b2d14e254fc13527
+publish.zh.md: d683762b78920dc754b6871ed7bd0caf3ee9afd4
diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md
index 26d1c2b737..d683762b78 100644
--- a/docs/user/develop/basic/publish.zh.md
+++ b/docs/user/develop/basic/publish.zh.md
@@ -2,14 +2,14 @@
 
 [English](publish.md) | 中文
 
-前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
+前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**，用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
 
-## 两个概念，两种 manifest
+## 两个概念，两种 manifest（元数据清单）
 
-安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest（元数据清单）种类不同，回答的问题也不同：
+安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest 种类不同，回答的问题也不同：
 
-- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。
-- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。
+- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是「这个包贡献什么？」：一个插入或覆盖插件行的 patch 文件。
+- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是「这套配置由哪些组合包按什么顺序组成？」。
 
 组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。
 
@@ -41,7 +41,7 @@ patch 文件的形状与你一直在写的 `--patch` overlay 相同——一个
       name: dsh-hello-plugin
 ```
 
-没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是"供插件包 import 的库"应有的形状，区别于"供用户启用的插件"。
+没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是「供插件包 import 的库」应有的形状，区别于「供用户启用的插件」。
 
 ### profile manifest
 
@@ -127,7 +127,7 @@ dsh plugin --profile demo add github:you/hello-plugin
 
   然后重新执行 `add`。
 
-请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
+请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent（智能体）运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
 
 如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
 
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 954eab633d..10e4f2429b 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/config.md
 config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
-config.zh.md: ce965dfc67c759ffcbad7b044b74abb2025851c2
+config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index ce965dfc67..621b5a75a9 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -47,7 +47,7 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务
 
 ## CLI 补丁层
 
-`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
+`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级 `$DSH_HOME/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
 
 补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
 
@@ -64,4 +64,4 @@ config:
 
 ## 精确配置参考
 
-每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
+每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力 seam](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml
index a48c5bf842..056122d1fb 100644
--- a/docs/user/guide/index.i18n.yaml
+++ b/docs/user/guide/index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/index.md
 index.md: a04698e29755d4a08b012f8b61accb79c470dcb0
-index.zh.md: 85990f49c7b3cdf7518237c6b558375b7a636243
+index.zh.md: 3808d9506fa9cb3a3e455ed478e4f02c18fc09ab
diff --git a/docs/user/guide/index.zh.md b/docs/user/guide/index.zh.md
index 85990f49c7..3808d9506f 100644
--- a/docs/user/guide/index.zh.md
+++ b/docs/user/guide/index.zh.md
@@ -2,11 +2,11 @@
 
 [English](index.md) | 中文
 
-DeepSeek Harness 是一个**插件化的 Agent 开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
+DeepSeek Harness 是一个**插件化的 agent（智能体）开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
 
 ## 它是什么
 
-Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 Agent。
+Harness 将 AI（人工智能） agent 所需的所有能力——LLM（大语言模型）调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 agent。
 
 ```yaml
 # Select the LLM backend
@@ -27,26 +27,26 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调
 
 ### 应用使用者
 
-如果你只是想用一个现成的 Agent 应用（如编程助手、对话代理），你需要的全部操作就是：
+如果你只是想用一个现成的 agent 应用（如编程助手、对话代理），你需要的全部操作就是：
 
-1. 复制一个 example 模板
-2. 填写 API key
-3. 运行
+1. 复制一个示例模板。
+2. 填写 API 密钥。
+3. 运行。
 
 不需要写任何代码。详见 [快速开始](./quickstart.md)。
 
 ### 插件开发者
 
-如果你想为 Agent 添加新能力——一个自定义 tool、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
+如果你想为 agent 添加新能力——一个自定义工具、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
 
-## 核心特性
+## 核心功能
 
 - **只需要配置** — `cordis.yml` 决定能力集合，换模型、加工具只需改一行
-- **随时替换 (HMR)** — 开发时修改插件代码，无需重启进程
+- **HMR（热模块替换）** — 开发时修改插件代码，无需重启进程
 
 ## 技术栈
 
-- **运行时**: Node.js ^22.19 或 >= 24
-- **语言**: TypeScript (ESM)
-- **框架**: Cordis
-- **包管理**: pnpm workspaces（仓库固定使用 pnpm 11）
+- **运行时**：Node.js ^22.19 或 >= 24
+- **语言**：TypeScript（ESM）
+- **框架**：Cordis
+- **包管理**：pnpm workspaces（仓库固定使用 pnpm 11）
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 38df7fb986..3795c8dcec 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
 providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
-providers.zh.md: f4a42a4093d253b4b230e4a838ba275a0ce58ac9
+providers.zh.md: 0e48c31c7006a5c9c0b014e46bc7915d625389db
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index f4a42a4093..0e48c31c70 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -2,14 +2,14 @@
 
 [English](providers.md) | 中文
 
-Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 Anthropic、OpenAI 这类内置目录里的提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
+Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 pi-ai 已安装目录中的 Anthropic、OpenAI 等提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
 
 ## 提供方从哪里来
 
 `cordis.yml` 决定装了哪些**适配器**，settings 文档决定跑哪些**提供方**。出厂组合里有两个 LLM 适配器：
 
 - `llm-deepseek` 提供 `deepseek-official` 路由，是默认可用的那个。
-- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出 provider profile，路由才注册上来；段落清空则一并撤下。
+- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出提供方 profile，路由才注册上来；段落清空则一并撤下。
 
 因此新增一个提供方通常不需要改 `cordis.yml`，写 settings 就够了——而模型页做的正是这件事。
 
@@ -120,7 +120,7 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 在 `dsh` 下，引用依次从继承环境、模型页的 `$DSH_HOME/.credentials.yaml` 存储、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析。未挂载凭据服务时，引用只读取同名环境变量。一份凭据供该路由上的所有模型使用。
 
-## 让 agent 用上新提供方
+## 让 agent（智能体）用上新提供方
 
 配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
 
@@ -133,7 +133,7 @@ api-gateway:
   reasoningEffort: high   # optional
 ```
 
-已经跑过一轮的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
+已经跑过一个轮次的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
 
 如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。
 
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index dfdba88bec..a2e09bd132 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/quickstart.md
 quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
-quickstart.zh.md: 7182f63586f4f08524c643a7c6c1ad599b2de098
+quickstart.zh.md: 4c62b0a9deda3559f29ad214903ca55aea8b970e
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index 7182f63586..4c62b0a9de 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -2,13 +2,13 @@
 
 [English](quickstart.md) | 中文
 
-本指南带你在 5 分钟内跑起一个 Agent。
+本指南带你在 5 分钟内跑起一个 agent（智能体）。
 
 ## 环境准备
 
 - [Node.js](https://nodejs.org/) ^22.19 或 >= 24
 - 通过 Corepack 使用 [pnpm](https://pnpm.io/) 11
-- [DeepSeek Platform](https://platform.deepseek.com/) API key
+- [DeepSeek Platform](https://platform.deepseek.com/) API 密钥
 
 ```sh
 node -v
@@ -16,7 +16,7 @@ corepack enable
 pnpm -v
 ```
 
-## 第一步：安装并配置 API key
+## 第一步：安装并配置 API 密钥
 
 ```sh
 git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
@@ -39,7 +39,7 @@ DEEPSEEK_API_KEY=sk-your-key-here
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
+`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
 
 ## 第三步：使用 Web UI
 
@@ -51,12 +51,12 @@ pnpm run dsh web
 
 打开 `http://127.0.0.1:3080`。agent 可以读写文件、运行命令、分配子任务和跟踪计划。可以尝试：`Create hello.js in the current directory, print "Hello from Harness!", and run it`。
 
-## 回头看
+## 运行原理
 
-`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性 runner。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
+`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性运行器。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
 
 ## 下一步
 
 - [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
 - [配置文件](./config.md) — 了解 `cordis.yml` 的格式
-- [开发插件](../develop/basic/) — 编写自己的 tool 或后端
+- [开发插件](../develop/basic/) — 编写自己的工具或后端
diff --git a/docs/web-styling.i18n.yaml b/docs/web-styling.i18n.yaml
index 0cbbafeec9..55277809ef 100644
--- a/docs/web-styling.i18n.yaml
+++ b/docs/web-styling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/web-styling.md
 web-styling.md: 5296cc7f83f712532262eadda6da098ae9f63ec7
-web-styling.zh.md: 6beec368f2f7fd5eb7606acfaae315d56899c739
+web-styling.zh.md: bec623911269cbd7020c26d5574ee88ca074b5d8
diff --git a/docs/web-styling.zh.md b/docs/web-styling.zh.md
index 6beec368f2..bec6239112 100644
--- a/docs/web-styling.zh.md
+++ b/docs/web-styling.zh.md
@@ -8,7 +8,7 @@
 
 [`ui-theme`](../packages/client/ui-theme/README.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
 
-全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现契约时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
+全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
 
 ## 组件规则
 
@@ -16,10 +16,10 @@
 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
 - 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
-- 当组件契约要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
+- 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 
 ## 变更系统
 
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式契约发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
+在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
diff --git a/examples/web-cordis/README.i18n.yaml b/examples/web-cordis/README.i18n.yaml
index 86cc276a4e..e515bf5f71 100644
--- a/examples/web-cordis/README.i18n.yaml
+++ b/examples/web-cordis/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 examples/web-cordis/README.md
 README.md: 21fe0a210b2e591a96dc254014a0f91ed9afa2ba
-README.zh.md: 35158affd5cbdd6f8fa7f5910500f21c2b241309
+README.zh.md: 660ff5f8db5d7d4e3eb8a10d842818ce9ce30e17
diff --git a/examples/web-cordis/README.zh.md b/examples/web-cordis/README.zh.md
index 35158affd5..660ff5f8db 100644
--- a/examples/web-cordis/README.zh.md
+++ b/examples/web-cordis/README.zh.md
@@ -18,4 +18,4 @@ pnpm run demo:cordis
 pnpm run demo:cordis acp
 ```
 
-这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
+这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全约定由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md) 定义。
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 039e8bb78d..25b3709d91 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
 README.md: 7589f37b174b94558bff9f74f860bb4b42705fb8
-README.zh.md: 4e99dd9313cca89e84ae0bfaf4a2179d726da864
+README.zh.md: e7b8b0ab2b5bb5bd38d7068091bc675e1d27f84a
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 4e99dd9313..e7b8b0ab2b 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -10,46 +10,46 @@
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
-| [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
-| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定表面 |
-| [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定表面 |
-| [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
-| [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
-| [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定接口 |
+| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定接口 |
+| [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定接口 |
+| [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定接口 |
+| [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定接口 |
+| [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定接口 |
 | [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
-| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
-| [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
-| [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
-| [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
-| [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
-| [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
-| [`skill/`](skill/README.md) | Skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定表面 |
-| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定表面 |
-| [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定表面 |
-| [`subagent/`](subagent/README.md) | Subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定表面 |
-| [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定表面 |
-| [`workflow/`](workflow/README.md) | 脚本 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定表面 |
-| [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定表面 |
-| [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
-| [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定表面 |
-| [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
-| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
-| [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
-| [`self-modification/`](self-modification/README.md) | agent 修改自身运行时：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)），以及受限 repository Plugin 加载 | 产品：稳定表面 |
-| [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
-| [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定表面 |
-| [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
-| [`settings/`](settings/README.md) | 用户设置 seam + 文件 provider | 产品：稳定表面 |
-| [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` provider | 产品：稳定表面 |
-| [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
-| [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
-| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定表面 |
-| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
-| [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定表面 |
-| [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定表面 |
-| [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定表面 |
-| [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定表面 |
+| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定接口 |
+| [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定接口 |
+| [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定接口 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定接口 |
+| [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定接口 |
+| [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定接口 |
+| [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定接口 |
+| [`skill/`](skill/README.md) | skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定接口 |
+| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定接口 |
+| [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定接口 |
+| [`subagent/`](subagent/README.md) | subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定接口 |
+| [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定接口 |
+| [`workflow/`](workflow/README.md) | 脚本 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定接口 |
+| [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定接口 |
+| [`spill/`](spill/README.md) | spill 能力系列：存储 seam、本地实现、工具结果 spill 策略 | 产品：稳定接口 |
+| [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定接口 |
+| [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定接口 |
+| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | 产品：稳定接口 |
+| [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定接口 |
+| [`self-modification/`](self-modification/README.md) | agent 修改自身运行时：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)），以及受限仓库插件加载 | 产品：稳定接口 |
+| [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定接口 |
+| [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定接口 |
+| [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定接口 |
+| [`settings/`](settings/README.md) | 用户设置 seam + 文件提供方 | 产品：稳定接口 |
+| [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` 提供方 | 产品：稳定接口 |
+| [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定接口 |
+| [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定接口 |
+| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定接口 |
+| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定接口 |
+| [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定接口 |
+| [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定接口 |
+| [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定接口 |
+| [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定接口 |
 | [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 |
 | [`examples/`](examples/README.md) | 演示组合包（agent-spine + CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
 | [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index 6a834cdf4d..e44c33641a 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/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/api/README.md
 README.md: 7c75e8012459266e0ce09c97416d140e5ac777e1
-README.zh.md: 87bd15fc4e5ad23ef785f7c9ee805a4aa1a35e46
+README.zh.md: f4e882570d2dc929cca466e0bdb05bb2943f2c93
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 87bd15fc4e..f4e882570d 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -9,9 +9,9 @@
 | [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.remote` |
 | [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
 
-运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 约定，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
 
 ## 已知限制与延期工作
 
-- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务契约。
+- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务约定。
 - 旧 API Proxy 仍位于 [`host/apiproxy`](../host/apiproxy/README.md)，作为尚未迁移到 Remote 的方法的回退路径。它使用由 `api-remotes` 持有的 Host resolver，使已迁移与旧方法共用同一套 Agent/Session 身份策略。
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 3f4cd32e4d..67b8b39ec1 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/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/api/gateway/README.md
 README.md: 0e1a03d2016b8cfbe165dbf1b0a9802290b29502
-README.zh.md: 6b5ccff2340405cc0045147239c5bd4f3eead7da
+README.zh.md: 3de685c18574172c8de8f2d4e94640a4b3ba193b
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 6b5ccff234..3de685c185 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约产物，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
@@ -20,7 +20,7 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
-生成的声明合并通过共享的 `TypeRTClientRemote` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+生成的声明合并通过共享的 `TypeRTClientRemote` 约定提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
 ## 模型体验
 
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index f8f7a6400b..68dbf6263f 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/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/api/remotes/README.md
 README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
-README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575
+README.zh.md: 12add6f8efc5b6af3e9b74b26a1abb2bb3936e0a
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
index 7490d68781..12add6f8ef 100644
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -8,7 +8,7 @@
 
 当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、可追踪 namespace Service、直接与作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 接口，不导入具体 Gateway。
 
-本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 约定，均可复用其 Client face。
 
 ## 构建边界
 
diff --git a/packages/bash/bash-env/README.i18n.yaml b/packages/bash/bash-env/README.i18n.yaml
index 47f4cf01cc..151e4898b0 100644
--- 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: b6f3aca41771f1ca990a4b708cd53119b8e8ad78
+README.zh.md: a67351fbc3c5aae7604f390fc9e3edd492d69fc1
diff --git a/packages/bash/bash-env/README.zh.md b/packages/bash/bash-env/README.zh.md
index b6f3aca417..a67351fbc3 100644
--- a/packages/bash/bash-env/README.zh.md
+++ b/packages/bash/bash-env/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-工具无关的 shell 环境插件：拥有 `ctx.bashEnv` 注册表，管理受信任的、每次执行收集的 `DSH_*` 变量，供模型可见的 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`DSH_HOME`、`DSH_SHELL=1`、`DSH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会响亮失败。
+工具无关的 shell 环境插件：拥有 `ctx.bashEnv` 注册表，管理受信任的、每次执行收集的 `DSH_*` 变量，供模型可见的 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`DSH_HOME`、`DSH_SHELL=1`、`DSH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会明确报错。
 
-包根导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
+包根导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
 
-## Config
+## 配置
 
 ```yaml
 - id: bash-env
@@ -15,11 +15,11 @@
     dshHome: C:\Users\me\.dsh   # default: $DSH_HOME, then ~/.dsh
 ```
 
-## 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`。
+`ctx.bashEnv` 负责收集。其他插件可以注册一个受 effect 作用域约束的 contributor，带有稳定名称、已声明的键/描述以及 `resolve(execution: ToolExecution)`；重复所有权与未声明的运行时键会明确报错，而 `list()` 只枚举声明、不执行提供方。Harness 内置键保留 `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID`；本插件的持久化翻译器通过读取与后端无关的 `sessionPersistence.locate()` seam 拥有 `DSH_SESSION_JSONL`。
 
 ```ts
 import type { Context } from 'cordis'
@@ -36,16 +36,16 @@ export function apply(ctx: Context): void {
 }
 ```
 
-覆盖层根据当前 `ToolExecution` 计算，并通过专用的 `BashExecRequest.dshEnv` 通道传递。本地执行器在合并该快照前移除所有继承的 `DSH_*`，因此嵌套 harness 与并发的父子 agent 无法泄漏过期的身份。`process.env` 永不被修改。shell 工具的描述只教授通用的 `$DSH_*` 约定，而不是点名持久化相关的变量或添加常驻的 system-prompt 段落。
+覆盖层根据当前 `ToolExecution` 计算，并通过专用的 `BashExecRequest.dshEnv` 通道传递。本地执行器在合并该快照前移除所有继承的 `DSH_*`，因此嵌套 harness 与并发的父子 agent 无法泄漏陈旧身份。`process.env` 永不被修改。shell 工具的描述只教授通用的 `$DSH_*` 约定，而不是点名持久化相关的变量或添加常驻的系统提示词段落。
 
-## Model Experience
+## 模型体验
 
-Indirectly, through the shell tools (`dsh-tool-bash`, `dsh-tool-pwsh`), which collect this registry's managed `DSH_*` snapshot into every shell-tool call.
+通过 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）间接产生影响；这些工具会把该注册表的受管 `DSH_*` 快照收集进每次 shell 工具调用。
 
 #### KV Cache effect
 
-No direct invalidation; the named consumers own any request-prefix changes.
+不会直接导致缓存失效；任何请求前缀变更均由上述消费方负责。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
-- **`list()` 只枚举 contributor 声明的变量** — 注册表自有的内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`）不包含在内，因此诊断、prompt 或 UI 代码不得把 `list()` 当作完整的环境目录。
+- **`list()` 只枚举 contributor 声明的变量** — 注册表自有的内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`）不包含在内，因此诊断、提示词或 UI 代码不得把 `list()` 当作完整的环境目录。
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index 9a0690b5c8..a3b4ec3597 100644
--- a/packages/bash/pwsh-local/README.i18n.yaml
+++ b/packages/bash/pwsh-local/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/pwsh-local/README.md
 README.md: 3e38ea3830cb651a80eaee744a42f68891767358
-README.zh.md: 8d32ce865d299bac37704e3e8730a7faa63ee108
+README.zh.md: d84a4ef4c94cd266bbb8f19bd21d7517016c50d5
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index 8d32ce865d..d84a4ef4c9 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -4,7 +4,7 @@
 
 `@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell 实现，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
 
-命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（`bash -c` 字符串域在这里没有对应物）。原生 Win32 路径（`C:\...`）原样通过。
+命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（这里不存在与 `bash -c` 字符串域对应的层）。原生 Win32 路径（`C:\...`）原样通过。
 
 包根导出默认与具名 `PwshLocalExecutor` 插件、其 `Config`、纯函数 `resolvePwshPath`/`candidatePwshPaths` 辅助函数，以及执行器注入每次 spawn 的 `ENV_OVERRIDES`/`ENCODING_PREAMBLE` 常量。
 
@@ -31,7 +31,7 @@
 - **UTF-8 输出固定**——每条命令都先以 UTF-8 设置 `[Console]::OutputEncoding` 与 `$OutputEncoding`，因此 Windows PowerShell 5.1 兜底（或任何控制台代码页非 UTF-8 的主机）不会破坏非 ASCII 输出：subprocess collector 以 UTF-8 解码字节。输入编码保持宿主默认；pwsh 7 默认为 UTF-8，不受影响。
 - **可执行文件解析**——`resolvePwshPath` 优先显式 `pwshPath`，然后在 Windows 上依次探测 PowerShell 7 安装位置、每个 PATH 条目（Microsoft Store 安装；剥离两端引号）以及作为遗留兜底的 Windows PowerShell 5.1，逐一检查 `existsSync`；其他平台回退为通过 PATH 解析的裸 `pwsh`。解析是 `(configured, env, platform)` 的纯函数，在构造时执行一次。
 - **受管进程组之上的配置预算**——`resolve()` 从配置填充 `workdir`/`timeoutMs`/`stdoutMaxBytes`，每次 spawn 都向服务提供显式字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程树终止（Windows 用 taskkill，POSIX 用进程组信号）、退出后管道排空宽限、保尾截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为单个受信调用方提高 stdout 捕获预算；stderr 与后台运行仍使用 `maxOutputBytes`。
-- **超时与取消分类**——`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号；只有执行器自身超时报告 `timedOut`，上游取消报告 `aborted`，自我终止的命令两者都不报告（见 [timeout 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。Windows 将强制终止报告为退出码 1 且无信号，因此基于信号的实情（`signal`、`killed` 状态）在那里仅限 POSIX；超时/取消分类与平台无关。
+- **超时与取消分类**——`run()` 通过一个 deadline 融合按配置上限截取的超时与调用方信号；只有执行器自身超时报告 `timedOut`，上游取消报告 `aborted`，自我终止的命令两者都不报告（见 [timeout 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。Windows 将强制终止报告为退出码 1 且无信号，因此带信号标记的事实（`signal`、`killed` 状态）在那里仅限 POSIX；超时/取消分类与平台无关。
 - **面向模型的终端环境**——`NO_COLOR=1 PAGER=cat GIT_PAGER=cat`（没有 `TERM=dumb`：那是 POSIX 概念；现代 PowerShell 渲染器遵循 `NO_COLOR`），作为普通 env 在服务的凭据清理与 `DSH_*` 通道规则之下合并；显式调用方条目仍然优先。
 - **后台进程**——`start()` 立即返回存活的 `BashProcess` 句柄，不设超时；句柄的 `readOutput()` 把服务基于偏移的 stdout/stderr 读取合并为带标记分段的增量与消费游标。仍在运行的进程属于 subprocess 服务，因此它跨执行器重载存活，并随服务销毁（被终止并 join）。一切任务形状的职责（id、所有权、轮询、通知）都在通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md) 中，由工具层把句柄注册进去——本执行器从不接触会话或注册表。
 
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index 43ff188d8d..e57f74b754 100644
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/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/tool-bash/README.md
 README.md: 47101e1198d13518c3d82877df8726c1fbf26b82
-README.zh.md: d60ac4b3826838e875f7d43bc314f62e1453c1d9
+README.zh.md: b8a0232c5b9af9ff47c17f552ca0ee606946698b
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index d60ac4b382..b8a0232c5b 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -4,9 +4,9 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具契约是 bash 方言——请挂载能解析 bash 的执行器。
+需要加载执行器实现（例如 `@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`）；结果渲染和后台进程适配仍保留在包内部。
+包根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。
 
 插件还会提供 `tool:bash` 提示词段落（顺序 105）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。
 
@@ -28,7 +28,7 @@
 
 ### 托管 shell 环境
 
-每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表契约——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
+每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表约定——贡献方注册、重复键／未声明键的明确报错、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧的身份信息，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
 
 结果文本依次包含 stdout、可选的 `[stderr]` 段落和适用的沙箱拒绝、超时、信号、退出代码及截断标记。超时与最终退出状态分别报告；非零退出仍是由模型解释的结果，不会成为 `isError`。截断结果会链接安全的完整 spill 文件，或报告文件不可用。只有 spawn 错误和中止等基础设施故障才会产生 `isError`。
 
@@ -52,7 +52,7 @@
 
 ## 逐会话模式切换
 
-对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换契约](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换约定](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 ## 模型体验
 
@@ -80,7 +80,7 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
 
 #### 模型看到的内容
 
-模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。仅当此生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。Agent 作用域的工具限制可以移除该 agent 的定义。
+模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。仅当此生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。agent 作用域的工具限制可以移除该 agent 的定义。
 
 #### Token 影响
 
diff --git a/packages/bash/tool-pwsh/README.i18n.yaml b/packages/bash/tool-pwsh/README.i18n.yaml
index 39325f5987..59e7a4991a 100644
--- a/packages/bash/tool-pwsh/README.i18n.yaml
+++ b/packages/bash/tool-pwsh/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/tool-pwsh/README.md
 README.md: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 17696fe6d908838aaaca12e8179f2ad9cb780210
+README.zh.md: 9b9dc2ff4feead06d5e592b5d0f79dc2874c8ff3
diff --git a/packages/bash/tool-pwsh/README.zh.md b/packages/bash/tool-pwsh/README.zh.md
index 17696fe6d9..9b9dc2ff4f 100644
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具契约是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
+注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具约定使用 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
 
 需要已加载的执行器实现与 `bash-env` 插件；两者都存在前工具保持 pending（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。
 
-包根只导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
+包根只导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
 
 插件还贡献 `tool:pwsh` prompt section（order 105）：非零退出以 `[exit code: N]` marker 报告，Windows 上的中断以无 signal 的 exit 1 结算。
 
@@ -24,7 +24,7 @@
 
 `command`、`workdir` 与 `timeoutMs` 在执行前经 `ctx.bash.resolve()` 按执行器配置默认值解析。workdir 默认值在工具层于 `resolve()` 之前从调用 agent 的 `session.header.cwd` 取得——每次会话的 cwd 必须来自 `exec.agent`，因为 N 个会话共享一个执行器；仅当没有会话 cwd 时执行器才回退到自己的配置 / `process.cwd()`。
 
-### Managed shell environment
+### 受管 shell 环境
 
 每次前台与后台模型 pwsh 调用都会通过共享的 [`dsh-bash-env`](../bash-env/) 注册表收到一份新收集的受信任 `DSH_*` 环境：`DSH_HOME`（Harness 主目录绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及活跃持久化后端定位到 JSONL 时的 `DSH_SESSION_JSONL`。向 `ctx.bashEnv` 贡献 `DSH_*` 事实的插件对 pwsh 调用与 bash 调用一视同仁。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；`process.env` 永不被修改。描述只教授通用的 `$env:DSH_*` 约定，而不是点名持久化相关的变量。
 
@@ -34,15 +34,15 @@
 
 当 `run_in_background` 为 true 时，本插件在 spawn 前预检 `ctx.tasks.start()`，把调用 agent 注册为 owner，并将返回的 `BashProcess` 句柄适配为通用的 cancel/done/增量输出钩子。任务运行时拥有 id、跨会话隔离、完成通知、等待与清理；本插件只把 pwsh 退出事实映射进任务输出与结果明细。`enableRunInBackground: false` 会移除参数并在执行时拒绝强制的后台调用。
 
-## UI presentation
+## UI 展示
 
 工具拥有自己的 `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
+## 模型体验
 
-### System prompt
+### 系统提示词
 
-#### What the model sees
+#### 模型看到的内容
 
 本插件注册作用域内的每个请求都包含下面的 pwsh 指引。作用域工具限制可以隐藏 schema，但不会移除这个独立注册的段落。
 
@@ -52,7 +52,7 @@
 Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure.
 ```
 
-#### Token effect
+#### Token 影响
 
 插件激活期间每次请求的固定小额输入成本。
 
@@ -60,13 +60,13 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 注册作用域与 prompt 文本不变时前缀稳定。插件激活或释放可能使该 prompt 段落的复用失效。
 
-### Tool schemas
+### 工具 schema
 
-#### What the model sees
+#### 模型看到的内容
 
-模型看到生成的 [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh)。按 agent 作用域的工具限制可以移除该 agent 的定义。
+模型看到生成的 [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh)。agent 作用域的工具限制可以移除该 agent 的定义。
 
-#### Token effect
+#### Token 影响
 
 工具可见的每个请求上的固定 schema 成本。
 
@@ -74,13 +74,13 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 可见性与工具定义不变时前缀稳定。限制或配置变更可能从首个变化 token 起使复用失效。
 
-### Foreground result
+### 前台结果
 
-#### What the model sees
+#### 模型看到的内容
 
 渲染器输出数据相关的 stdout 尾部，然后是可选的 `[stderr]` 与 stderr 尾部。条件行精确为 `[output truncated; full output: <path>]`、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空体渲染为 `(no output)`。
 
-#### Token effect
+#### Token 影响
 
 调用前零结果 token。每个流的输出有界，而每条已发出的行保留在历史中直到压缩。
 
@@ -88,13 +88,13 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 仅追加；新出现的内容跟随可复用的请求前缀，不会使既有 KV-cache 条目失效。
 
-### Background result
+### 后台结果
 
-#### What the model sees
+#### 模型看到的内容
 
 后台启动精确渲染为 `started background task <id>`；随后的读取与状态通过通用 `task_output`/`task_kill` 工具流转，包括内存截断丢弃未读字节时的 lossy 读取 spill 通知。
 
-#### Token effect
+#### Token 影响
 
 ack 是固定短行；任务输出按读取有界。
 
@@ -102,13 +102,13 @@ ack 是固定短行；任务输出按读取有界。
 
 仅追加；新出现的内容跟随可复用的请求前缀，不会使既有 KV-cache 条目失效。
 
-### Tool errors
+### 工具错误
 
-#### What the model sees
+#### 模型看到的内容
 
 校验与基础设施失败规范化为 `Error: <message>`。本包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`run_in_background is disabled for this deployment (enableRunInBackground: false)`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks` 与 `tool call aborted`。
 
-#### Token effect
+#### Token 影响
 
 只有失败的调用会新增这些保留 token；被中止的调用不产生命令输出。
 
@@ -116,9 +116,9 @@ ack 是固定短行；任务输出按读取有界。
 
 仅追加；新出现的内容跟随可复用的请求前缀，不会使既有 KV-cache 条目失效。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
 - **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
-- **PowerShell 方言契约** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
+- **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 3ae6f5427c..7885dd3280 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
+README.zh.md: a0a437437f3bb562f0a0d2bb52b1cba1df681606
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 88d1c4ad0c..a0a437437f 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -2,45 +2,45 @@
 
 [English](README.md) | 中文
 
-供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
+供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些辅助函数之上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
 
 | 导出 | 职责 |
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
 | `loadLayeredEnv(binName, cwd?, warn?)` | 构建产品 CLI（命令行界面）冻结的「继承环境 > 项目 `.env` > 用户 `.env`」快照，拒绝文件中的 bootstrap-only 变量，并在不替换继承值的前提下物化其余文件值 |
-| `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
-| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
+| `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader 拒绝转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
+| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的清理函数只会延迟致命退出，而不会取消它 |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
 | `loadOptionalPatches(binName, file)` | 解析一份可选的 patch 列表文件（即 profile 的 `cordis.patch.yml`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析一份形状相同的必需 patch 列表文件；文件缺失同样抛出异常，因为该文件是调用方指名的 |
 | `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
-| `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
+| `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步清理函数 |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时释放部分构造的上下文，并返回带标签的拒绝结果 |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
-Loader 结算会在导入或生命周期失败时 reject，并携带失败的配置项与阶段；`boot()` 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
+Loader 结算会在导入或生命周期失败时返回拒绝结果，并携带失败的配置项与阶段；`boot()` 会释放部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
 
-Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间处理函数保持注册并加闩：被报告的始终是第一个 rejection，后续 rejection（包括拆卸自身的）会被吞掉，而不会变成未捕获错误、在拆卸中途杀死进程。
+Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间，处理函数保持注册并处于锁定状态：被报告的始终是第一个 rejection，后续拒绝（包括拆卸自身产生的拒绝）会被忽略，而不会变成未捕获错误、在拆卸中途杀死进程。
 
-配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包（package））通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与 host 会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个已交付的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
+配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包）通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与宿主会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个随附的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
 
-此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
+此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md) 持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
 
-## Profile
+## Profiles
 
-profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
+profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则明确报错。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会明确报错（即 `dsh plugin` 路径）。
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
 - **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝 [bootstrap-only 文件变量](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision)，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
-长期运行的 surface 会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+长期运行的界面会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，监视器仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离观察方的失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
 
 ## 模型体验
 
@@ -48,11 +48,11 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 
 #### KV Cache 影响
 
-`boot()` 不会直接使缓存失效；消费方调用 `addHarnessSourceSection` 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效。请求前缀的其他任何变化均由相应的具名消费方持有。
+`boot()` 不会直接使缓存失效；消费方调用 `addHarnessSourceSection` 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效。请求前缀的其他任何变化均由相应的具名消费方负责。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
-- **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
+- **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生辅助组件；没有该辅助组件的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
 - **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境发现以启动为界**：`loadLayeredEnv` 只读取一次调用目录与 Harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
 - **用户 patch 层采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 98df59d988..860390d722 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/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/bundle/README.md
 README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: ef2027e347b79e14574ba1164aa9fddd364327e9
+README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index ef2027e347..b965664978 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 约定](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index f1a9d53be8..bc15c88a24 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
 README.md: 661b377817482d22f58f22b573075722646729a2
-README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
+README.zh.md: 8d3ed1c0f99b9245d27c68887aa7b2301368a17b
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index a6b91a8e60..8d3ed1c0f9 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -15,4 +15,4 @@ dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 ## 已知限制与延期工作
 
 - **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
-- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时大声失败，直到宿主提供该 seam。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该 seam。
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 7662182df0..0130cf36e5 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/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/bundle/web-app/README.md
 README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: 0ffc5cdaf1a98e5df11ef042c7d15a994515c170
+README.zh.md: c9fc86522da9c6b2ea79d1d079c71e5b26007f0a
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index 0ffc5cdaf1..c9fc86522d 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -10,7 +10,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### 模型看到的内容
 
-当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
+当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新约定，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
 
 #### Token 影响
 
@@ -22,5 +22,5 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 ## 已知限制与延期工作
 
-- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时大声失败并给出构建提示；没有从源码直接服务的回退路径。
+- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时明确报错并给出构建提示；没有从源码直接服务的回退路径。
 - **`lanAddresses` 是启动期快照**：启动后的网卡变化不会重新公告；打印的 LAN URL 始终与配置的信任栅栏一致。
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index 2ce3e44fa7..997063b3bb 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/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/client/README.md
 README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
-README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139
+README.zh.md: a3fe1a978de7ab5935ec527d115278703cbebcd4
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index edd378bf80..a3fe1a978d 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 UI 服务和特性插件。编写规则见 [AGENTS.md](AGENTS.md)；宿主半侧是 [`host/`](../host/README.md)。除 `test-runtime` 外，均为命名成 `@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>` 的**产品**包。
 
 | 包 | 目的 |
 |---|---|
@@ -14,15 +14,15 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`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 的方式。 |
+| [`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-tool/`](ui-tool/README.md) | 编排 Tool 调用树和按 Tool 键控的视图。 |
+| [`ui-tool/`](ui-tool/README.md) | 编排工具调用树和按工具键控的视图。 |
 | [`ui-goal/`](ui-goal/README.md) | 展示和管理当前目标。 |
 | [`ui-trajectory/`](ui-trajectory/README.md) | 提供 agent（智能体）活动的其他视图。 |
 | [`ui-command/`](ui-command/README.md) | 提供会话感知的命令发现与分发。 |
@@ -37,6 +37,6 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-settings-general/`](ui-settings-general/README.md) | 提供常规设置分区。 |
 | [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
 
-每个子文档负责自身的契约和详细行为。[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)负责跨包组合与加载决策。
+每个子文档负责自身的约定和详细行为。[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)负责跨包组合与加载决策。
 
 子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index ddfda12f4e..57d4c4c75c 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
 README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
-README.zh.md: d17012cc89c02a1b11f16d126b7c0cafe67fb2a0
+README.zh.md: 731daa15c8944febae1712788a9ae017d4756960
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index d17012cc89..731daa15c8 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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 不参与引导的组合。这道栅栏是可达性策略，而不是认证；Web 载体不提供认证层。决策记录：[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 下行
 
diff --git a/packages/client/test-runtime/README.i18n.yaml b/packages/client/test-runtime/README.i18n.yaml
index 26845c1d5c..7c67e91f5d 100644
--- a/packages/client/test-runtime/README.i18n.yaml
+++ b/packages/client/test-runtime/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/client/test-runtime/README.md
 README.md: 74da8fde7fd9cc3733d2d1ae03dd3d213e4d553e
-README.zh.md: a86b9e469a5632886891628267002a14588afeaa
+README.zh.md: 1df28f7b25c35333e91476e10480c22a728cdab3
diff --git a/packages/client/test-runtime/README.zh.md b/packages/client/test-runtime/README.zh.md
index a86b9e469a..1df28f7b25 100644
--- a/packages/client/test-runtime/README.zh.md
+++ b/packages/client/test-runtime/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-面向 client feature 测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。feature 套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。
+面向客户端功能测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。功能套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。
 
-替身实现的正是 feature 经 ctx 拿到的对外面（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
+替身实现的正是功能通过 ctx 获得的对外接口（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
 
 局部 DOM 快照：`declare(children)` 注册自动 frame，逐 key 的 `<div data-slot>` 包裹层即快照根；`renderSlot(key, owner)` 返回该 slot 的局部视图（container、限定范围的 Testing Library 查询、原位 `update(owner)`）；注册的快照序列化器把 CSS-module 哈希类名折回语义名（`_frame_a1b2c3` → `frame`）保持 `.snap` 只含结构，并把 `<svg>` 内部折叠为 `data-content` 指纹。需要自定义页面 frame 的套件改用 `root.declare(children, Frame)`；`mount(plugin)` 在真实 fiber 上运行并对缺失服务先行报错；`dispose()` 沿单一轴拆除视图、feature fiber、已铸 scope 与持久化 store 状态。
 
 不属于产品插件图（无 `dshClient`）；feature 包仅以 `devDependencies` 依赖之。
 
-## Model Experience
+## 模型体验
 
 无；本包是浏览器侧测试基础设施，无一物到达模型请求。
 
 #### KV Cache effect
 
-无；本包既不组装也不发送 provider 请求。
+无；本包既不组装也不发送提供方请求。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
 - **仅可经仓内源码别名消费。** spec 通过 tsconfig `paths` 解析到 `src`；构建产物 `lib/` 再导出 `@deepseek-ai/dsh-client-runtime/client`，而该 bundle 是无 Node ESM 导出的浏览器 loader 脚本，故 `lib/index.js` 在纯 Node 下不可导入。所有消费方都是仓内 Vitest 套件；不存在 Node 兼容的运行时入口。
 - **会话快照是 fixture 数据，不是重放历史。** `updateSnapshot` 直写快照 store；wire 到快照的运算仍由 runtime 包自身测试与 replay e2e 把守。因此 fixture 可以表达生产投影永不产出的状态。
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 822a02d321..a8c91a28b7 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
 README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
-README.zh.md: 90c4dc4cc169b2cbcd7e94275a692e3d062cfe98
+README.zh.md: 74b2c0d47e8ab103363881535df00831adbed89a
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 90c4dc4cc1..74b2c0d47e 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。Tool 展示属于 [`ui-tool`](../ui-tool/README.md)。
+会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。工具展示属于 [`ui-tool`](../ui-tool/README.md)。
 
 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份契约里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份约定里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的提示词。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
@@ -18,19 +18,19 @@
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
-聊天视图保留 Tool 的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体 Tool 席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
+聊天视图保留工具的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体工具席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
 
 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。
 
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
 
-`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` Tool 行属于 [`ui-tool`](../ui-tool/README.md)。
+`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` 工具行属于 [`ui-tool`](../ui-tool/README.md)。
 
 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。
 
 Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。QueueDock 会将其过滤掉，ChatView 则把它投影为会话流末尾带复制操作的用户样式气泡；非用户来源的 next-step 项（注入上下文）改以 `context` placement 广播，领取前不在任何界面渲染。与所有用户样式气泡一样，这里不显示 fork。Host 会等携带该 steering 的持久 `user/message` 进入 mux 流之后再退役 steering。客户端运行时接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史事件无法隐藏后来复用同一 `MessageId` 的单次入队项。气泡交接时因而不会产生空档或重复，会立即从持久节点恢复复制操作与时钟——steering 气泡与 user 气泡一样不带分支操作（[决策](../../../.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)）——并能在重连后从同一权威恢复。
 
-键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 契约：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
+键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 约定：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
@@ -60,4 +60,4 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。
 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。
 - **Queue 编辑仅支持文本**：包含非文本块的行仍显示扁平化预览，但由于内联编辑器无法保留这些块，其编辑控件会被禁用。文本行进入编辑模式后，删除和严格 steering（中途引导）操作会被保存和取消取代；Enter 保存，Escape 取消。
-- **Queue 严格 steering 会保留完整消息**：Agent 运行期间，steering 操作会以原子方式把所寻址的 Queue 单次入队项转移到当前 next-step 窗口。包含混合内容的行仍可使用此操作，因为它会转发不可变消息，而非文本投影。带 placement 的 Host 快照会在会话流末尾渲染待处理 steering，直到已消费的 `user/message` 折叠进持久 transcript（文本记录），因此立即展示、重连和回放共享同一个线性权威。
+- **Queue 严格 steering 会保留完整消息**：agent 运行期间，steering 操作会以原子方式把所寻址的 Queue 单次入队项转移到当前 next-step 窗口。包含混合内容的行仍可使用此操作，因为它会转发不可变消息，而非文本投影。带 placement 的 Host 快照会在会话流末尾渲染待处理 steering，直到已消费的 `user/message` 折叠进持久 transcript，因此立即展示、重连和回放共享同一个线性权威。
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index 7c2cb356ec..e9810d98da 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/client/ui-deliverables/README.md
 README.md: 189dedd88fed6914012204118ccdf9bdd0cd3bb2
-README.zh.md: bfcec3c54602533028942ed167b9526eaf3ca959
+README.zh.md: ba493549bd0bc3f8a2adbda5989448e497f0af93
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index bfcec3c546..ba493549bd 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-产物文件的功能属主：把"完成的一轮以其产出文件收尾"的产物行注册进 chat 视图的 `conversation.chat.turnTail` 空位。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该交互面，属主视图以零成本渲染一个空的空位。
+产出文件功能的属主：把已完成轮次末尾的产出文件行注册到 chat 视图的 `conversation.chat.turnTail` slot 中。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该界面，属主视图无需额外开销即可渲染空 slot。
 
-`producedForClosing` 从 tail 空位的 owner 通货——定稿的快照节点与收尾 assistant 的 seq——推导一轮产出的文件。词表是改写工具自身的跟随 `locations`，绝不是收尾正文：无论模型是否记得点名，产出文件都会被列出。改写按渲染意图识别而非工具名——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此新的改写工具靠声明自己做了什么加入。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
+`producedForClosing` 根据 tail slot 属主提供的当前数据，即定稿快照节点和收尾助手的 seq，推导一个轮次产出的文件。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在轮次边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
 
-`ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
+`ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个低调的标签、至多六个标签项（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每个标签项经由属主提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
-收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及保留 code 胶囊并采用 markdown 样式表的链接语言——静止为链接蓝、悬停出下划线，与 URL 提升的行内代码完全一致——完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
+收尾正文承载同一份词表。本插件提供供 chat 视图按收尾消息查询的 `chatFileMentions` 服务：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享同一 basename 时，文本保持不可点击而不作猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及保留代码标签，并采用 Markdown 样式表的链接样式：静止时为链接蓝色，悬停时显示下划线，与 URL 提升的行内代码完全一致——完整路径作为其 `title`；提及绝不会渲染在链接内部或流式文本中。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
 
 ## 模型体验
 
@@ -20,4 +20,4 @@
 
 ## 已知限制与暂缓事项
 
-- **提及匹配只认精确路径或唯一 basename。**后缀式提及（`out/index.html` 写作 `index.html` 可解析；`deep/out/index.html` 写作 `out/index.html` 则不行）保持死文本；放宽匹配器等真实的收尾消息形态需要时再做。
+- **提及匹配只认精确路径或唯一 basename。**后缀式提及（`out/index.html` 写作 `index.html` 可解析；`deep/out/index.html` 写作 `out/index.html` 则不行）保持不可点击；等真实的收尾消息形态产生需求后再放宽匹配规则。
diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml
index 9c61e62c48..8d7a5f1d4b 100644
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/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/client/ui-settings-general/README.md
 README.md: ab27e073dc76335efc619f56365d1705007f7ef2
-README.zh.md: 18bbecf67f51ae63bfacd4ba78437bea95b50bee
+README.zh.md: 16ff5604bee5425569b783e27a29699344f630e3
diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md
index 18bbecf67f..16ff5604be 100644
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -4,9 +4,9 @@
 
 设置界面无特定功能归属的文案与产品引导插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容、本地配置文件操作，「通用」分区及其 `settings.general.item` slot、`settings` 字典，以及第一个有序欢迎步骤。归具体功能所有的行（「权限」、「语言」、「外观」）、分区（「模型」）和条件式首次使用引导步骤仍由各自的功能包提供。
 
-回环浏览器通过 `settings.describe` 加载提供方的 `hasDocument` 能力，且只有在 Host 确认可准备好一份由提供方持有的本地文档时才渲染**打开配置文件**。该操作发送无路径参数且仅限回环访问的 `settings.openDocument` 请求；Host 会再次解析提供方路径、在文档缺失时将其创建出来，并交给原生文本编辑器（macOS 上使用 `open -t`，绕过浏览器文件关联；Linux 和 Windows 上使用桌面文件关联；WSL 上经 `wslpath -w` 转换后使用 Windows 文件关联）。打开失败时该操作仍可使用，并渲染本地化错误。临时读取失败或 Host 拓扑变化后，重新打开对话框或重新连接会刷新可用性。远程浏览器从不注册该操作，也从不发起这项特权 settings 读取。
+回环浏览器通过 `settings.describe` 加载提供方的 `hasDocument` 能力，且只有在 Host 确认可准备好一份由提供方持有的本地文档时才渲染**打开配置文件**。该操作发送无路径参数且仅限回环访问的 `settings.openDocument` 请求；Host 会再次解析提供方路径、在文档缺失时将其创建出来，并交给原生文本编辑器（macOS 上使用 `open -t`，绕过浏览器文件关联；Linux 和 Windows 上使用桌面文件关联；WSL 上经 `wslpath -w` 转换后使用 Windows 文件关联）。打开失败时该操作仍可使用，并渲染本地化错误。临时读取失败或 Host 拓扑变化后，重新打开对话框或重新连接会刷新可用性。远程浏览器从不注册该操作，也从不发起这项特权设置读取。
 
-`src/onboarding-copy.ts` 是完整通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文文案。宿主端在 user-settings seam 中注册 `ui-onboarding`。loopback 浏览器会比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。非 loopback 浏览器不能访问受保护的 settings API：它仍会显示通知，但「继续」只推进当前浏览器进程，重新加载后会再次显示通知。版本不同时，系统也会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
+`src/onboarding-copy.ts` 是完整通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文文案。宿主端在用户设置 seam 中注册 `ui-onboarding`。回环浏览器会比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。非回环浏览器不能访问受保护的设置 API：它仍会显示通知，但「继续」只推进当前浏览器进程，重新加载后会再次显示通知。版本不同时，系统也会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
 
 ## 模型体验
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 97008e3e0c..edc17bb0f8 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
 README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
-README.zh.md: f4e8044fe6e10e1fbdfb70987efe07c884fa9ac8
+README.zh.md: 2e6674480fda93a8e3f83fdbddb798880a546335
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index f4e8044fe6..2e6674480f 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
+客户端工具展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的根调用；本包渲染该根调用及其 Code Dispatch 子调用，并通过键控 slot `tool.call.toolview` 分发每个原子调用。未注册的工具名称使用通用卡片。
 
-业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
+业务 UI 包只注册协议中的工具名称和原子视图，不配对会话事件、不重建 transcript，也不负责根调用与子调用的拓扑。运行时继续负责调用与结果的配对、生命周期和递归 `subCalls` 投影；对话视图继续负责在 ChatFlow 中的位置。
 
-## 渲染契约
+## 渲染约定
 
-`ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
+`ToolCallTree` 接收一个已经包含递归 `subCalls` 的根 `ToolCallBlock`、选中状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准调用块，让根调用与任意深度的子调用经过同一条原子分发路径，不再订阅独立的父子映射。
 
-每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
+每个根调用和子调用的包装层都保留 `conversation.chat.tool` 的调用锚点 DOM 约定，供分页和 selection 使用。
 
-本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
+本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行渲染器与详情渲染器为 `terminal`、`read`、`diff`、`search` 和 `web` 渲染意图共用同一组纯卡片模型。未知的意图标签和格式错误的协议卡片数据都会回退为展平的工具结果文本。
 
-通用行把已知 Tool 名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取 Session service。
+通用行把已知工具名称归类为搜索、读取、shell、写入、编辑、代码或通用变体。运行中、成功、失败和中断状态只来自冻结的调用／结果切片。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取会话服务。
 
-## 原子 Tool 视图
+## 原子工具视图
 
-业务所有方把自己的 wire Tool 名称注册进 `tool.call.toolview`：
+业务属主把自己的协议工具名称注册到 `tool.call.toolview`：
 
 ```ts ignore-check
 ctx.slots.inject('tool.call.toolview', () =>
@@ -28,22 +28,22 @@ ctx.slots.inject('tool.call.toolview', () =>
   }, BusinessToolRow))
 ```
 
-owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd`，以及普通的 `openFile`／`inspect` 回调。注册项会收到正常的 Session slot runtime share，但不会收到 React node、Runtime service 或 root/subcall 知识。
+属主载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd`，以及普通的 `openFile`／`inspect` 回调。注册项会收到标准的会话 slot 运行时共享数据，但不会收到 React 节点、运行时服务或根调用／子调用拓扑信息。
 
-本包当前拥有 generic fallback，以及 bash/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
+本包当前负责通用回退，以及 bash/pwsh、读取、写入／编辑、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
 
-各类卡片的上限与 fallback 规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) Note 负责。
+各类卡片的上限与回退规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) Note 负责。
 
 ## 模型体验
 
-无，因为本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
+无，因为本包只渲染已经记录的工具调用和结果，不改变模型请求、工具执行或会话事件。
 
 #### KV Cache 影响
 
-无。本包只负责 Client 展示。
+无。本包只负责客户端展示。
 
 ## 已知限制与后续工作
 
-- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 契约已为未来的嵌套生产者做好准备。
-- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时／UI 约定已为未来的嵌套生产方做好准备。
+- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过键控 slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml
index 047513c346..1a1dd057f0 100644
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/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/client/ui-workspace/README.md
 README.md: 1ec07bd41e72bb5a26b2cfc3bf90e57e7d92db08
-README.zh.md: 18d9e356a9e5deb38624f377d41b2fc8bc677294
+README.zh.md: 8edd0fed6d3bdefd9df339a8b3d0588533264538
diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md
index 18d9e356a9..8edd0fed6d 100644
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -2,25 +2,25 @@
 
 [English](README.md) | 中文
 
-共享 Workspace 浏览器与选择器插件。`WorkspaceBrowser` 填充侧边栏的 `sidebar.workspaces` slot，`WorkspacePicker` 则填充页面局部 Session Intent 主视觉区的 `conversation.hero.workspace` slot；两个表层使用同一套 Workspace 菜单和添加流程。
+共享 Workspace 浏览器与选择器插件。`WorkspaceBrowser` 填充侧边栏的 `sidebar.workspaces` slot，`WorkspacePicker` 则填充页面局部 Session Intent 主视觉区的 `conversation.hero.workspace` slot；两个界面使用同一套 Workspace 菜单和添加流程。
 
-该浏览器通过全局运行时钩子将 Session 行渲染为分组或扁平形式，并负责 Workspace 添加／重命名和 Workspace 内的重排序流程。非空白查询会以单一扁平结果列表替代任一浏览模式：不区分大小写的标题和 Workspace 子串匹配项会立即显示，经 250 ms 防抖的 Host 请求则会加入经过排序的当前对话内容匹配项及其摘要片段。英文搜索输入框及其防御性请求路径会移除 NUL，将查询限制在传输 schema 规定的 500 个 UTF-16 code unit 内且不会拆分 surrogate pair，并保留现有的防抖与取消行为。每次新查询都会中止前一个请求；内容搜索失败时，元数据匹配项仍会显示，同时给出警告。列表最多显示 20 条结果，并会在查询过宽时提示用户缩小范围；打开所选 Session 时既不会清除查询，也不会跳转至特定事件。
+该浏览器通过全局运行时钩子将 Session 行渲染为分组或扁平形式，并负责 Workspace 添加／重命名和 Workspace 内的重排序流程。非空白查询会以单一扁平结果列表替代任一浏览模式：不区分大小写的标题和 Workspace 子串匹配项会立即显示，经 250 ms 防抖的 Host 请求则会加入经过排序的当前对话内容匹配项及其摘要片段。英文搜索输入框及其防御性请求路径会移除 NUL，将查询限制在传输 schema 规定的 500 个 UTF-16 代码单元内且不会拆分代理项对，并保留现有的防抖与取消行为。每次新查询都会中止前一个请求；内容搜索失败时，元数据匹配项仍会显示，同时给出警告。列表最多显示 20 条结果，并会在查询过宽时提示用户缩小范围；打开所选 Session 时既不会清除查询，也不会跳转至特定事件。
 
-该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。不同的规范路径即使 basename 和显示标题相同，仍会作为由 id 区分的独立 Workspace；侧边栏的悬停详情会显示完整路径。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **添加工作区…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为，此时侧边栏区头直接不渲染添加按钮，而非留下一个点了没反应的按钮）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。添加只有一条路径：占用者自带的新建文件夹能力已经覆盖了全新目录，因此不再单设按名称创建的对话框。菜单只在确有多个目标可选时出现——没有 Workspace 可列时，锚点手势直接拉起流程，而不是弹出只有一行的浮层；在列表基线落地前，空列表不算最终结果。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。Session 行内的 Archive 操作不经确认对话框直接提交（非破坏性：日志和 workspace 记账席位保持不变），通过 `ctx.workspaces.archiveSession` 归档；归档集合回声落地后，该行从所有分组视图——workspace 分组、Ungrouped、内容搜索和平铺列表——中消失，失败只作为控制台诊断输出，树保持不变。blank「新会话」行是纯占位：不渲染行菜单和时间标签（其中还没有发生任何事），rename/fork/归档都从首条 prompt 落地后才可用。
+该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。不同的规范化路径即使 basename 和显示标题相同，仍会作为由 id 区分的独立 Workspace；侧边栏的悬停详情会显示完整路径。每个注册各自声明一个**目录流子 slot**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **添加工作区…** 操作仅在当前界面的 slot 被占用时渲染（每次菜单渲染读取占用状态；slot 为空意味着该组合没有目录选择能力——seam 文档化的无流程默认行为，此时侧边栏区头直接不渲染添加按钮，而非留下一个点了没反应的按钮）。本包持有触发与接纳：占用方通过 slot 的属主交互约定（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。添加只有一条路径：占用者自带的新建文件夹能力已经覆盖了全新目录，因此不再单设按名称创建的对话框。菜单只在确有多个目标可选时出现——没有 Workspace 可列时，锚点手势直接拉起流程，而不是弹出只有一行的浮层；在列表基线落地前，空列表不算最终结果。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。Session 行内的 Archive 操作不经确认对话框直接提交（非破坏性：日志和 workspace 记账席位保持不变），通过 `ctx.workspaces.archiveSession` 归档；归档集合回声落地后，该行从所有分组视图——workspace 分组、Ungrouped、内容搜索和平铺列表——中消失，失败只作为控制台诊断输出，树保持不变。空白的「新会话」行只是占位符：不渲染行菜单和时间标签（其中还没有发生任何事），重命名、fork 和归档都从首条提示词落地后才可用。
 
 Workspace 和 Session 悬浮卡片会复制对应行被截断的值：激活 Workspace 卡片会写入其完整目录路径，激活非空白 Session 卡片则会写入其完整显示标题。临时的空白「新会话」卡片保持只读，因为其本地化标签是占位文案，并非会话内容。只有浏览器接受剪贴板写入后，卡片才会显示由字典提供的已复制状态。
 
-Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork，在 client 端递增继承的持久化标题后再打开子会话；尾部半角或全角括号编号会原样式递增，无编号标题追加 ` (1)`。源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。Fork 或改名失败都不会改变当前选中项，改名失败时已创建的子会话仍会留在列表中。
+Session 行内的 fork 操作在源会话最后一个已完成轮次处 fork，在客户端递增继承的持久化标题后再打开子会话；尾部半角或全角括号编号会原样式递增，无编号标题追加 ` (1)`。源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。Fork 或改名失败都不会改变当前选中项，改名失败时已创建的子会话仍会留在列表中。
 
 Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**等待审批**，计划审阅显示**计划待审**，普通问题显示**等待回答**。每个待处理交互都使用一枚琥珀色警告点，优先级高于运行指示器；普通行的悬浮卡片重复显示本地化状态，普通行和搜索结果行则都以相同文本提供面向辅助技术的视觉隐藏标签。运行状态使用蓝色指示器及其隐藏标签；空闲行会保留空的状态槽位。
 
 两个目标 slot 都由其他插件声明，因此 `apply` 使用 `slots.inject()` 在各自的声明生命周期内完成注册，并在目标 slot 的声明恢复后重新注册。
 
-共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互优先于会话自身的运行中状态，二者无论哪一项存在都会保持为行的主要状态，而后代活动仍作为独立的悬停与无障碍状态保留。两者均不存在时，后代活动优先于绿色的未查看完成提醒；最后一个运行中的后代停止后，该提醒会重新出现。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
+共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选父级的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互优先于会话自身的运行中状态，二者无论哪一项存在都会保持为行的主要状态，而后代活动仍作为独立的悬停与无障碍状态保留。两者均不存在时，后代活动优先于绿色的未查看完成提醒；最后一个运行中的后代停止后，该提醒会重新出现。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
 
 ## 模型体验
 
-无。选择器属于浏览器 chrome；这里没有任何内容进入模型请求。
+无。选择器属于浏览器界面；这里没有任何内容进入模型请求。
 
 #### KV Cache 影响
 
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index beeeef0ffd..34c5ffc794 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/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/credentials/credentials/README.md
 README.md: 95ef76d145727340d8135bf1d48babd6d8adb882
-README.zh.md: b3404858025d4ec53a76548c78c1808d2c858844
+README.zh.md: dce426fde734e3368317ccd2fa6848ca1e00048e
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index b340485802..dce426fde7 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -4,13 +4,13 @@
 
 抽象凭据 seam（`ctx.credentials`）。一条准则，三个推论：
 
-**配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据 provider 所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
+**配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据提供方所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
 
 **消费方按操作解析。** `resolve(ref)` 在每个操作开始时调用（LLM 适配器每次模型请求解析一次），绝不跨操作缓存——正是这次读取让改过的凭据无需重启任何插件就作用于下一次请求。
 
 **空的存储值等于不存在。**处处如此：`resolve` 跳过它，`describe` 报告未配置。空白永远不会伪装成已配置的机密。
 
-## 接口面
+## 接口
 
 ```ts
 import type { Context } from 'cordis'
@@ -25,24 +25,24 @@ await ctx.credentials.set(ref, 'sk-…')                   // rejects while a re
 await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
 ```
 
-`credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
 
-`set`/`unset` 的遮蔽规则是刻意的响亮失败：当只读来源（本地 provider 中即活跃进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
+`set`/`unset` 的遮蔽规则是刻意设计为明确报错：当只读来源（本地提供方中即当前进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
 
-## Providers
+## 提供方
 
-[`dsh-credentials-local`](../credentials-local/README.md) 把继承的进程环境叠加在其受管 `$DSH_HOME/.credentials.yaml` 文档之上，并以启动器的项目和用户 `.env` 层作为后备。seam 形状为 keyring、辅助命令、KMS 后端的 provider 留好了位置；远端 settings provider 永远不必携带机密。
+[`dsh-credentials-local`](../credentials-local/README.md) 把继承的进程环境叠加在其受管 `$DSH_HOME/.credentials.yaml` 文档之上，并以启动器的项目和用户 `.env` 层作为后备。seam 形状为 keyring、辅助命令、为 KMS 后端提供方留好了位置；远端设置提供方永远不必携带机密。
 
-## Model Experience
+## 模型体验
 
-经由消费它的 LLM 适配器间接生效：解析出的值为适配器的提供方请求授权，每个模型可见面都归适配器所有。
+经由消费它的 LLM 适配器间接生效：解析出的值为适配器的提供方请求授权，所有模型可见接口都由适配器负责。
 
 #### KV Cache effect
 
 无直接失效；凭据绝不进入请求前缀。
 
-## Known Limitations and Deferred Work
+## 已知限制与暂缓事项
 
 - **不提供枚举**——seam 只回答被问到的引用；配置界面从 settings schema 得知引用集合，`list()` 没有当前消费方。
-- **引用限定为环境变量形状**——在有 provider 需要更丰富寻址前，保持单一扁平的 POSIX 标识符命名空间。
+- **引用限定为环境变量形状**——在有提供方需要更丰富的寻址方式前，保持单一扁平的 POSIX 标识符命名空间。
 - **进程环境变化不可见**——不可能为其发事件；界面只能在自身导航时重新读取 `describe()`。
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index d0fe492135..fce2946cff 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/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/feedback/README.md
 README.md: af8e9d5c4903594299284d09f880aa8929f5e051
-README.zh.md: 01a26798d0b7dc8b376929252a60a99fff11b640
+README.zh.md: 9156ff1c8da8ed1128488fcacaf454425468163a
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index 01a26798d0..9156ff1c8d 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-feedback 家族让人类记录对会话的评价，但不据此采取任何动作。反馈属于持久的会话日志内容，与模型对话以及后续可能读取它的任何策略相互独立。
+反馈家族让人类记录对会话的评价，但不据此采取任何动作。反馈属于持久的会话日志内容，与模型对话以及后续可能读取它的任何策略相互独立。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 
-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
+被记录的评价仅写入日志：它绝不会进入模型接口或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index 20eb2741d6..3267e4e515 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/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/feedback/command-feedback/README.md
 README.md: e2eb6d4cf2b40e83efad1fa158edd72578658f56
-README.zh.md: f87067d67cf9dcb8f4da97afe3a9d59eb828faf7
+README.zh.md: 607a117a00cd0abd49c3a338256b65a2b958e73e
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index f87067d67c..607a117a00 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -4,7 +4,7 @@
 
 与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
@@ -15,9 +15,9 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集契约。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或宿主集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集约定。
 
-反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
+反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序接口、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
 权威记录是该事件，而不是命令记录，因为反馈可能来自 `/feedback` 之外的触发方式。让载荷不进入 `command/run`，可避免两条记录携带相同文本。
 
@@ -32,7 +32,7 @@
   name: '@deepseek-ai/dsh-command-feedback'
 ```
 
-随附的 `dsh` 基础组合无条件挂载此命令；它没有配置，也不依赖持久 goal 栈。Web 客户端通过命令适配器暴露该命令。无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器，因此不会暴露它。
+随附的 `dsh` 基础组合无条件挂载此命令；它没有配置，也不依赖持久目标栈。Web 客户端通过命令适配器暴露该命令。无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器，因此不会暴露它。
 
 ## 模型体验
 
@@ -40,7 +40,7 @@
 
 #### 模型看到的内容
 
-无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志且不携带 `surfaceOp`，因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
+无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志，且不携带 `surfaceOp`，因此它们绝不会进入有序接口、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
 
 #### Token 影响
 
@@ -50,10 +50,10 @@
 
 与模型请求路径无关。记录只追加到会话日志，不触碰已经可复用的请求前缀。本包贡献的任何内容都不会使缓存复用失效。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
 - **没有反馈检索或管理 surface**：可选的 OTel 插件仅将该事件用作共享触发器。本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。
 - **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
-- **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
+- **不支持修改或撤回**：会话日志是仅追加的，本包也不新增删除标记，因此错误的条目会一直保留在记录中，只能由后续条目取代。
 - **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
 - **随附的产品入口中只有 Web 使用此命令**：无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器，因此 `/feedback` 在那里不可用。
diff --git a/packages/fs/tool-str-replace-editor/README.i18n.yaml b/packages/fs/tool-str-replace-editor/README.i18n.yaml
index 7d08a33f9a..b6733eb3b8 100644
--- a/packages/fs/tool-str-replace-editor/README.i18n.yaml
+++ b/packages/fs/tool-str-replace-editor/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/fs/tool-str-replace-editor/README.md
 README.md: 97e9e0ab9ade7c7241c1aac3e2489e055d01ff8f
-README.zh.md: 48358eb3c9d81ddad6a83c4ff3ef0cf6542096b1
+README.zh.md: a71f040f3b1383604fa1f151f797906dd343c49a
diff --git a/packages/fs/tool-str-replace-editor/README.zh.md b/packages/fs/tool-str-replace-editor/README.zh.md
index 48358eb3c9..a71f040f3b 100644
--- a/packages/fs/tool-str-replace-editor/README.zh.md
+++ b/packages/fs/tool-str-replace-editor/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-基于 `ctx.fs` 的独立模型可见 `str_replace_editor`。它可与持久 Bash、一次性 Bash、沙箱 Bash 或其他终端表面组合。
+基于 `ctx.fs` 的独立模型可见 `str_replace_editor`。它可与持久 Bash、一次性 Bash、沙箱 Bash 或其他终端接口组合。
 
 ## 配置
 
@@ -13,13 +13,13 @@
 
 ## 工具
 
-Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从一开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
+schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
 
 ## 模型体验
 
 ### 工具 schema
 
-#### 模型所见
+#### 模型看到的内容
 
 生成的 [`str_replace_editor` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-str-replace-editor)，其中包含配置的 `description`。本插件不贡献独立系统提示词段。
 
@@ -33,7 +33,7 @@ Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert
 
 ### 工具结果
 
-#### 模型所见
+#### 模型看到的内容
 
 查看操作返回带行号文本或浅层目录列表。调用会向展示层提供文件位置，创建/替换还会提供 diff 卡片。修改操作返回简洁确认。长查看结果保留前缀并追加截断提示。
 
@@ -49,4 +49,4 @@ Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert
 
 - 操作面向 UTF-8 文本，不支持二进制文件。
 - `str_replace` 刻意拒绝零匹配或多匹配，且没有 `replace_all` 参数。
-- 每个修改操作都会经过 `fs/write-intent` 或 `fs/edit-intent`，解析当前 session 的沙箱策略，并交由挂载的文件系统与策略插件执行。
+- 每个修改操作都会经过 `fs/write-intent` 或 `fs/edit-intent`，解析当前会话的沙箱策略，并交由挂载的文件系统与策略插件执行。
diff --git a/packages/host/directory-picker-native/README.i18n.yaml b/packages/host/directory-picker-native/README.i18n.yaml
index 9e4a432c5e..9f2c323183 100644
--- a/packages/host/directory-picker-native/README.i18n.yaml
+++ b/packages/host/directory-picker-native/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/host/directory-picker-native/README.md
 README.md: 4dd0c79d080fe097d063cfd2200e30aafc2d2d42
-README.zh.md: 8ebf2a6e978ad042e522e7e2831a508501d3eca5
+README.zh.md: bbf6d361f48792a9f385a83032546f6d95fd3fc8
diff --git a/packages/host/directory-picker-native/README.zh.md b/packages/host/directory-picker-native/README.zh.md
index 8ebf2a6e97..bbf6d361f4 100644
--- a/packages/host/directory-picker-native/README.zh.md
+++ b/packages/host/directory-picker-native/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
+[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在派生的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
 
-**双面包**：browser half（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并经洞的 owner 会话上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于 live 状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
+**双面包**：浏览器端（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流 slot注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并通过 slot 的属主交互约定上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于有效状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；客户端不包含任何按能力类型进行的分支，挂载第二个流程包会在加载期失败（slot 的 kind 为 `single`）。
 
 ## 模型体验
 
 无。该后端服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
diff --git a/packages/host/frontend-static/README.i18n.yaml b/packages/host/frontend-static/README.i18n.yaml
index 9d757aaf6c..d894667745 100644
--- a/packages/host/frontend-static/README.i18n.yaml
+++ b/packages/host/frontend-static/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/host/frontend-static/README.md
 README.md: 82ba5a2cd0937e2c24505648aa1e3daec6bf2ece
-README.zh.md: 1130aa7cc241ee5245fceaba0ef66fcf95871e67
+README.zh.md: 205c44838e40697cf1429a198d313391ea7acbae
diff --git a/packages/host/frontend-static/README.zh.md b/packages/host/frontend-static/README.zh.md
index 1130aa7cc2..205c44838e 100644
--- a/packages/host/frontend-static/README.zh.md
+++ b/packages/host/frontend-static/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名 route 时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
+Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换器（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
 
 回退席位只有单一所有者（第二次占据会抛错），并受 effect 作用域约束：dispose（资源释放）插件的 fiber 会释放席位，此后无人占据的 webserver 回答 404。
 
diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index bd80f27f3e..63ced787c1 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/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/host/webserver/README.md
 README.md: 569c3f0c19db2c308beaef35baaf915fd39768cd
-README.zh.md: b311ebffa3fb067e684e9e443c2ac02dab917d61
+README.zh.md: 92b4bcad252eb8a2e29100333a8ae19b9e30e994
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index b311ebffa3..92b4bcad25 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -2,17 +2,17 @@
 
 [English](README.md) | 中文
 
-Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层契约，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
+Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为路由模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
 
-该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
+该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务 Web 浏览器形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
 
-监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合 reject；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 `decodeURIComponent` 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 `close()` 与 `closeAllConnections()`，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
+监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合被拒绝；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 `decodeURIComponent` 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录警告，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 `close()` 与 `closeAllConnections()`，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
 
 ## 模型体验
 
 无。该包只是浏览器与其他插件所注册 HTTP／upgrade route 之间的 Web 载体，其中没有任何内容会进入模型请求。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
diff --git a/packages/pty/tool-bash-persistent/README.i18n.yaml b/packages/pty/tool-bash-persistent/README.i18n.yaml
index aec30c2b4a..9f9e3e2cc2 100644
--- a/packages/pty/tool-bash-persistent/README.i18n.yaml
+++ b/packages/pty/tool-bash-persistent/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/pty/tool-bash-persistent/README.md
 README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
-README.zh.md: a525485933344a8f9bc218456c099efdef572902
+README.zh.md: 9689c42d4252dc804fb4100c41c6ead9dadb910c
diff --git a/packages/pty/tool-bash-persistent/README.zh.md b/packages/pty/tool-bash-persistent/README.zh.md
index a525485933..9689c42d42 100644
--- a/packages/pty/tool-bash-persistent/README.zh.md
+++ b/packages/pty/tool-bash-persistent/README.zh.md
@@ -2,16 +2,16 @@
 
 [English](README.md) | 中文
 
-模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具契约和 shell 复用；PTY 后端与沙箱策略由部署选择。
+模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包负责工具约定和 shell 复用；PTY 后端与沙箱策略由部署选择。
 
 ## 配置
 
 | 键 | 默认值 | 含义 |
 |---|---:|---|
-| `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
+| `backendType` | `shell` | 每个 agent（智能体）的 shell 使用的已注册 PTY 后端。 |
 | `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
 | `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
-| `description` | 持久 shell 描述 | 面向模型的环境契约。 |
+| `description` | 持久 shell 描述 | 面向模型的环境约定。 |
 
 ## 模型体验
 
@@ -19,7 +19,7 @@
 
 #### 模型所见
 
-生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent)，其中包含配置的 `description`。本插件不贡献独立系统提示词段；persona 与环境指导由部署负责。
+生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent)，其中包含配置的 `description`。本插件不贡献独立系统提示词段；角色设定与环境指导由部署负责。
 
 #### Token 影响
 
@@ -33,7 +33,7 @@
 
 #### 模型所见
 
-每个 Agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
+每个 agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
 
 #### Token 影响
 
@@ -45,6 +45,6 @@
 
 ## 已知限制与延后工作
 
-- 工具需要拥有它的 Agent 和真实 PTY 后端。
+- 工具需要拥有它的 agent 和真实 PTY 后端。
 - 显式 `exit` 与超时会丢弃 shell 状态。取消同样会重置 shell 并丢弃结果，即使已经能观察到完整状态标记也是如此；下次调用创建新 shell。
-- 网络访问、软件包镜像等环境事实应写入配置的 `description`，而非包默认描述。
+- 网络访问、包镜像等环境事实应写入配置的 `description`，而非包默认描述。
diff --git a/packages/session/session-checkpoint-policy/README.i18n.yaml b/packages/session/session-checkpoint-policy/README.i18n.yaml
index e435cf36d3..939a2b0a5f 100644
--- a/packages/session/session-checkpoint-policy/README.i18n.yaml
+++ b/packages/session/session-checkpoint-policy/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-checkpoint-policy/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-checkpoint-policy/README.md
 README.md: 01ed3c694967b1a86245d01b9d9f7eecd1193348
 README.zh.md: e2c197c0cc1d942a045c1ea22c1fb257f6e4059d
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 2ab76b4da9..fb28edd00c 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-persistence-jsonl/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
 README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
 README.zh.md: 59d21c6171e857849c4ab48940d66962fffbfdeb
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index f6d2d2926b..a0a2787e08 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-persistence-sqlite/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-sqlite/README.md
 README.md: 4961f62bf6854c343d35b8406c9d721590274534
 README.zh.md: 8610ef56f737bac8781536ea26a5b48dbf67ed48
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 5b131371b8..d6ca806d49 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/README.i18n.yaml
@@ -1,6 +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/session-persistence/session-persistence/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence/README.md
 README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
 README.zh.md: 1ef7eb6c6c507167f61bb5df7c4ce8183aac5d0d
diff --git a/packages/session/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
index 37c8d986f9..db570ff22a 100644
--- a/packages/session/session-projection-cache/README.i18n.yaml
+++ b/packages/session/session-projection-cache/README.i18n.yaml
@@ -1,6 +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/session-projection/session-projection-cache/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection-cache/README.md
 README.md: 5d4ad07fab6648acdb40c6aa86d32cc78b4c016e
 README.zh.md: 827480658b8c69647380a782c1a983b390380108
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 34c1910b16..4ca60337ff 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/README.i18n.yaml
@@ -1,6 +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/session-projection/session-projection/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection/README.md
 README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
 README.zh.md: f60a48bd41f0c33edb85a495ada9b6818ec46ee5
diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
index 0424414fac..d3fe513463 100644
--- a/packages/session/session-telemetry-otel/README.i18n.yaml
+++ b/packages/session/session-telemetry-otel/README.i18n.yaml
@@ -1,6 +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/telemetry/session-telemetry-otel/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry-otel/README.md
 README.md: 585995ce409255df9608bc33b76625374bc67669
 README.zh.md: 6d2cfa4d492cee7f90d557c83f5c1ab3c730c6e5
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index ee9c7288b1..0532902287 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/README.i18n.yaml
@@ -1,6 +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/telemetry/session-telemetry/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
 README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
 README.zh.md: 1ee0e0eb14bb06c8ac669cd417f2ee2ce46ca430
diff --git a/packages/session/session-title-all-messages-llm/README.i18n.yaml b/packages/session/session-title-all-messages-llm/README.i18n.yaml
index 54909b457e..e364ffc0a7 100644
--- a/packages/session/session-title-all-messages-llm/README.i18n.yaml
+++ b/packages/session/session-title-all-messages-llm/README.i18n.yaml
@@ -1,6 +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/session-title/session-title-all-messages-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-all-messages-llm/README.md
 README.md: 25ec92432b5c2d18624f2f4d851552ee2b3bf5d0
 README.zh.md: 947aa614741b2b0bd50e70f1d273a625a5624cc6
diff --git a/packages/session/session-title-first-message-llm/README.i18n.yaml b/packages/session/session-title-first-message-llm/README.i18n.yaml
index 1353b0b4e6..523ebc0bee 100644
--- a/packages/session/session-title-first-message-llm/README.i18n.yaml
+++ b/packages/session/session-title-first-message-llm/README.i18n.yaml
@@ -1,6 +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/session-title/session-title-first-message-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-first-message-llm/README.md
 README.md: c24d4de1fa945d11b5a868cad88a94ed14ad3891
 README.zh.md: 1f864b16c473654d0a52716cddbe26fe087860dc
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index 4ae7cd4aa7..8709d2c3db 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/README.i18n.yaml
@@ -1,6 +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/session-title/session-title-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-llm/README.md
 README.md: 342687b5aa0cd35a70abf8cc66b3fe80342bce0b
 README.zh.md: f6f39e07d300dbe53faa51514c29699ca1d6a3d2
diff --git a/packages/settings/README.i18n.yaml b/packages/settings/README.i18n.yaml
index 146f0ad32e..08a6c15dfd 100644
--- a/packages/settings/README.i18n.yaml
+++ b/packages/settings/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/settings/README.md
 README.md: 6f3719c58564a90fec3bd9f305cfaeb2b7bf0bf4
-README.zh.md: 0efb16dd4e5d5faa5f16814b94d55a20dc4c06c3
+README.zh.md: 41a640e3bbb8b297f08e354e8bdcf56e524ea3bd
diff --git a/packages/settings/README.zh.md b/packages/settings/README.zh.md
index 0efb16dd4e..41a640e3bb 100644
--- a/packages/settings/README.zh.md
+++ b/packages/settings/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-该包族通过注册的命名空间与可替换存储 provider 解析用户可编辑配置。
+该包族通过注册的命名空间与可替换存储提供方解析用户可编辑配置。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml
index ec26e4241f..83a2d75b38 100644
--- a/packages/settings/settings-local/README.i18n.yaml
+++ b/packages/settings/settings-local/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/settings/settings-local/README.md
 README.md: d1f3d755f9073acdf6fcfc5d1de883d74cc023c4
-README.zh.md: 03c7ef7c35312d9e1e4a86b0df71412875af7d6c
+README.zh.md: 2fe97435d56774351343b92fcbd5f80ee2680fd1
diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md
index 03c7ef7c35..2fe97435d5 100644
--- a/packages/settings/settings-local/README.zh.md
+++ b/packages/settings/settings-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-文件 settings provider。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 在写锁下先重读文档再原子写回，保留用户的 YAML 注释、当前未加载插件所拥有的分节，以及任何本进程尚未观察到的磁盘变更。
+基于文件的设置提供方。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 在写锁下先重读文档再原子写回，保留用户的 YAML 注释、当前未加载插件所拥有的分节，以及任何本进程尚未观察到的磁盘变更。
 
 ## 配置
 
@@ -17,28 +17,28 @@
 
 ## 行为
 
-- **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。
-- **每次写入都是一次读-改-写。** persist 先重读文档并把任何差异发布进 seam——无论是仍在 watcher 防抖窗口内的外部编辑、watcher 漏掉的变更，还是另一个进程的写入——再基于这份新鲜文本渲染，因此写入绝不会复活陈旧文档，也不会丢掉未观察到的同级分节。若磁盘上的文档已变为非法，写入响亮拒绝，而不是覆盖用户的手工编辑。
-- **写入持有跨进程写锁。** 读-渲染-rename 流程在 `wx` 创建的 `<file>.lock` 同级文件下运行，带指数退避与 2 s 的获取期限。竞争者会超时，但不会移除现有锁，因为锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方；遗留锁恢复须由操作者执行。读取方从不取锁：rename 提交是原子的，重载因此始终一致。
-- **写回原子、仅属主可读、抗符号链接。** 渲染以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。
+- **启动失败并明确报错，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。
+- **每次写入都是一次读-改-写。** persist 先重读文档并把任何差异发布进 seam——无论是仍在 watcher 防抖窗口内的外部编辑、watcher 漏掉的变更，还是另一个进程的写入——再基于这份新鲜文本渲染，因此写入绝不会复活陈旧文档，也不会丢掉未观察到的同级分节。若磁盘上的文档已变为非法，写入会明确报错并拒绝执行，而不是覆盖用户的手工编辑。
+- **写入持有跨进程写锁。** 读-渲染-rename 流程在以 `wx` 创建的同级锁文件 `<file>.lock` 保护下运行，带指数退避与 2 s 的获取期限。竞争者会超时，但不会移除现有锁，因为锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方；遗留锁恢复须由操作者执行。读取方从不取锁：rename 提交是原子的，重载因此始终一致。
+- **写回原子、仅属主可访问、抗符号链接。** 渲染以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。
 - **YAML 编辑是叶子级 diff。** 写入只设置发生变化的值、只删除被移除的键，因此注释、锚点与排版在每个未触碰的节点上以及每个被改键值对的键上都得以保留；被改的数组（或其他非 map 值）整体替换，其中的注释随之一同被换掉。JSON 重新序列化，无注释。
 - **重载与写入共享一条操作链。** watcher 刷新与来自各 namespace 队列的 persist 按队列顺序逐个执行；每次渲染都基于上一次操作提交后的文本。
 - **watcher 的 ready 信号做一次对账。** 初始加载与 watcher 自身的建立存在竞态，因此其间写入的变更绝不会触发事件；ready 时的对账补上这个启动缺口。
-- **Dispose 在每种 watch 模式下都保证静止。** 卸载先把提供方标记为已关闭，在 watcher 存在时将其关闭，再等待所有已排队或进行中的文档操作完成，之后不再有任何发布。
-- **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
+- **dispose（资源释放）在每种 watch 模式下都保证完全停稳。** 卸载先把提供方标记为已关闭，在 watcher 存在时将其关闭，再等待所有已排队或进行中的文档操作完成，之后不再有任何发布。
+- **按内容抑制自写。** 提供方缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
 - **Host 配置适配器会收到解析后的路径。** `ctx.settings.documentPath` 是 `resolveSpec()` 得出的绝对文件名，包括自定义 YAML/JSON 路径；`prepareDocument()` 会保留现有文件，或在 Host 打开文档前，以仅属主可访问的权限独占创建缺失的空文件。浏览器只收到可用性标志，绝不重建 `$DSH_HOME`，也绝不提交文件系统目标。
 
 ## 模型体验
 
-间接生效：本 provider 只存储并发布 namespace 分节，模型效果经由 `ctx.settings` 的消费插件产生，由各消费者自己的文档描述。
+间接生效：本提供方只存储并发布 namespace 分节，任何模型效果都经由 `ctx.settings` 的消费方产生，并由各消费方自己的接口文档说明。
 
 #### KV Cache 影响
 
-无直接失效；请求前缀的变更由消费插件拥有。
+无直接失效；请求前缀的任何变更均由消费方插件负责。
 
 ## 已知限制与暂缓事项
 
 - **同 namespace 冲突仍是后写胜出** — 写锁加读-改-写让并发写入者不会丢掉彼此的 namespace，但两个写入者编辑同一个 namespace 时仍以较后的写入为准；没有按值合并，也没有修订检查。
 - **漏掉的 watcher 事件在下一个信号前保持不可见** — 读取从不重新 stat 文件，因此 watcher 漏报的变更只会在下一个事件、下一次写入或重启时被并入。
 - **注释保留仅限 YAML 且仅限 map 形状** — JSON 文档重新序列化，无注释（JSON 本身没有），且被改数组内部的注释（或行内附着在被改标量值上的注释）随其所描述的值一同被换掉。
-- **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是 seam 层的延后特性。
+- **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是暂缓实现的 seam 层功能。
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index b2549e6be1..51c39bf1d0 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/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/settings/settings/README.md
 README.md: 0841624e553364fa03f7a1f1209aa72ab13d97e4
-README.zh.md: e8fe4485c2cf6cb6b8710347ebb8dcd1e8424b38
+README.zh.md: a23826bd5e3a19ab491970f3b4dc230d8b750b6a
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index e8fe4485c2..a23826bd5e 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-抽象用户设置 seam（`ctx.settings`）。一个 provider 持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载 provider 时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
+抽象用户设置 seam（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
 
 ## 服务 API
 
 - `documentPath` — 提供方拥有用户可编辑文件时，该字段是文件的绝对路径；非文件提供方保留 `undefined`。Host 配置适配器据此派生可用性，而浏览器协议只暴露一个布尔能力，绝不暴露文件系统目标。
 - `prepareDocument()` — 让文档做好供原生编辑器打开的准备后返回该路径。基类实现返回 `documentPath`；文件提供方可先创建缺失的文档。
 - `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。
-- `describe(options?)` — 每个 namespace 一条描述（`schema.toJSON()` 信封、解析值、分离出的 `base`/`user` 层、`applies`），供配置界面使用；字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段，并附加 `secrets` 槽位列表（`{ path, set }`）；每个 wire 面都必须传入它，纯遍历器 `redactSecrets(schema, value)` 已导出，供其他 wire 使用。
+- `describe(options?)` — 每个 namespace 一条描述（`schema.toJSON()` 封装、解析值、分离出的 `base`/`user` 层、`applies`），供配置界面使用；字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段，并附加 `secrets` 槽位列表（`{ path, set }`）；每个协议接口都必须传入它，纯遍历器 `redactSecrets(schema, value)` 已导出，供其他 wire 使用。
 - `get(ns)` — 解析值；未注册时为 `undefined`。
-- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。patch 必须是 JSON 形状的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默扭曲这类值）。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
+- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经提供方持久化后提交。patch 必须是 JSON 形状的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默扭曲这类值）。校验失败在持久化前拒绝；只读提供方（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
 - `replace(ns, section)` — 整体替换用户分节：这是刻意的重置（`replace({})` 重新继承 `base` 与 schema 默认值）。
 - `mutate(ns, ops)` — 在写入排到队首那一刻的分节上，按序施加 `{ op: 'set' | 'unset', path }` 编辑。这是任何持有**不完整**视图的调用方的删除路径：配置 UI 读到的是脱敏后的 descriptor，据此重建分节再整体替换，会把 wire 从未回传的每个机密都删掉，而一条 op 只点名它真正要改的那个字段。
-- 每次写入都可携带可选的 `expectedRevision`。每个 descriptor 都带有该 namespace 的 `revision`——一个针对其**原始**分节的单调计数器；期望值不再匹配的写入会以 `SettingsConflictError`（`code: 'SETTINGS_CONFLICT'`，并附上两个 revision）被拒绝，而不是覆盖先落地的那个写方。写队列只保证写入的先后次序，它本身分辨不出一个新写方与一个持有过期快照的写方。
-- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
+- 每次写入都可携带可选的 `expectedRevision`。每个 descriptor 都带有该 namespace 的 `revision`——一个针对其**原始**分节的单调计数器；期望值不再匹配的写入会以 `SettingsConflictError`（`code: 'SETTINGS_CONFLICT'`，并附上两个 revision）被拒绝，而不是覆盖先完成写入的写入方。写队列只保证写入的先后次序，它本身分辨不出新的写入方与持有陈旧快照的写入方。
+- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐监听器扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
 - 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。
 
-## 提供方契约
+## 提供方约定
 
 子类实现 `writable`、`load()`、`persist(ns, section)`，可选择为一个本地用户可编辑文件重写 `documentPath` 与 `prepareDocument()`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
 
@@ -34,10 +34,10 @@
 
 #### KV Cache 影响
 
-无直接失效；把设置值折叠进请求前缀的消费者拥有该变更。
+无直接失效；把设置值折叠进请求前缀的消费方负责该变更。
 
 ## 已知限制与暂缓事项
 
 - **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。
 - **`redactSecrets` 并非一条可被证明的协议边界**：walker 只跟随 `object`/`dict`/`array`，因此只能经由 union、intersection 或 transform 抵达的 `role('secret')` 会被**原样**返回，且 `secrets` 列表为空；而 `schema.toJSON()` 会把 secret 字段的 `.default(...)` 一并带给每个客户端。这两种情况都不会被拒绝；机密无法经由被遍历的容器抵达的 schema，绝不可注册到暴露于协议的 namespace 上。真正的答案是一个 fail-closed 的 `describeForWire()`——它拒绝自己无法证明安全的 schema，并对序列化信封与错误文本做净化——此项暂缓。
-- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
+- **跨进程并发由提供方定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按提供方行为收敛（本地文件提供方在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
diff --git a/packages/skill/skill-badge/README.i18n.yaml b/packages/skill/skill-badge/README.i18n.yaml
index 4dda53481c..80bfa13b34 100644
--- a/packages/skill/skill-badge/README.i18n.yaml
+++ b/packages/skill/skill-badge/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/skill/skill-badge/README.md
 README.md: 49b38023a7c110bb52bb351668905c702e251216
-README.zh.md: bf7eb0d7d4c0552c07f9cdf5665f8a20df829483
+README.zh.md: f22afd0d957f202eb7b2b5953015f7c0a4c5b571
diff --git a/packages/skill/skill-badge/README.zh.md b/packages/skill/skill-badge/README.zh.md
index bf7eb0d7d4..f22afd0d95 100644
--- a/packages/skill/skill-badge/README.zh.md
+++ b/packages/skill/skill-badge/README.zh.md
@@ -4,7 +4,7 @@
 
 可选的内置 skill（技能）提供方，向 `ctx.skills` 贡献 `dsh-badge`。该 skill 提供官方「powered by dsh」Markdown 片段和随包分发的 PNG，供无法可靠导入远程图片的系统使用。
 
-挂载该插件即可启用提供方。它没有配置。交付的 CLI（命令行界面）组合以 `disabled: true` 包含该插件；用户必须显式启用其 `skill-badge` 配置行，该 skill 才会进入目录。
+挂载该插件即可启用提供方。它没有配置。随附的 CLI（命令行界面）组合以 `disabled: true` 包含该插件；用户必须显式启用其 `skill-badge` 配置行，该 skill 才会进入目录。
 
 该提供方将随包分发的 `assets/` 目录作为 skill 资源基底公开。`dsh-badge.png` 是尺寸为 726×120 的源图资源，消费方以 121×20 的尺寸渲染。
 
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
index 6bc638bdc4..bcbfb4e6de 100644
--- a/packages/subagent/subagent-claude-code/README.i18n.yaml
+++ b/packages/subagent/subagent-claude-code/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/subagent/subagent-claude-code/README.md
 README.md: e62f60fceea16749296a91377785b81d94d751ca
-README.zh.md: e171524157b2b1696df31753816210d41637a911
+README.zh.md: 79c515e557ef9f576b2b71bf175c64b0eb828d93
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
index e171524157..79c515e557 100644
--- a/packages/subagent/subagent-claude-code/README.zh.md
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
@@ -20,7 +20,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
 
 ## 配置
 
@@ -31,7 +31,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 生产环境使用 `@anthropic-ai/claude-agent-sdk` 提供的 Claude Code CLI，以及宿主机原生设置与身份验证。本插件不安装另一份 CLI、不选择模型、不创建产品主目录、不执行登录，也不探测账户。具有凭证特征的环境变量会在显式 `env` 覆盖生效前被清除，因此供子进程使用的 API 密钥或 token 必须在该配置中显式提供。除非被覆盖，`ANTHROPIC_BASE_URL` 等非凭证端点变量以及 `PATH` 和 `HOME` 等普通环境变量仍会被继承。
 
-请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。正式 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_claude_code`。
+请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。随附的 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_claude_code`。
 
 ```yaml
 - id: subagent-claude-code
@@ -51,7 +51,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 ## 产品兼容性与证据
 
-运行时依赖精确锁定为 `@anthropic-ai/claude-agent-sdk@0.3.220`，其平台可选依赖提供 Claude Code 2.1.220。强制证据会通过无密钥回环产品路径与带密钥 DeepSeek 路径运行该官方发行版，而 Loader 组合则证明两个选择启用的产品包能够共存，且不会启动任一产品。
+运行时依赖精确锁定为 `@anthropic-ai/claude-agent-sdk@0.3.220`，其平台可选依赖提供 Claude Code 2.1.220。所需证据会通过无密钥回环产品路径与带密钥 DeepSeek 路径运行该官方发行版，而 Loader 组合则证明两个选择性启用的产品包能够共存，且不会启动任一产品。
 
 项目所有者按身份范围授权分发官方 SDK 及每个 SDK 版本声明的官方 CLI／平台载荷。[`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) 会披露当前可选载荷闭包，但不会把其声明条款归类为宽松许可证；其他无关的非宽松运行时依赖仍会使第三方声明门禁失败。
 
@@ -75,7 +75,7 @@ Claude Code 子任务会在一个全新的 SDK query 中接收独立文本任务
 
 #### 模型看到的内容
 
-通过 `dsh-tool-subagent`，父级模型只会看到符合严格成功条件的 Claude Code 最终答案，或者在结果未完成时看到消费方给出的原样错误。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息和产品标识符均不会复制到父会话。
+通过 `dsh-tool-subagent`，父级模型只会看到符合严格成功条件的 Claude Code 最终答案，或者在结果未完成时看到消费方给出的确切错误。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息和产品标识符均不会复制到父会话。
 
 #### 对 token 的影响
 
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
index 97c2b9f705..5c0c4a8851 100644
--- a/packages/subagent/subagent-codex/README.i18n.yaml
+++ b/packages/subagent/subagent-codex/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/subagent/subagent-codex/README.md
 README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
-README.zh.md: 10c8fcc47a9ab04bca983857bd44ede265c23435
+README.zh.md: 61b6760feeaeae2b3f9ab179d10b7f84e8ac82bf
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
index 10c8fcc47a..61b6760fee 100644
--- a/packages/subagent/subagent-codex/README.zh.md
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
-`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。随后，它通过 [`dsh-subprocess`](../../subprocess/subprocess/README.md) spawn 固定命令，依次执行 `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`，且仅在 Codex 返回有效的临时线程后才发布此次运行。若在发布前发生失败或取消，它会关闭通信链路、终止受管进程树并等待其退出，然后拒绝 `start()` 调用。
+`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。随后，它通过 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 派生固定命令，依次执行 `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`，且仅在 Codex 返回有效的临时线程后才发布此次运行。若在发布前发生失败或取消，它会关闭通信链路、终止受管进程树并等待其退出，然后拒绝 `start()` 调用。
 
 已发布的 `run.result` 恰好启动一个轮次。它只接受与此次运行的线程和轮次匹配的通知，随后等待权威的终止通知 `turn/completed`。以最后一条 `phase: "final_answer"` 的 `agentMessage` 为准；若 Codex 没有发出明确的最终阶段，则以最后一条 `phase: null` 的消息作为兼容性回退。过程说明绝不会取代上述任一答案；成功完成的轮次若没有非空白答案，结果也会判为错误。
 
@@ -16,7 +16,7 @@
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
 
 ## 配置
 
@@ -27,7 +27,7 @@
 
 生产环境会从 `PATH` 中解析 `codex`，并使用宿主机原生的 Codex 配置与身份验证。本插件不安装 Codex、不选择模型、不创建 `CODEX_HOME`、不执行登录，也不探测版本。子进程 seam 会移除具有凭证特征的环境变量，因此供子进程使用的 API 密钥必须在 `env` 中显式提供；除非被覆盖，`PATH` 和 `HOME` 等普通环境变量值仍然可用。
 
-请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。正式 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_codex`。
+请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。随附的 CLI（命令行界面）配置默认不会加载此提供方，也不会暴露 `subagent_codex`。
 
 ```yaml
 - id: subagent-codex
@@ -47,7 +47,7 @@
 
 ## 产品兼容性与证据
 
-生产环境的协议层有意只实现这一单次执行契约所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 npm 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
 
 ## 模型体验
 
@@ -69,7 +69,7 @@ Codex 子任务会在一个全新的临时线程中，以单个轮次接收这
 
 #### 模型看到的内容
 
-通过 `dsh-tool-subagent`，父级模型只会看到选定的 Codex 最终答案，或者在结果未完成时看到消费方给出的原样错误。Codex 的过程说明、推理（reasoning）、工具活动、stderr、工作区差异和产品标识符均不会复制到父会话。
+通过 `dsh-tool-subagent`，父级模型只会看到选定的 Codex 最终答案，或者在结果未完成时看到消费方给出的确切错误。Codex 的过程说明、推理（reasoning）、工具活动、stderr、工作区差异和产品标识符均不会复制到父会话。
 
 #### 对 token 的影响
 
@@ -83,7 +83,7 @@ Codex 子任务会在一个全新的临时线程中，以单个轮次接收这
 
 - **每次运行均新建一个进程、一个线程和一个轮次**：不支持续接、恢复、池化、进度流或产品会话持久化。
 - **产品安装和账户状态由宿主管理**：`codex` 缺失或不兼容、配置错误或身份验证失败，都会呈现为启动错误或运行错误；本插件不提供安装程序、登录流程或运行时版本门禁。
-- **兼容性由开发证据锁定**：若要从已验证的 0.146.0 协议基线升级，必须重新生成上游 schema 证据，并重新运行握手、答案选择、审批、取消、无密钥真实产品以及带密钥的 DeepSeek 随机数测试。
+- **兼容性由开发证据锁定**：若要从已验证的 0.146.0 协议基线升级，必须重新生成上游 schema 证据，并重新运行握手、答案选择、审批、取消、无密钥真实产品以及带密钥的 DeepSeek 唯一值测试。
 - **没有人工审批路径**：已知的无人值守审批请求会被拒绝，未知服务器请求会以默认拒绝方式使运行失败；部署方无法通过本包配置允许策略。
 - **仅返回最终文本**：推理、过程说明、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部。
 - **没有可选的共享能力**：对于本提供方，共享服务会拒绝输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 25b54630b2..a3d9b5f357 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
 README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 91be3c97bcb67ce10c61513113f683e741bc762f
+README.zh.md: e4e034c1060ea7b0040c75039200611702e05017
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 91be3c97bc..e4e034c106 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -6,10 +6,10 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 
 四层可单独导入：
 
-- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动过程中公开异步 spawn 失败，对未处理权限请求快速失败，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才解析或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
-- **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父级和 subagent 子级，主级优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
-- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
-- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
+- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动阶段报告异步派生失败，并默认拒绝未处理的权限请求，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才完成关闭或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
+- **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父会话和 subagent 子会话，主会话优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
+- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每种原生／JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已进行 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
+- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新模式写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件构成有序的主会话／子会话清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
 签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
@@ -65,11 +65,11 @@ defineAcpSnapshotSuite({
 
 无。该测试专用 harness 记录、规范化并比较 ACP transcript，不会改变 agent 组装的模型请求。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
-## 已知限制与待完成工作
+## 已知限制与暂缓事项
 
 - **会话收集需要原始 JSONL mode**：`runScenario` 收集持久化 `.jsonl` 日志，因此快照配置使用 `persistenceCompression: 'none'`；压缩 JSONL 和 SQLite 组合没有快照收集路径。
 - **构建 mode 需要当前产物**：先运行 `pnpm run build`，再选择 `DSH_EXAMPLE_MODE=lib`；源 mode 仍是零构建路径。
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index a61602c07b..90b4ac9a65 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
 README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
-README.zh.md: 10a6309bc47001d572abb3dd3f794ebfcf6252e8
+README.zh.md: a37efbf2e7da64cad243a7f93515b7e18904bc81
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 10a6309bc4..a37efbf2e7 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -2,25 +2,25 @@
 
 [English](README.md) | 中文
 
-该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
+该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、宿主网关和客户端 API 共享。它负责 Remote 服务基类、装饰器、显式绑定回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方约定；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
 
 ## Remote 声明
 
 - `@Remote` 将公开实例方法标记为可在其注册的 Cordis 服务上直接调用。
 - `@RemoteScope(key)` 标记接收者选自合并声明的作用域 Context 类型的方法。
-- `GatewayService` 将 `super(ctx, serviceKey, options?)` 接收的 Cordis key 同时绑定为默认 wire namespace。
-- `bindTypeRTGateway(this, serviceKey, options?)` 为无法继承 `GatewayService` 的 Service 提供同样可见且冻结的绑定。
+- `GatewayService` 将传给 `super(ctx, serviceKey, options?)` 的 Cordis 键绑定到同一默认协议命名空间。
+- `bindTypeRTGateway(this, serviceKey, options?)` 为无法继承 `GatewayService` 的服务提供同样可见且冻结的绑定。
 - `remoteMethods(service)` 返回按声明顺序排列、与内部状态分离的快照，供 Gateway 的 SRC 回退路径使用。
 
-Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用协作式取消。`InvocationDescriptor.cancellation` 记录这个保留的注入点；signal 绝不会成为 JSON 参数或 lookup 字段。SRC 识别末位参数名，严格生成还会校验它是否具有全局 `AbortSignal` 类型。
+宿主方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用协作式取消。`InvocationDescriptor.cancellation` 记录这个保留的注入点；该信号绝不会成为 JSON 参数或查找字段。SRC 识别末位参数名，严格生成还会校验它是否具有全局 `AbortSignal` 类型。
 
-装饰器初始化器将标记保存在以服务 prototype 为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加 symbol，也不会添加 prototype 属性、参数元数据或运行时反射字段。`GatewayService` 会暴露与显式 helper 相同的 public readonly `typertGateway` 绑定。
+装饰器初始化器将标记保存在以服务原型为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加符号，也不会添加原型属性、参数元数据或运行时反射字段。`GatewayService` 会暴露与显式辅助函数相同的公开只读 `typertGateway` 绑定。
 
 ## TypeRT 协议
 
-业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client Remote 使用的共享运行时形式。
+业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联宿主对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使客户端导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、网关和客户端 Remote 使用的共享运行时形式。
 
-查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+查找包与 Context 包同时负责该约定的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。查找提供方或宿主 Context 提供方提供稳定声明与默认解析器，宿主组合可以另行配置同步或异步解析器；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ## 模型体验
 
@@ -30,7 +30,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 无直接影响。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
 - 装饰器标记仅包含方法名，以及直接调用或 Context 调用模式。参数、结果、查找和 schema 反射需要 TypeRT 构建流水线。
 - Remote 装饰器只接受具有字符串名称的公开、非静态实例方法。SRC 执行无法表示重载签名，以及包含解构参数、默认参数或剩余参数的方法签名。
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index 33e1f6014b..5c6b6ac63d 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/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/util/atomic-write/README.md
 README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
-README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
+README.zh.md: 799f01be6f27e00b740c7e0a2c68218f99317451
diff --git a/packages/util/atomic-write/README.zh.md b/packages/util/atomic-write/README.zh.md
index 4284d06422..799f01be6f 100644
--- a/packages/util/atomic-write/README.zh.md
+++ b/packages/util/atomic-write/README.zh.md
@@ -4,7 +4,7 @@
 
 零依赖的原子文件替换，供绝不允许在磁盘上留下不完整、被符号链接劫持或权限过宽内容的文件型存储共用：用户设置文档（`dsh-settings-local`）与凭据存储（`dsh-credentials-local`）。
 
-## 接口面
+## 接口
 
 ```ts
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
@@ -20,15 +20,15 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 })
 ```
 
-`writeFileAtomic` 提交一份已经渲染好的字符串。契约按故障利用它的先后顺序列出：
+`writeFileAtomic` 提交一份已经渲染好的字符串。约定按故障可能利用各项机制的先后顺序列出：
 
 - **独占创建临时文件**（`wx` + 随机后缀）：open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
 - **全新 inode 携带 `mode` 走完 rename**：替换权限过宽的旧文件时直接收窄，不存在 chmod 竞态。`mode` 为必填，让权限决策始终可见于每个调用点（与所有新建 inode 一样受进程 umask 影响）。
-- **`rename` 替换的是符号链接目标本身**，绝不写穿到其指向的文件。
+- **`rename` 替换的是符号链接本身**，绝不写穿到其指向的文件。
 - **同目录兄弟文件**保证 rename 落在同一文件系统上，交换保持原子。
 - 自动创建父目录；任何失败都会移除临时文件并重新抛出该失败；读取方只会观察到旧内容或完整的新内容。
 
-`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。竞争者绝不移除现有锁：锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
+`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录同级文件 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。竞争者绝不移除现有锁：锁文件的存在时长无法区分已经崩溃的属主与被暂停但仍存活的写入方。
 
 ## 模型体验
 
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 633064ae4c..c8e36d8a5e 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
 README.md: 599a9ba747905b66452b57717dabcc6f4678a3dd
-README.zh.md: 69f9c670bbb3ea1b2fbddaa7508a19dfb47fad12
+README.zh.md: d728f835b1ece44d2848a618e504951f26fec7e2
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 69f9c670bb..d728f835b1 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -7,7 +7,7 @@
 | 层 | 来源 id | 它是什么 |
 |---|---|---|
 | 继承的进程环境 | `process` | 启动 shell、CI 任务或容器传入的东西——本次运行的明确意图 |
-| `<invocation cwd>/.env` | `project-env` | harness 被启动于其中的项目；产品信任它配置自己的 agent |
+| `<invocation cwd>/.env` | `project-env` | harness 被启动于其中的项目；产品信任它配置自己的 agent（智能体） |
 | `$DSH_HOME/.env` | `user-env` | 用户自己的机器级默认值 |
 
 这些值同样会进入 `process.env`——用户自己的 `--config` 树和第三方库要读它——但那份压平的视图不是 harness 解析任何值的依据。
@@ -16,7 +16,7 @@
 
 `get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索指定的层，不改变这一可信顺序。
 
-**省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。provider 适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
+**省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。提供方适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
 
 变量名按平台自身的规则匹配：POSIX 上精确匹配，Windows 上不区分大小写。在 Windows 上做大小写敏感的查找会选错层——shell 里的 `deepseek_api_key` 与项目 `.env` 里的 `DEEPSEEK_API_KEY` 对操作系统而言是同一个变量，把它们当成两个就会让项目胜出。
 
@@ -30,7 +30,7 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 当产品 CLI（命令行界面）启动了这棵树时，`environmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切确实就是它被启动时的环境。
 
-## Known Limitations and Deferred Work
+## 已知限制与暂缓事项
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 约定](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/python/development.i18n.yaml b/python/development.i18n.yaml
index b7792acf27..1a7b57f86d 100644
--- a/python/development.i18n.yaml
+++ b/python/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/development.md
 development.md: b0d4875f0d5b7c8fd2b4b480ac67793741640710
-development.zh.md: 4fda7efbeaa0359bd4999aca148ca21a63c4fd70
+development.zh.md: 053cd1d022ef5fc7d8cff98b9fc3234df6ff4cd1
diff --git a/python/development.zh.md b/python/development.zh.md
index 4fda7efbea..053cd1d022 100644
--- a/python/development.zh.md
+++ b/python/development.zh.md
@@ -2,7 +2,7 @@
 
 [English](development.md) | 中文
 
-根据所需的贡献者成果选择工作流：构建运行时产物、验证 SDK、从源码运行或构建分发包。包行为分别见 [SDK 参考](sdk/README.md)和[运行时载体参考](sdk-runtime/README.md)。
+根据所需的贡献者成果选择工作流：构建运行时产物、验证 SDK、从源码运行或构建分发包。包行为分别见 [SDK 参考](sdk/README.md) 和[运行时载体参考](sdk-runtime/README.md)。
 
 ## 构建运行时产物
 
@@ -13,7 +13,7 @@ pnpm install
 pnpm exec tsx scripts/build-exe-for-python-sdk.ts
 ```
 
-所需 `lib/` 产物已存在时使用 `--skip-build`；如需选择平台，请使用 `--targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64`。产物写入 `dist-exe/`，脚本会将所选载体同步到 `python/sdk-runtime/`。macOS 构建还会同步 `node-pty` 所需的配套 spawn helper。
+所需 `lib/` 产物已存在时使用 `--skip-build`；如需选择平台，请使用 `--targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64`。产物写入 `dist-exe/`，脚本会将所选载体同步到 `python/sdk-runtime/`。macOS 构建还会同步 `node-pty` 所需的配套 spawn 辅助程序。
 
 ## 验证 SDK
 
@@ -25,7 +25,7 @@ uv sync --project python/sdk --group test
 uv run --project python/sdk pytest
 ```
 
-`python/sdk/tests/test_bundled_runtime.py` 会运行可用的内置载体；某个载体的产物尚未构建时，会跳过该载体。仓库级测试政策见[测试](../docs/testing.md)。
+`python/sdk/tests/test_bundled_runtime.py` 会运行可用的内置载体；某个载体的产物尚未构建时，会跳过该载体。仓库级测试政策见 [测试](../docs/testing.md)。
 
 交互式冒烟测试需要环境变量或仓库根目录 `.env` 中存在 `DEEPSEEK_API_KEY`：
 
@@ -45,9 +45,9 @@ with DeepSeekHarness() as harness:
 
 完整的源码模式调用见 `python/sdk/tests/manual_sdk_agent_smoke.py`。
 
-## 构建分发物
+## 构建分发包
 
-根目录 `package.json` 的版本是两个 Python 分发物的权威版本。暂存脚本会将该版本注入两个 wheel 包，并将 SDK 固定到同版本的 `deepseek-harness-runtime-bin`。
+根目录 `package.json` 的版本是两个 Python 分发包的权威版本。暂存脚本会将该版本注入两个 wheel 包，并将 SDK 固定到同版本的 `deepseek-harness-runtime-bin`。
 
 纯 SDK wheel 包只需构建一次；每个原生平台分别构建一个运行时 wheel 包：
 
@@ -58,4 +58,4 @@ python scripts/build-python-release.py --package runtime --platform macos-arm64
 pip install --find-links dist-python deepseek-harness=="$version"
 ```
 
-运行时分发物仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 `python-vX.Y.Z` 标签。
+运行时分发包仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 `python-vX.Y.Z` 标签。
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 5d8f68f4cd..2385b3c24c 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -299,22 +299,54 @@ describe('docsPages locale routes', () => {
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
-    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md', 'inherited.md']
+    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md']
     for (const file of files) {
       const root = docsPages.find(page => page.route === `reference/cordis-api/${file}`)
       const english = docsPages.find(page => page.route === `en/reference/cordis-api/${file}`)
-      expect(root?.source).toBe(`docs/cordis-api/${file}`)
+      expect(root?.source).toBe(`docs/cordis-api/${file.replace(/\.md$/, '.zh.md')}`)
+      expect(root?.contentLocale).toBe('zh-CN')
       expect(root?.section).toBe('Cordis API')
-      expect(english?.source).toBe(root?.source)
+      expect(english?.source).toBe(`docs/cordis-api/${file}`)
+      expect(english?.contentLocale).toBe('en-US')
       expect(english?.section).toBe('Cordis Core API')
     }
   })
 
-  it('includes persistence event headings in both locale outlines', () => {
-    const pages = docsPages.filter(page => page.source === 'docs/persistence-catalog.md')
+  it('keeps Cordis inherited on the English fallback in both locales', () => {
+    const pages = docsPages.filter(page => page.route.endsWith('reference/cordis-api/inherited.md'))
     expect(pages).toHaveLength(2)
+    expect(pages.every(page => page.source === 'docs/cordis-api/inherited.md')).toBe(true)
+    expect(pages.every(page => page.contentLocale === 'en-US')).toBe(true)
+  })
+
+  it('includes persistence event headings in both locale outlines', () => {
+    const pages = docsPages.filter(page => page.route.endsWith('reference/persistence-catalog.md'))
+    expect(pages).toHaveLength(2)
+    expect(pages.map(page => page.source).sort()).toEqual([
+      'docs/persistence-catalog.md',
+      'docs/persistence-catalog.zh.md',
+    ])
     expect(pages.map(page => page.outline)).toEqual(['deep', 'deep'])
   })
+
+  it('projects reviewed generated counterparts into root locale routes', () => {
+    const routes = [
+      'reference/capability-seams.md',
+      'reference/agent-lifecycle.md',
+      'reference/tool-execution-pipeline.md',
+      'reference/config-catalog.md',
+      'reference/tool-catalog.md',
+      'reference/persistence-catalog.md',
+      'reference/cordis-api/context.md',
+      'reference/cordis-api/events.md',
+      'reference/cordis-api/fiber.md',
+      'reference/cordis-api/registry.md',
+      'reference/cordis-api/service.md',
+    ]
+    const pages = routes.map(route => docsPages.find(page => page.route === route))
+    expect(pages.every(page => page?.contentLocale === 'zh-CN')).toBe(true)
+    expect(pages.every(page => page?.source.endsWith('.zh.md'))).toBe(true)
+  })
 })
 
 describe('addProjectionFrontmatter', () => {
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index 112cd3ae4d..acc2a10c14 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -4,18 +4,9 @@
     ".agents/notes/implemented/AGENTS.md",
     ".agents/notes/implemented/CLAUDE.md",
     "docs/AGENTS.md",
-    "docs/agent-lifecycle.md",
-    "docs/capability-seams.md",
-    "docs/config-catalog.md",
-    "docs/cordis-api/",
-    "docs/event-producer-consumer.md",
-    "docs/graph-atlas.md",
+    "docs/cordis-api/inherited.md",
     "docs/i18n/style-samples.md",
     "docs/i18n/terminology.md",
-    "docs/i18n/translation-prompt.md",
-    "docs/module-graph.md",
-    "docs/persistence-catalog.md",
-    "docs/tool-catalog.md",
-    "docs/tool-execution-pipeline.md"
+    "docs/i18n/translation-prompt.md"
   ]
 }
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index b89df38f52..b5b2a1d5a7 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -19,6 +19,7 @@ import {
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
   partitionGeneratedRegions,
+  requiresSourceLanguageSwitcher,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -142,6 +143,16 @@ describe('translation pairing manifest', () => {
   })
 })
 
+describe('translation pairing switchers', () => {
+  it('exempts only paired generated English sources from reciprocal switchers', () => {
+    expect(requiresSourceLanguageSwitcher('docs/config-catalog.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/cordis-api/context.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/cordis-api/inherited.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/architecture.md')).toBe(true)
+    expect(requiresSourceLanguageSwitcher('packages/core/session/README.md')).toBe(true)
+  })
+})
+
 describe('translation pairing records', () => {
   const paths = translationPairPaths('docs/foo.md')
   const record = {
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 417e836578..87e31199a4 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -311,6 +311,27 @@ export function linksTo(tree: Nodes, target: string): boolean {
   return found
 }
 
+/** Generated English sources cannot carry a switcher without making their generator stale. */
+export function requiresSourceLanguageSwitcher(source: string): boolean {
+  return ![
+    'docs/agent-lifecycle.md',
+    'docs/capability-seams.md',
+    'docs/config-catalog.md',
+    'docs/cordis-api/context.md',
+    'docs/cordis-api/events.md',
+    'docs/cordis-api/fiber.md',
+    'docs/cordis-api/inherited.md',
+    'docs/cordis-api/registry.md',
+    'docs/cordis-api/service.md',
+    'docs/event-producer-consumer.md',
+    'docs/graph-atlas.md',
+    'docs/module-graph.md',
+    'docs/persistence-catalog.md',
+    'docs/tool-catalog.md',
+    'docs/tool-execution-pipeline.md',
+  ].includes(source)
+}
+
 /** Collect the ordered structural signature, skipping one switcher target. */
 export function translationStructureSignature(tree: Nodes, switcherTarget: string): TranslationStructureSignature {
   const sig: TranslationStructureSignature = { headings: [], code: [], tables: [], lists: [], links: [] }
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index be5c1816ae..95a2fe9747 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -24,6 +24,7 @@ import {
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
   partitionGeneratedRegions,
+  requiresSourceLanguageSwitcher,
   isTranslationScopeFile,
   TRANSLATION_SCOPE_GLOB_EXCLUDES,
   translationStructureDiff,
@@ -254,7 +255,7 @@ for (const source of [...pairAnchors].sort()) {
   if (!linksTo(zhTree, basename(source))) {
     errors.push(`${zh}: missing language switcher — no link to ${basename(source)}`)
   }
-  if (!linksTo(sourceTree, basename(zh))) {
+  if (requiresSourceLanguageSwitcher(source) && !linksTo(sourceTree, basename(zh))) {
     errors.push(`${source}: missing language switcher — no link back to ${basename(zh)}`)
   }
   for (const divergence of translationStructureDiff(
diff --git a/website/docs.ts b/website/docs.ts
index 3a31bf4baf..1e97d88e24 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -307,12 +307,9 @@ const subsystemsReference = pairedPages(([
   ...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
 
-const reference = mirroredPages([
-  ...([
+const reference = [
+  ...mirroredPages(([
     ['docs/architecture.md', 'reference/index.md', '架构', 'Architecture', 0],
-    ['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services', 2],
-    ['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle', 3],
-    ['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution', 4],
   ] as const).map(([source, route, rootLabel, enLabel, order]): MirroredPage => ({
     source,
     route,
@@ -321,27 +318,47 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '概念', en: 'Concepts' },
     order,
-  })),
-  ...([
+  }))),
+  ...pairedPages(([
+    ['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services', 2],
+    ['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle', 3],
+    ['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution', 4],
+  ] as const).map(([source, route, rootLabel, enLabel, order]): PairedPage => ({
+    source,
+    route,
+    label: { root: rootLabel, en: enLabel },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: '概念', en: 'Concepts' },
+    order,
+  }))),
+  ...pairedPages(([
     ['docs/config-catalog.md', 'reference/config-catalog.md', '插件配置', 'Plugin configuration'],
     ['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
     ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'],
-  ] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({
+  ] as const).map(([source, route, rootLabel, enLabel, outline], order): PairedPage => ({
     source,
     route,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '生成参考', en: 'Generated reference' },
     order,
     ...(outline === undefined ? {} : { outline }),
-  })),
-  ...([
+  }))),
+  ...pairedPages(([
     ['context.md', 'Context', 'Context'],
     ['events.md', 'Events', 'Events'],
     ['fiber.md', 'Fiber', 'Fiber'],
     ['registry.md', 'Plugin Registry', 'Plugin Registry'],
     ['service.md', 'Service', 'Service'],
+  ] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
+    source: `docs/cordis-api/${file}`,
+    route: `reference/cordis-api/${file}`,
+    label: { root: rootLabel, en: enLabel },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: 'Cordis API', en: 'Cordis Core API' },
+    order,
+  }))),
+  ...mirroredPages(([
     ['inherited.md', '继承接口面', 'Inherited surface'],
   ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
     source: `docs/cordis-api/${file}`,
@@ -350,9 +367,9 @@ const reference = mirroredPages([
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: 'Cordis API', en: 'Cordis Core API' },
-    order,
-  })),
-  ...([
+    order: order + 5,
+  }))),
+  ...mirroredPages(([
     ['goal.md', '目标', 'Goals', 14],
     ['pty.md', 'PTY 会话', 'PTY sessions', 26],
     ['commands.md', '命令', 'Human commands', 38],
@@ -364,8 +381,8 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '子系统', en: 'Subsystems' },
     order,
-  })),
-  ...([
+  }))),
+  ...mirroredPages(([
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
     ['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
@@ -378,8 +395,8 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '开发手册', en: 'Cookbook' },
     order,
-  })),
-])
+  }))),
+]
 
 /** Every canonical page published by the documentation website. */
 export const docsPages: DocsPage[] = [

From 90a876cbad9b54cfad30c1b2153291bb44a5e7f9 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 11:21:20 +0800
Subject: [PATCH 177/262] test: refresh translation prompt snapshot

---
 .../request-response.expected.json                 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 137315cf39..57fa7ebc3f 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 契约 | | | 如：`pairing contract` →`配对契约` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
@@ -12,7 +12,7 @@
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",
@@ -20,15 +20,15 @@
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\nGenerated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
@@ -40,11 +40,11 @@
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",

From a7af54a8d34247b9c4f5c6ec0b289be5e06b6cce Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 11:33:14 +0800
Subject: [PATCH 178/262] docs(i18n): standardize contract terminology

---
 .agents/notes/README.i18n.yaml                |  2 +-
 .agents/notes/README.zh.md                    | 14 +++----
 ...ev-invariants-over-deep-readonly.i18n.yaml |  2 +-
 ...11-dev-invariants-over-deep-readonly.zh.md |  2 +-
 .../2026-06-13-capability-seams.i18n.yaml     |  2 +-
 .../2026-06-13-capability-seams.zh.md         |  4 +-
 .../2026-06-13-twin-llm-adapters.i18n.yaml    |  2 +-
 .../2026-06-13-twin-llm-adapters.zh.md        |  4 +-
 .../2026-06-14-session-persistence.i18n.yaml  |  2 +-
 .../2026-06-14-session-persistence.zh.md      |  2 +-
 ...06-17-filesystem-capability-seam.i18n.yaml |  2 +-
 ...026-06-17-filesystem-capability-seam.zh.md | 16 ++++----
 ...nt-lifecycle-and-ownership-seams.i18n.yaml |  2 +-
 ...-agent-lifecycle-and-ownership-seams.zh.md |  2 +-
 .../2026-06-18-session-surface.i18n.yaml      |  2 +-
 .../2026-06-18-session-surface.zh.md          |  2 +-
 ...ed-persistence-write-coordinator.i18n.yaml |  2 +-
 ...shared-persistence-write-coordinator.zh.md |  2 +-
 ...eneric-long-running-tool-runtime.i18n.yaml |  2 +-
 ...20-generic-long-running-tool-runtime.zh.md | 14 +++----
 ...-21-bounded-llm-request-recovery.i18n.yaml |  2 +-
 ...6-06-21-bounded-llm-request-recovery.zh.md |  6 +--
 ...andatory-app-attribution-headers.i18n.yaml |  2 +-
 ...21-mandatory-app-attribution-headers.zh.md | 14 +++----
 .../2026-06-24-web-capability-seam.i18n.yaml  |  2 +-
 .../2026-06-24-web-capability-seam.zh.md      | 12 +++---
 ...06-26-file-context-as-event-gate.i18n.yaml |  2 +-
 ...026-06-26-file-context-as-event-gate.zh.md | 12 +++---
 ...6-07-02-tool-render-intent-union.i18n.yaml |  2 +-
 .../2026-07-02-tool-render-intent-union.zh.md |  4 +-
 ...bles-and-tool-guidance-ownership.i18n.yaml |  2 +-
 ...ariables-and-tool-guidance-ownership.zh.md |  2 +-
 ...05-windows-jsonl-durable-publish.i18n.yaml |  2 +-
 ...-07-05-windows-jsonl-durable-publish.zh.md |  8 ++--
 ...6-07-06-timeout-deadline-library.i18n.yaml |  2 +-
 .../2026-07-06-timeout-deadline-library.zh.md |  6 +--
 ...06-tool-result-retention-library.i18n.yaml |  2 +-
 ...-07-06-tool-result-retention-library.zh.md |  4 +-
 ...6-07-07-tool-call-timeout-policy.i18n.yaml |  2 +-
 .../2026-07-07-tool-call-timeout-policy.zh.md |  8 ++--
 .../2026-07-08-agent-scope-contexts.i18n.yaml |  2 +-
 .../2026-07-08-agent-scope-contexts.zh.md     |  8 ++--
 ...26-07-08-tool-output-spill-files.i18n.yaml |  2 +-
 .../2026-07-08-tool-output-spill-files.zh.md  |  4 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |  2 +-
 ...026-07-12-agent-scope-runtime-design.zh.md | 40 +++++++++----------
 .../2026-07-12-scoped-layers-store.i18n.yaml  |  2 +-
 .../2026-07-12-scoped-layers-store.zh.md      | 12 +++---
 ...2026-07-15-agent-initiator-scope.i18n.yaml |  2 +-
 .../2026-07-15-agent-initiator-scope.zh.md    | 10 ++---
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  2 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  8 ++--
 ...07-16-explicit-turn-cancellation.i18n.yaml |  2 +-
 ...026-07-16-explicit-turn-cancellation.zh.md |  2 +-
 ...19-cooperative-tool-cancellation.i18n.yaml |  2 +-
 ...-07-19-cooperative-tool-cancellation.zh.md |  6 +--
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |  2 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md | 18 ++++-----
 ...7-19-gui-web-client-architecture.i18n.yaml |  2 +-
 ...26-07-19-gui-web-client-architecture.zh.md | 10 ++---
 ...kage-invariant-runtime-contracts.i18n.yaml |  2 +-
 ...-package-invariant-runtime-contracts.zh.md |  8 ++--
 ...-package-owned-invariant-service.i18n.yaml |  2 +-
 ...7-19-package-owned-invariant-service.zh.md | 10 ++---
 ...-19-zstandard-jsonl-session-logs.i18n.yaml |  2 +-
 ...6-07-19-zstandard-jsonl-session-logs.zh.md |  2 +-
 ...0-canonical-tool-output-contract.i18n.yaml |  2 +-
 ...07-20-canonical-tool-output-contract.zh.md |  8 ++--
 ...20-unified-json-value-schema-dsl.i18n.yaml |  2 +-
 ...-07-20-unified-json-value-schema-dsl.zh.md |  4 +-
 ...2-slot-type-chain-implementation.i18n.yaml |  2 +-
 ...07-22-slot-type-chain-implementation.zh.md |  4 +-
 ...send-and-coalesced-user-messages.i18n.yaml |  2 +-
 ...ied-send-and-coalesced-user-messages.zh.md |  2 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |  2 +-
 ...26-07-23-client-plugin-loading-model.zh.md |  2 +-
 ...xt-injection-from-turn-execution.i18n.yaml |  2 +-
 ...ontext-injection-from-turn-execution.zh.md |  2 +-
 ...-24-single-harness-home-resolver.i18n.yaml |  2 +-
 ...6-07-24-single-harness-home-resolver.zh.md |  2 +-
 ...ession-scope-and-provide-channel.i18n.yaml |  2 +-
 ...nt-session-scope-and-provide-channel.zh.md |  6 +--
 ...eb-command-surfaces-and-assembly.i18n.yaml |  2 +-
 ...25-web-command-surfaces-and-assembly.zh.md |  2 +-
 ...input-machine-and-slash-pipeline.i18n.yaml |  2 +-
 ...web-input-machine-and-slash-pipeline.zh.md | 10 ++---
 ...-26-packed-chunk-rows-by-default.i18n.yaml |  2 +-
 ...6-07-26-packed-chunk-rows-by-default.zh.md |  6 +--
 .../2026-07-26-task-registry-seam.i18n.yaml   |  2 +-
 .../2026-07-26-task-registry-seam.zh.md       | 12 +++---
 ...ompiler-independent-typert-model.i18n.yaml |  2 +-
 ...27-compiler-independent-typert-model.zh.md |  4 +-
 ...07-27-dispose-ladder-to-consumer.i18n.yaml |  2 +-
 ...026-07-27-dispose-ladder-to-consumer.zh.md |  2 +-
 ...directory-picker-capability-seam.i18n.yaml |  2 +-
 ...-28-directory-picker-capability-seam.zh.md |  8 ++--
 ...xperimental-plugin-package-group.i18n.yaml |  2 +-
 ...28-experimental-plugin-package-group.zh.md |  6 +--
 ...ntified-immutable-message-values.i18n.yaml |  2 +-
 ...-identified-immutable-message-values.zh.md |  2 +-
 ...rtable-execution-world-consumers.i18n.yaml |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  8 ++--
 .../2026-07-28-user-settings-seam.i18n.yaml   |  2 +-
 .../2026-07-28-user-settings-seam.zh.md       |  4 +-
 ...-token-usage-and-request-context.i18n.yaml |  2 +-
 ...cted-token-usage-and-request-context.zh.md |  2 +-
 ...est-level-llm-config-credentials.i18n.yaml |  2 +-
 ...request-level-llm-config-credentials.zh.md |  2 +-
 ...-manager-native-repository-cache.i18n.yaml |  2 +-
 ...kage-manager-native-repository-cache.zh.md |  2 +-
 ...30-settings-write-path-integrity.i18n.yaml |  2 +-
 ...-07-30-settings-write-path-integrity.zh.md |  6 +--
 ...-static-repository-plugin-format.i18n.yaml |  2 +-
 ...7-30-static-repository-plugin-format.zh.md |  6 +--
 ...claimed-pre-step-inbox-lifecycle.i18n.yaml |  2 +-
 ...-31-claimed-pre-step-inbox-lifecycle.zh.md |  2 +-
 ...runtime-portable-identifier-seam.i18n.yaml |  2 +-
 ...ode-runtime-portable-identifier-seam.zh.md | 12 +++---
 ...26-08-01-packaged-ripgrep-search.i18n.yaml |  2 +-
 .../2026-08-01-packaged-ripgrep-search.zh.md  |  2 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |  2 +-
 ...026-08-02-typert-remote-method-calls.zh.md | 28 ++++++-------
 ...-pi-ai-declared-provider-catalog.i18n.yaml |  2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |  2 +-
 ...08-04-websocket-downlink-carrier.i18n.yaml |  2 +-
 ...026-08-04-websocket-downlink-carrier.zh.md |  2 +-
 ...e-session-jsonl-restore-pipeline.i18n.yaml |  2 +-
 ...large-session-jsonl-restore-pipeline.zh.md |  4 +-
 .../2026-08-05-session-preparation.i18n.yaml  |  2 +-
 .../2026-08-05-session-preparation.zh.md      |  2 +-
 ...08-05-slot-declaration-injection.i18n.yaml |  2 +-
 ...026-08-05-slot-declaration-injection.zh.md |  2 +-
 ...8-06-agent-event-payload-objects.i18n.yaml |  2 +-
 ...26-08-06-agent-event-payload-objects.zh.md |  4 +-
 ...ubagent-list-identity-projection.i18n.yaml |  2 +-
 ...06-subagent-list-identity-projection.zh.md | 28 ++++++-------
 ...arkdown-incremental-ast-renderer.i18n.yaml |  2 +-
 ...eb-markdown-incremental-ast-renderer.zh.md |  4 +-
 ...ssion-persistence-write-batching.i18n.yaml |  2 +-
 ...d-session-persistence-write-batching.zh.md |  6 +--
 ...ient-tool-presentation-ownership.i18n.yaml |  2 +-
 ...8-client-tool-presentation-ownership.zh.md |  8 ++--
 ...s-atomic-write-dacl-preservation.i18n.yaml |  2 +-
 ...ndows-atomic-write-dacl-preservation.zh.md |  4 +-
 ...-21-semantic-session-checkpoints.i18n.yaml |  2 +-
 ...6-07-21-semantic-session-checkpoints.zh.md |  2 +-
 .../2026-07-27-glob-sampling.i18n.yaml        |  2 +-
 .../bug-fix/2026-07-27-glob-sampling.zh.md    |  8 ++--
 ...table-snapshot-refresh-volatiles.i18n.yaml |  2 +-
 ...27-stable-snapshot-refresh-volatiles.zh.md |  2 +-
 ...ad-pre-identity-session-messages.i18n.yaml |  2 +-
 ...8-load-pre-identity-session-messages.zh.md |  6 +--
 ...d-scrollbars-and-reserved-gutter.i18n.yaml |  2 +-
 ...hemed-scrollbars-and-reserved-gutter.zh.md |  8 ++--
 ...-07-28-web-agent-runtime-context.i18n.yaml |  2 +-
 ...2026-07-28-web-agent-runtime-context.zh.md |  4 +-
 ...2026-07-28-web-gui-feedback-loop.i18n.yaml |  2 +-
 .../2026-07-28-web-gui-feedback-loop.zh.md    |  8 ++--
 ...9-human-transcript-append-origin.i18n.yaml |  2 +-
 ...07-29-human-transcript-append-origin.zh.md |  4 +-
 ...29-web-details-session-lifecycle.i18n.yaml |  2 +-
 ...-07-29-web-details-session-lifecycle.zh.md |  4 +-
 ...-30-composer-context-stack-order.i18n.yaml |  2 +-
 ...6-07-30-composer-context-stack-order.zh.md |  4 +-
 ...ranscript-log-ordered-projection.i18n.yaml |  2 +-
 ...eb-transcript-log-ordered-projection.zh.md |  8 ++--
 ...1-english-compaction-checkpoints.i18n.yaml |  2 +-
 ...07-31-english-compaction-checkpoints.zh.md |  2 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |  2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |  2 +-
 ...-fork-anchor-floors-to-event-seq.i18n.yaml |  2 +-
 ...7-31-fork-anchor-floors-to-event-seq.zh.md |  4 +-
 ...resume-selector-batch-projection.i18n.yaml |  2 +-
 ...-31-resume-selector-batch-projection.zh.md |  4 +-
 ...6-07-31-web-stop-preserves-queue.i18n.yaml |  2 +-
 .../2026-07-31-web-stop-preserves-queue.zh.md |  2 +-
 ...-ask-user-delegated-caller-guard.i18n.yaml |  2 +-
 ...8-01-ask-user-delegated-caller-guard.zh.md |  2 +-
 ...-08-02-goal-round-wrapup-message.i18n.yaml |  2 +-
 ...2026-08-02-goal-round-wrapup-message.zh.md |  4 +-
 ...odo-first-composer-context-order.i18n.yaml |  2 +-
 ...02-todo-first-composer-context-order.zh.md |  2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |  2 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |  2 +-
 ...3-hmr-initial-scan-boot-deadlock.i18n.yaml |  2 +-
 ...08-03-hmr-initial-scan-boot-deadlock.zh.md |  2 +-
 ...-04-load-pre-react-loop-sessions.i18n.yaml |  2 +-
 ...6-08-04-load-pre-react-loop-sessions.zh.md |  4 +-
 ...rding-step-owned-takeover-chrome.i18n.yaml |  2 +-
 ...nboarding-step-owned-takeover-chrome.zh.md |  8 ++--
 ...06-provider-credential-lifecycle.i18n.yaml |  2 +-
 ...-08-06-provider-credential-lifecycle.zh.md |  2 +-
 ...-attribution-observed-top-ledger.i18n.yaml |  2 +-
 ...roll-attribution-observed-top-ledger.zh.md |  8 ++--
 ...e-unpriced-replace-compatibility.i18n.yaml |  2 +-
 ...rface-unpriced-replace-compatibility.zh.md |  6 +--
 ...07-cancel-convergence-wake-latch.i18n.yaml |  2 +-
 ...-08-07-cancel-convergence-wake-latch.zh.md |  4 +-
 .../2026-06-14-acp-multi-session.i18n.yaml    |  2 +-
 .../2026-06-14-acp-multi-session.zh.md        |  4 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |  2 +-
 .../feature/2026-06-15-code-mode.zh.md        |  6 +--
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |  2 +-
 .../2026-06-17-filesystem-tool-schemas.zh.md  |  8 ++--
 ...06-18-compaction-capability-seam.i18n.yaml |  2 +-
 ...026-06-18-compaction-capability-seam.zh.md | 16 ++++----
 .../2026-06-22-acp-subagent-backend.i18n.yaml |  2 +-
 .../2026-06-22-acp-subagent-backend.zh.md     |  2 +-
 .../2026-06-24-workspace-context.i18n.yaml    |  2 +-
 .../2026-06-24-workspace-context.zh.md        |  2 +-
 .../2026-06-29-todo-write-tool.i18n.yaml      |  2 +-
 .../feature/2026-06-29-todo-write-tool.zh.md  |  2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |  2 +-
 .../2026-06-30-hook-protocol-lib.zh.md        |  4 +-
 .../2026-06-30-interception-seams.i18n.yaml   |  2 +-
 .../2026-06-30-interception-seams.zh.md       |  6 +--
 ...026-06-30-session-store-fork-api.i18n.yaml |  2 +-
 .../2026-06-30-session-store-fork-api.zh.md   |  2 +-
 .../2026-07-05-dynamic-workflows.i18n.yaml    |  2 +-
 .../2026-07-05-dynamic-workflows.zh.md        |  6 +--
 .../feature/2026-07-05-skill-system.i18n.yaml |  2 +-
 .../feature/2026-07-05-skill-system.zh.md     |  6 +--
 .../2026-07-06-approval-seam.i18n.yaml        |  2 +-
 .../feature/2026-07-06-approval-seam.zh.md    | 10 ++---
 .../2026-07-06-explicit-tool-order.i18n.yaml  |  2 +-
 .../2026-07-06-explicit-tool-order.zh.md      |  4 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |  2 +-
 .../feature/2026-07-06-sandbox.zh.md          |  6 +--
 .../2026-07-07-mcp-client-plugin.i18n.yaml    |  2 +-
 .../2026-07-07-mcp-client-plugin.zh.md        |  6 +--
 ...-07-08-background-subagent-tasks.i18n.yaml |  2 +-
 ...2026-07-08-background-subagent-tasks.zh.md |  4 +-
 ...-self-referential-cordis-toolset.i18n.yaml |  2 +-
 ...7-08-self-referential-cordis-toolset.zh.md |  8 ++--
 ...ession-identity-and-log-location.i18n.yaml |  2 +-
 ...nt-session-identity-and-log-location.zh.md |  4 +-
 ...-10-parallel-tool-call-execution.i18n.yaml |  2 +-
 ...6-07-10-parallel-tool-call-execution.zh.md |  8 ++--
 ...10-sqlite-session-query-provider.i18n.yaml |  2 +-
 ...-07-10-sqlite-session-query-provider.zh.md |  6 +--
 ...nt-persona-tool-filter-and-depth.i18n.yaml |  2 +-
 ...bagent-persona-tool-filter-and-depth.zh.md |  2 +-
 ...2026-07-13-session-query-tracing.i18n.yaml |  2 +-
 .../2026-07-13-session-query-tracing.zh.md    |  4 +-
 ...26-07-14-cross-family-fs-sandbox.i18n.yaml |  2 +-
 .../2026-07-14-cross-family-fs-sandbox.zh.md  |  2 +-
 ...16-durable-per-step-time-context.i18n.yaml |  2 +-
 ...-07-16-durable-per-step-time-context.zh.md |  2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |  2 +-
 .../2026-07-16-harness-level-loop.zh.md       |  6 +--
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  | 18 ++++-----
 ...-fresh-agent-ralph-workflow-tool.i18n.yaml |  2 +-
 ...7-19-fresh-agent-ralph-workflow-tool.zh.md |  2 +-
 .../2026-07-19-human-goal-command.i18n.yaml   |  2 +-
 .../2026-07-19-human-goal-command.zh.md       | 12 +++---
 ...26-07-19-model-facing-goal-tools.i18n.yaml |  2 +-
 .../2026-07-19-model-facing-goal-tools.zh.md  |  2 +-
 ...7-19-plugin-command-registration.i18n.yaml |  2 +-
 ...26-07-19-plugin-command-registration.zh.md |  6 +--
 ...-20-code-mode-typed-tool-returns.i18n.yaml |  2 +-
 ...6-07-20-code-mode-typed-tool-returns.zh.md | 12 +++---
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |  2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |  4 +-
 ...continuable-background-subagents.i18n.yaml |  2 +-
 ...-21-continuable-background-subagents.zh.md | 14 +++----
 ...6-07-21-cross-session-references.i18n.yaml |  2 +-
 .../2026-07-21-cross-session-references.zh.md |  4 +-
 ...-07-21-log-backed-session-titles.i18n.yaml |  2 +-
 ...2026-07-21-log-backed-session-titles.zh.md |  2 +-
 ...subagent-catalog-and-list-agents.i18n.yaml |  2 +-
 ...ble-subagent-catalog-and-list-agents.zh.md | 18 ++++-----
 .../2026-07-22-web-bind-address.i18n.yaml     |  2 +-
 .../feature/2026-07-22-web-bind-address.zh.md |  4 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |  2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |  4 +-
 ...026-07-23-web-assistant-markdown.i18n.yaml |  2 +-
 .../2026-07-23-web-assistant-markdown.zh.md   |  4 +-
 ...7-23-web-permission-and-approval.i18n.yaml |  2 +-
 ...26-07-23-web-permission-and-approval.zh.md |  8 ++--
 .../2026-07-23-web-todo-display.i18n.yaml     |  2 +-
 .../feature/2026-07-23-web-todo-display.zh.md |  2 +-
 ...model-facing-session-query-tools.i18n.yaml |  2 +-
 ...-24-model-facing-session-query-tools.zh.md |  2 +-
 ...26-07-24-provider-retry-policies.i18n.yaml |  2 +-
 .../2026-07-24-provider-retry-policies.zh.md  |  4 +-
 ...n-list-browsing-and-manual-order.i18n.yaml |  2 +-
 ...ssion-list-browsing-and-manual-order.zh.md |  6 +--
 ...-07-25-workspace-ui-product-flow.i18n.yaml |  2 +-
 ...2026-07-25-workspace-ui-product-flow.zh.md |  2 +-
 ...7-26-code-dispatch-ui-foundation.i18n.yaml |  2 +-
 ...26-07-26-code-dispatch-ui-foundation.zh.md |  6 +--
 ...code-mode-live-parallel-dispatch.i18n.yaml |  2 +-
 ...-26-code-mode-live-parallel-dispatch.zh.md | 12 +++---
 ...-07-26-todo-parallel-in-progress.i18n.yaml |  2 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |  2 +-
 ...ative-workspace-directory-picker.i18n.yaml |  2 +-
 ...27-native-workspace-directory-picker.zh.md |  2 +-
 ...-07-27-skill-catalog-hot-refresh.i18n.yaml |  2 +-
 ...2026-07-27-skill-catalog-hot-refresh.zh.md |  4 +-
 ...-27-trajectory-inspection-ledger.i18n.yaml |  2 +-
 ...6-07-27-trajectory-inspection-ledger.zh.md |  2 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |  2 +-
 ...escript-sdk-and-sdk-subagent-backend.zh.md |  2 +-
 ...6-07-27-web-session-fork-actions.i18n.yaml |  2 +-
 .../2026-07-27-web-session-fork-actions.zh.md |  2 +-
 .../2026-07-27-web-session-search.i18n.yaml   |  2 +-
 .../2026-07-27-web-session-search.zh.md       | 10 ++---
 ...07-27-web-subagent-conversations.i18n.yaml |  2 +-
 ...026-07-27-web-subagent-conversations.zh.md | 18 ++++-----
 ...ntinuable-subagent-conversations.i18n.yaml |  2 +-
 ...8-continuable-subagent-conversations.zh.md |  8 ++--
 ...2026-07-28-sdk-max-output-tokens.i18n.yaml |  2 +-
 .../2026-07-28-sdk-max-output-tokens.zh.md    |  2 +-
 ...26-07-28-skill-invocation-policy.i18n.yaml |  2 +-
 .../2026-07-28-skill-invocation-policy.zh.md  |  8 ++--
 .../2026-07-28-web-terminal-card.i18n.yaml    |  2 +-
 .../2026-07-28-web-terminal-card.zh.md        |  4 +-
 ...29-ask-question-web-presentation.i18n.yaml |  2 +-
 ...-07-29-ask-question-web-presentation.zh.md |  2 +-
 ...irectory-picker-adaptive-default.i18n.yaml |  2 +-
 ...29-directory-picker-adaptive-default.zh.md |  2 +-
 ...rsistent-bash-str-replace-editor.i18n.yaml |  2 +-
 ...9-persistent-bash-str-replace-editor.zh.md |  2 +-
 ...0-config-only-repository-plugins.i18n.yaml |  2 +-
 ...07-30-config-only-repository-plugins.zh.md |  4 +-
 ...continuable-subagent-report-tool.i18n.yaml |  2 +-
 ...-30-continuable-subagent-report-tool.zh.md |  4 +-
 ...0-current-sandbox-policy-context.i18n.yaml |  2 +-
 ...07-30-current-sandbox-policy-context.zh.md |  2 +-
 ...seek-onboarding-credential-setup.i18n.yaml |  2 +-
 ...deepseek-onboarding-credential-setup.zh.md |  2 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |  2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |  2 +-
 .../2026-07-30-search-render-card.i18n.yaml   |  2 +-
 .../2026-07-30-search-render-card.zh.md       |  8 ++--
 .../2026-07-30-web-diff-card.i18n.yaml        |  2 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |  4 +-
 ...026-07-30-web-queue-steer-action.i18n.yaml |  2 +-
 .../2026-07-30-web-queue-steer-action.zh.md   |  8 ++--
 ...026-07-30-web-read-card-frontend.i18n.yaml |  2 +-
 .../2026-07-30-web-read-card-frontend.zh.md   |  2 +-
 .../2026-07-30-web-read-card.i18n.yaml        |  2 +-
 .../feature/2026-07-30-web-read-card.zh.md    |  4 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |  2 +-
 .../2026-07-30-web-result-card-frontend.zh.md | 12 +++---
 .../2026-07-30-web-result-card.i18n.yaml      |  2 +-
 .../feature/2026-07-30-web-result-card.zh.md  |  4 +-
 .../2026-07-30-web-search-card.i18n.yaml      |  2 +-
 .../feature/2026-07-30-web-search-card.zh.md  | 12 +++---
 ...l-row-unified-expand-and-inspect.i18n.yaml |  2 +-
 ...-tool-row-unified-expand-and-inspect.zh.md |  2 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |  2 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |  6 +--
 ...-31-gui-full-access-confirmation.i18n.yaml |  2 +-
 ...6-07-31-gui-full-access-confirmation.zh.md |  2 +-
 ...mission-default-for-new-sessions.i18n.yaml |  2 +-
 ...-permission-default-for-new-sessions.zh.md |  2 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |  2 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |  4 +-
 ...-third-party-memory-mcp-examples.i18n.yaml |  2 +-
 ...7-31-third-party-memory-mcp-examples.zh.md |  4 +-
 .../2026-07-31-web-default-search.i18n.yaml   |  2 +-
 .../2026-07-31-web-default-search.zh.md       |  2 +-
 ...6-07-31-web-workspace-file-links.i18n.yaml |  2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |  2 +-
 ...026-08-01-pwsh-tool-and-executor.i18n.yaml |  2 +-
 .../2026-08-01-pwsh-tool-and-executor.zh.md   |  8 ++--
 ...2026-08-02-pwsh-tool-bash-parity.i18n.yaml |  2 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md    |  6 +--
 ...6-08-02-web-thinking-tail-scroll.i18n.yaml |  2 +-
 .../2026-08-02-web-thinking-tail-scroll.zh.md |  4 +-
 ...6-08-03-web-search-source-scroll.i18n.yaml |  2 +-
 .../2026-08-03-web-search-source-scroll.zh.md |  2 +-
 ...code-and-codex-subagent-backends.i18n.yaml |  2 +-
 ...ude-code-and-codex-subagent-backends.zh.md |  6 +--
 ...nter-revealed-sidebar-scrollbars.i18n.yaml |  2 +-
 ...-pointer-revealed-sidebar-scrollbars.zh.md |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |  4 +-
 ...26-08-06-bundled-dsh-badge-skill.i18n.yaml |  2 +-
 .../2026-08-06-bundled-dsh-badge-skill.zh.md  |  2 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |  2 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  4 +-
 ...06-resolved-theme-color-metadata.i18n.yaml |  2 +-
 ...-08-06-resolved-theme-color-metadata.zh.md |  2 +-
 .../2026-08-06-web-install-manifest.i18n.yaml |  2 +-
 .../2026-08-06-web-install-manifest.zh.md     |  6 +--
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |  2 +-
 .../2026-08-06-web-skill-tool-row.zh.md       |  8 ++--
 ...6-08-08-dsh-run-headless-command.i18n.yaml |  2 +-
 .../2026-08-08-dsh-run-headless-command.zh.md |  2 +-
 .../2026-06-17-ts-build-config.i18n.yaml      |  2 +-
 .../process/2026-06-17-ts-build-config.zh.md  |  4 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  2 +-
 ...6-06-20-core-data-structures-catalog.zh.md |  4 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |  2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |  2 +-
 ...2026-07-04-doc-tiers-and-budgets.i18n.yaml |  2 +-
 .../2026-07-04-doc-tiers-and-budgets.zh.md    |  4 +-
 ...-07-05-uniform-agent-note-format.i18n.yaml |  2 +-
 ...2026-07-05-uniform-agent-note-format.zh.md | 10 ++---
 ...-07-06-export-surface-jsdoc-gate.i18n.yaml |  2 +-
 ...2026-07-06-export-surface-jsdoc-gate.zh.md | 14 +++----
 .../2026-07-06-node-engine-floor.i18n.yaml    |  2 +-
 .../2026-07-06-node-engine-floor.zh.md        |  2 +-
 ...ackage-model-experience-contract.i18n.yaml |  2 +-
 ...12-package-model-experience-contract.zh.md | 12 +++---
 ...13-documentation-site-projection.i18n.yaml |  2 +-
 ...-07-13-documentation-site-projection.zh.md |  2 +-
 ...pt-program-backed-semantic-gates.i18n.yaml |  2 +-
 ...script-program-backed-semantic-gates.zh.md |  6 +--
 ...emove-generated-agent-note-index.i18n.yaml |  2 +-
 ...19-remove-generated-agent-note-index.zh.md |  2 +-
 ...nt-notes-for-non-trivial-changes.i18n.yaml |  2 +-
 ...-agent-notes-for-non-trivial-changes.zh.md | 12 +++---
 .../2026-07-20-gui-testing-system.i18n.yaml   |  2 +-
 .../2026-07-20-gui-testing-system.zh.md       |  2 +-
 ...rial-cross-platform-ci-reference.i18n.yaml |  2 +-
 ...1-serial-cross-platform-ci-reference.zh.md |  6 +--
 ...ence-based-larger-hosted-runners.i18n.yaml |  2 +-
 ...evidence-based-larger-hosted-runners.zh.md | 12 +++---
 ...-07-22-product-first-root-readme.i18n.yaml |  2 +-
 ...2026-07-22-product-first-root-readme.zh.md |  2 +-
 ...fig-solution-root-two-aggregates.i18n.yaml |  2 +-
 ...sconfig-solution-root-two-aggregates.zh.md |  6 +--
 ...sonal-staging-maintenance-skills.i18n.yaml |  2 +-
 ...-personal-staging-maintenance-skills.zh.md |  2 +-
 ...ortable-required-pull-request-ci.i18n.yaml |  2 +-
 ...23-portable-required-pull-request-ci.zh.md |  6 +--
 ...3-translation-prompt-v4-contract.i18n.yaml |  2 +-
 ...07-23-translation-prompt-v4-contract.zh.md | 12 +++---
 ...efed-minimal-translation-updates.i18n.yaml |  2 +-
 ...-briefed-minimal-translation-updates.zh.md | 10 ++---
 ...6-dependencies-over-hand-rolling.i18n.yaml |  2 +-
 ...07-26-dependencies-over-hand-rolling.zh.md |  4 +-
 ...-07-26-frozen-agent-note-archive.i18n.yaml |  2 +-
 ...2026-07-26-frozen-agent-note-archive.zh.md |  2 +-
 ...26-web-syntax-highlighting-shiki.i18n.yaml |  2 +-
 ...-07-26-web-syntax-highlighting-shiki.zh.md |  2 +-
 .../2026-07-29-oxlint-linter.i18n.yaml        |  2 +-
 .../process/2026-07-29-oxlint-linter.zh.md    |  6 +--
 ...-31-coverage-exempt-heavy-suites.i18n.yaml |  2 +-
 ...6-07-31-coverage-exempt-heavy-suites.zh.md |  6 +--
 ...staller-adopts-existing-checkout.i18n.yaml |  2 +-
 ...1-installer-adopts-existing-checkout.zh.md |  8 ++--
 ...package-anchored-subsystem-pages.i18n.yaml |  2 +-
 ...-03-package-anchored-subsystem-pages.zh.md |  4 +-
 ...6-in-repository-landlock-release.i18n.yaml |  2 +-
 ...08-06-in-repository-landlock-release.zh.md |  2 +-
 ...remotes-generated-contract-build.i18n.yaml |  2 +-
 ...api-remotes-generated-contract-build.zh.md | 14 +++----
 ...matic-translation-pairing-merges.i18n.yaml |  2 +-
 ...automatic-translation-pairing-merges.zh.md |  2 +-
 ...08-unified-github-label-taxonomy.i18n.yaml |  2 +-
 ...-08-08-unified-github-label-taxonomy.zh.md | 10 ++---
 ...-19-drop-mutable-session-summary.i18n.yaml |  2 +-
 ...6-06-19-drop-mutable-session-summary.zh.md |  6 +--
 ...-06-20-public-agent-stop-surface.i18n.yaml |  2 +-
 ...2026-06-20-public-agent-stop-surface.zh.md |  6 +--
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |  2 +-
 .../2026-06-26-fsspec-style-fs-seam.zh.md     | 14 +++----
 ...4-tighten-hook-protocol-contract.i18n.yaml |  2 +-
 ...07-04-tighten-hook-protocol-contract.zh.md |  4 +-
 ...plify-session-log-representation.i18n.yaml |  2 +-
 ...-simplify-session-log-representation.zh.md |  2 +-
 .../2026-07-17-one-send-one-turn.i18n.yaml    |  2 +-
 .../2026-07-17-one-send-one-turn.zh.md        |  4 +-
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |  2 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |  8 ++--
 ...nwrap-injected-content-envelopes.i18n.yaml |  2 +-
 ...20-unwrap-injected-content-envelopes.zh.md |  2 +-
 ...lan-specific-collaboration-state.i18n.yaml |  2 +-
 ...22-plan-specific-collaboration-state.zh.md |  4 +-
 ...-23-acp-automation-only-protocol.i18n.yaml |  2 +-
 ...6-07-23-acp-automation-only-protocol.zh.md |  6 +--
 ...collapse-persistence-flush-state.i18n.yaml |  2 +-
 ...-23-collapse-persistence-flush-state.zh.md |  6 +--
 ...nt-loop-observable-state-machine.i18n.yaml |  2 +-
 ...-agent-loop-observable-state-machine.zh.md |  4 +-
 ...6-merge-subagent-control-service.i18n.yaml |  2 +-
 ...07-26-merge-subagent-control-service.zh.md |  6 +--
 ...6-07-28-local-json-tree-renderer.i18n.yaml |  2 +-
 .../2026-07-28-local-json-tree-renderer.zh.md |  6 +--
 .../2026-07-30-private-agent-send.i18n.yaml   |  2 +-
 .../2026-07-30-private-agent-send.zh.md       |  4 +-
 ...y-neutral-sandbox-policy-context.i18n.yaml |  2 +-
 ...ility-neutral-sandbox-policy-context.zh.md |  2 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |  2 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |  6 +--
 .../2026-08-08-remove-cli-demo.i18n.yaml      |  2 +-
 .../2026-08-08-remove-cli-demo.zh.md          |  6 +--
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |  2 +-
 .../2026-06-19-acp-snapshot-tests.zh.md       |  4 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |  2 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |  2 +-
 ...-22-cross-platform-test-fixtures.i18n.yaml |  2 +-
 ...6-07-22-cross-platform-test-fixtures.zh.md |  6 +--
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |  2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md | 16 ++++----
 .../2026-06-16-typed-event-schemas.i18n.yaml  |  2 +-
 .../2026-06-16-typed-event-schemas.zh.md      |  4 +-
 ...sdk-project-editing-architecture.i18n.yaml |  2 +-
 ...-15-sdk-project-editing-architecture.zh.md |  6 +--
 ...on-through-tool-capability-seams.i18n.yaml |  2 +-
 ...lation-through-tool-capability-seams.zh.md | 10 ++---
 ...-domain-kv-storage-and-workspace.i18n.yaml |  2 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md | 10 ++---
 ...-25-client-settings-locale-theme.i18n.yaml |  2 +-
 ...6-07-25-client-settings-locale-theme.zh.md |  4 +-
 ...ssion-projection-and-command-log.i18n.yaml |  2 +-
 ...7-session-projection-and-command-log.zh.md | 20 +++++-----
 ...root-and-derived-medium-recovery.i18n.yaml |  2 +-
 ...age-root-and-derived-medium-recovery.zh.md |  2 +-
 ...7-29-durable-last-activity-index.i18n.yaml |  2 +-
 ...26-07-29-durable-last-activity-index.zh.md |  2 +-
 ...8-semantic-composer-chain-phases.i18n.yaml |  2 +-
 ...08-08-semantic-composer-chain-phases.zh.md |  4 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |  2 +-
 .../2026-07-06-recallable-compaction.zh.md    |  2 +-
 ...026-07-14-sdk-developer-projects.i18n.yaml |  2 +-
 .../2026-07-14-sdk-developer-projects.zh.md   |  2 +-
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |  2 +-
 ...026-07-17-sdk-follow-up-capabilities.zh.md | 10 ++---
 .../feature/2026-08-04-task-surface.i18n.yaml |  2 +-
 .../feature/2026-08-04-task-surface.zh.md     | 18 ++++-----
 ...-06-11-architectural-conformance.i18n.yaml |  2 +-
 ...2026-06-11-architectural-conformance.zh.md |  2 +-
 ...3-human-review-skill-maintenance.i18n.yaml |  2 +-
 ...07-13-human-review-skill-maintenance.zh.md | 14 +++----
 ...t-first-npm-baseline-publication.i18n.yaml |  2 +-
 ...ifact-first-npm-baseline-publication.zh.md |  6 +--
 ...04-prune-dead-core-spine-surface.i18n.yaml |  2 +-
 ...-07-04-prune-dead-core-spine-surface.zh.md | 22 +++++-----
 ...ndstrip-for-windows-sandbox-rung.i18n.yaml |  2 +-
 ...e-landstrip-for-windows-sandbox-rung.zh.md |  2 +-
 ...ssembled-assistant-messages-only.i18n.yaml |  2 +-
 ...20-assembled-assistant-messages-only.zh.md |  2 +-
 ...-20-drop-durable-step-boundaries.i18n.yaml |  2 +-
 ...6-06-20-drop-durable-step-boundaries.zh.md |  2 +-
 ...ld-session-persistence-interface.i18n.yaml |  2 +-
 ...0-fold-session-persistence-interface.zh.md |  6 +--
 ...06-20-truncate-interrupted-turns.i18n.yaml |  2 +-
 ...026-06-20-truncate-interrupted-turns.zh.md |  4 +-
 ...apse-workflow-to-foreground-core.i18n.yaml |  2 +-
 ...collapse-workflow-to-foreground-core.zh.md |  4 +-
 ...ne-unused-skill-registry-surface.i18n.yaml |  2 +-
 ...-prune-unused-skill-registry-surface.zh.md |  6 +--
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |  2 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |  6 +--
 README.i18n.yaml                              |  2 +-
 README.zh.md                                  |  2 +-
 apps/cli/README.i18n.yaml                     |  2 +-
 apps/cli/README.zh.md                         |  2 +-
 apps/cli/reference/README.i18n.yaml           |  2 +-
 apps/cli/reference/README.zh.md               |  4 +-
 docs/api-gateway.i18n.yaml                    |  2 +-
 docs/api-gateway.zh.md                        | 12 +++---
 docs/architecture.i18n.yaml                   |  2 +-
 docs/architecture.zh.md                       |  4 +-
 docs/cookbook/adding-a-package.i18n.yaml      |  2 +-
 docs/cookbook/adding-a-package.zh.md          |  4 +-
 docs/cookbook/adding-a-tool.i18n.yaml         |  2 +-
 docs/cookbook/adding-a-tool.zh.md             |  8 ++--
 docs/cookbook/adding-an-llm-adapter.i18n.yaml |  2 +-
 docs/cookbook/adding-an-llm-adapter.zh.md     |  2 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |  2 +-
 docs/cookbook/extension-cookbook.zh.md        |  2 +-
 .../maintaining-dsh-code-review.i18n.yaml     |  2 +-
 .../maintaining-dsh-code-review.zh.md         |  2 +-
 docs/cordis-primer.i18n.yaml                  |  2 +-
 docs/cordis-primer.zh.md                      |  2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |  2 +-
 docs/cordis-tutorial/04-events.zh.md          |  2 +-
 docs/defensive-patterns.i18n.yaml             |  2 +-
 docs/defensive-patterns.zh.md                 |  2 +-
 docs/development.i18n.yaml                    |  2 +-
 docs/development.zh.md                        | 14 +++----
 docs/glossary.i18n.yaml                       |  2 +-
 docs/glossary.zh.md                           |  2 +-
 docs/i18n/README.i18n.yaml                    |  2 +-
 docs/i18n/README.zh.md                        | 10 ++---
 docs/i18n/terminology.md                      |  4 +-
 ...0003-web-agent-gui-feedback-loop.i18n.yaml |  2 +-
 .../0003-web-agent-gui-feedback-loop.zh.md    |  2 +-
 ...ice-misclassified-child-failures.i18n.yaml |  2 +-
 ...-notice-misclassified-child-failures.zh.md |  6 +--
 docs/subsystems/README.i18n.yaml              |  2 +-
 docs/subsystems/README.zh.md                  | 16 ++++----
 docs/subsystems/bash.i18n.yaml                |  2 +-
 docs/subsystems/bash.zh.md                    |  2 +-
 docs/subsystems/code-runtime.i18n.yaml        |  2 +-
 docs/subsystems/code-runtime.zh.md            |  4 +-
 docs/subsystems/compaction.i18n.yaml          |  2 +-
 docs/subsystems/compaction.zh.md              |  2 +-
 docs/subsystems/core.i18n.yaml                |  2 +-
 docs/subsystems/core.zh.md                    | 10 ++---
 docs/subsystems/goal.i18n.yaml                |  2 +-
 docs/subsystems/goal.zh.md                    |  2 +-
 docs/subsystems/http-server.i18n.yaml         |  2 +-
 docs/subsystems/http-server.zh.md             |  2 +-
 docs/subsystems/invariants.i18n.yaml          |  2 +-
 docs/subsystems/invariants.zh.md              |  4 +-
 docs/subsystems/llm-streaming.i18n.yaml       |  2 +-
 docs/subsystems/llm-streaming.zh.md           | 10 ++---
 docs/subsystems/persistence.i18n.yaml         |  2 +-
 docs/subsystems/persistence.zh.md             |  2 +-
 docs/subsystems/sandbox.i18n.yaml             |  2 +-
 docs/subsystems/sandbox.zh.md                 |  2 +-
 docs/subsystems/session-projection.i18n.yaml  |  2 +-
 docs/subsystems/session-projection.zh.md      |  2 +-
 docs/subsystems/session-reference.i18n.yaml   |  2 +-
 docs/subsystems/session-reference.zh.md       |  2 +-
 docs/subsystems/session.i18n.yaml             |  2 +-
 docs/subsystems/session.zh.md                 |  8 ++--
 docs/subsystems/skills.i18n.yaml              |  2 +-
 docs/subsystems/skills.zh.md                  |  2 +-
 docs/subsystems/storage.i18n.yaml             |  2 +-
 docs/subsystems/storage.zh.md                 |  2 +-
 docs/subsystems/subagent.i18n.yaml            |  2 +-
 docs/subsystems/subagent.zh.md                |  4 +-
 docs/subsystems/subprocess.i18n.yaml          |  2 +-
 docs/subsystems/subprocess.zh.md              |  2 +-
 docs/subsystems/system-prompt.i18n.yaml       |  2 +-
 docs/subsystems/system-prompt.zh.md           |  2 +-
 docs/subsystems/tasks.i18n.yaml               |  2 +-
 docs/subsystems/tasks.zh.md                   |  4 +-
 docs/subsystems/telemetry.i18n.yaml           |  2 +-
 docs/subsystems/telemetry.zh.md               |  6 +--
 docs/subsystems/tools.i18n.yaml               |  2 +-
 docs/subsystems/tools.zh.md                   |  4 +-
 docs/subsystems/typert.i18n.yaml              |  2 +-
 docs/subsystems/typert.zh.md                  |  2 +-
 docs/subsystems/web.i18n.yaml                 |  2 +-
 docs/subsystems/web.zh.md                     |  2 +-
 docs/testing.i18n.yaml                        |  2 +-
 docs/testing.zh.md                            |  6 +--
 docs/user/develop/framework/events.i18n.yaml  |  2 +-
 docs/user/develop/framework/events.zh.md      |  2 +-
 .../develop/practice/llm-adapter.i18n.yaml    |  2 +-
 docs/user/develop/practice/llm-adapter.zh.md  |  2 +-
 docs/web-styling.i18n.yaml                    |  2 +-
 docs/web-styling.zh.md                        |  6 +--
 examples/acp-agent/README.i18n.yaml           |  2 +-
 examples/acp-agent/README.zh.md               |  4 +-
 examples/web-cordis/README.i18n.yaml          |  2 +-
 examples/web-cordis/README.zh.md              |  2 +-
 native/landlock-run/README.i18n.yaml          |  2 +-
 native/landlock-run/README.zh.md              |  4 +-
 .../packages/entry/README.i18n.yaml           |  2 +-
 .../landlock-run/packages/entry/README.zh.md  |  2 +-
 packages/acp/acp/README.i18n.yaml             |  2 +-
 packages/acp/acp/README.zh.md                 |  2 +-
 packages/api/README.i18n.yaml                 |  2 +-
 packages/api/README.zh.md                     |  4 +-
 packages/api/gateway/README.i18n.yaml         |  2 +-
 packages/api/gateway/README.zh.md             |  4 +-
 packages/api/remotes/README.i18n.yaml         |  2 +-
 packages/api/remotes/README.zh.md             |  2 +-
 packages/bash/bash-env/README.i18n.yaml       |  2 +-
 packages/bash/bash-env/README.zh.md           |  2 +-
 packages/bash/tool-bash/README.i18n.yaml      |  2 +-
 packages/bash/tool-bash/README.zh.md          |  8 ++--
 packages/bash/tool-pwsh/README.i18n.yaml      |  2 +-
 packages/bash/tool-pwsh/README.zh.md          |  6 +--
 packages/boot/README.i18n.yaml                |  2 +-
 packages/boot/README.zh.md                    |  2 +-
 packages/bundle/README.i18n.yaml              |  2 +-
 packages/bundle/README.zh.md                  |  2 +-
 packages/bundle/web-app/README.i18n.yaml      |  2 +-
 packages/bundle/web-app/README.zh.md          |  2 +-
 packages/client/README.i18n.yaml              |  2 +-
 packages/client/README.zh.md                  |  2 +-
 packages/client/connection/README.i18n.yaml   |  2 +-
 packages/client/connection/README.zh.md       |  2 +-
 packages/client/runtime/README.i18n.yaml      |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 packages/client/schema-form/README.i18n.yaml  |  2 +-
 packages/client/schema-form/README.zh.md      |  2 +-
 packages/client/ui-command/README.i18n.yaml   |  2 +-
 packages/client/ui-command/README.zh.md       |  4 +-
 .../client/ui-conversation/README.i18n.yaml   |  2 +-
 packages/client/ui-conversation/README.zh.md  |  4 +-
 packages/client/ui-layout/README.i18n.yaml    |  2 +-
 packages/client/ui-layout/README.zh.md        |  2 +-
 packages/client/ui-model/README.i18n.yaml     |  2 +-
 packages/client/ui-model/README.zh.md         |  2 +-
 packages/client/ui-sidebar/README.i18n.yaml   |  2 +-
 packages/client/ui-sidebar/README.zh.md       |  2 +-
 packages/client/ui-slash/README.i18n.yaml     |  2 +-
 packages/client/ui-slash/README.zh.md         |  4 +-
 packages/client/ui-slots/README.i18n.yaml     |  2 +-
 packages/client/ui-slots/README.zh.md         |  4 +-
 packages/client/ui-theme/README.i18n.yaml     |  2 +-
 packages/client/ui-theme/README.zh.md         |  2 +-
 packages/client/ui-tool/README.i18n.yaml      |  2 +-
 packages/client/ui-tool/README.zh.md          |  6 +--
 .../client/ui-trajectory/README.i18n.yaml     |  2 +-
 packages/client/ui-trajectory/README.zh.md    |  2 +-
 .../code-runtime/README.i18n.yaml             |  2 +-
 .../code-runtime/code-runtime/README.zh.md    |  6 +--
 packages/compact/README.i18n.yaml             |  2 +-
 packages/compact/README.zh.md                 |  2 +-
 .../compact/command-compact/README.i18n.yaml  |  2 +-
 packages/compact/command-compact/README.zh.md |  2 +-
 packages/compact/compact/README.i18n.yaml     |  2 +-
 packages/compact/compact/README.zh.md         |  6 +--
 .../session-reference/README.i18n.yaml        |  2 +-
 .../context/session-reference/README.zh.md    |  4 +-
 packages/core/agent-loop/README.i18n.yaml     |  2 +-
 packages/core/agent-loop/README.zh.md         |  2 +-
 packages/core/agent/README.i18n.yaml          |  2 +-
 packages/core/agent/README.zh.md              |  8 ++--
 packages/core/scope/README.i18n.yaml          |  2 +-
 packages/core/scope/README.zh.md              |  4 +-
 packages/core/system-prompt/README.i18n.yaml  |  2 +-
 packages/core/system-prompt/README.zh.md      |  2 +-
 packages/core/tools/README.i18n.yaml          |  2 +-
 packages/core/tools/README.zh.md              | 10 ++---
 .../examples/jsonrpc-demo/README.i18n.yaml    |  2 +-
 packages/examples/jsonrpc-demo/README.zh.md   |  2 +-
 .../command-feedback/README.i18n.yaml         |  2 +-
 .../feedback/command-feedback/README.zh.md    |  4 +-
 packages/fs/fs/README.i18n.yaml               |  2 +-
 packages/fs/fs/README.zh.md                   |  4 +-
 packages/fs/tool-fs-search/README.i18n.yaml   |  2 +-
 packages/fs/tool-fs-search/README.zh.md       |  4 +-
 packages/fs/tool-fs/README.i18n.yaml          |  2 +-
 packages/fs/tool-fs/README.zh.md              |  4 +-
 packages/goal/command-goal/README.i18n.yaml   |  2 +-
 packages/goal/command-goal/README.zh.md       |  2 +-
 packages/goal/goal-session/README.i18n.yaml   |  2 +-
 packages/goal/goal-session/README.zh.md       |  2 +-
 packages/goal/goal/README.i18n.yaml           |  2 +-
 packages/goal/goal/README.zh.md               |  4 +-
 packages/hooks/hook-protocol/README.i18n.yaml |  2 +-
 packages/hooks/hook-protocol/README.zh.md     |  4 +-
 packages/host/apiproxy/README.i18n.yaml       |  2 +-
 packages/host/apiproxy/README.zh.md           |  4 +-
 .../host/directory-picker/README.i18n.yaml    |  2 +-
 packages/host/directory-picker/README.zh.md   |  4 +-
 packages/host/webserver/README.i18n.yaml      |  2 +-
 packages/host/webserver/README.zh.md          |  2 +-
 packages/interaction/README.i18n.yaml         |  2 +-
 packages/interaction/README.zh.md             |  2 +-
 .../interaction/commands/README.i18n.yaml     |  2 +-
 packages/interaction/commands/README.zh.md    |  6 +--
 packages/llm/llm-deepseek/README.i18n.yaml    |  2 +-
 packages/llm/llm-deepseek/README.zh.md        |  4 +-
 packages/llm/token-meter/README.i18n.yaml     |  2 +-
 packages/llm/token-meter/README.zh.md         |  2 +-
 packages/lsp/lsp/README.i18n.yaml             |  2 +-
 packages/lsp/lsp/README.zh.md                 |  4 +-
 packages/mcp/mcp-client/README.i18n.yaml      |  2 +-
 packages/mcp/mcp-client/README.zh.md          |  2 +-
 packages/pty/pty/README.i18n.yaml             |  2 +-
 packages/pty/pty/README.zh.md                 |  4 +-
 .../pty/tool-bash-persistent/README.i18n.yaml |  2 +-
 .../pty/tool-bash-persistent/README.zh.md     |  4 +-
 packages/sandbox/sandbox/README.i18n.yaml     |  2 +-
 packages/sandbox/sandbox/README.zh.md         |  2 +-
 packages/scaffold/protocol/README.i18n.yaml   |  2 +-
 packages/scaffold/protocol/README.zh.md       |  2 +-
 .../session-query-sqlite/README.i18n.yaml     |  2 +-
 .../session-query-sqlite/README.zh.md         |  4 +-
 .../session-query/README.i18n.yaml            |  2 +-
 .../session-query/session-query/README.zh.md  |  4 +-
 .../README.i18n.yaml                          |  2 +-
 .../session-persistence-jsonl/README.zh.md    |  2 +-
 .../README.i18n.yaml                          |  2 +-
 .../session-persistence-sqlite/README.zh.md   | 10 ++---
 .../session-projection-cache/README.i18n.yaml |  4 +-
 .../session-projection-cache/README.zh.md     |  2 +-
 .../session-projection/README.i18n.yaml       |  2 +-
 .../session/session-projection/README.zh.md   |  4 +-
 .../session-telemetry-otel/README.i18n.yaml   |  2 +-
 .../session-telemetry-otel/README.zh.md       |  2 +-
 .../session-telemetry/README.i18n.yaml        |  2 +-
 .../session/session-telemetry/README.zh.md    |  2 +-
 .../session-title-llm/README.i18n.yaml        |  4 +-
 .../session/session-title-llm/README.zh.md    |  4 +-
 .../session/session-title/README.i18n.yaml    |  2 +-
 packages/session/session-title/README.zh.md   |  4 +-
 packages/settings/settings/README.i18n.yaml   |  2 +-
 packages/settings/settings/README.zh.md       |  2 +-
 packages/skill/skill/README.i18n.yaml         |  2 +-
 packages/skill/skill/README.zh.md             |  6 +--
 packages/spill/spill/README.i18n.yaml         |  2 +-
 packages/spill/spill/README.zh.md             |  2 +-
 .../storage/storage-sqlite/README.i18n.yaml   |  2 +-
 packages/storage/storage-sqlite/README.zh.md  |  2 +-
 .../subagent-claude-code/README.i18n.yaml     |  2 +-
 .../subagent-claude-code/README.zh.md         |  4 +-
 .../subagent/subagent-codex/README.i18n.yaml  |  2 +-
 packages/subagent/subagent-codex/README.zh.md |  6 +--
 .../subagent-dsh-sdk/README.i18n.yaml         |  2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |  2 +-
 .../subagent/subagent-fork/README.i18n.yaml   |  2 +-
 packages/subagent/subagent-fork/README.zh.md  |  2 +-
 .../subagent-inprocess/README.i18n.yaml       |  2 +-
 .../subagent/subagent-inprocess/README.zh.md  |  2 +-
 packages/subagent/subagent/README.i18n.yaml   |  2 +-
 packages/subagent/subagent/README.zh.md       |  6 +--
 .../subagent/tool-subagent/README.i18n.yaml   |  2 +-
 packages/subagent/tool-subagent/README.zh.md  |  2 +-
 .../subprocess/subprocess/README.i18n.yaml    |  2 +-
 packages/subprocess/subprocess/README.zh.md   |  2 +-
 packages/support/README.i18n.yaml             |  2 +-
 packages/support/README.zh.md                 |  6 +--
 .../support/acp-snapshot/README.i18n.yaml     |  2 +-
 packages/support/acp-snapshot/README.zh.md    |  2 +-
 packages/support/invariants/README.i18n.yaml  |  2 +-
 packages/support/invariants/README.zh.md      |  6 +--
 packages/tasks/tasks/README.i18n.yaml         |  2 +-
 packages/tasks/tasks/README.zh.md             |  8 ++--
 packages/typert/registry/README.i18n.yaml     |  2 +-
 packages/typert/registry/README.zh.md         |  2 +-
 packages/typert/type-meta/README.i18n.yaml    |  2 +-
 packages/typert/type-meta/README.zh.md        |  4 +-
 packages/util/README.i18n.yaml                |  2 +-
 packages/util/README.zh.md                    |  2 +-
 packages/util/atomic-write/README.i18n.yaml   |  2 +-
 packages/util/atomic-write/README.zh.md       |  2 +-
 packages/util/environment/README.i18n.yaml    |  2 +-
 packages/util/environment/README.zh.md        |  2 +-
 packages/util/native-command/README.i18n.yaml |  2 +-
 packages/util/native-command/README.zh.md     |  2 +-
 packages/web/README.i18n.yaml                 |  2 +-
 packages/web/README.zh.md                     |  2 +-
 packages/web/tool-web/README.i18n.yaml        |  2 +-
 packages/web/tool-web/README.zh.md            |  2 +-
 .../web/web-search-deepseek/README.i18n.yaml  |  2 +-
 packages/web/web-search-deepseek/README.zh.md |  2 +-
 packages/web/web/README.i18n.yaml             |  2 +-
 packages/web/web/README.zh.md                 |  4 +-
 packages/workflow/README.i18n.yaml            |  2 +-
 packages/workflow/README.zh.md                |  6 +--
 packages/workflow/tool-ralph/README.i18n.yaml |  2 +-
 packages/workflow/tool-ralph/README.zh.md     |  4 +-
 .../workflow/tool-workflow/README.i18n.yaml   |  2 +-
 packages/workflow/tool-workflow/README.zh.md  |  4 +-
 .../workflow-workerthread/README.i18n.yaml    |  2 +-
 .../workflow-workerthread/README.zh.md        |  2 +-
 packages/workflow/workflow/README.i18n.yaml   |  2 +-
 packages/workflow/workflow/README.zh.md       |  6 +--
 packages/workspace/README.i18n.yaml           |  2 +-
 packages/workspace/README.zh.md               |  2 +-
 .../request-response.expected.json            | 10 ++---
 848 files changed, 1506 insertions(+), 1506 deletions(-)

diff --git a/.agents/notes/README.i18n.yaml b/.agents/notes/README.i18n.yaml
index 6eac4fbcce..b33a36665d 100644
--- a/.agents/notes/README.i18n.yaml
+++ b/.agents/notes/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 .agents/notes/README.md
 README.md: 3cfbb5154713046846a3bfcb2ccea62c0e4cb6c0
-README.zh.md: 61887320e9e54b35154c79e33e9a9525aceeef50
+README.zh.md: 4b3a1ee57ea61a8e8ba4d01cf7c719bbf8440e30
diff --git a/.agents/notes/README.zh.md b/.agents/notes/README.zh.md
index 61887320e9..4b3a1ee57e 100644
--- a/.agents/notes/README.zh.md
+++ b/.agents/notes/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这里存放一类设计文档。**Agent Note** 记录塑造本代码库的决策或提案：代码和文档无法承载的*为什么*以及*放弃了什么*。本文件是入口和契约：Agent Note 存放在哪里、何时需要写一份，以及[文件内格式](#the-file-format)。
+这里存放一类设计文档。**Agent Note** 记录塑造本代码库的决策或提案：代码和文档无法承载的*为什么*以及*放弃了什么*。本文件是入口和约定：Agent Note 存放在哪里、何时需要写一份，以及[文件内格式](#the-file-format)。
 
 ## 布局与命名
 
@@ -45,13 +45,13 @@
 
 ## 何时需要写一份
 
-每个非平凡变更都必须在同一 PR（Pull Request）中新增或更新至少一份 Agent Note。如果变更修改了行为、架构、跨文件或跨包契约、流程或工具、测试策略、磁盘存储格式、协议格式（wire format）或配置格式，或者其他维护者可能合理重新审视的决策，就属于非平凡变更。对未来重大工作的提案从 `proposed/` 开始；已经做出的决策从 `implemented/` 开始。选择与决策匹配的类别文件夹（见[分类](#classification)）。
+每个非平凡变更都必须在同一 PR（Pull Request）中新增或更新至少一份 Agent Note。如果变更修改了行为、架构、跨文件或跨包约定、流程或工具、测试策略、磁盘存储格式、协议格式（wire format）或配置格式，或者其他维护者可能合理重新审视的决策，就属于非平凡变更。对未来重大工作的提案从 `proposed/` 开始；已经做出的决策从 `implemented/` 开始。选择与决策匹配的类别文件夹（见[分类](#classification)）。
 
-更新已经拥有该决策的 Agent Note 即可满足规则；不要创建重复记录。只有不涉及行为、契约、结构、流程或理由变化的纯机械性或局部编辑才可豁免。Agent Note 永远不会被编辑为一个*不同的决策*：用新 Agent Note 取代旧记录，并让两个记录保持互相链接，除非后续依据下方规则完全合并旧记录。编辑 `implemented/` Agent Note 以跟踪其现有决策的所在位置是必需的，而非禁止的；见 [implemented/AGENTS.md](implemented/AGENTS.md)。
+更新已经拥有该决策的 Agent Note 即可满足规则；不要创建重复记录。只有不涉及行为、约定、结构、流程或理由变化的纯机械性或局部编辑才可豁免。Agent Note 永远不会被编辑为一个*不同的决策*：用新 Agent Note 取代旧记录，并让两个记录保持互相链接，除非后续依据下方规则完全合并旧记录。编辑 `implemented/` Agent Note 以跟踪其现有决策的所在位置是必需的，而非禁止的；见 [implemented/AGENTS.md](implemented/AGENTS.md)。
 
-被完全取代的 implemented Agent Note 可以合并到当前持有该决策的记录中，并删除原文件。删除前，当前记录必须保存所有独有的决策依据、备选方案、影响、验证契约和明确指出的覆盖缺口；修复所有入站链接；并在同一变更中删除中文对侧文件和一致性记录。仅部分被取代的记录不符合此条件：保留两个记录并让它们互相链接，同时更新所有仍然适用的事实。合并不得将旧文件改写成与其相反的决策，也不得让 git 历史成为决策依据的唯一副本。
+被完全取代的 implemented Agent Note 可以合并到当前持有该决策的记录中，并删除原文件。删除前，当前记录必须保存所有独有的决策依据、备选方案、影响、验证约定和明确指出的覆盖缺口；修复所有入站链接；并在同一变更中删除中文对侧文件和一致性记录。仅部分被取代的记录不符合此条件：保留两个记录并让它们互相链接，同时更新所有仍然适用的事实。合并不得将旧文件改写成与其相反的决策，也不得让 git 历史成为决策依据的唯一副本。
 
-只有当一项功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中完全消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行时，新增该功能的 Agent Note 才可合并进后续的移除记录。移除决策的依据和验证该功能已不存在的测试可以保留。移除决策的持有记录必须保留最初动机、为什么该动机已不足以证明保留该功能的合理性、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。过时的实现清单和只验证已删除行为的测试不属于当前验证契约。仅移除一种传输、默认值、实现或展示属于部分取代；仍有任何持久数据或兼容处理也同样如此。
+只有当一项功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中完全消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行时，新增该功能的 Agent Note 才可合并进后续的移除记录。移除决策的依据和验证该功能已不存在的测试可以保留。移除决策的持有记录必须保留最初动机、为什么该动机已不足以证明保留该功能的合理性、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。过时的实现清单和只验证已删除行为的测试不属于当前验证约定。仅移除一种传输、默认值、实现或展示属于部分取代；仍有任何持久数据或兼容处理也同样如此。
 
 <a id="the-file-format"></a>
 
@@ -79,7 +79,7 @@ Status: <status>
 
 ### 正文骨架
 
-每份 Agent Note 的正文以 `## Problem` 开头：动机，写法上不依赖解决方案即可独立成文。后续内容取决于生命周期；固定章节使用以下规范名称且仅限这些名称，而真正独特的技术章节（包拓扑、协议契约、schema 等）在必需章节之间可自由组织。
+每份 Agent Note 的正文以 `## Problem` 开头：动机，写法上不依赖解决方案即可独立成文。后续内容取决于生命周期；固定章节使用以下规范名称且仅限这些名称，而真正独特的技术章节（包拓扑、协议约定、schema 等）在必需章节之间可自由组织。
 
 #### `proposed/`
 
@@ -126,4 +126,4 @@ Status: <status>
 
 ### 中文对侧文件
 
-`.zh.md` 对侧文件按 [i18n 契约](../../docs/i18n/README.md)逐章节镜像其英文对侧文件的结构；机器检查的头部标记（`# Agent Note: ` 和 `Status:` 行）保持英文原样不翻译。格式门禁跳过 `.zh.md` 文件——配对门禁负责它们的一致性。
+`.zh.md` 对侧文件按 [i18n 约定](../../docs/i18n/README.md)逐章节镜像其英文对侧文件的结构；机器检查的头部标记（`# Agent Note: ` 和 `Status:` 行）保持英文原样不翻译。格式门禁跳过 `.zh.md` 文件——配对门禁负责它们的一致性。
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
index 49a169445e..f89d1da013 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
 2026-06-11-dev-invariants-over-deep-readonly.md: f1a741927cf63b43b1aaf558efc148ff80d2d881
-2026-06-11-dev-invariants-over-deep-readonly.zh.md: 9aadde4f4452a53acce8a3bcf58560ee9722ecfb
+2026-06-11-dev-invariants-over-deep-readonly.zh.md: ade3e20adb8f5301adb87130d42c2bd7a37f8a47
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
index 9aadde4f44..ade3e20adb 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。
 
-单个值的不可变性只是契约的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
+单个值的不可变性只是约定的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
 
 TypeScript readonly 类型不是充分的运行时边界。它们在程序运行时消失，类型转换可以绕过它们，而递归的 `DeepReadonly<T>` 会扩散到每个日志和消息消费方，尽管某些下游请求处理 API 有意使用可变值。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index 03d64c4d4d..2a310c8172 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
 2026-06-13-capability-seams.md: 7c755dced7825d2831acc0901f6412b8e5afe95a
-2026-06-13-capability-seams.zh.md: 3d0fe2b842766838d247aca75972509bf6c7b951
+2026-06-13-capability-seams.zh.md: 31d20bb15f91533ab3c09d337a3cb11f812dbeb4
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
index 3d0fe2b842..31d20bb15f 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化／远程执行器和替代模型提供方。一项能力涉及三个关注点，它们以不同速率、因不同原因变化：*契约*（这项能力是什么）、*实现*（它如何运行）、*消费方接口*（模型和其他插件面向什么编程）。将三者捆绑在一个包中会耦合这些变化速率——把本地执行器换成沙箱化执行器时，模型看到的工具 schema 也会被搅动，尽管面向模型的契约从未改变。
+harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化／远程执行器和替代模型提供方。一项能力涉及三个关注点，它们以不同速率、因不同原因变化：*约定*（这项能力是什么）、*实现*（它如何运行）、*消费方接口*（模型和其他插件面向什么编程）。将三者捆绑在一个包中会耦合这些变化速率——把本地执行器换成沙箱化执行器时，模型看到的工具 schema 也会被搅动，尽管面向模型的约定从未改变。
 
 这与「谁在运行时提供、谁需要一项能力」是不同的问题，后者 Cordis 已通过服务 + `inject` 解决（提供方注册 `ctx.bash`；消费方声明 `inject: ['bash']`，其 fiber 挂起直到服务存在）。该机制是必要的，但不决定包的边界；本 Agent Note 决定的是包的边界。
 
@@ -29,4 +29,4 @@ harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化
 
 ## 后果
 
-每项能力需要更多包和更多样板代码（一组 `package.json`/`tsconfig`/README，加上 inject 接线）。换来的是：实现与消费方独立发布和版本管理，新后端永远不会波及面向模型的契约。该规则记录在 [AGENTS.md](../../../../AGENTS.md) § Conventions（「Capability seams are three packages」）和 [architecture.md](../../../../docs/architecture.md) §「Capability seams」中；bash 三件套是参考模板。何时合并、何时拆分是一个判断问题，架构文档对此有详细说明——本 Agent Note 记录的是*为什么*默认选择拆分。
+每项能力需要更多包和更多样板代码（一组 `package.json`/`tsconfig`/README，加上 inject 接线）。换来的是：实现与消费方独立发布和版本管理，新后端永远不会波及面向模型的约定。该规则记录在 [AGENTS.md](../../../../AGENTS.md) § Conventions（「Capability seams are three packages」）和 [architecture.md](../../../../docs/architecture.md) §「Capability seams」中；bash 三件套是参考模板。何时合并、何时拆分是一个判断问题，架构文档对此有详细说明——本 Agent Note 记录的是*为什么*默认选择拆分。
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
index 6fbbd961a2..d44279eb42 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md
 2026-06-13-twin-llm-adapters.md: a4c87325a0b0d1ebe6cf8f95672e5de74ef37d57
-2026-06-13-twin-llm-adapters.zh.md: 753d7900f23c0d3388be0488c291145fdccf5a95
+2026-06-13-twin-llm-adapters.zh.md: 2af7e7cca4d4c40e18cece1a4dd5c9cdb11901c8
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
index 753d7900f2..2af7e7cca4 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-`dsh-llm` 拥有一套提供方无关的流式词汇：`StreamChunk` 协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）以及内容块类型（[内容块词汇](2026-06-11-content-block-vocabulary.md)）。如果词汇仅针对单个适配器定义，就有可能将该适配器的特异行为固化到「中立」契约中：唯一实现碰巧做了什么，什么就成为事实上的规范；在第二个提供方到来之前，抽象层未经验证——而届时修复这种泄漏的代价已经很高。
+`dsh-llm` 拥有一套提供方无关的流式词汇：`StreamChunk` 协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）以及内容块类型（[内容块词汇](2026-06-11-content-block-vocabulary.md)）。如果词汇仅针对单个适配器定义，就有可能将该适配器的特异行为固化到「中立」约定中：唯一实现碰巧做了什么，什么就成为事实上的规范；在第二个提供方到来之前，抽象层未经验证——而届时修复这种泄漏的代价已经很高。
 
 ## 决策
 
-从一开始就针对同一份契约交付**两个**适配器，刻意基于不同的内部实现构建：
+从一开始就针对同一份约定交付**两个**适配器，刻意基于不同的内部实现构建：
 
 - `dsh-llm-deepseek`：直接 `fetch` + 仓库内翻译逻辑对接 DeepSeek API；SSE（Server-Sent Events）分帧委托给 `eventsource-parser`（[已归档的 SSE 解析器替换](../../archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)）。孪生身份在于自行持有 fetch/translate 内部实现而非委托给完整的提供方 SDK，不在于手写传输层管道。
 - `dsh-llm-pi-ai`：通过 `@earendil-works/pi-ai` 库访问同一端点（该库有自己的事件词汇）。
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index 6737b3f490..bead51ff09 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
 2026-06-14-session-persistence.md: 00e129e57c7144fd62eec26f5854ee21dec4e964
-2026-06-14-session-persistence.zh.md: 6e4e9ece56332ce74b01d60a111617c70e2a874a
+2026-06-14-session-persistence.zh.md: df03dce6bd978f10deb64b8d75ae0685dabab7cd
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index 6e4e9ece56..df03dce6bd 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -27,7 +27,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 契约；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
+上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 约定；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
 
 格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（冷准备时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index ddb215be9f..4511cefb31 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
 2026-06-17-filesystem-capability-seam.md: 7436d2a9402c76f17c7d6571eb489a86e550ebfb
-2026-06-17-filesystem-capability-seam.zh.md: fdeafba387b562352b377321327c526a67669ef6
+2026-06-17-filesystem-capability-seam.zh.md: a96d513d7f4fa793ebb3427e3f7b290862d0d5e9
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index fdeafba387..a96d513d7f 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -10,11 +10,11 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 这把三个独立变化的关注点耦合在了一起：
 
-1. 文件系统契约：插件可以请求哪些操作。
+1. 文件系统约定：插件可以请求哪些操作。
 2. 后端：当前是本地磁盘，未来可能是沙箱/远程/项目作用域的文件系统。
 3. 消费方接口：面向模型的 `read` / `write` / `edit` schema 与结果格式化。
 
-如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的契约应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
+如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的约定应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
 
 我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
 
@@ -55,7 +55,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
 
-## `ctx.fs` 契约
+## `ctx.fs` 约定
 
 `@deepseek-ai/dsh-fs` 拥有一个语义文件系统服务。它比 `readFile` / `writeFile` 更高层，这样 `tool-fs` 就不必重新实现路径解析、版本管理、文本解码、二进制拒绝、分页、原子替换、符号链接行为或字面编辑语义。
 
@@ -98,7 +98,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 策略插件（而非 `ctx.fs`）对先前观测进行门控：`edit` 要求 owner 有先前观测（否则报 `FS_NOT_OBSERVED`），记录的版本作为 CAS 基础传给 `editText`。在策略插件缺席时，`ctx.fs` 本身是一个完整的无约束 seam（无条件写入/编辑）；工具从不与策略方法耦合。
 
-文件系统契约失败以 `FsError extends HarnessError` 抛出，工具注册表将其转换为带结构化 `{ name, code }` 元数据的 `isError` 工具结果。`dsh-fs` 拥有此词汇，而非由每个工具各自发明消息。错误码包括 `FS_NOT_FOUND`、`FS_NOT_TEXT`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_NOT_REGULAR_FILE`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND` 和 `FS_ABORTED`。（早期草案包含 `FS_PARTIAL_OBSERVATION`；基于新鲜度的授权没有 partial/full 区分，因此已删除。目录列表相关的错误码后来由[为文件系统 seam 添加直接目录列举能力](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)添加。）
+文件系统约定失败以 `FsError extends HarnessError` 抛出，工具注册表将其转换为带结构化 `{ name, code }` 元数据的 `isError` 工具结果。`dsh-fs` 拥有此词汇，而非由每个工具各自发明消息。错误码包括 `FS_NOT_FOUND`、`FS_NOT_TEXT`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_NOT_REGULAR_FILE`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND` 和 `FS_ABORTED`。（早期草案包含 `FS_PARTIAL_OBSERVATION`；基于新鲜度的授权没有 partial/full 区分，因此已删除。目录列表相关的错误码后来由[为文件系统 seam 添加直接目录列举能力](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)添加。）
 
 ## 工具消费方行为
 
@@ -119,7 +119,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 该包通过 `ctx.systemPrompt.section(...)` 注册提示词引导，通过 `ctx.tools.register(...)` 注册 schema。工具 schema 仍通过 `SystemPrompt.assemble()` 和 `ToolRegistry.schemas()` 流入正常的提示词组装路径；无需改动 agent loop（智能体循环）。
 
-工具包在后端变化时保持面向模型的契约稳定：本地后端和远程后端内部可能以不同方式解析路径，但 `read` / `write` / `edit` schema 不会仅因后端变化而改变。
+工具包在后端变化时保持面向模型的约定稳定：本地后端和远程后端内部可能以不同方式解析路径，但 `read` / `write` / `edit` schema 不会仅因后端变化而改变。
 
 默认部署要求在用 `write` 或 `edit` 更新已有文件之前先 `read`。`tool-fs` 不通过检查是否运行过名为 `read` 的工具来实现这一点：它分发 `fs/write-intent`/`fs/edit-intent` 事件（将执行上下文作为不透明 actor 传递），`dsh-fs-policy` 插件推导 owner、对先前观测进行门控并提供版本期望。任何窗口化读取都能授权后续的写入/编辑，只要文件未变。用 `write` 创建新文件不要求先前观测。
 
@@ -144,9 +144,9 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 ## 后果
 
-**`cwd` 可能被误认为沙箱。** 本地后端的基目录是解析默认值，而非自动的隔离边界。如果需要隔离，必须由后端契约或 `tools/execute` 上的权限/沙箱插件强制执行。
+**`cwd` 可能被误认为沙箱。** 本地后端的基目录是解析默认值，而非自动的隔离边界。如果需要隔离，必须由后端约定或 `tools/execute` 上的权限/沙箱插件强制执行。
 
-**接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。契约应暴露显示元数据，而不要求消费方理解宿主路径。
+**接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。约定应暴露显示元数据，而不要求消费方理解宿主路径。
 
 **接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本 Agent Note 试图避免的耦合。
 
@@ -154,7 +154,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 **观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方 seam 只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
 
-**`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测契约不变。
+**`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测约定不变。
 
 **观测状态持久化被推迟。** 观测状态存在于内存中（`dsh-fs-policy` 内部的 `WeakMap`），因此恢复的会话保守地要求文件在写入/编辑前重新读取，直到未来的会话事件或持久化机制使观测可回放。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
index 853db24cf1..70c9f791f4 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
 2026-06-18-agent-lifecycle-and-ownership-seams.md: 93247a6da7446a5a67db33423d2b766ce4cf3308
-2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: 7c0f27e1e6ddeec91a8031ef7b1d9fd965a4463a
+2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: e17650c7789764dfb4240132f5903795e6f86381
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
index 7c0f27e1e6..e17650c778 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
@@ -14,7 +14,7 @@ ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 se
 
 ### 1. 队列感知的 `Agent.cancel(cause?)`
 
-`Agent` 接口新增 `cancel()` 动词——唯一的公开停止原语。（它最初与范围更窄、仅作用于步骤的 `abort()` 一同交付；后者后来因无人使用而移除，使 `cancel()` 成为唯一公开的停止工作方式。）它清空 inbox 的 queued + steering FIFO，在存在活跃轮次时中止它，并保留一个不带 cause 的 pre-run 标记，使在被领取前被取消的提示词永不运行，而后来的提示词仍保持独立。有效调用会在清空或中止前发出 `agent/cancel-requested`，携带类型化的 `user | parent` cause；空闲取消不发出任何事件，也不会使下一条提示词搁浅。`whenIdle()` 会在取消后达到完全停稳，ACP 的 `session/cancel` 映射到 `user`。[显式轮次取消决策](2026-07-16-explicit-turn-cancellation.md)规定了当前的 cause、signal 生命周期与协作式结算契约。
+`Agent` 接口新增 `cancel()` 动词——唯一的公开停止原语。（它最初与范围更窄、仅作用于步骤的 `abort()` 一同交付；后者后来因无人使用而移除，使 `cancel()` 成为唯一公开的停止工作方式。）它清空 inbox 的 queued + steering FIFO，在存在活跃轮次时中止它，并保留一个不带 cause 的 pre-run 标记，使在被领取前被取消的提示词永不运行，而后来的提示词仍保持独立。有效调用会在清空或中止前发出 `agent/cancel-requested`，携带类型化的 `user | parent` cause；空闲取消不发出任何事件，也不会使下一条提示词搁浅。`whenIdle()` 会在取消后达到完全停稳，ACP 的 `session/cancel` 映射到 `user`。[显式轮次取消决策](2026-07-16-explicit-turn-cancellation.md)规定了当前的 cause、signal 生命周期与协作式结算约定。
 
 ### 2. `AgentHandle` 异步释放器
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index 911d0709f1..ce26042716 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-session-surface.md
 2026-06-18-session-surface.md: 1bb3baac5e9bea3f657cbd3be2623223bda78ce2
-2026-06-18-session-surface.zh.md: bfbfd097ffeca59dec163dff911315d0ed94d028
+2026-06-18-session-surface.zh.md: b967ad467e58ed4f4b4009fe4746f1b8b6b22f25
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index bfbfd097ff..b967ad467e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -33,7 +33,7 @@ export type SurfaceOp =
 
 ### SurfaceManager：基于增量，而非全量重建
 
-一个 `Session` 拥有一个 `SurfaceManager`，后者维护事件 seq 的有序 `number[]`。管理器会在提交前校验每个种子或追加候选项而不应用它，然后只处理上次同步之后已经提交的事件，而不重新扫描整个日志。`Session.surface` 通过只读的 `SessionSurface` 契约暴露同一个管理器，因此接纳、派生历史、压缩与工作区上下文共享同一份增量状态。Replace 按数组位置定位两个端点（均包含在范围内），并把替换 seq splice 到该范围；不会用第二个管理器、链接对象或 seq 到节点的 map 来重复表达顺序。
+一个 `Session` 拥有一个 `SurfaceManager`，后者维护事件 seq 的有序 `number[]`。管理器会在提交前校验每个种子或追加候选项而不应用它，然后只处理上次同步之后已经提交的事件，而不重新扫描整个日志。`Session.surface` 通过只读的 `SessionSurface` 约定暴露同一个管理器，因此接纳、派生历史、压缩与工作区上下文共享同一份增量状态。Replace 按数组位置定位两个端点（均包含在范围内），并把替换 seq splice 到该范围；不会用第二个管理器、链接对象或 seq 到节点的 map 来重复表达顺序。
 
 无新事件时增量处理为 O(1)，有新事件到达时为 O(新事件数)。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 77c706518c..84edacb9dc 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
 2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
-2026-06-18-shared-persistence-write-coordinator.zh.md: 7c04ee921c9b3f965ef6bd6d2d203cf4cbd50ea2
+2026-06-18-shared-persistence-write-coordinator.zh.md: 0a7fbf351171d305b3b6245832a0b35a283c7c1d
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 7c04ee921c..0a7fbf3511 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 契约，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
+`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 约定，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index 863045f2ce..ebabaccdbb 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
 2026-06-20-generic-long-running-tool-runtime.md: 8cf6a34c3e4fc042bd73c147d83838734dfc9585
-2026-06-20-generic-long-running-tool-runtime.zh.md: 5af06b78e97980822687cdc82d9b0672a42b6fc2
+2026-06-20-generic-long-running-tool-runtime.zh.md: 44241321f6e4da428fe3a6402440af344fd69f10
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index 5af06b78e9..44241321f6 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-后台 bash 原本兼有两项职责：bash 执行器既运行进程，又管理 task id、所有权、增量读取、取消、完成监听器和面向模型的控制工具。新增后台 subagent 需要相同的生命周期与交互契约。如果每种长时间运行能力都独立实现该契约，就会重复隔离、清理、通知和提示词行为，还会让模型为每种生产方学习不同的收集与停止协议。
+后台 bash 原本兼有两项职责：bash 执行器既运行进程，又管理 task id、所有权、增量读取、取消、完成监听器和面向模型的控制工具。新增后台 subagent 需要相同的生命周期与交互约定。如果每种长时间运行能力都独立实现该约定，就会重复隔离、清理、通知和提示词行为，还会让模型为每种生产方学习不同的收集与停止协议。
 
 任务注册表、控制工具与完成通知共同构成一项 harness 功能。bash 和 subagent 只提供执行专属的钩子，不拥有通用任务行为。
 
@@ -21,7 +21,7 @@ Status: implemented
 
 `TaskService` 是 `@deepseek-ai/dsh-tasks` 中的抽象 seam；进程内注册表是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)中）。
 
-## 运行时契约
+## 运行时约定
 
 字面类型见[任务子系统页面](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
@@ -39,7 +39,7 @@ Status: implemented
 
 运行时为 `done` 附加一个 continuation，记录第一个终止结果、解决等待方，并逐个调用完成监听器，同时隔离每个监听器的错误。首次结果优先的结算在资源销毁期间至关重要：如果 `cancel` 抛出，运行时会强制将记录标为失败，并警告工作可能遗留，而不是永远等待一个可能永不完成的 promise。后续生产方结果不能覆盖该诊断，也不能重复通知。`cancel` 返回后如果最终未使 `done` 完成，仍会阻塞资源销毁，因为运行时无法区分这种情况与缓慢但有效的停止。
 
-任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制接口插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守契约的生产方。
+任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制接口插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守约定的生产方。
 
 ## 授权与所有者生命周期
 
@@ -49,7 +49,7 @@ task id 在运行时全局可见且可预测，因此注册表会授权每次访
 
 某个所有者的第一个任务会向 `owner.ctx` 附加一个异步 effect。agent 作用域释放时会取消该所有者的实时任务、等待其终止记录，并移除其快照。该 effect 可跨生产方重载存续，并加入 agent 现有的完全停稳边界。任务服务保留 effect disposer，使服务重载可以在全局资源销毁后，从仍然存活的 agent 作用域中分离回调。
 
-对于遵守契约的生产方，`AgentHandle.dispose()` 只在所属后台工作停止后解决。需要比 agent 存活更久的工作必须以无所有者方式启动；要跨运行时重启存续，则需另行设计持久任务。
+对于遵守约定的生产方，`AgentHandle.dispose()` 只在所属后台工作停止后解决。需要比 agent 存活更久的工作必须以无所有者方式启动；要跨运行时重启存续，则需另行设计持久任务。
 
 ## 服务接口
 
@@ -103,7 +103,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ### 立即抽象任务运行时后端
 
-当前 `TaskStart.run()` 契约传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将契约与进程内实现分离。
+当前 `TaskStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
 
 ### 由消费方负责授权或清理事件
 
@@ -121,7 +121,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ### 随机 id、提升或生命周期会话事件
 
-授权而非不可猜测性才是访问边界，并且 id 不用于派生文件系统路径；顺序生成的品牌化 id 可保持 transcript（文本记录）易读。将前台任务提升为后台任务需要 SDK 并未规定的用户交互契约。启动、读取和通知已作为工具与上下文事件记录，因此专用任务会话事件会重复面向模型的事实。
+授权而非不可猜测性才是访问边界，并且 id 不用于派生文件系统路径；顺序生成的品牌化 id 可保持 transcript（文本记录）易读。将前台任务提升为后台任务需要 SDK 并未规定的用户交互约定。启动、读取和通知已作为工具与上下文事件记录，因此专用任务会话事件会重复面向模型的事实。
 
 ## 测试
 
@@ -129,6 +129,6 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ## 后果
 
-bash 命令与 subagent 共享一套 id 词汇、列表、通知格式、提示词习惯和控制工具。新的长时间运行生产方只需实现执行钩子，而不必再实现一套注册表与工具族。[工具实操手册](../../../../docs/cookbook/adding-a-tool.md)将生产方指向本契约。
+bash 命令与 subagent 共享一套 id 词汇、列表、通知格式、提示词习惯和控制工具。新的长时间运行生产方只需实现执行钩子，而不必再实现一套注册表与工具族。[工具实操手册](../../../../docs/cookbook/adding-a-tool.md)将生产方指向本约定。
 
 有所属后台 bash 会随其 agent 一起停止，不再比 agent 存活更久。后台进程没有执行器超时；调用方必须终止无关工作，或依赖所有者/服务释放。流式读取只支持一个消费方，完成通知不会唤醒空闲 agent；生产方的 `cancel` 返回后如果未使 `done` 完成，仍可能阻塞资源销毁。持久任务、独立观察游标和前台提升仍属于单独设计。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index b038b0e02d..b8540c3319 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
 2026-06-21-bounded-llm-request-recovery.md: 587f2d26eee922e91c8797018964f983890eb8ec
-2026-06-21-bounded-llm-request-recovery.zh.md: 4efe4f946dac90f65f5b8af4a7c36037413616b6
+2026-06-21-bounded-llm-request-recovery.zh.md: dfc5e3ab67b62042c37f05199ed39bf47ded0c5d
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index 4efe4f946d..dfc5e3ab67 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -78,11 +78,11 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 
 `@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。
 
-边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此契约。
+边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此约定。
 
 ### 在现有日志中分隔尝试
 
-一次失败尝试可以在已关闭的步骤中留下 `assistant/chunk` 事件，但绝不会追加 `assistant/message`，也不会分发工具。重试会关闭失败轮次，开启下一个编号轮次，从持久表层重建请求，并生成自己的分片。步骤仍处于打开状态时，UI 可以渲染实时分片；当 `llm/retry` 标识失败步骤，或 `turn/end` 记录失败时，UI 再标记或清除这份暂时视图。Web 会验证完整的重试载荷契约，在 `llm/retry` 到达时清除失败的部分输出，将连续重试轮次的事件投影为稳定的一行，并用最新一次尝试更新该行，再从后续轮次事实派生 scheduled、started 或 cancelled 状态。倒计时以浏览器收到事件的时刻为计划延迟的起点，而不是使用 Host 事件时钟；它按向上取整且不低于 1 秒的秒数显示，仅在重试尚未结束时显示动画，并把最近一次失败的准确详情折叠在该行之后。即使失败尝试没有 assistant 节点，重试节点也会锚定自身的轨迹轮次。消息派生仍会忽略失败分片；Web 在重建历史时也会应用同一投影，因此刷新页面不会让已丢弃的部分输出重新出现，也不会生成重复的重试行。
+一次失败尝试可以在已关闭的步骤中留下 `assistant/chunk` 事件，但绝不会追加 `assistant/message`，也不会分发工具。重试会关闭失败轮次，开启下一个编号轮次，从持久表层重建请求，并生成自己的分片。步骤仍处于打开状态时，UI 可以渲染实时分片；当 `llm/retry` 标识失败步骤，或 `turn/end` 记录失败时，UI 再标记或清除这份暂时视图。Web 会验证完整的重试载荷约定，在 `llm/retry` 到达时清除失败的部分输出，将连续重试轮次的事件投影为稳定的一行，并用最新一次尝试更新该行，再从后续轮次事实派生 scheduled、started 或 cancelled 状态。倒计时以浏览器收到事件的时刻为计划延迟的起点，而不是使用 Host 事件时钟；它按向上取整且不低于 1 秒的秒数显示，仅在重试尚未结束时显示动画，并把最近一次失败的准确详情折叠在该行之后。即使失败尝试没有 assistant 节点，重试节点也会锚定自身的轨迹轮次。消息派生仍会忽略失败分片；Web 在重建历史时也会应用同一投影，因此刷新页面不会让已丢弃的部分输出重新出现，也不会生成重复的重试行。
 
 如果恢复预算耗尽，最终失败会连同结构化事实在 `turn/end.reason` 中存储一次。Web 会在该序列位置派生一个 `turn-error` 节点，并内联渲染适合展示的消息与可选错误码；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。实时事件和历史回放使用同一套折叠逻辑。如果暂时性恢复继续，`llm/retry` 就是该次尝试的失败与延迟的持久归属位置，因此该失败轮次不会再获得终态错误行。本决策不增加独立的最终错误事件或响应 id 词汇。
 
@@ -126,7 +126,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - 提供方 SDK 可能隐藏状态或重试标头。适配器会保留 SDK 公开的稳定事实，否则使用粗粒度 code，而不会让恢复策略解析脆弱的文本。
 - 持久重试事件扩展了会话协议和 UI 状态机。事件与其消费方一同交付，可避免产生无人使用的遥测词汇；但以后更改 schema 仍需要同步完成持久化和回放工作。
 - 清除失败步骤的实时分片可能会明显撤回输出。与把丢弃的文本或不完整工具 JSON 呈现为已提交历史相比，这是更好的选择；快照固定这一转换。
-- 适配器局部的空闲强制机制可以终止停滞的传输，而不会计入消费方思考时间。每个传输边界的契约测试会防止 SDK 漂移。
+- 适配器局部的空闲强制机制可以终止停滞的传输，而不会计入消费方思考时间。每个传输边界的约定测试会防止 SDK 漂移。
 - 多个 normal 恢复插件会叠加各自的有限预算。always mode 会先委托，再提供无界回退；重叠的分类器仍会形成依赖注册顺序的策略，必须由引入它们的插件记录并测试。
 
 ## 相关资料
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index b3db1ae497..43c2f227df 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
 2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: a10abff8d6e2addf196bf48e2634110aa5e13b3b
+2026-06-21-mandatory-app-attribution-headers.zh.md: d2f7300467790c0a67cfa0ab6222c40c9ee10311
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index a10abff8d6..d2f7300467 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -12,15 +12,15 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 ## 调研
 
-- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一份具体的 OpenRouter 契约，而非 IETF 或 OpenAI 兼容 API 标准。
+- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一份具体的 OpenRouter 约定，而非 IETF 或 OpenAI 兼容 API 标准。
 - **在 agent 工具生态中，`HTTP-Referer` 是一种 OpenRouter 感知的约定，而非通用 agent 约定。** 它足够常见，以至于 OpenRouter SDK 和示例直接暴露它，面向 OpenRouter 的框架通常需要一种方式来透传它。但 ACP（Agent Client Protocol）等 agent 协议在自己的 initialize 消息中协商名称、版本和能力，而模型提供方请求仍需 HTTP 层面的身份标识。因此「在 agent 世界中被接受」意味着「被 OpenRouter 集成所识别」，而非「可跨 agent 运行时或提供方移植」。
-- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同契约；不存在通用的精确格式。
+- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同约定；不存在通用的精确格式。
 - **标准化的通用客户端身份头部是 `User-Agent`。** RFC 9110 第 10.1.5 节将 `User-Agent` 定义为用户代理软件身份，说明它用于互操作性报告和分析，并说用户代理应当在每个请求中发送它（除非被配置为不发送）。这是唯一直接对应「哪个产品在发出此 HTTP 请求」的标准头部。
 - **`Referer` 是标准的，但 OpenRouter 的 `HTTP-Referer` 不是标准字段。** RFC 9110 第 10.1.3 节将 `Referer` 定义为获取目标 URI 的来源 URI，并用大量篇幅讨论隐私限制。OpenRouter 则要求 `HTTP-Referer`，将其用作应用 URL 标识符。该名称和含义是 OpenRouter 特有的，尽管它形似标准 `Referer` 头部的 CGI 环境变量形式。
 - **`From` 是标准的，但不适合作为强制默认值。** RFC 9110 第 10.1.2 节将 `From` 定义为负责用户代理的人的电子邮件地址。机器人代理应当发送它以便服务器联系运营者，但非机器人代理出于隐私和安全策略考虑不应在未经用户显式配置的情况下发送。harness 可以后续支持运营者联系方式，但不得凭空捏造或全局强制要求。
 - **请求体中的 `user` 或 `metadata` 字段不是应用归属。** 部分模型 API 暴露稳定的终端用户标识符、请求元数据、标签或项目/账户头部。这些对滥用监控、内部计费、仪表盘或链路追踪有用，但它们要么标识的是终端用户而非产品，要么是提供方特有的 body schema，要么不保证能通过 OpenAI 兼容网关透传。它们不能替代静态的应用身份头部。
 - **SDK 遥测头部标识的是 SDK，而非应用。** 官方和第三方 SDK 常发送库/版本头部。这些帮助 SDK 维护者调试其客户端，但除非应用显式提供产品归属层，否则它们不能标识 harness 作为应用。
-- **pi-ai 有原生支持的头部钩子。** `@earendil-works/pi-ai` 的 `StreamOptions.headers` 将调用方头部最后合并（覆盖提供方默认值），因此基于库的适配器无需包装或上游改动即可满足与手写适配器相同的线路契约。mock 服务器测试套件对两个适配器都断言头部到达了线路。
+- **pi-ai 有原生支持的头部钩子。** `@earendil-works/pi-ai` 的 `StreamOptions.headers` 将调用方头部最后合并（覆盖提供方默认值），因此基于库的适配器无需包装或上游改动即可满足与手写适配器相同的线路约定。mock 服务器测试套件对两个适配器都断言头部到达了线路。
 
 ## 决策
 
@@ -41,7 +41,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 | 目标 | 映射 |
 |---|---|
 | 所有基于 HTTP 的适配器 | `User-Agent: {product}/{version} (+{url})`——括号中的 `+url` 注释符合 RFC 9110 保守的 product/comment 语法。 |
-| 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效契约，否则不发送 OpenRouter 特有头部。 |
+| 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效约定，否则不发送 OpenRouter 特有头部。 |
 | OpenRouter 端点 | 目前仅 `User-Agent`。本 Agent Note 下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
 | 未来提供方 | 仅 `User-Agent`，除非后续提供方特有的 Agent Note 接受额外头部。不要类比复用 `HTTP-Referer`。 |
 
@@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 已落地的约定：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属约定（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
@@ -63,7 +63,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
 
-**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 契约当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
+**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 约定当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
 
 **仅使用提供方账户/项目身份。** 否决。组织/项目头部、API key、云账户和计费项目标识的是谁付费或谁拥有请求，而非哪个应用在发送流量。它们也不暴露公开的应用标题/类别，无法帮助 OpenRouter 等网关构建应用排名。
 
@@ -79,6 +79,6 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个阻塞发布的悬空承诺。
 
-**不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 pi-ai 的适配器依赖 pi-ai 继续尊重 `StreamOptions.headers`（最后合并覆盖提供方默认值）。线路级 mock 服务器测试是守卫：如果 pi-ai 升级后不再投递该头部，套件会变红。这对抽象施加了有益的压力：一个无法设置强制头部的提供方适配器不能完整实现 harness 的 LLM 契约。
+**不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 pi-ai 的适配器依赖 pi-ai 继续尊重 `StreamOptions.headers`（最后合并覆盖提供方默认值）。线路级 mock 服务器测试是守卫：如果 pi-ai 升级后不再投递该头部，套件会变红。这对抽象施加了有益的压力：一个无法设置强制头部的提供方适配器不能完整实现 harness 的 LLM 约定。
 
 **OpenRouter 排名尚未受益。** `User-Agent` 是提供方无关的 HTTP 身份的正确基线，但它不会创建 OpenRouter 应用页面或排名，因为 OpenRouter 要求 `HTTP-Referer` 来实现该产品功能。这是有意为之：公开应用市场参与是一个独立的产品决策，不是强制请求归属的前提。
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index fc370429b6..870afbe428 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
 2026-06-24-web-capability-seam.md: b705236690859961ed69b307dbb59ebefcbd65ac
-2026-06-24-web-capability-seam.zh.md: e3dc836004bf785c6811e4c4014e105266dbaade
+2026-06-24-web-capability-seam.zh.md: 987640dd5c8ee428a181ffd31d1e8e3803fe03a8
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index e3dc836004..987640dd5c 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-harness 需要面向模型的 web 工具，但不能将模型契约绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 seam 并非只是镜像某一家厂商。Fetch 是另一项独立能力：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
+harness 需要面向模型的 web 工具，但不能将模型约定绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 seam 并非只是镜像某一家厂商。Fetch 是另一项独立能力：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
 
 面向模型的接口必须保持稳定，而后端可以更换。更换搜索提供方不应改变模型发起查询的方式；更换 fetch 实现不应改变模型请求 URL 的方式。反过来，提供方包也不应仅仅因为自己有额外的提供方特有旋钮就暴露自己的面向模型工具 schema。
 
-如果把搜索和 fetch 直接放进 `dsh-tool-web`，面向模型的工具就要同时承担提供方选择、后端请求映射、传输策略、结果归一化、提示词引导、展示和 schema 注册。让每个提供方注册自己的工具则有相反的问题：工具的可用性、名称、描述和参数将取决于恰好加载了哪些提供方包，提供方特有字段会泄漏到模型契约中。
+如果把搜索和 fetch 直接放进 `dsh-tool-web`，面向模型的工具就要同时承担提供方选择、后端请求映射、传输策略、结果归一化、提示词引导、展示和 schema 注册。让每个提供方注册自己的工具则有相反的问题：工具的可用性、名称、描述和参数将取决于恰好加载了哪些提供方包，提供方特有字段会泄漏到模型约定中。
 
 还有一个提供方选择的问题。现有的 `tool-bash` 和 `tool-fs` 可以依赖 Cordis 的 `inject`，因为只有一个后端服务键。Web 有两项独立能力（`search` 和 `fetch`），每项能力可能有多个提供方。`inject: ['web']` 能证明 seam 存在，但不能证明存在可用的搜索或 fetch 提供方，也无法定义多个提供方注册时谁胜出。
 
@@ -32,7 +32,7 @@ Web 访问是一个一等能力 seam，遵循[能力 seam Agent Note](2026-06-13
 - 工具绝不会仅仅因为其选定的提供方缺失、配置错误、缺少凭证、存在歧义或暂时不可用就被注销。
 - 提供方在执行时解析，当选定的能力无法运行时返回结构化的 `WebError`。
 
-这使模型 schema 保持稳定，而不将插件加载顺序、凭证状态或 HMR（热模块替换）时序纳入面向模型的契约。如果 web 搜索已启用但不存在可用的搜索提供方，`web_search` 仍然可见，执行时以结构化的 `WebError`（如 `WEB_PROVIDER_UNAVAILABLE` 或 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`）失败。如果某个提供方在 `dsh-tool-web` 之后出现，下一次执行即可使用它而无需更改 schema。如果某个提供方在调用过程中消失，执行以结构化的 `WebError` 失败，而不是静默选择另一个提供方或回退到 `UNKNOWN_TOOL`。
+这使模型 schema 保持稳定，而不将插件加载顺序、凭证状态或 HMR（热模块替换）时序纳入面向模型的约定。如果 web 搜索已启用但不存在可用的搜索提供方，`web_search` 仍然可见，执行时以结构化的 `WebError`（如 `WEB_PROVIDER_UNAVAILABLE` 或 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`）失败。如果某个提供方在 `dsh-tool-web` 之后出现，下一次执行即可使用它而无需更改 schema。如果某个提供方在调用过程中消失，执行以结构化的 `WebError` 失败，而不是静默选择另一个提供方或回退到 `UNKNOWN_TOOL`。
 
 该 seam 刻意不暴露任何观察面——没有注册表变更事件，也没有聚合的能力状态查询。不可用性是调用方通过执行观察到的事实：`search()`/`fetch()` 在调用时解析提供方，并抛出命名了失败原因的结构化 `WebError`。[观察面 Agent Note](../../archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md) 记录了这一判断：基于调用的派生选择与基于启用的注册使得没有消费方需要变更信号或独立于执行和错误路由的可用性探测；未来的提供方状态面板会重新引入它实际消费的最小信号或查询。
 
@@ -66,13 +66,13 @@ flowchart LR
   toolWeb -->|ctx.tools.register| webFetch["tool: web_fetch"]
 ```
 
-`@deepseek-ai/dsh-web` 仅依赖 Cordis 和底层 harness 支持。它声明 `ctx.web`、提供方接口、请求/结果类型、提供方可用性契约和错误码。它不导入工具、agent、会话、LLM 或提供方包。
+`@deepseek-ai/dsh-web` 仅依赖 Cordis 和底层 harness 支持。它声明 `ctx.web`、提供方接口、请求/结果类型、提供方可用性约定和错误码。它不导入工具、agent、会话、LLM 或提供方包。
 
 提供方包仅依赖 `dsh-web` 和 Cordis。它们拥有凭证、端点、协议格式映射、解析和 `WebError` 转换，使用平台 `fetch`。每个提供方注入共享服务并注册后端；只有 `dsh-web` 拥有 `ctx.web` 键。提供方私有的协议形状不会产生对 `ctx.llm` 或 Cordis HTTP 服务的依赖。
 
 `@deepseek-ai/dsh-tool-web` 依赖 `@deepseek-ai/dsh-web`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 Cordis。它从不导入具体的提供方包。
 
-## `ctx.web` 契约
+## `ctx.web` 约定
 
 `ctx.web` 是一个提供方注册表加上一个带提供方选择的执行面。注册表部分与 `LlmService` 保持接近：每种能力类别一个 `Map<id, provider>`，`registerSearchProvider`/`registerFetchProvider` 方法返回 disposer，重复 id 抛出 `WebError`，执行时解析在选定提供方缺失或不可用时抛出异常。权威签名见 `packages/web/web/src/types.ts`；seam 的形状：
 
@@ -280,7 +280,7 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 ## 测试
 
-每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 契约与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
+每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 约定与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index 3463e0d6b1..726ab7374d 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
 2026-06-26-file-context-as-event-gate.md: 4700222aa2e0f91d9f355495c228e2eb92825f55
-2026-06-26-file-context-as-event-gate.zh.md: e0a3619859c2ab4eb99f7cbf69375f9fe40d10b7
+2026-06-26-file-context-as-event-gate.zh.md: dff5c3e9ea99e73d3d1a86c4012da1e4232021bb
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index e0a3619859..dff5c3e9ea 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -44,7 +44,7 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 这是有意为之的。如果 `dsh-fs-policy` 在其 waterfall（瀑布式事件）处理器中 stat 并比较版本，该检查与工具实际写入之间会存在 TOCTOU 间隙——文件可能在此期间变化，因此该检查只是一个虚假保证，提供方的锁无论如何都要兜底。将版本检查放在提供方的临界区中既无竞态又无额外 `stat`。所以 `dsh-fs-policy` **不做**任何文件系统 I/O；「必须基于最近一次读取」的保证由 CAS *实现*，`dsh-fs-policy` 只负责选择基准（`vObserved`）并对先前观测进行门控。
 
-## 提供方契约变更：版本守卫变为可选
+## 提供方约定变更：版本守卫变为可选
 
 为使裸提供方不受约束，其两个 mutation 上的版本守卫变为**可选**——传入则守卫，省略则无条件执行：
 
@@ -66,7 +66,7 @@ editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion
 
 ## 事件词汇（由 `dsh-fs` 拥有）
 
-事件定义在 `@deepseek-ai/dsh-fs` 中，而非 `dsh-fs-policy` 中。这是解耦契约所迫：`dsh-tool-fs` 是发射方，因此它必须引用事件类型，且即使 `dsh-fs-policy` 不再提供方法服务，它也必须能编译通过。`dsh-fs` 是 `dsh-tool-fs` 和 `dsh-fs-policy` 都已依赖的包，因此它是唯一能让发射方和策略监听方共享词汇而不让发射方依赖策略插件的归属地。
+事件定义在 `@deepseek-ai/dsh-fs` 中，而非 `dsh-fs-policy` 中。这是解耦约定所迫：`dsh-tool-fs` 是发射方，因此它必须引用事件类型，且即使 `dsh-fs-policy` 不再提供方法服务，它也必须能编译通过。`dsh-fs` 是 `dsh-tool-fs` 和 `dsh-fs-policy` 都已依赖的包，因此它是唯一能让发射方和策略监听方共享词汇而不让发射方依赖策略插件的归属地。
 
 这些事件携带既有的 `dsh-fs` 词汇（`FsTarget`、`FsVersion`、`FsWriteIntent`）加一个不透明的 actor——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
 
@@ -108,7 +108,7 @@ interface Events {
 
 `fs/*` 决策事件是**由工具分发的无绑定 waterfall**（类似 `agent/request`，由循环分发且无 `this`），而非服务绑定的 waterfall（如 `llm/stream`）。分发者是 `dsh-tool-fs` 插件，它不是一个服务。
 
-## 工具契约（`dsh-tool-fs`）
+## 工具约定（`dsh-tool-fs`）
 
 工具保留其面向模型的 schema（`read`/`write`/`edit`，逐字节不变）和提示词段落。提示词引导仍以策略优先，因为加载 fs 工具的部署预期也会加载 `dsh-fs-policy`：模型仍被告知在覆写或编辑前先读取，任何声称「后端」要求如此的措辞应修正为 fs-policy 插件要求如此。裸提供方回退不改变提示词立场。
 
@@ -124,9 +124,9 @@ interface Events {
 
 工具在每次分发时将 `exec`（工具执行上下文）作为 `actor` 参数传入，以便 `dsh-fs-policy` 推导其观测状态的 owner。工具不知道策略插件是否存在：它始终在 `next` thunk 中提供裸默认行为，而 `dsh-fs-policy` 在默认部署中会在 thunk 运行前短路它。
 
-**`fs/observed` 在操作成功后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器会在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件契约。
+**`fs/observed` 在操作成功后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器会在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件约定。
 
-## 策略插件契约（`dsh-fs-policy`）
+## 策略插件约定（`dsh-fs-policy`）
 
 `dsh-fs-policy` 是插件，不是服务。它不注册 `ctx.fileContext`，没有公开方法面，不暴露 `read`/`write`/`edit`/`resolve` 方法。它通过 `ctx.on()` 注册三个监听器（每个返回一个 disposer 用于 HMR）。它维护观测状态 `WeakMap<owner, Map<targetKey, { version }>>`，以及结构化的 owner 推导（将事件中不透明的 `object` actor 收窄为自己的 `{ agent?: { session? } }` 形状），但不注入 `fs`——每个处理器只操作自己的 `WeakMap`，从不操作 `ctx.fs`。
 
@@ -150,7 +150,7 @@ interface Events {
 
 ## 取代关系
 
-本 Agent Note 修正——而非推翻——[拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md)。四层拆分、提供方契约和新鲜度*策略*均保留。变更的是**工具与策略层之间的耦合方式**：强制性方法服务变为插件拥有的事件门控，fs I/O + 读取窗口从 `fileContext` 上移至 `dsh-tool-fs`。拆分文件系统 seam Agent Note 中关于 `dsh-tool-fs` 注入 `fileContext` 以及 `fileContext` 拥有 `read`/`write`/`edit` 的描述已在同一变更中更新。
+本 Agent Note 修正——而非推翻——[拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md)。四层拆分、提供方约定和新鲜度*策略*均保留。变更的是**工具与策略层之间的耦合方式**：强制性方法服务变为插件拥有的事件门控，fs I/O + 读取窗口从 `fileContext` 上移至 `dsh-tool-fs`。拆分文件系统 seam Agent Note 中关于 `dsh-tool-fs` 注入 `fileContext` 以及 `fileContext` 拥有 `read`/`write`/`edit` 的描述已在同一变更中更新。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
index 072823d0dc..d467684e40 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
 2026-07-02-tool-render-intent-union.md: 67607b2848305439513503d7e03ad5e2a2e4020a
-2026-07-02-tool-render-intent-union.zh.md: 9cbab75ce87f6d313ca4b6ac8dda043733361f0d
+2026-07-02-tool-render-intent-union.zh.md: f69442cc1cf226a5dd949fc3890029a69a639953
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
index 9cbab75ce8..f69442cc1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
@@ -63,7 +63,7 @@ terminal 意图只用于展示。harness 仍通过自身的 bash 服务执行命
 ## 曾考虑的替代方案
 
 - **完全删除工具自有的展示**：即本 Agent Note 所取代的那个被否决的 collapse 提案；其自身的结论正是推迟到两个真实工具和两个真实消费方存在后再做此联合类型，该条件现已满足。
-- **让 UI 执行 terminal 意图**：否决。这样会绕过 harness 的 bash 策略与归属契约，并把命令执行分裂到不同后端。terminal 卡片描述的是 harness 拥有的执行，绝不授权客户端侧执行。
+- **让 UI 执行 terminal 意图**：否决。这样会绕过 harness 的 bash 策略与归属约定，并把命令执行分裂到不同后端。terminal 卡片描述的是 harness 拥有的执行，绝不授权客户端侧执行。
 - **可合并扩展的联合类型**（`ContentBlockMap` 模式）：否决。新的渲染意图无论如何需要新的 bridge 代码来渲染，因此一个被 bridge 静默丢弃的插件添加变体，比封闭联合类型在 bridge 的 `assertNever` switch 处引发的编译错误更糟糕。
 - **保留可选字段集合**：即「问题」一节所剖析的现状：无效状态可表达、字段交互无文档、且完全无法请求 diff 卡片。
 
@@ -78,5 +78,5 @@ terminal 意图只用于展示。harness 仍通过自身的 bash 服务执行命
 ## 相关
 
 - 取代早先被否决的折叠工具自有呈现提案（已否决——「等两个真实工具和两个真实消费方，然后做带标签 render-intent 联合类型」）中的推迟决定。该条件现已满足；本 Agent Note 即为那个联合类型。
-- 被[结果时已应用 hunk 差异](../../archived/architecture/2026-07-02-result-time-applied-hunk-diffs.md)（已归档）扩展：后者添加了一个持久化的 `meta` 通道，使 write/edit 在结果时输出 `DiffResultView`（应用后的变更：带上下文行的 contextual hunk / 每个 `replace_all` 位点一个，或创建时的整文件 diff）——值/呈现拆分与持久化的 `presentationMeta` 通道现由[规范工具输出契约](2026-07-20-canonical-tool-output-contract.md)拥有。
+- 被[结果时已应用 hunk 差异](../../archived/architecture/2026-07-02-result-time-applied-hunk-diffs.md)（已归档）扩展：后者添加了一个持久化的 `meta` 通道，使 write/edit 在结果时输出 `DiffResultView`（应用后的变更：带上下文行的 contextual hunk / 每个 `replace_all` 位点一个，或创建时的整文件 diff）——值/呈现拆分与持久化的 `presentationMeta` 通道现由[规范工具输出约定](2026-07-20-canonical-tool-output-contract.md)拥有。
 - 将 `ToolTerminal` 折入当前 UI 传输层使用的带标签 `terminal` 视图。
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index 26354042d7..f80e5c3c77 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
 2026-07-05-prompt-variables-and-tool-guidance-ownership.md: a3b5021daf323971308760bde4f97651db8edbda
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 490d41302ea4f4e14e11e301acbf47170f95cace
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 0b84f188e6637d8b1b42ed2e6df3cd7e4061d75d
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 490d41302e..0b84f188e6 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 
 ### 工具指导归属
 
-每个工具的语义和选择指导放在工具 description 中。提示词 section 只承载跨调用习惯，例如检查 bash 退出标记或优先使用文件系统工具而非 shell 命令。`todo_write` 和 subagent 工具不需要 section，因为它们的 description 包含完整契约。部署 persona 只包含角色和行为。
+每个工具的语义和选择指导放在工具 description 中。提示词 section 只承载跨调用习惯，例如检查 bash 退出标记或优先使用文件系统工具而非 shell 命令。`todo_write` 和 subagent 工具不需要 section，因为它们的 description 包含完整约定。部署 persona 只包含角色和行为。
 
 ### Subagent 对话历史描述符
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
index 46aebedb0a..951017ba47 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
 2026-07-05-windows-jsonl-durable-publish.md: 38c4adc7a4f85d45e53e70fcac84073ab4e50775
-2026-07-05-windows-jsonl-durable-publish.zh.md: 3a91b7dab0751ad1b7ac1a425371ccf62d23e89c
+2026-07-05-windows-jsonl-durable-publish.zh.md: 205460bcd374bd351cfdf541eb4041c09461229d
diff --git a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md
index 3a91b7dab0..205460bcd3 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-`dsh-session-persistence-jsonl` 在首次追加时延迟发布会话日志。POSIX 协议会写入临时文件，对其执行 fsync，将其链接至最终名称，对父目录执行 fsync，然后移除临时链接。对父目录执行 fsync 是持久性契约的一部分：命名空间变更后发生崩溃时，已经提交的最终名称不能丢失，否则调用方会误以为会话日志已经物化。
+`dsh-session-persistence-jsonl` 在首次追加时延迟发布会话日志。POSIX 协议会写入临时文件，对其执行 fsync，将其链接至最终名称，对父目录执行 fsync，然后移除临时链接。对父目录执行 fsync 是持久性约定的一部分：命名空间变更后发生崩溃时，已经提交的最终名称不能丢失，否则调用方会误以为会话日志已经物化。
 
-Windows 具备原子命名空间操作，但 Node 没有暴露与 POSIX 等价的父目录 fsync 契约。如果把 Windows 目录同步失败视为成功，就会在无提示的情况下削弱持久化后端。因此，Windows 路径需要采用不同的发布原语，而不是在 POSIX 的 `syncDir` 辅助函数中添加条件分支。
+Windows 具备原子命名空间操作，但 Node 没有暴露与 POSIX 等价的父目录 fsync 约定。如果把 Windows 目录同步失败视为成功，就会在无提示的情况下削弱持久化后端。因此，Windows 路径需要采用不同的发布原语，而不是在 POSIX 的 `syncDir` 辅助函数中添加条件分支。
 
 ## 决策
 
@@ -28,8 +28,8 @@ Windows 通过持久的暂存发布来创建缺失目录：创建一个以固定
 
 ## 影响
 
-该后端在各平台上维持同一项外部契约：首次追加要么把完整日志发布到最终名称，要么失败且不覆盖已有日志。平台分流只是实现细节；`SessionPersistence` API 和 JSONL 逻辑记录格式均不改变。后续的 [Zstandard 编码决策](2026-07-19-zstandard-jsonl-session-logs.md)会先作用于不透明字节，然后才由任一平台执行发布。
+该后端在各平台上维持同一项外部约定：首次追加要么把完整日志发布到最终名称，要么失败且不覆盖已有日志。平台分流只是实现细节；`SessionPersistence` API 和 JSONL 逻辑记录格式均不改变。后续的 [Zstandard 编码决策](2026-07-19-zstandard-jsonl-session-logs.md)会先作用于不透明字节，然后才由任一平台执行发布。
 
-Windows 测试会在原生 Windows 上执行真实的 Win32 发布路径。断电行为属于 API 契约属性，单元测试无法证明；可测试的不变量包括：Windows 物化不会调用目录 fsync、最终路径冲突会失败、达到最大长度的目标路径组件仍可物化、临时日志在发布前已经执行 fsync，并且生成的日志可以正常加载。
+Windows 测试会在原生 Windows 上执行真实的 Win32 发布路径。断电行为属于 API 约定属性，单元测试无法证明；可测试的不变量包括：Windows 物化不会调用目录 fsync、最终路径冲突会失败、达到最大长度的目标路径组件仍可物化、临时日志在发布前已经执行 fsync，并且生成的日志可以正常加载。
 
 两个平台的追加和修复仍使用普通文件句柄 fsync。追加失败后，系统会关闭仅追加句柄，以读写模式重新打开日志，将文件截断到追加前的大小，并对回滚结果执行 fsync，因为 Windows 不允许在仅追加句柄上调用 `ftruncate`。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index c43bfd8960..24a047b540 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
 2026-07-06-timeout-deadline-library.md: 63463a76a65743436d4e78479800c19e257a42de
-2026-07-06-timeout-deadline-library.zh.md: 16f1a7eba902e6d7b3e2f730cb5df702a37bd429
+2026-07-06-timeout-deadline-library.zh.md: c47e6d4e6ed0bec368fca8857e5bd4d7229b6b0e
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index 16f1a7eba9..c47e6d4e6e 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -77,7 +77,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 | 关注点 | 负责方 |
 |---|---|
-| 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求契约 |
+| 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求约定 |
 | 启动一次性定时器、到期中止、携带 reason、与上游取消融合 | `dsh-timeout`（`deadline`） |
 | 仅围绕未结算的迭代器 demand 启动和重启 | `dsh-timeout`（`idleWatchdog`） |
 | 清除定时器 | `dsh-timeout`（任一原语的 `[Symbol.dispose]`） |
@@ -90,7 +90,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 ### 各能力如何消费该库
 
-- **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码契约不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。
+- **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码约定不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。
 - **bash**：`resolve()` 将请求钳位为显式规格。前台 `run()` 创建 deadline 并将其信号传给进程执行，后者既有的 abort 监听器执行进程组 kill。执行器将首个 abort 分类为超时或取消。后台启动保持无超时，仅转发上游取消。
 - **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。
 
@@ -100,7 +100,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
-- 模型流现在共享一个可重启的定时器契约，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
+- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
 
 以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在实现后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
index 17381d7269..29c7c13813 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md
 2026-07-06-tool-result-retention-library.md: 5e42660360e5a23b419c75b9c8006bec459bc322
-2026-07-06-tool-result-retention-library.zh.md: 422c301ba5f1aab33a54e1deffe42f390bcb662d
+2026-07-06-tool-result-retention-library.zh.md: 2a523e2eff36daf9100ac10bf5ae569eca30f830
diff --git a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md
index 422c301ba5..2a523e2eff 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md
@@ -95,7 +95,7 @@ type TextRetentionStrategy =
 
 ### 工具映射
 
-`read` 被有意排除在 v1 保留库之外。它的 `read-render` 辅助函数拥有文件专用的分页契约：`offset`／`limit`、行号、`totalLines`、offset 越界错误、逐行预览截断，以及能够在窗口中途停止扫描的所选输出字节上限。这是行窗口渲染器，不是通用保留原语。它未来可以共享中性的提示辅助函数，但不应把已经选定的窗口再传入 `ItemRetainer`。
+`read` 被有意排除在 v1 保留库之外。它的 `read-render` 辅助函数拥有文件专用的分页约定：`offset`／`limit`、行号、`totalLines`、offset 越界错误、逐行预览截断，以及能够在窗口中途停止扫描的所选输出字节上限。这是行窗口渲染器，不是通用保留原语。它未来可以共享中性的提示辅助函数，但不应把已经选定的窗口再传入 `ItemRetainer`。
 
 下文的 `FsGlobEntry` 与 `FlatGrepMatch` 是预期由发现工具使用的条目形态，不是现有保留库的导出。`FsGlobEntry` 是一个由后端派生的路径；`FlatGrepMatch` 是后端将保留匹配项按文件分组之前的一条未分组 grep 匹配。
 
@@ -138,7 +138,7 @@ const formatGrepNotice = (notice: RetentionNotice): string =>
 
 **已交付内容。** `@deepseek-ai/dsh-retention` 导出 `ItemRetainer`、`TextRetainer`、结果类型（`RetainedItems`、`RetainedText`）、策略类型（`ItemRetentionStrategy`、`TextRetentionStrategy`）、`Omitted`、`PushDecision`、`RetentionNotice`，以及中性的提示辅助函数 `describeOmitted`／`formatRetentionNotice`，且不依赖 Cordis 或任何工具包。单元测试覆盖具有精确省略计数的条目头部保留、文本头部保留、文本尾部保留、首尾字节保留、零预算、UTF-8 边界处理（2、3、4 字节码位，以及每个裁切位置上的无效起始字节）和未知省略量的措辞。
 
-**已记录但尚未迁移的内容。** `glob`、`grep`、`bash`、`web_fetch` 与 `web_search` 的映射已记录在[包 README](../../../../packages/util/retention/README.md) 中，但本次改动并未把每个工具都迁移到该库；迁移工作刻意留作独立的后续任务。`read` 被明确记录为不在范围内：其 `read-render` 行窗口契约（`offset`／`limit`、`totalLines`、offset 范围错误、逐行预览截断，以及针对所选窗口的字节上限）不属于通用保留，而一个 `Omitted` 计数也无法同时表达行窗口两侧。
+**已记录但尚未迁移的内容。** `glob`、`grep`、`bash`、`web_fetch` 与 `web_search` 的映射已记录在[包 README](../../../../packages/util/retention/README.md) 中，但本次改动并未把每个工具都迁移到该库；迁移工作刻意留作独立的后续任务。`read` 被明确记录为不在范围内：其 `read-render` 行窗口约定（`offset`／`limit`、`totalLines`、offset 范围错误、逐行预览截断，以及针对所选窗口的字节上限）不属于通用保留，而一个 `Omitted` 计数也无法同时表达行窗口两侧。
 
 **该库维持的边界。** `truncated` 表示 retainer 因预算省略了原本可用的内容，绝不表示上游不完整。工具专用状态，包括 `incomplete`、权限失败、提供方局部失败、跳过二进制文件、bash 落盘路径恢复和无效 UTF-8，均留在工具领域字段中、位于 retainer 之外。未来改动迁移某项工具时，该包的 README 与测试必须证明，除了有意改变的提示措辞外，模型可见的结果文本没有变化。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index e400692950..6e7aa8291a 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
 2026-07-07-tool-call-timeout-policy.md: b85a4d2d60ef60d9f75bd47d4d405aa55c132af6
-2026-07-07-tool-call-timeout-policy.zh.md: e67b9e4223f486208061f3944369cf3ec06fe72d
+2026-07-07-tool-call-timeout-policy.zh.md: f6a85c13a66689c48b10f160890ce3825125aec1
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index e67b9e4223..f6a85c13a6 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -52,7 +52,7 @@ catch 是基础 `next`（而非 waterfall 之外的东西）这一点至关重
     searchTimeoutMs: 30000
 ```
 
-超时放在工具定义上而非自由文本名称映射中，消除了拼错名称导致策略不生效的问题。`defineTool` 校验预算为正有限数。分发期间，执行器派生截止信号并将其赋给 `exec.signal`；注册表依据[工具取消契约](2026-07-19-cooperative-tool-cancellation.md)，在执行工具体之前将该截止信号与调用方的原始信号融合。执行器随后恢复调用方信号，并将自身的超时转换为 `TOOL_TIMEOUT`；没有预算的工具原样通过。
+超时放在工具定义上而非自由文本名称映射中，消除了拼错名称导致策略不生效的问题。`defineTool` 校验预算为正有限数。分发期间，执行器派生截止信号并将其赋给 `exec.signal`；注册表依据[工具取消约定](2026-07-19-cooperative-tool-cancellation.md)，在执行工具体之前将该截止信号与调用方的原始信号融合。执行器随后恢复调用方信号，并将自身的超时转换为 `TOOL_TIMEOUT`；没有预算的工具原样通过。
 
 信号替换采用**就地修改 `exec.signal`** 的方式，而非向 `next()` 传递新对象。Cordis 的 waterfall `next()` 忽略传入的任何参数，并以共享的 payload 数组重新调用下游监听器（`vendor/cordis/src/events.ts`），因此修改共享对象是包装器向注册表提供截止信号的方式。注册表会在进入工具体前再次融合已捕获的调用方信号；插件则在 `finally` 中将 `exec.signal` 恢复为调用方的原始值，使 `tools/post-execute` 永远不会看到本插件的截止信号。
 
@@ -71,7 +71,7 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 }
 ```
 
-这是一个协作式截止。它不会通过竞争工具 promise 来杀死任意工作；工具或其调用的能力必须遵循 `exec.signal` 并达到完全停稳。因此声明 `timeoutMs` 意味着「此工具与 `exec.signal` 协作」，插件 README 将此作为其契约。
+这是一个协作式截止。它不会通过竞争工具 promise 来杀死任意工作；工具或其调用的能力必须遵循 `exec.signal` 并达到完全停稳。因此声明 `timeoutMs` 意味着「此工具与 `exec.signal` 协作」，插件 README 将此作为其约定。
 
 无需新的会话事件来保证可重建性：`TOOL_TIMEOUT` 是该调用的最终面向模型的 `tool/result`，因此现有会话日志已经记录了下一次模型请求所见的内容和结构化 `{ name, code }` 错误。
 
@@ -107,8 +107,8 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 ## 后果
 
-- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发接口。其契约是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
+- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发接口。其约定是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
 - 多个 `tools/execute` 监听器按普通 Cordis waterfall 顺序组合：调用 `next()` 的监听器包装下游监听器加分发；不调用 `next()` 直接返回的监听器短路它们。一个同时组合超时与未来重试/沙箱/指标包装器的部署通过注册顺序选择语义（「超时覆盖整个重试」vs「超时覆盖每次尝试」）。
-- 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件契约声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
+- 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件约定声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
 - 过渡期间 `bash` 和已迁移的 web 工具有意使用不同的超时路径：`TOOL_TIMEOUT` 是面向模型的工具调用预算，而 `BASH_TIMEOUT` 仍是 bash 和钩子使用的 bash 后端超时。
 - 与字面提案的偏差，按 implemented-Agent Note 规则记录：插件包为 `@deepseek-ai/dsh-timeout-policy`（而非 `tool-timeout`）；信号替换是在 `next()` 之前就地修改 `exec.signal`（而非 `next({ ...exec, signal })`，Cordis 会忽略后者）；逐工具预算声明在 `ToolDefinition` 上（`timeoutMs`，由拥有该工具的插件从其配置中设置），而非在本插件配置中按工具名映射——因此执行器是零配置的，拼错工具名不可能发生。以上三点均在上文 `## Decision` 中描述。
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
index 215f612f5e..8f9fb5e270 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
 2026-07-08-agent-scope-contexts.md: eb3f6f247bac1a1d81aa2644132c7b9cc04d602c
-2026-07-08-agent-scope-contexts.zh.md: 673dd8578bf545b1f14f3b7e7b89874d804e4ae9
+2026-07-08-agent-scope-contexts.zh.md: a6dcd421cb2e8a64cdbe6393253355ad8554303e
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
index 673dd8578b..a6dcd421cb 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 Cordis 是 SDK 底层的插件框架。Cordis **上下文**是插件用来访问服务和注册效果的对象，效果的清理跟随该上下文。[Cordis 入门](../../../../docs/cordis-primer.md)对该框架有更详细的说明。
 
-对大多数贡献者而言，完整契约是四条规则：
+对大多数贡献者而言，完整约定是四条规则：
 
 | 问题 | 规则 |
 |---|---|
@@ -56,7 +56,7 @@ flowchart LR
 | 普通插件上下文 | 每个符合条件的 agent 视图 | 注册插件 |
 | `agent.ctx` | 仅该 agent 的视图 | agent 作用域 |
 
-工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此契约。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
+工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此约定。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
 
 普通贡献者的模式是在 agent setup 期间注册完整的本地世界：
 
@@ -88,7 +88,7 @@ await handle.dispose()
 ctx.tools.get('review_summary', handle.agent)  // undefined: scope is gone
 ```
 
-setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其契约仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
+setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其约定仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
 
 ### 操作选择视图
 
@@ -96,7 +96,7 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 工具查找与执行接收其所服务的 agent。提示词组装接收正在构建请求的 agent 的组装上下文。事件分发接收其领域主体。这使共享服务实例可在多个 agent 间复用，同时让每个操作的视图保持显式。
 
-只有采纳了作用域契约的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
+只有采纳了作用域约定的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
 
 ### 作用域事件将路由与事件数据分离
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
index 2145468f1f..dbac0c0688 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
 2026-07-08-tool-output-spill-files.md: 7c0ca90452645d251559be25108d12883210d00e
-2026-07-08-tool-output-spill-files.zh.md: a1bde1131374cd11215006b822dfc19aea707747
+2026-07-08-tool-output-spill-files.zh.md: 628023a9d12fec17d32749f9d17a3b701ca3a475
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
index a1bde11313..628023a9d1 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 这项改动之前的行为并不一致。`dsh-bash-local` 已经会在内存尾部溢出时，把完整 stdout／stderr 流写入私有的临时落盘文件；普通文本工具结果则仍以内联形式返回，除非工具自行实现上限。[工具结果保留库](2026-07-06-tool-result-retention-library.md)负责预览机制，但不负责存储，也不负责把这些机制应用于最终工具结果的执行流水线策略。
 
-其形态与超时策略设计一致：工具作者声明规范值与 Native renderer（原生渲染器），由策略插件在渲染后的内容上执行部署默认的上下文预算。工具仍可在提供方采集上限处提前落盘；由工具负责的展示落盘可以保留已完整采集的规范值，而只替换展示内容。[规范工具输出契约](2026-07-20-canonical-tool-output-contract.md)规定了这项区分。
+其形态与超时策略设计一致：工具作者声明规范值与 Native renderer（原生渲染器），由策略插件在渲染后的内容上执行部署默认的上下文预算。工具仍可在提供方采集上限处提前落盘；由工具负责的展示落盘可以保留已完整采集的规范值，而只替换展示内容。[规范工具输出约定](2026-07-20-canonical-tool-output-contract.md)规定了这项区分。
 
 ## 决策
 
@@ -164,7 +164,7 @@ ctx.tools.register(defineTool({
 
 ## 测试
 
-- `dsh-spill` 单元测试锁定 seam 契约：注册为 `ctx.spillStore`、每个上下文只允许一种实现，并在 dispose（资源释放）时释放。
+- `dsh-spill` 单元测试锁定 seam 约定：注册为 `ctx.spillStore`、每个上下文只允许一种实现，并在 dispose（资源释放）时释放。
 - `dsh-spill-local` 单元测试覆盖 `saveText`、`encodeSegment` 清理（分隔符／波浪号／完整路径段的点／空值）、会话哈希目录、仅所有者权限、每次保存生成不同路径、配置根目录／私有根目录，以及存储失败时的拒绝。
 - `dsh-spill-policy` 单元测试通过 `ctx.tools.execute` 驱动真实工具：禁用模式下无操作、替换超大文本、小结果／非文本结果保持不变、跳过 `read`、尽力回退（保存失败／无后端／无所有者），以及下游组合（限制已替换结果、保留 `additionalContexts`）。
 - `dsh-tool-web` 集成测试驱动 `web_fetch`，其实际执行路径经过 `ctx.tools.execute`，并使用真实的 `spill-local` 后端与策略；测试证明只有刻意加入的落盘提示会改变模型可见文本，而落盘文件保存完整的格式化结果。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index dbdc4347f6..380171ab17 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
 2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: 8b1332c23ce3b6c0332fcde40b4f4ac8dd20aa45
+2026-07-12-agent-scope-runtime-design.zh.md: e0c01f31eb2664608139f95dc60025a5b33e4618
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index 8b1332c23c..e0c01f31eb 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[agent 作用域契约](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份契约。
+[agent 作用域约定](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份约定。
 
 主要的设计风险是为每个竞态条件引入第二套机制。独立的预留、就绪哨兵、取消中继、快照层和保护注册表可能镜像同一个事实，直到没有读者能分辨哪个才是权威的。这些机制还会诱使运行时把可信的类型化调用当作敌对的序列化边界来处理。
 
@@ -24,13 +24,13 @@ Status: implemented
 | 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表条目 |
 | 协调创建/恢复 | 单个 `AgentCreationTransaction` |
 | 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 |
-| 在同一进程内传递类型化值 | Readonly 借用契约 |
+| 在同一进程内传递类型化值 | Readonly 借用约定 |
 | 组合模型可见的提示词与工具表面 | 单个共享工具视图加权威的 assembly-waterfall 结果 |
 | 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/完全停稳态事实 |
 
 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与提示词、subagent 与工作流，最后是可执行检查。
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者契约。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
@@ -104,7 +104,7 @@ detach 闭包捕获其确切注册表条目。它仅在映射仍指向该注册
 
 ### Setup 是私有世界内的可信组合
 
-Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开契约不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
+Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开约定不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
 
 事务将异步加载和 setup 与停用进行竞争，而非无限等待外部代码拥有的 promise。如果取消或所有者卸载获胜，即使外部 promise 永不结算，公开创建也会在事务拥有的清理之后拒绝。
 
@@ -185,7 +185,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 ## 信任边界：仅在所有权真正变更时复制
 
-运行时区分类型化的进程内契约与序列化及持久化边界。这是值和回调的主要简化规则。
+运行时区分类型化的进程内约定与序列化及持久化边界。这是值和回调的主要简化规则。
 
 | 边界 | 所有权规则 |
 |---|---|
@@ -196,9 +196,9 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 | 持久化会话或持久化数据 | 在提交前物化并验证 |
 | Worker、进程或协议格式消息 | 序列化、验证并拥有解码后的值 |
 
-测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产契约。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
+测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产约定。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
 
-回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件契约隔离失败。
+回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件约定隔离失败。
 
 ## 工具与提示词：单一视图、权威组装、已提交的结果
 
@@ -216,7 +216,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 注册表为每次执行分配一个新的带品牌的 `Symbol` token。嵌套的 Code Mode 调用将外层 token 作为 `parent` 携带，因此结构化输出可以通过标识将内层捕获与其外层 `run_code` 结果关联。
 
-注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化契约，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
+注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化约定，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
 
 参数在模型/工具 JSON 进入流水线时一次性物化。Pre-、around- 和 post-execute 监听器操作类型化的 execution 和决策。Call ID 关联、审批、单调守卫和 Code Mode 嵌套仍然是显式的关系检查。
 
@@ -256,7 +256,7 @@ Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子
 
 ### Skill 和 approval 服务信任类型化调用方
 
-Skill 注册表定义和 approval 策略是 readonly 的同进程契约。它们的服务不克隆回调对象，也不防御交接后的回调替换。
+Skill 注册表定义和 approval 策略是 readonly 的同进程约定。它们的服务不克隆回调对象，也不防御交接后的回调替换。
 
 Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
 
@@ -264,9 +264,9 @@ Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用
 
 Subagent 启动有一次所有权转移。提供方拥有未发布资源，直到其 start promise 以一个已发布 run 兑现；调用方拥有返回的 run 并必须 dispose 它。
 
-### 服务契约有一个取消通道
+### 服务约定有一个取消通道
 
-`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的契约。
+`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的约定。
 
 `SubagentStartRequest.signal` 是必需的。中止它会在启动期间，以及已发布 run 的剩余就绪或轮次工作中请求取消。`SubagentRun.dispose()` 也请求取消并等待完全停稳。没有单独的公开 `run.cancel()` 通道。
 
@@ -314,11 +314,11 @@ Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲
 
 ## 正确性强制
 
-该设计通过类型、运行时逃逸点、生成的契约和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
+该设计通过类型、运行时逃逸点、生成的约定和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
 
 ### 类型使常规路径难以误用
 
-Readonly 契约描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
+Readonly 约定描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
 
 TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进程消息或持久化文件，因此运行时强制保留在这些逃逸点。
 
@@ -326,9 +326,9 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 `dsh-scope/invariant` 配套插件在被选用时验证每个声明的作用域事件使用带标记的载体，以及暴露主体的事件族使用匹配的键。独立的 `dsh-session/invariant` 贡献在追加提交前暂存 trace 验证，并在同一事件提交后推进；二者都通过 `ctx.invariants` 注册。
 
-该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合契约变成推测性的运行时机制，却不保护真实的外部边界。
+该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合约定变成推测性的运行时机制，却不保护真实的外部边界。
 
-### 生成的产物使公开契约保持对齐
+### 生成的产物使公开约定保持对齐
 
 事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。
 
@@ -336,7 +336,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ## 曾考虑的替代方案
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域契约的替代方案。此处的替代方案关注实现形态。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
 
 ### 使用透明代理作为作用域载体
 
@@ -348,7 +348,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 对每个类型化的同进程参数做快照
 
-通用复制防御有状态 getter 和违反 readonly 契约的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
+通用复制防御有状态 getter 和违反 readonly 约定的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
 
 ### 为就绪、取消和 dispose 提供独立控制器
 
@@ -375,10 +375,10 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 - 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。
 - 创建和恢复不暴露部分配置的句柄；最终写入注册表时的失败者和发布失败清理每个已准备的资源。
 - Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。
-- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。
+- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 约定。
 - ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。
 - 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。
-- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳契约。
+- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳约定。
 - Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。
 
 ### 代价与局限
@@ -387,6 +387,6 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 
 可信的 `system-prompt/assemble` 监听器可以移除或替换 Code Mode 和结构化输出协议片段。这是有意为之：监听器拥有最终组合，必须保持部署期望仍可用的任何协议。
 
-该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 契约的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
+该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 约定的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
 
 [安全与权限非目标](2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)仍然是根本性的。这些机制证明注册组合、发布和生命期所有权；它们不证明隔离或父到子的非升权。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index 460495cbeb..d4886965ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
 2026-07-12-scoped-layers-store.md: c5186d1652bca617eed62ec02937f2d055ea727c
-2026-07-12-scoped-layers-store.zh.md: fbe95ab6c7b3391a70e34b83889bf9f8adeb6ba1
+2026-07-12-scoped-layers-store.zh.md: f5084426beef836d71e55c0898ec1edbdc7725f3
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
index fbe95ab6c7..f5084426be 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -16,7 +16,7 @@ agent（智能体）作用域机制（[决策](2026-07-08-agent-scope-contexts.m
 - change 回调运行前必须收集 undo，抛错的回调才能回滚变更。
 - 公开 disposer 必须就是 `ctx.effect()` 返回的那个函数；包装它会破坏 Cordis 基于身份的有序拆除。
 
-共享的是生命周期与保持插入顺序的存储，而不是注册表策略。工具限制、保留传输处理、提示词求值时机、命令规范化、精确诊断和回调异常隔离，仍分别属于不同的领域契约。
+共享的是生命周期与保持插入顺序的存储，而不是注册表策略。工具限制、保留传输处理、提示词求值时机、命令规范化、精确诊断和回调异常隔离，仍分别属于不同的领域约定。
 
 ## 决策
 
@@ -70,7 +70,7 @@ export class AnonymousEntries<V> {
 }
 ```
 
-## 存储契约
+## 存储约定
 
 - 构造器只创建一次 `global`，调用的是 `createLayer(undefined)`。只有 `effect()` 会创建专属层；`peek()` 和 `merge()` 从不创建专属层，而 `peek(undefined)` 返回 `undefined`，因为全局层已经显式存在。
 - `merge()` 是唯一会物化结果的通用读取接口。它按插入顺序复制全局命名条目，再按专属条目的插入顺序应用这些条目；同名条目完成遮蔽，但不会移动无关名称。
@@ -111,11 +111,11 @@ export class AnonymousEntries<V> {
 ## 后果
 
 - 支持作用域的注册表各自通过一个聚合层表达状态，并复用相同的构造、属主、回滚、通知和回收编排。各注册表仍各自保有领域特有的校验、诊断、过滤、求值和观察者策略。
-- 公开读取接口保持狭窄：直接遍历条目表可保留显式的活语义，`merge()` 是唯一共享的物化遮蔽操作。异构的 `ScopeLayer` 不具备整层 `values()` 契约。
-- helper 刻意保持同步。未来的登记若需要异步 setup 或多份分别拥有属主的 undo，必须先明确属主与 settlement 边界，再拓宽这项契约。
-- action 必须在保留贡献前抛错，或者为自己保留的一切返回 undo；helper 无法修复超出这项契约的变更。提供的条目操作是原子的，迁移后的注册表会在插入前执行可能失败的校验。
+- 公开读取接口保持狭窄：直接遍历条目表可保留显式的活语义，`merge()` 是唯一共享的物化遮蔽操作。异构的 `ScopeLayer` 不具备整层 `values()` 约定。
+- helper 刻意保持同步。未来的登记若需要异步 setup 或多份分别拥有属主的 undo，必须先明确属主与 settlement 边界，再拓宽这项约定。
+- action 必须在保留贡献前抛错，或者为自己保留的一切返回 undo；helper 无法修复超出这项约定的变更。提供的条目操作是原子的，迁移后的注册表会在插入前执行可能失败的校验。
 - 专属层会一直保持已分配状态，直到其聚合内的所有表都为空。因此，销毁一个门面不会丢弃同一 scope 拥有的其他贡献。
-- 四个公开符号构成一项可复用的包契约。将 `EntryValues` 保持为内部接口，并把消费方策略留在 helper 之外，可以限制兼容性范围。
+- 四个公开符号构成一项可复用的包约定。将 `EntryValues` 保持为内部接口，并把消费方策略留在 helper 之外，可以限制兼容性范围。
 - 迁移不改变任何公开注册表行为，也不改变模型、人类、协议、持久化、配置或依赖图层面的任何输出。
 
 ## 验证
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
index c85bb100aa..7f295cd363 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
 2026-07-15-agent-initiator-scope.md: 2f388ae1de3dd6583686e129a03f0cd76701e18d
-2026-07-15-agent-initiator-scope.zh.md: 64f70a4d1c3368d5621edb7251d0b567505affc0
+2026-07-15-agent-initiator-scope.zh.md: a0e3638081d875adc2412191829ab84c8dcd697c
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
index 64f70a4d1c..a0e3638081 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
@@ -20,21 +20,21 @@ harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负
 
 因此，并发驱动使用彼此独立的存储。子驱动的异步延续携带子 Agent；`withInitiator()` 返回后，调用方立即恢复之前的存储，而活动运行计数仍持续跟踪返回的 Promise，直到其结束。创建、持久化加载和尚未发布的 `setup(agentCtx)` 位于子驱动边界之外：由父 Agent 发起的创建使用父身份，而 `agentCtx.agent` 显式标识子 Agent。
 
-隐式身份不会取代显式契约。`ToolExecution.agent`、`AssembleContext.agent`、`GenerateOptions.sessionId`、任务归属、父子请求、`ctx.agent`、`agentCtx.agent`、审批与 hook 主体、`cwd` 选择、取消、worker 和进程消息、持久化记录及协议身份都保持显式传递。远程边界会把所需身份写入类型化请求，因为 ALS 只在进程内有效。
+隐式身份不会取代显式约定。`ToolExecution.agent`、`AssembleContext.agent`、`GenerateOptions.sessionId`、任务归属、父子请求、`ctx.agent`、`agentCtx.agent`、审批与 hook 主体、`cwd` 选择、取消、worker 和进程消息、持久化记录及协议身份都保持显式传递。远程边界会把所需身份写入类型化请求，因为 ALS 只在进程内有效。
 
 `AgentRegistry` 管理一个有序的发起方生命周期。teardown 会先拒绝新边界；移除 `ctx.agents` 后，AgentLoop 等注入方开始排空，注册表随后等待活动的返回 Promise 边界，最后调用 `AsyncLocalStorage.disable()`。如果某个边界继承的异步调用链启动所属 Cordis fiber 的卸载，私有运行标记谱系会从排空范围中释放该嵌套边界链，从而避免 teardown 等待自身完成，同时继续排空无关边界。在普通排空期间，进行中代码可通过保留的服务引用继续调用 `currentInitiator()` 和 `requireInitiator()`；dispose（资源释放）后，发起方方法会抛出 `agent initiator scope is disposed`。根 Context dispose 可能并发启动同级 fiber 的 teardown，因此除 Cordis 依赖顺序外仍必须统计活动边界。
 
-发起方作用域不负责管理脱离返回链的工作：注册表排空只跟踪 `withInitiator()` 或 `withoutInitiator()` 返回的 Promise。边界内创建的异步资源会继承其存储，直到自身结束或 ALS 被禁用；所属 seam 必须显式停止未纳入返回 Promise 的工作。Agent 所属的前台工作会把完整生命周期纳入返回值，并保留显式取消契约。无关的定时器、队列和部署基础设施在 `withoutInitiator(operation)` 下启动；队列、worker、进程和协议边界必须序列化身份，不能期待 ALS 传播。
+发起方作用域不负责管理脱离返回链的工作：注册表排空只跟踪 `withInitiator()` 或 `withoutInitiator()` 返回的 Promise。边界内创建的异步资源会继承其存储，直到自身结束或 ALS 被禁用；所属 seam 必须显式停止未纳入返回 Promise 的工作。Agent 所属的前台工作会把完整生命周期纳入返回值，并保留显式取消约定。无关的定时器、队列和部署基础设施在 `withoutInitiator(operation)` 下启动；队列、worker、进程和协议边界必须序列化身份，不能期待 ALS 传播。
 
 宿主感知的传输层可以从 `ctx.agents.requireInitiator().session.id` 推导由部署方拥有的 `X-Harness-Session-Id` 等请求头；模型可见 schema 和参数中不包含该请求头。本决策不让现有生产 MCP 或 Web 传输层采用此请求头。测试替身传输层用于证明可信边界，而不会把宿主路由策略分配给现有的提供方无关 seam。
 
-本决策扩展 [Agent 注册作用域契约](2026-07-08-agent-scope-contexts.md)及其[运行时设计](2026-07-12-agent-scope-runtime-design.md)，不会改变其中 `agent.ctx` 的静态含义。
+本决策扩展 [Agent 注册作用域约定](2026-07-08-agent-scope-contexts.md)及其[运行时设计](2026-07-12-agent-scope-runtime-design.md)，不会改变其中 `agent.ctx` 的静态含义。
 
 ## 验证
 
 Agent 服务测试锁定可选与必需读取、同步值及跨 realm Promise 的精确身份、内建 Promise 结束状态观察、并发、嵌套及清空边界、同步抛错或 Promise 拒绝后的恢复、普通与重入排空顺序及保留引用的错误。AgentLoop 集成测试锁定并发与嵌套驱动、无 Agent 调用、AgentRegistry 重启、根 Context 销毁，以及包内私有的循环和工具调度通过隐式查找完成。组合、模块图、构建及运行时闭包检查确保默认组合包、SDK 主干、Python 运行时闭包及直接 AgentLoop harness 通过 `ctx.agents` 完成接线，无需其他提供方。
 
-测试替身形式的宿主感知传输层在内部推导 `X-Harness-Session-Id`，并验证工具 schema 与日志中记录的参数都不包含身份字段。服务有意不排空边界操作所返回 Promise 之外的异步工作；这类工作仍由所属方的显式停止契约管理。
+测试替身形式的宿主感知传输层在内部推导 `X-Harness-Session-Id`，并验证工具 schema 与日志中记录的参数都不包含身份字段。服务有意不排空边界操作所返回 Promise 之外的异步工作；这类工作仍由所属方的显式停止约定管理。
 
 ## 考虑过的替代方案
 
@@ -46,7 +46,7 @@ Agent 服务测试锁定可选与必需读取、同步值及跨 realm Promise 
 
 **保存命名帧或完整运行时帧。** 只有一个字段的 `{ agent }` 帧只是包装该值，而 Agent、会话、inbox、取消、轮次、步骤、工具执行和持久化已经有各自的真源。增加更多字段会产生陈旧快照和另一套生命周期；直接携带 `Agent`，由方法名标识边界，无需重复保存状态。
 
-**包含步骤级 `AbortSignal`、`cwd`、沙箱或授权。** 它们的生命周期及权限范围与驱动边界不一致，而且现有 seam 已经显式传递这些值。新增控制能力需要独立决策和嵌套生命周期契约。
+**包含步骤级 `AbortSignal`、`cwd`、沙箱或授权。** 它们的生命周期及权限范围与驱动边界不一致，而且现有 seam 已经显式传递这些值。新增控制能力需要独立决策和嵌套生命周期约定。
 
 **使用进程级 `currentAgent`。** 并发 Agent 和 subagent 会在异步延续执行之间相互覆盖，因此可变全局值只在 harness 不具备的串行保证下才正确。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index aac1c86e11..ebf474f78b 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
 2026-07-15-lsp-capability-seam.md: 63cec0a4e349ffc5be27a84e955b15e9168f898b
-2026-07-15-lsp-capability-seam.zh.md: cdb1289f6956d8a4e46ed92847ddd8a58e588afa
+2026-07-15-lsp-capability-seam.zh.md: fa82e29e0252b612ae38357c363478f1cbad9ead
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index cdb1289f69..fa82e29e02 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 harness 已具备文本搜索与文件读取能力，但二者都无法识别程序符号。文本匹配无法可靠地区分同名函数、跟踪导入别名、关联接口与具体实现，也无法报告推断类型。因此，agent（智能体）在修改代码前缺少人类通过编辑器语言服务器获得的语义导航能力。
 
-语言服务器协议（Language Server Protocol，LSP）支持分属三个职责方：模型需要稳定的查询 schema，harness 需要提供方选择与规范化结果，本地实现则负责进程、JSON-RPC、工作区、同步与文件系统行为。将三者合并会使模型契约绑定本地子进程，并阻碍远程或沙箱原生提供方。
+语言服务器协议（Language Server Protocol，LSP）支持分属三个职责方：模型需要稳定的查询 schema，harness 需要提供方选择与规范化结果，本地实现则负责进程、JSON-RPC、工作区、同步与文件系统行为。将三者合并会使模型约定绑定本地子进程，并阻碍远程或沙箱原生提供方。
 
 许多语言服务器在查询文档已按当前文本打开时表现最佳。兼容的 agent 客户端必须限制这项状态、定义内部读取是否算作模型观察，并确保文档快照与服务器工作区索引位于同一文件系统命名空间。
 
@@ -32,7 +32,7 @@ harness 已具备文本搜索与文件读取能力，但二者都无法识别程
 
 服务边界只公开 `query(request, signal?)`，因为没有字段需要实现层填充默认值：`workspaceRoot` 是必填项，`languageId` 来自注册映射，超时与结果限制由消费方负责。`query()` 执行选择与推导时不使用隐藏的 `??` 后备逻辑，因此没有需要 resolve 的可执行 spec。`dsh-tool-lsp` 校验模型参数，并只把 `exec.signal` 作为裸 `AbortSignal` 传递，与 web 一致，并使 `dsh-lsp` 不依赖 `dsh-tools`。提供方在选择前被移除时按不可用失败；之后的释放遵循已选提供方的取消生命周期，不改路由。
 
-预期契约如下：
+预期约定如下：
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -81,7 +81,7 @@ interface LspService {
 
 `dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
-## 面向模型的契约
+## 面向模型的约定
 
 单一 `lsp` 工具接受以下参数：
 
@@ -149,7 +149,7 @@ interface LspToolInput {
 
 **照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景，但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口，因此本提案只对齐四种语义查询。
 
-**允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词，无法在本地与远程提供方之间维持统一契约。
+**允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词，无法在本地与远程提供方之间维持统一约定。
 
 **公开任意 LSP 方法。** JSON-RPC 逃生口会泄露协议载荷，并允许未经评审的变更或命令执行；操作联合保持封闭。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index d7f1670f34..f683189f93 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
 2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
-2026-07-16-explicit-turn-cancellation.zh.md: 729997d48df79bad9fa52cd76ec7fa1fab281ae3
+2026-07-16-explicit-turn-cancellation.zh.md: 0b9a06c0ae340a41eab9d6bff6126996bfc63bcf
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index 729997d48d..0b9a06c0ae 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程 seam 中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性契约。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
+Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程 seam 中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
 
 正在运行的轮次被中断后，以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么，运行时 signal 标识谁请求了取消；回放不会重复保存 `user` 或 `parent`。会话 seed/load 会拒绝携带取消原因或任何其他额外字段的旧式中止记录，因此回放无法重新引入由调用方持有的取消细节。仅限进程内的 `agent/cancel-requested` 通知不会持久化；未来若有审计需求，应使用独立的持久化控制请求事件，让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index 82d87580f8..a0956af598 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
 2026-07-19-cooperative-tool-cancellation.md: 4e82452cd6883593d4693766bea803c97fa4c977
-2026-07-19-cooperative-tool-cancellation.zh.md: 1d9fd3dcc8fa65e6f06050be749eec6ac9e996c2
+2026-07-19-cooperative-tool-cancellation.zh.md: aa94fd9f3d32167dc7d6b906ff14a6afd36ccb32
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index 1d9fd3dcc8..aa94fd9f3d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 `ToolDefinition.execute(args, exec)` 保持现有签名。`defineTool()` 会把 `exec.signal` 上下文推断为必填的 `AbortSignal`，因此每个已注册的 TypeScript 工具都能在无需类型断言的情况下观察或转发取消。所有第一方直接调用方和 Code Mode 嵌套调度都会显式传入当前操作的信号。
 
-注册表信任这份类型化同进程契约。它不在运行时校验 `AbortSignal`，也不为缺失或畸形信号添加敌意输入测试。校验仍位于解析器与配置、模型与工具 JSON、持久化与文件、worker、进程和协议边界；违反 TypeScript 接口的无类型 JavaScript 不享有兼容性契约。
+注册表信任这份类型化同进程约定。它不在运行时校验 `AbortSignal`，也不为缺失或畸形信号添加敌意输入测试。校验仍位于解析器与配置、模型与工具 JSON、持久化与文件、worker、进程和协议边界；违反 TypeScript 接口的无类型 JavaScript 不享有兼容性约定。
 
 ### 可变性由流水线阶段决定
 
@@ -54,9 +54,9 @@ Status: implemented
 
 **保留可选信号并生成后备值。** 不予采纳，因为注册表持有的后备信号不代表任何调用方生命周期，也会保留类型系统本应阻止的缺失情况。
 
-**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程 seam，不是序列化边界。运行时检查只会重复静态契约，仍无法强制实现协作式使用信号。
+**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程 seam，不是序列化边界。运行时检查只会重复静态约定，仍无法强制实现协作式使用信号。
 
-**添加 `supportsCancellation` 元数据、回调参数数量检查或信号使用 lint。** 不予采纳，因为这些方法都无法证明异步工作会观察或正确转发取消。信号可用性属于类型契约；具体行为仍由工具和能力负责。
+**添加 `supportsCancellation` 元数据、回调参数数量检查或信号使用 lint。** 不予采纳，因为这些方法都无法证明异步工作会观察或正确转发取消。信号可用性属于类型约定；具体行为仍由工具和能力负责。
 
 **向所有阶段公开同一个可变执行类型。** 不予采纳，因为观察者和工具实现只需要借用信号。按阶段划分类型可以把替换权限限制在流水线拥有该操作的位置。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 65cbe478ae..4578e9e268 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 55fa8084083aa83fbb4a38f8e41d2e5624b6e58e
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 49ebd642264c663377f16b8669fedc112d3bb6c7
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 55fa808408..49ebd64226 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
 
-同时各消费端的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE、将来 IPC），还需要一个通道无关的消息模型和单一契约事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
+同时各消费端的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE、将来 IPC），还需要一个通道无关的消息模型和单一约定事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
 
 ## Decision
 
@@ -151,7 +151,7 @@ export type ResponseValue<K> =
 - **锚定**：schema 统一 `satisfies z.ZodType<Wire<T>>`（`api/rpc.schema.ts`）。`Wire<T>` 是深度「| undefined」宽化——仓库开 `exactOptionalPropertyTypes` 而 zod `.optional()` 输出 `T | undefined`，直接锚原类型全线不可用；JSON wire 上缺席与 undefined 同形，宽化不损失校验语义。透传宽分支（`SessionEvent`/`ContentBlock`/帧 union/`RpcError`）与 brand id schema 用显式 cast + 注释。
 - brand cast 单点：每个 schema 文件的 id cast 收口一处（`rpcIdSchema` 是 rpc.schema.ts 唯一 cast 点）。
 
-## 契约面（ApiProxy）
+## 约定面（ApiProxy）
 
 根接口 `ApiProxy = { sessions, host, events, respond }`（`api/index.ts`）。新 client-request 域 = 新的一对文件（`<域>.ts` + `<域>.schema.ts`）+ 根接口一个字段 + map 加行。
 
@@ -183,7 +183,7 @@ export type ResponseValue<K> =
 - **prompt 关联**：prompt 的 rpcId 经 MessageSource（`'user-rpc'`）透传进 `user/message` 事件，client 以此把乐观回显转正。
 - **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，有缝再补拉一次。
 - **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 Agent 的情况下检查持久化存储，而绑定到 Agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
-- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：契约与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
+- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：约定与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
 - **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
 - **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
 
@@ -193,7 +193,7 @@ export type ResponseValue<K> =
 
 ### IApiClient：caller 视图
 
-与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名契约，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
+与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名约定，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
 
 ### 基类持有的协议路径
 
@@ -216,7 +216,7 @@ export type ResponseValue<K> =
 | `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，契约/基类零改 |
+| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
@@ -226,13 +226,13 @@ export type ResponseValue<K> =
 
 **加一个错误码（2 步）**：①`RpcErrorDetailsMap` 加一行（details 必填）；②`rpcErrorSchema` discriminatedUnion 加一支。
 
-**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。契约与基类零改。
+**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。约定与基类零改。
 
 **升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
 
 ## Consequences
 
-所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
 
 ## Alternatives considered
 
@@ -240,10 +240,10 @@ export type ResponseValue<K> =
 |---|---|
 | 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
 | 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开契约，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
-| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、契约双份人肉对齐、命名无 convention 自然漂移 |
+| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |
 | 三信封模型（Request/Response/Frame 各一信封，签名不感知方向） | rpcId 是逻辑层关联，帧与应答的方向语义靠通道推断在换载体时即失效 |
 | 具名 Request/Response 类型对为事实源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
 | REST 风格路径 | 消费者是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index d3bbc7da9d..5523e6d3b2 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
 2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
-2026-07-19-gui-web-client-architecture.zh.md: cf31220aad61e4845f7fe90b73bf5da4432e53de
+2026-07-19-gui-web-client-architecture.zh.md: 10779107a9dc6dc7335b2c5932c8c4877b531b50
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index cf31220aad..10779107a9 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-19-gui-web-client-architecture.md) | 中文
 
-> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/契约面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
 
 ## Problem
 
@@ -69,7 +69,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 ```
 
 - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
-- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
+- **ConversationSnapshot**（conversation.ts）：不可变快照约定——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
 - **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
@@ -79,8 +79,8 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 
 胶水包就是整条 ctx↔React 边界；组件保持零框架依赖。
 
-- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据契约合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
-- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 契约四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
+- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据约定合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
+- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 约定四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
 - `useInvoke(fn)`：把异步动作包成引用恒定的触发器加 pending 标志；pending 走 per-hook 外部 store 经 uSES 读出（渲染路径零 setState），并发调用计数，invoke 引用永不变。
 - 相等性协议，全链一致：生产端结构共享；消费端以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
 
@@ -108,7 +108,7 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
 - **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
index e292482740..6af30fd423 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
 2026-07-19-package-invariant-runtime-contracts.md: 86d86f69b606c348e85d1ae654b6b35c4326985a
-2026-07-19-package-invariant-runtime-contracts.zh.md: 386a294b577561d08493a3b2925910ee5ba971b4
+2026-07-19-package-invariant-runtime-contracts.zh.md: 94d332a34c1d6e681c10832ea4deb559d88b21a6
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
index 386a294b57..94d332a34c 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 有意义的包不变量契约
+# Agent Note: 有意义的包不变量约定
 
 Status: implemented
 
@@ -10,7 +10,7 @@ Status: implemented
 
 有用的运行时不变量会关联时间上的多个观测，或关联可变数据结构中的多个部分。例如：终止事件没有对应的开始事件、LLM（大语言模型）delta 指向未打开的块，或持久化结果的身份与请求不同。仅确认声明的方法存在、插件名称符合预期，或常量示例仍返回已知值，都不属于这种关系。
 
-有些包确实没有可持续观测的关系。纯工具、仅负责组合的包、薄适配器、可执行入口和测试支持包可能仍有重要契约，但类型检查、加载检查、聚焦单元测试或集成测试更适合执行这些契约。强迫这些包添加合成运行时断言，只会让实现围绕通过门禁优化，而不是检测损坏。
+有些包确实没有可持续观测的关系。纯工具、仅负责组合的包、薄适配器、可执行入口和测试支持包可能仍有重要约定，但类型检查、加载检查、聚焦单元测试或集成测试更适合执行这些约定。强迫这些包添加合成运行时断言，只会让实现围绕通过门禁优化，而不是检测损坏。
 
 ## 决策
 
@@ -64,7 +64,7 @@ Vitest 为每个包测试拓扑使用 `{ enabled: true }` 挂载 `InvariantServi
 ## 考虑过的替代方案
 
 - **保留生成的空 companion。** 拒绝，因为包获得有意义的运行时关系后，没有解释的占位符仍可能继续存在。
-- **要求每个包都执行断言。** 拒绝，因为方法存在性、插件形状和固定示例断言会重复更强的类型、加载和单元测试契约，却没有检查运行时一致性。
+- **要求每个包都执行断言。** 拒绝，因为方法存在性、插件形状和固定示例断言会重复更强的类型、加载和单元测试约定，却没有检查运行时一致性。
 - **在服务中保留通用形状 helper。** 拒绝，因为这会混淆编译期 API 验证和运行时不变量，并鼓励在中央定义产品假设。
 - **把产品检查移入服务。** 拒绝，因为产品词汇、依赖、测试和变更所有权应归属于产生这些数据的包。
 - **从根入口隐式注册 companion。** 拒绝，因为组合顺序和可选服务存在性会产生隐藏 effect。
@@ -75,4 +75,4 @@ Vitest 为每个包测试拓扑使用 `{ enabled: true }` 挂载 `InvariantServi
 - 空 companion 是带包专属说明、可评审的决策；删除说明后门禁会失败。
 - 类型声明、Cordis 可加载性、插件 metadata、服务方法形状和纯代数继续由所属的编译、加载、单元或集成门禁覆盖。
 - 运行时失败会标明所属 npm 包，并指出不一致的观测，而不是复述必要的 API 形状。
-- 原有 selection、blocklist 优先级、重复所有权、回滚、dispose 和 HMR（热模块替换）服务契约保持不变。
+- 原有 selection、blocklist 优先级、重复所有权、回滚、dispose 和 HMR（热模块替换）服务约定保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index 544e7415ce..291a3f3ce1 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
 2026-07-19-package-owned-invariant-service.md: e32efe9f6b3ce6b782c61db56d928e87c160dc9a
-2026-07-19-package-owned-invariant-service.zh.md: f134541c78f849fa085bebef527b57f911af0748
+2026-07-19-package-owned-invariant-service.zh.md: abb77cfc2dc4c15510baf0b205cefdbf3c890041
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index f134541c78..abb77cfc2d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 `@deepseek-ai/dsh-invariants` 是与产品无关的 Cordis 服务插件，注册 `ctx.invariants`。它只负责配置、注册唯一性、子 fiber 生命周期和带包归属的失败；不导入 session、agent、scope 或 agent-loop 包，也不包含这些包的检查。
 
-工作区内的每个包都发布 `./invariant` 伴随插件，注册自己完整且准确的 npm 包名。如果所有者具备有意义的事件或可变数据关系，companion 就检查该关系；否则空 installer 必须携带该所有者专属的说明。后续的[运行时契约 Agent Note](2026-07-19-package-invariant-runtime-contracts.md) 禁止生成的所有权占位符和合成 API 形状断言。包的根入口不会隐式导入或注册诊断，因此加载根包不会改变运行时检查，也不要求不变式服务存在。
+工作区内的每个包都发布 `./invariant` 伴随插件，注册自己完整且准确的 npm 包名。如果所有者具备有意义的事件或可变数据关系，companion 就检查该关系；否则空 installer 必须携带该所有者专属的说明。后续的[运行时约定 Agent Note](2026-07-19-package-invariant-runtime-contracts.md) 禁止生成的所有权占位符和合成 API 形状断言。包的根入口不会隐式导入或注册诊断，因此加载根包不会改变运行时检查，也不要求不变式服务存在。
 
 ### 配置与选择
 
@@ -64,13 +64,13 @@ blocklist 匹配优先于 allowlist 匹配。每个条目都是区分大小写
 | `@deepseek-ai/dsh-scope/invariant` | `@deepseek-ai/dsh-scope` | scoped event carrier 存在性与主体一致性 |
 | `@deepseek-ai/dsh-agent-loop/invariant` | `@deepseek-ai/dsh-agent-loop` | 模型请求重建 |
 
-这四个所有者提供了首批有状态检查。后续运行时契约决策为另外十七个确有事件或可变数据关系的所有者增加检查，并为其余包记录有理由的空 companion。每个伴随入口都是单独打包的 `./invariant` export，具有独立声明和对 Loader 安全的命名空间插件形态；服务包自身的伴随插件导入本地服务类型，避免形成自依赖。
+这四个所有者提供了首批有状态检查。后续运行时约定决策为另外十七个确有事件或可变数据关系的所有者增加检查，并为其余包记录有理由的空 companion。每个伴随入口都是单独打包的 `./invariant` export，具有独立声明和对 Loader 安全的命名空间插件形态；服务包自身的伴随插件导入本地服务类型，避免形成自依赖。
 
 `verify-package-invariants` 会发现每个工作区包，并拒绝缺失的伴随插件源码、生成标记、没有解释的空 installer、缺少或不使用失败报告器的非空 installer、外部或无法解析的注册名、缺失的 `./invariant` export 或发布文件、缺失的不变式对等依赖（peer dependency）、开发依赖及项目引用，以及遗漏伴随入口的自定义构建配置。
 
 ### Scoped event 语义映射
 
-生成的 scoped event 主体解析表位于 `dsh-scope`，与消费它的契约和不变式相邻。`gen-scoped-events` 使用根 TypeScript Program 枚举 `this: Scoped<Base>` 声明，从真实 `scopeTarget(base, key)` 调用推断路由键类型，并要求唯一、无歧义的 payload 主体或显式 unsupported 标记。提交的运行时映射不导入事件所有者包，因此语义完整性不会扩大服务包或 scope 包的运行时依赖闭包。
+生成的 scoped event 主体解析表位于 `dsh-scope`，与消费它的约定和不变式相邻。`gen-scoped-events` 使用根 TypeScript Program 枚举 `this: Scoped<Base>` 声明，从真实 `scopeTarget(base, key)` 调用推断路由键类型，并要求唯一、无歧义的 payload 主体或显式 unsupported 标记。提交的运行时映射不导入事件所有者包，因此语义完整性不会扩大服务包或 scope 包的运行时依赖闭包。
 
 ### 示例组合与 SDK 输出
 
@@ -88,9 +88,9 @@ Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、
 
 ## 考虑过的替代方案
 
-- **把所有检查保留在 `dsh-invariants`。** 不予采纳，因为注册包仍要导入所有被检查的产品领域，所有者变更仍需中央编辑，测试也继续远离被保护的契约。
+- **把所有检查保留在 `dsh-invariants`。** 不予采纳，因为注册包仍要导入所有被检查的产品领域，所有者变更仍需中央编辑，测试也继续远离被保护的约定。
 - **当 `ctx.invariants` 恰好存在时，让根包入口隐式注册检查。** 不予采纳，因为根入口行为会依赖组合顺序与可选服务是否存在，诊断无法独立选择，而且包加载会隐藏一个不在显式伴随插件中的注册 effect。
-- **在运行时自动发现所有 `invariant.ts` 文件。** 不予采纳，因为文件系统或包发现不是运行时所有权契约，会让 bundle 发布含义不清，也无法表达显式 Cordis 加载顺序或依赖安装。构建期生成与校验以及测试 host 可以枚举源码树，因为它们验证的是仓库完整性，而不是组合已发布的部署。
+- **在运行时自动发现所有 `invariant.ts` 文件。** 不予采纳，因为文件系统或包发现不是运行时所有权约定，会让 bundle 发布含义不清，也无法表达显式 Cordis 加载顺序或依赖安装。构建期生成与校验以及测试 host 可以枚举源码树，因为它们验证的是仓库完整性，而不是组合已发布的部署。
 - **根据当前已加载包集合验证 allow/block 条目。** 不予采纳，因为零匹配模式可能有意指向稍后加载或 HMR 加载的贡献；当前加载顺序不能决定配置有效性。
 
 ## 后果
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
index acb9d72ef1..be9d15968f 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
 2026-07-19-zstandard-jsonl-session-logs.md: 93fc20f931c75552352834b9340e7d38680d4254
-2026-07-19-zstandard-jsonl-session-logs.zh.md: 061d7fcb55c775eed10e99bae47777d32cc8eee1
+2026-07-19-zstandard-jsonl-session-logs.zh.md: e5495f2f5ae356d49bd2321e442c19ca834c2ab7
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
index 061d7fcb55..e5495f2f5a 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
@@ -38,7 +38,7 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
 
-共享持久化契约与协调器契约会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
+共享持久化约定与协调器约定会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index 680d2dd94a..75c2b53cef 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
 2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
-2026-07-20-canonical-tool-output-contract.zh.md: 26653ea769b8a642b70c4d3dd2f5ab907a70bd85
+2026-07-20-canonical-tool-output-contract.zh.md: 534aa2ed7ad65719b280f64f73a412bf5b17a1de
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
index 26653ea769..534aa2ed7a 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 规范工具输出契约
+# Agent Note: 规范工具输出约定
 
 Status: implemented
 
@@ -8,7 +8,7 @@ Status: implemented
 
 工具主体过去直接编写面向模型的 `ContentBlock[]`，并可选择将其与不透明的 `meta` 包装在一起。因此，Native 模式的 Function Calling（函数调用）虽然拥有可供人阅读的投影，但程序化调用方没有稳定的领域值：Code Mode 会将内容块重新展平为字符串，动态工具会重复定义内容形态，策略也可以替换展示内容，却无法区分这项变更究竟是替换展示，还是替换操作结果。多个能力 seam 已经返回了信息更丰富的提供方值，却又在面向模型的工具边界丢弃这些值。
 
-持久会话契约将这份展示内容视为回放时的权威来源，但如果持久化每一个信息丰富的中间值，就会扩大日志、使实现数据进入压缩（compaction）和迁移流程，还会错误地把执行期本地 API 变成会话格式的一部分。因此，系统底层需要在执行期间保留一个类型化值，并显式将其投影为现有的持久化内容和模型可见内容。
+持久会话约定将这份展示内容视为回放时的权威来源，但如果持久化每一个信息丰富的中间值，就会扩大日志、使实现数据进入压缩（compaction）和迁移流程，还会错误地把执行期本地 API 变成会话格式的一部分。因此，系统底层需要在执行期间保留一个类型化值，并显式将其投影为现有的持久化内容和模型可见内容。
 
 ## 决策
 
@@ -74,6 +74,6 @@ MCP 桥接层通过 `McpResult<{...}> = { content: JsonValue[]; structuredConten
 
 ## 影响
 
-Native 和回放行为仍以内容为先，并保持逐字节兼容；执行期调用方则无需解析内容，即可使用经过校验的领域值。失败结果必须包含消息，并可选择附加内部类名／代码信息；成功与失败结果由判别字段区分，失败结果绝不会承诺存在值。工具作者必须一并设计值及其 Native 投影；增加这项声明是有意为之，因为它避免从自然语言内容意外推导出程序化契约。
+Native 和回放行为仍以内容为先，并保持逐字节兼容；执行期调用方则无需解析内容，即可使用经过校验的领域值。失败结果必须包含消息，并可选择附加内部类名／代码信息；成功与失败结果由判别字段区分，失败结果绝不会承诺存在值。工具作者必须一并设计值及其 Native 投影；增加这项声明是有意为之，因为它避免从自然语言内容意外推导出程序化约定。
 
-中间值只受产生它们的能力和进程内存限制。日志不包含这些值，因此回放无法恢复；仅处理内容的 post 策略也无法隐藏这些值。这些都是执行期本地契约的明确属性，并非意外缺口。
+中间值只受产生它们的能力和进程内存限制。日志不包含这些值，因此回放无法恢复；仅处理内容的 post 策略也无法隐藏这些值。这些都是执行期本地约定的明确属性，并非意外缺口。
diff --git a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
index 42b61e04c1..152bae16ac 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.md
 2026-07-20-unified-json-value-schema-dsl.md: 5de3523eab15a91ea32dc09e2e239146fadea6f1
-2026-07-20-unified-json-value-schema-dsl.zh.md: 8521e03beb7398ebfdf5e5cddae7a99471aa38d7
+2026-07-20-unified-json-value-schema-dsl.zh.md: 0dc38dc289a32269c0f9e545ae53a8098ba02189
diff --git a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
index 8521e03beb..0dc38dc289 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-工具参数使用一套精简的作者侧 schema DSL，subagent／工作流的结构化输出则使用另一套原始 JSON Schema 子集和校验器。两套词汇在根类型、标量约束和校验方式上并不一致；如果继续沿用这种划分，类型化的规范工具输出契约要么还需重复实现两条路径，要么只能接受部分投影无法强制执行的 schema。
+工具参数使用一套精简的作者侧 schema DSL，subagent／工作流的结构化输出则使用另一套原始 JSON Schema 子集和校验器。两套词汇在根类型、标量约束和校验方式上并不一致；如果继续沿用这种划分，类型化的规范工具输出约定要么还需重复实现两条路径，要么只能接受部分投影无法强制执行的 schema。
 
 ## 决策
 
@@ -33,5 +33,5 @@ Status: implemented
 - 显式的对象开放方式和类型正确的字面量约束会让格式错误的声明在编写或注册阶段快速失败，而不是拖到后续模型调用时才失败。
 - 有界类型推导会为常规声明保留有用的精确类型，并将异常深的尾部结构退化为 `JsonValue`；运行时 schema 强制执行在任意深度仍保持精确。
 - 原始工具仍可直接注册范围更广的 JSON Schema，但统一代码生成会把不受支持的 schema 视为未知类型，不会假装自己能够强制执行。
-- 每个属性的 `required: true` 仍是工具作者契约；原有推导路径暴露可选性缺陷后，类型级回归覆盖会锁定必填键不得为可选。
+- 每个属性的 `required: true` 仍是工具作者约定；原有推导路径暴露可选性缺陷后，类型级回归覆盖会锁定必填键不得为可选。
 - 运行时测试和编译期测试覆盖所有根类型、恰好匹配一个分支时的重叠／无匹配行为、原始 schema 的默认开放语义、显式开放方式、有损 JSON 值、类型推导、核心投影和动态投影中的深层嵌套、动态注册中 JSON 不可见的键，以及非普通 schema 数组。
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
index 46ec2eb556..7c13de5842 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
 2026-07-22-slot-type-chain-implementation.md: 2f0ec32766100e492c68c474f8798be3df0a3d15
-2026-07-22-slot-type-chain-implementation.zh.md: 75e89d3f57b96a1699981123e8361c775db2b8a7
+2026-07-22-slot-type-chain-implementation.zh.md: 6ef7eaa7614b88b33f0fa2aa6089e97eb3a45c25
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
index 75e89d3f57..6ef7eaa761 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
@@ -55,7 +55,7 @@ ctx.slots.register({
 
 第四种 `SlotKind`——`'chain'`——把路由权相对 `keyed` 反转：keyed 的分派现场以 `entryKey` 点选占用 slot 的 entry，chain 则由 entry 自荐——owner 只分派一套格式统一的 owner props，永远不知道谁来接管，新的接管包注册进来 owner 零改动。chain 注册携带一个 `select` 纯选择器（`ChainSelect<O, M>`：`(owner) => matched | null`）与可选的 `priority`（升序；同值保持注册序 = 装配序——部署可控的 inject 拓扑——复用 list `order` 的同一稳定排序）；注册缺 `select` 即上文装载即炸情形之一。渲染时 outlet 按链序依次执行各 select：首个非 null 返回值当选，该值以 `matched` 并入组件 props（组件绝不自行重新推导匹配）；返回 `null` 则轮到下一个 entry；全 null 则渲染 owner 的 fallback 体（`ChainRenderOpts`）。
 
-「不接」的判定住在 `select` 里，绝不在挂载后的组件里自探 props：组件为了渲染 null 也得先挂载，其 hook 与 effect 全部白跑，随之而来的挂载/卸载抖动还会破坏 memo 化与 React key 语义；而选择器是纯函数——可单测、零挂载副作用——与「presentation methods are pure functions of `args`」是同一条纪律。纯，就是选择器的契约：不读外部可变状态、不产副作用，路由判定因此完全是 owner props 的函数，每次分派都可安全执行。选择器只做路由，绝不创建新对象——按分派逐次构造对象会让引用每次渲染都换新；把匹配值包成更丰富的面这件事，发生在当选组件内部（以 `matched` 为依赖的 `useMemo`）。
+「不接」的判定住在 `select` 里，绝不在挂载后的组件里自探 props：组件为了渲染 null 也得先挂载，其 hook 与 effect 全部白跑，随之而来的挂载/卸载抖动还会破坏 memo 化与 React key 语义；而选择器是纯函数——可单测、零挂载副作用——与「presentation methods are pure functions of `args`」是同一条纪律。纯，就是选择器的约定：不读外部可变状态、不产副作用，路由判定因此完全是 owner props 的函数，每次分派都可安全执行。选择器只做路由，绝不创建新对象——按分派逐次构造对象会让引用每次渲染都换新；把匹配值包成更丰富的面这件事，发生在当选组件内部（以 `matched` 为依赖的 `useMemo`）。
 
 类型链上，chain entry 的 SlotMap 形状是 `{ kind: 'chain'; scope; owner }`，`owner` 即链的货币；`M`——`matched` prop 的类型——从 select 返回值推导（选择器收窄 union 成员时，`matched` 类型自动随之收窄），且组件位不参与 `M` 的推断，与钉住 inject 份额的 NoInfer 裁定同源（见下文裁定）。owner 侧，`renderSlotChain(key, owner, { fallback })` 与 `renderSlot` 同住 `PropsRenderSlots` 份额，其键域静态收窄到本 entry children 声明中 chain kind 的键（`ChainKeysOf`）；分派现场只有一行，不含任何自有的派生或路由逻辑。
 
@@ -117,5 +117,5 @@ register 签名里的两条硬化裁定之所以存在，是因为显然的替
 | 模块级 store 句柄 | 模块级句柄是跨插件重载与跨测试用例的单例；工厂形把身份圈定在单次 apply/测试调用内 |
 | 组件直收 store 实例 | 渲染代码里能用 `update`/`set`，变更面就无从审计；声明的 actions 让「什么能变」保持为 register 现场的事实 |
 | 注册位用 `FC` / 从组件推断 `I` | FC 静态位产生协变噪音、拒绝合法组件；组件侧推断静默吸收 props 漂移（见上文裁定） |
-| 接管 slot 用 keyed 分派 + owner 侧路由 | owner 会不断攒下逐 entry 契约与硬编码路由表（每种接管一份 `find` + `entryKey`）；chain 货币让新增接管注册保持 owner 零改动 |
+| 接管 slot 用 keyed 分派 + owner 侧路由 | owner 会不断攒下逐 entry 约定与硬编码路由表（每种接管一份 `find` + `entryKey`）；chain 货币让新增接管注册保持 owner 零改动 |
 | 组件靠渲染 null 表示不接 | 不接也得先挂载——hook 与 effect 白跑，挂载/卸载抖动破坏 memo 化与 key 语义；纯选择器无需组件实例即可裁决 |
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
index 831d3c790f..0575e85c1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
 2026-07-22-unified-send-and-coalesced-user-messages.md: f32d6ca65d5236e1fabdd177cdf54e36929c853f
-2026-07-22-unified-send-and-coalesced-user-messages.zh.md: af829714276b1a77b8147d89a9be1c9ff6a007a5
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 6148cf4e0dda9032fca0ced5b466787877b89fa0
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
index af82971427..6148cf4e0d 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -50,4 +50,4 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 - [one-send-one-turn](../simplification/2026-07-17-one-send-one-turn.md)——本决策所依托的“每轮次只认领一条消息”规则。
 - [remove-agent-steering-mirror](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)——折叠镜像实时事件的先例。
 - [explicit-turn-cancellation](2026-07-16-explicit-turn-cancellation.md)——`keepInbox` 所扩展的取消原因信号。
-- [带标识的不可变消息值](2026-07-28-identified-immutable-message-values.md)——本路由决策现在所依托的消息标识与表示契约。
+- [带标识的不可变消息值](2026-07-28-identified-immutable-message-values.md)——本路由决策现在所依托的消息标识与表示约定。
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index f8a9c8c260..021857e30b 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
 2026-07-23-client-plugin-loading-model.md: 2dc0c68e5f20bd790c2362f92c16dece171babf5
-2026-07-23-client-plugin-loading-model.zh.md: ce7850e37b9ae2735565a35ce3de28f4f290ed04
+2026-07-23-client-plugin-loading-model.zh.md: 8cb8fb5523475fd0cc03fa20fc04422c6b7397e3
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index ce7850e37b..8cb8fb5523 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -31,7 +31,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 - **普通包**是模块系统自身所需的绝对基座，加上尚未转成 DI 的库：react 家族、cordis、`@deepseek-ai/dsh-client-modules`（模块系统本身——它永远不可能是插件，因为模块先于一切模块）、web 壳内核，以及——暂时——ui-slots、web-react、ui-primitives。普通包打进壳 bundle、播种进模块表、对 host 图不可见。
 - **插件包**是其余一切。每个都携带 `dshClient` manifest（元数据清单）声明（`{ platform, inject, immediately? }`）和同一种统一形态：共享 tsdown 预设产出 `lib/client.js`，`exports["./client"]` 指向该 bundle。每个都是 host 独家撰写的图里受治理的 entry。当前包括：connection、runtime、ui-theme、i18n、hmr（仅进 dev 图）、ui-layout、ui-sidebar、ui-conversation、ui-model-selector、ui-question、ui-trajectory。
 
-manifest 拥有包的装载契约：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
+manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
index 4be81330b6..d328c8a065 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
 2026-07-24-separate-context-injection-from-turn-execution.md: bb28d96cf1494d94ad7a7d4a4714e536c7072d2f
-2026-07-24-separate-context-injection-from-turn-execution.zh.md: 6debc6cf5e8fb7358ca8697fa64f175fb700d991
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 0edf3f4e8a062fe82462e263da383e27d79034c5
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
index 6debc6cf5e..0edf3f4e8a 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -71,4 +71,4 @@ enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。wate
 - idle 注入只有在后续 pre-step 接纳它后才会对模型可见，并可能被取消或 dispose 丢弃，而其持久 inbox 生命周期仍会保留记录。
 - 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器会保留这一顺序。
 - 必须影响当前请求的上下文要从 `agent/pre-step` 返回；普通注入只支持在最近的后续边界交付。
-- 公共投递契约和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。
+- 公共投递约定和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
index 19176b7654..cf3169bccf 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
 2026-07-24-single-harness-home-resolver.md: 159ba88b7b4a8d50f1be2cbe5d9162a654014e16
-2026-07-24-single-harness-home-resolver.zh.md: 89069c8e98e80be387fbc6b1630219b451be7bd6
+2026-07-24-single-harness-home-resolver.zh.md: ed4701bbd4e37ec5c9fba02767efabfbef8d065d
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
index 89069c8e98..ed4701bbd4 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
@@ -32,7 +32,7 @@ explicit configured path  >  $DSH_HOME  >  ~/.dsh
 
 **采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。telemetry 对齐到同一根目录——而不是保留自己的 XDG 路径——正是本决策所要消除的那种分歧。
 
-**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块契约据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。
+**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 7e3c02691b..06bfd11c4f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
 2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 1319a0d5a4eba4d70b0268605a0957c9a2eca7a9
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: cccc0b6d8f7309c5344e042d9cc2171587a18cb5
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 1319a0d5a4..cccc0b6d8f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -61,7 +61,7 @@ Session 实例与 scope 同生命周期，存活资格 = host listed（一个判
 
 「实体化但无首讯」的会话经 summary 派生位 `blank` 治理（派生列而非 header 字段，SessionHeader 保持不可变）：
 
-- host 判据：`session.events.length === 0`（零日志事件 = 尚无用户消息）。live 会话 `summarize()` 内存直读；cold 会话恒 `false`——lazy-create 契约保证 never-appended 会话根本不进 `persistence.list()`（JSONL/SQLite 两后端均已实证真 lazy），blank 从不落盘。
+- host 判据：`session.events.length === 0`（零日志事件 = 尚无用户消息）。live 会话 `summarize()` 内存直读；cold 会话恒 `false`——lazy-create 约定保证 never-appended 会话根本不进 `persistence.list()`（JSONL/SQLite 两后端均已实证真 lazy），blank 从不落盘。
 - wire 承载两处：`SessionSummary.blank` 必填列；`host/session-added` 帧必填 `blank` 字段（创建时恒 true，供别的 tab 按同一空会话状态入镜像）。
 - client 镜像只降不升（单调），三来源翻转，全部复用既有 wire 信号：
   - 发送方本地：首次 `prompt()` 的**成功响应**翻 false（受理即证明 user/message 已入 host 日志——此点翻转是确证而非乐观；`onEngaged` 同步更新列表镜像，当前 `New Session` 行原地转为普通标题，不新增列表行）。首讯被拒则会话保持 blank：与 host 权威对齐、继续显示为 `New Session`、在仍为该工作区成员时保持 connectWorkspace 复用资格。
@@ -77,7 +77,7 @@ Session 实例与 scope 同生命周期，存活资格 = host listed（一个判
 - 复用臂：list mirror 中找 `blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd。没有账户槽位的 cwd 匹配（CLI（命令行界面）/TUI 在 host cwd 创建的会话，或已删除/重建的注册）会打开一个任何分组表面都无法显示在该工作区下的会话，因此落到新建臂（见[成员复用修复](../bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md)）；命中直接返回该 id，不新建。
 - 新建臂：未命中则 `session.create({workspaceId})`，返回新 id。
 - 未知 workspaceId fail loud（不静默创建到别处）。
-- 解析保证（两臂同契约）：promise resolve 时返回的 id 已在 list store 且 `sessions.binding(id)` 同步可解析——`SessionsService.create` 在 RPC 成功后同步投影列表再 resolve，使 draft 搬运方可以在 open 之前往新 scope 的 machine 写文本，不等 notifier flush。
+- 解析保证（两臂同约定）：promise resolve 时返回的 id 已在 list store 且 `sessions.binding(id)` 同步可解析——`SessionsService.create` 在 RPC 成功后同步投影列表再 resolve，使 draft 搬运方可以在 open 之前往新 scope 的 machine 写文本，不等 notifier flush。
 - 调用方拿 id 自行 `sessions.open`；首讯发送就是普通 `session.prompt`——会话本来就在，失败即普通 prompt 失败，draft 文本还在 machine 里，重试即再次发送。
 - 全局 New Session 按钮默认取 `recentWorkspaceId`：先比较各 Workspace 内 Session 的最新 `updatedAt`，无 Session 时回退 Workspace `createdAt`，同值保持 Host 顺序；只有完全没有 Workspace 时才 `sessions.clear()` 进入无会话视图。Workspace 分组内的创建动作仍显式命中该 Workspace。
 - 运行时启动时订阅首次完整基线：若已有恢复成功的 current 会话则保持不动，否则自动 `connectWorkspace(recentWorkspaceId)` 并 open 返回的 blank 会话。该策略只结算一次；之后用户主动 clear 不会再次被自动选择覆盖，连接失败则等下一次基线投影重试。
@@ -131,6 +131,6 @@ slot scope 是闭集 `root | session-maybe | session`：
 
 - 插件获得与 host 同构的会话上下文：逐会话状态挂 actx、随 scope fiber 一次拆装，泄漏结构性不可能；双会话隔离由 scope filter 结构性保证。
 - client 对象层收敛为 wire 镜像：会话身份、生命周期、能力判别全部以 host 实体为准——输入体系（下一层）面对的永远是「有真 Agent 的会话」，slash/skill 等提供方一律以 sessionId 直接寻址。
-- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），回收靠 lazy persistence 的既有契约（重启蒸发），常规上限靠同 Workspace 复用。
+- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），回收靠 lazy persistence 的既有约定（重启蒸发），常规上限靠同 Workspace 复用。
 - 代价：id→ctx 换乘纪律、provide 的 Concurrent 纪律都是约定而非类型强制，靠 review 与测试钉住；「未选 workspace」期间输入全禁是产品面接受的体验代价（单一状态轴换来的）。
 - 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，等独立分支）。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
index 1742b6587e..f53930928f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
 2026-07-25-web-command-surfaces-and-assembly.md: 4c4a400abab940baebc1699fc15b709419865f0c
-2026-07-25-web-command-surfaces-and-assembly.zh.md: 092401751aa16c1a0ec4446d85a9f2591ee18425
+2026-07-25-web-command-surfaces-and-assembly.zh.md: f0d460199dcd947776924380d51fa6ceb65c9fe2
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
index 092401751a..f0d460199d 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 
 ### ui-command：`CommandService` + 按会话键控的 `CommandDirectory` + 逐会话 `PopupSelectController`
 
-- 投影 `ClientSessionContext { sessionId }` 自持于 ui-slash 契约（types.ts）：会话恒 agent-backed，会话身份即命令能力的全部投影；wire 以 `{sessionId}` 寻址（`command.list` / `command.execute` 均是；host 从会话 header 解析 Agent）。
+- 投影 `ClientSessionContext { sessionId }` 自持于 ui-slash 约定（types.ts）：会话恒 agent-backed，会话身份即命令能力的全部投影；wire 以 `{sessionId}` 寻址（`command.list` / `command.execute` 均是；host 从会话 header 解析 Agent）。
 - 目录按 `SessionId` 分区，per-key single-flight + epoch guard（旧拉取永不覆盖新态），`commands/changed` 全 key 软失效（旧快照继续服务、后台重拉）、`connection/reset` 全 key 硬失效并预热，Enter 必须等待当前 key 就绪、失败留草稿不降级。预热挂 source 的 `warm` 钩子——scope 出生时对全 roster 一次，即覆盖整个会话生命周期（会话能力自出生恒定）。
 - `register(contribution)` 注册 client 命令（descriptor + `available(projection)` + popupSelect spec）；候选合成 = host 目录 + contribution 可用性过滤，再过 query/position，host/contribution 重名 fail loud。
 - 命令三型按注册面派生，开发者不声明位置：host descriptor 带 `input` = **leadingInput**（回填 `/name ␣` + claim，继续打参数，仅限行首）；client 注册 popupSelect spec = **popupSelect**（官方选择框壳，业务零组件）；两者皆无 = **execute**（选中即执行，零 UI）。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index f22f2340ac..5605f1681e 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
 2026-07-25-web-input-machine-and-slash-pipeline.md: 39ef214a94fcd019f535fb60136d5dcc09b54e60
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 9b0ca0cadbc5e0212048b165f0d60d567a5639ad
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: dbd1aebff58c12f33dfe146d5cf4895801035bce
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index 9b0ca0cadb..dbd1aebff5 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -50,7 +50,7 @@ occurrence 表与 chip 三投影：
 
 ### 跨插件输入改写：三个 scoped bail 事件
 
-契约声明在 ui-slash（依赖最底层），生产者经 `sctx.bail(sctx, ...)` 派发，唯一消费侧是 hub 建 shell 时挂在 sctx 上的三个 listener；返回 `true` ⟺ 机器过 phase + CAS 守卫并实际改写（发出事件 ≠ 修改成功，Space 是否 `preventDefault` 以返回值为准）：
+约定声明在 ui-slash（依赖最底层），生产者经 `sctx.bail(sctx, ...)` 派发，唯一消费侧是 hub 建 shell 时挂在 sctx 上的三个 listener；返回 `true` ⟺ 机器过 phase + CAS 守卫并实际改写（发出事件 ≠ 修改成功，Space 是否 `preventDefault` 以返回值为准）：
 
 - `slash/input-begin-command` `{claim, span}`——菜单 pick / Space 裁决出的命令 claim 回填（SlashController 派发）。
 - `slash/input-insert-reference` `{reference, span}`——引用 chip 插入（SlashController 派发）。
@@ -74,13 +74,13 @@ occurrence 表与 chip 三投影：
 - ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true))`：summary 已证实为空的 Session 在任何 open state 下都保持 Hero，未经证实的 Session 则在 loading 期间进入 settling。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在 prompt 成功受理后翻 false。
 - 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt` 且固定 `mode:'queue'`（Web UI 无 steer 入口；host 线缆上的 `mode:'steer'` 不经此 machine）；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。
-- Notifier 双位契约：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
+- Notifier 双位约定：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
 
 ### 纯文本引用（决策 21）：text outcome 与 lexicon 装饰
 
 skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
 
-- PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同契约：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
+- PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同约定：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
 - source 可选 `lexicon?(session)` 钩子：同步热快照名录，`undefined` = 数据未热——零装饰、永不触发 fetch（渲染路径保持同步无副作用）；配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化（目录 settle、子代生灭）时的失效通道。controller 把各名录聚合进自己的 `lexicon` snapshot store（每次 source 通知重拉）；scope 出生后才注册的 source 由 service 广播给活 controller，补 warm 并并入名录。
 - `decorations.scanTextRefs`：词边界扫描 draft（行首/空白后的 `/name`、`@name`，`x/name` 永不命中）对照名录，命中即 `.textRef` mark（backdrop 纯 range 高亮，同 hlToken）；编辑破坏匹配形状下次扫描自然消失。
 - 发送即原文（不再 `<skill>` 序列化）；气泡侧 MessageItem 双形状装饰（legacy `<skill>` 标签 + 纯文本 token）。
@@ -116,7 +116,7 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 | ActiveCommand 中间态 / registerMode 模式注册表 / 从 draft 推导命令态 | claim 由 pick 路径显式建立——无表、无推导 |
 | bindTarget/bindDraft 对象直连 | 反向耦合 + root 单例跨会话误配；scoped bail 事件保依赖倒置且路由结构性正确 |
 | 统一 slash/input-apply 或全事件化 | 三个独立 payload 覆盖跨插件改写；异步链路保持 registry 显式调用 |
-| contenteditable / 富文本树 | 兼容性差；textarea + U+FFFC + occurrence 表覆盖全部交互契约 |
+| contenteditable / 富文本树 | 兼容性差；textarea + U+FFFC + occurrence 表覆盖全部交互约定 |
 | draft 双持久化 {text, occurrences} | mirror 写剪贴板投影零新概念；chip 跨刷新降级可接受 |
 | 原生 textarea undo 栈 | 受控 + 程序化写入下不可靠；粘贴两段 undo 语义只能自管 |
 | InputBar 收 16 员 wiring 回调包 | 消费矩阵实证 11 员 InputBar 独占、1 员死成员；标准件通道让组件自取，键盘面包内私递 |
@@ -130,6 +130,6 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 ## 后果
 
 - 一个常驻 conversation 外壳承接 no-session/blank/active：无 session → blank 保持 ConversationRoot、Hero、root scope Workspace picker、scrollport、composer seat、InputBar 与 textarea；只有严格 session header 和 body outlet 开始承载内容。同一 blank session → engaging/active 也保持 InputBar 与 textarea。EmptyState 与受控 intent 链（`sessions.updateIntent`/`updatePendingPrompt`/`workspaces.sendSession`）随最后消费者一并删除。
-- 输入面对命令零知识 + 可选依赖：无命令包时纯输入可用；`@` 引用与 skill 引用免费复用同一菜单/pick 管线。代价是空格/回车裁决是逐 source 轮询协议，其应答语义（同步/异步、undefined 含义）为冻结契约。
+- 输入面对命令零知识 + 可选依赖：无命令包时纯输入可用；`@` 引用与 skill 引用免费复用同一菜单/pick 管线。代价是空格/回车裁决是逐 source 轮询协议，其应答语义（同步/异步、undefined 含义）为冻结约定。
 - 提交事务化（attempt seq + 漂移守卫）使晚到结果回灌、会话切换、concurrent 重放三类缺陷结构性不可能，由矩阵测试钉住。
 - 已知欠账：chip 跨刷新保真（可复用粘贴匹配）未立项；subagent 引用的模型表示待业务立项。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
index 881981631c..938d86ef4b 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
 2026-07-26-packed-chunk-rows-by-default.md: d6a044676604e4a4512a7a6674edb80e120b2f3c
-2026-07-26-packed-chunk-rows-by-default.zh.md: 2488ab1d972b89b1248733482e8e4239b83797e2
+2026-07-26-packed-chunk-rows-by-default.zh.md: 0e3e06e0d4185603cd21939589855a51797560a4
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
index 2488ab1d97..0e3e06e0d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
@@ -26,7 +26,7 @@ JSONL 后端会打包每个持久追加批次。原始模式 `compression: 'none
 
 每个签入仓库的会话格式 JSONL fixture 都使用规范打包表示。`scripts/session-fixture-layout.snapshot.ts` 会在整个仓库中发现已跟踪的 `*.jsonl` 文件，以及未被忽略的新增未跟踪 JSONL 文件，选择首条记录为 `session` header 的文件，解码所有正文记录，并拒绝与 `packChunkRuns()` 输出不同的内容。因此，该清单无需维护路径列表即可覆盖 ACP、headless、TUI、`apps/web`、父会话、子会话以及未来的 fixture 名称。
 
-ACP 和 headless 快照运行会采集默认 JSONL 后端的输出。TUI 和 web 的记录模式写入器会在写入 fixture 前，对内存事件应用 `packChunkRuns()`。人工编写的 `packed-chunks` ACP 场景在普通配置下运行，并保留全部 3 种打包行类型；其契约先解码独立的源 fixture 和目标 fixture，再断言二者逐事件相等。
+ACP 和 headless 快照运行会采集默认 JSONL 后端的输出。TUI 和 web 的记录模式写入器会在写入 fixture 前，对内存事件应用 `packChunkRuns()`。人工编写的 `packed-chunks` ACP 场景在普通配置下运行，并保留全部 3 种打包行类型；其约定先解码独立的源 fixture 和目标 fixture，再断言二者逐事件相等。
 
 聚焦的包测试保留非打包和混合布局输入，以验证读取器兼容性。这些测试不会让默认快照语料库豁免规范布局要求。
 
@@ -36,9 +36,9 @@ ACP 和 headless 快照运行会采集默认 JSONL 后端的输出。TUI 和 web
 
 只要较旧分支仍可能携带 fixture 改动，测试政策和 ACP 快照 README 就会继续链接该命令。最新的开放 PR（Pull Request）清单确认每个受影响分支均已合并、关闭或符合规范后，[移除提案](../../proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会删除该 CLI、包命令、本过渡章节和文档链接，并替换永久门禁中仅适用于该命令的修复指引。共享规范布局转换器与快照门禁保持永久存在。
 
-### 验证契约
+### 验证约定
 
-JSONL 持久化测试证明：省略选项时会写入打包行，显式传入 `false` 时会按每个事件一行的形式写入，两种形式都会加载为完全相同的事件。规范布局转换器单元测试覆盖 header 保留、非打包转换、非会话 JSONL、已打包输入的幂等性和畸形输入。无密钥快照门禁覆盖每个签入仓库的 fixture 和组装后的回放路径；文档门禁则确保配置默认值与双语契约保持一致。
+JSONL 持久化测试证明：省略选项时会写入打包行，显式传入 `false` 时会按每个事件一行的形式写入，两种形式都会加载为完全相同的事件。规范布局转换器单元测试覆盖 header 保留、非打包转换、非会话 JSONL、已打包输入的幂等性和畸形输入。无密钥快照门禁覆盖每个签入仓库的 fixture 和组装后的回放路径；文档门禁则确保配置默认值与双语约定保持一致。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
index 9b9fd5aad6..6b969a2c03 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
 2026-07-26-task-registry-seam.md: 57ac176cf6d2b0a50fcbcfacd77f6a26b462b582
-2026-07-26-task-registry-seam.zh.md: d32de0cc62e1d7a2b5e5d70187e742aa0392fe29
+2026-07-26-task-registry-seam.zh.md: b81940a8f778f1ed9a65bf96e3a66c047fd234c2
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
index d32de0cc62..b81940a8f7 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
@@ -6,30 +6,30 @@ Status: implemented
 
 ## 问题
 
-[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 契约，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
+[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
 
 ## 决策
 
 `tasks/` 如今是一个 bash 三件套形态的三包能力家族：
 
-- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的契约（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
+- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
 - **`@deepseek-ai/dsh-tasks-local`（实现）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；seam 包不含任何实现依赖。
 - **`@deepseek-ai/dsh-tool-tasks`（消费方）**——保持不变；它注入 `'tasks'`，从不导入实现类型。
 
 各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即定义缺失的 `ctx.tasks` 服务的 seam 包；seam 自身的对外呈现（其 README 与直接挂载防线）会指向各实现，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
 
-该 seam 保持进程内契约语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
+该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
 
 ## 曾考虑的替代方案
 
-**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更契约）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里；而若维持现状，它们今天还会连带搅动每个消费方的实现依赖。
+**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更约定）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里；而若维持现状，它们今天还会连带搅动每个消费方的实现依赖。
 
 **在单个包内仅抽取接口（在具体类旁导出一个抽象类）。**否决，因为它在运作层面并未分离任何东西：消费方依然依赖携带实现及其依赖项的那个包，而替换后端若不把本地实现纳入自身依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
 
-**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法契约才是。生产方需要的是服务键和语义，而不只是类型形状。
+**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法约定才是。生产方需要的是服务键和语义，而不只是类型形状。
 
 ## 后果
 
-换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级包，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述契约；生命周期簿记方面的事实归实现包的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
+换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级包，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述约定；生命周期簿记方面的事实归实现包的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
 
 代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名实现包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 seam 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load an implementation such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
index 1c6a23eec8..132c12bbf7 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
 2026-07-27-compiler-independent-typert-model.md: 15641e5f785c5d2daecbfc2d5cffedd64d8384a7
-2026-07-27-compiler-independent-typert-model.zh.md: 7bddd3ffde343346c163f55ef493c32bad1e8314
+2026-07-27-compiler-independent-typert-model.zh.md: 409dbc7eb20cc746c2ebb2a891384d65d7da1bc6
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
index 7bddd3ffde..409dbc7eb2 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
@@ -22,7 +22,7 @@ PackageModel 识别 Cordis service、event、`@typert object` 引用对象和 `@
 
 [`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带 package-face reflection 与可选 Zod schema，并随 Cordis effect 撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
 
-包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 契约 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 契约。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
+包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 约定 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 约定。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
 
 构建期的 `CordisCatalogProjector` 一次消费分析后的 `FaceModel` 与 `TypeGraph`，生成 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md`，以及为 `tool-cordis` 提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` catalog。`tool-cordis` 读取该静态 catalog，运行时不依赖 `ctx.typert`。[`dsh-typert-loader`](../../../../packages/typert/loader/README.md) 与注册表仍是独立的运行时路径：loader 监听 Cordis Loader 配置项生命周期事件，导入显式发布的 `./typert` host 产物，并通过 `ctx.typert` 注册；两者都不是当前 `cordis_inspect` catalog 的数据源。
 
@@ -50,4 +50,4 @@ Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 pars
 
 新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围并对缺失能力失败。
 
-包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 契约 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
+包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 约定 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 1f44d8b4b7..cf0c363672 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
 2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
-2026-07-27-dispose-ladder-to-consumer.zh.md: 74cbc624e9153637dcdceb521c04af811799fdb0
+2026-07-27-dispose-ladder-to-consumer.zh.md: afa385120d6ac33e6084a56585d8d610622e604c
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 74cbc624e9..afa385120d 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**把阶梯作为便利方法留在句柄上。**否决：一个每个实现都必须提供的 seam 方法不是便利，而是契约表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
+**把阶梯作为便利方法留在句柄上。**否决：一个每个实现都必须提供的 seam 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
 
 **把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——这组堆叠变更刚刚删掉的那个单一用途库。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 048536527a..018c4812b1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
 2026-07-28-directory-picker-capability-seam.md: 01968990db81852dbf965a90fc151bab357ecb55
-2026-07-28-directory-picker-capability-seam.zh.md: ffbb939eabcca3e16711a4cadcadad50660a9e04
+2026-07-28-directory-picker-capability-seam.zh.md: f96f835c5f68d0ef6eff5410a7db18dc24eb8c2c
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index ffbb939eab..f96f835c5f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -6,13 +6,13 @@
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互契约**，不是同一契约的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
 
 ## 决策
 
-在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一契约方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
+在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
 
-**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 契约相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
+**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 约定相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
 
 并入本决策的位置与策略裁决：
 
@@ -29,7 +29,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick
 
 ## 曾考虑的替代方案
 
-- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举契约（hidden 标志、面包屑、home 锚点）不属于存储 seam。
+- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举约定（hidden 标志、面包屑、home 锚点）不属于存储 seam。
 - **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
 - **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture／测试后端，与促成这项工作的插件教义相悖。
 - **引入文件管理器／盘符枚举依赖。** 按上文调研否决；依赖政策要求记录于此。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml
index 187db47b0d..43e4b3d605 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md
 2026-07-28-experimental-plugin-package-group.md: 1ebae5dbb16d4c966f94ffde69fb0cb9bc163d80
-2026-07-28-experimental-plugin-package-group.zh.md: 633549bd47386de3eeb972052ecfdd164878e2f1
+2026-07-28-experimental-plugin-package-group.zh.md: 2d09451c5069a775906e5bc8748c334c29008164
diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md
index 633549bd47..2d09451c50 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md
@@ -10,15 +10,15 @@ Status: implemented
 
 ## 决策
 
-[`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) 中的子树规则要求所有公开契约整体处于实验状态或仅限内部使用的 Cordis 插件包位于 `packages/experimental/<pkg>/`。包名仍为 `@deepseek-ai/dsh-<pkg>`。
+[`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) 中的子树规则要求所有公开约定整体处于实验状态或仅限内部使用的 Cordis 插件包位于 `packages/experimental/<pkg>/`。包名仍为 `@deepseek-ai/dsh-<pkg>`。
 
 该分组供团队在仓库内共享工程人员和产品经理制作的原型：成员可以基于真实插件图发现、运行、评审并扩展彼此的原型，但这不代表产品会提供支持。
 
 官方发布版本不包含此目录。包只有移入对应的产品角色分组后才会纳入发布版本；发布包不得在运行时依赖此处的包。示例可以使用这些包；其他任何运行时依赖方也必须位于此处。测试可以将它们用作开发依赖。
 
-实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部契约，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。
+实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部约定，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。
 
-尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开契约、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
+尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开约定、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
index 34bdadf75b..307dc12518 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
 2026-07-28-identified-immutable-message-values.md: 472de8b133ba323c3e1ff5e53c8dacb3d66525c5
-2026-07-28-identified-immutable-message-values.zh.md: 6082fd5fb65f4acd0759a6c4b49be8110a559a73
+2026-07-28-identified-immutable-message-values.zh.md: d322ff93765294478d2adce41a5903f3a7fdd67d
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
index 6082fd5fb6..d322ff9376 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
@@ -16,7 +16,7 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则
 
 `createMessage(input)` 是角色通用的规范创建边界。它会生成 `MessageId`，将传入的角色、内容和来源与调用方对象解除引用关系，并在返回完整值前将其深度冻结。`createUserMessage({ content, source })` 为提示词和上下文生产方固定 user 角色。`createAssistantMessage({ content, source })` 同时固定 assistant 角色与模型来源类别，因此模型输出生产方只需提供内容和模型溯源信息。所有创建辅助函数的输入都不包含 id，因此调用方不会意外地把新消息的创建伪装成已有消息的导入。`freezeMessage(message)` 是独立的导入或转换边界：它会将已有标识的消息与调用方对象解除引用关系并深度冻结，不会生成替代标识。
 
-这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整契约只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。
+这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整约定只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。
 
 `Agent` 接口通过 `followup`、`steer` 和 `inject` 接收完整的 `UserMessage`。这些操作绝不会分配或返回标识；它们会冻结导入的值，而调用方已经持有该值的 id。inbox 领取和 `agent/pre-step` 会直接接收该消息。改写内容时会创建具有相同 id 的冻结替代值，而每个附加上下文都是单独创建的 `UserMessage`，拥有自己的 id。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 8cd6ad419a..3964ed6d04 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
 2026-07-28-portable-execution-world-consumers.md: 2cfdf08ac369048994ebc64d498caaa0847b77de
-2026-07-28-portable-execution-world-consumers.zh.md: ce6650a284e7d64fb1277c758bb77c2394e942c8
+2026-07-28-portable-execution-world-consumers.zh.md: 7e33c77d7ed901c955eb9a7b30f3e8c681e41940
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index ce6650a284..7e33c77d7e 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 只有文件操作、命令、终端和语言服务器共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
-普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
+普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期约定。
 
 ## 决策
 
@@ -46,7 +46,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 **为每项能力或工具创建独立沙箱。** 不予采纳，因为文件与进程操作将无法共享身份或状态，从而破坏编码用例，并增加生命周期所有者的数量。
 
-**把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
+**把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达约定。
 
 **把 PTY 就绪判断与会话策略移入进程管理服务。** 不予采纳，因为这些属于持久终端消费方的语义，而非 OS 进程机制。进程管理提供方负责只有其执行基底才能完成的操作；`dsh-pty-local` 负责 Harness 终端的语义。
 
@@ -56,11 +56,11 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop。
 
-**把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的契约、测试和消费方，同时避免把所有者变成无边界的能力集合。
+**把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的约定、测试和消费方，同时避免把所有者变成无边界的能力集合。
 
 **只通过 shell 命令实现远程文件系统操作。** 不予采纳，因为这会丢弃现有文件工具已消费的结构化文件系统身份、错误、流式输出、版本保护和原子变更语义。
 
-**新增通用分布式运行时抽象，或重新连接活跃句柄。** 不予采纳，因为现有能力 seam 已承载经证实的契约，而仅凭远程身份无法重建回调、待处理 promise、权限、协议状态或输出游标。新增一层只会推测 POC 边界之外的持久化与同步问题。
+**新增通用分布式运行时抽象，或重新连接活跃句柄。** 不予采纳，因为现有能力 seam 已承载经证实的约定，而仅凭远程身份无法重建回调、待处理 promise、权限、协议状态或输出游标。新增一层只会推测 POC 边界之外的持久化与同步问题。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
index 83f5bbef02..e876d151ab 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
 2026-07-28-user-settings-seam.md: bf93f95168b1b6d0dec5a9fc2c9aac5531f0564a
-2026-07-28-user-settings-seam.zh.md: e75cee19b600c3feca2475e609ca87d7e9a3ad7f
+2026-07-28-user-settings-seam.zh.md: 42e1196cfd8a4cc2ad1a4e2e2fee77bbd5ebbcd2
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
index e75cee19b6..42e1196cfd 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-**两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是契约：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。
+**两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是约定：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。
 
 **镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `<DSH_HOME>/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。
 
@@ -25,7 +25,7 @@ Status: implemented
 ## Alternatives considered
 
 - **以 Include 写回为用户层**（cordis-webui 式的按插件配置页写 loader entry 文件）：写回目标是按组合的文件，会把用户偏好绑死在某个 `cordis.yml` 上；用户层必须在模板升级中存活，并以同一文档服务 TUI 与 web。
-- **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者契约而非框架魔法。
+- **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者约定而非框架魔法。
 - **领域化的 settings 服务**（按产品域的 getter）：设计评审中的耦合反对成立；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。
 - **现在就做多层优先级**（Codex/Claude Code 式 system/managed/project 层级）：延后到真实第二层出现；resolve 步骤是分层未来唯一的扩展点。
 - **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——评审发现收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
index 9a0f384e0e..ca03afde36 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
 2026-07-29-projected-token-usage-and-request-context.md: 1e2c5ff067928620dee3d0937c247bec245e34f2
-2026-07-29-projected-token-usage-and-request-context.zh.md: fc885982ba45df68d456e153093005747ea74984
+2026-07-29-projected-token-usage-and-request-context.zh.md: 176e4929ac47dd2e83bf8361501b57058a3021f2
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
index fc885982ba..176e4929ac 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
@@ -20,7 +20,7 @@ Web 统计行原先从当前已加载的会话节点推导 token 总量。该窗
 
 `request/context` 是新增的仅入日志会话事件，记录请求所解析到的路由的、绑定注册项的元数据。AgentLoop 在步骤内紧随 `request/header` 追加它，数据取自 `prepareCall()` 现在与已解析配置一并返回的上下文元数据：正是那次已经校验过推理的、绑定注册项的查询，因此不会发生第二次解析。当提供方、模型和容量都与上一条记录相同时会跳过。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，从而清除较早路由的分母。
 
-容量刻意不进入 `EpochHeader`。该类型是重建契约，即请求由什么构建而成，而 `headerEquals` 会逐字段比较它，以判定某个快照是否真的是一次 `change`。容量是描述路由的适配器元数据，把它放进去会让容量变化伪装成请求封装的变化，还会把它拖进 AgentLoop 的重建不变式。
+容量刻意不进入 `EpochHeader`。该类型是重建约定，即请求由什么构建而成，而 `headerEquals` 会逐字段比较它，以判定某个快照是否真的是一次 `change`。容量是描述路由的适配器元数据，把它放进去会让容量变化伪装成请求封装的变化，还会把它拖进 AgentLoop 的重建不变式。
 
 两个单元都沿用标准投影生命周期：历史尾页基线、`session/projection` 实时帧、seq 高者胜的客户端存储、JSON 检查点、缓存恢复和单元卸载。系统没有任何 token 专用的历史字段、mux 帧、投影器、修订计数器或客户端栅栏。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index ae2347a7be..3111ab36ae 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
 2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
-2026-07-29-request-level-llm-config-credentials.zh.md: b2075798c9eb77d8fd8baecbbea77993ccda328f
+2026-07-29-request-level-llm-config-credentials.zh.md: 67a608293923291450ec3c226ac95ab4ff9f4af4
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index b2075798c9..67a6082939 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - **由桥接插件（`dsh-llm-models`）持有统一的 `models` 字典**——有了按插件划分的 namespace，就没有什么可桥接的了；它所需的适配器映射规则纯属凭空发明的间接层。
 - **把机密放进 settings.yaml 并靠 `role('secret')` 脱敏**——删除问题本身（引用）胜过缓解问题（脱敏 + 回填 + 同步告警）；编码 agent 同类产品在这一点上口径一致。
-- **注册表级的实时重试策略**——让 `providerRetryPolicy` 每次调用都重读，会静默改变所有注册都依赖的 `ctx.llm` 捕获契约；原地重新注册路由既保住该契约，又保持可观察。
+- **注册表级的实时重试策略**——让 `providerRetryPolicy` 每次调用都重读，会静默改变所有注册都依赖的 `ctx.llm` 捕获约定；原地重新注册路由既保住该约定，又保持可观察。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index e556108299..6c6a13bc33 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
 2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
-2026-07-30-package-manager-native-repository-cache.zh.md: ac72e5dc4ffa764e1dc430764a6f52fc083d32a4
+2026-07-30-package-manager-native-repository-cache.zh.md: 2dd10f756d0b26a7af89e74be034be83d95fcb0e
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index ac72e5dc4f..2dd10f756d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -16,7 +16,7 @@ vendor 中的 `@cordisjs/plugin-loader/repository` 导出 `RepositoryCache`：
 
 Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前 Node 可执行文件调用该包的 JavaScript 入口。它绝不探测全局可执行文件，也不经 Corepack 调用。每次缓存未命中都会创建一个隔离工程，其中只有一个名为 `repository` 的依赖；Git 与 GitHub 来源的解析和获取、pnpm 自身的内容寻址 store、依赖安装，以及仓库依赖图中的生命周期脚本均由 pnpm 负责。
 
-隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证契约。
+隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证约定。
 
 缓存项以精确 specifier 的 SHA-256 命名。同一进程内针对相同 specifier 的并发请求共享一项任务。安装在同级临时目录中进行；只有安装成功且存在包目录和标记时，系统才会把暂存目录原子重命名为最终键对应的目录。失败的暂存目录会被删除；如果另一进程已发布有效项，则以该项为准。后续进程会先校验标记与包目录，再返回稳定的 `node_modules/repository` 路径。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
index ab893fbb26..b8dcd32d8e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
 2026-07-30-settings-write-path-integrity.md: 7bd50adc8a812759c3ae3f80a50978d75baa712a
-2026-07-30-settings-write-path-integrity.zh.md: 600a3c7269510673433969c92d322fd1186d38f3
+2026-07-30-settings-write-path-integrity.zh.md: 155fb55b886ab41d11d947ee09194a367ac8a90f
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
index 600a3c7269..155fb55b88 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
@@ -20,9 +20,9 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 
 **写入持有以 `wx` 创建的同目录 `<file>.lock`。**读-渲染-rename 循环在一把跨进程写锁下运行，采用指数退避与 2 s 获取期限。竞争者会超时，但不会移除现有锁，因为锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方；遗留锁恢复须由操作者执行。读方从不加锁——rename 提交是原子的——因此竞争只发生在写方之间。重试与期限常量是协议不变式，而非部署配置。
 
-**观察者 dispose 达到完全停稳。**watcher 携带一个 `active` 标志，排队的调用即将启动时先检查它，因此在调用等待期间已经运行过的释放器能让这次启动彻底不发生；已启动的调用会登记进服务级的 `pendingTails` 集合，dispose 排空除了等待各写队列，还会等待该集合。`settings/updated` 扇出会把监听器返回的 thenable 的 rejection 收容进与同步抛错相同的监听器诊断；事件契约现已写明 `INVARIANT` 重抛只服务同步监听器——不变式配套插件必须保持同步，而已交付的那个配套插件本就是同步的。
+**观察者 dispose 达到完全停稳。**watcher 携带一个 `active` 标志，排队的调用即将启动时先检查它，因此在调用等待期间已经运行过的释放器能让这次启动彻底不发生；已启动的调用会登记进服务级的 `pendingTails` 集合，dispose 排空除了等待各写队列，还会等待该集合。`settings/updated` 扇出会把监听器返回的 thenable 的 rejection 收容进与同步抛错相同的监听器诊断；事件约定现已写明 `INVARIANT` 重抛只服务同步监听器——不变式配套插件必须保持同步，而已交付的那个配套插件本就是同步的。
 
-**写入边界只放行 JSON 数据。**调用时刻的快照就是一次 `cloneJsonShaped` 遍历：它把 patch 从调用方分离出来，并在任何内容持久化之前拒绝一切非 JSON 值——Date、Map、BigInt、非有限数值、函数、symbol、类实例、值为 `undefined` 的数组元素、循环引用——拒绝时附带该值以 `$` 为根的路径。显式为 `undefined` 的对象条目仍会跳过（稀疏 patch 契约），这一契约如今在边界处强制执行，而不再放在 `mergeLayers` 内部。
+**写入边界只放行 JSON 数据。**调用时刻的快照就是一次 `cloneJsonShaped` 遍历：它把 patch 从调用方分离出来，并在任何内容持久化之前拒绝一切非 JSON 值——Date、Map、BigInt、非有限数值、函数、symbol、类实例、值为 `undefined` 的数组元素、循环引用——拒绝时附带该值以 `$` 为根的路径。显式为 `undefined` 的对象条目仍会跳过（稀疏 patch 约定），这一约定如今在边界处强制执行，而不再放在 `mergeLayers` 内部。
 
 **YAML 编辑是叶子级 diff。**`renderYaml` 对比已存储分节与下一份分节，只对变化的值应用 `setIn`、对移除的键应用 `deleteIn`，并沿 map 递归。注释、锚点与格式在每个未触碰节点上、以及每个被改键值对的键节点上全部保留；数组等非 map 值在不相等时整体替换（`deepEqualJson` 是共享的判定谓词），其内部注释随之一并被带走。
 
@@ -31,7 +31,7 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 - **用 `proper-lockfile` 取代手写锁**——按“依赖优先于手写”政策做过权衡：该库几乎无人维护，其所有权与重试策略比这个单文件协议所需的更宽泛，而已交付的锁只是一个小型独占创建循环，带确定性的竞争测试。该政策偏向能删除自有代码的依赖；这个依赖只会把一个窄协议换成不透明的等价物。
 - **用修订号/CAS 取代锁**——rename 表达不了 compare-and-swap，因此 CAS 需要一个版本伴随文件或内容重哈希，外加每个写方里的一个重试循环；锁用一个原语实现同样的串行化，还让读方完全免锁。
 - **把外部编辑合并进正在进行的写入自身的分节**——seam 是在调用时刻可见的状态之上合并 patch 的，因此与写入竞态的同 namespace 外部编辑仍按后写胜出解决；要把外部编辑并进来，需要三方合并语义，而没有任何消费方提出过这种需求。写入会先发布外部状态，落败一方至少在被取代之前被观察到。
-- **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；契约里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。
+- **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；约定里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。
 - **保留 `structuredClone`、在提供方里做校验**——seam 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。
 
 ## 后果
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 6319b99fb2..6ee8b4bc32 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
 2026-07-30-static-repository-plugin-format.md: c9d755b925a6ea05eed71e75803397d2672df9f4
-2026-07-30-static-repository-plugin-format.zh.md: 361de64d2e98b9fb4ac42963e4ae48e77fbc7016
+2026-07-30-static-repository-plugin-format.zh.md: 70bcb09d989ae3a434e56847d9b628c5194ef56f
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index 361de64d2e..70bcb09d98 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -22,19 +22,19 @@
 
 `.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
 
-未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
+未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容约定。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
 
 ## 考虑过的替代方案
 
 **加载仓库自己的 Cordis 入口。** 拒绝，因为这会把宣传为静态的格式变成无限制代码加载 API，要求仓库作者依赖 Harness 内部实现，并重复普通 SDK／Plugin dependency 路径。
 
-**让生成包装模块直接实现 skills 和 MCP。** 拒绝，因为复制的运行时代码会与 `dsh-skill-local` 和 `dsh-mcp-client` 漂移，尤其是提供方失效、工具同步、失败和 teardown 契约。
+**让生成包装模块直接实现 skills 和 MCP。** 拒绝，因为复制的运行时代码会与 `dsh-skill-local` 和 `dsh-mcp-client` 漂移，尤其是提供方失效、工具同步、失败和 teardown 约定。
 
 **让每个生成包装模块 import Harness package。** 拒绝，因为 repository package 不应解析或锁定应用的内部依赖图。Loader builtin 提供一份由 app 所有的实现，并让生成包装模块保持无 import。
 
 **监视已准备 repository 资源。** 拒绝，因为一个精确 repository cache generation 是不可变的。Ref、子目录或配置变化会选择新 generation；第二套 watcher 会创造一套没有所有者的刷新身份。
 
-**把 MCP 连接失败当作 Loader 更新失败。** 拒绝，因为现有 MCP client 有意收束连接失败并不暴露工具。只对 repository source 改变该语义，会让同一 server 配置拥有两套失败契约。
+**把 MCP 连接失败当作 Loader 更新失败。** 拒绝，因为现有 MCP client 有意收束连接失败并不暴露工具。只对 repository source 改变该语义，会让同一 server 配置拥有两套失败约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
index 3128996f1e..a6be2d99e5 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
 2026-07-31-claimed-pre-step-inbox-lifecycle.md: 5184c00335b3084a8eb6d58fa33a0af8d3a16ed6
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4966ccc8a3a7535022c04f9445ca75102ccca71e
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4718b1b519051f0ae82b4c7f9d0599f45a800f1d
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
index 4966ccc8a3..4718b1b519 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 **reject 时把已领取批次重新入队。** 这看似保留重试行为，却会让否决隐式修改队列；若不为每个竞态加围栏，还会复制后续工作，并使 claim 无法成为原子所有权转移。
 
-**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二份契约，而持有确切消息标识的消费方并不需要这些字段。
+**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二份约定，而持有确切消息标识的消费方并不需要这些字段。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 45436c96e6..58470f9780 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
 2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 31d2410ee4809d0693f2e7897e61c50163bb0758
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: 215024467f6f76a79a1f48f33e9d3c5b216df08d
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 31d2410ee4..215024467f 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## Problem
 
-code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性契约。
+code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
 一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
-seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除契约，每个后端导入它们而非重新声明：
+seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个后端导入它们而非重新声明：
 
 - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。
 - `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。
@@ -21,24 +21,24 @@ seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移
 
 seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以 seam 名消费这些共享常量——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该契约与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
 
 ## Scope
 
 本 PR 只交付 seam 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。seam README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
-`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本契约要防止的可移植性分裂。
+`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
 ## Alternatives considered
 
 **每个后端声明自己的排除集。** 拒绝：这让可移植承诺变成逐后端成立。调用方在 worker 上测过的绑定列表可能被 Python 拒绝，而这正是 seam 存在要防止的分裂。
 
-**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的契约伸手进入兄弟实现。契约属于二者之上，即 seam。
+**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
 
 **在可移植标识符子集中保留 `$`。** 拒绝：`$` 是 JS 专有拼写。允许它会让 `$tools` 通过 worker 却在每个非 JS 后端上失败，为纯粹表面的好处破坏可移植性。
 
 ## Consequences
 
-获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一契约。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
+获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
 
 代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
index f63372c8b4..b8f2e4d7d7 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
 2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
-2026-08-01-packaged-ripgrep-search.zh.md: f2b1a12c737f772bff6a6c91c17f7453dbc89748
+2026-08-01-packaged-ripgrep-search.zh.md: d06841b220603d832048d1c76784f0e1d283679c
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
index f2b1a12c73..d06841b220 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 **让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
 
-**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具契约。
+**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index d3f73c3b5c..38adb776d6 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
 2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
-2026-08-02-typert-remote-method-calls.zh.md: da4459432e8c9e08821bcded2921cbd33fc5e8c8
+2026-08-02-typert-remote-method-calls.zh.md: 76c390487fcf224179c85b8aeaa8de9507757e65
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index da4459432e..76c390487f 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -10,7 +10,7 @@ Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事
 
 本决策只涵盖一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流仍采用独立设计。
 
-直接方法调用的契约属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
+直接方法调用的约定属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
 
 Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以不同类型合并同名 Cordis `Context`。Remote 投影不能把完整 Host 声明导入消费端，也不能依赖 Browser 专属类型；未来 TUI 若复用这套编程界面，也只能看到 Remote 标记的方法。本期不实现 TUI 接入，但实现边界不得阻断这种同构复用。
 
@@ -18,11 +18,11 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteScope()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
-Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
+Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一约定的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
 
 `@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.remote`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
 
-`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 契约，而不导入具体 Gateway 实现。
+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 约定，而不导入具体 Gateway 实现。
 
 ## 组件和 Cordis 服务
 
@@ -42,7 +42,7 @@ Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.http
 
 ## 业务声明
 
-普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 契约时，直接装饰该方法，不为此重命名。只有 wire 契约需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
+普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 约定时，直接装饰该方法，不为此重命名。只有 wire 约定需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
 
 ```text
 export class GoalService extends GatewayService {
@@ -87,7 +87,7 @@ export class ScopedGoalService extends GatewayService {
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
+Decorator 只表达“该方法参与 Remote 约定”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
@@ -217,7 +217,7 @@ Host lib build
 
 现有顶层 `build` 仍表现为先 `build:lib`、再 `build:web`，但 `build:lib` 内部必须先完成 Host 与 Remote artifact，再启动 Client TypeScript 编译。一次干净构建不能依赖上次残留的 `.d.ts`。
 
-即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 契约 pass。门禁调度器仅可在显式的 TypeRT 契约依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
+即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 约定 pass。门禁调度器仅可在显式的 TypeRT 约定依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
 
 ## `/remote` 包入口
 
@@ -236,7 +236,7 @@ Host lib build
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 ```
 
-该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一契约的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
+该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一约定的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
 
 业务 package 的发布文件必须同时包含 `lib/typert.remote-client.d.ts.map` 和 map 指向的 `src` 文件。生成 DTS 以 `//# sourceMappingURL=typert.remote-client.d.ts.map` 引用相邻 map；map 中的 source 从 `lib` 相对指向业务源码，例如 `../src/index.ts`。`/remote` export 不单独列出 map，package `files` 负责把它与源码一起发布。
 
@@ -309,7 +309,7 @@ await ctx.remote.$mount(goalsRemote)
 await ctx.remote.$mount(sessionsRemote)
 ```
 
-Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 契约和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 约定和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
 
 `ctx.remote.$mount()` 把 contribution 注册到 `TypeRT.remotes`，安装它的 namespace Service 和具体方法，并在它们就绪后才 resolve。调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
@@ -343,7 +343,7 @@ Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote
 
 TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
 
-Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
+Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 约定变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
 ## SRC 与 LIB 运行模式
 
@@ -454,7 +454,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
 - `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
-- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 契约向业务包暴露合并后的 Remote 类型。
+- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 约定向业务包暴露合并后的 Remote 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
@@ -490,9 +490,9 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 验证
 
-- Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
+- Goal Service 直接装饰业务签名已经符合 Remote 约定的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
-- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 契约；pre-push 钩子使用同一个已包含契约准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的契约 pass。
+- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 约定；pre-push 钩子使用同一个已包含约定准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的约定 pass。
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
@@ -504,9 +504,9 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 后果
 
-Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 契约 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
+Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 约定 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
 
-源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
+源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布约定。
 
 SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费方必须重新执行 lib build，因为系统没有增量 contract watcher。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 2969995da6..9414852f9c 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
 2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: ce91abd6dc71f790c72766cd3f819096d596182c
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: e487bd68c65f38332d09f661292c797a746b68d1
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index ce91abd6dc..e487bd68c6 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -64,4 +64,4 @@ pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `Cred
 
 ## Testing
 
-`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该契约：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项契约：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
+`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该约定：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项约定：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
index 2a4879b6aa..d6c40df351 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
 2026-08-04-websocket-downlink-carrier.md: b41ad687725c55acb8517fe7e93d645f007a0453
-2026-08-04-websocket-downlink-carrier.zh.md: 568240ec14592fba8444e5cc0a3bae2b35c45b94
+2026-08-04-websocket-downlink-carrier.zh.md: c8c8c34c7b7365bc3099cb33a5861051e015b226
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
index 568240ec14..c8c8c34c7b 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
@@ -22,7 +22,7 @@ WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和
 
 ## Verification
 
-webserver 契约测试钉住 upgrade pathname 分发、重复注册拒绝、disposer 与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、stream error 与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
+webserver 约定测试钉住 upgrade pathname 分发、重复注册拒绝、disposer 与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、stream error 与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
index 8a4b3606a8..6f00f147f3 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md
 2026-08-05-large-session-jsonl-restore-pipeline.md: eab53c683880ef7095233ed8122e532eb5add547
-2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 039e0c193179677b57e742d55f4c7df6bdff852f
+2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 2cd0d2ca20074d6adb0735db08071638ae2ced88
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
index 039e0c1931..2cd0d2ca20 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解码专用首帧并将其解析为会话头部，后续明文帧则按顺序产出并送入 JSONL 扫描器。
 
-`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误契约。迭代器产出的临时视图会在进入下一次迭代前被消费。
+`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误约定。迭代器产出的临时视图会在进入下一次迭代前被消费。
 
 累计帧处理时间约达 500 ms 后，异步读取器会在下一帧边界让出事件循环，并在继续前观察取消信号。单个帧仍是不可分割的同步操作。完整帧必须通过帧结束与校验和验证；只有结构上不完整的最终帧才使用既有前缀解码器进行恢复。
 
@@ -49,4 +49,4 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 
 快速解码器依赖运行时探测的 Node 内部接口，但接口不兼容时会改用公共实现，不会改变正确性。系统会在协作式帧边界让出点观察取消信号；截止时间并不是单个帧内部严格的挂钟时间上限。完整事件数组仍会驻留内存，因为它是活跃会话的权威日志；该流水线移除的是重复表示，并未对这份状态做分页。
 
-测试会强制执行两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性契约。
+测试会强制执行两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性约定。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index 09e63a6a1c..2fd0f4bd8e 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
 2026-08-05-session-preparation.md: 69d39f552ed3041403a24b5aefb435e4e721b09c
-2026-08-05-session-preparation.zh.md: a0ca27eb63552566c918c299bd5fba976687812c
+2026-08-05-session-preparation.zh.md: ec5b73e67c8ab9303f8840e16e4b4f2d928e7657
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index a0ca27eb63..ec5b73e67c 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -47,7 +47,7 @@ agent loop（智能体循环）通过同一条设置与发布流水线消费这
 
 ## 验证
 
-共享持久化契约覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
+共享持久化约定覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
index 43c5433343..9da3c3890f 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md
 2026-08-05-slot-declaration-injection.md: cb15125977c060144553d7cf75e3c2c26fb1b23b
-2026-08-05-slot-declaration-injection.zh.md: 385cab875bb445ba1ca324fc9b45363b8daf50b6
+2026-08-05-slot-declaration-injection.zh.md: 4b1fd40c26c6f055bb296807df4c888138ce7a64
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
index 385cab875b..4b1fd40c26 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
@@ -20,7 +20,7 @@ slot 级热替换还要求两个相互独立的所有者。移除声明方插件
 
 动态重载代码使用普通 Cordis 插件 fiber 作为替换单元：通过 `ctx.plugin()` 激活新模块；挂载替换模块之前，先 dispose 并等待旧 fiber；该 fiber 的 `slots.inject` 与 `slots.register` effect 会随之退出。renderer 订阅会观察到账本移除并卸载组件；无需建立 slot 自有的 fiber 树。
 
-## 失败与生命周期契约
+## 失败与生命周期约定
 
 如果注入创建时声明已经存在，回调 setup 失败会同步上报。延迟声明出现后发生的回调失败，会先取消订阅并回滚已收集的 effect，再在 slot 通知刷新之外上报，避免一个注册方使其他 listener 得不到执行机会。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常：注入是显式机制，不会削弱加载时验证。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
index b6e58aabc7..bd036ba86e 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.md
 2026-08-06-agent-event-payload-objects.md: 470c8fb3f9282005829846307778d3d1088c3888
-2026-08-06-agent-event-payload-objects.zh.md: ff201a7c3134c0ef809c9a798d65412541f9f1e7
+2026-08-06-agent-event-payload-objects.zh.md: 861a1b9c12c4ff050a9825212b02bc6c4e1c662d
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
index ff201a7c31..861a1b9c12 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，契约也一直分散在参数列表中，而不是集中在一个具名 payload 中。
+Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，约定也一直分散在参数列表中，而不是集中在一个具名 payload 中。
 
 ## 决策
 
@@ -18,7 +18,7 @@ dispatch 是融合的：`agentEvents(ctx, agent)`（以及一次性 `emitAgentEv
 
 ## 考虑过的替代方案
 
-**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，契约也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
+**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，约定也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
 
 **在每个 dispatch 位置手工构造主体。** loop 的中间设计调用 `ctx.waterfall(this.carrier, …)`，传入手工构造的 `{ agent: this, … }` payload；它避免了每次 dispatch 的分配，却重复了主体注入，并让作用域键与 payload 主体分叉。融合的 dispatcher 是每种 dispatch 模式的唯一注入点。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 0168528557..3bf5339f3e 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
 2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
-2026-08-06-subagent-list-identity-projection.zh.md: 368a70f5b3e5a27e4e1c648e8819476d40a57709
+2026-08-06-subagent-list-identity-projection.zh.md: 78aec8f4d0c47178bc033cc74f0314762f49cf7d
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index 368a70f5b3..78aec8f4d0 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -27,8 +27,8 @@ mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠
 
 与既有记录的关系：
 
-- 本记录取代 [durable-subagent-catalog](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) 中列表读路径的两项设计：经 `sessionQuery.traceSession` 枚举，与逐 child 读取描述符事件（`listEvents` 加精确 `readEvent` 双读、就地诊断分类）。diagnostic 行语义保留，分类改由列表按投影值缺席与 activity 派生；描述符事件仍是 mode/label 的唯一持久权威与折叠输入，恢复鉴权与激活契约不动。属部分取代，两记录保持交叉链接。
-- [session-projection RFC](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) 的 registry 契约（`ProjectionDefinition`、`snapshot`、`restore`）零改动，本记录只为其新增 `subagent` 身份 unit 一个注册项，并成为 snapshot（live）与 restore（cold）两处既有读法的又一消费实例——GUI history 的冷读已是同款。折叠规则只在 registry 注册一份；任何消费面都经 registry 计算，不存在第二份折叠逻辑。
+- 本记录取代 [durable-subagent-catalog](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) 中列表读路径的两项设计：经 `sessionQuery.traceSession` 枚举，与逐 child 读取描述符事件（`listEvents` 加精确 `readEvent` 双读、就地诊断分类）。diagnostic 行语义保留，分类改由列表按投影值缺席与 activity 派生；描述符事件仍是 mode/label 的唯一持久权威与折叠输入，恢复鉴权与激活约定不动。属部分取代，两记录保持交叉链接。
+- [session-projection RFC](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) 的 registry 约定（`ProjectionDefinition`、`snapshot`、`restore`）零改动，本记录只为其新增 `subagent` 身份 unit 一个注册项，并成为 snapshot（live）与 restore（cold）两处既有读法的又一消费实例——GUI history 的冷读已是同款。折叠规则只在 registry 注册一份；任何消费面都经 registry 计算，不存在第二份折叠逻辑。
 
 ### `subagent` projection unit
 
@@ -47,8 +47,8 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 ```
 
 - 投影是纯身份，**projection 体系不做失败通道**：unit 永不抛错；载荷损坏、版本不认识与整日志没有描述符一样，折叠结果是**可序列化的 null 哨兵**——map 条目为 `SubagentIdentityProjection | null`，非可选、非 undefined/缺 key。理由：registry 的 onChanged 推送经 JSON 序列化，undefined 字段被 stringify 丢弃，客户端帧校验拒收，消费方存储的旧身份将永不更新；null 完好过帧，消费方以哨兵替换旧身份。判定纪律：消费面把 null 与 undefined（仅 JSON 边界丢 key 可产生）一律视为无值。"算出来没有"如何呈现是消费方自己的事（见下文 `listChildren` 四态映射）。
-- label 强度由描述符 schema 决定：continuable 的 label 解析强制必有，one-shot 的本就可选；mode/label 判别与下文 child 行的强契约完全一致（行不携带 `seq`——它是投影内部的 own-suffix 证明）。
-- 身份携带 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无——`seq >= header.seedLength ?? 0` 证明身份折叠自 child 自身后缀，而非 fork 种子回放的祖先描述符。state 增 `seq` 使 unit `stateVersion` 升至 2，既存 checkpoint 行按 registry 契约版本失配失效、落权威重折。
+- label 强度由描述符 schema 决定：continuable 的 label 解析强制必有，one-shot 的本就可选；mode/label 判别与下文 child 行的强约定完全一致（行不携带 `seq`——它是投影内部的 own-suffix 证明）。
+- 身份携带 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无——`seq >= header.seedLength ?? 0` 证明身份折叠自 child 自身后缀，而非 fork 种子回放的祖先描述符。state 增 `seq` 使 unit `stateVersion` 升至 2，既存 checkpoint 行按 registry 约定版本失配失效、落权威重折。
 - 折叠规则：`subagent/descriptor` last-wins，与 `subagentTiming` 同一条 descriptor-reset 纪律——fork 前缀里的祖先描述符被自身描述符覆盖。损坏或版本不认识的载荷同样 last-wins：重置为 null 哨兵而非保留先前身份，健康祖先的 fork 不会继承自身描述符立不住的身份。
 
 ### 枚举：subagent 自管 live-preferred 合并
@@ -58,7 +58,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 - 过滤：`header.origin === 'subagent' && header.parentSession === parentSessionId`。
 - `hasChildren`：同一份合并材料向下看一层——存在 `origin === 'subagent'` 且 `parentSession` 为该 child 的直接后代。
 - `activity`：live 记录为 `running`，仅存在于持久化的为 `inactive`。
-- 排序：`createdAt` 升序、再按 child id 升序（与旧契约一致）。
+- 排序：`createdAt` 升序、再按 child id 升序（与旧约定一致）。
 - **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署，cold child 本就无法 resume，列出 live child 仍然有意义。（对照：旧实现在 sessionQuery 缺失时整体拒绝。）
 - persistence 列表失败使整次枚举失败；per-child 隔离只作用于逐 child 的冷读。
 
@@ -72,8 +72,8 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 | 2：cold child，cache 命中 | 可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 的 `subagent` 身份且 `identity.seq >= header.seedLength ?? 0` 才直接用——own descriptor 一经追加不可变，seq 门证明该值折叠自 child 自身后缀，无视行水位 | 零日志读 |
 | 3：cold child，兜底 | `persistence.inspect(id)` 整读 + `registry.restore({}, events, 0).snapshot.values.subagent` | 每次列表一次整读现算 |
 
-- 错误契约：`ctx.sessionProjections` 未挂载是配置错误，`listChildren` 在枚举前无条件检查并以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败——零 children 的部署同样确定失败，不因列表恰好为空而掩盖配置问题。会话存储同理：`ctx.get('sessions')`（严格全局读取，不走调用方作用域的属性代理）缺席以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 失败。两码的 wire 映射有别：apiproxy 只为 `PROJECTIONS_UNAVAILABLE` 设专门 wire 脸，`SESSION_STORE_UNAVAILABLE` 走通用 internal 兜底——apiproxy 组合自身就 inject `sessions`，该错误在其部署不可达，专门映射违反 need 原则。`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 已随 session-query 依赖删除。
-- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的响亮契约相对）。第二级任何抛错（包括缓存内任一 unit 行中毒使 `viewCheckpoint` 引爆）静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 切面早于描述符的行，`subagent` key 天然缺席，自动落底，无特判；行里的 null 哨兵同样不作数——一律落第三级，由权威重折裁决。创建窗口内的 count/interval checkpoint 可能把 fork 种子回放的祖先身份落进行——祖先 seq 落在 seed 区间，被 seq 门拒绝，同样落第三级裁决。
+- 错误约定：`ctx.sessionProjections` 未挂载是配置错误，`listChildren` 在枚举前无条件检查并以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败——零 children 的部署同样确定失败，不因列表恰好为空而掩盖配置问题。会话存储同理：`ctx.get('sessions')`（严格全局读取，不走调用方作用域的属性代理）缺席以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 失败。两码的 wire 映射有别：apiproxy 只为 `PROJECTIONS_UNAVAILABLE` 设专门 wire 脸，`SESSION_STORE_UNAVAILABLE` 走通用 internal 兜底——apiproxy 组合自身就 inject `sessions`，该错误在其部署不可达，专门映射违反 need 原则。`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 已随 session-query 依赖删除。
+- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的响亮约定相对）。第二级任何抛错（包括缓存内任一 unit 行中毒使 `viewCheckpoint` 引爆）静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 切面早于描述符的行，`subagent` key 天然缺席，自动落底，无特判；行里的 null 哨兵同样不作数——一律落第三级，由权威重折裁决。创建窗口内的 count/interval checkpoint 可能把 fork 种子回放的祖先身份落进行——祖先 seq 落在 seed 区间，被 seq 门拒绝，同样落第三级裁决。
 - per-child 隔离：单 child 的 cold 整读失败只使该行成为 `unavailable` diagnostic，下次列表自然重试，不影响 sibling（见四态映射）。
 - 冷路径的生命周期见证：preparation 的结果必须仍指向枚举时的那个生命周期——见证字段集与旧 SOURCE_CONFLICT 检查同款七字段（version、id、createdAt、cwd、parentSession、seedLength、delegationDepth）；同 id 删除后重新发布的会话对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
 - 冷读并发以常数 4 有界——它约束的是本地介质的一次只读扫描而非部署行为；出现联网 persistence backend 时提升为验证过的 `Config` 字段。
@@ -88,7 +88,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 
 ### `listChildren` 行形状与消费面
 
-`SubagentListEntry` **数据结构与重写前完全一致**——child 与 diagnostic 两臂、`kind` 判别、reason 三值、child 臂的 mode/label 强契约全部保留；变化只在诊断的信息来源：投影体系没有失败通道，diagnostic 由列表按投影值缺席与 activity 派生，列表本身零事件解析。"没有就等待硬读取"保证阶梯对健康数据必然算得出 mode/label。
+`SubagentListEntry` **数据结构与重写前完全一致**——child 与 diagnostic 两臂、`kind` 判别、reason 三值、child 臂的 mode/label 强约定全部保留；变化只在诊断的信息来源：投影体系没有失败通道，diagnostic 由列表按投影值缺席与 activity 派生，列表本身零事件解析。"没有就等待硬读取"保证阶梯对健康数据必然算得出 mode/label。
 
 ```ts ignore-check
 export type SubagentListEntry =
@@ -124,11 +124,11 @@ export type SubagentListEntry =
 已知边界偏差（有意接受，随本记录留档）：
 
 - 死于发布窗口的 fork child，seed 里若有祖先描述符，last-wins 会给出祖先身份，误现为 child 行；恢复仍按 own-suffix 折叠权威失败（`NOT_RESUMABLE`）。旧实现靠 `seedLength` 过滤将其 omit；projection unit 看不到 header，接受此残骸级偏差（`subagentTiming` 有同类既有暴露）。
-- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 契约本就保证恰一）。
+- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 约定本就保证恰一）。
 - live/persisted header 冲突，旧实现是 per-child corrupt；现枚举 live 优先、不做一致性校验，冲突不再被察觉，以 live 记录成行。
 - 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child `corrupt`，现统一成 `unavailable` 行（读侧无从区分成因）。
 - 未知 parent，旧实现经 session-query 抛 not-found（'parent session … was not found'）；现自管合并对不存在的 parent 得到空子集，枚举返回空列表，wire 上后续操作落到 child 级 subagent-not-found——语义与文案的静默变化，显式接受。
-- rung 2 的更晚事件窗口：cache 行恰在首个自有描述符之后落盘，日志随后追加第二个自有描述符（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃——此后冷列表的 rung 2 凭 seq≥seedLength 门持续供出行内旧身份（第一个自有描述符的值），与权威重折（last-wins 第二个）分歧，且 rung 2 命中期间不触发重折、无从察觉。边界三条：①前提是同一 child 出现第二个自有描述符，违反 establishing provider"恰追加一次"契约，属损坏类数据，与多描述符偏差同族同源；②需"损坏 + 崩溃错过 checkpoint（turn/end 与 disposal 两个 mandatory 点及 count/interval 节流点全部未及）"双条件同时成立；③健康 child（恰一自有描述符）不受影响——seq 门放行的正是唯一真身份。自愈条件：该 child 任一次 live 运行（turn/end mandatory checkpoint）或任何触发 cache.write 的时点，都会以新 fold 整行覆写（whole-record replace），rung 2 随即供正；权威路径（rung 3 重折、live snapshot、resume 折叠）自始正确，分歧只存在于持续冷、行未再更新期间的列表读。机制修法不采：gate 对账需知日志末端 seq，冷路径零读不可得；cache 行携 revision 是 opaque token，无法比较且跨域改 schema——按"cache 永不为权威"总纲归档为接受项。
+- rung 2 的更晚事件窗口：cache 行恰在首个自有描述符之后落盘，日志随后追加第二个自有描述符（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃——此后冷列表的 rung 2 凭 seq≥seedLength 门持续供出行内旧身份（第一个自有描述符的值），与权威重折（last-wins 第二个）分歧，且 rung 2 命中期间不触发重折、无从察觉。边界三条：①前提是同一 child 出现第二个自有描述符，违反 establishing provider"恰追加一次"约定，属损坏类数据，与多描述符偏差同族同源；②需"损坏 + 崩溃错过 checkpoint（turn/end 与 disposal 两个 mandatory 点及 count/interval 节流点全部未及）"双条件同时成立；③健康 child（恰一自有描述符）不受影响——seq 门放行的正是唯一真身份。自愈条件：该 child 任一次 live 运行（turn/end mandatory checkpoint）或任何触发 cache.write 的时点，都会以新 fold 整行覆写（whole-record replace），rung 2 随即供正；权威路径（rung 3 重折、live snapshot、resume 折叠）自始正确，分歧只存在于持续冷、行未再更新期间的列表读。机制修法不采：gate 对账需知日志末端 seq，冷路径零读不可得；cache 行携 revision 是 opaque token，无法比较且跨域改 schema——按"cache 永不为权威"总纲归档为接受项。
 
 消费面：wire、tool、GUI 的 diagnostic 处理**全部保持原状零改动**（`list_agents` 的 description 与 output schema 未动；该插件仅加载要求收窄——inject 去掉 `sessionQuery`）。行为上动的只有 apiproxy：路由段的 `hasSubagentDescriptor()` 扫描已删除，`hasSubagentOwner` 只看 `header.origin`——pre-#1569 的无 `origin` 存量不再被认作 subagent 属主，其本就不进目录，pre-release 立场接受；`subagents.history` 与 `session.history` 同源对齐——live child 用内存事件与注册表水位快照，cold child 用 `inspectServable` 直读持久化并 detached 折叠，不经查询服务，SESSION_QUERY_* 错误臂随之退役，wire 形状不变（`history` 的 JSDoc 措辞改为 live 内存快照／cold 持久日志双臂）。
 
@@ -151,9 +151,9 @@ export type SubagentListEntry =
 
 **给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
-**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强契约加算不出即 omit 更干净。
+**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
 
-**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担约定与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
 
 **registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
 
@@ -165,7 +165,7 @@ export type SubagentListEntry =
 
 ## 验证
 
-`packages/subagent/subagent/tests/list-children.spec.ts` 重写为本契约：无 persistence、query 服务与继续运行时的 live-only 列表；registry 缺席时零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`；live child 全程零 `inspect`、cold child 每次列表恰一次；多描述符 last-wins 取末者；损坏载荷与未知版本折为 `corrupt`；冷读失败映射 `unavailable` 且下次列表重试；fork seed 里的祖先描述符按该身份成行（偏差一钉住）；普通 fork 与无 subagent origin 的后代不入列也不计入 `hasChildren`；`createdAt`→id 排序；provider 未挂载不影响列表；压缩与未压缩孪生一致；预中止、持久化列表与冷读取消三例归一 `CANCELLED`；空列表与稳定错误码。敌意 unit 双路探针（`apply` 惰性置毒、`view` 引爆）证明任一注册 unit 在该 child 日志上的 fold/schema 抛错，在 live 与 cold 两条取值路径上都收纳为该 child 的 `corrupt` 行，sibling 与列表本身不受影响。第二级例：own-seq 身份直用零 `inspect`、fork 种子祖先身份（seq 落在 seed 区间）被门拒绝落底、行内无身份（null 哨兵或 key 缺席）落底、cache 服务缺席落底、缓存行中毒静默落底重折；冷路径 lifecycle 篡改按见证七字段逐一（`it.each`）降级为 `corrupt`。`tool-subagent-control` 的 list-agents 测试随加载要求收窄更新；`optional-session-query.spec.ts` 随依赖消失删除；既有无密钥快照（`subagent-list-agents` 等）零变化，钉住健康路径的 wire 与 model-visible 面不变；新增无密钥快照 `subagent-diagnostic`（examples/headless-agent）钉住四态映射的诊断分类——descriptor-less 定局残骸成 `corrupt` 行等模型可见变化。
+`packages/subagent/subagent/tests/list-children.spec.ts` 重写为本约定：无 persistence、query 服务与继续运行时的 live-only 列表；registry 缺席时零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`；live child 全程零 `inspect`、cold child 每次列表恰一次；多描述符 last-wins 取末者；损坏载荷与未知版本折为 `corrupt`；冷读失败映射 `unavailable` 且下次列表重试；fork seed 里的祖先描述符按该身份成行（偏差一钉住）；普通 fork 与无 subagent origin 的后代不入列也不计入 `hasChildren`；`createdAt`→id 排序；provider 未挂载不影响列表；压缩与未压缩孪生一致；预中止、持久化列表与冷读取消三例归一 `CANCELLED`；空列表与稳定错误码。敌意 unit 双路探针（`apply` 惰性置毒、`view` 引爆）证明任一注册 unit 在该 child 日志上的 fold/schema 抛错，在 live 与 cold 两条取值路径上都收纳为该 child 的 `corrupt` 行，sibling 与列表本身不受影响。第二级例：own-seq 身份直用零 `inspect`、fork 种子祖先身份（seq 落在 seed 区间）被门拒绝落底、行内无身份（null 哨兵或 key 缺席）落底、cache 服务缺席落底、缓存行中毒静默落底重折；冷路径 lifecycle 篡改按见证七字段逐一（`it.each`）降级为 `corrupt`。`tool-subagent-control` 的 list-agents 测试随加载要求收窄更新；`optional-session-query.spec.ts` 随依赖消失删除；既有无密钥快照（`subagent-list-agents` 等）零变化，钉住健康路径的 wire 与 model-visible 面不变；新增无密钥快照 `subagent-diagnostic`（examples/headless-agent）钉住四态映射的诊断分类——descriptor-less 定局残骸成 `corrupt` 行等模型可见变化。
 
 ## 后果
 
@@ -179,6 +179,6 @@ export type SubagentListEntry =
 ## 相关
 
 - [durable-subagent-catalog 与 list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)——被本记录部分取代：描述符仍是 mode/label 的持久权威与折叠输入，列表的枚举与取值改为自管合并加投影阶梯。
-- [session projections 与命令生命周期日志](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)——registry 契约的权威；本记录为其新增 `subagent` 身份 unit，并成为 snapshot/restore 两处既有读法的消费实例。
+- [session projections 与命令生命周期日志](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)——registry 约定的权威；本记录为其新增 `subagent` 身份 unit，并成为 snapshot/restore 两处既有读法的消费实例。
 - [web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)——`SessionHeader.origin` 的出处（#1569），身份判定去日志化的前半步；其 history 冷读（inspect 前缀加 registry 折叠）是本记录取值阶梯的同款先例。
 - [发布前可复用的 Session 准备阶段](2026-08-05-session-preparation.md)——`inspect()` 冷读与 LRU 复用；cold child 整读的成本模型建立其上。
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
index 20d21565b5..087513c174 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md
 2026-08-06-web-markdown-incremental-ast-renderer.md: 3599bfcc78dc4eefe5e82f461a469bdba15f3aae
-2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 2e00977da58ef29a77c45abcecf0f3bb62737929
+2026-08-06-web-markdown-incremental-ast-renderer.zh.md: c3a1134a478ee4c67a581fce63f20bc6ea1d6c33
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
index 2e00977da5..c3a1134a47 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 - **语法**([parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts)):`parseGfm`(流式臂与 `extractMarkdownPlainText`)和 `parseGfmWithMath`(定稿臂)以被替换的 remark 插件所包装的同一组 micromark 扩展调用 `mdast-util-from-markdown`,因此各处块边界完全一致。`mathCompatibility`(原 `remarkMathCompatibility`)现在直接导出其 micromark 扩展。
 - **增量解析**([incremental.ts](../../../../packages/client/ui-primitives/src/markdown/incremental.ts)):CommonMark 块解析按行推进,追加文本只会重塑解析前沿。`IncrementalMarkdownParser` 保留末尾两个块不稳定(最后一块是前沿;倒数第二块是安全裕量),冻结其前的所有块,只从最后一个冻结块的 `position.end.offset` 起重新解析源尾部——用的是解析器自己的偏移量,没有任何自制源扫描。每个源区间在整个流中解析 O(1) 次而非每 chunk 一次;单个巨型块(未闭合围栏)退化为旧的全量重解析成本,不会更差。非追加输入在递增的 generation 下重置状态。
-- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性契约范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
+- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性约定范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
 
 DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
 
@@ -30,4 +30,4 @@ DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react
 
 ## Consequences
 
-流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 契约对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
+流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 约定对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index 05c9a1fdd2..df37c8aa83 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
 2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
-2026-08-08-bounded-session-persistence-write-batching.zh.md: 4aafdd652aad87cfe74a449428cdbbf13312d260
+2026-08-08-bounded-session-persistence-write-batching.zh.md: fe1227f7706ba67a12bd7f19db5c0c57cfcfca4f
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index 4aafdd652a..fe1227f770 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -38,7 +38,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 **不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
 
-**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序契约。
+**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
 
 **按最新事件重置防抖窗口。** 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
 
@@ -46,13 +46,13 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 ## 验证
 
-控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化契约。
+控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化约定。
 
 ## 后果
 
 高频事件突发通常会减少持久化追加操作，同时保持逻辑事件数量完全不变。减少幅度取决于事件到达速率和后端延迟：位于同一 200 ms 窗口内的突发事件会成为一个批次，而强制 flush 与稀疏事件仍可能产生小批次。
 
-本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放契约，而不是再引入一条隐式计时器规则。
+本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放约定，而不是再引入一条隐式计时器规则。
 
 接纳后的事件在配置窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。部署可以选择较小的值以缩短普通丢失窗口，也可以选择较大的值以加强批处理。显式持久性边界保持不变，并会绕过等待。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index e1beb13c2c..81e53d0e26 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
 2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
-2026-08-08-client-tool-presentation-ownership.zh.md: 11a42ad69e4374afa6dccd3af74b8bd1b5e5c6f1
+2026-08-08-client-tool-presentation-ownership.zh.md: 010907144dea256fa97cc6bd49bbcf493ad64c78
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 11a42ad69e..010907144d 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
 
-这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排契约。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排约定。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
 
 ## Decision
 
@@ -60,13 +60,13 @@ Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sess
 | 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
 | details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
 
-## Slot 与 owner 契约
+## Slot 与 owner 约定
 
 slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
 
 整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
 
-席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 契约：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
+席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 约定：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
 
 业务插件遵循同一个注册形态：
 
@@ -86,7 +86,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Verification
 
-测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主契约；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主约定；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
index 6214a34d9c..a46aade24d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
 2026-07-19-windows-atomic-write-dacl-preservation.md: be9f82174300a7d605c6a6e63878728f08cb37be
-2026-07-19-windows-atomic-write-dacl-preservation.zh.md: d31b52b0a99240a1e4449427438e1e187b1b98da
+2026-07-19-windows-atomic-write-dacl-preservation.zh.md: ed52773b0314e06ecdc470f9d569685c47a7aec3
diff --git a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
index d31b52b0a9..ed52773b03 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定契约。新的 Windows 文件没有既有描述符需要保留，因此仍继承目标目录的 DACL；其暂存目录也因此位于目标文件旁。POSIX 继续使用仅所有者可访问的暂存 mode，并保留现有目标文件的 mode。
+`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定约定。新的 Windows 文件没有既有描述符需要保留，因此仍继承目标目录的 DACL；其暂存目录也因此位于目标文件旁。POSIX 继续使用仅所有者可访问的暂存 mode，并保留现有目标文件的 mode。
 
-Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。mode 位断言仍仅适用于 POSIX；新文件的 DACL 继承由操作系统契约规定，不应通过特定机器的账户允许列表来断言。
+Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。mode 位断言仍仅适用于 POSIX；新文件的 DACL 继承由操作系统约定规定，不应通过特定机器的账户允许列表来断言。
 
 ## 备选方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
index 05d9cfd033..032ba43584 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md
 2026-07-21-semantic-session-checkpoints.md: 697d878dccbfab1ded9f73e134d594ba6f0665e1
-2026-07-21-semantic-session-checkpoints.zh.md: e4d432cfa4655fcf6b010ab944dc12095eca009c
+2026-07-21-semantic-session-checkpoints.zh.md: c72f2bbad33967f54013f05568b9d1082d549357
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
index e4d432cfa4..c72f2bbad3 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
@@ -26,4 +26,4 @@ ACP（Agent Client Protocol）应用在一个有序 Cordis effect 中统一持
 
 ## 后果
 
-发生硬崩溃时，崩溃恢复会在最近的语义边界保留完整的模型请求、持久化的工具意图与完整且已结束的步骤，但允许上一个边界之后的部分流式分片仍可能丢失。默认的 CLI（命令行界面）、TUI、ACP、Python SDK 运行时、headless 持久化测试与 JSON-RPC 组合都会在持久化后端旁加载该策略。单元测试覆盖顺序、检查点期间的取消、失败关闭行为、嵌套分发、dispose（资源释放）与 Loader 形状，以及最终检查点的顺序与故障隔离；一个被 `SIGKILL` 终止的真实子进程通过 JSONL 证明系统可以恢复请求与工具意图，共享持久化契约则证明各后端都支持这两种恢复分类。崩溃 harness 会等待预期的标记内容，而不是仅等待路径存在，因此文件在写入前因打开而可见时，不会导致该 harness 提前终止子进程。无密钥 ACP 与 SDK 快照证明重试风险指引会进入恢复后的历史记录与下一个模型轮次，取消流程正常收尾时系统会持久化由循环实际生成的闭合边界，且 SDK 关闭流程会观察到已完整持久化的轮次。
+发生硬崩溃时，崩溃恢复会在最近的语义边界保留完整的模型请求、持久化的工具意图与完整且已结束的步骤，但允许上一个边界之后的部分流式分片仍可能丢失。默认的 CLI（命令行界面）、TUI、ACP、Python SDK 运行时、headless 持久化测试与 JSON-RPC 组合都会在持久化后端旁加载该策略。单元测试覆盖顺序、检查点期间的取消、失败关闭行为、嵌套分发、dispose（资源释放）与 Loader 形状，以及最终检查点的顺序与故障隔离；一个被 `SIGKILL` 终止的真实子进程通过 JSONL 证明系统可以恢复请求与工具意图，共享持久化约定则证明各后端都支持这两种恢复分类。崩溃 harness 会等待预期的标记内容，而不是仅等待路径存在，因此文件在写入前因打开而可见时，不会导致该 harness 提前终止子进程。无密钥 ACP 与 SDK 快照证明重试风险指引会进入恢复后的历史记录与下一个模型轮次，取消流程正常收尾时系统会持久化由循环实际生成的闭合边界，且 SDK 关闭流程会观察到已完整持久化的轮次。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
index 6a898fa0a4..3e97fb3f06 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md
 2026-07-27-glob-sampling.md: 67912cf290b127a96819d57f30387197af68323d
-2026-07-27-glob-sampling.zh.md: e339a5f87b483849df60feb726b061fe85074300
+2026-07-27-glob-sampling.zh.md: b8d7bbe1bc70e94cc4239867244be554eaf33e63
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
index e339a5f87b..b8d7bbe1bc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
@@ -22,17 +22,17 @@ Status: implemented
 
 **只保留按修改时间排序的前部。** 测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
 
-**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式契约，因此每个组合都必须选择一种，配置错误则在加载时失败。
+**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式约定，因此每个组合都必须选择一种，配置错误则在加载时失败。
 
 **对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
 
-**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先契约，也没有让受限页面更具代表性。
+**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先约定，也没有让受限页面更具代表性。
 
-**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序契约。现有上限是可以清楚解释的切换点。
+**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序约定。现有上限是可以清楚解释的切换点。
 
 **在顶层以下递归平衡。** 暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。
 
-**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照契约，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
+**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照约定，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
 
 **拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。** 否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
index 0820c01b7f..d17de641b9 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
 2026-07-27-stable-snapshot-refresh-volatiles.md: c3eeeca01a7820b5f410bd895de998e944e58eb2
-2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 388b67c67052074fa7423eae294e00b4122b2fe8
+2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 79a2758e7a7353c983f4e8a9d2531830dec311e4
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
index 388b67c670..79a2758e7a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别名、spill locator、嵌入的事件时间和省略字节数，但刷新写回会持久化本次生成的原始值。因此，即使比较契约将两份日志视为相等，一次行为未发生变化的刷新仍会用新的随机值或宿主特有的路径写法改写 fixture（测试前置数据）。
+ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别名、spill locator、嵌入的事件时间和省略字节数，但刷新写回会持久化本次生成的原始值。因此，即使比较约定将两份日志视为相等，一次行为未发生变化的刷新仍会用新的随机值或宿主特有的路径写法改写 fixture（测试前置数据）。
 
 消息身份所需的结构前提比记录对齐更弱：无关的日志事件可能破坏记录对齐，但继承而来的消息去除身份后的值在父级和子级日志之间仍保持不变。录制模式在替换现有 fixture 时也会从新生成的消息 UUID 开始。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
index 8c8b97c103..616caa6f68 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
 2026-07-28-load-pre-identity-session-messages.md: 2901527658421b37576bdf5b49e66829104a3b41
-2026-07-28-load-pre-identity-session-messages.zh.md: 210064f6e7c1ea239da89c4542346e164c48e274
+2026-07-28-load-pre-identity-session-messages.zh.md: bf6e58d8a895f41012449a1212533902e1211e99
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
index 210064f6e7..bf6e58d8a8 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 **按照预发布兼容性立场拒绝这些日志。** 这是处理其他 v0 形状变动的默认方式，但即使每个旧字段都能明确映射到当前消息表示，它仍会导致真实的第一方会话无法恢复。
 
-**就地重写完整的存储日志。** 这会使产物规范化，但违反仅追加存储契约，还需要为 JSONL 和 SQLite 分别实现原子替换机制，并将一次读取兼容性修复扩大为迁移系统。
+**就地重写完整的存储日志。** 这会使产物规范化，但违反仅追加存储约定，还需要为 JSONL 和 SQLite 分别实现原子替换机制，并将一次读取兼容性修复扩大为迁移系统。
 
 **每次加载时随机生成 id。** 这些消息会满足类型形状，却无法在检查、恢复、重启以及新旧形状混合追加之间保持稳定标识。
 
@@ -30,9 +30,9 @@ Status: implemented
 
 消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
 
-这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器契约会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
+这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器约定会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
 
 ## 相关
 
-- [将每条消息创建为带标识的不可变值](../architecture/2026-07-28-identified-immutable-message-values.md)：该记录负责当前的消息标识与不可变性契约。
+- [将每条消息创建为带标识的不可变值](../architecture/2026-07-28-identified-immutable-message-values.md)：该记录负责当前的消息标识与不可变性约定。
 - [会话持久化作为抽象服务](../architecture/2026-06-14-session-persistence.md)：该记录负责仅追加后端与恢复边界。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
index 7950dc88f3..082158c75c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
 2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 51d668f584ee254183d5d1cf709140df2556e8d0
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 1cf505e96122a66705fe42fc79757ac390ebf0ef
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
index 51d668f584..1cf505e961 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
@@ -20,9 +20,9 @@ Status: implemented
 
 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。
 
-两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
+两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定约定，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
 
-`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。
+`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
 
 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。
 
@@ -42,7 +42,7 @@ Status: implemented
 
 **把这两个属性绑定在 `html` 上。** 这是文档级皮肤最自然的落点，而它的失败是可测量的：规则挂在 `html` 上时，chromium 中滚动容器计算出的 `scrollbar-color` 为 `auto`，因为别名 token 在那个作用域内不存在。
 
-**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定契约——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
+**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定约定——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
 
 **不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 这正是本次变更最初提交的形态，被评审发现。在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
 
@@ -57,7 +57,7 @@ Status: implemented
 - 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。侧边栏内的滚动区域经由同一组间接变量，只在指针到达时才绘制滑块。
 - 两种渲染分别指定，因此改动滑块的几何或 hover 行为需要改两处：一处在 `scrollbar-width`／`scrollbar-color`，一处在伪元素。让两者都经由这组间接变量，把这份重复限制在 Firefox 与 WebKit 不共用的那些属性上。
 - hover token（`--dsw-alias-scrollbar-hover-l1`／`-l2`）只在伪元素路径上渲染。Firefox 通过 `scrollbar-color` 只表述一个滑块颜色，其 hover 表现由引擎自行推导，因此对 hover 颜色的设计改动在 Chromium 与 Safari 上可见，在 Firefox 上不可见。这是 `scrollbar-color` 本身的限制，不是这张样式表的限制。
-- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定契约。
+- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定约定。
 - 工作区列表在任何列表长度下都永久少了预留空位那一条宽度。这正是该修复换来的代价：以稳定的行几何，换掉只在列表较短时才可读的时间戳。
 - 调色板中没有轨道 token，因此日后若设计需要不透明轨道，要新增一个别名 token，而不是在这张样式表里写字面颜色。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
index 967a0ebcf4..1868a4ba02 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
 2026-07-28-web-agent-runtime-context.md: 6c2bb8faf0db56d2a29b47726ab295c3501cce2d
-2026-07-28-web-agent-runtime-context.zh.md: 09cbbdeabc244c265381b1ad67c3629b4c0763f5
+2026-07-28-web-agent-runtime-context.zh.md: ced6e767fd7463edae43b67025f35f77a631f150
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
index 09cbbdeabc..ced6e767fd 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
@@ -20,13 +20,13 @@ Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为
 
 ## 考虑过的替代方案
 
-**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息契约中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
+**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息约定中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
 
 **要求会话 Workspace 必须是 harness checkout。** Workspace cwd 是用户任务的目标，可以合理地指向空项目或其他仓库。将其与应用源码位置混为一谈会破坏这一边界，并且仍无法消除已安装版本或外部启动会话中的歧义。
 
 **把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
 
-**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用契约，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
+**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用约定，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
index 0e8b50db1a..c119ecf984 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
 2026-07-28-web-gui-feedback-loop.md: aa488e1df087722c072d98c67d47cdf63a42f6b8
-2026-07-28-web-gui-feedback-loop.zh.md: d9de988e5a2cc57794ff628b65eb050dee610747
+2026-07-28-web-gui-feedback-loop.zh.md: 9b6954092b737920ed18bc412037e917512e40dc
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
index d9de988e5a..9b6954092b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
@@ -14,15 +14,15 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
 
-按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
+按模式区分的提示词让 agent 而非用户负责隐藏的启动约定。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
 
 `apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。
 
-静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
+静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务约定负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
 
 ## 验证
 
-无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发契约。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
+无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发约定。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
 
 ## 考虑过的替代方案
 
@@ -36,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 影响
 
-常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
+常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式约定会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index cbc9924c07..69359852c2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
 2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: 909f0756dd29c9deddb840a188eb19a773f92d29
+2026-07-29-human-transcript-append-origin.zh.md: 030be076bec9c64ffc97957bbc0fc2b6084d2030
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index 909f0756dd..030be076be 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
 
-检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+检查点通过压缩接缝自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
 `session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
 
@@ -30,7 +30,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的契约，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
 
 **继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
index f314df3e08..96491ff288 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
 2026-07-29-web-details-session-lifecycle.md: 41b89fc059a02e56f53b27e5a5b48fb9488b93d7
-2026-07-29-web-details-session-lifecycle.zh.md: 82fb5e0c2608cccbb786a21971a74958417b4f10
+2026-07-29-web-details-session-lifecycle.zh.md: b6d7ecdf19382b4742dad6e032be930ae10c5f1e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
index 82fb5e0c26..b6d7ecdf19 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 **在 New Session 点击处理器中关闭详情栏。** 之所以否决：未选中表面没有会话作用域的详情，不得修改几何信息。详情栏是否关闭，应由随后对两个已定义会话 owner 的比较决定。
 
-**按会话持久化面板几何信息。** 之所以否决：产品契约需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
+**按会话持久化面板几何信息。** 之所以否决：产品约定需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
 
 **在会话基线就绪后保留持久化布局。** 之所以否决：这会仅为验证陈旧的查看状态，在呈现组件中重复实现启动生命周期。瞬时默认值无需就绪标志即可使重新加载具有确定性。
 
@@ -26,4 +26,4 @@ Status: implemented
 
 ## 后果
 
-详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用契约默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
+详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用约定默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
index fa83836e46..3393051e53 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.md
 2026-07-30-composer-context-stack-order.md: 150225ce27fa8459703170622cef754b7694e2fc
-2026-07-30-composer-context-stack-order.zh.md: f13ffc3c1136707a86ba5636a5b69304a132df01
+2026-07-30-composer-context-stack-order.zh.md: 12704a76db35c32590f75ecebcfd99116422afe6
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
index f13ffc3c11..12704a76db 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
@@ -10,11 +10,11 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
 
 ## 决策
 
-[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈契约：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
+[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈约定：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
 
 `ConversationRoot` 负责独立上下文卡片之间的 6px 间距。Goal 是一张独立的 752×36px 卡片，折叠后的 Todo 是一张独立的 752×44px 卡片。Queue 是末端 dock 条目：其 776px 包装层包含相同的 752px 面板列，并减去共享间距与具名的 5px 布局重叠量，因此后渲染的 composer 卡片只覆盖 Queue 边缘。空条目渲染为 null，不占用间距。
 
-顺序与重叠是两项独立契约。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
+顺序与重叠是两项独立约定。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index cede7ea5d9..17c4315966 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
 2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
-2026-07-30-web-transcript-log-ordered-projection.zh.md: acd198b6d3f3c5d57e233e09ee66f5d151e4f8f1
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 024d7dba7db7f06a684f5656abf7421e65cd4536
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index acd198b6d3..024d7dba7d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -53,15 +53,15 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 **一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只花一个文件，就精确消除了这一风险。
 
-**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议契约变更——为一个纯谓词付出的代价不成比例。
+**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议约定变更——为一个纯谓词付出的代价不成比例。
 
 **把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的记录之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。
 
-**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假契约。
+**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假约定。
 
 **把最近的 `/compact` 行与下一个检查点配对。** 已拒绝：两者之间可能落入上下文注入，并发或格式异常的生命周期记录也必须降级而不误取其他检查点。命令结果则指明权威摘要事件；引用存在歧义时不配对任何内容。
 
-**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据契约。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
+**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据约定。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
 
 ## Consequences
 
@@ -69,7 +69,7 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 `ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的“无单元格”分支，使标记不贡献单元格但仍推进耗时游标。
 
-性能契约未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
+性能约定未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
 
 Web e2e 场景现在围绕它录制的那一轮上的压缩事务播种一次真实的手动命令生命周期，因此 aria 基准经真实宿主与真实浏览器钉住完整行为：录制的提问与完整工具输出仍在屏幕上，其后恰好一条 `compact` 行报告规模，展开后会显示确切摘要。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出手动压缩。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
index 7d68e52c82..4701560508 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.md
 2026-07-31-english-compaction-checkpoints.md: dc95ed187a6ba5b86800f06ebefb2776995f9421
-2026-07-31-english-compaction-checkpoints.zh.md: 7cd4179430ed775f3807af5a02e81838e495c81e
+2026-07-31-english-compaction-checkpoints.zh.md: 54247dcfeffc8a0d94fd64b0bbd5cb2dee9b669f
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
index 7cd4179430..54247dcfef 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - **让回放的对话决定检查点语言**——不采纳：检查点是持久的提示词前缀，保留短暂的对话文体可能在后续压缩中放大这种影响。
 - **约束对话模型的语言**——不采纳：该策略针对内部检查点，而不是用户可见的对话；对整个对话施加规则会不必要地改变正常交互。
 - **要求仅输出 ASCII**——不采纳：ASCII 是字符集约束，而非工程文体约束，并会不必要地扭曲合法的字面量和技术材料。
-- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出契约中说明该要求更简洁，也直接将其与所请求的检查点绑定。
+- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出约定中说明该要求更简洁，也直接将其与所请求的检查点绑定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index fda3830670..f090dceaaf 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
 2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: 64459614dc3376a1c773de72cd36aa455894a03c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 3e4d2ce40c2196919aace410d86a2ea26b6001f8
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index 64459614dc..3e4d2ce40c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -52,7 +52,7 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 ## Testing
 
-`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 约定：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
 
 这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
index c4a5595fea..9ca3df22a0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.md
 2026-07-31-fork-anchor-floors-to-event-seq.md: 2cc8d66942442aca69c930be880cc41d56bced13
-2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 9f443f3d5165c01c6585d33bd6a37e90e9b3bf95
+2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 75fc1885f344e88c9ded575bc4aea58562e55673
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
index 9f443f3d51..75fc1885f3 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
@@ -18,11 +18,11 @@ host 的切分规则从来不是障碍。被中止的轮次会记录一条 reaso
 
 向下取整落在锚点自身所在的轮次内，不会回退：每一轮都以 `turn/start` 开头，所以 `turnEnd.seq - 1` 不可能是上一轮的 `turn/end`。host 随后按「首个位于锚点或其之后的 `turn/end`」收口，命中的正是读者点击的那一轮，与消息级 fork 按钮在已完成轮次上一贯承诺的整轮语义一致。
 
-apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
+apiproxy 的 fork 用例固定了 host 这一侧的约定：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
 
 ## 备选方案
 
-**让 wire 接受分数 `atSeq`。** 否决：host 契约要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
+**让 wire 接受分数 `atSeq`。** 否决：host 约定要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
 
 **在已中断的消息上隐藏 fork 按钮。** 否决：从读者主动叫停的那一轮分叉，恰恰是最需要 fork 的场景之一，而 host 侧这个能力一直是好的。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
index 3df507fc7c..7832e30b52 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
 2026-07-31-resume-selector-batch-projection.md: 39146527f13b20813bb6f5d5f1349ecab5724662
-2026-07-31-resume-selector-batch-projection.zh.md: 3f824a3063849306e5c1c21699f6a19eefcfefe5
+2026-07-31-resume-selector-batch-projection.zh.md: 19bea7211cc61fa7db80370ee3092e5c88bf931b
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
index 3f824a3063..19bea7211c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
@@ -26,9 +26,9 @@ session-query 与 session-persistence 的任何表面都未改变。随附的 TU
 
 **只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
 
-**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化契约、两个后端和查询记录形状，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费者再引入。
+**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化约定、两个后端和查询记录形状，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费者再引入。
 
-**专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效契约（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
+**专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效约定（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
index c78049cc8d..a9eade53c1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md
 2026-07-31-web-stop-preserves-queue.md: b8bba45009c126495a8b03ee36d6eb2cccac9a93
-2026-07-31-web-stop-preserves-queue.zh.md: 0e1fffae8819bea81b91fae10c76dbadc78474fe
+2026-07-31-web-stop-preserves-queue.zh.md: af9c114fd06452e58322f2554a0f2ccd861c81c9
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
index 0e1fffae88..af9c114fd0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
@@ -16,7 +16,7 @@ Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({
 
 AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。
 
-该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
+该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认约定仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
index 39bf79e628..090d230891 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
 2026-08-01-ask-user-delegated-caller-guard.md: 0350a7383f7ace6ecd742c98db18f8b977720cf9
-2026-08-01-ask-user-delegated-caller-guard.zh.md: 9c19722feb4586e07845fd20279574301267542d
+2026-08-01-ask-user-delegated-caller-guard.zh.md: afabe4fb742dac2696b88bf64515aba68424b4de
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
index 9c19722feb..afabe4fb74 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 以运行时所有权为权限依据。携带谱系的会话在无所有者的情况下恢复时就是运行时根，可以提问；存活子级即使持久化 `delegationDepth` 为零，仍无资格提问。不带 agent 的程序化调用继续沿用现有提供方路径。
 
-共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托契约本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
+共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托约定本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
 
 该安全边界与浏览器的 composer 选举相互独立。提议的[语义 composer 阶段](../../proposed/architecture/2026-08-08-semantic-composer-chain-phases.md)解决已有待处理交互与只读 subagent 界面的排序方式；它不会削弱此运行时守卫。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
index c8784f5991..c37b234616 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.md
 2026-08-02-goal-round-wrapup-message.md: c6bc3d5912b0789efde55880c2be892e98e34a5b
-2026-08-02-goal-round-wrapup-message.zh.md: 0a504b4dcc61feb932775b3d9ffd8424f3b0597d
+2026-08-02-goal-round-wrapup-message.zh.md: f223516e1255f2dafe026a48d1faafa838af6cb8
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
index 0a504b4dcc..f223516e12 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
@@ -18,13 +18,13 @@ Goal Round 的 `complete` 或 `blocked` 成功不再调用 `concludeTurn()`。
 
 ## 验证
 
-`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符契约：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一轮 → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同轮内的收尾 assistant 消息与 `completed` 轮次结束。
+`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符约定：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一轮 → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同轮内的收尾 assistant 消息与 `completed` 轮次结束。
 
 ## 曾考虑的替代方案
 
 - **在 `update_goal` 的 UI 卡片上展示完成文本** — 拒绝：`complete` 如今不携带任何自由文本；新增 `summary` 参数会让面向用户的汇报走工具参数通道，而且依然砍掉了模型在结果之后的自然发言。
 - **保留 `concludeTurn()` 并新增“再多一步纯文本”的 loop 原语** — 拒绝：为常规停止路径已经能提供的行为（只要没有结果终结轮次）增加新的 `agent-loop` 机制。
-- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧契约和工具的可回放值搅在一起。
+- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧约定和工具的可回放值搅在一起。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
index eeac8a251c..c68279a2b4 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.md
 2026-08-02-todo-first-composer-context-order.md: 26962426c763c6911fc61acab09cdb96725922b1
-2026-08-02-todo-first-composer-context-order.zh.md: a81401ffeb8df5855b584a5727e24067d9fb1e70
+2026-08-02-todo-first-composer-context-order.zh.md: 2bd09a95832b22afc919a6f2d18bef94d4209c40
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
index a81401ffeb..2bd09a9583 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
@@ -14,7 +14,7 @@ composer 上下文堆栈将 Goal 渲染在 Todo 之前，但 Harness 设计稿
 
 Todo、Goal 与可见的 Queue 面板共用 800px composer 宽度上限内的 752px 卡片列。Queue 保留 776px 包装层，并在两侧各留 12px 透明内缩，因为该包装层负责与 composer 重叠。Todo 是独立卡片，而非包装层，因此其响应式宽度和最大宽度都会直接扣除两层内缩。Goal 使用相同的响应式卡片列，并将内层横条的宽度上限设为 752px，从而在低于桌面宽度上限时也保持边缘对齐。
 
-[composer 堆栈契约](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
+[composer 堆栈约定](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 36c7895ac2..524915cee7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
 2026-08-03-cli-signal-shutdown-escalation.md: c8aac6e2be927bd1f4a445c00e0aaa870b10a465
-2026-08-03-cli-signal-shutdown-escalation.zh.md: 66fe7062ea35a6cc91dbdd6644088cb086a15439
+2026-08-03-cli-signal-shutdown-escalation.zh.md: bfe0b9c28e10b055888ba4850d1a1feacc5f8390
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index 66fe7062ea..bfe0b9c28e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -39,7 +39,7 @@ headless 对完成的轮次仍以 0 退出，对其他轮次结束原因或 API
 
 ## 后果
 
-健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭契约已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
+健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭约定已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
 
 该控制器属于启动器基础设施，而不是 Cordis 插件：它不会声称 dispose 已经完成，也不会削弱普通 disposer 必须达到完全停稳状态的生命周期规则。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 51fbed7ba9..1ca6de64cd 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
 2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 5f8d50c4c0103eb2209eafb89cf34233c4c1bc35
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: a023420182971a62f125808f777f877bafe3e9e2
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index 5f8d50c4c0..a023420182 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -38,4 +38,4 @@
 
 ## 测试
 
-`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端约定：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
index 02ea7ca431..8aab23d8a2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
 2026-08-04-load-pre-react-loop-sessions.md: b7dcad1ff7fe0aa8239ac03f52b50dfa55417515
-2026-08-04-load-pre-react-loop-sessions.zh.md: 14c6dcc7b4da016ebef424a66fae0b96fb469cd4
+2026-08-04-load-pre-react-loop-sessions.zh.md: 9dc8666d301b3baf454079498bf3ad7e1f510c96
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
index 14c6dcc7b4..9dc8666d30 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
@@ -26,11 +26,11 @@ react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持
 
 **将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会虚构来源。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
 
-**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加契约，并要求为读取兼容边界建立后端专用的原子迁移机制。
+**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立后端专用的原子迁移机制。
 
 ## 后果
 
-以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器契约覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
+以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器约定覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
 
 此例外支持基线格式，不支持重构开发期间产生的中间格式。具体而言，它没有为更早的实验性 `agent/inbox/spliced` 载荷定义迁移。通过确切形状识别，当前格式外观相似但结构错误的记录仍会走拒绝路径，不会被猜测性地转换为有效记录。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
index a08d6323dd..874c0c0d34 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
 2026-08-06-onboarding-step-owned-takeover-chrome.md: 4b3bbbc03c4494359297ae6e54bcc9a74c387e80
-2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 548285d285939325a26df3b8d70c43fe952813a9
+2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: ba4f503f7bc318fcb16f4413465a86609fa1bc61
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
index 548285d285..ba4f503f7b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
@@ -14,13 +14,13 @@
 
 接管界面框架属于步骤，不属于外壳。新增零 cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
 
-`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 契约现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
+`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 约定现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
 
 ## 曾考虑的替代方案
 
 **条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／销毁在两个包里都变成响应式接线。对本缺陷而言过重，否决。
 
-**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的契约变更。
+**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的约定变更。
 
 **在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法据步骤的 `null` 分支；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
 
@@ -28,8 +28,8 @@
 
 步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前是在不透明图层背后被置灰）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
 
-未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 契约的 JSDoc 已把包裹写为注册方的义务。
+未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 约定的 JSDoc 已把包裹写为注册方的义务。
 
 ## 测试
 
-`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳契约：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
+`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳约定：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
index de0b20d867..2d0579a4d1 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
 2026-08-06-provider-credential-lifecycle.md: c28788921e8f1b233b44e19b29ad4d4acaa25022
-2026-08-06-provider-credential-lifecycle.zh.md: 2ea3b21fb6ceb4fa38a0cad0daf47c3b6a98a664
+2026-08-06-provider-credential-lifecycle.zh.md: 2791baa7761b243cbdd34251d1dc11678b8a9a65
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
index 2ea3b21fb6..2791baa776 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
@@ -16,7 +16,7 @@ Models 编辑器横跨互相独立的 settings 与凭据 RPC 领域。之前它
 
 ## 曾考虑的替代方案
 
-**添加跨领域事务 RPC。**settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置契约。
+**添加跨领域事务 RPC。**settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置约定。
 
 **删除被移除 profile 所指定的每一个凭据引用。**自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
index 1c861833cf..2982e05c65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
 2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
-2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: ffb03fdb68c9cb040e311077dd698b310a033fdd
+2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: 7a1142cdd793cfce46bfd3908ab28345701aec7a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
index ffb03fdb68..7a1142cdd7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
@@ -12,13 +12,13 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 读者输入不再依据设备来识别。ChatView 维护一份 observed-top ledger（`observedTopRef`）：即最近一次由主线程交付、或由组件自身写入的 `scrollTop`，并在每一个程序化写入点（贴底跟随、打开时恢复、前置锚定、尺寸变化跟随以及滚动交付本身）同步记录。滚动事件到达时，偏离 `min(ledger, floor)` 超过半像素的位置即为读者输入；落在 ledger 上的位置（迟到的程序化交付），或恰好落在收缩后底部上的位置（内容收缩后的浏览器钳制），则维持当前的所有权状态。此后所有权只经由读者输入、按既有阈值规则变化：位置距底部在 `FOLLOW_THRESHOLD` 以内则重新贴底，超出则释放跟随并显示「回到底部」。滚轮监听器及其 epoch 簿记已删除；组件只监听 `scroll`，因此滚轮、触控、滚动条、键盘以及未来任何输入来源都由同一条规则覆盖。
 
-## 契约变更：收缩与重新增长被合并的钳制
+## 约定变更：收缩与重新增长被合并的钳制
 
-如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试契约已在同一变更中改写为只吸收纯收缩的保证。
+如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试约定已在同一变更中改写为只吸收纯收缩的保证。
 
 ## 测试
 
-`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 契约：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
+`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 约定：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
 
 该车道的 Chromium 无法合成任何非滚轮的设备滚动，这限定了 e2e 能真实驱动的范围：触控来源的 `Input.synthesizeScrollGesture` 与手工构造的 `Input.dispatchTouchEvent` 序列都能交付 DOM 事件，却从不移动滚动容器（无头模式与 Xvfb 下的有头模式皆然）；`default` 手势来源合成的是滚轮事件；合成器滚动条则完全无视合成的鼠标输入，且只有移除 `--hide-scrollbars` 后才能看到滚动条槽。键盘是唯一可用的非滚轮原语，因此由它承担真实输入流水线的证明；快滑场景则把触控的特征（组件从未写入过的逐帧衰减位移）直接回放进滚动容器。
 
@@ -34,4 +34,4 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 ## 后果
 
-每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的契约变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言契约的前提下，把快滑模拟替换为真实的触控划动。
+每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的约定变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言约定的前提下，把快滑模拟替换为真实的触控划动。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
index bb344c5afe..eb99fee949 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.md
 2026-08-06-token-surface-unpriced-replace-compatibility.md: 77b778fba695f560eb68af6da2f416e61ccff181
-2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: dd4c5883c4c6d37809c2f8100f266655d8ba600c
+2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: 0aff9db9b95e8670d85c8239dc2313b4e20f321c
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
index dd4c5883c4..0aff9db9b9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
@@ -8,19 +8,19 @@ Status: implemented
 
 `contextPressure` 与 `contextBreakdown` 两个投影只维护一份滚动累计的表层 token 总量，外加至多一条待结算的影子价格（shadow price）声明，因此其持久化检查点在会话整个生命周期内保持 O(1)。当前的替换生产方会紧贴在替换之前追加一条 `compact/summary` 或 `compact/prune` 计量事件；其 `shadowedTokenCount` 对被替换区间精确计价，`foldSurfaceProjection` 再把它换算成有符号增量。
 
-影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作契约违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
+影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作约定违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
 
 ## 决策
 
 到达时没有已就位声明的替换以价格中性的方式折叠：`foldSurfaceProjection` 返回 `deltaTokens: 0`，相当于把被替换区间计价为恰好等于其替换内容的成本，回放随即继续。因中间插入的事件而过期的声明也走同一条中性路径，因为折叠无法把它与从未计量过的日志区分开。
 
-已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格契约的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
+已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格约定的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
 
 两个投影共用同一个折叠，因此二者都不新增状态字段，也不提升 `stateVersion`。`surface-fold.ts` 与 `ctx.tokenMeter.measure()` 不受影响：它们持有逐节点的已计价表层，本来就不需要声明协议。
 
 ## 备选方案
 
-**维持抛出异常。**保住了严格的生产方契约，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
+**维持抛出异常。**保住了严格的生产方约定，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
 
 **在投影状态中持久化完整的已计价表层。**可以对任意被替换区间精确计价，但检查点会随每条模型可见消息各增加一个节点、无上限地增长，恰恰破坏了影子价格协议所要守住的 O(1) 约束（见[上下文仪表的 Agent Note](2026-08-05-context-meter-blind-to-compaction.md)）。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
index d31f344c27..e6758b23d2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
 2026-08-07-cancel-convergence-wake-latch.md: fe00c78bdfadac0cc6c9c173fd04256f77a22051
-2026-08-07-cancel-convergence-wake-latch.zh.md: f76ad360e2d8b70f76c6baf53e2fde963a80b6c4
+2026-08-07-cancel-convergence-wake-latch.zh.md: 736c5eb39809811363ed93529d90878ea9acdc89
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
index f76ad360e2..736c5eb398 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-`Agent.cancel(cause, { keepInbox: true })` 在触发 abort 信号后立即返回，但活动 driver 可能尚未收敛到 `idle`：LLM 流拆除、工具取消与 `turn/end` 落盘都会在 `abort()` 返回后异步展开。在该窗口内到达的唤醒 send 被放入 `next-turn`，而 `wakeDriver()` 对仍处于 `running` 的 phase 直接返回，退出的 driver 也从不重放这次唤醒——消息会一直停放到下一条唤醒 send 到达。被中止的 `runMaintenance` 活动周围也存在同样的唤醒丢失窗口。多个测试固化了停放行为（「等待下一次唤醒」）；该缺陷同时破坏了 `session.cancel` 与 `subagent.interrupt` 组合路径（issue #1838）。拥有取消与发送契约的既有决策是[显式轮次取消](../architecture/2026-07-16-explicit-turn-cancellation.md)与[统一发送](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)；生产环境中的 `keepInbox` 消费方是[Web 停止保留队列](2026-07-31-web-stop-preserves-queue.md)。
+`Agent.cancel(cause, { keepInbox: true })` 在触发 abort 信号后立即返回，但活动 driver 可能尚未收敛到 `idle`：LLM 流拆除、工具取消与 `turn/end` 落盘都会在 `abort()` 返回后异步展开。在该窗口内到达的唤醒 send 被放入 `next-turn`，而 `wakeDriver()` 对仍处于 `running` 的 phase 直接返回，退出的 driver 也从不重放这次唤醒——消息会一直停放到下一条唤醒 send 到达。被中止的 `runMaintenance` 活动周围也存在同样的唤醒丢失窗口。多个测试固化了停放行为（「等待下一次唤醒」）；该缺陷同时破坏了 `session.cancel` 与 `subagent.interrupt` 组合路径（issue #1838）。拥有取消与发送约定的既有决策是[显式轮次取消](../architecture/2026-07-16-explicit-turn-cancellation.md)与[统一发送](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)；生产环境中的 `keepInbox` 消费方是[Web 停止保留队列](2026-07-31-web-stop-preserves-queue.md)。
 
 ## 决策
 
-`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察契约：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
+`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
 
 `signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（验收条件 1）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
 
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
index 369f69973d..2d4b3c0ad0 100644
--- a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-14-acp-multi-session.md
 2026-06-14-acp-multi-session.md: 088fe984fbc94fe0d8654702d5fce9eb0581cd3b
-2026-06-14-acp-multi-session.zh.md: 083b160aa51e669b74931654cd08acaa3d2aa221
+2026-06-14-acp-multi-session.zh.md: ffa849d4baf742734df3ac4694cc9413d317ed1b
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
index 083b160aa5..ffa849d4ba 100644
--- a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-14-acp-multi-session.md) | 中文
 
-> 本 Agent Note 写于 ACP 还是编辑器桥接层的时期，动机来自 Zed 的多会话客户端模型。[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了编辑器接口；多路复用决策本身不变，本 Agent Note 现依照自动化契约陈述它。
+> 本 Agent Note 写于 ACP 还是编辑器桥接层的时期，动机来自 Zed 的多会话客户端模型。[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了编辑器接口；多路复用决策本身不变，本 Agent Note 现依照自动化约定陈述它。
 
 ## 问题
 
@@ -26,7 +26,7 @@ ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agen
 
 [ACP v1 明确允许一个连接上存在多个并发会话](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/get-started/architecture.mdx#L16-L24)，每个新会话都携带自己的主 `cwd`。本桥实现该会话级多路复用，其中包括[按会话 cwd 决策](../architecture/2026-07-02-fs-per-session-cwd.md)所记录的不同主工作区；它不会为每个会话创建一个 agent 子进程。
 
-一个会话内部的多根项目是另一项可选能力：ACP 把[有效根目录定义为主 `cwd` 加 `additionalDirectories`](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/session-setup.mdx#L313-L367)。自动化桥接层不公布任何多根能力，并拒绝非空的 `additionalDirectories`；如[包契约](../../../../packages/acp/acp/README.md#protocol-contract)所记录，每个全新会话恰好有一个工作区。
+一个会话内部的多根项目是另一项可选能力：ACP 把[有效根目录定义为主 `cwd` 加 `additionalDirectories`](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/session-setup.mdx#L313-L367)。自动化桥接层不公布任何多根能力，并拒绝非空的 `additionalDirectories`；如[包约定](../../../../packages/acp/acp/README.md#protocol-contract)所记录，每个全新会话恰好有一个工作区。
 
 [标准传输是每个 stdio 连接一个 agent 子进程](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/transports.mdx#L17-L42)；多个连接因此需要多个子进程或自定义传输，而本决策保证的是一个连接内部存在多个会话。在该连接内，`ctx.sandboxPolicy` 把每个会话的 `cwd` 解析为其自己的 `workspace-write` 根目录，因此共享的 bash 和文件系统服务可以服务并发项目而不授予跨项目写入。这不会添加 ACP `additionalDirectories`；它只是从已经支持的「每会话一个主根目录」路径中移除了进程级根目录限制。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 684b2510f0..97e5ee763f 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-15-code-mode.md
 2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: d6f0887f421296818b6bba7a26fc662c246cc28a
+2026-06-15-code-mode.zh.md: 87e39d7b68dd1dc2ebdee57f731be30d396a907b
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index d6f0887f42..87e39d7b68 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -42,7 +42,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调性守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
 
-1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
+1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生约定的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
 3. **完全停稳后结算。** 运行时结算后，桥 abort 未完成的工作并排空分发队列后再返回。成功时返回捕获的日志和完成值，将其作为规范输出；注册表再把该值渲染为持久化的 `tool/result.content`，供结果卡片直接读取。运行时失败变为 `CodeRunFailedError`；后端拒绝使用注册表的正常错误边界。两者都产生结构化的错误结果，且 `run_code` 结算后不允许子调用追加。
 
@@ -120,7 +120,7 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
-**`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
+**`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的约定线，错误路径是一个可工作的反馈循环，而非死胡同。
 
 **SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
 
@@ -128,6 +128,6 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 返回值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
 
-**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实契约。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实约定。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
 **预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）是抵御恶意程序的关键。两种情况均有单元测试（带 pending 诱饵分发的热循环会在耗尽 `computeMs` 预算时终止；等待慢速绑定的空闲程序则会持续运行至 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 27336b9c4b..586cab797e 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
 2026-06-17-filesystem-tool-schemas.md: 9941b3916b361a916c8148eb099eb8cfd46371c8
-2026-06-17-filesystem-tool-schemas.zh.md: 4de0fe000a5524a3c5e76c6fa67f8a8b7e37ac6d
+2026-06-17-filesystem-tool-schemas.zh.md: 8ba3c18629863ca9f04548d5993e9d200ecd4912
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
index 4de0fe000a..8ba3c18629 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -66,11 +66,11 @@ schema 不将 `expected_hash`、`expected_version` 或 `create_only` 作为面
 
 `edit` 要求同一执行上下文先前观测过该文件（任何窗口化的 read 都算——授权取决于观测到的版本是否仍为最新，而不要求查看全文），或该上下文先前对该文件执行过 write/edit。`dsh-fs-policy` 策略插件推导所有者，并将记录的版本作为陈旧版本防护提供；提供方的变更锁会强制执行该防护。
 
-首次实现拒绝 Codex 风格的 patch 语法和多模式 edit API。它使用一种严格的字面替换模式，使面向模型的契约保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
+首次实现拒绝 Codex 风格的 patch 语法和多模式 edit API。它使用一种严格的字面替换模式，使面向模型的约定保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
 
 ## 结果形状
 
-首次实现曾将 `ContentBlock[]` 格式化逻辑放在 `execute` 中。[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)如今将 `ctx.fs` 的结果事实保留为工具经校验的值，并通过 `output.render` 派生相同的模型文本；文件状态的记录/刷新仍归 `ctx.fs` 所有。
+首次实现曾将 `ContentBlock[]` 格式化逻辑放在 `execute` 中。[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)如今将 `ctx.fs` 的结果事实保留为工具经校验的值，并通过 `output.render` 派生相同的模型文本；文件状态的记录/刷新仍归 `ctx.fs` 所有。
 
 默认原生投影：
 
@@ -99,7 +99,7 @@ schema 测试固定每个工具的必填/可选参数集、空 `old_string` 拒
 
 ## 曾考虑的替代方案
 
-- **Codex 风格的 patch 语法或多模式 edit API**：否决。一种严格的字面替换模式使面向模型的契约保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
+- **Codex 风格的 patch 语法或多模式 edit API**：否决。一种严格的字面替换模式使面向模型的约定保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
 - **camelCase 参数名（OpenCode 风格）**：snake_case 与 Claude Code 及现有 harness 工具 schema 示例一致，且命名一旦发布即成为公开接口。
 - **面向模型的 `expected_hash` / `expected_version` / `create_only` 参数**：否决。陈旧检查由后端产生的版本和策略插件的观测状态驱动，从不依赖模型复制的脆弱令牌。
 
@@ -109,4 +109,4 @@ schema 测试固定每个工具的必填/可选参数集、空 `old_string` 拒
 
 **v1 中没有显式的面向模型的陈旧版本防护。** schema 不要求模型提供 expected hash/version。这是有意为之：陈旧检查来自后端产生的版本和 `dsh-fs-policy` 插件的观测状态，而非模型复制的脆弱令牌。文件系统安全失败通过 `dsh-fs` 拥有的结构化 `FsError` 代码浮现，而非模型提供的版本字段。
 
-**命名成为公开接口。** 一旦发布，将 `file_path` 改为 `filePath` 或 `old_string` 改为 `oldString` 会导致提示词、示例和下游客户端随之改动。本 Agent Note 预先选择 snake_case，并将其视为稳定的面向模型的契约。
+**命名成为公开接口。** 一旦发布，将 `file_path` 改为 `filePath` 或 `old_string` 改为 `oldString` 会导致提示词、示例和下游客户端随之改动。本 Agent Note 预先选择 snake_case，并将其视为稳定的面向模型的约定。
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 230bcb69f5..60a89e6fab 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
 2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
-2026-06-18-compaction-capability-seam.zh.md: 59eb899acae0352a019cfc5252365e0116f84597
+2026-06-18-compaction-capability-seam.zh.md: 297b9adda4f13f6fd4da9e73bf2bcf3d8d6ead0c
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 59eb899aca..297b9adda4 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 压缩作为能力 seam（抽象契约 + 基础后端）
+# Agent Note: 压缩作为能力 seam（抽象约定 + 基础后端）
 
 Status: implemented
 
@@ -16,22 +16,22 @@ Status: implemented
 
 ### 压缩是一个能力 seam，接口与实现分离
 
-遵循[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)，压缩以独立包发布，使契约、算法和（后续的）消费方 surface 各自独立演进：
+遵循[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)，压缩以独立包发布，使约定、算法和（后续的）消费方 surface 各自独立演进：
 
-1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件、手动失败分类体系以及规范的检查点消息来源。它将 `compactIfNeeded()`、`compactNow()` 和 `compactRegion()` 声明为**抽象方法**——契约说明压缩*做什么*，而非*怎么做*。
+1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件、手动失败分类体系以及规范的检查点消息来源。它将 `compactIfNeeded()`、`compactNow()` 和 `compactRegion()` 声明为**抽象方法**——约定说明压缩*做什么*，而非*怎么做*。
 2. **实现** — `@deepseek-ai/dsh-compact-basic`：具体的 `BasicCompactService`，消费 `ctx.tokenMeter`，并拥有尾→头保留遍历、通过 `ctx.llm.stream()` 生成摘要、surface 替换、锁、步骤前压力处理和规范的上下文溢出恢复。`summarize()` 是其唯一的子类钩子；计价与回放仍归 meter 所有。
 3. **无模型配套服务** — `@deepseek-ai/dsh-compact-tool-result-prune`：一个具体的可选服务，在后端选择摘要范围之前，重写当前过大的 `tool/result` 节点。它不是第二种压缩实现，也不实现 `CompactService`。
 4. **面向用户的消费方** — `@deepseek-ai/dsh-command-compact` 通过 `ctx.commands` 注册无参数 `/compact`，并调用后端无关的 `compactNow()` 操作。它是供用户直接控制的命令，不是面向模型的工具。
 
-### 契约依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离
+### 约定依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离
 
-能力 seam Agent Note 规定接口包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），契约就无法表达。
+能力 seam Agent Note 规定接口包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），约定就无法表达。
 
-这不是耦合异味，而是契约的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖契约真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
+这不是耦合异味，而是约定的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖约定真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
 
 ### 三个抽象操作，算法在后端
 
-早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
+早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
 `compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV Cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
@@ -110,7 +110,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 
 ## 曾考虑的替代方案
 
-- **完整算法作为接口的具体方法**——否决，因为它将契约重新耦合到一种保留策略。三个操作都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。
+- **完整算法作为接口的具体方法**——否决，因为它将约定重新耦合到一种保留策略。三个操作都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。
 - **在 `agent/request` 或压缩专属的 loop 回调上执行压缩**——否决，因为前者观察的是临时请求，后者会将通用生命周期耦合到压缩策略。对先前持久请求进行 pre-step 回放，再加上规范溢出恢复，即可覆盖成功和被拒绝的调用。
 - **`compact` 布尔值或无类型的请求元数据 map**——否决，因为多个辅助调用种类会变成互斥标志，而开放 map 会丢弃由编译器检查的词汇。一个类型化的 `purpose` 判别字段可以扩展其他调用种类，而无需再为 `GenerateOptions` 添加字段。
 - **单独的 `compact/error` 事件**——否决：`compact/end` 保留 `error?` 字段，与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件。
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index 9540bb6f0e..e55d06834c 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
 2026-06-22-acp-subagent-backend.md: c994ebfa69649bb9e79d3aa389a0e13c178131c7
-2026-06-22-acp-subagent-backend.zh.md: 62d631e95b5d1f299bed1fd00353b5ac9349b9a0
+2026-06-22-acp-subagent-backend.zh.md: 79be03dfc8310f6fc759d620c36d0d279c703073
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index 62d631e95b..79be03dfc8 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -30,7 +30,7 @@ subagent seam（[seam Agent Note](2026-06-21-subagent-capability-seam.md)）的
 
 ### StopReason 映射
 
-ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`max_tokens`→`max-tokens`、`refusal`→`refusal`、`cancelled`→`aborted`、`max_turn_requests`→`error`（无对等语义，任务未完成）、未知→`error`。spawn/传输/RPC 失败时，结果为 `error`（如果已请求取消则为 `aborted`）；按 seam 契约，`result` 在子 agent 级别失败时从不 reject。
+ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`max_tokens`→`max-tokens`、`refusal`→`refusal`、`cancelled`→`aborted`、`max_turn_requests`→`error`（无对等语义，任务未完成）、未知→`error`。spawn/传输/RPC 失败时，结果为 `error`（如果已请求取消则为 `aborted`）；按 seam 约定，`result` 在子 agent 级别失败时从不 reject。
 
 ### 安全：清洗子进程环境
 
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
index f17347689c..32c80847bb 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-24-workspace-context.md
 2026-06-24-workspace-context.md: 53a580aee50752b7c6daeff5caa42ba6409c8885
-2026-06-24-workspace-context.zh.md: 79e5b0014801878595d3a5d71b8c4b23c5aad996
+2026-06-24-workspace-context.zh.md: 39c3f52da10b7299301d10bd8b78330cbae8e19c
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
index 79e5b00148..39c3f52da1 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 默认的逐目录候选列表是 `['AGENTS.md', 'CLAUDE.md']`。该列表可通过 `instructionFileCandidates` 配置；`AGENTS.md` 是普通的第一候选项，而不是隐藏优先级。一个目录中只加载第一个存在的普通文件候选项。使用默认值时，`AGENTS.md` 是原生文件，`CLAUDE.md` 是兼容性回退。第二个列表 `localInstructionFileCandidates`（默认为 `['AGENTS.local.md', 'CLAUDE.local.md']`）会在同一目录的基础文件后加载叠加式本地覆盖层；[默认本地覆盖层记录](2026-07-21-local-instruction-overlay.md)负责说明该决策。
 
-候选条目必须是同一目录中的文件名。空条目、`.`／`..`，以及包含 `/` 或 `\` 的条目会被忽略。其他同目录名称可以显式选择加入；规则目录和导入语义不属于本契约。
+候选条目必须是同一目录中的文件名。空条目、`.`／`..`，以及包含 `/` 或 `\` 的条目会被忽略。其他同目录名称可以显式选择加入；规则目录和导入语义不属于本约定。
 
 用户全局文件固定为 `$DSH_HOME/AGENTS.md`，不受任一候选列表影响，也没有本地覆盖层。`$DSH_HOME` 默认为 `~/.dsh`，与 `~/.codex` 或 `~/.claude` 在 harness 层的 home 角色一致，而不会引入插件专用 home。波浪号展开与默认值位于 `dsh-paths` 中，以便未来的 harness 功能共享同一约定。
 
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index fa5b21ccac..2cb98d1258 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
 2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
-2026-06-29-todo-write-tool.zh.md: 5efcaf1f6e7ea69b1dd8cd0fd31b9cbd931666db
+2026-06-29-todo-write-tool.zh.md: 2e95cfc4b085b03a70a651c622ca87ad7efa1538
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 5efcaf1f6e..2e95cfc4b0 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -14,7 +14,7 @@ harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结
 
 ### 整列表替换，三态 status
 
-模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`，与 codex `update_plan` 相同的三元组；在 bridge 还把 todo 列表投影为 `plan` 更新时，它也与 ACP `PlanEntryStatus` 1:1 对应，该映射已随[仅面向自动化的 ACP 契约](../simplification/2026-07-23-acp-automation-only-protocol.md)退役。
+模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`，与 codex `update_plan` 相同的三元组；在 bridge 还把 todo 列表投影为 `plan` 更新时，它也与 ACP `PlanEntryStatus` 1:1 对应，该映射已随[仅面向自动化的 ACP 约定](../simplification/2026-07-23-acp-automation-only-protocol.md)退役。
 
 ### 状态在会话日志上，而非服务
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index 9a76a6024c..b5b5ea3b97 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
 2026-06-30-hook-protocol-lib.md: 2edff0d501cd7695873c68054eeb3a1e9942eced
-2026-06-30-hook-protocol-lib.zh.md: e9ae51f5d7697017ecc153866bbb8c3f6fd34eb6
+2026-06-30-hook-protocol-lib.zh.md: 90648c535e8bccd264ef9ae1ffd5f66590b1ac6d
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index e9ae51f5d7..90648c535e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出契约，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
+钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出约定，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
 
 本 Agent Note 引入 `@deepseek-ai/dsh-hook-protocol`，一个**库**（不是插件——它不注册也不注入任何东西），持有两个桥接插件共同依赖的真正相同的原语。共享与方言专属之间的分界是本设计的重心。
 
@@ -17,7 +17,7 @@ Status: implemented
 **共享（本库）：**
 - **Matcher** — `matcherDiagnostic(pattern, mode)` 与 `matchesMatcher(pattern, query, mode)`。两种方言的唯一差异收敛到 `mode` 参数：`claude` 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符表示多个精确匹配备选项），其他 pattern 视为正则；`codex` 始终使用未锚定正则。缺省/`''`/`'*'` 匹配一切。每个桥接插件会在解析 group 前忽略不支持的事件，丢弃受支持但没有 matcher 匹配对象的事件所带字段，校验其余可运行 group；其中任何无效正则都会导致整份配置加载失败，并给出包含方言／pattern／事件的稳定诊断，不会注册任何钩子监听器。运行时匹配仍会将无效正则隔离为不匹配，因此直接调用本库绝不向 agent loop（智能体循环）抛异常。
 - **执行** — `runHook(bash, hook, options)`。通过 `ctx.bash` seam 而非自建 `spawn` 运行命令钩子：执行器已提供清洗但可覆盖的 env、进程组 kill 和超时，正是协议所需的能力；`dsh-bash` 的 `stdin`/`env` 字段（正是为此添加的）是进程内桥接插件被允许使用的受信插件接口。它将桥接插件构建的 payload 序列化到 stdin（仅 CC 时追加尾部换行），遵守钩子的 `timeoutSec`（否则使用 `DEFAULT_HOOK_TIMEOUT_MS`，即两种方言共享的 10 分钟参考默认值），且从不抛异常（执行器拒绝变为 non-blocking-error 的 `HookOutput`）。
-- **解码** — `parseHookOutput(exit, stdout, stderr)`，exit-code + structured-stdout 编解码器，产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout；exit `2` → blocking error，`stderr` 为原因（以 `decision: 'block'` 呈现，调用方无需单独处理 exit-code 分支）；其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段（`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`）；桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析（CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript（文本记录），因此无需抑制；见 [收紧钩子协议契约 Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)）。
+- **解码** — `parseHookOutput(exit, stdout, stderr)`，exit-code + structured-stdout 编解码器，产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout；exit `2` → blocking error，`stderr` 为原因（以 `decision: 'block'` 呈现，调用方无需单独处理 exit-code 分支）；其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段（`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`）；桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析（CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript（文本记录），因此无需抑制；见 [收紧钩子协议约定 Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)）。
 - **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
index 3adc8a826f..b436887b7a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-seams.md
 2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
-2026-06-30-interception-seams.zh.md: 40989aa6bd6f2c103312c01fb4efbab21487adea
+2026-06-30-interception-seams.zh.md: 110b28d48a342b50f8e5c1024ed2f2df704e4099
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
index 40989aa6bd..110b28d48a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那样在生命周期节点扩展或管控 agent（智能体）。驱动本设计的关键视角转换是：**「原生钩子」不是一个包**——原生钩子只是一个普通的 Cordis 插件，订阅规范的生命周期事件。因此真正的产品是一个*强大、类型完备的规范事件表面*；CC/Codex 桥接（`dsh-hooks-claude` / `dsh-hooks-codex` 包）只是将外部 shell 钩子协议映射到同一表面的翻译层。桥接能做的事，普通插件可以直接做——而且更强大（无序列化边界、完整 `ctx`、类型化返回值）。
 
-该表面需要为以下场景提供各自独立的契约：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
+该表面需要为以下场景提供各自独立的约定：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
 
 ## 决策
 
@@ -31,7 +31,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 - **`ToolDefinition.finalizeContent`** 是一个可选、同步、对所有输入都有定义且仅能处理内容的边界，在调用创建时随可见定义一起被快照。注册表将候选结果规范化并创建无损快照后，它恰好运行一次；候选结果包括绕过后续 waterfall 的 pre、around 或 post 监听器失败，以及为另一个结果字段创建快照时发现的错误。它可以替换 `content`，也可返回 `undefined` 保留原内容，但不能重写 `isError`、结构化错误身份、上下文或呈现元数据。工具在此执行自身最后一道内容不变式，而无需将策略失败转换为更弱的阻止 decision。
 - **`tools/result`** 是在所有变换、无损 JSON 实体化和外层错误边界之后的同步且故障受控的通知。它接收相同的冻结执行身份和权威结果的不可变快照；观测者的失败按监听器隔离，无法改变或拒绝 `ToolRegistry.execute()` 返回的结果。
 
-核心调度与工具体位于规范化边界内部，因此工具、监听器、无效规范值、渲染器／投影器、非 JSON 呈现和身份形状错误均解析为 JSON 安全的 `isError` 结果，而非逃逸出轮次。post-execute 监听器因此可以检查一个抛出异常的工具；由工具定义负责的最终内容不变式也会覆盖外层流水线与候选结果实体化失败；最终观测者会同时看到执行期间的规范值，以及会话日志能够持久化的确切呈现字段。[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)定义值／投影与持久性规则。
+核心调度与工具体位于规范化边界内部，因此工具、监听器、无效规范值、渲染器／投影器、非 JSON 呈现和身份形状错误均解析为 JSON 安全的 `isError` 结果，而非逃逸出轮次。post-execute 监听器因此可以检查一个抛出异常的工具；由工具定义负责的最终内容不变式也会覆盖外层流水线与候选结果实体化失败；最终观测者会同时看到执行期间的规范值，以及会话日志能够持久化的确切呈现字段。[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)定义值／投影与持久性规则。
 
 ### 三个承重的循环决策
 
@@ -43,7 +43,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 工具执行前输入重写是一个独立的一致性决策
 
-`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，UI 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该契约属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
+`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，UI 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该约定属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
 
 ### 边界
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
index 3e46be0e44..3e5d68bb7e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
 2026-06-30-session-store-fork-api.md: 69ff85e1f137f4f263bf951af0a3f655411c606a
-2026-06-30-session-store-fork-api.zh.md: 75262c8ceca40745feba1d4384cb949b95f3c677
+2026-06-30-session-store-fork-api.zh.md: f354aaefbc16c6c3251da20de507602105a32296
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
index 75262c8cec..f354aaefbc 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
@@ -46,4 +46,4 @@ Host 通过 agent（智能体）注册表，以选定的种子和谱系创建子
 
 公开接口保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话创建时便带有种子事件，因此现有后端只需持久化该种子一次，并在 header 中保存 `parentSession`／`seedLength`。
 
-v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才声明支持该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖；store、Host、载体与客户端的专项测试固定边界和对账契约，真实 Chromium 场景则固定组装后的消息操作与谱系树。
+v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才声明支持该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖；store、Host、载体与客户端的专项测试固定边界和对账约定，真实 Chromium 场景则固定组装后的消息操作与谱系树。
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 394af669cd..52c64ec86d 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
 2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3
-2026-07-05-dynamic-workflows.zh.md: 246727649be8acc17dac1335d353e9b1591e3890
+2026-07-05-dynamic-workflows.zh.md: b66e767090e29f7e0cceb35b59eedb2ea60d12eb
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index 246727649b..b66e767090 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -12,7 +12,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 在 `packages/workflow/` 下以 bash seam 的形态（接口／实现／消费方）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
 
-### 脚本契约（兼容 Claude Code）
+### 脚本约定（兼容 Claude Code）
 
 一次工作流调用包含 JSON `meta`（`name`、`description`，以及可选的 `whenToUse`/`phases`）和一段支持顶层 `await` 并返回 JSON 值的 JavaScript `script` 正文。元数据作为数据校验，从不被执行。正文接收 `agent(prompt, options)`、`parallel(thunks)`、`pipeline(items, ...stages)`、`phase(title)`、`log(message)` 和 `args`。流水线各阶段接收 `(prev, item, index)`，阶段之间无屏障；失败的子 agent 和普通阶段错误将受影响的 item 结算为 `null` 并跳过其剩余阶段。Claude Code 的确定性限制随日志机制一并延后实现，因此兼容的脚本正文在将 meta 头移入参数后可以使用时钟和随机数。
 
@@ -28,7 +28,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 **为何选择 `node:worker_threads`**：每次运行获得一个非池化的 worker。vm 上下文限定了文档中说明的脚本接口范围，而消息端口 RPC 将 `agent()` 桥接到宿主侧的子循环。worker 防止脚本的同步工作阻塞宿主，提供序列化边界，并允许取消后强制终止。`isolated-vm` 因其维护状态和部署要求被否决。
 
-宿主在发布前校验元数据并解析正文。私有枚举键 payload 映射定义协议格式；待启动记录、已发布子记录、单一取消信号、worker 死亡回收、结果优先级与 dispose 完全停稳，在此协议上保持 subagent run 契约。这些竞态算法由 [agent 作用域运行时设计 Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#workflow-children-are-pending-starts-or-published-records) 定义。
+宿主在发布前校验元数据并解析正文。私有枚举键 payload 映射定义协议格式；待启动记录、已发布子记录、单一取消信号、worker 死亡回收、结果优先级与 dispose 完全停稳，在此协议上保持 subagent run 约定。这些竞态算法由 [agent 作用域运行时设计 Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#workflow-children-are-pending-starts-or-published-records) 定义。
 
 引擎暴露一条进程内 `MessageChannel` 测试路径，因为主进程 V8 覆盖率无法观测 worker 执行。
 
@@ -55,7 +55,7 @@ worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够
 ## 延迟（本轮明确的非目标）
 
 - **后台收集**（启动工具 → run id → 完成通知 → 收集），与 bash/subagent 后台统一一起设计。
-- **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本契约收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
+- **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本约定收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
 - **保存/打包的工作流**（`.deepseek/workflows/` 注册表、斜杠命令界面）和**脚本持久化到运行目录**（工具调用事件已经持久记录了脚本）。
 - **嵌套 `workflow()`**、**token `budget`**，以及 `effort`/`isolation`/`agentType` agent 选项（每个都会明确拒绝，并在消息中注明其已延迟实现）。
 - **整体运行的挂钟超时**：取消总能释放调用方（result 在宽限期内 settle），因此总运行时间上限是后台重设计的策略旋钮，不是此处的正确性需求。
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index e0f79bacb0..05b3a3700f 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-skill-system.md
 2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
-2026-07-05-skill-system.zh.md: 05bd880ecbd46f2b472eb2cc5442f11c07f89b4e
+2026-07-05-skill-system.zh.md: 42ae08e603411bee6212f6f321eb766c9b9d1859
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 05bd880ecb..42ae08e603 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -22,13 +22,13 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包（package）解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包有限 frontmatter 需求已声明的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
 
-本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方契约。
+本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方约定。
 
 `dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
+数据结构与目录/工具约定记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
 
 ## 曾考虑的替代方案
 
@@ -54,4 +54,4 @@ agent-core 主干包含一个目录贡献者、一个本地提供方和一个面
 
 ## 延后
 
-Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的契约范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
+Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的约定范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index b5c6343382..46f1ed0675 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-approval-seam.md
 2026-07-06-approval-seam.md: a286e07d51a70232f9aab0af5d8a19622cd222d4
-2026-07-06-approval-seam.zh.md: 6656cfe46de663f0e89eacc78dcfb3425812f9e0
+2026-07-06-approval-seam.zh.md: b15fcb2f6ed52ee591082770d68e265b5a703ff8
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
index 6656cfe46d..b15fcb2f6e 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -77,7 +77,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 #### 实体与依赖
 
-`dsh-user-approval` 依赖 Cordis，以及会话、agent 和带 brand 的调用契约；`dsh-tools` 与 `dsh-acp` 消费它。沙箱执行器保持独立，因为升级请求归 `dsh-tool-bash` 所有。固定的派发与审计服务仍是一个包；可替换的应答者留在各自的通道所有者中。静态能力授权和 `subagent-acp` 子侧权限应答仍是独立关注点。
+`dsh-user-approval` 依赖 Cordis，以及会话、agent 和带 brand 的调用约定；`dsh-tools` 与 `dsh-acp` 消费它。沙箱执行器保持独立，因为升级请求归 `dsh-tool-bash` 所有。固定的派发与审计服务仍是一个包；可替换的应答者留在各自的通道所有者中。静态能力授权和 `subagent-acp` 子侧权限应答仍是独立关注点。
 
 ### 测试
 
@@ -95,14 +95,14 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - **单一注册提供方而非 waterfall 监听器**：否决。`registerProvider()` 接口迫使所有组合问题——允许列表预过滤、外部钩子决策者、脚本化测试应答、人类前面的策略门禁——都塞进一个提供方实现。waterfall 直接复用运行时已有的组合能力、缺失时默认拒绝行为和 HMR（热模块替换）资源释放机制；seam 的 JSDoc 以约定固定单决策槽语义，而非发明一个提供方注册表。
 - **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
-- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
+- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的约定在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
 - **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
 - **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
 - **现在就提供 `allow_always`**：否决。协议能表达它，但兑现它意味着设计授权存储、作用域标识和撤销（§ 延后）。展示 harness 无法兑现的选项只会制造注定失败的授权。
 
 ## 后果
 
-实现后的契约由「测试」一节所列套件固定：
+实现后的约定由「测试」一节所列套件固定：
 
 - `allowed-once` 派发一次操作；其他所有结果都以不同原因拒绝，而 `'never'` 会在提示前拒绝。
 - 缺失、外部、无 agent、抛异常、无效或断开连接的应答路径都会失败关闭。
@@ -113,7 +113,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - **两个都会直接作出决策的应答者会竞争同一槽位。** 兄弟插件的监听器顺序不确定，seam 无法仲裁竞争的终端应答者。通过约定缓解（每个部署一个终端应答者；仅对「先决策或委派」门禁使用 `prepend`），而非事件总线不具备的优先级机制。
 - **生产路径仅在一种组合下得到验证。** `ask` 有两个生产者家族——钩子桥通过 `tools/pre-execute`，沙箱升级通过自己的门禁——协议格式录制在沙箱示例的快照套件中；因此在更多部署组合它之前，seam 的真实覆盖面就是这一种组合。
-- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭，届时需要另一种归属契约。
+- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭，届时需要另一种归属约定。
 
 ## FAQ
 
@@ -132,7 +132,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 本设计复用或对照的仓库内先例：
 
-- `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者契约复用了它。
+- `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者约定复用了它。
 - `hook/invoked`/`hook/result`——仅日志审计对先例，`approval/asked`/`approval/decided` 沿用了它；[钩子桥 Agent Note](2026-06-30-hook-bridges.md) 交付了 `permissionDecision: ask`，即第一个生产者。
 - [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
 - [仅面向自动化的 ACP Agent Note](../simplification/2026-07-23-acp-automation-only-protocol.md)——应答者路由时对会话映射执行的精确 agent 归属检查；[多会话 Agent Note](2026-06-14-acp-multi-session.md)——本设计实现的每会话权限归属阻塞项。
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
index c01e419b7d..3ede7af472 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
 2026-07-06-explicit-tool-order.md: bd6d0a04aa470ca33e618957ae1f08c1ef15fcfe
-2026-07-06-explicit-tool-order.zh.md: 88955aaaa55b18ac94153b34d4e514ecc1fa1100
+2026-07-06-explicit-tool-order.zh.md: 69365151f2c20cfa782ecc5560a6c600c8dec6a2
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
index 88955aaaa5..69365151f2 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 
 `assemble()` 在 `system-prompt/assemble` waterfall（瀑布式事件）之前将提供方工具归一为权威顺序，从源头消除注册顺序的差异。waterfall 从这个确定性列表开始；不变的顺序随后流入请求头、冻结的请求和重建检查，无需 loop 特有的排序逻辑。
 
-范围刻意收窄：本 Agent Note 修复的是注册顺序竞态，而非插件行为。`system-prompt/assemble` 的监听器仍然可以添加、移除或重排工具——正如它可以在 section 排序之后编辑 section——并对自身输出的确定性负责；waterfall 契约已经要求监听器是确定性的（可重建性不变式会捕获在构建与回放之间行为不一致的监听器）。
+范围刻意收窄：本 Agent Note 修复的是注册顺序竞态，而非插件行为。`system-prompt/assemble` 的监听器仍然可以添加、移除或重排工具——正如它可以在 section 排序之后编辑 section——并对自身输出的确定性负责；waterfall 约定已经要求监听器是确定性的（可重建性不变式会捕获在构建与回放之间行为不一致的监听器）。
 
 配置传递沿用 `persona` 的先例，`toolOrder` 与之并列：TUI、Headless 和 ACP 应用配置接受该键，并通过 `dsh-agent-spine-demo`（其 schema 是各所有者 schema 的交集）转发给 `SystemPrompt` 子服务。有一个 schemastery 细节至关重要：schemastery 数组默认为 `[]`，但省略的 `toolOrder` 必须保持 ABSENT（= 字典序），而不是变成一个显式配置的空列表（无效——缺少 rest 条目），因此链路上每个 schema 都将默认值强制为 `undefined`。
 
@@ -44,7 +44,7 @@ Status: implemented
 - 步骤之间的纯工具重排与其他 header 变更一样记录：一份原因是 `'change'` 的完整 `request/header` 快照。稳定的权威顺序会防止注册时序在普通路径上制造这类变化。
 - `toolOrder` 键沿 app → `agent-core` → `SystemPrompt` 的转发链传递，因此部署时将其放在 app 配置中 `persona` 旁边即可；`dsh-llm` 和 agent loop 无需改动。
 - `toolOrder` 中拼错或未加载的工具名称在提示词组装时使轮次失败，而非启动时：loop 在轮次内部组装（`turn/start` 之后、`step/start` 之前），因此拒绝到达轮次的外层 catch——轮次以 `error` 原因完整结束并携带错误消息，`agent/error` 复现该消息，不打开步骤，不记录 `request/header`，不向适配器发出请求，agent 回到空闲状态。每个轮次都以相同方式失败，直到配置被修正；进程本身保持运行（符合仓库规则：显式配置引用不得被静默忽略——执行点是组装，因为不存在更早的通用时刻）。
-- 工具提供方返回保留的 rest 条目名称时，其提示词组装失败形态与未知的已列名称相同。这防止哨兵值变成一个歧义的真实工具，并保持「从不丢弃工具」的排序契约。
+- 工具提供方返回保留的 rest 条目名称时，其提示词组装失败形态与未知的已列名称相同。这防止哨兵值变成一个歧义的真实工具，并保持「从不丢弃工具」的排序约定。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 755c076bca..5002872c0b 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md
 2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
-2026-07-06-sandbox.zh.md: 9f55626a8fd12782249284c83f1e76e1d2f89724
+2026-07-06-sandbox.zh.md: 85b9b6a65b6468b19c6044b4837abc4fab1cee1a
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 9f55626a8f..85b9b6a65b 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -50,7 +50,7 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 #### seam：`ctx.sandbox`
 
-`dsh-sandbox` 负责定义词汇和 `SandboxProvider` 契约：`confine(argv, policy)` 返回调用方应当 spawn 的替代 argv（经过包装，使进程及其所有子进程在约束下运行），加上所选后端达到的 `enforcement` 完整度、其拒绝方言（`denialSignatures`，该后端内核在拒绝文件操作时打印到 stderr 的子串），以及其结构化 runner 失败证据（`runnerFailureRules`，可选的允许退出码加上排除整行精确信息性行后按行匹配的致命签名）；没有可用后端时抛出失败关闭的 `SANDBOX_UNAVAILABLE` 错误，绝不静默放行。词汇：`SandboxMode`（`read-only` / `workspace-write` / `danger-full-access`，仅限文件操作——不声称覆盖网络和进程可见性）、`SandboxEnforcement`（`full` / `partial`）、`SandboxExecutionPolicy`（每次能力调用的完整 mode + 工作区根目录）以及 `SandboxPolicy`（提供给约束后端的子集）。
+`dsh-sandbox` 负责定义词汇和 `SandboxProvider` 约定：`confine(argv, policy)` 返回调用方应当 spawn 的替代 argv（经过包装，使进程及其所有子进程在约束下运行），加上所选后端达到的 `enforcement` 完整度、其拒绝方言（`denialSignatures`，该后端内核在拒绝文件操作时打印到 stderr 的子串），以及其结构化 runner 失败证据（`runnerFailureRules`，可选的允许退出码加上排除整行精确信息性行后按行匹配的致命签名）；没有可用后端时抛出失败关闭的 `SANDBOX_UNAVAILABLE` 错误，绝不静默放行。词汇：`SandboxMode`（`read-only` / `workspace-write` / `danger-full-access`，仅限文件操作——不声称覆盖网络和进程可见性）、`SandboxEnforcement`（`full` / `partial`）、`SandboxExecutionPolicy`（每次能力调用的完整 mode + 工作区根目录）以及 `SandboxPolicy`（提供给约束后端的子集）。
 
 策略随每次调用而非提供方携带：两个消费方可以在同一时刻以不同策略约束（bash 在 `read-only` 下运行，而一个受约束的子 agent 保持其状态目录可写），且经批准的升级重试是一次带有更宽策略的新调用——在配置固定的提供方模式下无法表达。
 
@@ -66,7 +66,7 @@ launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI
 
 Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 消费方同仓，并属于根 pnpm workspace。[仓库内 Landlock 发布决策](../process/2026-08-06-in-repository-landlock-release.md)负责共享锁文件、原生构建、打包演练和 npm 发布边界。平台二进制由 npm 选择，入口包拥有路径解析、探测、CLI 参数、致命前缀和部分强制执行通知，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
 
-后端 profile 共享模式契约但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
+后端 profile 共享模式约定但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
 
 #### bash 消费方
 
@@ -146,7 +146,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 - **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次新的带有自身参数和结果事实的已记录调用。
 - **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
 - **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
-- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照契约），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
+- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照约定），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
 - **将重试硬匹配到先前的拒绝**：否决。命令字符串同一性脆弱（引号、`workdir`、env 前缀、作为失败阶段重试的管道）——要么误拒诚实的重试，要么被轻易满足；真正的边界是人看到命令 + 理由。仅在 `allow_always` 授权存储需要机器可检查的范围时才重新考虑。
 - **通用 `env/state` facts map 加拥有者服务**：否决。approval 和沙箱独立组合，因此任何一方的状态都不应拖入第三个包；单键 fold 各自是一个 `findLast`，拥有者服务自然消解；没有跨旋钮的不变式，因此原子多键补丁无收益。
 - **通过 `agent.inject()` 加总线事件逐次叙述切换**：否决。独立通知会暴露归属方顺序和中间组合，而一次 pre-step 组合可以原子排队完整的当前状态。
diff --git a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
index 8ac4cd01ef..ca61a3783c 100644
--- a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md
 2026-07-07-mcp-client-plugin.md: 756a5c4dc9f1152ecb1955d93b8dc47fcf07c661
-2026-07-07-mcp-client-plugin.zh.md: 88401ad63bce0b690561acf3bb820b3b758779fa
+2026-07-07-mcp-client-plugin.zh.md: 9f45203c479379087c5a19eccce3ab7a339d4ed0
diff --git a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
index 88401ad63b..9f45203c47 100644
--- a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
@@ -104,7 +104,7 @@ type Config = StdioConfig | StreamableHttpConfig
 
 ### 公开名称规范化
 
-MCP 允许工具名最长 128 字符且可包含 `.`；DeepSeek 的函数名契约允许 `[A-Za-z0-9_-]` 且最多 64 字符。公开名称按确定性规则规范化：非法字符替换为 `_`，当替换或截断改变了名称时，追加 `(serverName, rawName)` 标识的 12 位十六进制 SHA-256 hash，确保不同的 MCP 标识永远不会坍缩为同一个公开名称：
+MCP 允许工具名最长 128 字符且可包含 `.`；DeepSeek 的函数名约定允许 `[A-Za-z0-9_-]` 且最多 64 字符。公开名称按确定性规则规范化：非法字符替换为 `_`，当替换或截断改变了名称时，追加 `(serverName, rawName)` 标识的 12 位十六进制 SHA-256 hash，确保不同的 MCP 标识永远不会坍缩为同一个公开名称：
 
 ```typescript
 function publicToolName(serverName: string, rawName: string): string {
@@ -131,7 +131,7 @@ MCP 仅保证工具名在[单个服务器内](https://modelcontextprotocol.io/sp
 ### 命名不变式
 
 1. 每个 MCP 工具拥有稳定标识 `(serverName, rawName)`；每个活跃标识恰好对应一个公开名称。
-2. 公开名称是确定性的、全局唯一的，且满足 DeepSeek 64 字符 `[A-Za-z0-9_-]` 契约。
+2. 公开名称是确定性的、全局唯一的，且满足 DeepSeek 64 字符 `[A-Za-z0-9_-]` 约定。
 3. MCP `tools/call` 始终接收原始的 raw name。
 4. 连接、断开或重新同步不相关的服务器永远不会重命名已有工具。
 5. 注册顺序永远不决定哪个工具可用。
@@ -206,7 +206,7 @@ v1 否决。它能防止跨服务器冲突，但无法将 MCP 注册与原生 ha
 ## 后果
 
 - 每个 MCP 服务器只需 `cordis.yml` 中的一条配置即完成集成：`serverName: filesystem` 加一条 stdio 命令（或一个 Streamable HTTP URL），就能将 `mcp__filesystem__read_file` 放入模型的工具列表，可调用，协议上使用原始的 `read_file`。
-- 公开名称是会话历史和权限/配置表面的一部分；命名算法是由测试固定的 v1 契约，发布后变更即为破坏性变更。
+- 公开名称是会话历史和权限/配置表面的一部分；命名算法是由测试固定的 v1 约定，发布后变更即为破坏性变更。
 - `mcp__<serverName>__` 限定符在每个名称上消耗 token。已接受：描述和 JSON Schema 在工具定义 token 中占主导，而限定符换来了稳定标识、冲突隔离和 MCP 全局策略匹配模式（`mcp__*`、`mcp__github__*`）。
 - **MCP SDK 稳定性**：`@modelcontextprotocol/sdk` 仍在演进中；破坏性变更需要更新桥接。版本已固定，且该 SDK 被广泛采用（Claude Desktop、Cursor、VS Code），因此破坏性变更不太可能悄然发生。
 - **工具 schema 质量**：MCP 服务器可能暴露描述不佳的工具（模糊的描述、不完整的 JSON Schema）。harness 原样透传——垃圾进垃圾出；这是服务器作者的责任，不是桥接的。
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
index d50b2323e3..e3b225948a 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
 2026-07-08-background-subagent-tasks.md: 679c57c3173a32b8cfccc6611b4ba74487e7f7e3
-2026-07-08-background-subagent-tasks.zh.md: 487943ab5cfe78226cde912854099fc56a5833a6
+2026-07-08-background-subagent-tasks.zh.md: c46f3925bc3334ff4cee79e4d9c95589e5361eaf
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
index 487943ab5c..c46f3925bc 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 [subagent seam](2026-06-21-subagent-capability-seam.md) 会返回 `SubagentRun`，但原先面向模型的工具会同步收集每一次运行。因此，各自独立的慢速委派要么一直占用父调用，要么按串行方式运行。
 
-subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者资源释放契约。
+subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者资源释放约定。
 
 ## 决策
 
@@ -16,7 +16,7 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 后台 subagent 使用[通用后台任务运行时](../architecture/2026-06-20-generic-long-running-tool-runtime.md)。`task_output`、`task_list` 和 `task_kill` 负责收集、列出、取消、完成通知和提示词引导；系统不提供 subagent 专用的配套工具。
 
-前台调用保留其同步契约：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
+前台调用保留其同步约定：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
 
 对于后台调用，工具会验证父级，并在调用 `ctx.tasks.start()` 前拒绝已中止的执行信号。任务运行时会在调用生产者启动器前，预检控制接口和拥有者清理。该启动器创建独立的 `AbortController` 并启动 `ctx.subagents.start()`；返回 id 之后，工具调用的信号不再拥有该子级。
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 105a9d3cfd..900fc9c374 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
 2026-07-08-self-referential-cordis-toolset.md: 29d331008d4111ae00147f2ddd19a628135339ac
-2026-07-08-self-referential-cordis-toolset.zh.md: 55013b774b4b6b371d9cbe6ac492b4e95500a7ff
+2026-07-08-self-referential-cordis-toolset.zh.md: d61ba794781226437a5d7499c20e5cd33119fe78
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index 55013b774b..d61ba79478 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -18,13 +18,13 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 ### 三个工具
 
-| 工具 | 契约 |
+| 工具 | 约定 |
 |---|---|
 | `cordis_inspect` | 当前进程活跃运行时的只读报告，每个 `what` 值对应一个 Markdown 段落（省略 `what` 则输出全部段落）。`plugins` 列出全部存活 fiber，`temporary` 只列 `cordis_mount` 创建的临时 Plugin。精确 `name` 搭配 `what: "api"` 或 `what: "events"` 可收窄到一个带源码文档的目标。 |
 | `cordis_mount` | 立即在 `node:vm` 沙箱中把 `code` 作为异步 JavaScript 函数体求值，且不保存到任何位置。返回的 Plugin 挂在内部 `cordis-dynamic` 分组下，并用新的进程内 id（`dyn-1`、`dyn-2`……）跟踪。 |
 | `cordis_unmount` | 按 id 卸载一个 `cordis_mount` 临时 Plugin，并只在其自有工具、监听器、服务、定时器和其他 effect 完全停稳后返回。它不能删除 Loader、配置或已安装的 Plugin。 |
 
-`cordis_inspect` 的段落是 `services`（每个已提供的 ctx 服务及所属 fiber）、`plugins`（全部存活 Plugin fiber）、`tools`（模型可调用的工具）、`temporary`（`cordis_mount` 子集，包含 id、running／pending 状态、提供与等待的服务和生命周期）、`api`（活跃服务签名及其引用类型）和 `events`（harness 事件及分发模式和签名）。临时 Plugin 可跨后续 turn 保持活跃，并在 `cordis_unmount`、工具集卸载或 DSH 重启后消失；系统绝不会自动恢复它们。宽泛的 `api` 和 `events` 报告省略完整 JSDoc；精确 `name` 返回一个服务或事件及其原始 JSDoc。其他段落不能搭配 name，未知目标会失败，而 API 目标必须处于活跃状态。[生成的工具目录](../../../../docs/tool-catalog.md)完整呈现面向模型的调用契约。
+`cordis_inspect` 的段落是 `services`（每个已提供的 ctx 服务及所属 fiber）、`plugins`（全部存活 Plugin fiber）、`tools`（模型可调用的工具）、`temporary`（`cordis_mount` 子集，包含 id、running／pending 状态、提供与等待的服务和生命周期）、`api`（活跃服务签名及其引用类型）和 `events`（harness 事件及分发模式和签名）。临时 Plugin 可跨后续 turn 保持活跃，并在 `cordis_unmount`、工具集卸载或 DSH 重启后消失；系统绝不会自动恢复它们。宽泛的 `api` 和 `events` 报告省略完整 JSDoc；精确 `name` 返回一个服务或事件及其原始 JSDoc。其他段落不能搭配 name，未知目标会失败，而 API 目标必须处于活跃状态。[生成的工具目录](../../../../docs/tool-catalog.md)完整呈现面向模型的调用约定。
 
 ### 沙箱语义
 
@@ -32,9 +32,9 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 沙箱全局变量刻意精简：一个带标签的直写 `console`（在宿主 stdout/stderr 上输出 `[cordis:<id>] …`，这样在挂载调用之后很久才触发的监听器输出仍能落到用户可见的地方）、`harness.defineTool` / `harness.registerTool` 注册对、新 vm 上下文缺少的编码原语（`btoa`/`atob` 作为基于 `Buffer` 的宿主闭包——这是一个经过审批的例外，`Buffer` 本身从不暴露——加上 `TextEncoder`/`TextDecoder`），以及对被扣留的 Node API 的可调用陷阱（`require`、`setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`、`fetch`），这些陷阱会抛出一条重定向消息指明 cordis 替代方案。只有函数形态的全局变量才设陷阱；`process` 和 `Buffer` 保持 `undefined`，这样 `typeof` 特性探测保持惰性而不会引爆一个抛异常的访问器。
 
-挂载代码通过三道控制跨越 vm 边界。双 realm `instanceof` 同时识别宿主和 vm 对象。`harness.defineTool` 在宿主 realm 中重建输出 schema／投影器，将工具体返回值快照为宿主自有的 JSON，并让注册表在观测前强制执行[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)。挂载的插件接收的是一个白名单上下文门面，而非原始或透传的 `Context`；框架管道和以 context 为值的返回会被拒绝。服务读取需要声明 `inject`，保留 Cordis 的激活与卸载语义。`ctx.tools.get` 仅暴露 schema 视图，因此挂载代码无法绕过 `ToolRegistry.execute` 直接调用定义。
+挂载代码通过三道控制跨越 vm 边界。双 realm `instanceof` 同时识别宿主和 vm 对象。`harness.defineTool` 在宿主 realm 中重建输出 schema／投影器，将工具体返回值快照为宿主自有的 JSON，并让注册表在观测前强制执行[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)。挂载的插件接收的是一个白名单上下文门面，而非原始或透传的 `Context`；框架管道和以 context 为值的返回会被拒绝。服务读取需要声明 `inject`，保留 Cordis 的激活与卸载语义。`ctx.tools.get` 仅暴露 schema 视图，因此挂载代码无法绕过 `ToolRegistry.execute` 直接调用定义。
 
-边界将无歧义的 JSON-Schema 形式规范化为 `ParameterSchemaSpec`，同时保留 `integer`、原始对象开放性和 required 数组。直接使用 DSL 的对象节点必须声明 `additionalProperties`；无效词汇会报错并给出可接受的替代方案。解析错误、TypeScript 错误、缺少 return、Node API 误用和重复工具名等错误信息包含相关源码行或纠正性契约，不叙述实现内部细节。
+边界将无歧义的 JSON-Schema 形式规范化为 `ParameterSchemaSpec`，同时保留 `integer`、原始对象开放性和 required 数组。直接使用 DSL 的对象节点必须声明 `additionalProperties`；无效词汇会报错并给出可接受的替代方案。解析错误、TypeScript 错误、缺少 return、Node API 误用和重复工具名等错误信息包含相关源码行或纠正性约定，不叙述实现内部细节。
 
 ### 内部分组与临时 Plugin 生命周期
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
index ece6f1a094..41a400987b 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
 2026-07-10-agent-session-identity-and-log-location.md: 7b51ae41ac00c12a496940c891092580003646fa
-2026-07-10-agent-session-identity-and-log-location.zh.md: 46c7c1ce429d66741cffbdd87eb415b90cf32fb3
+2026-07-10-agent-session-identity-and-log-location.zh.md: b310db258f781cb5326e4bfe9e9daf3a6c1793e7
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
index 46c7c1ce42..b310db258f 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
@@ -60,9 +60,9 @@ bash 工具说明只讲解持久约定：当前 harness 环境事实通过受管
 
 ## 测试
 
-单元测试覆盖注册表声明校验、effect 释放、逐次执行收集、`dshHome` 优先级，以及本地执行器清理并重建 `DSH_*` 的顺序。请求录制测试覆盖前台／后台快照、无 agent 调用、持久化不存在或为 JSONL、忽略模型 `env`，以及父子隔离。JSONL／SQLite 定位器契约测试与两套钩子桥接测试均锁定 transcript 可用和不可用两种方言。
+单元测试覆盖注册表声明校验、effect 释放、逐次执行收集、`dshHome` 优先级，以及本地执行器清理并重建 `DSH_*` 的顺序。请求录制测试覆盖前台／后台快照、无 agent 调用、持久化不存在或为 JSONL、忽略模型 `env`，以及父子隔离。JSONL／SQLite 定位器约定测试与两套钩子桥接测试均锁定 transcript 可用和不可用两种方言。
 
-一项无密钥的完整循环集成测试会在第一个轮次驱动真实的 agent loop、JSONL 持久化、tool-bash 与 bash-local。子进程打印 `DSH_HOME`、`DSH_SHELL`、会话 id、JSONL 目标和继承的陈旧哨兵值；测试校验当前值、陈旧变量不存在、刷写前文件不存在，并最终检查持久化 header。快照测试会固定录制请求 header 中的通用 bash 说明。该契约属于确定性的本地执行，不涉及模型选择，因此无需带密钥测试。
+一项无密钥的完整循环集成测试会在第一个轮次驱动真实的 agent loop、JSONL 持久化、tool-bash 与 bash-local。子进程打印 `DSH_HOME`、`DSH_SHELL`、会话 id、JSONL 目标和继承的陈旧哨兵值；测试校验当前值、陈旧变量不存在、刷写前文件不存在，并最终检查持久化 header。快照测试会固定录制请求 header 中的通用 bash 说明。该约定属于确定性的本地执行，不涉及模型选择，因此无需带密钥测试。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 6462a2c873..9566e667f2 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
 2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45
-2026-07-10-parallel-tool-call-execution.zh.md: 985557974c79d4080c4e35ccbb9740439988261a
+2026-07-10-parallel-tool-call-execution.zh.md: 278996fedb8c9dcc86916a1544535b1444b6e9f5
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 985557974c..278996fedb 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/subsystems/tools.md)。
+每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型约定见[工具数据结构](../../../../docs/subsystems/tools.md)。
 
 分类器有意设计为一元函数。返回 `true` 表示工具承诺：此调用可以与任何同样返回 `true` 的并列调用重叠执行。调度器不会比较调用，也不会证明它们的资源访问相容。
 
@@ -22,7 +22,7 @@ Status: implemented
 
 `defineTool()` 先验证参数，再调用类型化分类器。无效参数会被归为独占，且只有该调用真正执行时才会产生常规参数错误。`ctx.tools.executionMode(exec)` 会解析当前有效的工具定义，并返回带标签的 `parallel` 或 `exclusive` 模式；未知工具将按安全侧原则归为独占。
 
-使用带标签的模式，而不是公开布尔型调度器 API，使得以后可以表达感知资源的变体，无需改变分类器契约。
+使用带标签的模式，而不是公开布尔型调度器 API，使得以后可以表达感知资源的变体，无需改变分类器约定。
 
 ## 调度与顺序
 
@@ -50,7 +50,7 @@ Status: implemented
 
 Code Mode 仍不使用此调度器，因为模型只会发出一个原生 `run_code` 调用。`run_code` 及其内部派发队列仍按串行方式执行；`mode: 'both'` 中的原生并列调用使用常规调度器。
 
-## 安全契约
+## 安全约定
 
 工具返回 `true` 即承诺：其主体可以与其他并行调用同时运行。它不得直接变更父会话或其他由父级拥有的状态；它将输出返回给循环，由循环按模型顺序提交。
 
@@ -78,7 +78,7 @@ Code Mode 仍不使用此调度器，因为模型只会发出一个原生 `run_c
 
 **使用有状态的分类。** 向分类器提供实时 agent、注册表或 I/O 访问，会使决策依赖分类器的运行时机，并在分类与派发之间留下缺口。可变授权和陈旧状态检查仍属于执行时职责。
 
-**使用感知并列调用或感知资源的分类。** 调度器可以成对比较调用，或让每个调用声明资源读写要求。这样可以并行化不冲突的写入，却要求不相关工具共享资源标识和冲突语义。一元契约选择放弃这部分并发性，并在安全性取决于调用间关系时按安全侧原则处理。
+**使用感知并列调用或感知资源的分类。** 调度器可以成对比较调用，或让每个调用声明资源读写要求。这样可以并行化不冲突的写入，却要求不相关工具共享资源标识和冲突语义。一元约定选择放弃这部分并发性，并在安全性取决于调用间关系时按安全侧原则处理。
 
 **并行执行完整的工具流水线。** 这样可以让循环继续使用公开的单调用 API，但会并发运行 pre-execute 和 post-execute 中间件。现有防护和钩子桥可能承载有序状态，因此只允许派发重叠。
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
index 8f5de6df71..55a4439855 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
 2026-07-10-sqlite-session-query-provider.md: 372c21241f9ae5d7300165f016db9b36e6b52855
-2026-07-10-sqlite-session-query-provider.zh.md: b0789f18f5f334b14fe603ee36924666705136f1
+2026-07-10-sqlite-session-query-provider.zh.md: f5f2d22a209350975a4ccff9a538a55dfc8ff71e
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
index b0789f18f5..f5f2d22a20 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 精确读取的 `ctx.sessionQuery` 服务有意不维护派生索引。大规模持久化的历史记录需要全文搜索，而不是每次查询都扫描全部事件；当前的活跃会话则需要一个包含上次持久化检查点之后更新的覆盖层。搜索还需要具体的排序、摘要片段、过滤器、分页、取消以及重建行为。
 
-如果把这些关注点拆分到提供方协调器和数据库实现之间，就会产生两个耦合的对齐状态机。第一个实现既要暴露精简的提供方无关调用契约，也要在同一个生命周期内管理源观察、提取、SQLite 事务、代际与查询执行。
+如果把这些关注点拆分到提供方协调器和数据库实现之间，就会产生两个耦合的对齐状态机。第一个实现既要暴露精简的提供方无关调用约定，也要在同一个生命周期内管理源观察、提取、SQLite 事务、代际与查询执行。
 
 ## 决策
 
@@ -38,7 +38,7 @@ Status: implemented
 
 持久化文档在重启后仍然存在。实时会话使用连接本地的 TEMP 表，遮蔽相同 id 的持久化基础行，并在实时所有者分离时重新显露该基础行。关闭数据库会删除实时行。卸载持久化服务会隐藏持久化行，但不会把缺失视为权威删除；重新挂载后，系统会再次观察并对齐后端。实时会话头与持久化会话头的不可变字段发生冲突时，系统会失败，而不会合并两个来源。
 
-派生 schema 拥有独立的 application id 与单调递增的 schema 版本。持久化与 TEMP 会话元数据均遵循 `SessionHeader.createdAt` 的整数契约，将其存入严格的 `INTEGER` 列。系统识别到不兼容版本时，只会重置该派生数据库。如果数据库具有不属于本应用的 application id 或无法识别的用户表，系统会在修改日志模式前拒绝该数据库，防止意外配置的规范会话数据库遭到修改。在 POSIX 文件系统上，缺失的目录与数据库文件会以仅所有者可访问的权限创建，使新的 SQLite 伴随文件沿用该模式；现有权限模式保持不变。一个进程中的一个服务独占一条派生索引路径；代际与实时 TEMP 遮蔽状态都归连接所有，因此不支持跨进程写入方。
+派生 schema 拥有独立的 application id 与单调递增的 schema 版本。持久化与 TEMP 会话元数据均遵循 `SessionHeader.createdAt` 的整数约定，将其存入严格的 `INTEGER` 列。系统识别到不兼容版本时，只会重置该派生数据库。如果数据库具有不属于本应用的 application id 或无法识别的用户表，系统会在修改日志模式前拒绝该数据库，防止意外配置的规范会话数据库遭到修改。在 POSIX 文件系统上，缺失的目录与数据库文件会以仅所有者可访问的权限创建，使新的 SQLite 伴随文件沿用该模式；现有权限模式保持不变。一个进程中的一个服务独占一条派生索引路径；代际与实时 TEMP 遮蔽状态都归连接所有，因此不支持跨进程写入方。
 
 取消会使排队中的操作及时被拒绝。异步源观察一旦开始，调用方必须等待该后端 Promise 结算后才会收到拒绝；系统不会提交已中止的观察结果，也不会启动更多源观察或索引工作。Node 的同步 `DatabaseSync` 元数据与 MATCH 调用一旦开始在 JavaScript 线程上执行就无法中断，因此服务会在这些调用前后检查信号，但不承诺在语句执行期间抢占。
 
@@ -56,4 +56,4 @@ Status: implemented
 
 选定的分词器以较小的索引体积支持短 token，但不承诺子串召回。字面短语使查询语法安全且可预测，代价是不支持布尔表达式或完整 MATCH 表达式。取消在操作排队或等待数据源期间有效，但同步 SQLite 执行仍是不可抢占区段。
 
-单元测试将以下行为固化为契约：提取、过滤器、两种搜索范围、所有默认 surface、先过滤元数据再排序、摘要片段、字面量转义、确定性平局处理、完整分页、按范围的游标失效、动态挂载/卸载持久化服务、重启对齐、实时遮蔽、显露与重新打开、schema 安全、回滚重试，以及排队中或进行中的数据源等待取消。一个无需密钥的真实 Loader 路径测试会将该包与真实的 SQLite 持久化后端组合使用。
+单元测试将以下行为固化为约定：提取、过滤器、两种搜索范围、所有默认 surface、先过滤元数据再排序、摘要片段、字面量转义、确定性平局处理、完整分页、按范围的游标失效、动态挂载/卸载持久化服务、重启对齐、实时遮蔽、显露与重新打开、schema 安全、回滚重试，以及排队中或进行中的数据源等待取消。一个无需密钥的真实 Loader 路径测试会将该包与真实的 SQLite 持久化后端组合使用。
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
index b2e1785796..17cee6fc65 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
 2026-07-12-subagent-persona-tool-filter-and-depth.md: 2c5eaf8829e01536a2de34cc190573ff35e4ab77
-2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: 355db26ecaf57137420798474561d6a7032757cb
+2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: ae64e26d95e42ca6c933892348e22d3cbf0dc722
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
index 355db26eca..ae64e26d95 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
@@ -81,7 +81,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
 
 **为每种人设或工具集创建一个提供方。** 这会使共享相同传输和生命周期实现的提供方成倍增加，使动态部署配置变得笨拙，且仍需要递归机制。提供方的职责是执行传输；请求承载每个子 agent 的组合。
 
-**复制父级的完整工具视图。** 注册作用域设计上是扁平的，生命周期所有权不意味着可见性继承。复制已解析视图还会冻结动态全局注册，并在未完整定义任一契约的情况下混淆组合与授权。
+**复制父级的完整工具视图。** 注册作用域设计上是扁平的，生命周期所有权不意味着可见性继承。复制已解析视图还会冻结动态全局注册，并在未完整定义任一约定的情况下混淆组合与授权。
 
 **在子 agent 创建时快照允许的全局工具。** 冻结的 allow 集合使未来注册统一不可用，但它改变了热注册语义并开启了授权设计。已实现的过滤器保持为活跃的注册表谓词，并直接记录 allow 与 deny 的行为。
 
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
index 80a1952578..f2d337c93c 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
 2026-07-13-session-query-tracing.md: 47c12824a331546676d3bc79920f861afe648431
-2026-07-13-session-query-tracing.zh.md: 88ff93048db0e763888ce6f7fee60918be3675a7
+2026-07-13-session-query-tracing.zh.md: f578a69a3004722395d5b731f82482b8ebd548e5
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
index 88ff93048d..f578a69a30 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 校验边界
 
-事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以携带来源；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何契约违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
+事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以携带来源；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何约定违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
 
 所有返回的记录与数组都与内部状态分离。已知的实时事件追踪绝不查询持久化；持久化事件追踪保留精确读取所要求的列表／加载一致性检查。会话谱系必然属于跨语料操作，因此也保留跨语料的持久化失败语义。
 
@@ -27,7 +27,7 @@ Status: implemented
 - **公开独立的追踪辅助函数**：不予采纳，因为源优先级与状态分离边界属于 `ctx.sessionQuery`；公开辅助函数会诱使调用方绕过该边界。
 - **合并替换边与来源边**：不予采纳，因为位置替换可以遮蔽表面节点，同时引用不在表面上的构造输入，而消费方需要区分这两种含义。
 - **返回传递来源闭包**：不予采纳，因为这会掩盖日志中直接记录的证据、增大结果，并让一条遥远的格式错误边改变原本局部的输出。
-- **在格式错误的来源关系上返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部图会显得具有权威性。当规范的关系契约损坏时，精确检查会明确报错。
+- **在格式错误的来源关系上返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部图会显得具有权威性。当规范的关系约定损坏时，精确检查会明确报错。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
index 9697abde6f..eac4c74cdc 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
 2026-07-14-cross-family-fs-sandbox.md: e8a59be345b52f7684c574134b37f48bc49843fc
-2026-07-14-cross-family-fs-sandbox.zh.md: f816bc88db3d7624892fb057e63dd5f24381275e
+2026-07-14-cross-family-fs-sandbox.zh.md: 228e156688ce23c10ac42b2c96b3737f796d4524
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
index f816bc88db..228e156688 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
@@ -49,7 +49,7 @@ Status: implemented
 
 ### 强制执行点：提供方，而非 intent gate
 
-沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其契约称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。沙箱 Agent Note 的暂缓阶段措辞在同一变更中被更新以匹配。
+沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其约定称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。沙箱 Agent Note 的暂缓阶段措辞在同一变更中被更新以匹配。
 
 ### 范围之外
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
index 3975b65602..d01c01c55a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md
 2026-07-16-durable-per-step-time-context.md: e1a5c65894913ad93f46db8ae45e5ef5ead215f3
-2026-07-16-durable-per-step-time-context.zh.md: d353d2b4535cd2f6153adad084b4ca056f68dc8c
+2026-07-16-durable-per-step-time-context.zh.md: 129920a02dc21a91ddc92de3d920ddad24968656
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
index d353d2b453..129920a02d 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
@@ -66,4 +66,4 @@ Elapsed since the preceding step context: <duration-or-unavailable>.
 - 省略 `refreshIntervalMs` 或设为 `0` 时，每次符合条件的准备尝试都会留下记录；正数间隔会减少追加频率和历史增长，同时使持久调度在恢复后继续生效。
 - 时间上下文仅追加并保留到压缩隐藏旧表层节点为止，其中也包括后续取消或失败所留下的准备读数。
 - 第一个步骤的时长通常从开启轮次的提示词起算，后续步骤的时长则反映自上一条步骤上下文以来的模型与工具处理时间。
-- 省略 `timeZone` 时仍采用部署进程而非远程用户的时区，时长仍采用 harness 的持久追加边界而非客户端来源时间戳。若要支持客户端来源的时间，需要另行建立持久输入契约。
+- 省略 `timeZone` 时仍采用部署进程而非远程用户的时区，时长仍采用 harness 的持久追加边界而非客户端来源时间戳。若要支持客户端来源的时间，需要另行建立持久输入约定。
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 15d82777e1..3893ff403f 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
 2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
-2026-07-16-harness-level-loop.zh.md: 10f4cd2ac4991361261dd652d5d99dcb15d459be
+2026-07-16-harness-level-loop.zh.md: 8d61c36915c7a3b5e0fde94c4c0ba52ec48eddd1
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 10f4cd2ac4..8d61c36915 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -88,7 +88,7 @@ Ralph 是位于自有插件中的一等模型工具，展示了复杂固定执
 
 Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天的持久目标，以及设置、查看、编辑、暂停、恢复与清除控制。本实现采用这种可发现性，但使用本仓库的事件溯源目标记录、插件作用域与运行时权限检查。
 
-当前 [Claude Code goals](https://code.claude.com/docs/en/goal) 进一步验证了“前一 Turn 后启动另一 Turn 的目标”和定时 `/loop` 之间的区别。Claude Code 还会在每个 Turn 后使用独立小模型评估器。本实现采用策略区分，但有意不复制该评估器：评估器输入、工具访问、确定性检查、provider 选择、隔离与权限需要单独设计的插件契约，而不是隐式自我认证层。
+当前 [Claude Code goals](https://code.claude.com/docs/en/goal) 进一步验证了“前一 Turn 后启动另一 Turn 的目标”和定时 `/loop` 之间的区别。Claude Code 还会在每个 Turn 后使用独立小模型评估器。本实现采用策略区分，但有意不复制该评估器：评估器输入、工具访问、确定性检查、provider 选择、隔离与权限需要单独设计的插件约定，而不是隐式自我认证层。
 
 外部产品只是比较对象，不是兼容目标。本地源码研究帮助确定边界，而交付接口遵循本仓库“一切皆插件”、模型可见内容均记入日志、显式解析默认值与完全停稳后拆卸规则。
 
@@ -109,7 +109,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 ## 后果
 
-- 目标式执行在没有单个过载「loop」对象的情况下交付：同会话续行与全新 agent 迭代拥有显式、可独立测试的契约。
+- 目标式执行在没有单个过载「loop」对象的情况下交付：同会话续行与全新 agent 迭代拥有显式、可独立测试的约定。
 - 持久目标历史可以重放和 fork，而进程本地激活态会防止恢复时意外开始工作。
 - 人类获得小型 Codex 形态 UX；模型获得紧凑、带来源检查的工具表面；部署可以独立移除任一能力。
 - Ralph 展示了非平凡固定策略可以完全作为现有 workflow 与 subagent 原语之上的插件实现。
@@ -118,7 +118,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 ## 已知限制与暂缓事项
 
-- **独立评估**——同会话完成/阻塞和 Ralph 终止状态都是模型或工作者声明。独立评估器、评估器驱动反馈 Round、完成证书、确定性检查器、对抗式 verifier 与 criteria/executor/isolation 契约均予以延期。
+- **独立评估**——同会话完成/阻塞和 Ralph 终止状态都是模型或工作者声明。独立评估器、评估器驱动反馈 Round、完成证书、确定性检查器、对抗式 verifier 与 criteria/executor/isolation 约定均予以延期。
 - **聚合预算**——`maxGoalRounds` 与 Ralph `maxRounds` 是唯一聚合工作量限制。token、货币、耗时、provider 用量与逐 Round 价格准入策略均不存在。
 - **没有持久自治运行器**——同会话目标事实会持久化，但激活与调度只存在于进程内，并且有意在恢复后等待人类输入。Ralph 位于前台，进程丢失后无法恢复。后台收集、重启恢复与无人值守常驻执行均予以延期。
 - **没有时间调度器**——间隔 `/loop`、cron、主动维护以及云端或桌面调度不在本决策范围内。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 7756f7803c..f41c42e700 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
 2026-07-16-persistent-pty-sessions.md: 219f48235d527cffbf66020ceb22e80ca473093d
-2026-07-16-persistent-pty-sessions.zh.md: 18b81cd6a8d3f9cdbaa8566e1b166c3877ae8742
+2026-07-16-persistent-pty-sessions.zh.md: c3842936248fb2d1705708dfd694be563ce2adf9
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 18b81cd6a8..c384293624 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -22,7 +22,7 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 
 | 包 | 角色 | ctx key |
 |---|---|---|
-| `dsh-pty` | `PtyService`、branded `PtySessionId`、后端注册表、按 owner 隔离的会话契约和结果类型 | `ctx.pty` |
+| `dsh-pty` | `PtyService`、branded `PtySessionId`、后端注册表、按 owner 隔离的会话约定和结果类型 | `ctx.pty` |
 | `dsh-pty-local` | 基于 `ctx.subprocess.spawnTerminal()` 的持久 shell 后端：就绪状态、有界终端缓冲、沙箱解析和感知 owner 的会话生命周期 | 在 `ctx.pty` 上注册后端 |
 | `dsh-tool-pty` | 6 个面向模型的工具、后台发送的 task 运行时集成、使用指引和 UI 渲染意图 | 注册到 `ctx.tools` |
 
@@ -58,7 +58,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 | `terminal_close` | 关闭一个会话并等待进程树静默退出 | `{ killed }` |
 | `terminal_list` | 列出调用方的活会话 | 按 owner 隔离的会话摘要 |
 
-UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
+UI 渲染约定精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
 `terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。被取消的发送会保留其预留，直至异步前台信号发送结算，因此后续发送不会成为该信号的目标。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
@@ -88,7 +88,7 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此
 
 现有持久化 `tool/call` 与 `tool/result` 事件是模型发送文本和返回给模型的渲染输出的真源。`terminal_open` 通过已记录的工具结果返回 MOTD；前台 `send`/`read`/`list`/`signal`/`close` 结果走同一路径记录。PTY 包不会把原始字节流重复写入自定义会话事件。
 
-后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript sink 必须拥有独立的保留、凭证和隐私契约。
+后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript sink 必须拥有独立的保留、凭证和隐私约定。
 
 ### 进程树 teardown
 
@@ -130,7 +130,7 @@ plugins:
 
 ### 推迟的工作
 
-- 全屏 TUI 支持、命名按键序列、BEL 中断、终端 resize 工具和 alternate-screen 快照需要另行验证面向模型的契约。
+- 全屏 TUI 支持、命名按键序列、BEL 中断、终端 resize 工具和 alternate-screen 快照需要另行验证面向模型的约定。
 - 声明式 per-agent 启动需要 agent-setup 组合点；仍然禁止插件加载期全局会话。
 - harness 进程丢失后的会话恢复需要进程外 owner 和版本化协议。
 - 网络出口策略与外部副作用回滚超出 PTY 范围，继续作为独立安全工作。
@@ -138,9 +138,9 @@ plugins:
 
 ## 备选方案
 
-**用 PTY 替换 `bash`、文件系统工具或 task 工具。**拒绝。一次性工具拥有更强的校验、审批、沙箱、输出上限和回放契约。PTY 只服务交互式状态。
+**用 PTY 替换 `bash`、文件系统工具或 task 工具。**拒绝。一次性工具拥有更强的校验、审批、沙箱、输出上限和回放约定。PTY 只服务交互式状态。
 
-**给 `bash` 增加持久模式。**拒绝。按就绪而不是进程退出返回、跨调用保留进程树、暴露交互式 stdin 会形成不同的所有权和失败契约。
+**给 `bash` 增加持久模式。**拒绝。按就绪而不是进程退出返回、跨调用保留进程树、暴露交互式 stdin 会形成不同的所有权和失败约定。
 
 **要求从 `node-pty` 获取原生 master fd。**拒绝。它的公共 API 不暴露 master fd。本地子进程终端适配器改为从受支持的 OS 进程元数据推导前台组与子孙进程，并把不可读元数据视为 detector miss。
 
@@ -148,7 +148,7 @@ plugins:
 
 **发布可替换注册表 `PtyIdleDetector`。**拒绝。基底专用的前台事实来自挂载的终端进程原语，提示符／静默就绪判定则仍是 `dsh-pty-local` 内部的一项私有策略。替换文件系统／子进程执行环境就是所需扩展点。
 
-**新增 PTY 专用 `sleep` 工具。**拒绝。`ctx.tasks` 已经拥有有界等待、取消、完成通知和面向模型的收集。第二套通用唤醒机制会跨越 agent loop（智能体循环）边界并重复该契约。
+**新增 PTY 专用 `sleep` 工具。**拒绝。`ctx.tasks` 已经拥有有界等待、取消、完成通知和面向模型的收集。第二套通用唤醒机制会跨越 agent loop（智能体循环）边界并重复该约定。
 
 **包含 TUI sequence 与 BEL 处理。**拒绝。源 prototype 将这些路径视为 timing-sensitive，且仍记录未解决的 alternate-screen 和交互失败。行式 PTY 已能证明核心价值，无需把未经验证的行为放进基础层。
 
@@ -160,12 +160,12 @@ plugins:
 - 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
-- 包契约、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
+- 包约定、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
 
 ## 后果
 
-**无需削弱一次性工具即可获得持久终端状态。**Shell 与 REPL 状态可以跨工具调用保留，而 `bash`、`read`、`write` 和 `edit` 继续拥有更窄的校验、审批与回放契约。
+**无需削弱一次性工具即可获得持久终端状态。**Shell 与 REPL 状态可以跨工具调用保留，而 `bash`、`read`、`write` 和 `edit` 继续拥有更窄的校验、审批与回放约定。
 
 **Linux Tier 1 之外的 idle 都是启发式结果。**输出静默无法区分 prompt、sleep 和网络 I/O。类型化结果保留不确定性，有界 timeout、task 等待与信号让模型仍能掌握控制权。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
index 26b8332442..2e02bddec1 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
 2026-07-19-fresh-agent-ralph-workflow-tool.md: 6fe96587c49ef0316d1618fda2ee26b015b1ce87
-2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 03e5e4a705674b49c14cbb456b06d82fbd38f013
+2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7cd3cf388f9d1e03390dd08ed045562bcfeb1f4d
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
index 03e5e4a705..7cd3cf388f 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
@@ -52,7 +52,7 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
 
 - **把 Ralph 放进同会话目标驱动器** — 拒绝，因为 Goal Round 有意保留同一段对话，而 Ralph 的定义性属性是每个 Round 使用全新上下文；合并两者会让目标生命周期与子 agent 编排无法分离。
 - **在通用工作流工具上暴露 `fresh` 或循环标志** — 拒绝，因为模型编写的脚本表面应保持通用且与提供方无关；Ralph 的固定报告协议和停止策略值得拥有一个可评审消费方。
-- **为了方便重放而使用 `subagent_fork`** — 拒绝，因为继承的已完成轮次是隐式、不断增长的交接状态，并违反全新上下文契约。工作区加一份结构化报告即可重放，无需插入人为取消记录。
+- **为了方便重放而使用 `subagent_fork`** — 拒绝，因为继承的已完成轮次是隐式、不断增长的交接状态，并违反全新上下文约定。工作区加一份结构化报告即可重放，无需插入人为取消记录。
 - **让工具直接调用 subagent seam** — 拒绝，因为现有工作流引擎已经拥有前台编排、结构化子 agent、取消传播、工作线程终止、事件和完全停稳后的 dispose。复用它可以展示插件组合，而不是构建第二个循环运行时。
 - **静默截断大型报告** — 拒绝，因为截断可能删除状态证据或下一步，却仍看似权威交接。生产者必须在配置边界内发出有效报告。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
index 689b04ef55..5b39ad725e 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-human-goal-command.md
 2026-07-19-human-goal-command.md: 5fdd80f7423b80e84e58f7379130ee59a2e8a723
-2026-07-19-human-goal-command.zh.md: 841e7195454b2e0cfc6f74fb28369022b84c5780
+2026-07-19-human-goal-command.zh.md: 89d29497abfc758ff8373d272aa8620ca1bcfcc2
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
index 841e719545..89d29497ab 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 `/goal <objective>` 创建活跃且已激活的目标。已完成目标可以被替换，此时通过现有领域规则创建新的目标身份。任何未完成目标都会让命令直接失败，并提示用户使用行内编辑或明确清除。通用命令服务有意不提供模态确认 API；若静默执行清除再创建两条持久记录，就等于凭空制造破坏性同意，并暴露一个非原子的失败窗口。
 
-`/goal edit <objective>` 编辑当前未完成目标，但不改变其阶段或激活态。若目标已经完成，则创建一个新的活跃目标，因为领域不允许恢复已完成状态，而新的目标描述应拥有新的目标身份。单独使用 `edit` 会返回错误而不是启动编辑器，因为可移植的非结构化命令契约没有模态编辑器。
+`/goal edit <objective>` 编辑当前未完成目标，但不改变其阶段或激活态。若目标已经完成，则创建一个新的活跃目标，因为领域不允许恢复已完成状态，而新的目标描述应拥有新的目标身份。单独使用 `edit` 会返回错误而不是启动编辑器，因为可移植的非结构化命令约定没有模态编辑器。
 
 `/goal pause`、`/goal resume` 与 `/goal clear` 使用当前视图调用相应的比较并交换领域动词。恢复既适用于停止的持久阶段，也适用于会话恢复、fork 或驱动器替换后处于活跃但未激活状态的目标。领域规则仍会拒绝已耗尽的 Round 上限、对已活跃且已激活目标的重复恢复、非法阶段转换与陈旧身份。清除会移除当前指针，而会话日志保留带修订号的墓碑和此前快照。
 
@@ -50,10 +50,10 @@ TUI 应用包作出相反的产品选择。它默认让 `goals` 使用所有者
 
 - **让模型把 `/goal` 当作普通文本处理**——不予采纳，因为状态与直接生命周期操作会消耗模型轮次、可能被重新解释，也无法提供确定性的命令发现。
 - **在各 UI 中分别实现处理器**——不予采纳，因为语法、错误行为与目标状态格式会发生偏差，可选部署也无法把该功能作为一个 effect 统一增删。
-- **为 `ctx.commands` 添加模态编辑与替换确认**——不予采纳，因为现有跨界面契约是非结构化输入加直接输出；通用交互协议所需的设计远超这一个生产方。
+- **为 `ctx.commands` 添加模态编辑与替换确认**——不予采纳，因为现有跨界面约定是非结构化输入加直接输出；通用交互协议所需的设计远超这一个生产方。
 - **静默替换未完成目标**——不予采纳，因为这会在没有原子性或明确破坏性意图的情况下组合清除与创建。
 - **在人类状态中暴露目标 id 与修订号**——不予采纳，因为人类操作始终在一个同步处理器内针对确切的当前视图；这些字段只会增加实现噪声，无法避免另一处竞态。
-- **在无 UI 主干中无条件启用目标**——不予采纳，因为单次 SDK/CLI 的结束契约是物理轮次 API，而不是目标操作 API。
+- **在无 UI 主干中无条件启用目标**——不予采纳，因为单次 SDK/CLI 的结束约定是物理轮次 API，而不是目标操作 API。
 
 ## 后果
 
@@ -61,12 +61,12 @@ TUI 应用包作出相反的产品选择。它默认让 `goals` 使用所有者
 - 人类状态会区分持久阶段与实时激活态，并报告准确的目标 Round 上限。
 - 直接暂停、恢复、清除、创建与编辑不消耗模型轮次，而其已接受变更仍可从会话日志重建。
 - 恢复后的会话等待人类决策；`/goal resume` 是字面命令路径，任何语言的普通提示词则可以授权模型工具路径。
-- 无头组合保持单轮行为，除非明确选择加入目标并定义自己的长时间运行结束契约。
+- 无头组合保持单轮行为，除非明确选择加入目标并定义自己的长时间运行结束约定。
 
 ## 已知限制与暂缓事项
 
-- 可移植命令契约没有模态编辑器或确认交互；在出现通用跨界面交互原语之前，行内编辑与明确清除是有意选择。
+- 可移植命令约定没有模态编辑器或确认交互；在出现通用跨界面交互原语之前，行内编辑与明确清除是有意选择。
 - `/goal` 不接受逐命令 Round 上限。部署配置拥有默认值；得到直接人类指示后，已授权模型工具可以编辑上限。
 - TUI 渲染可移植纯文本，而不是持续更新的目标状态组件。可重连命令输出和适配器专用状态指示器予以延期。
 - ACP 自动化服务器、无头 CLI 与 JSON-RPC 前端不消费命令注册表。
-- 该命令观察并改变状态，但不认证完成或阻塞。基于评估器的认证延期到具有明确权限与隔离契约的独立策略层。
+- 该命令观察并改变状态，但不认证完成或阻塞。基于评估器的认证延期到具有明确权限与隔离约定的独立策略层。
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index debd2094e0..730de18a5a 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
 2026-07-19-model-facing-goal-tools.md: 0271194a38503711de77290c915010c26a9de74b
-2026-07-19-model-facing-goal-tools.zh.md: 235c3c5369871a8cdf731eee822abc4a3e6b58d1
+2026-07-19-model-facing-goal-tools.zh.md: 097aaa3b160a394ff3d13681be04dd19c7856ebc
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index 235c3c5369..097aaa3b16 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 位于 `packages/goal/tool-goal/` 的 `@deepseek-ai/dsh-tool-goal` 在 `ctx.goals` 之上贡献三个独占工具和一个系统提示词策略段：`get_goal`、`create_goal` 与 `update_goal`。工具名称和读取—创建—更新形态遵循 Codex 的紧凑目标工具表面，而权限规则使用本仓库公共的 agent（智能体）、会话、工具与目标 seam。
 
-### 工具与模型契约
+### 工具与模型约定
 
 `get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
index e58d618cf3..26dde53462 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
 2026-07-19-plugin-command-registration.md: c8f0f2772a41948e9eb257a16f40194518c568f9
-2026-07-19-plugin-command-registration.zh.md: 94853393f5f71b29cfbd8da5443b3d73ded20e92
+2026-07-19-plugin-command-registration.zh.md: a8f7a3d1e7947aeb41344a72106cee55d249010c
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
index 94853393f5..a8f7a3d1e7 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
@@ -14,7 +14,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派
 
 位于 `packages/interaction/commands/` 的 `@deepseek-ai/dsh-commands` 是产品命令注册表。TUI 应用 bundle（组合包）把它挂载在消费该服务的入口旁；[仅面向自动化的 ACP（Agent Client Protocol）应用](../simplification/2026-07-23-acp-automation-only-protocol.md)和无执行器、无 UI 的智能体 spine（主干）都省略该服务。TUI 注入该服务，命令生产者只依赖注册表及其操作的领域。
 
-### 注册表契约
+### 注册表约定
 
 `CommandDefinition` 包含不带 `/` 的小写名称、非空描述、可选的非结构化输入提示，以及可取消处理器。注册会校验元数据并复制一份与调用方脱离的副本、冻结最终生效的定义，并返回对应 Cordis effect 的精确 disposer（资源释放器）。同一层中的重复名称会失败。每个消费方都能看到所有有效定义；若命令插件无法在某种部署中运行，它就不在该部署中注册，而不是把消费方身份编码进共享领域。
 
@@ -30,7 +30,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派
 
 ### 直接分派与取消
 
-命令在仅面向人类的命令平面中运行。注册表不会把输入转成 `user/message`，输出不会成为会话事件，两者都不会隐式发送给模型。处理器接收对应的同一个目标 agent、原始输入和本次请求持有的 `AbortSignal`；生产者可以通过该智能体显式调度单独的模型可见工作，随后由生产者负责其日志记录和生命周期契约。信号中止时，注册表不再等待不合作的处理器；处理器仍负责停止已经启动的外部副作用。
+命令在仅面向人类的命令平面中运行。注册表不会把输入转成 `user/message`，输出不会成为会话事件，两者都不会隐式发送给模型。处理器接收对应的同一个目标 agent、原始输入和本次请求持有的 `AbortSignal`；生产者可以通过该智能体显式调度单独的模型可见工作，随后由生产者负责其日志记录和生命周期约定。信号中止时，注册表不再等待不合作的处理器；处理器仍负责停止已经启动的外部副作用。
 
 预期的处理器失败返回 `CommandResult.error`。抛出的异常或格式错误的结果仍是适配器可见的命令失败，而不是模型消息。该边界有意分离 UI 输出与持久领域变更：例如目标命令可以改变 `ctx.goals`，但持久状态由目标服务拥有。
 
@@ -58,7 +58,7 @@ TUI 测试覆盖全部迁移后的内置命令、实时插件发现、帮助与
 
 ## 后果
 
-- 命令生产者是普通的可移除插件，TUI 消费其经过校验的目录与分派契约。
+- 命令生产者是普通的可移除插件，TUI 消费其经过校验的目录与分派约定。
 - 智能体特定定义保留现有扁平作用域与遮蔽语义，不引入核心到 UI 的依赖。
 - 未知斜杠输入与命令输出是确定性 UI 行为，直接模型 token 成本为零。
 - 直接命令取消与模型轮次取消彼此隔离。
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
index 0af24062f6..900165a080 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
 2026-07-20-code-mode-typed-tool-returns.md: 2081d8161f0ee14493a09762b18ec7d9d07ea3c4
-2026-07-20-code-mode-typed-tool-returns.zh.md: 49d7a73f7f37d562fcbec2923d98ffa5ced97f68
+2026-07-20-code-mode-typed-tool-returns.zh.md: 808f8f96dbb1655dc00d1ccd9bb7f7ac93c9550f
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
index 49d7a73f7f..808f8f96db 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
@@ -10,13 +10,13 @@ Code Mode 过去会把每个嵌套工具的结果从 `ContentBlock[]` 重新投
 
 运行时还把绑定值和程序最终返回值当作展示数据。日志和完成值分别设置上限，导致过大或无法克隆的完成值可能被替换为检查后生成的文本，而中间值本来就不会进入模型上下文。这种设计使程序化组合产生信息损失，也混淆了内存边界与提示词边界。
 
-[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)确立了单一、经过校验的执行期值，并将 Native 渲染器与之分离。Code Mode 应直接消费该值，在跨越 worker 边界时完整保留它，并且只限制程序有意返回给模型的最终输出。
+[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)确立了单一、经过校验的执行期值，并将 Native 渲染器与之分离。Code Mode 应直接消费该值，在跨越 worker 边界时完整保留它，并且只限制程序有意返回给模型的最终输出。
 
 ## 决策
 
 Code Mode 是可见工具注册表的类型化投影。每个成功的绑定调用都会解析为 post-execute 策略处理后的最终规范 `JsonValue`，失败的绑定调用则会以真正的 `ToolCallError` 拒绝 Promise。中间值只存在于本次运行中，并完整跨越 worker 边界。只有外层 `run_code` 的日志、完成值或失败诊断会进入可配置的输出账本以及面向模型的输出落盘流水线。
 
-本文档定义叠加在原始 [Code Mode 基础](2026-06-15-code-mode.md)之上的返回值与失败契约。统一 schema 词汇由 [JSON 值 schema DSL Agent Note](../architecture/2026-07-20-unified-json-value-schema-dsl.md)负责定义；Native 渲染与策略投影仍由规范输出 Agent Note 负责定义。
+本文档定义叠加在原始 [Code Mode 基础](2026-06-15-code-mode.md)之上的返回值与失败约定。统一 schema 词汇由 [JSON 值 schema DSL Agent Note](../architecture/2026-07-20-unified-json-value-schema-dsl.md)负责定义；Native 渲染与策略投影仍由规范输出 Agent Note 负责定义。
 
 ### 生成的 SDK
 
@@ -51,7 +51,7 @@ declare const tools: {
 
 分发前，桥接层会把绑定参数快照为无损 JSON，再对分离后的值生成一次快照，供独立的持久摘要事件使用。宿主侧的值分离、执行数据的不可变处理与输出 schema 投影均采用迭代遍历，而不使用嵌套结构化克隆或递归冻结。`undefined`、非有限数、`-0`、稀疏数组、循环引用、函数和非普通对象都会使该调用在工具运行前被拒绝。成功分发会返回 `ToolExecutionResult.value`；Native `content`、元数据和内部错误信息不会传入程序。
 
-Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 seam 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把契约承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常契约，而不是供程序分类的失败联合。
+Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 seam 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把约定承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常约定，而不是供程序分类的失败联合。
 
 绑定参数与绑定返回值会在不可信 worker 协议的两端重新校验为无损 JSON，且不设字节上限。每个分离后的值在通过结构化克隆跨越边界前，都会编码为扁平的前序 token 流，其传输结构的嵌套深度有界；接收方再以迭代方式重建该值。因此，有效应用数据的嵌套深度既不受 JavaScript 调用栈深度上限限制，也不受特定平台对嵌套结构化克隆施加的上限限制。模块初始化时，worker 会捕获自身 JavaScript 运行域中 `Array.prototype` 和 `Object.prototype` 的引用、仅用于识别其他运行域普通容器原型、可获取原生函数源码的内建函数，以及 JSON 边界用于结构处理和计量的全部内建方法。属性写入使用原型为 null 的属性描述符；内部的数组与集合操作直接调用捕获的方法，不会访问可变的全局或原型槽位。因此，即使模型代码替换 `Object.keys`、`Array.isArray`、集合方法、字符串方法或 `Buffer.byteLength` 等辅助方法，重写内建原型的构造函数槽位，或向 `Object.prototype` 添加形如属性描述符的字段，也不会改变校验、协议传输或字节计量。面向其他运行域的原生函数源码检查仍会拒绝由用户编写、冒充 `Object` 或 `Array` 的构造函数。为保持依赖轻量，运行时 seam 将结构等价类型命名为 `CodeJsonValue`，从而无需依赖会话侧拥有的规范类型；生成的 SDK 和工具 API 则使用 `JsonValue`。这些值不会经过提示词截断、上下文输出落盘或持久化。因此，程序可以完整筛选已经采集的搜索、工作流、任务、文件系统与 MCP 值，同时提供方和执行器的采集上限仍会实际生效。
 
@@ -67,7 +67,7 @@ Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProper
 
 ### 类型化句柄与生命周期
 
-后台 producer 返回类型化的规范句柄，例如 `{ kind: 'background', taskId }`，同时保留既有的 Native 语句。已预先中止的后台调用仍是失败，因为成功输出承诺返回 id，而此时并未创建任务。`ctx.tasks.start()` 发布 id 后，工作由任务自有的取消机制控制：外围 `run_code` 调用完成，或随后被取消，都不会终止该任务。后续程序可以把返回的 id 传给 `task_output`；任务取消则由 `task_kill`、所有者的 dispose（资源释放）或服务 teardown（拆卸）流程负责。前台执行仍与本次调用的信号耦合。任务生命周期契约由[后台任务运行时 Agent Note](../architecture/2026-06-20-generic-long-running-tool-runtime.md)定义。
+后台 producer 返回类型化的规范句柄，例如 `{ kind: 'background', taskId }`，同时保留既有的 Native 语句。已预先中止的后台调用仍是失败，因为成功输出承诺返回 id，而此时并未创建任务。`ctx.tasks.start()` 发布 id 后，工作由任务自有的取消机制控制：外围 `run_code` 调用完成，或随后被取消，都不会终止该任务。后续程序可以把返回的 id 传给 `task_output`；任务取消则由 `task_kill`、所有者的 dispose（资源释放）或服务 teardown（拆卸）流程负责。前台执行仍与本次调用的信号耦合。任务生命周期约定由[后台任务运行时 Agent Note](../architecture/2026-06-20-generic-long-running-tool-runtime.md)定义。
 
 临时 Cordis Plugin 遵循同一规则：`cordis_mount` 返回 `{ id, pluginName, state, provides, waitingFor }`，因此程序可以直接读取 `mounted.id`，检查 active 或 pending 状态，并把该 id 传给 `cordis_unmount`，无需解析稳定的 Native 语句。
 
@@ -85,11 +85,11 @@ Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProper
 
 ## 考虑过的替代方案
 
-**返回 Native 文本并附加可选 JSON：**不予采纳。程序会面对两套相互竞争的成功契约；可选值不存在时，仍需使用工具专属的解析规则。规范值才是 API；Native 内容只是它的展示。
+**返回 Native 文本并附加可选 JSON：**不予采纳。程序会面对两套相互竞争的成功约定；可选值不存在时，仍需使用工具专属的解析规则。规范值才是 API；Native 内容只是它的展示。
 
 **让每个绑定返回成功／失败联合：**不予采纳。失败没有稳定的程序化分类体系。reject 保留普通的 `try`／`catch` 控制流，并且只暴露工具名与可供人阅读的消息。
 
-**限制每个中间绑定值：**不予采纳。中间值不会进入模型上下文，任意截断会破坏程序化组合。明确的边界仍是生产方的采集契约与进程内存。
+**限制每个中间绑定值：**不予采纳。中间值不会进入模型上下文，任意截断会破坏程序化组合。明确的边界仍是生产方的采集约定与进程内存。
 
 **静默检查格式化或截断过大的完成值：**不予采纳。把 JSON 值改成字符串既有损又违反类型。显式的 `output-limit` 失败让模型可以选择返回更小的结果，而保留的日志和诊断仍可使用普通的外层输出落盘机制。
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 0cf926921b..50196335f2 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
 2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
-2026-07-20-dsh-cli-personal-config.zh.md: b33a7fa321ca04f41e47386544ffc0f268a8b1b6
+2026-07-20-dsh-cli-personal-config.zh.md: 91d2c938b345a7f2233da1566ac6db5b934c3148
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index b33a7fa321..91d2c938b3 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
 
-**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该契约由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
+**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该约定由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
 
 **个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skills、AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 
@@ -34,7 +34,7 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 **个人完整 `cordis.yml` 去 include 请求的配置。** 否决：个人文件将不得不写死叶子配置的路径，而该路径随 checkout 变化；补丁反转了依赖方向，bin 仍然选择配置树，个人层只做修正。
 
-**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文契约。
+**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文约定。
 
 **用环境变量开关代替存在性判断。** 否决：默认关闭的个人配置永远不会被用起来；存在即生效加上每个测试的显式隔离，让实际运行获得 overlay、测试获得封闭性。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 1d93b7f440..03d812f73b 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
 2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
-2026-07-21-continuable-background-subagents.zh.md: 799e1914bdeb571dc697652081be6b0170768655
+2026-07-21-continuable-background-subagents.zh.md: 729ec62d9d3511661638144cdef6e31bf98ecdb7
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index 799e1914bd..729ec62d9d 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -33,7 +33,7 @@ durable child Session
 
 初始后台委派请求 `ctx.subagents` 启动 child 并注册其 Task。可继续提供方只有在确认本次激活的最终会话状态已持久化后，才会返回成功的 run 结果。Task 结算流程等待该结果，通过继续执行管理器的结算路径调用 `run.dispose()`，然后才记录 `TaskOutcome`；`task_kill` 中止活跃 run，其结算路径仍会 dispose 该 run。因此，终态 Task 会留下持久化 child 会话，但不会留下存活的 child agent。必需的持久性检查点若没有已安装的监听器或任一监听器失败，run 会以稳定错误码 `DURABILITY_FAILED` 拒绝，并将检查点失败保留为失败原因；管理器会记录失败的 Task，其详情说明最新状态未确认已持久化，因此恢复时可能不可用或已陈旧。
 
-后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 契约，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
+后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 约定，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
 
 用户界面适配器打开 child 会话时，只读取持久化 transcript，不会仅为展示而恢复 agent。用户输入通过继续执行管理器，启动或加入与 parent 输入相同的 Task 激活。由用户启动的 Task 会保留当前加载的精确 parent Agent 作为通知目标，`task_output` 仍是唯一结果路径。只要 Task 尚未标记为已报告，现有完成监听器最多注入一条主动通知；`kill`、终态读取或终态等待都可能将其标记为已报告，并抑制这条通知。因此，仅允许在该 parent 实例保持存活时进行用户交互。可以比 parent 存活更久、并将结论显式合并回去的用户自有会话属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)，不属于这一由 Task 持有的生命周期。
 
@@ -67,13 +67,13 @@ durable child Session
 
 发送到现有 run 的消息没有独立结果，其效果体现在当前 Task 的最终结果中。启动的后续轮次具有新 Task 的结果，并使用现有 `task_output` 读取路径。subagent 层不会再注入第二份完成通知。
 
-用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务契约，不建立彼此独立的执行路径。
+用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务约定，不建立彼此独立的执行路径。
 
 ### 持久化 child handle 与从持久化存储恢复
 
 继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/core/session/src/json.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
 
-版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果契约，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
+版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果约定，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
 
 从持久化存储恢复不能依赖 `SubagentRun` 的可选方法，因为该 run 已被 dispose，并且进程重启后不会保留。run 表示一次可 dispose 的激活，只暴露作用于当前激活的操作。`SubagentRun.steer?()` 这一名称明确指代提供确认语义且仅适用于在线消息的功能，以免该功能与服务编排或面向模型的工具混淆。
 
@@ -85,7 +85,7 @@ TODO（ACP 继续执行）：将远端 ACP session id 作为提供方专用描
 
 ### 结果与通知所有权
 
-每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告契约最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
+每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告约定最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
 
 Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可在重启后恢复，但不会恢复中断的 Task、其结果或通知。持久化 Task 恢复属于另一个问题。
 
@@ -95,7 +95,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 **允许用户轮次不使用 Task。** parent 消息加入此类轮次后，没有对应的 Task 结果或完成通知；UI 取消对 parent 所发消息的影响也不明确。让每次激活都拥有一个 Task，可使完成与取消成为 child 轮次的属性，而不是初始调用方的属性。
 
-**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 契约。
+**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 约定。
 
 **为每条消息创建 Task。** 发送到现有 run 的消息会加入已有轮次，不产生独立的最终结果；为这类消息创建 Task，会重复当前 Task，或报告一个它并不拥有的结果。只有启动新激活的消息才会创建 Task。
 
@@ -109,7 +109,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 ## 测试
 
-- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述契约。
+- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述约定。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
 - `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
@@ -123,5 +123,5 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - 活跃 run 关联只能协调一个运行时。多个进程同时恢复时不会串行化；此类部署需要持久化层的租约或 compare-and-set 操作。
 - 用户交互要求作为 owner 的那个精确 parent Agent 实例保持存活，因为 dispose owner 会取消并移除其 Task。用户交互还要求附加 Task 控制面。若要单独与 child 交互，后续必须将 Task 访问所有权与持久化通知目标分离。
 - 后台工具会在 child 发布和描述符持久化之前返回 child id 和 Task id。启动失败、最终持久性确认失败，或进程在 child 首次 flush 之前退出，都会使 Task 失败，并可能留下 unmaterialized 或陈旧的 child id；按 id 的控制操作会将缺失状态报告为不可用，而不会追溯修改工具确认消息。
-- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性契约便成为恢复契约的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
+- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性约定便成为恢复约定的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
 - Task 记录和活跃 run 关联位于进程内，而 child 会话具有持久性。重启会恢复会话，但不会恢复进行中的工作或其 Task 通知。
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
index c5d0cab7a1..e330fbd089 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
 2026-07-21-cross-session-references.md: b2d428e0937fdd881720720401948a1c3e7ef1f6
-2026-07-21-cross-session-references.zh.md: e242e159329a5f1446b08547cd0f176b6c1af3f7
+2026-07-21-cross-session-references.zh.md: ef89fd76c864c430f7b730d250e6511c2709f97e
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
index e242e15932..ef89fd76c8 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、来源过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息契约，还会让核心循环绑定某一种 UI 语法。
+TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、来源过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息约定，还会让核心循环绑定某一种 UI 语法。
 
 ## 决策
 
@@ -20,7 +20,7 @@ TUI 用户需要把另一场对话中的相关工作带入一条新消息，但
 
 准备过程按首次出现的顺序去重、拒绝目标会话自身的 id，并且执行可配置的数量限制，但引用硬上限为三个，所有读取均并行执行。该过程不会返回部分完成的上下文：任何读取、取消、校验或预算错误都会在调用 `followup()` 或 `steer()` 前拒绝本次操作。取消会与进行中的候选发现和精确读取竞速，因此即使持久化后端无法中断待处理操作，宿主也能及时结束等待；后端迟到的完成结果仍会被观察，但不能让消息入队。源会话在入队前完成读取，因此源会话后续新增消息、执行压缩、被删除或替换持久化内容，都无法改变目标会话中的快照。
 
-投影会保留直接用户消息与 steering（中途引导）、已完成的 assistant 文本，以及携带由 `dsh-compact` 导出的规范来源标记的检查点用户消息。该标记属于压缩能力契约的一部分，而非某个后端包名称。当源提示词已包含合并写入的前缀上下文时，投影只读取其模型不可见的显示内容，因此后续引用该目标不会递归传播先前的快照。投影会排除压缩前已被遮蔽的节点、工具及其结果、推理（reasoning）、注入的上下文、其他插件用户消息、仅用于日志的记录，以及尚未完成的 assistant 分片。因此，重复压缩只会暴露当前表层仍保留的最新折叠检查点谱系及其尾部消息；系统不提供 raw/current 开关，也不恢复被遮蔽的内容。
+投影会保留直接用户消息与 steering（中途引导）、已完成的 assistant 文本，以及携带由 `dsh-compact` 导出的规范来源标记的检查点用户消息。该标记属于压缩能力约定的一部分，而非某个后端包名称。当源提示词已包含合并写入的前缀上下文时，投影只读取其模型不可见的显示内容，因此后续引用该目标不会递归传播先前的快照。投影会排除压缩前已被遮蔽的节点、工具及其结果、推理（reasoning）、注入的上下文、其他插件用户消息、仅用于日志的记录，以及尚未完成的 assistant 分片。因此，重复压缩只会暴露当前表层仍保留的最新折叠检查点谱系及其尾部消息；系统不提供 raw/current 开关，也不恢复被遮蔽的内容。
 
 系统把一个聚合上下文序列化为 JSON，并置于固定的不可信背景警告之后。该警告要求模型不要遵循被引用会话中的指令、权限声明或工具请求，除非当前用户再次提出这些内容。标签安全序列化会把数据中的每个 `<` 无损转义为 JSON `\u003c`；因此源字符串无法拼出外围类似 XML 的标签，也无法逃逸数据区域。同一个序列化器会独立核算每个源的字节数。AgentLoop 会把快照持久化为一条带来源信息的 `user/message`，紧接在直接 `user/message` 之前。因此，目标回放无需新增事件类型、放置模式或提示词封套，也能满足「模型可见／日志可重建」不变量。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index e109560a2f..3ea46677ab 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
 2026-07-21-log-backed-session-titles.md: 89e6e67fb9ece4c087ba7b1bc52e61b78b94586c
-2026-07-21-log-backed-session-titles.zh.md: 4df21be565f57db056f506df477f665908d1fdfa
+2026-07-21-log-backed-session-titles.zh.md: 21a0ec5dc9cc90726dda502ba46a52d717c39df5
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index 4df21be565..21a0ec5dc9 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -53,7 +53,7 @@ Status: implemented
 - **将标题放入派生历史记录或请求前缀**：不予采纳，因为 UI 元数据会消耗 token、改变缓存标识，并让主模型观察到自己的标签。纯日志事件既保持可重建，又不会变得对模型可见。
 - **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
 - **静默截断过大的辅助输入**：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
-- **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取契约，而没有提前锁定搜索或索引策略。
+- **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取约定，而没有提前锁定搜索或索引策略。
 - **让 Web host 只使用回退标题**：不予采纳，因为 UI 虽会显示持久标题，却始终无法将第一条提示词的前缀改进为更好的标题。首消息提供方在主响应路径之外运行，并让模型摘要成为 Web 的默认结果。
 
 ## 后果
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index e4df6863da..538e89e047 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
 2026-07-22-durable-subagent-catalog-and-list-agents.md: 61bda2a52f2ea5db0a582fe668643a13b967f091
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a2bc36200d8c67b8da9dd3d55ea4179baa72e691
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: 6b5bff468349df4226aaf76dd7ed7d9ce5c3f33c
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index a2bc36200d..6b5bff4683 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 可继续的后台 subagent 会公开稳定的 child id，并将重建数据持久化在该 child 的会话中，因此 `send_message` 无需任何列表查询操作即可恢复已知 child。发现功能有两类需求不同的消费方：UI 可以同时展示一次性工作和可继续对话，而模型只应收到适合使用 `send_message` 的 child。[可继续 subagent](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)负责持久化 Session 与 Activation 设计；本记录负责共享的持久化清单及面向模型的投影。
 
-枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。契约还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载大量 child 日志会如何影响服务与工具消费方。
+枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。约定还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载大量 child 日志会如何影响服务与工具消费方。
 
 ## 决策
 
@@ -23,19 +23,19 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 - 将语料活动状态单独报告为 `running` 或 `inactive`，但不暗示已完成或可恢复；
 - 按 `createdAt` 升序、再按 child id 升序稳定返回所有结果 child。
 
-每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
+每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 约定负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
 
 ### 枚举决策
 
 第一版消费 `ctx.sessionQuery.traceSession(parentSessionId)`，并且只考虑追踪结果的第一层后代。目标可以存活，也可以只存在于持久化存储中；追踪逻辑语料不会加载或恢复 Agent。会话查询已经使用实时优先规则合并 `ctx.sessions` 与 `ctx.sessionPersistence`，保持不可变 header 一致性，根据 `SessionHeader.parentSession` 推导直接 child 谱系，并按 `createdAt` 升序、child id 升序排列 sibling。`listChildren()` 不会重复实现这套语料逻辑，也不会检查继续执行管理器的进程内 Activation map。
 
-语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 契约中的“损坏 child”是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
+语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 约定中的“损坏 child”是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
 
 会话谱系涵盖的范围比 subagent 身份更广：普通 `ctx.sessions.fork()` 也会创建直接 child。会话 header 不新增 `kind` 判别字段；每个候选必须改为在自身后缀中恰好包含一个有效的 `subagent/descriptor` 事件。`SubagentService.start()` 会在普通提供方分发前解析 `{ mode: 'one-shot', provider, label? }`，而继续执行管理器会在初始创建 child 时为 `{ mode: 'continuable', ...composition }` 建立快照并将其作为 seed。本地进程内的一次性驱动只在初始创建期间追加已解析的描述符，从持久化存储冷恢复时不会追加其他描述符；第二个事件属于损坏，而不是另一次 Activation 的证据。Agent 创建是一次性运行的发布边界：拒绝表示没有发布 child，而发布后的提示词、轮次、取消与基础设施结果会通过返回的 run 结算，且不会隐藏其 id。描述符事件是已追踪 child 属于由会话支撑的 subagent 的唯一证据。缺少该事件的候选属于普通 fork、没有本地会话记录的远端 child 或其他非 subagent 会话，系统会将其排除且不产生 diagnostic。
 
 已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose 或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
 
-subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时契约。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
+subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时约定。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
 
 `listChildren(parentSessionId, signal?)` 会把调用方的取消信号转发给 `traceSession()` 和条件性精确 `readEvent()` 操作。`listEvents()` 不接受取消参数，因此列表查询路径会在等待该操作的前后，以及每个候选处理完成后检查信号。如果取消信号触发后有查询操作以拒绝结算，服务会将结果归一化为 `SubagentError`，并携带稳定错误码 `CANCELLED`；后端中止错误或可映射为 diagnostic 的查询错误均不会逃逸，也不会使调用以成功的部分列表返回。
 
@@ -43,7 +43,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 如果实测规模日后需要索引，该索引属于派生状态：会话 header 和 child 描述符仍是权威信息，重建或损坏回退必须复现相同结果。索引不能成为第二个鉴权来源，也不能让尚未发布的 child 变得可见。
 
-### `list_agents` 契约
+### `list_agents` 约定
 
 `SubagentService.listChildren(parentSessionId: SessionId)` 返回 `Promise<SubagentListEntry[]>`，其中的单个数组不会将 child 与 diagnostic 分开，而是保留追踪结果中的候选顺序。`SubagentListEntry` 是一个由只读 `kind` 判别的封闭联合类型：
 
@@ -52,7 +52,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
 在已被取代的追踪读路径中，diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
@@ -80,13 +80,13 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 **持久化 parent 会话目录事件。** 直接 child header 已经提供持久化枚举种子，child 描述符则是重建的权威信息。第二份 parent 日志会重复状态，并造成跨会话顺序和陈旧条目行为，却无助于按 id 恢复。
 
-**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动契约。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
+**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动约定。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
 
 **某个 child 无法加载时让整次列表查询失败。** 这种做法不会让损坏问题被忽略，但一个损坏的 sibling 会让每个健康 child 都不再可见。逐 child diagnostic 在保持每次排除明确可见的同时，也保留了发现能力。
 
 **分别返回 child 和 diagnostic 数组。** 分离的数组会引入两个排序域，或者要求公开另一个排序键才能重建候选顺序。一个带判别字段的条目数组既能保留追踪顺序，也能保证 child 与 diagnostic 字段的类型安全。
 
-**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 契约，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
+**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 约定，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
 
 **立即为查询分页或设置上限（暂缓）。** 这可以限制一次结果的大小，但会使模型发现成为有状态操作，而且除非模型继续跟随 cursor，否则可能隐藏更早的 child。第一版没有 cursor、分页参数或候选数量上限配置，而是返回经稳定排序的完整集合；如果实测规模需要限制，服务级限制仍留待后续决策。
 
@@ -94,7 +94,7 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
 - `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载契约，以及 HMR dispose。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载约定，以及 HMR dispose。
 - 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
 - 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
diff --git a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml
index f5a469377b..ac5e4cb4c6 100644
--- a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-web-bind-address.md
 2026-07-22-web-bind-address.md: 3332176c0cee940648ad334a44edd30879225503
-2026-07-22-web-bind-address.zh.md: 5a8c49461b90abfd2476a56d7d148cdaaacd01e3
+2026-07-22-web-bind-address.zh.md: 5ad73b8916d9cedce1073f4a2d025f40197b7d65
diff --git a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md
index 5a8c49461b..5ad73b8916 100644
--- a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md
@@ -12,7 +12,7 @@ HTTP 承载层还把绑定地址隐藏在 `startWebServer()` 内部，导致其
 
 ## 决策
 
-`dsh web` 默认绑定 `127.0.0.1`。CLI（命令行界面）接受 `--host 0.0.0.0` 作为显式启用的全接口模式，并拒绝其他取值，使网络模式保持为一份规模小、经过审慎限定的契约。全接口模式仍然输出本机环回 URL，并在可用时输出第一个外部 IPv4 URL。
+`dsh web` 默认绑定 `127.0.0.1`。CLI（命令行界面）接受 `--host 0.0.0.0` 作为显式启用的全接口模式，并拒绝其他取值，使网络模式保持为一份规模小、经过审慎限定的约定。全接口模式仍然输出本机环回 URL，并在可用时输出第一个外部 IPv4 URL。
 
 `WebServerOptions.host` 为必填项。HTTP 承载层将该值直接传给 `node:http`，不提供回退值，因此每个壳层负责制定自己的绑定策略。以编程方式使用承载层的消费方可以直接选择其他主机名或地址。
 
@@ -26,4 +26,4 @@ HTTP 承载层还把绑定地址隐藏在 `startWebServer()` 内部，导致其
 
 ## 后果
 
-`dsh web` 的本地启动仍可通过 `http://127.0.0.1:3080` 访问；其他机器上的浏览器必须使用 `dsh web --host 0.0.0.0` 显式启用。CLI 尚未开放自定义接口地址或 IPv6 模式，而以编程方式使用承载层的消费方仍保留这种灵活性。服务器测试将环回模式和全接口模式向 Node 监听边界的传递固定为契约，Web 冒烟测试继续覆盖默认 CLI 路径。
+`dsh web` 的本地启动仍可通过 `http://127.0.0.1:3080` 访问；其他机器上的浏览器必须使用 `dsh web --host 0.0.0.0` 显式启用。CLI 尚未开放自定义接口地址或 IPv6 模式，而以编程方式使用承载层的消费方仍保留这种灵活性。服务器测试将环回模式和全接口模式向 Node 监听边界的传递固定为约定，Web 冒烟测试继续覆盖默认 CLI 路径。
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index be9c014650..ee8d4ca6af 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
 2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
-2026-07-23-session-telemetry-otel-revival.zh.md: 1d607ce9a3b77ae96664af72599beacb34fd9b47
+2026-07-23-session-telemetry-otel-revival.zh.md: b97840405bbde35f3b6b7f417b0615774fe43061
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index 1d607ce9a3..b97840405b 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-每个想把 harness 会话接入可观测性体系的部署方都得手写一套会话日志消费方：订阅、生命周期交接、以及最难的脱敏——原始日志携带文件内容与命令输出，可能内嵌凭据。遥测 seam 和 OTel 后端曾在 `session-telemetry-otlp-rfc` 分支（PR #222/#231）上完成过一版，但从未进入 master：该提案将原始会话事件原样导出，法务评审未予通过。捕获侧设计（后端契约、coordinator、handoff 游标、分片投影）本身合理且经过评审；导出侧的立场才是阻塞点。
+每个想把 harness 会话接入可观测性体系的部署方都得手写一套会话日志消费方：订阅、生命周期交接、以及最难的脱敏——原始日志携带文件内容与命令输出，可能内嵌凭据。遥测 seam 和 OTel 后端曾在 `session-telemetry-otlp-rfc` 分支（PR #222/#231）上完成过一版，但从未进入 master：该提案将原始会话事件原样导出，法务评审未予通过。捕获侧设计（后端约定、coordinator、handoff 游标、分片投影）本身合理且经过评审；导出侧的立场才是阻塞点。
 
 ## 决策
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**实现 runtime-telemetry RFC 的 outbox（落盘 spool、每 sink 游标、at-least-once、持久化 seam 的 `readCommitted` 方法）。** 推迟而非否决：SDK 立场使投递语义归属 reporting SDK，OTel SDK 自身的批处理流水线是诚实的默认。outbox 是纯增量层（`emit()` 契约不动）；待某个部署提出遥测必须满足的崩溃丢失要求时再复活。
+**实现 runtime-telemetry RFC 的 outbox（落盘 spool、每 sink 游标、at-least-once、持久化 seam 的 `readCommitted` 方法）。** 推迟而非否决：SDK 立场使投递语义归属 reporting SDK，OTel SDK 自身的批处理流水线是诚实的默认。outbox 是纯增量层（`emit()` 约定不动）；待某个部署提出遥测必须满足的崩溃丢失要求时再复活。
 
 **不设进程内脱敏点，交给接收端 collector processor。** 否决——接收端脱敏是先把秘密发出去再擦除。waterfall 在字节离开进程前提供一个可审计、可堆叠的擦除点；分支版本（PR #222 交付的形态）完全没有脱敏点，如今每条记录都必经该脱敏点。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
index e78ab9abbd..544870a5da 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
 2026-07-23-web-assistant-markdown.md: ad86559e3b5294b6bd67d69ff5c6ce37a5172008
-2026-07-23-web-assistant-markdown.zh.md: b47375db843ea1c81b913e3f7ac8cd1bbc278830
+2026-07-23-web-assistant-markdown.zh.md: e7544b2c731581e29b026026a2bb627defb91ca7
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
index b47375db84..e7544b2c73 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
@@ -12,7 +12,7 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd
 
 `@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`，用作不受信任的 assistant 文本渲染器；`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`，因此无需更改事件或快照，它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`，并保持按字面渲染。
 
-`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性契约）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
+`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性约定）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
 
 视觉间距、表格、链接、引用块、行内代码与代码块外框遵循 deepsuite `@deepseek/md`（`markdown.css` / `code-block.css`），并使用同一套 `--dsw-alias-markdown-*`、`--dsw-font-markdown-*`、`--dsw-alias-border-l*` 与 `--dsw-alias-label-*` token。链接使用 `--dsw-alias-state-business-primary`（deepsuite 的样式表使用 `--dsw-alias-brand-text`，仅在 newDesign 下为蓝色；design-platform 将 brand-text 保持为近黑色，此处不做重新调色）。当单个行内代码 token 完全由绝对 HTTP(S) URL 构成时，其代码外框会包含一个与普通链接相同、可通过键盘聚焦的安全外链锚点；端口、路径与查询文本保持不变，而命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。`CodeBlock` 提供语言横幅与复制控件（`复制` / `复制成功`）。已完成的文本通过定稿语法的数学扩展渲染 KaTeX；`mathCompatibility` 将 `\(...\)`、`\[...\]` 和块级同一行 `$$...$$` 映射为同一套标准数学 AST 节点。这是一层小范围的解析器兼容层，不是正则重写，也不修复格式错误的模型输出。流式输出在完成前保持按字面渲染，避免不完整公式闪现错误。引用胶囊、标题锚点、thinking-small markdown 变体，以及自定义 □/☑ 任务标记仍不在范围内；GFM 任务列表继续使用原生复选框。
 
@@ -34,7 +34,7 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
 
 **通过净化启用原始 HTML。** 原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。
 
-**移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 契约。
+**移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 约定。
 
 **为处理 CJK 标点边界而预处理 Markdown 源文本，或在解析后修复文本节点。**源文本重写必须在解析器掌握这些区别之前复现转义、代码、数学公式与定界符规则；文本节点修复则已经丢失部分源文本意图，也无法与已解析的行内节点组合。在分词器边界扩展 attention 可保留上游 resolver，并将差异限制在定界符的适用条件上。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
index 3c006bc9f1..01b96211a7 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.md
 2026-07-23-web-permission-and-approval.md: 06e184fe32ac684e3d8b0820d915ca7c372a5760
-2026-07-23-web-permission-and-approval.zh.md: b74e93006cb95c398eb464a9bd9a59e8c9cc57be
+2026-07-23-web-permission-and-approval.zh.md: c662f126c41b2e581bc39319f0e5569d364d7aec
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
index b74e93006c..c662f126c4 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
@@ -6,21 +6,21 @@ Status: implemented
 
 ## 问题
 
-Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议契约其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
+Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议约定其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
 
 ## 决策
 
 Web 承载层组合与 acp-agent 相同的沙箱化产品路径：`dsh-sandbox-local`、`dsh-sandbox-policy`、`dsh-bash-sandbox`、`dsh-fs-sandbox`、`dsh-user-approval` 与 `dsh-permission`，由 `BootHostOptions.sandbox` 提供部署默认值（`mode`，默认 `workspace-write`；`approvalPolicy`，默认 `ask`）。
 
-`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题 mint 一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是契约早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，解析应答者，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
+`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题 mint 一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是约定早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，解析应答者，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
 
 权限选择依托两个新的一元 RPC，`session.permissions` 与 `session.setPermission`，把 `ctx.permission` 投影为一个由协议拥有的 `PermissionOption` DTO（沿用 ACP bridge 的先例：每个协议拥有自己的呈现形状）。无权限的组合提供空的选择项，client 隐藏该控件。空闲期的切换以后写胜出（last-write-wins）的方式保存在 proxy 侧的 pending map 中，并在 `agent/pre-step` 时冲刷，因为旋钮事件必须保持轮次内闭合以支持持久回放；共享的 `hasOpenTurn` 折叠迁入 `dsh-session`，取代了 `dsh-user-approval`、ACP bridge 与 proxy 中各自的私有副本。
 
-在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 契约中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
+在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 约定中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
 
 ## 曾考虑的替代方案
 
-**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 契约的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
+**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 约定的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
 
 **用一个会话事件承载 pending 交互，而非实时注册表。** 不予采纳：可应答请求是瞬态的交互状态，而非持久的会话数据——审批的 `approval/asked`/`decided` 审计对已经记录了持久的那一半。持久化 requested 帧会在回放时重新问出已经作废的问题。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
index f90cfe79db..5c05f0b86d 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-todo-display.md
 2026-07-23-web-todo-display.md: bb66ef8512badea090b3b22030eef3f43f3b1119
-2026-07-23-web-todo-display.zh.md: 7270874d1e96bb0a553d57ba24b3bc2bb38a7a71
+2026-07-23-web-todo-display.zh.md: 5b3534e20956a4412814a782532d1337c08ff027
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
index 7270874d1e..5b3534e209 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ### 副作用通道，与窗口回放收敛
 
-`applyEventSideEffects` 新增一个 `todo/write` 分支（整份列表，后写覆盖先写），并在 `turn/start` 清空（[按轮次界定的计划生命周期](2026-07-28-todo-plan-clears-on-next-turn.md)）。`rebuildDerivedFromWindow` 从空计划扫过窗口，仅当窗口从未判定计划（无 `todo/write` 且无 `turn/start`）时恢复尾页种子；否则以窗口内写入／`turn/start` 折叠为准。`installWindow` 的每个调用方都是尾页请求（`doOpen`、其补洞重拉、`repairGap`；`loadOlder` 只往前拼接、不再播种），而 host 对尾页请求要么带上投影、要么在没有当前有效的计划时省略——因此字段缺失就是权威的空列表，直接照此赋值。这个区分在回滚场景上要紧：若 host 在持久化实时写入前崩溃，log 里就是空的，此时保留旧值会让已回滚的计划永远留在屏幕上。`ConversationSnapshot.todos` 是读取面。这遵循事件自身的契约（「仅存在于日志中的 UI 状态；绝不纳入派生历史」）：把每次写入作为对话节点呈现，会让已被取代的列表看起来仍然有效。
+`applyEventSideEffects` 新增一个 `todo/write` 分支（整份列表，后写覆盖先写），并在 `turn/start` 清空（[按轮次界定的计划生命周期](2026-07-28-todo-plan-clears-on-next-turn.md)）。`rebuildDerivedFromWindow` 从空计划扫过窗口，仅当窗口从未判定计划（无 `todo/write` 且无 `turn/start`）时恢复尾页种子；否则以窗口内写入／`turn/start` 折叠为准。`installWindow` 的每个调用方都是尾页请求（`doOpen`、其补洞重拉、`repairGap`；`loadOlder` 只往前拼接、不再播种），而 host 对尾页请求要么带上投影、要么在没有当前有效的计划时省略——因此字段缺失就是权威的空列表，直接照此赋值。这个区分在回滚场景上要紧：若 host 在持久化实时写入前崩溃，log 里就是空的，此时保留旧值会让已回滚的计划永远留在屏幕上。`ConversationSnapshot.todos` 是读取面。这遵循事件自身的约定（「仅存在于日志中的 UI 状态；绝不纳入派生历史」）：把每次写入作为对话节点呈现，会让已被取代的列表看起来仍然有效。
 
 ### TodoPanel：持久化列表作为一条常驻横条
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
index b11dc50cd6..e90a23fd2e 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
 2026-07-24-model-facing-session-query-tools.md: 863f557f11f89ff8dfc121b7da0b653852528394
-2026-07-24-model-facing-session-query-tools.zh.md: d8deaba15f111537a16deafe73ed6dd708ea044a
+2026-07-24-model-facing-session-query-tools.zh.md: 2acbf44b42aafd2eac37903e1acbefc5ba098377
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
index d8deaba15f..2acbf44b42 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `@deepseek-ai/dsh-tool-session-query` 是 `ctx.sessionQuery` 面向模型的消费者。它注册五个职责单一的只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`。该包依赖接口而非 SQLite 实现，负责模型参数校验与易读文本渲染，并贡献一个精简的提示词段，说明历史搜索以及从搜索转向追踪／读取的工作流。
 
-该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包契约。
+该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包约定。
 
 `session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接来源关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml
index 7718957ab6..c70efe3121 100644
--- a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md
 2026-07-24-provider-retry-policies.md: 1831ce6b96178d11e7c9927ceccbe07ea578cd2c
-2026-07-24-provider-retry-policies.zh.md: d44f954d75a09a40988655ef486733dc2ac6f58c
+2026-07-24-provider-retry-policies.zh.md: 22f18badcb47e4ce086ff2c68c7011612b2eabba
diff --git a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md
index d44f954d75..22f18badcb 100644
--- a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md
@@ -48,7 +48,7 @@ always 模式先请求下游恢复，使上下文溢出压缩（compaction）之
 
 **在 `dsh-llm-retry` 上维护单独的指定提供方列表**：不予采纳，因为它会在所属适配器配置之外重复提供方路由名称，并让提供方注册与恢复策略发生偏差。
 
-**设置很大的有限重试次数**：不予采纳，因为它最终仍会违反持续重试的契约，并把任意选取的运维上限序列化成看似有意义的数值。
+**设置很大的有限重试次数**：不予采纳，因为它最终仍会违反持续重试的约定，并把任意选取的运维上限序列化成看似有意义的数值。
 
 **使用提供方 SDK 重试**：不予采纳，因为隐藏尝试会叠加 agent 层预算，无法利用已关闭步骤的持久性边界，还可能在没有可重建重试记录的情况下拼接或丢弃流式输出。
 
@@ -60,6 +60,6 @@ always 模式先请求下游恢复，使上下文溢出压缩（compaction）之
 
 ## 后果
 
-normal 模式仍是有限的默认策略；显式的 always 策略可能在永久性的身份验证、配额、无效请求、协议或上下文错误上耗费无限次请求和无限时间。运维方必须为 always 模式配备可取消的调用方和针对提供方的成本控制。重试状态保持可观察且会持久化，但不会对模型可见；捕获实际提供服务的注册项，也能防止适配器生命周期变化反过来改变进行中请求的恢复契约。
+normal 模式仍是有限的默认策略；显式的 always 策略可能在永久性的身份验证、配额、无效请求、协议或上下文错误上耗费无限次请求和无限时间。运维方必须为 always 模式配备可取消的调用方和针对提供方的成本控制。重试状态保持可观察且会持久化，但不会对模型可见；捕获实际提供服务的注册项，也能防止适配器生命周期变化反过来改变进行中请求的恢复约定。
 
 本决策扩展了[瞬态 LLM（大语言模型）请求失败的有界恢复](../architecture/2026-06-21-bounded-llm-request-recovery.md)中确定的已关闭步骤恢复、单次可见适配器尝试、结构化失败与持久化状态设计。
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
index fe955d125d..cad70622c8 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
 2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9
-2026-07-25-session-list-browsing-and-manual-order.zh.md: 8ec5f71943a68a70f46fbd4c7702e4556b1892ec
+2026-07-25-session-list-browsing-and-manual-order.zh.md: 2bf778284aa551c75f1206ed08ca073e47b7a15d
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
index 8ec5f71943..2bf778284a 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
@@ -34,7 +34,7 @@ UI 为组内 session 行的 HTML5 拖拽(仅 workspace 分组、非搜索态；f
 
 ### 壳/区域切分
 
-ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settings,以及一个 `sidebar.workspaces` 洞;壳与区域的契约只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域(section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽)及其 groupBy store;rail 态的搜索/添加工作区图标也归区域,经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`(区域内直接组件组合;在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`)与薄包装 `WorkspacePicker`(继续填 ui-conversation 的 hero 坑);原 `sidebar.workspace` picker 坑与声明感知延迟注册随之删除。
+ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settings,以及一个 `sidebar.workspaces` 洞;壳与区域的约定只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域(section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽)及其 groupBy store;rail 态的搜索/添加工作区图标也归区域,经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`(区域内直接组件组合;在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`)与薄包装 `WorkspacePicker`(继续填 ui-conversation 的 hero 坑);原 `sidebar.workspace` picker 坑与声明感知延迟注册随之删除。
 
 ## Alternatives considered
 
@@ -50,8 +50,8 @@ ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settin
 
 ## Consequences
 
-- 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 契约随之改为手动序措辞。
-- 壳/区域两事实契约把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。
+- 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 约定随之改为手动序措辞。
+- 壳/区域两事实约定把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。
 - 平铺模式不支持排序与分组入口(建到指定 workspace 需切回分组视图),是拍板接受的范围收窄。
 - session Delete 的功能接线与状态枚举扩 wire,留待后续迭代。
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
index d8232afa44..6c4d70b005 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
 2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166
-2026-07-25-workspace-ui-product-flow.zh.md: a40f374fd794b11bff0de72cbc822fd638cd267c
+2026-07-25-workspace-ui-product-flow.zh.md: 372339331bdf2ee5f7c63abd1cc056ae37b16f78
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
index a40f374fd7..372339331b 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
@@ -116,6 +116,6 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe
 
 - SessionHeader 不记录最后活跃时间，历史 bootstrap 只能按 `createdAt` 初始化；此后由真实 Session 活跃事件逐项前移。
 - 历史 cwd 缺失、目录无效或 realpath 失败的 Session 留在 Ungrouped；本期没有手动收编入口。
-- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 契约。
+- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 约定。
 - 显式 Create Workspace 立即落盘，用户不发送就离开也会留下空 Workspace。
 - Host Session 在首个事件前仍遵循现有懒持久化语义；前端 Intent 不改变 Host 重启后的空 Session 行为。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
index d2ffd775a4..f8ccab3362 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
 2026-07-26-code-dispatch-ui-foundation.md: a1629c77304bc7ef744f7a09241bcdfc81e461ae
-2026-07-26-code-dispatch-ui-foundation.zh.md: d49b6956f75356511ca3b0f9f2e88b42629230f6
+2026-07-26-code-dispatch-ui-foundation.zh.md: 8f40281454e78d3d1baaf0dce3635bdf01d0a658
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
index d49b6956f7..8f40281454 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
 
-> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧契约变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
+> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
 
 ## 问题
 
@@ -14,7 +14,7 @@ Status: implemented
 
 三项变更，每项对应一个障碍：
 
-1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的契约：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、Web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
+1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的约定：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、Web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
 2. **`tool/code-dispatch` 记录子调用面向模型的完整结果**（`content: ContentBlock[]` 加 `isError`，即 `tool/result` 的词汇），取代 `resultSummary`，并把摘要与 cwd 归一化机制彻底删除。UI 渲染子调用走的代码路径与渲染原生结果完全相同，包括错误文本和非文本块。该事件保持仅日志（`deriveMessages()` 忽略它）：模型上下文没有任何变化。
 3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的 seam：设计目标是让 Web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 **一个 `--tools-mode` CLI（命令行界面）标志或 profile 配置键。** 推迟，而非否决：标志语法暗示永久性，profile JSON 又是用户配置；两者都会固化这个 seam，而按会话选择的设计本就打算移除它。环境变量则如实呈现了它权宜之计的本质。
 
-**记录规范 `value`，而非渲染后的 `content`。** 否决：`tool/result` 持久化的是内容而非值（见[规范输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)），与原生同等保真意味着与之精确对齐；值始终仅存在于执行期本地。
+**记录规范 `value`，而非渲染后的 `content`。** 否决：`tool/result` 持久化的是内容而非值（见[规范输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)），与原生同等保真意味着与之精确对齐；值始终仅存在于执行期本地。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
index ed15fd5c36..2b12308db9 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
 2026-07-26-code-mode-live-parallel-dispatch.md: e85d1f99f58f1aae28091cd8875ee87a6df5a1e7
-2026-07-26-code-mode-live-parallel-dispatch.zh.md: 39da98d9c3630d549f13df0ea555687614f3065a
+2026-07-26-code-mode-live-parallel-dispatch.zh.md: c7f91f570e20e27aade0e8f47606d31b1d8ae7eb
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
index 39da98d9c3..c7f91f570e 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
@@ -1,10 +1,10 @@
-# Agent Note: Code Mode 的实时分发生命周期，以及复用原生契约的并行执行
+# Agent Note: Code Mode 的实时分发生命周期，以及复用原生约定的并行执行
 
 Status: implemented
 
 [English](2026-07-26-code-mode-live-parallel-dispatch.md) | 中文
 
-> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发契约的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生契约本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
+> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发约定的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生约定本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
 
 ## 问题
 
@@ -12,12 +12,12 @@ Status: implemented
 
 ## 决策
 
-**一对生命周期事件，一份调度契约，与原生共用。**
+**一对生命周期事件，一份调度约定，与原生共用。**
 
 - **事件对**：`tool/code-dispatch-start`（父/子 id、名称、规范化参数）在调度器真正启动某个调用时才追加，而非在提交时，因此因 run 结算而被放弃的排队调用不会留下任何日志。既有的 `tool/code-dispatch` 结算该事件对（`subCallId` 相同）；每个已启动的调用恰好结算一次（中止也会作为 `isError` 结果经由流水线结算）。计时即这两个事件的 `time` 字段。两个事件都保持仅日志；模型上下文不受影响；格式保持 v0。
-- **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同、故障时默认判为不安全的 `isConcurrencySafe` 契约），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单通道驱动器独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
+- **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同、故障时默认判为不安全的 `isConcurrencySafe` 约定），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单通道驱动器独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
 - **客户端侧**：运行时的 `ToolCallTree` 把 start 事件存为 `RunningToolCall` 子级，并通过父级递归的 `subCalls` 投影出来（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致）。其结算事件会原位替换私有索引中的条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
-- **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实契约（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 Code Mode 快照都已重新录制。
+- **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实约定（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 Code Mode 快照都已重新录制。
 
 ## 曾考虑的替代方案
 
@@ -25,7 +25,7 @@ Status: implemented
 
 **在提交时而非入池时发出 start 事件。** 否决：提交即发 start 会把排了队却从未运行的调用显示成「运行中」，还得强行引入第三种「已放弃」终态事件才能使日志自洽。入池才发 start 保住了*已启动 ⇔ 恰好结算一次*这一不变式，且不需要第三种事件。
 
-**直接复用 loop 调度器的实现。** 否决：loop 调度的是一个已完整解析的批次，并按模型顺序提交结果；桥接层调度的则是一条开放式的提交流，其结果返回给程序，而不是进入 transcript（文本记录）。因此两者共享的只是*契约*（分类、池、屏障），而不是实现机制。
+**直接复用 loop 调度器的实现。** 否决：loop 调度的是一个已完整解析的批次，并按模型顺序提交结果；桥接层调度的则是一条开放式的提交流，其结果返回给程序，而不是进入 transcript（文本记录）。因此两者共享的只是*约定*（分类、池、屏障），而不是实现机制。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 8a92dd2fd1..451447736a 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
 2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: 26b7081e7b4e3688a46a2857da91ba45328532a9
+2026-07-26-todo-parallel-in-progress.zh.md: 3d86a32fbd0d17d802a9f6d69ab49176a808c72f
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 26b7081e7b..3d86a32fbd 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -47,7 +47,7 @@ Status: implemented
 
 ## 暂缓项
 
-两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试契约的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
index dade9b5d90..e433908f1f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.md
 2026-07-27-native-workspace-directory-picker.md: a36f7b239a9115fe5eb33472ec5084818a66e9f2
-2026-07-27-native-workspace-directory-picker.zh.md: bb3e2fc6f7c77c8ace97e53435297326f937e4e8
+2026-07-27-native-workspace-directory-picker.zh.md: cf30b4810fe5dc4d0ecfe30cd5eaf4b75ce3c23c
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
index bb3e2fc6f7..cf30b4810f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 工作区管理器必须在选择回调运行前插入或更新返回的工作区。因此，新纳入的目录会立即显示其 basename。再次打开已注册的路径时，则保留该工作区现有的标题。
 
-## 交互契约
+## 交互约定
 
 - 在 macOS、Windows 和 Linux 上，选择器一次只允许选择一个目录。
 - 取消系统对话框不会显示提示，并返回 `null`。
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
index b0e6012183..f65d3be4a5 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md
 2026-07-27-skill-catalog-hot-refresh.md: 43c2da75aeb0031dffb5f47d7e76805baa2920e5
-2026-07-27-skill-catalog-hot-refresh.zh.md: 04d39dd767e5438c57d3eb29523a8ff26592465c
+2026-07-27-skill-catalog-hot-refresh.zh.md: e33e4adafcc664a22560dd2d5da1d9b7a890479a
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
index 04d39dd767..e33e4adafc 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
@@ -36,7 +36,7 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - **监视每个 bundle 资源**：不予采纳，因为参考资料、脚本和产物都是按需加载的，不影响类别列表。宽泛的递归监视会增加失效、描述符压力和平台差异，却不能改善路由。
 - **将部分发现或失败发现发布为新目录**：不予采纳，因为暂时读取失败不能证明文件已删除。完整性位让面向模型的消费方保留最后一次完整目录，直到完整观察成功。
 - **保留公开的 `invalidateProvider(provider)`**：不予采纳，因为这会公开一项注册表变更方法，并要求调用方重复提供注册表已经持有的身份。发给工厂的闭包会将失效绑定到单个注册，并在释放后失去作用，因此观察方既不需要访问注册表，也不需要提供方身份。
-- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务契约。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
+- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务约定。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
 
 ## 影响
 
@@ -44,5 +44,5 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - TUI 的 `/skill:` 补全会收敛到同一份完整目录，而不会让每次按键都阻塞于发现；打开的斜杠命令名称草稿会在目录到达时刷新。
 - 目录消息采用仅追加、日志记录和全量列表快照。它们会保留较早的可重用 token；替换目录会显式停用陈旧名称，每次 digest 实际变化时，token 成本与当前目录大小成正比。
 - 仅修改正文不会产生目录消息。后续工具调用会看到当前内容，而先前工具结果仍准确记录模型之前加载的内容。
-- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁契约会限制这些成本。
+- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁约定会限制这些成本。
 - 远程或未来的可变提供方会保留各自注册作用域内的失效闭包，并通过自身观察机制调用它；注册表不会强制采用通用 watcher 或 TTL。
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
index 71c2325bb3..37c876275c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
 2026-07-27-trajectory-inspection-ledger.md: e3fc22234c1df449c99eac90af27de7da0b6f202
-2026-07-27-trajectory-inspection-ledger.zh.md: abf8fd3bcaeabba6061bd415acbe8ddefef7ac79
+2026-07-27-trajectory-inspection-ledger.zh.md: f167d818281c39a06e658c294f45e47d3ba40642
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
index abf8fd3bca..f167d81828 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
@@ -53,4 +53,4 @@ Status: implemented
 
 ## 后果
 
-轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表契约锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
+轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index 38dc165e7f..e3e6e045f8 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
 2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: c5c6c4eac053e9a3adfa2a2a441ac492ba3391ac
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 643ec36134a1ebe940da5de5b373fa0c25afcd42
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: fe0e93cd13d0decb8d6a95abb0c5feb141dcb78b
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index 643ec36134..fe0e93cd13 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -34,7 +34,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 **让 `subagent-dsh-sdk` 直说裸 JSON-RPC、绕开客户端 SDK。** 会复制 SDK 存在意义所在的请求/通知配对、订阅扇出、超时与拆除逻辑；用户的要求明确是一个*使用* SDK 的后端，分层的回报是后端成为可复用客户端之上约 200 行的纯策略。
 
-**把 SDK 后端折进 `subagent-acp`、用传输开关区分。** 两个后端共享子进程生命周期，但线协议（ACP SDK 连接 vs harness JSON-RPC）、子进程契约（任意 ACP 代理 vs harness 运行时）、结果提取（`agent_message_chunk` 累积 vs 会话事件读取）毫无共享。配置判别子会把两个协议埋进一个包；真正共享的 provider 侧部分移入 subagent seam 的 `out-of-process.ts`，进程机制则住在 `dsh-subprocess` seam。
+**把 SDK 后端折进 `subagent-acp`、用传输开关区分。** 两个后端共享子进程生命周期，但线协议（ACP SDK 连接 vs harness JSON-RPC）、子进程约定（任意 ACP 代理 vs harness 运行时）、结果提取（`agent_message_chunk` 累积 vs 会话事件读取）毫无共享。配置判别子会把两个协议埋进一个包；真正共享的 provider 侧部分移入 subagent seam 的 `out-of-process.ts`，进程机制则住在 `dsh-subprocess` seam。
 
 **给 TS SDK 与 Python 对等的捆绑运行时解析。** Python 的载体解析是为了给没有 Node 的用户发 wheel。TypeScript 消费方按定义就有 Node，且仓库内消费方还有工作区；为尚不存在的消费方编造发行方案违反「只实现当前需求」的规则。推迟到真实的 npm 发行消费方出现时再处理。
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
index 5268ea62f9..077613e488 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md
 2026-07-27-web-session-fork-actions.md: 578e59ec92e003fe5c8cdfe951a595f3a7371ecf
-2026-07-27-web-session-fork-actions.zh.md: d90124f6e6e164b0a1e0fce734f52976630cd848
+2026-07-27-web-session-fork-actions.zh.md: eb29b4358aefeb32c0ec291e1fac1948e2b0ec9d
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
index d90124f6e6..eb29b4358a 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互契约。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
+Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互约定。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
index 7701e5fcc7..de5df14b25 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-session-search.md
 2026-07-27-web-session-search.md: 4c49c0e61ca1b15181e767e4f65353312f8a3e3f
-2026-07-27-web-session-search.zh.md: e9aa00656443e544bad623540d07ff785b1285ef
+2026-07-27-web-session-search.zh.md: d4b06ec306ab8a4f6759f007cc133622e4cb63ee
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
index e9aa006564..d4b06ec306 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
@@ -10,7 +10,7 @@ Web 侧边栏会展示会话标题及其 Workspace 归属，但无法根据只
 
 ## 决策
 
-Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者契约，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
+Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者约定，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
 
 宿主网关通过现有的类型化 RPC 栈公开 `session.search`。它根据 `session.list` 使用的同一组可见摘要推导授权集合，向 `ctx.sessionQuery.searchSessions` 请求全局排序后的当前 surface `user/message` 和 `assistant/message` 匹配项，并持续消费提供方分页，直到获得 20 个已授权会话及一个前瞻项，或结果流耗尽。首个提供方页面请求 20 个命中；如果第一页返回 `SESSION_QUERY_INVALID_LIMIT`，页面大小会依次折半为 10、5、2、1，并在续传和陈旧世代重启中沿用探测所得的大小。每个命中的会话 id、最佳匹配会话 id、surface 和事件类型都会经过重新校验，其 snippet 才能离开宿主。发出的 snippet 最多包含 240 个 Unicode 码点；宿主与传输 schema 共用协议边界及码点安全的截断辅助函数，而传输 schema 会在客户端解析时独立强制执行 snippet 上限。将可能很大的授权集合排除在 SQLite 绑定之外，可避开可移植变量上限，同时保持全局排序。响应仍只有一个有界页面；`hasMore` 会指示 UI 提示用户缩小查询范围，而不是公开分页能力。陈旧的续传会丢弃当前尝试的部分结果、去重条目和游标，然后依据原始可见性快照从第一页重新开始。上限探测与陈旧重试共用 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果某页命中数超过其请求的上限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体信号会取消已被取代的工作，包括持久化列表枚举、分批受限执行的冷会话元数据 stat，以及每一次提供方调用；即使同时收到上限拒绝或陈旧拒绝，也以取消为准。查询服务缺失或索引／查询故障无法恢复时，仍作为业务错误处理，不会修改规范会话存储。
 
@@ -20,7 +20,7 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 
 内容匹配沿用 SQLite 后端经过规范化的字面 token／短语语义。共享语义投影会排除推理（reasoning）块，因此 UI 搜索绝不会将模型的私有推理作为命中或 snippet 返回；派生索引的 schema 版本会随之前进，使现有持久化索引重建并移除先前的这些文档。FTS5 运算符只作为数据处理，此搜索界面不提供拼写错误纠正、模糊匹配、前缀匹配或任意子串扩展。特别是，`unicode61` 分词器可能将一段连续中文视作单个 token，因此不保证 `搜索` 之类的较短查询能匹配 `会话搜索功能` 的内部片段。标题与 Workspace 匹配仍采用普通的客户端子串匹配。
 
-## 故障与可见性契约
+## 故障与可见性约定
 
 搜索绝不会扩大会话可见范围：没有可供服务的 cwd 的冷会话会被排除，原因与它们不出现在 `session.list` 中相同；只有 id 位于这条基线中的提供方命中才能离开宿主。被遮蔽事件和纯日志事件、消息内容之外的工具事件、错误、待办事项及其他追踪记录都不会产生 UI 命中结果。
 
@@ -29,8 +29,8 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 ## 曾考虑的替代方案
 
 - **在浏览器中扫描每个会话的历史记录**：不予采纳，因为这会让 UI 承担传输与折叠开销；除非加载冷态日志，否则还会漏掉这些日志；并会重复实现已经由 `ctx.sessionQuery` 负责的语义提取与源对齐。
-- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端契约，将召回扩展留作另一项基于度量结果的决策。
-- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 契约。会话级导航本身已有价值，无需让搜索与这项工作耦合。
+- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端约定，将召回扩展留作另一项基于度量结果的决策。
+- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 约定。会话级导航本身已有价值，无需让搜索与这项工作耦合。
 - **在侧边栏公开游标分页**：不予采纳，改为固定显示前 20 条结果并提示缩小查询范围；这样可使交互与取消状态保持有界。
 
 ## 后果
@@ -41,4 +41,4 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 
 ## 测试
 
-宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为契约。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的处置固定为契约；语义提取测试与 SQLite／fixture 搜索测试将排除仅存在于推理中的文本固定为契约。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose（资源释放）。fixture（测试前置数据）、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为契约。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
+宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为约定。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的处置固定为约定；语义提取测试与 SQLite／fixture 搜索测试将排除仅存在于推理中的文本固定为约定。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose（资源释放）。fixture（测试前置数据）、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为约定。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 4453cca8eb..e6cb63c10d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
 2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
-2026-07-27-web-subagent-conversations.zh.md: 6b2d7bbec1133cdeb2d0cd31a6f9a43b068d21f5
+2026-07-27-web-subagent-conversations.zh.md: f06e5f38ba49d35ac28582f1ad3ff5eebc8ace15
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 6b2d7bbec1..f06e5f38ba 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 由会话支撑的 subagent 具有持久化身份、持久化 transcript（文本记录）与直接 child 目录，但普通会话谱系无法将它们与 fork 区分开，也无法证明其描述符 mode 与继续执行授权。否则，绑定到 agent（智能体）的通用 Host 操作可能在其直接 parent 继续执行 owner 之外恢复或驱动 child。
 
-浏览器必须遵守[可继续 subagent 契约](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
+浏览器必须遵守[可继续 subagent 约定](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
 
 UI 还必须保留[持久化目录](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)的成员、mode 与 diagnostic。共享服务报告采用实时优先规则的语料活动状态，而 Web 投影会将其替换为确切 child Agent driver 的 `running` 或 `inactive` 状态。这两种活动状态都不是持久化结果，也不承诺继续执行会成功。
 
@@ -20,7 +20,7 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。
 
-停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)，该契约会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
+停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)，该约定会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
 
 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)。
 
@@ -28,14 +28,14 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-14602&p=f)、[层级展开](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-15917&p=f)与 [child 对话](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=388-18584&p=f)画框是非规范性的交互与视觉参考。本记录负责生命周期、协议与失败语义。
 
-| 设计意图 | 已交付契约 |
+| 设计意图 | 已交付约定 |
 | --- | --- |
 | 会话页头可打开紧凑的 child 列表。 | 触发器会汇总仅含 subagent 的完整后代谱系；树按服务顺序显示每个直接目录条目，包括已禁用的 diagnostic。 |
 | 选择一行会复用对话 UI。 | 已寻址历史绝不激活 child；只有 parent 存活的可继续行才保留普通输入框。 |
 | 嵌套 agent 会逐层展开。 | 每行携带一层 `hasChildren` 快照；展开时会立即预留已知直接后代行，随后仍只加载该行的直接目录，并保留其自身的 parent 地址。 |
 | 条目显示 label、状态、token 用量与活跃耗时，同时避免侧边栏条目重复。 | mode 与 `running`／`inactive` 活动状态会同时以文字和视觉呈现；可选 title、持久化 token 用量与活跃轮次耗时来自列表保留的投影值。紧凑耗时从一天起省略更小的单位，而悬停和无障碍名称仍保留精确的整秒数。`SessionHeader.origin` 会移除重复的导航条目，但不授予任何功能权限。 |
 
-## 产品契约
+## 产品约定
 
 只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而后代活动则成为悬停与无障碍状态中的第二项。两者均不存在时，后代活动优先于未查看的完成提醒；最后一个运行中的后代停止后，该提醒会恢复。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
 
@@ -45,11 +45,11 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
-## 宿主适配器与协议契约
+## 宿主适配器与协议约定
 
 `@deepseek-ai/dsh-host-apiproxy` 拥有浏览器安全的 `subagents` 域：
 
@@ -63,7 +63,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 普通 `session.history` 路由对于普通会话和 subagent 会话同样只执行观察，但它既不携带目录地址，也不授予继续执行权限。每条需要 Agent 的普通路由都会在恢复冷会话前经过共享所有权栅栏；`session.cancel` 与 `session.updateQueue` 会直接执行同一检查，因为它们有意只查询已附加的 Agent。
 
-适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包（package）导入契约，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
+适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包（package）导入约定，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
 
 ## 客户端对象层与呈现
 
@@ -89,7 +89,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
@@ -114,4 +114,4 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
 - child 可能在历史获取与 mux 订阅之间发布，因此现有序号归并也涵盖从冷态转为存活的已寻址路径。
 - 持久化 origin 会为 child header 与列表投影添加一个有意保持弱约束的产品分类字段；它不能变成授权捷径。
-- 除对正在运行的可继续 child 的当前轮次 Stop（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
+- 除对正在运行的可继续 child 的当前轮次 Stop（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 82639d4aa8..cf0c2038cb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
 2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
-2026-07-28-continuable-subagent-conversations.zh.md: 77f497ceeef35dcc519242dca30c81759cc3b907
+2026-07-28-continuable-subagent-conversations.zh.md: cd73d9a3b5ff1b9671a7b08ed1482fa1ad45f48e
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index 77f497ceee..cd73d9a3b5 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -54,7 +54,7 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的
 
 空闲的历史会话没有 `AgentHandle`。第一条通过鉴权的 `next-turn` 投递会根据持久化会话恢复激活，并将消息提交到其 inbox。冷恢复使用经过身份认证的确切在线 parent Agent 执行鉴权；当该 parent 有激活时，还使用它建立所有权，但绝不使用 parent 执行重建。
 
-激活作为消费方会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权契约。激活 dispose 后，历史会话不消耗运行时内存。
+激活作为消费方会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权约定。激活 dispose 后，历史会话不消耗运行时内存。
 
 ### 激活生命周期
 
@@ -113,7 +113,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 报告投递扩展
 
-可选的 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递契约。
+可选的 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递约定。
 
 ### 延后的 steering（中途引导）
 
@@ -143,7 +143,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 范围
 
-本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳契约，才能支持同样的行为。
+本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳约定，才能支持同样的行为。
 
 它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存；后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)在此生命周期之上补充了唯一的公开停止操作。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
 
@@ -169,7 +169,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，该 seam 只接受确切的在线 parent。
 
-**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 契约承载。
+**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 约定承载。
 
 **使用 child 引用计数。** 计数无法识别哪个 child 仍持有拆卸工作，也允许重复递减错误。身份集合会显式保留取消和 dispose 义务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml
index 89acd445d8..a5c375dc02 100644
--- a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.md
 2026-07-28-sdk-max-output-tokens.md: 3ba3e226d64b7d3d192d67bd88af463d2b0d9dc5
-2026-07-28-sdk-max-output-tokens.zh.md: 805c34f33946638bf5b9073f8bdbce156f7a36d3
+2026-07-28-sdk-max-output-tokens.zh.md: c472c640eb0bb3d8b732b2653f94889626ba6dcd
diff --git a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md
index 805c34f339..c472c640eb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md
@@ -28,6 +28,6 @@ Python 与 TypeScript SDK 可以选择提供方和模型，却无法限制对话
 
 ## 后果
 
-SDK 调用方无需修改 Cordis 组合即可限制模型输出，直接创建 Agent 也使用同一套经过校验的 `AgentOptions` 契约。该上限在持久化请求 header 中可见，并以 `GenerateOptions.maxTokens` 到达提供方适配器；DeepSeek 序列化会将其映射为 `max_tokens`。
+SDK 调用方无需修改 Cordis 组合即可限制模型输出，直接创建 Agent 也使用同一套经过校验的 `AgentOptions` 约定。该上限在持久化请求 header 中可见，并以 `GenerateOptions.maxTokens` 到达提供方适配器；DeepSeek 序列化会将其映射为 `max_tokens`。
 
 一个 SDK 运行时只有一个默认上限。需要不同上限的调用方应运行独立的运行时实例，或通过 agent options 显式覆盖某个进程内子级。达到上限时仍产生现有的 `max-tokens` 停止原因；将其映射为 `ok` 还是 `error` 仍由部署策略决定。
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index ea1b12edeb..1d67db187c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
 2026-07-28-skill-invocation-policy.md: 9d34bcb77ab7933ef9bf4e9b5227dade39903667
-2026-07-28-skill-invocation-policy.zh.md: 4b190dbd095306d41837bd9734049f5e3d85da72
+2026-07-28-skill-invocation-policy.zh.md: 687bd582ce3f4c74e50d36640afc6b683e289c90
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
index 4b190dbd09..687bd582ce 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
@@ -8,11 +8,11 @@ Status: implemented
 
 skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会移除禁止模型调用的 skill，而 `ctx.skills.get()` 仍是不过滤内容的可信 loader。该设计足以支持由模型发起的加载，却无法表示与 Claude 兼容的四类 skill：仅向用户公开、仅向模型公开、同时向两者公开，或者两者均不公开。TUI 从面向模型过滤后的列表中生成用户自动补全，并允许通过 `get()` 加载任意精确名称，这进一步放大了两类调用策略不匹配的问题。
 
-本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型契约。
+本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型约定。
 
 ## 决策
 
-`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行契约后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
+`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
 
 `ctx.skills.list()` 返回所有胜出的摘要，不再替任何调用接口选择策略。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 保持策略无关，因为可信内部调用方可能需要任意定义；对外消费方则必须在展示或加载 skill 之前执行自身对应的判定函数。模型工具和 TUI 会在调用 `get()` 前检查与调用策略无关的摘要，随后再次检查已加载的定义：被拒绝的名称绝不会进入定义加载流程，发现与加载之间发生策略变更也无法暴露该 skill 的正文。
 
@@ -39,12 +39,12 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
 
 **在 `ctx.skills.get()` 内执行调用策略。** 不予采纳，因为 `get()` 无法判断调用方是模型工具、人类命令还是可信编排逻辑。在此处过滤还会使两个接口均禁止调用的组合无法被检查或管理。
 
-**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 契约，而本仓库尚未发布，无需承担兼容义务。快速失败可以避免暗中保留不符合标准的拼写。
+**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 约定，而本仓库尚未发布，无需承担兼容义务。快速失败可以避免暗中保留不符合标准的拼写。
 
 **增加由浏览器端直接调用 skill 的 RPC。** 本次改动不予采纳，因为现有浏览器流程插入的是模型引用，而非已经加载的指令正文。因此，该流程应当取模型与用户调用策略的交集；直接由用户加载的接口需要单独设计协议与日志记录方式。
 
 ## 后果
 
-提供方与运行时注册对外提供小而类型明确的调用契约，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
+提供方与运行时注册对外提供小而类型明确的调用约定，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
 
 无密钥 ACP（Agent Client Protocol）快照固定了模型目录的变更：其中包含仅允许模型调用的 skill，并排除仅允许用户调用的 skill。组装后的无密钥 TUI 快照按精确名称发现并加载一个仅允许用户调用的 skill，随后在加载正文前拒绝一个仅允许模型调用的 skill；真实 Loader/PTY 冒烟测试通过随产品交付的终端进程证明了同一条仅允许用户调用的路径。真实宿主上的 Chromium 快照固定了浏览器在全部四种策略组合下的交集行为。TUI 单元测试覆盖这些组合以及资源释放竞态；注册表、本地解析器、模型工具和 API 代理测试则覆盖默认值、支持的布尔写法、格式错误的值、旧键拒绝、精确名称加载时的策略执行，以及浏览器侧的策略交集。
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 53dba67c61..77df231e1c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
 2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
-2026-07-28-web-terminal-card.zh.md: 4c74d880c5795cf85f32391b27e6ffd2c5074870
+2026-07-28-web-terminal-card.zh.md: 3a9025b3f2dee546253d923c121df0e04da73414
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 4c74d880c5..3a9025b3f2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,9 +12,9 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
-该组件的契约：
+该组件的约定：
 
 - **提示符行，每条命令行一行。** 命令的每一行各占一行：标签，其后原样跟随该行。因此一个在两行上承载两条 shell 命令的 `command` 就读作它本身的两条命令，而不是被压成一行并省略号截断。标签取 cwd 的最后一段路径，当 cwd 等于 `home` prop 时取 `~`——浏览器没有 `$HOME`，因此由调用方提供绝对家目录，不提供时该折叠不生效。视图不带 cwd 时渲染一个纯 `$`。末尾换行是终止符，不是一条空的末命令。只有**第一行**携带该标签：视图只知道一个工作目录——调用开始处的那个——而后面的行完全可能在别处运行，命令里一个 `cd` 就足以改变它。把标签在各行重复，等于陈述一个此处无人知晓的逐行目录，这与运行状态点只出现一次是同一个理由。其余行保留一个裸 `$`，因此它们仍读作提示符。
 - **整次调用一枚运行状态点，位于第一行。** 它是 `StateDot` 四种状态中的三种：运行期间为追逐动画，与渲染状态徽章相同的退出状态为红色，干净落定为绿色——与工具行行首图标使用同一个指示器，因此一行与其自身的卡片不可能对同一条命令产生分歧。该状态点存在的理由是：读者对一条 shell 命令的第一个问题就是它是否仍在运行；没有它时，这一点只能从「没有输出」推断，而一条落定后无输出的命令看起来也一样。它以脱离文档流的方式落在卡片以**自身左内边距**预留的落区里，因此既不会缩进其命令，也不依赖命令自身的文本度量来与之对齐。该预留用 padding 而非 margin，是因为每个渲染点都会整条重写 `margin` 来设定自己的缩进——那会静默取消基于 margin 的落区，并让容器把状态点裁掉。无论有多少行，都只有一枚：视图携带的退出状态属于整次调用，而 bash 不报告逐条命令的状态，因此每行一枚状态点就等于在断言——一条在失败调用中其实成功了的命令行自身失败了。那一处视觉隐藏的文本标签具有相同的作用域，因为 `StateDot` 是 `aria-hidden`，而每行一个标签会被辅助技术读成好几个各自独立的结果。
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
index 35c6e070a6..ade585187c 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
 2026-07-29-ask-question-web-presentation.md: 11471bba08b723620b83af0e14e64a759d11c520
-2026-07-29-ask-question-web-presentation.zh.md: 50f0dffa1a1f9cbd29b676cc1f21ba0298f6bf23
+2026-07-29-ask-question-web-presentation.zh.md: 6957d34fa5d3769340be9798998e59496e4b7f44
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
index 50f0dffa1a..6957d34fa5 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
@@ -38,7 +38,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 行内裁决字符串是问题流程仅剩的硬编码英文面；将其本地化是推迟的后续工作。在审批输入区接管交付之前，`PendingCard` 仍是可见但不可操作的审批占位。
 
-`ui-question` 新增 `dsh-client-locale` 依赖和此前没有的 inject face；其契约（`QuestionComposerInjected`）与消费者一起放在 `contract/slots.ts`。
+`ui-question` 新增 `dsh-client-locale` 依赖和此前没有的 inject face；其约定（`QuestionComposerInjected`）与消费者一起放在 `contract/slots.ts`。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml
index 8df627311b..327f20a740 100644
--- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md
 2026-07-29-directory-picker-adaptive-default.md: 7ff6529bb8e445f63343b1019ac520f56b19d5e4
-2026-07-29-directory-picker-adaptive-default.zh.md: fd3f1473beabdc14b4eea84efdb3fe25116f759d
+2026-07-29-directory-picker-adaptive-default.zh.md: 17cb912df472105ec3b34faa8baa36cf527d6173
diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md
index fd3f1473be..17cb912df4 100644
--- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md
@@ -25,6 +25,6 @@ Status: implemented
 
 - 随附的 web GUI 开箱即自适应：有人值守的本地宿主 → OS 选择器；SSH 启动、全网卡绑定、无头宿主、不支持的平台，或没有选择器二进制的 Linux → 应用内浏览器。探测是从启动上下文推断操作者位置，而任何启动侧信号都无法证明这一点：脱离的 tmux 会话会丢失 `SSH_*`；非 Aqua 的 darwin 进程仍被算作有显示；而 `ssh -L` 形态（在工作站本地启动、之后经转发端口访问，从 `127.0.0.1` 到达）会判定 `native`，把选择器弹在无人值守的工作站上——即便按连接自适应也修不了最后这一情形。错误的 `native` 选择会退化为后端既有的可重试失败对话框；处于这些形态的部署直接组合 `-browse`。
 - 选择器按运行时字符串（已导出的 `BACKEND_PACKAGES`）挂载后端，yml 行扫描看不到这一点；因此 `verify-cordis-config` 要求每个挂载 `-auto` 的组合把两个后端都声明为依赖，使无密钥的 Linux CI（它永远只会判定出 `browse`）无法掩盖被丢掉的 `-native` 依赖。随附树的 web e2e／快照通道（`apps/web/tests/scaffold.ts`）以 disable+insert 补丁固定 `-browse`——其 golden 是交互特定的，绝不能依赖运行该套件的宿主。
-- 每次启动只判定一次，维持 seam 的能力稳定性契约；按连接的形态在有部署提出需求前仍不在范围内。
+- 每次启动只判定一次，维持 seam 的能力稳定性约定；按连接的形态在有部署提出需求前仍不在范围内。
 - 同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务；`single` 洞中的重复流程）。
 - host 类型检查聚合现在引用两个后端项目（仅声明，node 入口不携带 client 合并），使选择器的 REAL-composition 测试能挂载它们——与 client 聚合对 `webserver` 的引用互为镜像。
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
index 243eed83f8..42a8e3e6bd 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
 2026-07-29-persistent-bash-str-replace-editor.md: c4750e30370bfd253064c39cb1adc0f5b2baa60d
-2026-07-29-persistent-bash-str-replace-editor.zh.md: 14c52fc90d8619d63ca3acab2d85447fab5eb735
+2026-07-29-persistent-bash-str-replace-editor.zh.md: 83159d9792fd9fadaaa342cc289300b35da34e4a
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
index 14c52fc90d..83159d9792 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 **暴露终端管理工具。** 被拒绝，因为 open/send/read/close 与单个持久 `bash` 调用是不同的模型动作空间。
 
-**修改原生 read/write/edit。** 被拒绝，因为这会扭曲其通用契约，而不是增加一个可独立组合的编辑器。
+**修改原生 read/write/edit。** 被拒绝，因为这会扭曲其通用约定，而不是增加一个可独立组合的编辑器。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index 1491968f15..0c996c69fd 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
 2026-07-30-config-only-repository-plugins.md: 2057125fc78596dd4e5eb153f77b828f83d9ceff
-2026-07-30-config-only-repository-plugins.zh.md: 6e741b46be716e21a11c2f508fb5e6d0505c76d0
+2026-07-30-config-only-repository-plugins.zh.md: 89d8bd518f2a744c58b042059d2d7787caefe38c
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 6e741b46be..89d8bd518f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败契约和清理行为。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败约定和清理行为。
 
 ## 实时更新与失败
 
@@ -36,7 +36,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 **监视缓存内容，或自动刷新相同 ref。** 否决，因为一个配置值必须标识一个不可变的已准备版本。后台远端解析会在没有配置差异的情况下改变可执行代码，并使回滚依赖可变的远端状态。
 
-**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定契约，并在需要时把原始值保留为错误原因。
+**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定约定，并在需要时把原始值保留为错误原因。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
index 54966549ba..8e7e02fe37 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
 2026-07-30-continuable-subagent-report-tool.md: 8324f1fa08f7dace6153712575e7e70a07ee9344
-2026-07-30-continuable-subagent-report-tool.zh.md: e7599c1d85328e83c7773718101b59e763a1e37f
+2026-07-30-continuable-subagent-report-tool.zh.md: 6b7472717e724af9bf598fada6d7e82070d06f3c
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
index e7599c1d85..6b7472717e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 可继续的进程内 subagent 能够接收 parent 后续发来的消息、保留后代、结算并冷恢复，但基础生命周期无法让它们将选中内容发送给直接 parent。child 的完整输出已可从持久化会话中重建，因此缺失的能力是显式投递，而非结果存储。
 
-如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式契约。
+如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式约定。
 
 ## 决策
 
@@ -16,7 +16,7 @@ Status: implemented
 
 该功能是协作控制，不是承载结果的执行包装层。它不新增 Task、`SubagentRun`、结果 promise、Activation 状态、投递队列或回放路径。
 
-### 面向模型的契约
+### 面向模型的约定
 
 `report` 只接受 `{ output: string }`，也只返回 `{ messageId: string }`。它不接受 child id、接收方 id 或投递模式。`exec.agent` 将工具调用绑定到发送报告的 child；服务从持久化 `parentSession` 中推导唯一接收方，调度则由部署配置决定。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
index 9e267e82a0..a9dec720a8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
 2026-07-30-current-sandbox-policy-context.md: 093f9a8a0b58256bb4f2301cc62fa83629de4fbd
-2026-07-30-current-sandbox-policy-context.zh.md: 729ea9d50c7dbbfa027e1cad11929ae1c2b379b1
+2026-07-30-current-sandbox-policy-context.zh.md: 6189df12ae2cd9c9a040cd40636596cda23548c9
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
index 729ea9d50c..6189df12ae 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
@@ -50,7 +50,7 @@ Status: implemented
 
 **缓存安全迁移后仍保留 Candidate A。** 不予采用，因为中性的真实提供方任务中，尽管已有 bash 尝试引导，模型仍以纯文本拒绝，且没有调用工具。保留下来的反预防性拒绝原则本身不说明任何升权机制；它告诉模型不要从常驻标签推断操作不可能完成，然后把拒绝与升权行为交还给可用工具。
 
-**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具契约下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
+**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具约定下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
 
 **独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合 seam 和额外的文档／门禁表面。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 418c81f17d..67de206735 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
 2026-07-30-deepseek-onboarding-credential-setup.md: 419ea0aea56e82e301189d90d5ca78495da2da71
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 936402c9ed83eccc3d5e78a57247f06347522c0f
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: ba31dc1141eecddc24e178841fefb96858ca4d8c
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 936402c9ed..ba31dc1141 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 **Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
 
-**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
+**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为约定；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
 **首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index 1ceb5a5213..f9944e3ed8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
 2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
-2026-07-30-queued-manual-compaction.zh.md: 29c3b921d0d59527aa1d8af1c91d085b52045377
+2026-07-30-queued-manual-compaction.zh.md: fe3b0ff5e6b8cab7cb332f958adc6ab8d94f23b8
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index 29c3b921d0..fe3b0ff5e6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -89,7 +89,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 **同时使用持久标记与进程本地 mutex。** 不予采用，因为两项权威在回放后可能产生分歧，还会要求用包装层分支处理标记对已经表达的状态。
 
-**与唤醒提示词一起阻塞注入。** 不予采用，因为按契约，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
+**与唤醒提示词一起阻塞注入。** 不予采用，因为按约定，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
 
 **要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index f26524cdc3..cee07159d1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md
 2026-07-30-search-render-card.md: 29544cb703f3ab048f4e7702935887ecf05179bf
-2026-07-30-search-render-card.zh.md: e0ae21924e82152ba629ab628476113ad9afe3d8
+2026-07-30-search-render-card.zh.md: 01ffe25522c462a26e781f9bd455711331e58445
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index e0ae21924e..01ffe25522 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `grep` 与 `glob` 返回结构化的 canonical 值 —— `grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`，`glob` 是 `{ paths: string[] }` —— 但每个 UI 只见过它们面向模型的渲染文本：`grep` 把匹配按文件头分组、每行 `Line N:`，`glob` 打印换行连接的路径列表，两者在内联上限（`grepMaxMatches`，默认 250；`globMaxResults`，默认 100）把后续结果落到 spill 文件时都追加一个 spill 脚注。想把搜索结果渲染成可展开的按文件匹配组、或可选择的路径列表的 web 前端，只能去重新解析那段文本。两个工具都已声明调用时的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)（`GenericCallView`，`kind: 'search'`），但没有结果时视图，所以已完成的调用回退到渲染原始文本的 generic 卡片。
 
-结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
+结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
 
 ## 决定
 
@@ -30,7 +30,7 @@ Status: implemented
 
 `SearchMeta` 的成员形状是对象字面量 `type` 别名，而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口，因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名；两者结构等价，所以投影值仍读回为 `SearchResultView`。
 
-没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端契约及其两个生产者。
+没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
 
 ## 考虑过的备选
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **把面向模型的文本作为视图的 `content` 附上。** 否决：对每个当前消费方是 no-op，且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状；文本回退读原始结果内容。
 
-**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策契约与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
+**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
 
 **镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决：搜索调用在 `execute` 前没有匹配或路径，视图只会携带 `GenericCallView` 已有的标题。
 
@@ -57,5 +57,5 @@ Status: implemented
 ## 相关
 
 - [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
-- [Canonical 工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
+- [Canonical 工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
 - [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index d78733bb33..2e01db1284 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
 2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
-2026-07-30-web-diff-card.zh.md: a9c710df99c1060bbf50b591b2f62120dc7dcbef
+2026-07-30-web-diff-card.zh.md: 901331907ed9052541aaee0d4fe70531b030d0f9
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index a9c710df99..901331907e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -32,7 +32,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 **并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
 
-**git 式行号槽。** `FileDiff` 契约只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端契约改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有契约的纯 Web 消费。
+**git 式行号槽。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有约定的纯 Web 消费。
 
 **复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
 
@@ -48,7 +48,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 `packages/client/ui-tool/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。
+fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身约定它不带 diff 行为断言，那由接线套件负责。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
index 624da25dc2..6a6683265e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.md
 2026-07-30-web-queue-steer-action.md: b04095b81f499982c8680a2d3627d8e98a70d8ac
-2026-07-30-web-queue-steer-action.zh.md: b04902b8a8a0d727b01aa6ba5562e12cc5d36c92
+2026-07-30-web-queue-steer-action.zh.md: af13292574b7f130fe858369c746ff2b8911984e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
index b04902b8a8..af13292574 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
@@ -12,7 +12,7 @@ Web composer 原本会在 agent 运行期间把所有 Enter 提交作为 Queue 
 
 ## 决策
 
-### 产品契约
+### 产品约定
 
 普通会话中每个非编辑态的 QueueDock 行都会提供名为“插话发送”的向上箭头操作。仅当会话报告 agent 正在运行时，该操作才会启用；包含混合内容的消息仍可使用，因为 steering 会转发完整且不可变的 `UserMessage`，而非该行的文本投影。已寻址 subagent 的 Queue 投影保持只读，因为其继续执行传输不提供 Queue 变更。
 
@@ -20,7 +20,7 @@ Web composer 原本会在 agent 运行期间把所有 Enter 提交作为 Queue 
 
 running 标志位只用于提示交互状态。在同步变更边界上，AgentLoop 的 `acceptsNextStep` 值才是权威依据。如果该窗口已经关闭，操作会保持 Queue 单次入队项不变并返回类型化的 `steer-unavailable` 错误，随后原唤醒单次入队项会经 Queue 继续执行。如果驱动器已经认领该项，则返回现有的 `queue-item-not-found` 错误，且独立轮次投递已经开始。UI 会把两种竞态都视为已收敛的 Queue 投递，不显示失败通知；传输和未知错误仍会显示。
 
-Composer 对新输入采用另一套尽力而为契约。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
+Composer 对新输入采用另一套尽力而为约定。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
 
 ### Agent 与生命周期边界
 
@@ -38,11 +38,11 @@ Host 仍以现有 `queuedMirror` 作为唯一的瞬态 inbox 权威。`session/q
 
 AgentLoop 认领待处理 steering 时，会在同步追加持久 `user/message` 之前立即发出 `agent/inbox/dequeue`。Host 会等到下一个微任务才退役该 steering 行，让持久 session 事件先进入线性 mux 流。客户端 Session 接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史回放不会消费后来复用同一 `MessageId` 的单次入队项。因此，ChatView 无需扫描持久历史就能每次只渲染一份权威，持久投影则会根据已记录的事件时间与序号恢复时钟、复制与 fork 操作。追加失败时，已认领行仍会退役。
 
-现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的契约：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该契约。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
+现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的约定：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该约定。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
 
 ### 验证
 
-AgentLoop 契约覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
+AgentLoop 约定覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
 
 Host schema 和代理测试覆盖新操作、两种类型化错误、带 placement 的快照与重连重放，以及先持久化再退役的顺序。客户端测试覆盖两种语义竞态的静默收敛、真实错误报告、只读 subagent 行和仅支持 Queue 的 subagent 手势。运行时与 ChatView 测试覆盖按单次入队项完成的待处理到持久交接，包括重复的 `MessageId` 值；Web ARIA 快照则覆盖位于运行状态行之后且仅有复制的待处理 steering，以及带时钟、复制和 fork 的持久节点。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index 3415ace63b..b4992a15c3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
 2026-07-30-web-read-card-frontend.md: e659645066b706f35709fead4c11023eb4fe9554
-2026-07-30-web-read-card-frontend.zh.md: 4fc02e23b45399c01b5c99d388f5ae1726b026c0
+2026-07-30-web-read-card-frontend.zh.md: ac3972ace7458b8a751b4cc342bbdb3e2b0a7a9e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index 4fc02e23b4..ac3972ace7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **新建一个 `ReadBlock` primitive，而不是扩展 `CodeBlock`。** `CodeBlock` 已经带语言横幅和复制控件做 shiki 高亮，但读取视图需要一个每行带该行自身文件行号的行号栏，而 `CodeBlock` 把内容渲染为单个 `<pre>` 树、没有逐行结构。给 `CodeBlock` 加一个可选行号栏会把读取专属的关切（窗口行号、"显示 N / M"提示、高度上限）强加给共享该组件的每个 markdown 代码围栏和每个 `run_code` 程序体。`ReadBlock` 转而复用真正共享的部分：`markdown/highlight.ts` 里的 shiki 语法单例。那里新增的 `highlightLines(code, lang)` 把代码切成 shiki 自己的逐行 token 数组（`codeToTokens`），而不是 `highlightToHtml` 产出的单 `<pre>` HTML，于是该 block 能每行放一个行号、同时用同一套 `--shiki-*` 自定义属性、同一份语法白名单给内容上色。高度上限及其头/尾展开算法照抄自 `TerminalBlock`（`ceil(max/2)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
 
-`readCardModel` 只在结果侧，与后端对称：一次读取调用在 `execute` 返回前不带任何内容，因此挂起中的调用保持为 `GenericCallView`（`kind: 'read'`），本函数对运行中的读取返回 null —— 该行保持其从参数派生的摘要，直到结果到达。它对结果视图不是读取卡片的已结算调用也返回 null，包括本 UI 版本不认识的 `card` 值（它从线路到来、不能被信任为一个已编译的变体）以及读取工具对错误结果自己的通用回退。卡片横幅标签在工具提供 `title` 时取它（契约的替换标题规则），否则取相对于会话工作区化简后的文件路径，使工作区根下的绝对路径显示为与行摘要相同的短形式。该 model 把冻结的行数组复制进 primitive 自己的行形状，因此卡片绝不持有指向运行时快照缓存的引用。
+`readCardModel` 只在结果侧，与后端对称：一次读取调用在 `execute` 返回前不带任何内容，因此挂起中的调用保持为 `GenericCallView`（`kind: 'read'`），本函数对运行中的读取返回 null —— 该行保持其从参数派生的摘要，直到结果到达。它对结果视图不是读取卡片的已结算调用也返回 null，包括本 UI 版本不认识的 `card` 值（它从线路到来、不能被信任为一个已编译的变体）以及读取工具对错误结果自己的通用回退。卡片横幅标签在工具提供 `title` 时取它（约定的替换标题规则），否则取相对于会话工作区化简后的文件路径，使工作区根下的绝对路径显示为与行摘要相同的短形式。该 model 把冻结的行数组复制进 primitive 自己的行形状，因此卡片绝不持有指向运行时快照缓存的引用。
 
 聊天行把卡片**常驻**渲染在摘要行之下，上限 `CHAT_READ_MAX_LINES`（8，是 primitive 默认值的一半），与 `BashRow` 对终端卡片的姿态相同 —— block 的内部展开器让长读取不会占据整个消息流。两个渲染点承载它：keyed `ReadRow`（经 `ctx.slots.inject` 以 `read` 键注册，与 bash 样例完全一致），其摘要是作为可打开的宿主链接的文件路径；以及 `GenericToolCard` 对没有自己 keyed 行的读取声明工具（例如归到 `read` 变体的 `web_fetch`）的回退。详情面板以 primitive 自己的全高上限（16）渲染同一张卡片，因为面板是单次调用的阅读界面。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
index 9bde6a14c7..a58a19000a 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card.md
 2026-07-30-web-read-card.md: 26d1634b6be86666980e65f842de51c868c26efd
-2026-07-30-web-read-card.zh.md: 749177e93e8e3b2e34aed46d1fe99226395a6686
+2026-07-30-web-read-card.zh.md: c48cd56b7f919d5ceb702f890ee18a2a735da347
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
index 749177e93e..c48cd56b7f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
@@ -14,9 +14,9 @@ Status: implemented
 
 给[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 新增第四个 `card` 标签 `read`——仅在结果侧。`ToolResultView` 增加 `ReadResultView { card: 'read'; title?; path; lines: ReadFileLine[]; totalLines; lang?; content? }`；`ReadFileLine { number; text }` 是共享的行单元。`ToolCallView` 不动：待定状态仍是 `GenericCallView`（`kind: 'read'`），因为一次调用在 `execute` 返回前不携带文件内容，调用时没有可展示的结构。这与 bash 终端 card 不同——终端 card 两侧都打标签，因为终端调用在调用时已携带命令和 cwd，而 read 调用既无内容也无总数，给调用侧打标签只会新增一个空变体。
 
-read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
+read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
 
-`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图契约的一部分。
+`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
 
 ### 语言提示推导
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index 6f3a5d895b..b844594397 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
 2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
-2026-07-30-web-result-card-frontend.zh.md: 4cec11371e8d0848f2f03ded0b093d80cc25a7a5
+2026-07-30-web-result-card-frontend.zh.md: e40d103c295b4699cde3327252c8bca3719e7962
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 4cec11371e..e40d103c29 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## Problem
 
-`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个 `kind` 标签联合,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是契约笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
+`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个 `kind` 标签联合,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是约定笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
 
 ## Decision
 
 `WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
-一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
+一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是约定把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
 **链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集。** MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
 
@@ -22,15 +22,15 @@ Status: implemented
 
 ## Consequences
 
-`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到契约的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
+`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到约定的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
 
 一条独立的后续 PR 会统一整行折叠/展开交互,并把每张常驻卡片（terminal、diff、web）一次性翻成 expand-gated;本卡片遵循当前的常驻约定,而非抢先做那次改动。
 
 ## Alternatives considered
 
-**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而契约已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
+**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而约定已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
 
-**重解析模型可见的渲染文本,而非消费结构化视图。** 因契约笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
+**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
 
 **不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此接缝处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 `packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
+fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配约定的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index 0badfa2a55..9eba8730a4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card.md
 2026-07-30-web-result-card.md: 838b13a7f3240c753e5cd1af6909389055c6352d
-2026-07-30-web-result-card.zh.md: 6e5170fcad82d709b050fb05e8efcfe955f20391
+2026-07-30-web-result-card.zh.md: 36ab372864e5cd848b999ee759e73658271b8f90
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index 6e5170fcad..36ab372864 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`web_search` 与 `web_fetch` 工具各自声明了一个 generic 待定卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图契约（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
+`web_search` 与 `web_fetch` 工具各自声明了一个 generic 待定卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图约定（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
 
 ## Decision
 
@@ -22,7 +22,7 @@ Status: implemented
 
 ## Consequences
 
-前端消费方由后续独立 PR 交付：本次生产者变更新增契约分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
+前端消费方由后续独立 PR 交付：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
 
 未来想用此卡片的 web 工具，声明一个返回带自有 `kind` 的 `card: 'web'` 视图的 `presentResult`；新增第三个 `kind` 是一次联合类型编辑加前端的分岔，而非一个新的 card 标签。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 0cfb6b01bd..461492312b 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-search-card.md
 2026-07-30-web-search-card.md: e0be857df69dfd46b6e936c775c6bae1476c26dc
-2026-07-30-web-search-card.zh.md: 1704b8f04c519511d5afa32ae6683c1e48ce7992
+2026-07-30-web-search-card.zh.md: 784afb0dd36f20c3a0e203d5595c46c8040d82ff
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index 1704b8f04c..784afb0dd3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 `grep` 与 `glob` 工具声明了一个仅在结果阶段存在的 `card: 'search'` render intent（[search render card](2026-07-30-search-render-card.md)）：`SearchMatchesResultView`（`shape: 'matches'`）携带 grep 按文件分组的匹配，或 `SearchPathsResultView`（`shape: 'paths'`）携带 glob 的扁平路径列表，两者都带 `truncated`/`total` 截断信号。该视图已经到达浏览器 —— host、connection、runtime 把它作为 `resultView` 投递到 `ConversationSnapshot` 上 —— 但 Web 客户端忽略了它：每个非终端、非 diff 的工具结果都落到 generic 卡片，渲染面向模型的文本。想把搜索结果渲染成可展开的按文件匹配分组、或可扫读的路径列表的 web 前端，只有那段预格式化文本。
 
-这正是 search render card note 指名的后续：那个 PR 是后端契约和它的两个生产者，本 PR 是 web 消费者。
+这正是 search render card note 指名的后续：那个 PR 是后端约定和它的两个生产者，本 PR 是 web 消费者。
 
 ## Decision
 
 `SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/tool/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
 
-与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
+与终端卡片的不对称是刻意的，继承自后端约定：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
 
 一个组件绘制两种形态，用 `kind` 区分，因为 `grep` 和 `glob` 是同一个视觉对象 —— 一个搜索结果。`SearchMatchesBlockProps`（`kind: 'matches'`）和 `SearchPathsBlockProps`（`kind: 'paths'`）让每种形态的字段保持必填，而不是所有字段都可选的单一接口。组件把它持有的形态压平成一个渲染行列表 —— matches 形态是一个文件头行加它的匹配行，paths 形态是每个路径一行 —— 于是高度上限把一个文件头当作一行来计，与一条匹配行或一个路径相同，头/尾切片算术就是 `TerminalBlock` 的（`ceil(max/2)` 头，其余为尾），因此一个长搜索结果和一段长命令输出在两张卡片间在同一处截断。
 
-组件契约：
+组件约定：
 
 - **按文件分组的匹配，逐文件可折叠。** 每个文件是一个头行（加粗路径加它的匹配计数，整行即折叠控件），后面跟它的 `lineNumber: line` 行。折叠一个组会把它的匹配行从压平列表和高度上限的算术里去掉，但绝不从复制文本里去掉。
 - **扁平路径列表。** paths 形态每行一个路径，无头行。
@@ -44,7 +44,7 @@ Status: implemented
 
 **两个卡片组件，每个工具一个。** 否决：`grep` 与 `glob` 是仅由 `kind` 区分的同一视觉对象，两个组件会重复横幅、高度上限、复制控件与不换行几何。一个按 `kind` 分支的组件正是后端那个单一 `card: 'search'` 视图的用途。
 
-**加一个 `SearchCallView`，让行在搜索运行时就渲染卡片。** 否决：后端契约刻意没有调用阶段的搜索视图 —— 搜索在 `execute` 前没有匹配或路径。运行中的行只显示摘要，`searchCardModel` 对运行块返回 null，忠实于实际存在的东西。
+**加一个 `SearchCallView`，让行在搜索运行时就渲染卡片。** 否决：后端约定刻意没有调用阶段的搜索视图 —— 搜索在 `execute` 前没有匹配或路径。运行中的行只显示摘要，`searchCardModel` 对运行块返回 null，忠实于实际存在的东西。
 
 **复用 `TerminalBlock` 或 `CodeBlock`。** 否决：两者都不建模逐文件可折叠的组或折叠式截断摘要，都需要把按文件分组的形态硬塞进去。三个块转而共享几何与字体 token，那是唯一一处一个实现对三者都正确的部分。
 
@@ -56,10 +56,10 @@ Status: implemented
 
 `packages/client/ui-primitives/tests/search-block.spec.tsx` 以 per-file 100% 覆盖固定组件：两种 kind、折入摘要的截断前总数、空结果分支、逐文件折叠/再展开且不影响邻居、一个文件头与其匹配一起计为一个被截断行、切口落在文件中间时尾部切片恢复其所属文件头、跨两种形态的头/尾上限及其展开控件（含无尾与默认上限的边界），以及复制控件在接受与拒绝的剪贴板路径上写入整个结构化结果。
 
-`packages/client/ui-tool/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-tool/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
+`packages/client/ui-tool/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-tool/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库约定要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按约定只测启动）无法捕获它。
 
 ## Related
 
-- [Search render intent —— grep 与 glob 发出结构化搜索卡片](2026-07-30-search-render-card.md) —— 后端契约与它的两个生产者；本 note 是它指名的 web 消费者后续。
+- [Search render intent —— grep 与 glob 发出结构化搜索卡片](2026-07-30-search-render-card.md) —— 后端约定与它的两个生产者；本 note 是它指名的 web 消费者后续。
 - [Web 终端卡片](2026-07-28-web-terminal-card.md) —— 本 note 镜像的先例：工具的 render intent 通过一个 `ui-primitives` 块、一个 `contract/*-card-model.ts` 推导、以及同样的三个渲染点到达浏览器。
 - [工具调用呈现的标签化 render-intent 联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 两张卡片都消费的 `card` 标签词汇。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
index 255dd08832..0943fb008c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
 2026-07-30-web-tool-row-unified-expand-and-inspect.md: 4fcf1e9a567b73cd04f1bbed170c391aaedd9e73
-2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 92d70f5aa6bd09e6f9e54015dafc38d8d3690a9e
+2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: aa81bb584cb794110454cf97520f82c1421e3e41
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
index 92d70f5aa6..aa81bb584c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
@@ -21,7 +21,7 @@
 
 ## 曾考虑的替代方案
 
-**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互契约本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
+**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互约定本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
 
 **通过 URL 或 trajectory 视图 prop 传递 Inspect。** 否决：视图环经由 slot 注册表渲染，两个视图没有可携带 prop 的共同父级；chat store 本就跨越该边界，一次性字段让交接可安全重放（字段出现之前的持久化快照以 `?? null` 复水）。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index e6ca4048fd..ee89a37a8b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
 2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
-2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db
+2026-07-31-code-mode-language-dispatch.zh.md: c8ab776dfb01265fa79b5f2b1001ca8109a96d7f
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index 1dbb3d889d..c8ab776dfb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -23,11 +23,11 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ### Python SDK 渲染器
 
-`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON-schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的契约一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
+`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON-schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的约定一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
 
 该上限服务的标准是**语法合法性**，这条边界是有意划定的：长的 `A | B | …` union 在任何长度下都是合法 Python，故不设上限——尽管 CPython 的 `compile()` 在沿左嵌套 `BinOp` 脊柱下降时会耗尽 C 递归（在 3.9 上实测：1,000 个分支可编译，5,000 个抛 `RecursionError`）。没有任何东西会编译这个块——它是提示词文本——所以那条限制在这里没有代价；而给 union 长度封顶会作废那几个钉住 walk 线性时间与类名传播上限的深链测试。将来若有渲染器确实需要可编译的输出，应当把 union 拍平，而不是截断。
 
-`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的契约是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
+`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
 
 ## Alternatives considered
 
@@ -41,6 +41,6 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
-Python SDK 文本断言的两条运行时契约同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 契约填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
+Python SDK 文本断言的两条运行时约定同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 约定填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
 
 其三，那个 PR 拥有 CPython 版本下限，连带拥有本渲染器的 Unicode 表偏斜。有四处表达式读所运行引擎的表（Node 22.23.1：Unicode 17.0），而解释器用它自己的表（CPython 3.9.6：13.0.0）：`isBareIdentifier` 的 `IDENTIFIER`，以及 `camelCase` 的切分集、头部测试与 `toUpperCase()`。解释器旧于引擎是会失败的那个方向——引擎发出的字符被其 tokenizer 拒收，整个块随之不可解析——而它经三条独立路径抵达。经判据抵达的是裸发的方法名或字段名，其中带有一个在两个版本之间新增的字符——首位加进 `XID_Start`，或尾部任意位置（含名字中部）加进 `XID_Continue`。经 `camelCase` 的 XID 读取抵达的是类名：只要工具 schema 中有任一对象形态声明 `TypedDict`，该类名就进入发出的文本，且判据对工具名的裁决并不对它设闸——工具名 `zz-` 加 U+1E4D0 因 `-` 被判据直接拒绝、从不触及那里的偏斜，却照样声明 `class Zz𞓐xArgs`。经大写映射抵达的是由判据已接受的工具派生出的类名——这是另一张表，窗口也比 XID 归属更宽：U+019B 既是 XID_Start 又 NFKC 稳定，故 `async def ƛ` 在 3.9.6 上可编译，但 Node 将其大写为 U+A7DC（在那里未分配；CPython 自己的 `.upper()` 在此是恒等），于是 `class ꟜArgs` 以 `invalid non-printable character U+A7DC` 失败。暴露窗口是两个版本之间发生变化的那些字符与映射，所以宣布支持某个 CPython 范围的那个 PR 必须在「接受该暴露」与「按该下限的表钉住全部四个读取点」之间显式作出决定——只钉判据会同时留下两条类名路径。此处无法决定：下限尚不存在，而按猜测钉死一张表会成为一个随部署而变、却没有可配置性支撑的常量。还有第二条轴随该下限一同确定，且不属于那四个读取点：本块在定义期会被求值的那些名字与语法。`TypedDict` 需要 3.8，PEP 585 的内建泛型 `dict[str, Any]` 与 `list[…]` 需要 3.9，`A | B` 形式的注解需要 3.10，`NotRequired` 需要 3.11。这些不是解析失败——本块在任何版本上都能解析，这正是 `MAX_LIST_NESTING` 上限所服务的标准——而是定义期求值失败，且产品中没有任何东西会求值这段文本。把它们与那四个读取点记在一起，可避免把「在所支持范围上可解析」读成「在其上可执行」。
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
index 99ea335b59..3a409f4c4b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.md
 2026-07-31-gui-full-access-confirmation.md: ca89ed23fb1b5c6ea438dd22fdf20d2b82af754c
-2026-07-31-gui-full-access-confirmation.zh.md: 0f487e41b544718bdf38de611a1ab2d59c44b063
+2026-07-31-gui-full-access-confirmation.zh.md: db5f4bc58e05e2441bcaa3da160de3bc9e707a6a
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
index 0f487e41b5..db5f4bc58e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
@@ -28,4 +28,4 @@ Status: implemented
 
 ## Consequences
 
-进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 契约，以及组装态 Web 回放。
+进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 约定，以及组装态 Web 回放。
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
index 3227fac451..7e4d85c66c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.md
 2026-07-31-permission-default-for-new-sessions.md: ffa4c8a07bdd08ca52edbc14fe10372ad76e8cf8
-2026-07-31-permission-default-for-new-sessions.zh.md: 5fc42724754acc1653ed93b48644794a38f52ba7
+2026-07-31-permission-default-for-new-sessions.zh.md: 0b994a3bf35d02ecc581c82591df624e50c00b2e
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
index 5fc4272475..0b994a3bf3 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
@@ -30,6 +30,6 @@ ApiProxy 在可配置提供方 namespace 之外，将 `permission` 显式加入
 
 **创建时只记录 `permission/preset`。** 不予采纳，因为沙箱和审批是由不同组件独立拥有的全量值调节项；固定全部三个事实，可以让其消费方不依赖未来的组合默认值变化。
 
-**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 契约超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
+**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 约定超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
 
 **恢复带 seed 的会话时应用最新默认值。** 不予采纳，因为恢复操作必须保留会话先前的有效执行策略；缺失的旧版事实应从该策略中补齐。
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 7bcfa9f599..2d393ff905 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
 2026-07-31-telemetry-anonymous-user-id.md: 3c8e3324cb418eac48cb5ae780c55bbcbaf3caa1
-2026-07-31-telemetry-anonymous-user-id.zh.md: 9ff6cf35a90d4087b4ab75987dc9244210e3d46a
+2026-07-31-telemetry-anonymous-user-id.zh.md: 6ba1b7abe0f253fc91e7f8856d9dc9d1d961550b
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 9ff6cf35a9..6ba1b7abe0 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -20,7 +20,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | 并发首启 | `wx` 独占写裁决，落败方重读胜者 id | 覆盖常见并发（重读撞进胜者建档-写入微秒窗仍可能各持一 id 一次运行，下次启动收敛到落盘值——telemetry 级后果，接受） |
 | 丢失语义 | 文件被删 → 下次启动换新 id，接受丢失 | 匿名身份无恢复价值；可恢复性要求派生材料，与匿名冲突 |
 | 写失败 | best-effort 返回内存 id | telemetry 永不因 home 只读被阻塞 |
-| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 契约且涨 wire 体积 |
+| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 约定且涨 wire 体积 |
 | semconv 依赖 | 不引 `@opentelemetry/semantic-conventions` 包 | 一个字符串常量不值一个依赖 |
 | 落点 | `session-telemetry-otel` 包内模块，非公共 util 包 | 仓规「有第二个真实消费者才拆包」；sdk launcher 回流保留自有存储，无现实关联需求 |
 | 单独开关 | 无 | 身份跟随 telemetry 整体开关（`DSH_TELEMETRY_DISABLED`）；关 telemetry 即整体不报 |
@@ -30,7 +30,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | 被拒 | 一句话理由 |
 |---|---|
 | hostname/IP 哈希派生 id（此前口径） | 可反查即非匿名；随机 UUID 语义干净，用户裁决取代 |
-| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 契约或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
+| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 约定或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
 | 公用 util 包统一两条回流（初版实现） | 唯一现实消费者是 OTel backend；sdk launcher 换用它只是为统一而统一——用户复议收回，回流关联需求出现时再抽包 |
 | 复用 telemetry.json 不新建文件 | 文件名/JSON 格式把身份挂在 launcher 链路命名下；OTel 回流身份是独立事实 |
 | AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；config 里传运行时事实与部署配置混淆 |
diff --git a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml
index 025c838a7d..1346111448 100644
--- a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.md
 2026-07-31-third-party-memory-mcp-examples.md: e82d65a3a5a60cafcc47df5a6873cf5768cd8b8f
-2026-07-31-third-party-memory-mcp-examples.zh.md: 18502f0c30fdbd62ffe49e34c587785d123046d2
+2026-07-31-third-party-memory-mcp-examples.zh.md: 512018b05bac6d175077d9dd82ebf8c328fc5a89
diff --git a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md
index 18502f0c30..512018b05b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 
 ## 版本固定、存储与身份
 
-| 提供方 | 已测试契约 |
+| 提供方 | 已测试约定 |
 |---|---|
 | Memorix | npm `1.3.0`，tag commit `500792cad3144142293bfbb20acb4841c9f7fcfa` |
 | MCP Reference Memory | npm `2026.7.4`，package commit `6dd0a683e198783e30feabf7abaf42f925bd18b1` |
@@ -49,7 +49,7 @@ Status: implemented
 
 提供方的工具描述仍然是权威定义。
 
-## 验证契约
+## 验证约定
 
 远程 CI 不会访问第三方服务或消耗密钥。无密钥套件解析全部三份 overlay 文件，检查其通用桥接器和密钥边界，将上游端点替换为包自带的 MCP fixture（测试前置数据）服务器，通过真实 Cordis Loader 启动，并验证工具发现。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
index 1c04bc1d55..7c42b6c7dc 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-default-search.md
 2026-07-31-web-default-search.md: 8f2cc6f5d1a9ec9f33279ae8e5c992bdc660e7fa
-2026-07-31-web-default-search.zh.md: 7d528617143cb9756d0a4532bb1ed6a3a3e70ca8
+2026-07-31-web-default-search.zh.md: 46db167b84f8c1a10686a941b174008ebafc720d
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
index 7d52861714..46db167b84 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
@@ -16,7 +16,7 @@ DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据
 
 搜索端点与 chat completions 保持独立：`DEEPSEEK_SEARCH_BASE_URL` 覆盖 Anthropic 兼容基址，`DEEPSEEK_BASE_URL` 则继续配置会话请求。每次 `web_search` 都会发起一次辅助 DeepSeek Messages 调用，并携带原生搜索服务器工具。发出请求前一刻，提供方会向发起请求的 agent（智能体）会话追加仅用于日志的 LLM（大语言模型）请求事件 `web/deepseek-search-llm-request`，其中包含已解析端点、API 版本，以及不含密钥的精确 JSON 请求体。凭据预检仍留在提供方内部，并与调用方取消存在竞态；这两项关注点都不会扩展通用 Web seam 或凭据 seam。
 
-默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有契约。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
+默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有约定。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index c1cc57b233..dc6aad3b11 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
 2026-07-31-web-workspace-file-links.md: fe71a2d8caa4dc9cc732a250d7e388d1a3b44182
-2026-07-31-web-workspace-file-links.zh.md: 0f8c87822087169aad9ac4283f706fd8a8748be9
+2026-07-31-web-workspace-file-links.zh.md: d2e49f4816a014dd5ec700b4d6f8fa0bede03e67
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 0f8c878220..d2e49f4816 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状契约。
+- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状约定。
 - **同源 HTTP 提供且不加隔离**——经实测不安全，记录在此以免有人重试：与 `/api` 并排提供的文档把 `settings.describe` 打到 `200` 并拿到完整数据，把 `session.list` 打到 35 KB 的全部会话转录，而这个页面根本不必由 agent 撰写（一条 read 行就让 clone 下来的仓库里任何文件变得可打开）。
 - **在那套同源提供之上加 `Content-Security-Policy: sandbox`**——它以剥夺文档的源来堵住这个洞，而这经实测会破坏本功能存在的意义所在的那类页面：所报告的产物在加载时抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们渲染得完美无缺，所以这种破坏是看不见的。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它。
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
index d4ec255235..fb9f46c641 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.md
 2026-08-01-pwsh-tool-and-executor.md: 7206f8ffe6640f8499f8453c40ab5846b23112c6
-2026-08-01-pwsh-tool-and-executor.zh.md: 5a48adb79fed209d2d2ecb9514fd51538491f04c
+2026-08-01-pwsh-tool-and-executor.zh.md: c59ba8e3e6c68d48d310861325c74dc6cec8e5c3
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
index 5a48adb79f..c59ba8e3e6 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
@@ -13,7 +13,7 @@ harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能
 在 `packages/bash/` 下新增两个包：
 
 - **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 从配置默认化并设上限，`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为 ONE argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
-- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，契约是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
+- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，约定是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
 
 Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
 
@@ -23,13 +23,13 @@ Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道
 
 **给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号实情、引号域）应各自归入自己包的文档。
 
-**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型契约保持诚实。
+**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型约定保持诚实。
 
 **现在就接入交付的 CLI 组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接线点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
 
 ## 后果
 
-- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范契约一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
-- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 契约。
+- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范约定一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
+- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 约定。
 - Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态实情仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
 - CLI 增加两个 workspace 依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index 40e24e9ac2..602d272b0b 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
 2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
-2026-08-02-pwsh-tool-bash-parity.zh.md: d7a68f0cab5281b25c3321e7ffff61c358b21a0a
+2026-08-02-pwsh-tool-bash-parity.zh.md: c6e1d69bd061f0794b125e225d8f976bd82224e7
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index d7a68f0cab..c6e1d69bd0 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见契约与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
+首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见约定与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
 
 ## 决策
 
@@ -20,9 +20,9 @@ Status: implemented
 
 ## 备选方案
 
-**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本契约在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
+**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本约定在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
 
-**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对契约改由各工具 README 记录。
+**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对约定改由各工具 README 记录。
 
 **提取完全共享的工具实现基座（抽象 shell 方言，两个薄叶子）。** 考虑后推迟：bash-env 提取与结构镜像（`render.ts`/`background.ts` 孪生）是它要立足的基础；在出现第三种方言或持久 PTY 孪生、让抽象的形态可观察之前，不做完整基座。
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
index c12de68dc8..484df46a31 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
 2026-08-02-web-thinking-tail-scroll.md: 18e94b2e0075bf7099b9b48177de2e274896942a
-2026-08-02-web-thinking-tail-scroll.zh.md: 9b1428af7d3ab3c25509696619de75adc1cd7b7f
+2026-08-02-web-thinking-tail-scroll.zh.md: 7bafeb0f64f05a41c502aba8f479e391c8b395f0
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
index 9b1428af7d..7bafeb0f64 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
@@ -12,7 +12,7 @@ Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠
 
 只有 reasoning block 是当前流式尾部、且仍处于折叠态的 Think 行会跟随实时输出。其摘要使用最新的非空行，而不是结算后的首行；已有单行摘要元素成为程序化横向滚动区，每次文本更新后钉到 `scrollWidth - clientWidth`。这里刻意直接赋值 `scrollLeft`，通过真实 delta 推进而不虚构独立的跑马灯速度：token 快则移动快，模型停顿则停止，短文本因滚动范围为零而保持静止。
 
-该行为由已有呈现组件拥有。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经拥有折叠／展开状态，因此由它决定摘要是否追随行内末端。不改变 session、wire、持久事件或模型可见契约。展开会移除折叠摘要，并让完整 reasoning 正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
+该行为由已有呈现组件拥有。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经拥有折叠／展开状态，因此由它决定摘要是否追随行内末端。不改变 session、wire、持久事件或模型可见约定。展开会移除折叠摘要，并让完整 reasoning 正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
 
 ## 曾考虑的替代方案
 
@@ -28,4 +28,4 @@ Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠
 
 ## 测试
 
-`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要约定仍然稳定。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 2ba0af23c4..7d6edc23db 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
 2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
-2026-08-03-web-search-source-scroll.zh.md: cf75a5e34632872d09a13e1667ecac5f01428e18
+2026-08-03-web-search-source-scroll.zh.md: 88f2ef9869ef5de7483eb0d7e2a76f8c14e8356b
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index cf75a5e346..88f2ef9869 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 模型侧不变：seam 仍在 `searchMaxResults` 处封顶来源，面向模型的 render 文本未动，`truncated` 标志及其 `来源列表已截断` 指示保留。卡片完整且可滚动地画出 seam 产出的这份列表，而非折叠其中段。
 
-只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的契约是它收到的 view，不是模型的上下文。
+只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的约定是它收到的 view，不是模型的上下文。
 
 `CHAT_WEB_MAX_SOURCES` 与该 primitive 的 `DEFAULT_WEB_MAX_SOURCES` 被移除：有了滚动，聊天行与详情面板展示同一份完整列表，仅以各自的容器高度区分。`<li value={ordinal}>` 仍钉住每条来源从 1 起算的引用序号；没有了折叠造成的间断，这些序号如今就是连续的。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
index 4673ffaab7..a15dbc2234 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
 2026-08-04-claude-code-and-codex-subagent-backends.md: e81d1fb14f719331c503dba539d6a5ec0f1eed4f
-2026-08-04-claude-code-and-codex-subagent-backends.zh.md: 3c78e8d5a4ca1a86942971721ad05c631901f231
+2026-08-04-claude-code-and-codex-subagent-backends.zh.md: ae5bb9f93dc027e7e6e59912b7e2ef00095a2162
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
index 3c78e8d5a4..ae5bb9f93d 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
@@ -55,7 +55,7 @@ Codex 0.146.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端
 
 启动回滚和已发布运行的资源释放都会关闭 SDK query、中止该次运行的控制器、调用共享的进程树终止机制，并等待整棵进程树退出。`Query.close()` 表达优雅的协议关闭意图，但不能取代子进程责任方的退出证明。Query 关闭失败、进程失败和清理失败仍可彼此独立地观察。
 
-带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 契约：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
+带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 约定：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
 
 ## 分发与证据
 
@@ -83,11 +83,11 @@ Claude Code 证据锁定 Agent SDK 0.3.220 及其平台分发的 Claude Code 2.1
 
 **由插件管理登录、产品主目录、模型、设置或权限。** 这些选择会在每个产品的原生配置之外建立另一套权威来源，并将一次性提供方扩张为账户管理功能。提供方只公开显式环境覆盖项和清理宽限期；无人值守交互会以默认拒绝方式失败。
 
-**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户契约，当前实现不会预先构建这些功能。
+**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户约定，当前实现不会预先构建这些功能。
 
 ## 后果
 
-用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 契约委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
+用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 约定委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
 
 每次委派都要承担新建产品进程和独立模型上下文的开销，且只有最终文本会到达父级。产品原生配置使行为取决于部署环境中安装的产品、账户状态和工作区设置。带密钥 e2e 运行还会消耗外部 API 配额，并依赖 DeepSeek 官方端点；对协议、失败、取消与审批的确定性覆盖仍由无密钥层级承担。提供方不会恢复会话、以流式方式传送进度、接受新的人工交互、回滚工具或文件副作用，也不会施加按实际经过时间触发的超时。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
index 86c05dc9bd..4710d92679 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
 2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 598c10dc2373eeb821d05f349a662156b194c71b
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 4f871a70298396b8ed75b39c2a4d199b69061472
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
index 598c10dc23..4f871a7029 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定接缝：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
-这拓宽了重新绑定契约，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
+这拓宽了重新绑定约定，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
 
 隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何既滚动又绘制抬升表面的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 51401adfdc..439826ee6c 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
 2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
-2026-08-05-pwsh-ui-bash-parity.zh.md: 967c5a9e1409028043dc5028fdca640ddfeb1acc
+2026-08-05-pwsh-ui-bash-parity.zh.md: 40109a32ed146a31a2424feb53a7cf0f41d87106
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 967c5a9e14..40109a32ed 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -18,11 +18,11 @@ Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 ter
 
 ## Alternatives considered
 
-**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享契约放在两个工具本就依赖的包上。
+**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享约定放在两个工具本就依赖的包上。
 
 **新建专用呈现包（如 `@deepseek-ai/dsh-shell-present`）。** 否决：为一个纯函数新建包要付出 manifest、module-graph/目录再生成与 README 面的成本；`@deepseek-ai/dsh-bash` 已在两个工具的闭包中，且已拥有该解析重建的 `BashRunResult` 事实。
 
-**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本契约缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的契约。
+**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本约定缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
index 222ed1ebbe..d89233e8eb 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
 2026-08-06-bundled-dsh-badge-skill.md: 512f67ca347ca311a1f80fef932f6af8c91b0fe9
-2026-08-06-bundled-dsh-badge-skill.zh.md: 88fcadf66944cb91419441be3916ae04968be663
+2026-08-06-bundled-dsh-badge-skill.zh.md: cedb03325f3e963c3fa217b72dcfce31eb44bfe7
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
index 88fcadf669..cedb03325f 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 交付的 CLI 组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill（技能），也不会获得任何模型可见内容。
 
-该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级契约覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
+该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级约定覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 3fccf77cc4..fc6a76df8b 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
 2026-08-06-continuable-subagent-interrupt.md: cb97a77434b43ee71fa30deee9811f7a45c53f1a
-2026-08-06-continuable-subagent-interrupt.zh.md: ee05afd963584331def8c7d6acfa26830b7c1d0f
+2026-08-06-continuable-subagent-interrupt.zh.md: e311cae0d5eecce508aba5351b1766282b294abb
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index ee05afd963..e311cae0d5 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,9 +39,9 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
+在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复只读替代（周边目录与 composer 约定由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
 
-`dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表契约由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
+`dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表约定由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
index 7550af746a..8f72736ce9 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
 2026-08-06-resolved-theme-color-metadata.md: 2f7a6f0bde5e75aeb6769939cae54d5319aa5bae
-2026-08-06-resolved-theme-color-metadata.zh.md: a6d530f841d5c744fc88831f9cb685d1ab5027b6
+2026-08-06-resolved-theme-color-metadata.zh.md: 0312794c607b59f4772d498e1533e0af70b9fbbe
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
index a6d530f841..0312794c60 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
@@ -16,7 +16,7 @@ ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根
 
 ## 验证
 
-呈现器的单元测试契约覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
+呈现器的单元测试约定覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
index d13ede02d2..000c72f6ed 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
 2026-08-06-web-install-manifest.md: d400c6e586f4b735fa8e3dcc4899c97e45ac89c1
-2026-08-06-web-install-manifest.zh.md: a7fee0248261e8d0597bb773d4f390973147337b
+2026-08-06-web-install-manifest.zh.md: d32ccf25c7b0e13a4094af4364a97385032462b7
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
index a7fee02482..d32ccf25c7 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线契约，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
+Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线约定，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
 
 ## 决策
 
@@ -24,7 +24,7 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 曾考虑的替代方案
 
-**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线契约。
+**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线约定。
 
 **声明单一的 `lang`。** 不予采纳，因为没有任何一种语言足以描述双语产品界面；省略该字段可避免声称安装后的体验由某一种区域设置独占。
 
@@ -36,4 +36,4 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 后果
 
-支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物契约。
+支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物约定。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 7ea7b3b14f..55ce6ceeb9 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
 2026-08-06-web-skill-tool-row.md: 04e8ffcd6e506142b569e60458af144233810bbd
-2026-08-06-web-skill-tool-row.zh.md: b96b3879f989f4f1934cdffaec83a283d74aa220
+2026-08-06-web-skill-tool-row.zh.md: c68ddea1d44e3b071deafc9450f6a2d09023cd80
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index b96b3879f9..c68ddea1d4 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -10,20 +10,20 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 ## 决策
 
-`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 契约，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
+`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 约定，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
 
 收起的行使用 14 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
-该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议契约。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议约定。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
 ## 考虑过的替代方案
 
 - 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
 - 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会增加协议和快照表层，却不会支持其他消费方。
-- 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
+- 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露约定而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
 
 ## 后果
 
-除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
+除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 约定、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
 
 即使已安装的 skill 目录发生变化，冷回放仍保持确定性；在用户显式展开指令前，transcript 保持紧凑。仅含结果的 history 页有意使用通用后备路径；让这个边缘情况保持通用呈现，可以保留现有 history 协议，并将该功能限定在客户端呈现层。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index bc2d1575ee..145c1cf619 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
 2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: 7b48dfd708efb197babcfcbeaf4f8a4ca76cde3f
+2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index 7b48dfd708..afb18fea6a 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -26,7 +26,7 @@ dsh run [--profile <name>] [--patch <path>...] <task...>
 
 `run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
 
-运行器面向用户的契约保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 契约。
+运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index a126f8c0d0..4b85d13e3d 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-17-ts-build-config.md
 2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
-2026-06-17-ts-build-config.zh.md: 41791129647b6a5bfeb966e05ee2c5b9132c45ef
+2026-06-17-ts-build-config.zh.md: 80b051cd5fb76672d4c056d1b6321029897225e8
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 4179112964..80b051cd5f 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-17-ts-build-config.md) | 中文
 
-> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 契约后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
+> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 约定后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
 
 ## 问题
 
@@ -76,7 +76,7 @@ tsx scripts/clean.ts
 
 构建职责更加清晰：
 
-- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成契约顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成约定顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
 - `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布 runtime bundle。
     - `lib/types/*.d.ts` 是发布用的声明输出；`.d.ts.map` 只作为本地编译产物保留。
     - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 6f51f73b00..483a429f97 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
 2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
-2026-06-20-core-data-structures-catalog.zh.md: 895f639446bc6c4e0fecbf1085197ba8b1810282
+2026-06-20-core-data-structures-catalog.zh.md: a1184cb25823c10949713271434628c3650678dd
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 895f639446..a1184cb258 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 
 ### `ts type-equiv` 机制——既逐字又防漂移
 
-持久性要求很具体：文档展示当前类型声明与原始 JSDoc 的**逐字**内容（让读者看到真实形状和源码契约，而非复述），**并且**以机械方式保证其与源码匹配。仓库已经会编译 ` ```ts ` 围栏块（`doc-typecheck`），但真正接受类型检查的块需要导入噪音，而且只能证明*可赋值性*——字段改名或 JSDoc 变化仍可能通过。因此：
+持久性要求很具体：文档展示当前类型声明与原始 JSDoc 的**逐字**内容（让读者看到真实形状和源码约定，而非复述），**并且**以机械方式保证其与源码匹配。仓库已经会编译 ` ```ts ` 围栏块（`doc-typecheck`），但真正接受类型检查的块需要导入噪音，而且只能证明*可赋值性*——字段改名或 JSDoc 变化仍可能通过。因此：
 
 - 完整的类型声明及其 JSDoc 会逐字粘贴到专用的 ` ```ts type-equiv ` 围栏中。简洁的 ` ```ts public-api ` 围栏承载类的源码等价环境声明投影，用于实现体不应进入目录的类。`doc-typecheck` 会识别并跳过这两种围栏（裸声明无法独立编译），并且**将它们排除在 opt-out 比例之外**——它们是单独受检的类别，而不是未经检查的草图。
 - 新增的 `scripts/verify-type-equiv.ts` 通过 TypeScript 解析器提取每个块，并断言其声明结构和每条 JSDoc 注释都与所声明的符号匹配，只忽略格式空白和非 JSDoc 注释。普通块保留完整声明。`public-api` 投影保留类的公共字段、构造函数、访问器和方法及其原始 JSDoc，同时移除实现体以及私有或受保护成员。之所以选择它而非编译式 `_Check` 断言，是因为目录所保留的是源码名称与文档一致性，而不是可赋值性。
@@ -45,7 +45,7 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与 seam 结构胜出。
-- **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或契约注释变化仍会通过。
+- **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或约定注释变化仍会通过。
 - **来源信息作为行文中的指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
 
 ## 验证教训
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 9e69041e2e..ce56c983fd 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
 2026-07-02-bilingual-docs-and-pairing-gate.md: 8e9d0ab8653528517346b198c97814d8d8979440
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: e8f18ebb0d1620830116f6d5d9ffef29664a578e
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: dbcf453d49237029d28cfc6f6651ffd14752a4f3
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index e8f18ebb0d..dbcf453d49 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 
 ## 验证
 
-验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
+验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
index dec5dcfafd..ba3b6a970d 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
 2026-07-04-doc-tiers-and-budgets.md: e7b3421d09a1ae5ab9a9373e8040832c1b0d4b97
-2026-07-04-doc-tiers-and-budgets.zh.md: 157ad13f521d2a497180e25b70e3537a4afbc099
+2026-07-04-doc-tiers-and-budgets.zh.md: 3bc04ae73a4d8c9c005e154a236772fc1845389e
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
index 157ad13f52..3bc04ae73a 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
@@ -14,13 +14,13 @@ Status: implemented
 - **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。
 - **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其词数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
 - **上限是只进不退的执行红线。** 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根 `AGENTS.md` ≤ 1,600 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600，但 `packages/AGENTS.md` ≤ 650、`docs/AGENTS.md` ≤ 1,250；`packages/README.md` ≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。
-- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
+- **精简的工作流 skill（技能），约定归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 约定之间的分工相同。
 
 ## 曾考虑的替代方案
 
 - **仅靠 skill 和评审纪律，不设门禁**：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有自动化保障的行文规则在此处已被证明无法维持，而本仓库自身的[质量门禁立场](2026-06-11-quality-gates.md)认为值得保持的不变式就值得编码。
 - **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如功能矩阵或类型目录，每一行都是事实），并产生逐文件的例外变更，训练贡献者机械地批准提限。
-- **将标准放在 skill 内部**：否决。契约归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。
+- **将标准放在 skill 内部**：否决。约定归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
index 040772a879..3b2ed0f39d 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
 2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
-2026-07-05-uniform-agent-note-format.zh.md: 8f874f26c43a88ec3d2f1185c7b4d6f2f39ba1bb
+2026-07-05-uniform-agent-note-format.zh.md: a13c436a3fa157a0bfe551a7ed0594d052a4de90
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
index 8f874f26c4..a13c436a3f 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
@@ -6,24 +6,24 @@ Status: implemented
 
 ## 问题
 
-Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着不同标题、状态格式、ADR 与提案模板，以及已实现记录中的提案阶段章节。作者会复制随手找到的相邻文件，而生命周期迁移可能跳过必要的改写，因为没有门禁强制执行文件内契约。
+Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着不同标题、状态格式、ADR 与提案模板，以及已实现记录中的提案阶段章节。作者会复制随手找到的相邻文件，而生命周期迁移可能跳过必要的改写，因为没有门禁强制执行文件内约定。
 
 ## 决策
 
-[README.md § 文件格式](../../README.md#the-file-format)是文件内契约——头部块（`# Agent Note: <title>`，加上无日期且与文件夹一致的 `Status:` 枚举，其中只有拒绝原因可作为额外内容）、各生命周期的正文骨架（所有文件均以 `Problem` 开篇；`proposed/` 使用 `Proposal`/`Acceptance criteria`/`Risks`；`implemented/` 使用现在时的 `Decision`/`Consequences`，并禁止提案阶段标题；`rejected/` 冻结提案结构）、强制的 `Alternatives considered` 章节，以及规范章节词汇；定制技术章节可在这些规范章节之间保持自由形式。`pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../../../scripts/verify-agent-note-format.ts)）作为 `doc-sync` 的一部分强制执行每项机械规则，因此跳过改写的生命周期迁移现在会使 CI 失败，而不再依赖评审者记忆。
+[README.md § 文件格式](../../README.md#the-file-format)是文件内约定——头部块（`# Agent Note: <title>`，加上无日期且与文件夹一致的 `Status:` 枚举，其中只有拒绝原因可作为额外内容）、各生命周期的正文骨架（所有文件均以 `Problem` 开篇；`proposed/` 使用 `Proposal`/`Acceptance criteria`/`Risks`；`implemented/` 使用现在时的 `Decision`/`Consequences`，并禁止提案阶段标题；`rejected/` 冻结提案结构）、强制的 `Alternatives considered` 章节，以及规范章节词汇；定制技术章节可在这些规范章节之间保持自由形式。`pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../../../scripts/verify-agent-note-format.ts)）作为 `doc-sync` 的一部分强制执行每项机械规则，因此跳过改写的生命周期迁移现在会使 CI 失败，而不再依赖评审者记忆。
 
 定义该格式的同一变更规范化了整个语料库——遵循预发布立场：不设过渡期，不容忍双格式。唯一适用既有内容豁免的是内容，而非格式：替代方案只能记录、不能杜撰，因此若某份格式制定前的 Agent Note 无法从记录中还原替代方案，就会带有内容完全匹配 `agent-note-format: alternatives-not-recorded` 的注释；门禁只对日期早于本文的文件接受该注释。
 
 ## 曾考虑的替代方案
 
-- **完整的刚性模板**（每个生命周期使用固定章节顺序，重构每份 Agent Note 以适配）：否决。大型设计 Agent Note 包含八到十五个定制技术章节（包拓扑、协议契约、schema），它们是承载设计的内容，而非漂移；刚性顺序会迫使我们现在进行破坏性改写，并永远与模板较劲。
+- **完整的刚性模板**（每个生命周期使用固定章节顺序，重构每份 Agent Note 以适配）：否决。大型设计 Agent Note 包含八到十五个定制技术章节（包拓扑、协议约定、schema），它们是承载设计的内容，而非漂移；刚性顺序会迫使我们现在进行破坏性改写，并永远与模板较劲。
 - **仅规范化头部**（H1 和 Status，正文不动）：否决。债务标记指出的是*正文*的体裁分裂，让 `Context`/`Decision` 与 `Problem`/`Proposal` 无限期并存什么也解决不了。
 - **不设 Status 行**（文件夹已经表示状态；格式制定前最新的三份 Agent Note 及其中一份的中文对应文件省略了该行）：否决，保留文件的自描述性。通过门禁校验该行与文件夹一致，消除了原本促使我们删除它的漂移风险。
 - **带日期的 Status**（`Status: implemented (accepted YYYY-MM-DD)`）：否决。接受日期属于叙述性历史，写作规则将其排除在文档之外；文件名承载首次提出日期，git 承载其余信息；门禁能检查日期格式，但永远无法检查其真实性。
 - **裸 `# <title>` H1**：否决。文件脱离目录树单独阅读时，`Agent Note: ` 前缀能自描述其体裁，而格式门禁可防止它漂移。
 - **以 `## What we give up` 作为已实现记录的结尾**（README 对 Agent Note 所记录内容的原有表述）：否决。它只点出成本，而诚实的后果章节也会记录取舍换来了什么。
-- **只有约定没有门禁**（写下契约，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
-- **独立的 `FORMAT.md` 契约文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个契约文件更易发现和维护。
+- **只有约定没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
+- **独立的 `FORMAT.md` 约定文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个约定文件更易发现和维护。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
index 8c2e77710e..d9660ac47d 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
 2026-07-06-export-surface-jsdoc-gate.md: 821f68ebe60eba44cade223b3bc8286e09740956
-2026-07-06-export-surface-jsdoc-gate.zh.md: 5f5f7b70a486b0aa5e8e7fd07810dfbcfb719a50
+2026-07-06-export-surface-jsdoc-gate.zh.md: ec5bf67ccbfe9fcc1996aa47177c2d9b1145cd67
diff --git a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
index 5f5f7b70a4..ec5bf67ccb 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
@@ -12,14 +12,14 @@ Status: implemented
 
 新增门禁 `scripts/verify-export-jsdoc.ts`（`pnpm run verify-export-jsdoc`，接入 `doc-sync`（文档同步门禁），与 `verify-cordis-catalog` 并列），遍历每个 `packages/<group>/<pkg>/src/` 目录树下的所有模块级导出名称。解析与检查辅助函数从 `gen-cordis-catalog.ts` 移入共享的 `scripts/jsdoc.ts`，使得「已文档化」在两类接口上含义一致：描述性文字在第一个块标签处截止、每个可检查参数需要非空 `@param`、非 void 且有显式标注的返回值需要非空 `@returns`、过时的 `@param` 报错，违规项汇总为一份报告。
 
-按声明类型划分的契约：
+按声明类型划分的约定：
 
 - 每个导出名称都需要带有非空描述文字的 JSDoc。
-- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数契约，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名契约推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是对外签名，适用完整契约；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
-- 导出类需要类级别的描述文字；公开方法（包括静态方法——可通过导出名称访问）遵循函数契约；公开属性和访问器需要描述文字（get/set 对由 getter 覆盖）。重载实现体免检——签名承载文档。
-- 导出接口、类型别名和枚举需要声明级别的描述文字；成员级别的强制有意推迟（承载关键成员契约的 seam 服务类已在 Cordis 门禁之下）。
+- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数约定，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名约定推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是对外签名，适用完整约定；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
+- 导出类需要类级别的描述文字；公开方法（包括静态方法——可通过导出名称访问）遵循函数约定；公开属性和访问器需要描述文字（get/set 对由 getter 覆盖）。重载实现体免检——签名承载文档。
+- 导出接口、类型别名和枚举需要声明级别的描述文字；成员级别的强制有意推迟（承载关键成员约定的 seam 服务类已在 Cordis 门禁之下）。
 - 导出命名空间递归检查（在 ambient `declare` 命名空间内，每个成员隐式导出）；命名空间本身仅在不与同名的已文档化声明合并时才需要描述文字（Config-namespace 惯用法只需文档化插件一次）。
-- `declare module`/`declare global` 体和 `export … from` 重导出语句被跳过：augmentation 不是包的导出，重导出的定义在其定义处检查。`export import X = N.member` 别名需要文档化自身——其目标可能是遍历不会访问的非导出命名空间成员——且门禁仅支持纯描述文字的目标类型：可调用、类或命名空间目标携带别名描述文字无法承载的签名/成员契约，门禁会拒绝并要求直接导出该声明。
+- `declare module`/`declare global` 体和 `export … from` 重导出语句被跳过：augmentation 不是包的导出，重导出的定义在其定义处检查。`export import X = N.member` 别名需要文档化自身——其目标可能是遍历不会访问的非导出命名空间成员——且门禁仅支持纯描述文字的目标类型：可调用、类或命名空间目标携带别名描述文字无法承载的签名/成员约定，门禁会拒绝并要求直接导出该声明。
 - 其余情况一律默认拒绝：`export =` 直接拒绝；即使参数使用绑定模式，只要基类未为其命名，仍需 `@param`；dispatch 不识别的导出语句类型本身就是违规——没有任何导出形式能因遗漏而免检。
 
 三类豁免避免门禁要求样板代码，精神与 Cordis 门禁的 `this`/`next` 豁免一致（为已豁免的名称编写文档是允许的；只有缺失才不被检查）：
@@ -32,9 +32,9 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的契约。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
+- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的约定。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
 - **扩展 `gen-cordis-catalog.ts`**：catalog 生成器渲染一个精选表面并守卫其新鲜度；仓库级遍历没有 catalog 可渲染。共享辅助函数、保持遍历独立，使每个门禁的职责清晰可读。
-- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而检查对象大多只是含义直观的字段；承载关键成员契约的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
+- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而检查对象大多只是含义直观的字段；承载关键成员约定的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
index ddca590dea..2a4cdaedae 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
 2026-07-06-node-engine-floor.md: ad21fbfe034cbf4bb7b75aaac4113f3139a1832d
-2026-07-06-node-engine-floor.zh.md: 0d1c31ed74565f9b20116cd0e666246baad9bf79
+2026-07-06-node-engine-floor.zh.md: e2ef7a99a8c3045b00f4980953f0adbe4a788cfb
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
index 0d1c31ed74..e2ef7a99a8 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-根 `engines.node` 范围中的 Node 22 分支是对安装后工作区的契约，而不仅仅是 harness 源码直接调用的运行时 API 的契约。它不得低于工作区在该分支上安装的依赖包所声明的 `engines.node`；否则 `pnpm install --engine-strict` 会在一个已宣传的 LTS 版本上失败，而非严格模式下的安装结果则会在依赖所支持的运行时范围之外运行。
+根 `engines.node` 范围中的 Node 22 分支是对安装后工作区的约定，而不仅仅是 harness 源码直接调用的运行时 API 的约定。它不得低于工作区在该分支上安装的依赖包所声明的 `engines.node`；否则 `pnpm install --engine-strict` 会在一个已宣传的 LTS 版本上失败，而非严格模式下的安装结果则会在依赖所支持的运行时范围之外运行。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
index 2bfcddbf3b..091a912f94 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
 2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
-2026-07-12-package-model-experience-contract.zh.md: 34dd909adc6a3a5f4c9113df675d31012b836370
+2026-07-12-package-model-experience-contract.zh.md: 9fb6e36e75dcca43fd3ed450c364c57ae7fb7ca4
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
index 34dd909adc..9fb6e36e75 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 包的模型体验契约
+# Agent Note: 包的模型体验约定
 
 Status: implemented
 
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-每个具有面向模型或邻近模型契约的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无已知限制”允许列表中的包则以模型体验章节本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
+每个具有面向模型或邻近模型约定的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无已知限制”允许列表中的包则以模型体验章节本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
 
 具有直接、条件式、有上限、生命周期、多表面或辅助模型效应的包，为每个上下文表面使用一个 H3。每个表面包含三个有序 H4 字段——`What the model sees`、`Token effect` 和 `KV Cache effect`——每个字段都以一个正文段落开头。缓存字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、作用域、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺提供方一定能命中缓存或将其保留特定时长。由包拥有的稳定文本按原文精确引用：系统提示词正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 表面链接生成的[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由提供方拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏提示词与 schema 中的一者而不影响另一者时，两种表面保持分离。
 
@@ -21,13 +21,13 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **只记录注册提示词或工具的包**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
-- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的契约；集中副本会增加又一个漂移面。
-- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的契约是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
+- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的约定；集中副本会增加又一个漂移面。
+- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的约定是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
 - **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
 - **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
 - **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
-- **只有约定而无门禁**：否决。仓库级契约必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
+- **只有约定而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
 
 ## 后果
 
-评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起请求前缀变化的位置。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性契约保持稳定。
+评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起请求前缀变化的位置。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性约定保持稳定。
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
index 07e0a89d0f..36f6181c46 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
 2026-07-13-documentation-site-projection.md: d9af915754fa6a1df51a27d18d412597472aaa73
-2026-07-13-documentation-site-projection.zh.md: 5b6de4b3425b6d20335a0f8055468ced414d4034
+2026-07-13-documentation-site-projection.zh.md: 7d7b4752b8f27d55aae8426a7dc001ce4340e661
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
index 5b6de4b342..7d7b4752b8 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
@@ -40,7 +40,7 @@ Mermaid 渲染权威图表。网站工作区显式声明 `vitepress-plugin-merma
 
 **只在部署工作流中构建。** 部署作业可以在合并后发现渲染故障。把生产构建纳入 `doc-sync`，则无论是否存在公开部署，同一个故障都能在本地和常规 CI 中暴露。
 
-**硬编码公开项目路径。** 固定的 `/deepseek-harness/` base 适用于公开项目 URL，却不适用于私有 Pages 站点分配的唯一源站，也不适用于未来的自定义域名。使用 Pages 元数据可让这些目标位置共享同一份构建契约。
+**硬编码公开项目路径。** 固定的 `/deepseek-harness/` base 适用于公开项目 URL，却不适用于私有 Pages 站点分配的唯一源站，也不适用于未来的自定义域名。使用 Pages 元数据可让这些目标位置共享同一份构建约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
index 6c243f94db..b6d2cad8df 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md
 2026-07-14-typescript-program-backed-semantic-gates.md: 91639d53b660c68ae52c7ddcef6b3f594e82273e
-2026-07-14-typescript-program-backed-semantic-gates.zh.md: 65e19ba2bd34c2411a2e5ca64dfc85f9bf18cfb3
+2026-07-14-typescript-program-backed-semantic-gates.zh.md: 2ccb6a95185e1f666359b8b864f6ad655070a47f
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
index 65e19ba2bd..2ccb6a9518 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
@@ -40,7 +40,7 @@ Context 与 AgentEventDispatch 调用只贡献由字符串字面量构成的有
 
 恰好一个匹配项会生成解析函数。存在多个匹配项时，含义不明确，生成器会失败。没有匹配项时，事件必须标记 `@dshScopeScan unsupported`；该标记只用于路由键有意留在事件参数之外的情况，例如按所属 agent（智能体）路由的会话事件和按父 agent 路由的 subagent 生命周期事件。此标记只表示扫描不受支持，不编码事件名、参数下标、属性路径或替代类型。
 
-提交到仓库的 [`scoped-events.generated.ts`](../../../../packages/core/scope/src/scoped-events.generated.ts) 是位于 scoped dispatch 所属包中的纯运行时映射，不导入任何事件声明方包。语义完整性由生成器自身保证：根 Program 枚举所有 scoped `Events` 声明与真实 `scopeTarget` 契约，通过 checker 解析唯一的 payload 路径，并在渲染 `unknown[]` 运行时边界前拒绝缺失、陈旧或含义不明确的条目。
+提交到仓库的 [`scoped-events.generated.ts`](../../../../packages/core/scope/src/scoped-events.generated.ts) 是位于 scoped dispatch 所属包中的纯运行时映射，不导入任何事件声明方包。语义完整性由生成器自身保证：根 Program 枚举所有 scoped `Events` 声明与真实 `scopeTarget` 约定，通过 checker 解析唯一的 payload 路径，并在渲染 `unknown[]` 运行时边界前拒绝缺失、陈旧或含义不明确的条目。
 
 `dsh-scope/invariant` companion 消费这份映射，不再维护手写事件表。Program 分析发生在仓库门禁内，而不是依赖生成的类型导入，因此 `dsh-scope` 和 `dsh-invariants` 都不需要依赖所有事件声明方。
 
@@ -59,7 +59,7 @@ Context 与 AgentEventDispatch 调用只贡献由字符串字面量构成的有
 ## 后果
 
 - 事件关系生成依据语义接收者身份和封闭事件值，不再依赖局部命名约定；
-- 带作用域的事件成员关系、主体提取和运行时不变式覆盖来自事件声明与真实 dispatch 契约，不再来自手写表；
-- 修改事件名、参数位置、主体属性或路由键类型时，会在其所属契约处触发生成失败；
+- 带作用域的事件成员关系、主体提取和运行时不变式覆盖来自事件声明与真实 dispatch 约定，不再来自手写表；
+- 修改事件名、参数位置、主体属性或路由键类型时，会在其所属约定处触发生成失败；
 - 构建扁平化 Program 比解析孤立文件消耗更多启动时间和内存，语义门禁也依赖有效的根项目图；
 - 生成的 TypeScript 仍属于提交到仓库的源码：事件声明方或 dispatch 形态发生变化后，必须重新生成该文件和受影响的文档。
diff --git a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
index 8297b3675e..ce16a025cc 100644
--- a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md
 2026-07-19-remove-generated-agent-note-index.md: ee85ec0757d5924f5784c43a50003eb96e0a9531
-2026-07-19-remove-generated-agent-note-index.zh.md: 7ace1c4f03d5ff3d1137fe611a5ec0ec2ae21b2f
+2026-07-19-remove-generated-agent-note-index.zh.md: 6e1967fbde0c6ac59bbc3a184dad68c989efadbc
diff --git a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md
index 7ace1c4f03..6e1967fbde 100644
--- a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md
+++ b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-按生命周期／类别组织的文件系统目录树就是 Agent Note 清单。[README.md](../../README.md) 继续作为人工维护的入口和契约，普通的目录树浏览与仓库搜索负责内容发现。
+按生命周期／类别组织的文件系统目录树就是 Agent Note 清单。[README.md](../../README.md) 继续作为人工维护的入口和约定，普通的目录树浏览与仓库搜索负责内容发现。
 
 `scripts/agent-note-tree.ts` 持有封闭的生命周期／类别集合与结构遍历器。`verify-agent-note-classification` 校验该目录树，并拒绝旧目录和根目录中的 `INDEX.md`，但不会渲染集中式清单或检查其新鲜度。
 
diff --git a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml
index fa3294857a..38c49d2a4f 100644
--- a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.md
 2026-07-19-require-agent-notes-for-non-trivial-changes.md: 162ae61affb4c1b0ad526fa0da41f84ebbb02089
-2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md: 1578312ba43bfc79fe50841aaf651da6f0771fb9
+2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md: f1bf434f78bf10f020089d2e1990874f72a1c082
diff --git a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md
index 1578312ba4..f1bf434f78 100644
--- a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md
+++ b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 ## 决策
 
-每项实质性变更都在同一个 PR（Pull Request）中新增或更新至少一份 Agent Note。实质性变更包括行为、架构、跨文件或跨包契约、流程或工具、测试策略、磁盘格式、协议格式（wire format）或配置格式，以及维护者可能合理重审的其他决策。
+每项实质性变更都在同一个 PR（Pull Request）中新增或更新至少一份 Agent Note。实质性变更包括行为、架构、跨文件或跨包约定、流程或工具、测试策略、磁盘格式、协议格式（wire format）或配置格式，以及维护者可能合理重审的其他决策。
 
-更新已经持有该决策的 Agent Note 即满足规则；仅当没有 Agent Note 持有该决策时才新增记录。完全机械或局部、且不改变行为、契约、结构、流程或决策依据的编辑可豁免。[Agent Notes README](../../README.md#when-to-write-one) 持有这条边界，根目录 `AGENTS.md` 则携带常驻指令。
+更新已经持有该决策的 Agent Note 即满足规则；仅当没有 Agent Note 持有该决策时才新增记录。完全机械或局部、且不改变行为、约定、结构、流程或决策依据的编辑可豁免。[Agent Notes README](../../README.md#when-to-write-one) 持有这条边界，根目录 `AGENTS.md` 则携带常驻指令。
 
-只有在当前持有该决策的记录保存了所有独有的决策依据、备选方案、影响、验证契约和明确指出的覆盖缺口后，才可将被完全取代的 implemented Agent Note 合并到该记录中并删除。同一变更还要修复入站链接，并删除中文对侧文件和伴随记录。仅部分被取代时，两个记录仍需互相链接并保持与现状一致；合并既不将旧决策改写成与其相反的决策，也不让 git 历史成为决策依据的唯一副本。
+只有在当前持有该决策的记录保存了所有独有的决策依据、备选方案、影响、验证约定和明确指出的覆盖缺口后，才可将被完全取代的 implemented Agent Note 合并到该记录中并删除。同一变更还要修复入站链接，并删除中文对侧文件和伴随记录。仅部分被取代时，两个记录仍需互相链接并保持与现状一致；合并既不将旧决策改写成与其相反的决策，也不让 git 历史成为决策依据的唯一副本。
 
-后续决策完全移除较早的功能时，只有该功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行，移除记录才会成为当前持有记录。移除决策的依据和验证该功能已不存在的测试可以保留。它必须保留该功能的最初动机、为什么该动机已不足以证明继续保留该功能、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。只描述已删除行为的实现清单和测试已经过时，不属于当前验证契约。仅移除一种传输、默认值、实现或展示仍属于部分取代。
+后续决策完全移除较早的功能时，只有该功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行，移除记录才会成为当前持有记录。移除决策的依据和验证该功能已不存在的测试可以保留。它必须保留该功能的最初动机、为什么该动机已不足以证明继续保留该功能、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。只描述已删除行为的实现清单和测试已经过时，不属于当前验证约定。仅移除一种传输、默认值、实现或展示仍属于部分取代。
 
 评审负责执行这条语义边界。自动化门禁不尝试把差异分类为平凡或实质性变更，因此这项政策不会增加门禁阶段或运行时间。
 
@@ -26,7 +26,7 @@ Status: implemented
 
 **每项变更都必须新增 Agent Note。** 当现有 Agent Note 已经持有该决策时，这会产生重复记录，也会让纯机械编辑承担空洞的流程负担。
 
-**永久保留每份被完全取代的 Agent Note。** 只要旧决策仍有部分适用，就需要保留互相链接的记录；但完全失效的 implemented Agent Note 与记录当前状态的契约相矛盾，并重复保存本可由一个记录持有的决策依据。
+**永久保留每份被完全取代的 Agent Note。** 只要旧决策仍有部分适用，就需要保留互相链接的记录；但完全失效的 implemented Agent Note 与记录当前状态的约定相矛盾，并重复保存本可由一个记录持有的决策依据。
 
 **新增 `superseded/` 生命周期。** 新增生命周期仍会保留过时记录并扩张目录树、格式门禁和维护规则，却无法减少重复内容。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 - 每项实质性变更都会在实现旁保留其决策依据和被放弃的备选方案。
 - 贡献者维护现有的决策持有记录，而不是创建重复记录。
-- 被完全取代的记录可以归并到一个当前持有记录中，同时不丢失其独有的决策依据或验证契约。
+- 被完全取代的记录可以归并到一个当前持有记录中，同时不丢失其独有的决策依据或验证约定。
 - 后来被移除的功能可以只有一个当前持有记录，而无需继续保留过时的实现与测试清单。
 - 仅部分被取代的情况仍需明确记录并互相链接；删除记录则必须在同一变更中清理链接和双语配对。
 - 机械编辑仍保持轻量，门禁拓扑和运行时间也保持不变。
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
index 6189729de0..bafe5adfdf 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
 2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39
-2026-07-20-gui-testing-system.zh.md: af4736ced6195dfc8d40ab276149490e8af94975
+2026-07-20-gui-testing-system.zh.md: bd617f39a7cd5fd49e5c3a8a992b7dff35a800bf
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
index af4736ced6..bd617f39a7 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -43,7 +43,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 - **修一个 bug 钉一条断言**：浏览器可见的 bug 钉进所属浏览器 spec（smoke 或 e2e 场景）；数据层 bug 钉进对应 spec（先例：res-close 误判钉在 webserver 桥 suite——纯 Node 秒级复现，不再需要 12s 浏览器哨兵作唯一防线）。
 - **fixture 全绿不算完，真 wire 也要过**：fixture 短路的恰是 wire 承载链（node:http 桥 close 语义、真网络时序），两次实证 bug 都藏在那里。改动触及连接/桥/handler/SSE 的，浏览器车道（`pnpm run test:web`）必跑——其无密钥 e2e 场景驱动真实 HTTP/SSE 承载，带密钥的真 host smoke 仍是真模型侧的补充。
-- 落盘代码即答案的对表工作流：行为改动落盘打红既有用例时，当场对表校准（改测试还是改代码以 RFC/契约为裁），不留悬红。
+- 落盘代码即答案的对表工作流：行为改动落盘打红既有用例时，当场对表校准（改测试还是改代码以 RFC/约定为裁），不留悬红。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index a1c49fdcae..02daf774f7 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
 2026-07-21-serial-cross-platform-ci-reference.md: 71b364f72a094f7899a0929eec29f3a16ccc8a93
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 4f5920ffc150ce16d5567ca05128f7524c2a2b21
+2026-07-21-serial-cross-platform-ci-reference.zh.md: bc8b210e4f32c4e2fe3154bb7ffe9d89210d5087
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 4f5920ffc1..bc8b210e4f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,11 +16,11 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 契约。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 约定。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
-该完整聚合流程仍明确划分平台归属。`pty-local` 支持 Linux 与 macOS，因此其单元测试和逐文件覆盖率契约由 POSIX 平台负责，而不会在 Windows 上加载一个明确拒绝 `win32` 的后端；Windows 仍会执行所有可移植包。可移植 fixture（测试前置数据）通过 `node:path` 派生原生路径，使用与生产代码相同的原生 realpath 实现比较规范化后的路径标识，并采用所有宿主机均允许的文件名。ACP（Agent Client Protocol）快照运行还会把生成的 cwd 分别通过 realpath 的 JavaScript 实现与原生实现得到的两种表示一并传给规范化器；规范化器按长度从长到短替换这些别名，避免 Windows 的短路径与长路径表示差异导致共享 fixture 反复变化。
+该完整聚合流程仍明确划分平台归属。`pty-local` 支持 Linux 与 macOS，因此其单元测试和逐文件覆盖率约定由 POSIX 平台负责，而不会在 Windows 上加载一个明确拒绝 `win32` 的后端；Windows 仍会执行所有可移植包。可移植 fixture（测试前置数据）通过 `node:path` 派生原生路径，使用与生产代码相同的原生 realpath 实现比较规范化后的路径标识，并采用所有宿主机均允许的文件名。ACP（Agent Client Protocol）快照运行还会把生成的 cwd 分别通过 realpath 的 JavaScript 实现与原生实现得到的两种表示一并传给规范化器；规范化器按长度从长到短替换这些别名，避免 Windows 的短路径与长路径表示差异导致共享 fixture 反复变化。
 
 macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上的 Node 24 曾在工作线程中执行 CJS 词法分析器时异常终止；进程边界能够隔离这一外部运行时故障，且无需从聚合流程中删除任何测试，而 Linux 与 Windows 仍使用开销更低的线程池。仓库自身引入的竞态均在相应的观测边界修复：开发构建产物的轮询逻辑每次发布重新扫描结果前，都会先暂存候选表、候选图和候选监视基线映射；构建产物缺失后会一直保持脏状态，直到成功计算内容哈希。PTY 就绪检测会在轮询检查前台进程组归属期间保留提示符候选项；常规静默时限也适用于交互式子进程继承提示符标记的情况。真实 PTY fixture 会在运行时拼接同步标记，使就绪等待逻辑不会把交互式 shell 的输入回显误判为子进程已就绪。实时链接场景下的包管理器 e2e 会保留由工作流预先准备的 Corepack 主目录、pnpm 元数据缓存和 store 缓存，同时隔离其他包管理器的可变缓存，因此不会在安装前丢弃可复用的包管理器状态。
 
@@ -34,7 +34,7 @@ master 分支的参考作业仅用于诊断，不参与拉取请求所要求的
 
 - **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。
 - **仅信任并发执行的主门禁清单**：不予采纳，因为调度逻辑与校验逻辑共享实现假设；串行聚合流程是一项独立的完整性检查。
-- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 契约。
+- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 约定。
 - **在每个拉取请求上运行真实内核 Sandbox 矩阵**：不予采纳，因为它的四个状态不参与分支保护，而重复安装、Landlock 构建以及为保持平台一致而运行的 macOS 单元测试会消耗运行器容量，却不会改变合并裁决。master 上的运行保留平台与已安装 launcher 的信号。
 - **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。
 - **在大型运行器上运行串行参考流程**：不予采纳，因为当组织自有运行器池无法分配作业时，必需 CI 及其独立参考流程都必须仍可运行。
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
index 1dc5d79676..d8d79cbf9a 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md
 2026-07-22-evidence-based-larger-hosted-runners.md: 53cc86efce9061c8f9836a17cb35ebb128085b7a
-2026-07-22-evidence-based-larger-hosted-runners.zh.md: 0484548c76cb7eed11dc4235ef024a700499ef6a
+2026-07-22-evidence-based-larger-hosted-runners.zh.md: c9daf5273e190d3828e80ebe81369e72f5d7a74d
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
index 0484548c76..c9daf5273e 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-企业保留仅限本仓库使用的 Ubuntu 和 Windows x64 大型运行器池。普通拉取请求直接指定 3 个 32 核运行器池：Ubuntu 24.04 用于完整覆盖率，Ubuntu latest 用于其余主 Node 24 清单，Windows 2025 用于阻塞性 Windows 契约。公网 IP 已禁用；工作流并发仍设有边界，因为自动扩缩容上限既不会分配闲置机器，也不意味着仓库工作可以无限扩展。
+企业保留仅限本仓库使用的 Ubuntu 和 Windows x64 大型运行器池。普通拉取请求直接指定 3 个 32 核运行器池：Ubuntu 24.04 用于完整覆盖率，Ubuntu latest 用于其余主 Node 24 清单，Windows 2025 用于阻塞性 Windows 约定。公网 IP 已禁用；工作流并发仍设有边界，因为自动扩缩容上限既不会分配闲置机器，也不意味着仓库工作可以无限扩展。
 
-必需主路径依赖这些企业级运行器池。GitHub 标准托管作业保留 Node 22.19、Node 26 和 Python SDK 兼容性契约，而[可移植恢复边界](2026-07-23-portable-required-pull-request-ci.md)与[串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)则在 `master` 上持续提供完整的标准运行器证据。`suite=larger-runner-benchmark` 比较已预配规格上相互独立的关键通道，`suite=consolidated-runner-benchmark` 则比较完整聚合流程。每项基准测试都会先报告实测的处理器和内存容量，再运行仓库工作。
+必需主路径依赖这些企业级运行器池。GitHub 标准托管作业保留 Node 22.19、Node 26 和 Python SDK 兼容性约定，而[可移植恢复边界](2026-07-23-portable-required-pull-request-ci.md)与[串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)则在 `master` 上持续提供完整的标准运行器证据。`suite=larger-runner-benchmark` 比较已预配规格上相互独立的关键通道，`suite=consolidated-runner-benchmark` 则比较完整聚合流程。每项基准测试都会先报告实测的处理器和内存容量，再运行仓库工作。
 
 原有的门禁级和粗粒度主流程分片作业已从工作流中移除。相应的静态、lint、覆盖率、快照和场景分片选择器也已从仓库中移除，因此未使用的诊断路径无法继续维系第二套 CI 架构。
 
@@ -22,9 +22,9 @@ Linux 主流程使用 3 个相互独立的 32 核作业。覆盖率单独运行
 
 门禁依赖关系保持显式。覆盖率消费源码，不等待构建。文档类型检查以消费方通道的完整 project-reference 输出为输入。快照回放和发布消费方等待生成的输出，而 Node 版本兼容性作业会验证对运行时敏感的源码加载，且不重复主源码项目图的类型检查。PTY 和子进程套件继续使用自身有界的内部并发，不继承运行器的核心数。
 
-产物边界保持显式。`scripts/publint-all.ts` 对内存中的发布视图调用 publint 支持的 API；该视图由每个 manifest（元数据清单）声明的文件和 npm 强制要求的元数据组成，从而避免为每个包启动一次包管理器 pack 进程。`scripts/verify-built-package-invariants.mjs` 将已声明的 `lib/` 文件暂存到真实包下，并通过普通 Node 和 Cordis Loader 规范化导入其已编译的自身引用；发布契约只要遗漏一个运行时分片，检查仍会失败。
+产物边界保持显式。`scripts/publint-all.ts` 对内存中的发布视图调用 publint 支持的 API；该视图由每个 manifest（元数据清单）声明的文件和 npm 强制要求的元数据组成，从而避免为每个包启动一次包管理器 pack 进程。`scripts/verify-built-package-invariants.mjs` 将已声明的 `lib/` 文件暂存到真实包下，并通过普通 Node 和 Cordis Loader 规范化导入其已编译的自身引用；发布约定只要遗漏一个运行时分片，检查仍会失败。
 
-Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物契约。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台契约。
+Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物约定。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台约定。
 
 一次分支头精确的全规格基准测试在修正构建尽早启动逻辑前，对每种 Linux 池都运行了完整且未分片的主 Node 聚合流程：
 
@@ -60,7 +60,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 **将原有的门禁级分片拓扑保留为手动参考。** 一套闲置的第二拓扑会让数百行工作流、选择器模块和场景分区行为继续存活。全规格和串行套件无需保留任何必需作业都不执行的生产代码，也能提供计时与完整性对照。
 
-**在每个发布校验器中恢复使用包管理器打包。** 不予采用，因为这会为每个包重复启动一个包管理器子进程。根据 manifest 构建的发布视图和已暂存的编译后自身引用，只需一份进程内清单即可保留发布文件契约。
+**在每个发布校验器中恢复使用包管理器打包。** 不予采用，因为这会为每个包重复启动一个包管理器子进程。根据 manifest 构建的发布视图和已暂存的编译后自身引用，只需一份进程内清单即可保留发布文件约定。
 
 **在每个 Node 版本上先构建，再运行覆盖率或类型检查。** 不予采用，因为覆盖率只消费源码，编译器分析也不依赖运行时。依赖构建产物的消费方仍等待生成的输出，兼容性作业则在每个已声明支持的 Node 版本上验证对运行时敏感的路径。
 
@@ -74,7 +74,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 **将必需的 Windows 检查和观测性 Windows 检查保留在不同作业中。** 这种拆分在工作流层保留状态语义，却需要支付两次设置开销。`run-gates` 在一个进程内保留了相同的必需与非阻塞区别。
 
-**通过系统包管理器安装 Bubblewrap。** 此方案会使用主机的包数据库，即使包内容很小，也可能主导整个作业耗时。固定版本的解压方式配合隔离探针，无需修改托管映像即可保留运行时契约。
+**通过系统包管理器安装 Bubblewrap。** 此方案会使用主机的包数据库，即使包内容很小，也可能主导整个作业耗时。固定版本的解压方式配合隔离探针，无需修改托管映像即可保留运行时约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml
index 1382e073c1..d85aa1fe0c 100644
--- a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-product-first-root-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 .agents/notes/implemented/process/2026-07-22-product-first-root-readme.md
 2026-07-22-product-first-root-readme.md: 32542a45019d64ed1826d4eb21e68c67c3c3d52e
-2026-07-22-product-first-root-readme.zh.md: 994228d89154a041757685f526cad63c9455cfc8
+2026-07-22-product-first-root-readme.zh.md: 8ef6f4b99ca2c935183a225b6357d2d128edb3b0
diff --git a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md
index 994228d891..8ef6f4b99c 100644
--- a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 **将仓库呈现为 SDK 和包清单。** 这样能立即展现实现广度，却会迫使新读者从包名反推出产品。包索引与生成的能力图仍是权威清单。
 
-**使用包含截图、徽章和重复教程的长篇营销页面。** 富媒体能够展示稳定的产品使用路径，但其内容会独立于命令和源码契约而逐渐陈旧。根 README 保持紧凑，并链接到可运行示例和各自维护的指南。
+**使用包含截图、徽章和重复教程的长篇营销页面。** 富媒体能够展示稳定的产品使用路径，但其内容会独立于命令和源码约定而逐渐陈旧。根 README 保持紧凑，并链接到可运行示例和各自维护的指南。
 
 **将根 README 投影为文档网站首页。** 使用同一个首页可以避免两套叙事，但文档网站的用户指南与仓库面向产品和开发者的入口在导航和维护需求上并不相同。
 
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
index 2a6cdcc2d0..45f0ba8ce1 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
 2026-07-22-tsconfig-solution-root-two-aggregates.md: 6e8d192b5fea1c7045ade6935fd0e2dc8434c502
-2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 60581e3de55227a393e2528ce7d3c8fa1bf9c570
+2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 827b56288fd832a65af6a948651b7e70127a1882
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
index 60581e3de5..827b56288f 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
@@ -27,7 +27,7 @@ GUI 拆分引入了第二个聚合 program（`tsconfig.client.json`，见[分层
 
 整个方案立足的原则：**cordis `Context` 的声明合并冲突只存在于同一个 `ts.Program` 内部，从不发生在模块解析中。** solution 文件不构成 program，因此从一个根文件同时引用两个聚合不会让两侧的声明合并相撞；vite-tsconfig-paths 只读取 `paths` 与 `include`、丢弃全部类型信息，因此一个门面可以横跨两侧。唯一会爆炸的做法是把两侧压平进同一个 program，由此推出两条派生纪律：`tsconfig.base.json` 永远不得添加 `include`/`files`（否则会泄漏进每个继承它的包，并收窄门面范围）；每个全仓级 `ts.Program` 消费方（`scripts/ts-project.ts`、doc-typecheck 独立模式）都显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子，绝不使用根 solution。基于 program 的生成器与语义门禁有意只留在宿主侧；客户端侧只有在真实需求出现时才引入基于 program 的门禁。
 
-根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 契约而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
+根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 约定而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
 
 solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更近的 tsconfig，tsx（get-tsconfig）通过根文件解析它们的 workspace 导入。`extends` 把 `paths` 映射带回根文件，`files: []` 则让它始终不构成 program。这不影响两者的*类型检查*：examples、scripts 与 website 的文件由宿主聚合纳入。
 
@@ -41,5 +41,5 @@ solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更
 
 - `docs/development.md#typescript-project-layout` 是权威描述；根 `AGENTS.md` 以约定形式收录上述两条纪律。
 - [ts-build-config Agent Note](2026-06-17-ts-build-config.md) 继续拥有 tsc 先行的构建流水线（tsc 负责输出，tsdown 负责打包，`.ts` 说明符配合 `rewriteRelativeImportExtensions`）；其原先「单一根类型检查项目」的形态由本文取代。
-- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成契约与 Client 消费契约的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
-- Host 与 Client 构建阶段必须串行：Host tsdown 生成契约后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
+- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成约定与 Client 消费约定的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
+- Host 与 Client 构建阶段必须串行：Host tsdown 生成约定后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
diff --git a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml
index e5d8f11c3c..eb11cc1b92 100644
--- a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.md
 2026-07-23-personal-staging-maintenance-skills.md: a7ccc5b1e0f13e880c58a93d2e4c2cd4f06e2a93
-2026-07-23-personal-staging-maintenance-skills.zh.md: d988eae0b4746f14b893b8f1f32f8396e6548232
+2026-07-23-personal-staging-maintenance-skills.zh.md: 8593291f510352429cbb29679e7d033589312e41
diff --git a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md
index d988eae0b4..8593291f51 100644
--- a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 仓库从其根 `skills/` 目录分发 [`dsh-customize`](../../../../skills/dsh-customize/SKILL.md)、[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md) 和 [`dsh-upstream-customization`](../../../../skills/dsh-upstream-customization/SKILL.md)。它们的描述同时说明操作内容和选择该 skill（技能）的用户请求。分发的 TUI 在启动时将该目录提供给本地 skill 提供方，在发现优先级上位于项目根目录和用户根目录之后。这些 skill 根据已安装的启动器而非个人路径或分支名称定位当前生效的检出和集成分支，遵从仓库内指令，要求使用任务 worktree，并利用集成分支所在 worktree 的既有 `.agents/merge.lock`，串行执行每一次个人集成分支修改。
 
-升级流程在变基前检查 Git 日志和提交范围，以识别将进入升级的上游变更、个人提交、重复内容和可能发生冲突的区域。它会丢弃上游已经提供的定制；如果这类定制在本地只剩文档差异，也会一并丢弃，除非该说明包含上游缺失且可独立使用的当前契约。每次升级尝试使用同一个 UTC 基本格式时间戳，用于其独立的 `dsh-staging-<timestamp>` 同级克隆、本地 `dsh-upgrade/prepare-<timestamp>` 分支、新的 `dsh-staging/<timestamp>` 分支、私有的上游引用与恢复引用，以及启动器备份。同级克隆的名称不派生自当前目录名，名称冲突会直接失败，而不是追加临时后缀。流程根据进程命令和运行时环境而非 shell 工作目录推导当前 DSH 进程的源码位置，随后将已安装启动器所指向的仓库和检出视为不可变，唯一例外是持有其既有合并锁。
+升级流程在变基前检查 Git 日志和提交范围，以识别将进入升级的上游变更、个人提交、重复内容和可能发生冲突的区域。它会丢弃上游已经提供的定制；如果这类定制在本地只剩文档差异，也会一并丢弃，除非该说明包含上游缺失且可独立使用的当前约定。每次升级尝试使用同一个 UTC 基本格式时间戳，用于其独立的 `dsh-staging-<timestamp>` 同级克隆、本地 `dsh-upgrade/prepare-<timestamp>` 分支、新的 `dsh-staging/<timestamp>` 分支、私有的上游引用与恢复引用，以及启动器备份。同级克隆的名称不派生自当前目录名，名称冲突会直接失败，而不是追加临时后缀。流程根据进程命令和运行时环境而非 shell 工作目录推导当前 DSH 进程的源码位置，随后将已安装启动器所指向的仓库和检出视为不可变，唯一例外是持有其既有合并锁。
 
 在独立克隆中验证通过后，工作流会创建并验证带时间戳的集成分支，然后以原子方式将启动器从保持不变的旧集成分支检出一次性切换到新集成分支检出。启动器绝不会指向准备、功能、评审、发布或处于分离状态的检出。切换前的失败会让已安装的检出和启动器保持不变；切换后的失败则恢复并验证启动器备份。旧的集成分支检出、其分支、恢复引用和启动器备份会一直保留，直到重启后的进程证明 DSH 运行于新的集成分支，且用户明确批准回滚清理为止。
 
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
index 440691d218..0f80587749 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
 2026-07-23-portable-required-pull-request-ci.md: 1a6939e8386e381cba114a7be71993a644457a45
-2026-07-23-portable-required-pull-request-ci.zh.md: f7a95ced2353ca7aaee9a586cc4f0bb297cbf7d4
+2026-07-23-portable-required-pull-request-ci.zh.md: 83737b61bc72e3c1ee6afb805d30256d572211a2
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
index f7a95ced23..83737b61bc 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node 以覆盖阻断性检查范围（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)），使拉取请求的 Windows 契约不依赖任何 Windows 运行器分配；完整的原生内核 Windows 清单位于 master 串行参考流程中。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node 以覆盖阻断性检查范围（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)），使拉取请求的 Windows 约定不依赖任何 Windows 运行器分配；完整的原生内核 Windows 清单位于 master 串行参考流程中。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的约定，但无法产出缺失的必需结果。
 
 当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 **根据标称核心数选择企业规格。** 基准测试表明扩展效果不呈单调变化，设置耗时也存在波动，因此必需运行器池改由完整作业的精确测量结果选定。
 
-**在容量不可用时跳过检查或降低其级别。** 这种方式通过丢弃证据而非执行仓库的必需契约来使状态变绿。
+**在容量不可用时跳过检查或降低其级别。** 这种方式通过丢弃证据而非执行仓库的必需约定来使状态变绿。
 
 **在每台主机上使用同一工作线程策略。** 外层门禁并发与内层工具工作线程在 Linux、Windows 和标准运行器上的争用方式不同；按主机实测的上限可以避免新增核心反而拖慢执行。
 
diff --git a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
index 3d471fc9f3..b768fb0abc 100644
--- a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md
 2026-07-23-translation-prompt-v4-contract.md: adeb63e0f4bf03ec0b94a371f596bb84138d81ed
-2026-07-23-translation-prompt-v4-contract.zh.md: 5bd7bbf0d2d02222ca8038afb0f5a156fffea1b0
+2026-07-23-translation-prompt-v4-contract.zh.md: bd9a18788cbc04f733f52270ec486923c552459e
diff --git a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
index 5bd7bbf0d2..bd9a18788c 100644
--- a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 经校准的翻译提示词 v4 契约
+# Agent Note: 经校准的翻译提示词 v4 约定
 
 Status: implemented
 
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-提交入库的[翻译提示词](../../../../docs/i18n/translation-prompt.md)是经过校准的流水线资源。其渲染器仅注入源语言、目标语言和当前[术语表](../../../../docs/i18n/terminology.md)，并在组装请求前拒绝未知、缺失或语法格式错误的占位符。请求组装器在模型可见的提示词之外保留源文件基本名，并在真正的源文档之前，将每组经评审的整篇文档对编排为一个纯文本 user/assistant 示例轮次。模板可以包含针对特定模型的校准规则，但这些规则必须服从仓库中具约束力的配对、术语、结构与强调格式契约。
+提交入库的[翻译提示词](../../../../docs/i18n/translation-prompt.md)是经过校准的流水线资源。其渲染器仅注入源语言、目标语言和当前[术语表](../../../../docs/i18n/terminology.md)，并在组装请求前拒绝未知、缺失或语法格式错误的占位符。请求组装器在模型可见的提示词之外保留源文件基本名，并在真正的源文档之前，将每组经评审的整篇文档对编排为一个纯文本 user/assistant 示例轮次。模板可以包含针对特定模型的校准规则，但这些规则必须服从仓库中具约束力的配对、术语、结构与强调格式约定。
 
-v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含义与受保护结构，再遵循术语表，然后以整篇金标校准语体，最后应用一般指导与内嵌示例。模型先以母语技术作者的方式起草，再逐项对照源文，保留执行主体、条件、否定、情态、生命周期条件、方向、结果通道、所有权和数量。文体指导不得虚构执行主体，也不得仅为丰富措辞而改换术语表词形、已定义概念或契约动词。无法裁定的术语在译文中保持不变，只在评审段标为待人工确认。
+v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含义与受保护结构，再遵循术语表，然后以整篇金标校准语体，最后应用一般指导与内嵌示例。模型先以母语技术作者的方式起草，再逐项对照源文，保留执行主体、条件、否定、情态、生命周期条件、方向、结果通道、所有权和数量。文体指导不得虚构执行主体，也不得仅为丰富措辞而改换术语表词形、已定义概念或约定动词。无法裁定的术语在译文中保持不变，只在评审段标为待人工确认。
 
 响应包含三个有序的顶层分段：`translation`、`review` 和 `final`。响应消费方根据保留的源文件上下文推导目标文件基本名，保留文件开头可选的 YAML frontmatter，并以机械方式在 `final` 中第一个 H1 之后插入或校正语言切换行。解析器要求每个分段恰好出现一次，拒绝封套之外的内容，并允许响应最外层有一层 `xml` Markdown 围栏，因为模型有时会照抄提示词中的示例围栏。
 
@@ -20,13 +20,13 @@ v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含
 
 分段定界行由协议格式（wire format）保留。当 Markdown 正文中的某一行仅包含定界标签（前面可以带反斜杠）时，序列化器和模型会在行首再添加一个反斜杠；解析器则只移除一个。这种保留计数的转义方式让字面量定界标签与已转义的定界标签都能无损往返，同时不会改动行内提及的标签。
 
-可执行契约由[渲染器、请求组装器、解析器和响应消费方](../../../../scripts/translation-prompt.ts)实现。单元测试覆盖两个翻译方向、请求顺序、占位符校验、目标路径校验、严格的分段顺序与数量约束、带围栏的响应、行内提及标签、Markdown 正文中的定界行，以及保留 YAML frontmatter 的新配对语言切换行校正。一个无密钥子进程快照锁定组装后的提示词、五个经评审的示例轮次，以及带 YAML frontmatter 的录制响应经目标路径校正后的消费结果。
+可执行约定由[渲染器、请求组装器、解析器和响应消费方](../../../../scripts/translation-prompt.ts)实现。单元测试覆盖两个翻译方向、请求顺序、占位符校验、目标路径校验、严格的分段顺序与数量约束、带围栏的响应、行内提及标签、Markdown 正文中的定界行，以及保留 YAML frontmatter 的新配对语言切换行校正。一个无密钥子进程快照锁定组装后的提示词、五个经评审的示例轮次，以及带 YAML frontmatter 的录制响应经目标路径校正后的消费结果。
 
 ## 考虑过的替代方案
 
 **在每个请求中注入 `translation-rules.md`。** 该文档既约束人类与 agent，也约束自动翻译流水线。注入它会让编辑规范的每次澄清都与模型行为耦合，并挤占经过人工校准的提示词约束；因此流水线仅注入具约束力的术语表，并直接校验自身资源。
 
-**使用严格的 CDATA XML 文档。** CDATA 提供通用的 XML 封装，但会引入一层嵌套协议、额外的 `]]>` 转义规则，以及三段式契约原本不需要的 XML 解析器行为。预留并转义六种定界行，既能维持经校准的响应形态，也能保留任意 Markdown 内容不变。
+**使用严格的 CDATA XML 文档。** CDATA 提供通用的 XML 封装，但会引入一层嵌套协议、额外的 `]]>` 转义规则，以及三段式约定原本不需要的 XML 解析器行为。预留并转义六种定界行，既能维持经校准的响应形态，也能保留任意 Markdown 内容不变。
 
 **只返回最终译文。** 单一正文更易解析，却会丢弃显式修正步骤；这个步骤用于在发布前发现语气、结构、术语和标点缺陷。
 
@@ -36,4 +36,4 @@ v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含
 
 ## 影响
 
-提示词措辞属于可执行行为，因此需要经过代码评审、翻译提示词校验器校验及可运行的请求/响应快照验证。聚焦测试固定保留的 v4 示例与选定的 v7 保护规则。`translation-prompt-v4` 快照目录命名的是稳定的渲染器／解析器协议谱系，而不是当前校准修订号。经校准的资源与通用翻译规则可以针对各自的受众分别演进，但评审必须拒绝任何与仓库约束性契约冲突的改动。只有当源文档中的封装标签独占一行时，行转义才会显现；解析器测试锁定这一无损行为。
+提示词措辞属于可执行行为，因此需要经过代码评审、翻译提示词校验器校验及可运行的请求/响应快照验证。聚焦测试固定保留的 v4 示例与选定的 v7 保护规则。`translation-prompt-v4` 快照目录命名的是稳定的渲染器／解析器协议谱系，而不是当前校准修订号。经校准的资源与通用翻译规则可以针对各自的受众分别演进，但评审必须拒绝任何与仓库约束性约定冲突的改动。只有当源文档中的封装标签独占一行时，行转义才会显现；解析器测试锁定这一无损行为。
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
index ac859f10dd..7f4bc40463 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
 2026-07-26-briefed-minimal-translation-updates.md: afd990b7b63adfd0e66a4726975b678d044e7cad
-2026-07-26-briefed-minimal-translation-updates.zh.md: dcdb253746041a7928ab7a544ae427293bc3f2de
+2026-07-26-briefed-minimal-translation-updates.zh.md: a6559667f0f1140d8a26cd5ebc4bb64b7b95fe45
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
index dcdb253746..a6559667f0 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[双语配对契约](2026-07-02-bilingual-docs-and-pairing-gate.md)早已规定对侧文件按最小幅度更新：把被改的一侧与其上次确认状态做 diff，据此修补对侧文件，绝不整篇重译；但仓库内置的工作流让每次更新都付出整篇文档级别的开销。负责翻译的 subagent 在动手处理一个两行的 diff 之前，要先加载完整的指导语料（guidance corpus），即 skill（技能）、配对契约、翻译规则、192 行的术语表、语体样例与行文标准；要通过 `git cat-file` 手工重新推导上次确认状态以来的 diff；每轮迭代还要重跑全语料配对门禁，而该门禁为校验一个配对要解析整棵树里的每一个配对。一次小的英文行文修改，动辄花掉数十倍于其应得份额的 token 用量与分钟数，被惩罚的恰恰是契约想要的行为：在同一个 PR（Pull Request）里把对侧文件一并带上。
+[双语配对约定](2026-07-02-bilingual-docs-and-pairing-gate.md)早已规定对侧文件按最小幅度更新：把被改的一侧与其上次确认状态做 diff，据此修补对侧文件，绝不整篇重译；但仓库内置的工作流让每次更新都付出整篇文档级别的开销。负责翻译的 subagent 在动手处理一个两行的 diff 之前，要先加载完整的指导语料（guidance corpus），即 skill（技能）、配对约定、翻译规则、192 行的术语表、语体样例与行文标准；要通过 `git cat-file` 手工重新推导上次确认状态以来的 diff；每轮迭代还要重跑全语料配对门禁，而该门禁为校验一个配对要解析整棵树里的每一个配对。一次小的英文行文修改，动辄花掉数十倍于其应得份额的 token 用量与分钟数，被惩罚的恰恰是约定想要的行为：在同一个 PR（Pull Request）里把对侧文件一并带上。
 
 ## 决策
 
@@ -31,10 +31,10 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **保留原工作流，只让门禁支持按对检查**：门禁扫描本是较小的开销，大头在语料加载与翻查历史。只收窄检查范围，约 3 倍的开销仍会原地保留。
-- **把整篇重译作为更新路径**（朴素流水线的做法）：依据基准测试证据否决，理由是保留度崩塌、术语漂移、成本最高。契约的最小更新规则得以延续，且从此有数据支撑。
+- **把整篇重译作为更新路径**（朴素流水线的做法）：依据基准测试证据否决，理由是保留度崩塌、术语漂移、成本最高。约定的最小更新规则得以延续，且从此有数据支撑。
 - **每个 subagent 批量处理多对文档**：否决。没有实测出节省（简报本身已对固定内容做了去重），而且一对文档停滞或陷入混乱会把其余配对一并拖住。
 - **在伴随记录中保存逐段的翻译记忆条目**（用分段 hash 取代整文件 hash）：否决。配对两侧的段落边界可以合理地不同，任一侧都可能先撰写，这类条目还会不断膨胀并在合并时产生冲突。基于现有整文件 hash 按需计算的区间映射，在对齐可信时能恢复同样的对齐关系，不可信时会明确说明。
-- **给自动提示词流水线加一个更新模式（prompt-v5）**：推迟，本文不做设计。今天没有任何调用方在驱动 [scripts/translation-prompt.ts](../../../../scripts/translation-prompt.ts)，实际的成本中心是 agent 路径。流水线在拥有消费方之前，维持其整篇文档的 v4 契约。
+- **给自动提示词流水线加一个更新模式（prompt-v5）**：推迟，本文不做设计。今天没有任何调用方在驱动 [scripts/translation-prompt.ts](../../../../scripts/translation-prompt.ts)，实际的成本中心是 agent 路径。流水线在拥有消费方之前，维持其整篇文档的 v4 约定。
 
 ## 后果
 
@@ -44,8 +44,8 @@ Status: implemented
 - 不带参数的 `--write` 不再可用；靠肌肉记忆的调用者必须点名配对或传 `--all`。这正是目的所在：批量背书如今是一个可见的、有意为之的动作。
 - 按对检查意味着一个更新循环可以在别处某个无关配对处于红灯时自己保持绿灯；`doc-sync`/CI 中的全语料检查仍然承载树级不变式。
 - 区间映射只在上次确认源文、当前源文与当前对侧文本三方的种类序列一致时才信任一处对齐；映射失败时粒度确定性地逐级放宽（单元 → 章节 → 整篇文档）而不是靠猜，因此被重构过的文档拿到的是一份明确写着「请自行定位相关区域」的简报，绝不会是一张错误的地图。
-- 「首次出现」的一次移位可能让简报扩大到直接改动块之外；这一成本是「首次出现」契约的明确后果，而非对齐启发式。
+- 「首次出现」的一次移位可能让简报扩大到直接改动块之外；这一成本是「首次出现」约定的明确后果，而非对齐启发式。
 
 ## 测试
 
-[scripts/translation-brief.spec.ts](../../../../scripts/translation-brief.spec.ts) 固定单元与章节的区间提取（以容器为作用域的种类、只按深度对齐章节从而让已翻译的标题文字仍能映射、首个标题前的序言）、对齐与改动索引检测、机械代码拼接及其每一个拒绝条件、带词边界与复数变形约束的双向术语行匹配、首次出现移位跟踪、围栏升级，以及渲染后简报的契约（带三方上下文的单元条目、机械／章节／整篇文档三种范围、分方向的规则摘要、按对的收尾命令）。[scripts/translation-pairing.spec.ts](../../../../scripts/translation-pairing.spec.ts) 固定未提交快照的精确字节持久化与取回、在不可用对象进入伴随记录前失败、参数归一化（配对的任一文件或裸词干都归一到锚点），以及 CLI（命令行界面）用例矩阵：按对检查、裸 `--write` 拒绝执行、`--write <pair>`、`--write --all`、`--list` 的互斥性、未知标志。
+[scripts/translation-brief.spec.ts](../../../../scripts/translation-brief.spec.ts) 固定单元与章节的区间提取（以容器为作用域的种类、只按深度对齐章节从而让已翻译的标题文字仍能映射、首个标题前的序言）、对齐与改动索引检测、机械代码拼接及其每一个拒绝条件、带词边界与复数变形约束的双向术语行匹配、首次出现移位跟踪、围栏升级，以及渲染后简报的约定（带三方上下文的单元条目、机械／章节／整篇文档三种范围、分方向的规则摘要、按对的收尾命令）。[scripts/translation-pairing.spec.ts](../../../../scripts/translation-pairing.spec.ts) 固定未提交快照的精确字节持久化与取回、在不可用对象进入伴随记录前失败、参数归一化（配对的任一文件或裸词干都归一到锚点），以及 CLI（命令行界面）用例矩阵：按对检查、裸 `--write` 拒绝执行、`--write <pair>`、`--write --all`、`--list` 的互斥性、未知标志。
diff --git a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml
index a15aaff72e..c69d808669 100644
--- a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md
 2026-07-26-dependencies-over-hand-rolling.md: 22720c483c1c9e8145497b3e83cbc9f17570b161
-2026-07-26-dependencies-over-hand-rolling.zh.md: 4c3aee489cd8a8269b2b083ea2fb7978d01f4e26
+2026-07-26-dependencies-over-hand-rolling.zh.md: 7c155c5ca208153d697a930698a02b0c61966034
diff --git a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md
index 4c3aee489c..7c155c5ca2 100644
--- a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md
@@ -10,13 +10,13 @@ harness 手写了大量基础设施，而成熟的外部包早已提供同等能
 
 ## 决策
 
-引入外部依赖是一种正当的简化，而不是政策特例。当一个维护良好的包（或我们引擎下限即已提供的 Node 内置能力）覆盖了某块手写接口面时，替换手写代码就是优先方向，并遵循与其他任何简化相同的证据标准：这次替换必须切实缩减我们负责维护的内容（代码、测试和契约面），而不是仅仅把复杂度挪到一个包装层后面。
+引入外部依赖是一种正当的简化，而不是政策特例。当一个维护良好的包（或我们引擎下限即已提供的 Node 内置能力）覆盖了某块手写接口面时，替换手写代码就是优先方向，并遵循与其他任何简化相同的证据标准：这次替换必须切实缩减我们负责维护的内容（代码、测试和约定面），而不是仅仅把复杂度挪到一个包装层后面。
 
 新依赖的准入门槛：
 
 - **净删除。** 该依赖替换的是实际由我们维护的代码（实现 + 专属测试 + 文档），而不是假想中的未来代码。只增加能力的依赖属于功能决策，不属于简化。
 - **健康度。** 持续维护、广泛使用、传递依赖足迹合理。一个无人维护的小包，只是拿我们的代码换来别人废弃的代码。
-- **边界契合。** 该包的语义要覆盖我们的实际契约；仍需围绕它手写补齐的残留语义，要计入这次替换的减分项。
+- **边界契合。** 该包的语义要覆盖我们的实际约定；仍需围绕它手写补齐的残留语义，要计入这次替换的减分项。
 - **不触碰已定案的 seam。** schemastery（配置 schema）、源码收录的 Cordis、`@earendil-works` 孪生适配器，以及其他记录在已实现 Agent Note 中的决策，不因本政策而重开；一次会瓦解已记录设计的替换，必须胜过所记录的论证理由，而不能只援引本 Agent Note。
 
 `packages/util/` 的「零依赖」章程描述的是该分组的*导出*纪律（util 包不携带 harness 依赖，从而任何分组都能依赖它们），并不禁止在能带来简化时使用外部包；如果一个 util 包的全部职责有维护良好的外部包做得更好，就应当用该依赖替换它，而不是为了章程而保留它。
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
index b5e11d7a71..1ae66cc1b7 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md
 2026-07-26-frozen-agent-note-archive.md: 52b43088b276c0c8e263fc8a81a2df1408cc8059
-2026-07-26-frozen-agent-note-archive.zh.md: ac87935fff1b3942d0bc8eade49237aa3c90d21e
+2026-07-26-frozen-agent-note-archive.zh.md: a37e06e7cbc19b5000d4849cc3ee2ddc9b451ee3
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
index ac87935fff..a37e06e7cb 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
@@ -14,7 +14,7 @@ implemented Agent Note 作为当前决策记录持续维护，因此活跃记录
 
 归档路径为 `.agents/notes/archived/{kind}/yyyy-mm-dd-topic.md`，其中省略了冗余的 `implemented` 层级。归档变更会移动完整的英文、中文和一致性伴随记录三个文件，保留 `Status: implemented`，并在两种语言的文件中紧接该状态行插入 `Archived: YYYY-MM-DD`。归档时只允许做文件迁移、添加该元数据行、相应地重新记录伴随记录，以及机械修复入站链接。
 
-归档后，这三个文件永久冻结，只作为历史背景，不再是当前权威依据。不得因为包重命名、行为变化、翻译标准、格式规则、出站链接失效或后续文档契约而更新归档文件。活跃文档可以有意链接到归档 Agent Note，也可以把该链接重定向到当前权威依据，或直接删除。仓库门禁因此会校验指向归档文件的链接，但绝不把归档文件作为链接源来校验。
+归档后，这三个文件永久冻结，只作为历史背景，不再是当前权威依据。不得因为包重命名、行为变化、翻译标准、格式规则、出站链接失效或后续文档约定而更新归档文件。活跃文档可以有意链接到归档 Agent Note，也可以把该链接重定向到当前权威依据，或直接删除。仓库门禁因此会校验指向归档文件的链接，但绝不把归档文件作为链接源来校验。
 
 [`verify-archived-agent-notes`](../../../../scripts/verify-archived-agent-notes.ts) 负责维护冻结边界。它只接受封闭集合中的 Agent Note 类别，要求三个配对文件完整、状态为 implemented，且归档日期有效并互相匹配；它还会用双方当前的 Git blob hash 校验伴随记录，并在仅追加的 manifest（元数据清单） 中按路径和 SHA-256 内容 hash 封存每项产物。其 `--write` 模式会先证明每条现有封存记录对应的内容都未改变，再仅追加新归档的产物。拉取请求 CI 会提供可信的基准 SHA，并在运行校验器前检出完整历史，因此复用运行器上的浅克隆检出无法漏掉基线 manifest。普通的 Agent Note 格式、翻译配对、换行、Markdown 链接、包路径、Mermaid、文档 TypeScript 和类型等价门禁都排除归档源文件，因此这些门禁持续演进的标准不会产生修改历史记录的压力。
 
diff --git a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml
index 1aab8e5bad..d7a09d388f 100644
--- a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.md
 2026-07-26-web-syntax-highlighting-shiki.md: 48a1e4c43f19693f90906f210f0ed85db3f31687
-2026-07-26-web-syntax-highlighting-shiki.zh.md: 31fb3d916c7cb1e928bc37eca86fb11e21374b16
+2026-07-26-web-syntax-highlighting-shiki.zh.md: 7998f7811c8b396538c0d6d06951814e7d4b8e39
diff --git a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md
index 31fb3d916c..7998f7811c 100644
--- a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-web-syntax-highlighting-shiki.md) | 中文
 
-> 范围：web client 唯一的一套语法高亮体系——依赖裁决、单例形态、token 表契约与各消费表面。本篇是 Code Mode UI 堆叠 PR（Pull Request）链的第五个 PR；[chat 子调用行 Agent Note](../feature/2026-07-26-code-mode-chat-subcall-rows.md)交付了 `run_code` 程序正文，而本体系存在的意义正是让它可读。样式的基本规则由 [Web 样式体系裁决](2026-07-19-web-styling-system.md)规定。
+> 范围：web client 唯一的一套语法高亮体系——依赖裁决、单例形态、token 表约定与各消费表面。本篇是 Code Mode UI 堆叠 PR（Pull Request）链的第五个 PR；[chat 子调用行 Agent Note](../feature/2026-07-26-code-mode-chat-subcall-rows.md)交付了 `run_code` 程序正文，而本体系存在的意义正是让它可读。样式的基本规则由 [Web 样式体系裁决](2026-07-19-web-styling-system.md)规定。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
index 4aec3f6a4f..9115979c19 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-29-oxlint-linter.md
 2026-07-29-oxlint-linter.md: 3e3de24be33b8f9461cea2967b0fa18f59ddb52a
-2026-07-29-oxlint-linter.zh.md: 5388416b54a5ff44b9ab9551d726705a84a8b1a1
+2026-07-29-oxlint-linter.zh.md: dae8c7451bd3fbe9296508491aaa51f1118abe92
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
index 5388416b54..dae8c7451b 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
@@ -24,15 +24,15 @@ CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行
 
 解决两处分析器差异后，迁移后的配置报告与迁移前一致的自有源码无问题基线：移除了一项冗余测试断言，而 `tsc` 要求的一处结构性类型转换使用了窄范围的 Oxlint 抑制指令。以已删除 ESLint 配置的精确 blob 为基准进行的一次性审核在完成规则名映射后确认：源码为 88 项对 88 项，示例为 87 项对 87 项，测试为 83 项对 83 项。已提交的指纹锁定这些经审核的 Oxlint 规则配置及完整的覆盖结构；它既不执行已删除的配置，也不纳入后续的上游预设变更。对 `typescript-eslint@8.61.0` 的评估还确认，`strictTypeChecked` 并未启用 `@typescript-eslint/no-empty-function`；已删除、仅用于测试的 `off` 条目不起作用。
 
-可执行契约测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
+可执行约定测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
 
 ## 考虑过的替代方案
 
 **在全仓库范围内同时运行两个 linter。** 所有正确性规则均可通过 Oxlint 原生规则、nursery 规则或 JavaScript 插件兼容层获得。在全仓库范围启用 ESLint 回退会保留较慢的项目服务初始化和两套正确性配置，却不会增加任何检查；保留的 ESLint 流程被刻意限制为不加载项目的暂存文件格式化。
 
-**依赖兼容层修复。** 兼容层会报告既有的 `@stylistic` 规则，但在 Oxlint 的两种修复模式下都不会应用这些规则的修复。保留窄范围的暂存文件格式化器，可以在不将 ESLint 扩张回仓库 linter 的情况下维持贡献者契约。
+**依赖兼容层修复。** 兼容层会报告既有的 `@stylistic` 规则，但在 Oxlint 的两种修复模式下都不会应用这些规则的修复。保留窄范围的暂存文件格式化器，可以在不将 ESLint 扩张回仓库 linter 的情况下维持贡献者约定。
 
-**移除尚无原生实现的 @stylistic 或 SonarJS 规则。** 这会移除依赖，但也会削弱机械质量契约。兼容层会保留这些规则，直到能够通过单独决策评估原生替代规则。
+**移除尚无原生实现的 @stylistic 或 SonarJS 规则。** 这会移除依赖，但也会削弱机械质量约定。兼容层会保留这些规则，直到能够通过单独决策评估原生替代规则。
 
 **迁移期间用 Oxfmt 替换 @stylistic。** 格式化器迁移会产生超出 lint 引擎边界的输出变化，并带来全仓库格式 diff。保留既有规则可使本次变更便于评审，并让格式化器选择保持独立。
 
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
index 9d3ac28ed2..8e9fb88179 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.md
 2026-07-31-coverage-exempt-heavy-suites.md: 7235a5193554947ecf71f62d522d09f4e21cb1da
-2026-07-31-coverage-exempt-heavy-suites.zh.md: b739e4494ae8d240b0e35109920a49876ebd222d
+2026-07-31-coverage-exempt-heavy-suites.zh.md: 7d622cd7db927f8ccbc12b22a563c5228c56b981
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
index b739e4494a..7d622cd7db 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
@@ -17,7 +17,7 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 - **插桩 gate**（`test:coverage`）：设 `DSH_COVERAGE_EXEMPT_HEAVY=1`，`vitest.config.ts` 据此从两个 project 的 exclude 中剔除豁免套件，其余全部文件照旧插桩并承担全部阈值证明。经 gate 自带 env 注入（既有 `Gate.env` 机制），不进 workflow 全局环境，因此并排的无插桩 gate 和本地直跑 `vitest run` 都看不到该变量、行为不变。
 - **无插桩 gate**（`test:coverage-exempt-heavy`）：用配对的 positional filter 恰好运行豁免套件，保证正确性信号不缩水。
 
-`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格契约与 filter/exclude 配对，防止两侧漂移。
+`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格约定与 filter/exclude 配对，防止两侧漂移。
 
 ### 豁免名单与逐项对账
 
@@ -29,9 +29,9 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 | 其中 tools-catalog.spec 额外 import | `typert-registry`、`tool-cordis` 的 src | 两包各自的测试独立满覆盖（focused coverage 实测无阈值错误） |
 | `scripts/install-lefthook.spec.ts`、`scripts/oxlint-contract.spec.ts`、`scripts/change-scope.spec.ts` | 无——被测对象是 `scripts/` 源码（从不在 coverage.include），执行方式是 spawn 子进程 | 无需接 |
 
-### 成员资格契约
+### 成员资格约定
 
-新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。契约文本随名单同文件维护。
+新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。约定文本随名单同文件维护。
 
 ### 门禁自动守卫名单正确性
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index 77003539ac..a2e19d3493 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
 2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
-2026-07-31-installer-adopts-existing-checkout.zh.md: 7cdcd5549fb2bca2a6cb11f0cf2867687565ae79
+2026-07-31-installer-adopts-existing-checkout.zh.md: e19baa0b1ee8ce71c1b8f3ee520322fb6557a720
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index 7cdcd5549f..e19baa0b1e 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `scripts/install.sh`会产生两种互不兼容的安装形态。`curl … | sh`安装会构建受管布局——`~/.dsh/source/master`处的 master 克隆、位于`dsh-staging/<时间戳>`分支上的 staging worktree，以及 PATH 启动器据以解析的稳定`current`符号链接。而从检出中运行同一脚本时，则依据此前的[检出内跳过克隆决策](../../archived/process/2026-07-22-installer-in-repo-skip-clone.md)，把`dsh`直接链接到该检出的`bin/dsh`。
 
-这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级契约禁止作为启动器目标的情形。升级技能早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
+这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级约定禁止作为启动器目标的情形。升级技能早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
 
 ## Decision
 
@@ -22,17 +22,17 @@ Status: implemented
 
 所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
 
-在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级契约。
+在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级约定。
 
 ## Alternatives considered
 
 **把`~/.dsh/source/master`做成指向该任意克隆的符号链接。** 已否决。Git 会解析该符号链接并记录*真实*路径：经由它创建的 worktree 会存储`gitdir: …/<克隆>/.git/worktrees/<名称>`，而`git worktree list`报告的是该克隆。因此这个符号链接纯属装饰——没有任何代码读取它——却又暗示容器拥有该仓库。它还会静默失效：移动克隆后，`master`看似仍在却已悬空，而每个 staging worktree 都会以`fatal: not a git repository`失败。最糟的是，它把两个名称别名到同一棵树上，于是"current 绝不能是 master 克隆"这项检查会在字符串比较下通过，实则为假。`~/.dsh/source/master`是位置而非名称，且只有位置具有权威性。
 
-**把检出自身提升为`current`的目标。** 已否决：升级契约要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
+**把检出自身提升为`current`的目标。** 已否决：升级约定要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
 
 **把就地链接保留在提示或`DSH_ADOPT`开关之后。** 已否决；本次变更的早期修订版本正是如此实现，之后被移除。分叉的形态本身就是缺陷，因此把它保留为一个选项等于保留了问题，并使此后每次改动需要推敲的状态翻倍——提示、开关、工作树不干净的警告，以及第二条链接路径，全都只为维持一种本不该产生的形态而存在。就地链接最初的动机——让脚本能针对本地源码进行测试——在接管方案下依然成立：以检出的`HEAD`为起点创建的 staging worktree 运行的是同一份代码。`DSH_SOURCE`仍是安装另一棵树的退路。
 
-**在工作树不干净时发出警告或提示。** 已否决：以`HEAD`为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该契约。
+**在工作树不干净时发出警告或提示。** 已否决：以`HEAD`为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该约定。
 
 **把被接管克隆的 staging worktree 放在该克隆旁边**（`~/src/staging-*`），而非放进`~/.dsh/source`。已否决：`current`和 PATH 启动器都是每用户唯一的，因此把 worktree 散落到各个克隆的父目录中，会重新引入 source 容器本就为之而设、意在杜绝的同级克隆蔓延问题。
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
index 7bc08eb82d..19dd1f9ab3 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
 2026-08-03-package-anchored-subsystem-pages.md: 5ba7937f0c142727d343a107a3ff87f5f337931e
-2026-08-03-package-anchored-subsystem-pages.zh.md: 27d56158a69a8144b0915054032fb3b54493bd0b
+2026-08-03-package-anchored-subsystem-pages.zh.md: 9166843cbfbbd065eca06e8716098581433ba41d
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
index 27d56158a6..9166843cbf 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## Problem
 
-[子系统目录](2026-06-20-core-data-structures-catalog.md)最初用主干-vs-seam 规则界定首页范围：如果循环在每个轮次都持有、派生、流式传输或记录某个类型，它就是「核心」。该规则选择的是类型而非包，因此当目录增长到四十多页后，首页变成了跨包大杂烩：LLM 对话词汇排在 agent 契约之前，创建/所有权词汇（`AgentHandle`、`CreateAgentOptions`、`ResumeAgentOptions`、`AgentFactory`）在目录中无处记录（生成器把它们豁免给了某个包 README），读者无法根据类型所在位置预测哪一页记录它。与此同时，各包分组 README 没有统一形状——有的带分节表格、游离的设计短文，或本应属于子系统页面的尾部段落。
+[子系统目录](2026-06-20-core-data-structures-catalog.md)最初用主干-vs-seam 规则界定首页范围：如果循环在每个轮次都持有、派生、流式传输或记录某个类型，它就是「核心」。该规则选择的是类型而非包，因此当目录增长到四十多页后，首页变成了跨包大杂烩：LLM 对话词汇排在 agent 约定之前，创建/所有权词汇（`AgentHandle`、`CreateAgentOptions`、`ResumeAgentOptions`、`AgentFactory`）在目录中无处记录（生成器把它们豁免给了某个包 README），读者无法根据类型所在位置预测哪一页记录它。与此同时，各包分组 README 没有统一形状——有的带分节表格、游离的设计短文，或本应属于子系统页面的尾部段落。
 
 ## Decision
 
-每个 `docs/subsystems/` 页面锚定到声明其词汇的包或包分组，页面归属跟随仓库布局：[core.md](../../../../docs/subsystems/core.md) 是 `packages/core` 的页面（创建与所有权、`Agent` 句柄及其投递/取消/拦截契约、指向该组专属页面的指针），[llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) 端到端拥有 `packages/llm`，依此类推。全仓通用类型模式（`…Map → 派生联合`、品牌化 id）保留在 core.md 一个明确标注的收尾小节中，而不是与包内容交错。这在*页面范围界定规则*的意义上取代了主干-vs-seam 规则；存活下来的放置启发式更简单：类型记录在其声明包对应的页面，机制仍与其机制放在一起。
+每个 `docs/subsystems/` 页面锚定到声明其词汇的包或包分组，页面归属跟随仓库布局：[core.md](../../../../docs/subsystems/core.md) 是 `packages/core` 的页面（创建与所有权、`Agent` 句柄及其投递/取消/拦截约定、指向该组专属页面的指针），[llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) 端到端拥有 `packages/llm`，依此类推。全仓通用类型模式（`…Map → 派生联合`、品牌化 id）保留在 core.md 一个明确标注的收尾小节中，而不是与包内容交错。这在*页面范围界定规则*的意义上取代了主干-vs-seam 规则；存活下来的放置启发式更简单：类型记录在其声明包对应的页面，机制仍与其机制放在一起。
 
 生成签名引用的每个类型都必须能在目录中某处解析：agent 所有权词汇从生成器的 `TYPE_LINK_EXEMPTIONS` 移入 `LINK_MAP → core.md`，因此豁免只留给真正服务本地或 vendored 的形状。每个粘贴的声明只有一个家（`SessionEvent` 位于 [session.md](../../../../docs/subsystems/session.md)；core.md 概括并链接）。
 
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 2a4a389174..9cef49fa0a 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
 2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
-2026-08-06-in-repository-landlock-release.zh.md: 9f2233f6ae95620d7221f83648b5dc9b4cf8c7d2
+2026-08-06-in-repository-landlock-release.zh.md: ffebe45c537ee192ef855296b3334937485e2a89
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index 9f2233f6ae..ffebe45c53 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
+`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器约定及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
 发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
index dec1b79d6a..189815bc8d 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
 2026-08-08-api-remotes-generated-contract-build.md: 947465b19a7c399038ae8a3106f7563592365a8d
-2026-08-08-api-remotes-generated-contract-build.zh.md: 7b559cd966c4acc055d41379c15f46fdfc649a00
+2026-08-08-api-remotes-generated-contract-build.zh.md: 26108bc840f701cb02db4a41138024a1be3c549f
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
index 7b559cd966..26108bc840 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: API Remotes 生成契约的有序构建
+# Agent Note: API Remotes 生成约定的有序构建
 
 Status: implemented
 
@@ -12,7 +12,7 @@ Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时
 
 ## 决策
 
-根构建先完成 Host tsc 和 Host tsdown，由 Host tsdown 运行 TypeRT 并生成 Remote Client 契约；随后完成 Client tsc、Client tsdown 和 Web 构建：
+根构建先完成 Host tsc 和 Host tsdown，由 Host tsdown 运行 TypeRT 并生成 Remote Client 约定；随后完成 Client tsc、Client tsdown 和 Web 构建：
 
 ~~~text
 tsc -b tsconfig.host.json
@@ -28,7 +28,7 @@ Vite Web build
 
 ## 唯一的 package 特例
 
-`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
+`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成约定的 `src/client/index.ts`：
 
 ~~~text
 packages/api/remotes/
@@ -47,11 +47,11 @@ packages/api/remotes/
 
 两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立 package，不能把同一源码同时交给两个 emitting project。
 
-这个例外由生成契约的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
+这个例外由生成约定的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
 
 ## TypeRT 与 tsdown
 
-Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 契约投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
+Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 约定投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
 
 TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` package 即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口 package 的 Host 模型也不会丢失。
 
@@ -69,11 +69,11 @@ Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cl
 
 **扫描 Client 编译产物或维护两份 workspace 清单。** 产物扫描会让 package 是否参与构建取决于残留文件，手工清单和 package 名过滤则会随目录调整产生漂移。完整 workspace 加包内 face 选择已经提供确定行为。
 
-**在 Client pass 再运行 TypeRT。** Remote Client 是 Host 契约的投影，没有独立 Client 反射源；第二个 TypeRT program 只会重复工作并增加两侧声明混入同一分析的风险。
+**在 Client pass 再运行 TypeRT。** Remote Client 是 Host 约定的投影，没有独立 Client 反射源；第二个 TypeRT program 只会重复工作并增加两侧声明混入同一分析的风险。
 
 ## 后果
 
-干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成契约，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
+干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成约定，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
 
 [TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通 package 单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
index 0c44f790b7..9e1fcce244 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
 2026-08-08-automatic-translation-pairing-merges.md: ac4e0c11290abfd48d0f3caf037062aa2fe36c4d
-2026-08-08-automatic-translation-pairing-merges.zh.md: 38e8c0a5613a6bd0b3e76143a93c93653430d0c2
+2026-08-08-automatic-translation-pairing-merges.zh.md: 149f37ec61689e01fa713dabe0ded5506dff4fed
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
index 38e8c0a561..149f37ec61 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 `pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
 
-## 失败契约
+## 失败约定
 
 | 普通 `git merge` 期间的失败 | 可观察状态 | 恢复 |
 |---|---|---|
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
index 5ee57b914f..2e33d34157 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
 2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
-2026-08-08-unified-github-label-taxonomy.zh.md: c8d727c9a56d6c7c25f73eacde42e0bef1c779b7
+2026-08-08-unified-github-label-taxonomy.zh.md: 75333e3823d6e96ef41b1359a81d53f4bd872f87
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
index c8d727c9a5..75333e3823 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
@@ -27,18 +27,18 @@ Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对
 | `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
 | `kind/dependency` | 在没有其他主导意图时更新依赖。 |
 
-类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类契约，因此必须明确修改分类体系和政策。
+类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类约定，因此必须明确修改分类体系和政策。
 
 仓库政策会拒绝不支持的 `kind/*` 值，并将统一过程中移除的所有别名列为保留名称：`kind/bug`、`kind/documentation`、`feature`、`bug-fix`、`doc`、`cleanup`、`testing`、`dependencies`、`ci`、`cli`、`llm` 和 `web-search`。精确保留这组已迁移的名称，可以防止过时的同义名称被重新创建成看似无关的管理用途标签。
 
 ### 领域
 
-领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
+领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同约定时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项约定。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
 
 - `area/web` 覆盖浏览器与 Electron 图形界面，`area/vscode` 覆盖编辑器扩展，`area/api` 覆盖跨界面协议与各语言 SDK。
 - `area/planning` 覆盖目标、计划、待办和调度，`area/workflow` 则覆盖可执行工作流与后台任务运行时。
 - `area/artifact` 有意合并产物、附件与多模态交付。只有当这些关注点再次需要独立评审或查询时，才有理由拆分标签。
-- `area/tools` 适用于通用注册表、schema 与执行契约。具体能力使用自身的领域标签，除非它还修改了这项通用契约。
+- `area/tools` 适用于通用注册表、schema 与执行约定。具体能力使用自身的领域标签，除非它还修改了这项通用约定。
 - `area/hooks` 表示 Claude Code 与 Codex 桥接，`area/infra` 覆盖构建、发布、CI、仓库门禁、生成器、依赖与开发者工具，`area/windows` 覆盖原生 Windows 产品支持，而不是 CI runner 的选型。
 
 领域集合有意保持可扩展。当现有说明都无法如实涵盖一个持久且可复用的领域时，agent（智能体）无需另行批准，即可创建一个简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后向请求者报告该标签及理由。仅为避免新增一个确有必要的领域标签而复用不准确的领域，不可接受。
@@ -61,11 +61,11 @@ Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然
 
 **为每种交付载体或媒体生命周期单设标签。** 浏览器与 Electron 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
 
-**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身契约变化时适用。
+**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身约定变化时适用。
 
 **在 Issue 上使用类型标签。** 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
 
-**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立契约产生实质影响，丢弃次要领域会隐藏受影响范围。
+**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立约定产生实质影响，丢弃次要领域会隐藏受影响范围。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
index ee84bcf366..2233dcadde 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
 2026-06-19-drop-mutable-session-summary.md: f87378a1c3737950eb536be8e3f6776586eb8a01
-2026-06-19-drop-mutable-session-summary.zh.md: 41dab3fa0b487b057d33335a21cee92cf211560f
+2026-06-19-drop-mutable-session-summary.zh.md: f15dcc038154a9170ac41fd5733712164728f518
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
index 41dab3fa0b..f15dcc0381 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 - `firstPrompt` 在生产代码中**从未被读取**。
 - 会话标题来自持久的 `session/title` 事件，工具卡片标题来自工具 presenter；二者都不读取可变的会话元数据。
 - 持久化列表的消费方使用不可变 header 中的标识、创建时间、谱系和 cwd 字段。近期排序和预览派生自日志，而非某个 `updatedAt` 摘要。
-- 决定性的一点：活跃的 `Session.header` 类型本来就是 `SessionHeader` 而非 `SessionMeta`——摘要从未存在于活跃会话对象上；它只存在于持久化层，除了自身的契约测试外无人写入、无人读取。
+- 决定性的一点：活跃的 `Session.header` 类型本来就是 `SessionHeader` 而非 `SessionMeta`——摘要从未存在于活跃会话对象上；它只存在于持久化层，除了自身的约定测试外无人写入、无人读取。
 
 ## 决策
 
@@ -22,7 +22,7 @@ Status: implemented
 
 摘要原本要提供的一切，在消费方真正需要时都**可从仅追加日志中派生**（`firstPrompt` = 第一条 `user/message`；近期度 = 最后一个事件的 `time` 或文件 mtime），或者已经存在于不可变 header 中（`createdAt`、`cwd`）。唯一*不可*派生的是用户*手动编辑*的标题，但它从未实现，纯属 YAGNI；如果未来真有功能需要，它可以作为独立的日志事件或 header 字段回归。
 
-这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公开服务契约和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**反直觉性**（未来读者在原 Agent Note 描述 `SessionMeta` 的位置发现 `SessionHeader` 时，若无此记录便会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
+这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公开服务约定和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**反直觉性**（未来读者在原 Agent Note 描述 `SessionMeta` 的位置发现 `SessionHeader` 时，若无此记录便会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
 
 ## 无需迁移
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-未来的会话选择器现在必须从日志派生预览/排序信息（或重新引入一个类型化字段），而不能直接读取现成的摘要行。这是正确的代价：为一个尚不存在的功能维护缓存，是每个后端都要承担维护成本、每个契约测试都要承担断言成本的无谓负担。这一原则——**通过的测试固定的是当前行为，不一定是正确行为；行为可能是过去妥协的产物**——现已作为独立约定记录在[根 AGENTS.md](../../../../AGENTS.md) 中，本次变更即为其实例。
+未来的会话选择器现在必须从日志派生预览/排序信息（或重新引入一个类型化字段），而不能直接读取现成的摘要行。这是正确的代价：为一个尚不存在的功能维护缓存，是每个后端都要承担维护成本、每个约定测试都要承担断言成本的无谓负担。这一原则——**通过的测试固定的是当前行为，不一定是正确行为；行为可能是过去妥协的产物**——现已作为独立约定记录在[根 AGENTS.md](../../../../AGENTS.md) 中，本次变更即为其实例。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index 3b50695584..77b76293e3 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
 2026-06-20-public-agent-stop-surface.md: e9c713c7ba8c784d3d66fe8f391e1b197f7394d2
-2026-06-20-public-agent-stop-surface.zh.md: 217c898eec6b9e232f2cf3982b2bec411e8d91ab
+2026-06-20-public-agent-stop-surface.zh.md: c57bb32643344c237dd68479e3ab8f8a7404a594
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index 217c898eec..c57bb32643 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者原本只暴露广义默认行为，该行为会清除已排队和 steering（中途引导）工作，同时中止活动轮次。`cancel(cause, { keepInbox: true })` 现在无需暴露私有轮次 holder 即可覆盖生产环境的 Web 停止策略；ACP 保留广义取消，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。
 
-行为差异确实存在，但已发布代码不需要独立的更窄动词。AgentLoop 为整个轮次拥有一个私有取消 holder。`cancel(cause, options?)` 携带显式且类型化的 `user` 或 `parent` 原因；其广义默认行为丢弃待处理输入，`keepInbox` 则为后续轮次保留待处理工作。资源释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note](../architecture/2026-07-16-explicit-turn-cancellation.md)。
+行为差异确实存在，但已发布代码不需要独立的更窄动词。AgentLoop 为整个轮次拥有一个私有取消 holder。`cancel(cause, options?)` 携带显式且类型化的 `user` 或 `parent` 原因；其广义默认行为丢弃待处理输入，`keepInbox` 则为后续轮次保留待处理工作。资源释放仍是单独的生命周期中断。完整的归属与传播约定位于[显式轮次取消 Agent Note](../architecture/2026-07-16-explicit-turn-cancellation.md)。
 
 多余的公开接口使循环承载了一个本质上属于内部拆卸的公开动词。带选项的 `cancel()` 可以表达调用方策略，而无需暴露第二个 holder 形态的操作。
 
 ## 决策
 
-`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。
+`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 约定。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。
 
 `whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。
 
@@ -32,7 +32,7 @@ Status: implemented
 
 ## 后果
 
-插件可以通过 `keepInbox` 在保留已排队提示词的同时中止活动轮次，但不能只中止某一个模型／工具步骤而让该轮次继续运行。仅步骤用例需要具名消费方和更窄契约；暴露私有循环机制仍缺乏正当理由。
+插件可以通过 `keepInbox` 在保留已排队提示词的同时中止活动轮次，但不能只中止某一个模型／工具步骤而让该轮次继续运行。仅步骤用例需要具名消费方和更窄约定；暴露私有循环机制仍缺乏正当理由。
 
 ## 相关
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index f0e7bb8fb9..7aab9c96af 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
 2026-06-26-fsspec-style-fs-seam.md: b5c201fb192782f130d3609978d16f0fc6d4d55e
-2026-06-26-fsspec-style-fs-seam.zh.md: 8346ba76d099a458236e200f304c4921553584d3
+2026-06-26-fsspec-style-fs-seam.zh.md: 2ed74af594296f2853f4d97474c4ee07ef83dbd5
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
index 8346ba76d0..2ed74af594 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -30,9 +30,9 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 `dsh-tool-fs` 保持相同的面向模型的 `read`/`write`/`edit` schema。它是执行器：注入 `fs`（不是策略服务）并直接访问 `ctx.fs`，拥有读取窗口化逻辑，并分发 `fs/*` 事件以便 `dsh-fs-policy` 进行门控和记录。
 
-本 Agent Note 决定了四层拆分、提供方契约和新鲜度策略。随后，[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 细化了工具↔策略耦合：`dsh-fs-policy` 是通过 `fs/*` 事件参与的门禁插件，而非 `ctx.fileContext` 方法服务，因此工具不会在方法层与其耦合；读取窗口和 fs I/O 位于 `dsh-tool-fs`。本文描述已经落地的事件门禁形状；提供方的版本守卫可选（省略即无条件裸提供方）。
+本 Agent Note 决定了四层拆分、提供方约定和新鲜度策略。随后，[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 细化了工具↔策略耦合：`dsh-fs-policy` 是通过 `fs/*` 事件参与的门禁插件，而非 `ctx.fileContext` 方法服务，因此工具不会在方法层与其耦合；读取窗口和 fs I/O 位于 `dsh-tool-fs`。本文描述已经落地的事件门禁形状；提供方的版本守卫可选（省略即无条件裸提供方）。
 
-## 提供方契约
+## 提供方约定
 
 `@deepseek-ai/dsh-fs` 收缩为提供方文本 IO 加受保护的文本变更：
 
@@ -65,9 +65,9 @@ type FsWriteIntent =
 
 这是一个*文本存储* seam，刻意比字节级 fsspec（`cat`/`open` 返回原始字节）高半个层次。UTF-8 解码、二进制/NUL 拒绝、受保护的全文件写入和受保护的字面文本编辑都在提供方内完成，因此策略层从不接触原始字节、不重新实现跨分片解码、也不将陈旧检查与变更临界区分离。面向模型的概念仍然不下沉到提供方：行窗口、带行号的行、渲染的页脚、观测状态存储都不会泄漏下去。
 
-从 `dsh-fs` 删除：`readPage`、`FsExpectation`、`FsView`、`FsStateSource`、`FsReadRequest`、`FsTextLine`、行/窗口常量、`formatReadBody` 和 observed-state `WeakMap`。`applyEdit` 由更窄的提供方原语 `editText` 取代，其契约是带版本守卫的字面文本变更，而非策略层读取授权。`FS_PARTIAL_OBSERVATION` 错误码也从 `FsErrorCode` 分类体系中移除：新鲜度授权没有部分/完整之分，因此没有任何路径会抛出它。`FsTargetKey` 和 `FsVersion` 按现有[品牌化 id Agent Note](../architecture/2026-06-20-branded-ids.md) 成为品牌化不透明 id。
+从 `dsh-fs` 删除：`readPage`、`FsExpectation`、`FsView`、`FsStateSource`、`FsReadRequest`、`FsTextLine`、行/窗口常量、`formatReadBody` 和 observed-state `WeakMap`。`applyEdit` 由更窄的提供方原语 `editText` 取代，其约定是带版本守卫的字面文本变更，而非策略层读取授权。`FS_PARTIAL_OBSERVATION` 错误码也从 `FsErrorCode` 分类体系中移除：新鲜度授权没有部分/完整之分，因此没有任何路径会抛出它。`FsTargetKey` 和 `FsVersion` 按现有[品牌化 id Agent Note](../architecture/2026-06-20-branded-ids.md) 成为品牌化不透明 id。
 
-## 策略契约
+## 策略约定
 
 `@deepseek-ai/dsh-fs-policy` 是插件，而非服务：它不注册任何 `ctx.*` 键，也不注入任何内容。它拥有不应位于 `FileSystem` 提供方基类上的写入/编辑新鲜度策略和 observed state（否则沙箱/远程后端会继承不该由其承载的面向模型观察策略）。它通过执行器分派的 `fs/*` 事件门禁贡献该策略。（本 Agent Note 最初提议带有 `read`/`write`/`edit` 方法的具体 `ctx.fileContext` 服务；[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 将其细化为本文所述插件，使工具永远不会在方法层与策略耦合。）
 
@@ -81,7 +81,7 @@ type FsWriteIntent =
 
 该插件不做任何文件系统 I/O：「你是否观测过此文件？」是一次 `WeakMap` 查找，而「你读取的版本是否仍然是当前版本？」在 `ctx.fs.editText`/`writeText` 内部、与执行变更相同的原子锁中决定——插件只提供 `vObserved` 作为基础。
 
-## 工具契约
+## 工具约定
 
 `dsh-tool-fs` 保持相同的 schema 和提示词表面。`read` 仍然暴露 `file_path`、`offset` 和 `limit`；`write` 和 `edit` 不变。它是执行器：验证模型参数，通过 `ctx.fs` 直接读取/写入/编辑，拥有行窗口化和结果渲染（`N: text`、页脚、`<path>/<content>` 封装），并分发 `fs/*` 事件。
 
@@ -109,7 +109,7 @@ type FsWriteIntent =
 
 ## 验证
 
-`dsh-fs` 精确暴露 `resolve`/`stat`/`readText`/`streamText`/`writeText`/`editText`（`stat` 返回 `FsInfo | undefined`，`writeText` 接受 `FsWriteIntent`），已删除的类型/原语不再存在；`dsh-fs-local` 不包含行、视图或 `formatReadBody` 逻辑；面向模型的 schema 保持逐字节不变。测试固定了以下行为：窗口化读取授权对未变文件的后续编辑；基于陈旧读取的编辑在尝试字面匹配之前报告 `FS_STALE_VERSION`；版本 CAS 行为得以保留；观测契约成立（`read` 工具的读取记录观测状态；直接 `ctx.fs` 读取不记录）；`dsh-fs-policy` 具有 HMR（热模块替换）/dispose（资源释放）测试覆盖。
+`dsh-fs` 精确暴露 `resolve`/`stat`/`readText`/`streamText`/`writeText`/`editText`（`stat` 返回 `FsInfo | undefined`，`writeText` 接受 `FsWriteIntent`），已删除的类型/原语不再存在；`dsh-fs-local` 不包含行、视图或 `formatReadBody` 逻辑；面向模型的 schema 保持逐字节不变。测试固定了以下行为：窗口化读取授权对未变文件的后续编辑；基于陈旧读取的编辑在尝试字面匹配之前报告 `FS_STALE_VERSION`；版本 CAS 行为得以保留；观测约定成立（`read` 工具的读取记录观测状态；直接 `ctx.fs` 读取不记录）；`dsh-fs-policy` 具有 HMR（热模块替换）/dispose（资源释放）测试覆盖。
 
 ## 后续扩展
 
@@ -126,5 +126,5 @@ type FsWriteIntent =
 - 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端 seam。
 - 直接使用 `ctx.fs` 会绕过策略：直接 `ctx.fs.readText` 不发出 `fs/observed`，因此在默认策略下，后续 `edit` 会以 `FS_NOT_OBSERVED` 拒绝，直到通过 `read` 工具读取该文件。这一失败是显式且有文档记录的。
 - 大文件行窗口化从后端移至 `dsh-tool-fs` 中的 `read` 工具；文本解码和二进制拒绝留在 `ctx.fs.streamText` 中，因此这只是窗口化逻辑的迁移，而非第二套文本 IO 实现。
-- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换契约。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该契约应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
+- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换约定。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该约定应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
 - 新鲜度允许在窗口化读取后进行全文件 `write`。这比旧的视图检查更弱，但避免了大文件无法编辑的问题；提示词引导仍然不鼓励盲目的全文件替换。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
index be9546102e..6a77e7a95a 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
 2026-07-04-tighten-hook-protocol-contract.md: a67d0e8447e36516006e57051581c03877c1ba12
-2026-07-04-tighten-hook-protocol-contract.zh.md: 638455d89923d0636483c8e8f39fb0613daa1376
+2026-07-04-tighten-hook-protocol-contract.zh.md: b57a8da8d9f0f921b69d0b63ad5c655eb47f5967
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
index 638455d899..b57a8da8d9 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 收紧 hook-protocol 契约——dialect、被丢弃的字段、双重默认值与 lib 拥有的 `hook/result` 语义
+# Agent Note: 收紧 hook-protocol 约定——dialect、被丢弃的字段、双重默认值与 lib 拥有的 `hook/result` 语义
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`dsh-hook-protocol`/bridge 契约中有四部分没有遵守 [subagent observe/enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)记下的准则——后者因缺少消费方而删除 `agentType` 生命周期字段，以下各项没有通过同一检验：
+`dsh-hook-protocol`/bridge 约定中有四部分没有遵守 [subagent observe/enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)记下的准则——后者因缺少消费方而删除 `agentType` 生命周期字段，以下各项没有通过同一检验：
 
 1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截 seam Agent Note](../feature/2026-06-30-interception-seams.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
 2. **`HookOutput.suppressOutput`**（同一文件）被 codec 解析后在所有路径上均被丢弃：没有 bridge 分支处理它、没有合并 fold、没有 warn、没有 deferred-list 行——在所有「被解析但未兑现」的同类字段中它是唯一没有明确延期声明的（`updatedInput` → 一条 warn 日志加 [pre-tool-input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)；`systemMessage` → 一条 warn 日志加 README deferred 行；`continue`/`stopReason` → 一个 `TODO(hook-continue-false)` 锚点加 `'stop'` decision 记录）。从结构上看根本无物可抑制：钩子 stdout 从不进入任何 transcript（文本记录）；上下文仅通过 `additionalContext` 流入，日志也只记录 `decision`/`stderrSummary`。因此，钩子作者设置 `suppressOutput: true` 得到的是无声的空操作，且无任何警告。
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
index 1a4259e08c..4edba8fd79 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
 2026-07-12-simplify-session-log-representation.md: a40f4013a97a9c940012dbb37d59beb2faf8fb22
-2026-07-12-simplify-session-log-representation.zh.md: 30808a4eff83b32bd0c47cc6e6cb211f2222b363
+2026-07-12-simplify-session-log-representation.zh.md: c4393511e1a78edacf60bc54a764721ad50e4d9d
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
index 30808a4eff..c4393511e1 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 `SurfaceManager` 同时在数组、seq map 和可变 `prev`/`next` 链接中存储相同顺序。生产代码从不读取任一链接：compact 的工具配对 balance 根据按 surface 顺序缓存的每个切点 balance 作答。替换已经使用 `indexOf`，因此链接并未使其主导操作成为常数时间。使用线性替换查找的 seq 数组具有相同的渐近替换成本，却只有一种表示需要验证。
 
-请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其契约声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
+请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其约定声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
 
 实现保留追加与替换操作的 `sourceEventSeqs`、崩溃修复的溯源信息，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
index af534f7b4b..dc75549250 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
 2026-07-17-one-send-one-turn.md: 834eb2b3aace0a0aa5f86f483e7b7d7aabbe467e
-2026-07-17-one-send-one-turn.zh.md: d05ce63c404ce4d10ac098e3a3c9617443cc278b
+2026-07-17-one-send-one-turn.zh.md: 5bd2ed0e70766c43b0a0a5d5d4038b39094d5099
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
index d05ce63c40..5bd2ed0e70 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**保留普通 send 的自动批处理，以减少模型调用。** 当消息进入队列的速度超过驱动器的处理速度时，这种做法可以提高吞吐量，但会让轮次边界取决于调度，并让后一条消息在前一轮关闭且到达检查点之前运行。本决策保留可预测的边界，并接受额外调用。未来若要加入批处理功能，必须提供调用方可见的显式契约，并有测量结果作为依据。
+**保留普通 send 的自动批处理，以减少模型调用。** 当消息进入队列的速度超过驱动器的处理速度时，这种做法可以提高吞吐量，但会让轮次边界取决于调度，并让后一条消息在前一轮关闭且到达检查点之前运行。本决策保留可预测的边界，并接受额外调用。未来若要加入批处理功能，必须提供调用方可见的显式约定，并有测量结果作为依据。
 
 ## 验证
 
@@ -42,4 +42,4 @@ Status: implemented
 
 普通轮次的边界可预测：消息 A、B 始终分开，B 只能在 A 关闭并到达检查点后运行。调用方仍然拿不到逐次 send 的完成句柄；待处理消息可通过其 `MessageId` 移除，面向整个 agent 的取消可以丢弃整个尚未启动的队尾，而状态与完全停稳仍是面向整个 agent 的观察。
 
-代价是模型请求和检查点都会增加。繁忙队列可能需要更长时间才能清空；如果生产方持续提交消息，队列也可能增长。只有建立显式且经过测量的契约后，才能重新引入普通 send 批处理。
+代价是模型请求和检查点都会增加。繁忙队列可能需要更长时间才能清空；如果生产方持续提交消息，队列也可能增长。只有建立显式且经过测量的约定后，才能重新引入普通 send 批处理。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index a21ac5cfe9..dcef1b190f 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
 2026-07-20-remove-stdio-and-echo-agents.md: 256e626f4ff41016d0227eef7cc3e4e51e15058b
-2026-07-20-remove-stdio-and-echo-agents.zh.md: bb7a2abd8be73ac3ea089121592b3f26162bf619
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 013135eff5d1dbbc570561e70c751ff4de289989
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index bb7a2abd8b..013135eff5 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -28,14 +28,14 @@ SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换
 
 ## 验证
 
-TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
+TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果约定和工具调用约定。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）约定。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 
-- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务契约、格式纯净的 stdout、持久完成边界和进程退出状态。
-- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的契约。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
+- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务约定、格式纯净的 stdout、持久完成边界和进程退出状态。
+- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的约定。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
 - **保留 Echo 作为无密钥快速上手路径**：不予采纳，因为首次产品体验应使用真实模型和受支持的 coding agent，而不是带专用工具的脚本化适配器。
 - **只为 CI 演示命令保留 Echo**：不予采纳，因为由测试持有的 Headless fixture 可以覆盖相同的 Loader 和构建产物边界，无需保留 mock 产品叶节点。
 - **移除所有 stdio 或 mock 机制**：不予采纳，因为分帧协议、进程 I/O 和确定性测试适配器是独立基础设施，并不是被移除的 agent。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml
index d6fa35a75d..b6c8b3dc89 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md
 2026-07-20-unwrap-injected-content-envelopes.md: aff458d76027bf5518497328ee1bd852869793b9
-2026-07-20-unwrap-injected-content-envelopes.zh.md: 59cbd823da3305185a05c79207fbd7b702a11fba
+2026-07-20-unwrap-injected-content-envelopes.zh.md: 727ce5e490b6115ad0b3ce383059aabcffd4c7b0
diff --git a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md
index 59cbd823da..727ce5e490 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 
 - **保留 `<context>` 封套，只对 steering（中途引导）去封套** —— 会为一个没有模型会读的框架位保留 `ContextEnvelope`/`envelope` 机制，并保留主要生产方本就退出的那种不一致。
 - **仅对插件来源的内容保留 envelope 字段** —— 会按 `source.kind` 把一条投影拆成两条，却没有观察到任何收益；插件引导 agent 时（钩子桥接器的轮次续行原因）同样希望指令被遵从，而不是被贴标签。
-- **把去封套的逻辑移入适配器** —— 规范投影就是模型可见契约（「模型可见 ⟺ 已记录」）；让各适配器在框架上各行其是，会使派生的 transcript 依赖于适配器。调用方确实想要的框架应放进调用方自己的内容里，而不是适配器。
+- **把去封套的逻辑移入适配器** —— 规范投影就是模型可见约定（「模型可见 ⟺ 已记录」）；让各适配器在框架上各行其是，会使派生的 transcript 依赖于适配器。调用方确实想要的框架应放进调用方自己的内容里，而不是适配器。
 
 ## 结果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
index b6ef95a950..9c7359d8d6 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
 2026-07-22-plan-specific-collaboration-state.md: d139f3d861244c80acfb604d17172461bbf0cd57
-2026-07-22-plan-specific-collaboration-state.zh.md: dbf90357e4c4967d9665533c9abd2b4e1838da27
+2026-07-22-plan-specific-collaboration-state.zh.md: 3d51b8fc31196efca49693050258c323ff3af843
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
index dbf90357e4..3d51b8fc31 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
@@ -22,7 +22,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 沙箱模式与审批策略仍是彼此独立的强制约束轴。Plan mode 既不读取也不写入二者；此次简化也没有为这些概念引入共享基类型、注册表或预设抽象。
 
-### 边界与模型契约
+### 边界与模型约定
 
 `plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩（compaction）都能恢复该状态，无需实时镜像。spawn 出的 agent（智能体）初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step 时，或在请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。
 
@@ -55,7 +55,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 **按 plan 专用名称允许列表或全局策略栈筛选工具。** 不予采纳，因为可变性是每个工具自身的属性，包括未来工具和 MCP 工具，而不应由每个 plan 部署维护一份列表。只有出现具体消费方后，effects 元数据才能建立共享策略；在此之前，plan mode 是引导机制，不是安全边界。
 
-**通过审批 seam 或普通文本完成评审。** 不予采纳，因为计划评审不是权限决策，需要原样的计划产物和纠正性自由文本，而且必须以已记录的工具调用作为结构化转换。用户交互 seam 提供了这项契约。
+**通过审批 seam 或普通文本完成评审。** 不予采纳，因为计划评审不是权限决策，需要原样的计划产物和纠正性自由文本，而且必须以已记录的工具调用作为结构化转换。用户交互 seam 提供了这项约定。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
index 3889001fe3..736a9aee5f 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
 2026-07-23-acp-automation-only-protocol.md: 0fe2fc27a963d21e8a24c1682359ab3bc9e7af48
-2026-07-23-acp-automation-only-protocol.zh.md: bd21696c40811adeb8b8883ef57c30f9321f4ea4
+2026-07-23-acp-automation-only-protocol.zh.md: d161f22672b1c1a1db131a58b4b8da531930ab97
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
index bd21696c40..d161f22672 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
@@ -34,9 +34,9 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 ## 考虑过的替代方案
 
-**在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互契约，并使编辑器约定继续存在于自动化边界中。
+**在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互约定，并使编辑器约定继续存在于自动化边界中。
 
-**通过严格的 seam 保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项契约。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
+**通过严格的 seam 保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项约定。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
 
 **用私有 subagent RPC 替换 ACP。** 不予采用，因为 ACP 已经提供类型化、可互操作的进程协议，并由跨进程 subagent 后端使用。
 
@@ -46,7 +46,7 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 ## 结果
 
-ACP 具有适合 agent 与自动化的精简契约，而 TUI 和 Web 拥有面向人类的交互与展示。该包注入的服务、依赖、协议分支和生命周期状态更少，也不再将自身定位为通用编辑器入口。
+ACP 具有适合 agent 与自动化的精简约定，而 TUI 和 Web 拥有面向人类的交互与展示。该包注入的服务、依赖、协议分支和生命周期状态更少，也不再将自身定位为通用编辑器入口。
 
 自动化客户端收到完整的已提交文本，而不是 token 增量或结构化工具 UI。当它们需要推理、工具跟踪信息、标题或更丰富的状态时，需要查看持久日志或其他 API。只支持全新会话也意味着，需要浏览持久会话或恢复会话的调用方必须使用 host API，而不是 ACP。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index 1bd3e02df3..33051c7a3d 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
 2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
-2026-07-23-collapse-persistence-flush-state.zh.md: d5b02ebc545a32fbdb44feed04ec2afbbafeff4b
+2026-07-23-collapse-persistence-flush-state.zh.md: 48896c7080ae28174e259318869c65b48b13418e
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index d5b02ebc54..48896c7080 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -35,12 +35,12 @@ Status: implemented
 ## 验证
 
 - 针对控制器的测试使用假时钟证明固定窗口不会重置，随后阻塞第一次追加，在该次写入期间接纳另一个事件，并在不调用 `session/flush` 的情况下观测到自动执行的第二个持久批次。
-- 共享协调器契约仍覆盖内存、JSONL 和 SQLite 后端上的活跃会话接管、冲突、崩溃修复，以及会话和后端的资源释放。
+- 共享协调器约定仍覆盖内存、JSONL 和 SQLite 后端上的活跃会话接管、冲突、崩溃修复，以及会话和后端的资源释放。
 - 失败和资源销毁测试会让写入失败的批次保持待处理，在关闭前重试这些批次，并证明尚在执行的控制器会延迟后端关闭。
-- 共享后端契约会持久化一个仍打开的活跃轮次，证明 `load` 会拒绝且不会写入合成闭合事件，随后完成该轮次并让其所有者退役，最后重新加载完全相同的已完成轮次。
+- 共享后端约定会持久化一个仍打开的活跃轮次，证明 `load` 会拒绝且不会写入合成闭合事件，随后完成该轮次并让其所有者退役，最后重新加载完全相同的已完成轮次。
 - AgentLoop 回归测试让 `resume()` 与一个仍打开的活跃轮次发生竞态，并证明原有的 agent（智能体）仍能完成该轮次并将其持久化，其间不会注入 `interrupted` 边界。
 - 一个受控后端会阻塞 `loadStored`，在修复操作持有标识占用期间尝试发布同 id 会话，并证明回滚不会留下残留控制器，之后可以成功恢复一个闭合会话。
-- 无所有者认领契约会为活跃 `Session` 设置不同的 `createdAt`，并证明活跃加载和之后的冷态加载均返回最初存储的标头。
+- 无所有者认领约定会为活跃 `Session` 设置不同的 `createdAt`，并证明活跃加载和之后的冷态加载均返回最初存储的标头。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
index 5067b15402..611d20bfe2 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
 2026-07-24-agent-loop-observable-state-machine.md: b1773fdf7fd3bcbea9c6b9a4a0ce37c715bce4ca
-2026-07-24-agent-loop-observable-state-machine.zh.md: f47e5901ec97a44efa00cf79ef8ce52fdcac9878
+2026-07-24-agent-loop-observable-state-machine.zh.md: ef44e9c058d165bfbbe226e9d0fca1e6f8072f53
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
index f47e5901ec..ef44e9c058 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
@@ -14,7 +14,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 ## 决策
 
-公开契约暴露四个正交的状态维度：
+公开约定暴露四个正交的状态维度：
 
 - 注册生命周期是从 `agent/created` 到 `agent/disposed` 的区间。dispose（资源释放）是注册表的终止边界，而不是一种 `AgentStatus`。
 - agent 整体活动状态为 `AgentStatus = 'idle' | 'running'`。连续多个轮次可以共用同一个 `running` 区间。
@@ -31,7 +31,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 ## 考虑过的替代方案
 
-**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开契约，并允许相互重叠的 seam 表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
+**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开约定，并允许相互重叠的 seam 表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
 
 **将 dispose 表示为第三种 `AgentStatus`。** 这样会让仍被持有的句柄得到一个终止状态值，但也会重复表达 `agent/disposed` 已经体现的注册表生命周期。当前决策让 `AgentStatus` 只表示 agent 存续期间的活动状态，并将注册生命周期作为独立维度。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
index 2fb2e4cf9b..c9735b903f 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
 2026-07-26-merge-subagent-control-service.md: ae7214f7c8c28f8a4b7d754839acbc938270f125
-2026-07-26-merge-subagent-control-service.zh.md: dc05e03c5d38df0317291aee2ffc1395dab8e362
+2026-07-26-merge-subagent-control-service.zh.md: 85a7f62ce789d80dc38ca52017554aa2c2921599
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
index dc05e03c5d..85a7f62ce7 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排契约。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
+可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
 
 ## 决策
 
@@ -18,7 +18,7 @@ Status: implemented
 
 继续执行的实现仍是内部管理器，不会扩展提供方注册表的核心状态。`SubagentService` 通过 `ctx.inject(['tasks', 'agents'], ...)` 创建该管理器，因此注入的 Cordis child fiber 拥有自身的 Task 完成监听器和拆卸 effect。加载提供方注册表不要求 Task 或持久化。只有 Task 和 Agent 可用时，该管理器才会存在；每项继续执行操作都在需要持久性时解析会话持久化服务。dispose（资源释放）该 fiber 会先取消并结算活跃的继续执行，再释放其关联。
 
-`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序契约不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层契约，改动反而多于保留现有的显式入口。
+`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序约定不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层约定，改动反而多于保留现有的显式入口。
 
 每个 `@deepseek-ai/dsh-tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`，默认值为 `one-shot`。这项配置表示策略；`provider.resume` 只用于检查所配置的可继续模式是否受提供方支持。因此，可恢复的提供方仍可执行一次性后台工作。`send_message` 工具是独立适配器：加载或省略该工具既不会启用也不会禁用 `startContinuable`。
 
@@ -30,7 +30,7 @@ Status: implemented
 
 **注册继续执行访问入口，或检查后续操作工具。** 注册表可以告诉委派工具继续执行接口是否存在，但启动具备持久性的工作不需要任何后续操作适配器。这样的注册表会把 UI 组合编码进执行策略，并以另一个名称重新建立插件间依赖关系。
 
-**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项契约。
+**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项约定。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml
index 6c6ead17b7..e386775842 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.md
 2026-07-28-local-json-tree-renderer.md: 5e8e6d6968319ada53e65a48e9e03b297dc0141c
-2026-07-28-local-json-tree-renderer.zh.md: f3a9faa5f9de264d0b7eadac631f7f4afff166b2
+2026-07-28-local-json-tree-renderer.zh.md: 1d491af9a76f1be1c89859e26c058d9460580095
diff --git a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md
index f3a9faa5f9..1d491af9a7 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md
@@ -13,19 +13,19 @@ Status: implemented
 `dsh-client-ui-primitives` 中的 `JsonTree` 自行负责递归呈现。
 
 - 每个渲染行都直接接收自身的值和属性路径。递归时，对象键和数组索引会附加到路径末尾，因此复制操作无需再从 DOM 渲染文本中反向还原应用数据。
-- 可展开行在本地渲染紧凑预览，仅在展开时挂载子行。`expandTopLevel` 可选择固定展开的括号框架或可折叠根节点，而不改变组件的公开契约。
+- 可展开行在本地渲染紧凑预览，仅在展开时挂载子行。`expandTopLevel` 可选择固定展开的括号框架或可折叠根节点，而不改变组件的公开约定。
 - 树中所有可见节点仅保留一个可通过 Tab 键聚焦的展开控件。使用指针激活控件后，该控件会成为 Tab 键焦点位置；上、下方向键循环移动焦点，左、右方向键折叠或展开当前焦点所在节点。
 - `react-json-view-lite` 不在 `dsh-client-ui-primitives` 的依赖项中，也没有 pnpm 补丁。针对性组件测试锁定预览、展开、键盘焦点和数组复制路径。
 
 ## 曾考虑的替代方案
 
-**保留发布文件补丁。** 不予采纳：应用专用的渲染逻辑和数组标识契约仍会隐藏在生成的第三方文件中；每次更新依赖，都必须评审一个没有配套源码映射的 fork。
+**保留发布文件补丁。** 不予采纳：应用专用的渲染逻辑和数组标识约定仍会隐藏在生成的第三方文件中；每次更新依赖，都必须评审一个没有配套源码映射的 fork。
 
 **直接使用不提供预览的上游渲染器。** 不予采纳：`{…}` 和 `[…]` 会丢失轨迹检查器扫读时所需的紧凑载荷上下文。
 
 **渲染后注入预览和行元数据。** 不予采纳：Effect 或 MutationObserver 仍会依赖同一套私有 DOM 结构，同时使 React 和命令式变更机制分别负责同一行的不同部分。
 
-**采用更大型的 JSON 查看器。** 不予采纳：编辑、搜索与主题系统不在当前只读契约范围内；扩大依赖范围也无法去除检查器专用的复制和布局代码。
+**采用更大型的 JSON 查看器。** 不予采纳：编辑、搜索与主题系统不在当前只读约定范围内；扩大依赖范围也无法去除检查器专用的复制和布局代码。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
index 3245b307e5..53c32d5278 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-30-private-agent-send.md
 2026-07-30-private-agent-send.md: 43353c309f98eab1bff91b8fbe0c9cfaa2bbc69b
-2026-07-30-private-agent-send.zh.md: 49f7c999ec60c7305bdca570a4d59039c7c1923b
+2026-07-30-private-agent-send.zh.md: 52ead82bb4e39a39e6c578ddb4311d1bae4afe69
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
index 49f7c999ec..52ead82bb4 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付契约公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
+`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付约定公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
 
 公开接口无法在不唤醒驱动器的情况下让一个轮次入队。`followup()` 始终请求执行，`steer()` 请求最近的步骤，`inject()` 则提供面向模型的上下文而不请求执行。本决策部分取代[统一交付决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)中关于公开接口的内容，同时保留其内部路由与统一的 `user/message` 表示。
 
@@ -22,6 +22,6 @@ Status: implemented
 
 ## 后果
 
-插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的契约，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
+插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的约定，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
 
 只有出现明确的消费方并定义显式的生命周期语义后，才能恢复已移除的无唤醒排队能力。`cancel({ keepInbox: true })` 仍会保留已通过受支持交付路径进入待处理状态的工作。
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
index f690cc7a95..1b40493eae 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.md
 2026-07-31-capability-neutral-sandbox-policy-context.md: d45c6c652fb7a061c2f92b7e03c41cce39da2a30
-2026-07-31-capability-neutral-sandbox-policy-context.zh.md: 9a1bb7a13d934826dddf89b409b25ba892a31ea3
+2026-07-31-capability-neutral-sandbox-policy-context.zh.md: c5aa9cc1f03fa83a3b6d9606afc30f6135681ae0
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
index 9a1bb7a13d..c5aa9cc1f0 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 当前策略上下文最初通过受强制执行家族与可升权家族两个独立注册表来映射运行时组合。后端、工具与示例中的六个调用点会贡献 `filesystem`、`bash` 或 `terminal`；策略服务保留 token 集合，以便独立释放各项注册，对两个注册表的内容求交集并排序，在每次生命周期变化时使提示词组装失效，并且需要测试覆盖所有家族组合。
 
-这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期契约。
+这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期约定。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 1c0cc5644d..77f0bb98ae 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
 2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856
-2026-07-31-one-route-to-add-a-workspace.zh.md: 0a59d3a505eb921b4ec980abaefedfcad8a3c294
+2026-07-31-one-route-to-add-a-workspace.zh.md: 9e0940e2a59fac907f023d6433f0056b99c41a60
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 0a59d3a505..9e0940e2a5 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -27,7 +27,7 @@ Status: implemented
 
 ## Wire and CLI residue
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一契约。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
 ## Testing
 
@@ -52,6 +52,6 @@ Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root`
 ## Consequences
 
 - 从 UI 已无法在操作者选定目录之外创建 Workspace；服务端控制的 `--workspace-root` 目标曾是约束新 workspace 文件夹落点的唯一手段，现在没有替代品。需要该约束的部署必须有意识地重新引入它。
-- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的契约，本改动使它成为唯一的契约。
+- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的约定，本改动使它成为唯一的约定。
 - 挂载了 `ui-workspace` 但未挂任何 directory-picker 包的组合，已完全无法添加 Workspace；现在它通过不渲染按钮来说明这一点，而不是提供一个按名称创建的兜底。
-- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让它如实，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 契约上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
+- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让它如实，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 约定上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
index cd43c3a27b..9a88d14722 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
 2026-08-08-remove-cli-demo.md: c1153f5e9fcc89585e926f8f088829c849d1f6c1
-2026-08-08-remove-cli-demo.zh.md: 1f9719b176c05009900a268a5bb2d2d7fcc79df3
+2026-08-08-remove-cli-demo.zh.md: 7f11e0c17a15454b99b32d14ea6eda177f4b01f6
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
index 1f9719b176..7f11e0c17a 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出契约、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
+在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出约定、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
 
-回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性契约。
+回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性约定。
 
 ## 决策
 
@@ -19,7 +19,7 @@ Status: implemented
 ## 考虑过的替代方案
 
 - **保留 `dsh-cli-demo` 作为 `dsh run` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
-- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）契约。
+- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）约定。
 - **随包一并删除规范事件快照。** 不予采纳：这些快照固定了模型可见的组装行为，而只检查最终文本的产品验收无法观察这些行为。
 - **保留应用插件，只删除它的 bin。** 不予采纳：隐藏的组装仍会重复显式的 headless profile，并掩盖测试叶节点挂载了哪些服务。
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index e5e6b3d67e..5dc542589f 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
 2026-06-19-acp-snapshot-tests.md: c6e81dc4a51083ed37ad6f837fe7dbb08c212e23
-2026-06-19-acp-snapshot-tests.zh.md: 5a579c3373442dc4cfc7d661ea2f2f398b804dc7
+2026-06-19-acp-snapshot-tests.zh.md: 729e5645b097f8db5b23594e16e48dc5b4cf211f
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index 5a579c3373..729e5645b0 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 `llm-replay` 短路了提供方无关的 `llm/stream` waterfall（瀑布式事件）。`deriveReplayScript()` 在终止的 `finish` 分片处切分已记录的 `assistant/chunk` 事件，并用 `(turn, step)` 变化拒绝前一条未终止的调用。携带 `llmStreamCall: true` 的 `compact/summary` 会在其持久日志位置贡献一次调用：回放根据 `rawOutput` 重建规范块边界，保留已记录的 usage（如有），并提供终止的 `stop`。该标记将这次本地调用与模板摘要或远程摘要区分开；后两者即使保留了 `rawOutput`，也未使用此上下文的适配器。
 
-### 内存中的回放条目遵守完整的 LLM 契约
+### 内存中的回放条目遵守完整的 LLM 约定
 
 `deriveReplayScript` 产出一组 `ReplayEntry`，即回放监听器按位置服务的内存单元：
 
@@ -52,7 +52,7 @@ Status: implemented
 
 快照运行断言**两个**归一化后的表面，因为 harness 的外部表面是不同的：
 
-1. **stdout transcript**——自动化客户端收到的、分帧后的 ACP JSON-RPC 响应与已提交的消息更新。它捕获传输契约的回归，与已提交的 `stdout.expected.jsonl` 比较。
+1. **stdout transcript**——自动化客户端收到的、分帧后的 ACP JSON-RPC 响应与已提交的消息更新。它捕获传输约定的回归，与已提交的 `stdout.expected.jsonl` 比较。
 2. **重新持久化的会话 JSONL**，经过规范化后与 `session.jsonl` 比较。同一 fixture 同时作为回放来源和预期日志。提示词与工具的主体内容会被清理；每种请求头类别由一个场景固定余下的请求头序列。该 pin 默认拥有可读的提示词与工具 schema 伴随文件；当完整的对应序列相同时，也可将另一个 pin 指定为其中任一来源，因此每个不同的伴随文件版本只提交一次。fixture 保护会拒绝重复的伴随文件内容，录制/刷新会拒绝生成不同字节的共享引用方。最初的请求头固定理由保留在[请求头固定 Agent Note](../../archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)中。Override 场景仅从其伴随文件派生模型行为。
 
 两个表面互补：stdout 覆盖精简的自动化协议格式，JSONL 覆盖协议格式有意省略的 loop、工具和 boundary 结构。
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 5ef82c77de..36c58755cc 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
 2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d
-2026-06-22-fork-child-replay-seed-boundary.zh.md: f64fc55fc63e2caa4b50112407b645e6e7f12b0f
+2026-06-22-fork-child-replay-seed-boundary.zh.md: 9e3f7e59394a5160f5ca5db1c9798b2e05f9d2dc
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index f64fc55fc6..9e3f7e5939 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -46,4 +46,4 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla
 
 - core 与两个后端新增一个持久化 header 字段；子系统目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
 - 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。
-- spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。
+- spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 约定）。
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
index bb1ed0b43b..80395b6359 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
 2026-07-22-cross-platform-test-fixtures.md: 6217aabfdbe8f14f869004c8dafb7e19f4b7443a
-2026-07-22-cross-platform-test-fixtures.zh.md: ce9c65106b904b4c16360c9cb2545b0316bd7120
+2026-07-22-cross-platform-test-fixtures.zh.md: bb6649a19766967e0c2f70272433c1fa2e93f72a
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
index ce9c65106b..bb6649a197 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-测试平台无关行为时，使用宿主的 `node:path` 和 `node:url` API 构造绝对路径与 `file:` URI，再根据契约要求断言原生绝对输出或稳定的工作区相对输出。无效 URI fixture 使用一种在所有受支持平台上都会被 `fileURLToPath()` 拒绝的编码形式。
+测试平台无关行为时，使用宿主的 `node:path` 和 `node:url` API 构造绝对路径与 `file:` URI，再根据约定要求断言原生绝对输出或稳定的工作区相对输出。无效 URI fixture 使用一种在所有受支持平台上都会被 `fileURLToPath()` 拒绝的编码形式。
 
 传输故障测试会注入连接的消息写入器，并传入与真实 Node 流相同的异步写入回调错误。生产写入器仍会把分帧消息写入子进程 stdin。这种方式让真实子进程保持存活，使测试无需触及平台特有的管道句柄，也能确定性地区分传输故障与进程退出。
 
@@ -24,9 +24,9 @@ Status: implemented
 
 **将所有路径和 URI 归一化为 POSIX 字符串。**这会使断言保持一致，但也会改变正确的 Windows 行为：外部路径是原生绝对路径，UNC 文件 URI 有效，而且已配置的主目录会按照宿主路径规则解析。
 
-**操纵子进程管道内部状态，直至写入失败。**CRT 描述符与 libuv 句柄在不同宿主和 Node 版本上的所有权不同，因此这种做法测试的是未文档化的 fixture 机制，而非连接的写入失败契约。
+**操纵子进程管道内部状态，直至写入失败。**CRT 描述符与 libuv 句柄在不同宿主和 Node 版本上的所有权不同，因此这种做法测试的是未文档化的 fixture 机制，而非连接的写入失败约定。
 
-**在 Windows 上跳过整个测试文件或包。**过宽的排除会隐藏受支持的行为。只排除无法在 Windows 上构造相应状态的单项 fixture；相关契约仍保持覆盖。
+**在 Windows 上跳过整个测试文件或包。**过宽的排除会隐藏受支持的行为。只排除无法在 Windows 上构造相应状态的单项 fixture；相关约定仍保持覆盖。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index 5f9a220dc5..b41a72fb3c 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
 2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
-2026-07-24-web-gui-browser-e2e-lane.zh.md: eb20ee378eb5154bafcb7a448202c66dacda9199
+2026-07-24-web-gui-browser-e2e-lane.zh.md: d32837d0e320df0dd53ef49a50092503328d0d73
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index eb20ee378e..d32837d0e3 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -10,7 +10,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 ## 决策
 
-`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品契约包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
+`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品约定包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
 
 ### Scaffold：`apps/web/tests/scaffold.ts`
 
@@ -40,15 +40,15 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 `DSH_SNAPSHOT` 选择 replay（默认，无密钥）、record（带密钥）或 refresh（无密钥）。发起提示的 spec 将所有模式共用的驱动步骤与仅供 replay/refresh 使用的断言分开；record 模式驱动真实输入框，采收内存中的会话 header 与事件，脱敏请求头，并 token 化当次运行的会话、cwd 与 RPC 标识。随后一次无密钥 refresh 重新生成 aria 预期输出。每条提示词都会与 fixture 中录制的 `user/message` 核对；每个场景目录都采用封闭清单，其中每个 JSONL 都是脱敏不动点。Web fixture 全部脱敏请求头且不钉任何 header 类别；见「暂缓」。
 
-### 覆盖契约
+### 覆盖约定
 
-该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动契约，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一契约可以验收虚拟化实现。另一份基于同一 fixture 的交互契约钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史契约从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
+该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动约定，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一约定可以验收虚拟化实现。另一份基于同一 fixture 的交互约定钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史约定从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
 
 ### CI 立场
 
-根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动契约](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
+根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动约定](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
 
-高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两轮执行真实 `bash` 调用并断言其持久化结果，最后一轮则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 轮，每第 10 轮执行一次 `bash` 调用并产生结果，每 10 轮强制执行一次 GC，并报告每 10 轮的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。逐轮诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性契约。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
+高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两轮执行真实 `bash` 调用并断言其持久化结果，最后一轮则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 轮，每第 10 轮执行一次 `bash` 调用并产生结果，每 10 轮强制执行一次 GC，并报告每 10 轮的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。逐轮诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性约定。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
 
 ## 业界先例
 
@@ -64,13 +64,13 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它用谎言满足 `llm-deepseek` 的快速失败密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）是诚实的无密钥，并在最早可解析点快速失败。
 
-**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器契约。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该契约后，再重新考虑。
+**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器约定。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该约定后，再重新考虑。
 
 **第二份提交的规范化会话日志预期输出。** 已否决：日志表面已由 ACP/headless/TUI 套件经同一循环与持久化钉住；在此只会翻倍刷新成本并重复测试下层。内联在根上下文事件上的世界状态断言保住了验证世界的义务。
 
 **以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
 
-**为可测试性改 wire 协议。** 已否决：契约已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
+**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
 **以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
 
@@ -88,7 +88,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 - **恢复后追问场景**：真实 wire 上的历史/实时缝合路径；当该代码变更或回归时作为独立场景补充。
 - **输入框 steering 手势**：输入在运行期间锁定（只能停止或等待），因此 steering 场景从页面走 wire 做 steer；`TODO(web-steer-composer)` 待产品长出真实的输入框手势后，把驱动步骤升级为该手势。
 - **拖拽会话重排**：`workspace.insertSessionBefore` 尚无浏览器场景；它需要在同一个工作区里物化两个会话，并合成 HTML5 拖拽事件。当该表面变更或回归时再补充。无行为的会话 Rename/Fork/Delete 和工作区 Delete 菜单行待获得行为后再补充场景。
-- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互契约不包含这项交接。
+- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互约定不包含这项交接。
 
 ## 后果
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index ea4966f81e..318262eecb 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
 2026-06-16-typed-event-schemas.md: 97a7d0c3787eb5556696e25a6c8b1bb75642aba9
-2026-06-16-typed-event-schemas.zh.md: d0c9ffb3640cb76f0c656e4ac841dc3817bcb86d
+2026-06-16-typed-event-schemas.zh.md: 6d665151a9c5879b3810ae93af8cc6bf5a21727c
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
index d0c9ffb364..6d665151a9 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -8,10 +8,10 @@ Status: proposed
 
 harness 将其核心词汇——内容块、消息来源、结束原因、轮次触发器、轮次结束原因与会话事件——建模为 **merge-extensible map**：一个 TypeScript `interface`（如 `SessionEventMap`、`ContentBlockMap`），插件通过声明合并对其扩展，公开联合类型则以 `Map[keyof Map]` 派生。这是本仓库的通用扩展模式，记录在 [docs/architecture.md](../../../../docs/architecture.md) 中（「The same merge-extensible-map pattern is used for `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`」），`defineTool` 的 `InferArgs` DSL 和 `assertNever` 穷举约定都依赖于它。
 
-该模式**仅存在于编译期**。类型在运行时消失：没有 schema 对象可供校验传入值、解析不可信输入或在运行时枚举变体。[会话持久化契约](../../implemented/architecture/2026-06-14-session-persistence.md)暴露了两个后果：
+该模式**仅存在于编译期**。类型在运行时消失：没有 schema 对象可供校验传入值、解析不可信输入或在运行时枚举变体。[会话持久化约定](../../implemented/architecture/2026-06-14-session-persistence.md)暴露了两个后果：
 
 1. **持久化将 `event.data` 视为不透明 JSON。** JSONL/SQLite 后端对每个事件逐字 `JSON.stringify`/`JSON.parse`；唯一的运行时守卫是 `isJsonValue`（往返可序列化性检查：拒绝 BigInt、函数、循环引用、非有限数等），而非结构校验。一个损坏但仍为合法 JSON 的事件数据（字段类型错误、字段缺失）会静默往返，只有在后续消费方的 `switch` 中才可能被捕获。
-2. **插件新增变体没有运行时契约。** 一个通过声明合并添加新 `SessionEventMap` 键的插件，在自身代码中获得了编译期类型，但没有任何机制校验它产出的值是否符合它所声明的形状——无论是在生产者处、持久化边界处还是重新加载时。
+2. **插件新增变体没有运行时约定。** 一个通过声明合并添加新 `SessionEventMap` 键的插件，在自身代码中获得了编译期类型，但没有任何机制校验它产出的值是否符合它所声明的形状——无论是在生产者处、持久化边界处还是重新加载时。
 
 由此引出问题：事件词汇是否应迁移到 **Zod** 或其他运行时 schema 库，使持久化边界和插件边界拥有运行时 schema 而非被擦除的类型。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
index e6fc787553..7493384e67 100644
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
 2026-07-15-sdk-project-editing-architecture.md: 8335af516dbaa85f4adb85286f976ce9be2c9da8
-2026-07-15-sdk-project-editing-architecture.zh.md: 51f0c5e7f4f033d8149a7ae01aae7a8c4755b76c
+2026-07-15-sdk-project-editing-architecture.zh.md: 4c59ac8cdedf0c7fdd1a2e7994135bc89653d55e
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
index 51f0c5e7f4..4c59ac8cde 100644
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
@@ -37,7 +37,7 @@ SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照
 
 `@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个包名。该例外是仓库架构事实，不增加第三个开发者产品入口。
 
-三个包只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品契约仍由 `dsh-sdk` 命令承担。
+三个包只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品约定仍由 `dsh-sdk` 命令承担。
 
 ## 工程聚合与编辑会话
 
@@ -99,7 +99,7 @@ create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和
 ## 后续工作
 
 - **可替换的 required 主干角色。** 当前 `spine` 以一个固定功能选项拥有整组实现，包含 SystemPrompt、LLMService 等。无法让开发者对其进行替换和切换，只能手工修改 Cordis 配置项。
-- **服务契约与包声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
+- **服务约定与包声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
 - **功能参数描述。** 当前功能的专用输入必须手工声明；SDK 无法从任意 Cordis 插件配置或 NPM package.json 信息中自动推导可交互参数。后续可以定义有限的声明式参数元数据，但不把任意 Cordis 插件配置转换成通用表单。
 - **SDK 应用级配置。** 当前项目资源模型只描述 Cordis 配置项及单个 Cordis 插件拥有的配置键，因此所有受 SDK 管理的配置都必须归属某个插件。跨插件或面向整个 SDK 应用的设置没有独立持久化位置；后续需要定义应用级配置文档及其所有权、读取和修改边界。
 
@@ -109,7 +109,7 @@ create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和
 
 **使用 `wizard.json` 与通用 Questionnaire。** 静态表单无法直接表达功能依赖、选项切换、已有值回填和项目资源变化；类型、门禁和动态选项最终仍要通过字符串注册表与过程式 `run()` 连接，形成新的内部 DSL。
 
-**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布包，只服务仓库开发；公开后会形成无法对外兑现的项目创建契约，因此保持隐藏。
+**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布包，只服务仓库开发；公开后会形成无法对外兑现的项目创建约定，因此保持隐藏。
 
 ## 验收标准
 
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
index e0c0fa0ccd..25b4c76ff7 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
 2026-07-19-required-cancellation-through-tool-capability-seams.md: c2cfb09f27222136965058695e9b6b706ac688a9
-2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 6aa7340d45e99b9072c28c6a1cfe6a769ff8f795
+2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 0544a17629c4fb130bed9ec6c7cae1a15d2211a8
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
index 6aa7340d45..0544a17629 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-已经实现的[工具注册表取消契约](../../implemented/architecture/2026-07-19-cooperative-tool-cancellation.md)让每个工具主体中的 `exec.signal` 成为必填值，但许多由工具主体调用的异步能力接口仍接受可选信号。因此，工具可以满足自身类型，却在下一次同进程调用时意外丢失取消。
+已经实现的[工具注册表取消约定](../../implemented/architecture/2026-07-19-cooperative-tool-cancellation.md)让每个工具主体中的 `exec.signal` 成为必填值，但许多由工具主体调用的异步能力接口仍接受可选信号。因此，工具可以满足自身类型，却在下一次同进程调用时意外丢失取消。
 
 这项缺口会沿调用链传递。文件系统工具可能调用路径解析和 I/O，Web 工具可能调用提供方，Bash 工具可能调用执行器，组合工具可能启动或等待任务、subagent 或工作流。只要某个控制工具所持有工作的、且会被工具等待的操作允许省略信号，TypeScript 就无法证明取消仍能到达拥有副作用的边界。
 
@@ -16,7 +16,7 @@ Status: proposed
 
 所有能从工具主体到达、且在工具仍持有或等待该操作期间执行的异步同进程能力操作，都必须接收 `AbortSignal`。根据所属 seam 的既有形态，这项要求可以表现为位置参数，也可以表现为必填的只读请求字段，但省略信号必须导致 TypeScript 编译失败。
 
-每个直接调用方提供自己持有的信号，或从自身必填的操作上下文继续传递信号。实现可以派生子截止时间或取消作用域，但派生信号在委托期间仍须与上游信号关联。能力实现不得生成永不中止信号、使用环境式异步本地取消，也不得仅为重复类型化同进程契约而在运行时校验 `AbortSignal`。
+每个直接调用方提供自己持有的信号，或从自身必填的操作上下文继续传递信号。实现可以派生子截止时间或取消作用域，但派生信号在委托期间仍须与上游信号关联。能力实现不得生成永不中止信号、使用环境式异步本地取消，也不得仅为重复类型化同进程约定而在运行时校验 `AbortSignal`。
 
 迁移首先从每个第一方 `ToolDefinition.execute()` 出发，清点其等待的能力调用；随后按内聚的接口／实现／消费方 seam，将测试与生成的 API 文档一并修改。文件系统、Bash 与任务、Web 与提供方、工作流与 subagent、代码运行时等能力族可以通过独立 PR（Pull Request）迁移，以保持每项变更可审查；但根据仓库的预发布原则，已经迁移的接口不得保留可选兼容重载。
 
@@ -32,7 +32,7 @@ Status: proposed
 
 **因为工具主体已经收到信号，所以继续让下游信号保持可选。** 不予采纳，因为外层回调中存在信号并不能让传递过程具备类型安全；每个可选能力调用仍可合法省略它。
 
-**通过 lint 规则或回调检查强制传递。** 不予采纳，因为语法检查无法可靠识别所有权、派生信号、抽象层或正确的完全停稳行为。必填接口参数可以在 TypeScript 能检查每个调用方的位置表达契约。
+**通过 lint 规则或回调检查强制传递。** 不予采纳，因为语法检查无法可靠识别所有权、派生信号、抽象层或正确的完全停稳行为。必填接口参数可以在 TypeScript 能检查每个调用方的位置表达约定。
 
 **把 `ToolRunContext` 传入所有能力。** 不予采纳，因为能力需要的是取消，而不是工具身份、agent（智能体）状态或上下文延后功能。传递更大的上下文会让可复用服务耦合到工具注册表，也会掩盖狭窄的 seam。
 
@@ -45,7 +45,7 @@ Status: proposed
 ## 验收标准
 
 - 清单把每个第一方工具主体映射到所有权交接前可以到达的异步能力操作。
-- 每个范围内的能力接口都要求 `AbortSignal`，并由编译期契约测试证明省略信号会失败。
+- 每个范围内的能力接口都要求 `AbortSignal`，并由编译期约定测试证明省略信号会失败。
 - 接口、实现、直接消费方、测试辅助函数、示例和生成的 API 引用必须一起迁移，不保留兼容重载或生产环境永不中止哨兵。
 - 派生截止时间和包装层作用域仍与调用方信号关联，集成测试证明取消到达副作用所有者，且等待的工作完全停稳。
 - 同步查询和明确交接后的分离工作不受这项要求约束；存在歧义时，需要记录并测试所有权转换。
@@ -62,4 +62,4 @@ Status: proposed
 
 **只有机械合规而没有协作行为。** 必填参数只能证明信号可用，不能证明实现会观察或转发它。进程、worker、套接字、提供方和任务边界仍需集成测试证明实际行为。
 
-**把同步或无关 API 纳入范围。** 在不存在异步工作的地方要求取消只会增加噪声，并削弱契约的辨识度。修改前，清单需要记录每项操作为何可由工具到达并承载其生命周期。
+**把同步或无关 API 纳入范围。** 在不存在异步工作的地方要求取消只会增加噪声，并削弱约定的辨识度。修改前，清单需要记录每项操作为何可由工具到达并承载其生命周期。
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 8109eb4854..6b3b6cafb3 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
 2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
-2026-07-24-domain-kv-storage-and-workspace.zh.md: 2904065a7374803495a9bbf8ff4e044310d9bd02
+2026-07-24-domain-kv-storage-and-workspace.zh.md: ea537e0e5e5b02955d0b279d80822b0220f2b20b
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index 2904065a73..ea537e0e5e 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -41,7 +41,7 @@ host 侧唯一的持久化面是 session 事件日志（`packages/session/sessio
 
 一个后端是一个**介质 owner**（一棵文件树 root / 一个 db 文件），通过**数据形状 facet** 暴露原语——本期只有 `kv`；session 迁移期加 `log`（见迁移节）。facet 是可选成员，缺席即该后端不支持该形状，解析时 fail loud。`kv` facet 的原语面：`open(descriptor)`（descriptor = 名字/版本/表名清单/有无 global，名字与表名限 `^[a-z][a-z0-9_]*$` 兼作文件名与 SQL 表名段）返回 unit，unit 提供 `loadAll` / `putRecord` / `deleteRecord`（缺 key 为 no-op）/ `setGlobal` / `close`（幂等）；值对后端是不透明 JSON。规范正文（含逐方法 JSDoc）在 `packages/storage/storage/src/backend.ts`。
 
-后端契约（共享契约测试逐条断言，两后端同套件）：
+后端约定（共享约定测试逐条断言，两后端同套件）：
 
 1. `open` 对不存在的介质创建（懒物化允许：可延迟到首写，但 `loadAll` 立即可用返回空表）；对已存在介质载入。
 2. 介质上版本 ≠ descriptor.version → `StorageError('version-mismatch')`，不迁移不重建。
@@ -256,7 +256,7 @@ export class WorkspaceRegistry extends Service {
 
 ### 复用与 session 后端迁移展望
 
-**长期方向**：session-persistence 的 JSONL/SQLite 后端里"纯介质操作"下沉到 `dsh-storage` 后端（session 包不删，`SessionPersistence` seam 与 coordinator 语义不动；动的只是它们脚下的文件/db 操作层）。复用的动机：介质层全是文件系统操作、数据库调用与跨平台兼容的脏活（Windows 权限与原子发布变体、fsync 语义、独占建文件……），这些只应写一遍；业务语义（session 怎么 append、何时 append、append 什么）留在上层——而"底下这次 append 是否正常完成"（持久性/原子性/平台正确性）是底层的责任，责任界面就是 facet 原语的契约。为此后端接口按**介质 owner + 数据形状 facet** 设计：session 日志是仅追加流，与 KV 形状不同——强行统一进 KV 原语会两头变形，所以按 facet 分开（`kv` 本期、`log` 迁移期），介质与生命周期共享。
+**长期方向**：session-persistence 的 JSONL/SQLite 后端里"纯介质操作"下沉到 `dsh-storage` 后端（session 包不删，`SessionPersistence` seam 与 coordinator 语义不动；动的只是它们脚下的文件/db 操作层）。复用的动机：介质层全是文件系统操作、数据库调用与跨平台兼容的脏活（Windows 权限与原子发布变体、fsync 语义、独占建文件……），这些只应写一遍；业务语义（session 怎么 append、何时 append、append 什么）留在上层——而"底下这次 append 是否正常完成"（持久性/原子性/平台正确性）是底层的责任，责任界面就是 facet 原语的约定。为此后端接口按**介质 owner + 数据形状 facet** 设计：session 日志是仅追加流，与 KV 形状不同——强行统一进 KV 原语会两头变形，所以按 facet 分开（`kv` 本期、`log` 迁移期），介质与生命周期共享。
 
 现状复用审计（迁移前就能看清的账）：
 
@@ -275,11 +275,11 @@ export class WorkspaceRegistry extends Service {
 
 | 套件 | 覆盖 | 后端 |
 | --- | --- | --- |
-| 后端契约（共享套件，一次编写两端跑） | 七条契约 + 版本拒绝 + close 幂等 | json、sqlite（`:memory:` + 临时目录） |
+| 后端约定（共享套件，一次编写两端跑） | 七条约定 + 版本拒绝 + close 幂等 | json、sqlite（`:memory:` + 临时目录） |
 | 注册表/mount | 重复注册、未挂载访问、disposer 摘除 | — |
 | domain 层 | open 六步语义、schema 拒绝、update 串行（并发交错压测）、`domain/changed` 逐条、global 初值懒物化、路由与 `facet-unsupported` | 任一（json） |
 | workspace | create/唯一性/realpath、attach 校验（含 sessionPersistence 缺席拒绝）、一致性口径四情形 | mock domain 或 json |
-| session delete 契约（future work，随实施并入 runPersistenceContract） | 未知 id、已删 id 复用、未物化 intent、与在途 append 串行、deleted 事件 | jsonl、sqlite |
+| session delete 约定（future work，随实施并入 runPersistenceContract） | 未知 id、已删 id 复用、未物化 intent、与在途 append 串行、deleted 事件 | jsonl、sqlite |
 
 快照：本期无模型可见面与组装面，不新增；下期 RPC 接线时随 `workspace.*` 域补。
 
@@ -318,7 +318,7 @@ export class WorkspaceRegistry extends Service {
 
 ## 验收标准
 
-- 测试矩阵本期四套件全绿：后端契约共享套件在 json/sqlite 双端、注册表/mount disposer 语义、domain 层（含 open 六步与路由 fail-loud）、workspace 全语义（create/attach 校验/一致性口径）。
+- 测试矩阵本期四套件全绿：后端约定共享套件在 json/sqlite 双端、注册表/mount disposer 语义、domain 层（含 open 六步与路由 fail-loud）、workspace 全语义（create/attach 校验/一致性口径）。
 - `ctx.workspace` 可在测试组装下完成 create → attach → list → 仅删除元数据的 delete 生命周期。
 - session-persistence 包零 diff（本期不动 session 侧的验收线）。
 - 本期无新快照（无模型可见面与组装面）；下期 RPC 接线时补。
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
index c0bccacb78..1bf84824b2 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
 2026-07-25-client-settings-locale-theme.md: fdcdcff92fa324803d5f2343f3fc3d9dcca069c7
-2026-07-25-client-settings-locale-theme.zh.md: 9cf973aee29cc1072c2fdaf1ce67e0b8395f1d90
+2026-07-25-client-settings-locale-theme.zh.md: efcbbff3727a7a5ce14ba7273c7d0e826a3e5cbd
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
index 9cf973aee2..efcbbff372 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-浏览器端已有的 Settings 直接写在 Sidebar 内，语言和主题也由组件本地状态直接改 DOM。这使 Settings 无法由独立插件扩展，偏好状态没有稳定的跨插件服务契约，主题注册表同时承担状态与呈现职责。
+浏览器端已有的 Settings 直接写在 Sidebar 内，语言和主题也由组件本地状态直接改 DOM。这使 Settings 无法由独立插件扩展，偏好状态没有稳定的跨插件服务约定，主题注册表同时承担状态与呈现职责。
 
 ## 提案
 
@@ -61,7 +61,7 @@ section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifes
 
 `SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明撤销与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会显式报错。这移除了陈旧 disposer 的在位判定机制和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
-### 服务契约
+### 服务约定
 
 ```ts
 export type ThemePreference = 'light' | 'dark' | 'system'
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index d4aa713b5c..ce7e7f5f4f 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
 2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
-2026-07-27-session-projection-and-command-log.zh.md: 0cc82d1aa65dc2b99882875d655ddbe17073354a
+2026-07-27-session-projection-and-command-log.zh.md: ef4de5ea924e28c28896558206566639295c4c8e
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index 0cc82d1aa6..ef4de5ea92 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -26,7 +26,7 @@ Status: proposed
 
 一个轻量的接口包：merge-extensible 类型表、注册表服务、边界上的 zod 校验。能力 seam 三方拆分：领域 host 插件负责贡献，载体负责消费，两侧互不相识。
 
-领域注册的是一个**状态驱动计算单元（state-driven computation unit）**——三个纯函数外加若干声明——绝不是一个不透明的 getter。驱动它是框架的职责（订阅、水位线（watermark）、缓存，以及后续的检查点机制），领域只负责数学本身。投影服务于所有业务领域（会话标题、plan、goal、权限、todos）；命令只是其中一条触发路径，在本契约中没有任何特殊地位。
+领域注册的是一个**状态驱动计算单元（state-driven computation unit）**——三个纯函数外加若干声明——绝不是一个不透明的 getter。驱动它是框架的职责（订阅、水位线（watermark）、缓存，以及后续的检查点机制），领域只负责数学本身。投影服务于所有业务领域（会话标题、plan、goal、权限、todos）；命令只是其中一条触发路径，在本约定中没有任何特殊地位。
 
 ```ts ignore-check
 export interface SessionProjectionMap {}   // the single type table for the whole chain
@@ -112,7 +112,7 @@ type UseProjection = {
 
 `undefined` 统一表示能力缺失（host 插件未挂载，或尚无任何基线/帧携带过该 key）。值仓只暴露按 key 的裸 `{subscribe, getSnapshot}` 面；其余交给带逐 key 缓存的 `bindSnapshotSelector`——引用稳定性成立，因为一个 key 的值引用只在帧或基线落地时才变化。写路径不变：变更回调留在 inject 共享面（回调出自 inject，活状态出自 `useProjection`）。
 
-「钩子不得穿过 inject」的唯一既有违例——`DetailsInjected.useSelection`——随本变更一并收编：选中态是住在聊天 store 里的查看状态，因此 details 注册声明共享 store 句柄，组件改读 `props.useStore(s => s.selection)`；`useSelection` 退出 inject 契约。
+「钩子不得穿过 inject」的唯一既有违例——`DetailsInjected.useSelection`——随本变更一并收编：选中态是住在聊天 store 里的查看状态，因此 details 注册声明共享 store 句柄，组件改读 `props.useStore(s => s.selection)`；`useSelection` 退出 inject 约定。
 
 ### 日志中的命令生命周期
 
@@ -133,7 +133,7 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 基础设施先行；三个在途 PR（Pull Request）原样不动，待基座落地后重新对接（它们的迁移映射即指南）：
 
-1. **host 基座**：`dsh-session-projection`（单元契约、主动驱动、水位线缓存）+ api-proxy 的 projections 块 + `session/projection` 推送帧。零领域注册也可合入（此时块与帧直接缺席）。
+1. **host 基座**：`dsh-session-projection`（单元约定、主动驱动、水位线缓存）+ api-proxy 的 projections 块 + `session/projection` 推送帧。零领域注册也可合入（此时块与帧直接缺席）。
 2. **客户端基座**：通用值仓 + `useProjection` 席位；下线按领域的 cell 机制，并在标题单元注册后一并下线 `session/title` 帧与标题快照表。帧的形状依赖 1（在此之前 fixture（测试前置数据）喂合成帧）。
 3. **命令通道**：两个事件、执行器落日志、通用节点 + keyed slot、通知通道下线、`{matched, commandId?}` 准入。与 1 并行。
 4. **领域重新对接**（在 1+2 之后）：先 todo（单元进 `tool-todo`，删掉搭载字段），再 plan（双事件单元、RPC 下线、开关改发 `/plan`），最后 goal（`goal/change` 单元，删掉 `goals.get`，把六个 `Session` 方法移入领域插件的 inject）。
@@ -143,11 +143,11 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 **专设一个 `session.projections` RPC**——不予采纳：基线刷新时刻与尾页拉取精确重合，单独的一元 RPC 只会换来第二次往返、第二个待调和的 seq，以及一个客户端「何时重取」决策——而搭载设计把这个决策整个删掉了。
 
-**不透明的 `get(agent)` 提供方契约**——曾是第一稿，后被否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
+**不透明的 `get(agent)` 提供方约定**——曾是第一稿，后被否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
 
-**为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影契约保持恰好三个纯函数。
+**为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影约定保持恰好三个纯函数。
 
-**把 seam 命名为 `registerFold`**——已被单元契约取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该 seam 注册的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
+**把 seam 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该 seam 注册的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
 
 **客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——曾是第二稿，后被否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
 
@@ -173,15 +173,15 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 - 历史尾页携带 `projections`，其 `asOfSeq` 等于窗口尾部 seq；loadOlder 页永不携带；未装注册表的部署照常返回不带该块的历史，客户端把所有 key 视为缺席。
 - 陈旧的基线不能覆盖更新的 `session/projection` 帧，重放的帧也不能让值仓倒退（两条路径都做 seq 高者胜测试）。
 - 在一个标签页执行的斜杠命令，刷新后、在第二个标签页上、恢复之后都在 flow 中渲染出持久节点；未注册的命令渲染通用卡片；命令结果的 composer 通知路径彻底移除。
-- `useProjection` 经标准 props 套件抵达组件；没有任何钩子穿过 inject 契约（包括 `useSelection`）。
+- `useProjection` 经标准 props 套件抵达组件；没有任何钩子穿过 inject 约定（包括 `useSelection`）。
 - 会话标题搭乘这对通用机制（基线块 + 投影帧）；专设的 `session/title` 帧与客户端标题快照表彻底移除。
 
 ## 风险
 
-- **全量值规则是承重结构**：未来某个领域若只记裸增量，就无法凭其最新事件服务消费方，还会让自己的单元复杂化。缓解：该规则写明在本 Note 与投影包的 README 里；单元契约让完整状态在每次转移处都是显式的。
+- **全量值规则是承重结构**：未来某个领域若只记裸增量，就无法凭其最新事件服务消费方，还会让自己的单元复杂化。缓解：该规则写明在本 Note 与投影包的 README 里；单元约定让完整状态在每次转移处都是显式的。
 - **单元的同步纪律**：`init`/`apply`/`view` 一旦 await 就会撕裂一致性切面。注册表在文档中申明这条纪律，invariant 配套在可行范围内断言同步性；其余由评审把关。
-- **注册表的实时增删不做推送**：会话中途加载或卸载领域插件会改变键集，但不会触发任何会话事件、也不会推任何帧；开着的客户端持有陈旧的 key 直到下次尾页拉取（重连、缺口修补、打开）。接受为仅开发期（HMR）的陈旧时窗——日后可以在变更流上加一个注册表变更推送，契约不受影响。
-- **忙碌会话上的主动驱动开销**：每个已提交事件都要过每个已注册单元的 `apply`。按构造，单元的逐事件开销很低（全量值规则），不匹配的事件返回同一引用，且已注册领域的数量很小；若真出现热点路径，可以加按单元的事件类型预过滤，契约不变。
+- **注册表的实时增删不做推送**：会话中途加载或卸载领域插件会改变键集，但不会触发任何会话事件、也不会推任何帧；开着的客户端持有陈旧的 key 直到下次尾页拉取（重连、缺口修补、打开）。接受为仅开发期（HMR）的陈旧时窗——日后可以在变更流上加一个注册表变更推送，约定不受影响。
+- **忙碌会话上的主动驱动开销**：每个已提交事件都要过每个已注册单元的 `apply`。按构造，单元的逐事件开销很低（全量值规则），不匹配的事件返回同一引用，且已注册领域的数量很小；若真出现热点路径，可以加按单元的事件类型预过滤，约定不变。
 - **投影载荷膨胀**：每个尾页携带每个已注册的 key。载荷是 UI 量级状态的全量值（一张 todo 清单、一份 goal 快照）；将来若某领域的值很大，可以在请求上加逐 key 的 opt-out 或惰性 key，模型本身不用改。
 - **命令日志体量**：每条斜杠命令两个仅日志事件；上限由人敲命令的频率决定，相对分片体量可忽略不计。
 - **重新对接的返工**：三个未合入的 PR 要变基到挪动后的地基上。这是基础设施先行的既定代价；设计台账中的迁移映射一节逐一列出每个 PR 的保留/删除清单。
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
index 040d099f38..2da4662891 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
 2026-07-28-storage-root-and-derived-medium-recovery.md: c7b423770fcca89c54d3866db7701348351cc259
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 54a2bbc6496bd8cce594b3ce3a105e4be6e8ff64
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: e271373662e4decfd0663133fd811ee1b9247507
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
index 54a2bbc649..e271373662 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
@@ -56,4 +56,4 @@ Status: proposed
 
 - **错误分类失误导致自动删除健康文件。** 由封闭的损坏类清单缓解：重置只在三个确定性解析期代码上触发；ENOENT 本来就是「空 unit」，一切 I/O 错误（EACCES、EIO）大声传播。单发重试把爆炸半径限定为每次 open 至多一删。
 - **根迁移改变既有 checkout 的查找位置。** 在 pre-release 立场下接受（后端拒绝旧格式、无外部消费方）；上文为在乎 per-cwd `workspace.json` 内容的人记录了一次性手动搬移。
-- **`destroy` 是存储 seam 上新增的破坏性原语。** 唯一调用方是 facility 的声明重置路径；后端契约将其记档为 facility 专属，任何面向模型或面向用户的路径都触不到它。
+- **`destroy` 是存储 seam 上新增的破坏性原语。** 唯一调用方是 facility 的声明重置路径；后端约定将其记档为 facility 专属，任何面向模型或面向用户的路径都触不到它。
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
index e4acea8bc5..af319b51a7 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
 2026-07-29-durable-last-activity-index.md: 0e441f54a719b29a1a450c133e08cdf7d2c82e9e
-2026-07-29-durable-last-activity-index.zh.md: 9557da0a186084499dfb0f3e8d36016d5b216ae7
+2026-07-29-durable-last-activity-index.zh.md: ebc2e2167d7743eafc5a4600fe9a0f687349e1a3
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
index 9557da0a18..ebc2e2167d 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
@@ -16,7 +16,7 @@ mtime 回答的是另一个问题：这份产物上次是什么时候被写入
 
 ## 提案
 
-把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每 id 状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 契约中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
+把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每 id 状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 约定中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
 
 两个已交付的后端受到的约束正好相反，本提案对它们有意采取不对称的处理：
 
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
index c70cbb870b..80ae253198 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
 2026-08-08-semantic-composer-chain-phases.md: 7d85518e9d5e5aa3e44e443cb1b90b325b0ffc6a
-2026-08-08-semantic-composer-chain-phases.zh.md: a202b9bfeb9276cdccaa7b438036cd1236a33317
+2026-08-08-semantic-composer-chain-phases.zh.md: c0c0bca32ffcc174929c3cbef4878138e1268e98
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
index a202b9bfeb..c0c0bca32f 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 
 阶段词汇归声明该 slot 的领域所有，而不属于全局 slot 框架。`SlotMap` 携带确切的阶段元组，用于编译期注册；运行时 `SlotSpec` 重复该元组，作为排序依据。其他链不会获得任何 composer 术语，也无需迁移，除非它们主动声明阶段。
 
-本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)契约，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
+本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)约定，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
 
 ## 备选方案
 
@@ -36,7 +36,7 @@ Status: proposed
 - Composer 测试覆盖问题加只读项、审批加只读项、问题加审批加只读项、解决后回到只读项，以及所有选择器均拒绝匹配时回退到 InputBar。问题在 `interaction` 内仍排在审批之前。
 - dispose（资源释放）、HMR（热模块替换）重新注册和重新连接回放均不能留下陈旧的当选阶段；选举仍是当前所有者 props 与当前注册项的纯函数。
 - 一项无密钥组装 Web 快照固定已寻址的 one-shot 对话及其待处理交互：交互界面胜出，解决该交互后，只读界面再次出现。
-- slot、conversation、question、permission 和 subagent 的 README／JSDoc 契约共同描述阶段所有权以及交互先于限制的规则。
+- slot、conversation、question、permission 和 subagent 的 README／JSDoc 约定共同描述阶段所有权以及交互先于限制的规则。
 - 该变更不修改任何模型可见的工具定义、系统提示词章节、请求路由或会话事件。因此，浏览器选举既不产生 token 开销，也不会使 KV Cache 失效；测试会比较仅在客户端发生状态转换前后的模型请求 header。
 
 ## 风险
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index e6fe2edcf1..ad963d6e81 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
 2026-07-06-recallable-compaction.md: ed5491e642ea7ac99fd9f4ba071a61e655f968d3
-2026-07-06-recallable-compaction.zh.md: ad3cba250973a8c8d9545a31b312cd4d3f23725f
+2026-07-06-recallable-compaction.zh.md: dabc606d0056e91f9ac473de6f166083bcee25e8
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index ad3cba2509..dabc606d00 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -107,4 +107,4 @@ Status: proposed
 - **存根目录会占用注意力**：每次请求中包含数十张稳定的索引卡，可能稀释模型关注点；验收标准中的 bench 度量会将其与 `compact-basic` 对比。
 - **成本**：每轮摘要输入大约是当前实现的两倍；短会话的成本和质量接近当前水平，而设计收益随会话长度增长。
 - **状态漂移与职责分工泄漏** 可以通过交接探针和存根评审观察；对应措施已列为后续事项。
-- **两个后端** 会扩大维护范围；seam 契约和共享回溯消费方会限制这一范围，bench 对比则用于逐步决定默认实现。
+- **两个后端** 会扩大维护范围；seam 约定和共享回溯消费方会限制这一范围，bench 对比则用于逐步决定默认实现。
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
index 8e61990639..be85390433 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
 2026-07-14-sdk-developer-projects.md: 65d2bf66232993222832eb0f2f4f56cfcf7afd16
-2026-07-14-sdk-developer-projects.zh.md: 07bf898a7ef672a21951afaa9038a86878ae2900
+2026-07-14-sdk-developer-projects.zh.md: fc96d25dbea44d28bbc146b76fc3e81093bec976
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
index 07bf898a7e..fc96d25dbe 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
@@ -129,7 +129,7 @@ Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约
 ## 后续工作
 
 - `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定包或仓库来源时创建本地插件/工具，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
-- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入契约
+- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入约定
 - 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
 
 ## 曾考虑的替代方案
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
index fab3ecc2b1..f5a16fae7e 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
 2026-07-17-sdk-follow-up-capabilities.md: 88d5d2f9bd1ce01c20177bcaee5bbe6b434bb978
-2026-07-17-sdk-follow-up-capabilities.zh.md: 998b7ec3cfddafe40537908fb61aa6d7e6f90418
+2026-07-17-sdk-follow-up-capabilities.zh.md: d54dc4d0635ef37d7196ff5cecbdd6ed093c98e3
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
index 998b7ec3cf..d54dc4d063 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 首个 SDK 版本通过[开发者工程 Agent Note](2026-07-14-sdk-developer-projects.md) 和 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md)定义的共享模型创建和编辑开发者拥有的 Cordis 工程。create 和 config 工作流仅支持交互调用，接入外部 Cordis 插件需要手工修改依赖和配置，命令行遥测没有明确的所属边界，交互分支也缺少稳定的测试策略。
 
-这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品契约。
+这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品约定。
 
 ## 提案
 
@@ -33,7 +33,7 @@ Create 和 config 使用相同的功能计划形状。create 通过上述命令
 
 ### Prompt 与工程编辑边界
 
-`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题契约公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
+`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题约定公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
 
 两条路径使用相同的 `Question` 对象、`FeatureConfigurator`、`SdkProject` 和 `ProjectEditSession`。因此，headless 路径只改变答案的到达方式，不改变功能解释或文件提交方式。
 
@@ -97,12 +97,12 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
 ## 验收标准
 
 - Create 能依据完整结构化输入在没有 TTY 时运行；使用 `--json` 时 stdout 只输出 NDJSON；缺少必答输入时通过 `action-required` 报告，且不写入部分工程。
-- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划契约。
+- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划约定。
 - `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时快速失败。
 - 初始化命令与每个 `dsh-sdk` 命令都进入同一条尽力而为的遥测收尾路径；明确禁用的配置项、`DO_NOT_TRACK` 或 CI 会阻止传输，遥测失败绝不改变命令结果。
 - 遥测绝不读取 `.env`；没有 `cordis.yml` 时不发送无关的 `package.json` 内容；两个符合条件的文本都经过脱敏；匿名标识符与 git 元数据无关。
 - 交互测试通过注入交互覆盖 create 和 config 决策，并断言已提交的工程文件；真实 PTY 覆盖只作为窄范围冒烟层。
-- Agent skill 说明公开的结构化输入与事件契约，不依赖包的私有导出。
+- Agent skill 说明公开的结构化输入与事件约定，不依赖包的私有导出。
 
 ## 风险
 
@@ -110,7 +110,7 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
 - 没有遥测配置项时默认上报可能让开发者意外；发布前 CLI 必须让关闭方法易于发现。
 - 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败会留下需要手工恢复的依赖改动。
 - GitHub 依赖可能按包管理器策略执行 preparation 或 lifecycle script；尚未解决的构建策略会带来供应链与可复现性风险。
-- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余契约。
+- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余约定。
 
 ## 参考资料
 
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
index 7dc26f8fb7..6dbffc67e2 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-08-04-task-surface.md
 2026-08-04-task-surface.md: 72fc9e12f1a02f66a02d3335ad2e8d0d4c1c3dc2
-2026-08-04-task-surface.zh.md: 087c80195f75e145da93c5557afb43a421e1050d
+2026-08-04-task-surface.zh.md: 32de8167affd48472469083a580e1dd3f98a3c24
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
index 087c80195f..32de8167af 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -10,7 +10,7 @@ Status: proposed
 
 这两种变通方案的职责归属都不合理。产品专用组件要求每种任务形态都新增触发方式并发布新版本。对于只需一个轮次的表单，生成代码所拥有的权限和生命周期成本都远超实际需要。这样做还会把展示界面而非用户结论变成持久产物。
 
-目前缺少这样一份契约：用有界、可回放的描述来定义临时 UI，并让它只属于一个会话和一次工具调用实例。产品应当负责校验、放置、交互机制和提交；agent 应当负责特定任务的文案、数据，以及从受支持组件中作出选择。
+目前缺少这样一份约定：用有界、可回放的描述来定义临时 UI，并让它只属于一个会话和一次工具调用实例。产品应当负责校验、放置、交互机制和提交；agent 应当负责特定任务的文案、数据，以及从受支持组件中作出选择。
 
 ## 提案
 
@@ -77,13 +77,13 @@ interface TaskSurfaceOption { id: string; label: string; detail?: string }
 
 Task Surface 服务通过受 schema 校验的配置定义限制。初始默认值为：规范化模型不超过 64 KiB、块不超过 64 个、字段不超过 32 个、表格行不超过 200 行、提交内容不超过 32 KiB。模型内的 ID 必须唯一；字段值必须符合其声明；未知字段会被拒绝。这些限制约束日志、DOM 和提示词成本，但不改变协议。
 
-## 工具与呈现契约
+## 工具与呈现约定
 
 `show_task_surface` 接收 `{ model: TaskSurfaceModelV1 }`。Host 解析并规范化完整模型；若该会话已有一个打开的 Task Surface，则拒绝调用；否则生成 `surfaceId`，并返回带规范化模型的规范值 `{ surfaceId, model }`。`presentationMeta` 持久化 `value.model`，使投影器和执行器不会对规范化结果产生分歧。Native 结果会指明该 Surface，并说明客户端无法渲染面板时，可以通过普通消息绕过它。随后工具调用 `exec.concludeTurn()`，防止 agent 越过所要求的人工检查点继续执行。
 
-工具定义省略 `isConcurrencySafe`。根据现有工具注册表契约，省略该字段会将每次调用归类为独占排序屏障，无需新增 `ToolDefinition` 字段。该工具只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
+工具定义省略 `isConcurrencySafe`。根据现有工具注册表约定，省略该字段会将每次调用归类为独占排序屏障，无需新增 `ToolDefinition` 字段。该工具只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
 
-浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
+浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出约定](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -102,13 +102,13 @@ interface TaskSurfacePresentationMeta {
 
 该工具保留通用 [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)。带 key 的 Web 行读取 `ToolResultNode` 上已经保留的带标签元数据，无需新增 render-intent 分支或呈现注册表。不支持 Task Surface 的客户端会渲染普通结果内容。
 
-Web 插件按照 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，提供两个静态的会话作用域注册项。一个以 `show_task_surface` 为 key 的 `conversation.chat.toolview` 条目将持久 transcript（文本记录）调用实例渲染为简洁摘要和只读回放。现有 `conversation.input.dock` 中的一个 `TaskSurfaceDock` 条目是唯一可操作的挂载点：它读取活动投影，针对确切身份调用 `getActive`，并拥有字段、草稿、提交和关闭操作。Dock 与 transcript 分页相互独立，因此即使 `ToolResultNode` 位于已加载历史窗口之外，活动 Surface 仍可操作。
+Web 插件按照 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)约定，提供两个静态的会话作用域注册项。一个以 `show_task_surface` 为 key 的 `conversation.chat.toolview` 条目将持久 transcript（文本记录）调用实例渲染为简洁摘要和只读回放。现有 `conversation.input.dock` 中的一个 `TaskSurfaceDock` 条目是唯一可操作的挂载点：它读取活动投影，针对确切身份调用 `getActive`，并拥有字段、草稿、提交和关闭操作。Dock 与 transcript 分页相互独立，因此即使 `ToolResultNode` 位于已加载历史窗口之外，活动 Surface 仍可操作。
 
 Dock 遵循现有 composer chain 的回退语义。任何 `conversation.composer` 接管都会隐藏包括 `TaskSurfaceDock` 在内的回退 composer 栈，但不会将其卸载；接管结束后，同一个草稿所有者会重新出现。接管方不会获得 Task Surface 操作，也不会创建另一个编辑器。
 
 模型不能选择会话标签页、Dock 顺序、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。transcript 行绝不会成为第二个编辑器，因此同一个 Surface 不会出现相互竞争的草稿或提交所有者。
 
-## 提交契约
+## 提交约定
 
 Task Surface 领域通过 Host 传输层公开三个操作。只有 `submit` 会接纳用户消息：
 
@@ -227,14 +227,14 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 | 包 | 职责 |
 |---|---|
 | `packages/core/agent` 和 `packages/core/agent-loop` | 为已认领的下一轮 inbox 调用实例提供通用终态结果，让 Host 观察方无需使用 Task Surface 专用类型，即可区分持久接纳和丢弃 |
-| `packages/task-surface/task-surface` | 浏览器安全的模型、带品牌类型的 ID、关联和待处理类型、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
+| `packages/task-surface/task-surface` | 浏览器安全的模型、带品牌类型的 ID、关联和待处理类型、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务约定 |
 | `packages/task-surface/tool-task-surface` | `show_task_surface`、规范输出、呈现元数据、通用 render intent、活动 Surface 检查和 `concludeTurn()` 行为 |
 | `packages/client/runtime` | 通用排队消息 `source` 投影和会话作用域的活动投影访问 |
 | `packages/client/ui-primitives` | 与 Task Surface 无关的 `MarkdownText.remoteImages` 策略，包括 `alt-only` 图片分支和 URL 策略测试 |
 | `packages/client/ui-task-surface` | 静态且可操作的 `TaskSurfaceDock`、带 key 的只读 transcript 行、消费 Task Surface 模型并以 `alt-only` 模式使用 `MarkdownText` 的声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
 | `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展与传递、队列操作限制，以及认领和终态结果的路由；将校验、待处理协调和接纳委托给 Task Surface 服务 |
 
-`ui-task-surface` 依赖浏览器安全的 Task Surface 领域包、客户端连接与运行时、locale、`ui-conversation` 所声明的 slot 契约、用于注册的 `ui-slots`，以及 `ui-primitives`；`ui-primitives` 不反向依赖 Task Surface。ApiProxy 依赖 Task Surface 服务契约和通用 AgentLoop 终态结果。核心 Agent 包不导入 Task Surface 类型。
+`ui-task-surface` 依赖浏览器安全的 Task Surface 领域包、客户端连接与运行时、locale、`ui-conversation` 所声明的 slot 约定、用于注册的 `ui-slots`，以及 `ui-primitives`；`ui-primitives` 不反向依赖 Task Surface。ApiProxy 依赖 Task Surface 服务约定和通用 AgentLoop 终态结果。核心 Agent 包不导入 Task Surface 类型。
 
 该实现依赖现有的消息日志、规范工具输出、带标签的 render intent、会话投影、按会话作用域声明的 slot store 和 slot 生命周期，不依赖在运行时创建客户端插件。Generated Client Plugin 工作流可以使用 Task Surface 展示审阅表单，但两个协议都不拥有或激活另一个协议。
 
@@ -250,7 +250,7 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 
 **从工具调用中渲染任意 HTML、CSS 或 JavaScript。**不予采用，因为这会把临时交互变成可执行的客户端插件代码，却不具备代码所需的构建、预览、评估、批准或回滚生命周期。
 
-**使用大型表单扩展 `userInteraction.ask()`。**本契约不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
+**使用大型表单扩展 `userInteraction.ask()`。**本约定不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
 
 **每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。一个静态的会话作用域 Dock 负责交互，一个静态带 key 的行概述已记录的调用实例；两个注册项都不使用调用实例身份。
 
diff --git a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
index f301aae614..d0c2fe4c0c 100644
--- a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-06-11-architectural-conformance.md
 2026-06-11-architectural-conformance.md: f7cb0d7397d4e03df225f68417da43b1fec8de62
-2026-06-11-architectural-conformance.zh.md: c82297fcbe02feed4cd04bc60730a3494b7faa4d
+2026-06-11-architectural-conformance.zh.md: 16692f765ceaeca585e6563f7dd864ac524adb77
diff --git a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
index c82297fcbe..16692f765c 100644
--- a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 - `vendor/*` 禁止从 `packages/*` 导入。
 - 分层：dsh-llm 不导入其他 dsh 包；dsh-session 仅导入 dsh-llm；以此类推（packages/README.md 中的依赖表，强制执行）。
 
-**适配器一致性套件**位于 dsh-llm（`@deepseek-ai/dsh-llm/conformance`）：一个以适配器工厂为参数的可复用 vitest 套件，用于断言分片协议契约，包括每个块内的索引单调递增、某个索引出现 `block-end` 后不再接收增量、恰好出现一个 `finish`、用量至多出现一次、每个 `tool-call-delta` 都携带调用 id，并且及时响应 abort。当前先对 mock 运行；DeepSeek V4 适配器从第一天起继承该套件。还可以选择提供开发模式下的 `strictAdapter()` 包装层，在调试标志开启时于运行时强制执行相同规则（与 [开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md) 配对）。
+**适配器一致性套件**位于 dsh-llm（`@deepseek-ai/dsh-llm/conformance`）：一个以适配器工厂为参数的可复用 vitest 套件，用于断言分片协议约定，包括每个块内的索引单调递增、某个索引出现 `block-end` 后不再接收增量、恰好出现一个 `finish`、用量至多出现一次、每个 `tool-call-delta` 都携带调用 id，并且及时响应 abort。当前先对 mock 运行；DeepSeek V4 适配器从第一天起继承该套件。还可以选择提供开发模式下的 `strictAdapter()` 包装层，在调试标志开启时于运行时强制执行相同规则（与 [开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md) 配对）。
 
 ## 计划
 
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
index e23ab9913b..5dd07029b3 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
 2026-07-13-human-review-skill-maintenance.md: 76391bd110b7a86b194a9340ffcf7cc4602d1d2e
-2026-07-13-human-review-skill-maintenance.zh.md: e442a39618a53ffdc130c94874a482315943caff
+2026-07-13-human-review-skill-maintenance.zh.md: 8ebff759cf29fa7773e4b883f83c231f88e153d2
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
index e442a39618..8ebff759cf 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
@@ -28,9 +28,9 @@ flowchart TD
   K --> L["Leave a reviewed local working-tree diff"]
 ```
 
-### 采集契约
+### 采集约定
 
-每个选定的 PR 都会在获取任何反馈前接受过滤：其 merge commit 必须是 `origin/master` 的祖先。merge commit 可达性是唯一的资格检查：直接 base 为功能分支的堆叠 PR，只要该 base 随后已经进入 master，就会被纳入，因为无论中间 stack 如何，评审人评论的代码此时已经在 master 上。工具还会解析落地 merge 的目标父级；无法重建的落地形态会记录到 `skipped-pulls.json` 并跳过。单个 PR 在预检、采集或证据收集时失败，只会被跳过，不会中止整次运行。如果时间窗口会超过 GitHub 搜索的 1,000 条结果上限，搜索阶段会明确失败，避免无提示地遗漏已合并 PR。采集阶段会完整读取内联评审评论、评审提交和 PR commit 的分页连接。不采集 PR 对话评论，因为强制推送后，GitHub 当前状态无法证明哪个仍然存在的 commit 位于评论之前，采纳契约因此必然会无条件排除这些评论。只有当 GitHub 报告 actor `type` 为 `User`，并且创建时间与最后编辑时间都严格早于 PR 合并时，工作流才接受已采集反馈；与合并同一时间戳的编辑视为合并后操作。评审提交使用 GraphQL 的 `lastEditedAt`，因为 REST 表示不含编辑时间。
+每个选定的 PR 都会在获取任何反馈前接受过滤：其 merge commit 必须是 `origin/master` 的祖先。merge commit 可达性是唯一的资格检查：直接 base 为功能分支的堆叠 PR，只要该 base 随后已经进入 master，就会被纳入，因为无论中间 stack 如何，评审人评论的代码此时已经在 master 上。工具还会解析落地 merge 的目标父级；无法重建的落地形态会记录到 `skipped-pulls.json` 并跳过。单个 PR 在预检、采集或证据收集时失败，只会被跳过，不会中止整次运行。如果时间窗口会超过 GitHub 搜索的 1,000 条结果上限，搜索阶段会明确失败，避免无提示地遗漏已合并 PR。采集阶段会完整读取内联评审评论、评审提交和 PR commit 的分页连接。不采集 PR 对话评论，因为强制推送后，GitHub 当前状态无法证明哪个仍然存在的 commit 位于评论之前，采纳约定因此必然会无条件排除这些评论。只有当 GitHub 报告 actor `type` 为 `User`，并且创建时间与最后编辑时间都严格早于 PR 合并时，工作流才接受已采集反馈；与合并同一时间戳的编辑视为合并后操作。评审提交使用 GraphQL 的 `lastEditedAt`，因为 REST 表示不含编辑时间。
 
 ### 采纳证据
 
@@ -40,13 +40,13 @@ flowchart TD
 
 两个独立配置的评审适配器，会从来源（`human-authored`、`forwarded-automation` 或 `unclear`）和采纳情况（`adopted`、`rejected` 或 `unclear`）两个维度，对每个符合条件的条目进行分类。只有两个适配器都判定为 `human-authored` 加 `adopted` 的条目才会继续。采纳集合随后会针对当前 skill 接受第二次独立分类：候选项、已经覆盖、实现专用或并非反馈。单个条目即可符合要求，不要求重复出现。意见分歧会得到一次有界的重新评估；如果仍未解决，则继续保留在运行产物中。单个批次的适配器输出如果未通过 schema 或 id 校验，系统会在批次层按不采纳处理：其中的每条反馈都标记为 unclear 并路由到 `excluded`，而不是中止整次运行；有问题的原始输出会保存在该次运行的私有产物中，供调试使用。如果任一适配器在某项操作的任何非空批次中都没有返回有效结果，运行会以非零状态退出并发出失败记录，而不会报告「没有候选项」。
 
-主适配器只根据结构化的共同指引起草，绝不接收原始评审文本。根据适配器作者的契约，它保持无工具且只读：返回完整的候选文件内容，由工具校验后写入唯一目标。两个适配器随后评审同一份完整 skill diff；阻塞性问题会进入有界修订循环，而且两者必须批准同一版修订。工具会在运行文档和 lint 检查前，以及报告成功前，再次拒绝暂存改动和目标 skill 之外的编辑，因此检查或并发进程无法通过添加其他路径混入。失败时，工具使用尽力而为的比较并交换回滚自身写入，以免覆盖维护者的并发编辑。成功时，它保存一份候选资料包，其中包含源 `origin/master` commit、源 skill blob ID、已评审 diff、完整候选文件、源反馈 ID 与 URL、落地证据范围、适配器判定和检查结果；它绝不提交、推送、打开或合并 PR。
+主适配器只根据结构化的共同指引起草，绝不接收原始评审文本。根据适配器作者的约定，它保持无工具且只读：返回完整的候选文件内容，由工具校验后写入唯一目标。两个适配器随后评审同一份完整 skill diff；阻塞性问题会进入有界修订循环，而且两者必须批准同一版修订。工具会在运行文档和 lint 检查前，以及报告成功前，再次拒绝暂存改动和目标 skill 之外的编辑，因此检查或并发进程无法通过添加其他路径混入。失败时，工具使用尽力而为的比较并交换回滚自身写入，以免覆盖维护者的并发编辑。成功时，它保存一份候选资料包，其中包含源 `origin/master` commit、源 skill blob ID、已评审 diff、完整候选文件、源反馈 ID 与 URL、落地证据范围、适配器判定和检查结果；它绝不提交、推送、打开或合并 PR。
 
 ### 评审适配器协议
 
-每个私有可执行文件从 stdin 接收有字节上限、带版本的 JSON 请求，并在 stdout 返回有字节上限且符合 schema 的 JSON。两个评审命令解析为逐字节相同的可执行文件时，工具拒绝运行；这只是最低限度的机械检查；确保主适配器与次适配器由独立提供方或模型驱动，仍是部署运维方的责任。`access` 与 `tools` 字段是适配器作者承担的契约标记，不是 OS 沙箱：评审子进程在清理后的环境中 spawn，其 `cwd` 指向私有运行目录而非仓库根目录；反馈包装在带随机数的 `<untrusted-feedback nonce="…">` 块中，每个提示词都会要求模型把它视为数据；128 位随机数防止不受信任的正文伪造结束标签。每个子进程都采用有界、感知中止的进程树清理。适配器作者把每项操作实现为纯只读推理（inference）；即使 `edit` 操作也只会在 JSON 中返回完整候选内容，由工具校验后写入唯一目标。每个生产 `git`／`gh`／检查命令同样在清理后的环境中 spawn，避免 pre-push 钩子的路由变量无提示地重定向维护工具。候选写入与失败回滚会针对最近一次写入内容使用尽力而为的比较并交换；回滚还会取消暂存目标，避免由适配器或检查暂存的候选项在失败运行后遗留并进入之后的 commit。
+每个私有可执行文件从 stdin 接收有字节上限、带版本的 JSON 请求，并在 stdout 返回有字节上限且符合 schema 的 JSON。两个评审命令解析为逐字节相同的可执行文件时，工具拒绝运行；这只是最低限度的机械检查；确保主适配器与次适配器由独立提供方或模型驱动，仍是部署运维方的责任。`access` 与 `tools` 字段是适配器作者承担的约定标记，不是 OS 沙箱：评审子进程在清理后的环境中 spawn，其 `cwd` 指向私有运行目录而非仓库根目录；反馈包装在带随机数的 `<untrusted-feedback nonce="…">` 块中，每个提示词都会要求模型把它视为数据；128 位随机数防止不受信任的正文伪造结束标签。每个子进程都采用有界、感知中止的进程树清理。适配器作者把每项操作实现为纯只读推理（inference）；即使 `edit` 操作也只会在 JSON 中返回完整候选内容，由工具校验后写入唯一目标。每个生产 `git`／`gh`／检查命令同样在清理后的环境中 spawn，避免 pre-push 钩子的路由变量无提示地重定向维护工具。候选写入与失败回滚会针对最近一次写入内容使用尽力而为的比较并交换；回滚还会取消暂存目标，避免由适配器或检查暂存的候选项在失败运行后遗留并进入之后的 commit。
 
-### 推广契约
+### 推广约定
 
 推广辅助工具从刷新至 `origin/master` 的干净 checkout 开始；当前 skill blob 与资料包中记录的源 blob 不同时，它拒绝应用候选项。运维方随后重新运行维护分析，或手动把 diff 变基后重新评审候选项；辅助工具绝不会用陈旧的完整文件输出替换较新的 `SKILL.md`。应用仍然有效的候选项后，它会打开 draft PR，其正文列出源反馈 URL 或 ID、用作采纳证据的落地 commit 范围、来源运行、检查结果和任何运维方编辑。原始适配器提示词与响应保持私有，但仓库评审人会获得足够的来源信息，以判断每条提议规则是否确实来自已采纳的人类反馈。
 
@@ -62,7 +62,7 @@ flowchart TD
 - **每次新评论都运行**：不予采纳，因为一轮评审会产生许多相关评论，并且缺少判断采纳情况所需的最终产物。
 - **把合并或讨论串解决视为采纳**：不予采纳，因为 PR 可能在反馈被拒绝、被取代或刻意不解决的情况下合并。
 - **自动创建或合并仓库改动**：不予采纳，因为工具首先需要通过有用的定期输出积累可信记录。维护者检查并通过普通仓库评审推广本地 diff。
-- **从已经修复的 bot 问题中学习**：不予采纳，因为来源契约限定为人类评审反馈。系统会在分析前按 actor 类型过滤，并通过来源评审排除转发自动化问题的人类账号。
+- **从已经修复的 bot 问题中学习**：不予采纳，因为来源约定限定为人类评审反馈。系统会在分析前按 actor 类型过滤，并通过来源评审排除转发自动化问题的人类账号。
 - **让同一个评审人既当作者又作最终裁决**：不予采纳，因为独立判定能在不受支持的概括进入 skill 之前暴露问题。
 
 ## 验收标准
@@ -80,6 +80,6 @@ flowchart TD
 
 - **根据 committer 时间戳推断因果关系。** 反馈 commit 基线通过比较 GitHub commit 时间戳与反馈创建时间戳选出；committer 时钟偏差与重写仍会留下误判采纳的残余窗口。与 GitHub 的 PR 事件流交叉比对可以进一步收紧，但需要采集定期工具作用域以外的事件。
 - **两个「非候选项」分类结果会直接路由到 `excluded`，不进入争议轮次。** 两个分类器都判断「不是候选项」，但对非候选原因意见不一时（例如 `covered` 与 `specific`），该条目会被排除而不是重新评估。两个分类器都同意它不会形成新的评审行为，所以争议轮次不会改变结果。
-- **超出字节哈希差异的双评审人独立性属于部署契约。** 两个命令解析为逐字节相同的可执行文件时，工具拒绝运行，但它无法验证两个不同包装层是否由不同提供方或模型驱动。运维方必须配置相互独立的主适配器与次适配器。
+- **超出字节哈希差异的双评审人独立性属于部署约定。** 两个命令解析为逐字节相同的可执行文件时，工具拒绝运行，但它无法验证两个不同包装层是否由不同提供方或模型驱动。运维方必须配置相互独立的主适配器与次适配器。
 - **候选写入与回滚使用尽力而为的比较并交换。** POSIX 上基于文件的比较并交换并不真正原子；窗口持续一个事件循环周期。该工具面向单用户定期维护，不考虑真正并发的编辑器。
 - **单维护者风险。** 由于机制位于单台机器，服务中断后，skill 维护会完全停止，直到运维方恢复服务，或通过一篇后续 Agent Note 把机制移交给新维护者。
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
index 5418a920e5..e4cee10cc2 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md
 2026-08-04-artifact-first-npm-baseline-publication.md: e79a988531ac266d72f7d2c036bdd10f3e4520a9
-2026-08-04-artifact-first-npm-baseline-publication.zh.md: d7322547c665700aeffce77ea0bb39f622220fe3
+2026-08-04-artifact-first-npm-baseline-publication.zh.md: 21581eb0d4ee3fad6217a2b8f2310d2fddded3a4
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
index d7322547c6..21581eb0d4 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
@@ -40,11 +40,11 @@ pack 阶段按以下顺序执行：
 
 拉取请求 CI 不会调用 pack 命令；安装态入口探测属于本地发布检查，而不是合并门禁。免凭据 CI 执行、其他每个 bin 与公开运行时入口的包自有探测、workflow artifact 传递及受保护 publish job 仍属于提案范围。
 
-## 发布 payload 契约
+## 发布 payload 约定
 
 发布包只携带消费方需要的构建产物。`package.json#files` 禁止包含 `src` 和 `lib/types/**/*.d.ts.map`；tarball 内容门禁还要独立确认不存在任何 `package/src/**` 与 `package/**/*.d.ts.map`，避免 manifest pattern 或 pack 行为绕过静态约束。运行时 JS、声明文件 `.d.ts`、配置、资源、worker 文件和 bundle 动态 chunk 必须按实际入口闭包收齐。
 
-源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方契约。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
+源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方约定。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
 
 每个 tarball 必须不含 `workspace:` specifier，并且所有指向本次发布集合的内部依赖与对等依赖（peer dependency）都必须精确等于本次派生版本，禁止使用 `^`、`~` 或其他 semver 范围跨越 commit 基线。除了明确仅供源码平面使用的 `exports["./src/*"]`，package manifest 中声明的每个消费方入口都必须指向 tarball 内存在的文件；动态 import、运行时拼接路径和非 export 资源不能只靠 manifest 检查，必须由安装后执行覆盖。
 
@@ -87,7 +87,7 @@ PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合
 
 **只运行 `dsh --help`。** 不采用，因为 Commander 可以在加载 TUI、Web 或 headless 动态入口之前输出帮助并退出。它无法证明默认生产启动路径完整。
 
-**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布契约。
+**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布约定。
 
 **要求真正的跨包原子发布。** 不采用，因为 npm 注册表没有相应事务。不可变 release bundle、发布前全量验证、integrity 比对与幂等恢复提供可实现的边界，同时明确保留部分上传短暂可见的限制。
 
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
index af8cad7d63..76abf19851 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
 2026-07-04-prune-dead-core-spine-surface.md: 7ee7ffc6e8c0f3672c98be6e23ef45a1abfc2b4e
-2026-07-04-prune-dead-core-spine-surface.zh.md: b65d607c1736545089c7116f8a14ab6e7510a8e1
+2026-07-04-prune-dead-core-spine-surface.zh.md: 69470658683f70ccc7ed71313654b769c3211cc9
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
index b65d607c17..6947065868 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -6,31 +6,31 @@ Status: proposed
 
 ## 问题
 
-若干包根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 契约、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
+若干包根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 约定、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
 
 生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note 行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/self-modification/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
 
 | 接口 | 生产证据 | 简化方式 |
 | --- | --- | --- |
-| `SurfaceManager.invalidate()` | 只有其单元测试调用它；seeding 在惰性创建的 manager 存在之前就已完成，且会话从不替换其日志引用。 | 删除它及其不可能触发的整体替换契约。 |
+| `SurfaceManager.invalidate()` | 只有其单元测试调用它；seeding 在惰性创建的 manager 存在之前就已完成，且会话从不替换其日志引用。 | 删除它及其不可能触发的整体替换约定。 |
 | `ToolExecutionResult.callId` | 每个钩子已经接收不可变的 `ToolExecution`；循环和 ACP（Agent Client Protocol）通过调用/会话事件关联。没有消费方读取这个重复的结果字段。 | 移除该字段、复制/不匹配守卫，以及证明该重复不可能不一致的测试。 |
 | `ReactLoopAgent` 根导出 | 包外的命名导入都是测试；生产代码面向 `Agent` 编程，通过 `ctx.agents` 创建/恢复。 | 将返回类型和接口类型设为 `Agent`，将具体循环类改为包内部；保留有意设计的同步、仅配置的 `AgentLoop.create()` 路径。 |
-| `workflow-workerthread` 的 protocol/runtime/session 再导出与命名的 `WorkerWorkflowEngine` | 所有通过包名导入的消费方都使用默认引擎；工作流 Agent Note 已将 worker 协议格式（wire format）定义为私有。 | 保留默认插件类/配置契约；移除重复的命名类导出，将协议模块保持为源码私有。 |
-| `code-runtime-worker` 的 protocol/bootstrap 再导出 | 包外的生产/e2e 消费方使用 `WorkerCodeRuntime` 和配置，而非 `BootstrapPort`、`PatchableStream` 或 worker 消息/启动类型。 | 保留运行时类/配置契约，将其协议格式/bootstrap 词汇改为源码私有。 |
+| `workflow-workerthread` 的 protocol/runtime/session 再导出与命名的 `WorkerWorkflowEngine` | 所有通过包名导入的消费方都使用默认引擎；工作流 Agent Note 已将 worker 协议格式（wire format）定义为私有。 | 保留默认插件类/配置约定；移除重复的命名类导出，将协议模块保持为源码私有。 |
+| `code-runtime-worker` 的 protocol/bootstrap 再导出 | 包外的生产/e2e 消费方使用 `WorkerCodeRuntime` 和配置，而非 `BootstrapPort`、`PatchableStream` 或 worker 消息/启动类型。 | 保留运行时类/配置约定，将其协议格式/bootstrap 词汇改为源码私有。 |
 | ACP 的 `agentOptions` 根导出 | 该辅助函数只有同文件和 ACP 测试消费方；唯一的包外生产消费方挂载的是插件命名空间。 | 保留 `name`、`inject`、`Config`、`AcpConfig` 和 `apply`；将 `agentOptions` 改为源码私有，通过桥接层行为测试。 |
 | `providerWording` 与 `completedTurnPrefix` 根导出 | 各有一个同包生产调用者；只有 balanced-prefix 辅助函数有一个同包白盒测试。 | 改为源码私有，测试提供方行为。 |
 | `depthOf`、`SubagentDepthError`、`waitForExit` 与 `exitsWithin` 根导出 | 生产 subagent 后端消费的是进程内 runner 和子进程构造/dispose（资源释放）辅助函数，而非这些强制机制和测试内部实现。`SENSITIVE_ENV_PATTERN` 不在其中，因为 SDK helper 会将它应用于调用方传入的环境。 | 保留深度与退出行为，但将剩余辅助函数和 error 改为源码私有；通过 spawn 和 dispose 测试。保持共享凭据正则公开。 |
-| `PersistenceCoordinator.inits`、后端 `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留两个后端、`SessionHeader` 和 SQLite 的版本契约。 |
+| `PersistenceCoordinator.inits`、后端 `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留两个后端、`SessionHeader` 和 SQLite 的版本约定。 |
 | `LlmError.status` 与回放 status | 适配器/回放填充它，但生产分支基于稳定的错误码/消息判断，从不读取原始 status。 | 移除未读字段和回放管道，保留错误分类。 |
-| `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 契约。 |
+| `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 约定。 |
 | `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region seam，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
 | `CompactionResult.startSeq`、`summarySeq`、`endSeq` 与 `summary` | 生产消费方只读取 shadowed range/seq/token 统计；持久日志拥有 summary 和事件标识。 | 移除四个结果回显，保留两个共享的 transcript（文本记录）渲染器。 |
 | `BasicCompactService` 的估算/摘要方法可见性 | 没有包外生产调用者调用这五个方法；已实现的 Agent Note 只将 `estimateContentTokens()` 和 `summarize()` 命名为子类钩子。 | 将这两个方法改为 `protected`，其余三个编排专用的估算器改为 private。 |
 | `CodeLogEntry.source`/`level` 与 `RunCodeMeta.dispatches` | 每个生产消费方都将日志映射为文本；没有 presenter/模型路径读取其他字段或持久化的 dispatch 计数。 | 将 code-runtime 日志改为字符串（或纯文本条目），移除 result-meta 的 dispatch 管道；保留用于生成确定性 dispatch id 的本地计数器。 |
 | `CodeRuntime.language` 与 `CodeRuntime.isolation` | worker 后端提供唯一的生产值，而 Code Mode 及其他所有生产调用方只调用 `run()`。 | 移除未读描述符，同时保留 worker 的语言、隔离、预算、取消与资源释放行为。 |
 | `ToolNotFoundError.toolName`、`SystemPrompt.config` 与 `BashTask.command` | 每个存储的公开值都没有生产读取者。 | 移除未读字段，保留错误消息、已解析的配置行为和任务生命周期。 |
-| 后端包根实现辅助函数 | 下方精确清单仅通过相对路径的同包导入调用。生产命名空间导入挂载的是保留的插件契约，不读取这些属性；命名根消费方都是测试。 | 保留每个适配器/提供方/服务及其配置/错误契约；停止在包根导出所列辅助函数/常量。 |
-| 消费方包根实现辅助函数 | 下方精确清单只有同包生产调用者。生产命名空间导入挂载的是插件契约，不读取辅助属性；命名根消费方都是测试。 | 保留插件契约和稳定的错误码；将测试迁移到包内模块或公开行为，停止在包根导出所列辅助函数。 |
+| 后端包根实现辅助函数 | 下方精确清单仅通过相对路径的同包导入调用。生产命名空间导入挂载的是保留的插件约定，不读取这些属性；命名根消费方都是测试。 | 保留每个适配器/提供方/服务及其配置/错误约定；停止在包根导出所列辅助函数/常量。 |
+| 消费方包根实现辅助函数 | 下方精确清单只有同包生产调用者。生产命名空间导入挂载的是插件约定，不读取辅助属性；命名根消费方都是测试。 | 保留插件约定和稳定的错误码；将测试迁移到包内模块或公开行为，停止在包根导出所列辅助函数。 |
 
 ### 分组辅助导出清单
 
@@ -43,18 +43,18 @@ Status: proposed
 
 ## 提案
 
-以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳契约。
+以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳约定。
 
 ## 曾考虑的替代方案
 
-**保留测试便利函数和自包含的结果字段为公开。** 公开辅助函数可以让白盒测试更方便，自包含的结果字段看起来更易用，未来的嵌入者可能需要具体循环类或枚举方法。这些好处是假设性的；当前它们让每处实现和文档都要解释没有已交付调用者能观察到的状态。真正的消费方可以引入它所需的最小契约，其所有权和失败语义明确。
+**保留测试便利函数和自包含的结果字段为公开。** 公开辅助函数可以让白盒测试更方便，自包含的结果字段看起来更易用，未来的嵌入者可能需要具体循环类或枚举方法。这些好处是假设性的；当前它们让每处实现和文档都要解释没有已交付调用者能观察到的状态。真正的消费方可以引入它所需的最小约定，其所有权和失败语义明确。
 
 **保留所有 catalog 成员以供模型编写的 mount 使用。** 自引用工具集是一条真实的通用消费路径，而非生成文档的噪音。然而，它的价值来自准确、可组合的服务接口，而非无限期保留重复字段或不一致的参数对；上述每一项 catalog 收缩都移除了在同一次执行、同一个 agent（智能体）或同一结果中其他位置已可获得的事实，并在同一变更中更新 API 参考。
 
 ## 验收标准
 
 - 精确符号搜索显示：在本 Agent Note 及任何已实现 Agent Note 修正之外，没有被移除的接口。
-- 本 Agent Note 列出的每个接口均按指定方式缺失或降级；清单之外有意保留的扩展/测试契约不变。
+- 本 Agent Note 列出的每个接口均按指定方式缺失或降级；清单之外有意保留的扩展/测试约定不变。
 - 工具执行、上下文压缩（context compaction）、两个 LLM 适配器、两个持久化后端、工作流隔离以及 agent 创建/恢复保持其已交付行为。
 - 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建和 hygiene 通过。
 
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
index 34eeca606c..7bea4132ff 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
 2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md: 236139f9198f178d44cdf0867cbad2377a127359
-2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: e636bba5b7d69774b2eb5eccea1f3272211dedf2
+2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: 650217e936aa65884e8fb4fed0358406c78e9931
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
index e636bba5b7..650217e936 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
@@ -14,7 +14,7 @@ Status: rejected — landstrip 未经实战检验（驳回时问世仅数天，
 
 当 Windows 沙箱阶段启动时，在动手编写自研 AppContainer 启动器仓库之前，先评估将 landstrip 的 Windows 后端包装为 `win32` 链运行器。评估必须回答：
 
-- **探测合成。** landstrip 没有 `--probe`；链所要求的功能探测契约必须从一次 trap 运行中合成出来。
+- **探测合成。** landstrip 没有 `--probe`；链所要求的功能探测约定必须从一次 trap 运行中合成出来。
 - **方言映射。** 拒绝与运行器失败两类 stderr 方言，以及失败关闭的退出码分类，都需要显式映射到链的词汇中。
 - **许可证。** 其二进制文件采用 LGPL-2.1-or-later 许可；在进入随产品发布的依赖闭包之前需要先做分发审查。
 - **溯源。** 自研启动器的价值在于一个约 300 行、可完整评审，并由原生 CI 逐字节锁定来源的 C 文件；而 landstrip 是单一维护者手中的一组 Rust 二进制文件。对*既有的 Linux 层级*而言，这笔权衡早有定论——不要替换它（见[沙箱 Agent Note](../../implemented/feature/2026-07-06-sandbox.md)以及该启动器自身移除 Rust 依赖的迁移记录）。而对一个我们尚未构建的层级，在第三方维护与第二个自研原生仓库之间如何取舍，是一个真正悬而未决的问题。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
index d9dd98233e..02d597f3ae 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
 2026-06-20-assembled-assistant-messages-only.md: edc756f71271065ec579a2becb8597190b34cdc8
-2026-06-20-assembled-assistant-messages-only.zh.md: e5f4f8a63a35f5f40c482a4a4855937cc8e6d544
+2026-06-20-assembled-assistant-messages-only.zh.md: 6f0611a57550c53a9881e551f24098869c807c3e
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
index e5f4f8a63a..6f0611a575 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
@@ -27,7 +27,7 @@ ACP `session/load` 可以将先前的 assistant 消息作为完整内容块回
 
 ## 放弃了什么
 
-规范的用户会话不再能重建旧轮次的精确 token 流。它也会丢失失败或中止流的部分 assistant 输出，除非另有事件或 fixture 记录。对于当前的恢复、加载和快照契约而言，这是过大的信息损失。需要精确确定性流的测试应当直接拥有该 fixture，前提是生产会话日志为用户可见的恢复保留了足够的保真度。
+规范的用户会话不再能重建旧轮次的精确 token 流。它也会丢失失败或中止流的部分 assistant 输出，除非另有事件或 fixture 记录。对于当前的恢复、加载和快照约定而言，这是过大的信息损失。需要精确确定性流的测试应当直接拥有该 fixture，前提是生产会话日志为用户可见的恢复保留了足够的保真度。
 
 ## 相关
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
index 8a90d8e997..ff7497fc6c 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md
 2026-06-20-drop-durable-step-boundaries.md: c5c4f269a378e334c4dc509d1288146d77d9a520
-2026-06-20-drop-durable-step-boundaries.zh.md: 66e6d02225eb51bd395e84114d54a0dac8389fe0
+2026-06-20-drop-durable-step-boundaries.zh.md: 32d8255638b9d8b16b24e861eb092bbc906892f8
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
index 66e6d02225..32d8255638 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
@@ -20,7 +20,7 @@ Status: rejected — `step/end` 是模型步骤已完成的持久信号；保留
 
 - `SessionEventMap` 不再包含 `step/start` 或 `step/end`。
 - agent loop 中不再有 `closeStep()` 终结路径。
-- ACP 快照和持久化契约 fixture（测试前置数据）不再期望步骤边界行。
+- ACP 快照和持久化约定 fixture（测试前置数据）不再期望步骤边界行。
 - `deriveMessages()` 和回放从步骤级事件推导出相同的消息历史。
 - [事件分类体系文档](../../../../docs/architecture.md)将轮次描述为持久化边界，将步骤描述为步骤级记录上的一个字段。
 - 会话格式版本和已记录的 fixture 被刷新；按预发布格式策略，非当前版本的已存储日志被拒绝。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 4c5b2d04de..6c492ef3ee 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
 2026-06-20-fold-session-persistence-interface.md: c0da160e766cf0bed532f0d11bd52e3a027dbe8b
-2026-06-20-fold-session-persistence-interface.zh.md: 93ab244429600bd15e2d8dadfa7dc218e37c2eff
+2026-06-20-fold-session-persistence-interface.zh.md: 8abdf77d2717cfed7209df72182187f75e32e241
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index 93ab244429..8abdf77d27 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -6,20 +6,20 @@ Status: rejected — 独立的持久化接口包是为持久化后端设计的
 
 ## 问题
 
-`dsh-session-persistence` 是一个接口包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和契约辅助工具。后端包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
+`dsh-session-persistence` 是一个接口包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和约定辅助工具。后端包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
 
 当持久化还是一个全新的可替换后端设计时，能力 seam 的拆分是合理的。但在可变摘要被移除之后，这个接口包基本上只是包装了会话日志自身的存储职责。继续保持独立可能带来的仪式感多于清晰度。
 
 ## 提案
 
-将抽象的 `SessionPersistence` 服务、协调器和持久化契约辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
+将抽象的 `SessionPersistence` 服务、协调器和持久化约定辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
 
 实施 PR（Pull Request）应更新[能力 seam](../../implemented/architecture/2026-06-13-capability-seams.md) 指南，补充此例外：持久化不同于 bash 或 LLM（大语言模型），因为它的词汇和生命周期事件本就属于会话包的核心领域。
 
 ## 验收标准
 
 - `@deepseek-ai/dsh-session-persistence` 作为包被移除。
-- `dsh-session` 导出持久化服务类型、协调器和契约辅助工具。
+- `dsh-session` 导出持久化服务类型、协调器和约定辅助工具。
 - JSONL 和 SQLite 后端包直接依赖 `dsh-session`。
 - `agent-loop` 的恢复功能使用会话包拥有的服务键。
 - [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session/session-persistence/README.md)说明后端实现为何仍保持独立。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
index 7e9b79fdeb..e92c9adf31 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
 2026-06-20-truncate-interrupted-turns.md: c4b0084de537927a27829eb78990c6559bd1df7d
-2026-06-20-truncate-interrupted-turns.zh.md: 2d3eca74416eff360029e3ac77f04662878a0084
+2026-06-20-truncate-interrupted-turns.zh.md: 16277f45a238c4e6cb0b36a6c8651f68cf0494a1
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
index 2d3eca7441..16277f45a2 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
@@ -6,7 +6,7 @@ Status: rejected — 单个轮次可以包含大量真实工作，包括多个
 
 ## 问题
 
-当前的持久化契约会保留已持久写入但从未关闭的最终轮次。加载时，`interruptedTurnClosers()` 扫描尾部，为未应答的工具调用合成 error `tool/result` 事件，在步骤处于打开状态时追加 `step/end`，追加 `turn/end { kind: 'interrupted' }`，并要求后端持久提交这次修复。协调器、JSONL 后端、SQLite 后端、会话事件词汇、不变式、文档和测试都对这条合成关闭路径进行了建模。
+当前的持久化约定会保留已持久写入但从未关闭的最终轮次。加载时，`interruptedTurnClosers()` 扫描尾部，为未应答的工具调用合成 error `tool/result` 事件，在步骤处于打开状态时追加 `step/end`，追加 `turn/end { kind: 'interrupted' }`，并要求后端持久提交这次修复。协调器、JSONL 后端、SQLite 后端、会话事件词汇、不变式、文档和测试都对这条合成关闭路径进行了建模。
 
 这是一套庞大的机制，只为保留上次崩溃轮次中的部分工作。它还会凭空创造从未发生过的事件。合成的工具结果虽然有用（因为它使提供方历史保持合法），但也意味着恢复后的日志中包含了模型可见、却并非任何工具产出的文本。当前设计在尚无已发布产品、也没有真实恢复 UX 来证明部分轮次恢复确有价值的情况下，就以最大限度保留尾部为优化目标。
 
@@ -22,7 +22,7 @@ Status: rejected — 单个轮次可以包含大量真实工作，包括多个
 - `interruptedTurnClosers()` 及其测试删除。
 - 持久化协调器的修复钩子截断后端特有的撕裂或未关闭的尾部状态，不追加关闭事件。
 - [会话持久化文档](../../../../packages/session/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
-- 快照与契约测试随其所固定的行为一同更新。
+- 快照与约定测试随其所固定的行为一同更新。
 - 会话格式版本与记录的 fixture（测试前置数据）刷新；按预发布格式策略，非当前版本的存储日志被拒绝，不提供迁移路径。
 
 ## 放弃的内容
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
index c62b690b4e..820638a9f6 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
 2026-07-12-collapse-workflow-to-foreground-core.md: 629e2140523c3ae7caf533de99821206d05f1b8e
-2026-07-12-collapse-workflow-to-foreground-core.zh.md: 1af80e7ca28eb0e5acf3f642244260034c57d0ab
+2026-07-12-collapse-workflow-to-foreground-core.zh.md: 9683d5a15bc7d201eaff905c440bbdf88bbc9388
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
index 1af80e7ca2..9683d5a15b 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
@@ -20,7 +20,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 保留已使用的核心：`agent(prompt, { schema, model })`、`parallel`、`pipeline`、`args`、并发/agent 上限、取消、有界 dispose（资源释放）、结构化结果、worker 隔离与前台工具收集。移除所有 `workflow/*` 事件及其仅供事件使用的 info/outcome 类型；移除 `phase()`、`log()`、agent 的 `label`/`phase`、phase 声明、`whenToUse` 及其 worker 消息/host 观测者；将工作流元数据收缩为工具实际使用的 name；移除仅供事件使用的 run id/meta 快照与合成的 agent-end 账本。将 `WorkflowRun` 收缩为 `result`、`cancel()` 和 `dispose()`；工具渲染请求方持有的 name。移除 `WorkflowStartRequest.signal` 及 worker host 的 input-signal listener/disarm 状态，保留调用方从其 abort signal 到 `run.cancel()` 的桥接。将 `WorkflowError` 变为单一的 fatal 错误类，不再有布尔模式或 `isFatalWorkflowError()` 辅助函数。
 
-修订已实施的动态工作流 Agent Note，并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联契约出发，而非原样复活这套协议。
+修订已实施的动态工作流 Agent Note，并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联约定出发，而非原样复活这套协议。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 ## 验收标准
 
-- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 契约。
+- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 约定。
 - 不再保留任何工作流事件、phase/log 协议消息、run-id 生成器、仅供进度使用的元数据、host 配对账本或 fatal 模式分支。
 - run handle 不再有 id/meta 回显，取消在同步 `start()` 返回后只有一条持有者拥有的通道。
 - parallel/pipeline 行为、上限、取消后的完全停稳、worker 隔离、结构化输出与面向模型的工作流场景保持测试覆盖。
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
index 306226eb1f..3da21fcadc 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
 2026-07-12-prune-unused-skill-registry-surface.md: 5a13effa04a6cd9954741a0a33ebc6fc3512fab8
-2026-07-12-prune-unused-skill-registry-surface.zh.md: f6010cba4efd3c80cab867dfdf2470ccf1495d6a
+2026-07-12-prune-unused-skill-registry-surface.zh.md: f0cca25cb642eba851b63ce784d8fb9343d1f692
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
index f6010cba4e..f0cca25cb6 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
@@ -10,9 +10,9 @@ skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register(
 
 ## 提案
 
-移除 `SkillService.register()`、`SkillRegistration`、运行时伪提供方及保留名称规则、运行时 revision/缓存分支，以及仅用于运行时的 source/rank 规范化逻辑。需要嵌入式 skill 的测试改为注册一个小型真实提供方。保留 `providerRevision` 作为进行中发现操作的 epoch，但已完成的目录缓存仅以 cwd 为键：每次提供方变更同步清除缓存，await 之后的 revision 比较已能阻止插入陈旧结果。从 skill 契约和本地提供方副本中移除 `whenToUse`、`SkillCandidate.path` 与 `SkillDefinition.path`，同时保留提供方的 locator/root 路径；保留 `metadata`、`disableModelInvocation`、`source`、`provider`、`locator` 和 `resourceBase`，因为它们要么是有意开放的扩展词汇，要么是生产消费的字段。
+移除 `SkillService.register()`、`SkillRegistration`、运行时伪提供方及保留名称规则、运行时 revision/缓存分支，以及仅用于运行时的 source/rank 规范化逻辑。需要嵌入式 skill 的测试改为注册一个小型真实提供方。保留 `providerRevision` 作为进行中发现操作的 epoch，但已完成的目录缓存仅以 cwd 为键：每次提供方变更同步清除缓存，await 之后的 revision 比较已能阻止插入陈旧结果。从 skill 约定和本地提供方副本中移除 `whenToUse`、`SkillCandidate.path` 与 `SkillDefinition.path`，同时保留提供方的 locator/root 路径；保留 `metadata`、`disableModelInvocation`、`source`、`provider`、`locator` 和 `resourceBase`，因为它们要么是有意开放的扩展词汇，要么是生产消费的字段。
 
-同步修订 skill 系统 Agent Note、README、JSDoc、目录文件与测试。agent（智能体）作用域的系统提示词段、工具提供方和变量明确不在本提案范围内：[agent 作用域贡献者契约](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)有意允许在 `setup(agentCtx)` 期间通过 agent 拥有的上下文注册这三者，因此仓库内没有固定的作用域注册并不能证明它们未被使用。
+同步修订 skill 系统 Agent Note、README、JSDoc、目录文件与测试。agent（智能体）作用域的系统提示词段、工具提供方和变量明确不在本提案范围内：[agent 作用域贡献者约定](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)有意允许在 `setup(agentCtx)` 期间通过 agent 拥有的上下文注册这三者，因此仓库内没有固定的作用域注册并不能证明它们未被使用。
 
 ## 曾考虑的替代方案
 
@@ -20,7 +20,7 @@ skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register(
 
 ## 验收标准
 
-- skill 收集只有一条提供方驱动的路径，已完成缓存仅以 cwd 为键，revision epoch 仅用于使进行中的发现操作失效；保留的 skill 字段要么有生产读取方，要么有记录在案的有意扩展契约。
+- skill 收集只有一条提供方驱动的路径，已完成缓存仅以 cwd 为键，revision epoch 仅用于使进行中的发现操作失效；保留的 skill 字段要么有生产读取方，要么有记录在案的有意扩展约定。
 - agent 作用域的提示词段、变量、工具提供方、工具守卫，以及原生模式和 Code Mode 下的 structured-output 提交行为保持不变。
 - 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建与 hygiene 全部通过。
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index 0f5dedddd2..af897a186b 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
 2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: b3f7a1d9717397ee9ed50890bc024fba7d79fa9a
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: cc56dd44938cfe6d4c4b0aff1c714d80b8d8f5b6
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index b3f7a1d971..cc56dd4493 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -35,7 +35,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `fast-deep-equal` 替换会话接口面的 `isDeepEqualJson`**、**以 `safe-stable-stringify` 承担 repeat-tool-guard 的规范化**：两项替换在机械层面都可行，但每一项都是拿约 17–20 行带注释、有测试的代码，去换一个核心包的第一个外部运行时依赖——在这个体量上是净亏损。
 - **以 zod/valibot 承担持久事件的严格解码器**（goal fold、tool-ralph、session）：它们是位于持久化边界、键集精确匹配、失败即大声报错、带事件专属报错信息的解码器；在仓库标准 schemastery 之外再放一个 schema 库是政策变更，不是删除。
 - **以 `gpt-tokenizer`/tiktoken 替换 token-meter**：[回放 token 计量决策](../../implemented/architecture/2026-07-15-replay-token-meter-service.md)已明确否决分词器后端；GPT 的 BPE 对 DeepSeek 模型来说也是错误的分词器，而且这个包约 350 行是回放折叠簿记，任何分词器都覆盖不了。
-- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的契约，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
+- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的约定，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
 
 **文件系统、子进程与终端：**
 
@@ -46,14 +46,14 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `shell-quote` 承担 POSIX 单引号包裹**：两个各 1 行、测试详尽的引号辅助函数，对上一个处于维护模式、有 CVE 历史、转义输出还不一样的包——安全边界不是省一行代码的地方。
 - **以 `strip-ansi` 承担 pty 净化**：pty 净化器是一台流式状态机，带跨分片的断裂序列续接和 OSC `133;D` 提示符标记提取（shell 就绪信号）；无状态的剥离器只能替掉约 20 行内层代码，全部状态机构件原样保留。`stripVTControlCharacters` 还被实证会泄漏未终止的 OSC 载荷，会话标题归一化器必须剥除它们（反欺骗）。
 - **以 `pidtree`/`ps-tree` 承担 pty 进程巡检器**：它们只给裸 PID 树；这段代码需要对抗 PID 复用的启动时间身份校验，加上 `/proc` stdin 等待检测，没有包做这些。
-- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」契约；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
+- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」约定；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
 - **以 `tree-kill` 承担 acp-snapshot 拆除与 lsp 进程终止**：那些代码行做的是排空顺序与错误传播，不是进程树遍历；lsp/bash 已经使用分离的进程组加 taskkill。
 - **在 TUI 测试驱动器上到处使用 node-pty**：已归档的 [Windows TUI 决策](../../archived/feature/2026-07-20-windows-tui-support.md)明确否决了在每个宿主上都使用 node-pty；它当时已经是 Windows 那一条腿。
 
 **服务器与 HTTP：**
 
 - **以 `msw` 替换 llm-mock-server**：这个服务器的存在意义就是在线路上制造故障——socket 销毁、SSE（Server-Sent Events）中途断连、停滞、监听前拒绝——服务对象是真实的 HTTP 适配器和子进程；进程内拦截一样都表达不了。设计归[线路故障服务器决策](../../implemented/testing/2026-07-25-scriptable-llm-wire-fault-server.md)所有。
-- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」契约、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
+- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」约定、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
 - **以 `@mozilla/readability`/`iconv-lite` 承担 web-fetch-local**：该提供方返回原始 HTML；字符集处理已经是内置的 `TextDecoder`；MIME 解析约 11 行；重定向跟随是同源安全策略。
 
 **SQLite 与存储：**
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 077f5fa7f2..a2196f3212 100644
--- a/README.i18n.yaml
+++ b/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 README.md
 README.md: ff4cf661a060772973629844d43758d26ac1be02
-README.zh.md: 977de7f22244ff49579393edcce66d02c5782de4
+README.zh.md: f066f406df9150355d9b2d4282e882129b7ece1e
diff --git a/README.zh.md b/README.zh.md
index 977de7f222..f066f406df 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -49,7 +49,7 @@ dsh plugin --profile tui add <package>  # install a plugin into a custom profile
 dsh --profile tui                       # boot it
 ```
 
-profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。
+profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。
 
 ### Headless
 
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 801560e7d7..162ea534b7 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
 README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 9518feed1d5d40c3e5ec2d346b929118ccc08810
+README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 9518feed1d..37967973ed 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -23,4 +23,4 @@ profile 目录包含一个 `package.json`（树外插件依赖，加上 profile
 
 ## 开发
 
-生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。
+生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析约定。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 325de8db4e..a478ae60d2 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
 README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: a65140e6dc9374e21bdd3018bce45432794a7b10
+README.zh.md: 81320ecbd19012123ab7e69967cbadb088356cfe
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a65140e6dc..81320ecbd1 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -61,7 +61,7 @@ dsh web --dump-config
 
 `DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 RL 兼容 `--patch` overlay：它固定使用 `native` 模式，仅将 `DSH_SYSTEM_PROMPT` 或 `You are a helpful software engineer assistant.` 渲染为系统提示词，禁用 Workspace 指令与所有 Web 运行时提示词贡献，并且在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，仅暴露持久 `bash` 和 `str_replace_editor`。
 
-`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该契约的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
+`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该约定的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
 
 ## 共享部署行为
 
@@ -69,7 +69,7 @@ dsh web --dump-config
 
 会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
 
-空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 约定](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 360e4b32e4..c395f05428 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
 api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: 92681b72ffc573cde834cece19568ec3f1d515ce
+api-gateway.zh.md: 5c4f306957a65a92abe8f15159ab2d23e61ef501
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 92681b72ff..5c4f306957 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -2,7 +2,7 @@
 
 [English](api-gateway.md) | 中文
 
-本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 契约，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
+本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 约定，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
 
 ## 编程模型
 
@@ -75,7 +75,7 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 约定，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
 
 ## 组件职责
 
@@ -138,7 +138,7 @@ SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Ho
 
 ## 开发模式
 
-完整构建会先生成 Host 契约，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
+完整构建会先生成 Host 约定，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
 
 ```sh
 pnpm run build
@@ -153,18 +153,18 @@ pnpm run dev:web
 
 `dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dshClient` 声明的 Client plugin 并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
 
-只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格契约，再让 Client 编译并打包新的贡献：
+只修改 Remote 方法实现体而不改变约定时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定，再让 Client 编译并打包新的贡献：
 
 ```sh
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 契约，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
 Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务契约允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务约定允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
 
 当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 2436ff9027..6791ac709d 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/architecture.md
 architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
-architecture.zh.md: 5780d54aad6085ef7811dfa94377a4c2478bfb99
+architecture.zh.md: 80028f33c620b35ffc549b4f4828a23a5f930e93
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 5780d54aad..80028f33c6 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -141,7 +141,7 @@ idle inject:
 
 **模型可见 ⟺ 已记录**：在 `step/start` 进入的消息加上折叠后的 `request/header` 可以重建每个请求。该 header 会标记适配器默认值，使后续提议丢弃这些值并重新解析路由，同时不丢失显式设置。`request/context` 会在路由变化时另行记录与注册项绑定的提供方、模型及容量元数据；它不参与请求重建或 header 相等性判断。`dsh-agent-loop/invariant` 通过 `ctx.invariants` 断言可重建性（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
 
-持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
+持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一约定（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
 在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
@@ -149,7 +149,7 @@ idle inject:
 
 消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 0c26b8be17..98b5a7fe23 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
 adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
-adding-a-package.zh.md: 8c0bc9dbd02b18a388f8e6ce91af10753c0210a2
+adding-a-package.zh.md: 400bd080b04ff5791393b56e67c1e3b9ade987de
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 8c0bc9dbd0..400bd080b0 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -31,7 +31,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 | 文件 | 变更 |
 |---|---|
 | `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
-| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成契约与 Client 消费契约之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
+| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成约定与 Client 消费约定之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
 | `knip.json` | 仅当包有仓库发现机制尚未覆盖的入口时需要 |
 
 `packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
@@ -74,7 +74,7 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.
 ````
 
-根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包契约。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
+根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包约定。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
 
 没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
 
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index ca64363bd6..16439b1732 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-tool.md
 adding-a-tool.md: cb418a9118901cc6572fb17125351bdda922434b
-adding-a-tool.zh.md: d8b73a51d1dde8647e7a032648f8a6344fcc83eb
+adding-a-tool.zh.md: 22eccec67a3f941976608dc7fc1cc4120e4e1bd1
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index d8b73a51d1..22eccec67a 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -2,7 +2,7 @@
 
 [English](adding-a-tool.md) | 中文
 
-面向模型的工具必须满足哪些契约，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
+面向模型的工具必须满足哪些约定，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
 
 ## 最小形态
 
@@ -37,7 +37,7 @@ export function apply(ctx: Context) {
 
 注册基于副作用：dispose（资源释放）插件 fiber 即注销该工具。schema 会自动流入系统提示词的组装过程。
 
-## execute() 契约的规则
+## execute() 约定的规则
 
 - **参数已为你校验。** `defineTool` 在 `execute` 运行前，会根据统一的 `ParameterSchemaSpec` 校验模型生成的 `arguments`（类型、必填键、字面量约束、恰好匹配一个分支的联合以及嵌套值——见[运行时参数校验](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)），因此 `execute` 内的 args 会匹配 `InferArgs`。显式对象节点必须声明 `additionalProperties: true | false`；隐式参数根对象保持开放。你仍需手动检查 schema DSL 无法表达的约束，例如非空字符串、正数或跨字段规则。直接注册的原始 JSON Schema 工具自行负责输入校验。
 - **注册借用你的只读定义。** 类型化的同进程贡献不是序列化边界；注册后不要修改其 schema 或替换回调。`schemas()` 只物化显式的模型可见投影。如需热替换工具，请 dispose 其所属副作用并注册替代品；回调闭包内的可变状态仍是普通的插件状态。
@@ -52,11 +52,11 @@ export function apply(ctx: Context) {
 
 通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', taskId }`；其 Native 渲染器可以保留 `started background task bash-1` 这类供人阅读的自然语言，但 Code Mode 绝不能通过解析该文本取得 id。
 
-producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整契约见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
+producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
 ## 执行策略与观测
 
-尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
+尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切约定见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
 
 ## Code Mode 自动触达你的工具
 
diff --git a/docs/cookbook/adding-an-llm-adapter.i18n.yaml b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
index 199a870ac9..4abdc20223 100644
--- a/docs/cookbook/adding-an-llm-adapter.i18n.yaml
+++ b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-an-llm-adapter.md
 adding-an-llm-adapter.md: 4fcc646ed2eea8a6170027d01761887aa28b0045
-adding-an-llm-adapter.zh.md: eeeb84583fb9951745083b60385547d14f461266
+adding-an-llm-adapter.zh.md: b1dacf77cb94884d9ca8780affc391e5127f0457
diff --git a/docs/cookbook/adding-an-llm-adapter.zh.md b/docs/cookbook/adding-an-llm-adapter.zh.md
index eeeb84583f..b1dacf77cb 100644
--- a/docs/cookbook/adding-an-llm-adapter.zh.md
+++ b/docs/cookbook/adding-an-llm-adapter.zh.md
@@ -22,7 +22,7 @@ export function apply(ctx: Context, config: Config) {
 
 注册基于副作用，可安全支持 HMR（热模块替换）；每个提供方路由仅对应一个适配器，重复注册会抛出异常，多路由注册要么全部成功，要么全部失败。`options.provider` 用于选择适配器，`options.model` 是提供方模型 ID，因此动态模型目录适配器无需重新配置生命周期即可提供新模型。密钥采用 Cordis 原生方式管理：schemastery Config 带环境变量回退，通过 cordis.yml 的 `!!js process.env.MY_KEY` 注入。切勿在代码中读取自行约定的密钥文件。
 
-## 协议义务（两个实现共同验证的契约）
+## 协议义务（两个实现共同验证的约定）
 
 - 在 `finish` **之前**发出 `usage`；`finish` 之后**不再发出任何内容**。稳健做法：缓冲 finish/usage 直到提供方的流结束标记，再统一 flush（可处理提供方在末尾发送仅含 usage 的分片的情况）。
 - 工具调用的 `arguments` 全程为原始 JSON 字符串；流式片段以 `argumentsDelta` 发送。如果你的提供方返回已解析的对象，请在 `block-end` 时重新 stringify。
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index e341244f40..919a9faf5d 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
 extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
-extension-cookbook.zh.md: c2fa2f83c39ca0eb93397f39c88265c028224c7a
+extension-cookbook.zh.md: c3370a519bb09435749d608fe7c63a5330c24f62
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index c2fa2f83c3..c3370a519b 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -64,7 +64,7 @@ export function apply(ctx: Context) {
 
 *协议驱动*将协议对端接入 `ctx.agents`；它可以服务于 UI 或自动化客户端。stdio 驱动拥有 stdout，通过工厂创建或恢复 agent（智能体），并将协议请求映射为 `followup()` 或 `cancel()`。底层提示词请求返回其持久入队回执；它不会通过关联 `MessageId` 与 `turn/end` 获得结果。整个 agent 的状态应单独发布。自动化方法可以从回执等待到下一次 idle，并概括这一显式拥有的区间；UI 通常则会持续观察开放式事件流。通过 `AgentHandle.dispose()` 拆除 agent，以使 dispose（资源释放）达到完全停稳。
 
-[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期契约。
+[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期约定。
 
 ```ts
 import type { Context } from 'cordis'
diff --git a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
index a069b8a4da..cb578de462 100644
--- a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
+++ b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/maintaining-dsh-code-review.md
 maintaining-dsh-code-review.md: 2b5d0d926ae922f2650daac33cf35991cb71c5e5
-maintaining-dsh-code-review.zh.md: 56d274c080fcd95b6d18219f4bf0e0e7485f624e
+maintaining-dsh-code-review.zh.md: 4466565b294ede89fa34da9e76b88f4ac39748eb
diff --git a/docs/cookbook/maintaining-dsh-code-review.zh.md b/docs/cookbook/maintaining-dsh-code-review.zh.md
index 56d274c080..4466565b29 100644
--- a/docs/cookbook/maintaining-dsh-code-review.zh.md
+++ b/docs/cookbook/maintaining-dsh-code-review.zh.md
@@ -20,7 +20,7 @@
 
 某次运行产出候选版本时，macOS 会发出一条带 `dsh-code-review-promote <timestamp>` 提示的通知。
 
-1. **根据 diff 本身作出判断。** 不要因为「评审者已经批准」就直接接受：维护者契约规定最终判断由操作员作出。检查清单是否膨胀、是否有历史叙述、是否根据单次事件作出无依据的外推，以及是否与现有 skill 或权威文档重复。
+1. **根据 diff 本身作出判断。** 不要因为「评审者已经批准」就直接接受：维护者约定规定最终判断由操作员作出。检查清单是否膨胀、是否有历史叙述、是否根据单次事件作出无依据的外推，以及是否与现有 skill 或权威文档重复。
 
    ```sh
    ls ~/dsh-code-review-outputs/                         # every candidate ever produced
diff --git a/docs/cordis-primer.i18n.yaml b/docs/cordis-primer.i18n.yaml
index ec67982eb5..9e1143231e 100644
--- a/docs/cordis-primer.i18n.yaml
+++ b/docs/cordis-primer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-primer.md
 cordis-primer.md: 4bcb2c9979994ca70f92031cbdc5dd22df9c1977
-cordis-primer.zh.md: d84beac54463ec193f009f506a4c9b1bda02c243
+cordis-primer.zh.md: a18b8b37af19a610b71babbe5e67f96bb09e81b1
diff --git a/docs/cordis-primer.zh.md b/docs/cordis-primer.zh.md
index d84beac544..a18b8b37af 100644
--- a/docs/cordis-primer.zh.md
+++ b/docs/cordis-primer.zh.md
@@ -23,7 +23,7 @@ Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。
 | `parallel` | 是 | 所有监听器并行观察事件 | 否 |
 | `serial` | 是 | 监听器按注册顺序观察 | 是 |
 
-分发模式是事件公开契约的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
+分发模式是事件公开约定的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
 
 <a id="cordis-waterfall-semantics"></a>
 
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index a78b8f690c..2914e62e30 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/04-events.md
 04-events.md: b0563c71fada3efc760ff7183bc7a82e7e86934e
-04-events.zh.md: 0999cbf116eca452e54418132fbaefe3622b2c26
+04-events.zh.md: 66b52fcb1d7ec4a81c823a7c8e016c5b17d45993
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index 0999cbf116..66b52fcb1d 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -79,7 +79,7 @@ export function apply(ctx: Context) {
 
 ## 分发模式
 
-`emit` 是 5 种分发模式之一。事件采用哪种模式是其契约的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路：
+`emit` 是 5 种分发模式之一。事件采用哪种模式是其约定的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路：
 
 | 模式 | 调用 | 语义 |
 |---|---|---|
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
index a00432f1d5..8f27720c45 100644
--- a/docs/defensive-patterns.i18n.yaml
+++ b/docs/defensive-patterns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/defensive-patterns.md
 defensive-patterns.md: 6dc1708f0b9bbcb00ad4774006d6d60059accf6a
-defensive-patterns.zh.md: 2ff5cba2a94c5149f2b92b37845d23211ee7989d
+defensive-patterns.zh.md: 587d09a812857e6cf61f64bfd0e17e3386d1a772
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
index 2ff5cba2a9..587d09a812 100644
--- a/docs/defensive-patterns.zh.md
+++ b/docs/defensive-patterns.zh.md
@@ -8,7 +8,7 @@
 
 一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。
 
-## 跨 seam 契约两侧都要遵守
+## 跨 seam 约定两侧都要遵守
 
 当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 00673a9415..5e2895c8ba 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
 development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 9d3606cf741f25318c630e08e8ac84ad5ee8d345
+development.zh.md: 56df93beddbb128cac8e0bcf2adaa9dcfb72c751
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 9d3606cf74..56df93bedd 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -21,7 +21,7 @@
 pnpm install
 ```
 
-安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
+安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
 
 如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：
 
@@ -73,9 +73,9 @@ pnpm run build:web
 
 两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
 
-TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
+TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
 
 业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git 集成
 
-当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
+当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。
 
 安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。
 
@@ -108,7 +108,7 @@ lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
-- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
+- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
@@ -156,10 +156,10 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index 2dfe08c2fd..ab9b5cec1d 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/glossary.md
 glossary.md: 16409517bff623a80d6e1e00888d95f63b42f780
-glossary.zh.md: fe3138ac81f2681d7fc69cc2aede96edeb7ec176
+glossary.zh.md: a84447dd067a3364033601742c116583661cdf45
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index fe3138ac81..a84447dd06 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -8,7 +8,7 @@ DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。
 
 - **scope**：按 agent（智能体）划分的注册单位。一项贡献（工具、提示词片段、变量、限制、监听器）要么是*全局的*（对所有 agent 可见），要么是*带作用域的*（归属于恰好一个 [scope key](#scope-key)）。只有两层，采用扁平结构：带作用域的注册不会向下继承给 subagent；子树行为通过 [lineage](#lineage) 数据表达，从不通过 scope 结构。
 - **scope key**：scope 的不透明标识，按对象同一性比较。harness 约定：一个活跃的 agent 就是其自身 scope 的 key。<a id="scope-key"></a>
-- **agent 上下文（`agent.ctx`）**：agent 的带作用域上下文；通过它进行的注册既具有 scope 可见性，其生命周期也绑定到该 scope（同一事实决定两者），其上的监听器参与该 agent 的 scope 过滤分发。注册表主体事件可以根据各自的事件契约有意保持不过滤。
+- **agent 上下文（`agent.ctx`）**：agent 的带作用域上下文；通过它进行的注册既具有 scope 可见性，其生命周期也绑定到该 scope（同一事实决定两者），其上的监听器参与该 agent 的 scope 过滤分发。注册表主体事件可以根据各自的事件约定有意保持不过滤。
 - **scope carrier**：scope 过滤分发所携带的 `thisArg`（由 `scopeTarget` 构建）；其过滤器放行无标签监听器加上主体自身的监听器。*无主体*的 carrier（没有 key）只放行无标签监听器。
 - **scoped dispatch**：规则是：关于某个 agent 的活动的事件以该 agent 的 carrier 进行分发。关于注册表本身的事件（如「一个工具被添加了」）属于*注册表主体*事件，保持不过滤。
 - **shadowing**：最具体者胜出的名称解析：一个带作用域的工具／片段／变量仅在该 scope 内替换同名的全局对应项。这是按 agent 定制 persona 和按 agent 定制工具变体的机制。
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index c62de565e7..aa299088e1 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
 README.md: 30f56eeebf15a3edec559e3080247dab9ab14178
-README.zh.md: 91d5b35a00994beea70f2bbd674cfb557d6f834d
+README.zh.md: 52d0061fc6b7edd6ecbcab0798380f7202fd4981
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 91d5b35a00..52d0061fc6 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
 
-## 配对契约
+## 配对约定
 
 - **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
 - **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
@@ -23,7 +23,7 @@
 
 ## 门禁：verify-translation-pairing
 
-`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：
+`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：
 
 1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。
 2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
@@ -37,7 +37,7 @@
 
 这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
 
-把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
+把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
 
 ## 范围与排除
 
@@ -55,4 +55,4 @@
 
 ## 分工
 
-这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
+这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 299f7db46f..846ade98b9 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -74,7 +74,7 @@
 | English | 中文 | 首次出现 | 不要译作 | 备注 |
 |---|---|---|---|---|
 | adapter | 适配器 | | | |
-| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |
+| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |
 | append-only | 仅追加 | | | |
 | artifact | 产物 | | 制品 | |
 | backend | 后端 | | | |
@@ -101,7 +101,7 @@
 | counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
 | configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |
 | context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
-| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| contract | 约定 | | | 如：`pairing contract` →`配对约定` |
 | Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
 | Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
 | crash recovery | 崩溃恢复 | | | |
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
index a32bb0e3e6..225a3f494b 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0003-web-agent-gui-feedback-loop.md
 0003-web-agent-gui-feedback-loop.md: 13d13a607babfe7f5ddfdb6773c94f973bbef0db
-0003-web-agent-gui-feedback-loop.zh.md: f80530605ef9274638c6848bf5a256f76057915c
+0003-web-agent-gui-feedback-loop.zh.md: 84c9043ce2e286512483c99c2e23ebdc99cb49b2
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
index f80530605e..84c9043ce2 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
@@ -31,7 +31,7 @@ Web agent 修改了 GUI 源码，却不知道由哪个 URL 和进程承载当前
 
 ## 根因
 
-Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久契约将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
+Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久约定将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
 
 裸 Vite 返回 HTTP 200，使错误的启动路径看似合理。`window.__DSH_BOOT__` 只由完整宿主注入，因此传输层就绪不代表应用已就绪。首个回归测试以另一种方式重复了同样的错误：超时机制终止 Vite 后，非零退出断言仍会通过。真实复现暴露了这一误报。
 
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
index b54453f3c4..8c66e9464c 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
 0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198
-0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231
+0004-landlock-partial-notice-misclassified-child-failures.zh.md: 55b462a4fe90b5d5c98bf846cad55e1fe4d6a4b0
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
index 5cf3e4422a..55b462a4fe 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
@@ -10,7 +10,7 @@ Status: resolved
 
 ## 概述
 
-原生 launcher 契约区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
+原生 launcher 约定区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
 
 harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情况。消费方只要发现非零退出同时携带该子串，就会归类为 runner 失败。因此，子进程的退出状态被错误地关联到 launcher 的信息性行：`false`、ripgrep 无匹配时的退出码 1、无效 pattern 的退出码 2，乃至由子进程自行选择的退出码 125，都可能在约束与执行均成功的情况下被错误归因为沙箱故障。
 
@@ -24,8 +24,8 @@ harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情
 
 ## 时间线
 
-- 原生 launcher 契约规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
-- 沙箱提供方把该契约简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
+- 原生 launcher 约定规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
+- 沙箱提供方把该约定简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
 - 单元测试覆盖了无诊断的成功、拒绝诊断和致命 runner 前缀。真实 runner 测试在没有可用内核时会自行跳过，也没有强制构造「部分强制执行通知后跟非零子进程退出」的情况。
 - 一个最小 POSIX 包装脚本会打印该通知并 `exec` 其负载；它通过 `false` 与 ripgrep 无匹配场景复现了故障。
 - 结构化规则、前台与后台共享的分类逻辑和组装后的回放覆盖共同弥补了仍然存在的沙箱归因缺口。文件系统搜索通过 `ctx.subprocess` 运行打包的 ripgrep；本修复让该路径继续位于沙箱化 bash 之外。
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index f1636e0191..b741c1cdf8 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
 README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
-README.zh.md: dda61d86c4d00117af851b4a55d16b97c6bc2f10
+README.zh.md: 04e07cc9c8b8b16c69bb09344e8533729525fe5c
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index dda61d86c4..04e07cc9c8 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,8 +6,8 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截契约，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
-| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截约定，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
 | [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
@@ -18,15 +18,15 @@
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方约定 |
 | [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
 | [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
-| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
+| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 约定 |
 | [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
 | [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
-| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
+| [pty.md](pty.md) | 持久化终端 ID、后端/会话约定、发送就绪状态、有界读取与 owner 可见快照 |
 | [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
 | [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
 | [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
@@ -37,15 +37,15 @@
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
-| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 契约、consumer 视图、`ctx.tasks` 服务行为 |
+| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 约定、consumer 视图、`ctx.tasks` 服务行为 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index f6ed20cace..6f035bdbd5 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/bash.md
 bash.md: dd7649ce46bea5642270fa553eb3d82f2dc33e9b
-bash.zh.md: bba9ece2955cee66e941aa878299cff6c06a97a0
+bash.zh.md: e3c607cb1599da97cb69369a34135abc310387ed
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index bba9ece295..e3c607cb15 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -218,7 +218,7 @@ interface BashProcessRead {
 
 ## 服务
 
-`BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[进程管理器](subprocess.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。`dsh-bash` 拥有 shell 工具共享的退出状态契约：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。
+`BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[进程管理器](subprocess.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。`dsh-bash` 拥有 shell 工具共享的退出状态约定：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 05e7e67ed1..3caad2c5f7 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/code-runtime.md
 code-runtime.md: 12779f1aafc8930410ae0d695e3f617caafcf607
-code-runtime.zh.md: de563dd3430348f5cf3675d4bf124adeba170559
+code-runtime.zh.md: 0bb18aaafff5a9b390685ee4c93a67f3f15502d5
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index de563dd343..0bb18aaaff 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -2,7 +2,7 @@
 
 [English](code-runtime.md) | 中文
 
-代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其接口（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread 后端与工具注册表消费方的契约见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回契约](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
+代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其接口（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread 后端与工具注册表消费方的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
 
 源码：[`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
@@ -36,7 +36,7 @@ interface CodeRunRequest {
 }
 ```
 
-结果将错误报告为一个**字段**，而不是让 `run()` 返回被拒绝的 Promise。报告程序失败是调用方的职责，不走异常路径（与 `BashExecutor.run` 失败时仍正常完成的契约一致）：
+结果将错误报告为一个**字段**，而不是让 `run()` 返回被拒绝的 Promise。报告程序失败是调用方的职责，不走异常路径（与 `BashExecutor.run` 失败时仍正常完成的约定一致）：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 86348bad3a..ed13dea399 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/compaction.md
 compaction.md: 5aef839192ea6f67bb409622187fe65fed795e73
-compaction.zh.md: 63b28518e68f71cc648d2f4e78a82bc5beafb621
+compaction.zh.md: 20b4b2381f6e638e1d1b4db13ba98d53379b38db
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 63b28518e6..20b4b2381f 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -81,7 +81,7 @@ type ManualCompactionErrorCode =
 
 压力压缩在串行 `agent/pre-step` 中运行，先于请求推导。一旦压力或规范化溢出满足条件，compact-basic 会在选择范围前调用可选的 [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md)，再通过 `ctx.tokenMeter` 重新测量，并且可以在不生成摘要的情况下推进 surface。失败请求的恢复在失败的步骤关闭后通过 `agent/request-error` 运行；仅当 surface replacement generation 前进时才返回重试动作，即便后续摘要工作在剪枝后抛异常亦如此；取消仍然优先。区域边界保持工具调用/结果配对，但不保持整个轮次，因此一个过大轮次中较早关闭的步骤可以被压缩。`dsh-compact-basic` 拥有阈值、保留尾部策略、溢出上限与失败处理。
 
-该 seam 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包契约](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
+该 seam 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包约定](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
 
 ## 工具结果剪枝产出
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index caf9356ee9..42f00a896e 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 6878300dc2cbd82d220e17d2d6f5e1009f41c48f
+core.zh.md: 96854801d684509d4d77b6408a4bb45b93438cdb
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 6878300dc2..96854801d6 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,7 +2,7 @@
 
 [English](core.md) | 中文
 
-**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截契约——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截约定——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
 
 ## 主干逐包速览
 
@@ -14,7 +14,7 @@
 | `system-prompt/` | 提示词段落与工具 schema 组装（`ctx.systemPrompt`） | [system-prompt.md](system-prompt.md) |
 | `tools/` | 带作用域的工具注册表与受保护的执行流水线（`ctx.tools`） | [tools.md](tools.md) |
 | `agent/` | `Agent` 接口、实时注册表、发起者作用域与 `agent/*` 事件词汇（`ctx.agents`） | 本页 |
-| `agent-loop/` | 实现公开 `Agent` 契约的具体 driver（`ctx.agentLoop`） | 本页 |
+| `agent-loop/` | 实现公开 `Agent` 约定的具体 driver（`ctx.agentLoop`） | 本页 |
 | `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
 `scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
@@ -50,7 +50,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
 
-`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚契约见下方[生成区块](#ctxagents--agentregistry)。
+`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
 <a id="the-agent-handle"></a>
 
@@ -206,7 +206,7 @@ type AgentCancelCause =
 
 cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
-[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
+[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
 <a id="initiating-agent"></a>
 
@@ -255,7 +255,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## `ToolDefinition`
 
-唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的约定。
 
 其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
 
diff --git a/docs/subsystems/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
index 945ed658d2..cdd932726e 100644
--- a/docs/subsystems/goal.i18n.yaml
+++ b/docs/subsystems/goal.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/goal.md
 goal.md: 6f54a5261cb44c3fda389e37cb689a00061ab241
-goal.zh.md: 043263f3231b4c727f21ca0b8fc07d8adffa0559
+goal.zh.md: ea5a0fe7923648aead5e6f54ab31162a7abdb954
diff --git a/docs/subsystems/goal.zh.md b/docs/subsystems/goal.zh.md
index 043263f323..ea5a0fe792 100644
--- a/docs/subsystems/goal.zh.md
+++ b/docs/subsystems/goal.zh.md
@@ -142,7 +142,7 @@ interface GoalChanged {
 
 ## 服务行为
 
-[`GoalService`](../../packages/goal/goal/src/index.ts) 解析创建默认值、从持久 `goal/change` 事件执行严格回放折叠、校验确切的活跃 agent 身份、以比较并设置方式执行变更，并发出 `goal/changed` 通知；监听器故障会被隔离。包 [README](../../packages/goal/goal/README.md) 负责记录可调用契约和面向模型的契约。
+[`GoalService`](../../packages/goal/goal/src/index.ts) 解析创建默认值、从持久 `goal/change` 事件执行严格回放折叠、校验确切的活跃 agent 身份、以比较并设置方式执行变更，并发出 `goal/changed` 通知；监听器故障会被隔离。包 [README](../../packages/goal/goal/README.md) 负责记录可调用约定和面向模型的约定。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 572039f635..6f61102676 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
 http-server.md: b9795fe98b432b6ef5f7d01a4d3e115c809fe642
-http-server.zh.md: b84ea457bcd37eed361fde88fbf680d189aeebfb
+http-server.zh.md: 8d55c48ae2882bd471ca4e64e011c7d79c4ebb40
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index b84ea457bc..8d55c48ae2 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -42,7 +42,7 @@ interface Config {
 
 ## 服务
 
-`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
+`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层约定，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
 
 处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包（package）从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
 
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 8ef657b3a4..23364aacc1 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/invariants.md
 invariants.md: 184d982bb27ab3ff98f715f0751c8bfcc1d08bea
-invariants.zh.md: bd2f83a018642832fe50ba5cca6dd82e2bd7d59b
+invariants.zh.md: e79b1c90a1c6284691404411ad9fa8ce62ef7e5e
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index bd2f83a018..e79b1c90a1 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -54,9 +54,9 @@ interface InvariantInstaller {
 
 `ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默地认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于配套插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此配套插件可以重载并再次注册同一名称，不留残余状态。
 
-## 配套插件契约
+## 配套插件约定
 
-每个工作区包都拥有一个 `./invariant` 配套插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
+每个工作区包都拥有一个 `./invariant` 配套插件（[包约定](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index f807656000..a54224c867 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: c65416f449d1783f398cdd81b0d6987de83a6141
-llm-streaming.zh.md: ce79ecca53edf7213853df118489817451baa7b0
+llm-streaming.zh.md: 08b627b41090e99d9a581758a593dc6d4dbf4dd7
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index ce79ecca53..08b627b410 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -2,7 +2,7 @@
 
 [English](llm-streaming.md) | 中文
 
-[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
+[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器约定（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
 
 源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
@@ -202,7 +202,7 @@ interface LlmFailure {
 }
 ```
 
-## 适配器契约
+## 适配器约定
 
 每个适配器必须遵守以下规则，每个消费方可以依赖它们：
 
@@ -216,7 +216,7 @@ interface LlmFailure {
 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
 
-该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
+该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
 ## `ResolvedRetryPolicy`
 
@@ -224,7 +224,7 @@ interface LlmFailure {
 
 ## `AppIdentity`：应用归属
 
-每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该约定有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
 ```ts type-equiv
 /**
@@ -504,7 +504,7 @@ interface GenerateOptions {
 }
 ```
 
-模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](#llmfailure)：
+模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式约定的 [`LlmFailure`](#llmfailure)：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 295e5392ca..e892317427 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
 persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
-persistence.zh.md: 6676bf26e6eb0fb8f7dd9a94d17d4d70d1d1b271
+persistence.zh.md: 4ff9da19e8127c15e73f822b14adb41a5a1658b0
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 6676bf26e6..4ff9da19e8 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index efbd158e18..a6f8fd2609 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/sandbox.md
 sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
-sandbox.zh.md: f526982a782144a0bf58abcde5d883e9dc813369
+sandbox.zh.md: 23644bb43a131a0e3c8595187a6fc11e74682d9e
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index f526982a78..23644bb43a 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -143,7 +143,7 @@ interface ConfinedArgv {
 
 ## 提供方与 fail-closed 错误
 
-`ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。消费方也可以在 spawn 或观察所返回的 argv 时对失败进行分类；该归因属于消费方契约。对于受限策略，静默的无隔离透传永远不合法。
+`ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。消费方也可以在 spawn 或观察所返回的 argv 时对失败进行分类；该归因属于消费方约定。对于受限策略，静默的无隔离透传永远不合法。
 
 提供方选择、探测、缓存和后端专有的强制执行报告归[本地提供方](../../packages/sandbox/sandbox-local/README.md)所有。
 
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index fc603d658d..98efe87541 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-projection.md
 session-projection.md: 64351195028c62f623b32cbeb80c952795c1e9e6
-session-projection.zh.md: cf9036e6db3f82d84ffa3b8aa809c5617409659a
+session-projection.zh.md: e4a03c6719095cc342d914612faf364fc48e4fa0
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index cf9036e6db..e4a03c6719 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-projection.md) | 中文
 
-会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流契约：[包（package）README](../../packages/session/session-projection/README.md)。
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
 
 源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index c1466bdcfc..a73c858289 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-reference.md
 session-reference.md: f539a59b8d26182aff9746b6d6a39a86ba15cb45
-session-reference.zh.md: 82b6a6c5ec5c91372fc6a43b73ad1572fccf5b3a
+session-reference.zh.md: 1035614141936af1f94bdabe35b3104be319a762
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 82b6a6c5ec..1035614141 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-reference.md) | 中文
 
-结构化的跨会话引用请求与准备后的消息上下文。[包契约](../../packages/context/session-reference) 负责规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
+结构化的跨会话引用请求与准备后的消息上下文。[包约定](../../packages/context/session-reference) 负责规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
 
 来源：[`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 2389cc806c..6f28409864 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session.md
 session.md: 7735e90807f6fce1b3645096437b3e86189dc8ec
-session.zh.md: 09f34ac19c2f685bf5f8e5b11355b4c642c584d0
+session.zh.md: 63eb460f7ef300decf3e32c0ace16b354606c271
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 09f34ac19c..63eb460f7e 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -177,7 +177,7 @@ interface EpochHeader {
 
 ### 路由容量事件：`request/context`
 
-请求所解析到的路由的上下文元数据是独立的已记录状态，在同一步骤内紧随 `request/header` 追加，且仅在提供方、模型或容量与上一条记录不同时追加。它保持在 `EpochHeader` 之外，因为该类型是由 `headerEquals` 逐字段比较的重建契约：容量描述的是路由，不是请求输入，把它折叠进去会让一次容量变化被登记为请求信封的 `change`，也会把适配器元数据拉进 loop 的重建不变式。与 `request/header` 一样，它不是 `SurfaceEventType`，也不产生 LLM 消息。`session.requestContext()` 以增量方式归并最新一条记录。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，因此新记录可以清除较早路由的容量。
+请求所解析到的路由的上下文元数据是独立的已记录状态，在同一步骤内紧随 `request/header` 追加，且仅在提供方、模型或容量与上一条记录不同时追加。它保持在 `EpochHeader` 之外，因为该类型是由 `headerEquals` 逐字段比较的重建约定：容量描述的是路由，不是请求输入，把它折叠进去会让一次容量变化被登记为请求信封的 `change`，也会把适配器元数据拉进 loop 的重建不变式。与 `request/header` 一样，它不是 `SurfaceEventType`，也不产生 LLM 消息。`session.requestContext()` 以增量方式归并最新一条记录。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，因此新记录可以清除较早路由的容量。
 
 ```ts type-equiv
 /** Registration-bound metadata for one resolved model route. */
@@ -585,11 +585,11 @@ interface TurnEndReasonMap {
 
 钩子桥接层的 `hook/invoked` / `hook/result` 溯源对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
-## 持久性契约
+## 持久性约定
 
-持久化后端依赖的契约如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.events` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
+持久化后端依赖的约定如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.events` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
 
-消费此契约的后端见 [persistence.md](persistence.md)。
+消费此约定的后端见 [persistence.md](persistence.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 84628f50b7..570dfe223f 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/skills.md
 skills.md: 78d510fafca0017b9528a215270172a74e9b0de1
-skills.zh.md: e88c9f1ba190eb1e90966d35c7dcc2eb86ecd6cc
+skills.zh.md: 12e51c45a779e3ca0634db62ac9adfe69112d09f
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index e88c9f1ba1..12e51c45a7 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -211,7 +211,7 @@ interface Config {
 }
 ```
 
-## 会话目录与工具契约
+## 会话目录与工具约定
 
 `dsh-tool-skill` 在存活会话中第一个观察到非空完整视图的 `agent/pre-step` 注入初始的持久 user-role `<system-reminder>`。目录只包含已排序的 skill `name` 和规范化、经 XML 转义的 `description`；不包含正文、路径、来源、提供方或路由提示。发现通过 `SkillLookupOptions` 转发该步骤的 abort signal。`catalogDescriptionMaxLength` 是消费方用于 description 上限的配置，默认值为 `500`，整数最小值为 `3`。
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 98092af5b3..3d8db33ada 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/storage.md
 storage.md: 52dc84b699921e911276ce5214bc975abfd22fa4
-storage.zh.md: f614b77153e835264e1650515946a9d2acf70e57
+storage.zh.md: 89ff7f69ed43b55101be834c21d11cf74ca2340b
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index f614b77153..89ff7f69ed 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -44,7 +44,7 @@ interface StorageBackend {
 }
 ```
 
-一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性契约，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
+一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
 
 ## 声明领域
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 994c04eaa5..9ecb6e4628 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
 subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
-subagent.zh.md: ddc3a715fbb6589dffc38f0e0c8b23bf35dddf6e
+subagent.zh.md: 37b274d7f3ffa5b5aadea773d29f7e6b4e5a833b
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ddc3a715fb..37b274d7f3 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -259,13 +259,13 @@ interface ContinuableCreateSpec {
 }
 ```
 
-描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果契约，而非持久化身份）。
+描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果约定，而非持久化身份）。
 
 本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index a3071e98a9..4c63f77618 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md
 subprocess.md: 0bc2bf86518bcc60bef02554b94471425f2ac433
-subprocess.zh.md: 5d6425707edcf1952c25dbdc91dbf7aab3779350
+subprocess.zh.md: 7e27bf15dfe0cdde09459dbfb239ab25ccde126a
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 5d6425707e..7e27bf15df 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -246,7 +246,7 @@ interface SubprocessOutcome {
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
index a1e14385f4..a7a5e5a6d0 100644
--- a/docs/subsystems/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
 system-prompt.md: 94ce40f8bf98dd4efe3514879c2527c2a7bd3b21
-system-prompt.zh.md: 37d366774089f91756433602a719e99b57747c17
+system-prompt.zh.md: c46ee6e2b70c6603500bd9061ed09b805ed61630
diff --git a/docs/subsystems/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
index 37d3667740..c46ee6e2b7 100644
--- a/docs/subsystems/system-prompt.zh.md
+++ b/docs/subsystems/system-prompt.zh.md
@@ -39,7 +39,7 @@ interface ToolProviderResult {
 
 ## 提示词段落
 
-`PromptSection` 是一份只读的同进程注册契约。其文本可以是静态的，也可以从当前组装上下文动态解析。
+`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的，也可以从当前组装上下文动态解析。
 
 ```ts type-equiv
 /** One contributed section of the system prompt (registry input). */
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index d28dcc2781..d1110928e7 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tasks.md
 tasks.md: 6237607307cbab8511f968ed591e3e3b8b845c6a
-tasks.zh.md: 99a6fcc4f54c1b52e5c6fd393327cc768f064297
+tasks.zh.md: c73765b4d5ad0309f3473890557171af21527682
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index 99a6fcc4f5..c73765b4d5 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -21,7 +21,7 @@ interface TaskKindMap {
 
 `TaskStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实归入 `TaskSnapshot.detail`。
 
-## 生产方契约
+## 生产方约定
 
 `TaskStart` 声明身份和启动器。运行时会在调用 `run()` 前完成预检，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问权限和生命周期状态。
 
@@ -151,7 +151,7 @@ interface TaskRead {
 
 ## 服务行为
 
-抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 契约见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 19cd6f6851..d520d56dcf 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/telemetry.md
 telemetry.md: 131c5814f29d70c356989e62fda1db5c1c5448d6
-telemetry.zh.md: 5d4a9d9994457bc06a9e4194c4807f88789a3cf0
+telemetry.zh.md: 147418000f240093f356fe9033612967f8e29ffb
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 5d4a9d9994..147418000f 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -2,7 +2,7 @@
 
 [English](telemetry.md) | 中文
 
-对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/session/session-telemetry/README.md)。
+对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [seam README](../../packages/session/session-telemetry/README.md)。
 
 源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
@@ -56,7 +56,7 @@ interface TelemetryRecord {
 
 每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端对 ledger 记录基于 `(session.id, event.seq)` 去重；ops 记录刻意省略这类标识——它们是用于告警的信号，而非用于累加的条目，重复被容忍而非被去重。
 
-## 后端契约
+## 后端约定
 
 ```ts type-equiv
 /**
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 21003bb796..77c413c7ff 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
 tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
-tools.zh.md: 50843b07f1d98b1c9d9222288b1273b34bee1e4a
+tools.zh.md: b2aa3d2b192f82c08b4a8e7931008a768fd04adf
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 50843b07f1..b2aa3d2b19 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -148,7 +148,7 @@ type InferArgs<S> = InferProperties<S, []>
 
 `defineTool({ name, description, parameters, output, execute, … })` 将参数推导与 `parameterSchemaSpecToJsonSchema()` 和 `validateArgs()` 绑定，并将 `execute`/`render`/`presentationMeta` 与 `InferValue<OutputSchema>` 绑定。Schema 记录只包含自有且可枚举的字符串键，schema 数组是稠密的内建数组，因此推导、编译与校验观察到的是同一份声明。精确推导保持到 16 层容器，之后放宽为 `JsonValue`；运行时校验仍会继续遍历完整 schema。`valueSchemaSpecToJsonSchema()` 通过同一套已强制执行的原始子集编译输出声明。参数不匹配时抛出 `ToolArgsError`（`INVALID_ARGS`）；函数体或后置策略产生的值无效时抛出 `ToolOutputError`（`INVALID_TOOL_OUTPUT`）。两者都经由常规工具错误路径处理。原始 JSON Schema 默认保持开放；不支持的关键字会被拒绝，而不会在未强制执行的情况下获准进入。
 
-注册是一个受信任的同进程契约。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
+注册是一个受信任的同进程约定。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
 
 ## `ToolRestriction` — 单个作用域的实时全局过滤器
 
@@ -243,7 +243,7 @@ type ToolExecutionMode =
   | { kind: 'exclusive' }
 ```
 
-Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型契约均不受影响）：
+Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型约定均不受影响）：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index b8fdb092f2..54d300d028 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
 typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
-typert.zh.md: ff6b45a517c75392ee87fa348d72bfae6cdf1efb
+typert.zh.md: 49ad64fbcfdee2d18662fe383335f61236258717
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index ff6b45a517..49ad64fbcf 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -2,7 +2,7 @@
 
 [English](typert.md) | 中文
 
-以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共契约的字面定义。
+以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共约定的字面定义。
 
 ## Lookup 与 Context 声明
 
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index f3f0ab9758..b22cd94946 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/web.md
 web.md: f300bf2daef172fe4a69c00f36c804cf874c189d
-web.zh.md: 0c72e343c1b6ea5de8e7c296014da35b0291a33b
+web.zh.md: 36afee9a964a0ad185242d5ee8f4f91689b1d295
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 0c72e343c1..36afee9a96 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -128,7 +128,7 @@ type WebFetchBody =
 
 ## 错误
 
-`WebError extends HarnessError`（[core.md](core.md) 错误分类体系），带有 `code: string`（开放式，与其他 seam 的错误一致——`LlmError`、`SubagentError`），而非封闭联合类型：提供方可以在不修改 `dsh-web` 的情况下抛出自己的错误代码，消费方必须容忍未知错误代码。错误代码按所有者划分。由 seam 统一定义的错误代码来自 `WebService` 的选择逻辑和共享契约：`WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`、`WEB_DUPLICATE_PROVIDER`（注册时的编程错误，类似 `LlmService` 的 `DUPLICATE_ADAPTER`）、`WEB_ABORTED`，以及 `WEB_PROVIDER_ERROR`（提供方自身故障经 seam 暴露时使用的兜底代码，包括 DNS、连接被拒绝、TLS 等网络或传输故障）。抓取传输层错误代码由 `dsh-web-fetch-local` 实现拥有，不同的抓取后端无需抛出它们：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
+`WebError extends HarnessError`（[core.md](core.md) 错误分类体系），带有 `code: string`（开放式，与其他 seam 的错误一致——`LlmError`、`SubagentError`），而非封闭联合类型：提供方可以在不修改 `dsh-web` 的情况下抛出自己的错误代码，消费方必须容忍未知错误代码。错误代码按所有者划分。由 seam 统一定义的错误代码来自 `WebService` 的选择逻辑和共享约定：`WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`、`WEB_DUPLICATE_PROVIDER`（注册时的编程错误，类似 `LlmService` 的 `DUPLICATE_ADAPTER`）、`WEB_ABORTED`，以及 `WEB_PROVIDER_ERROR`（提供方自身故障经 seam 暴露时使用的兜底代码，包括 DNS、连接被拒绝、TLS 等网络或传输故障）。抓取传输层错误代码由 `dsh-web-fetch-local` 实现拥有，不同的抓取后端无需抛出它们：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
 
 ## 服务
 
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 0b7cdfdc76..fca76bf305 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/testing.md
 testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
-testing.zh.md: e9182495fbdbb1458c9ff5b30a9591f8b70f27c5
+testing.zh.md: 14b2549c4c3556b6d3bdd5b39d01dee885559dd1
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index e9182495fb..14b2549c4c 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -6,10 +6,10 @@
 
 ## 层级
 
-- **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性契约回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
+- **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性约定回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/bash/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其 executor 套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。
 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。
-- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输契约与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
 签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
@@ -42,7 +42,7 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个示例或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。
 - 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。
-- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一契约。
+- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一约定。
 
 ## 何时需要快照测试
 
diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml
index 37dd601646..d6bb924fc7 100644
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/docs/user/develop/framework/events.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/framework/events.md
 events.md: c70150b4d9070063513021e420f253ff6d4e5de1
-events.zh.md: 813dc3631e0c776ad9c8763db65eebc3f2167578
+events.zh.md: b3b79a86d249eed0df15380e17a1ee71766b1a72
diff --git a/docs/user/develop/framework/events.zh.md b/docs/user/develop/framework/events.zh.md
index 813dc3631e..b3b79a86d2 100644
--- a/docs/user/develop/framework/events.zh.md
+++ b/docs/user/develop/framework/events.zh.md
@@ -22,7 +22,7 @@ ctx.emit('event-name', payload)
 
 ## 事件模式
 
-Cordis 提供多种事件模式，适用于不同的交互契约：
+Cordis 提供多种事件模式，适用于不同的交互约定：
 
 ### emit — 广播
 
diff --git a/docs/user/develop/practice/llm-adapter.i18n.yaml b/docs/user/develop/practice/llm-adapter.i18n.yaml
index 7ea31ce419..a7a745faaf 100644
--- a/docs/user/develop/practice/llm-adapter.i18n.yaml
+++ b/docs/user/develop/practice/llm-adapter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/llm-adapter.md
 llm-adapter.md: 7445688530c1ba61e5c065f9f5e49db6498da5b1
-llm-adapter.zh.md: e491bc0b6ef633b0b40cb094faf07fc84445c026
+llm-adapter.zh.md: c726735ff2679584d1c061ef8acddc8981dadd26
diff --git a/docs/user/develop/practice/llm-adapter.zh.md b/docs/user/develop/practice/llm-adapter.zh.md
index e491bc0b6e..c726735ff2 100644
--- a/docs/user/develop/practice/llm-adapter.zh.md
+++ b/docs/user/develop/practice/llm-adapter.zh.md
@@ -150,7 +150,7 @@ ctx.llm.registerAdapter(['model-name-1', 'model-name-2'], adapter)
 - `packages/llm/llm-deepseek/` — DeepSeek API 适配器（OpenAI 兼容格式）
 - `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式）
 
-对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。
+对比这两个已交付的适配器，可以看到同一套 harness 约定如何在不同提供方 SDK 之上实现。
 
 ## 错误处理
 
diff --git a/docs/web-styling.i18n.yaml b/docs/web-styling.i18n.yaml
index 0cbbafeec9..55277809ef 100644
--- a/docs/web-styling.i18n.yaml
+++ b/docs/web-styling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/web-styling.md
 web-styling.md: 5296cc7f83f712532262eadda6da098ae9f63ec7
-web-styling.zh.md: 6beec368f2f7fd5eb7606acfaae315d56899c739
+web-styling.zh.md: bec623911269cbd7020c26d5574ee88ca074b5d8
diff --git a/docs/web-styling.zh.md b/docs/web-styling.zh.md
index 6beec368f2..bec6239112 100644
--- a/docs/web-styling.zh.md
+++ b/docs/web-styling.zh.md
@@ -8,7 +8,7 @@
 
 [`ui-theme`](../packages/client/ui-theme/README.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
 
-全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现契约时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
+全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
 
 ## 组件规则
 
@@ -16,10 +16,10 @@
 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
 - 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
-- 当组件契约要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
+- 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 
 ## 变更系统
 
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式契约发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
+在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
diff --git a/examples/acp-agent/README.i18n.yaml b/examples/acp-agent/README.i18n.yaml
index cf9fee7334..a626a736df 100644
--- a/examples/acp-agent/README.i18n.yaml
+++ b/examples/acp-agent/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 examples/acp-agent/README.md
 README.md: 61c6efafe9dde4f91385beebdfd426c57006187b
-README.zh.md: 6eaf9fb5a91c737254e785d8601961b547e4e9ca
+README.zh.md: bd1b0e2200271a71074fbb2475167c25eb309d77
diff --git a/examples/acp-agent/README.zh.md b/examples/acp-agent/README.zh.md
index 6eaf9fb5a9..bd1b0e2200 100644
--- a/examples/acp-agent/README.zh.md
+++ b/examples/acp-agent/README.zh.md
@@ -15,10 +15,10 @@ pnpm run demo:code-mode       # same protocol with the Code Mode tool transport
 
 Stdout 只携带以换行分隔的 ACP JSON-RPC。`@deepseek-ai/dsh-acp-demo` 不安装 stdout logger；该叶节点新增的组件必须使用 stderr 输出诊断信息。
 
-自动化契约（支持的方法、基线提示词内容、已提交文本输出，以及有意缺少的 UI 界面）位于 [`@deepseek-ai/dsh-acp`](../../packages/acp/acp/README.md)。
+自动化约定（支持的方法、基线提示词内容、已提交文本输出，以及有意缺少的 UI 界面）位于 [`@deepseek-ai/dsh-acp`](../../packages/acp/acp/README.md)。
 
 ## 会话 workspace 与权限
 
-每次 `session/new` 都提供一个绝对 `cwd`。受沙箱限制的 bash 和文件系统修改会以该会话 cwd 为基准应用 `workspace-write`，因此并发会话可以使用不同的项目根目录；平台临时根目录仍是共享可写暂存空间（参见[沙箱契约](../../packages/sandbox/sandbox/README.md)）。`DSH_PERMISSION_MODE` 为部署选择 `workspace-write` 或 `danger-full-access`。
+每次 `session/new` 都提供一个绝对 `cwd`。受沙箱限制的 bash 和文件系统修改会以该会话 cwd 为基准应用 `workspace-write`，因此并发会话可以使用不同的项目根目录；平台临时根目录仍是共享可写暂存空间（参见[沙箱约定](../../packages/sandbox/sandbox/README.md)）。`DSH_PERMISSION_MODE` 为部署选择 `workspace-write` 或 `danger-full-access`。
 
 在 `workspace-write` 下，如果模型重试请求更广泛的沙箱访问权限，就会触发 `session/request_permission`，选项为 `allow_once` 和 `reject_once`。客户端以程序方式决策；客户端放弃选择或无法给出答复时，系统会按拒绝处理。选定结果仅适用于该次重试，并通过常规工具结果／审计路径记录。服务器绝不公开权限选择器，也不持久化客户端策略。
diff --git a/examples/web-cordis/README.i18n.yaml b/examples/web-cordis/README.i18n.yaml
index 86cc276a4e..d2004a499c 100644
--- a/examples/web-cordis/README.i18n.yaml
+++ b/examples/web-cordis/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 examples/web-cordis/README.md
 README.md: 21fe0a210b2e591a96dc254014a0f91ed9afa2ba
-README.zh.md: 35158affd5cbdd6f8fa7f5910500f21c2b241309
+README.zh.md: b3fecb4312dbcbaeff460a21f1d2db6b5288f9ad
diff --git a/examples/web-cordis/README.zh.md b/examples/web-cordis/README.zh.md
index 35158affd5..b3fecb4312 100644
--- a/examples/web-cordis/README.zh.md
+++ b/examples/web-cordis/README.zh.md
@@ -18,4 +18,4 @@ pnpm run demo:cordis
 pnpm run demo:cordis acp
 ```
 
-这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
+这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全约定由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index 2189d62b3c..58e58a26fe 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/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 native/landlock-run/README.md
 README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
-README.zh.md: c994087317be54d522d965de3e120da6fabb7ded
+README.zh.md: 6ae8d7d1d5ae4f2bda90cbf6aa74321a0dab3cb9
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index c994087317..6ae8d7d1d5 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 [Landlock](https://landlock.io/)「先限制自身、再执行」启动器，用于在 Linux 上限制子进程。它以按平台预构建的 npm 包以及一个轻量 JS 入口包的形式发布；入口包负责解析二进制文件并遵循其 CLI（命令行界面）契约。该启动器面向需要让不可信命令在文件系统允许清单约束下运行、同时保持自身不受限制的 agent harness（智能体框架）和其他宿主。
+一个 [Landlock](https://landlock.io/)「先限制自身、再执行」启动器，用于在 Linux 上限制子进程。它以按平台预构建的 npm 包以及一个轻量 JS 入口包的形式发布；入口包负责解析二进制文件并遵循其 CLI（命令行界面）约定。该启动器面向需要让不可信命令在文件系统允许清单约束下运行、同时保持自身不受限制的 agent harness（智能体框架）和其他宿主。
 
 第一个工具是 **`landlock-run`**：一个「先限制自身、再执行」的 [Landlock](https://landlock.io/) 启动器（基于原始内核 UAPI 编写，约 300 行 C11，并与 musl 静态链接）。它在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此命令及其产生的每个进程都在限制下运行，调用进程仍不受限制。它采用失败闭合：如果内核无法强制执行，则不运行命令并直接退出。
 
@@ -41,7 +41,7 @@ if (probe(launcher) !== 'unusable') {
 - `grantArgs({ readOnly?, readWrite? })`：启动器的授权 argv；未授予的一切都被拒绝。
 - `LAUNCHER_BIN` 和 `LAUNCHER_FAILURE_EXIT`（125）：约定常量。成功完成 exec 的子进程也可能返回 125，因此消费方必须同时看到致命诊断和该状态，才能将结果归因为启动器失败。
 
-完整的二进制契约（argv 语法、退出码、报告行）锁定在 [docs/cli-contract.md](docs/cli-contract.md) 中。
+完整的二进制约定（argv 语法、退出码、报告行）锁定在 [docs/cli-contract.md](docs/cli-contract.md) 中。
 
 ## 支持范围
 
diff --git a/native/landlock-run/packages/entry/README.i18n.yaml b/native/landlock-run/packages/entry/README.i18n.yaml
index 7c67f49670..1a701c02bc 100644
--- a/native/landlock-run/packages/entry/README.i18n.yaml
+++ b/native/landlock-run/packages/entry/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 native/landlock-run/packages/entry/README.md
 README.md: fff722428c5d213d9fcce0ee87a1d48cdc189884
-README.zh.md: f462fbe3cb0cb8d1d83b4d6b1d8e2f61e88ff69c
+README.zh.md: cbf867d9dd3551a12b74b19a6ceaf2be3e1c53a6
diff --git a/native/landlock-run/packages/entry/README.zh.md b/native/landlock-run/packages/entry/README.zh.md
index f462fbe3cb..cbf867d9dd 100644
--- a/native/landlock-run/packages/entry/README.zh.md
+++ b/native/landlock-run/packages/entry/README.zh.md
@@ -13,6 +13,6 @@ if (probe(launcher) !== 'unusable') {
 }
 ```
 
-启动器在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此整个进程树都在限制下运行。未授予的一切都被拒绝；启动器失败时以 `125` 退出且不运行命令：采用失败闭合策略，绝不在失败时放行。二进制契约锁定在仓库的 `docs/cli-contract.md` 中；C 源码作为 `src/main.c` 随该 tarball 分发，便于审计。
+启动器在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此整个进程树都在限制下运行。未授予的一切都被拒绝；启动器失败时以 `125` 退出且不运行命令：采用失败闭合策略，绝不在失败时放行。二进制约定锁定在仓库的 `docs/cli-contract.md` 中；C 源码作为 `src/main.c` 随该 tarball 分发，便于审计。
 
 平台包（由 `os`/`cpu` 选择的可选依赖，内部不含 JavaScript）：`@deepseek-ai/node-addon-landlock-run-linux-x64`、`@deepseek-ai/node-addon-landlock-run-linux-arm64`。在缺少对应包的宿主上，`launcherPath()` 返回一个固定但不存在的路径，`probe()` 报告 `'unusable'`；系统有意不提供安装时编译回退。
diff --git a/packages/acp/acp/README.i18n.yaml b/packages/acp/acp/README.i18n.yaml
index 1c8c175eb0..1b303a23a8 100644
--- a/packages/acp/acp/README.i18n.yaml
+++ b/packages/acp/acp/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/acp/acp/README.md
 README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
-README.zh.md: 4856b44683b5594ad0211af907d1a12ce814d492
+README.zh.md: eafae5602bdeb408ef548a9e706e059bd99bde17
diff --git a/packages/acp/acp/README.zh.md b/packages/acp/acp/README.zh.md
index 4856b44683..eafae5602b 100644
--- a/packages/acp/acp/README.zh.md
+++ b/packages/acp/acp/README.zh.md
@@ -17,7 +17,7 @@
 
 两个字段都是可选的，以便由另一个 agent/request 监听器提供目标。可运行的 ACP 组合同时要求两者。
 
-## 协议契约
+## 协议约定
 
 | 方法 | 行为 |
 |---|---|
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index 6a834cdf4d..e44c33641a 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/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/api/README.md
 README.md: 7c75e8012459266e0ce09c97416d140e5ac777e1
-README.zh.md: 87bd15fc4e5ad23ef785f7c9ee805a4aa1a35e46
+README.zh.md: f4e882570d2dc929cca466e0bdb05bb2943f2c93
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 87bd15fc4e..f4e882570d 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -9,9 +9,9 @@
 | [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.remote` |
 | [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
 
-运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 约定，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
 
 ## 已知限制与延期工作
 
-- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务契约。
+- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务约定。
 - 旧 API Proxy 仍位于 [`host/apiproxy`](../host/apiproxy/README.md)，作为尚未迁移到 Remote 的方法的回退路径。它使用由 `api-remotes` 持有的 Host resolver，使已迁移与旧方法共用同一套 Agent/Session 身份策略。
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 3f4cd32e4d..8e1e98774a 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/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/api/gateway/README.md
 README.md: 0e1a03d2016b8cfbe165dbf1b0a9802290b29502
-README.zh.md: 6b5ccff2340405cc0045147239c5bd4f3eead7da
+README.zh.md: f8c01b489f51fb5e78b608dd9c24a36c7bc64c3a
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 6b5ccff234..f8c01b489f 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 约定，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
@@ -20,7 +20,7 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
-生成的声明合并通过共享的 `TypeRTClientRemote` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+生成的声明合并通过共享的 `TypeRTClientRemote` 约定提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
 ## 模型体验
 
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index f8f7a6400b..68dbf6263f 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/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/api/remotes/README.md
 README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
-README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575
+README.zh.md: 12add6f8efc5b6af3e9b74b26a1abb2bb3936e0a
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
index 7490d68781..12add6f8ef 100644
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -8,7 +8,7 @@
 
 当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、可追踪 namespace Service、直接与作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 接口，不导入具体 Gateway。
 
-本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 约定，均可复用其 Client face。
 
 ## 构建边界
 
diff --git a/packages/bash/bash-env/README.i18n.yaml b/packages/bash/bash-env/README.i18n.yaml
index 47f4cf01cc..9f73734586 100644
--- 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: b6f3aca41771f1ca990a4b708cd53119b8e8ad78
+README.zh.md: e3103f32ce1d857267af9589619bed5538d2e6bf
diff --git a/packages/bash/bash-env/README.zh.md b/packages/bash/bash-env/README.zh.md
index b6f3aca417..e3103f32ce 100644
--- a/packages/bash/bash-env/README.zh.md
+++ b/packages/bash/bash-env/README.zh.md
@@ -4,7 +4,7 @@
 
 工具无关的 shell 环境插件：拥有 `ctx.bashEnv` 注册表，管理受信任的、每次执行收集的 `DSH_*` 变量，供模型可见的 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`DSH_HOME`、`DSH_SHELL=1`、`DSH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会响亮失败。
 
-包根导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
+包根导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
 
 ## Config
 
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index 43ff188d8d..e5eb0dfc41 100644
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/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/tool-bash/README.md
 README.md: 47101e1198d13518c3d82877df8726c1fbf26b82
-README.zh.md: d60ac4b3826838e875f7d43bc314f62e1453c1d9
+README.zh.md: c7e0b3ffdc02705bbbd6fd6bd9b8cce2548445f3
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index d60ac4b382..c7e0b3ffdc 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -4,9 +4,9 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具契约是 bash 方言——请挂载能解析 bash 的执行器。
+需要加载执行器实现（例如 `@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]` 标记，发现失败时先调查原因再继续。
 
@@ -28,7 +28,7 @@
 
 ### 托管 shell 环境
 
-每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表契约——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
+每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表约定——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
 
 结果文本依次包含 stdout、可选的 `[stderr]` 段落和适用的沙箱拒绝、超时、信号、退出代码及截断标记。超时与最终退出状态分别报告；非零退出仍是由模型解释的结果，不会成为 `isError`。截断结果会链接安全的完整 spill 文件，或报告文件不可用。只有 spawn 错误和中止等基础设施故障才会产生 `isError`。
 
@@ -52,7 +52,7 @@
 
 ## 逐会话模式切换
 
-对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换契约](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换约定](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 ## 模型体验
 
diff --git a/packages/bash/tool-pwsh/README.i18n.yaml b/packages/bash/tool-pwsh/README.i18n.yaml
index 39325f5987..ba4f758814 100644
--- a/packages/bash/tool-pwsh/README.i18n.yaml
+++ b/packages/bash/tool-pwsh/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/tool-pwsh/README.md
 README.md: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 17696fe6d908838aaaca12e8179f2ad9cb780210
+README.zh.md: 54614fcfad1cdec5866aa3cc96e52983f4eb1642
diff --git a/packages/bash/tool-pwsh/README.zh.md b/packages/bash/tool-pwsh/README.zh.md
index 17696fe6d9..54614fcfad 100644
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具契约是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
+注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具约定是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
 
 需要已加载的执行器实现与 `bash-env` 插件；两者都存在前工具保持 pending（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。
 
-包根只导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
+包根只导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
 
 插件还贡献 `tool:pwsh` prompt section（order 105）：非零退出以 `[exit code: N]` marker 报告，Windows 上的中断以无 signal 的 exit 1 结算。
 
@@ -120,5 +120,5 @@ ack 是固定短行；任务输出按读取有界。
 
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
 - **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
-- **PowerShell 方言契约** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
+- **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
diff --git a/packages/boot/README.i18n.yaml b/packages/boot/README.i18n.yaml
index 8f691dd089..66d3b7b63c 100644
--- a/packages/boot/README.i18n.yaml
+++ b/packages/boot/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/boot/README.md
 README.md: 5e4e483b60adab0b22ddb5279f4cd8fb699b9c35
-README.zh.md: d49afa45b9fb93f6fa83944167057f0c933cd05d
+README.zh.md: 95a3f98129a7d1fdfaffb3cac6fed77bab7cff56
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
index d49afa45b9..95a3f98129 100644
--- a/packages/boot/README.zh.md
+++ b/packages/boot/README.zh.md
@@ -8,4 +8,4 @@
 |---|---|---|
 | `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
 
-启动序列与个人配置契约见 [`app-boot/README.md`](app-boot/README.md)。
+启动序列与个人配置约定见 [`app-boot/README.md`](app-boot/README.md)。
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 98df59d988..860390d722 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/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/bundle/README.md
 README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: ef2027e347b79e14574ba1164aa9fddd364327e9
+README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index ef2027e347..b965664978 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 约定](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 7662182df0..25bf18dc45 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/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/bundle/web-app/README.md
 README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: 0ffc5cdaf1a98e5df11ef042c7d15a994515c170
+README.zh.md: bd14fe03d222f788563df0b562f86446df70b827
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index 0ffc5cdaf1..bd14fe03d2 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -10,7 +10,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### 模型看到的内容
 
-当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
+当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新约定，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
 
 #### Token 影响
 
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index 2ce3e44fa7..a6474de825 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/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/client/README.md
 README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
-README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139
+README.zh.md: 677ebc8158f5b7c63a5bc6ecc94a357e0783c378
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index edd378bf80..677ebc8158 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -37,6 +37,6 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-settings-general/`](ui-settings-general/README.md) | 提供常规设置分区。 |
 | [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
 
-每个子文档负责自身的契约和详细行为。[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)负责跨包组合与加载决策。
+每个子文档负责自身的约定和详细行为。[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)负责跨包组合与加载决策。
 
 子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index ddfda12f4e..9fca48fb8b 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
 README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
-README.zh.md: d17012cc89c02a1b11f16d126b7c0cafe67fb2a0
+README.zh.md: 9bb9405a0e7be5cdbe51b5099e33e2b85225d2fa
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index d17012cc89..9bb9405a0e 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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 浏览器信任栅栏
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 92b9e2abfc..f9af3fb8fe 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
 README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
-README.zh.md: 8ee06e93b475398750ee74d4900a8c6917cf71f5
+README.zh.md: 41c81532667f445ce1c52e1b84185ef503e82141
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 8ee06e93b4..41c8153266 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。契约：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。约定：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
 
 ## Slot 声明注入
 
diff --git a/packages/client/schema-form/README.i18n.yaml b/packages/client/schema-form/README.i18n.yaml
index 73ec057a53..9dfa981a3f 100644
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/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/client/schema-form/README.md
 README.md: 716cc7ba3c24f3a4de081e2d26f803b905235fac
-README.zh.md: 61fff15ca6a21e6267da158640e3782422e865c3
+README.zh.md: 9473620da83e73f7a095694b2321f1ebc5f9c53d
diff --git a/packages/client/schema-form/README.zh.md b/packages/client/schema-form/README.zh.md
index 61fff15ca6..9473620da8 100644
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -4,7 +4,7 @@
 
 面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 seam 侧的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包不含任何 React，也不做任何渲染。
 
-## 契约
+## 约定
 
 编辑的单元是**用户分节草稿**：一个以不可变方式编辑的普通对象（`setPath` 会物化中间对象，`deletePath` 即逐字段重置——去掉该键，解析值便回退到组合 base 与 schema 默认值）。字段只要出现在草稿中就被标记为**已覆盖**（`hasPath`）——判定采用存在性语义而非值比较，与 settings seam 的分层方式严格对应。`nodeAtPath` 解析可配置提供方目录 `settingsPath` 所寻址的 schema 节点（object 属性按名称解析，dict 条目经由 `inner`），编辑器因此可以在决定渲染什么之前，先探测某提供方的 profile 携带哪些字段（及其 `meta.role`）；无法解析的路径返回 `undefined`，调用方因此会大声降级，而不是渲染出错误的子树。`validateDraft(schema, draft)` 运行还原出的校验器并返回其失败消息，页面因此可以在写入前拒绝无效草稿。
 
diff --git a/packages/client/ui-command/README.i18n.yaml b/packages/client/ui-command/README.i18n.yaml
index 4d8ace8955..e59b4b2a12 100644
--- a/packages/client/ui-command/README.i18n.yaml
+++ b/packages/client/ui-command/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/client/ui-command/README.md
 README.md: bc7386c8fca3b5c623473328bee6322fa7295277
-README.zh.md: 478ee4ccee4558c70075baa45ab34ac6e3d71617
+README.zh.md: 54190ac9144b1bfc12ba84a47474311d5a5391ea
diff --git a/packages/client/ui-command/README.zh.md b/packages/client/ui-command/README.zh.md
index 478ee4ccee..54190ac914 100644
--- a/packages/client/ui-command/README.zh.md
+++ b/packages/client/ui-command/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端命令业务面（`ctx.command`）：以会话为 key 的命令目录缓存、带 matchSpace／matchEnter 裁决钩子的 `/` 命令 source、三型派发（execute／popupSelect／leadingInput），以及面向业务包的 popupSelect 注册面。契约：[Web 命令业务面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)。
+客户端命令业务面（`ctx.command`）：以会话为 key 的命令目录缓存、带 matchSpace／matchEnter 裁决钩子的 `/` 命令 source、三型派发（execute／popupSelect／leadingInput），以及面向业务包的 popupSelect 注册面。约定：[Web 命令业务面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)。
 
 `src/client/contract.ts` 是冻结的业务表层：`CommandServiceContract.register(name, spec)` 与 `decorate(name, spec)` 是业务包消费的全部内容；`CommandUiSpec{options, onSelect}` 让 popup 数据自给自足——壳组件归本包所有，业务永远见不到它。contribution 是 client 自有命令（与 host 同名碰撞即 fail-loud）；decoration（装饰）则把裸调用 popup 挂在**已存在的** host 命令上——host 保留目录行、带参 claim（space / 带参 enter）与生命周期记账，被装饰的名字若在会话目录中无 host 行则装饰永不触发。命令三型按每次派发派生，绝不在注册时定型：带 `input` 的 host descriptor 是 leadingInput，注册了 `CommandUiSpec` 的是 popupSelect，其余全部是 execute。
 
@@ -12,7 +12,7 @@
 
 `PopupSelectController`（`src/client/popup.ts`）是无头的壳状态：`PopupSelectView` 自行注册进 `conversation.input.overlay`（SlotMap key 归 ui-conversation 所有；本包只以 type-only 导入引入该声明——没有运行时依赖边）。壳是打开期间持有焦点的瞬态层；onSelect 之后的 token 片段消费在两条分支上都经 `consumeTokenSegment` 执行（菜单路径做 span CAS，回车路径做裸 token 相等比较），作用于接线层经 `bindDraft` 绑定的草稿表层。
 
-`/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的契约类型；壳组件本身是 overlay 注册的内部实现。
+`/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的约定类型；壳组件本身是 overlay 注册的内部实现。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 822a02d321..c03e330672 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
 README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
-README.zh.md: 90c4dc4cc169b2cbcd7e94275a692e3d062cfe98
+README.zh.md: b3ce1b66308213650505b8838b9b43cb9987c757
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 90c4dc4cc1..b3ce1b6630 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -8,7 +8,7 @@
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份契约里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份约定里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
@@ -30,7 +30,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时
 
 Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。QueueDock 会将其过滤掉，ChatView 则把它投影为会话流末尾带复制操作的用户样式气泡；非用户来源的 next-step 项（注入上下文）改以 `context` placement 广播，领取前不在任何界面渲染。与所有用户样式气泡一样，这里不显示 fork。Host 会等携带该 steering 的持久 `user/message` 进入 mux 流之后再退役 steering。客户端运行时接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史事件无法隐藏后来复用同一 `MessageId` 的单次入队项。气泡交接时因而不会产生空档或重复，会立即从持久节点恢复复制操作与时钟——steering 气泡与 user 气泡一样不带分支操作（[决策](../../../.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)）——并能在重连后从同一权威恢复。
 
-键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 契约：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
+键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 约定：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index 613876693a..ee6d490035 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/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/client/ui-layout/README.md
 README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
-README.zh.md: dd23550cc8f0134ed1231c86d88825dab96e8e79
+README.zh.md: 2ce3d1972d39013d84216596dc57d48ab2d245d9
diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
index dd23550cc8..2ce3d1972d 100644
--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -4,7 +4,7 @@
 
 外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景成为唯一的颜色依据；呈现器在 dispose（资源释放）时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
 
-AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用契约默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
+AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用约定默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
 
 `/client` 导出表层包含插件主体（`apply`／`inject`）、`LayoutService` 和四个 owner-share 接口。AppFrame、面板 store 与让步求解器仍属于包内部。
 
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index 9f6db24bba..a909395148 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/client/ui-model/README.md
 README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
-README.zh.md: 09fee7a2cfd22b773be569e37c4c31f8c299d707
+README.zh.md: 55ea296370ffa986c9b11b41f83ef83b12236e88
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 09fee7a2cf..55ea296370 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -22,6 +22,6 @@ Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择
 
 ## 已知限制与暂缓事项
 
-- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立更改模型目标的契约。
+- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立更改模型目标的约定。
 - **目录名仅供呈现**——选择与持久化使用提供方／模型／推理强度 id；目录查询或确切模型元数据查询失败的提供方以不可选失败行列出，重新加载前保持原样。
 - **不能任意输入推理强度**——composer 仅提供确切模型由适配器公布的推理强度；适配器没有推理元数据时不显示 Effort 行。
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index 9b00e02b2a..92507c838e 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/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/client/ui-sidebar/README.md
 README.md: 45ae267d98b17bbc612cf932f5b95b42ba6ff4bf
-README.zh.md: c0bae62de0811874a94810bd18c78378441db8a3
+README.zh.md: a9fb927305d0bab5fb4d27adbfdbec90dfa1dd6d
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index c0bae62de0..a9fb927305 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-侧边栏插件：真实 Host Workspace 按稳定的 Host 顺序排列；每个 Workspace 按自身顺序包含其 `sessionIds`，并以 `parentId` 嵌套；不属于任何 Workspace 的会话显示在末尾的 `Ungrouped` 分区。搜索、状态点以及折叠到布局拥有的 56px 轨道，都只属于呈现层。契约：[slot 系统标准](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)。
+侧边栏插件：真实 Host Workspace 按稳定的 Host 顺序排列；每个 Workspace 按自身顺序包含其 `sessionIds`，并以 `parentId` 嵌套；不属于任何 Workspace 的会话显示在末尾的 `Ungrouped` 分区。搜索、状态点以及折叠到布局拥有的 56px 轨道，都只属于呈现层。约定：[slot 系统标准](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)。
 
 New Session 会启动运行时的页面局部前端 Session Intent；真实 Workspace 的「+」会启动一项以该 Workspace 为目标的 Intent。Workspace 标题栏的「+」打开 ui-workspace 的共享选择器，选择结果同样以一个前端会话为目标。Workspace Intent 不会出现在侧边栏中。
 
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index 340f420504..6954134f01 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/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/client/ui-slash/README.md
 README.md: efb289aaf6b4a442b00e7a0b26ed044b7b061070
-README.zh.md: e2d99514d29b1b5aeeb1d7f42136ec73d961f3e7
+README.zh.md: c6d3236f615642b9efc6fabaa7ec407ad896a8e2
diff --git a/packages/client/ui-slash/README.zh.md b/packages/client/ui-slash/README.zh.md
index e2d99514d2..c6d3236f61 100644
--- a/packages/client/ui-slash/README.zh.md
+++ b/packages/client/ui-slash/README.zh.md
@@ -4,11 +4,11 @@
 
 输入触发流水线插件：光标处的 `/` 与 `@` 检测（词边界 + guard tier 规则）、分组候选菜单，以及把 pick 路由到已注册 source。`ctx.slash` 拥有 source roster，并按会话 scope（`sessionOf`）各解析一个 `SlashController`；对话接线层在 controller 上驱动 `track`／`arbitrate`／`onSpace`／`adjudicate`。同一个 controller 还暴露 `toggleSource`，供 chrome launcher 在一段合成 selection span 上只打开一个已注册 source；所得候选仍走通常的菜单、键盘仲裁、pick callback 与 scoped 输入改写。source 每次调用收到一个 `ClientSessionContext` 投影——会话始终由 agent（智能体）支撑，因此投影只含会话身份。source 在它能触达的每个会话 controller 中都会被预热：scope 出生时在场的 roster 随 controller 构造预热，晚于此注册的 source 由注册动作本身预热进每个活 controller。`lexicon` 名录在预热后仍会变化的 source 实现 `subscribeLexicon(session, listener)`；controller 每收到通知就重拉，并把聚合结果经其 `lexicon` 快照 store 发布。流水线与命令无关：空格／回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子，第一个非 undefined 的应答胜出。
 
-分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包契约（设计 v4 §5.1）；变更需经主线程仲裁。
+分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定（设计 v4 §5.1）；变更需经主线程仲裁。
 
 MenuView 把菜单 store 渲染进 `conversation.input.overlay` slot（列表类，会话 scope），菜单关闭期间渲染 null。键入式 trigger 会 seed 为该 trigger 注册的所有 source；程序化 launcher 只 seed 所请求的 source，并在菜单关闭或重新开始键入式 tracking 前，通过 controller 的 `launcher` 快照 store 发布该 source 名称。分组按可选的 `SlashSource.order` 排序（越小越靠前，默认 0，同值保持注册序），组标题行经 `slash.menu` locale 命名空间本地化（未知 source 显示其原名）；列表高度收敛到 composer 上方的可用空间，指针落在菜单与所在 composer 卡片之外即关闭菜单。该 slot 由 ui-conversation 的组合器条目拥有（锚点、children 声明、生命周期）；其 SlotMap 类型合并放在本包的 `src/client/slots.ts`，因为依赖方向（ui-conversation → ui-slash）不允许反向的类型导入。combobox 模式：焦点始终留在 textarea，行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载。
 
-`/client` 导出表层是插件主体（`apply`／`inject`）、`SlashService`、`MenuViewInjected` 与契约类型。MenuView 本身是内部实现——slot 注册以闭包持有它。
+`/client` 导出表层是插件主体（`apply`／`inject`）、`SlashService`、`MenuViewInjected` 与约定类型。MenuView 本身是内部实现——slot 注册以闭包持有它。
 
 ## 模型体验
 
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index 7b67f66d3b..a3bf047f84 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/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/client/ui-slots/README.md
 README.md: bb489dea0c3848cf3d501dcf095a65fe1cef9ef6
-README.zh.md: 91e4f817c414e11645aa4d3a1b9bcf94f9678805
+README.zh.md: 8b10ddf2d974c3054b5e086a302cd8f84dca9667
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index 91e4f817c4..8b10ddf2d9 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装 seam 契约。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
+Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装 seam 约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
 
 一次 `register({ name, children?, store?, inject?, ...kind }, Component)` 调用会向已声明 slot 贡献一个组件，同时声明子 slot（声明 = 渲染授权 = 运行时规范，三者共用一张表）、store seat 以及注册方的业务表层。组件会在调用点依据 `ComposedProps` 接受检查；该类型是四个 share 的交集，每个 share 都从各自的唯一真源派生：
 
@@ -17,7 +17,7 @@ chain-kind slot 会反转键控路由：条目自行提名，而不是由分发
 
 标准工具包接口（`SessionStandardProps`、`GlobalStandardProps`）在这里声明为空，由 runtime 包合并（与 SlotMap key 相同的 declare-merge 模式）。renderer 会把运行时 Session 和 Workspace observable source 绑定为 selector hook。Inject factory 参数从声明派生（`InjectParams`）：Session slot 获得 `sessionId`；声明 store 时追加 baked `actions`；没有其他参数，数据访问位于 apply 闭包的 ctx 中。
 
-store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 契约。引擎产物与 renderer host 契约携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 契约 hook 类型（`SnapshotSelectorHook`）位于这里。
+store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
 
 `SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index 6ca3d905b4..35b576523d 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/client/ui-theme/README.md
 README.md: 648213b258169b2e8869a93d058fcc65aece175e
-README.zh.md: 02481badc816e0eb42c0d2496c9a096d2dbdbccb
+README.zh.md: ec29b9be999d64eee76342f0a86eb8707807be06
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index 02481badc8..ec29b9be99 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。契约：api-contracts v3 §8。
+主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。约定：api-contracts v3 §8。
 
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 97008e3e0c..ca5f3cd25c 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
 README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
-README.zh.md: f4e8044fe6e10e1fbdfb70987efe07c884fa9ac8
+README.zh.md: 6b6e2a153be6a3cad5b57379de6fdc0cd4a58ea4
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index f4e8044fe6..6b6e2a153b 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -6,11 +6,11 @@ Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交
 
 业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
 
-## 渲染契约
+## 渲染约定
 
 `ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
 
-每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
+每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 约定，供分页和 selection 使用。
 
 本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
 
@@ -44,6 +44,6 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
-- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 契约已为未来的嵌套生产者做好准备。
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 约定已为未来的嵌套生产者做好准备。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-trajectory/README.i18n.yaml b/packages/client/ui-trajectory/README.i18n.yaml
index 83f0b0b2e5..e0646b2da8 100644
--- a/packages/client/ui-trajectory/README.i18n.yaml
+++ b/packages/client/ui-trajectory/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/client/ui-trajectory/README.md
 README.md: 2c737fe2d04df518e7d32d07aaede714a7a3566d
-README.zh.md: 738d6cafa0c6d44f05fecec01d565da91ef433e8
+README.zh.md: 1baa5a1a4422731161e6c8a743aa337a0e5cc774
diff --git a/packages/client/ui-trajectory/README.zh.md b/packages/client/ui-trajectory/README.zh.md
index 738d6cafa0..1baa5a1a44 100644
--- a/packages/client/ui-trajectory/README.zh.md
+++ b/packages/client/ui-trajectory/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。契约：api-contracts v3 §8。
+Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。约定：api-contracts v3 §8。
 
 ## 模型体验
 
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 3f2ea68116..99d66e084f 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
 README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: fff62b97b8ef76901e4680fb6c6c8ff4820ba35d
+README.zh.md: 2a68e6f05d12b737bdff530a351aa038628d85fc
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index fff62b97b8..2a68e6f05d 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -14,11 +14,11 @@
 | `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整约定见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。
 
 binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
@@ -33,6 +33,6 @@ binding-global 与 error-class 名称是**语言可移植**的：必须匹配标
 ## 已知限制与暂缓事项
 
 - **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
-- **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
+- **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的约定继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
 - **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index bdbb81127c..7e8ef24260 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/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/compact/README.md
 README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
-README.zh.md: 431e84ec645ae08da203e2d68e1f6813dd7ded2d
+README.zh.md: 001ca6f7c079a60cbd432664e4f0b06955aaf487
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index 431e84ec64..001ca6f7c0 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -13,4 +13,4 @@
 
 后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 负责说明依赖关系的设计依据。
 
-子系统参考——`compact/*` 事件、`CompactionResult`、服务、修剪结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在 [压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
+子系统参考——`compact/*` 事件、`CompactionResult`、服务、修剪结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
diff --git a/packages/compact/command-compact/README.i18n.yaml b/packages/compact/command-compact/README.i18n.yaml
index 68dfebd1b9..b1329c13db 100644
--- a/packages/compact/command-compact/README.i18n.yaml
+++ b/packages/compact/command-compact/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/compact/command-compact/README.md
 README.md: 5af39e82928d64c11474199b6b30058e9d289f45
-README.zh.md: a582bd5272b2e39ac1ffbf839888a4006b6d44bc
+README.zh.md: 70fac7ba495ae57757fbe73bd5c61951dd0c2fe9
diff --git a/packages/compact/command-compact/README.zh.md b/packages/compact/command-compact/README.zh.md
index a582bd5272..70fac7ba49 100644
--- a/packages/compact/command-compact/README.zh.md
+++ b/packages/compact/command-compact/README.zh.md
@@ -4,7 +4,7 @@
 
 通过 [`ctx.compact`](../compact/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index 1252d99e0f..dc2254d647 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
 README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22
-README.zh.md: 330b5b0cb9d5c2bf3953354112f3488447e71f87
+README.zh.md: d068869f1d9091e9671d8c2fb17df53a48c9916d
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 330b5b0cb9..d068869f1d 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -12,7 +12,7 @@
 | `@deepseek-ai/dsh-compact-basic` | 后端：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
 | `@deepseek-ai/dsh-command-compact` | 面向用户的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
 
-与 bash seam 不同，该接口依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。契约的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「接口只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
+与 bash seam 不同，该接口依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。约定的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「接口只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
 
 ## 服务 API（`ctx.compact`）
 
@@ -36,7 +36,7 @@
 
 每个会话的私有 cache 以 `session.surface.replaceGeneration` 和已处理表层条目数为 key。generation 未变时，只需将尚未处理的尾部条目纳入累计结果；仅向日志追加、但未新增表层条目时，不会读取事件。replace generation 变化时则会重建当前成员关系与配对状态。事件 seq 缺失以及 `tool/result` 没有对应的先前未闭合调用，均会被视为表层状态损坏并遭拒绝。
 
-## 表层契约
+## 表层约定
 
 `SurfaceEventType` 是封闭联合：只有 `user/message`、`assistant/message` 和 `tool/result` 可以携带 `surfaceOp`。因此 `compact/*` 事件**不能**出现在表层上。成功压缩改为：
 
@@ -89,5 +89,5 @@
 ## 已知限制与暂缓事项
 
 - **面向用户的命令，而非模型工具**：`@deepseek-ai/dsh-command-compact` 通过 `ctx.commands` 暴露无参数 `/compact`；不会注册面向模型的压缩工具。
-- **部分单元溢出不在契约内**：平衡摘要压缩无法拆分一个不可分单元。当闭合工具对中可移除的主要部分是承载文本的工具结果时，可选剪枝配套服务仍可修复该工具对；无法压缩大型非工具节点，或不可剪枝剩余部分过大的工具单元。
+- **部分单元溢出不在约定内**：平衡摘要压缩无法拆分一个不可分单元。当闭合工具对中可移除的主要部分是承载文本的工具结果时，可选剪枝配套服务仍可修复该工具对；无法压缩大型非工具节点，或不可剪枝剩余部分过大的工具单元。
 - **单独接近窗口大小的 envelope 不属于表层压缩工作**：压缩缩减派生历史，绝不缩减系统提示词、工具或会话前缀。
diff --git a/packages/context/session-reference/README.i18n.yaml b/packages/context/session-reference/README.i18n.yaml
index 24fb2c24dc..18ce315cd5 100644
--- a/packages/context/session-reference/README.i18n.yaml
+++ b/packages/context/session-reference/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/context/session-reference/README.md
 README.md: 145ec112d6b9cce9e9eb1567c60cde41c6d6eb3c
-README.zh.md: 71bab6c94161a37de507482405fb8362e08a89fa
+README.zh.md: 5d528a296ee77dc64b584d0683395cb4df67936a
diff --git a/packages/context/session-reference/README.zh.md b/packages/context/session-reference/README.zh.md
index 71bab6c941..5d528a296e 100644
--- a/packages/context/session-reference/README.zh.md
+++ b/packages/context/session-reference/README.zh.md
@@ -18,7 +18,7 @@
 
 ## 配置
 
-| Key | 默认值 | 契约 |
+| Key | 默认值 | 约定 |
 |---|---:|---|
 | `maxReferences` | `3` | 一条已准备消息中不同源会话的最大数量；必须不大于 `3`。 |
 | `candidateLimit` | `50` | 返回给宿主的默认候选数量。 |
@@ -44,7 +44,7 @@
 
 ## 已知限制与暂缓事项
 
-- **不支持消息正文检索**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化契约。
+- **不支持消息正文检索**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化约定。
 - **受信任调用方边界**：该服务假设宿主有权读取 `ctx.sessionQuery` 公开的每个会话；它不是面向模型的搜索工具。
 - **只投影文本**：不会在会话间传播非文本 user 与 assistant 块。
 - **没有实时链接**：引用是快照，不是 fork、恢复、订阅或源会话变更。
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index f80bc0cc79..c8a81c8d13 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
 README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
-README.zh.md: f14810ecf56f80c1f2a768aaf315415159e2c021
+README.zh.md: 22f9655d46c4c9764118f05cc919be26a471c00b
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index f14810ecf5..22f9655d46 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -31,7 +31,7 @@
 
 ### 不变量配套入口
 
-可选的 `@deepseek-ai/dsh-agent-loop/invariant` 配套入口会向 `ctx.invariants` 注册请求重建。循环会把每个确切的冻结请求记录在 `dsh-llm` 拥有的进程本地身份集合中；随后，配套入口要求存在实时会话，并根据日志独立重建消息边界和折叠后的请求 header。即使调用方冻结直接的一次性调用，或为其附加会话 id，这类调用仍不属于该契约。
+可选的 `@deepseek-ai/dsh-agent-loop/invariant` 配套入口会向 `ctx.invariants` 注册请求重建。循环会把每个确切的冻结请求记录在 `dsh-llm` 拥有的进程本地身份集合中；随后，配套入口要求存在实时会话，并根据日志独立重建消息边界和折叠后的请求 header。即使调用方冻结直接的一次性调用，或为其附加会话 id，这类调用仍不属于该约定。
 
 ### 配置（Schemastery）
 
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index b2d54ebc66..53a1a1f650 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
 README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
-README.zh.md: 4295c15923f6a5c6132369bfe2137e3d34dec6b1
+README.zh.md: e421070a6eec2e6e7e1fc7b45f0a5e29040bf712
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 4295c15923..e421070a6e 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -32,7 +32,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 - `ctx.agents.withInitiator(agent, operation)`：使用一个确切 Agent 运行，并保留操作的确切同步值或 Promise。
 - `ctx.agents.withoutInitiator(operation)`：对无关的进程本地工作隐藏继承的发起方。
 
-该作用域携带 `Agent` 本身，并且只在进程内有效。环境中的身份既不是存活证明，也不是授权；在服务、worker、进程、持久化和 wire 边界，显式 Agent 字段仍是权威来源。Teardown 会拒绝新边界，允许注入的依赖方和返回 Promise 的边界 drain，然后禁用底层 `AsyncLocalStorage`；未返回的工作仍归将其分离的子系统所有。如果某个边界继承的异步链开始卸载一个拥有它的 Cordis fiber，该嵌套边界链会从 drain 中释放，使卸载不会等待自身；其 continuation 会在 teardown 后观察到已 dispose 的服务。详细边界与 teardown 契约由[发起方作用域决策](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)拥有。
+该作用域携带 `Agent` 本身，并且只在进程内有效。环境中的身份既不是存活证明，也不是授权；在服务、worker、进程、持久化和 wire 边界，显式 Agent 字段仍是权威来源。Teardown 会拒绝新边界，允许注入的依赖方和返回 Promise 的边界 drain，然后禁用底层 `AsyncLocalStorage`；未返回的工作仍归将其分离的子系统所有。如果某个边界继承的异步链开始卸载一个拥有它的 Cordis fiber，该嵌套边界链会从 drain 中释放，使卸载不会等待自身；其 continuation 会在 teardown 后观察到已 dispose 的服务。详细边界与 teardown 约定由[发起方作用域决策](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)拥有。
 
 #### 工厂 seam（创建）
 
@@ -46,9 +46,9 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 ### 实时事件
 
-`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 契约位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 的生成区块；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
+`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 约定位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 的生成区块；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
 
-生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
+生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序约定。
 
 大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
@@ -111,7 +111,7 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 ## 已知限制与暂缓事项
 
 - **发起方作用域只存在于进程内**：worker、子进程、HTTP、持久队列和重启必须显式传递所需身份。
-- **环境身份可能比存活状态更久**：消费方在生命周期敏感工作前，仍要检查 `agent.status`、取消状态和所属能力契约。
+- **环境身份可能比存活状态更久**：消费方在生命周期敏感工作前，仍要检查 `agent.status`、取消状态和所属能力约定。
 - **委派以外的 agent 间通道**：共享状态、流式子输出和后台／轮询语义仍在当前同步 `ctx.subagents` seam 之外。
 - **`agent/session-start` 不能为启动设置门禁**：它仍是同步且不可 veto 的通知；必须在发布前完成的异步组合属于工厂的 `setup(agentCtx)` 事务。
 - **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
diff --git a/packages/core/scope/README.i18n.yaml b/packages/core/scope/README.i18n.yaml
index c9212a3998..8b49f4387b 100644
--- a/packages/core/scope/README.i18n.yaml
+++ b/packages/core/scope/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/core/scope/README.md
 README.md: 4f32573779a15e8c34b4936bfe75549dfc86d9f6
-README.zh.md: 16ec60a5489f909a46fd5f803dbf08490cd07988
+README.zh.md: d046a8a1e559a56a942d0b3da3b213e79af3abd3
diff --git a/packages/core/scope/README.zh.md b/packages/core/scope/README.zh.md
index 16ec60a548..d046a8a1e5 100644
--- a/packages/core/scope/README.zh.md
+++ b/packages/core/scope/README.zh.md
@@ -14,14 +14,14 @@
 - `scopeTarget(base: T, key: ScopeKey | undefined): Scoped<T>`：为按作用域筛选的事件构造不透明分发 `thisArg`。它把 `base` 现有的 `Context.filter` 与作用域谓词组合起来（无标签监听器 ⇒ 放行；有标签监听器 ⇒ 仅当标签 === key 时放行；`key === undefined` ⇒ 仅放行无标签监听器）。载体只包含路由状态；真实主体由事件参数携带。带 `{ global: true }` 的监听器绕过筛选（Cordis 语义）。
 - `Scoped<T>`：编译期不透明载体 brand。按作用域筛选的事件要求它作为 `this` 类型，因此使用裸主体分发会产生编译错误。类型参数记录主体类型，但不公开其属性。
 - `isScopeCarrier(value)`/`carrierKeyOf(value)`：运行时载体标记，开发不变式使用它们断言每次按作用域筛选的分发都携带载体，而且载体键与参数所指名的主体一致。
-- `ScopeLayer`：一个注册表的完整全局贡献或精确作用域贡献的聚合契约；`isEmpty()` 控制带作用域层的回收。
+- `ScopeLayer`：一个注册表的完整全局贡献或精确作用域贡献的聚合约定；`isEmpty()` 控制带作用域层的回收。
 - `ScopedLayers<L>`：拥有一个立即创建的全局层和按需创建的精确作用域层。`peek()` 从不创建；`merge()` 物化按插入顺序排列的具名遮蔽项；`effect()` 从同一上下文推导可见性与所有权，同时返回原样 Cordis disposer。
 - `NamedEntries<V>`：按插入顺序排列的具名存储，调用方拥有重复项诊断、查找，以及一个非空表世代内的实时迭代。表清空后，现有迭代器与后续插入项脱离；`insert()` 返回幂等的精确条目撤销函数。
 - `AnonymousEntries<V>`：按插入顺序排列的匿名存储；唯一内部键使相同值仍作为独立注册存在。它使用相同的清空世代迭代器边界；`append()` 返回幂等的精确条目撤销函数。
 
 可选配套包 `@deepseek-ai/dsh-scope/invariant` 拥有该运行时断言。它使用生成的 `scoped-events.generated.ts` 解析器映射，要求每个已声明的带作用域事件都携带载体；当 payload 公开路由主体时，还要求路由主体与载体键严格相等。基于 Program 的生成器根据事件声明和真实的 `scopeTarget(base, key)` 调用生成该映射。
 
-## 设计契约
+## 设计约定
 
 注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index e4caa9b815..5a70af1152 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
 README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5a838f4ed3cb1f57ecd9f41325e1612afaf5103a
+README.zh.md: 9b390f664decade482ea0386e59623cf317a2093
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5a838f4ed3..9b390f664d 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -23,7 +23,7 @@
 
 ### 实时事件
 
-`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发契约。
+`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发约定。
 
 ### 关键类型
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index b257ecbfa6..daede94370 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
 README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
-README.zh.md: 675d9299037bc5225fcd117148c574eb646cf680
+README.zh.md: e636e1e8e7f4e3830d394224d704ee680eab198b
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 675d929903..e636e1e8e7 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -31,11 +31,11 @@ tools:
 
 ### 取消
 
-取消采用协作方式，并等待完全停稳。每次类型化调用都提供由调用方拥有的 `AbortSignal`；工具主体通过必填的只读 `exec.signal` 接收它，只有 `tools/execute` 包装层可以临时替换这个必填信号。注册表会在替换期间保留调用方取消，并且绝不会在已启动的同进程 Promise 尚未结算时提前返回。调用主体前发生的取消为 `ABORTED_BEFORE_DISPATCH`；调用后的取消只能把成功结果替换为 `ABORTED`。拒绝、包装层失败、工具失败、后置策略失败或由超时机制产生的 `TOOL_TIMEOUT` 仍保留更具体的结果。入口处已中止的调用会实体化并冻结参数，随后跳过所有策略和分发阶段，只发布一个结果。每个异步工具都必须观测或转发该信号，并且只能在自身拥有的工作停止后结算。[工具取消 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md) 规定完整契约和强制终止边界。
+取消采用协作方式，并等待完全停稳。每次类型化调用都提供由调用方拥有的 `AbortSignal`；工具主体通过必填的只读 `exec.signal` 接收它，只有 `tools/execute` 包装层可以临时替换这个必填信号。注册表会在替换期间保留调用方取消，并且绝不会在已启动的同进程 Promise 尚未结算时提前返回。调用主体前发生的取消为 `ABORTED_BEFORE_DISPATCH`；调用后的取消只能把成功结果替换为 `ABORTED`。拒绝、包装层失败、工具失败、后置策略失败或由超时机制产生的 `TOOL_TIMEOUT` 仍保留更具体的结果。入口处已中止的调用会实体化并冻结参数，随后跳过所有策略和分发阶段，只发布一个结果。每个异步工具都必须观测或转发该信号，并且只能在自身拥有的工作停止后结算。[工具取消 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md) 规定完整约定和强制终止边界。
 
 ### 实时事件
 
-实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发 mode、作用域筛选和故障收容契约位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
+实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发 mode、作用域筛选和故障收容约定位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
 
 ### 关键类型
 
@@ -97,7 +97,7 @@ ctx.tools.register(defineTool({
 
 可选的 `timeoutMs` 必须为正数且为有限值；它是策略元数据，不是模型可见的 schema。
 
-可选的 `isConcurrencySafe(args)` 接收经过软验证的类型化参数。只有确切的 `true` 才允许并发分发／主体执行；无效输入和所有其他结果仍为独占。选择并发的主体不得改变父级拥有的状态；共享状态竞态必须具有交换性，否则必须安全拒绝。[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md) 规定完整安全契约。
+可选的 `isConcurrencySafe(args)` 接收经过软验证的类型化参数。只有确切的 `true` 才允许并发分发／主体执行；无效输入和所有其他结果仍为独占。选择并发的主体不得改变父级拥有的状态；共享状态竞态必须具有交换性，否则必须安全拒绝。[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md) 规定完整安全约定。
 
 ### 强制执行的原始 JSON Schema 子集
 
@@ -114,10 +114,10 @@ ctx.tools.register(defineTool({
 
 ### Code Mode
 
-在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度约定下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 约定之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回契约](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
+在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度约定下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 约定之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回约定](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
 
 - **SDK 段**（`tools:sdk`，顺序 150）：一个惰性提示词段，每次组装时都会重新生成与所加载运行时语言相符的 SDK 文本。TypeScript 形态发出 `JsonValue`、精确的 `ToolArgsMap` / `ToolOutputMap`、`ToolName`、`ToolCallError` 声明、面向调用作用域可见最终能力的映射 `tools` 命名空间（特殊名称使用带引号的键），以及固定用法说明；Python 形态（`ctx.codeRuntime.language === 'python'`）发出等价的具名 `TypedDict` 与一个带相同用法说明的 `tools` 对象。其输出具有确定性：工具按字典序排列；工具集合不变时，文本逐字节相同（有利于前缀 cache）。两个代码生成器都已导出，且绝不会在提示词组装期间抛出：`jsonSchemaToTs` 处理统一 schema 的每种构造并将不受支持的原始构造降级为 `unknown`；`jsonSchemaToPy` 同理，降级为 `Any`（当某字段名不是合法的 `TypedDict` 属性时，或在 SDK 渲染之外被调用时——`TypedDict` 声明所需的命名上下文由该渲染提供——整个对象降级为 `dict[str, Any]`）。
-- **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发契约的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联让以提交为语义的观察器能够把内部成功延迟到最终 `run_code` 结果，而无需公开实时外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系，并且即使程序后来失败，也会保留各自的来源／元数据。
+- **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发约定的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联让以提交为语义的观察器能够把内部成功延迟到最终 `run_code` 结果，而无需公开实时外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系，并且即使程序后来失败，也会保留各自的来源／元数据。
 - **结算纪律**：桥接层拥有一个运行作用域的中止机制；该中止会跟随传入的外层信号，并在运行因任何原因结算时触发，因此预算耗尽会中止正在运行的子工具，而不会将其遗留。桥接层随后会在返回之前排空队列，使每个 `tool/code-dispatch` 都落在仍打开的轮次内。失败的运行会抛出 `CodeRunFailedError`（`code: 'CODE_RUN_FAILED'`，message = 失败类型 + 已捕获日志），流水线会将其转换为模型可据以自我修正的结构化 `isError`。
 - **结果边界**：中间绑定值会完整跨越 worker 边界，且没有逐绑定字节上限。`run_code` 返回规范的 `{ logs: string[], result?: JsonValue }`；字符串原样呈现，其他所有存在的 JSON 根都通过栈安全的美化 JSON 遍历呈现，总缩进最多为 10 个字符（更深的子树保持紧凑），`null` 保持显式，而缺少 `result` 表示程序返回 `undefined`。worker 可配置的 `maxOutputBytes`（默认 64 MiB）只应用于组合序列化后的外层日志数组、完成值或失败消息载荷；固定的结果 envelope 语法和呈现空白不计入该账本。无效和超限的完成会明确失败，只有此外层结果可以使用普通 spill。
 
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index 5660d73494..c47938ce3b 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/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/examples/jsonrpc-demo/README.md
 README.md: fff8e78698cd3d6320606084ef5c533be7c52633
-README.zh.md: 207717c27ac7a0f91eaf888d7aed4ded1adef67c
+README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 207717c27a..75382b97ea 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
 
 ## 配置发现
 
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index 20eb2741d6..bc4a93d760 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/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/feedback/command-feedback/README.md
 README.md: e2eb6d4cf2b40e83efad1fa158edd72578658f56
-README.zh.md: f87067d67cf9dcb8f4da97afe3a9d59eb828faf7
+README.zh.md: c3b7b59d90d924de6042aeac1e7eec39457c6c83
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index f87067d67c..c3b7b59d90 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -4,7 +4,7 @@
 
 与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
@@ -15,7 +15,7 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集契约。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集约定。
 
 反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 8141819240..e0095d9858 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
 README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
-README.zh.md: 32faf67d6ed97914704ea5683f1fd987e2e64a93
+README.zh.md: 8eb2634df2754cdcada4e48046e19eb32b1cf3af
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 32faf67d6e..8eb2634df2 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -41,13 +41,13 @@
 
 ## 提供方 seam，不是策略层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
 
 `editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
-`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整契约见 `src/types.ts`。
+`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
 
 ## 模型体验
 
diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml
index fbe6453292..a8fe6a80d7 100644
--- a/packages/fs/tool-fs-search/README.i18n.yaml
+++ b/packages/fs/tool-fs-search/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/fs/tool-fs-search/README.md
 README.md: 32fa61e3bb09b2166499003953a5631a93baf73b
-README.zh.md: bf2eac320bf3dc0811ec8e3747487b4f3ce634b7
+README.zh.md: 34ffcdc9f64daba7350e4581b35e694213f24214
diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md
index bf2eac320b..34ffcdc9f6 100644
--- a/packages/fs/tool-fs-search/README.zh.md
+++ b/packages/fs/tool-fs-search/README.zh.md
@@ -16,11 +16,11 @@ await ctx.plugin(LocalSpillStore)                           // @deepseek-ai/dsh-
 
 ## 部署要求：无需宿主 rg，但工作目录与文件系统需共置
 
-二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区契约或特定提供方的搜索后端。
+二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
 
 ## 配置
 
-`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序契约。其余配置键是可选的搜索上限，默认值如下。
+`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序约定。其余配置键是可选的搜索上限，默认值如下。
 
 | 配置键 | 默认值 | 含义 |
 |---|---|---|
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index e9000e3500..32b85a4257 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
 README.md: 28880860dc6c89745eb21fbf732d04f596f9b07f
-README.zh.md: 8af0aec51e71681211bbd5a4f582be8b8b0271b8
+README.zh.md: b85fc7d90aaaf0d7e137bf8646bc023d6ca1e60f
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 8af0aec51e..b85fc7d90a 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -50,11 +50,11 @@ await ctx.plugin(ToolFs)                                  // this package — re
 
 ## `fs/observed` 发后即忘
 
-`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的契约是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
+`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的约定是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
 
 `read` 允许并发调度，因为其唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
 
-包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
+包根目录只导出 Cordis 插件约定（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
 
 ## 模型体验
 
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 90285c2860..5953c9c6a0 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/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/goal/command-goal/README.md
 README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
-README.zh.md: 82750a102784fad7da1038a97478880f60001bdf
+README.zh.md: ee40cd4219c45b6d9650036fda21c56599be6abd
diff --git a/packages/goal/command-goal/README.zh.md b/packages/goal/command-goal/README.zh.md
index 82750a1027..ee40cd4219 100644
--- a/packages/goal/command-goal/README.zh.md
+++ b/packages/goal/command-goal/README.zh.md
@@ -4,7 +4,7 @@
 
 面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) 负责用户体验与组合决策。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml
index 686f8aaa3f..226316dbd7 100644
--- a/packages/goal/goal-session/README.i18n.yaml
+++ b/packages/goal/goal-session/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/goal/goal-session/README.md
 README.md: 89413062de8cbb49d7066ec3ae42769a99c939a2
-README.zh.md: 075592e4e77e3336c1e2c08769ee255569e53360
+README.zh.md: a39a45232e7a2376154bc35182e77cc3b9ba1569
diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md
index 075592e4e7..a39a45232e 100644
--- a/packages/goal/goal-session/README.zh.md
+++ b/packages/goal/goal-session/README.zh.md
@@ -19,7 +19,7 @@
 
 该插件没有可调配置。`maxGoalRounds` 属于目标定义，面向模型的阻塞阈值则属于 [`dsh-tool-goal`](../tool-goal/README.md)；在驱动器中重复任一数值都可能产生分歧策略。
 
-## Round 契约
+## Round 约定
 
 当对应的活跃 agent 实例处于 idle 状态，且目标 phase 为 active、已启用续行并有剩余容量时，驱动器先为待处理 goal 变更创建检查点，再预留 `roundsStarted + 1`，对应当前 `{ goalId, revision }`。它会排入一条 `<goal_round>` 提示词，并携带 `GoalMessageSource`。`agent/pre-step` 监听器会在下游监听器前后验证完整的已领取记录与当前 goal；只有进入步骤的 `user/message` 才会增加 `roundsStarted`。因陈旧而被拒绝的预留不会消耗 Round 编号。
 
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index 5593953d89..3fee674e71 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/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/goal/goal/README.md
 README.md: 98765a809820bcd4aeba31e1dd4ef6e92eb30760
-README.zh.md: 7f59fc4b538ad68bfcf0686b7651d0ec64470c2e
+README.zh.md: d133cb154523dcf47b8a033cc60411ac6f6e9c9e
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index 7f59fc4b53..d133cb1545 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -15,9 +15,9 @@
 
 `defaultMaxGoalRounds` 必须是正的安全整数。`create()` 会在提交目标前于内部物化这项部署默认值；请求级取值可以覆盖它。
 
-## 服务契约
+## 服务约定
 
-`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更以 `GoalRef { id, revision }` 作为比较并设置防护，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更。
+`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更以 `GoalRef { id, revision }` 作为比较并设置防护，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更事件。
 
 最多只有一个当前目标。创建操作会生成 revision 为 1、phase 为 active 的目标并启用续行。未完成的目标必须编辑、转换或清除；已完成目标可以由拥有全局未使用过的 id 的目标替换。编辑会保留 phase、blocker reason 与 activation。暂停、完成、阻塞和清除都会停用续行。阻塞会记录策略自有的 lower-kebab-case 代码和规范化的自由文本说明；提供方限制、配置预算、执行错误与请求人工输入都使用这一种持久 phase，不会扩增生命周期状态。只有配置的 Round 上限仍有剩余容量时，resume 才接受已停止 phase 或 phase 为 active 但已停用续行的目标；它会清除原 blocker reason。phase 为 active 且已启用续行的目标会拒绝冗余操作。
 
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index ae64984c31..f082be00ef 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
 README.md: e807d9597eb5f811195bab9a0ad2b30b545e1205
-README.zh.md: b77c8d658eddf7ce60faaf171e6f41e09b8ef333
+README.zh.md: c206224b45a5b12a7aa85d24de301f3d949f294b
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index b77c8d658e..c206224b45 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -4,7 +4,7 @@
 
 Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它不是 Cordis 插件：不注册也不注入任何内容。它是一个**库**，提供两个桥接插件（`@deepseek-ai/dsh-hooks-claude`、`@deepseek-ai/dsh-hooks-codex`）导入的方言无关原语，使两者都无需重复实现协议中相同的部分。
 
-共享 lib 存在的原因是：Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出契约以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
+共享 lib 存在的原因是：Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
 
 ## 共享内容（此处）与各方言内容（桥接）
 
@@ -41,4 +41,4 @@ Hook 溯源记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`
 
 ## 已知限制与暂缓事项
 
-- **`HookOutput.updatedInput` 会被解析但不会应用**：输入改写是已暂缓的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)）；当 hook 设置它时，桥接会记录 + 警告。完整契约见 `src/types.ts`。
+- **`HookOutput.updatedInput` 会被解析但不会应用**：输入改写是已暂缓的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)）；当 hook 设置它时，桥接会记录 + 警告。完整约定见 `src/types.ts`。
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 1f02adea1d..bc7869b361 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
 README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
-README.zh.md: 4de15316fe31d75361fd3b8655c7c1f7d5fa4a02
+README.zh.md: 65475351e279f258f4417f2082673382e76a5be3
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 4de15316fe..65475351e2 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -16,7 +16,7 @@
 
 存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
 
-## 契约层（`/api`）
+## 约定层（`/api`）
 
 协议消息组成一个四象限可辨识联合：发起方 × 请求／响应，与物理通道解耦。四种消息分别是 `ClientRequest`（POST `/api/<method>` 的请求体）、`ServerResponse`（该 POST 的响应体）、`ServerRequest`（SSE 帧）和 `ClientResponse`（POST `/api/respond` 的请求体）。响应始终回显对应请求的 `rpcId`，绝不签发新值。方法的参数与返回值结构只存在于领域接口签名（`SessionsApi`、`HostApi`、`EventsApi`）中；`RpcMethodMap` 注册方法，其他所有位置均通过 `RequestPayload<K>`／`ResponseValue<K>` 派生。Zod schema 以 `satisfies z.ZodType<Wire<T>>` 锚定类型，并分两层解析：先解析信封，再解析业务载荷，随后按方法分发。业务错误由 `RpcResult` 的错误分支承载（`RpcErrorDetailsMap` 封闭错误码集合）；HTTP 状态只表达载体层结果。每个 `/api` POST 都必须声明 `application/json` 媒体类型——否则在分发前即以 415 拒绝，因此跨站「简单请求」（浏览器不经 CORS 预检就会发出）永远无法盲目执行有副作用的方法。
 
@@ -56,7 +56,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 ## 模型体验
 
-无。该包定义客户端与宿主间的协议契约和载体，其中没有任何内容会进入模型请求。
+无。该包定义客户端与宿主间的协议约定和载体，其中没有任何内容会进入模型请求。
 
 #### KV Cache 影响
 
diff --git a/packages/host/directory-picker/README.i18n.yaml b/packages/host/directory-picker/README.i18n.yaml
index a37ed552a4..aeb36e44d7 100644
--- a/packages/host/directory-picker/README.i18n.yaml
+++ b/packages/host/directory-picker/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/host/directory-picker/README.md
 README.md: 3749b238b56578ec68610bc13550760aa084bad6
-README.zh.md: 4f7c20e25a4e64f63c611fc56eeec3f249ad67e3
+README.zh.md: bc77a9c6e1d76e00926774dc518fce42b2860735
diff --git a/packages/host/directory-picker/README.zh.md b/packages/host/directory-picker/README.zh.md
index 4f7c20e25a..bc77a9c6e1 100644
--- a/packages/host/directory-picker/README.zh.md
+++ b/packages/host/directory-picker/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一契约方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，也能服务于 OS 对话框无法触及的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端通过声明合并加入自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam，无需通过 wire 公布能力：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一项组合配置会同时切换宿主能力与 client 流程。不应固定某种交互的组合改为挂载 [`-auto`](../directory-picker-auto/README.md) 选择器，它在启动时一次性判定宿主处境，并自行挂载匹配的后端行。
+web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一约定方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，也能服务于 OS 对话框无法触及的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端通过声明合并加入自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam，无需通过 wire 公布能力：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一项组合配置会同时切换宿主能力与 client 流程。不应固定某种交互的组合改为挂载 [`-auto`](../directory-picker-auto/README.md) 选择器，它在启动时一次性判定宿主处境，并自行挂载匹配的后端行。
 
 浏览原语失败时会抛出带类型的 `DirectoryPickerError`（`directory-unreadable`／`directory-exists`／`directory-create-failed`，各自携带出错对象的 `path`），消费网关将其 1:1 映射为协议错误码。`DirectoryEntry` 行携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示策略留在客户端；`DirectoryListing.crumbs` 是从文件系统根开始的祖先链，每个 crumb 都是跳转目标。设计依据、与 `ctx.fs` 的切分、策略裁决见[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
 
@@ -16,4 +16,4 @@ web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`
 
 ## 已知限制与暂缓事项
 
-- **契约未定义多根目录词汇**——浏览契约每次列举只暴露一条祖先链；按部署限定可浏览根（以及 Windows 盘符之上的根枚举）等到出现需要它的消费方再做，见 seam Agent Note。
+- **约定未定义多根目录词汇**——浏览约定每次列举只暴露一条祖先链；按部署限定可浏览根（以及 Windows 盘符之上的根枚举）等到出现需要它的消费方再做，见 seam Agent Note。
diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index bd80f27f3e..a9e5d9e48a 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/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/host/webserver/README.md
 README.md: 569c3f0c19db2c308beaef35baaf915fd39768cd
-README.zh.md: b311ebffa3fb067e684e9e443c2ac02dab917d61
+README.zh.md: 3aee06487743764bf2cb837360bb1ac9f0268508
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index b311ebffa3..3aee064877 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层契约，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
+Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
 
 该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
 
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index f2321e732a..5c99feeaf3 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
 README.md: a72cd48bb1d3ec15b1116d576fac86619df59528
-README.zh.md: 170a557e40befaa0f7073f25e8a2b372958a6ec1
+README.zh.md: 03fab9c4ce4479b3ab82f372f14f4d4208d7de04
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 170a557e40..03fab9c4ce 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -12,6 +12,6 @@
 | [`user-interaction/`](user-interaction/README.md) | 定义与提供方无关的用户问答 seam。 | `ctx.userInteraction` |
 | [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
 
-这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
+这些包通过现有的 agent（智能体）和会话约定集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
 
 子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)与 [commands.md](../../docs/subsystems/commands.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
diff --git a/packages/interaction/commands/README.i18n.yaml b/packages/interaction/commands/README.i18n.yaml
index 967fa0d4ef..f79052085f 100644
--- a/packages/interaction/commands/README.i18n.yaml
+++ b/packages/interaction/commands/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/interaction/commands/README.md
 README.md: 1709bdcdce4e43d98cfea5ff3972ab95bfd3c33b
-README.zh.md: 569f2aa8293793b26d63ee16e3ea7600e04a8397
+README.zh.md: 0f3ce975a015a555e6ad88a5fc872dc0e9e95fa1
diff --git a/packages/interaction/commands/README.zh.md b/packages/interaction/commands/README.zh.md
index 569f2aa829..0f3ce975a0 100644
--- a/packages/interaction/commands/README.zh.md
+++ b/packages/interaction/commands/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发契约。
+由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发约定。
 
-## 服务契约
+## 服务约定
 
 `ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示、可选的 `recordInput` 策略，以及可中止的处理器。`recordInput` 默认为 true；若载荷由命令的权威领域事件持有，该命令会将 `recordInput` 设为 false，让 `command/run` 省略 `args`，避免重复记录输入。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent（智能体）的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop（智能体循环）依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使运行中的适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
 
@@ -12,7 +12,7 @@
 
 `parseCommand()` 识别位于第 0 字节的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方负责各命令专用的语法，只能执行该语法允许的规范化。
 
-处理器返回 `success` 或 `error`，并可附带 UI 文本。若更丰富的呈现由一条更早的领域事件持有，成功的处理器还可返回 `sourceEventSeq`；生命周期不变量要求该引用指向同一会话中更早的一条非命令事件。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息契约。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
+处理器返回 `success` 或 `error`，并可附带 UI 文本。若更丰富的呈现由一条更早的领域事件持有，成功的处理器还可返回 `sourceEventSeq`；生命周期不变量要求该引用指向同一会话中更早的一条非命令事件。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息约定。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
 
 ## 组合
 
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 470dc19e92..e784f2c28b 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
 README.md: 6ad674ebdf8da4fd927a9499e80e06462d3c0dfb
-README.zh.md: 02a192e38aa19b24a34e83b3ddb77d786bbace0b
+README.zh.md: ca51a6f56ab2fa3bf47ca4f400a1474440bb39a4
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 02a192e38a..ca51a6f56a 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -6,7 +6,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 同一 seam 的第二个基于库的实现位于 `@deepseek-ai/dsh-llm-pi-ai`。本包拥有 `deepseek-official` 提供方路由——刻意区别于 pi-ai 的 catalog 名称 `deepseek`，因此同一组合可以并排挂载两条 DeepSeek 路径；而为 `deepseek-official` 本身注册另一个适配器仍会抛出 `LlmError('DUPLICATE_ADAPTER')`。
 
-包根入口导出 Cordis 插件契约与 `DeepSeekAdapter`；协议序列化、SSE 解析与分片转换 helper 不属于该根契约。
+包根入口导出 Cordis 插件约定与 `DeepSeekAdapter`；协议序列化、SSE 解析与分片转换 helper 不属于该根约定。
 
 ## 配置
 
@@ -60,7 +60,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 ## 应用归因
 
-每个请求都携带 dsh-llm `attributionHeaders()` 的共享归因标头，即用于识别 harness 的必需 `User-Agent` 基线（见 [dsh-llm § 应用归因](../llm/README.md#app-attribution-attributionts)）。在该适配器契约（adapter contract）下，直接 DeepSeek 请求与 OpenAI 兼容 gateway 请求都不会获得提供方特定应用归因标头；OpenRouter 应用归因暂缓到未来的显式 OpenRouter 适配器或模式。`GenerateOptions.purpose` 为 `compaction` 的请求（dsh-compact-basic 的辅助摘要调用）还会携带 `x-deepseek-harness-compact: 1`，让宿主可以将压缩流量与会话请求分开。
+每个请求都携带 dsh-llm `attributionHeaders()` 的共享归因标头，即用于识别 harness 的必需 `User-Agent` 基线（见 [dsh-llm § 应用归因](../llm/README.md#app-attribution-attributionts)）。在该适配器约定（adapter contract）下，直接 DeepSeek 请求与 OpenAI 兼容 gateway 请求都不会获得提供方特定应用归因标头；OpenRouter 应用归因暂缓到未来的显式 OpenRouter 适配器或模式。`GenerateOptions.purpose` 为 `compaction` 的请求（dsh-compact-basic 的辅助摘要调用）还会携带 `x-deepseek-harness-compact: 1`，让宿主可以将压缩流量与会话请求分开。
 
 ## 协议格式说明
 
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index a174ba4233..5b2d79f7fb 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/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/llm/token-meter/README.md
 README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
-README.zh.md: 8bdf86517abaff79b78346549ff79b2fff93486a
+README.zh.md: e3908ecea17b16669458f89a6359a432f5b24c0c
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index 8bdf86517a..e3908ecea1 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -8,7 +8,7 @@
 
 估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝，包括已废弃的全局 `contextWindow`；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
 
-## 测量契约
+## 测量约定
 
 `ctx.tokenMeter` 直接公开两个操作：
 
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index 02649a8d39..cceabd1036 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
 README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
-README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
+README.zh.md: a35f870603718ee6b7bcbfdf65f5d689d800447b
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index cc412333e6..a35f870603 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型契约绑定到本地子进程。
+**LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型约定绑定到本地子进程。
 
 该包是 LSP 能力中负责接口的三分之一：
 
@@ -27,7 +27,7 @@
 
 ## 词汇
 
-`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
+`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整约定见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
 
 ## 模型体验
 
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index ff00f20c67..6a3948bc19 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/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/mcp/mcp-client/README.md
 README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: 6537e52eaaea9193d2d95fd0ddf1b4202e5ace38
+README.zh.md: ced1ada5e4a317e37d8601ffe7beaed0e4056aff
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index 6537e52eaa..ced1ada5e4 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -47,7 +47,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 工具命名
 
-每个 MCP 工具都有两个名称：通过 `tools/call` 在协议上传送的原始 MCP 名称，以及公开名称 `mcp__<serverName>__<rawName>`，后者注册到 `ctx.tools`。公开名称会规范化为 DeepSeek 函数名称契约（64 个字符、`[A-Za-z0-9_-]`）；如果替换或截断改变名称，就会追加 `(serverName, rawName)` 的确定性 12 位十六进制 hash，确保不同工具绝不会折叠为同一个名称。名称是 `(serverName, rawName)` 的纯函数：连接顺序、重新同步和其他服务器永远不会重命名工具。
+每个 MCP 工具都有两个名称：通过 `tools/call` 在协议上传送的原始 MCP 名称，以及公开名称 `mcp__<serverName>__<rawName>`，后者注册到 `ctx.tools`。公开名称会规范化为 DeepSeek 函数名称约定（64 个字符、`[A-Za-z0-9_-]`）；如果替换或截断改变名称，就会追加 `(serverName, rawName)` 的确定性 12 位十六进制 hash，确保不同工具绝不会折叠为同一个名称。名称是 `(serverName, rawName)` 的纯函数：连接顺序、重新同步和其他服务器永远不会重命名工具。
 
 - 发布相同原始名称（例如 `search`）的两个服务器会在各自 namespace 下共存。
 - 存活实例中的重复 `serverName` 会使后加载的插件实例失败。
diff --git a/packages/pty/pty/README.i18n.yaml b/packages/pty/pty/README.i18n.yaml
index c7e214563d..19ab05fd45 100644
--- a/packages/pty/pty/README.i18n.yaml
+++ b/packages/pty/pty/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/pty/pty/README.md
 README.md: 0f8b8e499dc81ce91e249f44bb38c8cc1af89d3f
-README.zh.md: b0c2e21a2bd5fca1088908bdde76ff1eb2ee8bfd
+README.zh.md: c1062de5f06cfbebbd10200ed5a835b1ab93b8a0
diff --git a/packages/pty/pty/README.zh.md b/packages/pty/pty/README.zh.md
index b0c2e21a2b..c1062de5f0 100644
--- a/packages/pty/pty/README.zh.md
+++ b/packages/pty/pty/README.zh.md
@@ -4,7 +4,7 @@
 
 限定所有者范围的持久 PTY seam。`PtyService` 注册为 `ctx.pty`，生成不透明的会话 id，通过具名后端路由创建操作，将每个操作限制在完全相同的活跃 `Agent` 内，并在该 agent（智能体）或服务 dispose（资源释放）时等待后端完全停稳。
 
-## 契约
+## 约定
 
 - 后端注册一个稳定的 `type`，并返回尚未发布的 `PtyBackendSession`；失败或取消的设置过程必须清理部分资源。若清理失败，则以 `PtyBackendCleanupError` 拒绝，使注册表能在取消后继续保留该清理失败。
 - spawn 取消会保留调用方提供的确切中止原因。后端设置完成后，服务 dispose 与所有者消失仍分别对应可供机器路由的不同失败。
@@ -38,4 +38,4 @@
 ## 已知限制与暂缓事项
 
 - 会话只存在于进程本地，harness 重启后不会恢复。
-- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限契约。
+- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限约定。
diff --git a/packages/pty/tool-bash-persistent/README.i18n.yaml b/packages/pty/tool-bash-persistent/README.i18n.yaml
index aec30c2b4a..34376a0701 100644
--- a/packages/pty/tool-bash-persistent/README.i18n.yaml
+++ b/packages/pty/tool-bash-persistent/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/pty/tool-bash-persistent/README.md
 README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
-README.zh.md: a525485933344a8f9bc218456c099efdef572902
+README.zh.md: cf35a212159e7d12e1bdaa146b32b397d916a912
diff --git a/packages/pty/tool-bash-persistent/README.zh.md b/packages/pty/tool-bash-persistent/README.zh.md
index a525485933..cf35a21215 100644
--- a/packages/pty/tool-bash-persistent/README.zh.md
+++ b/packages/pty/tool-bash-persistent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具契约和 shell 复用；PTY 后端与沙箱策略由部署选择。
+模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具约定和 shell 复用；PTY 后端与沙箱策略由部署选择。
 
 ## 配置
 
@@ -11,7 +11,7 @@
 | `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
 | `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
 | `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
-| `description` | 持久 shell 描述 | 面向模型的环境契约。 |
+| `description` | 持久 shell 描述 | 面向模型的环境约定。 |
 
 ## 模型体验
 
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 72a03cbfdd..3c29efec12 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/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/sandbox/sandbox/README.md
 README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
-README.zh.md: 1e9ecee967bfc3621d6fb441f405e84896fa7863
+README.zh.md: abc5d387384e3a69e35496d6ce4bc9830185c55d
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index 1e9ecee967..abc5d38738 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
+抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
 用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
index 719a135b37..f038434410 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/scaffold/protocol/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/scaffold/protocol/README.md
 README.md: 88a48957d0d44cec9f776d31eab7d25bd353de5f
-README.zh.md: c662d28ec6eea5fe4829030daf210a91fd70ff0f
+README.zh.md: 6618d8838a00f945c79d7ec24b1e7491df08a3f1
diff --git a/packages/scaffold/protocol/README.zh.md b/packages/scaffold/protocol/README.zh.md
index c662d28ec6..6618d8838a 100644
--- a/packages/scaffold/protocol/README.zh.md
+++ b/packages/scaffold/protocol/README.zh.md
@@ -22,7 +22,7 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 | server→client | `subagent.started` | `SubagentStartedNotification` |
 | server→client | `subagent.finished` | `SubagentFinishedNotification`（仅进程内运行） |
 
-`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时会应用所选适配器的确切模型默认值，否则提供方行为保持不变。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式契约的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。
+`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时会应用所选适配器的确切模型默认值，否则提供方行为保持不变。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式约定的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。
 
 ## 模型体验
 
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index 9c2622086a..75fff04fcd 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
 README.md: 4bf4d979f2d2954cd6280c80bf7f5988d8121fd1
-README.zh.md: aafd4d0a1873090c2101bafb634c3b0d8dcbc6eb
+README.zh.md: 56f7dfa8bad3a04a6bf17eac08b62a1a11f4d53f
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index aafd4d0a18..56f7dfa8ba 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -4,7 +4,7 @@
 
 具体 `ctx.sessionQuery` 后端。`SessionQuerySqlite` 从接口包继承精确读取、跟踪和提供方无关的过滤，并使用 SQLite FTS5 实现其两个全文方法。搜索使用实时优先的逻辑会话语料库，并按每个会话中匹配度最高的事件对跨会话结果分组。
 
-## 搜索契约
+## 搜索约定
 
 `searchSessions(request, exec?)` 返回跨语料库的 `SessionSearchHit` 分页结果；`searchEvents(request, exec?)` 返回单个会话内的 `SessionEventSearchHit` 分页结果。查询不得省略，首尾空白会被移除，内部空白会被规范化，并按字面短语处理。引号、`OR`、`NEAR` 和 `*` 等 FTS5 语法被视为数据，而非可执行 MATCH 语法。元数据过滤器是在排名前应用的参数化 SQL 谓词。为使 SQLite FTS5 MATCH 保持在受支持的外层谓词上下文中，跨会话请求最多可编译 14 个组合会话与事件过滤谓词；会话内请求最多可编译 13 个过滤谓词，因为固定目标会话谓词占用一个槽位。每个范围端点编译为一个谓词。请求超过任一谓词预算，或超过 SQLite 可移植的 32,766 总绑定上限（包括固定查询和分页值）时，会在准备语句前以 `SESSION_QUERY_INVALID_FILTER` 失败。
 
@@ -24,7 +24,7 @@
 
 ## 配置
 
-| 键 | 默认值 | 契约 |
+| 键 | 默认值 | 约定 |
 |---|---:|---|
 | `path` | 必填 | 专用派生索引 SQLite 路径；支持 `:memory:`。在 POSIX 文件系统上，缺失的文件系统路径会以仅所有者可访问的方式创建。 |
 | `openAt` | `startup` | `startup` 会在服务激活完成前打开；`first-search` 把 SQLite 模块与句柄推迟到搜索时再加载和打开。 |
diff --git a/packages/session-query/session-query/README.i18n.yaml b/packages/session-query/session-query/README.i18n.yaml
index 6d801d9d23..423d3f2d90 100644
--- a/packages/session-query/session-query/README.i18n.yaml
+++ b/packages/session-query/session-query/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/session-query/session-query/README.md
 README.md: b75c1f23264cfa7c9323970b3c1a77ddcfe69be0
-README.zh.md: e1b9727ff892047c56d006e02906f3270fb11293
+README.zh.md: 4f1c4749a847326fd9fbc0ffa627651c052ccd71
diff --git a/packages/session-query/session-query/README.zh.md b/packages/session-query/session-query/README.zh.md
index e1b9727ff8..4f1c4749a8 100644
--- a/packages/session-query/session-query/README.zh.md
+++ b/packages/session-query/session-query/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`SessionQueryService` 是组合式抽象 `ctx.sessionQuery` 契约。它对实时 `ctx.sessions` 和可选的动态挂载 `ctx.sessionPersistence` 实现精确会话历史取回、关系跟踪和与提供方无关的过滤；具体后端实现它的两个全文方法。匹配 id 只产生一条记录：实时事件优先，而 `live` 和 `persisted` 会报告两种来源的可用性。如果不可变 header 存在冲突，则以 `SESSION_QUERY_SOURCE_CONFLICT` 失败。
+`SessionQueryService` 是组合式抽象 `ctx.sessionQuery` 约定。它对实时 `ctx.sessions` 和可选的动态挂载 `ctx.sessionPersistence` 实现精确会话历史取回、关系跟踪和与提供方无关的过滤；具体后端实现它的两个全文方法。匹配 id 只产生一条记录：实时事件优先，而 `live` 和 `persisted` 会报告两种来源的可用性。如果不可变 header 存在冲突，则以 `SESSION_QUERY_SOURCE_CONFLICT` 失败。
 
 ## 读取
 
@@ -37,7 +37,7 @@
 
 ## 配置
 
-| 键 | 默认值 | 契约 |
+| 键 | 默认值 | 约定 |
 |---|---:|---|
 | `readWindowMax` | `50` | `before` 或 `after` 的最大原始事件数。 |
 | `persistedInspectConcurrency` | `4` | 一次批量读取中的最大并发持久化日志检查数；必须是正的安全整数。 |
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 5a4c078a55..1ccd0b5286 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/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/session/session-persistence-jsonl/README.md
 README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
-README.zh.md: e260c7671a1f60eec23852ac27ee5da38425b5fd
+README.zh.md: cf044b937f7ae6d0464603a1b59ad9489423ebe0
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index e260c7671a..cf044b937f 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -42,7 +42,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 - **绑定存储身份。** 查找要求可读项目目录中只有一个匹配会话目录，然后验证 header id 等于请求 id，且 header id/cwd 派生所选 transcript 路径。列表应用同一路径检查，并拒绝重复 id。身份失败发生在修复或 append 前。
 - **延迟实体化。**`create(meta)` 不写入；第一次 `append` 将编码 header 和第一批写入临时文件并执行 `fsync`。POSIX 通过硬链接无覆盖发布，并对父目录 `fsync`。Windows 通过 `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` 无覆盖发布，并通过同一 write-through pattern 创建缺失目录。已创建但从未 append 的会话不留下磁盘内容，不在 `list` 中。
 - **仅追加。** 已 flush 事件绝不重写。后续原始批次 append 行；压缩批次 append 一个 frame。两条路径都执行 `fsync`，并在捕获到写入或同步失败时回滚到之前字节长度。
-- **崩溃恢复：保留有效尾部工作。**`load` 验证每个完整压缩 frame，并扫描解压 JSONL。最后 frame 结构不完整时，读取器保留其完整解码记录，从 frame 开头截断，并使用共享[持久化契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) 需要的合成工具、步骤和轮次 closer 重新编码这些记录。原始 mode 从第一个不完整行截断。完整 frame 中的 checksum/解压失败，或位于最后已提交的 `turn/end` 处或之前的缺陷属于损坏，会被拒绝。
+- **崩溃恢复：保留有效尾部工作。**`load` 验证每个完整压缩 frame，并扫描解压 JSONL。最后 frame 结构不完整时，读取器保留其完整解码记录，从 frame 开头截断，并使用共享[持久化约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) 需要的合成工具、步骤和轮次 closer 重新编码这些记录。原始 mode 从第一个不完整行截断。完整 frame 中的 checksum/解压失败，或位于最后已提交的 `turn/end` 处或之前的缺陷属于损坏，会被拒绝。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会截断不完整尾部或更改轻量修订。
 - **连续 seq。**`append` 拒绝第一个 `seq` 不继续已存储日志的批次，并拒绝非 JSON 可序列化 `event.data`，同时命名违规事件类型。
 - **轻量修订。**`listSnapshots(signal?)` 使用 device、inode、size 和纳秒时间戳标识日志，避免解析完整日志；该标识会在 append、修复、替换或存储变更后改变。完整前缀读取要求读取字节前后的身份一致，`readStoredRevision()` 使用同一身份校验保留的 preparation，而不加载日志。快照列表通过产物发现转发精确信号，并在每个 `stat` 前后检查取消；由于文件系统 `stat` 不可中断，取消会等待活动调用完成，然后在不启动另一次调用的情况下拒绝。
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index bb8335b826..41cd655b31 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/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/session/session-persistence-sqlite/README.md
 README.md: 4961f62bf6854c343d35b8406c9d721590274534
-README.zh.md: 237352d1661f505ec0352dfc3eae48d9b636e44a
+README.zh.md: 0507e0fa99bc553317c34e51f30e4daaceee93fd
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index 237352d166..0507e0fa99 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的契约（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
+SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
 
 `locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实、独立的逐会话 transcript（文本记录）路径。
 
-> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；契约接口（`SessionPersistence`）不会变，只更换存储驱动。
+> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；约定接口（`SessionPersistence`）不会变，只更换存储驱动。
 
 ## 存储模型
 
@@ -16,11 +16,11 @@ SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[
 
 在具有 POSIX mode 的文件系统上，后端为缺失目录请求 mode `0700`，并在 SQLite 打开前以 mode `0600` 排他创建缺失数据库；进程 umask 可进一步限制两者。新 WAL、共享内存和持久 rollback-journal sidecar 获得数据库最终的仅所有者 mode。现有目录、数据库文件和 sidecar 保留原 mode；除已存在数据库外的文件系统设置错误会使初始化失败。这些默认值防止宽松进程 umask 造成的意外暴露，但当其他 principal 能替换父目录中的数据库条目时，不保护数据库机密性或完整性。
 
-## 行上的契约语义
+## 行上的约定语义
 
-- **Append = 事务。**`append` 围绕批次运行 `BEGIN`/`COMMIT`：它实体化 `sessions` 行（如果仍延迟），并 INSERT 每个事件，首先断言连续 seq 契约（第一个事件 `seq` 必须等于已存储 next-seq）。批次中失败（重复 seq 上的 UNIQUE 违规）会完全回滚，使已存储日志和内存游标保持一致。（`load()` 已平衡已存储日志，因此 `append` 不必修复崩溃尾部。）
+- **Append = 事务。**`append` 围绕批次运行 `BEGIN`/`COMMIT`：它实体化 `sessions` 行（如果仍延迟），并 INSERT 每个事件，首先断言连续 seq 约定（第一个事件 `seq` 必须等于已存储 next-seq）。批次中失败（重复 seq 上的 UNIQUE 违规）会完全回滚，使已存储日志和内存游标保持一致。（`load()` 已平衡已存储日志，因此 `append` 不必修复崩溃尾部。）
 - **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
-- **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
+- **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会删除撕裂尾部行、追加恢复行或更改轻量修订。
 - **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该修订及其事件行，`readStoredRevision()` 则只查询会话行来校验保留的准备结果。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
 
diff --git a/packages/session/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
index 37c8d986f9..df2eadccfb 100644
--- a/packages/session/session-projection-cache/README.i18n.yaml
+++ b/packages/session/session-projection-cache/README.i18n.yaml
@@ -1,6 +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/session-projection/session-projection-cache/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection-cache/README.md
 README.md: 5d4ad07fab6648acdb40c6aa86d32cc78b4c016e
-README.zh.md: 827480658b8c69647380a782c1a983b390380108
+README.zh.md: 9dfcd645097cc8390812be3aef82b9535fa953eb
diff --git a/packages/session/session-projection-cache/README.zh.md b/packages/session/session-projection-cache/README.zh.md
index 827480658b..9dfcd64509 100644
--- a/packages/session/session-projection-cache/README.zh.md
+++ b/packages/session/session-projection-cache/README.zh.md
@@ -8,7 +8,7 @@
 
 - **每次后台写入都 fail-soft。** 持久写失败只记一条警告并保持缓存陈旧；下一次写入或冷读自愈。两次写之间崩溃的代价是更长的尾部回放，绝不是错误的值。
 - **`ver` 与活单元 `stateVersion` 不匹配即丢弃，绝不迁移。** 单元递增版本会在读取时使其行失效；该 key 从日志重新折叠。
-- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 契约的单元状态会大声失败。
+- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 约定的单元状态会大声失败。
 - **记录绑定到日志生命周期，而不只是 id。** 每条记录存储其折叠来源的 header 身份（`createdAt`、`cwd`）；每次读取先以活 header 或存储 header 为证验证它，再接受任何行——被删后重建的 id、或缓存幸存而持久化存储被换掉时，无关记录被整体丢弃，绝不播种幻影值。
 - **日志领先，缓存跟随。** 活会话检查点先把缓冲事件持久 flush，缓存行才落地，因此崩溃只会让缓存落后于日志（更长的尾部回放），绝不领先于它。
 
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 746d64865d..a39e3c8586 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/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/session/session-projection/README.md
 README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
-README.zh.md: 02f1876fc95b5e400f63ae6a0dd1910da4f63c3b
+README.zh.md: 01b23a7152a509efab6e169043a823d49d6d9fde
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index 02f1876fc9..01b23a7152 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -17,7 +17,7 @@
 - `SessionProjectionMap`——整条链路唯一的 merge-extensible 类型表（host 侧单元、协议块、React 钩子）。值是协议层 JSON 全量值；渲染归 slot 体系管，永远不归本层。
 - `ProjectionDefinition<K, S>`——`{ key, schema, init(), apply(state, event), view(state), stateVersion }`：由三个纯同步函数外加若干声明构成的状态驱动计算单元（state-driven computation unit），绝不是一个不透明的 getter。
 
-## 契约
+## 约定
 
 - **框架负责驱动，领域负责计算。** 注册表只订阅一次 `session/event`；每个已提交事件都会主动经过每个单元的 `apply`。领域不持有任何订阅。cell（每会话每单元一份 `{state, observedSeq}`，以 WeakMap 为键）惰性构建——在事件流过之后才注册的单元，或读取一个早于该注册的会话，都在首次触达时从 `init` 出发在内存日志上折叠。
 - **同引用即无工作。** 对与单元无关的事件，`apply` 必须返回同一个状态引用；驱动以 `Object.is` 把守变更流，因此不匹配的事件只花一次调用，不产生任何下游工作。
@@ -42,6 +42,6 @@
 ## 已知限制与暂缓事项
 
 - **每个尾页携带每个已注册的 key**——尚无逐 key 的 opt-out 或惰性 key 请求形状；在值都是 UI 量级的全量状态（一张 todo 清单、一份 goal 快照）时可以接受，若某领域的值变大再重议。
-- **主动驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，契约不变。
+- **主动驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，约定不变。
 - **注册表 cell 只活在内存里**——重启后首次触达时靠折叠日志重建；挂载了 `dsh-session-projection-cache` 的组合改由持久行播种该折叠。
 - **单元同步纪律只有部分可机械把关**——边界 `schema.parse` 能拒绝返回 Promise 的 `view`，但阻塞的 `apply`、或读取撕裂的非会话状态的 `apply`，只能靠评审把关；invariant 配套记载了为何不存在运行时检查。
diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
index f3a790b362..2897eb7dac 100644
--- a/packages/session/session-telemetry-otel/README.i18n.yaml
+++ b/packages/session/session-telemetry-otel/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/session/session-telemetry-otel/README.md
 README.md: 585995ce409255df9608bc33b76625374bc67669
-README.zh.md: 889e46c24785c21cbb19e980291310ad096e761f
+README.zh.md: 7f0b93363fbb4aebb80f0d3cc8108e58ce3f647f
diff --git a/packages/session/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md
index 889e46c247..7f0b93363f 100644
--- a/packages/session/session-telemetry-otel/README.zh.md
+++ b/packages/session/session-telemetry-otel/README.zh.md
@@ -49,6 +49,6 @@ seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；
 
 ## 已知限制与暂缓事项
 
-- **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 契约不动。
+- **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 约定不动。
 - **真实 collector 行为属于 SDK 导出器**：身份验证、TLS、限流及其他真实 OTLP 部署行为遵循上游 SDK，不由本包自有兼容层处理。
 - **反馈时快照**：`FEEDBACK_ONLY` 在反馈前不保留遥测自有副本。记录反馈时，它读取并脱敏当前的权威日志；反馈前发生崩溃时什么都不上传，而反馈前的策略变更会影响该次回放的导出内容。
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index 3d7e51ebe9..5fd708de38 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/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/session/session-telemetry/README.md
 README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
-README.zh.md: cb251587fc1ce651fe45e1961770a29508f6a1e6
+README.zh.md: 80044ceb57c93f8406398a9239d83cbb6015e98c
diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
index cb251587fc..80044ceb57 100644
--- a/packages/session/session-telemetry/README.zh.md
+++ b/packages/session/session-telemetry/README.zh.md
@@ -4,7 +4,7 @@
 
 遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
-## 后端契约
+## 后端约定
 
 `TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它在 `session/event` 热路径或显式权威日志回放期间同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 模式组合 `TelemetryCoordinator`，并在自身所属的触发器中调用 `captureSession(session, throughSeq?)`。
 
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index 4ae7cd4aa7..a7744c490b 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/README.i18n.yaml
@@ -1,6 +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/session-title/session-title-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-llm/README.md
 README.md: 342687b5aa0cd35a70abf8cc66b3fe80342bce0b
-README.zh.md: f6f39e07d300dbe53faa51514c29699ca1d6a3d2
+README.zh.md: 10496a727baa8a515f831feb425bc3d66ad91b5f
diff --git a/packages/session/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
index f6f39e07d3..10496a727b 100644
--- a/packages/session/session-title-llm/README.zh.md
+++ b/packages/session/session-title-llm/README.zh.md
@@ -6,7 +6,7 @@
 
 此包是普通库，不是 Cordis 插件。提供方插件调用 `registerSessionTitleLlmProvider()`，传入各自节奏与消息选择器；该函数验证共享配置，并将每次修订委派给 `generateSessionTitleWithLlm()`，使各插件的注册、路由、提示词、取消与验证行为不会漂移。
 
-## 路由与失败契约
+## 路由与失败约定
 
 `provider` 和 `model` 覆盖项都是可选的，但必须同时作为非空字符串提供。如果没有这一对取值，辅助模块会使用当前会话已记录 `request/header` 中捕获的确切提供方／模型路由；因此，在任何路由出现前显式刷新时必须提供覆盖项。辅助模块在记录或分发前，依据 `maxInputBytes` 检查最终 JSON 封装用户提示词的大小，包括 seq 字段、包装层与 JSON 转义，而不是将其截断。消费流期间和流完成后都会重新检查超时与调用方取消，因此即使 interceptor 或适配器忽略 abort，也不能接受迟到的成功结果。格式错误或空输出、工具调用和非 stop 结束原因同样会导致调用被拒绝；会话标题服务决定该拒绝属于自动警告还是显式调用方失败。
 
@@ -16,7 +16,7 @@
 
 除成对的路由覆盖项外，每个字段都必填；库不提供默认值。
 
-| 键 | 契约 |
+| 键 | 约定 |
 |---|---|
 | `targetWords` | 非 CJK 标题的正整数目标词数。 |
 | `targetCjkCharacters` | 中文、日文或韩文标题的正整数目标字符数。 |
diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
index f45602ce97..f87ea98542 100644
--- a/packages/session/session-title/README.i18n.yaml
+++ b/packages/session/session-title/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/session/session-title/README.md
 README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db
-README.zh.md: 9e271c044033ce17b5c8c744fe7a9cf433c7f473
+README.zh.md: 075e9e31fc7acbc76f0e3fd7a2642b4d879569d3
diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md
index 9e271c0440..075e9e31fc 100644
--- a/packages/session/session-title/README.zh.md
+++ b/packages/session/session-title/README.zh.md
@@ -21,13 +21,13 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会
 
 所有上限都是必填项；该库不提供默认值。
 
-| 键 | 契约 |
+| 键 | 约定 |
 |---|---|
 | `fallbackMaxWords` | 确定性回退中以空白分隔的最大正整数词数。 |
 | `fallbackMaxBytes` | 回退允许的最大正整数 UTF-8 字节数；不得超过 `maxTitleBytes`。 |
 | `maxTitleBytes` | 接受任何来源标题的最大正整数 UTF-8 字节数。 |
 
-## 提供方契约
+## 提供方约定
 
 提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。
 
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index b2549e6be1..dbbb9ba698 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/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/settings/settings/README.md
 README.md: 0841624e553364fa03f7a1f1209aa72ab13d97e4
-README.zh.md: e8fe4485c2cf6cb6b8710347ebb8dcd1e8424b38
+README.zh.md: 3dbe14a7ce6fc002569eb612f355fa0ff7372ae3
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index e8fe4485c2..3dbe14a7ce 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -18,7 +18,7 @@
 - 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
 - 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。
 
-## 提供方契约
+## 提供方约定
 
 子类实现 `writable`、`load()`、`persist(ns, section)`，可选择为一个本地用户可编辑文件重写 `documentPath` 与 `prepareDocument()`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
 
diff --git a/packages/skill/skill/README.i18n.yaml b/packages/skill/skill/README.i18n.yaml
index 2ca9cbac01..2c6f84ca3a 100644
--- a/packages/skill/skill/README.i18n.yaml
+++ b/packages/skill/skill/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/skill/skill/README.md
 README.md: 3dc2bcfa5775736717bdebcb92329d5655198234
-README.zh.md: d11f90d5a8356f06df63aa249a1f8b5851f36f5f
+README.zh.md: e57e389f9080cfc763916111cf80ea97980f01e7
diff --git a/packages/skill/skill/README.zh.md b/packages/skill/skill/README.zh.md
index d11f90d5a8..e57e389f90 100644
--- a/packages/skill/skill/README.zh.md
+++ b/packages/skill/skill/README.zh.md
@@ -43,13 +43,13 @@
 
 `isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
 
-## 提供方契约
+## 提供方约定
 
 提供方工厂同步运行，并接收一项注册作用域内的控制能力。注册失败或释放时，`control.signal` 会中止；仅当该精确注册仍处于活动状态时，`control.invalidate()` 才会清除已完成目录，因此延迟回调无法影响同名替代项。不可变提供方可以忽略该控制能力。远程设置、身份验证和发现由提供方可等待的 `list(options)` 调用执行。返回数组是完整发现的简写形式；若提供方已收集到可用候选项，却无法建立权威观测，则返回 `{ candidates, complete: false }`。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
 
-注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读契约。
+注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读约定。
 
-违反契约时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败，并省略其结果。显式的不完整观测仍会为 `list()` 和 `get()` 提供其候选项，但会使聚合快照不完整且不可缓存。提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试一次。如果这次重试也被后续修订取代，则返回其候选项，并将结果标为不完整且不予缓存，以免持续触发失效的提供方一直占用调用方。重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突。摘要按 skill 名称排序。
+违反约定时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败，并省略其结果。显式的不完整观测仍会为 `list()` 和 `get()` 提供其候选项，但会使聚合快照不完整且不可缓存。提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试一次。如果这次重试也被后续修订取代，则返回其候选项，并将结果标为不完整且不予缓存，以免持续触发失效的提供方一直占用调用方。重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突。摘要按 skill 名称排序。
 
 定义仍采用渐进式加载。`get()` 每次调用都会向胜出提供方请求正文，而不是在此注册表中缓存正文。若返回定义的名称不同于所选候选项，系统会拒绝该陈旧选择，并由注册表在内部使该精确提供方失效，以便下一次快照重新发现其目录。
 
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index 7e067f4464..4948b880f0 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
 README.md: c3434f90a8f7ab30baa6b237beab6dd9763f9bff
-README.zh.md: 627097b6c481b593523de7ed7951605397724a1c
+README.zh.md: fc80f8a5fee713a6cba1a5c8173c489bfc2c14d8
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index 627097b6c4..fc80f8a5fe 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -24,7 +24,7 @@
 
 ## 词汇
 
-`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整契约见 `src/types.ts`。
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整约定见 `src/types.ts`。
 
 设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
 
diff --git a/packages/storage/storage-sqlite/README.i18n.yaml b/packages/storage/storage-sqlite/README.i18n.yaml
index 468e931933..9a373d4039 100644
--- a/packages/storage/storage-sqlite/README.i18n.yaml
+++ b/packages/storage/storage-sqlite/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/storage/storage-sqlite/README.md
 README.md: efc1b3ca54181a43c067594cc339ccc3a8fea510
-README.zh.md: a2dffe43b8364f203980ac7306c9f3dd64df68d4
+README.zh.md: bcbccf388cda3955fe6cd6501fd9ffb63e4c2a50
diff --git a/packages/storage/storage-sqlite/README.zh.md b/packages/storage/storage-sqlite/README.zh.md
index a2dffe43b8..bcbccf388c 100644
--- a/packages/storage/storage-sqlite/README.zh.md
+++ b/packages/storage/storage-sqlite/README.zh.md
@@ -8,7 +8,7 @@
 
 每行一个文档：每个单元表都会成为一个物理 STRICT 表 `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)`，其中 `value` 是记录的 JSON 文本，因此一个 key 只更新一行（高频变更领域路由到这里而非 JSON 后端的原因）。单元标识位于两个元数据表中：`units` 在单元首次打开时标记其格式版本，描述符不同时以 `version-mismatch` 拒绝；`unit_globals` 保存每个单元的全局单例行。物理布局版本位于 `PRAGMA user_version`；其他任何标记值都会被拒绝（未发布格式，不迁移）。单元名和表名在进入 DDL 之前依据中心的 `UNIT_NAME_RE` 进行验证，因此不会把外部输入插值到 SQL 标识符中。
 
-每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 契约，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致；在计划的介质层提取完成前，该包逐字复用了后者的打开顺序。
+每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致；在计划的介质层提取完成前，该包逐字复用了后者的打开顺序。
 
 ## 配置（schemastery）
 
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
index 6bc638bdc4..2f6508a5e0 100644
--- a/packages/subagent/subagent-claude-code/README.i18n.yaml
+++ b/packages/subagent/subagent-claude-code/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/subagent/subagent-claude-code/README.md
 README.md: e62f60fceea16749296a91377785b81d94d751ca
-README.zh.md: e171524157b2b1696df31753816210d41637a911
+README.zh.md: d83a53ea502db659e575fdac0843f5318cff2fa3
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
index e171524157..d83a53ea50 100644
--- a/packages/subagent/subagent-claude-code/README.zh.md
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
@@ -20,7 +20,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
 
 ## 配置
 
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
index 97c2b9f705..d55f3ab937 100644
--- a/packages/subagent/subagent-codex/README.i18n.yaml
+++ b/packages/subagent/subagent-codex/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/subagent/subagent-codex/README.md
 README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
-README.zh.md: 10c8fcc47a9ab04bca983857bd44ede265c23435
+README.zh.md: b302b9dd865e7b19d0c74c0d1c342edb660c242a
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
index 10c8fcc47a..b302b9dd86 100644
--- a/packages/subagent/subagent-codex/README.zh.md
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
@@ -16,7 +16,7 @@
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
 
 ## 配置
 
@@ -47,7 +47,7 @@
 
 ## 产品兼容性与证据
 
-生产环境的协议层有意只实现这一单次执行契约所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
 
 ## 模型体验
 
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 3973b5dd92..b070f9f5d6 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/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/subagent/subagent-dsh-sdk/README.md
 README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
-README.zh.md: 5b196da8f11d71b065ee8111cec010b62edd896c
+README.zh.md: 8c8551f85951aa8475ab2ce95771e4d54e0ed89a
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index 5b196da8f1..8c8551f859 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程契约：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程约定：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
 
 ## 启动与所有权
 
diff --git a/packages/subagent/subagent-fork/README.i18n.yaml b/packages/subagent/subagent-fork/README.i18n.yaml
index cdfa061695..e40cf9901f 100644
--- a/packages/subagent/subagent-fork/README.i18n.yaml
+++ b/packages/subagent/subagent-fork/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/subagent/subagent-fork/README.md
 README.md: 55475aee7841e91960de79887dfe9bf37afdf9da
-README.zh.md: ef9e4b256931450c0b8664dcc640e000f01c01da
+README.zh.md: 379218970c406162309659277a4fcb2da885d9ea
diff --git a/packages/subagent/subagent-fork/README.zh.md b/packages/subagent/subagent-fork/README.zh.md
index ef9e4b2569..379218970c 100644
--- a/packages/subagent/subagent-fork/README.zh.md
+++ b/packages/subagent/subagent-fork/README.zh.md
@@ -31,7 +31,7 @@ fork 声明 `{ outputSchema: true, depthLimit: true, toolFilter: true, persona:
 
 #### 模型看到的内容
 
-子 agent 先接收由父 agent 已配平的已完成轮次构成的表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的契约。父 agent 当前进行中的轮次会被排除。
+子 agent 先接收由父 agent 已配平的已完成轮次构成的表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的约定。父 agent 当前进行中的轮次会被排除。
 
 #### Token 影响
 
diff --git a/packages/subagent/subagent-inprocess/README.i18n.yaml b/packages/subagent/subagent-inprocess/README.i18n.yaml
index 9bfe1023ee..a6a82fb47f 100644
--- a/packages/subagent/subagent-inprocess/README.i18n.yaml
+++ b/packages/subagent/subagent-inprocess/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/subagent/subagent-inprocess/README.md
 README.md: 67f0cf5dd1ecb18542af56953a0eaa40988aca0d
-README.zh.md: 0cb9008e52088c2a3c554a4ab6a45e2345b34a08
+README.zh.md: 648a160be5f1c3dcbe66a867a273a3df610dbc0a
diff --git a/packages/subagent/subagent-inprocess/README.zh.md b/packages/subagent/subagent-inprocess/README.zh.md
index 0cb9008e52..648a160be5 100644
--- a/packages/subagent/subagent-inprocess/README.zh.md
+++ b/packages/subagent/subagent-inprocess/README.zh.md
@@ -36,7 +36,7 @@
 
 ## 结构化输出
 
-`attachStructuredRuntime(childCtx, schema)` 会在子 agent 作用域中安装完整契约：
+`attachStructuredRuntime(childCtx, schema)` 会在子 agent 作用域中安装完整约定：
 
 - 使用请求 schema 注册的 `structured_output` 工具会校验并暂存模型值。
 - 一个顺序为 190 的系统提示词段会告诉子 agent，该工具调用就是终态答案。
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 23ed818ebb..ca81aa07a6 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
 README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
-README.zh.md: b385182f032da17e7326ac265f47a2a5046f918a
+README.zh.md: 52971add9646fd45a33661bb33b3f7d8c452219c
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index b385182f03..52971add96 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -44,7 +44,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 持久化描述符
 
-该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果契约）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
+该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果约定）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 委派深度
 
@@ -86,7 +86,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 明确报错，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 明确报错。完整约定见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整约定见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
@@ -100,7 +100,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 已知限制与暂缓事项
 
-- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
+- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权约定，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
 - **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。只有 `interrupt()` 接受持久化 parent 地址形式的用户授权，因为停止一个轮次是幂等的且不投递任何内容；未来 host 适配器需要具体的经认证交互，才能让该 seam 获得用户投递能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **取消收敛期间存在唤醒缺口**：中断信号发出后、活动 driver 进入 idle 前被接受的唤醒型 follow-up 会保持排队，直到另一条唤醒发送到达。Issue #1838 负责 agent-loop 的唤醒锁存；普通会话取消也受此影响。
diff --git a/packages/subagent/tool-subagent/README.i18n.yaml b/packages/subagent/tool-subagent/README.i18n.yaml
index a3bfacedda..e5f0c43f61 100644
--- a/packages/subagent/tool-subagent/README.i18n.yaml
+++ b/packages/subagent/tool-subagent/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/subagent/tool-subagent/README.md
 README.md: 6ec313b3b97f0ffa7488025d4314b1c6231a6f6a
-README.zh.md: 13ff7ee6fddd25c062c08b0b18c94323824f54b9
+README.zh.md: 1fd88363b3ade9d57c194580f81295eed139ac50
diff --git a/packages/subagent/tool-subagent/README.zh.md b/packages/subagent/tool-subagent/README.zh.md
index 13ff7ee6fd..1fd88363b3 100644
--- a/packages/subagent/tool-subagent/README.zh.md
+++ b/packages/subagent/tool-subagent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-基于一个已配置 `ctx.subagents` 提供方、面向模型的委派工具。更换提供方只会改变传输，不会改变执行契约。
+基于一个已配置 `ctx.subagents` 提供方、面向模型的委派工具。更换提供方只会改变传输，不会改变执行约定。
 
 ## 提供方选择与生命周期
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index e81656d84a..6da5dc1939 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
 README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
-README.zh.md: 828e8818ce3366bd955d83f7ccb5dab0f0379c46
+README.zh.md: b5d0aac765e433dbaeb9b6e24638ffa6bea6cc51
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 828e8818ce..b5d0aac765 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -4,7 +4,7 @@
 
 子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
-## 契约
+## 约定
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
 - spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
diff --git a/packages/support/README.i18n.yaml b/packages/support/README.i18n.yaml
index 824f20ae7e..8034ca14c0 100644
--- a/packages/support/README.i18n.yaml
+++ b/packages/support/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/support/README.md
 README.md: bf0bba1ea7d21700a6743195ec966512c20e01bc
-README.zh.md: 47eba4d51c66914f388ba4a5925323173d5ed7e2
+README.zh.md: 0ea9c6fdc015682a9008825b15127b2c940e4779
diff --git a/packages/support/README.zh.md b/packages/support/README.zh.md
index 47eba4d51c..0ea9c6fdc0 100644
--- a/packages/support/README.zh.md
+++ b/packages/support/README.zh.md
@@ -8,11 +8,11 @@
 |---|---|
 | [`acp-snapshot/`](acp-snapshot/README.md) | 提供 ACP（Agent Client Protocol）快照测试工具包 |
 | [`agent-loop-testkit/`](agent-loop-testkit/README.md) | 为 AgentLoop 测试挂载共享先决条件 |
-| [`invariants/`](invariants/README.md) | 运行开发期运行时契约断言 |
+| [`invariants/`](invariants/README.md) | 运行开发期运行时约定断言 |
 | [`loader-smoke/`](loader-smoke/README.md) | 启动由 Loader 组合的应用以执行冒烟测试 |
 | [`llm-mock-server/`](llm-mock-server/README.md) | 提供确定性的 OpenAI 兼容故障服务器 |
 | [`llm-replay/`](llm-replay/README.md) | 为无密钥测试和演示回放已记录的模型响应 |
 
-当一个包获得产品契约和产品消费方时，它会移出 `support/`。
+当一个包获得产品约定和产品消费方时，它会移出 `support/`。
 
-不变式契约记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。
+不变式约定记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 25b54630b2..c2aabcac4e 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
 README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 91be3c97bcb67ce10c61513113f683e741bc762f
+README.zh.md: a5fbae98c7eddf827e3747999cf9afeacf636caf
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 91be3c97bc..a5fbae98c7 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -11,7 +11,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
-签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
+签入仓库的会话 fixture 使用规范打包行。合并此约定的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
 消费方 `*.snapshot.ts` 就是场景表加一次工厂调用：
 
diff --git a/packages/support/invariants/README.i18n.yaml b/packages/support/invariants/README.i18n.yaml
index 9d8d8ff16c..44427199b2 100644
--- a/packages/support/invariants/README.i18n.yaml
+++ b/packages/support/invariants/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/support/invariants/README.md
 README.md: 203dbd5ad09f5b1378061fbf9adcff885889eae2
-README.zh.md: fb9d15f3d0cd77f8002c6ff1a909e09e8c6c61fa
+README.zh.md: 10f072e1d49b778944dfc0914eab48c527b21fed
diff --git a/packages/support/invariants/README.zh.md b/packages/support/invariants/README.zh.md
index fb9d15f3d0..10f072e1d4 100644
--- a/packages/support/invariants/README.zh.md
+++ b/packages/support/invariants/README.zh.md
@@ -30,7 +30,7 @@ interface Config {
 
 发布和注册覆盖全部包；但不会为了覆盖全部包而人为编造运行时断言。只有当包拥有可观察事件关系或相关可变数据关系时，配套入口才安装检查。确认必需方法、插件名称、注入、effect 或固定纯函数结果属于类型、加载或单元测试关注点，而非运行时不变量。
 
-如果不存在合理的运行时关系，配套入口使用空 installer，并以包专用的前置 `No runtime invariant:` 注释说明原因。纯工具、行为已通过 seam 观察的薄实现、仅组合包、二进制程序、契约需要崩溃/往返测试的持久化适配器和测试支持包通常属于此类。当 owner 获得可变状态或事件协议时，必须重新审视该说明。
+如果不存在合理的运行时关系，配套入口使用空 installer，并以包专用的前置 `No runtime invariant:` 注释说明原因。纯工具、行为已通过 seam 观察的薄实现、仅组合包、二进制程序、约定需要崩溃/往返测试的持久化适配器和测试支持包通常属于此类。当 owner 获得可变状态或事件协议时，必须重新审视该说明。
 
 当前可执行配套入口保护以下关系：
 
@@ -66,7 +66,7 @@ ctx.plugin(InvariantService, {
 ctx.plugin(SessionInvariant)
 ```
 
-标准 agent 主干挂载服务和 4 个核心有状态配套入口。自定义组合为希望检查其契约的其他已加载包显式添加配套入口；过滤器可以在不改变包入口的情况下禁用或选择注册。
+标准 agent 主干挂载服务和 4 个核心有状态配套入口。自定义组合为希望检查其约定的其他已加载包显式添加配套入口；过滤器可以在不改变包入口的情况下禁用或选择注册。
 
 每个普通 Vitest 拓扑都挂载显式启用的服务和当前测试包的配套入口。聚焦套件覆盖可执行配套入口的合法与违规观测，一个穷尽拓扑则挂载全部配套入口，以证明注册和 dispose 接线。
 
@@ -80,6 +80,6 @@ ctx.plugin(SessionInvariant)
 
 ## 已知限制与暂缓事项
 
-- 请求重建覆盖 loop 在冻结前显式标记的请求；直接一次性 LLM（大语言模型）调用即使由调用方冻结或附加会话 id，仍不在该标记契约内。
+- 请求重建覆盖 loop 在冻结前显式标记的请求；直接一次性 LLM（大语言模型）调用即使由调用方冻结或附加会话 id，仍不在该标记约定内。
 - 仅实时生命周期配套入口无法重建自身重新加载前开始的操作。标准组合和测试组合会在相应操作开始前挂载它们。
 - 正则表达式过滤器在服务生命周期内固定；更改它们需要执行普通 Cordis 插件重新加载。
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index 1d803e486e..e7206370dd 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/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/tasks/tasks/README.md
 README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a
-README.zh.md: f2e4b10d30d81c840f5598141bbe246634bf2884
+README.zh.md: 5cbcfac8d7153616c39642c11860fc88b8495d1f
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index f2e4b10d30..5cbcfac8d7 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-后台任务注册表 seam（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份契约下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
+后台任务注册表 seam（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
 
-## 服务契约
+## 服务约定
 
 - `start(spec): TaskId` 验证控制表层、spec、确切且仍存活的 owner，以及可选的 `outputLimitBytes`（如提供则须为正数），然后只调用生产方的 `run()` 一次。启动方抛出异常时不注册任何内容；成功返回会直接提交，不再执行其他可能失败的步骤。
 - `get(id, caller?)` 和 `list(caller?)` 返回非消费式快照。列表只包含调用方拥有及无 owner 的任务。
@@ -18,7 +18,7 @@
 
 `outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制表层在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
 
-实现还必须兑现契约的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
+实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
 
 参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
 
@@ -34,4 +34,4 @@
 
 - **流输出只有一个消费游标**：独立观察者需要游标或快照 API。
 - **前台工作无法转为后台**：生产方在启动前选择前台或后台。
-- **契约是进程内的**：`TaskStart.run()` 传入回调和确切的 `Agent` 对象；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。
+- **约定是进程内的**：`TaskStart.run()` 传入回调和确切的 `Agent` 对象；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。
diff --git a/packages/typert/registry/README.i18n.yaml b/packages/typert/registry/README.i18n.yaml
index f7193bdd9f..5730472079 100644
--- a/packages/typert/registry/README.i18n.yaml
+++ b/packages/typert/registry/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/typert/registry/README.md
 README.md: fa227b1c8faf1abd5a6492d4b8fe7d0c51ceeef1
-README.zh.md: b3dd820c9a4f23917e85631bedaf68e4fc5803c1
+README.zh.md: b708e536acb7a5c4dc47e8c83180728e2ce150cd
diff --git a/packages/typert/registry/README.zh.md b/packages/typert/registry/README.zh.md
index b3dd820c9a..b708e536ac 100644
--- a/packages/typert/registry/README.zh.md
+++ b/packages/typert/registry/README.zh.md
@@ -17,7 +17,7 @@
 - `toJSONSchema(key, params?)` 使用 `z.toJSONSchema()` 投影当前有效的 schema，且不缓存结果。
 - `typertKey()` 和 `typertPackageKey()` 构造两种稳定的标识形式。
 
-`@deepseek-ai/dsh-typert-registry/types` 子路径包含注册项和记录的纯类型契约。[`dsh-typert-loader`](../loader/README.md) 会在 Loader 组合中发现并注册生成的宿主侧产物；其他组合所有者可以直接调用 `ctx.typert.register()`。
+`@deepseek-ai/dsh-typert-registry/types` 子路径包含注册项和记录的纯类型约定。[`dsh-typert-loader`](../loader/README.md) 会在 Loader 组合中发现并注册生成的宿主侧产物；其他组合所有者可以直接调用 `ctx.typert.register()`。
 
 ## 模型体验
 
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index a61602c07b..c7a3c1c860 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
 README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
-README.zh.md: 10a6309bc47001d572abb3dd3f794ebfcf6252e8
+README.zh.md: 68b690d2143b4420f2e10efceaca0dfc1149d0ff
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 10a6309bc4..68b690d214 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
+该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方约定；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
 
 ## Remote 声明
 
@@ -20,7 +20,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client Remote 使用的共享运行时形式。
 
-查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+查找包与 Context 包同时负责其约定的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ## 模型体验
 
diff --git a/packages/util/README.i18n.yaml b/packages/util/README.i18n.yaml
index 69dbd9afbb..fd63d200f9 100644
--- a/packages/util/README.i18n.yaml
+++ b/packages/util/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/util/README.md
 README.md: b84f2cbb88981aa2edbde65d8a711b28cc5b48e9
-README.zh.md: b1d7ccf14059892d57fb01502f177e0e618058b1
+README.zh.md: 3814dffe1eb8c68f6d38d39aa750c80ce325f9af
diff --git a/packages/util/README.zh.md b/packages/util/README.zh.md
index b1d7ccf140..3814dffe1e 100644
--- a/packages/util/README.zh.md
+++ b/packages/util/README.zh.md
@@ -7,7 +7,7 @@
 | 包 | 职责 |
 |---|---|
 | [`brand/`](brand/README.md) | 提供带名义品牌的类型 |
-| [`paths/`](paths/README.md) | 解析 harness（智能体框架）数据根目录和共享路径 |
+| [`paths/`](paths/README.md) | 解析 Harness 数据根目录和共享路径 |
 | [`timeout/`](timeout/README.md) | 提供截止时间和超时分类原语 |
 | [`retention/`](retention/README.md) | 限制保留文本和项集合的大小 |
 | [`atomic-write/`](atomic-write/README.md) | 以原子方式替换文件 |
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index 33e1f6014b..a56d8ceb56 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/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/util/atomic-write/README.md
 README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
-README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
+README.zh.md: 570a5243aefbe6870c1991786f711adc77faacae
diff --git a/packages/util/atomic-write/README.zh.md b/packages/util/atomic-write/README.zh.md
index 4284d06422..570a5243ae 100644
--- a/packages/util/atomic-write/README.zh.md
+++ b/packages/util/atomic-write/README.zh.md
@@ -20,7 +20,7 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 })
 ```
 
-`writeFileAtomic` 提交一份已经渲染好的字符串。契约按故障利用它的先后顺序列出：
+`writeFileAtomic` 提交一份已经渲染好的字符串。约定按故障利用它的先后顺序列出：
 
 - **独占创建临时文件**（`wx` + 随机后缀）：open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
 - **全新 inode 携带 `mode` 走完 rename**：替换权限过宽的旧文件时直接收窄，不存在 chmod 竞态。`mode` 为必填，让权限决策始终可见于每个调用点（与所有新建 inode 一样受进程 umask 影响）。
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 633064ae4c..2064bef6b6 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
 README.md: 599a9ba747905b66452b57717dabcc6f4678a3dd
-README.zh.md: 69f9c670bbb3ea1b2fbddaa7508a19dfb47fad12
+README.zh.md: ca1da309fda28913ee7b90953d50fc0a7172ca87
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 69f9c670bb..ca1da309fd 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -32,5 +32,5 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 ## Known Limitations and Deferred Work
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 约定](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/packages/util/native-command/README.i18n.yaml b/packages/util/native-command/README.i18n.yaml
index 50116d2ef0..237ad82299 100644
--- a/packages/util/native-command/README.i18n.yaml
+++ b/packages/util/native-command/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/util/native-command/README.md
 README.md: dd9d1ddaf817b2ff77ec0cd01710053e918b4296
-README.zh.md: 339db7f3adb402193ef14247413b02f80b6f728d
+README.zh.md: 3ff8a392f2c511295adb0bf5f62b6e0527cbaea6
diff --git a/packages/util/native-command/README.zh.md b/packages/util/native-command/README.zh.md
index 339db7f3ad..3ff8a392f2 100644
--- a/packages/util/native-command/README.zh.md
+++ b/packages/util/native-command/README.zh.md
@@ -8,7 +8,7 @@
 
 它是**库，不是服务或插件**：没有 `ctx`、不注册任何东西、不持有状态、不发事件。
 
-## Surface
+## 接口面
 
 ```ts
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
diff --git a/packages/web/README.i18n.yaml b/packages/web/README.i18n.yaml
index 0eaedfb018..87177273da 100644
--- a/packages/web/README.i18n.yaml
+++ b/packages/web/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/web/README.md
 README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
-README.zh.md: c7c0546c6a2527ba04bd802945c0dd4ee4353a37
+README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc
diff --git a/packages/web/README.zh.md b/packages/web/README.zh.md
index c7c0546c6a..e328447d5d 100644
--- a/packages/web/README.zh.md
+++ b/packages/web/README.zh.md
@@ -13,6 +13,6 @@
 | [`web-fetch-local/`](web-fetch-local/README.md) | 抓取公共 HTTP 和 HTTPS 资源 | 注册到 `ctx.web` |
 | [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
 
-[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) 记录了搜索和抓取共用一项提供方选择服务的原因。
+[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
 
 子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index 4751678c04..4a1d973a1a 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/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/web/tool-web/README.md
 README.md: 646601bb5bd6c27876918b7aca49962ae34bae33
-README.zh.md: 192b7020f5fac026f325448630b2e17d7ce6a0c4
+README.zh.md: 135c75831045225a0ac6d4637ff5c8b4105336c0
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index 192b7020f5..135c758310 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -37,7 +37,7 @@
 
 ## 稳定注册
 
-工具注册遵循产品**启用状态**，而非后端可用性。即使选中的提供方缺失、错误配置、存在歧义或暂时不可用，工具仍保持可见；seam 在执行时解析提供方，执行以结构化 `WebError`（例如 `WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`）失败，`ToolRegistry.execute()` 会把它转为模型可读、钩子／UI 可路由的错误工具结果。这样无需把插件加载顺序、凭据状态或 HMR（热模块替换）时机纳入面向模型契约，也能保持模型 schema 稳定。要彻底移除 web 工具，请在此处通过配置将其禁用。
+工具注册遵循产品**启用状态**，而非后端可用性。即使选中的提供方缺失、错误配置、存在歧义或暂时不可用，工具仍保持可见；seam 在执行时解析提供方，执行以结构化 `WebError`（例如 `WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`）失败，`ToolRegistry.execute()` 会把它转为模型可读、钩子／UI 可路由的错误工具结果。这样无需把插件加载顺序、凭据状态或 HMR（热模块替换）时机纳入面向模型约定，也能保持模型 schema 稳定。要彻底移除 web 工具，请在此处通过配置将其禁用。
 
 工具绝不会调用提供方的 `available()`，也不会枚举提供方；唯一执行路径是 `ctx.web.search()`／`ctx.web.fetch()`，提供方不可用时，选择机制会在执行阶段抛出结构化 `WebError`，其错误码由工具接收。提供方选择完全留在 seam 内，由单一主体负责。
 
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index a552a7c9b2..4d5ac9d768 100644
--- a/packages/web/web-search-deepseek/README.i18n.yaml
+++ b/packages/web/web-search-deepseek/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/web/web-search-deepseek/README.md
 README.md: 95340314fe08d0963b899f4a1d704a98f85963a5
-README.zh.md: 48d94b64d15e4c0902e5222fe9a737b1e67270fc
+README.zh.md: cf83426f70d6d2a77fd9acf5e927d1b13ec345eb
diff --git a/packages/web/web-search-deepseek/README.zh.md b/packages/web/web-search-deepseek/README.zh.md
index 48d94b64d1..cf83426f70 100644
--- a/packages/web/web-search-deepseek/README.zh.md
+++ b/packages/web/web-search-deepseek/README.zh.md
@@ -79,6 +79,6 @@ DeepSeek 不返回该提供方可作为 `content` 信任的提供方生成答案
 ## 已知限制与暂缓事项
 
 - **一次搜索需要完整的 Messages 模型轮次**：会产生延迟与生成 token，并且最多执行 `maxUses` 次服务器侧搜索；DeepSeek 不公开专用检索端点。
-- **动态凭据的可用性在操作内部解析**：同步的 `available()` 契约可以确认解析器存在，但无法查询异步凭据存储。因此，选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。调用方取消在本地与该预检存在竞态，但无法强制任意凭据后端自行停止工作。
+- **动态凭据的可用性在操作内部解析**：同步的 `available()` 约定可以确认解析器存在，但无法查询异步凭据存储。因此，选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。调用方取消在本地与该预检存在竞态，但无法强制任意凭据后端自行停止工作。
 - **超量返回的源仍消耗 token**：协议没有结果数量旋钮，`maxResults` 只能由 seam 在事后截断。
 - **未引用的结果没有 `snippet`**：只有 `text` 块中的引用（`cited_text`）匹配其 URL 时，源才会获得 snippet。
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index fe4c307b3b..b6c139d63c 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
 README.md: 73765fe060cc0a2b0fa3d69703a670f488a29ac9
-README.zh.md: 3cce0fb528457b566b2c2ab4ffd1f29471255c07
+README.zh.md: bebdb52d6c9bd33db5a982c1f278e71c1882f2de
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index 3cce0fb528..bebdb52d6c 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**web 访问 seam**：抽象 `WebService`（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型契约绑定到某个厂商的 API 形状。
+**web 访问 seam**：抽象 `WebService`（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
 
 该包是 web 能力中负责接口的三分之一。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种能力，每种能力都可能有多个提供方：
 
@@ -43,7 +43,7 @@
 
 ## 词汇
 
-`WebSearchRequest`（`query`、`maxResults?`）→ `WebSearchResult`（`content?`、`sources[]`、`truncated`）；每个 `WebSearchSource` 都有必填 `url` 与可选 `title`／`snippet`／`publishedAt`（Perplexity 引用可能只含 URL）。`WebFetchRequest`（`url`）→ `WebFetchResult`（最终 `url`、`statusCode`、`body`、`truncated`）；取消作为可选的直接 `AbortSignal` 参数传给 `search()`／`fetch()`。`WebFetchBody` 是这里拥有的封闭判别联合（`html` | `text`）；消费方使用 `switch` 实现穷尽检查，因此新增类型会导致编译失败，直到处理完毕。完整契约见 `src/types.ts`，其中也包含 `WebError` code 分类体系。
+`WebSearchRequest`（`query`、`maxResults?`）→ `WebSearchResult`（`content?`、`sources[]`、`truncated`）；每个 `WebSearchSource` 都有必填 `url` 与可选 `title`／`snippet`／`publishedAt`（Perplexity 引用可能只含 URL）。`WebFetchRequest`（`url`）→ `WebFetchResult`（最终 `url`、`statusCode`、`body`、`truncated`）；取消作为可选的直接 `AbortSignal` 参数传给 `search()`／`fetch()`。`WebFetchBody` 是这里拥有的封闭判别联合（`html` | `text`）；消费方使用 `switch` 实现穷尽检查，因此新增类型会导致编译失败，直到处理完毕。完整约定见 `src/types.ts`，其中也包含 `WebError` code 分类体系。
 
 ## 模型体验
 
diff --git a/packages/workflow/README.i18n.yaml b/packages/workflow/README.i18n.yaml
index 1d87cec1bf..05ad673c61 100644
--- a/packages/workflow/README.i18n.yaml
+++ b/packages/workflow/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/workflow/README.md
 README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
-README.zh.md: 8460e22347a6c24b84f12f641479edb78bf1ed1e
+README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
diff --git a/packages/workflow/README.zh.md b/packages/workflow/README.zh.md
index 8460e22347..33b3f26780 100644
--- a/packages/workflow/README.zh.md
+++ b/packages/workflow/README.zh.md
@@ -1,4 +1,4 @@
-# workflow/：动态工作流能力族
+# workflow/：动态工作流能力家族
 
 [English](README.md) | 中文
 
@@ -11,6 +11,6 @@
 | [`tool-workflow/`](tool-workflow/README.md) | 向模型公开通用工作流执行 | 注册到 `ctx.tools` |
 | [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
 
-worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) 和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) 决策。
+worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
 
-子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
+子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
diff --git a/packages/workflow/tool-ralph/README.i18n.yaml b/packages/workflow/tool-ralph/README.i18n.yaml
index 6c560978cb..019495cdfb 100644
--- a/packages/workflow/tool-ralph/README.i18n.yaml
+++ b/packages/workflow/tool-ralph/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/workflow/tool-ralph/README.md
 README.md: daf242364d1093cff30cd1dc95823e1ecb89a9c7
-README.zh.md: c855c6b5f42728f67935208b44601b379364aa7f
+README.zh.md: 92c3256188d9b4c38a292ba7697f702dc46db737
diff --git a/packages/workflow/tool-ralph/README.zh.md b/packages/workflow/tool-ralph/README.zh.md
index c855c6b5f4..92c3256188 100644
--- a/packages/workflow/tool-ralph/README.zh.md
+++ b/packages/workflow/tool-ralph/README.zh.md
@@ -4,7 +4,7 @@
 
 面向模型的 `ralph` 工具运行固定的前台工作流，把一个不可变目标依次交给多个全新子 agent（智能体）。它展示如何把专用编排策略实现为基于 [`ctx.workflows`](../workflow/README.md) 和 [`ctx.subagents`](../../subagent/subagent/README.md) 的普通插件：不会向 `agent-loop` 添加 Ralph 模式或全新 agent loop（智能体循环），同会话的[目标领域](../../goal/goal/README.md)也保持独立。策略和暂缓事项由 [Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)负责。
 
-## 契约
+## 约定
 
 `ralph({ objective, maxRounds? })` 会等待整个运行完成。部署配置中的 `maxRounds` 既是默认值，也是调用覆盖值的上限。每个 Ralph Round 通过 `subagentProvider` 启动一个子 agent；该提供方必须存在、支持结构化输出，并报告 `inheritsParentContext: false`。已配置的提供方以 `WorkflowStartRequest.subagentProvider` 传递，使固定脚本无法检查或更改路由，普通的模型编写 `workflow` 工具也不会因此获得提供方选择器。解析后的 Round 上限还会作为 `WorkflowStartRequest.maxTotalAgents` 传递，使固定循环与引擎的子 agent 总数后备上限协同；Ralph 上限超过引擎部署上限时，引擎会在发布运行前拒绝。
 
@@ -73,7 +73,7 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
 
 #### 模型看到的内容
 
-每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获契约。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
+每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获约定。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
 
 #### Token 影响
 
diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml
index 3c104614bc..66212b2fb9 100644
--- a/packages/workflow/tool-workflow/README.i18n.yaml
+++ b/packages/workflow/tool-workflow/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/workflow/tool-workflow/README.md
 README.md: 5afa68764bfe339377954f8912b6f9b795435be1
-README.zh.md: 9af11811c9a91562983dcd865a0cb1a626cdac3c
+README.zh.md: 7f18c6f54332e11ea54a927ef2d7b723c2601c05
diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md
index 9af11811c9..7f18c6f543 100644
--- a/packages/workflow/tool-workflow/README.zh.md
+++ b/packages/workflow/tool-workflow/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 模型看到的内容
 
-工具有三个参数：`meta`（必需的身份数据：`name`、`description` 和可选的进度注解）、`script`（必需的纯 JavaScript 脚本体，不含 `export const meta` 语句；工具描述包含完整的编写契约）以及 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。插件还会贡献一个 `tool:<toolName>` 系统提示词段，其中包含使用策略：只有用户明确要求工作流／大型编排时才使用该工具；一两项委派优先使用普通 subagent 调用。这遵循工具指导随工具插件交付、绝不放入部署 persona 的约定。
+工具有三个参数：`meta`（必需的身份数据：`name`、`description` 和可选的进度注解）、`script`（必需的纯 JavaScript 脚本体，不含 `export const meta` 语句；工具描述包含完整的编写约定）以及 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。插件还会贡献一个 `tool:<toolName>` 系统提示词段，其中包含使用策略：只有用户明确要求工作流／大型编排时才使用该工具；一两项委派优先使用普通 subagent 调用。这遵循工具指导随工具插件交付、绝不放入部署 persona 的约定。
 
 ## 生命周期
 
@@ -49,7 +49,7 @@ Use the <toolName> tool ONLY when the user explicitly asks for a workflow or for
 
 #### 模型看到的内容
 
-工具可见时，已生成的默认 [`workflow` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workflow) 包含完整的 JavaScript 钩子与元数据契约；`toolName` 可以重命名该定义，模型会提交脚本、元数据和可选 args。
+工具可见时，已生成的默认 [`workflow` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workflow) 包含完整的 JavaScript 钩子与元数据约定；`toolName` 可以重命名该定义，模型会提交脚本、元数据和可选 args。
 
 #### Token 影响
 
diff --git a/packages/workflow/workflow-workerthread/README.i18n.yaml b/packages/workflow/workflow-workerthread/README.i18n.yaml
index b677e2e9e6..c67a1f9630 100644
--- a/packages/workflow/workflow-workerthread/README.i18n.yaml
+++ b/packages/workflow/workflow-workerthread/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/workflow/workflow-workerthread/README.md
 README.md: 9da420bdd67ac5b0a4bfffa312c6fe7b2dabf8f5
-README.zh.md: caba1cf5284c1586fe17e00ed4115ff12e3e4ae9
+README.zh.md: dbed654508bf38bd369247c411d3e8d3a1a749a5
diff --git a/packages/workflow/workflow-workerthread/README.zh.md b/packages/workflow/workflow-workerthread/README.zh.md
index caba1cf528..dbed654508 100644
--- a/packages/workflow/workflow-workerthread/README.zh.md
+++ b/packages/workflow/workflow-workerthread/README.zh.md
@@ -21,7 +21,7 @@ worker 仍提供实用的隔离：
 
 真正的不可信脚本沙箱需要在同一工作流 seam 背后采用不同引擎。
 
-## 脚本契约
+## 脚本约定
 
 工作流的 `meta` 是宿主提供的数据，而不是待求值的脚本文本。引擎会校验必需的 `name` 和 `description`、拒绝未知字段，并在返回运行前检查脚本正文能否解析。
 
diff --git a/packages/workflow/workflow/README.i18n.yaml b/packages/workflow/workflow/README.i18n.yaml
index ac1d7c0506..e56067bf2d 100644
--- a/packages/workflow/workflow/README.i18n.yaml
+++ b/packages/workflow/workflow/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/workflow/workflow/README.md
 README.md: 0de661423206cc71eb4669bc8ddb2419202bcb4a
-README.zh.md: da11b59aa285ea8f4e0e8c18ceab8922d706491a
+README.zh.md: 62abd00c013d054f4111a2db2ce72c58d3514087
diff --git a/packages/workflow/workflow/README.zh.md b/packages/workflow/workflow/README.zh.md
index da11b59aa2..62abd00c01 100644
--- a/packages/workflow/workflow/README.zh.md
+++ b/packages/workflow/workflow/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-工作流 seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
+工作流 seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件约定；引擎负责决定如何隔离并执行脚本。
 
 `@deepseek-ai/dsh-workflow-workerthread` 是当前引擎，`@deepseek-ai/dsh-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。
 
-## 服务与运行契约
+## 服务与运行约定
 
 `WorkflowService.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
 
@@ -31,7 +31,7 @@
 `WorkflowError` 携带一个代码和 `fatal` 标志。致命错误总会逸出 `parallel()` 和 `pipeline()`，而不会变成普通的逐项 `null`：
 
 - `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
-- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎约定；
 - `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
 - `AGENT_START`：提供方的异步启动调用被拒绝；
 - `AGENT_RESULT`：已发布子 agent 的结果因基础设施故障而被拒绝；
diff --git a/packages/workspace/README.i18n.yaml b/packages/workspace/README.i18n.yaml
index 427a7aac69..c7723f6c56 100644
--- a/packages/workspace/README.i18n.yaml
+++ b/packages/workspace/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/workspace/README.md
 README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
-README.zh.md: e59f54ad3d22201304a8126e0b0fbcab79fd17a7
+README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29
diff --git a/packages/workspace/README.zh.md b/packages/workspace/README.zh.md
index e59f54ad3d..6315ccb6b3 100644
--- a/packages/workspace/README.zh.md
+++ b/packages/workspace/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | [`workspace/`](workspace/README.md) | 注册 workspace 并记录其会话归属 | `ctx.workspace` |
 
-[workspace 包参考](workspace/README.md) 负责生命周期、持久化和删除语义。
+[workspace 包参考](workspace/README.md)负责生命周期、持久化和删除语义。
 
 子系统参考——实体、realpath 规范、注册/解析——见 [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md)；存储设计见 [domain KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 137315cf39..f25007786c 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 契约 | | | 如：`pairing contract` →`配对契约` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
@@ -12,7 +12,7 @@
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",
@@ -20,7 +20,7 @@
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
@@ -28,7 +28,7 @@
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
@@ -44,7 +44,7 @@
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",

From b995b12261d6825253eef2b18bea87c9ead9c912 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:14:51 +0800
Subject: [PATCH 179/262] test(fixtures): add private GitHub repository Plugin

---
 .../.dsh-plugin/package.json                        | 13 +++++++++++++
 .../skills/github-source-proof/SKILL.md             |  6 ++++++
 2 files changed, 19 insertions(+)
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md

diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
new file mode 100644
index 0000000000..e8723f671a
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "dsh-github-repository-plugin-e2e-fixture",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "prepare": "dsh-plugin-prepare"
+  },
+  "dsh": {
+    "skills": [
+      "../skills"
+    ]
+  }
+}
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md b/apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md
new file mode 100644
index 0000000000..eae668a4f9
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: github-source-proof
+description: Proves that dsh installed a private repository Plugin from an exact GitHub source.
+---
+
+This skill exists only in the GitHub repository source fixture.

From da2179dd2b034b28fb0fbed52b95628dff51641a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:24:45 +0800
Subject: [PATCH 180/262] test(fixtures): prepare repository Plugin at prepack

---
 .../fixtures/github-repository-plugin/.dsh-plugin/package.json  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
index e8723f671a..9ce1527d03 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "prepare": "dsh-plugin-prepare"
+    "prepack": "dsh-plugin-prepare"
   },
   "dsh": {
     "skills": [

From b91b1fdefe2baa6f76530f7b90f34307efc53e1f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:46:56 +0800
Subject: [PATCH 181/262] fix(repository-plugin): make GitHub source
 preparation self-contained

---
 ...-static-repository-plugin-format.i18n.yaml |  4 +-
 ...6-07-30-static-repository-plugin-format.md |  4 +-
 ...7-30-static-repository-plugin-format.zh.md |  4 +-
 ...it-repository-plugin-preparation.i18n.yaml |  6 ++
 ...owned-git-repository-plugin-preparation.md | 42 +++++++++
 ...ed-git-repository-plugin-preparation.zh.md | 42 +++++++++
 .github/workflows/ci.yml                      |  2 +
 .../github-repository-plugin.built.e2e.ts     | 89 +++++++++++++++++++
 .../app-boot/tests/repository-cache.spec.ts   | 46 ++++++----
 .../repository-plugin/README.i18n.yaml        |  4 +-
 .../repository-plugin/README.md               |  9 +-
 .../repository-plugin/README.zh.md            |  9 +-
 .../repository-plugin/src/format.ts           |  7 +-
 .../repository-plugin/src/index.ts            | 33 ++++---
 .../repository-plugin/src/source.ts           | 79 +++++++++++++++-
 .../tests/repository-plugin.spec.ts           | 64 ++++++++++++-
 scripts/run-gates.spec.ts                     | 22 ++++-
 scripts/run-gates.ts                          | 15 ++++
 vendor/README.md                              |  2 +-
 vendor/loader/src/repository.ts               | 35 ++++++--
 20 files changed, 454 insertions(+), 64 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
 create mode 100644 apps/cli/tests/github-repository-plugin.built.e2e.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 6319b99fb2..40a0461378 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: c9d755b925a6ea05eed71e75803397d2672df9f4
-2026-07-30-static-repository-plugin-format.zh.md: 361de64d2e98b9fb4ac42963e4ae48e77fbc7016
+2026-07-30-static-repository-plugin-format.md: 4823495dabee2101713ac72c8d0cee5bcc6b38d1
+2026-07-30-static-repository-plugin-format.zh.md: e5817ca982a71a609c86c5835b803b12f1317e1a
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index c9d755b925..4823495dab 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -14,7 +14,7 @@ The [package-manager-native repository cache](2026-07-30-package-manager-native-
 
 `@deepseek-ai/dsh-repository-plugin` owns a restricted `.dsh-plugin` package format with two contribution kinds only: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. At least one is required. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths.
 
-The `.dsh-plugin` package declares `dsh-plugin-prepare` as its ordinary package-manager `prepare` script. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. The `.mjs` extension avoids imposing `type: module` on repository-authored package metadata. The generated module is a fixed import-free template containing only a normalized manifest, an `inject` list derived from it (`loader`, plus `skills` and/or `tools` per the declared capabilities, so the wrapper fiber gates on the services its children need), and delegation to the `dsh-repository-plugin` Loader builtin. Preparation never discovers, transpiles, bundles, or preserves a custom repository entry point.
+The `.dsh-plugin` package declares exact `scripts.prepack: "dsh-plugin-prepare"` metadata without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's exact lifecycle metadata before importing that wrapper. The `.mjs` extension avoids imposing `type: module` on repository-authored package metadata. The generated module is a fixed import-free template containing only a normalized manifest, an `inject` list derived from it (`loader`, plus `skills` and/or `tools` per the declared capabilities, so the wrapper fiber gates on the services its children need), and delegation to the `dsh-repository-plugin` Loader builtin. Preparation never discovers, transpiles, bundles, or preserves a custom repository entry point. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 Loading the DSH package registers that builtin as an effect. A generated wrapper mounts the builtin as its child with `import.meta.url`, so all contributions belong to the wrapper fiber and disappear on Loader removal or rollback. The builtin revalidates the prepared manifest and path containment before reading assets. It composes the existing implementations rather than registering skills or MCP tools itself.
 
@@ -46,4 +46,4 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 
 ## Testing
 
-Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The keyless headless example loads a checked-in prepared wrapper through its real `cordis.yml` and snapshots the repository skill's logged model catalog row.
+Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, lets bundled pnpm fetch and prepare a private dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index 361de64d2e..e5817ca982 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -14,7 +14,7 @@
 
 `@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` package 格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
 
-`.dsh-plugin` package 把 `dsh-plugin-prepare` 声明为普通 package-manager `prepare` 脚本。Helper 会校验 metadata 与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。`.mjs` 扩展名避免强迫仓库作者在 package metadata 中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。
+`.dsh-plugin` 包声明精确的 `scripts.prepack: "dsh-plugin-prepare"` 元数据，且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的精确生命周期元数据。`.mjs` 扩展名避免强迫仓库作者在包元数据中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
@@ -46,4 +46,4 @@
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。Keyless headless 示例通过真实 `cordis.yml` 加载一份签入的已准备包装模块，并快照 repository skill 写入日志的模型目录行。
+聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，让随附 pnpm 获取并准备一个私有且不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
new file mode 100644
index 0000000000..55d9045506
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+2026-08-08-host-owned-git-repository-plugin-preparation.md: 45e84f9c8a89bb9d1eb7e4521634d16789dea2f0
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ba88d5bb351427118d55c357209b496b39c2eb98
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
new file mode 100644
index 0000000000..45e84f9c8a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -0,0 +1,42 @@
+# Agent Note: Host-owned preparation makes GitHub repository Plugins installable
+
+Status: implemented
+
+English | [中文](2026-08-08-host-owned-git-repository-plugin-preparation.zh.md)
+
+## Problem
+
+The repository Plugin authoring contract depended on `scripts.prepare: "dsh-plugin-prepare"` and told source repositories to add `@deepseek-ai/dsh-repository-plugin` as a development dependency. That package is private and not published to npm, so an otherwise valid external GitHub repository could not obtain the helper in a clean install.
+
+The lifecycle choice also failed for a selectable `.dsh-plugin` inside a pnpm workspace. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` joins the containing workspace and need not execute the unlisted `.dsh-plugin` package's `prepare` script. The install could therefore succeed and publish a cache generation containing only the source package metadata; real DSH startup failed later because `dsh-plugin.mjs` did not exist.
+
+The checked-in headless fixture did not catch either defect because it mounted an already prepared wrapper. It proved runtime composition, not GitHub acquisition or package preparation.
+
+## Decision
+
+The fixed authoring format now requires exact `scripts.prepack: "dsh-plugin-prepare"` metadata and no DSH dependency. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can still copy sibling repository assets such as `../skills` into the package.
+
+`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
+
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
+
+## Alternatives considered
+
+**Publish the prepare helper to npm.** Rejected because the source package would acquire a release/version dependency solely to call code already owned by the running DSH installation, and the existing helper is intentionally private.
+
+**Keep `prepare` and only inject the command.** Rejected because command availability does not make a nested package's `prepare` lifecycle run when the Git repository's package manager treats it as part of another workspace.
+
+**Prepare after RepositoryCache installs the selected package.** Rejected because pnpm's packed subdirectory no longer contains sibling source assets referenced by paths such as `../skills`; preparation must happen before packlist.
+
+**Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
+
+## Consequences
+
+- A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
+- `prepack`, not `prepare`, is part of the pre-release authoring format. Invalid lifecycle metadata fails during source preparation or installed-package validation instead of producing an ambiguous partial format.
+- Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
+- This repair does not expand the contribution surface: prepared repository Plugins still contribute only declared skills and common MCP definitions, while arbitrary package lifecycle code remains trusted installation code rather than a model-facing Cordis Plugin API.
+
+## Testing
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact live GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
new file mode 100644
index 0000000000..ba88d5bb35
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: 宿主自有的准备机制使 GitHub repository 插件可安装
+
+状态：已实现
+
+[English](2026-08-08-host-owned-git-repository-plugin-preparation.md) | 中文
+
+## 问题
+
+repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`，并要求源码仓库将 `@deepseek-ai/dsh-repository-plugin` 添加为开发依赖。该包是私有包，且未发布到 NPM，因此即使外部 GitHub 仓库符合其他要求，也无法在全新安装中取得该辅助程序。
+
+这种生命周期选择也无法支持 pnpm 工作区内可选的 `.dsh-plugin`。pnpm 会先运行 Git 托管仓库首选的包管理器，再打包选定的子目录，从而准备 Git 托管包。嵌套执行的 `pnpm install` 会加入外层工作区，而不一定执行未列入其中的 `.dsh-plugin` 包的 `prepare` 脚本。因此，安装可能成功并发布一个仅包含源包元数据的缓存 generation；随后真实 DSH 启动因 `dsh-plugin.mjs` 不存在而失败。
+
+签入仓库的 headless fixture（测试前置数据）没有捕获任一缺陷，因为它挂载的是已准备好的包装层。它证明的是运行时组合，而不是 GitHub 获取或包准备。
+
+## 决策
+
+修复后的创作格式要求元数据中精确包含 `scripts.prepack: "dsh-plugin-prepare"`，且不包含 DSH 依赖。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序仍可将 `../skills` 等同仓库的相邻资源复制进包内。
+
+`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
+
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
+
+## 考虑过的替代方案
+
+**把准备辅助程序发布到 NPM。** 拒绝，因为源包会仅为了调用当前运行的 DSH 安装本就拥有的代码，而增加一个需要发布和管理版本的依赖；现有辅助程序又有意保持私有。
+
+**保留 `prepare`，只注入命令。** 拒绝，因为当 Git 仓库的包管理器把嵌套包当作另一工作区的一部分时，即使命令可用，也不会使嵌套包的 `prepare` 生命周期得以运行。
+
+**在 RepositoryCache 安装选定包后再准备。** 拒绝，因为 pnpm 打包后的子目录不再包含 `../skills` 等路径所引用的同仓库相邻资源；准备必须在生成打包清单前完成。
+
+**在 DSH 中克隆 GitHub 仓库，并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定版本的包管理器负责的 ref 解析、子目录选择、依赖安装、打包清单行为和缓存完整性。
+
+## 后果
+
+- 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
+- 预发布创作格式使用 `prepack` 而不是 `prepare`。无效的生命周期元数据会在源码准备或已安装包校验阶段导致失败，而不会留下状态不明的半成品格式。
+- 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
+- 本次修复不扩大贡献范围：已准备的 repository 插件仍只贡献已声明的 skills 和通用 MCP 定义，而任意包生命周期代码仍是受信任的安装代码，不是面向模型的 Cordis 插件 API。
+
+## 测试
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确的真实 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 46ab8e892f..5324df431e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -175,6 +175,8 @@ jobs:
       DSH_NODE_COMPAT_SKIP_TYPECHECK: '1'
       DSH_OXLINT_THREADS: '8'
       DSH_PUBLINT_CONCURRENCY: '8'
+      DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE: >-
+        github:${{ github.event.pull_request.head.repo.full_name }}#${{ github.event.pull_request.head.sha }}&path:/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin
       # Failover halves snapshot concurrency for the shared 64-core VM.
       DSH_SNAPSHOT_MAX_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '12' || '32' }}
     steps:
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
new file mode 100644
index 0000000000..7262ddeb58
--- /dev/null
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -0,0 +1,89 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { startMockLlmServer } from '@deepseek-ai/dsh-llm-mock-server'
+import { execa } from 'execa'
+import { describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const source = process.env.DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE
+const required = process.env.DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E === '1'
+const enabled = required || source !== undefined
+
+describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () => {
+  it('installs a private exact GitHub source and exposes its skill to the model', async () => {
+    expect(existsSync(dshBin), 'the repository Plugin acceptance must run the built dsh entry').toBe(true)
+    expect(source, 'DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE is required by this CI lane').toMatch(
+      /^github:[^/\s#&]+\/[^/\s#&]+#[0-9a-f]{40}&path:\/.*\/\.dsh-plugin$/u,
+    )
+
+    const apiKey = 'github-repository-plugin-e2e-key'
+    const server = await startMockLlmServer({
+      sequence: ['success'],
+      apiKey,
+      successText: 'private GitHub repository Plugin reached dsh run',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-github-repository-plugin-'))
+    const patch = join(home, 'github-repository-plugin.cordis.patch.yml')
+    writeFileSync(patch, [
+      '- id: repository-plugins',
+      '  config:',
+      '    repositories:',
+      `      - ${JSON.stringify(source)}`,
+      '',
+    ].join('\n'))
+
+    try {
+      const result = await execa(process.execPath, [
+        dshBin,
+        'run',
+        '--patch',
+        patch,
+        'prove the private GitHub repository Plugin is active',
+      ], {
+        cwd: repoRoot,
+        input: '',
+        timeout: 120_000,
+        killSignal: 'SIGKILL',
+        reject: false,
+        env: {
+          ...process.env,
+          DSH_HOME: home,
+          DSH_TELEMETRY_DISABLED: '1',
+          DEEPSEEK_API_KEY: apiKey,
+          DEEPSEEK_BASE_URL: server.baseURL,
+        },
+      })
+      if (result.timedOut) {
+        throw new Error(`dsh GitHub repository Plugin run did not exit within 120s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+      }
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}`).toBe(0)
+      expect(result.stdout).toBe('private GitHub repository Plugin reached dsh run')
+      expect(server.requests.length).toBeGreaterThan(0)
+      expect(JSON.stringify(server.requests.map(request => request.body))).toContain(
+        'Proves that dsh installed a private repository Plugin from an exact GitHub source.',
+      )
+
+      const cacheRoot = join(home, 'cache', 'repository-plugins')
+      const generations = readdirSync(cacheRoot, { withFileTypes: true }).filter(entry => entry.isDirectory())
+      expect(generations).toHaveLength(1)
+      const installed = join(cacheRoot, generations[0]!.name, 'node_modules', 'repository')
+      const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8')) as Record<string, unknown>
+      expect(manifest).toMatchObject({
+        name: 'dsh-github-repository-plugin-e2e-fixture',
+        private: true,
+        scripts: { prepack: 'dsh-plugin-prepare' },
+      })
+      expect(manifest).not.toHaveProperty('dependencies')
+      expect(manifest).not.toHaveProperty('devDependencies')
+      expect(readFileSync(join(installed, 'dsh-plugin-assets/skills/0/github-source-proof/SKILL.md'), 'utf8'))
+        .toContain('This skill exists only in the GitHub repository source fixture.')
+      expect(readFileSync(join(installed, 'dsh-plugin.mjs'), 'utf8')).toContain('dsh-repository-plugin')
+    } finally {
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, 130_000)
+})
diff --git a/packages/boot/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
index b7d80470b8..186cbe1b43 100644
--- a/packages/boot/app-boot/tests/repository-cache.spec.ts
+++ b/packages/boot/app-boot/tests/repository-cache.spec.ts
@@ -36,14 +36,14 @@ describe('RepositoryCache', () => {
       calls.push(directory)
       await fakePackage(directory)
     }
-    const cache = new RepositoryCache(root, install)
+    const cache = new RepositoryCache(root, { install })
     const specifier = 'github:owner/repository#0123456789abcdef'
 
     const [first, concurrent] = await Promise.all([cache.resolve(specifier), cache.resolve(specifier)])
     expect(concurrent).toBe(first)
     expect(calls).toHaveLength(1)
 
-    const reopened = new RepositoryCache(root, async () => { throw new Error('cache miss') })
+    const reopened = new RepositoryCache(root, { install: async () => { throw new Error('cache miss') } })
     expect(await reopened.resolve(specifier)).toBe(first)
     expect(JSON.parse(await readFile(join(first, '..', '..', 'package.json'), 'utf8'))).toMatchObject({
       packageManager: `pnpm@${BUNDLED_PNPM_VERSION}`,
@@ -68,8 +68,8 @@ describe('RepositoryCache', () => {
     const specifier = 'github:owner/repository#race'
 
     const [first, second] = await Promise.all([
-      new RepositoryCache(root, install).resolve(specifier),
-      new RepositoryCache(root, install).resolve(specifier),
+      new RepositoryCache(root, { install }).resolve(specifier),
+      new RepositoryCache(root, { install }).resolve(specifier),
     ])
 
     expect(second).toBe(first)
@@ -80,11 +80,11 @@ describe('RepositoryCache', () => {
   it('removes a failed staging tree and permits an exact retry', async () => {
     const root = await temporaryRoot('repository-retry')
     let attempts = 0
-    const cache = new RepositoryCache(root, async (directory) => {
+    const cache = new RepositoryCache(root, { install: async (directory) => {
       attempts += 1
       if (attempts === 1) throw new Error('install failed')
       await fakePackage(directory)
-    })
+    } })
 
     await expect(cache.resolve('github:owner/repository#ref')).rejects.toThrow('failed to prepare repository')
     expect(await readdir(root)).toEqual([])
@@ -94,7 +94,7 @@ describe('RepositoryCache', () => {
 
   it('rejects empty or padded specifiers before touching the cache', async () => {
     const root = await temporaryRoot('repository-input')
-    const cache = new RepositoryCache(root, fakePackage)
+    const cache = new RepositoryCache(root, { install: fakePackage })
     expect(() => cache.resolve('')).toThrow('non-empty unpadded string')
     expect(() => cache.resolve(' github:owner/repository#ref')).toThrow('non-empty unpadded string')
     await expect(readdir(root)).resolves.toEqual([])
@@ -107,7 +107,7 @@ describe('RepositoryCache', () => {
     const entry = join(root, key)
     await mkdir(join(entry, 'node_modules', 'repository'), { recursive: true })
     await writeFile(join(entry, '.repository-cache.json'), '{}\n')
-    const cache = new RepositoryCache(root, async () => { throw new Error('must not reinstall') })
+    const cache = new RepositoryCache(root, { install: async () => { throw new Error('must not reinstall') } })
 
     await expect(cache.resolve(specifier)).rejects.toThrow('repository cache marker is invalid')
   })
@@ -115,6 +115,22 @@ describe('RepositoryCache', () => {
   it('selects and prepares a root .dsh-plugin Git subpath through the bundled pnpm', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
+    const executableDirectory = join(root, 'bin')
+    await mkdir(executableDirectory)
+    await writeFile(join(executableDirectory, 'dsh-plugin-prepare'), [
+      '#!/usr/bin/env node',
+      "const { cpSync, mkdirSync, writeFileSync } = require('node:fs')",
+      "mkdirSync('dsh-plugin-assets/skills', { recursive: true })",
+      "cpSync('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
+      "writeFileSync('dsh-plugin.mjs', 'export function apply() {}\\n')",
+      "writeFileSync('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
+      '',
+    ].join('\n'), { mode: 0o700 })
+    await writeFile(join(executableDirectory, 'dsh-plugin-prepare.cmd'), [
+      '@echo off',
+      'node "%~dp0\\dsh-plugin-prepare" %*',
+      '',
+    ].join('\r\n'))
     await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
     await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
@@ -125,17 +141,9 @@ describe('RepositoryCache', () => {
     await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
       name: 'repository-plugin-fixture',
       version: '1.0.0',
-      scripts: { prepare: 'node prepare.mjs' },
+      scripts: { prepack: 'dsh-plugin-prepare' },
       dsh: { skills: ['../skills'] },
     })}\n`)
-    await writeFile(join(repository, '.dsh-plugin', 'prepare.mjs'), [
-      "import { cp, mkdir, writeFile } from 'node:fs/promises'",
-      "await mkdir('dsh-plugin-assets/skills', { recursive: true })",
-      "await cp('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
-      "await writeFile('dsh-plugin.mjs', 'export function apply() {}\\n')",
-      "await writeFile('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
-      '',
-    ].join('\n'))
     await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
     await execFileAsync('git', ['add', '.'], { cwd: repository })
     await execFileAsync('git', [
@@ -148,7 +156,9 @@ describe('RepositoryCache', () => {
     vi.stubEnv('REPOSITORY_TEST_VISIBLE', 'visible')
     vi.stubEnv('REPOSITORY_TEST_TOKEN', 'hidden')
 
-    const installed = await new RepositoryCache(join(root, 'cache')).resolve(specifier)
+    const installed = await new RepositoryCache(join(root, 'cache'), {
+      executableDirectories: [executableDirectory],
+    }).resolve(specifier)
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
     await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
     await expect(readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8'))
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index e0ce60a641..c75c82dc84 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
-README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b
+README.md: e0b45dc5fd40b5d1005598ae100d23ca7d0b6ec9
+README.zh.md: 30f200d2b7188d88e4a5e4e566cf3394f799933a
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 33cd763d7d..e0b45dc5fd 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -14,10 +14,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "prepare": "dsh-plugin-prepare"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-repository-plugin": "^0.0.1"
+    "prepack": "dsh-plugin-prepare"
   },
   "dsh": {
     "skills": ["../skills"],
@@ -26,7 +23,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
 }
 ```
 
-`dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
+`scripts.prepack` must be exactly `dsh-plugin-prepare`. DSH supplies that command from its own installed runtime while preparing Git source, so the repository package needs no DSH or npm dependency. `dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
 
 ## Standalone app configuration
 
@@ -47,7 +44,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-`dsh-plugin-prepare` validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point.
+During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. The command validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained the exact `prepack` declaration. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point. Failure to run or complete preparation fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 The containing package manager still runs the configured repository package's lifecycle scripts. This restriction defines the supported DSH contribution surface; it is not a security boundary for a repository that the user chose to install as executable package-manager source.
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 903dfbe601..30f200d2b7 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -14,10 +14,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "prepare": "dsh-plugin-prepare"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-repository-plugin": "^0.0.1"
+    "prepack": "dsh-plugin-prepare"
   },
   "dsh": {
     "skills": ["../skills"],
@@ -26,7 +23,7 @@
 }
 ```
 
-`dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
+`scripts.prepack` 必须精确设为 `dsh-plugin-prepare`。DSH 会在准备 Git 源时由已安装的运行时提供该命令，因此仓库包无需添加 DSH 或 NPM 依赖。`dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
 
 ## 独立应用配置
 
@@ -47,7 +44,7 @@
 
 ## 准备阶段
 
-`dsh-plugin-prepare` 校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。
+安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。该命令校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装模块前，DSH 会重新校验已安装包是否仍保留精确的 `prepack` 声明。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。准备阶段未运行或未完成时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 外层包管理器仍会运行已配置仓库包的生命周期脚本。这里的限制只定义 DSH 所支持的贡献表面；对于用户选择以可执行包管理器源安装的仓库，它并不是安全边界。
 
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 9d66321087..654e37c201 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -14,6 +14,8 @@ export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
 export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
 /** Loader builtin used by every generated import-free wrapper. */
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
+/** Exact host-owned command required by the repository package `prepack` lifecycle. */
+export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
 
 const sourceMetadataSchema = z.object({
   skills: z.array(z.string().min(1)).default([]),
@@ -23,6 +25,9 @@ const sourceMetadataSchema = z.object({
 })
 const sourcePackageSchema = z.looseObject({
   name: z.string().min(1),
+  scripts: z.looseObject({
+    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+  }),
   dsh: sourceMetadataSchema,
 })
 const preparedManifestSchema = z.object({
@@ -148,7 +153,7 @@ export async function prepareDshPlugin(directory: string = process.cwd()): Promi
     throw new Error(`failed to read DSH plugin package metadata in ${pluginDirectory}`, { cause })
   }
   const parsed = sourcePackageSchema.safeParse(packageValue)
-  if (!parsed.success) throw formatZodError('invalid package.json#dsh', parsed.error)
+  if (!parsed.success) throw formatZodError('invalid DSH plugin package.json', parsed.error)
 
   const sourceRoot = await realpath(dirname(pluginDirectory))
   const skillSources: string[] = []
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index 73eb2dc473..d3d287974f 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -20,6 +20,7 @@ import {
 } from './format.ts'
 import { parseMcpDocument, resolveMcpServers } from './mcp.ts'
 import {
+  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -29,6 +30,7 @@ export {
   PREPARED_ASSET_DIRECTORY,
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_BUILTIN,
+  REPOSITORY_PLUGIN_PREPARE_COMMAND,
   prepareDshPlugin,
   type PreparedPluginManifest,
 } from './format.ts'
@@ -129,17 +131,24 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   if (new Set(repositories).size !== repositories.length) {
     throw new Error('repository sources must resolve to unique exact specifiers')
   }
-  const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir))
-  await ctx.effect(async function* () {
-    ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
-    yield () => {
-      if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
-        Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
+  const prepareCommand = repositories.length === 0 ? undefined : await createRepositoryPrepareCommand()
+  try {
+    const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir), {
+      executableDirectories: prepareCommand === undefined ? [] : [prepareCommand.directory],
+    })
+    await ctx.effect(async function* () {
+      ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
+      yield () => {
+        if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
+          Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
+        }
       }
-    }
-    for (const repository of repositories) {
-      const plugin = await loadPreparedRepository(ctx, cache, repository)
-      yield plugin.dispose
-    }
-  }, 'repository-plugin runtime and sources')
+      for (const repository of repositories) {
+        const plugin = await loadPreparedRepository(ctx, cache, repository)
+        yield plugin.dispose
+      }
+    }, 'repository-plugin runtime and sources')
+  } finally {
+    await prepareCommand?.dispose()
+  }
 }
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index 0befb82e42..e8a9e9b9cc 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -3,12 +3,18 @@
  * @module
  */
 
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import type { Context, Fiber, FiberState, Plugin } from 'cordis'
 import type { RepositoryCache } from '@cordisjs/plugin-loader/repository'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
-import { PREPARED_ENTRY_FILENAME } from './format.ts'
+import { z } from 'zod'
+import {
+  PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_PREPARE_COMMAND,
+} from './format.ts'
 
 // Value mirror: Cordis's const enum has no runtime object to import. Keep
 // aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts`.
@@ -17,11 +23,66 @@ const FIBER_ACTIVE = 2 as FiberState.ACTIVE
 /** Directory under the Harness home containing immutable repository generations. */
 export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
 
+/** Temporary host command supplied to repository package lifecycle scripts. */
+export interface RepositoryPrepareCommand {
+  /** Absolute directory to prepend to the isolated install's executable search path. */
+  directory: string
+  /** Remove the temporary command directory. */
+  dispose(): Promise<void>
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+function batchQuote(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`
+}
+
+/**
+ * Materialize the DSH-owned prepare executable used only while pnpm packs Git source.
+ * @returns a command directory and its idempotent cleanup operation.
+ */
+export async function createRepositoryPrepareCommand(): Promise<RepositoryPrepareCommand> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-repository-plugin-bin-'))
+  const target = fileURLToPath(new URL('../lib/bin.js', import.meta.url))
+  try {
+    await Promise.all([
+      writeFile(join(directory, REPOSITORY_PLUGIN_PREPARE_COMMAND), [
+        '#!/bin/sh',
+        `exec ${shellQuote(process.execPath)} ${shellQuote(target)} "$@"`,
+        '',
+      ].join('\n'), { mode: 0o700 }),
+      writeFile(join(directory, `${REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), [
+        '@echo off',
+        `${batchQuote(process.execPath)} ${batchQuote(target)} %*`,
+        '',
+      ].join('\r\n'), { mode: 0o700 }),
+    ])
+  } catch (cause) {
+    /* v8 ignore next -- requires a host filesystem failure after mkdtemp; cleanup semantics are the contract under test. */
+    await rm(directory, { recursive: true, force: true })
+    /* v8 ignore next -- preserves that unstageable host failure after best-effort cleanup. */
+    throw cause
+  }
+  return {
+    directory,
+    async dispose() {
+      await rm(directory, { recursive: true, force: true })
+    },
+  }
+}
+
 // The ref segment excludes `#` so `github:o/r#a#b` fails here — at the config
 // parser, with the syntax the error message promises — instead of inside the
 // cache's pnpm install ('misconfiguration fails loud at the earliest
 // resolvable point').
 const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
+const installedPackageSchema = z.looseObject({
+  scripts: z.looseObject({
+    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+  }),
+})
 
 function validPluginPath(path: string): boolean {
   const segments = path.split('/').slice(1)
@@ -57,6 +118,19 @@ export function resolveRepositoryCacheDirectory(configured: string | undefined):
   return resolve(configured ?? join(resolveDshHome(), 'cache', DEFAULT_REPOSITORY_CACHE_DIRECTORY))
 }
 
+async function assertInstalledPackageMetadata(directory: string): Promise<void> {
+  let value: unknown
+  try {
+    value = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')) as unknown
+  } catch (cause) {
+    throw new Error(`failed to read installed DSH plugin package metadata in ${directory}`, { cause })
+  }
+  const result = installedPackageSchema.safeParse(value)
+  if (!result.success) {
+    throw new Error(`installed DSH plugin package must declare scripts.prepack as ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
+  }
+}
+
 /**
  * Load one exact repository generation's generated wrapper as a child Cordis fiber.
  * @param ctx - repository runtime context that owns the child.
@@ -73,6 +147,7 @@ export async function loadPreparedRepository(
   const directory = await cache.resolve(specifier)
   const filename = join(directory, PREPARED_ENTRY_FILENAME)
   try {
+    await assertInstalledPackageMetadata(directory)
     const plugin = await import(/* @vite-ignore */pathToFileURL(filename).href) as Plugin
     const fiber = ctx.plugin(plugin)
     await fiber
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 39840fd1f3..d026a4e14c 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -14,6 +14,7 @@ import * as RepositoryPlugin from '@deepseek-ai/dsh-repository-plugin'
 import * as RepositoryPluginInvariant from '@deepseek-ai/dsh-repository-plugin/invariant'
 import { parsePreparedPluginConfig } from '../src/format.ts'
 import {
+  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -30,7 +31,12 @@ async function temporaryDirectory(name: string): Promise<string> {
 async function writePlugin(root: string, name: string, dsh: Record<string, unknown>): Promise<string> {
   const directory = join(root, '.dsh-plugin')
   await mkdir(directory, { recursive: true })
-  await writeFile(join(directory, 'package.json'), `${JSON.stringify({ name, version: '0.0.0', dsh }, undefined, 2)}\n`)
+  await writeFile(join(directory, 'package.json'), `${JSON.stringify({
+    name,
+    version: '0.0.0',
+    scripts: { prepack: RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND },
+    dsh,
+  }, undefined, 2)}\n`)
   return directory
 }
 
@@ -102,6 +108,16 @@ describe('dsh-plugin-prepare', () => {
     await writeFile(join(malformed, 'package.json'), '{')
     await expect(RepositoryPlugin.prepareDshPlugin(malformed)).rejects.toThrow('failed to read DSH plugin package metadata')
 
+    const lifecycleRoot = await temporaryDirectory('wrong-lifecycle')
+    const lifecycle = join(lifecycleRoot, '.dsh-plugin')
+    await mkdir(lifecycle)
+    await writeFile(join(lifecycle, 'package.json'), JSON.stringify({
+      name: 'wrong-lifecycle',
+      scripts: { prepare: 'dsh-plugin-prepare' },
+      dsh: { skills: ['../skills'] },
+    }))
+    await expect(RepositoryPlugin.prepareDshPlugin(lifecycle)).rejects.toThrow('prepack')
+
     const emptyRoot = await temporaryDirectory('empty-metadata')
     const empty = await writePlugin(emptyRoot, 'empty', {})
     await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root or mcpServers file')
@@ -272,6 +288,17 @@ describe('prepared repository plugin Loader composition', () => {
 })
 
 describe('configured GitHub repository sources', () => {
+  it('creates host-owned prepare commands and removes them idempotently', async () => {
+    const command = await createRepositoryPrepareCommand()
+    expect(await readFile(join(command.directory, RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND), 'utf8'))
+      .toContain(process.execPath)
+    expect(await readFile(join(command.directory, `${RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), 'utf8'))
+      .toContain(process.execPath)
+    await command.dispose()
+    await command.dispose()
+    await expect(stat(command.directory)).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
   it('defaults an omitted source list and rejects unknown configuration fields', () => {
     expect(RepositoryPlugin.Config.parse(undefined)).toEqual({ repositories: [] })
     expect(RepositoryPlugin.Config.safeParse({ repositories: [], unexpected: true }).success).toBe(false)
@@ -439,12 +466,43 @@ describe('configured GitHub repository sources', () => {
 
   it('labels a missing prepared wrapper with its exact source and path', async () => {
     const root = await temporaryDirectory('missing-wrapper')
+    const directory = await writePlugin(root, 'missing-wrapper', { skills: ['../skills'] })
     const ctx = new Context()
     const specifier = 'github:owner/repository#missing&path:/.dsh-plugin'
-    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, specifier))
+    await expect(loadPreparedRepository(ctx, { resolve: async () => directory }, specifier))
       .rejects.toThrow(`failed to load prepared repository Plugin ${JSON.stringify(specifier)}`)
     await ctx.fiber.dispose()
   })
+
+  it('rejects installed source with the obsolete prepare lifecycle', async () => {
+    const root = await temporaryDirectory('installed-lifecycle')
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'installed-lifecycle',
+      scripts: { prepare: 'dsh-plugin-prepare' },
+    }))
+    const ctx = new Context()
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#old&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining('must declare scripts.prepack') as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
+
+  it('labels missing installed package metadata with its source', async () => {
+    const root = await temporaryDirectory('missing-installed-metadata')
+    const ctx = new Context()
+    const specifier = 'github:owner/repository#damaged&path:/.dsh-plugin'
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, specifier))
+      .rejects.toMatchObject({
+        message: expect.stringContaining(JSON.stringify(specifier)) as string,
+        cause: expect.objectContaining({
+          message: expect.stringContaining('failed to read installed DSH plugin package metadata') as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
 })
 
 describe('repository plugin invariant companion', () => {
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index c7b8a7d2c9..5c4ba9899a 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -218,7 +218,7 @@ describe('Node 24 lane ownership', () => {
     const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
 
     expect(defaultConcurrency('ci-consumers', subject.length, 4)).toEqual({
-      workers: 10,
+      workers: 11,
       source: 'ci-consumers gate count',
     })
     expect(subject.map(item => item.id)).toEqual([
@@ -232,11 +232,19 @@ describe('Node 24 lane ownership', () => {
       'doc-typecheck',
       'node-next-types',
       'built-bin-smoke',
+      'github-repository-plugin-e2e',
     ])
     expect(subject.find(item => item.id === 'publint')?.needs).toEqual(['build'])
     expect(subject.find(item => item.id === 'built-package-invariants')?.needs).toEqual(['publint'])
     expect(subject.find(item => item.id === 'lint-and-duplication')?.needs).toEqual(['built-package-invariants'])
-    for (const id of ['snapshot', 'web-snapshot', 'doc-typecheck', 'node-next-types', 'built-bin-smoke']) {
+    for (const id of [
+      'snapshot',
+      'web-snapshot',
+      'doc-typecheck',
+      'node-next-types',
+      'built-bin-smoke',
+      'github-repository-plugin-e2e',
+    ]) {
       expect(subject.find(item => item.id === id)?.needs).toEqual(['built-package-invariants'])
     }
     expect(subject.find(item => item.id === 'snapshot')?.env).toEqual({ DSH_EXAMPLE_MODE: 'lib' })
@@ -249,6 +257,16 @@ describe('Node 24 lane ownership', () => {
         'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
       ]),
     )
+    const githubRepositoryPlugin = subject.find(item => item.id === 'github-repository-plugin-e2e')
+    expect(githubRepositoryPlugin).toMatchObject({
+      label: 'GitHub repository Plugin dsh run',
+      env: {
+        DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E: '1',
+      },
+    })
+    expect(githubRepositoryPlugin?.args).toEqual(
+      expect.arrayContaining(['apps/cli/tests/github-repository-plugin.built.e2e.ts']),
+    )
     expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
       displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
       env: { DSH_SNAPSHOT: 'replay' },
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index d99889d28b..3bd0e11987 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -406,6 +406,7 @@ function ciConsumerGates(): Gate[] {
       needs: validatedBuild,
     }),
     builtBinSmokeGate(validatedBuild),
+    githubRepositoryPluginE2eGate(validatedBuild),
   ]
 }
 
@@ -636,6 +637,20 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
   })
 }
 
+function githubRepositoryPluginE2eGate(needs: string[]): Gate {
+  return pnpmExec('github-repository-plugin-e2e', [
+    'vitest',
+    'run',
+    '--config',
+    'vitest.e2e.config.ts',
+    'apps/cli/tests/github-repository-plugin.built.e2e.ts',
+  ], {
+    label: 'GitHub repository Plugin dsh run',
+    needs,
+    env: { DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E: '1' },
+  })
+}
+
 /**
  * Reject a gate list whose graph cannot be executed unambiguously.
  * @param gates - complete aggregate to validate.
diff --git a/vendor/README.md b/vendor/README.md
index 02e33ea723..3cc2a313d2 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -39,7 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
 9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` run through the bundled pnpm and an injected command directory.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
diff --git a/vendor/loader/src/repository.ts b/vendor/loader/src/repository.ts
index 94a0c5cf16..c0cd1589aa 100644
--- a/vendor/loader/src/repository.ts
+++ b/vendor/loader/src/repository.ts
@@ -8,7 +8,7 @@ import { spawn } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { dirname, join, resolve } from 'node:path'
+import { delimiter, dirname, join, resolve } from 'node:path'
 
 /** Exact pnpm release shipped with the Loader for repository installation. */
 export const BUNDLED_PNPM_VERSION = '11.7.0'
@@ -21,6 +21,14 @@ const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i
 /** Injectable isolated-install boundary used by {@link RepositoryCache}. */
 export type RepositoryInstall = (directory: string) => Promise<void>
 
+/** Installation controls for {@link RepositoryCache}. */
+export interface RepositoryCacheOptions {
+  /** Override the isolated package installation boundary. */
+  install?: RepositoryInstall
+  /** Command directories resolved absolutely and prepended to package lifecycle `PATH`. */
+  executableDirectories?: readonly string[]
+}
+
 interface CacheMarker {
   specifier: string
 }
@@ -29,12 +37,26 @@ function scrubEnvironment(environment: NodeJS.ProcessEnv = process.env): NodeJS.
   return Object.fromEntries(Object.entries(environment).filter(([name]) => !SENSITIVE_ENV_PATTERN.test(name)))
 }
 
+function installEnvironment(executableDirectories: readonly string[]): NodeJS.ProcessEnv {
+  const scrubbed = scrubEnvironment()
+  if (executableDirectories.length === 0) return scrubbed
+  const path = Object.entries(scrubbed).find(([name]) => name.toUpperCase() === 'PATH')?.[1]
+  const withoutPath = Object.fromEntries(Object.entries(scrubbed).filter(([name]) => name.toUpperCase() !== 'PATH'))
+  return {
+    ...withoutPath,
+    PATH: [...executableDirectories, ...(path === undefined ? [] : [path])].join(delimiter),
+  }
+}
+
 function appendOutput(current: string, chunk: Uint8Array): string {
   const combined = current + Buffer.from(chunk).toString('utf8')
   return combined.length <= MAX_ERROR_OUTPUT ? combined : combined.slice(-MAX_ERROR_OUTPUT)
 }
 
-async function installWithBundledPnpm(directory: string): Promise<void> {
+async function installWithBundledPnpm(
+  directory: string,
+  executableDirectories: readonly string[],
+): Promise<void> {
   const require = createRequire(import.meta.url)
   const pnpmManifest = require.resolve('pnpm')
   const pnpmBin = join(dirname(pnpmManifest), 'bin', 'pnpm.mjs')
@@ -47,7 +69,7 @@ async function installWithBundledPnpm(directory: string): Promise<void> {
       '--reporter=append-only',
     ], {
       cwd: directory,
-      env: scrubEnvironment(),
+      env: installEnvironment(executableDirectories),
       shell: false,
       stdio: ['ignore', 'pipe', 'pipe'],
     })
@@ -122,13 +144,16 @@ export class RepositoryCache {
   readonly directory: string
 
   private readonly tasks = new Map<string, Promise<string>>()
+  private readonly install: RepositoryInstall
 
   /**
    * @param directory - caller-owned persistent cache root.
-   * @param install - isolated package installation boundary; defaults to the bundled pnpm.
+   * @param options - isolated installer override and lifecycle command directories.
    */
-  constructor(directory: string, private readonly install: RepositoryInstall = installWithBundledPnpm) {
+  constructor(directory: string, options: RepositoryCacheOptions = {}) {
     this.directory = resolve(directory)
+    const executableDirectories = (options.executableDirectories ?? []).map(entry => resolve(entry))
+    this.install = options.install ?? (staging => installWithBundledPnpm(staging, executableDirectories))
   }
 
   /**

From 778b9585d44439fa60a7e80efc90950a0c6c8f5b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:53:40 +0800
Subject: [PATCH 182/262] docs: refresh repository Plugin config source

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index eb4472d629..153ac72cc3 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1182,7 +1182,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/self-modification/repository-plugin/src/index.ts:42`](../packages/self-modification/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:44`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 

From a9af1a33f01310c56b60864afd51aceb95f9037a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:02:36 +0800
Subject: [PATCH 183/262] test(repository-plugin): update prepared fixture
 metadata

---
 examples/headless-agent/tests/keyless-smoke.e2e.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts
index 8b69406c53..c737e4ea72 100644
--- a/examples/headless-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts
@@ -6,7 +6,11 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import { PREPARED_ENTRY_FILENAME, prepareDshPlugin } from '@deepseek-ai/dsh-repository-plugin'
+import {
+  PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  prepareDshPlugin,
+} from '@deepseek-ai/dsh-repository-plugin'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
 const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
@@ -72,6 +76,7 @@ describe('headless-agent keyless smoke', () => {
       await writeFile(join(plugin, 'package.json'), `${JSON.stringify({
         name: 'headless-repository-fixture',
         version: '0.0.0',
+        scripts: { prepack: REPOSITORY_PLUGIN_PREPARE_COMMAND },
         dsh: { skills: ['../skills'] },
       }, undefined, 2)}\n`)
       await prepareDshPlugin(plugin)

From a0c64f49068cfa95925f9e056f327a9d18f07c3e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:16:59 +0800
Subject: [PATCH 184/262] ci(repository-plugin): authenticate private GitHub
 source

---
 ...26-07-30-static-repository-plugin-format.i18n.yaml |  4 ++--
 .../2026-07-30-static-repository-plugin-format.md     |  2 +-
 .../2026-07-30-static-repository-plugin-format.zh.md  |  2 +-
 ...-owned-git-repository-plugin-preparation.i18n.yaml |  4 ++--
 ...08-host-owned-git-repository-plugin-preparation.md |  5 +++--
 ...host-owned-git-repository-plugin-preparation.zh.md |  5 +++--
 .github/workflows/ci.yml                              | 11 +++++++++++
 .../repository-plugin/README.i18n.yaml                |  4 ++--
 .../self-modification/repository-plugin/README.md     |  2 ++
 .../self-modification/repository-plugin/README.zh.md  |  2 ++
 10 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 40a0461378..b555ad63c0 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: 4823495dabee2101713ac72c8d0cee5bcc6b38d1
-2026-07-30-static-repository-plugin-format.zh.md: e5817ca982a71a609c86c5835b803b12f1317e1a
+2026-07-30-static-repository-plugin-format.md: 5b1038f8738868a5838d4b20a6d56399c5f11ab6
+2026-07-30-static-repository-plugin-format.zh.md: c7cbc588c5ce6982c7c7003815151c9d40956972
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index 4823495dab..5b1038f873 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -46,4 +46,4 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 
 ## Testing
 
-Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, lets bundled pnpm fetch and prepare a private dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
+Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, authenticates to the private pull request repository through job-scoped Git configuration, lets bundled pnpm fetch and prepare its dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index e5817ca982..c7cbc588c5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -46,4 +46,4 @@
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，让随附 pnpm 获取并准备一个私有且不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
+聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，通过作业作用域的 Git 配置认证私有 PR 仓库，让随附 pnpm 获取并准备其中不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
index 55d9045506..39a7548d24 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: 45e84f9c8a89bb9d1eb7e4521634d16789dea2f0
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ba88d5bb351427118d55c357209b496b39c2eb98
+2026-08-08-host-owned-git-repository-plugin-preparation.md: 47410bf3c55455a971ec347eab4e8b37ea26c6a5
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 64c37543d34147c41fc7a362040c7ada8fde0652
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
index 45e84f9c8a..47410bf3c5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -18,7 +18,7 @@ The fixed authoring format now requires exact `scripts.prepack: "dsh-plugin-prep
 
 `@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
 
-The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
 
 ## Alternatives considered
 
@@ -33,10 +33,11 @@ The Node 24 consumer lane passes an exact source derived from the pull request h
 ## Consequences
 
 - A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
+- Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
 - `prepack`, not `prepare`, is part of the pre-release authoring format. Invalid lifecycle metadata fails during source preparation or installed-package validation instead of producing an ambiguous partial format.
 - Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
 - This repair does not expand the contribution surface: prepared repository Plugins still contribute only declared skills and common MCP definitions, while arbitrary package lifecycle code remains trusted installation code rather than a model-facing Cordis Plugin API.
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact live GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
index ba88d5bb35..64c37543d3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -18,7 +18,7 @@ repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`
 
 `@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
 
-Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
 
 ## 考虑过的替代方案
 
@@ -33,10 +33,11 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 
 ## 后果
 
 - 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
+- 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
 - 预发布创作格式使用 `prepack` 而不是 `prepare`。无效的生命周期元数据会在源码准备或已安装包校验阶段导致失败，而不会留下状态不明的半成品格式。
 - 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
 - 本次修复不扩大贡献范围：已准备的 repository 插件仍只贡献已声明的 skills 和通用 MCP 定义，而任意包生命周期代码仍是受信任的安装代码，不是面向模型的 Cordis 插件 API。
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确的真实 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5324df431e..d017fa14fb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -242,6 +242,17 @@ jobs:
         if: vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]'
         run: pnpm --filter @deepseek-ai/dsh-frontend exec playwright install chromium
 
+      - name: Configure private GitHub repository Plugin access
+        env:
+          DSH_GITHUB_SOURCE_TOKEN: ${{ github.token }}
+        run: |
+          source_config="$RUNNER_TEMP/dsh-github-source.gitconfig"
+          basic_auth=$(printf 'x-access-token:%s' "$DSH_GITHUB_SOURCE_TOKEN" | base64 | tr -d '\n')
+          git config --file "$source_config" url.https://github.com/.insteadOf git@github.com:
+          git config --file "$source_config" --add url.https://github.com/.insteadOf ssh://git@github.com/
+          git config --file "$source_config" http.https://github.com/.extraheader "AUTHORIZATION: basic $basic_auth"
+          echo "GIT_CONFIG_GLOBAL=$source_config" >> "$GITHUB_ENV"
+
       - name: Run compatibility, snapshot, and artifact gates
         run: pnpm run check:ci:consumers
 
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index c75c82dc84..9720364496 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: e0b45dc5fd40b5d1005598ae100d23ca7d0b6ec9
-README.zh.md: 30f200d2b7188d88e4a5e4e566cf3394f799933a
+README.md: 23c4cc0dceaf0692b7ef5067f9170b8c6b311cc0
+README.zh.md: db2f3e5a5c8915836d97177f797411e17e70441c
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index e0b45dc5fd..23c4cc0dce 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -40,6 +40,8 @@ The shipped `dsh-base` bundle every profile starts from contains an empty `repos
 
 Each source must use `github:owner/repository#<ref>`. Omitting `&path:` selects `/.dsh-plugin`; an explicit path is absolute within the repository and must end in `.dsh-plugin`. A commit ref gives the clearest immutable identity, while tags and branches remain accepted exact config values. `cacheDir` may override the default `$DSH_HOME/cache/repository-plugins` cache root.
 
+Git transport uses the host's ordinary Git authentication. Public repositories need no credentials; private sources require a read-only credential or SSH agent that can read the selected repository. DSH removes credential-shaped environment variables before package lifecycles, so configure Git itself, such as through a credential helper or job-scoped Git config, instead of expecting an exported token variable to cross that boundary. Repository lifecycle code is trusted and can invoke Git, so use the narrowest repository-scoped credential available.
+
 Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A valid source-list change installs and swaps the complete repository Plugin generation; a failed fetch, prepare, import, or Plugin application keeps the last good tree and broadcasts `hmr/config-update-failed(filename, error)`. One-shot runs read the layers only at startup, and a `--patch` overlay is never watched. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
 
 ## Preparation
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 30f200d2b7..db2f3e5a5c 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -40,6 +40,8 @@
 
 每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为精确配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
 
+Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有源需要可读取所选仓库的只读凭据或 SSH agent。DSH 会在包生命周期运行前移除名称符合凭据模式的环境变量，因此请配置 Git 本身，例如使用 Git 凭据辅助工具或作业作用域的 Git 配置，而不要指望已导出的 token 变量跨越该边界。仓库生命周期代码受信任且可以调用 Git，因此请使用作用域最窄且仅限所选仓库的凭据。
+
 长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套 repository Plugin generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入 repository Plugin 的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
 
 ## 准备阶段

From 033fa4b0b12ac88e2ee89597b059891bc4e12f90 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:25:14 +0800
Subject: [PATCH 185/262] feat(repository-plugin): load trusted package code

---
 ...-static-repository-plugin-format.i18n.yaml |  4 +-
 ...6-07-30-static-repository-plugin-format.md | 16 ++--
 ...7-30-static-repository-plugin-format.zh.md | 18 ++--
 ...-trusted-repository-package-code.i18n.yaml |  6 ++
 ...6-08-08-trusted-repository-package-code.md | 51 ++++++++++
 ...8-08-trusted-repository-package-code.zh.md | 51 ++++++++++
 ...it-repository-plugin-preparation.i18n.yaml |  4 +-
 ...owned-git-repository-plugin-preparation.md | 10 +-
 ...ed-git-repository-plugin-preparation.zh.md | 10 +-
 ...0-config-only-repository-plugins.i18n.yaml |  4 +-
 ...26-07-30-config-only-repository-plugins.md |  8 +-
 ...07-30-config-only-repository-plugins.zh.md |  8 +-
 .../.dsh-plugin/.mcp.json                     | 10 ++
 .../.dsh-plugin/package.json                  | 20 +++-
 .../.dsh-plugin/src/mcp-server.ts             | 19 ++++
 .../.dsh-plugin/src/plugin.ts                 | 59 ++++++++++++
 .../.dsh-plugin/tsconfig.json                 | 13 +++
 .../github-repository-plugin.built.e2e.ts     | 57 ++++++++---
 .../fixtures/repository-plugin/dsh-plugin.mjs | 11 ++-
 knip.json                                     | 11 +++
 packages/mcp/mcp-client/README.i18n.yaml      |  4 +-
 packages/mcp/mcp-client/README.md             |  3 +-
 packages/mcp/mcp-client/README.zh.md          |  3 +-
 packages/mcp/mcp-client/src/index.ts          | 10 +-
 packages/mcp/mcp-client/tests/apply.spec.ts   | 37 +++----
 .../mcp/mcp-client/tests/mcp-client.e2e.ts    | 29 ++----
 .../repository-plugin/README.i18n.yaml        |  4 +-
 .../repository-plugin/README.md               | 43 +++++++--
 .../repository-plugin/README.zh.md            | 43 +++++++--
 .../repository-plugin/package.json            |  2 +-
 .../repository-plugin/src/format.ts           | 65 +++++++++++--
 .../repository-plugin/src/index.ts            |  2 +-
 .../repository-plugin/src/source.ts           |  8 +-
 .../tests/repository-plugin.spec.ts           | 96 +++++++++++++++++--
 34 files changed, 590 insertions(+), 149 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index b555ad63c0..8ffa06ab1a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: 5b1038f8738868a5838d4b20a6d56399c5f11ab6
-2026-07-30-static-repository-plugin-format.zh.md: c7cbc588c5ce6982c7c7003815151c9d40956972
+2026-07-30-static-repository-plugin-format.md: 615529c89d32ed87c73d100b632318500e1ae86c
+2026-07-30-static-repository-plugin-format.zh.md: bb90994defccdaf2044b467cb3c5018c1c94641a
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index 5b1038f873..615529c89d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -6,15 +6,15 @@ English | [中文](2026-07-30-static-repository-plugin-format.zh.md)
 
 ## Problem
 
-A repository that already contains reusable skills or an MCP server declaration should be usable by standalone Harness applications without becoming a Harness SDK project or rewriting its existing layout. Popular repositories must be able to add one `.dsh-plugin` directory while keeping their current skills and `.mcp.json` elsewhere in the tree. At the same time, treating an arbitrary repository entry point as a Cordis Plugin would make every repository a new unrestricted runtime extension surface and would bypass the existing skill and MCP lifecycle owners.
+A repository that already contains reusable skills or an MCP server declaration should be usable by standalone Harness applications without becoming a Harness SDK project or rewriting its existing layout. Popular repositories must be able to add one `.dsh-plugin` directory while keeping their current skills and `.mcp.json` elsewhere in the tree. These portable static contributions still need to reuse the existing skill and MCP lifecycle owners when the same trusted package also carries native Cordis code.
 
 The [package-manager-native repository cache](2026-07-30-package-manager-native-repository-cache.md) prepares an exact package source but intentionally knows nothing about DSH formats. This layer therefore needs a package-manager-compatible authoring format, a deterministic prepared artifact, and a Cordis composition that stays transactional under Loader disposal and replacement.
 
 ## Decision
 
-`@deepseek-ai/dsh-repository-plugin` owns a restricted `.dsh-plugin` package format with two contribution kinds only: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. At least one is required. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths.
+`@deepseek-ai/dsh-repository-plugin` owns the static contribution subformat inside a `.dsh-plugin` package: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths. The package may additionally declare the explicit code entry owned by the [trusted repository package decision](2026-08-08-trusted-repository-package-code.md), and at least one code or static contribution is required.
 
-The `.dsh-plugin` package declares exact `scripts.prepack: "dsh-plugin-prepare"` metadata without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's exact lifecycle metadata before importing that wrapper. The `.mjs` extension avoids imposing `type: module` on repository-authored package metadata. The generated module is a fixed import-free template containing only a normalized manifest, an `inject` list derived from it (`loader`, plus `skills` and/or `tools` per the declared capabilities, so the wrapper fiber gates on the services its children need), and delegation to the `dsh-repository-plugin` Loader builtin. Preparation never discovers, transpiles, bundles, or preserves a custom repository entry point. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+The `.dsh-plugin` package declares a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The package may build its code first. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's helper-bearing lifecycle metadata before importing that wrapper. A static-only package still receives an import-free wrapper containing its normalized manifest, service-derived `inject` list, and delegation to the `dsh-repository-plugin` Loader builtin. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 Loading the DSH package registers that builtin as an effect. A generated wrapper mounts the builtin as its child with `import.meta.url`, so all contributions belong to the wrapper fiber and disappear on Loader removal or rollback. The builtin revalidates the prepared manifest and path containment before reading assets. It composes the existing implementations rather than registering skills or MCP tools itself.
 
@@ -22,11 +22,11 @@ Each prepared skill set mounts `dsh-skill-local` with a unique `repository:<pack
 
 Each `.mcp.json` server becomes one existing `dsh-mcp-client` child. The adapter accepts the common root `{ "mcpServers": ... }`; stdio definitions allow only optional `type: "stdio"`, `command`, `args`, and `env`, while HTTP definitions allow only `type: "http"`, `url`, and `headers`. Exact `${NAME}` process-environment references expand at runtime, after cache preparation; missing names fail Plugin load. HTTP maps to the client's Streamable HTTP transport, and stdio uses the prepared package directory as `cwd`. The existing client alone owns connection attempts, failure logging, remote tool synchronization, tool calls, and disconnects. Consequently an MCP connection failure keeps its established successful-plugin/no-tools behavior and is not reclassified as a repository preparation or Loader failure.
 
-Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `CLAUDE_PLUGIN_ROOT`, and a broader Claude compatibility contract. Hooks, commands, agents, apps, arbitrary Cordis code, marketplaces, and discovery are also unsupported. Repository subdirectory selection and GitHub source configuration belong to the [standalone app integration](../feature/2026-07-30-config-only-repository-plugins.md), not this format package.
+Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `CLAUDE_PLUGIN_ROOT`, and a broader Claude compatibility contract. Commands, hooks, agents, rules, and other foreign manifest conventions are not inferred from static repository layout; DSH-native behavior uses the explicit trusted Cordis entry. Repository subdirectory selection and GitHub source configuration belong to the [standalone app integration](../feature/2026-07-30-config-only-repository-plugins.md), not this static adapter.
 
 ## Alternatives considered
 
-**Load a repository's own Cordis entry point.** Rejected because it makes the advertised static format an unrestricted code-loading API, requires repository authors to depend on Harness internals, and duplicates the ordinary SDK/plugin-dependency path.
+**Discover an entry from `main`, `exports`, or repository layout.** Rejected because static assets do not imply that a package's ordinary entry is a Cordis Plugin. Trusted code loading is explicit through `dsh.entry` and remains outside this static adapter's ownership.
 
 **Teach generated wrappers to implement skills and MCP directly.** Rejected because copied runtime code would drift from `dsh-skill-local` and `dsh-mcp-client`, especially their provider invalidation, tool synchronization, failure, and teardown contracts.
 
@@ -39,11 +39,11 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 ## Consequences
 
 - Existing skill/MCP repositories can add a small `.dsh-plugin/package.json` without relocating their assets or adopting an SDK project.
-- Prepared output is deterministic static glue, while the configured repository and its dependency lifecycle remain trusted executable package-manager input rather than a sandbox.
+- Prepared static output is deterministic glue, while an optional `dsh.entry` and the configured repository lifecycle remain trusted executable package-manager input rather than a sandbox.
 - Multiple repository Plugins coexist through provider names and ordinary MCP server-name uniqueness; duplicate names fail through their existing registries and participate in Loader rollback.
 - Cached source edits do not appear live. Another exact source/ref/path/config selection is required.
-- Adding another contribution kind requires an explicit format and DSH-owned runtime consumer; it cannot arrive as repository JavaScript by accident.
+- Adding another portable static contribution kind requires an explicit format and DSH-owned runtime consumer; DSH-native behavior uses the separate explicit code entry.
 
 ## Testing
 
-Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, authenticates to the private pull request repository through job-scoped Git configuration, lets bundled pnpm fetch and prepare its dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
+Focused tests prepare skills and MCP metadata, prove a static-only wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head and observes the copied skill alongside the trusted code and MCP proofs owned by the superseding decision.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index c7cbc588c5..bb90994def 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：静态 repository Plugin 格式
+# Agent Note: 静态 repository Plugin 格式
 
 状态：已实现
 
@@ -6,15 +6,15 @@
 
 ## 问题
 
-一个已经包含可复用 skills 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。与此同时，如果把任意仓库入口都当作 Cordis Plugin，就会让每个仓库成为新的无限制运行时扩展表面，并绕过现有的 skill 与 MCP 生命周期所有者。
+一个已经包含可复用 skills 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。当同一个受信任包还携带原生 Cordis 代码时，这些可移植静态贡献仍需复用现有的 skill 与 MCP 生命周期所有者。
 
 [Package-manager-native repository cache](2026-07-30-package-manager-native-repository-cache.md) 会准备一个精确 package source，但有意不了解任何 DSH 格式。因此本层需要一种兼容 package manager 的创作格式、确定性的已准备产物，以及在 Loader dispose 和替换期间仍保持事务性的 Cordis 组合。
 
 ## 决策
 
-`@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` package 格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
+`@deepseek-ai/dsh-repository-plugin` 负责 `.dsh-plugin` 包内的静态贡献子格式：skill 根和一个通用 `.mcp.json`。其包元数据使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径。每条路径都可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的插件可以拥有其包上方相邻的子树，却不能访问无关宿主路径。该包还可以声明由[受信任 repository 包决策](2026-08-08-trusted-repository-package-code.md)负责的显式代码入口，并且至少需要一种代码或静态贡献。
 
-`.dsh-plugin` 包声明精确的 `scripts.prepack: "dsh-plugin-prepare"` 元数据，且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的精确生命周期元数据。`.mjs` 扩展名避免强迫仓库作者在包元数据中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+`.dsh-plugin` 包声明非空 `scripts.prepack`，调用 `dsh-plugin-prepare` 且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。包可以先构建其代码。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的生命周期元数据是否包含辅助命令。仅含静态贡献的包仍会获得无 import 包装层，其中包含规范化 manifest（元数据清单）、由服务派生的 `inject` 列表，以及对 `dsh-repository-plugin` Loader builtin 的委托。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
@@ -22,11 +22,11 @@
 
 `.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
 
-未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
+未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。命令、hook、agent（智能体）、规则和其他外来 manifest 约定不会从静态 repository 布局中推断出来；DSH 原生行为使用显式的受信任 Cordis 入口。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本静态适配器。
 
 ## 考虑过的替代方案
 
-**加载仓库自己的 Cordis 入口。** 拒绝，因为这会把宣传为静态的格式变成无限制代码加载 API，要求仓库作者依赖 Harness 内部实现，并重复普通 SDK／Plugin dependency 路径。
+**从 `main`、`exports` 或 repository 布局中发现入口。** 拒绝，因为静态资源并不表示包的普通入口就是 Cordis 插件。受信任代码通过 `dsh.entry` 显式加载，不属于该静态适配器的职责。
 
 **让生成包装模块直接实现 skills 和 MCP。** 拒绝，因为复制的运行时代码会与 `dsh-skill-local` 和 `dsh-mcp-client` 漂移，尤其是提供方失效、工具同步、失败和 teardown 契约。
 
@@ -39,11 +39,11 @@
 ## 后果
 
 - 现有 skill／MCP 仓库可以新增一个很小的 `.dsh-plugin/package.json`，无需移动资源或采用 SDK 项目。
-- 已准备输出是确定性的静态胶水；已配置仓库及其依赖生命周期仍是受信任的可执行 package-manager 输入，而非 sandbox。
+- 已准备的静态输出是确定性胶水；可选的 `dsh.entry` 和已配置的 repository 生命周期仍是受信任的可执行包管理器输入，而非沙箱。
 - 多个 repository Plugin 通过提供方名称和普通 MCP server-name 唯一性共存；重复名称经现有 registry 失败，并参与 Loader 回滚。
 - Cache 内的源码编辑不会实时出现；必须选择另一个精确 source／ref／path／config。
-- 新增贡献类型必须提供显式格式和 DSH 自有运行时消费方；它不能意外以 repository JavaScript 形式进入。
+- 新增可移植静态贡献类型必须提供显式格式和 DSH 自有运行时消费方；DSH 原生行为使用独立的显式代码入口。
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，通过作业作用域的 Git 配置认证私有 PR 仓库，让随附 pnpm 获取并准备其中不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
+聚焦测试会准备 skill 与 MCP 元数据，证明仅含静态贡献的包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 构建入口验收会使用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，并观察已复制的 skill，以及由取代本决策的新决策所负责的受信任代码与 MCP 验证证据。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
new file mode 100644
index 0000000000..eeea186c92
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+2026-08-08-trusted-repository-package-code.md: 4968d29a6da4180a8b016eef9176acb9bc64d8b1
+2026-08-08-trusted-repository-package-code.zh.md: 2e9f59bb1f571bb1bace9623a9e6976e0238a017
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
new file mode 100644
index 0000000000..4968d29a6d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -0,0 +1,51 @@
+# Agent Note: Trusted repository packages load Cordis code
+
+Status: implemented
+
+English | [中文](2026-08-08-trusted-repository-package-code.zh.md)
+
+## Problem
+
+The standalone repository format already installs a selected Git package and runs its dependency and lifecycle code with host authority, but it exposed only copied skills and MCP metadata to DSH. Forbidding a Cordis entry did not create a security boundary: package installation remained trusted executable code while the restriction prevented the package from contributing the Plugin behavior that the Harness architecture is designed to compose.
+
+A repository author also needs to keep an ordinary TypeScript npm package shape. Requiring publication to npm, pre-generated JavaScript in Git, or a DSH-owned TypeScript compiler would make a Git source less capable than the same package installed through a developer-owned SDK project. The first model request must observe any MCP tools that this package starts; background-only initial discovery makes a successful installation nondeterministic at the application boundary.
+
+## Decision
+
+A configured repository package is trusted code. Its `.dsh-plugin/package.json` may declare `dsh.entry` as a relative path to a compiled ESM Cordis Plugin inside that package, alongside or instead of `dsh.skills` and `dsh.mcpServers`. At least one contribution is required. The entry may use namespace exports or a default export and retains ordinary Cordis semantics for `name`, `inject`, `Config`, registrations, startup failure, and effect-scoped teardown.
+
+The package owns its npm dependencies and build toolchain. `scripts.prepack` is a non-empty package-authored command that must invoke the host-supplied `dsh-plugin-prepare`, but it may first run `tsc`, `tsdown`, or any other build. DSH neither parses the shell program nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; missing wrapper or build outputs fail before a cache generation becomes usable.
+
+The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
+
+`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Initial connection failure keeps the existing contained failure contract: it is logged, the client activates with no tools, and disposal still closes the transport.
+
+## Trust boundary
+
+Exact refs, source containment, credential-shaped environment scrubbing, prepared manifests, and immutable cache keys protect identity and composition integrity; they do not sandbox executable package input. Repository lifecycle scripts, transitive npm dependencies, the compiled entry, and spawned MCP servers can exercise the authority available to the DSH process and the Cordis services they receive. Users must therefore trust the selected repository and should pin immutable refs and grant Git only the narrow read credential needed for acquisition.
+
+Model-visible behavior remains governed by the owning DSH seam. A repository entry may register tools, prompt sections, policies, commands, agents, or other effects, but anything reaching a model request still needs the corresponding logged DSH representation and lifecycle cleanup. The repository format grants code loading; it does not weaken those service contracts.
+
+## Alternatives considered
+
+**Keep code forbidden while allowing arbitrary package lifecycles.** Rejected because installation already executes trusted repository code, so the restriction added no isolation and forced Plugin authors to publish or maintain a second integration path.
+
+**Have DSH compile repository TypeScript.** Rejected because compiler choice, module layout, generated chunks, native dependencies, and package metadata belong to the npm package. Running the package's declared build preserves the same boundary as other Git dependencies.
+
+**Import `main`, `exports`, or another discovered entry implicitly.** Rejected because an npm package may contain utilities or an MCP executable that is not a Cordis Plugin. The explicit `dsh.entry` field makes code activation reviewable and lets preparation validate the packed path.
+
+**Add a closed manifest field for every future DSH contribution.** Rejected as the universal extension mechanism. Skills and common MCP files retain useful portable static adapters, while DSH-native behavior composes through the existing Cordis Plugin and service contracts.
+
+## Consequences
+
+- A TypeScript DSH Plugin can live in a GitHub repository, install ordinary npm dependencies, compile during `prepack`, and run without publishing the Plugin package to npm.
+- Static-only repository packages remain valid and retain import-free wrappers; adding `dsh.entry` opts that package into runtime code import.
+- A package build, dependency install, entry import, unmet service, or Plugin startup failure prevents the candidate generation from replacing the last good configuration.
+- The initial MCP connection can lengthen application startup, while a contained connection failure still yields a running application with no tools from that server.
+- Repository code receives host authority, so source review and immutable pinning are operational security requirements rather than optional hardening.
+
+## Testing
+
+Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication while preserving contained connect failure and teardown.
+
+The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. That repository package installs pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Cache assertions require source files to be absent from the packed installation while both built modules, their installed dependency, copied assets, and generated wrapper are present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
new file mode 100644
index 0000000000..2e9f59bb1f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -0,0 +1,51 @@
+# Agent Note: 受信任 repository 包加载 Cordis 代码
+
+状态：已实现
+
+[English](2026-08-08-trusted-repository-package-code.md) | 中文
+
+## 问题
+
+独立 repository 格式已经会安装选定的 Git 包，并以宿主权限运行其依赖和生命周期代码，但它向 DSH 暴露的只有复制后的 skill（技能）和 MCP 元数据。禁止 Cordis 入口并未建立安全边界：包安装过程仍会执行受信任代码，而这项限制却阻止包贡献 Harness 架构本就用于组合的插件行为。
+
+仓库作者还需要保持普通 TypeScript NPM 包的结构。如果要求发布到 NPM、把预生成的 JavaScript 签入 Git，或使用 DSH 自有的 TypeScript 编译器，Git 源的能力就会弱于通过开发者自有 SDK 项目安装的同一个包。首个模型请求必须看到该包启动的所有 MCP 工具；仅在后台进行初始发现，会让一次成功安装在应用边界上具有不确定性。
+
+## 决策
+
+已配置的 repository 包是受信任代码。其 `.dsh-plugin/package.json` 可以连同 `dsh.skills` 和 `dsh.mcpServers` 声明 `dsh.entry`，也可以用它取代二者；`dsh.entry` 是指向该包内已编译 ESM Cordis 插件的相对路径。至少需要一种贡献。入口可以使用 namespace 导出或 default export，并沿用 Cordis 对 `name`、`inject`、`Config`、注册、启动失败和 effect 作用域清理的常规语义。
+
+包自行负责其 NPM 依赖和构建工具链。`scripts.prepack` 是由包作者编写的非空命令，必须调用宿主提供的 `dsh-plugin-prepare`，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 既不解析该 shell 程序，也不编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；包装层或构建输出缺失会在缓存 generation 可用前导致失败。
+
+生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
+
+`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。初始连接失败沿用既有的收束失败契约：系统会记录日志，client 激活但不注册工具，dispose 仍会关闭 transport。
+
+## 信任边界
+
+精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest（元数据清单）和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
+
+模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务契约。
+
+## 考虑过的替代方案
+
+**继续禁止代码，但允许任意包生命周期。** 拒绝，因为安装过程本就执行受信任的 repository 代码，所以该限制没有提供隔离，反而迫使插件作者发布或维护第二条集成路径。
+
+**由 DSH 编译 repository TypeScript。** 拒绝，因为编译器选择、模块布局、生成分片、原生依赖和包元数据属于 NPM 包。运行包所声明的构建，可以保持与其他 Git 依赖相同的边界。
+
+**隐式导入 `main`、`exports` 或其他发现的入口。** 拒绝，因为 NPM 包可能包含并非 Cordis 插件的实用工具或 MCP 可执行文件。显式 `dsh.entry` 字段使代码激活可供评审，并让准备阶段校验打包后的路径。
+
+**为未来每种 DSH 贡献添加封闭 manifest 字段。** 不采用它作为通用扩展机制。skill 和通用 MCP 文件仍保留有用的可移植静态适配器；DSH 原生行为则通过现有 Cordis 插件与服务契约组合。
+
+## 后果
+
+- TypeScript DSH 插件可以存放在 GitHub 仓库中，安装普通 NPM 依赖，在 `prepack` 期间完成编译，并在无需把插件包发布到 NPM 的情况下运行。
+- 仅含静态贡献的 repository 包仍然有效，并保留无 import 包装层；添加 `dsh.entry` 会使该包选择启用运行时代码导入。
+- 包构建、依赖安装、入口导入、所需服务未满足或插件启动失败，都会阻止候选 generation 替换最后一个可用配置。
+- 初始 MCP 连接可能延长应用启动时间；连接失败被收束后，仍会得到一个正常运行、但不含该 server 工具的应用。
+- Repository 代码获得宿主权限，因此源码评审和锁定不可变 ref 是运行安全要求，而不是可选加固措施。
+
+## 测试
+
+repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，同时保留收束连接失败与清理覆盖。
+
+Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。该 repository 包安装固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。缓存断言要求打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
index 39a7548d24..d3f10b5273 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: 47410bf3c55455a971ec347eab4e8b37ea26c6a5
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 64c37543d34147c41fc7a362040c7ada8fde0652
+2026-08-08-host-owned-git-repository-plugin-preparation.md: b459184f802981f91f611b0b781651cede0c9efd
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 5e24efa59ce44ffa8214f9c5ef9ff722ac0ca73a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
index 47410bf3c5..b459184f80 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -14,11 +14,11 @@ The checked-in headless fixture did not catch either defect because it mounted a
 
 ## Decision
 
-The fixed authoring format now requires exact `scripts.prepack: "dsh-plugin-prepare"` metadata and no DSH dependency. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can still copy sibling repository assets such as `../skills` into the package.
+The authoring format requires a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` and needs no DSH dependency for that helper. The package may declare its own build and runtime dependencies and run compilation before the helper. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can validate built entries and still copy sibling repository assets such as `../skills` into the package.
 
 `@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
 
-The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true` GitHub fixture. That fixture installs pinned npm dependencies, type-checks and bundles a TypeScript Cordis entry and MCP server in `prepack`, invokes the host helper, and proves the skill, MCP call, and code entry through real model requests and immutable-cache artifacts. The test fails if CI omits the exact source instead of silently skipping.
 
 ## Alternatives considered
 
@@ -34,10 +34,10 @@ The Node 24 consumer lane passes an exact source derived from the pull request h
 
 - A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
 - Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
-- `prepack`, not `prepare`, is part of the pre-release authoring format. Invalid lifecycle metadata fails during source preparation or installed-package validation instead of producing an ambiguous partial format.
+- `prepack`, not `prepare`, is part of the pre-release authoring format. It may contain package-owned build steps but must invoke the host helper; missing or empty lifecycle metadata fails installed-package validation instead of producing an ambiguous partial format.
 - Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
-- This repair does not expand the contribution surface: prepared repository Plugins still contribute only declared skills and common MCP definitions, while arbitrary package lifecycle code remains trusted installation code rather than a model-facing Cordis Plugin API.
+- The host supplies only the preparation executable. Package dependencies, compilation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
index 64c37543d3..5e24efa59c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -14,11 +14,11 @@ repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`
 
 ## 决策
 
-修复后的创作格式要求元数据中精确包含 `scripts.prepack: "dsh-plugin-prepare"`，且不包含 DSH 依赖。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序仍可将 `../skills` 等同仓库的相邻资源复制进包内。
+创作格式要求 `scripts.prepack` 非空且调用 `dsh-plugin-prepare`，使用该辅助程序无需 DSH 依赖。包可以声明自己的构建依赖与运行时依赖，并在调用辅助程序前完成编译。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序可以校验构建入口，并继续把 `../skills` 等同仓库的相邻资源复制进包内。
 
 `@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
 
-Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true` 的 GitHub fixture。该 fixture 安装固定版本的 NPM 依赖，在 `prepack` 中对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，调用宿主辅助程序，并通过真实模型请求和不可变缓存产物验证 skill（技能）、MCP 调用和代码入口。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
 
 ## 考虑过的替代方案
 
@@ -34,10 +34,10 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 
 
 - 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
 - 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
-- 预发布创作格式使用 `prepack` 而不是 `prepare`。无效的生命周期元数据会在源码准备或已安装包校验阶段导致失败，而不会留下状态不明的半成品格式。
+- 预发布创作格式使用 `prepack` 而不是 `prepare`。其中可以包含包自有构建步骤，但必须调用宿主辅助程序；生命周期元数据缺失或为空会在已安装包校验时失败，而不会留下状态不明的半成品格式。
 - 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
-- 本次修复不扩大贡献范围：已准备的 repository 插件仍只贡献已声明的 skills 和通用 MCP 定义，而任意包生命周期代码仍是受信任的安装代码，不是面向模型的 Cordis 插件 API。
+- 宿主只提供准备阶段可执行文件。包依赖、编译和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index 1491968f15..cee151c1ed 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.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 .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
-2026-07-30-config-only-repository-plugins.md: 2057125fc78596dd4e5eb153f77b828f83d9ceff
-2026-07-30-config-only-repository-plugins.zh.md: 6e741b46be716e21a11c2f508fb5e6d0505c76d0
+2026-07-30-config-only-repository-plugins.md: 1564a847ccef877a6cc91827e195aa04711d09ce
+2026-07-30-config-only-repository-plugins.zh.md: 8e8de1e6edc356c9bb9ab55f01b6cce7608358e7
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
index 2057125fc7..1564a847cc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
@@ -6,13 +6,13 @@ English | [中文](2026-07-30-config-only-repository-plugins.zh.md)
 
 ## Problem
 
-A standalone `dsh` user has no developer-owned SDK project whose `package.json`, lockfile, and `cordis.yml` can carry an external Plugin dependency. Requiring an install command or another state file would make “use this repository” a multi-step workflow, while loading arbitrary repository code would bypass the restricted [static repository Plugin format](../architecture/2026-07-30-static-repository-plugin-format.md). Long-running TUI and Web processes also need a failed edit to preserve their usable Plugin generation and tell observers why the candidate was rejected.
+A standalone `dsh` user has no developer-owned SDK project whose `package.json`, lockfile, and `cordis.yml` can carry an external Plugin dependency. Requiring an install command or another state file would make “use this repository” a multi-step workflow, while trusted repository code still needs an exact-source, transactional lifecycle owned by the [repository package format](../architecture/2026-08-08-trusted-repository-package-code.md). Long-running TUI and Web processes also need a failed edit to preserve their usable Plugin generation and tell observers why the candidate was rejected.
 
 ## Decision
 
 The shipped TUI and Web/headless `cordis.yml` trees contain an empty `repository-plugins` entry. A user changes only `$DSH_HOME/config.yaml`, replacing that entry's config with a `repositories` list. Each item uses `github:owner/repository#<ref>` plus an optional `&path:/.../.dsh-plugin`; omission selects `/.dsh-plugin`. An explicit ref is mandatory, paths are absolute within the repository and end in `.dsh-plugin`, and duplicate normalized specifiers reject before installation. There is no marketplace, discovery index, HTTPS URL vocabulary, or implicit latest generation.
 
-`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, runs its ordinary lifecycle including `prepare`, and atomically publishes the exact specifier. The DSH host imports only the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber, so skills and MCP retain the owners, failure contracts, and teardown defined by the format package.
+`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, installs its dependencies, runs its package-authored `prepack` and the host preparation helper, and atomically publishes the exact specifier. The DSH host imports the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber; that wrapper composes static skill and MCP owners plus an explicit trusted Cordis entry when declared.
 
 ## Live update and failure
 
@@ -24,7 +24,7 @@ An identical specifier permanently reuses its cache generation. HMR watches conf
 
 ## Trust boundary
 
-Configuring a repository authorizes package-manager lifecycle code from that repository and its dependencies to run with the user's filesystem authority. The pnpm child removes ambient environment variables whose names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, but this is credential-exposure reduction rather than a sandbox. The fixed runtime wrapper prevents repository-authored Cordis entry points from becoming part of the supported Plugin format; it does not make package preparation untrusted-safe.
+Configuring a repository authorizes package-manager lifecycle code, dependencies, the explicit `dsh.entry`, and spawned MCP servers from that repository to run with the user's filesystem authority. The pnpm child removes ambient environment variables whose names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, but this is credential-exposure reduction rather than a sandbox. The prepared wrapper validates composition boundaries and lifecycle state; it does not make repository code safe to run when the source is untrusted.
 
 ## Alternatives considered
 
@@ -43,7 +43,7 @@ Configuring a repository authorizes package-manager lifecycle code from that rep
 - A repository that adds `.dsh-plugin/package.json` can reach standalone users through one personal-config edit without changing its existing skills or `.mcp.json` layout.
 - Long-running apps can add, replace, or remove configured generations without restart; rejected candidates retain the last good runtime and produce one generic Cordis event.
 - First use may require Git/network access and preparation time. Later starts reuse the exact prepared cache; old generations consume disk until a separate cache-management policy exists.
-- Only skills and common MCP definitions are supported. Hooks, commands, agents, apps, arbitrary Cordis code, compatibility shims, OAuth-bearing MCP definitions, and marketplaces remain intentionally absent.
+- Skills and common MCP definitions retain portable static adapters, while an explicit `dsh.entry` can contribute DSH-native Cordis behavior. Format-specific compatibility shims, OAuth-bearing MCP definitions, and marketplaces remain intentionally absent.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 6e741b46be..8e8de1e6ed 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-独立 `dsh` 用户没有开发者自有的 SDK 项目，无法由其 `package.json`、lockfile 和 `cordis.yml` 承载外部插件依赖。若要求运行安装命令或维护另一份状态文件，「使用这个仓库」就会变成多步骤流程；若加载任意仓库代码，又会绕过受限的[静态仓库插件格式](../architecture/2026-07-30-static-repository-plugin-format.md)。长时间运行的 TUI 和 Web 进程还必须在编辑失败时保留仍可使用的插件版本，并向观察者说明候选配置被拒绝的原因。
+独立 `dsh` 用户没有开发者自有的 SDK 项目，无法由其 `package.json`、lockfile 和 `cordis.yml` 承载外部插件依赖。若要求运行安装命令或维护另一份状态文件，「使用这个仓库」就会变成多步骤流程；受信任的 repository 代码仍需要由[repository 包格式](../architecture/2026-08-08-trusted-repository-package-code.md)负责一套锁定精确来源且具事务性的生命周期。长时间运行的 TUI 和 Web 进程还必须在编辑失败时保留仍可使用的插件版本，并向观察者说明候选配置被拒绝的原因。
 
 ## 决策
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败契约和清理行为。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择已配置的 repository 子包，安装其依赖，运行包所定义的 `prepack` 与宿主准备辅助程序，并原子发布该精确说明符。DSH 宿主会导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber；该包装层组合静态 skill（技能）与 MCP 所有者，并在声明时组合显式的受信任 Cordis 入口。
 
 ## 实时更新与失败
 
@@ -24,7 +24,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 ## 信任边界
 
-配置仓库即授权该仓库及其依赖中的包管理器生命周期代码以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。固定的运行时包装模块会阻止仓库作者提供的 Cordis 入口成为受支持插件格式的一部分；它无法让包准备过程安全执行不受信任的代码。
+配置仓库即授权该仓库中的包管理器生命周期代码、依赖、显式 `dsh.entry` 和 spawn 的 MCP server 以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。已准备的包装层会校验组合边界和生命周期状态；当来源不受信任时，它无法让 repository 代码变得可安全运行。
 
 ## 考虑过的替代方案
 
@@ -43,7 +43,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 - 添加 `.dsh-plugin/package.json` 的仓库只需一次个人配置编辑即可供独立用户使用，无需改变现有 skill 或 `.mcp.json` 布局。
 - 长时间运行的应用无需重启即可新增、替换或移除已配置版本；被拒绝的候选配置会保留最后一个可用运行时，并产生一个通用 Cordis 事件。
 - 首次使用可能需要 Git／网络访问和准备时间。后续启动会复用这份精确的已准备缓存；在另行制定缓存管理政策之前，旧版本会持续占用磁盘空间。
-- 仅支持 skill 和通用 MCP 定义。钩子、命令、agent（智能体）、应用、任意 Cordis 代码、兼容 shim、带 OAuth 的 MCP 定义和插件市场均有意不提供。
+- skill 和通用 MCP 定义保留可移植静态适配器，而显式 `dsh.entry` 可以贡献 DSH 原生 Cordis 行为。格式专用的兼容 shim、带 OAuth 的 MCP 定义和插件市场仍有意不提供。
 
 ## 测试
 
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json
new file mode 100644
index 0000000000..4851f9f1f8
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json
@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "github_repository": {
+      "command": "node",
+      "args": [
+        "lib/mcp-server.mjs"
+      ]
+    }
+  }
+}
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
index 9ce1527d03..b11ea67c41 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -2,12 +2,28 @@
   "name": "dsh-github-repository-plugin-e2e-fixture",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
+  "files": [
+    "lib",
+    "dsh-plugin.mjs",
+    "dsh-plugin-assets"
+  ],
   "scripts": {
-    "prepack": "dsh-plugin-prepare"
+    "prepack": "tsc --noEmit && tsdown src/plugin.ts src/mcp-server.ts --no-config --tsconfig tsconfig.json --out-dir lib --platform node --target es2024 --clean && dsh-plugin-prepare"
   },
   "dsh": {
     "skills": [
       "../skills"
-    ]
+    ],
+    "mcpServers": "./.mcp.json",
+    "entry": "./lib/plugin.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "cordis": "4.0.0-rc.7",
+    "tsdown": "0.22.2",
+    "typescript": "6.0.3"
   }
 }
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts
new file mode 100644
index 0000000000..78a3e008f4
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts
@@ -0,0 +1,19 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+// The repository root's linter cannot resolve this independently installed
+// Git-package dependency; the package's prepack tsc validates the SDK types.
+/* oxlint-disable typescript/no-unsafe-assignment, typescript/no-unsafe-call, typescript/no-unsafe-member-access */
+const server = new McpServer({
+  name: 'github-repository-plugin-e2e',
+  version: '0.0.0',
+})
+
+server.registerTool('proof', {
+  description: 'Proves that an MCP server compiled from the exact GitHub repository package is active.',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: 'MCP_FROM_GITHUB_REPOSITORY' }],
+}))
+
+await server.connect(new StdioServerTransport())
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts
new file mode 100644
index 0000000000..5106f71b2f
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts
@@ -0,0 +1,59 @@
+import type { Context } from 'cordis'
+
+const PROOF_TOOL_NAME = 'mcp__github_repository__proof'
+
+interface TextBlock {
+  readonly type: 'text'
+  readonly text: string
+}
+
+interface ToolExecution {
+  readonly name: string
+}
+
+interface ToolResult {
+  readonly isError: boolean
+  readonly content: readonly TextBlock[]
+}
+
+type PostDecision =
+  | { readonly kind: 'accept'; readonly content?: readonly TextBlock[]; readonly value?: unknown; readonly additionalContexts?: readonly unknown[] }
+  | { readonly kind: 'block'; readonly feedback: readonly TextBlock[] }
+
+type PostListener = (
+  execution: ToolExecution,
+  result: ToolResult,
+  next: () => Promise<PostDecision>,
+) => Promise<PostDecision>
+
+type DshContext = Context & {
+  on(event: 'tools/post-execute', listener: PostListener): () => void
+}
+
+/** Cordis plugin name used by the repository acceptance fixture. */
+export const name = 'github-repository-typescript-proof'
+
+/** DSH tool registry required by the post-execute contribution. */
+export const inject = ['tools']
+
+/**
+ * Append a marker after the repository MCP proof tool succeeds.
+ * @param ctx - trusted DSH Cordis context supplied to the repository package.
+ */
+export function apply(ctx: Context): void {
+  const dsh = ctx as DshContext
+  dsh.on('tools/post-execute', async (execution, result, next): Promise<PostDecision> => {
+    const decision = await next()
+    if (execution.name !== PROOF_TOOL_NAME || result.isError || decision.kind !== 'accept' || Object.hasOwn(decision, 'value')) {
+      return decision
+    }
+    return {
+      kind: 'accept',
+      content: [
+        ...(decision.content ?? result.content),
+        { type: 'text', text: 'TS_PLUGIN_FROM_GITHUB_REPOSITORY' },
+      ],
+      ...decision.additionalContexts === undefined ? {} : { additionalContexts: decision.additionalContexts },
+    }
+  })
+}
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
new file mode 100644
index 0000000000..632e4db48c
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 7262ddeb58..0c13a71a02 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -1,4 +1,5 @@
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -13,7 +14,7 @@ const required = process.env.DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E === '1'
 const enabled = required || source !== undefined
 
 describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () => {
-  it('installs a private exact GitHub source and exposes its skill to the model', async () => {
+  it('installs, builds, and runs skill, MCP, and TypeScript Plugin contributions from a private exact GitHub source', async () => {
     expect(existsSync(dshBin), 'the repository Plugin acceptance must run the built dsh entry').toBe(true)
     expect(source, 'DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE is required by this CI lane').toMatch(
       /^github:[^/\s#&]+\/[^/\s#&]+#[0-9a-f]{40}&path:\/.*\/\.dsh-plugin$/u,
@@ -21,9 +22,11 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
 
     const apiKey = 'github-repository-plugin-e2e-key'
     const server = await startMockLlmServer({
-      sequence: ['success'],
+      sequence: ['tool_call_success', 'success'],
       apiKey,
-      successText: 'private GitHub repository Plugin reached dsh run',
+      toolName: 'mcp__github_repository__proof',
+      toolArguments: '{}',
+      successText: 'trusted GitHub repository package reached dsh run',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-github-repository-plugin-'))
     const patch = join(home, 'github-repository-plugin.cordis.patch.yml')
@@ -45,7 +48,7 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       ], {
         cwd: repoRoot,
         input: '',
-        timeout: 120_000,
+        timeout: 180_000,
         killSignal: 'SIGKILL',
         reject: false,
         env: {
@@ -57,14 +60,20 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
         },
       })
       if (result.timedOut) {
-        throw new Error(`dsh GitHub repository Plugin run did not exit within 120s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+        throw new Error(`dsh GitHub repository Plugin run did not exit within 180s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
       }
       expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}`).toBe(0)
-      expect(result.stdout).toBe('private GitHub repository Plugin reached dsh run')
-      expect(server.requests.length).toBeGreaterThan(0)
-      expect(JSON.stringify(server.requests.map(request => request.body))).toContain(
+      expect(result.stdout).toBe('trusted GitHub repository package reached dsh run')
+      expect(server.requests).toHaveLength(2)
+      const firstRequest = JSON.stringify(server.requests[0]!.body)
+      const secondRequest = JSON.stringify(server.requests[1]!.body)
+      expect(firstRequest).toContain(
         'Proves that dsh installed a private repository Plugin from an exact GitHub source.',
       )
+      expect(firstRequest).toContain('mcp__github_repository__proof')
+      expect(firstRequest).toContain('Proves that an MCP server compiled from the exact GitHub repository package is active.')
+      expect(secondRequest).toContain('MCP_FROM_GITHUB_REPOSITORY')
+      expect(secondRequest).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
 
       const cacheRoot = join(home, 'cache', 'repository-plugins')
       const generations = readdirSync(cacheRoot, { withFileTypes: true }).filter(entry => entry.isDirectory())
@@ -74,16 +83,38 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(manifest).toMatchObject({
         name: 'dsh-github-repository-plugin-e2e-fixture',
         private: true,
-        scripts: { prepack: 'dsh-plugin-prepare' },
+        scripts: {
+          prepack: 'tsc --noEmit && tsdown src/plugin.ts src/mcp-server.ts --no-config --tsconfig tsconfig.json --out-dir lib --platform node --target es2024 --clean && dsh-plugin-prepare',
+        },
+        dsh: {
+          skills: ['../skills'],
+          mcpServers: './.mcp.json',
+          entry: './lib/plugin.mjs',
+        },
+        dependencies: {
+          '@modelcontextprotocol/sdk': '1.29.0',
+        },
+        devDependencies: {
+          cordis: '4.0.0-rc.7',
+          tsdown: '0.22.2',
+          typescript: '6.0.3',
+        },
       })
-      expect(manifest).not.toHaveProperty('dependencies')
-      expect(manifest).not.toHaveProperty('devDependencies')
       expect(readFileSync(join(installed, 'dsh-plugin-assets/skills/0/github-source-proof/SKILL.md'), 'utf8'))
         .toContain('This skill exists only in the GitHub repository source fixture.')
-      expect(readFileSync(join(installed, 'dsh-plugin.mjs'), 'utf8')).toContain('dsh-repository-plugin')
+      expect(readFileSync(join(installed, 'dsh-plugin-assets/.mcp.json'), 'utf8')).toContain('lib/mcp-server.mjs')
+      expect(readFileSync(join(installed, 'lib/plugin.mjs'), 'utf8')).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
+      expect(readFileSync(join(installed, 'lib/mcp-server.mjs'), 'utf8')).toContain('MCP_FROM_GITHUB_REPOSITORY')
+      expect(existsSync(join(installed, 'src'))).toBe(false)
+      const installedRequire = createRequire(join(installed, 'lib/mcp-server.mjs'))
+      expect(existsSync(installedRequire.resolve('@modelcontextprotocol/sdk/server/mcp.js'))).toBe(true)
+      const wrapper = readFileSync(join(installed, 'dsh-plugin.mjs'), 'utf8')
+      expect(wrapper).toContain('dsh-repository-plugin')
+      expect(wrapper).toContain('await import(manifest.entry)')
+      expect(wrapper).toContain('"entry":"./lib/plugin.mjs"')
     } finally {
       await server.close()
       rmSync(home, { recursive: true, force: true })
     }
-  }, 130_000)
+  }, 190_000)
 })
diff --git a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
index 5515aa82a2..ce61e58973 100644
--- a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
+++ b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
@@ -1,9 +1,18 @@
 // Generated by dsh-plugin-prepare. Do not edit.
 const manifest = {"name":"headless-repository-fixture","skills":["dsh-plugin-assets/skills/0"]}
+const FIBER_ACTIVE = 2
 export const name = "headless-repository-fixture"
 export const inject = ["loader","skills"]
+async function mount(ctx, plugin, label, config) {
+  const fiber = ctx.plugin(plugin, config)
+  await fiber
+  if (fiber.state !== FIBER_ACTIVE) {
+    const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)
+    throw new Error(`${label} did not activate (waiting for services: ${missing.join(', ') || 'unknown'})`)
+  }
+}
 export async function apply(ctx) {
   const runtime = ctx.loader.builtins["dsh-repository-plugin"]
   if (runtime === undefined) throw new Error("missing Cordis builtin dsh-repository-plugin")
-  await ctx.plugin(runtime, { baseUrl: import.meta.url, manifest })
+  await mount(ctx, runtime, 'repository Plugin runtime', { baseUrl: import.meta.url, manifest })
 }
diff --git a/knip.json b/knip.json
index 63db33e51c..0757fe49f8 100644
--- a/knip.json
+++ b/knip.json
@@ -703,6 +703,17 @@
         "@deepseek-ai/.+"
       ]
     },
+    "apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin": {
+      "entry": [
+        "src/*.ts"
+      ],
+      "project": [
+        "src/**/*.ts"
+      ],
+      "ignoreBinaries": [
+        "dsh-plugin-prepare"
+      ]
+    },
     "packages/client/modules": {
       "entry": [
         "tests/**/*.spec.ts"
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 9fa4504cca..6b6d4d9270 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-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/mcp/mcp-client/README.md
-README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: eb9e0dbdb48423cc4bc698fda355e973e42bc7a3
+README.md: 6bcc195e36d24d7e5ae3462573b30f1b41c963a7
+README.zh.md: 8886c16c3fe66d283ae2191661118729a89f1aeb
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index d7966595c6..6bcc195e36 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -56,7 +56,7 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: `listTools()` → registers each tool via `ctx.tools.register()` under its public name.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection failure is logged and activates with no tools.
 - Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
@@ -101,7 +101,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Initial discovery is asynchronous** — plugin load does not wait for connection and `listTools()`, so a turn started immediately after boot or HMR can assemble before the MCP tools are registered.
 - **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
 - **Crash recovery is manual** — transport closure does not auto-reconnect; registered tools can remain visible but fail against the closed transport until an HMR reload or Host restart.
 - **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index eb9e0dbdb4..8886c16c3f 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -56,7 +56,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：`listTools()` → 通过 `ctx.tools.register()` 使用各自公开名称注册每个工具。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接失败会记录日志，插件仍会激活但不注册工具。
 - 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
@@ -101,7 +101,6 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 已知限制与暂缓事项
 
-- **初始发现是异步的**：插件加载不会等待连接和 `listTools()`，因此在启动或 HMR 后立即开始的轮次可能在 MCP 工具注册前完成组装。
 - **只桥接 MCP 的工具能力**：资源和提示词没有 harness 消费接口，暂缓实现。
 - **崩溃恢复需要手动触发**：传输关闭后不会自动重新连接；已注册工具可能仍然可见，但会因传输已关闭而调用失败，直到 HMR 重载或重启 Host。
 - **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 49609bac9a..9798b4cfcb 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -116,7 +116,13 @@ export const Config = z.union([
 
 // ---- Plugin apply ----
 
-export function apply(ctx: Context, config: Config): void {
+/**
+ * Connect one MCP server and publish its initial tool generation before activation.
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved transport and server namespace configuration.
+ * @returns startup readiness after connection and initial tool discovery settle.
+ */
+export function apply(ctx: Context, config: Config): Promise<void> {
   // Reserve the namespace first: a duplicate `serverName` fails THIS instance
   // at load with an actionable error and leaves the earlier instance intact.
   ctx.effect(() => {
@@ -179,4 +185,6 @@ export function apply(ctx: Context, config: Config): void {
     for (const dispose of live().values()) dispose()
     try { await client.close() } catch { /* transport already gone */ }
   }, 'mcp-client.connection')
+
+  return ready.then(() => undefined)
 }
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 5836c74e5a..6bb97a7032 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -141,8 +141,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('connects, syncs tools under the namespace, and registers a notification handler', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(mockConnect).toHaveBeenCalled()
     expect(mockListTools).toHaveBeenCalled()
@@ -152,11 +151,10 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('rejects a duplicate serverName at load and leaves the first instance intact', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
-    expect(() => { apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
+    expect(() => { void apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
     // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
@@ -165,8 +163,7 @@ describe('apply (plugin lifecycle)', () => {
     const first = new Context()
     await first.plugin(SystemPrompt)
     await first.plugin(ToolRegistry)
-    apply(first, stdioConfig)
-    await sleep(50)
+    await apply(first, stdioConfig)
 
     await first.fiber.dispose()
     await sleep(50)
@@ -176,16 +173,17 @@ describe('apply (plugin lifecycle)', () => {
     const second = new Context()
     await second.plugin(SystemPrompt)
     await second.plugin(ToolRegistry)
-    expect(() => { apply(second, stdioConfig) }).not.toThrow()
+    await expect(apply(second, stdioConfig)).resolves.toBeUndefined()
+    await second.fiber.dispose()
   })
 
   it('scopes serverName reservations per app root', async () => {
     const other = await mountRegistry()
 
-    apply(ctx, stdioConfig)
+    const first = apply(ctx, stdioConfig)
     // Same serverName on a DIFFERENT root is fine.
-    expect(() => { apply(other, stdioConfig) }).not.toThrow()
-    await sleep(50)
+    const second = apply(other, stdioConfig)
+    await Promise.all([first, second])
 
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
     expect(other.tools.get('mcp__srv__remote')).toBeDefined()
@@ -194,8 +192,7 @@ describe('apply (plugin lifecycle)', () => {
   it('logs error and registers no tools when connect fails; dispose is a no-op', async () => {
     mockConnect.mockRejectedValue(new Error('connection refused'))
 
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(mockListTools).not.toHaveBeenCalled()
     expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
@@ -208,8 +205,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('re-syncs tools on ToolListChanged notification', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
@@ -226,8 +222,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('keeps the previous generation when a re-sync fails', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
     mockListTools.mockRejectedValue(new Error('flaky server'))
@@ -242,7 +237,7 @@ describe('apply (plugin lifecycle)', () => {
     // Load through ctx.plugin so ONLY the plugin's fiber is disposed — the
     // registry must survive to observe the unregistration.
     const fiber = ctx.plugin({ name: 'mcp-client', inject: ['tools'], apply }, stdioConfig)
-    await sleep(50)
+    await fiber
 
     // Advance to a second generation first.
     mockListTools.mockResolvedValue({
@@ -264,8 +259,7 @@ describe('apply (plugin lifecycle)', () => {
   it('effect disposer handles client.close failure gracefully', async () => {
     mockClose.mockRejectedValue(new Error('already closed'))
 
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     // Should not throw when dispose is triggered.
     await ctx.fiber.dispose()
@@ -283,8 +277,7 @@ describe('apply (plugin lifecycle)', () => {
       toolCallTimeoutMs: 30_000,
     }
 
-    apply(ctx, httpConfig)
-    await sleep(50)
+    await apply(ctx, httpConfig)
 
     expect(mockConnect).toHaveBeenCalled()
     expect(ctx.tools.get('mcp__web__remote')).toBeDefined()
diff --git a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
index 3ce25e9240..6a71ab4007 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
@@ -43,21 +43,6 @@ async function mountRegistry(): Promise<Context> {
   return ctx
 }
 
-/** Apply the MCP client plugin and wait for tools to be registered. */
-async function applyAndWait(ctx: Context, config: Config, timeoutMs = 20_000): Promise<void> {
-  // Annotated bindings (not withResolvers<void>()): the tests lint layer runs
-  // no-invalid-void-type with default options, which rejects the explicit
-  // type argument in call position but accepts the inferred form.
-  const gate: PromiseWithResolvers<void> = Promise.withResolvers()
-  const timer = setTimeout(
-    () => { gate.reject(new Error(`applyAndWait timed out after ${timeoutMs}ms — no tools/change event`)) },
-    timeoutMs,
-  )
-  ctx.on('tools/change', () => { clearTimeout(timer); gate.resolve() })
-  apply(ctx, config)
-  await gate.promise
-}
-
 function sleep(ms: number): Promise<void> {
   const gate: PromiseWithResolvers<void> = Promise.withResolvers()
   setTimeout(gate.resolve, ms)
@@ -94,7 +79,7 @@ describe('fixture server — controlled scenarios', () => {
 
   beforeAll(async () => {
     ctx = await mountRegistry()
-    await applyAndWait(ctx, fixtureConfig)
+    await apply(ctx, fixtureConfig)
   }, 30_000)
 
   afterAll(async () => {
@@ -180,9 +165,9 @@ describe('fixture server — duplicate serverName', () => {
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
 
-    expect(() => { apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
+    expect(() => { void apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
 
     await ctx.fiber.dispose()
     await sleep(200)
@@ -192,7 +177,7 @@ describe('fixture server — duplicate serverName', () => {
 describe('fixture server — disposal', () => {
   it('disposes cleanly without error', async () => {
     const ctx = await mountRegistry()
-    await applyAndWait(ctx, {
+    await apply(ctx, {
       transport: 'stdio',
       serverName: 'fixture',
       command: process.execPath,
@@ -229,7 +214,7 @@ describe('server-everything — official test server', () => {
 
   beforeAll(async () => {
     ctx = await mountRegistry()
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 60_000)
 
   afterAll(async () => {
@@ -293,7 +278,7 @@ describe('server-filesystem — real filesystem operations', () => {
       cwd: '',
       toolCallTimeoutMs: 30_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 60_000)
 
   afterAll(async () => {
@@ -409,7 +394,7 @@ describe('streamable-http — in-process MCP server', () => {
       headers: { Authorization: 'Bearer e2e-test-token' },
       toolCallTimeoutMs: 15_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 30_000)
 
   afterAll(async () => {
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 9720364496..7d7c04cf69 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 23c4cc0dceaf0692b7ef5067f9170b8c6b311cc0
-README.zh.md: db2f3e5a5c8915836d97177f797411e17e70441c
+README.md: 52d04f16684842749e57d1b47db0a95beb22558c
+README.zh.md: 921bf70b8a2e78410510d1efce79ced5f52b4641
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 23c4cc0dce..52d04f1668 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Restricted repository Plugin format for DeepSeek Harness. A repository author declares static skill roots and an optional common `.mcp.json` in `.dsh-plugin/package.json`; the prepare helper copies those assets and emits a fixed import-free Cordis wrapper. The runtime wrapper can only delegate to this DSH-owned package, which composes [`dsh-skill-local`](../../skill/skill-local/README.md) and [`dsh-mcp-client`](../../mcp/mcp-client/README.md). Design rationale: [static repository Plugin format Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md).
+Trusted repository package format for DeepSeek Harness. A `.dsh-plugin` npm package may contribute a compiled Cordis/DSH Plugin entry, skill roots, and a common `.mcp.json`; its ordinary `prepack` lifecycle owns dependency installation and source compilation before the DSH prepare helper validates the outputs and emits the Loader wrapper. Static contributions compose [`dsh-skill-local`](../../skill/skill-local/README.md) and [`dsh-mcp-client`](../../mcp/mcp-client/README.md). Design rationale: [trusted repository package code](../../../.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md) and the [static contribution subformat](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md).
 
 ## Authoring format
 
@@ -13,17 +13,30 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
   "name": "humanize-dsh-plugin",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
   "scripts": {
-    "prepack": "dsh-plugin-prepare"
+    "build": "tsc",
+    "prepack": "npm run build && dsh-plugin-prepare"
   },
   "dsh": {
+    "entry": "./lib/plugin.js",
     "skills": ["../skills"],
     "mcpServers": "../.mcp.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` must be exactly `dsh-plugin-prepare`. DSH supplies that command from its own installed runtime while preparing Git source, so the repository package needs no DSH or npm dependency. `dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
+`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. DSH does not transpile TypeScript or infer a package entry.
+
+`dsh.entry` is an optional relative path to a compiled ESM Cordis Plugin inside `.dsh-plugin`. The module may use either namespace exports or a default export and owns its ordinary `name`, `inject`, `Config`, registrations, and effects. `dsh.skills` is an optional array of local skill roots, and `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one of the three fields is required. Skill and MCP paths may reach adjacent repository assets but must remain beneath the directory containing `.dsh-plugin`; the compiled entry must remain inside the package selected and packed by the package manager. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
+
+The repository package and every dependency or lifecycle script it runs are trusted code, just like an npm package selected directly by the user. This format is not a sandbox: install only repositories whose code may access the host process, filesystem, network, and services declared through Cordis. Exact refs and the immutable cache provide identity and reproducibility, not isolation.
 
 ## Standalone app configuration
 
@@ -46,19 +59,17 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. The command validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained the exact `prepack` declaration. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point. Failure to run or complete preparation fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
-
-The containing package manager still runs the configured repository package's lifecycle scripts. This restriction defines the supported DSH contribution surface; it is not a security boundary for a repository that the user chose to install as executable package-manager source.
+During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to build or prepare fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
-Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates to that builtin with its own module URL and prepared manifest. The runtime validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped (a `files`/`.npmignore` mistake, a damaged cache entry) fails the plugin load instead of silently mounting a skill-less plugin. Repository skill roots mount as a uniquely named `dsh-skill-local` provider with default project/user roots excluded and watching disabled; cached package generations are immutable. Wrapper disposal removes the provider and all composed MCP clients through normal Cordis child-fiber teardown.
+Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates its prepared static manifest to that builtin, then imports and mounts `dsh.entry` when declared. The entry is an ordinary Cordis child Plugin: its own `inject` gates activation, startup failures reject the repository generation, and all of its effects disappear on Loader removal or rollback. The runtime likewise validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped by `files`/`.npmignore` or damaged in cache fails instead of silently losing contributions. Repository skill roots mount as uniquely named `dsh-skill-local` providers with default project/user roots excluded and watching disabled; cached package generations are immutable.
 
 ## Common MCP format
 
 The `.mcp.json` root is `{ "mcpServers": { ... } }`. A stdio entry accepts only `type: "stdio"` (optional), `command`, `args`, and `env`; an HTTP entry accepts only `type: "http"`, `url`, and `headers`. String values support exact `${NAME}` process-environment expansion at Plugin load, and a missing name fails that load. HTTP URLs become the existing MCP client's `streamable-http` transport; stdio entries use the prepared package directory as `cwd`.
 
-Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle; a network or child-process connection failure retains that client's established log-and-no-tools behavior.
+Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation; a network or child-process connection failure is logged and still activates with no tools.
 
 ## Export shape
 
@@ -94,8 +105,22 @@ Conditional on successful connection and the remote tool list; schemas recur on
 
 Stable connected tool lists are prefix-stable. Plugin lifecycle or MCP tool-list changes can change later tool-schema prefixes from the first affected definition.
 
+### Repository code
+
+#### What the model sees
+
+Data-dependent. The trusted Cordis entry may contribute any DSH behavior available through its declared services and events, including tools, prompt sections, policies, commands, and transformations. Every model-visible contribution remains subject to its owning DSH seam's logging and lifecycle contract.
+
+#### Token effect
+
+Defined by the services and registrations the entry contributes; the repository format itself adds no model content.
+
+#### KV Cache effect
+
+Stable registrations preserve the owning surface's normal prefix behavior. Loading, removing, or replacing the exact repository generation can change any prefixes affected by that Plugin.
+
 ## Known Limitations and Deferred Work
 
-- **Skills and MCP only** — commands, hooks, agents, apps, arbitrary Cordis code, marketplaces, and compatibility shims are intentionally outside this format.
+- **No code sandbox** — `dsh.entry`, npm dependencies, and package lifecycle scripts execute with the DSH host's authority; repository trust is mandatory.
 - **No MCP authentication protocol** — static headers may use environment expansion, but OAuth-bearing definitions reject and private-server login flows are not implemented here.
 - **Generated assets are immutable runtime input** — repository cache generations are not watched; source, ref, path, or configuration must select another prepared generation.
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index db2f3e5a5c..921bf70b8a 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是 DeepSeek Harness 的受限 repository 插件格式。仓库作者在 `.dsh-plugin/package.json` 中声明静态 skill（技能）根和可选的通用 `.mcp.json`；prepare helper 会复制这些资源并生成固定、无 import 的 Cordis 包装模块。运行时包装模块只能委托给这个由 DSH 自有的包，再由它组合 [`dsh-skill-local`](../../skill/skill-local/README.md) 与 [`dsh-mcp-client`](../../mcp/mcp-client/README.md)。设计依据见[静态 repository 插件格式 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md)。
+这是 DeepSeek Harness 的受信任 repository 包格式。`.dsh-plugin` NPM 包可以贡献已编译的 Cordis／DSH 插件入口、skill（技能）根和通用 `.mcp.json`；其常规 `prepack` 生命周期负责安装依赖并编译源码，随后 DSH 准备辅助程序校验输出并生成 Loader 包装层。静态贡献由 [`dsh-skill-local`](../../skill/skill-local/README.md) 与 [`dsh-mcp-client`](../../mcp/mcp-client/README.md) 组合。设计依据见[受信任 repository 包代码](../../../.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md)和[静态贡献子格式](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md)。
 
 ## 创作格式
 
@@ -13,17 +13,30 @@
   "name": "humanize-dsh-plugin",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
   "scripts": {
-    "prepack": "dsh-plugin-prepare"
+    "build": "tsc",
+    "prepack": "npm run build && dsh-plugin-prepare"
   },
   "dsh": {
+    "entry": "./lib/plugin.js",
     "skills": ["../skills"],
     "mcpServers": "../.mcp.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` 必须精确设为 `dsh-plugin-prepare`。DSH 会在准备 Git 源时由已安装的运行时提供该命令，因此仓库包无需添加 DSH 或 NPM 依赖。`dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
+`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。DSH 不转译 TypeScript，也不推断包入口。
+
+`dsh.entry` 是指向 `.dsh-plugin` 内已编译 ESM Cordis 插件的可选相对路径。该模块可以使用 namespace 导出或 default export，并自行拥有常规的 `name`、`inject`、`Config`、注册和 effect。`dsh.skills` 是可选的本地 skill 根数组，`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；三个字段中至少声明一个。skill 和 MCP 路径可以引用相邻的 repository 资源，但必须留在包含 `.dsh-plugin` 的目录下；已编译入口必须留在由包管理器选中并打包的包内。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
+
+repository 包及其运行的每项依赖或生命周期脚本都是受信任代码，与用户直接选择的 NPM 包相同。本格式不是沙箱：只有在你信任仓库代码并愿意允许其访问宿主进程、文件系统、网络及其通过 Cordis 声明的服务时才应安装。精确 ref 和不可变缓存提供身份与可复现性，而非隔离。
 
 ## 独立应用配置
 
@@ -46,19 +59,17 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。该命令校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装模块前，DSH 会重新校验已安装包是否仍保留精确的 `prepack` 声明。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。准备阶段未运行或未完成时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
-
-外层包管理器仍会运行已配置仓库包的生命周期脚本。这里的限制只定义 DSH 所支持的贡献表面；对于用户选择以可执行包管理器源安装的仓库，它并不是安全边界。
+安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。构建或准备失败时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
-加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装模块都把自身模块 URL 和已准备的 manifest 委托给该 builtin。运行时在挂载前会校验每个声明的 skill 根都是包内实际存在的目录——生成输出被丢弃的包（`files`／`.npmignore` 配置失误、缓存条目损坏）会使插件加载失败，而不是静默挂载一个没有 skill 的插件。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。包装模块 dispose（资源释放）时，会通过正常的 Cordis 子 fiber teardown 移除提供方和所有组合的 MCP client。
+加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装层都把已准备的静态 manifest（元数据清单）委托给该 builtin，再在声明了 `dsh.entry` 时导入并挂载该入口。入口是普通的 Cordis 子插件：其自有 `inject` 会门控激活，启动失败会拒绝 repository generation，Loader 移除或回滚时，其所有 effect 都会消失。运行时同样会在挂载前校验每个声明的 skill 根都是包内实际存在的目录——生成输出因 `files`／`.npmignore` 被丢弃或在缓存中损坏的包会加载失败，而不是静默丢失贡献。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。
 
 ## 通用 MCP 格式
 
 `.mcp.json` 根对象是 `{ "mcpServers": { ... } }`。stdio 条目只接受可选的 `type: "stdio"`、`command`、`args` 和 `env`；HTTP 条目只接受 `type: "http"`、`url` 和 `headers`。字符串值在插件加载时支持严格的 `${NAME}` 进程环境变量展开；缺失变量会使该次加载失败。HTTP URL 映射到现有 MCP client 的 `streamable-http` transport；stdio 条目以已准备的包目录作为 `cwd`。
 
-未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期；网络或子进程连接失败沿用该 client 既有的“记录错误且不注册工具”行为。
+未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络或子进程连接失败会记录日志，且插件仍会激活但不注册工具。
 
 ## 导出形状
 
@@ -94,8 +105,22 @@ Namespace 插件：具名导出 `name`／`inject`／`apply`、准备阶段常量
 
 稳定的已连接工具列表保持前缀稳定。插件生命周期或 MCP 工具列表变化可能从首个受影响定义开始改变后续工具 schema 前缀。
 
+### Repository 代码
+
+#### 模型看到什么
+
+取决于数据。受信任的 Cordis 入口可以通过其声明的服务和事件贡献任意可用的 DSH 行为，包括工具、提示词片段、策略、命令和转换。每项模型可见贡献仍受所属 DSH seam 的日志与生命周期契约约束。
+
+#### Token 影响
+
+由入口贡献的服务和注册决定；repository 格式本身不添加模型内容。
+
+#### KV Cache 影响
+
+稳定的注册会保留所属表面的正常前缀行为。加载、移除或替换精确的 repository generation，可能改变受该插件影响的任意前缀。
+
 ## 已知限制与暂缓事项
 
-- **仅支持 skill 与 MCP**：commands、钩子、agent（智能体）、apps、任意 Cordis 代码、marketplace 和兼容 shim 均有意排除在该格式之外。
+- **没有代码沙箱**：`dsh.entry`、NPM 依赖和包生命周期脚本以 DSH 宿主权限执行；必须信任该 repository。
 - **没有 MCP 认证协议**：静态 header 可以使用环境变量展开，但带 OAuth 的定义会被拒绝，私有 server 登录流程不在此实现。
 - **生成资源是不可变运行时输入**：repository cache generation 不受监视；必须改变 source、ref、path 或配置才能选择另一份已准备 generation。
diff --git a/packages/self-modification/repository-plugin/package.json b/packages/self-modification/repository-plugin/package.json
index 87e88122f6..fbf18c0cb1 100644
--- a/packages/self-modification/repository-plugin/package.json
+++ b/packages/self-modification/repository-plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-repository-plugin",
-  "description": "Restricted repository plugin format and Cordis runtime for DeepSeek Harness",
+  "description": "Trusted repository package format and Cordis runtime for DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 654e37c201..63ba724108 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -1,5 +1,5 @@
 /**
- * Static repository-plugin preparation and prepared-manifest validation.
+ * Trusted repository-package preparation and prepared-manifest validation.
  * @module
  */
 
@@ -12,21 +12,36 @@ import { parseMcpDocument } from './mcp.ts'
 export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
 /** Fixed directory containing copied static plugin assets. */
 export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
-/** Loader builtin used by every generated import-free wrapper. */
+/** Loader builtin used by every generated repository wrapper. */
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
-/** Exact host-owned command required by the repository package `prepack` lifecycle. */
+/** Host-owned command that repository package `prepack` lifecycles must invoke. */
 export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
 
+/**
+ * Whether a package lifecycle declaration names the host preparation helper.
+ * @param script - package-authored lifecycle command.
+ * @returns true when the required helper command is present.
+ */
+export function hasRepositoryPrepareCommand(script: string): boolean {
+  return script.includes(REPOSITORY_PLUGIN_PREPARE_COMMAND)
+}
+
+const prepackSchema = z.string().min(1).refine(
+  hasRepositoryPrepareCommand,
+  { message: `must invoke ${REPOSITORY_PLUGIN_PREPARE_COMMAND}` },
+)
+
 const sourceMetadataSchema = z.object({
   skills: z.array(z.string().min(1)).default([]),
   mcpServers: z.string().min(1).optional(),
-}).strict().refine(value => value.skills.length > 0 || value.mcpServers !== undefined, {
-  message: 'declare at least one skill root or mcpServers file',
+  entry: z.string().min(1).optional(),
+}).strict().refine(value => value.skills.length > 0 || value.mcpServers !== undefined || value.entry !== undefined, {
+  message: 'declare at least one skill root, mcpServers file, or compiled entry',
 })
 const sourcePackageSchema = z.looseObject({
   name: z.string().min(1),
   scripts: z.looseObject({
-    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+    prepack: prepackSchema,
   }),
   dsh: sourceMetadataSchema,
 })
@@ -34,6 +49,7 @@ const preparedManifestSchema = z.object({
   name: z.string().min(1),
   skills: z.array(z.string().min(1)),
   mcpServers: z.string().min(1).optional(),
+  entry: z.string().min(1).optional(),
 }).strict()
 const preparedConfigSchema = z.object({
   // Wrappers pass import.meta.url, which is always file: for an installed
@@ -43,11 +59,12 @@ const preparedConfigSchema = z.object({
   manifest: preparedManifestSchema,
 }).strict()
 
-/** Static manifest embedded in the generated wrapper. */
+/** Prepared manifest embedded in the generated wrapper. */
 export interface PreparedPluginManifest {
   name: string
   skills: string[]
   mcpServers?: string
+  entry?: string
 }
 
 /** Untrusted generated-wrapper config accepted by the DSH-owned runtime builtin. */
@@ -74,6 +91,7 @@ export function parsePreparedPluginConfig(value: unknown): PreparedPluginConfig
       name: result.data.manifest.name,
       skills: result.data.manifest.skills,
       ...result.data.manifest.mcpServers === undefined ? {} : { mcpServers: result.data.manifest.mcpServers },
+      ...result.data.manifest.entry === undefined ? {} : { entry: result.data.manifest.entry },
     },
   }
 }
@@ -121,28 +139,49 @@ function wrapperSource(manifest: PreparedPluginManifest): string {
     ...manifest.skills.length > 0 ? ['skills'] : [],
     ...manifest.mcpServers === undefined ? [] : ['tools'],
   ]
+  const entryHelpers = manifest.entry === undefined ? [] : [
+    'function unwrap(exports) {',
+    '  const value = exports?.default ?? exports',
+    '  return value?.__esModule ? (value.default ?? value) : value',
+    '}',
+  ]
+  const entryApply = manifest.entry === undefined ? [] : [
+    '  const repositoryPlugin = unwrap(await import(manifest.entry))',
+    "  await mount(ctx, repositoryPlugin, 'repository Plugin entry')",
+  ]
   return [
     '// Generated by dsh-plugin-prepare. Do not edit.',
     `const manifest = ${JSON.stringify(manifest)}`,
+    'const FIBER_ACTIVE = 2',
     `export const name = ${JSON.stringify(manifest.name)}`,
     `export const inject = ${JSON.stringify(inject)}`,
+    ...entryHelpers,
+    'async function mount(ctx, plugin, label, config) {',
+    '  const fiber = ctx.plugin(plugin, config)',
+    '  await fiber',
+    '  if (fiber.state !== FIBER_ACTIVE) {',
+    '    const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)',
+    "    throw new Error(`${label} did not activate (waiting for services: ${missing.join(', ') || 'unknown'})`)",
+    '  }',
+    '}',
     'export async function apply(ctx) {',
     `  const runtime = ctx.loader.builtins[${JSON.stringify(REPOSITORY_PLUGIN_BUILTIN)}]`,
     `  if (runtime === undefined) throw new Error(${JSON.stringify(`missing Cordis builtin ${REPOSITORY_PLUGIN_BUILTIN}`)})`,
-    '  await ctx.plugin(runtime, { baseUrl: import.meta.url, manifest })',
+    "  await mount(ctx, runtime, 'repository Plugin runtime', { baseUrl: import.meta.url, manifest })",
+    ...entryApply,
     '}',
     '',
   ].join('\n')
 }
 
 /**
- * Validate and package one `.dsh-plugin` directory into static assets plus a fixed wrapper.
+ * Validate and package one `.dsh-plugin` directory into copied assets plus a generated wrapper.
  * Outputs are staged and committed by rename, but the final publish (remove
  * old outputs, rename assets, rename entry) is not one atomic step: a crash
  * mid-publish can leave assets without an entry or neither. Rerunning prepare
  * repairs the package; partial outputs are never importable as a plugin.
  * @param directory - `.dsh-plugin` package directory; defaults to the prepare process cwd.
- * @returns the generated static manifest.
+ * @returns the generated prepared manifest.
  */
 export async function prepareDshPlugin(directory: string = process.cwd()): Promise<PreparedPluginManifest> {
   const pluginDirectory = await realpath(resolve(directory))
@@ -169,11 +208,17 @@ export async function prepareDshPlugin(directory: string = process.cwd()): Promi
     mcpSource = await sourcePath(pluginDirectory, sourceRoot, parsed.data.dsh.mcpServers, 'file')
     parseMcpDocument(await readFile(mcpSource, 'utf8'))
   }
+  let entry: string | undefined
+  if (parsed.data.dsh.entry !== undefined) {
+    const entrySource = await sourcePath(pluginDirectory, pluginDirectory, parsed.data.dsh.entry, 'file')
+    entry = `./${relative(pluginDirectory, entrySource).split(sep).join('/')}`
+  }
 
   const manifest: PreparedPluginManifest = {
     name: parsed.data.name,
     skills: skillSources.map((_, index) => `${PREPARED_ASSET_DIRECTORY}/skills/${index}`),
     ...mcpSource === undefined ? {} : { mcpServers: `${PREPARED_ASSET_DIRECTORY}/.mcp.json` },
+    ...entry === undefined ? {} : { entry },
   }
   const staging = await mkdtemp(join(pluginDirectory, '.dsh-plugin-prepare-'))
   try {
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index d3d287974f..403c2d1ae9 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Restricted repository-plugin runtime for static skills and common MCP definitions.
+ * Trusted repository-package runtime for code, skills, and common MCP definitions.
  * @module @deepseek-ai/dsh-repository-plugin
  */
 
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index e8a9e9b9cc..51f015e68a 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -14,6 +14,7 @@ import { z } from 'zod'
 import {
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  hasRepositoryPrepareCommand,
 } from './format.ts'
 
 // Value mirror: Cordis's const enum has no runtime object to import. Keep
@@ -80,7 +81,10 @@ export async function createRepositoryPrepareCommand(): Promise<RepositoryPrepar
 const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
 const installedPackageSchema = z.looseObject({
   scripts: z.looseObject({
-    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+    prepack: z.string().min(1).refine(
+      hasRepositoryPrepareCommand,
+      { message: `must invoke ${REPOSITORY_PLUGIN_PREPARE_COMMAND}` },
+    ),
   }),
 })
 
@@ -127,7 +131,7 @@ async function assertInstalledPackageMetadata(directory: string): Promise<void>
   }
   const result = installedPackageSchema.safeParse(value)
   if (!result.success) {
-    throw new Error(`installed DSH plugin package must declare scripts.prepack as ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
+    throw new Error(`installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
   }
 }
 
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index d026a4e14c..06cacfd699 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -28,13 +28,18 @@ async function temporaryDirectory(name: string): Promise<string> {
   return directory
 }
 
-async function writePlugin(root: string, name: string, dsh: Record<string, unknown>): Promise<string> {
+async function writePlugin(
+  root: string,
+  name: string,
+  dsh: Record<string, unknown>,
+  prepack = RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND,
+): Promise<string> {
   const directory = join(root, '.dsh-plugin')
   await mkdir(directory, { recursive: true })
   await writeFile(join(directory, 'package.json'), `${JSON.stringify({
     name,
     version: '0.0.0',
-    scripts: { prepack: RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND },
+    scripts: { prepack },
     dsh,
   }, undefined, 2)}\n`)
   return directory
@@ -82,6 +87,24 @@ describe('dsh-plugin-prepare', () => {
       .resolves.toContain('mcp.expo.dev')
   })
 
+  it('preserves a compiled package entry and accepts a build before the host prepare command', async () => {
+    const root = await temporaryDirectory('compiled-entry')
+    const directory = await writePlugin(root, 'compiled-entry-fixture', {
+      entry: './lib/plugin.mjs',
+    }, 'npm run build && dsh-plugin-prepare')
+    await mkdir(join(directory, 'lib'))
+    await writeFile(join(directory, 'lib/plugin.mjs'), 'export default { name: "compiled-entry" }\n')
+
+    await expect(RepositoryPlugin.prepareDshPlugin(directory)).resolves.toEqual({
+      name: 'compiled-entry-fixture',
+      skills: [],
+      entry: './lib/plugin.mjs',
+    })
+    const wrapper = await readFile(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME), 'utf8')
+    expect(wrapper).toContain('await import(manifest.entry)')
+    expect(wrapper).toContain('"entry":"./lib/plugin.mjs"')
+  })
+
   it('rejects unsupported OAuth MCP metadata before publishing outputs', async () => {
     const root = await temporaryDirectory('oauth')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({
@@ -118,9 +141,18 @@ describe('dsh-plugin-prepare', () => {
     }))
     await expect(RepositoryPlugin.prepareDshPlugin(lifecycle)).rejects.toThrow('prepack')
 
+    const skippedPrepareRoot = await temporaryDirectory('skipped-prepare')
+    const skippedPrepare = await writePlugin(
+      skippedPrepareRoot,
+      'skipped-prepare',
+      { skills: ['../skills'] },
+      'npm run build',
+    )
+    await expect(RepositoryPlugin.prepareDshPlugin(skippedPrepare)).rejects.toThrow('must invoke dsh-plugin-prepare')
+
     const emptyRoot = await temporaryDirectory('empty-metadata')
     const empty = await writePlugin(emptyRoot, 'empty', {})
-    await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root or mcpServers file')
+    await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root, mcpServers file, or compiled entry')
 
     const missingRoot = await temporaryDirectory('missing-asset')
     const missing = await writePlugin(missingRoot, 'missing', { skills: ['../missing'] })
@@ -149,16 +181,21 @@ describe('dsh-plugin-prepare', () => {
     await writeSkill(outside, 'outside-skill')
     const escaped = await writePlugin(escapedRoot, 'escaped', { skills: [relative(join(escapedRoot, '.dsh-plugin'), outside)] })
     await expect(RepositoryPlugin.prepareDshPlugin(escaped)).rejects.toThrow('escapes its plugin source root')
+
+    const escapedEntryRoot = await temporaryDirectory('escaped-entry')
+    await writeFile(join(escapedEntryRoot, 'outside.mjs'), 'export default {}\n')
+    const escapedEntry = await writePlugin(escapedEntryRoot, 'escaped-entry', { entry: '../outside.mjs' })
+    await expect(RepositoryPlugin.prepareDshPlugin(escapedEntry)).rejects.toThrow('escapes its plugin source root')
   })
 
-  it('validates prepared wrapper configs with and without MCP assets', () => {
+  it('validates prepared wrapper configs with optional MCP assets and code entries', () => {
     expect(() => parsePreparedPluginConfig({})).toThrow('invalid prepared DSH plugin')
     expect(parsePreparedPluginConfig({
       baseUrl: 'file:///plugin/dsh-plugin.mjs',
-      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json' },
+      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json', entry: './lib/plugin.js' },
     })).toEqual({
       baseUrl: 'file:///plugin/dsh-plugin.mjs',
-      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json' },
+      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json', entry: './lib/plugin.js' },
     })
   })
 })
@@ -195,6 +232,35 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.fiber.dispose()
   })
 
+  it('mounts and removes the repository package code entry through the real Loader', async () => {
+    const root = await temporaryDirectory('code-loader')
+    const directory = await writePlugin(root, 'code-loader-fixture', { entry: './lib/plugin.mjs' })
+    await mkdir(join(directory, 'lib'))
+    await writeFile(join(directory, 'lib/plugin.mjs'), [
+      "export const name = 'repository-code-proof'",
+      'export function apply(ctx) {',
+      "  ctx.provide('repositoryCodeProof', { source: 'compiled-entry' })",
+      '}',
+      '',
+    ].join('\n'))
+    await RepositoryPlugin.prepareDshPlugin(directory)
+
+    const ctx = new Context()
+    ctx.baseUrl = pathToFileURL(directory).href + '/'
+    await ctx.plugin(Loader)
+    await ctx.plugin(RepositoryPlugin)
+    const id = await ctx.loader.create({
+      name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
+    })
+    await ctx.loader.await()
+    const getService = (name: string): unknown => (ctx as unknown as { get(name: string): unknown }).get(name)
+    expect(getService('repositoryCodeProof')).toEqual({ source: 'compiled-entry' })
+
+    await ctx.loader.remove(id)
+    expect(getService('repositoryCodeProof')).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
   it('delegates an MCP-only plugin to the existing client without turning connect failure into Loader failure', async () => {
     const root = await temporaryDirectory('mcp-loader')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({
@@ -484,7 +550,23 @@ describe('configured GitHub repository sources', () => {
     await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#old&path:/.dsh-plugin'))
       .rejects.toMatchObject({
         cause: expect.objectContaining({
-          message: expect.stringContaining('must declare scripts.prepack') as string,
+          message: expect.stringContaining('must declare a non-empty scripts.prepack') as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an installed source whose prepack omits the host prepare command', async () => {
+    const root = await temporaryDirectory('installed-skipped-prepare')
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'installed-skipped-prepare',
+      scripts: { prepack: 'npm run build' },
+    }))
+    const ctx = new Context()
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#unprepared&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining('must invoke dsh-plugin-prepare') as string,
         }) as Error,
       })
     await ctx.fiber.dispose()

From a7832cbfbfca3de1dd914d1d064ace39eb67eceb Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:59:48 +0800
Subject: [PATCH 186/262] fix(repository-cache): isolate Git package
 dependencies

---
 ...it-repository-plugin-preparation.i18n.yaml |  4 +-
 ...owned-git-repository-plugin-preparation.md |  9 ++-
 ...ed-git-repository-plugin-preparation.zh.md |  9 ++-
 .../app-boot/tests/repository-cache.spec.ts   | 29 +++++++-
 .../repository-plugin/README.i18n.yaml        |  4 +-
 .../repository-plugin/README.md               |  4 +-
 .../repository-plugin/README.zh.md            |  4 +-
 vendor/README.md                              |  2 +-
 vendor/loader/src/repository.ts               | 70 +++++++++++++------
 9 files changed, 98 insertions(+), 37 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
index d3f10b5273..189c3dc5c2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: b459184f802981f91f611b0b781651cede0c9efd
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 5e24efa59ce44ffa8214f9c5ef9ff722ac0ca73a
+2026-08-08-host-owned-git-repository-plugin-preparation.md: 3f92c0b2d782735bfb548711bb13a7a8d03a3824
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ef34c99b5d9f31ea13c5fddfee77c30e640d25c9
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
index b459184f80..3f92c0b2d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -10,13 +10,15 @@ The repository Plugin authoring contract depended on `scripts.prepare: "dsh-plug
 
 The lifecycle choice also failed for a selectable `.dsh-plugin` inside a pnpm workspace. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` joins the containing workspace and need not execute the unlisted `.dsh-plugin` package's `prepare` script. The install could therefore succeed and publish a cache generation containing only the source package metadata; real DSH startup failed later because `dsh-plugin.mjs` did not exist.
 
+The same workspace discovery could suppress package-owned dependencies after the move to `prepack`. When the source repository carried a root pnpm lockfile but did not list the selected `.dsh-plugin` as a workspace importer, pnpm reported a successful workspace install without installing dependencies declared only by that package. Its TypeScript build then failed because Cordis and the MCP SDK were absent.
+
 The checked-in headless fixture did not catch either defect because it mounted an already prepared wrapper. It proved runtime composition, not GitHub acquisition or package preparation.
 
 ## Decision
 
 The authoring format requires a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` and needs no DSH dependency for that helper. The package may declare its own build and runtime dependencies and run compilation before the helper. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can validate built entries and still copy sibling repository assets such as `../skills` into the package.
 
-`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
+`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. It also prepends a transaction-owned `pnpm` wrapper: the outer install still runs the pinned pnpm entry directly, while pnpm's hard-coded Git-package `pnpm install` reinvokes that same entry with `--ignore-workspace`. The selected package therefore owns dependency resolution even beneath another pnpm lockfile. Both command directories are removed after the child settles. The repository remains trusted package-manager input: DSH supplies the two host commands, but all package lifecycle scripts and dependencies still execute under the existing trust contract.
 
 The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true` GitHub fixture. That fixture installs pinned npm dependencies, type-checks and bundles a TypeScript Cordis entry and MCP server in `prepack`, invokes the host helper, and proves the skill, MCP call, and code entry through real model requests and immutable-cache artifacts. The test fails if CI omits the exact source instead of silently skipping.
 
@@ -30,14 +32,17 @@ The Node 24 consumer lane passes an exact source derived from the pull request h
 
 **Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
 
+**Add the in-repository CI fixture to this repository's pnpm workspace.** Rejected because that would repair only the proof fixture and leave an arbitrary selected package vulnerable to its containing repository's workspace membership and lockfile.
+
 ## Consequences
 
 - A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
 - Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
 - `prepack`, not `prepare`, is part of the pre-release authoring format. It may contain package-owned build steps but must invoke the host helper; missing or empty lifecycle metadata fails installed-package validation instead of producing an ambiguous partial format.
+- A selected package in a pnpm repository installs from its own manifest rather than an enclosing workspace. It must declare its dependencies and cannot rely on workspace-only hoisting; ordinary registry and relative `file:` dependencies remain package-owned inputs.
 - Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
 - The host supplies only the preparation executable. Package dependencies, compilation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires a relative `file:` build dependency during `prepack`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
index 5e24efa59c..ef34c99b5d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -10,13 +10,15 @@ repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`
 
 这种生命周期选择也无法支持 pnpm 工作区内可选的 `.dsh-plugin`。pnpm 会先运行 Git 托管仓库首选的包管理器，再打包选定的子目录，从而准备 Git 托管包。嵌套执行的 `pnpm install` 会加入外层工作区，而不一定执行未列入其中的 `.dsh-plugin` 包的 `prepare` 脚本。因此，安装可能成功并发布一个仅包含源包元数据的缓存 generation；随后真实 DSH 启动因 `dsh-plugin.mjs` 不存在而失败。
 
+迁移到 `prepack` 后，同一项 workspace 发现行为还可能抑制包自有依赖。如果源仓库带有根 pnpm lockfile，却未把所选 `.dsh-plugin` 列为 workspace importer，pnpm 会报告 workspace 安装成功，但不会安装仅由该包声明的依赖。随后其 TypeScript 构建会因缺少 Cordis 和 MCP SDK 而失败。
+
 签入仓库的 headless fixture（测试前置数据）没有捕获任一缺陷，因为它挂载的是已准备好的包装层。它证明的是运行时组合，而不是 GitHub 获取或包准备。
 
 ## 决策
 
 创作格式要求 `scripts.prepack` 非空且调用 `dsh-plugin-prepare`，使用该辅助程序无需 DSH 依赖。包可以声明自己的构建依赖与运行时依赖，并在调用辅助程序前完成编译。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序可以校验构建入口，并继续把 `../skills` 等同仓库的相邻资源复制进包内。
 
-`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
+`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。它还会前置一个由安装事务持有的 `pnpm` 包装命令：外层安装仍直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会通过 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行拥有依赖解析。两个命令目录都会在子进程结算后移除。仓库仍是受信任的包管理器输入：DSH 提供这两条宿主命令，但所有包生命周期脚本和依赖仍按既有信任契约执行。
 
 Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true` 的 GitHub fixture。该 fixture 安装固定版本的 NPM 依赖，在 `prepack` 中对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，调用宿主辅助程序，并通过真实模型请求和不可变缓存产物验证 skill（技能）、MCP 调用和代码入口。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
 
@@ -30,14 +32,17 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 
 
 **在 DSH 中克隆 GitHub 仓库，并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定版本的包管理器负责的 ref 解析、子目录选择、依赖安装、打包清单行为和缓存完整性。
 
+**把仓库内的 CI fixture 加入本仓库的 pnpm workspace。** 拒绝，因为这只能修复证明用的 fixture，任意所选包仍会受其所在仓库的 workspace membership 与 lockfile 影响。
+
 ## 后果
 
 - 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
 - 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
 - 预发布创作格式使用 `prepack` 而不是 `prepare`。其中可以包含包自有构建步骤，但必须调用宿主辅助程序；生命周期元数据缺失或为空会在已安装包校验时失败，而不会留下状态不明的半成品格式。
+- pnpm 仓库中的所选包按自身 manifest 安装，而不是按外层 workspace 安装。它必须声明自己的依赖，不能依赖仅由 workspace 提升而可见的包；常规 registry 依赖与相对 `file:` 依赖仍是包自有输入。
 - 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
 - 宿主只提供准备阶段可执行文件。包依赖、编译和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会让一个被源仓库根 pnpm lockfile 排除的包通过本地 Git 子路径运行，并要求 `prepack` 使用相对 `file:` 构建依赖；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
diff --git a/packages/boot/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
index 186cbe1b43..290b9ab2cc 100644
--- a/packages/boot/app-boot/tests/repository-cache.spec.ts
+++ b/packages/boot/app-boot/tests/repository-cache.spec.ts
@@ -112,7 +112,7 @@ describe('RepositoryCache', () => {
     await expect(cache.resolve(specifier)).rejects.toThrow('repository cache marker is invalid')
   })
 
-  it('selects and prepares a root .dsh-plugin Git subpath through the bundled pnpm', { timeout: 60_000 }, async () => {
+  it('isolates and prepares a .dsh-plugin Git subpath from an enclosing pnpm workspace', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
     const executableDirectory = join(root, 'bin')
@@ -132,16 +132,40 @@ describe('RepositoryCache', () => {
       '',
     ].join('\r\n'))
     await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
+    await mkdir(join(repository, 'build-helper'), { recursive: true })
     await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
       name: 'repository-fixture',
+      private: true,
       version: '1.0.0',
+      packageManager: `pnpm@${BUNDLED_PNPM_VERSION}`,
     })}\n`)
+    await writeFile(join(repository, 'pnpm-workspace.yaml'), 'packages: []\n')
+    await writeFile(join(repository, 'pnpm-lock.yaml'), [
+      "lockfileVersion: '9.0'",
+      'settings:',
+      '  autoInstallPeers: true',
+      '  excludeLinksFromLockfile: false',
+      'importers:',
+      '  .: {}',
+      '',
+    ].join('\n'))
+    await writeFile(join(repository, 'build-helper', 'package.json'), `${JSON.stringify({
+      name: 'repository-build-helper',
+      version: '1.0.0',
+      bin: 'index.js',
+    })}\n`)
+    await writeFile(join(repository, 'build-helper', 'index.js'), [
+      '#!/usr/bin/env node',
+      "require('node:fs').writeFileSync('dependency-built.txt', 'dependency available\\n')",
+      '',
+    ].join('\n'), { mode: 0o700 })
     await writeFile(join(repository, 'skills', 'fixture', 'SKILL.md'), 'repository skill source\n')
     await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
       name: 'repository-plugin-fixture',
       version: '1.0.0',
-      scripts: { prepack: 'dsh-plugin-prepare' },
+      scripts: { prepack: 'repository-build-helper && dsh-plugin-prepare' },
+      devDependencies: { 'repository-build-helper': 'file:../build-helper' },
       dsh: { skills: ['../skills'] },
     })}\n`)
     await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
@@ -159,6 +183,7 @@ describe('RepositoryCache', () => {
     const installed = await new RepositoryCache(join(root, 'cache'), {
       executableDirectories: [executableDirectory],
     }).resolve(specifier)
+    await expect(readFile(join(installed, 'dependency-built.txt'), 'utf8')).resolves.toBe('dependency available\n')
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
     await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
     await expect(readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8'))
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 7d7c04cf69..d41f4681a1 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 52d04f16684842749e57d1b47db0a95beb22558c
-README.zh.md: 921bf70b8a2e78410510d1efce79ced5f52b4641
+README.md: 1d858c5adcc208768dcbe99f129b47abb1722431
+README.zh.md: c2d0e6d72baeb0efb25abd8d50fee2922d2e810b
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 52d04f1668..1d858c5adc 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -32,7 +32,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
 }
 ```
 
-`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. DSH does not transpile TypeScript or infer a package entry.
+`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. The selected package is installed from its own manifest instead of inheriting an enclosing pnpm workspace, so declare every dependency it needs and do not depend on workspace-only hoisting. DSH does not transpile TypeScript or infer a package entry.
 
 `dsh.entry` is an optional relative path to a compiled ESM Cordis Plugin inside `.dsh-plugin`. The module may use either namespace exports or a default export and owns its ordinary `name`, `inject`, `Config`, registrations, and effects. `dsh.skills` is an optional array of local skill roots, and `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one of the three fields is required. Skill and MCP paths may reach adjacent repository assets but must remain beneath the directory containing `.dsh-plugin`; the compiled entry must remain inside the package selected and packed by the package manager. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
 
@@ -59,7 +59,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to build or prepare fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+During exact Git installation, DSH places temporary host-owned `pnpm` and `dsh-plugin-prepare` commands on the isolated package lifecycle `PATH`; neither command is fetched from the repository. The pnpm command reinvokes DSH's pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to install, build, or prepare fails before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 921bf70b8a..c2d0e6d72b 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -32,7 +32,7 @@
 }
 ```
 
-`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。DSH 不转译 TypeScript，也不推断包入口。
+`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。所选包按自身 manifest 独立安装，而不继承外层 pnpm workspace，因此必须声明所需的每项依赖，不能依赖仅由 workspace 提升而可见的包。DSH 不转译 TypeScript，也不推断包入口。
 
 `dsh.entry` 是指向 `.dsh-plugin` 内已编译 ESM Cordis 插件的可选相对路径。该模块可以使用 namespace 导出或 default export，并自行拥有常规的 `name`、`inject`、`Config`、注册和 effect。`dsh.skills` 是可选的本地 skill 根数组，`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；三个字段中至少声明一个。skill 和 MCP 路径可以引用相邻的 repository 资源，但必须留在包含 `.dsh-plugin` 的目录下；已编译入口必须留在由包管理器选中并打包的包内。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
 
@@ -59,7 +59,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。构建或准备失败时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+安装精确指定的 Git 源时，DSH 会把临时的宿主自有 `pnpm` 与 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；两个命令都不从 repository 获取。该 pnpm 命令会以 `--ignore-workspace` 重新调用 DSH 锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。安装、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
diff --git a/vendor/README.md b/vendor/README.md
index 3cc2a313d2..be55f8e77a 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -39,7 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
 9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` run through the bundled pnpm and an injected command directory.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. Temporary command directories are removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and requires its own build dependency.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
diff --git a/vendor/loader/src/repository.ts b/vendor/loader/src/repository.ts
index c0cd1589aa..91ad9c372a 100644
--- a/vendor/loader/src/repository.ts
+++ b/vendor/loader/src/repository.ts
@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
 import { delimiter, dirname, join, resolve } from 'node:path'
 
 /** Exact pnpm release shipped with the Loader for repository installation. */
@@ -48,6 +49,14 @@ function installEnvironment(executableDirectories: readonly string[]): NodeJS.Pr
   }
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+function batchQuote(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`
+}
+
 function appendOutput(current: string, chunk: Uint8Array): string {
   const combined = current + Buffer.from(chunk).toString('utf8')
   return combined.length <= MAX_ERROR_OUTPUT ? combined : combined.slice(-MAX_ERROR_OUTPUT)
@@ -60,29 +69,46 @@ async function installWithBundledPnpm(
   const require = createRequire(import.meta.url)
   const pnpmManifest = require.resolve('pnpm')
   const pnpmBin = join(dirname(pnpmManifest), 'bin', 'pnpm.mjs')
-  let output = ''
-  const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
-    const child = spawn(process.execPath, [
-      pnpmBin,
-      'install',
-      '--no-frozen-lockfile',
-      '--reporter=append-only',
-    ], {
-      cwd: directory,
-      env: installEnvironment(executableDirectories),
-      shell: false,
-      stdio: ['ignore', 'pipe', 'pipe'],
+  const commandDirectory = await mkdtemp(join(tmpdir(), 'cordis-repository-pnpm-'))
+  try {
+    await Promise.all([
+      writeFile(join(commandDirectory, 'pnpm'), [
+        '#!/bin/sh',
+        `exec ${shellQuote(process.execPath)} ${shellQuote(pnpmBin)} --ignore-workspace "$@"`,
+        '',
+      ].join('\n'), { mode: 0o700 }),
+      writeFile(join(commandDirectory, 'pnpm.cmd'), [
+        '@echo off',
+        `${batchQuote(process.execPath)} ${batchQuote(pnpmBin)} --ignore-workspace %*`,
+        '',
+      ].join('\r\n'), { mode: 0o700 }),
+    ])
+    let output = ''
+    const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+      const child = spawn(process.execPath, [
+        pnpmBin,
+        'install',
+        '--no-frozen-lockfile',
+        '--reporter=append-only',
+      ], {
+        cwd: directory,
+        env: installEnvironment([commandDirectory, ...executableDirectories]),
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      child.stdout.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
+      child.stderr.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
+      child.once('error', reject)
+      child.once('close', (code, signal) => { resolve({ code, signal }) })
     })
-    child.stdout.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
-    child.stderr.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
-    child.once('error', reject)
-    child.once('close', (code, signal) => { resolve({ code, signal }) })
-  })
-  if (result.signal !== null) {
-    throw new Error(`bundled pnpm install was killed by ${result.signal}${output ? `\n${output.trimEnd()}` : ''}`)
-  }
-  if (result.code !== 0) {
-    throw new Error(`bundled pnpm install exited with code ${String(result.code)}${output ? `\n${output.trimEnd()}` : ''}`)
+    if (result.signal !== null) {
+      throw new Error(`bundled pnpm install was killed by ${result.signal}${output ? `\n${output.trimEnd()}` : ''}`)
+    }
+    if (result.code !== 0) {
+      throw new Error(`bundled pnpm install exited with code ${String(result.code)}${output ? `\n${output.trimEnd()}` : ''}`)
+    }
+  } finally {
+    await rm(commandDirectory, { recursive: true, force: true })
   }
 }
 

From c750d5a9087532ebb8b207dff266794ed7e7c992 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:12:38 +0800
Subject: [PATCH 187/262] test(repository-plugin): resolve published Cordis
 types

---
 .../github-repository-plugin/.dsh-plugin/tsconfig.json        | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
index 632e4db48c..22d9301cfb 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2024",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
     "strict": true,
     "skipLibCheck": true,
     "noEmit": true

From 67b9e9b1d6eef219864c8cfa1cfca9c56935daa5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:29:21 +0800
Subject: [PATCH 188/262] test(repository-plugin): isolate agent mock sequence

---
 apps/cli/tests/github-repository-plugin.built.e2e.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 0c13a71a02..2e1ea4a08c 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -35,6 +35,8 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       '  config:',
       '    repositories:',
       `      - ${JSON.stringify(source)}`,
+      '- id: session-title-llm',
+      '  disabled: true',
       '',
     ].join('\n'))
 

From 913ecf5f1dbd7dfabb6ec49754882e2c8e114d6e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:13:20 +0800
Subject: [PATCH 189/262] fix(mcp-client): await Cordis startup discovery

---
 ...-trusted-repository-package-code.i18n.yaml |  4 +--
 ...6-08-08-trusted-repository-package-code.md |  6 ++--
 ...8-08-trusted-repository-package-code.zh.md |  6 ++--
 .../github-repository-plugin.built.e2e.ts     | 11 +++---
 docs/config-catalog.md                        |  6 +++-
 packages/mcp/mcp-client/README.i18n.yaml      |  4 +--
 packages/mcp/mcp-client/README.md             |  3 +-
 packages/mcp/mcp-client/README.zh.md          |  3 +-
 packages/mcp/mcp-client/src/index.ts          | 31 ++++++++++------
 packages/mcp/mcp-client/tests/apply.spec.ts   | 36 ++++++++++++++++++-
 .../mcp/mcp-client/tests/mcp-client.e2e.ts    |  8 ++++-
 .../mcp/mcp-client/tests/mcp-client.spec.ts   |  5 +++
 .../repository-plugin/README.i18n.yaml        |  4 +--
 .../repository-plugin/README.md               |  2 +-
 .../repository-plugin/README.zh.md            |  2 +-
 .../repository-plugin/src/mcp.ts              |  4 +++
 .../tests/mcp-format.spec.ts                  |  4 +++
 .../tests/repository-plugin.spec.ts           |  8 ++---
 18 files changed, 108 insertions(+), 39 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index eeea186c92..74c4f0eb41 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
-2026-08-08-trusted-repository-package-code.md: 4968d29a6da4180a8b016eef9176acb9bc64d8b1
-2026-08-08-trusted-repository-package-code.zh.md: 2e9f59bb1f571bb1bace9623a9e6976e0238a017
+2026-08-08-trusted-repository-package-code.md: cf72853836901af9c1c9e9f0d3d23f43997a4e97
+2026-08-08-trusted-repository-package-code.zh.md: cea47d85973a81f904b1596051ac58996459c635
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
index 4968d29a6d..cf72853836 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -18,7 +18,7 @@ The package owns its npm dependencies and build toolchain. `scripts.prepack` is
 
 The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
 
-`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Initial connection failure keeps the existing contained failure contract: it is logged, the client activates with no tools, and disposal still closes the transport.
+`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. Its entry is an `async function`, not an ordinary function returning a Promise: Cordis identifies prototype-bearing ordinary functions as constructors and does not treat a constructor's returned Promise as startup work. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Its `failOnStartupError` config preserves optional standalone servers by default while letting repository adapters require their declared servers. Repository-translated MCP clients enable that mode, so initial connection or discovery failure rejects the candidate generation and rollback still closes the transport.
 
 ## Trust boundary
 
@@ -41,11 +41,11 @@ Model-visible behavior remains governed by the owning DSH seam. A repository ent
 - A TypeScript DSH Plugin can live in a GitHub repository, install ordinary npm dependencies, compile during `prepack`, and run without publishing the Plugin package to npm.
 - Static-only repository packages remain valid and retain import-free wrappers; adding `dsh.entry` opts that package into runtime code import.
 - A package build, dependency install, entry import, unmet service, or Plugin startup failure prevents the candidate generation from replacing the last good configuration.
-- The initial MCP connection can lengthen application startup, while a contained connection failure still yields a running application with no tools from that server.
+- The initial MCP connection can lengthen application startup, and a repository-declared server that is unavailable prevents that candidate generation from activating.
 - Repository code receives host authority, so source review and immutable pinning are operational security requirements rather than optional hardening.
 
 ## Testing
 
-Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication while preserving contained connect failure and teardown.
+Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained connect failure, and prove strict startup rejection still closes the client.
 
 The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. That repository package installs pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Cache assertions require source files to be absent from the packed installation while both built modules, their installed dependency, copied assets, and generated wrapper are present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index 2e9f59bb1f..cea47d8597 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -18,7 +18,7 @@
 
 生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
 
-`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。初始连接失败沿用既有的收束失败契约：系统会记录日志，client 激活但不注册工具，dispose 仍会关闭 transport。
+`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。其入口必须是 `async function`，而不是返回 Promise 的普通函数：Cordis 会把带 prototype 的普通函数识别为 constructor，不会把 constructor 返回的 Promise 当作启动工作。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。其 `failOnStartupError` 配置默认保留独立可选 server 的行为，同时允许 repository adapter 要求已声明 server 必须可用。Repository 转换出的 MCP client 会启用该模式，因此初始连接或发现失败会拒绝候选 generation，回滚仍会关闭 transport。
 
 ## 信任边界
 
@@ -41,11 +41,11 @@
 - TypeScript DSH 插件可以存放在 GitHub 仓库中，安装普通 NPM 依赖，在 `prepack` 期间完成编译，并在无需把插件包发布到 NPM 的情况下运行。
 - 仅含静态贡献的 repository 包仍然有效，并保留无 import 包装层；添加 `dsh.entry` 会使该包选择启用运行时代码导入。
 - 包构建、依赖安装、入口导入、所需服务未满足或插件启动失败，都会阻止候选 generation 替换最后一个可用配置。
-- 初始 MCP 连接可能延长应用启动时间；连接失败被收束后，仍会得到一个正常运行、但不含该 server 工具的应用。
+- 初始 MCP 连接可能延长应用启动时间；repository 声明的 server 不可用时，该候选 generation 无法激活。
 - Repository 代码获得宿主权限，因此源码评审和锁定不可变 ref 是运行安全要求，而不是可选加固措施。
 
 ## 测试
 
-repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，同时保留收束连接失败与清理覆盖。
+repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留选择收束连接失败的能力，并证明严格启动拒绝仍会关闭 client。
 
 Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。该 repository 包安装固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。缓存断言要求打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 2e1ea4a08c..fb0bf2937a 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -67,15 +67,16 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}`).toBe(0)
       expect(result.stdout).toBe('trusted GitHub repository package reached dsh run')
       expect(server.requests).toHaveLength(2)
+      const runtimeDiagnostic = `${result.stderr}\nstdout:\n${result.stdout}`
       const firstRequest = JSON.stringify(server.requests[0]!.body)
       const secondRequest = JSON.stringify(server.requests[1]!.body)
-      expect(firstRequest).toContain(
+      expect(firstRequest, runtimeDiagnostic).toContain(
         'Proves that dsh installed a private repository Plugin from an exact GitHub source.',
       )
-      expect(firstRequest).toContain('mcp__github_repository__proof')
-      expect(firstRequest).toContain('Proves that an MCP server compiled from the exact GitHub repository package is active.')
-      expect(secondRequest).toContain('MCP_FROM_GITHUB_REPOSITORY')
-      expect(secondRequest).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
+      expect(firstRequest, runtimeDiagnostic).toContain('mcp__github_repository__proof')
+      expect(firstRequest, runtimeDiagnostic).toContain('Proves that an MCP server compiled from the exact GitHub repository package is active.')
+      expect(secondRequest, runtimeDiagnostic).toContain('MCP_FROM_GITHUB_REPOSITORY')
+      expect(secondRequest, runtimeDiagnostic).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
 
       const cacheRoot = join(home, 'cache', 'repository-plugins')
       const generations = readdirSync(cacheRoot, { withFileTypes: true }).filter(entry => entry.isDirectory())
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 153ac72cc3..9cc95bcaf5 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -988,6 +988,8 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 
 /** Config for connecting to an MCP server over Streamable HTTP (SSE). */
@@ -1006,10 +1008,12 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 ```
 
-Source: [`packages/mcp/mcp-client/src/index.ts:96`](../packages/mcp/mcp-client/src/index.ts)
+Source: [`packages/mcp/mcp-client/src/index.ts:100`](../packages/mcp/mcp-client/src/index.ts)
 
 ## `@deepseek-ai/dsh-permission`
 
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 6b6d4d9270..2d47705a0a 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-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/mcp/mcp-client/README.md
-README.md: 6bcc195e36d24d7e5ae3462573b30f1b41c963a7
-README.zh.md: 8886c16c3fe66d283ae2191661118729a89f1aeb
+README.md: c87255917a2def0aef938af9f2c910b65d5a96d5
+README.zh.md: 6fd6df39d7c5034795021d41de57f8500cbfd1c5
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index 6bcc195e36..c87255917a 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -44,6 +44,7 @@ The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same
 | `url` | http | yes | MCP server URL |
 | `headers` | http | no | Extra headers (e.g. auth tokens) |
 | `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+| `failOnStartupError` | both | no | Reject plugin activation when the initial connection or tool discovery fails (default `false`) |
 
 ## Tool naming
 
@@ -56,7 +57,7 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection failure is logged and activates with no tools.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection or discovery failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
 - Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index 8886c16c3f..6fd6df39d7 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -44,6 +44,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 | `url` | http | 是 | MCP 服务器 URL |
 | `headers` | http | 否 | 额外标头（例如认证 token） |
 | `toolCallTimeoutMs` | 两者 | 否 | 每次 `callTool` 调用的超时（默认 60000） |
+| `failOnStartupError` | 两者 | 否 | 初始连接或工具发现失败时拒绝插件激活（默认 `false`） |
 
 ## 工具命名
 
@@ -56,7 +57,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接失败会记录日志，插件仍会激活但不注册工具。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接或发现失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
 - 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 9798b4cfcb..348003be52 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -72,6 +72,8 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 
 /** Config for connecting to an MCP server over Streamable HTTP (SSE). */
@@ -90,6 +92,8 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 
 /** Configuration for one stdio or Streamable HTTP MCP server. */
@@ -104,6 +108,7 @@ export const Config = z.union([
     env: z.dict(String).default({}),
     cwd: z.string().default(''),
     toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+    failOnStartupError: z.boolean().default(false),
   }),
   z.object({
     transport: z.const('streamable-http'),
@@ -111,6 +116,7 @@ export const Config = z.union([
     url: z.string().required(),
     headers: z.dict(String).default({}),
     toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+    failOnStartupError: z.boolean().default(false),
   }),
 ]) as unknown as z<Config>
 
@@ -118,11 +124,13 @@ export const Config = z.union([
 
 /**
  * Connect one MCP server and publish its initial tool generation before activation.
+ * This entry remains explicitly `async`: Cordis treats a prototype-bearing
+ * ordinary function as a constructor, whose returned Promise is not startup work.
  * @param ctx - plugin context carrying the tool registry.
  * @param config - resolved transport and server namespace configuration.
  * @returns startup readiness after connection and initial tool discovery settle.
  */
-export function apply(ctx: Context, config: Config): Promise<void> {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   // Reserve the namespace first: a duplicate `serverName` fails THIS instance
   // at load with an actionable error and leaves the earlier instance intact.
   ctx.effect(() => {
@@ -151,10 +159,10 @@ export function apply(ctx: Context, config: Config): Promise<void> {
     toolCallTimeoutMs: config.toolCallTimeoutMs,
   }
 
-  // Connect and set up tools. Errors during connect/first sync are logged,
-  // not thrown (the plugin simply has no tools registered). `ready` resolves
-  // to an accessor for the CURRENT disposer generation, so the effect
-  // disposer below always unregisters the live set, not the first one.
+  // Connect and set up tools. `ready` always settles to an outcome so rollback
+  // can close a partially opened client even when strict startup later rejects.
+  // Its accessor returns the CURRENT disposer generation, so disposal always
+  // unregisters the live set, not the first one.
   const ready = (async () => {
     await client.connect(transport)
 
@@ -174,17 +182,20 @@ export function apply(ctx: Context, config: Config): Promise<void> {
       },
     )
 
-    return () => disposers
+    return { getDisposers: () => disposers }
   })().catch((error: unknown) => {
     ctx.logger.error(`mcp-client(${config.serverName}): failed to connect: ${String(error)}`)
-    return () => new Map<string, () => void>()
+    return { getDisposers: () => new Map<string, () => void>(), error }
   })
 
   ctx.effect(() => async () => {
-    const live = await ready
-    for (const dispose of live().values()) dispose()
+    const outcome = await ready
+    for (const dispose of outcome.getDisposers().values()) dispose()
     try { await client.close() } catch { /* transport already gone */ }
   }, 'mcp-client.connection')
 
-  return ready.then(() => undefined)
+  const outcome = await ready
+  if ('error' in outcome && config.failOnStartupError) {
+    throw new Error(`mcp-client(${config.serverName}): initial connection or tool discovery failed`, { cause: outcome.error })
+  }
 }
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 6bb97a7032..b2444341f1 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -82,6 +82,7 @@ const stdioConfig: Config = {
   env: {},
   cwd: '',
   toolCallTimeoutMs: 60_000,
+  failOnStartupError: false,
 }
 
 // ---- Tests ----
@@ -150,11 +151,30 @@ describe('apply (plugin lifecycle)', () => {
     expect(ctx.tools.get('remote')).toBeUndefined()
   })
 
+  it('keeps the Cordis plugin loading until initial discovery publishes its tools', async () => {
+    const connection: PromiseWithResolvers<void> = Promise.withResolvers()
+    mockConnect.mockImplementation(async () => {
+      await connection.promise
+    })
+    const fiber = ctx.plugin({ name: 'mcp-client-lifecycle', inject, apply }, stdioConfig)
+    let activated = false
+    const activation = Promise.resolve(fiber).then(() => { activated = true })
+
+    await vi.waitFor(() => { expect(mockConnect).toHaveBeenCalled() })
+    expect(activated).toBe(false)
+    expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
+
+    connection.resolve()
+    await activation
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+    await fiber.dispose()
+  })
+
   it('rejects a duplicate serverName at load and leaves the first instance intact', async () => {
     await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
-    expect(() => { void apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
+    await expect(apply(ctx, stdioConfig)).rejects.toThrow(/serverName "srv" is already in use/)
     // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
@@ -204,6 +224,19 @@ describe('apply (plugin lifecycle)', () => {
     expect(mockClose).toHaveBeenCalled()
   })
 
+  it('rejects activation and still closes the client when startup failure is configured as fatal', async () => {
+    mockConnect.mockRejectedValue(new Error('connection refused'))
+    await expect(apply(ctx, {
+      ...stdioConfig,
+      failOnStartupError: true,
+    })).rejects.toThrow('initial connection or tool discovery failed')
+
+    expect(mockListTools).not.toHaveBeenCalled()
+    expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
+    await ctx.fiber.dispose()
+    expect(mockClose).toHaveBeenCalled()
+  })
+
   it('re-syncs tools on ToolListChanged notification', async () => {
     await apply(ctx, stdioConfig)
 
@@ -275,6 +308,7 @@ describe('apply (plugin lifecycle)', () => {
       url: 'http://localhost:3000/mcp',
       headers: { Authorization: 'Bearer x' },
       toolCallTimeoutMs: 30_000,
+      failOnStartupError: false,
     }
 
     await apply(ctx, httpConfig)
diff --git a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
index 6a71ab4007..e1f51d20e9 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
@@ -75,6 +75,7 @@ describe('fixture server — controlled scenarios', () => {
     env: {},
     cwd: packageDir,
     toolCallTimeoutMs: 15_000,
+    failOnStartupError: false,
   }
 
   beforeAll(async () => {
@@ -164,10 +165,11 @@ describe('fixture server — duplicate serverName', () => {
       env: {},
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
+      failOnStartupError: false,
     }
     await apply(ctx, config)
 
-    expect(() => { void apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
+    await expect(apply(ctx, config)).rejects.toThrow(/serverName "dup" is already in use/)
 
     await ctx.fiber.dispose()
     await sleep(200)
@@ -185,6 +187,7 @@ describe('fixture server — disposal', () => {
       env: {},
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
+      failOnStartupError: false,
     })
 
     // Tools are registered before dispose.
@@ -210,6 +213,7 @@ describe('server-everything — official test server', () => {
     env: {},
     cwd: '',
     toolCallTimeoutMs: 30_000,
+    failOnStartupError: false,
   }
 
   beforeAll(async () => {
@@ -277,6 +281,7 @@ describe('server-filesystem — real filesystem operations', () => {
       env: {},
       cwd: '',
       toolCallTimeoutMs: 30_000,
+      failOnStartupError: false,
     }
     await apply(ctx, config)
   }, 60_000)
@@ -393,6 +398,7 @@ describe('streamable-http — in-process MCP server', () => {
       url: baseUrl,
       headers: { Authorization: 'Bearer e2e-test-token' },
       toolCallTimeoutMs: 15_000,
+      failOnStartupError: false,
     }
     await apply(ctx, config)
   }, 30_000)
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index f70f5aa6c1..b95251e7d3 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -713,6 +713,7 @@ describe('createTransport', () => {
       env: {},
       cwd: '/tmp',
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
@@ -727,6 +728,7 @@ describe('createTransport', () => {
       url: 'http://localhost:3000/mcp',
       headers: {},
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
@@ -741,6 +743,7 @@ describe('createTransport', () => {
       url: 'http://localhost:3000/mcp',
       headers: { Authorization: 'Bearer token' },
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
@@ -764,6 +767,7 @@ describe('createTransport', () => {
         env: { EXTRA: 'injected' },
         cwd: '',
         toolCallTimeoutMs: 60_000,
+        failOnStartupError: false,
       }
       // createTransport internally calls buildChildEnv; we verify by inspecting
       // the constructed StdioClientTransport. Since we can't inspect private fields
@@ -791,6 +795,7 @@ describe('createTransport', () => {
       env: { CUSTOM: 'value' },
       cwd: '',
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index d41f4681a1..5c4ad1e929 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 1d858c5adcc208768dcbe99f129b47abb1722431
-README.zh.md: c2d0e6d72baeb0efb25abd8d50fee2922d2e810b
+README.md: e10907408a98cd470ae935b327ae44322f2e54a7
+README.zh.md: b8ba7dccd929574cc5aa1b7a3d68bf4f1e2f80e4
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 1d858c5adc..e10907408a 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -69,7 +69,7 @@ Loading this package registers one effect-scoped Loader builtin. Each generated
 
 The `.mcp.json` root is `{ "mcpServers": { ... } }`. A stdio entry accepts only `type: "stdio"` (optional), `command`, `args`, and `env`; an HTTP entry accepts only `type: "http"`, `url`, and `headers`. String values support exact `${NAME}` process-environment expansion at Plugin load, and a missing name fails that load. HTTP URLs become the existing MCP client's `streamable-http` transport; stdio entries use the prepared package directory as `cwd`.
 
-Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation; a network or child-process connection failure is logged and still activates with no tools.
+Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Repository-declared servers enable its strict startup mode: Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation, while a network, child-process, or discovery failure rejects the candidate repository generation instead of silently activating without its declared tools.
 
 ## Export shape
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index c2d0e6d72b..b8ba7dccd9 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -69,7 +69,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 `.mcp.json` 根对象是 `{ "mcpServers": { ... } }`。stdio 条目只接受可选的 `type: "stdio"`、`command`、`args` 和 `env`；HTTP 条目只接受 `type: "http"`、`url` 和 `headers`。字符串值在插件加载时支持严格的 `${NAME}` 进程环境变量展开；缺失变量会使该次加载失败。HTTP URL 映射到现有 MCP client 的 `streamable-http` transport；stdio 条目以已准备的包目录作为 `cwd`。
 
-未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络或子进程连接失败会记录日志，且插件仍会激活但不注册工具。
+未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。Repository 声明的 server 会启用其严格启动模式：插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络、子进程或发现失败则会拒绝候选 repository generation，而不是在缺少已声明工具的情况下静默激活。
 
 ## 导出形状
 
diff --git a/packages/self-modification/repository-plugin/src/mcp.ts b/packages/self-modification/repository-plugin/src/mcp.ts
index bce8179121..6c1c5ccbf3 100644
--- a/packages/self-modification/repository-plugin/src/mcp.ts
+++ b/packages/self-modification/repository-plugin/src/mcp.ts
@@ -49,12 +49,14 @@ export type ResolvedMcpServer =
     args: string[]
     env: Record<string, string>
     cwd: string
+    failOnStartupError: true
   }
   | {
     transport: 'streamable-http'
     serverName: string
     url: string
     headers: Record<string, string>
+    failOnStartupError: true
   }
 
 function assertTemplate(value: string, location: string): void {
@@ -135,6 +137,7 @@ export function resolveMcpServers(document: McpDocument, environment: NodeJS.Pro
         args: (definition.args ?? []).map((value, index) => expand(value, environment, `mcpServers.${serverName}.args[${index}]`)),
         env: expandMap(definition.env, environment, `mcpServers.${serverName}.env`),
         cwd,
+        failOnStartupError: true,
       }
     }
     const url = expand(definition.url, environment, `mcpServers.${serverName}.url`)
@@ -147,6 +150,7 @@ export function resolveMcpServers(document: McpDocument, environment: NodeJS.Pro
       serverName,
       url,
       headers: expandMap(definition.headers, environment, `mcpServers.${serverName}.headers`),
+      failOnStartupError: true,
     }
   })
 }
diff --git a/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts b/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
index 5251ccdbc2..709c1a2c4b 100644
--- a/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
@@ -22,6 +22,7 @@ describe('repository plugin common .mcp.json support', () => {
       serverName: 'expo',
       url: 'https://mcp.expo.dev/mcp',
       headers: {},
+      failOnStartupError: true,
     }])
   })
 
@@ -43,6 +44,7 @@ describe('repository plugin common .mcp.json support', () => {
       args: ['--endpoint', 'http://localhost:8000'],
       env: { DJ_API_URL: 'http://localhost:8000' },
       cwd: '/plugin',
+      failOnStartupError: true,
     }])
   })
 
@@ -74,12 +76,14 @@ describe('repository plugin common .mcp.json support', () => {
         args: [],
         env: {},
         cwd: '/plugin',
+        failOnStartupError: true,
       },
       {
         transport: 'streamable-http',
         serverName: 'remote',
         url: 'http://localhost:3000/mcp',
         headers: { Authorization: 'Bearer test-token' },
+        failOnStartupError: true,
       },
     ])
   })
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 06cacfd699..40ae773e55 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -261,7 +261,7 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.fiber.dispose()
   })
 
-  it('delegates an MCP-only plugin to the existing client without turning connect failure into Loader failure', async () => {
+  it('fails an MCP repository plugin load when its declared server cannot connect', async () => {
     const root = await temporaryDirectory('mcp-loader')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({
       mcpServers: { offline: { command: join(root, 'missing-mcp-command') } },
@@ -275,12 +275,10 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(RepositoryPlugin)
-    const id = await ctx.loader.create({
+    await expect(ctx.loader.create({
       name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
-    })
-    await ctx.loader.await()
+    })).rejects.toThrow('initial connection or tool discovery failed')
     expect(ctx.tools.schemas().some(tool => tool.name.startsWith('mcp__offline__'))).toBe(false)
-    await ctx.loader.remove(id)
     await ctx.fiber.dispose()
   })
 

From e91ff6d4995d9ce93ca1446d9d501130c3fcdf9a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:19:04 +0800
Subject: [PATCH 190/262] test(repository-plugin): cover MCP activation cleanup

---
 .../tests/repository-plugin.spec.ts           | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 40ae773e55..26b739677a 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -261,6 +261,60 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.fiber.dispose()
   })
 
+  it('mounts and removes tools discovered from a repository MCP server', async () => {
+    const root = await temporaryDirectory('mcp-loader-success')
+    const server = join(root, 'mcp-server.mjs')
+    await writeFile(server, [
+      "import { createInterface } from 'node:readline'",
+      'const lines = createInterface({ input: process.stdin })',
+      'for await (const line of lines) {',
+      '  const request = JSON.parse(line)',
+      "  if (!('id' in request)) continue",
+      '  let result',
+      "  if (request.method === 'initialize') {",
+      '    result = {',
+      '      protocolVersion: request.params.protocolVersion,',
+      '      capabilities: { tools: {} },',
+      "      serverInfo: { name: 'repository-fixture', version: '0.0.0' },",
+      '    }',
+      "  } else if (request.method === 'tools/list') {",
+      '    result = {',
+      '      tools: [{',
+      "        name: 'proof',",
+      "        description: 'Repository MCP proof.',",
+      "        inputSchema: { type: 'object', properties: {} },",
+      '      }],',
+      '    }',
+      '  } else {',
+      '    result = {}',
+      '  }',
+      "  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\\n`)",
+      '}',
+      '',
+    ].join('\n'))
+    await writeFile(join(root, '.mcp.json'), JSON.stringify({
+      mcpServers: { online: { command: process.execPath, args: [server] } },
+    }))
+    const directory = await writePlugin(root, 'mcp-loader-success-fixture', { mcpServers: '../.mcp.json' })
+    await RepositoryPlugin.prepareDshPlugin(directory)
+
+    const ctx = new Context()
+    ctx.baseUrl = pathToFileURL(directory).href + '/'
+    await ctx.plugin(Loader)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(RepositoryPlugin)
+    const id = await ctx.loader.create({
+      name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
+    })
+    await ctx.loader.await()
+    expect(ctx.tools.get('mcp__online__proof')).toBeDefined()
+
+    await ctx.loader.remove(id)
+    expect(ctx.tools.get('mcp__online__proof')).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
   it('fails an MCP repository plugin load when its declared server cannot connect', async () => {
     const root = await temporaryDirectory('mcp-loader')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({

From 29b3e3fa84cdd6a0c2a20ec7615af50eec265301 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:16:14 +0800
Subject: [PATCH 191/262] fix(repository-plugin): require published prepare
 dependency

---
 ...-static-repository-plugin-format.i18n.yaml |   4 +-
 ...6-07-30-static-repository-plugin-format.md |   2 +-
 ...7-30-static-repository-plugin-format.zh.md |   2 +-
 ...-trusted-repository-package-code.i18n.yaml |   4 +-
 ...6-08-08-trusted-repository-package-code.md |   4 +-
 ...8-08-trusted-repository-package-code.zh.md |   4 +-
 ...owned-git-repository-plugin-preparation.md |  48 -------
 ...ed-git-repository-plugin-preparation.zh.md |  48 -------
 ...t-repository-plugin-preparation.i18n.yaml} |   6 +-
 ...acked-git-repository-plugin-preparation.md |  48 +++++++
 ...ed-git-repository-plugin-preparation.zh.md |  48 +++++++
 .../.dsh-plugin/package.json                  |   1 +
 .../github-repository-plugin.built.e2e.ts     | 134 +++++++++++++++++-
 docs/config-catalog.md                        |   2 +-
 knip.json                                     |   3 +
 .../app-boot/tests/repository-cache.spec.ts   |  40 +++---
 .../repository-plugin/README.i18n.yaml        |   4 +-
 .../repository-plugin/README.md               |   5 +-
 .../repository-plugin/README.zh.md            |   5 +-
 .../repository-plugin/package.json            |  20 +++
 .../repository-plugin/src/format.ts           |   4 +-
 .../repository-plugin/src/index.ts            |  32 ++---
 .../repository-plugin/src/source.ts           |  55 +------
 .../tests/repository-plugin.spec.ts           |  18 +--
 vendor/README.md                              |   2 +-
 vendor/loader/src/repository.ts               |  19 +--
 26 files changed, 319 insertions(+), 243 deletions(-)
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
 rename .agents/notes/implemented/bug-fix/{2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml => 2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml} (54%)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 8ffa06ab1a..33e7540bbc 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: 615529c89d32ed87c73d100b632318500e1ae86c
-2026-07-30-static-repository-plugin-format.zh.md: bb90994defccdaf2044b467cb3c5018c1c94641a
+2026-07-30-static-repository-plugin-format.md: afc88bb974ccc6ef7843eaf1e98f16b65bb6d4b3
+2026-07-30-static-repository-plugin-format.zh.md: a6dc6ec6ec89c04b79edea279029ae33091ca0af
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index 615529c89d..afc88bb974 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -14,7 +14,7 @@ The [package-manager-native repository cache](2026-07-30-package-manager-native-
 
 `@deepseek-ai/dsh-repository-plugin` owns the static contribution subformat inside a `.dsh-plugin` package: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths. The package may additionally declare the explicit code entry owned by the [trusted repository package decision](2026-08-08-trusted-repository-package-code.md), and at least one code or static contribution is required.
 
-The `.dsh-plugin` package declares a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The package may build its code first. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's helper-bearing lifecycle metadata before importing that wrapper. A static-only package still receives an import-free wrapper containing its normalized manifest, service-derived `inject` list, and delegation to the `dsh-repository-plugin` Loader builtin. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+The `.dsh-plugin` package declares the published `@deepseek-ai/dsh-repository-plugin` package as a development dependency and a non-empty `scripts.prepack` that invokes its `dsh-plugin-prepare` executable. During Git installation, pnpm installs that dependency from the selected package's own manifest; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The package may build its code first. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's helper-bearing lifecycle metadata before importing that wrapper. A static-only package still receives an import-free wrapper containing its normalized manifest, service-derived `inject` list, and delegation to the `dsh-repository-plugin` Loader builtin. The dependency and workspace-isolation rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
 
 Loading the DSH package registers that builtin as an effect. A generated wrapper mounts the builtin as its child with `import.meta.url`, so all contributions belong to the wrapper fiber and disappear on Loader removal or rollback. The builtin revalidates the prepared manifest and path containment before reading assets. It composes the existing implementations rather than registering skills or MCP tools itself.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index bb90994def..a6dc6ec6ec 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -14,7 +14,7 @@
 
 `@deepseek-ai/dsh-repository-plugin` 负责 `.dsh-plugin` 包内的静态贡献子格式：skill 根和一个通用 `.mcp.json`。其包元数据使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径。每条路径都可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的插件可以拥有其包上方相邻的子树，却不能访问无关宿主路径。该包还可以声明由[受信任 repository 包决策](2026-08-08-trusted-repository-package-code.md)负责的显式代码入口，并且至少需要一种代码或静态贡献。
 
-`.dsh-plugin` 包声明非空 `scripts.prepack`，调用 `dsh-plugin-prepare` 且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。包可以先构建其代码。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的生命周期元数据是否包含辅助命令。仅含静态贡献的包仍会获得无 import 包装层，其中包含规范化 manifest（元数据清单）、由服务派生的 `inject` 列表，以及对 `dsh-repository-plugin` Loader builtin 的委托。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+`.dsh-plugin` 包将已发布的 `@deepseek-ai/dsh-repository-plugin` 包声明为开发依赖，并声明非空 `scripts.prepack` 来调用其 `dsh-plugin-prepare` 可执行文件。在 Git 安装期间，pnpm 会按所选包自身的 manifest（元数据清单）安装该依赖；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。包可以先构建其代码。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的生命周期元数据是否包含辅助命令。仅含静态贡献的包仍会获得无 import 包装层，其中包含规范化 manifest、由服务派生的 `inject` 列表，以及对 `dsh-repository-plugin` Loader builtin 的委托。依赖与 workspace 隔离的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
 
 加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index 74c4f0eb41..16b72afb4e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
-2026-08-08-trusted-repository-package-code.md: cf72853836901af9c1c9e9f0d3d23f43997a4e97
-2026-08-08-trusted-repository-package-code.zh.md: cea47d85973a81f904b1596051ac58996459c635
+2026-08-08-trusted-repository-package-code.md: 6c568964c2d4392054107acb1e73ace8f50d5f0b
+2026-08-08-trusted-repository-package-code.zh.md: c2587286379398ab853b71c8b8819d274d06c65b
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
index cf72853836..6c568964c2 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -14,7 +14,7 @@ A repository author also needs to keep an ordinary TypeScript npm package shape.
 
 A configured repository package is trusted code. Its `.dsh-plugin/package.json` may declare `dsh.entry` as a relative path to a compiled ESM Cordis Plugin inside that package, alongside or instead of `dsh.skills` and `dsh.mcpServers`. At least one contribution is required. The entry may use namespace exports or a default export and retains ordinary Cordis semantics for `name`, `inject`, `Config`, registrations, startup failure, and effect-scoped teardown.
 
-The package owns its npm dependencies and build toolchain. `scripts.prepack` is a non-empty package-authored command that must invoke the host-supplied `dsh-plugin-prepare`, but it may first run `tsc`, `tsdown`, or any other build. DSH neither parses the shell program nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; missing wrapper or build outputs fail before a cache generation becomes usable.
+The package owns its npm dependencies and build toolchain. It declares the published `@deepseek-ai/dsh-repository-plugin` package to obtain the `dsh-plugin-prepare` executable. `scripts.prepack` is a non-empty package-authored command that must invoke that dependency-provided helper, but it may first run `tsc`, `tsdown`, or any other build. DSH neither injects the helper, parses the shell program, nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; a missing dependency, wrapper, or build output fails before a cache generation becomes usable.
 
 The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
 
@@ -48,4 +48,4 @@ Model-visible behavior remains governed by the owning DSH seam. A repository ent
 
 Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained connect failure, and prove strict startup rejection still closes the client.
 
-The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. That repository package installs pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Cache assertions require source files to be absent from the packed installation while both built modules, their installed dependency, copied assets, and generated wrapper are present.
+The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. The test packs the current repository Plugin build with the same private-field removal and workspace-dependency pinning used for publication, serves its packument and tarball from a job-local npm registry, and directs the Git package's ordinary scoped npm resolution there. That repository package obtains `dsh-plugin-prepare` from the simulated published dependency, installs its other pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Registry and cache assertions require npm resolution to reach the simulated publication, source files to be absent from the packed installation, and both built modules, their installed dependency, copied assets, and generated wrapper to be present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index cea47d8597..c258728637 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -14,7 +14,7 @@
 
 已配置的 repository 包是受信任代码。其 `.dsh-plugin/package.json` 可以连同 `dsh.skills` 和 `dsh.mcpServers` 声明 `dsh.entry`，也可以用它取代二者；`dsh.entry` 是指向该包内已编译 ESM Cordis 插件的相对路径。至少需要一种贡献。入口可以使用 namespace 导出或 default export，并沿用 Cordis 对 `name`、`inject`、`Config`、注册、启动失败和 effect 作用域清理的常规语义。
 
-包自行负责其 NPM 依赖和构建工具链。`scripts.prepack` 是由包作者编写的非空命令，必须调用宿主提供的 `dsh-plugin-prepare`，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 既不解析该 shell 程序，也不编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；包装层或构建输出缺失会在缓存 generation 可用前导致失败。
+包自行负责其 NPM 依赖和构建工具链。它声明已发布的 `@deepseek-ai/dsh-repository-plugin` 包以取得 `dsh-plugin-prepare` 可执行文件。`scripts.prepack` 是由包作者编写的非空命令，必须调用该依赖提供的辅助程序，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 不会注入辅助程序，也不会解析该 shell 程序或编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；依赖、包装层或构建输出缺失会在缓存 generation 可用前导致失败。
 
 生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
 
@@ -48,4 +48,4 @@
 
 repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留选择收束连接失败的能力，并证明严格启动拒绝仍会关闭 client。
 
-Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。该 repository 包安装固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。缓存断言要求打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
+Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。测试会采用发布时相同的移除 `private` 字段和固定 workspace 依赖版本流程，对当前 repository 插件构建进行打包；再由作业本地 NPM 注册表提供其 `packument` 与 tarball，并把 Git 包的常规 scoped NPM 解析指向该注册表。该 repository 包从模拟发布的依赖取得 `dsh-plugin-prepare`，安装其他固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。注册表与缓存断言要求 NPM 解析必须命中模拟发布，打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
deleted file mode 100644
index 3f92c0b2d7..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Agent Note: Host-owned preparation makes GitHub repository Plugins installable
-
-Status: implemented
-
-English | [中文](2026-08-08-host-owned-git-repository-plugin-preparation.zh.md)
-
-## Problem
-
-The repository Plugin authoring contract depended on `scripts.prepare: "dsh-plugin-prepare"` and told source repositories to add `@deepseek-ai/dsh-repository-plugin` as a development dependency. That package is private and not published to npm, so an otherwise valid external GitHub repository could not obtain the helper in a clean install.
-
-The lifecycle choice also failed for a selectable `.dsh-plugin` inside a pnpm workspace. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` joins the containing workspace and need not execute the unlisted `.dsh-plugin` package's `prepare` script. The install could therefore succeed and publish a cache generation containing only the source package metadata; real DSH startup failed later because `dsh-plugin.mjs` did not exist.
-
-The same workspace discovery could suppress package-owned dependencies after the move to `prepack`. When the source repository carried a root pnpm lockfile but did not list the selected `.dsh-plugin` as a workspace importer, pnpm reported a successful workspace install without installing dependencies declared only by that package. Its TypeScript build then failed because Cordis and the MCP SDK were absent.
-
-The checked-in headless fixture did not catch either defect because it mounted an already prepared wrapper. It proved runtime composition, not GitHub acquisition or package preparation.
-
-## Decision
-
-The authoring format requires a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` and needs no DSH dependency for that helper. The package may declare its own build and runtime dependencies and run compilation before the helper. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can validate built entries and still copy sibling repository assets such as `../skills` into the package.
-
-`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. It also prepends a transaction-owned `pnpm` wrapper: the outer install still runs the pinned pnpm entry directly, while pnpm's hard-coded Git-package `pnpm install` reinvokes that same entry with `--ignore-workspace`. The selected package therefore owns dependency resolution even beneath another pnpm lockfile. Both command directories are removed after the child settles. The repository remains trusted package-manager input: DSH supplies the two host commands, but all package lifecycle scripts and dependencies still execute under the existing trust contract.
-
-The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true` GitHub fixture. That fixture installs pinned npm dependencies, type-checks and bundles a TypeScript Cordis entry and MCP server in `prepack`, invokes the host helper, and proves the skill, MCP call, and code entry through real model requests and immutable-cache artifacts. The test fails if CI omits the exact source instead of silently skipping.
-
-## Alternatives considered
-
-**Publish the prepare helper to npm.** Rejected because the source package would acquire a release/version dependency solely to call code already owned by the running DSH installation, and the existing helper is intentionally private.
-
-**Keep `prepare` and only inject the command.** Rejected because command availability does not make a nested package's `prepare` lifecycle run when the Git repository's package manager treats it as part of another workspace.
-
-**Prepare after RepositoryCache installs the selected package.** Rejected because pnpm's packed subdirectory no longer contains sibling source assets referenced by paths such as `../skills`; preparation must happen before packlist.
-
-**Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
-
-**Add the in-repository CI fixture to this repository's pnpm workspace.** Rejected because that would repair only the proof fixture and leave an arbitrary selected package vulnerable to its containing repository's workspace membership and lockfile.
-
-## Consequences
-
-- A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
-- Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
-- `prepack`, not `prepare`, is part of the pre-release authoring format. It may contain package-owned build steps but must invoke the host helper; missing or empty lifecycle metadata fails installed-package validation instead of producing an ambiguous partial format.
-- A selected package in a pnpm repository installs from its own manifest rather than an enclosing workspace. It must declare its dependencies and cannot rely on workspace-only hoisting; ordinary registry and relative `file:` dependencies remain package-owned inputs.
-- Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
-- The host supplies only the preparation executable. Package dependencies, compilation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
-
-## Testing
-
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires a relative `file:` build dependency during `prepack`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
deleted file mode 100644
index ef34c99b5d..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Agent Note: 宿主自有的准备机制使 GitHub repository 插件可安装
-
-状态：已实现
-
-[English](2026-08-08-host-owned-git-repository-plugin-preparation.md) | 中文
-
-## 问题
-
-repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`，并要求源码仓库将 `@deepseek-ai/dsh-repository-plugin` 添加为开发依赖。该包是私有包，且未发布到 NPM，因此即使外部 GitHub 仓库符合其他要求，也无法在全新安装中取得该辅助程序。
-
-这种生命周期选择也无法支持 pnpm 工作区内可选的 `.dsh-plugin`。pnpm 会先运行 Git 托管仓库首选的包管理器，再打包选定的子目录，从而准备 Git 托管包。嵌套执行的 `pnpm install` 会加入外层工作区，而不一定执行未列入其中的 `.dsh-plugin` 包的 `prepare` 脚本。因此，安装可能成功并发布一个仅包含源包元数据的缓存 generation；随后真实 DSH 启动因 `dsh-plugin.mjs` 不存在而失败。
-
-迁移到 `prepack` 后，同一项 workspace 发现行为还可能抑制包自有依赖。如果源仓库带有根 pnpm lockfile，却未把所选 `.dsh-plugin` 列为 workspace importer，pnpm 会报告 workspace 安装成功，但不会安装仅由该包声明的依赖。随后其 TypeScript 构建会因缺少 Cordis 和 MCP SDK 而失败。
-
-签入仓库的 headless fixture（测试前置数据）没有捕获任一缺陷，因为它挂载的是已准备好的包装层。它证明的是运行时组合，而不是 GitHub 获取或包准备。
-
-## 决策
-
-创作格式要求 `scripts.prepack` 非空且调用 `dsh-plugin-prepare`，使用该辅助程序无需 DSH 依赖。包可以声明自己的构建依赖与运行时依赖，并在调用辅助程序前完成编译。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序可以校验构建入口，并继续把 `../skills` 等同仓库的相邻资源复制进包内。
-
-`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。它还会前置一个由安装事务持有的 `pnpm` 包装命令：外层安装仍直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会通过 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行拥有依赖解析。两个命令目录都会在子进程结算后移除。仓库仍是受信任的包管理器输入：DSH 提供这两条宿主命令，但所有包生命周期脚本和依赖仍按既有信任契约执行。
-
-Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true` 的 GitHub fixture。该 fixture 安装固定版本的 NPM 依赖，在 `prepack` 中对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，调用宿主辅助程序，并通过真实模型请求和不可变缓存产物验证 skill（技能）、MCP 调用和代码入口。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
-
-## 考虑过的替代方案
-
-**把准备辅助程序发布到 NPM。** 拒绝，因为源包会仅为了调用当前运行的 DSH 安装本就拥有的代码，而增加一个需要发布和管理版本的依赖；现有辅助程序又有意保持私有。
-
-**保留 `prepare`，只注入命令。** 拒绝，因为当 Git 仓库的包管理器把嵌套包当作另一工作区的一部分时，即使命令可用，也不会使嵌套包的 `prepare` 生命周期得以运行。
-
-**在 RepositoryCache 安装选定包后再准备。** 拒绝，因为 pnpm 打包后的子目录不再包含 `../skills` 等路径所引用的同仓库相邻资源；准备必须在生成打包清单前完成。
-
-**在 DSH 中克隆 GitHub 仓库，并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定版本的包管理器负责的 ref 解析、子目录选择、依赖安装、打包清单行为和缓存完整性。
-
-**把仓库内的 CI fixture 加入本仓库的 pnpm workspace。** 拒绝，因为这只能修复证明用的 fixture，任意所选包仍会受其所在仓库的 workspace membership 与 lockfile 影响。
-
-## 后果
-
-- 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
-- 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
-- 预发布创作格式使用 `prepack` 而不是 `prepare`。其中可以包含包自有构建步骤，但必须调用宿主辅助程序；生命周期元数据缺失或为空会在已安装包校验时失败，而不会留下状态不明的半成品格式。
-- pnpm 仓库中的所选包按自身 manifest 安装，而不是按外层 workspace 安装。它必须声明自己的依赖，不能依赖仅由 workspace 提升而可见的包；常规 registry 依赖与相对 `file:` 依赖仍是包自有输入。
-- 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
-- 宿主只提供准备阶段可执行文件。包依赖、编译和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
-
-## 测试
-
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会让一个被源仓库根 pnpm lockfile 排除的包通过本地 Git 子路径运行，并要求 `prepack` 使用相对 `file:` 构建依赖；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
similarity index 54%
rename from .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
rename to .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
index 189c3dc5c2..e1966105a3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
@@ -1,6 +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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: 3f92c0b2d782735bfb548711bb13a7a8d03a3824
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ef34c99b5d9f31ea13c5fddfee77c30e640d25c9
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
+2026-08-08-npm-backed-git-repository-plugin-preparation.md: 9437043d007f5331f36f1c4cff1fe0a3e768b060
+2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 1f06f7372dc0d948906ec4441cb161d2d2ed69e5
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
new file mode 100644
index 0000000000..9437043d00
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
@@ -0,0 +1,48 @@
+# Agent Note: npm-backed preparation makes GitHub repository Plugins self-contained
+
+Status: implemented
+
+English | [中文](2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md)
+
+## Problem
+
+The repository Plugin authoring contract requires `scripts.prepack` to invoke `dsh-plugin-prepare`. Supplying that executable from the running DSH installation made a source package appear valid even when its own manifest could not obtain the helper. It therefore did not prove the behavior users need after `@deepseek-ai/dsh-repository-plugin` is published: an ordinary Git-hosted npm package must be installable and preparable from only its declared dependencies.
+
+A selectable `.dsh-plugin` inside a pnpm workspace has a second isolation requirement. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` can join the containing workspace; when the root lockfile does not list `.dsh-plugin` as an importer, pnpm can report success without installing dependencies declared only by that package. Its TypeScript build or prepare command then fails, or a pre-generated artifact hides the missing dependency.
+
+The checked-in headless fixture mounts an already prepared wrapper. It proves runtime composition, not GitHub acquisition, npm resolution, or package-owned preparation.
+
+## Decision
+
+The `.dsh-plugin` package declares `@deepseek-ai/dsh-repository-plugin` as an ordinary development dependency and invokes its published `dsh-plugin-prepare` executable from `scripts.prepack`. The package may declare any other build and runtime dependencies and run arbitrary compilation before the helper. The repository Plugin package marks its Cordis and DSH peers optional so a helper-only development install resolves only the helper's actual `zod` runtime dependency; an application composition still supplies the peers used by the package's Cordis entry.
+
+DSH does not materialize or prepend a prepare executable. `RepositoryCache` supplies only a transaction-owned `pnpm` wrapper: the outer install runs the pinned pnpm entry directly, while pnpm's hard-coded Git-package `pnpm install` reinvokes the same entry with `--ignore-workspace`. The selected package therefore owns dependency resolution even beneath another pnpm lockfile, and normal package-manager lifecycle `PATH` construction exposes `node_modules/.bin/dsh-plugin-prepare`. The temporary pnpm wrapper disappears after the child settles. The repository remains trusted package-manager input: all dependency and lifecycle code executes under the existing trust contract.
+
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. It uses the existing private DeepSeek Harness repository rather than creating another repository per run. A job-scoped Git configuration gives the read-only job token access to that exact private source and rewrites pnpm's SSH fallback to authenticated HTTPS.
+
+The built-entry acceptance also creates an in-process npm registry. It stages the current built `@deepseek-ai/dsh-repository-plugin` as a publication artifact by removing `private`, replacing workspace protocols with the release version, and packing the declared files. The registry serves the resulting packument and tarball, while a job-local npm config directs only the `@deepseek-ai` scope to it. The real built `dsh run` child then fetches the exact Git source; that package resolves the helper through npm, type-checks and bundles a TypeScript Cordis entry and MCP server, prepares the adjacent skill, and loads all three contributions. A deliberately failing host `PATH` command proves the lifecycle selected the dependency-local executable. The acceptance also requires registry resolution and inspects the immutable prepared cache, so restoring a host-injected helper cannot satisfy it.
+
+## Alternatives considered
+
+**Inject `dsh-plugin-prepare` from the running DSH installation.** Rejected because it lets an incomplete repository manifest pass and tests a host-only path that npm consumers cannot reproduce.
+
+**Publish the source fixture itself to npm.** Rejected because the product contract is specifically that the DSH Plugin remains Git-hosted; only the reusable preparation helper is an npm dependency.
+
+**Create a new private GitHub repository in every CI run.** Rejected because the pull request repository at its exact head SHA is already a real authenticated private Git remote. Per-run repository mutation would add credentials, cleanup, and eventual-consistency failure modes without changing the acquisition path.
+
+**Prepare after `RepositoryCache` installs the selected package.** Rejected because pnpm's packed subdirectory no longer contains sibling source assets referenced by paths such as `../skills`; preparation must happen before packlist.
+
+**Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
+
+## Consequences
+
+- A repository author can commit a `.dsh-plugin` package, TypeScript source, skills, and MCP definitions to GitHub without publishing that Plugin package to npm. The package must declare the published preparation dependency.
+- Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
+- `prepack`, not `prepare`, is part of the authoring format. It may contain arbitrary package-owned build steps but must invoke the dependency-provided helper; missing dependency or lifecycle metadata fails before a cache generation is usable.
+- A selected package in a pnpm repository installs from its own manifest rather than an enclosing workspace. It cannot rely on workspace-only hoisting; ordinary registry and relative `file:` dependencies remain package-owned inputs.
+- Exact source strings identify immutable cache generations; a changed ref or source configuration selects another generation.
+- Package dependencies, compilation, preparation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
+
+## Testing
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires relative `file:` dependencies to provide both its build command and `dsh-plugin-prepare`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and preparation output. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: simulated published helper package, job-local npm registry, fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
new file mode 100644
index 0000000000..1f06f7372d
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: 基于 NPM 的准备机制使 GitHub repository 插件自包含
+
+状态：已实现
+
+[English](2026-08-08-npm-backed-git-repository-plugin-preparation.md) | 中文
+
+## 问题
+
+repository 插件创作契约要求 `scripts.prepack` 调用 `dsh-plugin-prepare`。如果由正在运行的 DSH 安装提供该可执行文件，即使源包自身的 manifest（元数据清单）无法取得辅助程序，它也会显得有效。因此，这并未证明 `@deepseek-ai/dsh-repository-plugin` 发布后用户所需的行为：普通 Git 托管 NPM 包必须只依靠自身声明的依赖即可安装和准备。
+
+pnpm workspace 内可选择的 `.dsh-plugin` 还有另一项隔离要求。pnpm 会在打包所选子目录前运行仓库首选的包管理器，以准备 Git 托管包。嵌套的 `pnpm install` 可能加入外层 workspace；当根 lockfile 未把 `.dsh-plugin` 列为 importer 时，pnpm 可能报告成功，却未安装仅由该包声明的依赖。随后，其 TypeScript 构建或准备命令会失败；也可能因为存在预生成产物，依赖缺失被掩盖。
+
+签入仓库的 headless fixture（测试前置数据）挂载的是已准备好的包装层。它证明运行时组合，而不证明 GitHub 获取、NPM 解析或包自有准备。
+
+## 决策
+
+`.dsh-plugin` 包将已发布的 `@deepseek-ai/dsh-repository-plugin` 声明为普通开发依赖，并在 `scripts.prepack` 中调用其已发布的 `dsh-plugin-prepare` 可执行文件。该包可以声明其他任意构建依赖与运行时依赖，并在辅助程序前执行任意编译。repository 插件包把 Cordis 与 DSH 对等依赖（peer dependency）标为可选，因此仅为使用辅助程序而进行的开发安装只会解析辅助程序实际依赖的 `zod` 运行时依赖；应用组合仍会提供该包 Cordis 入口所使用的对等依赖。
+
+DSH 不会生成准备阶段可执行文件，也不会将其前置到 `PATH`。`RepositoryCache` 只提供一个由事务持有的 `pnpm` 包装脚本：外层安装直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会以 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行负责依赖解析，正常的包管理器生命周期 `PATH` 构造会暴露 `node_modules/.bin/dsh-plugin-prepare`。临时 pnpm 包装脚本会在子进程结算后消失。repository 仍是受信任的包管理器输入：所有依赖与生命周期代码都按既有信任契约执行。
+
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 派生的精确源。它复用现有私有 DeepSeek Harness 仓库，而不会为每次运行新建仓库。作业作用域的 Git 配置允许只读作业 token 访问该精确私有源，并把 pnpm 的 SSH 回退改写为已认证 HTTPS。
+
+构建入口验收还会创建一个进程内 NPM 注册表。它通过移除 `private`、将 workspace protocol 替换为发布版本并打包声明的文件，把当前已构建的 `@deepseek-ai/dsh-repository-plugin` 暂存为发布产物。注册表会提供由此生成的 `packument` 与 tarball，作业本地 NPM 配置则只把 `@deepseek-ai` scope 指向它。实际构建的 `dsh run` 子进程随后获取精确 Git 源；该包通过 NPM 解析辅助程序，对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，准备相邻的 skill（技能），并加载全部三类贡献。一个刻意设为失败的宿主 `PATH` 命令可以证明，该生命周期选中的是依赖内的可执行文件。验收还要求经过注册表解析并检查不可变的已准备缓存，因此恢复宿主注入的辅助程序也无法通过。
+
+## 考虑过的替代方案
+
+**从正在运行的 DSH 安装注入 `dsh-plugin-prepare`。** 拒绝，因为这会让 manifest 不完整的 repository 包通过，并测试 NPM 消费方无法复现的纯宿主路径。
+
+**把源 fixture 本身发布到 NPM。** 拒绝，因为产品契约明确要求 DSH 插件仍托管在 Git；只有可复用的准备辅助程序是 NPM 依赖。
+
+**在每次 CI 运行中创建新的私有 GitHub 仓库。** 拒绝，因为 PR 仓库的精确 head SHA 已是经过认证的真实私有 Git remote。每次运行的仓库变更会增加凭据、清理和最终一致性失败模式，却不改变获取路径。
+
+**在 `RepositoryCache` 安装所选包后再准备。** 拒绝，因为 pnpm 打包后的子目录不再包含 `../skills` 等路径所引用的同仓库相邻资源；准备必须在生成 packlist 前完成。
+
+**在 DSH 中克隆 GitHub 仓库并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定包管理器负责的 ref 解析、子目录选择、依赖安装、packlist 行为和缓存完整性。
+
+## 后果
+
+- 仓库作者可以把 `.dsh-plugin` 包、TypeScript 源码、skill 与 MCP 定义提交到 GitHub，而无需把该插件包发布到 NPM。该包必须声明已发布的准备依赖。
+- 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
+- 创作格式使用 `prepack` 而不是 `prepare`。其中可以包含任意包自有构建步骤，但必须调用依赖提供的辅助程序；依赖或生命周期元数据缺失时，会在缓存 generation 可用前失败。
+- pnpm 仓库中的所选包按自身 manifest 安装，而不继承外层 workspace。它不能依赖仅由 workspace 提升而可见的包；普通注册表依赖和相对 `file:` 依赖仍是包自有输入。
+- 精确源字符串标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
+- 包依赖、编译、准备和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
+
+## 测试
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
index b11ea67c41..6871a4d053 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -22,6 +22,7 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-repository-plugin": "0.0.1",
     "cordis": "4.0.0-rc.7",
     "tsdown": "0.22.2",
     "typescript": "6.0.3"
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index fb0bf2937a..e1386e2bfe 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -1,7 +1,9 @@
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, globSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:http'
 import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { startMockLlmServer } from '@deepseek-ai/dsh-llm-mock-server'
 import { execa } from 'execa'
@@ -9,12 +11,121 @@ import { describe, expect, it } from 'vitest'
 
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const repositoryPluginPackage = join(repoRoot, 'packages/cordis/repository-plugin')
+const releasePackageNames = new Set(globSync([
+  'vendor/*/package.json',
+  'packages/*/*/package.json',
+  'apps/*/package.json',
+], { cwd: repoRoot }).map((filename) => {
+  const manifest = JSON.parse(readFileSync(join(repoRoot, filename), 'utf8')) as Record<string, unknown>
+  if (typeof manifest.name !== 'string') throw new Error(`workspace package name is missing: ${filename}`)
+  return manifest.name
+}))
 const source = process.env.DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE
 const required = process.env.DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E === '1'
 const enabled = required || source !== undefined
 
+interface PublishedPackageRegistry {
+  url: string
+  requests: string[]
+  close(): Promise<void>
+}
+
+function publishedManifest(): Record<string, unknown> {
+  const manifest = JSON.parse(readFileSync(join(repositoryPluginPackage, 'package.json'), 'utf8')) as Record<string, unknown>
+  const version = manifest.version
+  if (typeof version !== 'string') throw new Error('repository Plugin package version is missing')
+  Reflect.deleteProperty(manifest, 'private')
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    const dependencies = manifest[field]
+    if (typeof dependencies !== 'object' || dependencies === null || Array.isArray(dependencies)) continue
+    const entries = dependencies as Record<string, unknown>
+    for (const name of Object.keys(entries)) {
+      if (releasePackageNames.has(name)) {
+        entries[name] = version
+      }
+    }
+  }
+  return manifest
+}
+
+async function startPublishedPackageRegistry(root: string): Promise<PublishedPackageRegistry> {
+  const staging = join(root, 'published-repository-plugin')
+  const artifacts = join(root, 'npm-registry-artifacts')
+  mkdirSync(staging)
+  mkdirSync(artifacts)
+  cpSync(join(repositoryPluginPackage, 'lib'), join(staging, 'lib'), { recursive: true })
+  for (const filename of ['README.md', 'README.zh.md', 'README.i18n.yaml']) {
+    cpSync(join(repositoryPluginPackage, filename), join(staging, filename))
+  }
+  cpSync(join(repoRoot, 'LICENSE'), join(staging, 'LICENSE'))
+  const manifest = publishedManifest()
+  writeFileSync(join(staging, 'package.json'), `${JSON.stringify(manifest, undefined, 2)}\n`)
+  const packed = await execa('pnpm', ['pack', '--pack-destination', artifacts], {
+    cwd: staging,
+    reject: false,
+  })
+  if (packed.exitCode !== 0) {
+    throw new Error(`failed to pack the simulated published prepare package:\n${packed.stderr}\n${packed.stdout}`)
+  }
+  const tarballs = readdirSync(artifacts).filter(filename => filename.endsWith('.tgz'))
+  if (tarballs.length !== 1) throw new Error(`expected one simulated published tarball, found ${tarballs.length}`)
+  const tarball = readFileSync(join(artifacts, tarballs[0]!))
+  const name = manifest.name as string
+  const version = manifest.version as string
+  const requests: string[] = []
+  let registryUrl = ''
+  const server = createServer((request, response) => {
+    const path = decodeURIComponent(new URL(request.url ?? '/', registryUrl).pathname)
+    requests.push(`${request.method ?? 'GET'} ${path}`)
+    if (path === `/${name}`) {
+      const metadata = {
+        name,
+        'dist-tags': { latest: version },
+        versions: {
+          [version]: {
+            ...manifest,
+            dist: {
+              tarball: `${registryUrl}${name}/-/${name.split('/').at(-1)}-${version}.tgz`,
+              shasum: createHash('sha1').update(tarball).digest('hex'),
+              integrity: `sha512-${createHash('sha512').update(tarball).digest('base64')}`,
+            },
+          },
+        },
+      }
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify(metadata))
+      return
+    }
+    if (path === `/${name}/-/${name.split('/').at(-1)}-${version}.tgz`) {
+      response.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': String(tarball.length),
+      })
+      response.end(tarball)
+      return
+    }
+    response.writeHead(404, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'not found' }))
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const address = server.address()
+  if (address === null || typeof address === 'string') throw new Error('simulated npm registry did not expose a TCP address')
+  registryUrl = `http://127.0.0.1:${address.port}/`
+  return {
+    url: registryUrl,
+    requests,
+    close: () => new Promise<void>((resolve, reject) => {
+      server.close((error) => { if (error === undefined) resolve(); else reject(error) })
+    }),
+  }
+}
+
 describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () => {
-  it('installs, builds, and runs skill, MCP, and TypeScript Plugin contributions from a private exact GitHub source', async () => {
+  it('installs the published prepare dependency, then builds and runs skill, MCP, and TypeScript Plugin contributions from a private exact GitHub source', async () => {
     expect(existsSync(dshBin), 'the repository Plugin acceptance must run the built dsh entry').toBe(true)
     expect(source, 'DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE is required by this CI lane').toMatch(
       /^github:[^/\s#&]+\/[^/\s#&]+#[0-9a-f]{40}&path:\/.*\/\.dsh-plugin$/u,
@@ -29,6 +140,17 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       successText: 'trusted GitHub repository package reached dsh run',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-github-repository-plugin-'))
+    const registry = await startPublishedPackageRegistry(home)
+    const npmrc = join(home, 'npmrc')
+    writeFileSync(npmrc, `@deepseek-ai:registry=${registry.url}\n`)
+    const hostBin = join(home, 'host-bin')
+    mkdirSync(hostBin)
+    writeFileSync(join(hostBin, 'dsh-plugin-prepare'), [
+      '#!/bin/sh',
+      'echo "host PATH supplied dsh-plugin-prepare instead of the declared npm dependency" >&2',
+      'exit 91',
+      '',
+    ].join('\n'), { mode: 0o700 })
     const patch = join(home, 'github-repository-plugin.cordis.patch.yml')
     writeFileSync(patch, [
       '- id: repository-plugins',
@@ -59,6 +181,8 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
           DSH_TELEMETRY_DISABLED: '1',
           DEEPSEEK_API_KEY: apiKey,
           DEEPSEEK_BASE_URL: server.baseURL,
+          NPM_CONFIG_USERCONFIG: npmrc,
+          PATH: process.env.PATH === undefined ? hostBin : `${hostBin}${delimiter}${process.env.PATH}`,
         },
       })
       if (result.timedOut) {
@@ -68,6 +192,8 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(result.stdout).toBe('trusted GitHub repository package reached dsh run')
       expect(server.requests).toHaveLength(2)
       const runtimeDiagnostic = `${result.stderr}\nstdout:\n${result.stdout}`
+      expect(registry.requests, runtimeDiagnostic).toContain('GET /@deepseek-ai/dsh-repository-plugin')
+      expect(registry.requests, runtimeDiagnostic).toContain('GET /@deepseek-ai/dsh-repository-plugin/-/dsh-repository-plugin-0.0.1.tgz')
       const firstRequest = JSON.stringify(server.requests[0]!.body)
       const secondRequest = JSON.stringify(server.requests[1]!.body)
       expect(firstRequest, runtimeDiagnostic).toContain(
@@ -98,6 +224,7 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
           '@modelcontextprotocol/sdk': '1.29.0',
         },
         devDependencies: {
+          '@deepseek-ai/dsh-repository-plugin': '0.0.1',
           cordis: '4.0.0-rc.7',
           tsdown: '0.22.2',
           typescript: '6.0.3',
@@ -117,6 +244,7 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(wrapper).toContain('"entry":"./lib/plugin.mjs"')
     } finally {
       await server.close()
+      await registry.close()
       rmSync(home, { recursive: true, force: true })
     }
   }, 190_000)
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 9cc95bcaf5..82f8534ad2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1186,7 +1186,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/self-modification/repository-plugin/src/index.ts:44`](../packages/self-modification/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:43`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 
diff --git a/knip.json b/knip.json
index 0757fe49f8..9ca15de212 100644
--- a/knip.json
+++ b/knip.json
@@ -710,6 +710,9 @@
       "project": [
         "src/**/*.ts"
       ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-repository-plugin"
+      ],
       "ignoreBinaries": [
         "dsh-plugin-prepare"
       ]
diff --git a/packages/boot/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
index 290b9ab2cc..9689790ffc 100644
--- a/packages/boot/app-boot/tests/repository-cache.spec.ts
+++ b/packages/boot/app-boot/tests/repository-cache.spec.ts
@@ -115,24 +115,9 @@ describe('RepositoryCache', () => {
   it('isolates and prepares a .dsh-plugin Git subpath from an enclosing pnpm workspace', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
-    const executableDirectory = join(root, 'bin')
-    await mkdir(executableDirectory)
-    await writeFile(join(executableDirectory, 'dsh-plugin-prepare'), [
-      '#!/usr/bin/env node',
-      "const { cpSync, mkdirSync, writeFileSync } = require('node:fs')",
-      "mkdirSync('dsh-plugin-assets/skills', { recursive: true })",
-      "cpSync('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
-      "writeFileSync('dsh-plugin.mjs', 'export function apply() {}\\n')",
-      "writeFileSync('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
-      '',
-    ].join('\n'), { mode: 0o700 })
-    await writeFile(join(executableDirectory, 'dsh-plugin-prepare.cmd'), [
-      '@echo off',
-      'node "%~dp0\\dsh-plugin-prepare" %*',
-      '',
-    ].join('\r\n'))
     await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
     await mkdir(join(repository, 'build-helper'), { recursive: true })
+    await mkdir(join(repository, 'prepare-helper'), { recursive: true })
     await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
       name: 'repository-fixture',
@@ -160,12 +145,29 @@ describe('RepositoryCache', () => {
       "require('node:fs').writeFileSync('dependency-built.txt', 'dependency available\\n')",
       '',
     ].join('\n'), { mode: 0o700 })
+    await writeFile(join(repository, 'prepare-helper', 'package.json'), `${JSON.stringify({
+      name: 'repository-prepare-helper',
+      version: '1.0.0',
+      bin: { 'dsh-plugin-prepare': 'index.js' },
+    })}\n`)
+    await writeFile(join(repository, 'prepare-helper', 'index.js'), [
+      '#!/usr/bin/env node',
+      "const { cpSync, mkdirSync, writeFileSync } = require('node:fs')",
+      "mkdirSync('dsh-plugin-assets/skills', { recursive: true })",
+      "cpSync('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
+      "writeFileSync('dsh-plugin.mjs', 'export function apply() {}\\n')",
+      "writeFileSync('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
+      '',
+    ].join('\n'), { mode: 0o700 })
     await writeFile(join(repository, 'skills', 'fixture', 'SKILL.md'), 'repository skill source\n')
     await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
       name: 'repository-plugin-fixture',
       version: '1.0.0',
       scripts: { prepack: 'repository-build-helper && dsh-plugin-prepare' },
-      devDependencies: { 'repository-build-helper': 'file:../build-helper' },
+      devDependencies: {
+        'repository-build-helper': 'file:../build-helper',
+        'repository-prepare-helper': 'file:../prepare-helper',
+      },
       dsh: { skills: ['../skills'] },
     })}\n`)
     await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
@@ -180,9 +182,7 @@ describe('RepositoryCache', () => {
     vi.stubEnv('REPOSITORY_TEST_VISIBLE', 'visible')
     vi.stubEnv('REPOSITORY_TEST_TOKEN', 'hidden')
 
-    const installed = await new RepositoryCache(join(root, 'cache'), {
-      executableDirectories: [executableDirectory],
-    }).resolve(specifier)
+    const installed = await new RepositoryCache(join(root, 'cache')).resolve(specifier)
     await expect(readFile(join(installed, 'dependency-built.txt'), 'utf8')).resolves.toBe('dependency available\n')
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
     await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 5c4ad1e929..770cf0fab0 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: e10907408a98cd470ae935b327ae44322f2e54a7
-README.zh.md: b8ba7dccd929574cc5aa1b7a3d68bf4f1e2f80e4
+README.md: 3a6478d5cca05684e80ce0854cb6e0b5d2f88bd4
+README.zh.md: 274d11c96cb61d4d9fa4b837433994248c94bff4
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index e10907408a..3a6478d5cc 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -27,12 +27,13 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-repository-plugin": "^0.0.1",
     "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. The selected package is installed from its own manifest instead of inheriting an enclosing pnpm workspace, so declare every dependency it needs and do not depend on workspace-only hoisting. DSH does not transpile TypeScript or infer a package entry.
+`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. The package declares `@deepseek-ai/dsh-repository-plugin` as an ordinary development dependency so its published executable is available to that lifecycle. DSH does not inject the helper: the repository package declares and runs its own compiler, runtime dependencies, preparation helper, and other npm lifecycle code. The selected package is installed from its own manifest instead of inheriting an enclosing pnpm workspace, so declare every dependency it needs and do not depend on workspace-only hoisting. DSH does not transpile TypeScript or infer a package entry.
 
 `dsh.entry` is an optional relative path to a compiled ESM Cordis Plugin inside `.dsh-plugin`. The module may use either namespace exports or a default export and owns its ordinary `name`, `inject`, `Config`, registrations, and effects. `dsh.skills` is an optional array of local skill roots, and `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one of the three fields is required. Skill and MCP paths may reach adjacent repository assets but must remain beneath the directory containing `.dsh-plugin`; the compiled entry must remain inside the package selected and packed by the package manager. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
 
@@ -59,7 +60,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH places temporary host-owned `pnpm` and `dsh-plugin-prepare` commands on the isolated package lifecycle `PATH`; neither command is fetched from the repository. The pnpm command reinvokes DSH's pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to install, build, or prepare fails before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+During exact Git installation, DSH's bundled pnpm installs the selected package from its own manifest. A transaction-owned `pnpm` wrapper reinvokes the same pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed; its ordinary `node_modules/.bin` lookup obtains `dsh-plugin-prepare` from the declared `@deepseek-ai/dsh-repository-plugin` dependency. That package marks its Cordis/DSH runtime peers optional so using the executable alone does not install the runtime graph. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to resolve the published helper, install dependencies, build, or prepare fails before a cache generation is published. Rationale: [npm-backed Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index b8ba7dccd9..274d11c96c 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -27,12 +27,13 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-repository-plugin": "^0.0.1",
     "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。所选包按自身 manifest 独立安装，而不继承外层 pnpm workspace，因此必须声明所需的每项依赖，不能依赖仅由 workspace 提升而可见的包。DSH 不转译 TypeScript，也不推断包入口。
+`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。包将 `@deepseek-ai/dsh-repository-plugin` 声明为普通开发依赖，使该生命周期可以使用其已发布的可执行文件。DSH 不会注入辅助程序：repository 包自行声明并运行编译器、运行时依赖、准备辅助程序及其他 NPM 生命周期代码。所选包按自身 manifest 独立安装，而不继承外层 pnpm workspace，因此必须声明所需的每项依赖，不能依赖仅由 workspace 提升而可见的包。DSH 不转译 TypeScript，也不推断包入口。
 
 `dsh.entry` 是指向 `.dsh-plugin` 内已编译 ESM Cordis 插件的可选相对路径。该模块可以使用 namespace 导出或 default export，并自行拥有常规的 `name`、`inject`、`Config`、注册和 effect。`dsh.skills` 是可选的本地 skill 根数组，`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；三个字段中至少声明一个。skill 和 MCP 路径可以引用相邻的 repository 资源，但必须留在包含 `.dsh-plugin` 的目录下；已编译入口必须留在由包管理器选中并打包的包内。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
 
@@ -59,7 +60,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 会把临时的宿主自有 `pnpm` 与 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；两个命令都不从 repository 获取。该 pnpm 命令会以 `--ignore-workspace` 重新调用 DSH 锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。安装、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+安装精确指定的 Git 源时，DSH 随附的 pnpm 会按所选包自身的 manifest 安装。由事务持有的 `pnpm` 包装脚本会以 `--ignore-workspace` 重新调用同一份锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行；其常规 `node_modules/.bin` 查找会从已声明的 `@deepseek-ai/dsh-repository-plugin` 依赖取得 `dsh-plugin-prepare`。该包把 Cordis／DSH 运行时对等依赖（peer dependency）标为可选，因此单独使用该可执行文件不会安装运行时依赖图。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。无法解析已发布的辅助程序，或安装依赖、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[基于 NPM 的 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
diff --git a/packages/self-modification/repository-plugin/package.json b/packages/self-modification/repository-plugin/package.json
index fbf18c0cb1..f20ec986c2 100644
--- a/packages/self-modification/repository-plugin/package.json
+++ b/packages/self-modification/repository-plugin/package.json
@@ -36,6 +36,26 @@
     "@deepseek-ai/dsh-skill-local": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "peerDependenciesMeta": {
+    "@cordisjs/plugin-loader": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-invariants": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-mcp-client": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-paths": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill-local": {
+      "optional": true
+    },
+    "cordis": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "zod": "^4.4.3"
   },
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 63ba724108..852e57b253 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -14,11 +14,11 @@ export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
 export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
 /** Loader builtin used by every generated repository wrapper. */
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
-/** Host-owned command that repository package `prepack` lifecycles must invoke. */
+/** Dependency-provided command that repository package `prepack` lifecycles must invoke. */
 export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
 
 /**
- * Whether a package lifecycle declaration names the host preparation helper.
+ * Whether a package lifecycle declaration names the preparation dependency's helper.
  * @param script - package-authored lifecycle command.
  * @returns true when the required helper command is present.
  */
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index 403c2d1ae9..8026199c16 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -20,7 +20,6 @@ import {
 } from './format.ts'
 import { parseMcpDocument, resolveMcpServers } from './mcp.ts'
 import {
-  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -131,24 +130,17 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   if (new Set(repositories).size !== repositories.length) {
     throw new Error('repository sources must resolve to unique exact specifiers')
   }
-  const prepareCommand = repositories.length === 0 ? undefined : await createRepositoryPrepareCommand()
-  try {
-    const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir), {
-      executableDirectories: prepareCommand === undefined ? [] : [prepareCommand.directory],
-    })
-    await ctx.effect(async function* () {
-      ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
-      yield () => {
-        if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
-          Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
-        }
+  const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir))
+  await ctx.effect(async function* () {
+    ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
+    yield () => {
+      if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
+        Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
       }
-      for (const repository of repositories) {
-        const plugin = await loadPreparedRepository(ctx, cache, repository)
-        yield plugin.dispose
-      }
-    }, 'repository-plugin runtime and sources')
-  } finally {
-    await prepareCommand?.dispose()
-  }
+    }
+    for (const repository of repositories) {
+      const plugin = await loadPreparedRepository(ctx, cache, repository)
+      yield plugin.dispose
+    }
+  }, 'repository-plugin runtime and sources')
 }
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index 51f015e68a..a85bb0467e 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -3,10 +3,9 @@
  * @module
  */
 
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { pathToFileURL } from 'node:url'
 import type { Context, Fiber, FiberState, Plugin } from 'cordis'
 import type { RepositoryCache } from '@cordisjs/plugin-loader/repository'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
@@ -24,56 +23,6 @@ const FIBER_ACTIVE = 2 as FiberState.ACTIVE
 /** Directory under the Harness home containing immutable repository generations. */
 export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
 
-/** Temporary host command supplied to repository package lifecycle scripts. */
-export interface RepositoryPrepareCommand {
-  /** Absolute directory to prepend to the isolated install's executable search path. */
-  directory: string
-  /** Remove the temporary command directory. */
-  dispose(): Promise<void>
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", "'\\''")}'`
-}
-
-function batchQuote(value: string): string {
-  return `"${value.replaceAll('%', '%%')}"`
-}
-
-/**
- * Materialize the DSH-owned prepare executable used only while pnpm packs Git source.
- * @returns a command directory and its idempotent cleanup operation.
- */
-export async function createRepositoryPrepareCommand(): Promise<RepositoryPrepareCommand> {
-  const directory = await mkdtemp(join(tmpdir(), 'dsh-repository-plugin-bin-'))
-  const target = fileURLToPath(new URL('../lib/bin.js', import.meta.url))
-  try {
-    await Promise.all([
-      writeFile(join(directory, REPOSITORY_PLUGIN_PREPARE_COMMAND), [
-        '#!/bin/sh',
-        `exec ${shellQuote(process.execPath)} ${shellQuote(target)} "$@"`,
-        '',
-      ].join('\n'), { mode: 0o700 }),
-      writeFile(join(directory, `${REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), [
-        '@echo off',
-        `${batchQuote(process.execPath)} ${batchQuote(target)} %*`,
-        '',
-      ].join('\r\n'), { mode: 0o700 }),
-    ])
-  } catch (cause) {
-    /* v8 ignore next -- requires a host filesystem failure after mkdtemp; cleanup semantics are the contract under test. */
-    await rm(directory, { recursive: true, force: true })
-    /* v8 ignore next -- preserves that unstageable host failure after best-effort cleanup. */
-    throw cause
-  }
-  return {
-    directory,
-    async dispose() {
-      await rm(directory, { recursive: true, force: true })
-    },
-  }
-}
-
 // The ref segment excludes `#` so `github:o/r#a#b` fails here — at the config
 // parser, with the syntax the error message promises — instead of inside the
 // cache's pnpm install ('misconfiguration fails loud at the earliest
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 26b739677a..b5abf6fbdd 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -14,7 +14,6 @@ import * as RepositoryPlugin from '@deepseek-ai/dsh-repository-plugin'
 import * as RepositoryPluginInvariant from '@deepseek-ai/dsh-repository-plugin/invariant'
 import { parsePreparedPluginConfig } from '../src/format.ts'
 import {
-  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -87,7 +86,7 @@ describe('dsh-plugin-prepare', () => {
       .resolves.toContain('mcp.expo.dev')
   })
 
-  it('preserves a compiled package entry and accepts a build before the host prepare command', async () => {
+  it('preserves a compiled package entry and accepts a build before the package prepare command', async () => {
     const root = await temporaryDirectory('compiled-entry')
     const directory = await writePlugin(root, 'compiled-entry-fixture', {
       entry: './lib/plugin.mjs',
@@ -406,17 +405,6 @@ describe('prepared repository plugin Loader composition', () => {
 })
 
 describe('configured GitHub repository sources', () => {
-  it('creates host-owned prepare commands and removes them idempotently', async () => {
-    const command = await createRepositoryPrepareCommand()
-    expect(await readFile(join(command.directory, RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND), 'utf8'))
-      .toContain(process.execPath)
-    expect(await readFile(join(command.directory, `${RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), 'utf8'))
-      .toContain(process.execPath)
-    await command.dispose()
-    await command.dispose()
-    await expect(stat(command.directory)).rejects.toMatchObject({ code: 'ENOENT' })
-  })
-
   it('defaults an omitted source list and rejects unknown configuration fields', () => {
     expect(RepositoryPlugin.Config.parse(undefined)).toEqual({ repositories: [] })
     expect(RepositoryPlugin.Config.safeParse({ repositories: [], unexpected: true }).success).toBe(false)
@@ -608,7 +596,7 @@ describe('configured GitHub repository sources', () => {
     await ctx.fiber.dispose()
   })
 
-  it('rejects an installed source whose prepack omits the host prepare command', async () => {
+  it('rejects an installed source whose prepack omits the package prepare command', async () => {
     const root = await temporaryDirectory('installed-skipped-prepare')
     await writeFile(join(root, 'package.json'), JSON.stringify({
       name: 'installed-skipped-prepare',
diff --git a/vendor/README.md b/vendor/README.md
index be55f8e77a..684c2c6363 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -39,7 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
 9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. Temporary command directories are removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and requires its own build dependency.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. The temporary command directory is removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and obtains both its build and prepare commands from declared dependencies.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
diff --git a/vendor/loader/src/repository.ts b/vendor/loader/src/repository.ts
index 91ad9c372a..5cb6ec387b 100644
--- a/vendor/loader/src/repository.ts
+++ b/vendor/loader/src/repository.ts
@@ -26,8 +26,6 @@ export type RepositoryInstall = (directory: string) => Promise<void>
 export interface RepositoryCacheOptions {
   /** Override the isolated package installation boundary. */
   install?: RepositoryInstall
-  /** Command directories resolved absolutely and prepended to package lifecycle `PATH`. */
-  executableDirectories?: readonly string[]
 }
 
 interface CacheMarker {
@@ -38,14 +36,13 @@ function scrubEnvironment(environment: NodeJS.ProcessEnv = process.env): NodeJS.
   return Object.fromEntries(Object.entries(environment).filter(([name]) => !SENSITIVE_ENV_PATTERN.test(name)))
 }
 
-function installEnvironment(executableDirectories: readonly string[]): NodeJS.ProcessEnv {
+function installEnvironment(commandDirectory: string): NodeJS.ProcessEnv {
   const scrubbed = scrubEnvironment()
-  if (executableDirectories.length === 0) return scrubbed
   const path = Object.entries(scrubbed).find(([name]) => name.toUpperCase() === 'PATH')?.[1]
   const withoutPath = Object.fromEntries(Object.entries(scrubbed).filter(([name]) => name.toUpperCase() !== 'PATH'))
   return {
     ...withoutPath,
-    PATH: [...executableDirectories, ...(path === undefined ? [] : [path])].join(delimiter),
+    PATH: [commandDirectory, ...(path === undefined ? [] : [path])].join(delimiter),
   }
 }
 
@@ -62,10 +59,7 @@ function appendOutput(current: string, chunk: Uint8Array): string {
   return combined.length <= MAX_ERROR_OUTPUT ? combined : combined.slice(-MAX_ERROR_OUTPUT)
 }
 
-async function installWithBundledPnpm(
-  directory: string,
-  executableDirectories: readonly string[],
-): Promise<void> {
+async function installWithBundledPnpm(directory: string): Promise<void> {
   const require = createRequire(import.meta.url)
   const pnpmManifest = require.resolve('pnpm')
   const pnpmBin = join(dirname(pnpmManifest), 'bin', 'pnpm.mjs')
@@ -92,7 +86,7 @@ async function installWithBundledPnpm(
         '--reporter=append-only',
       ], {
         cwd: directory,
-        env: installEnvironment([commandDirectory, ...executableDirectories]),
+        env: installEnvironment(commandDirectory),
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
       })
@@ -174,12 +168,11 @@ export class RepositoryCache {
 
   /**
    * @param directory - caller-owned persistent cache root.
-   * @param options - isolated installer override and lifecycle command directories.
+   * @param options - isolated installer override.
    */
   constructor(directory: string, options: RepositoryCacheOptions = {}) {
     this.directory = resolve(directory)
-    const executableDirectories = (options.executableDirectories ?? []).map(entry => resolve(entry))
-    this.install = options.install ?? (staging => installWithBundledPnpm(staging, executableDirectories))
+    this.install = options.install ?? installWithBundledPnpm
   }
 
   /**

From cc7bd4948d5059ac96769b6c2abbed6eade438c5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:50:54 +0800
Subject: [PATCH 192/262] fix(repository-plugin): reject incomplete MCP
 publication

---
 ...-static-repository-plugin-format.i18n.yaml |  4 ++--
 ...6-07-30-static-repository-plugin-format.md |  4 ++--
 ...7-30-static-repository-plugin-format.zh.md |  4 ++--
 ...-trusted-repository-package-code.i18n.yaml |  4 ++--
 ...6-08-08-trusted-repository-package-code.md |  8 +++----
 ...8-08-trusted-repository-package-code.zh.md | 10 ++++----
 docs/config-catalog.md                        |  4 ++--
 packages/mcp/mcp-client/README.i18n.yaml      |  4 ++--
 packages/mcp/mcp-client/README.md             |  7 +++---
 packages/mcp/mcp-client/README.zh.md          |  7 +++---
 packages/mcp/mcp-client/src/index.ts          | 14 +++++++----
 packages/mcp/mcp-client/src/tools.ts          |  8 +++++--
 packages/mcp/mcp-client/tests/apply.spec.ts   | 24 ++++++++++++++++++-
 .../mcp/mcp-client/tests/mcp-client.spec.ts   |  1 +
 .../repository-plugin/README.i18n.yaml        |  4 ++--
 .../repository-plugin/README.md               |  5 ++--
 .../repository-plugin/README.zh.md            |  5 ++--
 .../repository-plugin/src/format.ts           |  1 +
 .../repository-plugin/src/source.ts           |  6 ++++-
 .../tests/repository-plugin.spec.ts           |  8 ++++++-
 20 files changed, 89 insertions(+), 43 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 33e7540bbc..422b667ebd 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: afc88bb974ccc6ef7843eaf1e98f16b65bb6d4b3
-2026-07-30-static-repository-plugin-format.zh.md: a6dc6ec6ec89c04b79edea279029ae33091ca0af
+2026-07-30-static-repository-plugin-format.md: c66ee111eb0cac9e0d6c54581855ffc18efc8611
+2026-07-30-static-repository-plugin-format.zh.md: 969d7eb536158137807826eba2313670a7d37580
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index afc88bb974..c66ee111eb 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -20,7 +20,7 @@ Loading the DSH package registers that builtin as an effect. A generated wrapper
 
 Each prepared skill set mounts `dsh-skill-local` with a unique `repository:<package-name>` provider name, only the copied custom roots, and watching disabled. `dsh-skill-local` therefore gains two general configuration fields: `providerName` and `includeDefaultRoots`. Their defaults preserve its existing single local provider; repository instances set a distinct name and exclude project/user roots so multiple instances neither collide nor duplicate host-local discovery.
 
-Each `.mcp.json` server becomes one existing `dsh-mcp-client` child. The adapter accepts the common root `{ "mcpServers": ... }`; stdio definitions allow only optional `type: "stdio"`, `command`, `args`, and `env`, while HTTP definitions allow only `type: "http"`, `url`, and `headers`. Exact `${NAME}` process-environment references expand at runtime, after cache preparation; missing names fail Plugin load. HTTP maps to the client's Streamable HTTP transport, and stdio uses the prepared package directory as `cwd`. The existing client alone owns connection attempts, failure logging, remote tool synchronization, tool calls, and disconnects. Consequently an MCP connection failure keeps its established successful-plugin/no-tools behavior and is not reclassified as a repository preparation or Loader failure.
+Each `.mcp.json` server becomes one existing `dsh-mcp-client` child. The adapter accepts the common root `{ "mcpServers": ... }`; stdio definitions allow only optional `type: "stdio"`, `command`, `args`, and `env`, while HTTP definitions allow only `type: "http"`, `url`, and `headers`. Exact `${NAME}` process-environment references expand at runtime, after cache preparation; missing names fail Plugin load. HTTP maps to the client's Streamable HTTP transport, and stdio uses the prepared package directory as `cwd`. The existing client alone owns connection attempts, failure logging, remote tool synchronization, tool calls, and disconnects. Repository instances enable strict startup, so an initial connection, discovery, or tool-registration failure rejects the repository Loader generation; non-strict standalone clients retain the logged successful-plugin/no-tools behavior.
 
 Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `CLAUDE_PLUGIN_ROOT`, and a broader Claude compatibility contract. Commands, hooks, agents, rules, and other foreign manifest conventions are not inferred from static repository layout; DSH-native behavior uses the explicit trusted Cordis entry. Repository subdirectory selection and GitHub source configuration belong to the [standalone app integration](../feature/2026-07-30-config-only-repository-plugins.md), not this static adapter.
 
@@ -34,7 +34,7 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 
 **Watch prepared repository assets.** Rejected because an exact repository cache generation is immutable. Ref, subdirectory, or configuration changes select a new generation; a second watcher would create an unowned refresh identity.
 
-**Treat MCP connect failures as Loader update failures.** Rejected because the existing MCP client deliberately contains connect failures and exposes no tools. Changing that semantic only for repository sources would create two failure contracts for the same server configuration.
+**Make every MCP connect failure a Loader update failure.** Rejected because optional standalone MCP clients deliberately contain startup failures and expose no tools. The MCP client instead owns an explicit strict-startup option, which repository adapters enable for their declared servers.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index a6dc6ec6ec..969d7eb536 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -20,7 +20,7 @@
 
 每份已准备 skill 集合都会挂载 `dsh-skill-local`，使用唯一的 `repository:<package-name>` 提供方名称、仅包含复制后的自定义根，并禁用监视。因此 `dsh-skill-local` 新增两个通用配置字段：`providerName` 和 `includeDefaultRoots`。默认值保持原有单一本地提供方行为；repository 实例设置不同名称并排除项目／用户根，使多个实例既不冲突，也不会重复宿主本地发现。
 
-`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
+`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。Repository 实例会启用严格启动，因此初始连接、发现或工具注册失败会拒绝 repository Loader generation；非严格的独立 client 则保留“记录日志、Plugin 成功但不注册工具”的行为。
 
 未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。命令、hook、agent（智能体）、规则和其他外来 manifest 约定不会从静态 repository 布局中推断出来；DSH 原生行为使用显式的受信任 Cordis 入口。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本静态适配器。
 
@@ -34,7 +34,7 @@
 
 **监视已准备 repository 资源。** 拒绝，因为一个精确 repository cache generation 是不可变的。Ref、子目录或配置变化会选择新 generation；第二套 watcher 会创造一套没有所有者的刷新身份。
 
-**把 MCP 连接失败当作 Loader 更新失败。** 拒绝，因为现有 MCP client 有意收束连接失败并不暴露工具。只对 repository source 改变该语义，会让同一 server 配置拥有两套失败契约。
+**把每次 MCP 连接失败都当作 Loader 更新失败。** 拒绝，因为可选的独立 MCP client 会有意收束启动失败，并且不暴露工具。MCP client 改为自行提供显式的严格启动选项，由 repository 适配器为其声明的 server 启用。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index 16b72afb4e..af4950b20c 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
-2026-08-08-trusted-repository-package-code.md: 6c568964c2d4392054107acb1e73ace8f50d5f0b
-2026-08-08-trusted-repository-package-code.zh.md: c2587286379398ab853b71c8b8819d274d06c65b
+2026-08-08-trusted-repository-package-code.md: 387479b3b36a8bc5e145641ae40802b3090ced70
+2026-08-08-trusted-repository-package-code.zh.md: aff34d4485553f076c5dd1b71f0a3c5b5c62bc8f
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
index 6c568964c2..387479b3b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -16,9 +16,9 @@ A configured repository package is trusted code. Its `.dsh-plugin/package.json`
 
 The package owns its npm dependencies and build toolchain. It declares the published `@deepseek-ai/dsh-repository-plugin` package to obtain the `dsh-plugin-prepare` executable. `scripts.prepack` is a non-empty package-authored command that must invoke that dependency-provided helper, but it may first run `tsc`, `tsdown`, or any other build. DSH neither injects the helper, parses the shell program, nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; a missing dependency, wrapper, or build output fails before a cache generation becomes usable.
 
-The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
+The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. The wrapper statically declares dependencies implied by the prepared manifest; an entry module's additional `inject` is discovered only when mounted and must already be available in the host composition. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
 
-`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. Its entry is an `async function`, not an ordinary function returning a Promise: Cordis identifies prototype-bearing ordinary functions as constructors and does not treat a constructor's returned Promise as startup work. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Its `failOnStartupError` config preserves optional standalone servers by default while letting repository adapters require their declared servers. Repository-translated MCP clients enable that mode, so initial connection or discovery failure rejects the candidate generation and rollback still closes the transport.
+`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. Its entry is an `async function`, not an ordinary function returning a Promise: Cordis identifies prototype-bearing ordinary functions as constructors and does not treat a constructor's returned Promise as startup work. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Its `failOnStartupError` config preserves optional standalone servers by default while letting repository adapters require their declared servers. Repository-translated MCP clients enable that mode, so initial connection, discovery, or tool-registration failure rejects the candidate generation and rollback still closes the transport.
 
 ## Trust boundary
 
@@ -41,11 +41,11 @@ Model-visible behavior remains governed by the owning DSH seam. A repository ent
 - A TypeScript DSH Plugin can live in a GitHub repository, install ordinary npm dependencies, compile during `prepack`, and run without publishing the Plugin package to npm.
 - Static-only repository packages remain valid and retain import-free wrappers; adding `dsh.entry` opts that package into runtime code import.
 - A package build, dependency install, entry import, unmet service, or Plugin startup failure prevents the candidate generation from replacing the last good configuration.
-- The initial MCP connection can lengthen application startup, and a repository-declared server that is unavailable prevents that candidate generation from activating.
+- Initial MCP synchronization can lengthen application startup by the MCP SDK's per-request timeout, and a repository-declared server that is unavailable or cannot publish its complete tool generation prevents that candidate generation from activating.
 - Repository code receives host authority, so source review and immutable pinning are operational security requirements rather than optional hardening.
 
 ## Testing
 
-Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained connect failure, and prove strict startup rejection still closes the client.
+Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained startup failure, and prove strict connection or tool-registration rejection still closes the client.
 
 The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. The test packs the current repository Plugin build with the same private-field removal and workspace-dependency pinning used for publication, serves its packument and tarball from a job-local npm registry, and directs the Git package's ordinary scoped npm resolution there. That repository package obtains `dsh-plugin-prepare` from the simulated published dependency, installs its other pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Registry and cache assertions require npm resolution to reach the simulated publication, source files to be absent from the packed installation, and both built modules, their installed dependency, copied assets, and generated wrapper to be present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index c258728637..aff34d4485 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -16,13 +16,13 @@
 
 包自行负责其 NPM 依赖和构建工具链。它声明已发布的 `@deepseek-ai/dsh-repository-plugin` 包以取得 `dsh-plugin-prepare` 可执行文件。`scripts.prepack` 是由包作者编写的非空命令，必须调用该依赖提供的辅助程序，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 不会注入辅助程序，也不会解析该 shell 程序或编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；依赖、包装层或构建输出缺失会在缓存 generation 可用前导致失败。
 
-生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
+生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。包装层会静态声明已准备 manifest（元数据清单）所隐含的依赖；入口模块的额外 `inject` 只有在挂载时才会被发现，并且此时必须已存在于宿主组合中。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
 
-`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。其入口必须是 `async function`，而不是返回 Promise 的普通函数：Cordis 会把带 prototype 的普通函数识别为 constructor，不会把 constructor 返回的 Promise 当作启动工作。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。其 `failOnStartupError` 配置默认保留独立可选 server 的行为，同时允许 repository adapter 要求已声明 server 必须可用。Repository 转换出的 MCP client 会启用该模式，因此初始连接或发现失败会拒绝候选 generation，回滚仍会关闭 transport。
+`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。其入口必须是 `async function`，而不是返回 Promise 的普通函数：Cordis 会把带 prototype 的普通函数识别为 constructor，不会把 constructor 返回的 Promise 当作启动工作。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。其 `failOnStartupError` 配置默认保留独立可选 server 的行为，同时允许 repository adapter 要求已声明 server 必须可用。Repository 转换出的 MCP client 会启用该模式，因此初始连接、发现或工具注册失败会拒绝候选 generation，回滚仍会关闭 transport。
 
 ## 信任边界
 
-精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest（元数据清单）和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
+精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest 和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
 
 模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务契约。
 
@@ -41,11 +41,11 @@
 - TypeScript DSH 插件可以存放在 GitHub 仓库中，安装普通 NPM 依赖，在 `prepack` 期间完成编译，并在无需把插件包发布到 NPM 的情况下运行。
 - 仅含静态贡献的 repository 包仍然有效，并保留无 import 包装层；添加 `dsh.entry` 会使该包选择启用运行时代码导入。
 - 包构建、依赖安装、入口导入、所需服务未满足或插件启动失败，都会阻止候选 generation 替换最后一个可用配置。
-- 初始 MCP 连接可能延长应用启动时间；repository 声明的 server 不可用时，该候选 generation 无法激活。
+- 初始 MCP 同步可能因 MCP SDK 的单次请求超时而延长应用启动时间；repository 声明的 server 不可用或无法发布完整工具 generation 时，该候选 generation 无法激活。
 - Repository 代码获得宿主权限，因此源码评审和锁定不可变 ref 是运行安全要求，而不是可选加固措施。
 
 ## 测试
 
-repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留选择收束连接失败的能力，并证明严格启动拒绝仍会关闭 client。
+repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留可选择启用的启动失败收束行为，并证明严格连接拒绝或工具注册拒绝仍会关闭 client。
 
 Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。测试会采用发布时相同的移除 `private` 字段和固定 workspace 依赖版本流程，对当前 repository 插件构建进行打包；再由作业本地 NPM 注册表提供其 `packument` 与 tarball，并把 Git 包的常规 scoped NPM 解析指向该注册表。该 repository 包从模拟发布的依赖取得 `dsh-plugin-prepare`，安装其他固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。注册表与缓存断言要求 NPM 解析必须命中模拟发布，打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 82f8534ad2..34ea4a7fbd 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -988,7 +988,7 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 
@@ -1008,7 +1008,7 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 ```
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 2d47705a0a..de8c3e8cd1 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-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/mcp/mcp-client/README.md
-README.md: c87255917a2def0aef938af9f2c910b65d5a96d5
-README.zh.md: 6fd6df39d7c5034795021d41de57f8500cbfd1c5
+README.md: 76d1271f6f7a3e9c959bdcf5e969906f25563c56
+README.zh.md: 49de996863ab16a46cd7ee82b13624523dbb853f
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index c87255917a..76d1271f6f 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -44,7 +44,7 @@ The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same
 | `url` | http | yes | MCP server URL |
 | `headers` | http | no | Extra headers (e.g. auth tokens) |
 | `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
-| `failOnStartupError` | both | no | Reject plugin activation when the initial connection or tool discovery fails (default `false`) |
+| `failOnStartupError` | both | no | Reject plugin activation when initial connection or tool synchronization fails (default `false`) |
 
 ## Tool naming
 
@@ -57,8 +57,8 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection or discovery failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
-- Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection, discovery, or registration failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
+- Listens for `notifications/tools/list_changed` → re-syncs; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation and leaves no tools from that server.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
 - Native/model rendering keeps the existing text projection: text blocks join with newlines while image, audio, resource, and unsupported blocks become placeholders.
@@ -103,6 +103,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
+- **Startup timeout is inherited from the MCP SDK** — DSH does not yet expose a connection/discovery timeout. Each initialize or paginated `tools/list` request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
 - **Crash recovery is manual** — transport closure does not auto-reconnect; registered tools can remain visible but fail against the closed transport until an HMR reload or Host restart.
 - **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
 - **Unsupported MCP output schemas are not enforced** — `structuredContent` falls back to `JsonValue` when the advertised schema uses vocabulary outside the harness subset.
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index 6fd6df39d7..49de996863 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -44,7 +44,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 | `url` | http | 是 | MCP 服务器 URL |
 | `headers` | http | 否 | 额外标头（例如认证 token） |
 | `toolCallTimeoutMs` | 两者 | 否 | 每次 `callTool` 调用的超时（默认 60000） |
-| `failOnStartupError` | 两者 | 否 | 初始连接或工具发现失败时拒绝插件激活（默认 `false`） |
+| `failOnStartupError` | 两者 | 否 | 初始连接或工具同步失败时拒绝插件激活（默认 `false`） |
 
 ## 工具命名
 
@@ -57,8 +57,8 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接或发现失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
-- 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接、发现或注册失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
+- 监听 `notifications/tools/list_changed` → 重新同步；获取阶段失败时保留上一世代的注册，注册冲突则会回滚本次尝试的世代，并且不保留该服务器的任何工具。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
 - Native／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
@@ -103,6 +103,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 ## 已知限制与暂缓事项
 
 - **只桥接 MCP 的工具能力**：资源和提示词没有 harness 消费接口，暂缓实现。
+- **启动超时继承自 MCP SDK**：DSH 尚未公开连接／发现超时。每次 initialize 请求或分页 `tools/list` 请求都使用 SDK 默认的 60 秒，因此在初始同步完成期间，无响应的 server 或 cursor chain 可能同时延迟激活与 teardown。
 - **崩溃恢复需要手动触发**：传输关闭后不会自动重新连接；已注册工具可能仍然可见，但会因传输已关闭而调用失败，直到 HMR 重载或重启 Host。
 - **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。
 - **不强制执行不受支持的 MCP 输出 schema**：已声明 schema 使用 harness 子集之外的词汇时，`structuredContent` 会回退到 `JsonValue`。
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 348003be52..0fe7dd9de3 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -72,7 +72,7 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 
@@ -92,7 +92,7 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 
@@ -155,6 +155,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   )
 
   const opts = {
+    registrationFailure: 'contain' as const,
     serverName: config.serverName,
     toolCallTimeoutMs: config.toolCallTimeoutMs,
   }
@@ -166,7 +167,10 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   const ready = (async () => {
     await client.connect(transport)
 
-    let disposers = await syncTools(client, ctx, opts, new Map())
+    let disposers = await syncTools(client, ctx, {
+      ...opts,
+      registrationFailure: config.failOnStartupError ? 'throw' : 'contain',
+    }, new Map())
 
     client.setNotificationHandler(
       ToolListChangedNotificationSchema,
@@ -184,7 +188,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
 
     return { getDisposers: () => disposers }
   })().catch((error: unknown) => {
-    ctx.logger.error(`mcp-client(${config.serverName}): failed to connect: ${String(error)}`)
+    ctx.logger.error(`mcp-client(${config.serverName}): startup failed: ${String(error)}`)
     return { getDisposers: () => new Map<string, () => void>(), error }
   })
 
@@ -196,6 +200,6 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
 
   const outcome = await ready
   if ('error' in outcome && config.failOnStartupError) {
-    throw new Error(`mcp-client(${config.serverName}): initial connection or tool discovery failed`, { cause: outcome.error })
+    throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error })
   }
 }
diff --git a/packages/mcp/mcp-client/src/tools.ts b/packages/mcp/mcp-client/src/tools.ts
index 49e023ca4d..28c2a66319 100644
--- a/packages/mcp/mcp-client/src/tools.ts
+++ b/packages/mcp/mcp-client/src/tools.ts
@@ -23,6 +23,8 @@ import type { JsonSchemaNode, JsonValue } from '@deepseek-ai/dsh-tools'
 
 /** Resolved options relevant to tool bridging. */
 export interface ToolBridgeOptions {
+  /** Whether a registry conflict is contained or rejects this synchronization. */
+  registrationFailure: 'contain' | 'throw'
   serverName: string
   toolCallTimeoutMs: number
 }
@@ -111,8 +113,9 @@ export function publicToolName(serverName: string, rawName: string): string {
  * 2. Swap: dispose the previous generation, register the new one. A registry
  *    conflict here can only mean a foreign registration squats on this
  *    server's `mcp__<serverName>__` namespace — the partial generation is
- *    rolled back (zero tools from this server), the error is logged, and an
- *    empty map is returned.
+ *    rolled back (zero tools from this server) and logged. Initial strict
+ *    synchronization may propagate the conflict so its parent transaction
+ *    rejects; ordinary clients and later re-syncs return an empty map.
  *
  * @param client - Connected MCP Client instance used to list and call tools.
  * @param ctx - Cordis context providing the `tools` service for registration.
@@ -164,6 +167,7 @@ export async function syncTools(
     // sees either the full generation or none of it — never a partial set.
     for (const dispose of disposers.values()) dispose()
     ctx.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`)
+    if (opts.registrationFailure === 'throw') throw error
     return new Map()
   }
   return disposers
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index b2444341f1..70c88ad660 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -229,7 +229,7 @@ describe('apply (plugin lifecycle)', () => {
     await expect(apply(ctx, {
       ...stdioConfig,
       failOnStartupError: true,
-    })).rejects.toThrow('initial connection or tool discovery failed')
+    })).rejects.toThrow('initial connection or tool synchronization failed')
 
     expect(mockListTools).not.toHaveBeenCalled()
     expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
@@ -237,6 +237,28 @@ describe('apply (plugin lifecycle)', () => {
     expect(mockClose).toHaveBeenCalled()
   })
 
+  it('rejects strict startup when the initial tool generation cannot be registered', async () => {
+    ctx.tools.register({
+      name: 'mcp__srv__remote',
+      description: 'Foreign squatter',
+      parameters: { type: 'object' },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value as string }],
+      },
+      execute: async () => 'foreign',
+    })
+
+    await expect(apply(ctx, {
+      ...stdioConfig,
+      failOnStartupError: true,
+    })).rejects.toThrow('initial connection or tool synchronization failed')
+
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+    await ctx.fiber.dispose()
+    expect(mockClose).toHaveBeenCalled()
+  })
+
   it('re-syncs tools on ToolListChanged notification', async () => {
     await apply(ctx, stdioConfig)
 
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index b95251e7d3..d19e30b94b 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -64,6 +64,7 @@ async function mountRegistry(): Promise<Context> {
 }
 
 const defaultOpts: ToolBridgeOptions = {
+  registrationFailure: 'contain',
   serverName: 'srv',
   toolCallTimeoutMs: 60_000,
 }
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 770cf0fab0..9d7f305263 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 3a6478d5cca05684e80ce0854cb6e0b5d2f88bd4
-README.zh.md: 274d11c96cb61d4d9fa4b837433994248c94bff4
+README.md: 0df0680cef873d9f7078cb63d1c803e5c323f07c
+README.zh.md: 04e5f8f81ba1b3e788775e9deaff6bb0b6dd1a48
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 3a6478d5cc..0df0680cef 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -64,13 +64,13 @@ During exact Git installation, DSH's bundled pnpm installs the selected package
 
 ## Runtime composition
 
-Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates its prepared static manifest to that builtin, then imports and mounts `dsh.entry` when declared. The entry is an ordinary Cordis child Plugin: its own `inject` gates activation, startup failures reject the repository generation, and all of its effects disappear on Loader removal or rollback. The runtime likewise validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped by `files`/`.npmignore` or damaged in cache fails instead of silently losing contributions. Repository skill roots mount as uniquely named `dsh-skill-local` providers with default project/user roots excluded and watching disabled; cached package generations are immutable.
+Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates its prepared static manifest to that builtin, then imports and mounts `dsh.entry` when declared. The wrapper can statically gate only the `loader`, `skills`, and `tools` services implied by the prepared manifest; the entry's own `inject` is discovered when that child is mounted. The entry must reach `ACTIVE`, so a missing entry-only service or startup failure rejects the repository generation instead of committing an inert child, and all effects disappear on Loader removal or rollback. The runtime likewise validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped by `files`/`.npmignore` or damaged in cache fails instead of silently losing contributions. Repository skill roots mount as uniquely named `dsh-skill-local` providers with default project/user roots excluded and watching disabled; cached package generations are immutable.
 
 ## Common MCP format
 
 The `.mcp.json` root is `{ "mcpServers": { ... } }`. A stdio entry accepts only `type: "stdio"` (optional), `command`, `args`, and `env`; an HTTP entry accepts only `type: "http"`, `url`, and `headers`. String values support exact `${NAME}` process-environment expansion at Plugin load, and a missing name fails that load. HTTP URLs become the existing MCP client's `streamable-http` transport; stdio entries use the prepared package directory as `cwd`.
 
-Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Repository-declared servers enable its strict startup mode: Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation, while a network, child-process, or discovery failure rejects the candidate repository generation instead of silently activating without its declared tools.
+Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Repository-declared servers enable its strict startup mode: Plugin activation waits for the initial connection and tool synchronization, so the first model request observes a fully registered initial tool generation, while a network, child-process, discovery, or registration failure rejects the candidate repository generation instead of silently activating without its declared tools.
 
 ## Export shape
 
@@ -123,5 +123,6 @@ Stable registrations preserve the owning surface's normal prefix behavior. Loadi
 ## Known Limitations and Deferred Work
 
 - **No code sandbox** — `dsh.entry`, npm dependencies, and package lifecycle scripts execute with the DSH host's authority; repository trust is mandatory.
+- **Entry-only service dependencies are not pre-gated** — the generated wrapper cannot declare an entry module's `inject` before importing it. Any service beyond those implied by Skills or MCP must already exist when the wrapper mounts the entry, or that repository generation rejects.
 - **No MCP authentication protocol** — static headers may use environment expansion, but OAuth-bearing definitions reject and private-server login flows are not implemented here.
 - **Generated assets are immutable runtime input** — repository cache generations are not watched; source, ref, path, or configuration must select another prepared generation.
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 274d11c96c..04e5f8f81b 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -64,13 +64,13 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 运行时组合
 
-加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装层都把已准备的静态 manifest（元数据清单）委托给该 builtin，再在声明了 `dsh.entry` 时导入并挂载该入口。入口是普通的 Cordis 子插件：其自有 `inject` 会门控激活，启动失败会拒绝 repository generation，Loader 移除或回滚时，其所有 effect 都会消失。运行时同样会在挂载前校验每个声明的 skill 根都是包内实际存在的目录——生成输出因 `files`／`.npmignore` 被丢弃或在缓存中损坏的包会加载失败，而不是静默丢失贡献。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。
+加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装层都把已准备的静态 manifest（元数据清单）委托给该 builtin，再在声明了 `dsh.entry` 时导入并挂载该入口。包装层只能静态门控已准备 manifest 所隐含的 `loader`、`skills` 与 `tools` 服务；入口自身的 `inject` 要到挂载该子级时才会发现。入口必须进入 `ACTIVE`，因此缺少入口专用服务或启动失败时，会拒绝 repository generation，而不会提交未激活的子级；Loader 移除或回滚时，所有 effect 都会消失。运行时同样会在挂载前校验每个声明的 skill 根都是包内实际存在的目录——生成输出因 `files`／`.npmignore` 被丢弃或在缓存中损坏的包会加载失败，而不是静默丢失贡献。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。
 
 ## 通用 MCP 格式
 
 `.mcp.json` 根对象是 `{ "mcpServers": { ... } }`。stdio 条目只接受可选的 `type: "stdio"`、`command`、`args` 和 `env`；HTTP 条目只接受 `type: "http"`、`url` 和 `headers`。字符串值在插件加载时支持严格的 `${NAME}` 进程环境变量展开；缺失变量会使该次加载失败。HTTP URL 映射到现有 MCP client 的 `streamable-http` transport；stdio 条目以已准备的包目录作为 `cwd`。
 
-未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。Repository 声明的 server 会启用其严格启动模式：插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络、子进程或发现失败则会拒绝候选 repository generation，而不是在缺少已声明工具的情况下静默激活。
+未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。Repository 声明的 server 会启用其严格启动模式：插件激活会等待初始连接与工具同步，因此首个模型请求会看到已完整注册的初始工具 generation；网络、子进程、发现或注册失败则会拒绝候选 repository generation，而不是在缺少已声明工具的情况下静默激活。
 
 ## 导出形状
 
@@ -123,5 +123,6 @@ Namespace 插件：具名导出 `name`／`inject`／`apply`、准备阶段常量
 ## 已知限制与暂缓事项
 
 - **没有代码沙箱**：`dsh.entry`、NPM 依赖和包生命周期脚本以 DSH 宿主权限执行；必须信任该 repository。
+- **入口专用服务依赖不会预先门控**：生成的包装层无法在导入入口模块前声明其 `inject`。除 skill 或 MCP 隐含的服务外，其他任何服务在包装层挂载入口时都必须已经存在，否则该 repository generation 会被拒绝。
 - **没有 MCP 认证协议**：静态 header 可以使用环境变量展开，但带 OAuth 的定义会被拒绝，私有 server 登录流程不在此实现。
 - **生成资源是不可变运行时输入**：repository cache generation 不受监视；必须改变 source、ref、path 或配置才能选择另一份已准备 generation。
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 852e57b253..743a2fbf39 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -152,6 +152,7 @@ function wrapperSource(manifest: PreparedPluginManifest): string {
   return [
     '// Generated by dsh-plugin-prepare. Do not edit.',
     `const manifest = ${JSON.stringify(manifest)}`,
+    '// Value mirror: Cordis const enum FiberState.ACTIVE; keep aligned with dsh-repository-plugin source.ts.',
     'const FIBER_ACTIVE = 2',
     `export const name = ${JSON.stringify(manifest.name)}`,
     `export const inject = ${JSON.stringify(inject)}`,
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index a85bb0467e..8460bc800b 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -80,7 +80,11 @@ async function assertInstalledPackageMetadata(directory: string): Promise<void>
   }
   const result = installedPackageSchema.safeParse(value)
   if (!result.success) {
-    throw new Error(`installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
+    throw new Error([
+      `installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:`,
+      z.prettifyError(result.error),
+      'Clear the matching repository cache generation before retrying the same source, or select a different exact source/ref/path after fixing the package.',
+    ].join('\n'))
   }
 }
 
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index b5abf6fbdd..3b8d587dbc 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -330,7 +330,7 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.plugin(RepositoryPlugin)
     await expect(ctx.loader.create({
       name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
-    })).rejects.toThrow('initial connection or tool discovery failed')
+    })).rejects.toThrow('initial connection or tool synchronization failed')
     expect(ctx.tools.schemas().some(tool => tool.name.startsWith('mcp__offline__'))).toBe(false)
     await ctx.fiber.dispose()
   })
@@ -593,6 +593,12 @@ describe('configured GitHub repository sources', () => {
           message: expect.stringContaining('must declare a non-empty scripts.prepack') as string,
         }) as Error,
       })
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#old&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining('Clear the matching repository cache generation') as string,
+        }) as Error,
+      })
     await ctx.fiber.dispose()
   })
 

From e00ec8e2aa023e58f637a3891c1a8d9f8b2db43c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:57:56 +0800
Subject: [PATCH 193/262] test(repository-plugin): refresh prepared wrapper
 fixture

---
 .../tests/fixtures/repository-plugin/dsh-plugin.mjs              | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
index ce61e58973..29aa97c5ec 100644
--- a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
+++ b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
@@ -1,5 +1,6 @@
 // Generated by dsh-plugin-prepare. Do not edit.
 const manifest = {"name":"headless-repository-fixture","skills":["dsh-plugin-assets/skills/0"]}
+// Value mirror: Cordis const enum FiberState.ACTIVE; keep aligned with dsh-repository-plugin source.ts.
 const FIBER_ACTIVE = 2
 export const name = "headless-repository-fixture"
 export const inject = ["loader","skills"]

From 690fc798a516fedaaee8b458619e0ed6f4bdf6d2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 01:14:37 +0800
Subject: [PATCH 194/262] test(repository-plugin): isolate simulated npm
 release

---
 apps/cli/tests/github-repository-plugin.built.e2e.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index e1386e2bfe..139dc8208f 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -182,6 +182,11 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
           DEEPSEEK_API_KEY: apiKey,
           DEEPSEEK_BASE_URL: server.baseURL,
           NPM_CONFIG_USERCONFIG: npmrc,
+          // A warm runner cache could satisfy the exact tarball without
+          // contacting this test's registry, which would stop proving the
+          // unpublished package was installed through the simulated release.
+          PNPM_CONFIG_CACHE_DIR: join(home, 'pnpm-cache'),
+          PNPM_CONFIG_STORE_DIR: join(home, 'pnpm-store'),
           PATH: process.env.PATH === undefined ? hostBin : `${hostBin}${delimiter}${process.env.PATH}`,
         },
       })

From 8d76ddaa6c5f02ce39647f2fb5808d97228b911e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:15:36 +0800
Subject: [PATCH 195/262] fix(repository-plugin): enforce published prepare
 dependency

---
 ...0-config-only-repository-plugins.i18n.yaml |  4 +--
 ...26-07-30-config-only-repository-plugins.md |  4 +--
 ...07-30-config-only-repository-plugins.zh.md |  4 +--
 packages/mcp/mcp-client/tests/apply.spec.ts   |  2 +-
 .../repository-plugin/README.i18n.yaml        |  4 +--
 .../repository-plugin/README.md               |  2 +-
 .../repository-plugin/README.zh.md            |  2 +-
 .../repository-plugin/src/format.ts           |  5 +++
 .../repository-plugin/src/index.ts            |  1 +
 .../repository-plugin/src/source.ts           |  6 +++-
 .../tests/repository-plugin.spec.ts           | 33 +++++++++++++++++++
 11 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index cee151c1ed..74992551f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.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 .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
-2026-07-30-config-only-repository-plugins.md: 1564a847ccef877a6cc91827e195aa04711d09ce
-2026-07-30-config-only-repository-plugins.zh.md: 8e8de1e6edc356c9bb9ab55f01b6cce7608358e7
+2026-07-30-config-only-repository-plugins.md: 35327a30e03c51311f634e05ade209ab93ae0155
+2026-07-30-config-only-repository-plugins.zh.md: e2ef728cadf33f12da0e96a71fd984b694f497b0
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
index 1564a847cc..35327a30e0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
@@ -12,13 +12,13 @@ A standalone `dsh` user has no developer-owned SDK project whose `package.json`,
 
 The shipped TUI and Web/headless `cordis.yml` trees contain an empty `repository-plugins` entry. A user changes only `$DSH_HOME/config.yaml`, replacing that entry's config with a `repositories` list. Each item uses `github:owner/repository#<ref>` plus an optional `&path:/.../.dsh-plugin`; omission selects `/.dsh-plugin`. An explicit ref is mandatory, paths are absolute within the repository and end in `.dsh-plugin`, and duplicate normalized specifiers reject before installation. There is no marketplace, discovery index, HTTPS URL vocabulary, or implicit latest generation.
 
-`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, installs its dependencies, runs its package-authored `prepack` and the host preparation helper, and atomically publishes the exact specifier. The DSH host imports the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber; that wrapper composes static skill and MCP owners plus an explicit trusted Cordis entry when declared.
+`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, installs its dependencies, runs its package-authored `prepack`, and atomically publishes the exact specifier. The selected package's direct development dependency on `@deepseek-ai/dsh-repository-plugin` supplies `dsh-plugin-prepare` through package-local `node_modules/.bin`; the lifecycle invokes it after any package-owned build. The DSH host imports the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber; that wrapper composes static skill and MCP owners plus an explicit trusted Cordis entry when declared.
 
 ## Live update and failure
 
 `dsh-app-boot` mounts the root Include through one helper that retains its exact Loader `Entry`. The TUI and Web register `$DSH_HOME/config.yaml` through Cordis HMR; headless reads the same file at startup without retaining a watcher. A watcher update rebuilds the Include patch list as immutable app-owned patches followed by the newly parsed personal patches, so Web-generated port, session-root, trust, and frontend values survive every personal edit unless a later personal patch deliberately replaces that row.
 
-Cordis serializes and coalesces exact-path changes. Include and Loader reconcile a candidate transactionally: success commits the new source list, while fetch, preparation, wrapper import, format, or child-Plugin failure rejects the candidate and retains or restores the last good tree. HMR normalizes the caught value to `Error`, logs it, and broadcasts the parallel `hmr/config-update-failed(filename, error)` event; observer failures cannot break refresh processing. MCP transport connection failure remains the existing MCP client's contained successful-Plugin/no-tools result and therefore is not reclassified as a config-update failure.
+Cordis serializes and coalesces exact-path changes. Include and Loader reconcile a candidate transactionally: success commits the new source list, while fetch, preparation, wrapper import, format, or child-Plugin failure rejects the candidate and retains or restores the last good tree. HMR normalizes the caught value to `Error`, logs it, and broadcasts the parallel `hmr/config-update-failed(filename, error)` event; observer failures cannot break refresh processing. Repository MCP servers use strict startup, so an initial connection, discovery, or tool-registration failure rejects the candidate and becomes a config-update failure; non-strict standalone MCP clients retain their contained successful-Plugin/no-tools behavior.
 
 An identical specifier permanently reuses its cache generation. HMR watches configuration, not cached repository code; the user changes the ref, path, or source list to select another generation.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 8e8de1e6ed..e2ef728cad 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择已配置的 repository 子包，安装其依赖，运行包所定义的 `prepack` 与宿主准备辅助程序，并原子发布该精确说明符。DSH 宿主会导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber；该包装层组合静态 skill（技能）与 MCP 所有者，并在声明时组合显式的受信任 Cordis 入口。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择已配置的 repository 子包，安装其依赖，运行包所定义的 `prepack`，并原子发布该精确说明符。所选包对 `@deepseek-ai/dsh-repository-plugin` 的直接开发依赖通过包内 `node_modules/.bin` 提供 `dsh-plugin-prepare`；该生命周期会在任何包自有构建完成后调用它。DSH 宿主会导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber；该包装层组合静态 skill（技能）与 MCP 所有者，并在声明时组合显式的受信任 Cordis 入口。
 
 ## 实时更新与失败
 
 `dsh-app-boot` 通过一个辅助函数挂载根 Include，并保留其确切的 Loader `Entry`。TUI 和 Web 通过 Cordis HMR（热模块替换）注册 `$DSH_HOME/config.yaml`；无头界面在启动时读取同一文件，但不保留监视器。监视器更新会重新构建 Include 补丁列表，先放置不可变的应用自有补丁，再放置新解析的个人补丁。因此，Web 生成的端口、会话根目录、信任和前端值会在每次个人编辑后保留，除非后续个人补丁有意替换相应配置项。
 
-Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装模块导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播并行的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。MCP 传输连接失败仍沿用现有 MCP 客户端所收束的「插件成功加载但无工具」结果，因此不会被重新分类为配置更新失败。
+Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装模块导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播并行的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。Repository MCP 服务器采用严格启动，因此初始连接、发现或工具注册失败会拒绝候选配置，并构成配置更新失败；非严格的独立 MCP 客户端仍保留其所收束的「插件成功加载但无工具」行为。
 
 相同说明符会永久复用同一个缓存版本。HMR 监视配置，而非已缓存的仓库代码；用户必须改变 ref、路径或源列表，才能选择另一个版本。
 
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 70c88ad660..44b3e272f4 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -209,7 +209,7 @@ describe('apply (plugin lifecycle)', () => {
     expect(other.tools.get('mcp__srv__remote')).toBeDefined()
   })
 
-  it('logs error and registers no tools when connect fails; dispose is a no-op', async () => {
+  it('logs error and registers no tools when connect fails; dispose closes the client', async () => {
     mockConnect.mockRejectedValue(new Error('connection refused'))
 
     await apply(ctx, stdioConfig)
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 9d7f305263..e083b8abf3 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 0df0680cef873d9f7078cb63d1c803e5c323f07c
-README.zh.md: 04e5f8f81ba1b3e788775e9deaff6bb0b6dd1a48
+README.md: 666f00e02b9ab33bff348df6b4ff90e3f3bfecc7
+README.zh.md: 62f467dd9ccac904ea2a216242f5475c29734a86
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 0df0680cef..666f00e02b 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -60,7 +60,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH's bundled pnpm installs the selected package from its own manifest. A transaction-owned `pnpm` wrapper reinvokes the same pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed; its ordinary `node_modules/.bin` lookup obtains `dsh-plugin-prepare` from the declared `@deepseek-ai/dsh-repository-plugin` dependency. That package marks its Cordis/DSH runtime peers optional so using the executable alone does not install the runtime graph. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to resolve the published helper, install dependencies, build, or prepare fails before a cache generation is published. Rationale: [npm-backed Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
+During exact Git installation, DSH's bundled pnpm installs the selected package from its own manifest. A transaction-owned `pnpm` wrapper reinvokes the same pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed; its ordinary `node_modules/.bin` lookup obtains `dsh-plugin-prepare` from the declared direct development dependency on `@deepseek-ai/dsh-repository-plugin`. That package marks its Cordis/DSH runtime peers optional so using the executable alone does not install the runtime graph. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained both the direct development dependency and a `prepack` declaration containing the helper command. Failure to resolve the published helper, install dependencies, build, or prepare fails before a cache generation is published. Rationale: [npm-backed Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 04e5f8f81b..62f467dd9c 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -60,7 +60,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 随附的 pnpm 会按所选包自身的 manifest 安装。由事务持有的 `pnpm` 包装脚本会以 `--ignore-workspace` 重新调用同一份锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行；其常规 `node_modules/.bin` 查找会从已声明的 `@deepseek-ai/dsh-repository-plugin` 依赖取得 `dsh-plugin-prepare`。该包把 Cordis／DSH 运行时对等依赖（peer dependency）标为可选，因此单独使用该可执行文件不会安装运行时依赖图。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。无法解析已发布的辅助程序，或安装依赖、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[基于 NPM 的 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
+安装精确指定的 Git 源时，DSH 随附的 pnpm 会按所选包自身的 manifest 安装。由事务持有的 `pnpm` 包装脚本会以 `--ignore-workspace` 重新调用同一份锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行；其常规 `node_modules/.bin` 查找会从直接声明的 `@deepseek-ai/dsh-repository-plugin` 开发依赖中取得 `dsh-plugin-prepare`。该包把 Cordis／DSH 运行时对等依赖（peer dependency）标为可选，因此单独使用该可执行文件不会安装运行时依赖图。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍同时保留该直接开发依赖，以及包含该辅助命令的 `prepack` 声明。无法解析已发布的辅助程序，或安装依赖、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[基于 NPM 的 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 743a2fbf39..7af948595d 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -16,6 +16,8 @@ export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
 /** Dependency-provided command that repository package `prepack` lifecycles must invoke. */
 export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
+/** Published package whose direct development dependency supplies the prepare command. */
+export const REPOSITORY_PLUGIN_PACKAGE_NAME = '@deepseek-ai/dsh-repository-plugin'
 
 /**
  * Whether a package lifecycle declaration names the preparation dependency's helper.
@@ -40,6 +42,9 @@ const sourceMetadataSchema = z.object({
 })
 const sourcePackageSchema = z.looseObject({
   name: z.string().min(1),
+  devDependencies: z.looseObject({
+    [REPOSITORY_PLUGIN_PACKAGE_NAME]: z.string().min(1),
+  }),
   scripts: z.looseObject({
     prepack: prepackSchema,
   }),
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index 8026199c16..1251fe45e2 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -29,6 +29,7 @@ export {
   PREPARED_ASSET_DIRECTORY,
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_BUILTIN,
+  REPOSITORY_PLUGIN_PACKAGE_NAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
   prepareDshPlugin,
   type PreparedPluginManifest,
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index 8460bc800b..536025d6d7 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -12,6 +12,7 @@ import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { z } from 'zod'
 import {
   PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_PACKAGE_NAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
   hasRepositoryPrepareCommand,
 } from './format.ts'
@@ -29,6 +30,9 @@ export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
 // resolvable point').
 const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
 const installedPackageSchema = z.looseObject({
+  devDependencies: z.looseObject({
+    [REPOSITORY_PLUGIN_PACKAGE_NAME]: z.string().min(1),
+  }),
   scripts: z.looseObject({
     prepack: z.string().min(1).refine(
       hasRepositoryPrepareCommand,
@@ -81,7 +85,7 @@ async function assertInstalledPackageMetadata(directory: string): Promise<void>
   const result = installedPackageSchema.safeParse(value)
   if (!result.success) {
     throw new Error([
-      `installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:`,
+      `installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}, and declare ${JSON.stringify(REPOSITORY_PLUGIN_PACKAGE_NAME)} in devDependencies:`,
       z.prettifyError(result.error),
       'Clear the matching repository cache generation before retrying the same source, or select a different exact source/ref/path after fixing the package.',
     ].join('\n'))
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 3b8d587dbc..086616f2f9 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -32,12 +32,16 @@ async function writePlugin(
   name: string,
   dsh: Record<string, unknown>,
   prepack = RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  devDependencies: Record<string, string> = {
+    [RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1',
+  },
 ): Promise<string> {
   const directory = join(root, '.dsh-plugin')
   await mkdir(directory, { recursive: true })
   await writeFile(join(directory, 'package.json'), `${JSON.stringify({
     name,
     version: '0.0.0',
+    devDependencies,
     scripts: { prepack },
     dsh,
   }, undefined, 2)}\n`)
@@ -149,6 +153,17 @@ describe('dsh-plugin-prepare', () => {
     )
     await expect(RepositoryPlugin.prepareDshPlugin(skippedPrepare)).rejects.toThrow('must invoke dsh-plugin-prepare')
 
+    const undeclaredPrepareRoot = await temporaryDirectory('undeclared-prepare-dependency')
+    const undeclaredPrepare = await writePlugin(
+      undeclaredPrepareRoot,
+      'undeclared-prepare-dependency',
+      { skills: ['../skills'] },
+      RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND,
+      {},
+    )
+    await expect(RepositoryPlugin.prepareDshPlugin(undeclaredPrepare))
+      .rejects.toThrow(RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME)
+
     const emptyRoot = await temporaryDirectory('empty-metadata')
     const empty = await writePlugin(emptyRoot, 'empty', {})
     await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root, mcpServers file, or compiled entry')
@@ -584,6 +599,7 @@ describe('configured GitHub repository sources', () => {
     const root = await temporaryDirectory('installed-lifecycle')
     await writeFile(join(root, 'package.json'), JSON.stringify({
       name: 'installed-lifecycle',
+      devDependencies: { [RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1' },
       scripts: { prepare: 'dsh-plugin-prepare' },
     }))
     const ctx = new Context()
@@ -606,6 +622,7 @@ describe('configured GitHub repository sources', () => {
     const root = await temporaryDirectory('installed-skipped-prepare')
     await writeFile(join(root, 'package.json'), JSON.stringify({
       name: 'installed-skipped-prepare',
+      devDependencies: { [RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1' },
       scripts: { prepack: 'npm run build' },
     }))
     const ctx = new Context()
@@ -618,6 +635,22 @@ describe('configured GitHub repository sources', () => {
     await ctx.fiber.dispose()
   })
 
+  it('rejects installed source without the declared prepare dependency', async () => {
+    const root = await temporaryDirectory('installed-missing-prepare-dependency')
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'installed-missing-prepare-dependency',
+      scripts: { prepack: 'dsh-plugin-prepare' },
+    }))
+    const ctx = new Context()
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#ambient-helper&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining(`${JSON.stringify(RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME)} in devDependencies`) as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
+
   it('labels missing installed package metadata with its source', async () => {
     const root = await temporaryDirectory('missing-installed-metadata')
     const ctx = new Context()

From fc20194733b1af225567e2342fff84470de077ed Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:22:46 +0800
Subject: [PATCH 196/262] fix(repository-plugin): follow package regrouping

---
 ...-08-npm-backed-git-repository-plugin-preparation.i18n.yaml | 4 ++--
 ...2026-08-08-npm-backed-git-repository-plugin-preparation.md | 2 +-
 ...6-08-08-npm-backed-git-repository-plugin-preparation.zh.md | 2 +-
 apps/cli/tests/github-repository-plugin.built.e2e.ts          | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
index e1966105a3..f13bae898a 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
-2026-08-08-npm-backed-git-repository-plugin-preparation.md: 9437043d007f5331f36f1c4cff1fe0a3e768b060
-2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 1f06f7372dc0d948906ec4441cb161d2d2ed69e5
+2026-08-08-npm-backed-git-repository-plugin-preparation.md: 958b932f82f4da3cf63aa911260411855e514409
+2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 4986c55787f291ba9e0d4594854c15eb3c892c72
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
index 9437043d00..958b932f82 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
@@ -45,4 +45,4 @@ The built-entry acceptance also creates an in-process npm registry. It stages th
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires relative `file:` dependencies to provide both its build command and `dsh-plugin-prepare`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and preparation output. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: simulated published helper package, job-local npm registry, fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
+`packages/boot/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires relative `file:` dependencies to provide both its build command and `dsh-plugin-prepare`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and preparation output. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: simulated published helper package, job-local npm registry, fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
index 1f06f7372d..4986c55787 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
@@ -45,4 +45,4 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
+`packages/boot/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 139dc8208f..7bb4706dd7 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -11,7 +11,7 @@ import { describe, expect, it } from 'vitest'
 
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
-const repositoryPluginPackage = join(repoRoot, 'packages/cordis/repository-plugin')
+const repositoryPluginPackage = join(repoRoot, 'packages/self-modification/repository-plugin')
 const releasePackageNames = new Set(globSync([
   'vendor/*/package.json',
   'packages/*/*/package.json',

From a208bc1a9263291481a1a5719fb583ea02ad354c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:28:31 +0800
Subject: [PATCH 197/262] docs(config-catalog): refresh repository source

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 34ea4a7fbd..0a5d0f7519 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1186,7 +1186,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/self-modification/repository-plugin/src/index.ts:43`](../packages/self-modification/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:44`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 

From c8e0b0f3a7bae107b332617e9b82cb3531f3fd99 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:41:30 +0800
Subject: [PATCH 198/262] test(repository-plugin): update keyless prepare
 fixture

---
 examples/headless-agent/tests/keyless-smoke.e2e.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts
index c737e4ea72..ba75ce9294 100644
--- a/examples/headless-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts
@@ -9,6 +9,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 import {
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  REPOSITORY_PLUGIN_PACKAGE_NAME,
   prepareDshPlugin,
 } from '@deepseek-ai/dsh-repository-plugin'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
@@ -77,6 +78,7 @@ describe('headless-agent keyless smoke', () => {
         name: 'headless-repository-fixture',
         version: '0.0.0',
         scripts: { prepack: REPOSITORY_PLUGIN_PREPARE_COMMAND },
+        devDependencies: { [REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1' },
         dsh: { skills: ['../skills'] },
       }, undefined, 2)}\n`)
       await prepareDshPlugin(plugin)

From 9087be1a2acd6556f7170b810ff0d0fc81f60244 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 12:21:57 +0800
Subject: [PATCH 199/262] fix(docs): address generated translation review
 findings

---
 ...9-human-transcript-append-origin.i18n.yaml |   2 +-
 ...07-29-human-transcript-append-origin.zh.md |  10 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |   2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |   2 +-
 ...30-generated-third-party-notices.i18n.yaml |   2 +-
 ...-07-30-generated-third-party-notices.zh.md |   6 +-
 docs/api-gateway.i18n.yaml                    |   2 +-
 docs/api-gateway.zh.md                        |   2 +-
 docs/config-catalog.i18n.yaml                 |   2 +-
 docs/config-catalog.zh.md                     |   6 +-
 ...sponding-to-pr-review-on-a-stack.i18n.yaml |   2 +-
 .../responding-to-pr-review-on-a-stack.zh.md  |   2 +-
 docs/cordis-api/context.i18n.yaml             |   2 +-
 docs/cordis-api/context.zh.md                 |   4 +-
 docs/cordis-api/fiber.i18n.yaml               |   2 +-
 docs/cordis-api/fiber.zh.md                   |   6 +-
 docs/development.i18n.yaml                    |   2 +-
 docs/development.zh.md                        |   4 +-
 docs/i18n/README.i18n.yaml                    |   4 +-
 docs/i18n/README.md                           |   8 +-
 docs/i18n/README.zh.md                        |   8 +-
 docs/i18n/style-samples.md                    |   4 +-
 docs/module-graph.i18n.yaml                   |   2 +-
 docs/module-graph.zh.md                       | 162 +++++++++---------
 docs/persistence-catalog.i18n.yaml            |   2 +-
 docs/persistence-catalog.zh.md                |   2 +-
 docs/subsystems/README.i18n.yaml              |   2 +-
 docs/subsystems/README.zh.md                  |  16 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   2 +-
 docs/subsystems/llm-streaming.zh.md           |  10 +-
 docs/subsystems/subagent.i18n.yaml            |   2 +-
 docs/subsystems/subagent.md                   |   2 +-
 docs/tool-catalog.i18n.yaml                   |   2 +-
 docs/tool-catalog.zh.md                       |  40 ++---
 .../request-response.expected.json            |   8 +-
 scripts/translation-pairing-merge.spec.ts     |  60 +++++++
 scripts/translation-pairing-merge.ts          |   3 +-
 37 files changed, 230 insertions(+), 169 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index 7bce30803e..9c333a1363 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
 2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: ad952b697a11bd8f2d72785ec013bcf3e973db04
+2026-07-29-human-transcript-append-origin.zh.md: bfe39384f1f5a8badd4c859c89f450177f53ed62
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index ad952b697a..bfe39384f1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 终端从追加来源的 surface 事件回放 transcript，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的 transcript。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
 
-检查点通过压缩seam自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+检查点通过压缩 seam 自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
 `session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
 
@@ -24,17 +24,17 @@ Status: implemented
 
 ## 延后事项
 
-浏览器客户端在[Web transcript 投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份追加来源 transcript并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝这个检查点。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，旧规则会把整段被遮蔽的范围一起拉到该页。
+浏览器客户端在[Web transcript 投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份追加来源 transcript 并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝这个检查点。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，旧规则会把整段被遮蔽的范围一起拉到该页。
 
 终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
 
 ## 考虑过的替代方案
 
-**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。seam已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。seam 已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
 
 **继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
 
-**持久化第二份展示用 transcript。** 被否决：仅追加的日志已经包含权威源材料，平行 transcript换不来任何东西，反而增加迁移与一致性工作。
+**持久化第二份展示用 transcript。** 被否决：仅追加的日志已经包含权威源材料，平行 transcript 换不来任何东西，反而增加迁移与一致性工作。
 
 **用 `compact/*` 括号而不是检查点来推导标记。** 就 transcript 而言被否决：括号是围绕一次操作的一对时间点标记，而 transcript 需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
 
@@ -46,7 +46,7 @@ Status: implemented
 
 `rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换推理（reasoning）时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。
 
-`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` seam的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
+`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` seam 的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
 
 两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（「隐藏被遮蔽的工具调用」），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture（测试前置数据），以显示被保留的提示、完整的工具卡片和那行标记。
 
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 812256d0ae..56ffbc366d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
 2026-07-02-bilingual-docs-and-pairing-gate.md: b462efd99c008a1e8254b6754a408e9e94e787d6
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 409177996d7ffc63a36c865cc00002a33fe538f1
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 564442ce9bd09a448c030e30f34930673a06727b
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 409177996d..564442ce9b 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 
 ## 验证
 
-验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
+验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 907669edb8..004c168fe7 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
 2026-07-30-generated-third-party-notices.md: f2591c8d0c7d4b83ecc96bf237ded667e322d55c
-2026-07-30-generated-third-party-notices.zh.md: eef1e1f46bd9086ad0ccb1cf164330b3bbf601bb
+2026-07-30-generated-third-party-notices.zh.md: 97b62223c0f1e5d179e58f27a01251d8af43357b
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index eef1e1f46b..97b62223c0 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -16,11 +16,11 @@ Status: implemented
 
 **新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
-有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
+有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
 文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
-**分层依据是声明方所在区域，而非manifest 字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一 manifest——即根 manifest、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器通过 `tsx` 执行，根本没有任何 manifest 把它声明为运行时依赖，只能由生成器显式标记。
+**分层依据是声明方所在区域，而非 manifest 字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一 manifest——即根 manifest、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器通过 `tsx` 执行，根本没有任何 manifest 把它声明为运行时依赖，只能由生成器显式标记。
 
 运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。
 
@@ -30,7 +30,7 @@ manifest 集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生
 
 ## Testing
 
-断言新鲜度的同一个 spec 也用fixture（测试前置数据）manifest钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
+断言新鲜度的同一个 spec 也用 fixture（测试前置数据）manifest 钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
 
 Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK manifest，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
 
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index b1f78b85e4..de205997db 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
 api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: f77a3e2675cc8ee6d27a8f6c9cbeb39609a9c282
+api-gateway.zh.md: f9fb6cff368bb4c7b75240452e2853c6f24da096
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index f77a3e2675..f9fb6cff36 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -159,7 +159,7 @@ pnpm run dev:web
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定产物，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净的 worktree不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定产物，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净的 worktree 不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index bff77bc092..b976d35268 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
 config-catalog.md: eb4472d629e41f154384549245ecce1c8ec266e2
-config-catalog.zh.md: 42c1f6e85c416c68f18b8b2976300dec7e32dbc4
+config-catalog.zh.md: b29c64d9f4382628633639ff338ceb9bc56590ed
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 42c1f6e85c..b29c64d9f4 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -5,7 +5,7 @@
 
 [English](config-catalog.md) | 中文
 
-`cordis.yml` 条目可以设置的每个 `config:` 块：针对每个可加载的运行框架包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.md)，而 [subsystems/](subsystems/core.md) 则记录了这些声明所引用的类型。
+每个 `config:` 块均可由 `cordis.yml` 条目设置：针对每个可加载的运行框架包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.md)，而 [subsystems/](subsystems/core.md) 则记录了这些声明所引用的类型。
 
 英文源文件由源代码（`scripts/gen-config-catalog.ts`）生成，并通过 `pnpm run verify-config-catalog`（`doc-sync` 的一部分）验证为最新；本中文文件作为经评审对侧通过双语配对维护。声明块使用 `ts config-catalog` 围栏（doc-typecheck 会跳过它，因为单独引用导入项的声明无法独立编译）。英文生成器还会将运行时 schemastery schema 与粘贴的声明进行交叉核对——每个经 schema 验证的键（包括嵌套键）都必须能在声明的配置类型中找到——因此，粘贴内容无法隐藏加载器接受的字段。
 
@@ -641,7 +641,7 @@ export interface JsonRpcConfig {
 
 依赖：`Readable`（`node:stream`）· `Writable`（`node:stream`）
 
-来源：[`packages/scaffold/server/src/index.ts:25`](../packages/scaffold/server/src/index.ts)
+来源：[`packages/scaffold/server/src/index.ts:29`](../packages/scaffold/server/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-deepseek`
 
@@ -2572,7 +2572,7 @@ export interface Config {
 
 ## 无配置的可加载插件
 
-这些插件通过不含 `config:` 块的 `cordis.yml` 条目加载；它们未声明任何配置接口。
+这些插件通过 `cordis.yml` 中不含 `config:` 块的条目加载；它们未声明任何配置接口。
 
 - `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)）
 - `@deepseek-ai/dsh-api-gateway` — 需要 `typert`（[`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts)）
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
index 7757b8419d..7e481af0bc 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/responding-to-pr-review-on-a-stack.md
 responding-to-pr-review-on-a-stack.md: 6bb7be3daf8613666f02f21e96bf7b1ac8cb3606
-responding-to-pr-review-on-a-stack.zh.md: 7567220096bb9dd6f3f68c16c08493ffb7529de7
+responding-to-pr-review-on-a-stack.zh.md: cd4984a09a8bdc1ab38fe2bbe54e669bff18230f
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
index 7567220096..cd4984a09a 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
@@ -19,7 +19,7 @@
 3. 将修复后的层按顺序传播到每个受影响的子 PR：
    - **Merge-forward：** 将修复后的父分支合并到其子分支，验证子分支，然后继续沿堆叠向上传播。依照[增量更新 base 的决策](../../.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)，保留每个正在处理的检查点。
    - **原生级联 rebase：** 使用 `gh stack rebase`，验证所有已改写的层，然后通过 `gh stack push` 发布；也可以使用 `gh stack sync`，该命令可能先发布，因此必须按照 [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md) 在同步后立即验证。
-4. 委派的修复需要信任但验证：subagent的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
+4. 委派的修复需要信任但验证：subagent 的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
 5. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及当前承载修复的 commit 或 head。
 6. 每次改写推送后，都要重新读取未解决线程、批准状态、可合并性和检查结果。经 force-push 改写的 commit OID 或已过时的内联锚点，都不足以证明该发现当前仍处于已解决状态。
 7. 仅可通过官方堆叠流程落地。如果这些 PR 尚未关联，落地 skill 会自动关联作者相同的链；如果作者不同，则先询问用户；如果原生堆叠支持不可用，则硬性停止流程。
diff --git a/docs/cordis-api/context.i18n.yaml b/docs/cordis-api/context.i18n.yaml
index 618b112792..884e233721 100644
--- a/docs/cordis-api/context.i18n.yaml
+++ b/docs/cordis-api/context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/context.md
 context.md: 320b23de1c8d19e2dacdf0ec9f2361037bcf8048
-context.zh.md: 2e4cdc1d2822d6cc19bf1907a44cc31c429016ea
+context.zh.md: 9b1f92a329ff4d75b3fafe7bf6bc8db317bcc267
diff --git a/docs/cordis-api/context.zh.md b/docs/cordis-api/context.zh.md
index 2e4cdc1d28..9b1f92a329 100644
--- a/docs/cordis-api/context.zh.md
+++ b/docs/cordis-api/context.zh.md
@@ -58,7 +58,7 @@ isolate(name: string, label?: symbol)
 
 创建一个子上下文，使 `name` 拥有独立的服务作用域。
 
-在返回的上下文之下，对服务 `name` 的读写会根据新标签解析，而不再根据父上下文的标签解析，因此可以提供不同的实现而不影响父作用域。向两次 `isolate()` 调用传入相同的 `label`，可使二者加入同一作用域。
+在返回的上下文之下，对服务 `name` 的读写会根据新标签解析，而不再根据父上下文的标签解析，因此可以提供不同的实现而不影响父作用域。将同一个 `label` 传给两次 `isolate()` 调用，可使二者加入同一作用域。
 
 - `name`：要隔离的服务名称。
 - `label`：要加入的作用域标签；默认为一个新建的唯一 symbol。
@@ -230,7 +230,7 @@ static is(value: any): value is Context
 
 - `value`：要测试的值。
 
-如果 `value` 是 Cordis 上下文，**返回** `true`，并收窄其类型。
+如果返回 `true`，则 `value` 是 Cordis 上下文，并会收窄其类型。
 
 [源码](../../vendor/cordis/src/context.ts#L61)
 
diff --git a/docs/cordis-api/fiber.i18n.yaml b/docs/cordis-api/fiber.i18n.yaml
index 0c45c03f5f..6c01366dc1 100644
--- a/docs/cordis-api/fiber.i18n.yaml
+++ b/docs/cordis-api/fiber.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md
 fiber.md: 36d2861ac6a53e8186a92d86c65ba228d4b59ee5
-fiber.zh.md: 8fbc10c9870106f3fc7dfabe9725581898d9ef22
+fiber.zh.md: fafa559ca911677c43893862190009d82c39c56b
diff --git a/docs/cordis-api/fiber.zh.md b/docs/cordis-api/fiber.zh.md
index 8fbc10c987..fafa559ca9 100644
--- a/docs/cordis-api/fiber.zh.md
+++ b/docs/cordis-api/fiber.zh.md
@@ -29,7 +29,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 
 在此 fiber 上注册一个支持清理的作用。
 
-`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
 
 - `execute`：作用主体；可接受的结构见 `Effect`。
 - `label`：在 `getEffects()` 诊断信息中显示的作用标签。
@@ -130,7 +130,7 @@ public store: Dict<Impl> | undefined
 public inertia: Promise<void> | undefined
 ```
 
-当前正在进行的加载或卸载转换；如果没有此类转换，则为 `undefined`。
+当前正在进行的加载或卸载转换；如果没有此类转换，则为 undefined。
 
 [源码](../../vendor/cordis/src/fiber.ts#L198)
 
@@ -185,7 +185,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 
 在此 fiber 上注册一个支持清理的作用。
 
-`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
 
 - `execute`：作用主体；可接受的结构见 `Effect`。
 - `label`：在 `getEffects()` 诊断信息中显示的作用标签。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index d6d5d3dcc3..d2ea5f9122 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
 development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 60a4660f5d6be48fd4d0d8f30777ae37495d6296
+development.zh.md: 073810cb7e1042c43388b2299c2a1cb550fc0523
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 60a4660f5d..073810cb7e 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -21,7 +21,7 @@
 pnpm install
 ```
 
-安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
+安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
 
 如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：
 
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git 集成
 
-当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
+当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。
 
 安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index c10cab36cb..8a8eb256fb 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: b6190e7dd84ae5f159fd452f093bf37f24edfda9
-README.zh.md: f1c808442efe3ca7da87c30ba22d3560bcf125e9
+README.md: 17d09eadd6d4eeb61d5f7ced188991f175070f98
+README.zh.md: 5e623777e1ca09295a7c690bfbb8760385527c98
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index b6190e7dd8..17d09eadd6 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -17,8 +17,8 @@ This repo's documentation is read by people and agents both inside and outside t
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).
 
-  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
-- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
+  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
+- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[English](foo.md) | 中文`. An authored English file reciprocates there with `English | [中文](foo.zh.md)`; a listed generated English source omits that line so it remains byte-identical to generator output.
 - **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
 ## The gate: verify-translation-pairing
@@ -26,7 +26,7 @@ This repo's documentation is read by people and agents both inside and outside t
 `pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:
 
 1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.
-2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.
+2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), the Chinese side and every authored English source carry their language switchers (listed generated English sources are exempt), and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.
 3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.
 
 Source-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.
@@ -57,4 +57,4 @@ Generated English references and graphs participate in pairing when a reviewed C
 
 ## Division of labor
 
-Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.
+Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, the Chinese backlink and authored-source switcher (with the documented generated-source exception), and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index f1c808442e..5e623777e1 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -17,8 +17,8 @@
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。
 
-  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
-- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
+  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留必需的语言切换行和结构签名时，组合出一份新记录。中文文件必须保留指向英文的反向链接；普通撰写的英文源必须保留指向中文的链接，而清单内的生成英文源不作此要求。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
+- **语言切换行。** 中文文件一律在 H1 标题后立即以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在同一位置以 `English | [中文](foo.zh.md)` 互链；清单内的生成英文源省略此行，以便与生成器输出逐字节一致。
 - **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
 ## 门禁：verify-translation-pairing
@@ -26,7 +26,7 @@
 `pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：
 
 1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。
-2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
+2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、中文侧和所有普通撰写的英文源都带语言切换行（清单内的生成英文源除外）、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。
 
 面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。
@@ -57,4 +57,4 @@
 
 ## 分工
 
-这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
+这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、中文反向链接和普通撰写源的切换行（生成源按本文规则例外），以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 432c95e684..6860b91549 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -16,7 +16,7 @@
 
 > This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the generated regions of [subsystems/](../subsystems/core.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包的对外约定写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
@@ -60,7 +60,7 @@
 
 > The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
 
-门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分契约要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
+门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分约定要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
 
 ## ⑥ Agent Note 论证
 
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 212b107093..a0ba36d097 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
 module-graph.md: 6f47c36e970009838e1ab921f4abe013eaeded5f
-module-graph.zh.md: 5da7bc962e1c38e3febfbca59e6bb11b014ecc7f
+module-graph.zh.md: 644305dbde58f5c35ec57fb9c313dcb78fae9938
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 5da7bc962e..644305dbde 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -1207,8 +1207,8 @@ flowchart TD
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`helper`](../packages/scaffold/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
-| [`telemetry`](../packages/scaffold/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`helper`](../packages/scaffold/helper) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`telemetry`](../packages/scaffold/telemetry) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
@@ -1240,18 +1240,18 @@ flowchart TD
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`session-persistence`](../packages/support/acp-snapshot) | `session-persistence` | [`brand`](../packages/support/invariants), [`invariants`](../packages/core/session), [`session`](../packages/boot/app-boot), [`timeout`](../packages/util/environment) |
-| [`acp-snapshot`](../packages/support/invariants) | `support` | [`invariants`](../packages/util/paths), [`session`](../packages/core/system-prompt) |
-| [`app-boot`](../packages/client/ui-question) | `ui` | [`environment`](../packages/client/locale), [`invariants`](../packages/support/invariants), [`paths`](../packages/client/ui-settings-general), [`system-prompt`](../packages/client/connection) |
-| [`client-ui-question`](../packages/client/locale) | `client` | [`client-locale`](../packages/client/runtime), [`invariants`](../packages/client/ui-primitives) |
-| [`client-ui-settings-general`](../packages/client/ui-settings) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/web-react), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-sidebar), [`client-ui-settings`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-web-react`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-sidebar`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-slash`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-theme), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-theme`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-workspace), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-workspace`](../packages/support/invariants) | `client` | [`client-locale`](../packages/code-runtime/code-runtime-worker), [`client-runtime`](../packages/code-runtime/code-runtime), [`client-ui-primitives`](../packages/support/invariants), [`client-ui-slots`](../packages/core/session), [`invariants`](../packages/util/timeout) |
-| [`code-runtime-worker`](../packages/sandbox/sandbox-local) | `code-runtime` | [`code-runtime`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`session`](../packages/sandbox/sandbox), [`timeout`](../packages/session/session-persistence) |
-| [`sandbox-local`](../packages/util/brand) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/core/session), [`sandbox`](../packages/util/timeout) |
-| [`session-projection`](../packages/session/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`app-boot`](../packages/boot/app-boot) | `boot` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
@@ -1263,28 +1263,28 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`session-persistence-jsonl`](../packages/support/llm-replay) | `session-persistence` | [`invariants`](../packages/compact/compact), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm) |
-| [`session-persistence-sqlite`](../packages/core/session) | `session-persistence` | [`invariants`](../packages/support/loader-smoke), [`session`](../packages/core/agent), [`session-persistence`](../packages/support/invariants) |
-| [`session-title`](../packages/llm/llm) | `session-title` | [`brand`](../packages/core/session), [`invariants`](../packages/bundle/headless), [`llm`](../packages/core/agent), [`session`](../packages/host/apiproxy), [`session-projection`](../packages/host/webserver) |
-| [`llm-replay`](../packages/support/invariants) | `support` | [`compact`](../packages/core/session), [`invariants`](../packages/client/ui-layout), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-slots) |
-| [`loader-smoke`](../packages/client/ui-theme) | `support` | [`agent`](../packages/support/invariants), [`invariants`](../packages/context/time-context), [`llm`](../packages/core/agent), [`session`](../packages/support/invariants) |
-| [`commands`](../packages/core/session) | `ui` | [`agent`](../packages/context/tmux-context), [`brand`](../packages/core/agent), [`invariants`](../packages/bash/bash), [`scope`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`user-approval`](../packages/e2b/fs-e2b) | `ui` | [`agent`](../packages/e2b/e2b), [`brand`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-browse), [`scope`](../packages/client/locale), [`session`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-primitives) |
-| [`user-interaction`](../packages/client/ui-slots) | `ui` | [`agent`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-native) |
-| [`headless`](../packages/client/runtime) | `bundle` | [`agent`](../packages/client/ui-slots), [`host-apiproxy`](../packages/client/ui-workspace), [`host-webserver`](../packages/support/invariants), [`invariants`](../packages/interaction/commands), [`session`](../packages/core/agent) |
-| [`client-ui-layout`](../packages/util/brand) | `client` | [`client-runtime`](../packages/support/invariants), [`client-ui-slots`](../packages/core/scope), [`client-ui-theme`](../packages/core/session), [`invariants`](../packages/interaction/user-approval) |
-| [`time-context`](../packages/core/agent) | `context` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/llm/llm) |
-| [`tmux-context`](../packages/core/scope) | `context` | [`agent`](../packages/core/session), [`bash`](../packages/core/system-prompt), [`invariants`](../packages/interaction/user-interaction), [`session`](../packages/core/agent) |
-| [`fs-e2b`](../packages/support/invariants) | `e2b` | [`e2b`](../packages/llm/llm), [`fs`](../packages/lsp/lsp-local), [`invariants`](../packages/util/brand) |
-| [`host-directory-picker-browse`](../packages/fs/fs) | `host` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/llm/llm), [`client-ui-primitives`](../packages/lsp/lsp), [`client-ui-slots`](../packages/subprocess/subprocess), [`client-ui-workspace`](../packages/util/timeout), [`invariants`](../packages/pty/pty) |
-| [`host-directory-picker-native`](../packages/core/agent) | `host` | [`client-runtime`](../packages/util/brand), [`client-ui-slots`](../packages/support/invariants), [`client-ui-workspace`](../packages/sandbox/sandbox-policy), [`invariants`](../packages/core/agent) |
-| [`lsp-local`](../packages/support/invariants) | `lsp` | [`brand`](../packages/sandbox/sandbox), [`fs`](../packages/core/session), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/scaffold/scripts), [`lsp`](../packages/boot/app-boot), [`subprocess`](../packages/support/invariants), [`timeout`](../packages/session/session-persistence-jsonl) |
-| [`pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/core/session), [`brand`](../packages/session/session-persistence), [`invariants`](../packages/session/session-persistence-sqlite) |
-| [`sandbox-policy`](../packages/support/invariants) | `sandbox` | [`agent`](../packages/core/session), [`invariants`](../packages/session/session-persistence), [`sandbox`](../packages/session/session-projection-cache), [`session`](../packages/support/invariants), [`system-prompt`](../packages/core/session) |
-| [`scripts`](../packages/session/session-persistence) | `sdk` | [`app-boot`](../packages/session/session-projection), [`invariants`](../packages/storage/storage-domain) |
-| [`session-projection-cache`](../packages/session/session-telemetry) | `session-projection` | [`invariants`](../packages/core/agent), [`session`](../packages/support/invariants), [`session-persistence`](../packages/core/session), [`session-projection`](../packages/session/session-title), [`storage-domain`](../packages/util/brand) |
-| [`tasks`](../packages/support/invariants) | `tasks` | [`agent`](../packages/llm/llm), [`brand`](../packages/core/session), [`invariants`](../packages/session/session-projection), [`session`](../packages/tasks/tasks) |
-| [`session-telemetry`](../packages/core/agent) | `telemetry` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
+| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
+| [`user-approval`](../packages/interaction/user-approval) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`user-interaction`](../packages/interaction/user-interaction) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`scripts`](../packages/scaffold/scripts) | `scaffold` | [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants) |
+| [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
+| [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-title`](../packages/session/session-title) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
 | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
@@ -1295,14 +1295,14 @@ flowchart TD
 | [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
-| [`session-title-llm`](../packages/acp/acp) | `session-title` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`session`](../packages/core/session), [`session-title`](../packages/interaction/user-approval), [`timeout`](../packages/api/remotes) |
-| [`acp`](../packages/core/agent) | `acp` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/session/session-persistence) |
-| [`permission`](../packages/typert/registry) | `ui` | [`bash`](../packages/client/ui-conversation), [`commands`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`sandbox`](../packages/client/ui-primitives), [`sandbox-policy`](../packages/client/ui-slash), [`session`](../packages/client/ui-slots), [`session-projection`](../packages/support/invariants), [`settings`](../packages/llm/token-meter), [`user-approval`](../packages/feedback/command-feedback) |
-| [`api-remotes`](../packages/interaction/commands) | `api` | [`agent`](../packages/support/invariants), [`goal`](../packages/core/session), [`invariants`](../packages/host/directory-picker-auto), [`session`](../packages/host/directory-picker-browse), [`session-persistence`](../packages/host/directory-picker-native), [`typert-registry`](../packages/host/webserver) |
-| [`client-ui-conversation`](../packages/support/invariants) | `client` | [`client-locale`](../packages/interaction/permission), [`client-runtime`](../packages/bash/bash), [`client-ui-primitives`](../packages/interaction/commands), [`client-ui-slash`](../packages/support/invariants), [`client-ui-slots`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy), [`token-meter`](../packages/core/session) |
-| [`command-feedback`](../packages/session/session-projection) | `feedback` | [`commands`](../packages/settings/settings), [`invariants`](../packages/interaction/user-approval), [`session`](../packages/pty/pty-local) |
-| [`host-directory-picker-auto`](../packages/core/agent) | `host` | [`host-directory-picker-browse`](../packages/support/invariants), [`host-directory-picker-native`](../packages/pty/pty), [`host-webserver`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy) |
-| [`pty-local`](../packages/core/session) | `pty` | [`agent`](../packages/subprocess/subprocess), [`invariants`](../packages/session/session-title-llm), [`pty`](../packages/support/invariants), [`sandbox`](../packages/llm/llm), [`sandbox-policy`](../packages/core/session), [`session`](../packages/session/session-title), [`subprocess`](../packages/util/timeout) |
+| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
+| [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
+| [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1315,31 +1315,31 @@ flowchart TD
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
-| [`timeout-policy`](../packages/todo/tool-todo) | `timeout` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`timeout`](../packages/core/session), [`tools`](../packages/session/session-projection) |
-| [`tool-todo`](../packages/core/tools) | `todo` | [`agent`](../packages/plan/plan-mode), [`invariants`](../packages/core/agent), [`session`](../packages/interaction/commands), [`session-projection`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
-| [`plan-mode`](../packages/core/session) | `plan` | [`agent`](../packages/session/session-projection), [`commands`](../packages/core/system-prompt), [`invariants`](../packages/core/tools), [`llm`](../packages/interaction/user-interaction), [`session`](../packages/hooks/hooks-codex), [`session-projection`](../packages/core/agent), [`system-prompt`](../packages/hooks/hook-protocol), [`tools`](../packages/support/invariants), [`user-interaction`](../packages/llm/llm) |
-| [`tool-cordis`](../packages/core/session) | `cordis` | [`invariants`](../packages/session/session-persistence), [`scope`](../packages/core/tools), [`tools`](../packages/session-query/session-query-sqlite) |
-| [`hooks-codex`](../packages/support/invariants) | `hooks` | [`agent`](../packages/core/session), [`hook-protocol`](../packages/session/session-persistence), [`invariants`](../packages/session-query/session-query), [`llm`](../packages/session-query/tool-session-query), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm), [`tools`](../packages/core/session) |
-| [`session-checkpoint-policy`](../packages/session-query/session-query) | `session-persistence` | [`agent`](../packages/core/system-prompt), [`invariants`](../packages/util/timeout), [`llm`](../packages/core/tools), [`session`](../packages/support/agent-loop-testkit), [`session-persistence`](../packages/core/agent), [`tools`](../packages/support/invariants) |
-| [`session-query-sqlite`](../packages/llm/llm) | `session-query` | [`invariants`](../packages/core/session), [`session`](../packages/core/system-prompt), [`session-persistence`](../packages/core/tools), [`session-query`](../packages/client/ui-command) |
-| [`tool-session-query`](../packages/client/connection) | `session-query` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-query`](../packages/client/ui-primitives), [`system-prompt`](../packages/client/ui-slash), [`timeout`](../packages/client/ui-slots), [`tools`](../packages/support/invariants) |
-| [`session-title-all-messages-llm`](../packages/client/ui-deliverables) | `session-title` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-title`](../packages/client/ui-slots), [`session-title-llm`](../packages/support/invariants) |
-| [`session-title-first-message-llm`](../packages/client/ui-goal) | `session-title` | [`invariants`](../packages/api/remotes), [`llm`](../packages/client/locale), [`session`](../packages/client/runtime), [`session-title`](../packages/client/ui-conversation), [`session-title-llm`](../packages/client/ui-primitives) |
-| [`agent-loop-testkit`](../packages/client/ui-slots) | `support` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/client/ui-tool), [`session`](../packages/client/locale), [`system-prompt`](../packages/client/runtime), [`tools`](../packages/client/ui-conversation) |
-| [`tool-ask-user`](../packages/client/ui-primitives) | `ui` | [`agent`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`tools`](../packages/context/session-reference), [`user-interaction`](../packages/core/agent) |
-| [`client-ui-command`](../packages/compact/compact) | `client` | [`client-connection`](../packages/support/invariants), [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/retention), [`client-ui-conversation`](../packages/core/session), [`client-ui-primitives`](../packages/session-query/session-query), [`client-ui-slash`](../packages/context/workspace-context), [`client-ui-slots`](../packages/core/agent), [`invariants`](../packages/fs/fs) |
-| [`client-ui-deliverables`](../packages/support/invariants) | `client` | [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/paths), [`client-ui-conversation`](../packages/core/session), [`client-ui-slots`](../packages/core/tools), [`invariants`](../packages/guard/repeat-tool-guard) |
-| [`client-ui-goal`](../packages/core/agent) | `client` | [`api-remotes`](../packages/support/invariants), [`client-locale`](../packages/core/tools), [`client-runtime`](../packages/guard/timeout-policy), [`client-ui-conversation`](../packages/support/invariants), [`client-ui-primitives`](../packages/llm/llm), [`client-ui-slots`](../packages/util/timeout), [`goal`](../packages/core/tools), [`invariants`](../packages/interaction/tool-ask-user) |
-| [`client-ui-tool`](../packages/core/agent) | `client` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/core/tools), [`client-ui-conversation`](../packages/interaction/user-interaction), [`client-ui-primitives`](../packages/lsp/tool-lsp), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm) |
-| [`session-reference`](../packages/lsp/lsp) | `context` | [`agent`](../packages/core/system-prompt), [`compact`](../packages/util/timeout), [`invariants`](../packages/core/tools), [`llm`](../packages/mcp/mcp-client), [`retention`](../packages/support/invariants), [`session`](../packages/llm/llm), [`session-query`](../packages/subprocess/subprocess) |
-| [`workspace-context`](../packages/core/tools) | `context` | [`agent`](../packages/pty/tool-bash-persistent), [`fs`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/pty/pty), [`paths`](../packages/util/timeout), [`session`](../packages/core/tools), [`tools`](../packages/pty/tool-pty) |
-| [`repeat-tool-guard`](../packages/core/agent) | `guard` | [`agent`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`tools`](../packages/pty/pty) |
-| [`tool-lsp`](../packages/util/retention) | `lsp` | [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks), [`lsp`](../packages/core/tools), [`system-prompt`](../packages/self-modification/tool-cordis), [`timeout`](../packages/support/invariants), [`tools`](../packages/core/scope) |
-| [`mcp-client`](../packages/core/tools) | `mcp` | [`invariants`](../packages/session/session-checkpoint-policy), [`llm`](../packages/core/agent), [`subprocess`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
-| [`tool-bash-persistent`](../packages/core/session) | `pty` | [`agent`](../packages/session/session-persistence), [`invariants`](../packages/core/tools), [`pty`](../packages/session/session-telemetry-otel), [`timeout`](../packages/util/brand), [`tools`](../packages/feedback/command-feedback) |
-| [`tool-pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/llm/llm), [`invariants`](../packages/util/paths), [`llm`](../packages/core/session), [`pty`](../packages/session/session-telemetry), [`retention`](../packages/session/session-title-all-messages-llm), [`system-prompt`](../packages/support/invariants), [`tasks`](../packages/llm/llm), [`tools`](../packages/core/session) |
-| [`tool-tasks`](../packages/session/session-title) | `tasks` | [`agent`](../packages/session/session-title-llm), [`invariants`](../packages/session/session-title-first-message-llm), [`llm`](../packages/support/invariants), [`retention`](../packages/llm/llm), [`system-prompt`](../packages/core/session), [`tasks`](../packages/session/session-title), [`tools`](../packages/session/session-title-llm) |
-| [`session-telemetry-otel`](../packages/tasks/tool-tasks) | `telemetry` | [`brand`](../packages/core/agent), [`command-feedback`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`llm`](../packages/util/retention), [`paths`](../packages/core/system-prompt), [`session`](../packages/tasks/tasks), [`session-telemetry`](../packages/core/tools) |
+| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
+| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
+| [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
+| [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
+| [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
+| [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/self-modification/tool-cordis) | `self-modification` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
+| [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
+| [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
+| [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
@@ -1349,22 +1349,22 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`repository-plugin`](../packages/hooks/hooks-claude) | `cordis` | [`invariants`](../packages/core/agent), [`mcp-client`](../packages/hooks/hook-protocol), [`paths`](../packages/support/invariants), [`skill-local`](../packages/llm/llm) |
-| [`hooks-claude`](../packages/core/session) | `hooks` | [`agent`](../packages/session/session-persistence), [`hook-protocol`](../packages/subagent/subagent), [`invariants`](../packages/core/tools), [`llm`](../packages/bundle/web-app), [`session`](../packages/bash/bash-env), [`session-persistence`](../packages/support/invariants), [`subagent`](../packages/core/system-prompt), [`tools`](../packages/client/ui-model) |
-| [`web-app`](../packages/client/connection) | `bundle` | [`bash-env`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-command) |
-| [`client-ui-model`](../packages/client/ui-conversation) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-ui-command`](../packages/support/invariants), [`client-ui-conversation`](../packages/client/ui-permission), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`invariants`](../packages/client/schema-form) |
-| [`client-ui-permission`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-schema-form`](../packages/support/invariants), [`client-ui-command`](../packages/interaction/permission), [`client-ui-primitives`](../packages/client/ui-plan), [`client-ui-slash`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`permission`](../packages/client/ui-conversation) |
-| [`client-ui-plan`](../packages/client/ui-primitives) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/plan/plan-mode), [`client-ui-conversation`](../packages/client/ui-skill), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`plan-mode`](../packages/client/ui-primitives) |
-| [`client-ui-skill`](../packages/client/ui-slash) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/ui-tool), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-subagent), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-ui-tool`](../packages/client/ui-conversation), [`invariants`](../packages/client/ui-primitives) |
-| [`client-ui-subagent`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/ui-slots), [`client-runtime`](../packages/support/invariants), [`client-ui-conversation`](../packages/subagent/subagent), [`client-ui-primitives`](../packages/llm/token-meter), [`client-ui-slash`](../packages/scaffold/protocol), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`subagent`](../packages/core/session), [`token-meter`](../packages/subagent/subagent) |
-| [`sdk-protocol`](../packages/self-modification/repository-plugin) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/mcp/mcp-client), [`session`](../packages/util/paths), [`subagent`](../packages/skill/skill-local) |
+| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`jsonrpc`](../packages/examples/agent-spine-demo) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/core/agent-loop), [`llm`](../packages/bash/bash-env), [`llm-deepseek`](../packages/goal/goal), [`scope`](../packages/goal/goal-session), [`sdk-protocol`](../packages/support/invariants), [`session`](../packages/llm/llm), [`subagent`](../packages/llm/llm-retry) |
-| [`agent-spine-demo`](../packages/util/paths) | `examples` | [`agent`](../packages/core/scope), [`agent-loop`](../packages/core/session), [`bash-env`](../packages/session/session-title), [`goal`](../packages/skill/skill), [`goal-session`](../packages/skill/skill-local), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks-local), [`llm-retry`](../packages/bash/tool-bash), [`paths`](../packages/goal/tool-goal), [`scope`](../packages/skill/tool-skill), [`session`](../packages/tasks/tool-tasks), [`session-title`](../packages/core/tools), [`skill`](../packages/context/workspace-context), [`skill-local`](../packages/scaffold/server), [`system-prompt`](../packages/core/agent), [`tasks-local`](../packages/support/invariants), [`tool-bash`](../packages/llm/llm), [`tool-goal`](../packages/llm/llm-deepseek), [`tool-skill`](../packages/core/scope), [`tool-tasks`](../packages/scaffold/protocol), [`tools`](../packages/core/session), [`workspace-context`](../packages/subagent/subagent) |
-| [`sdk-client`](../packages/scaffold/client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 49f2c2a45e..c15a931612 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-catalog.md
 persistence-catalog.md: 04c3a492fe837f7acc102901a289bf74f0cecf3f
-persistence-catalog.zh.md: 3f75cb55e2771b27e494aca9ea81ffeba3e69064
+persistence-catalog.zh.md: 5e2b62d71a5dea93ede0f1a5b16dc528dca197a7
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 3f75cb55e2..5e2b62d71a 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -7,7 +7,7 @@
 
 会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
 
-英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（`doc-typecheck` 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
+英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（doc-typecheck 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
 
 以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。
 
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index f1636e0191..b741c1cdf8 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
 README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
-README.zh.md: dda61d86c4d00117af851b4a55d16b97c6bc2f10
+README.zh.md: 04e07cc9c8b8b16c69bb09344e8533729525fe5c
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index dda61d86c4..04e07cc9c8 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,8 +6,8 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截契约，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
-| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截约定，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
 | [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
@@ -18,15 +18,15 @@
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方约定 |
 | [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
 | [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
-| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
+| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 约定 |
 | [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
 | [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
-| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
+| [pty.md](pty.md) | 持久化终端 ID、后端/会话约定、发送就绪状态、有界读取与 owner 可见快照 |
 | [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
 | [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
 | [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
@@ -37,15 +37,15 @@
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
-| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 契约、consumer 视图、`ctx.tasks` 服务行为 |
+| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 约定、consumer 视图、`ctx.tasks` 服务行为 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 0945fee0a3..946aca73b0 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: 1705c45697df98b51ba9f69c8c91b3a8a18dea76
-llm-streaming.zh.md: 591326582c96023df5a184e19e3e4fc812187fb4
+llm-streaming.zh.md: b47ae516e39cb6657ce5b6ada69d524d5f5ea174
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 591326582c..b47ae516e3 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -2,7 +2,7 @@
 
 [English](llm-streaming.md) | 中文
 
-[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
+[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器约定（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
 
 源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
@@ -202,7 +202,7 @@ interface LlmFailure {
 }
 ```
 
-## 适配器契约
+## 适配器约定
 
 每个适配器必须遵守以下规则，每个消费方可以依赖它们：
 
@@ -216,7 +216,7 @@ interface LlmFailure {
 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
 
-该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
+该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
 ## `ResolvedRetryPolicy`
 
@@ -224,7 +224,7 @@ interface LlmFailure {
 
 ## `AppIdentity`：应用归属
 
-每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该约定有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
 ```ts type-equiv
 /**
@@ -504,7 +504,7 @@ interface GenerateOptions {
 }
 ```
 
-模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](#llmfailure)：
+模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式约定的 [`LlmFailure`](#llmfailure)：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index f080915228..445596fe69 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
+subagent.md: a934c84835334cd6d31c79c4d52b4fb5ebfd722d
 subagent.zh.md: 65ea762fcddb0f7b4ef5ec977cc14f13c8bf4589
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 3bf3ac7c48..a934c84835 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -135,7 +135,7 @@ persisted Session
 
 `running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine.
 
-The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/enqueue`, `agent/inbox/dequeue`, and `agent/inbox/discard` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
+The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/inserted`, `agent/inbox/claimed`, and `agent/inbox/discarded` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
 
 Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` are durable provenance after admission and grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 8eecc6cc4a..9e530c0668 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/tool-catalog.md
 tool-catalog.md: 8986847d1ed2fe9d64ada0c71f34700ff95fb364
-tool-catalog.zh.md: ed78883f74a7d245de97bc45d7125e6245e140ce
+tool-catalog.zh.md: 831ed5d5cdcc15f32d2a4c8673858935fca1e435
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index ed78883f74..831ed5d5cd 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -17,26 +17,26 @@
 
 | 工具包 | 模型可见名称 | 依赖 | 写入／影响 | 随产品发布的别名 | 部署说明 |
 | --- | --- | --- | --- | --- | --- |
-| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userInteraction` | `tool/call`、`UI/provider 回答问题后的 tool/result` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 |
-| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`每个桥接子调用对应的一组 tool/code-dispatch-start + tool/code-dispatch`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
-| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`获批评审后的 plan/mode inactive`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
-| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
+| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userInteraction` | `tool/call`、`tool/result after a UI/provider answers the question` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 |
+| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
+| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
+| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
-| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`进程本地临时 Plugin 生命周期` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
+| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
-| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`变更对应的 fs/write-intent 或 fs/edit-intent`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after successful file operations`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after successful file operations`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
-| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`变更对应的 goal/change`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
+| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`goal/change for mutations`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
 | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`、`ctx.lsp`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 |
-| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`执行期间的工作流与子会话事件` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
-| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`通过 agent.inject() 注入的 user/message 替换目录` | - | - |
+| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`workflow and child session events during execution` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
+| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`user/message replacement catalogs via agent.inject()` | - | - |
 | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`、`session_event_search`、`session_event_trace`、`session_search`、`session_trace` | `ctx.tools`、`ctx.systemPrompt`、`ctx.sessionQuery`、`a calling Agent for workspace authority` | `tool/call`、`tool/result` | - | 这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 |
-| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`经所选提供方产生的子会话事件` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
-| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`经 ctx.subagents 产生的子会话事件` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
-| `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`直接父会话中的 user 角色消息` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。 |
-| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`通过 agent.inject() 发送后台完成通知的 user/message` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
+| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`child session events through the chosen provider` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
+| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`child session events through ctx.subagents` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
+| `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`a user-role message in the direct parent session` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。 |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 |
 | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflows`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
 | `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 |
@@ -147,7 +147,7 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
 
 ### `exit_plan_mode`
 
-仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 `#` 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。
+仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 # 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。
 
 ```json
 {
@@ -208,7 +208,7 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
 
 来源：[`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
 
-bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
+bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
 
 ## `@deepseek-ai/dsh-tool-pwsh`
 
@@ -307,7 +307,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 ### `cordis_unmount`
 
-卸载当前进程中由 cordis_mount 创建的临时 Plugin。它会等待该插件的工具、监听器、服务、定时器及其他自有效果全部清理完成。只接受 `dyn-N` 临时 id；无法移除 Loader、已配置或已安装的 Plugin。
+卸载当前进程中由 cordis_mount 创建的临时 Plugin。它会等待该插件的工具、监听器、服务、定时器及其他自有效果全部清理完成。只接受 dyn-N 临时 id；无法移除 Loader、已配置或已安装的 Plugin。
 
 ```json
 {
@@ -326,7 +326,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
-不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。
+不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。
 
 ## `@deepseek-ai/dsh-tool-bash-persistent`
 
@@ -361,7 +361,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 * 状态会在命令调用以及与用户的讨论之间持久保留
 * 如果 `path` 是文件，`view` 会显示应用 `cat -n` 后的结果。如果 `path` 是目录，`view` 会列出最多向下 2 层的非隐藏文件和目录
-* 如果指定的 `path` 已作为文件存在，则不能使用 `create` 命令
+* 如果指定的 `create` 命令目标 `path` 已作为文件存在，则不能使用该命令
 * 如果 `command` 产生较长输出，输出会被截断并标记为 `<response clipped>`
 
 使用 `str_replace` 命令时请注意：
@@ -1266,7 +1266,7 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
 
 来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
 
-这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。
+这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。
 
 ## `@deepseek-ai/dsh-tool-subagent-report`
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 57fa7ebc3f..43904e9624 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -20,15 +20,15 @@
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\nGenerated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[English](foo.md) | 中文`. An authored English file reciprocates there with `English | [中文](foo.zh.md)`; a listed generated English source omits that line so it remains byte-identical to generator output.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), the Chinese side and every authored English source carry their language switchers (listed generated English sources are exempt), and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\nGenerated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, the Chinese backlink and authored-source switcher (with the documented generated-source exception), and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留必需的语言切换行和结构签名时，组合出一份新记录。中文文件必须保留指向英文的反向链接；普通撰写的英文源必须保留指向中文的链接，而清单内的生成英文源不作此要求。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 中文文件一律在 H1 标题后立即以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在同一位置以 `English | [中文](foo.zh.md)` 互链；清单内的生成英文源省略此行，以便与生成器输出逐字节一致。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、中文侧和所有普通撰写的英文源都带语言切换行（清单内的生成英文源除外）、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、中文反向链接和普通撰写源的切换行（生成源按本文规则例外），以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
@@ -44,7 +44,7 @@
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index 118a2023b9..073e22ff89 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -119,6 +119,12 @@ const otherSource = baseSource.replace('Beta base.', 'Beta other.')
 const otherZh = baseZh.replace('乙基础。', '乙对侧。')
 const mergedSource = currentSource.replace('Beta base.', 'Beta other.')
 const mergedZh = currentZh.replace('乙基础。', '乙对侧。')
+const generatedBaseSource = '# Module graph\n\nAlpha base.\n\nBeta base.\n'
+const generatedBaseZh = '# 模块图\n\n[English](module-graph.md) | 中文\n\n甲基础。\n\n乙基础。\n'
+const generatedCurrentSource = generatedBaseSource.replace('Alpha base.', 'Alpha current.')
+const generatedCurrentZh = generatedBaseZh.replace('甲基础。', '甲当前。')
+const generatedOtherSource = generatedBaseSource.replace('Beta base.', 'Beta other.')
+const generatedOtherZh = generatedBaseZh.replace('乙基础。', '乙对侧。')
 const manualBaseSource = baseSource.replace('guide.zh.md', 'manual.zh.md')
 const manualBaseZh = baseZh.replace('guide.md', 'manual.md')
 const manualCurrentSource = manualBaseSource.replace('Alpha base.', 'Alpha current.')
@@ -257,6 +263,60 @@ describe('translation pairing merge composition', () => {
     expect(result.zhHash).toBe(gitBlobHash(Buffer.from(mergedZh)))
   })
 
+  it('merges a generated source without an English language switcher', () => {
+    const fixture = createFixture(false)
+    const ancestor = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, generatedBaseZh)
+    const current = record(fixture.root, 'docs/module-graph.md', generatedCurrentSource, generatedCurrentZh)
+    const other = record(fixture.root, 'docs/module-graph.md', generatedOtherSource, generatedOtherZh)
+
+    const result = mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/module-graph.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )
+
+    expect(result.sourceContent.toString('utf8')).toBe(
+      generatedCurrentSource.replace('Beta base.', 'Beta other.'),
+    )
+    expect(result.zhContent.toString('utf8')).toBe(generatedCurrentZh.replace('乙基础。', '乙对侧。'))
+  })
+
+  it('rejects an authored source without an English language switcher', () => {
+    const fixture = createFixture(false)
+    const source = baseSource.replace('English | [中文](guide.zh.md)\n\n', '')
+    const ancestor = record(fixture.root, 'docs/guide.md', source, baseZh)
+    const current = record(fixture.root, 'docs/guide.md', source, baseZh)
+    const other = record(fixture.root, 'docs/guide.md', source, baseZh)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow('docs/guide.md clean merge lost its language-switcher link to guide.zh.md')
+  })
+
+  it('rejects generated Chinese content without its English backlink', () => {
+    const fixture = createFixture(false)
+    const zh = generatedBaseZh.replace('[English](module-graph.md) | 中文\n\n', '')
+    const ancestor = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, zh)
+    const current = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, zh)
+    const other = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, zh)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/module-graph.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow(
+      'docs/module-graph.zh.md clean merge lost its language-switcher link to module-graph.md',
+    )
+  })
+
   it('leaves owner-content conflicts for a human', () => {
     const fixture = createFixture(false)
     const ancestor = record(fixture.root, 'docs/guide.md', baseSource, baseZh)
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
index 7c6d38469c..5ba9ceb0cb 100644
--- a/scripts/translation-pairing-merge.ts
+++ b/scripts/translation-pairing-merge.ts
@@ -15,6 +15,7 @@ import {
   linksTo,
   isTranslationScopeFile,
   parseTranslationMarkdown,
+  requiresSourceLanguageSwitcher,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -163,7 +164,7 @@ function loadRecordOwners(
 function assertMergedPairStructure(paths: TranslationPairPaths, source: Buffer, zh: Buffer): void {
   const sourceTree = parseTranslationMarkdown(source.toString('utf8'))
   const zhTree = parseTranslationMarkdown(zh.toString('utf8'))
-  if (!linksTo(sourceTree, basename(paths.zh))) {
+  if (requiresSourceLanguageSwitcher(paths.source) && !linksTo(sourceTree, basename(paths.zh))) {
     throw new Error(`${paths.source} clean merge lost its language-switcher link to ${basename(paths.zh)}`)
   }
   if (!linksTo(zhTree, basename(paths.source))) {

From 17360907f6de707fc522f46f6cae9db449fc1d19 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 12:35:06 +0800
Subject: [PATCH 200/262] docs(i18n): address terminology review findings

---
 ...andatory-app-attribution-headers.i18n.yaml |  2 +-
 ...21-mandatory-app-attribution-headers.zh.md | 10 +++---
 ...-07-05-uniform-agent-note-format.i18n.yaml |  2 +-
 ...2026-07-05-uniform-agent-note-format.zh.md |  2 +-
 ...ackage-model-experience-contract.i18n.yaml |  2 +-
 ...12-package-model-experience-contract.zh.md |  2 +-
 ...-09-chinese-contract-terminology.i18n.yaml |  6 ++++
 ...2026-08-09-chinese-contract-terminology.md | 33 +++++++++++++++++++
 ...6-08-09-chinese-contract-terminology.zh.md | 33 +++++++++++++++++++
 ...collapse-persistence-flush-state.i18n.yaml |  2 +-
 ...-23-collapse-persistence-flush-state.zh.md | 18 +++++-----
 docs/i18n/style-samples.md                    |  4 +--
 docs/i18n/translation-prompt.md               |  4 +--
 packages/llm/README.i18n.yaml                 |  2 +-
 packages/llm/README.zh.md                     |  2 +-
 packages/plan/README.i18n.yaml                |  2 +-
 packages/plan/README.zh.md                    |  2 +-
 packages/tasks/tool-tasks/README.i18n.yaml    |  2 +-
 packages/tasks/tool-tasks/README.zh.md        |  2 +-
 python/README.i18n.yaml                       |  2 +-
 python/README.zh.md                           |  2 +-
 python/sdk/README.i18n.yaml                   |  2 +-
 python/sdk/README.zh.md                       |  2 +-
 23 files changed, 106 insertions(+), 34 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 43c2f227df..6303b1e77a 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
 2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: d2f7300467790c0a67cfa0ab6222c40c9ee10311
+2026-06-21-mandatory-app-attribution-headers.zh.md: 6f0d0199f859fd462fdecc24e4063cbd27311bab
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index d2f7300467..6f0d0199f8 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -12,9 +12,9 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 ## 调研
 
-- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一份具体的 OpenRouter 约定，而非 IETF 或 OpenAI 兼容 API 标准。
-- **在 agent 工具生态中，`HTTP-Referer` 是一种 OpenRouter 感知的约定，而非通用 agent 约定。** 它足够常见，以至于 OpenRouter SDK 和示例直接暴露它，面向 OpenRouter 的框架通常需要一种方式来透传它。但 ACP（Agent Client Protocol）等 agent 协议在自己的 initialize 消息中协商名称、版本和能力，而模型提供方请求仍需 HTTP 层面的身份标识。因此「在 agent 世界中被接受」意味着「被 OpenRouter 集成所识别」，而非「可跨 agent 运行时或提供方移植」。
-- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同约定；不存在通用的精确格式。
+- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一项具体的 OpenRouter 惯例，而非 IETF 或 OpenAI 兼容 API 标准。
+- **在 agent 工具生态中，`HTTP-Referer` 是一种 OpenRouter 感知的惯例，而非通用 agent 惯例。** 它足够常见，以至于 OpenRouter SDK 和示例直接暴露它，面向 OpenRouter 的框架通常需要一种方式来透传它。但 ACP（Agent Client Protocol）等 agent 协议在自己的 initialize 消息中协商名称、版本和能力，而模型提供方请求仍需 HTTP 层面的身份标识。因此「在 agent 世界中被接受」意味着「被 OpenRouter 集成所识别」，而非「可跨 agent 运行时或提供方移植」。
+- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同惯例；不存在通用的精确格式。
 - **标准化的通用客户端身份头部是 `User-Agent`。** RFC 9110 第 10.1.5 节将 `User-Agent` 定义为用户代理软件身份，说明它用于互操作性报告和分析，并说用户代理应当在每个请求中发送它（除非被配置为不发送）。这是唯一直接对应「哪个产品在发出此 HTTP 请求」的标准头部。
 - **`Referer` 是标准的，但 OpenRouter 的 `HTTP-Referer` 不是标准字段。** RFC 9110 第 10.1.3 节将 `Referer` 定义为获取目标 URI 的来源 URI，并用大量篇幅讨论隐私限制。OpenRouter 则要求 `HTTP-Referer`，将其用作应用 URL 标识符。该名称和含义是 OpenRouter 特有的，尽管它形似标准 `Referer` 头部的 CGI 环境变量形式。
 - **`From` 是标准的，但不适合作为强制默认值。** RFC 9110 第 10.1.2 节将 `From` 定义为负责用户代理的人的电子邮件地址。机器人代理应当发送它以便服务器联系运营者，但非机器人代理出于隐私和安全策略考虑不应在未经用户显式配置的情况下发送。harness 可以后续支持运营者联系方式，但不得凭空捏造或全局强制要求。
@@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 已落地的约定：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属约定（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属约定（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定（adapter contract）章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
@@ -63,7 +63,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
 
-**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 约定当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
+**向所有提供方发送 OpenRouter 头部。** 否决。这会把一项自定义的 OpenRouter 惯例当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
 
 **仅使用提供方账户/项目身份。** 否决。组织/项目头部、API key、云账户和计费项目标识的是谁付费或谁拥有请求，而非哪个应用在发送流量。它们也不暴露公开的应用标题/类别，无法帮助 OpenRouter 等网关构建应用排名。
 
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
index 3b2ed0f39d..ae738e3fad 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
 2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
-2026-07-05-uniform-agent-note-format.zh.md: a13c436a3fa157a0bfe551a7ed0594d052a4de90
+2026-07-05-uniform-agent-note-format.zh.md: 3daa686b64b31ee2638b25dd4c42e5d8172f1d97
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
index a13c436a3f..3daa686b64 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
@@ -22,7 +22,7 @@ Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着
 - **带日期的 Status**（`Status: implemented (accepted YYYY-MM-DD)`）：否决。接受日期属于叙述性历史，写作规则将其排除在文档之外；文件名承载首次提出日期，git 承载其余信息；门禁能检查日期格式，但永远无法检查其真实性。
 - **裸 `# <title>` H1**：否决。文件脱离目录树单独阅读时，`Agent Note: ` 前缀能自描述其体裁，而格式门禁可防止它漂移。
 - **以 `## What we give up` 作为已实现记录的结尾**（README 对 Agent Note 所记录内容的原有表述）：否决。它只点出成本，而诚实的后果章节也会记录取舍换来了什么。
-- **只有约定没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
+- **只有惯例没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过惯例禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠惯例在此处能达到什么效果。
 - **独立的 `FORMAT.md` 约定文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个约定文件更易发现和维护。
 
 ## 后果
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
index 091a912f94..444389759b 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
 2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
-2026-07-12-package-model-experience-contract.zh.md: 9fb6e36e75dcca43fd3ed450c364c57ae7fb7ca4
+2026-07-12-package-model-experience-contract.zh.md: ded8c9fd940b986d9b37ad1563060b8b96e966bb
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
index 9fb6e36e75..ded8c9fd94 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 - **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
 - **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
 - **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
-- **只有约定而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
+- **只有惯例而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.i18n.yaml
new file mode 100644
index 0000000000..408f164e06
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.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 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
+2026-08-09-chinese-contract-terminology.md: d2fea45c6864a19b89c78a52f614ccac341a0127
+2026-08-09-chinese-contract-terminology.zh.md: 772b78daba00c5d881fd0091951557dfc0951ee9
diff --git a/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
new file mode 100644
index 0000000000..d2fea45c68
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
@@ -0,0 +1,33 @@
+# Agent Note: Standardize Chinese contract terminology on 约定
+
+Status: implemented
+
+English | [中文](2026-08-09-chinese-contract-terminology.zh.md)
+
+## Problem
+
+The Chinese documentation rendered English `contract` inconsistently as `契约` and `约定`, sometimes within one file or paragraph. The terminology table prescribed `契约`, while reviewed incremental proofreading selected the more natural engineering rendering `约定`. Leaving the table and corpus split made either choice fail the repository's terminology rule and allowed later translations to reintroduce the disagreement.
+
+English `convention` also commonly renders as `约定`. That overlap is intentional: ordinary Chinese engineering prose uses `约定` for both concepts, and context normally carries whether a statement is descriptive practice or a binding interface rule. Where an English sentence explicitly contrasts a convention with a contract, the Chinese sentence must preserve the distinction through wording such as `惯例` versus `约定`, rather than mechanically giving every `convention` the same rendering.
+
+## Decision
+
+The terminology source of truth defines `contract` as `约定` and `adapter contract` as `适配器约定（adapter contract）` on first mention. Every active Chinese documentation pair follows that ruling; archived Agent Notes remain frozen. Unpaired bilingual calibration assets and the translation prompt's explanatory prose follow the same terms so they cannot teach the superseded rendering.
+
+The migration is semantic prose maintenance, not a rename of identifiers. Inline code, file paths, links, API names, English filenames containing `contract`, and machine-readable values remain unchanged. `convention` does not receive a global terminology row or corpus-wide rewrite: translators preserve natural Chinese and explicitly disambiguate only where the source contrasts the two concepts.
+
+## Alternatives considered
+
+**Keep `contract` as `契约`.** Rejected because the reviewed corpus consistently preferred `约定` for technical interfaces, lifecycle guarantees, and behavioral boundaries, and maintaining the older term would require reverting accepted proofreading across many documents.
+
+**Give `convention` a mandatory global rendering.** Rejected because its meaning ranges from naming practice to protocol convention. A single forced term would create a second broad migration without improving ordinary prose; only explicit source contrasts require a distinct rendering.
+
+**Permit both `契约` and `约定` for `contract`.** Rejected because it preserves the exact inconsistency that made package families and even individual paragraphs disagree.
+
+## Consequences
+
+Active Chinese documentation has one binding rendering for `contract`, and future translation prompts receive that decision directly from the terminology table. Archived records keep their historical text. A source sentence that contrasts convention and contract requires local semantic wording, so equal Chinese dictionary choices never erase a distinction the source actually uses.
+
+## Verification
+
+The migration scans every active bilingual pair, updates each affected Chinese document, re-records its pairing sidecar, and leaves active prose with no `契约` occurrences. The pairing gate, full `doc-sync`, website build, translation prompt tests and snapshot, and `git diff --check` verify the resulting corpus and pipeline assets.
diff --git a/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md
new file mode 100644
index 0000000000..772b78daba
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 将中文 contract 术语统一为「约定」
+
+Status: implemented
+
+[English](2026-08-09-chinese-contract-terminology.md) | 中文
+
+## 问题
+
+中文文档对英文 `contract` 的译法在「契约」与「约定」之间不一致，有时甚至出现在同一文件或段落中。术语表规定使用「契约」，而经过评审的增量复校选择了更符合工程语境的「约定」。若术语表与语料继续分裂，无论选择哪一种译法都会违反仓库术语规则，后续翻译也会再次引入分歧。
+
+英文 `convention` 也常译为「约定」。这种重合是有意保留的：普通中文工程文体会用「约定」表达这两个概念，通常可由上下文判断它描述的是惯常做法还是有约束力的接口规则。如果英文句子明确对比 convention 与 contract，中文必须通过「惯例」与「约定」等措辞保留这种区分，而不能机械地把每个 `convention` 都译成同一个词。
+
+## 决策
+
+术语真源规定 `contract` 译为「约定」，`adapter contract` 首次出现时写作「适配器约定（adapter contract）」。所有活跃中文文档配对均遵循该裁决；归档 Agent Note 保持冻结。未参与配对的双语校准资产和翻译提示词说明文字也采用相同术语，避免继续教授已被取代的译法。
+
+这次迁移只维护语义正文，不重命名标识符。行内代码、文件路径、链接、API 名称、文件名中包含的英文 `contract` 以及机器可读值均保持不变。`convention` 不新增全局术语行，也不做全语料改写：翻译时保留自然中文，只在源文明确对比两个概念时消歧。
+
+## 考虑过的替代方案
+
+**继续把 `contract` 译为「契约」。** 否决，因为经过评审的语料在技术接口、生命周期保证和行为边界中一致倾向使用「约定」；保留旧术语意味着回退大量已接受的复校结果。
+
+**为 `convention` 规定强制的全局译法。** 否决，因为它既可表示命名惯例，也可表示协议约定。强制一种译法会带来另一轮大规模迁移，却无法改善普通行文；只有源文明示对比时才需要使用不同措辞。
+
+**允许 `contract` 同时使用「契约」与「约定」。** 否决，因为这会保留导致包家族乃至同一段落互相矛盾的原始问题。
+
+## 后果
+
+活跃中文文档对 `contract` 只有一种有约束力的译法，后续翻译提示词会直接从术语表获得该决定。归档记录保留历史文字。源文若对比 convention 与 contract，仍需在局部使用语义化措辞，因此相同的常用中文译法不会抹去源文真正表达的区别。
+
+## 验证
+
+迁移扫描每一组活跃双语配对，更新受影响的中文文档并重新记录对应 sidecar，使活跃正文不再出现「契约」。配对门禁、完整 `doc-sync`、网站构建、翻译提示词测试与快照，以及 `git diff --check` 共同验证最终语料和流水线资产。
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index 33051c7a3d..23214f72f8 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
 2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
-2026-07-23-collapse-persistence-flush-state.zh.md: 48896c7080ae28174e259318869c65b48b13418e
+2026-07-23-collapse-persistence-flush-state.zh.md: 2f7ed68984694ff8555aaef12f732a42d9305805
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index 48896c7080..2f7ed68984 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 将实时持久化归并到单个刷新控制器
+# Agent Note: 将实时持久化归并到单个刷写控制器
 
 Status: implemented
 
@@ -12,25 +12,25 @@ Status: implemented
 
 ## 决策
 
-每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享刷新屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
+每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享刷写屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
 
-`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式刷新、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
+`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式刷写、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
 
 初始化只进入现有的按 id 操作链一次，并在占有该轮执行权时调用未串行化的核心操作。该操作链与活跃控制器保持分离，因为公共 `create`、`append`、`load` 调用即使没有 `Session` 对象仍可能发生竞态，依然需要按标识串行执行。
 
-崩溃修复仅适用于冷态标识。对于活跃标识，`load(id)` 会在等待刷新完成前，先对内存中的权威事件生成快照，再将这些事件与 `SessionState.meta`（即持久化写入实际使用的标头）一同返回；若轮次仍打开，则在不读取或修复存储的情况下拒绝该次加载。冷态加载会先在按 id 操作链内同步占用对应标识，再等待读取已存储前缀或执行修复写入；在这项占用解除前，`session/created` 发布边界会拒绝同 id 活跃会话的发布并将其回滚。HMR（热模块替换）接管仍由 `loadStored` 与协调器的 cwd 检查独立处理，会截断撕裂的存储，但不会闭合权威的活跃轮次。
+崩溃修复仅适用于冷态标识。对于活跃标识，`load(id)` 会在等待刷写完成前，先对内存中的权威事件生成快照，再将这些事件与 `SessionState.meta`（即持久化写入实际使用的标头）一同返回；若轮次仍打开，则在不读取或修复存储的情况下拒绝该次加载。冷态加载会先在按 id 操作链内同步占用对应标识，再等待读取已存储前缀或执行修复写入；在这项占用解除前，`session/created` 发布边界会拒绝同 id 活跃会话的发布并将其回滚。HMR（热模块替换）接管仍由 `loadStored` 与协调器的 cwd 检查独立处理，会截断撕裂的存储，但不会闭合权威的活跃轮次。
 
-活跃控制器映射同时也是退役注册表。退役成功时，系统排空并移除其控制器；退役失败时，控制器保留在映射中。后端资源销毁会停止接纳事件，刷新所有仍存在的控制器，等待其余按 id 操作完成，然后关闭后端。无需另设退役集合来重新发现未完成的工作。
+活跃控制器映射同时也是退役注册表。退役成功时，系统排空并移除其控制器；退役失败时，控制器保留在映射中。后端资源销毁会停止接纳事件，刷写所有仍存在的控制器，等待其余按 id 操作完成，然后关闭后端。无需另设退役集合来重新发现未完成的工作。
 
 ## 备选方案
 
 **保留仅由检查点触发的延后写入。** 这种方式可以形成更大的批次，但会让持久性依赖另行挂载的检查点策略，并使检查点之间因崩溃而丢失数据的窗口达到最大。有界后台调度仍会合并突发事件，并在强制屏障之间持久化进度。
 
-**在整个协调器范围内使用一个刷新 promise。** 这种挂接方式适用于单个文件，但全局 promise 会串行化互不相关的会话。每个活跃会话各有一个控制器，既能让不同会话的后端操作独立推进，又由按 id 操作链保护同一标识的操作。
+**在整个协调器范围内使用一个刷写 promise。** 这种挂接方式适用于单个文件，但全局 promise 会串行化互不相关的会话。每个活跃会话各有一个控制器，既能让不同会话的后端操作独立推进，又由按 id 操作链保护同一标识的操作。
 
-**永久锁存首次后台写入错误。** 这会让后续每次刷新都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
+**永久锁存首次后台写入错误。** 这会让后续每次刷写都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
 
-**拒绝对所有活跃会话的加载。** 这样做很安全，但会让持久化消费方和测试无法再使用既有的闭合活跃会话快照。先生成快照再刷新，为调用提供了稳定的线性化点：刷新成功即可证明正是该快照已持久化，而活跃路径绝不调用崩溃修复。
+**拒绝对所有活跃会话的加载。** 这样做很安全，但会让持久化消费方和测试无法再使用既有的闭合活跃会话快照。先生成快照再刷写，为调用提供了稳定的线性化点：刷写成功即可证明正是该快照已持久化，而活跃路径绝不调用崩溃修复。
 
 ## 验证
 
@@ -44,6 +44,6 @@ Status: implemented
 
 ## 后果
 
-活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和刷新屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
+活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和刷写屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
 
 `session/flush` 不再决定普通持久化何时开始。它仍是循环和检查点策略使用的顺序与错误观测边界，因此检查点成功仍表示在其完成前接纳的每个事件都已持久化。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 432c95e684..1b8a0e3f1a 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -16,7 +16,7 @@
 
 > This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the generated regions of [subsystems/](../subsystems/core.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外约定写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
@@ -60,7 +60,7 @@
 
 > The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
 
-门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分契约要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
+门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分约定要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
 
 ## ⑥ Agent Note 论证
 
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 0f8b836da4..06e426aa5c 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,8 +1,8 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。[提示词 v4 契约 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录兼容协议；v7 保留该协议并选择性吸收经评估的生成质量改进。修改本文件会改变翻译行为，需正常经过 PR 评审。
+本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。[提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录兼容协议；v7 保留该协议并选择性吸收经评估的生成质量改进。修改本文件会改变翻译行为，需正常经过 PR 评审。
 
-## 占位符契约
+## 占位符约定
 
 流水线渲染模板时替换以下占位符，除此之外不改写系统消息：
 
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index a3ccfcf944..a8bc82817f 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/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/llm/README.md
 README.md: 077ae600c89cff80cd71830e37bda00707c1d837
-README.zh.md: 95355d34c014a1b442da1028251301d6d4202c6b
+README.zh.md: 46d4aa8a6088b3d5f40718f0c2626783e6c05c4b
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index 95355d34c0..46d4aa8a60 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -14,4 +14,4 @@ LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
 
-子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定（adapter contract）——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/plan/README.i18n.yaml b/packages/plan/README.i18n.yaml
index 8291b525f1..c2a60d7d2d 100644
--- a/packages/plan/README.i18n.yaml
+++ b/packages/plan/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/plan/README.md
 README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
-README.zh.md: 1b28af328f6da5cfabb09093c339f6504316f0e7
+README.zh.md: 0ee1c658ee0a7863eb16b99d956e882f320a3717
diff --git a/packages/plan/README.zh.md b/packages/plan/README.zh.md
index 1b28af328f..0ee1c658ee 100644
--- a/packages/plan/README.zh.md
+++ b/packages/plan/README.zh.md
@@ -10,4 +10,4 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
 
 [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
 
-子系统参考——`plan/mode` 折叠、步骤边界刷新、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
+子系统参考——`plan/mode` 折叠、步骤边界刷写、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
diff --git a/packages/tasks/tool-tasks/README.i18n.yaml b/packages/tasks/tool-tasks/README.i18n.yaml
index 65b1128efb..24e6b6892a 100644
--- a/packages/tasks/tool-tasks/README.i18n.yaml
+++ b/packages/tasks/tool-tasks/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/tasks/tool-tasks/README.md
 README.md: 6e8e889c2330d6991cb384674b011e4d2e988268
-README.zh.md: 3b9dbd4f895eb38f0ffc7951169ff292da8603f1
+README.zh.md: 355b6736b476fb2434f17ea3857544f32c40adb3
diff --git a/packages/tasks/tool-tasks/README.zh.md b/packages/tasks/tool-tasks/README.zh.md
index 3b9dbd4f89..355b6736b4 100644
--- a/packages/tasks/tool-tasks/README.zh.md
+++ b/packages/tasks/tool-tasks/README.zh.md
@@ -18,7 +18,7 @@
 
 ## 完成通知
 
-一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step 收件箱。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
+一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step inbox。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
 
 ## 配置
 
diff --git a/python/README.i18n.yaml b/python/README.i18n.yaml
index 249bf6bb76..9e0a17e270 100644
--- a/python/README.i18n.yaml
+++ b/python/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 python/README.md
 README.md: 27637edb9d4d5e8714fe379a00b6aae3af1a541f
-README.zh.md: 9eed37aa10cc1bc1265938968d8084ce1ef840ce
+README.zh.md: b0587b25b66750780768786e02b02037dd10ec0a
diff --git a/python/README.zh.md b/python/README.zh.md
index 9eed37aa10..b0587b25b6 100644
--- a/python/README.zh.md
+++ b/python/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 行为
 
-除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置约定分别由 [SDK 参考](sdk/README.md) 和 [运行时载体参考](sdk-runtime/README.md) 定义。
+除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置约定分别由 [SDK 参考](sdk/README.md)和[运行时载体参考](sdk-runtime/README.md)定义。
 
 ## 贡献者工作流
 
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 081b8eb17e..6467b4ca87 100644
--- a/python/sdk/README.i18n.yaml
+++ b/python/sdk/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 python/sdk/README.md
 README.md: 2d545688c58a2f1b755e647d7cda9555249e41c4
-README.zh.md: 3f1e15bf8a148efd18fe66272bec2e0b28de8d21
+README.zh.md: b335d75aedc3a145771b23ea5d408315cae9a3e3
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 3f1e15bf8a..b335d75aed 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -31,7 +31,7 @@ with DeepSeekHarness(
 
 `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
 
-`Session.run()` 拥有一个从收件箱持久接收该提示词时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
+`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
 
 `HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
 

From 76b3353452fd46f2fa27453d18985fab994d14d7 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 22 Jul 2026 18:02:26 +0800
Subject: [PATCH 201/262] docs: call waterfall interception short-circuiting

---
 .../2026-06-11-microkernel-event-taxonomy.i18n.yaml           | 4 ++--
 .../architecture/2026-06-11-microkernel-event-taxonomy.md     | 2 +-
 .../architecture/2026-06-11-microkernel-event-taxonomy.zh.md  | 2 +-
 .../2026-07-12-agent-scope-runtime-design.i18n.yaml           | 4 ++--
 .../architecture/2026-07-12-agent-scope-runtime-design.md     | 4 ++--
 .../architecture/2026-07-12-agent-scope-runtime-design.zh.md  | 4 ++--
 .../2026-07-08-self-referential-cordis-toolset.i18n.yaml      | 4 ++--
 .../feature/2026-07-08-self-referential-cordis-toolset.md     | 2 +-
 .../feature/2026-07-08-self-referential-cordis-toolset.zh.md  | 2 +-
 AGENTS.md                                                     | 2 +-
 docs/architecture.i18n.yaml                                   | 4 ++--
 docs/architecture.md                                          | 2 +-
 docs/architecture.zh.md                                       | 2 +-
 docs/cordis-api/inherited.md                                  | 2 +-
 docs/tool-catalog.md                                          | 2 +-
 docs/user/develop/framework/events.i18n.yaml                  | 4 ++--
 docs/user/develop/framework/events.md                         | 4 ++--
 docs/user/develop/framework/events.zh.md                      | 4 ++--
 .../snapshots/advanced-toolchain/system-prompt.expected.md    | 2 +-
 .../snapshots/advanced-toolchain/tool-schemas.expected.json   | 2 +-
 .../tests/snapshots/cordis-inspect-jsdoc/session.jsonl        | 2 +-
 .../tests/snapshots/advanced-toolchain/session.1.jsonl        | 2 +-
 .../tests/snapshots/advanced-toolchain/session.2.jsonl        | 2 +-
 .../tests/snapshots/advanced-toolchain/session.jsonl          | 2 +-
 packages/core/agent-loop/tests/loop.spec.ts                   | 2 +-
 packages/self-modification/tool-cordis/src/api-catalog.ts     | 2 +-
 packages/self-modification/tool-cordis/src/index.ts           | 2 +-
 packages/self-modification/tool-cordis/src/inspect.ts         | 2 +-
 packages/self-modification/tool-cordis/tests/inspect.spec.ts  | 4 ++--
 scripts/gen-cordis-catalog.ts                                 | 2 +-
 30 files changed, 40 insertions(+), 40 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
index 1d561dd14a..5a5aa0eaea 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.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 .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
-2026-06-11-microkernel-event-taxonomy.md: 202595fed125966a5d77920536e7f4ee88f875fe
-2026-06-11-microkernel-event-taxonomy.zh.md: 1365910157c36699bfe1fdb3a10aa0785948e0fa
+2026-06-11-microkernel-event-taxonomy.md: fe6c242acbc0b64123711a17a528f35c02d91087
+2026-06-11-microkernel-event-taxonomy.zh.md: aa3db53d640145836817f9835a30c69815f70d23
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
index 202595fed1..fe6c242acb 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
@@ -12,7 +12,7 @@ The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic
 
 Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:
 
-- **waterfall** (around-middleware) where plugins transform, veto, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
+- **waterfall** (around-middleware) where plugins transform, short-circuit, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
 - **serial** (awaited in listener order) for ordered checkpoints such as `agent/turn-stopping`.
 - **parallel** (awaited fan-out) where every listener must get an independent chance: the `session/flush` durability checkpoint.
 - **emit** (synchronous fire-and-forget) for notifications: inbox transitions, lifecycle, errors, and the contained immutable `tools/result` observation. Durable session events own turn and step boundaries.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
index 1365910157..aa3db53d64 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展 seam 是带类型的事件，具有明确的分发模式：
 
-- **waterfall（瀑布式事件）**（around-middleware）：插件可变换、否决、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
+- **waterfall（瀑布式事件）**（around-middleware）：插件可变换、短路、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
 - **serial**（按监听器顺序依次 await）：用于 `agent/turn-stopping` 等有序检查点。
 - **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
 - **emit**（同步 fire-and-forget）：用于通知：inbox 转换、生命周期、错误，以及受错误隔离的 `tools/result` 观测；该观测接收不可变的最终结果。轮次与步骤边界由持久会话事件拥有。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index 380171ab17..f5fdd4e906 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.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 .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
-2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: e0c01f31eb2664608139f95dc60025a5b33e4618
+2026-07-12-agent-scope-runtime-design.md: b8f265551c4ebbb94d32b3599959fe6cc4da974d
+2026-07-12-agent-scope-runtime-design.zh.md: 22cd35a601bc011c27a748098be11990f5ee4653
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index b93c291957..b8f265551c 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -34,7 +34,7 @@ The [July 8 Agent Note](2026-07-08-agent-scope-contexts.md) remains the contribu
 
 ## Cordis model: context, fiber, effect, receiver, and waterfall
 
-Five Cordis ideas are required to understand the implementation. A context selects services and registration ownership; a fiber is one live plugin or child lifecycle; an effect attaches cleanup to a fiber; an event receiver selects listeners; and a waterfall lets listeners transform or veto an operation in sequence.
+Five Cordis ideas are required to understand the implementation. A context selects services and registration ownership; a fiber is one live plugin or child lifecycle; an effect attaches cleanup to a fiber; an event receiver selects listeners; and a waterfall lets listeners transform or short-circuit an operation in sequence.
 
 ### A context is an ownership path through one service graph
 
@@ -56,7 +56,7 @@ Cordis filters listeners using the dispatch receiver (`this`), while harness lis
 
 Product helpers therefore construct the carrier and pass the domain subject separately. This prevents listener routing from becoming an alternate object model and keeps event signatures understandable without knowledge of carrier internals.
 
-A Cordis waterfall is middleware-style dispatch. Each listener receives `next()`: calling it delegates to the remaining listeners and base operation, while returning without it vetoes or replaces the downstream result. Waterfalls power prompt assembly and tool policy; ordinary emit events notify synchronously, and parallel events await all listeners without a veto result.
+A Cordis waterfall is middleware-style dispatch. Each listener receives `next()`: calling it delegates to the remaining listeners and base operation, while returning without it short-circuits or replaces the downstream result. Waterfalls power prompt assembly and tool policy; ordinary emit events notify synchronously, and parallel events await all listeners without a veto result.
 
 ## Scope routing: one opaque key selects one layer
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index e0c01f31eb..22cd35a601 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -34,7 +34,7 @@ Status: implemented
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
-理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或否决一个操作。
+理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或短路一个操作。
 
 ### 上下文是贯穿单个服务图的所有权路径
 
@@ -56,7 +56,7 @@ Cordis 使用 dispatch receiver（`this`）过滤监听器，而 harness 的监
 
 因此，产品辅助函数构造载体并单独传递领域主体。这防止监听器路由变成另一套对象模型，并使事件签名在不了解载体内部的情况下也可理解。
 
-Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
+Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则短路或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
 
 ## 作用域路由：一个不透明键选择一层
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 900fc9c374..2032c54723 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: 29d331008d4111ae00147f2ddd19a628135339ac
-2026-07-08-self-referential-cordis-toolset.zh.md: d61ba794781226437a5d7499c20e5cd33119fe78
+2026-07-08-self-referential-cordis-toolset.md: a2f614cc5a236e45622eae2b30f518181331cc79
+2026-07-08-self-referential-cordis-toolset.zh.md: 6c56c2bf0c8cc8d175f451290620d9386bb69a23
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index 29d331008d..a2f614cc5a 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -81,4 +81,4 @@ The correctness investment therefore goes where it pays for every capability at
 
 ## Consequences
 
-The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` vetoes the chain, so a mounted listener can lobotomize the agent's own tool dispatch ([waterfall semantics](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume.
+The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` short-circuits the chain, so a mounted listener can stop the agent's own tool dispatch ([waterfall semantics](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume.
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index d61ba79478..6c56c2bf0c 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -81,4 +81,4 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 ## 后果
 
-该工具集是刻意的显式启用设计，具有完全特权的 `ctx`，因此部署方采用它的意识程度应与 bash 工具相当。以下几个事实由工具描述直接告知模型：一个 waterfall（瀑布式事件）监听器（如 `tools/pre-execute`）如果不调用 `next()` 就返回，会否决整条链，因此一个挂载的监听器可以瘫痪 agent 自身的工具分发（[waterfall 语义](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)）；挂载代码在当前轮次的工具调用内运行，因此 await 任何只在该轮次结束后才 resolve 的东西会导致死锁；`vmTimeoutMs` 仅约束同步执行；挂载不会在会话恢复后存活。
+该工具集是刻意的显式启用设计，具有完全特权的 `ctx`，因此部署方采用它的意识程度应与 bash 工具相当。以下几个事实由工具描述直接告知模型：一个 waterfall（瀑布式事件）监听器（如 `tools/pre-execute`）如果不调用 `next()` 就返回，会短路整条链，因此一个挂载的监听器可以阻止 agent 自身的工具分发（[waterfall 语义](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)）；挂载代码在当前轮次的工具调用内运行，因此 await 任何只在该轮次结束后才 resolve 的东西会导致死锁；`vmTimeoutMs` 仅约束同步执行；挂载不会在会话恢复后存活。
diff --git a/AGENTS.md b/AGENTS.md
index dcb001768e..deabc5ed99 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
-- **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
+- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
 - **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively.
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 6791ac709d..1b81c2c5da 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
-architecture.zh.md: 80028f33c620b35ffc549b4f4828a23a5f930e93
+architecture.md: 06c15f204b3a695de49df29938781f8f033c4a7e
+architecture.zh.md: 29fe94f5a94c317854366e811dc6ceb74d2fddfe
diff --git a/docs/architecture.md b/docs/architecture.md
index f593ee5c54..06c15f204b 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -63,7 +63,7 @@ Events are the service extension API ([subsystems](subsystems/core.md), [produce
 
 ### Interception Semantics
 
-Waterfalls are around-middleware: listeners delegate with `next()`; returning without it vetoes or takes over ([semantics](cordis-primer.md#cordis-waterfall-semantics)).
+Waterfalls are around-middleware: listeners delegate with `next()`; returning without it short-circuits or takes over ([semantics](cordis-primer.md#cordis-waterfall-semantics)).
 
 ## Default Loop Lifecycle
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 80028f33c6..29fe94f5a9 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -63,7 +63,7 @@
 
 ### 拦截语义
 
-waterfall（瀑布式事件）是环绕中间件：监听器通过 `next()` 委托；不调用它而直接返回会否决或接管（[语义](cordis-primer.md#cordis-waterfall-semantics)）。
+waterfall（瀑布式事件）是环绕中间件：监听器通过 `next()` 委托；不调用它而直接返回会短路或接管（[语义](cordis-primer.md#cordis-waterfall-semantics)）。
 
 ## 默认循环生命周期
 
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 5582bdd1ac..8bf23274e5 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -10,7 +10,7 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
 - `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
-- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
+- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / short-circuit chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
 - `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:164`](../../vendor/cordis/src/registry.ts))
 - `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
 - `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 8986847d1e..e598429553 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -284,7 +284,7 @@ Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self
 
 ### `cordis_mount`
 
-Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.
+Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.
 
 ```json
 {
diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml
index d6bb924fc7..f39b04145d 100644
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/docs/user/develop/framework/events.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 docs/user/develop/framework/events.md
-events.md: c70150b4d9070063513021e420f253ff6d4e5de1
-events.zh.md: b3b79a86d249eed0df15380e17a1ee71766b1a72
+events.md: 8a8c076d9c7b40d73182db074c4f494fded8c6dd
+events.zh.md: 9649d89d575a1b05fa524bd460043da71dc9ae43
diff --git a/docs/user/develop/framework/events.md b/docs/user/develop/framework/events.md
index c70150b4d9..8a8c076d9c 100644
--- a/docs/user/develop/framework/events.md
+++ b/docs/user/develop/framework/events.md
@@ -63,7 +63,7 @@ await ctx.serial('setup-phase', context)
 
 ### waterfall — pipeline
 
-Each listener may wrap the downstream result to form a processing chain. A listener **must call `next()` to delegate downstream**; omitting the call vetoes the pipeline:
+Each listener may wrap the downstream result to form a processing chain. A listener **must call `next()` to delegate downstream**; omitting the call short-circuits the pipeline:
 
 ```ts ignore-check
 // Dispatch
@@ -77,7 +77,7 @@ ctx.on('my-plugin/transform', async (_input, next) => {
 ```
 
 ::: warning
-A waterfall listener **must call `next()`**. Omitting it vetoes the pipeline by design, enabling interception and gateway behavior.
+A waterfall listener **must call `next()`**. Omitting it short-circuits the pipeline by design, enabling interception and gateway behavior.
 :::
 
 ## Typed events
diff --git a/docs/user/develop/framework/events.zh.md b/docs/user/develop/framework/events.zh.md
index b3b79a86d2..9649d89d57 100644
--- a/docs/user/develop/framework/events.zh.md
+++ b/docs/user/develop/framework/events.zh.md
@@ -63,7 +63,7 @@ await ctx.serial('setup-phase', context)
 
 ### waterfall（瀑布式事件）— 流水线
 
-每个监听器可以包装下游返回值，形成处理链。**必须调用 `next()` 传递给下游**，不调用即为否决：
+每个监听器可以包装下游返回值，形成处理链。**必须调用 `next()` 传递给下游**，不调用即会短路流水线：
 
 ```ts ignore-check
 // Dispatch
@@ -77,7 +77,7 @@ ctx.on('my-plugin/transform', async (_input, next) => {
 ```
 
 ::: warning
-waterfall 监听器**必须调用 `next()`**。不调用 `next` 等于否决整个流水线，这是故意为之的设计——用于实现拦截/网关逻辑。
+waterfall 监听器**必须调用 `next()`**。不调用 `next` 会短路整个流水线，这是故意为之的设计——用于实现拦截/网关逻辑。
 :::
 
 ## 类型安全的事件
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index b9fc8ec9d9..2014dc54e3 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -60,7 +60,7 @@ interface ToolArgsMap {
     /** Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events". */
     name?: string;
   } & Record<string, JsonValue>;
-  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */
+  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */
   cordis_mount: {
     /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */
     code: string;
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index 70ab4e61f6..403d3fbc6c 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -72,7 +72,7 @@
     },
     {
       "name": "cordis_mount",
-      "description": "Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.",
+      "description": "Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
index 12a88365a6..9fcadd71d4 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -25,7 +25,7 @@
 {"type":"assistant/chunk","seq":23,"time":1785730459921,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":24,"time":1785730459921,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"283c82b3-1bda-481c-a716-c35f363c9752"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
 {"type":"tool/call","seq":25,"time":1785730459921,"data":{"turn":1,"step":2,"callId":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}}
-{"type":"tool/result","seq":26,"time":1785730459929,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-tools-event"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-event","content":[{"type":"text","text":"## events\n- tools/pre-execute [waterfall] — Allow, deny, or ask before dispatch.\n    /**\n     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n     * approval support turns `ask` into denial. Async gates must observe\n     * `exec.signal`; the registry rechecks cancellation after they settle but\n     * never abandons their promise.\n     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.\n     * @param exec - the pending call (name, parsed arguments, caller agent).\n     * @mode waterfall\n     */\n    'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>\nwaterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain."}],"isError":false}],"role":"user","id":"c187306a-d73c-4bcd-b76c-8607ddbc0974"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
+{"type":"tool/result","seq":26,"time":1785730459929,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-tools-event"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-event","content":[{"type":"text","text":"## events\n- tools/pre-execute [waterfall] — Allow, deny, or ask before dispatch.\n    /**\n     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n     * approval support turns `ask` into denial. Async gates must observe\n     * `exec.signal`; the registry rechecks cancellation after they settle but\n     * never abandons their promise.\n     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.\n     * @param exec - the pending call (name, parsed arguments, caller agent).\n     * @mode waterfall\n     */\n    'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>\nwaterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() short-circuits the chain."}],"isError":false}],"role":"user","id":"c187306a-d73c-4bcd-b76c-8607ddbc0974"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
 {"type":"step/end","seq":27,"time":1785730459929,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":28,"time":1785730459939,"data":{"turn":1,"step":3}}
 {"type":"assistant/chunk","seq":29,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
index ff58bd3a43..44cbf0e360 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
@@ -6,7 +6,7 @@
 {"type":"step/start","seq":4,"time":1785730501506,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":5,"time":1785730501506,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"fc62f9e7-b8f6-441f-9ee8-17f1f9e4feca"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730501506,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498583897,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498583897,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730501507,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":10,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
index 02c779e8f4..6988595618 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
@@ -6,7 +6,7 @@
 {"type":"step/start","seq":4,"time":1785730501645,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":5,"time":1785730501645,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"093bfc20-c6fc-4573-b172-2c6ca40c188b"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730501645,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498584067,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498584067,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730501646,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":10,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
index a168db4b8b..6769414d10 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -5,7 +5,7 @@
 {"type":"step/start","seq":3,"time":1783957884486,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":4,"time":1785498583779,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: try a no-op temporary Cordis Plugin named snapshot-marker; use run_code to inspect the live temporary Plugins through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; stop dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"},"role":"user","id":"d2f4f71c-78bc-4a22-908d-c08fbb3ab9ef"},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1785498583779,"data":{"title":"Run this advanced flow exactly","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":6,"time":1785498583782,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":6,"time":1785498583782,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":7,"time":1785730501403,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":8,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":9,"time":1783950000008,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts
index 1173607ae9..c42331de58 100644
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -338,7 +338,7 @@ describe('agent loop', () => {
     expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou run on mock.')
   })
 
-  it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
+  it('omits the system field when system-prompt/assemble short-circuits with an empty assembly', async () => {
     // The documented escape valve: a deployment that must drop the harness
     // openers short-circuits the assemble waterfall; the request then carries
     // NO system field at all (not an empty string).
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index 5bd34a8642..e8381a56a6 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -3306,7 +3306,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
 /** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */
 export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [
   { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' },
-  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).' },
+  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / short-circuit chain).' },
   { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.' },
   { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.' },
   { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.' },
diff --git a/packages/self-modification/tool-cordis/src/index.ts b/packages/self-modification/tool-cordis/src/index.ts
index 5476dc0929..6ba56ccfe4 100644
--- a/packages/self-modification/tool-cordis/src/index.ts
+++ b/packages/self-modification/tool-cordis/src/index.ts
@@ -154,7 +154,7 @@ export function apply(ctx: Context, config: Config): void {
       + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). '
       + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a '
       + 'trailing `next` callback which MUST be called — returning without `next()` '
-      + 'VETOES the call; prefer plain notification events unless you intend to '
+      + 'SHORT-CIRCUITS the call; prefer plain notification events unless you intend to '
       + 'intercept. (2) Never await something that only resolves after the current '
       + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). '
       + '(3) Your `ctx` is a restricted façade: you can register tools, observe '
diff --git a/packages/self-modification/tool-cordis/src/inspect.ts b/packages/self-modification/tool-cordis/src/inspect.ts
index cc0f3a4cda..08bbeb44cf 100644
--- a/packages/self-modification/tool-cordis/src/inspect.ts
+++ b/packages/self-modification/tool-cordis/src/inspect.ts
@@ -224,6 +224,6 @@ export function describeEvents(events: readonly EventApiEntry[] = EVENT_API, nam
     entry.push(`    ${event.signature}`)
     return entry
   })
-  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
+  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() short-circuits the chain.')
   return lines
 }
diff --git a/packages/self-modification/tool-cordis/tests/inspect.spec.ts b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
index 2b3b32aee8..ca9fb4e03f 100644
--- a/packages/self-modification/tool-cordis/tests/inspect.spec.ts
+++ b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
@@ -95,7 +95,7 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tools/change [emit]')
     expect(report).toContain('- tools/pre-execute [waterfall]')
     expect(report).toMatch(/'agent\/status'\(/)
-    expect(report).toContain('returning without next() vetoes the chain')
+    expect(report).toContain('returning without next() short-circuits the chain')
     expect(report).not.toContain('/**')
     expect(report).not.toContain('@mode waterfall')
   })
@@ -171,7 +171,7 @@ describe('inspect renderers (direct)', () => {
 
   it('describeEvents renders an empty catalog as just the waterfall caution', () => {
     expect(describeEvents([])).toEqual([
-      'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.',
+      'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() short-circuits the chain.',
     ])
   })
 })
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index aaae6f7649..66b3cea813 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -508,7 +508,7 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
   ],
   inheritedServices: [
     { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / short-circuit chain).', source: 'vendor/cordis/src/events.ts:34' },
     { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
     { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
     { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },

From 9d5eb37638b36948f2fd8d134e40d75d9fd3c3c7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 12:13:58 +0800
Subject: [PATCH 202/262] fix(headless): dsh run is a direct core front door

---
 ...-model-catalog-and-acp-selection.i18n.yaml |   4 +-
 ...-15-llm-model-catalog-and-acp-selection.md |   4 +-
 ...-llm-model-catalog-and-acp-selection.zh.md |   4 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |   4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |   8 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |   8 +-
 ...tree-boot-and-transport-layering.i18n.yaml |   4 +-
 ...config-tree-boot-and-transport-layering.md |   8 +-
 ...fig-tree-boot-and-transport-layering.zh.md |   8 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |   4 +-
 .../2026-08-05-profile-plugin-bundles.md      |   2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |   2 +-
 ...-headless-direct-core-front-door.i18n.yaml |   6 +
 ...6-08-09-headless-direct-core-front-door.md |  44 +++
 ...8-09-headless-direct-core-front-door.zh.md |  44 +++
 ...07-24-web-session-model-selector.i18n.yaml |   4 +-
 .../2026-07-24-web-session-model-selector.md  |  20 +-
 ...026-07-24-web-session-model-selector.zh.md |  20 +-
 ...default-model-follows-the-picker.i18n.yaml |   4 +-
 ...-08-07-default-model-follows-the-picker.md |  40 ++-
 ...-07-default-model-follows-the-picker.zh.md |  40 ++-
 ...6-08-08-dsh-run-headless-command.i18n.yaml |   4 +-
 .../2026-08-08-dsh-run-headless-command.md    |  30 +-
 .../2026-08-08-dsh-run-headless-command.zh.md |  30 +-
 apps/cli/README.i18n.yaml                     |   4 +-
 apps/cli/README.md                            |   2 +-
 apps/cli/README.zh.md                         |   2 +-
 apps/cli/composition.md                       |   3 +
 apps/cli/reference/README.i18n.yaml           |   4 +-
 apps/cli/reference/README.md                  |   4 +-
 apps/cli/reference/README.zh.md               |   4 +-
 apps/cli/tests/built-bin.e2e.ts               |  16 +-
 apps/cli/tests/fixtures/never-dispose.mjs     |   1 +
 apps/cli/tests/headless-shutdown.e2e.ts       |   7 +-
 apps/web/tests/declared-reasoning.e2e.ts      |   6 +-
 apps/web/tests/declared-reasoning.overlay.yml |   2 +-
 apps/web/tests/default-model.e2e.ts           |   8 +-
 apps/web/tests/default-model.overlay.yml      |   2 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   1 +
 docs/architecture.zh.md                       |   1 +
 docs/capability-seams.md                      |   7 +
 docs/config-catalog.md                        |  43 ++-
 docs/event-producer-consumer.md               |   2 +-
 docs/i18n/terminology.md                      |   1 +
 docs/module-graph.md                          |  18 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |  24 ++
 docs/subsystems/core.zh.md                    |  24 ++
 docs/user/guide/providers.i18n.yaml           |   4 +-
 docs/user/guide/providers.md                  |   6 +-
 docs/user/guide/providers.zh.md               |   6 +-
 docs/user/guide/quickstart.i18n.yaml          |   4 +-
 docs/user/guide/quickstart.md                 |   4 +-
 docs/user/guide/quickstart.zh.md              |   4 +-
 .../tests/fixtures/dsh-run.cordis.yml         |   2 +-
 .../headless-agent/tests/headless.snapshot.ts |   2 +-
 .../snapshots/dsh-run/session.expected.jsonl  |   4 +-
 knip.json                                     |   5 +
 packages/acp/acp/src/index.ts                 |   4 +-
 packages/boot/app-boot/README.i18n.yaml       |   4 +-
 packages/boot/app-boot/README.md              |   2 +-
 packages/boot/app-boot/README.zh.md           |   2 +-
 packages/boot/app-boot/src/profile.ts         |  33 +-
 packages/boot/app-boot/tests/profile.spec.ts  |  27 ++
 packages/bundle/README.i18n.yaml              |   4 +-
 packages/bundle/README.md                     |   2 +-
 packages/bundle/README.zh.md                  |   2 +-
 packages/bundle/base/README.i18n.yaml         |   4 +-
 packages/bundle/base/README.md                |   2 +-
 packages/bundle/base/README.zh.md             |   2 +-
 packages/bundle/base/cordis.patch.yml         |   8 +
 packages/bundle/base/package.json             |   1 +
 packages/bundle/headless/README.i18n.yaml     |   4 +-
 packages/bundle/headless/README.md            |   8 +-
 packages/bundle/headless/README.zh.md         |   8 +-
 packages/bundle/headless/cordis.patch.yml     |  31 +-
 packages/bundle/headless/package.json         |  11 +-
 packages/bundle/headless/src/index.ts         | 212 +++++------
 .../bundle/headless/tests/headless.spec.ts    | 335 ++++++++----------
 packages/bundle/headless/tsconfig.json        |  12 +-
 packages/bundle/web-app/README.i18n.yaml      |   4 +-
 packages/bundle/web-app/README.md             |   2 +-
 packages/bundle/web-app/README.zh.md          |   2 +-
 packages/bundle/web-app/cordis.patch.yml      |   6 +-
 packages/client/connection/src/client/api.ts  |   2 +-
 .../client/connection/src/client/fixture.ts   |  24 +-
 .../client/connection/src/client/index.ts     |   2 +-
 packages/client/connection/tests/fake-api.ts  |  12 +-
 .../client/connection/tests/fixture.spec.ts   |   2 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   4 +-
 packages/client/runtime/README.zh.md          |   4 +-
 packages/client/runtime/tests/fake-api.ts     |   6 +-
 packages/client/runtime/tests/manager.spec.ts |   2 +-
 packages/client/runtime/tests/session.spec.ts |  12 +-
 packages/client/ui-model/README.i18n.yaml     |   4 +-
 packages/client/ui-model/README.md            |   6 +-
 packages/client/ui-model/README.zh.md         |   6 +-
 .../ui-model/src/client/ModelSelect.tsx       |  18 +-
 .../client/ui-model/src/client/directory.ts   |  28 +-
 packages/client/ui-model/src/client/index.ts  |  20 +-
 packages/client/ui-model/src/client/slots.ts  |   8 +-
 .../ui-model/tests/browser-plugin.spec.ts     |   6 +-
 .../ui-model/tests/model-select.spec.tsx      |  10 +-
 packages/core/README.i18n.yaml                |   4 +-
 packages/core/README.md                       |   5 +-
 packages/core/README.zh.md                    |   5 +-
 .../core/agent-default-model/README.i18n.yaml |   6 +
 packages/core/agent-default-model/README.md   |  25 ++
 .../core/agent-default-model/README.zh.md     |  25 ++
 .../core/agent-default-model/package.json     |  44 +++
 .../core/agent-default-model/src/index.ts     | 107 ++++++
 .../core/agent-default-model/src/invariant.ts |  30 ++
 .../tests/agent-default-model.spec.ts         |  98 +++++
 .../core/agent-default-model/tsconfig.json    |  30 ++
 .../core/agent-default-model/tsdown.config.ts |  25 ++
 packages/core/agent/README.i18n.yaml          |   4 +-
 packages/core/agent/README.md                 |   2 +-
 packages/core/agent/README.zh.md              |   2 +-
 packages/core/agent/src/index.ts              |   2 +-
 .../src/{llm-target.ts => model-selection.ts} |  42 +--
 ...target.spec.ts => model-selection.spec.ts} |  14 +-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |  20 +-
 packages/host/apiproxy/README.zh.md           |  22 +-
 packages/host/apiproxy/package.json           |   1 +
 packages/host/apiproxy/src/api-proxy.ts       | 116 +++---
 packages/host/apiproxy/src/api/index.ts       |   2 +-
 packages/host/apiproxy/src/api/llm.ts         |   4 +-
 .../host/apiproxy/src/api/sessions.schema.ts  |  12 +-
 packages/host/apiproxy/src/api/sessions.ts    |  12 +-
 packages/host/apiproxy/src/index.ts           |  97 +----
 .../apiproxy/tests/api-proxy-approval.spec.ts |   4 +-
 .../apiproxy/tests/api-proxy-blank.spec.ts    |   2 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |  26 +-
 .../apiproxy/tests/api-proxy-commands.spec.ts |   2 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |  17 +-
 .../tests/api-proxy-default-route.spec.ts     | 108 ------
 .../apiproxy/tests/api-proxy-fork.spec.ts     |   4 +-
 .../apiproxy/tests/api-proxy-models.spec.ts   |  26 +-
 .../tests/api-proxy-projections.spec.ts       |   2 +-
 .../apiproxy/tests/api-proxy-question.spec.ts |   2 +-
 .../apiproxy/tests/api-proxy-rename.spec.ts   |   2 +-
 .../apiproxy/tests/api-proxy-search.spec.ts   |   2 +-
 .../tests/api-proxy-subagents.spec.ts         |   2 +-
 .../apiproxy/tests/api-proxy-view.spec.ts     |  10 +-
 .../tests/api-proxy-workspace.spec.ts         |   2 +-
 .../apiproxy/tests/client-handler.spec.ts     |   2 +-
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |   2 +-
 packages/host/apiproxy/tsconfig.json          |   3 +
 .../tool-cordis/src/api-catalog.ts            |  18 +
 .../todo/tool-todo/tests/projection.spec.ts   |   2 +-
 pnpm-lock.yaml                                |  41 ++-
 scripts/gen-cordis-catalog.ts                 |   2 +
 scripts/gen-doc-graphs.ts                     |   8 +
 .../request-response.expected.json            |   2 +-
 .../verify-package-readme-model-experience.ts |   5 +-
 tsconfig.host.json                            |   1 +
 159 files changed, 1508 insertions(+), 1042 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
 create mode 100644 packages/core/agent-default-model/README.i18n.yaml
 create mode 100644 packages/core/agent-default-model/README.md
 create mode 100644 packages/core/agent-default-model/README.zh.md
 create mode 100644 packages/core/agent-default-model/package.json
 create mode 100644 packages/core/agent-default-model/src/index.ts
 create mode 100644 packages/core/agent-default-model/src/invariant.ts
 create mode 100644 packages/core/agent-default-model/tests/agent-default-model.spec.ts
 create mode 100644 packages/core/agent-default-model/tsconfig.json
 create mode 100644 packages/core/agent-default-model/tsdown.config.ts
 rename packages/core/agent/src/{llm-target.ts => model-selection.ts} (55%)
 rename packages/core/agent/tests/{llm-target.spec.ts => model-selection.spec.ts} (86%)
 delete mode 100644 packages/host/apiproxy/tests/api-proxy-default-route.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
index faade67459..f38ba32c11 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.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 .agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
-2026-07-15-llm-model-catalog-and-acp-selection.md: 9edc723b0dfafeaf395eb9325373835138ddbc41
-2026-07-15-llm-model-catalog-and-acp-selection.zh.md: aefd0af3e4de8fac4f5819e0ee279d3343aec6be
+2026-07-15-llm-model-catalog-and-acp-selection.md: 41174209d2c44bedb5dd0615c5f877ecebd43639
+2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 43442487649f7a552d66bd66b64e0e5072f5e00b
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
index 9edc723b0d..41174209d2 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
@@ -34,9 +34,9 @@ The ACP automation transport is not a catalog consumer. Its deployment config su
 
 ### Prompt/request consistency and durability
 
-`installAgentLlmTarget` (in `dsh-agent`) installs scoped `system-prompt/assemble` and `agent/request` listeners for a front-door-owned target. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched.
+`installModelSelection` (in `dsh-agent`) installs scoped `system-prompt/assemble` and `agent/request` listeners for a front-door-owned selection. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched.
 
-The request header remains the durable source of truth. When a selected target is actually used, the existing full `request/header` snapshot records it, and a front door initializes its selection from the folded last request header before falling back to creation options. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state.
+The request header remains the durable source of truth. When a selection is actually used, the existing full `request/header` snapshot records it, and a front door initializes its selection from the folded last request header before falling back to creation options. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
index aefd0af3e4..4344248764 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
@@ -34,9 +34,9 @@ ACP 自动化传输层不是目录消费方。它通过部署配置为新创建
 
 ### 提示词／请求一致性与持久化
 
-`installAgentLlmTarget`（位于 `dsh-agent`）为前门拥有的目标安装 agent 作用域的 `system-prompt/assemble` 与 `agent/request` 监听器。提示词组装在每个步骤对所选组合做一次快照，在下游提示词监听器之后覆写组装出的 `provider` 与 `model` 变量；请求监听器在下游请求监听器之后应用同一快照。因此，发生在异步组装期间的选择会从下一个步骤生效，而不会让提示词文本与路由分裂。其他调用配置字段保持不变。
+`installModelSelection`（位于 `dsh-agent`）为前门拥有的选择安装 agent 作用域的 `system-prompt/assemble` 与 `agent/request` 监听器。提示词组装在每个步骤对所选组合做一次快照，在下游提示词监听器之后覆写组装出的 `provider` 与 `model` 变量；请求监听器在下游请求监听器之后应用同一快照。因此，发生在异步组装期间的选择会从下一个步骤生效，而不会让提示词文本与路由分裂。其他调用配置字段保持不变。
 
-请求头仍是持久化的真源。当所选目标真正被使用时，现有的完整 `request/header` 快照会记录它；前门先从折叠后的最后一个请求头初始化其选择，然后才回退到创建选项。从未被请求使用的选择有意只保留在内存中，因为它从未成为模型可见状态。
+请求头仍是持久化的真源。当某个选择真正被使用时，现有的完整 `request/header` 快照会记录它；前门先从折叠后的最后一个请求头初始化其选择，然后才回退到创建选项。从未被请求使用的选择有意只保留在内存中，因为它从未成为模型可见状态。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 4578e9e268..13da6f9711 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 49ebd642264c663377f16b8669fedc112d3bb6c7
+2026-07-19-gui-layering-and-rpc-protocol.md: ceb8e5db593aef14d6db259f6293381fe83defe2
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: ecd577f7ec5af5d588d0dbf03f94010e00782732
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index 8e020e4fe9..ceb8e5db59 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -31,7 +31,7 @@ Directories layer as follows:
     - **Fetch-arrival plugin packages** (`ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the implementation lives under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle). Cross-plugin consumption of `/client` is type-only; value cooperation goes through cordis services.
 - `apps/` holds the externally exported application shapes, assembled from Client / Host mixtures.
     - `apps/web` (`dsh-frontend`) is the vite application: a thin `main.ts` over the shell surface exported by `dsh-client-web`.
-    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = startHost + webserver + the built `dsh-frontend` dist; `dsh run` = headless in-process calls, zero HTTP.
+    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = Host + webserver + the built `dsh-frontend` dist; `dsh run` = [a direct core Agent/Session front door](2026-08-09-headless-direct-core-front-door.md), with zero Host, HTTP, or browser layer.
     - A future Electron shape reuses the same web client packages over an IPC fetch carrier.
 
 ```
@@ -79,7 +79,7 @@ Packages under `packages/host/*` and `packages/client/*` **must carry the direct
 2. **Write an assembly module under `apps/`**: `startHost()` + a client subclass + the shape's private signal/print/exit semantics; a mixture never becomes a package — assembly is written in the app.
 3. **Import `dsh-host-webserver` only if you need HTTP carriage**, otherwise zero ports.
 
-The two existing shapes are the template: `apps/cli/src/web.ts` (startHost + dist location + startWebServer + signal shutdown) and `headless.ts` (startHost + InProcessApiClient isomorphic direct calls, zero HTTP zero ports). ACP-class protocol bridges do not follow this checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
+The two existing shapes preserve the boundary: the Web shape mounts Host, carrier, and browser composition, while `dsh run` mounts a direct core runner with zero Host, HTTP, or ports. ACP-class protocol bridges do not follow the client-carrier checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
 
 ## Message protocol
 
@@ -215,7 +215,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 | Subclass | Package | doFetch | Purpose |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing — `dsh run` headless is the protocol's second real consumer |
+| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
 | (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
@@ -242,7 +242,7 @@ Every client shape consumes one contract: adding a unary method is a five-step m
 |---|---|
 | Packaging by "product shape" (a web family, an electron family) | What shapes share is host/client capability, not the shape itself; capability-provider layering means a new shape needs zero new packages |
 | A package per mixture (e.g. a standalone headless package) | A mixture has exactly one consumer (its own app); packaging it is ownerless abstraction, while assembly in the app is readable and disposable |
-| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | A second command plane bypasses the contract, losing wire validation/observability/multi-client consistency; ctx keeps exactly two formal uses — front doors and headless event subscription |
+| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | Client shapes require wire validation, observability, and multi-client consistency. Direct headless is a local front door with no client boundary and uses the public Agent/Session seams rather than a client command plane |
 | webserver depending on runtime (saving the handler injection) | Structural-typing injection keeps webserver reusable by sidecars/tests with zero workspace deps; a package dependency would drag assembly knowledge into the carrier layer |
 | Package names without the group prefix (continuing dsh-<tail>) | `dsh-runtime`/`dsh-web-ui` lose their belonging in the flat npm namespace; the cost is one explicit paths entry per package |
 | Reusing the in-repo JSON-RPC 2.0 (dsh-jsonrpc) | Numeric error codes degrade to a single fallback code, contracts get aligned by hand in two copies, and naming drifts without a convention |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 49ebd64226..ecd577f7ec 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -29,7 +29,7 @@ Status: implemented
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
 - `apps/` 作为对外导出的应用形态入口，可以由 Client / Host 混合组装。
     - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳表面之上的一层薄 `main.ts`。
-    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = startHost + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = headless 进程内直调，零 HTTP。
+    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = Host + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = [直接使用核心 Agent／Session 的前门](2026-08-09-headless-direct-core-front-door.md)，不含 Host、HTTP 或浏览器层。
     - 将来的 Electron 形态经由 IPC fetch 载体复用同一套 web client 包。
 
 ```
@@ -77,7 +77,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 2. **在 `apps/` 下写拼装模块**：`startHost()` + 客户端子类 + 该形态私有的信号/打印/退出语义；混合体不建包，拼装写在 app 里。
 3. **需要 HTTP 承载才 import `dsh-host-webserver`**，否则零端口。
 
-现有两形态即模板：`apps/cli/src/web.ts`（startHost + dist 定位 + startWebServer + 信号停机）与 `headless.ts`（startHost + InProcessApiClient 同构直调，零 HTTP 零端口）。ACP 类协议桥不走本清单：它把 core 暴露给外部生态，直接 `ctx.plugin(前门插件)` 挂载、不套 fetch。
+现有两种形态保持这一边界：Web 形态挂载 Host、载体与浏览器组合，而 `dsh run` 挂载直接使用核心服务的 runner，不包含 Host、HTTP 或端口。ACP 类协议桥不遵循 client 载体清单：它把 core 暴露给外部生态，直接通过 `ctx.plugin(前门插件)` 挂载，不套 fetch。
 
 ## 消息协议
 
@@ -213,7 +213,7 @@ export type ResponseValue<K> =
 
 | 子类 | 所在包 | doFetch | 用途 |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
 | （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
@@ -240,7 +240,7 @@ export type ResponseValue<K> =
 |---|---|
 | 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
 | 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 消费型 client 直连 ctx（省 apiproxy 一层） | client 形态需要 wire 校验、观测与多 client 一致性。直接 headless 是没有 client 边界的本地前门，使用公开的 Agent／Session seam，而不是 client 命令面 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
 | 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index 2c1f309a79..2ee0de0625 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.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 .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: 88f94b1f58ae7a3451c7772f4a9ff7d6564254c0
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 5f03dfbb8e5eaeeb52076584721e70ea66a292df
+2026-07-24-web-config-tree-boot-and-transport-layering.md: 496499a691dbca012e5e953cbb6eb1d0bf25b635
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4a83db6f797ad2a0b048ef996d10dbc5ea0a33dd
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index 88f94b1f58..496499a691 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -16,23 +16,23 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the activation audit. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.
 
-**Config sources have one declaration place each.** yml static values are engineering defaults; the profile json (`./.dsh-tmp-profile/config.json`, read-only, never created, cwd-anchored until the `$DSH_HOME` migration) is user config mapped through a static `PROFILE_MAPPINGS` table onto target rows (`provider`/`model` → the `api-gateway` row, `persistenceRoot` → the jsonl row); CLI flags map onto the `webserver` row with a field set disjoint from the json's; env values enter through yml `!!js` expressions, never through the mapping table. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. An unmapped json key fails loud. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
+**Config sources have one declaration place each.** Bundle yml values are engineering defaults, Settings sections are writable user preferences, CLI flags address their owning launcher rows, and env values enter through yml `!!js` expressions. Patches replace a row's config wholesale. The resolved frontend `distIndex` uses that patch channel as an assembly fact. The transport-independent provider/model default belongs to `ctx.agentDefaultModel`; the [direct headless front door](2026-08-09-headless-direct-core-front-door.md) and the Web gateway consume the same state.
 
-**The transport splits five ways.** `dsh-host-apiproxy` upgraded to the gateway plugin (`api-gateway` row): default-exports `ApiProxyService`, config `{provider, model}`, provides `ctx.apiProxy`, transport-agnostic and registers no routes — `createApiProxy` moved here from the retired runtime package. `dsh-host-webserver` shrank to a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, per-request failures answer 400 and log without exiting, and knows no harness concepts. The connection node half owns the binding: it injects both services and registers `toFetchHandler(ctx.apiProxy)` under the `/api` prefix — future IPC carriers swap connection's transport while the gateway stays untouched. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns the graph: incremental per-package scanning (no full-rescan code path — `internal/plugin` marks the fiber's entry name dirty, a flush reconciles each name against live entries, package metadata including negative verdicts is cached forever, re-hashing is reachable only through `rebuilt(id)`), the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload: `fs.watchFile` stat-polling driven by `onGraphChanged` membership, and the `/plugins/events` SSE route.
+**The transport splits five ways.** `dsh-host-apiproxy` is the gateway plugin (`api-gateway` row): it default-exports `ApiProxyService`, configures only `{workspaceRoot?}`, consumes the base layer's front-door-neutral `ctx.agentDefaultModel`, provides `ctx.apiProxy`, remains transport-agnostic, and registers no routes. `dsh-host-webserver` is a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, answers per-request failures with 400 and logging, and knows no harness concepts. The connection node half owns the `/api` binding from `ctx.apiProxy` through `toFetchHandler`. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns incremental package scanning, the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload through `fs.watchFile` membership and the `/plugins/events` SSE route.
 
 **Package export discipline.** The modules package exposes exactly `.` (node half) and `./client` (the complete browser half: `ClientModuleSystem`, `parseBootManifest`, the adoption plugin face) — no bespoke subpaths; wire types re-export through the root for host-side consumers. The adoption handshake: the kernel writes the constructed instance to `window.__DSH_MODULES__` before cordis exists; the `./client` apply reads the slot (missing = loud throw) and provides `ctx.modules`.
 
 ## Consequences
 
 - Recomposing a web deployment is a yml/patch edit; the retired pieces (`mountWebPlugins`, `CLIENT_PACKAGES`, `createHostWebPluginRegistry`, `startWebServer`, the webserver's graph/SSE/api knowledge) are deleted.
-- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. The profile write path, the `$DSH_HOME` profile relocation, and IPC carriers remain recorded deferrals.
+- [Headless is a direct core front door](2026-08-09-headless-direct-core-front-door.md): its shipped profile contains the shared base Agent capabilities and omits Host, HTTP, Web, and browser layers. The transport split in this note is the browser surface's contract.
 - A TypeScript pitfall worth remembering: a `declare module 'cordis'` augmentation in a file with **no cordis import** is demoted to a standalone module declaration and silently shatters the program-wide `Context` merge (`ctx.on`/`ctx.effect` vanish across the program). Anchor with `import type {} from 'cordis'`.
 
 ## Alternatives considered
 
 | Rejected | One-line reason |
 |---|---|
-| Dedicated `dsh-host-profile` receiver package | The profile json is consumed at patch time; the only runtime consumer of `{provider, model}` is the gateway itself — its config is the receiver |
+| Dedicated `dsh-host-profile` receiver package | User model state belongs to the Settings-backed `ctx.agentDefaultModel`; an extra Host receiver would duplicate ownership and exclude direct front doors |
 | Runtime `assembly` shim plugin providing an `apiHandler` service | Existed only because `createApiProxy` lived in runtime; moving it into apiproxy made the gateway self-hosting, and `toFetchHandler` is a pure function the binding side calls |
 | Full-rescan + incremental scan coexisting | Two implementations, two semantics; the single per-package path covers the activation pass too |
 | A bespoke `./impl` export on the modules package | Non-uniform export surface; the standard `./client` carries the whole browser half |
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index 5f03dfbb8e..4a83db6f79 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -16,23 +16,23 @@ Status: implemented
 
 **boot 胶水由两个类组成。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有那些必须独立于 cordis、提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest（元数据清单）、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加 activation audit。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐一创建图行、settle、sweep。
 
-**每个配置源有唯一声明位置。** yml 静态值是工程默认；profile json（`./.dsh-tmp-profile/config.json`，只读、绝不创建、暂锚 cwd 直至 `$DSH_HOME` 迁移）是用户配置，经静态 `PROFILE_MAPPINGS` 表映射到目标行（`provider`/`model` → `api-gateway` 行，`persistenceRoot` → jsonl 行）；CLI（命令行界面）flags 映射到 `webserver` 行、字段集与 json 不相交；env 值经 yml `!!js` 表达式进入，绝不进映射表。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。未映射的 json 键 fail loud。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
+**每个配置源有唯一声明位置。** 组合包 yml 值是工程默认，Settings 分节是可写的用户偏好，CLI（命令行界面）flags 面向其归属的启动器配置行，env 值则通过 yml `!!js` 表达式进入。patch 会整体替换一行的 config。解析后的前端 `distIndex` 通过同一条 patch 通道作为组装事实传递。与传输无关的提供方／模型默认值归 `ctx.agentDefaultModel` 所有；[直接 headless 前门](2026-08-09-headless-direct-core-front-door.md)与 Web 网关消费同一份状态。
 
-**传输五分。** `dsh-host-apiproxy` 升格网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，config `{provider, model}`，provide `ctx.apiProxy`，传输无关、不注册路由——`createApiProxy` 从已退役的运行时包迁入。`dsh-host-webserver` 缩成朴素路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败答 400 并记日志，不退出进程，不认识任何 harness 概念。connection node 半拥有绑定：inject 两个服务，把 `toFetchHandler(ctx.apiProxy)` 注册在 `/api` 前缀下——将来 IPC 载体只换 connection 的传输，网关零改动。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有图：单包增量扫描（无全量重扫路径——`internal/plugin` 把 fiber 的 entry 名标脏，flush 逐名对账 live entries，包括否定结论在内的包元数据会永久缓存，重哈希唯一入口 `rebuilt(id)`）、bundle 路由、index tap、`onRebuilt`/`onGraphChanged` 通知。HMR node 半拥有开发期重载：`fs.watchFile` stat 轮询、watch 集合跟随 `onGraphChanged`、`/plugins/events` SSE 路由。
+**传输五分。** `dsh-host-apiproxy` 是网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，只配置 `{workspaceRoot?}`，消费 base 层不偏向特定前门的 `ctx.agentDefaultModel`，provide `ctx.apiProxy`，保持传输无关且不注册路由。`dsh-host-webserver` 是朴素的路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败时答 400 并记日志，且不认识任何 harness 概念。connection node 半拥有从 `ctx.apiProxy` 经 `toFetchHandler` 绑定到 `/api` 的逻辑。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有单包增量扫描、bundle 路由、index tap 与 `onRebuilt`/`onGraphChanged` 通知。HMR node 半通过 `fs.watchFile` membership 与 `/plugins/events` SSE 路由拥有开发期重载。
 
 **包出口纪律。** modules 包只暴露 `.`（node 半）与 `./client`（完整浏览器半：`ClientModuleSystem`、`parseBootManifest`、收编插件面）——不设专用子路径；wire 类型经根出口 re-export 给 host 侧消费方。收编握手：内核在 cordis 之前把建好的实例写入 `window.__DSH_MODULES__`；`./client` 的 apply 读取该槽位（缺少时显式抛错）并 provide `ctx.modules`。
 
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。profile 写入路径、profile 迁 `$DSH_HOME`、IPC 载体仍为挂账项。
+- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的契约。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## 考虑过的替代方案
 
 | 弃案 | 一行理由 |
 |---|---|
-| 专门的 `dsh-host-profile` 受体包 | profile json 在 patch 阶段消费完；`{provider, model}` 的唯一运行时消费方是网关自己——受体即网关 config |
+| 专门的 `dsh-host-profile` 受体包 | 用户模型状态归 Settings 支撑的 `ctx.agentDefaultModel` 所有；额外的 Host 受体会重复归属，并排除直接前门 |
 | 运行时里的 `assembly` 垫层插件（provide `apiHandler`） | 它的存在只因 `createApiProxy` 住运行时；本体迁入 apiproxy 后网关自持插件身份，且 `toFetchHandler` 是绑定方自己调的纯函数 |
 | 全量重扫与增量扫描并存 | 两条实现两份语义；单包路径足以覆盖激活初扫 |
 | modules 包特设 `./impl` 出口 | 出口面不统一；标准 `./client` 承载完整浏览器半 |
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index 3e1d038514..342bcac5e0 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: 8613e600ad633818abb4319e614230340c3b3876
-2026-08-05-profile-plugin-bundles.zh.md: 03a771364c4f3262801f28e68b96ec5de633e5ec
+2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
+2026-08-05-profile-plugin-bundles.zh.md: a186a27aff9ff3b4202ce5327f88637caa52b11d
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index 8613e600ad..f183fc5ff5 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -12,7 +12,7 @@ The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.y
 
 Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a `package.json` (pnpm-managed out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list) and a user `cordis.patch.yml`. A **bundle** is an npm package declaring `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the two manifest kinds live under distinct `dsh.profile` / `dsh.bundle` keys so a package.json states which role it plays. The tree composes over an empty root by applying each bundle's patch in `dsh.profile.bundles` order, then the user layer, then `--patch` overlays, then flag patches — one `applyEntryPatches` call, identical for boot, flag derivation, and `--dump-config`.
 
-The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile, while generic `dsh --profile <name>` boots without a task; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
+The shipped bundles are `@deepseek-ai/dsh-base` (shared core rows), `@deepseek-ai/dsh-web-app` (browser Host rows and Web runtime glue), and `@deepseek-ai/dsh-headless` (a direct one-shot runner over base, without web-app). `dsh web` is the Web-flag alias for `--profile web`; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile; generic `dsh --profile <name>` boots without a task. Patch overlays use `--patch`. `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` with installed bundle declarations; a package without a bundle declaration remains a plain dependency. [Headless as a direct core front door](2026-08-09-headless-direct-core-front-door.md) owns the headless composition contract.
 
 The [`dsh run` command decision](../feature/2026-08-08-dsh-run-headless-command.md) owns the one-shot grammar; this note owns the profile composition it selects.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 03a771364c..a186a27aff 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
-已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
+随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合契约。
 
 [`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
new file mode 100644
index 0000000000..cab1c8e338
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.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 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
+2026-08-09-headless-direct-core-front-door.md: cae17970633d6eda9d4f823118827ee2bfe32abf
+2026-08-09-headless-direct-core-front-door.zh.md: 8ff5e870b7f0fbc82065c6c55b4635cdc586036c
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
new file mode 100644
index 0000000000..cae1797063
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
@@ -0,0 +1,44 @@
+# Agent Note: headless is a direct core front door
+
+Status: implemented
+
+English | [中文](2026-08-09-headless-direct-core-front-door.zh.md)
+
+## Problem
+
+The `headless` product contract is one local task with final assistant text on stdout, a success-sensitive exit code, empty stderr on success, and no listening port. A composition containing Workspace Host services, ApiProxy, HTTP, the Web runtime, or browser plugins contradicts that contract and makes local completion depend on an unrelated transport tree.
+
+The direct front door still needs the same deployment model state as Web-created Agents. A separate provider/model default would give one deployment two answers, while deriving completion before the Agent and Session persistence are quiescent permits stdout and the exit code to observe incomplete state.
+
+## Decision
+
+The shipped `headless` profile contains `dsh-base` and `dsh-headless`. The headless bundle supplies its persona and tool mode, disables HMR, mounts the Code Mode worker explicitly, and inserts `headless-runner`. Its tree contains no `@deepseek-ai/dsh-host-*` package, ApiProxy, HTTP server, Web runtime, or browser client. Code Mode and Session persistence are one-shot Agent capabilities independent of Web presentation.
+
+`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. Unexpected driver failures use stderr and exit 1.
+
+`@deepseek-ai/dsh-agent-default-model` owns the transport-independent default used for an Agent without a session-local selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers the `agent-default-model` Settings section. Composition config supplies `{provider, model}`; user settings may also supply `reasoningEffort`. `currentSelection()` returns the live complete selection and `saveSelection()` writes it as a complete section, so a selection without an effort clears any stored effort. `dsh-base` supplies the composition entry. Direct and ApiProxy front doors consume this service; ApiProxy alone owns session-local precedence, model validation, and persistence of accepted Web selections.
+
+`loadProfile` recognizes the exact installation-owned headless tuple (`dsh-base`, `dsh-web-app`, `dsh-headless`) and normalizes it to the shipped headless template while preserving every other manifest field. Extra, missing, or reordered bundle lists are user-owned and remain untouched.
+
+This note owns the headless transport and completion contracts. [`dsh run` owns one-shot headless execution](../feature/2026-08-08-dsh-run-headless-command.md) owns the command grammar, [GUI layering and RPC protocol](2026-07-19-gui-layering-and-rpc-protocol.md) owns browser gateway boundaries, [web config-tree boot and transport layering](2026-07-24-web-config-tree-boot-and-transport-layering.md) owns the Web tree, and [the default model follows the picker](../feature/2026-08-07-default-model-follows-the-picker.md) owns persistence of the shared Agent default.
+
+## Verification
+
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshot drives `dsh run` through a replayed tool round trip and records direct user-message provenance. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+
+## Alternatives considered
+
+| Alternative | Contract mismatch |
+|---|---|
+| Keep `dsh-web-app` but suppress its observation line | The process still opens a port and carries the Host, Web, and browser trees. |
+| Build a Host-only one-shot bundle around ApiProxy | ApiProxy is a client protocol gateway; a local one-shot front door has no client boundary. |
+| Use `InProcessApiClient` for product-level protocol coverage | Product execution would depend on an unrelated protocol solely to exercise that protocol. |
+| Give headless a separate provider/model config | Direct and Web creation would have independent defaults and persistence. |
+| Omit Code Mode and Session persistence | Both capabilities belong to one-shot Agent execution rather than Web presentation. |
+| Normalize every tuple containing Web and headless bundles | Bundle lists are an extension surface; only the exact installation-owned tuple is safe to classify. |
+
+## Consequences
+
+`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message has direct user provenance and therefore carries no ApiProxy `rpcId`.
+
+ApiProxy carrier coverage stays in the ApiProxy package. Custom one-shot profiles may include Host or Web bundles explicitly, while the shipped profile and the recognized installation-owned tuple are Web-free.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
new file mode 100644
index 0000000000..8ff5e870b7
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -0,0 +1,44 @@
+# Agent Note: headless 是直接使用核心服务的入口
+
+Status: implemented
+
+[English](2026-08-09-headless-direct-core-front-door.md) | 中文
+
+## 问题
+
+`headless` 的产品契约是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一契约，也使本地完成状态依赖无关的传输树。
+
+直接前门仍需要与 Web 所创建 Agent 相同的部署模型状态。独立的提供方／模型默认值会让同一部署产生两种答案，而在 Agent 与会话持久化完全停稳之前推导完成状态，会让 stdout 与退出状态观察到不完整状态。
+
+## 决策
+
+随附的 `headless` profile 包含 `dsh-base` 与 `dsh-headless`。headless 组合包提供自身的 persona 与工具模式、禁用 HMR（热模块替换）、显式挂载 Code Mode worker，并插入 `headless-runner`。其插件树不包含任何 `@deepseek-ai/dsh-host-*` 包、ApiProxy、HTTP server、Web 运行时或浏览器客户端。Code Mode 与会话持久化均为独立于 Web 呈现的一次性 Agent 能力。
+
+`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。驱动器的意外失败写入 stderr 并以 1 退出。
+
+`@deepseek-ai/dsh-agent-default-model` 拥有与传输无关的默认值，供没有会话级选择的 Agent 使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel` 并注册 `agent-default-model` Settings 分节。组合配置提供 `{provider, model}`，用户设置还可以提供 `reasoningEffort`。`currentSelection()` 返回当前的完整选择，`saveSelection()` 则写入完整分节，因此不含强度的选择会清除已存强度。`dsh-base` 提供组合条目。直接前门与 ApiProxy 前门均消费该服务；只有 ApiProxy 负责会话级优先级、模型校验与已接受 Web 选择的持久化。
+
+`loadProfile` 识别安装过程拥有的精确 headless 元组（`dsh-base`、`dsh-web-app`、`dsh-headless`），将其规范化为随附的 headless 模板，并保留 manifest（元数据清单）的其他所有字段。带额外项、缺少项或顺序不同的组合包列表归用户所有，保持不变。
+
+本 Agent Note 负责 headless 的传输与完成契约。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
+
+## 验证
+
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，并记录直接用户消息的来源。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+
+## 考虑过的替代方案
+
+| 替代方案 | 契约不匹配之处 |
+|---|---|
+| 保留 `dsh-web-app`，但隐藏观察行 | 进程仍会打开端口并携带 Host、Web 与浏览器插件树。 |
+| 围绕 ApiProxy 构建纯 Host 一次性组合包 | ApiProxy 是客户端协议网关，而本地一次性前门没有客户端边界。 |
+| 使用 `InProcessApiClient` 实现产品级协议覆盖 | 产品执行会仅为测试无关协议而依赖该协议。 |
+| 为 headless 单独提供提供方／模型配置 | 直接创建与 Web 创建会拥有彼此独立的默认值和持久化。 |
+| 省略 Code Mode 与会话持久化 | 两项能力都属于一次性 Agent 执行，而不是 Web 呈现。 |
+| 规范化所有包含 Web 与 headless 组合包的元组 | 组合包列表是扩展面；只有精确的安装过程所属元组可以安全分类。 |
+
+## 后果
+
+`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息直接来自用户，因此不携带 ApiProxy `rpcId`。
+
+ApiProxy 载体覆盖保留在 ApiProxy 包中。自定义一次性 profile 可以显式包含 Host 或 Web 组合包；随附 profile 与可识别的安装过程所属元组均不含 Web。
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
index 77104f258e..626d98b3c8 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.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 .agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
-2026-07-24-web-session-model-selector.md: 05e923fb3b5df72485ffb8d6ff5aa0104b19a8a0
-2026-07-24-web-session-model-selector.zh.md: c1fd59ada0340a984ddf4a9dcc4c357f9609acb1
+2026-07-24-web-session-model-selector.md: 78017b14a806f8e609a85e340094cd2a349d47e1
+2026-07-24-web-session-model-selector.zh.md: 87a342721f5e47f5bcedfafb578eb6916101d2f5
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
index 05e923fb3b..78017b14a8 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
@@ -6,17 +6,17 @@ English | [中文](2026-07-24-web-session-model-selector.zh.md)
 
 ## Problem
 
-The Web conversation displayed and sent through the Host's fixed provider/model route without exposing that route or letting a user change it. The TUI already had a session-local route target, but copying its presentation or hardcoding DeepSeek models in the browser would split model discovery and step-boundary semantics across front doors. A switch made while a response is running also needs one atomic boundary: prompt variables and request routing cannot observe different targets.
+The Web conversation needs a visible, mutable session model selection sourced from the Host. Copying TUI presentation or hardcoding DeepSeek models in the browser would split model discovery and step-boundary semantics across front doors. A switch made while a response is running also needs one atomic boundary: prompt variables and request routing cannot observe different selections.
 
 ## Decision
 
-The Web Host reuses `installAgentLlmTarget` for every created or resumed agent. The provider/model/reasoning target starts from the latest `request/header` when the session has used a model, otherwise from the Host default route. `session.selectModel` changes the session-local mutable target, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed target persists through the existing full `request/header` snapshot, while a choice that has not reached a request remains process-local.
+The Web Host installs `ModelSelection` for every created or resumed Agent. The provider/model/reasoning selection comes from the latest `request/header` when the session has used a model, otherwise from `ctx.agentDefaultModel`. `session.selectModel` assigns the session-local selection, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed selection persists through the full `request/header` snapshot, while a choice that has not reached a request remains process-local.
 
-The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently on purpose: the TUI still renders the unlisted current model as its own row and marks it current, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so a target the user just deleted should read as a decision to make rather than a selection to keep; the TUI, which only picks from what exists, has no such edit to reconcile. The cost is real and accepted — a Web composer showing the unset label can still send to the routed target — and the divergence is deliberate, not a missed migration. Exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target.
+The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently: the TUI renders the unlisted current model as its own row, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so an absent row presents a selection decision; the TUI only picks from existing rows. A Web composer showing the unset label can still send with its current routable selection. Exact resolution decides whether a provider/model pair and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before assigning the selection.
 
-The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete target, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so older responses cannot replace a newer result; connection reset discards the process-local projection before restoring the Host target. Failures retain the previous current target and usable groups.
+The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete `ModelSelection`, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so an older response cannot replace a newer result; connection reset discards the process-local projection before restoring the Host selection. Failures retain the previous selection and usable groups.
 
-`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current target is absent from the groups, the trigger instead displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model replaces the complete target through the existing selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.
+`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current selection is absent from the groups, the trigger displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model assigns the complete selection through the shared selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.
 
 The production browser roster is assembled from `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml`; the model feature is one `dshClient` row rather than a package hardcoded in Web boot code. Its package manifest orders it after the runtime and command feature, while Cordis service injection waits for the conversation slot before registering the composer occupant.
 
@@ -26,18 +26,18 @@ The production browser roster is assembled from `apps/cli/config/base.cordis.yml
 
 **Hardcode the current DeepSeek catalog in the Web client.** This would drift from registered adapters and exclude deployment-owned providers. The LLM registry remains the source of provider and model metadata, including partial lookup failures.
 
-**Keep `High`/`Max` as client-local UI state.** Static DeepSeek labels cannot represent `off`, pi-ai provider vocabularies, adapter defaults, validation, resume, or the next provider request. Exact-model metadata owns the selectable vocabulary, and the session target owns the selected id.
+**Keep `High`/`Max` as client-local UI state.** Static DeepSeek labels cannot represent `off`, pi-ai provider vocabularies, adapter defaults, validation, resume, or the next provider request. Exact-model metadata owns the selectable vocabulary, and the session selection owns the selected id.
 
-**Make the selection a global default.** A global mutation would unexpectedly redirect other open conversations. The target belongs to one live session, while Host configuration remains the default for sessions without a logged request.
+**Use only a global default.** A default mutation would unexpectedly redirect blank conversations. The session selection belongs to one live session, while `ctx.agentDefaultModel` supplies the fallback for sessions without a logged request.
 
-**Reject changes while an agent is running.** The shared atomic target already separates the assembled step from the next selection. Keeping the selector available lets the user prepare the following step without altering the in-flight request.
+**Reject changes while an Agent is running.** The atomic selection snapshot separates the assembled step from the next selection. Keeping the selector available lets the user prepare the following step without altering the in-flight request.
 
 **Persist every click as a new session event.** A choice is not model-visible until prompt assembly consumes it. Persisting unused UI intent would add a durable event that does not reconstruct a model request; the existing `request/header` records the first request that actually uses the route.
 
 ## Consequences
 
-Any Host-backed Web conversation, including a blank session, can switch among dynamically discovered provider groups and adapter-owned reasoning levels without displaying duplicated `provider/model` labels. The current consumed target survives resume and reconnect; catalog names remain presentation-only, while selection and persistence use provider/model/effort ids. A provider catalog or exact-metadata outage degrades only that group. Route changes can reduce provider-side cache reuse, but the selector adds no prompt content and does not disturb the in-flight step. A model without reasoning metadata has no Effort row.
+Any Host-backed Web conversation, including a blank session, can switch among dynamically discovered provider groups and adapter-owned reasoning levels without displaying duplicated `provider/model` labels. The consumed selection survives resume and reconnect; catalog names remain presentation-only, while selection and persistence use provider/model/effort ids. A provider catalog or exact-metadata outage degrades only that group. Provider/model changes can reduce provider-side cache reuse, but the selector adds no prompt content and does not disturb the in-flight step. A model without reasoning metadata has no Effort row.
 
 ## Testing
 
-Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-target submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for a removed row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture removes the active catalog row and pins the fallback before choosing a replacement.
+Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-selection submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for an absent row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture omits the active catalog row and pins the fallback before choosing a replacement.
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
index c1fd59ada0..87a342721f 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
@@ -6,17 +6,17 @@ Status: implemented
 
 ## 问题
 
-Web 对话原本通过 Host 固定的提供方与模型路由显示并发送消息，既不呈现该路由，也不允许用户更改。TUI 已经具备会话级的路由目标，但如果照搬其呈现方式，或在浏览器中硬编码 DeepSeek 模型，就会让模型发现逻辑和步骤边界语义分散到不同前门中。响应运行期间发生的切换还需要一个原子边界：提示词变量与请求路由不能观测到不同的目标。
+Web 对话需要一项由 Host 提供、可见且可更改的会话模型选择。如果照搬 TUI 的呈现方式，或在浏览器中硬编码 DeepSeek 模型，就会让模型发现逻辑和步骤边界语义分散到不同前门中。响应运行期间发生的切换还需要一个原子边界：提示词变量与请求路由不能观测到不同的选择。
 
 ## 决策
 
-Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlmTarget`。如果会话已经使用过模型，提供方／模型／推理（reasoning）目标从最新的 `request/header` 开始；否则采用 Host 默认路由。`session.selectModel` 会更改会话级可变目标，提示词组装则将该目标与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一个实际采用的目标通过现有的完整 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。
+Web Host 为每个新建或恢复的 Agent 安装 `ModelSelection`。如果会话已经使用过模型，提供方／模型／推理（reasoning）选择来自最新的 `request/header`；否则来自 `ctx.agentDefaultModel`。`session.selectModel` 会赋值会话级选择，提示词组装则将它与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一个实际采用的选择通过完整的 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。
 
-会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门有意对这一状态给出不同回答：TUI 仍把未列出的当前模型渲染为独立一行并标记为当前，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 正是编辑目录所在的前门，因此用户刚刚删除的目标应当读作一个有待作出的决定，而不是一项可以保留的选择；TUI 只在已存在的模型中挑选，没有这类编辑需要调和。这一代价真实存在且已被接受——显示未设置标签的 Web composer 仍会发送到实际路由的目标——这一分歧是有意为之，而不是一处遗漏的迁移。精确解析决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。
+会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门对这一状态给出不同回答：TUI 把未列出的当前模型渲染为独立一行，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 是编辑目录的 surface，因此缺席的目录行代表一项待作出的选择；TUI 只从现有行中选择。显示未设置标签的 Web composer 仍可以使用当前可路由选择发送消息。精确解析决定提供方／模型组合与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在赋值该选择前具体化适配器配置的默认值。
 
-浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整目标、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 目标。失败时保留先前的当前目标和可用分组。
+浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整的 `ModelSelection`、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 选择。失败时保留先前的选择和可用分组。
 
-`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前目标不在分组中时，触发器改为显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过现有选择路径替换完整目标。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。
+`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前选择不在分组中时，触发器显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过共享的选择路径赋值完整选择。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。
 
 生产环境的浏览器名册由 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 共同组装；模型功能对应其中一行 `dshClient` 配置项，而不是 Web boot 代码中硬编码的包。其包 manifest（元数据清单）将加载顺序置于运行时与命令功能之后；Cordis 服务注入则等待 conversation slot 可用，再注册 composer 占用方。
 
@@ -26,18 +26,18 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm
 
 **在 Web 客户端中硬编码当前 DeepSeek 目录。** 该目录会与已注册适配器发生偏离，也会排除部署自有的提供方。LLM 注册表继续作为提供方与模型元数据的真源，也负责呈现部分查询失败。
 
-**将 `High`／`Max` 保留为客户端本地 UI 状态。** 静态 DeepSeek 标签无法覆盖 `off`、pi-ai 的提供方词汇、适配器默认值与校验，也不能参与恢复或下一次提供方请求。精确模型元数据拥有可选词汇，会话目标则拥有已选择的 ID。
+**将 `High`／`Max` 保留为客户端本地 UI 状态。** 静态 DeepSeek 标签无法覆盖 `off`、pi-ai 的提供方词汇、适配器默认值与校验，也不能参与恢复或下一次提供方请求。精确模型元数据拥有可选词汇，会话选择则拥有已选择的 ID。
 
-**将选择设为全局默认值。** 全局变更会意外改道其他已打开的对话。目标仅属于一个实时会话；对于没有已记录请求的会话，Host 配置仍是默认值。
+**只使用全局默认值。** 默认值变更会意外改道空白对话。会话选择仅属于一个实时会话；对于没有已记录请求的会话，`ctx.agentDefaultModel` 提供回退值。
 
-**agent 运行期间拒绝更改。** 共享原子目标已经将当前组装步骤与下一次选择分离。保持选择器可用，可以让用户为下一个步骤预先选择模型，而不会改变正在执行的请求。
+**Agent 运行期间拒绝更改。** 原子选择快照将当前组装步骤与下一次选择分离。保持选择器可用，可以让用户为下一个步骤预先选择模型，而不会改变正在执行的请求。
 
 **将每次点击作为新的会话事件持久化。** 只有提示词组装采用某项选择后，该选择才对模型可见。持久化尚未使用的 UI 意图，会增加一个无法重建模型请求的持久事件；现有 `request/header` 会记录首次实际使用该路由的请求。
 
 ## 影响
 
-任何由 Host 支撑的 Web 对话（包括空白会话）都可以在动态发现的提供方分组和适配器持有的推理级别之间切换，而无需显示重复的 `provider/model` 标签。当前实际采用的目标会在恢复和重连后保留；目录名称仅用于呈现，而选择和持久化使用提供方／模型／推理强度 ID。某个提供方的目录或精确元数据不可用时，只有相应分组会降级。路由变更可能降低提供方侧的缓存复用率，但选择器不会添加任何提示词内容，也不会干扰正在执行的步骤。没有推理元数据的模型不显示 Effort 行。
+任何由 Host 支撑的 Web 对话（包括空白会话）都可以在动态发现的提供方分组和适配器持有的推理级别之间切换，而无需显示重复的 `provider/model` 标签。实际采用的选择会在恢复和重连后保留；目录名称仅用于呈现，而选择和持久化使用提供方／模型／推理强度 ID。某个提供方的目录或精确元数据不可用时，只有相应分组会降级。提供方／模型变更可能降低提供方侧的缓存复用率，但选择器不会添加任何提示词内容，也不会干扰正在执行的步骤。没有推理元数据的模型不显示 Effort 行。
 
 ## 测试
 
-Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
+Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整选择提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及缺席模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会省略活动目录行，在选择替代模型之前固定该回退。
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
index f513e90666..0f28e14222 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.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 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
-2026-08-07-default-model-follows-the-picker.md: d20f0ab8b8c8bd19f596e6ef73f0a58d96c24d38
-2026-08-07-default-model-follows-the-picker.zh.md: 0d2821cb63407fe766e6fe3d36de31d9fc6f1c13
+2026-08-07-default-model-follows-the-picker.md: ed7e7a424d2cacadea890506fd9150ffdf7a993c
+2026-08-07-default-model-follows-the-picker.zh.md: 52308518f06a140a9f79440e48229356bc61dca5
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
index d20f0ab8b8..ed7e7a424d 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
@@ -6,38 +6,42 @@ English | [中文](2026-08-07-default-model-follows-the-picker.zh.md)
 
 ## Problem
 
-The route a new session started from was frozen into the gateway's composition entry (`api-gateway` in the web-app bundle patch). Switching models in a conversation reached that conversation only: the next session went back to the shipped default, and the only way to change it was to hand-edit a `cordis.yml` row and restart. There was no user-settings tier between the composition and the per-session choice.
+A session model picker and a deployment default are two layers of the same preference. If the picker affects only its addressed session, the next blank session can select a different model with no user-facing way to align the default. If the default lives inside a Host gateway, direct Agent front doors cannot share it without depending on Host or duplicating state.
+
+Reasoning effort makes the persistence shape significant: a model selection without an effort must clear a stored effort, or the next Agent may apply an effort that its selected model does not accept.
 
 ## Decision
 
-`ApiProxyService` registers its `{provider, model, reasoningEffort?}` slice as the `api-gateway` settings section: the composition entry is the `base` layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` stays outside the section — a launcher fact, not a preference. `reasoningEffort` is the mirror case: it lives in the section but NOT in the plugin config, because the seam merges the user layer over the composition entry per field and an absent key cannot override a present one. A composition-set effort would therefore survive every later switch to a model without one — precisely the stranding the wholesale `replace` exists to prevent. Effort is a per-model fact anyway; a deployment default for it belongs on the adapter profile, which resolves per model.
+`AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers `{provider, model, reasoningEffort?}` as the `agent-default-model` Settings section. Its `{provider, model}` composition entry is the base layer and `settings.yaml` supplies the user layer. The service is front-door-neutral, so direct creation and ApiProxy-backed creation share one default ([headless direct core front door](../architecture/2026-08-09-headless-direct-core-front-door.md)). `workspaceRoot` remains ApiProxy config because it is a Host launcher fact rather than model state.
 
-`session.selectModel` records an accepted switch as the new default. There is no separate gesture: switching models in the composer IS how the default is chosen. The write is `replace`, not `update` — switching to a model with no reasoning effort has to clear a stored one, and a merged patch would strand it for the next session to fail on. A storage failure is logged without undoing the switch, which already applies to its own session, and a deployment with no settings provider keeps the entry with the switch staying process-local.
+`reasoningEffort` belongs to the Settings section but not to the plugin config. Settings layers merge by field, so a configured effort would survive a user selection that omits it. `saveSelection()` instead writes the complete user section; absence therefore clears a stored effort. A deployment-wide effort default belongs to the adapter profile, which resolves it per model.
 
-`ApiProxyDefaults` carries `defaultTarget()` and `persistDefaultTarget()` closures instead of flat `provider`/`model` fields, so `createApiProxy` needs no knowledge of the settings seam.
+`session.selectModel` applies an accepted `ModelSelection` to its session and calls `saveDefaultModelSelection()` for the shared Agent default. A storage failure is logged without undoing the session selection. A deployment with no settings provider retains the composition entry and keeps the accepted selection only in that session.
 
-`targetFor` resolves its tiers on **every** read rather than seeding a ref once: an explicit selection in this process, else the session's own latest logged `request/header`, else the live default. Both directions depend on the re-read. A session that has run a turn derives from its log forever after, so changing the default never retargets it. A session still blank starts from a default saved after it was created — which matters because New Session reuses a blank session rather than minting another, so a creation-time seed would show the superseded model in exactly the flow the feature exists for.
+`ApiProxyDefaults` carries `defaultModelSelection()` and `saveDefaultModelSelection()` closures, so `createApiProxy` has no dependency on the Settings seam. `ApiProxyService` wires them to `ctx.agentDefaultModel.currentSelection()` and `ctx.agentDefaultModel.saveSelection()`.
 
-The stored route is not validated against the registry. A default naming a route the Models page has since removed still reaches `session.models` as `current`, matching no advertised group — which is what makes the composer seat's existing fallback prompt for a selection instead of naming a model the deployment cannot reach.
+`selectionFor(agent)` resolves its tiers on every read: a process-local session selection, otherwise the session's latest logged `request/header`, otherwise the live Agent default. A session with a logged request remains bound to that durable selection. A blank session observes the current default even when it was created before the preference was saved; this matches the New Session surface, which may reuse a blank session.
+
+The stored selection does not require catalog membership. A provider route may serve a model omitted from its advisory catalog. `session.models` therefore reports the stored selection independently of advertised groups and separately reports whether an adapter serves its provider.
 
 ## Consequences
 
-`ApiProxyDefaults` changed shape, updating ~40 test construction sites. `host.describe` now reports the live default rather than a captured one, which is what it always meant. `settings.yaml` gains an `api-gateway:` section the moment a user switches models; the `api-gateway` namespace is deliberately NOT added to the gateway's exposed-namespace allowlist, so the Settings page neither reads nor writes it — the model picker is its editor.
+`host.describe` reports the live Agent default. A successful model switch stores an `agent-default-model:` section in `settings.yaml`. The gateway does not expose that namespace through its Settings-page allowlist; the model picker is its editor.
 
-## Follow-up: blocking a session that cannot send
+## A session that cannot send
 
-A default naming a route the Models page has since removed leaves the composer saying "Select model" while the input still accepts a message, which then fails inside the adapter mid-turn. Two changes close it.
+`session.prompt` refuses with `model-unavailable` before opening a turn when no adapter serves the session's selected provider. This method is the enforcement boundary; a disabled composer is only a client affordance.
 
-The Host refuses. `session.prompt` checks whether an adapter serves the session's route and answers `model-unavailable` before opening a turn. This is the enforcement boundary: a client that disables its composer is an affordance, and the method stays callable regardless.
+`session.models` reports `routable`. The ui-model plugin projects an unroutable selection through `ctx.conversation.blocks`, and the composer becomes inert while leaving the model seat available. An unknown client-side routability state, including an initial or failed catalog load, does not block input.
 
-The composer goes inert. `session.models` reports `routable`, and ui-model pushes a block through the new `ctx.conversation.blocks` registry; the bar renders the same disabled textarea it already renders without a workspace, with the blocker's own localized reason as the placeholder — except the model seat, which a block deliberately leaves live, because choosing a model is how the user clears it. The push direction is forced — ui-model already depends on ui-conversation, so ui-conversation cannot read it back.
-
-The gate is `routable`, NOT "the current target matches no advertised group". Catalog membership is advisory by design: a route serving a model it stopped advertising is absent from the groups yet perfectly usable, and blocking there would break a supported configuration (a narrowed `models` list over a live route). `routable` is also three-valued on the client — `null` before the first load or after a failed one never blocks, so a slow or unreachable Host cannot lock a working composer.
+Routability is distinct from catalog membership. A live provider route can serve an unadvertised model, so absence from catalog groups does not imply that the session is unusable.
 
 ## Alternatives considered
 
-- **Falling back to the composition entry when the stored route is unregistered.** Rejected: the composer would then name the shipped DeepSeek model instead of prompting, which is both a silent switch to a provider the user did not pick and the opposite of the requested behavior.
-- **Validating and clearing a stale default.** Rejected: catalog membership is advisory by design (`buildModelCatalog` documents it), so an adapter may serve a model its own catalog stopped advertising; self-healing would break that deliberate case.
-- **A `settings.update` merge patch.** Rejected: it cannot clear `reasoningEffort`, so a switch from a reasoning model to a plain one leaves an effort the next session fails on.
-- **Persisting only from blank sessions.** Rejected: the most informative switch is the one made mid-conversation after seeing a model underperform, and that one would never be saved.
-- **A separate "set as default" affordance.** Rejected for now: it adds a second gesture for what every comparable product infers from the switch itself. The cost is that a temporary switch in an old session also moves the default.
+| Alternative | Contract mismatch |
+|---|---|
+| Fall back to the composition entry when the stored provider is unavailable | The product silently switches away from the user's selection. |
+| Validate the stored selection against catalog membership | Catalogs are advisory and may omit requestable models. |
+| Save with a merge patch | An omitted `reasoningEffort` cannot clear the stored field. |
+| Save only selections made in blank sessions | An informed mid-conversation selection never becomes the deployment default. |
+| Add a separate “set as default” gesture | The session picker and future-session preference can diverge despite representing the same user choice. |
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
index 0d2821cb63..52308518f0 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -6,38 +6,42 @@ Status: implemented
 
 ## 问题
 
-新会话的起始路由被冻结在网关的组合条目里（web-app bundle patch 中的 `api-gateway` 行）。在一段对话里切换模型只影响这段对话：下一个会话又回到出厂默认，而要改这个默认值，唯一的办法是手工编辑一条 `cordis.yml` 行并重启。组合层与每会话选择之间没有用户设置这一层。
+会话模型选择器与部署默认值是同一项偏好的两个层次。如果选择器只影响其所在会话，下一个空白会话可能选择不同模型，用户却没有途径使默认值与选择器一致。如果默认值位于 Host 网关内部，直接创建 Agent 的前门只有依赖 Host 或复制状态才能共享它。
+
+推理强度使持久化形态成为契约的一部分：不含强度的模型选择必须清除已存强度，否则下一个 Agent 可能会采用所选模型不接受的强度。
 
 ## 决定
 
-`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是镜像的一例：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
+`AgentDefaultModelService` 提供 `ctx.agentDefaultModel`，并把 `{provider, model, reasoningEffort?}` 注册为 `agent-default-model` Settings 分节。其 `{provider, model}` 组合条目是 base 层，`settings.yaml` 提供用户层。该服务不偏向特定前门，因此直接创建与 ApiProxy 支撑的创建共享同一个默认值（[headless 直接 core 前门](../architecture/2026-08-09-headless-direct-core-front-door.md)）。`workspaceRoot` 仍是 ApiProxy 配置，因为它是 Host 启动器事实，而不是模型状态。
 
-`session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`reasoningEffort` 属于 Settings 分节，但不属于插件配置。Settings 层按字段合并，因此已配置的强度会在用户选择省略它时继续存在。`saveSelection()` 写入完整的用户分节；缺席值由此清除已存强度。部署级强度默认值属于适配器 profile，并由它按模型解析。
 
-`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置这条缝的存在。
+`session.selectModel` 把被接受的 `ModelSelection` 应用于所在会话，并调用 `saveDefaultModelSelection()` 保存共享的 Agent 默认值。存储失败只记日志，不撤销会话选择。没有 Settings 提供方的部署保留组合条目，被接受的选择只停留在该会话中。
 
-`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一轮的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
+`ApiProxyDefaults` 携带 `defaultModelSelection()` 与 `saveDefaultModelSelection()` 闭包，因此 `createApiProxy` 不依赖 Settings seam。`ApiProxyService` 将它们分别接到 `ctx.agentDefaultModel.currentSelection()` 与 `ctx.agentDefaultModel.saveSelection()`。
 
-存下来的路由不做注册表校验。默认值指向一条模型页已经删除的路由时，它照样作为 `current` 送到 `session.models`，匹配不到任何已公布的分组——而这正是让输入框选择器已有的回退提示重新选择、而不是显示一个部署根本够不着的模型的原因。
+`selectionFor(agent)` 每次读取时都解析各层：先取进程内的会话选择，其次取会话最新记录的 `request/header`，最后取当前 Agent 默认值。已有请求日志的会话持续绑定到该持久选择。空白会话即使创建于偏好保存之前，也会观察到当前默认值；这与 New Session surface 可能复用空白会话的行为一致。
+
+已存选择不要求属于目录。某条提供方路由可能服务其咨询性目录未列出的模型。因此，`session.models` 会在已公布分组之外单独报告已存选择，并另行报告适配器是否服务其提供方。
 
 ## 影响
 
-`ApiProxyDefaults` 形状变了，约 40 处测试构造点随之更新。`host.describe` 现在报告的是活的默认值而非捕获的快照，这本就是它一直想表达的含义。用户一旦切换模型，`settings.yaml` 就会多出一个 `api-gateway:` 段；`api-gateway` 这个 namespace 刻意**没有**加进网关的暴露名单，因此设置页既不读也不写它——模型选择器就是它的编辑器。
+`host.describe` 报告当前 Agent 默认值。模型切换成功后，`settings.yaml` 中会存有一个 `agent-default-model:` 分节。网关不通过 Settings 页 allowlist 暴露该 namespace；模型选择器是它的编辑器。
 
-## 后续：让发不出消息的会话禁止输入
+## 无法发送消息的会话
 
-默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后这一轮在适配器内部失败。两处改动关掉这个口子。
+当没有适配器服务会话所选提供方时，`session.prompt` 会在开启轮次前以 `model-unavailable` 拒绝。这一方法是执行边界；禁用 composer 只是客户端提供的便利。
 
-宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
+`session.models` 报告 `routable`。ui-model 插件通过 `ctx.conversation.blocks` 投影不可路由的选择，composer 随之变为不可操作，同时保留模型 seat 可用。客户端不知道是否可路由时不会阻断输入，包括目录首次加载或加载失败的情况。
 
-编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder——唯独模型 seat 被 block 刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
-
-闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计是咨询性的：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
+可路由性与目录成员关系不同。仍在服务的提供方路由可以处理未公布的模型，因此不在目录分组中并不代表会话不可用。
 
 ## 考虑过的替代方案
 
-- **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
-- **校验并清空失效的默认值。** 否决：目录成员关系按设计是咨询性的（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
-- **用 `settings.update` 合并补丁。** 否决：它清不掉 `reasoningEffort`，于是从推理模型切到普通模型会留下一个等级，让下一个会话在它上面失败。
-- **只在空白会话里持久化。** 否决：最有信息量的切换恰恰是对话到一半发现模型不行时做的那一次，而它永远存不下来。
-- **单独做一个「设为默认」的入口。** 目前否决：同类产品都从切换本身推断的事情，它却要多一个手势。代价是在老会话里的临时切换也会移动默认值。
+| 替代方案 | 契约不匹配之处 |
+|---|---|
+| 已存提供方不可用时回落到组合条目 | 产品会静默切离用户选择。 |
+| 根据目录成员关系校验已存选择 | 目录仅供参考，可能省略仍可请求的模型。 |
+| 使用合并 patch 保存 | 省略的 `reasoningEffort` 无法清除已存字段。 |
+| 只保存空白会话中的选择 | 对话期间知情作出的选择不会成为部署默认值。 |
+| 增加单独的「设为默认」手势 | 会话选择器与未来会话偏好虽然代表同一用户选择，却仍可能分歧。 |
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index 145c1cf619..f4e308c8f2 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.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 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
-2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
+2026-08-08-dsh-run-headless-command.md: 566eeb5b2a09a0d07d72a68e4a5f449d2822e708
+2026-08-08-dsh-run-headless-command.zh.md: 177410e783a37026940829da5f81343ddc61cb29
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
index d1cc0573d1..566eeb5b2a 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
@@ -6,36 +6,36 @@ English | [中文](2026-08-08-dsh-run-headless-command.zh.md)
 
 ## Problem
 
-The product launcher attached optional task text to its generic profile boot: `dsh --profile headless "task"`. That made one argv shape mean either a long-lived profile or a one-shot run according to a row discovered only after composition. The parser's `ProfileInvocation` carried optional task state, help presented a profile implementation detail as the user command, and a custom profile could accept a task only through the same overloaded root.
+Generic profile boot and one-shot task execution have different lifecycle contracts. A root grammar that accepts optional task text makes one argv shape mean either a long-lived process or a terminating task according to a plugin row discovered only after composition. It also exposes a profile implementation detail as the primary user command and gives custom profiles no explicit one-shot entry.
 
-The former `dsh -p` spelling was already absent from the parser, so restoring it or detecting it specially would add compatibility machinery to a pre-release interface. A separate application-file proposal also used the `run` verb, leaving two incompatible owners for one top-level command.
+The `run` verb must have one top-level meaning. Sharing it with application-file execution or inferring its meaning from positional shape creates the same ambiguity.
 
 ## Decision
 
-One-shot execution owns an explicit grammar:
+One-shot execution owns this grammar:
 
 ```text
 dsh run [--profile <name>] [--patch <path>...] <task...>
 ```
 
-`--profile` defaults to `headless` and remains available for custom one-shot compositions. `--patch` is repeatable and occupies the existing overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
+`--profile` defaults to `headless` and supports custom one-shot compositions. `--patch` is repeatable and occupies the normal overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
 
-The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns the composition selected by this grammar.
+`RunInvocation` is a distinct `DshInvocation` member. The generic profile invocation carries no task state and accepts no positional arguments. Both dispatch paths use `runProfile`: profile boot omits `task`, while `run` supplies it. A one-shot profile without `headless-runner` fails through the composed-row check, and profile boot containing that row without a task points to `dsh run --profile <name> "<task>"`.
 
-`RunInvocation` is a separate `DshInvocation` member. The generic profile invocation no longer carries task text, and its root command accepts no positional arguments. Both dispatch paths call the existing deep `runProfile` module: `profile` omits `task`, while `run` supplies it. There is no shallow `run.ts` forwarding module and no alias, warning, or custom detector for former spellings; they fail through the ordinary Commander grammar. A one-shot profile without `headless-runner` still fails through the existing composed-row check, while booting a profile that contains that row without a task points to `dsh run --profile <name> "<task>"`.
+The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns composition. [Headless is a direct core front door](../architecture/2026-08-09-headless-direct-core-front-door.md) owns the execution contract: one fresh persisted Session, final assistant text on stdout, completed/non-completed exit mapping, empty stderr on success, no listening port, and bounded signal shutdown after Agent quiescence and Session flush.
 
-The `run` verb belongs to one-shot task execution. Launching an application file must choose another command name; two top-level meanings selected by positional shape would recreate the ambiguity this command removes.
-
-The runner's user-visible contract stays the same: a fresh persisted session, browser observation URL on stderr, final assistant text on stdout, completed/non-completed exit mapping, and bounded signal shutdown. The product-level keyless acceptance exposed that the in-process mux consumer could lag the same-process `agent/status: idle` notification and derive output before reading the final frames. The idle notification now captures the authoritative final session sequence, and the runner waits until the ordered mux reaches that boundary (or the stream ends) before deriving text and exit reason. This enforces the existing idle-to-idle contract without adding a wire field or a timing delay.
+The `run` verb belongs only to one-shot task execution. Application-file launch requires a distinct command name.
 
 ## Alternatives considered
 
-- **Keep task text on `dsh --profile`.** Rejected because profile boot and one-shot execution remain one grammar whose meaning depends on a late composition check.
-- **Preserve `dsh -p` or the positional profile form as aliases.** Rejected under the pre-release stance: compatibility branches would outlive the interface they were meant to retire.
-- **Make `--profile headless` mandatory under `run`.** Rejected because the shipped one-shot surface should have the shortest canonical spelling, while optional `--profile` preserves plugin-defined one-shot compositions.
-- **Give `dsh run` to application-file launch and choose another headless verb.** Rejected because `run` describes executing a task through the harness; application-file ownership would make the product's primary one-shot command less direct and collide with custom one-shot profiles.
-- **Add `apps/cli/src/run.ts`.** Rejected because it would only forward to `runProfile`, splitting command ownership without hiding any complexity.
+| Alternative | Contract mismatch |
+|---|---|
+| Put task text on root profile boot | Lifecycle meaning depends on a plugin row discovered after parsing. |
+| Accept root aliases such as `dsh -p` | The pre-release grammar acquires compatibility branches with no current command ownership. |
+| Require `--profile headless` | The shipped one-shot surface loses its shortest canonical spelling. |
+| Use `dsh run` for application files | One top-level verb has two meanings and the primary task command becomes indirect. |
+| Add a shallow `apps/cli/src/run.ts` forwarder | Command ownership splits without hiding any complexity. |
 
 ## Consequences
 
-This is an intentional breaking CLI change. Documentation, help, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Existing custom one-shot profiles keep working through `--profile`; long-lived profiles and config dumps retain their existing root grammar. The competing application-file command must be renamed and rebased separately rather than sharing or overloading `run`.
+Help, documentation, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Custom one-shot profiles use `--profile`; long-lived profile boot and config dumps keep the root profile grammar. Application-file execution is a separate command concern.
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index afb18fea6a..177410e783 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -6,36 +6,36 @@ Status: implemented
 
 ## 问题
 
-产品启动器过去把可选任务文本挂在通用 profile 启动命令上：`dsh --profile headless "task"`。于是，同一种 argv 形态会表示常驻 profile 或一次性运行，具体含义取决于组合完成后才发现的配置行。解析器的 `ProfileInvocation` 携带可选任务状态，帮助信息把 profile 的实现细节呈现为用户命令，自定义 profile 也只能通过同一个过载的根命令接收任务。
+通用 profile 启动与一次性任务执行具有不同的生命周期约定。若根语法接受可选任务文本，同一种 argv 形态会表示常驻进程或终止式任务，具体含义取决于组合完成后才发现的插件配置行。它还会把 profile 实现细节暴露成主要用户命令，并使自定义 profile 缺少明确的一次性入口。
 
-解析器中已经没有原来的 `dsh -p` 写法，因此恢复该写法或加入特殊检测，会给预发布接口增加兼容机制。另一个应用文件提案也使用 `run` 动词，使同一个顶层命令同时归属两个互不兼容的功能。
+`run` 动词必须只有一种顶层含义。与应用文件执行共用该动词，或根据位置参数形态推断含义，都会产生相同的歧义。
 
 ## 决策
 
-一次性执行采用明确语法：
+一次性执行采用以下语法：
 
 ```text
 dsh run [--profile <name>] [--patch <path>...] <task...>
 ```
 
-`--profile` 默认为 `headless`，同时保留对自定义一次性组合的支持。`--patch` 可重复使用，并沿用既有 overlay 层的位置。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
+`--profile` 默认为 `headless`，并支持自定义一次性组合。`--patch` 可重复使用，并占据正常的 overlay 层。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
 
-[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责该语法所选择的组合。
+`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不携带任务状态，也不接受位置参数。两条分派路径都使用 `runProfile`：profile 启动省略 `task`，而 `run` 提供该字段。缺少 `headless-runner` 的一次性 profile 会触发组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
 
-`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不再携带任务文本，其根命令也不接受位置参数。两条分派路径都调用已有的深层 `runProfile` 模块：`profile` 省略 `task`，`run` 则提供该字段。实现中没有只负责转发的浅层 `run.ts` 模块，也没有面向旧写法的别名、警告或自定义检测器；旧写法会按普通 Commander 语法失败。缺少 `headless-runner` 的一次性 profile 仍会触发既有的组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
+[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责组合。[Headless 是直接 core 前门](../architecture/2026-08-09-headless-direct-core-front-door.md)负责执行约定：一个新的持久化会话、stdout 上的最终 assistant 文本、completed／非 completed 的退出状态映射、成功时为空的 stderr、无监听端口，以及 Agent 完全停稳且会话 flush 后的有界信号关闭。
 
-`run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
-
-运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
+`run` 动词只负责一次性任务执行。应用文件启动需要不同的命令名。
 
 ## 考虑过的替代方案
 
-- **把任务文本保留在 `dsh --profile` 上。** 不予采纳：profile 启动和一次性执行仍共用同一套语法，其含义取决于较晚发生的组合检查。
-- **保留 `dsh -p` 或位置参数 profile 形式作为别名。** 不予采纳：根据预发布立场，这些兼容分支会比本应退役的接口存续更久。
-- **要求在 `run` 下必须指定 `--profile headless`。** 不予采纳：已交付的一次性接口应采用最短的规范写法，同时用可选的 `--profile` 保留插件定义的一次性组合。
-- **把 `dsh run` 交给应用文件启动，并为 headless 选择另一个动词。** 不予采纳：`run` 描述的是通过 harness 执行任务；若归应用文件所有，产品的主要一次性命令会更不直接，并与自定义一次性 profile 冲突。
-- **新增 `apps/cli/src/run.ts`。** 不予采纳：它只会转发到 `runProfile`，拆分命令归属，却没有隐藏任何复杂度。
+| 替代方案 | 约定不匹配之处 |
+|---|---|
+| 把任务文本放在根 profile 启动命令上 | 生命周期含义依赖解析后才发现的插件配置行。 |
+| 接受 `dsh -p` 等根命令别名 | 预发布语法获得不属于任何当前命令的兼容分支。 |
+| 要求指定 `--profile headless` | 随附的一次性 surface 失去最短的规范写法。 |
+| 将 `dsh run` 用于应用文件 | 一个顶层动词具有两种含义，主要任务命令也变得间接。 |
+| 添加仅转发的 `apps/cli/src/run.ts` | 命令归属被拆分，却没有隐藏任何复杂度。 |
 
 ## 后果
 
-这是一次有意为之的 CLI（命令行界面）破坏性变更。文档、帮助信息、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照都使用 `dsh run`。现有自定义一次性 profile 可继续通过 `--profile` 工作；常驻 profile 和配置 dump 保留既有的根命令语法。与之竞争的应用文件命令必须单独改名并 rebase，不得共享或重载 `run`。
+帮助信息、文档、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照均使用 `dsh run`。自定义一次性 profile 使用 `--profile`；常驻 profile 启动与配置 dump 使用根 profile 语法。应用文件执行是独立的命令关注点。
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 162ea534b7..101332555d 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
-README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
+README.md: dd29f7fc03a783079ea3194de99589c1f545be5b
+README.zh.md: 60e7aa1ec1ea2fad7e3f3d97a0f6bf42355adffc
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 12108fcbff..dd29f7fc03 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -9,7 +9,7 @@ The `dsh` command is the product launcher for profiles: ordered stacks of plugin
 | Command | Purpose |
 |---|---|
 | `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session, print the final answer, and exit; the profile defaults to `headless`. |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session directly over core, print the final answer, and exit; the profile defaults to `headless` and mounts no Web server. |
 | `dsh web` | Alias of `--profile web` with the Web flag family (`--host`, `--port`, `--dev`, ...). |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 37967973ed..60e7aa1ec1 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -9,7 +9,7 @@
 | 命令 | 用途 |
 |---|---|
 | `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | 运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`。 |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | 直接在 core 上运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`，且不挂载 Web server。 |
 | `dsh web` | `--profile web` 的别名，附带 Web flag 系列（`--host`、`--port`、`--dev` 等）。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 8bebf18040..cfcd903e32 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -32,6 +32,8 @@ flowchart LR
   cfg --> plugin_dsh_base_user_interaction
   plugin_dsh_base_agent["agent<br/>@deepseek-ai/dsh-agent"]
   cfg --> plugin_dsh_base_agent
+  plugin_dsh_base_agent_default_model["agent-default-model<br/>@deepseek-ai/dsh-agent-default-model"]
+  cfg --> plugin_dsh_base_agent_default_model
   plugin_dsh_base_tasks["tasks<br/>@deepseek-ai/dsh-tasks-local"]
   cfg --> plugin_dsh_base_tasks
   plugin_dsh_base_llm_retry["llm-retry<br/>@deepseek-ai/dsh-llm-retry"]
@@ -174,6 +176,7 @@ flowchart LR
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |
 | `user-interaction` | `@deepseek-ai/dsh-user-interaction` |
 | `agent` | `@deepseek-ai/dsh-agent` |
+| `agent-default-model` | `@deepseek-ai/dsh-agent-default-model` |
 | `tasks` | `@deepseek-ai/dsh-tasks-local` |
 | `llm-retry` | `@deepseek-ai/dsh-llm-retry` |
 | `settings` | `@deepseek-ai/dsh-settings-local` |
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index a478ae60d2..9bfe494ba6 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: 81320ecbd19012123ab7e69967cbadb088356cfe
+README.md: 4f8aa86c0f6cdb91eb843048cd5ed4943a896c73
+README.zh.md: 09bc19220a869bedfcaa98baccbf6d4f6a3f3223
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index e616b420d6..4f8aa86c0f 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -10,7 +10,7 @@ This reference defines the profile, one-shot run, web-alias, plugin-management,
 
 Bundle names resolve from the dsh installation first, then from the profile directory. In-box bundles (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. A bare plugin `name` in any patch row resolves through the profile directory's Node parent-walk, which reaches the maintained installation fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
-The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + web-app + headless). Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
+The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + headless). On load, the exact installation-owned headless tuple (base + web-app + headless) normalizes to the shipped template; extra, missing, or reordered bundle lists are user-owned and remain untouched. Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
 
 Profile boot accepts no positional task. A profile that mounts the one-shot runner row (`headless-runner`) therefore fails loud with the canonical `dsh run --profile <name> "<task>"` command instead of reaching the row's raw required-field error.
 
@@ -27,7 +27,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `dsh run [--profile <name>] [--patch <path>...] <task...>` joins the task arguments with spaces, rejects a missing or blank task, and defaults `--profile` to `headless`. Repeatable `--patch` overlays occupy the same layer position as profile-boot overlays. A custom selected profile must mount `headless-runner`; otherwise launch fails before boot with a diagnostic naming that missing row.
 
-The launcher patches the task text into the runner row, which drives one fresh persisted session through the in-process API carrier, prints the final assistant text on stdout, and exits 0 on a completed turn, else 1. At the idle boundary, the runner waits until its mux consumer has observed the session's final event sequence before deriving that output and exit reason. The session's Web host runs on an OS-assigned port and is announced on stderr, so the run is observable in a browser.
+The launcher patches the task text into the runner row. After Loader settlement, the runner reads the shared `ctx.agentDefaultModel` default, creates one fresh persisted Agent through `ctx.agents`, submits the task, waits for quiescence, and flushes the Session before deriving the last non-empty assistant text and final `turn/end` reason from its durable interval. It prints the text on stdout and exits 0 for `completed`, else 1. The shipped headless profile mounts no ApiProxy, Host, HTTP server, Web runtime, or browser client; a successful run writes nothing to stderr and opens no listening port.
 
 ## Plugin management
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 81320ecbd1..09bc19220a 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -10,7 +10,7 @@
 
 组合包名称先从 dsh 安装解析，再从 profile 目录解析。因此内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`）总是来自与正在运行的 `dsh` 相同的安装；树外组合包来自 profile 由 pnpm 管理的 `node_modules`。任何 patch 行中的裸插件 `name` 通过 profile 目录的 Node 父目录逐级查找解析，该查找可达到持续维护的安装后备目录 `$DSH_HOME/profiles/node_modules`（安装的应用和组合包所依赖的每个包对应一个符号链接，每次启动时修复）。
 
-`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + web-app + headless）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
+`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + headless）。加载时，与安装所管理的 headless 元组（base + web-app + headless）完全一致的列表会规范化为随附模板；包含额外项、缺少项或调整过顺序的组合包列表由用户拥有，保持不变。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
 Profile 启动不接受位置参数任务。因此，挂载了一次性运行器行（`headless-runner`）的 profile 会显式报错，并提示规范命令 `dsh run --profile <name> "<task>"`，而不会触发该行原始的必填字段错误。
 
@@ -27,7 +27,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `dsh run [--profile <name>] [--patch <path>...] <task...>` 会用空格拼接任务参数，拒绝缺失或空白任务，并让 `--profile` 默认为 `headless`。可重复使用的 `--patch` overlay 与 profile 启动的 overlay 位于同一层。所选的自定义 profile 必须挂载 `headless-runner`；否则启动器会在启动前失败，并在诊断中指明缺少该行。
 
-启动器把任务文本 patch 进运行器行，运行器再通过进程内 API 载体驱动一个全新的持久化会话，在 stdout 打印最终 assistant 文本，并在轮次完成时以 0 退出，否则以 1 退出。到达 idle 边界时，运行器会等到 mux 消费方观察到会话的最终事件序号，再生成输出与退出原因。会话的 Web 宿主运行在 OS 分配的端口上并公布到 stderr，因此该次运行可在浏览器中观察。
+启动器把任务文本 patch 进运行器行。Loader 结算后，运行器读取共享的 `ctx.agentDefaultModel` 默认值，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对 Session 执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 stdout 打印文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端；成功运行不会向 stderr 写入任何内容，也不会打开监听端口。
 
 ## 插件管理
 
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index a42780581f..073f541fe0 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -222,7 +222,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       })
       expect(result.code, result.stderr).toBe(0)
       expect(result.stdout).toBe('published dsh run reached the mock')
-      expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+$/u)
+      expect(result.stderr).toBe('')
       expect(server.requests.length).toBeGreaterThan(0)
       expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
       expect(JSON.stringify(server.requests.map(request => request.body))).toContain('answer from the published entry')
@@ -470,6 +470,20 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
     }, 30_000)
 
+    it('prints a headless profile with no Host, HTTP, or browser rows', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'headless', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-agent-default-model'")
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-headless'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-host-")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-web-app'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-client-")
+    }, 30_000)
+
     it('composes the profile user layer and a --patch overlay in order', async () => {
       // Auto-init the web profile first, then write its user layer.
       const init = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })
diff --git a/apps/cli/tests/fixtures/never-dispose.mjs b/apps/cli/tests/fixtures/never-dispose.mjs
index 0c29cc2967..5dc8510550 100644
--- a/apps/cli/tests/fixtures/never-dispose.mjs
+++ b/apps/cli/tests/fixtures/never-dispose.mjs
@@ -8,6 +8,7 @@ import { existsSync } from 'node:fs'
  */
 export function apply(ctx) {
   const keepAlive = setInterval(() => {}, 60_000)
+  process.stderr.write('dsh-test: never-dispose ready\n')
   ctx.effect(() => async () => {
     clearInterval(keepAlive)
     const armFile = process.env.DSH_TEST_SHUTDOWN_ARM_FILE
diff --git a/apps/cli/tests/headless-shutdown.e2e.ts b/apps/cli/tests/headless-shutdown.e2e.ts
index 237554864c..b0bcbb7cae 100644
--- a/apps/cli/tests/headless-shutdown.e2e.ts
+++ b/apps/cli/tests/headless-shutdown.e2e.ts
@@ -22,7 +22,7 @@ if pid == 0:
     os.chdir(cwd)
     os.execvpe(node, [node, *json.loads(launch_args_json)], env)
 
-markers = [b"dsh: observing at ", b"dsh-test: never-dispose started"]
+markers = [b"dsh-test: never-dispose ready", b"dsh-test: never-dispose started"]
 output = bytearray()
 marker_index = 0
 deadline = time.monotonic() + float(timeout_seconds)
@@ -73,7 +73,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
       name: 'dsh-profile-headless',
       private: true,
       dependencies: {},
-      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'] } },
+      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'] } },
     }, undefined, 2))
     await writeFile(join(profileDir, 'cordis.patch.yml'), [
       '- insert:',
@@ -124,7 +124,8 @@ async function runHeadlessPtySmoke(): Promise<string> {
 describe.skipIf(process.platform === 'win32')('headless process shutdown (real Loader tree in a PTY)', () => {
   it('lets a second Ctrl+C force exit while the first signal is draining', async () => {
     const output = await runHeadlessPtySmoke()
-    expect(output).toContain('dsh: observing at ')
+    expect(output).not.toContain('dsh: observing at ')
+    expect(output).toContain('dsh-test: never-dispose ready')
     expect(output).toContain('dsh-test: never-dispose started')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
diff --git a/apps/web/tests/declared-reasoning.e2e.ts b/apps/web/tests/declared-reasoning.e2e.ts
index 664f20dfe6..f908511214 100644
--- a/apps/web/tests/declared-reasoning.e2e.ts
+++ b/apps/web/tests/declared-reasoning.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: a hand-declared model's `reasoningEfforts` reaches the
 // composer's effort pane — the levels a settings profile declares are exactly
-// what the picker offers, and picking one records it with the default route.
+// what the picker offers, and picking one records it with the Agent default.
 // Zero model calls: declaring, describing, and switching are settings/llm
 // traffic only, so there is no fixture and a stray stream would fail loud.
 import { readFile } from 'node:fs/promises'
@@ -77,8 +77,8 @@ describe.skipIf(MODE === 'record')('web e2e: declared reasoning efforts reach th
     const snapshot = await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-    // Picking a level is the same gesture that saves the default target, so
-    // the effort lands in the gateway's settings section beside the route.
+    // Picking a level is the same gesture that saves the default selection, so
+    // the effort lands in the Agent default Settings section beside provider/model.
     await page.getByRole('menuitemradio', { name: 'High' }).click()
     await expect.poll(
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
diff --git a/apps/web/tests/declared-reasoning.overlay.yml b/apps/web/tests/declared-reasoning.overlay.yml
index d90452178c..ff89f036b3 100644
--- a/apps/web/tests/declared-reasoning.overlay.yml
+++ b/apps/web/tests/declared-reasoning.overlay.yml
@@ -2,7 +2,7 @@
 # deepseek-official default would be a route nothing serves. This scenario
 # starts the default on its own declared reasoning model so the effort pane
 # describes that model from the first open.
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: acme-gateway
     model: acme-think
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
index 24ee5a1616..0c43bf3998 100644
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -1,5 +1,5 @@
 // Web e2e scenario: switching models in the composer is how this deployment's
-// default is chosen. The gesture writes the `api-gateway` settings section, a
+// default is chosen. The gesture writes the shared `agent-default-model` settings section, a
 // session created afterwards starts from it, and a session that already logged
 // a route keeps deriving from its own log — the tier order the gateway
 // resolves on every read.
@@ -21,7 +21,7 @@ import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
 import { ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, saveFailureShot } from './support.ts'
 
-/** Points the shipped `api-gateway` default at this scenario's own route. */
+/** Points the shipped shared Agent default at this scenario's own route. */
 const OVERLAY = fileURLToPath(new URL('./default-model.overlay.yml', import.meta.url))
 
 /** The route this scenario starts on, patched over the shipped default. */
@@ -110,12 +110,12 @@ describe('web e2e: the composer model switch is the default for later sessions',
     await page.getByRole('menuitem', { name: /模型/ }).click()
     await page.getByRole('menuitemradio', { name: 'Acme Large' }).click()
 
-    // The switch is what sets the default: the gateway's own settings section
+    // The switch is what sets the default: the shared Agent-route settings section
     // now names it, beside the provider profiles the Models page writes.
     await expect.poll(
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
       { timeout: 10_000 },
-    ).toContain('api-gateway:')
+    ).toContain('agent-default-model:')
     const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
     expect(document).toContain(`provider: ${ROUTE}`)
     expect(document).toContain(`model: ${MODEL}`)
diff --git a/apps/web/tests/default-model.overlay.yml b/apps/web/tests/default-model.overlay.yml
index 540e4891d6..5ec0e77405 100644
--- a/apps/web/tests/default-model.overlay.yml
+++ b/apps/web/tests/default-model.overlay.yml
@@ -2,7 +2,7 @@
 # deepseek-official default would be a route nothing serves — which the
 # composer now correctly refuses to type into. This scenario declares its own
 # pi-ai routes and starts the default on one of them.
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: origin-gateway
     model: origin-large
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 1b81c2c5da..3b279ef25a 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 06c15f204b3a695de49df29938781f8f033c4a7e
-architecture.zh.md: 29fe94f5a94c317854366e811dc6ceb74d2fddfe
+architecture.md: ed33fb215c3b4fd830bef219da74f4ee98dec81d
+architecture.zh.md: 19d2500142449c63d725f89a651b22205af6b301
diff --git a/docs/architecture.md b/docs/architecture.md
index 06c15f204b..ed33fb215c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -17,6 +17,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and variables |
 | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, process-local initiator scope |
+| `ctx.agentDefaultModel` | [`dsh-agent-default-model`](../packages/core/agent-default-model/README.md) | Settings-backed model selection shared by Agent front doors |
 | `ctx.agentLoop` | `dsh-agent-loop` | concrete `Agent` driver |
 
 ### Capability Services
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 29fe94f5a9..19d2500142 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -17,6 +17,7 @@
 | `ctx.systemPrompt` | `dsh-system-prompt` | 有序的提示词片段、工具 schema 和变量 |
 | `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | 活跃 agent（智能体）、委托创建、`agent/*` 事件、进程内发起方作用域 |
+| `ctx.agentDefaultModel` | [`dsh-agent-default-model`](../packages/core/agent-default-model/README.md) | 由 Settings 支撑、供 Agent 入口共享的模型选择 |
 | `ctx.agentLoop` | `dsh-agent-loop` | 实体 `Agent` 驱动器 |
 
 ### 功能服务
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 4b46a6566b..d61353210e 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -94,6 +94,9 @@ flowchart LR
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
+  pkg_agent_default_model["agent-default-model"]
+  svc_agentDefaultModel["ctx.agentDefaultModel<br/>Default Agent model selection"]
+  pkg_headless["headless"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -176,6 +179,7 @@ flowchart LR
   pkg_tool_workflow["tool-workflow"]
   pkg_acp --> svc_approval
   pkg_agent --> svc_agents
+  pkg_agent_default_model --> svc_agentDefaultModel
   pkg_agent_loop --> svc_agentLoop
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
@@ -265,6 +269,8 @@ flowchart LR
   pkg_workflow --> svc_workflows
   pkg_workflow_workerthread --> svc_workflows
   pkg_workspace --> svc_workspace
+  svc_agentDefaultModel --> pkg_headless
+  svc_agentDefaultModel --> pkg_host_apiproxy
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
@@ -397,6 +403,7 @@ flowchart LR
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agentDefaultModel` | `core` | [`agent-default-model`](../packages/core/agent-default-model) | - | [`headless`](../packages/bundle/headless), [`host-apiproxy`](../packages/host/apiproxy) | - | Layers the default ModelSelection through settings so direct and Host-backed Agent front doors share one state owner. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 0a5d0f7519..6219a0080f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -14,7 +14,7 @@ A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml`
 Requires: `agents`
 
 ```ts config-catalog
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -80,6 +80,20 @@ Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) ·
 
 Source: [`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
 
+## `@deepseek-ai/dsh-agent-default-model`
+
+```ts config-catalog
+/** Composition entry for the default model selection. */
+export interface Config {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts)
+
 ## `@deepseek-ai/dsh-agent-loop`
 
 Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
@@ -475,17 +489,17 @@ Source: [`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.
 
 ## `@deepseek-ai/dsh-headless`
 
-Requires: `apiProxy` · `httpServer`
+Requires: `agentDefaultModel` · `agents` · `sessions`
 
 ```ts config-catalog
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 ```
 
-Source: [`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
+Source: [`packages/bundle/headless/src/index.ts:29`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
@@ -550,32 +564,17 @@ Source: [`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-c
 
 ## `@deepseek-ai/dsh-host-apiproxy`
 
-Requires: `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
+Requires: `agentDefaultModel` · `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
 
 ```ts config-catalog
-/**
- * Gateway plugin config: host-level agent routing and Workspace creation root.
- *
- * `reasoningEffort` is deliberately absent, so the section carries one field
- * the composition cannot. The seam resolves a section by MERGING the user
- * layer over the composition entry per field, and an absent key cannot
- * override a present one — so a composition-set effort would survive every
- * later switch to a model that has none, and strand it for the next session
- * to fail on. Effort is a per-model fact anyway: a deployment default belongs
- * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
- * which resolves per model rather than per gateway.
- */
+/** Gateway plugin config: the Host-only Workspace creation root. */
 export interface Config {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 ```
 
-Source: [`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
+Source: [`packages/host/apiproxy/src/index.ts:38`](../packages/host/apiproxy/src/index.ts)
 
 ## `@deepseek-ai/dsh-host-directory-picker-browse`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index f5ea3eba36..628750959e 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -18,7 +18,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 846ade98b9..a089e2a1f0 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -137,6 +137,7 @@
 | message | 消息 | | | |
 | mod | 模组 | | | |
 | model provider | 模型提供方 | | | |
+| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |
 | module | 模块 | | | |
 | non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |
 | npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 6f47c36e97..e7d6b47e70 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -25,6 +25,7 @@ flowchart TD
   end
   subgraph group_core["packages/core"]
     pkg_agent["agent"]
+    pkg_agent_default_model["agent-default-model"]
     pkg_agent_loop["agent-loop"]
     pkg_scope["scope"]
     pkg_session["session"]
@@ -510,6 +511,10 @@ flowchart TD
   pkg_token_meter --> pkg_llm
   pkg_token_meter --> pkg_session
   pkg_token_meter --> pkg_session_projection
+  pkg_agent_default_model --> pkg_agent
+  pkg_agent_default_model --> pkg_invariants
+  pkg_agent_default_model --> pkg_llm
+  pkg_agent_default_model --> pkg_settings
   pkg_goal --> pkg_agent
   pkg_goal --> pkg_brand
   pkg_goal --> pkg_invariants
@@ -553,11 +558,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
   pkg_loader_smoke --> pkg_session
-  pkg_headless --> pkg_agent
-  pkg_headless --> pkg_host_apiproxy
-  pkg_headless --> pkg_host_webserver
-  pkg_headless --> pkg_invariants
-  pkg_headless --> pkg_session
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
@@ -698,6 +698,11 @@ flowchart TD
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
   pkg_api_remotes --> pkg_typert_registry
+  pkg_headless --> pkg_agent
+  pkg_headless --> pkg_agent_default_model
+  pkg_headless --> pkg_invariants
+  pkg_headless --> pkg_llm
+  pkg_headless --> pkg_session
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
@@ -1252,6 +1257,7 @@ flowchart TD
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1263,7 +1269,6 @@ flowchart TD
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1295,6 +1300,7 @@ flowchart TD
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 42f00a896e..6a117435f5 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 96854801d684509d4d77b6408a4bb45b93438cdb
+core.md: b09e5b4f0a076a7f95a751a6204836a81a4c31e9
+core.zh.md: 01ac656fb657296fb26217108b8a4a15a5a88280
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index cc9cc30677..b09e5b4f0a 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -314,6 +314,30 @@ The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm)
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
+
+### `ctx.agentDefaultModel` — `AgentDefaultModelService`
+
+Owns the default model selection independently of any Host or transport. The composition entry remains usable without a settings provider; when one is mounted, its user layer is read live.
+
+```ts cordis-catalog
+/**
+ * Read the current default model selection.
+ * @returns a detached provider, model, and optional reasoning selection.
+ */
+currentSelection(): ModelSelection
+
+/**
+ * Save the complete default model selection. A deployment without a settings
+ * provider keeps its composition entry.
+ * @param next - resolved selection accepted by a front door.
+ * @returns fulfillment after the optional settings write settles.
+ */
+async saveSelection(next: ModelSelection): Promise<void>
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:64`](../../packages/core/agent-default-model/src/index.ts)
+
 <a id="ctxagentloop--agentloop"></a>
 
 ### `ctx.agentLoop` — `AgentLoop`
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 96854801d6..01ac656fb6 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -322,6 +322,30 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
+
+### `ctx.agentDefaultModel` — `AgentDefaultModelService`
+
+Owns the default model selection independently of any Host or transport. The composition entry remains usable without a settings provider; when one is mounted, its user layer is read live.
+
+```ts cordis-catalog
+/**
+ * Read the current default model selection.
+ * @returns a detached provider, model, and optional reasoning selection.
+ */
+currentSelection(): ModelSelection
+
+/**
+ * Save the complete default model selection. A deployment without a settings
+ * provider keeps its composition entry.
+ * @param next - resolved selection accepted by a front door.
+ * @returns fulfillment after the optional settings write settles.
+ */
+async saveSelection(next: ModelSelection): Promise<void>
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:64`](../../packages/core/agent-default-model/src/index.ts)
+
 <a id="ctxagentloop--agentloop"></a>
 
 ### `ctx.agentLoop` — `AgentLoop`
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 38df7fb986..cf4fba292f 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
-providers.zh.md: f4a42a4093d253b4b230e4a838ba275a0ce58ac9
+providers.md: ad0bd3696dbbdc4a89334932196d72a0afd3d209
+providers.zh.md: 719039cf7af8b59663642ebad81dbf315a023154
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index 8b52044e64..ad0bd3696d 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -124,16 +124,16 @@ Under `dsh`, references resolve from the inherited environment, the Models page'
 
 A configured route appears in the web model picker and can be switched at any time, which is how most people use it.
 
-Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `api-gateway`. There is no separate gesture.
+Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `agent-default-model`. There is no separate gesture.
 
 ```yaml
-api-gateway:
+agent-default-model:
   provider: acme-gateway
   model: acme-large
   reasoningEffort: high   # optional
 ```
 
-A session that has already run a turn is never retargeted by it — that session derives its route from its own log, so changing the default only reaches sessions that have not started. The shipped fallback under this section is the `api-gateway` composition entry (`deepseek-official` / `deepseek-v4-flash`), which a self-assembled `cordis.yml` may override; a composition you assemble yourself — headless, for instance — sets `agent-loop`'s `agents` instead.
+After a session has run a turn, its own log remains authoritative for its model selection; the default applies only to sessions without a recorded request. The shipped fallback under this section is the base bundle's `agent-default-model` composition entry (`deepseek-official` / `deepseek-v4-flash`). A self-assembled `cordis.yml` mounts and configures `@deepseek-ai/dsh-agent-default-model`; both direct front doors and Host-backed front doors read that same service.
 
 If the provider a saved default names is later removed, the composer says **Select model** and refuses input until you pick one, rather than sending to a route nothing serves.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index f4a42a4093..719039cf7a 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -124,16 +124,16 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
 
-在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `api-gateway` 段里。没有另一个单独的手势。
+在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `agent-default-model` 段里。没有另一个单独的手势。
 
 ```yaml
-api-gateway:
+agent-default-model:
   provider: acme-gateway
   model: acme-large
   reasoningEffort: high   # optional
 ```
 
-已经跑过一轮的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
+会话跑过一轮后，其自身日志仍是模型选择的权威；默认值只适用于尚无请求记录的会话。这个段落之下的出厂兜底是 base 组合包的 `agent-default-model` 组合条目（`deepseek-official` / `deepseek-v4-flash`）。自行组装的 `cordis.yml` 会挂载并配置 `@deepseek-ai/dsh-agent-default-model`；直接前门与 Host 支撑的前门都读取同一服务。
 
 如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。
 
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index dfdba88bec..9bb9b99bd8 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
-quickstart.zh.md: 7182f63586f4f08524c643a7c6c1ad599b2de098
+quickstart.md: ce196641f205324334533c025b4ac1dc791f857d
+quickstart.zh.md: ce12f43fa660f0a99be73749e0345570575fbbee
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 9d1a04f0a0..ce196641f2 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -39,7 +39,7 @@ Run a non-interactive task and print its final answer:
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. While it runs, stderr prints the local browser URL where the session can be observed.
+`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. It starts no Web server or listening port, and a successful run leaves stderr empty.
 
 ## Step 3: use the Web UI
 
@@ -53,7 +53,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,
 
 ## What happened
 
-`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml), [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root. `dsh web` uses the first two layers without the one-shot runner. Both select the DeepSeek model and capability plugins appropriate to their entry mode.
+`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root, then the runner drives the core Agent and Session services directly. `dsh web` instead composes `dsh-base` with [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), which owns the Host, HTTP, and browser layers. Both read the same default DeepSeek model route from `dsh-base`.
 
 ## Next steps
 
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index 7182f63586..ce12f43fa6 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -39,7 +39,7 @@ DEEPSEEK_API_KEY=sk-your-key-here
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
+`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。
 
 ## 第三步：使用 Web UI
 
@@ -53,7 +53,7 @@ pnpm run dsh web
 
 ## 回头看
 
-`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性 runner。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
+`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合，随后 runner 直接驱动 core Agent 与 Session 服务。`dsh web` 则由 `dsh-base` 与 [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 组合，后者拥有 Host、HTTP 与浏览器层。二者都从 `dsh-base` 读取同一个默认 DeepSeek 模型路由。
 
 ## 下一步
 
diff --git a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
index 7d411f7a0f..4199bfb9ca 100644
--- a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
@@ -1,4 +1,4 @@
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: cli-mock
     model: cli-mock
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 87261439da..593b05b4e8 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -234,7 +234,7 @@ describe('headless stream-json snapshots', () => {
     })
 
     expect(result.stdout).toBe('CLI tool round trip complete: CLI_TOOL_ROUND_TRIP\n')
-    expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+\n$/u)
+    expect(result.stderr).toBe('')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
   it('prints the original Loader activation error through the assembled one-shot app', async () => {
diff --git a/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl b/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
index 1312eb6511..260ae241b0 100644
--- a/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","seq":0,"time":0,"data":{"preset":"danger-full-access"}}
 {"type":"sandbox/mode","seq":1,"time":0,"data":{"mode":"danger-full-access"}}
 {"type":"approval/policy","seq":2,"time":0,"data":{"policy":"never"}}
-{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}
 {"type":"turn/start","seq":4,"time":0,"data":{"turn":1}}
 {"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":6,"time":0,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"session/title","seq":9,"time":0,"data":{"title":"Prove the product dsh run","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"cli-mock","model":"cli-mock","reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/knip.json b/knip.json
index 9ca15de212..812f7446bc 100644
--- a/knip.json
+++ b/knip.json
@@ -751,6 +751,11 @@
         "@cordisjs/.+"
       ]
     },
+    "packages/bundle/headless": {
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-code-runtime-worker"
+      ]
+    },
     "packages/bundle/web-app": {
       "ignoreDependencies": [
         "@deepseek-ai/.+"
diff --git a/packages/acp/acp/src/index.ts b/packages/acp/acp/src/index.ts
index 50549d7ab0..a1d37e2aa9 100644
--- a/packages/acp/acp/src/index.ts
+++ b/packages/acp/acp/src/index.ts
@@ -66,7 +66,7 @@ function internalError(detail: string): RequestError {
   return RequestError.internalError(undefined, detail)
 }
 
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -100,7 +100,7 @@ interface SessionRecord {
 /**
  * Mount the automation-only ACP server.
  * @param ctx - Cordis context carrying the agent factory and session events.
- * @param config - Initial provider/model target and optional test transport.
+ * @param config - Initial provider/model selection and optional test transport.
  */
 export function apply(ctx: Context, config: AcpConfig): void {
   // ACP handlers execute outside this plugin's injection scope, so capture the
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index fd61b9bec2..e64706453e 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
-README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 454d504be72c2120ec4aeaa1b22545e7d6ba2fee
+README.md: c060e99acb8cc40b8de92806727eea9e3723b7d2
+README.zh.md: f28b89e63e4bd6f07f2f7a55dfba5c2f78862feb
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index c256b89288..c060e99acb 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -33,7 +33,7 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..
 
 ## Profiles
 
-A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps can never drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm ever managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path).
+A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps cannot drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path). `loadProfile` normalizes an exact installation-owned bundle tuple to its shipped template while preserving every other manifest field; any extra, missing, or reordered entry makes the list user-owned and leaves it unchanged.
 
 User-level machine-local preferences also live in the Harness home:
 
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 454d504be7..f28b89e63e 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -35,7 +35,7 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 ## Profile
 
-profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
+profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，且无需 pnpm 管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。`loadProfile` 会将与安装自有组合包元组完全一致的列表规范化为随发行版交付的模板，同时保留 manifest 中其他所有字段；一旦条目有任何额外、缺失或重排，该列表就归用户所有并保持不变。
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index c353f18bef..1e71f3e8a7 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -114,6 +114,11 @@ export function resolveProfileDir(name: string, home: string = resolveDshHome())
 /** The shipped profile templates auto-initialized on first use, by name. */
 export const PROFILE_TEMPLATES: Record<string, readonly string[]> = {
   web: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
+  headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'],
+}
+
+/** Installation-owned bundle tuples normalized to the shipped template. */
+const INSTALLATION_OWNED_PROFILE_TUPLES: Record<string, readonly string[]> = {
   headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'],
 }
 
@@ -279,6 +284,32 @@ export function writeProfileManifest(dir: string, manifest: ProfileManifest): vo
   writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest, undefined, 2) + '\n')
 }
 
+/** Return whether two bundle lists have the same values in the same order. */
+function sameBundles(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+/**
+ * Normalize an exact installation-owned bundle tuple to its shipped template
+ * while preserving every other manifest field. Any other list is user-owned.
+ */
+function normalizeShippedProfile(name: string, dir: string, manifest: ProfileManifest): ProfileManifest {
+  const installationOwned = INSTALLATION_OWNED_PROFILE_TUPLES[name]
+  const current = PROFILE_TEMPLATES[name]
+  const bundles = manifest.dsh?.profile?.bundles
+  if (installationOwned === undefined || current === undefined || bundles === undefined
+    || !sameBundles(bundles, installationOwned)) return manifest
+  const normalized: ProfileManifest = {
+    ...manifest,
+    dsh: {
+      ...manifest.dsh,
+      profile: { ...manifest.dsh?.profile, bundles: [...current] },
+    },
+  }
+  writeProfileManifest(dir, normalized)
+  return normalized
+}
+
 /**
  * Resolve a package's root directory from one anchor without depending on the
  * package exporting `./package.json` (`require.resolve` would need that):
@@ -350,7 +381,7 @@ export function loadProfile(
     }
     initProfile(dir, template)
   }
-  const manifest = readProfileManifest(binName, dir)
+  const manifest = normalizeShippedProfile(name, dir, readProfileManifest(binName, dir))
   // A hand-written profile manifest may omit the dsh section entirely.
   const bundles = manifest.dsh?.profile?.bundles ?? []
   const layers = bundles.map((packageName): ProfileLayer => {
diff --git a/packages/boot/app-boot/tests/profile.spec.ts b/packages/boot/app-boot/tests/profile.spec.ts
index f0bd6f5da7..bd0294475d 100644
--- a/packages/boot/app-boot/tests/profile.spec.ts
+++ b/packages/boot/app-boot/tests/profile.spec.ts
@@ -161,6 +161,33 @@ describe('loadProfile', () => {
       .toEqual([...PROFILE_TEMPLATES.web ?? []])
   })
 
+  it('normalizes only the exact installation-owned headless bundle tuple', () => {
+    const anchor = stageInstallation({
+      '@deepseek-ai/dsh-base': { patch: '[]\n' },
+      '@deepseek-ai/dsh-web-app': { patch: '[]\n' },
+      '@deepseek-ai/dsh-headless': { patch: '[]\n' },
+      'custom-bundle': { patch: '[]\n' },
+    })
+    const home = tmp()
+    const stock = resolveProfileDir('headless', home)
+    initProfile(stock, [
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless',
+    ])
+    loadProfile('t', 'headless', anchor, home)
+    expect(readProfileManifest('t', stock).dsh?.profile?.bundles)
+      .toEqual(['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'])
+
+    const customHome = tmp()
+    const custom = resolveProfileDir('headless', customHome)
+    initProfile(custom, [
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless', 'custom-bundle',
+    ])
+    loadProfile('t', 'headless', anchor, customHome)
+    expect(readProfileManifest('t', custom).dsh?.profile?.bundles).toEqual([
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless', 'custom-bundle',
+    ])
+  })
+
   it('fails loud when a listed bundle declares no dsh.bundle', () => {
     const anchor = stageInstallation({ 'not-a-bundle': {} })
     const home = tmp()
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 860390d722..eafbe0b0ab 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/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/bundle/README.md
-README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
+README.md: 696aa9ef7bbed23774f2b9ab2648ca83edcf0978
+README.zh.md: 2bb22c7949d759f404288548ea0eccfa0aac866b
diff --git a/packages/bundle/README.md b/packages/bundle/README.md
index af06fe921a..696aa9ef7b 100644
--- a/packages/bundle/README.md
+++ b/packages/bundle/README.md
@@ -8,6 +8,6 @@ Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "pat
 |---|---|---|
 | [`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` |
+| [`headless/`](headless/README.md) | Direct one-shot task mode over base, with no Host or Web layer | 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>`.
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index b965664978..2bb22c7949 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -8,6 +8,6 @@ Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle
 |---|---|---|
 | [`base/`](base/README.md) | 每个 profile 最先应用的共享 dsh 核心 | —（仅 patch） |
 | [`web-app/`](web-app/README.md) | 浏览器表层：web patch 层 + 运行时粘合插件 | 挂载多条配置行 |
-| [`headless/`](headless/README.md) | 叠加在 base + web-app 之上的一次性任务模式 | 挂载 `headless-runner` |
+| [`headless/`](headless/README.md) | 直接运行在 base 之上的一次性任务模式，不含 Host 或 Web 层 | 挂载 `headless-runner` |
 
 内置组合包从 dsh 安装目录解析；树外（out-of-tree）组合包通过 `dsh plugin --profile <name> add <package>` 安装进 profile。
diff --git a/packages/bundle/base/README.i18n.yaml b/packages/bundle/base/README.i18n.yaml
index 2ae7df0bdc..973959478e 100644
--- a/packages/bundle/base/README.i18n.yaml
+++ b/packages/bundle/base/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/bundle/base/README.md
-README.md: 301d397d4c87687b382665cf63af47ab5e3f85be
-README.zh.md: f007bc817b6cbad84725fe8abe72549cf67d8cd7
+README.md: fb003908a262dc21edd3c9d49c972e487534f367
+README.zh.md: 13e64db6d34374fac63bf9bfd60544fc46b86f35
diff --git a/packages/bundle/base/README.md b/packages/bundle/base/README.md
index 301d397d4c..fb003908a2 100644
--- a/packages/bundle/base/README.md
+++ b/packages/bundle/base/README.md
@@ -2,7 +2,7 @@
 
 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 shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, the shared [`agent-default-model`](../../core/agent-default-model/README.md) selection, 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.
 
diff --git a/packages/bundle/base/README.zh.md b/packages/bundle/base/README.zh.md
index f007bc817b..13e64db6d3 100644
--- a/packages/bundle/base/README.zh.md
+++ b/packages/bundle/base/README.zh.md
@@ -2,7 +2,7 @@
 
 [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，绝不通过代码。
+以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、共享的 [`agent-default-model`](../../core/agent-default-model/README.md) 选择、工具、持久化、策略、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)负责渲染它。
 
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index 799affc16b..c512127199 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -65,6 +65,14 @@
     - id: agent
       name: '@deepseek-ai/dsh-agent'
 
+    # The transport-independent default for Agents created by front doors.
+    # Settings may supply a saved selection; consumers read it at creation time.
+    - id: agent-default-model
+      name: '@deepseek-ai/dsh-agent-default-model'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+
     - id: tasks
       name: '@deepseek-ai/dsh-tasks-local'
 
diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json
index 507952b43a..c2cd151b3e 100644
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -35,6 +35,7 @@
     "@cordisjs/plugin-hmr": "workspace:*",
     "@cordisjs/plugin-timer": "workspace:*",
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-bash-env": "workspace:^",
     "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index f1a9d53be8..ea768061df 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: 661b377817482d22f58f22b573075722646729a2
-README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
+README.md: 6faf1dc732345a86ec1d7b60c4f9a606e0491512
+README.zh.md: a189f77f57cf0f641abe7c11288dbc1cdf05355a
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index 661b377817..6faf1dc732 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -2,11 +2,13 @@
 
 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), waits at idle until that mux has consumed the session's final event sequence, 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 run "task"`), and fails loud when the selected profile lacks this row.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A successful run writes nothing to stderr and opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks 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.
+None, as the runner submits the task as an ordinary user message; prompts and tools belong to the base and headless bundle rows.
 
 #### KV Cache effect
 
@@ -14,5 +16,5 @@ 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.
+- **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
 - **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index a6b91a8e60..a189f77f57 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -2,11 +2,13 @@
 
 [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 链路都会真实运行）驱动一个任务轮次，在 idle 时等待该 mux 消费完会话的最终事件序号，再聚合该轮次最终的 assistant 文本，写到 stdout，并经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
+
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。成功运行时不会向 stderr 写入任何内容，也不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
-无。runner 把任务作为普通用户消息经共享组合提交；提示词与工具归 base／web 组合包所有。
+无影响，因为 runner 把任务作为普通用户消息提交；提示词与工具归 base 和 headless 组合包中的相应行所有。
 
 #### KV Cache 影响
 
@@ -14,5 +16,5 @@ dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 ## 已知限制与延期工作
 
-- **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
+- **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
 - **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时大声失败，直到宿主提供该 seam。
diff --git a/packages/bundle/headless/cordis.patch.yml b/packages/bundle/headless/cordis.patch.yml
index 5801a20863..8b147714be 100644
--- a/packages/bundle/headless/cordis.patch.yml
+++ b/packages/bundle/headless/cordis.patch.yml
@@ -1,21 +1,26 @@
-# 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`.
+# The dsh-headless bundle patch: one-shot task mode directly over dsh-base.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. The launcher
+# patches the runner's `task`; the direct driver creates an Agent through the
+# core registry and prints the final durable assistant message.
 
-- id: webserver
+- id: system-prompt
   config:
-    host: 127.0.0.1
-    port: 0
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
 
-- id: web-runtime
+# One-shot runs never watch or reload their composition.
+- id: hmr
+  disabled: true
+
+- id: tools
   config:
-    mode: production
-    printUrl: false
-    surfaceContext: false
+    # Keep the same temporary process-wide Code Mode opt-in as the Web surface.
+    mode: !!js process.env.DSH_TOOLS_MODE
 
 - insert:
+    # Code Mode is a core execution capability, not a Web component.
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
     - id: headless-runner
       name: '@deepseek-ai/dsh-headless'
diff --git a/packages/bundle/headless/package.json b/packages/bundle/headless/package.json
index 2b28423168..bc461e4c72 100644
--- a/packages/bundle/headless/package.json
+++ b/packages/bundle/headless/package.json
@@ -1,6 +1,6 @@
 {
   "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",
+  "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -32,22 +32,23 @@
     }
   },
   "dependencies": {
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
     "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-agent-default-model": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^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-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index 8db505c3ac..670838661a 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -1,36 +1,33 @@
 /**
- * @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 run "task"`).
+ * @deepseek-ai/dsh-headless — one-shot direct Agent driver. The bundle patch
+ * rides over dsh-base without Host, HTTP, or browser plugins; this runner
+ * creates one Agent through the core registry, drives the task to quiescence,
+ * flushes its Session, prints the final assistant text, and exits.
+ *
  * @module @deepseek-ai/dsh-headless
  */
 
+import { randomUUID } from 'node:crypto'
 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'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { ModelSelectionRef } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 // 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']
+/** Core services required before the one-shot turn can start. */
+export const inject = ['agentDefaultModel', 'agents', 'sessions']
 
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 
@@ -38,16 +35,15 @@ 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 {
+/** Outcome of one owned run interval. */
+interface RunOutcome {
   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).
+ * Process-facing effects of one run, injectable for tests. The launcher owns
+ * bounded tree shutdown and wires `exit()` to it.
  */
 export interface HeadlessIo {
   stdout: { write(chunk: string): unknown }
@@ -56,127 +52,91 @@ export interface HeadlessIo {
   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. */
+    /** Process-facing effects provided before the headless tree mounts. */
     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 to the final session-event sequence 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<number>,
-  io: HeadlessIo,
-): Promise<TurnOutcome> {
+/** Aggregate the last assistant text and turn outcome in one owned interval. */
+function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcome {
   let started = false
   let text = ''
-  let reason: string = 'error'
-  let observedSeq = -1
-  let resolveProgress: (() => void) | undefined
-  const streamDone = (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
-        observedSeq = event.seq
-        resolveProgress?.()
-        resolveProgress = undefined
-        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`)
+  let reason = 'error'
+  for (const event of events) {
+    if (event.seq < firstSeq) continue
+    if (event.type === 'turn/start') {
+      started = true
+      continue
     }
-  })()
-  const streamEnded = streamDone.then(() => 'ended' as const)
-  const idleSeq = await idle
-  while (observedSeq < idleSeq) {
-    const progress = new Promise<'progress'>((resolve) => { resolveProgress = () => { resolve('progress') } })
-    if (await Promise.race([progress, streamEnded]) === 'ended') break
+    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
   }
   return { text, reason }
 }
 
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io: HeadlessIo, error: unknown): void {
+  io.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`)
+  io.exit(1)
+}
+
 /**
- * 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}.
+ * Run one task through a freshly created Agent and request process exit.
+ * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+ * @param task - one-shot task text.
+ * @param io - process-facing effects.
+ */
+async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
+  // Loader siblings mount concurrently. Await the complete application before
+  // creating an Agent so its scoped tools and adapters are not half-composed.
+  await ctx.get('loader')?.await()
+  const agents = ctx.get('agents')
+  const defaultModel = ctx.get('agentDefaultModel')
+  const sessions = ctx.get('sessions')
+  // Early process shutdown can dispose the tree while settlement is pending.
+  if (agents === undefined || defaultModel === undefined || sessions === undefined) return
+
+  const selection = defaultModel.currentSelection()
+  const { agent } = await agents.create({
+    sessionId: SessionId(`session-${randomUUID()}`),
+    meta: { cwd: process.cwd() },
+    agentOptions: { provider: selection.provider, model: selection.model },
+    setup: (agentCtx) => {
+      const selected: ModelSelectionRef = { current: selection, assembled: undefined }
+      installModelSelection(agentCtx, selected)
+    },
+  })
+  await agent.whenIdle()
+  const firstSeq = agent.session.seq
+  agent.followup(createUserMessage({
+    content: [{ type: 'text', text: task }],
+    source: { kind: 'user' },
+  }))
+  await agent.whenIdle()
+  await sessions.flush(agent.session)
+  const outcome = summarize(agent.session.events, firstSeq)
+  io.stdout.write(outcome.text + '\n')
+  io.exit(outcome.reason === 'completed' ? 0 : 1)
+}
+
+/**
+ * Mount the one-shot direct driver.
+ * @param ctx - plugin context carrying core services and the launcher-owned IO seam.
+ * @param config - validated task 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<number>((resolve) => {
-      ctx.on('agent/status', ({ agent, status }) => {
-        if (agent.id === created.sessionId && status === 'idle') resolve(agent.session.seq - 1)
-      })
-    })
-    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)
-  })()
+  void run(ctx, config.task, io).catch((error: unknown) => { fail(io, error) })
 }
diff --git a/packages/bundle/headless/tests/headless.spec.ts b/packages/bundle/headless/tests/headless.spec.ts
index 9408ee62bf..294c224354 100644
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -1,170 +1,163 @@
-/**
- * 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.
- */
+/** Direct one-shot Agent driving, durable aggregation, flushing, and exit mapping. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
+import AgentDefaultModelService from '@deepseek-ai/dsh-agent-default-model'
+import { createAssistantMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
 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 Script {
+  before?(session: Session): void
+  afterPrompt(session: Session, message: UserMessage): Promise<void> | void
 }
 
-interface RpcShapedRequest { rpcId: string }
-
-interface ScriptedApiOptions {
-  promptFails?: boolean
-  framesAfterPrompt?: boolean
-  onPrompt?: () => void
+function appendTurn(
+  session: Session,
+  turn: number,
+  message: UserMessage,
+  text: string | undefined,
+  completed: boolean,
+): void {
+  session.append('turn/start', { turn })
+  session.append('step/start', { turn, step: 1 })
+  session.append('user/message', message, { surfaceOp: 'append' })
+  if (text !== undefined) {
+    session.append('assistant/message', {
+      turn,
+      step: 1,
+      message: createAssistantMessage({
+        content: [{ type: 'text', text }],
+        source: { provider: 'test-provider', model: 'test-model' },
+      }),
+    }, { surfaceOp: 'append' })
+  }
+  session.append('step/end', { turn, step: 1 })
+  session.append('turn/end', {
+    turn,
+    reason: completed
+      ? { kind: 'completed' }
+      : { kind: 'aborted', reason: { kind: 'user' } },
+  })
 }
 
-/** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
-function scriptedApi(events: ScriptedEvent[], options: ScriptedApiOptions = {}): unknown {
-  let releaseFrames = (): void => {}
-  const framesReady = options.framesAfterPrompt === true
-    ? new Promise<void>((resolve) => { releaseFrames = resolve })
-    : Promise.resolve()
-  const prepared = events.map((event) => {
-    if (event.type === 'stream/error') return { streamError: true } as const
-    const { sessionId = 'S1', ...rest } = event
-    return { streamError: false, sessionId, event: stamped(rest) } as const
+/** Mount the real registries around a small scripted Agent factory. */
+async function bench(script: Script): Promise<{
+  ctx: Context
+  run(): Promise<{ code: number; out: string; err: string; order: string[] }>
+}> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentDefaultModelService, { provider: 'test-provider', model: 'test-model' })
+  ctx.agents.setFactory({
+    async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle> {
+      const session = ctx.sessions.create(options.sessionId, {
+        ...options.meta === undefined ? {} : { meta: options.meta },
+      })
+      let idle = Promise.resolve()
+      const agent = {} as Agent
+      const agentCtx = ownerCtx.extend({ agent })
+      Object.assign(agent, {
+        id: session.id,
+        options: options.agentOptions ?? {},
+        session,
+        inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+        status: 'idle',
+        ctx: agentCtx,
+        cancel: () => {},
+        runMaintenance: () => Promise.reject(new Error('not used')),
+        send: () => {},
+        followup: (message: UserMessage) => {
+          agent.inbox.append('next-turn', message)
+          idle = Promise.resolve().then(() => script.afterPrompt(session, message))
+        },
+        steer: () => {},
+        inject: () => {},
+        whenIdle: () => idle,
+      } satisfies Partial<Agent>)
+      await options.setup?.(agentCtx)
+      script.before?.(session)
+      ctx.agents.register(agent)
+      return { agent, dispose: () => Promise.resolve() }
+    },
+    resume: () => Promise.reject(new Error('not used')),
   })
   return {
-    sessions: {
-      create: (request: RpcShapedRequest) =>
-        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-      prompt: (request: RpcShapedRequest) => {
-        releaseFrames()
-        options.onPrompt?.()
-        return 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* () {
-        await framesReady
-        for (const item of prepared) {
-          if (item.streamError) {
-            yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
-            continue
-          }
-          yield { rpcId: 'e', payload: { type: 'session/event', sessionId: item.sessionId, event: item.event } }
+    ctx,
+    run: async () => {
+      let out = ''
+      let err = ''
+      const order: string[] = []
+      ctx.on('session/flush', () => { order.push('flush') })
+      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: (code) => { order.push('exit'); resolve(code) },
         }
-      },
+        ctx.provide('headlessIo', io)
+      })
+      apply(ctx, { task: 'do the thing' })
+      return { code: await exited, out, err, order }
     },
   }
 }
 
-/**
- * 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; framesAfterPrompt?: boolean; idleInPrompt?: 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)
-  })
-  const emitIdle = (): void => {
-    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
-  }
-  ctx.provide('apiProxy', scriptedApi(events, {
-    ...options.promptFails === undefined ? {} : { promptFails: options.promptFails },
-    ...options.framesAfterPrompt === undefined ? {} : { framesAfterPrompt: options.framesAfterPrompt },
-    ...options.idleInPrompt === true ? { onPrompt: emitIdle } : {},
-  }) 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.
-  if (options.idleInPrompt !== true) {
-    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' })
-    emitIdle()
-  }
-  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('aggregates the final text across the complete idle-to-idle interval and flushes before exit', async () => {
+    const test = await bench({
+      before(session) {
+        const setupMessage = {
+          role: 'user', content: [{ type: 'text', text: 'setup' }], source: { kind: 'user' }, id: 'setup',
+        } as UserMessage
+        appendTurn(session, 0, setupMessage, 'pre-task noise', true)
+      },
+      async afterPrompt(session, message) {
+        await Promise.resolve()
+        appendTurn(session, 1, message, '', true)
+        appendTurn(session, 2, message, 'final answer', true)
+      },
+    })
+    const result = await test.run()
+    expect(result).toEqual({
+      code: 0,
+      out: 'final answer\n',
+      err: '',
+      order: ['flush', 'exit'],
+    })
+    await test.ctx.fiber.dispose()
   })
 
-  it('consumes through the idle sequence when queued frames arrive after the status transition', async () => {
-    const { code, out } = await run(
-      [messageTurn, text(1, 'race-free answer'), end(1, 'completed')],
-      { framesAfterPrompt: true, idleInPrompt: true },
-    )
-    expect(code).toBe(0)
-    expect(out).toBe('race-free answer\n')
+  it('waits for asynchronously appended events instead of racing Agent idleness', async () => {
+    const test = await bench({
+      afterPrompt: async (session, message) => {
+        await new Promise(resolve => setTimeout(resolve, 5))
+        appendTurn(session, 1, message, 'race-free answer', true)
+      },
+    })
+    expect(await test.run()).toMatchObject({ code: 0, out: 'race-free answer\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  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 the final turn does not complete', async () => {
+    const test = await bench({
+      afterPrompt(session, message) { appendTurn(session, 1, message, undefined, false) },
+    })
+    expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  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('exits 1 when the owned interval contains no turn', async () => {
+    const test = await bench({ afterPrompt: () => {} })
+    expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  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 () => {
+  it('reports a direct Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
     const exited = new Promise<number>((resolve) => {
@@ -174,15 +167,16 @@ describe('headless runner', () => {
         exit: resolve,
       } satisfies HeadlessIo)
     })
-    ctx.provide('apiProxy', scriptedApi([messageTurn, end(1, 'completed')], { promptFails: true }) as never)
-    ctx.provide('httpServer', { port: 1 } as never)
+    ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+    ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
+    ctx.provide('agents', { create: () => Promise.reject(new Error('factory exploded')) } as never)
     apply(ctx, { task: 't' })
     expect(await exited).toBe(1)
-    expect(err).toContain('agent-busy')
+    expect(err).toBe('dsh: factory exploded\n')
     await ctx.fiber.dispose()
   })
 
-  it('reports the stream-failed diagnostic when the event channel dies, still settling at idle', async () => {
+  it('stringifies a non-Error Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
     const exited = new Promise<number>((resolve) => {
@@ -192,67 +186,52 @@ describe('headless runner', () => {
         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 } } }),
+    ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+    ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
+    const rejected = {
+      then(_resolve: (value: never) => void, reject: (reason: unknown) => void): void {
+        reject('factory exploded')
       },
-      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)
+    }
+    ctx.provide('agents', { create: () => rejected } as never)
     apply(ctx, { task: 't' })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
     expect(await exited).toBe(1)
-    expect(err).toContain('event stream failed')
+    expect(err).toBe('dsh: factory exploded\n')
     await ctx.fiber.dispose()
   })
 
-  it('waits for Loader settlement and abandons the run when the tree died during it', async () => {
+  it('abandons a run when the tree is disposed during Loader settlement', async () => {
     const ctx = new Context()
-    let err = ''
     let exited = false
     ctx.provide('headlessIo', {
       stdout: { write: () => true },
-      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      stderr: { write: () => 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)
+    const services = ctx.plugin((child: Context) => {
+      child.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+      child.provide('sessions', {} as never)
+      child.provide('agents', {} as never)
     })
-    await webserverFiber
+    await services
     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()
+    await services.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({} as never)).toThrow()
     expect(new Config({ task: 'x' })).toEqual({ task: 'x' })
   })
 })
diff --git a/packages/bundle/headless/tsconfig.json b/packages/bundle/headless/tsconfig.json
index 7894985500..9ae3212f6b 100644
--- a/packages/bundle/headless/tsconfig.json
+++ b/packages/bundle/headless/tsconfig.json
@@ -17,15 +17,15 @@
     {
       "path": "../../../vendor/schemastery"
     },
-    {
-      "path": "../../host/apiproxy"
-    },
-    {
-      "path": "../../host/webserver"
-    },
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../core/agent-default-model"
+    },
+    {
+      "path": "../../llm/llm"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 25bf18dc45..35f9bb4286 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/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/bundle/web-app/README.md
-README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: bd14fe03d222f788563df0b562f86446df70b827
+README.md: d89ae4a7e28506166498caf0032f864bbb109cc5
+README.zh.md: 3c02ed81b0d34d0f8ec597e9dbea2690151ea5e3
diff --git a/packages/bundle/web-app/README.md b/packages/bundle/web-app/README.md
index dc35cb4b59..d89ae4a7e2 100644
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -2,7 +2,7 @@
 
 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 cache, storage) and the browser plugin roster, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, 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 when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top, silences the URL line, and disables the surface context.
+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 cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, 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 when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
 
 ## Model Experience
 
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index bd14fe03d2..3c02ed81b0 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -2,7 +2,7 @@
 
 [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, surfaceContext, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层，关闭 URL 行并禁用表层上下文。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
 
 ## 模型体验
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 62ed35bd49..d4fb2e8511 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -72,13 +72,9 @@
       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).
+    # shares. The base layer's agent-default-model service owns the default model.
     - id: api-gateway
       name: '@deepseek-ai/dsh-host-apiproxy'
-      config:
-        provider: deepseek-official
-        model: deepseek-v4-flash
 
     # ── layer 2: transport/service ──────────────────────────────────────────────
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index 6f29b2dda0..c373376710 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -12,7 +12,7 @@ export type {
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels,
   GoalsApi, GoalRef,
   SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
   CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi,
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 2a081284b2..24f5668d42 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -30,7 +30,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 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,
+  ModelProviderGroup, ModelSelection, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
   ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -1347,7 +1347,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, blank: false, cwd: '/tmp/fixture' },
   ]
   const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
-  const modelTargets = new Map<SessionId, ModelTarget>(sessions.map(session => [
+  const modelSelections = new Map<SessionId, ModelSelection>(sessions.map(session => [
     session.sessionId,
     { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
   ]))
@@ -1989,7 +1989,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
           sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: true, cwd,
         }
         sessions.push(created)
-        modelTargets.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+        modelSelections.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
         attachedSessions += 1
         const emitSession = (): void => {
           // Mirrors the host: the frame fires at creation, so blank is constantly true.
@@ -2098,7 +2098,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         return ok(request, { ...page, ...projections === undefined ? {} : { projections } })
       },
       models: request => ok(request, {
-        current: modelTargets.get(request.payload.sessionId)
+        current: modelSelections.get(request.payload.sessionId)
           ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
         // The fixture's routes all serve; a surface exercising the blocked
         // posture drives it through its own stub.
@@ -2107,14 +2107,14 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         failures: [],
       }),
       selectModel: (request) => {
-        const selected: ModelTarget = {
+        const selected: ModelSelection = {
           provider: request.payload.provider,
           model: request.payload.model,
           ...request.payload.reasoningEffort === undefined
             ? {}
             : { reasoningEffort: request.payload.reasoningEffort },
         }
-        modelTargets.set(request.payload.sessionId, selected)
+        modelSelections.set(request.payload.sessionId, selected)
         return ok(request, { selected })
       },
       prompt: (request) => {
@@ -2153,11 +2153,11 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         // Capacity parallel of the host token-meter's request/context record:
         // log-only, appended inside the open turn, and deduplicated against the
         // route already recorded (the fixture never varies contextWindow).
-        const target = modelTargets.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
-        if (lastRequestContext(logOf(id))?.model !== target.model) {
+        const selection = modelSelections.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
+        if (lastRequestContext(logOf(id))?.model !== selection.model) {
           append(id, {
             type: 'request/context',
-            data: { provider: target.provider, model: target.model, contextWindow: 128_000 },
+            data: { provider: selection.provider, model: selection.model, contextWindow: 128_000 },
           })
         }
         startReply(
@@ -2167,9 +2167,9 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
             ? MARKDOWN_FIXTURE
             : userText === 'report model'
               ? (() => {
-                const target = modelTargets.get(id)
-                return `当前模型：${target?.provider ?? 'unknown'}/${target?.model ?? 'unknown'}`
-                  + (target?.reasoningEffort === undefined ? '' : ` · 推理等级：${target.reasoningEffort}`)
+                const selection = modelSelections.get(id)
+                return `当前模型：${selection?.provider ?? 'unknown'}/${selection?.model ?? 'unknown'}`
+                  + (selection?.reasoningEffort === undefined ? '' : ` · 推理等级：${selection.reasoningEffort}`)
               })()
               : `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`,
         )
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index c2a6668d46..e14a0764a8 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -20,7 +20,7 @@ export type {
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  MessageId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  MessageId, ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels,
   SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt,
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index ef5071316e..c61b97833b 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  CommandDescriptor, HostFrame, IApiClient, ModelSelection, MuxFrame,
   RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
 } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
@@ -50,11 +50,11 @@ export class FakeApiClient implements IApiClient {
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelTarget: ModelTarget }>> =
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelSelection: ModelSelection }>> =
     () => Promise.resolve(ok({
       events: [],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' },
     }))
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
@@ -63,8 +63,8 @@ export class FakeApiClient implements IApiClient {
     groups: [],
     failures: [],
   }))
-  onSelectModel: (payload: ModelTarget & { sessionId: SessionId })
-  => Promise<RpcResponse<{ selected: ModelTarget }>> =
+  onSelectModel: (payload: ModelSelection & { sessionId: SessionId })
+  => Promise<RpcResponse<{ selected: ModelSelection }>> =
     payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onUpdateQueue: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
@@ -105,7 +105,7 @@ export class FakeApiClient implements IApiClient {
     history: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) =>
       this.record('session.history', payload, this.onHistory(payload)),
     models: (payload: unknown) => this.record('session.models', payload, this.onModels(payload)),
-    selectModel: (payload: ModelTarget & { sessionId: SessionId }) =>
+    selectModel: (payload: ModelSelection & { sessionId: SessionId }) =>
       this.record('session.selectModel', payload, this.onSelectModel(payload)),
     rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)),
     fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)),
diff --git a/packages/client/connection/tests/fixture.spec.ts b/packages/client/connection/tests/fixture.spec.ts
index f608190936..53b68ca786 100644
--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -168,7 +168,7 @@ describe('createFixtureApi', () => {
     })
   })
 
-  it('serves grouped models and keeps a selected target for later history and fixture requests', async () => {
+  it('serves grouped models and keeps a selection for later history and fixture requests', async () => {
     const api = createFixtureApi()
     const sessionId = sid('fx-alpha')
     const catalog = await api.sessions.models(req({ sessionId }))
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index f9af3fb8fe..930a12dea3 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
-README.zh.md: 41c81532667f445ce1c52e1b84185ef503e82141
+README.md: c2ce461439a89aa4fe2d59ebf92d14539479dac8
+README.zh.md: bca93b80989152eccccaf13c0f31435c91e7393c
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index a9b6049745..c2ce461439 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -62,7 +62,7 @@ The Session object validates plugin-owned, provider-routed `llm/retry` payloads
 
 ## Session model selection
 
-Each resident `Session` owns a `modelSelection` snapshot containing the current provider/model target, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current target, opening a selector refreshes the directory, and selection failures preserve the last target and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the target reported by the Host without replacing unchanged selection substructure.
+Each resident `Session` owns a `modelSelection` snapshot containing the current `ModelSelection`, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current selection, opening a selector refreshes the directory, and selection failures preserve the last selection and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the selection reported by the Host without replacing unchanged selection substructure.
 
 ## Model Experience
 
@@ -70,7 +70,7 @@ None, as the session object layer selects the provider/model route used by a lat
 
 #### KV Cache effect
 
-Changing the target can change or invalidate provider-side cache reuse; this package does not alter the prompt prefix itself.
+Changing the model selection can change or invalidate provider-side cache reuse; this package does not alter the prompt prefix itself.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 41c8153266..bca93b8098 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -62,7 +62,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 ## 会话模型选择
 
-每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。
+每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前 `ModelSelection`、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前选择，打开选择器会刷新目录；选择失败会保留上一个选择和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的选择，同时不替换未变化的选择子结构。
 
 ## 模型体验
 
@@ -70,7 +70,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 #### KV Cache 影响
 
-更改目标可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
+更改模型选择可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index 5e510c0012..80f45db067 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  ClientResponse, CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  ClientResponse, CommandDescriptor, HostFrame, IApiClient, ModelSelection, MuxFrame,
   RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
@@ -64,7 +64,7 @@ export class FakeApiClient implements IApiClient {
   onSearch: (payload: unknown) => Promise<RpcResponse<{ items: SessionSearchItem[]; hasMore: boolean }>> =
     () => Promise.resolve(ok({ items: [], hasMore: false }))
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
-  readonly defaultModel: ModelTarget = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
+  readonly defaultModel: ModelSelection = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
@@ -82,7 +82,7 @@ export class FakeApiClient implements IApiClient {
     failures: [],
   }))
   onSelectModel: (payload: { provider: string; model: string }) =>
-  Promise<RpcResponse<{ selected: ModelTarget }>> =
+  Promise<RpcResponse<{ selected: ModelSelection }>> =
     payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onUpdateQueue: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
diff --git a/packages/client/runtime/tests/manager.spec.ts b/packages/client/runtime/tests/manager.spec.ts
index e203e49dd9..c69465df45 100644
--- a/packages/client/runtime/tests/manager.spec.ts
+++ b/packages/client/runtime/tests/manager.spec.ts
@@ -842,7 +842,7 @@ describe('connected generation', () => {
     api.onHistory = () => Promise.resolve(ok({
       events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' },
     }))
     const manager = new SessionManager(api)
     const openedSession = manager.get(S1)
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 5d5f292f92..834f37d434 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -89,7 +89,7 @@ describe('open', () => {
     gate.resolve(ok({
       events: entries(page) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await opening
     const seqs = session.getSnapshot().nodes.map(n => n.seq)
@@ -631,7 +631,7 @@ describe('paging', () => {
     gate.resolve(ok({
       events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await Promise.all([first, second])
     expect(api.callsOf('session.history')).toHaveLength(2) // open + one page, not two
@@ -1018,7 +1018,7 @@ describe('remaining branches', () => {
     stale.resolve(ok({
       events: entries(plainTurn(0, 0, '旧', '代')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'stale' },
+      modelSelection: { provider: 'deepseek-official', model: 'stale' },
     })) // success, but its generation is gone
     await Promise.all([opening, resynced])
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9]) // only the fresh generation's window
@@ -1041,7 +1041,7 @@ describe('remaining branches', () => {
     secondPull.resolve(ok({
       events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'stale' },
+      modelSelection: { provider: 'deepseek-official', model: 'stale' },
     }))
     await Promise.all([opening, resynced])
     expect(session.getSnapshot().openState).toBe('open')
@@ -1059,7 +1059,7 @@ describe('remaining branches', () => {
     repairPull.resolve(ok({
       events: entries(plainTurn(0, 0, '旧', '页')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'stale' },
+      modelSelection: { provider: 'deepseek-official', model: 'stale' },
     })) // repair result: stale, dropped
     await resynced
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
@@ -1104,7 +1104,7 @@ describe('remaining branches', () => {
         { event: ev.toolResult(7, 1, 'h1', 'done'), view: { for: 'result', view: { card: 'generic', title: '历史果' } } },
       ] as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await session.open()
     expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index a909395148..e630daf0fa 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/ui-model/README.md
-README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
-README.zh.md: 55ea296370ffa986c9b11b41f83ef83b12236e88
+README.md: b37f807944850fb34331cd8d78b4a2ccf157f21c
+README.zh.md: 906096bed06af26517e215b2d1e1da4b62e58095
diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md
index 5a6f998476..b37f807944 100644
--- a/packages/client/ui-model/README.md
+++ b/packages/client/ui-model/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Model selection plugin, browser half: TWO entries over ONE per-session directory owned by `ModelService` (`ctx.models`). For ordinary sessions, the `/model` popupSelect contribution (registered through `ctx.command`) and the composer's named `conversation.input.model` seat both load the session's advisory directory through `session.models` and submit through `session.selectModel` via the same `ModelDirectory` instance. The compact composer trigger opens a two-level Model/Effort menu: models stay provider-grouped, while the selected exact model supplies its adapter-owned effort names, descriptions, and default. `/model` applies the selected model's default effort, and the composer can then choose any advertised effort.
 
-The Host-reported provider/model/reasoning target is the single selection fact, but it is echoed only when the exact route remains in the advertised groups; removing that catalog row leaves the routable target intact while the trigger prompts `Select model`, no stale row is synthesized, and no Effort row is shown until the user picks an advertised model. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored target before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior target and directory.
+The Host-reported provider/model/reasoning `ModelSelection` is the single selection fact, but it is echoed only when the exact provider/model pair remains in the advertised groups; an absent catalog row leaves the routable selection intact while the trigger prompts `Select model`, no stale row is synthesized, and no Effort row is shown until the user picks an advertised model. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored selection before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior selection and directory.
 
 When the Host reports that no adapter serves the session's route (`session.models.routable`), this plugin raises a composer block through `ctx.conversation.blocks` and the input goes inert with this plugin's own copy; recovering clears it without a reload. It follows `routable` and nothing else: a `null` — before the first load, or after one failed — never blocks, or a slow Host would lock a working composer, and catalog membership never blocks either, because a route serving a model it stopped advertising is missing from the groups yet perfectly usable. The trigger's own `Select model` fallback still covers that case, which is display, not a gate.
 
@@ -14,7 +14,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`), `ModelServic
 
 ## Model Experience
 
-Indirectly, through the `session.selectModel` RPC available to ordinary sessions, both entries submit the provider/model/reasoning target that the Host snapshots at the next prompt-assembly boundary, so the following request uses the chosen route and effort while a running step keeps its assembled target; the selection becomes durable only when the existing request header records a request that consumes it, and menu interaction adds no prompt content.
+Indirectly, through the `session.selectModel` RPC available to ordinary sessions, both entries submit the complete `ModelSelection` that the Host snapshots at the next prompt-assembly boundary, so the following request uses the selected provider, model, and effort while a running step keeps its assembled selection; the selection becomes durable only when the existing request header records a request that consumes it, and menu interaction adds no prompt content.
 
 #### KV Cache effect
 
@@ -22,6 +22,6 @@ Switching the route can reduce or invalidate provider-side cache reuse for subse
 
 ## Known Limitations and Deferred Work
 
-- **No create-time or addressed-subagent selection** — both entries require an existing ordinary session's Agent; there is no draft-phase model choice to fold into session creation, and subagent continuation deliberately exposes no independent model-retargeting contract.
+- **No create-time or addressed-subagent selection** — both entries require an existing ordinary session's Agent; there is no draft-phase model choice to fold into session creation, and subagent continuation deliberately exposes no independent model-selection contract.
 - **Directory names are presentation-only** — selection and persistence use provider/model/effort ids; a provider whose catalog or exact-model metadata lookup fails lists as an unselectable failure row until reload.
 - **No arbitrary effort input** — the composer offers only the exact model's adapter-advertised levels; an adapter without reasoning metadata leaves the Effort row absent.
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 55ea296370..906096bed0 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -4,7 +4,7 @@
 
 模型选择插件（浏览器侧）：**两个入口共用一份会话级目录**，由 `ModelService`（`ctx.models`）持有。对于普通会话，`/model` popupSelect 贡献项（经 `ctx.command` 注册）与 composer 的具名 `conversation.input.model` slot 都通过同一个 `ModelDirectory` 实例，经 `session.models` 加载会话的建议目录，并经 `session.selectModel` 提交。紧凑型 composer 触发器会打开两级 Model/Effort 菜单：模型仍按提供方分组，所选具体模型则提供由其适配器持有的推理强度名称、说明和默认值。`/model` 应用所选模型的默认推理强度，composer 随后可以选择任一已公布的推理强度。
 
-Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择事实，但只有当该精确路由仍在已公布分组中时才会回显；删除该目录行会保留仍可路由的目标，但触发器会提示 `Select model`，系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。
+Host 报告的 `ModelSelection` 是唯一的选择事实，其中包含提供方、模型与推理（reasoning）强度；但只有当该提供方／模型对仍在已公布分组中时才会回显。目录行缺席时，可路由的选择保持不变，但触发器会提示 `Select model`；系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的选择。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的选择和目录。
 
 当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 注册一个 composer 阻塞块，输入框随之停用并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来可用的 composer；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
 
@@ -14,7 +14,7 @@ Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择
 
 ## 模型体验
 
-间接影响。两个入口都通过仅供普通会话使用的 `session.selectModel` RPC 提交提供方／模型／推理强度目标；Host 会在下一次提示词组装边界对该目标进行快照，因此后续请求采用所选路由和推理强度，而运行中的步骤保留已组装目标。只有当现有请求头记录一次实际采用该选择的请求后，选择才会持久化；菜单交互不会添加提示词内容。
+间接影响。两个入口都通过仅供普通会话使用的 `session.selectModel` RPC 提交完整的 `ModelSelection`；Host 会在下一次提示词组装边界对其进行快照，因此后续请求采用所选提供方、模型与推理强度，而运行中的步骤保留已组装选择。只有当现有请求头记录一次实际采用该选择的请求后，选择才会持久化；菜单交互不会添加提示词内容。
 
 #### KV Cache 影响
 
@@ -22,6 +22,6 @@ Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择
 
 ## 已知限制与暂缓事项
 
-- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立更改模型目标的约定。
+- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立的模型选择约定。
 - **目录名仅供呈现**——选择与持久化使用提供方／模型／推理强度 id；目录查询或确切模型元数据查询失败的提供方以不可选失败行列出，重新加载前保持原样。
 - **不能任意输入推理强度**——composer 仅提供确切模型由适配器公布的推理强度；适配器没有推理元数据时不显示 Effort 行。
diff --git a/packages/client/ui-model/src/client/ModelSelect.tsx b/packages/client/ui-model/src/client/ModelSelect.tsx
index 343243a28c..6b7bfd19b9 100644
--- a/packages/client/ui-model/src/client/ModelSelect.tsx
+++ b/packages/client/ui-model/src/client/ModelSelect.tsx
@@ -14,7 +14,7 @@ import {
   type KeyboardEvent, type FocusEvent,
 } from 'react'
 import clsx from 'clsx'
-import type { ModelReasoningEffort, ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelReasoningEffort, ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import {
   IconCheckOutline16, IconChevronDownOutline14, IconChevronRightOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -58,17 +58,17 @@ export function ModelSelect(
     group.models.map(model => ({
       group,
       model,
-      target: {
+      selection: {
         provider: group.id,
         model: model.id,
         ...model.reasoning?.defaultEffort === undefined
           ? {}
           : { reasoningEffort: model.reasoning.defaultEffort },
-      } satisfies ModelTarget,
+      } satisfies ModelSelection,
     }))), [state.groups])
   const selectedIndex = state.current === null
     ? -1
-    : choices.findIndex(c => c.target.provider === state.current?.provider && c.target.model === state.current.model)
+    : choices.findIndex(c => c.selection.provider === state.current?.provider && c.selection.model === state.current.model)
   const currentChoice = choices[selectedIndex]
   const reasoning = currentChoice?.model.reasoning
   const effectiveEffort = state.current?.reasoningEffort ?? reasoning?.defaultEffort
@@ -148,12 +148,12 @@ export function ModelSelect(
     close()
   }
 
-  const choose = (target: ModelTarget): void => {
-    if (state.current?.provider === target.provider && state.current.model === target.model) {
+  const choose = (selection: ModelSelection): void => {
+    if (state.current?.provider === selection.provider && state.current.model === selection.model) {
       close(true)
       return
     }
-    void select(target).then((accepted) => {
+    void select(selection).then((accepted) => {
       if (accepted && rootRef.current !== null) close(true)
     })
   }
@@ -164,12 +164,12 @@ export function ModelSelect(
       close(true)
       return
     }
-    const target: ModelTarget = {
+    const selection: ModelSelection = {
       provider: state.current.provider,
       model: state.current.model,
       ...effort === undefined ? {} : { reasoningEffort: effort },
     }
-    void select(target).then((accepted) => {
+    void select(selection).then((accepted) => {
       if (accepted && rootRef.current !== null) close(true)
     })
   }
diff --git a/packages/client/ui-model/src/client/directory.ts b/packages/client/ui-model/src/client/directory.ts
index 8432cf1b77..1555a2df43 100644
--- a/packages/client/ui-model/src/client/directory.ts
+++ b/packages/client/ui-model/src/client/directory.ts
@@ -6,17 +6,17 @@
  * either entry is what the other shows next.
  */
 import type {
-  IApiClient, ModelCatalogFailure, ModelProviderGroup, ModelTarget, SessionId, SessionModels,
+  IApiClient, ModelCatalogFailure, ModelProviderGroup, ModelSelection, SessionId, SessionModels,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** Directory snapshot both entries render from. */
 export interface ModelDirectoryState {
-  /** Target the host reports for the next assembled step; null before the first load. */
-  current: ModelTarget | null
+  /** Model selection the host reports for the next assembled step; null before the first load. */
+  current: ModelSelection | null
   /**
-   * Whether an adapter serves the current target's route, as the host reports
+   * Whether an adapter serves the current selection's provider, as the host reports
    * it — null before the first load, which is NOT the same as blocked. Read
    * this rather than "current matches no group": catalog membership is
    * advisory, so a route serving a model it stopped advertising is missing
@@ -57,7 +57,7 @@ export class ModelDirectory {
 
   /**
    * Refresh the advisory directory (both entries call this on open).
-   * Failure preserves the last good groups and current target.
+   * Failure preserves the last good groups and current selection.
    * @returns the fresh directory value.
    */
   async load(): Promise<SessionModels> {
@@ -86,22 +86,22 @@ export class ModelDirectory {
   }
 
   /**
-   * Select the complete provider/model/reasoning target (both entries submit through here). Success
+   * Select the complete provider/model/reasoning selection (both entries submit through here). Success
    * updates the shared current; failure surfaces on the store and throws so
    * each entry's own retry surface engages.
-   * @param target - provider, provider-owned model id, and optional adapter-owned effort.
-   */
-  async select(target: ModelTarget): Promise<void> {
+   * @param selection - provider, provider-owned model id, and optional adapter-owned effort.
+ */
+  async select(selection: ModelSelection): Promise<void> {
     this.assertAvailable()
     const generation = ++this.generation
     this.store.update((s) => { s.status = 'selecting'; s.error = null })
     const { result } = await this.sessions.selectModel({
       sessionId: this.sessionId,
-      provider: target.provider,
-      model: target.model,
-      ...target.reasoningEffort === undefined
+      provider: selection.provider,
+      model: selection.model,
+      ...selection.reasoningEffort === undefined
         ? {}
-        : { reasoningEffort: target.reasoningEffort },
+        : { reasoningEffort: selection.reasoningEffort },
     })
     if (this.disposed || generation !== this.generation) {
       if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`)
@@ -124,7 +124,7 @@ export class ModelDirectory {
   /**
    * Drop the previous Host generation's projection and repull it. Clearing
    * first prevents an unconsumed process-local selection from being displayed
-   * while the restarted Host has restored the last logged request target.
+   * while the restarted Host has restored the last logged model selection.
    */
   resetConnected(): void {
     if (this.disposed) return
diff --git a/packages/client/ui-model/src/client/index.ts b/packages/client/ui-model/src/client/index.ts
index 68a82bd20a..f55cb83c1c 100644
--- a/packages/client/ui-model/src/client/index.ts
+++ b/packages/client/ui-model/src/client/index.ts
@@ -4,14 +4,14 @@
  * contribution and the composer's named `conversation.input.model` seat both
  * load the session's provider-grouped advisory directory (`session.models`)
  * and submit through `session.selectModel` via the same directory instance,
- * so the host-reported current target is the single fact both surfaces echo
+ * so the host-reported current selection is the single fact both surfaces echo
  * — a switch made in either entry is what the other shows next. Failures
  * ride each entry's own retry surface (popup shell error/retry; seat menu
  * inline error) without forking the state. Addressed subagent sessions expose
  * neither entry because those Agent-bound RPCs would activate persisted
  * history outside the direct-parent continuation seam.
  */
-import type { ModelTarget, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { CommandServiceContract, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.model seat).
@@ -68,13 +68,13 @@ function optionsOf(directory: SessionModels, t: TranslateNS<'model'>): SelectOpt
 }
 
 /**
- * Resolve a picked row back to its target by matching against the loaded
+ * Resolve a picked row back to its model selection by matching against the loaded
  * groups (the same data the rows were built from — ids stay opaque).
  * @param state - the session's directory snapshot.
  * @param id - the picked row id.
- * @returns the row's target, or undefined for failure rows / stale ids.
+ * @returns the row's model selection, or undefined for failure rows / stale ids.
  */
-function targetOf(state: ModelDirectoryState, id: string): ModelTarget | undefined {
+function selectionOf(state: ModelDirectoryState, id: string): ModelSelection | undefined {
   for (const group of state.groups) {
     for (const model of group.models) {
       if (rowId(group.id, model.id) !== id) continue
@@ -139,11 +139,11 @@ export function apply(ctx: ClientContext): void {
             throw new Error('model selection is unavailable for addressed subagent sessions')
           }
           const directory = models.directoryFor(session.sessionId)
-          const target = targetOf(directory.store.getSnapshot(), option.id)
-          if (target === undefined) {
+          const selection = selectionOf(directory.store.getSnapshot(), option.id)
+          if (selection === undefined) {
             throw new Error('this provider\'s catalog failed to load — pick a model from a loaded group')
           }
-          await directory.select(target)
+          await directory.select(selection)
         },
       },
     }), 'ui-model: /model contribution')
@@ -165,8 +165,8 @@ export function apply(ctx: ClientContext): void {
           load: () => {
             if (available) directory.load().catch(() => { /* surfaced on the store */ })
           },
-          select: (target: ModelTarget) => available
-            ? directory.select(target).then(() => true, () => false)
+          select: (selection: ModelSelection) => available
+            ? directory.select(selection).then(() => true, () => false)
             : Promise.resolve(false),
         }
       },
diff --git a/packages/client/ui-model/src/client/slots.ts b/packages/client/ui-model/src/client/slots.ts
index 3d408de232..e3e3957726 100644
--- a/packages/client/ui-model/src/client/slots.ts
+++ b/packages/client/ui-model/src/client/slots.ts
@@ -4,7 +4,7 @@
  * entry; this package only contributes the single occupant, so no SlotMap
  * merge lives here.
  */
-import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ModelDirectoryState } from './directory.ts'
 
@@ -17,9 +17,9 @@ export interface ModelSelectInjected {
   /** Refresh the advisory directory (fire-and-forget; errors land on the store). */
   load: () => void
   /**
-   * Select a complete provider/model/reasoning target through the shared route.
-   * @param target - model target and optional adapter-owned effort.
+   * Select a complete provider/model/reasoning selection.
+   * @param selection - model selection and optional adapter-owned effort.
    * @returns whether the host accepted the selection.
    */
-  select: (target: ModelTarget) => Promise<boolean>
+  select: (selection: ModelSelection) => Promise<boolean>
 }
diff --git a/packages/client/ui-model/tests/browser-plugin.spec.ts b/packages/client/ui-model/tests/browser-plugin.spec.ts
index 4fbeca5600..422ada56b3 100644
--- a/packages/client/ui-model/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-model/tests/browser-plugin.spec.ts
@@ -13,7 +13,7 @@ import { describe, expect, it } from 'vitest'
 import { createScope } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandContribution, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
 import type { ModelSelectInjected } from '../src/client/slots.ts'
 import { apply, inject } from '../src/client/index.ts'
@@ -55,7 +55,7 @@ const GROUPS = [{
 /** Boot the plugin over fake faces + a stateful fake host (current moves on selectModel). */
 async function bench() {
   const ctx = new Context()
-  let current: ModelTarget = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
+  let current: ModelSelection = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
   const calls = { models: 0, select: 0 }
   ctx.provide('connection', { api: { sessions: {
     models: () => {
@@ -125,7 +125,7 @@ async function bench() {
     contribution: () => contribution!,
     seat: () => seats.get('conversation.input.model')!,
     hostCurrent: () => current,
-    setHostCurrent: (target: ModelTarget) => { current = target },
+    setHostCurrent: (selection: ModelSelection) => { current = selection },
     address: (id: SessionId) => { addressed.add(id) },
     setRoutable: (next: boolean) => { routable = next },
     blockOf: (key: string) => blocks.get(sid(key)),
diff --git a/packages/client/ui-model/tests/model-select.spec.tsx b/packages/client/ui-model/tests/model-select.spec.tsx
index 75a0622ed6..1b1e1ef17c 100644
--- a/packages/client/ui-model/tests/model-select.spec.tsx
+++ b/packages/client/ui-model/tests/model-select.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ComponentProps } from 'react'
 import type { ModelDirectoryState } from '../src/client/directory.ts'
@@ -48,10 +48,10 @@ function state(overrides: Partial<ModelDirectoryState> = {}): ModelDirectoryStat
 afterEach(cleanup)
 
 describe('ModelSelect reasoning effort', () => {
-  it('renders adapter metadata and submits the effort as part of the session target', async () => {
+  it('renders adapter metadata and submits the effort as part of the session selection', async () => {
     const directory = createSnapshotStore<ModelDirectoryState>(state())
-    const select = vi.fn(async (target: ModelTarget) => {
-      directory.set(state({ current: target }))
+    const select = vi.fn(async (selection: ModelSelection) => {
+      directory.set(state({ current: selection }))
       return true
     })
     render(<ModelSelect
@@ -112,7 +112,7 @@ describe('ModelSelect reasoning effort', () => {
       .toEqual(['Default', 'Standard'])
   })
 
-  it('prompts for a new selection when the current target is no longer advertised', () => {
+  it('prompts for a selection when the current model is no longer advertised', () => {
     const directory = createSnapshotStore(state({
       current: { provider: 'deepseek-official', model: 'removed-model' },
     }))
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index ff41da1511..f3ab9dcc56 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
-README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
-README.zh.md: c0a24d78cb8ff2a2b2ccc2d2a2f4294424be55b0
+README.md: 19aed9abafa8e4531d2ee31ff0442003328a9ef6
+README.zh.md: 73ed1f500799cb235a8835ffb0317370f9a0a7e6
diff --git a/packages/core/README.md b/packages/core/README.md
index 40a888183a..19aed9abaf 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The session log, system-prompt assembly, tool registry, agent vocabulary, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against.
+The session log, system-prompt assembly, tool registry, agent vocabulary, deployment-default model selection, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -11,9 +11,10 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 | [`system-prompt/`](system-prompt/README.md) | Prompt and tool-schema assembly registry | `ctx.systemPrompt` |
 | [`tools/`](tools/README.md) | Scoped tool registry and execution pipeline | `ctx.tools` |
 | [`agent/`](agent/README.md) | Agent interface, registry, and event vocabulary | `ctx.agents` |
+| [`agent-default-model/`](agent-default-model/README.md) | Default model selection shared by Agent front doors | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | Default concrete agent driver | `ctx.agentLoop` |
 
-`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable.
+`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable. `agent-default-model` owns the deployment selection an Agent front door uses only when a session has no selection of its own.
 
 Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
 
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index c0a24d78cb..73ed1f5007 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-构成 harness 默认控制主干的会话日志、系统提示词组装、工具注册表、agent（智能体）词汇和具体循环。这些是**产品**包，即插件和消费方构建所依赖的稳定 surface。
+构成 harness 默认控制主干的会话日志、系统提示词组装、工具注册表、agent（智能体）词汇、部署默认模型选择和具体循环。这些是**产品**包，即插件和消费方构建所依赖的稳定 surface。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -11,9 +11,10 @@
 | [`system-prompt/`](system-prompt/README.md) | 提示词和工具 schema 组装注册表 | `ctx.systemPrompt` |
 | [`tools/`](tools/README.md) | 作用域工具注册表和执行流水线 | `ctx.tools` |
 | [`agent/`](agent/README.md) | Agent 接口、注册表和事件词汇 | `ctx.agents` |
+| [`agent-default-model/`](agent-default-model/README.md) | 各 Agent 入口共享的默认模型选择 | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | 默认具体 agent 驱动器 | `ctx.agentLoop` |
 
-`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。
+`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。`agent-default-model` 负责部署选择，Agent 入口仅在会话自身没有选择时使用它。
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
 
diff --git a/packages/core/agent-default-model/README.i18n.yaml b/packages/core/agent-default-model/README.i18n.yaml
new file mode 100644
index 0000000000..92c6095788
--- /dev/null
+++ b/packages/core/agent-default-model/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/core/agent-default-model/README.md
+README.md: 02bcc9be3adee2293a20b3ae87ddaf4d52e70deb
+README.zh.md: 807b612bd25e49aa318c13c8c8dc7595a6459080
diff --git a/packages/core/agent-default-model/README.md b/packages/core/agent-default-model/README.md
new file mode 100644
index 0000000000..02bcc9be3a
--- /dev/null
+++ b/packages/core/agent-default-model/README.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-agent-default-model
+
+English | [中文](README.zh.md)
+
+The deployment default used when a front door creates an Agent that has no session-local model selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel`; direct front doors such as `dsh run` and Host-backed front doors such as ApiProxy read the same service instead of owning parallel provider/model defaults.
+
+The plugin config requires `{ provider, model }`. That composition entry is the base of the `agent-default-model` Settings section; a mounted settings provider layers the user's choice over it and changes are visible on the next `currentSelection()` read. `reasoningEffort` belongs to the Settings section but deliberately not to plugin config: a complete saved selection can clear an effort when the next selected model has none, while a composition value would be inherited again.
+
+- `ctx.agentDefaultModel.currentSelection()` returns a detached `{ provider, model, reasoningEffort? }` selection for a newly created Agent.
+- `ctx.agentDefaultModel.saveSelection(selection)` saves the complete user selection. Without a settings provider it is a no-op and the composition entry remains current.
+
+The service does not validate catalog membership. A provider route may serve an unadvertised model, and the consumer that actually opens a model request owns availability diagnostics.
+
+## Model Experience
+
+Indirectly, through the provider/model selection supplied to a front door; request assembly and adapters own the model-visible request.
+
+#### KV Cache effect
+
+Changing the default affects only Agents that subsequently resolve from it. An existing session whose request log already names a selection keeps that selection, so this service does not invalidate its established prefix.
+
+## Known Limitations and Deferred Work
+
+- The service owns one process-wide default; per-session selection remains the front door's responsibility.
+- Without a settings provider, `saveSelection()` cannot retain a selection for a later Agent.
diff --git a/packages/core/agent-default-model/README.zh.md b/packages/core/agent-default-model/README.zh.md
new file mode 100644
index 0000000000..807b612bd2
--- /dev/null
+++ b/packages/core/agent-default-model/README.zh.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-agent-default-model
+
+[English](README.md) | 中文
+
+该部署默认值供入口在创建尚无会话级模型选择的 Agent 时使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel`；`dsh run` 这类直接入口与 ApiProxy 这类由 Host 支撑的入口读取同一服务，而不是分别持有平行的提供方／模型默认值。
+
+插件配置必须提供 `{ provider, model }`。该组合配置项构成 Settings 中 `agent-default-model` 分节的基础层；挂载的设置提供方在其上叠加用户选择，更改会在下一次调用 `currentSelection()` 时可见。`reasoningEffort` 属于该 Settings 分节，但特意不属于插件配置：完整保存的选择必须能在下一个选定模型没有推理（reasoning）强度时清除旧值，而组合配置值会再次被继承。
+
+- `ctx.agentDefaultModel.currentSelection()` 返回一份独立的 `{ provider, model, reasoningEffort? }` 选择，供新创建的 Agent 使用。
+- `ctx.agentDefaultModel.saveSelection(selection)` 保存完整的用户选择。未挂载设置提供方时，此调用不执行任何操作，组合配置项仍为当前值。
+
+该服务不校验目录成员关系。提供方路由可以服务未在目录中公布的模型；实际发起模型请求的消费方负责可用性诊断。
+
+## 模型体验
+
+通过提供给入口的提供方／模型选择间接影响；模型可见请求由请求组装与适配器负责。
+
+#### KV Cache 影响
+
+更改默认值只影响之后从该默认值解析选择的 Agent。请求日志已经指明选择的现有会话仍沿用该选择，因此本服务不会使其已建立的前缀失效。
+
+## 已知限制与暂缓事项
+
+- 该服务只拥有一项进程级默认值；每个会话的选择仍由入口负责。
+- 未挂载设置提供方时，`saveSelection()` 无法保留选择供后续 Agent 使用。
diff --git a/packages/core/agent-default-model/package.json b/packages/core/agent-default-model/package.json
new file mode 100644
index 0000000000..d012fbea93
--- /dev/null
+++ b/packages/core/agent-default-model/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-agent-default-model",
+  "description": "Default model selection shared by Agent front doors",
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-settings": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/core/agent-default-model/src/index.ts b/packages/core/agent-default-model/src/index.ts
new file mode 100644
index 0000000000..36b3b9ba44
--- /dev/null
+++ b/packages/core/agent-default-model/src/index.ts
@@ -0,0 +1,107 @@
+/**
+ * Default model selection for an Agent without a session-specific selection.
+ *
+ * @module @deepseek-ai/dsh-agent-default-model
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { ModelSelection } from '@deepseek-ai/dsh-agent'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+declare module 'cordis' {
+  interface Context {
+    /** Default model selection for Agents created without an explicit model. */
+    agentDefaultModel: AgentDefaultModelService
+  }
+}
+
+/** Settings namespace carrying the default model selection for future Agents. */
+export const AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE = settingsNamespace('agent-default-model')
+
+/** Stored and composed default model selection. */
+export interface AgentDefaultModelSettings {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+  /** Adapter-owned reasoning effort, or provider/default behavior when absent. */
+  reasoningEffort?: string
+}
+
+/** Schema of the default Agent model settings section. */
+export const AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA: z<AgentDefaultModelSettings> = z.object({
+  provider: z.string().required(),
+  model: z.string().required(),
+  reasoningEffort: z.string(),
+})
+
+/** Composition entry for the default model selection. */
+export interface Config {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+
+/** Project stored settings onto the Agent-facing selection type. */
+function selection(settings: AgentDefaultModelSettings): ModelSelection {
+  return {
+    provider: settings.provider,
+    model: settings.model,
+    ...settings.reasoningEffort === undefined
+      ? {}
+      : { reasoningEffort: ReasoningEffortId(settings.reasoningEffort) },
+  }
+}
+
+/**
+ * Owns the default model selection independently of any Host or transport.
+ * The composition entry remains usable without a settings provider; when one
+ * is mounted, its user layer is read live.
+ */
+export class AgentDefaultModelService extends Service {
+  static Config: z<Config> = z.object({
+    provider: z.string().required(),
+    model: z.string().required(),
+  })
+
+  private source: () => AgentDefaultModelSettings
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'agentDefaultModel')
+    const entry: AgentDefaultModelSettings = { provider: config.provider, model: config.model }
+    this.source = () => entry
+    installSettingsSection(ctx, AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA, entry, {
+      setSource: (current) => { this.source = current },
+      // Every consumer reads through currentSelection(), so no registration-level fact
+      // needs rebuilding when the settings document changes.
+      onChange: () => {},
+    })
+  }
+
+  /**
+   * Read the current default model selection.
+   * @returns a detached provider, model, and optional reasoning selection.
+   */
+  currentSelection(): ModelSelection {
+    return selection(this.source())
+  }
+
+  /**
+   * Save the complete default model selection. A deployment without a settings
+   * provider keeps its composition entry.
+   * @param next - resolved selection accepted by a front door.
+   * @returns fulfillment after the optional settings write settles.
+   */
+  async saveSelection(next: ModelSelection): Promise<void> {
+    await this.ctx.get('settings')?.replace(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, {
+      provider: next.provider,
+      model: next.model,
+      ...next.reasoningEffort === undefined ? {} : { reasoningEffort: String(next.reasoningEffort) },
+    })
+  }
+}
+
+export default AgentDefaultModelService
diff --git a/packages/core/agent-default-model/src/invariant.ts b/packages/core/agent-default-model/src/invariant.ts
new file mode 100644
index 0000000000..8366018661
--- /dev/null
+++ b/packages/core/agent-default-model/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for the default Agent model selection.
+ *
+ * The service owns no independent event relationship: settings registration
+ * already validates every mutable value before `currentSelection()` can observe it.
+ * The empty installer keeps that absence explicit in composed invariant sets.
+ *
+ * @module @deepseek-ai/dsh-agent-default-model/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-default-model'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-default-model-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** No runtime invariant: settings validation owns the only mutable-value relationship. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the intentionally empty invariant contribution.
+ * @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))
diff --git a/packages/core/agent-default-model/tests/agent-default-model.spec.ts b/packages/core/agent-default-model/tests/agent-default-model.spec.ts
new file mode 100644
index 0000000000..ef479b4a96
--- /dev/null
+++ b/packages/core/agent-default-model/tests/agent-default-model.spec.ts
@@ -0,0 +1,98 @@
+/** Default Agent model settings layered over a real settings provider. */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentDefaultModelService, { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '../src/index.ts'
+import { Settings } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+
+/** The smallest real provider: one in-memory document, always writable. */
+class MemorySettings extends Settings {
+  doc: Record<string, unknown> = {}
+
+  get writable(): boolean {
+    return true
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc = { ...this.doc, [ns]: structuredClone(section) }
+    return Promise.resolve()
+  }
+}
+
+async function boot(): Promise<{
+  ctx: Context
+  settingsFiber: Context['fiber']
+  defaultModel: AgentDefaultModelService
+}> {
+  const ctx = new Context()
+  const settingsFiber = ctx.plugin(MemorySettings)
+  await settingsFiber.await()
+  await ctx.plugin(AgentDefaultModelService, {
+    provider: 'deepseek-official',
+    model: 'deepseek-v4-flash',
+  })
+  return { ctx, settingsFiber, defaultModel: ctx.agentDefaultModel }
+}
+
+describe('AgentDefaultModelService', () => {
+  it('resolves the user layer over the composition entry', async () => {
+    const bench = await boot()
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'deepseek-official', model: 'deepseek-v4-flash',
+    })
+
+    await bench.defaultModel.saveSelection({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: ReasoningEffortId('high'),
+    })
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('clears a stored effort when the saved selection has none', async () => {
+    const bench = await boot()
+    await bench.defaultModel.saveSelection({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: ReasoningEffortId('high'),
+    })
+    await bench.defaultModel.saveSelection({ provider: 'acme-gateway', model: 'acme-plain' })
+    expect(bench.defaultModel.currentSelection()).toEqual({ provider: 'acme-gateway', model: 'acme-plain' })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('layers a hand-written partial section over the entry', async () => {
+    const bench = await boot()
+    await bench.settingsFiber.ctx.settings.replace(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, {
+      model: 'deepseek-reasoner',
+    })
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'deepseek-official', model: 'deepseek-reasoner',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('falls back to the composition entry when the settings provider detaches', async () => {
+    const bench = await boot()
+    await bench.defaultModel.saveSelection({ provider: 'acme-gateway', model: 'acme-large' })
+    expect(bench.defaultModel.currentSelection().provider).toBe('acme-gateway')
+    await bench.settingsFiber.dispose()
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'deepseek-official', model: 'deepseek-v4-flash',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('keeps the composition entry when no settings provider is mounted', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentDefaultModelService, { provider: 'p', model: 'm' })
+    await ctx.agentDefaultModel.saveSelection({ provider: 'other', model: 'other' })
+    expect(ctx.agentDefaultModel.currentSelection()).toEqual({ provider: 'p', model: 'm' })
+    await ctx.fiber.dispose()
+  })
+})
diff --git a/packages/core/agent-default-model/tsconfig.json b/packages/core/agent-default-model/tsconfig.json
new file mode 100644
index 0000000000..95b89f17b5
--- /dev/null
+++ b/packages/core/agent-default-model/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../settings/settings"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/core/agent-default-model/tsdown.config.ts b/packages/core/agent-default-model/tsdown.config.ts
new file mode 100644
index 0000000000..ab8dc26ee8
--- /dev/null
+++ b/packages/core/agent-default-model/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 53a1a1f650..825c1714a2 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
-README.zh.md: e421070a6eec2e6e7e1fc7b45f0a5e29040bf712
+README.md: ba0fa456593e598b6532c10ef2390bbd55f3a486
+README.zh.md: 581da5c8621e5653f57edce38ac9816da7a40d40
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 3a3bdf6a4b..ba0fa45659 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -12,7 +12,7 @@ Tracks live agents and carries the initiating Agent through asynchronous driver
 
 ### Public API
 
-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installAgentLlmTarget(agentCtx, target)` snapshots a mutable provider/model/reasoning-effort selection during prompt assembly, applies the route to prompt variables, and applies the complete target to request routing for one step; an absent selected effort clears an inherited effort so the target uses adapter/provider defaults. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installModelSelection(agentCtx, selection)` snapshots a mutable provider/model/reasoning-effort selection during prompt assembly, applies its provider and model to prompt variables, and applies the complete selection to request routing for one step; an absent selected effort clears an inherited effort so adapter/provider defaults apply. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 `AgentOptions` supplies the initial provider/model route and an optional positive `maxTokens` output cap. The concrete loop resolves any exact-model adapter default, records the effective cap in the request header, and applies it to each conversation-model request; an explicit Agent option wins, while omission leaves the adapter or provider route default in control.
 
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index e421070a6e..581da5c862 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -12,7 +12,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 
 ### 公开 API
 
-带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installAgentLlmTarget(agentCtx, target)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将路由应用到提示词变量，并将完整目标应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使该目标使用适配器／提供方默认值。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
+带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installModelSelection(agentCtx, selection)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将其中的提供方和模型应用到提示词变量，并将完整选择应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使适配器／提供方默认值生效。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
 
 `AgentOptions` 提供初始的提供方／模型路由，以及可选的正数 `maxTokens` 输出上限。具体循环会解析确切模型的适配器默认值，把生效上限记录到请求 header，并应用到每次对话模型请求；显式 Agent 选项优先，省略时由适配器或提供方路由默认值控制。
 
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 8f316f75dc..44c55d80a2 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -17,7 +17,7 @@ import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
 export * from './inbox.ts'
-export * from './llm-target.ts'
+export * from './model-selection.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'
 
diff --git a/packages/core/agent/src/llm-target.ts b/packages/core/agent/src/model-selection.ts
similarity index 55%
rename from packages/core/agent/src/llm-target.ts
rename to packages/core/agent/src/model-selection.ts
index e23ea9d750..4d36ca34fb 100644
--- a/packages/core/agent/src/llm-target.ts
+++ b/packages/core/agent/src/model-selection.ts
@@ -1,13 +1,13 @@
 /**
- * Agent-scoped LLM target snapshot shared by interactive front doors.
- * @module @deepseek-ai/dsh-agent/llm-target
+ * Agent-scoped model selection shared by interactive front doors.
+ * @module @deepseek-ai/dsh-agent/model-selection
  */
 
 import type { Context } from 'cordis'
 import type { LlmCallConfig, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 
-/** Complete provider/model route and optional reasoning effort selected for one live agent. */
-export interface AgentLlmTarget {
+/** Complete provider, model, and optional reasoning effort selected for one live Agent. */
+export interface ModelSelection {
   /** Registered provider route. */
   provider: string
   /** Provider-owned model id. */
@@ -16,31 +16,31 @@ export interface AgentLlmTarget {
   reasoningEffort?: ReasoningEffortId
 }
 
-/** Mutable selection plus the target captured for the current step. */
-export interface AgentLlmTargetRef {
-  /** Target selected for the next step that enters prompt assembly. */
-  current: AgentLlmTarget | undefined
-  /** Target captured when the current step entered prompt assembly. */
-  assembled: AgentLlmTarget | undefined
+/** Mutable model selection plus the value captured for the current step. */
+export interface ModelSelectionRef {
+  /** Model selected for the next step that enters prompt assembly. */
+  current: ModelSelection | undefined
+  /** Selection captured when the current step entered prompt assembly. */
+  assembled: ModelSelection | undefined
 }
 
 /**
- * Couple one mutable target to agent-scoped prompt assembly and request routing.
- * Prompt assembly snapshots the selected target before delegating, then applies
- * its route to prompt variables and its route/effort to request config so a
+ * Couple one mutable selection to Agent-scoped prompt assembly and request routing.
+ * Prompt assembly snapshots the selected model before delegating, then applies
+ * its provider/model pair and effort to request config so a
  * concurrent switch takes effect on a later step instead of splitting the two
- * surfaces. An absent selected effort clears any inherited effort so a model
- * switch can restore that target's provider/default behavior.
+ * surfaces. An absent selected effort clears any inherited effort, restoring
+ * the selected model's provider/default behavior.
  *
- * @param agentCtx - The target agent's scoped context.
- * @param target - Mutable selection owned by the calling front door.
+ * @param agentCtx - The selected Agent's scoped context.
+ * @param selection - Mutable selection owned by the calling front door.
  * @returns Disposer for both scoped waterfall listeners.
  */
-export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetRef): () => void {
+export function installModelSelection(agentCtx: Context, selection: ModelSelectionRef): () => void {
   const disposeAssembly = agentCtx.on('system-prompt/assemble', async (_assembly, _context, next) => {
-    const selected = target.current
+    const selected = selection.current
     const assembled = await next()
-    target.assembled = selected
+    selection.assembled = selected
     if (selected === undefined) return assembled
     return {
       ...assembled,
@@ -55,7 +55,7 @@ export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetR
     'agent/request',
     async (_payload, next): Promise<LlmCallConfig> => {
       const resolved = await next()
-      const selected = target.assembled
+      const selected = selection.assembled
       if (selected === undefined) return resolved
       const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = resolved
       return {
diff --git a/packages/core/agent/tests/llm-target.spec.ts b/packages/core/agent/tests/model-selection.spec.ts
similarity index 86%
rename from packages/core/agent/tests/llm-target.spec.ts
rename to packages/core/agent/tests/model-selection.spec.ts
index 991a69ea32..2d7a1a7336 100644
--- a/packages/core/agent/tests/llm-target.spec.ts
+++ b/packages/core/agent/tests/model-selection.spec.ts
@@ -3,18 +3,18 @@ import { Context } from 'cordis'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import {
   agentEvents,
-  installAgentLlmTarget,
+  installModelSelection,
   type Agent,
-  type AgentLlmTargetRef,
+  type ModelSelectionRef,
 } from '../src/index.ts'
 import { ReasoningEffortId, type LlmCallConfig } from '@deepseek-ai/dsh-llm'
 
-describe('installAgentLlmTarget()', () => {
+describe('installModelSelection()', () => {
   it('snapshots prompt variables and request routing together, then disposes both listeners', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
-    const target: AgentLlmTargetRef = { current: undefined, assembled: undefined }
-    const dispose = installAgentLlmTarget(ctx, target)
+    const selection: ModelSelectionRef = { current: undefined, assembled: undefined }
+    const dispose = installModelSelection(ctx, selection)
     const agent = {} as Agent
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
@@ -24,13 +24,13 @@ describe('installAgentLlmTarget()', () => {
       'agent/request', { turn: 1, step: 0, signal }, () => Promise.resolve(seed),
     )).resolves.toBe(seed)
 
-    target.current = {
+    selection.current = {
       provider: 'alpha',
       model: 'a1',
       reasoningEffort: ReasoningEffortId('high'),
     }
     expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'alpha', model: 'a1' })
-    target.current = { provider: 'beta', model: 'b1' }
+    selection.current = { provider: 'beta', model: 'b1' }
     await expect(agentEvents(ctx, agent).waterfall(
       'agent/request', { turn: 1, step: 0, signal }, () => Promise.resolve(seed),
     )).resolves.toEqual({
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index bc7869b361..b994e46b03 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
-README.zh.md: 65475351e279f258f4417f2082673382e76a5be3
+README.md: 5e3a6cf57ce3fe11b3f31d7f68055f34708d74eb
+README.zh.md: b96487d6d67deb8a0a6ddf4a92784f31dafb3e89
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index a3c9f21469..5e3a6cf57c 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -2,19 +2,19 @@
 
 English | [中文](README.zh.md)
 
-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, reasoningEffort?, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped Web composition lives in [`packages/bundle/web-app/cordis.patch.yml`](../../bundle/web-app/cordis.patch.yml), while its default Agent model selection belongs to [`@deepseek-ai/dsh-agent-default-model`](../../core/agent-default-model/README.md) in the base bundle.
 
-## The default route (`api-gateway` settings section)
+## The shared Agent default (`agent-default-model` Settings section)
 
-`{provider, model, reasoningEffort?}` is also the gateway's user-settings section, registered under `api-gateway`: the composition entry is the `base` layer and `settings.yaml` layers the user's own choice over it. `workspaceRoot` is deliberately outside the section — a launcher fact, not a preference.
+`ApiProxyService` consumes `ctx.agentDefaultModel`; it does not own a provider/model config or settings section. The shared service registers `{provider, model, reasoningEffort?}` under `agent-default-model`: the base bundle's composition entry is the lower layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` remains ApiProxy config because it is a Host launcher fact, not a model preference.
 
-A session resolves its route from three tiers, re-read on every access rather than seeded once: a selection made in this process, else the session's own latest logged `request/header`, else this default. Re-reading is what makes both directions hold — a session that has run a turn derives its route from its log forever after, so changing the default never retargets it, while a session still blank (New Session reuses one rather than minting another) starts from a default saved after it was created.
+A session resolves its model selection from three tiers on every access: a selection made in this process, otherwise the session's latest logged `request/header`, otherwise this default. A session that has run a turn derives its selection from its log, while a blank session observes a default saved after it was created.
 
-`session.selectModel` records an accepted switch as the new default, which is how the default is chosen in practice: there is no separate gesture. What it stores is the RESOLVED target, so an adapter-materialized default effort is pinned as the user saw it and a later adapter-default change does not silently move stored defaults. The write replaces the section wholesale rather than merging, because switching to a model with no reasoning effort has to clear a stored one; a storage failure is logged without undoing the switch, which already applies to its own session. A deployment with no settings provider keeps the composition entry and a switch stays process-local.
+`session.selectModel` saves an accepted switch as the deployment default; there is no separate gesture. It stores the resolved `ModelSelection`, including an adapter-materialized default effort. The complete-section write clears a stored effort when the selected model has none. A storage failure is logged without undoing the session selection. A deployment with no settings provider keeps the composition entry and the switch remains session-local.
 
-The section's `reasoningEffort` has no counterpart in the plugin config, deliberately: the seam merges the user layer over the composition entry per field, so an absent key cannot override a present one and a composition-set effort would survive every later switch to a model without one. A deployment default for effort belongs on the adapter profile, which resolves per model.
+The section's `reasoningEffort` has no counterpart in the agent-default-model plugin config, deliberately: the seam merges the user layer over the composition entry per field, so an absent key cannot override a present one and a composition-set effort would survive every later switch to a model without one. A deployment default for effort belongs on the adapter profile, which resolves per model.
 
-The stored route is not validated against the registry, in either direction. A default naming a route the Models page has since removed still reaches `session.models` as the session's `current` — matching no advertised group, which is precisely what makes a selector prompt for a replacement instead of naming a model the deployment cannot reach. Repairing it silently would also break the deliberate converse: an adapter may serve a model its catalog does not advertise.
+The stored selection is independent of catalog membership. A default naming an unavailable provider still reaches `session.models` as the session's `current`, allowing the selector to request a replacement instead of silently choosing another model. Conversely, an adapter may serve a model that its catalog does not advertise.
 
 ## Contract layer (`/api`)
 
@@ -30,9 +30,9 @@ Question responses are validated against their pending request before the first
 
 Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
 
-`session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
+`session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged `ModelSelection`, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
 
-Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. `session.models` additionally reports `routable`: whether an adapter currently serves the current target's route, which is deliberately NOT derivable from the groups — a route serving a model it stopped advertising is absent from them yet perfectly usable, while a route whose adapter is gone can serve nothing. `session.prompt` refuses on that same fact with `model-unavailable` rather than spending the pre-step path to fail inside an adapter; a client that disables its composer is an affordance, and this method stays callable regardless.
+Session model selection is a session-domain contract. `session.models` returns the current `ModelSelection` separately from provider-grouped advisory models, exact-model reasoning metadata, and provider-local lookup failures. The selection may be absent from the groups and is never injected as a synthetic row; clients can prompt for another selection without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and assigns the complete selection for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable provider or unsupported effort returns `model-unavailable`. `session.models` additionally reports `routable`: whether an adapter currently serves the selected provider. This is deliberately not derivable from the groups because an adapter may serve an unadvertised model. `session.prompt` refuses on the same fact with `model-unavailable` before opening a turn; a disabled composer is a client affordance, and the method remains callable.
 
 Pending queued input is a live control-plane contract, not conversation history. The gateway derives the complete `next-turn` queue from durable `agent/inbox/spliced` mutations and broadcasts authoritative `session/queue` snapshots after each change and on reconnect; pending `next-step` steering stays outside this Web projection. Within `next-step`, user-origin messages carry the `steering` placement while injected context (approval notices, task completion, attached snapshots) carries `context` and is not surfaced until claimed. The message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications remain available to lifecycle observers but do not build the queue view. `session.updateQueue` addresses one `MessageId`; edit and remove mutate the attached Agent through `Inbox.splice()`. A claim's pure deletion splice wins races before pre-step admission, so a later operation returns `queue-item-not-found`. `session.cancel` aborts only the active turn and preserves pending inbox work; after cancellation reaches quiescence and the closing turn flushes, AgentLoop claims the next waking message in FIFO order, and the browser never resends or promotes it. Queue operations never resume a cold session, and the client never infers retirement from turn or status events.
 
@@ -52,7 +52,7 @@ The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-pag
 
 ## Carrier layer (`/client` + root)
 
-`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh run` headless.
+`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` remains the isomorphic point for callers and carrier tests that need the full wire serialization/validation path without a network. Product `dsh run` is a direct core front door and does not mount this package.
 
 ## Model Experience
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 65475351e2..b96487d6d6 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -2,19 +2,19 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 约定（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+所有客户端形态共用的 API 网关：TS 约定（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。随发行版交付的 Web 组合位于 [`packages/bundle/web-app/cordis.patch.yml`](../../bundle/web-app/cordis.patch.yml)，其默认 Agent（智能体）模型选择属于 base 组合包中的 [`@deepseek-ai/dsh-agent-default-model`](../../core/agent-default-model/README.md)。
 
-## 默认路由（`api-gateway` 设置段）
+## 共享 Agent 默认值（`agent-default-model` Settings 分节）
 
-`{provider, model, reasoningEffort?}` 同时是网关的用户设置段，注册在 `api-gateway` 之下：组合条目是 `base` 层，`settings.yaml` 把用户自己的选择叠加其上。`workspaceRoot` 刻意不在段内——它是启动器事实，不是偏好。
+`ApiProxyService` 消费 `ctx.agentDefaultModel`；它不持有提供方／模型配置或 Settings 分节。共享服务在 `agent-default-model` 下注册 `{provider, model, reasoningEffort?}`：base 组合包的组合条目是底层，`settings.yaml` 把用户选择叠加其上。`workspaceRoot` 仍属于 ApiProxy 配置，因为它是 Host 启动器事实，而不是模型偏好。
 
-会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
+会话每次访问时都按三级解析模型选择：本进程内作出的选择，其次是该会话日志中最新的 `request/header`，最后是这个默认值。已经跑过一轮的会话从自己的日志推导选择，空白会话则能观察到创建之后保存的默认值。
 
-`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不带推理等级的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`session.selectModel` 会把接受的切换保存为部署默认值；没有单独的选择动作。它存储已解析的 `ModelSelection`，包括适配器实体化的默认推理强度。完整分节写入会在所选模型没有推理强度时清除已存值。存储失败只记日志，不会撤销会话选择。没有设置提供方的部署保留组合条目，切换只对当前会话生效。
 
-设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不带推理等级的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
+Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中刻意没有对应字段：seam 按字段把用户层合并到组合条目之上，因此缺席的键无法覆盖已有键，组合层中的推理强度会在以后选择没有推理强度的模型时继续存在。推理强度的部署默认值属于按模型解析的适配器 profile。
 
-存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
+存储的选择独立于目录成员关系。默认值指向不可用的提供方时，它仍会作为会话的 `current` 送到 `session.models`，让选择器请求用户重新选择，而不是静默选用其他模型。反过来，适配器也可以服务其目录中未公布的模型。
 
 ## 约定层（`/api`）
 
@@ -24,15 +24,15 @@
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent（智能体），然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
 
-`session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
+`session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的 `ModelSelection` 及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
-会话模型路由属于会话领域约定。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
+会话模型选择属于会话领域约定。`session.models` 将当前 `ModelSelection` 与按提供方分组的建议性模型、精确模型的推理（reasoning）元数据和逐提供方查询失败记录分开返回。该选择可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户作出另一项选择，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并指定将在下一提示词组装边界使用的完整选择。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用的提供方或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`，即当前是否有适配器为所选提供方提供服务。该值刻意不从分组推导，因为适配器可以服务未公布的模型。`session.prompt` 会依据同一事实，在开启轮次之前以 `model-unavailable` 拒绝；客户端禁用 composer 只是提示性设计，这个方法始终可被调用。
 
 待处理的 queued 输入属于实时控制平面约定，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
 
@@ -52,7 +52,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 ## 载体层（`/client` + 根路径）
 
-`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh run` headless 模式使用。
+`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，仍是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供需要该路径的调用方和载体测试使用。产品的 `dsh run` 是直连 core 的入口，不挂载本包。
 
 ## 模型体验
 
diff --git a/packages/host/apiproxy/package.json b/packages/host/apiproxy/package.json
index 91d03b4448..511fc25dba 100644
--- a/packages/host/apiproxy/package.json
+++ b/packages/host/apiproxy/package.json
@@ -39,6 +39,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 52236b0f29..01b792353d 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -7,8 +7,9 @@ import { randomUUID } from 'node:crypto'
 import { mkdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Context } from 'cordis'
-import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { Agent, ModelSelection, ModelSelectionRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-default-model'
 import { createUserMessage, freezeMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
@@ -83,14 +84,6 @@ import { openNativePath, openNativeTextFile } from './native-path-opener.ts'
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
 
-/**
- * The settings namespace carrying the user's default route. Named for the
- * gateway rather than for the package, because this key is what a person reads
- * and writes in `settings.yaml`; the row id in a composition happens to match
- * but does not determine it.
- */
-export const API_GATEWAY_SETTINGS_NAMESPACE = settingsNamespace('api-gateway')
-
 /** Non-model settings namespaces intentionally served to the Web client. */
 const WEB_SETTINGS_NAMESPACES = ['permission'] as const
 
@@ -152,7 +145,7 @@ function ok<T>(request: RpcRequest<unknown>, value: T): RpcResponse<T> {
 /**
  * Build the provider/model catalog over every registered route. Shared by the
  * session-scoped `session.models` and host-scoped `llm.models`. Catalog
- * membership stays advisory: an unlisted session target remains valid for
+ * membership stays advisory: an unlisted session selection remains valid for
  * provider dispatch, but is not injected back into the selector after its
  * owning catalog stops advertising it. Per-provider failures ride `failures`
  * without failing the sound groups; groups that advertise nothing are dropped.
@@ -345,14 +338,14 @@ function directoryError(error: unknown): RpcError {
   return { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} }
 }
 
-/** Resolved Host routing and project-directory defaults consumed by the API implementation. */
+/** Resolved Agent model and project-directory defaults consumed by the API implementation. */
 export interface ApiProxyDefaults {
   /**
-   * The route a session starts from when its own log names none. Read on
+   * The model selection a session starts from when its own log names none. Read on
    * every access rather than captured, so a default saved during this process
    * reaches the sessions that have not run a turn yet.
    */
-  defaultTarget: () => AgentLlmTarget
+  defaultModelSelection: () => ModelSelection
   /**
    * Record a selection as the new default. Either absent, or a closure that
    * may itself decline — the gateway plugin always passes one, and it no-ops
@@ -361,7 +354,7 @@ export interface ApiProxyDefaults {
    * reported and swallowed: the switch already applies to its own session,
    * and undoing it because storage failed would be the worse outcome.
    */
-  persistDefaultTarget?: (target: AgentLlmTarget) => Promise<void>
+  saveDefaultModelSelection?: (selection: ModelSelection) => Promise<void>
   /** Default project directory for new sessions whose create request carries no cwd. */
   cwd: string
   /** Parent directory for name-created workspaces. */
@@ -734,17 +727,17 @@ function changedWorkspaceView(workspaceId: string, value: unknown): WorkspaceVie
 /**
  * Implement ApiProxy over a composed host context.
  * @param ctx - a context with the Host spine and Workspace registry mounted.
- * @param defaults - host routing and project-directory defaults.
+ * @param defaults - Agent model and project-directory defaults.
  * @returns the ApiProxy implementation.
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
-  /** The seed route each create/resume declares; re-read so it never goes stale. */
+  /** The seed model each create/resume declares; re-read so it never goes stale. */
   const agentOptions = (): AgentOptions => {
-    const { provider, model } = defaults.defaultTarget()
+    const { provider, model } = defaults.defaultModelSelection()
     return { provider, model }
   }
-  type WebLlmTargetRef = AgentLlmTargetRef & { current: AgentLlmTarget }
-  const targets = new WeakMap<Agent, WebLlmTargetRef>()
+  type WebModelSelectionRef = ModelSelectionRef & { current: ModelSelection }
+  const selections = new WeakMap<Agent, WebModelSelectionRef>()
   /** Client-chosen identity creation/resume, deduplicated across concurrent retries. */
   const sessionCreations = new Map<SessionId, Promise<Agent>>()
   /** Serializes path ownership and explicit title checks with Workspace mutations. */
@@ -754,29 +747,28 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
 
   /**
-   * Install or return the session-local target that prompt assembly snapshots.
+   * Install or return the session-local model selection that prompt assembly snapshots.
    *
    * Precedence, resolved on EVERY read rather than seeded once: a selection
    * made in this process, else the session's own latest logged request/header,
-   * else the live host default. Re-reading is what keeps the two tiers honest
-   * in both directions — a session that has run a turn derives its route from
-   * its log forever after, so changing the default never retargets it; and a
-   * session still blank (New Session reuses one rather than minting another)
-   * starts from a default saved after it was created. There is no create-time
+   * else the live Agent default. Re-reading keeps the two tiers exact in both
+   * directions: a session with a recorded request derives its selection from
+   * its log, while a blank session (New Session reuses one rather than minting
+   * another) reads any default saved after it was created. There is no create-time
    * per-session override tier on this wire — if one returns (a create-options
    * contribution), it must fold in between the selection and the log.
    */
-  function targetFor(agent: Agent): WebLlmTargetRef {
-    const installed = targets.get(agent)
+  function selectionFor(agent: Agent): WebModelSelectionRef {
+    const installed = selections.get(agent)
     if (installed !== undefined) return installed
-    let picked: AgentLlmTarget | undefined
-    const target: WebLlmTargetRef = {
-      get current(): AgentLlmTarget {
+    let picked: ModelSelection | undefined
+    const selection: WebModelSelectionRef = {
+      get current(): ModelSelection {
         if (picked !== undefined) return picked
         // Incrementally folded by the session, so a per-step read costs
         // O(new events) rather than a rescan.
         const logged = agent.session.requestHeader()?.config
-        if (logged === undefined) return defaults.defaultTarget()
+        if (logged === undefined) return defaults.defaultModelSelection()
         return {
           provider: logged.provider,
           model: logged.model,
@@ -785,21 +777,21 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             : { reasoningEffort: logged.reasoningEffort },
         }
       },
-      set current(next: AgentLlmTarget) {
+      set current(next: ModelSelection) {
         picked = next
       },
       assembled: undefined,
     }
-    installAgentLlmTarget(agent.ctx, target)
-    targets.set(agent, target)
-    return target
+    installModelSelection(agent.ctx, selection)
+    selections.set(agent, selection)
+    return selection
   }
 
   /** Pre-publication setup used by both fresh and resumed Web agents. */
-  function installTarget(agentCtx: Context): void {
+  function installSelection(agentCtx: Context): void {
     const agent = agentCtx.agent
     if (agent === undefined) throw new Error('api-proxy: agent setup has no scoped agent')
-    targetFor(agent)
+    selectionFor(agent)
   }
 
   const hasSubagentOwner = (
@@ -810,7 +802,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     apiRemoteSubagentOwnershipError(sessionId)
   const inspectServable = (sessionId: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> =>
     inspectApiRemoteSession(ctx, sessionId)
-  const agentFor = createApiRemoteAgentResolver(ctx, { agentOptions, setup: installTarget })
+  const agentFor = createApiRemoteAgentResolver(ctx, { agentOptions, setup: installSelection })
 
   /** Send one transient frame to every connected mux consumer. */
   function broadcast(payload: MuxFrame): void {
@@ -1076,7 +1068,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return (await ctx.agents.resume({
             resumeSessionId: sessionId,
             agentOptions: agentOptions(),
-            setup: installTarget,
+            setup: installSelection,
           })).agent
         }
 
@@ -1089,7 +1081,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           sessionId,
           agentOptions: agentOptions(),
           meta: { cwd },
-          setup: installTarget,
+          setup: installSelection,
         })).agent
       })().catch((error: unknown) => {
         // Another Host entry path may have published the same identity while
@@ -1235,10 +1227,10 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   }
 
   /**
-   * Whether an adapter currently serves this route, and therefore whether a
-   * session pointed at it can start a turn. Catalog membership cannot answer
+   * Whether an adapter currently serves this provider, and therefore whether
+   * a session selecting it can start a turn. Catalog membership cannot answer
    * it: an adapter may serve a model its own catalog stopped advertising, so
-   * a route missing from the groups is not the same as one nothing serves.
+   * a provider missing from the groups is not the same as one nothing serves.
    * A composition with no llm registry at all cannot judge and says yes —
    * the dispatch it would have refused fails on its own terms.
    */
@@ -1249,7 +1241,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
   /**
    * Resolve the addressed agent for a turn-starting method and refuse when no
-   * adapter serves its current route: a route nothing serves cannot start a
+   * adapter serves its current selection: a provider nothing serves cannot start a
    * turn, and letting it try spends the whole pre-step path to fail inside
    * the adapter with a message about registration. Refusing here names the
    * model the session is pointed at while the draft is still in the composer.
@@ -1262,13 +1254,13 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     const found = await agentFor(sessionId)
     if ('error' in found) return { refused: err(request, found.error) }
     const agent = found.agent
-    const target = targetFor(agent).current
-    if (!routeServed(target.provider)) {
+    const selection = selectionFor(agent).current
+    if (!routeServed(selection.provider)) {
       return {
         refused: err(request, {
           code: 'model-unavailable',
-          message: `no adapter serves provider "${target.provider}"; select a model for this session`,
-          details: { provider: target.provider, model: target.model },
+          message: `no adapter serves provider "${selection.provider}"; select a model for this session`,
+          details: { provider: selection.provider, model: selection.model },
         }),
       }
     }
@@ -1643,7 +1635,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         const { sessionId } = request.payload
         const found = await agentFor(sessionId)
         if ('error' in found) return err(request, found.error)
-        const current = targetFor(found.agent).current
+        const current = selectionFor(found.agent).current
         const { groups, failures } = await buildModelCatalog(ctx)
         const routable = routeServed(current.provider)
         return ok(request, { current: { ...current }, routable, groups, failures })
@@ -1661,20 +1653,20 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               ? {}
               : { reasoningEffort: ReasoningEffortId(reasoningEffort) },
           })
-          const selected: AgentLlmTarget = {
+          const selected: ModelSelection = {
             provider: resolved.provider,
             model: resolved.model,
             ...resolved.reasoningEffort === undefined
               ? {}
               : { reasoningEffort: resolved.reasoningEffort },
           }
-          targetFor(found.agent).current = selected
+          selectionFor(found.agent).current = selected
           // A switch is also how this deployment's default is chosen: the next
           // session created without one of its own starts here. Sessions that
-          // have already logged a route are unaffected — they derive from
-          // their own log (see targetFor).
+          // have already logged a selection are unaffected — they derive from
+          // their own log (see selectionFor).
           try {
-            await defaults.persistDefaultTarget?.(selected)
+            await defaults.saveDefaultModelSelection?.(selected)
           } catch (error: unknown) {
             ctx.logger.warn(
               `api-proxy: the model switch applies to this session but was not saved as the default: ${String(error)}`,
@@ -1783,7 +1775,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               seedLength: cut,
             },
             agentOptions: agentOptions(),
-            setup: installTarget,
+            setup: installSelection,
           })
         } catch (error: unknown) {
           return err(request, {
@@ -2192,7 +2184,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     host: {
       describe(request) {
         // TODO(step2): version should read apps/cli's package.json; placeholder for now.
-        const route = defaults.defaultTarget()
+        const selection = defaults.defaultModelSelection()
         return Promise.resolve(ok(request, {
           version: '0.0.1',
           // Same source as session.create's fallback: the UI's default project
@@ -2200,8 +2192,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           cwd: defaults.cwd,
           // Read live for the same reason: this is what the NEXT session will
           // start from, so a saved default has to be what it reports.
-          provider: route.provider,
-          model: route.model,
+          provider: selection.provider,
+          model: selection.model,
           attachedSessions: ctx.agents.list().length,
         }))
       },
@@ -2730,11 +2722,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             // A provider's own settings carry its model catalog and endpoint,
             // so a change there invalidates the model list even when the route
             // set is untouched — `llm/adapters-updated` alone misses it. The
-            // gateway's own section is the other such source: it names the
-            // route every session with no logged one resolves to, so an
+            // Agent default section is the other such source: it names the
+            // selection every session with no logged one resolves to, so an
             // externally edited default (another tab, a hand-edited
             // settings.yaml) has to reach an open selector too.
-            if (modelProviderNamespaces().has(name) || name === String(API_GATEWAY_SETTINGS_NAMESPACE)) {
+            if (modelProviderNamespaces().has(name) || name === String(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE)) {
               queue.push(frame({ type: 'host/models-changed' }))
             }
           }),
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 5537a0e382..8e35c62514 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -37,7 +37,7 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
+  ModelReasoningEffort, ModelSelection, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
   SessionsApi, SessionSummary,
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
diff --git a/packages/host/apiproxy/src/api/llm.ts b/packages/host/apiproxy/src/api/llm.ts
index 29cda6cf78..01564992d0 100644
--- a/packages/host/apiproxy/src/api/llm.ts
+++ b/packages/host/apiproxy/src/api/llm.ts
@@ -3,8 +3,8 @@
  * surfaces. `llm.providers` merges the configurable-provider directory
  * (which providers CAN be configured, and where their settings live) with the
  * live route registry; `llm.models` is the session-independent model catalog
- * (the same groups as `session.models`, without the per-session current
- * target). Both invalidate on the `host/models-changed` frame.
+ * (the same groups as `session.models`, without a per-session selection).
+ * Both invalidate on the `host/models-changed` frame.
  */
 
 import type { RpcRequest, RpcResponse } from './rpc.ts'
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
index 80e64fb12a..a1cc88dace 100644
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -12,7 +12,7 @@ import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
+  ModelReasoningEffort, ModelSelection, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
 import type { WorkspaceId } from './workspace.ts'
@@ -140,12 +140,12 @@ export const sessionHistoryRequestSchema = z.object({
   maxMessages: z.number().int().positive().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'session.history'>>>
 
-/** Complete provider/model target. */
-export const modelTargetSchema = z.object({
+/** Complete provider/model selection. */
+export const modelSelectionSchema = z.object({
   provider: z.string().min(1),
   model: z.string().min(1),
   reasoningEffort: z.string().min(1).optional(),
-}) satisfies z.ZodType<Wire<ModelTarget>>
+}) satisfies z.ZodType<Wire<ModelSelection>>
 
 /** One adapter-owned reasoning effort. */
 export const modelReasoningEffortSchema = z.object({
@@ -224,7 +224,7 @@ export const sessionModelsRequestSchema = z.object({
 
 /** session.models response value. */
 export const sessionModelsValueSchema = z.object({
-  current: modelTargetSchema,
+  current: modelSelectionSchema,
   routable: z.boolean(),
   groups: z.array(modelProviderGroupSchema),
   failures: z.array(modelCatalogFailureSchema),
@@ -240,7 +240,7 @@ export const sessionSelectModelRequestSchema = z.object({
 
 /** session.selectModel response value. */
 export const sessionSelectModelValueSchema = z.object({
-  selected: modelTargetSchema,
+  selected: modelSelectionSchema,
 }) satisfies z.ZodType<Wire<ResponseValue<'session.selectModel'>>>
 
 /** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index 2e795928ec..a5fc8fffad 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -53,8 +53,8 @@ export interface SessionProjectionsBlock {
   values: Partial<SessionProjectionMap>
 }
 
-/** Complete model target selected for one session. */
-export interface ModelTarget {
+/** Complete model selection for one session. */
+export interface ModelSelection {
   /** Registered provider route. */
   provider: string
   /** Provider-owned model id. */
@@ -115,8 +115,8 @@ export interface ModelCatalogFailure {
 
 /** Detached model-directory snapshot for one session. */
 export interface SessionModels {
-  /** Target selected for the session's next assembled step. */
-  current: ModelTarget
+  /** Model selection for the session's next assembled step. */
+  current: ModelSelection
   /**
    * Whether an adapter currently serves `current.provider`, and therefore
    * whether this session can start a turn at all. Deliberately NOT derivable
@@ -240,7 +240,7 @@ export interface SessionsApi {
   models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>
 
   /**
-   * Selects the complete target for this session. Exact model metadata
+   * Selects the complete model selection for this session. Exact model metadata
    * validates an optional reasoning effort, while catalog membership remains
    * advisory. Session-backed subagents reject with `agent-busy`.
    */
@@ -250,7 +250,7 @@ export interface SessionsApi {
     model: string
     reasoningEffort?: string
   }>):
-  Promise<RpcResponse<{ selected: ModelTarget }>>
+  Promise<RpcResponse<{ selected: ModelSelection }>>
 
   /**
    * Renames a session: appends a `session/title` event with the `user`
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index 1a6e0be281..667e85bdac 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -7,28 +7,24 @@
  * `ctx.apiProxy`). Transport-agnostic by design: this package registers no
  * routes — physical carriers wrap `ctx.apiProxy` themselves.
  *
- * The gateway also owns the `api-gateway` settings section: the route a
- * session starts from when its own log names none. The composition entry is
- * the shipped default and the section layers the user's choice over it, so
- * switching models in a conversation is what sets the default for the next
- * one. Sessions that have already logged a route are never retargeted by it.
+ * The gateway consumes `ctx.agentDefaultModel`, the transport-independent default
+ * shared with direct front doors. Switching models persists through that
+ * service; sessions that have already logged a selection remain unchanged.
  */
 
 import { resolve } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import type { AgentLlmTarget } from '@deepseek-ai/dsh-agent'
-import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import { installSettingsSection } from '@deepseek-ai/dsh-settings'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
 import type { ApiProxy } from './api/index.ts'
-import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
+import { createApiProxy } from './api-proxy.ts'
 
 export type * from './api/index.ts'
 export { RpcId } from './api/rpc.ts'
 export { toFetchHandler } from './fetch/handler.ts'
 export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
 export type { IApiClient } from './fetch/client.ts'
-export { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
+export { createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'
 
 declare module 'cordis' {
@@ -38,62 +34,12 @@ declare module 'cordis' {
   }
 }
 
-/**
- * The `api-gateway` settings section: the route a session starts from when its
- * own log names none. `workspaceRoot` is deliberately not part of it — that is
- * a launcher fact, not a preference.
- */
-export interface DefaultRouteSettings {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
-  /** Default reasoning effort; absence preserves the adapter/provider default. */
-  reasoningEffort?: string
-}
-
-/**
- * Gateway plugin config: host-level agent routing and Workspace creation root.
- *
- * `reasoningEffort` is deliberately absent, so the section carries one field
- * the composition cannot. The seam resolves a section by MERGING the user
- * layer over the composition entry per field, and an absent key cannot
- * override a present one — so a composition-set effort would survive every
- * later switch to a model that has none, and strand it for the next session
- * to fail on. Effort is a per-model fact anyway: a deployment default belongs
- * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
- * which resolves per model rather than per gateway.
- */
+/** Gateway plugin config: the Host-only Workspace creation root. */
 export interface Config {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 
-/**
- * Schema of the `api-gateway` section, exported because it IS that section's
- * contract — the shape anything reading or writing `settings.yaml` addresses.
- */
-export const DEFAULT_ROUTE_SCHEMA: z<DefaultRouteSettings> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  reasoningEffort: z.string(),
-})
-
-/** Project the stored/composed section onto the agent-facing target shape. */
-function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
-  return {
-    provider: settings.provider,
-    model: settings.model,
-    ...settings.reasoningEffort === undefined
-      ? {}
-      : { reasoningEffort: ReasoningEffortId(settings.reasoningEffort) },
-  }
-}
-
 /**
  * The API gateway service: implements the ApiProxy contract over the composed
  * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
@@ -101,13 +47,11 @@ function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
  */
 export class ApiProxyService extends Service implements ApiProxy {
   static inject = [
-    'agents', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
+    'agentDefaultModel', 'agents', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
     'tools', 'userInteraction', 'workspace',
   ]
 
   static Config: z<Config> = z.object({
-    provider: z.string().required(),
-    model: z.string().required(),
     workspaceRoot: z.string(),
   })
 
@@ -127,30 +71,9 @@ export class ApiProxyService extends Service implements ApiProxy {
   constructor(ctx: Context, config: Config) {
     super(ctx, 'apiProxy')
     const cwd = process.cwd()
-    // The composition entry is the shipped default; the settings section
-    // layers the user's own choice over it, and a deployment without a
-    // settings provider simply keeps the entry.
-    const entry: DefaultRouteSettings = { provider: config.provider, model: config.model }
-    let route: () => DefaultRouteSettings = () => entry
-    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
-      setSource: (current) => {
-        route = current
-      },
-      // Nothing registration-level derives from the default: every consumer
-      // reads it through the thunk at the moment it needs a route.
-      onChange: () => {},
-    })
     const api = createApiProxy(ctx, {
-      defaultTarget: () => routeTarget(route()),
-      // Wholesale, never a merge: switching to a model with no reasoning
-      // effort must clear a stored one, and a merged patch would strand it
-      // for the next session to fail on. This clears it because the entry
-      // below the user layer carries no effort to re-inherit — the reason
-      // `Config` deliberately has no such field. The section holds no
-      // secrets, so there is nothing a replace can collaterally drop.
-      persistDefaultTarget: async (target) => {
-        await ctx.get('settings')?.replace(API_GATEWAY_SETTINGS_NAMESPACE, target)
-      },
+      defaultModelSelection: () => ctx.agentDefaultModel.currentSelection(),
+      saveDefaultModelSelection: selection => ctx.agentDefaultModel.saveSelection(selection),
       cwd,
       workspaceRoot: resolve(config.workspaceRoot ?? cwd),
     })
diff --git a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
index e6555898cd..2272c7c61d 100644
--- a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
@@ -27,7 +27,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(ApprovalService)
-  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
   return { ctx, api }
 }
 
@@ -217,7 +217,7 @@ describe('approval pending registry', () => {
     await ctx.plugin(ApprovalService)
     let api!: ApiProxy
     const fiber = ctx.plugin(Object.assign((fiberCtx: Context) => {
-      api = createApiProxy(fiberCtx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+      api = createApiProxy(fiberCtx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     }, { inject: ['sessions', 'agents', 'userInteraction', 'approval'] }))
     await fiber.await()
     const abort = new AbortController()
diff --git a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
index 4943c051bb..ed2eaeefc5 100644
--- a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
@@ -35,7 +35,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy; attach: (sessio
   await ctx.plugin(AgentRegistry)
   return {
     ctx,
-    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
     attach: (session) => {
       ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     },
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 8e79c641a8..be76bf4cc6 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -64,7 +64,7 @@ describe('sessions.list cold merge', () => {
         return undefined
       },
     })
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.list(request({}))
     expect(response.result.ok).toBe(true)
@@ -92,7 +92,7 @@ describe('attached updatedAt excludes end-seed', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(UserInteractionService)
     await ctx.plugin(AgentRegistry)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     // Old work, resumed just now: the log tail would report the pickup.
     const worked = 1_000_000
@@ -150,7 +150,7 @@ describe('cold history recovery view', () => {
       inspect: (id: SessionId, signal?: AbortSignal) => coordinator.inspect(id, signal),
       locate: () => undefined,
     } as never)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId, beforeSeq: 2, maxMessages: 10 }))
     if (!history.result.ok) throw new Error('history failed')
@@ -206,7 +206,7 @@ describe('Remote Agent and Session lookup policy', () => {
     })
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -250,7 +250,7 @@ describe('Remote Agent and Session lookup policy', () => {
     const resume = vi.spyOn(ctx.agents, 'resume')
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -312,7 +312,7 @@ describe('subagent ownership fence', () => {
       locate: () => undefined,
     } as never)
     const resume = vi.spyOn(ctx.agents, 'resume')
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId }))
     expect(history.result.ok).toBe(true)
@@ -371,7 +371,7 @@ describe('subagent ownership fence', () => {
     // instead of answering `agent-busy`.
     const resume = vi.spyOn(ctx.agents, 'resume')
       .mockRejectedValue(new Error('registry unavailable in this bench'))
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const prompt = await api.sessions.prompt(request({
       sessionId,
@@ -412,7 +412,7 @@ describe('subagent ownership fence', () => {
     })
     const startingChild = { id: startingSession.id, session: startingSession, status: 'idle', ctx } as Agent
     ctx.agents.enter(startingChild, parent)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const stopped = await api.sessions.cancel(request({ sessionId: originChild.id }))
     expect(stopped.result.ok).toBe(false)
@@ -458,7 +458,7 @@ describe('subagent ownership fence', () => {
     const followup = vi.fn()
     const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
     ctx.agents.register(agent)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.prompt(request({
       sessionId: agent.id,
@@ -476,7 +476,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const listed = await api.sessions.list(request({}))
     expect(listed.result.ok).toBe(true)
@@ -501,7 +501,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
       list: () => Promise.resolve([]),
       inspect,
     } as never)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.history(request({ sessionId: sid('session-missing') }))
     expect(response.result.ok).toBe(false)
@@ -527,7 +527,7 @@ describe('sessions.prompt synchronous rejection', () => {
       followup: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
       steer: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
     } as unknown as Agent)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     for (const mode of ['queue', 'steer'] as const) {
       const response = await api.sessions.prompt(request({
@@ -571,7 +571,7 @@ describe('sessions.prompt synchronous rejection', () => {
       ctx.agents.register(child)
       throw new Error('session id already published')
     })
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const models = await api.sessions.models(request({ sessionId }))
     expect(models.result.ok).toBe(false)
diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
index 09526c5a87..b44701fca0 100644
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -25,7 +25,7 @@ import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
 import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 function request<P>(payload: P): RpcRequest<P> {
   return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 86a77f4af2..0beb7455cf 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -22,9 +22,10 @@ import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepsee
 import type { HostFrame } from '../src/api/index.ts'
 import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
-import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from '../src/api-proxy.ts'
+import { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-default-model'
+import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 let nextRpc = 1
 function request<P>(payload: P): RpcRequest<P> {
@@ -398,21 +399,21 @@ describe('settings domain', () => {
     expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'permission' }])
   })
 
-  it('invalidates the model catalog when the gateway default route changes', async () => {
+  it('invalidates the model catalog when the Agent default selection changes', async () => {
     const ctx = await harness()
-    const route = ctx.settings.register(API_GATEWAY_SETTINGS_NAMESPACE, z.object({
+    const defaultModel = ctx.settings.register(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, z.object({
       provider: z.string().required(),
       model: z.string().required(),
     }), { base: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } })
     const api = createApiProxy(ctx, DEFAULTS)
-    // The gateway's own section names the route every session with no logged
-    // one resolves to, so an externally edited default — another tab, a
+    // The shared section names the selection every blank session resolves to,
+    // so an externally edited default — another tab, a
     // hand-edited settings.yaml — has to reach an open selector as well.
     const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 2, async () => {
-      await route.replace({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+      await defaultModel.replace({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
     })
     expect(frames).toEqual([
-      { type: 'host/settings-changed', ns: 'api-gateway' },
+      { type: 'host/settings-changed', ns: 'agent-default-model' },
       { type: 'host/models-changed' },
     ])
   })
diff --git a/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts b/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
deleted file mode 100644
index 996cea5da2..0000000000
--- a/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * The `api-gateway` settings section over a REAL settings provider: the
- * composition entry as the base layer, the wholesale replace the gateway
- * persists with, and the fallback when the provider detaches. The other model
- * specs drive hand-rolled `defaultTarget`/`persistDefaultTarget` closures, so
- * this is the only place the layering itself is exercised.
- */
-
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import { Settings, installSettingsSection } from '@deepseek-ai/dsh-settings'
-import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
-import { API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA } from '../src/index.ts'
-import type { DefaultRouteSettings } from '../src/index.ts'
-
-/** The smallest real provider: one in-memory document, always writable. */
-class MemorySettings extends Settings {
-  doc: Record<string, unknown> = {}
-
-  get writable(): boolean {
-    return true
-  }
-
-  protected load(): Promise<Record<string, unknown>> {
-    return Promise.resolve(structuredClone(this.doc))
-  }
-
-  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
-    this.doc = { ...this.doc, [ns]: structuredClone(section) }
-    return Promise.resolve()
-  }
-}
-
-/** Mount the gateway's own section wiring over a live provider. */
-async function boot(entry: DefaultRouteSettings) {
-  const ctx = new Context()
-  const fiber = ctx.plugin(MemorySettings)
-  await fiber.await()
-  let route: () => DefaultRouteSettings = () => entry
-  const consumer = ctx.plugin(function section(child: Context) {
-    installSettingsSection(child, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
-      setSource: (current) => { route = current },
-      onChange: () => {},
-    })
-  })
-  await consumer.await()
-  const settings = ctx.get('settings')
-  if (settings === undefined) throw new Error('settings provider did not mount')
-  return { ctx, fiber, consumer, settings, read: () => route() }
-}
-
-describe('the api-gateway default-route section', () => {
-  it('resolves the composition entry until the user layer overrides it', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
-    })
-    expect(bench.read()).toEqual({
-      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
-    })
-    await bench.ctx.fiber.dispose()
-  })
-
-  it('clears a stored effort when the next switch has none', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
-    })
-    expect(bench.read().reasoningEffort).toBe('high')
-
-    // The whole reason the gateway persists with `replace` rather than a merge
-    // patch — and the reason `Config` carries no effort for the base layer to
-    // re-inherit here. A stranded effort would fail the next session's first
-    // request against a model that does not support it.
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-plain',
-    })
-    expect(bench.read()).toEqual({ provider: 'acme-gateway', model: 'acme-plain' })
-    await bench.ctx.fiber.dispose()
-  })
-
-  it('layers a hand-written partial section over the entry', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    // Someone editing settings.yaml by hand may name only the model. The
-    // entry supplies the provider, which is what makes this legal — and is
-    // exactly why an effort in the entry could never be cleared, so there
-    // is none to inherit.
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, { model: 'deepseek-reasoner' })
-    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
-    await bench.ctx.fiber.dispose()
-  })
-
-  it('falls back to the composition entry when the provider detaches', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-large',
-    })
-    expect(bench.read().provider).toBe('acme-gateway')
-
-    // A deployment that loses its settings provider keeps serving the route it
-    // was composed with rather than the one it can no longer read.
-    await bench.fiber.dispose()
-    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    await bench.ctx.fiber.dispose()
-  })
-})
diff --git a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
index fb6f8cdfed..bc1f0a14df 100644
--- a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
@@ -82,7 +82,7 @@ function liveAgent(
 }
 
 const api = (ctx: Context) => createApiProxy(ctx, {
-  defaultTarget: () => ({ provider: 'default-provider', model: 'default-model' }),
+  defaultModelSelection: () => ({ provider: 'default-provider', model: 'default-model' }),
   cwd: '/tmp',
   workspaceRoot: '/tmp',
 })
@@ -254,7 +254,7 @@ describe('sessions.fork', () => {
     await ctx.fiber.dispose()
   })
 
-  it('installs the latest logged model target before the child can run', async () => {
+  it('installs the latest logged model selection before the child can run', async () => {
     const ctx = await composed()
     const source = liveAgent(ctx, 'session-routed', 1)
     source.append('request/header', {
diff --git a/packages/host/apiproxy/tests/api-proxy-models.spec.ts b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
index 818260504c..83d0fa3916 100644
--- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
@@ -1,6 +1,6 @@
 /**
  * Web session model-directory and selection behavior: dynamic provider grouping,
- * provider-local catalog failures, logged-target restoration without stale
+ * provider-local catalog failures, logged-selection restoration without stale
  * catalog injection, advisory pass-through models, and the prompt-assembly
  * boundary for a running selection change.
  */
@@ -119,13 +119,13 @@ function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false
 }
 
 describe('Web session model selection', () => {
-  it('groups successful providers and leaves an unlisted current target out of the catalog', async () => {
+  it('groups successful providers and leaves an unlisted current selection out of the catalog', async () => {
     const { ctx, sessionId } = await harness({
       provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: ReasoningEffortId('max'),
     })
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const catalog = expectValue(await api.sessions.models(request({ sessionId })))
     expect(catalog.current).toEqual({
@@ -160,7 +160,7 @@ describe('Web session model selection', () => {
 
   it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
     const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
 
@@ -226,11 +226,11 @@ describe('Web session model selection', () => {
     await ctx.fiber.dispose()
   })
 
-  it('reads the host default live for a session whose log names no route', async () => {
+  it('reads the Agent default live for a session whose log names no selection', async () => {
     const { ctx, sessionId } = await harness()
     let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
     const api = createApiProxy(ctx, {
-      defaultTarget: () => stored,
+      defaultModelSelection: () => stored,
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
@@ -248,14 +248,14 @@ describe('Web session model selection', () => {
     await ctx.fiber.dispose()
   })
 
-  it('keeps a session that logged a route on it when the host default moves', async () => {
+  it('keeps a session on its logged selection when the Agent default differs', async () => {
     const { ctx, sessionId } = await harness({
       provider: 'deepseek-official',
       model: 'deepseek-chat',
     })
     let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
     const api = createApiProxy(ctx, {
-      defaultTarget: () => stored,
+      defaultModelSelection: () => stored,
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
@@ -271,9 +271,9 @@ describe('Web session model selection', () => {
     const saved: unknown[] = []
     let reject = false
     const api = createApiProxy(ctx, {
-      defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
-      persistDefaultTarget: (target) => {
-        saved.push(target)
+      defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      saveDefaultModelSelection: (selection) => {
+        saved.push(selection)
         return reject ? Promise.reject(new Error('read-only document')) : Promise.resolve()
       },
       cwd: '/tmp',
@@ -306,7 +306,7 @@ describe('Web session model selection', () => {
   it('refuses a prompt no adapter can route, and reports it on the directory', async () => {
     const { ctx, sessionId } = await harness()
     const api = createApiProxy(ctx, {
-      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      defaultModelSelection: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
@@ -339,7 +339,7 @@ describe('Web session model selection', () => {
     const api = createApiProxy(ctx, {
       // What a Models-page removal leaves behind: the settings document still
       // names the route the user last picked, and nothing serves it.
-      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      defaultModelSelection: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
diff --git a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
index c9cb212004..ddc558fefd 100644
--- a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
@@ -68,7 +68,7 @@ function seedMessages(session: Session, count: number): void {
   }
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
 describe('session.history projections block', () => {
   it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {
diff --git a/packages/host/apiproxy/tests/api-proxy-question.spec.ts b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
index 32835f5054..00f7fdfffe 100644
--- a/packages/host/apiproxy/tests/api-proxy-question.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
@@ -14,7 +14,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   return {
     ctx,
-    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
index 2f93cdd9b3..9d5ddb09fd 100644
--- a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
@@ -68,7 +68,7 @@ function liveAgent(ctx: Context, id: string, turns: number): Session {
   return session
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
 describe('sessions.rename', () => {
   it('accepts through the composed title service: normalized user-source event, echoed seq', async () => {
diff --git a/packages/host/apiproxy/tests/api-proxy-search.spec.ts b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
index 15a4ae3bf3..0220f4804b 100644
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -27,7 +27,7 @@ vi.mock('node:fs/promises', async (importOriginal) => {
 })
 
 const sid = (value: string): SessionId => value as SessionId
-const defaults = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const defaults = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 function request(query: string): RpcRequest<{ query: string }> {
   return { rpcId: RpcId(`search-${query}`), payload: { query } }
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index 62c7e653e0..7542d328ba 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -95,7 +95,7 @@ function bench(options: {
   ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
-    defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
   })
   return { api, getAgent, listChildren, inspect, snapshot, restore, followup, interrupt, parent }
 }
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 4490c71bc2..9810ff5cb8 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -105,7 +105,7 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 describe('mux live view computation', () => {
   it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
     const collected = collect(stream, 9, abort)
@@ -170,7 +170,7 @@ describe('mux live view computation', () => {
 
   it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     // history resolves the agent first; a live structural stub is enough (only
     // .session is read on this path).
@@ -238,7 +238,7 @@ describe('mux live view computation', () => {
 
   it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     session.append('turn/start', { turn: 1 })
@@ -287,7 +287,7 @@ describe('mux live view computation', () => {
 
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
 
@@ -308,7 +308,7 @@ describe('mux live view computation', () => {
 
   it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
     const collected = collect(stream, 4, abort)
diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
index aa560bdf58..637c2fcbe0 100644
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -100,7 +100,7 @@ async function harness(
   // object per harness mirrors the seam's stability contract.
   ctx.provide('directoryPicker', { capability: () => picker } as never)
   const api = createApiProxy(ctx, {
-    defaultTarget: () => ({ provider: 'test', model: 'test-model' }),
+    defaultModelSelection: () => ({ provider: 'test', model: 'test-model' }),
     cwd: workspaceRoot,
     workspaceRoot,
     ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index 476ebf344f..ad95275e38 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -41,7 +41,7 @@ function scriptedApi(overrides: {
       history: r => ok(r, {
         events: [],
         hasMore: false,
-        modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
       }),
       models: r => ok(r, {
         current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 75b6dff3f7..6d2ae5b23c 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -192,7 +192,7 @@ describe('sessions domain schemas', () => {
     expect(sessionHistoryValueSchema.parse({
       events: [],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }).hasMore).toBe(false)
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 64d7944892..eb22348935 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -35,6 +35,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../core/agent-default-model"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index e8381a56a6..302fd4c9b3 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -62,6 +62,20 @@ export interface TypeApiEntry {
 
 /** Every harness `ctx.<key>` service, sorted by key. */
 export const SERVICE_API: readonly ServiceApiEntry[] = [
+  {
+    key: 'agentDefaultModel',
+    summary: 'Owns the default model selection independently of any Host or transport.',
+    methods: [
+      {
+        signature: 'currentSelection(): ModelSelection',
+        jsDoc: '/**\n * Read the current default model selection.\n * @returns a detached provider, model, and optional reasoning selection.\n */',
+      },
+      {
+        signature: 'async saveSelection(next: ModelSelection): Promise<void>',
+        jsDoc: '/**\n * Save the complete default model selection. A deployment without a settings\n * provider keeps its composition entry.\n * @param next - resolved selection accepted by a front door.\n * @returns fulfillment after the optional settings write settles.\n */',
+      },
+    ],
+  },
   {
     key: 'agentLoop',
     summary: 'Concrete agent factory and driver service.',
@@ -2233,6 +2247,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ModelMessageSource',
     declaration: 'export interface ModelMessageSource extends AssistantProvenance {\n    kind: \'model\';\n}',
   },
+  {
+    name: 'ModelSelection',
+    declaration: 'export interface ModelSelection {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n}',
+  },
   {
     name: 'ObjectJsonSchema',
     declaration: 'export type ObjectJsonSchema = JsonSchemaNode & {\n    type: \'object\';\n};',
diff --git a/packages/todo/tool-todo/tests/projection.spec.ts b/packages/todo/tool-todo/tests/projection.spec.ts
index 08cb7d3216..d6d459a4d7 100644
--- a/packages/todo/tool-todo/tests/projection.spec.ts
+++ b/packages/todo/tool-todo/tests/projection.spec.ts
@@ -45,7 +45,7 @@ async function harness(withTodoTool: boolean): Promise<Bench> {
   if (withTodoTool) await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
   const session = ctx.sessions.create()
   ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
-  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
   return {
     ctx,
     session,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e9726e9bee..bd2eab469c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1013,6 +1013,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-default-model':
+        specifier: workspace:^
+        version: link:../../core/agent-default-model
       '@deepseek-ai/dsh-agent-loop':
         specifier: workspace:^
         version: link:../../core/agent-loop
@@ -1233,6 +1236,9 @@ importers:
 
   packages/bundle/headless:
     dependencies:
+      '@deepseek-ai/dsh-code-runtime-worker':
+        specifier: workspace:^
+        version: link:../../code-runtime/code-runtime-worker
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
@@ -1243,15 +1249,15 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
-      '@deepseek-ai/dsh-host-apiproxy':
+      '@deepseek-ai/dsh-agent-default-model':
         specifier: workspace:^
-        version: link:../../host/apiproxy
-      '@deepseek-ai/dsh-host-webserver':
-        specifier: workspace:^
-        version: link:../../host/webserver
+        version: link:../../core/agent-default-model
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -2935,6 +2941,28 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/core/agent-default-model:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-settings':
+        specifier: workspace:^
+        version: link:../../settings/settings
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/core/agent-loop:
     dependencies:
       schemastery:
@@ -3893,6 +3921,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-default-model':
+        specifier: workspace:^
+        version: link:../../core/agent-default-model
       '@deepseek-ai/dsh-api-remotes':
         specifier: workspace:^
         version: link:../../api/remotes
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 66b3cea813..de53d44755 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -44,6 +44,7 @@ export { REGION_BEGIN, REGION_END }
  */
 export const SERVICE_PAGE: Record<string, string> = {
   agentLoop: 'core.md',
+  agentDefaultModel: 'core.md',
   agents: 'core.md',
   approval: 'approval.md',
   bash: 'bash.md',
@@ -196,6 +197,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   AgentCancelCause: 'core.md',
   AgentFactory: 'core.md',
   AgentHandle: 'core.md',
+  ModelSelection: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
   ContentBlock: 'llm-streaming.md',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index cc26b6b0af..745bc23e4f 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -307,6 +307,14 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
+  {
+    key: 'agentDefaultModel',
+    pkg: 'agent-default-model',
+    title: 'Default Agent model selection',
+    mode: 'core',
+    consumers: ['headless', 'host-apiproxy'],
+    note: 'Layers the default ModelSelection through settings so direct and Host-backed Agent front doors share one state owner.',
+  },
   {
     key: 'agentLoop',
     pkg: 'agent-loop',
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index f25007786c..ded84487bf 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index a0eec4960f..20e6c4bc14 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -48,6 +48,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/core/agent-default-model': { kind: 'indirect', reason: 'The service supplies a ModelSelection; request assembly and adapters own the model-visible request.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
   'packages/e2b/e2b': { kind: 'none', reason: 'The shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.' },
@@ -68,7 +69,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },
-  'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the host snapshots the target at the next prompt-assembly boundary and owns the model-visible effect.' },
+  'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the Host snapshots the selection at the next prompt-assembly boundary and owns the model-visible effect.' },
   'packages/client/ui-goal': { kind: 'indirect', reason: 'The strip verbs route goal.* mutations; the host GoalService owns the model-visible goal/change context message.' },
   'packages/client/ui-permission': { kind: 'indirect', reason: 'The picker submits the host /permission command; the knob events it appends own the model-visible effect through the sandbox/approval consumers.' },
   'packages/client/ui-plan': { kind: 'indirect', reason: 'The chip dispatches /plan off; dsh-plan-mode owns the model-visible policy, exit tool, and logged state.' },
@@ -94,7 +95,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' },
   'packages/host/frontend-static': { kind: 'none', reason: 'The SPA dist server answers browser asset requests and registers no model surface.' },
   'packages/bundle/base': { kind: 'indirect', reason: 'The bundle is a patch-list carrier; each inserted row\'s package owns its model surface.' },
-  'packages/bundle/headless': { kind: 'none', reason: 'The one-shot runner submits the task as an ordinary user message; prompts and tools belong to the composed base/web bundles.' },
+  'packages/bundle/headless': { kind: 'none', reason: 'The one-shot runner submits the task as an ordinary user message; prompts and tools belong to the composed base and headless bundles.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 31631995cf..f890487f3b 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -138,6 +138,7 @@
     { "path": "./packages/session/session-telemetry-otel" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
+    { "path": "./packages/core/agent-default-model" },
     { "path": "./packages/interaction/commands" },
     { "path": "./packages/goal/goal" },
     { "path": "./packages/goal/tool-goal" },

From 63b6e18f71e9e5f65ce344714cde6083e3ffba02 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 13:35:00 +0800
Subject: [PATCH 203/262] fix(headless): terminal model failures reach stderr

---
 ...-headless-direct-core-front-door.i18n.yaml |  4 +-
 ...6-08-09-headless-direct-core-front-door.md |  4 +-
 ...8-09-headless-direct-core-front-door.zh.md |  4 +-
 .../tests/fixtures/cli-mock-llm.ts            |  4 ++
 .../headless-agent/tests/headless.snapshot.ts | 41 +++++++++++++++----
 .../snapshots/dsh-run/stderr.expected.txt     |  1 +
 packages/bundle/headless/README.i18n.yaml     |  4 +-
 packages/bundle/headless/README.md            |  2 +-
 packages/bundle/headless/README.zh.md         |  2 +-
 packages/bundle/headless/src/index.ts         | 11 +++--
 .../bundle/headless/tests/headless.spec.ts    | 21 ++++++++++
 11 files changed, 76 insertions(+), 22 deletions(-)
 create mode 100644 examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt

diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
index cab1c8e338..921bc193e4 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.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 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
-2026-08-09-headless-direct-core-front-door.md: cae17970633d6eda9d4f823118827ee2bfe32abf
-2026-08-09-headless-direct-core-front-door.zh.md: 8ff5e870b7f0fbc82065c6c55b4635cdc586036c
+2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
+2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
index cae1797063..875939b424 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
@@ -14,7 +14,7 @@ The direct front door still needs the same deployment model state as Web-created
 
 The shipped `headless` profile contains `dsh-base` and `dsh-headless`. The headless bundle supplies its persona and tool mode, disables HMR, mounts the Code Mode worker explicitly, and inserts `headless-runner`. Its tree contains no `@deepseek-ai/dsh-host-*` package, ApiProxy, HTTP server, Web runtime, or browser client. Code Mode and Session persistence are one-shot Agent capabilities independent of Web presentation.
 
-`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. Unexpected driver failures use stderr and exit 1.
+`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. A terminal `error` reason writes its durable code and message to stderr; unexpected driver failures also use stderr and exit 1.
 
 `@deepseek-ai/dsh-agent-default-model` owns the transport-independent default used for an Agent without a session-local selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers the `agent-default-model` Settings section. Composition config supplies `{provider, model}`; user settings may also supply `reasoningEffort`. `currentSelection()` returns the live complete selection and `saveSelection()` writes it as a complete section, so a selection without an effort clears any stored effort. `dsh-base` supplies the composition entry. Direct and ApiProxy front doors consume this service; ApiProxy alone owns session-local precedence, model validation, and persistence of accepted Web selections.
 
@@ -24,7 +24,7 @@ This note owns the headless transport and completion contracts. [`dsh run` owns
 
 ## Verification
 
-Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshot drives `dsh run` through a replayed tool round trip and records direct user-message provenance. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record direct user-message provenance, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
index 8ff5e870b7..7de5efbe17 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 随附的 `headless` profile 包含 `dsh-base` 与 `dsh-headless`。headless 组合包提供自身的 persona 与工具模式、禁用 HMR（热模块替换）、显式挂载 Code Mode worker，并插入 `headless-runner`。其插件树不包含任何 `@deepseek-ai/dsh-host-*` 包、ApiProxy、HTTP server、Web 运行时或浏览器客户端。Code Mode 与会话持久化均为独立于 Web 呈现的一次性 Agent 能力。
 
-`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。驱动器的意外失败写入 stderr 并以 1 退出。
+`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。结束原因为 `error` 时，其持久化错误码与消息写入 stderr；驱动器的意外失败也写入 stderr 并以 1 退出。
 
 `@deepseek-ai/dsh-agent-default-model` 拥有与传输无关的默认值，供没有会话级选择的 Agent 使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel` 并注册 `agent-default-model` Settings 分节。组合配置提供 `{provider, model}`，用户设置还可以提供 `reasoningEffort`。`currentSelection()` 返回当前的完整选择，`saveSelection()` 则写入完整分节，因此不含强度的选择会清除已存强度。`dsh-base` 提供组合条目。直接前门与 ApiProxy 前门均消费该服务；只有 ApiProxy 负责会话级优先级、模型校验与已接受 Web 选择的持久化。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 验证
 
-包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，并记录直接用户消息的来源。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录直接用户消息的来源，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
 
 ## 考虑过的替代方案
 
diff --git a/examples/headless-agent/tests/fixtures/cli-mock-llm.ts b/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
index 80a4f7e240..b0b120ecb2 100644
--- a/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
+++ b/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
@@ -29,6 +29,10 @@ class CliMockAdapter extends LlmAdapter {
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if (process.env.DSH_CLI_MOCK_FAILURE === '1') {
+      yield { type: 'finish', reason: { kind: 'error', failure: { code: 'SERVER', message: 'CLI mock provider failed' } } }
+      return
+    }
     const toolResult = options.messages.at(-1)?.content.find(block => block.type === 'tool-result')
     if (toolResult === undefined) {
       const args = JSON.stringify({ command: 'printf CLI_TOOL_ROUND_TRIP', description: 'Prove the CLI tool round trip.' })
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 593b05b4e8..ff00d42b6b 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -54,6 +54,7 @@ const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', i
 const deepseekDefaultsConfigPath = fileURLToPath(new URL('./fixtures/deepseek-defaults.cordis.yml', import.meta.url))
 const dshRunOverlayPath = fileURLToPath(new URL('./fixtures/dsh-run.cordis.yml', import.meta.url))
 const dshRunSessionExpected = join(snapshotsDir, 'dsh-run', 'session.expected.jsonl')
+const dshRunFailureExpected = join(snapshotsDir, 'dsh-run', 'stderr.expected.txt')
 const cliMockLlmPluginPath = fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url))
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 
@@ -196,6 +197,16 @@ async function persistedLogs(cwd: string, root: string = join(cwd, '.sessions'))
   }))
 }
 
+/** Install the keyless product-CLI adapter into the temporary headless profile. */
+async function prepareCliMockFixture(cwd: string): Promise<void> {
+  const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
+  await mkdir(fixtureDir, { recursive: true })
+  await Promise.all([
+    copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
+    writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
+  ])
+}
+
 describe('headless stream-json snapshots', () => {
   it('runs one task through the product dsh run command', async () => {
     const task = 'Prove the product dsh run path with one real tool round trip.'
@@ -211,14 +222,7 @@ describe('headless stream-json snapshots', () => {
         DSH_TELEMETRY_DISABLED: '1',
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
       },
-      prepare: async (cwd) => {
-        const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
-        await mkdir(fixtureDir, { recursive: true })
-        await Promise.all([
-          copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
-          writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
-        ])
-      },
+      prepare: prepareCliMockFixture,
       inspect: async (cwd) => {
         const logs = await persistedLogs(cwd, join(cwd, '.dsh', 'sessions'))
         expect(logs).toHaveLength(1)
@@ -237,6 +241,27 @@ describe('headless stream-json snapshots', () => {
     expect(result.stderr).toBe('')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('prints a terminal model failure through the product dsh run command', async () => {
+    const result = await runLoaderSmoke({
+      label: 'product dsh run model failure snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-run-failure-',
+      binScript: dshBinScript,
+      configPath: dshRunOverlayPath,
+      binArgs: ['run', '--patch', dshRunOverlayPath, 'Trigger the keyless model failure.'],
+      tsconfigPath,
+      expectedExitCode: 1,
+      env: {
+        DSH_CLI_MOCK_FAILURE: '1',
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: prepareCliMockFixture,
+    })
+
+    expect(result.stdout).toBe('\n')
+    await expect(result.stderr).toMatchFileSnapshot(dshRunFailureExpected)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('prints the original Loader activation error through the assembled one-shot app', async () => {
     const result = await runLoaderSmoke({
       label: 'headless startup activation error snapshot',
diff --git a/examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt b/examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt
new file mode 100644
index 0000000000..79665a83c3
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt
@@ -0,0 +1 @@
+dsh: SERVER: CLI mock provider failed
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index ea768061df..4d43c64eb3 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: 6faf1dc732345a86ec1d7b60c4f9a606e0491512
-README.zh.md: a189f77f57cf0f641abe7c11288dbc1cdf05355a
+README.md: fbdf80be3d587b0ef526c1a36952a761035f7312
+README.zh.md: 833737e08643e0ad6b585f93fdc6ae018242b937
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index 6faf1dc732..fbdf80be3d 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
 
-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A successful run writes nothing to stderr and opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index a189f77f57..833737e086 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -4,7 +4,7 @@
 
 dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
 
-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。成功运行时不会向 stderr 写入任何内容，也不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index 670838661a..2ea68c441b 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -38,7 +38,7 @@ export const Config: z<Config> = z.object({
 /** Outcome of one owned run interval. */
 interface RunOutcome {
   text: string
-  reason: string
+  reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
 }
 
 /**
@@ -63,7 +63,7 @@ declare module 'cordis' {
 function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcome {
   let started = false
   let text = ''
-  let reason = 'error'
+  let reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
   for (const event of events) {
     if (event.seq < firstSeq) continue
     if (event.type === 'turn/start') {
@@ -78,7 +78,7 @@ function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcom
         .join('')
       if (joined !== '') text = joined
     }
-    if (event.type === 'turn/end') reason = event.data.reason.kind
+    if (event.type === 'turn/end') reason = event.data.reason
   }
   return { text, reason }
 }
@@ -125,7 +125,10 @@ async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
   await sessions.flush(agent.session)
   const outcome = summarize(agent.session.events, firstSeq)
   io.stdout.write(outcome.text + '\n')
-  io.exit(outcome.reason === 'completed' ? 0 : 1)
+  if (outcome.reason?.kind === 'error') {
+    io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`)
+  }
+  io.exit(outcome.reason?.kind === 'completed' ? 0 : 1)
 }
 
 /**
diff --git a/packages/bundle/headless/tests/headless.spec.ts b/packages/bundle/headless/tests/headless.spec.ts
index 294c224354..bd24a9300a 100644
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -151,6 +151,27 @@ describe('headless runner', () => {
     await test.ctx.fiber.dispose()
   })
 
+  it('prints the durable model failure when the final turn ends in error', async () => {
+    const test = await bench({
+      afterPrompt(session, message) {
+        session.append('turn/start', { turn: 1 })
+        session.append('step/start', { turn: 1, step: 1 })
+        session.append('user/message', message, { surfaceOp: 'append' })
+        session.append('step/end', { turn: 1, step: 1 })
+        session.append('turn/end', {
+          turn: 1,
+          reason: { kind: 'error', error: { code: 'SERVER', message: 'provider unavailable' } },
+        })
+      },
+    })
+    expect(await test.run()).toMatchObject({
+      code: 1,
+      out: '\n',
+      err: 'dsh: SERVER: provider unavailable\n',
+    })
+    await test.ctx.fiber.dispose()
+  })
+
   it('exits 1 when the owned interval contains no turn', async () => {
     const test = await bench({ afterPrompt: () => {} })
     expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })

From 6607775604481a64825b5b3f1c95c6a07ebd4146 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 13:46:14 +0800
Subject: [PATCH 204/262] fix(docs): close final translation review gaps

---
 .../2026-07-12-agent-scope-runtime-design.i18n.yaml       | 2 +-
 .../2026-07-12-agent-scope-runtime-design.zh.md           | 8 ++++----
 .../2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml  | 2 +-
 .../2026-07-30-followup-enqueue-and-owned-runs.zh.md      | 2 +-
 .../2026-08-08-trusted-repository-package-code.i18n.yaml  | 2 +-
 .../2026-08-08-trusted-repository-package-code.zh.md      | 4 ++--
 ...31-composer-text-layers-share-one-scrollport.i18n.yaml | 2 +-
 ...-07-31-composer-text-layers-share-one-scrollport.zh.md | 2 +-
 .../2026-07-31-fail-loud-releases-the-terminal.i18n.yaml  | 2 +-
 .../2026-07-31-fail-loud-releases-the-terminal.zh.md      | 4 ++--
 .../2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml   | 2 +-
 .../2026-08-03-hmr-initial-scan-boot-deadlock.zh.md       | 2 +-
 .../2026-08-04-composer-tab-gutter-reservation.i18n.yaml  | 2 +-
 .../2026-08-04-composer-tab-gutter-reservation.zh.md      | 2 +-
 ...npm-backed-git-repository-plugin-preparation.i18n.yaml | 2 +-
 ...-08-npm-backed-git-repository-plugin-preparation.zh.md | 8 ++++----
 .../2026-07-26-todo-parallel-in-progress.i18n.yaml        | 2 +-
 .../feature/2026-07-26-todo-parallel-in-progress.zh.md    | 4 ++--
 .../2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml  | 4 ++--
 .../process/2026-07-02-bilingual-docs-and-pairing-gate.md | 2 +-
 .../2026-07-02-bilingual-docs-and-pairing-gate.zh.md      | 2 +-
 packages/boot/app-boot/README.i18n.yaml                   | 2 +-
 packages/boot/app-boot/README.zh.md                       | 6 +++---
 packages/host/directory-picker-native/README.i18n.yaml    | 2 +-
 packages/host/directory-picker-native/README.zh.md        | 4 ++--
 packages/support/acp-snapshot/README.i18n.yaml            | 2 +-
 packages/support/acp-snapshot/README.zh.md                | 2 +-
 scripts/project-doc-site.spec.ts                          | 1 +
 .../translation-prompt-v4/request-response.expected.json  | 4 ++--
 scripts/translation-pairing.ts                            | 1 +
 30 files changed, 44 insertions(+), 42 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index 380171ab17..df9ebc9337 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
 2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: e0c01f31eb2664608139f95dc60025a5b33e4618
+2026-07-12-agent-scope-runtime-design.zh.md: b78cd5dfd97e6825e404e06666908c6b53ac9709
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index e0c01f31eb..b78cd5dfd9 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与提示词、subagent 与工作流，最后是可执行检查。
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md) 仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) 拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
@@ -208,7 +208,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。Schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
 
-[subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule)拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
+[subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule) 拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
 
 `ToolRestriction` 接受 readonly 的 allow/deny 名称并将其编译为内部集合。多个限制取交集。公开的 `visible()` 和 `knownNames()` 方法是不必要的，因为只有注册表需要中间视图。
 
@@ -330,13 +330,13 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 生成的产物使公开约定保持对齐
 
-事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。
+事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md) 拥有 Program 构造、语义事件发现和解析器生成规则。
 
 行为测试固定了作用域路由和 dispose、最终写入注册表时的碰撞清理、发布回滚、有序完全停稳、持久化前/后提交行为、跨展示和执行的活跃工具过滤、协作式提示词组装、原生和 Code Mode 中的结构化输出提交、异步 subagent 启动和信号取消、worker 终端仲裁、ACP 结算和进程拆除。
 
 ## 曾考虑的替代方案
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered) 拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
 
 ### 使用透明代理作为作用域载体
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index b4863f08b5..a066480489 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
 2026-07-30-followup-enqueue-and-owned-runs.md: 54f4af75eeb29b06504fa2629b0665f3e5f4c4ee
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: 51f82b7c703be13165e0cd7d7b354ea14e3a965e
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: 226f0b9b61883cee5f6e321ae6b89b7b27b79e35
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index 51f82b7c70..226f0b9b61 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
 
-ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或dispose（资源释放）并列。
+ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或 dispose（资源释放）并列。
 
 Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index af4950b20c..9d49d8b1c2 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
 2026-08-08-trusted-repository-package-code.md: 387479b3b36a8bc5e145641ae40802b3090ced70
-2026-08-08-trusted-repository-package-code.zh.md: aff34d4485553f076c5dd1b71f0a3c5b5c62bc8f
+2026-08-08-trusted-repository-package-code.zh.md: ecc325c3dd0a9e823f1411c3a809c30ada486289
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index aff34d4485..ecc325c3dd 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -24,7 +24,7 @@
 
 精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest 和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
 
-模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务契约。
+模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务约定。
 
 ## 考虑过的替代方案
 
@@ -34,7 +34,7 @@
 
 **隐式导入 `main`、`exports` 或其他发现的入口。** 拒绝，因为 NPM 包可能包含并非 Cordis 插件的实用工具或 MCP 可执行文件。显式 `dsh.entry` 字段使代码激活可供评审，并让准备阶段校验打包后的路径。
 
-**为未来每种 DSH 贡献添加封闭 manifest 字段。** 不采用它作为通用扩展机制。skill 和通用 MCP 文件仍保留有用的可移植静态适配器；DSH 原生行为则通过现有 Cordis 插件与服务契约组合。
+**为未来每种 DSH 贡献添加封闭 manifest 字段。** 不采用它作为通用扩展机制。skill 和通用 MCP 文件仍保留有用的可移植静态适配器；DSH 原生行为则通过现有 Cordis 插件与服务约定组合。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
index 71f89e6866..d9a9857cc8 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md
 2026-07-31-composer-text-layers-share-one-scrollport.md: ba11384409714d6a64a964d63197705acf39d213
-2026-07-31-composer-text-layers-share-one-scrollport.zh.md: cf0ce7bc344f6566d56a9e3cd81a63be5f68d614
+2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 7a2500a6253c7cf50a57458b66c9b80503414ace
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
index cf0ce7bc34..7a2500a625 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
@@ -63,7 +63,7 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 - 光标不可能离开自己的字形。浏览器滚动的是同一个盒子，因此「textarea 把某一行放在哪」与「backdrop 把这一行画在哪」之间的距离在任何偏移下都是一个固定的行盒常量，手势进行中也不例外。场景测试度量的正是这个数。
 - 滚动条从 textarea 移到了滚动容器上——视觉位置相同，只是外移了一层。`.card` 的 l2 token 绑定仍会继承下去。
 - chip、claim token 高亮与文本引用标记在滚动时仍与其字形对齐，因为它们定位在 backdrop 内部、随之移动。除去掉哨兵之外，装饰扫描没有变化。
-- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话 transcript（文本记录）滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到transcript 的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
+- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话 transcript（文本记录）滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到 transcript 的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
 - 翻页与拖拽选区的行为未变，二者均做了新旧对照实测。`PageDown`/`PageUp` 本来就不会移动 textarea 的插入点——chromium 是滚动一页并保持 `selectionStart` 不变，新旧几何皆然，区别只在于滚的是哪个盒子。拖拽选区越过下边缘仍会自动滚动，且落点一致（chromium 628/628、firefox 625/620、WebKit 170/170——WebKit 自动滚动较慢，但改动前后一样慢）。
 - composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，因此如果没有这个独立 effect，第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
 - 撤销/重做可以在不恢复光标、也不回视的情况下改动草稿：状态机重放上一版草稿，DOM 选区停在浏览器钳位后的位置。这早于本次改动且未被改动——在此点名，是因为另外两处恢复都会回视，会让这处遗漏看起来像有意为之；真被报告时 helper 就在旁边。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index 6bf16a8981..7449d1b5fc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
 2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: d5fdf72013259a60df64e8f79e64169770f3435c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 407161d112cbbb6f476773f6f7e21c2ce820956e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index d5fdf72013..407161d112 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -17,9 +17,9 @@ zsh: command not found: 4cecho
 
 Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动顺序。`ui-tui` 会先激活并调用 pi-tui 的 `ProcessTerminal.start()`，它把 stdin 置为 raw 模式、启用 bracketed paste，并写出 Kitty 键盘协议探测序列——该序列以一个 Device Attributes 查询（`ESC [ c`）结尾。随后某个同级条目（这里是 `llm-pi-ai`）因自身配置而 rejection。
 
-在当时，该 rejection 以未处理 rejection 的形式浮现，而 `installFailLoud` 只写一行 stderr 就立即调用 `process.exit(1)`。（事务化 Loader 现在让配置树失败经 `boot()` 结算，由它自行释放部分构建的上下文；release 回调仍然守护 `boot()` 看不到的 rejection——插件游离的异步工作在挂载期间或挂载之后失败。）没有任何环节释放这棵树，因此 `ProcessTerminal.stop()` 从未执行：raw 模式、bracketed paste 和键盘协议都残留在比进程活得更久的 shell 上。终端对 Device Attributes 查询的回应（`1;2;4c`）在进程退出之后才到达，被 shell 当作用户输入读入——也就是上面那段字面文本。
+在当时，该 rejection 以未处理 rejection 的形式浮现，而 `installFailLoud` 只写一行 stderr 就立即调用 `process.exit(1)`。（事务化 Loader 现在让配置树失败经 `boot()` 结算，由它自行 dispose（资源释放）部分构建的上下文；release 回调仍然守护 `boot()` 看不到的 rejection——插件游离的异步工作在挂载期间或挂载之后失败。）没有任何环节 dispose 这棵树，因此 `ProcessTerminal.stop()` 从未执行：raw 模式、bracketed paste 和键盘协议都残留在比进程活得更久的 shell 上。终端对 Device Attributes 查询的回应（`1;2;4c`）在进程退出之后才到达，被 shell 当作用户输入读入——也就是上面那段字面文本。
 
-`/exit` 路径从不受影响，因为它会释放整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
+`/exit` 路径从不受影响，因为它会 dispose 整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 1ca6de64cd..b265906af0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
 2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: a023420182971a62f125808f777f877bafe3e9e2
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 7123e423aab1293d138a1c24cb0dded00a83c89a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index a023420182..7123e423aa 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -20,7 +20,7 @@
 - `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 一条的 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
 - `hmr/src/index.ts` 给主 watcher 传入 `ignoreInitial: true`。初始扫描只会重新宣告启动刚刚消费过的文件；抑制它同时消除了启动期 refresh 和对已加载模块的多余 `add` 事件。`registerConfig()` 保留自己 `ignoreInitial: false` 的 watcher，因为注册时已存在的个人配置必须恰好应用一次。
 
-两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚释放整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
+两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚并 dispose（资源释放）整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
index 64ec136c6d..3b41a39be5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md
 2026-08-04-composer-tab-gutter-reservation.md: 3b28c35c1f11676e41cabde76d1b0d16c688f034
-2026-08-04-composer-tab-gutter-reservation.zh.md: 8c435d85a2a068684ac4781296963f822df43484
+2026-08-04-composer-tab-gutter-reservation.zh.md: 8724195a53a846d0fb09fb1182f94a40214c23d8
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
index 8c435d85a2..8724195a53 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
@@ -10,7 +10,7 @@ composer 座位在组件树中只有一个节点、一个位置，但它究竟
 
 在 Chat 中它是会话列滚动容器（`[data-conversation-scroll]`）的 sticky **子元素**，因而依附于该容器的 content box——而占布局宽度的滚动条会把这个盒子收窄一条滚动条的宽度。声明了 `data-conversation-composer-overlay` 的视图（Trajectory 即是其一）会把会话列的滚动搬进视图自身：以该属性为条件的那条分支把滚动容器留作 `overflow: hidden`，并把座位改为绝对定位——对齐的是 padding box，而滚动条从不收窄这个盒子。
 
-于是只要transcript（文本记录）超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：transcript 增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
+于是只要 transcript（文本记录）超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：transcript 增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
index f13bae898a..86e63238fa 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
 2026-08-08-npm-backed-git-repository-plugin-preparation.md: 958b932f82f4da3cf63aa911260411855e514409
-2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 4986c55787f291ba9e0d4594854c15eb3c892c72
+2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: d2256e0eae303c371371b9b5ba1967105aa61834
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
index 4986c55787..d2256e0eae 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
@@ -6,7 +6,7 @@
 
 ## 问题
 
-repository 插件创作契约要求 `scripts.prepack` 调用 `dsh-plugin-prepare`。如果由正在运行的 DSH 安装提供该可执行文件，即使源包自身的 manifest（元数据清单）无法取得辅助程序，它也会显得有效。因此，这并未证明 `@deepseek-ai/dsh-repository-plugin` 发布后用户所需的行为：普通 Git 托管 NPM 包必须只依靠自身声明的依赖即可安装和准备。
+repository 插件创作约定要求 `scripts.prepack` 调用 `dsh-plugin-prepare`。如果由正在运行的 DSH 安装提供该可执行文件，即使源包自身的 manifest（元数据清单）无法取得辅助程序，它也会显得有效。因此，这并未证明 `@deepseek-ai/dsh-repository-plugin` 发布后用户所需的行为：普通 Git 托管 NPM 包必须只依靠自身声明的依赖即可安装和准备。
 
 pnpm workspace 内可选择的 `.dsh-plugin` 还有另一项隔离要求。pnpm 会在打包所选子目录前运行仓库首选的包管理器，以准备 Git 托管包。嵌套的 `pnpm install` 可能加入外层 workspace；当根 lockfile 未把 `.dsh-plugin` 列为 importer 时，pnpm 可能报告成功，却未安装仅由该包声明的依赖。随后，其 TypeScript 构建或准备命令会失败；也可能因为存在预生成产物，依赖缺失被掩盖。
 
@@ -16,7 +16,7 @@ pnpm workspace 内可选择的 `.dsh-plugin` 还有另一项隔离要求。pnpm
 
 `.dsh-plugin` 包将已发布的 `@deepseek-ai/dsh-repository-plugin` 声明为普通开发依赖，并在 `scripts.prepack` 中调用其已发布的 `dsh-plugin-prepare` 可执行文件。该包可以声明其他任意构建依赖与运行时依赖，并在辅助程序前执行任意编译。repository 插件包把 Cordis 与 DSH 对等依赖（peer dependency）标为可选，因此仅为使用辅助程序而进行的开发安装只会解析辅助程序实际依赖的 `zod` 运行时依赖；应用组合仍会提供该包 Cordis 入口所使用的对等依赖。
 
-DSH 不会生成准备阶段可执行文件，也不会将其前置到 `PATH`。`RepositoryCache` 只提供一个由事务持有的 `pnpm` 包装脚本：外层安装直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会以 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行负责依赖解析，正常的包管理器生命周期 `PATH` 构造会暴露 `node_modules/.bin/dsh-plugin-prepare`。临时 pnpm 包装脚本会在子进程结算后消失。repository 仍是受信任的包管理器输入：所有依赖与生命周期代码都按既有信任契约执行。
+DSH 不会生成准备阶段可执行文件，也不会将其前置到 `PATH`。`RepositoryCache` 只提供一个由事务持有的 `pnpm` 包装脚本：外层安装直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会以 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行负责依赖解析，正常的包管理器生命周期 `PATH` 构造会暴露 `node_modules/.bin/dsh-plugin-prepare`。临时 pnpm 包装脚本会在子进程结算后消失。repository 仍是受信任的包管理器输入：所有依赖与生命周期代码都按既有信任约定执行。
 
 Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 派生的精确源。它复用现有私有 DeepSeek Harness 仓库，而不会为每次运行新建仓库。作业作用域的 Git 配置允许只读作业 token 访问该精确私有源，并把 pnpm 的 SSH 回退改写为已认证 HTTPS。
 
@@ -26,7 +26,7 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 
 
 **从正在运行的 DSH 安装注入 `dsh-plugin-prepare`。** 拒绝，因为这会让 manifest 不完整的 repository 包通过，并测试 NPM 消费方无法复现的纯宿主路径。
 
-**把源 fixture 本身发布到 NPM。** 拒绝，因为产品契约明确要求 DSH 插件仍托管在 Git；只有可复用的准备辅助程序是 NPM 依赖。
+**把源 fixture 本身发布到 NPM。** 拒绝，因为产品约定明确要求 DSH 插件仍托管在 Git；只有可复用的准备辅助程序是 NPM 依赖。
 
 **在每次 CI 运行中创建新的私有 GitHub 仓库。** 拒绝，因为 PR 仓库的精确 head SHA 已是经过认证的真实私有 Git remote。每次运行的仓库变更会增加凭据、清理和最终一致性失败模式，却不改变获取路径。
 
@@ -45,4 +45,4 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 
 
 ## 测试
 
-`packages/boot/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
+`packages/boot/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式约定。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 43076fbfe4..90ea440ef8 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
 2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: 64047e8b27e779e6ca23ea6c435bcdfecf38066d
+2026-07-26-todo-parallel-in-progress.zh.md: ebd4b1567eba637493956993b43b1ec56df14c39
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 64047e8b27..ebd4b1567e 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -41,9 +41,9 @@ Status: implemented
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
-`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的slot；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
+`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的 slot；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
 
-`summarySuffix` 是 `ToolRow` 上的slot，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
+`summarySuffix` 是 `ToolRow` 上的 slot，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
 
 ## 暂缓项
 
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 56ffbc366d..4fd3657a7d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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 .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
-2026-07-02-bilingual-docs-and-pairing-gate.md: b462efd99c008a1e8254b6754a408e9e94e787d6
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 564442ce9bd09a448c030e30f34930673a06727b
+2026-07-02-bilingual-docs-and-pairing-gate.md: 930efd3a2df8ad99b3c209c6084436ab6b27dc0a
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 2e288a29e9484683b9961d1e420a6e92ca05e5fe
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index b462efd99c..930efd3a2d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -12,7 +12,7 @@ This repo's documentation corpus is read by people and agents inside and outside
 
 - **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).
 - **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.
-- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.
+- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.
 - **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.
 - **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.
 - **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 564442ce9b..2e288a29e9 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 - **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。
 - **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
-- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。
+- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。
 - **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。
 - **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。
 - **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 7885dd3280..330c4c43ac 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: a0a437437f3bb562f0a0d2bb52b1cba1df681606
+README.zh.md: 6ff915c618f636f05f1f8591433feb3aef9151a8
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index a0a437437f..6ff915c618 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -18,14 +18,14 @@
 | `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
 | `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步清理函数 |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时释放部分构造的上下文，并返回带标签的拒绝结果 |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并返回带标签的拒绝结果 |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
-Loader 结算会在导入或生命周期失败时返回拒绝结果，并携带失败的配置项与阶段；`boot()` 会释放部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
+Loader 结算会在导入或生命周期失败时返回拒绝结果，并携带失败的配置项与阶段；`boot()` 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
 
-Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间，处理函数保持注册并处于锁定状态：被报告的始终是第一个 rejection，后续拒绝（包括拆卸自身产生的拒绝）会被忽略，而不会变成未捕获错误、在拆卸中途杀死进程。
+Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先 dispose 部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前 dispose 整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间，处理函数保持注册并处于锁定状态：被报告的始终是第一个 rejection，后续拒绝（包括拆卸自身产生的拒绝）会被忽略，而不会变成未捕获错误、在拆卸中途杀死进程。
 
 配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包）通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与宿主会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个随附的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
 
diff --git a/packages/host/directory-picker-native/README.i18n.yaml b/packages/host/directory-picker-native/README.i18n.yaml
index 9f2c323183..c2062933e5 100644
--- a/packages/host/directory-picker-native/README.i18n.yaml
+++ b/packages/host/directory-picker-native/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/host/directory-picker-native/README.md
 README.md: 4dd0c79d080fe097d063cfd2200e30aafc2d2d42
-README.zh.md: bbf6d361f48792a9f385a83032546f6d95fd3fc8
+README.zh.md: e7d0ec99c1aaca8f22f8d5dc29fcbddd73d9f7c0
diff --git a/packages/host/directory-picker-native/README.zh.md b/packages/host/directory-picker-native/README.zh.md
index bbf6d361f4..e7d0ec99c1 100644
--- a/packages/host/directory-picker-native/README.zh.md
+++ b/packages/host/directory-picker-native/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在派生的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
+[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
 
-**双面包**：浏览器端（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流 slot注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并通过 slot 的属主交互约定上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于有效状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；客户端不包含任何按能力类型进行的分支，挂载第二个流程包会在加载期失败（slot 的 kind 为 `single`）。
+**双面包**：浏览器端（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流 slot 注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并通过 slot 的属主交互约定上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于有效状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；客户端不包含任何按能力类型进行的分支，挂载第二个流程包会在加载期失败（slot 的 kind 为 `single`）。
 
 ## 模型体验
 
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 648b807368..bf71e04e3e 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
 README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 2f71649117f8f962cec9648a0cadd79f4e182c60
+README.zh.md: 7c1c3328ab8490c7eebd4b2492bc4ae6f4fcd5a5
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 2f71649117..7c1c3328ab 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -6,7 +6,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 
 四层可单独导入：
 
-- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动阶段报告异步派生失败，并默认拒绝未处理的权限请求，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才完成关闭或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
+- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动阶段报告异步 spawn 失败，默认拒绝未处理的权限请求，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才完成关闭或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
 - **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父会话和 subagent 子会话，主会话优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每种原生／JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已进行 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新模式写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件构成有序的主会话／子会话清单；场景表不重复其数量。必须在 vitest 收集时调用。
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 2385b3c24c..d3f00f3408 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -330,6 +330,7 @@ describe('docsPages locale routes', () => {
   })
 
   it('projects reviewed generated counterparts into root locale routes', () => {
+    // module-graph, event-producer-consumer, and graph-atlas are paired but intentionally unpublished.
     const routes = [
       'reference/capability-seams.md',
       'reference/agent-lifecycle.md',
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index d4aeea3fa1..161a52bbf9 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -40,11 +40,11 @@
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 87e31199a4..e80605c14b 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -320,6 +320,7 @@ export function requiresSourceLanguageSwitcher(source: string): boolean {
     'docs/cordis-api/context.md',
     'docs/cordis-api/events.md',
     'docs/cordis-api/fiber.md',
+    // Excluded from pairing, but kept here for generated-category completeness and direct spec coverage.
     'docs/cordis-api/inherited.md',
     'docs/cordis-api/registry.md',
     'docs/cordis-api/service.md',

From d5adb4b4a72d5f484e9a4b96bad9797d56af4171 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 13:51:10 +0800
Subject: [PATCH 205/262] fix(docs): sync generated catalog terminology

---
 docs/tool-catalog.i18n.yaml | 4 ++--
 docs/tool-catalog.zh.md     | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 9e530c0668..b0125b77fa 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: 8986847d1ed2fe9d64ada0c71f34700ff95fb364
-tool-catalog.zh.md: 831ed5d5cdcc15f32d2a4c8673858935fca1e435
+tool-catalog.md: e598429553ad9e6666e483b4bf8f49b0e8dc6c1c
+tool-catalog.zh.md: 81ea65f88979801cc1262e3c1cd0f527dee4b9ae
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 831ed5d5cd..81ea65f889 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -286,7 +286,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 ### `cordis_mount`
 
-在当前 DSH 进程中挂载临时 Cordis Plugin。它创建的是内存中的运行时 Plugin，而不是已安装或已配置的 Plugin。该插件会在后续轮次中保持活动，直到执行 cordis_unmount、工具集卸载或 DSH 重启。它不会创建文件、安装包、修改 cordis.yml 或个人／项目配置、在重启后保留，也不会自动转为永久插件。若要保留，请让 Agent 通过常规开发工作流实现普通的本地、项目或仓库 Plugin。它可能影响同一进程中的其他会话；沙箱不是安全边界，注入的服务会访问真实运行时。`code` 会立即作为异步 JavaScript 函数的函数体在隔离沙箱中运行，并且**必须** `return` 一个插件。支持两种形式：函数形式 `return (ctx) => { … }`，它不声明 inject，因此可以注册工具、监听事件和提供服务，但访问**任何**服务（例如 ctx.bash）都会抛出异常；仅在不需要服务时使用。对象形式 `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }`，它声明依赖，Cordis 只在服务存在后激活插件；**优先使用**这种形式。你只能访问 inject 中列出的服务：即使未声明的服务存在，访问它也会抛出异常，因为如果提供方被卸载，未声明的依赖将无法清理。代码调用服务**之前**，请读取 cordis_inspect 的 what:"api"；它会列出方法签名以及参数／返回值的类型形状，不要猜测字段类型，例如 bash 运行的 stdout 是对象而非字符串。在 `apply` 内，请使用标准 Cordis API：通过 `ctx.on(event, listener)` 观察事件（见 cordis_inspect 的 what:"events"），或调用 `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` 为自己提供新工具；该工具会在你的**下一步骤**可调用。工具参数：每个键**就是**一个属性，即 { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }；每个直接 DSL 对象都声明 additionalProperties: true|false，而 oneOf: [schema, schema, ...] 会取代 type，表示恰好匹配一个成员的联合。也接受原始 JSON Schema { type: 'object', properties, required?: […] } 包装层，其中对象默认开放。工具的 `execute` **必须**返回 `output.schema` 声明的无损 JSON 值；`output.render(args, value)` 单独返回 Native／模型内容块。临时 Plugin 可以**组合**：一个 Plugin 可以通过 `ctx.provide('name', value)` 提供服务，另一个则可声明 `inject: ['name']` 来消费它；消费方会在提供方出现前保持等待，提供方卸载后重新回到等待状态。在 `apply` 中注册的一切都会由 cordis_unmount 自动清理。沙箱全局对象：`console`（带 `[cordis:<id>]` 标签，写入 harness 终端）、`harness.defineTool`、`harness.registerTool`、`btoa`、`atob`、`TextEncoder`、`TextDecoder`。Node API 已**禁用**：文件系统／网络／定时工作必须通过 Cordis 服务完成，绝不能使用 Node 内置能力；`require`、`setTimeout`／`setInterval` 和 `fetch` 会抛出重定向错误，`process` 和 `Buffer` 未定义。应改用 inject: ['fs'] + ctx.fs 处理文件、inject: ['web'] + ctx.web 处理 HTTP、inject: ['bash'] + ctx.bash 处理进程、inject: ['timer'] + ctx.setTimeout/ctx.setInterval 处理定时（这些是 fiber effect，卸载时自动清理）；cordis_inspect 的 what:"api" 会展示**当前**运行时提供的能力。请编写**纯** JavaScript，不要使用 TypeScript（不得使用 `as` 或类型注解）。注意事项：(1) waterfall（瀑布式事件）事件（例如 tools/pre-execute）会向监听器传入最后一个 `next` 回调，该回调**必须**被调用；不调用 `next()` 就返回会**否决**此次调用。除非你有意拦截，否则请优先使用普通通知事件。(2) 切勿等待只能在当前轮次之后解析的内容；你的代码运行在该轮次的工具调用**内部**，否则会死锁。(3) 你的 `ctx` 是受限门面：可以注册工具、观察事件、提供／消费服务和使用定时器，但不会提供框架内部能力（ctx.root、ctx.fiber、ctx.extend、ctx.plugin 等）。不过，它并非安全边界：你注入的服务（例如 ctx.bash）会访问真实运行时。
+在当前 DSH 进程中挂载临时 Cordis Plugin。它创建的是内存中的运行时 Plugin，而不是已安装或已配置的 Plugin。该插件会在后续轮次中保持活动，直到执行 cordis_unmount、工具集卸载或 DSH 重启。它不会创建文件、安装包、修改 cordis.yml 或个人／项目配置、在重启后保留，也不会自动转为永久插件。若要保留，请让 Agent 通过常规开发工作流实现普通的本地、项目或仓库 Plugin。它可能影响同一进程中的其他会话；沙箱不是安全边界，注入的服务会访问真实运行时。`code` 会立即作为异步 JavaScript 函数的函数体在隔离沙箱中运行，并且**必须** `return` 一个插件。支持两种形式：函数形式 `return (ctx) => { … }`，它不声明 inject，因此可以注册工具、监听事件和提供服务，但访问**任何**服务（例如 ctx.bash）都会抛出异常；仅在不需要服务时使用。对象形式 `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }`，它声明依赖，Cordis 只在服务存在后激活插件；**优先使用**这种形式。你只能访问 inject 中列出的服务：即使未声明的服务存在，访问它也会抛出异常，因为如果提供方被卸载，未声明的依赖将无法清理。代码调用服务**之前**，请读取 cordis_inspect 的 what:"api"；它会列出方法签名以及参数／返回值的类型形状，不要猜测字段类型，例如 bash 运行的 stdout 是对象而非字符串。在 `apply` 内，请使用标准 Cordis API：通过 `ctx.on(event, listener)` 观察事件（见 cordis_inspect 的 what:"events"），或调用 `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` 为自己提供新工具；该工具会在你的**下一步骤**可调用。工具参数：每个键**就是**一个属性，即 { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }；每个直接 DSL 对象都声明 additionalProperties: true|false，而 oneOf: [schema, schema, ...] 会取代 type，表示恰好匹配一个成员的联合。也接受原始 JSON Schema { type: 'object', properties, required?: […] } 包装层，其中对象默认开放。工具的 `execute` **必须**返回 `output.schema` 声明的无损 JSON 值；`output.render(args, value)` 单独返回 Native／模型内容块。临时 Plugin 可以**组合**：一个 Plugin 可以通过 `ctx.provide('name', value)` 提供服务，另一个则可声明 `inject: ['name']` 来消费它；消费方会在提供方出现前保持等待，提供方卸载后重新回到等待状态。在 `apply` 中注册的一切都会由 cordis_unmount 自动清理。沙箱全局对象：`console`（带 `[cordis:<id>]` 标签，写入 harness 终端）、`harness.defineTool`、`harness.registerTool`、`btoa`、`atob`、`TextEncoder`、`TextDecoder`。Node API 已**禁用**：文件系统／网络／定时工作必须通过 Cordis 服务完成，绝不能使用 Node 内置能力；`require`、`setTimeout`／`setInterval` 和 `fetch` 会抛出重定向错误，`process` 和 `Buffer` 未定义。应改用 inject: ['fs'] + ctx.fs 处理文件、inject: ['web'] + ctx.web 处理 HTTP、inject: ['bash'] + ctx.bash 处理进程、inject: ['timer'] + ctx.setTimeout/ctx.setInterval 处理定时（这些是 fiber effect，卸载时自动清理）；cordis_inspect 的 what:"api" 会展示**当前**运行时提供的能力。请编写**纯** JavaScript，不要使用 TypeScript（不得使用 `as` 或类型注解）。注意事项：(1) waterfall（瀑布式事件）事件（例如 tools/pre-execute）会向监听器传入最后一个 `next` 回调，该回调**必须**被调用；不调用 `next()` 就返回会**短路**此次调用。除非你有意拦截，否则请优先使用普通通知事件。(2) 切勿等待只能在当前轮次之后解析的内容；你的代码运行在该轮次的工具调用**内部**，否则会死锁。(3) 你的 `ctx` 是受限门面：可以注册工具、观察事件、提供／消费服务和使用定时器，但不会提供框架内部能力（ctx.root、ctx.fiber、ctx.extend、ctx.plugin 等）。不过，它并非安全边界：你注入的服务（例如 ctx.bash）会访问真实运行时。
 
 ```json
 {

From 3b5ee1dce17545efb97e220f0598aaa5d740d48d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 13:57:50 +0800
Subject: [PATCH 206/262] fix(windows): address native CI review findings

---
 ...rial-cross-platform-ci-reference.i18n.yaml |  4 ++--
 ...7-21-serial-cross-platform-ci-reference.md |  2 +-
 ...1-serial-cross-platform-ci-reference.zh.md |  2 +-
 .github/workflows/ci.yml                      |  5 +++--
 apps/cli/src/profile-boot.ts                  | 11 +++++++---
 .../boot/app-boot/tests/hmr-config.spec.ts    |  6 +++--
 packages/util/paths/src/index.ts              | 22 ++++++++++++++-----
 scripts/ci-workflow.spec.ts                   |  1 +
 vendor/README.md                              |  2 +-
 vendor/hmr/src/index.ts                       |  7 +++---
 10 files changed, 41 insertions(+), 21 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index 5e8f015f50..33bffe92ff 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.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 .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
-2026-07-21-serial-cross-platform-ci-reference.md: dd41cdb51bd226b19bc6aca498c7713a3cc9a6b7
-2026-07-21-serial-cross-platform-ci-reference.zh.md: ec026df8164df0a2400200adbe81230920ce5daa
+2026-07-21-serial-cross-platform-ci-reference.md: 07dc430e6fed3fe75a006ca03523bd6e4fc969d0
+2026-07-21-serial-cross-platform-ci-reference.zh.md: 8bbb60cdead2957069de22ecaddf01c6cd9fb305
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index dd41cdb51b..07dc430e6f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -16,7 +16,7 @@ Real-kernel sandbox proofs require specific hosted operating systems and archite
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Wine-hosted Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity; an independent native Windows job reports the complete Windows inventory without participating in the required aggregate. A push to `master` skips those jobs and runs four explicit references: `serial / linux`, `serial / macos`, and `serial / windows` on standard hosted runners, plus `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
+[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Wine-hosted Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity; an independent native Windows job reports the complete Windows inventory without participating in the required aggregate. On a push to `master`, the active reference is `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). The standard-hosted `serial / linux`, `serial / macos`, and `serial / windows` definitions remain disabled under `TODO(hosted-serial-ci)` until their portable capacity can be restored. The separate job definitions intentionally keep their short checkout, runtime setup, and immutable install sequences visible instead of hiding operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
 
 Each reference job runs `pnpm run check:ci` without any shard selector. `DSH_GATE_CONCURRENCY=1` makes the top-level aggregate execute one ready gate at a time; coverage, snapshot replay, built-bin smoke, and publication validation also receive worker counts of one. The reference jobs may run beside one another, but each host's repository gates are serial and complete. Linux installs bubblewrap before replaying snapshots, and Windows enables Developer Mode before installing the symlinked workspace.
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index ec026df816..8bbb60cdea 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和由 Wine 承载的 Windows 作业，以及 Node 兼容性与 Python 约定；一个独立的原生 Windows 作业会报告完整的 Windows 清单，但不参与必需聚合流程。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和由 Wine 承载的 Windows 作业，以及 Node 兼容性与 Python 约定；一个独立的原生 Windows 作业会报告完整的 Windows 清单，但不参与必需聚合流程。向 `master` 推送时，当前启用的参考作业是公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——该热备演练持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。标准托管的 `serial / linux`、`serial / macos` 和 `serial / windows` 定义仍处于禁用状态，并由 `TODO(hosted-serial-ci)` 标记，直到其可移植容量恢复。各自独立的作业定义有意显式保留简短的代码检出、运行时设置和依赖锁定的安装步骤，而不是用矩阵或可复用工作流隐藏操作系统差异。`workflow_dispatch` 仅用于运行器基准测试。
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d3e2239fdd..264cbd9f6c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -431,6 +431,7 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: windows-2025
     name: windows node 24 / native complete
+    timeout-minutes: 60
     env:
       DSH_GATE_CONCURRENCY: '1'
       DSH_PUBLINT_CONCURRENCY: '1'
@@ -721,8 +722,8 @@ jobs:
         with:
           dest: ${{ runner.temp }}/setup-pnpm
 
-      # The Windows lanes deliberately skip the store cache like the required
-      # windows job; an empty cache input disables setup-node's caching.
+      # The benchmark's Windows lanes deliberately skip the store cache like
+      # the independent native Windows job; an empty input disables caching.
       - uses: actions/setup-node@v6
         with:
           node-version: ${{ env.PRIMARY_NODE_VERSION }}
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index b49bd37535..b4fee306cf 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -168,6 +168,7 @@ export interface RunProfileOptions {
   environment: EnvironmentSnapshot
 }
 
+/** Re-throw setup failures unless this invocation's signal already owns shutdown. */
 function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void {
   if (!signal.aborted) throw error
 }
@@ -253,9 +254,13 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
   })
   app.current = ctx
   // A surface can dispose the whole tree while startup or this post-boot
-  // watcher setup is still in flight. Fiber state owns liveness; the local
-  // signal fact distinguishes that expected exit race from a real HMR error.
-  if (watchProfilePatch && !signalShutdown.signal.aborted && ctx.fiber.state === FiberState.ACTIVE) {
+  // watcher setup is still in flight. Loader presence and fiber state own
+  // liveness; the local signal fact distinguishes that expected exit race
+  // from a real HMR error.
+  if (watchProfilePatch
+    && !signalShutdown.signal.aborted
+    && ctx.fiber.state === FiberState.ACTIVE
+    && ctx.get('loader') !== undefined) {
     try {
       // Config-only HMR for the live profile patch layer: the web bundle
       // disables the shared module-reload `hmr` row (its reload lifecycle is
diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index fe6bb556b4..ba14e6967f 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import Hmr from '@cordisjs/plugin-hmr'
 import Loader from '@cordisjs/plugin-loader'
 import Timer from '@cordisjs/plugin-timer'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 async function bootHmr(dir: string, root: string[] = []): Promise<Context> {
   const ctx = new Context()
@@ -33,7 +33,8 @@ describe('HMR exact config paths', () => {
     symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
     writeFileSync(filename, 'export const generation = 0\n')
     const ctx = await bootHmr(alias, ['.'])
-    const expected = pathToFileURL(filename).href
+    const expected = pathToFileURL(join(realpathSync(target), 'module.ts')).href
+    const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)
     const observed: string[] = []
     ctx.on('hmr/change', (url) => { observed.push(url) })
     try {
@@ -43,6 +44,7 @@ describe('HMR exact config paths', () => {
         writeFileSync(filename, `export const generation = ${generation}\n`)
         await new Promise(resolve => setTimeout(resolve, 20))
       }
+      expect(cacheHas).toHaveBeenCalledWith(expected)
     } finally {
       await ctx.fiber.dispose()
       rmSync(alias, { force: true })
diff --git a/packages/util/paths/src/index.ts b/packages/util/paths/src/index.ts
index 591158d7c0..122408509a 100644
--- a/packages/util/paths/src/index.ts
+++ b/packages/util/paths/src/index.ts
@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-paths
  */
 
-import { realpath } from 'node:fs/promises'
+import { opendir, realpath } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 
@@ -20,19 +20,29 @@ export const DSH_HOME_ENV = 'DSH_HOME'
 /**
  * Give a native filesystem watcher one canonical spelling of a path, even
  * when its final components do not exist yet. The deepest existing ancestor
- * is resolved through {@link realpath}; the missing suffix is then restored.
- * This prevents Windows short-name aliases from being mixed with long paths
- * emitted by the native watcher backend.
+ * is resolved through {@link realpath}; when a suffix is missing, that
+ * ancestor is also proved to be an enumerable directory before the suffix is
+ * restored. This prevents Windows from treating a regular-file ancestor as
+ * ordinary absence, and prevents short-name aliases from being mixed with
+ * long paths emitted by the native watcher backend.
  * @param path - Watch target or root, resolved against the current directory.
  * @returns the target with its existing ancestor canonicalized.
- * @throws when ancestor traversal encounters an error other than absence.
+ * @throws when ancestor traversal encounters an error other than absence, or
+ * the existing ancestor of a missing suffix is not an enumerable directory.
  */
 export async function canonicalizeWatchPath(path: string): Promise<string> {
   let current = resolve(path)
   const missing: string[] = []
   while (true) {
     try {
-      return join(await realpath(current), ...missing.reverse())
+      const canonical = await realpath(current)
+      if (missing.length > 0) {
+        // A Windows file-as-parent probe reports ENOENT. Opening the resolved
+        // ancestor preserves the cross-platform directory requirement.
+        const directory = await opendir(canonical)
+        await directory.close()
+      }
+      return join(canonical, ...missing.reverse())
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
       const parent = dirname(current)
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 05edaaef55..128988a464 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -53,6 +53,7 @@ describe('CI workflow', () => {
     expect(workflow.jobs).toHaveProperty('wine-apt-cache')
     expect(windowsNative['runs-on']).toBe('windows-2025')
     expect(windowsNative.name).toBe('windows node 24 / native complete')
+    expect(windowsNative['timeout-minutes']).toBe(60)
     expect(windowsNative.if).toBe("github.event_name == 'pull_request'")
     expect(windowsNative).not.toHaveProperty('continue-on-error')
     expect(nativeCommandSteps).toHaveLength(3)
diff --git a/vendor/README.md b/vendor/README.md
index 0e44771616..a5e998ef39 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -38,7 +38,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory and use that spelling for Node module-cache identity; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while exact-config callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
 10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. The temporary command directory is removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and obtains both its build and prepare commands from declared dependencies.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
diff --git a/vendor/hmr/src/index.ts b/vendor/hmr/src/index.ts
index c1d379e36c..7c36201b13 100644
--- a/vendor/hmr/src/index.ts
+++ b/vendor/hmr/src/index.ts
@@ -242,12 +242,13 @@ class Hmr extends Service {
 
     const onChange = (kind: 'add' | 'change' | 'unlink', path: string) => {
       this.ctx.logger.debug('%s detected at %C', kind, path)
-      const filename = resolve(this.baseDir, path)
+      const filename = resolve(watchBaseDir, path)
+      const configuredFilename = resolve(this.baseDir, path)
       // Config reload: the file is a loader config file (e.g. cordis.yml).
       for (const entry of loader.entries()) {
         const include = entry.subtree as Include | undefined
-        if (include?.filename !== filename) continue
-        this.refreshConfig(include, filename, () => include.refresh())
+        if (include?.filename !== filename && include?.filename !== configuredFilename) continue
+        this.refreshConfig(include, include.filename, () => include.refresh())
         return
       }
 

From c12bcc6f4b1828e5c2e91abd11cdcc285638e9ae Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 14:33:57 +0800
Subject: [PATCH 207/262] fix(docs): close remaining typography review gaps

---
 .../2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml      | 2 +-
 .../2026-07-19-gui-layering-and-rpc-protocol.zh.md          | 6 +++---
 .../2026-08-04-composer-tab-gutter-reservation.i18n.yaml    | 2 +-
 .../2026-08-04-composer-tab-gutter-reservation.zh.md        | 2 +-
 .../2026-07-31-gui-full-access-confirmation.i18n.yaml       | 2 +-
 .../feature/2026-07-31-gui-full-access-confirmation.zh.md   | 2 +-
 .../feature/2026-07-31-session-archive-global-set.i18n.yaml | 2 +-
 .../feature/2026-07-31-session-archive-global-set.zh.md     | 2 +-
 .../feature/2026-08-03-fs-tool-error-remedy.i18n.yaml       | 2 +-
 .../feature/2026-08-03-fs-tool-error-remedy.zh.md           | 2 +-
 .../process/2026-07-20-gui-testing-system.i18n.yaml         | 2 +-
 .../implemented/process/2026-07-20-gui-testing-system.zh.md | 2 +-
 .../2026-08-06-doc-site-carries-its-images.i18n.yaml        | 2 +-
 .../process/2026-08-06-doc-site-carries-its-images.zh.md    | 2 +-
 .../process/2026-08-08-browser-gif-evidence-chain.i18n.yaml | 2 +-
 .../process/2026-08-08-browser-gif-evidence-chain.zh.md     | 2 +-
 16 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 4578e9e268..cb882f6bc5 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 49ebd642264c663377f16b8669fedc112d3bb6c7
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 5c7ee5a407216807e84bd2e62f604dc9c24b6ec9
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 49ebd64226..5c7ee5a407 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -8,8 +8,8 @@ Status: implemented
 
 ## Problem
 
-需要提供 UI 对接层，除已有 ACP/stdio基础版本外，还需要 Web(server) 、 Electron 、等其他产品 UI 形态。我们把这些形态统一称为 Client。希望有如下能力支持:
-- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh run`(headless) ，一个进程两种模式（设计预留）
+需要提供 UI 对接层，除已有 ACP（Agent Client Protocol）/stdio 基线外，还需要 Web（server）、Electron 等其他产品 UI 形态。我们把这些形态统一称为 Client。希望具备以下能力：
+- 一个 `dsh` 进程同时支持 `dsh web`（启动）和 `dsh run`（headless），一个进程两种模式（设计预留）
 - 以与 `dsh web` 同构的 Web 技术形态，在 Electron 中启动
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
@@ -20,7 +20,7 @@ Status: implemented
 
 ### 分层
 
-目录按照如下分层:
+目录按照如下分层：
 - `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
 - `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）：
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
index 3b41a39be5..8a9b6236ae 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md
 2026-08-04-composer-tab-gutter-reservation.md: 3b28c35c1f11676e41cabde76d1b0d16c688f034
-2026-08-04-composer-tab-gutter-reservation.zh.md: 8724195a53a846d0fb09fb1182f94a40214c23d8
+2026-08-04-composer-tab-gutter-reservation.zh.md: c357dd06c52a834c18d2e8a25246d4ad003db548
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
index 8724195a53..c357dd06c5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
@@ -36,7 +36,7 @@ overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图
 
 ## 后果
 
-- Chat 的内容列永久变窄 8px——hero 态与transcript 尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
+- Chat 的内容列永久变窄 8px——hero 态与 transcript 尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
 - 一条声明覆盖三种切换，因为这三者本就是同一个差异：Chat ↔ Trajectory、Chat 内部 transcript 较短 ↔ transcript 可滚动，以及 hero ↔ 第一个可滚动轮次。
 - overlay 状态现在是一个滚动容器。今天其中没有任何内容会溢出；将来若有视图允许自身内容超出会话列，这个盒子会滚动而不是裁剪，那个视图就需要像 Trajectory 视图那样自带裁剪。
 - 提交的 golden 记录了预留条带，因此样式表中 `::-webkit-scrollbar` 宽度的变化——决定这条预留有多宽的那个值——会在本场景中与在侧边栏场景中一样，以可评审的 diff 形式出现。
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
index fa5ea6f634..ef08e0829b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.md
 2026-07-31-gui-full-access-confirmation.md: ca89ed23fb1b5c6ea438dd22fdf20d2b82af754c
-2026-07-31-gui-full-access-confirmation.zh.md: a31c1ee744b111dd6917f0d2ed7ba9988c2aee47
+2026-07-31-gui-full-access-confirmation.zh.md: b4ab92271f6b4a6ebe3b7e7c3f82f859c53933bf
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
index a31c1ee744..b4ab92271f 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
@@ -13,7 +13,7 @@ Status: implemented
 **每个权限选择器都把 `danger-full-access` 关进共享的页面内 `RiskConfirmation` 对话框：启用按钮在用户勾选明确的风险确认复选框前保持禁用；预设以产品标签 `Full access` 展示；所有取消路径都不作任何提交。**
 
 - `RiskConfirmation`（ui-primitives）是受控的 Modal 组合：标题、说明、确认复选框、取消，以及 `acknowledged` 勾选前禁用的确认按钮。它始终是页面内对话框——Modal portal 到本文档 body，绝不打开可能落在另一块显示器上的原生或独立浏览器窗口。`Modal` 新增 `contentClassName` slot，令警示正文在受限的移动端／横屏视口内滚动，动作行保持固定。
-- composer chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale slot以 `access.confirm.*` 键供给。
+- composer chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale slot 以 `access.confirm.*` 键供给。
 - `/permission` popup（ui-permission 构建于 ui-command 外壳之上）以数据而非第二套对话框实现完成把关：`SelectOption` 新增可选的 `confirmation` 载荷，popup 控制器拥有 `confirming`/`acknowledged` 状态迁移，`PopupSelectView` 在门控选项未决期间把选择卡换成同一个 `RiskConfirmation`。
 - 「通用」设置中的「权限」行在把 Full access 持久化为后续会话的默认值前，也使用同一个受控 `RiskConfirmation`。警示会明确说明该设置只影响后续会话；取消、Escape、关闭与点击遮罩均不会改动已存默认值。
 - `Full access` 在每个选择器中都有意覆盖 kebab 转 Title Case 的显示变换；命令与 Settings 写入在 wire 上保留机器名，每份警示正文都保持中英文 locale 感知。
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
index 5565ea70b1..22cc5fb3ea 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-session-archive-global-set.md
 2026-07-31-session-archive-global-set.md: fab99a405a6f8264c36453473327e32905bac9c8
-2026-07-31-session-archive-global-set.zh.md: b10440039f1c6a8ea2f89d9239a0285dd70cf9a2
+2026-07-31-session-archive-global-set.zh.md: 4789c11a6d6883966b2218a16644177408e3df1f
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
index b10440039f..4789c11a6d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
@@ -30,4 +30,4 @@ Sidebar workspace 浏览区的会话行菜单里，「Delete session」一直是
 
 ## 后果
 
-归档后 UI 无查看/取消归档入口（本期口径，记录在 README 的 Known Limitation 中）；数据与slot完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
+归档后 UI 无查看/取消归档入口（本期口径，记录在 README 的 Known Limitation 中）；数据与 slot 完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index f0dba56167..d9d9142437 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
 2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
-2026-08-03-fs-tool-error-remedy.zh.md: ed3cbcf9c262db44321036fc1afcc829a5696b2f
+2026-08-03-fs-tool-error-remedy.zh.md: 6bb0d0b6ffcda282db67dd1a54f0074b3be5c6e1
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
index ed3cbcf9c2..6bb0d0b6ff 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -17,7 +17,7 @@ Status: implemented
 
 结构化 `FsError` 错误码保持不变，使重试/权限/UI 层继续基于它路由；原始错误作为 `cause` 链入。提供方消息保持面向机器且不变。
 
-在 `edit.ts` 中，`fs/edit-intent` waterfall（瀑布式事件）现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent slot抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
+在 `edit.ts` 中，`fs/edit-intent` waterfall（瀑布式事件）现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent slot 抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
index bafe5adfdf..ddfa339fdd 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
 2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39
-2026-07-20-gui-testing-system.zh.md: bd617f39a7cd5fd49e5c3a8a992b7dff35a800bf
+2026-07-20-gui-testing-system.zh.md: a0e819fd5269da6aa3379309c76eea006975cef8
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
index bd617f39a7..a0e819fd52 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -18,7 +18,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 | 层 | 被测物 | 关键手段 | 文件落点 |
 |---|---|---|---|
-| 1 协议同构层 | `AbstractApiClient` + `toFetchHandler`（双向数据/rpcId/ZOD类型/SSE 流/合批/超时） | **同构点全链**：`InProcessApiClient(toFetchHandler(脚本化 impl))` 不过网络但真跑 wire 序列化——零浏览器、纯 node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
+| 1 协议同构层 | `AbstractApiClient` + `toFetchHandler`（双向数据/rpcId/ZOD 类型/SSE 流/合批/超时） | **同构点全链**：`InProcessApiClient(toFetchHandler(脚本化 impl))` 不过网络但真跑 wire 序列化——零浏览器、纯 node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
 | 2 对象层编排 | `Session`/`SessionManager`/`ConnectionController`（状态机与时序：缝合/去重/翻页/乐观清稿/pendingBuffers/重连/退避） | **「事件序列进→快照出」黄金路径**：可编程假体 + deferred 控时序 + fake timers 控退避 | `packages/client/{runtime,connection}/tests/` |
 | 3 组装呈现层 | 构建产物 × 真实 client loader 与插件组合 | 归应用所有的语义快照会在 jsdom 下启动全部 8 个已构建的 client 插件，以固定确定性的跨插件状态变化；独立使用 Playwright 裸库的冒烟测试负责验证真实浏览器/承载层边界，真 host 用例在无密钥时自行跳过；无密钥浏览器 e2e 车道会禁用交付配置中的模型适配器行，并通过 `dsh-llm-replay` 在真实进程内 web 组装中回放录制的会话 fixture，与会话区 aria 期望输出比对（[web e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)、[必需 CI 门禁](../testing/2026-07-30-web-browser-snapshot-ci-gate.md)） | `apps/web/tests/*.snapshot.ts`、`apps/web/tests/smoke-{fixture,real}.e2e.ts`、`apps/web/tests/{replay-round-trip,seeded-history}.e2e.ts` |
 
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
index 15045d2590..c3bf152222 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
 2026-08-06-doc-site-carries-its-images.md: 4078a9b6251cf67456590ae25602a9f288c88dc1
-2026-08-06-doc-site-carries-its-images.zh.md: 134bd20e628322dc9c6d95cb261648618fbdf7a7
+2026-08-06-doc-site-carries-its-images.zh.md: 4ab90f9736dae95090b0d805f6fbe5d4846c7a0c
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
index 134bd20e62..4ab90f9736 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张manifest 未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
+`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张 manifest 未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
 
 副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；manifest 撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index bd7ec32f75..822265cb31 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
 2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
-2026-08-08-browser-gif-evidence-chain.zh.md: 7b21abb23b5cb3a7b5dd8fd2accc561974008ad9
+2026-08-08-browser-gif-evidence-chain.zh.md: afb45b4771766c4ab6e44b0f4f91f01f3827668d
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index 7b21abb23b..afb45b4771 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求worktree 干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器上下文时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求 worktree 干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器上下文时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 

From 3754c0d58615899d0040d12050b35526323e9b16 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 14:35:46 +0800
Subject: [PATCH 208/262] test(windows): let HMR atomic changes settle

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index ba14e6967f..033ad1661a 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -42,7 +42,8 @@ describe('HMR exact config paths', () => {
       for (let generation = 1; !observed.includes(expected); generation += 1) {
         if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
         writeFileSync(filename, `export const generation = ${generation}\n`)
-        await new Promise(resolve => setTimeout(resolve, 20))
+        // Leave Chokidar's atomic-write window idle so one coalesced change can publish.
+        await new Promise(resolve => setTimeout(resolve, 250))
       }
       expect(cacheHas).toHaveBeenCalledWith(expected)
     } finally {

From 7016ad93deb203e28cc306f8e88e98bdd69215ff Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 14:55:06 +0800
Subject: [PATCH 209/262] refactor: make lint workflows Oxlint-only

---
 .../2026-06-11-quality-gates.i18n.yaml        |   4 +-
 .../process/2026-06-11-quality-gates.md       |   2 +-
 .../process/2026-06-11-quality-gates.zh.md    |   2 +-
 .../2026-07-22-fast-local-git-hooks.i18n.yaml |   4 +-
 .../2026-07-22-fast-local-git-hooks.md        |   6 +-
 .../2026-07-22-fast-local-git-hooks.zh.md     |   6 +-
 .../2026-07-29-oxlint-linter.i18n.yaml        |   4 +-
 .../process/2026-07-29-oxlint-linter.md       |  14 +-
 .../process/2026-07-29-oxlint-linter.zh.md    |  14 +-
 ...6-08-09-oxlint-only-fix-workflow.i18n.yaml |   6 +
 .../2026-08-09-oxlint-only-fix-workflow.md    |  37 ++++
 .../2026-08-09-oxlint-only-fix-workflow.zh.md |  37 ++++
 .oxlintrc.json                                |  18 ++
 .oxlintrc.staged.json                         |  17 +-
 THIRD_PARTY_NOTICES.md                        |   2 -
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 eslint.format.config.mjs                      |  59 ------
 lefthook.yml                                  |   7 -
 package.json                                  |   4 +-
 pnpm-lock.yaml                                | 105 -----------
 scripts/oxlint-contract.spec.ts               | 172 +++++++++++++-----
 scripts/run-oxlint.ts                         |  48 ++++-
 24 files changed, 323 insertions(+), 253 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md
 delete mode 100644 eslint.format.config.mjs

diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml b/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml
index e8cdb21a40..3134a16824 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.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 .agents/notes/implemented/process/2026-06-11-quality-gates.md
-2026-06-11-quality-gates.md: 60db7ba5cfa8184c0fcce764aa027f32a9b721ab
-2026-06-11-quality-gates.zh.md: 10585977820ba8e4f4bc6e251d484dc657d0558c
+2026-06-11-quality-gates.md: 83cba5c867f71471d421ab935e1f53b430b01c43
+2026-06-11-quality-gates.zh.md: 1162b3836424bd47a8d35bd754a7983ac2e9bebe
diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.md b/.agents/notes/implemented/process/2026-06-11-quality-gates.md
index 60db7ba5cf..83cba5c867 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.md
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.md
@@ -19,7 +19,7 @@ Every mechanically checkable AGENTS.md promise gets a command that exits non-zer
 - jscpd detects cross-file clones in package production TypeScript and repository scripts; narrow source-range exceptions document deliberately parallel implementations.
 - Per-file 100% coverage on `packages/*/*/src` (v8); unreachable defensive guards carry `/* v8 ignore */ ` with stated reasons instead of deletion.
 - knip (dead code/deps), publint (package correctness), workspace constraints (workspace rules: private, cordis peer+dev, uniform version, ESM), and a NodeNext consumer typecheck for built package declarations.
-- lefthook pre-commit applies formatting-only ESLint fixes before Oxlint validation and native fixes, rejects staged whitespace, and checks the vendor manifest; pre-push runs incremental typecheck. CI runs the full matrix on node 22.19/24/26 plus built application smokes for the Headless, TUI, ACP, JSON-RPC, workflow, and code-runtime entry paths.
+- lefthook pre-commit applies project-free Oxlint validation and [safe fixes with a bounded retry](2026-08-09-oxlint-only-fix-workflow.md), rejects staged whitespace, and checks the vendor manifest; pre-push runs incremental typecheck. CI runs the full matrix on node 22.19/24/26 plus built application smokes for the Headless, TUI, ACP, JSON-RPC, workflow, and code-runtime entry paths.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md b/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
index 1058597782..1162b38364 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - jscpd 检测包的生产 TypeScript 代码与仓库脚本中的跨文件克隆；窄范围的源码区间例外用于记录有意为之的并行实现。
 - `packages/*/*/src` 下按文件 100% 覆盖率（v8）；不可达的防御性守卫使用 `/* v8 ignore */ ` 并注明理由，而非删除。
 - knip（死代码/依赖）、publint（包的正确性）、workspace 约束（workspace 规则：private、cordis peer+dev、统一版本、ESM），以及对构建出的包声明文件进行 NodeNext 消费方类型检查。
-- lefthook pre-commit 先应用仅用于格式化的 ESLint 修复，再执行 Oxlint 验证和原生修复，拒绝已暂存的空白问题并检查 vendor manifest（元数据清单）；pre-push 运行增量类型检查。CI 在 Node 22.19/24/26 上运行完整矩阵，并对 Headless、TUI、ACP（Agent Client Protocol）、JSON-RPC、工作流和代码运行时入口路径执行已构建应用的冒烟测试。
+- lefthook pre-commit 执行不加载项目的 Oxlint 验证，并应用带[一次有界重试](2026-08-09-oxlint-only-fix-workflow.md)的安全修复，拒绝已暂存的空白问题并检查 vendor manifest（元数据清单）；pre-push 运行增量类型检查。CI 在 Node 22.19/24/26 上运行完整矩阵，并对 Headless、TUI、ACP（Agent Client Protocol）、JSON-RPC、工作流和代码运行时入口路径执行已构建应用的冒烟测试。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
index 0121a65219..701e850d7f 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.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 .agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
-2026-07-22-fast-local-git-hooks.md: af8a9380fc3cbf4f672ca0b32faa7b187522cf11
-2026-07-22-fast-local-git-hooks.zh.md: 1b2c3bf42a65f35d96c266f5f3afb63f26039388
+2026-07-22-fast-local-git-hooks.md: c3d3579b2e91419fad64f0e64a10926d2362881e
+2026-07-22-fast-local-git-hooks.zh.md: f85daa9c74a23987cc560f14c5e087fdfb3d7f5e
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
index af8a9380fc..c3d3579b2e 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
@@ -12,7 +12,7 @@ Fast hooks still need to reject cheap, high-confidence defects before work leave
 
 ## Decision
 
-[lefthook.yml](../../../../lefthook.yml) keeps both hooks as bounded local checkpoints. Pre-commit runs sequentially: a formatting-only ESLint config fixes and re-stages changed JavaScript and TypeScript, a project-free [Oxlint](2026-07-29-oxlint-linter.md) profile validates those files and applies native safe fixes, `git diff --cached --check` rejects staged whitespace errors, and the vendor manifest guard checks vendored-source metadata. Pre-push runs `pnpm run typecheck`, which prepares the generated Host TypeRT contracts before the Client incremental typecheck.
+[lefthook.yml](../../../../lefthook.yml) keeps both hooks as bounded local checkpoints. Pre-commit runs sequentially: a project-free [Oxlint](2026-07-29-oxlint-linter.md) profile validates changed JavaScript and TypeScript, applies safe fixes with a [bounded retry](2026-08-09-oxlint-only-fix-workflow.md), and re-stages them; `git diff --cached --check` rejects staged whitespace errors, and the vendor manifest guard checks vendored-source metadata. Pre-push runs `pnpm run typecheck`, which prepares the generated Host TypeRT contracts before the Client incremental typecheck.
 
 Pre-commit does not run type analysis, tests, snapshots, documentation checks, builds, hygiene, or the gate scheduler. Pre-push adds only the Host contract build required by repository typecheck. The opt-in `check:all` package script selects the `check-all` scheduler inventory in [scripts/run-gates.ts](../../../../scripts/run-gates.ts) independently of the hooks; it is a contributor command, not an agent instruction.
 
@@ -27,10 +27,10 @@ This decision supersedes the local-hook portion of [Parallel pre-push gates](202
 - **Keep the full pre-push suite and optimize its scheduler** — preserves the earliest exhaustive signal but still repeats agent-selected evidence and CI, while unrelated failures continue blocking publication.
 - **Remove pre-push entirely** — makes pushes cheapest but loses the fast cross-file guarantee that TypeScript provides after several commits.
 - **Keep typecheck in pre-commit** — catches type errors earlier but charges every intermediate commit instead of one push; staged lint already covers the commit-local syntax and style boundary.
-- **Make staged lint check-only** — avoids hook-side mutation, but contributors intentionally retain the auto-fix workflow; the formatting-only pass and Lefthook's `stage_fixed` preserve it without making ESLint a repository correctness runner or duplicating `git add`.
+- **Make staged lint check-only** — avoids hook-side mutation, but contributors intentionally retain the auto-fix workflow; Oxlint's bounded retry and Lefthook's `stage_fixed` preserve it without a separate formatter or duplicate `git add`.
 
 ## Consequences
 
-Normal commits take the project-free staged formatter-and-lint critical path, and warm pushes take the prepared incremental typecheck critical path. Contributors retain a one-command opt-in rehearsal without widening the hook critical paths or the agent-required validation set. Hook latency is observed in development and PR evidence rather than enforced by a timing test whose result would depend on host load and cache state.
+Normal commits take the project-free staged Oxlint fix-and-validate critical path, and warm pushes take the prepared incremental typecheck critical path. Contributors retain a one-command opt-in rehearsal without widening the hook critical paths or the agent-required validation set. Hook latency is observed in development and PR evidence rather than enforced by a timing test whose result would depend on host load and cache state.
 
 Local publication no longer proves the exhaustive repository matrix. Agents must select relevant behavioral evidence, reviewers must evaluate whether that selection matches the diff, and CI supplies the comprehensive signal once per pushed revision.
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
index 1b2c3bf42a..f85daa9c74 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
@@ -12,7 +12,7 @@ agent（智能体）已经会运行能够覆盖自身改动的测试和检查，
 
 ## 决策
 
-[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 约定，再运行 Client 增量类型检查。
+[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证改动过的 JavaScript 和 TypeScript 文件，应用带[一次有界重试](2026-08-09-oxlint-only-fix-workflow.md)的安全修复，并重新暂存这些文件；`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 约定，再运行 Client 增量类型检查。
 
 Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 约定构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
 
@@ -27,10 +27,10 @@ agent 检查待推送的 diff，并仅运行一次能够覆盖其行为的最小
 - **保留全量 pre-push 套件并优化其调度器**——能够最早提供全面信号，但仍会重复 agent 已选取的证据和 CI，且无关失败仍会阻塞推送。
 - **完全移除 pre-push**——推送成本最低，但会失去 TypeScript 在多个提交之后提供的快速跨文件保证。
 - **在 pre-commit 中保留类型检查**——更早捕获类型错误，但每次中间提交都要承担开销，而不是只在推送时运行一次；暂存文件 lint 已经覆盖提交本身的语法与风格边界。
-- **将暂存文件 lint 设为仅检查模式**——避免钩子修改文件，但贡献者有意保留自动修复工作流；仅用于格式化的流程和 Lefthook 的 `stage_fixed` 会保留该工作流，而不会让 ESLint 成为仓库正确性检查运行器，也无需重复执行 `git add`。
+- **将暂存文件 lint 设为仅检查模式**——避免钩子修改文件，但贡献者有意保留自动修复工作流；Oxlint 的一次有界重试和 Lefthook 的 `stage_fixed` 会保留该工作流，无需单独的格式化器，也无需重复执行 `git add`。
 
 ## 结果
 
-普通提交的关键路径是不加载项目的暂存文件格式化与 lint，缓存已预热时推送的关键路径是经过准备的增量类型检查。贡献者仍可选择用一条命令完整演练，且不会扩展钩子关键路径或 agent 必须运行的验证集合。钩子耗时只作为开发观察数据和 PR（Pull Request）证据记录，不设置会受主机负载与缓存状态影响的计时测试。
+普通提交的关键路径是不加载项目的暂存文件 Oxlint 修复与验证，缓存已预热时推送的关键路径是经过准备的增量类型检查。贡献者仍可选择用一条命令完整演练，且不会扩展钩子关键路径或 agent 必须运行的验证集合。钩子耗时只作为开发观察数据和 PR（Pull Request）证据记录，不设置会受主机负载与缓存状态影响的计时测试。
 
 从本地推送成功不再能证明仓库完整矩阵已通过。agent 必须选择相关的行为证据，评审人必须判断该选择是否与 diff 相符，CI 则对每个推送版本提供一次全面信号。
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
index 9115979c19..851b2a3674 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.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 .agents/notes/implemented/process/2026-07-29-oxlint-linter.md
-2026-07-29-oxlint-linter.md: 3e3de24be33b8f9461cea2967b0fa18f59ddb52a
-2026-07-29-oxlint-linter.zh.md: dae8c7451bd3fbe9296508491aaa51f1118abe92
+2026-07-29-oxlint-linter.md: 15bdd4302745fdf3d1a2bd0d28fbc3d4b9fc50bb
+2026-07-29-oxlint-linter.zh.md: 8e3d69cdce2cc05346149acbd49f9b0b75ac6098
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
index 3e3de24be3..15bdd43027 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
@@ -12,25 +12,25 @@ A faster runner cannot justify losing rules. The migration must preserve the str
 
 ## Decision
 
-The root [`.oxlintrc.json`](../../../../.oxlintrc.json) is the authoritative type-aware repository lint configuration. The project-free [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) profile inherits its source rules but disables type analysis for the bounded pre-commit path. The `lint` package script, gate scheduler, CI, and lefthook invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts); `lint:fix` and lefthook first invoke the formatting-only [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs). The direct `eslint` and `@typescript-eslint/parser` development dependencies exist only for this parser-without-project formatting pass; their exact versions pin the tested parser/fixer pairing, and that config contains no correctness or type-aware rules.
+The root [`.oxlintrc.json`](../../../../.oxlintrc.json) is the authoritative type-aware repository lint configuration. The project-free [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) profile inherits its source rules, disables type analysis for the bounded pre-commit path, and re-includes preserved TypeGraph fixtures that the type-aware backend cannot analyze. The `lint` and `lint:fix` package scripts, gate scheduler, CI, and lefthook invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts); the [Oxlint-only fix workflow](2026-08-09-oxlint-only-fix-workflow.md) owns multipass plugin fixes and supersedes the separate formatting fallback.
 
 `options.typeAware` enables `oxlint-tsgolint`. Its backend performs per-file TypeScript-project discovery: package sources use their package projects, host tests/examples/website use `tsconfig.host.json`, and client tests plus `scripts/client-bundle-purity.spec.ts` use `tsconfig.client.json`. The program-less root solution is never flattened. Oxlint's `--tsconfig` override affects import resolution but is ignored by type-aware linting, so this repository does not set it. The configuration explicitly carries the migrated strict-type-checked rules and repository overrides instead of enabling broad Oxlint categories whose contents may change. `typescript/no-unnecessary-condition` remains enabled from Oxlint's nursery set because it was an enforced repository rule before migration.
 
-Oxlint's JavaScript-plugin compatibility layer runs `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` so the existing formatting and file-local duplicate-logic rules remain enforced. The compatibility layer reports `@stylistic` violations but does not execute their fixers, so the formatting-only ESLint pass owns only the corresponding auto-fixes; an executable parity check keeps those fixable rule definitions aligned while `max-len` remains validation-only. Owned-source suppressions use `oxlint-*` directives and the `typescript/*` namespace, and unused directives remain warnings; vendored sources keep their upstream directives because Oxlint excludes `vendor/**`.
+Oxlint's JavaScript-plugin compatibility layer runs `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` so the existing formatting and file-local duplicate-logic rules remain enforced. The compatibility layer reports `@stylistic` violations and executes their safe fixes; `max-len` remains validation-only. Owned-source suppressions use `oxlint-*` directives and the `typescript/*` namespace, and unused directives remain warnings; vendored sources keep their upstream directives because Oxlint excludes `vendor/**`.
 
-CI does not restore or save a lint-result cache. `DSH_OXLINT_THREADS` makes the shared runner pass the same bound to Oxlint's `--threads` option and the type-aware backend's `GOMAXPROCS` environment variable; ordinary local runs use both defaults. Pre-commit applies the formatting-only ESLint fixes, runs project-free Oxlint validation and native safe fixes, accepts selections containing only ignored files, and re-stages the result through lefthook. Public `lint` and CI retain the complete type-aware rules after preparing generated declarations.
+CI does not restore or save a lint-result cache. `DSH_OXLINT_THREADS` makes the shared runner pass the same bound to Oxlint's `--threads` option and the type-aware backend's `GOMAXPROCS` environment variable; ordinary local runs use both defaults. Pre-commit runs project-free Oxlint validation and safe fixes with one bounded retry, accepts selections containing only ignored files, and re-stages the result through lefthook. Public `lint` and CI retain the complete type-aware rules after preparing generated declarations.
 
 ## Verification
 
 The migrated configuration reports the same clean owned-source baseline after resolving two analyzer differences: one redundant test assertion was removed, while one structural cast required by `tsc` carries a narrow Oxlint suppression. A one-time audit against the exact deleted ESLint configuration blob established source 88-to-88, examples 87-to-87, and tests 83-to-83 after the rule-name translations. The committed fingerprint pins those audited Oxlint profiles and the complete override shape; it neither executes the deleted configuration nor propagates later upstream preset changes. Evaluating `typescript-eslint@8.61.0` also confirms that `strictTypeChecked` did not enable `@typescript-eslint/no-empty-function`; the deleted tests-only `off` entry was inert.
 
-Executable contract tests require type-aware diagnostics from the package, host, and client projects; assert the client-only script's project; reject unmatched fallback analysis; and exercise the Stylistic, SonarJS, and nursery compatibility paths. They also pin the staged profile's project-free inheritance, unused-suppression reporting, ignored-only staged selections, formatter/validator rule parity, and final formatted bytes. Runner tests pin both worker controls, and typecheck confirms that migration-driven source edits preserve the TypeScript programs.
+Executable contract tests require type-aware diagnostics from the package, host, and client projects; assert the client-only script's project; reject unmatched fallback analysis; and exercise the Stylistic, SonarJS, and nursery compatibility paths. They also pin the staged profile's project-free inheritance and TypeGraph coverage, unused-suppression reporting, ignored-only staged selections, the complete Stylistic rule set, and convergent final formatted bytes. Runner tests pin both worker controls, and typecheck confirms that migration-driven source edits preserve the TypeScript programs.
 
 ## Alternatives considered
 
-**Run both linters repository-wide.** Every correctness rule is available through Oxlint's native rules, nursery rule, or JavaScript-plugin compatibility layer. A repository-wide ESLint fallback would preserve the slower project-service setup and two correctness configurations without adding a check; the retained ESLint pass is deliberately limited to project-free staged formatting.
+**Run both linters repository-wide.** Every correctness rule is available through Oxlint's native rules, nursery rule, or JavaScript-plugin compatibility layer. A repository-wide ESLint fallback would preserve the slower project-service setup and two correctness configurations without adding a check.
 
-**Rely on compatibility-layer fixes.** The layer reports the established `@stylistic` rules but does not apply their fixes under either Oxlint fix mode. Keeping the narrow staged formatter preserves the contributor contract without broadening ESLint back into a repository linter.
+**Use a separate formatter.** The migration retained a narrow ESLint pass because the compatibility-layer fixes were treated as unavailable. The [Oxlint-only fix workflow](2026-08-09-oxlint-only-fix-workflow.md) supersedes that part of the decision with one bounded retry after the pinned toolchain proved it could execute the same fixes.
 
 **Drop @stylistic or SonarJS rules that are not native.** This would remove dependencies but weaken the mechanical quality contract. The compatibility layer preserves those rules until native replacements can be evaluated as a separate decision.
 
@@ -42,4 +42,4 @@ Local migration measurements reduced a clean type-aware lint run from about 61 s
 
 Type-aware diagnostics now come from the TypeScript Go analyzer bundled through `oxlint-tsgolint`, so edge-case inference can differ from typescript-eslint even when `tsc` accepts the same program. Lint and typecheck remain separate required evidence.
 
-The JavaScript-plugin compatibility API, staged profile, and staged formatter are additional boundaries to maintain. Commits defer type-aware diagnostics to public lint and CI, pay one project-free ESLint startup before Oxlint, and avoid depending on generated declarations. The root development graph retains ESLint plus the TypeScript parser. Repository-wide validation, type-aware analysis, cache policy, worker control, and inline directives remain Oxlint-owned.
+The JavaScript-plugin compatibility API and staged profile are additional boundaries to maintain. Commits defer type-aware diagnostics to public lint and CI and avoid depending on generated declarations. Repository-wide validation, fixes, type-aware analysis, cache policy, worker control, and inline directives remain Oxlint-owned.
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
index dae8c7451b..8e3d69cdce 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
@@ -12,25 +12,25 @@ Status: implemented
 
 ## 决策
 
-根目录的 [`.oxlintrc.json`](../../../../.oxlintrc.json) 是仓库类型感知 lint 配置的权威来源。不加载项目的 [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) 配置继承其源码规则，但会为有界的 pre-commit 路径禁用类型分析。`lint` 包脚本、门禁调度器、CI 和 lefthook 通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint；`lint:fix` 和 lefthook 会先调用仅用于格式化的 [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs)。直接的 `eslint` 和 `@typescript-eslint/parser` 开发依赖仅用于这次不加载项目的格式化流程；其精确版本锁定经过测试的解析器与修复器配对，该配置不包含正确性规则或类型感知规则。
+根目录的 [`.oxlintrc.json`](../../../../.oxlintrc.json) 是仓库类型感知 lint 配置的权威来源。不加载项目的 [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) 配置继承其源码规则，为有界的 pre-commit 路径禁用类型分析，并重新纳入类型感知后端无法分析但需保留的 TypeGraph fixture（测试前置数据）。`lint` 与 `lint:fix` 包脚本、门禁调度器、CI 和 lefthook 通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint；[仅使用 Oxlint 的修复工作流](2026-08-09-oxlint-only-fix-workflow.md)负责多轮插件修复，并取代单独的格式化回退路径。
 
 `options.typeAware` 启用 `oxlint-tsgolint`。其后端按文件发现 TypeScript 项目：包源码使用各自的包项目，host 测试、示例和网站使用 `tsconfig.host.json`，client 测试及 `scripts/client-bundle-purity.spec.ts` 使用 `tsconfig.client.json`。不含程序的根解决方案绝不会被扁平化。Oxlint 的 `--tsconfig` 覆盖项会影响导入解析，但类型感知 lint 会忽略它，因此本仓库不设置该选项。该配置显式载入迁移后的严格类型检查规则和仓库覆盖配置，而不启用内容可能发生变化的 Oxlint 宽泛类别。`typescript/no-unnecessary-condition` 仍从 Oxlint 的 nursery 规则集中启用，因为它在迁移前就是仓库强制执行的规则。
 
-Oxlint 的 JavaScript 插件兼容层运行 `@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs`，从而继续强制执行现有的格式和文件内重复逻辑规则。兼容层会报告 `@stylistic` 违规，但不会执行其修复器，因此仅用于格式化的 ESLint 流程只负责相应的自动修复；一项可执行检查确保这些可修复规则定义保持一致，而 `max-len` 仅用于验证。自有源码中的抑制指令使用 `oxlint-*` 指令和 `typescript/*` 命名空间，未使用的指令仍作为警告报告；vendor 源码保留其上游指令，因为 Oxlint 会排除 `vendor/**`。
+Oxlint 的 JavaScript 插件兼容层运行 `@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs`，从而继续强制执行现有的格式和文件内重复逻辑规则。兼容层会报告 `@stylistic` 违规并执行其安全修复；`max-len` 仍仅用于验证。自有源码中的抑制指令使用 `oxlint-*` 指令和 `typescript/*` 命名空间，未使用的指令仍作为警告报告；vendor 源码保留其上游指令，因为 Oxlint 会排除 `vendor/**`。
 
-CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行器将同一上限传给 Oxlint 的 `--threads` 选项和类型感知后端的 `GOMAXPROCS` 环境变量；普通本地运行对两者均采用默认值。Pre-commit 应用仅用于格式化的 ESLint 修复，运行不加载项目的 Oxlint 验证并应用原生安全修复，接受仅含已忽略文件的文件选择，并通过 lefthook 重新暂存结果。公共 `lint` 和 CI 会先准备生成的声明，并保留完整的类型感知规则。
+CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行器将同一上限传给 Oxlint 的 `--threads` 选项和类型感知后端的 `GOMAXPROCS` 环境变量；普通本地运行对两者均采用默认值。Pre-commit 运行不加载项目的 Oxlint 验证，应用带一次有界重试的安全修复，接受仅含已忽略文件的文件选择，并通过 lefthook 重新暂存结果。公共 `lint` 和 CI 会先准备生成的声明，并保留完整的类型感知规则。
 
 ## 验证
 
 解决两处分析器差异后，迁移后的配置报告与迁移前一致的自有源码无问题基线：移除了一项冗余测试断言，而 `tsc` 要求的一处结构性类型转换使用了窄范围的 Oxlint 抑制指令。以已删除 ESLint 配置的精确 blob 为基准进行的一次性审核在完成规则名映射后确认：源码为 88 项对 88 项，示例为 87 项对 87 项，测试为 83 项对 83 项。已提交的指纹锁定这些经审核的 Oxlint 规则配置及完整的覆盖结构；它既不执行已删除的配置，也不纳入后续的上游预设变更。对 `typescript-eslint@8.61.0` 的评估还确认，`strictTypeChecked` 并未启用 `@typescript-eslint/no-empty-function`；已删除、仅用于测试的 `off` 条目不起作用。
 
-可执行约定测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
+可执行约定测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为与 TypeGraph fixture 覆盖、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、完整的 Stylistic 规则集，以及收敛后最终格式化的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
 
 ## 考虑过的替代方案
 
-**在全仓库范围内同时运行两个 linter。** 所有正确性规则均可通过 Oxlint 原生规则、nursery 规则或 JavaScript 插件兼容层获得。在全仓库范围启用 ESLint 回退会保留较慢的项目服务初始化和两套正确性配置，却不会增加任何检查；保留的 ESLint 流程被刻意限制为不加载项目的暂存文件格式化。
+**在全仓库范围内同时运行两个 linter。** 所有正确性规则均可通过 Oxlint 原生规则、nursery 规则或 JavaScript 插件兼容层获得。在全仓库范围启用 ESLint 回退会保留较慢的项目服务初始化和两套正确性配置，却不会增加任何检查。
 
-**依赖兼容层修复。** 兼容层会报告既有的 `@stylistic` 规则，但在 Oxlint 的两种修复模式下都不会应用这些规则的修复。保留窄范围的暂存文件格式化器，可以在不将 ESLint 扩张回仓库 linter 的情况下维持贡献者约定。
+**使用单独的格式化器。** 迁移保留了窄范围的 ESLint 流程，因为当时认为兼容层无法执行修复。锁定版本的工具链证明能够执行相同修复后，[仅使用 Oxlint 的修复工作流](2026-08-09-oxlint-only-fix-workflow.md)以一次有界重试取代了该部分决策。
 
 **移除尚无原生实现的 @stylistic 或 SonarJS 规则。** 这会移除依赖，但也会削弱机械质量约定。兼容层会保留这些规则，直到能够通过单独决策评估原生替代规则。
 
@@ -42,4 +42,4 @@ CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行
 
 类型感知诊断现在来自通过 `oxlint-tsgolint` 捆绑的 TypeScript Go 分析器，因此即使 `tsc` 接受同一程序，边界场景下的类型推断也可能与 typescript-eslint 不同。lint 与类型检查仍是两项相互独立的必要证据。
 
-JavaScript 插件兼容 API、暂存配置和暂存文件格式化器是需要维护的额外边界。每次提交把类型感知诊断留给公共 lint 和 CI，在 Oxlint 之前启动一次不加载项目的 ESLint，并避免依赖生成的声明。根目录开发依赖图仍保留 ESLint 和 TypeScript 解析器。全仓库验证、类型感知分析、缓存政策、工作线程控制和内联指令仍由 Oxlint 负责。
+JavaScript 插件兼容 API 和暂存配置是需要维护的额外边界。每次提交把类型感知诊断留给公共 lint 和 CI，并避免依赖生成的声明。全仓库验证、修复、类型感知分析、缓存政策、工作线程控制和内联指令仍由 Oxlint 负责。
diff --git a/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.i18n.yaml
new file mode 100644
index 0000000000..824c74bd7f
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.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 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
+2026-08-09-oxlint-only-fix-workflow.md: bc38812db101499d980c38cb6c1dc5cba32e5cd6
+2026-08-09-oxlint-only-fix-workflow.zh.md: 91674837dd7c0c2da8d5b6214082dc7a2f2f0fac
diff --git a/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
new file mode 100644
index 0000000000..bc38812db1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
@@ -0,0 +1,37 @@
+# Agent Note: Oxlint-only fix workflow
+
+Status: implemented
+
+English | [中文](2026-08-09-oxlint-only-fix-workflow.zh.md)
+
+## Problem
+
+The [repository linter migration](2026-07-29-oxlint-linter.md) retained a formatting-only ESLint invocation because Oxlint's JavaScript-plugin bridge was treated as validation-only. The pinned Oxlint toolchain executes the safe fixers supplied by `@stylistic/eslint-plugin`, so the separate formatter duplicates a configuration boundary, command startup, and direct `eslint` plus `@typescript-eslint/parser` dependencies.
+
+A single Oxlint invocation is not an equivalent replacement. Overlapping plugin fixes can apply one change while leaving a newly exposed diagnostic; the repository's `semi` and `object-curly-spacing` fixture requires a second pass before it is clean. The workflow must retry that case without printing obsolete first-pass diagnostics.
+
+## Decision
+
+All repository lint and fix workflows invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts). Normal validation remains one process with inherited output. An invocation containing `--fix`, `--fix-suggestions`, or `--fix-dangerously` captures the first Oxlint result; success emits its stdout and stderr on their original channels, while a completed non-zero run discards its potentially obsolete diagnostics and runs the same command once more with inherited output. The runner re-raises a child signal instead of retrying or converting it to an exit code, and the second process completion is final.
+
+The `lint:fix` package script and staged lefthook job use that runner directly. The type-aware root profile still ignores preserved TypeGraph fixture shapes that `oxlint-tsgolint` cannot analyze; the project-free staged profile re-includes that directory, carries its intentional `any` and quote exceptions, and applies its style fixes before the full type-aware fix pass. The formatting-only ESLint configuration and the direct `eslint` and `@typescript-eslint/parser` development dependencies are absent. `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` remain Oxlint JavaScript plugins because they preserve enforced rules; pnpm still installs ESLint as their declared peer, but no repository configuration or workflow invokes it.
+
+## Verification
+
+The executable lint contract drives a deliberately overlapping style violation through the repository runner and requires a successful exit plus exact final bytes. The same contract pins the complete Stylistic rule set, project-free TypeGraph fixture coverage, the package scripts, the staged hook command, the deleted formatter configuration, and the absence of direct ESLint parser and runner dependencies. Existing executable probes continue to cover the Stylistic and SonarJS compatibility plugins, project-free staged validation, and type-aware project discovery.
+
+## Alternatives considered
+
+**Keep the formatting-only ESLint pass.** This preserves ESLint's built-in multipass behavior but retains a second runner, a duplicated formatting config, and direct dependencies after Oxlint can execute the same plugin fixes.
+
+**Run Oxlint once with `--fix`.** This is simpler, but overlapping safe fixes can leave the command partially formatted and non-zero even though another identical pass completes it.
+
+**Adopt Oxfmt.** A formatter migration changes the repository's output contract and would create an unrelated formatting diff. It remains a separate decision from removing the redundant ESLint execution path.
+
+**Remove the JavaScript compatibility plugins.** This would eliminate their ESLint peer graph but would also drop the enforced Stylistic and SonarJS rules. Dependency-tree purity does not justify weakening the quality contract.
+
+## Consequences
+
+Contributors, package scripts, hooks, and CI have one lint runner and one rule configuration. The staged profile repeats the root ignore list so it can re-include formatter-only fixtures without exposing vendor or generated files. A completed non-zero fix invocation always pays for one retry, including a stable unfixable error. The first pass buffers each output stream up to 64 MiB so obsolete diagnostics are not printed when the retry succeeds; process creation and capture failures, including that limit being exceeded, surface immediately without a retry.
+
+The dependency lock can still contain ESLint through plugin peer resolution. Removing that transitive package requires native replacements or a formatter decision that also replaces the compatibility plugins; it is not part of the workflow simplification.
diff --git a/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md
new file mode 100644
index 0000000000..91674837dd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 仅使用 Oxlint 的修复工作流
+
+Status: implemented
+
+[English](2026-08-09-oxlint-only-fix-workflow.md) | 中文
+
+## 问题
+
+[仓库 linter 迁移](2026-07-29-oxlint-linter.md)保留了一次仅用于格式化的 ESLint 调用，因为当时认为 Oxlint 的 JavaScript 插件桥接层只能用于校验。固定版本的 Oxlint 工具链能够执行 `@stylistic/eslint-plugin` 提供的安全修复，因此单独的格式化器重复引入了配置边界、命令启动过程，以及对 `eslint` 和 `@typescript-eslint/parser` 的直接依赖。
+
+单次调用 Oxlint 并不能实现等价替代。相互重叠的插件修复可能先应用一项变更，却留下由此新暴露的诊断；仓库中包含 `semi` 和 `object-curly-spacing` 违规的 fixture（测试前置数据）需要运行第二轮才能完全修复。工作流必须重试这种情况，同时不得打印第一轮中已经失效的诊断。
+
+## 决策
+
+仓库的所有 lint 与修复工作流都通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint。普通校验仍由单个进程执行，并直接继承输出。包含 `--fix`、`--fix-suggestions` 或 `--fix-dangerously` 的调用会捕获第一次 Oxlint 的运行结果；如果成功，就通过原有通道输出其 stdout 和 stderr；如果进程正常结束但状态非零，则丢弃其中可能已经失效的诊断，随后以继承输出的方式再运行一次相同命令。子进程被信号终止时，运行器会重新触发该信号，而不会重试或将其转换为退出码；第二个进程的结束结果作为最终结果。
+
+`lint:fix` 包脚本和处理暂存文件的 lefthook 作业直接使用该运行器。类型感知的根配置仍会忽略 `oxlint-tsgolint` 无法分析、需要保留原始形态的 TypeGraph fixture；不加载项目的暂存配置会重新纳入该目录，保留其中有意设置的 `any` 与引号规则例外，并在完整的类型感知修复轮次之前应用其样式修复。仓库中不存在仅用于格式化的 ESLint 配置，也不直接依赖 `eslint` 和 `@typescript-eslint/parser` 这两个开发依赖。`@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs` 仍作为 Oxlint 的 JavaScript 插件保留，因为它们承载了已强制执行的规则；pnpm 仍会将 ESLint 作为这些插件声明的对等依赖（peer dependency）进行安装，但仓库中的配置和工作流均不会调用它。
+
+## 验证
+
+可执行 lint 约定将一项特意构造、修复相互重叠的样式违规交给仓库运行器处理，并要求运行器成功退出且最终字节完全一致。同一约定还会固定完整的 Stylistic 规则集、不加载项目时对 TypeGraph fixture 的覆盖、包脚本、暂存文件钩子命令、已删除的格式化器配置，以及 ESLint 解析器和运行器不存在直接依赖这一事实。现有的可执行探针继续覆盖 Stylistic 和 SonarJS 兼容插件、不加载项目的暂存文件校验，以及类型感知的项目发现。
+
+## 考虑过的替代方案
+
+**保留仅用于格式化的 ESLint 轮次。** 这会保留 ESLint 内置的多轮修复行为，但在 Oxlint 已能执行相同插件修复的情况下，仍需维护第二个运行器、重复的格式化配置和直接依赖。
+
+**仅运行一次带 `--fix` 的 Oxlint。** 这样更简单，但相互重叠的安全修复可能使命令只完成部分格式化并以非零状态退出，即使再次运行同一命令就能完成修复。
+
+**采用 Oxfmt。** 迁移格式化器会改变仓库的输出约定，并产生无关的格式化 diff。它与移除冗余 ESLint 执行路径是两项独立决策。
+
+**移除 JavaScript 兼容插件。** 这会消除这些插件引入的 ESLint 对等依赖图，但也会移除强制执行的 Stylistic 和 SonarJS 规则。追求依赖树纯净不能成为削弱质量约定的理由。
+
+## 结果
+
+贡献者、包脚本、钩子和 CI 统一使用一个 lint 运行器和一份规则配置。暂存配置会重复根配置的忽略清单，以便重新纳入仅用于格式化的 fixture，同时避免将 vendor 或生成文件纳入检查。修复进程正常结束但状态非零时，始终会额外执行一次重试；稳定存在且无法修复的错误也不例外。第一轮的每条输出流最多缓冲 64 MiB，因此重试成功时不会打印已经失效的诊断；进程创建或输出捕获失败（包括超出该上限）时会立即报告错误，不会重试。
+
+依赖锁中仍可能因插件的对等依赖解析而包含 ESLint。要移除这个传递依赖，需要使用原生替代方案，或另行决定采用能够同时取代兼容插件的格式化器；这不属于本次工作流简化的范围。
diff --git a/.oxlintrc.json b/.oxlintrc.json
index ed470ecd70..70f53fd4cd 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -298,6 +298,24 @@
       "jsPlugins": [
         "@stylistic/eslint-plugin"
       ]
+    },
+    {
+      // The project-free staged profile re-includes this syntax-coverage fixture.
+      "files": [
+        "packages/typert/generator/tests/fixtures/type-model/**/*.{ts,tsx}"
+      ],
+      "rules": {
+        "typescript/no-explicit-any": "off"
+      }
+    },
+    {
+      // TypeGraph coverage must retain source-authored syntax that the normal quote rule forbids.
+      "files": [
+        "packages/typert/generator/tests/fixtures/type-model/packages/host/src/models.ts"
+      ],
+      "rules": {
+        "@stylistic/quotes": "off"
+      }
     }
   ]
 }
diff --git a/.oxlintrc.staged.json b/.oxlintrc.staged.json
index db79a933fa..ca693f67ae 100644
--- a/.oxlintrc.staged.json
+++ b/.oxlintrc.staged.json
@@ -3,5 +3,20 @@
   "extends": ["./.oxlintrc.json"],
   "options": {
     "typeAware": false
-  }
+  },
+  "ignorePatterns": [
+    "**/lib/**",
+    "**/node_modules/**",
+    "**/.sessions/**",
+    ".claude/**",
+    "**/.doc-typecheck-*/**",
+    "**/.node-next-types-*/**",
+    "website/.generated/**",
+    "vendor/**",
+    "native/**",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.config.ts",
+    "packages/client/tsdown.client.ts"
+  ]
 }
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 48f04c9799..55c753b45d 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -139,7 +139,6 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@types/spdx-expression-parse`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/turndown`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/ws`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
-| [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint) | MIT |
 | [`@vitejs/plugin-react`](https://github.com/vitejs/vite-plugin-react) | MIT |
 | [`@vitest/coverage-v8`](https://github.com/vitest-dev/vitest) | MIT |
 | [`@yarnpkg/cli-dist`](https://github.com/yarnpkg/berry) | BSD-2-Clause |
@@ -148,7 +147,6 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`dayjs`](https://github.com/iamkun/dayjs) | MIT |
 | [`debug`](https://github.com/debug-js/debug) | MIT |
 | [`esbuild`](https://github.com/evanw/esbuild) | MIT |
-| [`eslint`](https://github.com/eslint/eslint) | MIT |
 | [`eslint-plugin-sonarjs`](https://github.com/SonarSource/SonarJS) | LGPL-3.0-only |
 | [`execa`](https://github.com/sindresorhus/execa) | MIT |
 | [`fast-check`](https://github.com/dubzzz/fast-check) | MIT |
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 5e2895c8ba..84cff8fa96 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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 docs/development.md
-development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 56df93beddbb128cac8e0bcf2adaa9dcfb72c751
+development.md: 8b6c148d87fdd6288695b0029b9dfcc0139d2144
+development.zh.md: 55ca013cc0dd901500e340a7447057de27665f61
diff --git a/docs/development.md b/docs/development.md
index f7084403b3..8b6c148d87 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -106,7 +106,7 @@ The installer probes the exact Node/tsx driver entrypoint before publishing its
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
-- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-commit` verifies staged pairing records against the staged owner blobs, validates staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint fixes with one bounded retry, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
 - `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.
 - `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 56df93bedd..55ca013cc0 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -106,7 +106,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
-- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件，并通过一次有界重试应用 Oxlint 修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
 - `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
diff --git a/eslint.format.config.mjs b/eslint.format.config.mjs
deleted file mode 100644
index 5681688e81..0000000000
--- a/eslint.format.config.mjs
+++ /dev/null
@@ -1,59 +0,0 @@
-import stylistic from '@stylistic/eslint-plugin'
-import parser from '@typescript-eslint/parser'
-
-// Oxlint's JavaScript-plugin compatibility layer reports these rules but does
-// not execute their fixers. Keep this config formatting-only: Oxlint remains
-// the authoritative repository linter after this pass applies safe fixes.
-export default [
-  {
-    ignores: [
-      '**/lib/**',
-      '**/node_modules/**',
-      '**/.sessions/**',
-      '.claude/**',
-      '**/.doc-typecheck-*/**',
-      '**/.node-next-types-*/**',
-      // Do not mirror Oxlint's contract-fixture ignore: those files must reach this formatter.
-      'website/.generated/**',
-      'vendor/**',
-      'native/**',
-      '**/*.js',
-      '**/*.mjs',
-      '**/*.config.ts',
-      'packages/client/tsdown.client.ts',
-    ],
-  },
-  {
-    files: ['**/*.{ts,tsx,mts,cts}'],
-    languageOptions: {
-      parser,
-      parserOptions: {
-        sourceType: 'module',
-      },
-    },
-    plugins: {
-      '@stylistic': stylistic,
-    },
-    rules: {
-      '@stylistic/indent': ['error', 2],
-      '@stylistic/semi': ['error', 'never'],
-      '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
-      '@stylistic/comma-dangle': ['error', 'always-multiline'],
-      '@stylistic/eol-last': ['error', 'always'],
-      '@stylistic/no-trailing-spaces': 'error',
-      '@stylistic/object-curly-spacing': ['error', 'always'],
-      '@stylistic/arrow-parens': ['error', 'as-needed', { requireForBlockBody: true }],
-      '@stylistic/member-delimiter-style': ['error', {
-        multiline: { delimiter: 'none' },
-        singleline: { delimiter: 'semi', requireLast: false },
-      }],
-    },
-  },
-  {
-    // TypeGraph coverage must retain source-authored syntax that the normal quote rule forbids.
-    files: ['packages/typert/generator/tests/fixtures/type-model/packages/host/src/models.ts'],
-    rules: {
-      '@stylistic/quotes': 'off',
-    },
-  },
-]
diff --git a/lefthook.yml b/lefthook.yml
index 0e78d16252..0ea7f4e537 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -8,13 +8,6 @@ pre-commit:
       glob: '*.i18n.yaml'
       run: node_modules/.bin/tsx scripts/verify-translation-pairing.ts --cached {staged_files}
 
-    - name: format (staged)
-      glob: '*.{ts,tsx,mts,cts,mjs}'
-      exclude:
-        - 'vendor/*/src/**'
-      run: node_modules/.bin/eslint --config eslint.format.config.mjs --fix --no-warn-ignored {staged_files}
-      stage_fixed: true
-
     - name: lint (staged)
       glob: '*.{ts,tsx,mts,cts,mjs}'
       exclude:
diff --git a/package.json b/package.json
index 864814ffe6..d417354739 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
     "lint": "npm run build:lib:host && npm run lint:contracts-ready",
     "lint:contracts-ready": "tsx scripts/run-oxlint.ts .",
     "lint:fix": "npm run build:lib:host && npm run lint:fix:contracts-ready",
-    "lint:fix:contracts-ready": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
+    "lint:fix:contracts-ready": "tsx scripts/run-oxlint.ts --config .oxlintrc.staged.json packages/typert/generator/tests/fixtures/type-model --fix && tsx scripts/run-oxlint.ts . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
@@ -139,10 +139,8 @@
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.0",
     "@types/spdx-expression-parse": "^4.0.0",
-    "@typescript-eslint/parser": "8.61.0",
     "@vitest/coverage-v8": "^4.1.8",
     "@yarnpkg/cli-dist": "4.17.1",
-    "eslint": "10.5.0",
     "eslint-plugin-sonarjs": "^4.1.0",
     "execa": "^10.0.0",
     "fast-check": "^4.8.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bd2eab469c..da3703e5ff 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -41,18 +41,12 @@ importers:
       '@types/spdx-expression-parse':
         specifier: ^4.0.0
         version: 4.0.0
-      '@typescript-eslint/parser':
-        specifier: 8.61.0
-        version: 8.61.0(eslint@10.5.0(jiti@2.7.0))(typescript@6.0.3)
       '@vitest/coverage-v8':
         specifier: ^4.1.8
         version: 4.1.8(vitest@4.1.8)
       '@yarnpkg/cli-dist':
         specifier: 4.17.1
         version: 4.17.1
-      eslint:
-        specifier: 10.5.0
-        version: 10.5.0(jiti@2.7.0)
       eslint-plugin-sonarjs:
         specifier: ^4.1.0
         version: 4.1.0(eslint@10.5.0(jiti@2.7.0))
@@ -9962,53 +9956,10 @@ packages:
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
-  '@typescript-eslint/parser@8.61.0':
-    resolution: {integrity: sha512-5B7PfA2e1NQGCnDHd/0lW7W3gvp3d59Ryw54FYO8Uswxo9f6ikw3AZV+Xj/TvpImmpsiYyUqAfhC6kJID1jF6w==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/project-service@8.61.0':
-    resolution: {integrity: sha512-DV42F7MLJO6Rax7SK1yg43tcnEfGUrurSpSxKuVX+a3RCTzBlH3fuxprrOJXKCJGAaw82xXocikJ0uQaqwXgGA==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/scope-manager@8.61.0':
-    resolution: {integrity: sha512-IWdXFHFSb6mlC3HPc7QsLDm5zYEbUla6trDEHf32D3/dnuUyXd87plScSNXSbm0/RxMvObpI17sv/EDTGrGZkA==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-
-  '@typescript-eslint/tsconfig-utils@8.61.0':
-    resolution: {integrity: sha512-O5Amvdv9ztMpxpf+vmFULGG78IE6Qwdr3bCGvqwG4nwc9H2qXkOYJJnRbRHyMkQTjv1d03olqwwwzHLMqpFePQ==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/tsconfig-utils@8.65.0':
-    resolution: {integrity: sha512-j6GzGqCiRdA7Qhur2VVmKZAkBLfnHFQfx4TaJGL9RMveZqCo48jSHHO0DTgizEnGhtWnqmbtCUSrqSkdiY/0Hg==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
   '@typescript-eslint/types@8.61.0':
     resolution: {integrity: sha512-9QTQpZ5Iin4CdIodfbDQFSeiSJKidgYJYug1P9CC2xWgUTvlmixViqDZNciMjwLBZyJnG4tGmPl97rVAFb1AJg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  '@typescript-eslint/types@8.65.0':
-    resolution: {integrity: sha512-JSSwWNy+H0E/01jJEM+hrX6N0OFDzFzeIhHFSAS01tlVaevpG8cFyYRPhS5yjGOvBUx3sqQHVMjCL1CAZZMxBg==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-
-  '@typescript-eslint/typescript-estree@8.61.0':
-    resolution: {integrity: sha512-42zatd5qSvvcV1JdDBCLxYRznvP4eIHpPoZXdkPFnAmanA4FuZ5dibSnCBggY8hQnqajPpoGjXFdZ7fIJKQnlA==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/visitor-keys@8.61.0':
-    resolution: {integrity: sha512-QVLZu3ZPQEE+HICQyAMZ2yLQhxf0meY/wx6Hx14YcTNj13JB3qHlX3lJ02L3fLGHgERRH71kvYDwiXIguT3AjQ==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-
   '@ungap/structured-clone@1.3.3':
     resolution: {integrity: sha512-60YRaenCQcVjYEKOcG824+DRGGIQ3VKErcBoAEDJZz5bKIs2ZG+X/H9Nk+Q6EVkwJk5QNApxbrc5QtBSwtrXAg==}
 
@@ -15039,64 +14990,8 @@ snapshots:
     dependencies:
       '@types/node': 22.20.0
 
-  '@typescript-eslint/parser@8.61.0(eslint@10.5.0(jiti@2.7.0))(typescript@6.0.3)':
-    dependencies:
-      '@typescript-eslint/scope-manager': 8.61.0
-      '@typescript-eslint/types': 8.61.0
-      '@typescript-eslint/typescript-estree': 8.61.0(typescript@6.0.3)
-      '@typescript-eslint/visitor-keys': 8.61.0
-      debug: 4.4.3
-      eslint: 10.5.0(jiti@2.7.0)
-      typescript: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
-  '@typescript-eslint/project-service@8.61.0(typescript@6.0.3)':
-    dependencies:
-      '@typescript-eslint/tsconfig-utils': 8.65.0(typescript@6.0.3)
-      '@typescript-eslint/types': 8.65.0
-      debug: 4.4.3
-      typescript: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
-  '@typescript-eslint/scope-manager@8.61.0':
-    dependencies:
-      '@typescript-eslint/types': 8.61.0
-      '@typescript-eslint/visitor-keys': 8.61.0
-
-  '@typescript-eslint/tsconfig-utils@8.61.0(typescript@6.0.3)':
-    dependencies:
-      typescript: 6.0.3
-
-  '@typescript-eslint/tsconfig-utils@8.65.0(typescript@6.0.3)':
-    dependencies:
-      typescript: 6.0.3
-
   '@typescript-eslint/types@8.61.0': {}
 
-  '@typescript-eslint/types@8.65.0': {}
-
-  '@typescript-eslint/typescript-estree@8.61.0(typescript@6.0.3)':
-    dependencies:
-      '@typescript-eslint/project-service': 8.61.0(typescript@6.0.3)
-      '@typescript-eslint/tsconfig-utils': 8.61.0(typescript@6.0.3)
-      '@typescript-eslint/types': 8.61.0
-      '@typescript-eslint/visitor-keys': 8.61.0
-      debug: 4.4.3
-      minimatch: 10.2.5
-      semver: 7.8.4
-      tinyglobby: 0.2.17
-      ts-api-utils: 2.5.0(typescript@6.0.3)
-      typescript: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
-  '@typescript-eslint/visitor-keys@8.61.0':
-    dependencies:
-      '@typescript-eslint/types': 8.61.0
-      eslint-visitor-keys: 5.0.1
-
   '@ungap/structured-clone@1.3.3': {}
 
   '@upsetjs/venn.js@2.0.0':
diff --git a/scripts/oxlint-contract.spec.ts b/scripts/oxlint-contract.spec.ts
index 7592780881..ccb226fb41 100644
--- a/scripts/oxlint-contract.spec.ts
+++ b/scripts/oxlint-contract.spec.ts
@@ -1,14 +1,15 @@
 import { spawnSync } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { fileURLToPath } from 'node:url'
 import { flattenDiagnosticMessageText, parseConfigFileTextToJson } from 'typescript'
 import { describe, expect, it } from 'vitest'
 
 const repositoryRoot = fileURLToPath(new URL('..', import.meta.url))
-const eslintCli = fileURLToPath(new URL('../node_modules/eslint/bin/eslint.js', import.meta.url))
 const oxlintCli = fileURLToPath(new URL('../node_modules/oxlint/bin/oxlint', import.meta.url))
+const tsxCli = fileURLToPath(new URL('../node_modules/tsx/dist/cli.mjs', import.meta.url))
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -18,11 +19,11 @@ function isUnknownArray(value: unknown): value is unknown[] {
   return Array.isArray(value)
 }
 
-function runStagedFormatter(paths: readonly string[]) {
-  return spawnSync(process.execPath, [eslintCli, '--config', 'eslint.format.config.mjs', '--fix', '--no-warn-ignored', ...paths], {
+function runRepositoryOxlint(args: readonly string[], env: NodeJS.ProcessEnv = {}) {
+  return spawnSync(process.execPath, [tsxCli, 'scripts/run-oxlint.ts', ...args], {
     cwd: repositoryRoot,
     encoding: 'utf8',
-    env: { ...process.env, NO_COLOR: '1' },
+    env: { ...process.env, NO_COLOR: '1', ...env },
   })
 }
 
@@ -150,7 +151,7 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     }
   }, 20_000)
 
-  it('keeps formatter rules aligned with Oxlint validation', async () => {
+  it('keeps the complete stylistic contract in Oxlint', async () => {
     const oxlintPath = join(repositoryRoot, '.oxlintrc.json')
     const result = parseConfigFileTextToJson(oxlintPath, await readFile(oxlintPath, 'utf8'))
     if (result.error !== undefined) {
@@ -160,27 +161,67 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     if (!isRecord(parsed) || !isUnknownArray(parsed.overrides)) {
       throw new Error('.oxlintrc.json must contain an overrides array')
     }
+    expect(parsed.ignorePatterns).toEqual(expect.arrayContaining([
+      'packages/typert/generator/tests/fixtures/type-model/**',
+    ]))
     const stylisticOverride = parsed.overrides.find((value: unknown) =>
       isRecord(value) && isRecord(value.rules) && '@stylistic/max-len' in value.rules)
     if (!isRecord(stylisticOverride) || !isRecord(stylisticOverride.rules)) {
       throw new Error('.oxlintrc.json must contain the @stylistic validator override')
     }
-    const validatorRules = { ...stylisticOverride.rules }
-    const maxLen = validatorRules['@stylistic/max-len']
-    delete validatorRules['@stylistic/max-len']
+    expect(stylisticOverride.rules).toMatchObject({
+      '@stylistic/indent': ['error', 2],
+      '@stylistic/semi': ['error', 'never'],
+      '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
+      '@stylistic/comma-dangle': ['error', 'always-multiline'],
+      '@stylistic/eol-last': ['error', 'always'],
+      '@stylistic/no-trailing-spaces': 'error',
+      '@stylistic/object-curly-spacing': ['error', 'always'],
+      '@stylistic/arrow-parens': ['error', 'as-needed', { requireForBlockBody: true }],
+      '@stylistic/member-delimiter-style': ['error', {
+        multiline: { delimiter: 'none' },
+        singleline: { delimiter: 'semi', requireLast: false },
+      }],
+      '@stylistic/max-len': ['error', { code: 140, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: true }],
+    })
+    const typeGraphOverride = parsed.overrides.find((value: unknown) =>
+      isRecord(value)
+      && isUnknownArray(value.files)
+      && value.files.includes('packages/typert/generator/tests/fixtures/type-model/packages/host/src/models.ts'))
+    expect(typeGraphOverride).toMatchObject({
+      rules: { '@stylistic/quotes': 'off' },
+    })
+  })
 
-    const formatterUrl = pathToFileURL(join(repositoryRoot, 'eslint.format.config.mjs')).href
-    const formatterModule = await import(formatterUrl) as unknown
-    if (!isRecord(formatterModule) || !isUnknownArray(formatterModule.default)) {
-      throw new Error('eslint.format.config.mjs must default-export a config array')
-    }
-    const formatterOverride = formatterModule.default.find((value: unknown) => isRecord(value) && isRecord(value.rules))
-    if (!isRecord(formatterOverride) || !isRecord(formatterOverride.rules)) {
-      throw new Error('eslint.format.config.mjs must contain a rules object')
+  it('checks preserved TypeGraph syntax without type-aware analysis', () => {
+    const result = runOxlint([
+      '--config',
+      '.oxlintrc.staged.json',
+      'packages/typert/generator/tests/fixtures/type-model',
+    ])
+
+    expect(result.error).toBeUndefined()
+    expect(result.status, normalizedOutput(result)).toBe(0)
+  })
+
+  it('keeps repository lint workflows Oxlint-only', async () => {
+    const packageJson = JSON.parse(await readFile(join(repositoryRoot, 'package.json'), 'utf8')) as unknown
+    if (!isRecord(packageJson) || !isRecord(packageJson.scripts) || !isRecord(packageJson.devDependencies)) {
+      throw new Error('package.json must contain scripts and devDependencies objects')
     }
 
-    expect(validatorRules).toStrictEqual(formatterOverride.rules)
-    expect(maxLen).toStrictEqual(['error', { code: 140, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: true }])
+    expect(packageJson.scripts['lint:contracts-ready']).toBe('tsx scripts/run-oxlint.ts .')
+    expect(packageJson.scripts['lint:fix:contracts-ready']).toBe(
+      'tsx scripts/run-oxlint.ts --config .oxlintrc.staged.json packages/typert/generator/tests/fixtures/type-model --fix && tsx scripts/run-oxlint.ts . --fix',
+    )
+    expect(packageJson.devDependencies).not.toHaveProperty('eslint')
+    expect(packageJson.devDependencies).not.toHaveProperty('@typescript-eslint/parser')
+    expect(existsSync(join(repositoryRoot, 'eslint.format.config.mjs'))).toBe(false)
+
+    const lefthook = await readFile(join(repositoryRoot, 'lefthook.yml'), 'utf8')
+    expect(lefthook).toContain('scripts/run-oxlint.ts --config .oxlintrc.staged.json --fix')
+    expect(lefthook).not.toContain('node_modules/.bin/eslint')
+    expect(lefthook).not.toContain('eslint.format.config.mjs')
   })
 
   it('reports an unused suppression', async () => {
@@ -227,10 +268,13 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     if (result.error !== undefined) {
       throw new Error(flattenDiagnosticMessageText(result.error.messageText, '\n'))
     }
-    expect(result.config).toMatchObject({
+    const stagedConfig = result.config as unknown
+    if (!isRecord(stagedConfig)) throw new Error('.oxlintrc.staged.json must contain a config object')
+    expect(stagedConfig).toMatchObject({
       extends: ['./.oxlintrc.json'],
       options: { typeAware: false },
     })
+    expect(stagedConfig.ignorePatterns).not.toContain('packages/typert/generator/tests/fixtures/type-model/**')
 
     const suffix = randomUUID()
     const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
@@ -254,30 +298,76 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     }
   })
 
-  it('applies staged stylistic fixes before Oxlint validation', async () => {
+  it('preserves successful fix output channels', async () => {
     const suffix = randomUUID()
-    const configPath = await writeContractConfig(suffix)
-    const directory = join(repositoryRoot, 'scripts', `.oxlint-contract-${suffix}`)
-    const path = join(directory, 'fix.ts')
+    const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
 
     try {
-      await mkdir(directory, { recursive: true })
-      await writeFile(path, 'const value={answer:1};  \nconsole.log(value)\n')
-
-      const relativePath = relative(repositoryRoot, path)
-      const formatResult = runStagedFormatter([relativePath])
-      const lintResult = runOxlint(['--config', relative(repositoryRoot, configPath), '--fix', relativePath])
-
-      expect(formatResult.error).toBeUndefined()
-      expect(formatResult.status, normalizedOutput(formatResult)).toBe(0)
-      expect(lintResult.error).toBeUndefined()
-      expect(lintResult.status, normalizedOutput(lintResult)).toBe(0)
-      await expect(readFile(path, 'utf8')).resolves.toBe('const value={ answer:1 }\nconsole.log(value)\n')
-    } finally {
-      await Promise.all([
-        rm(directory, { recursive: true, force: true }),
-        rm(configPath, { force: true }),
+      await writeFile(path, '// oxlint-disable-next-line no-console\nexport const value = 1\n')
+      const result = runRepositoryOxlint([
+        '--config',
+        '.oxlintrc.staged.json',
+        '--format',
+        'unix',
+        '--fix',
+        relative(repositoryRoot, path),
       ])
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, normalizedOutput(result)).toBe(0)
+      expect(result.stdout).toContain('Unused oxlint-disable directive')
+      expect(result.stderr).toBe('')
+    } finally {
+      await rm(path, { force: true })
     }
-  }, 20_000)
+  })
+
+  it('prints only the final diagnostics when a fix retry still fails', async () => {
+    const suffix = randomUUID()
+    const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
+
+    try {
+      await writeFile(path, `export const longProbe = ${'1 + '.repeat(80)}1\n`)
+      const result = runRepositoryOxlint([
+        '--config',
+        '.oxlintrc.staged.json',
+        '--format',
+        'unix',
+        '--fix',
+        relative(repositoryRoot, path),
+      ])
+      const output = normalizedOutput(result)
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, output).toBe(1)
+      expect(output.match(/@stylistic\(max-len\)/g)).toHaveLength(1)
+    } finally {
+      await rm(path, { force: true })
+    }
+  })
+
+  it.each(['--fix', '--fix-suggestions', '--fix-dangerously'])(
+    'converges overlapping staged stylistic fixes through Oxlint under %s',
+    async (fixFlag) => {
+      const suffix = randomUUID()
+      const directory = join(repositoryRoot, 'scripts', `.oxlint-contract-${suffix}`)
+      const path = join(directory, 'fix.ts')
+
+      try {
+        await mkdir(directory, { recursive: true })
+        await writeFile(path, 'const value={answer:1};  \nconsole.log(value)\n')
+
+        const relativePath = relative(repositoryRoot, path)
+        const lintResult = runRepositoryOxlint(['--config', '.oxlintrc.staged.json', fixFlag, relativePath])
+
+        expect(lintResult.error).toBeUndefined()
+        expect(lintResult.status, normalizedOutput(lintResult)).toBe(0)
+        expect(normalizedOutput(lintResult)).not.toContain('@stylistic')
+        await expect(readFile(path, 'utf8')).resolves.toBe('const value={ answer:1 }\nconsole.log(value)\n')
+      } finally {
+        await rm(directory, { recursive: true, force: true })
+      }
+    },
+    20_000,
+  )
 })
diff --git a/scripts/run-oxlint.ts b/scripts/run-oxlint.ts
index e833f75c69..13ed84799f 100644
--- a/scripts/run-oxlint.ts
+++ b/scripts/run-oxlint.ts
@@ -3,6 +3,12 @@ import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const oxlintCli = fileURLToPath(new URL('../node_modules/oxlint/bin/oxlint', import.meta.url))
+const MAX_CAPTURED_OUTPUT_BYTES = 64 * 1024 * 1024
+const FIX_FLAGS = new Set(['--fix', '--fix-dangerously', '--fix-suggestions'])
+
+function isFixInvocation(args: readonly string[]): boolean {
+  return args.some(arg => FIX_FLAGS.has(arg))
+}
 
 /** Complete Oxlint child-process arguments and environment. */
 export interface OxlintInvocation {
@@ -32,14 +38,50 @@ export function resolveOxlintInvocation(args: readonly string[], env: NodeJS.Pro
   }
 }
 
+function completeFrom(result: { readonly signal: NodeJS.Signals | null; readonly status: number | null }): void {
+  if (result.signal !== null) {
+    process.kill(process.pid, result.signal)
+    return
+  }
+  process.exitCode = result.status ?? 1
+}
+
 function main(): void {
   const invocation = resolveOxlintInvocation(process.argv.slice(2), process.env)
-  const result = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+  if (!isFixInvocation(invocation.args)) {
+    const result = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+      env: invocation.env,
+      stdio: 'inherit',
+    })
+    if (result.error !== undefined) throw result.error
+    completeFrom(result)
+    return
+  }
+
+  const first = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+    encoding: 'utf8',
+    env: invocation.env,
+    maxBuffer: MAX_CAPTURED_OUTPUT_BYTES,
+  })
+  if (first.error !== undefined) throw first.error
+  if (first.signal !== null) {
+    completeFrom(first)
+    return
+  }
+  if (first.status === 0) {
+    process.stdout.write(first.stdout)
+    process.stderr.write(first.stderr)
+    process.exitCode = 0
+    return
+  }
+
+  // Overlapping JS-plugin fixes can expose one more fixable diagnostic after the first pass.
+  const second = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
     env: invocation.env,
     stdio: 'inherit',
   })
-  if (result.error !== undefined) throw result.error
-  process.exitCode = result.status ?? 1
+  if (second.error !== undefined) throw second.error
+  completeFrom(second)
 }
 
 const entrypoint = process.argv[1]

From d950f60bdfbd3d9ef4a7fe3349f8a03a8b03afc5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 14:58:54 +0800
Subject: [PATCH 210/262] test(windows): stabilize aliased HMR writes

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index 033ad1661a..1de504c221 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -26,21 +26,23 @@ async function eventually(test: () => boolean, message: string): Promise<void> {
 }
 
 describe('HMR exact config paths', () => {
-  it('observes module changes when its watch base is a filesystem alias', { timeout: 20_000 }, async () => {
+  it('observes module changes when its watch base is a filesystem alias', { timeout: 30_000 }, async () => {
     const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-module-canonical-'))
     const alias = `${target}-alias`
-    const filename = join(alias, 'module.ts')
+    const aliasFilename = join(alias, 'module.ts')
     symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
-    writeFileSync(filename, 'export const generation = 0\n')
+    writeFileSync(aliasFilename, 'export const generation = 0\n')
     const ctx = await bootHmr(alias, ['.'])
-    const expected = pathToFileURL(join(realpathSync(target), 'module.ts')).href
+    const filename = join(realpathSync(target), 'module.ts')
+    const expected = pathToFileURL(filename).href
     const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)
     const observed: string[] = []
     ctx.on('hmr/change', (url) => { observed.push(url) })
     try {
-      const deadline = Date.now() + 10_000
+      const deadline = Date.now() + 20_000
       for (let generation = 1; !observed.includes(expected); generation += 1) {
         if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        // The watch base, not the writer spelling, is the alias under test.
         writeFileSync(filename, `export const generation = ${generation}\n`)
         // Leave Chokidar's atomic-write window idle so one coalesced change can publish.
         await new Promise(resolve => setTimeout(resolve, 250))

From 8829d15b8e252e9bc491c5ca0785a3ca570c00b4 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:02:52 +0800
Subject: [PATCH 211/262] test: update Oxlint override fingerprint

---
 scripts/lint-rule-fingerprint.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/lint-rule-fingerprint.spec.ts b/scripts/lint-rule-fingerprint.spec.ts
index a28afcc8cf..b1f57eba7b 100644
--- a/scripts/lint-rule-fingerprint.spec.ts
+++ b/scripts/lint-rule-fingerprint.spec.ts
@@ -85,7 +85,7 @@ describe('Oxlint repository rule fingerprint', () => {
   const overrides: readonly unknown[] = parsed.overrides
 
   it('pins the complete override shape', () => {
-    expect(overrides).toHaveLength(6)
+    expect(overrides).toHaveLength(8)
   })
 
   it.each(Object.entries(profiles))('pins the %s rule profile', (_name, profile) => {

From cf5e04f75c3f0cfeebef28454145051576b7b8af Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Sun, 9 Aug 2026 15:12:23 +0800
Subject: [PATCH 212/262] docs: document idle watchdog activity pulses

---
 .../2026-07-06-timeout-deadline-library.i18n.yaml     |  4 ++--
 .../2026-07-06-timeout-deadline-library.md            | 11 ++++++-----
 .../2026-07-06-timeout-deadline-library.zh.md         | 11 ++++++-----
 3 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index 24a047b540..8b3d66c3b0 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.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 .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: 63463a76a65743436d4e78479800c19e257a42de
-2026-07-06-timeout-deadline-library.zh.md: c47e6d4e6ed0bec368fca8857e5bd4d7229b6b0e
+2026-07-06-timeout-deadline-library.md: 1afb8e326356f012498eed778e9bab1b0be64ea5
+2026-07-06-timeout-deadline-library.zh.md: c6992ba5463122e4eb4ebd1d904d0c0906140353
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index 63463a76a6..1afb8e3263 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
@@ -57,10 +57,11 @@ export function deadline(
 export interface IdleWatchdog {
   readonly signal: AbortSignal
   next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  pulse(): void
   [Symbol.dispose](): void
 }
 
-/** Arm only while one iterator `next()` is outstanding, then rearm on later demand. */
+/** Arm only while one iterator `next()` is outstanding; rearm on later demand or out-of-band activity. */
 export function idleWatchdog(
   upstream: AbortSignal | undefined,
   timeoutMs: number,
@@ -71,7 +72,7 @@ export function idleWatchdog(
 export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): TimeoutReason | undefined
 ```
 
-`deadline` fuses an upstream signal with a one-shot timer through `AbortSignal.any`, adds a typed `TimeoutReason`, and exposes disposable timer cleanup. Non-positive timeouts are an internal no-timeout sentinel for backend-owned background work; external hints pass through `clampTimeout` and must be positive and finite. Without a timer or upstream signal, the function returns a never-aborting signal with the same disposal shape. `idleWatchdog` instead requires a positive finite interval, keeps one stable fused signal for the entire stream, and arms its timer only while one iterator `next()` is outstanding; resolution disarms it, later demand rearms it, concurrent demand fails, and disposal clears the active arm. Providers translate timeout reasons into seam-specific results. `timeoutOf(signal, code)` scopes classification so an outer nested deadline is treated as upstream cancellation rather than the inner capability's timeout.
+`deadline` fuses an upstream signal with a one-shot timer through `AbortSignal.any`, adds a typed `TimeoutReason`, and exposes disposable timer cleanup. Non-positive timeouts are an internal no-timeout sentinel for backend-owned background work; external hints pass through `clampTimeout` and must be positive and finite. Without a timer or upstream signal, the function returns a never-aborting signal with the same disposal shape. `idleWatchdog` instead requires a positive finite interval, keeps one stable fused signal for the entire stream, and arms its timer only while one iterator `next()` is outstanding; resolution disarms it, later demand rearms it, and `pulse()` rearms that same outstanding demand after out-of-band transport activity. A pulse outside outstanding demand or after disposal is a no-op; concurrent demand fails, and disposal clears the active arm. Providers translate timeout reasons into seam-specific results. `timeoutOf(signal, code)` scopes classification so an outer nested deadline is treated as upstream cancellation rather than the inner capability's timeout.
 
 ### The division of labor
 
@@ -79,7 +80,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 |---|---|
 | Validate request hint and clamp default/max | `dsh-timeout` (`clampTimeout`) — pure arithmetic plus the shared positive-finite request contract |
 | Arm one-shot timer, abort on deadline, carry reason, fuse with upstream cancel | `dsh-timeout` (`deadline`) |
-| Arm and rearm only around outstanding iterator demand | `dsh-timeout` (`idleWatchdog`) |
+| Arm and rearm only around outstanding iterator demand, including out-of-band activity | `dsh-timeout` (`idleWatchdog`) |
 | Clear the timer | `dsh-timeout` (`[Symbol.dispose]` on either primitive) |
 | Classify the first abort reason after abort | `dsh-timeout` (`timeoutOf`) |
 | **Actually terminate the work** | the capability's implementation |
@@ -92,7 +93,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 
 - **web_fetch** — the tool stays validate-and-forward; the provider's hand-rolled controller + `setTimeout` + manual listener + `finally` + `signal.reason` recovery is replaced by provider-owned `deadline`/`timeoutOf`. A pre-aborted upstream signal still throws `WEB_ABORTED` up front; otherwise `fetch` runs against the fused `d.signal`, and `translateAbortOrNetwork` classifies a thrown error by the signal (`timeoutOf` → `WEB_FETCH_TIMEOUT`, else aborted → `WEB_ABORTED`, else network → `WEB_PROVIDER_ERROR`). The public error-code contract is unchanged, and `TimeoutReason` never crosses the web seam as the public error.
 - **bash** — `resolve()` clamps the request into an explicit spec. Foreground `run()` creates the deadline and passes its signal to process execution, whose existing abort listener performs the process-group kill. The executor classifies the first abort as timeout or cancellation. Background starts remain timeout-free and forward only upstream cancellation.
-- **LLM adapters** — `dsh-llm-deepseek` and `dsh-llm-pi-ai` wrap actual transport iteration with `idleWatchdog`. The five-minute configured interval covers only outstanding provider demand, not time the downstream consumer spends between chunks. The stable signal reaches `fetch` or the SDK for the whole call, so timeout closes the underlying request and maps to `TIMEOUT`, while an earlier caller abort maps to `ABORTED`.
+- **LLM adapters** — `dsh-llm-deepseek` and `dsh-llm-pi-ai` wrap actual transport iteration with `idleWatchdog`. The five-minute configured interval covers only outstanding provider demand, not time the downstream consumer spends between chunks. The direct DeepSeek adapter also pulses that outstanding demand when its SSE parser observes a comment, without yielding the comment as a `StreamChunk` or writing it to the session log. The pi-ai SDK does not expose comment activity to its adapter, so that path can rearm only when the SDK yields. The stable signal reaches `fetch` or the SDK for the whole call, so timeout closes the underlying request and maps to `TIMEOUT`, while an earlier caller abort maps to `ABORTED`.
 
 ## Consequences
 
@@ -100,7 +101,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 - `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
-- Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
+- Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. Adapters that can observe out-of-band transport activity may pulse an outstanding demand; suppressed activity remains invisible to the watchdog. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
 
 Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; future ripgrep-backed fs discovery tools can consume the same provider-owned deadline shape once they exist; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index c47e6d4e6e..c6992ba546 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -57,10 +57,11 @@ export function deadline(
 export interface IdleWatchdog {
   readonly signal: AbortSignal
   next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  pulse(): void
   [Symbol.dispose](): void
 }
 
-/** Arm only while one iterator `next()` is outstanding, then rearm on later demand. */
+/** Arm only while one iterator `next()` is outstanding; rearm on later demand or out-of-band activity. */
 export function idleWatchdog(
   upstream: AbortSignal | undefined,
   timeoutMs: number,
@@ -71,7 +72,7 @@ export function idleWatchdog(
 export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): TimeoutReason | undefined
 ```
 
-`deadline` 通过 `AbortSignal.any` 将上游信号与一次性定时器融合，附加一个类型化的 `TimeoutReason`，并暴露可 dispose（资源释放）的定时器清理。非正数超时是内部的「无超时」哨兵，用于后端拥有的后台任务；外部提示经过 `clampTimeout`，必须为正有限值。既无定时器也无上游信号时，函数返回一个永不中止的信号，具有相同的 disposal 形状。`idleWatchdog` 则要求正有限的间隔，在整个流期间保持一个稳定的融合信号，并且只在一个迭代器 `next()` 尚未结算时启动定时器；结算会解除定时器，后续 demand 会重新启动，并发 demand 会失败，dispose 会清除当前 arm。提供方将超时原因转译为 seam 特定的结果。`timeoutOf(signal, code)` 限定分类范围，使外层嵌套的 deadline 被视为上游取消而非内层能力自身的超时。
+`deadline` 通过 `AbortSignal.any` 将上游信号与一次性定时器融合，附加一个类型化的 `TimeoutReason`，并暴露可 dispose（资源释放）的定时器清理。非正数超时是内部的「无超时」哨兵，用于后端拥有的后台任务；外部提示经过 `clampTimeout`，必须为正有限值。既无定时器也无上游信号时，函数返回一个永不中止的信号，具有相同的 disposal 形状。`idleWatchdog` 则要求正有限的间隔，在整个流期间保持一个稳定的融合信号，并且只在一个迭代器 `next()` 尚未结算时启动定时器；结算会解除定时器，后续 demand 会重新启动，带外传输活动发生后，`pulse()` 则会为同一个尚未结算的 demand 重新启动定时器。若没有尚未结算的 demand，或已经 dispose，pulse 不执行任何操作；并发 demand 会失败，dispose 会清除当前 arm。提供方将超时原因转译为 seam 特定的结果。`timeoutOf(signal, code)` 限定分类范围，使外层嵌套的 deadline 被视为上游取消而非内层能力自身的超时。
 
 ### 职责划分
 
@@ -79,7 +80,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 |---|---|
 | 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求约定 |
 | 启动一次性定时器、到期中止、携带 reason、与上游取消融合 | `dsh-timeout`（`deadline`） |
-| 仅围绕未结算的迭代器 demand 启动和重启 | `dsh-timeout`（`idleWatchdog`） |
+| 仅围绕未结算的迭代器 demand 启动和重启，带外活动也会触发重启 | `dsh-timeout`（`idleWatchdog`） |
 | 清除定时器 | `dsh-timeout`（任一原语的 `[Symbol.dispose]`） |
 | 中止后对首个 abort reason 进行分类 | `dsh-timeout`（`timeoutOf`） |
 | **实际终止工作** | 各能力的实现 |
@@ -92,7 +93,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 - **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码约定不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。
 - **bash**：`resolve()` 将请求钳位为显式规格。前台 `run()` 创建 deadline 并将其信号传给进程执行，后者既有的 abort 监听器执行进程组 kill。执行器将首个 abort 分类为超时或取消。后台启动保持无超时，仅转发上游取消。
-- **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。
+- **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。DeepSeek 直连适配器还会在其 SSE（Server-Sent Events）解析器观察到注释时，对该项尚未结算的 demand 调用 `pulse()`；该注释既不会作为 `StreamChunk` 产出，也不会写入会话日志。pi-ai SDK 不会向其适配器暴露注释活动，因此该路径只能在 SDK 产出值时重新启动定时器。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。
 
 ## 后果
 
@@ -100,7 +101,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
-- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
+- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。能够观察到带外传输活动的适配器可以对尚未结算的 demand 调用 `pulse()`；被屏蔽的活动对 watchdog 仍不可见。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
 
 以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在实现后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
 

From 996ff7a4409e92b26471507395937344bf22c847 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:14:14 +0800
Subject: [PATCH 213/262] test: refresh translation prompt snapshot

---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index ded84487bf..0bd65e93e4 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, validates staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint fixes with one bounded retry, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件，并通过一次有界重试应用 Oxlint 修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 9704749b0139cc539945990a2a00f36d49b1d3ef Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:35:02 +0800
Subject: [PATCH 214/262] docs: replace vague provenance prose with recorded
 facts

---
 .../2026-06-18-session-surface.i18n.yaml      |  4 +--
 .../2026-06-18-session-surface.md             | 10 +++---
 .../2026-06-18-session-surface.zh.md          | 10 +++---
 ...-21-bounded-llm-request-recovery.i18n.yaml |  4 +--
 ...2026-06-21-bounded-llm-request-recovery.md |  2 +-
 ...6-06-21-bounded-llm-request-recovery.zh.md |  2 +-
 ...bles-and-tool-guidance-ownership.i18n.yaml |  4 +--
 ...t-variables-and-tool-guidance-ownership.md |  2 +-
 ...ariables-and-tool-guidance-ownership.zh.md |  2 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |  4 +--
 .../2026-07-05-reconstructable-requests.md    |  4 +--
 .../2026-07-05-reconstructable-requests.zh.md |  4 +--
 ...n-pressure-and-overflow-recovery.i18n.yaml |  4 +--
 ...mpaction-pressure-and-overflow-recovery.md |  2 +-
 ...ction-pressure-and-overflow-recovery.zh.md |  2 +-
 ...-14-provider-routed-llm-adapters.i18n.yaml |  4 +--
 ...2026-07-14-provider-routed-llm-adapters.md | 16 ++++-----
 ...6-07-14-provider-routed-llm-adapters.zh.md | 16 ++++-----
 ...07-15-replay-token-meter-service.i18n.yaml |  4 +--
 .../2026-07-15-replay-token-meter-service.md  |  8 ++---
 ...026-07-15-replay-token-meter-service.zh.md |  8 ++---
 ...-package-owned-invariant-service.i18n.yaml |  4 +--
 ...6-07-19-package-owned-invariant-service.md |  2 +-
 ...7-19-package-owned-invariant-service.zh.md |  2 +-
 ...0-canonical-tool-output-contract.i18n.yaml |  4 +--
 ...26-07-20-canonical-tool-output-contract.md |  2 +-
 ...07-20-canonical-tool-output-contract.zh.md |  2 +-
 ...send-and-coalesced-user-messages.i18n.yaml |  4 +--
 ...nified-send-and-coalesced-user-messages.md |  4 +--
 ...ied-send-and-coalesced-user-messages.zh.md |  4 +--
 ...xt-injection-from-turn-execution.i18n.yaml |  4 +--
 ...e-context-injection-from-turn-execution.md |  6 ++--
 ...ontext-injection-from-turn-execution.zh.md |  6 ++--
 ...-26-packed-chunk-rows-by-default.i18n.yaml |  4 +--
 ...2026-07-26-packed-chunk-rows-by-default.md |  2 +-
 ...6-07-26-packed-chunk-rows-by-default.zh.md |  2 +-
 ...ntified-immutable-message-values.i18n.yaml |  4 +--
 ...-28-identified-immutable-message-values.md |  6 ++--
 ...-identified-immutable-message-values.zh.md |  6 ++--
 ...-29-terminal-llm-stream-failures.i18n.yaml |  4 +--
 ...2026-07-29-terminal-llm-stream-failures.md |  4 +--
 ...6-07-29-terminal-llm-stream-failures.zh.md |  4 +--
 ...adapter-owned-max-token-defaults.i18n.yaml |  4 +--
 ...-07-30-adapter-owned-max-token-defaults.md |  4 +--
 ...-30-adapter-owned-max-token-defaults.zh.md |  4 +--
 ...ssion-persistence-write-batching.i18n.yaml |  4 +--
 ...nded-session-persistence-write-batching.md |  4 +--
 ...d-session-persistence-write-batching.zh.md |  4 +--
 ...ad-pre-identity-session-messages.i18n.yaml |  4 +--
 ...7-28-load-pre-identity-session-messages.md |  2 +-
 ...8-load-pre-identity-session-messages.zh.md |  2 +-
 ...9-human-transcript-append-origin.i18n.yaml |  4 +--
 ...26-07-29-human-transcript-append-origin.md |  6 ++--
 ...07-29-human-transcript-append-origin.zh.md |  6 ++--
 ...cky-composer-conversation-scroll.i18n.yaml |  2 +-
 ...-29-sticky-composer-conversation-scroll.md |  2 +-
 ...ranscript-log-ordered-projection.i18n.yaml |  4 +--
 ...0-web-transcript-log-ordered-projection.md |  2 +-
 ...eb-transcript-log-ordered-projection.zh.md |  2 +-
 ...-04-load-pre-react-loop-sessions.i18n.yaml |  4 +--
 ...2026-08-04-load-pre-react-loop-sessions.md |  2 +-
 ...6-08-04-load-pre-react-loop-sessions.zh.md |  2 +-
 ...ontext-meter-blind-to-compaction.i18n.yaml |  4 +--
 ...08-05-context-meter-blind-to-compaction.md |  2 +-
 ...05-context-meter-blind-to-compaction.zh.md |  2 +-
 ...-attribution-observed-top-ledger.i18n.yaml |  2 +-
 ...-scroll-attribution-observed-top-ledger.md |  4 +--
 ...06-18-compaction-capability-seam.i18n.yaml |  4 +--
 .../2026-06-18-compaction-capability-seam.md  | 10 +++---
 ...026-06-18-compaction-capability-seam.zh.md | 10 +++---
 .../feature/2026-07-06-sandbox.i18n.yaml      |  4 +--
 .../implemented/feature/2026-07-06-sandbox.md |  4 +--
 .../feature/2026-07-06-sandbox.zh.md          |  4 +--
 ...-self-referential-cordis-toolset.i18n.yaml |  4 +--
 ...6-07-08-self-referential-cordis-toolset.md |  2 +-
 ...7-08-self-referential-cordis-toolset.zh.md |  2 +-
 ...2026-07-13-session-query-tracing.i18n.yaml |  4 +--
 .../2026-07-13-session-query-tracing.md       | 12 +++----
 .../2026-07-13-session-query-tracing.zh.md    | 12 +++----
 .../2026-07-16-harness-level-loop.i18n.yaml   |  4 +--
 .../feature/2026-07-16-harness-level-loop.md  |  6 ++--
 .../2026-07-16-harness-level-loop.zh.md       |  6 ++--
 ...26-07-19-model-facing-goal-tools.i18n.yaml |  4 +--
 .../2026-07-19-model-facing-goal-tools.md     |  6 ++--
 .../2026-07-19-model-facing-goal-tools.zh.md  |  6 ++--
 ...6-07-21-cross-session-references.i18n.yaml |  4 +--
 .../2026-07-21-cross-session-references.md    |  2 +-
 .../2026-07-21-cross-session-references.zh.md |  2 +-
 ...-07-21-log-backed-session-titles.i18n.yaml |  4 +--
 .../2026-07-21-log-backed-session-titles.md   |  6 ++--
 ...2026-07-21-log-backed-session-titles.zh.md |  6 ++--
 ...model-facing-session-query-tools.i18n.yaml |  4 +--
 ...-07-24-model-facing-session-query-tools.md |  2 +-
 ...-24-model-facing-session-query-tools.zh.md |  2 +-
 ...-27-trajectory-inspection-ledger.i18n.yaml |  4 +--
 ...2026-07-27-trajectory-inspection-ledger.md |  4 +--
 ...6-07-27-trajectory-inspection-ledger.zh.md |  4 +--
 ...-workspace-registration-deletion.i18n.yaml |  4 +--
 ...6-07-27-workspace-registration-deletion.md |  4 +--
 ...7-27-workspace-registration-deletion.zh.md |  4 +--
 ...ntinuable-subagent-conversations.i18n.yaml |  4 +--
 ...7-28-continuable-subagent-conversations.md | 20 +++++------
 ...8-continuable-subagent-conversations.zh.md | 18 +++++-----
 ...continuable-subagent-report-tool.i18n.yaml |  4 +--
 ...-07-30-continuable-subagent-report-tool.md |  6 ++--
 ...-30-continuable-subagent-report-tool.zh.md |  6 ++--
 ...6-07-30-queued-manual-compaction.i18n.yaml |  4 +--
 .../2026-07-30-queued-manual-compaction.md    |  4 +--
 .../2026-07-30-queued-manual-compaction.zh.md |  4 +--
 ...b-context-source-and-steer-marks.i18n.yaml |  4 +--
 ...8-04-web-context-source-and-steer-marks.md | 10 +++---
 ...4-web-context-source-and-steer-marks.zh.md |  8 ++---
 ...26-08-05-context-form-vocabulary.i18n.yaml |  4 +--
 .../2026-08-05-context-form-vocabulary.md     | 12 +++----
 .../2026-08-05-context-form-vocabulary.zh.md  | 10 +++---
 ...-20-core-data-structures-catalog.i18n.yaml |  4 +--
 ...2026-06-20-core-data-structures-catalog.md |  4 +--
 ...6-06-20-core-data-structures-catalog.zh.md |  4 +--
 ...26-07-27-worktree-local-lefthook.i18n.yaml |  4 +--
 .../2026-07-27-worktree-local-lefthook.md     |  2 +-
 .../2026-07-27-worktree-local-lefthook.zh.md  |  2 +-
 ...6-in-repository-landlock-release.i18n.yaml |  4 +--
 ...26-08-06-in-repository-landlock-release.md |  4 +--
 ...08-06-in-repository-landlock-release.zh.md |  4 +--
 ...08-08-browser-gif-evidence-chain.i18n.yaml |  4 +--
 .../2026-08-08-browser-gif-evidence-chain.md  |  8 ++---
 ...026-08-08-browser-gif-evidence-chain.zh.md |  8 ++---
 ...08-unified-github-label-taxonomy.i18n.yaml |  4 +--
 ...026-08-08-unified-github-label-taxonomy.md |  4 +--
 ...-08-08-unified-github-label-taxonomy.zh.md |  4 +--
 ...-names-actors-and-recorded-facts.i18n.yaml |  6 ++++
 ...e-prose-names-actors-and-recorded-facts.md | 33 ++++++++++++++++++
 ...rose-names-actors-and-recorded-facts.zh.md | 33 ++++++++++++++++++
 ...plify-session-log-representation.i18n.yaml |  4 +--
 ...-12-simplify-session-log-representation.md |  2 +-
 ...-simplify-session-log-representation.zh.md |  2 +-
 ...t-invariants-from-shipped-config.i18n.yaml |  4 +--
 ...-03-omit-invariants-from-shipped-config.md |  2 +-
 ...-omit-invariants-from-shipped-config.zh.md |  2 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |  4 +--
 .../2026-07-06-recallable-compaction.md       |  8 ++---
 .../2026-07-06-recallable-compaction.zh.md    |  8 ++---
 ...-07-08-interactive-side-sessions.i18n.yaml |  4 +--
 .../2026-07-08-interactive-side-sessions.md   |  4 +--
 ...2026-07-08-interactive-side-sessions.zh.md |  4 +--
 ...3-human-review-skill-maintenance.i18n.yaml |  4 +--
 ...26-07-13-human-review-skill-maintenance.md | 16 ++++-----
 ...07-13-human-review-skill-maintenance.zh.md | 16 ++++-----
 ...ndstrip-for-windows-sandbox-rung.i18n.yaml |  4 +--
 ...uate-landstrip-for-windows-sandbox-rung.md |  8 ++---
 ...e-landstrip-for-windows-sandbox-rung.zh.md |  8 ++---
 ...19-fold-compaction-package-split.i18n.yaml |  4 +--
 ...026-07-19-fold-compaction-package-split.md |  2 +-
 ...-07-19-fold-compaction-package-split.zh.md |  2 +-
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |  4 +--
 ...-dependency-swaps-rejected-by-nih-audit.md |  2 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |  2 +-
 .agents/skills/record-browser-gif/SKILL.md    | 12 +++----
 apps/cli/reference/README.i18n.yaml           |  4 +--
 apps/cli/reference/README.md                  |  2 +-
 apps/cli/reference/README.zh.md               |  2 +-
 apps/cli/src/dump-config.ts                   |  4 +--
 apps/cli/tests/built-bin.e2e.ts               |  2 +-
 apps/web/tests/seeded-history.e2e.ts          |  2 +-
 docs/AGENTS.md                                |  2 +-
 docs/agent-lifecycle.md                       |  2 +-
 docs/architecture.i18n.yaml                   |  4 +--
 docs/architecture.md                          |  6 ++--
 docs/architecture.zh.md                       |  6 ++--
 docs/config-catalog.md                        |  2 +-
 .../maintaining-dsh-code-review.i18n.yaml     |  4 +--
 docs/cookbook/maintaining-dsh-code-review.md  |  4 +--
 .../maintaining-dsh-code-review.zh.md         |  4 +--
 docs/persistence-catalog.md                   |  8 ++---
 docs/subsystems/README.i18n.yaml              |  4 +--
 docs/subsystems/README.md                     |  2 +-
 docs/subsystems/README.zh.md                  |  2 +-
 docs/subsystems/compaction.i18n.yaml          |  4 +--
 docs/subsystems/compaction.md                 | 10 +++---
 docs/subsystems/compaction.zh.md              | 10 +++---
 docs/subsystems/core.i18n.yaml                |  4 +--
 docs/subsystems/core.md                       | 14 ++++----
 docs/subsystems/core.zh.md                    | 14 ++++----
 docs/subsystems/llm-streaming.i18n.yaml       |  4 +--
 docs/subsystems/llm-streaming.md              | 18 +++++-----
 docs/subsystems/llm-streaming.zh.md           | 18 +++++-----
 docs/subsystems/session-query.i18n.yaml       |  4 +--
 docs/subsystems/session-query.md              | 14 ++++----
 docs/subsystems/session-query.zh.md           | 14 ++++----
 docs/subsystems/session-title.i18n.yaml       |  4 +--
 docs/subsystems/session-title.md              | 10 +++---
 docs/subsystems/session-title.zh.md           | 10 +++---
 docs/subsystems/session.i18n.yaml             |  4 +--
 docs/subsystems/session.md                    | 34 +++++++++----------
 docs/subsystems/session.zh.md                 | 34 +++++++++----------
 docs/subsystems/spill.i18n.yaml               |  4 +--
 docs/subsystems/spill.md                      |  6 ++--
 docs/subsystems/spill.zh.md                   |  6 ++--
 docs/subsystems/subagent.i18n.yaml            |  4 +--
 docs/subsystems/subagent.md                   |  6 ++--
 docs/subsystems/subagent.zh.md                |  6 ++--
 docs/tool-catalog.md                          |  2 +-
 .../headless-agent/tests/compaction.e2e.ts    |  2 +-
 native/landlock-run/docs/architecture.md      |  2 +-
 native/landlock-run/scripts/build.ts          |  2 +-
 .../scripts/verify-launcher-binary.mjs        |  5 ++-
 packages/bash/bash-sandbox/README.i18n.yaml   |  4 +--
 packages/bash/bash-sandbox/README.md          |  4 +--
 packages/bash/bash-sandbox/README.zh.md       |  4 +--
 packages/bash/bash-sandbox/src/helpers.ts     |  2 +-
 packages/bash/bash-sandbox/src/index.ts       |  2 +-
 .../tests/partial-landlock.spec.ts            |  2 +-
 .../bash/bash-sandbox/tests/sandbox.spec.ts   |  4 +--
 packages/boot/app-boot/README.i18n.yaml       |  4 +--
 packages/boot/app-boot/README.md              |  2 +-
 packages/boot/app-boot/README.zh.md           |  2 +-
 packages/boot/app-boot/src/index.ts           | 16 ++++-----
 .../boot/app-boot/tests/config-dump.spec.ts   | 10 +++---
 packages/client/runtime/README.i18n.yaml      |  4 +--
 packages/client/runtime/README.md             |  4 +--
 packages/client/runtime/README.zh.md          |  4 +--
 .../src/client/sessions/context-provenance.ts |  2 +-
 .../src/client/sessions/conversation.ts       | 10 +++---
 .../runtime/src/client/sessions/session.ts    |  2 +-
 .../src/client/sessions/transcript-adapter.ts |  6 ++--
 packages/client/runtime/tests/event-script.ts |  2 +-
 .../client/runtime/tests/history-fold.spec.ts |  2 +-
 .../runtime/tests/transcript-adapter.spec.ts  | 12 +++----
 .../client/ui-conversation/README.i18n.yaml   |  4 +--
 packages/client/ui-conversation/README.md     |  4 +--
 packages/client/ui-conversation/README.zh.md  |  4 +--
 .../src/client/chat/CompactionItem.tsx        |  2 +-
 .../src/client/chat/ContextBody.module.css    |  2 +-
 .../src/client/chat/ContextBody.tsx           |  8 ++---
 .../src/client/chat/ContextInjectionRow.tsx   |  2 +-
 .../tests/chat-branch-tails.spec.tsx          |  6 ++--
 .../tests/markdown-dom-parity.spec.tsx        |  2 +-
 .../src/client/context-branches.ts            |  4 +--
 .../src/client/trajectory-record.ts           |  2 +-
 .../compact/compact-basic/README.i18n.yaml    |  4 +--
 packages/compact/compact-basic/README.md      |  6 ++--
 packages/compact/compact-basic/README.zh.md   |  6 ++--
 packages/compact/compact-basic/src/index.ts   |  4 +--
 packages/compact/compact-basic/src/region.ts  |  2 +-
 .../compact/compact-basic/src/summarizer.ts   |  4 +--
 .../compact-basic/tests/compact-basic.spec.ts |  2 +-
 .../tests/manual-compact.spec.ts              |  8 ++---
 .../compact-tool-result-prune/src/index.ts    |  2 +-
 .../compact-tool-result-prune/src/types.ts    |  2 +-
 .../tests/tool-result-prune.spec.ts           |  2 +-
 packages/compact/compact/README.i18n.yaml     |  4 +--
 packages/compact/compact/README.md            |  2 +-
 packages/compact/compact/README.zh.md         |  2 +-
 packages/compact/compact/src/types.ts         |  4 +--
 .../context/session-reference/src/types.ts    |  2 +-
 .../context/workspace-context/src/state.ts    |  2 +-
 packages/core/agent-loop/README.i18n.yaml     |  4 +--
 packages/core/agent-loop/README.md            |  4 +--
 packages/core/agent-loop/README.zh.md         |  4 +--
 packages/core/agent-loop/src/tool-calls.ts    |  4 +--
 .../tests/contract-regressions.spec.ts        |  2 +-
 packages/core/agent/README.i18n.yaml          |  4 +--
 packages/core/agent/README.md                 |  2 +-
 packages/core/agent/README.zh.md              |  2 +-
 packages/core/agent/src/types.ts              |  8 ++---
 packages/core/session/README.i18n.yaml        |  4 +--
 packages/core/session/README.md               | 12 +++----
 packages/core/session/README.zh.md            | 12 +++----
 packages/core/session/src/index.ts            |  8 ++---
 packages/core/session/src/invariant.ts        |  2 +-
 packages/core/session/src/repair.ts           |  4 +--
 packages/core/session/src/surface.ts          |  4 +--
 packages/core/session/src/types.ts            | 10 +++---
 .../tests/gen-persistence-catalog.spec.ts     |  4 +--
 packages/core/session/tests/session.spec.ts   |  2 +-
 packages/core/session/tests/surface.spec.ts   |  8 ++---
 packages/core/tools/README.i18n.yaml          |  4 +--
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/README.zh.md              |  2 +-
 packages/fs/fs-local/tests/fsio.spec.ts       |  2 +-
 packages/goal/tool-goal/README.i18n.yaml      |  4 +--
 packages/goal/tool-goal/README.md             |  2 +-
 packages/goal/tool-goal/README.zh.md          |  2 +-
 .../tests/repeat-tool-guard.spec.ts           |  2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |  4 +--
 packages/hooks/hook-protocol/README.md        |  2 +-
 packages/hooks/hook-protocol/README.zh.md     |  2 +-
 packages/hooks/hook-protocol/src/events.ts    |  2 +-
 packages/hooks/hook-protocol/src/invariant.ts |  4 +--
 packages/hooks/hook-protocol/src/types.ts     |  4 +--
 .../hook-protocol/tests/invariant.spec.ts     |  2 +-
 packages/hooks/hooks-claude/src/index.ts      |  2 +-
 packages/hooks/hooks-claude/src/invariant.ts  |  2 +-
 packages/hooks/hooks-codex/src/index.ts       |  4 +--
 packages/hooks/hooks-codex/src/invariant.ts   |  2 +-
 packages/host/apiproxy/README.i18n.yaml       |  4 +--
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 packages/host/apiproxy/src/api-proxy.ts       |  4 +--
 packages/host/apiproxy/src/api/sessions.ts    |  2 +-
 .../apiproxy/tests/api-proxy-search.spec.ts   |  2 +-
 .../apiproxy/tests/api-proxy-view.spec.ts     |  6 ++--
 packages/interaction/commands/src/index.ts    |  2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |  4 +--
 packages/llm/llm-pi-ai/README.md              |  4 +--
 packages/llm/llm-pi-ai/README.zh.md           |  4 +--
 packages/llm/llm-pi-ai/tests/convert.spec.ts  |  2 +-
 packages/llm/llm/README.i18n.yaml             |  4 +--
 packages/llm/llm/README.md                    |  6 ++--
 packages/llm/llm/README.zh.md                 |  6 ++--
 packages/llm/llm/src/call-config.ts           |  2 +-
 packages/llm/llm/src/message.ts               |  8 ++---
 packages/llm/llm/tests/message.spec.ts        |  2 +-
 packages/llm/llm/tests/service.spec.ts        |  2 +-
 packages/llm/token-meter/README.i18n.yaml     |  4 +--
 packages/llm/token-meter/README.md            |  6 ++--
 packages/llm/token-meter/README.zh.md         |  6 ++--
 packages/llm/token-meter/src/index.ts         |  6 ++--
 .../llm/token-meter/tests/token-meter.spec.ts |  6 ++--
 packages/sandbox/sandbox-local/src/index.ts   |  2 +-
 packages/scaffold/server/src/server.ts        |  2 +-
 packages/scaffold/server/tests/server.spec.ts |  2 +-
 .../tool-cordis/src/api-catalog.ts            |  8 ++---
 .../session-query/README.i18n.yaml            |  4 +--
 .../session-query/session-query/README.md     |  6 ++--
 .../session-query/session-query/README.zh.md  |  6 ++--
 .../session-query/session-query/src/index.ts  |  4 +--
 .../session-query/src/tracing.ts              |  2 +-
 .../session-query/session-query/src/types.ts  |  8 ++---
 .../session-query/tests/tracing.spec.ts       |  4 +--
 .../tool-session-query/src/index.ts           |  2 +-
 .../tool-session-query/src/presentation.ts    |  2 +-
 .../session-persistence/README.i18n.yaml      |  4 +--
 .../session/session-persistence/README.md     |  2 +-
 .../session/session-persistence/README.zh.md  |  2 +-
 .../session-title-llm/README.i18n.yaml        |  4 +--
 packages/session/session-title-llm/README.md  |  2 +-
 .../session/session-title-llm/README.zh.md    |  2 +-
 .../session/session-title-llm/src/index.ts    |  2 +-
 .../session-title-llm/src/invariant.ts        |  2 +-
 .../session/session-title/README.i18n.yaml    |  4 +--
 packages/session/session-title/README.md      |  2 +-
 packages/session/session-title/README.zh.md   |  2 +-
 packages/session/session-title/src/index.ts   | 10 +++---
 .../session/session-title/src/invariant.ts    |  5 +--
 .../session-title/tests/invariant.spec.ts     |  4 +--
 .../tests/service-contracts.spec.ts           | 12 +++----
 packages/settings/settings/README.i18n.yaml   |  4 +--
 packages/settings/settings/README.md          |  2 +-
 packages/settings/settings/README.zh.md       |  2 +-
 packages/skill/tool-skill/src/index.ts        |  2 +-
 packages/spill/spill/README.i18n.yaml         |  4 +--
 packages/spill/spill/README.md                |  2 +-
 packages/spill/spill/README.zh.md             |  2 +-
 packages/spill/spill/src/index.ts             |  2 +-
 packages/spill/spill/src/types.ts             |  2 +-
 packages/subagent/subagent/README.i18n.yaml   |  4 +--
 packages/subagent/subagent/README.md          |  8 ++---
 packages/subagent/subagent/README.zh.md       |  8 ++---
 .../subagent/subagent/src/continuation.ts     |  4 +--
 packages/subagent/subagent/src/index.ts       |  2 +-
 packages/subagent/subagent/src/invariant.ts   |  2 +-
 packages/subagent/subagent/src/types.ts       |  4 +--
 .../subagent/subagent/tests/invariant.spec.ts |  2 +-
 .../tool-subagent-control/README.i18n.yaml    |  4 +--
 .../subagent/tool-subagent-control/README.md  |  2 +-
 .../tool-subagent-control/README.zh.md        |  2 +-
 .../tests/tool-subagent-control.spec.ts       |  2 +-
 .../tool-subagent-report/README.i18n.yaml     |  4 +--
 .../subagent/tool-subagent-report/README.md   |  2 +-
 .../tool-subagent-report/README.zh.md         |  2 +-
 .../tests/tool-subagent-report.spec.ts        |  2 +-
 packages/support/invariants/README.i18n.yaml  |  4 +--
 packages/support/invariants/README.md         |  2 +-
 packages/support/invariants/README.zh.md      |  2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  2 +-
 packages/util/environment/package.json        |  2 +-
 packages/util/environment/src/index.ts        |  4 +--
 packages/workspace/workspace/src/index.ts     |  4 +--
 scripts/gen-doc-graphs.ts                     |  2 +-
 380 files changed, 946 insertions(+), 874 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index ce26042716..b400a7b6c7 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: 1bb3baac5e9bea3f657cbd3be2623223bda78ce2
-2026-06-18-session-surface.zh.md: b967ad467e58ed4f4b4009fe4746f1b8b6b22f25
+2026-06-18-session-surface.md: 3a033960e7cbf577c69c1df9940e064ef34163d3
+2026-06-18-session-surface.zh.md: 5c1348595589e8b69b0fe4a679f2536a83ef3142
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 1bb3baac5e..3a033960e7 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-18-session-surface.zh.md)
 
 ## Problem
 
-The event log is authoritative, but history manipulation had no durable shared mechanism. Plugins such as compaction would otherwise rewrite derived requests through order-sensitive listeners, leave no provenance, and require repeated changes to `deriveMessages()`.
+The event log is authoritative, but history manipulation had no durable shared mechanism. Without one, plugins such as compaction would rewrite derived requests through order-sensitive listeners without recording which events each replacement used. Every new history manipulation would also require changes to `deriveMessages()`.
 
 ## Decision
 
@@ -16,7 +16,7 @@ Add a **surface** — a derived, cached order of event sequences (the subset of
 
 Every `SessionEvent` gains two optional fields (structural metadata, like `seq`/`time`):
 
-- **`sourceEventSeqs?: number[]`** — seq numbers of events that are provenance sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means legacy or otherwise unrecorded provenance. Other surface events require a non-empty list when the field is present. Provenance is a core design principle; without it, the replace-range operation cannot be validated on replay.
+- **`sourceEventSeqs?: number[]`** — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means a legacy or foreign event did not record the stream. Other surface events require a non-empty list when the field is present. Without these cited seqs, replay cannot validate that a replace-range operation names every event it removed.
 - **`surfaceOp?: SurfaceOp`** — how this event entered the surface. Absent for non-surface events.
 
 ### SurfaceOp: two operations
@@ -49,7 +49,7 @@ The `repair.ts` module synthesizes `tool/result` closers for orphaned tool calls
 
 ### Invariants
 
-`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: only `assistant/message` may use an empty provenance list; references are unique, earlier, and known; replacement endpoints exist in surface order; and provenance covers every shadowed node. These are single-record acceptance and storage-projection rules, not optional invariant-service contributions.
+`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: only `assistant/message` may use an empty source-event list; references are unique, earlier, and known; replacement endpoints exist in surface order; and `sourceEventSeqs` covers every shadowed node. These are single-record acceptance and storage-projection rules, not optional invariant-service contributions.
 
 Every surface-eligible event must carry `surfaceOp` or it would disappear from derived history. Typed `append` overloads enforce this for literal event types; runtime checks in `append` and the seed constructor cover widened unions and loaded logs. Invalid seeds are rejected rather than upgraded under the pre-release format policy.
 
@@ -63,11 +63,11 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 ## Consequences
 
 - **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array for candidate acceptance and live projection; `SessionSurface` is its readonly public view. `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants).
-- **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Chunk seqs are collected for `assistant/message` provenance; `tool/call` seqs are captured for `tool/result` provenance.
+- **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Each `assistant/message` cites its chunk seqs; each `tool/result` cites its `tool/call` seq.
 - **`packages/session/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
 - **`packages/session/session-persistence-jsonl`**: No changes required.
 - **`packages/session/session-persistence`**: Abstract interface unchanged.
 
 The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
 
-A `tool/result` replacement may rewrite exactly one current `tool/result` and must preserve every data field except `content`. Session acceptance enforces this rule together with positional range and provenance validation, independent of optional diagnostic plugins.
+A `tool/result` replacement may rewrite exactly one current `tool/result` and must preserve every data field except `content`. Session acceptance enforces this rule together with positional range and cited source-event validation, independent of optional diagnostic plugins.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index b967ad467e..5c13485955 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-事件日志是权威数据源，但历史操纵此前没有持久化的共享机制。如果没有这样的机制，上下文压缩（context compaction）等插件只能通过顺序敏感的监听器改写派生请求，不留溯源信息，且每次新增操纵都要反复修改 `deriveMessages()`。
+事件日志是权威数据源，但历史操纵此前没有持久化的共享机制。如果没有这样的机制，上下文压缩（context compaction）等插件会通过顺序敏感的监听器改写派生请求，却不记录每次替换使用了哪些事件。每次新增历史操纵时，还必须修改 `deriveMessages()`。
 
 ## 决策
 
@@ -16,7 +16,7 @@ Status: implemented
 
 每个 `SessionEvent` 获得两个可选字段（结构性元数据，与 `seq`/`time` 同级）：
 
-- **`sourceEventSeqs?: number[]`**：作为溯源来源的事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段表示旧数据或未记录的溯源。其他 surface 事件一旦出现此字段，就必须是非空列表。溯源是核心设计原则；没有它，replace-range 操作在回放时无法被验证。
+- **`sourceEventSeqs?: number[]`**：被引用为数据来源的早期事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段，表示某个旧事件或外部事件没有记录该流。其他 surface 事件一旦出现此字段，就必须是非空列表。如果没有这些引用的 seq，回放就无法验证 replace-range 操作是否列出了它移除的每个事件。
 - **`surfaceOp?: SurfaceOp`**：该事件如何进入 surface。非 surface 事件不携带此字段。
 
 ### SurfaceOp：两种操作
@@ -49,7 +49,7 @@ export type SurfaceOp =
 
 ### 不变式
 
-`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：只有 `assistant/message` 可以使用空的溯源列表；引用必须唯一、更早且已知；替换端点必须存在于 surface 顺序中；溯源必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则，不是由可选的不变式服务提供的规则。
+`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：只有 `assistant/message` 可以使用空的源事件列表；引用必须唯一、更早且已知；替换端点必须存在于 surface 顺序中；`sourceEventSeqs` 必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则，不是由可选的不变式服务提供的规则。
 
 每个可进入 surface 的事件都必须携带 `surfaceOp`，否则它将从派生历史中消失。类型化的 `append` 重载对字面事件类型强制执行此规则；`append` 和种子构造函数中的运行时检查覆盖宽化联合类型和加载的日志。按照预发布格式策略，无效的种子被拒绝而非升级。
 
@@ -63,11 +63,11 @@ export type SurfaceOp =
 ## 后果
 
 - **`packages/core/session`**：`surface.ts`（`SurfaceManager`）维护一个用于候选接纳和实时投影的有序 seq 数组；`SessionSurface` 是其只读公共视图。`SurfaceOp`/`SurfaceIntent` 与顶层会话事件字段记录条目如何加入它。`append()` 要求 surface 事件携带 `SurfaceIntent`，`deriveMessages()` 以遍历 surface 作为唯一派生路径，`repair.ts` 则发出 surface 感知的闭合事件。种子构造函数拒绝缺少 `surfaceOp` 标记的可进入 surface 的种子事件（见「不变式」一节）。
-- **`packages/core/agent-loop`**：所有涉及 surface 事件的追加操作都传入 surface 选项。收集分片 seq 用于 `assistant/message` 溯源；捕获 `tool/call` seq 用于 `tool/result` 溯源。
+- **`packages/core/agent-loop`**：所有涉及 surface 事件的追加操作都传入 surface 选项。每个 `assistant/message` 都引用产生它的分片 seq；每个 `tool/result` 都引用它的 `tool/call` seq。
 - **`packages/session/session-persistence-sqlite`**：`events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）；`SCHEMA_VERSION` 递增（bump-and-reject，无迁移）。
 - **`packages/session/session-persistence-jsonl`**：无需改动。
 - **`packages/session/session-persistence`**：抽象接口不变。
 
 Surface 是未来历史操纵的基础。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
 
-一次 `tool/result` 替换只能改写当前的一个 `tool/result`，并且必须保留除 `content` 以外的每个数据字段。Session 接纳会与位置范围和溯源校验一起强制这条规则，不依赖可选的诊断插件。
+一次 `tool/result` 替换只能改写当前的一个 `tool/result`，并且必须保留除 `content` 以外的每个数据字段。Session 接纳会与位置范围和引用的源事件校验一起强制这条规则，不依赖可选的诊断插件。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index b8540c3319..dcfcccc3cf 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
-2026-06-21-bounded-llm-request-recovery.md: 587f2d26eee922e91c8797018964f983890eb8ec
-2026-06-21-bounded-llm-request-recovery.zh.md: dfc5e3ab67b62042c37f05199ed39bf47ded0c5d
+2026-06-21-bounded-llm-request-recovery.md: 41f02f977a5fb628d57c162c64f8aaa1c2e6b1c0
+2026-06-21-bounded-llm-request-recovery.zh.md: 3e95865d73e75b8f7ae227ebabe322a21c2b83ae
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
index 587f2d26ee..41f02f977a 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
@@ -115,7 +115,7 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - HMR-during-backoff tests prove disposal unregisters the listener, aborts and awaits its captured callbacks, emits no retry decision after disposal, and leaves no timer or promise alive.
 - Pure unit tests cover transient-code selection, exponential backoff and jitter bounds, valid and over-cap `Retry-After`, exhausted budgets, deterministic timer/random seams, and abort during backoff.
 - Real agent-loop tests cover failure before chunks, partial chunks then failure, thrown and in-band failures, retry to success in a new turn, exhaustion to structured `turn/end.reason`, and composition with `dsh-compact-basic` context-overflow recovery.
-- The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry has distinct provenance.
+- The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry records its own chunk seqs and provider/model route.
 - The plugin-owned `llm/retry` event is non-surface, survives JSONL and SQLite round trips, is ignored by message derivation, and drives TUI and Web retraction plus scheduled-retry rendering. Client tests cover complete wire validation, clock-independent countdown, cancellation versus completed retry labels, and trajectory attribution; keyless UI snapshots cover Web scheduling and success, a real Web composition test covers partial transport failure through recovery, and ACP automation snapshots confirm that a discarded attempt stays off the wire while the recovered reply is emitted.
 - Idle-watchdog tests prove the stable signal is rearmed only while `next()` is outstanding, disarmed during consumer think time and in `finally`, and classified separately from a total-call deadline and an earlier caller abort; adapter tests prove the signal stops the underlying request rather than merely detaching it.
 - Direct `ctx.llm.stream()` callers remain single-attempt and receive the same structured failure facts.
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index dfc5e3ab67..3e95865d73 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -115,7 +115,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - 退避期间执行 HMR 的测试证明：dispose 过程会注销监听器、中止并等待其捕获的回调，dispose 后不发出重试决策，也不留下存活的定时器或 promise。
 - 纯单元测试覆盖暂时性 code 选择、指数退避和抖动边界、有效及超出上限的 `Retry-After`、耗尽的预算、确定性定时器／随机数 seam，以及退避期间中止。
 - 真实 agent-loop 测试覆盖分片前失败、部分分片后失败、抛出及带内失败、在新轮次中重试至成功、耗尽后写入结构化 `turn/end.reason`，以及与 `dsh-compact-basic` 上下文溢出恢复的组合。
-- 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试具有不同的来源信息。
+- 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试会记录自己的分片 seq 和提供方／模型路由。
 - 插件拥有的不进入表层的 `llm/retry` 事件可在 JSONL 和 SQLite 往返后保留，被消息派生忽略，并驱动 TUI 和 Web 撤回及计划重试渲染。客户端测试覆盖完整的 wire 验证、独立于时钟的倒计时、已取消与已完成重试标签的区别以及轨迹归属；无密钥 UI 快照覆盖 Web 的调度与成功，真实 Web 组合测试覆盖部分传输失败直至恢复，ACP 自动化快照确认，被丢弃的尝试不会通过协议发出，而恢复后的回复会正常发出。
 - 空闲看门狗测试证明：只有 `next()` 尚未完成时才会重新布防稳定信号；在消费方思考期间及 `finally` 中会解除布防；它与总调用 deadline 以及更早发生的调用方中止分开分类。适配器测试证明该信号会终止底层请求，而不只是与其脱离。
 - `ctx.llm.stream()` 的直接调用方仍只尝试一次，并收到相同的结构化失败事实。
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index f80e5c3c77..b242af54ee 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.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 .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
-2026-07-05-prompt-variables-and-tool-guidance-ownership.md: a3b5021daf323971308760bde4f97651db8edbda
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 0b84f188e6637d8b1b42ed2e6df3cd7e4061d75d
+2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 199153741a5677e9f7b9bc6510f7a77b9791343e
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 988c128382fd8ff5a8a4742486860d931013ac80
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
index a3b5021daf..199153741a 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
@@ -18,7 +18,7 @@ The assembled system prompt had four defects, all of one family: facts the harne
 
 ## Decision
 
-**One principle: every fact in the prompt has exactly one owner.** The model name and workspace are config/session facts → the harness exposes them as variables and the persona references them. Per-tool semantics and when-to-use → the tool's `description`. Cross-call habits a description cannot carry → the tool package's prompt section. Harness provenance → the static `harness:identity` section. Deployment role and behavior → the deployment's persona.
+**One principle: every fact in the prompt has exactly one owner.** The model name and workspace are config/session facts → the harness exposes them as variables and the persona references them. Per-tool semantics and when-to-use → the tool's `description`. Cross-call habits a description cannot carry → the tool package's prompt section. The product name and SDK identity line → the static `harness:identity` section. Deployment role and behavior → the deployment's persona.
 
 ### Assemble context
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 0b84f188e6..988c128382 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 决策
 
-**一条原则：提示词中的每个事实恰好有一个归属方。** 模型名称和工作区是配置/会话事实 → harness 将它们暴露为变量，persona 引用它们。每个工具的语义和何时使用 → 工具的 `description`。description 无法承载的跨调用习惯 → 包的提示词 section。harness 来源标识 → 静态的 `harness:identity` section。部署角色与行为 → 部署的 persona。
+**一条原则：提示词中的每个事实恰好有一个归属方。** 模型名称和工作区是配置/会话事实 → harness 将它们暴露为变量，persona 引用它们。每个工具的语义和何时使用 → 工具的 `description`。description 无法承载的跨调用习惯 → 包的提示词 section。产品名称和 SDK 身份说明 → 静态的 `harness:identity` section。部署角色与行为 → 部署的 persona。
 
 ### 组装上下文
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 1b5962f672..9acc4ee6f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: ebca9b99cad791159302da9c2bbce9f4df147aab
-2026-07-05-reconstructable-requests.zh.md: e7ed83bbc553e86d53d88e442b0fd8992973c9e7
+2026-07-05-reconstructable-requests.md: 3676e4bc7f6d0272f382b13e178f04b16f18f992
+2026-07-05-reconstructable-requests.zh.md: bcae6b941fb0110aa4e5011685365a5edf7512d3
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index ebca9b99ca..3676e4bc7f 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -30,9 +30,9 @@ Each proposed step first claims its inbox batch and runs `agent/pre-step`. Rejec
 
 **Enforcement.** The `dsh-agent-loop/invariant` companion registers with `ctx.invariants` and, when selected, independently rebuilds each loop request through a fresh `Session`, so the live cache cannot vouch for itself, then compares messages and folded header fields at `llm/stream`. The loop records the exact frozen request through `markAgentLoopRequest()` in `dsh-llm`; the process-local identity lets the companion and other request observers recognize conversation work, while direct one-shots remain excluded regardless of their frozen shape or session id. Correctness depends on sequence-bounded reconstruction rather than listener order. A with-key e2e requires positive cache-read tokens after the first request; per-step usage is the production signal, and a header change or compaction appears as a cache-read drop on the next step.
 
-### The MiniCode shape: adopted, with the provenance arrow inverted
+### The MiniCode shape: adopted, with the event log as the source
 
-Like MiniCode, the conversation advances append-only and resets only when model-visible state changes. Unlike MiniCode, the event log remains the source of truth because it also owns persistence, recovery, boundaries, tool pairing, and provenance. `Session` caches message and header folds derived from that log, making every request independently checkable.
+Like MiniCode, the conversation advances append-only and resets only when model-visible state changes. Unlike MiniCode, the event log remains the source of truth because it also owns persistence, recovery, boundaries, tool pairing, and links from derived events to their inputs. `Session` caches message and header folds derived from that log, making every request independently checkable.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index e7ed83bbc5..bcae6b941f 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -30,9 +30,9 @@ Status: implemented
 
 **强制执行。** `dsh-agent-loop/invariant` 配套插件向 `ctx.invariants` 注册，并在被选用时通过一个全新的 `Session` 独立重建每个循环请求，使活跃缓存无法为自身背书，然后在 `llm/stream` 处比较消息和折叠后的 header 字段。循环通过 `dsh-llm` 的 `markAgentLoopRequest()` 记录精确的冻结请求；这一进程内标识让配套插件和其他请求观察者识别对话工作，而直接的一次性调用无论其冻结形状或会话 id 如何都保持排除。正确性依赖于序列有界的重建，而非监听器顺序。带密钥的 e2e 要求首次请求之后有正值的 cache-read token；逐步骤用量是生产信号，header 变更或压缩表现为下一步骤的 cache-read 下降。
 
-### MiniCode 形态：采纳，但溯源箭头反转
+### MiniCode 形态：采纳，以事件日志为真源
 
-与 MiniCode 相同，对话仅追加推进，仅在模型可见状态变更时重置。与 MiniCode 不同，事件日志仍是真源，因为它同时拥有持久化、恢复、边界、工具配对和溯源。`Session` 缓存从日志推导的消息和 header 折叠结果，使每个请求都可独立检查。
+与 MiniCode 相同，对话仅追加推进，仅在模型可见状态变更时重置。与 MiniCode 不同，事件日志仍是真源，因为它同时拥有持久化、恢复、边界、工具配对，并记录派生事件到其输入事件的关联。`Session` 缓存从日志推导的消息和 header 折叠结果，使每个请求都可独立检查。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index 03acf306b4..2330a5df0c 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.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 .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6fbd5e2c9d57da3f25c72c652ca50eb45b84323c
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 8a480999038cf892842290e3ea3902683d87e431
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6f18d5da014f35b47c40c541ca75ca5ab81499b2
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 7b6ce75b145e96e58a49331e0390f1d3f82200e4
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
index 6fbd5e2c9d..6f18d5da01 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
@@ -32,7 +32,7 @@ If cancellation lands after assistant tool calls are durable but before all call
 
 `CompactService.compactIfNeeded(agent, trigger, signal)` accepts `trigger: 'pressure' | 'context-overflow'`. The interface gains no estimation methods or token types; `ctx.tokenMeter` remains the reusable accounting owner.
 
-For `pressure`, compact-basic resolves the durable provider/model target's adapter-owned capacity and exact-target policy, then applies the resulting threshold and retained-tail budgets to one unified `ctx.tokenMeter.measure()` result. Below pressure it returns without pruning. Once pressure qualifies, optional `ctx.toolResultPrune` rewrites oversized current results and compact-basic remeasures through the same meter; safe pressure skips the model call, while remaining pressure selects and summarizes from the pruned surface. The same singleton meter owns range pricing, provenance, shadowed token counts, and non-shrinking-summary rejection. Common defaults remain threshold ratio `0.8`, retained-history ratio `0.16`, summarization provider/model `''`, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`; optional `modelPolicies` entries override them for an exact provider/model pair.
+For `pressure`, compact-basic resolves the durable provider/model target's adapter-owned capacity and exact-target policy, then applies the resulting threshold and retained-tail budgets to one unified `ctx.tokenMeter.measure()` result. Below pressure it returns without pruning. Once pressure qualifies, optional `ctx.toolResultPrune` rewrites oversized current results and compact-basic remeasures through the same meter; safe pressure skips the model call, while remaining pressure selects and summarizes from the pruned surface. The same singleton meter owns range pricing, cited source-event accounting, shadowed token counts, and non-shrinking-summary rejection. Common defaults remain threshold ratio `0.8`, retained-history ratio `0.16`, summarization provider/model `''`, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`; optional `modelPolicies` entries override them for an exact provider/model pair.
 
 For canonical overflow, compact-basic requires no capacity metadata and bypasses scalar pressure and the normal retained-token budget. It prunes first, then chooses the maximal tool-balanced head range while leaving the newest indivisible unit and attempts one shrinking summary compaction under the same signal when a range exists. The automatic listener snapshots `session.surface.replaceGeneration` and returns `{ kind: 'retry' }` whenever pruning or summarization increases it. This remains true when pruning lands before later summary work throws; cancellation still wins. A backend returning a result without replacement cannot authorize retry, while pruning-only progress can authorize a retry without a `CompactionResult`.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index 8a48099903..7b6ce75b14 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -32,7 +32,7 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 `CompactService.compactIfNeeded(agent, trigger, signal)` 接收 `trigger: 'pressure' | 'context-overflow'`。接口不增加估算方法或 token 类型；`ctx.tokenMeter` 继续作为可复用的核算所有者。
 
-对于 `pressure`，compact-basic 先解析持久提供方/模型目标对应适配器所维护的容量与精确目标策略，再把得到的阈值与保留尾部预算应用到一次统一的 `ctx.tokenMeter.measure()` 结果。未达到压力阈值时直接返回，不执行剪枝。压力达到条件后，可选的 `ctx.toolResultPrune` 会改写当前表层中过大的工具结果，compact-basic 再通过同一个 meter 重新计量；若压力已降至安全水平则跳过模型调用，否则从已剪枝表层选择范围并生成摘要。范围定价、来源、被遮蔽 token 数与非缩小摘要拒绝也由同一个单例 meter 完成。通用默认值保持为阈值比例 `0.8`、保留历史比例 `0.16`、摘要提供方/模型 `''`、`maxTokens: 8192`、`compactionRetries: 1` 与 `auto: true`；可选 `modelPolicies` 项可以按精确提供方/模型组合覆盖这些值。
+对于 `pressure`，compact-basic 先解析持久提供方/模型目标对应适配器所维护的容量与精确目标策略，再把得到的阈值与保留尾部预算应用到一次统一的 `ctx.tokenMeter.measure()` 结果。未达到压力阈值时直接返回，不执行剪枝。压力达到条件后，可选的 `ctx.toolResultPrune` 会改写当前表层中过大的工具结果，compact-basic 再通过同一个 meter 重新计量；若压力已降至安全水平则跳过模型调用，否则从已剪枝表层选择范围并生成摘要。范围定价、引用的源事件计量、被遮蔽 token 数与非缩小摘要拒绝也由同一个单例 meter 完成。通用默认值保持为阈值比例 `0.8`、保留历史比例 `0.16`、摘要提供方/模型 `''`、`maxTokens: 8192`、`compactionRetries: 1` 与 `auto: true`；可选 `modelPolicies` 项可以按精确提供方/模型组合覆盖这些值。
 
 对于规范化溢出，compact-basic 不要求容量元数据，并绕过标量压力与普通保留 token 预算。它先执行剪枝，再在保留最新不可分割单元的同时选择最大的工具配对平衡头部范围；存在范围时，才在同一 signal 下尝试一次缩小摘要压缩。自动监听器先记录 `session.surface.replaceGeneration`，剪枝或摘要让 generation 增加时就返回 `{ kind: 'retry' }`。即使剪枝先落盘而后续摘要工作抛错，这条规则仍然成立；取消依然优先。后端若只返回结果但没有替换表层，不能授权重试；只有剪枝取得进展时，即使没有 `CompactionResult` 也可以授权重试。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index 2d39db2332..6ed066b24a 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.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 .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: 9039334370ba5d71eb71879970c2e572a5b023df
-2026-07-14-provider-routed-llm-adapters.zh.md: eff33496e1a61472534009533270f8f943ccc1f8
+2026-07-14-provider-routed-llm-adapters.md: bb516a39b6c7303d125575bbd3d4138f9af65f7d
+2026-07-14-provider-routed-llm-adapters.zh.md: 2b6af0d509c28cb79dcd3342a007be8e54799ebc
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index 9039334370..bb516a39b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -10,7 +10,7 @@ English | [中文](2026-07-14-provider-routed-llm-adapters.zh.md)
 
 The conflation prevents a provider gateway from serving an open-ended model catalog. OpenRouter, for example, is one provider with many model ids, while a private OpenAI-compatible endpoint may add models without changing the Harness plugin tree. Every newly selected model currently needs to have been registered during plugin startup. The same model id can also exist at multiple providers, so model-only registration cannot state which provider the caller intended.
 
-`dsh-llm-pi-ai` exposed none of pi-ai's provider abstraction. It constructed an inline DeepSeek `openai-completions` model, applied DeepSeek-specific payload patches, and stamped every replayed assistant message as DeepSeek. pi-ai itself has a provider/model catalog, selects APIs such as `openai-responses`, `anthropic-messages`, and `google-generative-ai`, and preserves provider-specific response ids and reasoning/tool signatures for later turns. The Harness conversion dropped that provenance, so simply replacing the inline model with a catalog lookup would have made same-model replay and cross-provider handoff incomplete.
+`dsh-llm-pi-ai` exposed none of pi-ai's provider abstraction. It constructed an inline DeepSeek `openai-completions` model, applied DeepSeek-specific payload patches, and stamped every replayed assistant message as DeepSeek. pi-ai itself has a provider/model catalog, selects APIs such as `openai-responses`, `anthropic-messages`, and `google-generative-ai`, and preserves provider-specific response ids and reasoning/tool signatures for later turns. The Harness conversion dropped the provider/model route and provider response fields, so simply replacing the inline model with a catalog lookup would have made same-model replay and cross-provider handoff incomplete.
 
 The adapter configuration also assumes one DeepSeek API key and endpoint. A generic backend needs independent credentials and endpoint overrides per provider while leaving AWS, Google ADC, OAuth, and other ambient authentication mechanisms to pi-ai.
 
@@ -36,15 +36,15 @@ The adapter calls pi-ai's `streamSimple()` so each catalog model chooses its reg
 
 pi-ai's common stream options do not expose stop sequences. `dsh-llm-pi-ai` rejects a defined Harness `stop` option with `UNSUPPORTED_OPTION` rather than silently ignoring it or growing a second provider-specific payload implementation. `dsh-llm-deepseek` continues to support `stop` through its native request serializer.
 
-### Durable assistant provenance and replay state
+### Recorded assistant route and replay state
 
-Assistant messages carry provider-neutral provenance containing the request's `provider` and `model`, plus an optional JSON-serializable adapter replay state. A successful `assistant/message` session event records this provenance and `deriveMessages()` returns it with the assistant message. User, system, context, and tool-result messages carry no assistant provenance. The provider/model fields are authoritative loop data; an adapter owns only its opaque replay-state payload.
+Assistant messages carry the request's `provider` and `model`, plus an optional JSON-serializable adapter replay state. A successful `assistant/message` session event records those fields and `deriveMessages()` returns them with the assistant message. User, system, context, and tool-result messages carry no assistant route fields. The provider/model fields are authoritative loop data; an adapter owns only its opaque replay-state payload.
 
-A terminal successful `finish` chunk may carry replay state, and `BlockAssembler` retains it alongside usage and finish reason. The loop attaches that state to the assembled assistant provenance without exposing a response-rewrite hook. Error and aborted responses do not produce a normal assistant message and therefore do not enter future model history.
+A terminal successful `finish` chunk may carry replay state, and `BlockAssembler` retains it alongside usage and finish reason. The loop attaches that state to the assembled assistant message's model source without exposing a response-rewrite hook. Error and aborted responses do not produce a normal assistant message and therefore do not enter future model history.
 
-The pi-ai replay state is a versioned, minimal projection of its successful `AssistantMessage`: source API/provider/model, response id/model, stop reason, and index-aligned text, thinking, and tool-call signatures. It does not duplicate text or tool arguments already carried by Harness content blocks, and it omits diagnostics, timestamps, usage, and errors. On a later request, `LlmService` gives replay state to the target adapter only when the historical provider and target provider are currently owned by the same adapter instance. That adapter combines the logged Harness content with replay state when it can restore the historical response, and owns any required cross-model or cross-provider conversion. An adapter receiving replay state with an unknown version or mismatched block shape fails explicitly; a different adapter receives only provider-neutral content and provenance.
+The pi-ai replay state is a versioned, minimal projection of its successful `AssistantMessage`: source API/provider/model, response id/model, stop reason, and index-aligned text, thinking, and tool-call signatures. It does not duplicate text or tool arguments already carried by Harness content blocks, and it omits diagnostics, timestamps, usage, and errors. On a later request, `LlmService` gives replay state to the target adapter only when the historical provider and target provider are currently owned by the same adapter instance. That adapter combines the logged Harness content with replay state when it can restore the historical response, and owns any required cross-model or cross-provider conversion. An adapter receiving replay state with an unknown version or mismatched block shape fails explicitly; a different adapter receives only provider-neutral content plus provider/model fields.
 
-This state is model-visible replay input and therefore follows the existing [reconstructable-request rule](2026-07-05-reconstructable-requests.md): it is present in both the terminal `finish` chunk and the assembled `assistant/message` provenance that drives derivation. Resume and fork preserve it verbatim. Compaction that shadows the assistant message also removes its replay state from the active surface; the summary is ordinary provider-neutral content.
+This state is model-visible replay input and therefore follows the existing [reconstructable-request rule](2026-07-05-reconstructable-requests.md): it is present in both the terminal `finish` chunk and the assembled `assistant/message` model source that drives derivation. Resume and fork preserve it verbatim. Compaction that shadows the assistant message also removes its replay state from the active surface; the summary is ordinary provider-neutral content.
 
 ### Propagate the target through every request producer
 
@@ -54,7 +54,7 @@ Compaction configuration gains `summarizationProvider` beside `summarizationMode
 
 The JSON-RPC runtime receives provider and model explicitly. Its convenience fallback mounts `dsh-llm-deepseek` only for provider `deepseek` when that provider has no registered owner; other missing providers fail without guessing an adapter.
 
-The on-disk session format remains the pre-release pinned version `0`, with no compatibility promise. Seed/load validation rejects request headers lacking provider and assistant messages lacking required provenance instead of accepting an old shape that can no longer reconstruct the request.
+The on-disk session format remains the pre-release pinned version `0`, with no compatibility promise. Seed/load validation rejects request headers and assistant messages that omit required provider/model fields instead of accepting an old shape that can no longer reconstruct the request.
 
 ## Alternatives considered
 
@@ -78,7 +78,7 @@ The on-disk session format remains the pre-release pinned version `0`, with no c
 - pi-ai credentials, transport knobs, SDK timeouts, and the five-minute-default `streamIdleTimeoutMs` watchdog are scoped per provider profile. Hidden provider retries are disabled; bounded retries belong to the separately composed agent recovery policy.
 - `dsh-llm-pi-ai` rejects stop sequences because pi-ai's common stream API cannot express them; the native DeepSeek adapter retains its stop support.
 - Replay state is portable only within the adapter instance that owns both the historical and target providers. Cross-provider and cross-model restoration is an adapter responsibility, and another adapter receives provider-neutral history without the opaque state.
-- Current pre-release session JSONL requires provider/model request headers and assistant provenance. Older shapes remain version `0` but are rejected rather than migrated.
+- Current pre-release session JSONL requires provider/model on request headers and assistant messages. Older shapes remain version `0` but are rejected rather than migrated.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index eff33496e1..2b6af0d509 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 这种混淆使提供方网关无法提供开放的模型目录。例如，OpenRouter 是一个包含大量模型 ID 的提供方，私有 OpenAI 兼容端点也可能在不修改 Harness 插件树的情况下增加模型。目前，每个新选择的模型都必须在插件启动期间完成注册。同一个模型 ID 还可能存在于多个提供方中，因此仅按模型注册无法表达调用方预期使用的提供方。
 
-`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用的 payload 补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理和工具签名。Harness 转换丢弃了这些来源信息，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
+`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用的 payload 补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理和工具签名。Harness 转换丢弃了提供方／模型路由和提供方响应字段，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
 
 适配器配置同样假定只存在一个 DeepSeek API 密钥和端点。通用后端需要为各提供方分别配置凭据和端点覆盖，同时继续由 pi-ai 处理 AWS、Google ADC、OAuth 等环境认证机制。
 
@@ -36,15 +36,15 @@ Status: implemented
 
 pi-ai 的通用流选项不支持停止序列。若 Harness `stop` 选项已定义，`dsh-llm-pi-ai` 会以 `UNSUPPORTED_OPTION` 拒绝请求，不会静默忽略，也不会增加第二套提供方专用 payload 实现。`dsh-llm-deepseek` 继续通过原生请求序列化器支持 `stop`。
 
-### 持久化助手来源信息与回放状态
+### 已记录的助手路由与回放状态
 
-助手消息携带提供方无关的来源信息，其中包含请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些来源信息，`deriveMessages()` 返回助手消息时也会包含这些信息。用户、system、context 与工具结果消息不携带助手来源信息。provider/model 字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。
+助手消息携带请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些字段，`deriveMessages()` 返回助手消息时也会包含它们。用户、system、context 与工具结果消息不携带助手路由字段。provider/model 字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。
 
-成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。只有当 `agent/step-result` 处理后的内容与提供方组装输出在结构上相等时，agent loop 才会把回放状态附加到助手来源信息。监听器重写内容后，provider/model 来源信息仍会保留，但已经陈旧的回放状态会被移除。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
+成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。agent loop 会把该状态附加到已组装助手消息的模型来源中，但不公开响应改写钩子。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
 
-pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容与来源信息。
+pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容以及 provider/model 字段。
 
-该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 来源信息中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。
+该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 模型来源中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。
 
 ### 在所有请求生产方中传播目标
 
@@ -54,7 +54,7 @@ pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包
 
 JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方没有注册所有者时，其便利回退才会挂载 `dsh-llm-deepseek`；其他缺失的提供方会直接失败，不会猜测适配器。
 
-磁盘会话格式仍使用预发布阶段固定的版本 `0`，且不承诺兼容性。seed/load 验证会拒绝缺少 provider 的请求头，以及缺少必需来源信息的助手消息，不会接受已无法重建请求的旧格式。
+磁盘会话格式仍使用预发布阶段固定的版本 `0`，且不承诺兼容性。seed/load 验证会拒绝省略必需 provider/model 字段的请求头和助手消息，不会接受已无法重建请求的旧格式。
 
 ## 考虑过的替代方案
 
@@ -78,7 +78,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 - pi-ai 凭据、传输选项、SDK 超时，以及默认五分钟的 `streamIdleTimeoutMs` 空闲超时机制均按提供方配置隔离。系统禁用隐藏的提供方重试；有界重试由单独组合的 agent 恢复策略负责。
 - pi-ai 的通用流 API 无法表达停止序列，因此 `dsh-llm-pi-ai` 会拒绝停止序列；原生 DeepSeek 适配器仍支持停止序列。
 - 仅当历史提供方与目标提供方归同一个适配器实例所有时，回放状态才可移植。适配器负责跨提供方和跨模型恢复；其他适配器只接收不含不透明状态的提供方无关历史。
-- 当前预发布会话 JSONL 要求请求头包含 provider/model，助手消息包含来源信息。旧格式仍使用版本 `0`，但会被拒绝，不执行迁移。
+- 当前预发布会话 JSONL 要求请求头和助手消息都包含 provider/model。旧格式仍使用版本 `0`，但会被拒绝，不执行迁移。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml
index 80fe86f2bc..8579c7231a 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.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 .agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
-2026-07-15-replay-token-meter-service.md: c0f4b467ad0013dd4ac0a0301281b011ea8c261c
-2026-07-15-replay-token-meter-service.zh.md: c1d81dc0e76ee687ced5c23d26197627551e1ced
+2026-07-15-replay-token-meter-service.md: 4013cc92f67597a9b87edfc97d14c7f47f0523ac
+2026-07-15-replay-token-meter-service.zh.md: 4bee27db2a7d021b25dfdf1feefa148cfb016100
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
index c0f4b467ad..4013cc92f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-15-replay-token-meter-service.zh.md)
 
 Context pressure is useful outside compaction. A compaction backend, an overflow guard, or a future request-policy plugin can all need the same answer: how many tokens does the durable request consume? Keeping that fold inside `dsh-compact-basic` duplicates replay logic, makes measurement unavailable without compaction, and encourages callers to reuse stale accounting.
 
-Provider usage is not a complete answer. It describes one successful call under one exact request envelope, while the current surface can grow, shrink, or be replaced afterward. Sessions also switch providers and models, old logs can lack chunk provenance, and usage fields separate input, cache-read, cache-write, output, and reasoning counts. A useful service therefore combines the latest exact anchor with conservative heuristic repricing and exposes the log revision consumed by each result.
+Provider usage is not a complete answer. It describes one successful call under one exact request envelope, while the current surface can grow, shrink, or be replaced afterward. Sessions also switch providers and models, old logs can omit the chunk seqs behind an assistant message, and usage fields separate input, cache-read, cache-write, output, and reasoning counts. A useful service therefore combines the latest exact anchor with conservative heuristic repricing and exposes the log revision consumed by each result.
 
 ## Decision
 
@@ -20,17 +20,17 @@ The service has no configuration. Estimation uses a fixed four-characters-per-to
 
 ### Per-session replay folds
 
-Each session owns one isolated incremental fold. Active folds advance from `session/event`; every read catches up through the durable tail, so listener ordering, seeded sessions, and service reload do not change the answer. The fold tracks canonical full request-header snapshots, step boundaries, surface appends and replacements, assistant usage, and assistant-chunk provenance. A malformed next event fails transactionally and remains unread rather than partially mutating state.
+Each session owns one isolated incremental fold. Active folds advance from `session/event`; every read catches up through the durable tail, so listener ordering, seeded sessions, and service reload do not change the answer. The fold tracks canonical full request-header snapshots, step boundaries, surface appends and replacements, assistant usage, and the chunk seqs cited by each assistant message. A malformed next event fails transactionally and remains unread rather than partially mutating state.
 
 `measure(session, requestHeader?)` synchronizes the fold once and returns scalar pressure together with positional per-node prices. `totalTokens` remains request-and-response pressure; `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override changes pressure pricing only, while the surface fields always describe the current session. `estimateMessage(message)` applies the fixed heuristic without session state. Each result is one detached, deeply immutable snapshot carrying one `logRevision`. Every measurement clones the current nodes and is therefore O(surface).
 
 Provider usage is reused only when the measured canonical request envelope equals the latest successful-call anchor. Any provider, model, system, prefix, tool, or call-config change causes complete heuristic repricing. Surface changes remain a signed delta from a matching anchor, including negative values after a shrinking replacement. A later successful request replaces the earlier anchor, including across provider or model switches.
 
-Usage sums the disjoint input, cache-read, cache-write, and output buckets. Reasoning is not added a second time. Every successful model call records an `assistant/message`, including content-less and max-token calls, with its exact earlier chunk seqs. An explicit empty provenance list means a known empty provider stream; absent legacy provenance conservatively treats the durable assistant output as provider output.
+Usage sums the disjoint input, cache-read, cache-write, and output buckets. Reasoning is not added a second time. Every successful model call records an `assistant/message`, including content-less and max-token calls, with its exact earlier chunk seqs. An explicit empty `sourceEventSeqs` list means a known empty provider stream; an absent legacy list conservatively treats the durable assistant output as provider output.
 
 ### Compact-basic consumes, but does not own, measurement
 
-`dsh-compact-basic` requires `ctx.tokenMeter`; `CompactService` gains no token methods or types. Configuration, the region transaction, and summarization stay in separate modules; the service registers automatic listeners itself, while `summarize()` remains its sole subclass hook. The singleton meter consistently prices pressure, retention, shadowed content, provenance, and non-shrinking-summary rejection.
+`dsh-compact-basic` requires `ctx.tokenMeter`; `CompactService` gains no token methods or types. Configuration, the region transaction, and summarization stay in separate modules; the service registers automatic listeners itself, while `summarize()` remains its sole subclass hook. The singleton meter consistently prices pressure, retention, shadowed content, cited source events, and non-shrinking-summary rejection.
 
 Automatic compaction uses one unified measurement for each threshold-and-retention decision. The region transaction measures after appending its durable `compact/start` lock and again after asynchronous summarization, then compares the detached surface-node vectors. An intervening surface mutation prevents replacement; `logRevision` may advance for unrelated log-only facts without invalidating an unchanged selected span.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
index c1d81dc0e7..4bee27db2a 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 上下文压力并不只对压缩（compaction）有用。压缩后端、溢出保护或未来的请求策略插件都可能需要回答同一个问题：持久请求消耗了多少 token？如果把该折叠逻辑留在 `dsh-compact-basic` 内部，就会重复实现回放逻辑，使未加载压缩的调用方无法使用计量，并诱使调用方复用陈旧的核算结果。
 
-提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换提供方与模型，旧日志可能缺少分片来源，usage 字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把最新精确锚点与保守的启发式重新定价结合起来，并公开每个结果已经消费的日志修订号。
+提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换提供方与模型，旧日志可能缺少构成 assistant 消息的分片 seq，usage 字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把最新精确锚点与保守的启发式重新定价结合起来，并公开每个结果已经消费的日志修订号。
 
 ## 决策
 
@@ -20,17 +20,17 @@ Status: implemented
 
 ### 逐会话回放折叠
 
-每个会话都有一个隔离的增量折叠。活跃折叠通过 `session/event` 前进；每次读取都会追到持久日志尾部，因此监听器顺序、种子会话与服务重载不会改变答案。折叠跟踪规范的完整请求头快照、步骤边界、表层追加与替换、assistant usage，以及 assistant 分片来源。下一个畸形事件会以事务方式失败并保持未读，不会让状态只修改一半。
+每个会话都有一个隔离的增量折叠。活跃折叠通过 `session/event` 前进；每次读取都会追到持久日志尾部，因此监听器顺序、种子会话与服务重载不会改变答案。折叠跟踪规范的完整请求头快照、步骤边界、表层追加与替换、assistant usage，以及每条 assistant 消息引用的分片 seq。下一个畸形事件会以事务方式失败并保持未读，不会让状态只修改一半。
 
 `measure(session, requestHeader?)` 只同步一次折叠，并在返回标量压力的同时给出逐位置节点价格。`totalTokens` 仍表示请求与响应压力；`surfaceTokens` 是仅针对表层的启发式总量，并等于 `nodes[].tokens` 之和。`requestHeader` 覆盖只改变压力定价，表层字段始终描述当前会话。`estimateMessage(message)` 不依赖会话状态，直接应用固定启发式规则。每个结果都是一个分离且深度不可变的快照，只携带一个 `logRevision`。每次计量都会复制当前节点，因此成本为 O(surface)。
 
 只有当待计量的规范请求信封等于最近一次成功调用的锚点时，服务才复用提供方 usage。提供方、模型、系统提示词、前缀、工具或调用配置任一变化都会触发完整的启发式重新定价。表层变化相对匹配锚点保留有符号增量，包括缩小替换后的负值。后续成功请求会替换先前锚点，提供方或模型切换时也一样。
 
-Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket 求和，不会再次加入推理计数。每次成功模型调用都会记录 `assistant/message`，包括无内容调用与达到 token 上限的调用，并带上精确的更早分片 seq。显式空来源列表表示已知为空的提供方流；旧日志中缺失的来源则保守地把持久 assistant 输出视为提供方输出。
+Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket 求和，不会再次加入推理计数。每次成功模型调用都会记录 `assistant/message`，包括无内容调用与达到 token 上限的调用，并带上精确的更早分片 seq。显式的空 `sourceEventSeqs` 列表表示已知为空的提供方流；旧日志中缺失的列表则保守地把持久 assistant 输出视为提供方输出。
 
 ### compact-basic 消费计量，但不拥有计量
 
-`dsh-compact-basic` 要求 `ctx.tokenMeter`；`CompactService` 不增加 token 方法或类型。配置、区域事务与摘要分别保留在独立模块中，服务自身注册自动监听器，而 `summarize()` 仍是唯一的子类钩子。单例计量器一致用于压力、保留、被遮蔽内容、来源以及非缩小摘要拒绝的定价。
+`dsh-compact-basic` 要求 `ctx.tokenMeter`；`CompactService` 不增加 token 方法或类型。配置、区域事务与摘要分别保留在独立模块中，服务自身注册自动监听器，而 `summarize()` 仍是唯一的子类钩子。单例计量器一致用于压力、保留、被遮蔽内容、引用的源事件以及非缩小摘要拒绝的定价。
 
 自动压缩的每次阈值与保留联合决策只使用一次统一计量。区域事务会在追加持久 `compact/start` 锁后执行计量，在异步摘要完成后再次计量，随后比较分离的表层节点向量。期间发生的表层变更会阻止替换；`logRevision` 可以因无关的纯日志事实而推进，而不会使未变的选定范围失效。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index 291a3f3ce1..ad5f67e601 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.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 .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
-2026-07-19-package-owned-invariant-service.md: e32efe9f6b3ce6b782c61db56d928e87c160dc9a
-2026-07-19-package-owned-invariant-service.zh.md: abb77cfc2dc4c15510baf0b205cefdbf3c890041
+2026-07-19-package-owned-invariant-service.md: 6ab53f1a9bfa043f17875fa179a99b832b3fcf1a
+2026-07-19-package-owned-invariant-service.zh.md: 378b730c479eed05a2ad11e6a6e084929ec09653
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
index e32efe9f6b..6ab53f1a9b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -102,4 +102,4 @@ Every Vitest configuration loads a test host that mounts an explicitly enabled s
 - One selected executable contribution adds one child fiber and its listener/state cost; a selected empty contribution has no listener or trace-state cost, while filtered registrations retain only name ownership.
 - Regex sources are deployment configuration and remain fixed until the service reloads.
 - Ordinary Vitest roots install the owning test package's selected companion; one exhaustive topology pays the full child-fiber cost once for repository-wide registration coverage.
-- Session storage validation, snapshotting, freezing, provenance, and surface acceptance remain always on and are not affected by invariant selection.
+- Session storage validation, snapshotting, freezing, cited source-event validation, and surface acceptance remain always on and are not affected by invariant selection.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index abb77cfc2d..378b730c47 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -102,4 +102,4 @@ Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、
 - 每个选中的可执行贡献增加一个子 fiber 及其 listener/状态成本；选中的空贡献不增加 listener 或 trace 状态成本，被过滤注册则只保留包名占用。
 - 正则表达式源属于部署配置，在服务重载前保持固定。
 - 普通 Vitest 根上下文会安装当前测试包中被选中的伴随插件；一个完整拓扑只支付一次全部子 fiber 成本，用于覆盖整个仓库的注册。
-- 会话存储验证、快照、冻结、provenance 与 surface 接受规则始终启用，不受不变式选择影响。
+- 会话存储验证、快照、冻结、引用的源事件验证与 surface 接受规则始终启用，不受不变式选择影响。
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index 75c2b53cef..1cb93a9643 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.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 .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
-2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
-2026-07-20-canonical-tool-output-contract.zh.md: 534aa2ed7ad65719b280f64f73a412bf5b17a1de
+2026-07-20-canonical-tool-output-contract.md: fc4a8d52f2ad6ff532fafdd7a987a095c8e3bcef
+2026-07-20-canonical-tool-output-contract.zh.md: a42c5d9a2b581012af823343991ac5789a787658
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
index 2429e1c141..fc4a8d52f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
@@ -24,7 +24,7 @@ output: {
 
 `defineTool` infers the body return and both projectors from the unified `ValueSchemaSpec`. Raw and dynamic definitions provide the compiled `JsonSchemaNode` form. Registration rejects a missing declaration or unsupported raw schema; there is no content-return compatibility path.
 
-For each successful dispatch the registry snapshots the returned value as lossless `JsonValue`, validates it against `output.schema`, deep-freezes it, then invokes the pure renderer and, for a direct surface call, the optional metadata projector. Renderer, projector, schema, or lossless-JSON failures are contained as ordinary `ToolOutputError` results. An around `tools/execute` wrapper receives and returns the canonical success/failure union; a wrapper-authored success is normalized again through the resolved tool's output declaration instead of trusting independently authored content. Canonical-result provenance is scoped to the immutable dispatch token, so returning a cached result from another call or tool triggers normalization under the active declaration rather than bypassing it.
+For each successful dispatch the registry snapshots the returned value as lossless `JsonValue`, validates it against `output.schema`, deep-freezes it, then invokes the pure renderer and, for a direct surface call, the optional metadata projector. Renderer, projector, schema, or lossless-JSON failures are contained as ordinary `ToolOutputError` results. An around `tools/execute` wrapper receives and returns the canonical success/failure union; a wrapper-authored success is normalized again through the resolved tool's output declaration instead of trusting independently authored content. Each canonical result is tied to the immutable dispatch token that created it, so returning a cached result from another call or tool triggers normalization under the active declaration rather than bypassing it.
 
 ```ts ignore-check
 type ToolExecutionResult =
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
index 534aa2ed7a..a42c5d9a2b 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -24,7 +24,7 @@ output: {
 
 `defineTool` 从统一的 `ValueSchemaSpec` 推导工具主体返回值和两个投影器的类型。原始定义和动态定义则提供编译后的 `JsonSchemaNode` 形式。注册时会拒绝缺失输出声明或采用不受支持的原始 schema 的定义，不提供兼容旧式内容返回值的路径。
 
-每次成功分发时，注册表会将返回值快照为无损 `JsonValue`，依据 `output.schema` 校验并深度冻结，然后调用纯渲染器；对于直接的外层调用，还会调用可选的元数据投影器。渲染器、投影器、schema 或无损 JSON 处理失败都会被收敛为普通 `ToolOutputError` 结果。围绕 `tools/execute` 的包装层接收并返回规范的成功／失败联合；包装层自行产生的成功结果会再次通过已解析工具的输出声明完成归一化，而不会信任其独立编写的内容。每个规范结果的来源归属仅限于一个不可变的分发 token；因此，如果包装层返回来自其他调用或工具的缓存结果，系统会依据当前生效的输出声明重新执行归一化，而不会绕过这一步。
+每次成功分发时，注册表会将返回值快照为无损 `JsonValue`，依据 `output.schema` 校验并深度冻结，然后调用纯渲染器；对于直接的外层调用，还会调用可选的元数据投影器。渲染器、投影器、schema 或无损 JSON 处理失败都会被收敛为普通 `ToolOutputError` 结果。围绕 `tools/execute` 的包装层接收并返回规范的成功／失败联合；包装层自行产生的成功结果会再次通过已解析工具的输出声明完成归一化，而不会信任其独立编写的内容。每个规范结果都与创建它的不可变分发 token 绑定；因此，如果包装层返回来自其他调用或工具的缓存结果，系统会依据当前生效的输出声明重新执行归一化，而不会绕过这一步。
 
 ```ts ignore-check
 type ToolExecutionResult =
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
index 0575e85c1c..77ee43a2d9 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.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 .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
-2026-07-22-unified-send-and-coalesced-user-messages.md: f32d6ca65d5236e1fabdd177cdf54e36929c853f
-2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 6148cf4e0dda9032fca0ced5b466787877b89fa0
+2026-07-22-unified-send-and-coalesced-user-messages.md: bc195e77c71b554d60c03c91134bbcef95678fff
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 668ca01bc6b6854642fee2afe9f7be7354b25c5c
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
index f32d6ca65d..bc195e77c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
@@ -14,9 +14,9 @@ Separately, `context/message` and `user/message` had converged: the surface proj
 
 **One primitive, three preset aliases.** The `Agent` interface's `send(message, target, wakeup)` covers the (`target` × `wakeup`) matrix. Its complete `UserMessage` owns identity, role, model-facing `content`, and producer `source`; the remaining arguments own only routing policy. `followup` (`next-turn`/wakeup), `steer` (`next-step`/wakeup), and `inject` (`next-step`/no-wakeup) each accept that one message and fix the policy. `wakeup` reserves a driver when the agent is idle; an already active driver receives no second reservation and can claim the input only if it reaches a later pre-step boundary. `next-turn`/no-wakeup (queue without waking) is representable with no alias and no current caller.
 
-**inject is a non-waking next-step delivery.** It always appends the complete message to the next-step inbox and records that insertion in a durable `agent/inbox/spliced` event. The driver claims it at a later pre-step and records it as model-visible `user/message` only when the final decision returns it in the entering batch; idle injection remains pending until another delivery wakes the driver. Its required `UserMessage.source` preserves the caller's explicit provenance.
+**inject is a non-waking next-step delivery.** It always appends the complete message to the next-step inbox and records that insertion in a durable `agent/inbox/spliced` event. The driver claims it at a later pre-step and records it as model-visible `user/message` only when the final decision returns it in the entering batch; idle injection remains pending until another delivery wakes the driver. Its required `UserMessage.source` preserves the source fields supplied by the caller.
 
-**context/message is gone.** Injected context uses one `UserMessage` value in the inbox and becomes a `user/message` event if admitted; context producers supply the appropriate non-user `source` explicitly, and typed source variants carry any domain-specific durable provenance. The surface, derivation, and `SurfaceEventType` drop `context/message`; consumers that need "is this a human prompt?" read `source.kind === 'user'` instead of the event type.
+**context/message is gone.** Injected context uses one `UserMessage` value in the inbox and becomes a `user/message` event if admitted; context producers supply the appropriate non-user `source` explicitly, and typed source variants carry any durable producer-specific fields. The surface, derivation, and `SurfaceEventType` drop `context/message`; consumers that need "is this a human prompt?" read `source.kind === 'user'` instead of the event type.
 
 **Goal continuation attribution uses positive rounds.** Goal lifecycle state commits through the domain-owned `goal/change` event defined by the later [goal-owned durable event decision](2026-07-31-goal-owned-durable-events.md). A positive round advances only from an admitted continuation `user/message`; goal persistence does not use injection or inbox state.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
index 6148cf4e0d..668ca01bc6 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -14,9 +14,9 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 
 **一个原语，三个预设别名。** `Agent` 接口的 `send(message, target, wakeup)` 覆盖 (`target` × `wakeup`) 矩阵。完整的 `UserMessage` 持有标识、角色、模型可见 `content` 与生产方 `source`；其余参数只持有路由策略。`followup`（`next-turn`/wakeup）、`steer`（`next-step`/wakeup）和 `inject`（`next-step`/no-wakeup）都接收这一条消息并固定策略。`wakeup` 会在 agent 空闲时保留一个驱动器；已经活跃的驱动器不会获得第二次保留，只有在抵达后续 pre-step 边界时才能领取该输入。`next-turn`/no-wakeup（入队但不唤醒）可以表达，只是没有别名，也没有当前调用方。
 
-**inject 是不会唤醒的 next-step 投递。** 它始终把完整消息追加到 next-step inbox，并在持久 `agent/inbox/spliced` 事件中记录该插入。驱动器会在后续 pre-step 领取它，并且只有最终决策把它放入进入步骤的批次时，才会将其记录为模型可见的 `user/message`；空闲注入会保持待处理，直到其他投递唤醒驱动器。必填的 `UserMessage.source` 会保留调用方显式提供的来源信息。
+**inject 是不会唤醒的 next-step 投递。** 它始终把完整消息追加到 next-step inbox，并在持久 `agent/inbox/spliced` 事件中记录该插入。驱动器会在后续 pre-step 领取它，并且只有最终决策把它放入进入步骤的批次时，才会将其记录为模型可见的 `user/message`；空闲注入会保持待处理，直到其他投递唤醒驱动器。必填的 `UserMessage.source` 会保留调用方提供的源字段。
 
-**context/message 已移除。** 注入的上下文在 inbox 中使用同一个 `UserMessage` 值，并在获准时成为 `user/message` 事件；上下文生产方显式提供合适的非 `user` 类别 `source`，类型化 source 变体携带所有特定于领域的持久来源信息。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。
+**context/message 已移除。** 注入的上下文在 inbox 中使用同一个 `UserMessage` 值，并在获准时成为 `user/message` 事件；上下文生产方显式提供合适的非 `user` 类别 `source`，类型化 source 变体携带持久化的生产方专用字段。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。
 
 **Goal 继续执行归属使用正数 Round。** Goal 生命周期状态通过后续的[Goal 自有持久事件决策](2026-07-31-goal-owned-durable-events.md)所定义的领域自有 `goal/change` 事件提交。正数 Round 只从已准入的继续执行 `user/message` 推进；goal 持久化不使用注入或 inbox 状态。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
index d328c8a065..a55c6dbd74 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.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 .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
-2026-07-24-separate-context-injection-from-turn-execution.md: bb28d96cf1494d94ad7a7d4a4714e536c7072d2f
-2026-07-24-separate-context-injection-from-turn-execution.zh.md: 0edf3f4e8a062fe82462e263da383e27d79034c5
+2026-07-24-separate-context-injection-from-turn-execution.md: 719c4562b6687e42cc70721658152992735ec662
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 4564c5376f3e6f9de4d50dc13f2d1f01e6230d91
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
index bb28d96cf1..719c4562b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
@@ -12,7 +12,7 @@ Atomic attachment to an inbox message forced the loop to preserve context throug
 
 Idle `inject()` exposed a second mismatch. Injection did not request model execution, yet the implementation opened and closed a zero-step `injection` turn solely to satisfy the turn-enclosure invariant and obtain a durability checkpoint. A turn therefore sometimes meant “run the agent loop” and sometimes meant “persist context without running it.”
 
-`HookContext` also named its producer rather than its role. The value could come from a native plugin, a hook bridge, prompt admission, or tool post-processing; its stable meaning was additional model-facing context with provenance.
+`HookContext` also named its producer rather than its role. The value could come from a native plugin, a hook bridge, prompt admission, or tool post-processing; its stable meaning was additional model-facing context whose source named the producer.
 
 ## Decision
 
@@ -22,7 +22,7 @@ A caller that owns context delivers an identified, frozen `UserMessage` through
 
 An entering pre-step returns the complete `PreStepDecision.messages` batch for the request being finalized. Tool extension points still return `additionalContexts`, which enter the next-step inbox only after the corresponding tool results. These values are extension-point outputs, not attachments captured from a caller's inbox item.
 
-Every additional context is an independent `UserMessage` whose `source` records provenance. Inbox insertion is durable immediately; admission later records the same value as `user/message`. There is no `context/message`, prompt-prefix placement, stable request delimiter, or prompt envelope. Transcript and UI consumers distinguish direct user messages from injected context by `source`.
+Every additional context is an independent `UserMessage` whose `source` names its producer and carries producer-specific fields. Inbox insertion is durable immediately; admission later records the same value as `user/message`. There is no `context/message`, prompt-prefix placement, stable request delimiter, or prompt envelope. Transcript and UI consumers distinguish direct user messages from injected context by `source`.
 
 ## Injection lifecycle
 
@@ -36,7 +36,7 @@ The loop appends injected `user/message` events only from entered batches inside
 
 ## Extension and caller semantics
 
-The enter branch's `PreStepDecision.messages` is the complete batch for the proposed step. A waterfall listener that delegates with `next()` preserves downstream messages unless it intentionally replaces them; additions follow natural waterfall return order. Tool-result `additionalContexts` retain FIFO order and individual provenance.
+The enter branch's `PreStepDecision.messages` is the complete batch for the proposed step. A waterfall listener that delegates with `next()` preserves downstream messages unless it intentionally replaces them; additions follow natural waterfall return order. Tool-result `additionalContexts` retain FIFO order and each message's source.
 
 Caller-driven injection and current-step context deliberately use different timing. `inject()` joins the next pre-step available and cannot promise that a request already being finalized will consume it. A listener that must affect that exact request returns the context in `PreStepDecision.messages`; downstream rejection or failure then prevents it from materializing.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
index 0edf3f4e8a..4564c5376f 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -12,7 +12,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入：
 
 空闲状态下的 `inject()` 还暴露了另一处语义错位。注入当时并不请求模型执行，但实现仅为了满足轮次封闭不变量并获得持久性检查点，就会打开并关闭一个零步骤的 `injection` 轮次。于是，当时的轮次有时表示「运行 agent loop」，有时却表示「不运行 agent，仅持久化上下文」。
 
-`HookContext` 的名字也描述了生产方，而非该值的职责。它可能来自原生插件、hook bridge、提示词准入或工具后处理；其稳定含义是带来源信息的额外模型上下文。
+`HookContext` 的名字也描述了生产方，而非该值的职责。它可能来自原生插件、hook bridge、提示词准入或工具后处理；其稳定含义是额外的模型可见上下文，并且 source 会指明生产方。
 
 ## 决策
 
@@ -22,7 +22,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入：
 
 返回 enter 的 pre-step 会为正在最终确定的请求返回完整的 `PreStepDecision.messages` 批次。工具扩展点仍可返回 `additionalContexts`，这些上下文只会在对应工具结果之后进入 next-step inbox。这些值是扩展点的输出，而不是从调用方 inbox 条目捕获的附件。
 
-每项额外上下文都是独立的 `UserMessage`，并由 `source` 记录来源。inbox 插入会立即持久化；后续准入会将同一个值记录为 `user/message`。不再有 `context/message`、prompt-prefix 放置方式、稳定请求分隔符或提示词封套。transcript 与 UI 消费方通过 `source` 区分直接用户消息和注入上下文。
+每项额外上下文都是独立的 `UserMessage`，其 `source` 会指明生产方，并携带生产方专用字段。inbox 插入会立即持久化；后续准入会将同一个值记录为 `user/message`。不再有 `context/message`、prompt-prefix 放置方式、稳定请求分隔符或提示词封套。transcript 与 UI 消费方通过 `source` 区分直接用户消息和注入上下文。
 
 ## 注入生命周期
 
@@ -36,7 +36,7 @@ loop 只会在轮次内从进入步骤的批次追加注入的 `user/message`。
 
 ## 扩展点与调用方语义
 
-enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。waterfall（瀑布式事件）监听器调用 `next()` 委托时，会保留下游消息，除非有意替换；新增消息遵循 waterfall 的自然返回顺序。工具结果的 `additionalContexts` 保留 FIFO 顺序及各自来源。
+enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。waterfall（瀑布式事件）监听器调用 `next()` 委托时，会保留下游消息，除非有意替换；新增消息遵循 waterfall 的自然返回顺序。工具结果的 `additionalContexts` 保留 FIFO 顺序及每条消息的 source。
 
 调用方主动注入与当前步骤上下文刻意采用不同的时序。`inject()` 会加入下一个可用 pre-step，无法保证正在最终确定的请求会消费它。必须影响该请求的监听器在 `PreStepDecision.messages` 中返回上下文；下游 reject 或失败时，该上下文不会落入日志。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
index 938d86ef4b..0b44906fd6 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.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 .agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
-2026-07-26-packed-chunk-rows-by-default.md: d6a044676604e4a4512a7a6674edb80e120b2f3c
-2026-07-26-packed-chunk-rows-by-default.zh.md: 0e3e06e0d4185603cd21939589855a51797560a4
+2026-07-26-packed-chunk-rows-by-default.md: 141c9a32a07b5cb4885a21b419df30d45dc1061b
+2026-07-26-packed-chunk-rows-by-default.zh.md: a03654ec82755cadeea734d277c0893db546a5c1
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
index d6a0446766..141c9a32a0 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
@@ -48,7 +48,7 @@ JSONL persistence tests prove that omission writes a packed row, explicit `false
 
 **Remove `packChunks` and always pack.** One writer is simpler, but one-event-per-line output remains useful for diagnostics and for focused mixed-layout compatibility tests. The explicit opt-out preserves those current consumers without weakening the default.
 
-**Batch chunks as logical session events.** This reduces event count, but it delays or reshapes live delivery, renumbers provenance, and requires every UI and replay consumer to understand another streaming unit. Physical packing obtains the storage benefit behind the existing persistence interface.
+**Batch chunks as logical session events.** This reduces event count, but it delays or reshapes live delivery, renumbers the chunk seqs cited by assistant messages, and requires every UI and replay consumer to understand another streaming unit. Physical packing obtains the storage benefit behind the existing persistence interface.
 
 **Keep the branch migrator permanently.** The read-only canonicalizer and snapshot gate own continuing enforcement. A mutation command has value only while in-flight branches still carry the former fixture layout, so its lifetime is explicitly bounded by the removal proposal.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
index 0e3e06e0d4..a03654ec82 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
@@ -48,7 +48,7 @@ JSONL 持久化测试证明：省略选项时会写入打包行，显式传入 `
 
 **删除 `packChunks` 并始终打包。** 只保留一个写入器更简单，但每个事件一行的输出仍适用于诊断和聚焦的混合布局兼容性测试。显式停用选项在不削弱默认值的同时，保留了这些现有消费方。
 
-**把分片批量合并为逻辑会话事件。** 这会减少事件数量，但也会延迟或重塑实时传递，改变溯源信息所引用的序号，并要求每个 UI 和回放消费方理解另一种流式单位。物理打包通过现有持久化接口获得存储收益。
+**把分片批量合并为逻辑会话事件。** 这会减少事件数量，但也会延迟或重塑实时传递，重新编号助手消息引用的分片 seq，并要求每个 UI 和回放消费方理解另一种流式单位。物理打包通过现有持久化接口获得存储收益。
 
 **永久保留分支迁移器。** 只读的规范布局转换器与快照门禁负责持续强制执行。只有在途分支仍携带旧 fixture 布局时，会修改仓库内容的命令才有价值，因此移除提案明确限定了其生命周期。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
index 307dc12518..4aa30937c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.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 .agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
-2026-07-28-identified-immutable-message-values.md: 472de8b133ba323c3e1ff5e53c8dacb3d66525c5
-2026-07-28-identified-immutable-message-values.zh.md: d322ff93765294478d2adce41a5903f3a7fdd67d
+2026-07-28-identified-immutable-message-values.md: f1e0e8c0b42bd2dc4b3c729dc15b5f2a36b98338
+2026-07-28-identified-immutable-message-values.zh.md: 0d1f2fcf5be76089f1c135757a7a50729f099ccd
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
index 472de8b133..f1e0e8c0b4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
@@ -8,13 +8,13 @@ English | [中文](2026-07-28-identified-immutable-message-values.zh.md)
 
 The harness had several message-shaped representations with different identity rules. Agent input acquired an inbox correlation id only when the loop accepted it, while durable user messages, assistant messages, tool results, and model-request messages could have no identity. Prompt admission therefore sat between creation and identity, and equivalent content was copied across live events, durable events, and model requests without one value that named the message throughout its lifetime.
 
-This made identity a routing side effect rather than a message invariant. Producers could not refer to a message before calling the agent, prompt hooks received content and source separately, and later projections had to reconstruct a message while deciding whether an id existed. Immutability also began at different boundaries: some inputs were frozen by the loop, some only by session append, and provider-produced assistant output used a separate provenance-bearing shape.
+This made identity a routing side effect rather than a message invariant. Producers could not refer to a message before calling the agent, prompt hooks received content and source separately, and later projections had to reconstruct a message while deciding whether an id existed. Immutability also began at different boundaries: some inputs were frozen by the loop, some only by session append, and provider-produced assistant output used a separate shape carrying provider, model, and replay state.
 
 ## Decision
 
 `@deepseek-ai/dsh-llm` owns one `Message` value with required `id`, `role`, `content`, and `source`. `MessageId` is opaque and shared by user, assistant, and tool-result messages. A message receives its id at creation, before inbox routing, claim, pre-step rewriting, durable append, or request projection. The same id survives every representation boundary.
 
-`createMessage(input)` is the canonical role-generic creation boundary. It mints a `MessageId`, detaches the supplied role, content, and source, and deep-freezes the complete value before returning it. `createUserMessage({ content, source })` fixes the user role for prompt and context producers. `createAssistantMessage({ content, source })` fixes both the assistant role and the model source kind, so model-output producers supply only content and model provenance. All creation helpers exclude an input id so callers cannot accidentally present creation as import. `freezeMessage(message)` is the separate import or transformation boundary: it detaches and deep-freezes a message whose identity already exists, without minting a replacement.
+`createMessage(input)` is the canonical role-generic creation boundary. It mints a `MessageId`, detaches the supplied role, content, and source, and deep-freezes the complete value before returning it. `createUserMessage({ content, source })` fixes the user role for prompt and context producers. `createAssistantMessage({ content, source })` fixes both the assistant role and the model source kind, so model-output producers supply only content plus provider, model, and optional replay state. All creation helpers exclude an input id so callers cannot accidentally present creation as import. `freezeMessage(message)` is the separate import or transformation boundary: it detaches and deep-freezes a message whose identity already exists, without minting a replacement.
 
 The helpers live in `dsh-llm` beside the base message vocabulary because their complete contracts depend only on that vocabulary. `createToolResultMessage()` belongs with the other creation helpers: it couples a tool call id to the exact user-role tool-result block and source without depending on session state or events. `dsh-session` consumes complete messages rather than owning their construction.
 
@@ -40,7 +40,7 @@ Every message producer must choose creation or import explicitly, and tests cons
 
 Live inbox events, durable events, derived history, and model requests can correlate one message without content equality or envelope-specific ids. Pending-input policy and UI attachment cleanup can compare `MessageId` before a turn exists, while claims retain that identity inside the open turn. Deep freezing prevents a producer, hook, or observer from changing the value after identity is established.
 
-The shared representation removes the old `UserMessageData`/`AgentMessage` split and folds provider provenance into typed message sources. Event envelopes still own facts that are not message semantics, such as turn and step position, token usage, internal tool failure identity, and presentation metadata.
+The shared representation removes the old `UserMessageData`/`AgentMessage` split and puts provider, model, and optional replay state into typed message sources. Event envelopes still own facts that are not message semantics, such as turn and step position, token usage, internal tool failure identity, and presentation metadata.
 
 The message and helper unit tests pin immediate identity, detachment, deep immutability, and preservation of an imported id. Agent-loop tests pin identity across admission, inbox lifecycle, durable append, content rewriting, and cancellation; session tests pin frozen derivation and identity-preserving replacement.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
index d322ff9376..0d1f2fcf5b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
@@ -8,13 +8,13 @@ Status: implemented
 
 harness 曾存在多种形似消息的表示，各自采用不同的标识规则。agent（智能体）输入只有在 agent loop 接受后才会取得 inbox 关联 id，而持久用户消息、assistant 消息、工具结果和模型请求消息都可能没有标识。因此，提示词准入介于创建消息与建立标识之间；等价内容会在实时事件、持久事件和模型请求之间复制，却没有一个值能在消息的整个生命周期中标识它。
 
-这使标识成为路由的副作用，而不是消息不变量。生产方无法在调用 agent 前引用一条消息，提示词钩子会分别接收内容和来源，后续投影则必须一边重建消息，一边决定 id 是否存在。不可变性也从不同边界开始：部分输入由 agent loop 冻结，部分直到会话追加时才冻结，由提供方生成的 assistant 输出则使用另一种携带溯源信息的形状。
+这使标识成为路由的副作用，而不是消息不变量。生产方无法在调用 agent 前引用一条消息，提示词钩子会分别接收内容和来源，后续投影则必须一边重建消息，一边决定 id 是否存在。不可变性也从不同边界开始：部分输入由 agent loop 冻结，部分直到会话追加时才冻结，由提供方生成的 assistant 输出则使用另一种携带提供方、模型和回放状态的形状。
 
 ## 决策
 
 `@deepseek-ai/dsh-llm` 持有唯一一种 `Message` 值，其 `id`、`role`、`content` 和 `source` 均为必填。`MessageId` 是不透明标识，由用户消息、assistant 消息和工具结果消息共享。消息在创建时就会获得 id，早于 inbox 路由、领取、pre-step 改写、持久追加或请求投影。同一个 id 会跨越每个表示边界。
 
-`createMessage(input)` 是角色通用的规范创建边界。它会生成 `MessageId`，将传入的角色、内容和来源与调用方对象解除引用关系，并在返回完整值前将其深度冻结。`createUserMessage({ content, source })` 为提示词和上下文生产方固定 user 角色。`createAssistantMessage({ content, source })` 同时固定 assistant 角色与模型来源类别，因此模型输出生产方只需提供内容和模型溯源信息。所有创建辅助函数的输入都不包含 id，因此调用方不会意外地把新消息的创建伪装成已有消息的导入。`freezeMessage(message)` 是独立的导入或转换边界：它会将已有标识的消息与调用方对象解除引用关系并深度冻结，不会生成替代标识。
+`createMessage(input)` 是角色通用的规范创建边界。它会生成 `MessageId`，将传入的角色、内容和来源与调用方对象解除引用关系，并在返回完整值前将其深度冻结。`createUserMessage({ content, source })` 为提示词和上下文生产方固定 user 角色。`createAssistantMessage({ content, source })` 同时固定 assistant 角色与模型来源类别，因此模型输出生产方只需提供内容，以及提供方、模型和可选的回放状态。所有创建辅助函数的输入都不包含 id，因此调用方不会意外地把新消息的创建伪装成已有消息的导入。`freezeMessage(message)` 是独立的导入或转换边界：它会将已有标识的消息与调用方对象解除引用关系并深度冻结，不会生成替代标识。
 
 这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整约定只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。
 
@@ -40,7 +40,7 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则
 
 实时 inbox 事件、持久事件、派生历史和模型请求可以关联同一条消息，无需比较内容或使用封装专用 id。待处理输入策略和 UI 附件清理可以在轮次存在之前比较 `MessageId`，领取后则会在已打开的轮次内保留该标识。深度冻结可以防止生产方、钩子或观察方在标识建立后更改消息值。
 
-共享表示移除了旧的 `UserMessageData`/`AgentMessage` 划分，并将提供方溯源信息纳入带类型的消息来源。事件封装仍持有不属于消息语义的事实，例如轮次与步骤位置、token 用量、内部工具失败标识和呈现元数据。
+共享表示移除了旧的 `UserMessageData`/`AgentMessage` 划分，并将提供方、模型和可选的回放状态放入带类型的消息来源。事件封装仍持有不属于消息语义的事实，例如轮次与步骤位置、token 用量、内部工具失败标识和呈现元数据。
 
 消息和辅助函数的单元测试会锁定即时标识、解除输入引用、深度不可变性，以及导入 id 的保留。agent loop 测试会锁定标识跨越准入、inbox 生命周期、持久追加、内容改写和取消的行为；会话测试会锁定冻结派生和保留标识的替换行为。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
index 2bef24442d..e43491d3d1 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.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 .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
-2026-07-29-terminal-llm-stream-failures.md: 1e26973360f07c212016c6a44103448a3510a75b
-2026-07-29-terminal-llm-stream-failures.zh.md: d3eeb0534f6cb8d4d1ad167cca089314eb02b513
+2026-07-29-terminal-llm-stream-failures.md: 3f9fc4255e5b2462e14f73414894c5912191c595
+2026-07-29-terminal-llm-stream-failures.zh.md: a73edd89180b22225eb97804857bd1d3b93a4c4a
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
index 1e26973360..3f9fc4255e 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
@@ -28,10 +28,10 @@ The agent loop consumes one failure representation. It iterates and logs chunks
 
 **Require every adapter to emit failure chunks and forbid throws.** Library iterators, transports, and JavaScript dispatch can still throw. Requiring every adapter to reproduce the same catch boundary duplicates ownership and does not protect a direct `LlmService` consumer from an incomplete implementation.
 
-**Catch every iteration error in the agent loop.** The loop cannot reliably distinguish provider failure from middleware, session append, cancellation, or assembly failure without restoring the same sidecar provenance mechanism. Classification belongs where the adapter call is made.
+**Catch every iteration error in the agent loop.** The loop cannot reliably distinguish provider failure from middleware, session append, cancellation, or assembly failure without restoring a sidecar map from stream objects to the adapter calls that created them. Classification belongs where the adapter call is made.
 
 **Return a `Result` before streaming.** A pre-stream result cannot represent a transport failure after partial output without adding a second response lifecycle. The existing terminal chunk already represents both early and late attempt outcomes.
 
 ## Consequences
 
-All `LlmService.stream()` consumers receive adapter operational failures through one typed terminal protocol, while programming and lifecycle failures retain ordinary exception semantics. Recovery gives up exact thrown-object identity and exposes only detached provider-neutral facts. The stream service owns slightly more adapter plumbing, but consumers delete provenance catches and stream-keyed metadata. Prepared calls carry their policy explicitly, and middleware-only routing remains visibly policy-free.
+All `LlmService.stream()` consumers receive adapter operational failures through one typed terminal protocol, while programming and lifecycle failures retain ordinary exception semantics. Recovery gives up exact thrown-object identity and exposes only detached provider-neutral facts. The stream service owns slightly more adapter plumbing, but consumers delete catches that identify which adapter threw and delete stream-keyed metadata. Prepared calls carry their policy explicitly, and middleware-only routing remains visibly policy-free.
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
index d3eeb0534f..a73edd8918 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
@@ -28,10 +28,10 @@ agent loop 只消费一种失败表示。它不再使用分类 catch，而是直
 
 **要求所有适配器发出失败 chunk，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会重复归属，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。
 
-**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。
+**在 agent loop 中捕获所有迭代错误。** 如果不恢复一张从流对象到创建该对象的适配器调用的 sidecar 映射，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。
 
 **在流式输出前返回 `Result`。** 流前结果无法表示部分输出之后的传输失败，除非增加第二套响应生命周期。现有终止 chunk 已能表示早期和后期尝试结果。
 
 ## Consequences
 
-所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。
+所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了用于识别哪个适配器抛出异常的 catch，也删除了以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
index 752dc0f1aa..e417ee2d89 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.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 .agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
-2026-07-30-adapter-owned-max-token-defaults.md: a522848fd4482f84859e587505b6a5e6f5c72d60
-2026-07-30-adapter-owned-max-token-defaults.zh.md: 8db6a06199fc1c4e73c86492d12dc86edafe8c7e
+2026-07-30-adapter-owned-max-token-defaults.md: c6a784f23a028f500c6e6ff80dc3e13eee93ec1b
+2026-07-30-adapter-owned-max-token-defaults.zh.md: 3caa81126c5d45db7ef5c84540b0deb81764aaf4
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
index a522848fd4..c6a784f23a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
@@ -12,7 +12,7 @@ An LLM adapter could serialize an explicit `GenerateOptions.maxTokens`, but its
 
 `LlmResolvedModelInfo.defaultMaxTokens` carries an optional adapter-configured per-request output cap for one exact provider/model route. `LlmService` validates it as a positive safe integer and materializes it into `LlmCallConfig.maxTokens` only when the caller omitted a value. A prepared call identifies materialized `maxTokens` and `reasoningEffort` fields as adapter defaults; explicit request or Agent options remain unmarked and therefore win without clamping.
 
-The agent loop continues to prepare calls before logging `request/header`, so the effective config and its adapter-default provenance become durable request facts before dispatch. Before the next `agent/request` waterfall, the loop removes marked fields from the proposal; exact-model resolution then materializes the current route's defaults again. A provider/model switch therefore cannot mistake a previous adapter's default for an explicit override, while explicit conversation values persist. Direct `LlmService.stream()` calls resolve the same default at the final adapter boundary. The field is a request default rather than a hard model output limit; adapters that preserve provider-owned defaults omit it.
+The agent loop continues to prepare calls before logging `request/header`, so the effective config and markers for fields supplied by adapter defaults become durable request facts before dispatch. Before the next `agent/request` waterfall, the loop removes marked fields from the proposal; exact-model resolution then materializes the current route's defaults again. A provider/model switch therefore cannot mistake a previous adapter's default for an explicit override, while explicit conversation values persist. Direct `LlmService.stream()` calls resolve the same default at the final adapter boundary. The field is a request default rather than a hard model output limit; adapters that preserve provider-owned defaults omit it.
 
 The native DeepSeek adapter exposes `maxTokens` in Cordis config with a 256,000-token default and maps the effective value to `max_tokens`. Its default context capacity is 1,000,000 tokens: both built-in V4 entries publish that exact capacity, while configured entries without capacity and unlisted pass-through ids inherit the same adapter-wide fallback.
 
@@ -28,6 +28,6 @@ The native DeepSeek adapter exposes `maxTokens` in Cordis config with a 256,000-
 
 ## Consequences
 
-DeepSeek conversations send `max_tokens: 256000` by default, and the same value plus its adapter provenance appear in the session request header. Deployments can change the adapter default through `llm-deepseek.config.maxTokens`; per-agent and per-request values override it. Changing the route rematerializes the new exact adapter's default instead of carrying DeepSeek's derived value forward. Other adapters retain their existing behavior until they intentionally publish `defaultMaxTokens`.
+DeepSeek conversations send `max_tokens: 256000` by default, and the session request header records both the value and that the adapter supplied it. Deployments can change the adapter default through `llm-deepseek.config.maxTokens`; per-agent and per-request values override it. Changing the route rematerializes the new exact adapter's default instead of carrying DeepSeek's derived value forward. Other adapters retain their existing behavior until they intentionally publish `defaultMaxTokens`.
 
 The 256,000-token output budget reserves a large part of the one-million-token context on endpoints that pre-allocate requested output. Deployments whose gateway or model supports a smaller budget must lower `maxTokens`; the explicit configuration is preferable to an undocumented provider fallback.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
index 8db6a06199..3caa81126c 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
@@ -12,7 +12,7 @@ LLM（大语言模型）适配器可以序列化显式的 `GenerateOptions.maxTo
 
 `LlmResolvedModelInfo.defaultMaxTokens` 携带一条确切提供方／模型路由的可选单次请求输出上限，该值由适配器配置。`LlmService` 将其校验为正安全整数，并且仅在调用方省略值时才填入 `LlmCallConfig.maxTokens`。准备后的调用会将已填入的 `maxTokens` 和 `reasoningEffort` 字段标记为适配器默认值；显式请求值或 Agent 选项不带该标记，因此优先且不会被自动调整。
 
-agent loop 仍在记录 `request/header` 前准备调用，因此生效配置及其适配器默认值来源会在分派前成为持久请求事实。下一次 `agent/request` waterfall（瀑布式事件）前，agent loop 会从提议中移除带标记字段，随后精确模型解析会再次填入当前路由的默认值。因此，切换提供方／模型不会把前一个适配器的默认值误当成显式覆盖，而显式对话值则会保留。直接调用 `LlmService.stream()` 时，也会在最终适配器边界解析同一默认值。该字段是请求默认值，而非模型输出硬上限；保留提供方持有默认值的适配器会省略它。
+agent loop 仍在记录 `request/header` 前准备调用，因此生效配置和标明哪些字段由适配器默认值填入的标记，会在分派前成为持久请求事实。下一次 `agent/request` waterfall（瀑布式事件）前，agent loop 会从提议中移除带标记字段，随后精确模型解析会再次填入当前路由的默认值。因此，切换提供方／模型不会把前一个适配器的默认值误当成显式覆盖，而显式对话值则会保留。直接调用 `LlmService.stream()` 时，也会在最终适配器边界解析同一默认值。该字段是请求默认值，而非模型输出硬上限；保留提供方持有默认值的适配器会省略它。
 
 原生 DeepSeek 适配器在 Cordis 配置中公开 `maxTokens`，默认值为 256,000 token，并将生效值映射为 `max_tokens`。其默认上下文容量为 1,000,000 token：两个内置 V4 配置项均公布这一精确容量；不含容量的已配置项和未列出的原样传递 id 则继承同一个适配器级回退值。
 
@@ -28,6 +28,6 @@ agent loop 仍在记录 `request/header` 前准备调用，因此生效配置及
 
 ## Consequences
 
-DeepSeek 对话默认发送 `max_tokens: 256000`，会话请求 header 中也会出现相同的值及其适配器来源。部署可以通过 `llm-deepseek.config.maxTokens` 更改适配器默认值；每个 agent 和每次请求的值都会覆盖它。更改路由会重新填入新的精确适配器默认值，而不是继续沿用 DeepSeek 派生出的值。其他适配器会保留现有行为，直至主动公布 `defaultMaxTokens`。
+DeepSeek 对话默认发送 `max_tokens: 256000`，会话请求 header 会记录该值，并记录该值由适配器提供。部署可以通过 `llm-deepseek.config.maxTokens` 更改适配器默认值；每个 agent 和每次请求的值都会覆盖它。更改路由会重新填入新的精确适配器默认值，而不是继续沿用 DeepSeek 派生出的值。其他适配器会保留现有行为，直至主动公布 `defaultMaxTokens`。
 
 对于预分配请求输出的端点，256,000 token 的输出预算会占用 1,000,000 token 上下文中的很大部分。如果部署使用的 gateway 或模型仅支持较小预算，则必须调低 `maxTokens`；显式配置优于未记录的提供方回退值。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index df37c8aa83..38082cf462 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.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 .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
-2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
-2026-08-08-bounded-session-persistence-write-batching.zh.md: fe1227f7706ba67a12bd7f19db5c0c57cfcfca4f
+2026-08-08-bounded-session-persistence-write-batching.md: 6d77ef90276dcf143bb63019f801379b702b43b2
+2026-08-08-bounded-session-persistence-write-batching.zh.md: 37ebb1566f1826ebbc6fcaf3dca11b65aed3a8ba
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
index 46dc612492..6d77ef9027 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
@@ -8,7 +8,7 @@ English | [中文](2026-08-08-bounded-session-persistence-write-batching.zh.md)
 
 Streaming responses can emit many `assistant/chunk` events in a short interval. The persistence coordinator previously scheduled a backend append as soon as an idle queue received one event. Events arriving while that append was active shared a follow-up batch, but a fast backend could still produce many small durable appends. Each JSONL append creates and syncs a Zstandard frame or raw suffix, while each SQLite append opens and commits a transaction and increments the session revision.
 
-Dropping chunk events or replacing them with assembled messages would reduce logical storage, but it would also change the event log, replay, sequence numbers, timestamps, and provenance. The write-amplification problem does not require that larger semantic change.
+Dropping chunk events or replacing them with assembled messages would reduce logical storage, but it would also change the event log, replay, sequence numbers, timestamps, and the chunk seqs cited by assistant messages. The write-amplification problem does not require that larger semantic change.
 
 ### Quantified baseline
 
@@ -36,7 +36,7 @@ This decision supersedes only the immediate scheduling cadence in [Collapse live
 
 ## Alternatives considered
 
-**Do not persist streaming chunk events.** Rejected here: it changes the event-sourced authority and recovery semantics rather than only physical write cadence. The existing [assembled-message rejection](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md) remains the guardrail until a no-information-loss replacement defines replay, fork, provenance, sequence, and crash behavior independently. The [packed-row decision](2026-07-26-packed-chunk-rows-by-default.md) remains the complementary JSONL storage-size optimization.
+**Do not persist streaming chunk events.** Rejected here: it changes the event-sourced authority and recovery semantics rather than only physical write cadence. The existing [assembled-message rejection](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md) remains the guardrail until a no-information-loss replacement defines replay, fork, cited source-event links, sequence, and crash behavior independently. The [packed-row decision](2026-07-26-packed-chunk-rows-by-default.md) remains the complementary JSONL storage-size optimization.
 
 **Write only at semantic checkpoints.** Rejected: it maximizes batching but makes the ordinary crash-loss window depend on a separately mounted policy. Bounded background writes preserve progress between checkpoints while mandatory flushes keep their stronger ordering contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index fe1227f770..37ebb1566f 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 流式响应可能会在短时间内发出大量 `assistant/chunk` 事件。此前，只要空闲队列收到一个事件，持久化协调器就会立即调度一次后端追加。该追加仍在进行时到达的事件会共用一个后续批次，但如果后端速度很快，仍可能产生大量小规模的持久化追加。每次 JSONL 追加都会创建并同步一个 Zstandard 帧或原始格式后缀，而每次 SQLite 追加都会打开并提交一个事务，同时递增会话修订版本。
 
-丢弃分片事件或用组装后的消息替代它们可以减少逻辑存储量，但也会改变事件日志、回放、序列号、时间戳和来源信息。写放大问题不要求采取这项语义变化更大的方案。
+丢弃分片事件或用组装后的消息替代它们可以减少逻辑存储量，但也会改变事件日志、回放、序列号、时间戳，以及助手消息引用的分片 seq。写放大问题不要求采取这项语义变化更大的方案。
 
 ### 量化基线
 
@@ -36,7 +36,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 ## 备选方案
 
-**不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
+**不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、引用源事件的关联、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
 
 **仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
index 616caa6f68..1c8bb4a7d0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.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 .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
-2026-07-28-load-pre-identity-session-messages.md: 2901527658421b37576bdf5b49e66829104a3b41
-2026-07-28-load-pre-identity-session-messages.zh.md: bf6e58d8a895f41012449a1212533902e1211e99
+2026-07-28-load-pre-identity-session-messages.md: 694bf9ed9ec7a24399b5898665c2222a806f93c6
+2026-07-28-load-pre-identity-session-messages.zh.md: 23f55e1b67f988b6da0ae651f0b53059715eab86
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
index 2901527658..694bf9ed9e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
@@ -28,7 +28,7 @@ The upgrade is read-only. Stored legacy records remain unchanged; a resumed sess
 
 ## Consequences
 
-Pre-identity JSONL and SQLite sessions resume with their original message content, sources, provider provenance, tool correlation, errors, metadata, and surface replacements. The returned events are otherwise indistinguishable from current imported message snapshots and remain deeply frozen.
+Pre-identity JSONL and SQLite sessions resume with their original message content, sources, assistant provider/model fields, tool correlation, errors, metadata, and surface replacements. The returned events are otherwise indistinguishable from current imported message snapshots and remain deeply frozen.
 
 This is one explicit same-version import exception, not a general v0 compatibility layer. Adding another exception requires another complete, unambiguous mapping at the persistence boundary; malformed current data continues to fail rather than being guessed into validity. The shared coordinator contract exercises the upgrade against the in-memory reference, JSONL, and SQLite backends, including deterministic reload and tool-result replacement identity.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
index bf6e58d8a8..23f55e1b67 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 后果
 
-消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
+消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、assistant 的提供方／模型字段、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
 
 这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器约定会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index 69359852c2..0e3118da05 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.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 .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
-2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: 030be076bec9c64ffc97957bbc0fc2b6084d2030
+2026-07-29-human-transcript-append-origin.md: fe60ab6e745fdc08d84deb4a6e2e4fe8168a23e8
+2026-07-29-human-transcript-append-origin.zh.md: b8fe6f6e4b9b5298f9d07bdf395e33e33b4a200d
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
index 9804d3d8d6..fe60ab6e74 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-29-human-transcript-append-origin.zh.md)
 
 ## Problem
 
-The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message` and `assistant/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only provenance and the replacement that cites it.
+The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message` and `assistant/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only `compact/summary` event and the replacement that cites it.
 
 Nothing was lost from the log. `Session.events` still held every original message and full tool result; the surface only decides what the model is sent next. The defect was entirely in the projection.
 
@@ -18,13 +18,13 @@ The terminal replays the transcript from append-origin surface events and keeps
 
 A checkpoint is recognized through the compaction seam's own contract — `isCompactCheckpointSource`, the backend-independent marker `CompactService` requires on the replacement user message — so the terminal depends on the declared vocabulary, not on the shape of the replacement. `dsh-session-reference` already consumes that predicate to project another session's log; this is the same question asked by a different reader. Other replacements are silent: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary in the conversation.
 
-`session.history` counts only append-origin messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` provenance stays on the page of the replacement that cites it.
+`session.history` counts only append-origin messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` event stays on the page of the replacement that cites it.
 
 No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required.
 
 ## Deferred
 
-The browser client is fixed separately, in [the web transcript projection note](2026-07-30-web-transcript-log-ordered-projection.md): it projects the same append-origin transcript in log order and renders a marker component, and it closes the pagination hole this change opened — because `session.history` no longer spends quota on the checkpoint, it never cuts on the checkpoint's provenance group, so a page can carry a checkpoint citing a `surfaceOp.start` outside the window, which the browser's surface fold rejected. That hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page.
+The browser client is fixed separately, in [the web transcript projection note](2026-07-30-web-transcript-log-ordered-projection.md): it projects the same append-origin transcript in log order and renders a marker component, and it closes the pagination hole this change opened — because `session.history` no longer spends quota on the checkpoint, it never cuts on the checkpoint and its cited source events as a unit, so a page can carry a checkpoint citing a `surfaceOp.start` outside the window, which the browser's surface fold rejected. That hole predates this change (counting could already run past a checkpoint into the range it shadows), but when the checkpoint was the oldest counted message, the old pagination rule happened to include the whole shadowed range on the same page.
 
 The terminal's [archived live compaction progress decision](../../archived/feature/2026-07-30-compaction-progress-visibility.md) uses standalone bracket events to drive the existing one-cell indicator. It does not change the completion marker owned here or add scale: the checkpoint's `sourceEventSeqs` remain available for a separately justified count or range. Progress therefore needs neither marker-content changes nor a prerequisite `renderReplacement(event)` extraction.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index 030be076be..b8fe6f6e4b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
+终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志 `compact/summary` 事件与引用它的替换之间。
 
 日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。
 
@@ -18,13 +18,13 @@ Status: implemented
 
 检查点通过压缩接缝自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
-`session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
+`session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 事件会与引用它的替换留在同一页。
 
 持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
 
 ## Deferred
 
-浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。
+浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会在检查点与检查点引用的来源事件这个整体内切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但当检查点是最旧的被计数消息时，旧分页规则会把整段被遮蔽的范围放在同一页。
 
 终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
index fdb487f16b..7bedb71288 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.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 .agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
-2026-07-29-sticky-composer-conversation-scroll.md: 8657080078e475d6e90f17a6c0f8cb5b2fb1555d
+2026-07-29-sticky-composer-conversation-scroll.md: d628e10979318ba371d56f61c5e96363b4135ad7
 2026-07-29-sticky-composer-conversation-scroll.zh.md: a588903adf51c6fcdd01f851d4f5e6570f695242
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
index 8657080078..d628e10979 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
@@ -26,7 +26,7 @@ Chat history prepend follows reader intent through stable rendered node/call ide
 
 **Keep StatsLine inside ChatView below the message column.** Rejected: outside the sticky composer it would scroll away while the input stayed pinned.
 
-**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership were left outside the provenance model instead of adding a general input state machine. The [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) later closed this deferral by generalizing attribution through the observed-top ledger, still without an input state machine.
+**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership were left outside the input-source model instead of adding a general input state machine. The [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) later closed this deferral by generalizing attribution through the observed-top ledger, still without an input state machine.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 17c4315966..a14b575c0f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 024d7dba7db7f06a684f5656abf7421e65cd4536
+2026-07-30-web-transcript-log-ordered-projection.md: dbc3f9e23be9120df62c2b6b7a9d9aba4c3a42a9
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 329392c47d69c4cf3506a5e14ca0ef48d35dce4c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index 3b7aaeb117..dbc3f9e23b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -18,7 +18,7 @@ Node order is seq-monotonic by construction, and three things follow. The log-on
 
 `foldDegraded` is gone from `ConversationSnapshot`, and with it the padding sentinels, the `baseSeq` arithmetic they needed, and `degradedSeqs()`. They existed only to satisfy the core fold's `seq === index` assertion and to survive its throw; the fold they describe is no longer run. Deleting the flag is part of the fix, not cleanup after it — `degradedSeqs()` was already almost the log-ordered projection, reached after a thrown error instead of intended.
 
-The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's own `compact/summary` provenance, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left the provenance outside makes those fields unavailable, the same soft-fall as a call-less tool result, and a later page supplying the provenance resolves them.
+The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left that event outside makes those fields unavailable, the same soft-fall as a call-less tool result, and a later page supplying the event resolves them.
 
 The [manual compaction command](../feature/2026-07-30-queued-manual-compaction.md) returns the summary event's seq as the successful `CommandResult.sourceEventSeq`, and `command/done` persists that optional reference. Chat pairs only a successful named `/compact` command whose reference equals exactly one loaded `CompactionSummaryNode.summaryEventSeq`. The running command first renders `compact · Compacting context…`; after the checkpoint lands, the same React key renders one collapsed `compact` disclosure at the checkpoint's flow position with the count and token estimate. Input rejection, no compactable history, cancellation, and failure remain generic command rows with complete handler-authored text. Automatic compaction has no command reference and keeps the standalone context-compacted marker.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 024d7dba7d..329392c47d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -18,7 +18,7 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 
 `foldDegraded` 从 `ConversationSnapshot` 消失，随之消失的是哨兵填充、它们所需的 `baseSeq` 算术，以及 `degradedSeqs()`。它们的存在只为满足核心 fold 的 `seq === index` 断言并在其抛错时存活；它们所描述的 fold 已不再运行。删除该标志是修复的一部分，而非修复之后的清理——`degradedSeqs()` 本身已几乎就是按日志顺序的投影，只是作为抛错后的落点而非本意到达。
 
-标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点自己的 `compact/summary` 溯源，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把溯源留在窗口外时这些字段不可用，与无调用的工具结果同一种软退让；后续补上溯源的分页会解析出它们。
+标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把该事件留在窗口外时这些字段不可用，与无调用的工具结果同一种软退让；后续补上该事件的分页会解析出它们。
 
 [手动压缩命令](../feature/2026-07-30-queued-manual-compaction.md)会把摘要事件的 seq 作为成功结果的 `CommandResult.sourceEventSeq` 返回，`command/done` 则持久化这项可选引用。Chat 只会配对成功且名称为 `/compact`、其引用恰好等于唯一一个已加载 `CompactionSummaryNode.summaryEventSeq` 的命令。运行中的命令先渲染为 `compact · Compacting context…`；检查点落地后，同一个 React key 会在检查点的消息流位置渲染一条收起的 `compact` 展开项，并显示条目数量和 token 估算值。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行，并保留处理器撰写的完整文本。自动压缩没有命令引用，继续使用独立的上下文已压缩标记。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
index 8aab23d8a2..ac37eaded2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.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 .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
-2026-08-04-load-pre-react-loop-sessions.md: b7dcad1ff7fe0aa8239ac03f52b50dfa55417515
-2026-08-04-load-pre-react-loop-sessions.zh.md: 9dc8666d301b3baf454079498bf3ad7e1f510c96
+2026-08-04-load-pre-react-loop-sessions.md: 277a481f366f1182fd3948caf858607efd550e5e
+2026-08-04-load-pre-react-loop-sessions.zh.md: 0d21ef1a97c5e841609406b9c8ed4723e6da09b1
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
index b7dcad1ff7..277a481f36 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
@@ -24,7 +24,7 @@ The importer does not synthesize inbox splices. A resumed pre-react-loop agent b
 
 **Replay old inbox notifications into durable splices.** Those notifications were not session events and do not provide a trustworthy pending-state snapshot. Inferring insertions without every claim and discard would re-run consumed work.
 
-**Assign coarse aborted records to an existing caller.** Mapping them to `user`, `parent`, or `hook` would manufacture provenance. A dedicated `legacy` cause keeps the stop classification without making a false audit claim.
+**Assign coarse aborted records to an existing caller.** Mapping them to `user`, `parent`, or `hook` would invent a caller that the old record did not name. A dedicated `legacy` cause keeps the stop classification without making a false audit claim.
 
 **Rewrite stored JSONL and SQLite records.** A rewrite would violate the append-only contract and require backend-specific atomic migration machinery for a read compatibility boundary.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
index 9dc8666d30..0d21ef1a97 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
@@ -24,7 +24,7 @@ react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持
 
 **将旧 inbox 通知回放为持久 splice。** 这些通知不是会话事件，也无法提供可信的待处理状态快照。如果无法获知每一次领取和丢弃，就推断插入操作，会让已消费的工作再次执行。
 
-**将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会虚构来源。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
+**将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会凭空指定旧记录未注明的调用方。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
 
 **重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立后端专用的原子迁移机制。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
index dfaaea4ab7..1c3faea34f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.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 .agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
-2026-08-05-context-meter-blind-to-compaction.md: 8f4845c3c9bf52c5c3a2d39dee2ff25bda30c7bd
-2026-08-05-context-meter-blind-to-compaction.zh.md: 94ada0a9118db63876d5805ef5a8197d9c764102
+2026-08-05-context-meter-blind-to-compaction.md: 10ded250cec9c92d90803bdf5969cc7f5aa54c50
+2026-08-05-context-meter-blind-to-compaction.zh.md: 1508a907e6a71b465a2b9aed137f40bb8e539ae5
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
index 8f4845c3c9..10ded250ce 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
@@ -27,7 +27,7 @@ This reverses the "the ring, header, and bar length stay provider-exact" half of
 
 ## Alternatives considered
 
-**Project `measure().totalTokens` instead.** The measurement service already composes exactly this (`baseline` anchor plus signed `surfaceDeltaTokens`), and it reacts correctly — measured at 4383 → 304 across the same compaction. But it is a service over private replay state, not a pure fold, and a projection cannot call it. Reproducing its anchor inside a `ProjectionDefinition` needs `_estimateProviderAssistant`'s random access to the chunk provenance (`session.events[seq]`), which `apply(state, event)` does not have. Anchoring on the sampled surface total is the same idea reachable from a pure per-event fold.
+**Project `measure().totalTokens` instead.** The measurement service already composes exactly this (`baseline` anchor plus signed `surfaceDeltaTokens`), and it reacts correctly — measured at 4383 → 304 across the same compaction. But it is a service over private replay state, not a pure fold, and a projection cannot call it. Reproducing its anchor inside a `ProjectionDefinition` needs `_estimateProviderAssistant`'s random access to the chunk events cited by seq (`session.events[seq]`), which `apply(state, event)` does not have. Anchoring on the sampled surface total is the same idea reachable from a pure per-event fold.
 
 **Emit a synthetic usage record at the end of compaction.** Would move `pressureTokens` itself, but the only usage compaction holds is the summarization request's own — a different prompt entirely. Recording it as the conversation's prompt size would be a lie in the durable log rather than in one display.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
index 94ada0a911..1508a907e6 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
@@ -27,7 +27,7 @@ AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messag
 
 ## 备选方案
 
-**改为投影 `measure().totalTokens`。** 测量服务本来就合成了正是这个量（`baseline` 锚点加有符号的 `surfaceDeltaTokens`），而且反应正确——同一次压缩前后实测为 4383 → 304。但它是一个建立在私有重放状态上的服务，不是纯折叠，投影无法调用它。要在 `ProjectionDefinition` 内部复现它的锚点，需要 `_estimateProviderAssistant` 对分片来源的随机访问（`session.events[seq]`），而 `apply(state, event)` 拿不到。以取样时的表层总量作为锚点，是同一个思路在纯逐事件折叠中可达的版本。
+**改为投影 `measure().totalTokens`。** 测量服务本来就合成了正是这个量（`baseline` 锚点加有符号的 `surfaceDeltaTokens`），而且反应正确——同一次压缩前后实测为 4383 → 304。但它是一个建立在私有重放状态上的服务，不是纯折叠，投影无法调用它。要在 `ProjectionDefinition` 内部复现它的锚点，需要 `_estimateProviderAssistant` 对按 seq 引用的分片事件进行随机访问（`session.events[seq]`），而 `apply(state, event)` 拿不到。以取样时的表层总量作为锚点，是同一个思路在纯逐事件折叠中可达的版本。
 
 **在压缩结束时补写一条合成的用量记录。** 这确实能推动 `pressureTokens` 本身，但压缩手上唯一的用量是摘要请求自己的用量——那是完全另一个提示词。把它记成本对话的提示词规模，等于把谎言写进持久日志，而不只是写进某一处展示。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
index 2982e05c65..d7e6553fd3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.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 .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
-2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
+2026-08-06-reader-scroll-attribution-observed-top-ledger.md: ef5ddbeb9bea1393f474dfb4c809ae2e19bfea5c
 2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: 7a1142cdd793cfce46bfd3908ab28345701aec7a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
index 2dcd0178e4..ef5ddbeb9b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.m
 
 ## Problem
 
-ChatView's bottom-follow recognized only wheel/trackpad gestures as reader input: while pinned to the floor, a scroll event without matching wheel movement was treated as programmatic and snapped back. Touch panning, native-scrollbar dragging, and keyboard paging therefore could not leave the bottom of a streaming transcript — on a phone the tail was effectively locked. That wheel-only provenance was a deliberate deferral in the [sticky-composer note](2026-07-29-sticky-composer-conversation-scroll.md), which rejected a general input state machine "for this narrow fix" and left every other scroll source outside the model.
+ChatView's bottom-follow recognized only wheel/trackpad gestures as reader input: while pinned to the floor, a scroll event without matching wheel movement was treated as programmatic and snapped back. Touch panning, native-scrollbar dragging, and keyboard paging therefore could not leave the bottom of a streaming transcript — on a phone the tail was effectively locked. That wheel-only input classification was a deliberate deferral in the [sticky-composer note](2026-07-29-sticky-composer-conversation-scroll.md), which rejected a general input state machine "for this narrow fix" and left every other scroll source outside the model.
 
 ## Decision
 
@@ -34,4 +34,4 @@ The lane's Chromium cannot synthesize any non-wheel device scrolling, which boun
 
 ## Consequences
 
-Every reader input owns bottom-follow uniformly, with less code: the wheel listener, its epoch counter, and the pre-input baseline bookkeeping are gone, and attribution rides state the component already maintained. The sticky-composer note's layout, wheel chaining, and prepend-anchoring decisions are untouched and remain authoritative; its narrow provenance rule is superseded by this note. The cost is the contract change above — a coalesced non-React shrink-plus-regrow clamp now pauses follow until the reader returns to the floor or presses Back to bottom — traded for touch, scrollbar, and keyboard correctness during streaming. The e2e lane gains non-wheel coverage only within what its browser can synthesize; if gesture synthesis starts working in a future Chromium, the fling emulation can be replaced by real touch strokes without changing the asserted contract.
+Every reader input owns bottom-follow uniformly, with less code: the wheel listener, its epoch counter, and the pre-input baseline bookkeeping are gone, and attribution rides state the component already maintained. The sticky-composer note's layout, wheel chaining, and prepend-anchoring decisions are untouched and remain authoritative; its wheel-only input rule is superseded by this note. The cost is the contract change above — a coalesced non-React shrink-plus-regrow clamp now pauses follow until the reader returns to the floor or presses Back to bottom — traded for touch, scrollbar, and keyboard correctness during streaming. The e2e lane gains non-wheel coverage only within what its browser can synthesize; if gesture synthesis starts working in a future Chromium, the fling emulation can be replaced by real touch strokes without changing the asserted contract.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 60a89e6fab..c23637d7e3 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
-2026-06-18-compaction-capability-seam.zh.md: 297b9adda4f13f6fd4da9e73bf2bcf3d8d6ead0c
+2026-06-18-compaction-capability-seam.md: fa9325d08fa73dd1654216d211abb03cdf1a0940
+2026-06-18-compaction-capability-seam.zh.md: d8522f3714211f23bafb201e7354e8b0fc2f5fb1
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 390d091fd6..fa9325d08f 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-18-compaction-capability-seam.zh.md)
 
 A long-running agent conversation grows without bound. As the event log accumulates turns, the derived message history eventually approaches the model's context window — the model then truncates mid-response (`max-tokens`) or degrades. **Compaction** is the mitigation: replace a run of older history with a concise summary, keeping recent context intact.
 
-The [session surface](../architecture/2026-06-18-session-surface.md) was built as the foundation for exactly this — an ordered projection over the event log with a `surfaceOp: { op: 'replace', start, end }` operation purpose-built to shadow a range of entries and insert a replacement, with `sourceEventSeqs` recording provenance so the decision replays deterministically. What remained was the plugin that *decides what to compact and produces the summary*.
+The [session surface](../architecture/2026-06-18-session-surface.md) was built as the foundation for exactly this — an ordered projection over the event log with a `surfaceOp: { op: 'replace', start, end }` operation purpose-built to shadow a range of entries and insert a replacement, with `sourceEventSeqs` listing every source event so replay can validate that the replacement cites every event it removes. What remained was the plugin that *decides what to compact and produces the summary*.
 
 Two forces shape the design. First, compaction policy and reusable token measurement vary independently: measurement belongs to the LLM-family [`ctx.tokenMeter` service](../architecture/2026-07-15-replay-token-meter-service.md), while summarization can be a model call, a template, or a remote service. Second, `SurfaceEventType` is closed to the message-producing event types (`user/message`, `assistant/message`, `tool/result`); only those may carry `surfaceOp`. A bespoke `compaction/*` event therefore **cannot** itself appear on the surface — the compiler and Session's always-on append/seed boundary reject `surfaceOp` on it.
 
@@ -71,12 +71,12 @@ Auto-compaction always starts at the surface head, merging the prior checkpoint
 
 ### Surface replacement: `compact/*` events are log-only; one `user/message` carries the summary
 
-Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` event. The backend instead appends a **single `user/message`** with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` whose `content` is the (framed) summary and whose `sourceEventSeqs` covers the shadowed entries *and* the bookkeeping events. The interface exports that source and `isCompactCheckpointSource()` so consumers recognize a persisted or cloned checkpoint without depending on backend package identity. The `compact/*` events are pure log records (lock + provenance). The surface mutation sits **inside** the lock — `compact/end` is the last event appended:
+Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` event. The backend instead appends a **single `user/message`** with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` whose `content` is the (framed) summary and whose `sourceEventSeqs` covers the shadowed entries *and* the bookkeeping events. The interface exports that source and `isCompactCheckpointSource()` so consumers recognize a persisted or cloned checkpoint without depending on backend package identity. The `compact/*` events record the lock, summary, selected range, shadowed seqs, token count, and model call without joining the surface. The surface mutation sits **inside** the lock — `compact/end` is the last event appended:
 
 ```
 compact/start    → log-only. Acquires the lock.
 [summarize older range via the backend]
-compact/summary  → log-only. Provenance: raw summary, local-call marker, range, shadowed seqs, token count.
+compact/summary  → log-only. Records the raw summary, local-call marker, range, shadowed seqs, and token count.
 user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
                    THE surface mutation (framed summary).
                    deriveMessages() renders it as a user-role message.
@@ -93,7 +93,7 @@ The basic backend wraps the summary as established checkpoint context and tags i
 
 The `compact/start … compact/end` bracket is justified by two roles:
 
-1. **Crash-detectable orphan + provenance** (primary). Summarization is a slow model call persisted *after* `compact/start`. A crash mid-summarization leaves a `compact/start` with no matching `compact/end` — a detectable orphan. Releasing the lock last (rather than first) converts the crash window from *silent corruption* into that detectable orphan.
+1. **Crash-detectable orphan plus recorded summary inputs** (primary). Summarization is a slow model call persisted *after* `compact/start`. A crash mid-summarization leaves a `compact/start` with no matching `compact/end` — a detectable orphan. Releasing the lock last (rather than first) converts the crash window from *silent corruption* into that detectable orphan.
 2. **Prevents concurrent compaction.** Every automatic, manual, and explicit-range entry point refuses a live unmatched `compact/start`. The bracket is the single lock; no process-local mutex duplicates it.
 
 The lock excludes another compaction, not unrelated facts. Its markers are time points rather than an exclusive container, so durable inbox splices may appear between a standalone manual start and end. Automatic work requires whole-surface stability inside its turn. Manual work revalidates only the selected positional span, letting append-only context outside it remain visible after replacement.
@@ -122,7 +122,7 @@ The lifecycle boundary makes crash state unambiguous:
 - **Automatic seams**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
 - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry.
 - **`dsh-compact`** owns `COMPACT_CHECKPOINT_SOURCE`, `isCompactCheckpointSource(source)`, `toolPairingBalancedBefore(session, seq)`, and `toolPairingBalancedAfter(session, seq)`. The marker identifies replacement summaries across backend implementations. The cached surface-edge checks prevent `compactRegion` and `compactIfNeeded` from splitting a tool-call/result pair, validate current membership by seq, answer both edges from one per-cut balance sequence, and reject stale or missing seqs and orphan results.
-- **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.
+- **`dsh-session`** validates positional replacement, complete cited source-event coverage, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.
 - **Wiring**: `examples/tui-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, `dsh-compact-basic`, then `dsh-command-compact`; service-wide defaults make the composition usable without repeated numeric policy.
 
 ## Testing
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 297b9adda4..d8522f3714 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 长时间运行的 agent（智能体）对话会无限增长。随着事件日志不断累积轮次，派生出的消息历史最终逼近模型的上下文窗口，模型随即截断响应（`max-tokens`）或性能退化。**上下文压缩（context compaction）** 是对此的缓解手段：用一段简洁的摘要替换一批较早的历史，保持近期上下文完整。
 
-[会话接口面](../architecture/2026-06-18-session-surface.md)正是为此而构建的基础设施：一份建立在事件日志之上的有序投影，带有专门设计的 `surfaceOp: { op: 'replace', start, end }` 操作，用于遮蔽一段条目并插入替换内容，`sourceEventSeqs` 记录溯源信息以便决策可确定性地回放。剩下的是那个*决定压缩什么、并产出摘要*的插件。
+[会话接口面](../architecture/2026-06-18-session-surface.md)正是为此而构建的基础设施：一份建立在事件日志之上的有序投影，带有专门设计的 `surfaceOp: { op: 'replace', start, end }` 操作，用于遮蔽一段条目并插入替换内容，`sourceEventSeqs` 列出每个来源事件，使回放可以验证替换是否引用了它移除的每个事件。剩下的是那个*决定压缩什么、并产出摘要*的插件。
 
 两股力量塑造了设计。第一，压缩策略与可复用的 token 测量独立变化：测量归 LLM 系列的 [`ctx.tokenMeter` 服务](../architecture/2026-07-15-replay-token-meter-service.md)所有，摘要生成则可以使用模型调用、模板或远程服务。第二，`SurfaceEventType` 封闭为产生消息的事件类型（`user/message`、`assistant/message`、`tool/result`）；只有这些类型可以携带 `surfaceOp`。因此一个专用的 `compaction/*` 事件**不能**出现在 surface 上，编译器与 Session 始终启用的 append/seed 边界都会拒绝在其上附加 `surfaceOp`。
 
@@ -71,12 +71,12 @@ retry → next numbered step/start      ⟵ derives from the replacement surface
 
 ### Surface 替换：`compact/*` 事件仅存在于日志；一条 `user/message` 承载摘要
 
-由于 `SurfaceEventType` 是封闭的，摘要不能搭载在 `compact/*` 事件上。后端改为追加一条**单独的 `user/message`**，带有 `source: COMPACT_CHECKPOINT_SOURCE` 和 `surfaceOp: { op: 'replace', start, end }`；其 `content` 是（带框架的）摘要，`sourceEventSeqs` 覆盖被遮蔽的条目*和*簿记事件。接口导出该来源和 `isCompactCheckpointSource()`，使消费方无需依赖后端包身份，即可识别持久化或克隆得到的检查点。`compact/*` 事件是纯日志记录（锁 + 溯源信息）。surface 变更位于锁**内部**，`compact/end` 是最后追加的事件：
+由于 `SurfaceEventType` 是封闭的，摘要不能搭载在 `compact/*` 事件上。后端改为追加一条**单独的 `user/message`**，带有 `source: COMPACT_CHECKPOINT_SOURCE` 和 `surfaceOp: { op: 'replace', start, end }`；其 `content` 是（带框架的）摘要，`sourceEventSeqs` 覆盖被遮蔽的条目*和*簿记事件。接口导出该来源和 `isCompactCheckpointSource()`，使消费方无需依赖后端包身份，即可识别持久化或克隆得到的检查点。`compact/*` 事件记录锁、摘要、选中区间、被遮蔽的 seq、token 数和模型调用，但不加入 surface。surface 变更位于锁**内部**，`compact/end` 是最后追加的事件：
 
 ```
 compact/start    → log-only. Acquires the lock.
 [summarize older range via the backend]
-compact/summary  → log-only. Provenance: raw summary, local-call marker, range, shadowed seqs, token count.
+compact/summary  → log-only. Records the raw summary, local-call marker, range, shadowed seqs, and token count.
 user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
                    THE surface mutation (framed summary).
                    deriveMessages() renders it as a user-role message.
@@ -93,7 +93,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 
 `compact/start … compact/end` 标记对承担两项职责：
 
-1. **可检测的崩溃孤儿 + 来源追溯**（首要）。摘要生成是一次慢速模型调用，持久化在 `compact/start` *之后*。摘要生成中途崩溃会留下一个没有匹配 `compact/end` 的 `compact/start`——一个可检测的孤儿。最后释放锁（而非最先）将崩溃窗口从*静默损坏*转变为可检测的孤儿。
+1. **可检测的崩溃孤儿 + 已记录的摘要输入**（首要）。摘要生成是一次慢速模型调用，持久化在 `compact/start` *之后*。摘要生成中途崩溃会留下一个没有匹配 `compact/end` 的 `compact/start`——一个可检测的孤儿。最后释放锁（而非最先）将崩溃窗口从*静默损坏*转变为可检测的孤儿。
 2. **防止并发压缩。** 每个自动、手动和显式范围入口点都会拒绝活动的未匹配 `compact/start`。该标记对就是唯一的锁；没有进程本地 mutex 重复承担同一职责。
 
 该锁只排除另一项压缩，不排除无关事实。其标记是时间点，而不是排他的容器，因此持久 inbox splice 可以出现在独立手动 start 与 end 之间。自动工作要求其轮次内的整个 surface 保持稳定。手动工作只重新验证所选位置 span，使其外部的仅追加上下文在替换后保持可见。
@@ -122,7 +122,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 - **自动 seam**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
 - **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
 - **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。
-- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、完整溯源信息和仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。
+- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、引用的来源事件是否覆盖完整，以及仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。
 - **接线**：`examples/tui-agent/cordis.yml` 依次加载零配置的 `dsh-token-meter`、`dsh-compact-tool-result-prune`、`dsh-compact-basic`，然后加载 `dsh-command-compact`；服务级默认值使组合无需重复数值策略即可使用。
 
 ## 测试
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 5002872c0b..5982d816f9 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
-2026-07-06-sandbox.zh.md: 85b9b6a65b6468b19c6044b4837abc4fab1cee1a
+2026-07-06-sandbox.md: d73bb5520ffba43142c70e3197ae033db1af67d9
+2026-07-06-sandbox.zh.md: 5fc2ee7c4a53df22fab93c358824a10dca89989e
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 06c5590454..d73bb5520f 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -70,7 +70,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La
 
 #### The bash consumer
 
-`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection is runner-owned only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with positive provenance for provider argv[0]; a bare `syscall: 'spawn'` without an exact error path, other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner-owned rejections to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same provenanced shape makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code gate and a remaining fatal line after informational exclusions. A match outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
+`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection is runner-owned only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` whose error path equals provider argv[0]; a bare `syscall: 'spawn'` without an exact error path, other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner-owned rejections to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same shape with the runner path makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code gate and a remaining fatal line after informational exclusions. A match outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
 
 The model sees the current effective file policy in the owner-derived `sandbox:policy` context, while the static tool description explains the denial marker (`[sandbox: file access denied under <mode> mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](2026-07-30-current-sandbox-policy-context.md) owns the context's rationale and boundaries.
 
@@ -185,7 +185,7 @@ Costs and accepted limits:
 ## FAQ
 
 - **A command came back with `[sandbox: file access denied under read-only mode]` — did it fail?** It RAN, and the kernel refused a file effect: the denial is a result fact orthogonal to exit code. The teaching forbids retrying around it; the one sanctioned move is the same command retried once with an escalation request.
-- **How is a BROKEN sandbox told apart from a failing command?** Any provider-argv spawn rejection proves the confined launch never started, but it identifies a broken runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]. A bare `syscall: 'spawn'` without an exact error path and all other rejections remain ordinary command-start errors. After a process starts, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground failures throw structured `SANDBOX_UNAVAILABLE` with spawn or matched-line detail; an asynchronously rejected or settled background task stamps `sandbox.runnerFailed` and renders its own marker. A `SubprocessService` that synchronously throws the same provenanced `ENOENT`/`EACCES` shape makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result.
+- **How is a BROKEN sandbox told apart from a failing command?** Any provider-argv spawn rejection proves the confined launch never started, but it identifies a broken runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]. A bare `syscall: 'spawn'` without an exact error path and all other rejections remain ordinary command-start errors. After a process starts, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground failures throw structured `SANDBOX_UNAVAILABLE` with spawn or matched-line detail; an asynchronously rejected or settled background task stamps `sandbox.runnerFailed` and renders its own marker. A `SubprocessService` that synchronously throws the same `ENOENT`/`EACCES` shape with the runner path makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result.
 - **What happens on a platform with no backend — Windows today?** `confine()` throws the fail-closed `SANDBOX_UNAVAILABLE` and the command never spawns; `win32` is a reserved EMPTY chain, pinned by test to fail closed identically until a Windows runner fills it (§ Deferred phases).
 - **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the packaged Landlock launcher, and the verdict is cached for the provider's lifetime.
 - **Does the sandbox restrict network or process visibility?** No — `SandboxMode` claims FILE effects only; the bwrap profile deliberately does not unshare pid, and no backend claims network. Whether network restriction becomes its own knob is left open in § The seam.
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 85b9b6a65b..5fc2ee7c4a 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -70,7 +70,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 
 
 #### bash 消费方
 
-`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且带有明确指向提供方 argv[0] 的来源信息时，拒绝才会归因于 runner；没有精确错误路径的裸 `syscall: 'spawn'`、其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将可归因于 runner 的拒绝转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码门控与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
+`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，拒绝才会归因于 runner；没有精确错误路径的裸 `syscall: 'spawn'`、其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将可归因于 runner 的拒绝转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样带有 runner 路径的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码门控与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
 
 模型会在归属方派生的 `sandbox:policy` 上下文中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under <mode> mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](2026-07-30-current-sandbox-policy-context.md)负责该上下文的理由与边界。
 
@@ -185,7 +185,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 ## FAQ
 
 - **一个命令返回了 `[sandbox: file access denied under read-only mode]`——它失败了吗？** 它运行了，内核拒绝了一个文件操作：拒绝是与退出码正交的结果事实。相关指令禁止通过绕过限制来重试；唯一被认可的动作是以升级请求重试同一命令一次。
-- **如何区分损坏的沙箱与失败的命令？** 提供方 argv 的任何 spawn 拒绝都能证明受限启动从未开始，但只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 runner 损坏。没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有拒绝仍是普通的命令启动错误。进程启动后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台失败会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 spawn 错误或匹配行作为详细信息；遭异步拒绝或已结算的后台任务则盖章 `sandbox.runnerFailed` 并渲染自己的标记。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。
+- **如何区分损坏的沙箱与失败的命令？** 提供方 argv 的任何 spawn 拒绝都能证明受限启动从未开始，但只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 runner 损坏。没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有拒绝仍是普通的命令启动错误。进程启动后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台失败会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 spawn 错误或匹配行作为详细信息；遭异步拒绝或已结算的后台任务则盖章 `sandbox.runnerFailed` 并渲染自己的标记。如果 `SubprocessService` 同步抛出同样带有 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。
 - **在没有后端的平台上会发生什么——今天的 Windows？** `confine()` 抛出失败关闭的 `SANDBOX_UNAVAILABLE`，命令永不 spawn；`win32` 是保留的空链，由测试固定为同样失败关闭，直到 Windows runner 填充它（§ 延迟阶段）。
 - **`bwrap` 已安装在我的主机上但不可用（禁用了非特权 userns、LSM 拒绝 `mount`）——会发生什么？** 链探测是功能性的——它构建并强制一个真实 profile 而非检查 `--version`——因此存在但不可用的 `bwrap` 探测失败，选择落到已打包的 Landlock launcher，结论在提供方生命周期内缓存。
 - **沙箱限制网络或进程可见性吗？** 不——`SandboxMode` 仅声称文件操作；bwrap profile 刻意不 unshare pid，没有后端声称网络。网络限制是否成为自己的旋钮留在 § seam 中开放。
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 2032c54723..3023f86bba 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: a2f614cc5a236e45622eae2b30f518181331cc79
-2026-07-08-self-referential-cordis-toolset.zh.md: 6c56c2bf0c8cc8d175f451290620d9386bb69a23
+2026-07-08-self-referential-cordis-toolset.md: 5fc2fb07fcd0b00bf72c818d3806b298312cdc31
+2026-07-08-self-referential-cordis-toolset.zh.md: 8f34c97d94cad9b79a0e823406c07cdcfb38793f
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index a2f614cc5a..5fc2fb07fc 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -75,7 +75,7 @@ The correctness investment therefore goes where it pays for every capability at
 
 **A hand-maintained service/event reference in the tool.** The first cut of the inspect tool carried a hand-written table of service method signatures. It was replaced by the generated `api-catalog.ts` because a hand table drifts from the JSDoc the moment a signature changes and nothing gates the drift, whereas the generated artifact is freshness-checked against the same AST the docs use.
 
-**A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a full changed request header, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call.
+**A new `cordis/mount` session event.** A durable event recording each mount's source and name has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a full changed request header, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs the mount source and name outside the tool call.
 
 **A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *surface* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime.
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index 6c56c2bf0c..8f34c97d94 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -75,7 +75,7 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 **在工具中手工维护服务/事件参考。** inspect 工具的第一版携带了一份手写的服务方法签名表。它被生成的 `api-catalog.ts` 取代，因为手写表在签名变化的瞬间就会与 JSDoc 脱节且没有门禁约束这种漂移，而生成产物的新鲜度由文档使用的同一套 AST 检查。
 
-**新增 `cordis/mount` 会话事件。** 一个持久的溯源事件记录每次挂载（源码、名称）有明确先例（`hook/invoked`、`compact/start`）。v1 中予以否决：挂载和卸载已经作为 `tool/call` / `tool/result` 对可见，工具集变化已经作为完整的变更 request header 被记录，因此专用事件只会重复记录。如果审计用例需要将挂载溯源从工具调用中分离出来，日后仍可添加。
+**新增 `cordis/mount` 会话事件。** 一个持久事件记录每次挂载的源码和名称，有明确先例（`hook/invoked`、`compact/start`）。v1 中予以否决：挂载和卸载已经作为 `tool/call` / `tool/result` 对可见，工具集变化已经作为完整的变更 request header 被记录，因此专用事件只会重复记录。如果审计用例需要在工具调用之外取得挂载的源码和名称，日后仍可添加。
 
 **加固的/能力受限的沙箱。** 对 Node 内置模块设陷阱并向挂载代码提供白名单门面而非原始上下文，可能暗示意图是为安全而沙箱化。这里明确不是：陷阱和门面收窄的是挂载代码所见的*接口面*——将其引导至 cordis 服务、远离易泄漏的 Node 内置模块和框架内部——目的是正确性和封堵未受保护的上下文逃逸，但门面暴露的能力（`ctx.bash`、`ctx.fs`、`ctx.web`）触及真实运行时，因此它不是安全边界。真正的安全边界（独立进程、权限提示）超出了一个开发/显式启用工具集的范围，且会与其核心目的——将活跃运行时交给模型——相冲突。
 
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
index f2d337c93c..a1f605b52b 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.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 .agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
-2026-07-13-session-query-tracing.md: 47c12824a331546676d3bc79920f861afe648431
-2026-07-13-session-query-tracing.zh.md: f578a69a3004722395d5b731f82482b8ebd548e5
+2026-07-13-session-query-tracing.md: 66ec68cff116c973c723ee086cdb273f9375842b
+2026-07-13-session-query-tracing.zh.md: 6a39a9857d30ea7911a313bff5504d4f5ae04562
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
index 47c12824a3..66ec68cff1 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-13-session-query-tracing.zh.md)
 
 ## Problem
 
-Session relationships are encoded across immutable headers, positional surface operations, and logged provenance arrays. A consumer reconstructing those relationships directly would need to duplicate corpus precedence, surface folding, malformed-log handling, deterministic lineage ordering, and cloning. Positional replacement and provenance are different graphs, so collapsing them into one generic edge type would also lose meaning.
+Session relationships are encoded across immutable headers, positional surface operations, and logged arrays of cited source-event seqs. A consumer reconstructing those relationships directly would need to duplicate corpus precedence, surface folding, malformed-log handling, deterministic lineage ordering, and cloning. Positional replacement and cited-source relationships mean different things, so collapsing them into one generic edge type would also lose meaning.
 
 ## Decision
 
@@ -14,20 +14,20 @@ Session relationships are encoded across immutable headers, positional surface o
 
 `SessionLineageTrace` returns the target, known parents in immediate-to-outward order, and recursive descendant trees whose siblings sort by creation time and then session id. `complete: true` carries the known root; `complete: false` carries the first unresolved parent id. A cycle connected to the target fails with `SESSION_QUERY_INVALID_LINEAGE`.
 
-`SessionEventTrace` keeps positional and provenance relationships separate. `replacedBy` is the immediate positional replacer, `replacementChain` follows replacers to the final node, and `replacedEventSeqs` lists the actual surface nodes directly removed by the target. `sourceEventSeqs` preserves direct logged source order, while `derivedEventSeqs` lists later direct reverse references in log order. Provenance is not expanded transitively.
+`SessionEventTrace` keeps positional replacements separate from cited source-event relationships. `replacedBy` is the immediate positional replacer, `replacementChain` follows replacers to the final node, and `replacedEventSeqs` lists the actual surface nodes directly removed by the target. `sourceEventSeqs` preserves direct logged source order, while `derivedEventSeqs` lists later direct reverse references in log order. The query does not follow cited source events transitively.
 
 ## Validation boundary
 
-Event tracing checks target existence before surface analysis. Both event listing and tracing then use `dsh-session`'s one-pass surface fold, which accepts or rejects the loaded log as a whole: event seqs are zero-based and contiguous, surface markers obey event-type eligibility, provenance belongs only to surface event types, present arrays are nonempty and duplicate-free, every source is an earlier seq, and every positional replacement names and cites all surface nodes it removes. Every contract failure uses `SESSION_QUERY_INVALID_SURFACE`; there is no weaker classification-only surface standard.
+Event tracing checks target existence before surface analysis. Both event listing and tracing then use `dsh-session`'s one-pass surface fold, which accepts or rejects the loaded log as a whole: event seqs are zero-based and contiguous, surface markers obey event-type eligibility, only surface event types may cite source-event seqs, present arrays are nonempty and duplicate-free, every source is an earlier seq, and every positional replacement names and cites all surface nodes it removes. Every contract failure uses `SESSION_QUERY_INVALID_SURFACE`; there is no weaker classification-only surface standard.
 
 All returned records and arrays are detached. A known live event trace never consults persistence; persisted event traces preserve the exact-read list/load consistency check. Session lineage is necessarily a cross-corpus operation and therefore preserves cross-corpus persistence failure semantics.
 
 ## Alternatives considered
 
 - **Expose standalone tracing helpers** — rejected because the source-precedence and detachment boundary belongs to `ctx.sessionQuery`; public helpers would invite callers to bypass it.
-- **Combine replacement and provenance edges** — rejected because a positional replacement can shadow surface nodes while also citing non-surface construction inputs, and consumers need to distinguish those meanings.
-- **Return transitive provenance closure** — rejected because it obscures logged direct evidence, increases result size, and lets one malformed distant edge alter otherwise local output.
-- **Best-effort traces over malformed provenance** — rejected because a structurally plausible partial graph would look authoritative. Exact inspection fails loudly when the canonical relationship contract is broken.
+- **Combine replacement and cited-source edges** — rejected because a positional replacement can shadow surface nodes while also citing non-surface construction inputs, and consumers need to distinguish those meanings.
+- **Return all transitively cited source events** — rejected because it obscures logged direct evidence, increases result size, and lets one malformed distant edge alter otherwise local output.
+- **Best-effort traces over malformed source-event lists** — rejected because a structurally plausible partial result would look authoritative. Exact inspection fails loudly when the canonical relationship contract is broken.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
index f578a69a30..6a39a9857d 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-会话关系分散编码在不可变 header、位置式表面操作和已记录的来源数组中。消费方如果直接重建这些关系，就必须重复实现语料优先级、表面折叠、格式错误日志的处理、确定性的谱系顺序和克隆。位置替换与来源属于不同的图，因此把两者合并为一种通用边类型也会丢失含义。
+会话关系分散编码在不可变 header、位置式表面操作和已记录的来源事件 seq 引用数组中。消费方如果直接重建这些关系，就必须重复实现语料优先级、表面折叠、格式错误日志的处理、确定性的谱系顺序和克隆。位置替换关系与来源事件引用关系表示不同含义，因此把两者合并为一种通用边类型也会丢失含义。
 
 ## 决策
 
@@ -14,20 +14,20 @@ Status: implemented
 
 `SessionLineageTrace` 返回目标、按从直接父级到外层父级排序的已知父级，以及递归的后代树；同级节点先按创建时间排序，再按 session id 排序。`complete: true` 会携带已知根节点；`complete: false` 会携带第一个无法解析的父级 id。与目标相连的循环会以 `SESSION_QUERY_INVALID_LINEAGE` 失败。
 
-`SessionEventTrace` 将位置关系与来源关系分开保留。`replacedBy` 是直接的位置替换者，`replacementChain` 沿替换者追踪至最终节点，`replacedEventSeqs` 则列出目标直接移除的真实表面节点。`sourceEventSeqs` 保留日志中直接来源的顺序，而 `derivedEventSeqs` 按日志顺序列出后续的直接反向引用。来源关系不会传递展开。
+`SessionEventTrace` 将位置替换与来源事件引用关系分开保留。`replacedBy` 是直接的位置替换者，`replacementChain` 沿替换者追踪至最终节点，`replacedEventSeqs` 则列出目标直接移除的真实表面节点。`sourceEventSeqs` 保留日志中直接来源的顺序，而 `derivedEventSeqs` 按日志顺序列出后续的直接反向引用。查询不会继续传递追踪被引用的来源事件。
 
 ## 校验边界
 
-事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以携带来源；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何约定违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
+事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以引用来源事件 seq；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何约定违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
 
 所有返回的记录与数组都与内部状态分离。已知的实时事件追踪绝不查询持久化；持久化事件追踪保留精确读取所要求的列表／加载一致性检查。会话谱系必然属于跨语料操作，因此也保留跨语料的持久化失败语义。
 
 ## 考虑过的替代方案
 
 - **公开独立的追踪辅助函数**：不予采纳，因为源优先级与状态分离边界属于 `ctx.sessionQuery`；公开辅助函数会诱使调用方绕过该边界。
-- **合并替换边与来源边**：不予采纳，因为位置替换可以遮蔽表面节点，同时引用不在表面上的构造输入，而消费方需要区分这两种含义。
-- **返回传递来源闭包**：不予采纳，因为这会掩盖日志中直接记录的证据、增大结果，并让一条遥远的格式错误边改变原本局部的输出。
-- **在格式错误的来源关系上返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部图会显得具有权威性。当规范的关系约定损坏时，精确检查会明确报错。
+- **合并替换边与来源事件引用边**：不予采纳，因为位置替换可以遮蔽表面节点，同时引用不在表面上的构造输入，而消费方需要区分这两种含义。
+- **返回所有传递引用的来源事件**：不予采纳，因为这会掩盖日志中直接记录的证据、增大结果，并让一条遥远的格式错误边改变原本局部的输出。
+- **对格式错误的来源事件列表返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部结果会显得具有权威性。当规范的关系约定损坏时，精确检查会明确报错。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 3893ff403f..7952219be6 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
-2026-07-16-harness-level-loop.zh.md: 8d61c36915c7a3b5e0fde94c4c0ba52ec48eddd1
+2026-07-16-harness-level-loop.md: bc375621c5bf71ae6e3fbcd754d3b62e43353ae9
+2026-07-16-harness-level-loop.zh.md: fd74fbf85a63cb2f35fbcf7f694f738a07fe0cee
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index f37bea0842..bc375621c5 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -36,7 +36,7 @@ Time-based `/loop` or scheduled execution is a third policy and is not implement
 | Package | Repository category | Owned structures and verbs |
 |---|---|---|
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`, domain service | Owns `GoalId`, compare-and-set `GoalRef`, `GoalSnapshot`, four-state `GoalPhase`, structured `GoalBlockReason`, process-local `GoalActivation`, replay folding, and `get`, `create`, `edit`, `pause`, `resume`, `complete`, `block`, `clear`, and `disarm` verbs. |
-| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; authenticates live turn provenance and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
+| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; requires a direct human message in a live root-agent turn and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`, continuation policy | Reserves, fences, admits, attributes, settles, cancels, and quiescently drains same-session goal rounds without importing the concrete loop. |
 | `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`, human-command producer | Registers `/goal` status, creation, edit, pause, resume, and clear over the goal domain for TUI. |
@@ -68,7 +68,7 @@ Normal turn completion schedules another round only while the goal remains activ
 
 The human UX follows the compact Codex shape in the [public OpenAI Codex TUI dispatcher at commit `678157a`](https://github.com/openai/codex/blob/678157acaa819d5510adfe359abb5d0392cfe461/codex-rs/tui/src/chatwidget/slash_dispatch.rs#L750-L805): `/goal` shows status, `/goal <objective>` creates, and `edit`, `pause`, `resume`, or `clear` perform direct lifecycle actions. The commit permalink keeps the researched grammar verifiable as Codex evolves. Status includes durable phase, admitted/capped rounds, and live armed/disarmed activation. Direct status and command output do not enter model history; accepted domain mutations remain reconstructable because the goal service records them.
 
-The model receives only `get_goal`, `create_goal`, and `update_goal`. It may create a goal when a direct human request clearly asks for substantial multi-round work, and it may infer that intent in any language. It must not turn routine one-turn work into a goal. Direct-human provenance is enforced in code; semantic interpretation remains model judgment. An autonomous goal round may report `complete` or `blocked` for the exact current goal round but cannot edit, pause, resume, or replace the human objective.
+The model receives only `get_goal`, `create_goal`, and `update_goal`. It may create a goal when a direct human request clearly asks for substantial multi-round work, and it may infer that intent in any language. It must not turn routine one-turn work into a goal. Code requires a direct human message in the current live root-agent turn; semantic interpretation remains model judgment. An autonomous goal round may report `complete` or `blocked` for the exact current goal round but cannot edit, pause, resume, or replace the human objective.
 
 TUI mounts the shared command registry and complete goal stack by default and exposes `/goal` through one producer. ACP mounts the goal domain, model tools, and same-session driver but deliberately omits the human command plane. Every effective registered command is discoverable and invocable through every composed command adapter; a plugin incompatible with an application omits its command producer from that composition rather than relying on registry-level surface masks. The UI-less agent spine is opt-in so one-shot callers do not silently become multi-round operations. The headless CLI and JSON-RPC front doors do not consume the command plane; ordinary human text can still authorize model goal tools when that stack is composed.
 
@@ -111,7 +111,7 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 
 - Goal-based execution ships without one overloaded “loop” object: same-session continuation and fresh-agent iteration have explicit, separately testable contracts.
 - Durable goal history is replayable and forkable, while process-local activation prevents accidental work on resume.
-- Humans receive a small Codex-shaped UX; models receive a compact provenance-checked tool surface; deployments can remove either independently.
+- Humans receive a small Codex-shaped UX; models receive a compact tool set whose mutating calls require a direct human message in the current live root-agent turn; deployments can remove either independently.
 - Ralph demonstrates a nontrivial fixed policy entirely as a plugin over existing workflow and subagent primitives.
 - Round limits are generous by default but remain deployment-controlled. They bound iterations, not tokens, price, elapsed time, or external side effects.
 - The original proposal's evaluator, budget, reflector, background-task, CLI, and generic loop-session architecture is intentionally not part of the implemented public surface.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 8d61c36915..fd74fbf85a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 | 包 | 仓库类别 | 所属结构与动词 |
 |---|---|---|
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`，领域服务 | 拥有 `GoalId`、比较并交换 `GoalRef`、`GoalSnapshot`、四状态 `GoalPhase`、结构化 `GoalBlockReason`、进程本地 `GoalActivation`、重放折叠，以及 `get`、`create`、`edit`、`pause`、`resume`、`complete`、`block`、`clear` 与 `disarm` 动词。 |
-| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`，面向模型消费方 | 注册互斥的 `get_goal`、`create_goal` 与 `update_goal`；认证实时 Turn 来源，并把自治 Round 权限收窄到带机器可路由原因代码的完成或阻塞报告。 |
+| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`，面向模型消费方 | 注册互斥的 `get_goal`、`create_goal` 与 `update_goal`；要求实时根 agent Turn 中有一条人类直接发送的消息，并把自治 Round 权限收窄到带机器可路由原因代码的完成或阻塞报告。 |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`，续行策略 | 在不导入具体 loop 的情况下，预留、设围栏、接纳、归属、结算、取消并排空同会话 Goal Round，直至完全停稳。 |
 | `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`，UI 注册表 | 拥有面向人类专用命令的 `CommandDefinition`、发现、作用域注册、直接分发、`CommandResult` 与请求取消。 |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`，人类命令生产方 | 为 TUI 注册构建在目标领域之上的 `/goal` 状态、创建、编辑、暂停、恢复与清除。 |
@@ -68,7 +68,7 @@ Goal Round 驱动器为每个特定的实时 agent 至多拥有一个待定预
 
 人类 UX 遵循 [OpenAI Codex 在提交 `678157a` 时的公开 TUI 分发器](https://github.com/openai/codex/blob/678157acaa819d5510adfe359abb5d0392cfe461/codex-rs/tui/src/chatwidget/slash_dispatch.rs#L750-L805)中的紧凑形态：`/goal` 显示状态，`/goal <objective>` 创建目标，而 `edit`、`pause`、`resume` 或 `clear` 执行直接生命周期操作。该提交永久链接让研究所得语法在 Codex 演进时仍可验证。状态包含持久阶段、已接纳/上限 Round 数以及实时已激活/未激活状态。直接状态与命令输出不会进入模型历史；已接受领域变更仍可重建，因为目标服务会记录它们。
 
-模型只接收 `get_goal`、`create_goal` 和 `update_goal`。当直接人类请求清楚要求大量多 Round 工作时，模型可以创建目标，并且可以从任何语言推断该意图。它不得把日常单 Turn 工作变成目标。直接人类来源由代码强制执行；语义解释仍是模型判断。自治目标 Round 可以为确切的当前 Goal Round 报告 `complete` 或 `blocked`，但不能编辑、暂停、恢复或替换人类目标。
+模型只接收 `get_goal`、`create_goal` 和 `update_goal`。当直接人类请求清楚要求大量多 Round 工作时，模型可以创建目标，并且可以从任何语言推断该意图。它不得把日常单 Turn 工作变成目标。代码要求当前实时根 agent Turn 中有一条人类直接发送的消息；语义解释仍是模型判断。自治目标 Round 可以为确切的当前 Goal Round 报告 `complete` 或 `blocked`，但不能编辑、暂停、恢复或替换人类目标。
 
 TUI 默认挂载共享命令注册表和完整目标栈，并通过一个生产方暴露 `/goal`。ACP（Agent Client Protocol）挂载目标领域、模型工具和同会话驱动器，但有意省略人类命令平面。每条有效已注册命令都能被每个已组合的命令适配器发现和调用；若插件与某应用不兼容，该应用组合会省略其命令生产方，而不是依赖注册表层面的表面掩码。无 UI 的 agent 主干要求显式选择加入，以免单次调用方静默变成多 Round 操作。无头 CLI（命令行界面）与 JSON-RPC 前端不消费命令平面；挂载目标栈后，普通人类文本仍可授权模型目标工具。
 
@@ -111,7 +111,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 - 目标式执行在没有单个过载「loop」对象的情况下交付：同会话续行与全新 agent 迭代拥有显式、可独立测试的约定。
 - 持久目标历史可以重放和 fork，而进程本地激活态会防止恢复时意外开始工作。
-- 人类获得小型 Codex 形态 UX；模型获得紧凑、带来源检查的工具表面；部署可以独立移除任一能力。
+- 人类获得小型 Codex 形态 UX；模型获得一组紧凑工具，其中的修改操作要求当前实时根 agent Turn 中有一条人类直接发送的消息；部署可以独立移除任一能力。
 - Ralph 展示了非平凡固定策略可以完全作为现有 workflow 与 subagent 原语之上的插件实现。
 - Round 上限默认宽裕，但仍由部署控制。它限制迭代次数，不限制 token、价格、耗时或外部副作用。
 - 原始提案中的评估器、预算、反思器、后台任务、CLI 与通用 loop-session 架构有意不进入已实现公开表面。
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index 730de18a5a..088290b3fc 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.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 .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
-2026-07-19-model-facing-goal-tools.md: 0271194a38503711de77290c915010c26a9de74b
-2026-07-19-model-facing-goal-tools.zh.md: 097aaa3b160a394ff3d13681be04dd19c7856ebc
+2026-07-19-model-facing-goal-tools.md: abed410c7fd71b18c2cc0d0db745e76d98352546
+2026-07-19-model-facing-goal-tools.zh.md: a51ad417ff0928583ccddddafe65d23bc86bd24d
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
index 0271194a38..abed410c7f 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
@@ -28,7 +28,7 @@ An autonomous goal round that successfully reports completion or blocking defers
 
 Every call requires an `exec.agent` that is the exact running object in `AgentRegistry`, is the current inherited driver initiator, and has an open turn. These are execution-time checks and cannot be bypassed by prompt injection or hand-authored tool arguments.
 
-Create, edit, pause, and resume additionally require an accepted user message or user steering event in the current turn of a runtime-root agent. Root ownership is derived from the live agent graph rather than durable fork ancestry: a resumed fork can receive direct human authority, while a live child remains a subagent and cannot mutate these states. User source is a host attestation: every `Agent.followup()` or `steer()` input requires an explicit source, so the host labels direct human content `{ kind: 'user' }` and non-human producers label their own provenance. The runtime proves provenance, not whether the human's wording semantically warrants creation or resumption; that interpretation remains with the model.
+Create, edit, pause, and resume additionally require an accepted user message or user steering event in the current turn of a runtime-root agent. Root ownership is derived from the live agent graph rather than durable fork ancestry: a resumed fork can receive direct human authority, while a live child remains a subagent and cannot mutate these states. User source is a host attestation: every `Agent.followup()` or `steer()` input requires an explicit source, so the host labels direct human content `{ kind: 'user' }` and non-human producers identify themselves in their source fields. The runtime proves that the current turn contains a direct human message, not whether the human's wording semantically warrants creation or resumption; that interpretation remains with the model.
 
 Complete and blocked accept either direct-human authority or the exact current goal round. Goal-round authority requires a goal-sourced `user/message` whose goal id, revision, and round all equal the folded current goal. It grants only the two terminal reports. Direct human authority may stop a goal immediately.
 
@@ -44,7 +44,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 
 - **Rely on prompt instructions for authority** — rejected because text can guide model judgment but cannot authenticate the live caller, turn, or source event.
 - **Expose every goal-service verb as a separate tool** — rejected because a compact read/create/update surface reduces schema cost and keeps compare-and-set behavior uniform.
-- **Require exact command phrases** — rejected because natural-language intent, including languages other than English, should be interpreted by the model; execution authority depends on provenance rather than spelling.
+- **Require exact command phrases** — rejected because natural-language intent, including languages other than English, should be interpreted by the model; execution authority depends on a direct human message in the current turn rather than spelling.
 - **Authorize from persisted root or fork metadata** — rejected because a fork that becomes an independently resumed top-level session should accept new human authority, while a currently owned child should not.
 - **Let autonomous rounds edit or resume the goal** — rejected because continuation authority is narrower than authority to redefine or restart the human objective.
 - **Treat the blocked threshold as an evaluator** — rejected because event counts cannot prove that an obstacle is semantically unchanged or truly terminal.
@@ -53,7 +53,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 ## Consequences
 
 - Models receive a stable, compact lifecycle surface without direct access to the goal service.
-- State-changing calls are constrained by live runtime provenance as well as durable compare-and-set references.
+- State-changing calls require a live runtime-root agent and a direct human message in the current turn, as well as durable compare-and-set references.
 - Human requests can create and rearm goals through ordinary natural language, while restored sessions remain inert until such input arrives.
 - Goal rounds can finish or report a repeated blocker but cannot broaden their own mandate.
 - Deployment policy selects the blocking lower bound; the same resolved value controls enforcement and prompt guidance.
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index 097aaa3b16..a51ad417ff 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 每次调用都要求存在 `exec.agent`，且它必须是 `AgentRegistry` 中完全相同的运行中对象、当前继承的驱动发起者，并处于开放轮次内。这些检查在执行时进行，不能通过提示词注入或手写工具参数绕过。
 
-创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.followup()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则标注自己的来源信息。运行时证明来源，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。
+创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.followup()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则在来源字段中注明自己。运行时证明当前轮次包含人类直接发送的消息，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。
 
 完成与阻塞既接受直接人类权限，也接受准确的当前 Goal Round。Goal Round 权限要求存在一条来源为目标的 `user/message`，其中目标 id、修订号和 Round 都与折叠后的当前目标相等。它只授予这两种终止报告权限。直接人类权限可以立即停止目标。
 
@@ -44,7 +44,7 @@ Status: implemented
 
 - **依赖提示词指令实施权限**——不予采纳，因为文本可以指导模型判断，却不能认证实时调用者、轮次或来源事件。
 - **把每个目标服务动词分别暴露为工具**——不予采纳，因为紧凑的读取/创建/更新表面可以降低模式成本，并保持统一的比较并交换行为。
-- **要求精确命令短语**——不予采纳，因为自然语言意图（包括英语以外的语言）应由模型解释；执行权限取决于来源，而不是拼写。
+- **要求精确命令短语**——不予采纳，因为自然语言意图（包括英语以外的语言）应由模型解释；执行权限取决于当前轮次中人类直接发送的消息，而不是拼写。
 - **根据持久的根或派生元数据授权**——不予采纳，因为成为独立恢复顶层会话的派生应接受新的人类权限，而当前仍受所有权约束的子智能体则不应接受。
 - **允许自主回合编辑或恢复目标**——不予采纳，因为继续执行权限比重新定义或重启人类目标的权限更窄。
 - **把阻塞阈值当作评估器**——不予采纳，因为事件计数无法证明障碍在语义上未改变或确实不可继续。
@@ -53,7 +53,7 @@ Status: implemented
 ## 后果
 
 - 模型获得稳定而紧凑的生命周期表面，无需直接访问目标服务。
-- 改变状态的调用同时受到实时运行时来源与持久比较并交换引用的约束。
+- 改变状态的调用要求实时运行时根 agent、当前轮次中人类直接发送的消息，以及持久比较并交换引用。
 - 人类可以通过普通自然语言请求创建和重新激活目标，而恢复后的会话在收到此类输入前保持静止。
 - Goal Round 可以完成或报告重复阻塞，但不能自行扩大任务权限。
 - 部署策略选择阻塞下限；同一个解析后的值同时控制执行与提示词指导。
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
index e330fbd089..a4bc18ecce 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.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 .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
-2026-07-21-cross-session-references.md: b2d428e0937fdd881720720401948a1c3e7ef1f6
-2026-07-21-cross-session-references.zh.md: ef89fd76c864c430f7b730d250e6511c2709f97e
+2026-07-21-cross-session-references.md: 46424e12949697054da2f920fbe55ca9dcbaf075
+2026-07-21-cross-session-references.zh.md: 7956dbef79aa77ab9d2be810420ae8c1b4e82a8d
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md
index b2d428e093..46424e1294 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-21-cross-session-references.zh.md)
 
 ## Problem
 
-TUI users need to bring relevant work from another conversation into one new message without resuming, forking, or granting the source transcript authority over the current session. The harness already exposes exact session enumeration and raw event inspection, but every host independently parsing logs would duplicate compaction folding, provenance filtering, size limits, error behavior, and persistence. Encoding host markup directly into the agent message contract would also bind the core loop to one UI syntax.
+TUI users need to bring relevant work from another conversation into one new message without resuming, forking, or granting the source transcript authority over the current session. The harness already exposes exact session enumeration and raw event inspection, but every host independently parsing logs would duplicate compaction folding, filtering by cited source-event seqs, size limits, error behavior, and persistence. Encoding host markup directly into the agent message contract would also bind the core loop to one UI syntax.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
index ef89fd76c8..7956dbef79 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、来源过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息约定，还会让核心循环绑定某一种 UI 语法。
+TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、按被引用来源事件 seq 过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息约定，还会让核心循环绑定某一种 UI 语法。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index 3ea46677ab..75e87605ec 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.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 .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
-2026-07-21-log-backed-session-titles.md: 89e6e67fb9ece4c087ba7b1bc52e61b78b94586c
-2026-07-21-log-backed-session-titles.zh.md: 21a0ec5dc9cc90726dda502ba46a52d717c39df5
+2026-07-21-log-backed-session-titles.md: 47025ba7e72ea6746d6f4428a81d6d754a8dcd03
+2026-07-21-log-backed-session-titles.zh.md: d7e12875354ca1fc66f0035020c7ffe2ddaa9354
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
index 89e6e67fb9..47025ba7e7 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
@@ -16,7 +16,7 @@ The [`session-title` capability family](../../../../packages/session/README.md)
 
 ### Event ownership and folding
 
-Every accepted revision is a log-only `session/title` event. Its payload contains normalized non-empty text, the exact eligible human `user/message` seqs used to derive it, and either fallback provenance or the registered provider id plus optional provider/model route. Before an auxiliary title-model dispatch, the shared helper appends a log-only `session/title-llm-request` event containing the title-provider id, exact source seqs, route, system prompt, messages, and output-token cap; a later generation failure leaves the request auditable. The dispatched envelope is deep-frozen to preserve exact agreement with that record but carries no process-local agent-loop request identity, so loop-only reconstruction checks do not compare it with the main conversation header. Validation failures that never reach dispatch create no request event. `foldSessionTitle()` selects the latest title event and adds that event's seq and timestamp as `SessionTitleSnapshot`. Neither event enters `session.surface` or `deriveMessages()`.
+Every accepted revision is a log-only `session/title` event. Its payload contains normalized non-empty text, the exact eligible human `user/message` seqs used to derive it, and either the fallback source kind or the registered provider id plus optional provider/model route. Before an auxiliary title-model dispatch, the shared helper appends a log-only `session/title-llm-request` event containing the title-provider id, exact source seqs, route, system prompt, messages, and output-token cap; a later generation failure leaves the request auditable. The dispatched envelope is deep-frozen to preserve exact agreement with that record but carries no process-local agent-loop request identity, so loop-only reconstruction checks do not compare it with the main conversation header. Validation failures that never reach dispatch create no request event. `foldSessionTitle()` selects the latest title event and adds that event's seq and timestamp as `SessionTitleSnapshot`. Neither event enters `session.surface` or `deriveMessages()`.
 
 The title service appends `session/title` directly after checking its current revision and exact live session; the bundled model helper likewise appends its literal `session/title-llm-request` record before dispatch. Both records may sit between turns without inventing an execution boundary. Persistence admits them to bounded background batches and drains through ordinary checkpoints and lifecycle teardown; title publication does not force a per-event flush. No generic marker, cast, or settlement queue sits between the event owner and `Session.append()`. This is the domain-specific application of the [standalone log-only event decision](../simplification/2026-07-28-remove-synthetic-log-only-turns.md).
 
@@ -51,8 +51,8 @@ A fork inherits seed title events unchanged, like the rest of its source log —
 - **Mutable `SessionHeader` or side metadata** — rejected because it creates a second persistence mutation protocol, weakens immutable identity metadata, makes crash atomicity backend-specific, and gives forks ambiguous copy-versus-reference behavior. The append-only log already owns replayable latest-wins state.
 - **Await title generation before returning the agent response** — rejected because auxiliary provider latency and failure would sit on the main interaction's critical path. The deterministic fallback gives immediate useful state while a better title may arrive later.
 - **Put titles in derived history or the request prefix** — rejected because UI metadata would consume tokens, change cache identity, and make the main model observe its own label. A log-only event remains reconstructable without becoming model-visible.
-- **Permit multiple registered providers and resolve precedence after completion** — rejected because completion order is not product precedence and would make retries, HMR, and provenance nondeterministic. A deployment that needs a composite policy can register one provider that owns that policy.
-- **Silently truncate oversized auxiliary input** — rejected because the provider result would claim exact source-message provenance while receiving only partial text. Keeping the prior title and warning preserves truthful attribution.
+- **Permit multiple registered providers and resolve precedence after completion** — rejected because completion order is not product precedence and would make retries, HMR, and the recorded provider nondeterministic. A deployment that needs a composite policy can register one provider that owns that policy.
+- **Silently truncate oversized auxiliary input** — rejected because the provider result would cite source-message seqs whose complete text it did not receive. Keeping the prior title and warning preserves the exact input record.
 - **Index titles in `listSessions()` immediately** — rejected because the existing lightweight metadata list would need per-backend derived-index synchronization. Exact `readTitle()` establishes the read contract without precommitting search or indexing policy.
 - **Keep the Web host fallback-only** — rejected because the UI would expose durable titles but never improve them beyond the first-prompt prefix. The first-message provider keeps its latency off the main response path while making model summaries the default Web outcome.
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index 21a0ec5dc9..d7e1287535 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 ### 事件归属与折叠
 
-每个已接受的修订都是纯日志 `session/title` 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 `user/message` 的准确 seq，以及回退来源信息，或已注册的提供方 id 加可选的提供方和模型路由。辅助标题模型发起调用前，共享辅助组件会追加一个纯日志 `session/title-llm-request` 事件，其载荷包含标题提供方 id、准确的源 seq、路由、系统提示词、消息和输出 token 上限；即使后续生成失败，这次请求仍可审计。发送的请求信封经过深度冻结，以确保其与该记录精确一致，但它有意不携带进程本地的 agent loop（智能体循环）请求身份，因此仅针对 agent loop 的重建检查不会将它与主对话请求头进行比较。未进入调用阶段的验证失败不会创建请求事件。`foldSessionTitle()` 选择最新的标题事件，并将该事件的 seq 和时间戳加入 `SessionTitleSnapshot`。这两类事件都不会进入 `session.surface` 或 `deriveMessages()`。
+每个已接受的修订都是纯日志 `session/title` 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 `user/message` 的准确 seq，以及回退来源 kind，或已注册的提供方 id 加可选的提供方和模型路由。辅助标题模型发起调用前，共享辅助组件会追加一个纯日志 `session/title-llm-request` 事件，其载荷包含标题提供方 id、准确的源 seq、路由、系统提示词、消息和输出 token 上限；即使后续生成失败，这次请求仍可审计。发送的请求信封经过深度冻结，以确保其与该记录精确一致，但它有意不携带进程本地的 agent loop（智能体循环）请求身份，因此仅针对 agent loop 的重建检查不会将它与主对话请求头进行比较。未进入调用阶段的验证失败不会创建请求事件。`foldSessionTitle()` 选择最新的标题事件，并将该事件的 seq 和时间戳加入 `SessionTitleSnapshot`。这两类事件都不会进入 `session.surface` 或 `deriveMessages()`。
 
 标题服务会在检查当前修订和确切的实时会话后，直接追加 `session/title`；随附模型辅助函数同样会在发起调用前追加其字面量 `session/title-llm-request` 记录。两类记录都可以位于轮次之间，而无需虚构执行边界。持久化会将它们接纳到有界后台批次中，并通过常规检查点和生命周期 teardown 排空；标题发布不会强制逐事件 flush。事件所有方与 `Session.append()` 之间不存在通用标记、类型断言或结算队列。这是[独立纯日志事件决策](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)在特定领域中的应用。
 
@@ -51,8 +51,8 @@ Status: implemented
 - **可变 `SessionHeader` 或独立元数据**：不予采纳，因为这会创建第二套持久化变更协议，削弱不可变身份元数据，让崩溃原子性因后端而异，并使 fork 的复制或引用行为产生歧义。仅追加日志已经负责可回放的后写覆盖状态。
 - **返回 agent 响应前等待标题生成**：不予采纳，因为辅助提供方的延迟和故障会进入主交互的关键路径。确定性回退方案可以立即提供可用状态，质量更高的标题则可稍后到达。
 - **将标题放入派生历史记录或请求前缀**：不予采纳，因为 UI 元数据会消耗 token、改变缓存标识，并让主模型观察到自己的标签。纯日志事件既保持可重建，又不会变得对模型可见。
-- **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
-- **静默截断过大的辅助输入**：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
+- **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和已记录的提供方变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
+- **静默截断过大的辅助输入**：不予采纳，因为提供方结果会引用源消息 seq，却没有收到这些消息的完整文本。保留原有标题并发出警告，可以保留准确的输入记录。
 - **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取约定，而没有提前锁定搜索或索引策略。
 - **让 Web host 只使用回退标题**：不予采纳，因为 UI 虽会显示持久标题，却始终无法将第一条提示词的前缀改进为更好的标题。首消息提供方在主响应路径之外运行，并让模型摘要成为 Web 的默认结果。
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
index e90a23fd2e..f51e1f482a 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.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 .agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
-2026-07-24-model-facing-session-query-tools.md: 863f557f11f89ff8dfc121b7da0b653852528394
-2026-07-24-model-facing-session-query-tools.zh.md: 2acbf44b42aafd2eac37903e1acbefc5ba098377
+2026-07-24-model-facing-session-query-tools.md: 7dcb25fc4205442bd0b0743a6228427fa66ead1c
+2026-07-24-model-facing-session-query-tools.zh.md: 29582ec498119ee5956f7a3fe9bcefaabf13b122
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
index 863f557f11..7dcb25fc42 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
@@ -14,7 +14,7 @@ The unified `ctx.sessionQuery` service exposes exact reads, filters, relationshi
 
 The package entrypoint is only the public composition root for configuration, prompt registration, and tool registration. Its internal modules follow the execution boundary: `input.ts` owns model schemas, normalization, and filter construction; `service-boundary.ts` contains provider calls and model-safe error translation; `workspace-access.ts` owns caller identity, workspace authorization, title access, and lineage projection; `operations.ts` orchestrates the five service workflows; and `presentation.ts` renders tool results and call cards. This keeps policy in its owning layer without changing the package contract.
 
-`session_search` groups full-text matches by session and exposes typed session and event metadata filters. `session_event_search` searches one session, defaulting to the caller's current session. `session_trace` returns the complete authorized ancestor chain and recursive descendant trees. `session_event_trace` returns every known positional replacement and direct provenance relationship for one event. `session_event_read` returns the exact target event as unabridged JSON and optionally summarizes a bounded raw-event window; omitted `before` and `after` values mean target-only.
+`session_search` groups full-text matches by session and exposes typed session and event metadata filters. `session_event_search` searches one session, defaulting to the caller's current session. `session_trace` returns the complete authorized ancestor chain and recursive descendant trees. `session_event_trace` returns every known positional replacement and direct cited source-event relationship for one event. `session_event_read` returns the exact target event as unabridged JSON and optionally summarizes a bounded raw-event window; omitted `before` and `after` values mean target-only.
 
 Model-facing filters use flat snake-case fields. Timestamps are timezone-qualified ISO 8601 strings at the tool boundary, convert to inclusive epoch-millisecond ranges for the service, and render as UTC ISO 8601. List values are ORed inside one filter while separate filters are ANDed. Requested parent ids are deduplicated and authority-filtered before FTS, so only parents in the caller workspace enter the provider clause; missing and cross-workspace guesses behave identically, while the root-session marker remains independently ORed into that clause. Event type strings remain open because `SessionEventMap` is merge-extensible; availability and event surface use closed values.
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
index 2acbf44b42..29582ec498 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包约定。
 
-`session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接来源关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
+`session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接引用来源事件的关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
 
 面向模型的过滤条件使用扁平的 snake-case 字段。工具边界上的时间戳采用带时区的 ISO 8601 字符串，转换为服务使用的闭区间毫秒时间戳，并以 UTC ISO 8601 渲染。同一个过滤条件中的列表值按 OR 组合，不同过滤条件按 AND 组合。请求的父会话 id 会在 FTS 之前去重并按权限过滤，因此只有调用者工作区中的父会话会进入提供方条件；缺失与跨工作区的猜测具有相同行为，而根会话标记仍会独立按 OR 加入该条件。由于 `SessionEventMap` 可通过声明合并扩展，事件类型字符串保持开放；可用状态与事件表层使用封闭取值。
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
index 37c876275c..d69b63df7f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.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 .agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
-2026-07-27-trajectory-inspection-ledger.md: e3fc22234c1df449c99eac90af27de7da0b6f202
-2026-07-27-trajectory-inspection-ledger.zh.md: f167d818281c39a06e658c294f45e47d3ba40642
+2026-07-27-trajectory-inspection-ledger.md: a905e65942365c17b7513028b275288c82428221
+2026-07-27-trajectory-inspection-ledger.zh.md: 70fcdcdb0d2f26d120325a76a3e1f49ae6350c57
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
index e3fc22234c..a905e65942 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
@@ -19,7 +19,7 @@ Trajectory has to make prose, machine payloads, token usage, timing, and nested
 - The client runtime exposes a read-only history source independent from Session and SessionManager. Each activated source owns its raw entries, paging, live gap repair, and reconnect rebuild; the ordinary conversation snapshot remains the folded Chat projection. Trajectory opens the source's tail while mounted and requests one older page when the user reaches the loaded range's top, then lazily derives event order, context lineage, schema index, and Requests instead of imposing those structures on every conversation consumer.
 - Ordinary generation and compaction calls form one chronological Request projection, distinguished by purpose rather than separate collections. Effective prompt state and its change ride the Request that introduced them; compaction and prompt changes are not independent inspection entities. Request numbering and cumulative usage cover the loaded history window and expand as older pages arrive.
 - Call schemas come from the active recorded Request header. Keyless snapshot fixtures deliberately replace that catalog with the non-array `{{tools}}` token, which the durable inspection boundary treats as unavailable instead of attempting to project or fabricate schemas.
-- Selecting a record or Request opens an inspector inside Trajectory. Tabs and Summary sections follow the selected entity: Markdown messages expose rendered, source, provenance, and hierarchy views; tools add JSON payload/result and schema views; Requests add options, usage, timing, and result navigation. Scrollable Summary regions keep their scrollbar thumbs transparent until hover or `focus-within`, while retaining the scrollbar reservation and scroll behavior. Images render as media rather than serialized data.
+- Selecting a record or Request opens an inspector inside Trajectory. Tabs and Summary sections follow the selected entity: Markdown messages expose rendered content, source fields, provider/model fields, and hierarchy views; tools add JSON payload/result and schema views; Requests add options, usage, timing, and result navigation. Scrollable Summary regions keep their scrollbar thumbs transparent until hover or `focus-within`, while retaining the scrollbar reservation and scroll behavior. Images render as media rather than serialized data.
 - Turn folding removes all rows after its first record and replaces them with a compact step/tool-call count; Assistant folding applies the same interaction to its tool-call descendants. Global controls fold or expand both levels.
 - A long ledger initially positions the loaded tail at the bottom and mounts only the viewport's row window plus bounded overscan. Request-only separators join the next measurable virtual item, with a terminal separator retaining its own fixed clearance, so the virtualizer never owns a zero-height item. Semantic DOM-safe row keys and ARIA indexes expose identity independently from mount position. A tail with known older history virtualizes immediately even when its loaded projection is below the ordinary row threshold. Stable-key virtualizer anchoring preserves the visible item across prepends and appends; the manual scroll-height fallback applies only when completing pagination disables virtualization. Selection, timeline focus, folding, search, and bottom following address records by stable event or tool-call identity rather than requiring their DOM rows to exist. An explicit loading row covers records until initial positioning finishes and while an older page is pending. The raw window base sequence detects a prepend even when a page adds no surface-visible node.
 - The separate Waterfall tab is removed. A fixed Overview above the ledger projects every loaded record with known `startedAt` onto three semantic timing lanes using its own duration. While an older prefix remains unloaded and the viewport includes the loaded domain's start, a neutral ellipsis control covers the truncated edge and loads one earlier page without assigning unknown history a fabricated duration; hovering that control suppresses the ordinary timeline cursor. Finalized Assistant spans divide the recorded interval at the first non-empty token delta, so distinct TTFT and decoding colors retain their actual ratio; incomplete timing falls back to one Assistant color. Hovering for 500 ms exposes exact start/end, total duration, TTFT, and decoding time without relying on the browser's native tooltip delay. Dragging left or right commits an inclusive interval filter: any record whose active interval overlaps either boundary remains visible, records without known timing leave the focused ledger, and clearing the selection restores the full branch. Wheel gestures zoom the time domain. A right-button click clears the interval selection; dragging instead pans an already zoomed viewport without mutating it. The Overview keeps the full time domain while focused so the selection can be resized or cleared without losing orientation.
@@ -53,4 +53,4 @@ Trajectory has to make prose, machine payloads, token usage, timing, and nested
 
 ## Consequences
 
-Trajectory shows more useful records per viewport while retaining Turn and Request orientation. Context rewrites and compactions remain inline with their surrounding history, while a rewind begins a successor branch that inherits only the retained prefix. The floating composer leaves the ledger visible to the viewport edge without covering its final rows or hiding horizontal controls. The main ledger omits token usage and duration so content receives the available width; the local inspector exposes those facts together with full payloads, provenance, schemas, and request timing. The Overview uses recorded start/duration and token-boundary facts without fabricating live elapsed time, and its inclusive focus behavior matches the interaction users already know from Chrome DevTools Network. Tail-first paging bounds initial transport and projection work, virtualization bounds mounted row elements, incremental partial projection removes loaded-history length from ordinary token-frame work, and completed-step chunk compaction makes structural rebuilds proportional to inspection-relevant entries rather than the raw token count. Focused component tests pin tail-first paging, prepend anchoring and identity retention, the virtual window, tail following, content-only streaming without repeated scroll writes, streaming structural sharing, high-sequence window folding, timing projection, delayed detail disclosure, folding, record and interval selection, entity-specific tabs, and running/error semantics. A real-browser long-ledger contract pins stable prepend geometry, bounded mounting, top/middle/bottom reachability, and bounded scroll writes across a paced stream; the assembled Web snapshot pins the ledger, Overview timing details, composer overlay geometry, and inspector through the real client composition.
+Trajectory shows more useful records per viewport while retaining Turn and Request orientation. Context rewrites and compactions remain inline with their surrounding history, while a rewind begins a successor branch that inherits only the retained prefix. The floating composer leaves the ledger visible to the viewport edge without covering its final rows or hiding horizontal controls. The main ledger omits token usage and duration so content receives the available width; the local inspector exposes those facts together with full payloads, provider/model and source fields, schemas, and request timing. The Overview uses recorded start/duration and token-boundary facts without fabricating live elapsed time, and its inclusive focus behavior matches the interaction users already know from Chrome DevTools Network. Tail-first paging bounds initial transport and projection work, virtualization bounds mounted row elements, incremental partial projection removes loaded-history length from ordinary token-frame work, and completed-step chunk compaction makes structural rebuilds proportional to inspection-relevant entries rather than the raw token count. Focused component tests pin tail-first paging, prepend anchoring and identity retention, the virtual window, tail following, content-only streaming without repeated scroll writes, streaming structural sharing, high-sequence window folding, timing projection, delayed detail disclosure, folding, record and interval selection, entity-specific tabs, and running/error semantics. A real-browser long-ledger contract pins stable prepend geometry, bounded mounting, top/middle/bottom reachability, and bounded scroll writes across a paced stream; the assembled Web snapshot pins the ledger, Overview timing details, composer overlay geometry, and inspector through the real client composition.
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
index f167d81828..70fcdcdb0d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - 客户端 runtime 提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费者承担这些结构。
 - 普通生成调用与压缩调用形成一条按时间排序的请求投影，以 purpose 区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
 - 调用 schema 来自当前生效且已记录的请求头。无密钥快照 fixture（测试前置数据）有意将该目录替换为非数组 token `{{tools}}`，持久化检查边界会将其视为不可用，而不是尝试投影或虚构 schema。
-- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概览区域随实体类型变化：Markdown 消息提供渲染、源码、来源和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
+- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概览区域随实体类型变化：Markdown 消息提供渲染内容、来源字段、提供方／模型字段和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
 - 折叠轮次时保留其第一条记录，将后续行替换为紧凑的步骤和工具调用数量；折叠助手时对其工具调用后代应用相同交互。全局控件可以分别折叠或展开这两个层级。
 - 长记录表初始时将已加载尾部置于底部，只挂载视口对应的行窗口及有界的额外缓冲行。仅含请求的分隔行并入下一个具备可测高度的虚拟项，末尾分隔行则保留固定留白，因此虚拟化器不会管理零高度项。可安全用于 DOM 的语义行键与 ARIA 索引使标识不依赖挂载位置。只要已知尾部之前仍有更早历史，即使当前已加载投影低于常规行数阈值，也会立即启用虚拟化。基于稳定键的虚拟化器锚定会在向前补页和尾部追加时保留当前可见项；只有分页完成导致虚拟化停用时，才使用手动滚动高度兜底。选择、时间线聚焦、折叠、搜索和末尾跟随均按稳定的事件或工具调用标识定位，不要求对应 DOM 行已存在。初始定位完成前以及更早页面仍在等待时，明确的加载行会遮住真实记录。原始窗口的基准序号即使在一页未增加任何 surface 可见节点时，也能检测到这次向前补页。
 - 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 `startedAt` 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间相交的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
@@ -53,4 +53,4 @@ Status: implemented
 
 ## 后果
 
-轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
+轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、提供方／模型字段、来源字段、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
index 6a48bdc751..fa4523a51d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.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 .agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
-2026-07-27-workspace-registration-deletion.md: ae12b09979f20385336eef8d805173dd9c08d887
-2026-07-27-workspace-registration-deletion.zh.md: 85f399142bb0faf4b4bbf438ef2892d957814fab
+2026-07-27-workspace-registration-deletion.md: ef8a7fb9ae13c23e04a5760cd443c4a744ec4f19
+2026-07-27-workspace-registration-deletion.zh.md: 21c378b5c6d738bc6b9a00856691a56d65217586
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
index ae12b09979..ef8a7fb9ae 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-27-workspace-registration-deletion.zh.md)
 
 ## Problem
 
-A Workspace registers an existing code directory so the GUI can name it and order its Sessions. That record has no reliable provenance proving that Harness created or owns the directory, and the Session log is an independent persistence object. Treating the row's Delete action as recursive source deletion or Session deletion would destroy data outside the record's ownership boundary.
+A Workspace registers an existing code directory so the GUI can name it and order its Sessions. That record does not say that Harness created or owns the directory, and the Session log is an independent persistence object. Treating the row's Delete action as recursive source deletion or Session deletion would destroy data outside the record's ownership boundary.
 
 The existing visual-only menu row also left deletion semantics undefined across durable order, the Workspace table, Host streams, concurrent browser tabs, reconnect baselines, and a list request racing the mutation.
 
@@ -22,7 +22,7 @@ Registry operations serialize create and delete. Deletion first writes the Works
 
 The Host stream keeps its committed-id set through the preceding global-order write and removes the id only on the table deletion. Create rollback therefore emits no false removal, while every connected tab receives exactly the id needed to delete its projection.
 
-Create and delete write a durable `pendingMutation` before their record/order pair can diverge. Startup completes only the named create or delete and clears the marker; it never infers crash provenance from an orphan row alone. Unmarked order/table divergence therefore retains the registry's fail-loud corruption behavior. A deletion whose table write committed but marker cleanup failed still reports success—the requested state and removal frame are already committed—and the next startup clears that marker idempotently.
+Create and delete write a durable `pendingMutation` before their record/order pair can diverge. Startup completes only the operation named by that marker and clears it; an orphan row alone does not identify which operation was interrupted. Unmarked order/table divergence therefore retains the registry's fail-loud corruption behavior. A deletion whose table write committed but marker cleanup failed still reports success—the requested state and removal frame are already committed—and the next startup clears that marker idempotently.
 
 ## Client convergence
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
index 85f399142b..21c378b5c6 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其会话排序。该记录没有可靠的来源信息来证明 Harness 创建或拥有该目录，会话日志也是独立的持久化对象。若将行内 Delete 操作视为递归删除源码或删除会话，就会破坏该记录所有权边界之外的数据。
+Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其会话排序。该记录没有说 Harness 创建或拥有该目录，会话日志也是独立的持久化对象。若将行内 Delete 操作视为递归删除源码或删除会话，就会破坏该记录所有权边界之外的数据。
 
 现有菜单行只有视觉呈现，没有实际功能，因此持久化顺序、Workspace 表、Host 流、并发浏览器标签页、重连基线，以及列表请求与变更并发时的删除语义也没有定义。
 
@@ -22,7 +22,7 @@ Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其
 
 Host 流在前一笔全局顺序写入期间继续保留其已提交 id 集合，只在删除表行时移除该 id。因此，创建回滚不会发出错误的移除帧，而每个已连接标签页都能收到从自身投影中删除该记录所需的准确 id。
 
-Create 与 delete 会在记录／顺序对可能分叉之前写入持久化的 `pendingMutation`。启动时只补全其中明确命名的 create 或 delete，并清除该标记；系统绝不会仅凭孤立表行的形状推断崩溃来源。因此，没有标记的顺序／表分叉仍会保持注册表原有的损坏直接失败语义。如果删除的表写入已经提交、但标记清理失败，操作仍会报告成功——请求状态和移除帧都已经提交——下一次启动会以幂等方式清除该标记。
+Create 与 delete 会在记录／顺序对可能分叉之前写入持久化的 `pendingMutation`。启动时只补全该标记明确命名的操作，并清除标记；仅有一行孤立记录无法确定哪个操作被中断。因此，没有标记的顺序／表分叉仍会保持注册表原有的损坏直接失败语义。如果删除的表写入已经提交、但标记清理失败，操作仍会报告成功——请求状态和移除帧都已经提交——下一次启动会以幂等方式清除该标记。
 
 ## 客户端收敛
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index cf0c2038cb..c0e97060b2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
-2026-07-28-continuable-subagent-conversations.zh.md: cd73d9a3b5ff1b9671a7b08ed1482fa1ad45f48e
+2026-07-28-continuable-subagent-conversations.md: 632de8c9f7a6d2c71dcca6d817a827f788645b4e
+2026-07-28-continuable-subagent-conversations.zh.md: 9752dab97684d7249418c1a6d19905ab48ac82ca
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index 56d9abb2b0..632de8c9f7 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -40,17 +40,17 @@ Any failure before inbox acceptance rejects without returning either id. Agent c
 
 `backgroundMode: 'one-shot' | 'continuable'` remains deployment policy. Configured continuable mode requires `prepareContinuable`; method presence replaces `SubagentProvider.resume?()` as the capability check, while a capable provider may still run one-shot work.
 
-Cold resume does not dispatch through a subagent provider. The continuation manager folds the generic in-process descriptor, calls `ctx.agents.resume()` through the same activation-owner scope, installs the returned `AgentHandle`, and submits the waiting `next-turn`. `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent. The initial provider name remains lifecycle provenance after that provider unregisters; it is not a recovery capability or a requirement for later residency. Remote providers require a separate design.
+Cold resume does not dispatch through a subagent provider. The continuation manager folds the generic in-process descriptor, calls `ctx.agents.resume()` through the same activation-owner scope, installs the returned `AgentHandle`, and submits the waiting `next-turn`. `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent. The descriptor retains the initial provider name after that provider unregisters; the name does not grant a recovery capability or require the provider for later residency. Remote providers require a separate design.
 
 `SubagentProvider.start()` and `SubagentRun` remain exclusively on the unchanged one-shot path. A continuable Activation directly owns its `AgentHandle` and never creates, wraps, or retains a `SubagentRun`; `SubagentRun.steer?()` is therefore absent.
 
-`ctx.subagents.followup(parent, childId, content, { source, signal })` remains the sole parent-to-child continuation-message operation. The exact live parent Agent authorizes delivery; cold resume checks that authority before reconstruction and every path checks it again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. `source` remains durable provenance and grants no authority. The model-facing `send_message` tool keeps only its stable `subagent_id` and `message` fields and always submits a follow-up turn. Both start and follow-up return the accepted `MessageId`, and neither reports how the manager materialized the Activation.
+`ctx.subagents.followup(parent, childId, content, { source, signal })` remains the sole parent-to-child continuation-message operation. The exact live parent Agent authorizes delivery; cold resume checks that authority before reconstruction and every path checks it again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. `source` records who supplied the admitted message and grants no authority. The model-facing `send_message` tool keeps only its stable `subagent_id` and `message` fields and always submits a follow-up turn. Both start and follow-up return the accepted `MessageId`, and neither reports how the manager materialized the Activation.
 
 For start and follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance. After the operation returns its `MessageId`, the manager owns the Activation independently; later caller cancellation does not cancel the accepted turn or dispose the child.
 
 ### Durable Session and live Activation
 
-The Session owns the stable child identity, transcript, direct-parent lineage, delegation depth, and versioned continuation descriptor. `SessionHeader.parentSession` is durable provenance and an authorization input; it is not a live routing capability and does not imply that the historical parent is resident.
+The Session owns the stable child identity, transcript, direct-parent lineage, delegation depth, and versioned continuation descriptor. `SessionHeader.parentSession` records the direct parent and is an authorization input; it is not a live routing capability and does not imply that the recorded parent is resident.
 
 An idle historical Session has no `AgentHandle`. The first authorized `next-turn` delivery resumes an Activation from the persisted Session and submits the message to its inbox. Cold resume uses the exact live parent Agent for authorization and, when that parent has an Activation, ownership; it never uses the parent for reconstruction.
 
@@ -121,9 +121,9 @@ This version exposes no subagent steering operation. Parent continuation message
 
 A later host UI may expose separate **Steer** and **Follow up** actions. Host steering would be strict and live-only: it may call the existing Agent steering path only while the Activation accepts a next step, must reject otherwise, and must never fall back to queueing or cold resume. Exposing parent steering to a model-facing tool remains a separate design.
 
-### Authority and provenance
+### Authority and recorded sender identity
 
-Authority is supplied by an exact live Agent tool context. `MessageSource` and `senderSessionId` are durable provenance after admission, not caller-controlled authority.
+Authority is supplied by an exact live Agent tool context. After admission, `MessageSource` and `senderSessionId` record who supplied the message; callers cannot use those fields as authority.
 
 This version authorizes only the durable child's direct parent. The manager checks `SessionHeader.parentSession` against the exact live parent Agent at the final no-await inbox-admission boundary before registering the child in that parent's `ownedChildren`; cold resume also performs an earlier check before reconstruction for fail-fast rejection. Other Agents, ancestors, hosts, teams, and workflows remain rejected until a concrete consumer justifies another authority protocol.
 
@@ -137,7 +137,7 @@ Host and manager teardown remains the lifecycle stop path. Manager unload applie
 
 Each turn requests the Session durability checkpoint, while final Activation settlement additionally awaits `ctx.sessions.flush()` as a best-effort barrier. The manager deliberately ignores the boolean result because listener participation cannot identify a persistence backend. A rejection is logged without changing the lifecycle result or host-drain outcome; the manager still disposes the handle and releases ownership, and the persisted child state may be missing or stale on a later resume.
 
-Only messages written to the child Session log are reconstructable with their admitted provenance; inbox acceptance alone provides no restart guarantee.
+Only messages written to the child Session log are reconstructable with the source that supplied them; inbox acceptance alone provides no restart guarantee.
 
 Session and descriptor persistence survive restart. Activation state, Agent inbox contents, and the ownership graph are process-local. A process crash may lose an accepted initial prompt or follow-up that remained in the inbox without reaching the Session log. The Session and descriptor may survive so a later authorized message can cold-resume the child, but the lost message is not replayed automatically. Recovering accepted unfinished or unlogged messages requires a durable inbox protocol and is not implied here.
 
@@ -159,7 +159,7 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 **Make report delivery part of the base lifecycle.** Repeatable child-to-parent reporting is compatible with this lifecycle, but quiet versus waking delivery, acknowledgement, durability, and retry behavior are independent product choices. The later report package remains optional and consumes an explicit child-setup seam, so continuable residency does not silently grant a return channel.
 
-**Treat `SessionHeader.parentSession` as live ownership.** Durable lineage does not prove that the historical parent currently owns the child. Membership in the live parent's `ownedChildren` records the process-local relationship without changing durable provenance.
+**Treat `SessionHeader.parentSession` as live ownership.** Durable lineage does not prove that the recorded parent currently owns the child. Membership in the live parent's `ownedChildren` records the process-local relationship without changing the durable parent id.
 
 **Retain the exact parent Agent in a separate link.** The parent Activation already owns its `AgentHandle`, and `ownedChildren` prevents that Activation from disposing while the child remains live. Resolving the parent by Session id is therefore sufficient and avoids a redundant runtime reference.
 
@@ -181,9 +181,9 @@ The implementation pins these behaviors:
 - `SubagentProvider.prepareContinuable?()` returns only a detached `ContinuableCreateSpec`; configured continuable mode requires that capability, while `backgroundMode` remains an independent policy choice.
 - The manager calls `ctx.agents.create()` through its private activation-owner scope, installs the returned `AgentHandle` and parent ownership, calls `Agent.followup(initialPrompt)`, and returns `{ childId, messageId }` when inbox acceptance yields the `MessageId`, without waiting for turn start or a Session-log write.
 - Every failure before initial-prompt inbox acceptance rejects without ids and rolls back any created handle, Activation, and parent `ownedChildren` membership through a closing transaction visible to concurrent delivery and drain; lifecycle publication failure emits no unmatched terminal edge.
-- Cold resume calls `ctx.agents.resume()` from the continuation manager and never dispatches through or requires the initial subagent provider; the persisted provider name remains lifecycle provenance after provider removal, while `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent.
+- Cold resume calls `ctx.agents.resume()` from the continuation manager and never dispatches through or requires the initial subagent provider; the descriptor retains the initial provider name after provider removal, while `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent.
 - A continuable Activation directly owns `AgentHandle` and never creates, wraps, or retains `SubagentRun`; `SubagentProvider.start()` and `SubagentRun` remain one-shot-only, without `SubagentRun.steer?()`.
-- `followup()` accepts only the exact live direct parent and rechecks that identity at the final no-await inbox-admission boundary after any materialization; durable message provenance cannot authorize delivery.
+- `followup()` accepts only the exact live direct parent and rechecks that identity at the final no-await inbox-admission boundary after any materialization; durable message source fields cannot authorize delivery.
 - Continuation messages always use `Agent.followup()` and share its inbox FIFO, including when the child already has an open turn.
 - `ctx.subagents.followup()` and its `send_message` adapter return only the accepted `MessageId`; the continuation layer accepts no delivery target and defines no subagent-specific route result.
 - Caller signals stop start and follow-up only before inbox acceptance, while host-scoped and manager-global teardown retain child-first cleanup; the [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md) is the one public stop and does not enter teardown.
@@ -194,7 +194,7 @@ The implementation pins these behaviors:
 - Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, logs rejection without interpreting listener participation as durability proof, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation.
 - Manager teardown closes admission globally; a host owning selected top-level Agents instead closes admission only below their exact identities until those roots leave the registry. Both track admitted materializations by exact ancestry, install one memoized disposal cutoff per selected visible Activation, propagate cancellation top-down, release handles child-first, await every selected branch despite individual failures, and only then dispose the corresponding top-level Agents or manager scope.
 - The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup seam.
-- Session logs reconstruct only messages that were actually written, with their admitted provenance; inbox-accepted but unlogged messages have no restart guarantee.
+- Session logs reconstruct only messages that were actually written, with the source that supplied each message; inbox-accepted but unlogged messages have no restart guarantee.
 - No continuable-subagent path creates or depends on a Task, `TaskId`, Task completion notice, Task cancellation, or intermediate result-bearing execution wrapper.
 - Unit coverage pins the `startContinuable()` inbox-acceptance return boundary, complete rollback for each pre-acceptance and lifecycle-publication failure, global and parent-scoped drain quiescence for materialization caught between Agent publication and Activation registration, sibling-forest isolation, exact ancestry after an intermediate Agent leaves the registry, provider-independent cold resume, final exact-parent reauthorization after cold-resume materialization, caller-signal and teardown ownership on both sides of acceptance, and the absence of automatic replay for accepted-but-unlogged messages.
 - Unit coverage pins the residency-only routing table, single-inbox ordering, `MessageId` correlation through inbox events, follow-up during an open turn, waiting wakeup, cold resume, ownership registration and release, child-first disposal, send-versus-dispose races, best-effort final flush with absent and failing listeners, and the absence of public subagent cancellation and steering.
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index cd73d9a3b5..9752dab976 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -40,17 +40,17 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的
 
 `backgroundMode: 'one-shot' | 'continuable'` 仍是部署策略。配置为 continuable 时要求存在 `prepareContinuable`；该方法是否存在会取代 `SubagentProvider.resume?()` 成为能力检查，而具备该能力的提供方仍可运行 one-shot 工作。
 
-冷恢复不会通过 subagent 提供方分发。继续执行管理器会归并通用的进程内描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，安装返回的 `AgentHandle`，并提交等待中的 `next-turn`。`SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。初始提供方注销后，其名称仍作为生命周期来源信息保留；它不是恢复能力，也不是后续驻留的必要条件。远程提供方需要单独设计。
+冷恢复不会通过 subagent 提供方分发。继续执行管理器会归并通用的进程内描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，安装返回的 `AgentHandle`，并提交等待中的 `next-turn`。`SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。初始提供方注销后，描述符仍保留其名称；该名称不赋予恢复能力，也不要求后续驻留时该提供方存在。远程提供方需要单独设计。
 
 `SubagentProvider.start()` 和 `SubagentRun` 只保留在不变的 one-shot 路径上。可继续激活直接持有自身的 `AgentHandle`，绝不创建、包装或保留 `SubagentRun`；因此，`SubagentRun.steer?()` 不存在。
 
-`ctx.subagents.followup(parent, childId, content, { source, signal })` 仍是唯一的从 parent 到 child 的继续执行消息操作。确切的在线 parent Agent 授权投递；冷恢复会在重建前检查该权限，每条路径还会在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。`source` 仍是持久化来源信息，不赋予任何权限。面向模型的 `send_message` 工具只保留稳定的 `subagent_id` 和 `message` 字段，并始终提交一个 follow-up 轮次。start 和 follow-up 都返回已接受的 `MessageId`，两者都不报告管理器如何物化激活。
+`ctx.subagents.followup(parent, childId, content, { source, signal })` 仍是唯一的从 parent 到 child 的继续执行消息操作。确切的在线 parent Agent 授权投递；冷恢复会在重建前检查该权限，每条路径还会在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。`source` 记录谁提供了获准消息，不赋予任何权限。面向模型的 `send_message` 工具只保留稳定的 `subagent_id` 和 `message` 字段，并始终提交一个 follow-up 轮次。start 和 follow-up 都返回已接受的 `MessageId`，两者都不报告管理器如何物化激活。
 
 对于 start 和 follow-up，调用方 signal 只在 inbox 接受消息前持有查找、物化和准入。操作返回 `MessageId` 后，管理器会独立持有该激活；调用方之后的取消不会取消已接受的轮次，也不会 dispose child。
 
 ### 持久化会话与在线激活
 
-会话持有稳定的 child 身份、transcript（文本记录）、直接 parent 谱系、委派深度和带版本的继续执行描述符。`SessionHeader.parentSession` 是持久化来源信息和鉴权输入；它不是在线路由能力，也不表示历史 parent 仍然驻留。
+会话持有稳定的 child 身份、transcript（文本记录）、直接 parent 谱系、委派深度和带版本的继续执行描述符。`SessionHeader.parentSession` 记录直接 parent，并作为鉴权输入；它不是在线路由能力，也不表示记录的 parent 仍然驻留。
 
 空闲的历史会话没有 `AgentHandle`。第一条通过鉴权的 `next-turn` 投递会根据持久化会话恢复激活，并将消息提交到其 inbox。冷恢复使用经过身份认证的确切在线 parent Agent 执行鉴权；当该 parent 有激活时，还使用它建立所有权，但绝不使用 parent 执行重建。
 
@@ -121,9 +121,9 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 后续宿主 UI 可以分别暴露 **Steer** 和 **Follow up** 操作。宿主 steering 必须严格且仅限在线使用：只有当激活接受下一步骤时，它才能调用现有的 Agent steering 路径；其他情况必须拒绝，而且绝不能转为排队或冷恢复。是否通过面向模型的工具暴露 parent steering 仍需单独设计。
 
-### 权限与来源
+### 权限与已记录的发送方身份
 
-权限来自确切的在线 Agent 工具上下文。`MessageSource` 和 `senderSessionId` 是准入后的持久化来源信息，不是由调用方控制的权限。
+权限来自确切的在线 Agent 工具上下文。准入后，`MessageSource` 和 `senderSessionId` 记录谁提供了消息；调用方不能用这些字段取得权限。
 
 本版本只授权持久化 child 的直接 parent。管理器会在将 child 注册到该 parent 的 `ownedChildren` 之前，于最终无 await 的 inbox 准入边界根据确切的在线 parent Agent 检查 `SessionHeader.parentSession`；冷恢复还会在重建前执行一次更早的检查，以便快速失败。其他 Agent、祖先、宿主、团队和工作流仍被拒绝，直至有具体消费方证明另一种权限协议合理。
 
@@ -137,7 +137,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 每个轮次都会请求执行会话持久性检查点，而 Activation 最终结算还会等待 `ctx.sessions.flush()`，将其作为 best-effort 屏障。管理器特意忽略布尔结果，因为 listener 是否参与无法标识持久化后端。rejection 会被记录，但不会改变生命周期结果或宿主 drain 的结果；管理器仍会 dispose handle 并释放所有权，后续恢复时持久化 child 状态可能缺失或陈旧。
 
-只有实际写入 child 会话日志的消息，才能根据其准入来源重建；仅被 inbox 接受并不提供重启保证。
+只有实际写入 child 会话日志的消息，才能在重建时保留提供它的来源；仅被 inbox 接受并不提供重启保证。
 
 会话和描述符的持久化状态可在重启后保留。激活状态、Agent inbox 内容和所有权图都是进程内状态。进程崩溃可能丢失已被接受但仍留在 inbox、尚未写入会话日志的初始提示词或 follow-up。会话和描述符可能保留，因此后续获得授权的消息仍可冷恢复 child，但丢失的消息不会自动回放。恢复已接受但未完成或未写入日志的消息需要持久化 inbox 协议，本提案不隐含该能力。
 
@@ -159,7 +159,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **将报告投递纳入基础生命周期。** 可重复的 child 到 parent 报告与该生命周期兼容，但静默投递还是唤醒投递、确认、持久性和重试行为都是独立的产品决策。后续的 report 包保持可选，并消费一条显式 child 设置 seam，因此可继续驻留不会默认授予返回通道。
 
-**将 `SessionHeader.parentSession` 视为在线所有权。** 持久化谱系不能证明历史 parent 当前持有 child。在线 parent 的 `ownedChildren` 成员关系会记录进程内关系，而不改变持久化来源。
+**将 `SessionHeader.parentSession` 视为在线所有权。** 持久化谱系不能证明已记录的 parent 当前持有 child。在线 parent 的 `ownedChildren` 成员关系会记录进程内关系，而不改变持久化 parent id。
 
 **在单独的 link 中保留确切的 parent Agent。** parent 激活已经持有自身 `AgentHandle`，而且 `ownedChildren` 会在 child 仍然在线时阻止该激活 dispose。因此，通过会话 id 解析 parent 已经足够，也可以避免冗余的运行时引用。
 
@@ -181,7 +181,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - `SubagentProvider.prepareContinuable?()` 只返回分离式 `ContinuableCreateSpec`；配置为 continuable 时要求具备该能力，而 `backgroundMode` 仍是独立的策略选择。
 - 管理器通过私有 activation-owner 作用域调用 `ctx.agents.create()`，安装返回的 `AgentHandle` 并建立 parent 所有权，调用 `Agent.followup(initialPrompt)`，然后在 inbox 接受消息并产生 `MessageId` 时返回 `{ childId, messageId }`，而不等待轮次开始或消息写入会话日志。
 - 初始提示词被 inbox 接受前的每条失败路径都会导致操作被拒绝且不返回 id，并通过一个对并发投递和 drain 可见的关闭事务回滚已创建的任何 handle、激活和 parent `ownedChildren` 成员关系；生命周期发布失败不会产生无配对的终止事件。
-- 冷恢复由继续执行管理器调用 `ctx.agents.resume()`，绝不通过或依赖初始 subagent 提供方；提供方移除后，持久化的提供方名称仍作为生命周期来源信息保留，且 `SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。
+- 冷恢复由继续执行管理器调用 `ctx.agents.resume()`，绝不通过或依赖初始 subagent 提供方；提供方移除后，描述符仍保留初始提供方名称，且 `SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。
 - 可继续激活直接持有 `AgentHandle`，绝不创建、包装或保留 `SubagentRun`；`SubagentProvider.start()` 和 `SubagentRun` 只用于 one-shot，且没有 `SubagentRun.steer?()`。
 - `followup()` 只接受确切的在线直接 parent，并在任何物化之后的最终无 await 的 inbox 准入边界再次检查该身份；持久化消息来源信息不能授权投递。
 - 继续执行消息始终使用 `Agent.followup()` 并共享其 inbox FIFO，包括 child 已有开放轮次的情况。
@@ -194,7 +194,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。
 - 管理器拆卸会全局关闭准入；拥有选定顶层 Agent 的宿主则只关闭这些确切身份之下的准入，直到这些根离开注册表。两者都会按确切祖先关系跟踪已获准的物化过程，为每个选中的可见 Activation 安装一个记忆化 dispose 截止点，自顶向下传播取消，按 child-first 顺序释放 handle，即使个别分支失败也会等待所有选中分支，之后才 dispose 对应的顶层 Agent 或管理器作用域。
 - 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup seam 贡献一个显式的 child 作用域工具。
-- 会话日志只能根据准入来源重建实际写入的消息；已被 inbox 接受但未写入日志的消息没有重启保证。
+- 会话日志只会重建实际写入的消息，并保留每条消息的提供来源；已被 inbox 接受但未写入日志的消息没有重启保证。
 - 可继续 subagent 路径不创建或依赖 Task、`TaskId`、Task 完成通知、Task 取消或中间的带结果执行包装层。
 - 单元覆盖固定 `startContinuable()` 在 inbox 接受消息时的返回边界、每条接受前和生命周期发布失败路径的完整回滚、全局和限定到 parent 作用域的 drain 都会等待夹在 Agent 发布与 Activation 注册之间的物化过程完全停稳、同级森林隔离、中间 Agent 离开注册表后的确切祖先关系、不依赖提供方的冷恢复、冷恢复物化后的最终确切 parent 再授权、接受前后两个阶段的调用方 signal 与拆卸所有权，以及已接受但未写入日志的消息不会自动回放。
 - 单元覆盖固定仅由驻留状态决定的路由表、单 inbox 顺序、通过 inbox 事件关联 `MessageId`、在开放轮次期间 follow-up、等待唤醒、冷恢复、所有权注册与释放、child-first dispose、发送与 dispose 的竞争、没有 listener 和 listener 失败时的 best-effort 最终 flush，以及不存在公开 subagent 取消和 steering。
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
index 8e7e02fe37..716ac0d144 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.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 .agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
-2026-07-30-continuable-subagent-report-tool.md: 8324f1fa08f7dace6153712575e7e70a07ee9344
-2026-07-30-continuable-subagent-report-tool.zh.md: 6b7472717e724af9bf598fada6d7e82070d06f3c
+2026-07-30-continuable-subagent-report-tool.md: 6a607f1da48fdfde36b2d9351f131dd3ef67ba7f
+2026-07-30-continuable-subagent-report-tool.zh.md: 6dd408aff755ef7d4e27a62b347ffc839616c702
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
index 8324f1fa08..6a607f1da4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
@@ -28,7 +28,7 @@ The tool uses generic rendering with no locations. Its acknowledgement includes
 
 ### Service authority
 
-The subagent seam exposes `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`. The exact live child Agent is the sender credential. The continuation manager accepts only an Activation whose `handle.agent === child`, derives its direct parent from the child's durable header, and requires that id to resolve to a live parent Agent in the final synchronous authorization-and-send span. The API accepts no caller-selected recipient, ancestor, or provenance.
+The subagent seam exposes `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`. The exact live child Agent is the sender credential. The continuation manager accepts only an Activation whose `handle.agent === child`, derives its direct parent from the child's durable header, and requires that id to resolve to a live parent Agent in the final synchronous authorization-and-send span. The API accepts no caller-selected recipient, ancestor, or sender fields.
 
 Roots, one-shot children, forged objects, stale Agents, and same-id replacements fail with `UNAUTHORIZED`. A closing child Activation fails with `ACTIVATION_CLOSING`; manager drain and pre-acceptance cancellation retain their existing lifecycle errors. A missing or send-rejecting direct parent fails with `PARENT_UNAVAILABLE` and `direct parent is not live; report was not delivered`. Failure returns no id, cold-resumes no parent, writes no offline mailbox, and mutates no absent-parent Session.
 
@@ -42,7 +42,7 @@ Quiet delivery calls `parent.inject()`. It adds model-visible context without st
 
 Waking delivery calls `parent.followup()`. It creates one ordinary FIFO parent turn, wakes a parked parent driver, and never steers an open turn. When that parent is itself a continuable Activation, the send uses the manager's existing admission accounting so the parent cannot settle between synchronous enqueue and the admission microtask.
 
-Both modes frame one user-role message as `Background subagent <child-id> reported:` followed by the exact `output`. Durable provenance is `{ kind: 'subagent-report', senderSessionId: child.id }`. Normal Agent ordering governs concurrent sends; the subagent layer creates no second queue.
+Both modes frame one user-role message as `Background subagent <child-id> reported:` followed by the exact `output`. The durable message source is `{ kind: 'subagent-report', senderSessionId: child.id }`. Normal Agent ordering governs concurrent sends; the subagent layer creates no second queue.
 
 ### Acknowledgement and recovery
 
@@ -106,7 +106,7 @@ A post-creation revocation check can reject the Activation only after the Agent
 - Quiet delivery is the validated default and never starts a parent request. Wakeup creates exactly one later FIFO turn and never steers an open turn.
 - Child cancellation or disposal after parent acceptance does not retract the report. Before acceptance, child disposal, drain, parent loss, or caller cancellation rejects the operation.
 - Fresh and resumed Activations compose current setup contributions before publication. Grants wait for the next Activation; revocation is immediate for resident children.
-- Unit coverage pins visibility, allow-list behavior, both delivery modes, stable identity and provenance, nested routing, invalid senders, absent parents, cancellation, drain, revocation races, and the absence of Tasks or implicit final reporting.
+- Unit coverage pins visibility, allow-list behavior, both delivery modes, stable message and sender identities, nested routing, invalid senders, absent parents, cancellation, drain, revocation races, and the absence of Tasks or implicit final reporting.
 - The keyless assembled snapshot proves the real child tool, quiet non-wakeup behavior, durable parent framing, and later parent consumption.
 
 ### Accepted risks
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
index 6b7472717e..6dd408aff7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ### 服务权限
 
-subagent seam 暴露 `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`。确切的在线 child Agent 是发送方凭据。继续执行管理器只接受 `handle.agent === child` 的 Activation，从 child 的持久化 header 中推导其直接 parent，并要求该 id 在最终的同步授权与发送区间解析为一个在线 parent Agent。该 API 不接受由调用方选择的接收方、祖先或来源信息。
+subagent seam 暴露 `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`。确切的在线 child Agent 是发送方凭据。继续执行管理器只接受 `handle.agent === child` 的 Activation，从 child 的持久化 header 中推导其直接 parent，并要求该 id 在最终的同步授权与发送区间解析为一个在线 parent Agent。该 API 不接受由调用方选择的接收方、祖先或发送方字段。
 
 root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以 `UNAUTHORIZED` 失败。正在关闭的 child Activation 以 `ACTIVATION_CLOSING` 失败；管理器 drain 和接受前取消保留既有的生命周期错误。直接 parent 不存在或拒绝接受时，以 `PARENT_UNAVAILABLE` 和 `direct parent is not live; report was not delivered` 失败。失败不返回 id，不冷恢复 parent，不写入离线邮箱，也不会修改缺失 parent 的会话。
 
@@ -42,7 +42,7 @@ root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以
 
 唤醒投递调用 `parent.followup()`。它会创建一个普通的 FIFO parent 轮次，唤醒已驻留的 parent driver，且绝不 steering 已开始的轮次。当该 parent 本身也是可继续 Activation 时，发送会使用管理器现有的准入计数，防止 parent 在同步入队与准入微任务之间结算。
 
-两种模式都会将一条用户角色消息封装为 `Background subagent <child-id> reported:`，后面跟随完全原样的 `output`。持久化来源信息为 `{ kind: 'subagent-report', senderSessionId: child.id }`。并发发送的顺序由 Agent 的常规规则决定；subagent 层不会创建第二条队列。
+两种模式都会将一条用户角色消息封装为 `Background subagent <child-id> reported:`，后面跟随完全原样的 `output`。持久化消息来源为 `{ kind: 'subagent-report', senderSessionId: child.id }`。并发发送的顺序由 Agent 的常规规则决定；subagent 层不会创建第二条队列。
 
 ### 确认与恢复
 
@@ -106,7 +106,7 @@ ACP（Agent Client Protocol）快照 harness 新增 `waitForSubagentTurnEnd`，
 - 静默投递是校验后的默认模式，绝不会启动 parent 请求。wakeup 会恰好创建一个后续 FIFO 轮次，绝不 steering 已开始的轮次。
 - parent 接受后取消或 dispose child 不会撤回报告。接受前，child dispose、drain、parent 丢失或调用方取消都会拒绝操作。
 - 新建和恢复的 Activation 都会在发布前组合当前设置贡献。新授权等待下一个 Activation 才生效，而已驻留 child 的授权撤销立即生效。
-- 单元覆盖固定可见性、allow-list 行为、两种投递模式、稳定身份与来源信息、嵌套路由、无效发送方、缺失的 parent、取消、drain、撤销竞争，以及不存在 Task 或隐式最终报告。
+- 单元覆盖固定可见性、allow-list 行为、两种投递模式、稳定的消息与发送方身份、嵌套路由、无效发送方、缺失的 parent、取消、drain、撤销竞争，以及不存在 Task 或隐式最终报告。
 - 无密钥整体组装快照证明真实 child 工具、静默且不唤醒的行为、持久化 parent 封装，以及 parent 后续消费。
 
 ### 已接受的风险
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index f9944e3ed8..9921a12aee 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.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 .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
-2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
-2026-07-30-queued-manual-compaction.zh.md: fe3b0ff5e6b8cab7cb332f958adc6ab8d94f23b8
+2026-07-30-queued-manual-compaction.md: 94afdd84dfe573ee2b60eb3dbfdae2dd5b6beb1e
+2026-07-30-queued-manual-compaction.zh.md: 96eaa667eaee8adb42ec63e35beb0b32912c83a0
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
index 5100808ada..94afdd84df 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
@@ -91,7 +91,7 @@ That reference also carried client-side replacement-anchor machinery to preserve
 
 **Hold injection with waking prompts.** Rejected because idle injection is non-waking durable context by contract; delaying it would make plugin ordering depend on a UI command.
 
-**Require the marker interval to contain only compaction events.** Rejected because markers represent lock time points. Provenance names the selected and shadowed seqs exactly; exclusivity would add no correctness and would reject valid injection.
+**Require the marker interval to contain only compaction events.** Rejected because markers represent lock time points. `compact/summary` names the selected range and shadowed seqs exactly; exclusivity would add no correctness and would reject valid injection.
 
 **Treat every unmatched marker as permanently busy.** Rejected because a crash-recovered or forked session would remain wedged. `session/end-seed` is the explicit lifecycle evidence that distinguishes stale history from a live process-local attempt.
 
@@ -105,6 +105,6 @@ The command package pins registration, Loader composition, argument rejection, e
 
 Interactive users can compact useful history without spending a conversation-model turn. A prompt accepted before the command wins; one submitted during the command waits with its original queue identity. Manual compaction consumes session seqs but no turn number.
 
-The log exposes slow, failed, crashed, and successful attempts through the same bracket. A stale pre-boundary orphan no longer wedges a new lifecycle, while a current unmatched start remains a hard busy signal. Marker intervals may contain unrelated events, so consumers use provenance and relative ordering rather than assuming a contiguous compaction-only slice.
+The log exposes slow, failed, crashed, and successful attempts through the same bracket. A stale pre-boundary orphan no longer wedges a new lifecycle, while a current unmatched start remains a hard busy signal. Marker intervals may contain unrelated events, so consumers use the seqs recorded in `compact/summary` and relative ordering rather than assuming a contiguous compaction-only slice.
 
 The shared transaction keeps one ordering and one lock across every entry point. Failure reporting is precise about whether only the log changed, the surface may have partially changed, or the in-memory commit could not be persisted.
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index fe3b0ff5e6..96eaa667ea 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -91,7 +91,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 **与唤醒提示词一起阻塞注入。** 不予采用，因为按约定，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
 
-**要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
+**要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。`compact/summary` 会精确指明所选区间与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
 
 **把每个未匹配标记都永久视为 busy。** 不予采用，因为崩溃恢复或 fork 后的会话会永久卡住。`session/end-seed` 是区分陈旧历史与当前进程活动尝试的显式生命周期证据。
 
@@ -105,6 +105,6 @@ Agent loop 测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命
 
 交互用户无需消耗会话模型轮次即可压缩有效历史。在命令前获接纳的提示词胜出；命令期间提交的提示词会以原有队列身份等待。手动压缩会消耗会话 seq，但不消耗轮次编号。
 
-日志通过同一对标记暴露缓慢、失败、崩溃与成功的尝试。边界前的陈旧未匹配标记不会再卡住新的生命周期，而当前未匹配 start 仍是严格的 busy 信号。标记区间可以包含不相关事件，因此消费方使用溯源信息与相对顺序，而不假定存在连续且仅含压缩事件的切片。
+日志通过同一对标记暴露缓慢、失败、崩溃与成功的尝试。边界前的陈旧未匹配标记不会再卡住新的生命周期，而当前未匹配 start 仍是严格的 busy 信号。标记区间可以包含不相关事件，因此消费方使用 `compact/summary` 记录的 seq 与相对顺序，而不假定存在连续且仅含压缩事件的切片。
 
 共享事务让每个入口点保持同一种顺序并使用同一把锁。失败报告会精确区分只有日志发生变化、surface 可能部分改变，以及内存 commit 无法持久化这三种情况。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
index abb67be310..7876882425 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.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 .agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
-2026-08-04-web-context-source-and-steer-marks.md: ca44702cf637c4250d141396ac22d206a16acc15
-2026-08-04-web-context-source-and-steer-marks.zh.md: 09cefd07e3b417b63f05ce430cfed7b30597452f
+2026-08-04-web-context-source-and-steer-marks.md: d74badedaa9623014dbba10ae68ca680daf75de1
+2026-08-04-web-context-source-and-steer-marks.zh.md: f7a84db9d53a2f270ad47828c7aead2fd5ce8a68
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
index ca44702cf6..d74badedaa 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
@@ -8,13 +8,13 @@ English | [中文](2026-08-04-web-context-source-and-steer-marks.zh.md)
 
 Everything a producer adds to the model-facing conversation reached the Web transcript as one of two anonymous shapes. Every logged non-user `user/message` — the skill catalog, the runtime snapshot, reconciled `AGENTS.md` instructions, a guard notice, a subagent report, a cross-session snapshot — collapsed into one identical `上下文注入` row, so a reader could not tell what had been added without expanding each row and reading raw JSON. Mid-turn steering was worse: it rendered in exactly the bubble a turn-opening prompt uses, leaving the transcript unable to say which message interrupted a running turn.
 
-The distinctions are already durable. `user/message.source` is the merge-extensible provenance every producer must supply, while `agent/inbox/spliced` records whether an identified message entered and left `next-turn` or `next-step`; only the presentation discarded them. The terminal transcript this Web UI replaced did name each card's producer, so the Web surface was a regression for the same log.
+The distinctions are already durable. Every producer must supply a merge-extensible `user/message.source` that identifies itself, while `agent/inbox/spliced` records whether an identified message entered and left `next-turn` or `next-step`; only the presentation discarded them. The terminal transcript this Web UI replaced did name each card's producer, so the Web surface was a regression for the same log.
 
 ## Decision
 
 The transcript names all three roles a non-prompt message can play — injected context, recalled session, and steering.
 
-`TranscriptAdapter` and the history fold attach a `provenance` view to every `ContextMessageNode`, computed by `contextProvenance()` from the durable source alone. It returns a `role` (`inject`, or `recall` for a cross-session snapshot) and a `label` naming the producer. `ContextInjectionRow` titles itself from the role and shows the label beside that title in `ToolRow`'s summary geometry, so the collapsed row already answers what was added and by whom; the 141px scrollport and truncation bound are unchanged from the [archived disclosure decision](../../archived/feature/2026-07-30-web-context-injection-disclosure.md). What renders inside that scrollport is chosen by the independent form axis added in the [context form decision](2026-08-05-context-form-vocabulary.md).
+`TranscriptAdapter` and the history fold attach a `provenance` view containing the producer role and label to every `ContextMessageNode`; `contextProvenance()` computes it from the durable source alone. It returns a `role` (`inject`, or `recall` for a cross-session snapshot) and a `label` naming the producer. `ContextInjectionRow` titles itself from the role and shows the label beside that title in `ToolRow`'s summary geometry, so the collapsed row already answers what was added and by whom; the 141px scrollport and truncation bound are unchanged from the [archived disclosure decision](../../archived/feature/2026-07-30-web-context-injection-disclosure.md). What renders inside that scrollport is chosen by the independent form axis added in the [context form decision](2026-08-05-context-form-vocabulary.md).
 
 **The label is read out of the log, never from a client-side table of producer names.** `workspace-instructions` is named by the distinct instruction paths it reconciled, `session-reference` by the titles of the sessions it read, a plugin source by its logged plugin id, and any other source by its own `kind` — the documented default arm for a merge-extensible union. A source carrying no readable kind degrades to an unnamed injection. A new or renamed producer is therefore identifiable without a client release, no label can go stale against the code, and a resumed, forked, or foreign log projects exactly like a live session.
 
@@ -24,7 +24,7 @@ The transcript names all three roles a non-prompt message can play — injected
 
 ## Alternatives considered
 
-**Localize producer names in the client.** A dictionary keyed by plugin id would read better than `@deepseek-ai/dsh-system-prompt`, but it drifts silently on every rename, needs a client change per new producer, and cannot name a producer from a foreign log at all. Provenance the log already carries is worth more than prose the client invents.
+**Localize producer names in the client.** A dictionary keyed by plugin id would read better than `@deepseek-ai/dsh-system-prompt`, but it drifts silently on every rename, needs a client change per new producer, and cannot name a producer from a foreign log at all. The producer name already recorded in the log is more reliable than a label the client invents.
 
 **Register presentations per source kind.** The disclosure decision deferred a keyed context-view slot until source-owned presentations emerged. Naming a row is not a distinct presentation, and a registry keyed on mounted producers would fail exactly where it matters — a resumed log whose producer is no longer mounted still has to render.
 
@@ -36,14 +36,14 @@ The transcript names all three roles a non-prompt message can play — injected
 
 ## Testing
 
-- `packages/client/runtime` unit coverage pins each provenance arm, the label fallbacks when a name field is missing, empty, or wrongly typed, the unnamed degradation for a source with no readable kind, and steering reconstruction on reset and live append paths.
+- `packages/client/runtime` unit coverage pins each source kind, the label fallbacks when a name field is missing, empty, or wrongly typed, the unnamed degradation for a source with no readable kind, and steering reconstruction on reset and live append paths.
 - `packages/client/ui-conversation` jsdom coverage pins the role title, the producer label beside it, the label's survival while expanded, the roleless header, and the steering caption on both durable and pending bubbles.
 - The keyless assembled-Web goldens carry the named header and the steering caption, so the assembled transcript — not only component tests — proves the marks.
 
 ## Consequences
 
 - A reader can attribute every non-prompt message in the transcript at a glance, and the header stays honest for logs this client version has never seen a producer for.
-- Producer names in the UI are package-shaped (`dsh-tool-skill`, `@deepseek-ai/dsh-system-prompt`) wherever the source carries only a plugin id. That is the cost of refusing a client-side name table; a producer that wants a better name records better provenance.
+- Producer names in the UI are package-shaped (`dsh-tool-skill`, `@deepseek-ai/dsh-system-prompt`) wherever the source carries only a plugin id. That is the cost of refusing a client-side name table; a producer that wants a better label must record one in its source fields.
 - `ContextMessageNode` gains a required field, so every constructed node — including test fixtures — must supply it.
 - `SteeringMessageNode` remains a distinct presentation node even though the agent loop now records admitted steering as `user/message`; its identity comes from the durable inbox history rather than a separate message event.
 - The `recall` arm has no producer in a shipped Web leaf until a host mounts `dsh-session-reference`; it is reachable only through logs written elsewhere.
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
index 09cefd07e3..f7a84db9d5 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
@@ -8,13 +8,13 @@ Status: implemented
 
 生产方向模型侧对话补充的一切内容，进入 Web transcript（文本记录）后只剩两种匿名形态。每一条已记录的非用户 `user/message`——skill 目录、运行时快照、经过对账的 `AGENTS.md` 指令、guard 提示、子 agent 汇报、跨会话快照——都塌缩成同一行 `上下文注入`，读者不逐行展开去读原始 JSON 就无从知道究竟注入了什么。steering（中途引导）的情况更糟：它渲染成与开轮提示完全相同的气泡，于是 transcript 无法说明哪一条消息打断了正在运行的轮次。
 
-这些区分本来就是持久事实。`user/message.source` 是每个生产方都必须提供的可合并扩展来源，`agent/inbox/spliced` 则记录有身份的消息是从 `next-turn` 还是 `next-step` 进入和离开；把这些事实丢掉的只有呈现层。被这套 Web UI 取代的终端 transcript 本来会写出每张卡片的生产者，因此面对同一份日志，Web 侧是一次倒退。
+这些区分本来就是持久事实。每个生产方都必须提供可合并扩展的 `user/message.source` 并在其中注明自己，`agent/inbox/spliced` 则记录有身份的消息是从 `next-turn` 还是 `next-step` 进入和离开；把这些事实丢掉的只有呈现层。被这套 Web UI 取代的终端 transcript 本来会写出每张卡片的生产者，因此面对同一份日志，Web 侧是一次倒退。
 
 ## Decision
 
 transcript 为非提示消息可能承担的三种角色分别命名：注入上下文、召回会话、steering。
 
-`TranscriptAdapter` 与历史折叠为每个 `ContextMessageNode` 附加一份 `provenance` 视图，由 `contextProvenance()` 仅依据持久来源计算得出。它返回 `role`（`inject`，跨会话快照则为 `recall`）与命名生产者的 `label`。`ContextInjectionRow` 以角色作为标题，并按 `ToolRow` 摘要的几何在标题旁展示该名称，因此折叠态就已经回答了「注入了什么、由谁注入」；141px 滚动视口与截断上限沿用[已归档的展开项决策](../../archived/feature/2026-07-30-web-context-injection-disclosure.md)，未作改动。视口里渲染什么，则由[上下文形态决策](2026-08-05-context-form-vocabulary.md)引入的、相互独立的形态轴决定。
+`TranscriptAdapter` 与历史折叠为每个 `ContextMessageNode` 附加一份包含生产者角色和名称的 `provenance` 视图；`contextProvenance()` 仅依据持久来源计算该视图。它返回 `role`（`inject`，跨会话快照则为 `recall`）与命名生产者的 `label`。`ContextInjectionRow` 以角色作为标题，并按 `ToolRow` 摘要的几何在标题旁展示该名称，因此折叠态就已经回答了「注入了什么、由谁注入」；141px 滚动视口与截断上限沿用[已归档的展开项决策](../../archived/feature/2026-07-30-web-context-injection-disclosure.md)，未作改动。视口里渲染什么，则由[上下文形态决策](2026-08-05-context-form-vocabulary.md)引入的、相互独立的形态轴决定。
 
 **名称从日志中读出，绝不来自客户端维护的生产者名称表。** `workspace-instructions` 以它对账过的去重指令文件路径命名，`session-reference` 以它读取的会话标题命名，插件来源以其记录的插件 id 命名，其余来源则以自身的 `kind` 命名——这正是可合并扩展联合类型有文档记载的默认分支。没有可读 kind 的来源降级为无名注入。于是新增或重命名的生产者无需客户端发版即可辨识，任何名称都不会相对代码变味，恢复、fork 或来自外部的日志与实时会话的投影结果完全一致。
 
@@ -24,7 +24,7 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 
 ## Alternatives considered
 
-**在客户端本地化生产者名称。** 以插件 id 为键的字典读起来确实比 `@deepseek-ai/dsh-system-prompt` 好，但它会在每次重命名时悄悄失准，每新增一个生产者都要改客户端，而且对来自外部的日志根本无法命名。日志已经承载的来源，比客户端自己编出来的措辞更有价值。
+**在客户端本地化生产者名称。** 以插件 id 为键的字典读起来确实比 `@deepseek-ai/dsh-system-prompt` 好，但它会在每次重命名时悄悄失准，每新增一个生产者都要改客户端，而且对来自外部的日志根本无法命名。日志已经记录的生产者名称，比客户端自己编造的标签更可靠。
 
 **按来源 kind 注册呈现。** 展开项决策把键控的 context-view 槽位推迟到出现由来源自有的呈现需求为止。为一行命名并不构成独立呈现，而以「已挂载的生产者」为键的注册表恰恰会在最要紧的地方失效——生产者已不再挂载的恢复日志同样必须渲染出来。
 
@@ -43,7 +43,7 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 ## Consequences
 
 - 读者一眼即可归因 transcript 中每一条非提示消息；即便面对本客户端版本从未见过其生产者的日志，标题栏依然如实。
-- 只要来源仅携带插件 id，UI 中的生产者名称就呈现为包名形态（`dsh-tool-skill`、`@deepseek-ai/dsh-system-prompt`）。这是拒绝客户端名称表的代价；想要更好名称的生产者应当记录更好的来源。
+- 只要来源仅携带插件 id，UI 中的生产者名称就呈现为包名形态（`dsh-tool-skill`、`@deepseek-ai/dsh-system-prompt`）。这是拒绝客户端名称表的代价；想要更好标签的生产者必须在来源字段中记录该标签。
 - `ContextMessageNode` 增加了一个必填字段，因此每一处构造该节点的代码——包括测试 fixture——都必须提供它。
 - 即使 agent loop 现在把已经接纳的 steering 记录为 `user/message`，`SteeringMessageNode` 仍是独立的呈现节点；它的身份来自持久 inbox 历史，而不是独立消息事件。
 - 在某个宿主挂载 `dsh-session-reference` 之前，`recall` 分支在已发布的 Web 叶子中没有生产者，只能通过别处写入的日志抵达。
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 65d14e9aa4..e407eccd64 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 618c11b925208d09a62d10101656e3358e327ddb
-2026-08-05-context-form-vocabulary.zh.md: 66278b261f23601461c96f08e87ea58766b2bfc2
+2026-08-05-context-form-vocabulary.md: 7750523b89ebdda125a7bae8a853ab28a20eeb3f
+2026-08-05-context-form-vocabulary.zh.md: 8a6ced60b254ddf5e9075d199be98b3fbe442e2b
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 618c11b925..7750523b89 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-05-context-form-vocabulary.zh.md)
 
 ## Problem
 
-Every logged non-user `user/message` rendered through one body: the whole message serialized as inline JSON. A reader opening a row met `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`, where the escaping had collapsed the only thing worth reading — the model-facing prose — into a single line, and the provenance sat inside the same blob.
+Every logged non-user `user/message` rendered through one body: the whole message serialized as inline JSON. A reader opening a row met `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`, where the escaping had collapsed the only thing worth reading — the model-facing prose — into a single line, and the producer fields sat inside the same blob.
 
 Naming the producer in the header (the [source and steer marks decision](2026-08-04-web-context-source-and-steer-marks.md)) fixed *who added this*. It could not fix *what kind of thing was added*, because nothing in the log said so. Injected context is not one shape: a reconciled `AGENTS.md`, a catalog of available skills, a runtime policy snapshot, and a subagent's report are as different from each other as a terminal card is from a diff card, yet all four presented as the same wall of escaped JSON.
 
@@ -16,7 +16,7 @@ The tool surface already solved this shape. `ToolCallView` has three cards, not
 
 `MessageSource` gains an optional producer-declared `form: ContextForm` — a small tagged vocabulary of information *shapes*, independent of `kind`:
 
-- `kind` answers **who produced this** and remains pure provenance.
+- `kind` answers **who produced this** and carries no presentation choice.
 - `form` answers **what shape of information it is**. Several producers may share one form, and one producer may emit more than one over a session.
 
 The vocabulary is semantic, never visual. A value states that the content is a file's instructions or a catalog of available items; colors, icons, ordering, and collapse defaults are the consumer's business and must not enter the union. It grows one value at a time, as producers gain the structured fields their form needs. This release declares two:
@@ -41,7 +41,7 @@ Both readers are **all-or-nothing**: one unreadable entry disqualifies the recor
 
 The producer side validates the same durable data with the same posture. `catalogHistory` reads `source.entries` out of `agent.session.events`, which on resume or fork is a JSONL/SQLite seed whose validation only guarantees a source object with a non-empty `kind` — no per-kind field is checked. An unreadable catalog is therefore skipped as "not this plugin's record", the posture the replaced content digest had; throwing there would fail every later step of that session at the latest, least diagnosable point.
 
-Everything else — including a form this UI version does not present, a form absent from the source, and a `catalog` whose entries are unusable — renders the **opaque** body: the model-facing text with its real line breaks, then the remaining provenance as fields. Opaque is the documented default, not a leftover bin. A resumed, forked, or foreign log must render whether or not its producer is mounted here, which is also why the classification lives in the durable source rather than in a client-side table keyed by producer.
+Everything else — including a form this UI version does not present, a form absent from the source, and a `catalog` whose entries are unusable — renders the **opaque** body: the model-facing text with its real line breaks, then the remaining source data as fields. Opaque is the documented default; the contract assigns these unsupported cases to it. A resumed, forked, or foreign log must render whether or not its producer is mounted here, which is also why the classification lives in the durable source rather than in a client-side table keyed by producer.
 
 ## Why not a presenter registry
 
@@ -51,7 +51,7 @@ The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure fu
 
 **Map source kinds to renderers in the client.** Cheapest to write and requires no format change, but it puts producer knowledge back in the client: every new kind then needs a client release to render as anything but opaque, and a foreign log cannot be classified at all. It also reintroduces exactly the coupling the [source and steer marks decision](2026-08-04-web-context-source-and-steer-marks.md) removed for labels.
 
-**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. It breaks on the shared shapes: three producers emit runtime snapshots today, and folding them into one kind would erase their provenance. Two axes keep provenance exact while letting presentations be shared.
+**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. It breaks on the shared shapes: three producers emit runtime snapshots today, and folding them into one kind would erase which producer supplied each message. Two axes keep the producer exact while letting presentations be shared.
 
 **Let the client parse the model-facing prose.** The entries and file sections are visibly structured in the text. Parsing them couples the presentation to prompt wording, so every reword silently breaks a card — the same reason catalog identity moved off the text.
 
@@ -60,14 +60,14 @@ The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure fu
 ## Testing
 
 - `packages/client/runtime` pins the form projection, including the unknown, empty, wrongly-typed, and absent values that must degrade to opaque.
-- `packages/client/ui-conversation` pins each body: the opaque body's preserved line breaks and provenance fields, the instructions body's file list and verbatim framing, the catalog body's entry list, and a catalog with unusable entries falling back to opaque.
+- `packages/client/ui-conversation` pins each body: the opaque body's preserved line breaks and source fields, the instructions body's file list and verbatim framing, the catalog body's entry list, and a catalog with unusable entries falling back to opaque.
 - `packages/skill/tool-skill` pins the new source on first publication and replacement, republish behavior driven by the durable entries, and a malformed durable catalog leaving step observation intact.
 - The keyless assembled-Web seeded-history scenario expands a real `instructions` context in Chromium and asserts its file list, verbatim framing, and the unchanged disclosure geometry. `catalog` has no assembled coverage: the hermetic scaffold publishes no skills, so no catalog reaches a browser scenario.
 
 ## Consequences
 
 - A reader can tell what was added without expanding, and reading it no longer means reading escaped JSON.
-- The durable `MessageSource` now carries a semantic classification beside provenance. The boundary is load-bearing: facts and shape only, never presentation. A producer that wants a better card records better facts.
+- The durable `MessageSource` now records content shape beside the producer kind and its fields. The boundary is load-bearing: facts and shape only, never presentation. A producer that wants a better card records better facts.
 - Catalog identity no longer depends on the model-facing prose, deleting the text-slicing path that could mistake a reworded catalog for a changed one.
 - Every shipped producer except the two hook bridges now declares a form. The bridges stay opaque by design: their content is whatever an external program printed, so no shape can be promised for it. Unknown kinds and unreadable records land there too.
 - `ContextFormed` is discriminated by `form`, so a producer cannot declare a shape without the facts that shape is presented from — a `notice` without its summary, or a `snapshot` without its sections, fails to compile.
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 66278b261f..8a6ced60b2 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-每一条已记录的非用户 `user/message` 都通过同一个内容区渲染：把整条消息序列化成内联 JSON。读者展开一行，看到的是 `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`——转义把唯一值得读的东西（面向模型的散文）压成了一行，而来源信息又和它挤在同一坨里。
+每一条已记录的非用户 `user/message` 都通过同一个内容区渲染：把整条消息序列化成内联 JSON。读者展开一行，看到的是 `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`——转义把唯一值得读的东西（面向模型的散文）压成了一行，生产者字段也放在同一个 JSON 对象中。
 
 在标题栏写出生产者（[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)）解决了「这是谁加的」。它解决不了「加进来的是什么东西」，因为日志里根本没有这句话。注入上下文不是一种形状：对账后的 `AGENTS.md`、可用 skill 的目录、运行时策略快照、子 agent 的汇报，彼此之间的差别不亚于终端卡片与 diff 卡片，然而这四者呈现出来是同一堵转义 JSON 的墙。
 
@@ -16,7 +16,7 @@ Status: implemented
 
 `MessageSource` 新增一个可选、由生产方声明的 `form: ContextForm`——一份关于信息**形状**的小型 tagged 词汇表，与 `kind` 相互独立：
 
-- `kind` 回答**由谁产生**，保持纯粹的溯源语义。
+- `kind` 回答**由谁产生**，不携带呈现选择。
 - `form` 回答**这是何种形态的信息**。多个生产方可以共用一种形态，一个生产方在一次会话中也可以发出多种。
 
 该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。本次声明两个：
@@ -41,7 +41,7 @@ Status: implemented
 
 生产方一侧对同一份持久数据采取同样的姿态。`catalogHistory` 从 `agent.session.events` 读 `source.entries`，而恢复或 fork 时它来自 JSONL／SQLite 种子，种子验证只保证来源是带非空 `kind` 的对象，不校验任何 kind 特有字段。因此不可读的目录被当作「不是本插件的记录」跳过——正是被替换掉的内容 digest 原有的姿态；在那里抛错会让该会话此后每一步都在最晚、最难定位的点失败。
 
-其余一切——包括本 UI 版本不呈现的形态、来源未声明形态、以及条目不可用的 `catalog`——一律渲染 **opaque** 内容区：按真实换行展示面向模型的文本，其后把剩余来源信息列成字段。opaque 是有文档的默认，不是兜底垃圾桶。恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处都必须渲染得出来——这同样是分类信息必须落在持久来源里、而不是落在客户端以生产方为键的表里的原因。
+其余一切——包括本 UI 版本不呈现的形态、来源未声明形态、以及条目不可用的 `catalog`——一律渲染 **opaque** 内容区：按真实换行展示面向模型的文本，其后把剩余来源数据列成字段。opaque 是文档规定的默认；约定要求这些不支持的情况使用它。恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处都必须渲染得出来——这同样是分类信息必须落在持久来源里、而不是落在客户端以生产方为键的表里的原因。
 
 ## 为什么不做 presenter 注册表
 
@@ -51,7 +51,7 @@ Status: implemented
 
 **在客户端把来源 kind 映射到渲染器。** 写起来最省，也不用改格式，但它把生产方知识放回了客户端：此后每新增一个 kind 都要客户端发版才能渲染成 opaque 以外的东西，而外部日志根本无法分类。它还会重新引入[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)刚为名称去掉的那种耦合。
 
-**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但它在共享形状上就崩了：今天有三个生产方发出运行时快照，把它们并成一个 kind 会抹掉各自的溯源。两根轴既保住溯源的精确，又让呈现可以共享。
+**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但它在共享形状上就崩了：今天有三个生产方发出运行时快照，把它们并成一个 kind 会删除每条消息中标明其生产方的 `source` 字段。两根轴会保留准确的生产方，同时让呈现方式可以共享。
 
 **让客户端解析面向模型的散文。** 条目与文件分节在文本里确实有可见结构。解析它们会把呈现耦合到 prompt 措辞上，于是每改一次文案就静默碎掉一张卡——这也正是目录身份从文本上迁走的原因。
 
@@ -67,7 +67,7 @@ Status: implemented
 ## Consequences
 
 - 读者不展开就能知道加进来的是什么，展开之后读到的也不再是转义 JSON。
-- 持久 `MessageSource` 现在在溯源之外还承载一个语义分类。这条边界是承重的：只放事实与形状，绝不放呈现。想要更好卡片的生产方应当记录更好的事实。
+- 持久 `MessageSource` 现在会在生产者 kind 及其字段之外记录内容形状。这条边界是承重的：只放事实与形状，绝不放呈现。想要更好卡片的生产方应当记录更好的事实。
 - 目录身份不再依赖面向模型的散文，删掉了那条可能把「改了措辞」误判为「改了内容」的文本切分路径。
 - 除两个 hook 桥接外，每个已发布的生产方现在都声明了形态。桥接按设计保持 opaque：其内容是外部程序打印出来的任意文本，无法承诺任何形状。未知 kind 与不可读记录同样落在这里。
 - `ContextFormed` 按 `form` 判别，因此生产方无法在缺少该形态所需事实的情况下声明它——没有 summary 的 `notice`、没有 sections 的 `snapshot`，都会编译失败。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 483a429f97..3ae0cff501 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
-2026-06-20-core-data-structures-catalog.zh.md: a1184cb25823c10949713271434628c3650678dd
+2026-06-20-core-data-structures-catalog.md: fd2b8ef8c7a43d9835cfbc39fc296465d7f5aba5
+2026-06-20-core-data-structures-catalog.zh.md: 6aafdd70384c89ce39113227d11db93f53107442
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 9a3f80df59..fd2b8ef8c7 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -35,7 +35,7 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 - Complete type declarations and their JSDoc are pasted verbatim into a dedicated ` ```ts type-equiv ` fence. A concise ` ```ts public-api ` fence carries the source-equivalent ambient projection for a class whose implementation bodies do not belong in the catalog. `doc-typecheck` recognizes both and skips them (the bare declarations are not standalone-compilable), and **excludes them from the opt-out ratio** — they are a separately-checked category, not unchecked sketches.
 - A new `scripts/verify-type-equiv.ts` extracts each block via the TypeScript parser and asserts that its declaration structure and every JSDoc comment match the declared symbol, ignoring only formatting whitespace and non-JSDoc comments. Ordinary blocks retain the complete declaration. A `public-api` projection retains a class's public fields, constructor, accessors, and methods with their original JSDoc while removing implementation bodies and private or protected members. This is chosen over a compiled `_Check` assertion because source names and documentation identity, not assignability, are the properties the catalog preserves.
-- Provenance lives in a central `scripts/type-equiv.manifest.json` (`{ doc, symbol, source }` entries), **not** in directive comments in the prose. The script enforces a **1:1 correspondence** between each primary type-equiv block and one manifest entry, so a block can never be silently unchecked and an entry can never rot. A paired `.zh.md` block reuses the unsuffixed sibling's entry only when the complete tracked fence sequence matches in order, kind, and byte-exact body; otherwise the gate checks it independently, finds no manifest entry, and fails.
+- Each type block's document, symbol, and source file are recorded in `scripts/type-equiv.manifest.json` (`{ doc, symbol, source }` entries), **not** in directive comments in the prose. The script enforces a **1:1 correspondence** between each primary type-equiv block and one manifest entry, so a block can never be silently unchecked and an entry can never rot. A paired `.zh.md` block reuses the unsuffixed sibling's entry only when the complete tracked fence sequence matches in order, kind, and byte-exact body; otherwise the gate checks it independently, finds no manifest entry, and fails.
 - Wired into `doc-sync`, so relevant documentation changes run it locally and CI runs it with the other documentation checks.
 
 ### Maintenance is the author's job, with a gate backstop
@@ -46,7 +46,7 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 - **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-seam structure won.
 - **A compiled `_Check` assignability assertion** instead of the source match — rejected because assignability does not preserve names or JSDoc: a renamed field with the same type or a changed contract comment would pass.
-- **Provenance as directive comments in the prose** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
+- **Put each type block's source in a directive comment** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
 
 ## Verification lesson
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index a1184cb258..6aafdd7038 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -35,7 +35,7 @@ Status: implemented
 
 - 完整的类型声明及其 JSDoc 会逐字粘贴到专用的 ` ```ts type-equiv ` 围栏中。简洁的 ` ```ts public-api ` 围栏承载类的源码等价环境声明投影，用于实现体不应进入目录的类。`doc-typecheck` 会识别并跳过这两种围栏（裸声明无法独立编译），并且**将它们排除在 opt-out 比例之外**——它们是单独受检的类别，而不是未经检查的草图。
 - 新增的 `scripts/verify-type-equiv.ts` 通过 TypeScript 解析器提取每个块，并断言其声明结构和每条 JSDoc 注释都与所声明的符号匹配，只忽略格式空白和非 JSDoc 注释。普通块保留完整声明。`public-api` 投影保留类的公共字段、构造函数、访问器和方法及其原始 JSDoc，同时移除实现体以及私有或受保护成员。之所以选择它而非编译式 `_Check` 断言，是因为目录所保留的是源码名称与文档一致性，而不是可赋值性。
-- 来源信息存放在集中的 `scripts/type-equiv.manifest.json`（`{ doc, symbol, source }` 条目）中，**而非**行文中的指令注释。脚本在每个主 type-equiv 块与一条 manifest（元数据清单）条目之间强制执行 **1:1 对应**，因此一个块永远不会被静默漏检，一条条目也永远不会腐烂。只有当配对 `.zh.md` 块的完整受跟踪围栏序列在顺序、类型和按字节精确的正文上均与无后缀兄弟文件匹配时，才会复用后者的条目；否则门禁会独立检查该块，发现没有 manifest 条目后失败。
+- 每个类型块的文档、symbol 和源文件都记录在集中的 `scripts/type-equiv.manifest.json`（`{ doc, symbol, source }` 条目）中，**而非**行文中的指令注释。脚本在每个主 type-equiv 块与一条 manifest（元数据清单）条目之间强制执行 **1:1 对应**，因此一个块永远不会被静默漏检，一条条目也永远不会腐烂。只有当配对 `.zh.md` 块的完整受跟踪围栏序列在顺序、类型和按字节精确的正文上均与无后缀兄弟文件匹配时，才会复用后者的条目；否则门禁会独立检查该块，发现没有 manifest 条目后失败。
 - 接入 `doc-sync`，因此相关文档变更会在本地运行它，CI 也会与其他文档检查一起运行它。
 
 ### 维护是作者的职责，门禁作为兜底
@@ -46,7 +46,7 @@ Status: implemented
 
 - **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与 seam 结构胜出。
 - **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或约定注释变化仍会通过。
-- **来源信息作为行文中的指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
+- **将每个类型块的源文件写进指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
 
 ## 验证教训
 
diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml
index 4dee769645..c39852515a 100644
--- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.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 .agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
-2026-07-27-worktree-local-lefthook.md: 75dfd47087356c34005ec4673e174e451a72c660
-2026-07-27-worktree-local-lefthook.zh.md: 42d4d89e375dfd7b28298d89e82c5e9e74908062
+2026-07-27-worktree-local-lefthook.md: 5a10c5d3769bbe5ad1fd0407982bb34c8763e2ae
+2026-07-27-worktree-local-lefthook.zh.md: e7e96f2317368621a348f4a851672bbec1b7e857
diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
index 75dfd47087..5a10c5d376 100644
--- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
+++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
@@ -12,7 +12,7 @@ Lefthook-generated hooks prefer an absolute binary path captured from the instal
 
 ## Decision
 
-Hook installation is worktree-scoped. With `CI=true` or `GITHUB_ACTIONS=true`, the installer returns before Git discovery or mutation because automated jobs do not consume contributor hooks. Otherwise, it requires Git 2.26 or newer for configuration-scope provenance, upgrades a format-0 repository to format 1, enables `extensions.worktreeConfig`, and assigns the current worktree an absolute `core.hooksPath` at `$GIT_DIR/dsh-hooks`.
+Hook installation is worktree-scoped. With `CI=true` or `GITHUB_ACTIONS=true`, the installer returns before Git discovery or mutation because automated jobs do not consume contributor hooks. Otherwise, it requires Git 2.26 or newer so `git config --show-scope` can report which scope supplied a value, upgrades a format-0 repository to format 1, enables `extensions.worktreeConfig`, and assigns the current worktree an absolute `core.hooksPath` at `$GIT_DIR/dsh-hooks`.
 
 Before upgrading format 0, the installer refuses direct common-config `extensions.*`; it also refuses direct `core.worktree` or `core.bare=true` and non-empty dormant worktree configs that enabling the extension would activate. The migration removes direct `core.bare=false` because false is Git's default. The common repository config and every existing `config.worktree` must be regular files. These checks disable include expansion because Git's repository-format parser also ignores included targets. A repository-scoped lock serializes migration and hook writes; its process ID, random token, file identity, and exact contents must still match at release. Dead or invalid locks require manual recovery rather than automatic breaking.
 
diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md
index 42d4d89e37..e7e96f2317 100644
--- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md
@@ -12,7 +12,7 @@ Lefthook 生成的钩子会优先使用安装时从对应 worktree 记录的绝
 
 ## 决策
 
-钩子安装以 worktree 为作用域。当 `CI=true` 或 `GITHUB_ACTIONS=true` 时，安装程序会在探测 Git 或做出任何变更之前返回，因为自动化任务不会使用贡献者钩子。否则，为了获取配置作用域的来源信息，安装程序要求 Git 2.26 或更高版本；它会将格式版本为 0 的仓库升级到格式版本 1，启用 `extensions.worktreeConfig`，并将当前 worktree 的 `core.hooksPath` 设为指向 `$GIT_DIR/dsh-hooks` 的绝对路径。
+钩子安装以 worktree 为作用域。当 `CI=true` 或 `GITHUB_ACTIONS=true` 时，安装程序会在探测 Git 或做出任何变更之前返回，因为自动化任务不会使用贡献者钩子。否则，安装程序要求 Git 2.26 或更高版本，使 `git config --show-scope` 可以报告由哪个作用域提供配置值；它会将格式版本为 0 的仓库升级到格式版本 1，启用 `extensions.worktreeConfig`，并将当前 worktree 的 `core.hooksPath` 设为指向 `$GIT_DIR/dsh-hooks` 的绝对路径。
 
 升级格式 0 之前，安装程序会拒绝共用配置中直接设置的 `extensions.*`；它还会拒绝直接设置的 `core.worktree` 或 `core.bare=true`，以及启用扩展后将被激活的非空且尚未生效的 worktree 配置。迁移会移除直接设置的 `core.bare=false`，因为 false 是 Git 的默认值。共用仓库配置和每个已有的 `config.worktree` 都必须是常规文件。这些检查会禁用 include 展开，因为 Git 的仓库格式解析器也会忽略 include 目标。仓库级锁会串行化迁移和钩子写入；释放时，锁的进程 ID、随机令牌、文件身份和完整内容必须仍然匹配。所属进程已结束或内容无效的锁必须手动恢复，不会被自动破坏。
 
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 9cef49fa0a..ced42801aa 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.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 .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
-2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
-2026-08-06-in-repository-landlock-release.zh.md: ffebe45c537ee192ef855296b3334937485e2a89
+2026-08-06-in-repository-landlock-release.md: 1540cebbf5a3dffa20003c70ffcec426aeca104b
+2026-08-06-in-repository-landlock-release.zh.md: eaa576f0b39630eb07286906c1f537a0498ad646
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
index 3ae9e9c3c5..1540cebbf5 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
@@ -8,7 +8,7 @@ English | [中文](2026-08-06-in-repository-landlock-release.zh.md)
 
 The `@deepseek-ai/node-addon-landlock-run` source already lives beside its DeepSeek Harness consumers under `native/landlock-run`, but it previously kept a separate pnpm workspace and lockfile and depended on a standalone repository for npm publication. Harness packages consumed a fixed registry version, so one pull request could change the launcher contract and its consumer without testing those changes together. The source repository's native workflow could rehearse the package, but it did not publish the artifact it tested.
 
-The mirror also duplicated release coordination: export the source, update another lockfile, run another release workflow, publish the native family, then return to this repository to bump registry dependencies. That split made source-to-binary provenance, rollback, and security-fix coordination harder without changing what npm users actually needed.
+The mirror also duplicated release coordination: export the source, update another lockfile, run another release workflow, publish the native family, then return to this repository to bump registry dependencies. That split made it harder to match each binary to its source commit, roll back releases, and coordinate security fixes without changing what npm users actually needed.
 
 The existing unscoped npm names are owned by the standalone publisher account rather than the `@deepseek-ai` organization. Moving only the workflow would therefore leave publication dependent on a personal credential outside the repository's release ownership.
 
@@ -37,7 +37,7 @@ Launcher protocol, TypeScript entry code, native source, harness consumption, an
 
 npm consumers install `@deepseek-ai/node-addon-landlock-run`; the old unscoped package names are not silently redirected. A supported Linux host downloads the scoped entry package and its matching architecture package; the other architecture package is skipped. An unsupported host receives no platform binary and follows the existing deterministic fail-closed probe path.
 
-The implementation touches more files than a dependency-line edit because the repository must also own workspace constraints, TypeScript build order, cleanup, CI triggers, release tags, lockfile generation, packed-install provenance, release documentation, and generated notices. The behavioral boundary stays narrow: it changes only the Landlock package family and its three direct workspace consumers, not the version or publication state of other DeepSeek Harness packages.
+The implementation touches more files than a dependency-line edit because the repository must also own workspace constraints, TypeScript build order, cleanup, CI triggers, release tags, lockfile generation, comparison of installed binaries with workspace builds, release documentation, and generated notices. The behavioral boundary stays narrow: it changes only the Landlock package family and its three direct workspace consumers, not the version or publication state of other DeepSeek Harness packages.
 
 The first scoped release must use an `@deepseek-ai` organization token through the `npm-publish` environment's `NPM_TOKEN`, because npm cannot configure trusted publishing until a package exists. After bootstrap, all three packages must authorize this repository's release workflow before the fallback token can be removed. npm still publishes packages sequentially and offers no cross-package transaction, so a failed publish can leave a partial version. Because npm rejects an already-published name and version, an operator must inspect the registry and publish only the missing tarballs rather than rerunning the workflow unchanged. Linux x64 and arm64 runners remain the authoritative binary and real-kernel checks; a macOS checkout can verify the entry package and unsupported-platform behavior but cannot replace those jobs.
 
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index ffebe45c53..eaa576f0b3 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器约定及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
-发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
+发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却让每个二进制更难对应到其源提交，也让发布回滚和安全修复协调更困难。
 
 现有的非 scoped npm 包名归独立发布账号所有，而不属于 `@deepseek-ai` 组织。因此，仅迁移工作流仍会让发布依赖仓库发布归属之外的个人凭证。
 
@@ -37,7 +37,7 @@ Status: implemented
 
 npm 消费方改为安装 `@deepseek-ai/node-addon-landlock-run`；原先的非 scoped 包名不会被静默重定向。受支持的 Linux 主机会下载 scoped 入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
 
-实现涉及的文件比只修改一行依赖更多，因为仓库还必须负责 workspace 约束、TypeScript 构建顺序、清理、CI 触发条件、发布 tag、锁文件生成、打包安装来源证明、发布文档和生成的第三方声明。行为边界仍然很窄：此次改动只影响 Landlock 包家族及其 3 个直接 workspace 消费方，不改变其他 DeepSeek Harness 包的版本或发布状态。
+实现涉及的文件比只修改一行依赖更多，因为仓库还必须负责 workspace 约束、TypeScript 构建顺序、清理、CI 触发条件、发布 tag、锁文件生成、将已安装二进制与 workspace 构建进行比较、发布文档和生成的第三方声明。行为边界仍然很窄：此次改动只影响 Landlock 包家族及其 3 个直接 workspace 消费方，不改变其他 DeepSeek Harness 包的版本或发布状态。
 
 第一次发布 scoped 包时，必须通过 `npm-publish` 环境的 `NPM_TOKEN` 使用 `@deepseek-ai` 组织 token，因为 npm 只有在包已经存在后才能配置 trusted publishing。完成 bootstrap 后，必须让 3 个包都授权本仓库的发布工作流，才能移除后备 token。npm 仍会按顺序发布各个包，且不提供跨包事务，因此发布失败可能留下只完成了一部分的版本。由于 npm 会拒绝已经发布的同名同版本包，操作人员必须检查注册表并只发布缺失的 tarball，而不能原样重新运行工作流。Linux x64 和 arm64 runner 仍提供权威的二进制构建与真实内核检查；macOS checkout 可以验证入口包和不受支持平台上的行为，但不能取代这些作业。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index 21006b51db..b1246cc82e 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.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 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
-2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
-2026-08-08-browser-gif-evidence-chain.zh.md: 8aafc842e55775bade8885a792ce7b92dfc8df4e
+2026-08-08-browser-gif-evidence-chain.md: b1ee54aa21949c50d69be3384a35547b752e6858
+2026-08-08-browser-gif-evidence-chain.zh.md: 43fa0139b198c91363ccf30327a62c0b894557a0
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
index 93dfad76b3..b1ee54aa21 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
@@ -8,15 +8,15 @@ English | [中文](2026-08-08-browser-gif-evidence-chain.zh.md)
 
 A browser-demo storyboard can contain individually truthful screenshots without proving one truthful execution. Reusing global application state can admit old settings or sessions, capture automation can accidentally combine frames from separate model runs, and a chat transcript can show a successful fallback without exposing the tool rejection that caused it. Fuzzy accessible-name matching can also accept prompt echoes or descendant text instead of the intended result.
 
-Headless production recording has two further boundaries. A product default may open a native operating-system surface that automation cannot drive, while replacing that surface with a mock or test hook would change the provenance. After publication, a successful git push does not prove that a private-repository GIF is fetchable or that GitHub recognizes the pull-request Markdown as an image.
+Headless production recording has two further boundaries. A product default may open a native operating-system surface that automation cannot drive, while replacing that surface with a mock or test hook would mean the GIF no longer shows the production path. After publication, a successful git push does not prove that a private-repository GIF is fetchable or that GitHub recognizes the pull-request Markdown as an image.
 
 ## Decision
 
-The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Before building, it requires a clean worktree and records that commit SHA. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, session, and isolated browser state, and every published frame comes from the same server and model-backed scenario run. When a fresh browser context is unavailable, the exact origin's cookies and site storage are cleared before navigation. Existing user browser state is used only when requested or required, is declared in the provenance, and does not substantiate fresh client state. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
+The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Before building, it requires a clean worktree and records that commit SHA. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, session, and isolated browser state, and every published frame comes from the same server and model-backed scenario run. When a fresh browser context is unavailable, the exact origin's cookies and site storage are cleared before navigation. Existing user browser state is used only when requested or required, is stated next to the GIF, and does not substantiate fresh client state. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
 
 Browser automation waits for unique, exact semantic states. When the claim concerns a tool call, rejection, or recovery, the storyboard includes a detail or trajectory frame that identifies the tool, shows its status or stable error code, and shows the downstream result. The final encoded GIF remains the verification subject; when a viewer cannot animate it, representative frames are decoded from that GIF instead of treating source screenshots as equivalent evidence.
 
-The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated in the provenance. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
+The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated next to the GIF. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
 
 Publication verifies the boundary again. The assets branch contains media only, the staged and published bytes match the verified artifact, and a private-repository asset is checked through authenticated API or raw requests for its path, byte size, checksum, response status, and media type. This proves the repository-member review path only; the [documentation-site image decision](2026-08-06-doc-site-carries-its-images.md) owns why a public site cannot depend on a private raw URL. Immediately before the pull-request body changes, the live head must still equal the recorded head. After the edit, the live head is checked again and must remain at that recorded value; GitHub's Markdown renderer separately must produce the expected image.
 
@@ -34,4 +34,4 @@ Publication verifies the boundary again. The assets branch contains media only,
 
 GUI evidence now establishes one causal execution rather than a collage of plausible states, and reviewers can inspect both a structured tool failure and the completed result. Publication detects stale pull-request heads, corrupted or misplaced media, and invalid image Markdown before the body is treated as finished.
 
-The workflow spends additional scratch state, may repeat a real model round after a capture failure, and usually adds a detail frame plus authenticated publication checks. Headless recordings can use fewer production backends than an interactive desktop, and every such selection remains part of the stated provenance.
+The workflow spends additional scratch state, may repeat a real model round after a capture failure, and usually adds a detail frame plus authenticated publication checks. Headless recordings can use fewer production backends than an interactive desktop, and every selected backend is stated next to the GIF.
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index 8aafc842e5..43fa0139b1 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -8,15 +8,15 @@ Status: implemented
 
 浏览器演示的分镜可以由每张都真实的截图组成，却无法证明这些截图来自同一次真实执行。复用应用全局状态可能引入旧设置或旧会话；录制自动化可能误将不同模型运行的画面合并；聊天 transcript（文本记录）可能显示降级处理成功，却没有揭示触发降级的工具拒绝。按无障碍名称进行模糊匹配，还可能误把提示词回显或后代文本当成预期结果。
 
-无头模式下的生产环境录制还有两道边界。产品默认配置可能打开自动化无法操控的原生操作系统界面，而用 mock 或测试钩子替换该界面会改变证据来源。发布之后，git 推送成功也不能证明私有仓库中的 GIF 可以获取，或 GitHub 能将 PR（Pull Request）的 Markdown 识别为图片。
+无头模式下的生产环境录制还有两道边界。产品默认配置可能打开自动化无法操控的原生操作系统界面，而用 mock 或测试钩子替换该界面，就意味着 GIF 不再展示生产路径。发布之后，git 推送成功也不能证明私有仓库中的 GIF 可以获取，或 GitHub 能将 PR（Pull Request）的 Markdown 识别为图片。
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在 GIF 旁说明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 
-仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在证据来源说明中注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
+仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在 GIF 旁注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
 
 发布环节会再次验证边界。资产分支只包含媒体文件，暂存和发布的字节必须与已验证产物一致；对于私有仓库中的资产，应通过经身份验证的 API 或原始内容请求，检查其路径、字节大小、校验和、响应状态和媒体类型。这只能证明仓库成员的评审访问路径；[文档站点图片决策](2026-08-06-doc-site-carries-its-images.md)解释了公共站点为何不能依赖私有的原始内容 URL。修改 PR 正文之前，必须再次确认在线 head 仍与录制时的 head 相同。编辑后还要再次检查在线 head，且它必须保持为该记录值；GitHub 的 Markdown 渲染器则须单独生成预期图片。
 
@@ -34,4 +34,4 @@ Status: implemented
 
 GUI 证据现在能证明一次具有因果关系的执行，而不是将若干可信状态拼成集合；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
 
-该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
+该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每个选中的后端都会写在 GIF 旁。
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
index 2e33d34157..295dcfd0bf 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.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 .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
-2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
-2026-08-08-unified-github-label-taxonomy.zh.md: 75333e3823d6e96ef41b1359a81d53f4bd872f87
+2026-08-08-unified-github-label-taxonomy.md: 44508b4f0e2dc4de97950b0738829c0b362cc506
+2026-08-08-unified-github-label-taxonomy.zh.md: b1e3629fd93dcbff6e253058b4c465dc9bb5fd63
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
index fddda6c990..44508b4f0e 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
@@ -45,7 +45,7 @@ The area set is intentionally extensible. When no existing description honestly
 
 ### Issues and migrations
 
-Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
+Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record how an Issue was created and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
 
 Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
 
@@ -69,4 +69,4 @@ Label migrations preserve meaning before removing aliases: add the canonical rep
 
 ## Consequences
 
-Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
+Reviewers and automation can query intent, semantic scope, how an Issue was created, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
index 75333e3823..b1e3629fd9 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
@@ -45,7 +45,7 @@ Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对
 
 ### Issue 与迁移
 
-Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
+Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 的创建方式，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
 
 迁移标签时，须先保留语义，再移除别名：先添加规范替代标签，核验可加标签对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
 
@@ -69,4 +69,4 @@ Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然
 
 ## 后果
 
-评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
+评审人和自动化流程可以分别查询意图、语义范围、Issue 的创建方式、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
new file mode 100644
index 0000000000..b18d088e03
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.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 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
+2026-08-09-concrete-prose-names-actors-and-recorded-facts.md: efb6e9bcc6f1c817bb0be07ccd31bafc4b2ac3fb
+2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md: 41b0ce82631536c53ea45d60c1405a8387885d0f
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
new file mode 100644
index 0000000000..efb6e9bcc6
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
@@ -0,0 +1,33 @@
+# Agent Note: Concrete prose names actors and recorded facts
+
+Status: implemented
+
+English | [中文](2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md)
+
+## Problem
+
+Repository prose used abstract category labels where readers needed different concrete facts. The same label could mean earlier event seqs cited by a replacement, the provider and model that produced a message, the caller that supplied context, the file that supplied a configuration row, or the CI job that built a binary. Readers had to inspect code before they could tell which fact the sentence promised.
+
+Replacing one broad label with another would preserve that ambiguity. Renaming types, fields, and protocol members during an editorial cleanup would instead change contracts that the wording problem did not require changing.
+
+## Decision
+
+Maintained prose names the exact actor, action, source, event, field, file, or process needed by the local contract. It states what was recorded and who or what recorded it. Writers apply a spoken-language check and replace words they would not use while explaining the same point to a colleague.
+
+The rule applies to Markdown, READMEs, active Agent Notes, JSDoc and comments, prompts, diagnostics, and user-visible strings. An audit judges each sentence separately; it does not replace a term across the repository with one preferred synonym. The edited sentence preserves actor, action, conditions, order, modality, exceptions, ownership, failure behavior, and consequences.
+
+Exact code identifiers, public APIs, durable fields, protocol members, type names, headings with external references, and filenames stay unchanged unless a coordinated contract rename is independently required. Surrounding prose explains their fields or behavior directly. Generated documents and catalogs update from their owning source.
+
+This decision complements the [documentation tiers and budgets](2026-07-04-doc-tiers-and-budgets.md) decision, which continues to own placement, document form, and word budgets.
+
+## Alternatives considered
+
+**Ban a fixed list of words.** Rejected because a word may be an exact identifier or the clearest term in another contract. Sentence-level review catches ambiguity without rejecting valid names.
+
+**Replace every abstract label with “source,” “origin,” or “metadata.”** Rejected because another broad label still leaves readers to infer whether the sentence means a file, caller, event seq, provider/model pair, commit, or build job.
+
+**Rename every matching identifier with the prose.** Rejected because editorial clarity does not justify unrelated API, protocol, durable-format, type, or file migrations. Those changes require their own consumer audit and decision.
+
+## Consequences
+
+Documentation and diagnostics may use a few more words, but each statement tells readers which value or process matters without requiring source inspection. Repository-wide prose audits require semantic classification and cannot use blind replacement. Bilingual counterparts preserve the same concrete fact, and generated copies are refreshed only after their owning source changes.
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
new file mode 100644
index 0000000000..41b0ce8263
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 具体表述说明执行者和记录的事实
+
+Status: implemented
+
+[English](2026-08-09-concrete-prose-names-actors-and-recorded-facts.md) | 中文
+
+## 问题
+
+仓库行文使用了抽象的类别名称，但读者需要知道的具体事实各不相同。同一个名称可能指替换操作引用的早期事件 seq、生成消息的提供方和模型、提供上下文的调用方、提供某行配置的文件，或构建某个二进制文件的 CI 任务。读者必须查看代码，才能知道句子承诺的是哪项事实。
+
+用另一个宽泛名称替换原名称，仍会保留这种歧义。在行文整理中重命名类型、字段和协议成员，反而会改变与行文问题无关的约定。
+
+## 决策
+
+仓库维护的行文直接写明当地约定需要的执行者、动作、来源、事件、字段、文件或进程。句子说明记录了什么，以及由谁或什么记录。写作者还要检查自己是否会在向同事解释同一个问题时使用这些词；如果不会，就替换它们。
+
+该规则适用于 Markdown、README、活跃 Agent Note、JSDoc 与注释、提示词、诊断信息和用户可见字符串。审查会分别判断每个句子，不会在整个仓库中用一个偏好的近义词统一替换某个术语。编辑后的句子保留执行者、动作、条件、顺序、情态、例外、归属、失败行为和后果。
+
+除非另一项独立需求明确要求协调重命名约定，否则确切的代码标识符、公开 API、持久字段、协议成员、类型名、带有外部引用的标题和文件名均保持不变。它们周围的行文直接说明其字段或行为。生成的文档和目录在维护它们的源文件修改后更新。
+
+该决策补充了[文档层级与字数预算](2026-07-04-doc-tiers-and-budgets.md)决策；后者继续规定内容位置、文档形式和字数预算。
+
+## 曾考虑的替代方案
+
+**禁止一份固定词表中的所有词。** 不予采纳：某个词可能是确切的标识符，也可能是另一项约定中最清楚的用词。逐句审查可以找出歧义，且不会拒绝有效名称。
+
+**将每个抽象名称都替换为“来源”、“起源”或“元数据”。** 不予采纳：另一个宽泛名称仍会让读者自行推测句子指的是文件、调用方、事件 seq、提供方／模型组合、commit 还是构建任务。
+
+**在修改行文时重命名所有匹配的标识符。** 不予采纳：让行文更清楚，不能作为进行无关 API、协议、持久格式、类型或文件迁移的理由。这些改动需要各自的消费方审查和决策。
+
+## 后果
+
+文档和诊断信息可能会多用几个词，但每条说明都会告诉读者哪个值或哪个执行过程有关，无需查看源码。全仓库行文审查必须根据句子的具体含义分类，不能盲目替换。双语对侧文件保留相同的具体事实，只有在维护这些副本的源文件更改后才会刷新它们。
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
index 4edba8fd79..a47ee48e1f 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.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 .agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
-2026-07-12-simplify-session-log-representation.md: a40f4013a97a9c940012dbb37d59beb2faf8fb22
-2026-07-12-simplify-session-log-representation.zh.md: c4393511e1a78edacf60bc54a764721ad50e4d9d
+2026-07-12-simplify-session-log-representation.md: 3efb531d3c0822d7444d1270eac4da2617c12447
+2026-07-12-simplify-session-log-representation.zh.md: 5e9b453fd9905bf858dc5cb0cc09bf5c558ea0e6
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
index a40f4013a9..3efb531d3c 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
@@ -12,7 +12,7 @@ The session log maintains two representations that cost more machinery than thei
 
 The request-header subsystem implements a custom system/tool delta codec and transmission-decision layer even though its contract says deltas are an encoding optimization, not a reconstructability requirement. Retaining the initial/resume full snapshot at each loop-instance boundary, then writing a canonical full `request/header` whenever that instance's assembled header changes, preserves replay while deleting `SystemDelta`, `ToolsDelta`, round-trip fallback, and the durable `request/header-delta` variant. Codec-only vocabulary disappears with the codec, not because its individual arms were invalid.
 
-The implementation retains append and replacement `sourceEventSeqs`, crash-repair provenance, and all `SessionStartSource` variants because those fields have an audit/interception role that zero current readers does not overturn.
+The implementation retains append and replacement `sourceEventSeqs`, the `tool/call` seq cited by crash-repaired results, and all `SessionStartSource` variants because those fields have an audit/interception role that zero current readers does not overturn.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
index c4393511e1..5e9b453fd9 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其约定声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
 
-实现保留追加与替换操作的 `sourceEventSeqs`、崩溃修复的溯源信息，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
+实现保留追加与替换操作的 `sourceEventSeqs`、崩溃修复结果引用的 `tool/call` seq，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
index 91b9e6a0c0..a5b5587c90 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.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 .agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
-2026-08-03-omit-invariants-from-shipped-config.md: ff9a3b0ab2b4797ca4e96bea9e6b961b2e38501f
-2026-08-03-omit-invariants-from-shipped-config.zh.md: 526ce0756e69b36b6f54b46b23e1814322d6a1fd
+2026-08-03-omit-invariants-from-shipped-config.md: a691a0949806a752203a41bd6c66a50e97d8f1d7
+2026-08-03-omit-invariants-from-shipped-config.zh.md: cb2b04de6f4634e9107052c6855cba532b3030ba
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
index ff9a3b0ab2..a691a09498 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
@@ -12,7 +12,7 @@ English | [中文](2026-08-03-omit-invariants-from-shipped-config.zh.md)
 
 The shipped `dsh` configuration trees under `apps/cli/config/` mount neither `@deepseek-ai/dsh-invariants` nor any package-owned `./invariant` companion. The CLI package therefore carries no direct dependency on the invariant service.
 
-Invariant support remains available for focused tests, example bundles, generated SDK compositions, and custom deployments that opt into diagnostics explicitly. Session validation, snapshotting, freezing, and provenance remain always on and do not depend on the optional service, as defined by the [source-owned immutability decision](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
+Invariant support remains available for focused tests, example bundles, generated SDK compositions, and custom deployments that opt into diagnostics explicitly. Session validation, snapshotting, freezing, and cited source-event validation remain always on and do not depend on the optional service, as defined by the [source-owned immutability decision](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
 
 The built CLI config-dump test checks both shipped surfaces and rejects either the service entry or any `@deepseek-ai/dsh-*/invariant` entry.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
index 526ce0756e..cb2b04de6f 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `apps/cli/config/` 下交付的 `dsh` 配置树既不挂载 `@deepseek-ai/dsh-invariants`，也不挂载任何包拥有的 `./invariant` 伴随插件。因此，CLI 包不再直接依赖不变式服务。
 
-不变式支持仍可供聚焦测试、示例组合包、生成的 SDK 组合，以及显式选择诊断的自定义部署使用。会话验证、快照、冻结和 provenance 始终启用，且不依赖可选服务，具体由[源端拥有的不可变性决策](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md)规定。
+不变式支持仍可供聚焦测试、示例组合包、生成的 SDK 组合，以及显式选择诊断的自定义部署使用。会话验证、快照、冻结和来源事件引用验证始终启用，且不依赖可选服务，具体由[源端拥有的不可变性决策](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md)规定。
 
 构建后 CLI 的配置转储测试会检查两个交付的 surface，并拒绝服务条目或任何 `@deepseek-ai/dsh-*/invariant` 条目。
 
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index ad963d6e81..f8d4a07f6c 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.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 .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: ed5491e642ea7ac99fd9f4ba071a61e655f968d3
-2026-07-06-recallable-compaction.zh.md: dabc606d0056e91f9ac473de6f166083bcee25e8
+2026-07-06-recallable-compaction.md: 6f7baedeaae0038b7f5106cd5fc4e23bdfbbd8dd
+2026-07-06-recallable-compaction.zh.md: cbf8b4a3843ca35647cc569255dfe9d26b45b988
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index ed5491e642..6f7baedeaa 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-06-recallable-compaction.zh.md)
 
 ## Problem
 
-Compaction is a one-way door. The summary the model sees carries no reference to what it shadows — the `shadowedRange` provenance lives only on the log-only `compact/summary` event — and no tool lets the model read a shadowed span back. Whatever the summarizer drops is gone from the model's reachable world, even though the append-only log holds every byte. Repeated compaction compounds this: the head checkpoint is rewritten every pass, so the request prefix takes a full prompt-cache miss each time, and earlier summaries are re-summarized generation after generation.
+Compaction is irreversible from the model's current context. The summary the model sees carries no reference to what it shadows — `shadowedRange` lives only on the log-only `compact/summary` event — and no tool lets the model read a shadowed span back. Whatever the summarizer drops is unavailable to the model, even though the append-only log holds every byte. Repeated compaction compounds this: the head checkpoint is rewritten every pass, so the request prefix takes a full prompt-cache miss each time, and earlier summaries are re-summarized generation after generation.
 
 The root cause is one artifact playing two conflicting roles. An **index** wants to be frozen, chronological, and cheap; the model's **working memory** wants a global view, re-prioritization, and mutability. A single summary can be neither well.
 
@@ -22,7 +22,7 @@ Newly stale history splits into chunks by deterministic policy: accumulate towar
 
 - two or three lines of what happened;
 - a keyword line of low-frequency literal anchors — exact error strings, values, config keys — grouped by kind;
-- a code-composed footer: `[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`. Pointers are assembled from provenance, never model-authored.
+- a code-composed footer: `[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`. Code assembles these pointers from the `compact/summary` seq and `shadowedRange`; the model never writes them.
 
 A committed stub is never rewritten and never re-enters a later compaction region. A stub call's input is layered: the fixed preamble and the byte-identical pass-start state checkpoint (the shared prefix across all calls in the phase), then the keyword lines of all previously committed stubs — so a new entry indexes what is distinctive to its chunk instead of repeating the directory — the one or two most recent committed stubs for chronological continuity, and the slice itself. Sibling stubs from the same pass are not inputs (the concurrent phase forbids it; turn-aligned boundaries carry local continuity instead), and the state checkpoint is background only, never material to summarize into the stub. A slice consisting of recalled content is stubbed by code alone — a pointer line, no LLM call. A failed stub call degrades the same way: its slice gets a code-only pointer stub and the pass continues, making the state rewrite the only hard LLM dependency in a pass.
 
@@ -46,7 +46,7 @@ A new package `@deepseek-ai/dsh-tool-recall` (consumer-only, over the `dsh-sessi
 - `history_read(checkpoint, offset?)` — renders the shadowed span of any checkpoint in the log, including superseded ones, as `User:`/`Assistant:`/`Tool result:` transcript, paginated by a configured budget with a continuation cursor.
 - `history_search(query, checkpoint?, limit?)` — case-insensitive literal scan over every shadowed span; returns snippets with checkpoint ids and coverage metadata (`scanned`/`matched`/`truncated`). The zero-match hint notes the scan is literal and points at direct `history_read` of a plausible checkpoint.
 
-Both read `exec.agent.session.events` (the tool-todo access pattern; non-agent callers rejected), render only surface-type message events, and return ordinary `tool/result`s — recalled bytes land at the context tail, logged, so reconstructability holds with no special casing. There is no new storage and no sidecar index: the session log is the archive, `compact/summary` provenance is the index metadata, and the tools are a read path over both. The tool schemas and the package's one system-prompt section are static strings; checkpoint ids reach the model only through footers. The transcript renderer moves from `compact-basic` into `dsh-session`, shared by summarizer and tools.
+Both read `exec.agent.session.events` (the tool-todo access pattern; non-agent callers rejected), render only surface-type message events, and return ordinary `tool/result`s — recalled bytes land at the context tail, logged, so reconstructability holds with no special casing. There is no new storage and no sidecar index: the session log stores the content, `compact/summary.shadowedRange` and `shadowedSeqs` identify what each checkpoint replaced, and the tools read both. The tool schemas and the package's one system-prompt section are static strings; checkpoint ids reach the model only through footers. The transcript renderer moves from `compact-basic` into `dsh-session`, shared by summarizer and tools.
 
 ### Cache and cost
 
@@ -94,7 +94,7 @@ Specified during review, deferred until observation calls for them:
 ## Acceptance criteria
 
 - Auto-compaction over a long session yields `[stubs…][state][tail]` after every completed pass; prior stubs stay byte-identical across passes; committed stubs never fall inside a later region; the superseded state checkpoint folds without a tombstone, renders labeled, and stays reachable and searchable through the two-hop chain.
-- Every checkpoint's surface text ends with the deterministic footer; footers round-trip through replay byte-identically; the state checkpoint's provenance records its wider input range.
+- Every checkpoint's surface text ends with the deterministic footer; footers round-trip through replay byte-identically; the state checkpoint's `shadowedRange` records its wider input range.
 - Nothing commits before all summaries exist and the guard passes on like-for-like accounting; a guard failure commits nothing and does not fail the turn; a mid-commit kill resumed at the next pre-step completes the pass with the state region committed unconditionally, merge base read from the log; a legacy head checkpoint is adopted as state-class.
 - `history_read` renders any logged checkpoint's span under budget with a working cursor; `history_search` covers every shadowed span with checkpoint-id snippets and coverage metadata, asserted in particular by finding content that exists only in a span shadowed by a superseded state checkpoint — the regression pin for trailing-slice reachability; both reject non-agent callers and never-existing ids or orphaned `compact/start` with typed errors; recalled content appears as ordinary `tool/result`s; request-reconstruction invariants pass over sessions with compaction plus recall; one keyless snapshot scenario covers compact-then-recall end to end; tool schemas and the prompt section are byte-identical across passes.
 - On the long-horizon bench suite: task success does not regress against `compact-basic` at equal budgets; a handoff-fidelity probe (restate K known decisions and constraints after a pass) scores no worse; recall usage frequency and hit usefulness are reported per run via the dsh bench report pipeline, alongside the stub-directory attention measurement and cache-hit telemetry.
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index dabc606d00..cbf8b4a384 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-压缩（compaction）是一扇单向门。模型看到的摘要没有指向被其遮蔽内容的引用，因为 `shadowedRange` 来源只存在于仅写入日志、模型不可见的 `compact/summary` 事件上，也没有工具能让模型重新读取被遮蔽的区段。即使仅追加日志仍保存每一个字节，摘要器丢弃的内容也会离开模型可触达的世界。重复压缩会进一步放大问题：每一轮都会重写头部检查点，因此请求前缀每次都会完全失去提示词缓存命中，而更早的摘要也会一代又一代地被重新摘要。
+压缩（compaction）对模型的当前上下文不可逆。模型看到的摘要没有指向被其遮蔽内容的引用，因为 `shadowedRange` 只存在于仅写入日志、模型不可见的 `compact/summary` 事件上，也没有工具能让模型重新读取被遮蔽的区段。即使仅追加日志仍保存每一个字节，摘要器丢弃的内容也对模型不可用。重复压缩会进一步加重这些结果：每一轮都会重写头部检查点，因此请求前缀每次都会完全失去提示词缓存命中，而更早的摘要也会在后续每一轮中重新生成摘要。
 
 根本原因是一个产物承担了两个互相冲突的角色。**索引** 需要冻结、按时间排序且成本低廉；模型的**工作记忆** 则需要全局视图、重新确定优先级并且可变。单一摘要无法同时胜任两者。
 
@@ -22,7 +22,7 @@ Status: proposed
 
 - 用两三行说明发生了什么；
 - 用一行关键词记录低频字面锚点，例如确切的错误字符串、值和配置键，并按类别分组；
-- 由代码组装页脚：`[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`。指针根据来源组装，绝不由模型编写。
+- 由代码组装页脚：`[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`。代码根据 `compact/summary` seq 和 `shadowedRange` 组装这些指针，模型绝不会编写它们。
 
 已经提交的存根永不重写，也绝不再次进入之后的压缩区域。存根调用采用分层输入：固定前导内容与逐字节相同的本轮开始状态检查点（该阶段所有调用共享的前缀）；随后是先前所有已提交存根的关键词行，使新条目索引其分片的独特内容，而不是重复整个目录；再加最近一两个已提交存根以维持时间连续性；最后是切片本身。同一轮中的同级存根不作为输入，因为并发阶段禁止这种依赖，而与轮次对齐的边界已经维持局部连续性。状态检查点只作为背景，绝不能成为存根需要总结的材料。完全由回溯内容构成的切片只通过代码生成存根，即只写一行指针，不调用 LLM（大语言模型）。存根调用失败时采用相同降级方式：其切片获得一个仅由代码生成的指针存根，本轮继续执行，使状态重写成为一轮中唯一的强制 LLM 依赖。
 
@@ -46,7 +46,7 @@ Status: proposed
 - `history_read(checkpoint, offset?)`：把日志中任意检查点（包括已被取代的检查点）遮蔽的区段渲染为 `User:`／`Assistant:`／`Tool result:` transcript（文本记录），并按配置预算分页，提供续传游标。
 - `history_search(query, checkpoint?, limit?)`：对每个被遮蔽区段进行不区分大小写的字面量扫描；返回带检查点 id 的片段与覆盖元数据（`scanned`／`matched`／`truncated`）。零匹配提示会说明扫描按字面量执行，并建议对可能的检查点直接使用 `history_read`。
 
-两个工具都读取 `exec.agent.session.events`（沿用 tool-todo 访问模式；拒绝非 agent（智能体）调用方），只渲染表面类型的消息事件，并返回普通 `tool/result`：回溯字节会进入上下文尾部并记录到日志，因此无需特殊处理即可满足可重建性。系统不增加新存储或伴随索引：会话日志是归档，`compact/summary` 来源是索引元数据，而这些工具是两者之上的读取路径。工具 schema 与该包唯一的系统提示词章节都是静态字符串；检查点 id 只会通过页脚抵达模型。transcript 渲染器从 `compact-basic` 移入 `dsh-session`，供摘要器与工具共享。
+两个工具都读取 `exec.agent.session.events`（沿用 tool-todo 访问模式；拒绝非 agent（智能体）调用方），只渲染表面类型的消息事件，并返回普通 `tool/result`：回溯字节会进入上下文尾部并记录到日志，因此无需特殊处理即可满足可重建性。系统不增加新存储或伴随索引：会话日志存储内容，`compact/summary.shadowedRange` 和 `shadowedSeqs` 指明每个检查点替换了什么，这些工具读取两者。工具 schema 与该包唯一的系统提示词章节都是静态字符串；检查点 id 只会通过页脚抵达模型。transcript 渲染器从 `compact-basic` 移入 `dsh-session`，供摘要器与工具共享。
 
 ### 缓存与成本
 
@@ -94,7 +94,7 @@ Status: proposed
 ## 验收标准
 
 - 长会话自动压缩后，每一轮完成时都会得到 `[stubs…][state][tail]`；先前存根在各轮之间保持逐字节相同；已提交存根绝不落入后续区域；被取代的状态检查点无需墓碑即可折入历史，渲染时带有标签，并可通过两跳链路触达和搜索。
-- 每个检查点的表面文本都以确定性页脚结束；页脚通过回放逐字节往返；状态检查点的来源记录其更宽的输入范围。
+- 每个检查点的表面文本都以确定性页脚结束；页脚通过回放逐字节往返；状态检查点的 `shadowedRange` 记录其更宽的输入范围。
 - 在全部摘要就绪且保护逻辑通过同类核算前，不提交任何内容；保护失败不会提交任何内容，也不会让轮次失败；提交中途被终止后，下一次 pre-step 会恢复处理，从日志读取合并基线，并无条件提交状态区域以完成本轮；旧版头部检查点会被视为状态类。
 - `history_read` 在预算内渲染任意已记录检查点的区段，并提供可用游标；`history_search` 覆盖每个被遮蔽区段，返回带检查点 id 的片段与覆盖元数据，测试尤其要能找到只存在于被已取代状态检查点遮蔽区段中的内容，这是锁定尾随切片可达性的回归用例；两个工具都会拒绝非 agent 调用方，并对从未存在的 id 或遗留 `compact/start` 返回类型化错误；回溯内容作为普通 `tool/result` 出现；请求重建不变量会在同时包含压缩与回溯的会话上通过；一项无密钥快照场景端到端覆盖先压缩再回溯；工具 schema 与提示词章节在各轮之间逐字节相同。
 - 在长时间跨度 bench 套件中：任务成功率在预算相同的条件下不低于 `compact-basic`；交接保真探针（在一轮后重新陈述 K 项已知决策和约束）的得分不降低；每次运行都通过 dsh bench 报告流水线汇报回溯使用频率和命中有效性，并同时报告存根目录注意力度量与缓存命中遥测。
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
index 6963b28121..af92c05200 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.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 .agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
-2026-07-08-interactive-side-sessions.md: dfd325babe215782c9c1cbec3fd9f874783af7ab
-2026-07-08-interactive-side-sessions.zh.md: a1441cfe12df933855c7b9fe08c5e09f9e6107d3
+2026-07-08-interactive-side-sessions.md: 228380ca2d3d7b2efeb37e713574e1863ce17f38
+2026-07-08-interactive-side-sessions.zh.md: f4e3bfdddff16fe687f2637b3626e7e1382eba61
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
index dfd325babe..228380ca2d 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-08-interactive-side-sessions.zh.md)
 
 ## Problem
 
-A user may want to explore a question from a live session without changing its main context. Existing primitives do not expose that product shape: [session-store fork](../../implemented/feature/2026-06-30-session-store-fork-api.md) creates an unattached session, while [fork subagents](../../implemented/feature/2026-06-21-subagent-capability-seam.md) are model-driven tasks whose transcript collapses into one tool result. Neither gives the user a separate conversation, and neither records a conclusion back into the parent with provenance.
+A user may want to explore a question from a live session without changing its main context. Existing primitives do not expose that product shape: [session-store fork](../../implemented/feature/2026-06-30-session-store-fork-api.md) creates an unattached session, while [fork subagents](../../implemented/feature/2026-06-21-subagent-capability-seam.md) are model-driven tasks whose transcript collapses into one tool result. Neither gives the user a separate conversation, and neither records a conclusion in the parent together with the side session that produced it.
 
 ## Proposal
 
@@ -23,7 +23,7 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 
 - **Use the subagent seam:** rejected because side sessions are user-driven, client-visible, and may outlive a parent turn; subagents are model-driven runs returning one tool result.
 - **Change the child system prompt:** rejected by default because any byte change invalidates the prefix cache from token zero. Deployments may still prefer that stronger separation.
-- **Add `sidechat/*` events:** deferred because a sourced `context/message` already provides durability, provenance, and replay. A dedicated event is justified only by a surface that needs distinct rendering.
+- **Add `sidechat/*` events:** deferred because a sourced `context/message` already records the content, producer, and replay input durably. A dedicated event is justified only by a surface that needs distinct rendering.
 - **Bind a protocol surface now:** rejected because current UIs are client-owned. Live presentation must eventually derive from the durable message so replay renders the same record.
 
 ## Acceptance criteria
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
index a1441cfe12..f4e3bfdddf 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-用户可能希望在不改变当前会话主上下文的前提下，探索一个来自活跃会话的问题。现有原语无法提供这种产品形态：[会话存储 fork](../../implemented/feature/2026-06-30-session-store-fork-api.md)创建的是一个无关联的会话，而 [fork subagent](../../implemented/feature/2026-06-21-subagent-capability-seam.md)是模型驱动的任务，其 transcript（文本记录）会折叠为一条工具结果。两者都不能给用户一个独立的对话，也都不能将结论带着出处信息记录回父会话。
+用户可能希望在不改变当前会话主上下文的前提下，探索一个来自活跃会话的问题。现有原语无法提供这种产品形态：[会话存储 fork](../../implemented/feature/2026-06-30-session-store-fork-api.md)创建的是一个无关联的会话，而 [fork subagent](../../implemented/feature/2026-06-21-subagent-capability-seam.md)是模型驱动的任务，其 transcript（文本记录）会折叠为一条工具结果。两者都不能给用户一个独立的对话，也都不能在父会话中同时记录结论和产生该结论的侧会话。
 
 ## 提案
 
@@ -23,7 +23,7 @@ Status: proposed
 
 - **使用 subagent seam：** 否决。侧会话是用户驱动的、客户端可见的，且可能存活超过父会话的一个轮次；subagent 是模型驱动的运行，返回一条工具结果。
 - **修改子会话的系统提示词：** 默认否决，因为任何字节变化都会从第零个 token 起使前缀缓存失效。部署方仍可选择这种更强的隔离方式。
-- **新增 `sidechat/*` 事件：** 延后。插件来源的 `context/message` 已提供持久性、出处与回放能力；只有当某个界面需要差异化渲染时，专用事件才有正当理由。
+- **新增 `sidechat/*` 事件：** 延后。已标注来源的 `context/message` 已经持久记录内容、生产方和回放输入；只有当某个界面需要差异化渲染时，专用事件才有正当理由。
 - **现在就绑定一个协议界面：** 否决。当前 UI 由客户端拥有。实时呈现最终必须从持久消息派生，以使回放渲染出相同的记录。
 
 ## 验收标准
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
index 5dd07029b3..cb2b5d41c9 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.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 .agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
-2026-07-13-human-review-skill-maintenance.md: 76391bd110b7a86b194a9340ffcf7cc4602d1d2e
-2026-07-13-human-review-skill-maintenance.zh.md: 8ebff759cf29fa7773e4b883f83c231f88e153d2
+2026-07-13-human-review-skill-maintenance.md: b741c8b595fcd36613cb246af483863d1e056697
+2026-07-13-human-review-skill-maintenance.zh.md: 1c00577fdb08c30b1fff794c08da20ec38891de1
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
index 76391bd110..b741c8b595 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
@@ -10,13 +10,13 @@ The `dsh-code-review` skill records failure modes that require reviewer judgment
 
 ## Proposal
 
-Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master`. The intended scheduler runs daily with a two-UTC-day overlap; manual runs accept another `--since` duration or repeated `--pr` arguments for an explicit set. The scan is idempotent against the current skill and stores no repository cursor. The only repository file changed by promotion is [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md); the draft PR carries a provenance summary so reviewers can audit the source feedback and adoption evidence without the private adapter logs.
+Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master`. The intended scheduler runs daily with a two-UTC-day overlap; manual runs accept another `--since` duration or repeated `--pr` arguments for an explicit set. The scan is idempotent against the current skill and stores no repository cursor. The only repository file changed by promotion is [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md); the draft PR lists the source feedback URLs or IDs and adoption evidence without exposing the private adapter logs.
 
 ```mermaid
 flowchart TD
   A["Maintainer or scheduler runs the tool on origin/master"] --> B["List PRs merged in the overlap window"]
   B --> C["Collect pre-merge User feedback and final PR evidence"]
-  C --> D["Two reviewers verify provenance and adoption"]
+  C --> D["Two reviewers verify the author and adoption"]
   D --> E{"Both confirm human-authored and adopted?"}
   E -- "No" --> F["Exclude or retain as unresolved"]
   E -- "Yes" --> G["Two reviewers classify against the current skill"]
@@ -38,7 +38,7 @@ Each feedback item carries a stable source ID and bounded change evidence. When
 
 ### Dual-reviewer classification and drafting
 
-Two independently configured reviewer adapters classify every eligible item by provenance (`human-authored`, `forwarded-automation`, or `unclear`) and adoption (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging. If either adapter returns no valid result for any nonempty batch in an operation, the run exits non-zero and emits a failure record instead of reporting “no candidate.”
+Two independently configured reviewer adapters classify who authored every eligible item (`human-authored`, `forwarded-automation`, or `unclear`) and whether the change adopted it (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging. If either adapter returns no valid result for any nonempty batch in an operation, the run exits non-zero and emits a failure record instead of reporting “no candidate.”
 
 The primary adapter drafts from structured agreed guidance, never raw review text. It remains tool-free and read-only by adapter-author contract: it returns complete candidate file content, which the tool validates before writing the sole target. Both adapters then review the same complete skill diff; blocking findings return to a bounded revision loop, and both must approve the same revision. The tool rejects staged changes and edits outside the target skill both before running the documentation and lint gates and again before reporting success, so a gate or concurrent process that adds another path cannot slip through. It restores its own write on failure using best-effort compare-and-swap so a concurrent maintainer edit is not overwritten. On success it saves a candidate bundle containing the source `origin/master` commit, source skill blob ID, reviewed diff, complete candidate, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; it never commits, pushes, opens, or merges a PR.
 
@@ -48,21 +48,21 @@ Each private executable receives a byte-bounded, versioned JSON request on stdin
 
 ### Promotion contract
 
-The promote helper starts from a clean checkout at refreshed `origin/master` and refuses to apply a candidate when the current skill blob differs from the bundle's recorded source blob. The operator then reruns the maintenance analysis or manually rebases the diff and repeats the candidate review; the helper never replaces a newer `SKILL.md` with stale complete-file output. After applying a current candidate, it opens a draft PR whose body lists the source feedback URLs or IDs, the landed commit range used as adoption evidence, the originating run, gate results, and any operator edits. Raw adapter prompts and responses remain private, but repository reviewers receive enough provenance to judge whether each proposed rule follows from adopted human feedback.
+The promote helper starts from a clean checkout at refreshed `origin/master` and refuses to apply a candidate when the current skill blob differs from the bundle's recorded source blob. The operator then reruns the maintenance analysis or manually rebases the diff and repeats the candidate review; the helper never replaces a newer `SKILL.md` with stale complete-file output. After applying a current candidate, it opens a draft PR whose body lists the source feedback URLs or IDs, the landed commit range used as adoption evidence, the originating run, gate results, and any operator edits. Raw adapter prompts and responses remain private, but repository reviewers receive those concrete inputs so they can judge whether each proposed rule follows from adopted human feedback.
 
 ### Where the mechanism lives
 
-The tool source, adapter binaries, provider credentials, and intended daily scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs any provenance benefit. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up Agent Note that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
+The tool source, adapter binaries, provider credentials, and intended daily scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs the benefit of committing the tool and its history. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up Agent Note that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
 
 ## Alternatives considered
 
-- **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed provenance. Retained option for a later handoff.
+- **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed source and review history. Retained option for a later handoff.
 - **Record every feedback-time PR head** — rejected: it improves causal isolation but requires a continuously running observer, durable event state, retries, and force-push reconciliation. Periodic maintenance uses reviewed-commit evidence where available and fails closed on broader whole-PR evidence.
 - **Persist a processed-PR cursor** — rejected: an overlapping time-window scan is cheap and naturally idempotent against the current skill, while cursor state creates recovery and missed-event problems.
 - **Run on every new comment** — rejected: review waves produce many related comments and lack the final artifact needed to judge adoption.
 - **Treat merge or thread resolution as adoption** — rejected: a PR can merge with rejected, superseded, or intentionally unresolved feedback.
 - **Create or merge repository changes automatically** — rejected: the tool first needs a track record of useful periodic output. The maintainer inspects and promotes the local diff through normal repository review.
-- **Learn from bot findings that were fixed** — rejected: the source contract is human review feedback. Actor type is filtered before analysis, and human accounts forwarding automated findings are excluded by provenance review.
+- **Learn from bot findings that were fixed** — rejected: the source contract is human review feedback. Author type is filtered before analysis, and human accounts forwarding automated findings are excluded by the author check.
 - **Use one reviewer as author and final judge** — rejected: independent verdicts expose unsupported generalization before it reaches the skill.
 
 ## Acceptance criteria
@@ -73,7 +73,7 @@ Promotion from `proposed/` to `implemented/` requires all of the following to be
 - Both reviewer adapters are independently configured (distinct providers or models) and complete an analyze / adopt / review pass without user intervention. **Observed on 2026-07-15:** distinct primary/secondary adapters completed adoption + analysis in ~8 minutes; batch fail-closed handled one adapter id-hallucination without aborting the run.
 - A scheduler triggers the tool without an interactive terminal, and a candidate diff (or a "no candidate" record) reaches the operator through a durable notification channel.
 - A controlled acquisition case advances the target branch with a feedback-matching change after the feedback baseline; the reviewer evidence excludes that target-only change while retaining a later PR-owned change.
-- The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the provenance summary defined above.
+- The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the source feedback IDs, adopted commit range, originating run, checks, and operator edits defined above.
 - At least one candidate diff produced by this workflow is inspected by the operator and promoted to `master` through a normal repository PR review. That PR is the evidence that the workflow can turn adopted feedback into shipped skill guidance.
 
 ## Risks
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
index 8ebff759cf..1c00577fdb 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
@@ -10,13 +10,13 @@ Status: proposed
 
 ## 提案
 
-在仓库外定期维护。一项保存在 skill 维护者机器上、而不提交到本仓库的私有工具，会针对刷新至 `origin/master` 的干净完整历史 checkout 运行。预期的调度器每天运行，并使用两天的 UTC 重叠窗口；手动运行可以通过另一个 `--since` 时长或重复的 `--pr` 参数指定显式集合。扫描相对于当前 skill 是幂等的，不存储仓库游标。推广时唯一会变更的仓库文件是 [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md)；draft PR（Pull Request）携带来源概述，因此评审人无需私有适配器日志，也能审计源反馈与采纳证据。
+在仓库外定期维护。一项保存在 skill 维护者机器上、而不提交到本仓库的私有工具，会针对刷新至 `origin/master` 的干净完整历史 checkout 运行。预期的调度器每天运行，并使用两天的 UTC 重叠窗口；手动运行可以通过另一个 `--since` 时长或重复的 `--pr` 参数指定显式集合。扫描相对于当前 skill 是幂等的，不存储仓库游标。推广时唯一会变更的仓库文件是 [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md)；draft PR（Pull Request）列出源反馈 URL 或 ID 和采纳证据，不会公开私有适配器日志。
 
 ```mermaid
 flowchart TD
   A["Maintainer or scheduler runs the tool on origin/master"] --> B["List PRs merged in the overlap window"]
   B --> C["Collect pre-merge User feedback and final PR evidence"]
-  C --> D["Two reviewers verify provenance and adoption"]
+  C --> D["Two reviewers verify the author and adoption"]
   D --> E{"Both confirm human-authored and adopted?"}
   E -- "No" --> F["Exclude or retain as unresolved"]
   E -- "Yes" --> G["Two reviewers classify against the current skill"]
@@ -38,7 +38,7 @@ flowchart TD
 
 ### 双评审人分类与起草
 
-两个独立配置的评审适配器，会从来源（`human-authored`、`forwarded-automation` 或 `unclear`）和采纳情况（`adopted`、`rejected` 或 `unclear`）两个维度，对每个符合条件的条目进行分类。只有两个适配器都判定为 `human-authored` 加 `adopted` 的条目才会继续。采纳集合随后会针对当前 skill 接受第二次独立分类：候选项、已经覆盖、实现专用或并非反馈。单个条目即可符合要求，不要求重复出现。意见分歧会得到一次有界的重新评估；如果仍未解决，则继续保留在运行产物中。单个批次的适配器输出如果未通过 schema 或 id 校验，系统会在批次层按不采纳处理：其中的每条反馈都标记为 unclear 并路由到 `excluded`，而不是中止整次运行；有问题的原始输出会保存在该次运行的私有产物中，供调试使用。如果任一适配器在某项操作的任何非空批次中都没有返回有效结果，运行会以非零状态退出并发出失败记录，而不会报告「没有候选项」。
+两个独立配置的评审适配器，会对每个符合条件的条目分类：谁编写了它（`human-authored`、`forwarded-automation` 或 `unclear`），以及变更是否采纳了它（`adopted`、`rejected` 或 `unclear`）。只有两个适配器都判定为 `human-authored` 加 `adopted` 的条目才会继续。采纳集合随后会针对当前 skill 接受第二次独立分类：候选项、已经覆盖、实现专用或并非反馈。单个条目即可符合要求，不要求重复出现。意见分歧会得到一次有界的重新评估；如果仍未解决，则继续保留在运行产物中。单个批次的适配器输出如果未通过 schema 或 id 校验，系统会在批次层按不采纳处理：其中的每条反馈都标记为 unclear 并路由到 `excluded`，而不是中止整次运行；有问题的原始输出会保存在该次运行的私有产物中，供调试使用。如果任一适配器在某项操作的任何非空批次中都没有返回有效结果，运行会以非零状态退出并发出失败记录，而不会报告「没有候选项」。
 
 主适配器只根据结构化的共同指引起草，绝不接收原始评审文本。根据适配器作者的约定，它保持无工具且只读：返回完整的候选文件内容，由工具校验后写入唯一目标。两个适配器随后评审同一份完整 skill diff；阻塞性问题会进入有界修订循环，而且两者必须批准同一版修订。工具会在运行文档和 lint 检查前，以及报告成功前，再次拒绝暂存改动和目标 skill 之外的编辑，因此检查或并发进程无法通过添加其他路径混入。失败时，工具使用尽力而为的比较并交换回滚自身写入，以免覆盖维护者的并发编辑。成功时，它保存一份候选资料包，其中包含源 `origin/master` commit、源 skill blob ID、已评审 diff、完整候选文件、源反馈 ID 与 URL、落地证据范围、适配器判定和检查结果；它绝不提交、推送、打开或合并 PR。
 
@@ -48,21 +48,21 @@ flowchart TD
 
 ### 推广约定
 
-推广辅助工具从刷新至 `origin/master` 的干净 checkout 开始；当前 skill blob 与资料包中记录的源 blob 不同时，它拒绝应用候选项。运维方随后重新运行维护分析，或手动把 diff 变基后重新评审候选项；辅助工具绝不会用陈旧的完整文件输出替换较新的 `SKILL.md`。应用仍然有效的候选项后，它会打开 draft PR，其正文列出源反馈 URL 或 ID、用作采纳证据的落地 commit 范围、来源运行、检查结果和任何运维方编辑。原始适配器提示词与响应保持私有，但仓库评审人会获得足够的来源信息，以判断每条提议规则是否确实来自已采纳的人类反馈。
+推广辅助工具从刷新至 `origin/master` 的干净 checkout 开始；当前 skill blob 与资料包中记录的源 blob 不同时，它拒绝应用候选项。运维方随后重新运行维护分析，或手动把 diff 变基后重新评审候选项；辅助工具绝不会用陈旧的完整文件输出替换较新的 `SKILL.md`。应用仍然有效的候选项后，它会打开 draft PR，其正文列出源反馈 URL 或 ID、用作采纳证据的落地 commit 范围、发起该候选项的运行、检查结果和任何运维方编辑。原始适配器提示词与响应保持私有，但仓库评审人会获得这些具体输入，从而判断每条提议规则是否确实来自已采纳的人类反馈。
 
 ### 机制所在位置
 
-工具源码、适配器二进制文件、提供方凭据和预期的每日调度器保存在维护者机器上，不会提交到本仓库。本文规定协议，参考实现属于私有基础设施。该机制只服务于由单个运维方维护的一项 skill，因此，持续通过仓库评审审查机制改动的成本高于来源可追溯性的收益。如果该机制将来移交给第二位维护者，移交工作需要一篇后续 Agent Note 来修订本决策；任何接手者都应从运维文档 [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) 入手。
+工具源码、适配器二进制文件、提供方凭据和预期的每日调度器保存在维护者机器上，不会提交到本仓库。本文规定协议，参考实现属于私有基础设施。该机制只服务于由单个运维方维护的一项 skill，因此，持续通过仓库评审审查机制改动的成本高于提交工具及其历史的收益。如果该机制将来移交给第二位维护者，移交工作需要一篇后续 Agent Note 来修订本决策；任何接手者都应从运维文档 [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) 入手。
 
 ## 考虑过的替代方案
 
-- **把工具放入本仓库。** 对单维护者作用域不予采纳：仓库维护开销（类型检查、lint、覆盖率与横切重构）会超过已提交来源信息的价值。未来移交时仍可重新考虑。
+- **把工具放入本仓库。** 对单维护者作用域不予采纳：仓库维护开销（类型检查、lint、覆盖率与横切重构）会超过已提交源码和评审历史的价值。未来移交时仍可重新考虑。
 - **记录每条反馈产生时的 PR head**：不予采纳，因为这需要持续运行的观察器、持久事件状态、重试和强制推送协调。定期维护会在可用时使用经过评审的 commit 证据，并在整 PR 证据范围过宽、无法确认时直接排除。
 - **持久化已处理 PR 游标**：不予采纳，因为带重叠的时间窗口扫描成本低廉，并且相对于当前 skill 天然幂等；游标状态反而带来恢复和漏事件问题。
 - **每次新评论都运行**：不予采纳，因为一轮评审会产生许多相关评论，并且缺少判断采纳情况所需的最终产物。
 - **把合并或讨论串解决视为采纳**：不予采纳，因为 PR 可能在反馈被拒绝、被取代或刻意不解决的情况下合并。
 - **自动创建或合并仓库改动**：不予采纳，因为工具首先需要通过有用的定期输出积累可信记录。维护者检查并通过普通仓库评审推广本地 diff。
-- **从已经修复的 bot 问题中学习**：不予采纳，因为来源约定限定为人类评审反馈。系统会在分析前按 actor 类型过滤，并通过来源评审排除转发自动化问题的人类账号。
+- **从已经修复的 bot 问题中学习**：不予采纳，因为来源约定限定为人类评审反馈。系统会在分析前按作者类型过滤，并通过作者检查排除转发自动化问题的人类账号。
 - **让同一个评审人既当作者又作最终裁决**：不予采纳，因为独立判定能在不受支持的概括进入 skill 之前暴露问题。
 
 ## 验收标准
@@ -73,7 +73,7 @@ flowchart TD
 - 两个评审适配器独立配置（不同的提供方或模型），无需用户干预即可完成 analyze／adopt／review 流程。**2026-07-15 已观察：** 不同的主／次适配器约用 8 分钟完成采纳与分析；一次适配器 id 幻觉由批次级保守失败机制处理，没有中止整次运行。
 - 调度器在没有交互式终端的情况下触发工具，并通过持久通知通道把候选 diff（或「没有候选项」记录）送达运维方。
 - 一个受控采集场景会在反馈基线之后，向目标分支加入与反馈匹配的变更；评审证据排除该目标分支专有变更，同时保留后续由 PR 自身加入的变更。
-- 源 skill 改变后，推广辅助工具会拒绝候选项；仍然有效的候选项会按照上文定义的来源概述打开 draft PR。
+- 源 skill 改变后，推广辅助工具会拒绝候选项；仍然有效的候选项会打开 draft PR，其中包含上文定义的源反馈 ID、已采纳 commit 范围、发起该候选项的运行、检查和运维方编辑。
 - 该工作流生成的至少一个候选 diff 会由运维方检查，并通过普通仓库 PR 评审推广到 `master`。该 PR 用以证明工作流能够把已采纳反馈转化为已交付的 skill 指引。
 
 ## 风险
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
index 7bea4132ff..07f441de52 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.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 .agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
-2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md: 236139f9198f178d44cdf0867cbad2377a127359
-2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: 650217e936aa65884e8fb4fed0358406c78e9931
+2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md: e995ec4e20f41cc4377131c0f6e8672e0588ccea
+2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: e2e8869f2b6f89559a4cc1403ec530ed45d4aaab
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
index 236139f919..e995ec4e20 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
@@ -17,16 +17,16 @@ When the Windows sandbox phase is picked up, evaluate wrapping landstrip's Windo
 - **Probe synthesis.** landstrip has no `--probe`; the chain's functional-probe contract would have to be synthesized from a trap run.
 - **Dialect mapping.** Denial and runner-failure stderr dialects, and fail-closed exit-code classification, need explicit mapping into the chain's vocabulary.
 - **License.** The binaries are LGPL-2.1-or-later; distribution review is required before it enters the shipped closure.
-- **Provenance.** The in-house launcher's value is byte-pinned native-CI provenance over a ~300-line reviewable C file; landstrip is a single-maintainer Rust binary set. For the *existing Linux rung* that trade is already settled — do not swap it ([sandbox note](../../implemented/feature/2026-07-06-sandbox.md) and the launcher's own migration away from a Rust dependency). For a rung we have not built, weighing third-party maintenance against a second in-house native repo is a genuinely open question.
+- **Source and build record.** Each in-house launcher binary is byte-pinned to a native CI build of a ~300-line reviewable C file; landstrip is a single-maintainer Rust binary set. For the *existing Linux rung* that trade is already settled — do not swap it ([sandbox note](../../implemented/feature/2026-07-06-sandbox.md) and the launcher's own migration away from a Rust dependency). For a rung we have not built, weighing third-party maintenance against a second in-house native repo is a genuinely open question.
 
 ## Alternatives considered
 
-- **Build the in-house AppContainer launcher as planned.** Still the default if the evaluation fails on license, provenance, or probe fit; the cost is owning a second native security launcher repo indefinitely.
-- **Swap the Linux Landlock rung to landstrip too.** Rejected outright: sandbox correctness is a security invariant, the current launcher's reviewability and provenance chain were chosen deliberately, and it already migrated away from a Rust dependency for exactly this reason.
+- **Build the in-house AppContainer launcher as planned.** Still the default if the evaluation fails on license, source/build auditability, or probe fit; the cost is owning a second native security launcher repo indefinitely.
+- **Swap the Linux Landlock rung to landstrip too.** Rejected outright: sandbox correctness is a security invariant, the current launcher has reviewable C source and binaries byte-pinned to native CI builds, and it already migrated away from a Rust dependency for exactly this reason.
 
 ## Acceptance criteria
 
-- Before any Windows-rung implementation starts, an evaluation records the probe, dialect, license, and provenance answers, and the go/no-go is added to the sandbox note's deferred-phases plan.
+- Before any Windows-rung implementation starts, an evaluation records the probe, dialect, license, source repository, release process, and binary build answers, and the go/no-go is added to the sandbox note's deferred-phases plan.
 
 ## Risks
 
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
index 650217e936..e2e8869f2b 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
@@ -17,16 +17,16 @@ Status: rejected — landstrip 未经实战检验（驳回时问世仅数天，
 - **探测合成。** landstrip 没有 `--probe`；链所要求的功能探测约定必须从一次 trap 运行中合成出来。
 - **方言映射。** 拒绝与运行器失败两类 stderr 方言，以及失败关闭的退出码分类，都需要显式映射到链的词汇中。
 - **许可证。** 其二进制文件采用 LGPL-2.1-or-later 许可；在进入随产品发布的依赖闭包之前需要先做分发审查。
-- **溯源。** 自研启动器的价值在于一个约 300 行、可完整评审，并由原生 CI 逐字节锁定来源的 C 文件；而 landstrip 是单一维护者手中的一组 Rust 二进制文件。对*既有的 Linux 层级*而言，这笔权衡早有定论——不要替换它（见[沙箱 Agent Note](../../implemented/feature/2026-07-06-sandbox.md)以及该启动器自身移除 Rust 依赖的迁移记录）。而对一个我们尚未构建的层级，在第三方维护与第二个自研原生仓库之间如何取舍，是一个真正悬而未决的问题。
+- **源码与构建记录。** 每个自研启动器二进制都逐字节锁定到一个约 300 行、可完整评审的 C 文件的原生 CI 构建；而 landstrip 是单一维护者手中的一组 Rust 二进制文件。对*既有的 Linux 层级*而言，这笔权衡早有定论——不要替换它（见[沙箱 Agent Note](../../implemented/feature/2026-07-06-sandbox.md)以及该启动器自身移除 Rust 依赖的迁移记录）。而对一个我们尚未构建的层级，在第三方维护与第二个自研原生仓库之间如何取舍，是一个真正悬而未决的问题。
 
 ## 曾考虑的替代方案
 
-- **按原计划构建自研 AppContainer 启动器。** 若评估在许可证、溯源或探测契合度上不通过，这仍是默认选项；代价是要长期维护第二个原生安全启动器仓库。
-- **把 Linux Landlock 层级也换成 landstrip。** 直接否决：沙箱正确性是安全不变量，当前启动器的可审阅性与溯源链是刻意选择的结果，而且它正是出于这一原因才迁移摆脱了 Rust 依赖。
+- **按原计划构建自研 AppContainer 启动器。** 若评估在许可证、源码／构建可审计性或探测契合度上不通过，这仍是默认选项；代价是要长期维护第二个原生安全启动器仓库。
+- **把 Linux Landlock 层级也换成 landstrip。** 直接否决：沙箱正确性是安全不变量，当前启动器有可审阅的 C 源码，其二进制逐字节锁定到原生 CI 构建，而且它正是出于这一原因才迁移摆脱了 Rust 依赖。
 
 ## 验收标准
 
-- 在任何 Windows 层级实现开始之前，先有一份评估记录下探测、方言、许可证与溯源问题的答案，并把「采用／不采用」（go/no-go）结论加入沙箱 Agent Note 的延后阶段计划。
+- 在任何 Windows 层级实现开始之前，先有一份评估记录下探测、方言、许可证、源代码仓库、发布流程和二进制构建问题的答案，并把「采用／不采用」（go/no-go）结论加入沙箱 Agent Note 的延后阶段计划。
 
 ## 风险
 
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
index 71171bbd04..2e98c0fdc7 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.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 .agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
-2026-07-19-fold-compaction-package-split.md: 47c9feb6bb0dd06fec0f002b7c1e930b288abe5e
-2026-07-19-fold-compaction-package-split.zh.md: ef2d1ee34783477f1b77f75d05b58d7679c6c4d4
+2026-07-19-fold-compaction-package-split.md: eeb0b5871ceacbbefc8bfa9f782b4bdd6735f20a
+2026-07-19-fold-compaction-package-split.zh.md: 1b7e456536254acd98944c601da12d97453803ba
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
index 47c9feb6bb..eeb0b5871c 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
@@ -29,7 +29,7 @@ Amend the implemented compaction decision and the [recallable-compaction proposa
 - `@deepseek-ai/dsh-compact-basic` and its workspace/package metadata are removed.
 - `@deepseek-ai/dsh-compact` owns the current configuration, plugin class, algorithm, types, events, and shared helpers.
 - Existing deployments can load the surviving package with equivalent configuration and model-visible behavior.
-- Automatic and manual compaction preserve cancellation, locking, token accounting, tool pairing, durable events, provenance, retry convergence, and transcript rendering.
+- Automatic and manual compaction preserve cancellation, locking, token accounting, tool pairing, durable events, cited source-event seqs, retry convergence, and transcript rendering.
 - Loader composition, unit, runaway-turn, cancellation, snapshot, and real-model compaction tests pass; generated catalogs and module graphs are current.
 
 ## Risks
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
index ef2d1ee347..1b7e456536 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
@@ -29,7 +29,7 @@ Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 
 - 删除 `@deepseek-ai/dsh-compact-basic` 及其工作区和包元数据。
 - `@deepseek-ai/dsh-compact` 拥有当前配置、插件类、算法、类型、事件和共享辅助方法。
 - 现有部署可以使用等效配置加载保留的包，模型可见行为等效。
-- 自动压缩和手动压缩保留取消、锁、token 用量、工具配对、持久事件、来源、重试收敛和 transcript 渲染行为。
+- 自动压缩和手动压缩保留取消、锁、token 用量、工具配对、持久事件、引用的来源事件 seq、重试收敛和 transcript 渲染行为。
 - loader 组合、单元、失控轮次、取消、快照和真实模型压缩测试全部通过；生成目录与模块图保持最新。
 
 ## 风险
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index af897a186b..ae1231acde 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.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 .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
-2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: cc56dd44938cfe6d4c4b0aff1c714d80b8d8f5b6
+2026-07-26-dependency-swaps-rejected-by-nih-audit.md: c3422a9c8b4d60b4795aed5108923ac3446b0a46
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: 9e21c89fcba0b05cfb5c00bef5261e834302bea1
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
index 538f6a41b4..c3422a9c8b 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
@@ -67,7 +67,7 @@ Adopt the following dependency swaps. Rejected — per-item evidence below; a fu
 - **`syncpack`/`manypkg` for `check-workspace-constraints.ts`**: they cover ~20 lines of range alignment; the load-bearing 200+ lines (computed `files` lists, cordis peer=dev pairing, hierarchy shape) are repo policy no generic engine expresses.
 - **`remark-validate-links` for `verify-md-links.ts`**: the gate rides the repo's shared mdast toolchain; adopting remark-cli adds a second markdown stack to delete one small file.
 - **`prebuildify`/`node-gyp-build` for the landlock launcher packaging**: inapplicable — those load `.node` addons via dlopen; the launcher ships a standalone exec'd static binary, and per-platform `optionalDependencies` *is* the ecosystem convention for binaries.
-- **Replacing the Landlock launcher itself with `@landstrip/landstrip`**: fails the security-invariant test — the launcher is a ~300-line reviewable C file with byte-pinned provenance that already migrated away from a Rust dependency; a single-maintainer LGPL Rust binary set is a larger audit surface with weaker provenance. (The unbuilt Windows rung was weighed separately and also [rejected](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — landstrip is not battle-tested.)
+- **Replacing the Landlock launcher itself with `@landstrip/landstrip`**: fails the security-invariant test — the launcher is a ~300-line reviewable C file whose binaries are byte-pinned to native CI builds and that already migrated away from a Rust dependency; a single-maintainer LGPL Rust binary set is a larger audit surface whose releases are harder to match to reviewed source. (The unbuilt Windows rung was weighed separately and also [rejected](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — landstrip is not battle-tested.)
 - **`hatch-nodejs-version` for Python release versioning**: roughly LOC-neutral (a custom metadata hook replaces the regex), inverts the recorded decision that the dev sentinel never determines a release version, and puts a single-maintainer build plugin in the release supply chain.
 - **YAML consolidation (`js-yaml` vs `yaml`)**: the repo carries both parsers, with the `!!js` tag defined four times on js-yaml (vendored include, app-boot, apps/cli, `scripts/verify-cordis-config.ts`) and twice on `yaml` (sdk-telemetry's `ScalarTag`, sdk-helper's comment-preserving Document editing). The direction is forced — js-yaml cannot replace `yaml` (sdk-helper needs the Document API) — but migrating the js-yaml sites cannot retire the library either (the vendored include pins it) and would put two parsers in charge of one dialect that must agree exactly, against the [personal-config note](../../implemented/feature/2026-07-20-dsh-cli-personal-config.md)'s deliberate load-only-copy parity. Deletable: ~20–25 lines of duplicate tag definitions and two `@types/js-yaml` entries. The consolidation moment is a future include sync, not now.
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index cc56dd4493..9e21c89fcb 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -67,7 +67,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `syncpack`/`manypkg` 替换 `check-workspace-constraints.ts`**：它们只覆盖约 20 行的版本范围对齐；承重的 200+ 行（计算生成的 `files` 列表、cordis peer=dev 配对、层级形状）是仓库政策，没有通用引擎能表达。
 - **以 `remark-validate-links` 替换 `verify-md-links.ts`**：该门禁搭载仓库共享的 mdast 工具链；采用 remark-cli 等于为删掉一个小文件而增加第二套 markdown 技术栈。
 - **以 `prebuildify`/`node-gyp-build` 承担 landlock 启动器打包**：不适用——那些工具通过 dlopen 加载 `.node` addon；这个启动器交付的是独立 exec 的静态二进制，而按平台划分的 `optionalDependencies` 恰恰*就是*二进制分发的生态惯例。
-- **以 `@landstrip/landstrip` 替换 Landlock 启动器本身**：未通过安全不变式检验——启动器是一个约 300 行、可完整评审、来源逐字节锁定的 C 文件，且早已从一个 Rust 依赖迁移出来；单一维护者的 LGPL Rust 二进制集合是更大的审计面加更弱的来源保障。（尚未构建的 Windows 层级经单独权衡后同样被[驳回](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——landstrip 未经实战检验。）
+- **以 `@landstrip/landstrip` 替换 Landlock 启动器本身**：未通过安全不变式检验——启动器是一个约 300 行、可完整评审的 C 文件，其二进制逐字节锁定到原生 CI 构建，且早已从一个 Rust 依赖迁移出来；单一维护者的 LGPL Rust 二进制集合有更大的审计面，其发布更难与已审阅源码对应。（尚未构建的 Windows 层级经单独权衡后同样被[驳回](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——landstrip 未经实战检验。）
 - **以 `hatch-nodejs-version` 承担 Python 发布版本号**：代码行数大致持平（一个自定义 metadata 钩子换掉那个正则），却反转了「dev 哨兵值绝不决定发布版本」这条记录在案的决策，还把一个单一维护者的构建插件放进发布供应链。
 - **YAML 归一（`js-yaml` 与 `yaml`）**：仓库同时携带两个解析器，`!!js` 标签在 js-yaml 上定义了四次（vendor 收录的 include、app-boot、apps/cli、`scripts/verify-cordis-config.ts`），在 `yaml` 上定义了两次（sdk-telemetry 的 `ScalarTag`、sdk-helper 的保留注释式 Document 编辑）。方向是被迫的——js-yaml 无法取代 `yaml`（sdk-helper 需要 Document API）——但迁移 js-yaml 各调用点也退休不了这个库（vendor 收录的 include 锁定了它），还会让两个解析器共管一种必须完全一致的方言，违背[个人配置决策](../../implemented/feature/2026-07-20-dsh-cli-personal-config.md)刻意的「仅加载副本」对等性。可删除的：约 20–25 行重复标签定义和两条 `@types/js-yaml` 条目。归一的时机是未来某次 include 同步，不是现在。
 
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index 90862b113e..e6d8c2658f 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: record-browser-gif
-description: Record browser or Web UI interaction demos as optimized GIFs using the available built-in browser, state-based frame capture, and deterministic encoding, then publish to a dedicated assets branch when the task includes attaching the GIF to a pull request. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include such a GIF with real provenance.
+description: Record browser or Web UI interaction demos as optimized GIFs using the available built-in browser, state-based frame capture, and deterministic encoding, then publish to a dedicated assets branch when the task includes attaching the GIF to a pull request. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include a GIF recorded from the pull request's real server and model flow.
 ---
 
 # Record Browser GIF
@@ -13,13 +13,13 @@ The [evidence-chain decision](../../notes/implemented/process/2026-08-08-browser
 
 A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via [the assets-branch workflow](#publish-to-an-assets-branch).
 
-The GIF's provenance is part of the evidence and must be real: a real server booted from that pull request's own branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for fixture provenance. State the provenance next to the embed — the exact demonstrated commit SHA, which tree and origin served, which mode flags or browser-state exceptions applied, and that a real model round ran — so reviewers know exactly what the recording proves.
+The recording itself is part of the evidence: use a real server booted from that pull request's branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for a fixture recording. Next to the embed, state the exact demonstrated commit SHA, the tree and origin that served it, any mode flags or browser-state exceptions, and whether a real model round ran, so reviewers know exactly what the recording proves.
 
 ## Keep the boundary explicit
 
 - Recording produces frame images and one local `.gif` artifact only; it never mutates remote state.
 - Publication — pushing the GIF to an assets branch and embedding it in a pull request body — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch.
-- Preserve the requested provenance. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
+- Preserve the requested recording conditions. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
 - Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.
 
 ## Stage the application
@@ -33,9 +33,9 @@ A GIF for a specific pull request demonstrates that pull request's tree, so stag
 
 ## Record the flow
 
-1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required; state that exception in the provenance and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
+1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required; state that exception next to the GIF and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback next to the GIF.
 2. Resolve the evidence boundary before recording: identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
-3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State the override in the provenance; a fixture, mock transport, or test-only hook is not an acceptable substitute.
+3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State that override next to the GIF; a fixture, mock transport, or test-only hook is not an acceptable substitute.
 4. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
 5. Keep one viewport and crop for every frame, and name frames lexically: `00-initial.png`, `01-typed.png`, and so on.
 6. Store frames under the repository's gitignored `.playwright-mcp/` directory — browser-tool screenshots can only be written under the tool's allowed roots, and relative filenames resolve against the repository root. Create the frame subdirectory first (`mkdir -p .playwright-mcp/gif-frames-<label>`); writing into a missing directory fails with ENOENT at capture time.
@@ -99,7 +99,7 @@ For a new series, make a fresh shallow scratch clone (`git clone --depth 1 <repo
 
 After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
 
-Immediately before editing the pull-request body, re-read its live head and compare it with the commit recorded in the GIF provenance. Stop and re-record when it moved. After the edit, re-read the live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
+Immediately before editing the pull-request body, re-read its live head and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. After the edit, re-read the live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
 
 Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image:
 
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 9bfe494ba6..0a03868e2b 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: 4f8aa86c0f6cdb91eb843048cd5ed4943a896c73
-README.zh.md: 09bc19220a869bedfcaa98baccbf6d4f6a3f3223
+README.md: bb3e1d77f00e03f6a21f4da3c04994f208e84293
+README.zh.md: 3802f940ef6663ec215cf09293a9edda5ea4c512
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 4f8aa86c0f..bb3e1d77f0 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -21,7 +21,7 @@ dsh --profile web --dump-default-config
 dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print provenance comments per layer; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
+`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print comments naming the file that supplied each row and every overlay that changed it; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
 
 ## One-shot run
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 09bc19220a..3802f940ef 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -21,7 +21,7 @@ dsh --profile web --dump-default-config
 dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会按层打印来源注释；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
+`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会打印注释，标明每行由哪个文件提供，以及哪些 overlay 修改过它；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
 
 ## 一次性运行
 
diff --git a/apps/cli/src/dump-config.ts b/apps/cli/src/dump-config.ts
index 9de7a55f60..1754eb4efd 100644
--- a/apps/cli/src/dump-config.ts
+++ b/apps/cli/src/dump-config.ts
@@ -1,7 +1,7 @@
 /**
  * Config-dump entry for `dsh --profile <name> --dump-config`: compose the
  * profile's patch layers through the include plugin's patch algorithm without
- * booting or evaluating `!!js`, with one provenance layer per bundle, the
+ * booting or evaluating `!!js`, with one source layer per bundle, the
  * profile's own patch file, and each `--patch` overlay.
  * @module @deepseek-ai/dsh/dump-config
  */
@@ -20,7 +20,7 @@ const NAME = 'dsh'
 
 /* v8 ignore start -- built-bin acceptance drives this boot-free dispatch */
 /**
- * Print a profile composition with provenance comments.
+ * Print a profile composition with comments naming each source file and patch layer.
  * @param profile - the profile name.
  * @param defaultOnly - omit the profile's user layer and `--patch` overlays
  * (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 073f541fe0..de44b110a1 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -518,7 +518,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(code).toBe(0)
       expect(stdout).toContain('provider: configured-provider')
       expect(stdout).not.toContain('personal-provider')
-      // Both layers patched the row; provenance lists them in application order.
+      // Both layers patched the row; the comment lists them in application order.
       expect(stdout).toContain(`patched by ${profilePatch}, ${overlay}`)
       expect(stderr).toContain('patch: entry "absent-row" not found')
     }, 30_000)
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index fac240fbe1..072a322fb6 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -83,7 +83,7 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
   /**
    * Append one event at the next seq/time.
    * @param event - the event body, without seq/time.
-   * @returns the seq it took, so provenance cites the push instead of arithmetic over the push order below.
+   * @returns the assigned seq, so later `sourceEventSeqs` cite the pushed event directly.
    */
   const at = (event: Record<string, unknown>): number => {
     const taken = seq++
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 672f6ba6f6..22a8ba53d7 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -42,7 +42,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
+- Write for professional programmers. Use concise, direct English without metaphor. Name the actor, source, event, field, or process; use words you would say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Do not overuse "gate", "vocabulary", "surface", or "seam".
 
 ## Wordcount Budgets
 
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 8690c792be..7e3939b7fd 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -71,7 +71,7 @@ sequenceDiagram
   Driver-->>SDK: <code>agent/status</code> idle
 ```
 
-The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.
+The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history, while the durable event keeps usage and `sourceEventSeqs` listing the exact `assistant/chunk` events, including an explicit empty list.
 
 `dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
 
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 3b279ef25a..33c39a89b4 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: ed33fb215c3b4fd830bef219da74f4ee98dec81d
-architecture.zh.md: 19d2500142449c63d725f89a651b22205af6b301
+architecture.md: 5e009d8345112bb0adcb2f55b4e49bbbf3bf8d00
+architecture.zh.md: c99336a03cd32fc4fb44b06c40ddd08a36b6a378
diff --git a/docs/architecture.md b/docs/architecture.md
index ed33fb215c..5e009d8345 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -92,7 +92,7 @@ forever:
       'step/start'
       append the returned batch as separate 'user/message' events
       assemble ordered prompt and tool schemas -> snapshot derived messages
-      agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
+      agent/request (config only) -> resolve adapter defaults and mark defaulted fields + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
       'assistant/chunk'
       'assistant/message'
       schedule tool calls by ctx.tools.executionMode:
@@ -144,13 +144,13 @@ The session log is authoritative. `deriveMessages()` projects model history; raw
 
 Durability is a plugin concern. Backends copy synchronous `session/event` notifications into fixed-window durable batches; `session/flush` bypasses the wait before requests and top-level tool dispatch, and after `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([checkpoint decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md), [batching decision](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
 
-Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; latest wins with provenance. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
+Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; the latest title event wins, and it records the source message seqs and whether the user, fallback, or provider supplied it. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
 
 ### Model Content
 
 Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](subsystems/token-meter.md).
 
-Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)).
+Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, the successful provider/model route, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)).
 
 ## Extension And Composition
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 19d2500142..c99336a03c 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -92,7 +92,7 @@ forever:
       'step/start'
       append the returned batch as separate 'user/message' events
       assemble ordered prompt and tool schemas -> snapshot derived messages
-      agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
+      agent/request (config only) -> resolve adapter defaults and mark defaulted fields + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
       'assistant/chunk'
       'assistant/message'
       schedule tool calls by ctx.tools.executionMode:
@@ -144,13 +144,13 @@ idle inject:
 
 持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一约定（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
-在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
+在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新的标题事件生效，并记录来源消息 seq，以及标题由用户、后备逻辑还是提供方提供。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
 ### 模型内容
 
 消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功使用的提供方／模型路由和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 6219a0080f..4c49120f17 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1197,7 +1197,7 @@ export interface Config {
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
    * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
    * infrastructure failure.
    */
   runnerCommand?: string[]
diff --git a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
index cb578de462..fde0ddda14 100644
--- a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
+++ b/docs/cookbook/maintaining-dsh-code-review.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 docs/cookbook/maintaining-dsh-code-review.md
-maintaining-dsh-code-review.md: 2b5d0d926ae922f2650daac33cf35991cb71c5e5
-maintaining-dsh-code-review.zh.md: 4466565b294ede89fa34da9e76b88f4ac39748eb
+maintaining-dsh-code-review.md: 8aa8a5792bff2c49041f2f8b5e8146e7cff14e0e
+maintaining-dsh-code-review.zh.md: b26c98e8679eece78e72ee684580c1ed1181aa7c
diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
index 2b5d0d926a..8aa8a5792b 100644
--- a/docs/cookbook/maintaining-dsh-code-review.md
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -10,7 +10,7 @@ Run the private tool daily with a two-UTC-day overlap; until the proposed schedu
 
 1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
 2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
-3. Two independently configured reviewer adapters classify provenance and adoption, then classify agreed-adopted items against the current skill.
+3. Two independently configured reviewer adapters classify who wrote each item and whether the change adopted it, then classify agreed-adopted items against the current skill.
 4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
 5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
 
@@ -38,7 +38,7 @@ When a run produces a candidate, a macOS notification arrives with a `dsh-code-r
      rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
      ```
    - **Batch.** Keep the candidate aside if the update is small and could combine with a future one. The source-skill check still applies; rerun the analysis or manually rebase and re-review the diff if `master` changes first.
-   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body carries the manifest's provenance summary. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
+   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body lists the source feedback URLs or IDs, landed commit range, originating run, checks, and operator edits. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
 
      ```sh
      cd ~/path/to/deepseek-harness   # clean master
diff --git a/docs/cookbook/maintaining-dsh-code-review.zh.md b/docs/cookbook/maintaining-dsh-code-review.zh.md
index 4466565b29..b26c98e867 100644
--- a/docs/cookbook/maintaining-dsh-code-review.zh.md
+++ b/docs/cookbook/maintaining-dsh-code-review.zh.md
@@ -10,7 +10,7 @@
 
 1. 选择指定窗口内合并、且合并 commit 可从 `origin/master` 到达的 PR（每天运行默认选择 2 个 UTC 日，每周运行选择 7 日）。合并 commit 无法到达的 PR（例如父分支被 squash 的堆叠分支），或超出 250 个 commit 获取上限的 PR，会记录到 `skipped-pulls.json` 并跳过，不会中止本次运行。
 2. 收集合并前带 commit 锚点的人工评审反馈（行内评论和评审提交），然后比较反馈时与最终落地的 PR patch。它不获取 PR 会话评论，因为 GitHub 当前状态无法为这些评论提供可抵抗 force-push 的反馈时基线；它也不会把只存在于目标分支的变更作为采纳证据。
-3. 两个独立配置的评审适配器先对来源和采纳情况分类，再根据当前 skill 对双方一致认定已采纳的条目分类。
+3. 两个独立配置的评审适配器先对每个条目的作者以及更改是否采纳了它进行分类，再根据当前 skill 对双方一致认定已采纳的条目分类。
 4. 主适配器起草完整修订版 `SKILL.md`；两个适配器评审同一份 diff；只要仍有阻塞性问题，循环就会继续，直到双方批准。
 5. 工具声明成功前，会针对候选版本运行 `pnpm run doc-sync` 和 `pnpm run lint`。
 
@@ -38,7 +38,7 @@
      rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
      ```
    - **留待成批处理。** 如果更新很小，可以把候选版本留待与后续版本合并。源 skill 检查仍然适用；如果 `master` 先发生变化，请重新运行分析，或手动 rebase 并重新评审 diff。
-   - **提升。** 在仓库的干净 `master` checkout 中运行提升辅助工具。它会刷新 `master`、验证当前 skill 与记录的源 blob 一致、应用保存的 diff，并创建一份 draft PR，其正文包含 manifest 的来源摘要。如果 skill 已发生漂移，它会停止而不是覆盖更新后的指导；操作员仍需在 GitHub 上评审 PR，并选择合并或关闭。
+   - **提升。** 在仓库的干净 `master` checkout 中运行提升辅助工具。它会刷新 `master`、验证当前 skill 与记录的源 blob 一致、应用保存的 diff，并创建一份 draft PR，其正文列出原始反馈的 URL 或 ID、已落地的 commit 范围、发起这次更改的运行、检查以及操作员编辑。如果 skill 已发生漂移，它会停止而不是覆盖更新后的指导；操作员仍需在 GitHub 上评审 PR，并选择合并或关闭。
 
      ```sh
      cd ~/path/to/deepseek-harness   # clean master
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 04c3a492fe..975a882706 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -64,11 +64,11 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -286,7 +286,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 
 ```ts persistence-catalog
 /**
- * Provenance record of a completed summarization — log-only, no surfaceOp.
+ * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
  * The summary content is in `data.summary`; the actual surface replacement
  * is performed by the immediately following `user/message` event that
  * shadows the compacted range. That adjacency is contractual — the
@@ -365,7 +365,7 @@ Source: [`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain
 
 ```ts persistence-catalog
 /**
- * A hook command was invoked at a hook point — log-only provenance (like
+ * A hook command was invoked at a hook point — a log-only record (like
  * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
  * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
  * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index b741c1cdf8..313b07ed56 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
-README.zh.md: 04e07cc9c8b8b16c69bb09344e8533729525fe5c
+README.md: 94e935998e39d4209476a8c62eb99fed0e0ce317
+README.zh.md: 0f4a4c65797cf75acc6f937e8e8beb5fcd641652
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 1c3d14aeb4..94e935998e 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -18,7 +18,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
 | [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
 | [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
-| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
+| [session-title.md](session-title.md) | durable title snapshots, cited source-message seqs, and the asynchronous provider contract |
 | [session-reference.md](session-reference.md) | structured cross-session references: `SessionReferenceInput`/`Candidate`, prepared message contexts, the stable error taxonomy |
 | [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 04e07cc9c8..0f4a4c6579 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -18,7 +18,7 @@
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方约定 |
+| [session-title.md](session-title.md) | 持久标题快照、被引用的来源消息 seq 与异步提供方约定 |
 | [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index ed13dea399..425f48409a 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 5aef839192ea6f67bb409622187fe65fed795e73
-compaction.zh.md: 20b4b2381f6e638e1d1b4db13ba98d53379b38db
+compaction.md: 058fdba7969ac1f5b337b7ff008b0e62cf9ed035
+compaction.zh.md: b4108ed5de55e027d633a180db968c7cd7ffee59
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 5aef839192..058fdba796 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -8,15 +8,15 @@ Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact
 
 ## The `compact/*` session events
 
-Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the compaction lock and its provenance, and never join the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. See the Agent Note for why reusing `user/message` is honest rather than a workaround.
+Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. See the Agent Note for why reusing `user/message` is honest rather than a workaround.
 
 | Event | Payload | Role |
 |---|---|---|
 | `compact/start` | `{ turn }` | acquires the log-recorded lock; a number identifies the open automatic turn, while `null` identifies a standalone manual attempt |
-| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()` (which requires complete `rawOutput`), the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); unmarked `rawOutput` does not identify the call path |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()` (which requires complete `rawOutput`), the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); unmarked `rawOutput` does not identify the call path |
 | `compact/end` | `{ turn, error? }` | releases the lock with the same numeric-or-null owner (`error` records an unsuccessful attempt) |
 
-The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` provenance record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished.
+The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished.
 
 The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
 
@@ -88,7 +88,7 @@ The seam exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalan
 The optional tool-result pruning service reports each durable content replacement and the aggregate Unicode-code-point reduction. Its public result types live in [`compact-tool-result-prune/src/types.ts`](../../packages/compact/compact-tool-result-prune/src/types.ts).
 
 ```ts type-equiv
-/** Provenance and size accounting for one landed surface replacement. */
+/** Cited source event and size accounting for one landed surface replacement. */
 interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
   readonly originalSeq: number
@@ -212,7 +212,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 /**
  * Prune every over-budget tool result from one stable current-surface snapshot.
  * Each replacement preserves the complete event data except for `content`,
- * points at the shadowed node for durable provenance and replay, and is
+ * cites the shadowed node so replay can recover the replacement input, and is
  * immediately preceded by a `compact/prune` shadow-price event pricing the
  * shadowed node through the injected token meter, so pure consumers can
  * subtract it without per-node state.
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 20b4b2381f..b4108ed5de 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -8,15 +8,15 @@
 
 ## `compact/*` 会话事件
 
-压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——记录压缩锁及其 provenance，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
+压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——它们记录锁、摘要、选中范围、被遮蔽事件 seq、token 数以及模型调用，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
 
 | 事件 | 载荷 | 作用 |
 |---|---|---|
 | `compact/start` | `{ turn }` | 获取日志记录的锁；数字标识打开的自动轮次，`null` 标识独立手动尝试 |
-| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记（此时必须提供完整的 `rawOutput`）、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；未带标记的 `rawOutput` 并不能判定调用路径 |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | 安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记（此时必须提供完整的 `rawOutput`）、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；未带标记的 `rawOutput` 并不能判定调用路径 |
 | `compact/end` | `{ turn, error? }` | 使用相同的数字或 `null` 归属值释放锁（`error` 记录失败尝试） |
 
-锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
+锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
 
 这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。
 
@@ -88,7 +88,7 @@ type ManualCompactionErrorCode =
 可选的工具结果剪枝服务会报告每次持久内容替换以及 Unicode code point 的总减少量。其公开结果类型位于 [`compact-tool-result-prune/src/types.ts`](../../packages/compact/compact-tool-result-prune/src/types.ts)。
 
 ```ts type-equiv
-/** Provenance and size accounting for one landed surface replacement. */
+/** Cited source event and size accounting for one landed surface replacement. */
 interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
   readonly originalSeq: number
@@ -212,7 +212,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 /**
  * Prune every over-budget tool result from one stable current-surface snapshot.
  * Each replacement preserves the complete event data except for `content`,
- * points at the shadowed node for durable provenance and replay, and is
+ * cites the shadowed node so replay can recover the replacement input, and is
  * immediately preceded by a `compact/prune` shadow-price event pricing the
  * shadowed node through the injected token meter, so pure consumers can
  * subtract it without per-node state.
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 6a117435f5..55589b0232 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: b09e5b4f0a076a7f95a751a6204836a81a4c31e9
-core.zh.md: 01ac656fb657296fb26217108b8a4a15a5a88280
+core.md: b6ed77c1f06b903924db31547d57e07ea37129be
+core.zh.md: e0cf8b39ba2430e250c9d0e51eebf902537cf198
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index b09e5b4f0a..b6ed77c1f0 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -107,7 +107,7 @@ interface Agent {
    * cancel leaves it parked. A wake submitted while already idle always opens
    * its turn boundary, even when its message is cleared before the driver
    * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
+   * @param message - identified content and the source that supplied it.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
    */
@@ -116,7 +116,7 @@ interface Agent {
   /**
    * Queue an ordinary follow-up turn and wake the driver. The item becomes the
    * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
+   * @param message - identified prompt content and the source that supplied it.
    */
   followup(message: UserMessage): void
 
@@ -125,7 +125,7 @@ interface Agent {
    * a running driver consumes it at its next step boundary.
    * A rejected step leaves steering parked in the inbox until the next
    * wake; cancellation or disposal may discard pending steering.
-   * @param message - identified steering content and its producer provenance.
+   * @param message - identified steering content and the source that supplied it.
    */
   steer(message: UserMessage): void
 
@@ -135,7 +135,7 @@ interface Agent {
    * idle drivers leave it pending until follow-up or steering
    * wakes them. It may miss a request whose pre-step already claimed its
    * batch. Cancellation or disposal may discard pending context.
-   * @param message - identified injected context and its producer provenance.
+   * @param message - identified injected context and the source that supplied it.
    */
   inject(message: UserMessage): void
 }
@@ -200,7 +200,7 @@ type AgentCancelCause =
   | { readonly kind: 'disposed' }
 ```
 
-The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
+The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; recording who requested cancellation would require a separate durable event rather than overloading the terminal result.
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
@@ -210,7 +210,7 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
+Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's id and source. Hook bridges map their native decision fields onto this typed result.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
@@ -243,7 +243,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## Sessions
 
-A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants additionally carry `sourceEventSeqs` provenance and a `surfaceOp`.
+A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants may also list cited earlier events in `sourceEventSeqs` and carry a `surfaceOp`.
 
 The `SessionEvent` envelope's exact conditional shape, the twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 01ac656fb6..e0cf8b39ba 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -111,7 +111,7 @@ interface Agent {
    * cancel leaves it parked. A wake submitted while already idle always opens
    * its turn boundary, even when its message is cleared before the driver
    * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
+   * @param message - identified content and the source that supplied it.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
    */
@@ -120,7 +120,7 @@ interface Agent {
   /**
    * Queue an ordinary follow-up turn and wake the driver. The item becomes the
    * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
+   * @param message - identified prompt content and the source that supplied it.
    */
   followup(message: UserMessage): void
 
@@ -129,7 +129,7 @@ interface Agent {
    * a running driver consumes it at its next step boundary.
    * A rejected step leaves steering parked in the inbox until the next
    * wake; cancellation or disposal may discard pending steering.
-   * @param message - identified steering content and its producer provenance.
+   * @param message - identified steering content and the source that supplied it.
    */
   steer(message: UserMessage): void
 
@@ -139,7 +139,7 @@ interface Agent {
    * idle drivers leave it pending until follow-up or steering
    * wakes them. It may miss a request whose pre-step already claimed its
    * batch. Cancellation or disposal may discard pending context.
-   * @param message - identified injected context and its producer provenance.
+   * @param message - identified injected context and the source that supplied it.
    */
   inject(message: UserMessage): void
 }
@@ -204,7 +204,7 @@ type AgentCancelCause =
   | { readonly kind: 'disposed' }
 ```
 
-cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
+cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录谁请求了取消，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
 [事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
@@ -216,7 +216,7 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有
 
 ## 拦截决策
 
-pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。
+pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的 id 和 source。钩子桥接层把其原生决策字段映射到这一类型化结果上。
 
 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
@@ -249,7 +249,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## 会话
 
-`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。每个条目携带单调的 `seq`、`time` 与按 `type` 判别的 `data` payload；surface 变体还额外携带 `sourceEventSeqs` provenance 与 `surfaceOp`。
+`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。每个条目携带单调的 `seq`、`time` 与按 `type` 判别的 `data` payload；surface 变体还可以在 `sourceEventSeqs` 中列出被引用的较早事件，并携带 `surfaceOp`。
 
 `SessionEvent` 信封的确切条件形状、十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 946aca73b0..abb60661c8 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 1705c45697df98b51ba9f69c8c91b3a8a18dea76
-llm-streaming.zh.md: b47ae516e39cb6657ce5b6ada69d524d5f5ea174
+llm-streaming.md: 37f2fcc51a8b899414927615a7c7750254fa9445
+llm-streaming.zh.md: f9dab459be1006c6ea894498b9a28b49e9ec7738
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 1705c45697..37f2fcc51a 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -31,10 +31,10 @@ The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBl
 
 Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
 
-A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:
+A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages name the provider and model that produced them and carry optional adapter-private replay data in their source:
 
 ```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
+/** Provider/model identity and adapter-private replay data for an assistant message. */
 interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -58,7 +58,7 @@ interface Message {
   readonly role: 'system' | 'user' | 'assistant'
   /** Exact model-facing blocks. */
   readonly content: ContentBlock[]
-  /** Required producer provenance. */
+  /** Required source fields supplied by the producer. */
   readonly source: MessageSource
 }
 ```
@@ -78,12 +78,12 @@ interface MessageSourceMap {
 }
 ```
 
-Provenance and shape are two independent axes. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
+Producer identity and content shape are independent. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
 
 ```ts type-equiv
 /**
  * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
+ * the producer beside the source fields it supplied.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
@@ -210,7 +210,7 @@ Every adapter MUST obey these, and every consumer may rely on them:
 - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
 - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
 - **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
-- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content and provenance without the private state.
+- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state.
 
 This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
 
@@ -264,7 +264,7 @@ interface TokenUsage {
 
 ## `BlockAssembler`
 
-`BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with its provider/model provenance. A consumer that needs the assembled result without re-implementing the fold uses this.
+`BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with the provider and model that produced it. A consumer that needs the assembled result without re-implementing the fold uses this.
 
 ```ts public-api
 /**
@@ -585,9 +585,9 @@ interface LlmDiscoveredModel {
 
 ### The request envelope: `LlmCallConfig` and the logged header
 
-The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
+The loop builds each request from logged state. `EpochHeader` records call config, marks the fields supplied by adapter defaults, and records the rendered prompt and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
-`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus provenance under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
+`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus the fields supplied by adapter defaults under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
 
 On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
 
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index b47ae516e3..f9dab459be 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -31,10 +31,10 @@ interface ContentBlockMap {
 
 源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
 
-`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：
+`Message` 是一个带标识且不可变的角色／来源／内容值。模型生成的 assistant 消息会在来源中记录生成它的提供方和模型，以及可选的适配器私有回放数据：
 
 ```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
+/** Provider/model identity and adapter-private replay data for an assistant message. */
 interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -58,7 +58,7 @@ interface Message {
   readonly role: 'system' | 'user' | 'assistant'
   /** Exact model-facing blocks. */
   readonly content: ContentBlock[]
-  /** Required producer provenance. */
+  /** Required source fields supplied by the producer. */
   readonly source: MessageSource
 }
 ```
@@ -78,12 +78,12 @@ interface MessageSourceMap {
 }
 ```
 
-溯源与形态是相互独立的两根轴。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
+生产方标识与内容形态相互独立。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
 
 ```ts type-equiv
 /**
  * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
+ * the producer beside the source fields it supplied.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
@@ -214,7 +214,7 @@ interface LlmFailure {
 - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
-- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
+- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。
 
 该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
@@ -272,7 +272,7 @@ interface TokenUsage {
 
 ## `BlockAssembler`
 
-`BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同其提供方/模型 provenance 一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
+`BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同生成它的提供方和模型一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
 
 ```ts public-api
 /**
@@ -593,9 +593,9 @@ interface LlmDiscoveredModel {
 
 ### 请求信封：`LlmCallConfig` 与记录的 header
 
-循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
+循环从已记录状态构建每个请求。`EpochHeader` 记录调用配置，标记由适配器默认值提供的字段，并通过完整的 `request/header` 快照记录渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
 
-`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置及其来源。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
+`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置以及由适配器默认值提供的字段。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
 
 在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 728a6cf8db..02a3502a1a 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: 54ae1eaf34a17d4979a621e4fc310780b425364e
-session-query.zh.md: b770514757c30aa5d87b25e5d280b1ce6710cd9c
+session-query.md: 9e907b2ebf12c01620921c7955f25d2fdd6ce4fb
+session-query.zh.md: 4452330ebd5e487387c0ad15bea45b76d9c643be
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 54ae1eaf34..9e907b2ebf 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -292,10 +292,10 @@ interface SessionEventWindow {
 
 ## Event relationships
 
-Event traces distinguish positional surface replacement from logged provenance. Every seq list contains direct links except `replacementChain`, which follows immediate replacers from the target to the final positional replacement.
+Event traces distinguish positional surface replacement from events cited as sources. Every seq list contains direct links except `replacementChain`, which follows immediate replacers from the target to the final positional replacement.
 
 ```ts type-equiv
-/** Request for direct surface and provenance relationships around one event. */
+/** Request for direct surface replacements and relationships to cited source events around one event. */
 interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
@@ -305,7 +305,7 @@ interface SessionEventTraceRequest {
 ```
 
 ```ts type-equiv
-/** Direct surface and provenance relationships for one event. */
+/** Direct surface replacements and relationships to cited source events for one event. */
 interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
@@ -315,9 +315,9 @@ interface SessionEventTrace {
   replacementChain: number[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
-  /** Direct logged provenance sources in their recorded order. */
+  /** Earlier events cited directly as sources, in their recorded order. */
   sourceEventSeqs: number[]
-  /** Later events that directly name the target as a provenance source, in log order. */
+  /** Later events that directly cite the target as a source, in log order. */
   derivedEventSeqs: number[]
 }
 ```
@@ -471,11 +471,11 @@ async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
 async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
 
 /**
- * Trace one event's direct positional and provenance relationships.
+ * Trace one event's direct positional replacements and cited source events.
  * @param request - target session id and event seq.
  * @param signal - optional cancellation for persisted source resolution.
  * @returns source header, direct links, and the target's positional replacement chain.
- * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
  */
 async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index b770514757..4452330ebd 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -292,10 +292,10 @@ interface SessionEventWindow {
 
 ## 事件关系
 
-事件追踪会区分位置替换与日志中记录的来源关系。除 `replacementChain` 外，每个 seq 列表都只包含直接链接；该链从目标沿直接 replacer 追踪到最终的位置替换。
+事件追踪会区分位置替换与被引用为来源的事件。除 `replacementChain` 外，每个 seq 列表都只包含直接链接；该链从目标沿直接 replacer 追踪到最终的位置替换。
 
 ```ts type-equiv
-/** Request for direct surface and provenance relationships around one event. */
+/** Request for direct surface replacements and relationships to cited source events around one event. */
 interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
@@ -305,7 +305,7 @@ interface SessionEventTraceRequest {
 ```
 
 ```ts type-equiv
-/** Direct surface and provenance relationships for one event. */
+/** Direct surface replacements and relationships to cited source events for one event. */
 interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
@@ -315,9 +315,9 @@ interface SessionEventTrace {
   replacementChain: number[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
-  /** Direct logged provenance sources in their recorded order. */
+  /** Earlier events cited directly as sources, in their recorded order. */
   sourceEventSeqs: number[]
-  /** Later events that directly name the target as a provenance source, in log order. */
+  /** Later events that directly cite the target as a source, in log order. */
   derivedEventSeqs: number[]
 }
 ```
@@ -471,11 +471,11 @@ async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
 async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
 
 /**
- * Trace one event's direct positional and provenance relationships.
+ * Trace one event's direct positional replacements and cited source events.
  * @param request - target session id and event seq.
  * @param signal - optional cancellation for persisted source resolution.
  * @returns source header, direct links, and the target's positional replacement chain.
- * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
  */
 async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
 
diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
index 8b58415234..29804cae7e 100644
--- a/docs/subsystems/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.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 docs/subsystems/session-title.md
-session-title.md: 3a2df284f2af14def284e502f4e37daaf4d7a262
-session-title.zh.md: 3a74baa9005459b35b658df95bdd7b57256b3e2e
+session-title.md: 339177b03a03b7d82375f7a293934cb164e9f266
+session-title.zh.md: b1353025a4f621e9a3117c0406ad304c35828a49
diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md
index 3a2df284f2..339177b03a 100644
--- a/docs/subsystems/session-title.md
+++ b/docs/subsystems/session-title.md
@@ -8,7 +8,7 @@ Sources: [`packages/session/session-title/src/index.ts`](../../packages/session/
 
 ## Durable title state
 
-`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` carries exact human-message provenance, while `SessionTitleSnapshot` adds the durable event envelope facts selected by `foldSessionTitle()`.
+`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` lists the exact human-message seqs used for the title, while `SessionTitleSnapshot` adds the durable event envelope facts selected by `foldSessionTitle()`.
 
 ```ts type-equiv
 /** Identifies one session-title provider registration. */
@@ -47,7 +47,7 @@ interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 ```
@@ -86,7 +86,7 @@ interface SessionTitleLlmRequestEventData {
 
 ## Provider input and output
 
-The service snapshots eligible messages through one revision. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends provenance.
+The service snapshots eligible messages through one revision. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends the title with its source-message seqs and source kind.
 
 ```ts type-equiv
 /** One eligible human text message exposed to title providers. */
@@ -132,14 +132,14 @@ interface SessionTitleProviderResult {
 ```ts type-equiv
 /** One optional asynchronous title implementation registered with the service. */
 interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md
index 3a74baa900..b1353025a4 100644
--- a/docs/subsystems/session-title.zh.md
+++ b/docs/subsystems/session-title.zh.md
@@ -8,7 +8,7 @@
 
 ## 持久标题状态
 
-提供方生成修订时会记录 `SessionTitleProviderId`。`SessionTitleEventData` 携带精确的人类消息来源信息，`SessionTitleSnapshot` 则加入 `foldSessionTitle()` 选出的持久事件封装信息。
+提供方生成修订时会记录 `SessionTitleProviderId`。`SessionTitleEventData` 列出生成标题时使用的精确人类消息 seq，`SessionTitleSnapshot` 则加入 `foldSessionTitle()` 选出的持久事件封装信息。
 
 ```ts type-equiv
 /** Identifies one session-title provider registration. */
@@ -47,7 +47,7 @@ interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 ```
@@ -86,7 +86,7 @@ interface SessionTitleLlmRequestEventData {
 
 ## 提供方输入与输出
 
-服务会对截至某一修订的合格消息创建快照。提供方返回的 seq 仅可来自该请求；由服务负责的接纳流程会验证顺序、规范化标题、强制执行字节上限并追加来源信息。
+服务会对截至某一修订的合格消息创建快照。提供方返回的 seq 仅可来自该请求；由服务负责的接纳流程会验证顺序、规范化标题、强制执行字节上限，并追加标题及其来源消息 seq 和来源类型。
 
 ```ts type-equiv
 /** One eligible human text message exposed to title providers. */
@@ -132,14 +132,14 @@ interface SessionTitleProviderResult {
 ```ts type-equiv
 /** One optional asynchronous title implementation registered with the service. */
 interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 6f28409864..890563b91d 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 7735e90807f6fce1b3645096437b3e86189dc8ec
-session.zh.md: 63eb460f7ef300decf3e32c0ace16b354606c271
+session.md: 6fb39e946cf5acdc407aab99888d40960d617248
+session.zh.md: 30edd630b4c945d3b696b5ac346b4bcebfb3df16
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 7735e90807..6fb39e946c 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -8,7 +8,7 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
 
 ## `SessionEventMap` — the event vocabulary
 
-The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` provenance for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.
+The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` records for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.
 
 ```ts type-equiv
 /** A user-role specialization of the one shared message representation. */
@@ -151,7 +151,7 @@ interface TodoItem {
 
 ### The request header event: `request/header`
 
-The request envelope — the `EpochHeader` (call config + adapter-default provenance + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability Agent Note). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message.
+The request envelope — the `EpochHeader` (call config + markers for adapter-supplied defaults + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability Agent Note). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message.
 
 ```ts type-equiv
 /**
@@ -217,11 +217,11 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -232,7 +232,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`.
 
-For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means legacy or otherwise unrecorded provenance. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
+For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means the source stream was not recorded in a legacy or foreign event. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
 
 ## Surface types
 
@@ -278,15 +278,15 @@ type SurfaceOp =
 
 ```ts type-equiv
 /**
- * Surface placement and provenance for {@link Session.append}. Required on
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
 interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
-   * Complete known provenance source set. `assistant/message` may use a
+   * Complete set of known source-event seqs. `assistant/message` may use a
    * present empty array for a known empty provider stream; omission means its
-   * provenance was not recorded. Other surface events require a non-empty set
+   * source stream was not recorded. Other surface events require a non-empty set
    * when this field is present.
    */
   sourceEventSeqs?: number[]
@@ -295,7 +295,7 @@ interface SurfaceIntent {
 
 Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived model history. A human-facing transcript is the other projection and reads the log's append-origin events instead, because the surface deliberately shadows the ranges a replacement summarizes (`isAppendSurfaceEvent` in [dsh-session](../../packages/core/session/README.md)). Non-surface types reject it at compile time.
 
-The same provenance distinction applies here: only `assistant/message` may carry a present empty `sourceEventSeqs`; omission does not assert that its source stream was empty.
+Only `assistant/message` may carry a present empty `sourceEventSeqs`; omission means the source stream was not recorded and does not assert that the stream was empty.
 
 ### `SessionSurface` — the live readonly surface projection
 
@@ -430,8 +430,8 @@ declare class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
-   *   numbers of events this one derives from). REQUIRED for
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
@@ -445,7 +445,7 @@ declare class Session {
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance), or when the candidate violates the
    *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier provenance, positional replacement validity, and complete
+   *   earlier source-event references, positional replacement validity, and complete
    *   shadowed-node coverage). One recursive pass reads, validates, and
    *   copies each nested value once, so a stateful getter cannot supply one value
    *   to validation and another to storage. The event log is the durable source
@@ -508,11 +508,11 @@ declare class Session {
 `Session.deriveMessages()` projects the event log into the `Message[]` the model sees — cached (each surface node projected once, when first seen; a surface rewrite rebuilds) and frozen (a fresh array per call over shared, deep-frozen messages, so mutating logged history through a projection is unrepresentable). `deriveEventMessage(event)` is the per-node pure function the fold applies — public so external reconstructors and the dev invariant project a log prefix with exactly the same rules and cannot disagree with the cache. The projection rules:
 
 - `user/message` → a user message carrying exact `content`; an optional envelope remains log-only display metadata.
-- `assistant/message` → an assistant message with the event's provider/model provenance and optional adapter-private replay state. Raw `assistant/chunk` events are replay/UI data and are **skipped** in derivation (the assembled message is authoritative). An **empty-content** `assistant/message` is also skipped — a max-tokens step cut off with no content still records an `assistant/message` to host its usage/provenance, but a content-less assistant turn must not enter the provider transcript.
+- `assistant/message` → an assistant message with the provider and model that produced it plus optional adapter-private replay state. Raw `assistant/chunk` events are replay/UI data and are **skipped** in derivation (the assembled message is authoritative). An **empty-content** `assistant/message` is also skipped — a max-tokens step cut off with no content still records an `assistant/message` to hold its usage, provider, and model, but a content-less assistant turn must not enter the provider transcript.
 - `tool/result` → a user message carrying a `tool-result` block.
-- `user/message` (injected context, i.e. non-`user` source) → a user-role message carrying its `content` verbatim at its chronological position; provenance and domain data live in its typed source.
+- `user/message` (injected context, i.e. non-`user` source) → a user-role message carrying its `content` verbatim at its chronological position; its typed source names the producer and carries any producer-specific data.
 
-Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and does not project into a message. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message, so their usage chunk is the durable accounting record. Because this unreleased format intentionally has no compatibility promise, seed/load validation rejects request headers without provider+model and assistant messages without provider/model provenance instead of guessing a route for historical data.
+Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and does not project into a message. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message, so their usage chunk is the durable accounting record. Because this unreleased format intentionally has no compatibility promise, seed/load validation rejects request headers and assistant messages that omit provider/model instead of guessing a route for historical data.
 
 ## Live-session fork API
 
@@ -577,9 +577,9 @@ Activity ordering excludes the boundary through `lastActivityTime(events)`: pick
 
 ## Plugin-contributed log-only events
 
-A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The full per-event enumeration — core and plugin-contributed alike, with payloads and provenance — is the generated [persistence log event catalog](../persistence-catalog.md); the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
+A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, cited source-event seqs, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
 
-The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
+The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
 ## Durability contract
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 63eb460f7e..30edd630b4 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -8,7 +8,7 @@
 
 ## `SessionEventMap`：事件词汇
 
-仅追加的事件类型。可通过声明合并扩展：插件通过 declaration merging 声明额外的事件类型。例如[压缩（compaction） seam](compaction.md) 添加了 `compact/start` / `compact/summary` / `compact/end`，`@deepseek-ai/dsh-hook-protocol` 添加了仅记录日志的 `hook/invoked` / `hook/result` 溯源事件，用于钩子桥接。与 `compact/*` 一样，这些都不是 `SurfaceEventType`（没有 `surfaceOp`）。生成的[持久化日志事件目录](../persistence-catalog.md)列举了所有成员（核心与合并扩展的），包含其 payload、surface 标记与声明位置。
+仅追加的事件类型。可通过声明合并扩展：插件通过 declaration merging 声明额外的事件类型。例如[压缩（compaction） seam](compaction.md) 添加了 `compact/start` / `compact/summary` / `compact/end`，`@deepseek-ai/dsh-hook-protocol` 为钩子桥接添加了仅记录日志的 `hook/invoked` / `hook/result` 记录。与 `compact/*` 一样，这些都不是 `SurfaceEventType`（没有 `surfaceOp`）。生成的[持久化日志事件目录](../persistence-catalog.md)列举了所有成员（核心与合并扩展的），包含其 payload、surface 标记与声明位置。
 
 ```ts type-equiv
 /** A user-role specialization of the one shared message representation. */
@@ -153,7 +153,7 @@ interface TodoItem {
 
 ### 请求头事件：`request/header`
 
-请求信封（即 `EpochHeader`：调用配置 + 适配器默认值来源 + 渲染后的系统提示词 + 已组装的工具 schema）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；之后请求发生变化时，系统会以 reason `'change'` 记录另一份完整快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。
+请求信封（即 `EpochHeader`：调用配置 + 适配器所提供默认值的标记 + 渲染后的系统提示词 + 已组装的工具 schema）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；之后请求发生变化时，系统会以 reason `'change'` 记录另一份完整快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。
 
 ```ts type-equiv
 /**
@@ -219,11 +219,11 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -234,7 +234,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展，对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`：插件添加的变体是合法的未知值；处理已知 case 后在 `default` 中放行。
 
-对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或其他未记录溯源信息的情况。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
+对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或外部事件没有记录源流。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
 
 ## Surface 类型
 
@@ -280,15 +280,15 @@ type SurfaceOp =
 
 ```ts type-equiv
 /**
- * Surface placement and provenance for {@link Session.append}. Required on
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
 interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
-   * Complete known provenance source set. `assistant/message` may use a
+   * Complete set of known source-event seqs. `assistant/message` may use a
    * present empty array for a known empty provider stream; omission means its
-   * provenance was not recorded. Other surface events require a non-empty set
+   * source stream was not recorded. Other surface events require a non-empty set
    * when this field is present.
    */
   sourceEventSeqs?: number[]
@@ -297,7 +297,7 @@ interface SurfaceIntent {
 
 对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生模型历史的唯一来源）。面向人类的记录（transcript）是另一个投影，读取的是日志中追加来源的事件，因为 surface 会有意遮蔽替换所概括的范围（见 [dsh-session](../../packages/core/session/README.md) 的 `isAppendSurfaceEvent`）。非 surface 类型在编译期拒绝此参数。
 
-此处适用相同的溯源区分：只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段并不表示其源流为空。
+只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段表示源流没有记录，而不是表示源流为空。
 
 ### `SessionSurface`：实时只读 surface 投影
 
@@ -432,8 +432,8 @@ declare class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
-   *   numbers of events this one derives from). REQUIRED for
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
@@ -447,7 +447,7 @@ declare class Session {
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance), or when the candidate violates the
    *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier provenance, positional replacement validity, and complete
+   *   earlier source-event references, positional replacement validity, and complete
    *   shadowed-node coverage). One recursive pass reads, validates, and
    *   copies each nested value once, so a stateful getter cannot supply one value
    *   to validation and another to storage. The event log is the durable source
@@ -510,11 +510,11 @@ declare class Session {
 `Session.deriveMessages()` 将事件日志投影为模型看到的 `Message[]`。它是缓存的（每个 surface 节点在首次出现时投影一次；surface 重写触发重建）且冻结的（每次调用返回一个新数组，引用共享的深冻结消息，因此通过投影修改已记录的历史在类型上不可表达）。`deriveEventMessage(event)` 是折叠所应用的逐节点纯函数，公开暴露以便外部重建器和开发不变式检查能以完全相同的规则投影日志前缀，不会与缓存产生分歧。投影规则：
 
 - `user/message` → 一条携带确切 `content` 的 user 消息；可选 envelope 仅作为日志中的展示元数据保留。
-- `assistant/message` → 一条 assistant 消息，包含事件的提供方/模型溯源信息和可选的适配器私有回放状态。原始 `assistant/chunk` 事件属于回放/UI 数据，在派生时会被**跳过**（组装后的消息才是权威）。**内容为空的** `assistant/message` 也会跳过：因 max-tokens 而截断且无内容的步骤仍会记录一条 `assistant/message` 以承载用量和溯源信息，但无内容的 assistant 轮次不得进入提供方 transcript（文本记录）。
+- `assistant/message` → 一条 assistant 消息，包含生成它的提供方和模型，以及可选的适配器私有回放状态。原始 `assistant/chunk` 事件属于回放/UI 数据，在派生时会被**跳过**（组装后的消息才是权威）。**内容为空的** `assistant/message` 也会跳过：因 max-tokens 而截断且无内容的步骤仍会记录一条 `assistant/message` 来保存用量、提供方和模型，但无内容的 assistant 轮次不得进入提供方 transcript（文本记录）。
 - `tool/result` → 一条携带 `tool-result` 块的 user 消息。
-- `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`；溯源信息与领域数据都在其类型化的 source 中。
+- `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`；其类型化 source 标明生产方，并携带所有生产方专用数据。
 
-其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝缺少提供方和模型的请求头，以及缺少提供方/模型溯源信息的 assistant 消息，而不会猜测历史数据应走的提供方路由。
+其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝没有提供方／模型的请求头和 assistant 消息，而不会猜测历史数据应走的提供方路由。
 
 ## 活跃会话 fork API
 
@@ -581,9 +581,9 @@ interface TurnEndReasonMap {
 
 ## 插件贡献的仅日志事件
 
-插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。完整的逐事件枚举（核心与插件贡献的，含 payload 与溯源信息）见生成的[持久化日志事件目录](../persistence-catalog.md)；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
+插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记、被引用的来源事件 seq 和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
 
-钩子桥接层的 `hook/invoked` / `hook/result` 溯源对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
+钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
 ## 持久性约定
 
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index 67b938a93a..1e9547cc28 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/subsystems/spill.md
-spill.md: 41a3fdaf7d9b15fbc6d479724f77f579b8a98738
-spill.zh.md: 02a6fc4e88dfcfdb47f7639d988fc09c6bc42c69
+spill.md: a0a476761ab0633227d7c87033daee79f649bf50
+spill.zh.md: 65d7e4cb89a93e2e709af0a620f523aad2315ed2
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index 41a3fdaf7d..a0a476761a 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -8,7 +8,7 @@ Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/typ
 
 ## The save request
 
-`saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), WHERE it came from (`source`, descriptive provenance for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
+`saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -42,7 +42,7 @@ interface SpillOwner {
 
 ```ts type-equiv
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
  * filename and inspection. Not interpreted for access control; purely
  * descriptive.
  */
@@ -107,7 +107,7 @@ Semantics every implementation must honor:
 ```ts cordis-catalog
 /**
  * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, provenance, suggested name, and full text to save.
+ * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
  * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
  */
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 02a6fc4e88..65d7e4cb89 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -8,7 +8,7 @@
 
 ## 保存请求
 
-`saveText` 是整个 seam：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、内容来源（`source`，用于命名和检查的描述性来源信息，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
+`saveText` 是整个 seam：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -42,7 +42,7 @@ interface SpillOwner {
 
 ```ts type-equiv
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
  * filename and inspection. Not interpreted for access control; purely
  * descriptive.
  */
@@ -107,7 +107,7 @@ Semantics every implementation must honor:
 ```ts cordis-catalog
 /**
  * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, provenance, suggested name, and full text to save.
+ * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
  * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
  */
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 9ecb6e4628..cad0584ea2 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
-subagent.zh.md: 37b274d7f3ffa5b5aadea773d29f7e6b4e5a833b
+subagent.md: cbb7c37f1ff3bce673f78a29ff8993659078df73
+subagent.zh.md: 308770141aa44fadeabed5f080d0df47c3802f15
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 3bf3ac7c48..cbb7c37f1f 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -137,7 +137,7 @@ persisted Session
 
 The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/enqueue`, `agent/inbox/dequeue`, and `agent/inbox/discard` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
 
-Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` are durable provenance after admission and grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
+Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` record who supplied an admitted message but grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
 
 For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no steering operation.
 
@@ -425,7 +425,7 @@ interface SubagentProvider {
 }
 ```
 
-Provider `start()` fulfills with a published run. The service mints a unique `runId`, snapshots `local` from the provider's exact `localAgent`, observes the result, emits `subagent/start`, and returns the same run; a `start()` rejection implies cleanup of unpublished resources and emits no lifecycle pair, while a post-publication result rejection closes the emitted pair. Each continuable Activation emits the same observe-only pair for its residency epoch, so a cold resume is a new epoch with its own `runId`. The paired `subagent/end` carries the same identity and the final output or infrastructure failure. Both events are observe-only and contain listener exceptions. Their `provider` field is provenance for the run or Activation epoch, not a claim that the provider remains registered when the edge is emitted.
+Provider `start()` fulfills with a published run. The service mints a unique `runId`, snapshots `local` from the provider's exact `localAgent`, observes the result, emits `subagent/start`, and returns the same run; a `start()` rejection implies cleanup of unpublished resources and emits no lifecycle pair, while a post-publication result rejection closes the emitted pair. Each continuable Activation emits the same observe-only pair for its residency epoch, so a cold resume is a new epoch with its own `runId`. The paired `subagent/end` carries the same identity and the final output or infrastructure failure. Both events are observe-only and contain listener exceptions. Their `provider` field names the provider that started the run or Activation epoch; it does not claim that the provider remains registered when the edge is emitted.
 
 ## In-process backends: depth and seed
 
@@ -469,7 +469,7 @@ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
  * @param parent - the exact live direct parent authorizing this delivery.
  * @param childId - durable child session id.
  * @param content - user-role content to deliver.
- * @param options - durable provenance and caller cancellation, which stops the
+ * @param options - the message source fields and caller cancellation, which stops the
  *   operation only before inbox acceptance.
  * @returns the accepted message's inbox id.
  * @throws when continuation services are unavailable, parent authority is
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 37b274d7f3..308770141a 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -137,7 +137,7 @@ persisted Session
 
 Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/enqueue`、`agent/inbox/dequeue` 与 `agent/inbox/discard` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
 
-后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 在准入之后是持久的来源凭据，不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
+后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 记录谁提供了已准入的消息，但不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
 
 对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
 
@@ -427,7 +427,7 @@ interface SubagentProvider {
 }
 ```
 
-提供方的 `start()` 会以已发布的 run fulfill。服务铸造唯一的 `runId`，从提供方确切的 `localAgent` 快照 `local`，观察结果，emit `subagent/start`，并返回同一个 run；`start()` rejection 意味着未发布资源已清理，且不会 emit 生命周期事件对，而发布后的结果 rejection 会结束已经 emit 的事件对。每个可继续 Activation 都会为其驻留纪元 emit 相同的仅观察事件对，因此一次冷恢复就是一段拥有自己 `runId` 的新纪元。配对的 `subagent/end` 携带相同标识与最终输出或基础设施失败。两个事件都仅用于观察，且会隔离各自的 listener 异常。其中的 `provider` 字段是 run 或 Activation 时段的来源信息，并不声明该 edge 发出时提供方仍处于注册状态。
+提供方的 `start()` 会以已发布的 run fulfill。服务铸造唯一的 `runId`，从提供方确切的 `localAgent` 快照 `local`，观察结果，emit `subagent/start`，并返回同一个 run；`start()` rejection 意味着未发布资源已清理，且不会 emit 生命周期事件对，而发布后的结果 rejection 会结束已经 emit 的事件对。每个可继续 Activation 都会为其驻留纪元 emit 相同的仅观察事件对，因此一次冷恢复就是一段拥有自己 `runId` 的新纪元。配对的 `subagent/end` 携带相同标识与最终输出或基础设施失败。两个事件都仅用于观察，且会隔离各自的 listener 异常。其中的 `provider` 字段标明了启动 run 或 Activation 时段的提供方，并不声明该 edge 发出时提供方仍处于注册状态。
 
 ## 进程内后端：深度与种子
 
@@ -471,7 +471,7 @@ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
  * @param parent - the exact live direct parent authorizing this delivery.
  * @param childId - durable child session id.
  * @param content - user-role content to deliver.
- * @param options - durable provenance and caller cancellation, which stops the
+ * @param options - the message source fields and caller cancellation, which stops the
  *   operation only before inbox acceptance.
  * @returns the accepted message's inbox id.
  * @throws when continuation services are unavailable, parent authority is
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index e598429553..36ea230990 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -1021,7 +1021,7 @@ Source: [`packages/session-query/tool-session-query/src/index.ts`](../packages/s
 
 ### `session_event_trace`
 
-Read every direct replacement and provenance relationship for one event in an authorized session.
+Read every direct replacement and relationship to a cited source event for one event in an authorized session.
 
 ```json
 {
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index 6fe6f4055b..35a9a1627e 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -64,7 +64,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     expect(starts.length).toBeGreaterThan(0)
     expect(ends.length).toBe(starts.length) // every start was released
 
-    // It succeeded at least once: a compact/summary provenance event and a
+    // It succeeded at least once: a `compact/summary` event describing the summary and a
     // replace-op user/message (the surface mutation) both landed.
     const summaries = events.filter(e => e.type === 'compact/summary')
     expect(summaries.length).toBeGreaterThan(0)
diff --git a/native/landlock-run/docs/architecture.md b/native/landlock-run/docs/architecture.md
index b462b40635..458281bf29 100644
--- a/native/landlock-run/docs/architecture.md
+++ b/native/landlock-run/docs/architecture.md
@@ -25,7 +25,7 @@ The launcher exits `125` without exec'ing the command on any launcher-level fail
 
 ## Build and release model
 
-Builds are native-only. `scripts/build.ts` compiles the running architecture's binaries with the distro `musl-gcc` (static: no loader or libc expectations on consumers, one binary for glibc and musl distros); CI's per-architecture runners are the builders of record, and no cross toolchain exists in the repo. The audit surface of a tool is its reviewed C source plus CI provenance, enforced by three gates: platform prepack refuses missing/wrong-ELF binaries, entry prepack refuses unbuilt `lib/`, and the release pipeline byte-pins installed binaries against the workspace builds they were packed from.
+Builds are native-only. `scripts/build.ts` compiles the running architecture's binaries with the distro `musl-gcc` (static: no loader or libc expectations on consumers, one binary for glibc and musl distros); CI's per-architecture runners are the builders of record, and no cross toolchain exists in the repo. Review covers the C source and the CI job that built each binary, enforced by three gates: platform prepack refuses missing/wrong-ELF binaries, entry prepack refuses unbuilt `lib/`, and the release pipeline byte-pins installed binaries against the workspace builds they were packed from.
 
 The package matrix is checked-in metadata (`prebuilds.json` + `os`/`cpu` fields); `scripts/github-matrix.mjs` derives the CI and Release matrices from it, so adding a platform extends automation without editing workflows.
 
diff --git a/native/landlock-run/scripts/build.ts b/native/landlock-run/scripts/build.ts
index 5866cc0dc4..b8e2d34f12 100644
--- a/native/landlock-run/scripts/build.ts
+++ b/native/landlock-run/scripts/build.ts
@@ -10,7 +10,7 @@
  * distros alike, no loader or libc expectations on the consumer host), and
  * CI's per-arch runners are the builders of record. No cross toolchain
  * exists here on purpose: native runners replace it, and the audit surface
- * is the reviewed C source plus CI provenance.
+ * is the reviewed C source plus the CI job that built the binary.
  *
  * Binaries land in `packages/<name>/bin/` — git-ignored (root
  * `.gitignore`), packed into the platform package's npm tarball behind its
diff --git a/native/landlock-run/scripts/verify-launcher-binary.mjs b/native/landlock-run/scripts/verify-launcher-binary.mjs
index 083cd837aa..997b20ca0f 100644
--- a/native/landlock-run/scripts/verify-launcher-binary.mjs
+++ b/native/landlock-run/scripts/verify-launcher-binary.mjs
@@ -8,9 +8,8 @@
  * binary's absence surfacing only at runtime as a failed probe on every
  * consumer — and a binary copied across packages would advertise an
  * architecture it cannot execute. The check is presence + ELF `e_machine`
- * against the package's declared `cpu`; byte provenance is
- * `verify-packed-install.mjs`'s concern (it pins the installed tarball
- * against the workspace build).
+ * against the package's declared `cpu`. `verify-packed-install.mjs`
+ * separately pins the installed tarball bytes to the workspace build.
  *
  * Runs from each platform package's `prepack` hook (pnpm sets the script
  * cwd to the package directory). Also callable directly with an explicit
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index b4eb8c4869..97ea5f301b 100644
--- 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: 74c1e28f76db35603bb9f72e0522e16ece5589f7
-README.zh.md: 34ad936f31bf4ce11e175653a3a895a56e4822cc
+README.md: 3ac46eaef8a0c6ee47c3141e2580c4d2e7750e8c
+README.zh.md: 4f3fb85c8de00497e4aff546d8234a81336586cb
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 74c1e28f76..3ac46eaef8 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -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 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.
+- **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` whose error path equals 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 `ENOENT`/`EACCES` shape with the runner path, 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/).
@@ -84,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.
-- **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.
+- **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 synchronous `SubprocessService` throw that names the runner path instead fails `start()` immediately.
 - **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index 34ad936f31..4f3fb85c8d 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -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 归因是保守的。** 进程启动前，只有当调用方拥有的 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` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
+- **Runner 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带 runner 路径的 `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/)。
@@ -84,5 +84,5 @@
 
 - **限制只覆盖文件影响**：网络访问与进程可见性不变，因此这些模式不是通用安全沙箱。
 - **拒绝从失败命令的 stderr 推断**：后端特征使该推断可跨平台使用，但包含相同后端特征的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
-- **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现；同步 `SubprocessService` 抛出带有来源信息的 `ENOENT`／`EACCES` 时，则会使 `start()` 立即失败。
+- **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现；`SubprocessService` 同步抛出的错误包含 runner 路径时，则会使 `start()` 立即失败。
 - **`danger-full-access` 有意绕过 `ctx.sandbox`**：它是显式无约束模式，不是更宽的沙箱 profile。
diff --git a/packages/bash/bash-sandbox/src/helpers.ts b/packages/bash/bash-sandbox/src/helpers.ts
index 357c73efa1..24ecb390de 100644
--- a/packages/bash/bash-sandbox/src/helpers.ts
+++ b/packages/bash/bash-sandbox/src/helpers.ts
@@ -23,7 +23,7 @@ function isUsableWorkdir(path: string): boolean {
 }
 
 /**
- * Attribute only Node ENOENT/EACCES failures with positive argv[0] provenance
+ * Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
  * 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
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index eadbae9fef..32695c475d 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -124,7 +124,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     try {
       proc = this.startArgv(spec, confined.argv)
     } catch (error) {
-      // LocalSubprocessService reports provenanced ENOENT/EACCES through async
+      // LocalSubprocessService reports ENOENT/EACCES with the failed executable path 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))
diff --git a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
index b578716c43..9176ac320b 100644
--- a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
+++ b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
@@ -151,7 +151,7 @@ describe('partial Landlock runner-failure classification', () => {
 
     // 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.
+    // ENOENT/EACCES with the exact failed executable path required for runner attribution.
     const foreground = await bash.run(bash.resolve(request)).catch((value: unknown) => value)
     expect(foreground).not.toBeInstanceOf(SandboxUnavailableError)
 
diff --git a/packages/bash/bash-sandbox/tests/sandbox.spec.ts b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
index 5bcf68df2d..9c3eceda1e 100644
--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -240,7 +240,7 @@ describe('fail closed', () => {
     expect(background).not.toBeInstanceOf(SandboxUnavailableError)
   })
 
-  it('classifies a synchronous SubprocessService EACCES with exact runner provenance', async () => {
+  it('classifies a synchronous SubprocessService EACCES with the exact runner path', async () => {
     const runner = join(spillDir, 'unexecutable-runner')
     const { ctx, bash } = await setup({}, argv => ({
       argv: [runner, ...argv],
@@ -439,7 +439,7 @@ describe('isRunnerSpawnFailure', () => {
     expect(isRunnerSpawnFailure(spawnError('ENOENT'), undefined, process.cwd())).toBe(false)
   })
 
-  it('accepts only syscall provenance compatible with the exact runner program', () => {
+  it('accepts only syscall and error-path facts that identify 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 })
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index e64706453e..21b4371c29 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
-README.md: c060e99acb8cc40b8de92806727eea9e3723b7d2
-README.zh.md: f28b89e63e4bd6f07f2f7a55dfba5c2f78862feb
+README.md: 1bbd376121ae79bf37376b51f5ac3eb405af6dfd
+README.zh.md: 0ecaa38deebfafe39673725ee8d35c36d60c5a41
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index c060e99acb..1bbd376121 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -19,7 +19,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md) and [`ds
 | `watchUserPatches(ctx, options)` | Register the named patch file with the existing Cordis HMR service; each add/change/removal transactionally recomposes the full patch list through the caller's `compose` closure (app-owned layers around the current user layer) and returns an async disposer |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile machinery (see [Profiles](#profiles)) |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error |
-| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of rows from the same file and patch layers is preceded by a `# ==` comment naming them, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |
 
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index f28b89e63e..0ecaa38dee 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -19,7 +19,7 @@
 | `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
-| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来自同一文件且经相同补丁层修改的连续行之前都有一条 `# ==` 注释，标明该文件和这些补丁层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index dec77aecab..c722f30f0f 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -165,7 +165,7 @@ function readEnvLayer(
  * Load the product CLI's inherited > invoking-directory `.env` > Harness-home
  * `.env` snapshot. The Harness home resolves before either file; both files
  * are checked before either is applied, and accepted values are materialized
- * without replacing inherited ones. The snapshot preserves source provenance.
+ * without replacing inherited ones. The snapshot preserves which layer supplied each value.
  * @param binName - the diagnostic prefix on the diagnostics.
  * @param cwd - the invoking directory whose `.env` is the project layer.
  * @param warn - sink for the one-line misconfiguration diagnostics.
@@ -335,9 +335,9 @@ function parsePatchList(
   return parsed as PatchOptions[]
 }
 
-/** One overlay patch list with the label provenance comments print for it. */
+/** One overlay patch list with the source label printed in dump comments. */
 export interface ConfigDumpLayer {
-  /** Source name shown in provenance comments (a file basename or path). */
+  /** Source name shown in dump comments (a file basename or path). */
   label: string
   /** The layer's patches, from {@link loadOverlayPatches} / {@link loadOptionalPatches}. */
   patches: PatchOptions[]
@@ -353,10 +353,10 @@ export interface ConfigDumpLayer {
  * sees) compose identically — then render the result as YAML in the same
  * dialect (`!!js` expressions print verbatim, unevaluated).
  *
- * Every run of rows with the same provenance is preceded by a `# ==` comment
+ * Every run of rows from the same file and patch layers is preceded by a `# ==` comment
  * naming the file that contributed the rows and any layers that patched them,
  * so the output stays a loadable YAML document while showing which section
- * comes from which file. Provenance is derived from single-call prefix
+ * comes from which file. The file and patch labels are derived from single-call prefix
  * snapshots (base + layers 1..k), diffed positionally: the patch algorithm
  * only rewrites rows in place or appends, so a top-level index identifies one
  * row across snapshots, and a layer whose addition changes the row (config
@@ -372,7 +372,7 @@ export interface ConfigDumpLayer {
  * @param layers - overlay layers in application order (later wins).
  * @param warn - sink for skipped-patch diagnostics; defaults to stderr.
  * @returns the composed entry list rendered as a YAML document with
- * provenance comment separators.
+ * source comment separators.
  */
 export function renderConfigDump(
   binName: string,
@@ -439,7 +439,7 @@ export function renderConfigDump(
   return groupedDump(composed, provenance)
 }
 
-/** Render the composed rows grouped under one provenance comment per contiguous run. */
+/** Render the composed rows grouped under one source-and-patches comment per contiguous run. */
 function groupedDump(
   composed: readonly unknown[],
   provenance: readonly { origin: string; patchedBy: string[] }[],
@@ -455,7 +455,7 @@ function groupedDump(
   }
   for (let index = 0; index < composed.length; index += 1) {
     const record = provenance[index]
-    /* v8 ignore next -- provenance is index-aligned with composed by construction */
+    /* v8 ignore next -- this array is index-aligned with composed by construction */
     if (record === undefined) continue
     const label = record.patchedBy.length === 0
       ? record.origin
diff --git a/packages/boot/app-boot/tests/config-dump.spec.ts b/packages/boot/app-boot/tests/config-dump.spec.ts
index 4f5d8e83e5..3876ec2421 100644
--- a/packages/boot/app-boot/tests/config-dump.spec.ts
+++ b/packages/boot/app-boot/tests/config-dump.spec.ts
@@ -1,7 +1,7 @@
 /**
  * `renderConfigDump` behavior: the offline composition must equal what
  * `boot()` mounts (same parser, same patch algorithm), print `!!js`
- * expressions verbatim, separate provenance runs with comment lines while
+ * expressions verbatim, separate source-file runs with comment lines while
  * staying one loadable YAML document, and report skipped patches through
  * `warn` instead of failing — mirroring the Loader's boot-time warning for a
  * shared overlay whose row exists only on another surface.
@@ -35,7 +35,7 @@ function writeBase(dir: string): string {
 }
 
 describe('renderConfigDump', () => {
-  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its provenance', () => {
+  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its source and patches', () => {
     const dir = tmp()
     const base = writeBase(dir)
     const surface = join(dir, 'surface.yml')
@@ -78,7 +78,7 @@ describe('renderConfigDump', () => {
     ])
     // Unevaluated: the expression text round-trips as a !!js scalar.
     expect(dump).toContain('!!js process.env.DSH_DUMP_SPEC')
-    // Provenance separators: origin file, plus every layer that changed the
+    // Source separators: origin file, plus every layer that changed the
     // row; an inserted row carries the inserting layer as its origin.
     expect(dump).toContain('# == base.yml, patched by surface.yml')
     expect(dump).toContain('# == base.yml\n- id: untouched')
@@ -86,7 +86,7 @@ describe('renderConfigDump', () => {
     expect(dump.indexOf('# == base.yml, patched by surface.yml')).toBeLessThan(dump.indexOf('# == base.yml\n- id: untouched'))
   })
 
-  it('groups contiguous same-provenance rows under one separator', () => {
+  it('groups contiguous rows with the same origin and patches under one separator', () => {
     const dir = tmp()
     const base = join(dir, 'base.yml')
     writeFileSync(base, [
@@ -130,7 +130,7 @@ describe('renderConfigDump', () => {
       config?: { config?: { v?: number } }[]
     }[]
     expect(parsed[0]?.config?.[0]?.config?.v).toBe(1)
-    // The skipped layer did not change the row, so it is not in provenance.
+    // The skipped layer did not change the row, so the comment does not list it.
     expect(dump).toContain('# == base.yml, patched by a.yml\n- id: g')
     expect(dump).not.toContain('b.yml\n- id: g')
   })
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 930a12dea3..641898424e 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: c2ce461439a89aa4fe2d59ebf92d14539479dac8
-README.zh.md: bca93b80989152eccccaf13c0f31435c91e7393c
+README.md: 08a45adc441cc2f672e84dea38d0991537187a1f
+README.zh.md: 7abf86aee015a7108547a0025ca8ba5beceecfb2
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index c2ce461439..08a45adc44 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -36,9 +36,9 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 ## The human transcript
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
-Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
+Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
 ## Request inspection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index bca93b8098..7abf86aee0 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -36,9 +36,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
 ## 请求检查
 
diff --git a/packages/client/runtime/src/client/sessions/context-provenance.ts b/packages/client/runtime/src/client/sessions/context-provenance.ts
index 6f46a510c1..e487f78b5d 100644
--- a/packages/client/runtime/src/client/sessions/context-provenance.ts
+++ b/packages/client/runtime/src/client/sessions/context-provenance.ts
@@ -1,4 +1,4 @@
-// Context provenance projection: the role and the human-facing producer name
+// Context source projection: the role and the human-facing producer name
 // of one logged non-user `user/message`, read from its durable `source` alone.
 // The client keeps no table of known plugin ids — a renamed or newly mounted
 // producer must never need a client release to stay identifiable, and a resumed
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index dba9ec9513..2681bb33f3 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -191,14 +191,14 @@ export interface CompactionSummaryNode {
   seq: number
   /** Unix epoch ms of the checkpoint event. */
   time: number
-  /** Summary text from the checkpoint's `compact/summary` provenance; null when
-   *  the window cut left that provenance outside (the marker is then not expandable). */
+  /** Summary text from the checkpoint's cited `compact/summary` event; null when
+   *  the window cut left that event outside (the marker is then not expandable). */
   summary: string | null
-  /** Seq of the loaded `compact/summary` event, or null when that provenance is outside the window. */
+  /** Seq of the loaded `compact/summary` event, or null when that event is outside the window. */
   summaryEventSeq: number | null
-  /** Number of surface items replaced, or null when summary provenance is unavailable or malformed. */
+  /** Number of surface items replaced, or null when the summary event is unavailable or malformed. */
   shadowedItemCount: number | null
-  /** Estimated token price of the replaced items, or null when summary provenance is unavailable or malformed. */
+  /** Estimated token price of the replaced items, or null when the summary event is unavailable or malformed. */
   shadowedTokenCount: number | null
 }
 
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 659afcac4a..aee51d3dc2 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -686,7 +686,7 @@ export class Session implements SessionFace {
    *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
    *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
    *  raw range, which is what lets the transcript render every event between its ends and lets a
-   *  compaction checkpoint find its own provenance. */
+   *  compaction checkpoint find its cited summary event. */
   private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
     if (this.openState === 'loading' || this.stitching) {
       this.liveBuffer.push({ event, view })
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index 25fade8633..e9e1c1d8d6 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -184,10 +184,10 @@ function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
 
 /**
  * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's own provenance (`sourceEventSeqs` names the
+ * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
  * `compact/summary` event), never from the framed checkpoint payload, which is
  * an instruction envelope written for the model. A window cut that left the
- * provenance outside soft-falls to `summary: null` (a non-expandable marker),
+ * summary event outside soft-falls to `summary: null` (a non-expandable marker),
  * the same posture as a call-less tool result.
  */
 function materializeCompaction(
@@ -222,7 +222,7 @@ function materializeCompaction(
 
 /** Log-ordered human transcript over a paged raw event window (never consults surface order). */
 export class TranscriptAdapter {
-  /** Window events by seq: provenance lookup for a checkpoint's summary. */
+  /** Window events by seq, used to find the summary event cited by a checkpoint. */
   private eventIndex = new Map<number, SessionEvent>()
   /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
   private projected: ConversationNode[] = []
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index bc3c10e762..de72d5b351 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -105,7 +105,7 @@ export const ev = {
       ...text === undefined ? {} : { text },
       ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
     } }),
-  /** A compaction's log-only `compact/summary` provenance record. */
+  /** A compaction's log-only `compact/summary` record. */
   compactSummary: (seq: number, summary: string, start: number, end: number): SessionEvent =>
     at(seq, { type: 'compact/summary', data: {
       summary: text(summary),
diff --git a/packages/client/runtime/tests/history-fold.spec.ts b/packages/client/runtime/tests/history-fold.spec.ts
index 37a1060fec..2f15bc9c92 100644
--- a/packages/client/runtime/tests/history-fold.spec.ts
+++ b/packages/client/runtime/tests/history-fold.spec.ts
@@ -12,7 +12,7 @@ const at = (seq: number, event: Record<string, unknown>): SessionEvent =>
 describe('projectConversationHistory', () => {
   it('names an injected context node from its durable source, like the live adapter', () => {
     // The fold declares its own node mapping (jscpd:ignore in the source), so
-    // the provenance projection is pinned on both sides independently.
+    // the source projection is pinned on both sides independently.
     const injected = at(0, {
       type: 'user/message',
       surfaceOp: 'append',
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index 05dc2855ca..b161046f84 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -14,7 +14,7 @@ import { ev, plainTurn } from './event-script.ts'
 const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
   ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
 
-/** A `compact/summary` provenance event (log-only, no surfaceOp). */
+/** A `compact/summary` event (log-only, no surfaceOp). */
 function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
   return at(seq, {
     type: 'compact/summary',
@@ -188,7 +188,7 @@ describe('TranscriptAdapter', () => {
 
   it('skips events core does not call surface-eligible, marker or not', () => {
     // The transcript is the append-origin surface, so log-only events (a chunk,
-    // a turn boundary, a compact/* provenance record) and a future type core
+    // a turn boundary, a `compact/*` record) and a future type core
     // has not admitted contribute no node.
     const adapter = new TranscriptAdapter()
     adapter.reset([
@@ -313,7 +313,7 @@ describe('TranscriptAdapter', () => {
     })
 
     it.each([
-      ['absent provenance', undefined],
+      ['absent summary event', undefined],
       ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
       ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
       ['an empty summary array', compactSummary(1, [])],
@@ -345,7 +345,7 @@ describe('TranscriptAdapter', () => {
       ])
     })
 
-    it('leaves the summary null when the checkpoint records no provenance at all', () => {
+    it('leaves the summary null when the checkpoint cites no source events', () => {
       const adapter = new TranscriptAdapter()
       adapter.reset([at(2, {
         type: 'user/message',
@@ -361,7 +361,7 @@ describe('TranscriptAdapter', () => {
       }])
     })
 
-    it('skips a non-summary provenance seq before reaching the real one', () => {
+    it('skips a cited non-summary seq before reaching the summary event', () => {
       const adapter = new TranscriptAdapter()
       adapter.reset([
         ev.user(0, '被压缩的问题'),
@@ -372,7 +372,7 @@ describe('TranscriptAdapter', () => {
       expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
     })
 
-    it('resolves the summary once an older page supplies the provenance', () => {
+    it('resolves the summary once an older page supplies the cited summary event', () => {
       const adapter = new TranscriptAdapter()
       const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
       adapter.reset([landed])
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index c03e330672..341a3409c3 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
-README.zh.md: b3ce1b66308213650505b8838b9b43cb9987c757
+README.md: 58c8dc68758ddae11966195c42cf324e388cfc47
+README.zh.md: f60b89c0ac378f5a87bb49194465fd8bc65d7c42
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index f5cf9b72b4..58c8dc6875 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, and turn status), composer dock (session stats sticky with the input), input dock (queue rows plus the todo plan strip), details shell, and scope-addressed ConversationService. Tool presentation belongs to [`ui-tool`](../ui-tool/README.md).
 
-Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with structured summary provenance shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
+Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with a loaded `compact/summary` event shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when the cited `compact/summary` event is outside the loaded window, the checkpoint remains visible but non-expandable.
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
@@ -16,7 +16,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
 
-Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The shared `DisclosureRow` primitive gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
+Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The shared `DisclosureRow` primitive gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [producer-label decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining source fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index b3ce1b6630..f60b89c0ac 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -4,7 +4,7 @@
 
 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。Tool 展示属于 [`ui-tool`](../ui-tool/README.md)。
 
-压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
+压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个已加载对应 `compact/summary` 事件的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；被引用的 `compact/summary` 事件位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
@@ -14,7 +14,7 @@
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[生产者标签决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源字段列出。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
index 5bd5a081cf..0995149e67 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -3,7 +3,7 @@
 // marker reports where the model stopped seeing that history — it never
 // replaces it. The framed checkpoint payload is written for the model and is
 // not rendered; the disclosure shows the summary from the checkpoint's own
-// provenance, and a window cut that left that provenance outside makes the row
+// cited `compact/summary` event, and a window cut that left that event outside makes the row
 // non-expandable rather than empty.
 
 import { memo, useState } from 'react'
diff --git a/packages/client/ui-conversation/src/client/chat/ContextBody.module.css b/packages/client/ui-conversation/src/client/chat/ContextBody.module.css
index c1f6f5361b..3ed07752bc 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextBody.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ContextBody.module.css
@@ -9,7 +9,7 @@
   overflow-wrap: anywhere;
 }
 
-/* Provenance beneath the text: dimmer than the content it describes. */
+/* Source fields beneath the text: dimmer than the content they describe. */
 .fields {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-conversation/src/client/chat/ContextBody.tsx b/packages/client/ui-conversation/src/client/chat/ContextBody.tsx
index 6af65bcdb9..3bbf9a842f 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextBody.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ContextBody.tsx
@@ -66,7 +66,7 @@ function boundedText(text: string, t: Translate): string {
 
 /**
  * One source field rendered as a value row; nested shapes stay compact JSON.
- * Bounded on its own, because provenance is as unbounded as the text: an unknown
+ * Bounded on its own, because source fields are as unbounded as the text: an unknown
  * producer may record an arbitrarily large string or array.
  */
 function fieldValue(value: unknown, t: Translate): string {
@@ -77,7 +77,7 @@ function fieldValue(value: unknown, t: Translate): string {
 }
 
 /**
- * Provenance fields as a key/value list. `kind` is always omitted because the
+ * Source fields as a key/value list. `kind` is always omitted because the
  * row header already names the producer. `form` is omitted only when a
  * dedicated body rendered for it — then the presentation the reader is looking
  * at IS that value. On the opaque fallback the declaration is kept, because
@@ -159,7 +159,7 @@ function ModelFacingContent({ content, t }: {
 
 /**
  * Default presentation: the model-facing text as text, with its real line
- * breaks, and the remaining provenance beneath it. This is what every form
+ * breaks, and the remaining source fields beneath it. This is what every form
  * this UI version does not recognize renders as.
  * @param props - Durable content, its source, and the locale seat.
  * @returns The opaque context body.
@@ -428,7 +428,7 @@ export function NoticeBody({ content, t }: {
 /**
  * `relay` form: which agent sent this, then what it said.
  *
- * The sender is an opaque session id; it is shown as provenance rather than a
+ * The sender is an opaque session id; it is shown as a field rather than a
  * label, because this client cannot resolve it to a title.
  * @param props - Durable content, its source, and the locale seat.
  * @returns The relay context body.
diff --git a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
index 1afdad37f1..889b15b085 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
@@ -25,7 +25,7 @@ export interface ContextInjectionRowProps {
  * from a workspace instruction file or a recalled session without expanding.
  * The expanded body follows the producer-declared form; an absent or unknown
  * form renders the opaque body.
- * @param props - Durable content, its projected provenance and form, and the locale seat.
+ * @param props - Durable content, its projected producer role/name and form, and the locale seat.
  * @returns A collapsed context row with a bounded, form-specific body.
  */
 export function ContextInjectionRow({ content, source, provenance, form, t }: ContextInjectionRowProps) {
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 41cbd61afc..0362c3ee4b 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -226,7 +226,7 @@ describe('MessageItem arms', () => {
     expect(disclosure.getAttribute('aria-expanded')).toBe('true')
     // An unknown form renders the opaque body: the model-facing text keeps its
     // real line breaks instead of being escaped into one JSON line, and the
-    // remaining provenance follows it as fields.
+    // remaining source data follows it as fields.
     expect(ctxView.container.querySelector('[data-context-text]')?.textContent)
       .toBe('line one\n\nline two')
     const fields = [...ctxView.container.querySelectorAll('[data-context-fields] dt')].map(node => node.textContent)
@@ -418,7 +418,7 @@ describe('MessageItem arms', () => {
     expect(view.container.querySelector('[data-context-text]')?.textContent).toBe('firstsecond')
   })
 
-  it('bounds an oversized provenance field, not only the model-facing text', () => {
+  it('bounds an oversized source field, not only the model-facing text', () => {
     const view = render(
       <MessageItem t={t} node={{
         kind: 'context',
@@ -708,7 +708,7 @@ describe('MessageItem arms', () => {
     expect(row.getAttribute('aria-expanded')).toBe('false')
   })
 
-  it('a marker whose provenance fell outside the window is not expandable', () => {
+  it('a marker whose cited summary event fell outside the window is not expandable', () => {
     const view = render(<MessageItem t={t} node={{
       kind: 'compaction', seq: 6, time: 1_000, summary: null,
       summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
diff --git a/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx b/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
index c1b4eb2f2f..70197763da 100644
--- a/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
@@ -7,7 +7,7 @@
 // change and must be reviewed as such — never re-record to silence a
 // refactor.
 //
-// Provenance is reproducible: the replaced pipeline last lived at commit
+// The fixture source is reproducible: the replaced pipeline last lived at commit
 // 9e8101b800 (origin/master before the renderer swap merged). Checking out
 // that ref in a worktree, copying this spec, and running it records all
 // fixtures from react-markdown byte-identical to the ones committed here:
diff --git a/packages/client/ui-trajectory/src/client/context-branches.ts b/packages/client/ui-trajectory/src/client/context-branches.ts
index bc5b74057b..2501511c50 100644
--- a/packages/client/ui-trajectory/src/client/context-branches.ts
+++ b/packages/client/ui-trajectory/src/client/context-branches.ts
@@ -12,7 +12,7 @@ export interface TrajectoryContextBranch {
   contexts: readonly ConversationContext[]
   latest: ConversationContext
   nodes: readonly ConversationNode[]
-  /** Seq that opened this branch; earlier requests require retained surface provenance. */
+  /** Seq that opened this branch; earlier requests require retained cited surface events. */
   startSeq: number
   /** Exact pre-rewind surface records inherited by this branch. */
   retainedSurfaceSeqs: ReadonlySet<number>
@@ -101,7 +101,7 @@ export function deriveTrajectoryContextBranches(
 
 /**
  * Test whether a provider request belongs to one rewind branch.
- * @param branch - Branch carrying exact inherited surface provenance.
+ * @param branch - Branch carrying the exact inherited surface event seqs.
  * @param request - Provider request to classify.
  * @returns Whether the request began on this branch or produced a retained surface record.
  */
diff --git a/packages/client/ui-trajectory/src/client/trajectory-record.ts b/packages/client/ui-trajectory/src/client/trajectory-record.ts
index a979278f3f..2c3f2a1a83 100644
--- a/packages/client/ui-trajectory/src/client/trajectory-record.ts
+++ b/packages/client/ui-trajectory/src/client/trajectory-record.ts
@@ -46,7 +46,7 @@ export interface TrajectoryCellProps extends HTMLAttributes<HTMLDivElement> {
   opensTurn?: boolean
   /** Source session-event seq for cross-record navigation. */
   sourceSeq?: number
-  /** Producer provenance from a user-role message or context injection. */
+  /** Producer role and name from a user-role message or context injection. */
   messageSource?: unknown
   /** Producer-owned model-hidden metadata carried beside the message source. */
   /** A separator-only anchor for an auxiliary request with no visible record. */
diff --git a/packages/compact/compact-basic/README.i18n.yaml b/packages/compact/compact-basic/README.i18n.yaml
index 61b6e4e6fb..c01b9166b5 100644
--- a/packages/compact/compact-basic/README.i18n.yaml
+++ b/packages/compact/compact-basic/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/compact/compact-basic/README.md
-README.md: 4241899788998a744801bb0406a15ecd70af6401
-README.zh.md: c1df4afaa1837a3b689da80cc1b49df43f60e513
+README.md: 5395219147e8932c8e5874e84e534a2c2fe33d53
+README.zh.md: 59479b26c5c8cf27e6ac84814c09f14ecbf9662c
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index 4241899788..5395219147 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -16,12 +16,12 @@ This backend owns the compaction policy:
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes. The optional pruner can repair an oversized closed tool unit when its text-bearing result is the removable bulk; indivisible non-tool units and non-prunable tool remainders remain out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
 - **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The call replays the conversation's own system prompt, tools, and shadowed-region messages verbatim and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. It sets `GenerateOptions.purpose` to `compaction`, which adapters may forward as request attribution (the DeepSeek adapter sends `x-deepseek-harness-compact: 1`) without touching the model-visible body. Only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
-- **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint.
-- **Lifecycle** — all entry points share one bracket-first region transaction. It validates the range and live lock, appends `compact/start` synchronously, prepares and awaits the summary, revalidates, appends provenance plus the replacement, and makes exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; the serial `agent/pre-step` listener checks pressure before request derivation, while canonical provider overflow enters through `agent/request-error` and authorizes retry only after durable surface progress. `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
+- **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the `compact/summary` event, and later automatic cycles merge the prior checkpoint.
+- **Lifecycle** — all entry points share one bracket-first region transaction. It validates the range and live lock, appends `compact/start` synchronously, prepares and awaits the summary, revalidates, appends `compact/summary` plus the replacement, and makes exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; the serial `agent/pre-step` listener checks pressure before request derivation, while canonical provider overflow enters through `agent/request-error` and authorizes retry only after durable surface progress. `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
 - **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
 - **Failure handling** — a live unmatched `compact/start` is the durable lock. An unmatched marker before a newer `session/end-seed` is stale evidence from a prior lifecycle and does not block; one after that boundary reports `busy`. Summary and changed-span failures close with an error and leave the conversation surface untouched, though the attempt remains in the log. A failed close deliberately leaves a blocking orphan. Operational pressure failures warn and continue, while overflow-recovery failure preserves the original provider error only when no earlier replacement advanced the surface. Cancellation remains authoritative after cleanup and durability.
 
-The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()` and requires complete `rawOutput`, while unmarked `rawOutput` does not identify the call path. The transaction preserves those fields on `compact/summary`.
+The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, cited source events, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()` and requires complete `rawOutput`, while unmarked `rawOutput` does not identify the call path. The transaction preserves those fields on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
diff --git a/packages/compact/compact-basic/README.zh.md b/packages/compact/compact-basic/README.zh.md
index c1df4afaa1..59479b26c5 100644
--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -16,12 +16,12 @@
 - **保留**：压缩最旧的完整表层单元，同时保留近期尾部，并通过 [`dsh-compact` 边界 helper](../compact/README.md#tool-pairing-boundaries) 将切分点调整到工具调用／结果配对平衡的位置。轮次边界不会保护失控轮次内的旧步骤。尚未闭合且不可分的尾部会在闭合前拒绝压缩。当闭合的超大工具单元以文本型结果为可移除主体时，可选 pruner 可以修复它；不可分的非工具单元与不可剪枝的工具剩余部分不在范围内。
 - **收敛**：最多按 `compactionRetries` 重试头部检查点压缩；拒绝不能缩小源内容的摘要，如果重试仍无法回到阈值以下，则抛出异常。
 - **摘要**：直接 `llm/stream` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 agent 目标，而不运行仅用于 agent loop 的 `agent/request` seam。该调用会逐字回放会话自身的系统提示词、工具与已遮蔽区域消息，并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。它将 `GenerateOptions.purpose` 设为 `compaction`，适配器可将其作为请求归因转发（DeepSeek 适配器发送 `x-deepseek-harness-compact: 1`），但不会触碰模型可见的请求体。只有返回的文本会进入检查点；推理（reasoning）和工具调用都会被排除，以免泄露私有推理或产生遗留调用。
-- **框定**：替换 user 消息使用 `<compacted-summary>` 标签标记已建立的检查点上下文。原始摘要保留在溯源事件上，后续自动周期会合并之前的检查点。
-- **生命周期**：所有入口点共享一个先记录标记的区域事务。它会验证范围与活动锁，同步追加 `compact/start`，准备并等待摘要，重新验证，再追加溯源信息和替换，最后恰好进行一次闭合尝试。自动调用和显式范围调用要求数字标识的开放轮次归属，并要求整个表层保持稳定；串行 `agent/pre-step` listener 会在派生请求之前检查压力，而规范提供方溢出则经由 `agent/request-error` 进入，并且只在表层取得持久进展后才允许重试。`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
+- **框定**：替换 user 消息使用 `<compacted-summary>` 标签标记已建立的检查点上下文。原始摘要保留在 `compact/summary` 事件上，后续自动周期会合并之前的检查点。
+- **生命周期**：所有入口点共享一个先记录标记的区域事务。它会验证范围与活动锁，同步追加 `compact/start`，准备并等待摘要，重新验证，再追加 `compact/summary` 和替换，最后恰好进行一次闭合尝试。自动调用和显式范围调用要求数字标识的开放轮次归属，并要求整个表层保持稳定；串行 `agent/pre-step` listener 会在派生请求之前检查压力，而规范提供方溢出则经由 `agent/request-error` 进入，并且只在表层取得持久进展后才允许重试。`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
 - **失败处理**：活动的未匹配 `compact/start` 是持久锁。位于较新 `session/end-seed` 之前的未匹配标记，是先前生命周期留下的陈旧证据，不会阻塞；位于该边界之后的标记报告 `busy`。摘要和 span 变更失败会以错误闭合，并保持会话表层不变，但日志中仍保留该尝试。闭合失败会有意留下阻塞性的未匹配标记。压力检查中的运行故障会发出警告并继续；只有此前没有替换推进表层时，溢出恢复失败才保留原始提供方错误。完成清理与持久化后，取消仍具有最终决定权。
 
-受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，且必须提供完整的 `rawOutput`；未带标记的 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
+受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、被引用的源事件、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，且必须提供完整的 `rawOutput`；未带标记的 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
 
 ## 配置（`BasicCompactConfig`）
 
diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts
index 211ac8a920..27b59d0451 100644
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -93,7 +93,7 @@ const modelPolicy: z<ModelCompactPolicyConfig> = z.object({
 
 /**
  * Dependency-light compaction backend using `ctx.tokenMeter` for pressure,
- * retention, provenance, and summary-convergence pricing.
+ * retention, cited source events, and summary-convergence pricing.
  *
  * `summarize()` is the sole subclass customization hook; the replay and durable
  * mutation strategy stays fixed so every pricing decision uses the singleton
@@ -230,7 +230,7 @@ export class BasicCompactService extends CompactService {
    * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
    * @param agent - supplies routed-model history, fallback model, and session id.
    * @param signal - optional cancellation forwarded to the adapter.
-   * @returns safe text summary blocks and exact auxiliary-call provenance.
+   * @returns safe text summary blocks and the exact auxiliary call envelope and output.
    */
   protected async summarize(
     input: SummarizationInput,
diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts
index 352603579b..b220074e02 100644
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -403,7 +403,7 @@ function assertSelectedSpanStable(
   }
 }
 
-/** Append one already-summarized provenance and replacement body without yielding. */
+/** Append one completed summary record and replacement body without yielding. */
 function commitCompactionBody(
   session: Session,
   startEvent: SessionEvent<'compact/start'>,
diff --git a/packages/compact/compact-basic/src/summarizer.ts b/packages/compact/compact-basic/src/summarizer.ts
index 8113dcd439..bed4dedb69 100644
--- a/packages/compact/compact-basic/src/summarizer.ts
+++ b/packages/compact/compact-basic/src/summarizer.ts
@@ -84,7 +84,7 @@ export interface SummarizationInput {
   readonly messages: readonly Message[]
 }
 
-/** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
+/** Safe summary content plus the exact auxiliary call envelope recorded with it. */
 export type SummaryResult = {
   summary: ContentBlock[]
   provider: string
@@ -116,7 +116,7 @@ export type SummaryResult = {
  * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
  * @param agent - supplies routed-model history, fallback model, and session id.
  * @param signal - optional cancellation forwarded to the adapter.
- * @returns safe text-only summary blocks and exact call provenance.
+ * @returns safe text-only summary blocks and the exact call envelope and output.
  */
 export async function summarizeWithLlm(
   ctx: Context,
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index 0e74a77e04..996d5d61e1 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -838,7 +838,7 @@ describe('optional model-free tool-result pruning', () => {
 })
 
 describe('compaction region transaction', () => {
-  it('lands a framed, replayable checkpoint with exact pricing provenance', async () => {
+  it('lands a framed, replayable checkpoint with exact source seqs and token price', async () => {
     const compact = service()
     compact.rawOutput = [
       { type: 'reasoning', text: 'private compact thought' },
diff --git a/packages/compact/compact-basic/tests/manual-compact.spec.ts b/packages/compact/compact-basic/tests/manual-compact.spec.ts
index d2dcda461e..7544c3223b 100644
--- a/packages/compact/compact-basic/tests/manual-compact.spec.ts
+++ b/packages/compact/compact-basic/tests/manual-compact.spec.ts
@@ -618,7 +618,7 @@ describe('compactNow transaction and failure classification', () => {
     const agent = fakeAgent(session, () => () => { released += 1 })
     const append = session.append.bind(session)
     vi.spyOn(session, 'append').mockImplementation(((type: string, ...rest: never[]) => {
-      if (type === 'compact/summary') throw new Error('provenance rejected')
+      if (type === 'compact/summary') throw new Error('summary record rejected')
       return (append as (...args: never[]) => unknown)(type as never, ...rest)
     }) as never)
 
@@ -627,7 +627,7 @@ describe('compactNow transaction and failure classification', () => {
     expect(error.code).toBe('commit')
     expect(released).toBe(1)
     const end = session.events.findLast(event => event.type === 'compact/end')
-    expect(end?.type === 'compact/end' && end.data.error).toContain('provenance rejected')
+    expect(end?.type === 'compact/end' && end.data.error).toContain('summary record rejected')
     expect(end?.type === 'compact/end' && end.data.turn).toBeNull()
   })
 
@@ -637,14 +637,14 @@ describe('compactNow transaction and failure classification', () => {
     const agent = fakeAgent(session, () => () => undefined)
     const append = session.append.bind(session)
     vi.spyOn(session, 'append').mockImplementation(((type: string, ...rest: never[]) => {
-      if (type === 'compact/summary') throw new Error('provenance rejected')
+      if (type === 'compact/summary') throw new Error('summary record rejected')
       return (append as (...args: never[]) => unknown)(type as never, ...rest)
     }) as never)
     vi.spyOn(ctx.sessions, 'flush').mockRejectedValueOnce(new Error('disk full'))
 
     const error = await rejection(compact.compactNow(agent, SIGNAL))
     expect(error.code).toBe('commit')
-    expect(causeOf(error).message).toBe('provenance rejected')
+    expect(causeOf(error).message).toBe('summary record rejected')
     vi.restoreAllMocks()
   })
 
diff --git a/packages/compact/compact-tool-result-prune/src/index.ts b/packages/compact/compact-tool-result-prune/src/index.ts
index f783cdd59d..48e3ee308b 100644
--- a/packages/compact/compact-tool-result-prune/src/index.ts
+++ b/packages/compact/compact-tool-result-prune/src/index.ts
@@ -124,7 +124,7 @@ export class ToolResultPruneService extends Service {
   /**
    * Prune every over-budget tool result from one stable current-surface snapshot.
    * Each replacement preserves the complete event data except for `content`,
-   * points at the shadowed node for durable provenance and replay, and is
+   * cites the shadowed node so replay can recover the replacement input, and is
    * immediately preceded by a `compact/prune` shadow-price event pricing the
    * shadowed node through the injected token meter, so pure consumers can
    * subtract it without per-node state.
diff --git a/packages/compact/compact-tool-result-prune/src/types.ts b/packages/compact/compact-tool-result-prune/src/types.ts
index f9dd846f35..13544b163e 100644
--- a/packages/compact/compact-tool-result-prune/src/types.ts
+++ b/packages/compact/compact-tool-result-prune/src/types.ts
@@ -17,7 +17,7 @@ export interface ResolvedConfig {
   readonly tailChars: number
 }
 
-/** Provenance and size accounting for one landed surface replacement. */
+/** Cited source event and size accounting for one landed surface replacement. */
 export interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
   readonly originalSeq: number
diff --git a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
index c5c7171c08..69a28eb123 100644
--- a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
+++ b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
@@ -159,7 +159,7 @@ describe('ToolResultPruneService content transform', () => {
 })
 
 describe('ToolResultPruneService session transaction', () => {
-  it('prunes a stable snapshot, preserves all data, and records provenance', () => {
+  it('prunes a stable snapshot, preserves all data, and cites the replaced result', () => {
     const session = Session.create(SessionId('preserve'))
     const originalSeq = appendToolStep(session, 1, 'one', [{
       type: 'text',
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index dc2254d647..c5045934c9 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22
-README.zh.md: d068869f1d9091e9671d8c2fb17df53a48c9916d
+README.md: c32be20117abfe15e278082089c5fd87828c81ef
+README.zh.md: 530b1ca30061956fbe37a4b4b90fed99c02e5a7f
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 2bf39cac91..c32be20117 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -42,7 +42,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,
-3. appends `compact/summary` (log-only) — provenance: summary, range, shadowed seqs, token count, and provider/model call envelope,
+3. appends `compact/summary` (log-only) with the summary, range, shadowed seqs, token count, and provider/model call envelope,
 4. appends a single `user/message` with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
 5. appends `compact/end` (log-only) — releases the lock.
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index d068869f1d..530b1ca300 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -42,7 +42,7 @@
 
 1. 追加 `compact/start`（仅日志）：获取锁；
 2. 摘要该范围；
-3. 追加 `compact/summary`（仅日志）：溯源信息包括摘要、范围、已遮蔽 seq、token 数与提供方／模型调用 envelope；
+3. 追加 `compact/summary`（仅日志），其中记录摘要、范围、已遮蔽 seq、token 数与提供方／模型调用 envelope；
 4. 追加单个 `user/message`，其携带 `source: COMPACT_CHECKPOINT_SOURCE` 和包含摘要的 `surfaceOp: { op: 'replace', start, end }`：这是**本操作唯一的表层变更**；
 5. 追加 `compact/end`（仅日志）：释放锁。
 
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index c235507c6a..4429e8b291 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -1,6 +1,6 @@
 /**
  * Compaction vocabulary: the result type and the `compact/*` session events.
- * Those declaration-merged events are log-only lock/provenance markers, not
+ * Those declaration-merged events record the lock and summary inputs without entering the surface, so they are not
  * surface events; a separate replacement `user/message` carries the summary.
  * Backend packages own configuration and retention policy; see
  * `.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md`.
@@ -18,7 +18,7 @@ declare module '@deepseek-ai/dsh-session' {
      */
     'compact/start': { turn: number | null }
     /**
-     * Provenance record of a completed summarization — log-only, no surfaceOp.
+     * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
      * The summary content is in `data.summary`; the actual surface replacement
      * is performed by the immediately following `user/message` event that
      * shadows the compacted range. That adjacency is contractual — the
diff --git a/packages/context/session-reference/src/types.ts b/packages/context/session-reference/src/types.ts
index 0693e0d212..e1eff84244 100644
--- a/packages/context/session-reference/src/types.ts
+++ b/packages/context/session-reference/src/types.ts
@@ -3,7 +3,7 @@
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 
-/** Durable provenance for one prepared cross-session context. */
+/** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
 export interface SessionReferenceSource {
   kind: 'session-reference'
   /** Material lifted out of another session's log (`recall` context form). */
diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts
index f302e48363..20343c9512 100644
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -33,7 +33,7 @@ import {
 
 export const name = 'workspace-context'
 
-/** Durable provenance and reconciliation facts for one workspace context. */
+/** Durable producer, file, and reconciliation facts for one workspace context. */
 export interface WorkspaceInstructionSource {
   kind: 'workspace-instructions'
   /** Every workspace context carries instructions read out of a file (the `instructions` context form). */
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index c8a81c8d13..9eb0eb4921 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
-README.zh.md: 22f9655d46c4c9764118f05cc919be26a471c00b
+README.md: 608a21a2f00545bbc03f675ee2f76034624bb10d
+README.zh.md: fc23c6cb0645c88f2e081a5dbb81dface8c553d6
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 81bc441197..608a21a2f0 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -63,9 +63,9 @@ Every inbox mutation publishes one normalized `agent/inbox/spliced` event before
 
 The driver owns one agent for its lifetime and runs inside `ctx.agents.withInitiator(agent, ...)`. Package-private orchestration entry points recover the exact Agent, derive `agent.session` once, and let operation-local helpers capture it instead of forwarding the concrete driver or per-operation `Session` through shallow interfaces. A helper keeps an explicit `Session` when that is its actual interface, while creation, persistence load, unpublished setup, services, workers, processes, persistence, and wire protocols retain their explicit identities. The [agent service](../agent/README.md#initiating-agent-scope) owns propagation, teardown, and detached-work rules.
 
-Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. The anchor records the assembled content as-is, retains exact chunk provenance (`[]` for a stream with no chunks), and includes usage when available; empty content stays out of derived message history.
+Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. The anchor records the assembled content as-is, lists the exact chunk seqs in `sourceEventSeqs` (`[]` for a stream with no chunks), and includes usage when available; empty content stays out of derived message history.
 
-After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance applies the same provenance rule when resuming.
+After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance follows the same adapter-default marker rule when resuming.
 
 Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Waking input that lands after the abort fires but before the activity converges to idle is latched (`wakeRequested`) and replayed at the driver's own convergence boundary, so it runs without a further waking send; a `disposed` cancel never latches, and a wake submitted while already idle always opens its turn boundary (status shows a transient `idle → running → idle` pair even when the message was cleared). Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) and the [cancel-convergence wake latch](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md) own the lifecycle and race contract.
 
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index 22f9655d46..fc23c6cb06 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -63,9 +63,9 @@ interface Config {
 
 驱动器在其整个生命周期内拥有一个 agent，并在 `ctx.agents.withInitiator(agent, ...)` 内运行。包私有的编排入口点会恢复确切的 Agent，一次性派生 `agent.session`，并让操作局部的辅助函数捕获它，而不是通过浅层接口继续传递具体驱动器或每次操作的 `Session`。如果显式 `Session` 正是辅助函数的实际接口，该辅助函数会保留它；创建、持久化加载、未发布 setup、服务、worker、进程、持久化和 wire 协议则继续保留各自的显式身份。[agent 服务](../agent/README.md#initiating-agent-scope)规定传播、teardown 和分离工作规则。
 
-每次提供方调用成功结束时，都会恰好追加一个 `assistant/message` 完成锚点，包括无内容调用和以 `max-tokens` 结束的调用。该锚点原样记录组装后的内容，保留确切的分片溯源（流没有分片时为 `[]`），并在用量可用时包含用量；空内容不会进入派生消息历史。
+每次提供方调用成功结束时，都会恰好追加一个 `assistant/message` 完成锚点，包括无内容调用和以 `max-tokens` 结束的调用。该锚点原样记录组装后的内容，在 `sourceEventSeqs` 中列出确切的分片 seq（流没有分片时为 `[]`），并在用量可用时包含用量；空内容不会进入派生消息历史。
 
-在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。
+在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会遵循同一套适配器默认值标记规则。
 
 插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会以终止错误或中止结束的形式由 `ctx.llm` 传来，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose 则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态约定。
 
diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts
index 47082dac18..693ff7bd91 100644
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -130,7 +130,7 @@ async function runGroup(
   const { session } = ctx.agents.requireInitiator()
   const { maxParallelToolCalls } = ctx.agentLoop.config
   const slots: (Slot | undefined)[] = group.map(() => undefined)
-  // Started slots retain their tool/call seq for result provenance.
+  // Started slots retain their `tool/call` seq so the result can cite it.
   const callSeqs: number[] = group.map(() => -1)
   let nextToStart = 0
   let committed = 0
@@ -258,7 +258,7 @@ function appendSkippedToolCall(session: Session, turn: number, step: number, blo
   }, callSeq)
 }
 
-/** Append a started call and return its provenance sequence. */
+/** Append a started call and return the event seq that its result must cite. */
 function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): number {
   const event = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments })
   return event.seq
diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts
index b6540d9912..7dfbaddc41 100644
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -59,7 +59,7 @@ function inboxText(message: UserMessage): string {
     .join('')
 }
 
-describe('assistant replay provenance', () => {
+describe('assistant replay provider and model fields', () => {
   it('records adapter replay state with the assembled assistant content', async () => {
     const response = textResponse('unchanged')
     const replayState = { private: 'state' }
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 825c1714a2..d1d8e5401d 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: ba0fa456593e598b6532c10ef2390bbd55f3a486
-README.zh.md: 581da5c8621e5653f57edce38ac9816da7a40d40
+README.md: 73d32d09d880b0d27b80a7aeecc1eb75bf03f8dd
+README.zh.md: e140d76c940ac605ddc6dedad8a9f2f16457fde0
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index ba0fa45659..73d32d09d8 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -115,5 +115,5 @@ Prefix-stable while an agent's scoped registrations are unchanged. Setup or relo
 - **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.
 - **`agent/session-start` cannot gate startup** — it remains a synchronous, veto-less notification; async composition that must finish before publication belongs in the factory's `setup(agentCtx)` transaction instead.
 - **`cancel()` clears the inbox by default** — it aborts the in-flight turn plus queued and steering work; `cancel(cause, { keepInbox: true })` aborts only the turn and preserves pending items. There is still no step-only abort that keeps the in-flight turn running ([stop-surface Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
-- **Each additional `UserMessage` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source; mixed provenance is unrepresentable.
+- **Each additional `UserMessage` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source, so the message cannot name several producers.
 - **`SessionStartSource` reserves `'clear'`/`'compact'` with no emitter yet** — only `'startup'`/`'resume'` occur until the driving subsystems land (`TODO(compaction)`).
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 581da5c862..e140d76c94 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -115,5 +115,5 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 - **委派以外的 agent 间通道**：共享状态、流式子输出和后台／轮询语义仍在当前同步 `ctx.subagents` seam 之外。
 - **`agent/session-start` 不能为启动设置门禁**：它仍是同步且不可 veto 的通知；必须在发布前完成的异步组合属于工厂的 `setup(agentCtx)` 事务。
 - **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
-- **每条附加 `UserMessage` 恰好携带一个 `MessageSource`**：多个插件合并到一次工具调用上的贡献会归入一个来源；无法表示混合来源。
+- **每条附加 `UserMessage` 恰好携带一个 `MessageSource`**：多个插件合并到一次工具调用上的贡献会归入同一来源，因此该消息无法列出多个生产者。
 - **`SessionStartSource` 预留 `'clear'`/`'compact'`，但还没有发出方**：在驱动子系统落地前，只会出现 `'startup'`/`'resume'`（`TODO(compaction)`）。
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index d8cb5c4114..ba9afa50d7 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -109,7 +109,7 @@ export interface Agent {
    * cancel leaves it parked. A wake submitted while already idle always opens
    * its turn boundary, even when its message is cleared before the driver
    * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
+   * @param message - identified content and the source that supplied it.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
    */
@@ -118,7 +118,7 @@ export interface Agent {
   /**
    * Queue an ordinary follow-up turn and wake the driver. The item becomes the
    * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
+   * @param message - identified prompt content and the source that supplied it.
    */
   followup(message: UserMessage): void
 
@@ -127,7 +127,7 @@ export interface Agent {
    * a running driver consumes it at its next step boundary.
    * A rejected step leaves steering parked in the inbox until the next
    * wake; cancellation or disposal may discard pending steering.
-   * @param message - identified steering content and its producer provenance.
+   * @param message - identified steering content and the source that supplied it.
    */
   steer(message: UserMessage): void
 
@@ -137,7 +137,7 @@ export interface Agent {
    * idle drivers leave it pending until follow-up or steering
    * wakes them. It may miss a request whose pre-step already claimed its
    * batch. Cancellation or disposal may discard pending context.
-   * @param message - identified injected context and its producer provenance.
+   * @param message - identified injected context and the source that supplied it.
    */
   inject(message: UserMessage): void
 }
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index abb9bfc6f2..67364cb415 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 00e007ee6064f485bf80dfda0227ab6e834f6414
-README.zh.md: e9d074f52db46cb42e497ad1ef49c2b37a6ec7d8
+README.md: 04d3cec7e431f5f265d52851eae59600536ce5b7
+README.zh.md: e9529b3c91c8d2413c64b4e344af83b6ebe698de
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 00e007ee60..04d3cec7e4 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
 
-The optional `@deepseek-ai/dsh-session/invariant` companion registers this package's relational trace checks with `ctx.invariants`: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, provenance, and surface acceptance remain always-on responsibilities of the root session package.
+The optional `@deepseek-ai/dsh-session/invariant` companion registers this package's relational trace checks with `ctx.invariants`: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, cited source-event validation, and surface acceptance remain always-on responsibilities of the root session package.
 
 ## Service: `SessionStore` (ctx key: `sessions`)
 
@@ -36,8 +36,8 @@ The store pairs announced creation with disposal, publishes post-commit append n
 
 Plain class (not a Cordis Service). Create live sessions through `ctx.sessions.create()` and detached replay or inspection sessions through `Session.create()`; the detached factory does not publish lifecycle events or bind the session to a fiber.
 
-- `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, complete replacement coverage, and content-only single-result `tool/result` rewrites, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
-- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over the complete identified, frozen messages stored by those entries. Assistant messages preserve provider/model provenance and adapter-private replay state in their model source. A surface rewrite rebuilds the projection; there is no raw-log fallback.
+- `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, cited source-event seqs, complete replacement coverage, and content-only single-result `tool/result` rewrites, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
+- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over the complete identified, frozen messages stored by those entries. Assistant messages preserve the provider and model that produced them plus adapter-private replay state in their model source. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and request checks.
 - `session.surface` exposes the readonly `SessionSurface` view owned by the session's single incremental surface manager; `replaceGeneration` changes on every committed rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
@@ -68,7 +68,7 @@ A `user/message` stores the complete `UserMessage` directly, including the ident
 
 ### Session event vocabulary (`types.ts`)
 
-The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Provider/model/replay provenance rides on `assistant/message`.
+The generated [persistence log event catalog](../../../docs/persistence-catalog.md) enumerates each append-only event type with its payload, surface badge, cited source-event seqs, and declaration site. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Each `assistant/message` records the provider, model, and optional replay state.
 
 Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, bounded recovery's non-surface `llm/retry`, the hook bridges' `hook/*`); merged members appear in the same catalog. A plugin owns the relational invariant for its merged events, including whether a log-only event may appear between turns. A producer that requires durability appends through `Session` and then awaits `ctx.sessions.flush(session)` without fabricating an execution turn.
 
@@ -78,7 +78,7 @@ An interrupted live turn ends with `{ kind: 'aborted', reason: AgentCancelCause
 
 Every `SessionEvent` carries two optional top-level fields (structural metadata):
 
-- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
+- `sourceEventSeqs?: number[]` — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means a legacy or foreign event did not record the source stream; other surface events require a non-empty list when this field is present.
 - `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
 
 ### Metadata types (`types.ts`)
@@ -88,7 +88,7 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 ### Extension points
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model, and assistant messages require provider/model provenance. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
+- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers and assistant messages require provider/model. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
 - Compaction: `dsh-compact-basic` appends a `user/message` replacement for summary checkpoints, while `dsh-compact-tool-result-prune` appends a content-only `tool/result` replacement. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership, replacement validation, and `replaceGeneration`.
 
 ## Model Experience
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index e9d074f52d..e9529b3c91 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -4,7 +4,7 @@
 
 事件溯源的会话日志和内存存储。`Session` 是 agent（智能体）全部交互历史的仅追加真源，LLM（大语言模型）消息历史由它*派生*。原始日志之上维护一个 **surface** 层（产生消息事件的有序投影），以便高效派生和压缩（compaction）。
 
-可选配套入口 `@deepseek-ai/dsh-session/invariant` 将此包的关系轨迹检查注册到 `ctx.invariants`：序号单调递增、轮次／步骤闭合，以及同一步骤内的工具调用／结果配对。加载或重新加载时，它会回放现有会话；存储校验、快照、冻结、溯源信息和 surface 准入仍始终由根会话包负责。
+可选配套入口 `@deepseek-ai/dsh-session/invariant` 将此包的关系轨迹检查注册到 `ctx.invariants`：序号单调递增、轮次／步骤闭合，以及同一步骤内的工具调用／结果配对。加载或重新加载时，它会回放现有会话；存储校验、快照、冻结、被引用的源事件校验和 surface 准入仍始终由根会话包负责。
 
 ## 服务：`SessionStore`（ctx 键：`sessions`）
 
@@ -36,8 +36,8 @@
 
 普通类（不是 Cordis 服务）。活跃会话通过 `ctx.sessions.create()` 创建，脱离态的回放或检查会话通过 `Session.create()` 创建；脱离态工厂不会发布生命周期事件，也不会将会话绑定到 fiber。
 
-- `session.append(type, data, opts?)` 会为持久数据和 surface 元数据制作快照并冻结它们，校验标记形态、溯源信息、替换覆盖完整性，以及仅修改内容的单个 `tool/result` 重写，随后同步提交，再在彼此独立的失败收容下通知观察者。对已附加会话的重入追加会被拒绝，运行时检查也覆盖扩宽后的联合类型和已加载日志。
-- `session.deriveMessages()` 对每个新的 surface 条目只做一次增量投影，并返回一个新数组，其中包含这些条目存储的完整、带标识且冻结的消息。assistant 消息会在其模型来源中保留提供方／模型溯源信息及适配器私有回放状态。surface 重写会重建投影；不存在原始日志回退。
+- `session.append(type, data, opts?)` 会为持久数据和 surface 元数据制作快照并冻结它们，校验标记形态、被引用的源事件 seq、替换覆盖完整性，以及仅修改内容的单个 `tool/result` 重写，随后同步提交，再在彼此独立的失败收容下通知观察者。对已附加会话的重入追加会被拒绝，运行时检查也覆盖扩宽后的联合类型和已加载日志。
+- `session.deriveMessages()` 对每个新的 surface 条目只做一次增量投影，并返回一个新数组，其中包含这些条目存储的完整、带标识且冻结的消息。assistant 消息的模型来源会保留生成该消息的提供方和模型，以及适配器私有回放状态。surface 重写会重建投影；不存在原始日志回退。
 - `session.deriveEventMessage(event)` 是重建和请求检查使用的规范逐事件投影。
 - `session.surface` 暴露只读 `SessionSurface` 视图，由会话唯一的增量 surface 管理器所有；每次提交重写，`replaceGeneration` 都会变化。
 - `session.events` 是按追加失效的缓存冻结快照；已接受事件保持深度冻结。
@@ -68,7 +68,7 @@
 
 ### 会话事件词汇（`types.ts`）
 
-生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记和溯源信息。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。提供方／模型／回放溯源信息随 `assistant/message` 一同保存。
+生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记、被引用的源事件 seq 与声明位置。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。每条 `assistant/message` 都会记录提供方、模型和可选回放状态。
 
 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。
 
@@ -78,7 +78,7 @@
 
 每个 `SessionEvent` 都有两个可选顶层字段（结构元数据）：
 
-- `sourceEventSeqs?: number[]`：溯源信息的源序号（例如 `assistant/chunk` 的序号，它们是 `assistant/message` 的来源；或压缩替换条目背后被遮蔽的条目）。对于 `assistant/message`，存在的 `[]` 记录已知为空的提供方流；省略则表示旧版或其他未记录的溯源信息。其他 surface 事件若有此字段，则要求非空列表。
+- `sourceEventSeqs?: number[]`：被引用为来源的较早事件 seq（例如 `assistant/message` 引用的 `assistant/chunk` seq，或压缩替换条目引用的已遮蔽条目）。对于 `assistant/message`，存在的 `[]` 表示已知提供方流为空；省略则表示旧版或外部事件没有记录源流。其他 surface 事件若有此字段，则要求非空列表。
 - `surfaceOp?: SurfaceOp`：事件进入 surface 的方式。非 surface 事件（边界、分片、用量、错误）不含该字段。
 
 ### 元数据类型（`types.ts`）
@@ -88,7 +88,7 @@
 ### 扩展点
 
 - 持久化插件：订阅 `session/event`（延后写入），并在 `session/flush`（受等待）及 fiber dispose（资源释放）时排空。持久后端读取日志并重新加载到实时会话；这类后端会把元数据 seam（`SessionHeader`、`session.header`）与日志一同存储。
-- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头必须包含提供方／模型，assistant 消息必须包含提供方／模型溯源信息。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
+- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头和 assistant 消息都必须包含提供方／模型。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
 - 压缩：`dsh-compact-basic` 为摘要检查点追加一个替换用 `user/message`，而 `dsh-compact-tool-result-prune` 追加仅修改内容的 `tool/result` 替换。工具配对边界策略及其缓存归 [`dsh-compact` seam](../../compact/compact/README.md) 所有；此包拥有有序 surface 成员关系、替换校验与 `replaceGeneration`。
 
 ## 模型体验
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 3f73242958..1c1d2a3023 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -293,7 +293,7 @@ function assertCurrentLlmShape(event: Record<string, unknown>, index: number): v
 
 const allowedAdapterKeys = new Set(['reasoningEffort', 'maxTokens'])
 
-/** Validate adapter-default provenance imported from a durable request header. */
+/** Validate adapter-default markers imported from a durable request header. */
 function assertAdapterDefaults(
   value: unknown,
   config: Record<string, unknown>,
@@ -592,8 +592,8 @@ export class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
-   *   numbers of events this one derives from). REQUIRED for
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
@@ -607,7 +607,7 @@ export class Session {
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance), or when the candidate violates the
    *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier provenance, positional replacement validity, and complete
+   *   earlier source-event references, positional replacement validity, and complete
    *   shadowed-node coverage). One recursive pass reads, validates, and
    *   copies each nested value once, so a stateful getter cannot supply one value
    *   to validation and another to storage. The event log is the durable source
diff --git a/packages/core/session/src/invariant.ts b/packages/core/session/src/invariant.ts
index f86b43716e..77d2b22ac2 100644
--- a/packages/core/session/src/invariant.ts
+++ b/packages/core/session/src/invariant.ts
@@ -125,7 +125,7 @@ function validateEvent(
       break
     }
     case 'tool/result': {
-      // Session has already validated a provenance-backed content rewrite.
+      // Session has already validated a content rewrite that cites its replaced event.
       // It is durable turn work, not a second execution of the original call.
       if (event.surfaceOp !== 'append') {
         if (trace.openTurn === null) {
diff --git a/packages/core/session/src/repair.ts b/packages/core/session/src/repair.ts
index 1114156c2e..1203bed341 100644
--- a/packages/core/session/src/repair.ts
+++ b/packages/core/session/src/repair.ts
@@ -47,7 +47,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   let openTurn: number | null = null
   let openStep: number | null = null
   // Reset at each turn boundary so earlier calls cannot leak into tail repair.
-  // Assistant blocks register calls; later tool/call events add provenance seqs.
+  // Assistant blocks register calls; later `tool/call` events add their seqs to `sourceEventSeqs`.
   const pendingCalls = new Map<CallId, { step: number; callSeq?: number }>()
   for (const event of events) {
     switch (event.type) {
@@ -76,7 +76,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
         }
         break
       case 'tool/call':
-        // Add the tool/call seq used as provenance on a synthetic result.
+        // Cite the `tool/call` seq from the synthetic result.
         {
           const entry = pendingCalls.get(event.data.callId)
           if (entry) {
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index ad1c4b2ad3..4e2690a227 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -207,7 +207,7 @@ function surfaceOpOf(event: SessionEvent): SurfaceOp | undefined {
   return op
 }
 
-/** Validate provenance against prior log entries and the replacement range. */
+/** Validate cited source-event seqs against prior log entries and the replacement range. */
 function assertProvenance(
   event: SessionEvent,
   shadowedSeqs: readonly number[],
@@ -382,7 +382,7 @@ function applySurfacePlan(
  * Replay a complete session log through the canonical surface fold.
  * @param events - session events in contiguous seq order.
  * @returns detached current sequences and replacement history.
- * @throws when an event violates surface metadata, provenance, range, or tool-result rewrite rules.
+ * @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
  */
 export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult {
   const state = createFoldState()
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index d655c2488e..c1071e1e01 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -345,15 +345,15 @@ export type SurfaceOp =
   | { op: 'replace'; start: number; end: number }
 
 /**
- * Surface placement and provenance for {@link Session.append}. Required on
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
 export interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
-   * Complete known provenance source set. `assistant/message` may use a
+   * Complete set of known source-event seqs. `assistant/message` may use a
    * present empty array for a known empty provider stream; omission means its
-   * provenance was not recorded. Other surface events require a non-empty set
+   * source stream was not recorded. Other surface events require a non-empty set
    * when this field is present.
    */
   sourceEventSeqs?: number[]
@@ -382,11 +382,11 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts
index 9f18e75bbe..9a09cb3489 100644
--- a/packages/core/session/tests/gen-persistence-catalog.spec.ts
+++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts
@@ -95,10 +95,10 @@ describe('gen-persistence-catalog collectLogEvents', () => {
 
   it('extracts a member declaration-merged via the session module', () => {
     const events = collectLogEvents(make({
-      'packages/group/fix/src/types.ts': merge('    /** Merged provenance. */\n    \'fix/merged\': { id: string }'),
+      'packages/group/fix/src/types.ts': merge('    /** Merged event source record. */\n    \'fix/merged\': { id: string }'),
     }))
     expect(events).toHaveLength(1)
-    expect(events[0]).toMatchObject({ name: 'fix/merged', doc: 'Merged provenance.' })
+    expect(events[0]).toMatchObject({ name: 'fix/merged', doc: 'Merged event source record.' })
   })
 
   it('collapses a newline-separated multi-line payload to a valid one-line fragment', () => {
diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts
index 1394db01e3..39f0530874 100644
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -417,7 +417,7 @@ describe('Session', () => {
     }
   })
 
-  it('round-trips adapter-default provenance and rejects invalid durable values', () => {
+  it('round-trips adapter-default markers and rejects invalid durable values', () => {
     const valid = {
       type: 'request/header',
       seq: 0,
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index 4a7de73b03..7c7ca160b6 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -78,8 +78,8 @@ function toolResultEvent(
   }
 }
 
-describe('foldSurface provenance', () => {
-  it('accepts absent or valid provenance and complete replacement coverage', () => {
+describe('foldSurface source-event references', () => {
+  it('accepts absent or valid source-event references and complete replacement coverage', () => {
     const events = [
       provenanceEvent(0, undefined),
       provenanceEvent(1, undefined),
@@ -91,7 +91,7 @@ describe('foldSurface provenance', () => {
     expect(() => foldSurface(events)).not.toThrow()
   })
 
-  it('rejects provenance on a non-surface event', () => {
+  it('rejects source-event references on a non-surface event', () => {
     const event = {
       type: 'turn/start',
       seq: 0,
@@ -102,7 +102,7 @@ describe('foldSurface provenance', () => {
     expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/)
   })
 
-  it('accepts explicit empty provenance on an assistant message', () => {
+  it('accepts an explicit empty source-event list on an assistant message', () => {
     const event = {
       type: 'assistant/message',
       seq: 0,
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 53f11f85a1..80c185d9b3 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: 97aa97c6ca7675ff5b891e62224a4d1d7780ef42
-README.zh.md: 7ecc146e1f47c95b01b47740868a333cee694b59
+README.md: 73c18552baa4b8b68c3d34c2d928d479548180ba
+README.zh.md: 9812fd50b2500b6393c9328ea1c366eb04963e74
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 97aa97c6ca..73c18552ba 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -54,7 +54,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 
 - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically.
 - `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
-- `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Canonical-result provenance belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
+- `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Each canonical result belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
 - `tools/post-execute` may replace presentation content, replace the canonical value, block with feedback, or attach ordered contexts. A definition's optional `finalizeContent` then owns its last content-only invariant across normal results and outer pipeline failures; `tools/result` observes the immutable final outcome. Content replacement is not a confidentiality boundary: block or replace the value when programmatic consumers must not receive it.
 - Exact signatures and ordering live in the generated region of [tools.md](../../../docs/subsystems/tools.md#cordis-surface) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 7ecc146e1f..9812fd50b2 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -54,7 +54,7 @@ tools:
 
 - 工具插件调用 `ctx.tools.register()`：schema 会自动流入组装结果。
 - `tools/pre-execute` 是可重排的允许／拒绝／询问门禁；`ctx.tools.guard()` 在其后添加单调的拥有方策略。
-- `tools/execute` 会环绕包装规范化后的规范分发，以支持超时、重试或指标采集。包装层只能替换操作信号；包装层生成的成功结果会根据已解析工具的输出声明进行规范化。规范结果的来源属于一个不可变分发 token，因此，来自其他调用或工具的缓存结果会根据当前声明重新验证。
+- `tools/execute` 会环绕包装规范化后的规范分发，以支持超时、重试或指标采集。包装层只能替换操作信号；包装层生成的成功结果会根据已解析工具的输出声明进行规范化。每个规范结果属于一个不可变分发 token，因此来自其他调用或工具的缓存结果会根据当前声明重新验证。
 - `tools/post-execute` 可以替换呈现内容、替换规范值、通过反馈阻止，或附加有序上下文。随后，定义可选的 `finalizeContent` 会在普通结果和外层流水线失败中维护其最终、仅涉及内容的不变式；`tools/result` 观测不可变的最终结果。内容替换不是保密边界：当编程消费方不得接收某个值时，应阻止或替换该值。
 - 确切签名与顺序位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块和[流水线](../../../docs/tool-execution-pipeline.md)中。
 - MCP 服务器：每个服务器使用一个插件；发现工具后，使用服务器的 schema 调用 `ctx.tools.register()`。
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 15588e40b9..ed30b896bf 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -382,7 +382,7 @@ function daclAcePolicy(descriptor: Buffer): string[] {
   for (let index = 0; index < aceCount; index++) {
     const size = descriptor.readUInt16LE(offset + 2)
     const ace = Buffer.from(descriptor.subarray(offset, offset + size))
-    // INHERITED_ACE records provenance, not the entry's access policy.
+    // INHERITED_ACE records which parent ACE produced this entry, not the entry's access policy.
     ace.writeUInt8(ace.readUInt8(1) & ~0x10, 1)
     const key = ace.toString('hex')
     if (!seen.has(key)) {
diff --git a/packages/goal/tool-goal/README.i18n.yaml b/packages/goal/tool-goal/README.i18n.yaml
index 3f4131c2b1..5f12f06484 100644
--- a/packages/goal/tool-goal/README.i18n.yaml
+++ b/packages/goal/tool-goal/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/goal/tool-goal/README.md
-README.md: c8c1ab84c237ee34db7abcd63962476693b5e56c
-README.zh.md: 7120280fcaa8710e5bab819a0539c926ab4e424a
+README.md: b93da1ced1cfbea0b4cdc2a7e253b9a515e75b21
+README.zh.md: 2c813c6406b170f93ee0b90939904d3570425ec3
diff --git a/packages/goal/tool-goal/README.md b/packages/goal/tool-goal/README.md
index c8c1ab84c2..b93da1ced1 100644
--- a/packages/goal/tool-goal/README.md
+++ b/packages/goal/tool-goal/README.md
@@ -73,7 +73,7 @@ Schemas are prefix-stable while their definitions and visibility are unchanged.
 
 ## Known Limitations and Deferred Work
 
-- **Semantic intent remains model judgment** — execution can prove direct human provenance, not whether a request is substantial enough to merit a goal.
+- **Semantic intent remains model judgment** — execution can prove that the current turn contains a direct human message, not whether the request is substantial enough to merit a goal.
 - **Same-condition blocking remains model judgment** — the runtime enforces distinct admitted-round count, not semantic equivalence of obstacles; an independent evaluator is deferred.
 - **No scheduling or direct human rendering** — these tools mutate state only; the same-session driver and [`dsh-command-goal`](../command-goal/README.md) are independent consumers of the same domain.
 - **Goal-round authority requires a driver** — the autonomous `complete`/`blocked` path is dormant unless a continuation driver admits goal-sourced user turns; mounting this tool package alone does not create them.
diff --git a/packages/goal/tool-goal/README.zh.md b/packages/goal/tool-goal/README.zh.md
index 7120280fca..2c813c6406 100644
--- a/packages/goal/tool-goal/README.zh.md
+++ b/packages/goal/tool-goal/README.zh.md
@@ -73,7 +73,7 @@ schema 的定义与可见性不变时，前缀保持稳定。调用和结果会
 
 ## 已知限制与暂缓事项
 
-- **语义意图仍由模型判断**：执行只能证明人类直接来源，无法证明请求是否足够重大而值得创建 goal。
+- **语义意图仍由模型判断**：执行只能证明当前轮次包含一条人类直接发送的消息，无法证明请求是否足够重大而值得创建 goal。
 - **阻塞条件是否相同仍由模型判断**：运行时强制统计互不重复的已准入 Goal Round，而不判断障碍在语义上是否等价；独立评估器的实现暂缓。
 - **不负责调度或直接面向人类呈现**：这些工具只变更状态；同会话驱动器与 [`dsh-command-goal`](../command-goal/README.md) 是同一领域的独立消费方。
 - **Goal Round 权限需要驱动器**：除非续行驱动器准入 goal 来源的用户轮次，否则自主 `complete`／`blocked` 路径不会启用；只挂载这个包不会创建这些轮次。
diff --git a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts
index 40382218d8..20cd9a0104 100644
--- a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts
+++ b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts
@@ -330,7 +330,7 @@ describe('fold onto the downstream decision', () => {
 
     const found = reminders(agent)
     expect(found).toHaveLength(3)
-    // Only the repeated call adds guard context; downstream provenance survives.
+    // Only the repeated call adds guard context; downstream source fields survive.
     expect(found[0]!.text).toBe('downstream-ctx')
     expect(found[0]!.source).toEqual({ kind: 'plugin', plugin: 'test' })
     expect(found[1]!.text).toContain('repeating the exact same tool call')
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index f082be00ef..b7c8ec3ee8 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
-README.md: e807d9597eb5f811195bab9a0ad2b30b545e1205
-README.zh.md: c206224b45a5b12a7aa85d24de301f3d949f294b
+README.md: 797d15c357bd26e0db072b30b61c251005021905
+README.zh.md: 8a96cd2f1f91ad2d7a12fc15ffc06ea0c2c1d80f
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index e807d9597e..797d15c357 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -29,7 +29,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 
 Declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT a `SurfaceEventType`, no `surfaceOp`): `hook/invoked` (a hook command ran) and `hook/result` (its outcome, paired by `handlerId`, with `appendHookResult` owning the decision rule). Payloads and per-event JSDoc are in the generated [persistence log event catalog](../../../docs/persistence-catalog.md); `stderrSummary` is truncated to the record's `stderrSummaryMaxChars` (the bridge's config, reference default `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500; omitted when empty).
 
-Hook provenance records must sit inside an open turn. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that owner-defined relation by construction. `SessionStart` runs before turn 1 and gets no `hook/*` record; its allowed context remains pending in the inbox until a waking delivery opens a turn — see the hooks Agent Note.
+Hook invocation/result records must sit inside an open turn. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that owner-defined relation by construction. `SessionStart` runs before turn 1 and gets no `hook/*` record; its allowed context remains pending in the inbox until a waking delivery opens a turn — see the hooks Agent Note.
 
 ## Model Experience
 
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index c206224b45..8a96cd2f1f 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -29,7 +29,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 
 通过 declaration merging 合并到 `SessionEventMap`（仅日志，与 `compact/*` 相同；不是 `SurfaceEventType`，没有 `surfaceOp`）：`hook/invoked`（hook 命令已运行）与 `hook/result`（其结果，按 `handlerId` 配对，决策规则由 `appendHookResult` 负责）。Payload 与每事件 JSDoc 位于生成的 [持久化日志事件目录](../../../docs/persistence-catalog.md)；`stderrSummary` 会截断到记录的 `stderrSummaryMaxChars`（桥接配置，参考默认值 `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500；为空时省略）。
 
-Hook 溯源记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足这条由所有者定义的关系。`SessionStart` 在轮次 1 之前运行，因此没有 `hook/*` 记录；其获准的上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次，详见 hooks Agent Note。
+Hook 调用／结果记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足这条由所有者定义的关系。`SessionStart` 在轮次 1 之前运行，因此没有 `hook/*` 记录；其获准的上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次，详见 hooks Agent Note。
 
 ## 模型体验
 
diff --git a/packages/hooks/hook-protocol/src/events.ts b/packages/hooks/hook-protocol/src/events.ts
index 025250cdac..3f1a827ecc 100644
--- a/packages/hooks/hook-protocol/src/events.ts
+++ b/packages/hooks/hook-protocol/src/events.ts
@@ -68,7 +68,7 @@ export function summarizeStderr(stderr: string, maxChars: number): string | unde
 }
 
 /**
- * Append a `hook/invoked` provenance event to `session`.
+ * Append a `hook/invoked` event naming the handler and hook point to `session`.
  * @param session - the session whose open turn records the event.
  * @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
  */
diff --git a/packages/hooks/hook-protocol/src/invariant.ts b/packages/hooks/hook-protocol/src/invariant.ts
index 9bc5e6a1e1..8a7c7338c3 100644
--- a/packages/hooks/hook-protocol/src/invariant.ts
+++ b/packages/hooks/hook-protocol/src/invariant.ts
@@ -1,4 +1,4 @@
-/** Package-owned hook provenance-stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
+/** Package-owned hook invocation/result stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
 
 import type { Context } from 'cordis'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
@@ -98,7 +98,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     }
     if (event.type !== 'hook/invoked' && event.type !== 'hook/result') return
     const candidate = staged.get(event)
-    /* v8 ignore next -- internal/dispatch stages every hook provenance event */
+    /* v8 ignore next -- internal/dispatch stages every hook invocation/result event */
     if (candidate === undefined || candidate.session !== session) return fail('hook event published without pre-commit validation')
     staged.delete(event)
     applyHookTransition(trace.pending, candidate.transition)
diff --git a/packages/hooks/hook-protocol/src/types.ts b/packages/hooks/hook-protocol/src/types.ts
index 6a3dd616f3..1be2b7cb04 100644
--- a/packages/hooks/hook-protocol/src/types.ts
+++ b/packages/hooks/hook-protocol/src/types.ts
@@ -8,7 +8,7 @@
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /**
-     * A hook command was invoked at a hook point — log-only provenance (like
+     * A hook command was invoked at a hook point — a log-only record (like
      * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
      * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
      * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
@@ -43,7 +43,7 @@ declare module '@deepseek-ai/dsh-session' {
 /**
  * The bridge that ran a hook — the CC bridge stamps `'claude'`, the Codex
  * bridge `'codex'`. A native plugin on the interception seams is not a bridge
- * and writes no `hook/*` provenance (see the interception-seams Agent Note).
+ * and writes no `hook/*` invocation/result records (see the interception-seams Agent Note).
  */
 export type HookDialect = 'claude' | 'codex'
 
diff --git a/packages/hooks/hook-protocol/tests/invariant.spec.ts b/packages/hooks/hook-protocol/tests/invariant.spec.ts
index f1792be67f..94e5b57847 100644
--- a/packages/hooks/hook-protocol/tests/invariant.spec.ts
+++ b/packages/hooks/hook-protocol/tests/invariant.spec.ts
@@ -45,7 +45,7 @@ describe('hook-protocol invariants', () => {
     session.append('hook/result', result())
   })
 
-  it('rebuilds pending hook provenance from an existing session', async () => {
+  it('rebuilds pending hook invocations from an existing session', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create()
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index 77b3a2711b..e42f875f13 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -195,7 +195,7 @@ export function apply(ctx: Context, config: Config): void {
     return createUserMessage({ content, source: PLUGIN_SOURCE })
   }
 
-  /** Prepend one context without flattening downstream provenance or metadata. */
+  /** Prepend one context without flattening source fields or other downstream metadata. */
   function prependContext(ours: UserMessage, theirs: UserMessage[] | undefined): UserMessage[] {
     return [ours, ...theirs ?? []]
   }
diff --git a/packages/hooks/hooks-claude/src/invariant.ts b/packages/hooks/hooks-claude/src/invariant.ts
index 18bc942e9f..d7908419d4 100644
--- a/packages/hooks/hooks-claude/src/invariant.ts
+++ b/packages/hooks/hooks-claude/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
- * their cross-event provenance relation.
+ * which invocation event each result cites.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 304deef63c..873b1e35ae 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -107,7 +107,7 @@ export function apply(ctx: Context, config: Config): void {
   /**
    * Run and fold one configured Codex hook point.
    *
-   * A supplied turn records the hook provenance pair inside that open turn.
+   * A supplied turn records the hook invocation/result pair inside that open turn.
    * Detached lifecycle points omit it.
    */
   async function runPoint(
@@ -177,7 +177,7 @@ export function apply(ctx: Context, config: Config): void {
     return createUserMessage({ content, source: PLUGIN_SOURCE })
   }
 
-  /** Prepend one context without flattening downstream provenance or metadata. */
+  /** Prepend one context without flattening source fields or other downstream metadata. */
   function prependContext(ours: UserMessage, theirs: UserMessage[] | undefined): UserMessage[] {
     return [ours, ...theirs ?? []]
   }
diff --git a/packages/hooks/hooks-codex/src/invariant.ts b/packages/hooks/hooks-codex/src/invariant.ts
index 5f0f6ed173..c3eacb7ab0 100644
--- a/packages/hooks/hooks-codex/src/invariant.ts
+++ b/packages/hooks/hooks-codex/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
- * their cross-event provenance relation.
+ * which invocation event each result cites.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index b994e46b03..3069ec7948 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 5e3a6cf57ce3fe11b3f31d7f68055f34708d74eb
-README.zh.md: b96487d6d67deb8a0a6ddf4a92784f31dafb3e89
+README.md: 9b430fca1c2352334e6428eb37b80726a4e02c02
+README.zh.md: c36a88b44348d0054e71ea9d796291b91fadbf20
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 5e3a6cf57c..9b430fca1c 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -24,7 +24,7 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc
 
 Question responses are validated against their pending request before the first answer claims it. A multi-select item may carry both requested option labels in `selected` and non-empty `custom` text; a single-select item must use one or the other. Duplicate labels, unknown labels, mismatched ids, incomplete batches, and empty custom text are rejected as `bad-response`.
 
-`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
+`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only `compact/summary` record on the same page as the replacement that cites it.
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index b96487d6d6..c36a88b443 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -24,7 +24,7 @@ Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志 `compact/summary` 记录与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 01b792353d..a4ce497c1d 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -109,7 +109,7 @@ function isAborted(signal: AbortSignal): boolean {
  * backwards from the window tail. Replacement copies never entered the
  * conversation a reader sees — they restate a shadowed range for the model
  * alone — so they consume no quota; the page stays one contiguous raw range,
- * which keeps a compaction's log-only provenance on the same page as its
+ * which keeps a compaction's log-only `compact/summary` record on the same page as its
  * replacement. The cut is the starting seq of the oldest message group (chunks
  * group via sourceEventSeqs — never cut mid-message). The tail page naturally
  * includes the in-progress partial.
@@ -1508,7 +1508,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             // Host visibility is the authorization boundary. Consume the
             // provider's globally ranked stream rather than binding every
             // visible id into one SQLite statement, then re-check complete
-            // provenance before emitting any snippet.
+            // provider id before emitting any snippet.
             for (const hit of page.items) {
               if (authorized.length > SESSION_SEARCH_RESULT_LIMIT) continue
               if (
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index a5fc8fffad..0a4da455a2 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -216,7 +216,7 @@ export interface SessionsApi {
    * Reads a window of history events; page boundaries align to append-origin message
    * boundaries: one page = all raw events owned by a whole number of such messages (including
    * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no
-   * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail
+   * `maxMessages`, so a compaction's `compact/summary` record stays on the page of its replacement. The tail
    * page (beforeSeq absent) additionally carries the in-flight
    * partial — chunk events already emitted for the last unfinalized message.
    * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
diff --git a/packages/host/apiproxy/tests/api-proxy-search.spec.ts b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
index 0220f4804b..8b2e030509 100644
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -165,7 +165,7 @@ describe('session.search', () => {
     expect(searchSessions).not.toHaveBeenCalled()
   })
 
-  it('rejects snippets whose provider provenance violates the Host filters', async () => {
+  it('rejects snippets whose recorded provider violates the Host filters', async () => {
     const ctx = await baseContext()
     const visible = hit('visible')
     ctx.sessions.create(visible.header.id, { meta: visible.header })
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 9810ff5cb8..8b82a99d27 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -236,7 +236,7 @@ describe('mux live view computation', () => {
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
   })
 
-  it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
+  it('counts only append-origin messages toward maxMessages and keeps each compaction summary with its replacement', async () => {
     const { ctx } = await harness()
     const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
@@ -247,7 +247,7 @@ describe('mux live view computation', () => {
     const third = appendUserText(session, 'second prompt')
     appendAssistantText(session, 'second reply', 2)
     const shadowed = [...session.surface.nodes]
-    // A compaction transaction: log-only provenance immediately followed by the
+    // A compaction transaction: a log-only summary record immediately followed by the
     // replacement that shadows the range.
     const summary = appendExtension(session, 'compact/summary', {
       summary: [{ type: 'text', text: 'summary' }],
@@ -277,7 +277,7 @@ describe('mux live view computation', () => {
     expect(messages.map(event => event.seq)).toEqual([third.seq, third.seq + 1, third.seq + 3])
     expect(page.some(event => event.seq === first.seq)).toBe(false)
     expect(response.result.value.hasMore).toBe(true)
-    // The range stays contiguous, so the checkpoint's provenance is readable on
+    // The range stays contiguous, so the checkpoint's summary record is readable on
     // the same page as the checkpoint itself.
     const summaryIndex = page.findIndex(event => event.seq === summary.seq)
     expect(summaryIndex).toBeGreaterThan(-1)
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 64a9f8e8c8..94c4861e66 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -18,7 +18,7 @@ const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u
 
 /**
  * Producer record for one command invocation (the `command/run` event's
- * provenance slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
+ * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
  * shape; minimal today because every executor caller is a human-facing UI
  * surface dispatching a human-typed line, so the sole variant is `user`.
  */
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 37ea49150b..eea304b414 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: eb67ce889193aadbd694d7aae53e47c7d20703be
-README.zh.md: 8b8e5e6a219841d700db7161a7352a1880c41165
+README.md: 4ad669344056a8290057cd39cbde56b0a2d80ba4
+README.zh.md: 96e1ef2dd3219e8b1fe0d5afbf5c784d9c3e42d5
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index eb67ce8891..4ad6693440 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -133,9 +133,9 @@ Credentials never enter that collection. The harness resolves a route's key thro
 
 The selected model descriptor supplies the protocol implementation. This includes native API differences such as OpenAI models whose descriptor uses the Responses API rather than Chat Completions; the harness adapter does not hardcode endpoint selection by model name.
 
-Successful assistant responses store a versioned, lossless-JSON replay state beside their durable provider/model provenance. At request time, `LlmService` passes replay state only when the historical provider route and target provider route are currently owned by this same `PiAiAdapter` instance. The adapter validates the state and restores pi-ai response ids and provider signatures even when the target provider or model changes; pi-ai then decides which metadata its target API can reuse. History without replay state is translated as foreign provider-neutral content and never impersonates a native pi-ai response.
+Successful assistant responses store a versioned, lossless-JSON replay state beside the provider and model that produced them. At request time, `LlmService` passes replay state only when the historical provider route and target provider route are currently owned by this same `PiAiAdapter` instance. The adapter validates the state and restores pi-ai response ids and provider signatures even when the target provider or model changes; pi-ai then decides which metadata its target API can reuse. History without replay state is translated as foreign provider-neutral content and never impersonates a native pi-ai response.
 
-If a listener rewrites assembled assistant content, the loop drops replay state before logging the message because its provider metadata no longer describes the content. Invalid versions, malformed metadata, provenance provider/model mismatches, and content/block mismatches fail explicitly with `LlmError('INVALID_REPLAY_STATE')`.
+If a listener rewrites assembled assistant content, the loop drops replay state before logging the message because its provider metadata no longer describes the content. Invalid versions, malformed metadata, provider/model mismatches between the message and replay state, and content/block mismatches fail explicitly with `LlmError('INVALID_REPLAY_STATE')`.
 
 ## Vocabulary differences
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 8b8e5e6a21..96e1ef2dd3 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -133,9 +133,9 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 所选模型 descriptor 提供协议实现。这包括原生 API 差异，例如 descriptor 使用 Responses API 而非 Chat Completions 的 OpenAI 模型；harness 适配器不会按模型名称硬编码端点选择。
 
-成功的 assistant 响应会在自身持久提供方／模型溯源旁存储经版本化的无损 JSON 回放状态。请求时，`LlmService` 只有在历史提供方路由与目标提供方路由当前由同一个 `PiAiAdapter` 实例拥有时，才会传递回放状态。即使目标提供方或模型改变，适配器也会验证状态并恢复 pi-ai 响应 id 与提供方 signature；随后由 pi-ai 判定目标 API 可以复用哪些元数据。没有回放状态的历史会被转换为外来的、与提供方无关的内容，绝不伪装为原生 pi-ai 响应。
+成功的 assistant 响应会将经版本化的无损 JSON 回放状态与生成该响应的提供方和模型一同存储。请求时，`LlmService` 只有在历史提供方路由与目标提供方路由当前由同一个 `PiAiAdapter` 实例拥有时，才会传递回放状态。即使目标提供方或模型改变，适配器也会验证状态并恢复 pi-ai 响应 id 与提供方 signature；随后由 pi-ai 判定目标 API 可以复用哪些元数据。没有回放状态的历史会被转换为外来的、与提供方无关的内容，绝不伪装为原生 pi-ai 响应。
 
-如果 listener 改写已组装 assistant 内容，loop 会在记录消息前丢弃回放状态，因为其提供方元数据不再描述该内容。无效版本、格式错误元数据、溯源提供方／模型不匹配，以及内容／块不匹配都会显式以 `LlmError('INVALID_REPLAY_STATE')` 失败。
+如果 listener 改写已组装 assistant 内容，loop 会在记录消息前丢弃回放状态，因为其提供方元数据不再描述该内容。无效版本、格式错误元数据、消息与回放状态之间的提供方／模型不匹配，以及内容／块不匹配都会显式以 `LlmError('INVALID_REPLAY_STATE')` 失败。
 
 ## 词汇差异
 
diff --git a/packages/llm/llm-pi-ai/tests/convert.spec.ts b/packages/llm/llm-pi-ai/tests/convert.spec.ts
index d125578b7f..b71d67b6c7 100644
--- a/packages/llm/llm-pi-ai/tests/convert.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/convert.spec.ts
@@ -102,7 +102,7 @@ describe('toPiContext', () => {
     expect((context.messages[0] as AssistantMessage).stopReason).toBe('stop')
   })
 
-  it('preserves model provenance for foreign assistant messages without replay state', () => {
+  it('preserves provider and model for foreign assistant messages without replay state', () => {
     const context = toPiContext({
       provider: 'openai',
       model: 'new-model',
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 4b1eda16c0..c4e8277b42 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: ddbc2ea482ca0848fb0ee0813839cf5ff1829bcc
-README.zh.md: 0ebb99c6e3743b881905110985575d348f1c7601
+README.md: a437a689e934701b925dbf5a39a912c3af7dd46b
+README.zh.md: 7ed0c9c8a93e102b3d350be48be3a07e30011582
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index ddbc2ea482..a437a689e9 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -21,7 +21,7 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` Discover the models one registered provider currently advertises.
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` Resolve validated exact-model identity plus available context, output-default, and reasoning metadata from the owning adapter, with optional cancellation for asynchronous adapters.
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` Validate an explicit effort and materialize adapter-configured call defaults without clamping.
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus detached context metadata and adapter-default provenance in one exact-model lookup, then capture its current adapter registration and immutable retry policy as one cancellable, one-shot call.
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus detached context metadata and markers for fields supplied by adapter defaults in one exact-model lookup, then capture its current adapter registration and immutable retry policy as one cancellable, one-shot call.
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
 `LlmService` normalizes failures from final adapter selection, synchronous dispatch, iterator construction, and iteration into the stream protocol's single terminal form: `finish { kind: 'error' | 'aborted', failure }`. A failure after partial deltas may leave content blocks open; consumers discard that incomplete output. Errors from `llm/stream` middleware, nested calls, adapter cleanup, and downstream consumers remain thrown because they are plugin or consumer failures rather than model-request outcomes. A prepared call exposes the immutable retry policy captured with its exact adapter registration; a route handled entirely by middleware has no serving policy.
@@ -51,13 +51,13 @@ Exact-model metadata is a separate correctness query, not a catalog decoration o
 
 `Message` is the shared immutable value used by delivery, durable history, and model requests. Every message has a required `MessageId`, role, content, and typed source from creation onward. `createMessage(input)` mints the identity and returns a detached deep-frozen value; `createUserMessage({ content, source })` fixes the user role; `createAssistantMessage({ content, source })` fixes the assistant role and model source kind; `createToolResultMessage({ callId, content, isError })` fixes the user role and couples the tool source to its result block; `freezeMessage(message)` imports an identity that already exists and never replaces it. Message rewrites preserve the identity and produce another frozen value. Browser code imports these value constructors from the dependency-minimal `@deepseek-ai/dsh-llm/message` entry instead of the service-bearing package root.
 
-Message content is an array of typed blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages use a model source carrying provider/model provenance and optional adapter-private replay state. Before dispatch, `LlmService` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
+Message content is an array of typed blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages use a model source carrying the provider and model that produced them plus optional adapter-private replay state. Before dispatch, `LlmService` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
 
 Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). Every adapter outcome reaches consumers as one terminal `finish`; operational failure uses its `error` or `aborted` reason rather than throwing across the stream API. `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages.
 
 ### Call configuration (`call-config.ts`)
 
-`LlmCallConfig` is the provider, model, optional adapter-owned reasoning effort, and sampling scalars of one conversation's requests (`provider`, `model`, `reasoningEffort`, `temperature`, `maxTokens`, `stop` — each mapping 1:1 onto the same-named `GenerateOptions` field). It is per-conversation state recorded in the session log as part of the request header (see the dsh-session `request/header` events), never a silently-adjustable per-call knob: the `agent/request` waterfall proposes a replacement, `prepareCall()` validates it and materializes adapter defaults under the turn signal, and the loop logs the effective value plus adapter-default provenance before using the prepared call's registration-bound stream. The next proposal omits marked defaults so a changed route resolves its own values; unmarked explicit fields persist. `callConfigEquals(a, b)` is the field-wise real-change detector; `deepFreeze(value)` is the ownership helper the loop applies to every built request before dispatch (`llm/stream` listeners and adapters read, never rewrite). `markAgentLoopRequest()` gives that exact object process-local loop provenance, and `isAgentLoopRequest()` lets observers distinguish it from independently logged auxiliary calls that may also be frozen and session-associated. `GenerateOptions.purpose` classifies logged auxiliary compaction and session-title calls so adapters can apply purpose-specific transport policy without changing ordinary conversation requests.
+`LlmCallConfig` is the provider, model, optional adapter-owned reasoning effort, and sampling scalars of one conversation's requests (`provider`, `model`, `reasoningEffort`, `temperature`, `maxTokens`, `stop` — each mapping 1:1 onto the same-named `GenerateOptions` field). It is per-conversation state recorded in the session log as part of the request header (see the dsh-session `request/header` events), never a silently-adjustable per-call knob: the `agent/request` waterfall proposes a replacement, `prepareCall()` validates it and materializes adapter defaults under the turn signal, and the loop logs the effective value plus markers for fields supplied by adapter defaults before using the prepared call's registration-bound stream. The next proposal omits marked defaults so a changed route resolves its own values; unmarked explicit fields persist. `callConfigEquals(a, b)` is the field-wise real-change detector; `deepFreeze(value)` is the ownership helper the loop applies to every built request before dispatch (`llm/stream` listeners and adapters read, never rewrite). `markAgentLoopRequest()` marks that exact object as created by the process-local agent loop, and `isAgentLoopRequest()` lets observers distinguish it from independently logged auxiliary calls that may also be frozen and session-associated. `GenerateOptions.purpose` classifies logged auxiliary compaction and session-title calls so adapters can apply purpose-specific transport policy without changing ordinary conversation requests.
 
 ### App attribution (`attribution.ts`)
 
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 0ebb99c6e3..7ed0c9c8a9 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -21,7 +21,7 @@
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` 发现某个已注册提供方当前公布的模型。
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` 从拥有精确路由的适配器解析经校验的确切模型身份，以及可用上下文、输出默认值和推理（reasoning）元数据；异步适配器可选地支持取消。
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` 校验显式推理强度，并填入适配器配置的调用默认值，但不自动调整。
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置、脱耦的上下文元数据与适配器默认值溯源，再将当前适配器注册和不可变重试策略捕获为一次可取消、一次性调用。
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置、脱耦的上下文元数据以及标明哪些字段由适配器默认值填入的标记，再将当前适配器注册和不可变重试策略捕获为一次可取消、一次性调用。
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` 将一次模型调用流式输出为原始分片（token 级增量）。消费方使用 `BlockAssembler` 将分片组装为块／消息。
 
 `LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
@@ -51,13 +51,13 @@
 
 `Message` 是投递、持久历史和模型请求共享的不可变值。每条消息从创建起都必须具有 `MessageId`、角色、内容和带类型的来源。`createMessage(input)` 生成标识，并返回与输入分离且深度冻结的值；`createUserMessage({ content, source })` 固定 user 角色；`createAssistantMessage({ content, source })` 固定 assistant 角色与模型来源类别；`createToolResultMessage({ callId, content, isError })` 固定 user 角色，并将工具来源与其结果块耦合；`freezeMessage(message)` 导入已有标识，绝不将其替换。改写消息时会保留标识，并产生另一个冻结值。浏览器端代码会从依赖最少的 `@deepseek-ai/dsh-llm/message` 入口导入这些值构造函数，而不是从包含服务的包根入口导入。
 
-消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带提供方／模型溯源与可选适配器私有回放状态。dispatch 前，`LlmService` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。
+消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带生成该消息的提供方和模型，以及可选的适配器私有回放状态。dispatch 前，`LlmService` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。
 
 流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 到达消费方；运行故障使用其 `error` 或 `aborted` 原因，而不会跨流 API 抛出。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。
 
 ### 调用配置（`call-config.ts`）
 
-`LlmCallConfig` 是一个会话中各次请求的提供方、模型、可选的适配器持有推理强度和采样标量（`provider`、`model`、`reasoningEffort`、`temperature`、`maxTokens`、`stop`，每个都与同名 `GenerateOptions` 字段 1:1 映射）。它是作为请求标头一部分记录在会话日志中的每会话状态（见 dsh-session `request/header` 事件），绝不是可静默调整的每次调用旋钮：`agent/request` waterfall 会提议替换，`prepareCall()` 在轮次 signal 控制下校验它并填入适配器默认值，loop 随后记录生效值及适配器默认值来源，再使用已准备调用中与注册绑定的流。下一次提议会省略带标记的默认值，使变更后的路由解析自身的值；未带标记的显式字段会保留。`callConfigEquals(a, b)` 是逐字段真实变更检测器；`deepFreeze(value)` 是 loop 在 dispatch 前对每个已构建请求应用的所有权 helper（`llm/stream` listener 与适配器只读，绝不改写）。`markAgentLoopRequest()` 为该精确对象添加进程本地 loop 溯源，`isAgentLoopRequest()` 让观测方可以将其与同样可能冻结并关联会话、但独立记录的辅助调用区分。`GenerateOptions.purpose` 对已记录辅助压缩与会话标题调用分类，让适配器可以应用目的特定传输策略，而不改变普通会话请求。
+`LlmCallConfig` 是一个会话中各次请求的提供方、模型、可选的适配器持有推理强度和采样标量（`provider`、`model`、`reasoningEffort`、`temperature`、`maxTokens`、`stop`，每个都与同名 `GenerateOptions` 字段 1:1 映射）。它是作为请求标头一部分记录在会话日志中的每会话状态（见 dsh-session `request/header` 事件），绝不是可静默调整的每次调用旋钮：`agent/request` waterfall 会提议替换，`prepareCall()` 在轮次 signal 控制下校验它并填入适配器默认值，loop 随后记录生效值以及标明哪些字段由适配器默认值填入的标记，再使用已准备调用中与注册绑定的流。下一次提议会省略带标记的默认值，使变更后的路由解析自身的值；未带标记的显式字段会保留。`callConfigEquals(a, b)` 是逐字段真实变更检测器；`deepFreeze(value)` 是 loop 在 dispatch 前对每个已构建请求应用的所有权 helper（`llm/stream` listener 与适配器只读，绝不改写）。`markAgentLoopRequest()` 将该精确对象标记为由进程本地 agent loop 创建，`isAgentLoopRequest()` 让观测方可以将其与同样可能冻结并关联会话、但独立记录的辅助调用区分。`GenerateOptions.purpose` 对已记录辅助压缩与会话标题调用分类，让适配器可以应用目的特定传输策略，而不改变普通会话请求。
 
 ### 应用归因（`attribution.ts`）
 
diff --git a/packages/llm/llm/src/call-config.ts b/packages/llm/llm/src/call-config.ts
index 848654ad3b..6bf108dc1a 100644
--- a/packages/llm/llm/src/call-config.ts
+++ b/packages/llm/llm/src/call-config.ts
@@ -61,7 +61,7 @@ export function callConfigEquals(a: LlmCallConfig, b: LlmCallConfig): boolean {
 /**
  * Mark one exact request object as assembled by dsh-agent-loop.
  * @param request - loop-owned request envelope before LLM dispatch.
- * @returns the same request object with process-local loop provenance.
+ * @returns the same request object marked as created by the process-local agent loop.
  */
 export function markAgentLoopRequest<T extends GenerateOptions>(request: T): T {
   AGENT_LOOP_REQUESTS.add(request)
diff --git a/packages/llm/llm/src/message.ts b/packages/llm/llm/src/message.ts
index 7db1f855a8..c4032f5294 100644
--- a/packages/llm/llm/src/message.ts
+++ b/packages/llm/llm/src/message.ts
@@ -4,7 +4,7 @@ import { MessageId, type CallId } from './brand.ts'
 import { deepFreeze } from './call-config.ts'
 import type { ContentBlock, ToolResultBlock } from './types.ts'
 
-/** Provider ownership and adapter-private replay data for an assistant message. */
+/** Provider/model identity and adapter-private replay data for an assistant message. */
 export interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -31,7 +31,7 @@ export interface ToolMessageSource {
 
 /**
  * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
+ * the producer beside the source fields it supplied.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
@@ -133,7 +133,7 @@ export interface Message {
   readonly role: 'system' | 'user' | 'assistant'
   /** Exact model-facing blocks. */
   readonly content: ContentBlock[]
-  /** Required producer provenance. */
+  /** Required source fields supplied by the producer. */
   readonly source: MessageSource
 }
 
@@ -200,7 +200,7 @@ export function createUserMessage<T extends NewUserMessage>(
 
 /**
  * Create one identified model-produced assistant message and freeze it before publication.
- * @param input - complete content and model provenance for a new assistant message.
+ * @param input - complete content plus the provider, model, and optional replay state for a new assistant message.
  * @returns an immutable assistant message with fixed role/source tags and a fresh stable identity.
  */
 export function createAssistantMessage(
diff --git a/packages/llm/llm/tests/message.spec.ts b/packages/llm/llm/tests/message.spec.ts
index c906c97e8b..846d37c9df 100644
--- a/packages/llm/llm/tests/message.spec.ts
+++ b/packages/llm/llm/tests/message.spec.ts
@@ -74,7 +74,7 @@ describe('message construction', () => {
     expect(Object.isFrozen(message.source)).toBe(true)
   })
 
-  it('couples tool-result content and provenance to one call identity', () => {
+  it('couples tool-result content and its cited call seq to one call identity', () => {
     const callId = CallId('call-1')
     const message = createToolResultMessage({
       callId,
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index 990d1c38ea..414c50cd28 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -1046,7 +1046,7 @@ describe('LlmService', () => {
     })
   })
 
-  it('strips replay state but preserves provenance when the target uses a different adapter instance', async () => {
+  it('strips replay state but preserves provider and model when the target uses a different adapter instance', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     ctx.llm.registerAdapter(['historical'], new RecordingAdapter(SCRIPT))
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index 5b2d79f7fb..9b68fa047a 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/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/llm/token-meter/README.md
-README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
-README.zh.md: e3908ecea17b16669458f89a6359a432f5b24c0c
+README.md: 929d0322f6268562a10b9ab715cc0330800966b5
+README.zh.md: 40cea07c7dea20d0af9bf67ade2cb4164f7aed08
diff --git a/packages/llm/token-meter/README.md b/packages/llm/token-meter/README.md
index 8f868f25f3..929d0322f6 100644
--- a/packages/llm/token-meter/README.md
+++ b/packages/llm/token-meter/README.md
@@ -17,9 +17,9 @@ The estimator has no settings. It intentionally uses one fixed heuristic: four c
 
 `measure()` synchronizes once and returns one detached, deeply immutable snapshot. `totalTokens` is request-and-response pressure, while `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override affects pressure fields only; the surface fields still describe the current session. Every call clones the positional nodes, so measurement is O(surface).
 
-The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and assistant-chunk provenance. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
+The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and the chunk seqs cited by each assistant message. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
 
-Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty provenance list means a known empty provider stream, while absent legacy provenance conservatively treats the durable assistant output as provider output.
+Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty `sourceEventSeqs` list means a known empty provider stream, while an absent legacy list conservatively treats the durable assistant output as provider output.
 
 ## Session projections
 
@@ -65,4 +65,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **The fixed heuristic is approximate** — content without reusable provider usage is priced by character count plus structural overhead, not an exact provider tokenizer or request serializer.
 - **Every measurement clones the current surface** — coherent immutable snapshots make reads O(surface), including below-threshold pressure checks.
 - **Provider usage is only reusable for an identical canonical envelope** — prompt, prefix, tools, provider, model, or call-config changes deliberately fall back to full heuristic estimation.
-- **Legacy provenance is conservative** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.
+- **Missing legacy source seqs are handled conservatively** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index e3908ecea1..40cea07c7d 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -17,9 +17,9 @@
 
 `measure()` 会同步一次，并返回一个独立且深度不可变的快照。`totalTokens` 是请求与响应压力，`surfaceTokens` 是仅表层启发式总量，等于 `nodes[].tokens` 之和。`requestHeader` 覆盖只影响压力字段；表层字段仍描述当前会话。每次调用都会克隆带位置的节点，因此测量是 O(surface)。
 
-fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成功 assistant 消息、提供方用量和 assistant 分片溯源。只有当最新成功调用的规范请求 envelope 与已测量 envelope 匹配，且其总量不低于该调用的完整启发式锚点时，才会复用提供方用量；后续成功会替换较早锚点。否则会对当前 envelope 与表层进行完整估算。表层变更保持相对于匹配锚点的带符号值，包括缩减替换后的负 delta。
+fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成功 assistant 消息、提供方用量，以及每条 assistant 消息引用的分片 seq。只有当最新成功调用的规范请求 envelope 与已测量 envelope 匹配，且其总量不低于该调用的完整启发式锚点时，才会复用提供方用量；后续成功会替换较早锚点。否则会对当前 envelope 与表层进行完整估算。表层变更保持相对于匹配锚点的带符号值，包括缩减替换后的负 delta。
 
-用量计量会求和不重叠的输入、cache-read、cache-write 与输出 bucket；不会再次添加推理（reasoning）。每次成功调用都会记录一个 assistant 锚点，包括无内容调用。显式空溯源列表表示已知空提供方流，而遗留溯源缺失时，fold 会保守地将持久 assistant 输出视为提供方输出。
+用量计量会求和不重叠的输入、cache-read、cache-write 与输出 bucket；不会再次添加推理（reasoning）。每次成功调用都会记录一个 assistant 锚点，包括无内容调用。显式的空 `sourceEventSeqs` 列表表示已知空提供方流；遗留记录缺少该列表时，fold 会保守地将持久 assistant 输出视为提供方输出。
 
 ## 会话投影
 
@@ -65,4 +65,4 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 - **固定启发式规则是近似值**：没有可复用提供方用量的内容按字符数加结构开销计价，而不是使用精确提供方 tokenizer 或请求 serializer。
 - **每次测量都会克隆当前表层**：一致且不可变的快照使读取成为 O(surface)，包括低于阈值的压力检查。
 - **提供方用量只能为完全相同的规范 envelope 复用**：提示词、前缀、工具、提供方、模型或调用配置变更都会有意回退到完整启发式估算。
-- **遗留溯源采取保守策略**：没有 `sourceEventSeqs` 的 assistant 消息无法区分提供方输出与 listener 改写，因此 fold 不会声称已知空流或精确分片流。
+- **保守处理缺少源事件 seq 的遗留记录**：没有 `sourceEventSeqs` 的 assistant 消息无法区分提供方输出与 listener 改写，因此 fold 不会声称已知空流或精确分片流。
diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts
index 31991b482a..caea2a2701 100644
--- a/packages/llm/token-meter/src/index.ts
+++ b/packages/llm/token-meter/src/index.ts
@@ -270,9 +270,9 @@ export class TokenMeterService extends Service {
   }
 
   /**
-   * Reassemble provider output from exact chunk provenance for a usage anchor.
-   * Missing legacy provenance conservatively treats the durable output as the
-   * provider output; explicit empty provenance prices a known empty stream.
+   * Reassemble provider output from the exact cited chunk seqs for a usage anchor.
+   * Missing legacy source seqs conservatively treat the durable output as the
+   * provider output; an explicit empty list prices a known empty stream.
    */
   private _estimateProviderAssistant(
     session: Session,
diff --git a/packages/llm/token-meter/tests/token-meter.spec.ts b/packages/llm/token-meter/tests/token-meter.spec.ts
index 7009cc6a33..5638ce642b 100644
--- a/packages/llm/token-meter/tests/token-meter.spec.ts
+++ b/packages/llm/token-meter/tests/token-meter.spec.ts
@@ -313,7 +313,7 @@ describe('replay anchors and surface folds', () => {
     expect(advanced.surfaceDeltaTokens).toBeGreaterThan(0)
   })
 
-  it('distinguishes explicit empty provenance from absent legacy provenance', () => {
+  it('distinguishes an explicit empty source-event list from an absent legacy list', () => {
     const explicit = Session.create(SessionId('explicit-empty'))
     const legacy = Session.create(SessionId('legacy-absent'))
     appendSuccessfulCall(explicit, header('deepseek-v4-flash'), {
@@ -503,7 +503,7 @@ describe('malformed replay and listener lifecycle', () => {
     )
   })
 
-  it('rejects invalid assistant provenance', () => {
+  it('rejects invalid assistant source-event references', () => {
     const cases: Array<{
       name: string
       appendSource(session: Session): number[]
@@ -553,7 +553,7 @@ describe('malformed replay and listener lifecycle', () => {
     }
   })
 
-  it('rejects repeated and non-earlier assistant provenance', () => {
+  it('rejects repeated and non-earlier assistant source-event references', () => {
     const duplicate = Session.create(SessionId('duplicate-source'))
     duplicate.append('step/start', { turn: 1, step: 1 })
     appendHeader(duplicate, header('deepseek-v4-flash'))
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 7e9405d14b..0b1cf3a34d 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -27,7 +27,7 @@ export interface Config {
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
    * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
    * infrastructure failure.
    */
   runnerCommand?: string[]
diff --git a/packages/scaffold/server/src/server.ts b/packages/scaffold/server/src/server.ts
index 797e0cbfea..e6c22d7ff2 100644
--- a/packages/scaffold/server/src/server.ts
+++ b/packages/scaffold/server/src/server.ts
@@ -87,7 +87,7 @@ export class HarnessSdkServer {
     this.disposers.push(ctx.on('subagent/end', function (this: Scoped<SubagentService>, info: SubagentRunEndInfo) {
       const parent = subagentParentOf(this)
       // This protocol reports only in-process child sessions. The service
-      // snapshots the provider's exact run provenance through child disposal;
+      // snapshots the provider name and local flag through child disposal;
       // matching ids or parent lineage alone never establishes locality.
       if (!info.local) return
       const payload: SubagentFinishedNotification = {
diff --git a/packages/scaffold/server/tests/server.spec.ts b/packages/scaffold/server/tests/server.spec.ts
index c9d1944781..0acfcfccef 100644
--- a/packages/scaffold/server/tests/server.spec.ts
+++ b/packages/scaffold/server/tests/server.spec.ts
@@ -664,7 +664,7 @@ describe('HarnessSdkServer', () => {
     }
   })
 
-  it('uses explicit local provenance when start was missed and ignores remote runs', async () => {
+  it('uses the recorded local flag when start was missed and ignores remote runs', async () => {
     const storageDir = await mkdtemp(join(tmpdir(), 'dsh-jsonrpc-subagent-fallback-'))
     const ctx = await makeHarness(storageDir)
     let parentHandle: AgentHandle | undefined
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index 302fd4c9b3..a8fa2b4cff 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -768,7 +768,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>',
-        jsDoc: '/**\n * Trace one event\'s direct positional and provenance relationships.\n * @param request - target session id and event seq.\n * @param signal - optional cancellation for persisted source resolution.\n * @returns source header, direct links, and the target\'s positional replacement chain.\n * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.\n */',
+        jsDoc: '/**\n * Trace one event\'s direct positional replacements and cited source events.\n * @param request - target session id and event seq.\n * @param signal - optional cancellation for persisted source resolution.\n * @returns source header, direct links, and the target\'s positional replacement chain.\n * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.\n */',
       },
       {
         signature: 'async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>',
@@ -916,7 +916,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract saveText(input: SaveTextSpill): Promise<SpillRef>',
-        jsDoc: '/**\n * Persist `input.content` to a session-scoped spill artifact.\n * @param input - the owner, provenance, suggested name, and full text to save.\n * @returns the saved artifact\'s {@link SpillRef}; rejects on a storage failure.\n */',
+        jsDoc: '/**\n * Persist `input.content` to a session-scoped spill artifact.\n * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.\n * @returns the saved artifact\'s {@link SpillRef}; rejects on a storage failure.\n */',
       },
     ],
   },
@@ -962,7 +962,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>',
-        jsDoc: '/**\n * Deliver one later message to a continuable child as its next FIFO turn. A\n * resident child\'s Agent inbox accepts it directly (waking a `waiting`\n * Activation), while an absent one is cold-resumed from its persisted\n * Session. The Agent inbox is the only queue, so every accepted message has\n * one observable order.\n * @param parent - the exact live direct parent authorizing this delivery.\n * @param childId - durable child session id.\n * @param content - user-role content to deliver.\n * @param options - durable provenance and caller cancellation, which stops the\n *   operation only before inbox acceptance.\n * @returns the accepted message\'s inbox id.\n * @throws when continuation services are unavailable, parent authority is\n *   rejected, or the message was not admitted.\n */',
+        jsDoc: '/**\n * Deliver one later message to a continuable child as its next FIFO turn. A\n * resident child\'s Agent inbox accepts it directly (waking a `waiting`\n * Activation), while an absent one is cold-resumed from its persisted\n * Session. The Agent inbox is the only queue, so every accepted message has\n * one observable order.\n * @param parent - the exact live direct parent authorizing this delivery.\n * @param childId - durable child session id.\n * @param content - user-role content to deliver.\n * @param options - the message source fields and caller cancellation, which stops the\n *   operation only before inbox acceptance.\n * @returns the accepted message\'s inbox id.\n * @throws when continuation services are unavailable, parent authority is\n *   rejected, or the message was not admitted.\n */',
       },
       {
         signature: 'interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void',
@@ -1134,7 +1134,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'pruneSession(session: Session): PruneResult',
-        jsDoc: '/**\n * Prune every over-budget tool result from one stable current-surface snapshot.\n * Each replacement preserves the complete event data except for `content`,\n * points at the shadowed node for durable provenance and replay, and is\n * immediately preceded by a `compact/prune` shadow-price event pricing the\n * shadowed node through the injected token meter, so pure consumers can\n * subtract it without per-node state.\n * @param session - session whose current surface is rewritten.\n * @returns landed replacements and aggregate Unicode-code-point savings.\n * @throws when the session rejects a replacement; replacements committed\n * earlier in the pass remain durable.\n */',
+        jsDoc: '/**\n * Prune every over-budget tool result from one stable current-surface snapshot.\n * Each replacement preserves the complete event data except for `content`,\n * cites the shadowed node so replay can recover the replacement input, and is\n * immediately preceded by a `compact/prune` shadow-price event pricing the\n * shadowed node through the injected token meter, so pure consumers can\n * subtract it without per-node state.\n * @param session - session whose current surface is rewritten.\n * @returns landed replacements and aggregate Unicode-code-point savings.\n * @throws when the session rejects a replacement; replacements committed\n * earlier in the pass remain durable.\n */',
       },
     ],
   },
diff --git a/packages/session-query/session-query/README.i18n.yaml b/packages/session-query/session-query/README.i18n.yaml
index 423d3f2d90..3735d1c559 100644
--- a/packages/session-query/session-query/README.i18n.yaml
+++ b/packages/session-query/session-query/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/session-query/session-query/README.md
-README.md: b75c1f23264cfa7c9323970b3c1a77ddcfe69be0
-README.zh.md: 4f1c4749a847326fd9fbc0ffa627651c052ccd71
+README.md: 5d4d689477fca4fd6b01091f1304ff3065af7443
+README.zh.md: 957b5c39d9ff2127e7819ae01077fec51950b26f
diff --git a/packages/session-query/session-query/README.md b/packages/session-query/session-query/README.md
index b75c1f2326..5d4d689477 100644
--- a/packages/session-query/session-query/README.md
+++ b/packages/session-query/session-query/README.md
@@ -15,7 +15,7 @@ English | [中文](README.zh.md)
 - `readSurface(sessionId)` returns one cloned header, raw-log capture boundary, and the complete folded current surface in model-history order. A live session wins over persistence; compaction is observed before or after its replacement append, never as a synthetic mixture.
 - `readEvent(request, signal?)` returns a cloned header, the full target event, and a bounded raw-seq window. `before` and `after` default to zero and may not exceed `readWindowMax`.
 - `traceSession(sessionId, signal?)` reads the corpus once and returns immediate-to-outward ancestors plus deterministic recursive descendant trees. `complete: false` identifies the first missing parent; a target-connected cycle fails with `SESSION_QUERY_INVALID_LINEAGE`.
-- `traceEvent(request, signal?)` loads the logical log once and returns its cloned source header with direct positional replacements and direct logged provenance. `replacementChain` follows positional replacers to the final replacement; provenance links remain non-transitive.
+- `traceEvent(request, signal?)` loads the logical log once and returns its cloned source header with direct positional replacements and direct cited source-event links. `replacementChain` follows positional replacers to the final replacement; source-event links remain non-transitive.
 
 Persistence is optional and may mount or unmount dynamically. Cross-corpus listing and lineage tracing fail with `SESSION_QUERY_PERSISTENCE_FAILED` while mounted persistence is unreadable; a successfully read durable record that fails Session validation reports `SESSION_QUERY_CORRUPT_SESSION` instead. A title read, event trace, or event read targeting a known live session does not consult persistence, so durable backend health cannot make current in-memory state unreadable. Persisted title and event operations list before loading and reject a metadata mismatch rather than combining inconsistent observations. Lineage-trace cancellation is passed to persisted listing; event-trace and event-read cancellation is passed to persisted listing and inspection. Each waits for the started backend call to settle, then rejects with the signal's exact reason even when the backend ignored that signal. A pre-aborted known-live title read, event trace, or event read rejects before folding or snapshotting without consulting persistence. A batch title observation performs one metadata listing, inspects its unique persisted ids with at most `persistedInspectConcurrency` workers, and preserves each title's own observed header for downstream authorization. Cancellation starts no queued inspections and rejects only after already-started workers settle. `listSessions()` remains lightweight and does not load logs or index titles.
 
@@ -33,7 +33,7 @@ The package has no provider coordinator, fallback implementation, or standalone
 
 `SessionQueryError.code` is a closed union covering request validation, missing targets, malformed surfaces, source conflicts, persistence/index failures, cancellation, and invalid or stale cursors; the exact literals are defined in [`src/config.ts`](src/config.ts).
 
-`listEvents()`, `readSurface()`, and `traceEvent()` run the same one-pass `dsh-session` surface fold. A loaded log is valid only when event seqs are zero-based and contiguous, surface markers obey event-type eligibility, provenance arrays are nonempty and duplicate-free, references name earlier events, and each positional replacement names and cites every surface node it removes; every violation fails with `SESSION_QUERY_INVALID_SURFACE`.
+`listEvents()`, `readSurface()`, and `traceEvent()` run the same one-pass `dsh-session` surface fold. A loaded log is valid only when event seqs are zero-based and contiguous, surface markers obey event-type eligibility, source-event arrays are nonempty and duplicate-free, references name earlier events, and each positional replacement names and cites every surface node it removes; every violation fails with `SESSION_QUERY_INVALID_SURFACE`.
 
 ## Configuration
 
@@ -53,4 +53,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No caller authorization** — this is trusted context-wide infrastructure; a future model tool or UI must constrain which sessions its caller may inspect.
-- **No registries or model-facing tool** — extractor and search-provider registries, recursive event-provenance traversal, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; SQLite ownership and tokenizer decisions live in the [implemented search note](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md).
+- **No registries or model-facing tool** — extractor and search-provider registries, recursive traversal through cited source events, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; SQLite ownership and tokenizer decisions live in the [implemented search note](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md).
diff --git a/packages/session-query/session-query/README.zh.md b/packages/session-query/session-query/README.zh.md
index 4f1c4749a8..957b5c39d9 100644
--- a/packages/session-query/session-query/README.zh.md
+++ b/packages/session-query/session-query/README.zh.md
@@ -15,7 +15,7 @@
 - `readSurface(sessionId)` 返回一个克隆 header、原始日志捕获边界，以及按模型历史顺序排列的完整折叠后当前表层。实时会话优先于持久化；压缩（compaction）只会在其替换追加之前或之后被观察，绝不会出现合成混合。
 - `readEvent(request, signal?)` 返回一个克隆 header、完整目标事件和有界的原始 seq 窗口。`before` 和 `after` 默认为 0，且不得超过 `readWindowMax`。
 - `traceSession(sessionId, signal?)` 只读取一次语料库，返回从直接父级向外的祖先，以及确定性的递归后代树。`complete: false` 标识第一个缺失父级；与目标相连的循环会以 `SESSION_QUERY_INVALID_LINEAGE` 失败。
-- `traceEvent(request, signal?)` 只加载一次逻辑日志，返回其克隆源 header、直接位置替换和直接已记录来源信息。`replacementChain` 沿位置替换者跟踪到最终替换；来源链接仍不传递。
+- `traceEvent(request, signal?)` 只加载一次逻辑日志，返回其克隆源 header、直接位置替换和直接引用的源事件链接。`replacementChain` 沿位置替换者跟踪到最终替换；源事件链接仍不传递。
 
 持久化是可选的，可动态挂载或卸载。已挂载持久化无法读取时，跨语料库列表和血缘跟踪以 `SESSION_QUERY_PERSISTENCE_FAILED` 失败；已经成功读取、但无法通过 Session 校验的持久化记录则以 `SESSION_QUERY_CORRUPT_SESSION` 失败。针对已知实时会话的标题读取、事件跟踪或事件读取不会查询持久化，因此持久化后端的健康状态无法使当前内存状态变得不可读。持久化标题和事件操作在加载前先执行列表查询，并在元数据不匹配时拒绝，而不会组合不一致的观察。血缘跟踪的取消信号会传递给持久化列表查询；事件跟踪和事件读取的取消信号会传递给持久化列表查询和检查。每项操作都会等待已启动的后端调用结算，然后使用信号的精确原因拒绝，即使后端忽略了该信号。针对已知实时会话且预先中止的标题读取、事件跟踪或事件读取会在 fold 或快照之前拒绝，且不查询持久化。批量标题观察执行一次元数据列表查询，使用最多 `persistedInspectConcurrency` 个 worker 检查唯一持久化 id，并保留每个标题自己观察到的 header，供下游授权使用。取消不会启动已排队检查，且只在已启动 worker 结算后拒绝。`listSessions()` 仍保持轻量，不加载日志或索引标题。
 
@@ -33,7 +33,7 @@
 
 `SessionQueryError.code` 是一个封闭联合，覆盖请求验证、缺失目标、格式错误的表层、来源冲突、持久化/索引失败、取消，以及无效或陈旧游标；精确字面值在 [`src/config.ts`](src/config.ts) 中定义。
 
-`listEvents()`、`readSurface()` 和 `traceEvent()` 执行同一个单遍 `dsh-session` 表层 fold。只有当事件 seq 从零开始且连续、表层标记符合事件类型的适用性要求、来源数组非空且无重复、引用指向较早事件，且每个位置替换都命名并引用它移除的每个表层节点时，加载的日志才有效；任何违规都以 `SESSION_QUERY_INVALID_SURFACE` 失败。
+`listEvents()`、`readSurface()` 和 `traceEvent()` 执行同一个单遍 `dsh-session` 表层 fold。只有当事件 seq 从零开始且连续、表层标记符合事件类型的适用性要求、源事件数组非空且无重复、引用指向较早事件，且每个位置替换都命名并引用它移除的每个表层节点时，加载的日志才有效；任何违规都以 `SESSION_QUERY_INVALID_SURFACE` 失败。
 
 ## 配置
 
@@ -53,4 +53,4 @@
 ## 已知限制与暂缓事项
 
 - **无调用方授权**：这是上下文范围内的可信基础设施；未来的模型工具或 UI 必须限制调用方可检查的会话。
-- **无注册表或面向模型工具**：尚未提供提取器和搜索提供方注册表、递归事件来源遍历以及面向模型的工具。[跟踪决策](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) 负责关系语义；SQLite 归属和 tokenizer 决策位于[已实现搜索记录](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md)。
+- **无注册表或面向模型工具**：尚未提供提取器和搜索提供方注册表、递归遍历所引用的源事件的能力，以及面向模型的工具。[跟踪决策](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) 负责关系语义；SQLite 归属和 tokenizer 决策位于[已实现搜索记录](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md)。
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index 7878026345..f2c6b57c66 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -283,11 +283,11 @@ export abstract class SessionQueryService extends Service {
   }
 
   /**
-   * Trace one event's direct positional and provenance relationships.
+   * Trace one event's direct positional replacements and cited source events.
    * @param request - target session id and event seq.
    * @param signal - optional cancellation for persisted source resolution.
    * @returns source header, direct links, and the target's positional replacement chain.
-   * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+   * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
    */
   async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation> {
     const loaded = await this._corpus.load(request.sessionId, signal)
diff --git a/packages/session-query/session-query/src/tracing.ts b/packages/session-query/session-query/src/tracing.ts
index d929317b50..681e6ce59a 100644
--- a/packages/session-query/session-query/src/tracing.ts
+++ b/packages/session-query/session-query/src/tracing.ts
@@ -60,7 +60,7 @@ export function currentSurfaceEvents(
  * @param sessionId - owner of the event log.
  * @param events - detached raw event log.
  * @param seq - target event seq.
- * @returns direct surface and provenance relationships.
+ * @returns direct surface replacements and relationships to cited source events.
  */
 export function traceEvent(
   sessionId: SessionId,
diff --git a/packages/session-query/session-query/src/types.ts b/packages/session-query/session-query/src/types.ts
index b01d80dade..c98b5a749e 100644
--- a/packages/session-query/session-query/src/types.ts
+++ b/packages/session-query/session-query/src/types.ts
@@ -93,7 +93,7 @@ export type SessionLineageTrace = {
   }
 )
 
-/** Request for direct surface and provenance relationships around one event. */
+/** Request for direct surface replacements and relationships to cited source events around one event. */
 export interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
@@ -101,7 +101,7 @@ export interface SessionEventTraceRequest {
   seq: number
 }
 
-/** Direct surface and provenance relationships for one event. */
+/** Direct surface replacements and relationships to cited source events for one event. */
 export interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
@@ -111,9 +111,9 @@ export interface SessionEventTrace {
   replacementChain: number[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
-  /** Direct logged provenance sources in their recorded order. */
+  /** Earlier events cited directly as sources, in their recorded order. */
   sourceEventSeqs: number[]
-  /** Later events that directly name the target as a provenance source, in log order. */
+  /** Later events that directly cite the target as a source, in log order. */
   derivedEventSeqs: number[]
 }
 
diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts
index a6b5d73eb9..24e8622ab2 100644
--- a/packages/session-query/session-query/tests/tracing.spec.ts
+++ b/packages/session-query/session-query/tests/tracing.spec.ts
@@ -275,7 +275,7 @@ describe('session lineage tracing', () => {
 })
 
 describe('session event tracing', () => {
-  it('returns direct replacement and provenance links in their contract order', async () => {
+  it('returns direct replacement and cited source-event links in their contract order', async () => {
     const ctx = await queryContext()
     const session = ctx.sessions.create(SessionId('trace'))
     appendTraceEvents(session)
@@ -380,7 +380,7 @@ describe('session event tracing', () => {
       .rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
   })
 
-  it('checks target existence before surface or provenance analysis', async () => {
+  it('checks target existence before surface or source-event analysis', async () => {
     const bad = header('bad-target')
     const malformed: SessionEvent[] = [appendEvent(0), {
       type: 'assistant/message',
diff --git a/packages/session-query/tool-session-query/src/index.ts b/packages/session-query/tool-session-query/src/index.ts
index d6eb659b4d..5187e254ae 100644
--- a/packages/session-query/tool-session-query/src/index.ts
+++ b/packages/session-query/tool-session-query/src/index.ts
@@ -95,7 +95,7 @@ export function apply(ctx: Context, config: Config): void {
 
   ctx.tools.register(defineTool({
     name: 'session_event_trace',
-    description: 'Read every direct replacement and provenance relationship for one event in an authorized session.',
+    description: 'Read every direct replacement and relationship to a cited source event for one event in an authorized session.',
     parameters: {
       ...toolInput.targetSessionParameter,
       seq: { type: 'integer', required: true, description: 'Target event sequence number.' },
diff --git a/packages/session-query/tool-session-query/src/presentation.ts b/packages/session-query/tool-session-query/src/presentation.ts
index 6e99bd22eb..659a48d17b 100644
--- a/packages/session-query/tool-session-query/src/presentation.ts
+++ b/packages/session-query/tool-session-query/src/presentation.ts
@@ -157,7 +157,7 @@ function formatEventTrace(
     `Replaced by: ${trace.replacedBy ?? 'none'}`,
     `Replacement chain: ${seqList(trace.replacementChain)}`,
     `Events replaced by target: ${seqList(trace.replacedEventSeqs)}`,
-    `Direct provenance sources: ${seqList(trace.sourceEventSeqs)}`,
+    `Events cited directly as sources: ${seqList(trace.sourceEventSeqs)}`,
     `Direct derived events: ${seqList(trace.derivedEventSeqs)}`,
   ].join('\n')
 }
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index b6c2b25e6f..8341e48a1e 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
-README.zh.md: 6b02f37343da07a80953ecb9d05e5903bd42d95c
+README.md: 29ee219a55d0823f03bb512c0fa37b7e249817eb
+README.zh.md: c750d2f85fd267a94c36770452f1e5c7e647a2fb
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 89c7cd5eba..29ee219a55 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -35,7 +35,7 @@ Each `session/event` copies its event into the session controller. The first pen
 
 Crash repair is cold-only. For a live id, `load(id)` snapshots the authoritative in-memory log, waits for that snapshot to become durable, and returns it only when balanced; an open live turn rejects instead of receiving synthetic interruption closers. For a cold id, inspection reads, validates, freezes, and constructs one unpublished Session; repeated inspection reuses that object graph only while its source revision remains current. `prepare(id)` performs the same check before repair, reserves the exact Session, commits any pending torn-tail/interrupted-turn repair, and returns it for publication. HMR adoption reads through `loadStored`, applies the coordinator's cwd check, and never closes the active turn.
 
-Backend reads normalize the exact supported same-version shapes before current-shape validation. Pre-identity messages receive the deterministic id `legacy-message:<session-id>:<event-seq>`; a tool-result content replacement inherits its target's imported id. A pre-react-loop `turn/start` loses its obsolete trigger, a removed `steering/message` becomes the same identified `user/message`, and an older `turn/end` maps its terminal reason without inventing unavailable cancellation provenance. The coordinator uses the same normalized view for `load`, `inspect`, `readFrom`, ownerless-state claims, and HMR prefix adoption. Storage remains append-only: reads do not rewrite old records, and later appends use the current shape. These are narrow import exceptions from the [pre-identity message](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md) and [pre-react-loop session](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md) decisions, not a general v0 migration promise.
+Backend reads normalize the exact supported same-version shapes before current-shape validation. Pre-identity messages receive the deterministic id `legacy-message:<session-id>:<event-seq>`; a tool-result content replacement inherits its target's imported id. A pre-react-loop `turn/start` loses its obsolete trigger, a removed `steering/message` becomes the same identified `user/message`, and an older `turn/end` maps its terminal reason without inventing a caller that the old record did not name. The coordinator uses the same normalized view for `load`, `inspect`, `readFrom`, ownerless-state claims, and HMR prefix adoption. Storage remains append-only: reads do not rewrite old records, and later appends use the current shape. These are narrow import exceptions from the [pre-identity message](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md) and [pre-react-loop session](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md) decisions, not a general v0 migration promise.
 
 When a live session emits `session/disposed`, the coordinator waits for its controller, serializes a final drain, then releases state owned by that exact `Session` object. Failed retirement leaves the controller in the live-session map, so backend teardown can retry it. Backend teardown stops event admission first, flushes every remaining controller, awaits per-id operations, and only then closes the storage handle.
 
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index 6b02f37343..c750d2f85f 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -35,7 +35,7 @@
 
 崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源修订值仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留该 Session 本身，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
 
-后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 引入前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构无法获得的取消来源的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无所有者状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
+后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 引入前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构旧记录中未命名调用方的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无所有者状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
 
 实时会话发出 `session/disposed` 时，协调器等待其 controller，串行化最终 drain，然后释放该精确 `Session` 对象拥有的状态。失败退役会将 controller 保留在实时会话 map 中，使后端拆卸可重试。后端拆卸先停止事件接纳，flush 每个剩余 controller，等待每 id 操作，最后才关闭存储句柄。
 
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index a7744c490b..d0a3459c64 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/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/session/session-title-llm/README.md
-README.md: 342687b5aa0cd35a70abf8cc66b3fe80342bce0b
-README.zh.md: 10496a727baa8a515f831feb425bc3d66ad91b5f
+README.md: db03205cabf9f723ee9bf6ad122026d75cb92113
+README.zh.md: a214caae84aeee7a3a5c90f55e8a01ea957b823f
diff --git a/packages/session/session-title-llm/README.md b/packages/session/session-title-llm/README.md
index 342687b5aa..db03205cab 100644
--- a/packages/session/session-title-llm/README.md
+++ b/packages/session/session-title-llm/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared implementation policy for model-backed session-title providers. It resolves the auxiliary route, frames exact selected human messages as JSON, records the exact dispatchable request, applies a language-aware title instruction, enforces input and output budgets, composes timeout and caller cancellation, assembles the stream, and returns normalized text with exact source seqs and model provenance.
+Shared implementation policy for model-backed session-title providers. It resolves the auxiliary route, frames exact selected human messages as JSON, records the exact dispatchable request, applies a language-aware title instruction, enforces input and output budgets, composes timeout and caller cancellation, assembles the stream, and returns normalized text with exact source seqs plus the provider/model route used to generate it.
 
 This package is a library, not a Cordis plugin. The provider plugins call `registerSessionTitleLlmProvider()` with their cadence and message selector; it validates shared config and delegates each revision to `generateSessionTitleWithLlm()`, so registration, route, prompt, cancellation, and validation behavior cannot drift between them.
 
diff --git a/packages/session/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
index 10496a727b..a214caae84 100644
--- a/packages/session/session-title-llm/README.zh.md
+++ b/packages/session/session-title-llm/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-由模型支持的会话标题提供方的共享实现策略。它解析辅助路由，将精确选中的用户消息封装为 JSON，记录可分发的确切请求，应用语言感知的标题指令，强制执行输入和输出预算，组合超时与调用方取消，组装流，并返回带有确切来源 seq 和模型来源信息的规范化文本。
+由模型支持的会话标题提供方的共享实现策略。它解析辅助路由，将精确选中的用户消息封装为 JSON，记录可分发的确切请求，应用语言感知的标题指令，强制执行输入和输出预算，组合超时与调用方取消，组装流，并返回规范化文本，同时给出确切来源 seq 以及生成该文本时使用的提供方／模型路由。
 
 此包是普通库，不是 Cordis 插件。提供方插件调用 `registerSessionTitleLlmProvider()`，传入各自节奏与消息选择器；该函数验证共享配置，并将每次修订委派给 `generateSessionTitleWithLlm()`，使各插件的注册、路由、提示词、取消与验证行为不会漂移。
 
diff --git a/packages/session/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
index 646c9e53d5..1b0e328621 100644
--- a/packages/session/session-title-llm/src/index.ts
+++ b/packages/session/session-title-llm/src/index.ts
@@ -146,7 +146,7 @@ export type SessionTitleLlmMessageSelector = (
  * Register one model-backed provider through the shared configuration and call policy.
  * @param ctx - context exposing the title and LLM services.
  * @param config - untrusted required deployment policy.
- * @param id - stable plugin identity recorded in title provenance.
+ * @param id - stable plugin id recorded with generated titles.
  * @param automatic - provider-owned automatic generation cadence.
  * @param selectMessages - exact source-message selection for one revision.
  */
diff --git a/packages/session/session-title-llm/src/invariant.ts b/packages/session/session-title-llm/src/invariant.ts
index 419db90185..64350ebf20 100644
--- a/packages/session/session-title-llm/src/invariant.ts
+++ b/packages/session/session-title-llm/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: this stateless helper validates and freezes each auxiliary request before
- * dispatch; deadline, stream, and provenance relationships are checked synchronously and by tests.
+ * dispatch; deadline, stream, cited message seqs, and provider/model fields are checked synchronously and by tests.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
index f87ea98542..4b038799f3 100644
--- a/packages/session/session-title/README.i18n.yaml
+++ b/packages/session/session-title/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/session/session-title/README.md
-README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db
-README.zh.md: 075e9e31fc7acbc76f0e3fd7a2642b4d879569d3
+README.md: e7004eb2e03757cb28b4b5756a876e1dee4b6229
+README.zh.md: 45c1aafdf214f63ae7a071d2558eaefec13ea70f
diff --git a/packages/session/session-title/README.md b/packages/session/session-title/README.md
index 13a2a1c298..e7004eb2e0 100644
--- a/packages/session/session-title/README.md
+++ b/packages/session/session-title/README.md
@@ -29,7 +29,7 @@ All limits are required; the library supplies no defaults.
 
 ## Provider contract
 
-A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and optional model provenance. The service normalizes and validates the result before it becomes durable.
+A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and the optional provider/model route used to generate it. The service normalizes and validates the result before it becomes durable.
 
 See the [session-title data structures](../../../docs/subsystems/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
 
diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md
index 075e9e31fc..45c1aafdf2 100644
--- a/packages/session/session-title/README.zh.md
+++ b/packages/session/session-title/README.zh.md
@@ -29,7 +29,7 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会
 
 ## 提供方约定
 
-提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。
+提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及生成该标题时使用的可选提供方／模型路由。服务会在结果持久保存前进行规范化和验证。
 
 参见[会话标题数据结构](../../../docs/subsystems/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。
 
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index 12da431c68..ab2298aa6c 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -63,7 +63,7 @@ export interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 
@@ -146,14 +146,14 @@ export interface SessionTitleProviderResult {
 
 /** One optional asynchronous title implementation registered with the service. */
 export interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
@@ -615,12 +615,12 @@ export class SessionTitleService extends Service {
     let model: SessionTitleModelProvenance | undefined
     if (modelCandidate !== undefined) {
       if (modelCandidate === null || typeof modelCandidate !== 'object') {
-        throw new Error('session-title provider model provenance requires non-empty provider and model')
+        throw new Error('session-title provider result model must contain non-empty provider and model strings')
       }
       const record = modelCandidate as Record<string, unknown>
       if (typeof record.provider !== 'string' || record.provider.length === 0
         || typeof record.model !== 'string' || record.model.length === 0) {
-        throw new Error('session-title provider model provenance requires non-empty provider and model')
+        throw new Error('session-title provider result model must contain non-empty provider and model strings')
       }
       model = { provider: record.provider, model: record.model }
     }
diff --git a/packages/session/session-title/src/invariant.ts b/packages/session/session-title/src/invariant.ts
index 25b00a10aa..a826104489 100644
--- a/packages/session/session-title/src/invariant.ts
+++ b/packages/session/session-title/src/invariant.ts
@@ -16,7 +16,7 @@ export const name = 'session-title-invariant'
 export const inject = ['invariants']
 
 /**
- * Durable title-provenance invariant: an automatic title always cites at
+ * Durable title-source invariant: an automatic title always cites at
  * least one human `user/message` seq, and an explicit user rename cites none
  * — `messageSeqs` is empty iff `source.kind` is `user`. Provider revisions
  * are validated by the service before their append; this checks the durable
@@ -32,7 +32,8 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     if (event.type !== 'session/title') return
     const { source, messageSeqs } = event.data
     if ((messageSeqs.length === 0) !== (source.kind === 'user')) {
-      fail(`session/title event ${String(event.seq)} breaks provenance: source "${source.kind}" with ${String(messageSeqs.length)} cited message seq(s)`)
+      const requirement = source.kind === 'user' ? 'cite no message seqs' : 'cite at least one message seq'
+      fail(`session/title event ${String(event.seq)} with source "${source.kind}" must ${requirement}; got ${String(messageSeqs.length)}`)
     }
   }, { global: true })
 }, { inject: ['sessions'] })
diff --git a/packages/session/session-title/tests/invariant.spec.ts b/packages/session/session-title/tests/invariant.spec.ts
index 5b316448da..d1a6abb527 100644
--- a/packages/session/session-title/tests/invariant.spec.ts
+++ b/packages/session/session-title/tests/invariant.spec.ts
@@ -1,4 +1,4 @@
-// Title-provenance invariant: messageSeqs is empty iff source.kind is 'user'
+// Title-source invariant: `messageSeqs` is empty iff `source.kind` is `user`.
 // — the durable relationship every appended session/title event must keep.
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
@@ -14,7 +14,7 @@ async function setup(): Promise<Context> {
   return ctx
 }
 
-describe('session-title provenance invariant', () => {
+describe('session-title source invariant', () => {
   it('accepts cited automatic titles and citation-free user renames', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('title-invariant-valid'))
diff --git a/packages/session/session-title/tests/service-contracts.spec.ts b/packages/session/session-title/tests/service-contracts.spec.ts
index 6a425ae36f..28d7e6749e 100644
--- a/packages/session/session-title/tests/service-contracts.spec.ts
+++ b/packages/session/session-title/tests/service-contracts.spec.ts
@@ -436,12 +436,12 @@ describe('SessionTitleService provider validation and stale scheduling', () => {
       { value: { title: 'valid', messageSeqs: [999] }, error: /unique, ordered seqs/ },
       { value: { title: 'valid', messageSeqs: [first.seq, first.seq] }, error: /unique, ordered seqs/ },
       { value: { title: 'valid', messageSeqs: [second.seq, first.seq] }, error: /unique, ordered seqs/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: null }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: 'route' }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 1, model: 'm' } }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: '', model: 'm' } }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: 1 } }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: '' } }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: null }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: 'route' }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 1, model: 'm' } }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: '', model: 'm' } }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: 1 } }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: '' } }, error: /provider result model/ },
     ]
     for (const item of cases) {
       result = item.value
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index dbbb9ba698..f1dc1c8851 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/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/settings/settings/README.md
-README.md: 0841624e553364fa03f7a1f1209aa72ab13d97e4
-README.zh.md: 3dbe14a7ce6fc002569eb612f355fa0ff7372ae3
+README.md: 49ae5b405c003b6116e459cf377fc7a099538f2e
+README.zh.md: c55db331ece9421fb7f0367697ce158b8e9b06f1
diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md
index 0841624e55..49ae5b405c 100644
--- a/packages/settings/settings/README.md
+++ b/packages/settings/settings/README.md
@@ -38,6 +38,6 @@ No direct invalidation; a consumer that folds a settings value into the request
 
 ## Known Limitations and Deferred Work
 
-- **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; there is no project/managed layering or per-value provenance yet.
+- **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; it does not yet record which layer supplied each resolved value.
 - **`redactSecrets` is not a proven wire boundary** — the walker follows `object`/`dict`/`array`, so a `role('secret')` reached only through a union, intersection, or transform is returned VERBATIM with an empty `secrets` list, and `schema.toJSON()` carries a secret field's `.default(...)` to every client. Neither case is rejected; a schema whose secrets are not reachable through the walked containers must not be registered on a wire-exposed namespace. A fail-closed `describeForWire()` — one that refuses a schema it cannot prove safe, and sanitizes the serialized envelope and error text — is the real answer and is deferred.
 - **Cross-process concurrency is provider-defined** — the seam serializes writes per namespace in-process only; concurrent processes converge by provider behavior (the local file provider read-modify-writes under a writer lock, so namespaces survive concurrent writers and same-namespace conflicts resolve last-write-wins).
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index 3dbe14a7ce..c55db331ec 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -38,6 +38,6 @@
 
 ## 已知限制与暂缓事项
 
-- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。
+- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；它尚未记录每个解析值由哪一层提供。
 - **`redactSecrets` 并非一条可被证明的协议边界**：walker 只跟随 `object`/`dict`/`array`，因此只能经由 union、intersection 或 transform 抵达的 `role('secret')` 会被**原样**返回，且 `secrets` 列表为空；而 `schema.toJSON()` 会把 secret 字段的 `.default(...)` 一并带给每个客户端。这两种情况都不会被拒绝；机密无法经由被遍历的容器抵达的 schema，绝不可注册到暴露于协议的 namespace 上。真正的答案是一个 fail-closed 的 `describeForWire()`——它拒绝自己无法证明安全的 schema，并对序列化信封与错误文本做净化——此项暂缓。
 - **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index 604cd63bcf..bc9a1634a1 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -26,7 +26,7 @@ export const inject = ['agents', 'tools', 'skills']
 
 const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500
 /**
- * Durable provenance for one published session skill catalog. The catalog is a
+ * Durable provider and item records for one published session skill catalog. The catalog is a
  * `catalog`-form context, so it records the entries it published beside the
  * model-facing prose: a consumer presenting the list must not re-parse the
  * `<available_skills>` block, whose framing exists for the model.
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index 4948b880f0..110d814fe2 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
-README.md: c3434f90a8f7ab30baa6b237beab6dd9763f9bff
-README.zh.md: fc80f8a5fee713a6cba1a5c8173c489bfc2c14d8
+README.md: d3cce987f80c0db5165718b7cc4fd6ada92f2a02
+README.zh.md: 37d6587d08d96c55a36c9b7388f2ae418531a6cd
diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md
index c3434f90a8..d3cce987f8 100644
--- a/packages/spill/spill/README.md
+++ b/packages/spill/spill/README.md
@@ -24,7 +24,7 @@ Storage is grouped by the request's `owner` session as a save-time namespace; th
 
 ## Vocabulary
 
-`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` (toolName, callId, label) is descriptive provenance for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
+`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` records the producing `toolName`, `callId`, and `label` for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
 
 See the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design rationale, including why creation belongs to the runtime spill seam rather than the model-facing `write` tool.
 
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index fc80f8a5fe..37d6587d08 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -24,7 +24,7 @@
 
 ## 词汇
 
-`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整约定见 `src/types.ts`。
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource` 记录产生该 spill 的 `toolName`、`callId` 和 `label`，供后端命名和检查使用，不用于访问控制。完整约定见 `src/types.ts`。
 
 设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
 
diff --git a/packages/spill/spill/src/index.ts b/packages/spill/spill/src/index.ts
index 4c8826defb..73bfe75f33 100644
--- a/packages/spill/spill/src/index.ts
+++ b/packages/spill/spill/src/index.ts
@@ -49,7 +49,7 @@ export abstract class SpillStore extends Service {
 
   /**
    * Persist `input.content` to a session-scoped spill artifact.
-   * @param input - the owner, provenance, suggested name, and full text to save.
+   * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
    * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
    */
   abstract saveText(input: SaveTextSpill): Promise<SpillRef>
diff --git a/packages/spill/spill/src/types.ts b/packages/spill/spill/src/types.ts
index 96376bb268..a3657e5c3c 100644
--- a/packages/spill/spill/src/types.ts
+++ b/packages/spill/spill/src/types.ts
@@ -39,7 +39,7 @@ export interface SpillOwner {
 }
 
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
  * filename and inspection. Not interpreted for access control; purely
  * descriptive.
  */
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index ca81aa07a6..e1ba59aa50 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
-README.zh.md: 52971add9646fd45a33661bb33b3f7d8c452219c
+README.md: 7658dad2fc8d79ca178ed5467448de9527f7bc49
+README.zh.md: 8d3bc4b96ac366e919256f4409ebd54d3505de87
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index cd25bace16..7658dad2fc 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -27,7 +27,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 
 `SubagentStartRequest.label` is an optional short durable display label for a session-backed one-shot child. Model-facing delegation supplies its existing `description`; lower-level callers need not invent presentation metadata. Continuable starts always carry their own required label. `signal` is required and is the canonical cancellation channel for a one-shot `start`. An abort before publication makes `start()` reject after rollback; an abort after publication cancels the returned run's remaining turn work without hiding its id. The request may also select a model, require structured output, cap delegation depth, restrict child tools, or set a child persona. For a continuable start or follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance; afterward the manager owns the Activation independently, so later caller cancellation neither cancels the accepted turn nor disposes the child.
 
-Follow-up authority comes from the exact live direct parent recorded in the child's durable header. Cold resume checks that authority before reconstruction and again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. The `source` on a follow-up is durable provenance retained on the delivered message and grants no authority.
+Follow-up authority comes from the exact live direct parent recorded in the child's durable header. Cold resume checks that authority before reconstruction and again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. The `source` on a follow-up records who supplied the delivered message and grants no authority.
 
 Same-process requests, descriptors, results, and event payloads are trusted typed values borrowed as immutable. The service does not clone or freeze them; serialization and hostile-input validation belong at actual process, worker, persistence, and model boundaries.
 
@@ -72,13 +72,13 @@ A continuation-managed parent Activation records each child Session id in an `ow
 
 ## Lifecycle events
 
-The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field is lifecycle provenance rather than a live-registry claim: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch retains its descriptor's initial provider name without requiring that provider to be registered.
+The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field names the provider that started the run or Activation epoch rather than claiming current registration: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch retains its descriptor's initial provider name without requiring that provider to be registered.
 
 Run events are scoped to the delegating parent. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peer listeners or changing the run.
 
 Provider additions and removals also emit `subagent/provider-added` and `subagent/provider-removed`. Consumers such as the model-facing tool use those events because Cordis may load sibling plugins concurrently; configuration order does not prove registration order.
 
-Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority. Interrupt authority is deliberately wider than delivery authority: a human presents the durable direct-parent address so a live child stays stoppable while its parent Agent is offline, and any exact live ancestor recorded in the Activation's materialization lineage may stop its descendant, because stopping a turn is idempotent and delivers no content.
+Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` records the sender without granting authority. Interrupt authority is deliberately wider than delivery authority: a human presents the durable direct-parent address so a live child stays stoppable while its parent Agent is offline, and any exact live ancestor recorded in the Activation's materialization lineage may stop its descendant, because stopping a turn is idempotent and delivers no content.
 
 When `ctx.sessionProjections` is available, the service registers two projection units. `subagentTiming` resets at each descriptor so a fork seed's ancestor work cannot enter the child's total, then accumulates `turn/start` → `turn/end` active time and retains same-cut `active.since` and `active.through` bounds for an open turn; while that turn remains open, `active.through` follows the latest folded event, giving an inactive consumer a conservative crash bound without mixing in newer session metadata. `subagent` folds the durable identity — mode plus creation label — from `subagent/descriptor` events with the same last-wins reset discipline, so a fork seed's ancestor descriptor stands only until the child's own overrides it; a malformed or unrecognized-version payload folds to the serializable `null` sentinel — indistinguishable from a log with no descriptor, and surviving every JSON push frame so a consumer replaces a stale identity instead of keeping it — and never throws.
 
@@ -105,6 +105,6 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **No current-turn steering** — continuable messages and waking reports enqueue later turns; neither redirects an open turn.
 - **Wake gap during cancellation convergence** — a waking follow-up accepted after the interrupt signal is issued but before the active driver becomes idle remains queued until another waking send. Issue #1838 owns the agent-loop wake latch, which also affects ordinary session cancellation.
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
-- **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with their admitted provenance. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
+- **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with the source that supplied them. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
 - **No durable report mailbox** — reports require a live direct parent and provide acceptance identity rather than exactly-once delivery or a read receipt.
 - **Lifecycle events are observe-only** — a run-affecting `subagent/end` continuation or decision surface waits for a concrete consumer.
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 52971add96..8d3bc4b96a 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -27,7 +27,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
-后续操作的权限来自子 agent 持久化 header 中记录的确切在线直接父级。冷恢复会在重建前检查该权限，并在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。后续操作上的 `source` 是保留在所投递消息上的持久化来源，不授予任何权限。
+后续操作的权限来自子 agent 持久化 header 中记录的确切在线直接父级。冷恢复会在重建前检查该权限，并在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。后续操作上的 `source` 记录谁提供了所投递的消息，不授予任何权限。
 
 同进程请求、描述符、结果和事件 payload 都是以不可变方式借用的可信类型值。服务不会克隆或冻结它们；序列化和不可信输入校验属于真实的进程、worker、持久化和模型边界。
 
@@ -72,13 +72,13 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 生命周期事件
 
-服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段是生命周期来源信息，而非提供方仍在注册的声明：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
+服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段指明启动该运行或 Activation 时段的提供方，不表示该提供方当前仍在注册：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
 
 运行事件受执行委派的父级作用域约束。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变运行。
 
 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
 
-可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 记录发送方，但不授予权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
 当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使消费方替换陈旧身份而不是将其保留——绝不抛错。
 
@@ -105,6 +105,6 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **取消收敛期间存在唤醒缺口**：中断信号发出后、活动 driver 进入 idle 前被接受的唤醒型 follow-up 会保持排队，直到另一条唤醒发送到达。Issue #1838 负责 agent-loop 的唤醒锁存；普通会话取消也受此影响。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
-- **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同其被接受时的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
+- **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同提供该消息的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
 - **没有持久化的上报 mailbox**：上报需要实时直接父级，提供的是接受标识，不保证恰好一次投递，也不提供已读回执。
 - **生命周期事件只供观察**：影响运行的 `subagent/end` 延续或决策接口仍需等待具体消费方。
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index 67cc177fe1..3425a12851 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -386,7 +386,7 @@ export class SubagentContinuationManager {
    * @param parent - the exact live direct parent authorizing this delivery.
    * @param childId - the durable child session id.
    * @param content - the user-role content to deliver.
-   * @param options - durable provenance and caller cancellation.
+   * @param options - the message source fields and caller cancellation.
    * @returns the accepted message's inbox id.
    * @throws when parent authority, availability, or admission rejects the delivery.
    */
@@ -826,7 +826,7 @@ export class SubagentContinuationManager {
    * Submit to a freshly materialized Activation or roll it back completely.
    * @param activation - the just-published Activation to admit or release.
    * @param content - the initial or resumed message content.
-   * @param source - durable provenance for the accepted message.
+   * @param source - durable fields naming who supplied the accepted message.
    * @param parent - the live direct parent authorizing admission.
    * @param signal - caller cancellation owning admission until acceptance.
    * @returns the accepted inbox message id.
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 2a118565fa..241682c006 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -218,7 +218,7 @@ export class SubagentService extends Service {
    * @param parent - the exact live direct parent authorizing this delivery.
    * @param childId - durable child session id.
    * @param content - user-role content to deliver.
-   * @param options - durable provenance and caller cancellation, which stops the
+   * @param options - the message source fields and caller cancellation, which stops the
    *   operation only before inbox acceptance.
    * @returns the accepted message's inbox id.
    * @throws when continuation services are unavailable, parent authority is
diff --git a/packages/subagent/subagent/src/invariant.ts b/packages/subagent/subagent/src/invariant.ts
index 8797f0513f..d9a497eb77 100644
--- a/packages/subagent/subagent/src/invariant.ts
+++ b/packages/subagent/subagent/src/invariant.ts
@@ -45,7 +45,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
       const info = args[0] as SubagentRunInfo
       // Provider availability is an admission-time relationship. A published
       // one-shot run may outlive provider removal, and a cold-resumed Activation
-      // carries durable provider provenance without dispatching through it.
+      // records the initial provider name without dispatching through it.
       if (info.provider.length === 0 || String(info.runId).length === 0 || String(info.id).length === 0) {
         fail('subagent/start provider, runId, and child id must be non-empty')
       }
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index 91e11ad661..b003b75507 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -37,7 +37,7 @@ export interface SubagentRunInfo {
   /** Unique identity shared with the paired terminal event. */
   readonly runId: SubagentRunId
   /**
-   * Provider provenance for this run or Activation epoch. The named provider
+   * Provider that started this run or Activation epoch. The named provider
    * may be absent when an accepted run becomes ready or a persisted Activation
    * cold-resumes, because neither lifecycle depends on continued registration.
    */
@@ -55,7 +55,7 @@ export interface SubagentRunInfo {
 export interface SubagentRunEndInfo {
   /** Unique identity shared with the paired start event. */
   readonly runId: SubagentRunId
-  /** The same provider provenance carried by the paired start event. */
+  /** The same provider name carried by the paired start event. */
   readonly provider: string
   /** The child agent's id. */
   readonly id: SessionId
diff --git a/packages/subagent/subagent/tests/invariant.spec.ts b/packages/subagent/subagent/tests/invariant.spec.ts
index e288b77a86..21bdda0e06 100644
--- a/packages/subagent/subagent/tests/invariant.spec.ts
+++ b/packages/subagent/subagent/tests/invariant.spec.ts
@@ -80,7 +80,7 @@ describe('subagent invariants', () => {
       .toThrow(/identity diverges/)
   })
 
-  it('accepts historical provider provenance after registration ends', async () => {
+  it('accepts the recorded provider name after registration ends', async () => {
     const ctx = await setup()
     const historical = provider('historical')
     ctx.emit('subagent/provider-added', historical)
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index d25adaad9d..885345b576 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
-README.md: 4d9991b720bbbff8862e693b6aaed332f414af0e
-README.zh.md: 6f7138571fa7f8cb500df1a513f92d1f7f2b82e6
+README.md: 460617378841b791f7d8750962a9e4549643928e
+README.zh.md: 5939a1636a5f92dc797e5788c88bba7048ec7c96
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index 4d9991b720..4606173788 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The optional, globally named `send_message`, `interrupt_agent`, and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and `interrupt_agent` and requires only `subagents`; the separately loadable `./list-agents` plugin registers `list_agents` and declares `subagents` plus `agents` as load-time dependencies. Its catalog reads additionally require the session store and projection registry at call time, but no query service. A deployment can keep the root tools while omitting the list tool. No tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
 
-The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and attributes every message as durable provenance `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
+The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and records every message source as `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
 
 `interrupt_agent(agent_id)` passes `exec.agent` as the exact live ancestor authority for `ctx.subagents.interrupt()`: the target may be a direct child or a deeper descendant, and the service — never this tool — verifies the caller against the target Activation's recorded lineage. Only the target's current turn stops (`keepInbox`): queued messages stay parked until a later `send_message`, published descendants keep running, and the child stays available for follow-ups. The call returns as soon as the stop request is accepted, without waiting for target quiescence; an absent or already-settled target is an accepted no-op, while self, sibling, stale, and non-ancestor callers become errored results.
 
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index 6f7138571f..5939a1636a 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -4,7 +4,7 @@
 
 可选的全局具名 `send_message`、`interrupt_agent` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message` 与 `interrupt_agent`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，并将 `subagents` 与 `agents` 声明为加载时依赖。其目录读取在调用时还要求会话存储与投影注册表，但不要求任何查询服务。部署可保留根插件工具并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
 
-本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
+本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源记录为 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
 `interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
 
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index 9b5f98dd7e..c5ea8fd1b8 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -132,7 +132,7 @@ describe('dsh-tool-subagent-control', () => {
 
     const loaded = await ctx.sessionPersistence.load(started.childId)
     const followUp = loaded.events.findLast(event => event.type === 'user/message')
-    // Durable provenance records the calling agent without granting authority.
+    // The durable message source records the calling agent without granting authority.
     expect(followUp?.type === 'user/message' && followUp.data.source).toEqual({
       kind: 'coordinator',
       form: 'relay',
diff --git a/packages/subagent/tool-subagent-report/README.i18n.yaml b/packages/subagent/tool-subagent-report/README.i18n.yaml
index 1b10e2628a..8d64d7e87f 100644
--- a/packages/subagent/tool-subagent-report/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-report/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-report/README.md
-README.md: cd73154dfb9c8b37f4a811c3beedbe6a63207f58
-README.zh.md: 501598ec4e731b9315f3f08e0c81f5bb655c2b34
+README.md: 1772b72d83563e89ed0e3814e515b06a2b36fe0f
+README.zh.md: 94101fbc9611a04c56ed3a9171889499c9144c21
diff --git a/packages/subagent/tool-subagent-report/README.md b/packages/subagent/tool-subagent-report/README.md
index cd73154dfb..1772b72d83 100644
--- a/packages/subagent/tool-subagent-report/README.md
+++ b/packages/subagent/tool-subagent-report/README.md
@@ -46,7 +46,7 @@ Append-only in the child. In the parent, the framed report follows existing hist
 
 #### What the model sees
 
-One user-role parent message framed as `Background subagent <child-id> reported:` followed by the child's exact `output`, with durable provenance `{ kind: 'subagent-report', senderSessionId: <child-id> }`.
+One user-role parent message framed as `Background subagent <child-id> reported:` followed by the child's exact `output`, with a durable source `{ kind: 'subagent-report', senderSessionId: <child-id> }` that names the child.
 
 #### Token effect
 
diff --git a/packages/subagent/tool-subagent-report/README.zh.md b/packages/subagent/tool-subagent-report/README.zh.md
index 501598ec4e..94101fbc96 100644
--- a/packages/subagent/tool-subagent-report/README.zh.md
+++ b/packages/subagent/tool-subagent-report/README.zh.md
@@ -46,7 +46,7 @@
 
 #### 模型看到的内容
 
-一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级未经改动的 `output`，并带有持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。
+一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级未经改动的 `output`，并带有指明该子级的持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。
 
 #### Token 影响
 
diff --git a/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts b/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts
index ac90b4612b..17d5025c61 100644
--- a/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts
+++ b/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts
@@ -159,7 +159,7 @@ describe('dsh-tool-subagent-report', () => {
     expect(names).not.toContain('send_message')
   })
 
-  it('delivers quiet reports with stable identity and provenance without waking', async () => {
+  it('delivers quiet reports with stable message and sender identities without waking', async () => {
     const { ctx, parent, adapter } = await setup()
     const { started, child } = await startChild(ctx, parent)
     const parentRequests = adapter.requests.filter(request => request.sessionId === parent.id).length
diff --git a/packages/support/invariants/README.i18n.yaml b/packages/support/invariants/README.i18n.yaml
index 44427199b2..9d85ffd0a5 100644
--- a/packages/support/invariants/README.i18n.yaml
+++ b/packages/support/invariants/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/support/invariants/README.md
-README.md: 203dbd5ad09f5b1378061fbf9adcff885889eae2
-README.zh.md: 10f072e1d49b778944dfc0914eab48c527b21fed
+README.md: 71f7fb8b913610aad03694effad7746c0cb16499
+README.zh.md: ce2fc593a294a7f870bb42faa980fab462348e3b
diff --git a/packages/support/invariants/README.md b/packages/support/invariants/README.md
index 203dbd5ad0..71f7fb8b91 100644
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -24,7 +24,7 @@ The service owns every registration fiber, while the returned disposer also belo
 
 `InvariantError` extends `Error`, carries stable `code: 'INVARIANT'`, and exposes the owning `packageName` without adding a product dependency to the service.
 
-Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete provenance and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The `dsh-session` invariant companion checks the remaining cross-record rules that Session does not own.
+Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete cited source-event coverage and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The `dsh-session` invariant companion checks the remaining cross-record rules that Session does not own.
 
 ## Package companions
 
diff --git a/packages/support/invariants/README.zh.md b/packages/support/invariants/README.zh.md
index 10f072e1d4..ce2fc593a2 100644
--- a/packages/support/invariants/README.zh.md
+++ b/packages/support/invariants/README.zh.md
@@ -24,7 +24,7 @@ interface Config {
 
 `InvariantError` 扩展 `Error`，携带稳定 `code: 'INVARIANT'`，并公开所属 `packageName`，而不向服务添加产品依赖。
 
-在每个组合中，Session 自身负责不可变且通过对外接口校验的日志存储：它对每个候选项制作一份无损 JSON 快照，验证完整来源和位置替换，将 `tool/result` 替换限制为一个当前结果的 `content`，深度冻结已接受记录，并通过不可变数组快照公开日志。`dsh-session` 不变量配套入口检查 Session 不负责的其余跨记录规则。
+在每个组合中，Session 自身负责不可变且通过对外接口校验的日志存储：它对每个候选项制作一份无损 JSON 快照，验证引用的源事件是否齐全以及位置替换是否合法，将 `tool/result` 替换限制为一个当前结果的 `content`，深度冻结已接受记录，并通过不可变数组快照公开日志。`dsh-session` 不变量配套入口检查 Session 不负责的其余跨记录规则。
 
 ## 包配套入口
 
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 4be9e01c9d..5c9a575f5c 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -267,7 +267,7 @@ describe('deriveReplayScript', () => {
         seq: 1,
         time: 0,
         data: {
-          summary: [{ type: 'text', text: 'incomplete provenance' }],
+          summary: [{ type: 'text', text: 'missing source events' }],
           llmStreamCall: true,
           shadowedRange: { start: 1, end: 1 },
           shadowedSeqs: [1],
diff --git a/packages/util/environment/package.json b/packages/util/environment/package.json
index 6029a9f52a..15cbb603a5 100644
--- a/packages/util/environment/package.json
+++ b/packages/util/environment/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-environment",
-  "description": "Immutable launch-time environment snapshot with per-layer provenance for the DeepSeek Harness",
+  "description": "Immutable DeepSeek Harness launch environment that records which layer supplied each value",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 741e5752cd..63a59c7337 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * Immutable launch-time environment snapshot with per-value source
- * provenance. Harness consumers resolve through it instead of a flattened
+ * Immutable launch-time environment snapshot that records which layer
+ * supplied each value. Harness consumers resolve through it instead of a flattened
  * `process.env`; launchers may still materialize accepted values for config
  * expressions and third-party libraries.
  * @module @deepseek-ai/dsh-environment
diff --git a/packages/workspace/workspace/src/index.ts b/packages/workspace/workspace/src/index.ts
index 71401862f2..ddd2b901b3 100644
--- a/packages/workspace/workspace/src/index.ts
+++ b/packages/workspace/workspace/src/index.ts
@@ -363,7 +363,7 @@ export class WorkspaceRegistry extends Service {
   /**
    * Complete the one mutation explicitly named by durable state. Unexplained
    * order/table divergence still reaches {@link validateStoredState} and
-   * fails loud; this path never infers provenance from shape alone.
+   * fails loud; this path never guesses which operation created a row from its shape alone.
    */
   private async recoverPendingMutation(): Promise<void> {
     const state = this.requireState()
@@ -608,7 +608,7 @@ export class WorkspaceRegistry extends Service {
   private enqueueOperation<T>(operation: () => Promise<T>): Promise<T> {
     const result = this.operationTail.then(async () => {
       // A committed delete may leave only its marker cleanup pending. Retry
-      // recovery before another create/delete can overwrite that provenance.
+      // recovery before another create/delete can overwrite that pending operation record.
       await this.recoverPendingMutation()
       return await operation()
     })
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 745bc23e4f..7991a7355e 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1230,7 +1230,7 @@ function renderLifecycle(): string {
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
     '```',
     '',
-    'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
+    'The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history, while the durable event keeps usage and `sourceEventSeqs` listing the exact `assistant/chunk` events, including an explicit empty list.',
     '',
     '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',

From 48882aa988b528fb9d1629f8dfff443e6ff14767 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:42:24 +0800
Subject: [PATCH 215/262] test(windows): isolate HMR alias identity

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index 1de504c221..b555645da8 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -8,12 +8,12 @@ import Loader from '@cordisjs/plugin-loader'
 import Timer from '@cordisjs/plugin-timer'
 import { describe, expect, it, vi } from 'vitest'
 
-async function bootHmr(dir: string, root: string[] = []): Promise<Context> {
+async function bootHmr(dir: string, root: string[] = [], usePolling?: boolean): Promise<Context> {
   const ctx = new Context()
   ctx.baseUrl = pathToFileURL(dir).href + '/'
   await ctx.plugin(Loader)
   await ctx.plugin(Timer)
-  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0 })
+  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0, usePolling })
   return ctx
 }
 
@@ -32,7 +32,9 @@ describe('HMR exact config paths', () => {
     const aliasFilename = join(alias, 'module.ts')
     symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
     writeFileSync(aliasFilename, 'export const generation = 0\n')
-    const ctx = await bootHmr(alias, ['.'])
+    // This acceptance owns alias-to-cache identity. Other cases below exercise
+    // native events; polling keeps Windows fs.watch queue pressure out of it.
+    const ctx = await bootHmr(alias, ['.'], true)
     const filename = join(realpathSync(target), 'module.ts')
     const expected = pathToFileURL(filename).href
     const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)

From dcb45aae65b9ac4b37dd57712e62619daecd9040 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:43:01 +0800
Subject: [PATCH 216/262] test(windows): preserve watcher defaults

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index b555645da8..9a1bc250cd 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -13,7 +13,12 @@ async function bootHmr(dir: string, root: string[] = [], usePolling?: boolean):
   ctx.baseUrl = pathToFileURL(dir).href + '/'
   await ctx.plugin(Loader)
   await ctx.plugin(Timer)
-  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0, usePolling })
+  await ctx.plugin(Hmr, {
+    root,
+    ignored: [],
+    debounce: 0,
+    ...usePolling === undefined ? {} : { usePolling },
+  })
   return ctx
 }
 

From 3766e333b1cfee2cf53842eebeae024c73fe9c29 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:51:34 +0800
Subject: [PATCH 217/262] test(snapshot): refresh session query tool schema

---
 .../snapshots/session-query-spill/tool-schemas.expected.json    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 7719bd3193..aed34842df 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -298,7 +298,7 @@
     },
     {
       "name": "session_event_trace",
-      "description": "Read every direct replacement and provenance relationship for one event in an authorized session.",
+      "description": "Read every direct replacement and relationship to a cited source event for one event in an authorized session.",
       "parameters": {
         "type": "object",
         "properties": {

From 96beea5cad22735d7c3f3bc8f3b8665a76f8cfbc Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 16:02:05 +0800
Subject: [PATCH 218/262] fix(docs): align merged contract terminology

---
 ...24-web-config-tree-boot-and-transport-layering.i18n.yaml | 2 +-
 ...-07-24-web-config-tree-boot-and-transport-layering.zh.md | 2 +-
 .../2026-08-05-profile-plugin-bundles.i18n.yaml             | 2 +-
 .../architecture/2026-08-05-profile-plugin-bundles.zh.md    | 2 +-
 .../2026-08-09-headless-direct-core-front-door.i18n.yaml    | 2 +-
 .../2026-08-09-headless-direct-core-front-door.zh.md        | 6 +++---
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index 2ee0de0625..ff517555db 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
 2026-07-24-web-config-tree-boot-and-transport-layering.md: 496499a691dbca012e5e953cbb6eb1d0bf25b635
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4a83db6f797ad2a0b048ef996d10dbc5ea0a33dd
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: c4bed7b730cf37e1d90750f5c93fbccb920ced21
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index 4a83db6f79..c4bed7b730 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的契约。
+- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的约定。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## 考虑过的替代方案
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index f5c23bd7e3..f68aeb97b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
 2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
-2026-08-05-profile-plugin-bundles.zh.md: 294082249c2d3244321cb7efabf0eb286d11ef46
+2026-08-05-profile-plugin-bundles.zh.md: 8887bd39b7d0002f7c683ec74b7c91f002b18406
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 294082249c..8887bd39b7 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
-随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合契约。
+随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合约定。
 
 [`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
index 921bc193e4..4088beaa7d 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
 2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
-2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f
+2026-08-09-headless-direct-core-front-door.zh.md: ff05661513f784ed735f823cf2a8ac28b267f694
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
index 7de5efbe17..ff05661513 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`headless` 的产品契约是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一契约，也使本地完成状态依赖无关的传输树。
+`headless` 的产品约定是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一约定，也使本地完成状态依赖无关的传输树。
 
 直接前门仍需要与 Web 所创建 Agent 相同的部署模型状态。独立的提供方／模型默认值会让同一部署产生两种答案，而在 Agent 与会话持久化完全停稳之前推导完成状态，会让 stdout 与退出状态观察到不完整状态。
 
@@ -20,7 +20,7 @@ Status: implemented
 
 `loadProfile` 识别安装过程拥有的精确 headless 元组（`dsh-base`、`dsh-web-app`、`dsh-headless`），将其规范化为随附的 headless 模板，并保留 manifest（元数据清单）的其他所有字段。带额外项、缺少项或顺序不同的组合包列表归用户所有，保持不变。
 
-本 Agent Note 负责 headless 的传输与完成契约。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
+本 Agent Note 负责 headless 的传输与完成约定。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
 
 ## 验证
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-| 替代方案 | 契约不匹配之处 |
+| 替代方案 | 约定不匹配之处 |
 |---|---|
 | 保留 `dsh-web-app`，但隐藏观察行 | 进程仍会打开端口并携带 Host、Web 与浏览器插件树。 |
 | 围绕 ApiProxy 构建纯 Host 一次性组合包 | ApiProxy 是客户端协议网关，而本地一次性前门没有客户端边界。 |

From 93e858faf969881c49e4fc3dc0e141b5527e542b Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 16:31:15 +0800
Subject: [PATCH 219/262] docs: address prose review findings

---
 .../2026-06-18-session-surface.i18n.yaml          |  4 ++--
 .../architecture/2026-06-18-session-surface.md    |  2 +-
 .../architecture/2026-06-18-session-surface.zh.md |  2 +-
 ...8-09-headless-direct-core-front-door.i18n.yaml |  4 ++--
 .../2026-08-09-headless-direct-core-front-door.md |  4 ++--
 ...26-08-09-headless-direct-core-front-door.zh.md |  4 ++--
 .../feature/2026-07-06-sandbox.i18n.yaml          |  4 ++--
 .../implemented/feature/2026-07-06-sandbox.md     |  2 +-
 .../implemented/feature/2026-07-06-sandbox.zh.md  |  2 +-
 .../2026-08-05-context-form-vocabulary.i18n.yaml  |  4 ++--
 .../feature/2026-08-05-context-form-vocabulary.md |  2 +-
 .../2026-08-05-context-form-vocabulary.zh.md      |  2 +-
 docs/config-catalog.md                            |  7 ++++---
 docs/persistence-catalog.md                       |  3 ++-
 docs/subsystems/session.i18n.yaml                 |  4 ++--
 docs/subsystems/session.md                        | 15 ++++++++-------
 docs/subsystems/session.zh.md                     | 15 ++++++++-------
 packages/bash/bash-sandbox/README.i18n.yaml       |  4 ++--
 packages/bash/bash-sandbox/README.md              |  4 ++--
 packages/bash/bash-sandbox/README.zh.md           |  4 ++--
 packages/core/session/README.i18n.yaml            |  4 ++--
 packages/core/session/README.md                   |  2 +-
 packages/core/session/README.zh.md                |  2 +-
 packages/core/session/src/types.ts                |  9 +++++----
 packages/host/apiproxy/src/api-proxy.ts           |  7 ++++---
 packages/sandbox/sandbox-local/src/index.ts       |  7 ++++---
 .../tests/tool-session-query.spec.ts              |  1 +
 packages/subagent/subagent/README.i18n.yaml       |  4 ++--
 packages/subagent/subagent/README.md              |  2 +-
 packages/subagent/subagent/README.zh.md           |  2 +-
 packages/subagent/subagent/src/types.ts           |  7 ++++---
 31 files changed, 74 insertions(+), 65 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index b400a7b6c7..c10a8a497c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: 3a033960e7cbf577c69c1df9940e064ef34163d3
-2026-06-18-session-surface.zh.md: 5c1348595589e8b69b0fe4a679f2536a83ef3142
+2026-06-18-session-surface.md: 73b3ab9080506edb9b0693c22a4c30544b506c11
+2026-06-18-session-surface.zh.md: 0c7ebbacd2f89da8012f3c08f1e4354a1d6c2e8e
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 3a033960e7..73b3ab9080 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -16,7 +16,7 @@ Add a **surface** — a derived, cached order of event sequences (the subset of
 
 Every `SessionEvent` gains two optional fields (structural metadata, like `seq`/`time`):
 
-- **`sourceEventSeqs?: number[]`** — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means a legacy or foreign event did not record the stream. Other surface events require a non-empty list when the field is present. Without these cited seqs, replay cannot validate that a replace-range operation names every event it removed.
+- **`sourceEventSeqs?: number[]`** — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; when the field is absent, a legacy or foreign event does not record which earlier events produced the message. Other surface events require a non-empty list when the field is present. Without these cited seqs, replay cannot validate that a replace-range operation names every event it removed.
 - **`surfaceOp?: SurfaceOp`** — how this event entered the surface. Absent for non-surface events.
 
 ### SurfaceOp: two operations
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index 5c13485955..0c7ebbacd2 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 每个 `SessionEvent` 获得两个可选字段（结构性元数据，与 `seq`/`time` 同级）：
 
-- **`sourceEventSeqs?: number[]`**：被引用为数据来源的早期事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段，表示某个旧事件或外部事件没有记录该流。其他 surface 事件一旦出现此字段，就必须是非空列表。如果没有这些引用的 seq，回放就无法验证 replace-range 操作是否列出了它移除的每个事件。
+- **`sourceEventSeqs?: number[]`**：被引用为数据来源的早期事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；旧格式或外部事件缺少该字段时，没有记录这条消息由哪些早期事件产生。其他 surface 事件一旦出现此字段，就必须是非空列表。如果没有这些引用的 seq，回放就无法验证 replace-range 操作是否列出了它移除的每个事件。
 - **`surfaceOp?: SurfaceOp`**：该事件如何进入 surface。非 surface 事件不携带此字段。
 
 ### SurfaceOp：两种操作
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
index 921bc193e4..46d4a76284 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.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 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
-2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
-2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f
+2026-08-09-headless-direct-core-front-door.md: f4604329a9276448a0021bb749b09e8c1b82e3c1
+2026-08-09-headless-direct-core-front-door.zh.md: 1299840f84eb4dacb093f1e6551bef03636b338f
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
index 875939b424..f4604329a9 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
@@ -24,7 +24,7 @@ This note owns the headless transport and completion contracts. [`dsh run` owns
 
 ## Verification
 
-Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record direct user-message provenance, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record a `user/message` with `source.kind: 'user'`, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
 
 ## Alternatives considered
 
@@ -39,6 +39,6 @@ Package tests use the real Session store and Agent registry around a scripted Ag
 
 ## Consequences
 
-`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message has direct user provenance and therefore carries no ApiProxy `rpcId`.
+`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message records `source.kind: 'user'` and therefore carries no ApiProxy `rpcId`.
 
 ApiProxy carrier coverage stays in the ApiProxy package. Custom one-shot profiles may include Host or Web bundles explicitly, while the shipped profile and the recognized installation-owned tuple are Web-free.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
index 7de5efbe17..1299840f84 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 验证
 
-包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录直接用户消息的来源，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录一条带 `source.kind: 'user'` 的 `user/message`，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
 
 ## 考虑过的替代方案
 
@@ -39,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息直接来自用户，因此不携带 ApiProxy `rpcId`。
+`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息记录 `source.kind: 'user'`，因此不携带 ApiProxy `rpcId`。
 
 ApiProxy 载体覆盖保留在 ApiProxy 包中。自定义一次性 profile 可以显式包含 Host 或 Web 组合包；随附 profile 与可识别的安装过程所属元组均不含 Web。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 5982d816f9..fdb075d228 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: d73bb5520ffba43142c70e3197ae033db1af67d9
-2026-07-06-sandbox.zh.md: 5fc2ee7c4a53df22fab93c358824a10dca89989e
+2026-07-06-sandbox.md: 943b1e27ff2d61a56e5532a20b9983d181c15e29
+2026-07-06-sandbox.zh.md: 89a73afb6154363b9d3e7c1afedbda386994325a
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index d73bb5520f..943b1e27ff 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -70,7 +70,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La
 
 #### The bash consumer
 
-`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection is runner-owned only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` whose error path equals provider argv[0]; a bare `syscall: 'spawn'` without an exact error path, other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner-owned rejections to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same shape with the runner path makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code gate and a remaining fatal line after informational exclusions. A match outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
+`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection counts as a runner failure only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn <runner>'`; a present path also requires `syscall: 'spawn'` or the exact `spawn <runner>`. Other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner failures to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same runner-identifying shape makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code check and a remaining fatal line after informational exclusions. A match takes priority over denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
 
 The model sees the current effective file policy in the owner-derived `sandbox:policy` context, while the static tool description explains the denial marker (`[sandbox: file access denied under <mode> mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](2026-07-30-current-sandbox-policy-context.md) owns the context's rationale and boundaries.
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 5fc2ee7c4a..89a73afb61 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -70,7 +70,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 
 
 #### bash 消费方
 
-`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，拒绝才会归因于 runner；没有精确错误路径的裸 `syscall: 'spawn'`、其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将可归因于 runner 的拒绝转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样带有 runner 路径的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码门控与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
+`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，Node 报告 `ENOENT` 或 `EACCES`，并且错误符合以下一种形态时，才判定为 runner 失败：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn <runner>'`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn <runner>'`。其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将 runner 失败转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样能指明 runner 的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码检查与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
 
 模型会在归属方派生的 `sandbox:policy` 上下文中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under <mode> mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](2026-07-30-current-sandbox-policy-context.md)负责该上下文的理由与边界。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index e407eccd64..1ae3905478 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 7750523b89ebdda125a7bae8a853ab28a20eeb3f
-2026-08-05-context-form-vocabulary.zh.md: 8a6ced60b254ddf5e9075d199be98b3fbe442e2b
+2026-08-05-context-form-vocabulary.md: 3362059974443d1f6b543358e1eaba99ef239e43
+2026-08-05-context-form-vocabulary.zh.md: cee66c0b39f6dadd8579d7d95c4051e0c712e620
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 7750523b89..3362059974 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -51,7 +51,7 @@ The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure fu
 
 **Map source kinds to renderers in the client.** Cheapest to write and requires no format change, but it puts producer knowledge back in the client: every new kind then needs a client release to render as anything but opaque, and a foreign log cannot be classified at all. It also reintroduces exactly the coupling the [source and steer marks decision](2026-08-04-web-context-source-and-steer-marks.md) removed for labels.
 
-**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. It breaks on the shared shapes: three producers emit runtime snapshots today, and folding them into one kind would erase which producer supplied each message. Two axes keep the producer exact while letting presentations be shared.
+**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. This design loses information when several producers share one form: three producers emit runtime snapshots today, and combining them into one kind would make it impossible to tell which producer supplied each message. Separate `kind` and `form` fields record the producer while allowing several producers to share one presentation.
 
 **Let the client parse the model-facing prose.** The entries and file sections are visibly structured in the text. Parsing them couples the presentation to prompt wording, so every reword silently breaks a card — the same reason catalog identity moved off the text.
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 8a6ced60b2..cee66c0b39 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -51,7 +51,7 @@ Status: implemented
 
 **在客户端把来源 kind 映射到渲染器。** 写起来最省，也不用改格式，但它把生产方知识放回了客户端：此后每新增一个 kind 都要客户端发版才能渲染成 opaque 以外的东西，而外部日志根本无法分类。它还会重新引入[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)刚为名称去掉的那种耦合。
 
-**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但它在共享形状上就崩了：今天有三个生产方发出运行时快照，把它们并成一个 kind 会删除每条消息中标明其生产方的 `source` 字段。两根轴会保留准确的生产方，同时让呈现方式可以共享。
+**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但多个生产方共享同一形态时，这种设计无法保留完整信息：今天有三个生产方发出运行时快照，把它们并成一个 kind 后，将无法分辨每条消息由哪个生产方提供。独立的 `kind` 和 `form` 字段会记录生产方，同时允许多个生产方共用一种呈现方式。
 
 **让客户端解析面向模型的散文。** 条目与文件分节在文本里确实有可见结构。解析它们会把呈现耦合到 prompt 措辞上，于是每改一次文案就静默碎掉一张卡——这也正是目录身份从文本上迁走的原因。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 4c49120f17..e1d0374afa 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1196,9 +1196,10 @@ export interface Config {
    * Override the runner argv; bwrap-shaped profile arguments are appended. A
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
-   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
-   * infrastructure failure.
+   * {@link runnerFailureSignatures}. Consumers classify a spawn rejection only after
+   * confirming the workdir is usable. `ENOENT` or `EACCES` identifies the runner when
+   * `error.path` equals argv[0] and `error.syscall` is `spawn` or `spawn <runner>`, or
+   * when `error.path` is absent and `error.syscall` is exactly `spawn <runner>`.
    */
   runnerCommand?: string[]
   /**
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 975a882706..614f6afbeb 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -68,7 +68,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 890563b91d..da4ec0a16b 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 6fb39e946cf5acdc407aab99888d40960d617248
-session.zh.md: 30edd630b4c945d3b696b5ac346b4bcebfb3df16
+session.md: 4b057317969c8dc59c899fb07812e01a0b5d94d3
+session.zh.md: 804edc32635ddfcc1335ecd9c0a6c4df4f998594
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 6fb39e946c..4b05731796 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -221,7 +221,8 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -232,7 +233,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`.
 
-For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means the source stream was not recorded in a legacy or foreign event. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
+For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while a legacy or foreign event with no field does not record which earlier events produced the message. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
 
 ## Surface types
 
@@ -285,9 +286,9 @@ interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a
-   * present empty array for a known empty provider stream; omission means its
-   * source stream was not recorded. Other surface events require a non-empty set
-   * when this field is present.
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
    */
   sourceEventSeqs?: number[]
 }
@@ -295,7 +296,7 @@ interface SurfaceIntent {
 
 Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived model history. A human-facing transcript is the other projection and reads the log's append-origin events instead, because the surface deliberately shadows the ranges a replacement summarizes (`isAppendSurfaceEvent` in [dsh-session](../../packages/core/session/README.md)). Non-surface types reject it at compile time.
 
-Only `assistant/message` may carry a present empty `sourceEventSeqs`; omission means the source stream was not recorded and does not assert that the stream was empty.
+Only `assistant/message` may carry a present empty `sourceEventSeqs`; when the field is absent, the event does not record which earlier events produced the message, and the provider may still have emitted chunks.
 
 ### `SessionSurface` — the live readonly surface projection
 
@@ -577,7 +578,7 @@ Activity ordering excludes the boundary through `lastActivityTime(events)`: pick
 
 ## Plugin-contributed log-only events
 
-A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, cited source-event seqs, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
+A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
 
 The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 30edd630b4..804edc3263 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -223,7 +223,8 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -234,7 +235,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展，对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`：插件添加的变体是合法的未知值；处理已知 case 后在 `default` 中放行。
 
-对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或外部事件没有记录源流。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
+对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；旧格式或外部事件缺少该字段时，没有记录这条消息由哪些早期事件产生。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
 
 ## Surface 类型
 
@@ -287,9 +288,9 @@ interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a
-   * present empty array for a known empty provider stream; omission means its
-   * source stream was not recorded. Other surface events require a non-empty set
-   * when this field is present.
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
    */
   sourceEventSeqs?: number[]
 }
@@ -297,7 +298,7 @@ interface SurfaceIntent {
 
 对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生模型历史的唯一来源）。面向人类的记录（transcript）是另一个投影，读取的是日志中追加来源的事件，因为 surface 会有意遮蔽替换所概括的范围（见 [dsh-session](../../packages/core/session/README.md) 的 `isAppendSurfaceEvent`）。非 surface 类型在编译期拒绝此参数。
 
-只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段表示源流没有记录，而不是表示源流为空。
+只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；字段不存在时，该事件没有记录这条消息由哪些早期事件产生，但提供方仍可能发出过分片。
 
 ### `SessionSurface`：实时只读 surface 投影
 
@@ -581,7 +582,7 @@ interface TurnEndReasonMap {
 
 ## 插件贡献的仅日志事件
 
-插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记、被引用的来源事件 seq 和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
+插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
 
 钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index 97ea5f301b..426f2901e5 100644
--- 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: 3ac46eaef8a0c6ee47c3141e2580c4d2e7750e8c
-README.zh.md: 4f3fb85c8de00497e4aff546d8234a81336586cb
+README.md: 884681ec73990af600833756caf5dd7305b0d481
+README.zh.md: a19b4cae4606a56ae5ce496fa9f0c10ba2eb9156
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 3ac46eaef8..884681ec73 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -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 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` whose error path equals 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 `ENOENT`/`EACCES` shape with the runner path, 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.
+- **The runner path or syscall must match.** 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 either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn <runner>'`. A present path also requires `syscall: 'spawn'` or the exact `spawn <runner>`. 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 runner-identifying `ENOENT`/`EACCES` shape, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code check and a remaining fatal stderr line must both match after exact informational-line exclusions. A match takes priority over 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/).
@@ -70,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). 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.
+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` path or syscall evidence that names argv[0] 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
 
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index 4f3fb85c8d..a19b4cae46 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -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 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码门控和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
+- **Runner 路径或 syscall 必须匹配。** 进程启动前，调用方拥有的 workdir 必须经独立验证可用，Node 必须报告 `ENOENT` 或 `EACCES`，并且错误必须符合以下一种形态：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn <runner>'`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn <runner>'`。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样能指明 runner 的 `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/)。
@@ -70,7 +70,7 @@
 
 #### 模型看到的内容
 
-如果没有 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` 前缀。
+如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误](../../sandbox/sandbox/README.md#confinement-error-indirectly)；该错误由 `dsh-sandbox` 定义。判定为 runner 失败的 spawn 错误会以原始 spawn 错误作为详细信息；如果拒绝没有通过 `ENOENT`／`EACCES` 的 `path` 或 `syscall` 证据指明 `argv[0]`，它仍是普通的命令启动错误。已结算的 runner 失败则以匹配到的致命 stderr 行作为详细信息，并保留原始 stderr 收集结果。如果追加了 `Runner failure: <detail>`，它就是权威诊断；前面的后端安装文本只是通用的 `SANDBOX_UNAVAILABLE` 前缀。
 
 #### Token 影响
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 67364cb415..71cb01a34d 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 04d3cec7e431f5f265d52851eae59600536ce5b7
-README.zh.md: e9529b3c91c8d2413c64b4e344af83b6ebe698de
+README.md: 09e027c82fe1a81d97b3e70d95231ccc553e3ed1
+README.zh.md: 3fdd1e68b18f5ce4b3846ca0d2376b968a0754e3
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 04d3cec7e4..09e027c82f 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -68,7 +68,7 @@ A `user/message` stores the complete `UserMessage` directly, including the ident
 
 ### Session event vocabulary (`types.ts`)
 
-The generated [persistence log event catalog](../../../docs/persistence-catalog.md) enumerates each append-only event type with its payload, surface badge, cited source-event seqs, and declaration site. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Each `assistant/message` records the provider, model, and optional replay state.
+The generated [persistence log event catalog](../../../docs/persistence-catalog.md) enumerates each append-only event type with its payload, surface badge, and declaration site. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Each `assistant/message` records the provider, model, and optional replay state.
 
 Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, bounded recovery's non-surface `llm/retry`, the hook bridges' `hook/*`); merged members appear in the same catalog. A plugin owns the relational invariant for its merged events, including whether a log-only event may appear between turns. A producer that requires durability appends through `Session` and then awaits `ctx.sessions.flush(session)` without fabricating an execution turn.
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index e9529b3c91..3fdd1e68b1 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -68,7 +68,7 @@
 
 ### 会话事件词汇（`types.ts`）
 
-生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记、被引用的源事件 seq 与声明位置。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。每条 `assistant/message` 都会记录提供方、模型和可选回放状态。
+生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记与声明位置。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。每条 `assistant/message` 都会记录提供方、模型和可选回放状态。
 
 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。
 
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index c1071e1e01..1c9a622643 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -352,9 +352,9 @@ export interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a
-   * present empty array for a known empty provider stream; omission means its
-   * source stream was not recorded. Other surface events require a non-empty set
-   * when this field is present.
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
    */
   sourceEventSeqs?: number[]
 }
@@ -386,7 +386,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index a4ce497c1d..fde6cd32ee 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1506,9 +1506,10 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               )
             }
             // Host visibility is the authorization boundary. Consume the
-            // provider's globally ranked stream rather than binding every
-            // visible id into one SQLite statement, then re-check complete
-            // provider id before emitting any snippet.
+            // provider's globally ranked results rather than binding every
+            // visible id into one SQLite statement, then require each hit to
+            // name a visible session and a current message from that same
+            // session before emitting its snippet.
             for (const hit of page.items) {
               if (authorized.length > SESSION_SEARCH_RESULT_LIMIT) continue
               if (
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 0b1cf3a34d..67698f80b4 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -26,9 +26,10 @@ export interface Config {
    * Override the runner argv; bwrap-shaped profile arguments are appended. A
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
-   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
-   * infrastructure failure.
+   * {@link runnerFailureSignatures}. Consumers classify a spawn rejection only after
+   * confirming the workdir is usable. `ENOENT` or `EACCES` identifies the runner when
+   * `error.path` equals argv[0] and `error.syscall` is `spawn` or `spawn <runner>`, or
+   * when `error.path` is absent and `error.syscall` is exactly `spawn <runner>`.
    */
   runnerCommand?: string[]
   /**
diff --git a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
index db1cc4483b..23ca3f939e 100644
--- a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
+++ b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
@@ -1978,6 +1978,7 @@ describe('trace and exact read rendering', () => {
     )
     const result = await mounted.call('session_event_trace', { session_id: session.id, seq: 0 })
     expect(text(result)).toContain('Replacement chain: 1')
+    expect(text(result)).toContain('Events cited directly as sources: none')
     expect(text(result)).toContain('Direct derived events: 1')
     expect(text(result)).toContain(new Date(session.events[0]?.time ?? 0).toISOString())
   })
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index e1ba59aa50..4fac8ecd2e 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: 7658dad2fc8d79ca178ed5467448de9527f7bc49
-README.zh.md: 8d3bc4b96ac366e919256f4409ebd54d3505de87
+README.md: a1b5807e5e9e880879e39e0bacaa1a54743f227e
+README.zh.md: 823227af1841730c8fd926295bf7c4ca74497255
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7658dad2fc..a1b5807e5e 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -72,7 +72,7 @@ A continuation-managed parent Activation records each child Session id in an `ow
 
 ## Lifecycle events
 
-The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field names the provider that started the run or Activation epoch rather than claiming current registration: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch retains its descriptor's initial provider name without requiring that provider to be registered.
+The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field contains the provider name recorded when the child was first created rather than claiming current registration: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch reads the initial provider name from its descriptor without calling or registering that provider.
 
 Run events are scoped to the delegating parent. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peer listeners or changing the run.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 8d3bc4b96a..823227af18 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -72,7 +72,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 生命周期事件
 
-服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段指明启动该运行或 Activation 时段的提供方，不表示该提供方当前仍在注册：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
+服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段包含子 agent 初次创建时记录的提供方名称，不表示该提供方当前仍在注册：已接受的一次性 run 可在提供方移除后才结算；冷恢复时段会从描述符读取初始提供方名称，不会调用或注册该提供方。
 
 运行事件受执行委派的父级作用域约束。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变运行。
 
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index b003b75507..f83b65f559 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -37,9 +37,10 @@ export interface SubagentRunInfo {
   /** Unique identity shared with the paired terminal event. */
   readonly runId: SubagentRunId
   /**
-   * Provider that started this run or Activation epoch. The named provider
-   * may be absent when an accepted run becomes ready or a persisted Activation
-   * cold-resumes, because neither lifecycle depends on continued registration.
+   * Provider name recorded when the child was first created. The provider may
+   * be absent when an accepted one-shot run becomes ready or a persisted
+   * Activation cold-resumes, because neither lifecycle depends on continued
+   * registration.
    */
   readonly provider: string
   /** The child agent's id. */

From 455e6ec583d3bdbc5deebf229af5e0b7b488348e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:40:13 +0800
Subject: [PATCH 220/262] fix(hmr): await module watcher readiness

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  2 +-
 ...08-08-native-windows-pull-request-ci.zh.md |  2 +-
 vendor/README.md                              |  2 +-
 vendor/hmr/src/index.ts                       | 41 ++++++++++++++-----
 5 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 8cc2763444..75d7f8b670 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: e98de723dfe118a297a2e9074d94d52dd6dddc47
-2026-08-08-native-windows-pull-request-ci.zh.md: 02ad94b095c8fd1361c4b113d486f8091bb9cf5a
+2026-08-08-native-windows-pull-request-ci.md: 4e2ea07e90656f212f0613ffa17184ff2c3c8c45
+2026-08-08-native-windows-pull-request-ci.zh.md: 306243af3f3e0b280dd25caa5c99df2176590f3b
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index e98de723df..4e2ea07e90 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -16,7 +16,7 @@ Every pull request also starts an independent `windows-native` job named `window
 
 The native gate keeps workspace build and production-site failures blocking inside its own job while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
-The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
+The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path. Module HMR attaches listeners and awaits the main watcher's ready event before plugin startup settles, so an immediate post-boot edit cannot race the initial scan.
 
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 02ad94b095..306243af3f 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 原生门禁在其自身作业内继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
-首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
+首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。模块 HMR 会挂接监听器并等待主 watcher 的 ready 事件，之后插件启动才会完成，因此启动后立即发生的编辑无法与初始扫描形成竞态。
 
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
diff --git a/vendor/README.md b/vendor/README.md
index a5e998ef39..c2004c36e0 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -38,7 +38,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory and use that spelling for Node module-cache identity; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while exact-config callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory, attach change listeners before declaring the service ready, and use that spelling for Node module-cache identity; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while exact-config callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
 10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. The temporary command directory is removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and obtains both its build and prepare commands from declared dependencies.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
diff --git a/vendor/hmr/src/index.ts b/vendor/hmr/src/index.ts
index 7c36201b13..169ee2e00a 100644
--- a/vendor/hmr/src/index.ts
+++ b/vendor/hmr/src/index.ts
@@ -214,6 +214,17 @@ class Hmr extends Service {
 
     const match = picomatch(ignored)
     const watchBaseDir = await realpath(this.baseDir)
+
+    // Collect externals before opening the watcher so every post-ready change
+    // is observed by listeners that already have their classification state.
+    const mainUrl = pathToFileURL(resolve(process.argv[1])).href
+    const mainJob = this.internal.loadCache.get(mainUrl)
+    if (mainJob) {
+      this.externals = await loadDependencies(mainJob)
+    } else {
+      this.externals = new Set()
+    }
+
     this.watcher = watch(root, {
       ...this.config,
       cwd: watchBaseDir,
@@ -228,16 +239,6 @@ class Hmr extends Service {
       ignoreInitial: true,
     })
 
-    // Collect externals: framework modules reachable from the main entry.
-    // Changes to these files require a full process restart, not HMR.
-    const mainUrl = pathToFileURL(resolve(process.argv[1])).href
-    const mainJob = this.internal.loadCache.get(mainUrl)
-    if (mainJob) {
-      this.externals = await loadDependencies(mainJob)
-    } else {
-      this.externals = new Set()
-    }
-
     const partialReload = this.ctx.debounce(() => this.partialReload(), this.config.debounce)
 
     const onChange = (kind: 'add' | 'change' | 'unlink', path: string) => {
@@ -271,6 +272,26 @@ class Hmr extends Service {
     this.watcher.on('add', path => onChange('add', path))
     this.watcher.on('change', path => onChange('change', path))
     this.watcher.on('unlink', path => onChange('unlink', path))
+
+    const ready = Promise.withResolvers<void>()
+    let readyState: 'pending' | 'resolved' | 'rejected' = root.length === 0 ? 'resolved' : 'pending'
+    if (root.length === 0) {
+      ready.resolve()
+    } else {
+      this.watcher.once('ready', () => {
+        readyState = 'resolved'
+        ready.resolve()
+      })
+    }
+    this.watcher.on('error', (error) => {
+      if (readyState === 'pending') {
+        readyState = 'rejected'
+        ready.reject(error)
+      } else {
+        this.ctx.logger.warn(error)
+      }
+    })
+    await ready.promise
   }
 
   private refreshConfig(key: object, filename: string, refresh: () => Promise<void> | void) {

From 829e874ed2d42fc0dd2916797384b540511b3f06 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 16:42:54 +0800
Subject: [PATCH 221/262] docs: keep prose rule within budget

---
 docs/AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 4dc640fa93..a7e6b06747 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -42,7 +42,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write for professional programmers. Use concise, direct English without metaphor. Name the actor, source, event, field, or process; use words you would say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Do not overuse "gate", "vocabulary", "surface", or "seam".
+- Write directly without metaphor. Name actors and exact facts; use words you'd say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Avoid "gate", "vocabulary", "surface", or "seam".
 
 ## Wordcount Budgets
 

From e94cacd088273a31a3ae19ea33f95ffc90c237f1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:50:20 +0800
Subject: [PATCH 222/262] test(hmr): separate repeated watcher failures

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index 9a1bc250cd..dbb3a8ca83 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -185,6 +185,9 @@ describe('HMR exact config paths', () => {
       expect(observed.error).toBeInstanceOf(Error)
       expect(observed.error.message).toBe('42')
 
+      // Let Chokidar's atomic-write window close before requiring a distinct
+      // second notification from the same path.
+      await new Promise(resolve => setTimeout(resolve, 250))
       writeFileSync(filename, 'invalid again')
       await eventually(() => failureCount === 2, 'HMR stopped broadcasting after an observer rejected')
     } finally {

From 27ac49e6877e638d9c9d91c30316875a052d2b80 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 14:45:32 +0800
Subject: [PATCH 223/262] docs: define a seam as the (Service, Service
 provider, Consumer) trio

---
 .../architecture/2026-06-13-capability-seams.i18n.yaml      | 4 ++--
 .../implemented/architecture/2026-06-13-capability-seams.md | 4 ++++
 .../architecture/2026-06-13-capability-seams.zh.md          | 4 ++++
 AGENTS.md                                                   | 2 +-
 docs/architecture.i18n.yaml                                 | 4 ++--
 docs/architecture.md                                        | 4 +++-
 docs/architecture.zh.md                                     | 4 +++-
 docs/glossary.i18n.yaml                                     | 4 ++--
 docs/glossary.md                                            | 4 ++++
 docs/glossary.zh.md                                         | 4 ++++
 docs/i18n/terminology.md                                    | 2 +-
 docs/subsystems/bash.i18n.yaml                              | 4 ++--
 docs/subsystems/bash.md                                     | 4 ++--
 docs/subsystems/bash.zh.md                                  | 4 ++--
 docs/subsystems/code-runtime.i18n.yaml                      | 4 ++--
 docs/subsystems/code-runtime.md                             | 4 ++--
 docs/subsystems/code-runtime.zh.md                          | 4 ++--
 docs/subsystems/compaction.i18n.yaml                        | 4 ++--
 docs/subsystems/compaction.md                               | 4 ++--
 docs/subsystems/compaction.zh.md                            | 4 ++--
 docs/subsystems/credentials.i18n.yaml                       | 4 ++--
 docs/subsystems/credentials.md                              | 4 ++--
 docs/subsystems/credentials.zh.md                           | 4 ++--
 docs/subsystems/filesystem.i18n.yaml                        | 4 ++--
 docs/subsystems/filesystem.md                               | 6 +++---
 docs/subsystems/filesystem.zh.md                            | 6 +++---
 docs/subsystems/persistence.i18n.yaml                       | 4 ++--
 docs/subsystems/persistence.md                              | 6 +++---
 docs/subsystems/persistence.zh.md                           | 6 +++---
 docs/subsystems/sandbox.i18n.yaml                           | 4 ++--
 docs/subsystems/sandbox.md                                  | 4 ++--
 docs/subsystems/sandbox.zh.md                               | 4 ++--
 docs/subsystems/session-query.i18n.yaml                     | 4 ++--
 docs/subsystems/session-query.md                            | 4 ++--
 docs/subsystems/session-query.zh.md                         | 4 ++--
 docs/subsystems/settings.i18n.yaml                          | 4 ++--
 docs/subsystems/settings.md                                 | 4 ++--
 docs/subsystems/settings.zh.md                              | 4 ++--
 docs/subsystems/spill.i18n.yaml                             | 4 ++--
 docs/subsystems/spill.md                                    | 4 ++--
 docs/subsystems/spill.zh.md                                 | 4 ++--
 docs/subsystems/subprocess.i18n.yaml                        | 4 ++--
 docs/subsystems/subprocess.md                               | 6 +++---
 docs/subsystems/subprocess.zh.md                            | 6 +++---
 docs/subsystems/tasks.i18n.yaml                             | 4 ++--
 docs/subsystems/tasks.md                                    | 4 ++--
 docs/subsystems/tasks.zh.md                                 | 4 ++--
 docs/subsystems/telemetry.i18n.yaml                         | 4 ++--
 docs/subsystems/telemetry.md                                | 6 +++---
 docs/subsystems/telemetry.zh.md                             | 6 +++---
 docs/subsystems/workflow.i18n.yaml                          | 4 ++--
 docs/subsystems/workflow.md                                 | 4 ++--
 docs/subsystems/workflow.zh.md                              | 4 ++--
 docs/subsystems/workspace.i18n.yaml                         | 4 ++--
 docs/subsystems/workspace.md                                | 4 ++--
 docs/subsystems/workspace.zh.md                             | 4 ++--
 packages/bash/bash/README.i18n.yaml                         | 4 ++--
 packages/bash/bash/README.md                                | 2 +-
 packages/bash/bash/README.zh.md                             | 2 +-
 packages/code-runtime/code-runtime/README.i18n.yaml         | 4 ++--
 packages/code-runtime/code-runtime/README.md                | 2 +-
 packages/code-runtime/code-runtime/README.zh.md             | 2 +-
 packages/compact/compact/README.i18n.yaml                   | 4 ++--
 packages/compact/compact/README.md                          | 2 +-
 packages/compact/compact/README.zh.md                       | 2 +-
 packages/fs/fs/README.i18n.yaml                             | 4 ++--
 packages/fs/fs/README.md                                    | 2 +-
 packages/fs/fs/README.zh.md                                 | 2 +-
 packages/spill/spill/README.i18n.yaml                       | 4 ++--
 packages/spill/spill/README.md                              | 2 +-
 packages/spill/spill/README.zh.md                           | 2 +-
 packages/typert/generator/src/cordis-catalog.ts             | 6 +-----
 .../typert/generator/tests/cordis-catalog-contract.spec.ts  | 2 +-
 packages/web/web/README.i18n.yaml                           | 4 ++--
 packages/web/web/README.md                                  | 2 +-
 packages/web/web/README.zh.md                               | 2 +-
 .../translation-prompt-v4/request-response.expected.json    | 2 +-
 77 files changed, 155 insertions(+), 139 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index 2a310c8172..4a8f0149e2 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.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 .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
-2026-06-13-capability-seams.md: 7c755dced7825d2831acc0901f6412b8e5afe95a
-2026-06-13-capability-seams.zh.md: 31d20bb15f91533ab3c09d337a3cb11f812dbeb4
+2026-06-13-capability-seams.md: 1bad79a9d6d46e56afba862521403ee7c921ba21
+2026-06-13-capability-seams.zh.md: a44913539eed800f82d3f270fef05be17f524a2c
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
index 7c755dced7..1bad79a9d6 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
@@ -22,6 +22,10 @@ Implementation and consumer then evolve independently: a sandboxed executor repl
 
 The split is not mandatory when the parts are genuinely one concern: the LLM seam folds interface + consumer into `dsh-llm` (the consumer is the loop itself, not a swappable schema surface) with adapters as the implementation packages. Don't split preemptively — a capability with one conceivable implementation and one consumer stays one package until a second appears.
 
+## Terminology: "seam" names the trio, not the interface
+
+A **seam** is the whole capability — the three roles together: a **Service Definition** (the Cordis `Service` that owns `ctx.<key>` and the vocabulary; an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`), one or more **Service providers** (implementations that register a backend), and a **Consumer** (the model- or plugin-facing surface). `packages/bash` is the canonical example — `dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`. The interface package alone is the *Service Definition*, one member — not the seam. The Service Definition is never a TypeScript `interface`; where prose must name it, use the class name or `abstract class`, never `interface`. Reserving "seam" strictly for the trio and realigning the many existing "the X seam" usages is deferred to a follow-up; the [glossary](../../../../docs/glossary.md#capability-seam) is the canonical entry.
+
 ## Alternatives considered
 
 - **One combined package** — rejected because it recouples the three rates of change the split exists to separate (the whole point).
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
index 31d20bb15f..a44913539e 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -22,6 +22,10 @@ harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化
 
 当各部分确实属于同一个关注点时，三分并非强制：LLM（大语言模型） seam 将接口 + 消费方合并为 `dsh-llm`（消费方是 agent loop（智能体循环）本身，而非可替换的 schema 接口），适配器作为实现包。不要预防性地拆分——如果一项能力只有一种可设想的实现和一个消费方，就保持为一个包，直到出现第二种实现或第二个消费方。
 
+## 术语：seam 指三者组合，而非接口
+
+一个 **seam** 是完整的能力——三个角色合在一起：**Service Definition**（拥有 `ctx.<key>` 和词汇的 Cordis `Service`；可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表）、一个或多个 **Service provider**（注册后端的实现）和 **Consumer**（面向模型或插件的表面）。`packages/bash` 是规范范例——`dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`。接口包本身只是 *Service Definition*，是其中一个成员——不是 seam。Service Definition 从不是 TypeScript `interface`；在正文必须命名它时，使用类名或 `abstract class`，永远不要用 `interface`。严格把「seam」保留给三者组合，并校准现有大量「X seam」用法的工作推迟到后续；[术语表](../../../../docs/glossary.md#capability-seam)是规范条目。
+
 ## 曾考虑的替代方案
 
 - **单一合并包**：否决。因为它重新耦合了三分设计本要分离的三种变化速率（这正是拆分的意义所在）。
diff --git a/AGENTS.md b/AGENTS.md
index deabc5ed99..def643ad95 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -104,7 +104,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
-- **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively.
+- **Capability seams span three packages** — interface / implementation / consumer; don't split preemptively. The seam is all three ([glossary](docs/glossary.md#capability-seam)).
 - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
 - **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
 - **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test seam is not configurability. Protocol constants, external specs, and security invariants stay fixed.
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index f380ec5e42..7c8b1b95c8 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 5e009d8345112bb0adcb2f55b4e49bbbf3bf8d00
-architecture.zh.md: a1f01d734819d76276ae5b9ec74b4a7f9e98fc93
+architecture.md: bb76e6ce106bf6ab06b3a12b536aabbae581740f
+architecture.zh.md: eb2fc4dea190914d0b5f0732db571c81f2f0d471
diff --git a/docs/architecture.md b/docs/architecture.md
index 5e009d8345..bb76e6ce10 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -156,7 +156,9 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 ### Capability Pattern
 
-Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md).
+A **seam** is a swappable capability across three packages: a **Service Definition** (the Cordis `Service` owning its `ctx` key and vocabulary), a **Service provider** (the implementation plugin), and a **Consumer**. The Service Definition alone is the service, not the seam. Bash is the reference; the [capability graph](capability-seams.md) shows every family.
+
+Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks.
 
 Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)).
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index a1f01d7348..eb2fc4dea1 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -156,7 +156,9 @@ idle inject:
 
 ### 能力模式
 
-能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[能力图](capability-seams.md)。
+一个 **seam** 是跨三个包的一项可替换能力：**Service Definition**（拥有自身 `ctx` key 和词汇的 Cordis `Service`）、**Service provider**（实现插件）和 **Consumer**。Service Definition 本身只是服务，不是 seam。Bash 是参考；[能力图](capability-seams.md)展示每个家族。
+
+文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。
 
 例外情况包括 LLM（大语言模型）接口／消费方合并、文件系统策略、web 注册表，以及具名 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
 
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index ab9b5cec1d..b9dd5915c0 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.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 docs/glossary.md
-glossary.md: 16409517bff623a80d6e1e00888d95f63b42f780
-glossary.zh.md: a84447dd067a3364033601742c116583661cdf45
+glossary.md: acb093b097da62c92e3ade07f2dcb454eee576d2
+glossary.zh.md: ddf76edb1fd7e810badb68fadc0e3c67f2bc2b58
diff --git a/docs/glossary.md b/docs/glossary.md
index 16409517bf..acb093b097 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -4,6 +4,10 @@ English | [中文](glossary.zh.md)
 
 Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per concept. Terms link to their entries with standard Markdown anchors; implementation detail stays in package READMEs and Agent Notes.
 
+## capability-seam
+
+- **seam** — a *swappable capability* packaged as a trio: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`, never a TypeScript `interface`), one or more **Service providers** (the implementation plugins that register a backend), and a **Consumer** (the model- or plugin-facing surface that injects the service). `packages/bash` is the canonical example: `dsh-bash` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), `dsh-tool-bash` (consumer). The seam is all three together; the interface package alone is the *Service Definition*, one member — calling it "the seam" is the misuse this entry names. Fold roles only when they are genuinely one concern (`dsh-llm` folds the Service Definition and consumer); never split preemptively.
+
 ## agent-scope
 
 - **scope** — the unit of per-agent registration: a contribution (tool, prompt section, variable, restriction, listener) is either *global* (visible to every agent) or *scoped* (owned by exactly one [scope key](#scope-key)). Two levels, flat: scoped registrations do not inherit down to subagents; subtree behavior is expressed with [lineage](#lineage) data, never scope structure.
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index a84447dd06..ddf76edb1f 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -4,6 +4,10 @@
 
 DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。各术语通过标准 Markdown 锚点链接到相应条目；实现细节留在各包的 README 与 Agent Note 中。
 
+## capability-seam
+
+- **seam**：一种*可替换能力*，以三者组合的形式打包：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表，从不是 TypeScript `interface`）、一个或多个 **Service provider**（注册后端的实现插件）以及 **Consumer**（注入该服务、面向模型或插件的表面）。`packages/bash` 是规范范例：`dsh-bash`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方）、`dsh-tool-bash`（消费方）。seam 是三者整体；接口包本身只是 *Service Definition*，是其中一个成员——把它称为「seam」正是本条目指出的误用。只有在角色确实属于同一个关注点时才合并角色（`dsh-llm` 合并 Service Definition 和消费方）；永远不要预防性地拆分。
+
 ## agent-scope
 
 - **scope**：按 agent（智能体）划分的注册单位。一项贡献（工具、提示词片段、变量、限制、监听器）要么是*全局的*（对所有 agent 可见），要么是*带作用域的*（归属于恰好一个 [scope key](#scope-key)）。只有两层，采用扁平结构：带作用域的注册不会向下继承给 subagent；子树行为通过 [lineage](#lineage) 数据表达，从不通过 scope 结构。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index a089e2a1f0..4e49ef9694 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -55,7 +55,7 @@
 | Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
 | schema | schema | | | |
 | schema DSL | schema DSL | | | |
-| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |
+| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
 | skill | skill | skill（技能） | | |
 | slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |
 | spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 6f035bdbd5..077edaa10e 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/subsystems/bash.md
-bash.md: dd7649ce46bea5642270fa553eb3d82f2dc33e9b
-bash.zh.md: e3c607cb1599da97cb69369a34135abc310387ed
+bash.md: 232443daf944237e0c9f8904a0ebeeab3d2de749
+bash.zh.md: aaabc8fb1de654096e01fcee1ad1d0f881d534e8
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index dd7649ce46..232443daf9 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor-abstract-seam"></a>
+<a id="ctxbash--bashexecutor"></a>
 
-### `ctx.bash` — `BashExecutor` (abstract seam)
+### `ctx.bash` — `BashExecutor`
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index e3c607cb15..aaabc8fb1d 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor-abstract-seam"></a>
+<a id="ctxbash--bashexecutor"></a>
 
-### `ctx.bash` — `BashExecutor` (abstract seam)
+### `ctx.bash` — `BashExecutor`
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 3caad2c5f7..5c6c47580d 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
-code-runtime.md: 12779f1aafc8930410ae0d695e3f617caafcf607
-code-runtime.zh.md: 0bb18aaafff5a9b390685ee4c93a67f3f15502d5
+code-runtime.md: 7185e99042101b2c3707f3d0ed80ae6c1f1f58f0
+code-runtime.zh.md: 2b5ebea4e0e43cebd695c20d59fa6e705e4ebcf2
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index 12779f1aaf..7185e99042 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -168,9 +168,9 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+<a id="ctxcoderuntime--coderuntime"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+### `ctx.codeRuntime` — `CodeRuntime`
 
 Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 0bb18aaaff..2b5ebea4e0 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -168,9 +168,9 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+<a id="ctxcoderuntime--coderuntime"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+### `ctx.codeRuntime` — `CodeRuntime`
 
 Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 425f48409a..384a29469b 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 058fdba7969ac1f5b337b7ff008b0e62cf9ed035
-compaction.zh.md: b4108ed5de55e027d633a180db968c7cd7ffee59
+compaction.md: 47d115710a66bf1501e61806cbc68febbe4667ca
+compaction.zh.md: a89b218f16a44dbd184340631fa4f468f15f48f5
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 058fdba796..47d115710a 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice-abstract-seam"></a>
+<a id="ctxcompact--compactservice"></a>
 
-### `ctx.compact` — `CompactService` (abstract seam)
+### `ctx.compact` — `CompactService`
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index b4108ed5de..a89b218f16 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice-abstract-seam"></a>
+<a id="ctxcompact--compactservice"></a>
 
-### `ctx.compact` — `CompactService` (abstract seam)
+### `ctx.compact` — `CompactService`
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 7e9e057c75..2ea649fe56 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
-credentials.zh.md: f236b0b2daef85784308f10dbcfc67db84c42234
+credentials.md: 84b156e366b2f4d0aeaba11b1b8d005ff59ad11d
+credentials.zh.md: c12191529e4324aed57b0ec8870fdca5c4dcae8a
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 0bc2224ac0..84b156e366 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials-abstract-seam"></a>
+<a id="ctxcredentials--credentials"></a>
 
-### `ctx.credentials` — `Credentials` (abstract seam)
+### `ctx.credentials` — `Credentials`
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index f236b0b2da..c12191529e 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials-abstract-seam"></a>
+<a id="ctxcredentials--credentials"></a>
 
-### `ctx.credentials` — `Credentials` (abstract seam)
+### `ctx.credentials` — `Credentials`
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index e57b2aef45..3b5987bfec 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 591f1b4d4b1177ccbe7c2280d2054da5d4be8b99
-filesystem.zh.md: d599e48c1fba2d564a544f628ca3475b781e5cd5
+filesystem.md: 6c89f6f88babf09b1cf0f6ac2b739b511568f18b
+filesystem.zh.md: 16be774c74d02894434467dc68e927fdba2e38c7
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 591f1b4d4b..6c89f6f88b 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -262,7 +262,7 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem) below shows the exact signatures.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem-abstract-seam"></a>
+<a id="ctxfs--filesystem"></a>
 
-### `ctx.fs` — `FileSystem` (abstract seam)
+### `ctx.fs` — `FileSystem`
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index d599e48c1f..16be774c74 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -262,7 +262,7 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem) 展示确切的 `ctx.fs` 签名。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem-abstract-seam"></a>
+<a id="ctxfs--filesystem"></a>
 
-### `ctx.fs` — `FileSystem` (abstract seam)
+### `ctx.fs` — `FileSystem`
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index ae2ef3a216..1ee31d85d0 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
-persistence.zh.md: 8785ca9c7dad562e6b27261920ab48c72c607121
+persistence.md: c8d8bba1650dd54b533e95a4ddd0a8f5a19bb0c6
+persistence.zh.md: b4440183bc56086739ac1e9fa6390e9287335986
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 580ec250eb..c8d8bba165 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## The backends
 
-Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`, proving the seam is genuinely backend-agnostic:
+Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`:
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
@@ -213,9 +213,9 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+<a id="ctxsessionpersistence--sessionpersistence"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+### `ctx.sessionPersistence` — `SessionPersistence`
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 8785ca9c7d..b4440183bc 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## 后端
 
-两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`，证明该 seam 确实与后端无关：
+两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`：
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
@@ -213,9 +213,9 @@ interface SessionPersistenceSnapshot {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+<a id="ctxsessionpersistence--sessionpersistence"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+### `ctx.sessionPersistence` — `SessionPersistence`
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index a6f8fd2609..ab7bbb6b07 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.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 docs/subsystems/sandbox.md
-sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
-sandbox.zh.md: 23644bb43a131a0e3c8595187a6fc11e74682d9e
+sandbox.md: b08eacbc040568fa40c681f65577b64afe53fbaa
+sandbox.zh.md: 1e5f7f55b4923f96ffb9263e9d0784f849fd4d13
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index dd960b3021..b08eacbc04 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -155,9 +155,9 @@ Provider selection, probing, caching, and backend-specific enforcement reports b
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+<a id="ctxsandbox--sandboxprovider"></a>
 
-### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+### `ctx.sandbox` — `SandboxProvider`
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index 23644bb43a..1e5f7f55b4 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -155,9 +155,9 @@ interface ConfinedArgv {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+<a id="ctxsandbox--sandboxprovider"></a>
 
-### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+### `ctx.sandbox` — `SandboxProvider`
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 02a3502a1a..02734a5cdc 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: 9e907b2ebf12c01620921c7955f25d2fdd6ce4fb
-session-query.zh.md: 4452330ebd5e487387c0ad15bea45b76d9c643be
+session-query.md: e62cd1c6ff744e7ccdc6f26f5ad76a6512a205bf
+session-query.zh.md: 7bd2b55509e4c5bb971a44680d0d7576c5d10146
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 9e907b2ebf..e62cd1c6ff 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+<a id="ctxsessionquery--sessionqueryservice"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+### `ctx.sessionQuery` — `SessionQueryService`
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 4452330ebd..7bd2b55509 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+<a id="ctxsessionquery--sessionqueryservice"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+### `ctx.sessionQuery` — `SessionQueryService`
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index a257e0e33e..e541d20f69 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/subsystems/settings.md
-settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
-settings.zh.md: 720eb9c2718c1fa14a148cced806c224634dba69
+settings.md: c15b11c8635def88aba49b6df66aa56a22fbe0ae
+settings.zh.md: 7f588ededd0ad2eb058995d4d54fe71c8b6bc67a
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index 9256bf9436..c15b11c863 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings-abstract-seam"></a>
+<a id="ctxsettings--settings"></a>
 
-### `ctx.settings` — `Settings` (abstract seam)
+### `ctx.settings` — `Settings`
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 720eb9c271..7f588ededd 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings-abstract-seam"></a>
+<a id="ctxsettings--settings"></a>
 
-### `ctx.settings` — `Settings` (abstract seam)
+### `ctx.settings` — `Settings`
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index 1e9547cc28..c0e9f9f50d 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/subsystems/spill.md
-spill.md: a0a476761ab0633227d7c87033daee79f649bf50
-spill.zh.md: 65d7e4cb89a93e2e709af0a620f523aad2315ed2
+spill.md: 4998ac62d1cd4e86a6e92ec5a0c85955b137f4be
+spill.zh.md: 0495c6fbcdb5c909a142539f69d5dd2bd551413c
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index a0a476761a..4998ac62d1 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -92,9 +92,9 @@ The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes u
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore-abstract-seam"></a>
+<a id="ctxspillstore--spillstore"></a>
 
-### `ctx.spillStore` — `SpillStore` (abstract seam)
+### `ctx.spillStore` — `SpillStore`
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 65d7e4cb89..0495c6fbcd 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -92,9 +92,9 @@ type SpillLocator = Branded<'SpillLocator'>
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore-abstract-seam"></a>
+<a id="ctxspillstore--spillstore"></a>
 
-### `ctx.spillStore` — `SpillStore` (abstract seam)
+### `ctx.spillStore` — `SpillStore`
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index 4c63f77618..0af3183692 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
-subprocess.md: 0bc2bf86518bcc60bef02554b94471425f2ac433
-subprocess.zh.md: 7e27bf15dfe0cdde09459dbfb239ab25ccde126a
+subprocess.md: b501af81dca94025713d46a23a67b543f5df95cd
+subprocess.zh.md: 84b497c90bb5956b0dcb65ca1cb72122b415bd7e
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index 0bc2bf8651..b501af81dc 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -242,7 +242,7 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice-abstract-seam).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice).
 
 ## Service behavior
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+<a id="ctxsubprocess--subprocessservice"></a>
 
-### `ctx.subprocess` — `SubprocessService` (abstract seam)
+### `ctx.subprocess` — `SubprocessService`
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 7e27bf15df..84b497c90b 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -242,7 +242,7 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice-abstract-seam)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice)中。
 
 ## 服务行为
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+<a id="ctxsubprocess--subprocessservice"></a>
 
-### `ctx.subprocess` — `SubprocessService` (abstract seam)
+### `ctx.subprocess` — `SubprocessService`
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index d1110928e7..6f9d3c6861 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.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 docs/subsystems/tasks.md
-tasks.md: 6237607307cbab8511f968ed591e3e3b8b845c6a
-tasks.zh.md: c73765b4d5ad0309f3473890557171af21527682
+tasks.md: f042dfec7438bd2e385cc8c225a3faa171b9ca4f
+tasks.zh.md: bf660a9606f0bc9081532c970e88f249ea0ec4ae
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index 6237607307..f042dfec74 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -161,9 +161,9 @@ The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defin
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice-abstract-seam"></a>
+<a id="ctxtasks--taskservice"></a>
 
-### `ctx.tasks` — `TaskService` (abstract seam)
+### `ctx.tasks` — `TaskService`
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index c73765b4d5..bf660a9606 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -161,9 +161,9 @@ interface TaskRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice-abstract-seam"></a>
+<a id="ctxtasks--taskservice"></a>
 
-### `ctx.tasks` — `TaskService` (abstract seam)
+### `ctx.tasks` — `TaskService`
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index d520d56dcf..b53153692f 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: 131c5814f29d70c356989e62fda1db5c1c5448d6
-telemetry.zh.md: 147418000f240093f356fe9033612967f8e29ffb
+telemetry.md: c9afd276f7c4183db0d1accea2b9aafe71a0e5cc
+telemetry.zh.md: e7ea255a50cace18c7d59b2c77c96bc426d5ee0c
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 131c5814f2..c9afd276f7 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
 
 ## The redact waterfall: `telemetry/record`
 
@@ -119,9 +119,9 @@ Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordi
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+<a id="ctxtelemetry--telemetry"></a>
 
-### `ctx.telemetry` — `Telemetry` (abstract seam)
+### `ctx.telemetry` — `Telemetry`
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 147418000f..e7ea255a50 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
@@ -119,9 +119,9 @@ interface TelemetryBackend {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+<a id="ctxtelemetry--telemetry"></a>
 
-### `ctx.telemetry` — `Telemetry` (abstract seam)
+### `ctx.telemetry` — `Telemetry`
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index 4f581d8bae..fed94d62bc 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.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 docs/subsystems/workflow.md
-workflow.md: 53cb8be2c975fba396c3d2023c60fc1da2ed9c8a
-workflow.zh.md: 652b68c833f7f20fe72307946d02f89558be2c2b
+workflow.md: c87e88f1e1dddcd57822e47e5773dba127f9cdcf
+workflow.zh.md: 57d69ffd5300a6b4d6e037758a75c19e9ccd51a7
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index 53cb8be2c9..c87e88f1e1 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -139,9 +139,9 @@ The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `wo
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+<a id="ctxworkflows--workflowservice"></a>
 
-### `ctx.workflows` — `WorkflowService` (abstract seam)
+### `ctx.workflows` — `WorkflowService`
 
 Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 652b68c833..57d69ffd53 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -139,9 +139,9 @@ interface WorkflowRun {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+<a id="ctxworkflows--workflowservice"></a>
 
-### `ctx.workflows` — `WorkflowService` (abstract seam)
+### `ctx.workflows` — `WorkflowService`
 
 Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index b2c2248876..1b94464e30 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
-workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
+workspace.md: 21b08bd8b0936e9c7357ad15e7ff4176a981a042
+workspace.zh.md: 30bfc0054880ca82b5f7c64780d405524656a1f1
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index ca088a2091..21b08bd8b0 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -133,9 +133,9 @@ Sessions get their cwd at create time from whoever creates them, not from this r
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+<a id="ctxdirectorypicker--directorypicker"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+### `ctx.directoryPicker` — `DirectoryPicker`
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index e414c759a0..30bfc00548 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -133,9 +133,9 @@ interface Workspace {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+<a id="ctxdirectorypicker--directorypicker"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+### `ctx.directoryPicker` — `DirectoryPicker`
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 169a45d5cd..72bd7650be 100644
--- 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: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee
-README.zh.md: f8bcfce06a406eb94a2486e9825f2beb11b8fd5e
+README.md: e142a796e94dab4ecaa67b8dfce0be4f554f26c0
+README.zh.md: 24a44b418a675d863551642f2edb1f655a2705ab
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 690f4e6174..e142a796e9 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
+The **`BashExecutor`** (`ctx.bash`) defines WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
 
 This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index f8bcfce06a..24a44b418a 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**bash 执行器 seam**：抽象 `BashExecutor` 服务（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
+**`BashExecutor`**（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
 
 本包是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：
 
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 99d66e084f..0a72d1608c 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: 2a68e6f05d12b737bdff530a351aa038628d85fc
+README.md: 637cc6adae3372ea60ca003f74af416513484270
+README.zh.md: fcc4c7323dd547c2421bb1e5a009481bf78cfc70
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index bb1c20d00a..637cc6adae 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **code-execution seam**: an abstract `CodeRuntime` service (`ctx.codeRuntime`) defining WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
+The **`CodeRuntime`** (`ctx.codeRuntime`) defines WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
 
 This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
 
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index 2a68e6f05d..fcc4c7323d 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是**代码执行 seam**：抽象的 `CodeRuntime` 服务（`ctx.codeRuntime`）只定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
+**`CodeRuntime`**（`ctx.codeRuntime`）定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
 此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
 
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index c5045934c9..dae5564742 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: c32be20117abfe15e278082089c5fd87828c81ef
-README.zh.md: 530b1ca30061956fbe37a4b4b90fed99c02e5a7f
+README.md: c7fdbef33b2e65089a0f0112e19122db4f26bb77
+README.zh.md: 493d269202b3a5b89cd600391e7144219ed2bf12
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index c32be20117..c7fdbef33b 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **compaction seam**: an abstract `CompactService` (`ctx.compact`) defining WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
+The **`CompactService`** (`ctx.compact`) defines WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
 
 This package is the interface tier of the compaction capability, split so each concern evolves (and swaps) independently:
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 530b1ca300..493d269202 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**压缩（compaction） seam**：抽象 `CompactService`（`ctx.compact`）定义压缩做什么，即判定历史记录是否过大，并将较早范围摘要为单个表层节点，但不规定如何实现。
+**`CompactService`**（`ctx.compact`）定义压缩做什么，即判定历史记录是否过大，并将较早范围摘要为单个表层节点，但不规定如何实现。
 
 这个包是压缩能力的接口层，因此各项职责均可独立演进，也可独立替换：
 
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index e0095d9858..5ed8633331 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
-README.zh.md: 8eb2634df2754cdcada4e48046e19eb32b1cf3af
+README.md: 11134e6298e6c87d1046952c65bb2dadff43e4a2
+README.zh.md: 7edece618150739d5ff67c605788dae42a5a5c32
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 5c58fc476b..11134e6298 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **`FileSystem`** (`ctx.fs`) defines the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
 This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 8eb2634df2..7edece6181 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
 
 本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index 110d814fe2..cddfc91ea7 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
-README.md: d3cce987f80c0db5165718b7cc4fd6ada92f2a02
-README.zh.md: 37d6587d08d96c55a36c9b7388f2ae418531a6cd
+README.md: ecaef9fc53ec3d9017143cfc012abc9cabe77072
+README.zh.md: 5393ccb312245f3bbfcf28ea8e097b0a343966e9
diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md
index d3cce987f8..ecaef9fc53 100644
--- a/packages/spill/spill/README.md
+++ b/packages/spill/spill/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **spill storage seam**: an abstract `SpillStore` service (`ctx.spillStore`) defining WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance — without saying HOW.
+The **`SpillStore`** (`ctx.spillStore`) defines WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance — without saying HOW.
 
 This package is one third of the spill capability, split so each concern evolves (and swaps) independently:
 
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index 37d6587d08..5393ccb312 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**spill 存储 seam**：抽象的 `SpillStore` 服务（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。
+**`SpillStore`**（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。
 
 该包是 spill 能力的三个组成部分之一。拆分后，各项关注点可独立演进和替换：
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 1950c255cb..553ab75490 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -84,8 +84,6 @@ export interface ServiceEntry {
   key: string
   /** The service class/interface name, e.g. `LlmService`. */
   type: string
-  /** Whether the service class is abstract (a seam interface). */
-  abstract: boolean
   /** Class-level JSDoc prose, one line per paragraph. */
   doc: string
   /** Public methods (bodies stripped), in source order. */
@@ -258,7 +256,6 @@ export class CordisCatalogProjector {
         entries.push({
           key: service.key,
           type: declaration.name,
-          abstract: declaration.abstract,
           doc,
           methods,
           source,
@@ -747,8 +744,7 @@ function renderEvent(e: EventEntry, onPage: string, linkedTypePages: Readonly<Re
 
 /** Render one harness service entry onto its owning page. */
 function renderService(s: ServiceEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
-  const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [...anchorFor(`ctx.${s.key} — ${s.type}${kind}`), `### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  const out = [...anchorFor(`ctx.${s.key} — ${s.type}`), `### \`ctx.${s.key}\` — \`${s.type}\``, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
     const declarations = s.methods.flatMap((method, index) => [
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index bde52505dc..a6b68a4ee7 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -259,7 +259,7 @@ export class FixService {
   it('extracts a well-formed service with its methods and class JSDoc', () => {
     const services = collectServices(makeService(WELL_FORMED))
     expect(services).toHaveLength(1)
-    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', abstract: false, doc: 'Fixture service.' })
+    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', doc: 'Fixture service.' })
     expect(services[0]?.methods).toHaveLength(3)
     expect(services[0]?.methods[0]).toEqual({
       signature: 'run(id: string): string',
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index b6c139d63c..5adff6e81c 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
-README.md: 73765fe060cc0a2b0fa3d69703a670f488a29ac9
-README.zh.md: bebdb52d6c9bd33db5a982c1f278e71c1882f2de
+README.md: c05965478a049b4145a94075e42bd9602675628f
+README.zh.md: 686157cc87ff456ccc535e3f92fd6524758b35f4
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index 73765fe060..c05965478a 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **web access seam**: an abstract `WebService` (`ctx.web`) defining WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
+The **`WebService`** (`ctx.web`) defines WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
 
 This package is the interface third of the web capability. Unlike bash/fs it spans two capabilities (search and fetch) on one seam, with potentially multiple providers each:
 
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index bebdb52d6c..686157cc87 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**web 访问 seam**：抽象 `WebService`（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
+**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型契约绑定到某个厂商的 API 形状。
 
 该包是 web 能力中负责接口的三分之一。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种能力，每种能力都可能有多个提供方：
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index cbdd3d758e..38cc7950ec 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",

From 95eb4bcf40e62a5f22434fe9feaa2ba6f1b0845d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:20:58 +0800
Subject: [PATCH 224/262] test(windows): vary HMR polling writes

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index dbb3a8ca83..d21e222104 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -48,9 +48,13 @@ describe('HMR exact config paths', () => {
     try {
       const deadline = Date.now() + 20_000
       for (let generation = 1; !observed.includes(expected); generation += 1) {
-        if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        if (Date.now() >= deadline) {
+          throw new Error(`HMR did not observe ${expected} through the alias; observed ${JSON.stringify(observed)}`)
+        }
         // The watch base, not the writer spelling, is the alias under test.
-        writeFileSync(filename, `export const generation = ${generation}\n`)
+        // Grow the file on every write: polling must not depend on timestamp
+        // precision when several generations land inside one filesystem tick.
+        writeFileSync(filename, `export const generation = ${generation}\n${' '.repeat(generation)}\n`)
         // Leave Chokidar's atomic-write window idle so one coalesced change can publish.
         await new Promise(resolve => setTimeout(resolve, 250))
       }

From dda02250f52a4e85052a7c6bbed245d7d8509309 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:34:32 +0800
Subject: [PATCH 225/262] docs: reserve seam for complete capabilities

---
 ...ev-invariants-over-deep-readonly.i18n.yaml |  4 +-
 ...06-11-dev-invariants-over-deep-readonly.md |  2 +-
 ...11-dev-invariants-over-deep-readonly.zh.md |  2 +-
 ...06-11-microkernel-event-taxonomy.i18n.yaml |  4 +-
 .../2026-06-11-microkernel-event-taxonomy.md  |  6 +--
 ...026-06-11-microkernel-event-taxonomy.zh.md |  6 +--
 .../2026-06-13-capability-seams.i18n.yaml     |  4 +-
 .../2026-06-13-capability-seams.md            | 22 ++++-----
 .../2026-06-13-capability-seams.zh.md         | 22 ++++-----
 .../2026-06-14-session-persistence.i18n.yaml  |  4 +-
 .../2026-06-14-session-persistence.md         |  6 +--
 .../2026-06-14-session-persistence.zh.md      | 12 ++---
 ...06-17-filesystem-capability-seam.i18n.yaml |  4 +-
 .../2026-06-17-filesystem-capability-seam.md  | 14 +++---
 ...026-06-17-filesystem-capability-seam.zh.md | 14 +++---
 ...fecycle-and-ownership-contracts.i18n.yaml} |  6 +--
 ...gent-lifecycle-and-ownership-contracts.md} | 16 +++----
 ...t-lifecycle-and-ownership-contracts.zh.md} | 16 +++----
 ...ed-persistence-write-coordinator.i18n.yaml |  4 +-
 ...18-shared-persistence-write-coordinator.md |  2 +-
 ...shared-persistence-write-coordinator.zh.md |  6 +--
 .../2026-06-20-branded-ids.i18n.yaml          |  4 +-
 .../architecture/2026-06-20-branded-ids.md    | 12 ++---
 .../architecture/2026-06-20-branded-ids.zh.md | 12 ++---
 ...eneric-long-running-tool-runtime.i18n.yaml |  4 +-
 ...06-20-generic-long-running-tool-runtime.md |  6 +--
 ...20-generic-long-running-tool-runtime.zh.md |  6 +--
 ...-21-bounded-llm-request-recovery.i18n.yaml |  4 +-
 ...2026-06-21-bounded-llm-request-recovery.md |  8 ++--
 ...6-06-21-bounded-llm-request-recovery.zh.md |  8 ++--
 ...andatory-app-attribution-headers.i18n.yaml |  4 +-
 ...06-21-mandatory-app-attribution-headers.md |  4 +-
 ...21-mandatory-app-attribution-headers.zh.md |  4 +-
 .../2026-06-24-web-capability-seam.i18n.yaml  |  4 +-
 .../2026-06-24-web-capability-seam.md         |  8 ++--
 .../2026-06-24-web-capability-seam.zh.md      |  8 ++--
 ...06-26-file-context-as-event-gate.i18n.yaml |  4 +-
 .../2026-06-26-file-context-as-event-gate.md  |  8 ++--
 ...026-06-26-file-context-as-event-gate.zh.md |  8 ++--
 ...stdin-env-trusted-plugin-surface.i18n.yaml |  4 +-
 ...0-bash-stdin-env-trusted-plugin-surface.md |  4 +-
 ...ash-stdin-env-trusted-plugin-surface.zh.md |  4 +-
 ...026-06-30-event-domain-semantics.i18n.yaml |  4 +-
 .../2026-06-30-event-domain-semantics.md      |  4 +-
 .../2026-06-30-event-domain-semantics.zh.md   |  6 +--
 .../2026-07-02-fs-per-session-cwd.i18n.yaml   |  4 +-
 .../2026-07-02-fs-per-session-cwd.md          |  2 +-
 .../2026-07-02-fs-per-session-cwd.zh.md       |  2 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |  4 +-
 .../2026-07-05-reconstructable-requests.md    |  2 +-
 .../2026-07-05-reconstructable-requests.zh.md |  8 ++--
 ...6-07-06-timeout-deadline-library.i18n.yaml |  4 +-
 .../2026-07-06-timeout-deadline-library.md    |  2 +-
 .../2026-07-06-timeout-deadline-library.zh.md |  2 +-
 ...6-07-07-tool-call-timeout-policy.i18n.yaml |  4 +-
 .../2026-07-07-tool-call-timeout-policy.md    |  6 +--
 .../2026-07-07-tool-call-timeout-policy.zh.md |  6 +--
 ...26-07-08-tool-output-spill-files.i18n.yaml |  4 +-
 .../2026-07-08-tool-output-spill-files.md     |  2 +-
 .../2026-07-08-tool-output-spill-files.zh.md  |  2 +-
 ...n-pressure-and-overflow-recovery.i18n.yaml |  4 +-
 ...mpaction-pressure-and-overflow-recovery.md |  2 +-
 ...ction-pressure-and-overflow-recovery.zh.md |  2 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |  4 +-
 .../2026-07-12-agent-scope-runtime-design.md  |  4 +-
 ...026-07-12-agent-scope-runtime-design.zh.md |  4 +-
 ...-14-provider-routed-llm-adapters.i18n.yaml |  4 +-
 ...2026-07-14-provider-routed-llm-adapters.md |  2 +-
 ...6-07-14-provider-routed-llm-adapters.zh.md |  2 +-
 ...-model-catalog-and-acp-selection.i18n.yaml |  4 +-
 ...-15-llm-model-catalog-and-acp-selection.md |  4 +-
 ...-llm-model-catalog-and-acp-selection.zh.md |  4 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  4 +-
 .../2026-07-15-lsp-capability-seam.md         |  6 +--
 .../2026-07-15-lsp-capability-seam.zh.md      |  6 +--
 ...07-16-explicit-turn-cancellation.i18n.yaml |  4 +-
 .../2026-07-16-explicit-turn-cancellation.md  |  8 ++--
 ...026-07-16-explicit-turn-cancellation.zh.md | 10 ++--
 ...19-cooperative-tool-cancellation.i18n.yaml |  4 +-
 ...026-07-19-cooperative-tool-cancellation.md |  4 +-
 ...-07-19-cooperative-tool-cancellation.zh.md |  4 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |  4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md | 10 ++--
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  8 ++--
 ...7-19-gui-web-client-architecture.i18n.yaml |  4 +-
 .../2026-07-19-gui-web-client-architecture.md |  4 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  4 +-
 ...kage-invariant-runtime-contracts.i18n.yaml |  4 +-
 ...-19-package-invariant-runtime-contracts.md |  2 +-
 ...-package-invariant-runtime-contracts.zh.md |  2 +-
 ...-package-owned-invariant-service.i18n.yaml |  4 +-
 ...6-07-19-package-owned-invariant-service.md |  2 +-
 ...7-19-package-owned-invariant-service.zh.md |  2 +-
 ...el-context-and-compaction-policy.i18n.yaml |  4 +-
 ...ted-model-context-and-compaction-policy.md |  4 +-
 ...-model-context-and-compaction-policy.zh.md |  4 +-
 ...2-slot-type-chain-implementation.i18n.yaml |  4 +-
 ...26-07-22-slot-type-chain-implementation.md |  4 +-
 ...07-22-slot-type-chain-implementation.zh.md |  4 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |  4 +-
 .../2026-07-23-client-plugin-loading-model.md | 12 ++---
 ...26-07-23-client-plugin-loading-model.zh.md | 12 ++---
 ...ession-scope-and-provide-channel.i18n.yaml |  4 +-
 ...lient-session-scope-and-provide-channel.md |  2 +-
 ...nt-session-scope-and-provide-channel.zh.md |  2 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |  4 +-
 .../2026-07-26-subprocess-seam.md             | 12 ++---
 .../2026-07-26-subprocess-seam.zh.md          | 12 ++---
 .../2026-07-26-task-registry-seam.i18n.yaml   |  4 +-
 .../2026-07-26-task-registry-seam.md          | 22 ++++-----
 .../2026-07-26-task-registry-seam.zh.md       | 22 ++++-----
 ...07-27-dispose-ladder-to-consumer.i18n.yaml |  4 +-
 .../2026-07-27-dispose-ladder-to-consumer.md  |  4 +-
 ...026-07-27-dispose-ladder-to-consumer.zh.md |  6 +--
 ...directory-picker-capability-seam.i18n.yaml |  4 +-
 ...-07-28-directory-picker-capability-seam.md |  8 ++--
 ...-28-directory-picker-capability-seam.zh.md |  8 ++--
 .../2026-07-28-user-settings-seam.i18n.yaml   |  4 +-
 .../2026-07-28-user-settings-seam.md          |  4 +-
 .../2026-07-28-user-settings-seam.zh.md       |  4 +-
 ...undaries-and-atomic-registration.i18n.yaml |  4 +-
 ...tial-boundaries-and-atomic-registration.md |  2 +-
 ...l-boundaries-and-atomic-registration.zh.md |  2 +-
 ...-followup-enqueue-and-owned-runs.i18n.yaml |  4 +-
 ...6-07-30-followup-enqueue-and-owned-runs.md |  2 +-
 ...7-30-followup-enqueue-and-owned-runs.zh.md |  2 +-
 ...-manager-native-repository-cache.i18n.yaml |  4 +-
 ...package-manager-native-repository-cache.md |  2 +-
 ...kage-manager-native-repository-cache.zh.md |  2 +-
 ...30-settings-write-path-integrity.i18n.yaml |  4 +-
 ...026-07-30-settings-write-path-integrity.md |  4 +-
 ...-07-30-settings-write-path-integrity.zh.md |  6 +--
 .../2026-07-30-web-config-plane.i18n.yaml     |  4 +-
 .../2026-07-30-web-config-plane.md            |  4 +-
 .../2026-07-30-web-config-plane.zh.md         |  4 +-
 ...claimed-pre-step-inbox-lifecycle.i18n.yaml |  4 +-
 ...-07-31-claimed-pre-step-inbox-lifecycle.md |  4 +-
 ...-31-claimed-pre-step-inbox-lifecycle.zh.md |  4 +-
 ...runtime-portable-identifier-seam.i18n.yaml |  4 +-
 ...1-code-runtime-portable-identifier-seam.md | 16 +++----
 ...ode-runtime-portable-identifier-seam.zh.md | 16 +++----
 ...26-08-01-packaged-ripgrep-search.i18n.yaml |  4 +-
 .../2026-08-01-packaged-ripgrep-search.md     |  2 +-
 .../2026-08-01-packaged-ripgrep-search.zh.md  |  2 +-
 ...-pi-ai-declared-provider-catalog.i18n.yaml |  4 +-
 ...6-08-03-pi-ai-declared-provider-catalog.md |  2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |  2 +-
 ...4-configuration-source-ownership.i18n.yaml |  4 +-
 ...26-08-04-configuration-source-ownership.md |  2 +-
 ...08-04-configuration-source-ownership.zh.md |  2 +-
 ...-provider-endpoint-interrogation.i18n.yaml |  4 +-
 ...4-draft-provider-endpoint-interrogation.md |  4 +-
 ...raft-provider-endpoint-interrogation.zh.md |  4 +-
 ...08-04-websocket-downlink-carrier.i18n.yaml |  4 +-
 .../2026-08-04-websocket-downlink-carrier.md  |  4 +-
 ...026-08-04-websocket-downlink-carrier.zh.md |  4 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |  4 +-
 .../2026-08-05-profile-plugin-bundles.md      |  2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |  2 +-
 .../2026-08-05-session-preparation.i18n.yaml  |  4 +-
 .../2026-08-05-session-preparation.md         |  2 +-
 .../2026-08-05-session-preparation.zh.md      |  2 +-
 ...ubagent-list-identity-projection.i18n.yaml |  4 +-
 ...08-06-subagent-list-identity-projection.md |  2 +-
 ...06-subagent-list-identity-projection.zh.md |  2 +-
 ...ient-tool-presentation-ownership.i18n.yaml |  4 +-
 ...8-08-client-tool-presentation-ownership.md |  6 +--
 ...8-client-tool-presentation-ownership.zh.md |  6 +--
 ...20-error-cause-chain-diagnostics.i18n.yaml |  4 +-
 ...026-07-20-error-cause-chain-diagnostics.md |  8 ++--
 ...-07-20-error-cause-chain-diagnostics.zh.md |  8 ++--
 ...nsport-truncation-classification.i18n.yaml |  2 +-
 ...-ai-transport-truncation-classification.md |  2 +-
 ...ranscript-log-ordered-projection.i18n.yaml |  4 +-
 ...0-web-transcript-log-ordered-projection.md |  2 +-
 ...eb-transcript-log-ordered-projection.zh.md |  2 +-
 ...resume-selector-batch-projection.i18n.yaml |  4 +-
 ...-07-31-resume-selector-batch-projection.md |  2 +-
 ...-31-resume-selector-batch-projection.zh.md |  2 +-
 ...-08-06-api-key-format-validation.i18n.yaml |  4 +-
 .../2026-08-06-api-key-format-validation.md   |  6 +--
 ...2026-08-06-api-key-format-validation.zh.md |  6 +--
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 +-
 .../feature/2026-06-15-code-mode.md           |  4 +-
 .../feature/2026-06-15-code-mode.zh.md        |  4 +-
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |  4 +-
 .../2026-06-17-filesystem-tool-schemas.md     |  2 +-
 .../2026-06-17-filesystem-tool-schemas.zh.md  |  2 +-
 ...06-18-compaction-capability-seam.i18n.yaml |  4 +-
 .../2026-06-18-compaction-capability-seam.md  |  6 +--
 ...026-06-18-compaction-capability-seam.zh.md |  8 ++--
 ...6-06-21-subagent-capability-seam.i18n.yaml |  4 +-
 .../2026-06-21-subagent-capability-seam.md    |  6 +--
 .../2026-06-21-subagent-capability-seam.zh.md |  6 +--
 .../2026-06-22-acp-subagent-backend.i18n.yaml |  4 +-
 .../2026-06-22-acp-subagent-backend.md        |  2 +-
 .../2026-06-22-acp-subagent-backend.zh.md     |  2 +-
 .../feature/2026-06-30-hook-bridges.i18n.yaml |  4 +-
 .../feature/2026-06-30-hook-bridges.md        | 12 ++---
 .../feature/2026-06-30-hook-bridges.zh.md     | 12 ++---
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |  4 +-
 .../feature/2026-06-30-hook-protocol-lib.md   |  2 +-
 .../2026-06-30-hook-protocol-lib.zh.md        |  2 +-
 ...0-interception-extension-points.i18n.yaml} |  6 +--
 ...26-06-30-interception-extension-points.md} | 14 +++---
 ...06-30-interception-extension-points.zh.md} | 20 ++++----
 .../2026-07-05-dynamic-workflows.i18n.yaml    |  4 +-
 .../feature/2026-07-05-dynamic-workflows.md   |  4 +-
 .../2026-07-05-dynamic-workflows.zh.md        |  4 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |  4 +-
 .../feature/2026-07-05-skill-system.md        |  4 +-
 .../feature/2026-07-05-skill-system.zh.md     |  4 +-
 .../2026-07-06-approval-seam.i18n.yaml        |  4 +-
 .../feature/2026-07-06-approval-seam.md       |  4 +-
 .../feature/2026-07-06-approval-seam.zh.md    |  4 +-
 .../2026-07-06-explicit-tool-order.i18n.yaml  |  4 +-
 .../feature/2026-07-06-explicit-tool-order.md |  2 +-
 .../2026-07-06-explicit-tool-order.zh.md      |  2 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |  4 +-
 .../implemented/feature/2026-07-06-sandbox.md | 14 +++---
 .../feature/2026-07-06-sandbox.zh.md          | 14 +++---
 ...-10-parallel-tool-call-execution.i18n.yaml |  4 +-
 ...2026-07-10-parallel-tool-call-execution.md |  2 +-
 ...6-07-10-parallel-tool-call-execution.zh.md |  2 +-
 ...10-sqlite-session-query-provider.i18n.yaml |  4 +-
 ...026-07-10-sqlite-session-query-provider.md |  2 +-
 ...-07-10-sqlite-session-query-provider.zh.md |  2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |  4 +-
 .../feature/2026-07-16-harness-level-loop.md  |  8 ++--
 .../2026-07-16-harness-level-loop.zh.md       |  8 ++--
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  4 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  4 +-
 ...-fresh-agent-ralph-workflow-tool.i18n.yaml |  4 +-
 ...6-07-19-fresh-agent-ralph-workflow-tool.md |  4 +-
 ...7-19-fresh-agent-ralph-workflow-tool.zh.md |  4 +-
 ...26-07-19-model-facing-goal-tools.i18n.yaml |  4 +-
 .../2026-07-19-model-facing-goal-tools.md     |  2 +-
 .../2026-07-19-model-facing-goal-tools.zh.md  |  2 +-
 ...rsisted-same-session-goal-domain.i18n.yaml |  4 +-
 ...7-19-persisted-same-session-goal-domain.md |  2 +-
 ...9-persisted-same-session-goal-domain.zh.md |  2 +-
 ...9-same-session-goal-round-driver.i18n.yaml |  4 +-
 ...26-07-19-same-session-goal-round-driver.md |  4 +-
 ...07-19-same-session-goal-round-driver.zh.md |  4 +-
 ...-20-code-mode-typed-tool-returns.i18n.yaml |  4 +-
 ...2026-07-20-code-mode-typed-tool-returns.md |  4 +-
 ...6-07-20-code-mode-typed-tool-returns.zh.md |  4 +-
 ...-07-25-workspace-ui-product-flow.i18n.yaml |  4 +-
 .../2026-07-25-workspace-ui-product-flow.md   |  2 +-
 ...2026-07-25-workspace-ui-product-flow.zh.md |  2 +-
 ...26-07-26-code-dispatch-log-spill.i18n.yaml |  4 +-
 .../2026-07-26-code-dispatch-log-spill.md     |  4 +-
 .../2026-07-26-code-dispatch-log-spill.zh.md  |  4 +-
 ...7-26-code-dispatch-ui-foundation.i18n.yaml |  4 +-
 .../2026-07-26-code-dispatch-ui-foundation.md |  4 +-
 ...26-07-26-code-dispatch-ui-foundation.zh.md |  4 +-
 ...2026-07-27-tmux-location-context.i18n.yaml |  4 +-
 .../2026-07-27-tmux-location-context.md       |  2 +-
 .../2026-07-27-tmux-location-context.zh.md    |  2 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |  4 +-
 ...typescript-sdk-and-sdk-subagent-backend.md |  6 +--
 ...escript-sdk-and-sdk-subagent-backend.zh.md |  6 +--
 ...07-27-web-subagent-conversations.i18n.yaml |  4 +-
 .../2026-07-27-web-subagent-conversations.md  |  6 +--
 ...026-07-27-web-subagent-conversations.zh.md |  6 +--
 ...-workspace-registration-deletion.i18n.yaml |  4 +-
 ...6-07-27-workspace-registration-deletion.md |  2 +-
 ...7-27-workspace-registration-deletion.zh.md |  2 +-
 ...ntinuable-subagent-conversations.i18n.yaml |  4 +-
 ...7-28-continuable-subagent-conversations.md | 10 ++--
 ...8-continuable-subagent-conversations.zh.md | 10 ++--
 ...26-07-28-skill-invocation-policy.i18n.yaml |  4 +-
 .../2026-07-28-skill-invocation-policy.md     |  4 +-
 .../2026-07-28-skill-invocation-policy.zh.md  |  2 +-
 .../2026-07-28-web-terminal-card.i18n.yaml    |  4 +-
 .../feature/2026-07-28-web-terminal-card.md   |  4 +-
 .../2026-07-28-web-terminal-card.zh.md        |  4 +-
 ...0-current-sandbox-policy-context.i18n.yaml |  4 +-
 ...26-07-30-current-sandbox-policy-context.md |  2 +-
 ...07-30-current-sandbox-policy-context.zh.md |  2 +-
 ...-plan-review-presentation-intent.i18n.yaml |  4 +-
 ...6-07-30-plan-review-presentation-intent.md |  4 +-
 ...7-30-plan-review-presentation-intent.zh.md |  2 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |  4 +-
 .../2026-07-30-web-result-card-frontend.md    |  4 +-
 .../2026-07-30-web-result-card-frontend.zh.md |  4 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |  4 +-
 .../2026-07-31-code-mode-language-dispatch.md |  6 +--
 ...26-07-31-code-mode-language-dispatch.zh.md |  6 +--
 ...7-31-web-telemetry-default-mount.i18n.yaml |  4 +-
 .../2026-07-31-web-telemetry-default-mount.md |  2 +-
 ...26-07-31-web-telemetry-default-mount.zh.md |  2 +-
 ...nter-revealed-sidebar-scrollbars.i18n.yaml |  4 +-
 ...-04-pointer-revealed-sidebar-scrollbars.md |  2 +-
 ...-pointer-revealed-sidebar-scrollbars.zh.md |  2 +-
 ...26-08-05-context-form-vocabulary.i18n.yaml |  4 +-
 .../2026-08-05-context-form-vocabulary.md     |  2 +-
 .../2026-08-05-context-form-vocabulary.zh.md  |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |  4 +-
 .../feature/2026-08-05-pwsh-ui-bash-parity.md |  4 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |  4 +-
 ...6-08-07-web-inline-file-mentions.i18n.yaml |  4 +-
 .../2026-08-07-web-inline-file-mentions.md    |  2 +-
 .../2026-08-07-web-inline-file-mentions.zh.md |  2 +-
 ...8-user-explicit-skill-invocation.i18n.yaml |  4 +-
 ...26-08-08-user-explicit-skill-invocation.md |  2 +-
 ...08-08-user-explicit-skill-invocation.zh.md |  2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  4 +-
 ...2026-06-20-core-data-structures-catalog.md | 22 ++++-----
 ...6-06-20-core-data-structures-catalog.zh.md | 24 +++++-----
 .../2026-07-02-tool-schema-catalog.i18n.yaml  |  4 +-
 .../process/2026-07-02-tool-schema-catalog.md |  4 +-
 .../2026-07-02-tool-schema-catalog.zh.md      |  4 +-
 .../2026-07-20-gui-testing-system.i18n.yaml   |  4 +-
 .../process/2026-07-20-gui-testing-system.md  |  2 +-
 .../2026-07-20-gui-testing-system.zh.md       |  2 +-
 ...package-anchored-subsystem-pages.i18n.yaml |  4 +-
 ...-08-03-package-anchored-subsystem-pages.md |  2 +-
 ...-03-package-anchored-subsystem-pages.zh.md |  2 +-
 ...-06-20-public-agent-stop-surface.i18n.yaml |  4 +-
 .../2026-06-20-public-agent-stop-surface.md   |  4 +-
 ...2026-06-20-public-agent-stop-surface.zh.md |  4 +-
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |  4 +-
 .../2026-06-26-fsspec-style-fs-seam.md        | 10 ++--
 .../2026-06-26-fsspec-style-fs-seam.zh.md     | 10 ++--
 ...4-tighten-hook-protocol-contract.i18n.yaml |  4 +-
 ...26-07-04-tighten-hook-protocol-contract.md |  2 +-
 ...07-04-tighten-hook-protocol-contract.zh.md |  2 +-
 ...lan-specific-collaboration-state.i18n.yaml |  4 +-
 ...07-22-plan-specific-collaboration-state.md |  2 +-
 ...22-plan-specific-collaboration-state.zh.md |  2 +-
 ...-23-acp-automation-only-protocol.i18n.yaml |  4 +-
 ...2026-07-23-acp-automation-only-protocol.md |  2 +-
 ...6-07-23-acp-automation-only-protocol.zh.md |  2 +-
 ...nt-loop-observable-state-machine.i18n.yaml |  4 +-
 ...-24-agent-loop-observable-state-machine.md |  2 +-
 ...-agent-loop-observable-state-machine.zh.md |  4 +-
 ...6-merge-subagent-control-service.i18n.yaml |  4 +-
 ...26-07-26-merge-subagent-control-service.md |  2 +-
 ...07-26-merge-subagent-control-service.zh.md |  2 +-
 ...-remove-synthetic-log-only-turns.i18n.yaml |  4 +-
 ...6-07-28-remove-synthetic-log-only-turns.md |  2 +-
 ...7-28-remove-synthetic-log-only-turns.zh.md |  2 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |  4 +-
 ...2026-07-31-one-route-to-add-a-workspace.md |  2 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |  2 +-
 .../2026-08-04-remove-tui-package.i18n.yaml   |  4 +-
 .../2026-08-04-remove-tui-package.md          |  2 +-
 .../2026-08-04-remove-tui-package.zh.md       |  2 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |  4 +-
 ...6-06-22-fork-child-replay-seed-boundary.md |  2 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |  2 +-
 ...6-06-22-subagent-snapshot-replay.i18n.yaml |  4 +-
 .../2026-06-22-subagent-snapshot-replay.md    |  2 +-
 .../2026-06-22-subagent-snapshot-replay.zh.md |  2 +-
 ...-22-cross-platform-test-fixtures.i18n.yaml |  4 +-
 ...2026-07-22-cross-platform-test-fixtures.md |  2 +-
 ...6-07-22-cross-platform-test-fixtures.zh.md |  2 +-
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |  4 +-
 .../2026-07-24-web-gui-browser-e2e-lane.md    |  8 ++--
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |  8 ++--
 .../2026-06-16-typed-event-schemas.i18n.yaml  |  4 +-
 .../2026-06-16-typed-event-schemas.md         |  4 +-
 .../2026-06-16-typed-event-schemas.zh.md      |  4 +-
 ...on-through-tool-capability-seams.i18n.yaml |  4 +-
 ...cellation-through-tool-capability-seams.md |  2 +-
 ...lation-through-tool-capability-seams.zh.md |  2 +-
 ...-25-client-settings-locale-theme.i18n.yaml |  4 +-
 ...2026-07-25-client-settings-locale-theme.md |  2 +-
 ...6-07-25-client-settings-locale-theme.zh.md |  6 +--
 ...ssion-projection-and-command-log.i18n.yaml |  4 +-
 ...7-27-session-projection-and-command-log.md |  4 +-
 ...7-session-projection-and-command-log.zh.md |  6 +--
 ...026-06-30-pre-tool-input-rewrite.i18n.yaml |  4 +-
 .../2026-06-30-pre-tool-input-rewrite.md      |  4 +-
 .../2026-06-30-pre-tool-input-rewrite.zh.md   |  4 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |  4 +-
 .../2026-07-06-recallable-compaction.md       |  2 +-
 .../2026-07-06-recallable-compaction.zh.md    |  2 +-
 ...-07-08-interactive-side-sessions.i18n.yaml |  4 +-
 .../2026-07-08-interactive-side-sessions.md   |  2 +-
 ...2026-07-08-interactive-side-sessions.zh.md |  2 +-
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |  4 +-
 .../2026-07-17-sdk-follow-up-capabilities.md  |  2 +-
 ...026-07-17-sdk-follow-up-capabilities.zh.md |  2 +-
 ...04-prune-dead-core-spine-surface.i18n.yaml |  4 +-
 ...026-07-04-prune-dead-core-spine-surface.md |  6 +--
 ...-07-04-prune-dead-core-spine-surface.zh.md |  6 +--
 ...ld-session-persistence-interface.i18n.yaml |  4 +-
 ...6-20-fold-session-persistence-interface.md | 10 ++--
 ...0-fold-session-persistence-interface.zh.md | 10 ++--
 ...apse-workflow-to-foreground-core.i18n.yaml |  4 +-
 ...12-collapse-workflow-to-foreground-core.md |  4 +-
 ...collapse-workflow-to-foreground-core.zh.md |  4 +-
 ...ne-unused-skill-registry-surface.i18n.yaml |  4 +-
 ...-12-prune-unused-skill-registry-surface.md |  2 +-
 ...-prune-unused-skill-registry-surface.zh.md |  2 +-
 ...19-fold-compaction-package-split.i18n.yaml |  4 +-
 ...026-07-19-fold-compaction-package-split.md |  8 ++--
 ...-07-19-fold-compaction-package-split.zh.md |  8 ++--
 AGENTS.md                                     | 40 ++++++++--------
 apps/web/tests/approval-composer.e2e.ts       |  2 +-
 apps/web/tests/default-model.e2e.ts           |  2 +-
 apps/web/tests/lifecycle-chrome.e2e.ts        |  2 +-
 apps/web/tests/live-interactions.e2e.ts       |  2 +-
 apps/web/tests/models-settings.e2e.ts         |  2 +-
 apps/web/tests/replay-round-trip.e2e.ts       |  2 +-
 apps/web/tests/scaffold.ts                    |  2 +-
 .../tests/sidebar-subagent-activity.e2e.ts    |  2 +-
 apps/web/tests/skill-user-invoke.e2e.ts       |  4 +-
 docs/AGENTS.md                                |  6 +--
 docs/architecture.i18n.yaml                   |  4 +-
 docs/architecture.md                          |  8 ++--
 docs/architecture.zh.md                       |  8 ++--
 docs/config-catalog.i18n.yaml                 |  4 +-
 docs/config-catalog.md                        |  4 +-
 docs/config-catalog.zh.md                     |  4 +-
 docs/cookbook/adding-a-package.i18n.yaml      |  4 +-
 docs/cookbook/adding-a-package.md             |  2 +-
 docs/cookbook/adding-a-package.zh.md          |  2 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |  4 +-
 docs/cookbook/extension-cookbook.md           |  8 ++--
 docs/cookbook/extension-cookbook.zh.md        |  8 ++--
 docs/defensive-patterns.i18n.yaml             |  4 +-
 docs/defensive-patterns.md                    |  4 +-
 docs/defensive-patterns.zh.md                 |  6 +--
 docs/event-producer-consumer.i18n.yaml        |  4 +-
 docs/event-producer-consumer.md               |  2 +-
 docs/event-producer-consumer.zh.md            |  2 +-
 docs/glossary.i18n.yaml                       |  4 +-
 docs/glossary.md                              |  2 +-
 docs/glossary.zh.md                           |  2 +-
 docs/i18n/terminology.md                      |  4 +-
 docs/i18n/translation-prompt.md               |  2 +-
 docs/subsystems/README.i18n.yaml              |  4 +-
 docs/subsystems/README.md                     | 10 ++--
 docs/subsystems/README.zh.md                  | 10 ++--
 docs/subsystems/bash.i18n.yaml                |  4 +-
 docs/subsystems/bash.md                       |  8 ++--
 docs/subsystems/bash.zh.md                    |  8 ++--
 docs/subsystems/code-runtime.i18n.yaml        |  4 +-
 docs/subsystems/code-runtime.md               | 14 +++---
 docs/subsystems/code-runtime.zh.md            | 12 ++---
 docs/subsystems/commands.i18n.yaml            |  4 +-
 docs/subsystems/commands.md                   |  4 +-
 docs/subsystems/commands.zh.md                |  4 +-
 docs/subsystems/compaction.i18n.yaml          |  4 +-
 docs/subsystems/compaction.md                 |  8 ++--
 docs/subsystems/compaction.zh.md              |  8 ++--
 docs/subsystems/core.i18n.yaml                |  4 +-
 docs/subsystems/core.md                       | 14 +++---
 docs/subsystems/core.zh.md                    | 14 +++---
 docs/subsystems/credentials.i18n.yaml         |  4 +-
 docs/subsystems/credentials.md                |  4 +-
 docs/subsystems/credentials.zh.md             |  4 +-
 docs/subsystems/filesystem.i18n.yaml          |  4 +-
 docs/subsystems/filesystem.md                 | 16 +++----
 docs/subsystems/filesystem.zh.md              | 16 +++----
 docs/subsystems/invariants.i18n.yaml          |  4 +-
 docs/subsystems/invariants.md                 |  2 +-
 docs/subsystems/invariants.zh.md              |  2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |  4 +-
 docs/subsystems/llm-streaming.md              |  4 +-
 docs/subsystems/llm-streaming.zh.md           |  4 +-
 docs/subsystems/lsp.i18n.yaml                 |  4 +-
 docs/subsystems/lsp.md                        |  2 +-
 docs/subsystems/lsp.zh.md                     |  2 +-
 docs/subsystems/persistence.i18n.yaml         |  4 +-
 docs/subsystems/persistence.md                |  4 +-
 docs/subsystems/persistence.zh.md             |  4 +-
 docs/subsystems/plan.i18n.yaml                |  4 +-
 docs/subsystems/plan.md                       |  2 +-
 docs/subsystems/plan.zh.md                    |  2 +-
 docs/subsystems/sandbox.i18n.yaml             |  4 +-
 docs/subsystems/sandbox.md                    |  4 +-
 docs/subsystems/sandbox.zh.md                 |  4 +-
 docs/subsystems/session-projection.i18n.yaml  |  4 +-
 docs/subsystems/session-projection.md         |  2 +-
 docs/subsystems/session-projection.zh.md      |  2 +-
 docs/subsystems/session-query.i18n.yaml       |  4 +-
 docs/subsystems/session-query.md              |  6 +--
 docs/subsystems/session-query.zh.md           |  6 +--
 docs/subsystems/session.i18n.yaml             |  4 +-
 docs/subsystems/session.md                    |  2 +-
 docs/subsystems/session.zh.md                 |  2 +-
 docs/subsystems/settings.i18n.yaml            |  4 +-
 docs/subsystems/settings.md                   |  4 +-
 docs/subsystems/settings.zh.md                |  4 +-
 docs/subsystems/skills.i18n.yaml              |  4 +-
 docs/subsystems/skills.md                     |  6 +--
 docs/subsystems/skills.zh.md                  |  6 +--
 docs/subsystems/spill.i18n.yaml               |  4 +-
 docs/subsystems/spill.md                      |  8 ++--
 docs/subsystems/spill.zh.md                   |  8 ++--
 docs/subsystems/storage.i18n.yaml             |  4 +-
 docs/subsystems/storage.md                    |  4 +-
 docs/subsystems/storage.zh.md                 |  4 +-
 docs/subsystems/subagent.i18n.yaml            |  4 +-
 docs/subsystems/subagent.md                   | 12 ++---
 docs/subsystems/subagent.zh.md                | 14 +++---
 docs/subsystems/subprocess.i18n.yaml          |  4 +-
 docs/subsystems/subprocess.md                 | 10 ++--
 docs/subsystems/subprocess.zh.md              | 10 ++--
 docs/subsystems/tasks.i18n.yaml               |  4 +-
 docs/subsystems/tasks.md                      |  6 +--
 docs/subsystems/tasks.zh.md                   |  6 +--
 docs/subsystems/telemetry.i18n.yaml           |  4 +-
 docs/subsystems/telemetry.md                  | 16 +++----
 docs/subsystems/telemetry.zh.md               | 16 +++----
 docs/subsystems/tools.i18n.yaml               |  4 +-
 docs/subsystems/tools.md                      |  6 +--
 docs/subsystems/tools.zh.md                   |  6 +--
 docs/subsystems/web.i18n.yaml                 |  4 +-
 docs/subsystems/web.md                        |  4 +-
 docs/subsystems/web.zh.md                     |  4 +-
 docs/subsystems/workflow.i18n.yaml            |  4 +-
 docs/subsystems/workflow.md                   |  8 ++--
 docs/subsystems/workflow.zh.md                |  8 ++--
 docs/subsystems/workspace.i18n.yaml           |  4 +-
 docs/subsystems/workspace.md                  |  4 +-
 docs/subsystems/workspace.zh.md               |  4 +-
 docs/user/develop/basic/tool.i18n.yaml        |  4 +-
 docs/user/develop/basic/tool.md               |  2 +-
 docs/user/develop/basic/tool.zh.md            |  2 +-
 docs/user/develop/practice/index.i18n.yaml    |  4 +-
 docs/user/develop/practice/index.md           | 44 ++++++++---------
 docs/user/develop/practice/index.zh.md        | 48 +++++++++----------
 docs/user/guide/config.i18n.yaml              |  2 +-
 docs/user/guide/config.md                     |  2 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  2 +-
 native/landlock-run/AGENTS.md                 |  4 +-
 native/landlock-run/docs/architecture.md      |  2 +-
 .../landlock-run/packages/entry/src/index.ts  |  4 +-
 native/landlock-run/test/entry.test.js        |  2 +-
 packages/AGENTS.md                            |  2 +-
 packages/README.i18n.yaml                     |  4 +-
 packages/README.md                            | 12 ++---
 packages/README.zh.md                         | 12 ++---
 packages/bash/README.i18n.yaml                |  4 +-
 packages/bash/README.md                       |  2 +-
 packages/bash/README.zh.md                    |  8 ++--
 packages/bash/bash-local/README.i18n.yaml     |  4 +-
 packages/bash/bash-local/README.md            |  2 +-
 packages/bash/bash-local/README.zh.md         |  2 +-
 packages/bash/bash-local/src/index.ts         |  4 +-
 packages/bash/bash-sandbox/README.i18n.yaml   |  4 +-
 packages/bash/bash-sandbox/README.md          |  2 +-
 packages/bash/bash-sandbox/README.zh.md       |  2 +-
 packages/bash/bash/README.i18n.yaml           |  4 +-
 packages/bash/bash/README.md                  | 12 ++---
 packages/bash/bash/README.zh.md               | 12 ++---
 packages/bash/bash/src/index.ts               |  2 +-
 packages/bash/bash/src/invariant.ts           |  2 +-
 packages/bash/pwsh-local/README.i18n.yaml     |  4 +-
 packages/bash/pwsh-local/README.md            |  2 +-
 packages/bash/pwsh-local/README.zh.md         |  2 +-
 packages/bash/pwsh-local/src/index.ts         |  4 +-
 packages/bash/tool-bash/README.i18n.yaml      |  4 +-
 packages/bash/tool-bash/README.md             |  6 +--
 packages/bash/tool-bash/README.zh.md          |  6 +--
 packages/bash/tool-bash/src/index.ts          |  4 +-
 .../bash/tool-bash/tests/integration.spec.ts  |  2 +-
 packages/bash/tool-pwsh/src/background.ts     |  2 +-
 packages/bash/tool-pwsh/src/index.ts          |  4 +-
 packages/boot/app-boot/src/profile.ts         | 10 ++--
 packages/bundle/headless/README.i18n.yaml     |  4 +-
 packages/bundle/headless/README.md            |  4 +-
 packages/bundle/headless/README.zh.md         |  4 +-
 packages/bundle/web-app/src/index.ts          |  2 +-
 packages/bundle/web-app/tests/web-app.spec.ts |  4 +-
 packages/client/AGENTS.md                     |  2 +-
 packages/client/connection/README.i18n.yaml   |  4 +-
 packages/client/connection/README.md          |  2 +-
 packages/client/connection/README.zh.md       |  2 +-
 packages/client/connection/src/client/api.ts  |  2 +-
 packages/client/locale/src/client/index.ts    |  2 +-
 packages/client/locale/tests/locale.spec.ts   |  2 +-
 packages/client/modules/README.i18n.yaml      |  4 +-
 packages/client/modules/README.md             |  2 +-
 packages/client/modules/README.zh.md          |  2 +-
 .../client/modules/src/client/manifest.ts     | 16 +++----
 packages/client/modules/src/client/system.ts  |  8 ++--
 packages/client/modules/tests/loader.spec.ts  |  2 +-
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          | 12 ++---
 .../runtime/src/client/contract/sessions.ts   |  2 +-
 .../src/client/sessions/projection-store.ts   |  2 +-
 .../runtime/src/client/sessions/service.ts    |  6 +--
 .../runtime/src/client/sessions/session.ts    |  2 +-
 .../src/client/sessions/transcript-adapter.ts |  4 +-
 packages/client/runtime/src/client/slots.ts   |  2 +-
 .../src/client/workspaces/workspace.ts        |  2 +-
 .../tests/compact-checkpoint-pin.spec.ts      | 10 ++--
 .../runtime/tests/projection-store.spec.ts    |  2 +-
 .../runtime/tests/slots-service.spec.ts       |  8 ++--
 packages/client/schema-form/README.i18n.yaml  |  4 +-
 packages/client/schema-form/README.md         |  2 +-
 packages/client/schema-form/README.zh.md      |  2 +-
 packages/client/test-runtime/src/index.ts     |  8 ++--
 packages/client/test-runtime/src/sessions.ts  |  2 +-
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../ui-conversation/src/client/apply.ts       |  2 +-
 .../src/client/input/facade.ts                |  2 +-
 .../src/client/queue/QueueDock.tsx            |  2 +-
 .../tests/input-scenarios.spec.tsx            |  2 +-
 .../tests/selection-survival.spec.tsx         |  2 +-
 packages/client/ui-layout/src/client/index.ts |  2 +-
 .../client/ui-layout/src/client/service.ts    |  2 +-
 .../client/ui-layout/tests/service.spec.ts    |  2 +-
 packages/client/ui-model/README.i18n.yaml     |  4 +-
 packages/client/ui-model/README.md            |  2 +-
 packages/client/ui-model/README.zh.md         |  2 +-
 packages/client/ui-model/src/client/index.ts  |  2 +-
 .../client/ui-primitives/src/clipboard.ts     |  2 +-
 .../ui-primitives/src/markdown/incremental.ts |  2 +-
 .../ui-primitives/tests/diff-block.spec.tsx   |  2 +-
 .../tests/terminal-block.spec.tsx             |  2 +-
 .../ui-sidebar/src/client/contract/slots.ts   |  2 +-
 .../client/ui-slash/src/client/controller.ts  |  2 +-
 packages/client/ui-slots/README.i18n.yaml     |  4 +-
 packages/client/ui-slots/README.md            |  6 +--
 packages/client/ui-slots/README.zh.md         |  6 +--
 packages/client/ui-slots/src/index.ts         |  6 +--
 packages/client/ui-slots/src/renderer.ts      | 10 ++--
 .../ui-theme/src/client/settings-contract.ts  |  2 +-
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  5 +-
 .../ui-tool/tests/toolview-slot.spec.tsx      |  2 +-
 .../client/web-react/src/scoped-slots.tsx     |  4 +-
 packages/client/web/README.i18n.yaml          |  4 +-
 packages/client/web/README.md                 |  4 +-
 packages/client/web/README.zh.md              |  4 +-
 packages/client/web/src/boot.tsx              |  8 ++--
 packages/code-runtime/README.i18n.yaml        |  4 +-
 packages/code-runtime/README.md               |  6 +--
 packages/code-runtime/README.zh.md            |  6 +--
 .../code-runtime-worker/src/index.ts          |  6 +--
 .../code-runtime/README.i18n.yaml             |  4 +-
 packages/code-runtime/code-runtime/README.md  |  6 +--
 .../code-runtime/code-runtime/README.zh.md    |  6 +--
 .../code-runtime/code-runtime/src/index.ts    |  6 +--
 .../code-runtime/code-runtime/src/types.ts    |  2 +-
 .../code-runtime/tests/reserved.spec.ts       |  2 +-
 .../code-runtime/tests/service.spec.ts        |  2 +-
 packages/compact/README.i18n.yaml             |  4 +-
 packages/compact/README.md                    |  2 +-
 packages/compact/README.zh.md                 |  2 +-
 .../compact/compact-basic/README.i18n.yaml    |  4 +-
 packages/compact/compact-basic/README.md      |  6 +--
 packages/compact/compact-basic/README.zh.md   |  6 +--
 packages/compact/compact/README.i18n.yaml     |  4 +-
 packages/compact/compact/README.md            | 16 +++----
 packages/compact/compact/README.zh.md         | 16 +++----
 packages/compact/compact/src/index.ts         |  2 +-
 .../compact/compact/tests/compact.spec.ts     |  2 +-
 .../context/tmux-context/README.i18n.yaml     |  4 +-
 packages/context/tmux-context/README.md       |  2 +-
 packages/context/tmux-context/README.zh.md    |  2 +-
 packages/context/tmux-context/src/index.ts    |  4 +-
 packages/core/README.i18n.yaml                |  4 +-
 packages/core/README.md                       |  2 +-
 packages/core/README.zh.md                    |  2 +-
 packages/core/agent-loop/README.i18n.yaml     |  4 +-
 packages/core/agent-loop/README.md            |  6 +--
 packages/core/agent-loop/README.zh.md         |  6 +--
 packages/core/agent-loop/src/index.ts         |  2 +-
 packages/core/agent-loop/tests/cancel.spec.ts |  2 +-
 .../agent-loop/tests/interception.spec.ts     |  2 +-
 packages/core/agent/README.i18n.yaml          |  4 +-
 packages/core/agent/README.md                 |  6 +--
 packages/core/agent/README.zh.md              |  8 ++--
 packages/core/agent/src/inbox.ts              |  2 +-
 packages/core/agent/src/index.ts              |  2 +-
 packages/core/agent/src/types.ts              |  6 +--
 packages/core/session/README.i18n.yaml        |  4 +-
 packages/core/session/README.md               |  6 +--
 packages/core/session/README.zh.md            |  6 +--
 packages/core/session/src/index.ts            |  2 +-
 packages/core/system-prompt/README.i18n.yaml  |  4 +-
 packages/core/system-prompt/README.md         |  2 +-
 packages/core/system-prompt/README.zh.md      |  2 +-
 packages/core/tools/README.i18n.yaml          |  4 +-
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/README.zh.md              |  2 +-
 packages/core/tools/src/code-mode.ts          |  2 +-
 packages/core/tools/src/index.ts              |  6 +--
 packages/core/tools/src/presentation.ts       |  6 +--
 packages/core/tools/src/py-types.ts           |  2 +-
 packages/core/tools/tests/code-mode.spec.ts   |  2 +-
 packages/core/tools/tests/tools.spec.ts       |  4 +-
 .../credentials-local/src/invariant.ts        |  2 +-
 .../credentials/credentials/README.i18n.yaml  |  4 +-
 packages/credentials/credentials/README.md    |  2 +-
 packages/credentials/credentials/README.zh.md |  2 +-
 packages/credentials/credentials/src/index.ts |  2 +-
 packages/e2b/fs-e2b/README.i18n.yaml          |  4 +-
 packages/e2b/fs-e2b/README.md                 |  4 +-
 packages/e2b/fs-e2b/README.zh.md              |  4 +-
 packages/e2b/fs-e2b/src/index.ts              |  2 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  2 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  2 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  2 +-
 .../agent-spine-demo/README.i18n.yaml         |  4 +-
 packages/examples/agent-spine-demo/README.md  |  4 +-
 .../examples/agent-spine-demo/README.zh.md    |  4 +-
 packages/fs/README.i18n.yaml                  |  4 +-
 packages/fs/README.md                         |  8 ++--
 packages/fs/README.zh.md                      | 14 +++---
 packages/fs/fs-local/README.i18n.yaml         |  4 +-
 packages/fs/fs-local/README.md                |  2 +-
 packages/fs/fs-local/README.zh.md             |  2 +-
 packages/fs/fs-local/src/fsio.ts              |  4 +-
 packages/fs/fs-local/src/index.ts             |  2 +-
 packages/fs/fs-local/tests/filesystem.spec.ts |  4 +-
 packages/fs/fs-policy/README.i18n.yaml        |  4 +-
 packages/fs/fs-policy/README.md               |  4 +-
 packages/fs/fs-policy/README.zh.md            |  4 +-
 packages/fs/fs-sandbox/src/index.ts           |  2 +-
 packages/fs/fs/README.i18n.yaml               |  4 +-
 packages/fs/fs/README.md                      |  6 +--
 packages/fs/fs/README.zh.md                   | 26 +++++-----
 packages/fs/fs/src/index.ts                   |  2 +-
 packages/fs/fs/src/types.ts                   |  2 +-
 packages/fs/fs/tests/service.spec.ts          |  2 +-
 packages/fs/tool-fs/README.i18n.yaml          |  4 +-
 packages/fs/tool-fs/README.md                 |  2 +-
 packages/fs/tool-fs/README.zh.md              |  2 +-
 packages/fs/tool-fs/src/session-cwd.ts        |  2 +-
 packages/goal/goal-session/README.i18n.yaml   |  4 +-
 packages/goal/goal-session/README.md          |  2 +-
 packages/goal/goal-session/README.zh.md       |  2 +-
 packages/goal/goal-session/src/index.ts       |  2 +-
 packages/guard/README.i18n.yaml               |  4 +-
 packages/guard/README.md                      |  2 +-
 packages/guard/README.zh.md                   |  4 +-
 packages/guard/timeout-policy/src/index.ts    |  2 +-
 packages/hooks/README.i18n.yaml               |  4 +-
 packages/hooks/README.md                      |  2 +-
 packages/hooks/README.zh.md                   |  2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |  4 +-
 packages/hooks/hook-protocol/README.md        |  4 +-
 packages/hooks/hook-protocol/README.zh.md     |  4 +-
 packages/hooks/hook-protocol/src/detached.ts  |  2 +-
 packages/hooks/hook-protocol/src/index.ts     |  2 +-
 packages/hooks/hook-protocol/src/merge.ts     |  2 +-
 packages/hooks/hook-protocol/src/runner.ts    |  2 +-
 packages/hooks/hook-protocol/src/types.ts     | 10 ++--
 .../hooks/hook-protocol/tests/runner.spec.ts  |  2 +-
 packages/hooks/hooks-claude/README.i18n.yaml  |  4 +-
 packages/hooks/hooks-claude/README.md         | 10 ++--
 packages/hooks/hooks-claude/README.zh.md      | 10 ++--
 packages/hooks/hooks-claude/src/index.ts      | 12 ++---
 .../hooks-claude/tests/coverage-cases.ts      |  2 +-
 packages/hooks/hooks-codex/README.i18n.yaml   |  4 +-
 packages/hooks/hooks-codex/README.md          |  8 ++--
 packages/hooks/hooks-codex/README.zh.md       |  8 ++--
 packages/hooks/hooks-codex/src/index.ts       |  8 ++--
 .../hooks/hooks-codex/tests/coverage-cases.ts |  2 +-
 packages/host/apiproxy/src/api-proxy.ts       |  6 +--
 packages/host/apiproxy/src/api/events.ts      |  2 +-
 .../host/apiproxy/src/native-path-opener.ts   |  4 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |  2 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |  2 +-
 .../tests/api-proxy-subagents.spec.ts         |  2 +-
 .../src/native-picker.ts                      |  2 +-
 .../src/win32-dialog-logic.ts                 |  2 +-
 .../src/win32-dialog.ts                       |  2 +-
 packages/host/directory-picker/src/index.ts   |  2 +-
 .../host/directory-picker/src/invariant.ts    |  5 +-
 packages/host/webserver/src/index.ts          |  2 +-
 packages/interaction/README.i18n.yaml         |  4 +-
 packages/interaction/README.md                |  2 +-
 packages/interaction/README.zh.md             |  2 +-
 .../tool-ask-user/README.i18n.yaml            |  4 +-
 packages/interaction/tool-ask-user/README.md  |  2 +-
 .../interaction/tool-ask-user/README.zh.md    |  2 +-
 .../interaction/tool-ask-user/src/index.ts    |  2 +-
 .../interaction/user-approval/src/index.ts    |  2 +-
 .../user-interaction/README.i18n.yaml         |  4 +-
 .../interaction/user-interaction/README.md    |  4 +-
 .../interaction/user-interaction/README.zh.md |  4 +-
 .../interaction/user-interaction/src/index.ts |  2 +-
 packages/llm/README.i18n.yaml                 |  4 +-
 packages/llm/README.md                        |  2 +-
 packages/llm/README.zh.md                     |  6 +--
 packages/llm/llm-deepseek/src/adapter.ts      |  4 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |  4 +-
 packages/llm/llm-pi-ai/README.md              |  2 +-
 packages/llm/llm-pi-ai/README.zh.md           |  2 +-
 packages/llm/llm-pi-ai/src/adapter.ts         |  2 +-
 packages/llm/llm-retry/src/index.ts           |  6 +--
 packages/llm/llm/README.i18n.yaml             |  4 +-
 packages/llm/llm/README.md                    |  4 +-
 packages/llm/llm/README.zh.md                 |  4 +-
 packages/llm/llm/src/error.ts                 |  2 +-
 packages/llm/llm/src/retry-policy.ts          |  2 +-
 packages/llm/llm/tests/attribution.spec.ts    |  2 +-
 packages/llm/token-meter/src/index.ts         |  2 +-
 packages/lsp/README.i18n.yaml                 |  4 +-
 packages/lsp/README.md                        |  6 +--
 packages/lsp/README.zh.md                     |  6 +--
 packages/lsp/lsp-local/src/connection.ts      |  6 +--
 packages/lsp/lsp-local/src/instance.ts        |  2 +-
 packages/lsp/lsp-local/src/translate.ts       |  6 +--
 packages/lsp/lsp/README.i18n.yaml             |  4 +-
 packages/lsp/lsp/README.md                    |  8 ++--
 packages/lsp/lsp/README.zh.md                 |  8 ++--
 packages/lsp/lsp/src/index.ts                 |  2 +-
 packages/lsp/tool-lsp/README.i18n.yaml        |  4 +-
 packages/lsp/tool-lsp/README.md               |  2 +-
 packages/lsp/tool-lsp/README.zh.md            |  2 +-
 .../plan/plan-mode/tests/plan-mode.spec.ts    |  2 +-
 packages/sandbox/sandbox-local/src/index.ts   |  8 ++--
 .../sandbox/sandbox-local/tests/local.spec.ts |  6 +--
 packages/sandbox/sandbox/README.i18n.yaml     |  4 +-
 packages/sandbox/sandbox/README.md            |  4 +-
 packages/sandbox/sandbox/README.zh.md         |  6 +--
 packages/sandbox/sandbox/src/index.ts         |  2 +-
 packages/scaffold/create-sdk/src/headless.ts  |  2 +-
 packages/scaffold/scripts/src/telemetry.ts    |  4 +-
 packages/scaffold/server/README.i18n.yaml     |  4 +-
 packages/scaffold/server/README.md            |  2 +-
 packages/scaffold/server/README.zh.md         |  2 +-
 packages/scaffold/server/src/index.ts         |  8 ++--
 .../server/tests/plugin-apply.spec.ts         |  2 +-
 .../scaffold/telemetry/src/anonymous-id.ts    |  8 ++--
 packages/scaffold/telemetry/src/reporter.ts   |  4 +-
 .../repository-plugin/src/mcp.ts              |  2 +-
 .../tool-cordis/src/api-catalog.ts            | 20 ++++----
 .../session-query-sqlite/README.i18n.yaml     |  4 +-
 .../session-query-sqlite/README.md            |  2 +-
 .../session-query-sqlite/README.zh.md         |  2 +-
 .../session-query/session-query/src/index.ts  |  2 +-
 .../session-persistence-jsonl/src/index.ts    |  2 +-
 .../README.i18n.yaml                          |  4 +-
 .../session-persistence-sqlite/README.md      |  2 +-
 .../session-persistence-sqlite/README.zh.md   |  6 +--
 .../session-persistence/README.i18n.yaml      |  4 +-
 .../session/session-persistence/README.md     |  4 +-
 .../session/session-persistence/README.zh.md  |  4 +-
 .../session-persistence/src/coordinator.ts    |  2 +-
 .../session/session-persistence/src/index.ts  |  4 +-
 .../tests/persistence.spec.ts                 |  2 +-
 .../session-projection/README.i18n.yaml       |  4 +-
 packages/session/session-projection/README.md |  6 +--
 .../session/session-projection/README.zh.md   |  6 +--
 .../session/session-projection/src/index.ts   |  4 +-
 .../session/session-projection/src/types.ts   |  2 +-
 .../session-telemetry-otel/src/index.ts       |  8 ++--
 .../session-telemetry-otel/src/invariant.ts   |  2 +-
 .../session-telemetry-otel/src/user-id.ts     |  6 +--
 .../tests/user-id.spec.ts                     |  2 +-
 .../session-telemetry/README.i18n.yaml        |  4 +-
 packages/session/session-telemetry/README.md  |  6 +--
 .../session/session-telemetry/README.zh.md    |  6 +--
 .../session-telemetry/src/coordinator.ts      |  8 ++--
 .../session/session-telemetry/src/index.ts    | 10 ++--
 .../session-telemetry/src/invariant.ts        |  2 +-
 packages/session/session-title/src/index.ts   |  2 +-
 .../settings-local/tests/lock-race.spec.ts    |  2 +-
 packages/settings/settings/README.i18n.yaml   |  4 +-
 packages/settings/settings/README.md          |  2 +-
 packages/settings/settings/README.zh.md       |  2 +-
 packages/settings/settings/src/index.ts       |  8 ++--
 packages/settings/settings/tests/memory.ts    |  4 +-
 .../settings/settings/tests/settings.spec.ts  |  2 +-
 packages/skill/skill/src/index.ts             |  3 +-
 packages/skill/tool-skill/README.i18n.yaml    |  4 +-
 packages/skill/tool-skill/README.md           |  2 +-
 packages/skill/tool-skill/README.zh.md        |  6 +--
 packages/spill/spill-policy/src/index.ts      |  2 +-
 packages/spill/spill/README.i18n.yaml         |  4 +-
 packages/spill/spill/README.md                |  8 ++--
 packages/spill/spill/README.zh.md             |  8 ++--
 packages/spill/spill/src/index.ts             |  4 +-
 packages/spill/spill/src/types.ts             |  2 +-
 packages/spill/spill/tests/service.spec.ts    |  2 +-
 packages/storage/README.i18n.yaml             |  4 +-
 packages/storage/README.md                    |  2 +-
 packages/storage/README.zh.md                 |  2 +-
 .../storage/storage-domain/README.i18n.yaml   |  4 +-
 packages/storage/storage-domain/README.md     |  2 +-
 packages/storage/storage-domain/README.zh.md  |  2 +-
 packages/storage/storage-domain/src/domain.ts |  2 +-
 .../tests/helpers/memory-backend.ts           |  2 +-
 packages/subagent/README.i18n.yaml            |  4 +-
 packages/subagent/README.md                   |  2 +-
 packages/subagent/README.zh.md                |  2 +-
 .../subagent-acp/tests/subagent-acp.e2e.ts    |  2 +-
 .../subagent/subagent-claude-code/src/run.ts  |  4 +-
 packages/subagent/subagent-codex/src/run.ts   |  4 +-
 packages/subagent/subagent/README.i18n.yaml   |  4 +-
 packages/subagent/subagent/README.md          |  4 +-
 packages/subagent/subagent/README.zh.md       | 10 ++--
 packages/subagent/subagent/src/index.ts       |  6 +--
 packages/subagent/subagent/src/lifecycle.ts   |  2 +-
 .../subagent/subagent/src/list-children.ts    |  2 +-
 packages/subprocess/README.i18n.yaml          |  4 +-
 packages/subprocess/README.md                 |  4 +-
 packages/subprocess/README.zh.md              |  4 +-
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  4 +-
 .../subprocess/subprocess-local/README.zh.md  |  6 +--
 .../subprocess/subprocess-local/src/index.ts  | 12 ++---
 .../subprocess-local/src/terminal.ts          |  4 +-
 .../subprocess-local/tests/spawn.spec.ts      |  2 +-
 .../subprocess/subprocess/README.i18n.yaml    |  4 +-
 packages/subprocess/subprocess/README.md      |  4 +-
 packages/subprocess/subprocess/README.zh.md   |  4 +-
 packages/subprocess/subprocess/src/index.ts   |  2 +-
 .../subprocess/subprocess/src/invariant.ts    |  2 +-
 packages/subprocess/subprocess/src/types.ts   |  2 +-
 .../tests/fixtures/fake-acp-agent.ts          |  2 +-
 packages/support/invariants/src/index.ts      |  2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  2 +-
 packages/tasks/README.i18n.yaml               |  4 +-
 packages/tasks/README.md                      |  2 +-
 packages/tasks/README.zh.md                   |  2 +-
 packages/tasks/tasks-local/README.i18n.yaml   |  4 +-
 packages/tasks/tasks-local/README.md          |  2 +-
 packages/tasks/tasks-local/README.zh.md       |  2 +-
 packages/tasks/tasks-local/src/index.ts       |  4 +-
 packages/tasks/tasks-local/src/invariant.ts   |  2 +-
 packages/tasks/tasks/README.i18n.yaml         |  4 +-
 packages/tasks/tasks/README.md                |  2 +-
 packages/tasks/tasks/README.zh.md             |  2 +-
 packages/tasks/tasks/src/index.ts             |  2 +-
 packages/tasks/tasks/tests/service.spec.ts    |  2 +-
 packages/todo/README.i18n.yaml                |  4 +-
 packages/todo/README.md                       |  2 +-
 packages/todo/README.zh.md                    |  2 +-
 packages/todo/tool-todo/README.i18n.yaml      |  4 +-
 packages/todo/tool-todo/README.md             |  2 +-
 packages/todo/tool-todo/README.zh.md          |  2 +-
 .../todo/tool-todo/tests/integration.spec.ts  |  2 +-
 .../typert/generator/src/cordis-catalog.ts    |  6 ++-
 .../tests/cordis-catalog-contract.spec.ts     |  2 +-
 packages/web/tool-web/README.i18n.yaml        |  4 +-
 packages/web/tool-web/README.md               |  2 +-
 packages/web/tool-web/README.zh.md            |  2 +-
 packages/web/tool-web/src/fetch.ts            |  2 +-
 packages/web/web-fetch-local/README.i18n.yaml |  4 +-
 packages/web/web-fetch-local/README.md        |  2 +-
 packages/web/web-fetch-local/README.zh.md     |  2 +-
 .../web/web-search-deepseek/src/provider.ts   |  2 +-
 packages/web/web-search-exa/README.i18n.yaml  |  4 +-
 packages/web/web-search-exa/README.md         |  2 +-
 packages/web/web-search-exa/README.zh.md      |  2 +-
 packages/web/web-search-exa/src/provider.ts   |  2 +-
 .../web-search-perplexity/README.i18n.yaml    |  4 +-
 packages/web/web-search-perplexity/README.md  |  4 +-
 .../web/web-search-perplexity/README.zh.md    |  4 +-
 packages/web/web/README.i18n.yaml             |  4 +-
 packages/web/web/README.md                    | 14 +++---
 packages/web/web/README.zh.md                 | 16 +++----
 packages/web/web/src/index.ts                 |  2 +-
 packages/workflow/tool-ralph/src/index.ts     |  2 +-
 .../workflow-workerthread/src/runtime.ts      |  4 +-
 packages/workflow/workflow/src/index.ts       |  4 +-
 .../request-response.expected.json            |  2 +-
 vitest.config.ts                              |  2 +-
 966 files changed, 2166 insertions(+), 2159 deletions(-)
 rename .agents/notes/implemented/architecture/{2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml => 2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml} (64%)
 rename .agents/notes/implemented/architecture/{2026-06-18-agent-lifecycle-and-ownership-seams.md => 2026-06-18-agent-lifecycle-and-ownership-contracts.md} (72%)
 rename .agents/notes/implemented/architecture/{2026-06-18-agent-lifecycle-and-ownership-seams.zh.md => 2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md} (71%)
 rename .agents/notes/implemented/feature/{2026-06-30-interception-seams.i18n.yaml => 2026-06-30-interception-extension-points.i18n.yaml} (56%)
 rename .agents/notes/implemented/feature/{2026-06-30-interception-seams.md => 2026-06-30-interception-extension-points.md} (83%)
 rename .agents/notes/implemented/feature/{2026-06-30-interception-seams.zh.md => 2026-06-30-interception-extension-points.zh.md} (76%)

diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
index f89d1da013..5027c64154 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.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 .agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
-2026-06-11-dev-invariants-over-deep-readonly.md: f1a741927cf63b43b1aaf558efc148ff80d2d881
-2026-06-11-dev-invariants-over-deep-readonly.zh.md: ade3e20adb8f5301adb87130d42c2bd7a37f8a47
+2026-06-11-dev-invariants-over-deep-readonly.md: 66980f1ee09c6112f72786d6c3a147aadbc57f6c
+2026-06-11-dev-invariants-over-deep-readonly.zh.md: 38a19ee7dd63823b5a5e103908410786c20435c6
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
index f1a741927c..66980f1ee0 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-11-dev-invariants-over-deep-readonly.zh.md)
 
 ## Problem
 
-The session log needs two different protections: immutable ownership of each stored fact, and checks for relationships among facts across time and service seams. Conflating them in an optional development plugin would leave production history vulnerable; trying to express both through TypeScript readonly types would not create a runtime boundary or describe relational rules.
+The session log needs two different protections: immutable ownership of each stored fact, and checks for relationships among facts across time and service contracts. Conflating them in an optional development plugin would leave production history vulnerable; trying to express both through TypeScript readonly types would not create a runtime boundary or describe relational rules.
 
 The session log is the durable source of truth for replay, request reconstruction, persistence, and user-visible history. Code outside the session package must be able to inspect that history without retaining a reference that can rewrite it later, and inputs accepted from callers must not remain connected to caller-owned mutable objects.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
index ade3e20adb..38a19ee7dd 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务 seam 的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
+会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务约定的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
 
 会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
index 5a5aa0eaea..6c3244e519 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.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 .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
-2026-06-11-microkernel-event-taxonomy.md: fe6c242acbc0b64123711a17a528f35c02d91087
-2026-06-11-microkernel-event-taxonomy.zh.md: aa3db53d640145836817f9835a30c69815f70d23
+2026-06-11-microkernel-event-taxonomy.md: 6cacbc30f29c863de0f8ddfa4df7251a64bc80ca
+2026-06-11-microkernel-event-taxonomy.zh.md: 40edfa1ada0c11395e8ff29e0abfcb0c38de096a
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
index fe6c242acb..6cacbc30f2 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
@@ -10,14 +10,14 @@ The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic
 
 ## Decision
 
-Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:
+Pure Cordis event taxonomy. The loop's extension points are typed events with deliberate dispatch modes:
 
 - **waterfall** (around-middleware) where plugins transform, short-circuit, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
 - **serial** (awaited in listener order) for ordered checkpoints such as `agent/turn-stopping`.
 - **parallel** (awaited fan-out) where every listener must get an independent chance: the `session/flush` durability checkpoint.
 - **emit** (synchronous fire-and-forget) for notifications: inbox transitions, lifecycle, errors, and the contained immutable `tools/result` observation. Durable session events own turn and step boundaries.
 
-The event vocabulary lives in interface packages (dsh-agent declares the agent/* events); `@deepseek-ai/dsh-agent-loop` is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.
+The event vocabulary lives in contract packages (`dsh-agent` declares the `agent/*` events); `@deepseek-ai/dsh-agent-loop` is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.
 
 ## Alternatives considered
 
@@ -28,4 +28,4 @@ The event vocabulary lives in interface packages (dsh-agent declares the agent/*
 - Every MVP feature maps to a listener (the [feature → mechanism map](../../../../docs/cookbook/extension-cookbook.md#the-feature--mechanism-map) is the proof obligation, kept current).
 - HMR and disposal come free: listeners and registrations are Cordis effects.
 - Waterfall semantics (call `next()` or short-circuit) are non-obvious and must be taught — documented in AGENTS.md and covered by composition tests.
-- The loop must be defensive: plugin exceptions are contained at turn level, steering from any seam is never stranded (regression-tested).
+- The loop must be defensive: plugin exceptions are contained at turn level, steering from any extension point is never stranded (regression-tested).
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
index aa3db53d64..40edfa1ada 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -10,14 +10,14 @@ Status: implemented
 
 ## 决策
 
-纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展 seam 是带类型的事件，具有明确的分发模式：
+纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展点是带类型的事件，具有明确的分发模式：
 
 - **waterfall（瀑布式事件）**（around-middleware）：插件可变换、短路、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
 - **serial**（按监听器顺序依次 await）：用于 `agent/turn-stopping` 等有序检查点。
 - **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
 - **emit**（同步 fire-and-forget）：用于通知：inbox 转换、生命周期、错误，以及受错误隔离的 `tools/result` 观测；该观测接收不可变的最终结果。轮次与步骤边界由持久会话事件拥有。
 
-事件词汇定义在接口包中（dsh-agent 声明 agent/* 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
+事件词汇定义在约定包中（`dsh-agent` 声明 `agent/*` 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
 
 ## 曾考虑的替代方案
 
@@ -28,4 +28,4 @@ Status: implemented
 - 每个 MVP 功能都映射到一个监听器（[功能→机制映射](../../../../docs/cookbook/extension-cookbook.md#the-feature--mechanism-map)是证明义务，保持更新）。
 - HMR 与 dispose 无需额外工作：监听器和注册均为 Cordis effect。
 - waterfall 语义（调用 `next()` 或短路）不直观，需要教学——在 AGENTS.md 中记录，并由组合测试覆盖。
-- 循环必须具备防御性：插件异常在轮次级别被隔离，任何 seam 发出的 steering（中途引导）永远不会被搁置（有回归测试保障）。
+- 循环必须具备防御性：插件异常在轮次级别被隔离，任何扩展点发出的 steering（中途引导）永远不会被搁置（有回归测试保障）。
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index 4a8f0149e2..ccf15a5c1e 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.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 .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
-2026-06-13-capability-seams.md: 1bad79a9d6d46e56afba862521403ee7c921ba21
-2026-06-13-capability-seams.zh.md: a44913539eed800f82d3f270fef05be17f524a2c
+2026-06-13-capability-seams.md: ca5071cff1b26ba3b89537a73f40d7ecbde4b2bb
+2026-06-13-capability-seams.zh.md: 7790124b980e0525705c2db398802ea6a418685a
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
index 1bad79a9d6..ca5071cff1 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
@@ -1,4 +1,4 @@
-# Agent Note: Capability seams — interface / implementation / consumer split
+# Agent Note: Capability seams — Service Definition / Service provider / Consumer roles
 
 Status: implemented
 
@@ -12,25 +12,25 @@ This is distinct from "who provides vs. needs a capability at runtime", which Co
 
 ## Decision
 
-A swappable capability is **three packages**:
+A swappable capability has **three roles**:
 
-1. **Interface** — an abstract service + the vocabulary types, owning the `ctx.<key>` and depending only on its vocabulary dependencies (e.g. `dsh-bash`: `BashExecutor`, `BashRunResult`, `BashProcess`).
-2. **Implementation** — a concrete subclass loaded as a plugin (e.g. `dsh-bash-local`: subprocesses, process-group kills, spill-file truncation). Sandboxed/remote backends are sibling packages implementing the same interface.
-3. **Consumer** — what the model and plugins see (e.g. `dsh-tool-bash`: the `bash` schema, with background handles registered into the generic task runtime). Consumers `inject` the interface key and never import implementation types.
+1. **Service Definition** — the Cordis `Service` and vocabulary types owning `ctx.<key>` and depending only on the vocabulary the contract needs (e.g. `dsh-bash`: `BashExecutor`, `BashRunResult`, `BashProcess`). A definition may be an abstract class or a concrete registry service; it is never a TypeScript `interface`.
+2. **Service provider** — a plugin that supplies or registers an implementation (e.g. `dsh-bash-local`: subprocesses, process-group kills, spill-file truncation). Sandboxed and remote providers are sibling packages implementing or registering against the same Service Definition.
+3. **Consumer** — what the model and plugins program against (e.g. `dsh-tool-bash`: the `bash` schema, with background handles registered into the generic task runtime). Consumers inject the service key and never import provider-specific types.
 
-Implementation and consumer then evolve independently: a sandboxed executor replaces `dsh-bash-local` without touching a tool schema.
+Service providers and Consumers then evolve independently: a sandboxed executor replaces `dsh-bash-local` without touching a tool schema.
 
-The split is not mandatory when the parts are genuinely one concern: the LLM seam folds interface + consumer into `dsh-llm` (the consumer is the loop itself, not a swappable schema surface) with adapters as the implementation packages. Don't split preemptively — a capability with one conceivable implementation and one consumer stays one package until a second appears.
+Roles normally use separate packages when they evolve independently, but the split is not mandatory when the roles are genuinely one concern: the LLM seam folds Service Definition and Consumer into `dsh-llm` (the Consumer is the loop itself, not a swappable schema surface) with adapters as Service provider packages. Don't split preemptively — a capability with one conceivable provider and one Consumer stays one package until a second appears.
 
 ## Terminology: "seam" names the trio, not the interface
 
-A **seam** is the whole capability — the three roles together: a **Service Definition** (the Cordis `Service` that owns `ctx.<key>` and the vocabulary; an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`), one or more **Service providers** (implementations that register a backend), and a **Consumer** (the model- or plugin-facing surface). `packages/bash` is the canonical example — `dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`. The interface package alone is the *Service Definition*, one member — not the seam. The Service Definition is never a TypeScript `interface`; where prose must name it, use the class name or `abstract class`, never `interface`. Reserving "seam" strictly for the trio and realigning the many existing "the X seam" usages is deferred to a follow-up; the [glossary](../../../../docs/glossary.md#capability-seam) is the canonical entry.
+A **seam** is the whole capability — the three roles together: a **Service Definition** (the Cordis `Service` that owns `ctx.<key>` and the vocabulary), one or more **Service providers**, and one or more **Consumers**. `packages/bash` is the canonical example — `dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`. A package may own multiple roles, but one role alone is not the seam. The term "seam" is reserved for this complete capability; name a constituent by its role, class, service, contract, or extension point. The [glossary](../../../../docs/glossary.md#capability-seam) is the canonical entry.
 
 ## Alternatives considered
 
-- **One combined package** — rejected because it recouples the three rates of change the split exists to separate (the whole point).
-- **`@cordisjs/plugin-capability`** — a different axis entirely: it is a permission/capability-*security* service (named permissions with inheritance, tested against a session via `ctx.capability.test`), a candidate for the deferred permissions/sandbox work on the `tools/pre-execute` deny/ask seam, NOT a mechanism for swapping implementations. Confusing the two ("capability") is the trap this Agent Note names.
+- **Always combine the roles** — rejected because it recouples independently changing Service Definitions, providers, and Consumers.
+- **`@cordisjs/plugin-capability`** — a different axis entirely: it is a permission/capability-*security* service (named permissions with inheritance, tested against a session via `ctx.capability.test`), a candidate for the deferred permissions/sandbox work on the `tools/pre-execute` deny/ask gate, NOT a mechanism for swapping implementations. Confusing the two ("capability") is the trap this Agent Note names.
 
 ## Consequences
 
-More packages and more boilerplate per capability (a `package.json`/`tsconfig`/README trio, the inject wiring). Bought: implementations and consumers ship and version independently, and a new backend never risks the model-facing contract. The rule is documented in [AGENTS.md](../../../../AGENTS.md) § Conventions ("Capability seams are three packages") and [architecture.md](../../../../docs/architecture.md) § "Capability seams"; the bash trio is the reference template. When to fold vs. split is a judgment call the architecture doc spells out — this Agent Note records *why* the default is to split.
+Separating roles adds packages and boilerplate (`package.json`, `tsconfig`, README, and injection wiring). In return, Service providers and Consumers ship and version independently, and a new backend never risks the model-facing contract. [AGENTS.md](../../../../AGENTS.md) and [architecture.md](../../../../docs/architecture.md) carry the rule; the bash trio is the reference template. This Agent Note records why independently changing roles normally split while genuinely shared concerns may remain folded.
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
index a44913539e..7790124b98 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 能力 seam——接口／实现／消费方三分
+# Agent Note: 能力 seam——Service Definition / Service provider / Consumer 角色
 
 Status: implemented
 
@@ -12,25 +12,25 @@ harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化
 
 ## 决策
 
-一项可替换的能力由**三个包**构成：
+一项可替换的能力包含**三个角色**：
 
-1. **接口**——一个抽象服务加词汇类型，拥有 `ctx.<key>`，仅依赖其词汇依赖（例如 `dsh-bash`：`BashExecutor`、`BashRunResult`、`BashProcess`）。
-2. **实现**——一个具体子类，以插件形式加载（例如 `dsh-bash-local`：子进程、进程组 kill、spill 文件截断）。沙箱化／远程后端是实现同一接口的兄弟包。
-3. **消费方**——模型和插件看到的内容（例如 `dsh-tool-bash`：`bash` schema，后台句柄注册到通用任务运行时）。消费方 `inject` 接口键，从不导入实现类型。
+1. **Service Definition**——拥有 `ctx.<key>` 的 Cordis `Service` 和词汇类型，仅依赖约定所需的词汇（例如 `dsh-bash`：`BashExecutor`、`BashRunResult`、`BashProcess`）。Service Definition 可以是抽象类，也可以是具体的注册表服务；绝不是 TypeScript `interface`。
+2. **Service provider**——提供或注册实现的插件（例如 `dsh-bash-local`：子进程、进程组 kill、spill 文件截断）。沙箱化和远程 Service provider 是依据同一 Service Definition 实现或注册的兄弟包。
+3. **Consumer**——模型和插件编程所面向的内容（例如 `dsh-tool-bash`：`bash` schema，后台句柄注册到通用任务运行时）。Consumer 注入服务键，从不导入 Service provider 特有的类型。
 
-实现与消费方由此独立演进：沙箱化执行器替换 `dsh-bash-local` 时无需触碰任何工具 schema。
+Service provider 与 Consumer 由此独立演进：沙箱化执行器替换 `dsh-bash-local` 时无需触碰任何工具 schema。
 
-当各部分确实属于同一个关注点时，三分并非强制：LLM（大语言模型） seam 将接口 + 消费方合并为 `dsh-llm`（消费方是 agent loop（智能体循环）本身，而非可替换的 schema 接口），适配器作为实现包。不要预防性地拆分——如果一项能力只有一种可设想的实现和一个消费方，就保持为一个包，直到出现第二种实现或第二个消费方。
+当角色独立演进时，通常使用不同的包；但当各角色确实属于同一个关注点时，并非必须拆分：LLM（大语言模型） seam 将 Service Definition 和 Consumer 合并为 `dsh-llm`（Consumer 是 agent loop（智能体循环）本身，而非可替换的 schema 接口），适配器作为 Service provider 包。不要预防性地拆分——如果一项能力只有一种可设想的 Service provider 和一个 Consumer，就保持为一个包，直到出现第二个。
 
 ## 术语：seam 指三者组合，而非接口
 
-一个 **seam** 是完整的能力——三个角色合在一起：**Service Definition**（拥有 `ctx.<key>` 和词汇的 Cordis `Service`；可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表）、一个或多个 **Service provider**（注册后端的实现）和 **Consumer**（面向模型或插件的表面）。`packages/bash` 是规范范例——`dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`。接口包本身只是 *Service Definition*，是其中一个成员——不是 seam。Service Definition 从不是 TypeScript `interface`；在正文必须命名它时，使用类名或 `abstract class`，永远不要用 `interface`。严格把「seam」保留给三者组合，并校准现有大量「X seam」用法的工作推迟到后续；[术语表](../../../../docs/glossary.md#capability-seam)是规范条目。
+一个 **seam** 是完整的能力——三个角色合在一起：**Service Definition**（拥有 `ctx.<key>` 和词汇的 Cordis `Service`）、一个或多个 **Service provider**，以及一个或多个 **Consumer**。`packages/bash` 是规范范例——`dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`。一个包可以承担多个角色，但单个角色本身不是 seam。「seam」一词严格保留给这种完整能力；命名其中一个组成部分时，应使用其角色、类、服务、约定或扩展点。[术语表](../../../../docs/glossary.md#capability-seam)是规范条目。
 
 ## 曾考虑的替代方案
 
-- **单一合并包**：否决。因为它重新耦合了三分设计本要分离的三种变化速率（这正是拆分的意义所在）。
-- **`@cordisjs/plugin-capability`**：这是完全不同的维度。它是一个权限／能力*安全*服务（具名权限加继承，通过 `ctx.capability.test` 对会话进行检测），是延后的权限/沙箱工作（`tools/pre-execute` deny/ask seam）的候选方案，不是替换实现的机制。混淆这两个「能力」概念正是本 Agent Note 所指出的陷阱。
+- **始终合并各角色**：否决。因为它会重新耦合独立变化的 Service Definition、Service provider 和 Consumer。
+- **`@cordisjs/plugin-capability`**：这是完全不同的维度。它是一个权限／能力*安全*服务（具名权限加继承，通过 `ctx.capability.test` 对会话进行检测），是延后的权限/沙箱工作（`tools/pre-execute` deny/ask 门）的候选方案，不是替换实现的机制。混淆这两个「能力」概念正是本 Agent Note 所指出的陷阱。
 
 ## 后果
 
-每项能力需要更多包和更多样板代码（一组 `package.json`/`tsconfig`/README，加上 inject 接线）。换来的是：实现与消费方独立发布和版本管理，新后端永远不会波及面向模型的约定。该规则记录在 [AGENTS.md](../../../../AGENTS.md) § Conventions（「Capability seams are three packages」）和 [architecture.md](../../../../docs/architecture.md) §「Capability seams」中；bash 三件套是参考模板。何时合并、何时拆分是一个判断问题，架构文档对此有详细说明——本 Agent Note 记录的是*为什么*默认选择拆分。
+分离角色会增加包和样板代码（`package.json`、`tsconfig`、README 和注入接线）。换来的是：Service provider 与 Consumer 独立发布和版本管理，新后端永远不会波及面向模型的约定。[AGENTS.md](../../../../AGENTS.md) 和 [architecture.md](../../../../docs/architecture.md) 载有这项规则；bash 三件套是参考模板。本 Agent Note 记录为什么独立变化的角色通常需要拆分，而确实共享的关注点可以保持合并。
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index bead51ff09..f2b2982bc1 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.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 .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
-2026-06-14-session-persistence.md: 00e129e57c7144fd62eec26f5854ee21dec4e964
-2026-06-14-session-persistence.zh.md: df03dce6bd978f10deb64b8d75ae0685dabab7cd
+2026-06-14-session-persistence.md: 46fd3755a3c35bd342119fb59b560775a679f740
+2026-06-14-session-persistence.zh.md: f29b192ec9814de2a183599bcfc0a4a0c301b31e
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
index 00e129e57c..46fd3755a3 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
@@ -12,7 +12,7 @@ The [event-sourced model](2026-06-11-event-sourced-sessions.md) makes the append
 
 ## Decision
 
-Persistence is an abstract **capability seam** ([capability seams](2026-06-13-capability-seams.md), the `dsh-bash` template), not loop or core logic:
+Persistence is a **capability seam** with an abstract Service Definition ([capability seams](2026-06-13-capability-seams.md), the `dsh-bash` template), not loop or core logic:
 
 1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`. Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type.
 2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only logical JSONL log per session: a `SessionHeader` line followed by storage records that losslessly represent the contiguous `SessionEvent` stream. Eligible `assistant/chunk` delta runs use packed rows by default; [checksummed Zstandard frames](2026-07-19-zstandard-jsonl-session-logs.md) are the default physical encoding, with raw lines configurable.
@@ -22,7 +22,7 @@ Key choices recorded here because they are durable, contested, and surprising:
 - **The canonical durable log persists every `SessionEvent` losslessly, including `assistant/chunk`.** JSONL storage may encode a consecutive delta run as one packed row, but logical readers reconstruct the exact event boundaries, sequence numbers, and timestamps. `deriveMessages()` skips chunks, and a chunk-filtered rollout (Codex's `policy.rs`) is tempting — but `seq = log.length` and validation of `events[i].seq === i` require a *contiguous* logical log; filtering chunks out would leave holes and break both the contract and resume. A chunk-filtered projection is possible later as a derived view with its own renumbering, but it is NOT the canonical log.
 - **Append-only; a crashed turn is closed, never truncated.** Flushed events are never rewritten. The [semantic checkpoint policy](../bug-fix/2026-07-21-semantic-session-checkpoints.md) drains the request before model dispatch, a recorded top-level call before tool dispatch, and the complete response/result batch after a step; the loop drains the final turn boundary. Because one interrupted turn may contain substantial valid work, cold inspection preserves its contiguous, parseable events and adds risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }` to the in-memory logical view. `prepare` or `load` commits those closers before returning a recoverable view; the synthetic results keep resumed provider transcripts valid. Only an incomplete final record is discarded during committed repair; a parse error or sequence gap at or before the last real `turn/end` is corruption and makes the session unloadable.
 - **File backend canonical, DB backend a proven drop-in.** `SessionEvent` maps 1:1 onto a row `(session_id, seq, type, time, data)` — `append` is INSERT (in a transaction asserting the contiguous-seq contract), and reads use SELECT … ORDER BY seq. `dsh-session-persistence-sqlite` is exactly this: a `SessionPersistence` subclass with no interface change (opencode runs this exact shape on SQLite/WAL), and it passes the same `runPersistenceContract` suite as the JSONL backend — so the contract holds both backends to identical semantics (lazy materialization, logical interrupted-turn closure, single committed repair, contiguous-seq), expressed once over file bytes and once over rows. Its database carries a dedicated application id and monotonic schema version. A pristine file creates all tables and stamps both header values in one transaction; an unversioned file with any user-defined schema object or application identity, a foreign current-version identity, and every non-current version reject before journal-mode mutation.
-- **Metadata is out-of-log.** Format version, cwd, and lineage are storage concerns, not replayable conversation state, so they live in a `SessionHeader` owned by `dsh-session` and attached to a `Session` via a new readonly `session.header` — never in `SessionEventMap`, never reaching `deriveMessages()`. `createdAt` is non-negative safe-integer Unix epoch milliseconds: live creation and persistence registration reject fractional values, JSONL validates the decoded header, and SQLite stores it in a strict `INTEGER` column. The alternative (a merge-extensible `session/meta` event as log line 0) was rejected: an in-log event would ride along with a seeded/forked session for free, but metadata is not replayable state, so the explicit out-of-log header seam is the cleaner cost. (The header was originally split into an immutable `SessionHeader` plus a mutable `SessionSummary` whose union was `SessionMeta`; the mutable summary was later removed as dead state — see [Drop the mutable session summary](../simplification/2026-06-19-drop-mutable-session-summary.md).)
+- **Metadata is out-of-log.** Format version, cwd, and lineage are storage concerns, not replayable conversation state, so they live in a `SessionHeader` owned by `dsh-session` and attached to a `Session` via a new readonly `session.header` — never in `SessionEventMap`, never reaching `deriveMessages()`. `createdAt` is non-negative safe-integer Unix epoch milliseconds: live creation and persistence registration reject fractional values, JSONL validates the decoded header, and SQLite stores it in a strict `INTEGER` column. The alternative (a merge-extensible `session/meta` event as log line 0) was rejected: an in-log event would ride along with a seeded/forked session for free, but metadata is not replayable state, so the explicit out-of-log header boundary is the cleaner cost. (The header was originally split into an immutable `SessionHeader` plus a mutable `SessionSummary` whose union was `SessionMeta`; the mutable summary was later removed as dead state — see [Drop the mutable session summary](../simplification/2026-06-19-drop-mutable-session-summary.md).)
 - **`ctx.agents.create()` and `ctx.agents.resume()` are async factories; resume additionally crosses the persistence boundary.** `ctx.agents.resume({ resumeSessionId })` obtains the exact unpublished Session through `ctx.sessionPersistence.prepare()`, publishes it under the persisted id, and continues its projections. The [Session preparation decision](2026-08-05-session-preparation.md) owns reuse between history inspection and resume. The agent-loop does NOT hard-inject `sessionPersistence` (that would pend non-persistent demos forever); `resume` rejects with a clear error when it is absent.
 
 ## Alternatives considered
@@ -33,4 +33,4 @@ Format versioning: the header carries a `version`; cold reads reject any non-cur
 
 ## Consequences
 
-Two new packages and the metadata seam in `dsh-session` (`session.header`, the `create(id?, options?)` signature). Bought: durable resume/fork, a read/replay path, crash tolerance, and host-side session access over the existing event-sourced log, with the backend swappable behind one interface. The reusable `runPersistenceContract` suite holds every backend to the same append-only, contiguous-seq, lazy-materialization, logical-recovery, integer-metadata, and serializability semantics. Persisting the full logical log also settles event fidelity: every `assistant/chunk` survives exactly even when JSONL packs several into one storage row. SQLite initialization either commits its complete owned schema and header identity or leaves no partial schema to strand on the next open.
+Two new packages and the metadata contract in `dsh-session` (`session.header`, the `create(id?, options?)` signature). Bought: durable resume/fork, a read/replay path, crash tolerance, and host-side session access over the existing event-sourced log, with the backend swappable behind one interface. The reusable `runPersistenceContract` suite holds every backend to the same append-only, contiguous-seq, lazy-materialization, logical-recovery, integer-metadata, and serializability semantics. Persisting the full logical log also settles event fidelity: every `assistant/chunk` survives exactly even when JSONL packs several into one storage row. SQLite initialization either commits its complete owned schema and header identity or leaves no partial schema to strand on the next open.
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index df03dce6bd..f29b192ec9 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-持久化是一个抽象的**能力 seam**（[能力 seam](2026-06-13-capability-seams.md)，`dsh-bash` 模板），而非循环或核心逻辑：
+持久化是一个具有抽象 Service Definition 的**能力 seam**（[能力 seam](2026-06-13-capability-seams.md)，`dsh-bash` 模板），而非循环或核心逻辑：
 
 1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`。其持久化单元就是现有的 `SessionEvent`（`{ type, seq, time, data }`），原样复用，无转换类型。
 2. **实现**（`dsh-session-persistence-jsonl`）：每个会话一个仅追加的逻辑 JSONL 日志：先是一行 `SessionHeader`，随后是无损表示连续 `SessionEvent` 流的存储记录。符合条件的 `assistant/chunk` 增量连续段默认使用打包行；[带校验和的 Zstandard 帧](2026-07-19-zstandard-jsonl-session-logs.md)是默认物理编码，也可通过配置使用原始行。
@@ -20,10 +20,10 @@ Status: implemented
 以下关键选择记录于此，因为它们长期有效、存在争议且出人意料：
 
 - **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
-- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些收尾事件；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
-- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 约定成立的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该约定以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
-- **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header，SQLite 则将其存入严格的 `INTEGER` 列。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header seam 是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.md)。）
-- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得原本那个尚未发布的会话，以持久化 id 发布该会话，并延续其投影。[会话准备决策](2026-08-05-session-preparation.md)负责历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
+- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些 closer；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
+- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 约定的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该约定以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
+- **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header，SQLite 则将其存入严格的 `INTEGER` 列。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header 边界是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.md)。）
+- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得精确的未发布 Session，以持久化 id 发布它，并继续其投影。[Session 准备阶段决策](2026-08-05-session-preparation.md)定义历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
 
 ## 曾考虑的替代方案
 
@@ -33,4 +33,4 @@ Status: implemented
 
 ## 后果
 
-新增两个包，以及 `dsh-session` 中的元数据 seam（`session.header`，`create(id?, options?)` 签名）。收益：持久恢复/fork、读取/回放路径、崩溃容忍，以及基于现有事件溯源日志的宿主侧会话访问，后端可在同一接口下替换。可复用的 `runPersistenceContract` 测试套件以相同的仅追加、连续 seq、惰性物化、逻辑恢复、整数元数据与可序列化语义约束每个后端。持久化完整的逻辑日志还确定了事件保真度：即使 JSONL 将多个 `assistant/chunk` 打包到一条存储行中，每个事件也会精确保留。SQLite 初始化要么提交完整的自有 schema 与 header 标识，要么不留下任何会使下次打开受阻的部分 schema。
+新增两个包，以及 `dsh-session` 中的元数据约定（`session.header`，`create(id?, options?)` 签名）。收益：持久恢复/fork、读取/回放路径、崩溃容忍，以及基于现有事件溯源日志的宿主侧会话访问，后端可在同一接口下替换。可复用的 `runPersistenceContract` 测试套件以相同的仅追加、连续 seq、惰性物化、逻辑恢复、整数元数据与可序列化语义约束每个后端。持久化完整的逻辑日志还确定了事件保真度：即使 JSONL 将多个 `assistant/chunk` 打包到一条存储行中，每个事件也会精确保留。SQLite 初始化要么提交完整的自有 schema 与 header 标识，要么不留下任何会使下次打开受阻的部分 schema。
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index 4511cefb31..159483fb73 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 7436d2a9402c76f17c7d6571eb489a86e550ebfb
-2026-06-17-filesystem-capability-seam.zh.md: a96d513d7f4fa793ebb3427e3f7b290862d0d5e9
+2026-06-17-filesystem-capability-seam.md: 35fe5148ca44f733aa0a354e215cd1d77eb8180e
+2026-06-17-filesystem-capability-seam.zh.md: 998b5ead48dcaf168ad48c8ad7a403a7e3b3e955
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 7436d2a940..35fe5148ca 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -26,9 +26,9 @@ Filesystem access is a first-class capability seam following [the capability-sea
 2. `@deepseek-ai/dsh-fs-local` (`packages/fs/fs-local`) provides the first implementation, backed by the local filesystem.
 3. `@deepseek-ai/dsh-tool-fs` (`packages/fs/tool-fs`) provides the model-facing `read`, `write`, and `edit` tools over `ctx.fs`, and is the executor that dispatches the `fs/*` events.
 
-The consumer package depends only on the interface package, never on `dsh-fs-local`. A deployment that wants a different backend loads a different provider for `ctx.fs` without changing the tool schemas or model-facing prompt guidance.
+The Consumer package depends only on the Service Definition package, never on `dsh-fs-local`. A deployment that wants a different backend loads a different provider for `ctx.fs` without changing the tool schemas or model-facing prompt guidance.
 
-The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This Agent Note established the three-package seam; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md). This document is updated to describe that landed four-package shape.
+The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This Agent Note established the three-package boundary; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md). This document is updated to describe that landed four-package shape.
 
 The first backend is deliberately local-only: `dsh-fs-local` implements `ctx.fs` against the host filesystem. Future sibling backends can provide sandboxed, remote, virtual, or project-scoped filesystems behind the same interface.
 
@@ -53,7 +53,7 @@ The filesystem seam uses the same dependency direction as the bash trio:
 
 `@deepseek-ai/dsh-tool-fs` depends on `@deepseek-ai/dsh-fs`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-system-prompt`, and `cordis`. It registers model-facing tools and prompt sections. It must not import `node:fs`, `node:path`, or `@deepseek-ai/dsh-fs-local`; filesystem execution always goes through `ctx.fs`. If the implementation needs concrete agent or session helper types, those dependencies belong in `tool-fs`; they must not leak back into `dsh-fs`.
 
-The root `tool-fs` plugin registers the full filesystem tool suite (`read`, `write`, and `edit`) by composing the per-tool registration helpers. It injects `fs` and never imports an implementation package.
+The root `tool-fs` plugin registers the full filesystem tool suite (`read`, `write`, and `edit`) by composing the per-tool registration helpers. It injects `fs` and never imports a Service provider package.
 
 ## `ctx.fs` contract
 
@@ -68,7 +68,7 @@ The interface covers these semantic operations:
 - Create or replace a UTF-8 text file.
 - Edit an existing UTF-8 text file by literal replacement.
 
-The provider seam also carries the freshness hooks that policy builds on — but the observed-state store and owner derivation live in the `dsh-fs-policy` plugin, not on `ctx.fs`:
+The provider contract also carries the freshness hooks that policy builds on — but the observed-state store and owner derivation live in the `dsh-fs-policy` plugin, not on `ctx.fs`:
 
 - The backend mints an opaque `version` token per target (in `stat` and in every read/mutation outcome).
 - `writeText`/`editText` take an OPTIONAL version expectation: omit it for an unconditional bare-provider mutation, or supply it to guard the mutation inside the backend's atomic critical section.
@@ -127,7 +127,7 @@ The root plugin registers the full suite by composing the per-tool registration
 
 ## Testing
 
-Tests follow the package boundary, not only the user-visible tools: the service seam in `dsh-fs`; real filesystem behavior through the `ctx.fs` interface in `dsh-fs-local` (resolution, symlinks, streaming, binary/UTF-8 rejection, unconditional and version-guarded writes, literal-edit semantics, line-ending preservation, structured `FsError` codes); the consumer surface in `dsh-tool-fs` against the real local provider (mock only the model/clock, never the collaborator); and integration through `ctx.tools.execute()` with and without `dsh-fs-policy`, world-verified by reading files back from disk rather than trusting either the canonical value or rendered content. The observed-state/owner-derivation policy is tested in `dsh-fs-policy`, not here.
+Tests follow the package boundary, not only the user-visible tools: the service contract in `dsh-fs`; real filesystem behavior through the `ctx.fs` interface in `dsh-fs-local` (resolution, symlinks, streaming, binary/UTF-8 rejection, unconditional and version-guarded writes, literal-edit semantics, line-ending preservation, structured `FsError` codes); the consumer surface in `dsh-tool-fs` against the real local provider (mock only the model/clock, never the collaborator); and integration through `ctx.tools.execute()` with and without `dsh-fs-policy`, world-verified by reading files back from disk rather than trusting either the canonical value or rendered content. The observed-state/owner-derivation policy is tested in `dsh-fs-policy`, not here.
 
 The defensive-pattern classes this repo has been bitten by are pinned directly:
 
@@ -139,7 +139,7 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 ## Alternatives considered
 
 - **Model-facing tools directly over `node:fs`** — the tool package would own execution policy, path resolution, atomic writes, text decoding, and edit semantics at once, coupling the three independently-changing concerns the Problem names and churning schemas on any backend swap.
-- **One combined `dsh-fs-tools` package** — the pre-seam shape; rejected for the same interface/implementation/consumer split as bash, and the combined name never became public surface.
+- **One combined `dsh-fs-tools` package** — the pre-seam shape; rejected for the same Service Definition / Service provider / Consumer split as bash, and the combined name never became public surface.
 - **Observed-state on `ctx.fs`** — the shape this Agent Note first landed; superseded by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) and [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md): a sandboxed/remote backend must not inherit model-facing observation policy, so the provider keeps only the version token and the optional version-guarded mutation.
 
 ## Consequences
@@ -152,7 +152,7 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 
 **Edit semantics are race-prone by nature.** Literal edit is a read-modify-write operation; the guard is the backend's atomic mutation critical section plus the optional version expectation, so concurrent edits settle deterministically — one wins, the other gets `FS_STALE_VERSION`.
 
-**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This Agent Note first placed it inside the filesystem seam; the split-fs-seam Agent Note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider seam keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
+**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This Agent Note first placed it inside the filesystem seam; the split-fs-seam Agent Note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider contract keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
 
 **The `resolve`-then-operate shape costs an extra round-trip per call.** Each tool may resolve a path to an `FsTarget` and then issue the read/write/edit as a separate `ctx.fs` call. For the local backend this is negligible (resolution is in-memory path normalization), but a remote/sandboxed backend may turn each step into its own request, so a single `read` can become two network round-trips. Backends where the round-trip matters can cache or fold resolution internally while preserving the observable contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index a96d513d7f..998b5ead48 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -26,9 +26,9 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 2. `@deepseek-ai/dsh-fs-local`（`packages/fs/fs-local`）提供第一个实现，以本地文件系统为后端。
 3. `@deepseek-ai/dsh-tool-fs`（`packages/fs/tool-fs`）通过 `ctx.fs` 提供面向模型的 `read`、`write` 和 `edit` 工具，是分发 `fs/*` 事件的执行器。
 
-消费方包仅依赖接口包，从不依赖 `dsh-fs-local`。需要不同后端的部署只需为 `ctx.fs` 加载不同的提供方，无需改动工具 schema 或面向模型的提示词引导。
+Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需要不同后端的部署只需为 `ctx.fs` 加载不同的提供方，无需改动工具 schema 或面向模型的提示词引导。
 
-读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本 Agent Note 确立了由三个包构成的 seam；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。本文已更新为描述最终落地的四包形态。
+读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本 Agent Note 确立了由三个包构成的边界；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。本文已更新为描述最终落地的四包形态。
 
 第一个后端有意仅限本地：`dsh-fs-local` 基于宿主文件系统实现 `ctx.fs`。未来的兄弟后端可在同一接口之后提供沙箱、远程、虚拟或项目作用域的文件系统。
 
@@ -53,7 +53,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 `@deepseek-ai/dsh-tool-fs` 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 `cordis`。它注册面向模型的工具和提示词段落。它禁止导入 `node:fs`、`node:path` 或 `@deepseek-ai/dsh-fs-local`；文件系统执行始终通过 `ctx.fs`。如果实现需要具体的 agent 或会话辅助类型，这些依赖属于 `tool-fs`；它们禁止回漏到 `dsh-fs` 中。
 
-根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
+根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入 Service provider 包。
 
 ## `ctx.fs` 约定
 
@@ -68,7 +68,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 - 创建或替换一个 UTF-8 文本文件。
 - 通过字面替换编辑一个已有的 UTF-8 文本文件。
 
-提供方 seam 还携带策略所依赖的新鲜度钩子——但观测状态存储和 owner 推导位于 `dsh-fs-policy` 插件中，而非 `ctx.fs` 上：
+提供方约定还携带策略所依赖的新鲜度钩子——但观测状态存储和 owner 推导位于 `dsh-fs-policy` 插件中，而非 `ctx.fs` 上：
 
 - 后端为每个目标铸造一个不透明的 `version` 令牌（在 `stat` 以及每次读取/变更结果中）。
 - `writeText`/`editText` 接受一个可选的版本期望：省略它表示无条件的裸提供方变更；提供它则在后端的原子临界区内守护变更。
@@ -127,7 +127,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 ## 测试
 
-测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
+测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务约定；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
 
 本仓库曾踩过的防御性模式类别被直接固定：
 
@@ -139,7 +139,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 ## 曾考虑的替代方案
 
 - **面向模型的工具直接基于 `node:fs`**：工具包将同时承担执行策略、路径解析、原子写入、文本解码和编辑语义，耦合问题部分所列的三个独立变化的关注点，且任何后端替换都会搅动 schema。
-- **单一合并包 `dsh-fs-tools`**：seam 之前的形态；以与 bash 相同的接口/实现/消费方拆分理由否决，且合并名称从未成为公开接口。
+- **单一合并包 `dsh-fs-tools`**：seam 之前的形态；以与 bash 相同的 Service Definition / Service provider / Consumer 拆分理由否决，且合并名称从未成为公开接口。
 - **观测状态放在 `ctx.fs` 上**：本 Agent Note 最初落地的形态；被 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 和 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 取代：沙箱/远程后端不应继承面向模型的观测策略，因此提供方只保留版本令牌和可选的版本守护变更。
 
 ## 后果
@@ -152,7 +152,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 **编辑语义天然易受竞争影响。** 字面编辑是读-改-写操作；守护手段是后端的原子变更临界区加上可选的版本期望，因此并发编辑确定性地收敛——一个赢，另一个得到 `FS_STALE_VERSION`。
 
-**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方 seam 只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
+**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方约定只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
 
 **`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测约定不变。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
similarity index 64%
rename from .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
rename to .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
index 70c9f791f4..4ea64d5530 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
@@ -1,6 +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 .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
-2026-06-18-agent-lifecycle-and-ownership-seams.md: 93247a6da7446a5a67db33423d2b766ce4cf3308
-2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: e17650c7789764dfb4240132f5903795e6f86381
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
+2026-06-18-agent-lifecycle-and-ownership-contracts.md: ad334d30afcaf1864a1ea3dd42f3c5b7d157603b
+2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md: b9240969c9e952c1b38cbd4c088853005e156067
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
similarity index 72%
rename from .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
rename to .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
index 93247a6da7..ad334d30af 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
@@ -1,16 +1,16 @@
-# Agent Note: Agent lifecycle and ownership seams
+# Agent Note: Agent lifecycle and ownership contracts
 
 Status: implemented
 
-English | [中文](2026-06-18-agent-lifecycle-and-ownership-seams.zh.md)
+English | [中文](2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md)
 
 ## Problem
 
-Several ACP and tool-bash limitations were symptoms of the same missing seam: plugins could create or resume agents through `ctx.agents`, but they could not own and dispose one agent independently, and long-running bash tasks carried no stable owner in the executor itself. ACP aborted and awaited agents on disconnect but could not unregister just that session's agent; `session/cancel` could not cancel queued-but-not-yet-started work; and `tool-bash` kept task ownership in a plugin-local `Map`, so an HMR reload could make an old task look unowned.
+Several ACP and tool-bash limitations were symptoms of the same missing ownership contract: plugins could create or resume agents through `ctx.agents`, but they could not own and dispose one agent independently, and long-running bash tasks carried no stable owner in the executor itself. ACP aborted and awaited agents on disconnect but could not unregister just that session's agent; `session/cancel` could not cancel queued-but-not-yet-started work; and `tool-bash` kept task ownership in a plugin-local `Map`, so an HMR reload could make an old task look unowned.
 
 ## Decision
 
-Three seams: the queue-aware cancel, the `AgentHandle` disposer, and the bash owner token.
+Three contract changes: the queue-aware cancel, the `AgentHandle` disposer, and the bash owner token.
 
 ### 1. Queue-aware `Agent.cancel(cause?)`
 
@@ -22,9 +22,9 @@ A new `cancel()` verb on the `Agent` interface — the single public stop primit
 
 **Teardown ORDER is load-bearing for durability**, and the implementation folds the session lifecycle into the agent's SINGLE composite cordis effect (`SessionStore.prepare`/`enter`/`announce`, replacing a sibling-effect split). A fiber unload disposes sibling effects concurrently (`Promise.all`), which would race removing the session store's append publication hooks against the loop's closing `session/flush` and drop the closing `turn/end`; inside one effect the disposers run as an ordered LIFO chain (loop stopped + `await agent.done` BEFORE the session detaches), so the loop's final flush is captured on BOTH the handle's `dispose()` and a fiber unload. The contained `agent/disposed` and `session/disposed` notifications cannot reject the chain or skip later teardown.
 
-### 3. Bash owner token in the seam
+### 3. Bash owner token in the Service Definition
 
-Background-task ownership moved from a `tool-bash` plugin-local `Map<string, Agent>` into the executor. `BashExecRequest` gains an optional `owner?: string`; the resolved `BashExecSpec` carries it as required-but-nullable `owner: string | undefined` (a forgotten owner is a visible `undefined`, never a silently-absent property). The executor stores the token on its task and exposes it via a new `BashExecutor.ownerOf(id): string | undefined` seam (NOT on the public `BashTask` — one read path, no redundant API). `tool-bash` deletes its `Map` entirely: it stamps `exec.agent?.id` (the shared registry/session id) as the owner at `start`, and `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token with `!== undefined` semantics (an empty-string token is still a real owner). The completion notice finds the live agent by scanning `ctx.get('agents')?.list()` for `agent.id === ownerToken` (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, where the `ctx.agents` proxy would throw). Because ownership now lives on the task in the executor (disposed with the `dsh-bash` fiber), it SURVIVES a `tool-bash` HMR reload — closing the old `XXX(tool-bash-owner-hmr)` gap. (The `onTaskDone` listener is still effect-scoped to `tool-bash`'s `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
+Background-task ownership moved from a `tool-bash` plugin-local `Map<string, Agent>` into the executor. `BashExecRequest` gains an optional `owner?: string`; the resolved `BashExecSpec` carries it as required-but-nullable `owner: string | undefined` (a forgotten owner is a visible `undefined`, never a silently-absent property). The executor stores the token on its task and exposes it via a new `BashExecutor.ownerOf(id): string | undefined` method (NOT on the public `BashTask` — one read path, no redundant API). `tool-bash` deletes its `Map` entirely: it stamps `exec.agent?.id` (the shared registry/session id) as the owner at `start`, and `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token with `!== undefined` semantics (an empty-string token is still a real owner). The completion notice finds the live agent by scanning `ctx.get('agents')?.list()` for `agent.id === ownerToken` (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, where the `ctx.agents` proxy would throw). Because ownership now lives on the task in the executor (disposed with the `dsh-bash` fiber), it SURVIVES a `tool-bash` HMR reload — closing the old `XXX(tool-bash-owner-hmr)` gap. (The `onTaskDone` listener is still effect-scoped to `tool-bash`'s `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
 
 ## Verification
 
@@ -37,11 +37,11 @@ These invariants hold and are pinned by tests:
 
 ## Session owner tokens are unique among live agents
 
-The bash owner-token comparison relies on the shared `Agent.id`/`SessionId` being unique among live agents. Concurrent same-ID operations may both prepare privately, but publication enters the session and agent in order; `SessionStore.enter()` rejects a duplicate live session id, and every losing transaction rolls its private state back. A programmatic caller therefore cannot publish two live agents with one session token. The access *policy* (token comparison) stays in `tool-bash` (the consumer); the bash seam stores only an opaque `owner` string and never interprets it — the correct interface/implementation/consumer split.
+The bash owner-token comparison relies on the shared `Agent.id`/`SessionId` being unique among live agents. Concurrent same-ID operations may both prepare privately, but publication enters the session and agent in order; `SessionStore.enter()` rejects a duplicate live session id, and every losing transaction rolls its private state back. A programmatic caller therefore cannot publish two live agents with one session token. The access *policy* (token comparison) stays in `tool-bash` (the Consumer); the bash capability keeps `owner` opaque and never interprets it — the correct Service Definition / Service provider / Consumer split.
 
 ## Alternatives considered
 
-- **A public `BashTask.owner` field** instead of the `BashExecutor.ownerOf(id)` seam — rejected: one read path, no redundant API.
+- **A public `BashTask.owner` field** instead of the `BashExecutor.ownerOf(id)` Service Definition method — rejected: one read path, no redundant API.
 - **Sibling cordis effects for the agent's session lifecycle** — rejected: a fiber unload disposes sibling effects concurrently (`Promise.all`), racing removal of the store-owned append publication hooks against the loop's closing `session/flush`; the single composite effect's ordered LIFO chain is what captures the closing `turn/end` on both disposal paths.
 - **A separate step-only `abort()` beside `cancel()`** — shipped originally, then removed as unused; `cancel()` is the single public stop primitive ([the public-stop-surface Agent Note](../simplification/2026-06-20-public-agent-stop-surface.md)).
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
similarity index 71%
rename from .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
rename to .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
index e17650c778..b9240969c9 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
@@ -1,16 +1,16 @@
-# Agent Note: Agent 生命周期与所有权 seam
+# Agent Note: Agent 生命周期与所有权约定
 
 Status: implemented
 
-[English](2026-06-18-agent-lifecycle-and-ownership-seams.md) | 中文
+[English](2026-06-18-agent-lifecycle-and-ownership-contracts.md) | 中文
 
 ## 问题
 
-ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 seam 的症状：插件可以通过 `ctx.agents` 创建或恢复 agent（智能体），但无法独立拥有和 dispose（资源释放）单个 agent，而长时间运行的 bash 任务在执行器中也没有稳定的所有者。ACP 在断连时中止并等待 agent，却无法仅注销该会话的 agent；`session/cancel` 无法取消已入队但尚未开始的工作；`tool-bash` 将任务所有权保存在插件本地的 `Map` 中，因此一次 HMR（热模块替换）重载就可能让旧任务看起来无主。
+ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个所有权约定缺失的症状：插件可以通过 `ctx.agents` 创建或恢复 agent（智能体），但无法独立拥有和 dispose（资源释放）单个 agent，而长时间运行的 bash 任务在执行器中也没有稳定的所有者。ACP 在断连时中止并等待 agent，却无法仅注销该会话的 agent；`session/cancel` 无法取消已入队但尚未开始的工作；`tool-bash` 将任务所有权保存在插件本地的 `Map` 中，因此一次 HMR（热模块替换）重载就可能让旧任务看起来无主。
 
 ## 决策
 
-三个 seam：队列感知的取消、`AgentHandle` 释放器，以及 bash 所有者令牌。
+三项约定变更：队列感知的取消、`AgentHandle` 释放器，以及 bash 所有者令牌。
 
 ### 1. 队列感知的 `Agent.cancel(cause?)`
 
@@ -22,9 +22,9 @@ ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 se
 
 **拆除顺序对持久性至关重要**，实现将会话生命周期折叠进 agent 的单个复合 Cordis effect（`SessionStore.prepare`/`enter`/`announce`，取代兄弟 effect 拆分）。fiber 卸载会并发释放兄弟 effect（`Promise.all`），这会让会话存储的 append 发布钩子移除与循环关闭时的 `session/flush` 竞争，从而丢失关闭的 `turn/end`；在一个 effect 内，释放器作为有序的 LIFO 链运行（停止循环 + `await agent.done` 在会话分离之前），因此无论 handle 的 `dispose()` 还是 fiber 卸载，都会捕获循环的最终刷写。被隔离的 `agent/disposed` 和 `session/disposed` 通知无法拒绝该链或跳过后续拆除。
 
-### 3. Bash seam 中的所有者令牌
+### 3. Service Definition 中的 Bash 所有者令牌
 
-后台任务所有权从 `tool-bash` 插件本地的 `Map<string, Agent>` 移入执行器。`BashExecRequest` 新增可选的 `owner?: string`；解析后的 `BashExecSpec` 将其作为必需但可空的 `owner: string | undefined` 携带（被遗忘的 owner 是可见的 `undefined`，而非静默缺失的属性）。执行器把 token 存在任务上，并通过新的 `BashExecutor.ownerOf(id): string | undefined` seam 暴露它（不放在公开的 `BashTask` 上——只有一条读取路径，没有冗余 API）。`tool-bash` 完全删除其 `Map`：它在 `start` 时将 `exec.agent?.id`（共享的注册表/会话 id）盖章为 owner，`bash_output`/`bash_kill` 则以 `!== undefined` 语义把 `ctx.bash.ownerOf(id)` 与调用方 token 比较（空字符串 token 仍是真实 owner）。完成通知通过扫描 `ctx.get('agents')?.list()` 查找 `agent.id === ownerToken` 的存活 agent（经 `ctx.get` 读取——`onTaskDone` 运行在 bash fiber 这一外部 fiber 上，直接使用 `ctx.agents` proxy 会抛异常）。由于所有权现在保存在执行器的任务上（随 `dsh-bash` fiber dispose），它能跨越 `tool-bash` HMR 重载，关闭旧的 `XXX(tool-bash-owner-hmr)` 缺口。（`onTaskDone` 监听器仍受 `tool-bash` 的 `apply` effect 约束，因此落在重载间隙的完成仍会丢失一条通知——既有的重载间隙丢失——但所有权隔离本身已经不受 HMR 影响。）
+后台任务所有权从 `tool-bash` 插件本地的 `Map<string, Agent>` 移入执行器。`BashExecRequest` 新增可选的 `owner?: string`；解析后的 `BashExecSpec` 将其作为必需但可空的 `owner: string | undefined` 携带（被遗忘的 owner 是可见的 `undefined`，而非静默缺失的属性）。执行器把 token 存在任务上，并通过新的 `BashExecutor.ownerOf(id): string | undefined` 方法暴露它（不放在公开的 `BashTask` 上——只有一条读取路径，没有冗余 API）。`tool-bash` 完全删除其 `Map`：它在 `start` 时将 `exec.agent?.id`（共享的注册表/会话 id）盖章为 owner，`bash_output`/`bash_kill` 则以 `!== undefined` 语义把 `ctx.bash.ownerOf(id)` 与调用方 token 比较（空字符串 token 仍是真实 owner）。完成通知通过扫描 `ctx.get('agents')?.list()` 查找 `agent.id === ownerToken` 的存活 agent（经 `ctx.get` 读取——`onTaskDone` 运行在 bash fiber 这一外部 fiber 上，直接使用 `ctx.agents` proxy 会抛异常）。由于所有权现在保存在执行器的任务上（随 `dsh-bash` fiber dispose），它能跨越 `tool-bash` HMR 重载，关闭旧的 `XXX(tool-bash-owner-hmr)` 缺口。（`onTaskDone` 监听器仍受 `tool-bash` 的 `apply` effect 约束，因此落在重载间隙的完成仍会丢失一条通知——既有的重载间隙丢失——但所有权隔离本身已经不受 HMR 影响。）
 
 ## 验证
 
@@ -37,11 +37,11 @@ ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 se
 
 ## 会话所有者令牌在存活 agent 中唯一
 
-bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agent 中唯一。并发的同 ID 操作可以都私下准备，但发布时会依次登记会话和 agent；`SessionStore.enter()` 拒绝重复的存活会话 id，每个失败事务都回滚自己的私有状态。因此程序化调用方无法发布两个共享同一会话 token 的存活 agent。访问*策略*（token 比较）留在消费方 `tool-bash`；bash seam 只存储不透明的 `owner` 字符串且从不解释它——这是正确的接口/实现/消费方拆分。
+bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agent 中唯一。并发的同 ID 操作可以都私下准备，但发布时会依次登记会话和 agent；`SessionStore.enter()` 拒绝重复的存活会话 id，每个失败事务都回滚自己的私有状态。因此程序化调用方无法发布两个共享同一会话 token 的存活 agent。访问*策略*（token 比较）留在 Consumer `tool-bash`；bash 能力只存储不透明的 `owner` 字符串且从不解释它——这是正确的 Service Definition / Service provider / Consumer 拆分。
 
 ## 曾考虑的替代方案
 
-- **公开的 `BashTask.owner` 字段**而非 `BashExecutor.ownerOf(id)` seam：否决。一条读取路径即可，无需冗余 API。
+- **公开的 `BashTask.owner` 字段**而非 `BashExecutor.ownerOf(id)` Service Definition 方法：否决。一条读取路径即可，无需冗余 API。
 - **为 agent 的会话生命周期使用兄弟 Cordis effect**：否决。fiber 卸载时并发释放兄弟 effect（`Promise.all`），store 拥有的 append 发布钩子的移除与循环的关闭 `session/flush` 产生竞争；单一复合 effect 的有序 LIFO 链才能在两条释放路径上都捕获关闭的 `turn/end`。
 - **在 `cancel()` 之外另设一个仅中止步骤的 `abort()`**：最初发布过，后因无人使用而移除；`cancel()` 是唯一的公开停止原语（见[公开停止接口 Agent Note](../simplification/2026-06-20-public-agent-stop-surface.md)）。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 84edacb9dc..702a9035d5 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.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 .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
-2026-06-18-shared-persistence-write-coordinator.zh.md: 0a7fbf351171d305b3b6245832a0b35a283c7c1d
+2026-06-18-shared-persistence-write-coordinator.md: 1d373317664f605e5164e2eb6980b8fa7c6b4e05
+2026-06-18-shared-persistence-write-coordinator.zh.md: 607f1fe68d1404a56c84848c8561cf8749daab0b
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
index 12131ebf83..1d37331766 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-18-shared-persistence-write-coordinator.zh.md)
 
 ## Problem
 
-`dsh-session-persistence-jsonl` and `dsh-session-persistence-sqlite` intentionally prove the same `SessionPersistence` contract over different storage media, but their write-path orchestration was duplicated: per-session state, `session/created` adoption, backend-specific prefix reads, write-behind control, per-id operation serialization, HMR seeding, and dispose drains. The pure seed-prefix collision and serializability guards had already moved into the seam package; the remaining orchestration was still correctness-heavy and received the same fixes twice. Only the storage primitives (write bytes vs. INSERT rows) differed.
+`dsh-session-persistence-jsonl` and `dsh-session-persistence-sqlite` intentionally prove the same `SessionPersistence` contract over different storage media, but their write-path orchestration was duplicated: per-session state, `session/created` adoption, backend-specific prefix reads, write-behind control, per-id operation serialization, HMR seeding, and dispose drains. The pure seed-prefix collision and serializability guards had already moved into the Service Definition package; the remaining orchestration was still correctness-heavy and received the same fixes twice. Only the storage primitives (write bytes vs. INSERT rows) differed.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 0a7fbf3511..607f1fe68d 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 约定，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
+`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 约定，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 Service Definition 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
 
 ## 决策
 
 将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
 
-组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不修改状态的逻辑检查，以及通过 `load` 实现的默认准备回退。
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
 
 协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
@@ -44,4 +44,4 @@ Status: implemented
 
 ## 后果
 
-协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不修改状态的检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
+协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不可变检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
index 0af0c0038b..f906aa4336 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.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 .agents/notes/implemented/architecture/2026-06-20-branded-ids.md
-2026-06-20-branded-ids.md: 7c0b7ca89418e8312ec728223dac519f70edc3ed
-2026-06-20-branded-ids.zh.md: 039953754b184af97eb9b4ea3bbb1325d45eda25
+2026-06-20-branded-ids.md: 005706a12769a03e9c8ce66bf631ca0d75ade8b4
+2026-06-20-branded-ids.zh.md: b6b58a8b703d5637a6a5053543193bf9779489ac
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
index 7c0b7ca894..005706a127 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -12,15 +12,15 @@ The harness brands `CallId` (`packages/llm/llm/src/brand.ts`) and the shared age
 
 The bash **owner token** is the related sub-case: `BashExecRequest.owner?: string` and `BashExecSpec.owner: string | undefined` (`packages/bash/bash/src/types.ts`) are documented as a deliberately *opaque* isolation key, but in every live caller the value IS the owning agent's shared `Agent.id`/`SessionId` (`callerToken = (exec) => exec.agent?.id` in `packages/bash/tool-bash/src/index.ts`) wearing a different seam-local name. It is compared for access control (`owner !== callerToken(exec)`), so a mismatched-but-well-typed string here is a cross-session isolation bug the type system currently cannot catch. This is the shared id alias covered by the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md).
 
-**Gap 2 — brand erosion at the seams of the *already-branded* IDs.** Even `CallId` and `SessionId` decay back to bare `string` at exactly the places confusion is most likely: registry/store key types and public method params. Representative sites include the session store, the agent registry (both keyed by the shared `SessionId`), tool-presentation call-id maps, ACP's session records, and the persistence coordinator. A brand that is dropped at a collection key buys nothing on lookups — the value of the existing brands is partly unrealized.
+**Gap 2 — brand erosion at the boundaries of the *already-branded* IDs.** Even `CallId` and `SessionId` decay back to bare `string` at exactly the places confusion is most likely: registry/store key types and public method params. Representative sites include the session store, the agent registry (both keyed by the shared `SessionId`), tool-presentation call-id maps, ACP's session records, and the persistence coordinator. A brand that is dropped at a collection key buys nothing on lookups — the value of the existing brands is partly unrealized.
 
 ## Decision
 
 A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The work is in three parts, all honoring the existing "not every string" policy.
 
-- **Brand the bash task id.** Add `BashTaskId = Branded<'BashTaskId'>` plus its same-named factory in `packages/bash/bash/src/types.ts` (the package that *owns* the id), importing `Branded` from `@deepseek-ai/dsh-brand` exactly as `SessionId` does. The brand primitive lives in the dependency-free `dsh-brand` utility package precisely so `dsh-bash` can brand its ids by depending on it alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`. Thread it through `BashTask.id`, the `BashExecutor` seam methods (`get`/`ownerOf`/`readOutput`/`kill`), the generation site in `dsh-bash-local` (brand the counter output once, at creation), and the `dsh-tool-bash` validate/access surface (`validateTaskId` returns a `BashTaskId`; `task_id` is branded at the tool boundary where the model's string arrives).
+- **Brand the bash task id.** Add `BashTaskId = Branded<'BashTaskId'>` plus its same-named factory in `packages/bash/bash/src/types.ts` (the package that *owns* the id), importing `Branded` from `@deepseek-ai/dsh-brand` exactly as `SessionId` does. The brand primitive lives in the dependency-free `dsh-brand` utility package precisely so `dsh-bash` can brand its ids by depending on it alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`. Thread it through `BashTask.id`, the `BashExecutor` Service Definition methods (`get`/`ownerOf`/`readOutput`/`kill`), the generation site in `dsh-bash-local` (brand the counter output once, at creation), and the `dsh-tool-bash` validate/access surface (`validateTaskId` returns a `BashTaskId`; `task_id` is branded at the tool boundary where the model's string arrives).
 
-- **Mint a distinct `OwnerToken` brand.** Add `OwnerToken = Branded<'OwnerToken'>` in `packages/bash/bash/src/types.ts`; type `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` as `OwnerToken | undefined`. The `dsh-tool-bash` consumer casts the agent's shared `id` (`SessionId`) into an `OwnerToken` at the boundary — the one place the two vocabularies meet. The bash seam never imports `dsh-session`. (Rationale in the next section.)
+- **Mint a distinct `OwnerToken` brand.** Add `OwnerToken = Branded<'OwnerToken'>` in `packages/bash/bash/src/types.ts`; type `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` as `OwnerToken | undefined`. The `dsh-tool-bash` consumer casts the agent's shared `id` (`SessionId`) into an `OwnerToken` at the boundary — the one place the two vocabularies meet. The bash Service Definition never imports `dsh-session`. (Rationale in the next section.)
 
 - **Stop the brand erosion.** Propagate the existing brands to the `Map` key types and public method params listed under Gap 2 — `Map<SessionId, Session>`, `Map<SessionId, Agent>`, `get(id: SessionId)`, `Map<CallId, …>`, ACP's `SessionId` surface, and the coordinator's `Map<SessionId, …>`. This is the larger mechanical share of the diff and the part that makes the *existing* brands actually load-bearing on lookups, not just on struct fields.
 
@@ -46,7 +46,7 @@ export function OwnerToken(id: string): OwnerToken {
 
 ### Why not typing `owner` as `SessionId`?
 
-The obvious shortcut is to type `owner` as `SessionId` directly — it always *is* one. We reject that. The bash executor seam is a capability seam (interface `dsh-bash`, implementation `dsh-bash-local`, consumer `dsh-tool-bash`) and its owner token is *documented as deliberately opaque*: the executor "never interprets it (no access policy lives in the seam — that is the consumer's job)" (`packages/bash/bash/src/types.ts`). Typing the seam's field as `SessionId` would import `dsh-session`'s vocabulary into a package that must not know what an owner token *means* — it would couple a generic execution backend to the session model and contradict the opaque-token design. A sandboxed or remote executor that replaces `dsh-bash-local` should not inherit a session dependency. The distinct `OwnerToken` brand keeps the seam decoupled: `dsh-bash` knows only "an owner is some opaque branded token," and the `dsh-tool-bash` consumer — which already decides the access policy — is the single boundary that casts its `SessionId` into an `OwnerToken`. The brand still delivers the safety win (you cannot pass a `BashTaskId` or a raw string where an owner is expected) without the coupling.
+The obvious shortcut is to type `owner` as `SessionId` directly — it always *is* one. We reject that. The bash executor seam is a capability seam (Service Definition `dsh-bash`, Service provider `dsh-bash-local`, Consumer `dsh-tool-bash`) and its owner token is *documented as deliberately opaque*: the executor "never interprets it (no access policy lives in the seam — that is the consumer's job)" (`packages/bash/bash/src/types.ts`). Typing the Service Definition's field as `SessionId` would import `dsh-session`'s vocabulary into a package that must not know what an owner token *means* — it would couple a generic execution backend to the session model and contradict the opaque-token design. A sandboxed or remote executor that replaces `dsh-bash-local` should not inherit a session dependency. The distinct `OwnerToken` brand keeps the seam decoupled: `dsh-bash` knows only "an owner is some opaque branded token," and the `dsh-tool-bash` consumer — which already decides the access policy — is the single boundary that casts its `SessionId` into an `OwnerToken`. The brand still delivers the safety win (you cannot pass a `BashTaskId` or a raw string where an owner is expected) without the coupling.
 
 ## Out of scope / possible extensions
 
@@ -60,10 +60,10 @@ Kept deliberately narrow per the "not every string needs a brand" policy. Each o
 
 ## Verification
 
-The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` and threaded end-to-end (executor seam, the `dsh-bash-local` generation site, the `dsh-tool-bash` model-facing surface) with no `dsh-bash` dependency on `dsh-session`; no collection keyed by an in-scope branded id (`CallId`/`SessionId`/`BashTaskId`) is keyed by bare `string`; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied `task_id`), never as scattered `as` casts.
+The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` and threaded end-to-end (Service Definition, the `dsh-bash-local` generation site, the `dsh-tool-bash` model-facing surface) with no `dsh-bash` dependency on `dsh-session`; no collection keyed by an in-scope branded id (`CallId`/`SessionId`/`BashTaskId`) is keyed by bare `string`; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied `task_id`), never as scattered `as` casts.
 
 ## Consequences
 
-- **Mechanical churn across two surfaces.** Propagating brands touches the bash seam (interface + impl + consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md) because both touch the session-id / owner-token boundary; `OwnerToken` stays distinct from the unified id for the decoupling reason above.
+- **Mechanical churn across two surfaces.** Propagating brands touches the bash seam (Service Definition + Service provider + Consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md) because both touch the session-id / owner-token boundary; `OwnerToken` stays distinct from the unified id for the decoupling reason above.
 - **Brands do not validate.** A brand is a confusability guard, not a correctness proof: a *wrong* session id that is still a well-formed string passes the type checker exactly as before. This Agent Note does not close that gap (see Out of scope) — it only stops the *category* error of passing the wrong *kind* of id.
 - **The "where to stop" line stays a judgment call.** Branding `BashTaskId` but not `ToolName`, `OwnerToken` but not `ModelId`, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in `brand.ts` is the tie-breaker, and this Agent Note errs toward the ids that are model-facing or used for access control.
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
index 039953754b..b6b58a8b70 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
@@ -12,15 +12,15 @@ harness 使用 `Branded<B> = string & { readonly [BRAND]: B }` 机制，为 `Cal
 
 bash **owner token** 是相关的子情形：`BashExecRequest.owner?: string` 和 `BashExecSpec.owner: string | undefined`（`packages/bash/bash/src/types.ts`）被文档描述为刻意*不透明*的隔离键，但在所有实际调用方中，该值就是所属 agent（智能体）共享的 `Agent.id`/`SessionId`（`callerToken = (exec) => exec.agent?.id`，位于 `packages/bash/tool-bash/src/index.ts`），只是披着另一个 seam 本地名称。它被用于访问控制比较（`owner !== callerToken(exec)`），因此一个不匹配但类型正确的 string 在此处就是跨会话隔离 bug，而当前类型系统无法捕获。这正是[统一 agent/session 标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)覆盖的共享 id 别名。
 
-**缺口 2：*已经 brand* 的 ID 在 seam 处被侵蚀。** 就连 `CallId` 和 `SessionId` 也恰好在最容易混淆的地方退化为裸 `string`：注册表/store 键类型和公开方法参数。代表性位置包括会话存储、agent 注册表（二者都以共享的 `SessionId` 为键）、工具展示层的 call-id map、ACP（Agent Client Protocol）的会话记录，以及持久化协调器。在集合键处丢弃 brand，会让既有 brand 在查找时毫无价值；它们的价值只实现了一部分。
+**缺口 2：*已经 brand* 的 ID 在边界处被侵蚀。** 就连 `CallId` 和 `SessionId` 也恰好在最容易混淆的地方退化为裸 `string`：注册表/store 键类型和公开方法参数。代表性位置包括会话存储、agent 注册表（二者都以共享的 `SessionId` 为键）、工具展示层的 call-id map、ACP（Agent Client Protocol）的会话记录，以及持久化协调器。在集合键处丢弃 brand，会让既有 brand 在查找时毫无价值；它们的价值只实现了一部分。
 
 ## 决策
 
 纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。工作分三部分，全部遵循既有的「不是每个 string 都需要」策略。
 
-- **为 bash task id 加 brand。** 在 `packages/bash/bash/src/types.ts`（*拥有*该 id 的包）中添加 `BashTaskId = Branded<'BashTaskId'>` 及其同名工厂，从 `@deepseek-ai/dsh-brand` 导入 `Branded`，方式与 `SessionId` 完全一致。brand 原语位于无依赖的 `dsh-brand` 工具包中，正是为了让 `dsh-bash` 仅依赖它就能为自己的 id 加 brand，而无需引入 `dsh-llm`（或 `dsh-session`）来获取 `Branded`。将其贯穿 `BashTask.id`、`BashExecutor` seam 方法（`get`/`ownerOf`/`readOutput`/`kill`）、`dsh-bash-local` 中的生成点（在创建时对计数器输出做一次 brand），以及 `dsh-tool-bash` 的校验/访问面（`validateTaskId` 返回 `BashTaskId`；`task_id` 在模型 string 到达的工具边界处被 brand）。
+- **为 bash task id 加 brand。** 在 `packages/bash/bash/src/types.ts`（*拥有*该 id 的包）中添加 `BashTaskId = Branded<'BashTaskId'>` 及其同名工厂，从 `@deepseek-ai/dsh-brand` 导入 `Branded`，方式与 `SessionId` 完全一致。brand 原语位于无依赖的 `dsh-brand` 工具包中，正是为了让 `dsh-bash` 仅依赖它就能为自己的 id 加 brand，而无需引入 `dsh-llm`（或 `dsh-session`）来获取 `Branded`。将其贯穿 `BashTask.id`、`BashExecutor` Service Definition 方法（`get`/`ownerOf`/`readOutput`/`kill`）、`dsh-bash-local` 中的生成点（在创建时对计数器输出做一次 brand），以及 `dsh-tool-bash` 的校验/访问面（`validateTaskId` 返回 `BashTaskId`；`task_id` 在模型 string 到达的工具边界处被 brand）。
 
-- **铸造独立的 `OwnerToken` brand。** 在 `packages/bash/bash/src/types.ts` 中添加 `OwnerToken = Branded<'OwnerToken'>`；将 `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` 的类型标注为 `OwnerToken | undefined`。`dsh-tool-bash` 消费方在边界处将 agent 共享的 `id`（`SessionId`）cast 为 `OwnerToken`——这是两套词汇唯一交汇的地方。bash seam 从不导入 `dsh-session`。（理由见下一节。）
+- **铸造独立的 `OwnerToken` brand。** 在 `packages/bash/bash/src/types.ts` 中添加 `OwnerToken = Branded<'OwnerToken'>`；将 `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` 的类型标注为 `OwnerToken | undefined`。`dsh-tool-bash` 消费方在边界处将 agent 共享的 `id`（`SessionId`）cast 为 `OwnerToken`——这是两套词汇唯一交汇的地方。bash Service Definition 从不导入 `dsh-session`。（理由见下一节。）
 
 - **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是 diff 中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
 
@@ -46,7 +46,7 @@ export function OwnerToken(id: string): OwnerToken {
 
 ### 为什么不把 `owner` 类型标注为 `SessionId`？
 
-显而易见的捷径是直接把 `owner` 类型标注为 `SessionId`——它确实*总是*一个会话 id。我们否决这个方案。bash 执行器 seam 是能力 seam（接口 `dsh-bash`、实现 `dsh-bash-local`、消费方 `dsh-tool-bash`），其 owner token 被*明确记录为刻意不透明*：执行器「从不解释它（seam 中没有访问策略——那是消费方的职责）」（`packages/bash/bash/src/types.ts`）。把 seam 字段类型标注为 `SessionId`，会把 `dsh-session` 的词汇引入一个不应知道 owner token *含义*的包——这会让通用执行后端耦合会话模型，并违背不透明 token 的设计。取代 `dsh-bash-local` 的沙箱或远程执行器不应继承会话依赖。独立的 `OwnerToken` brand 使 seam 保持解耦：`dsh-bash` 只知道「owner 是某种带 brand 的不透明 token」，而已经决定访问策略的 `dsh-tool-bash` 消费方，是把其 `SessionId` cast 为 `OwnerToken` 的唯一边界。该 brand 仍带来安全收益（不能把 `BashTaskId` 或裸 string 传到 owner 位置），且不引入耦合。
+显而易见的捷径是直接把 `owner` 类型标注为 `SessionId`——它确实*总是*一个会话 id。我们否决这个方案。bash 执行器 seam 是能力 seam（Service Definition `dsh-bash`、Service provider `dsh-bash-local`、Consumer `dsh-tool-bash`），其 owner token 被*明确记录为刻意不透明*：执行器「从不解释它（seam 中没有访问策略——那是消费方的职责）」（`packages/bash/bash/src/types.ts`）。把 Service Definition 的字段类型标注为 `SessionId`，会把 `dsh-session` 的词汇引入一个不应知道 owner token *含义*的包——这会让通用执行后端耦合会话模型，并违背不透明 token 的设计。取代 `dsh-bash-local` 的沙箱或远程执行器不应继承会话依赖。独立的 `OwnerToken` brand 使 seam 保持解耦：`dsh-bash` 只知道「owner 是某种带 brand 的不透明 token」，而已经决定访问策略的 `dsh-tool-bash` 消费方，是把其 `SessionId` cast 为 `OwnerToken` 的唯一边界。该 brand 仍带来安全收益（不能把 `BashTaskId` 或裸 string 传到 owner 位置），且不引入耦合。
 
 ## 不在范围内 / 可能的扩展
 
@@ -60,10 +60,10 @@ export function OwnerToken(id: string): OwnerToken {
 
 ## 验证
 
-已落地的不变式：`BashTaskId` 和 `OwnerToken` 定义在 `dsh-bash` 中，并端到端贯穿执行器 seam、`dsh-bash-local` 生成点与 `dsh-tool-bash` 面向模型的 surface，且 `dsh-bash` 未添加对 `dsh-session` 的依赖；没有任何以范围内 brand id（`CallId`/`SessionId`/`BashTaskId`）为键的集合使用裸 `string`；公开方法参数和导出签名保留 brand；每个原始 string 进入的边界（提供方 call id、ACP 会话 id、模型提供的 `task_id`）都通过 cast 工厂构造 brand，而不是散落的 `as` cast。
+已落地的不变式：`BashTaskId` 和 `OwnerToken` 定义在 `dsh-bash` 中，并端到端贯穿 Service Definition、`dsh-bash-local` 生成点与 `dsh-tool-bash` 面向模型的 surface，且 `dsh-bash` 未添加对 `dsh-session` 的依赖；没有任何以范围内 brand id（`CallId`/`SessionId`/`BashTaskId`）为键的集合使用裸 `string`；公开方法参数和导出签名保留 brand；每个原始 string 进入的边界（提供方 call id、ACP 会话 id、模型提供的 `task_id`）都通过 cast 工厂构造 brand，而不是散落的 `as` cast。
 
 ## 后果
 
-- **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（接口 + 实现 + 消费方）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。变更可观察地为纯类型变更——无快照或 e2e 行为差异。它与[统一 agent/会话标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)相邻，因为二者都触及会话 id / owner-token 边界；`OwnerToken` 出于上述解耦理由仍与统一后的 id 保持独立。
+- **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（Service Definition + Service provider + Consumer）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。变更可观察地为纯类型变更——无快照或 e2e 行为差异。它与[统一 agent/会话标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)相邻，因为二者都触及会话 id / owner-token 边界；`OwnerToken` 出于上述解耦理由仍与统一后的 id 保持独立。
 - **Brand 不做校验。** Brand 是混淆防护，不是正确性证明：一个*错误的*会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本 Agent Note 不关闭这个缺口（见「不在范围内」）——它只阻止这类*类别*错误：传入错误*种类*的 id。
 - **「在哪里停下」仍是判断题。** 为 `BashTaskId` 加 brand 但不为 `ToolName` 加，为 `OwnerToken` 加但不为 `ModelId` 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；`brand.ts` 中的策略是裁决依据，本 Agent Note 倾向于面向模型或用于访问控制的 id。
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index ebabaccdbb..6da549618b 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: 8cf6a34c3e4fc042bd73c147d83838734dfc9585
-2026-06-20-generic-long-running-tool-runtime.zh.md: 44241321f6e4da428fe3a6402440af344fd69f10
+2026-06-20-generic-long-running-tool-runtime.md: 0dd49fe60f2c45081973657ff960b780d2d47257
+2026-06-20-generic-long-running-tool-runtime.zh.md: 6e8458aea73536859bf4c81894679d31a5034d3a
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 8cf6a34c3e..0dd49fe60f 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -17,9 +17,9 @@ The `tasks/` package group owns background-task semantics:
 - `@deepseek-ai/dsh-tasks` registers running work as `ctx.tasks` and owns task ids, authorization, snapshots, reads, cancellation, waiting, completion listeners, and cleanup.
 - `@deepseek-ai/dsh-tool-tasks` exposes `task_output`, `task_list`, and `task_kill`, injects completion notices, and supplies the background-task system-prompt guidance.
 
-Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The execution seams remain independent of sessions and the task registry.
+Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The bash and subagent capability seams remain independent of sessions and the task registry.
 
-`TaskService` is the abstract seam in `@deepseek-ai/dsh-tasks`; the process-local registry is `LocalTaskService` in `@deepseek-ai/dsh-tasks-local` (the [task-registry seam Agent Note](2026-07-26-task-registry-seam.md) records that split).
+`TaskService` is the Service Definition in `@deepseek-ai/dsh-tasks`; the process-local provider is `LocalTaskService` in `@deepseek-ai/dsh-tasks-local` (the [task-registry contract Agent Note](2026-07-26-task-registry-seam.md) records that split).
 
 ## Runtime contract
 
@@ -103,7 +103,7 @@ Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup,
 
 ### An immediate abstract task-runtime backend
 
-The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry seam Agent Note](2026-07-26-task-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
+The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry contract Agent Note](2026-07-26-task-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
 
 ### Consumer-owned authorization or cleanup events
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index 44241321f6..6e8458aea7 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -17,9 +17,9 @@ Status: implemented
 - `@deepseek-ai/dsh-tasks` 将运行中的工作注册为 `ctx.tasks`，并拥有 task id、授权、快照、读取、取消、等待、完成监听器与清理。
 - `@deepseek-ai/dsh-tool-tasks` 暴露 `task_output`、`task_list` 和 `task_kill`，注入完成通知，并提供后台任务的系统提示词指导。
 
-长时间运行工具是生产方。`dsh-tool-bash` 将 `BashProcess` 适配为增量输出与进程取消；`dsh-tool-subagent` 将子运行适配为最终输出与子运行释放。执行 seam 保持独立，不依赖会话或任务注册表。
+长时间运行工具是生产方。`dsh-tool-bash` 将 `BashProcess` 适配为增量输出与进程取消；`dsh-tool-subagent` 将子运行适配为最终输出与子运行释放。bash 与 subagent 能力 seam 保持独立，不依赖会话或任务注册表。
 
-`TaskService` 是 `@deepseek-ai/dsh-tasks` 中的抽象 seam；进程内注册表是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)中）。
+`TaskService` 是 `@deepseek-ai/dsh-tasks` 中的 Service Definition；进程内 Service provider 是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表约定 Agent Note](2026-07-26-task-registry-seam.md)中）。
 
 ## 运行时约定
 
@@ -103,7 +103,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ### 立即抽象任务运行时后端
 
-当前 `TaskStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
+当前 `TaskStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表约定 Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
 
 ### 由消费方负责授权或清理事件
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index 72569c7b6a..16dde8df0e 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
-2026-06-21-bounded-llm-request-recovery.md: 8879d77a6f6191d028e321487020de7df91c73ae
-2026-06-21-bounded-llm-request-recovery.zh.md: dfbe0e0afa6dfd131cc2be72682c4de9f3c27c9a
+2026-06-21-bounded-llm-request-recovery.md: 985ac3803b8d35ea9275052946dc2cbb33480a9f
+2026-06-21-bounded-llm-request-recovery.zh.md: 8d845cce797d3a17d1223970186a23ffcece1ec8
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
index 8879d77a6f..985ac3803b 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
@@ -48,11 +48,11 @@ Adapters extract structured facts before falling back to message inspection. The
 
 The shared transient-code set is intentionally small: adapter mappings for `RATE_LIMIT` and `SERVER`, explicit `TIMEOUT` and `TRANSPORT` codes for remote failures, and `EMPTY_RESPONSE` for a completed provider response with no content blocks. Both adapters classify the last case as an error finish; see [empty model responses are retryable](../bug-fix/2026-07-24-empty-model-response-is-retryable.md). Authentication, quota, invalid request, context overflow, protocol, abort, and unknown failures keep distinct stable codes and are not transient by default. Adding a code requires adapter fixtures and a documented policy decision; it does not require expanding a second failure-class enum.
 
-### Put retry policy on the existing failed-step seam
+### Put retry policy on the existing failed-step extension point
 
 `@deepseek-ai/dsh-llm-retry` is a function plugin that listens to `agent/request-error`. It introduces no service or new loop branch; the agent-loop package changes only the data carried through its existing failed-step recovery control flow.
 
-The `agent/request-error` seam carries the current `LlmFailure`, an immutable list of prior failures that authorized retry turns in the consecutive recovery sequence, and the serving registration's immutable retry policy. The loop transports but does not interpret that policy, owns the consecutive failure history, and clears it after a successful model request. Normal `dsh-llm-retry` policy counts durable retry records scheduled by the same exact-provider policy, while `dsh-compact-basic` keeps its own context-overflow budget. Alternating transient and context-overflow failures therefore consume their owning finite budgets independently; the maximum request count is one plus the sum of the loaded finite budgets.
+The `agent/request-error` waterfall carries the current `LlmFailure`, an immutable list of prior failures that authorized retry turns in the consecutive recovery sequence, and the serving registration's immutable retry policy. The loop transports but does not interpret that policy, owns the consecutive failure history, and clears it after a successful model request. Normal `dsh-llm-retry` policy counts durable retry records scheduled by the same exact-provider policy, while `dsh-compact-basic` keeps its own context-overflow budget. Alternating transient and context-overflow failures therefore consume their owning finite budgets independently; the maximum request count is one plus the sum of the loaded finite budgets.
 
 The [provider-policy decision](../feature/2026-07-24-provider-retry-policies.md) owns the current configuration shape. Provider adapters register their nested `retryPolicy`; omission uses normal defaults: two transient retries, a 500 millisecond initial delay, a 10 second delay cap, 10 percent jitter, and the five transient codes above. The count and delay bounds match the conservative edge of the inspected implementations: [OpenCode uses two request retries with 500 ms/10 s bounds](https://github.com/anomalyco/opencode/blob/9976269ab1accfc9f9dc98a4a688c516934de422/%70ackages/llm/src/route/executor.ts#L36-L39), [Pi separates three agent-level retries from provider retries and defaults provider retries to zero](https://github.com/earendil-works/pi/blob/3da591ab74ab9ab407e72ed882600b2c851fae21/%70ackages/coding-agent/docs/settings.md#L139-L147), and [Codex uses finite request/stream budgets plus a five-minute idle timeout](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/model-provider-info/src/lib.rs#L25-L33). Ten percent follows [Codex's bounded jitter](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/codex-client/src/retry.rs#L40-L47).
 
@@ -113,7 +113,7 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - `agent/request-error` carries current failure facts, immutable prior-retried failure facts, and the serving registration's immutable retry policy; a success clears the history, and alternating transient/context-overflow integration tests prove the two policies consume only their own finite budgets.
 - Each provider adapter validates its nested retry policy at Loader startup, and `ctx.llm` captures it with the route; normal mode delegates ineligible paths and makes at most `maxRetries + 1` provider requests when no other policy applies.
 - HMR-during-backoff tests prove disposal unregisters the listener, aborts and awaits its captured callbacks, emits no retry decision after disposal, and leaves no timer or promise alive.
-- Pure unit tests cover transient-code selection, exponential backoff and jitter bounds, valid and over-cap `Retry-After`, exhausted budgets, deterministic timer/random seams, and abort during backoff.
+- Pure unit tests cover transient-code selection, exponential backoff and jitter bounds, valid and over-cap `Retry-After`, exhausted budgets, deterministic timer/random hooks, and abort during backoff.
 - Real agent-loop tests cover failure before chunks, partial chunks then failure, thrown and in-band failures, retry to success in a new turn, exhaustion to structured `turn/end.reason`, and composition with `dsh-compact-basic` context-overflow recovery.
 - The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry records its own chunk seqs and provider/model route.
 - The plugin-owned `llm/retry` event is non-surface, survives JSONL and SQLite round trips, is ignored by message derivation, and drives TUI and Web retraction plus scheduled-retry rendering. Client tests cover complete wire validation, clock-independent countdown, cancellation versus completed retry labels, and trajectory attribution; keyless UI snapshots cover Web scheduling and success, a real Web composition test covers partial transport failure through recovery, and ACP automation snapshots confirm that a discarded attempt stays off the wire while the recovered reply is emitted.
@@ -134,5 +134,5 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - [Structured error taxonomy](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md) owns stable machine-routable codes and cause chaining.
 - [Reconstructable requests](../../implemented/architecture/2026-07-05-reconstructable-requests.md) makes provider/model and complete request inputs durable before dispatch.
 - [Timeout deadline library](../../implemented/architecture/2026-07-06-timeout-deadline-library.md) separates shared deadline classification from capability-owned termination.
-- [After-call compaction pressure and context-overflow recovery](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md) owns the current closed-step request-recovery seam and bounded overflow retry.
+- [After-call compaction pressure and context-overflow recovery](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md) owns the current closed-step request-recovery extension point and bounded overflow retry.
 - [Provider-routed LLM adapters](../../implemented/architecture/2026-07-14-provider-routed-llm-adapters.md) owns explicit provider/model routing and the one-adapter-per-provider invariant.
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index dfbe0e0afa..8d845cce79 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -48,11 +48,11 @@ agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agen
 
 共享的暂时性 code 集有意保持很小：适配器针对 `RATE_LIMIT` 和 `SERVER` 的映射，远程失败使用的显式 `TIMEOUT` 和 `TRANSPORT` code，以及提供方响应已完成却没有内容块时使用的 `EMPTY_RESPONSE`。两个适配器都会把最后一种情况归类为错误 finish；详见[空模型响应可重试](../bug-fix/2026-07-24-empty-model-response-is-retryable.md)。身份验证、配额、无效请求、上下文溢出、协议、中止和未知失败都保留不同的稳定 code，且默认不属于暂时性失败。新增 code 需要适配器 fixture（测试前置数据）和已记录的策略决策；无需扩展第二个失败类枚举。
 
-### 将重试策略放在现有失败步骤 seam 上
+### 将重试策略放在现有失败步骤扩展点上
 
 `@deepseek-ai/dsh-llm-retry` 是监听 `agent/request-error` 的函数插件。它不引入服务或新的循环分支；agent-loop 包仅会更改通过现有失败步骤恢复控制流携带的数据。
 
-`agent/request-error` seam 携带当前 `LlmFailure`、在连续恢复序列中授权重试轮次的不可变先前失败列表，以及实际服务注册所对应的不可变重试策略。循环只传递而不解释该策略；它拥有连续失败历史，并在模型请求成功后清除。`dsh-llm-retry` 的 normal 策略统计由同一项确切提供方策略安排的持久重试记录，`dsh-compact-basic` 则维护自己的上下文溢出预算。因此，暂时性失败与上下文溢出交替出现时，会各自独立消耗其有限预算；最大请求数等于 1 加上所有已加载有限预算之和。
+`agent/request-error` waterfall 携带当前 `LlmFailure`、在连续恢复序列中授权重试轮次的不可变先前失败列表，以及实际服务注册所对应的不可变重试策略。循环只传递而不解释该策略；它拥有连续失败历史，并在模型请求成功后清除。`dsh-llm-retry` 的 normal 策略统计由同一项确切提供方策略安排的持久重试记录，`dsh-compact-basic` 则维护自己的上下文溢出预算。因此，暂时性失败与上下文溢出交替出现时，会各自独立消耗其有限预算；最大请求数等于 1 加上所有已加载有限预算之和。
 
 当前配置形状由[提供方策略决策](../feature/2026-07-24-provider-retry-policies.md)规定。提供方适配器会注册嵌套的 `retryPolicy`；省略时使用 normal 默认值：两次暂时性重试、500 毫秒初始延迟、10 秒延迟上限、10% 抖动，以及上述五个暂时性 code。计数与延迟边界参考了所调查实现中较保守的一端：[OpenCode 使用两次请求重试，延迟边界为 500 毫秒／10 秒](https://github.com/anomalyco/opencode/blob/9976269ab1accfc9f9dc98a4a688c516934de422/%70ackages/llm/src/route/executor.ts#L36-L39)；[Pi 将三次 agent 级重试与提供方重试分开，且提供方重试默认为零](https://github.com/earendil-works/pi/blob/3da591ab74ab9ab407e72ed882600b2c851fae21/%70ackages/coding-agent/docs/settings.md#L139-L147)；[Codex 使用有限请求／流预算以及五分钟空闲超时](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/model-provider-info/src/lib.rs#L25-L33)。10% 抖动参考 [Codex 的有界抖动](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/codex-client/src/retry.rs#L40-L47)。
 
@@ -113,7 +113,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - `agent/request-error` 携带当前失败事实、不可变的先前已重试失败事实，以及实际服务注册所对应的不可变重试策略；成功会清除历史，暂时性失败／上下文溢出交替发生的集成测试证明两种策略只消耗各自的有限预算。
 - 每个提供方适配器都在 Loader 启动时验证其嵌套重试策略，`ctx.llm` 则将该策略与路由一同捕获；normal mode 会委托不合格路径，而且在没有其他策略时最多发起 `maxRetries + 1` 次提供方请求。
 - 退避期间执行 HMR 的测试证明：dispose 过程会注销监听器、中止并等待其捕获的回调，dispose 后不发出重试决策，也不留下存活的定时器或 promise。
-- 纯单元测试覆盖暂时性 code 选择、指数退避和抖动边界、有效及超出上限的 `Retry-After`、耗尽的预算、确定性定时器／随机数 seam，以及退避期间中止。
+- 纯单元测试覆盖暂时性 code 选择、指数退避和抖动边界、有效及超出上限的 `Retry-After`、耗尽的预算、确定性定时器／随机数钩子，以及退避期间中止。
 - 真实 agent-loop 测试覆盖分片前失败、部分分片后失败、抛出及带内失败、在新轮次中重试至成功、耗尽后写入结构化 `turn/end.reason`，以及与 `dsh-compact-basic` 上下文溢出恢复的组合。
 - 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试会记录自己的分片 seq 和提供方／模型路由。
 - 插件拥有的不进入表层的 `llm/retry` 事件可在 JSONL 和 SQLite 往返后保留，被消息派生忽略，并驱动 TUI 和 Web 撤回及计划重试渲染。客户端测试覆盖完整的 wire 验证、独立于时钟的倒计时、已取消与已完成重试标签的区别以及轨迹归属；无密钥 UI 快照覆盖 Web 的调度与成功，真实 Web 组合测试覆盖部分传输失败直至恢复，ACP 自动化快照确认，被丢弃的尝试不会通过协议发出，而恢复后的回复会正常发出。
@@ -134,5 +134,5 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - [结构化错误分类体系](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md)负责稳定、可供机器路由的 code 与 cause chaining。
 - [可重建请求](../../implemented/architecture/2026-07-05-reconstructable-requests.md)使提供方／模型和完整请求输入在分发前持久化。
 - [超时 deadline 库](../../implemented/architecture/2026-07-06-timeout-deadline-library.md)将共享的 deadline 分类与能力自身拥有的终止操作分开。
-- [调用后压缩压力与上下文溢出恢复](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)负责当前已关闭步骤的请求恢复 seam 与有界溢出重试。
+- [调用后压缩压力与上下文溢出恢复](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)负责当前已关闭步骤的请求恢复扩展点与有界溢出重试。
 - [提供方路由的 LLM（大语言模型）适配器](../../implemented/architecture/2026-07-14-provider-routed-llm-adapters.md)负责显式提供方／模型路由与每个提供方仅有一个适配器的不变量。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 6303b1e77a..32db924032 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: 6f0d0199f859fd462fdecc24e4063cbd27311bab
+2026-06-21-mandatory-app-attribution-headers.md: 71e74e753c39c8eddfe886d69ee9f28edff9ebab
+2026-06-21-mandatory-app-attribution-headers.zh.md: 9cc2c178cd83f3f041282a0dac34b70f78bcc467
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index de9125bc89..71e74e753c 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-21-mandatory-app-attribution-headers.zh.md)
 
 ## Problem
 
-LLM provider requests should identify the product making them. That is useful for provider-side support, abuse investigation, compatibility debugging, and traffic analytics. Before this Agent Note the harness only partially did this: the hand-rolled DeepSeek adapter sent a hand-copied `User-Agent` constant (`packages/llm/llm-deepseek/src/adapter.ts`), while the pi-ai-backed twin sent no harness-owned headers at all (`packages/llm/llm-pi-ai/src/adapter.ts`). New adapters could therefore omit attribution silently, and a library-backed adapter could drift from the hand-rolled adapter even though [the twin-adapter Agent Note](2026-06-13-twin-llm-adapters.md) exists to keep the provider seam honest across both implementations.
+LLM provider requests should identify the product making them. That is useful for provider-side support, abuse investigation, compatibility debugging, and traffic analytics. Before this Agent Note the harness only partially did this: the hand-rolled DeepSeek adapter sent a hand-copied `User-Agent` constant (`packages/llm/llm-deepseek/src/adapter.ts`), while the pi-ai-backed twin sent no harness-owned headers at all (`packages/llm/llm-pi-ai/src/adapter.ts`). New adapters could therefore omit attribution silently, and a library-backed adapter could drift from the hand-rolled adapter even though [the twin-adapter Agent Note](2026-06-13-twin-llm-adapters.md) exists to keep the provider contract honest across both implementations.
 
 The immediate prompt came from OpenRouter's [App Attribution](https://openrouter.ai/docs/app-attribution) docs. OpenRouter creates app pages and rankings from `HTTP-Referer` plus display/category headers. That is valuable, but it is not the HTTP standard for application identity. The risk is adopting OpenRouter's exact header set as if it were universal, then leaking provider-specific headers to direct DeepSeek requests, future OpenAI/Anthropic/Vertex adapters, test servers, or proxies that log unknown fields indefinitely.
 
@@ -34,7 +34,7 @@ The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attri
 - version: read from the owning package's manifest via `createRequire`, never a hand-copied constant
 - app URL: `https://github.com/deepseek-ai/deepseek-harness-sdk` - the planned public home, which must exist before release
 
-The default is mandatory and non-empty. White-label deployments pass their own `AppIdentity` to `attributionHeaders(identity)` - the override seam is the function parameter, with no deployment config plumbing until a consumer needs it - and omission falls back to the harness default rather than suppressing attribution. There is no per-request API for the model, user prompt, session id, cwd, user email, API key owner, or local machine identity to influence these fields.
+The default is mandatory and non-empty. White-label deployments pass their own `AppIdentity` to `attributionHeaders(identity)` - the override hook is the function parameter, with no deployment config plumbing until a consumer needs it - and omission falls back to the harness default rather than suppressing attribution. There is no per-request API for the model, user prompt, session id, cwd, user email, API key owner, or local machine identity to influence these fields.
 
 Wire mapping (`attributionHeaders`; header names lowercase in code - HTTP field names are case-insensitive on the wire):
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 6f0d0199f8..9cc2c178cd 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-LLM（大语言模型）提供方请求应当标识发出请求的产品。这对提供方侧的技术支持、滥用调查、兼容性调试和流量分析都有价值。在本 Agent Note 之前，harness 只做了部分工作：手写的 DeepSeek 适配器发送了一个手动复制的 `User-Agent` 常量（`packages/llm/llm-deepseek/src/adapter.ts`），而基于 pi-ai 的孪生适配器则完全不发送 harness 自有的头部（`packages/llm/llm-pi-ai/src/adapter.ts`）。因此新适配器可以悄无声息地省略归属标识，而基于库的适配器也可能与手写适配器产生偏差——尽管[孪生适配器 Agent Note](2026-06-13-twin-llm-adapters.md) 的存在正是为了让两种实现在提供方 seam 上保持诚实。
+LLM（大语言模型）提供方请求应当标识发出请求的产品。这对提供方侧的技术支持、滥用调查、兼容性调试和流量分析都有价值。在本 Agent Note 之前，harness 只做了部分工作：手写的 DeepSeek 适配器发送了一个手动复制的 `User-Agent` 常量（`packages/llm/llm-deepseek/src/adapter.ts`），而基于 pi-ai 的孪生适配器则完全不发送 harness 自有的头部（`packages/llm/llm-pi-ai/src/adapter.ts`）。因此新适配器可以悄无声息地省略归属标识，而基于库的适配器也可能与手写适配器产生偏差——尽管[孪生适配器 Agent Note](2026-06-13-twin-llm-adapters.md) 的存在正是为了让两种实现在提供方约定上保持诚实。
 
 直接触发因素来自 OpenRouter 的[应用归属](https://openrouter.ai/docs/app-attribution)文档。OpenRouter 根据 `HTTP-Referer` 加上 display/category 头部来创建应用页面和排名。这有价值，但它不是 HTTP 标准中的应用身份机制。风险在于：把 OpenRouter 的精确头部集当作通用标准来采纳，然后将提供方特有的头部泄漏到直连 DeepSeek 的请求、未来的 OpenAI/Anthropic/Vertex 适配器、测试服务器或无限期记录未知字段的代理中。
 
@@ -34,7 +34,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 - 版本：通过 `createRequire` 从所属包的 manifest（元数据清单）读取，绝不手动复制常量
 - 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页，且必须在发布前实际存在
 
-默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖 seam 就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
+默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖钩子就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
 
 线路映射（`attributionHeaders`；代码中头部名称小写——HTTP 字段名在线路上不区分大小写）：
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index 43259e19b2..4147d8dc12 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.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 .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
-2026-06-24-web-capability-seam.md: b705236690859961ed69b307dbb59ebefcbd65ac
-2026-06-24-web-capability-seam.zh.md: ea9261b4bc16cbd913c90f5ccb1aeebc1a0d8dea
+2026-06-24-web-capability-seam.md: 3893c9f9d45eac90c9ae381f9fa92ad8c7ae7644
+2026-06-24-web-capability-seam.zh.md: 70745c235d17e3cbf6152c2ef470283b0bad85f2
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
index b705236690..3893c9f9d4 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-24-web-capability-seam.zh.md)
 
 ## Problem
 
-The harness needs model-facing web tools without binding the model contract to one vendor's API shape. Search is the immediate pressure point: supporting both Exa search and Perplexity search from the start — two deliberately different provider shapes (Exa returns a flat `results[]` of `{title, url, highlights, publishedDate}`; Perplexity returns a generated answer plus citations) — is what proves the normalized seam does not just mirror one vendor. Fetch is a separate capability: an anonymous public HTTP(S) fetch backend has transport, security, redirect, decoding, and size-limit concerns that are not the same as provider-backed search.
+The harness needs model-facing web tools without binding the model contract to one vendor's API shape. Search is the immediate pressure point: supporting both Exa search and Perplexity search from the start — two deliberately different provider shapes (Exa returns a flat `results[]` of `{title, url, highlights, publishedDate}`; Perplexity returns a generated answer plus citations) — is what proves the normalized web contract does not just mirror one vendor. Fetch is a separate operation: an anonymous public HTTP(S) fetch backend has transport, security, redirect, decoding, and size-limit concerns that are not the same as provider-backed search.
 
 The model-facing surface must stay stable while backends change. A search provider swap should not change how the model asks for a query, and a fetch implementation swap should not change how the model asks for a URL. Conversely, a provider package should not expose its own model-facing tool schema just because it has extra provider-specific knobs.
 
@@ -38,7 +38,7 @@ The seam deliberately exposes no observation surface — no registry-change even
 
 ## Package topology
 
-The three-package interface/implementation/consumer split follows bash and filesystem, but the *interface* package is closer to the LLM seam. `LlmService` (`packages/llm/llm/src/index.ts`) is a name-keyed provider registry: `registerAdapter(models, adapter)` stores adapters in a `Map`, returns a disposer, throws `DUPLICATE_ADAPTER` on duplicate keys, and throws `NO_ADAPTER` at resolution time. `ctx.web` follows that registry shape, but has two capability kinds and a richer selection policy (a configured provider id, or auto-select when exactly one usable provider is registered), so the `WebError` an execution throws can explain why a search or fetch capability cannot run.
+The three-package Service Definition / Service provider / Consumer split follows bash and filesystem, but the *interface* package is closer to the LLM seam. `LlmService` (`packages/llm/llm/src/index.ts`) is a name-keyed provider registry: `registerAdapter(models, adapter)` stores adapters in a `Map`, returns a disposer, throws `DUPLICATE_ADAPTER` on duplicate keys, and throws `NO_ADAPTER` at resolution time. `ctx.web` follows that registry shape, but has two capability kinds and a richer selection policy (a configured provider id, or auto-select when exactly one usable provider is registered), so the `WebError` an execution throws can explain why a search or fetch capability cannot run.
 
 The dependency direction mirrors bash and filesystem:
 
@@ -280,7 +280,7 @@ Tool execution lets these errors flow through `ToolRegistry.execute()`, which al
 
 ## Testing
 
-Each layer is pinned at its own seam: the registry/selection/truncation/abort contract and the `WebError` codes in `dsh-web`; per-provider request/response mapping over recorded fixtures (Perplexity fixtures include URL-only citations so the optional source fields stay honest) plus a self-skipping with-key smoke per real provider; real local-HTTP behavior in `web-fetch-local`; and enablement-driven registration, structured execution errors, and result formatting through the real tool registry in `dsh-tool-web`. A real-Loader smoke guards the two export shapes ([postmortem 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)): `dsh-web` is a default-exported service, while the providers and `tool-web` are namespace plugins where a stray `export default` would drop `inject`.
+Each layer is pinned at its own boundary: the registry/selection/truncation/abort contract and the `WebError` codes in `dsh-web`; per-provider request/response mapping over recorded fixtures (Perplexity fixtures include URL-only citations so the optional source fields stay honest) plus a self-skipping with-key smoke per real provider; real local-HTTP behavior in `web-fetch-local`; and enablement-driven registration, structured execution errors, and result formatting through the real tool registry in `dsh-tool-web`. A real-Loader smoke guards the two export shapes ([postmortem 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)): `dsh-web` is a default-exported service, while the providers and `tool-web` are namespace plugins where a stray `export default` would drop `inject`.
 
 ## Alternatives considered
 
@@ -302,7 +302,7 @@ Rejected. Registration order is not a product policy. It can change with config
 
 ### Treat Firecrawl/Exa/Tavily/Parallel extraction as fetch
 
-Rejected for the first version. Those providers often return extracted or summarized content rather than a concrete HTTP response. If the product needs extraction, design `web_extract` or deliberately widen the fetch seam later.
+Rejected for the first version. Those providers often return extracted or summarized content rather than a concrete HTTP response. If the product needs extraction, design `web_extract` or deliberately widen the fetch operation later.
 
 ### Mirror Claude Code's `url + prompt` WebFetch shape
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index ea9261b4bc..70745c235d 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 需要面向模型的 web 工具，但不能将模型约定绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 seam 并非只是镜像某一家厂商。Fetch 是另一项独立能力：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
+harness 需要面向模型的 web 工具，但不能将模型约定绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 web 约定并非只是镜像某一家厂商。Fetch 是另一项独立操作：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
 
 面向模型的接口必须保持稳定，而后端可以更换。更换搜索提供方不应改变模型发起查询的方式；更换 fetch 实现不应改变模型请求 URL 的方式。反过来，提供方包也不应仅仅因为自己有额外的提供方特有旋钮就暴露自己的面向模型工具 schema。
 
@@ -38,7 +38,7 @@ Web 访问是一个一等能力 seam，遵循[能力 seam Agent Note](2026-06-13
 
 ## 包拓扑
 
-由三个包构成的接口/实现/消费方拆分沿用 bash 和 filesystem 的模式，但*接口*包更接近 LLM（大语言模型） seam。`LlmService`（`packages/llm/llm/src/index.ts`）是一个按名称键控的提供方注册表：`registerAdapter(models, adapter)` 将适配器存入 `Map`、返回 disposer、对重复键抛出 `DUPLICATE_ADAPTER`、在解析时抛出 `NO_ADAPTER`。`ctx.web` 沿用该注册表形状，但有两种能力类别和更丰富的选择策略（配置的提供方 id，或在恰好只有一个可用提供方注册时自动选择），因此执行时抛出的 `WebError` 能解释搜索或 fetch 能力为何无法运行。
+由三个包构成的 Service Definition / Service provider / Consumer 拆分沿用 bash 和 filesystem 的模式，但*接口*包更接近 LLM（大语言模型） seam。`LlmService`（`packages/llm/llm/src/index.ts`）是一个按名称键控的提供方注册表：`registerAdapter(models, adapter)` 将适配器存入 `Map`、返回 disposer、对重复键抛出 `DUPLICATE_ADAPTER`、在解析时抛出 `NO_ADAPTER`。`ctx.web` 沿用该注册表形状，但有两种能力类别和更丰富的选择策略（配置的提供方 id，或在恰好只有一个可用提供方注册时自动选择），因此执行时抛出的 `WebError` 能解释搜索或 fetch 能力为何无法运行。
 
 依赖方向与 bash 和 filesystem 一致：
 
@@ -280,7 +280,7 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 ## 测试
 
-每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 约定与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
+每一层在自己的边界处固定：`dsh-web` 中的注册/选择/截断/abort 约定与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
 
 ## 曾考虑的替代方案
 
@@ -302,7 +302,7 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 ### 将 Firecrawl/Exa/Tavily/Parallel 提取视为 fetch
 
-在第一版中否决。这些提供方通常返回提取或摘要后的内容，而非具体的 HTTP 响应。如果产品需要提取，日后设计 `web_extract` 或刻意扩展 fetch seam。
+在第一版中否决。这些提供方通常返回提取或摘要后的内容，而非具体的 HTTP 响应。如果产品需要提取，日后设计 `web_extract` 或刻意扩展 fetch 操作。
 
 ### 镜像 Claude Code 的 `url + prompt` WebFetch 形状
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index 726ab7374d..ffa6f48889 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.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 .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: 4700222aa2e0f91d9f355495c228e2eb92825f55
-2026-06-26-file-context-as-event-gate.zh.md: dff5c3e9ea99e73d3d1a86c4012da1e4232021bb
+2026-06-26-file-context-as-event-gate.md: df1a43e252cff02b287497210664c3d14dcd35a9
+2026-06-26-file-context-as-event-gate.zh.md: 3d784c9e150430c8054f6b08ccc5c66fa85e09b4
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index 4700222aa2..df1a43e252 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
@@ -26,7 +26,7 @@ tool          dsh-tool-fs       executor: resolves, reads windows, writes/edits
 policy        dsh-fs-policy  plugin: listens to fs/write-intent +
                                 fs/edit-intent (single-slot waterfall) and fs/observed
                                 (emit) events; adds observed-state + freshness.
-provider seam dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
+provider contract dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
                                 guard is OPTIONAL; owns the fs policy event vocabulary
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
@@ -72,7 +72,7 @@ These events carry existing `dsh-fs` vocabulary (`FsTarget`, `FsVersion`, `FsWri
 
 **The two `fs/*` decision events are single-slot, first-wins waterfalls.** `dsh-fs-policy` returns without calling `next()`, so it owns the slot in the default deployment; a listener registered earlier or with `prepend` would replace that policy. Permission, audit, and sandbox concerns remain on the composable `tools/execute` waterfall.
 
-The actor is typed `object` in `dsh-fs` — a pure opaque carrier the provider seam never reads or narrows. The owner-derivation (`actor.agent?.session`) and the `{ agent?: { session? } }` structural shape stay entirely inside `dsh-fs-policy`, which narrows the `object` actor to that shape in its listeners. `dsh-fs` owns the event names and the fs vocabulary; it does NOT own the policy layer's runtime owner structure.
+The actor is typed `object` in `dsh-fs` — a pure opaque carrier the provider contract never reads or narrows. The owner-derivation (`actor.agent?.session`) and the `{ agent?: { session? } }` structural shape stay entirely inside `dsh-fs-policy`, which narrows the `object` actor to that shape in its listeners. `dsh-fs` owns the event names and the fs vocabulary; it does NOT own the policy layer's runtime owner structure.
 
 ```ts
 import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
@@ -136,7 +136,7 @@ The tool passes `exec` (the tool-execution context) as the `actor` argument on e
 
 An observed-state entry is the **prior-observation record**: a successful `read`, `write`, OR `edit` all emit `fs/observed` and record `{ version }`, so the entry's presence means "this owner has observed this target at this version", not narrowly "has read it". This is what lets a create-then-edit or edit-then-edit sequence work without an intervening re-read: the mutation refreshes the recorded version to its own result, so the next edit's basis is the version it just produced. `FS_NOT_OBSERVED` rejects only an edit with NO prior observation of any kind. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
 
-`dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event seam. That is what removes the method coupling from `dsh-tool-fs`.
+`dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event gate. That is what removes the method coupling from `dsh-tool-fs`.
 
 ## Bare-provider behavior (no `dsh-fs-policy`)
 
@@ -166,6 +166,6 @@ Tests pin both paths: without `dsh-fs-policy`, the root tool plugin boots agains
 
 - **Event indirection over a method call.** A waterfall + emit is less direct than `await ctx.fileContext.edit(...)`. The payoff is removing the tool-to-policy method dependency while keeping the default policy plugin; the cost is one more event vocabulary to learn. Mitigated by keeping the three events narrow and documenting the default-thunk semantics on each.
 - **Policy events in the storage seam.** `dsh-fs` gains two version-decision events plus a recording event though it is "just storage". This is the price of decoupling (the emitter cannot depend on the policy plugin). The events carry only `dsh-fs` vocabulary plus an opaque `object` actor and no model-facing concepts, so the seam stays free of line-window/observation policy types and of the agent/session owner structure.
-- **Single policy occupant, first-wins by convention.** The `fs/write-intent`/`fs/edit-intent` slots hold exactly one decider; the first-registered (or `prepend`ed) listener wins and the rest are short-circuited. `dsh-fs-policy` owning the slot is a deployment convention, not an event-enforced invariant — a second decider registered first would bypass it. This is acceptable because a second fs-version-policy decider is a misconfiguration, not a feature. If a future need for *layered* fs version policy appears, it is a new Agent Note (a composable value-passing seam), not a silent second listener on these events. Layered permission/audit/sandbox interception already has its home on `tools/execute`.
+- **Single policy occupant, first-wins by convention.** The `fs/write-intent`/`fs/edit-intent` slots hold exactly one decider; the first-registered (or `prepend`ed) listener wins and the rest are short-circuited. `dsh-fs-policy` owning the slot is a deployment convention, not an event-enforced invariant — a second decider registered first would bypass it. This is acceptable because a second fs-version-policy decider is a misconfiguration, not a feature. If a future need for *layered* fs version policy appears, it is a new Agent Note (a composable value-passing waterfall), not a silent second listener on these events. Layered permission/audit/sandbox interception already has its home on `tools/execute`.
 - **Dropping the post-read confirming stat** makes a follow-up *guarded* edit occasionally fail-closed (`FS_STALE_VERSION` → re-read) under a read/write race. This is a UX nicety lost, never a correctness hole; the provider lock still prevents wrong-version writes.
 - **The bare provider does no read-before-write/edit and no version check.** A deployment without `dsh-fs-policy` lets the model overwrite or edit any existing file unconditionally. This is the deliberate meaning of keeping the tool independent of a policy service: the safety disciplines live in the `dsh-fs-policy` plugin. A deployment that omits it is opting into an unconstrained filesystem on purpose; that is not the intended stance for a config that ships the fs tools.
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index dff5c3e9ea..3d784c9e15 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -26,7 +26,7 @@ tool          dsh-tool-fs       executor: resolves, reads windows, writes/edits
 policy        dsh-fs-policy  plugin: listens to fs/write-intent +
                                 fs/edit-intent (single-slot waterfall) and fs/observed
                                 (emit) events; adds observed-state + freshness.
-provider seam dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
+provider contract dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
                                 guard is OPTIONAL; owns the fs policy event vocabulary
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
@@ -72,7 +72,7 @@ editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion
 
 **两个 `fs/*` 决策事件是单槽、先到先得的 waterfall。** `dsh-fs-policy` 不调用 `next()` 直接返回，因此在默认部署中它占据该槽位；更早注册或使用 `prepend` 的监听器会替代该策略。权限、审计和沙箱关注点仍留在可组合的 `tools/execute` waterfall 上。
 
-actor 在 `dsh-fs` 中类型为 `object`——一个纯粹的不透明载体，提供方 seam 从不读取或收窄它。owner 的推导（`actor.agent?.session`）和 `{ agent?: { session? } }` 结构形状完全留在 `dsh-fs-policy` 内部，由其在监听器中将 `object` actor 收窄为该形状。`dsh-fs` 拥有事件名和 fs 词汇；它不拥有策略层的运行时 owner 结构。
+actor 在 `dsh-fs` 中类型为 `object`——一个纯粹的不透明载体，提供方约定从不读取或收窄它。owner 的推导（`actor.agent?.session`）和 `{ agent?: { session? } }` 结构形状完全留在 `dsh-fs-policy` 内部，由其在监听器中将 `object` actor 收窄为该形状。`dsh-fs` 拥有事件名和 fs 词汇；它不拥有策略层的运行时 owner 结构。
 
 ```ts
 import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
@@ -136,7 +136,7 @@ interface Events {
 
 一条观测状态条目是**先前观测记录**：成功的 `read`、`write` 或 `edit` 都会 emit `fs/observed` 并记录 `{ version }`，因此条目的存在意味着「此 owner 在此版本观测过此目标」，而非狭义的「已读取过」。这使得 create-then-edit 或 edit-then-edit 序列无需中间重新读取即可工作：mutation 将记录的版本刷新为自身的结果，因此下一次编辑的基准就是它刚产出的版本。`FS_NOT_OBSERVED` 只拒绝完全没有任何先前观测的编辑。owner 从 `{ agent?: { session? } }` 结构化推导；dispose 时丢弃所有状态（HMR 安全）。
 
-`dsh-fs-policy` 现在是一个纯策略/记录插件，没有服务面——它只通过事件 seam 影响外界。这正是移除 `dsh-tool-fs` 方法耦合的关键。
+`dsh-fs-policy` 现在是一个纯策略/记录插件，没有服务面——它只通过事件门控影响外界。这正是移除 `dsh-tool-fs` 方法耦合的关键。
 
 ## 裸提供方行为（无 `dsh-fs-policy`）
 
@@ -166,6 +166,6 @@ interface Events {
 
 - **事件间接层取代方法调用。** 一次 waterfall + emit 不如 `await ctx.fileContext.edit(...)` 直接。收益是移除了工具到策略的方法依赖，同时保留默认策略插件；代价是多一套事件词汇需要学习。通过保持三个事件的窄小范围并在每个事件上记录 default-thunk 语义来缓解。
 - **策略事件位于存储 seam 中。** `dsh-fs` 增加了两个版本决策事件和一个记录事件，尽管它「只是存储」。这是解耦的代价（发射方不能依赖策略插件）。这些事件只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不携带面向模型的概念，因此 seam 不沾染行窗口/观测策略类型，也不沾染 agent/会话所有者结构。
-- **单一策略占位者，按约定先到先得。** `fs/write-intent`/`fs/edit-intent` 槽位恰好容纳一个决策者；先注册（或 `prepend`）的监听器获胜，其余被短路。`dsh-fs-policy` 占据该槽位是部署约定，而非事件系统强制的不变式——一个先注册的第二决策者会绕过它。这是可接受的，因为第二个 fs 版本策略决策者是配置错误，而非功能。如果未来出现*分层* fs 版本策略的需求，那是一个新 Agent Note（可组合的值传递 seam），而非在这些事件上静默添加第二个监听器。分层的权限/审计/沙箱拦截已有其归属：`tools/execute`。
+- **单一策略占位者，按约定先到先得。** `fs/write-intent`/`fs/edit-intent` 槽位恰好容纳一个决策者；先注册（或 `prepend`）的监听器获胜，其余被短路。`dsh-fs-policy` 占据该槽位是部署约定，而非事件系统强制的不变式——一个先注册的第二决策者会绕过它。这是可接受的，因为第二个 fs 版本策略决策者是配置错误，而非功能。如果未来出现*分层* fs 版本策略的需求，那是一个新 Agent Note（可组合的值传递 waterfall），而非在这些事件上静默添加第二个监听器。分层的权限/审计/沙箱拦截已有其归属：`tools/execute`。
 - **移除读后确认 stat** 使后续*有守卫*的编辑在 read/write 竞争下偶尔为安全起见拒绝写入（`FS_STALE_VERSION` → 重新读取）。这是丢失的 UX 便利，绝非正确性漏洞；提供方锁仍阻止基于错误版本的写入。
 - **裸提供方不做先读后写/编辑，也不做版本检查。** 没有 `dsh-fs-policy` 的部署允许模型无条件覆写或编辑任何已有文件。这正是保持工具独立于策略服务的有意含义：安全纪律存在于 `dsh-fs-policy` 插件中。省略它的部署是有意选择无约束的文件系统；对于发布 fs 工具的配置而言，这不是预期的姿态。
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
index 459ffa188c..8201388c72 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: aa0c785be84bcb8a49f8a2670afa0f6bed6277db
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 48108fdd5b8217263590fba336480f1b487e882f
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 1c2cfc4257e93b2f2f126947e93b38aa2d4cd570
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 050f604259033f20be8174754c32f624e9a0ce76
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
index aa0c785be8..1c2cfc4257 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md)
 
 The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.bash` capability seam ([dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This Agent Note adds those two inputs.
 
-`stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these seam fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule.
+`stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these Service Definition fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule.
 
 ## Decision
 
@@ -16,7 +16,7 @@ Add `stdin?: string` and `env?: Record<string, string>` to **both** `BashExecReq
 
 Three deliberate choices:
 
-1. **The model-facing tool omits `stdin` and `env`.** Shell syntax already covers those needs, so duplicate parameters would add surface without authority separation. The tool builds requests only from declared model arguments, signal, and owner; trusted in-process callers may set the seam fields directly. Harness-owned variables use the separate `dshEnv` channel from the [managed environment decision](../feature/2026-07-10-agent-session-identity-and-log-location.md), so ordinary `env` cannot replace them.
+1. **The model-facing tool omits `stdin` and `env`.** Shell syntax already covers those needs, so duplicate parameters would add surface without authority separation. The tool builds requests only from declared model arguments, signal, and owner; trusted in-process callers may set the request fields directly. Harness-owned variables use the separate `dshEnv` channel from the [managed environment decision](../feature/2026-07-10-agent-session-identity-and-log-location.md), so ordinary `env` cannot replace them.
 
 2. **`env` merges AFTER the credential scrub, so an explicit caller entry wins even on a credential-shaped name.** The later managed-namespace decision manages `DSH_*`: ambient entries are removed, and trusted `dshEnv` merges last, so an ordinary `env` entry can never displace a managed value. The complete order is `scrub(process.env, including DSH_*)` → `ENV_OVERRIDES` → ordinary `env` → `dshEnv`.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
index 48108fdd5b..050f604259 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令：钩子是一条 shell 命令，通过 **stdin 上的 JSON** 接收事件载荷，并从若干**环境变量**（`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……）读取上下文。harness 已经在 `ctx.bash` 能力 seam 后面有一个完善的命令执行器（[dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)），具备进程组终止、输出截断/溢出处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程管道——但该 seam 此前无法写入 stdin 或设置额外 env。本 Agent Note 添加这两个输入。
 
-`stdin` 和 `env` 不构成新的模型能力，因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护，而非靠隐藏这些 seam 字段；模型工具参数是静态 JSON，不会展开 shell 变量。因此这些字段服务于受信的进程内调用方（如钩子桥接层），它们需要传递结构化输入和 `CLAUDE_*` 变量，而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.md)。
+`stdin` 和 `env` 不构成新的模型能力，因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护，而非靠隐藏这些 Service Definition 字段；模型工具参数是静态 JSON，不会展开 shell 变量。因此这些字段服务于受信的进程内调用方（如钩子桥接层），它们需要传递结构化输入和 `CLAUDE_*` 变量，而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.md)。
 
 ## 决策
 
@@ -16,7 +16,7 @@ Status: implemented
 
 三个有意为之的选择：
 
-1. **模型侧工具不暴露 `stdin` 和 `env`。** Shell 语法已覆盖这些需求，重复参数只会增加接口面而不带来权限隔离。工具仅从声明的模型参数、signal 和 owner 构建请求；受信的进程内调用方可以直接设置 seam 字段。harness 自有变量使用[托管环境决策](../feature/2026-07-10-agent-session-identity-and-log-location.md)规定的独立 `dshEnv` 通道，因此普通 `env` 无法替换它们。
+1. **模型侧工具不暴露 `stdin` 和 `env`。** Shell 语法已覆盖这些需求，重复参数只会增加接口面而不带来权限隔离。工具仅从声明的模型参数、signal 和 owner 构建请求；受信的进程内调用方可以直接设置请求字段。harness 自有变量使用[托管环境决策](../feature/2026-07-10-agent-session-identity-and-log-location.md)规定的独立 `dshEnv` 通道，因此普通 `env` 无法替换它们。
 
 2. **`env` 在凭证擦除之后合并，因此调用方显式设置的条目即使具有凭证形态的名称也会胜出。** 后续的托管命名空间决策负责管理 `DSH_*`：这类环境条目会被移除，受信的 `dshEnv` 最后合并，因此普通 `env` 条目永远无法顶掉托管值。完整顺序为 `scrub(process.env, including DSH_*)` → `ENV_OVERRIDES` → 普通 `env` → `dshEnv`。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index 2e69991c33..fab7f4d6d6 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.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 .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
-2026-06-30-event-domain-semantics.md: 14102b105e7bcaa6a00ac9c406933f772fc45a6f
-2026-06-30-event-domain-semantics.zh.md: 2607e59490d8ba139bb1289d0f2941894281f6c6
+2026-06-30-event-domain-semantics.md: a3af693126b71c5844260f53c62b4ab4a28fe56f
+2026-06-30-event-domain-semantics.zh.md: 1f6df779fdccb921861f6ea848e33d9cd866b027
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
index 14102b105e..a3af693126 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
@@ -10,7 +10,7 @@ The harness extends the agent loop through a Cordis event taxonomy (see [the mic
 
 - `session/*` carries the durable, event-sourced log (`SessionEventMap`).
 - `agent/*` carries live runtime signals that hand a plugin the `Agent` handle.
-- `tools/*` carries the tool registry + execution seam.
+- `tools/*` carries the tool registry and execution pipeline.
 
 Two problems motivated pinning the semantics down. First, several turn/step boundaries existed BOTH as a durable `SessionEvent` (`turn/start`, `turn/end`, `step/start`, `step/end`) AND as a mirrored `agent/*` emit (`agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end`). A consumer had two sources of truth for the same fact, and every lifecycle change had to update both. Second, the upcoming Hooks subsystem needs ONE coherent, documented surface to subscribe to — a plugin author (and the Claude Code / Codex hook bridges built on top) must know, without reading the loop, whether to listen on a session event or an agent event, and why.
 
@@ -22,7 +22,7 @@ This vocabulary is the foundation for interception decisions, the durable `hook/
 
 - **`session/*` — the durable, replayable FACT log.** Owns `SessionEventMap`; every entry is JSON-only (no live objects). One `session/event` emit per append, plus the `session/flush` parallel durability checkpoint. It is also the live transcript feed: a consumer that wants to render or react to what happened subscribes here, so live rendering and replay projections share one path.
 - **`agent/*` — the LIVE runtime surface.** Always carries the live `Agent`. Interception waterfalls (`agent/pre-step`, `agent/request`, `agent/request-error`) transform, reject, or recover; awaited `agent/turn-stopping` observes the stop boundary; transient emits report lifecycle, status, inbox insertion/claim/discard, and errors. Turn and step BOUNDARIES are NOT here — they are durable session events read off `session/event`, as are the token stream (`assistant/chunk`) and mid-turn steering (a `user/message`).
-- **`tools/*` — the tool registry + execution seam.**
+- **`tools/*` — the tool registry and execution pipeline.**
 
 **The boundary rule:** a durable, replayable fact is a `SessionEvent`; a live interception or a transient/live-object signal is an `agent`/`tools` Cordis event. A turn or step boundary is a durable fact, so it lives in the session log and is read off the `session/event` feed — it is NOT mirrored as an `agent/*` emit.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
index 2607e59490..1f6df779fd 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -10,7 +10,7 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 
 - `session/*` 承载持久的、事件溯源的日志（`SessionEventMap`）。
 - `agent/*` 承载运行时实时信号，向插件传递 `Agent` 句柄。
-- `tools/*` 承载工具注册表与执行 seam。
+- `tools/*` 承载工具注册表与执行流水线。
 
 两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `SessionEvent`（`turn/start`、`turn/end`、`step/start`、`step/end`）和镜像的 `agent/*` emit（`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`）存在。消费方对同一事实有两个真源，每次生命周期变更都必须同时更新两处。第二，即将到来的钩子子系统需要一个连贯且有文档的订阅表面——插件作者（以及基于其上构建的 Claude Code / Codex 钩子桥接）必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件，以及原因。
 
@@ -21,8 +21,8 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 **三个域，各司其职，以一条边界规则统一。**
 
 - **`session/*`——持久的、可回放的事实日志。** 拥有 `SessionEventMap`；每条记录仅含 JSON（无活对象）。每次追加触发一次 `session/event` emit，加上 `session/flush` 并行持久性检查点。它同时也是实时 transcript（文本记录）源：想渲染或响应已发生事件的消费方在此订阅，因此实时渲染与回放投影共享同一路径。
-- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和作为一条 `user/message` 的轮次中途 steering（中途引导）同理。
-- **`tools/*`——工具注册表与执行 seam。**
+- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和中途 steering（以 `user/message` 呈现）同理。
+- **`tools/*`——工具注册表与执行流水线。**
 
 **边界规则：** 持久的、可回放的事实是 `SessionEvent`；实时拦截或瞬态/活对象信号是 `agent`/`tools` Cordis 事件。轮次或步骤边界是持久事实，因此存在于会话日志中并从 `session/event` 源读取——不会被镜像为 `agent/*` emit。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml
index da7848d581..ceccf93631 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.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 .agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
-2026-07-02-fs-per-session-cwd.md: d3f54e89e735016a373fa14c60123c681b3e7adf
-2026-07-02-fs-per-session-cwd.zh.md: 86058437a14f64cc7faf6e6ad413c52efba5fd39
+2026-07-02-fs-per-session-cwd.md: 23c9f414590df8c79109e46f24af031b765b8f58
+2026-07-02-fs-per-session-cwd.zh.md: 5e429bbda16c2c7e29114e6d8586c13b658cac0a
diff --git a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
index d3f54e89e7..23c9f41459 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
@@ -26,7 +26,7 @@ Thread the caller's session cwd into path resolution, exactly as `dsh-tool-bash`
 
 ### Why the caller supplies the cwd (not the provider)
 
-The provider seam must not depend on `dsh-agent` / `dsh-session` — it is a text-storage backend that a sandboxed or remote implementation also satisfies, and those have no notion of an "agent session". The tool already receives the `ToolExecution` (`exec`), which carries the agent, so the tool is the right place to project `exec → cwd` and hand the provider a plain string. This is the "explicit > implicit at package seams" convention: the base directory arrives as an explicit argument the provider acts on, not smuggled in by having the provider reach into a session it should not know about. It also matches `dsh-tool-bash` one-to-one, so the two model-facing file surfaces resolve paths identically.
+The provider contract must not depend on `dsh-agent` / `dsh-session` — it is a text-storage backend that a sandboxed or remote implementation also satisfies, and those have no notion of an "agent session". The tool already receives the `ToolExecution` (`exec`), which carries the agent, so the tool is the right place to project `exec → cwd` and hand the provider a plain string. This is the "explicit > implicit at package boundaries" convention: the base directory arrives as an explicit argument the provider acts on, not smuggled in by having the provider reach into a session it should not know about. It also matches `dsh-tool-bash` one-to-one, so the two model-facing file surfaces resolve paths identically.
 
 The default lives in ONE place — the provider's `config.cwd`. `sessionCwd` returns `undefined` rather than `process.cwd()` when there is no session, so the tool never manufactures a base the provider would otherwise choose.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
index 86058437a1..5e429bbda1 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
@@ -26,7 +26,7 @@ ACP（Agent Client Protocol）桥接层为每个会话提供独立的工作区
 
 ### 为何由调用方（而非提供方）提供 cwd
 
-提供方 seam 不得依赖 `dsh-agent`／`dsh-session`——它是一个文本存储后端，沙箱或远程实现同样满足该接口，而这些实现没有「agent 会话」的概念。工具已经接收了 `ToolExecution`（`exec`），其中携带 agent，因此工具是将 `exec → cwd` 投影并向提供方传递一个纯字符串的正确位置。这遵循「包边界处显式优于隐式」的约定：基准目录作为显式参数传入，提供方据此行动，而非让提供方越界去读取它不应知晓的会话。这也与 `dsh-tool-bash` 一一对应，使两个面向模型的文件操作接口以相同方式解析路径。
+提供方约定不得依赖 `dsh-agent`／`dsh-session`——它是一个文本存储后端，沙箱或远程实现同样满足该接口，而这些实现没有「agent 会话」的概念。工具已经接收了 `ToolExecution`（`exec`），其中携带 agent，因此工具是将 `exec → cwd` 投影并向提供方传递一个纯字符串的正确位置。这遵循「包边界处显式优于隐式」的约定：基准目录作为显式参数传入，提供方据此行动，而非让提供方越界去读取它不应知晓的会话。这也与 `dsh-tool-bash` 一一对应，使两个面向模型的文件操作接口以相同方式解析路径。
 
 默认值只存在于一个地方——提供方的 `config.cwd`。`sessionCwd` 在没有会话时返回 `undefined` 而非 `process.cwd()`，因此工具永远不会自行制造一个提供方本应自行选择的基准目录。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 9acc4ee6f6..b85c732f6e 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: 3676e4bc7f6d0272f382b13e178f04b16f18f992
-2026-07-05-reconstructable-requests.zh.md: bcae6b941fb0110aa4e5011685365a5edf7512d3
+2026-07-05-reconstructable-requests.md: c971f411eb932cab29d7a52662a0e05a1f638daa
+2026-07-05-reconstructable-requests.zh.md: b788f895cbb33f6ffa59b36430e81384a468f582
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index 3676e4bc7f..c971f411eb 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -49,7 +49,7 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 - A request that is not explained by the log cannot be constructed by accident — not by the loop, not by a listener; mutating a built request throws; every header change is a durable, diffable log event.
 - Model-visible context uses logged message channels. `agent.inject()` and tool `additionalContexts` enter the inbox for a later claim, while `agent/pre-step` returns context that must settle with the current claimed batch. Each entered value is a durable sourced `user/message`, paid once and prefix-cached thereafter at the price of accumulating in history until compaction.
 - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replacement entry), a real prompt, tool, or config change (`request/header` with reason `change`), or a process boundary with drift (a differing `resume` snapshot). The provider's own reasoning-content exclusion is managed server-side.
-- `agent/pre-step` is the current-request message seam; direct inbox mutation is the eventual later-request seam.
+- `agent/pre-step` is the current-request message channel; direct inbox mutation is the eventual later-request channel.
 - Tool-result trimming (planned) needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
 - Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated.
 - Snapshot expected outputs changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index bcae6b941f..b788f895cb 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -47,9 +47,9 @@ Status: implemented
 ## 后果
 
 - 一个日志无法解释的请求不可能被意外构造——无论是循环还是监听器；变异已构建的请求会抛异常；每个 header 变更都是持久的、可 diff 的日志事件。
-- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价，此后即被前缀缓存，代价是会在历史中累积直至压缩。
-- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身对思考内容的排除由服务端管理。
-- `agent/pre-step` 是当前请求的消息 seam；直接修改 inbox 则是最终进入后续请求的 seam。
-- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存失效由相同的压力逻辑批量处理。
+- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价并在后续成为可缓存前缀，代价是会在历史中累积直至压缩。
+- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
+- `agent/pre-step` 是当前请求的消息通道；直接修改 inbox 则是最终进入后续请求的通道。
+- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index 8b3d66c3b0..c85785a097 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.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 .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: 1afb8e326356f012498eed778e9bab1b0be64ea5
-2026-07-06-timeout-deadline-library.zh.md: c6992ba5463122e4eb4ebd1d904d0c0906140353
+2026-07-06-timeout-deadline-library.md: 72f02208f601ff5514fe6ea0006ea922cdbd49b7
+2026-07-06-timeout-deadline-library.zh.md: c4da7f2028abc32d0c393dd1aeb3c59a4c05acec
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index 1afb8e3263..72f02208f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
@@ -97,7 +97,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 
 ## Consequences
 
-- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the seam type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched.
+- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the Service Definition type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched.
 - `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index c6992ba546..c4da7f2028 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -97,7 +97,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 ## 后果
 
-- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，seam 类型 `BashRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。
+- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，Service Definition 类型 `BashRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index 6e7aa8291a..36484da590 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.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 .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
-2026-07-07-tool-call-timeout-policy.md: b85a4d2d60ef60d9f75bd47d4d405aa55c132af6
-2026-07-07-tool-call-timeout-policy.zh.md: f6a85c13a66689c48b10f160890ce3825125aec1
+2026-07-07-tool-call-timeout-policy.md: d341a2c598765b6de4d2a7e242f38847e48f081b
+2026-07-07-tool-call-timeout-policy.zh.md: 6d10b552b951f428f475323ba115007e39b66aaf
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index b85a4d2d60..d341a2c598 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -32,7 +32,7 @@ ctx.tools.execute(exec)
 
 The default behavior is conservative: a tool that declares no `timeoutMs` receives no `TOOL_TIMEOUT` deadline from the plugin.
 
-### The `tools/execute` around seam
+### The `tools/execute` around-dispatch extension point
 
 `@deepseek-ai/dsh-tools` declares a `tools/execute` waterfall whose base `next()` is the dispatch-with-normalization thunk — the same inner `try`/`catch` that turns a thrown tool (or unknown tool) into an `isError` `ToolExecutionResult`. A listener receives `(exec, next)`: it calls `next()` to delegate to dispatch (returning its result, optionally wrapped) or returns a replacement result to short-circuit dispatch. The whole pipeline still sits inside `execute`'s outer try/catch, so a throwing listener becomes an `isError` result, never a turn failure.
 
@@ -101,13 +101,13 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit
 
 **Let `timeout-policy` match tool arguments itself.** A rule engine such as "disable timeout when `bash.run_in_background` is true" would make the policy plugin know tool-specific argument semantics. Avoided by not migrating bash to tool-call timeout.
 
-**Use `tools/pre-execute` plus `tools/post-execute` instead of a new around seam.** A pre listener could arm a deadline and mutate `exec.signal`; a post listener could classify and replace. That loses because the deadline lifetime would cross two independent waterfalls: a call-id map, cleanup on every pre-deny/tool-throw/post-throw/dispose path, and ordering rules with every other listener. `tools/pre-execute` is also the allow/deny gate, not an execution wrapper. `tools/execute` gives the timeout one lexical scope: arm, delegate, classify, dispose.
+**Use `tools/pre-execute` plus `tools/post-execute` instead of a new around-dispatch extension point.** A pre listener could arm a deadline and mutate `exec.signal`; a post listener could classify and replace. That loses because the deadline lifetime would cross two independent waterfalls: a call-id map, cleanup on every pre-deny/tool-throw/post-throw/dispose path, and ordering rules with every other listener. `tools/pre-execute` is also the allow/deny gate, not an execution wrapper. `tools/execute` gives the timeout one lexical scope: arm, delegate, classify, dispose.
 
 **Use `Promise.race` to enforce timeouts for non-cooperative tools.** Rejected for the same reason as the timeout-library Agent Note: it returns control to the caller while the underlying process, fetch, or provider operation may still be running. The plugin only sends a signal; termination remains the implementation's responsibility.
 
 ## Consequences
 
-- `@deepseek-ai/dsh-tools` gains an around-dispatch surface after the interception seams deliberately split pre/post tool hooks. Its contract is narrow — wrap registry dispatch, not replace the pre-gate or post-result policy — and the base `next()` is dispatch-with-normalization so a wrapper never sees a raw tool throw.
+- `@deepseek-ai/dsh-tools` gains an around-dispatch surface after the interception points deliberately split pre/post tool hooks. Its contract is narrow — wrap registry dispatch, not replace the pre-gate or post-result policy — and the base `next()` is dispatch-with-normalization so a wrapper never sees a raw tool throw.
 - Multiple `tools/execute` listeners compose by ordinary Cordis waterfall order: a listener that calls `next()` wraps downstream listeners plus dispatch; one that returns without `next()` short-circuits them. A deployment combining timeout with a future retry/sandbox/metrics wrapper chooses semantics by registration order ("timeout covers the whole retry" vs "timeout covers each attempt").
 - Opt-in by declaration is a deliberate misconfiguration risk: a tool can declare a `timeoutMs` without honoring `exec.signal`, and that tool will not stop on timeout. The registry awaits that non-quiescent body rather than racing it, while the plugin contract states that declaring a budget means cooperative; the web tools prove the pattern on tools that already forward the signal.
 - During the transition `bash` and the migrated web tools use different timeout paths on purpose: `TOOL_TIMEOUT` is the model-facing tool-call budget, while `BASH_TIMEOUT` remains the bash backend timeout used by bash and hooks.
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index f6a85c13a6..6d10b552b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -32,7 +32,7 @@ ctx.tools.execute(exec)
 
 默认行为是保守的：未声明 `timeoutMs` 的工具不会从该插件收到 `TOOL_TIMEOUT` 截止信号。
 
-### `tools/execute` 环绕 seam
+### `tools/execute` 环绕分发扩展点
 
 `@deepseek-ai/dsh-tools` 声明了一个 `tools/execute` waterfall，其基础 `next()` 是带规范化的分发 thunk——即同一个内部 `try`/`catch`，将抛出的工具错误（或未知工具错误）转换为 `isError` 的 `ToolExecutionResult`。监听器接收 `(exec, next)`：调用 `next()` 委托给分发（返回其结果，可选地包装），或返回替代结果以短路分发。整个流水线仍位于 `execute` 的外层 try/catch 内，因此抛出异常的监听器会变成 `isError` 结果，而非轮次失败。
 
@@ -101,13 +101,13 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 **让 `timeout-policy` 自行匹配工具参数。** 诸如「当 `bash.run_in_background` 为 true 时禁用超时」之类的规则引擎会让策略插件了解工具特定的参数语义。通过不将 bash 迁移到工具调用超时来规避此问题。
 
-**使用 `tools/pre-execute` 加 `tools/post-execute` 代替新的环绕 seam。** pre 监听器可以启动截止时间并修改 `exec.signal`；post 监听器可以分类并替换。这样做的问题是截止时间的生命周期会跨越两个独立的 waterfall：需要 call-id 映射、在每条 pre-deny/tool-throw/post-throw/dispose（资源释放）路径上清理，以及与其他监听器的排序规则。`tools/pre-execute` 也是允许/拒绝门禁，而非执行包装器。`tools/execute` 给超时一个词法作用域：启动、委托、分类、释放。
+**使用 `tools/pre-execute` 加 `tools/post-execute` 代替新的环绕分发扩展点。** pre 监听器可以启动截止时间并修改 `exec.signal`；post 监听器可以分类并替换。这样做的问题是截止时间的生命周期会跨越两个独立的 waterfall：需要 call-id 映射、在每条 pre-deny/tool-throw/post-throw/dispose（资源释放）路径上清理，以及与其他监听器的排序规则。`tools/pre-execute` 也是允许/拒绝门禁，而非执行包装器。`tools/execute` 给超时一个词法作用域：启动、委托、分类、释放。
 
 **使用 `Promise.race` 对非协作工具强制超时。** 与超时库 Agent Note 相同的理由否决：它在底层进程、fetch 或提供方操作可能仍在运行时就将控制权返回给调用方。插件只发送信号；终止仍是实现方的责任。
 
 ## 后果
 
-- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发接口。其约定是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
+- `@deepseek-ai/dsh-tools` 在拦截点有意拆分 pre/post 工具钩子之后，获得了一个环绕分发接口。其约定是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
 - 多个 `tools/execute` 监听器按普通 Cordis waterfall 顺序组合：调用 `next()` 的监听器包装下游监听器加分发；不调用 `next()` 直接返回的监听器短路它们。一个同时组合超时与未来重试/沙箱/指标包装器的部署通过注册顺序选择语义（「超时覆盖整个重试」vs「超时覆盖每次尝试」）。
 - 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件约定声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
 - 过渡期间 `bash` 和已迁移的 web 工具有意使用不同的超时路径：`TOOL_TIMEOUT` 是面向模型的工具调用预算，而 `BASH_TIMEOUT` 仍是 bash 和钩子使用的 bash 后端超时。
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
index dbac0c0688..34abd78451 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.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 .agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
-2026-07-08-tool-output-spill-files.md: 7c0ca90452645d251559be25108d12883210d00e
-2026-07-08-tool-output-spill-files.zh.md: 628023a9d12fec17d32749f9d17a3b701ca3a475
+2026-07-08-tool-output-spill-files.md: 0c8e5e25fc8a229db8fca36512ba781e548b5256
+2026-07-08-tool-output-spill-files.zh.md: 771253335bf5822cb855c63e7dd0bbf0d517bab3
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
index 7c0ca90452..0c8e5e25fc 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
@@ -22,7 +22,7 @@ A thin spill storage seam plus a default spill policy plugin, in a new `packages
 | `@deepseek-ai/dsh-spill-local` | Local backend: private, session-scoped file storage on the host filesystem. |
 | `@deepseek-ai/dsh-spill-policy` | Tool-result policy plugin: wraps final text results after dispatch and replaces oversized results with a retained preview plus a spill locator. |
 
-There is no dedicated model-facing consumer package. The consumer is the existing `ctx.tools` execution pipeline: `dsh-spill-policy` consumes final tool results through the `tools/post-execute` waterfall, and the model follows the backend-supplied retrieval hint for the returned locator.
+There is no dedicated model-facing Consumer package. The Consumer is the existing `ctx.tools` execution pipeline: `dsh-spill-policy` consumes final tool results through the `tools/post-execute` waterfall, and the model follows the backend-supplied retrieval hint for the returned locator.
 
 ### Spill seam
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
index 628023a9d1..771253335b 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 | `@deepseek-ai/dsh-spill-local` | 本地后端：在宿主文件系统中提供私有、会话作用域的文件存储。 |
 | `@deepseek-ai/dsh-spill-policy` | 工具结果策略插件：包装分发后的最终文本结果，并以保留预览和落盘定位符替换超大结果。 |
 
-系统不增加专用的面向模型消费方包。消费方是现有 `ctx.tools` 执行流水线：`dsh-spill-policy` 通过 `tools/post-execute` waterfall（瀑布式事件）使用最终工具结果，模型则按照后端随定位符返回的检索提示读取内容。
+系统不增加专用的面向模型 Consumer 包。Consumer 是现有 `ctx.tools` 执行流水线：`dsh-spill-policy` 通过 `tools/post-execute` waterfall（瀑布式事件）使用最终工具结果，模型则按照后端随定位符返回的检索提示读取内容。
 
 ### 落盘 seam
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index 2330a5df0c..d658f71140 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.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 .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6f18d5da014f35b47c40c541ca75ca5ab81499b2
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 7b6ce75b145e96e58a49331e0390f1d3f82200e4
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 08715d3ad6ad7a2346327861e7134b10da184f00
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 77b57274d0d931f0ec58fecd3d5f9ca5bba3f624
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
index 6f18d5da01..08715d3ad6 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-10-after-call-compaction-pressure-and-overflow-recove
 
 ## Problem
 
-`agent/pre-step` runs before final request routing and before assistant output, tool results, buffered context, and steering exist. Even with the assembled prompt and session prefix, its pressure view is provisional because `agent/request` can still change routing or call configuration and tool schemas are not frozen with those inputs. Adding fields cannot make pre-call state describe a completed call and couples the generic seam to compaction.
+`agent/pre-step` runs before final request routing and before assistant output, tool results, buffered context, and steering exist. Even with the assembled prompt and session prefix, its pressure view is provisional because `agent/request` can still change routing or call configuration and tool schemas are not frozen with those inputs. Adding fields cannot make pre-call state describe a completed call and couples the generic extension point to compaction.
 
 Successful calls are not the only pressure signal. A provider can reject a request for exceeding its context window before it returns usage, and some successful calls omit usage. The system therefore needs replayable post-call pressure plus a narrow failure-recovery path that preserves the provider error whenever compaction cannot prove useful progress.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index 7b6ce75b14..77b57274d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`agent/pre-step` 运行在最终请求路由之前，也早于 assistant 输出、工具结果、缓冲上下文与 steering（中途引导）的产生。即使它接收已装配提示词与会话前缀，压力视图仍是临时的，因为 `agent/request` 还可以改变路由或调用配置，工具 schema 也没有与这些输入一同冻结。增加字段无法让调用前状态描述已完成调用，还会把通用 seam 与压缩耦合。
+`agent/pre-step` 运行在最终请求路由之前，也早于 assistant 输出、工具结果、缓冲上下文与 steering（中途引导）的产生。即使它接收已装配提示词与会话前缀，压力视图仍是临时的，因为 `agent/request` 还可以改变路由或调用配置，工具 schema 也没有与这些输入一同冻结。增加字段无法让调用前状态描述已完成调用，还会把通用扩展点与压缩耦合。
 
 成功调用也不是唯一的压力信号。提供方可能在返回 usage 之前就因上下文窗口超限拒绝请求，一些成功调用也不提供 usage。因此，系统需要可回放的调用后压力，以及一条狭窄的失败恢复路径；当压缩无法证明取得有效进展时，必须保留原始提供方错误。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index dcdf18b494..91deb7153c 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.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 .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
-2026-07-12-agent-scope-runtime-design.md: b8f265551c4ebbb94d32b3599959fe6cc4da974d
-2026-07-12-agent-scope-runtime-design.zh.md: 51fc92fcc6da21b163122984f6e2b102b2e65521
+2026-07-12-agent-scope-runtime-design.md: 8903a2fefa83dba042f8105b182e590783a9adde
+2026-07-12-agent-scope-runtime-design.zh.md: d86ab3d8cb9a051d4664aedac812b10b53521f22
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index b8f265551c..8903a2fefa 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -226,7 +226,7 @@ After post-execute or outer pipeline normalization, the registry losslessly snap
 
 SystemPrompt first resolves the global-plus-agent sections, variables, and tool providers into a deterministic registry contribution. The scope-filtered `system-prompt/assemble` waterfall may then reorder, replace, add, or remove any section, variable, or schema. Its returned assembly is authoritative; there is no later restoration pass and no finality metadata on ordinary prompt sections, tool definitions, or provider results.
 
-This is a trusted same-process extension seam, not an authority boundary. A listener that changes Code Mode's `run_code` schema or `tools:sdk` instructions, or a structured child's capture schema or instruction, owns preserving a coherent protocol in the assembly it returns. ToolRegistry still reserves `run_code` against ordinary tool registration and restriction because those are registry invariants, but assembly middleware remains free to transform the final model-visible surface.
+This is a trusted same-process extension point, not an authority boundary. A listener that changes Code Mode's `run_code` schema or `tools:sdk` instructions, or a structured child's capture schema or instruction, owns preserving a coherent protocol in the assembly it returns. ToolRegistry still reserves `run_code` against ordinary tool registration and restriction because those are registry invariants, but assembly middleware remains free to transform the final model-visible surface.
 
 Scope solves the real isolation problem directly. Structured-output contributions register in the child's exact scope, while Code Mode derives its transport and SDK from the same resolved tool view. A second named-protection system would need another ownership and collision rule across arbitrary schema providers—including providers that intentionally contribute duplicate names—without creating a new trust boundary.
 
@@ -360,7 +360,7 @@ This splits provider acceptance from publication and forces every consumer to re
 
 ### Restore selected prompt or tool contributions after assembly
 
-A post-waterfall restoration pass would create a second composition rule after the documented cooperative seam. Correctly assigning canonical presence or absence would also require provider ownership and collision rules for arbitrary tool-schema providers, whose ordinary output may contain duplicate names. Scoped registration already supplies the required per-agent isolation, and trusted assembly listeners own the protocol consistency of what they return, so named restoration adds machinery without establishing an independent boundary.
+A post-waterfall restoration pass would create a second composition rule after the documented cooperative waterfall. Correctly assigning canonical presence or absence would also require provider ownership and collision rules for arbitrary tool-schema providers, whose ordinary output may contain duplicate names. Scoped registration already supplies the required per-agent isolation, and trusted assembly listeners own the protocol consistency of what they return, so named restoration adds machinery without establishing an independent boundary.
 
 ### Remove worker/process lifecycle guards with same-process hardening
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index 51fc92fcc6..d86ab3d8cb 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -226,7 +226,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 SystemPrompt 首先将全局加 agent 的段、变量和工具提供方解析为确定性的注册表贡献。作用域过滤的 `system-prompt/assemble` waterfall 随后可以重排、替换、添加或移除任何段、变量或 schema。其返回的组装结果即为权威；没有后续的恢复步骤，普通提示词段、工具定义或提供方结果上也没有终态元数据。
 
-这是一个可信的同进程扩展 seam，而非权限边界。修改 Code Mode 的 `run_code` schema 或 `tools:sdk` 指令，或结构化子级的捕获 schema 或指令的监听器，有责任在其返回的组装中保持协议的一致性。ToolRegistry 仍然保留 `run_code` 不受普通工具注册和限制影响，因为那些是注册表不变式，但 assembly 中间件仍然可以自由变换最终的模型可见表面。
+这是一个可信的同进程扩展点，而非权限边界。修改 Code Mode 的 `run_code` schema 或 `tools:sdk` 指令，或结构化子级的捕获 schema 或指令的监听器，有责任在其返回的组装中保持协议的一致性。ToolRegistry 仍然保留 `run_code` 不受普通工具注册和限制影响，因为那些是注册表不变式，但 assembly 中间件仍然可以自由变换最终的模型可见表面。
 
 Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子级的精确作用域中，而 Code Mode 从同一个已解析的工具视图派生其传输和 SDK。第二套命名保护系统需要另一套所有权和碰撞规则来覆盖任意 schema 提供方（包括有意贡献重复名称的提供方），却不创建新的信任边界。
 
@@ -360,7 +360,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 在 assembly 之后恢复选定的提示词或工具贡献
 
-Waterfall 之后的恢复步骤会在文档化的协作式 seam 之后创建第二套组合规则。正确分配规范的存在或缺失还需要为任意工具 schema 提供方制定所有权和碰撞规则，而这些提供方的普通输出可能包含重复名称。作用域注册已经提供了所需的按 agent 隔离，可信的 assembly 监听器拥有其返回内容的协议一致性，因此命名恢复增加了机制却不建立独立边界。
+Waterfall 之后的恢复步骤会在文档化的协作式 waterfall 之后创建第二套组合规则。正确分配规范的存在或缺失还需要为任意工具 schema 提供方制定所有权和碰撞规则，而这些提供方的普通输出可能包含重复名称。作用域注册已经提供了所需的按 agent 隔离，可信的 assembly 监听器拥有其返回内容的协议一致性，因此命名恢复增加了机制却不建立独立边界。
 
 ### 用同进程加固替代 worker/进程生命周期守卫
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index 6ed066b24a..dd7ff64291 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.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 .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: bb516a39b6c7303d125575bbd3d4138f9af65f7d
-2026-07-14-provider-routed-llm-adapters.zh.md: 2b6af0d509c28cb79dcd3342a007be8e54799ebc
+2026-07-14-provider-routed-llm-adapters.md: 8bd34126d05140e486cd170bfc9255f0962dc413
+2026-07-14-provider-routed-llm-adapters.zh.md: 09d9032da5845d3e416dcfa047fde8e6527025b4
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index bb516a39b6..8bd34126d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -28,7 +28,7 @@ A provider has exactly one adapter owner in a Cordis context. `dsh-llm-deepseek`
 
 ### Explicit pi-ai provider profiles
 
-`dsh-llm-pi-ai` takes one non-empty list of provider profiles. Provider names must be unique within the list and present in pi-ai's `getProviders()` result. Each profile contains the provider name plus optional `apiKey`, `baseURL`, headers, reasoning level and budgets, cache retention, transport, SDK timeouts, a Harness stream-idle timeout, and a provider-owned `retryPolicy`. The adapter forces pi-ai's `maxRetries` to zero so one `stream()` call makes one visible provider attempt, while `dsh-llm-retry` executes the resolved policy at the agent failed-step seam. Credentials are never global: an explicit key applies only to its profile, while an absent key lets pi-ai resolve its standard environment variable, OAuth token, AWS credential chain, Google ADC, or other provider-native ambient authentication. An explicitly empty key is invalid configuration rather than an environment fallback.
+`dsh-llm-pi-ai` takes one non-empty list of provider profiles. Provider names must be unique within the list and present in pi-ai's `getProviders()` result. Each profile contains the provider name plus optional `apiKey`, `baseURL`, headers, reasoning level and budgets, cache retention, transport, SDK timeouts, a Harness stream-idle timeout, and a provider-owned `retryPolicy`. The adapter forces pi-ai's `maxRetries` to zero so one `stream()` call makes one visible provider attempt, while `dsh-llm-retry` executes the resolved policy at the agent failed-step extension point. Credentials are never global: an explicit key applies only to its profile, while an absent key lets pi-ai resolve its standard environment variable, OAuth token, AWS credential chain, Google ADC, or other provider-native ambient authentication. An explicitly empty key is invalid configuration rather than an environment fallback.
 
 The plugin registers all configured provider names against one `PiAiAdapter` in one all-or-nothing call. A request uses its provider to select the matching profile and finds its model in `getModels(provider)` to obtain the catalog descriptor. An unknown provider fails at plugin load; an unknown model fails before network I/O with `UNKNOWN_MODEL`. The catalog object is never mutated. When a profile supplies `baseURL`, the adapter clones the selected descriptor and overrides only `baseUrl`, so a private endpoint can retain pi-ai's API, capabilities, compatibility flags, context limits, and reasoning map. The private endpoint must implement the selected provider's protocol, and the model id must still exist in the installed pi-ai catalog.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index 2b6af0d509..09d9032da5 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ### 显式 pi-ai 提供方配置
 
-`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、Harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤 seam 上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
+`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、Harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤扩展点上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
 
 插件通过一次全有或全无调用，将所有已配置的提供方名称注册到同一个 `PiAiAdapter`。请求按 provider 选择对应配置，并在 `getModels(provider)` 中查找模型以取得目录描述符。未知提供方会在插件加载时失败；未知模型会在网络 I/O 前以 `UNKNOWN_MODEL` 失败。适配器不会修改目录对象。当配置提供 `baseURL` 时，适配器复制选中的描述符，仅覆盖 `baseUrl`，使私有端点保留 pi-ai 的 API、能力、兼容标志、上下文限制与推理映射。私有端点必须实现所选提供方的协议，模型 ID 也仍须存在于已安装的 pi-ai 目录中。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
index f38ba32c11..02d531f642 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.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 .agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
-2026-07-15-llm-model-catalog-and-acp-selection.md: 41174209d2c44bedb5dd0615c5f877ecebd43639
-2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 43442487649f7a552d66bd66b64e0e5072f5e00b
+2026-07-15-llm-model-catalog-and-acp-selection.md: 77f8e379e2b07ecf4e67fa7197752543cfedd6dd
+2026-07-15-llm-model-catalog-and-acp-selection.zh.md: ce4a04a66e345834bc2b16b743be89dc7a0b9424
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
index 41174209d2..77f8e379e2 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-15-llm-model-catalog-and-acp-selection.zh.md)
 
 ## Problem
 
-Provider-routed adapters let every request choose `provider + model`, but `LlmService` exposed only routing and streaming. A UI could not discover which providers were registered or which models an adapter was prepared to recommend. ACP clients therefore received no `model` session config option, so Zed, JetBrains, and VS Code integrations had no model list even though the request seam already supported runtime switching.
+Provider-routed adapters let every request choose `provider + model`, but `LlmService` exposed only routing and streaming. A UI could not discover which providers were registered or which models an adapter was prepared to recommend. ACP clients therefore received no `model` session config option, so Zed, JetBrains, and VS Code integrations had no model list even though the LLM service already supported runtime switching.
 
 Model discovery cannot become request validation. The hand-written DeepSeek adapter deliberately forwards arbitrary model ids to a public or private endpoint, while pi-ai has a finite installed catalog that is authoritative for its own request resolution. Treating one shared catalog as a whitelist would remove the private-endpoint behavior that provider routing was designed to preserve.
 
@@ -50,7 +50,7 @@ The request header remains the durable source of truth. When a selection is actu
 
 ## Consequences
 
-- Any adapter can expose a dynamic model list without leaking provider-library types into the core seam.
+- Any adapter can expose a dynamic model list without leaking provider-library types into the LLM Service Definition.
 - Catalog consumers must treat absence as “not advertised,” never “invalid request.”
 - pi-ai adapters expose their installed provider catalogs; hand-written DeepSeek deployments list known choices explicitly and retain arbitrary model support.
 - Human-facing catalog consumers own their selection interaction. ACP uses its fixed deployment target and does not widen the protocol with model discovery.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
index 4344248764..ce4a04a66e 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-基于提供方路由的适配器允许每次请求选择 `provider + model`，但 `LlmService` 只暴露路由和流式调用。UI 无法发现已注册的提供方，也无法知道适配器愿意推荐哪些模型。因此，ACP 客户端收不到 `model` 会话配置项；即使请求 seam 已经支持运行时切换，Zed、JetBrains 和 VS Code 集成仍没有模型列表。
+基于提供方路由的适配器允许每次请求选择 `provider + model`，但 `LlmService` 只暴露路由和流式调用。UI 无法发现已注册的提供方，也无法知道适配器愿意推荐哪些模型。因此，ACP 客户端收不到 `model` 会话配置项；即使 LLM 服务已经支持运行时切换，Zed、JetBrains 和 VS Code 集成仍没有模型列表。
 
 模型发现不能变成请求校验。手写 DeepSeek 适配器会把任意模型 ID 原样转发给公开或私有端点，而 pi-ai 的有限安装目录则是其自身请求解析的权威依据。将共享目录视为白名单，会破坏提供方路由需要保留的私有端点能力。
 
@@ -50,7 +50,7 @@ ACP 自动化传输层不是目录消费方。它通过部署配置为新创建
 
 ## 结果
 
-- 任意适配器都能暴露动态模型列表，无需把提供方库类型泄漏到核心 seam。
+- 任意适配器都能暴露动态模型列表，无需把提供方库类型泄漏到 LLM Service Definition。
 - 目录消费方必须把缺失理解为「未展示」，而不是「请求无效」。
 - pi-ai 适配器会暴露其已安装的提供方目录；手写 DeepSeek 部署显式列出已知选项，同时保留对任意模型的支持。
 - 面向人类的目录消费方拥有各自的选择交互。ACP 使用固定部署目标，不会为模型发现扩大协议范围。
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index ebf474f78b..03b17f5f33 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 63cec0a4e349ffc5be27a84e955b15e9168f898b
-2026-07-15-lsp-capability-seam.zh.md: fa82e29e0252b612ae38357c363478f1cbad9ead
+2026-07-15-lsp-capability-seam.md: 65d547a51568cca43fd8b2887bfe9a61c512b34d
+2026-07-15-lsp-capability-seam.zh.md: a9dcedaa80742bb338dbca4c0c532ca6e7cb2655
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 63cec0a4e3..65d547a515 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -79,7 +79,7 @@ interface LspService {
 
 Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's canonical workspace URI so consumers relativize file URIs in the execution world's namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
 
-`dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their interface packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
+`dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their Service Definition packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
 
 ## Model-facing contract
 
@@ -155,7 +155,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 
 **Expose `resolve(request)` / `query(spec)`.** With no defaulted fields, resolution would only expose provider selection, and a public spec could outlive provider disposal or replacement. One operation keeps selection and invocation atomic to the registration lifetime.
 
-**Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
+**Wrap the signal in an LSP execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
 
 **Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider consumes streamed full text directly through the same `ctx.fs` execution world used by its subprocess.
 
@@ -178,7 +178,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 - Registry tests pin atomic reservation/release, order-independent selection, and structured unavailable, disposed, conflict, and unsupported-operation errors.
 - Fake-stdio tests pin exact initialization capabilities, four protocol mappings, `Location`/`LocationLink` and hover normalization, and `findReferences` mapping to `references.includeDeclaration`.
 - Synchronization tests pin UTF-16 negotiation and conversion, supported and rejected `textDocumentSync` forms, blocked and failed open writes, balanced transient open/close, close-write failure, and malformed-response rejection.
-- Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden seam deadline, and bounded awaited teardown.
+- Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden LSP deadline, and bounded awaited teardown.
 - Lifecycle tests pin startup single-flight, complete-lifecycle serialization with fresh queued source reads, cross-workspace parallelism, abortable queues, crash replacement without replay, failed-stdin teardown, and quiescent disposal.
 - Filesystem-host tests pin session-cwd requirements, provider-owned containment and URI rendering, bounded document reads, unformatted source, and no `fs/observed` event.
 - A keyless pinned TypeScript real-server e2e exercises all four operations; runnable configuration uses the same explicit provider mapping.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index fa82e29e02..a9dcedaa80 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -79,7 +79,7 @@ interface LspService {
 
 映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方的规范工作区 URI，使消费方在执行世界的命名空间内相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
 
-`dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
+`dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的 Service Definition 包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
 ## 面向模型的约定
 
@@ -155,7 +155,7 @@ interface LspToolInput {
 
 **公开 `resolve(request)` / `query(spec)`。** 没有需要填充默认值的字段时，resolve 只会暴露提供方选择，而公开 spec 可能活过提供方释放或替换。单一操作让选择与调用共用注册生命周期。
 
-**将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
+**将信号包装为 LSP 执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
 
 **通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境消费流式传输的完整文本。
 
@@ -178,7 +178,7 @@ interface LspToolInput {
 - 注册表测试固定原子占用/释放、不受顺序影响的选择，以及结构化的不可用、已释放、冲突和不支持操作错误。
 - 测试用 stdio server 固定精确的初始化能力、四种协议映射、`Location`/`LocationLink` 与 `hover` 归一化，以及 `findReferences` 到 `references.includeDeclaration` 的映射。
 - 同步测试固定 UTF-16 协商与转换、受支持和被拒绝的 `textDocumentSync` 形式、打开写入阻塞与失败、配对的临时打开/关闭、关闭写入失败和错误响应拒绝。
-- 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、服务边界无隐藏截止时间，以及受限且等待完成的清理。
+- 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、LSP 无隐藏截止时间，以及受限且等待完成的清理。
 - 生命周期测试固定启动 single-flight、完整生命周期串行化及排队查询读取最新源文件、跨工作区并行、可取消队列、崩溃后不重放的替换、stdin 失败后的进程拆除，以及释放后完全停稳。
 - 文件系统宿主测试固定 session cwd 要求、提供方自有的 containment 与 URI 渲染、有界文档读取、无格式源文本和不发送 `fs/observed`。
 - 无密钥且固定版本的 TypeScript 真实服务器 e2e 覆盖四种操作；可运行配置使用同一项显式提供方映射。
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index f683189f93..19f77344e1 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.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 .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
-2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
-2026-07-16-explicit-turn-cancellation.zh.md: 0b9a06c0ae340a41eab9d6bff6126996bfc63bcf
+2026-07-16-explicit-turn-cancellation.md: 5d7b5856ceebd3dc49564c1800004188da162fd8
+2026-07-16-explicit-turn-cancellation.zh.md: ba20b80f3c280087d71688ef4596fb075fa5782b
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
index 2b7cb8cc77..5d7b5856ce 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
@@ -12,7 +12,7 @@ The [initiating Agent scope decision](2026-07-15-agent-initiator-scope.md) inten
 
 ## Decision
 
-Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. TypeScript enforces that vocabulary at this typed same-process seam, with no runtime validator, fallback, or special compatibility contract for untyped callers. An active `TurnCancellation` copies the typed discriminant into a fresh frozen signal reason; idle cancellation has no holder to mutate and does not arm later work.
+Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. TypeScript enforces that vocabulary at this typed same-process boundary, with no runtime validator, fallback, or special compatibility contract for untyped callers. An active `TurnCancellation` copies the typed discriminant into a fresh frozen signal reason; idle cancellation has no holder to mutate and does not arm later work.
 
 An interrupted live turn ends with the coarse durable `{ kind: 'aborted' }` outcome. The terminal event records what happened to the turn, while the runtime signal identifies who requested cancellation; it does not duplicate `user` or `parent` into replay. Session seed/load rejects legacy aborted records with a reason or any other extra field, so replay cannot reintroduce caller-owned cancellation detail. The process-local `agent/cancel-requested` notification is not durable; a future audit requirement uses a separate durable control-request event so a request and its eventual outcome remain distinct. Durable events contain no stack, signal, error object, free-form cancellation text, or backend-private detail.
 
@@ -20,7 +20,7 @@ AgentLoop privately owns one `TurnCancellation` per prospective turn. It install
 
 The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer is latched and runs when the aborted activity converges to idle — a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
 
-The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining seams keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
+The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining APIs keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
 
 `ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a canonical frozen cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam.
 
@@ -46,10 +46,10 @@ Initiator-scope tests assert that every hook still observes the exact Agent and
 
 **Expose public turn or step context wrappers.** Existing seams already identify Agent, turn, and step. A wrapper would widen every API, duplicate ownership, and tempt callers to treat a captured object as durable authority.
 
-**Abandon uncooperative work after a grace period.** Returning idle while same-process work still runs breaks teardown and resource-ownership guarantees. Hard termination requires a worker or process isolation boundary and is outside this control seam.
+**Abandon uncooperative work after a grace period.** Returning idle while same-process work still runs breaks teardown and resource-ownership guarantees. Hard termination requires a worker or process isolation boundary and is outside this control boundary.
 
 ## Consequences
 
-Cancellation has one runtime owner, one signal per live turn, and one typed runtime caller vocabulary. Session retains the coarse `aborted` outcome that its consumers actually use, rejects reason-bearing legacy forms, and stays isolated from runtime objects. Cooperative cancellation reaches every asynchronous turn seam, including work before the first step and after the last one, while terminal publication and persistence remain outside its authority.
+Cancellation has one runtime owner, one signal per live turn, and one typed runtime caller vocabulary. Session retains the coarse `aborted` outcome that its consumers actually use, rejects reason-bearing legacy forms, and stays isolated from runtime objects. Cooperative cancellation reaches every asynchronous turn extension point, including work before the first step and after the last one, while terminal publication and persistence remain outside its authority.
 
 The explicit signal adds parameters to several public events and requires plugins to forward cancellation deliberately. This is intentional: authority is visible at the call boundary, lifetime matches the turn, and stale ambient descendants cannot acquire control. Uncooperative in-process work may delay cancellation, but the reported quiescent state remains truthful.
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index 0b9a06c0ae..ba20b80f3c 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程 seam 中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
+Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程边界中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
 
 正在运行的轮次被中断后，以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么，运行时 signal 标识谁请求了取消；回放不会重复保存 `user` 或 `parent`。会话 seed/load 会拒绝携带取消原因或任何其他额外字段的旧式中止记录，因此回放无法重新引入由调用方持有的取消细节。仅限进程内的 `agent/cancel-requested` 通知不会持久化；未来若有审计需求，应使用独立的持久化控制请求事件，让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。
 
@@ -20,7 +20,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它
 
 对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
-显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。步骤前处理入口、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
+显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 API 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
 `ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
 
@@ -30,7 +30,7 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 ## 验证
 
-约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在步骤前处理、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
+约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
 
 发起方作用域测试断言所有钩子仍观察到同一个 Agent 且没有环境中的轮次 signal，并发 Agent 保持独立的身份与 signal，嵌套子驱动只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的完全停稳。
 
@@ -46,10 +46,10 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 **公开轮次或步骤上下文包装类型。** 现有 seam 已经标识 Agent、轮次和步骤。包装类型会加宽所有 API、重复归属，并诱导调用方把捕获的对象当成持久权限。
 
-**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就报告空闲状态，会破坏资源清理与资源归属保证。硬终止需要 worker 或进程隔离边界，不属于该控制 seam。
+**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就报告空闲状态，会破坏资源清理与资源归属保证。硬终止需要 worker 或进程隔离边界，不属于该控制边界。
 
 ## 后果
 
-取消拥有一个运行时归属方、每个活跃轮次一个 signal，以及一套类型化的运行时调用方词汇。会话保留其消费方实际使用的粗粒度 `aborted` 结果，拒绝携带原因的旧式形式，并与运行时对象保持隔离。协作式取消覆盖每个异步轮次 seam，包括第一个步骤之前和最后一个步骤之后的工作，而终态发布和持久化仍在其权限范围之外。
+取消拥有一个运行时归属方、每个活跃轮次一个 signal，以及一套类型化的运行时调用方词汇。会话保留其消费方实际使用的粗粒度 `aborted` 结果，拒绝携带原因的旧式形式，并与运行时对象保持隔离。协作式取消覆盖每个异步轮次扩展点，包括第一个步骤之前和最后一个步骤之后的工作，而终态发布和持久化仍在其权限范围之外。
 
 显式 signal 会给多个公开事件增加参数，并要求插件有意识地转发取消。这是有意设计：权限在调用边界可见，生命周期与轮次匹配，陈旧的环境异步后代无法获得控制能力。不协作的进程内工作可能延迟取消，但所报告的完全停稳仍然真实。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index a0956af598..a1f8d14b76 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.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 .agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
-2026-07-19-cooperative-tool-cancellation.md: 4e82452cd6883593d4693766bea803c97fa4c977
-2026-07-19-cooperative-tool-cancellation.zh.md: aa94fd9f3d32167dc7d6b906ff14a6afd36ccb32
+2026-07-19-cooperative-tool-cancellation.md: 781202688a5cbcd7076ee694fc7dd9489683d8e8
+2026-07-19-cooperative-tool-cancellation.zh.md: 8e61d6fb4eb99c5d6726e1b1af15765b84c34b03
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
index 4e82452cd6..781202688a 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
@@ -42,7 +42,7 @@ The registry first creates the call token, snapshots the visible definition's op
 
 Once a tool body starts, the registry awaits it. Cancellation reaches the body through the fused signal but never races or abandons its promise. A cooperative implementation stops or forwards cancellation and settles after its owned work reaches quiescence; an uncooperative same-process implementation can keep the registry pending indefinitely. Process, worker, network, and provider layers retain responsibility for their own termination mechanisms.
 
-This decision requires cancellation at the tool invocation seam only. Making signals required on asynchronous capabilities reachable from tool bodies is a separate migration proposed in [Required cancellation through tool-reachable capability seams](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md).
+This decision requires cancellation at the tool invocation boundary only. Making signals required on asynchronous capabilities reachable from tool bodies is a separate migration proposed in [Required cancellation through tool-reachable capability seams](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md).
 
 ## Verification
 
@@ -54,7 +54,7 @@ No registry test can prove that arbitrary third-party same-process code observes
 
 **Keep the signal optional and synthesize a fallback.** Rejected because a registry-owned fallback has no caller lifetime to represent and preserves the exact omission the type should prevent.
 
-**Validate `AbortSignal` at runtime.** Rejected because this is a typed same-process seam, not a serialization boundary. Runtime checks would duplicate the static contract without making cooperative use enforceable.
+**Validate `AbortSignal` at runtime.** Rejected because this is a typed same-process boundary, not a serialization boundary. Runtime checks would duplicate the static contract without making cooperative use enforceable.
 
 **Add `supportsCancellation` metadata, callback-arity checks, or signal-use linting.** Rejected because none proves that asynchronous work observes or correctly forwards cancellation. Availability is a type contract; behavior remains a tool and capability responsibility.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index aa94fd9f3d..8e61d6fb4e 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -42,7 +42,7 @@ Status: implemented
 
 工具主体一旦启动，注册表就会等待它完成。取消通过融合信号到达工具主体，但注册表不会与其 promise 竞速或丢弃该 promise。协作式实现会停止自身工作或继续转发取消，并在所持有的工作完全停稳后完成；不协作的同进程实现可能让注册表无限期保持等待。进程、worker、网络和提供方层仍负责各自的终止机制。
 
-这项决策只要求工具调用 seam 携带取消信号。让工具主体可达的异步能力也必须接收信号，属于另一项迁移，见提议中的[工具可达能力 seam 中的必填取消](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md)。
+这项决策只要求工具调用边界携带取消信号。让工具主体可达的异步能力也必须接收信号，属于另一项迁移，见提议中的[工具可达能力 seam 中的必填取消](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md)。
 
 ## 验证
 
@@ -54,7 +54,7 @@ Status: implemented
 
 **保留可选信号并生成后备值。** 不予采纳，因为注册表持有的后备信号不代表任何调用方生命周期，也会保留类型系统本应阻止的缺失情况。
 
-**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程 seam，不是序列化边界。运行时检查只会重复静态约定，仍无法强制实现协作式使用信号。
+**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程边界，不是序列化边界。运行时检查只会重复静态约定，仍无法强制实现协作式使用信号。
 
 **添加 `supportsCancellation` 元数据、回调参数数量检查或信号使用 lint。** 不予采纳，因为这些方法都无法证明异步工作会观察或正确转发取消。信号可用性属于类型约定；具体行为仍由工具和能力负责。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index c7f632c50e..4632c7e1ac 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: ceb8e5db593aef14d6db259f6293381fe83defe2
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: bc0b6a9e883a1ce7d2990f8dc7284035649ac215
+2026-07-19-gui-layering-and-rpc-protocol.md: ebab36e66768f6216603923d2313e77eaf412ae1
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 308446e48772c3bb8d6e0b5851dd526af641593a
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index ceb8e5db59..ebab36e667 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -175,7 +175,7 @@ Two logical streams: the mux stream (`/api/events.mux`, all-session aggregate) a
 |---|---|---|
 | `session/event` | `{ sessionId; event: SessionEvent }` | core passthrough: core events pass verbatim, `assistant/chunk` IS the token stream, no separate delta frame |
 
-The remaining frame types are not re-copied here; the full unions are `MuxFrame`/`HostFrame` in `api/events.ts`. Three semantic points to know: `session/subscribed` carries lastSeq for history seam-race detection; the `approval/question` requested frames are answerable (stable rpcId) and the resolved frames are the convergence surface; `host/agent-error` is the only outlet for live failures with no turn position.
+The remaining frame types are not re-copied here; the full unions are `MuxFrame`/`HostFrame` in `api/events.ts`. Three semantic points to know: `session/subscribed` carries lastSeq for history-race detection; the `approval/question` requested frames are answerable (stable rpcId) and the resolved frames are the convergence surface; `host/agent-error` is the only outlet for live failures with no turn position.
 
 **Passthrough discipline**: events/messages/content blocks on the wire ARE the core types (`SessionEvent`/`ContentBlock`) — no second DTO set; types reach the browser through the `import type` dependency chain. `SessionEventMap` is merge-extensible: the client applies its documented default (ignore) to unknown types, and the event schema keeps a "valid envelope + unknown type" branch — the envelope stays strict; this is not field-level passthrough.
 
@@ -183,11 +183,11 @@ The remaining frame types are not re-copied here; the full unions are `MuxFrame`
 
 - **History = event replay**: one fold (client side); history pagination and live increments share one code path; the server maintains no second materialized-snapshot system. History **page boundaries align to message boundaries** (never cut mid-message; chunks group with their finalized message), and the tail page includes the in-flight partial's chunks.
 - **Prompt correlation**: the prompt's rpcId rides MessageSource (`'user-rpc'`) into the `user/message` event; the client uses it to promote the optimistic echo.
-- **Reconnect = rebuild**: no resume cursor (`mux`'s `since` signature is a reserved seat, ignored if passed); on disconnect reopen the stream + refetch history; compare `subscribed.lastSeq` with the history tail seq and backfill once if there is a seam.
+- **Reconnect = rebuild**: no resume cursor (`mux`'s `since` signature is a reserved seat, ignored if passed); on disconnect reopen the stream + refetch history; compare `subscribed.lastSeq` with the history tail seq and backfill once if there is a gap.
 - **Cold session handling follows ownership**: `session.history` and the source read for `session.fork` inspect persistence without an Agent, while Agent-bound ordinary-session methods such as `prompt` resume through a deduplicated in-flight table. Session-backed subagents reject that generic resume path, and attachment status is not exposed to clients (`running` already covers it).
 - **Approvals/questions**: the requested frame mints a stable rpcId on acceptance; first answer wins, and the host's in-memory pending table (keyed by rpcId) is the only referee; after a mux reopen, still-pending requested frames replay after the subscribed frame (rpcId reused verbatim — refresh recovery). The audit events `approval/asked`/`decided` continue through the durable log — frames = the live control plane, events = the durable audit. **Status**: the contract and frame types are shipped; the host-side pending table/wire answerer is unimplemented (`respond` in `api-proxy.ts` is a stub, always `not-pending`); PendingCard v1 is display-only.
 - **No protocol version**: client and host release bound together; `host.describe` has no protocolVersion field; introduce one when an independently released client appears.
-- **Reserved-seam discipline**: the map holds only implemented methods; an unknown method fails loud at envelope parse (`bad-request`) — no not-implemented fallback code. The reservation list (implementing = copy the signature into the domain interface + add the map row + add the schema pair): `session.fork`, `prompt.mode` gaining `'inject'`, `task.list`, `host.listModels`, describe gaining `hostInstanceId`. (`session.rename` graduated from this list: it appends a user-source `session/title` event.)
+- **Reserved-method discipline**: the map holds only implemented methods; an unknown method fails loud at envelope parse (`bad-request`) — no not-implemented fallback code. The reservation list (implementing = copy the signature into the domain interface + add the map row + add the schema pair): `session.fork`, `prompt.mode` gaining `'inject'`, `task.list`, `host.listModels`, describe gaining `hostInstanceId`. (`session.rename` graduated from this list: it appends a user-source `session/title` event.)
 
 ## The client carrier: the AbstractApiClient class family (`fetch/client.ts`)
 
@@ -230,11 +230,11 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 **Plug in a new carrier**: subclass `AbstractApiClient` implementing only `doFetch`; to intercept at the protocol layer (like the fixture), override the `callUnary`/`openMux`/`openHost` virtuals instead. Contract and base class stay unchanged.
 
-**Promote a reserved seam**: copy the reserved signature into the domain interface → add the map row → add the schema pair → add the UNARY_ROUTES row → implement.
+**Promote a reserved method**: copy the reserved signature into the domain interface → add the map row → add the schema pair → add the UNARY_ROUTES row → implement.
 
 ## Consequences
 
-Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. Ordinary unary calls remain bounded, while `host.pickDirectory` and `command.execute` may stay pending until the operation finishes or caller/connection cancellation arrives; this accepts that a non-cooperative user-paced operation can hang its request rather than treating valid operation duration as transport failure. The other accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved seams (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
+Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. Ordinary unary calls remain bounded, while `host.pickDirectory` and `command.execute` may stay pending until the operation finishes or caller/connection cancellation arrives; this accepts that a non-cooperative user-paced operation can hang its request rather than treating valid operation duration as transport failure. The other accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved methods (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index bc0b6a9e88..308446e487 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -173,7 +173,7 @@ export type ResponseValue<K> =
 |---|---|---|
 | `session/event` | `{ sessionId; event: SessionEvent }` | 核心透传：core 事件原样过，`assistant/chunk` 即 token 流，无独立 delta 帧 |
 
-其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缝竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
+其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
 
 **透传纪律**：wire 上的事件/消息/内容块就是 core 类型（`SessionEvent`/`ContentBlock`），不造第二套 DTO；类型经 `import type` 依赖链直达浏览器。`SessionEventMap` merge-extensible：client 对未知 type documented-default（忽略），事件 schema 留「合法信封+未知类型」分支——信封仍严格，不是字段级 passthrough。
 
@@ -185,7 +185,7 @@ export type ResponseValue<K> =
 - **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 Agent 的情况下检查持久化存储，而绑定到 Agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
 - **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：约定与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
 - **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
-- **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
+- **预留方法纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
 
 ## 客户端载体：AbstractApiClient 类体系（`fetch/client.ts`）
 
@@ -228,11 +228,11 @@ export type ResponseValue<K> =
 
 **接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。约定与基类零改。
 
-**升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
+**升格一个预留方法**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
 
 ## Consequences
 
-所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留方法（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 5523e6d3b2..b7e331c934 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
-2026-07-19-gui-web-client-architecture.zh.md: 10779107a9dc6dc7335b2c5932c8c4877b531b50
+2026-07-19-gui-web-client-architecture.md: 7567ac3cb8b1a580e145f8f0da49b6ec371a35bd
+2026-07-19-gui-web-client-architecture.zh.md: 9b682febf1bd1aad1a767b8b2db4e83dd993cf2f
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index e25d002b92..7567ac3cb8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -30,7 +30,7 @@ Both ends run cordis. The host is a cordis plugin tree; the browser runs a secon
 
 ## The client cordis tree and the loading chain
 
-The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` seam; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
+The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` contract; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
 
 Type universes stay split at the aggregate level — `tsconfig.host.json` is the host program and `tsconfig.client.json` the client program, both referenced by the solution root `tsconfig.json` — because both sides merge cordis `Context` under the same keys (`sessions`, `loader`) with different services; client packages consume the wire vocabulary through pure type subpaths (`@deepseek-ai/dsh-session/types` and kin) so no host augmentation rides into the client program.
 
@@ -42,7 +42,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 ## Services and scope addressing
 
-A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
+A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
 There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: Runtime projects Code Dispatch topology into each root's recursive `subCalls`; ui-conversation places that ordered root into the single `'conversation.chat.tool'` seat without interpreting Tool names or topology; ui-tool renders the supplied tree and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 10779107a9..9b682febf1 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 ## client cordis 树与装载链
 
-装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` seam；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
+装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` 约定；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
 类型宇宙在聚合层拆分——`tsconfig.host.json` 是 host program、`tsconfig.client.json` 是 client program，二者由 solution 根 `tsconfig.json` 引用，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
 
@@ -42,7 +42,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 ## 服务与 scope 寻址
 
-服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
+服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装约定）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
 slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
index 6af30fd423..9a1610a341 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.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 .agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
-2026-07-19-package-invariant-runtime-contracts.md: 86d86f69b606c348e85d1ae654b6b35c4326985a
-2026-07-19-package-invariant-runtime-contracts.zh.md: 94d332a34c1d6e681c10832ea4deb559d88b21a6
+2026-07-19-package-invariant-runtime-contracts.md: c1a5aa1e55965b07b34ce307375d77e75cdeb9be
+2026-07-19-package-invariant-runtime-contracts.zh.md: 29fc2ecf2937b7557e16d972ad71230c0e304617
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
index 86d86f69b6..c1a5aa1e55 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-19-package-invariant-runtime-contracts.zh.md)
 
 ## Problem
 
-The package-owned invariant seam made publication and registration exhaustive, but its first generated baseline accepted empty installers. A follow-up then replaced those empties with generic assertions about plugin names, injections, effects, service methods, and fixed pure-library examples. Those assertions made every companion executable without making the system safer: TypeScript, Cordis startup, package tests, and module-load tests already enforce those shapes, while the invariant service should detect impossible runtime state.
+The package-owned invariant service made publication and registration exhaustive, but its first generated baseline accepted empty installers. A follow-up then replaced those empties with generic assertions about plugin names, injections, effects, service methods, and fixed pure-library examples. Those assertions made every companion executable without making the system safer: TypeScript, Cordis startup, package tests, and module-load tests already enforce those shapes, while the invariant service should detect impossible runtime state.
 
 A useful runtime invariant relates observations over time or across a mutable data structure. Examples include a terminal event without its start, an LLM delta for a block that is not open, or a durable result whose identity differs from its request. Merely confirming that a declared method exists, that a plugin has its expected name, or that a constant example still returns a known value is not such a relation.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
index 94d332a34c..29fc2ecf29 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-包自有不变量 seam 让发布和注册实现了全覆盖，但最初的生成基线允许空安装器。后续方案又用针对插件名称、注入、effect、服务方法和纯工具库中的固定示例的通用断言替代这些空实现。这些断言虽然让每个 companion 都能执行，却没有提高系统安全性：TypeScript、Cordis 启动、包测试和模块加载测试已经约束这些形状，而不变量服务应当发现不可能出现的运行时状态。
+包自有不变量服务让发布和注册实现了全覆盖，但最初的生成基线允许空安装器。后续方案又用针对插件名称、注入、effect、服务方法和纯工具库中的固定示例的通用断言替代这些空实现。这些断言虽然让每个 companion 都能执行，却没有提高系统安全性：TypeScript、Cordis 启动、包测试和模块加载测试已经约束这些形状，而不变量服务应当发现不可能出现的运行时状态。
 
 有用的运行时不变量会关联时间上的多个观测，或关联可变数据结构中的多个部分。例如：终止事件没有对应的开始事件、LLM（大语言模型）delta 指向未打开的块，或持久化结果的身份与请求不同。仅确认声明的方法存在、插件名称符合预期，或常量示例仍返回已知值，都不属于这种关系。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index ad5f67e601..a6875e43df 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.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 .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
-2026-07-19-package-owned-invariant-service.md: 6ab53f1a9bfa043f17875fa179a99b832b3fcf1a
-2026-07-19-package-owned-invariant-service.zh.md: 378b730c479eed05a2ad11e6a6e084929ec09653
+2026-07-19-package-owned-invariant-service.md: 296c55b21b947d32412acff54715d3687cf9c43b
+2026-07-19-package-owned-invariant-service.zh.md: 8aa776feabdef84a4007dc317115e6d72f6bbc50
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
index 6ab53f1a9b..296c55b21b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -1,4 +1,4 @@
-# Agent Note: Package-owned invariant service seam
+# Agent Note: Package-owned invariant service contract
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index 378b730c47..8aa776feab 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 包拥有的不变式服务 seam
+# Agent Note: 包拥有的不变式服务约定
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml
index 20abdeec64..9223e938a7 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.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 .agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
-2026-07-20-routed-model-context-and-compaction-policy.md: 6a2626d4eea3e30533199320b6b0ed5b05e7fd28
-2026-07-20-routed-model-context-and-compaction-policy.zh.md: 128563718554e2f8ed49f933aceb77cb18623dee
+2026-07-20-routed-model-context-and-compaction-policy.md: 630c259e5bbf6edc46cc837aedb627e673dc71f2
+2026-07-20-routed-model-context-and-compaction-policy.zh.md: ba2b5286995cb735baf9821294b8b5e0e625da5a
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
index 6a2626d4ee..630c259e5b 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
@@ -28,7 +28,7 @@ Compact-basic owns consumer policy. Top-level fields define defaults; `modelPoli
 
 For proactive pressure, compact-basic reads the latest durable request route, resolves its adapter capacity and exact-target policy, and scales ratios into a `ResolvedCompactSpec`. It performs this resolution on every check, so a provider or model switch in one session changes capacity and policy immediately. An absolute retained budget that is not below the scaled threshold fails when the target capacity first makes that comparison possible.
 
-The same exact-target override can select summarization provider/model, summarization output cap, convergence retries, and overflow retry cap. These are compaction concerns and never enter the adapter seam.
+The same exact-target override can select summarization provider/model, summarization output cap, convergence retries, and overflow retry cap. These are compaction concerns and never enter an LLM provider.
 
 ### Target-specific pressure failures preserve optional composition
 
@@ -48,7 +48,7 @@ Service tests cover detached context metadata, invalid adapter output, catalog i
 
 ## Consequences
 
-- Capacity has one authoritative owner at the provider seam, while compaction policy stays in the optional consuming plugin.
+- Capacity has one authoritative owner at the provider contract, while compaction policy stays in the optional consuming plugin.
 - The same compact-basic instance safely handles different windows, provider switches, and identical model ids under different providers without consulting discovery metadata.
 - LLM-only and meter-only compositions remain valid; loading compact-basic adds no reverse dependency from adapters.
 - DeepSeek deployments may set exact per-model capacities, or use `defaultContextWindow` for entries without capacity and unlisted pass-through ids.
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
index 1285637185..ba2b528699 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
@@ -28,7 +28,7 @@ Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolici
 
 对于主动压力检查，compact-basic 读取最新持久请求路由，解析其适配器容量与精确目标策略，再把比例缩放为 `ResolvedCompactSpec`。每次检查都会重新解析，因此同一会话切换提供方或模型后，容量与策略会立即变化。若绝对保留预算不小于缩放后的阈值，系统会在目标容量首次允许比较两者时失败。
 
-同一精确目标覆盖还可以选择摘要提供方/模型、摘要输出上限、收敛重试次数与溢出重试上限。这些都属于压缩问题，不会进入适配器 seam。
+同一精确目标覆盖还可以选择摘要提供方/模型、摘要输出上限、收敛重试次数与溢出重试上限。这些都属于压缩问题，不会进入任何 LLM 提供方。
 
 ### 目标专用压力错误仍保留可选组合
 
@@ -48,7 +48,7 @@ Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolici
 
 ## 后果
 
-- 容量在提供方 seam 上拥有唯一权威归属方，而压缩策略留在可选消费插件中。
+- 容量在提供方约定上拥有唯一权威归属方，而压缩策略留在可选消费插件中。
 - 同一个 compact-basic 实例无需查询发现元数据，就能安全处理不同窗口、提供方切换，以及不同提供方下的相同模型 id。
 - 仅 LLM 与仅 meter 的组合仍然有效；加载 compact-basic 不会让适配器产生反向依赖。
 - DeepSeek 部署可以设置精确的逐模型容量，也可以让未提供容量的模型项与未列出的透传 id 使用 `defaultContextWindow`。
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
index 7c13de5842..be5e4be24f 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.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 .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
-2026-07-22-slot-type-chain-implementation.md: 2f0ec32766100e492c68c474f8798be3df0a3d15
-2026-07-22-slot-type-chain-implementation.zh.md: 6ef7eaa7614b88b33f0fa2aa6089e97eb3a45c25
+2026-07-22-slot-type-chain-implementation.md: 9930aaa62bd4b1f37dac9736517524b7e01b1746
+2026-07-22-slot-type-chain-implementation.zh.md: 2778d223cd89b4394bd629661dbb58105e6655cb
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
index 2f0ec32766..9930aaa62b 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
@@ -88,11 +88,11 @@ An inject factory takes what its declarations earn it — `sessionId` for sessio
 
 Hooks are framework-made only: `useSession`, `useSessions`, `useWorkspaces`, `useStore`, `renderSlot` plus the hooks bound from provide contributions and inject `hooks` compartments — every one synthesized by the renderer's single binding machinery; business code passes plain data and callbacks between parent and child (a component's own behavioral hooks that subscribe to nothing external remain fine). Live data has exactly three channels: what the parent knows travels as owner props at the renderSlot site; what only the component knows is local state; what must be shared across entries or survive remounts is a declared store. Derivation is a pure function over framework-hook data (`useMemo`), never a subscription of its own.
 
-### Tree context and the renderer seam
+### Tree context and the renderer contract
 
 `SessionProvider` is a framework component **delivered as a standard-kit seat**: an entry whose `children` declare a session-scope slot receives it as a prop (type in ui-slots, value injected by the renderer) — components never value-import it. It is self-wired (it reads the runtime's current-session state internally; the assembler passes nothing), render-prop shaped — `children(sessionId)` with an `empty` branch, remounting under `key={sessionId}`. `BindingContext` is machinery-internal; business components see zero React contexts. Inject factories execute inside the outlet on purpose (per-entry error boundaries catch them; a crashing registrant blacks out only its own entry while assembly errors rethrow); the outlet reads tree context as a machinery-only implicit parameter — the "identity from the register closure, situation from the tree position" split.
 
-Rendering lives behind an install seam so the runtime stays React-free: `SlotRenderer` (interface in ui-slots, implementation `createSlotRenderer()` in web-react) is installed once at shell boot via `ctx.slots.install(...)`; double install and render-before-install throw. Ownership bookkeeping is a single `Map<key, entry>` in the service — ledger, slots, contributions, render bindings, and store instances all live and die on the one entry axis, which closes the stale-authority window across plugin reloads by construction (a disposed entry's captured `renderSlot` throws a stale-authorization error on entry).
+Rendering lives behind an installation contract so the runtime stays React-free: `SlotRenderer` (interface in ui-slots, implementation `createSlotRenderer()` in web-react) is installed once at shell boot via `ctx.slots.install(...)`; double install and render-before-install throw. Ownership bookkeeping is a single `Map<key, entry>` in the service — ledger, slots, contributions, render bindings, and store instances all live and die on the one entry axis, which closes the stale-authority window across plugin reloads by construction (a disposed entry's captured `renderSlot` throws a stale-authorization error on entry).
 
 ### Type-chain implementation rulings
 
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
index 6ef7eaa761..2778d223cd 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
@@ -88,11 +88,11 @@ inject 工厂只接收其声明所授权的形参——session slot 获得 `sess
 
 hook 只许框架造：`useSession`、`useSessions`、`useWorkspaces`、`useStore`、`renderSlot` 五席，加上 provide 贡献与 inject `hooks` 格绑出的 hook——全部出自渲染器同一台绑定机械；业务代码在父子组件之间只传普通数据与回调（组件自用、不订阅任何外部数据源的行为 hook 不在此限）。活数据恰有三条通道：父知道的，作为 owner props 在 renderSlot 现场传入；只有组件自己知道的，是本地 state；需要跨 entry 共享或跨重挂载存活的，是声明的 store。派生是对框架 hook 数据做纯函数（`useMemo`），绝不自成一路订阅。
 
-### 树上语境与渲染器安装缝
+### 树上语境与渲染器约定
 
 `SessionProvider` 是框架组件，**以标配 slot 形式送达**：`children` 里声明了 session scope slot 的 entry 经 prop 收到它（类型住 ui-slots，值由渲染器注入）——组件永不对它做值 import。它框架自接线（内部自读 runtime 的当前会话状态，装配方零传参），render-prop 形——`children(sessionId)` 外加 `empty` 分支，以 `key={sessionId}` 重挂。`BindingContext` 属机械内部；业务组件可见的 React Context 为零。inject 工厂有意在 outlet 内部执行（per-entry 错误边界接得住它们；崩溃的注册方只黑掉自己那一格，装配错误则重抛）；outlet 将树上下文作为仅供框架机制使用的隐式参数读取——即「身份出自 register 闭包、现场出自树位置」的分工。
 
-渲染位于一个 install seam 之后，因此 runtime 不依赖 React：`SlotRenderer`（接口住 ui-slots，实现 `createSlotRenderer()` 住 web-react）在壳 boot 时经 `ctx.slots.install(...)` 安装一次；双重安装与安装前渲染均 throw。归属记账是服务里的单一 `Map<key, entry>`——账本、slot、贡献、渲染绑定、store 实例全部沿同一条 entry 轴生灭，跨插件重载的陈旧权威窗口由此在构造上关闭（已 dispose 的 entry 所捕获的 `renderSlot`，一进入口即抛陈旧授权（stale-authorization）错误）。
+渲染位于一份安装约定之后，因此 runtime 不依赖 React：`SlotRenderer`（接口住 ui-slots，实现 `createSlotRenderer()` 住 web-react）在壳 boot 时经 `ctx.slots.install(...)` 安装一次；双重安装与安装前渲染均 throw。归属记账是服务里的单一 `Map<key, entry>`——账本、slot、贡献、渲染绑定、store 实例全部沿同一条 entry 轴生灭，跨插件重载的陈旧权威窗口由此在构造上关闭（已 dispose 的 entry 所捕获的 `renderSlot`，一进入口即抛陈旧授权（stale-authorization）错误）。
 
 ### 类型链实现裁定
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index 33ff739db9..7c4e3bef22 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.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 .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
-2026-07-23-client-plugin-loading-model.md: 2dc0c68e5f20bd790c2362f92c16dece171babf5
-2026-07-23-client-plugin-loading-model.zh.md: abe62f4c03147cc4716103e531adb812f073e622
+2026-07-23-client-plugin-loading-model.md: 302363fcb03a7aa2438b9d97d4e3405db7d6ce8d
+2026-07-23-client-plugin-loading-model.zh.md: 23061a9800b21ada64ef1a3c205c588a9406b67d
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
index 2dc0c68e5f..302363fcb0 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-23-client-plugin-loading-model.zh.md)
 
 ## Problem
 
-On the host, cordis plugin loading stands on Node's module machinery — the require cache and the internal ESM loader own module identity and bytes. The vendored `@cordisjs/plugin-loader` implements plugin governance and hot reload on top of that substrate, and the two meet at one seam: `Loader.internal`.
+On the host, cordis plugin loading stands on Node's module machinery — the require cache and the internal ESM loader own module identity and bytes. The vendored `@cordisjs/plugin-loader` implements plugin governance and hot reload on top of that substrate, and the two meet at one boundary: `Loader.internal`.
 
 The browser client runs the same cordis plugin mechanism, so it needs the same substrate underneath — and the browser has no Node module system.
 
@@ -16,7 +16,7 @@ Conventional frontend engineering digests all dependencies at build time: one bu
 
 The lower layer supplies four capabilities: externals (the platform list), remote arrival (same-origin external classic scripts plus lazy factory registration), versioning (content-hash revs), and hot update (invalidate/prefetch).
 
-Plugin bundles are built independently outside Vite's module graph. Feeding response text into an inline script leaves the browser with a dynamic source execution: no standard source-map chain connects the network resource, generated bundle, and TypeScript/TSX source, so performance profiles and stacks stop at generated `client.js`; the module system must also buffer the complete source and split one arrival responsibility across fetch and execute transport seams.
+Plugin bundles are built independently outside Vite's module graph. Feeding response text into an inline script leaves the browser with a dynamic source execution: no standard source-map chain connects the network resource, generated bundle, and TypeScript/TSX source, so performance profiles and stacks stop at generated `client.js`; the module system must also buffer the complete source and split one arrival responsibility across fetch and execute transport boundaries.
 
 On top of that, client and host plugins register and load consistently: a package declares `dshClient` once, the host scans the declaration into the boot graph, and the same Loader semantics govern entries on both sides.
 
@@ -35,7 +35,7 @@ The manifest owns the package's loading contract: its `inject` dependency edges,
 
 To add a plugin package: declare `dshClient`, emit the `./client` bundle through the shared preset, add the name to the composing app's roster. Nothing else changes hands.
 
-When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (will receive the slots machinery now living in runtime — SlotsService, the renderer seam, the root slot), web-react (will take the renderer install into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
+When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (will receive the slots machinery now living in runtime — SlotsService, the renderer contract, the root slot), web-react (will take the renderer install into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
 
 Four edge rules govern imports across the two kinds. None of them depends on any per-package mark:
 
@@ -50,7 +50,7 @@ The browser mirrors the host's division of labor. `dsh-client-modules` (`ClientM
 
 `ClientModuleSystem` is a lazy CJS table. Executing a bundle only **registers** its factory — the bundle calls `window.__ModuleLoader__.load({ id, factory })` and nothing else happens. Every module body side effect, CSS injection included, lives inside the factory closure and runs at materialization: the first `require`/import of that id, memoized after that. A factory that requires a registered-but-unmaterialized sibling materializes it recursively, so no sort order exists anywhere. When asked to import an id, the table resolves through a fixed branch order: seed word → memoized record → static registration (shell-own modules, e.g. app-shell) → registered factory → graph-row external classic-script load → loud throw. That final throw is the runtime mirror of the build-time purity gate. The system also keeps per-module bookkeeping — owned `<style data-plugin>` tag ids, observed require edges — and exposes the two verbs HMR needs: `prefetch(id)` (load the script and register its factory; concurrent calls share one in-flight task) and `invalidate(id)` (drop the factory and record so the next arrival reloads it).
 
-The vendored Loader consumes the module system through its `internal` seam — the only call site is `tree.import` — and owns everything entry-shaped: entry creation, fiber activation through cordis service waiting (PENDING until injected services exist, cascading when a service is provided), update/refresh, teardown. The governance code is byte-identical to the host side, per vendor policy. Browserization is compile-time mapping in the shell's vite config: a `node:module` stub alias plus `process.*` defines make `ModuleLoader.fromInternal()` return undefined — exactly the empty slot the shell fills. The module system mounts as `ctx.modules`.
+The vendored Loader consumes the module system through its `internal` contract — the only call site is `tree.import` — and owns everything entry-shaped: entry creation, fiber activation through cordis service waiting (PENDING until injected services exist, cascading when a service is provided), update/refresh, teardown. The governance code is byte-identical to the host side, per vendor policy. Browserization is compile-time mapping in the shell's vite config: a `node:module` stub alias plus `process.*` defines make `ModuleLoader.fromInternal()` return undefined — exactly the empty slot the shell fills. The module system mounts as `ctx.modules`.
 
 ### External-script arrival and source maps
 
@@ -122,7 +122,7 @@ The support boundary, stated honestly. Reload is coarse by design: fresh fiber,
 
 ## Consequences
 
-One governance implementation runs on both sides of the wire; the browser-specific surface is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` seam.
+One governance implementation runs on both sides of the wire; the browser-specific surface is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` hook.
 
 Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch surfaces at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
 
@@ -139,5 +139,5 @@ Roster endgame (landed 2026-07-25 with the config-tree boot move): the roster li
 | Import maps | Ruled out earlier; the DI require table is the terminal mechanism |
 | Full ctx-ification now (react and libraries via services, no module table) | The module-axis extreme; parked — the upgrade law walks there one package at a time instead |
 | Eager instantiation with a frozen table | Requires arrival-time ordering; lazy CJS registration makes recursive `require` self-ordering and matches the naive-puller phase split |
-| Fetch response text, then inject an inline `<script>` | Makes the module system buffer the complete source and maintain separate fetch/execute seams; dynamic source execution also breaks the browser-native association among the network resource, source map, and profile |
+| Fetch response text, then inject an inline `<script>` | Makes the module system buffer the complete source and maintain separate fetch/execute paths; dynamic source execution also breaks the browser-native association among the network resource, source map, and profile |
 | Builder-push rebuild channel (`POST /plugins/rebuilt` from the orchestrator's `onSuccess`) | Couples reload to one blessed builder process and a second wire protocol; the webserver already holds every bundle path, and stat polling covers the torn-write race (re-hash on every stat change) that once justified pushing |
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index abe62f4c03..23061a9800 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## Problem
 
-host 侧，cordis 插件装载站在 Node 的模块机制之上——require cache 与内部 ESM loader 拥有模块身份与字节。vendored `@cordisjs/plugin-loader` 在这层基座之上实现插件治理与热重载，二者在唯一一道 seam 相接：`Loader.internal`。
+host 侧，cordis 插件装载站在 Node 的模块机制之上——require cache 与内部 ESM loader 拥有模块身份与字节。vendored `@cordisjs/plugin-loader` 在这层基座之上实现插件治理与热重载，二者在唯一一道边界相接：`Loader.internal`。
 
 浏览器客户端跑同一套 cordis 插件机制，因此底下需要同样的基座——而浏览器没有 Node 模块系统。
 
@@ -16,7 +16,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 
 下层供给四项能力：external（平台清单）、远程到达（同源外部 classic script 加惰性工厂登记）、版本化（内容哈希 rev）、热更新（invalidate/prefetch）。
 
-插件 bundle 独立构建在 Vite 模块图之外。若把响应文本塞进内联 script，浏览器只能看到一次动态源码执行：网络资源、生成 bundle、TypeScript/TSX 源码之间没有标准 sourcemap 链，性能 profile 与 stack 只能落到生成后的 `client.js`；模块系统还要持有整份源码文本，并把同一项到达职责拆成 fetch 与 execute 两道传输 seam。
+插件 bundle 独立构建在 Vite 模块图之外。若把响应文本塞进内联 script，浏览器只能看到一次动态源码执行：网络资源、生成 bundle、TypeScript/TSX 源码之间没有标准 sourcemap 链，性能 profile 与 stack 只能落到生成后的 `client.js`；模块系统还要持有整份源码文本，并把同一项到达职责拆成 fetch 与 execute 两道传输边界。
 
 在此之上，client 与 host 插件以一致的方式注册与装载：包声明一次 `dshClient`，host 把声明扫描进 boot 图，同一套 Loader 语义在两侧治理 entry。
 
@@ -35,7 +35,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
-普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器 seam、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
+普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器约定、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
 
 四条边规则治理横跨两类包的 import。没有一条依赖任何单包标记：
 
@@ -50,7 +50,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 `ClientModuleSystem` 是一张 lazy CJS 表。执行 bundle 只**登记**其工厂——bundle 调用 `window.__ModuleLoader__.load({ id, factory })`，此外什么都不发生。模块体的一切副作用（包括 CSS 注入）都住在工厂闭包里，在物化时运行：物化即该 id 的首次 `require`/import，此后记忆化。工厂若 require 一个已登记未物化的同伴，就递归物化它，因此任何地方都不存在排序。被要求 import 一个 id 时，表按固定分支顺序解析：种子词条 → 记忆化的记录 → 静态登记（壳自有模块，如 app-shell）→ 已登记的工厂 → 图行外部 classic script 加载 → 大声抛错。最后这一抛是构建期纯度门禁在运行期的镜像。系统还保管逐模块的簿记——名下 `<style data-plugin>` 标签 id、观测到的 require 边——并暴露 HMR（热模块替换）需要的两个动词：`prefetch(id)`（加载脚本、只登记工厂；并发调用共享同一在途任务）与 `invalidate(id)`（丢弃工厂与记录，下次到达即重新加载）。
 
-vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点是 `tree.import`——并拥有一切 entry 形状的事务：entry 创建、fiber 经 cordis 服务等待的激活（注入的服务未就位即保持 PENDING，服务 provide 时级联激活）、update/refresh、拆除。治理代码按 vendor 政策与 host 侧逐字节相同。浏览器化是壳 vite 配置里的编译期映射：一个 `node:module` stub 别名加若干 `process.*` define，使 `ModuleLoader.fromInternal()` 返回 undefined——这正是留给壳来填的空槽。模块系统挂载为 `ctx.modules`。
+vendored Loader 经其 `internal` 约定消费模块系统——唯一调用点是 `tree.import`——并拥有一切 entry 形状的事务：entry 创建、fiber 经 cordis 服务等待的激活（注入的服务未就位即保持 PENDING，服务 provide 时级联激活）、update/refresh、拆除。治理代码按 vendor 政策与 host 侧逐字节相同。浏览器化是壳 vite 配置里的编译期映射：一个 `node:module` stub 别名加若干 `process.*` define，使 `ModuleLoader.fromInternal()` 返回 undefined——这正是留给壳来填的空槽。模块系统挂载为 `ctx.modules`。
 
 ### 外部脚本到达与源码映射
 
@@ -122,7 +122,7 @@ vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点
 
 ## Consequences
 
-wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模块系统加一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一道可替换的 `loadBundle` seam。
+wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模块系统加一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一个可替换的 `loadBundle` 钩子。
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
@@ -139,5 +139,5 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模
 | import map | 早已排除；DI require 表是终局机制 |
 | 现在就彻底 ctx 化（react 与库全走服务，不设模块表） | 模块轴上的极端形态；搁置——升级法则改为一次一包走向它 |
 | 冻结表 + 到达即实例化 | 要求按到达时刻排序；lazy CJS 登记让递归 `require` 自行定序，且与朴素拉取器的分层相合 |
-| fetch 响应文本后注入内联 `<script>` | 模块系统必须缓冲整份源码并维护 fetch/execute 两道 seam；动态源码执行也切断浏览器网络资源、sourcemap 与 profile 的原生关联 |
+| fetch 响应文本后注入内联 `<script>` | 模块系统必须缓冲整份源码并维护 fetch/execute 两条路径；动态源码执行也切断浏览器网络资源、sourcemap 与 profile 的原生关联 |
 | 构建器推送重建通道（编排器在 `onSuccess` 里 POST `/plugins/rebuilt`） | 把重载耦合到一个钦定的构建器进程和第二套 wire 协议；webserver 本就握有每个 bundle 路径，stat 轮询（每次 stat 变化即重哈希）已兜住当年为推送辩护的撕裂写竞态 |
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 06bfd11c4f..073a71d118 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.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 .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: cccc0b6d8f7309c5344e042d9cc2171587a18cb5
+2026-07-25-web-client-session-scope-and-provide-channel.md: 6e4c58c229cea9ff9f0e5ccf03b04c799755244b
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 4d4824f5596139523f5d5b94cb79ba9d1944ff15
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
index 3c51f06fca..6e4c58c229 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
@@ -116,7 +116,7 @@ Slot scope is the closed set `root | session-maybe | session`:
 |---|---|
 | A client-local Intent + materialize (published CAS / the pendingPrompt attach transaction / the before-create chain) | The client is forced to simulate the first half-life the host lacks, breeding a pile of state machinery — published CAS, the attach transaction, partial publication |
 | Host-reserved IDs (a draft Map) | The host merely acknowledges a number; the state machine stays on the client untouched |
-| A host draft Session (a Session without an Agent) | Every host surface that looks up the Agent must fork for drafts; core would need an attachAgent seam plus late-written header cwd |
+| A host draft Session (a Session without an Agent) | Every host surface that looks up the Agent must fork for drafts; core would need an `attachAgent` API plus late-written header cwd |
 | Binding an Agent before cwd (ungrouped) | Overturns the readonly header.cwd "created in" invariant, plus the launch-dir side-effect product trap |
 | Passing session context down through React Context | Plugins should hold one mental model across host and client; the scope mechanism is isomorphic to the host dsh-scope |
 | A `scopeTarget` carrier + fused dispatcher (mirroring the host `agentEvents`) | The host wrapper layer guards the business Agent subject against drifting from the scope key; client events have no subject to guard — the filter on the actx plus cordis primitives covers every need |
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index cccc0b6d8f..4d4824f559 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -116,7 +116,7 @@ slot scope 是闭集 `root | session-maybe | session`：
 |---|---|
 | client-local Intent + materialize（published CAS / pendingPrompt attach 事务 / before-create 链） | client 被迫模拟 host 缺失的前半段生命，养出 published CAS、attach 事务、部分发布一坨状态机 |
 | host 预留 ID（draft Map） | host 只认了个号，状态机原封留在 client |
-| host draft Session（有 Session 无 Agent） | 每个查 Agent 的 host 面都要为 draft 分叉；core 要开 attachAgent seam + header cwd 后写 |
+| host draft Session（有 Session 无 Agent） | 每个查 Agent 的 host 面都要为 draft 分叉；core 要新增 `attachAgent` API + header cwd 后写 |
 | 无 cwd 先绑 Agent（ungrouped） | header.cwd readonly「created in」不变性被推翻 + launch-dir 副作用产品坑 |
 | React Context 层层传会话语境 | 插件在 host/client 两侧应是一个心智模型；scope 机制与 host dsh-scope 同构 |
 | `scopeTarget` carrier + 融合派发器（镜像 host `agentEvents`） | host 包装层护的是「业务 Agent subject 与 scope key 不漂移」，client 事件无 subject 可护；filter 住 actx + cordis 原语覆盖全部需求 |
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index f805e7cde3..830661f8cd 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 8797102c65ebab663bcf72fced5791364fe2c6ae
-2026-07-26-subprocess-seam.zh.md: 8a7ff14079374d6d74a1ec729dd02c8961fa23e6
+2026-07-26-subprocess-seam.md: 378f941ead65ebdcacac665d31cd269e7a2e0565
+2026-07-26-subprocess-seam.zh.md: 4e085dcde46ef041985006019d3c6b98fed609c8
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 8797102c65..378f941ead 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,14 +12,14 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
-- **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
-- **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
+- **`@deepseek-ai/dsh-subprocess` (Service Definition)** — the abstract `SubprocessService` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The Service Definition also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (Service provider)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the Service Definition's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The provider has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their Consumers.
+- **`dsh-bash-local` (Consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
+- **`dsh-bash` (Service Definition)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash Consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
 Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-subprocess-local` (CLI, examples, python bundled runtime, create-sdk's bash feature resources, inline test configs).
 
-Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral seam shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
+Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral contract shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
 Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
 
@@ -33,7 +33,7 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 **Route every process launch through `ctx.subprocess`.** Rejected because the MCP SDK owns its transport spawn, the SDK wizard has no Cordis context and needs inherited redirection, the TUI probe is synchronous, and support launchers deliberately stay independent of product seams. PTY allocation did move behind `spawnTerminal()` because the provider, not the consumer, owns that substrate-specific primitive.
 
-**Put `run_in_background`/task semantics into the process seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The process seam sits *below* the bash executor, not beside the task registry.
+**Put `run_in_background`/task semantics into the subprocess capability seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The subprocess seam sits *below* the bash executor, not beside the task registry.
 
 **Move `ENV_OVERRIDES` (TERM=dumb, PAGER=cat …) into the subprocess service.** Rejected: a generic subprocess service must not impose terminal presentation policy on non-terminal consumers; the ambient scrub (credential-shaped and `DSH_*` names) is a security/identity invariant and stays, but terminal friendliness is the bash tool's choice, expressed through the spec's explicit env where a caller's own entry still wins.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 8a7ff14079..4e085dcde4 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,14 +12,14 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
-- **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
-- **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
+- **`@deepseek-ai/dsh-subprocess`（Service Definition）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 Service Definition 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（Service provider）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 Service Definition 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该 Service provider 没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自 Consumer 所有。
+- **`dsh-bash-local`（Consumer）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
+- **`dsh-bash`（Service Definition）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash Consumer 需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
 如今，每个加载 bash 执行器的组合都同时加载 `@deepseek-ai/dsh-subprocess-local`：CLI（命令行界面）、各示例、Python 捆绑运行时、create-sdk 的 bash 功能资源，以及各内联测试配置。
 
-后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
+后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为约定随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
 基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 **把每一次进程启动都路由到 `ctx.subprocess`。**否决：MCP SDK 拥有其传输 spawn，SDK 向导没有 Cordis 上下文且需要继承式重定向，TUI 探测是同步的，support 启动器则刻意独立于产品 seam。PTY 分配迁到 `spawnTerminal()`，因为这项底层专用原语归提供方而非消费方所有。
 
-**改把 `run_in_background`/任务语义放进进程 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。进程 seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
+**改把 `run_in_background`/任务语义放进 subprocess 能力 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。subprocess seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
 **把 `ENV_OVERRIDES`（TERM=dumb、PAGER=cat 等）移入管理器。**否决：通用进程管理器不得把终端呈现策略强加给非终端消费方；对环境中凭据形态名称与 `DSH_*` 名称的清除是安全与身份不变式，予以保留，但终端友好性是 bash 工具自己的选择，经 spec 的显式 env 表达，而调用方自己的条目依旧优先。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
index 6b969a2c03..fc8cf85334 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.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 .agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
-2026-07-26-task-registry-seam.md: 57ac176cf6d2b0a50fcbcfacd77f6a26b462b582
-2026-07-26-task-registry-seam.zh.md: b81940a8f778f1ed9a65bf96e3a66c047fd234c2
+2026-07-26-task-registry-seam.md: 45801505f1729ec6094900acf94b4c17ed92c3b1
+2026-07-26-task-registry-seam.zh.md: 8dd90b34d2da1d22caba13fe8c388dab4a29be0d
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
index 57ac176cf6..45801505f1 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
@@ -6,30 +6,30 @@ English | [中文](2026-07-26-task-registry-seam.zh.md)
 
 ## Problem
 
-The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and control surface programs against and the process-local implementation (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` surface producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the control surface (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the interface / implementation / consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
+The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and control surface programs against and the process-local provider (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` surface producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the control surface (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the Service Definition / Service provider / Consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
 
 ## Decision
 
 `tasks/` is now a three-package capability family in the bash-trio shape:
 
-- **`@deepseek-ai/dsh-tasks` (interface)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachSurface`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every implementation owes: registrations outlive producer and surface fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no control surface is attached.
-- **`@deepseek-ai/dsh-tasks-local` (implementation)** — `LocalTaskService`, the process-local registry moved verbatim: the in-memory store, per-kind counters, waiter bookkeeping, `TASK_WAIT_TIMEOUT` deadline code, owner-cleanup effects, and force-fail teardown. The `dsh-timeout` dependency moves here with it; the seam has no implementation dependencies.
-- **`@deepseek-ai/dsh-tool-tasks` (consumer)** — unchanged; it injects `'tasks'` and never imports implementation types.
+- **`@deepseek-ai/dsh-tasks` (Service Definition)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachSurface`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every Service provider owes: registrations outlive producer and surface fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no control surface is attached.
+- **`@deepseek-ai/dsh-tasks-local` (Service provider)** — `LocalTaskService`, the process-local registry moved verbatim: the in-memory store, per-kind counters, waiter bookkeeping, `TASK_WAIT_TIMEOUT` deadline code, owner-cleanup effects, and force-fail teardown. The `dsh-timeout` dependency moves here with it; the Service Definition package has no provider dependencies.
+- **`@deepseek-ai/dsh-tool-tasks` (Consumer)** — unchanged; it injects `'tasks'` and never imports provider types.
 
-Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks` — the seam that defines the absent `ctx.tasks` service — and the seam's own surfaces (its README and the direct-mount fence) point at implementations, so the producer message stays correct when another backend becomes the recommended default. Producers, `TaskKindMap` declaration merges, and the control surface keep importing `@deepseek-ai/dsh-tasks` only.
+Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks` — the Service Definition package that declares the absent `ctx.tasks` service — and the Service Definition package's own surfaces (its README and the direct-mount fence) point at Service providers, so the producer message stays correct when another backend becomes the recommended default. Producers, `TaskKindMap` declaration merges, and the control surface keep importing `@deepseek-ai/dsh-tasks` only.
 
-The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` still passes callbacks and exact `Agent` objects, so a durable or cross-process backend still has design work to do before it can implement this interface (identity, restart, ownership, observation). The split moves that future work out of every consumer's dependency graph; it does not pre-design the backend.
+The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` still passes callbacks and exact `Agent` objects, so a durable or cross-process backend still has design work to do before it can satisfy this Service Definition (identity, restart, ownership, observation). The split moves that future work out of every Consumer's dependency graph; it does not pre-design the backend.
 
 ## Alternatives considered
 
-**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting an interface before a second implementation risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the surface `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the seam package either way, and today they would also churn every consumer's implementation dependency.
+**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting a Service Definition before a second provider risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the surface `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the Service Definition package either way, and today they would also churn every Consumer's provider dependency.
 
-**Interface-only extraction inside one package (export an abstract class beside the concrete one).** Rejected because it separates nothing operationally: consumers still depend on the package that carries the implementation and its dependencies, and a replacement backend still cannot ship without the local one in its graph. The package boundary is the unit of independent evolution here.
+**Service-Definition-only extraction inside one package (export an abstract class beside the concrete one).** Rejected because it separates nothing operationally: Consumers still depend on the package that carries the provider and its dependencies, and a replacement backend still cannot ship without the local one in its graph. The package boundary is the unit of independent evolution here.
 
-**Splitting `types.ts` out but leaving the service concrete.** Rejected for the same reason — the types are not the seam; `ctx.tasks` and its method contract are. Producers need the service key and semantics, not just the shapes.
+**Splitting `types.ts` out but leaving the service concrete.** Rejected for the same reason — the types are not the complete capability; the `ctx.tasks` Service Definition and its method contract are. Producers need the service key and semantics, not just the shapes.
 
 ## Consequences
 
-Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling package implementing eight abstract methods, and no producer, control surface, or `TaskKindMap` extender changes when one lands. The seam README states the contract; the implementation README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the seam keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
+Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling Service provider implementing eight abstract methods, and no producer, control surface, or `TaskKindMap` extender changes when one lands. The Service Definition README states the contract; the provider README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the Service Definition package keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
 
-Cost: one more package (manifest, tsconfig, README, invariant companion), and compositions must name the implementation package. `abstract` erases at runtime and this package name used to be the mountable registry, so the seam constructor fails loudly when mounted directly — a stale composition row gets "load an implementation such as @deepseek-ai/dsh-tasks-local" at load time instead of a half-registered `ctx.tasks` failing far from the misconfiguration.
+Cost: one more package (manifest, tsconfig, README, invariant companion), and compositions must name the Service provider package. `abstract` erases at runtime and this package name used to be the mountable registry, so the Service Definition constructor fails loudly when mounted directly — a stale composition row gets "load a Service provider such as @deepseek-ai/dsh-tasks-local" at load time instead of a half-registered `ctx.tasks` failing far from the misconfiguration.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
index b81940a8f7..8dd90b34d2 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
@@ -6,30 +6,30 @@ Status: implemented
 
 ## 问题
 
-[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
+[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内 Service provider（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备 Service Definition / Service provider / Consumer 三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
 
 ## 决策
 
 `tasks/` 如今是一个 bash 三件套形态的三包能力家族：
 
-- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
-- **`@deepseek-ai/dsh-tasks-local`（实现）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；seam 包不含任何实现依赖。
-- **`@deepseek-ai/dsh-tool-tasks`（消费方）**——保持不变；它注入 `'tasks'`，从不导入实现类型。
+- **`@deepseek-ai/dsh-tasks`（Service Definition）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个 Service provider 都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
+- **`@deepseek-ai/dsh-tasks-local`（Service provider）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；Service Definition 包不含任何提供方依赖。
+- **`@deepseek-ai/dsh-tool-tasks`（Consumer）**——保持不变；它注入 `'tasks'`，从不导入提供方类型。
 
-各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即定义缺失的 `ctx.tasks` 服务的 seam 包；seam 自身的对外呈现（其 README 与直接挂载防线）会指向各实现，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
+各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即声明缺失的 `ctx.tasks` 服务的 Service Definition 包；Service Definition 包自身的对外呈现（其 README 与直接挂载防线）会指向各 Service provider，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
 
-该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
+该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能满足此 Service Definition 之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个 Consumer 的依赖图；它并不预先设计后端。
 
 ## 曾考虑的替代方案
 
-**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更约定）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里；而若维持现状，它们今天还会连带搅动每个消费方的实现依赖。
+**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二个 Service provider 出现前抽取 Service Definition，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更约定）不因这次拆分而改变：无论拆分与否，这类变更都会落在 Service Definition 包里；而若维持现状，它们今天还会连带搅动每个 Consumer 的提供方依赖。
 
-**在单个包内仅抽取接口（在具体类旁导出一个抽象类）。**否决，因为它在运作层面并未分离任何东西：消费方依然依赖携带实现及其依赖项的那个包，而替换后端若不把本地实现纳入自身依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
+**在单个包内仅抽取 Service Definition（在具体类旁导出一个抽象类）。**否决，因为它在运作层面并未分离任何东西：Consumer 依然依赖携带 Service provider 及其依赖项的那个包，而替换后端若不把本地 Service provider 纳入自身依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
 
-**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法约定才是。生产方需要的是服务键和语义，而不只是类型形状。
+**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是完整能力，`ctx.tasks` Service Definition 及其方法约定才是。生产方需要的是服务键和语义，而不只是类型形状。
 
 ## 后果
 
-换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级包，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述约定；生命周期簿记方面的事实归实现包的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
+换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级 Service provider，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。Service Definition 的 README 陈述约定；生命周期簿记方面的事实归 Service provider 的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；Service Definition 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
 
-代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名实现包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 seam 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load an implementation such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
+代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名 Service provider 包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 Service Definition 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load a Service provider such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index cf0c363672..16ec810666 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.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 .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
-2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
-2026-07-27-dispose-ladder-to-consumer.zh.md: afa385120d6ac33e6084a56585d8d610622e604c
+2026-07-27-dispose-ladder-to-consumer.md: 25deabe811f8eb361690fec2d4fdd40cdf23dd57
+2026-07-27-dispose-ladder-to-consumer.zh.md: 359f800c9c190b7af7c08bf1d7b9b5ebf275cbaf
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
index e9af88e8e7..25deabe811 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
@@ -14,10 +14,10 @@ The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(c
 
 ## Alternatives considered
 
-**Keep the ladder on the handle as a convenience.** Rejected: a seam method every implementation must provide is not a convenience, it is contract surface — and this one encodes one consumer's cooperation shape (stdin-EOF-first) as if it were process vocabulary. The seam's own README already had to caveat that children quiescing on other signals need "their own tier-1", which is the admission that the ladder is policy.
+**Keep the ladder on the handle as a convenience.** Rejected: a Service Definition method every Service provider must implement is not a convenience, it is contract surface — and this one encodes one consumer's cooperation shape (stdin-EOF-first) as if it were process vocabulary. The seam's own README already had to caveat that children quiescing on other signals need "their own tier-1", which is the admission that the ladder is policy.
 
 **Move the ladder to a shared helper package.** Rejected: one consumer. A second out-of-process backend with the same stdin-EOF cooperation shape can lift `disposeAcpChild` to shared code when it exists; extracting now would recreate `dsh-subagent-subprocess`, the single-purpose library this stack just deleted.
 
 ## Consequences
 
-Bought: the seam is one method and one type smaller; implementations owe four verbs and no teardown policy; the cooperative EOF window lives beside the ACP config field that tunes it, while the subprocess owner alone owns the termination window and final join. Cost: a future backend wanting EOF-first teardown writes ~20 lines against the verbs (or lifts the ACP helper); the ladder's tier tests live in the ACP suite, and the seam suite pins the verbs the ladder composes (bounded `waitForExit` false before escalation and an unbounded whole-tree join after it) instead of the composed policy.
+Bought: the Service Definition is one method and one type smaller; Service providers owe four verbs and no teardown policy; the cooperative EOF window lives beside the ACP config field that tunes it, while the subprocess owner alone owns the termination window and final join. Cost: a future backend wanting EOF-first teardown writes ~20 lines against the verbs (or lifts the ACP helper); the ladder's tier tests live in the ACP suite, and the Service Definition suite pins the verbs the ladder composes (bounded `waitForExit` false before escalation and an unbounded whole-tree join after it) instead of the composed policy.
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index afa385120d..359f800c9c 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -10,14 +10,14 @@ Status: implemented
 
 ## 决策
 
-阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程所有者证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的完全停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
+阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程责任方证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
 
 ## 曾考虑的替代方案
 
-**把阶梯作为便利方法留在句柄上。**否决：一个每个实现都必须提供的 seam 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
+**把阶梯作为便利方法留在句柄上。**否决：一个每个 Service provider 都必须实现的 Service Definition 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
 
 **把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——这组堆叠变更刚刚删掉的那个单一用途库。
 
 ## 后果
 
-换来的是：seam 少了一个方法和一个类型；实现只需提供四个动词，无需提供拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程所有者拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
+买到的：Service Definition 少了一个方法和一个类型；Service provider 只欠四个动词，不欠拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程责任方拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，Service Definition 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 018c4812b1..2ab9d7c12b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.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 .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
-2026-07-28-directory-picker-capability-seam.md: 01968990db81852dbf965a90fc151bab357ecb55
-2026-07-28-directory-picker-capability-seam.zh.md: f96f835c5f68d0ef6eff5410a7db18dc24eb8c2c
+2026-07-28-directory-picker-capability-seam.md: 898d8dc3a6fa41cfacc694f15c88d3a71c48f413
+2026-07-28-directory-picker-capability-seam.zh.md: fce9a801ad8535b264c91f6d3b32373e35cb146d
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
index 01968990db..898d8dc3a6 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-28-directory-picker-capability-seam.zh.md)
 
 ## Problem
 
-The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection seam). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the planned in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
+The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection point). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the planned in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
 
 ## Decision
 
-A three-package capability seam in `packages/host/` — `directory-picker` (interface), `directory-picker-native`, `directory-picker-browse` (backends) — with one contract method: `capability()` returns a **discriminated union**, `{ kind: 'native', pick(signal) }` or `{ kind: 'browse', list(path?), createDirectory(path, name) }`. The gateway (`dsh-host-apiproxy`) injects `directoryPicker`, serves the matching RPCs, and answers `directory-picker-unavailable` for the other kind. The union is discriminated because the backends differ in *interaction shape* — flattening them into one method set would force every backend to fake the other's shape.
+A three-package capability seam in `packages/host/` — `directory-picker` (Service Definition), `directory-picker-native`, `directory-picker-browse` (backends) — with one contract method: `capability()` returns a **discriminated union**, `{ kind: 'native', pick(signal) }` or `{ kind: 'browse', list(path?), createDirectory(path, name) }`. The gateway (`dsh-host-apiproxy`) injects `directoryPicker`, serves the matching RPCs, and answers `directory-picker-unavailable` for the other kind. The union is discriminated because the backends differ in *interaction shape* — flattening them into one method set would force every backend to fake the other's shape.
 
 **The client side is slot-composed, not advertisement-branched.** ui-workspace's two trigger surfaces each declare a `single` directory-flow hole (`conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`; two keys because a hole has exactly one declaring slot entry — same owner contract, same occupant). Backend packages are **dual-face**: the browser half registers the matching interaction into both holes — `-native` a renderless occupant driving `host.pickDirectory`, `-browse` the in-app Select Workspace Directory dialog. The hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`) carries the whole exchange: ui-workspace keeps the trigger (menu entry rendered only while the hole is occupied) and the adoption (`createWorkspace({path})`, retryable error dialog, Choose again), the occupant owns everything between `open` and the picked path. One `cordis.yml` row therefore swaps the host capability and the client flow together; a mismatch is impossible by construction, and mounting two flow packages fails at client load (`single` hole). The earlier `host.describe.directoryPicker` advertisement and the client's kind branching are deleted — with composition wiring both sides, a wire fact for the client to branch on had no remaining consumer. The hole registry (`ctx.slots.entries`) replaces it as the per-menu-open occupancy read.
 
@@ -30,7 +30,7 @@ Placement and policy rulings folded into this decision:
 ## Alternatives considered
 
 - **Extend `ctx.fs` with browse methods.** Rejected: authority-domain coupling above; also a listing-for-display contract (hidden flags, crumbs, home anchor) does not belong on a storage seam.
-- **One uniform seam method set (`pick(): path`).** Rejected: an in-app browser cannot be served behind a single host-side call — the browsing loop lives in the client and needs primitives on the wire; the native chooser cannot implement primitives. The interaction difference is irreducible, hence the discriminant.
+- **One uniform Service Definition method set (`pick(): path`).** Rejected: an in-app browser cannot be served behind a single host-side call — the browsing loop lives in the client and needs primitives on the wire; the native chooser cannot implement primitives. The interaction difference is irreducible, hence the discriminant.
 - **Direct stdlib calls inside apiproxy (no seam).** Rejected: keeps the gateway the only swap point (source edits), loses fixture/test backends, and contradicts the plugin doctrine that motivated the work.
 - **Adopting a file-manager/drive-enumeration dependency.** Rejected per the survey above; recorded here as the dependency policy requires.
 - **A flip-label show-hidden toggle ("Hide hidden files").** Rejected: a flipping action label is ambiguous between state and action and doubles the negative; the fixed label with a pressed presentation states both at once.
@@ -38,7 +38,7 @@ Placement and policy rulings folded into this decision:
 - **A permanently visible path input above the Miller view.** Rejected: the breadcrumb is already the "where am I" reading, and a second always-present field duplicates it while costing a row of a 500px card that the columns need. The glyph plus the hover-lit zone puts the affordance on the bar that already answers the question.
 - **Scanning the draft on every keystroke, or only on Enter.** Per keystroke: walking one path segment issues a listing per character, most of them for directories the operator is typing through, not at. Only on Enter (what shipped first): the panes and the typed text disagreed for the whole edit — the complaint this bullet answers. The 250ms rest keeps one scan per directory the typing actually settles on.
 - **Emptying a pane on a prefix miss (what shipped first).** Rejected: mid-name the miss is the normal state, so the pane blanked exactly while the operator needed it to confirm the name; releasing the filter keeps the level readable and costs only the transient wideness.
-- **A wire `separator` field on `DirectoryListing` (host stamps `path.sep`).** Deferred, not rejected: it is the authoritative form — a POSIX home directory containing a backslash defeats the `listing.home` heuristic — but it touches the seam type and every backend; the browse client's `separatorOf` carries a TODO pointing at this alternative until a wire change is next scheduled.
+- **A wire `separator` field on `DirectoryListing` (host stamps `path.sep`).** Deferred, not rejected: it is the authoritative form — a POSIX home directory containing a backslash defeats the `listing.home` heuristic — but it touches the Service Definition type and every backend; the browse client's `separatorOf` carries a TODO pointing at this alternative until a wire change is next scheduled.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index f96f835c5f..fce9a801ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -6,11 +6,11 @@
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入点）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
 
 ## 决策
 
-在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
+在 `packages/host/` 落一个三包能力 seam——`directory-picker`（Service Definition）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
 
 **client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 约定相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
 
@@ -30,7 +30,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick
 ## 曾考虑的替代方案
 
 - **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举约定（hidden 标志、面包屑、home 锚点）不属于存储 seam。
-- **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
+- **统一的 Service Definition 方法集（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
 - **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture／测试后端，与促成这项工作的插件教义相悖。
 - **引入文件管理器／盘符枚举依赖。** 按上文调研否决；依赖政策要求记录于此。
 - **动作标签随状态翻转的"显示隐藏"开关（"隐藏隐藏文件"）。** 否决：会翻转的动作标签在状态与动作之间有歧义，还把否定叠了两层；固定标签加按下态呈现一次说清两者。
@@ -38,7 +38,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick
 - **在 Miller 视图上方常驻一个路径输入框。** 否决：面包屑本就在回答"我在哪儿"，再常驻一个字段是重复回答，还要从 500px 卡片里挪走一行——那是列需要的高度。图标加悬停亮起的区域，把这个入口放在了已经回答该问题的那一栏上。
 - **每敲一个键就扫描草稿，或只在 Enter 时扫描。** 每键扫描：走完一段路径就是每个字符一次列举，其中多数目录操作者只是路过而非停留。只在 Enter 时扫描（最初落地的行为）：整个编辑过程中各栏与所键入文本各说各话——正是本条所回应的抱怨。250ms 的停顿把扫描收敛为"键入真正停下来的每个目录一次"。
 - **前缀无一匹配时清空该栏（最初落地的行为）。** 否决：名字敲到一半时"无匹配"才是常态，于是恰恰在操作者需要它确认名字时把栏清空了；解除过滤保住了层级的可读性，代价只是短暂的宽松。
-- **在 `DirectoryListing` 上增设线上 `separator` 字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 seam 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排线上变更。
+- **在 `DirectoryListing` 上增设线上 `separator` 字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 Service Definition 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排线上变更。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
index e876d151ab..512bd4fac7 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.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 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
-2026-07-28-user-settings-seam.md: bf93f95168b1b6d0dec5a9fc2c9aac5531f0564a
-2026-07-28-user-settings-seam.zh.md: 42e1196cfd8a4cc2ad1a4e2e2fee77bbd5ebbcd2
+2026-07-28-user-settings-seam.md: 62eae0db157d61266af165f609daaefcd7d5e285
+2026-07-28-user-settings-seam.zh.md: bf0f5d850f4cf303efdbd6476ae210cf8779a31d
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
index bf93f95168..62eae0db15 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-28-user-settings-seam.zh.md)
 
-> Scope: the `packages/settings/` capability family — the abstract seam, the file-backed provider, and the composition boundary between user settings and `cordis.yml`. The [web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) recorded "the profile write path" as a deferral; this seam is that write path's owner. Consumer migrations (theme, locale, default model route) and the web `settings.*` RPC surface are follow-ups, not part of this note's shipped scope.
+> Scope: the `packages/settings/` capability family — the Service Definition, the file-backed provider, and the composition boundary between user settings and `cordis.yml`. The [web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) recorded "the profile write path" as a deferral; this seam is that write path's owner. Consumer migrations (theme, locale, default model route) and the web `settings.*` RPC surface are follow-ups, not part of this note's shipped scope.
 
 ## Problem
 
@@ -14,7 +14,7 @@ User-editable configuration had no owner: `dsh web` read a cwd-anchored profile
 
 **Two planes with a litmus test.** `cordis.yml` (+ Include patches) stays the composition plane: which plugins exist, wiring, deployment config, owned by the orchestrator and upgraded with the product. A settings namespace carries only the user-editable subset; the test is "should the personal config page edit it?" Values live in both planes without ambiguity because layering is the contract: schema defaults, then the registrant's composition `base` (its entry-config subset), then the user document section.
 
-**Three-package seam mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `<DSH_HOME>/settings.yaml`), chokidar watch, read-modify-write persists under a cross-process writer lock with atomic `0600` tmp+rename commits, leaf-level diff patching of the written namespace (comments survive untouched nodes), and content-equality self-write suppression ([write-path integrity note](2026-07-30-settings-write-path-integrity.md)).
+**Three-package boundary mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `<DSH_HOME>/settings.yaml`), chokidar watch, read-modify-write persists under a cross-process writer lock with atomic `0600` tmp+rename commits, leaf-level diff patching of the written namespace (comments survive untouched nodes), and content-equality self-write suppression ([write-path integrity note](2026-07-30-settings-write-path-integrity.md)).
 
 **Registrations are caller-fiber effects.** `register()` runs through the service proxy, so `this.ctx` is the registrant's context and the registration rides `ctx.effect`: disposing the registrant removes the namespace and its watchers (proven by the HMR disposal test), while the user's section keeps living in storage for the next owner.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
index 42e1196cfd..bf0f5d850f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-28-user-settings-seam.md) | 中文
 
-> 范围：`packages/settings/` 能力族——抽象 seam、文件 provider，以及用户设置与 `cordis.yml` 的组合边界。[web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) 曾把"profile 写路径"记为延后项；本 seam 就是该写路径的归属。消费者迁移（主题、语言、默认模型路由）与 web `settings.*` RPC 面是后续工作，不在本 note 已交付范围内。
+> 范围：`packages/settings/` 能力族——Service Definition、文件 provider，以及用户设置与 `cordis.yml` 的组合边界。[web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) 曾把"profile 写路径"记为延后项；本 seam 就是该写路径的归属。消费者迁移（主题、语言、默认模型路由）与 web `settings.*` RPC 面是后续工作，不在本 note 已交付范围内。
 
 ## 问题
 
@@ -14,7 +14,7 @@ Status: implemented
 
 **两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是约定：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。
 
-**镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `<DSH_HOME>/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。
+**镜像 `session-persistence/` 的三包边界。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `<DSH_HOME>/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。
 
 **注册是调用方 fiber 上的 effect。**`register()` 经服务代理调用，`this.ctx` 即注册方 context，注册挂在 `ctx.effect` 上：dispose 注册方即移除 namespace 及其观察者（HMR disposal 测试证明），而用户的分节继续留在存储中等待下一任 owner。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 15189e7387..3a6b661601 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: 94b32c3cfaa3e1c5059573881a2f393d29aed3ac
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 088e24cbfd7db9da73c2ed3e3d11fdef24249c37
+2026-07-30-credential-boundaries-and-atomic-registration.md: 300280e6d4f8be2c0519efcb7ecfc82028d05445
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2b66c543bdd80612bee65a6e6e4a78ab565d5188
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index 94b32c3cfa..300280e6d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.md)
 
-> Scope: the third review round over the [request-level LLM configuration seam](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this round applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
+> Scope: the third review round over the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this round applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
 
 ## Problem
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 088e24cbfd..2b66c543bd 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
 
-> 范围：对[请求级 LLM（大语言模型）配置 seam](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
+> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index a066480489..b478070862 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.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 .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
-2026-07-30-followup-enqueue-and-owned-runs.md: 54f4af75eeb29b06504fa2629b0665f3e5f4c4ee
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: 226f0b9b61883cee5f6e321ae6b89b7b27b79e35
+2026-07-30-followup-enqueue-and-owned-runs.md: e0561f8cfc975dd60e69307b160070c292efff8e
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: a807b3ebe47399cae95c38bc2232e20e00e839f5
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
index 54f4af75ee..e0561f8cfc 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md)
 
 `Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input.
 
-The [one-send-one-turn decision](../simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers that pair one prompt request with a turn result manufacture that missing relationship downstream. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome.
+The [one-send-one-turn decision](../simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle in the core API. Protocol and SDK layers that pair one prompt request with a turn result manufacture that missing relationship downstream. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index 226f0b9b61..a807b3ebe4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `Agent.followup()` 会标识一条用户消息并将其排入队列，但单次 follow-up 并不拥有随后发生的活动。在 agent（智能体）下一次进入 idle 前，steering（中途引导）、注入的上下文、工具续行、恢复和后续排队消息都可能参与活动。因此，`MessageId` 可以证明 inbox 已准入，但不能标识哪一条 assistant 消息或哪一个 `turn/end` 是该输入的结果。
 
-[one-send-one-turn 决策](../simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。凡是把一项提示词请求与一个轮次结果配对的协议层和 SDK 层，都会在下游人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。
+[one-send-one-turn 决策](../simplification/2026-07-17-one-send-one-turn.md) 已经在核心 API 中排除了按 send 返回完成句柄的设计。凡是把一项提示词请求与一个轮次结果配对的协议层和 SDK 层，都会在下游人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index 53eb3cefe5..df68353802 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.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 .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
-2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
-2026-07-30-package-manager-native-repository-cache.zh.md: a4ad07c42eec7b05f51b18aaf54fcfedaa4d4b3c
+2026-07-30-package-manager-native-repository-cache.md: 38e7356d4abfc8eba8854f0a96700da448ff4ac4
+2026-07-30-package-manager-native-repository-cache.zh.md: 6833eeb4279c9feb9ac1860e780b8ed58b09d334
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
index 0ea145f20a..38e7356d4a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
@@ -32,7 +32,7 @@ An identical specifier permanently reuses its published entry. The caller change
 
 **Disable repository lifecycle scripts.** Rejected because common plugin repositories need a declarative `prepare` step to validate and package their plugin subdirectory. The trust boundary is explicit configuration of executable source, not an incomplete illusion that only static files can run.
 
-**Introduce a Cordis repository service.** Rejected because cache lookup has no runtime contribution registry or provider variation. A small helper lets the later host own Cordis lifecycle and HMR without adding a service seam prematurely.
+**Introduce a Cordis repository service.** Rejected because cache lookup has no runtime contribution registry or provider variation. A small helper lets the later host own Cordis lifecycle and HMR without adding a service contract prematurely.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index a4ad07c42e..6833eeb427 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -32,7 +32,7 @@ Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前
 
 **禁用仓库生命周期脚本。** 不予采纳：常见插件仓库需要声明式 `prepare` 步骤来校验并打包插件子目录。信任边界是显式配置可执行来源，而不是营造一种不完整的假象，仿佛只有静态文件能够运行。
 
-**引入 Cordis 仓库服务。** 不予采纳：缓存查找没有运行时贡献注册表，也不存在提供方变体。小型 helper 让后续宿主负责 Cordis 生命周期与 HMR（热模块替换），无需过早新增服务 seam。
+**引入 Cordis 仓库服务。** 不予采纳：缓存查找没有运行时贡献注册表，也不存在提供方变体。小型 helper 让后续宿主负责 Cordis 生命周期与 HMR（热模块替换），无需过早新增服务约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
index b8dcd32d8e..14a0ad2bb0 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.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 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
-2026-07-30-settings-write-path-integrity.md: 7bd50adc8a812759c3ae3f80a50978d75baa712a
-2026-07-30-settings-write-path-integrity.zh.md: 155fb55b886ab41d11d947ee09194a367ac8a90f
+2026-07-30-settings-write-path-integrity.md: f9b56ca83ad3027083884442a051eca102207c24
+2026-07-30-settings-write-path-integrity.zh.md: 1e8ce7eddb6a639512cd792e98fc135f49a8c0be
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
index 7bd50adc8a..f9b56ca83a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-settings-write-path-integrity.zh.md)
 
 ## Problem
 
-Review found the provider's write path could destroy state it never observed, and the seam's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the seam side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
+Review found the provider's write path could destroy state it never observed, and the Service Definition's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the Service Definition side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
 
 ## Decision
 
@@ -28,7 +28,7 @@ Review found the provider's write path could destroy state it never observed, an
 - **Revision/CAS instead of a lock** — rename cannot express compare-and-swap, so a CAS needs a version sidecar or content re-hash and a retry loop in every writer; the lock achieves the same serialization with one primitive and keeps readers free.
 - **Merging external edits into the in-flight write's own section** — the seam merges patches over the state visible at call time, so a same-namespace external edit racing a write still resolves last-write-wins; folding it in would need three-way merge semantics no consumer has asked for. The write publishes the external state first, so the loser is at least observed before being superseded.
 - **Declaring async `settings/updated` listeners unsupported** — the typed signature is `void` and lint flags misused promises, but an unlinted JS plugin can still register an async listener; a contract note cannot un-throw an unhandled rejection, so containment is the only defense that holds at runtime.
-- **Keeping `structuredClone` and validating in the provider** — the seam is the durable boundary's owner (every provider stores JSON-shaped documents), and rejecting at call time gives the caller the offending path; a provider-side check would reject after merge, blaming the merged section instead of the caller's value.
+- **Keeping `structuredClone` and validating in the provider** — the Service Definition is the durable boundary's owner (every provider stores JSON-shaped documents), and rejecting at call time gives the caller the offending path; a provider-side check would reject after merge, blaming the merged section instead of the caller's value.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
index 155fb55b88..1e8ce7eddb 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
@@ -8,9 +8,9 @@ Status: implemented
 
 ## 问题
 
-评审发现，提供方的写路径可能销毁它从未观察到的状态，而 seam 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
+评审发现，提供方的写路径可能销毁它从未观察到的状态，而 Service Definition 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
 
-在 seam 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。
+在 Service Definition 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。
 
 YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删掉——而这个保注释的提供方承诺过要保住它们。
 
@@ -32,7 +32,7 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 - **用修订号/CAS 取代锁**——rename 表达不了 compare-and-swap，因此 CAS 需要一个版本伴随文件或内容重哈希，外加每个写方里的一个重试循环；锁用一个原语实现同样的串行化，还让读方完全免锁。
 - **把外部编辑合并进正在进行的写入自身的分节**——seam 是在调用时刻可见的状态之上合并 patch 的，因此与写入竞态的同 namespace 外部编辑仍按后写胜出解决；要把外部编辑并进来，需要三方合并语义，而没有任何消费方提出过这种需求。写入会先发布外部状态，落败一方至少在被取代之前被观察到。
 - **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；约定里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。
-- **保留 `structuredClone`、在提供方里做校验**——seam 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。
+- **保留 `structuredClone`、在提供方里做校验**——Service Definition 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 6c9f7d8ce0..7fbaf3c2b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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 .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
-2026-07-30-web-config-plane.md: 483058c8a24ad8c414278eba84f4226e973f2923
-2026-07-30-web-config-plane.zh.md: 840ac7f2e46c82e7b858c353086e1a9541db563e
+2026-07-30-web-config-plane.md: 78fa9cf970dea30fdc842799134bc1d11608c800
+2026-07-30-web-config-plane.zh.md: b8a4347f95a741140a61e1d47f837aa0502d85ee
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
index 483058c8a2..78fa9cf970 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
@@ -22,7 +22,7 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 **A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog takes the row shape the pi-ai provider form introduces: one bordered entry per model, id and display name on the row, and the capacities behind the row's own disclosure, so the two editors read as one design rather than diverging once both land. Every field keeps the indexed `aria-label` that names it. Both capacities are text fields reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: a field holds the typed text while it has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. The shared class names carry this file's token spellings, not that branch's: `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and `--dsw-alias-text-primary` are undeclared, so they resolve to the light-mode literals in their fallback slots — the defect this section was moved off. A styles test now rejects any `--dsw-*` name the token sheet does not declare, so the next editor to name one fails rather than shipping a light-only surface.
 
-**The Models page is a three-domain join with seam-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `<ROUTE>_API_KEY` when none exists (the pi-ai profile records the derivation only when a key is entered), so `settings.yaml` never carries a key value; a blank pi-ai key materializes a reference-free profile and preserves provider-native authentication. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized confirmation dialog whose row actions, title, description, and final action identify the same provider; confirmation removes an exact configured+writable derived credential before the profile, while custom, environment, and unidentified targets remain untouched. Both stages are idempotent and a partial failure stays in the dialog for retry. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. The partial-commit and credential-ownership rationale lives in the [provider credential lifecycle note](../bug-fix/2026-08-06-provider-credential-lifecycle.md).
+**The Models page is a three-domain join with service-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `<ROUTE>_API_KEY` when none exists (the pi-ai profile records the derivation only when a key is entered), so `settings.yaml` never carries a key value; a blank pi-ai key materializes a reference-free profile and preserves provider-native authentication. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized confirmation dialog whose row actions, title, description, and final action identify the same provider; confirmation removes an exact configured+writable derived credential before the profile, while custom, environment, and unidentified targets remain untouched. Both stages are idempotent and a partial failure stays in the dialog for retry. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. The partial-commit and credential-ownership rationale lives in the [provider credential lifecycle note](../bug-fix/2026-08-06-provider-credential-lifecycle.md).
 
 ## Alternatives considered
 
@@ -36,4 +36,4 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 ## Consequences
 
-The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; seam, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
+The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; Service Definition, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index 840ac7f2e4..b8a4347f95 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -22,7 +22,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 **架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录采用 pi-ai 提供方表单引入的行形态：每个模型一个带边框的条目，ID 与显示名称落在行上，容量则收在该行自己的折叠区里，使两个编辑器呈现为同一套设计，而不是在双方都落地后各自分岔。每个字段都保留那个为其命名的带序号 `aria-label`。两项容量都是文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：字段持有焦点期间保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。共用的类名承载的是本文件的 token 写法，而非那个分支的：`--dsw-alias-border-subtle`、`--dsw-alias-text-tertiary` 和 `--dsw-alias-text-primary` 均未声明，于是它们解析为各自回退槽位中的亮色模式字面值——正是本节此前迁离的那个缺陷。现在有一个样式测试会拒绝 token 表未声明的任何 `--dsw-*` 名称，因此下一个写出这类名称的编辑者会当场失败，而不是交付一个只有亮色的界面。
 
-**Models 页是一次三领域联接，应用语义与 seam 同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `<ROUTE>_API_KEY`（仅在输入密钥时，pi-ai profile 才会记录该派生），因此 `settings.yaml` 从不携带密钥值；留空 pi-ai 密钥会具化一个不带引用的 profile，并保留提供方原生认证。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化确认对话框，其行操作、标题、说明和最终操作都会点名同一个提供方；确认后会先清除与派生目标精确匹配且已配置、可写的凭据，再删除 profile，自定义目标、环境目标和无法识别的目标则保持不变。两个阶段都具备幂等性，部分失败会留在对话框中供重试。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。部分提交与凭据所有权的理由记录在[提供方凭据生命周期 note](../bug-fix/2026-08-06-provider-credential-lifecycle.md)中。
+**Models 页是一次三领域联接，应用语义与服务同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `<ROUTE>_API_KEY`（仅在输入密钥时，pi-ai profile 才会记录该派生），因此 `settings.yaml` 从不携带密钥值；留空 pi-ai 密钥会具化一个不带引用的 profile，并保留提供方原生认证。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化确认对话框，其行操作、标题、说明和最终操作都会点名同一个提供方；确认后会先清除与派生目标精确匹配且已配置、可写的凭据，再删除 profile，自定义目标、环境目标和无法识别的目标则保持不变。两个阶段都具备幂等性，部分失败会留在对话框中供重试。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。部分提交与凭据所有权的理由记录在[提供方凭据生命周期 note](../bug-fix/2026-08-06-provider-credential-lifecycle.md)中。
 
 ## 曾考虑的替代方案
 
@@ -36,4 +36,4 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 ## 后果
 
-整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；seam、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
+整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；Service Definition、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
index a6be2d99e5..927f3d1c6d 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.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 .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
-2026-07-31-claimed-pre-step-inbox-lifecycle.md: 5184c00335b3084a8eb6d58fa33a0af8d3a16ed6
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4718b1b519051f0ae82b4c7f9d0599f45a800f1d
+2026-07-31-claimed-pre-step-inbox-lifecycle.md: 037b17fa823a28d1ded6f599c62374432d546c22
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: b77a2e052b57151ee897555ed88d6632820e0ebf
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
index 5184c00335..037b17fa82 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
@@ -14,7 +14,7 @@ Occurrence-local inbox wrappers also duplicated the identity already carried by
 
 Before every proposed step, `Inbox.claim(target)` atomically removes the complete batch: all `next-step` messages and, at a turn boundary, one `next-turn` message. At the initial boundary the loop first commits `turn/start`, so the claim and its single `agent/pre-step` decision have durable turn ownership. Claiming records normalized `agent/inbox/spliced` pure deletions with no outcome. The loop then emits `agent/inbox/claimed { message, turn }` once per claimed message and awaits the waterfall with that exclusive batch and `{ turn, step, signal }`.
 
-`PreStepDecision` is `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`. Reject opens no step, leaves the claimed batch removed, and closes the turn as blocked without any step events. Empty entry, cancellation, and failure before `step/start` likewise close a balanced no-step turn. Enter supplies the complete batch appended as `user/message` events after `step/start`. A listener wrapping `next()` preserves downstream changes unless it intentionally replaces them, so all message rewrites settle once in the final return value. There is no `agent/prompt-prepare`, `agent/prompt-submit`, or `agent/step` seam.
+`PreStepDecision` is `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`. Reject opens no step, leaves the claimed batch removed, and closes the turn as blocked without any step events. Empty entry, cancellation, and failure before `step/start` likewise close a balanced no-step turn. Enter supplies the complete batch appended as `user/message` events after `step/start`. A listener wrapping `next()` preserves downstream changes unless it intentionally replaces them, so all message rewrites settle once in the final return value. There is no `agent/prompt-prepare`, `agent/prompt-submit`, or `agent/step` extension point.
 
 The durable inbox remains two `UserMessage[]` lists addressed by `MessageId`. `append`, `prepend`, and `splice` take a target, while `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists before committing a normalized splice. Replacement may change identity and emits the old message as discarded followed by the new message as inserted. Every insertion emits `agent/inbox/inserted { message }`; an ordinary removal records `outcome: 'canceled'` and emits `agent/inbox/discarded { message }`. Claiming is the loop's internal step-boundary operation on the inbox and records pure deletions without notifications or an outcome, so the loop can publish claimed events itself. These live events add no placement, outcome, or batch fields.
 
@@ -34,7 +34,7 @@ The archived [addressable queue occurrence decision](../../archived/feature/2026
 
 ## Verification
 
-Agent-loop coverage pins turn-start-before-claim-before-pre-step ordering, exact live event payloads, balanced no-step rejection, final-batch rewriting, input inserted after a claim, listener failure, and cancellation. Inbox and consumer tests pin pure claim deletions, canceled ordinary removals, workspace-context staging, replacement, and same-step entry, plan/goal/hook behavior, UI cleanup, compaction, checkpointing, and resumed durable projection. Generated event and type catalogs expose only the new seam and payloads.
+Agent-loop coverage pins turn-start-before-claim-before-pre-step ordering, exact live event payloads, balanced no-step rejection, final-batch rewriting, input inserted after a claim, listener failure, and cancellation. Inbox and consumer tests pin pure claim deletions, canceled ordinary removals, workspace-context staging, replacement, and same-step entry, plan/goal/hook behavior, UI cleanup, compaction, checkpointing, and resumed durable projection. Generated event and type catalogs expose only the new waterfall and payloads.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
index 4718b1b519..b77a2e052b 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 每个拟议步骤之前，`Inbox.claim(target)` 会原子移除完整批次：全部 `next-step` 消息，以及轮次边界上的一条 `next-turn` 消息。在首次边界，循环会先提交 `turn/start`，使领取及其唯一一次 `agent/pre-step` 决策拥有持久轮次归属。领取会记录规范化、不带 outcome 的纯删除 `agent/inbox/spliced`。随后，循环针对每条已领取消息发出一次 `agent/inbox/claimed { message, turn }`，并用该独占批次与 `{ turn, step, signal }` 等待 waterfall（瀑布式事件）。
 
-`PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` seam。
+`PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` 扩展点。
 
 持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此循环可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
 
@@ -34,7 +34,7 @@ Status: implemented
 
 ## 验证
 
-Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 seam 与载荷。
+Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 waterfall 与载荷。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 58470f9780..37ab3eda38 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.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 .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
-2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 215024467f6f76a79a1f48f33e9d3c5b216df08d
+2026-07-31-code-runtime-portable-identifier-seam.md: ba2aa8eeabb823978fca32a59d98d56971784a92
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: 689ffa1b1ffcb5be1e2aa2bd9cd49c2ae40ba7ee
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
index 9e9df50235..ba2aa8eeab 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
@@ -8,24 +8,24 @@ English | [中文](2026-07-31-code-runtime-portable-identifier-seam.zh.md)
 
 The code-runtime seam promises that a binding-namespace list valid on one backend is valid on every backend, so a Code Mode consumer can hand the same bindings to any registered runtime without knowing its language. The first backend, `dsh-code-runtime-worker`, privately owned the identifier rules that enforce part of that promise: an `IDENTIFIER` regex that allowed the JS-only `$`, a `RESERVED_WORDS` set holding only ECMAScript keywords, and a `RESERVED_ERROR_PROPERTIES` set of three JS `Error` slots. Those rules described the worker's own language, not the seam's portability contract.
 
-A second backend written against a different language (CPython, arriving in a later PR of this stack) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so the seam's implementation reached into a sibling implementation. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
+A second backend written against a different language (CPython, arriving in a later PR of this stack) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so a Service provider reached into a sibling Service provider. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
 
 ## Decision
 
-The seam package (`@deepseek-ai/dsh-code-runtime`) exports the portable-identifier exclusion contract as four named constants, and every backend imports them rather than re-declaring:
+The Service Definition package (`@deepseek-ai/dsh-code-runtime`) exports the portable-identifier exclusion contract as four named constants, and every Service provider imports them rather than re-declaring:
 
 - `PORTABLE_RESERVED_WORDS` — the union of ECMAScript and Python reserved words. A namespace global or error-class name matching any is refused on all backends, so `lambda` is refused even though it is a legal JS parameter name. Adding a language widens this union, which is a deliberate breaking review of existing binding names.
 - `RESERVED_BINDING_GLOBALS` — globals some backend owns in the program's namespace: `console` (the worker's log capture), `__dsh_main__`/`__builtins__`/`__name__` (the Python bootstrap's wrapper and seeded module globals), and `__debug__` (not a seeded slot but a CPython compile-time constant that rejects assignment, so an injected global under that name is unreachable — the same portability split by a different mechanism). Refused everywhere so a namespace list cannot pick a name that works on one backend and collides on another.
 - `RESERVED_ERROR_MEMBERS` — error-member names every backend refuses: the JS `Error` slots (`name`, `message`, `stack`) and Python's exception-protocol members (`args`, `with_traceback`, `add_note`).
 - `DUNDER_MEMBER` — the dunder-form regex (`__x__`, non-empty middle), refused as an error member wholesale because several are constrained CPython descriptors whose exact set is an interpreter-version detail.
 
-The seam also narrows the portable identifier subset to `[A-Za-z_][A-Za-z0-9_]*` (documented on `CodeBindingNamespace.global` and `CodeBindingErrorClass`), dropping the JS-only `$`. The worker consumes the shared constants directly by their seam names — `PORTABLE_RESERVED_WORDS` for both binding-global and error-class names, `RESERVED_BINDING_GLOBALS` for backend-owned slots, `RESERVED_ERROR_MEMBERS` plus `DUNDER_MEMBER` for error members — with no local re-alias; its `IDENTIFIER` regex loses `$`.
+The Service Definition also narrows the portable identifier subset to `[A-Za-z_][A-Za-z0-9_]*` (documented on `CodeBindingNamespace.global` and `CodeBindingErrorClass`), dropping the JS-only `$`. The worker consumes the shared constants directly under their exported names — `PORTABLE_RESERVED_WORDS` for both binding-global and error-class names, `RESERVED_BINDING_GLOBALS` for backend-owned slots, `RESERVED_ERROR_MEMBERS` plus `DUNDER_MEMBER` for error members — with no local re-alias; its `IDENTIFIER` regex loses `$`.
 
-The constants live at the seam even though only one backend ships in this PR: the whole point is that the contract is language-agnostic and owned above any single language. A backend that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
+The constants live in the Service Definition even though only one backend ships in this PR: the whole point is that the contract is language-agnostic and owned above any single language. A Service provider that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
 
 ## Scope
 
-This PR delivers only the seam extension and the worker's adoption of it. No Python backend, `py-types` renderer, or Code Mode language dispatch ships here — they are later PRs in the stack that depend on these exports. The seam README's worker-only wording is left unchanged for the same reason: linking to a `dsh-code-runtime-python` README that does not yet exist would break the dead-link gate.
+This PR delivers only the Service Definition extension and the worker's adoption of it. No Python backend, `py-types` renderer, or Code Mode language dispatch ships here — they are later PRs in the stack that depend on these exports. The Service Definition README's worker-only wording is left unchanged for the same reason: linking to a `dsh-code-runtime-python` README that does not yet exist would break the dead-link gate.
 
 `RESERVED_BINDING_GLOBALS` currently encodes the not-yet-merged Python bootstrap's concrete design: it seeds exactly `__builtins__`/`__name__` and wraps the program under `__dsh_main__`. The Python-backend PR that seeds any additional module global (`__doc__`, `__loader__`, `__spec__`, `__file__`, `__package__`, …) MUST widen this set in the same change, exactly as adding a language widens `PORTABLE_RESERVED_WORDS` — a name the bootstrap seeds but the set omits is the portability split this contract exists to prevent.
 
@@ -33,12 +33,12 @@ This PR delivers only the seam extension and the worker's adoption of it. No Pyt
 
 **Each backend declares its own exclusions.** Rejected: it makes the portability promise per-backend. A binding list the caller tested on the worker could be refused by Python, which is exactly the split the seam exists to prevent.
 
-**The Python backend imports the worker's constants.** Rejected: it inverts the dependency — the seam's implementations would reach into a sibling implementation for a contract neither owns. The contract belongs above both, at the seam.
+**The Python backend imports the worker's constants.** Rejected: it inverts the dependency — the seam's Service providers would reach into a sibling implementation for a contract neither owns. The contract belongs above both, at the seam.
 
 **Keep `$` in the portable identifier subset.** Rejected: `$` is JS-only spelling. Allowing it would let `$tools` pass the worker and fail every non-JS backend, breaking portability for a purely cosmetic gain.
 
 ## Consequences
 
-Bought: one place — the seam package — defines what a portable binding name is, and every backend enforces the same contract by import. A namespace list valid on one backend is valid on all, verifiably, not by coincidence of which backend the caller tested.
+Bought: one place — the Service Definition package — defines what a portable binding name is, and every backend enforces the same contract by import. A namespace list valid on one backend is valid on all, verifiably, not by coincidence of which backend the caller tested.
 
-Cost: existing worker callers using a `$`-containing global now fail identifier validation. Under the pre-release stance this is a corrected foundation, not a compatibility break to shim. The worker's seam-misuse tests gain cases for `$tools`, Python exception members (`args`), dunders (`__dict__`), and a Python-owned global (`__dsh_main__`), proving the shared set is enforced from the worker side.
+Cost: existing worker callers using a `$`-containing global now fail identifier validation. Under the pre-release stance this is a corrected foundation, not a compatibility break to shim. The worker's Service Definition misuse tests gain cases for `$tools`, Python exception members (`args`), dunders (`__dict__`), and a Python-owned global (`__dsh_main__`), proving the shared set is enforced from the worker side.
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 215024467f..689ffa1b1f 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -8,24 +8,24 @@ Status: implemented
 
 code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
-一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
+一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使一个 Service provider 伸手进入另一个兄弟 Service provider。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
-seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个后端导入它们而非重新声明：
+Service Definition 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个 Service provider 导入它们而非重新声明：
 
 - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。
 - `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。
 - `RESERVED_ERROR_MEMBERS`——每个后端都拒绝的 error-member 名称：JS `Error` 槽位（`name`、`message`、`stack`）与 Python 异常协议成员（`args`、`with_traceback`、`add_note`）。
 - `DUNDER_MEMBER`——dunder 形式正则（`__x__`，非空中缀），作为 error member 被整体拒绝，因为其中若干是受约束的 CPython 描述符，其确切集合是解释器版本细节。
 
-seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以 seam 名消费这些共享常量——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
+Service Definition 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以这些常量的导出名称消费它们——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管本 PR 只交付一个后端，这些常量仍置于 Service Definition：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的 Service provider 才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
 
 ## Scope
 
-本 PR 只交付 seam 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。seam README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
+本 PR 只交付 Service Definition 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。Service Definition README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
 `RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
@@ -33,12 +33,12 @@ seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记
 
 **每个后端声明自己的排除集。** 拒绝：这让可移植承诺变成逐后端成立。调用方在 worker 上测过的绑定列表可能被 Python 拒绝，而这正是 seam 存在要防止的分裂。
 
-**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
+**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的 Service provider 会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
 
 **在可移植标识符子集中保留 `$`。** 拒绝：`$` 是 JS 专有拼写。允许它会让 `$tools` 通过 worker 却在每个非 JS 后端上失败，为纯粹表面的好处破坏可移植性。
 
 ## Consequences
 
-获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
+获得：一个地方——Service Definition 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
 
-代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
+代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 Service Definition misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
index b8f2e4d7d7..86a7237e7e 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.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 .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
-2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
-2026-08-01-packaged-ripgrep-search.zh.md: d06841b220603d832048d1c76784f0e1d283679c
+2026-08-01-packaged-ripgrep-search.md: 0320e9db1e1bead7d36ba66aa42ad5da345cdcbf
+2026-08-01-packaged-ripgrep-search.zh.md: 40471048ece89b0cd56aad7211097003a40ac3df
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
index 7c515618a1..0320e9db1e 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
@@ -22,7 +22,7 @@ The `fs-glob-sampling` ACP snapshot scenario now executes the real packaged bina
 
 **Keep the bash seam and probe, but document `rg` as a required host dependency.** Rejected: the host dependency is exactly the failure this change removes, and Windows support for the discovery tools was the point of the exercise; a documented requirement is still a requirement.
 
-**Make `rgPath` injectable (a config field or env override) so tests and snapshots keep substituting a stand-in binary.** Rejected: it adds a public deployment surface whose only consumer would be test seams, and the real binary is deterministic enough to pin directly through fixture mtimes — the packaged binary is the deployment, so tests should exercise it.
+**Make `rgPath` injectable (a config field or env override) so tests and snapshots keep substituting a stand-in binary.** Rejected: it adds a public deployment surface whose only consumer would be test hooks, and the real binary is deterministic enough to pin directly through fixture mtimes — the packaged binary is the deployment, so tests should exercise it.
 
 **Switch to a pure-JS glob/search engine (e.g. `picomatch`/`tinyglobby`).** Rejected: the [dependency-swaps audit](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) already rejected that on the "no glob engine exists" evidence; ripgrep semantics (`--sort=modified`, VCS pruning, JSON transport, regex dialect) are the tool contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
index d06841b220..40471048ec 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 **保留 bash seam 与探针，仅把 `rg` 记为必需宿主依赖。** 否决：宿主依赖正是本次改动要消除的失败模式，而让发现工具支持 Windows 正是此举的目的；写进文档的依赖仍是依赖。
 
-**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
+**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试钩子会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
 
 **改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具约定。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index fb4922d5c5..0b7c4c42a8 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.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 .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
-2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: 9ed1abc5cedbba637466531f7fc48f73c1e18a0d
+2026-08-03-pi-ai-declared-provider-catalog.md: f4b5a8565dbeb836c7aa4edb9c565f649de20f0a
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: 61e2053efe4dd1234bcd319eb989d946639d2e86
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
index f908eb6293..f4b5a8565d 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
@@ -35,7 +35,7 @@ The configurable-provider directory is now the installed catalog **joined with**
 
 pi-ai reports a model with no reasoning metadata as supporting the single level `off`, and the adapter used to pass that straight through. It reaches the seam as a one-item effort list, which every surface renders as a picker holding one selectable control — and that control is a lie: `off` becomes an *omitted* reasoning option at dispatch, byte-for-byte the request that naming no effort already produces. A provider whose own default is to think keeps thinking while the surface shows `off` selected.
 
-`reasoningInfo` therefore omits the seam's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model whose entry declares no `reasoningEfforts` ([[2026-08-08-pi-ai-per-model-reasoning-declarations]] made declared efforts carry that metadata) **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
+`reasoningInfo` therefore omits the Service Definition's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model whose entry declares no `reasoningEfforts` ([[2026-08-08-pi-ai-per-model-reasoning-declarations]] made declared efforts carry that metadata) **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
 
 ### Credentials stay outside pi-ai
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index 9ed1abc5ce..61e2053efe 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -35,7 +35,7 @@ Status: implemented
 
 pi-ai 把没有推理元数据的模型报告为只支持 `off` 一档，而适配器此前原样透传。它抵达 seam 时是一个单元素的 effort 列表，任何界面都会把它渲染成一个只有一项可选控件的选择器——而这个控件在撒谎：`off` 在派发时变成被*省略*的 reasoning 选项，与「不点名任何档位」产出的请求逐字节相同。自身默认就在思考的提供方会继续思考，界面却显示 `off` 已选中。
 
-因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 seam 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖条目未声明 `reasoningEfforts` 的每一个手工声明模型（[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 让声明的档位携带这份元数据）**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
+因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 Service Definition 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖条目未声明 `reasoningEfforts` 的每一个手工声明模型（[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 让声明的档位携带这份元数据）**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
 
 ### 凭据留在 pi-ai 之外
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 6e2e6e1453..989393cfc3 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: ef30a22c120af1437f348e52843e1dd45c9837ae
-2026-08-04-configuration-source-ownership.zh.md: ef352ce4c7b8eef8fc2dcd3aa7154bda770ffd4e
+2026-08-04-configuration-source-ownership.md: dc24fd4eb57294b73c3d2f8935418182726b35c2
+2026-08-04-configuration-source-ownership.zh.md: 20a8aebb626cf2282b7ddf27540be2c05eaae946
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index ef30a22c12..dc24fd4eb5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -56,7 +56,7 @@ The line is that these take effect with no user action, before any turn, outside
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
 - Composition is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; the product CLI offers no flag above it, so a deployment that must win against stored settings owns its own bin or loader tree.
 - Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all; the environment package records the remaining subprocess reach as a limitation.
-- Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
+- Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request credential resolution is separate work.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index ef352ce4c7..20a8aebb62 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -58,7 +58,7 @@ inherited process environment      (read-only, wins)
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - composition 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
 - 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；环境包将其余变量仍可抵达子进程这一点记录为一项限制。
-- Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
+- Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求解析凭据是另一件事。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
index 9b8339d0e2..ba894a29e5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.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 .agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
-2026-08-04-draft-provider-endpoint-interrogation.md: 65545098cd1063c40081481c1ac8f0afdb4fb390
-2026-08-04-draft-provider-endpoint-interrogation.zh.md: 6300e357182e0e81028c6d01026ea93c4fc5202f
+2026-08-04-draft-provider-endpoint-interrogation.md: 6a545ea5c97ef7e7f0e916c1676c1361f7a9bf3b
+2026-08-04-draft-provider-endpoint-interrogation.zh.md: 852e140cafc6eb595e8784f3735e79cec1b78c42
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
index 65545098cd..6a545ea5c9 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
@@ -10,7 +10,7 @@ Once a pi-ai route became [a declaration rather than a catalog lookup](2026-08-0
 
 The obvious answer, a dynamic runtime catalog refreshed in the background, was rejected with the layer below it: it makes a route's model list external mutable state needing a cache, an invalidation story, and an offline path, while the product need is narrower. What is needed is a *question asked once*, whose answer the user adopts into `settings.yaml` — so `settings.yaml` remains the only thing deciding what a route serves.
 
-The awkward part is that the question is about something that does not exist yet. The provider being added has no route, no stored profile, and no stored credential; the endpoint and key are values in a form the user is still typing. Every existing seam operation is keyed by a registered provider route, so none of them can carry this.
+The awkward part is that the question is about something that does not exist yet. The provider being added has no route, no stored profile, and no stored credential; the endpoint and key are values in a form the user is still typing. Every existing LLM Service Definition operation is keyed by a registered provider route, so none of them can carry this.
 
 ## Decision
 
@@ -29,7 +29,7 @@ pi-ai supplies `createProvider({ fetchModels })` plus `Models.refresh()` and a `
 
 ## Alternatives considered
 
-**Key interrogation by provider route.** Symmetric with every other seam operation, and it would let the request omit the endpoint. But the case that motivates the feature — adding a provider — has no route, so the operation would only work for providers already configured, which are the ones that need it least.
+**Key interrogation by provider route.** Symmetric with every other LLM Service Definition operation, and it would let the request omit the endpoint. But the case that motivates the feature — adding a provider — has no route, so the operation would only work for providers already configured, which are the ones that need it least.
 
 **Put the capability on `LlmAdapter`.** Adapters are reached through a route registration, so this has the same problem, plus it would make an adapter instance answer questions about endpoints it does not serve.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
index 6300e35718..852e140caf 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是*只问一次*，其答案由用户采纳进 `settings.yaml`，从而让 `settings.yaml` 始终是决定路由服务内容的唯一真源。
 
-麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 seam 操作都以已注册的提供方路由为键，因此没有一个能承载它。
+麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 LLM Service Definition 操作都以已注册的提供方路由为键，因此没有一个能承载它。
 
 ## Decision
 
@@ -29,7 +29,7 @@ pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与
 
 ## Alternatives considered
 
-**以提供方路由为键。** 与其他每个 seam 操作对称，也能让请求省去端点。但催生该功能的场景——新增提供方——没有路由，于是这个操作只对已配置好的提供方可用，而它们恰恰最不需要它。
+**以提供方路由为键。** 与其他每个 LLM Service Definition 操作对称，也能让请求省去端点。但催生该功能的场景——新增提供方——没有路由，于是这个操作只对已配置好的提供方可用，而它们恰恰最不需要它。
 
 **把能力挂在 `LlmAdapter` 上。** 适配器要经由路由注册才能抵达，因此问题相同；而且这会让一个适配器实例去回答它并不服务的端点的问题。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
index d6c40df351..bf5e1a833d 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.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 .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
-2026-08-04-websocket-downlink-carrier.md: b41ad687725c55acb8517fe7e93d645f007a0453
-2026-08-04-websocket-downlink-carrier.zh.md: c8c8c34c7b7365bc3099cb33a5861051e015b226
+2026-08-04-websocket-downlink-carrier.md: f757487c7b0880cfff25b93644341dc85b5e0e38
+2026-08-04-websocket-downlink-carrier.zh.md: fb07520602b66d33d4bc6e00764ff839f9553a7a
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
index b41ad68772..f757487c7b 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
@@ -16,7 +16,7 @@ WebSocket carries only the host→browser downlink. All client→host unary call
 
 ## Upgrade and lifecycle boundaries
 
-`dsh-host-webserver` provides an exact upgrade-route registration seam alongside ordinary routes, dispatches Node upgrade sockets by pathname only, contains raw-socket errors, and waits for surviving upgraded connections to close during server teardown; it knows nothing about Harness frames or WebSocket messages. `dsh-client-connection` owns the WebSocket handshake, frame output, and stream cancellation, and reuses the `/api` Host/Origin trust fence before upgrade. An untrusted authority or cross-origin Origin is rejected before `ctx.apiProxy.events.*` starts.
+`dsh-host-webserver` provides an exact upgrade-route registration point alongside ordinary routes, dispatches Node upgrade sockets by pathname only, contains raw-socket errors, and waits for surviving upgraded connections to close during server teardown; it knows nothing about Harness frames or WebSocket messages. `dsh-client-connection` owns the WebSocket handshake, frame output, and stream cancellation, and reuses the `/api` Host/Origin trust fence before upgrade. An untrusted authority or cross-origin Origin is rejected before `ctx.apiProxy.events.*` starts.
 
 A browser abort or socket close cancels the corresponding host stream; plugin teardown also waits for that source iterator's cleanup. If a host stream throws midway, the carrier sends one existing `stream/error` frame and then closes the socket; the client treats that frame as connection loss rather than delivering it to a business sink. Each WebSocket reports open independently, and the existing readiness handshake still waits until mux and host are both open and the `host.describe` HTTP call has succeeded before publishing connected.
 
@@ -36,4 +36,4 @@ Webserver contract tests pin upgrade-pathname dispatch, duplicate-registration r
 
 ## Consequences
 
-Each Web page still has two long-lived downlink connections, but they no longer consume the browser's six-connection HTTP/1.1 quota. The runtime continues to consume the original two streams and retains all reconnect, seam-repair, and cross-stream unordered semantics. The cost is one more upgrade-registration surface in the webserver, a WebSocket implementation dependency in the connection package's host half, and separate maintenance of the browser WebSocket and in-process SSE physical codecs. They share the same `ServerRequest`/frame schemas and `IApiClient` semantics, avoiding a second application protocol.
+Each Web page still has two long-lived downlink connections, but they no longer consume the browser's six-connection HTTP/1.1 quota. The runtime continues to consume the original two streams and retains all reconnect, stream-repair, and cross-stream unordered semantics. The cost is one more upgrade-registration surface in the webserver, a WebSocket implementation dependency in the connection package's host half, and separate maintenance of the browser WebSocket and in-process SSE physical codecs. They share the same `ServerRequest`/frame schemas and `IApiClient` semantics, avoiding a second application protocol.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
index c8c8c34c7b..fb07520602 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
@@ -16,7 +16,7 @@ WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和
 
 ## Upgrade 与生命周期边界
 
-`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册缝，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket message。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和 stream cancellation，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
+`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册点，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket message。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和 stream cancellation，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
 
 浏览器 abort 或 socket close 会取消对应的 host stream；plugin teardown 还会等待该 source iterator 完成清理。host stream 中途抛错时，载体发送一份现有的 `stream/error` frame 后关闭 socket；客户端把该 frame 收敛为连接丢失，不投递给业务 sink。每条 WebSocket 独立报告 open，既有 readiness handshake 仍等待 mux、host 都 open 且 `host.describe` HTTP 调用成功后才发布 connected。
 
@@ -36,4 +36,4 @@ webserver 约定测试钉住 upgrade pathname 分发、重复注册拒绝、disp
 
 ## Consequences
 
-每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；runtime 继续消费原有双流并保留所有重连、补缝和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection host 半依赖 WebSocket 实现，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套业务协议。
+每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；runtime 继续消费原有双流并保留所有重连、流修复和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection host 半依赖 WebSocket 实现，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套业务协议。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index f68aeb97b3..fcac71abf4 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
-2026-08-05-profile-plugin-bundles.zh.md: 8887bd39b7d0002f7c683ec74b7c91f002b18406
+2026-08-05-profile-plugin-bundles.md: 8b5ab0c99282f6868fc3f70781e618af9a317c09
+2026-08-05-profile-plugin-bundles.zh.md: 2a685d68b3de9210488e26f8e6dd93dfc07f956c
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index f183fc5ff5..8b5ab0c992 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -24,7 +24,7 @@ Two supporting refactors: the webserver's built-in static dist serving became th
 
 - **Dependency-scan plus partial `patchOrder`** (the original sketch): scanning `dependencies` for bundles and ordering unlisted ones alphabetically has two sources of truth and an implicit tie-break; one explicit ordered `dsh.profile.bundles` list is smaller and fully deterministic. A raw `pnpm add` inside the profile installs a library without activating any patch — explicit, no spooky scan.
 - **`link:` entries for in-box bundles**: pnpm cannot version, install, or update a `link:` into the installation, it embeds a machine path in a user file, and it breaks when the installation moves. The two-anchor resolution plus healed symlink fallback gives the same guarantee ("bundles come from the installation") without ceremony.
-- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows the launcher patches, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` seam is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
+- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows the launcher patches, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` host hook is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
 - **Transitive bundle auto-application**: only direct `dsh.profile.bundles` entries contribute layers; a meta-bundle wanting to re-export another bundle's patch must do so explicitly in its own patch file.
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 8887bd39b7..2a685d68b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 - **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
-- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` 宿主钩子是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index d59721303b..563a2b6bb1 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.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 .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
-2026-08-05-session-preparation.md: 69d39f552ed3041403a24b5aefb435e4e721b09c
-2026-08-05-session-preparation.zh.md: 23681c7cb52d670482bc83e665ec7731dea98bbd
+2026-08-05-session-preparation.md: 50f1ea38e671c6aa7b0f4adaf2fecbf83decc23c
+2026-08-05-session-preparation.zh.md: 84b5cf48452bb09f8ca2d1572772490b703589da
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
index 69d39f552e..50f1ea38e6 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
@@ -16,7 +16,7 @@ Fresh creation and persisted resume also reached the same publication boundary t
 
 The Agent loop consumes both forms through one setup-and-publication pipeline: it acquires the preparation, builds the private Agent context around `preparation.session`, awaits optional setup, publishes that exact Session and Agent, and disposes the preparation on every exit. Publication transfers the live lifecycle to the existing Session and Agent stores; `SessionPreparation` itself owns no Agent behavior.
 
-This refines the publication boundary from the [Agent lifecycle and ownership decision](2026-06-18-agent-lifecycle-and-ownership-seams.md) without replacing its ownership model.
+This refines the publication boundary from the [Agent lifecycle and ownership decision](2026-06-18-agent-lifecycle-and-ownership-contracts.md) without replacing its ownership model.
 
 ## Persisted preparation lifecycle
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index 23681c7cb5..84b5cf4845 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上对准备对象执行 dispose（资源释放）。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
 
-该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-seams.md)中的发布边界，但不替换其所有权模型。
+该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-contracts.md)中的发布边界，但不替换其所有权模型。
 
 ## 持久化准备生命周期
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 3bf5339f3e..c12ec3a68c 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.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 .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
-2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
-2026-08-06-subagent-list-identity-projection.zh.md: 78aec8f4d0c47178bc033cc74f0314762f49cf7d
+2026-08-06-subagent-list-identity-projection.md: 727c9113fc95a85e6c2732902289a49a76ee8a8d
+2026-08-06-subagent-list-identity-projection.zh.md: c499247a1bd6bd4c971638a29e82f35b16b64690
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
index ba023d0480..727c9113fc 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
@@ -149,7 +149,7 @@ Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entir
 
 **The projection-cache ladder (v3 draft: `cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
 
-**A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new seam primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
+**A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new persistence primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
 
 **Optional mode/label on list rows (one v4 draft).** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index 78aec8f4d0..c499247a1b 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -149,7 +149,7 @@ export type SubagentListEntry =
 
 **projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
 
-**给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
+**给 persistence 加有界读原语抢救存量。** 为一次性问题新开 persistence 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
 **list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 81e53d0e26..12e27bf58c 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
-2026-08-08-client-tool-presentation-ownership.zh.md: 010907144dea256fa97cc6bd49bbcf493ad64c78
+2026-08-08-client-tool-presentation-ownership.md: f12a116c34064186b6be1496e1071025221817c4
+2026-08-08-client-tool-presentation-ownership.zh.md: f5f7d71f1e05b27855d29acc223b340c8d89f1d8
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index 9ea7d7dfc5..f12a116c34 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -20,11 +20,11 @@ Tool is a first-class Client UI concept with one presentation owner, `@deepseek-
 
 `ui-tool` occupies that whole-Tool seat. `ToolCallTree` recursively walks the root block's `subCalls` and routes every level through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. It neither reads Session nor maintains a second call topology.
 
-Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this seam. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
+Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this slot. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
 
 The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
 
-The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation seam, and this package boundary adds no Tool projector/fold registry.
+The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation contract, and this package boundary adds no Tool projector/fold registry.
 
 ## Runtime and render path
 
@@ -102,4 +102,4 @@ Test ownership follows production ownership. `ui-conversation` tests install a l
 
 ## Consequences
 
-`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot seams; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
+`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot contracts; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 010907144d..f5f7d71f1e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -20,11 +20,11 @@ Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool`
 
 `ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
 
-业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 slot 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
 
 details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
 
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
+Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示约定，这个包边界不会增加 Tool projector/fold registry。
 
 ## Runtime 与渲染链路
 
@@ -102,4 +102,4 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Consequences
 
-`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两个跨包 slot seam；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。
+`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两份跨包 slot 约定；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
index eda7b29acf..c9581fcbfb 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.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 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
-2026-07-20-error-cause-chain-diagnostics.md: 89edd4529cc16617fdca736dbbea4b170400d6bd
-2026-07-20-error-cause-chain-diagnostics.zh.md: 673921c913a9f1fefe6f85303cf5952f8edbcc1d
+2026-07-20-error-cause-chain-diagnostics.md: 32716b5a68b3b73bded47633eca95995cdbfc586
+2026-07-20-error-cause-chain-diagnostics.zh.md: 9911c32b6d68c1f5569a1fceadb65e23c6586594
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
index 89edd4529c..32716b5a68 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
@@ -1,4 +1,4 @@
-# Agent Note: Render error cause chains at every diagnostic seam
+# Agent Note: Render error cause chains at every diagnostic boundary
 
 Status: implemented
 
@@ -8,14 +8,14 @@ English | [中文](2026-07-20-error-cause-chain-diagnostics.zh.md)
 
 A TUI run against an unreachable DeepSeek endpoint failed with the single notice `fetch failed` and no further detail. Two independent gaps produced that dead end:
 
-1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic seam in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line.
+1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic boundary in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line.
 2. The readline front door (`dsh-stdio`) rendered no failure reason at all: a `turn/end` with `reason.kind === 'error'` printed nothing but the next `> ` prompt, so the same failure in `demo:repl` was pure silence.
 
 ## Decision
 
 - `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-surface renderer only; routing stays on `HarnessError.code`.
 - The DeepSeek adapter wraps a pre-response transport failure in `LlmError('TRANSPORT')` naming the configured `baseURL` and chaining the original rejection as `cause`. An aborted request becomes `LlmError('ABORTED')`; because the turn signal is already aborted, the loop still classifies the turn as cancellation rather than recovery.
-- Every diagnostic seam renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The live `agent/error` event and `SettleReason` preserve the thrown value as `unknown`; each diagnostic consumer renders it instead of the loop wrapping it into another error. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer.
+- Every diagnostic boundary renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The live `agent/error` event and `SettleReason` preserve the thrown value as `unknown`; each diagnostic Consumer renders it instead of the loop wrapping it into another error. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer.
 - `dsh-stdio` renders failure `turn/end` reasons: `[turn failed <code>] <message>`, `[turn aborted] <reason>`, `[turn rejected] <reason>`, `[turn interrupted by a previous process exit]`, and the output-token-limit notice. Unknown merge-extended kinds fall through as ordinary turn ends.
 
 `errorChain` lives in `dsh-llm` beside `HarnessError` for the same reason the base class does: it is the leaf package every consumer already imports, so sharing costs no new dependency edge.
@@ -32,6 +32,6 @@ A TUI run against an unreachable DeepSeek endpoint failed with the single notice
 
 - A transport failure now reads `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …` in the TUI notice, the readline transcript, and the persisted session log, at the cost of longer diagnostic strings.
 - Durable `turn/end` error messages include cause detail. Existing snapshot fixtures replay byte-identically because their scripted errors carry no `cause` (for such errors `errorChain(err)` equals `err.message`); only unit-test expectation strings changed. A fixture recorded from a real transport failure would carry the chain.
-- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: <message>`), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these seams.
+- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: <message>`), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these diagnostic boundaries.
 - `dsh-stdio` output for failed turns is no longer silent; piped consumers that parsed the transcript see new `[turn …]` lines.
 - Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, and `dsh-workflow-workerthread` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
index 673921c913..9911c32b6d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 在每个诊断界面渲染错误 cause 链
+# Agent Note: 在每个诊断边界渲染错误 cause 链
 
 Status: implemented
 
@@ -8,14 +8,14 @@ Status: implemented
 
 TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed` 通知，没有任何进一步细节。两个独立缺口共同造成了这个死胡同：
 
-1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断界面都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
+1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断边界都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
 2. readline 前门（`dsh-stdio`）完全不渲染失败原因：`reason.kind === 'error'` 的 `turn/end` 只打印下一个 `> ` 提示符，同样的失败在 `demo:repl` 里就是纯粹的沉默。
 
 ## 决策
 
 - `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是用于诊断界面的渲染器；路由仍然基于 `HarnessError.code`。
 - DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('TRANSPORT')`，写明配置的 `baseURL` 并将原始拒绝值作为 `cause` 串入错误链。被中止的请求变为 `LlmError('ABORTED')`；由于轮次信号已处于中止状态，agent loop（智能体循环）仍将该轮次归类为取消而非恢复。
-- 每个诊断界面改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。实时 `agent/error` 事件与 `SettleReason` 以 `unknown` 原样保留抛出值；各诊断消费方自行渲染，而不是由循环把它包装成另一个错误。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
+- 每个诊断边界改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。实时 `agent/error` 事件与 `SettleReason` 以 `unknown` 原样保留抛出值；各诊断 Consumer 自行渲染，而不是由循环把它包装成另一个错误。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
 - `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed <code>] <message>`、`[turn aborted] <reason>`、`[turn rejected] <reason>`、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。通过声明合并扩展出的未知 kind 按普通 turn 结束处理。
 
 `errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费方都已导入的叶子包，共享不增加新的依赖边。
@@ -32,6 +32,6 @@ TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed`
 
 - 传输失败现在在 TUI 通知、readline transcript（文本记录）和持久化会话日志里显示为 `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。
 - 持久化的 `turn/end` 错误消息包含 cause 细节。现有快照 fixture（测试前置数据）字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。
-- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些诊断界面上，链细节被判断为比类名更有价值。
+- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些诊断边界上，链细节被判断为比类名更有价值。
 - `dsh-stdio` 对失败轮次的输出不再沉默；解析 transcript 的管道消费方会看到新的 `[turn …]` 行。
 - `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml
index 4a4e6d71cc..c7891f6a05 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.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 .agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
-2026-07-22-pi-ai-transport-truncation-classification.md: 119200a788c0b0521f385f4cf4e6adf05a0512f9
+2026-07-22-pi-ai-transport-truncation-classification.md: 4f645a26286bac3d95b285d1f37422797775e979
 2026-07-22-pi-ai-transport-truncation-classification.zh.md: 0625d6041ccaeaff9d0d6f659c7b3856ab985ef6
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
index 119200a788..4f645a2628 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
@@ -22,7 +22,7 @@ Classification stays on message text because that is the only signal pi-ai deliv
 
 ## Alternatives considered
 
-**Capture the `cause` via a pi-ai fetch/dispatcher/client hook.** Rejected: pi-ai 0.81.1 exposes none. `StreamOptions` offers only `onPayload`/`onResponse`; `onResponse` fires before the body stream is consumed, so it cannot observe a mid-stream drop. The Anthropic path accepts a `client` object, but constructing and injecting a provider SDK client per request to intercept transport errors reaches around the adapter seam for one diagnostic string.
+**Capture the `cause` via a pi-ai fetch/dispatcher/client hook.** Rejected: pi-ai 0.81.1 exposes none. `StreamOptions` offers only `onPayload`/`onResponse`; `onResponse` fires before the body stream is consumed, so it cannot observe a mid-stream drop. The Anthropic path accepts a `client` object, but constructing and injecting a provider SDK client per request to intercept transport errors reaches around the adapter boundary for one diagnostic string.
 
 **Leave both as `PI_AI_ERROR` and widen `llm-retry`'s retryable set.** Rejected: `PI_AI_ERROR` is the catch-all for genuinely unclassified failures, including non-retryable ones (a malformed provider response, an unexpected SDK bug). Making the catch-all retryable would retry failures that will never succeed; the fix is to classify the recoverable case, not to blur the bucket.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index a14b575c0f..231502dcb7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: dbc3f9e23be9120df62c2b6b7a9d9aba4c3a42a9
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 329392c47d69c4cf3506a5e14ca0ef48d35dce4c
+2026-07-30-web-transcript-log-ordered-projection.md: e261ccba597f27149a9527f99b93454dfe5fe5fb
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 5684a8157bb7e1b23cd868fa13ab201ffd07a274
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index dbc3f9e23b..e261ccba59 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -37,7 +37,7 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 ```
 
-Renaming the seam's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
+Renaming the Service Definition's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
 
 `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` stays as the behavioral half, driving the adapter with a checkpoint built from the canonical **value**. The test value-imports the cordis-free `@deepseek-ai/dsh-compact/checkpoint` leaf and deliberately never loads the compact package root or the host-side `Context` merges reachable through it.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 329392c47d..5684a8157b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -37,7 +37,7 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 ```
 
-重命名缝隙的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
+重命名 Service Definition 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
 
 `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。该测试以值导入方式从不含 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 叶子路径取得该值，并刻意不加载 compact 包根或经由它可达的宿主侧 `Context` 合并。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
index 7832e30b52..e7139bc607 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.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 .agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
-2026-07-31-resume-selector-batch-projection.md: 39146527f13b20813bb6f5d5f1349ecab5724662
-2026-07-31-resume-selector-batch-projection.zh.md: 19bea7211cc61fa7db80370ee3092e5c88bf931b
+2026-07-31-resume-selector-batch-projection.md: 5b0b33c34137efb95f31e07e7fce7622aeb2dbce
+2026-07-31-resume-selector-batch-projection.zh.md: a12df91ba75b7bdc2d9f48dc633ad1689d163180
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
index 39146527f1..5b0b33c341 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
@@ -22,7 +22,7 @@ No session-query or session-persistence surface changed. The shipped TUI composi
 
 ## Alternatives considered
 
-**Keep per-row route/turn/goal columns via a generic batch projection (`projectSessions`).** Implemented first, then rejected: it still decompressed and parsed every log on every `/resume`, so browsing cost stayed O(total log bytes), and it grew the session-query public API for one consumer. The public seam was reverted; `readTitleSnapshots` keeps using the internal `projectMany` unchanged.
+**Keep per-row route/turn/goal columns via a generic batch projection (`projectSessions`).** Implemented first, then rejected: it still decompressed and parsed every log on every `/resume`, so browsing cost stayed O(total log bytes), and it grew the session-query public API for one consumer. The public contract was reverted; `readTitleSnapshots` keeps using the internal `projectMany` unchanged.
 
 **Fix only the O(N²) listing inside `SessionCorpus.load()`.** Rejected as the primary fix: the per-candidate full decompress, replay validation, and triple clone dominated on large logs. The redundant pre-listing in `load()` remains a candidate cleanup with error-semantics implications.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
index 19bea7211c..a12df91ba7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
@@ -22,7 +22,7 @@ session-query 与 session-persistence 的任何表面都未改变。随附的 TU
 
 ## Alternatives considered
 
-**通过通用批量投影（`projectSessions`）保留每行的路由/轮次/目标列。** 先实现后否决：它仍在每次 `/resume` 时解压并解析全部日志，浏览开销依旧是 O(日志总字节数)，且为单一消费者扩大了 session-query 公开 API。该公开 seam 已回退；`readTitleSnapshots` 继续使用内部 `projectMany`，保持不变。
+**通过通用批量投影（`projectSessions`）保留每行的路由/轮次/目标列。** 先实现后否决：它仍在每次 `/resume` 时解压并解析全部日志，浏览开销依旧是 O(日志总字节数)，且为单一消费者扩大了 session-query 公开 API。该公开约定已回退；`readTitleSnapshots` 继续使用内部 `projectMany`，保持不变。
 
 **只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index 3a9d189fb5..c20fdb52b5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: 2174cb466c6af72f15005ce1ba3dec8100de6f2f
-2026-08-06-api-key-format-validation.zh.md: 540239c34637eb5940be105127f3367e0969acfa
+2026-08-06-api-key-format-validation.md: f404a3bed728f9917f794f9c06f1a9dad32e64c8
+2026-08-06-api-key-format-validation.zh.md: a94d7eb577a84e7adf440c034aebe603faec7f64
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index 2174cb466c..f404a3bed7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -42,9 +42,9 @@ The rule applies to a value that was *provided*; deciding whether one was provid
 
 ### Where the rule lives
 
-`normalizeApiKey` is a module of the `dsh-llm` seam, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
+`normalizeApiKey` is a module of the `dsh-llm` Service Definition, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
 
-Both adapters also need the identical "refuse a stored credential" diagnosis, differing only by package prefix. `LlmError` is declared in the seam's `index.ts`, so `assertUsableApiKey(raw, pkg, ref)` lives there beside it and neither adapter carries a local copy. The predicate module stays dependency-free: importing `LlmError` into `api-key.ts` would cycle with `index.ts`'s re-export of it.
+Both adapters also need the identical "refuse a stored credential" diagnosis, differing only by package prefix. `LlmError` is declared in the Service Definition's `index.ts`, so `assertUsableApiKey(raw, pkg, ref)` lives there beside it and neither adapter carries a local copy. The predicate module stays dependency-free: importing `LlmError` into `api-key.ts` would cycle with `index.ts`'s re-export of it.
 
 The client cannot import any of this: client packages reference only client packages, so `packages/client/ui-models` mirrors the predicate in its own `apiKey.ts` and owns the localized messages, exactly as `validateDeepSeekModels` mirrors the host's `catalogModel` schema. Each side names the other in a comment.
 
@@ -66,7 +66,7 @@ The client cannot import any of this: client packages reference only client pack
 
 **A validation module shared by client and host.** Rejected by the source-plane layout: client packages reference only client packages plus `vendor/cordis` and `support/invariants`, and widening that to reach a host package would collide the two `Context` merges the split exists to keep apart. Mirroring a one-line predicate with a test on each side is the established shape here.
 
-**A per-adapter thrower in each of `llm-deepseek` and `llm-pi-ai`.** The first plan gave each adapter its own, differing only by the package prefix in the message, with a duplication-gate exemption to excuse the pair. Rejected before implementation: `LlmError` is declared in the seam, so the seam can own the diagnosis outright, and an exemption there would have hidden exactly the duplication it was covering for.
+**A per-adapter thrower in each of `llm-deepseek` and `llm-pi-ai`.** The first plan gave each adapter its own, differing only by the package prefix in the message, with a duplication-gate exemption to excuse the pair. Rejected before implementation: `LlmError` is declared in the Service Definition, so that package can own the diagnosis outright, and an exemption there would have hidden exactly the duplication it was covering for.
 
 **Sniffing the `TypeError` in the adapter's `catch`.** This would classify the ByteString failure after the fact, leaving the header construction itself unguarded. It depends on the wording of a Node error message, so it degrades silently across runtime versions, and it cannot help `llm-pi-ai`, whose request header is built inside the pi-ai SDK. Refusing the key before handing it over works for both adapters and for the discovery probe.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index 540239c346..a94d7eb577 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -42,9 +42,9 @@ Status: implemented
 
 ### 规则住在哪里
 
-`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费方而非一个预设消费方。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
+`normalizeApiKey` 是 `dsh-llm` Service Definition 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费方而非一个预设消费方。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
 
-两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 seam 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
+两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 Service Definition 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
 
 客户端无法引入其中任何一个：client 包只 reference client 包，因此 `packages/client/ui-models` 在自己的 `apiKey.ts` 中镜像这个断言并持有本地化文案，正如 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
 
@@ -66,7 +66,7 @@ Status: implemented
 
 **由 client 与 host 共享一个校验模块。** 被 source plane 布局否决：client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`，把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试，是此处的既定形态。
 
-**在 `llm-deepseek` 与 `llm-pi-ai` 中各留一个抛错 helper。** 最初的计划正是各留一份，差别仅在消息中的包名前缀，并配一个重复检测豁免来放行这一对。在实现之前即被否决：`LlmError` 声明在 seam 中，因此 seam 完全可以自己拥有这句诊断，而那里的一个豁免恰恰会掩盖它本要遮掩的重复。
+**在 `llm-deepseek` 与 `llm-pi-ai` 中各留一个抛错 helper。** 最初的计划正是各留一份，差别仅在消息中的包名前缀，并配一个重复检测豁免来放行这一对。在实现之前即被否决：`LlmError` 声明在 Service Definition 中，因此该包完全可以自己拥有这句诊断，而那里的一个豁免恰恰会掩盖它本要遮掩的重复。
 
 **在适配器的 `catch` 中嗅探 `TypeError`。** 这只是事后归类 ByteString 失败，header 构造本身仍无防护。它依赖 Node 错误消息的措辞，因而会随运行时版本静默失效；它也帮不到 `llm-pi-ai`——后者的请求 header 构造在 pi-ai SDK 内部。在交出 Key 之前就拒绝，则对两个适配器与探测路径同时有效。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 97e5ee763f..34e437c316 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: 87e39d7b68dd1dc2ebdee57f731be30d396a907b
+2026-06-15-code-mode.md: 8a6fa068a4c7fee6fbfd9e16757a0fae5efa0c8b
+2026-06-15-code-mode.zh.md: 00d4fd48b83e183d45423722bf223a63e305d5a4
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 99bbed3eda..8a6fa068a4 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -19,7 +19,7 @@ Tool presentation belongs to the registry that owns tool visibility: implementin
 Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
-2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
+2. **Code execution is a capability seam** — `packages/code-runtime/` contains the Service Definition package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); Consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another Service provider package, not a redesign.
 3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
@@ -118,7 +118,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Risks
 
-**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
+**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same approval and sandbox policies. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
 
 **`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 87e39d7b68..00d4fd48b8 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -19,7 +19,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 三项决策，各自在下方独立小节中展开：
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
-2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包`@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
+2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含 Service Definition 包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；Consumer = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个 Service provider 包，而非重新设计。
 3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
@@ -118,7 +118,7 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 ## 风险
 
-**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
+**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的审批与沙箱策略。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的约定线，错误路径是一个可工作的反馈循环，而非死胡同。
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 586cab797e..860156eb06 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.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 .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
-2026-06-17-filesystem-tool-schemas.md: 9941b3916b361a916c8148eb099eb8cfd46371c8
-2026-06-17-filesystem-tool-schemas.zh.md: 8ba3c18629863ca9f04548d5993e9d200ecd4912
+2026-06-17-filesystem-tool-schemas.md: b48f8e5d44913f2b6a2b7e1b19269c58e72efd1f
+2026-06-17-filesystem-tool-schemas.zh.md: ad4081d28950a4a2df4f5718038e2a4124bf70b5
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
index 9941b3916b..b48f8e5d44 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
@@ -20,7 +20,7 @@ The schema should be small enough to implement in the first `dsh-tool-fs` pass,
 | `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Under the default fs-policy, updates to existing files require a prior observation; new-file creates do not. | YES |
 | `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; under the default fs-policy requires a prior observation (any windowed read counts). | YES |
 
-The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The consumer package translates these model-facing names into `ctx.fs` calls and `fs/*` event dispatches.
+The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The Consumer package translates these model-facing names into `ctx.fs` calls and `fs/*` event dispatches.
 
 ## Tool schemas
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
index 8ba3c18629..ad4081d289 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 | `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | 创建或覆盖 UTF-8 文本。在默认 fs-policy 下，更新现有文件前必须先观测；创建新文件则不需要。 | 是 |
 | `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | 字面字符串替换；默认要求唯一匹配；在默认 fs-policy 下必须先观测（任意窗口读取均算作观测）。 | 是 |
 
-schema 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。消费方包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
+schema 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。Consumer 包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
 
 ## 工具 schema
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index c23637d7e3..1ab18b72e9 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: fa9325d08fa73dd1654216d211abb03cdf1a0940
-2026-06-18-compaction-capability-seam.zh.md: d8522f3714211f23bafb201e7354e8b0fc2f5fb1
+2026-06-18-compaction-capability-seam.md: 6357482600fabd0354325a19118ec245eee5d855
+2026-06-18-compaction-capability-seam.zh.md: a5c60c667734f119a8bd9d9b6a8fbc9c66155470
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index fa9325d08f..6357482600 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -14,7 +14,7 @@ Two forces shape the design. First, compaction policy and reusable token measure
 
 ## Decision
 
-### Compaction is a capability seam, split interface / implementation
+### Compaction is a capability seam with separate Service Definition and Service provider roles
 
 Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md), compaction ships as separate packages so the contract, the algorithm, and (later) the consumer surface evolve independently:
 
@@ -25,7 +25,7 @@ Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seam
 
 ### The contract depends on `dsh-session` and `dsh-llm` — a deliberate deviation
 
-The capability-seams Agent Note states the interface package "depends only on cordis" (true of `dsh-bash`, whose vocabulary is self-contained). Compaction **cannot** honor that: its verbs act on an agent-owned `Session` (`compactRegion(start, end, agent)`) and its output uses the content vocabulary (`CompactionResult.summary: ContentBlock[]`). There is no way to express the contract without naming `Session`/`SessionEvent` (from `dsh-session`) and `ContentBlock` (from `dsh-llm`).
+The capability-seams Agent Note states the Service Definition package "depends only on cordis" (true of `dsh-bash`, whose vocabulary is self-contained). Compaction **cannot** honor that: its verbs act on an agent-owned `Session` (`compactRegion(start, end, agent)`) and its output uses the content vocabulary (`CompactionResult.summary: ContentBlock[]`). There is no way to express the contract without naming `Session`/`SessionEvent` (from `dsh-session`) and `ContentBlock` (from `dsh-llm`).
 
 This is not a coupling smell — it is the contract's domain. The "only cordis" guidance was always shorthand for "the interface depends only on what the contract genuinely names, and never on an implementation." `dsh-session` and `dsh-llm` are themselves interface/vocabulary packages, not implementations; `dsh-compact` still imports no backend. The seam's real invariant — *consumers and implementations evolve independently behind an abstract service* — holds intact.
 
@@ -119,7 +119,7 @@ The lifecycle boundary makes crash state unambiguous:
 ## Consequences
 
 - **Packages**: `packages/compact/compact` supplies the interface, `compact-basic` supplies the backend, `compact-tool-result-prune` supplies optional deterministic rewriting, and `command-compact` supplies human `/compact`. `packages/llm/token-meter` owns replay-aware measurement independently.
-- **Automatic seams**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
+- **Automatic extension points**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
 - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry.
 - **`dsh-compact`** owns `COMPACT_CHECKPOINT_SOURCE`, `isCompactCheckpointSource(source)`, `toolPairingBalancedBefore(session, seq)`, and `toolPairingBalancedAfter(session, seq)`. The marker identifies replacement summaries across backend implementations. The cached surface-edge checks prevent `compactRegion` and `compactIfNeeded` from splitting a tool-call/result pair, validate current membership by seq, answer both edges from one per-cut balance sequence, and reject stale or missing seqs and orphan results.
 - **`dsh-session`** validates positional replacement, complete cited source-event coverage, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index d8522f3714..a5c60c6677 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-### 压缩是一个能力 seam，接口与实现分离
+### 压缩是一个能力 seam，Service Definition 与 Service provider 角色分离
 
 遵循[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)，压缩以独立包发布，使约定、算法和（后续的）消费方 surface 各自独立演进：
 
@@ -25,7 +25,7 @@ Status: implemented
 
 ### 约定依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离
 
-能力 seam Agent Note 规定接口包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），约定就无法表达。
+能力 seam Agent Note 规定 Service Definition 包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），约定就无法表达。
 
 这不是耦合异味，而是约定的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖约定真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
-`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV Cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
+`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
 ### 成功的持久步骤工作完成后运行自动压力检查
 
@@ -119,7 +119,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 ## 后果
 
 - **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写，`command-compact` 提供面向用户的 `/compact`。`packages/llm/token-meter` 独立拥有回放感知的测量。
-- **自动 seam**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
+- **自动扩展点**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
 - **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
 - **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。
 - **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、引用的来源事件是否覆盖完整，以及仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index 45dc5edb5c..ac018acdc8 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 752e639b09ea2ac0ba19841ddfe38b15b44d22e9
-2026-06-21-subagent-capability-seam.zh.md: f0b0ba2ab8b0bb7b611e995c56e30db68b21cfa7
+2026-06-21-subagent-capability-seam.md: 553411a0d8f989c883e3eea929669ccebcfe807b
+2026-06-21-subagent-capability-seam.zh.md: 5fa2bd62828e9afcb79647ec4821c2da1da041e7
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 752e639b09..553411a0d8 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -14,18 +14,18 @@ The distinctive requirement — the one that shapes the whole design — is that
 
 - **in-process** — a child concrete `Agent` on the same `Context` (the cheapest, and nearly free given the existing agent factory);
 - **ACP** — act as an ACP *client* driving another agent process (which can be another instance of ourselves);
-- **Codex app-server and Claude Code Agent SDK** — current one-shot siblings that apply the same named-provider seam to official product processes ([product-provider Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md));
+- **Codex app-server and Claude Code Agent SDK** — current one-shot siblings that apply the same named-provider contract to official product processes ([product-provider Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md));
 - later: **A2A** using the same out-of-process "start a child, prompt it, settle, cancel" shape.
 
 ## Alternatives considered
 
 ### Why not the bash seam shape
 
-The bash seam ([capability seams](../architecture/2026-06-13-capability-seams.md)) registers exactly one `BashExecutor` per context; loading a second throws. That is correct for bash (one machine, one way to run a command) but wrong here: coexistence is the requirement. So the subagent service is a **named-provider registry** — each implementation registers under a unique name and a caller picks one by name — mirroring the **LLM adapter registry** (`LlmService.registerAdapter`), not the single-service bash executor. The seam is still three-package (interface / implementation / consumer); only the "one vs. many implementations" axis differs.
+The bash seam ([capability seams](../architecture/2026-06-13-capability-seams.md)) registers exactly one `BashExecutor` per context; loading a second throws. That is correct for bash (one machine, one way to run a command) but wrong here: coexistence is the requirement. So the subagent service is a **named-provider registry** — each implementation registers under a unique name and a caller picks one by name — mirroring the **LLM adapter registry** (`LlmService.registerAdapter`), not the single-service bash executor. The seam is still three-package (Service Definition / Service provider / Consumer); only the "one vs. many implementations" axis differs.
 
 ## Decision
 
-### The three-package seam
+### The three-package boundary
 
 A new package group `packages/subagent/`:
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index f0b0ba2ab8..5fa2bd6282 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -14,18 +14,18 @@ harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
-- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性同类提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
+- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性同类提供方，将同一个命名提供方约定应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
 - 后续：**A2A**，采用同样的进程外形态：「启动子 agent、发送提示词、结算、取消」。
 
 ## 曾考虑的替代方案
 
 ### 为何不采用 bash seam 的形状
 
-bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口、实现、消费方）；只是「一个 vs. 多个实现」这个维度不同。
+bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（Service Definition / Service provider / Consumer）；只是「一个 vs. 多个实现」这个维度不同。
 
 ## 决策
 
-### 由三个包构成的 seam
+### 由三个包构成的边界
 
 新建包组 `packages/subagent/`：
 
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index e55d06834c..4cf94795a8 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.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 .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
-2026-06-22-acp-subagent-backend.md: c994ebfa69649bb9e79d3aa389a0e13c178131c7
-2026-06-22-acp-subagent-backend.zh.md: 79be03dfc8310f6fc759d620c36d0d279c703073
+2026-06-22-acp-subagent-backend.md: 211030a6ecc9b6f673174ba410415c7bd80818ef
+2026-06-22-acp-subagent-backend.zh.md: 2dde3d96329cc47d9c7cca08e1d25764c32f8ebe
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
index c994ebfa69..211030a6ec 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
@@ -59,4 +59,4 @@ Every run pays a fresh subprocess (spawn + `initialize` + `newSession`). The par
 
 ## Product-provider siblings
 
-The [Codex app-server and Claude Code Agent SDK providers](2026-08-04-claude-code-and-codex-subagent-backends.md) apply the same out-of-process spawn/prompt/settle/cancel boundary as siblings registered by name. A2A remains a future sibling transport; the ACP backend proves that the common seam supports this boundary without owning product-private protocols.
+The [Codex app-server and Claude Code Agent SDK providers](2026-08-04-claude-code-and-codex-subagent-backends.md) apply the same out-of-process spawn/prompt/settle/cancel boundary as siblings registered by name. A2A remains a future sibling transport; the ACP backend proves that the subagent seam supports this boundary without owning product-private protocols.
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index 79be03dfc8..2dde3d9632 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -59,4 +59,4 @@ ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`
 
 ## 兄弟产品提供方
 
-[Codex app-server 与 Claude Code Agent SDK 提供方](2026-08-04-claude-code-and-codex-subagent-backends.md)作为按名称注册的兄弟提供方，采用同样的进程外启动/提示词/结算/取消边界。A2A 仍是未来的兄弟传输方式；ACP 后端证明了通用 seam 能够支持这项边界，而无需负责产品私有协议。
+[Codex app-server 与 Claude Code Agent SDK 提供方](2026-08-04-claude-code-and-codex-subagent-backends.md)作为按名称注册的兄弟提供方，采用同样的进程外启动/提示词/结算/取消边界。A2A 仍是未来的兄弟传输方式；ACP 后端证明了 subagent seam 能够支持这项边界，而无需负责产品私有协议。
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
index de978c055c..96e76345cc 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.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 .agents/notes/implemented/feature/2026-06-30-hook-bridges.md
-2026-06-30-hook-bridges.md: a31116818c57e18d04e656f371efd1101a63b6af
-2026-06-30-hook-bridges.zh.md: 0fa76c0cee0f74101e70f44d442daa2fb46e6649
+2026-06-30-hook-bridges.md: eecc1fc75c10618481231083f890e0e4b122c1ee
+2026-06-30-hook-bridges.zh.md: dcc8f496cb3bc6ea7857ce804a9159cbfcbc3f08
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
index a31116818c..eecc1fc75c 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
@@ -6,9 +6,9 @@ English | [中文](2026-06-30-hook-bridges.zh.md)
 
 ## Problem
 
-The harness's extension surface is its typed interception seams ([the interception-seams Agent Note](2026-06-30-interception-seams.md)): a "native hook" is just an ordinary cordis plugin subscribing to `agent/session-start`, `agent/pre-step`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-stopping`, `subagent/start`, or `subagent/end`. But users arrive with **existing** Claude Code (CC) and Codex hook configs — a `hooks.json` (or a settings file's `hooks` key) full of shell-command hooks — and want those to run unmodified. This Agent Note introduces the two **bridge plugins** that translate that external shell-hook protocol onto the typed seams, built on the shared wire-protocol library ([the hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)).
+The harness's extension surface is its typed interception points ([the interception extension-points Agent Note](2026-06-30-interception-extension-points.md)): a "native hook" is just an ordinary cordis plugin subscribing to `agent/session-start`, `agent/pre-step`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-stopping`, `subagent/start`, or `subagent/end`. But users arrive with **existing** Claude Code (CC) and Codex hook configs — a `hooks.json` (or a settings file's `hooks` key) full of shell-command hooks — and want those to run unmodified. This Agent Note introduces the two **bridge plugins** that translate that external shell-hook protocol onto the typed extension points, built on the shared wire-protocol library ([the hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)).
 
-The framing that shapes the whole design: **a bridge is a compatibility adapter, not a power tool.** Anything a bridge does (block a tool, inject context, force continuation, observe a subagent) a native cordis plugin does more powerfully — typed returns, full `ctx`, no serialization boundary. The bridge's reason to exist is to run the explicitly supported subset of external CC/Codex command hooks. That keeps each bridge thin: parse the config, pick a matcher mode, build the per-event payload, call `runHook` + `mergeHookOutputs` from the shared lib, and map the neutral outcome onto a seam Decision. The package READMEs own the exact current unsupported-event and partial-field inventory against the official protocols.
+The framing that shapes the whole design: **a bridge is a compatibility adapter, not a power tool.** Anything a bridge does (block a tool, inject context, force continuation, observe a subagent) a native cordis plugin does more powerfully — typed returns, full `ctx`, no serialization boundary. The bridge's reason to exist is to run the explicitly supported subset of external CC/Codex command hooks. That keeps each bridge thin: parse the config, pick a matcher mode, build the per-event payload, call `runHook` + `mergeHookOutputs` from the shared lib, and map the neutral outcome to a typed Decision. The package READMEs own the exact current unsupported-event and partial-field inventory against the official protocols.
 
 ## Decision
 
@@ -19,9 +19,9 @@ Two independent plugins in the `packages/hooks/` group, each a function/namespac
 
 ### Outcome → Decision mapping
 
-Each bridge maps the neutral `MergedHookOutcome` from the shared lib onto the seam's typed Decision:
+Each bridge maps the neutral `MergedHookOutcome` from the shared lib onto each extension point's typed Decision:
 
-| Seam | CC | Codex |
+| Extension point | CC | Codex |
 |---|---|---|
 | `agent/session-start` (emit) | additionalContext → `agent.inject()` | plain-stdout output → additionalContext → `agent.inject()` |
 | `agent/pre-step` | `deny`→`reject`; context-only→delegate+fold into `enter` | `block`→`reject`; context-only→delegate+fold into `enter` |
@@ -59,9 +59,9 @@ Hooks run in the agent's session workspace, so relative paths target the user's
 
 - **Tool-input rewrite.** A CC/Codex `updatedInput` is logged + warned, not honored — input rewrite is a deferred consistency-design problem ([the pre-tool-input-rewrite Agent Note](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)), because the pre-execution args are read by `tool/call` audit + `assistant/message` history + tool presentation, so an honest rewrite is a design unit, not a field.
 - **Stop loop-guard** (`TODO(stop-loop-guard)`). Claude Code supplies `stop_hook_active` and overrides a hook after eight consecutive blocks; Codex supplies `stop_hook_active` but documents no equivalent cap. Both bridges always report `false`, so a Stop hook that unconditionally blocks force-continues every step — a hook author must self-limit until state tracking lands.
-- **Hook `continue:false` (hard halt).** A hook can ask to halt the whole run (CC/Codex `continue:false`); the shared merge folds it into `MergedHookOutcome.stop`/`stopReason`, but no bridge acts on it (`TODO(hook-continue-false)`) — the interception seams have no "hard-halt the agent" primitive yet (a Decision blocks/steers a single point, not the run). Deferred with the loop-guard work; mid-turn requests record the halt in `hook/result`, and the hook keeps its per-point effect (decision/context) meanwhile.
+- **Hook `continue:false` (hard halt).** A hook can ask to halt the whole run (CC/Codex `continue:false`); the shared merge folds it into `MergedHookOutcome.stop`/`stopReason`, but no bridge acts on it (`TODO(hook-continue-false)`) — the interception points have no "hard-halt the agent" primitive yet (a Decision blocks/steers a single point, not the run). Deferred with the loop-guard work; mid-turn requests record the halt in `hook/result`, and the hook keeps its per-point effect (decision/context) meanwhile.
 - **Config discovery.** The path is explicit in `cordis.yml` and process-level (see above); the full multi-layer CC/Codex precedence walk, per-session project-local discovery, and the trust/hash model are not reimplemented (`TODO(per-session-hook-config)`).
-- **Session-start / subagent-start context is best-effort (`TODO(session-start-gating)`).** Both hooks run detached from startup, so their context is injected when ready but may miss the first request or a short-lived child. Guaranteeing first-request delivery requires an awaited startup seam.
+- **Session-start / subagent-start context is best-effort (`TODO(session-start-gating)`).** Both hooks run detached from startup, so their context is injected when ready but may miss the first request or a short-lived child. Guaranteeing first-request delivery requires an awaited startup extension point.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
index 0fa76c0cee..dcc8f496cb 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](2026-06-30-interception-seams.md)）：所谓「原生钩子」不过是一个普通的 Cordis 插件，订阅 `agent/session-start`、`agent/pre-step`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-stopping`、`subagent/start` 或 `subagent/end`。但用户带着**既有的** Claude Code（CC）和 Codex 钩子配置到来，一个 `hooks.json`（或 settings 文件中的 `hooks` 键）里满是 shell 命令钩子，并希望它们原样运行。本 Agent Note 引入两个**桥接插件**，将外部 shell 钩子协议翻译到类型化 seam 上，构建于共享的协议格式（wire format）库之上（见 [hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)）。
+harness 的扩展面是其类型化拦截点（见[拦截扩展点 Agent Note](2026-06-30-interception-extension-points.md)）：所谓「原生钩子」不过是一个普通的 Cordis 插件，订阅 `agent/session-start`、`agent/pre-step`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-stopping`、`subagent/start` 或 `subagent/end`。但用户带着**既有的** Claude Code（CC）和 Codex 钩子配置到来，一个 `hooks.json`（或 settings 文件中的 `hooks` 键）里满是 shell 命令钩子，并希望它们原样运行。本 Agent Note 引入两个**桥接插件**，将外部 shell 钩子协议翻译到类型化扩展点上，构建于共享的协议格式（wire format）库之上（见 [hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)）。
 
-贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为 seam Decision。各包的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
+贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为类型化 Decision。各包的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
 
 ## 决策
 
@@ -19,9 +19,9 @@ harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](
 
 ### Outcome → Decision 映射
 
-每个桥接将共享库返回的中性 `MergedHookOutcome` 映射到 seam 的类型化 Decision：
+每个桥接将共享库返回的中性 `MergedHookOutcome` 映射到各扩展点的类型化 Decision：
 
-| Seam | CC | Codex |
+| 扩展点 | CC | Codex |
 |---|---|---|
 | `agent/session-start`（emit） | additionalContext → `agent.inject()` | 纯 stdout 输出 → additionalContext → `agent.inject()` |
 | `agent/pre-step` | `deny`→`reject`；仅上下文→委托并折叠到 `enter` | `block`→`reject`；仅上下文→委托并折叠到 `enter` |
@@ -59,9 +59,9 @@ Claude Code 始终导出 `CLAUDE_PROJECT_DIR`，常见的未修改钩子引用 `
 
 - **工具输入重写。** CC/Codex 的 `updatedInput` 被记录日志并发出警告，但不予执行——输入重写是一个推迟的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)），因为 pre-execution 参数被 `tool/call` 审计、`assistant/message` 历史和工具展示共同读取，诚实的重写是一个设计单元，而非一个字段。
 - **Stop 循环防护**（`TODO(stop-loop-guard)`）。Claude Code 提供 `stop_hook_active` 并在连续八次阻塞后覆盖钩子；Codex 提供 `stop_hook_active` 但未记录等效上限。两个桥接始终报告 `false`，因此一个无条件阻塞的 Stop 钩子会在每一步强制继续——在状态追踪落地之前，钩子作者必须自行限制。
-- **钩子 `continue:false`（硬停止）。** 钩子可以请求终止整个运行（CC/Codex `continue:false`）；共享合并将其折叠为 `MergedHookOutcome.stop`/`stopReason`，但没有桥接对其采取行动（`TODO(hook-continue-false)`）——拦截 seam 尚无「硬停止 agent」原语（Decision 阻塞/引导的是单个点，而非整个运行）。与循环防护工作一同推迟；轮中请求会将停止请求记录在 `hook/result` 中，钩子在此期间保留其逐点效果（决策/上下文）。
+- **钩子 `continue:false`（硬停止）。** 钩子可以请求终止整个运行（CC/Codex `continue:false`）；共享合并将其折叠为 `MergedHookOutcome.stop`/`stopReason`，但没有桥接对其采取行动（`TODO(hook-continue-false)`）——拦截点尚无「硬停止 agent」原语（Decision 阻塞/引导的是单个点，而非整个运行）。与循环防护工作一同推迟；轮中请求会将停止请求记录在 `hook/result` 中，钩子在此期间保留其逐点效果（决策/上下文）。
 - **配置发现。** 路径在 `cordis.yml` 中显式指定且为进程级（见上文）；完整的多层 CC/Codex 优先级遍历、按会话的项目本地发现以及信任/hash 模型未被重新实现（`TODO(per-session-hook-config)`）。
-- **Session-start / subagent-start 上下文为尽力而为（`TODO(session-start-gating)`）。** 两个钩子以 detached 方式运行，不阻塞启动流程，因此其上下文在就绪时注入，但可能错过首个请求或短命的 subagent。要保证首请求送达，需要一个 awaited 的启动 seam。
+- **Session-start / subagent-start 上下文为尽力而为（`TODO(session-start-gating)`）。** 两个钩子以 detached 方式运行，不阻塞启动流程，因此其上下文在就绪时注入，但可能错过首个请求或短命的 subagent。要保证首请求送达，需要一个 awaited 的启动扩展点。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index b5b5ea3b97..547f88999e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.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 .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
-2026-06-30-hook-protocol-lib.md: 2edff0d501cd7695873c68054eeb3a1e9942eced
-2026-06-30-hook-protocol-lib.zh.md: 90648c535e8bccd264ef9ae1ffd5f66590b1ac6d
+2026-06-30-hook-protocol-lib.md: 576a126e1022ac72265c476e03ef36aaf17f78b4
+2026-06-30-hook-protocol-lib.zh.md: f2554eaa378a26bf8254d86d458e0de5ce1aa4fd
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
index 2edff0d501..576a126e10 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
@@ -21,7 +21,7 @@ A new `packages/hooks/` group with `hook-protocol` as a pure library. It owns fo
 - **Merge** — `mergeHookOutputs(outputs)`, folding multiple matched hooks into one most-restrictive `MergedHookOutcome`: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined `\n\n`, context/system-messages accumulated in order.
 - **`hook/*` session events** — `hook/invoked` / `hook/result`, declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT `SurfaceEventType`s), with `appendHookInvoked`/`appendHookResult` helpers so the invoked/result pairing and owner-defined execution relation stay consistent across bridges. `appendHookResult` also owns the durable record's semantics — the decision string (the hook's parsed decision, else `'stop'` on `continue:false`, else `'pass'`) and the 500-character `stderrSummary` truncation derive from the `HookOutput` here, not per-bridge.
 
-**Per-dialect (the bridge plugins):** building each event's stdin payload (CC's base+per-event field sets vs Codex's snake_case with `turn_id`/`model` extras), the dialect's env + `${CLAUDE_PLUGIN_ROOT}` substitution (CC) vs none (Codex), and mapping the neutral `HookOutput`/`MergedHookOutcome` onto the harness's seam-specific typed Decisions (`PreToolDecision`, `PreStepDecision`, `ContinuationDecision`, `PostToolDecision`).
+**Per-dialect (the bridge plugins):** building each event's stdin payload (CC's base+per-event field sets vs Codex's snake_case with `turn_id`/`model` extras), the dialect's env + `${CLAUDE_PLUGIN_ROOT}` substitution (CC) vs none (Codex), and mapping the neutral `HookOutput`/`MergedHookOutcome` onto the harness's extension-point-specific typed Decisions (`PreToolDecision`, `PreStepDecision`, `ContinuationDecision`, `PostToolDecision`).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index 90648c535e..f2554eaa37 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 - **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
 
-**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 两者皆无（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
+**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 无替换（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness 各扩展点专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
similarity index 56%
rename from .agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
rename to .agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
index b436887b7a..6955ae64a6 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
@@ -1,6 +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 .agents/notes/implemented/feature/2026-06-30-interception-seams.md
-2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
-2026-06-30-interception-seams.zh.md: 110b28d48a342b50f8e5c1024ed2f2df704e4099
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
+2026-06-30-interception-extension-points.md: 68be3c94f55ae13155e9b22cb91ef1ad10b1e0ed
+2026-06-30-interception-extension-points.zh.md: 262793dd7a297f343391a22fb8d9f1d57a9ff531
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
similarity index 83%
rename from .agents/notes/implemented/feature/2026-06-30-interception-seams.md
rename to .agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
index 3b2c62cd44..68be3c94f5 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
@@ -1,18 +1,18 @@
-# Agent Note: Interception seams — the typed-Decision surface a hook programs against
+# Agent Note: Interception extension points — the typed-Decision surface a hook programs against
 
 Status: implemented
 
-English | [中文](2026-06-30-interception-seams.zh.md)
+English | [中文](2026-06-30-interception-extension-points.zh.md)
 
 ## Problem
 
 The harness needs a hooks subsystem: users extend or gate the agent at lifecycle points the way Claude Code (CC) and Codex do. The key reframe driving this design is that **"native hooks" are not a package** — a native hook is just an ordinary Cordis plugin subscribing to the canonical lifecycle events. So the real product is a *powerful, well-typed canonical event surface*; the CC/Codex bridges (the `dsh-hooks-claude` / `dsh-hooks-codex` packages) are merely translators that map an external shell-hook protocol onto that same surface. Anything a bridge can do, a plain plugin can do directly — more powerfully (no serialization boundary, full `ctx`, typed returns).
 
-The surface needs distinct contracts for per-prompt policy (CC's `UserPromptSubmit`), session-start observation (CC's `SessionStart`), pre-tool policy, around-dispatch control, post-tool transformation, final-result observation, and continuation with a model-facing reason. Conflating those phases gives plugins mutation channels they do not need and makes finality depend on listener ordering. The [event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md) supplies the three-domain rule and the typed-Decision idiom; this Agent Note applies them to the lifecycle seams.
+The surface needs distinct contracts for per-prompt policy (CC's `UserPromptSubmit`), session-start observation (CC's `SessionStart`), pre-tool policy, around-dispatch control, post-tool transformation, final-result observation, and continuation with a model-facing reason. Conflating those phases gives plugins mutation channels they do not need and makes finality depend on listener ordering. The [event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md) supplies the three-domain rule and the typed-Decision idiom; this Agent Note applies them to the lifecycle extension points.
 
 ## Decision
 
-The canonical surface separates transformable policy, around-dispatch control, and observe-only notification. Policy waterfalls return small seam-specific **typed Decision unions**; wrappers return normalized results; notifications receive immutable snapshots and cannot affect the outcome. The set covers the hook points in scope (`session-start`, `prompt-submit`, `pre-tool`, `post-tool`, `stop`-via-continuation) while leaving non-hook execution policy independently composable.
+The canonical surface separates transformable policy, around-dispatch control, and observe-only notification. Policy waterfalls return small extension-point-specific **typed Decision unions**; wrappers return normalized results; notifications receive immutable snapshots and cannot affect the outcome. The set covers the hook points in scope (`session-start`, `prompt-submit`, `pre-tool`, `post-tool`, `stop`-via-continuation) while leaving non-hook execution policy independently composable.
 
 **Agent events** (`dsh-agent`):
 - `agent/session-start({ agent, source })` — emit, once before turn 1, carrying a `SessionStartSource` (`startup` for a fresh/forked create, `resume` for a reloaded persisted session; `clear`/`compact` reserved). A pure notification — it CANNOT block startup (a deliberate gap: a bridge logs/injects, it does not gate startup). A listener seeds context via `agent.inject()`.
@@ -47,12 +47,12 @@ Core dispatch and the tool body sit inside normalization boundaries, so tool, li
 
 ### Boundaries
 
-The seam package does **not** declare `hook/*` session events (the durable hook-invocation log); those belong to `dsh-hook-protocol`, because a native plugin uses typed decisions without an external hook log. The native-plugin integration test (`packages/core/agent-loop/tests/interception.spec.ts`) composes the seams through the real loop with no `hook/*` protocol. Compaction (`PreCompact`/`PostCompact`), Notification, and Codex `PermissionRequest` remain outside this decision. The [approval seam](2026-07-06-approval-seam.md) resolves `ask` decisions through `ctx.approval`; terminal monotonic stopping is expressed by tool-result data, while `agent/turn-stopping` is the last chance to steer another step.
+The Service Definition package does **not** declare `hook/*` session events (the durable hook-invocation log); those belong to `dsh-hook-protocol`, because a native plugin uses typed decisions without an external hook log. The native-plugin integration test (`packages/core/agent-loop/tests/interception.spec.ts`) composes the extension points through the real loop with no `hook/*` protocol. Compaction (`PreCompact`/`PostCompact`), Notification, and Codex `PermissionRequest` remain outside this decision. The [approval seam](2026-07-06-approval-seam.md) resolves `ask` decisions through `ctx.approval`; terminal monotonic stopping is expressed by tool-result data, while `agent/turn-stopping` is the last chance to steer another step.
 
 ## Alternatives considered
 
-- **Shipping pre-tool INPUT rewrite as part of this seam set** — deferred as the over-reach signal; the section above carries the consistency problem (audit, history, and presentation all read `tool/call.arguments` logged before execution), and [the pre-tool input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md) owns the design.
-- **Declaring the durable `hook/*` SessionEvents alongside the seams** — rejected: a native plugin uses the typed Decisions with no hook log at all (the worked example proves it), so the durable log belongs to [the hook-protocol library](2026-06-30-hook-protocol-lib.md), not the seam surface.
+- **Shipping pre-tool INPUT rewrite as part of this extension-point set** — deferred as the over-reach signal; the section above carries the consistency problem (audit, history, and presentation all read `tool/call.arguments` logged before execution), and [the pre-tool input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md) owns the design.
+- **Declaring the durable `hook/*` SessionEvents alongside the extension points** — rejected: a native plugin uses the typed Decisions with no hook log at all (the worked example proves it), so the durable log belongs to [the hook-protocol library](2026-06-30-hook-protocol-lib.md), not the extension surface.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md
similarity index 76%
rename from .agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
rename to .agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md
index 110b28d48a..262793dd7a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md
@@ -1,22 +1,22 @@
-# Agent Note: 拦截 seam——钩子编程所面对的类型化 Decision 表面
+# Agent Note: 拦截扩展点——钩子编程所面对的类型化 Decision 表面
 
 Status: implemented
 
-[English](2026-06-30-interception-seams.md) | 中文
+[English](2026-06-30-interception-extension-points.md) | 中文
 
 ## 问题
 
 harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那样在生命周期节点扩展或管控 agent（智能体）。驱动本设计的关键视角转换是：**「原生钩子」不是一个包**——原生钩子只是一个普通的 Cordis 插件，订阅规范的生命周期事件。因此真正的产品是一个*强大、类型完备的规范事件表面*；CC/Codex 桥接（`dsh-hooks-claude` / `dsh-hooks-codex` 包）只是将外部 shell 钩子协议映射到同一表面的翻译层。桥接能做的事，普通插件可以直接做——而且更强大（无序列化边界、完整 `ctx`、类型化返回值）。
 
-该表面需要为以下场景提供各自独立的约定：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
+该表面需要为以下场景提供各自独立的约定：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期扩展点。
 
 ## 决策
 
-规范表面将可变换策略、环绕调度控制与仅观测通知分离。策略 waterfall（瀑布式事件）返回小型的、seam 专属的**类型化 Decision 联合类型**；包装层返回规范化结果；通知接收不可变快照，无法影响结果。覆盖的钩子点包括 `session-start`、`prompt-submit`、`pre-tool`、`post-tool`、通过 continuation 实现的 `stop`，同时将非钩子的执行策略留作独立可组合。
+规范表面将可变换策略、环绕调度控制与仅观测通知分离。策略 waterfall（瀑布式事件）返回小型的、扩展点专属的**类型化 Decision 联合类型**；包装层返回规范化结果；通知接收不可变快照，无法影响结果。覆盖的钩子点包括 `session-start`、`prompt-submit`、`pre-tool`、`post-tool`、通过 continuation 实现的 `stop`，同时将非钩子的执行策略留作独立可组合。
 
 **Agent 事件**（`dsh-agent`）：
 - `agent/session-start({ agent, source })` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
-- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步中，`messages` 为空。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持移除状态。
+- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步会收到空批次。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持已删除。
 
 **`agent/turn-stopping`** 是自然停止边界上的一次 awaited 通知。需要再执行一步的监听器调用 `agent.steer()`，传入来源显式的 steering（中途引导）内容供模型使用；循环随后重新读取 outbox，继续执行或关闭轮次。
 
@@ -35,7 +35,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 三个承重的循环决策
 
-1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把会记录到日志中的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
+1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把带日志的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
 
 2. **工具执行后的 `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是一条独立的带来源 `user/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用／工具结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，在所有已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
 
@@ -47,13 +47,13 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 边界
 
-seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；那些属于 `dsh-hook-protocol`，因为原生插件使用类型化 decision 而无需外部钩子日志。原生插件集成测试（`packages/core/agent-loop/tests/interception.spec.ts`）通过真实循环组合这些 seam，不涉及 `hook/*` 协议。压缩（compaction）（`PreCompact`/`PostCompact`）、Notification 和 Codex `PermissionRequest` 不在本决策范围内。[审批 seam](2026-07-06-approval-seam.md) 通过 `ctx.approval` 解析 `ask` decision；终结性的单调停止由工具结果数据表达，而 `agent/turn-stopping` 是引导再执行一步的最后机会。
+Service Definition 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；那些属于 `dsh-hook-protocol`，因为原生插件使用类型化 decision 而无需外部钩子日志。原生插件集成测试（`packages/core/agent-loop/tests/interception.spec.ts`）通过真实循环组合这些扩展点，不涉及 `hook/*` 协议。压缩（compaction）（`PreCompact`/`PostCompact`）、Notification 和 Codex `PermissionRequest` 不在本决策范围内。[审批 seam](2026-07-06-approval-seam.md) 通过 `ctx.approval` 解析 `ask` decision；终结性的单调停止由工具结果数据表达，而 `agent/turn-stopping` 是引导再执行一步的最后机会。
 
 ## 曾考虑的替代方案
 
-- **将工具执行前输入重写作为本 seam 集的一部分发布**：推迟，视为越界信号；上文已阐述一致性问题（审计、历史和展示都读取执行前记录的 `tool/call.arguments`），[工具执行前输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)负责该设计。
-- **将持久的 `hook/*` SessionEvents 与 seam 一起声明**：否决。原生插件使用类型化 Decision 而完全不需要钩子日志（实际示例已证明），因此持久日志属于[钩子协议库](2026-06-30-hook-protocol-lib.md)，而非 seam 表面。
+- **将工具执行前输入重写作为本扩展点集合的一部分发布**：推迟，视为越界信号；上文已阐述一致性问题（审计、历史和展示都读取执行前记录的 `tool/call.arguments`），[工具执行前输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)负责该设计。
+- **将持久的 `hook/*` SessionEvents 与扩展点一起声明**：否决。原生插件使用类型化 Decision 而完全不需要钩子日志（实际示例已证明），因此持久日志属于[钩子协议库](2026-06-30-hook-protocol-lib.md)，而非扩展表面。
 
 ## 后果
 
-规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的约定记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP（Agent Client Protocol）桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的约定记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 52c64ec86d..5c845ed10b 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3
-2026-07-05-dynamic-workflows.zh.md: b66e767090e29f7e0cceb35b59eedb2ea60d12eb
+2026-07-05-dynamic-workflows.md: 4dc8744f7505aeb84a14dbf5ad0cc8cb5783d234
+2026-07-05-dynamic-workflows.zh.md: 5d3f5b014ff4532050bb0afd5464f7ec5e91a323
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index b0fb2349e6..4dc8744f75 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -10,7 +10,7 @@ The harness can delegate ONE task to ONE child (`dsh-tool-subagent`), but work t
 
 ## Decision
 
-A workflow capability family at `packages/workflow/` in the bash seam shape (interface / implementation / consumer), plus the structured-output foundation it needs on the subagent seam.
+A workflow capability family at `packages/workflow/` in the bash seam shape (Service Definition / Service provider / Consumer), plus the structured-output foundation it needs on the subagent seam.
 
 ### The script contract (Claude Code-compatible)
 
@@ -36,7 +36,7 @@ The engine exposes an in-process `MessageChannel` test path because main-process
 
 **Value boundary**: `materializeFromRealm` copies outbound values and rejects functions, symbols, nested `undefined`, exotic prototypes, cycles, sparse arrays, and non-finite numbers. Data-property copies make `"__proto__"` safe; getters are read normally and a throwing getter fails loudly. `args` crosses through `workerData` and is cloned again before exposure. Realm functions are invoked rather than copied, and thrown values use a total renderer so `result` cannot reject. Hook errors are host-realm `WorkflowError`s, so scripts branch on `name` or `code` rather than `instanceof Error`, as documented in the engine README. Concurrency, total-agent, item, timeout, and grace limits are validated config.
 
-### The consumer (dsh-tool-workflow)
+### The Consumer (`dsh-tool-workflow`)
 
 A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by the call's `meta.name` parameter (presentation is a pure function of args). The tool description IS the model-facing authoring spec. The usage policy ships with the tool as its own `tool:<toolName>` prompt section (explicit-ask-only guidance — tool guidance lives in tool plugins, never in the deployment persona); the harness has no ultracode-style effort gate.
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index b66e767090..5d3f5b014f 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -10,7 +10,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 ## 决策
 
-在 `packages/workflow/` 下以 bash seam 的形态（接口／实现／消费方）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
+在 `packages/workflow/` 下以 bash seam 的形态（Service Definition／Service provider／Consumer）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
 
 ### 脚本约定（兼容 Claude Code）
 
@@ -36,7 +36,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 **值边界**：`materializeFromRealm` 复制出站值，并拒绝函数、symbol、嵌套 `undefined`、异域原型、循环引用、稀疏数组和非有限数字。数据属性复制使 `"__proto__"` 安全；getter 正常读取，抛出异常的 getter 会明确报错。`args` 通过 `workerData` 传入，暴露前再次克隆。realm 函数被调用而非复制，抛出的值使用对所有输入均有定义的渲染器，因此 `result` 不会 reject。钩子错误是宿主 realm 的 `WorkflowError`，脚本应基于 `name` 或 `code` 分支而非 `instanceof Error`，如引擎 README 所述。并发、total-agent、item、超时和宽限限制均为经校验的配置。
 
-### 消费方（dsh-tool-workflow）
+### Consumer（`dsh-tool-workflow`）
 
 一个 `workflow` 工具，镜像 `dsh-tool-subagent` 的同步形态：启动、await、`try/finally` dispose、abort 桥接 `exec.signal`、非 `completed` → `isError`。渲染意图：一张以调用的 `meta.name` 参数为标题的 `generic` 卡片（展示是参数的纯函数）。工具描述即面向模型的编写规范。使用策略以工具自身的 `tool:<toolName>` 提示词段落随工具发布（显式请求才使用的引导——工具引导存在于工具插件中，从不在部署 persona 中）；harness 没有 ultracode 风格的 effort 门控。
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index 05b3a3700f..59204fcfa0 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
-2026-07-05-skill-system.zh.md: 42ae08e603411bee6212f6f321eb766c9b9d1859
+2026-07-05-skill-system.md: c4b177d84c97e5c541bffb6dfeb2135aedb8d5b8
+2026-07-05-skill-system.zh.md: d0ca688e96c10e674c9b92da8805d653ce5fd063
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index 5961c535a1..c4b177d84c 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -24,7 +24,7 @@ Each skill is either `<name>/SKILL.md` or `<name>.md` with YAML frontmatter. `na
 
 Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is loaded: project-root lookup probes `.git` with `resolve` and `stat`, root discovery uses `listDir`, and skill reads use `readText`. The Node filesystem remains a fallback for minimal contexts that mount `dsh-skill-local` without the fs seam. Missing roots, unreadable or malformed skill files, and transient provider `list()` failures degrade to warn-and-skip so one bad source does not make every agent request fail; malformed candidates still fail fast because they are provider contract violations.
 
-`dsh-tool-skill` injects one durable user-role `<system-reminder>` catalog as a sourced `user/message` at the session's first `agent/pre-step`, and only when that agent's tool view resolves this plugin's exact `skill` registration. The catalog contains sorted skill name and description only; it excludes bodies, paths, sources, providers, and routing hints. Descriptions are whitespace-normalized, XML-escaped, and capped by `catalogDescriptionMaxLength`, whose default is `500` and minimum is `3`. Full skill bodies are never included in the catalog. (The catalog originally rode the request-only [session-prefix seam](../../archived/feature/2026-07-07-session-prefix.md), archived; the [unified sourced-message decision](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) moved it into durable history.)
+`dsh-tool-skill` injects one durable user-role `<system-reminder>` catalog as a sourced `user/message` at the session's first `agent/pre-step`, and only when that agent's tool view resolves this plugin's exact `skill` registration. The catalog contains sorted skill name and description only; it excludes bodies, paths, sources, providers, and routing hints. Descriptions are whitespace-normalized, XML-escaped, and capped by `catalogDescriptionMaxLength`, whose default is `500` and minimum is `3`. Full skill bodies are never included in the catalog. (The catalog originally rode the request-only [session-prefix extension point](../../archived/feature/2026-07-07-session-prefix.md), archived; the [unified sourced-message decision](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) moved it into durable history.)
 
 The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path.
 
@@ -38,7 +38,7 @@ The data structures and catalog/tool contract are documented in [skills.md](../.
 
 **Put local filesystem scanning directly inside `ctx.skills`.** Rejected because coding agents, web agents, and future plugin ecosystems need different skill sources. A provider registry mirrors the subagent seam: the registry owns conflict resolution and consumers, while implementations own loading.
 
-**Use a system-prompt section.** Rejected because the rendered system prompt is a single string, while the catalog is a user-role `<system-reminder>` message. The [request-only session-prefix seam](../../archived/feature/2026-07-07-session-prefix.md) (archived) was the original mechanism; after the unified sourced-message decision removed that seam, the catalog became a durable sourced injection with the same message shape.
+**Use a system-prompt section.** Rejected because the rendered system prompt is a single string, while the catalog is a user-role `<system-reminder>` message. The [request-only session-prefix extension point](../../archived/feature/2026-07-07-session-prefix.md) (archived) was the original mechanism; after the unified sourced-message decision removed it, the catalog became a durable sourced injection with the same message shape.
 
 **Materialize built-in DSH authoring skills under `~/.dsh/skills/.system`.** Rejected because bundled skills do not write user home on startup, and embedded or remote providers supply configured skills.
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 42ae08e603..d0ca688e96 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -24,7 +24,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方约定。
 
-`dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
+`dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀扩展点](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
@@ -38,7 +38,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 **将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现拥有加载。
 
-**使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条 user-role `<system-reminder>` 消息。[仅请求的会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）是最初的机制；统一带来源消息的决策移除该 seam 后，目录改为具有相同消息形状的持久化带来源注入。
+**使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条 user-role `<system-reminder>` 消息。[仅请求的会话前缀扩展点](../../archived/feature/2026-07-07-session-prefix.md)（已归档）是最初的机制；统一带来源消息的决策移除该扩展点后，目录改为具有相同消息形状的持久化带来源注入。
 
 **在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不应在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index 46f1ed0675..c1ba01b255 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.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 .agents/notes/implemented/feature/2026-07-06-approval-seam.md
-2026-07-06-approval-seam.md: a286e07d51a70232f9aab0af5d8a19622cd222d4
-2026-07-06-approval-seam.zh.md: b15fcb2f6ed52ee591082770d68e265b5a703ff8
+2026-07-06-approval-seam.md: 7c830d93f19a40ab193cfebabca854882ab68d62
+2026-07-06-approval-seam.zh.md: 9dedfddadc23b0da44b28e8750508653ee20bb83
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
index a286e07d51..7c830d93f1 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
@@ -97,7 +97,7 @@ Snapshots record allowed and rejected sandbox escalation through `session/reques
 - **An inline `tools/pre-execute` permission gate in the ACP bridge** — rejected: prompting for every bridge-owned call hardwires the asking policy into the transport, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hook-produced `ask` decisions without a shared mechanism.
 - **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/interaction/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
 - **Static optional injection in `dsh-tools`** — rejected: the vendored cordis `Inject` type has no optional flag — the object form maps service names to intercept config, and a declared inject gates the fiber. `ctx.get('approval')` is the documented opportunistic-consumption pattern (the `tool-bash` owner-token lookup, the loop's persistence probe), reads presence per call, and degrades correctly across HMR without extra machinery.
-- **The capability-seam three-package split** — rejected: interface/implementation/consumer fits a seam whose implementation is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture an implementation package with nothing in it ("don't split preemptively").
+- **The capability-seam three-package split** — rejected: Service Definition / Service provider / Consumer fits a seam whose Service provider is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture a Service provider package with nothing in it ("don't split preemptively").
 - **Offering `allow_always` now** — rejected: the protocol can express it, but honoring it means designing grant storage, scope identity, and revocation (§ Deferred). Advertising an option the harness cannot honor manufactures doomed grants.
 
 ## Consequences
@@ -134,6 +134,6 @@ In-repo precedents this design copies or contrasts with:
 
 - The `fs/write-intent` gate (`packages/fs/fs/`) — the documented single-occupancy decision-slot waterfall semantics (first answer wins, delegate via `next()`) the answerer contract reuses.
 - `hook/invoked`/`hook/result` — the log-only audit-pair precedent `approval/asked`/`approval/decided` follows; [the hook-bridges Agent Note](2026-06-30-hook-bridges.md) ships `permissionDecision: ask`, the first producer.
-- [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` `allow`/`deny`/`ask` vocabulary whose `ask` this seam services.
+- [The interception extension-points Agent Note](2026-06-30-interception-extension-points.md) — the `tools/pre-execute` `allow`/`deny`/`ask` vocabulary whose `ask` this seam services.
 - [The automation-only ACP Agent Note](../simplification/2026-07-23-acp-automation-only-protocol.md) — the exact-agent ownership check against the session map that the answerer routes through; [the multi-session Agent Note](2026-06-14-acp-multi-session.md) — the per-session permission-ownership blocker this implements.
 - The opportunistic `ctx.get()` consumption pattern (`tool-bash`'s owner-token lookup, the loop's persistence probe) — how `dsh-tools` consumes the seam without gating its fiber on it.
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
index b15fcb2f6e..9dedfddadc 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -97,7 +97,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 - **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
 - **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的约定在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
 - **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
-- **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
+- **能力 seam 的三包拆分**：否决。Service Definition/Service provider/Consumer 适合 Service provider 可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的 Service provider 包（「不要预防性拆分」）。
 - **现在就提供 `allow_always`**：否决。协议能表达它，但兑现它意味着设计授权存储、作用域标识和撤销（§ 延后）。展示 harness 无法兑现的选项只会制造注定失败的授权。
 
 ## 后果
@@ -134,6 +134,6 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者约定复用了它。
 - `hook/invoked`/`hook/result`——仅日志审计对先例，`approval/asked`/`approval/decided` 沿用了它；[钩子桥 Agent Note](2026-06-30-hook-bridges.md) 交付了 `permissionDecision: ask`，即第一个生产者。
-- [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
+- [拦截扩展点 Agent Note](2026-06-30-interception-extension-points.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
 - [仅面向自动化的 ACP Agent Note](../simplification/2026-07-23-acp-automation-only-protocol.md)——应答者路由时对会话映射执行的精确 agent 归属检查；[多会话 Agent Note](2026-06-14-acp-multi-session.md)——本设计实现的每会话权限归属阻塞项。
 - 机会性 `ctx.get()` 消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测）——`dsh-tools` 消费该 seam 而不阻塞其 fiber 的方式。
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
index 3ede7af472..786f76c858 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.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 .agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
-2026-07-06-explicit-tool-order.md: bd6d0a04aa470ca33e618957ae1f08c1ef15fcfe
-2026-07-06-explicit-tool-order.zh.md: 69365151f2c20cfa782ecc5560a6c600c8dec6a2
+2026-07-06-explicit-tool-order.md: 7a4553b50da409b531a9fe14fcfbb201a5165fc4
+2026-07-06-explicit-tool-order.zh.md: a78a38a6ada3ed0a2f3a756830747916446e188c
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
index bd6d0a04aa..7a4553b50d 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
@@ -39,7 +39,7 @@ Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it:
 ## Consequences
 
 - Every registry-built assembly starts with a deterministic tool order on every host; absent an expert listener that deliberately changes it, every `request/header` event and model request inherits that order. The CI-vs-local registration-order flip is structurally gone, and the default is lexicographic.
-- The initial `PromptAssembly.tools` is canonical, so waterfall listeners start from the model-facing order; provider registration order is observable nowhere before that cooperative seam.
+- The initial `PromptAssembly.tools` is canonical, so waterfall listeners start from the model-facing order; provider registration order is observable nowhere before that cooperative extension point.
 - The snapshot suite's single pinned request-header fixture (`text-turn`) carries the new canonical tool order; every other ACP snapshot keeps the header bulk scrubbed as `{{system}}`/`{{tools}}`, per the pinned-header design.
 - A pure tool reordering between steps is logged like any other header change: a full `request/header` snapshot with reason `'change'`. Stable canonical order prevents registration timing from creating such changes in the ordinary path.
 - The `toolOrder` key rides the app → `agent-core` → `SystemPrompt` forwarding chain, so deployments set it next to `persona` in the app config; `dsh-llm` and the agent loop are untouched.
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
index 69365151f2..a78a38a6ad 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
@@ -39,7 +39,7 @@ Status: implemented
 ## 后果
 
 - 每个由注册表构建的组装在任何宿主上都以确定性工具顺序开始；在没有专家监听器刻意改变的情况下，每个 `request/header` 事件和模型请求都继承该顺序。CI 与本地之间的注册顺序翻转从结构上被消除，默认为字典序。
-- 初始 `PromptAssembly.tools` 是权威的，因此 waterfall 监听器从模型侧顺序开始；提供方注册顺序在该协作 seam 之前无处可观测。
+- 初始 `PromptAssembly.tools` 是权威的，因此 waterfall 监听器从模型侧顺序开始；提供方注册顺序在该协作扩展点之前无处可观测。
 - 快照套件中唯一锁定请求头的 fixture（`text-turn`）携带新的权威工具顺序；按照锁定请求头的设计，其他 ACP 快照仍将大段 header 替换为 `{{system}}`/`{{tools}}`。
 - 步骤之间的纯工具重排与其他 header 变更一样记录：一份原因是 `'change'` 的完整 `request/header` 快照。稳定的权威顺序会防止注册时序在普通路径上制造这类变化。
 - `toolOrder` 键沿 app → `agent-core` → `SystemPrompt` 的转发链传递，因此部署时将其放在 app 配置中 `persona` 旁边即可；`dsh-llm` 和 agent loop 无需改动。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index fdb075d228..289e9a582a 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 943b1e27ff2d61a56e5532a20b9983d181c15e29
-2026-07-06-sandbox.zh.md: 89a73afb6154363b9d3e7c1afedbda386994325a
+2026-07-06-sandbox.md: 0214a202a41983c76fa25e3a82e1cfaec70a0d55
+2026-07-06-sandbox.zh.md: bd8dcdb74f723a955ea2a1cc5b224ef2ded4a8d5
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 943b1e27ff..0214a202a4 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -38,7 +38,7 @@ Four `cordis.yml` entries turn an unconfined coding agent into the sandboxed pro
 
 The swap is invisible to every consumer of `ctx.bash`: the bash tools, hook commands, and background tasks run exactly as before by directly spawning the wrapped argv the provider returns. Deleting the `sandbox` and `permission` entries and replacing `bash` with `@deepseek-ai/dsh-bash-local` is the opt-out — execution is unconfined again and the escalation fields vanish from the tool schema, because they are capability-gated on the mounted executor, not on configuration. Omitting only `approval` keeps confinement but fails every escalation closed with its own error text; `permission` also requires the approval seam and a confining executor, so a partially composed preset layer fails loud at load.
 
-Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` at `confine()` rather than degrading to unconfined execution. If the selected runner rejects with attributable `ENOENT` or `EACCES`, the consumer reports the same infrastructure error from the spawn channel before any command starts; other spawn errors retain local command-start semantics while still running nothing. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner seam for keyless tests.
+Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` at `confine()` rather than degrading to unconfined execution. If the selected runner rejects with attributable `ENOENT` or `EACCES`, the consumer reports the same infrastructure error from the spawn channel before any command starts; other spawn errors retain local command-start semantics while still running nothing. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner hook for keyless tests.
 
 Denied file effects return a `[sandbox: file access denied under <mode> mode]` marker and instructions not to work around the denial. A confining executor adds paired `sandbox_permissions` and `justification` fields for one approved retry that must be strictly wider than the session's effective mode. A grant widens only that retry; rejection executes nothing, returns `the user rejected escalating this command to "<mode>"`, and permits no re-ask. The owner-derived pending policy context states the current file policy without replacing those enforcement boundaries. When `dsh-permission` is composed with a UI adapter, one preset selects both knob values; unmatched values fold to `custom`. The [ACP automation composition](../../../../examples/acp-agent/README.md) does not mount that UI service and selects its deployment mode explicitly.
 
@@ -54,7 +54,7 @@ OS subprocess confinement applies to the bash executor, including hook commands,
 
 Policy rides each CALL, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is a new call with a wider policy — inexpressible under a config-fixed provider mode.
 
-The seam confines SAME-WORLD subprocesses only: a backend shares the host's filesystem and kernel. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups, because an agent whose bash runs in a container while its fs tools write the host lives in two split worlds.
+The seam confines SAME-WORLD subprocesses only: a backend shares the host's filesystem and kernel. Containers, microVMs, and remote executors are NOT backends of this seam — they replace the Service providers for whole capability seams (`ctx.bash`, `ctx.fs`) as environment-coherent groups, because an agent whose bash runs in a container while its fs tools write the host lives in two split worlds.
 
 Left open, for the phase that needs them: whether network restriction arrives as a separate `network_mode` or merges into `sandbox_mode` once a runner enforces both, and whether `SandboxPolicy` grows extra writable-root grants now (the launcher already speaks `--rw <path>`) or only when escalation needs them.
 
@@ -82,7 +82,7 @@ The model sees the current effective file policy in the owner-derived `sandbox:p
 
 When a confining executor is mounted, `bash` advertises paired `sandbox_permissions` and `justification` fields. The schema exposes the full closed escalation vocabulary because effective mode is per-session; execution rejects any target that is not strictly wider than that call's effective mode. Approval resolves before execution. `allowed-once` stamps the granted mode onto only that request, while `rejected`, `cancelled`, `unavailable`, a missing approval service, or a missing agent all fail closed with distinct results. No grant is persisted.
 
-Escalation is a same-turn retry of the denied command with the narrowest sufficient `sandbox_permissions` and a `justification`; the approval prompt is the consent step. It must be grounded in an actual denial, except when the session already observed the same denied access, and a disabled or rejected approval ends that command. The retry, approval decision, and result use existing tool and approval events. `dsh-tool-bash` owns the ask because the executor seam has neither the agent nor call id required for user interaction.
+Escalation is a same-turn retry of the denied command with the narrowest sufficient `sandbox_permissions` and a `justification`; the approval prompt is the consent step. It must be grounded in an actual denial, except when the session already observed the same denied access, and a disabled or rejected approval ends that command. The retry, approval decision, and result use existing tool and approval events. `dsh-tool-bash` owns the ask because the executor Service Definition has neither the agent nor call id required for user interaction.
 
 Left open: what a durable grant's scope identity is beyond the sandbox mode — exact call, path, command prefix, session, or time window — before an `allow_always` option can be advertised.
 
@@ -113,7 +113,7 @@ Before each proposed step, sandbox and approval policy are rendered as ordered c
 
 #### In-process tools
 
-fs/web/todo execute in-process, so their sandbox semantics are policy at their seams. The fs seam now enforces the shared mode vocabulary through a sandboxed provider (`dsh-fs-sandbox` fences write/edit by mode; see [the cross-family fs sandbox RFC](2026-07-14-cross-family-fs-sandbox.md)), so `read-only`/`workspace-write` are real boundaries for the filesystem tools, not a bash-only approximation. web/todo remain unfenced (web's only effect is network, outside the file-effect mode vocabulary). No generic per-tool sandbox runtime: a host-mediated tool leaves the process only by returning declarative effects the host validates, which is a rewrite, not a wrapper — the follow-up settled on one shared policy home (`ctx.sandboxPolicy`) with per-seam enforcement, not a uniform wrapper.
+fs/web/todo execute in-process, so their sandbox semantics are policy at their capability boundaries. The fs seam now enforces the shared mode vocabulary through a sandboxed provider (`dsh-fs-sandbox` fences write/edit by mode; see [the cross-family fs sandbox RFC](2026-07-14-cross-family-fs-sandbox.md)), so `read-only`/`workspace-write` are real boundaries for the filesystem tools, not a bash-only approximation. web/todo remain unfenced (web's only effect is network, outside the file-effect mode vocabulary). No generic per-tool sandbox runtime: a host-mediated tool leaves the process only by returning declarative effects the host validates, which is a rewrite, not a wrapper — the follow-up settled on one shared policy home (`ctx.sandboxPolicy`) with per-capability enforcement, not a uniform wrapper.
 
 ### Testing
 
@@ -142,7 +142,7 @@ Each phase gets its full design when picked up, validated against the code at th
 - **Config-fixed mode on the provider** — rejected: one mode per process; cannot serve concurrent consumers with different policies nor the one-shot widened retry.
 - **One interface spanning containers/VMs too** — rejected: `confine(argv)` presupposes a shared filesystem; environment isolation is capability-sibling backends deployed as coherent groups.
 - **Generic ToolRuntime wrapping any tool** — rejected: mechanically false for in-process tools (closures over `ctx`); the declarative-effects rewrite is unjustified for fs/web/todo.
-- **Ask inside the executor (`dsh-bash-sandbox`)** — rejected: no `agent` to route through, no `callId` to attach the prompt to; adding them teaches a transport seam about sessions and UIs — the tool layer holds both and owns the model-facing vocabulary.
+- **Ask inside the executor (`dsh-bash-sandbox`)** — rejected: no `agent` to route through, no `callId` to attach the prompt to; adding them teaches a transport boundary about sessions and UIs — the tool layer holds both and owns the model-facing vocabulary.
 - **Auto-retry inside the same tool call** — rejected: a hidden re-entry the log cannot reconstruct: one `tool/call` would have produced two executions with different policies — the retry is a NEW logged call with its own arguments and result facts.
 - **Advertise the escalation fields unconditionally** — rejected: under `dsh-bash-local` they are a dead lever — advertising an option the harness cannot honor manufactures doomed grants; capability-gating costs one registration-time read.
 - **A default-relative escalation ladder (advertise only the modes wider than the executor's registration-time default)** — rejected: per-session overrides make the default the wrong baseline — a session switched narrower than the default loses exactly the lever it needs, and under a `danger-full-access` default the fields vanish entirely while a `read-only`-overridden session stays confined with no escalation path. The enum pins the closed target vocabulary; strict widening is a per-call execution check against the session's effective mode.
@@ -199,8 +199,8 @@ Costs and accepted limits:
 
 In-repo precedents this design copies or contrasts with:
 
-- [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
+- [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the Service Definition / Service provider / Consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
 - The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/subsystems/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention.
 - [The approval seam Agent Note](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there.
 - [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [standalone log-only events](../simplification/2026-07-28-remove-synthetic-log-only-turns.md) — the log-as-store foundation the per-session modes fold over, and the explicit durability boundary the anchoring design obeys.
-- [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
+- [The interception extension-points Agent Note](2026-06-30-interception-extension-points.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 89a73afb61..bd8dcdb74f 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -38,7 +38,7 @@ harness 是一个 SDK，因此约束必须是开发者可组合的能力：是
 
 这一替换对 `ctx.bash` 的所有消费方透明：bash 工具、钩子命令和后台任务照常运行，直接使用提供方返回的已包装 argv 启动。删除 `sandbox` 和 `permission` 条目、将 `bash` 替换为 `@deepseek-ai/dsh-bash-local` 即为退出——执行恢复为无约束，升级字段从工具 schema 中消失，因为它们是基于已挂载执行器的能力门控，而非基于配置。仅省略 `approval` 则保留约束但以自身错误文本关闭每次升级；`permission` 还要求 approval seam 和约束执行器同时存在，因此部分组合的 preset 层在加载时即大声失败。
 
-配置错误会显式导致失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。如果所选 runner 以可归因的 `ENOENT` 或 `EACCES` 拒绝，消费方会在任何命令开始前通过 spawn 通道报告同一基础设施错误；其他 spawn 错误仍保留本地命令启动语义，同时也不会运行任何内容。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner seam。
+配置错误会显式导致失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。如果所选 runner 以可归因的 `ENOENT` 或 `EACCES` 拒绝，消费方会在任何命令开始前通过 spawn 通道报告同一基础设施错误；其他 spawn 错误仍保留本地命令启动语义，同时也不会运行任何内容。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner 钩子。
 
 被拒绝的文件操作返回 `[sandbox: file access denied under <mode> mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to "<mode>"`，且不允许再次请求。由归属方派生的待处理策略上下文会说明当前文件策略，但不会取代这些强制执行边界。当 `dsh-permission` 与某个 UI 适配器一起组合时，一个 preset 同时选定两个旋钮值；不匹配的组合折叠为 `custom`。[ACP 自动化组合](../../../../examples/acp-agent/README.md)不挂载该 UI 服务，而是显式选定其部署模式。
 
@@ -54,7 +54,7 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 策略随每次调用而非提供方携带：两个消费方可以在同一时刻以不同策略约束（bash 在 `read-only` 下运行，而一个受约束的子 agent 保持其状态目录可写），且经批准的升级重试是一次带有更宽策略的新调用——在配置固定的提供方模式下无法表达。
 
-该 seam 仅约束与宿主机共享文件系统和内核的子进程。容器、microVM 和远程执行器不是此 seam 的后端——它们以环境一致的组替换整个能力实现（`ctx.bash`、`ctx.fs`），因为一个 bash 在容器中运行而 fs 工具写主机的 agent 生活在两个割裂的世界中。
+该 seam 仅约束与宿主机共享文件系统和内核的子进程。容器、microVM 和远程执行器不是此 seam 的后端——它们以环境一致的组替换整个能力 seam（`ctx.bash`、`ctx.fs`）的 Service provider，因为一个 bash 在容器中运行而 fs 工具写主机的 agent 生活在两个割裂的世界中。
 
 留待需要时再决定：网络限制是作为独立的 `network_mode` 到来，还是在某个 runner 同时强制两者后合并进 `sandbox_mode`；以及 `SandboxPolicy` 是现在就增加额外的可写根授权（launcher 已支持 `--rw <path>`），还是等到升级机制需要时再加。
 
@@ -82,7 +82,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 
 
 当约束执行器被挂载时，`bash` 公布配对的 `sandbox_permissions` 和 `justification` 字段。schema 暴露完整的封闭升级词汇，因为有效模式是按会话的；执行拒绝任何不严格宽于该调用有效模式的目标。批准在执行之前解析。`allowed-once` 仅将授权模式盖章到该请求上，而 `rejected`、`cancelled`、`unavailable`、缺失的 approval 服务或缺失的 agent 都以各自不同的结果文本失败关闭。授权不持久化。
 
-升级是对被拒绝命令的同轮次重试，使用最窄的足够 `sandbox_permissions` 和一个 `justification`；批准提示是同意步骤。它必须基于实际的拒绝，除非会话已观察到相同的被拒绝访问；禁用或被拒绝的批准终结该命令。重试、批准决策和结果使用既有的工具和批准事件。`dsh-tool-bash` 拥有请求动作，因为执行器 seam 既没有 agent 也没有用户交互所需的 call id。
+升级是对被拒绝命令的同轮次重试，使用最窄的足够 `sandbox_permissions` 和一个 `justification`；批准提示是同意步骤。它必须基于实际的拒绝，除非会话已观察到相同的被拒绝访问；禁用或被拒绝的批准终结该命令。重试、批准决策和结果使用既有的工具和批准事件。`dsh-tool-bash` 拥有请求动作，因为执行器 Service Definition 既没有 agent 也没有用户交互所需的 call id。
 
 仍未决定：持久授权超出沙箱模式之外的作用域标识是什么——确切调用、路径、命令前缀、会话或时间窗口——这是公布 `allow_always` 选项之前必须回答的问题。
 
@@ -113,7 +113,7 @@ interface SessionEventMap {
 
 #### 进程内工具
 
-fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层面的策略。fs seam 现在通过沙箱提供方强制共享模式词汇（`dsh-fs-sandbox` 按模式限制 write/edit；见[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md)），因此 `read-only`/`workspace-write` 对文件系统工具也是真实边界，而非仅限 bash 的近似。web/todo 仍不受限制（web 的唯一效果是网络，不在文件效果模式词汇内）。没有通用的按工具沙箱运行时：主机中介的工具仅通过返回主机验证的声明式效果来离开进程，那是一次重写而非包装——后续设计选择了一个共享策略归属 `ctx.sandboxPolicy`，由各 seam 强制，而不是统一包装器。
+fs/web/todo 在进程内执行，因此它们的沙箱语义是各自能力边界层面的策略。fs seam 现在通过沙箱提供方强制共享模式词汇（`dsh-fs-sandbox` 按模式限制 write/edit；见[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md)），因此 `read-only`/`workspace-write` 对文件系统工具也是真实边界，而非仅限 bash 的近似。web/todo 仍不受限制（web 的唯一效果是网络，不在文件效果模式词汇内）。没有通用的按工具沙箱运行时：主机中介的工具仅通过返回主机验证的声明式效果来离开进程，那是一次重写而非包装——后续设计选择了一个共享策略归属 `ctx.sandboxPolicy`，由各能力强制，而不是统一包装器。
 
 ### 测试
 
@@ -142,7 +142,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 - **提供方上的配置固定模式**：否决。每进程一个模式；无法服务具有不同策略的并发消费方，也无法表达一次性放宽重试。
 - **一个接口同时覆盖容器/VM**：否决。`confine(argv)` 预设共享文件系统；环境隔离是作为一致组部署的能力兄弟后端。
 - **通用 ToolRuntime 包装任何工具**：否决。对进程内工具（闭包了 `ctx`）机械上不成立；声明式效果重写对 fs/web/todo 而言不合理。
-- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加提示词的 `callId`；添加它们会让传输 seam 了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
+- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加提示词的 `callId`；添加它们会让传输边界了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
 - **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次新的带有自身参数和结果事实的已记录调用。
 - **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
 - **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
@@ -199,8 +199,8 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 
 本设计复制或对比的仓库内先例：
 
-- [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
+- [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——Service Definition/Service provider/Consumer 拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
 - `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/subsystems/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
 - [批准 seam Agent Note](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。
 - [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[独立纯日志事件](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)——按会话模式 fold 所依赖的日志即存储基础，以及锚定设计遵守的显式持久性边界。
-- [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
+- [拦截扩展点 Agent Note](2026-06-30-interception-extension-points.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 9566e667f2..527dd9bead 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.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 .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
-2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45
-2026-07-10-parallel-tool-call-execution.zh.md: 278996fedb8c9dcc86916a1544535b1444b6e9f5
+2026-07-10-parallel-tool-call-execution.md: 830691b7596accd1c5746fc51e38a9022f09e501
+2026-07-10-parallel-tool-call-execution.zh.md: bd336919adbf9b96f64477c1e24964172cde6d92
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
index 7fd540539f..830691b759 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
@@ -82,7 +82,7 @@ Snapshot coverage pins the visible multi-call transcript: pending calls may over
 
 **Parallelize the complete tool pipeline.** This keeps the loop on the public one-call API but runs pre- and post-execute middleware concurrently. Existing guards and hook bridges may carry ordered state, so only dispatch overlaps.
 
-**Expose staged methods or a scheduling waterfall.** Public `prepare` / `dispatch` / `finalize` methods or a `tools/execution-mode` event add extension surface before another consumer needs it. The loop uses an internal scheduler view, while `executionMode(exec)` leaves an insertion point for a policy seam.
+**Expose staged methods or a scheduling waterfall.** Public `prepare` / `dispatch` / `finalize` methods or a `tools/execution-mode` event add extension surface before another consumer needs it. The loop uses an internal scheduler view, while `executionMode(exec)` leaves an insertion point for a policy hook.
 
 **Convert scheduler failures into tool results.** AgentLoop cannot determine whether a rejected dispatch invoked the tool body; ToolRegistry owns body-invocation state and typed tool outcomes. Internal scheduler failures therefore remain terminal instead of being reclassified as `ABORTED` results.
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 278996fedb..bd336919ad 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -82,7 +82,7 @@ Code Mode 仍不使用此调度器，因为模型只会发出一个原生 `run_c
 
 **并行执行完整的工具流水线。** 这样可以让循环继续使用公开的单调用 API，但会并发运行 pre-execute 和 post-execute 中间件。现有防护和钩子桥可能承载有序状态，因此只允许派发重叠。
 
-**公开分阶段方法或调度 waterfall。** 公开的 `prepare` / `dispatch` / `finalize` 方法或 `tools/execution-mode` 事件，会在出现另一个消费方之前扩大扩展接口。循环使用内部调度器视图，而 `executionMode(exec)` 为策略 seam 保留了插入点。
+**公开分阶段方法或调度 waterfall。** 公开的 `prepare` / `dispatch` / `finalize` 方法或 `tools/execution-mode` 事件，会在出现另一个消费方之前扩大扩展接口。循环使用内部调度器视图，而 `executionMode(exec)` 为策略钩子保留了插入点。
 
 **将调度器故障转换为工具结果。** AgentLoop 无法判断被拒绝的派发是否已调用工具主体；ToolRegistry 负责工具主体调用状态和类型化工具结果。因此，内部调度器故障保持为终态，而不会被重新分类为 `ABORTED` 结果。
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
index 55a4439855..3d36c07567 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.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 .agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
-2026-07-10-sqlite-session-query-provider.md: 372c21241f9ae5d7300165f016db9b36e6b52855
-2026-07-10-sqlite-session-query-provider.zh.md: f5f2d22a209350975a4ccff9a538a55dfc8ff71e
+2026-07-10-sqlite-session-query-provider.md: 0e15ea15f516091825276c4a9bcde2184c653123
+2026-07-10-sqlite-session-query-provider.zh.md: caf700fd5979ff64c1445caba7fd44ffc28cb925
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
index 372c21241f..0e15ea15f5 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
@@ -16,7 +16,7 @@ Splitting those concerns across a provider coordinator and a database implementa
 
 `@deepseek-ai/dsh-session-query-sqlite` extends the interface service and is the sole concrete owner of `ctx.sessionQuery`. It depends on live `ctx.sessions`, observes optional `ctx.sessionPersistence` dynamically, and owns a dedicated derived SQLite database. There is no search-provider registry, coordinator, persistence event, or agent-loop integration.
 
-The interface package also owns shared first-party semantic extraction and provider-independent filtering. `SessionResultFilter` covers id, nullable cwd, created-at range, nullable parent, and availability; `ctx.sessionQuery.filterSessions()` applies it without an FTS provider. `SessionEventResultFilter` covers seq/time ranges, event type, surface, and literal semantic text. Arrays are ANDed and list values are ORed. The text clause escapes caller input into a Unicode case-insensitive regular expression whose whitespace runs match one or more whitespace characters; it is available through `ctx.sessionQuery.filterEvents()` and is not delegated to an FTS provider.
+The Service Definition package also owns shared first-party semantic extraction and provider-independent filtering. `SessionResultFilter` covers id, nullable cwd, created-at range, nullable parent, and availability; `ctx.sessionQuery.filterSessions()` applies it without an FTS provider. `SessionEventResultFilter` covers seq/time ranges, event type, surface, and literal semantic text. Arrays are ANDed and list values are ORed. The text clause escapes caller input into a Unicode case-insensitive regular expression whose whitespace runs match one or more whitespace characters; it is available through `ctx.sessionQuery.filterEvents()` and is not delegated to an FTS provider.
 
 ## Search semantics
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
index f5f2d22a20..caf700fd59 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 `@deepseek-ai/dsh-session-query-sqlite` 扩展接口服务，并且是 `ctx.sessionQuery` 唯一的具体所有者。它依赖实时的 `ctx.sessions`，动态观察可选的 `ctx.sessionPersistence`，并拥有一个专用的派生 SQLite 数据库。系统没有搜索提供方注册表、协调器、持久化事件或 agent loop（智能体循环）集成。
 
-接口包还拥有共享的第一方语义提取与提供方无关的过滤。`SessionResultFilter` 涵盖 id、可空的 cwd、创建时间范围、可空的父会话与可用性；`ctx.sessionQuery.filterSessions()` 无需 FTS 提供方即可应用这些过滤器。`SessionEventResultFilter` 涵盖 seq/时间范围、事件类型、surface 与字面语义文本。过滤器数组内各项按逻辑与（AND）组合，列表值按逻辑或（OR）组合。文本子句会将调用方输入转义为不区分大小写的 Unicode 正则表达式，其中每段连续空白都匹配一个或多个空白字符；该子句通过 `ctx.sessionQuery.filterEvents()` 提供，不会委托给 FTS 提供方。
+Service Definition 包还拥有共享的第一方语义提取与提供方无关的过滤。`SessionResultFilter` 涵盖 id、可空的 cwd、创建时间范围、可空的父会话与可用性；`ctx.sessionQuery.filterSessions()` 无需 FTS 提供方即可应用这些过滤器。`SessionEventResultFilter` 涵盖 seq/时间范围、事件类型、surface 与字面语义文本。过滤器数组内各项按逻辑与（AND）组合，列表值按逻辑或（OR）组合。文本子句会将调用方输入转义为不区分大小写的 Unicode 正则表达式，其中每段连续空白都匹配一个或多个空白字符；该子句通过 `ctx.sessionQuery.filterEvents()` 提供，不会委托给 FTS 提供方。
 
 ## 搜索语义
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 7952219be6..d7d288e9f9 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: bc375621c5bf71ae6e3fbcd754d3b62e43353ae9
-2026-07-16-harness-level-loop.zh.md: fd74fbf85a63cb2f35fbcf7f694f738a07fe0cee
+2026-07-16-harness-level-loop.md: 2efcf64adf07152b544c82f5bbf3bd8e415cd64d
+2026-07-16-harness-level-loop.zh.md: 8b83ca4a7f957f304c093e4b3f4c462c6301d6bc
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index bc375621c5..2efcf64adf 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -19,7 +19,7 @@ This proposal is implemented in amended form as two explicit plugin policies ove
 1. **Same-session goals** retain one durable objective in the current session and admit goal-attributed continuation turns only while live activation is armed.
 2. **Fresh-agent Ralph runs** execute a fixed foreground workflow whose rounds each spawn a new structured child with no conversation seed.
 
-There is no `packages/loop/` family, `LoopDriver`, `LoopId`, universal `StopCondition`, or model-facing generic `loop` tool. The two policies share the repository's ordinary agent, session, tools, workflow, subagent, and UI extension seams, but they do not pretend that one lifecycle fits both.
+There is no `packages/loop/` family, `LoopDriver`, `LoopId`, universal `StopCondition`, or model-facing generic `loop` tool. The two policies share the repository's ordinary agent, session, tools, workflow, subagent, and UI extension points, but they do not pretend that one lifecycle fits both.
 
 ### Vocabulary and policy boundary
 
@@ -98,11 +98,11 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 
 ## Alternatives considered
 
-- **Implement the original universal loop capability seam** — rejected because `Evaluator`, `BudgetPolicy`, `RoundHandoff`, `GoalReflector`, background task ownership, persistence, and scheduling do not form one coherent mandatory abstraction. Building all of them before their first concrete consumers would create broad speculative surface and duplicate existing session, workflow, subagent, and task machinery.
+- **Implement the original universal loop capability** — rejected because `Evaluator`, `BudgetPolicy`, `RoundHandoff`, `GoalReflector`, background task ownership, persistence, and scheduling do not form one coherent mandatory abstraction. Building all of them before their first concrete consumers would create broad speculative surface and duplicate existing session, workflow, subagent, and task machinery.
 - **Implement only same-session goals** — rejected because fresh-context iteration is materially different and is a valuable demonstration of the plugin architecture. Ralph belongs as a fixed workflow consumer with explicit context reset.
 - **Put Ralph inside the goal-round driver** — rejected because same-session goals deliberately preserve one conversation while Ralph deliberately removes it. Combining them would make activation, replay, handoff, and UI state ambiguous.
 - **Treat a fork as a fresh Ralph child** — rejected because a fork carries a conversation prefix. Fresh children plus workspace state and one explicit report are easier to bound and replay without a synthetic cancel record.
-- **Copy Claude Code's evaluator into the first goal implementation** — rejected because a transcript-only model evaluator is one useful policy, not a generally trustworthy completion certificate. Deterministic evaluation and isolation must remain possible, so the evaluator is deferred until its authority and provider seam are designed.
+- **Copy Claude Code's evaluator into the first goal implementation** — rejected because a transcript-only model evaluator is one useful policy, not a generally trustworthy completion certificate. Deterministic evaluation and isolation must remain possible, so the evaluator is deferred until its authority and provider contract are designed.
 - **Automatically continue after session restore** — rejected because opening a session is observation, not authority to spend resources. Durable state is restored while activation waits for a new human prompt.
 - **Route `/goal` through the model** — rejected because status and explicit lifecycle controls should be deterministic, token-free UI actions; ordinary natural-language prompts remain the semantic model path.
 - **Modify the concrete agent loop with goal or Ralph modes** — rejected because public queue, prompt, session, cancellation, workflow, and subagent seams already support both policies. The generic cancel-requested observation is the only core coordination addition.
@@ -125,5 +125,5 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 - **No generic loop journal or execution-world rewind** — session replay reconstructs goal history, not prior files, processes, environment, credentials, or external side effects. Ralph treats the current workspace as authority and carries no cross-run journal.
 - **No goal reflector** — concern events, automatic no-progress heuristics, goal revision by an independent reflector, stuck-pattern detection, and `loop_split` are not implemented. Humans can edit, pause, clear, or resume the goal directly.
 - **Ralph policy remains narrow** — one round creates one fresh child; within-round fan-out, evaluator/worker role separation, dynamic provider/model selection, and structural recursive-Ralph tool denial need separate policy surfaces. Prompt guidance is not enforcement.
-- **Ralph does not retry a failed child** — an ordinary failure preserves the failed round and last good handoff, while fatal workflow infrastructure failures can end before that state is available. Retry count, backoff, and richer failure transport need separate policy and seam design.
+- **Ralph does not retry a failed child** — an ordinary failure preserves the failed round and last good handoff, while fatal workflow infrastructure failures can end before that state is available. Retry count, backoff, and richer failure transport need separate policy and boundary design.
 - **Portable UI remains modest** — TUI renders plain-text goal status and generic Ralph cards. ACP carries only committed assistant text; there is no continuous status widget, reconnectable command output, modal goal editor, or command plane in ACP, the headless CLI, or JSON-RPC.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index fd74fbf85a..8b83ca4a7f 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 1. **同会话目标**在当前会话中保留一个持久目标，并且只在实时激活态已激活时接纳带目标归属的续行轮次。
 2. **全新 agent Ralph 运行**执行一个固定前台工作流，其中每个 Round 都生成一个不带对话种子的全新结构化子 agent。
 
-系统中没有 `packages/loop/` 包族、`LoopDriver`、`LoopId`、通用 `StopCondition` 或面向模型的通用 `loop` 工具。两项策略共享本仓库普通的 agent、会话、工具、工作流、subagent 与 UI 扩展 seam，但不会假装一种生命周期可以同时适配两者。
+系统中没有 `packages/loop/` 包族、`LoopDriver`、`LoopId`、通用 `StopCondition` 或面向模型的通用 `loop` 工具。两项策略共享本仓库普通的 agent、会话、工具、工作流、subagent 与 UI 扩展点，但不会假装一种生命周期可以同时适配两者。
 
 ### 词汇与策略边界
 
@@ -98,11 +98,11 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 ## 考虑过的替代方案
 
-- **实现原始通用 loop 能力 seam**——不予采纳，因为 `Evaluator`、`BudgetPolicy`、`RoundHandoff`、`GoalReflector`、后台任务所有权、持久化与调度并不构成一项一致的必选抽象。在出现首个具体消费者前全部构建，会产生宽泛推测性表面，并重复现有 session、workflow、subagent 与 task 机制。
+- **实现原始通用 loop 能力**——不予采纳，因为 `Evaluator`、`BudgetPolicy`、`RoundHandoff`、`GoalReflector`、后台任务所有权、持久化与调度并不构成一项一致的必选抽象。在出现首个具体消费者前全部构建，会产生宽泛推测性表面，并重复现有 session、workflow、subagent 与 task 机制。
 - **只实现同会话目标**——不予采纳，因为全新上下文迭代在实质上不同，也是插件架构的重要示范。Ralph 应作为带显式上下文重置的固定工作流消费者。
 - **把 Ralph 放进目标回合驱动器**——不予采纳，因为同会话目标有意保留一段对话，而 Ralph 有意移除对话。合并两者会让激活、重放、交接与 UI 状态含糊不清。
 - **把 fork 当成全新 Ralph 子 agent**——不予采纳，因为 fork 会携带对话前缀。全新子 agent 加工作区状态与一份显式报告更容易限制和重放，并且无需合成取消记录。
-- **把 Claude Code 评估器复制进首个目标实现**——不予采纳，因为只读取转录的模型评估器是一项有用策略，但不是普遍可信的完成证书。系统必须仍能支持确定性评估与隔离，因此评估器延期到其权限与 provider seam 完成设计之后。
+- **把 Claude Code 评估器复制进首个目标实现**——不予采纳，因为只读取转录的模型评估器是一项有用策略，但不是普遍可信的完成证书。系统必须仍能支持确定性评估与隔离，因此评估器延期到其权限与提供方约定完成设计之后。
 - **会话恢复后自动续行**——不予采纳，因为打开会话是观察行为，不是花费资源的权限。系统恢复持久状态，而激活态等待新的人类提示词。
 - **通过模型路由 `/goal`**——不予采纳，因为状态与显式生命周期控制应是确定性且零 token 的 UI 操作；普通自然语言提示词仍是语义模型路径。
 - **为具体 agent loop 增加目标或 Ralph 模式**——不予采纳，因为公开队列、提示词、会话、取消、工作流与 subagent seam 已经支持两项策略。通用 cancel-requested 观察是唯一核心协调新增项。
@@ -125,5 +125,5 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 - **没有通用 loop 日志或执行世界回退**——会话重放会重建目标历史，而不会恢复此前文件、进程、环境、凭据或外部副作用。Ralph 把当前工作区作为权威，并且没有跨运行日志。
 - **没有目标反思器**——concern 事件、自动无进展启发式、由独立反思器执行的目标修订、卡住模式检测与 `loop_split` 均未实现。人类可以直接编辑、暂停、清除或恢复目标。
 - **Ralph 策略仍然狭窄**——一个 Round 创建一个全新子 agent；Round 内扇出、评估器/工作者角色分离、动态 provider/模型选择与从结构上禁止递归调用 Ralph 工具都需要独立策略表面。提示词指导不是强制执行。
-- **Ralph 不会重试失败的子 agent**——普通失败会保留失败 Round 与上一份有效交接，而致命工作流基础设施错误可能在该状态可用前结束。重试次数、退避与更丰富的失败传输需要独立的策略与 seam 设计。
+- **Ralph 不会重试失败的子 agent**——普通失败会保留失败 Round 与上一份有效交接，而致命工作流基础设施错误可能在该状态可用前结束。重试次数、退避与更丰富的失败传输需要独立的策略与边界设计。
 - **可移植 UI 仍较朴素**——TUI 渲染纯文本目标状态和通用 Ralph 卡片。ACP 只承载已提交的助手文本；系统没有持续状态组件、可重连命令输出、模态目标编辑器，ACP、无头 CLI 与 JSON-RPC 也没有命令平面。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index f41c42e700..1730793d35 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 219f48235d527cffbf66020ceb22e80ca473093d
-2026-07-16-persistent-pty-sessions.zh.md: c3842936248fb2d1705708dfd694be563ce2adf9
+2026-07-16-persistent-pty-sessions.md: 5d45f5fd13099352d503bc3296e4f6b7b0c53bc8
+2026-07-16-persistent-pty-sessions.zh.md: a0b4150157110b64943a42ce4e3544342e1be788
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 219f48235d..5d45f5fd13 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -26,7 +26,7 @@ The implementation supports interactive shells and line-oriented REPLs on Linux
 | `dsh-pty-local` | Persistent-shell backend over `ctx.subprocess.spawnTerminal()`: readiness, bounded terminal buffers, sandbox resolution, and owner-aware session lifecycle | registers a backend on `ctx.pty` |
 | `dsh-tool-pty` | Six model-facing tools, task-runtime integration for background sends, guidance, and UI render intents | registers on `ctx.tools` |
 
-Readiness remains PTY-backend behavior, not a second public seam. The terminal-process provider supplies only substrate facts such as the foreground process group and whether it can prove that group is waiting on input; `dsh-pty-local` combines those facts with prompt and silence evidence into the common send result.
+Readiness remains PTY-backend behavior, not a second public contract. The terminal-process provider supplies only substrate facts such as the foreground process group and whether it can prove that group is waiting on input; `dsh-pty-local` combines those facts with prompt and silence evidence into the common send result.
 
 ### Agent ownership and identity
 
@@ -64,7 +64,7 @@ The UI render contract is exact and location-free. `terminal_send` uses terminal
 
 Foreground sends return a bounded rendered delta and two independent facts: `waitReason` (`stdin_read | inferred_idle | timeout | session_exit`) and `sessionStatus` (`running` or `exited` with exit code or signal). `session_exit` refers to the PTY's top-level shell process, not an arbitrary foreground command whose status the shell consumes. A timeout never implies process exit. `dsh-tool-pty.maxResultBytes` defaults to 262144, rejects values below 64 so creation acknowledgements retain registry-issued ids, and caps each single-text UTF-8 result after normalized tool or pipeline errors, wait, session, pagination, truncation, generic task-status wrappers, policy denials or short-circuits, and post-execute replacements or blocks; the terminal definitions' last-mile `finalizeContent` callback leaves deliberately structured multi-block policy content unchanged. The renderer reserves suffix space and preserves code-point boundaries instead of treating the backend payload cap as the final model bound.
 
-With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `ctx.tasks` and returns immediately with `taskId`. The producer places `maxResultBytes` on the task snapshot so `task_output`, terminal kill status, and completion notices enforce the same complete-result cap after generic metadata. `task_output(wait: true)` waits, reads incremental output, and records the final result; `task_kill` resolves the current foreground PGID and delivers a real `SIGINT`, including when the application has disabled terminal `ISIG`, and escalates only through the PTY backend's owned teardown path. If the task surface is absent, background mode fails before writing input. No PTY-specific `sleep` tool or general wake-up seam is added.
+With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `ctx.tasks` and returns immediately with `taskId`. The producer places `maxResultBytes` on the task snapshot so `task_output`, terminal kill status, and completion notices enforce the same complete-result cap after generic metadata. `task_output(wait: true)` waits, reads incremental output, and records the final result; `task_kill` resolves the current foreground PGID and delivers a real `SIGINT`, including when the application has disabled terminal `ISIG`, and escalates only through the PTY backend's owned teardown path. If the task surface is absent, background mode fails before writing input. No PTY-specific `sleep` tool or general wake-up API is added.
 
 `terminal_read` pages backward from the newest retained line. The backend enforces both line and UTF-8 byte caps on retained scrollback and the returned page payload, so one oversized line cannot bypass the backend bound; the tool then caps the fully rendered page including pagination and truncation metadata. `truncated` distinguishes retention loss from an ordinary viewport delta.
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index c384293624..a0b4150157 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -26,7 +26,7 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 | `dsh-pty-local` | 基于 `ctx.subprocess.spawnTerminal()` 的持久 shell 后端：就绪状态、有界终端缓冲、沙箱解析和感知 owner 的会话生命周期 | 在 `ctx.pty` 上注册后端 |
 | `dsh-tool-pty` | 6 个面向模型的工具、后台发送的 task 运行时集成、使用指引和 UI 渲染意图 | 注册到 `ctx.tools` |
 
-就绪判定仍属于 PTY 后端行为，不是第二条公共 seam。终端进程提供方只提供基底事实，例如前台进程组，以及能否证明该组正在等待输入；`dsh-pty-local` 将这些事实与提示符和静默证据组合成统一的发送结果。
+就绪判定仍属于 PTY 后端行为，不是第二条公共约定。终端进程提供方只提供基底事实，例如前台进程组，以及能否证明该组正在等待输入；`dsh-pty-local` 将这些事实与提示符和静默证据组合成统一的发送结果。
 
 ### agent 所有权与身份
 
@@ -64,7 +64,7 @@ UI 渲染约定精确且不携带位置信息。`terminal_send` 只为前台发
 
 前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。`dsh-tool-pty.maxResultBytes` 默认为 262144；低于 64 的值会被拒绝，以确保创建确认保留 registry 签发的 id；每个单文本 UTF-8 结果在加入规范化的工具或流水线错误、等待、会话、分页、截断、通用 task 状态包装、策略拒绝或短路以及 post-execute 替换或阻断后，仍受该值限制；终端定义自有的末端 `finalizeContent` callback 会原样保留策略刻意返回的结构化多 block 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
-当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。生产方把 `maxResultBytes` 写入 task 快照，使 `task_output`、kill 返回的终态状态和完成通知在加上通用元数据后，仍对完整结果执行同一上限。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 会解析当前前台 PGID 并发送真正的 `SIGINT`，即使应用已禁用终端 `ISIG` 也同样如此，且后续升级仍只通过 PTY 后端拥有的 teardown 路径进行。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 seam。
+当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。生产方把 `maxResultBytes` 写入 task 快照，使 `task_output`、kill 返回的终态状态和完成通知在加上通用元数据后，仍对完整结果执行同一上限。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 会解析当前前台 PGID 并发送真正的 `SIGINT`，即使应用已禁用终端 `ISIG` 也同样如此，且后续升级仍只通过 PTY 后端拥有的 teardown 路径进行。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 API。
 
 `terminal_read` 从最新保留行向后分页。后端同时对保留的 scrollback 和返回页载荷执行行数与 UTF-8 字节上限，因此单个超长行无法绕过后端上限；工具随后再限制包含分页与截断元数据的完整渲染页。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
index 2e02bddec1..50c5668e6c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.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 .agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
-2026-07-19-fresh-agent-ralph-workflow-tool.md: 6fe96587c49ef0316d1618fda2ee26b015b1ce87
-2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7cd3cf388f9d1e03390dd08ed045562bcfeb1f4d
+2026-07-19-fresh-agent-ralph-workflow-tool.md: bbc8aba54bbd2cbfe9d9ba1fcc8cf9ad5c257d4f
+2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7ac405c2f6f80fa3151fb8b88c266ae2b83ea3eb
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
index 6fe96587c4..bbc8aba54b 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
@@ -12,7 +12,7 @@ Adding Ralph behavior to `dsh-agent-loop`, the goal driver, or the public model-
 
 ## Decision
 
-Add `@deepseek-ai/dsh-tool-ralph` as a separate consumer package under `packages/workflow/`. It registers `ralph({ objective, maxRounds? })`, owns a fixed workflow script, and depends only on `ctx.tools`, `ctx.systemPrompt`, `ctx.workflows`, and `ctx.subagents`. A Ralph run is not a session goal, creates no goal state, and requires no branch in the concrete agent loop.
+Add `@deepseek-ai/dsh-tool-ralph` as a separate Consumer package under `packages/workflow/`. It registers `ralph({ objective, maxRounds? })`, owns a fixed workflow script, and depends only on `ctx.tools`, `ctx.systemPrompt`, `ctx.workflows`, and `ctx.subagents`. A Ralph run is not a session goal, creates no goal state, and requires no branch in the concrete agent loop.
 
 The tool is foreground-only. The calling agent parents every child for cwd and lineage, the parent tool call waits for the complete run, and the parent step's abort signal cancels the workflow. `run.dispose()` is awaited on every path, so cancellation reaches the worker engine's bounded settlement and child quiescence before the call returns.
 
@@ -70,5 +70,5 @@ A keyless real-stack integration drives the fixed script through the actual work
 - Runs are foreground and process-local. Background collection, persistence/resume, scheduling, and restart recovery are absent.
 - Round count is the only aggregate budget. Token, currency, elapsed-time, and provider-usage budgets remain separate future policy.
 - One round creates one child. Within-round fan-out, evaluator/worker role separation, dynamic provider or model selection, and cross-run journals are deferred.
-- An ordinary child failure ends the run without retry, while preserving the failed round and last successful handoff. Fatal workflow infrastructure failures can end before the fixed script returns that state; adding retry or richer failure transport requires separate policy and seam design.
+- An ordinary child failure ends the run without retry, while preserving the failed round and last successful handoff. Fatal workflow infrastructure failures can end before the fixed script returns that state; adding retry or richer failure transport requires separate policy and boundary design.
 - Prompt guidance asks models not to invoke Ralph recursively; a structural child-tool restriction would require a separately designed workflow child-policy surface.
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
index 7cd3cf388f..7ac405c2f6 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-在 `packages/workflow/` 下新增独立的消费方包 `@deepseek-ai/dsh-tool-ralph`。它注册 `ralph({ objective, maxRounds? })`，拥有固定工作流脚本，并且只依赖 `ctx.tools`、`ctx.systemPrompt`、`ctx.workflows` 和 `ctx.subagents`。Ralph 运行不是会话目标，不会创建目标状态，也不要求在具体 agent loop 中增加分支。
+在 `packages/workflow/` 下新增独立的 Consumer 包 `@deepseek-ai/dsh-tool-ralph`。它注册 `ralph({ objective, maxRounds? })`，拥有固定工作流脚本，并且只依赖 `ctx.tools`、`ctx.systemPrompt`、`ctx.workflows` 和 `ctx.subagents`。Ralph 运行不是会话目标，不会创建目标状态，也不要求在具体 agent loop 中增加分支。
 
 该工具仅以前台方式运行。调用 agent 作为每个子 agent 的父级以提供 cwd 和谱系，父工具调用等待整次运行结束，父步骤的中止信号会取消工作流。每条路径都会等待 `run.dispose()`，因此调用返回前，取消会经过工作线程引擎的有界收敛并使子 agent 完全停稳。
 
@@ -70,5 +70,5 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
 - 运行位于前台且只存在于进程内。后台收集、持久化/恢复、调度和重启恢复均不存在。
 - Round 数是唯一聚合预算。token、货币、耗时和提供方用量预算仍属于未来的独立策略。
 - 每个 Round 创建一个子 agent。Round 内扇出、evaluator/工作者角色分离、动态提供方或模型选择，以及跨运行日志均被推迟。
-- 普通子 agent 失败会结束运行且不重试，同时保留失败 Round 与上一份成功交接。致命工作流基础设施错误可能在固定脚本返回该状态前结束；增加重试或更丰富的失败传输需要独立的策略与 seam 设计。
+- 普通子 agent 失败会结束运行且不重试，同时保留失败 Round 与上一份成功交接。致命工作流基础设施错误可能在固定脚本返回该状态前结束；增加重试或更丰富的失败传输需要独立的策略与边界设计。
 - 提示指导模型不要递归调用 Ralph；结构化的子 agent 工具限制需要另行设计工作流子策略表面。
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index 088290b3fc..bedab21f20 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.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 .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
-2026-07-19-model-facing-goal-tools.md: abed410c7fd71b18c2cc0d0db745e76d98352546
-2026-07-19-model-facing-goal-tools.zh.md: a51ad417ff0928583ccddddafe65d23bc86bd24d
+2026-07-19-model-facing-goal-tools.md: c2f1210ea636b61e99111d261cf9302c77576b46
+2026-07-19-model-facing-goal-tools.zh.md: fd8ca90ba3b6809a7225b118ec6d311fb193cc8f
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
index abed410c7f..c2f1210ea6 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
@@ -12,7 +12,7 @@ The surface also needs to preserve the separation between durable state and live
 
 ## Decision
 
-`@deepseek-ai/dsh-tool-goal` in `packages/goal/tool-goal/` contributes three exclusive tools and one system-prompt policy section over `ctx.goals`: `get_goal`, `create_goal`, and `update_goal`. The names and read-create-update shape follow Codex's compact goal tool surface while the authority rules use this repository's public agent, session, tool, and goal seams.
+`@deepseek-ai/dsh-tool-goal` in `packages/goal/tool-goal/` contributes three exclusive tools and one system-prompt policy section over `ctx.goals`: `get_goal`, `create_goal`, and `update_goal`. The names and read-create-update shape follow Codex's compact goal tool surface while the authority rules use this repository's public agent, session, tool, and goal services.
 
 ### Tools and model contract
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index a51ad417ff..fd8ca90ba3 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-位于 `packages/goal/tool-goal/` 的 `@deepseek-ai/dsh-tool-goal` 在 `ctx.goals` 之上贡献三个独占工具和一个系统提示词策略段：`get_goal`、`create_goal` 与 `update_goal`。工具名称和读取—创建—更新形态遵循 Codex 的紧凑目标工具表面，而权限规则使用本仓库公共的 agent（智能体）、会话、工具与目标 seam。
+位于 `packages/goal/tool-goal/` 的 `@deepseek-ai/dsh-tool-goal` 在 `ctx.goals` 之上贡献三个独占工具和一个系统提示词策略段：`get_goal`、`create_goal` 与 `update_goal`。工具名称和读取—创建—更新形态遵循 Codex 的紧凑目标工具表面，而权限规则使用本仓库公共的 agent（智能体）、会话、工具与目标服务。
 
 ### 工具与模型约定
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
index 578218ce21..c14cfe4c3b 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.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 .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
-2026-07-19-persisted-same-session-goal-domain.md: ce93a652f3910912fbf6afc28061de4d13eb2de2
-2026-07-19-persisted-same-session-goal-domain.zh.md: ddb4fdedafbacbfec355a7a1c912a5f9545e208a
+2026-07-19-persisted-same-session-goal-domain.md: cdbbdd55c8c9b73851d5e729492656eda1380430
+2026-07-19-persisted-same-session-goal-domain.zh.md: 7c8af321ec78779ecbf4e5e00805ef6f152b2aa1
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
index ce93a652f3..cdbbdd55c8 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-19-persisted-same-session-goal-domain.zh.md)
 
 A long-running objective outlives one prompt, turn, or model request. Treating that objective as an in-memory loop variable loses it on process restart, while putting it only in UI state makes model behavior impossible to reconstruct. Treating every session turn as progress also charges unrelated human messages against an automatic-work budget.
 
-Durable lifecycle and permission to continue are different facts. A session may retain an active objective after restart or fork, but silently starting work when a user opens that session is surprising. The domain needs replayable state without persisted auto-execution authority, and it must remain a plugin on the public agent/session seams rather than a special case in the concrete loop.
+Durable lifecycle and permission to continue are different facts. A session may retain an active objective after restart or fork, but silently starting work when a user opens that session is surprising. The domain needs replayable state without persisted auto-execution authority, and it must remain a plugin on the public agent and session services rather than a special case in the concrete loop.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
index ddb4fdedaf..7c8af321ec 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 长时间运行的目标会跨越单个提示词、轮次或模型请求。若把该目标视为内存中的循环变量，进程重启时就会丢失；若只存放在 UI 状态中，又无法重建模型行为。若把会话中的每个轮次都视为目标进度，与自动工作无关的人类消息也会消耗预算。
 
-持久化的生命周期与继续执行的权限是两个不同事实。会话在重启或 fork（派生）后可以保留活跃目标，但用户打开会话时静默启动工作并不符合直觉。该领域需要可回放的状态，却不能持久化自动执行权限；它还必须作为公共 agent（智能体）与会话 seam 上的插件存在，而不是具体循环中的特例。
+持久化的生命周期与继续执行的权限是两个不同事实。会话在重启或 fork（派生）后可以保留活跃目标，但用户打开会话时静默启动工作并不符合直觉。该领域需要可回放的状态，却不能持久化自动执行权限；它还必须作为公共 agent（智能体）与会话服务上的插件存在，而不是具体循环中的特例。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
index 4fd53a1941..d5c7073d5c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.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 .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
-2026-07-19-same-session-goal-round-driver.md: a989b9d3487ebbf8ff11a4e34cb08029f1e4ace4
-2026-07-19-same-session-goal-round-driver.zh.md: 309b5ce45c2edb516a329f9992cea5558a2aeb8c
+2026-07-19-same-session-goal-round-driver.md: 2ca08e4b6f0d16d66663db5275f3bce72bd3a9d7
+2026-07-19-same-session-goal-round-driver.zh.md: a41d9705e18cddb851c0a99a8dd7fc901f2be81a
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
index a989b9d348..2ca08e4b6f 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
@@ -49,7 +49,7 @@ The driver classifies one closed goal-owned turn as follows:
 
 No abnormal outcome requests an automatic retry. A later human prompt can ask to continue in any language; the model reads the stopped goal and uses the goal tool's resume action, which records a new revision and arms continuation.
 
-### Durability and cancellation seam
+### Durability and cancellation contract
 
 Every `goal/changed` notification creates a checkpoint obligation. The driver awaits `ctx.sessions.flush(session)` before reserving work, then checks for a newer mutation, agent lifecycle change, or competing prompt. Turn-end flush failure is reported by the existing `agent/error` notification after `turn/end`; the driver finds that exact closed turn even when a concurrent one-shot injection appended a later turn, associates the failure with the exact attempt, and disarms before the next idle decision.
 
@@ -75,7 +75,7 @@ The core cancellation test proves notification order and containment: observers
 
 ## Alternatives considered
 
-- **Add a goal loop inside `dsh-agent-loop`** — rejected because the public queue, prompt, session, cancellation, and status seams are sufficient, and a concrete-loop branch would privilege one policy.
+- **Add a goal loop inside `dsh-agent-loop`** — rejected because the public queue, prompt, session, cancellation, and status contracts are sufficient, and a concrete-loop branch would privilege one policy.
 - **Use `agent/turn-continuation` to make every round another step** — rejected because a goal round is an outer policy iteration and must have its own durable user prompt, turn boundary, round count, and failure settlement.
 - **Persist a pending reservation** — rejected because a crash cannot prove that queued process memory had reached admission; only the durable `user/message` consumes the round.
 - **Retry provider or persistence errors automatically** — rejected because retry policy spends resources and needs explicit authority; stopped phases plus later human resume are simpler and observable.
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
index 309b5ce45c..a41d9705e1 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
@@ -49,7 +49,7 @@ Status: implemented
 
 异常结果都不会请求自动重试。之后的人类提示词可以用任何语言要求继续；模型读取已停止目标并调用目标工具的 resume 动作，记录新修订并重新激活继续执行。
 
-### 持久性与取消 seam
+### 持久性与取消约定
 
 每次 `goal/changed` 通知都会产生一个检查点义务。驱动器在预留工作前等待 `ctx.sessions.flush(session)`，随后检查是否出现了更新的变更、agent 生命周期变化或竞争提示词。轮次结束时的 flush 失败会在 `turn/end` 之后通过现有 `agent/error` 通知报告；即使并发的一次性注入已追加后续轮次，驱动器仍会找到对应的同一个已关闭轮次，把失败关联到对应的同一次尝试，并在下一次空闲决策前解除激活。
 
@@ -75,7 +75,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-- **在 `dsh-agent-loop` 内添加目标循环**——不予采纳，因为公共队列、提示词、会话、取消和状态 seam 已经足够，具体循环分支还会赋予某种策略特权。
+- **在 `dsh-agent-loop` 内添加目标循环**——不予采纳，因为公共队列、提示词、会话、取消和状态约定已经足够，具体循环分支还会赋予某种策略特权。
 - **使用 `agent/turn-continuation` 把每个 Round 变成另一个步骤**——不予采纳，因为 Goal Round 是外层策略迭代，必须拥有自己的持久用户提示词、轮次边界、Round 计数和失败结算。
 - **持久化待处理预留**——不予采纳，因为崩溃无法证明进程内队列已经达到接纳点；只有持久 `user/message` 才消耗回合。
 - **自动重试提供方或持久化错误**——不予采纳，因为重试会消耗资源，需要显式授权；停止阶段加之后的人类恢复更简单，也可观察。
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
index 900165a080..bd135deda4 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.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 .agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
-2026-07-20-code-mode-typed-tool-returns.md: 2081d8161f0ee14493a09762b18ec7d9d07ea3c4
-2026-07-20-code-mode-typed-tool-returns.zh.md: 808f8f96dbb1655dc00d1ccd9bb7f7ac93c9550f
+2026-07-20-code-mode-typed-tool-returns.md: 059c715e35fb856e92d35926e6133701e5602c97
+2026-07-20-code-mode-typed-tool-returns.zh.md: 1bb88d29ffd96d65ce06033202499d2780814abd
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
index 2081d8161f..059c715e35 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
@@ -51,9 +51,9 @@ declare const tools: {
 
 Before dispatch the bridge snapshots binding arguments as lossless JSON and snapshots the detached value again for an independent durable summary event. Host-side detachment, immutable execution, and output-schema projection all use iterative traversals rather than nested structured clone or recursive freezing. `undefined`, non-finite numbers, `-0`, sparse arrays, cycles, functions, and exotic objects reject that call before the tool runs. Successful dispatch returns `ToolExecutionResult.value`; Native `content`, metadata, and internal error information do not cross to the program.
 
-Code Mode declares its rejection capability on the runtime request as `{ name: "ToolCallError", memberNameProperty: "toolName" }`. The runtime seam treats those names as data: the worker materializes and injects the actual constructor used for `tools` binding failures, so `error instanceof ToolCallError` works without making a generic runtime know about tools. The worker constructs failures and defines their public fields through module-captured error and property-definition intrinsics plus null-prototype descriptors, so model mutations cannot replace the promised rejection with a worker failure. The error has the standard `Error` message plus the exact `toolName`; it deliberately omits `ToolFailure.info`, error codes, and Native content. This is an exception contract for control flow, not a failure union for programmatic classification.
+Code Mode declares its rejection capability on the runtime request as `{ name: "ToolCallError", memberNameProperty: "toolName" }`. The runtime Service Definition treats those names as data: the worker materializes and injects the actual constructor used for `tools` binding failures, so `error instanceof ToolCallError` works without making a generic runtime know about tools. The worker constructs failures and defines their public fields through module-captured error and property-definition intrinsics plus null-prototype descriptors, so model mutations cannot replace the promised rejection with a worker failure. The error has the standard `Error` message plus the exact `toolName`; it deliberately omits `ToolFailure.info`, error codes, and Native content. This is an exception contract for control flow, not a failure union for programmatic classification.
 
-Binding arguments and resolutions are revalidated as lossless JSON on both sides of the hostile worker protocol and have no byte cap. Before crossing through structured clone, each detached value is encoded as a flat pre-order token stream whose transport nesting is bounded; the receiver rebuilds it iteratively. Valid application nesting therefore has neither a JavaScript call-stack depth cap nor a platform-specific nested structured-clone limit. At module initialization the worker captures its own realm's `Array.prototype` and `Object.prototype` identities, the native function-source intrinsic used only to recognize foreign-realm plain-container prototypes, and every structural and metering intrinsic used by the JSON boundary. Property writes use null-prototype descriptors, while private array and set operations invoke captured methods without consulting mutable global or prototype slots. Model code can therefore replace helpers such as `Object.keys`, `Array.isArray`, collection methods, string methods, or `Buffer.byteLength`, rewrite intrinsic-prototype constructor slots, or add descriptor-shaped fields to `Object.prototype` without changing validation, wire transport, or byte accounting. The foreign-realm native function-source check still rejects user-authored constructors that imitate `Object` or `Array`. The dependency-light runtime seam names its structural equivalent `CodeJsonValue` so it need not depend on the session-owned canonical type; the generated SDK and tool API use `JsonValue`. Intermediate values are not prompt-truncated, context-spilled, or persisted. This preserves full acquired search, workflow, task, filesystem, and MCP values for programmatic filtering while leaving provider and executor acquisition limits truthful.
+Binding arguments and resolutions are revalidated as lossless JSON on both sides of the hostile worker protocol and have no byte cap. Before crossing through structured clone, each detached value is encoded as a flat pre-order token stream whose transport nesting is bounded; the receiver rebuilds it iteratively. Valid application nesting therefore has neither a JavaScript call-stack depth cap nor a platform-specific nested structured-clone limit. At module initialization the worker captures its own realm's `Array.prototype` and `Object.prototype` identities, the native function-source intrinsic used only to recognize foreign-realm plain-container prototypes, and every structural and metering intrinsic used by the JSON boundary. Property writes use null-prototype descriptors, while private array and set operations invoke captured methods without consulting mutable global or prototype slots. Model code can therefore replace helpers such as `Object.keys`, `Array.isArray`, collection methods, string methods, or `Buffer.byteLength`, rewrite intrinsic-prototype constructor slots, or add descriptor-shaped fields to `Object.prototype` without changing validation, wire transport, or byte accounting. The foreign-realm native function-source check still rejects user-authored constructors that imitate `Object` or `Array`. The dependency-light runtime Service Definition names its structural equivalent `CodeJsonValue` so it need not depend on the session-owned canonical type; the generated SDK and tool API use `JsonValue`. Intermediate values are not prompt-truncated, context-spilled, or persisted. This preserves full acquired search, workflow, task, filesystem, and MCP values for programmatic filtering while leaving provider and executor acquisition limits truthful.
 
 ### Outer result and output ledger
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
index 808f8f96db..1bb88d29ff 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
@@ -51,9 +51,9 @@ declare const tools: {
 
 分发前，桥接层会把绑定参数快照为无损 JSON，再对分离后的值生成一次快照，供独立的持久摘要事件使用。宿主侧的值分离、执行数据的不可变处理与输出 schema 投影均采用迭代遍历，而不使用嵌套结构化克隆或递归冻结。`undefined`、非有限数、`-0`、稀疏数组、循环引用、函数和非普通对象都会使该调用在工具运行前被拒绝。成功分发会返回 `ToolExecutionResult.value`；Native `content`、元数据和内部错误信息不会传入程序。
 
-Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 seam 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把约定承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常约定，而不是供程序分类的失败联合。
+Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 Service Definition 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把约定承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常约定，而不是供程序分类的失败联合。
 
-绑定参数与绑定返回值会在不可信 worker 协议的两端重新校验为无损 JSON，且不设字节上限。每个分离后的值在通过结构化克隆跨越边界前，都会编码为扁平的前序 token 流，其传输结构的嵌套深度有界；接收方再以迭代方式重建该值。因此，有效应用数据的嵌套深度既不受 JavaScript 调用栈深度上限限制，也不受特定平台对嵌套结构化克隆施加的上限限制。模块初始化时，worker 会捕获自身 JavaScript 运行域中 `Array.prototype` 和 `Object.prototype` 的引用、仅用于识别其他运行域普通容器原型、可获取原生函数源码的内建函数，以及 JSON 边界用于结构处理和计量的全部内建方法。属性写入使用原型为 null 的属性描述符；内部的数组与集合操作直接调用捕获的方法，不会访问可变的全局或原型槽位。因此，即使模型代码替换 `Object.keys`、`Array.isArray`、集合方法、字符串方法或 `Buffer.byteLength` 等辅助方法，重写内建原型的构造函数槽位，或向 `Object.prototype` 添加形如属性描述符的字段，也不会改变校验、协议传输或字节计量。面向其他运行域的原生函数源码检查仍会拒绝由用户编写、冒充 `Object` 或 `Array` 的构造函数。为保持依赖轻量，运行时 seam 将结构等价类型命名为 `CodeJsonValue`，从而无需依赖会话侧拥有的规范类型；生成的 SDK 和工具 API 则使用 `JsonValue`。这些值不会经过提示词截断、上下文输出落盘或持久化。因此，程序可以完整筛选已经采集的搜索、工作流、任务、文件系统与 MCP 值，同时提供方和执行器的采集上限仍会实际生效。
+绑定参数与绑定返回值会在不可信 worker 协议的两端重新校验为无损 JSON，且不设字节上限。每个分离后的值在通过结构化克隆跨越边界前，都会编码为扁平的前序 token 流，其传输结构的嵌套深度有界；接收方再以迭代方式重建该值。因此，有效应用数据的嵌套深度既不受 JavaScript 调用栈深度上限限制，也不受特定平台对嵌套结构化克隆施加的上限限制。模块初始化时，worker 会捕获自身 JavaScript 运行域中 `Array.prototype` 和 `Object.prototype` 的引用、仅用于识别其他运行域普通容器原型、可获取原生函数源码的内建函数，以及 JSON 边界用于结构处理和计量的全部内建方法。属性写入使用原型为 null 的属性描述符；内部的数组与集合操作直接调用捕获的方法，不会访问可变的全局或原型槽位。因此，即使模型代码替换 `Object.keys`、`Array.isArray`、集合方法、字符串方法或 `Buffer.byteLength` 等辅助方法，重写内建原型的构造函数槽位，或向 `Object.prototype` 添加形如属性描述符的字段，也不会改变校验、协议传输或字节计量。面向其他运行域的原生函数源码检查仍会拒绝由用户编写、冒充 `Object` 或 `Array` 的构造函数。为保持依赖轻量，运行时 Service Definition 将结构等价类型命名为 `CodeJsonValue`，从而无需依赖会话侧拥有的规范类型；生成的 SDK 和工具 API 则使用 `JsonValue`。这些值不会经过提示词截断、上下文输出落盘或持久化。因此，程序可以完整筛选已经采集的搜索、工作流、任务、文件系统与 MCP 值，同时提供方和执行器的采集上限仍会实际生效。
 
 ### 外层结果与输出账本
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
index 5fd9467179..535d2a86a4 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.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 .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
-2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166
-2026-07-25-workspace-ui-product-flow.zh.md: 14f33b0eebcf8885670e72cfb6e2c9a87b7a3432
+2026-07-25-workspace-ui-product-flow.md: bfdde9797433eca67e47da73468cba855f2a02b9
+2026-07-25-workspace-ui-product-flow.zh.md: 74a9dd6f70396201a78f3204bfdc7d8b5d4f5d98
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
index 7a6a41e19d..bfdde97974 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
@@ -82,7 +82,7 @@ Deleting a Workspace registration removes its group without deleting or closing
 
 React components only consume `useSessions`, `useWorkspaces`, and session-scoped hooks; they do not own entity lifecycles. The Zustand store retains only layout, the current view, composer text for ordinary real Sessions, and other purely presentational state. Session and Workspace Intents, materialization phases, errors, and retained prompts reside in the React-free runtime object layer.
 
-The Sidebar and conversation empty hero receive standardized actions through slots: `startSession`, `updateSessionPrompt`, `sendSession`, `open`, and `toggleSidebar`. The Workspace picker reuses the same component and the `createWorkspace` seam; its owner supplies only popover state, an anchor, and a selection callback. The presentation layer does not send `host/workspace-changed` directly; Host events originate only from Host mutations and the stream adapter.
+The Sidebar and conversation empty hero receive standardized actions through slots: `startSession`, `updateSessionPrompt`, `sendSession`, `open`, and `toggleSidebar`. The Workspace picker reuses the same component and the `createWorkspace` action; its owner supplies only popover state, an anchor, and a selection callback. The presentation layer does not send `host/workspace-changed` directly; Host events originate only from Host mutations and the stream adapter.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
index 14f33b0eeb..74a9dd6f70 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
@@ -82,7 +82,7 @@ Workspace 组严格使用 Host 返回的持久顺序。Bootstrap 一次性确定
 
 React 组件只消费 `useSessions`、`useWorkspaces` 与 session-scoped 钩子，不拥有实体生命周期。Zustand store 只保留布局、当前 view、普通真实 Session 的 composer 文本和其他纯呈现状态；Session/Workspace Intent、materialize phase、错误和 retained prompt 位于 React-free 运行时对象层。
 
-Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` seam；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host 事件只由 Host mutation 与流适配器产生。
+Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` 动作；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host 事件只由 Host mutation 与流适配器产生。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
index f44f0911f5..71cb05f10a 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
-2026-07-26-code-dispatch-log-spill.md: eee8fb73b3f1ddba0a2da3ad5a9d2d4417d5951c
-2026-07-26-code-dispatch-log-spill.zh.md: 3ef95b5bc0aec1238fd9bb89f545b7f23938ea79
+2026-07-26-code-dispatch-log-spill.md: 3892a4a5a21c03d97d1873c68e2228119010e5c5
+2026-07-26-code-dispatch-log-spill.zh.md: c98b29e491e059fe27eb5b1ccea1b9664dce4639
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
index eee8fb73b3..3892a4a5a2 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
@@ -14,8 +14,8 @@ Since the full-content dispatch logging landed, a `run_code` program that reads
 
 **A log-shaping waterfall on the registry, and the spill policy as its first listener.**
 
-- **Seam**: `tools/code-dispatch-log` — a scope-filtered waterfall the bridge runs (via the registry's PRIVATE `shapeDispatchLog` invoker, handed to the bridge as a capability closure in `RunCodeBridgeOptions` — the waterfall is the public seam, the invoker never widens the service surface; contained: a throwing listener falls back to the unshaped content, with total error formatting so a hostile thrown value cannot escape the containment) over each settled sub-dispatch before appending `tool/code-dispatch`. The payload (`CodeDispatchLog`) carries the outer execution, the hoisted `agent` routing key, the sub-call identity, and the default content — the RENDERED result projection a native `tool/result` would carry (the program itself received the structured `value`). Only the durable copy is shapeable; the model sees neither. Shaping runs OFF the program path as tracked side work, but bounded: past `maxParallelSubCalls` pending log tasks the ordered commit lane holds, so a slow spill backend backpressures the run instead of accumulating unbounded pending I/O; run settlement still drains every task inside the open turn.
-- **Policy**: `dsh-spill-policy` registers a second arm on the new seam sharing the exact replacement pipeline of its model-facing arm (same `maxInlineBytes` cap, same preview + locator + within-cap invariant, same best-effort fallbacks), with the artifact labeled `dispatch` under the sub-call id. UIs and replay read the full text through the spill artifact exactly as they do for spilled native results, so the native-parity rendering story survives bounding.
+- **Extension point**: `tools/code-dispatch-log` — a scope-filtered waterfall the bridge runs (via the registry's PRIVATE `shapeDispatchLog` invoker, handed to the bridge as a capability closure in `RunCodeBridgeOptions` — the waterfall is the public contract, the invoker never widens the service surface; contained: a throwing listener falls back to the unshaped content, with total error formatting so a hostile thrown value cannot escape the containment) over each settled sub-dispatch before appending `tool/code-dispatch`. The payload (`CodeDispatchLog`) carries the outer execution, the hoisted `agent` routing key, the sub-call identity, and the default content — the RENDERED result projection a native `tool/result` would carry (the program itself received the structured `value`). Only the durable copy is shapeable; the model sees neither. Shaping runs OFF the program path as tracked side work, but bounded: past `maxParallelSubCalls` pending log tasks the ordered commit lane holds, so a slow spill backend backpressures the run instead of accumulating unbounded pending I/O; run settlement still drains every task inside the open turn.
+- **Policy**: `dsh-spill-policy` registers a second arm on the new extension point sharing the exact replacement pipeline of its model-facing arm (same `maxInlineBytes` cap, same preview + locator + within-cap invariant, same best-effort fallbacks), with the artifact labeled `dispatch` under the sub-call id. UIs and replay read the full text through the spill artifact exactly as they do for spilled native results, so the native-parity rendering story survives bounding.
 - **One deliberate asymmetry**: the model-facing arm skips `read` (the `read → spill → read again` loop); the dispatch-log arm bounds `read` sub-calls too — a log copy is not model context, so the loop cannot happen, and `read` is precisely the tool that produces huge logs.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
index 3ef95b5bc0..c98b29e491 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
@@ -14,8 +14,8 @@ Status: implemented
 
 **在注册表上增设一个日志整形 waterfall（瀑布式事件），spill 策略作为其第一个监听器。**
 
-- **seam**：`tools/code-dispatch-log`，一个按作用域过滤的 waterfall，由桥接层在追加 `tool/code-dispatch` 之前对每个已结算的子分发运行（经由注册表的私有 `shapeDispatchLog` 调用器——作为能力闭包经 `RunCodeBridgeOptions` 交给桥接层；waterfall 才是公开 seam，调用器绝不扩大服务接口。故障被兜住：监听器抛出异常时回退到未整形的内容，并用可处理任意抛出值的错误格式化，确保恶意抛出值无法逃出兜底）。载荷（`CodeDispatchLog`）携带外层执行、提升出来的 `agent` 路由键、子调用标识与默认内容——即原生 `tool/result` 所载的渲染后结果投影（程序本身收到的是结构化 `value`）。可整形的只有持久副本；模型两者都看不到。整形作为被跟踪的旁路工作在程序路径之外运行，但有界：待处理日志任务超过 `maxParallelSubCalls` 时有序提交通道会暂停，因此慢速 spill 后端会对整个 run 施加背压，而不是无限累积待完成 I/O；run 结算仍会在开放轮次内排空全部任务。
-- **策略**：`dsh-spill-policy` 在新 seam 上注册第二个分支，与其面向模型的分支共用一模一样的替换流水线（同样的 `maxInlineBytes` 上限、同样的预览 + 定位符 + 不超上限不变式、同样的尽力而为回退），产物以 `dispatch` 为标签，记在子调用 id 名下。UI 与回放通过 spill 产物读取全文，方式与读取被 spill 的原生结果完全相同，因此与原生同等保真的渲染在施加边界之后依然成立。
+- **扩展点**：`tools/code-dispatch-log`，一个按作用域过滤的 waterfall，由桥接层在追加 `tool/code-dispatch` 之前对每个已结算的子分发运行（经由注册表的私有 `shapeDispatchLog` 调用器——作为能力闭包经 `RunCodeBridgeOptions` 交给桥接层；waterfall 才是公开约定，调用器绝不扩大服务接口。故障被兜住：监听器抛出异常时回退到未整形的内容，并用可处理任意抛出值的错误格式化，确保恶意抛出值无法逃出兜底）。载荷（`CodeDispatchLog`）携带外层执行、提升出来的 `agent` 路由键、子调用标识与默认内容——即原生 `tool/result` 所载的渲染后结果投影（程序本身收到的是结构化 `value`）。可整形的只有持久副本；模型两者都看不到。整形作为被跟踪的旁路工作在程序路径之外运行，但有界：待处理日志任务超过 `maxParallelSubCalls` 时有序提交通道会暂停，因此慢速 spill 后端会对整个 run 施加背压，而不是无限累积待完成 I/O；run 结算仍会在开放轮次内排空全部任务。
+- **策略**：`dsh-spill-policy` 在新扩展点上注册第二个分支，与其面向模型的分支共用一模一样的替换流水线（同样的 `maxInlineBytes` 上限、同样的预览 + 定位符 + 不超上限不变式、同样的尽力而为回退），产物以 `dispatch` 为标签，记在子调用 id 名下。UI 与回放通过 spill 产物读取全文，方式与读取被 spill 的原生结果完全相同，因此与原生同等保真的渲染在施加边界之后依然成立。
 - **一处有意的不对称**：面向模型的分支跳过 `read`（避免 `read → spill → read again` 循环）；分发日志分支则连 `read` 子调用也施加边界：日志副本不是模型上下文，该循环因此不可能发生，而 `read` 恰恰是会产生巨大日志的那个工具。
 
 ## 曾考虑的替代方案
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
index f8ccab3362..e809bdfc6c 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
-2026-07-26-code-dispatch-ui-foundation.md: a1629c77304bc7ef744f7a09241bcdfc81e461ae
-2026-07-26-code-dispatch-ui-foundation.zh.md: 8f40281454e78d3d1baaf0dce3635bdf01d0a658
+2026-07-26-code-dispatch-ui-foundation.md: 1714472018a415114efed7ce189a3d82268dd8e3
+2026-07-26-code-dispatch-ui-foundation.zh.md: 8ede615bf15b99c5ecf9a8da427b571180921e54
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
index a1629c7730..1714472018 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-26-code-dispatch-ui-foundation.zh.md)
 
-> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement seam for the `dsh` config tree.
+> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement switch for the `dsh` config tree.
 
 ## Problem
 
@@ -16,7 +16,7 @@ Three changes, one per obstacle:
 
 1. **`run_code` gains a required `description` parameter** (bash's exact contract: active voice, 5-10 words, shown in the UI; whitespace-only rejected at execute). `presentCall` now titles the card with the description and moves the program to `rawInput`. The prompt-side cost is a few tokens per call; the return is that every surface — TUI card, ACP title, web row — gets a human-readable label without parsing TypeScript.
 2. **`tool/code-dispatch` logs the sub-call's complete model-facing outcome** — `content: ContentBlock[]` + `isError`, the `tool/result` vocabulary — replacing `resultSummary` and deleting the summarize/cwd-normalization machinery outright. A UI renders a sub-call through the identical code path as a native result, including error text and non-text blocks. The event stays log-only (`deriveMessages()` ignores it): nothing about model context changes.
-3. **`DSH_TOOLS_MODE` env var on the `dsh` config tree** (`native`|`code`|`both`; unset keeps the schema default): the `tools` row reads it via `!!js`, and the worker code runtime is mounted unconditionally (Loader metadata is static, so no conditional row exists; a native boot only registers the service — workers spawn per run). This is an explicitly temporary seam: per-session tool-mode selection owned by the web UI is the design goal, and the env var dies when that lands.
+3. **`DSH_TOOLS_MODE` env var on the `dsh` config tree** (`native`|`code`|`both`; unset keeps the schema default): the `tools` row reads it via `!!js`, and the worker code runtime is mounted unconditionally (Loader metadata is static, so no conditional row exists; a native boot only registers the service — workers spawn per run). This is an explicitly temporary configuration hook: per-session tool-mode selection owned by the web UI is the design goal, and the env var dies when that lands.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
index 8f40281454..8ede615bf1 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
 
-> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
+> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用开关，归本篇所有。
 
 ## 问题
 
@@ -16,7 +16,7 @@ Status: implemented
 
 1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的约定：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、Web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
 2. **`tool/code-dispatch` 记录子调用面向模型的完整结果**（`content: ContentBlock[]` 加 `isError`，即 `tool/result` 的词汇），取代 `resultSummary`，并把摘要与 cwd 归一化机制彻底删除。UI 渲染子调用走的代码路径与渲染原生结果完全相同，包括错误文本和非文本块。该事件保持仅日志（`deriveMessages()` 忽略它）：模型上下文没有任何变化。
-3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的 seam：设计目标是让 Web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
+3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的配置钩子：设计目标是让 Web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml
index 1f1ab7d8d2..63a7bda71b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.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 .agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
-2026-07-27-tmux-location-context.md: dc9e559d1ed5cbb419901303a81e69cb0d0ba828
-2026-07-27-tmux-location-context.zh.md: 9c8a56f12406ff17ce9c25538dcfdf8e7aa06f91
+2026-07-27-tmux-location-context.md: 2a2188c920b678565173d28fb18268f951cc9a11
+2026-07-27-tmux-location-context.zh.md: c0f6e9f5ca56bef9794f55e72ffbbe3ee1be7240
diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
index dc9e559d1e..2a2188c920 100644
--- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
+++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
@@ -52,7 +52,7 @@ Unit tests pin: first-step injection and source/surface metadata; the `$TMUX_PAN
 
 - **Push from a tmux hook / background watcher** — rejected: requires installing hooks in the user's tmux and a background process with teardown, to gain mid-step freshness that per-turn context does not need.
 - **Run every step** — rejected: location is stable within a turn; re-querying adds token cost without new information. Gating on `step === 1` yields per-turn readings.
-- **Raw `child_process`** — rejected: bypasses the sandbox/policy seam and hand-rolls subprocess code the `ctx.bash` executor already owns.
+- **Raw `child_process`** — rejected: bypasses the sandbox policy path and hand-rolls subprocess code the `ctx.bash` executor already owns.
 - **Include pane/window pixel sizes** — rejected: sizes churn on every resize and add noise; the layout tree already conveys structure.
 - **Scrape sibling panes with `capture-pane`** — rejected: large, noisy, and privacy-sensitive; out of scope for "own location".
 - **Dynamic system-prompt section** — rejected: replacing a value erases the earlier readings behind prior reasoning and is not reconstructable; one durable attributed message records each location where it became visible.
diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md
index 9c8a56f124..c0f6e9f5ca 100644
--- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md
@@ -52,7 +52,7 @@ window active=<0|1>, pane active=<0|1>, layout <window-layout>
 
 - **由 tmux hook / 后台监视器推送**——否决：需要在用户的 tmux 中安装 hook，并引入带清理的后台进程，只为换取按轮次上下文并不需要的步内新鲜度。
 - **每个 step 都运行**——否决：位置在一轮内稳定；重复查询只增加 token 成本而无新信息。以 `step === 1` 为门槛得到按轮次读数。
-- **裸 `child_process`**——否决：绕过沙箱/策略 seam，并手写 `ctx.bash` 执行器已拥有的子进程代码。
+- **裸 `child_process`**——否决：绕过沙箱策略路径，并手写 `ctx.bash` 执行器已拥有的子进程代码。
 - **包含 pane/window 像素尺寸**——否决：尺寸每次缩放都变动、徒增噪声；布局树已传达结构。
 - **用 `capture-pane` 抓取相邻 pane**——否决：庞大、嘈杂且涉及隐私；超出"自身位置"范围。
 - **动态系统提示区块**——否决：替换某个值会抹去支撑先前推理的历史读数且不可重建；单条持久且带来源的消息在每个位置变得可见时予以记录。
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index e3e6e045f8..912cc3a7d7 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.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 .agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: c5c6c4eac053e9a3adfa2a2a441ac492ba3391ac
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: fe0e93cd13d0decb8d6a95abb0c5feb141dcb78b
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: e4ceeb6b1bc0b9e10fb5383454cbac1b404d4ad8
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 18e5c891f5810135b1ed5e6cfc27b94ad452c575
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
index c5c6c4eac0..e4ceeb6b1b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
@@ -10,7 +10,7 @@ The stdio JSON-RPC serving surface (`@deepseek-ai/dsh-jsonrpc`, the [single-exe
 
 ## Decision
 
-Three packages, layered exactly like the existing Python stack, plus one seam registration:
+Three packages, layered exactly like the existing Python stack, plus one Service provider registration:
 
 - **`@deepseek-ai/dsh-sdk-protocol`** (`packages/scaffold/protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
 - **`@deepseek-ai/dsh-sdk-client`** (`packages/scaffold/client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
@@ -30,7 +30,7 @@ Four tiers, per [testing policy](../../../../docs/testing.md):
 
 ## Alternatives considered
 
-**Import wire types from `dsh-jsonrpc` instead of extracting a protocol package.** Makes every SDK consumer (including `subagent-dsh-sdk`, which must not serve JSON-RPC) depend on the server plugin and its `dsh-agent`/`dsh-llm-deepseek` peer set, and leaves the notification payloads anonymous. The capability-seam rule (interface/implementation/consumer as separate packages) already names this shape; the transport is genuinely two-sided.
+**Import wire types from `dsh-jsonrpc` instead of extracting a protocol package.** Makes every SDK consumer (including `subagent-dsh-sdk`, which must not serve JSON-RPC) depend on the server plugin and its `dsh-agent`/`dsh-llm-deepseek` peer set, and leaves the notification payloads anonymous. The capability-seam rule (Service Definition / Service provider / Consumer as separate packages) already names this shape; the transport is genuinely two-sided.
 
 **Have `subagent-dsh-sdk` speak raw JSON-RPC without the client SDK.** Duplicates the request/notification pairing, subscription fan-out, timeout, and teardown logic the SDK exists to own; the user's ask was explicitly a backend that *uses* the SDK, and the layering earns its keep by making the backend ~200 lines of policy over a reusable client.
 
@@ -38,7 +38,7 @@ Four tiers, per [testing policy](../../../../docs/testing.md):
 
 **Give the TS SDK bundled-runtime resolution parity with Python.** Python's carrier resolution exists to ship wheels to users without Node. A TypeScript consumer definitionally has Node and (in-repo) the workspace; inventing a distribution story with no consumer violates the require-current-need rule. Deferred until a real npm-distribution consumer appears.
 
-**Export source modules, normalization helpers, and subscription producer operations.** These are implementation seams with no caller need; exposing them would make callers learn how the client validates and distributes wire input. The package roots instead enumerate the supported client and protocol interfaces, and the client re-exports the one protocol error callers must distinguish.
+**Export source modules, normalization helpers, and subscription producer operations.** These are implementation details with no caller need; exposing them would make callers learn how the client validates and distributes wire input. The package roots instead enumerate the supported client and protocol interfaces, and the client re-exports the one protocol error callers must distinguish.
 
 **Reuse `dsh-acp-snapshot`'s `runScenario` for the SDK snapshots.** That harness speaks ACP (`ClientSideConnection`, `InputStep` scripts). The SDK suite's whole point is to drive the *SDK client* as the entry surface; it reuses the normalize/refresh library layer (`normalizeSessionLog`, `refreshFixtureReplacements`, …) and leaves the ACP driver alone.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index fe0e93cd13..18e5c891f5 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -10,7 +10,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 ## 决策
 
-三个包，分层与既有 Python 栈完全一致，外加一个 seam 注册：
+三个包，分层与既有 Python 栈完全一致，外加一个 Service provider 注册：
 
 - **`@deepseek-ai/dsh-sdk-protocol`**（`packages/scaffold/protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
 - **`@deepseek-ai/dsh-sdk-client`**（`packages/scaffold/client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
@@ -30,7 +30,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 ## 考虑过的替代方案
 
-**从 `dsh-jsonrpc` 导入线类型而不是提取协议包。** 会让每个 SDK 消费方（包括绝不能提供 JSON-RPC 服务的 `subagent-dsh-sdk`）依赖服务器插件及其 `dsh-agent`/`dsh-llm-deepseek` peer 集合，且通知载荷仍然匿名。能力 seam 规则（接口/实现/消费方三个包分立）已经点名了这种形态；这个传输是货真价实的双边物。
+**从 `dsh-jsonrpc` 导入线类型而不是提取协议包。** 会让每个 SDK 消费方（包括绝不能提供 JSON-RPC 服务的 `subagent-dsh-sdk`）依赖服务器插件及其 `dsh-agent`/`dsh-llm-deepseek` peer 集合，且通知载荷仍然匿名。能力 seam 规则（Service Definition/Service provider/Consumer 三个包分立）已经点名了这种形态；这个传输是货真价实的双边物。
 
 **让 `subagent-dsh-sdk` 直说裸 JSON-RPC、绕开客户端 SDK。** 会复制 SDK 存在意义所在的请求/通知配对、订阅扇出、超时与拆除逻辑；用户的要求明确是一个*使用* SDK 的后端，分层的回报是后端成为可复用客户端之上约 200 行的纯策略。
 
@@ -38,7 +38,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 **给 TS SDK 与 Python 对等的捆绑运行时解析。** Python 的载体解析是为了给没有 Node 的用户发 wheel。TypeScript 消费方按定义就有 Node，且仓库内消费方还有工作区；为尚不存在的消费方编造发行方案违反「只实现当前需求」的规则。推迟到真实的 npm 发行消费方出现时再处理。
 
-**导出源模块、规范化辅助函数和订阅投递端操作。** 这些都是调用方不需要的实现 seam；暴露它们会让调用方不得不理解客户端如何校验与分发线输入。各包根转而枚举受支持的客户端接口与协议接口，客户端则只重新导出调用方必须区分的那一种协议错误。
+**导出源模块、规范化辅助函数和订阅投递端操作。** 这些都是调用方不需要的实现细节；暴露它们会让调用方不得不理解客户端如何校验与分发线输入。各包根转而枚举受支持的客户端接口与协议接口，客户端则只重新导出调用方必须区分的那一种协议错误。
 
 **复用 `dsh-acp-snapshot` 的 `runScenario` 做 SDK 快照。** 那个 harness 说 ACP（`ClientSideConnection`、`InputStep` 脚本）。SDK 套件的全部意义就是以 *SDK 客户端*为入口表面；它复用 normalize/refresh 库层（`normalizeSessionLog`、`refreshFixtureReplacements`……），不动 ACP 驱动器。
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index e6cb63c10d..5a47ad865c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
-2026-07-27-web-subagent-conversations.zh.md: f06e5f38ba49d35ac28582f1ad3ff5eebc8ace15
+2026-07-27-web-subagent-conversations.md: 42b1a553adc0222d33feeea21fa5690235d6e5e3
+2026-07-27-web-subagent-conversations.zh.md: d373662987f7afc820b180b360493c5725f13617
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index 46c4949c56..42b1a553ad 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -47,7 +47,7 @@ Selecting a row records its exact address before opening the resident client `Se
 
 A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input and Send action disabled so independent Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter and Send admit another FIFO turn even while the child runs, while independent Stop routes through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
 
-Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation seam.
+Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation path.
 
 ## Host adapter and wire contract
 
@@ -89,7 +89,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 
 **Auto-resume an absent parent.** Rejected because continuation requires the exact live direct parent. Child navigation must not mutate the parent lifecycle.
 
-**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and, at this decision's time, the continuation seam exposed no authority-safe cancellation handle. The later [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md) added that explicit authority as a dedicated subagent route; falling through to `session.cancel` remains rejected.
+**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and, at this decision's time, the continuation contract exposed no authority-safe cancellation handle. The later [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md) added that explicit authority as a dedicated subagent route; falling through to `session.cancel` remains rejected.
 
 **Show only continuable children.** Rejected because the durable catalog deliberately describes both session-backed modes. One-shot transcripts remain useful even though they never accept follow-ups.
 
@@ -105,7 +105,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
 - Client object tests pin retained and restored addresses, one-shot read-only and cancel rejection, history routing, continuable prompt and interrupt routing, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
 - jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the LLM seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index f06e5f38ba..d373662987 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -47,7 +47,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
-已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
+已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行路径之外激活持久化 child 历史。
 
 ## 宿主适配器与协议约定
 
@@ -89,7 +89,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行约定未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
@@ -105,7 +105,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
 - 客户端对象测试固定已保留与已恢复的地址、one-shot 只读与取消拒绝、历史路由、可继续提示词与中断路由、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
 - jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 LLM seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
index fa4523a51d..ca3cf443f9 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.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 .agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
-2026-07-27-workspace-registration-deletion.md: ef8a7fb9ae13c23e04a5760cd443c4a744ec4f19
-2026-07-27-workspace-registration-deletion.zh.md: 21c378b5c6d738bc6b9a00856691a56d65217586
+2026-07-27-workspace-registration-deletion.md: 08bce9fefa13f6e093aaf5ef6c8e8dfb9a409c1d
+2026-07-27-workspace-registration-deletion.zh.md: c75d29c102e3528dc755d21a2a9854a8c4a5a811
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
index ef8a7fb9ae..08bce9fefa 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
@@ -14,7 +14,7 @@ The existing visual-only menu row also left deletion semantics undefined across
 
 `ctx.workspace.delete(id)` deletes only the Workspace registration: its id leaves durable `workspaceIds`, its `workspaces` table row and entity-cache entry disappear, and its ordered `sessionIds` account disappears with that row. It never calls filesystem removal or `SessionPersistence`; the directory, every user file, every live Session, and every persisted Session log remain. Because sidebar grouping is the complement of all surviving Workspace accounts, those Sessions immediately appear under Ungrouped, including the current Session.
 
-Unknown ids return `false` at the domain seam. `workspace.delete({ workspaceId })` maps that distinction to `workspace-not-found`; success returns `{ deleted: true }`. `workspace.list` remains the reconnect baseline.
+Unknown ids return `false` at the domain contract. `workspace.delete({ workspaceId })` maps that distinction to `workspace-not-found`; success returns `{ deleted: true }`. `workspace.list` remains the reconnect baseline.
 
 ## Durable commit and publication
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
index 21c378b5c6..c75d29c102 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
@@ -14,7 +14,7 @@ Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其
 
 `ctx.workspace.delete(id)` 只删除 Workspace 注册记录：其 id 会从持久化的 `workspaceIds` 中移除，`workspaces` 表行与实体缓存条目会消失，有序 `sessionIds` 账本也随该行一并消失。它绝不调用文件系统移除操作或 `SessionPersistence`；目录、所有用户文件、所有实时会话和所有已持久化的会话日志都会保留。侧边栏分组是所有存续 Workspace 账本的补集，因此这些会话（包括当前会话）会立即出现在 Ungrouped 下。
 
-未知 id 在 domain seam 返回 `false`。`workspace.delete({ workspaceId })` 将该结果映射为 `workspace-not-found`；成功时返回 `{ deleted: true }`。`workspace.list` 仍是重连基线。
+未知 id 在领域约定处返回 `false`。`workspace.delete({ workspaceId })` 将该结果映射为 `workspace-not-found`；成功时返回 `{ deleted: true }`。`workspace.list` 仍是重连基线。
 
 ## 持久化提交与发布
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index c0e97060b2..2e5c66b55c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: 632de8c9f7a6d2c71dcca6d817a827f788645b4e
-2026-07-28-continuable-subagent-conversations.zh.md: 9752dab97684d7249418c1a6d19905ab48ac82ca
+2026-07-28-continuable-subagent-conversations.md: 991b89599d7f300c79928e568833a2cd488f5a4e
+2026-07-28-continuable-subagent-conversations.zh.md: a7d282c4fadd943ad9250e01de5d379a776a32a0
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index 632de8c9f7..991b89599d 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -117,7 +117,7 @@ The optional child-scoped `report(output)` tool was added later without changing
 
 ### Deferred steering
 
-This version exposes no subagent steering operation. Parent continuation messages always open later FIFO turns, so the continuation layer stores no current-turn controller and adds no controller-aware Agent admission seam.
+This version exposes no subagent steering operation. Parent continuation messages always open later FIFO turns, so the continuation layer stores no current-turn controller and adds no controller-aware Agent admission contract.
 
 A later host UI may expose separate **Steer** and **Follow up** actions. Host steering would be strict and live-only: it may call the existing Agent steering path only while the Activation accepts a next step, must reject otherwise, and must never fall back to queueing or cold resume. Exposing parent steering to a model-facing tool remains a separate design.
 
@@ -155,9 +155,9 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 **Dispose the Agent while waiting.** Reconstructing a parent while its child still belongs to the previous process-local ownership graph would require a durable ownership and teardown protocol. Retaining the `AgentHandle` only for the unfinished graph preserves child-first teardown without keeping settled history resident.
 
-**Let the provider create, resume, or deliver through an Agent handle.** Initial providers own only `prepareContinuable()` and its detached creation-spec distinction: whether a child begins fresh or with a parent prefix. The manager must call `ctx.agents.create()` through its private activation-owner scope so that scope is a structural owner of every handle. A persisted in-process Session already contains the initial prefix and generic reconstruction descriptor, while delivery belongs to the Agent inbox. Giving providers any later handle, `SubagentRun`, or message ownership would preserve a seam with no shipped behavior to own.
+**Let the provider create, resume, or deliver through an Agent handle.** Initial providers own only `prepareContinuable()` and its detached creation-spec distinction: whether a child begins fresh or with a parent prefix. The manager must call `ctx.agents.create()` through its private activation-owner scope so that scope is a structural owner of every handle. A persisted in-process Session already contains the initial prefix and generic reconstruction descriptor, while delivery belongs to the Agent inbox. Giving providers any later handle, `SubagentRun`, or message ownership would retain provider ownership with no shipped behavior to justify it.
 
-**Make report delivery part of the base lifecycle.** Repeatable child-to-parent reporting is compatible with this lifecycle, but quiet versus waking delivery, acknowledgement, durability, and retry behavior are independent product choices. The later report package remains optional and consumes an explicit child-setup seam, so continuable residency does not silently grant a return channel.
+**Make report delivery part of the base lifecycle.** Repeatable child-to-parent reporting is compatible with this lifecycle, but quiet versus waking delivery, acknowledgement, durability, and retry behavior are independent product choices. The later report package remains optional and consumes an explicit child-setup hook, so continuable residency does not silently grant a return channel.
 
 **Treat `SessionHeader.parentSession` as live ownership.** Durable lineage does not prove that the recorded parent currently owns the child. Membership in the live parent's `ownedChildren` records the process-local relationship without changing the durable parent id.
 
@@ -167,7 +167,7 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 **Expose subagent steering now.** Parent steering needs current-turn controller state and a separate admission policy from follow-up delivery. Queueing every first-version continuation avoids that state and its admission race.
 
-**Expose host-user follow-up without a host consumer.** A public authority-minting method and user branch would make cold resume possible without the historical parent, but no production host adapter calls that operation. The seam accepts only the exact live parent until a concrete authenticated host interaction can receive a private capability.
+**Expose host-user follow-up without a host consumer.** A public authority-minting method and user branch would make cold resume possible without the historical parent, but no production host adapter calls that operation. The continuation API accepts only the exact live parent until a concrete authenticated host interaction can receive a private capability.
 
 **Return a subagent-specific delivery route.** Labels such as `started`, `queued`, and `resumed` duplicate Activation and inbox state without giving the caller an independent result. Reusing `MessageId` and the existing inbox events keeps delivery correlation on the Agent contract that owns it.
 
@@ -193,7 +193,7 @@ The implementation pins these behaviors:
 - Every continuation-managed parent Activation disposes only after all directly owned child Activations complete `AgentHandle` disposal; top-level Agents do not join the waiting graph.
 - Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, logs rejection without interpreting listener participation as durability proof, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation.
 - Manager teardown closes admission globally; a host owning selected top-level Agents instead closes admission only below their exact identities until those roots leave the registry. Both track admitted materializations by exact ancestry, install one memoized disposal cutoff per selected visible Activation, propagate cancellation top-down, release handles child-first, await every selected branch despite individual failures, and only then dispose the corresponding top-level Agents or manager scope.
-- The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup seam.
+- The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup hook.
 - Session logs reconstruct only messages that were actually written, with the source that supplied each message; inbox-accepted but unlogged messages have no restart guarantee.
 - No continuable-subagent path creates or depends on a Task, `TaskId`, Task completion notice, Task cancellation, or intermediate result-bearing execution wrapper.
 - Unit coverage pins the `startContinuable()` inbox-acceptance return boundary, complete rollback for each pre-acceptance and lifecycle-publication failure, global and parent-scoped drain quiescence for materialization caught between Agent publication and Activation registration, sibling-forest isolation, exact ancestry after an intermediate Agent leaves the registry, provider-independent cold resume, final exact-parent reauthorization after cold-resume materialization, caller-signal and teardown ownership on both sides of acceptance, and the absence of automatic replay for accepted-but-unlogged messages.
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index 9752dab976..a7d282c4fa 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -117,7 +117,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 延后的 steering（中途引导）
 
-本版本不暴露 subagent steering 操作。parent 的继续执行消息始终开启后续 FIFO 轮次，因此继续执行层不存储当前轮次控制方，也不新增能够感知控制方的 Agent 准入 seam。
+本版本不暴露 subagent steering 操作。parent 的继续执行消息始终开启后续 FIFO 轮次，因此继续执行层不存储当前轮次控制方，也不新增能够感知控制方的 Agent 准入约定。
 
 后续宿主 UI 可以分别暴露 **Steer** 和 **Follow up** 操作。宿主 steering 必须严格且仅限在线使用：只有当激活接受下一步骤时，它才能调用现有的 Agent steering 路径；其他情况必须拒绝，而且绝不能转为排队或冷恢复。是否通过面向模型的工具暴露 parent steering 仍需单独设计。
 
@@ -155,9 +155,9 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **等待期间 dispose Agent。** child 仍属于上一个进程内所有权图时重建 parent，需要持久化所有权与拆卸协议。只为尚未完成的所有权图保留 `AgentHandle`，可以在不让已结算历史驻留的前提下，保留 child-first 拆卸。
 
-**让提供方通过 Agent handle 创建、恢复 child 或投递消息。** 初始提供方只持有 `prepareContinuable()` 及其分离式创建规格这一项差异：child 是全新启动，还是带有 parent 前缀。管理器必须通过私有 activation-owner 作用域自行调用 `ctx.agents.create()`，使该作用域成为每个 handle 的结构化所有者。持久化的进程内会话已经包含初始前缀及通用重建描述符，消息投递则属于 Agent inbox。让提供方持有任何后续 handle、`SubagentRun` 或消息所有权，会保留一条没有已发布行为可承载的 seam。
+**让提供方通过 Agent handle 创建、恢复 child 或投递消息。** 初始提供方只持有 `prepareContinuable()` 及其分离式创建规格这一项差异：child 是全新启动，还是带有 parent 前缀。管理器必须通过私有 activation-owner 作用域自行调用 `ctx.agents.create()`，使该作用域成为每个 handle 的结构化所有者。持久化的进程内会话已经包含初始前缀及通用重建描述符，消息投递则属于 Agent inbox。让提供方持有任何后续 handle、`SubagentRun` 或消息所有权，会让提供方保留所有权，却没有已发布行为需要它。
 
-**将报告投递纳入基础生命周期。** 可重复的 child 到 parent 报告与该生命周期兼容，但静默投递还是唤醒投递、确认、持久性和重试行为都是独立的产品决策。后续的 report 包保持可选，并消费一条显式 child 设置 seam，因此可继续驻留不会默认授予返回通道。
+**将报告投递纳入基础生命周期。** 可重复的 child 到 parent 报告与该生命周期兼容，但静默投递还是唤醒投递、确认、持久性和重试行为都是独立的产品决策。后续的 report 包保持可选，并消费一个显式的 child 设置钩子，因此可继续驻留不会默认授予返回通道。
 
 **将 `SessionHeader.parentSession` 视为在线所有权。** 持久化谱系不能证明已记录的 parent 当前持有 child。在线 parent 的 `ownedChildren` 成员关系会记录进程内关系，而不改变持久化 parent id。
 
@@ -167,7 +167,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **现在就暴露 subagent steering。** parent steering 需要当前轮次控制方状态，以及不同于 follow-up 投递的单独准入策略。首个版本将每条继续执行消息都排队，可以避免引入该状态及其准入竞争。
 
-**在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，该 seam 只接受确切的在线 parent。
+**在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，继续执行 API 只接受确切的在线 parent。
 
 **返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 约定承载。
 
@@ -193,7 +193,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - 每个由继续执行管理器管理的 parent 激活只会在直接持有的所有 child 激活完成 `AgentHandle` dispose 后进行 dispose；顶层 Agent 不加入等待图。
 - Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。
 - 管理器拆卸会全局关闭准入；拥有选定顶层 Agent 的宿主则只关闭这些确切身份之下的准入，直到这些根离开注册表。两者都会按确切祖先关系跟踪已获准的物化过程，为每个选中的可见 Activation 安装一个记忆化 dispose 截止点，自顶向下传播取消，按 child-first 顺序释放 handle，即使个别分支失败也会等待所有选中分支，之后才 dispose 对应的顶层 Agent 或管理器作用域。
-- 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup seam 贡献一个显式的 child 作用域工具。
+- 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup 钩子贡献一个显式的 child 作用域工具。
 - 会话日志只会重建实际写入的消息，并保留每条消息的提供来源；已被 inbox 接受但未写入日志的消息没有重启保证。
 - 可继续 subagent 路径不创建或依赖 Task、`TaskId`、Task 完成通知、Task 取消或中间的带结果执行包装层。
 - 单元覆盖固定 `startContinuable()` 在 inbox 接受消息时的返回边界、每条接受前和生命周期发布失败路径的完整回滚、全局和限定到 parent 作用域的 drain 都会等待夹在 Agent 发布与 Activation 注册之间的物化过程完全停稳、同级森林隔离、中间 Agent 离开注册表后的确切祖先关系、不依赖提供方的冷恢复、冷恢复物化后的最终确切 parent 再授权、接受前后两个阶段的调用方 signal 与拆卸所有权，以及已接受但未写入日志的消息不会自动回放。
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index 1d67db187c..9ecdf26043 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.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 .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
-2026-07-28-skill-invocation-policy.md: 9d34bcb77ab7933ef9bf4e9b5227dade39903667
-2026-07-28-skill-invocation-policy.zh.md: 687bd582ce3f4c74e50d36640afc6b683e289c90
+2026-07-28-skill-invocation-policy.md: 67b50c7f92f7c93a13b495877bb8f87cfac44552
+2026-07-28-skill-invocation-policy.zh.md: 20d41ec1b2fdbfe5bbbe3c54a681dd4f807c703e
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
index 9d34bcb77a..67b50c7f92 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
@@ -12,7 +12,7 @@ The local parser also exposed an internal camel-case spelling as frontmatter. Su
 
 ## Decision
 
-`SkillSummary` carries a required typed `invocation: SkillInvocationPolicy` object whose `modelInvocable: boolean` and `userInvocable: boolean` fields are positive and symmetric. Omission exists only at explicit input seams: a runtime `SkillRegistration` without a policy and local frontmatter without either invocation key resolve to `{ modelInvocable: true, userInvocable: true }` before producing candidates or definitions. Future frontmatter keys remain outside the domain model until a consumer and enforcement contract exist; the local provider still parses frontmatter as an open `Record<string, unknown>`, then projects only recognized fields and their defaults into the normalized typed policy.
+`SkillSummary` carries a required typed `invocation: SkillInvocationPolicy` object whose `modelInvocable: boolean` and `userInvocable: boolean` fields are positive and symmetric. Omission exists only at explicit input boundaries: a runtime `SkillRegistration` without a policy and local frontmatter without either invocation key resolve to `{ modelInvocable: true, userInvocable: true }` before producing candidates or definitions. Future frontmatter keys remain outside the domain model until a consumer and enforcement contract exist; the local provider still parses frontmatter as an open `Record<string, unknown>`, then projects only recognized fields and their defaults into the normalized typed policy.
 
 `ctx.skills.list()` returns every winning summary and no longer chooses an invocation surface. `isModelInvocable(skill)` and `isUserInvocable(skill)` read the matching positive field directly. `ctx.skills.get()` remains policy-neutral because trusted internal callers may need any definition, while a public consumer must enforce its own predicate before advertising or loading a skill. The model tool and TUI check the invocation-neutral summary before calling `get()`, then recheck the loaded definition so a denied name never reaches definition loading and a policy change between discovery and load cannot expose its body.
 
@@ -33,7 +33,7 @@ This decision extends the [skill system](2026-07-05-skill-system.md) and superse
 
 ## Alternatives considered
 
-**Store all frontmatter in a generic `Map` and read string keys in `isModelInvocable` / `isUserInvocable`.** Rejected because misspelled keys, non-boolean values, and consumer-specific coercion would cross package seams without type checking. The parser boundary remains open; the domain model is deliberately typed and narrow.
+**Store all frontmatter in a generic `Map` and read string keys in `isModelInvocable` / `isUserInvocable`.** Rejected because misspelled keys, non-boolean values, and consumer-specific coercion would cross package boundaries without type checking. The parser boundary remains open; the domain model is deliberately typed and narrow.
 
 **Keep `ctx.skills.list()` model-filtered and add a second user list.** Rejected because discovery, duplicate resolution, caching, and ordering are surface-neutral work. One complete catalog plus explicit predicates prevents those mechanisms from drifting while making each consumer's policy visible at its boundary.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
index 687bd582ce..20d41ec1b2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
@@ -12,7 +12,7 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
 
 ## 决策
 
-`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
+`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入边界可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
 
 `ctx.skills.list()` 返回所有胜出的摘要，不再替任何调用接口选择策略。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 保持策略无关，因为可信内部调用方可能需要任意定义；对外消费方则必须在展示或加载 skill 之前执行自身对应的判定函数。模型工具和 TUI 会在调用 `get()` 前检查与调用策略无关的摘要，随后再次检查已加载的定义：被拒绝的名称绝不会进入定义加载流程，发现与加载之间发生策略变更也无法暴露该 skill 的正文。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 77df231e1c..65af28ee2e 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.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 .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
-2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
-2026-07-28-web-terminal-card.zh.md: 3a9025b3f2dee546253d923c121df0e04da73414
+2026-07-28-web-terminal-card.md: 0338fa1cdb4a19177bddd4181661173bf75492b0
+2026-07-28-web-terminal-card.zh.md: f9dc686cfbf817fe5a1c15b8d5a94e3f8ab2adee
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
index 026b32fed2..0338fa1cdb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
@@ -12,7 +12,7 @@ The Web client ignored it. `packages/client/ui-tool/src/client/tool/models/tool-
 
 ## Decision
 
-`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
+`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs in this UI bridge; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
 
 The component's contract:
 
@@ -49,7 +49,7 @@ One premise of that split has since weakened: [tool rows stopped being details-p
 
 `TerminalBlock` reads only the terminal view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view. A UI without the terminal capability still gets the bridge's fenced fallback; nothing about the tool's result shape changed.
 
-A `run_code` sub-dispatch does not reach a terminal card on the shipped wire: `session.ts` folds `tool/code-dispatch(-start)` with `callView: null`/`resultView: null`, and the host's `viewFor` presents only top-level `tool/call`/`tool/result`, so a nested bash call keeps the generic flattened form. Both arms are pinned — the resolution path with views injected, and the no-view shape the wire actually delivers — so the gap is recorded rather than implied. Carrying presenter views through the code-dispatch wire is that seam's own change.
+A `run_code` sub-dispatch does not reach a terminal card on the shipped wire: `session.ts` folds `tool/code-dispatch(-start)` with `callView: null`/`resultView: null`, and the host's `viewFor` presents only top-level `tool/call`/`tool/result`, so a nested bash call keeps the generic flattened form. Both arms are pinned — the resolution path with views injected, and the no-view shape the wire actually delivers — so the gap is recorded rather than implied. Carrying presenter views through the code-dispatch wire is that boundary's own change.
 
 Inline rendering is licensed for the terminal intent alone. A future intent that wants it needs its own bound and its own decision, argued against the reason recorded here rather than against the panel-only convention on its own.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 3a9025b3f2..f9dc686cfb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,7 +12,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这个 UI 桥接层；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
 该组件的约定：
 
@@ -49,7 +49,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `TerminalBlock` 只读取 terminal 视图携带的字段，因此它始终是渲染意图内容的纯函数——不查会话状态，与产出该视图的 presenter 一样可安全回放。不具备终端能力的 UI 仍从桥接层拿到围栏式回退；工具的结果形态未作任何改动。
 
-在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于那道接缝自身的改动。
+在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于该边界自身的改动。
 
 内嵌渲染的许可仅授予 terminal 意图。将来想要内嵌的意图需要有自己的边界与自己的决定，且需针对此处记录的理由来论证，而不是仅针对「只在面板」这条约定本身。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
index 9ae0827be2..e16de3af0f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.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 .agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
-2026-07-30-current-sandbox-policy-context.md: 093f9a8a0b58256bb4f2301cc62fa83629de4fbd
-2026-07-30-current-sandbox-policy-context.zh.md: ce7ff2d0cff0fc1068995fde174a4eb1df5343b7
+2026-07-30-current-sandbox-policy-context.md: ab231d19aec4852369c0f1a13fc50c69ab8128f1
+2026-07-30-current-sandbox-policy-context.zh.md: f269f70702373c4bd3d8172ccfaae921868146ca
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
index 093f9a8a0b..ab231d19ae 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
@@ -52,7 +52,7 @@ The cache-safe delivery rework then supplied a separate, non-statistical accepta
 
 **Keep sandbox mode absent because a standing mode label once caused preemptive refusal.** Rejected because a fresh Web request otherwise exposes mutation tools while withholding their standing policy, producing false capability claims before the first operation. The earlier live measurement remains a required counter-test: five of twelve turns ended without a tool call under `Bash commands run under the "read-only" file sandbox.` The committed tool-owned attempt guidance postdates that measurement, so the replacement is selected through a new positive-control experiment under the current tool contract rather than assuming the old and current conditions match.
 
-**A separate model-context package.** Rejected because the policy owner can resolve current session state directly and the existing assembly service can order it. A new package would add a shallow composition seam and documentation/gate surface around the same request boundary.
+**A separate model-context package.** Rejected because the policy owner can resolve current session state directly and the existing assembly service can order it. A new package would add a shallow composition layer and documentation/gate surface around the same request boundary.
 
 **Enumerate writable temporary roots.** Rejected because the backend is selected later at `confine()`: bwrap, Landlock, Seatbelt, and the in-process filesystem fence do not grant one common temporary-path set. Host-specific paths in a standing request would be both unstable and overclaimed.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
index ce7ff2d0cf..f269f70702 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
@@ -52,7 +52,7 @@ Status: implemented
 
 **继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具约定下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
 
-**独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合 seam 和额外的文档／门禁表面。
+**独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合层和额外的文档／门禁表面。
 
 **枚举可写临时根目录。** 不予采用，因为后端要到稍后的 `confine()` 才会选定：bwrap、Landlock、Seatbelt 和进程内文件系统围栏并不授予一套共同的临时路径。常驻请求中的主机特定路径既不稳定，也会作出过度承诺。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml
index 4571273d21..0e4f334485 100644
--- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.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 .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
-2026-07-30-plan-review-presentation-intent.md: aeab12aac308c24aa5c4b5953a60ae0f2cf6c5b5
-2026-07-30-plan-review-presentation-intent.zh.md: 1e52d7363ccc2fe5390a4f91aa7fe058229fe34a
+2026-07-30-plan-review-presentation-intent.md: f524f7ec67dff3e6d7a6bf59ac204f5c8aae13c6
+2026-07-30-plan-review-presentation-intent.zh.md: 69e0ae00fbc2a98ed45a6d2b711a17f7c947c7e6
diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
index aeab12aac3..f524f7ec67 100644
--- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
+++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
@@ -30,7 +30,7 @@ Dismissal became its own model-facing outcome. `ASK_CANCELLED` previously reache
 
 **Route the card on the question's `id` or `header` (`plan-review` / `Plan review`).** Rejected: string-sniffing a foreign package's copy across a wire boundary, which any wording change silently breaks. The intent is the declaration that makes the routing legible.
 
-**Order the options and let the card read position 0 as approve.** Rejected: a positional contract at a package seam, invisible in both the type and the wire frame, and unenforceable — a producer that reorders its options would invert a user's verdict. Naming the label costs one string.
+**Order the options and let the card read position 0 as approve.** Rejected: a positional contract at a package boundary, invisible in both the type and the wire frame, and unenforceable — a producer that reorders its options would invert a user's verdict. Naming the label costs one string.
 
 **Register a second composer-chain entry for the plan card.** Rejected: two entries would select over the same pending question carrier, making the surface depend on chain priority and on whether the plan package's client half is composed at all. One entry that picks its own shape cannot race itself, and the generic flow is the built-in fallback.
 
@@ -42,7 +42,7 @@ Dismissal became its own model-facing outcome. `ASK_CANCELLED` previously reache
 
 ## Consequences
 
-The question protocol now carries a presentation axis. Adding a second intent is a tag on the union, a producer that sets it, a schema member, and a panel — no new frame, service, or answer shape. The cost is that the question seam knows presentation exists at all, and that `ui-question` knows the word "plan"; both are the price of one entry owning every question surface.
+The question protocol now carries a presentation axis. Adding a second intent is a tag on the union, a producer that sets it, a schema member, and a panel — no new frame, service, or answer shape. The cost is that the question contract knows presentation exists at all, and that `ui-question` knows the word "plan"; both are the price of one entry owning every question surface.
 
 The plan gate reads as a plan gate: the plan is the card's content, the verdict is two labelled buttons, and taking the turn back is a third. The generic flow is untouched for every other question, and its committed goldens did not move.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md
index 1e52d7363c..69e0ae00fb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md
@@ -42,7 +42,7 @@ Status: implemented
 
 ## 结果
 
-问题协议从此带有一个呈现轴。新增第二个意图 = 联合上的一个标签、一个设置它的生产方、一个 schema 成员、一个面板 —— 不需要新的帧、服务或回答形状。代价是问题 seam 从此知道"呈现"这件事存在，且 `ui-question` 知道"plan"这个词；两者都是由单一条目拥有全部问题界面所要付的价钱。
+问题协议从此带有一个呈现轴。新增第二个意图 = 联合上的一个标签、一个设置它的生产方、一个 schema 成员、一个面板 —— 不需要新的帧、服务或回答形状。代价是问题约定从此知道"呈现"这件事存在，且 `ui-question` 知道"plan"这个词；两者都是由单一条目拥有全部问题界面所要付的价钱。
 
 计划关口读起来就像计划关口：计划是卡片的内容，裁决是两个带标签的按钮，把轮次拿回来是第三个。通用流程对其他每个问题都未受影响，其已提交的 golden 也没有变动。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index b844594397..9233d3f0c6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
-2026-07-30-web-result-card-frontend.zh.md: e40d103c295b4699cde3327252c8bca3719e7962
+2026-07-30-web-result-card-frontend.md: 0f3e46cda1aeeb0f526f839a9071f09058810b86
+2026-07-30-web-result-card-frontend.zh.md: d9802099f7d2300b4a4c88556103d0c014aaebee
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index c7e63220d8..0f3e46cda1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -32,13 +32,13 @@ A separate later PR unifies the whole-row collapse/expand interaction and will f
 
 **Reparse the model-facing render text instead of consuming the structured view.** Rejected for the same reason the contract note gives: `web_search`'s render collapses each source's fields into one free-text line labelled by title OR hostname, so reparsing cannot recover `{url, title?, snippet?, publishedAt?}`. The structured `resultView` is the only faithful source, which is why the backend PR added it.
 
-**Render plain anchors without the protocol allowlist.** Rejected: the URL is model-authored and unverified at this seam, so an unfiltered href would let a `javascript:` URL execute on click. The allowlist is the http(s) subset of MarkdownText's (which also permits `mailto:`), so untrusted retrieval links behave identically wherever they render.
+**Render plain anchors without the protocol allowlist.** Rejected: the URL is model-authored and unverified at this presentation boundary, so an unfiltered href would let a `javascript:` URL execute on click. The allowlist is the http(s) subset of MarkdownText's (which also permits `mailto:`), so untrusted retrieval links behave identically wherever they render.
 
 ## Testing
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` pins the component per-file to the 100% gate: both kinds; the title-or-hostname-or-raw-URL label fallback; the safe-link attributes on both kinds (an http(s) URL becoming an external anchor with `target`/`rel`, a `javascript:`/`file:`/unparseable URL rendering as a plain span with no href); the snippet and date shown or omitted on present/empty/absent; the truncation indicator gated on the flag; and the full source list rendering inside one scroll container with no expand control and `<li value>` numbering every source contiguously from 1.
 
-`packages/client/ui-tool/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so a coverage run measures none of it.
+`packages/client/ui-tool/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring boundary: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so a coverage run measures none of it.
 
 The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (`web_search`) and 67 (`web_fetch`), authored inline because the client-side fixture cannot import the web tool: turn 66's result view carries an answer and three sources exercising the citation list (a titled source with a snippet and date, a source with no title so its hostname labels the link, and a source with a date but no snippet) with the capped indicator on; turn 67's carries the fetched URL and a 200 status. Both keep a generic pending call view and add the `web` card only at result time, matching the contract's result-only web shape, and are named after the real tools so they hit the keyed `WebRow`. They are ordered before the todo turn (renumbered to 68) for the same reason the terminal turn is: the standing plan retires at the next `turn/start`, so a turn appended after it would empty the dock's plan strip. This drives the built-boot snapshot and a live `?fixture` server.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index e40d103c29..d9802099f7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -32,13 +32,13 @@ Status: implemented
 
 **重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
 
-**不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此接缝处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
+**不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此展示边界处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
 ## Testing
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` 把组件钉到 per-file 100% 门槛:两种 kind;标题-或-主机名-或-原始 URL 的标签回退;两种 kind 上的安全链接属性（http(s) URL 成为带 `target`/`rel` 的外链,`javascript:`/`file:`/无法解析的 URL 渲染为无 href 的纯 span）;snippet 与日期在存在/为空/缺失时的显示或省略;由标志位控制的截断提示;以及完整 source 列表渲染在单个滚动容器内、无展开控件、`<li value>` 从 1 起为每条 source 连续编号。
 
-`packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
+`packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线边界镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
 fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配约定的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index ee89a37a8b..2c8ee18abb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
-2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
-2026-07-31-code-mode-language-dispatch.zh.md: c8ab776dfb01265fa79b5f2b1001ca8109a96d7f
+2026-07-31-code-mode-language-dispatch.md: 3a6e248160f165d6b341a5c8719abffd69a43820
+2026-07-31-code-mode-language-dispatch.zh.md: 46ef842f4b4209787c831b657159a97604324a66
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
index 71e4fd5a30..3a6e248160 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
@@ -19,7 +19,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at
 
 Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
 
-`code-mode.ts` depends only on the runtime seam (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the seam's `language` field, which is already on master.
+`code-mode.ts` depends only on the runtime Service Definition (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the service's `language` field, which is already on master.
 
 ### The Python SDK renderer
 
@@ -27,7 +27,7 @@ Both tables are read with `Object.hasOwn` before use so a language named `toStri
 
 The standard that cap serves is grammatical validity, and the boundary is deliberate: a long `A | B | …` union is valid Python at any length and is left uncapped, even though CPython's `compile()` exhausts its C recursion walking the left-nested `BinOp` spine (measured on 3.9: 1,000 branches compile, 5,000 raise `RecursionError`). Nothing compiles this block — it is prompt text — so that limit costs nothing, whereas capping union length would retire the deep-chain tests that pin the walk's linear time and the class-name propagation cap. A future renderer that does need compilable output should flatten unions rather than truncate them.
 
-`renderType` validates the whole schema once (`assertSupportedJsonSchema`) and then trusts it, wrapping the walk in one `try/catch` that degrades to `Any` — the same trusted-after-validation stance the sibling `ts-types` renderer takes at this typed same-process seam ([Trust TypeScript at typed same-process seams](../../../../AGENTS.md)). It deliberately carries NO defenses against a schema whose accessors mutate between reads (post-validation cycles, TOCTOU on `const`/`enum`, self-referential functions): the input is a first-party registration (a `defineTool` literal or a raw registration) or a wire-derived plain JSON schema — the former is trusted per AGENTS.md, the latter is a `JSON.parse` product that physically cannot carry accessors, and `renderType` re-validates the whole tree on every call regardless — so such inputs are unreachable, and adding per-shape guards here would break symmetry with `ts-types` (which has none) for values the static interface forbids. `jsonSchemaToPy(schema: unknown)` accepts `unknown` and returns `Any` on a malformed schema — the Python counterpart of the TS flavor's `unknown` — but its contract is "degrade an unsupported schema", not "survive an adversarial mutating one".
+`renderType` validates the whole schema once (`assertSupportedJsonSchema`) and then trusts it, wrapping the walk in one `try/catch` that degrades to `Any` — the same trusted-after-validation stance the sibling `ts-types` renderer takes at this typed same-process boundary ([Trust TypeScript at typed same-process boundaries](../../../../AGENTS.md)). It deliberately carries NO defenses against a schema whose accessors mutate between reads (post-validation cycles, TOCTOU on `const`/`enum`, self-referential functions): the input is a first-party registration (a `defineTool` literal or a raw registration) or a wire-derived plain JSON schema — the former is trusted per AGENTS.md, the latter is a `JSON.parse` product that physically cannot carry accessors, and `renderType` re-validates the whole tree on every call regardless — so such inputs are unreachable, and adding per-shape guards here would break symmetry with `ts-types` (which has none) for values the static interface forbids. `jsonSchemaToPy(schema: unknown)` accepts `unknown` and returns `Any` on a malformed schema — the Python counterpart of the TS flavor's `unknown` — but its contract is "degrade an unsupported schema", not "survive an adversarial mutating one".
 
 ## Alternatives considered
 
@@ -37,7 +37,7 @@ The standard that cap serves is grammatical validity, and the boundary is delibe
 
 ## Consequences
 
-Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
+Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the Consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the Service Definition package must not import its Consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the Service Definition would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
 
 The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index c8ab776dfb..46ef842f4b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -19,7 +19,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
 
-`code-mode.ts` 只依赖运行时 seam（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要 seam 的 `language` 字段，而该字段已在 master 上。
+`code-mode.ts` 只依赖运行时 Service Definition（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要服务的 `language` 字段，而该字段已在 master 上。
 
 ### Python SDK 渲染器
 
@@ -27,7 +27,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 该上限服务的标准是**语法合法性**，这条边界是有意划定的：长的 `A | B | …` union 在任何长度下都是合法 Python，故不设上限——尽管 CPython 的 `compile()` 在沿左嵌套 `BinOp` 脊柱下降时会耗尽 C 递归（在 3.9 上实测：1,000 个分支可编译，5,000 个抛 `RecursionError`）。没有任何东西会编译这个块——它是提示词文本——所以那条限制在这里没有代价；而给 union 长度封顶会作废那几个钉住 walk 线性时间与类名传播上限的深链测试。将来若有渲染器确实需要可编译的输出，应当把 union 拍平，而不是截断。
 
-`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
+`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程边界上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process boundaries](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
 
 ## Alternatives considered
 
@@ -37,7 +37,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ## Consequences
 
-新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
+新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在 Consumer 的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：Service Definition 包不得 import 其 Consumer 的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 Service Definition 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
 
 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
index 5866d98309..6f61384fd8 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.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 .agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
-2026-07-31-web-telemetry-default-mount.md: c1525a44196991d5059969ea70af34501b199323
-2026-07-31-web-telemetry-default-mount.zh.md: ef5f7e4500a1776e049ac27e0e64756e78725a61
+2026-07-31-web-telemetry-default-mount.md: 3e20fa44666139778e85a8bd5b948ab2df14529b
+2026-07-31-web-telemetry-default-mount.zh.md: 97b153255a1e64aba0a686faf1817b69467fb663
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
index c1525a4419..3e20fa4466 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
@@ -26,7 +26,7 @@ The keyless integration test `apps/cli/tests/telemetry-web.e2e.ts` pins the depl
 
 ## Alternatives considered
 
-**No default mount; deployments add the row themselves (continuing the SDK stance).** Rejected for this stage: this repo's web/headless composition IS the internal deployment, and default-on reporting is that deployment's product requirement; the SDK stance survives in the seam packages (unmounted = nothing leaves).
+**No default mount; deployments add the row themselves (continuing the SDK stance).** Rejected for this stage: this repo's web/headless composition IS the internal deployment, and default-on reporting is that deployment's product requirement; the SDK stance survives in the Service Definition packages (unmounted = nothing leaves).
 
 **A config field instead of an env patch for the switch.** Infeasible: cordis rows have no config-level disable semantic, and `exporter.url` validation fails loud at plugin construction, so the switch must take effect before the Loader — AppCLIEntry's patch layer is the only seat.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
index ef5f7e4500..97b153255a 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**默认不挂载，部署方自行加行（SDK 立场的延续）。** 当前阶段不采用：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 seam 包保持（不挂 = 零外发）。
+**默认不挂载，部署方自行加行（SDK 立场的延续）。** 当前阶段不采用：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 Service Definition 包保持（不挂 = 零外发）。
 
 **开关做成 config 字段而非 env patch。** 不可行：cordis 行没有 config 层的 disable 语义，且 `exporter.url` 校验在插件构造期 fail-loud，开关必须在 Loader 之前生效——AppCLIEntry patch 层是唯一落点。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
index fa352e395b..87dd63043d 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.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 .agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
-2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: f3a92d6645c7f98a60fd3c4431cdfb84babfd51b
+2026-08-04-pointer-revealed-sidebar-scrollbars.md: 997945d55f7294f56a30917b050b5455de74acdf
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 128d7f12ba3e5be1c87774e79b3278383f59bf0b
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
index eb86f710e4..997945d55f 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
@@ -20,7 +20,7 @@ The pointer surface is the column, not the list. A pointer heading for the bar c
 
 `transparent` is what makes the reveal free of layout. `scrollbar-gutter: stable` on the list exists so rows never move ([the gutter note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)); rebinding a colour leaves that reservation in force, so the thumb appears in space the list was already holding for it.
 
-The indirection pair rather than a rule on the list, because that pair is ui-theme's documented rebinding seam: one declaration reaches both rendering paths (the WebKit pseudo-elements and Firefox's `scrollbar-color`), and custom properties inherit, which is what makes the column — rather than each scroll region in it — the thing that owns the state.
+The indirection pair rather than a rule on the list, because that pair is ui-theme's documented rebinding contract: one declaration reaches both rendering paths (the WebKit pseudo-elements and Firefox's `scrollbar-color`), and custom properties inherit, which is what makes the column — rather than each scroll region in it — the thing that owns the state.
 
 That widens the rebinding contract, so its gate states the new shape rather than accepting it by silence: `ui-theme/tests/scrollbar-styles.spec.ts` admits exactly two rebind targets, the l2 pair or `transparent`, and judges the *rule* rather than each declaration — a mixed rule (`thumb: transparent` beside an l2 hover) would repaint the bar the moment the pointer reached it while passing a per-declaration check. The elevation half compares whole values against the pair's canonical spelling, which is also what rejects a crossed pair and a token wrapped in a literal expression; an l1 rebind and a bare colour were already out.
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
index f3a92d6645..128d7f12ba 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 `transparent` 正是让这次显示不触发任何布局的原因。列表上的 `scrollbar-gutter: stable` 存在的意义就是让行永不移动（见[空槽 Agent Note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)）；重新绑定的只是颜色，那份预留始终有效，所以滑块出现在列表本就为它留出的空间里。
 
-选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定 seam：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
+选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定约定：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
 这拓宽了重新绑定约定，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 5cb1a7a155..98861322f3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 3362059974443d1f6b543358e1eaba99ef239e43
-2026-08-05-context-form-vocabulary.zh.md: 164f6e4a2cd4c76ff4418a0540a2030a0be1b845
+2026-08-05-context-form-vocabulary.md: 573be191cd228f8ca41641c4298b2987781b3435
+2026-08-05-context-form-vocabulary.zh.md: 2c7a2124f3528a6b660f6f26253bf76a53ab7b8e
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 3362059974..573be191cd 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -45,7 +45,7 @@ Everything else — including a form this UI version does not present, a form ab
 
 ## Why not a presenter registry
 
-The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure function each tool implements. Context deliberately has no equivalent, because the input differs in ownership: a tool's `args` are generated by the **model** against a model-facing schema, so a translation step is unavoidable; a context `source` is constructed by the **producing plugin** itself, under no external constraint, and can simply record the facts a presentation needs. Adding a registry would have bought a translation nobody needs, at the cost of a host computation point, a wire field per context message, and a browser bundle for every producing package (the client purity gate forbids host packages from contributing components).
+The tool presentation contract pairs its vocabulary with `presentCall(args)`, a host-side pure function each tool implements. Context deliberately has no equivalent, because the input differs in ownership: a tool's `args` are generated by the **model** against a model-facing schema, so a translation step is unavoidable; a context `source` is constructed by the **producing plugin** itself, under no external constraint, and can simply record the facts a presentation needs. Adding a registry would have bought a translation nobody needs, at the cost of a host computation point, a wire field per context message, and a browser bundle for every producing package (the client purity gate forbids host packages from contributing components).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 164f6e4a2c..2c7a2124f3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -45,7 +45,7 @@ Status: implemented
 
 ## 为什么不做 presenter 注册表
 
-工具 seam 把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
+工具呈现约定把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 439826ee6c..21dc393ff4 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.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 .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
-2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
-2026-08-05-pwsh-ui-bash-parity.zh.md: 40109a32ed146a31a2424feb53a7cf0f41d87106
+2026-08-05-pwsh-ui-bash-parity.md: 95e884e9b67f3fb3927cd5154883ab08b3e7b3bb
+2026-08-05-pwsh-ui-bash-parity.zh.md: 937e6cefd3ac74f8e2fe797cdc4480b2b78fc3cb
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
index 815b448b89..95e884e9b6 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
@@ -12,7 +12,7 @@ The [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-t
 
 `dsh-tool-pwsh`'s `presentResult` now mirrors `dsh-tool-bash`'s call-for-call: a completed foreground result is a `terminal` card whose output body is the marker-free rendered text and whose exit-status pill is the parsed `exitCode`/`signal`; background acknowledgements and `isError` results stay generic `console`-fenced cards; non-single-text-block results stay untouched (`undefined`).
 
-The parse is shared, not duplicated: `parseExitStatus`/`ParsedExitStatus` moved from `dsh-tool-bash`'s private render module into the `@deepseek-ai/dsh-bash` seam package (exported from its index), and `dsh-tool-bash`'s `render.ts` re-exports it so its source-plane consumers keep one import root. Both tools' renderers emit the same `[exit code: N]` / `[killed by signal: X]` markers, so one seam-owned inverse can never drift between the twins — the same "shared, not duplicated" shape the [bash-env extraction](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) used for the `DSH_*` registry.
+The parse is shared, not duplicated: `parseExitStatus`/`ParsedExitStatus` moved from `dsh-tool-bash`'s private render module into the `@deepseek-ai/dsh-bash` Service Definition package (exported from its index), and `dsh-tool-bash`'s `render.ts` re-exports it so its source-plane consumers keep one import root. Both tools' renderers emit the same `[exit code: N]` / `[killed by signal: X]` markers, so one Service-Definition-owned inverse can never drift between the twins — the same "shared, not duplicated" shape the [bash-env extraction](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) used for the `DSH_*` registry.
 
 The Web UI needs no per-tool code for the card itself: the client's terminal-card bridge maps any `card: 'terminal'` result view (`terminal-card-model` in `dsh-client-ui-conversation`), so the pwsh presenter change flows through the same rendering path bash already has. The collapsed tool row does get one client classification entry: `classifyTool('pwsh')` now yields the shell-family row (`bash` variant, its own `Pwsh` title) instead of the generic `others` "Tool call" row. A keyless browser lane (`apps/web/tests/pwsh-terminal.e2e.ts`) seeds a session whose pwsh call/result is presented by the real tool on replay — the api-proxy recomputes views from logged args/result content — and pins the terminal card golden, including the exit pill and the run-state dot.
 
@@ -27,6 +27,6 @@ The Web UI needs no per-tool code for the card itself: the client's terminal-car
 ## Consequences
 
 - A Windows composition using `dsh-tool-pwsh` now shows its shell calls exactly as bash calls look in the Web UI: cwd-headed terminal card, raw output, exit-status pill, run-state dot, and the red failure treatment on non-zero exits.
-- `parseExitStatus` becomes public seam surface on `@deepseek-ai/dsh-bash`; `dsh-tool-bash/src/render.ts` keeps re-exporting it, so no bash-tool consumer changes.
+- `parseExitStatus` becomes public contract surface on `@deepseek-ai/dsh-bash`; `dsh-tool-bash/src/render.ts` keeps re-exporting it, so no bash-tool consumer changes.
 - The roadmap's stage 2 shrinks: the TUI is removed (EOL), and the terminal-card counterpart now ships on the Web surface. The Windows default composition (stage 1) remains the outstanding stage.
 - Verification: `dsh-bash` owns the parse edge cases under the per-file coverage gate; `tool-pwsh`'s presenter suite mirrors `tool-bash`'s (clean/non-zero/signal/timeout round-trip, marker-like output, background/error generics, multi-block fallback); the client row-model suite pins the `Pwsh` shell-family row; the web `pwsh-terminal` lane is the assembled keyless scenario.
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 40109a32ed..937e6cefd3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `dsh-tool-pwsh` 的 `presentResult` 现在逐调用镜像 `dsh-tool-bash`：完成的前台结果是 `terminal` 卡，输出正文为去 marker 的渲染文本，退出状态 pill 为解析出的 `exitCode`/`signal`；后台 ack 与 `isError` 结果保持通用 `console` 围栏卡片；非单一文本块结果保持不变（`undefined`）。
 
-解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` seam 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 seam 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的 "共享而非复制" 形态。
+解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` Service Definition 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 Service Definition 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的 "共享而非复制" 形态。
 
 Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 terminal 卡桥接（`dsh-client-ui-conversation` 的 `terminal-card-model`）映射任意 `card: 'terminal'` 结果视图，因此 pwsh presenter 变更直接流经 bash 已有的同一渲染路径。折叠的工具行有一处客户端分类条目：`classifyTool('pwsh')` 现在归入 shell 家族行（`bash` variant，自有 `Pwsh` 标题），而非通用的 `others` "Tool call" 行。一条 keyless 浏览器通道（`apps/web/tests/pwsh-terminal.e2e.ts`）播种一个会话，其 pwsh 调用/结果在回放时由真实工具呈现（api-proxy 从已记录的 args/result 内容重新计算视图），并钉住 terminal 卡 golden，包括退出 pill 与运行状态点。
 
@@ -27,6 +27,6 @@ Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 ter
 ## Consequences
 
 - 使用 `dsh-tool-pwsh` 的 Windows 组合现在在 Web UI 中显示的 shell 调用与 bash 调用完全一致：cwd 头的 terminal 卡、原始输出、退出状态 pill、运行状态点，以及非零退出时的红色失败处理。
-- `parseExitStatus` 成为 `@deepseek-ai/dsh-bash` 的公开 seam 表面；`dsh-tool-bash/src/render.ts` 继续再导出它，bash 工具消费方零改动。
+- `parseExitStatus` 成为 `@deepseek-ai/dsh-bash` 的公开约定表面；`dsh-tool-bash/src/render.ts` 继续再导出它，bash 工具消费方零改动。
 - 路线图阶段 2 收窄：TUI 已移除（EOL），terminal 卡对应物现已在 Web 表面交付。Windows 默认组合（阶段 1）仍是未完成的阶段。
 - 验证：`dsh-bash` 在逐文件覆盖率门禁下拥有解析边界用例；`tool-pwsh` 的 presenter 套件镜像 `tool-bash` 的（干净/非零/信号/超时往返、marker 状输出、后台/错误 generic、多块回退）；客户端行模型套件钉住 `Pwsh` shell 家族行；web `pwsh-terminal` 通道是组装后的 keyless 场景。
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
index 8153420c3d..1f486c1684 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.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 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
-2026-08-07-web-inline-file-mentions.md: 581efb5a9eb497e030d19118d52d003b37118108
-2026-08-07-web-inline-file-mentions.zh.md: 25c8ca6e106cd877a4d46a7b1338728e96771fc1
+2026-08-07-web-inline-file-mentions.md: cb51e6cfa5eebe0341b50c7638d51ac2d8641ba7
+2026-08-07-web-inline-file-mentions.zh.md: 1dfbf712fa6017ca0ee7238e0589b85d05902804
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
index 581efb5a9e..cb51e6cfa5 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
@@ -20,7 +20,7 @@ The produced-files row lists a turn's output, but the closing message usually al
 
 - **Path-shaped regex over all prose** — links `package.json` mentioned abstractly and examples that were never written; every false positive is a click that opens nothing or the wrong file. The vocabulary approach cannot produce a dead link.
 - **Linking suffix matches (`out/index.html` mentioned as `index.html` in a subdirectory listing)** — deferred; exact path and unique basename cover the observed closing-message shapes, and a wider matcher can loosen later without breaking the seam.
-- **Resolving in ui-primitives against a passed path list** — puts matching policy in the generic renderer, where other consumers would inherit it unasked. The resolver seam keeps policy with the owner.
+- **Resolving in ui-primitives against a passed path list** — puts matching policy in the generic renderer, where other consumers would inherit it unasked. The resolver contract keeps policy with the owner.
 - **Threading the vocabulary through the turn-tail chain** — the chain is a render dispatch below the message; mentions decorate markdown inside it, which only data reaching MarkdownText can do. The optional service is that data path, and its absence is the off state.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
index 25c8ca6e10..1dfbf712fa 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 - **对全部正文跑路径形状的正则**——会把随口提到的 `package.json` 和从未写过的示例都链接上；每个误报都是一次打开空无或错误文件的点击。词表方案不可能产生死链。
 - **链接后缀匹配（子目录列表里把 `out/index.html` 写作 `index.html`）**——暂缓；精确路径加唯一 basename 已覆盖观察到的收尾消息形态，之后放宽匹配器不会破坏这道 seam。
-- **在 ui-primitives 里对传入的路径列表做解析**——把匹配策略放进通用渲染器，其他消费方会被动继承。解析器 seam 让策略留在持有者手里。
+- **在 ui-primitives 里对传入的路径列表做解析**——把匹配策略放进通用渲染器，其他消费方会被动继承。解析器约定让策略留在持有者手里。
 - **经由 turn-tail chain 传递词表**——chain 是消息下方的渲染派发；提及要装饰的是消息内部的 markdown，只有抵达 MarkdownText 的数据才做得到。可选 service 就是那条数据通路，它的缺席即关闭态。
 
 ## 后果
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 51b05b277e..963e4b1cae 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
-2026-08-08-user-explicit-skill-invocation.md: d925938279923282170dc99934f4fa44d8ecf2b4
-2026-08-08-user-explicit-skill-invocation.zh.md: 2d6d7130a1e80e3e9dba2681815668b3510356ba
+2026-08-08-user-explicit-skill-invocation.md: 55001ec2b352bba6f37dd937f64ec8b10853bffb
+2026-08-08-user-explicit-skill-invocation.zh.md: 5e9eb90502a178c4171899247ebac9bec965c89f
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
index d925938279..55001ec2b3 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -21,7 +21,7 @@ Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reaso
 
 ## Alternatives considered
 
-- **`skill.invoke` RPC (host injects, client claims)** — implemented first, in two iterations: a single mixed message (user text folded into the body), then a gesture prompt plus injection delivered through inbox primitives. Rejected after real-session testing: the mixed message polluted the injection with user prose; the two-message form depended on wake-ordering subtleties (`followup` claims the whole next-turn queue synchronously inside the first waking call, stranding any later message in the next turn — reproduced live), and the dedicated RPC duplicated a path `session.prompt` already provides while leaving TUI/ACP to reimplement recognition. The pre-step seam removes the RPC, the claim machinery, and the ordering hazard outright.
+- **`skill.invoke` RPC (host injects, client claims)** — implemented first, in two iterations: a single mixed message (user text folded into the body), then a gesture prompt plus injection delivered through inbox primitives. Rejected after real-session testing: the mixed message polluted the injection with user prose; the two-message form depended on wake-ordering subtleties (`followup` claims the whole next-turn queue synchronously inside the first waking call, stranding any later message in the next turn — reproduced live), and the dedicated RPC duplicated a path `session.prompt` already provides while leaving TUI/ACP to reimplement recognition. The pre-step extension point removes the RPC, the claim machinery, and the ordering hazard outright.
 - **`agent.inject()` from the RPC handler** — the inject queue (`next-step`, wake-free) is claimed ahead of the next-turn prompt, putting the injection above the gesture in the log; and pairing it with a waking `followup` reintroduces the same ordering coupling. The pre-step listener injects inside the step assembly, where ordering is explicit.
 - **A host `/skill <name>` command** (command registry, plan-mode precedent) — two-token UX, no name completion, and user-only skills stay undiscoverable in the menu; the per-cwd skill catalog also fits the static command registry poorly. Rejected.
 - **Client-side expansion** (fetch body, splice into the prompt) — authorization becomes bypassable client courtesy, the log loses the invocation semantics, and Codex deleted its equivalent mechanism (custom prompts) in favor of core injection. Rejected.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index 2d6d7130a1..5e9eb90502 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP（Agent Client Protocol）不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
+- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP（Agent Client Protocol）不得不各自重新实现识别。pre-step 扩展点把 RPC、认领机制与顺序隐患一并干净移除。
 - **从 RPC 处理器调用 `agent.inject()`**——inject 队列（`next-step`，不唤醒）会在 next-turn 提示词之前被认领，使注入在日志中排到手势之上；而与会唤醒的 `followup` 搭配又会重新引入同样的顺序耦合。pre-step 监听器在步骤组装内部注入，那里的顺序是显式的。
 - **宿主 `/skill <name>` 命令**（命令注册表，plan 模式先例）——两 token 的 UX、没有名称补全、仅限用户的 skill 在菜单里仍不可发现；按 cwd 的 skill 目录也与静态命令注册表格格不入。否决。
 - **客户端展开**（拉取正文、拼进提示词）——授权沦为可被绕过的客户端善意，日志失去调用语义，而且 Codex 已删除其等价机制（custom prompts）转向核心注入。否决。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 3ae0cff501..20bd2a96db 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: fd2b8ef8c7a43d9835cfbc39fc296465d7f5aba5
-2026-06-20-core-data-structures-catalog.zh.md: 6aafdd70384c89ce39113227d11db93f53107442
+2026-06-20-core-data-structures-catalog.md: 2f2e1fe43e29c972577f6b31fcd2f8249229779f
+2026-06-20-core-data-structures-catalog.zh.md: e2653a8248f6be24699dc55196e64231280cb7f9
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index fd2b8ef8c7..2f2e1fe43e 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -14,20 +14,20 @@ So the work had two intertwined questions: **what belongs in such a catalog** (t
 
 A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
 
-### What counts as "core" — the spine-vs-seam line
+### What counts as "core" — the spine-vs-subsystem line
 
 > **Superseded as the page-scoping rule** by [package-anchored subsystem pages](2026-08-03-package-anchored-subsystem-pages.md): each page now anchors to the package group that declares its vocabulary. The `ts type-equiv` mechanism below remains current.
 
-The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own seam page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
+The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own subsystem page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
-The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a seam-page detail.*** Worked through:
+The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a subsystem-page detail.*** Worked through:
 
 - A data structure is **core** if it flows through the agent-loop spine — the loop holds, derives, streams, or logs it on every turn regardless of which plugins load (`Message`, `StreamChunk`, `SessionEvent`, the `Agent` handle) — **or** it is the single headline type a plugin author writes against a pipeline (`ToolDefinition`).
-- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a seam-page detail. That is the spine-vs-seam line made sharp.
+- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a subsystem-page detail. That is the spine-vs-subsystem line made sharp.
 - `ToolSchema` is core (it is a field of `GenerateOptions`, the model request that flows through every step) even though it is conceptually part of the tool pipeline — *flows through the spine* wins over *conceptual home* when they conflict.
-- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are seam pages.
+- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary belong on subsystem pages.
 
-`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sibling seam pages for the per-seam detail; the folder's [README](../../../../docs/subsystems/README.md) indexes every page. The original seam pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
+`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sibling subsystem pages for package-owned detail; the folder's [README](../../../../docs/subsystems/README.md) indexes every page. The original subsystem pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
 
 ### The `ts type-equiv` mechanism — literal AND drift-proof
 
@@ -44,20 +44,20 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 ## Alternatives considered
 
-- **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-seam structure won.
+- **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-subsystem structure won.
 - **A compiled `_Check` assignability assertion** instead of the source match — rejected because assignability does not preserve names or JSDoc: a renamed field with the same type or a changed contract comment would pass.
 - **Put each type block's source in a directive comment** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
 
 ## Verification lesson
 
-The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
+The spine-vs-subsystem rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
 
-`verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-seam and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
+`verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-subsystem and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
 
 ## Consequences
 
 - The vocabulary now has a single home that **cannot silently drift**: a field or public class-member change in source fails `verify-type-equiv` in `doc-sync` and CI until the paste is refreshed. Cordis service methods remain owned by the generated services catalog rather than being duplicated here.
-- The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
+- The spine-vs-subsystem line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the seam-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the subsystem-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 6aafdd7038..e2653a8248 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 子系统目录与 `ts type-equiv` 漂移门禁
+# Agent Note: 核心数据结构目录与 `ts type-equiv` 漂移门禁
 
 Status: implemented
 
@@ -14,20 +14,20 @@ Status: implemented
 
 新增的 `docs/subsystems/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
 
-### 何为「核心」——主干与 seam 的分界线
+### 何为「核心」——主干与子系统的分界线
 
 > **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
 
-范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入自己的 seam 页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入其自身的子系统页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
-确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是 seam 页面细节。*** 逐一验证如下：
+确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子系统页面细节。*** 逐一验证如下：
 
 - 一个数据结构是**核心**的，如果它流经 agent loop 主干——无论加载了哪些插件，循环在每个轮次都会持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄）——**或者**它是插件作者面对某条流水线时编写的唯一标志性类型（`ToolDefinition`）。
-- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是 seam 页面细节。这就是主干与 seam 分界线的精确表述。
+- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是子系统页面细节。这就是主干与子系统分界线的精确表述。
 - `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
-- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇属于 seam 页面。
+- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇归入子系统页面。
 
-`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级 seam 页面获取各 seam 的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的 seam 页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
+`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级子系统页面获取包所拥有的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的子系统页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
 
 ### `ts type-equiv` 机制——既逐字又防漂移
 
@@ -44,20 +44,20 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-- **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与 seam 结构胜出。
+- **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与子系统结构胜出。
 - **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或约定注释变化仍会通过。
 - **将每个类型块的源文件写进指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
 
 ## 验证教训
 
-主干与 seam 规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
+主干与子系统规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
 
-`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与 seam 的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
+`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与子系统的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
 
 ## 后果
 
 - 这些词汇现在有一个**无法悄然漂移**的唯一归属：源码中的字段或公共类成员发生变化后，`doc-sync` 和 CI 中的 `verify-type-equiv` 会持续失败，直至粘贴内容刷新。Cordis 服务方法仍由生成的服务目录负责，而不会在此重复。
-- 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
+- 主干与子系统分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
-- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：九个精简页面（权限预设、计划模式、运行时不变式、HTTP 载体、存储——同时拥有 `ctx.storage` 与 `ctx.storageDomain`——终端扩展、工作区、客户端模块、遥测）覆盖了原先没有页面的十个 `ctx` 服务，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
+- 自 2026-07-27 起，子系统页面层级覆盖每个承载服务的子系统：九个精简页面（权限预设、计划模式、运行时不变式、HTTP 载体、存储——同时拥有 `ctx.storage` 与 `ctx.storageDomain`——终端扩展、工作区、客户端模块、遥测）覆盖了原先没有页面的十个 `ctx` 服务，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
index d97c4dd0b7..5daaeb33b1 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.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 .agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
-2026-07-02-tool-schema-catalog.md: 673b51831512662c4e2cc3b79cd85b149c78f585
-2026-07-02-tool-schema-catalog.zh.md: 8e47d807a2490e362bb3db6d1d634c75c60997e3
+2026-07-02-tool-schema-catalog.md: 1339d6631cb6abd7abc3cf193ed805de612b8425
+2026-07-02-tool-schema-catalog.zh.md: d7275ee4b5fa7d351c1a0cf6240343d75d726630
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
index 673b518315..1339d6631c 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
@@ -10,7 +10,7 @@ The repository had no single reference for the names, descriptions, and JSON Sch
 
 ## Decision
 
-Generate the catalog by **booting each tool plugin and reading its registered schemas**, not by parsing source. `scripts/gen-tool-catalog.ts` mounts each shipped tool package on a fresh cordis `Context` (with `SystemPrompt` + `ToolRegistry` and the injected seams the plugin's `apply` reads), calls `ctx.tools.schemas()` — exactly the `ToolSchema[]` the model is sent — disposes the context, and renders one `## <package>` section per package with a ` ```json ` `parameters` block per tool. It mirrors the `gen-cordis-catalog` / `gen-module-graph` CLI shape: default `--write` regenerates, `--check` fails if the committed copy is stale, output is deterministic (manifest-ordered, tools sorted by name). `verify-tool-catalog` (the `--check`) runs inside `doc-sync`, so relevant documentation changes and CI exercise the same freshness check.
+Generate the catalog by **booting each tool plugin and reading its registered schemas**, not by parsing source. `scripts/gen-tool-catalog.ts` mounts each shipped tool package on a fresh cordis `Context` (with `SystemPrompt` + `ToolRegistry` and the injected services the plugin's `apply` reads), calls `ctx.tools.schemas()` — exactly the `ToolSchema[]` the model is sent — disposes the context, and renders one `## <package>` section per package with a ` ```json ` `parameters` block per tool. It mirrors the `gen-cordis-catalog` / `gen-module-graph` CLI shape: default `--write` regenerates, `--check` fails if the committed copy is stale, output is deterministic (manifest-ordered, tools sorted by name). `verify-tool-catalog` (the `--check`) runs inside `doc-sync`, so relevant documentation changes and CI exercise the same freshness check.
 
 ### Why boot, not parse (the crux)
 
@@ -29,7 +29,7 @@ Booting has a cost the AST pass did not: there is no source declaration set to e
 
 ### A hand-maintained boot manifest is the irreducible policy
 
-The filesystem discovers the tool-package inventory and the completeness guard rejects omissions. `TOOL_PACKAGES` still owns an explicit boot recipe for each package because required seam implementations and config are policy, not facts that can be inferred safely from layout or injection names.
+The filesystem discovers the tool-package inventory and the completeness guard rejects omissions. `TOOL_PACKAGES` still owns an explicit boot recipe for each package because required Service providers and config are policy, not facts that can be inferred safely from layout or injection names.
 
 ### Scope
 
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
index 8e47d807a2..d7275ee4b5 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-目录通过**启动每个工具插件并读取其已注册 schema** 来生成，而不是解析源码。`scripts/gen-tool-catalog.ts` 在全新的 Cordis `Context` 上挂载每个已发布工具包；该上下文还提供 `SystemPrompt`、`ToolRegistry` 以及插件 `apply` 所读取的注入 seam。生成器调用 `ctx.tools.schemas()`——也就是发送给模型的确切 `ToolSchema[]`——随后 dispose（资源释放）上下文，并为每个包渲染一个 `## <package>` 章节，每个工具附带一个 ` ```json ` `parameters` 块。它与 `gen-cordis-catalog` / `gen-module-graph` 的 CLI 形状一致：默认 `--write` 重新生成；提交副本陈旧时 `--check` 失败；输出具有确定性（按清单排序，工具按名称排序）。`verify-tool-catalog`（即 `--check`）在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一项新鲜度检查。
+目录通过**启动每个工具插件并读取其已注册 schema** 来生成，而不是解析源码。`scripts/gen-tool-catalog.ts` 在全新的 Cordis `Context` 上挂载每个已发布工具包；该上下文还提供 `SystemPrompt`、`ToolRegistry` 以及插件 `apply` 所读取的注入服务。生成器调用 `ctx.tools.schemas()`——也就是发送给模型的确切 `ToolSchema[]`——随后 dispose（资源释放）上下文，并为每个包渲染一个 `## <package>` 章节，每个工具附带一个 ` ```json ` `parameters` 块。它与 `gen-cordis-catalog` / `gen-module-graph` 的 CLI 形状一致：默认 `--write` 重新生成；提交副本陈旧时 `--check` 失败；输出具有确定性（按清单排序，工具按名称排序）。`verify-tool-catalog`（即 `--check`）在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一项新鲜度检查。
 
 ### 为何启动而非解析（核心要点）
 
@@ -29,7 +29,7 @@ Cordis 目录是纯 TypeScript AST 遍历，因为每个事件/服务名都是
 
 ### 手动维护的启动 manifest 是不可化约的策略
 
-文件系统负责发现工具包清单，完整性守卫负责拒绝遗漏。`TOOL_PACKAGES` 仍然为每个包持有一份显式的启动配方，因为所需的 seam 实现和配置属于策略，不是能从目录布局或注入名称安全推断的事实。
+文件系统负责发现工具包清单，完整性守卫负责拒绝遗漏。`TOOL_PACKAGES` 仍然为每个包持有一份显式的启动配方，因为所需的 Service provider 和配置属于策略，不是能从目录布局或注入名称安全推断的事实。
 
 ### 范围
 
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
index ddfa339fdd..4442f5c345 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.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 .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
-2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39
-2026-07-20-gui-testing-system.zh.md: a0e819fd5269da6aa3379309c76eea006975cef8
+2026-07-20-gui-testing-system.md: 20e2709d070439f33664d07c6424c864cd84e850
+2026-07-20-gui-testing-system.zh.md: ca59abd65a450f4afde1eed63a969bd09650ed9f
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
index 4a1600bbef..20e2709d07 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
@@ -14,7 +14,7 @@ The GUI stack spans multiple application shapes, and within one shape multiple r
 
 ## Decision
 
-Cut along the architecture's natural test seams into three tiers, bottom-up:
+Cut along the architecture's natural test hooks into three tiers, bottom-up:
 
 | Tier | Under test | Key technique | File location |
 |---|---|---|---|
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
index a0e819fd52..ca59abd65a 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -14,7 +14,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 ## Decision（三层结构）
 
-贴架构天然测试缝切三层，自底向上：
+沿架构天然的测试钩子切分为三层，自底向上：
 
 | 层 | 被测物 | 关键手段 | 文件落点 |
 |---|---|---|---|
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
index 19dd1f9ab3..b124dbfd9e 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.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 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
-2026-08-03-package-anchored-subsystem-pages.md: 5ba7937f0c142727d343a107a3ff87f5f337931e
-2026-08-03-package-anchored-subsystem-pages.zh.md: 9166843cbfbbd065eca06e8716098581433ba41d
+2026-08-03-package-anchored-subsystem-pages.md: f429f3d41c1f152e83faeb12c379d221627e767f
+2026-08-03-package-anchored-subsystem-pages.zh.md: 3a56fa39357591197606a28b49cf0eac8f58963e
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
index 5ba7937f0c..f429f3d41c 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
@@ -20,7 +20,7 @@ The [subsystems README](../../../../docs/subsystems/README.md) indexes every pag
 
 ## Alternatives considered
 
-**Keep the spine-vs-seam scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
+**Keep the spine-vs-subsystem scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
 
 **A flat single-document catalog.** Already rejected in the [original catalog note](2026-06-20-core-data-structures-catalog.md); the growth to forty-one pages confirmed that verdict.
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
index 9166843cbf..3a56fa3935 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**保留主干-vs-seam 界定规则。**它逐类型回答「这个类型是核心吗？」，这正是首页积累了四个包的类型、却缺失 `packages/core/agent` 一半公开 surface 的原因。按仓库布局可预测性胜出。
+**保留主干-vs-子系统界定规则。**它逐类型回答「这个类型是核心吗？」，这正是首页积累了四个包的类型、却缺失 `packages/core/agent` 一半公开 surface 的原因。按仓库布局可预测性胜出。
 
 **扁平的单文档目录。**在[原目录 note](2026-06-20-core-data-structures-catalog.md) 中已被否决；增长到四十一页证实了该结论。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index 77b76293e3..a07b952a01 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.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 .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
-2026-06-20-public-agent-stop-surface.md: e9c713c7ba8c784d3d66fe8f391e1b197f7394d2
-2026-06-20-public-agent-stop-surface.zh.md: c57bb32643344c237dd68479e3ab8f8a7404a594
+2026-06-20-public-agent-stop-surface.md: ecbd00864f9e11205e544049a2e1c641ac132213
+2026-06-20-public-agent-stop-surface.zh.md: e9b0a3b8735537f2323dfe246eb7002b23c14947
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
index e9c713c7ba..ecbd00864f 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
@@ -18,9 +18,9 @@ The extra surface area made the loop carry a public verb that was mostly a teard
 
 `cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use broad `cancel()` to abandon current and queued work or `keepInbox` to abort the active turn while retaining pending work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract. The [Web stop decision](../bug-fix/2026-07-31-web-stop-preserves-queue.md) is the production `keepInbox` consumer.
 
-`whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public seam (`packages/acp/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/acp/acp/src` itself has no `whenIdle()` call.
+`whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public contract (`packages/acp/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/acp/acp/src` itself has no `whenIdle()` call.
 
-Public `abort()` is absent, and the disposer remains async and waits for the loop to stop. Tests exercise cancellation through the public typed cause and explicit signal seams rather than reaching into the holder.
+Public `abort()` is absent, and the disposer remains async and waits for the loop to stop. Tests exercise cancellation through the public typed cause and explicit signal APIs rather than reaching into the holder.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index c57bb32643..e9b0a3b873 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -18,9 +18,9 @@ Status: implemented
 
 `cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 约定。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。
 
-`whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。
+`whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开约定等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。
 
-公共 `abort()` 已不存在，disposer 仍为异步并等待循环停止。测试通过公共类型化原因和显式 signal seam 验证取消，而不会伸入 holder 内部。
+公共 `abort()` 已不存在，disposer 仍为异步并等待循环停止。测试通过公共类型化原因和显式 signal API 验证取消，而不会伸入 holder 内部。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index 7aab9c96af..956cfcee91 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.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 .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
-2026-06-26-fsspec-style-fs-seam.md: b5c201fb192782f130d3609978d16f0fc6d4d55e
-2026-06-26-fsspec-style-fs-seam.zh.md: 2ed74af594296f2853f4d97474c4ee07ef83dbd5
+2026-06-26-fsspec-style-fs-seam.md: c11c129a55c2e9e37efc83b01a219cae8b937fbc
+2026-06-26-fsspec-style-fs-seam.zh.md: 0e73ee134563bf8208e63f37bf36415eb1bf562d
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
index b5c201fb19..c11c129a55 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
@@ -24,7 +24,7 @@ Split the stack into four layers:
 ```text
 tool          dsh-tool-fs       model-facing schemas + read windowing + text rendering; the EXECUTOR (reads/writes/edits via ctx.fs, dispatches the fs/* events)
 policy        dsh-fs-policy  observed-state + read-before-edit + write/edit freshness, contributed through the fs/* event gate (no service)
-provider seam dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
+provider contract dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
 
@@ -61,7 +61,7 @@ type FsWriteIntent =
 
 `writeText` is atomic temp-file + rename with an explicit write expectation. `createIfAbsent` creates a missing target and rejects an existing target with `FS_NOT_OBSERVED`; it is the path used when the owner has no prior read. `replaceIfVersion` replaces only when the target exists at the observed version; a missing target or version mismatch throws `FS_STALE_VERSION`.
 
-`editText` is a provider-level guarded text mutation. When guarded it first verifies the target still exists at `expected.version`, then reads the current text, applies literal replacement, and writes atomically. The stale check must happen before literal matching so an edit based on an old read reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` from matching against newer content. Keeping this primitive on the provider seam preserves backend-local locking and lets a future remote backend implement native compare-and-edit without forcing the policy layer to pull the whole file through it.
+`editText` is a provider-level guarded text mutation. When guarded it first verifies the target still exists at `expected.version`, then reads the current text, applies literal replacement, and writes atomically. The stale check must happen before literal matching so an edit based on an old read reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` from matching against newer content. Keeping this primitive on the provider contract preserves backend-local locking and lets a future remote backend implement native compare-and-edit without forcing the policy layer to pull the whole file through it.
 
 This is a *text-storage* seam, deliberately half a level above byte-level fsspec (`cat`/`open` hand back raw bytes). UTF-8 decoding, binary/NUL rejection, guarded full-file writes, and guarded literal text edits live in the provider so the policy layer never touches raw bytes, reimplements cross-chunk decoding, or separates stale checks from the mutation critical section. Model-facing concepts still stay out of the provider: no line windows, numbered lines, rendered footers, or observed-state store leak down.
 
@@ -105,7 +105,7 @@ This Agent Note reverses two decisions from [filesystem-capability-seam](../arch
 - Text reads no longer return backend-numbered line records or `full`/`partial` views; authorization is based on version freshness, so a windowed read can authorize edit when the file is unchanged.
 - Literal edit no longer sits behind the old `applyEdit` API that mixed backend mutation with seam-owned observation policy. It remains a provider primitive as `editText`, because version guard + literal match + atomic rewrite must stay inside the provider's mutation critical section.
 
-It keeps the interface/implementation/consumer discipline, consumer-never-imports-backend rule, backend-defined target/version/display metadata, atomic local writes, and the shared `FsError` taxonomy.
+It keeps the Service Definition / Service provider / Consumer discipline, consumer-never-imports-backend rule, backend-defined target/version/display metadata, atomic local writes, and the shared `FsError` taxonomy.
 
 ## Verification
 
@@ -123,8 +123,8 @@ The seam was later extended with direct directory listing by [Add direct directo
 
 ## Consequences
 
-- Adds a fourth fs package and a new plugin layer. This is intentional: it is the previously deferred policy layer, not a second abstract backend seam.
+- Adds a fourth fs package and a new plugin layer. This is intentional: it is the previously deferred policy layer, not a second abstract backend contract.
 - Direct `ctx.fs` use bypasses the policy: a direct `ctx.fs.readText` emits no `fs/observed`, so under the default policy a later `edit` rejects with `FS_NOT_OBSERVED` until the file is read through the `read` tool. The failure is explicit and documented.
 - Large-file line windowing moves from the backend to the `read` tool in `dsh-tool-fs`; text decoding and binary rejection stay in `ctx.fs.streamText`, so this is relocation of windowing only, not a second text-IO implementation.
-- Keeping `editText` in the provider seam means every backend must implement the literal replacement contract. This is intentional: the operation is not pure storage, but stale guard + literal match + atomic rewrite is the unit that must stay together for correct error attribution and concurrency behavior. The contract should stay narrow and text-only so future backends can implement it natively or by whole-file rewrite.
+- Keeping `editText` in the provider contract means every backend must implement the literal replacement contract. This is intentional: the operation is not pure storage, but stale guard + literal match + atomic rewrite is the unit that must stay together for correct error attribution and concurrency behavior. The contract should stay narrow and text-only so future backends can implement it natively or by whole-file rewrite.
 - Freshness permits full-file `write` after a windowed read. That is weaker than the old view check, but avoids making large files impossible to edit; prompt guidance still discourages blind full replaces.
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
index 2ed74af594..0e73ee1345 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 ```text
 tool          dsh-tool-fs       model-facing schemas + read windowing + text rendering; the EXECUTOR (reads/writes/edits via ctx.fs, dispatches the fs/* events)
 policy        dsh-fs-policy  observed-state + read-before-edit + write/edit freshness, contributed through the fs/* event gate (no service)
-provider seam dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
+provider contract dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
 
@@ -61,7 +61,7 @@ type FsWriteIntent =
 
 `writeText` 通过临时文件 + rename 实现原子写入，并带有显式的写入期望。`createIfAbsent` 创建不存在的目标，对已存在的目标以 `FS_NOT_OBSERVED` 拒绝；这是 owner 没有先前读取时使用的路径。`replaceIfVersion` 仅在目标以观测到的版本存在时替换；目标不存在或版本不匹配时抛出 `FS_STALE_VERSION`。
 
-`editText` 是提供方级别的受保护文本变更。启用守卫时，它首先验证目标仍以 `expected.version` 存在，然后读取当前文本、应用字面替换并原子写入。陈旧检查必须在字面匹配之前发生，这样基于旧读取的编辑会报告 `FS_STALE_VERSION`，而不是对更新内容进行匹配后报告 `FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`。将此原语保留在提供方 seam 上，保持了后端本地锁定的能力，也让未来的远程后端能够实现原生的 compare-and-edit，而无需策略层拉取整个文件。
+`editText` 是提供方级别的受保护文本变更。启用守卫时，它首先验证目标仍以 `expected.version` 存在，然后读取当前文本、应用字面替换并原子写入。陈旧检查必须在字面匹配之前发生，这样基于旧读取的编辑会报告 `FS_STALE_VERSION`，而不是对更新内容进行匹配后报告 `FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`。将此原语保留在提供方约定上，保持了后端本地锁定的能力，也让未来的远程后端能够实现原生的 compare-and-edit，而无需策略层拉取整个文件。
 
 这是一个*文本存储* seam，刻意比字节级 fsspec（`cat`/`open` 返回原始字节）高半个层次。UTF-8 解码、二进制/NUL 拒绝、受保护的全文件写入和受保护的字面文本编辑都在提供方内完成，因此策略层从不接触原始字节、不重新实现跨分片解码、也不将陈旧检查与变更临界区分离。面向模型的概念仍然不下沉到提供方：行窗口、带行号的行、渲染的页脚、观测状态存储都不会泄漏下去。
 
@@ -105,7 +105,7 @@ type FsWriteIntent =
 - 文本读取不再返回后端编号的行记录或 `full`/`partial` 视图；授权基于版本新鲜度，因此窗口化读取在文件未变时即可授权编辑。
 - 字面编辑不再位于旧的 `applyEdit` API 之后（该 API 混合了后端变更与 seam 拥有的观测策略）。它作为 `editText` 保留为提供方原语，因为版本守卫 + 字面匹配 + 原子重写必须留在提供方的变更临界区内。
 
-保留的内容：接口/实现/消费方纪律、消费方不导入后端规则、后端定义的 target/version/display 元数据、原子本地写入，以及共享的 `FsError` 分类体系。
+保留的内容：Service Definition / Service provider / Consumer 纪律、消费方不导入后端规则、后端定义的 target/version/display 元数据、原子本地写入，以及共享的 `FsError` 分类体系。
 
 ## 验证
 
@@ -123,8 +123,8 @@ type FsWriteIntent =
 
 ## 后果
 
-- 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端 seam。
+- 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端约定。
 - 直接使用 `ctx.fs` 会绕过策略：直接 `ctx.fs.readText` 不发出 `fs/observed`，因此在默认策略下，后续 `edit` 会以 `FS_NOT_OBSERVED` 拒绝，直到通过 `read` 工具读取该文件。这一失败是显式且有文档记录的。
 - 大文件行窗口化从后端移至 `dsh-tool-fs` 中的 `read` 工具；文本解码和二进制拒绝留在 `ctx.fs.streamText` 中，因此这只是窗口化逻辑的迁移，而非第二套文本 IO 实现。
-- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换约定。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该约定应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
+- 将 `editText` 保留在提供方约定上意味着每个后端都必须实现字面替换约定。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该约定应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
 - 新鲜度允许在窗口化读取后进行全文件 `write`。这比旧的视图检查更弱，但避免了大文件无法编辑的问题；提示词引导仍然不鼓励盲目的全文件替换。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
index 6a77e7a95a..80f7b1a144 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.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 .agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
-2026-07-04-tighten-hook-protocol-contract.md: a67d0e8447e36516006e57051581c03877c1ba12
-2026-07-04-tighten-hook-protocol-contract.zh.md: b57a8da8d9f0f921b69d0b63ad5c655eb47f5967
+2026-07-04-tighten-hook-protocol-contract.md: 0c2397fa298ebd67d24f86d66d7d049b9da57ce9
+2026-07-04-tighten-hook-protocol-contract.zh.md: b0edd754eb5115936a03a892a2db0b67552f64f1
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
index a67d0e8447..0c2397fa29 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-04-tighten-hook-protocol-contract.zh.md)
 
 Four pieces of the `dsh-hook-protocol`/bridge contract missed the discipline the [subagent-observe-enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md) records — it dropped an `agentType` lifecycle field for lacking a consumer, and these failed the same test:
 
-1. **`HookDialect`'s `'native'` variant** (`packages/hooks/hook-protocol/src/types.ts`) had zero producers — the bridges stamp `'claude'` and `'codex'`; the only `'native'` constructor anywhere was the lib's own unit test. The field's own JSDoc defines `dialect` as "the bridge that ran it", and native is not a bridge: the [interception-seams Agent Note](../feature/2026-06-30-interception-seams.md) records that native hooks are not a package and that "a native plugin can already use the typed Decisions" without the durable hook log, and the flagship native-plugin worked example asserts exactly that (no `hook/*` events at all).
+1. **`HookDialect`'s `'native'` variant** (`packages/hooks/hook-protocol/src/types.ts`) had zero producers — the bridges stamp `'claude'` and `'codex'`; the only `'native'` constructor anywhere was the lib's own unit test. The field's own JSDoc defines `dialect` as "the bridge that ran it", and native is not a bridge: the [interception extension-points Agent Note](../feature/2026-06-30-interception-extension-points.md) records that native hooks are not a package and that "a native plugin can already use the typed Decisions" without the durable hook log, and the flagship native-plugin worked example asserts exactly that (no `hook/*` events at all).
 2. **`HookOutput.suppressOutput`** (same file) was parsed by the codec and discarded on every path: no bridge branch, no merge fold, no warn, no deferred-list row — uniquely among its parsed-but-unhonored siblings, each of which carries a stated deferral (`updatedInput` → a logged warn plus the [pre-tool-input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md); `systemMessage` → a logged warn plus a README deferred row; `continue`/`stopReason` → a `TODO(hook-continue-false)` anchor plus the `'stop'` decision record). Structurally there is nothing to suppress: hook stdout never enters any transcript (context flows only via `additionalContext`; the log records only `decision`/`stderrSummary`), so a hook author setting `suppressOutput: true` got silent nothing with no warn.
 3. **`defaultTimeoutMs` was double-defaulted in both bridge configs with a floating literal** — a schema `.default(600_000)` AND a `?? 600_000` fallback (`packages/hooks/hooks-claude/src/index.ts`, `packages/hooks/hooks-codex/src/index.ts`), two homes per bridge for one protocol-level constant, so the bridges could silently drift apart on the shared default. *The proposal's original remedy — delete the knob outright — was overtaken by the no-hardcoded-tunables audit, which kept the knob as the explicit bridge-owned config (and added `stderrSummaryMaxChars` beside it); what remained to fix was the literal's home.*
 4. **The `hook/result` semantics lived in the bridges, twice, not in the lib that owns the event.** `summarize()` — the stderr truncation rule — was byte-identical in `packages/hooks/hooks-claude/src/index.ts` and `packages/hooks/hooks-codex/src/index.ts`, and so was the decision-string rule `output.decision ?? (output.continue === false ? 'stop' : 'pass')`; yet `dsh-hook-protocol` declared `hook/result`, documented `stderrSummary` as "truncated" without owning the truncation, and documented the decision values without owning the mapping. If one bridge drifted (a different cap, a different fallback), the shared durable event's semantics would fork silently.
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
index b57a8da8d9..b0edd754eb 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `dsh-hook-protocol`/bridge 约定中有四部分没有遵守 [subagent observe/enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)记下的准则——后者因缺少消费方而删除 `agentType` 生命周期字段，以下各项没有通过同一检验：
 
-1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截 seam Agent Note](../feature/2026-06-30-interception-seams.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
+1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截扩展点 Agent Note](../feature/2026-06-30-interception-extension-points.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
 2. **`HookOutput.suppressOutput`**（同一文件）被 codec 解析后在所有路径上均被丢弃：没有 bridge 分支处理它、没有合并 fold、没有 warn、没有 deferred-list 行——在所有「被解析但未兑现」的同类字段中它是唯一没有明确延期声明的（`updatedInput` → 一条 warn 日志加 [pre-tool-input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)；`systemMessage` → 一条 warn 日志加 README deferred 行；`continue`/`stopReason` → 一个 `TODO(hook-continue-false)` 锚点加 `'stop'` decision 记录）。从结构上看根本无物可抑制：钩子 stdout 从不进入任何 transcript（文本记录）；上下文仅通过 `additionalContext` 流入，日志也只记录 `decision`/`stderrSummary`。因此，钩子作者设置 `suppressOutput: true` 得到的是无声的空操作，且无任何警告。
 3. **`defaultTimeoutMs` 在两个 bridge 配置中都以游离的字面量重复设置了默认值**——schema 的 `.default(600_000)` 加上一个 `?? 600_000` 回退（`packages/hooks/hooks-claude/src/index.ts`、`packages/hooks/hooks-codex/src/index.ts`），一个协议级常量在每个 bridge 中有两个归属地，两个 bridge 可能在共享默认值上悄然分歧。*提案最初的补救措施是彻底删除该旋钮，但被 no-hardcoded-tunables 审计所取代：审计保留了该旋钮作为 bridge 拥有的显式配置（并在旁边新增了 `stderrSummaryMaxChars`）；剩下要修的是字面量的归属地。*
 4. **`hook/result` 的语义存在于两个 bridge 中（各一份），而非拥有该事件的 lib。** `summarize()`——stderr 截断规则——在 `packages/hooks/hooks-claude/src/index.ts` 与 `packages/hooks/hooks-codex/src/index.ts` 中逐字节相同；decision 字符串规则 `output.decision ?? (output.continue === false ? 'stop' : 'pass')` 同样如此。然而 `dsh-hook-protocol` 声明了 `hook/result`、在文档中将 `stderrSummary` 描述为「已截断」却不拥有截断逻辑，记录了 decision 值却不拥有映射逻辑。如果某个 bridge 漂移（不同的上限、不同的回退），共享持久化事件的语义就会悄然分叉。
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
index 9c7359d8d6..5355169c7f 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.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 .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
-2026-07-22-plan-specific-collaboration-state.md: d139f3d861244c80acfb604d17172461bbf0cd57
-2026-07-22-plan-specific-collaboration-state.zh.md: 3d51b8fc31196efca49693050258c323ff3af843
+2026-07-22-plan-specific-collaboration-state.md: bab39ccc594c35b482c8a24ab805b6c4f2d2472b
+2026-07-22-plan-specific-collaboration-state.zh.md: 9dc88884b5a63baff4d682ff04b40f6970160c70
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
index d139f3d861..bab39ccc59 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
@@ -49,7 +49,7 @@ The tool renders the submitted plan as a generic card titled by its first headin
 
 **Let one presentation transport own plan state.** Rejected because TUI, Web, resume, fork, prompt assembly, and the exit tool need the same logged fact independently of any one transport. Presentation adapters own only their projections.
 
-**Split a capability-seam trio or put the state in the agent loop.** Rejected because plan mode has no swappable backend, while existing session, prompt, tool, command, and lifecycle seams already provide every required hook.
+**Split a capability-seam trio or put the state in the agent loop.** Rejected because plan mode has no swappable backend, while existing session, prompt, tool, command, and lifecycle extension points already provide every required hook.
 
 **Put flips in surface messages or store plans in files.** Rejected because the stance is a log-only fact and the tool argument already records the reviewable plan. Surface duplication spends model context, while a plan directory creates a second durable home.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
index 3d51b8fc31..9dc88884b5 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
@@ -49,7 +49,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 **让一种呈现传输拥有 plan 状态。** 不予采纳，因为 TUI、Web、恢复、fork、提示词组装和退出工具都需要独立于任何单一传输使用同一项已记录事实。呈现适配器只拥有各自的投影。
 
-**拆成能力 seam 三包，或把状态放进 agent loop。** 不予采纳，因为 plan mode 没有可替换后端，而现有的会话、提示词、工具、命令和生命周期 seam 已经提供所需的全部钩子。
+**拆成能力 seam 三包，或把状态放进 agent loop。** 不予采纳，因为 plan mode 没有可替换后端，而现有的会话、提示词、工具、命令和生命周期扩展点已经提供所需的全部钩子。
 
 **将状态切换写入表层消息，或把计划存入文件。** 不予采纳，因为协作状态是仅日志事实，工具参数已经记录了可评审的计划。重复写入表层会消耗模型上下文，而计划目录会形成第二个持久归属。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
index 736a9aee5f..d09614a7fa 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.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 .agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
-2026-07-23-acp-automation-only-protocol.md: 0fe2fc27a963d21e8a24c1682359ab3bc9e7af48
-2026-07-23-acp-automation-only-protocol.zh.md: d161f22672b1c1a1db131a58b4b8da531930ab97
+2026-07-23-acp-automation-only-protocol.md: 29da3025251f9826c5780493bb2725b114a40601
+2026-07-23-acp-automation-only-protocol.zh.md: bf326ce9f6fea8c55b842bc61e3d8521032ea4d1
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
index 0fe2fc27a9..29da302525 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
@@ -36,7 +36,7 @@ Protocol and lifecycle tests pin stop-reason and prompt codecs, version negotiat
 
 **Keep ACP as an editor UI until Web reaches parity.** Rejected because it leaves two interactive contracts to evolve and keeps editor conventions in the automation boundary.
 
-**Keep the earlier editor bridge behind disciplined seams.** Rejected even though that bridge correctly used interface services, tool-owned render intents, approval and user-interaction answerers, harness-owned execution, and a stdout-pure composition. Its terminal cards were capability-gated, display-only Zed `_meta` projections with a text fallback rather than ACP `terminal/create`, so shell execution never left the harness. The projection derived each display terminal id from the stable per-call id to prevent collisions and recovered exit code or signal from the rendered status markers because the pure result presenter received content blocks rather than a structured exit; marker round-trip tests and an explicit no-capability `console` fallback test pinned both contracts. Those boundaries were coherent but could not make editor cards, session navigation, configuration pickers, and human elicitation belong in an automation protocol.
+**Keep the earlier editor bridge behind disciplined service boundaries.** Rejected even though that bridge correctly used interface services, tool-owned render intents, approval and user-interaction answerers, harness-owned execution, and a stdout-pure composition. Its terminal cards were capability-gated, display-only Zed `_meta` projections with a text fallback rather than ACP `terminal/create`, so shell execution never left the harness. The projection derived each display terminal id from the stable per-call id to prevent collisions and recovered exit code or signal from the rendered status markers because the pure result presenter received content blocks rather than a structured exit; marker round-trip tests and an explicit no-capability `console` fallback test pinned both contracts. Those boundaries were coherent but could not make editor cards, session navigation, configuration pickers, and human elicitation belong in an automation protocol.
 
 **Replace ACP with a private subagent RPC.** Rejected because ACP already supplies a typed, interoperable process protocol and is used by the out-of-process subagent backend.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
index d161f22672..bf326ce9f6 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
@@ -36,7 +36,7 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 **在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互约定，并使编辑器约定继续存在于自动化边界中。
 
-**通过严格的 seam 保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项约定。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
+**通过严格的服务边界保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项约定。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
 
 **用私有 subagent RPC 替换 ACP。** 不予采用，因为 ACP 已经提供类型化、可互操作的进程协议，并由跨进程 subagent 后端使用。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
index 611d20bfe2..f749676ff4 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.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 .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
-2026-07-24-agent-loop-observable-state-machine.md: b1773fdf7fd3bcbea9c6b9a4a0ce37c715bce4ca
-2026-07-24-agent-loop-observable-state-machine.zh.md: ef44e9c058d165bfbbe226e9d0fca1e6f8072f53
+2026-07-24-agent-loop-observable-state-machine.md: 2c9cdd3ac090d2236e8922e06c94b5504570fead
+2026-07-24-agent-loop-observable-state-machine.zh.md: 0659fb3414de49d3ee12dc913fa62698bb2e6a79
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
index b1773fdf7f..2c9cdd3ac0 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
@@ -31,7 +31,7 @@ The event taxonomy removes the legacy prompt preparation/submission and serial s
 
 ## Alternatives considered
 
-**Keep the fine-grained event sequence.** This preserves a dedicated interception point for every internal phase, including request-only prefixes, assistant-message rewriting, post-step work, in-turn request recovery, and terminal stop overrides. It also makes the loop's private sequencing a permanent public contract and lets overlapping seams express conflicting decisions. The decision accepts the lost interception points in exchange for one boundary per supported extension responsibility.
+**Keep the fine-grained event sequence.** This preserves a dedicated interception point for every internal phase, including request-only prefixes, assistant-message rewriting, post-step work, in-turn request recovery, and terminal stop overrides. It also makes the loop's private sequencing a permanent public contract and lets overlapping extension points express conflicting decisions. The decision accepts the lost interception points in exchange for one boundary per supported extension responsibility.
 
 **Represent disposal as a third `AgentStatus`.** This gives retained handles a terminal status value but duplicates the registry lifecycle already expressed by `agent/disposed`. The decision keeps `AgentStatus` about live activity and makes registration lifetime a separate dimension.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
index ef44e9c058..0659fb3414 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
@@ -21,7 +21,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 - 待处理消息插入时会发出 `agent/inbox/inserted`，随后要么在原子纯删除领取后发出 `agent/inbox/claimed`，要么在普通删除后发出 `agent/inbox/discarded`。`MessageId` 关联确切消息；持久 splice 坐标保留 placement 与取消信息。inbox 事件描述插入、领取和丢弃，而不是轮次完成。
 - 已领取的轮次经过 pre-step 进入决策和零个或多个请求步骤。自动重试会关闭失败轮次并立即开启另一个轮次；`agent/settled` 只报告该重试链的终态轮次，且仍不同于 agent 整体转换到 `status === 'idle'`。
 
-循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering（中途引导），循环在所有监听器完成后根据这份数据作出决定。
+循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering，循环在所有监听器完成后根据这份数据作出决定。
 
 是否继续和终止执行由数据表达，不再由返回的控制枚举表达。工具调用和已接受的 steering 要求再执行一个步骤。携带 `concludesTurn` 的工具结果会在其所属步骤终止工具循环。循环不再暴露通用的 `ContinuationDecision` 或终止返回通道。
 
@@ -31,7 +31,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 ## 考虑过的替代方案
 
-**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开约定，并允许相互重叠的 seam 表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
+**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开约定，并允许相互重叠的扩展点表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
 
 **将 dispose 表示为第三种 `AgentStatus`。** 这样会让仍被持有的句柄得到一个终止状态值，但也会重复表达 `agent/disposed` 已经体现的注册表生命周期。当前决策让 `AgentStatus` 只表示 agent 存续期间的活动状态，并将注册生命周期作为独立维度。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
index c9735b903f..36c3b2190c 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.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 .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
-2026-07-26-merge-subagent-control-service.md: ae7214f7c8c28f8a4b7d754839acbc938270f125
-2026-07-26-merge-subagent-control-service.zh.md: 85a7f62ce789d80dc38ca52017554aa2c2921599
+2026-07-26-merge-subagent-control-service.md: 2757ba678863a355e0f9c4bb324035ba666796be
+2026-07-26-merge-subagent-control-service.zh.md: d9fd913fb229f63548d2aae65ed62c98a7bd4de0
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
index ae7214f7c8..2757ba6788 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
@@ -8,7 +8,7 @@ The public operation set is refined by [Intent-named subagent continuation opera
 
 ## Problem
 
-Continuable-child orchestration originally lived in a separate `ctx.subagentControl` service above the raw `ctx.subagents` provider seam. That split kept provider dispatch independent of Tasks and persistence, and gave model and human adapters one orchestration contract. In practice the two services described one capability family, every continuable caller needed both, and the provider-bound delegation tool had to infer policy from `provider.resume` and inspect whether the control service and `send_message` tool happened to be loaded. This made sibling plugin presence decide execution semantics and coupled starting continuable work to an optional follow-up surface.
+Continuable-child orchestration originally lived in a separate `ctx.subagentControl` service above the raw `ctx.subagents` provider contract. That split kept provider dispatch independent of Tasks and persistence, and gave model and human adapters one orchestration contract. In practice the two services described one capability family, every continuable caller needed both, and the provider-bound delegation tool had to infer policy from `provider.resume` and inspect whether the control service and `send_message` tool happened to be loaded. This made sibling plugin presence decide execution semantics and coupled starting continuable work to an optional follow-up surface.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
index 85a7f62ce7..d9fd913fb2 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
+可继续 child 的编排最初位于原始 `ctx.subagents` 提供方约定之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
index 9d3eb4677f..e25830686b 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.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 .agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
-2026-07-28-remove-synthetic-log-only-turns.md: 61c1aa4b1599fe020e0cd96c32daea01d419e95a
-2026-07-28-remove-synthetic-log-only-turns.zh.md: 65281d8342997165b465a744bb08dd2d815e014e
+2026-07-28-remove-synthetic-log-only-turns.md: cb4925fb7897d95898b3f620c5034b3082a72a0d
+2026-07-28-remove-synthetic-log-only-turns.zh.md: 1fb572449e0a78697a9c32a0e42bb5ae7499f97c
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
index 61c1aa4b15..cb4925fb78 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
@@ -10,7 +10,7 @@ The session store exposed `appendOutOfBand()` so a plugin could publish a late l
 
 That rule was introduced when persistence recovery treated the last `turn/end` as the only committed boundary. The persistence scanners now preserve every valid contiguous event, and crash repair reacts only to an actually open turn. Retaining synthetic turns for title updates therefore inflated turn counts, produced execution outcomes for work that never ran the model, and let a late metadata write consume the next turn number.
 
-The generic seam also duplicated domain policy. Its marker map said which plugin events were eligible, while the title capability already owned cancellation, liveness, and stale-result rules. Replacing it with another generic or title-specific append wrapper would preserve the same type indirection for two literal event types.
+The generic helper also duplicated domain policy. Its marker map said which plugin events were eligible, while the title capability already owned cancellation, liveness, and stale-result rules. Replacing it with another generic or title-specific append wrapper would preserve the same type indirection for two literal event types.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
index 65281d8342..1fb572449e 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 引入该规则时，持久化恢复曾将最后一个 `turn/end` 视为唯一的已提交边界。如今，持久化扫描器会保留每个合法且连续的事件，崩溃修复也只处理确实处于开放状态的轮次。因此，为标题更新保留合成轮次会夸大轮次计数、为从未运行模型的工作产生执行结果，还会让延迟到达的元数据写入占用下一个轮次编号。
 
-通用 seam 还重复了领域策略。它的标记映射说明哪些插件事件符合条件，而标题功能本就拥有取消、活跃性和陈旧结果处理规则。改用另一个通用或标题专属追加包装层，仍会为两个字面量事件类型保留同一层类型间接性。
+通用辅助函数还重复了领域策略。它的标记映射说明哪些插件事件符合条件，而标题功能本就拥有取消、活跃性和陈旧结果处理规则。改用另一个通用或标题专属追加包装层，仍会为两个字面量事件类型保留同一层类型间接性。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 77f0bb98ae..26e91f9351 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.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 .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
-2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856
-2026-07-31-one-route-to-add-a-workspace.zh.md: 9e0940e2a59fac907f023d6433f0056b99c41a60
+2026-07-31-one-route-to-add-a-workspace.md: 93f10493848a65aee9c9e67502abfd73fe1e6d1f
+2026-07-31-one-route-to-add-a-workspace.zh.md: 83d91abb9ada3c1431a1b4ef126ea42a8406d326
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
index 5d002265b5..93f1049384 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
@@ -27,7 +27,7 @@ The direct-open path carries the busy rule the menu entry states: while a pick i
 
 ## Wire and CLI residue
 
-The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client seam that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-seam, and CLI surface with its own reviewer and its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
+The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client contract that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-contract, and CLI surface with its own reviewer and its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 9e0940e2a5..83d91abb9a 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -27,7 +27,7 @@ Status: implemented
 
 ## Wire and CLI residue
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端约定同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端约定与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
index b688f011de..73c3fb6e55 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.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 .agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
-2026-08-04-remove-tui-package.md: 1057243c70f6f2775a5d0c5f5eddcb72cbad699e
-2026-08-04-remove-tui-package.zh.md: 17a75921f3e8f227772133243bc0ea5b8ba927a7
+2026-08-04-remove-tui-package.md: f048a04db02b582d038ebf549999c0fda50e30d3
+2026-08-04-remove-tui-package.zh.md: be18cbd33cd4a2bb592de4e7986b2786da272d0f
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
index 1057243c70..f048a04db0 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
@@ -14,7 +14,7 @@ The package also made the repository's supported application inventory misleadin
 
 The `packages/ui/tui` package is deleted without a compatibility package or alias. Its source, package tests, terminal snapshots, dependency declarations, patched `pi-tui` artifact, workspace references, generated service catalog entry, and documentation are removed together. Generic host and agent-loop capabilities remain unchanged.
 
-The SDK run-interface union now contains only `acp` and `embed`. `create-sdk` defaults to ACP, generated templates contain no terminal startup, resume, session-environment, or model-argument branch, and the builtin `ask-user` feature is removed because neither remaining generated interface supplies a `UserInteractionProvider`. Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation seams directly.
+The SDK run-interface union now contains only `acp` and `embed`. `create-sdk` defaults to ACP, generated templates contain no terminal startup, resume, session-environment, or model-argument branch, and the builtin `ask-user` feature is removed because neither remaining generated interface supplies a `UserInteractionProvider`. Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation services directly.
 
 This decision supersedes the reusable-package retention in [the explicit-config `dsh` entrypoint decision](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md) and the current applicability of the archived TUI implementation notes. Their historical records remain frozen, but they are not authority for the supported package or application inventory.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
index 17a75921f3..be18cbd33c 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent loop（智能体循环）能力保持不变。
 
-SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现 seam。
+SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现服务。
 
 本决策取代[显式配置 `dsh` 入口决策](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 36c58755cc..32c0bd83b9 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.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 .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
-2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d
-2026-06-22-fork-child-replay-seed-boundary.zh.md: 9e3f7e59394a5160f5ca5db1c9798b2e05f9d2dc
+2026-06-22-fork-child-replay-seed-boundary.md: bcbbd279771a2ebe7eee643958ecf09cbd7ca7be
+2026-06-22-fork-child-replay-seed-boundary.zh.md: ad086880d77a842be8c5dc7378018c92af95e698
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
index 27db3b768f..bcbbd27977 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
@@ -39,7 +39,7 @@ This closes the routing correctness gap, and two recorded fork scenarios exercis
 
 ## Alternatives considered
 
-- **Derive the boundary heuristically in `llm-replay`** (the seeded prefix is contiguous parent events ending at the last `turn/end` before the child's first `user/message`). Rejected: a brittle heuristic in the test harness that re-derives a fact the producer already knows. Persisting the boundary at its source (the fork backend) is the "explicit > implicit at package seams" rule applied across the persistence boundary — the reader of a child fixture never has to reconstruct where the inheritance ended.
+- **Derive the boundary heuristically in `llm-replay`** (the seeded prefix is contiguous parent events ending at the last `turn/end` before the child's first `user/message`). Rejected: a brittle heuristic in the test harness that re-derives a fact the producer already knows. Persisting the boundary at its source (the fork backend) is the "explicit > implicit at package boundaries" rule applied across the persistence boundary — the reader of a child fixture never has to reconstruct where the inheritance ended.
 - **Pin the format version instead of bumping** (the `SESSION_FORMAT_VERSION = 0` "unstable" stance the event log uses). Rejected for the SQLite *table* layout: `SCHEMA_VERSION` is the monotonic bump-and-reject knob (a small enumerable set of revisions worth telling apart), distinct from the event-vocabulary `version`. Adding a column is precisely the breaking table change it versions, so it bumps.
 
 ## Consequences
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index 9e3f7e5939..ad086880d7 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -39,7 +39,7 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla
 
 ## 曾考虑的替代方案
 
-- **在 `llm-replay` 中启发式推导边界**（播种前缀是连续的父事件，止于子会话第一条 `user/message` 之前的最后一个 `turn/end`）。否决：在测试 harness 中用脆弱的启发式重新推导一个生产者已经知道的事实。在源头（fork 后端）持久化边界，是「在包 seam 处显式优于隐式」这条规则跨越持久化边界的应用——子会话 fixture（测试前置数据）的读取者永远不需要重建继承在哪里结束。
+- **在 `llm-replay` 中启发式推导边界**（播种前缀是连续的父事件，止于子会话第一条 `user/message` 之前的最后一个 `turn/end`）。否决：在测试 harness 中用脆弱的启发式重新推导一个生产者已经知道的事实。在源头（fork 后端）持久化边界，是「在包边界处显式优于隐式」这条规则跨越持久化边界的应用——子会话 fixture（测试前置数据）的读取者永远不需要重建继承在哪里结束。
 - **固定格式版本而不递增**（事件日志使用的 `SESSION_FORMAT_VERSION = 0`「不稳定」姿态）。对 SQLite *表*布局否决：`SCHEMA_VERSION` 是单调递增并拒绝旧版的旋钮（一组小的、值得区分的修订），与事件词汇表的 `version` 不同。新增列正是它所版本化的那种破坏性表变更，因此需要递增。
 
 ## 后果
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
index 947e2da6eb..34edafb0d1 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.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 .agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
-2026-06-22-subagent-snapshot-replay.md: b8fefce5ff27b0cd3cfa2920b137e78cda0d696d
-2026-06-22-subagent-snapshot-replay.zh.md: e8bd8917a02e02f2ce89105eb64794876653574d
+2026-06-22-subagent-snapshot-replay.md: 45034c29f608eb5b58f44b80438b801b6224cb82
+2026-06-22-subagent-snapshot-replay.zh.md: 1b90c1bda854b7cd8cd9eae1e8c9f34328477f15
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
index b8fefce5ff..45034c29f6 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
@@ -53,6 +53,6 @@ Both replay keyless in the default gate.
 ## Consequences
 
 - The `TODO(subagent-snapshots)` deferral is resolved: nested-agent transcripts are now a first-class snapshot shape.
-- `GenerateOptions.sessionId` is a small, honest core-seam addition useful beyond replay (telemetry, request routing).
+- `GenerateOptions.sessionId` is a small, honest core API addition useful beyond replay (telemetry, request routing).
 - The `subagent` tool is bound to a single provider, so both children in `subagent-multi` are spawn (fresh). The keying routes by session, not by backend, so it is already correct for fork. The script *derivation* was not: a fork child's log begins with the seeded parent prefix (the parent's `assistant/chunk` events), so deriving its script from the whole log would replay the parent's responses as the child's. That correctness gap is closed by persisting a seed boundary — see [Persist the seed boundary so fork-child replay routes correctly](2026-06-22-fork-child-replay-seed-boundary.md) — and recorded fork + mixed spawn+fork scenarios now exercise both transports through one transcript (see [Record fork and mixed spawn+fork snapshot scenarios](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)).
 - Out-of-process (ACP) subagents are a different replay shape entirely (each child is its own PROCESS with its own replay), tracked as `TODO(acp-subagent-replay)` in the PR3 plan.
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
index e8bd8917a0..1b90c1bda8 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
@@ -53,6 +53,6 @@ Status: implemented
 ## 后果
 
 - `TODO(subagent-snapshots)` 延期项已解决：嵌套 agent 的 transcript 现在是快照层的一等形态。
-- `GenerateOptions.sessionId` 是一个小而诚实的 core-seam 新增，在回放之外同样有用（遥测、请求路由）。
+- `GenerateOptions.sessionId` 是一个小而诚实的 core API 新增，在回放之外同样有用（遥测、请求路由）。
 - `subagent` 工具绑定到单一提供方，因此 `subagent-multi` 中的两个子 agent 都是 spawn（全新创建）。键控按会话路由而非按后端路由，因此对 fork 同样正确。但脚本*派生*逻辑此前不正确：fork 子会话的日志以种子化的父前缀（父会话的 `assistant/chunk` 事件）开头，如果从完整日志派生脚本，就会把父 agent 的响应当作子 agent 的来回放。这一正确性缺口通过持久化种子边界来弥合——见[持久化 seed 边界以确保 fork 子会话回放正确路由](2026-06-22-fork-child-replay-seed-boundary.md)——录制的 fork 与混合 spawn+fork 场景现在通过一份 transcript 同时验证两种传输方式（见[记录 fork 与混合 spawn+fork 快照场景](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)）。
 - 进程外（ACP（Agent Client Protocol））subagent 是完全不同的回放形态（每个子 agent 是自己的进程、有自己的回放），作为 `TODO(acp-subagent-replay)` 记录在 PR3 计划中。
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
index 80395b6359..dcc666c622 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.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 .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
-2026-07-22-cross-platform-test-fixtures.md: 6217aabfdbe8f14f869004c8dafb7e19f4b7443a
-2026-07-22-cross-platform-test-fixtures.zh.md: bb6649a19766967e0c2f70272433c1fa2e93f72a
+2026-07-22-cross-platform-test-fixtures.md: 9114481543d6cae1661cbed70868eddb2faa09fc
+2026-07-22-cross-platform-test-fixtures.zh.md: 710ec5887f02b5c3c71d69f16ab726323501ac92
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
index 6217aabfdb..9114481543 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
@@ -30,4 +30,4 @@ Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on tha
 
 ## Consequences
 
-Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer seam. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer.
+Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer hook. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer.
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
index bb6649a197..710ec5887f 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器 seam 注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；命令同步执行成功时，可确保 dispose（资源释放）在有限时间内完成，并确保清理返回前即可观察到后代进程退出；若进程树终止失败，资源释放逻辑仍能观察到该失败。
+可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器钩子注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；命令同步执行成功时，可确保 dispose（资源释放）在有限时间内完成，并确保清理返回前即可观察到后代进程退出；若进程树终止失败，资源释放逻辑仍能观察到该失败。
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index b41a72fb3c..dcd5119f92 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.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 .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
-2026-07-24-web-gui-browser-e2e-lane.zh.md: d32837d0e320df0dd53ef49a50092503328d0d73
+2026-07-24-web-gui-browser-e2e-lane.md: aa289c9a70623904606e2d06b6492acb3a7d98a3
+2026-07-24-web-gui-browser-e2e-lane.zh.md: 9e26dcb53f0373ac967c627b95b895385784f925
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
index 095ad9055c..aa289c9a70 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
@@ -18,7 +18,7 @@ A plain shared-fixture module (the [testing-policy sanctioned shape](../../../..
 
 `launchWebScaffold()` boots the real web composition from the shipped `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`; every host-level `skill-local` root (`dshHome`, `agentsHome`, and `bundledSkillDir`) pinned beneath the temp workspace with watching disabled, because ambient skill catalogs are model-visible input; `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md); `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor); the webserver row pinned to port 0 with the built dist; and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure.
 
-Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the open seam on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the seam empty, so a stray stream fails loud with NO_ADAPTER.
+Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the empty adapter registry on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the registry empty, so a stray stream fails loud with NO_ADAPTER.
 
 `seedSession()` seeds cold sessions through the real persistence API — a throwaway `Context` mounting `SessionStore` + `SessionPersistenceJsonl` against the host's root, `create()` + `append()`, one `utimes` backdate for deterministic sidebar order (the `semantic-checkpoint.snapshot.ts` precedent) — never raw file writes, so the seeder knows nothing of bucket hashing, filename encoding, or compression, and the host's zstd default needs no boot knob. Seeds are validated at seed time (parseable, ending in `turn/end` — an open final turn would be mutated by resume's crash repair).
 
@@ -52,7 +52,7 @@ High-cardinality performance diagnostics use the separate opt-in `apps/web/tests
 
 ## Prior art
 
-Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot + AI SDK, lobe-chat, open-webui, OpenHands, Chainlit, continue, cline, langfuse, gradio/streamlit; Playwright HAR/route, MSW, Polly/nock, WireMock, aimock). The dominant proven architecture for apps that own their backend is an in-process fake/replay model behind the real backend seam with everything downstream real (LibreChat's `LIBRECHAT_TEST_RUN_HOOK` fake model; ai-chatbot's `MockLanguageModelV3` + `simulateReadableStream`; continue's scripted mock provider classes) — which is what `dsh-llm-replay` already is. Browser-level SSE interception cannot exercise incremental rendering (`route.fulfill` delivers the whole body at once; playwright#33564) and leaves the server SSE stack untested, so projects use it only for edge cases. Chunk pacing as a fixture parameter recurs everywhere (LibreChat 10ms default with slow profiles; ai-chatbot 500ms); real models in CI rot (open-webui's suite grew 120-second timeouts, was disabled, then deleted); sessions are seeded at the persistence layer with controlled timestamps (LibreChat inserts backdated Mongo documents; langfuse seeds its DB). No surveyed project replays a recorded agent-event log through the real backend for UI tests — the closest are provider-level recorded fixtures (aimock) and frontend-level socket history emission (OpenHands MSW) — so the session-log-as-fixture design goes one step beyond prior art along the axis this repo's model-visible ⟺ logged invariant makes natural.
+Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot + AI SDK, lobe-chat, open-webui, OpenHands, Chainlit, continue, cline, langfuse, gradio/streamlit; Playwright HAR/route, MSW, Polly/nock, WireMock, aimock). The dominant proven architecture for apps that own their backend is an in-process fake/replay model behind the real backend contract with everything downstream real (LibreChat's `LIBRECHAT_TEST_RUN_HOOK` fake model; ai-chatbot's `MockLanguageModelV3` + `simulateReadableStream`; continue's scripted mock provider classes) — which is what `dsh-llm-replay` already is. Browser-level SSE interception cannot exercise incremental rendering (`route.fulfill` delivers the whole body at once; playwright#33564) and leaves the server SSE stack untested, so projects use it only for edge cases. Chunk pacing as a fixture parameter recurs everywhere (LibreChat 10ms default with slow profiles; ai-chatbot 500ms); real models in CI rot (open-webui's suite grew 120-second timeouts, was disabled, then deleted); sessions are seeded at the persistence layer with controlled timestamps (LibreChat inserts backdated Mongo documents; langfuse seeds its DB). No surveyed project replays a recorded agent-event log through the real backend for UI tests — the closest are provider-level recorded fixtures (aimock) and frontend-level socket history emission (OpenHands MSW) — so the session-log-as-fixture design goes one step beyond prior art along the axis this repo's model-visible ⟺ logged invariant makes natural.
 
 ## Alternatives considered
 
@@ -60,7 +60,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot
 
 **Mock HTTP provider at `DEEPSEEK_BASE_URL`.** Rejected as the lane's mechanism (kept for the one existing workspace-probe smoke): fixtures become hand-authored OpenAI SSE byte scripts, a second fixture format that drifts from the session-log format the rest of the repo records and replays; the adapter's real HTTP path is with-key e2e's job.
 
-**Growing the `?fixture` client.** Rejected: tier separation — `FixtureApiClient` exists to test the client shell without a server; everything below the client API seam stays untested by construction.
+**Growing the `?fixture` client.** Rejected: tier separation — `FixtureApiClient` exists to test the client shell without a server; everything below the client API boundary stays untested by construction.
 
 **Placeholder `DEEPSEEK_API_KEY` + replay interception instead of disabling the adapter row.** Rejected despite zero composition change and two in-tree precedents: it satisfies `llm-deepseek`'s fail-loud key check with a lie and leaves a dead adapter mounted-but-intercepted; the disabled row (the ACP overlay's move) is honest keylessness and fails loud at the earliest resolvable point.
 
@@ -70,7 +70,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot
 
 **Spawning the `dsh web` bin with a `DSH_SNAPSHOT` replay branch.** Rejected: it needs a test-only replay branch plus environment plumbing in the shipped CLI. The in-process scaffold already loads the same `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml`; only argv, profile JSON, and `AppCLIEntry` glue remain outside it, and the keyless CLI smokes cover those paths.
 
-**Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless isomorphic seam (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.
+**Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless in-process path (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.
 
 **Real-model browser tests as the keyless lane.** Rejected: nondeterministic by construction; the surveyed cautionary case (open-webui) grew unbounded timeouts and was deleted. The with-key W5 smoke stays as the live-model complement.
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index d32837d0e3..9e26dcb53f 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -18,7 +18,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 `launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
 
-无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
+无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充空的适配器注册表——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让注册表保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
 
 `seedSession()` 通过真实持久化 API 播种冷会话——一次性 `Context` 挂载 `SessionStore` + `SessionPersistenceJsonl` 指向 host 的根目录，`create()` + `append()`，一次 `utimes` 回拨保证侧栏顺序确定（`semantic-checkpoint.snapshot.ts` 先例）——绝不裸写文件，因此播种器对桶哈希、文件名编码、压缩一无所知，host 的 zstd 默认值也无需任何启动开关。种子在播种时即校验（可解析、以 `turn/end` 结尾——未闭合的最终轮次会被恢复（resume）的崩溃修复改写）。
 
@@ -52,7 +52,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 ## 业界先例
 
-调研了 AI 聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端 seam 后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
+调研了 AI 聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端约定后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
 
 ## 曾考虑的替代方案
 
@@ -60,7 +60,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **`DEEPSEEK_BASE_URL` 处的 mock HTTP 提供方。** 作为本车道机制已否决（仅保留给既有的工作区探针冒烟）：fixture 会变成手写的 OpenAI SSE 字节脚本，一种与仓库其余部分录制回放的会话日志格式渐行渐远的第二 fixture 格式；适配器的真实 HTTP 路径归带密钥 e2e 管。
 
-**扩展 `?fixture` 客户端。** 已否决：分层纪律——`FixtureApiClient` 的存在意义就是脱离服务器测试客户端 shell；client API seam 以下按构造即失测。
+**扩展 `?fixture` 客户端。** 已否决：分层纪律——`FixtureApiClient` 的存在意义就是脱离服务器测试客户端 shell；client API 边界以下按构造即失测。
 
 **用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它用谎言满足 `llm-deepseek` 的快速失败密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）是诚实的无密钥，并在最早可解析点快速失败。
 
@@ -70,7 +70,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
 
-**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
+**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥进程内路径（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
 **以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index 318262eecb..29932b1d06 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.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 .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
-2026-06-16-typed-event-schemas.md: 97a7d0c3787eb5556696e25a6c8b1bb75642aba9
-2026-06-16-typed-event-schemas.zh.md: 6d665151a9c5879b3810ae93af8cc6bf5a21727c
+2026-06-16-typed-event-schemas.md: d919db18f347d0633155f92bfecc43b8bf846659
+2026-06-16-typed-event-schemas.zh.md: 369a70846265035d92bf51fcd516793b648e2f0f
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
index 97a7d0c378..d919db18f3 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
@@ -42,7 +42,7 @@ This is a repository-wide vocabulary redesign, not a persistence implementation
 Keep the compile-time pattern. Persistence stays opaque-JSON + serializability guard. Plugins extend via declaration merging; correctness of event *shape* is the producer's responsibility and is enforced by TypeScript at compile time. Package-owned invariant companions check selected cross-record relationships when enabled but do not provide general runtime shape schemas.
 
 - **Pros**: zero churn; plugin extension is a one-line `interface` augmentation with full type inference and no runtime registration ceremony; no new runtime dependency; the `defineTool` DSL and `assertNever` exhaustiveness keep working.
-- **Cons**: no runtime structural validation at the persistence boundary or at plugin seams; a malformed-but-JSON datum is caught late.
+- **Cons**: no runtime structural validation at the persistence boundary or at plugin boundaries; a malformed-but-JSON datum is caught late.
 
 ### B. Header/closed-shape validation only (schemastery), events stay opaque
 Tighten only the genuinely-closed shapes that already have hand-rolled type guards — e.g. the JSONL `HeaderLine` guard (`isHeaderLine`) — using **schemastery** (the repo's existing schema library, already used for every plugin `static Config`). Leave the merge-extensible event union as-is.
@@ -53,7 +53,7 @@ Tighten only the genuinely-closed shapes that already have hand-rolled type guar
 ### C. Runtime schema registry for the whole vocabulary (Zod or schemastery)
 Replace the merge-extensible maps with a runtime registry the producers contribute to and the persistence/consumer paths validate against.
 
-- **Pros**: real runtime validation at the durable boundary and at plugin seams; one source of truth; enables generic tooling (auto-generated docs, fuzzing, wire-format checks).
+- **Pros**: real runtime validation at the durable boundary and at plugin boundaries; one source of truth; enables generic tooling (auto-generated docs, fuzzing, wire-format checks).
 - **Cons**: the full blast radius above; **Zod is not currently a direct dependency** (only a transitive dep of `@earendil-works/pi-ai`) and the repo's chosen schema lib is **schemastery** — adopting Zod broadly is itself a dependency decision; declaration-merge ergonomics (one-line plugin extension, full inference) are replaced by runtime registration + manual type wiring; the `assertNever` exhaustiveness guarantee weakens (runtime variants aren't statically exhaustive).
 
 ## Proposal
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
index 6d665151a9..369a708462 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -42,7 +42,7 @@ harness 将其核心词汇——内容块、消息来源、结束原因、轮次
 保留编译期模式。持久化继续使用不透明 JSON + 可序列化性守卫。插件通过声明合并扩展；事件*形状*的正确性由生产者负责，并由 TypeScript 在编译期保证。启用包自有的不变式 companion 后，它们会检查选定的跨记录关系，但不提供通用运行时形状 schema。
 
 - **优点**：零变动；插件扩展只需一行 `interface` 增补，享有完整类型推断，无需运行时注册仪式；无新运行时依赖；`defineTool` DSL 与 `assertNever` 穷举继续工作。
-- **缺点**：持久化边界和插件 seam 处无运行时结构校验；格式错误但仍为合法 JSON 的数据被延迟捕获。
+- **缺点**：持久化边界和插件边界处无运行时结构校验；格式错误但仍为合法 JSON 的数据被延迟捕获。
 
 ### B. 仅对头部/封闭形状做校验（schemastery），事件仍为不透明
 仅对那些已有手写类型守卫的真正封闭形状加以收紧——例如 JSONL 的 `HeaderLine` 守卫（`isHeaderLine`）——使用 **schemastery**（仓库现有的 schema 库，已用于每个插件的 `static Config`）。merge-extensible 事件联合类型保持不变。
@@ -53,7 +53,7 @@ harness 将其核心词汇——内容块、消息来源、结束原因、轮次
 ### C. 为整个词汇建立运行时 schema 注册表（Zod 或 schemastery）
 用运行时注册表替换 merge-extensible map，生产者向其贡献 schema，持久化/消费路径据此校验。
 
-- **优点**：持久化边界和插件 seam 处获得真正的运行时校验；单一真源；可支撑通用工具（自动生成文档、模糊测试、协议格式（wire format）检查）。
+- **优点**：持久化边界和插件边界处获得真正的运行时校验；单一真源；可支撑通用工具（自动生成文档、模糊测试、协议格式（wire format）检查）。
 - **缺点**：上述全部影响范围；**Zod 目前不是直接依赖**（仅作为 `@earendil-works/pi-ai` 的传递依赖），仓库选定的 schema 库是 **schemastery**——广泛引入 Zod 本身就是一个依赖决策；声明合并的易用性（一行插件扩展、完整推断）被运行时注册 + 手动类型接线取代；`assertNever` 穷举保证弱化（运行时变体在静态层面不可穷举）。
 
 ## 提案
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
index 25b4c76ff7..c383ac1f48 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.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 .agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
-2026-07-19-required-cancellation-through-tool-capability-seams.md: c2cfb09f27222136965058695e9b6b706ac688a9
-2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 0544a17629c4fb130bed9ec6c7cae1a15d2211a8
+2026-07-19-required-cancellation-through-tool-capability-seams.md: 1909b8451b6c70bde7c67f0cc0c1c3f4db443f7f
+2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 7a9c78c71afe4d51f3d0f46f2cb59fc7cb5bf133
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
index c2cfb09f27..1909b8451b 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
@@ -18,7 +18,7 @@ Require an `AbortSignal` on every asynchronous same-process capability operation
 
 Each direct caller supplies a signal it owns or propagates from its own required operation context. Implementations may derive a child deadline or cancellation scope, but the derived signal remains linked to the upstream signal for the delegated lifetime. Capability implementations do not synthesize never-abort signals, use ambient async-local cancellation, or validate `AbortSignal` at runtime solely to repeat the typed same-process contract.
 
-The migration begins with an inventory from every first-party `ToolDefinition.execute()` through the capability calls it awaits. It then changes each coherent interface/implementation/consumer seam together, including tests and generated API documentation. Separate PRs may migrate filesystem, bash/task, web/provider, workflow/subagent, code-runtime, and similar families so each change remains reviewable, but no migrated interface keeps an optional compatibility overload under the repository's pre-release policy.
+The migration begins with an inventory from every first-party `ToolDefinition.execute()` through the capability calls it awaits. It then changes each coherent Service Definition / Service provider / Consumer seam together, including tests and generated API documentation. Separate PRs may migrate filesystem, bash/task, web/provider, workflow/subagent, code-runtime, and similar families so each change remains reviewable, but no migrated interface keeps an optional compatibility overload under the repository's pre-release policy.
 
 ### Scope boundary
 
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
index 0544a17629..7a9c78c71a 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 
 每个直接调用方提供自己持有的信号，或从自身必填的操作上下文继续传递信号。实现可以派生子截止时间或取消作用域，但派生信号在委托期间仍须与上游信号关联。能力实现不得生成永不中止信号、使用环境式异步本地取消，也不得仅为重复类型化同进程约定而在运行时校验 `AbortSignal`。
 
-迁移首先从每个第一方 `ToolDefinition.execute()` 出发，清点其等待的能力调用；随后按内聚的接口／实现／消费方 seam，将测试与生成的 API 文档一并修改。文件系统、Bash 与任务、Web 与提供方、工作流与 subagent、代码运行时等能力族可以通过独立 PR（Pull Request）迁移，以保持每项变更可审查；但根据仓库的预发布原则，已经迁移的接口不得保留可选兼容重载。
+迁移首先从每个第一方 `ToolDefinition.execute()` 出发，清点其等待的能力调用；随后按内聚的 Service Definition／Service provider／Consumer seam，将测试与生成的 API 文档一并修改。文件系统、Bash 与任务、Web 与提供方、工作流与 subagent、代码运行时等能力族可以通过独立 PR（Pull Request）迁移，以保持每项变更可审查；但根据仓库的预发布原则，已经迁移的接口不得保留可选兼容重载。
 
 ### 范围边界
 
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
index 1bf84824b2..0ba77577f4 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.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 .agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
-2026-07-25-client-settings-locale-theme.md: fdcdcff92fa324803d5f2343f3fc3d9dcca069c7
-2026-07-25-client-settings-locale-theme.zh.md: efcbbff3727a7a5ce14ba7273c7d0e826a3e5cbd
+2026-07-25-client-settings-locale-theme.md: 961a7d96705095486ed7e4b2044f8f0f4a3cd79c
+2026-07-25-client-settings-locale-theme.zh.md: 9c7be340f508f7bb12d1448625232258da412e10
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
index fdcdcff92f..961a7d9670 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
@@ -55,7 +55,7 @@ root
             └─ models (order 10)         ui-models 注册
 ```
 
-Section and item contributions use `ctx.slots.inject()` and do not depend on the client manifest's apply order; localized labels ride the label thunk from the [full-rollout note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md). The SlotMap types split homes: trigger/header/close/section have their canonical home in the ui-settings contract (the consumers, general and models, both depend on the shell — no cycle); `settings.general.item`'s canonical home is the locale package — it is the lowest common dependency of all item registrants (a settings row always carries copy), while the declarer general's contract is unreachable from locale/ui-theme (it would form a cycle); ui-theme consumes it through a re-export seam.
+Section and item contributions use `ctx.slots.inject()` and do not depend on the client manifest's apply order; localized labels ride the label thunk from the [full-rollout note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md). The SlotMap types split homes: trigger/header/close/section have their canonical home in the ui-settings contract (the consumers, general and models, both depend on the shell — no cycle); `settings.general.item`'s canonical home is the locale package — it is the lowest common dependency of all item registrants (a settings row always carries copy), while the declarer general's contract is unreachable from locale/ui-theme (it would form a cycle); ui-theme consumes it through a re-export outlet.
 
 ### Slot declarations are first-class injectable waits
 
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
index efcbbff372..9c7be340f5 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
@@ -55,11 +55,11 @@ root
             └─ models (order 10)         ui-models 注册
 ```
 
-section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest（元数据清单）的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings 约定（消费方 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的约定对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export seam 消费。
+section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest 的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings contract（消费者 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的 contract 对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export 出口消费。
 
 ### slot 声明是一等可注入等待对象
 
-`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明撤销与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会显式报错。这移除了陈旧 disposer 的在位判定机制和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明折叠与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会大声失败。这删除了陈旧 disposer 判在位机器和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ### 服务约定
 
@@ -127,4 +127,4 @@ Locale 内置中文和 English；`setLocale`/`setTheme` 是唯一写入口，未
 
 ## 风险
 
-slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。服务事件可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR（热模块替换）后残留。
+slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。service event 可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR 后残留。
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index ce7e7f5f4f..c5910fb083 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
-2026-07-27-session-projection-and-command-log.zh.md: ef4de5ea924e28c28896558206566639295c4c8e
+2026-07-27-session-projection-and-command-log.md: 6c2c8137453d04ba6b631fe7f80a788a639b096b
+2026-07-27-session-projection-and-command-log.zh.md: f3370ea2631e9c9904c6fc996c2c8aff698c3830
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 2fc463ab6e..6c2c813745 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -24,7 +24,7 @@ A state-carrying log event MUST carry the complete post-change state, never a ba
 
 ### Host projection registry (`dsh-session-projection`, new package)
 
-A light interface package: the merge-extensible type map, the registry service, zod at the boundary. Capability-seam three-way split: domain host plugins contribute, carriers consume, neither knows the other.
+A light Service Definition package: the merge-extensible type map, the registry service, zod at the boundary. Capability-seam roles: domain host plugins provide projection units, carriers consume them, and neither knows the other.
 
 What a domain registers is a **state-driven computation unit** — three pure functions plus declarations — never an opaque getter. The framework owns driving it (subscription, watermark, caching, and later checkpointing); the domain owns only the mathematics. Projections serve every business domain (session title, plan, goal, permission, todos); commands are merely one trigger path and hold no special position in this contract.
 
@@ -147,7 +147,7 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 
 **A live-only overlay hook (`live?(agent, base)`) for plan's pending intent** — rejected: it existed solely because the user's plan *selection* was not in the log. Routing the selection through the standard command channel puts `command/run` on the account, pending becomes a pure replay quantity, and the projection contract stays exactly three pure functions.
 
-**Naming the seam `registerFold`** — superseded by the unit contract: the registered object now genuinely is a fold, but `fold*` in this repo names pure `(events) => state` helper functions while this seam registers a keyed, schema'd, versioned unit. Projection remains the event-sourcing term for the read-model role, and both #587's note title and #497's comments already use it.
+**Naming the registration API `registerFold`** — superseded by the unit contract: the registered object now genuinely is a fold, but `fold*` in this repo names pure `(events) => state` helper functions while this registry accepts a keyed, schema'd, versioned unit. Projection remains the event-sourcing term for the read-model role, and both #587's note title and #497's comments already use it.
 
 **Client-side folding (per-domain projection cells with a `fromEvent`)** — rejected after being the second draft: once plan's unit folds two event types, a client cell must duplicate the host's transition logic in the browser — the same fold written twice, evolving separately. Pushing finished values (the title-frame precedent, generalized) keeps one computation site and reduces the client to a generic seq-guarded value store; domains write zero client code.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index ef4de5ea92..f3370ea263 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -24,7 +24,7 @@ Status: proposed
 
 ### host 侧投影注册表（`dsh-session-projection`，新包）
 
-一个轻量的接口包：merge-extensible 类型表、注册表服务、边界上的 zod 校验。能力 seam 三方拆分：领域 host 插件负责贡献，载体负责消费，两侧互不相识。
+一个轻量的 Service Definition 包：merge-extensible 类型表、注册表服务、边界上的 zod 校验。能力 seam 的角色如下：领域 host 插件提供投影单元，载体消费这些单元，两侧互不相识。
 
 领域注册的是一个**状态驱动计算单元（state-driven computation unit）**——三个纯函数外加若干声明——绝不是一个不透明的 getter。驱动它是框架的职责（订阅、水位线（watermark）、缓存，以及后续的检查点机制），领域只负责数学本身。投影服务于所有业务领域（会话标题、plan、goal、权限、todos）；命令只是其中一条触发路径，在本约定中没有任何特殊地位。
 
@@ -58,7 +58,7 @@ declare module 'cordis' {
 
 ### 已交付的消费方：subagent 身份单元
 
-注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久的 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位线缓存，零日志读），对 cold child 则对一次持久化读取所得的事件调用 `restore({}, events, 0)` 读取。注册表约定不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
+注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久化 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位缓存，零日志读），对 cold child 则用一次持久化整读的结果调用 `restore({}, events, 0)` 读取。注册表约定不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
 
 ### 协议层：历史尾页上的 projections 块
 
@@ -147,7 +147,7 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 **为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影约定保持恰好三个纯函数。
 
-**把 seam 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该 seam 注册的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
+**把注册 API 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该注册表接收的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
 
 **客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——曾是第二稿，后被否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
 
diff --git a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml
index 0b1aa5995a..cfe816fde7 100644
--- a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.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 .agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
-2026-06-30-pre-tool-input-rewrite.md: f35e6af465ce8cec5685911c43e12b8dd66f2e6a
-2026-06-30-pre-tool-input-rewrite.zh.md: 5793b38293e117e328350722ad1efb3126fd176c
+2026-06-30-pre-tool-input-rewrite.md: 63027079a996f2f7b9d2ef87afcd4e64a2691fb1
+2026-06-30-pre-tool-input-rewrite.zh.md: 8930a3a0b1ca136eb2c788e081f4093df8940162
diff --git a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
index f35e6af465..63027079a9 100644
--- a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-pre-tool-input-rewrite.zh.md)
 
 ## Problem
 
-The [interception-seams Agent Note](../../implemented/feature/2026-06-30-interception-seams.md) defines `tools/pre-execute` as an allow/deny/ask gate over an execution whose identity is already protected and whose arguments are deeply frozen. Claude Code's `PreToolUse` hook also offers `updatedInput`, so a faithful bridge needs an explicit rewrite mechanism. A rewrite cannot be a mutation escape hatch on the existing execution object: it must keep the durable history, audit record, presentation, and executed value consistent.
+The [interception extension-points Agent Note](../../implemented/feature/2026-06-30-interception-extension-points.md) defines `tools/pre-execute` as an allow/deny/ask gate over an execution whose identity is already protected and whose arguments are deeply frozen. Claude Code's `PreToolUse` hook also offers `updatedInput`, so a faithful bridge needs an explicit rewrite mechanism. A rewrite cannot be a mutation escape hatch on the existing execution object: it must keep the durable history, audit record, presentation, and executed value consistent.
 
 ## The problem: three readers of pre-execution arguments
 
@@ -49,5 +49,5 @@ Allowing a pre-execute listener to assign `exec.arguments` would provide only an
 
 - Does rewriting the `assistant/message` tool-call block corrupt any provider's expectation on replay, or is a separate correction safer?
 - Should the original arguments be preserved on the `tool/call` event (audit) and, if so, under what field?
-- Does the rewrite decision move before the log commit or become a dedicated earlier seam, and how do existing pre-tool allow/deny hooks avoid running twice?
+- Does the rewrite decision move before the log commit or become a dedicated earlier extension point, and how do existing pre-tool allow/deny hooks avoid running twice?
 - How does this interact with a future permission `ask` flow (a user approving a rewritten call)?
diff --git a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
index 5793b38293..8930a3a0b1 100644
--- a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-[拦截 seam Agent Note](../../implemented/feature/2026-06-30-interception-seams.md) 将 `tools/pre-execute` 定义为一道针对执行的允许/拒绝/询问门禁，此时执行的身份标识已受保护、参数已被深度冻结。Claude Code 的 `PreToolUse` 钩子还提供了 `updatedInput`，因此忠实的桥接需要一个显式的重写机制。重写不能是对现有执行对象的可变逃逸口：它必须保持持久化历史、审计记录、展示层与实际执行值之间的一致性。
+[拦截扩展点 Agent Note](../../implemented/feature/2026-06-30-interception-extension-points.md) 将 `tools/pre-execute` 定义为一道针对执行的允许/拒绝/询问门禁，此时执行的身份标识已受保护、参数已被深度冻结。Claude Code 的 `PreToolUse` 钩子还提供了 `updatedInput`，因此忠实的桥接需要一个显式的重写机制。重写不能是对现有执行对象的可变逃逸口：它必须保持持久化历史、审计记录、展示层与实际执行值之间的一致性。
 
 ## 问题本质：执行前参数的三个读取方
 
@@ -49,5 +49,5 @@ Status: proposed
 
 - 重写 `assistant/message` 中的工具调用块是否会破坏某些提供方在回放时的预期？还是单独的修正更安全？
 - 原始参数是否应保留在 `tool/call` 事件（审计）上？如果是，放在什么字段？
-- 重写决策是移到日志提交之前，还是成为一个专门的更早 seam？现有的 pre-tool 允许/拒绝钩子如何避免运行两次？
+- 重写决策是移到日志提交之前，还是成为一个专门的更早扩展点？现有的 pre-tool 允许/拒绝钩子如何避免运行两次？
 - 这与未来的权限 `ask` 流程（用户批准一个被重写的调用）如何交互？
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index f8d4a07f6c..aa6add0de4 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.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 .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: 6f7baedeaae0038b7f5106cd5fc4e23bdfbbd8dd
-2026-07-06-recallable-compaction.zh.md: cbf8b4a3843ca35647cc569255dfe9d26b45b988
+2026-07-06-recallable-compaction.md: 5fd26dd2d4086dd6f834f7bdb3194b0ad16db1eb
+2026-07-06-recallable-compaction.zh.md: 25ce6ca50d1755e3a90dbadb35d027c95262e5a4
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index 6f7baedeaa..5fd26dd2d4 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -83,7 +83,7 @@ Specified during review, deferred until observation calls for them:
 - **Pure stubs, no state checkpoint** — rejected: presumes the model knows what it is missing; fails on unknown unknowns.
 - **LLM aging/consolidation of frozen chunks** — rejected as a routine mechanism: summary-of-summary loss and frozen-prefix churn; the code-only rollup is its surviving form, deferred.
 - **Full prefix as chunk-summarizer input** — rejected: O(N²); the state document gives the same background at O(state).
-- **One summarize call emitting all outputs** — rejected: the summarize path has no structured-output enforcement; parsing one free-text response apart is the fragile seam the fail-closed design avoids.
+- **One summarize call emitting all outputs** — rejected: the summarize path has no structured-output enforcement; parsing one free-text response apart is the fragile boundary the fail-closed design avoids.
 - **Model-chosen chunk boundaries** — deferred: parse-and-validate cost against unproven value; chunk policy sits behind config.
 - **Model-authored pointers** — rejected: pointers must be exact; deterministic assembly is.
 - **FTS/vector index sidecar** — rejected in-session: the live log is in memory and bounded, a literal scan under budget suffices; an index earns its keep at cross-session scope.
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index cbf8b4a384..25ce6ca50d 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -83,7 +83,7 @@ Status: proposed
 - **只保留纯存根，不设状态检查点**：不予采纳，因为这假定模型知道自己缺少什么，在面对未知的未知时会失败。
 - **由 LLM 老化／整合冻结分片**：不作为常规机制，因为摘要的摘要会丢失信息，并使冻结前缀频繁变化；其保留下来的形式是由代码汇总，且延后实现。
 - **把完整前缀作为分片摘要器输入**：不予采纳，因为成本为 O(N²)；状态文档以 O(state) 提供相同背景。
-- **一次摘要调用输出全部结果**：不予采纳，因为摘要路径没有结构化输出约束；解析一份自由文本响应并将其拆开，正是保守失败设计要避免的脆弱 seam。
+- **一次摘要调用输出全部结果**：不予采纳，因为摘要路径没有结构化输出约束；解析一份自由文本响应并将其拆开，正是保守失败设计要避免的脆弱边界。
 - **由模型选择分片边界**：延后实现，因为相对于未经证明的收益，解析与校验成本过高；分片策略由配置控制。
 - **由模型编写指针**：不予采纳，因为指针必须精确，应由确定性代码组装。
 - **FTS／向量索引伴随存储**：在会话内不予采纳，因为实时日志已在内存中且大小有界，在预算内进行字面量扫描已经足够；只有跨会话范围才能证明索引的价值。
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
index af92c05200..fe92cb6fdd 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.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 .agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
-2026-07-08-interactive-side-sessions.md: 228380ca2d3d7b2efeb37e713574e1863ce17f38
-2026-07-08-interactive-side-sessions.zh.md: f4e3bfdddff16fe687f2637b3626e7e1382eba61
+2026-07-08-interactive-side-sessions.md: ff7f152b8a106c5b3856846e6980160d1ed59b43
+2026-07-08-interactive-side-sessions.zh.md: f81a3809231ac18ba6b134abd4a821f47af8b662
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
index 228380ca2d..ff7f152b8a 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
@@ -36,6 +36,6 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 
 ## Risks
 
-- Read-only behavior is advisory until a `tools/pre-execute` deny gate enforces it; [the interception seam](../../implemented/feature/2026-06-30-interception-seams.md) can add that gate without changing these mechanics.
+- Read-only behavior is advisory until a `tools/pre-execute` deny gate enforces it; [the interception point](../../implemented/feature/2026-06-30-interception-extension-points.md) can add that gate without changing these mechanics.
 - A compacted source forks its compacted view, so a bound surface should disclose that the child inherits summaries rather than replaced turns.
 - Repeated handbacks consume parent context. The per-merge length cap bounds each note; later consolidation belongs to compaction.
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
index f4e3bfdddf..f81a380923 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
@@ -36,6 +36,6 @@ Status: proposed
 
 ## 风险
 
-- 只读行为在 `tools/pre-execute` 拒绝门禁强制执行之前仅为建议性质；[拦截 seam](../../implemented/feature/2026-06-30-interception-seams.md) 可在不改变本机制的前提下添加该门禁。
+- 只读行为在 `tools/pre-execute` 拒绝门禁强制执行之前仅为建议性质；[拦截点](../../implemented/feature/2026-06-30-interception-extension-points.md) 可在不改变本机制的前提下添加该门禁。
 - 经过压缩（compaction）的源会话 fork 出的是其压缩视图，因此绑定的界面应当告知用户子会话继承的是摘要而非被替换的轮次。
 - 反复的 handback 会消耗父会话上下文。每次合并的长度上限约束了单条笔记的大小；后续的合并整理属于上下文压缩的职责。
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
index f5a16fae7e..a0a0dc998d 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.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 .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
-2026-07-17-sdk-follow-up-capabilities.md: 88d5d2f9bd1ce01c20177bcaee5bbe6b434bb978
-2026-07-17-sdk-follow-up-capabilities.zh.md: d54dc4d0635ef37d7196ff5cecbdd6ed093c98e3
+2026-07-17-sdk-follow-up-capabilities.md: 9a17f07139014f95666789e41cacb7af180ef5d8
+2026-07-17-sdk-follow-up-capabilities.zh.md: 2431c5c3d9e45605223d9bb1843e48a3c711759e
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
index 88d5d2f9bd..9a17f07139 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
@@ -12,7 +12,7 @@ These gaps are coupled. Create and config already share questions, feature confi
 
 ## Proposal
 
-The SDK extends the existing prompt and project-editing boundaries instead of creating parallel workflows. A non-interactive prompt port and structured feature plan drive create and config, `dsh-sdk create <source>` delegates dependency resolution to the project package manager before mounting the resolved package through `ProjectEditSession`, launcher-side telemetry wraps `create-sdk` and every `dsh-sdk` command, and injected prompt streams provide the primary interactive-test seam.
+The SDK extends the existing prompt and project-editing boundaries instead of creating parallel workflows. A non-interactive prompt port and structured feature plan drive create and config, `dsh-sdk create <source>` delegates dependency resolution to the project package manager before mounting the resolved package through `ProjectEditSession`, launcher-side telemetry wraps `create-sdk` and every `dsh-sdk` command, and injected prompt streams provide the primary interactive-test hook.
 
 | Capability | Product entrypoint | Owning mechanism | Required outcome |
 |---|---|---|---|
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
index d54dc4d063..2431c5c3d9 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
@@ -12,7 +12,7 @@ Status: proposed
 
 ## 提案
 
-SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；交互测试主要通过注入的提示词输入输出流完成。
+SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；注入的提示词输入输出流提供主要的交互测试钩子。
 
 | 功能 | 产品入口 | 所属机制 | 必须达到的结果 |
 |---|---|---|---|
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
index 76abf19851..91cfd64d91 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.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 .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
-2026-07-04-prune-dead-core-spine-surface.md: 7ee7ffc6e8c0f3672c98be6e23ef45a1abfc2b4e
-2026-07-04-prune-dead-core-spine-surface.zh.md: 69470658683f70ccc7ed71313654b769c3211cc9
+2026-07-04-prune-dead-core-spine-surface.md: a2ae3170884bd011676f057004549ff7c93b49d4
+2026-07-04-prune-dead-core-spine-surface.zh.md: 6bf796f1203683acdb7ea6e2389a7f2996fb8351
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
index 7ee7ffc6e8..a2ae317088 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
@@ -23,7 +23,7 @@ The production corpus is `packages/*/*/src`, example sources/config, and runtime
 | `PersistenceCoordinator.inits`, backend `inits` accessors, `seedCoversPrefix`, and `assertSerializable` | The accessors exist for white-box tests; `seedCoversPrefix` has no outside production importer; `assertSerializable` has no production caller and duplicates the coordinator append boundary's lossless snapshot. | Observe initialization through `session/flush`, make `seedCoversPrefix` source-private, and delete `assertSerializable`. Keep both backends, `SessionHeader`, and SQLite's version contract. |
 | `LlmError.status` and replay status | Adapters/replay populate it, but production branches on stable error code/message and never reads raw status. | Remove the unread field and replay plumbing while preserving error classification. |
 | `BlockAssembler.push()` return value | Both production callers ignore the returned completed block. | Return `void`; keep the deliberately public `blocks()`/`message()` contract. |
-| `compactRegion`'s separate `session` argument | The fixed caller passes the same object already present as `agent.session`; the model-visible mount API can also call the method, but accepting two identities permits a mounted plugin to provide an incoherent pair. | Keep the manual-region seam while deliberately narrowing it to `agent.session` as the one source of truth. |
+| `compactRegion`'s separate `session` argument | The fixed caller passes the same object already present as `agent.session`; the model-visible mount API can also call the method, but accepting two identities permits a mounted plugin to provide an incoherent pair. | Keep the manual-region API while deliberately narrowing it to `agent.session` as the one source of truth. |
 | `CompactionResult.startSeq`, `summarySeq`, `endSeq`, and `summary` | The production consumer reads only shadowed range/seq/token accounting; the durable log owns summary and event identity. | Remove the four result echoes while keeping both shared transcript renderers. |
 | `BasicCompactService` estimation/summarization visibility | No outside production caller invokes the five methods; the implemented Agent Note names only `estimateContentTokens()` and `summarize()` as subclass hooks. | Make those two `protected` and the three orchestration-only estimators private. |
 | `CodeLogEntry.source`/`level` and `RunCodeMeta.dispatches` | Every production consumer maps logs to text; no presenter/model path reads the other fields or the persisted dispatch count. | Make code-runtime logs strings (or text-only entries) and remove result-meta dispatch plumbing; keep the local counter that mints deterministic dispatch ids. |
@@ -43,7 +43,7 @@ The production corpus is `packages/*/*/src`, example sources/config, and runtime
 
 ## Proposal
 
-Remove or demote every row as one bounded coordinated public-surface cleanup. Update package READMEs, JSDoc, generated API/event catalogs, type-equivalence records, exports maps where needed, and tests so they exercise the owning public seam instead of preserving test-only entry points. Do not collapse any capability seam, LLM adapter, persistence backend, or lifecycle quiescence contract.
+Remove or demote every row as one bounded coordinated public-surface cleanup. Update package READMEs, JSDoc, generated API/event catalogs, type-equivalence records, exports maps where needed, and tests so they exercise the owning public contract instead of preserving test-only entry points. Do not collapse any capability seam, LLM adapter, persistence backend, or lifecycle quiescence contract.
 
 ## Alternatives considered
 
@@ -60,4 +60,4 @@ Remove or demote every row as one bounded coordinated public-surface cleanup. Up
 
 ## Risks
 
-Most removals are compile-visible but runtime-neutral. The compaction argument cleanup deliberately forbids a session/context mismatch while retaining the manual-region seam. External pre-release embedders and existing model-written mounts may import fewer helpers, pass fewer arguments, or receive narrower result shapes; this is an intentional product-surface contraction, not merely generated-catalog cleanup. The repository is unreleased, so carrying unsupported surface is the larger foundation cost.
+Most removals are compile-visible but runtime-neutral. The compaction argument cleanup deliberately forbids a session/context mismatch while retaining the manual-region API. External pre-release embedders and existing model-written mounts may import fewer helpers, pass fewer arguments, or receive narrower result shapes; this is an intentional product-surface contraction, not merely generated-catalog cleanup. The repository is unreleased, so carrying unsupported surface is the larger foundation cost.
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
index 6947065868..6bf796f120 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -23,7 +23,7 @@ Status: proposed
 | `PersistenceCoordinator.inits`、后端 `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留两个后端、`SessionHeader` 和 SQLite 的版本约定。 |
 | `LlmError.status` 与回放 status | 适配器/回放填充它，但生产分支基于稳定的错误码/消息判断，从不读取原始 status。 | 移除未读字段和回放管道，保留错误分类。 |
 | `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 约定。 |
-| `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region seam，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
+| `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region API，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
 | `CompactionResult.startSeq`、`summarySeq`、`endSeq` 与 `summary` | 生产消费方只读取 shadowed range/seq/token 统计；持久日志拥有 summary 和事件标识。 | 移除四个结果回显，保留两个共享的 transcript（文本记录）渲染器。 |
 | `BasicCompactService` 的估算/摘要方法可见性 | 没有包外生产调用者调用这五个方法；已实现的 Agent Note 只将 `estimateContentTokens()` 和 `summarize()` 命名为子类钩子。 | 将这两个方法改为 `protected`，其余三个编排专用的估算器改为 private。 |
 | `CodeLogEntry.source`/`level` 与 `RunCodeMeta.dispatches` | 每个生产消费方都将日志映射为文本；没有 presenter/模型路径读取其他字段或持久化的 dispatch 计数。 | 将 code-runtime 日志改为字符串（或纯文本条目），移除 result-meta 的 dispatch 管道；保留用于生成确定性 dispatch id 的本地计数器。 |
@@ -43,7 +43,7 @@ Status: proposed
 
 ## 提案
 
-以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳约定。
+以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开约定验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳约定。
 
 ## 曾考虑的替代方案
 
@@ -60,4 +60,4 @@ Status: proposed
 
 ## 风险
 
-大多数移除在编译时可见但对运行时无影响。上下文压缩参数清理有意禁止会话/上下文不匹配，同时保留手动 region seam。外部预发布嵌入者和现有模型编写的 mount 可能导入更少的辅助函数、传递更少的参数或接收更窄的结果形状；这是有意的产品接口收缩，而非仅仅是生成 catalog 的清理。仓库尚未发布，因此承载不受支持的接口才是更大的基础成本。
+大多数移除在编译时可见但对运行时无影响。上下文压缩参数清理有意禁止会话/上下文不匹配，同时保留手动 region API。外部预发布嵌入者和现有模型编写的 mount 可能导入更少的辅助函数、传递更少的参数或接收更窄的结果形状；这是有意的产品接口收缩，而非仅仅是生成 catalog 的清理。仓库尚未发布，因此承载不受支持的接口才是更大的基础成本。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 6c492ef3ee..08fbd08cee 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.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 .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
-2026-06-20-fold-session-persistence-interface.md: c0da160e766cf0bed532f0d11bd52e3a027dbe8b
-2026-06-20-fold-session-persistence-interface.zh.md: 8abdf77d2717cfed7209df72182187f75e32e241
+2026-06-20-fold-session-persistence-interface.md: 3079e9495cdbf4dd698fccc65d3c2fdada29cfc1
+2026-06-20-fold-session-persistence-interface.zh.md: e028089399e15d5d125d28788586fa1ef58980e7
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
index c0da160e76..3079e9495c 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
@@ -1,18 +1,18 @@
 # Agent Note: Fold the persistence interface into dsh-session
 
-Status: rejected — the separate persistence interface package is the intended modular capability seam for durable backends. Folding it into `dsh-session` would reduce package count at the cost of a cleaner backend boundary.
+Status: rejected — the separate persistence Service Definition package is the intended modular role split for the durable-persistence capability seam. Folding it into `dsh-session` would reduce package count at the cost of a cleaner backend boundary.
 
 English | [中文](2026-06-20-fold-session-persistence-interface.zh.md)
 
 ## Problem
 
-`dsh-session-persistence` is an interface package whose main concepts are already owned by `dsh-session`: `SessionHeader`, `SessionEvent`, `SessionId`, `session/event`, and `session/flush`. The package adds the abstract `SessionPersistence` service, the shared write coordinator, and contract helpers. Backend packages depend on it, and `agent-loop` has to optionally find a sibling service for resume.
+`dsh-session-persistence` is a Service Definition package whose main concepts are already owned by `dsh-session`: `SessionHeader`, `SessionEvent`, `SessionId`, `session/event`, and `session/flush`. The package adds the abstract `SessionPersistence` service, the shared write coordinator, and contract helpers. Provider packages depend on it, and `agent-loop` has to optionally find a sibling service for resume.
 
-The capability-seam split made sense when persistence was a new swappable backend design. After the mutable summary was removed, the interface package mostly wraps the session log's own storage concern. Keeping it separate may be more ceremony than clarity.
+The capability-seam split made sense when persistence was a new swappable backend design. After the mutable summary was removed, the Service Definition package mostly wraps the session log's own storage concern. Keeping it separate may be more ceremony than clarity.
 
 ## Proposal
 
-Move the abstract `SessionPersistence` service, the coordinator, and persistence contract helpers into `dsh-session`. Keep JSONL and SQLite as separate backend packages that register the session-owned service. This preserves backend swappability while deleting one support package and one cross-package seam.
+Move the abstract `SessionPersistence` service, the coordinator, and persistence contract helpers into `dsh-session`. Keep JSONL and SQLite as separate backend packages that register the session-owned service. This preserves backend swappability while deleting one support package and one cross-package boundary.
 
 The implementing PR should update the [capability seams](../../implemented/architecture/2026-06-13-capability-seams.md) guidance with the exception: persistence is not like bash or LLM because its vocabulary and lifecycle events are already the session package's core domain.
 
@@ -26,6 +26,6 @@ The implementing PR should update the [capability seams](../../implemented/archi
 
 ## What we give up
 
-`dsh-session` becomes heavier: it owns both the in-memory log and the persistence interface. That is the trade. If third-party persistence backends were already a public ecosystem, the separate interface package would be a cleaner SDK boundary; pre-release, the extra package looks like abstraction before there is an external consumer.
+`dsh-session` becomes heavier: it owns both the in-memory log and the persistence Service Definition. That is the trade. If third-party persistence backends were already a public ecosystem, the separate Service Definition package would be a cleaner SDK boundary; pre-release, the extra package looks like abstraction before there is an external Consumer.
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index 8abdf77d27..e028089399 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -1,18 +1,18 @@
 # Agent Note: 将持久化接口合并进 dsh-session
 
-Status: rejected — 独立的持久化接口包是为持久化后端设计的模块化能力 seam。将其折叠进 `dsh-session` 虽能减少包数量，却会牺牲更清晰的后端边界。
+Status: rejected — 独立的持久化 Service Definition 包是持久化能力 seam 预期的模块化角色拆分。将其折叠进 `dsh-session` 虽能减少包数量，却会牺牲更清晰的后端边界。
 
 [English](2026-06-20-fold-session-persistence-interface.md) | 中文
 
 ## 问题
 
-`dsh-session-persistence` 是一个接口包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和约定辅助工具。后端包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
+`dsh-session-persistence` 是一个 Service Definition 包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和约定辅助工具。提供方包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
 
-当持久化还是一个全新的可替换后端设计时，能力 seam 的拆分是合理的。但在可变摘要被移除之后，这个接口包基本上只是包装了会话日志自身的存储职责。继续保持独立可能带来的仪式感多于清晰度。
+当持久化还是一个全新的可替换后端设计时，能力 seam 的拆分是合理的。但在可变摘要被移除之后，这个 Service Definition 包基本上只是包装了会话日志自身的存储职责。继续保持独立可能带来的仪式感多于清晰度。
 
 ## 提案
 
-将抽象的 `SessionPersistence` 服务、协调器和持久化约定辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
+将抽象的 `SessionPersistence` 服务、协调器和持久化约定辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包边界。
 
 实施 PR（Pull Request）应更新[能力 seam](../../implemented/architecture/2026-06-13-capability-seams.md) 指南，补充此例外：持久化不同于 bash 或 LLM（大语言模型），因为它的词汇和生命周期事件本就属于会话包的核心领域。
 
@@ -26,6 +26,6 @@ Status: rejected — 独立的持久化接口包是为持久化后端设计的
 
 ## 放弃了什么
 
-`dsh-session` 变得更重：它同时拥有内存日志和持久化接口。这就是代价。如果第三方持久化后端已经形成公开生态，独立的接口包会是更清晰的 SDK 边界；但在预发布阶段尚无外部消费方时，这个额外的包更像是过早引入的抽象。
+`dsh-session` 变得更重：它同时拥有内存日志和持久化 Service Definition。这就是代价。如果第三方持久化后端已经形成公开生态，独立的 Service Definition 包会是更清晰的 SDK 边界；但在预发布阶段尚无外部 Consumer 时，这个额外的包更像是过早引入的抽象。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
index 820638a9f6..9ade4e5770 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.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 .agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
-2026-07-12-collapse-workflow-to-foreground-core.md: 629e2140523c3ae7caf533de99821206d05f1b8e
-2026-07-12-collapse-workflow-to-foreground-core.zh.md: 9683d5a15bc7d201eaff905c440bbdf88bbc9388
+2026-07-12-collapse-workflow-to-foreground-core.md: 5fc46584f83eb5307ff16f3353b56951b928aef3
+2026-07-12-collapse-workflow-to-foreground-core.zh.md: 0b4c73e5df973215b10166f3dc2bbd525cc8231b
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
index 629e214052..5fc46584f8 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
@@ -28,7 +28,7 @@ Amend the implemented dynamic-workflow Agent Note and update the seam/tool/worke
 
 ## Acceptance criteria
 
-- The workflow public seam contains only execution, cancellation, result, and disposal contracts with a production consumer.
+- The workflow public contract contains only execution, cancellation, result, and disposal contracts with a production consumer.
 - No workflow event, phase/log protocol message, run-id generator, progress-only metadata, host pairing ledger, or fatal-mode branch remains.
 - The run handle has no id/meta echoes, and cancellation has one holder-owned channel after synchronous `start()` returns.
 - Parallel/pipeline behavior, caps, cancellation quiescence, worker containment, structured output, and the model-facing workflow scenarios retain coverage.
@@ -36,4 +36,4 @@ Amend the implemented dynamic-workflow Agent Note and update the seam/tool/worke
 
 ## Risks
 
-This is a compile-visible contraction of the workflow DSL, event taxonomy, handle, and start request. Existing workflow calls that supply descriptive metadata, and scripts that use `phase`, `log`, or labels, must shrink; programmatic callers bridge their own abort source to the returned handle; and a future observer must add a better-correlated seam. The execution semantics that make workflows useful do not change.
+This is a compile-visible contraction of the workflow DSL, event taxonomy, handle, and start request. Existing workflow calls that supply descriptive metadata, and scripts that use `phase`, `log`, or labels, must shrink; programmatic callers bridge their own abort source to the returned handle; and a future observer must add a better-correlated event contract. The execution semantics that make workflows useful do not change.
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
index 9683d5a15b..0b4c73e5df 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
@@ -28,7 +28,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 ## 验收标准
 
-- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 约定。
+- 工作流公开约定仅包含有生产消费方的执行、取消、结果与 dispose 约定。
 - 不再保留任何工作流事件、phase/log 协议消息、run-id 生成器、仅供进度使用的元数据、host 配对账本或 fatal 模式分支。
 - run handle 不再有 id/meta 回显，取消在同步 `start()` 返回后只有一条持有者拥有的通道。
 - parallel/pipeline 行为、上限、取消后的完全停稳、worker 隔离、结构化输出与面向模型的工作流场景保持测试覆盖。
@@ -36,4 +36,4 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 ## 风险
 
-这是对工作流 DSL、事件分类体系、handle 与 start request 的编译可见收缩。现有提供描述性元数据的工作流调用，以及使用 `phase`、`log` 或 label 的脚本，都必须相应精简；程序化调用方需自行将 abort source 桥接到返回的 handle；未来的观测者必须添加一个关联性更好的 seam。使工作流有用的执行语义不变。
+这是对工作流 DSL、事件分类体系、handle 与 start request 的编译可见收缩。现有提供描述性元数据的工作流调用，以及使用 `phase`、`log` 或 label 的脚本，都必须相应精简；程序化调用方需自行将 abort source 桥接到返回的 handle；未来的观测者必须添加一个关联性更好的事件约定。使工作流有用的执行语义不变。
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
index 3da21fcadc..66c131db5f 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.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 .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
-2026-07-12-prune-unused-skill-registry-surface.md: 5a13effa04a6cd9954741a0a33ebc6fc3512fab8
-2026-07-12-prune-unused-skill-registry-surface.zh.md: f0cca25cb642eba851b63ce784d8fb9343d1f692
+2026-07-12-prune-unused-skill-registry-surface.md: 30247cad9c3b05f2a3afbffa1e1c140e9cd88e25
+2026-07-12-prune-unused-skill-registry-surface.zh.md: 02e47919c8d171ebd00aa03bf8612d5ca5f3e901
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
index 5a13effa04..30247cad9c 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-12-prune-unused-skill-registry-surface.zh.md)
 
 ## Problem
 
-The skill service's embedded-runtime subsystem has zero production caller of `ctx.skills.register()`. It adds a reserved `runtime` provider name, a runtime map/rank/source, duplicate policy, a second revision in cache keys, normalization, disposers, and tests alongside the provider seam every shipped skill already uses. `SkillSummary.whenToUse` and candidate/definition `path` are parsed and copied but never read by a production consumer: the model catalog renders name/description, resource loading uses `resourceBase`, and providers own their locator. The deliberately open `metadata` extension point stays.
+The skill service's embedded-runtime subsystem has zero production caller of `ctx.skills.register()`. It adds a reserved `runtime` provider name, a runtime map/rank/source, duplicate policy, a second revision in cache keys, normalization, disposers, and tests alongside the provider contract every shipped skill already uses. `SkillSummary.whenToUse` and candidate/definition `path` are parsed and copied but never read by a production consumer: the model catalog renders name/description, resource loading uses `resourceBase`, and providers own their locator. The deliberately open `metadata` extension point stays.
 
 ## Proposal
 
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
index f0cca25cb6..02e47919c8 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
@@ -6,7 +6,7 @@ Status: rejected — 直接在运行时注册 skill 是为第三方插件保留
 
 ## 问题
 
-skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）函数以及相应测试——而所有已交付的 skill 都只使用提供方 seam。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
+skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）函数以及相应测试——而所有已交付的 skill 都只使用提供方约定。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
 
 ## 提案
 
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
index 2e98c0fdc7..6e9bbece70 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.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 .agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
-2026-07-19-fold-compaction-package-split.md: eeb0b5871ceacbbefc8bfa9f782b4bdd6735f20a
-2026-07-19-fold-compaction-package-split.zh.md: 1b7e456536254acd98944c601da12d97453803ba
+2026-07-19-fold-compaction-package-split.md: 8bd83c389454092171633af806178ef8a9a74c72
+2026-07-19-fold-compaction-package-split.zh.md: ada725cbf726695836cc2dfce47fce82bea8d0f0
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
index eeb0b5871c..8bd83c3894 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
@@ -1,12 +1,12 @@
 # Agent Note: Fold the single compaction backend into its service package
 
-Status: rejected — More compaction backends are planned, so the interface and basic implementation packages remain separate.
+Status: rejected — More compaction backends are planned, so the Service Definition and basic provider packages remain separate.
 
 English | [中文](2026-07-19-fold-compaction-package-split.zh.md)
 
 ## Problem
 
-Compaction is split between `@deepseek-ai/dsh-compact`, which owns an abstract two-method service and shared types, and `@deepseek-ai/dsh-compact-basic`, which owns the only complete implementation. Shipped configurations load only the basic package, and no production package independently consumes the interface package except that implementation.
+Compaction is split between `@deepseek-ai/dsh-compact`, which owns an abstract two-method service and shared types, and `@deepseek-ai/dsh-compact-basic`, which owns the only complete provider. Shipped configurations load only the basic package, and no production package independently consumes the Service Definition package except that provider.
 
 The split adds a package manifest, README, project boundary, dependency edge, abstract forwarding class, generated catalog entries, and composition wiring without demonstrating backend substitution. The [capability-seam decision](../../implemented/architecture/2026-06-13-capability-seams.md) requires a real interface, implementation, and consumer rather than a preemptive split; the [compaction decision](../../implemented/feature/2026-06-18-compaction-capability-seam.md) records that its independent consumer was deferred.
 
@@ -14,7 +14,7 @@ The split adds a package manifest, README, project boundary, dependency edge, ab
 
 Move the basic implementation into `@deepseek-ai/dsh-compact` and remove `@deepseek-ai/dsh-compact-basic`. Keep `ctx.compact`, `CompactionResult`, the shared transcript and tool-pairing helpers, the existing configuration, and the concrete compaction algorithm in one package.
 
-Preserve `summarize()` as a protected customization hook. A deployment-specific summarizer can subclass or intercept the existing LLM call without requiring a second capability package. Reintroduce an interface package only when a second complete backend and an independent consumer need substitution.
+Preserve `summarize()` as a protected customization hook. A deployment-specific summarizer can subclass or intercept the existing LLM call without requiring a second capability package. Reintroduce a separate Service Definition package only when a second complete backend and an independent Consumer need substitution.
 
 Amend the implemented compaction decision and the [recallable-compaction proposal](../../proposed/feature/2026-07-06-recallable-compaction.md) if this proposal is accepted so package ownership has one durable description.
 
@@ -22,7 +22,7 @@ Amend the implemented compaction decision and the [recallable-compaction proposa
 
 **Keep the split because a remote or recall backend may arrive.** A possible future implementation does not justify the current package boundary. Recall adds a consumer of compaction results, not necessarily another implementation, and a remote summarizer can use the protected hook.
 
-**Move the implementation package name onto the interface package.** Keeping `compact-basic` as the surviving name would make the product service appear to be one optional backend. `compact` is the stable service identity already used by `ctx.compact` and is the clearer single-package owner.
+**Move the provider package name onto the Service Definition package.** Keeping `compact-basic` as the surviving name would make the product service appear to be one optional backend. `compact` is the stable service identity already used by `ctx.compact` and is the clearer single-package owner.
 
 ## Acceptance criteria
 
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
index 1b7e456536..ada725cbf7 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
@@ -1,12 +1,12 @@
 # Agent Note: 将唯一的压缩后端并入服务包
 
-Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 实现包继续分离。
+Status: rejected — 计划增加更多压缩后端，因此 Service Definition 包与 basic 提供方包继续分离。
 
 [English](2026-07-19-fold-compaction-package-split.md) | 中文
 
 ## 问题
 
-压缩（compaction）目前拆分在两个包中：`@deepseek-ai/dsh-compact` 拥有一个含两个方法的抽象服务和共享类型，`@deepseek-ai/dsh-compact-basic` 拥有唯一的完整实现。交付配置只加载 basic 包，除了该实现外，没有生产包独立消费接口包。
+压缩（compaction）目前拆分在两个包中：`@deepseek-ai/dsh-compact` 拥有一个含两个方法的抽象服务和共享类型，`@deepseek-ai/dsh-compact-basic` 拥有唯一的完整提供方。交付配置只加载 basic 包，除了该提供方外，没有生产包独立消费 Service Definition 包。
 
 该拆分增加了一份包 manifest（元数据清单）、README、项目边界、依赖边、抽象转发类、生成目录项和组合接线，却没有实际的后端替换用例。[能力 seam 决策](../../implemented/architecture/2026-06-13-capability-seams.md)要求接口、实现和消费方都必须真实存在，而不能预先拆分；[压缩决策](../../implemented/feature/2026-06-18-compaction-capability-seam.md)也记录了独立消费方仍被推迟。
 
@@ -14,7 +14,7 @@ Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 
 
 把 basic 实现移入 `@deepseek-ai/dsh-compact`，并删除 `@deepseek-ai/dsh-compact-basic`。`ctx.compact`、`CompactionResult`、共享 transcript（文本记录）和工具配对辅助方法、现有配置以及具体压缩算法都由一个包负责。
 
-保留 `summarize()` 作为受保护的自定义钩子。部署专用的摘要器可以通过继承或拦截现有 LLM（大语言模型）调用完成定制，无需第二个能力包。只有在第二个完整后端与独立消费方确实需要替换实现时，才重新提取接口包。
+保留 `summarize()` 作为受保护的自定义钩子。部署专用的摘要器可以通过继承或拦截现有 LLM（大语言模型）调用完成定制，无需第二个能力包。只有在第二个完整后端与独立 Consumer 确实需要替换实现时，才重新引入独立的 Service Definition 包。
 
 如果本提案获准，应同步修订已实现的压缩决策与[可回忆压缩提案](../../proposed/feature/2026-07-06-recallable-compaction.md)，使包所有权只有一处持久说明。
 
@@ -22,7 +22,7 @@ Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 
 
 **为可能出现的远程或回忆后端保留拆分。** 一种可能的未来实现不足以支撑当前包边界。回忆功能会增加压缩结果的消费方，但不一定增加另一种实现；远程摘要器也可以使用受保护钩子。
 
-**将实现包名用于接口包。** 如果保留 `compact-basic` 作为最终名称，产品服务会看起来像一个可选后端。`compact` 已经是 `ctx.compact` 使用的稳定服务标识，更适合作为单包所有者。
+**将提供方包名用于 Service Definition 包。** 如果保留 `compact-basic` 作为最终名称，产品服务会看起来像一个可选后端。`compact` 已经是 `ctx.compact` 使用的稳定服务标识，更适合作为单包所有者。
 
 ## 验收标准
 
diff --git a/AGENTS.md b/AGENTS.md
index def643ad95..ff31eb0b65 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,30 +14,30 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
   api/         Remote BFF assembly and TypeRT RPC gateway
   typert/      type graph generator, loader, and runtime registry
-  llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
+  llm/         LLM capability: Service Definition/Consumer + DeepSeek providers
   e2b/         E2B POC: sandbox + FS/subprocess adapters
-  bash/        bash executor seam + local/pwsh impls + model-facing shell tools
-  subprocess/  subprocess seam + local process-tree impl
-  pty/         persistent PTY seam/backend/tools
-  fs/          filesystem seam/backends/policy/tools
-  lsp/         language-server seam/local backend/tool
+  bash/        bash capability: Service Definition + local/pwsh providers + shell Consumers
+  subprocess/  subprocess capability + local process-tree provider
+  pty/         persistent PTY capability
+  fs/          filesystem capability + policy
+  lsp/         language-server capability
   skill/       skill provider registry + local impl + catalog/loader tool
-  web/         web seam + search/fetch providers + model-facing web tools
-  compact/     compaction seam + basic backend
+  web/         web capability: Service Definition + search/fetch providers + tool Consumer
+  compact/     compaction capability + basic provider
   context/     request-context plugins
-  subagent/    subagent seam + spawn/fork/ACP backends + tool
+  subagent/    subagent capability: Service Definition + providers + delegation Consumers
   bundle/      installable dsh --profile patch-layer bundles
-  workflow/    workflow seam + worker-thread engine + workflow tool
+  workflow/    workflow capability + worker-thread provider + tool Consumer
   todo/        todo_write tool
   plan/        plan mode as logged state
   guard/       loop-hygiene + tool-timeout plugins
   self-modification/  the agent inspects/mounts its own plugins
   hooks/       Claude Code/Codex hook bridges + wire-protocol library
   session/     durable session data: persistence, projection, titles, telemetry
-  settings/    user-settings seam + file provider
-  credentials/ credential-reference seam + env/.env provider
+  settings/    user-settings capability + file provider
+  credentials/ credential-reference capability + env/.env provider
   acp/         automation-only Agent Client Protocol server
-  interaction/ approval/interaction seams, permission, commands, ask-user
+  interaction/ approval/interaction capabilities, permission, commands, ask-user
   boot/        shared app-bin glue
   scaffold/    project tooling: helper, launcher, initializer, SDK protocol
   examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
@@ -103,14 +103,14 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
-- **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
-- **Capability seams span three packages** — interface / implementation / consumer; don't split preemptively. The seam is all three ([glossary](docs/glossary.md#capability-seam)).
+- **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
+- **A capability seam comprises Service Definition / Service provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
 - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
-- **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
-- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test seam is not configurability. Protocol constants, external specs, and security invariants stay fixed.
+- **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
+- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed.
 - **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
 - **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
-- **Trust TypeScript at typed same-process seams.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
+- **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
 - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
 - **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
@@ -119,7 +119,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
-- **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
+- **Plan unit, e2e, and snapshot coverage** for new capability seams, lifecycle shapes, and transcript surfaces; add missing snapshot-harness support in the same change.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
 - **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
@@ -131,7 +131,7 @@ Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle,
 
 ## Type safety and documentation
 
-Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why a narrower type is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring seam, protocol, or class.
+Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class.
 
 Comments and docs preserve complete contracts and non-obvious orientation, not reasoning transcripts. Do not narrate control flow or tests, preserve review history, or restate code. Keep factual clauses affecting behavior, failure, timing, ownership, or safe use; link aggressively to owning rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for prose decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each new or changed acceptance path rejects an invalid case. Use narrow justified exceptions instead of disabling a rule globally.
 
diff --git a/apps/web/tests/approval-composer.e2e.ts b/apps/web/tests/approval-composer.e2e.ts
index 5723c7a9db..33259b6ed2 100644
--- a/apps/web/tests/approval-composer.e2e.ts
+++ b/apps/web/tests/approval-composer.e2e.ts
@@ -89,7 +89,7 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
     await input.fill('')
 
     // Read-only: the mode whose denial the model escalates from. Switched
-    // through the shipped access-mode chip, not a test-only seam.
+    // through the shipped access-mode chip, not a test-only override.
     await page.locator('[aria-label^="Access mode"]').click()
     await page.getByRole('menuitem', { name: 'Read Only' }).click()
     await expect.poll(
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
index 0c43bf3998..791f8e98c1 100644
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -4,7 +4,7 @@
 // a route keeps deriving from its own log — the tier order the gateway
 // resolves on every read.
 // Zero model calls: the switch is settings/llm-domain traffic only, so there
-// is no fixture and a stray stream would fail loud on the open seam. Both
+// is no fixture and a stray stream would fail loud because the adapter registry is empty. Both
 // routes are declared host-side (not through the UI, which has its own
 // scenario) through the pi-ai adapter the shipped tree already mounts: a
 // fixture-less scaffold registers no adapter at all, so the routes the
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 1aa6b3dea9..5f2173248e 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -232,7 +232,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
 
   it.skipIf(MODE === 'record')('cascades the dark theme from the body attribute to painted surfaces', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-lifecycle-dark'))
-    // This scenario pins the ThemeService's DOM contract seam directly (the
+    // This scenario pins the ThemeService's DOM contract directly (the
     // body[data-ds-dark-theme] attribute -> stylesheet cascade); the REAL
     // user gesture above it (Settings -> Appearance cubes) is owned by
     // settings-chrome.e2e.ts. Driving the attribute here keeps the cascade
diff --git a/apps/web/tests/live-interactions.e2e.ts b/apps/web/tests/live-interactions.e2e.ts
index e3a427c446..90383f6987 100644
--- a/apps/web/tests/live-interactions.e2e.ts
+++ b/apps/web/tests/live-interactions.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenarios: live-turn interactions — cancellation, error surfacing,
 // and transient-retry recovery, all through the real composition and wire.
-// The model seam is dsh-llm-replay with override sidecars: `hang` (+ a
+// The model adapter is dsh-llm-replay with override sidecars: `hang` (+ a
 // readyFile marker) makes mid-stream cancel deterministic by construction,
 // `throw` entries express provider failures by stable code, and `{ patches }`
 // augmentation injects a transient throw before the recorded success so
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index be3c6f18a1..53d5ef4982 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -7,7 +7,7 @@
 // provider status. The customized-settings fold writes the curated
 // reasoning field as a merge patch. Zero model calls: configuration is pure
 // settings/credentials/llm-domain traffic, so there is no fixture and a
-// stray stream would fail loud on the open seam. The provider under test is
+// stray stream would fail loud because the adapter registry is empty. The provider under test is
 // minimax-cn so a developer's real ANTHROPIC/OPENAI environment keys can
 // never shadow the derived reference. The deletion dialog distinguishes a
 // reference-free profile from a page-managed key before the credential and
diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts
index 19271ad020..0bb0bc8176 100644
--- a/apps/web/tests/replay-round-trip.e2e.ts
+++ b/apps/web/tests/replay-round-trip.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: fresh round trip. A real chromium types a prompt into the
 // real composer; the wire, apiproxy, agent loop, and the REAL bash tool (echo
-// in the temp workspace) all run; the model seam is dsh-llm-replay (keyless)
+// in the temp workspace) all run; the model adapter is dsh-llm-replay (keyless)
 // or the live adapter (record). Drive steps run in every mode and wait only
 // on generic completion (whenTurnSettled — never model-content selectors, so
 // record cannot hang on a live model answering differently); assertion steps
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 6a8ff82ff1..31a638c12e 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -151,7 +151,7 @@ export interface WebScaffold {
   mode: WebSnapshotMode
   /** Browser-facing origin for the bound test server. */
   baseUrl: string
-  /** Settled root context (the in-process barrier seam; headless event subscription is its sanctioned use). */
+  /** Settled root context (the in-process readiness barrier; headless event subscription is its sanctioned use). */
   ctx: Context
   /** Temp project directory sessions run in (bash/fs tool cwd). */
   workspaceCwd: string
diff --git a/apps/web/tests/sidebar-subagent-activity.e2e.ts b/apps/web/tests/sidebar-subagent-activity.e2e.ts
index 4c37ea6fc1..8e40480090 100644
--- a/apps/web/tests/sidebar-subagent-activity.e2e.ts
+++ b/apps/web/tests/sidebar-subagent-activity.e2e.ts
@@ -27,7 +27,7 @@ const MODE = webSnapshotMode()
 const HOLD_PROVIDER = 'web-test-hold'
 const HOLD_MODEL = 'hold'
 
-/** Model seam that completes the owner turn, then holds its delegated child open. */
+/** Model stub that completes the owner turn, then holds its delegated child open. */
 class StagedAdapter extends LlmAdapter {
   activeCalls = 0
   private calls = 0
diff --git a/apps/web/tests/skill-user-invoke.e2e.ts b/apps/web/tests/skill-user-invoke.e2e.ts
index 2d5a039623..302aa062b0 100644
--- a/apps/web/tests/skill-user-invoke.e2e.ts
+++ b/apps/web/tests/skill-user-invoke.e2e.ts
@@ -2,7 +2,7 @@
 // the composer (issue #1470). The entered `/name args` line claims into
 // skill.invoke: the real host forwards the gesture as an ordinary user
 // prompt, injects the rendered body as instructions context named after the
-// skill, and starts a turn answered by the replay seam. The transcript shows
+// skill, and starts a turn answered by the replay adapter. The transcript shows
 // the gesture bubble, the collapsed context-injection row, and the reply.
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -133,7 +133,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
     expect(injected).not.toContain(ARGS_TEXT)
     await injectionRow.click()
 
-    // The injection started a turn; the replay seam answers it.
+    // The injection started a turn; the replay adapter answers it.
     await page.getByText('USER_INVOKE_REPLY', { exact: false }).first().waitFor({ timeout: 20_000 })
 
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index a7e6b06747..f373fd6469 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -20,7 +20,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 |---|---|---|
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [architecture.md](architecture.md) | System map: services, loop, capability seams, extension points — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
 | [subsystems/](subsystems/README.md) | One reference page per subsystem: type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
@@ -42,7 +42,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write directly without metaphor. Name actors and exact facts; use words you'd say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Avoid "gate", "vocabulary", "surface", or "seam".
+- Write directly: name actors and facts plainly ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability; avoid metaphorical "gate", "vocabulary", and "surface".
 
 ## Wordcount Budgets
 
@@ -65,7 +65,7 @@ Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standar
 - Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
 - Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
 - Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
-- Rationale repeated beside sibling methods instead of once at the owning seam or helper.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
 - Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it, or demote the detail to the linked home.
 - Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
 - Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 7c8b1b95c8..dff7978387 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: bb76e6ce106bf6ab06b3a12b536aabbae581740f
-architecture.zh.md: eb2fc4dea190914d0b5f0732db571c81f2f0d471
+architecture.md: 506283bfc651d38fe4bccd50fb8a86143d2b41d8
+architecture.zh.md: ea48af8131ebbdc70a45e403dfddc78dfcfb6f47
diff --git a/docs/architecture.md b/docs/architecture.md
index bb76e6ce10..506283bfc6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -156,11 +156,9 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 ### Capability Pattern
 
-A **seam** is a swappable capability across three packages: a **Service Definition** (the Cordis `Service` owning its `ctx` key and vocabulary), a **Service provider** (the implementation plugin), and a **Consumer**. The Service Definition alone is the service, not the seam. Bash is the reference; the [capability graph](capability-seams.md) shows every family.
+A **seam** is a swappable capability with **Service Definition**, **Service provider**, and **Consumer** roles. Packages may combine roles; individual roles are not seams. Filesystem and subprocess providers share one execution world; Bash, PTY, and LSP need no provider forks ([capability graph](capability-seams.md)).
 
-Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks.
-
-Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)).
+Exceptions combine LLM Service Definition/Consumer roles, filesystem policy, web registries, and skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate a self-contained turn to Codex or another product provider ([subagent.md](subsystems/subagent.md)).
 
 `dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths.
 
@@ -191,4 +189,4 @@ New behavior attaches to a documented extension point; a loop change updates thi
 | Fork a live session | call `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | Scope a registration to one agent | use its `agent.ctx` (see Agent Scope) |
 
-The [extension cookbook](cookbook/extension-cookbook.md) has plugin skeletons and the feature-to-seam map; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
+The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index eb2fc4dea1..ea48af8131 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -156,11 +156,9 @@ idle inject:
 
 ### 能力模式
 
-一个 **seam** 是跨三个包的一项可替换能力：**Service Definition**（拥有自身 `ctx` key 和词汇的 Cordis `Service`）、**Service provider**（实现插件）和 **Consumer**。Service Definition 本身只是服务，不是 seam。Bash 是参考；[能力图](capability-seams.md)展示每个家族。
+一个 **seam** 是一项包含 **Service Definition**、**Service provider** 和 **Consumer** 三种角色的可替换能力。包可以合并承担多个角色；任何单一角色都不是 seam。文件系统与进程管理提供方共享一个执行世界，Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork（[能力图](capability-seams.md)）。
 
-文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。
-
-例外情况包括 LLM（大语言模型）接口／消费方合并、文件系统策略、web 注册表，以及具名 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
+例外情况包括 LLM（大语言模型）Service Definition／消费方角色合并、文件系统策略、web 注册表，以及 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 或其他产品提供方（[subagent.md](subsystems/subagent.md)）。
 
 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
@@ -191,4 +189,4 @@ idle inject:
 | fork 活跃会话 | 调用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 将注册项限定到单个 agent | 使用其 `agent.ctx`（参见 Agent 作用域） |
 
-[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到 seam 的映射；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)将功能映射到能力；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 1fd835771a..5ec532504d 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: e1d0374afab497982b862ab84af4c003a30b5d93
-config-catalog.zh.md: 93ca0a02b0027a77f3f2f9e1c41faa1275161ed2
+config-catalog.md: a059159aae690330c55971bc49d62fcb1b030660
+config-catalog.zh.md: 9a0742ec8af10db90d0a2aad146c0cbec5a1a8a2
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index e1d0374afa..a059159aae 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -623,7 +623,7 @@ Source: [`packages/support/invariants/src/index.ts:15`](../packages/support/inva
 Requires: `agents`
 
 ```ts config-catalog
-/** JSON-RPC deployment config plus runtime-only test seams. */
+/** JSON-RPC deployment config plus runtime-only test hooks. */
 export interface JsonRpcConfig {
   /** Report max-token turn/subagent termination as a successful SDK result. */
   maxTokensAsSuccess?: boolean
@@ -1515,7 +1515,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/skill/src/index.ts:265`](../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:266`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 93ca0a02b0..9a0742ec8a 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -625,7 +625,7 @@ export interface Config {
 需要：`agents`
 
 ```ts config-catalog
-/** JSON-RPC deployment config plus runtime-only test seams. */
+/** JSON-RPC deployment config plus runtime-only test hooks. */
 export interface JsonRpcConfig {
   /** Report max-token turn/subagent termination as a successful SDK result. */
   maxTokensAsSuccess?: boolean
@@ -1517,7 +1517,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/skill/skill/src/index.ts:265`](../packages/skill/skill/src/index.ts)
+来源：[`packages/skill/skill/src/index.ts:266`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 98b5a7fe23..aa582c2bb1 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.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 docs/cookbook/adding-a-package.md
-adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
-adding-a-package.zh.md: 400bd080b04ff5791393b56e67c1e3b9ade987de
+adding-a-package.md: 79e8604a47a4bdbb7e2912990a8b1c8be300b3b0
+adding-a-package.zh.md: 5fcdf03f52dfdfe375aeb2b6fd41e50ee406d043
diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md
index 8ab603ea7b..79e8604a47 100644
--- a/docs/cookbook/adding-a-package.md
+++ b/docs/cookbook/adding-a-package.md
@@ -40,7 +40,7 @@ Covered automatically by globs or package-manifest discovery — no edits needed
 
 ## 3. Decide the package topology
 
-For a swappable capability, split interface / implementation / consumer into separate packages (see docs/architecture.md § "Capability seams" — the bash trio is the template). A single-purpose plugin stays one package.
+For a swappable capability, separate Service Definition / Service provider / Consumer roles into packages when they evolve independently (see docs/architecture.md § "Capability seams" — the bash trio is the template). A single-purpose plugin stays one package.
 
 ## 4. Write the package README
 
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 400bd080b0..5fcdf03f52 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -40,7 +40,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 
 ## 3. 确定包拓扑
 
-对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
+对于可替换的能力，当 Service Definition／Service provider／Consumer 角色需要独立演进时，将它们拆分到不同包中（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
 
 ## 4. 编写包 README
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index c053132c54..0509a67549 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.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 docs/cookbook/extension-cookbook.md
-extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
-extension-cookbook.zh.md: 83521cd348c68ba6f20f5beecfbcde51b0f2fb02
+extension-cookbook.md: 025a1b6ecd11593b5d6be9d0f64e57ac8b5e3139
+extension-cookbook.zh.md: f838a281fabdba473b72b27f7b14274d9aa97528
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index e04f6ffcf9..025a1b6ecd 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -2,7 +2,7 @@
 
 English | [中文](extension-cookbook.zh.md)
 
-Reference shapes for the harness extension surface. The snippets omit imports and helper implementations and are not copy-paste-complete. For concrete authoring paths, see the [package checklist](adding-a-package.md), [first-tool tutorial](../user/develop/basic/tool.md), [tool reference](adding-a-tool.md), and [LLM adapter guide](adding-an-llm-adapter.md); the [architecture](../architecture.md) owns the system and extension-seam map.
+Reference shapes for the harness extension surface. The snippets omit imports and helper implementations and are not copy-paste-complete. For concrete authoring paths, see the [package checklist](adding-a-package.md), [first-tool tutorial](../user/develop/basic/tool.md), [tool reference](adding-a-tool.md), and [LLM adapter guide](adding-an-llm-adapter.md); the [architecture](../architecture.md) owns the system and extension-point map.
 
 ## A tool plugin
 
@@ -10,7 +10,7 @@ A tool registers on `ctx.tools`. The annotated `defineTool` example (typed `exec
 
 ## A hook plugin (permission-gate example)
 
-This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this seam. Hook plugins can intercept other seams and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception seam; it needs no external protocol.
+This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this extension point. Hook plugins can intercept other extension points and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception point; it needs no external protocol.
 
 ```ts
 import type { Context } from 'cordis'
@@ -94,13 +94,13 @@ Runnable leaves load their plugin trees from `examples/*/cordis.yml`; the root `
 
 ## The feature → mechanism map
 
-Every product feature maps to a listener on a documented extension seam — the microkernel claim made checkable ([microkernel Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)). No row modifies the loop.
+Every product feature maps to a listener on a documented extension point — the microkernel claim made checkable ([microkernel Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)). No row modifies the loop.
 
 `system-prompt/assemble` is an expert cooperative whole-assembly transform: its returned assembly is authoritative, so listener authors own preserving active Code Mode and structured-output protocol contributions. Prefer `ctx.tools.restrict()` for tool filtering that must stay aligned across presentation, lookup, and execution.
 
 | Product feature | Plugin mechanism |
 |---|---|
-| Hook system (user + project level) | listeners on `agent/session-start`, `agent/pre-step`, `agent/request`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfall seams return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude` / `dsh-hooks-codex` bridges map hook config files onto these seams |
+| Hook system (user + project level) | listeners on `agent/session-start`, `agent/pre-step`, `agent/request`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfalls return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude` / `dsh-hooks-codex` bridges map hook config files onto these extension points |
 | `/goal` | `ctx.goals` owns durable state, `dsh-goal-session` schedules same-session rounds through the public `Agent`, and separate command/tool producers expose human/model control |
 | `/loop` | on the `turn/end` session event, `followup()` the next iteration; or force-continue |
 | Dynamic workflow | `ctx.workflows` + the worker-thread engine + the `workflow` tool; structured in-process children enforce output with scoped prompt/tool registrations, a monotonic tool guard, final `tools/result` commit (including enclosing `run_code`), and the structured-output execution's monotonic `concludeTurn()` marker |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index 83521cd348..f838a281fa 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -2,7 +2,7 @@
 
 [English](extension-cookbook.md) | 中文
 
-harness 扩展表面的参考形态。代码片段省略了 import 和辅助实现，无法直接复制运行。具体编写路径见[包检查清单](adding-a-package.md)、[第一个工具教程](../user/develop/basic/tool.md)、[工具参考](adding-a-tool.md)和 [LLM（大语言模型）适配器指南](adding-an-llm-adapter.md)；系统与扩展 seam 映射由[架构文档](../architecture.md)负责。
+harness 扩展表面的参考形态。代码片段省略了 import 和辅助实现，无法直接复制运行。具体编写路径见[包检查清单](adding-a-package.md)、[第一个工具教程](../user/develop/basic/tool.md)、[工具参考](adding-a-tool.md)和 [LLM（大语言模型）适配器指南](adding-an-llm-adapter.md)；系统与扩展点映射由[架构文档](../architecture.md)负责。
 
 ## 工具插件
 
@@ -10,7 +10,7 @@ harness 扩展表面的参考形态。代码片段省略了 import 和辅助实
 
 ## 钩子插件（以权限门禁为例）
 
-这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该 seam。钩子插件也可以拦截其他 seam，本身并不等同于权限门禁。「原生钩子」是在拦截 seam 上运行的普通 Cordis 插件，不需要外部协议。
+这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该扩展点。钩子插件也可以拦截其他扩展点，本身并不等同于权限门禁。「原生钩子」是在拦截点上运行的普通 Cordis 插件，不需要外部协议。
 
 ```ts
 import type { Context } from 'cordis'
@@ -94,13 +94,13 @@ export function apply(ctx: Context) {
 
 ## 功能→机制映射
 
-每个产品功能都映射到一个文档化扩展 seam 上的监听器——微内核声明由此可验证（[微内核 Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）。没有任何一行修改循环本身。
+每个产品功能都映射到一个文档化扩展点上的监听器——微内核声明由此可验证（[微内核 Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）。没有任何一行修改循环本身。
 
 `system-prompt/assemble` 是一个专家协作式的整体装配变换：其返回的装配结果具有权威性，因此监听器作者有责任保留活跃的 Code Mode 和结构化输出协议的贡献。对于需要在展示、查找和执行之间保持对齐的工具过滤，优先使用 `ctx.tools.restrict()`。
 
 | 产品功能 | 插件机制 |
 |---|---|
-| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall seam 返回类型化决策，`agent/turn-stopping` 则可通过 steering（中途引导）触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
+| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall 返回类型化决策，`agent/turn-stopping` 则可通过 steering（中途引导）触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些扩展点上 |
 | `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话 Round，独立的命令/工具生产方分别提供人类/模型控制 |
 | `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
 | 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
index 8f27720c45..68f62583c2 100644
--- a/docs/defensive-patterns.i18n.yaml
+++ b/docs/defensive-patterns.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 docs/defensive-patterns.md
-defensive-patterns.md: 6dc1708f0b9bbcb00ad4774006d6d60059accf6a
-defensive-patterns.zh.md: 587d09a812857e6cf61f64bfd0e17e3386d1a772
+defensive-patterns.md: afb462e120892eafe676d8b7feef273c2d0e42df
+defensive-patterns.zh.md: ab5f689d47f89b6930b749824c69325490bd4586
diff --git a/docs/defensive-patterns.md b/docs/defensive-patterns.md
index 6dc1708f0b..afb462e120 100644
--- a/docs/defensive-patterns.md
+++ b/docs/defensive-patterns.md
@@ -8,9 +8,9 @@ Hard-won bug-class rules: each pattern below is a class of defect that actually
 
 A result can be several things at once — a process can time out AND exit 0 because it trapped the signal. Surface each independent fact (`timedOut`, `signal`, `exitCode`) on its own; never nest one flag's report inside another's branch, or a caller reads a cut-short run as a clean success.
 
-## Honor cross-seam contracts on BOTH sides
+## Honor public contracts on BOTH sides
 
-When an implementation boundary receives several representations of one outcome, normalize them before crossing the public seam. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmService.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer.
+When an implementation boundary receives several representations of one outcome, normalize them before crossing the public contract. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmService.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer.
 
 ## Async state is not synchronous state
 
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
index 587d09a812..ab5f689d47 100644
--- a/docs/defensive-patterns.zh.md
+++ b/docs/defensive-patterns.zh.md
@@ -8,13 +8,13 @@
 
 一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。
 
-## 跨 seam 约定两侧都要遵守
+## 公共约定两侧都要遵守
 
-当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
+当一个实现边界接收到同一结果的多种表示时，应在跨越公共约定前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止 finish chunk 暴露模型请求失败；middleware 与消费方缺陷仍会抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化约定；通过真实消费方覆盖每种来源形式。
 
 ## 异步状态不是同步状态
 
-`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
+`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent 下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
 
 ## Dispose 必须达到完全停稳，而不仅仅是请求停止
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 8aaa444853..788069e02d 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 628750959e9c165006e221655cacb2de2dfcf637
-event-producer-consumer.zh.md: f09d8dc0b877c2c1d167b1aaad391bfe524828ed
+event-producer-consumer.md: d5f6674a5e9355f6f2c3fac23a45fcda180b3a0f
+event-producer-consumer.zh.md: 7568e852c891e6c9556486899fe1bdcd3053cb07
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 628750959e..d5f6674a5e 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:284`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index f09d8dc0b8..7568e852c8 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -38,7 +38,7 @@
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:284`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index b9dd5915c0..1dfb89b07f 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.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 docs/glossary.md
-glossary.md: acb093b097da62c92e3ade07f2dcb454eee576d2
-glossary.zh.md: ddf76edb1fd7e810badb68fadc0e3c67f2bc2b58
+glossary.md: d556e760dd2f07ab640aafca06b2757b47935406
+glossary.zh.md: d6a8e423ff2a6324ce0cdd65dd3edde573fac5b1
diff --git a/docs/glossary.md b/docs/glossary.md
index acb093b097..d556e760dd 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -6,7 +6,7 @@ Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per conce
 
 ## capability-seam
 
-- **seam** — a *swappable capability* packaged as a trio: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`, never a TypeScript `interface`), one or more **Service providers** (the implementation plugins that register a backend), and a **Consumer** (the model- or plugin-facing surface that injects the service). `packages/bash` is the canonical example: `dsh-bash` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), `dsh-tool-bash` (consumer). The seam is all three together; the interface package alone is the *Service Definition*, one member — calling it "the seam" is the misuse this entry names. Fold roles only when they are genuinely one concern (`dsh-llm` folds the Service Definition and consumer); never split preemptively.
+- **seam** — a *swappable capability* with three roles: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`, never a TypeScript `interface`), one or more **Service providers**, and one or more **Consumers** that inject the service. `packages/bash` is the canonical example: `dsh-bash` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), and `dsh-tool-bash` (Consumer). Roles normally occupy separate packages when they evolve independently, but a package may own multiple roles when they are one concern (`dsh-llm` owns its Service Definition and Consumer). The seam is the complete capability, never one role; reserve the term for that meaning and name a constituent by its role, class, service, contract, or extension point.
 
 ## agent-scope
 
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index ddf76edb1f..d6a8e423ff 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -6,7 +6,7 @@ DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。
 
 ## capability-seam
 
-- **seam**：一种*可替换能力*，以三者组合的形式打包：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表，从不是 TypeScript `interface`）、一个或多个 **Service provider**（注册后端的实现插件）以及 **Consumer**（注入该服务、面向模型或插件的表面）。`packages/bash` 是规范范例：`dsh-bash`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方）、`dsh-tool-bash`（消费方）。seam 是三者整体；接口包本身只是 *Service Definition*，是其中一个成员——把它称为「seam」正是本条目指出的误用。只有在角色确实属于同一个关注点时才合并角色（`dsh-llm` 合并 Service Definition 和消费方）；永远不要预防性地拆分。
+- **seam**：一种包含三种角色的*可替换能力*：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表，从不是 TypeScript `interface`）、一个或多个 **Service provider**，以及一个或多个注入该服务的 **Consumer**。`packages/bash` 是规范范例：`dsh-bash`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方），以及 `dsh-tool-bash`（Consumer）。角色需要独立演进时通常位于不同包，但属于同一关注点时，一个包也可以承担多个角色（`dsh-llm` 同时承担 Service Definition 和 Consumer）。seam 是完整能力，绝不是其中一个角色；该术语仅保留此义，能力成员应按其角色、类、服务、约定或扩展点命名。
 
 ## agent-scope
 
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 4e49ef9694..51ec3673a6 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -55,7 +55,7 @@
 | Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
 | schema | schema | | | |
 | schema DSL | schema DSL | | | |
-| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
+| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
 | skill | skill | skill（技能） | | |
 | slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |
 | spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |
@@ -84,7 +84,7 @@
 | cancel | 取消 | | | |
 | canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |
 | capability | 能力 | | | 必须与 `feature` → `功能` 区分 |
-| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |
+| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |
 | feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
 | feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
 | checkpoint | 检查点 | | | |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 06e426aa5c..f4aece8a52 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -91,7 +91,7 @@ A lower-priority rule may refine but never override a higher-priority requiremen
 - Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.
 
 #### When translating into Chinese
-- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: "three-package seam" → "由三个包构成的 seam", not "三包 seam". Do not add classifiers to code, identifiers, versions, units, or fixed names.
+- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: "three-role capability seam" → "包含三种角色的能力 seam", not "三角色 seam". Do not add classifiers to code, identifiers, versions, units, or fixed names.
 
 ### Punctuation
 
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index 313b07ed56..2379b7d25b 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: 94e935998e39d4209476a8c62eb99fed0e0ce317
-README.zh.md: 0f4a4c65797cf75acc6f937e8e8beb5fcd641652
+README.md: 096fd7de4d2644dac664fac940b6487052115258
+README.zh.md: 6b6758db8f7118a09f6b0998231d3944f44f5052
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 94e935998e..096fd7de4d 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -7,12 +7,12 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | Page | Owns |
 |---|---|
 | [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, agent creation and ownership (`AgentHandle`), the `Agent` handle with its delivery/cancellation/interception contracts, and the repo-wide type patterns (`…Map → derived-union`, branded ids) |
-| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` provider contract |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
-| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
+| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API boundaries |
 | [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
-| [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
+| [commands.md](commands.md) | the human-command registry service: definitions, adapter discovery, direct invocation, results, and parsing views |
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
 | [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
@@ -42,10 +42,10 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
 | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
 | [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the claimable fallback seat, index taps |
-| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
+| [storage.md](storage.md) | the storage subsystem: the backend contract (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
-| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
+| [telemetry.md](telemetry.md) | the session-telemetry capability seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
 
 > Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section.
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 0f4a4c6579..6b6758db8f 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -7,12 +7,12 @@
 | 页面 | 负责内容 |
 |---|---|
 | [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截约定，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
-| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` 提供方约定 |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
-| [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
+| [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API 边界 |
 | [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
-| [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
+| [commands.md](commands.md) | 人类命令注册表服务：定义、适配器发现、直接调用、结果与解析视图 |
 | [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
 | [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` |
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
@@ -42,10 +42,10 @@
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
 | [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
-| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
+| [storage.md](storage.md) | 存储子系统：后端约定（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
+| [telemetry.md](telemetry.md) | 会话遥测能力 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 077edaa10e..81dc8ce5d7 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/subsystems/bash.md
-bash.md: 232443daf944237e0c9f8904a0ebeeab3d2de749
-bash.zh.md: aaabc8fb1de654096e01fcee1ad1d0f881d534e8
+bash.md: 1c60f261e292f389ea4afa3f962f698e0272007b
+bash.zh.md: 2533cbe10dc0a480d285f87e458cf5ee5fa12d75
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index 232443daf9..1c60f261e2 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -2,7 +2,7 @@
 
 English | [中文](bash.zh.md)
 
-The bash execution seam is split across interface ([dsh-bash](../../packages/bash/bash), `ctx.bash`), implementations ([dsh-bash-local](../../packages/bash/bash-local) and [dsh-bash-sandbox](../../packages/bash/bash-sandbox)), and consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash` schema). Generic background-task ids, ownership, and controls live in [tasks.md](tasks.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md).
+The bash execution seam is split across a Service Definition ([dsh-bash](../../packages/bash/bash), `ctx.bash`), Service providers ([dsh-bash-local](../../packages/bash/bash-local) and [dsh-bash-sandbox](../../packages/bash/bash-sandbox)), and Consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash` schema). Generic background-task ids, ownership, and controls live in [tasks.md](tasks.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md).
 
 Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
 
@@ -12,7 +12,7 @@ Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.t
 
 ## Request vs. spec: the `resolve()` split
 
-The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package seams" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
+The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package boundaries" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
 
 ```ts type-equiv
 /**
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor"></a>
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
 
-### `ctx.bash` — `BashExecutor`
+### `ctx.bash` — `BashExecutor` (abstract seam)
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index aaabc8fb1d..2533cbe10d 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -2,7 +2,7 @@
 
 [English](bash.md) | 中文
 
-bash 执行 seam 分为接口（[dsh-bash](../../packages/bash/bash)，`ctx.bash`）、实现（[dsh-bash-local](../../packages/bash/bash-local) 与 [dsh-bash-sandbox](../../packages/bash/bash-sandbox)）和消费方（[dsh-tool-bash](../../packages/bash/tool-bash)，即 `bash` schema）。通用后台任务的 task id、所有权与控制位于 [tasks.md](tasks.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制位于[进程管理器 seam](subprocess.md)之后。
+bash 执行 seam 分为 Service Definition（[dsh-bash](../../packages/bash/bash)，`ctx.bash`）、Service provider（[dsh-bash-local](../../packages/bash/bash-local) 与 [dsh-bash-sandbox](../../packages/bash/bash-sandbox)）和 Consumer（[dsh-tool-bash](../../packages/bash/tool-bash)，即 `bash` schema）。通用后台任务的 task id、所有权与控制位于 [tasks.md](tasks.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制位于[进程管理器 seam](subprocess.md)之后。
 
 源码：[`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
 
@@ -12,7 +12,7 @@ bash 执行 seam 分为接口（[dsh-bash](../../packages/bash/bash)，`ctx.bash
 
 ## 请求与规格：`resolve()` 拆分
 
-该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包 seam 上显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
+该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包边界处显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
 
 ```ts type-equiv
 /**
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor"></a>
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
 
-### `ctx.bash` — `BashExecutor`
+### `ctx.bash` — `BashExecutor` (abstract seam)
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 5c6c47580d..cbe983a780 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
-code-runtime.md: 7185e99042101b2c3707f3d0ed80ae6c1f1f58f0
-code-runtime.zh.md: 2b5ebea4e0e43cebd695c20d59fa6e705e4ebcf2
+code-runtime.md: 8a767287414824e6f76659c02c47193522eb21c7
+code-runtime.zh.md: e6bb7cb93cb542dceb2c7e335162a03429d161e8
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index 7185e99042..8a76728741 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -2,13 +2,13 @@
 
 English | [中文](code-runtime.zh.md)
 
-The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose interface ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread backend and tool-registry consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
+The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose Service Definition ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service provider and tool-registry Consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
 
 Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
 ## The run: request in, result out
 
-A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package seams" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
+A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package boundaries" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
 
 ```ts type-equiv
 /**
@@ -112,7 +112,7 @@ interface CodeBindingNamespace {
 ```
 
 ```ts type-equiv
-/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
 type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
 ```
 
@@ -168,17 +168,17 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime"></a>
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime`
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
 ```ts cordis-catalog
 /**
  * Execute one program against the request's bindings and capture what it
  * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means seam misuse only).
+ * field; rejection means Service Definition contract misuse only).
  * @param request - the program, its bindings, and the abort signal; the
  *   request carries everything the runtime acts on, with no hidden defaults.
  * @returns the run's outcome: completion value (when transferable), the
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 2b5ebea4e0..e6bb7cb93c 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -2,7 +2,7 @@
 
 [English](code-runtime.md) | 中文
 
-代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其接口（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread 后端与工具注册表消费方的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
+代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其 Service Definition（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread Service provider 与工具注册表 Consumer 的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
 
 源码：[`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
@@ -112,7 +112,7 @@ interface CodeBindingNamespace {
 ```
 
 ```ts type-equiv
-/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
 type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
 ```
 
@@ -168,17 +168,17 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime"></a>
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime`
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
 ```ts cordis-catalog
 /**
  * Execute one program against the request's bindings and capture what it
  * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means seam misuse only).
+ * field; rejection means Service Definition contract misuse only).
  * @param request - the program, its bindings, and the abort signal; the
  *   request carries everything the runtime acts on, with no hidden defaults.
  * @returns the run's outcome: completion value (when transferable), the
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 3bd5420573..5bc05d2916 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: c1ab6d9782f515321104d0cf4d9e037c6a68a18d
-commands.zh.md: 3b3d8def042b107c5098e76c511424f023975e77
+commands.md: c71c19b8a3f94ba468e6871d5658c4eca1c6276d
+commands.zh.md: 3f1df0e8aa40524160c8f770793b6064dd5988ae
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index c1ab6d9782..c71c19b8a3 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -2,13 +2,13 @@
 
 English | [中文](commands.zh.md)
 
-The human-command seam of [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
+The human-command registry service from [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
 
 Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## Input metadata
 
-The seam exposes one optional unstructured-input hint. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
+The service exposes one optional unstructured-input hint. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
 
 ```ts type-equiv
 /** Immutable metadata for a command's optional unstructured input. */
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 3b3d8def04..3f1df0e8aa 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -2,13 +2,13 @@
 
 [English](commands.md) | 中文
 
-[`dsh-commands`](../../packages/interaction/commands) 的用户命令 seam。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/interaction/commands/README.md) 负责组合方式与限制。
+[`dsh-commands`](../../packages/interaction/commands) 提供的用户命令注册表服务。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/interaction/commands/README.md) 负责组合方式与限制。
 
 来源：[`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## 输入元数据
 
-该 seam 公开一个可选的非结构化输入提示。命令的可用性由插件组合决定：每个消费注册表的适配器都会看到全部生效定义。
+该服务公开一个可选的非结构化输入提示。命令的可用性由插件组合决定：每个消费注册表的适配器都会看到全部生效定义。
 
 ```ts type-equiv
 /** Immutable metadata for a command's optional unstructured input. */
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 384a29469b..6445fa5d5c 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 47d115710a66bf1501e61806cbc68febbe4667ca
-compaction.zh.md: a89b218f16a44dbd184340631fa4f468f15f48f5
+compaction.md: 942cc740db6b7006952bfc33a39ea9826d673e61
+compaction.zh.md: c5b65a95f9c0db8b02912c68ef93edce2ceb7c43
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 47d115710a..942cc740db 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -2,7 +2,7 @@
 
 English | [中文](compaction.zh.md)
 
-The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: interface ([dsh-compact](../../packages/compact/compact), `ctx.compact`), implementation (a backend such as [dsh-compact-basic](../../packages/compact/compact-basic)), and human consumer ([dsh-command-compact](../../packages/compact/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
+The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: Service Definition ([dsh-compact](../../packages/compact/compact), `ctx.compact`), Service provider (a backend such as [dsh-compact-basic](../../packages/compact/compact-basic)), and human Consumer ([dsh-command-compact](../../packages/compact/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
 
 Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts)
 
@@ -81,7 +81,7 @@ type ManualCompactionErrorCode =
 
 Pressure compaction runs at serial `agent/pre-step` before request derivation. Once pressure or canonical overflow qualifies, compact-basic invokes optional [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md) before range selection, remeasures through `ctx.tokenMeter`, and can advance the surface without a summary. Failed-request recovery runs through `agent/request-error` after the failed step closes and returns a retry action only when the surface replacement generation advances, even if later summary work throws after pruning; cancellation still wins. Region boundaries preserve tool-call/result pairing but not whole turns, allowing early closed steps of one oversized turn to compact. `dsh-compact-basic` owns thresholds, retained-tail policy, overflow caps, and failure handling.
 
-The seam exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for those edge checks. Both validate current surface membership and reject missing seqs and orphan results; the [package contract](../../packages/compact/compact/README.md#tool-pairing-boundaries) owns their cache semantics.
+The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for those edge checks. Both validate current surface membership and reject missing seqs and orphan results; the [package contract](../../packages/compact/compact/README.md#tool-pairing-boundaries) owns their cache semantics.
 
 ## Tool-result pruning outcomes
 
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice"></a>
+<a id="ctxcompact--compactservice-abstract-seam"></a>
 
-### `ctx.compact` — `CompactService`
+### `ctx.compact` — `CompactService` (abstract seam)
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index a89b218f16..c5b65a95f9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -2,7 +2,7 @@
 
 [English](compaction.md) | 中文
 
-压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为接口（[dsh-compact](../../packages/compact/compact)，`ctx.compact`）、实现（例如 [dsh-compact-basic](../../packages/compact/compact-basic) 后端）和面向用户的消费方（[dsh-command-compact](../../packages/compact/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
+压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为 Service Definition（[dsh-compact](../../packages/compact/compact)，`ctx.compact`）、Service provider（例如 [dsh-compact-basic](../../packages/compact/compact-basic) 后端）和面向用户的 Consumer（[dsh-command-compact](../../packages/compact/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
 
 源码：[`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts)
 
@@ -81,7 +81,7 @@ type ManualCompactionErrorCode =
 
 压力压缩在串行 `agent/pre-step` 中运行，先于请求推导。一旦压力或规范化溢出满足条件，compact-basic 会在选择范围前调用可选的 [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md)，再通过 `ctx.tokenMeter` 重新测量，并且可以在不生成摘要的情况下推进 surface。失败请求的恢复在失败的步骤关闭后通过 `agent/request-error` 运行；仅当 surface replacement generation 前进时才返回重试动作，即便后续摘要工作在剪枝后抛异常亦如此；取消仍然优先。区域边界保持工具调用/结果配对，但不保持整个轮次，因此一个过大轮次中较早关闭的步骤可以被压缩。`dsh-compact-basic` 拥有阈值、保留尾部策略、溢出上限与失败处理。
 
-该 seam 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包约定](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
+该 Service Definition 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包约定](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
 
 ## 工具结果剪枝产出
 
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice"></a>
+<a id="ctxcompact--compactservice-abstract-seam"></a>
 
-### `ctx.compact` — `CompactService`
+### `ctx.compact` — `CompactService` (abstract seam)
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 52df396cf2..2fb9c399be 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: b6ed77c1f06b903924db31547d57e07ea37129be
-core.zh.md: d4bee1240a7f66ee0f0dc2ff2a81edb20700d99e
+core.md: ec9a966164f2b706ae16341c628fb8f849eb7382
+core.zh.md: 4de168fd9714a935b4d9b08bbabd52492d1ea1cc
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index b6ed77c1f0..ec9a966164 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -17,7 +17,7 @@ A turn flows through the six packages in one loop: the driver in [`agent-loop`](
 | `agent-loop/` | The concrete driver implementing the public `Agent` contract (`ctx.agentLoop`) | this page |
 | `scope/` | The scoped-registration primitive the registries and loop build per-agent scoping on | [scope.md](scope.md) |
 
-`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
+`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the public `Agent` contract and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
 
 ## Creation and ownership
 
@@ -48,7 +48,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, seed boundary, origin classification, delegation depth), an optional `seed` replay prefix for forks, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
 
-`AgentFactory` is the creation seam behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
+`AgentFactory` is the creation contract behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
 
 ## The agent handle
 
@@ -401,7 +401,7 @@ currentInitiator(): Agent | undefined
  * Read the initiating Agent and fail when no initiator boundary is active.
  * Use this for private helpers contractually below a driver, or for a
  * deployment-owned outbound request whose contract forbids agentless calls.
- * Generic or direct-call seams use optional lookup or explicit request fields.
+ * Generic or direct-call paths use optional lookup or explicit request fields.
  * @returns the inherited Agent.
  * @throws when no initiator is active or this service instance has been disposed.
  */
@@ -557,12 +557,12 @@ Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/i
 
 #### `agent/created` — emit
 
-A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving extension point. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
 
 ```ts cordis-catalog
 /**
  * A fully configured agent and live session were published. Setup is
- * composition-only; `agent/session-start` is the first startup-driving seam.
+ * composition-only; `agent/session-start` is the first startup-driving extension point.
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
@@ -718,14 +718,14 @@ Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/t
 
 #### `agent/request` — waterfall
 
-Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this waterfall cannot mutate messages.
 
 ```ts cordis-catalog
 /**
  * Replace the frozen call configuration. `await next()` yields the config
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
- * content must use logged channels; this seam cannot mutate messages.
+ * content must use logged channels; this waterfall cannot mutate messages.
  * @param payload.agent - the agent making the model call.
  * @param payload.turn - the open turn number.
  * @param payload.step - the step whose request this is.
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index d4bee1240a..4de168fd97 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -17,7 +17,7 @@
 | `agent-loop/` | 实现公开 `Agent` 约定的具体 driver（`ctx.agentLoop`） | 本页 |
 | `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
-`scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
+`scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是公开 `Agent` 约定的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
 
 <a id="creation-and-ownership"></a>
 
@@ -50,7 +50,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
 
-`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
+`AgentFactory` 是注册表背后的创建约定：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
 <a id="the-agent-handle"></a>
 
@@ -409,7 +409,7 @@ currentInitiator(): Agent | undefined
  * Read the initiating Agent and fail when no initiator boundary is active.
  * Use this for private helpers contractually below a driver, or for a
  * deployment-owned outbound request whose contract forbids agentless calls.
- * Generic or direct-call seams use optional lookup or explicit request fields.
+ * Generic or direct-call paths use optional lookup or explicit request fields.
  * @returns the inherited Agent.
  * @throws when no initiator is active or this service instance has been disposed.
  */
@@ -565,12 +565,12 @@ Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/i
 
 #### `agent/created` — emit
 
-A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving extension point. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
 
 ```ts cordis-catalog
 /**
  * A fully configured agent and live session were published. Setup is
- * composition-only; `agent/session-start` is the first startup-driving seam.
+ * composition-only; `agent/session-start` is the first startup-driving extension point.
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
@@ -726,14 +726,14 @@ Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/t
 
 #### `agent/request` — waterfall
 
-Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this waterfall cannot mutate messages.
 
 ```ts cordis-catalog
 /**
  * Replace the frozen call configuration. `await next()` yields the config
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
- * content must use logged channels; this seam cannot mutate messages.
+ * content must use logged channels; this waterfall cannot mutate messages.
  * @param payload.agent - the agent making the model call.
  * @param payload.turn - the open turn number.
  * @param payload.step - the step whose request this is.
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 2ea649fe56..7e9e057c75 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: 84b156e366b2f4d0aeaba11b1b8d005ff59ad11d
-credentials.zh.md: c12191529e4324aed57b0ec8870fdca5c4dcae8a
+credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
+credentials.zh.md: f236b0b2daef85784308f10dbcfc67db84c42234
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 84b156e366..0bc2224ac0 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials"></a>
+<a id="ctxcredentials--credentials-abstract-seam"></a>
 
-### `ctx.credentials` — `Credentials`
+### `ctx.credentials` — `Credentials` (abstract seam)
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index c12191529e..f236b0b2da 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials"></a>
+<a id="ctxcredentials--credentials-abstract-seam"></a>
 
-### `ctx.credentials` — `Credentials`
+### `ctx.credentials` — `Credentials` (abstract seam)
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 3b5987bfec..3dad767e63 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 6c89f6f88babf09b1cf0f6ac2b739b511568f18b
-filesystem.zh.md: 16be774c74d02894434467dc68e927fdba2e38c7
+filesystem.md: 6748ddc7f290b6714302223758587226647641e7
+filesystem.zh.md: 28535d3d9d40e92bb6d5b2b0995a535b42fd9a23
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 6c89f6f88b..6748ddc7f2 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -8,7 +8,7 @@ The model is **additive, not subtractive**: `ctx.fs` alone is a complete, uncons
 
 Provider source: [`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.ts) and [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts). Policy source: [`packages/fs/fs-policy/src/types.ts`](../../packages/fs/fs-policy/src/types.ts). Read-rendering source: [`packages/fs/tool-fs/src/read-render.ts`](../../packages/fs/tool-fs/src/read-render.ts).
 
-## Target identity and metadata (provider seam)
+## Target identity and metadata (provider contract)
 
 Every operation resolves a user-supplied path to an opaque backend target first. Consumers may display `displayPath`, but must not parse `targetKey` (a branded opaque id) or assume it is a local absolute path.
 
@@ -111,7 +111,7 @@ interface FsDirEntry {
 }
 ```
 
-## Write and edit guards (provider seam)
+## Write and edit guards (provider contract)
 
 Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
 
@@ -177,7 +177,7 @@ interface FsEditOutcome {
 }
 ```
 
-## The fs policy events (provider-seam vocabulary)
+## The fs policy events (provider contract vocabulary)
 
 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
@@ -229,7 +229,7 @@ interface FileReadOutcome {
 
 Observed state is a `WeakMap<owner, Map<targetKey, { version }>>` held inside the `dsh-fs-policy` plugin. An entry exists **iff** the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence is the prior-observation record — there is no separate `hasRead` flag and no view distinction. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. A successful read/write/edit refreshes the recorded version for that owner; disposal drops everything (HMR safety).
 
-## Error taxonomy (provider seam)
+## Error taxonomy (provider contract)
 
 Filesystem failures use stable `FsErrorCode` strings carried by `FsError` (`HarnessError`). The tool registry preserves `{ name, code }` on error results, so retry, permission, and UI layers can branch without parsing text.
 
@@ -258,11 +258,11 @@ type FsErrorCode =
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem) below shows the exact signatures.
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem"></a>
+<a id="ctxfs--filesystem-abstract-seam"></a>
 
-### `ctx.fs` — `FileSystem`
+### `ctx.fs` — `FileSystem` (abstract seam)
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 16be774c74..28535d3d9d 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -8,7 +8,7 @@
 
 提供方源码：[`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.ts) 与 [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts)。策略源码：[`packages/fs/fs-policy/src/types.ts`](../../packages/fs/fs-policy/src/types.ts)。读取渲染源码：[`packages/fs/tool-fs/src/read-render.ts`](../../packages/fs/tool-fs/src/read-render.ts)。
 
-## 目标标识与元数据（提供方 seam）
+## 目标标识与元数据（提供方约定）
 
 每个操作首先将用户提供的路径解析为不透明的后端目标。消费方可以显示 `displayPath`，但禁止解析 `targetKey`（一个品牌化的不透明 id），也不得假设它是本地绝对路径。
 
@@ -111,7 +111,7 @@ interface FsDirEntry {
 }
 ```
 
-## 写入与编辑守卫（提供方 seam）
+## 写入与编辑守卫（提供方约定）
 
 `writeText` 和 `editText` 的版本守卫都是可选的：省略守卫时执行无条件的裸提供方变更，提供守卫时则执行相应的条件检查。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
 
@@ -177,7 +177,7 @@ interface FsEditOutcome {
 }
 ```
 
-## fs 策略事件（提供方 seam 词汇）
+## fs 策略事件（提供方约定词汇）
 
 `dsh-fs` 拥有三个事件，由工具分发、策略插件监听，使发射方（`dsh-tool-fs`）与监听方（`dsh-fs-policy`）共享词汇，而发射方无需依赖策略插件。它们只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不含面向模型的概念，也不含 agent/会话所有者结构。
 
@@ -229,7 +229,7 @@ interface FileReadOutcome {
 
 已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, { version }>>`。**当且仅当**所有者已读取、写入或编辑过该目标时（每次成功都 emit `fs/observed`），条目才存在，因此其存在本身就是先前观测的记录——没有单独的 `hasRead` 标志，也没有视图区分。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。成功的 read/write/edit 会刷新该所有者对应的已记录版本；dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全）。
 
-## 错误分类体系（提供方 seam）
+## 错误分类体系（提供方约定）
 
 文件系统故障使用稳定的 `FsErrorCode` 字符串，由 `FsError`（`HarnessError`）携带。工具注册表在错误结果上保留 `{ name, code }`，使重试、权限和 UI 层可以按 code 分支而无需解析文本。
 
@@ -258,11 +258,11 @@ type FsErrorCode =
 
 ## 文件 IO 不设超时
 
-`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方 seam 也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem) 展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem"></a>
+<a id="ctxfs--filesystem-abstract-seam"></a>
 
-### `ctx.fs` — `FileSystem`
+### `ctx.fs` — `FileSystem` (abstract seam)
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 23364aacc1..2ff4b67060 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.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 docs/subsystems/invariants.md
-invariants.md: 184d982bb27ab3ff98f715f0751c8bfcc1d08bea
-invariants.zh.md: e79b1c90a1c6284691404411ad9fa8ce62ef7e5e
+invariants.md: ccf81f0252dd2db4eec666df6fab8c7d6a830f25
+invariants.zh.md: 046aa4a56d48fa0386fba3a51d850ab21ce5145d
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
index 184d982bb2..ccf81f0252 100644
--- a/docs/subsystems/invariants.md
+++ b/docs/subsystems/invariants.md
@@ -2,7 +2,7 @@
 
 English | [中文](invariants.zh.md)
 
-[dsh-invariants](../../packages/support/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the seam design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).
+[dsh-invariants](../../packages/support/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the registry design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).
 
 Source: [`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
 
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index e79b1c90a1..046aa4a56d 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -2,7 +2,7 @@
 
 [English](invariants.md) | 中文
 
-[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
+[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；注册表设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
 
 源码：[`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index abb60661c8..1808f2d8e4 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 37f2fcc51a8b899414927615a7c7750254fa9445
-llm-streaming.zh.md: f9dab459be1006c6ea894498b9a28b49e9ec7738
+llm-streaming.md: 0cfce7a06d1db73268e2457c4979d1b1ccc889b7
+llm-streaming.zh.md: 19541462805c50b0ed446a346523d20de91d0351
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 37f2fcc51a..0cfce7a06d 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -621,9 +621,9 @@ interface LlmCallConfigAdapterDefaults {
 }
 ```
 
-## The seam
+## Service and provider contracts
 
-`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#model-content).
+`LlmAdapter` is the provider contract: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#model-content).
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index f9dab459be..1954146280 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -629,9 +629,9 @@ interface LlmCallConfigAdapterDefaults {
 }
 ```
 
-## seam
+## 服务与提供方约定
 
-`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#model-content)。
+`LlmAdapter` 是提供方约定：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#model-content)。
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/docs/subsystems/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
index eb3a5e36ba..400274ceef 100644
--- a/docs/subsystems/lsp.i18n.yaml
+++ b/docs/subsystems/lsp.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 docs/subsystems/lsp.md
-lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
-lsp.zh.md: d428f2b5f9568b231b0b50a13bd4a41f7ea81346
+lsp.md: f8fa2be3d79c0aff9b288f61bf64bbb91e327f1d
+lsp.zh.md: fc9214fa7b10c2dac2a6cd90e0c29776313653f4
diff --git a/docs/subsystems/lsp.md b/docs/subsystems/lsp.md
index 03d0ce2dbe..f8fa2be3d7 100644
--- a/docs/subsystems/lsp.md
+++ b/docs/subsystems/lsp.md
@@ -2,7 +2,7 @@
 
 English | [中文](lsp.zh.md)
 
-The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: interface ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic implementation ([dsh-lsp-local](../../packages/lsp/lsp-local), a configured stdio language-server host), and consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
+The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service provider ([dsh-lsp-local](../../packages/lsp/lsp-local), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
 
 Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
 
diff --git a/docs/subsystems/lsp.zh.md b/docs/subsystems/lsp.zh.md
index d428f2b5f9..fc9214fa7b 100644
--- a/docs/subsystems/lsp.zh.md
+++ b/docs/subsystems/lsp.zh.md
@@ -2,7 +2,7 @@
 
 [English](lsp.md) | 中文
 
-LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：接口（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用实现（[dsh-lsp-local](../../packages/lsp/lsp-local)，经过配置的 stdio 语言服务器宿主）和消费方（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换提供方不会改变模型请求导航的方式。
+LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：Service Definition（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用 Service provider（[dsh-lsp-local](../../packages/lsp/lsp-local)，经过配置的 stdio 语言服务器宿主）和 Consumer（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换提供方不会改变模型请求导航的方式。
 
 源文件：[`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 1ee31d85d0..eb5478eef8 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: c8d8bba1650dd54b533e95a4ddd0a8f5a19bb0c6
-persistence.zh.md: b4440183bc56086739ac1e9fa6390e9287335986
+persistence.md: 991efe39a059e08cdf7904b473486b336cb2071c
+persistence.zh.md: 2391eeb2a751388b6aa139d0646b52fe5af04601
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index c8d8bba165..991efe39a0 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -213,9 +213,9 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence"></a>
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence`
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index b4440183bc..2391eeb2a7 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -213,9 +213,9 @@ interface SessionPersistenceSnapshot {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence"></a>
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence`
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index efe9e376c6..2286bad3fd 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: ee4b911050863765960ba46952ba923a7115e129
-plan.zh.md: 0481bdf76adf2f00fe18073fe8daa5ba172bbfe1
+plan.md: 29a2473c440b654422c4c563820efa72847a820a
+plan.zh.md: bcb327719102b90c1c7009d78cee0fa930cdc7a8
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index ee4b911050..29a2473c44 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -14,7 +14,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — the next request derivation, in whichever turn it occurs (selection never forces continuation, so an intent recorded after a turn's final step lands in a later turn). `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
-The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception point that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
 ## Configuration
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 0481bdf76a..bcb3277191 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -14,7 +14,7 @@
 
 由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——即下一次请求派生，落在哪个轮次就在哪个轮次生效（选择绝不强制续行，因此在某轮最后一步之后记录的意图会在之后的轮次落地）。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
-唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截点，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
 ## 配置
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index ab7bbb6b07..a6f8fd2609 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.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 docs/subsystems/sandbox.md
-sandbox.md: b08eacbc040568fa40c681f65577b64afe53fbaa
-sandbox.zh.md: 1e5f7f55b4923f96ffb9263e9d0784f849fd4d13
+sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
+sandbox.zh.md: 23644bb43a131a0e3c8595187a6fc11e74682d9e
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index b08eacbc04..dd960b3021 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -155,9 +155,9 @@ Provider selection, probing, caching, and backend-specific enforcement reports b
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider"></a>
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
 
-### `ctx.sandbox` — `SandboxProvider`
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index 1e5f7f55b4..23644bb43a 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -155,9 +155,9 @@ interface ConfinedArgv {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider"></a>
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
 
-### `ctx.sandbox` — `SandboxProvider`
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 98efe87541..54cadaf5b5 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: 64351195028c62f623b32cbeb80c952795c1e9e6
-session-projection.zh.md: e4a03c6719095cc342d914612faf364fc48e4fa0
+session-projection.md: ddb3877618904d3185eba7d9d351afbcc81b2d04
+session-projection.zh.md: 39e6099130ba0d91e72e8f1afd5661e5894f8d0f
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index 6435119502..ddb3877618 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -2,7 +2,7 @@
 
 English | [中文](session-projection.zh.md)
 
-The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the interface and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
 
 Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index e4a03c6719..39e6099130 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-projection.md) | 中文
 
-会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
 
 源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 02734a5cdc..4ba7a3392b 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: e62cd1c6ff744e7ccdc6f26f5ad76a6512a205bf
-session-query.zh.md: 7bd2b55509e4c5bb971a44680d0d7576c5d10146
+session-query.md: 3b6d99af58ffb7c3e7b58cc4a3e9143732382861
+session-query.zh.md: c23e9ad53ef6a3e4a8e50a892824068f33e4e15b
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index e62cd1c6ff..3b6d99af58 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -2,7 +2,7 @@
 
 English | [中文](session-query.zh.md)
 
-Query vocabulary over the live-preferred logical session corpus. The [interface package](../../packages/session-query/session-query) owns exact reads, source precedence, relationship tracing, semantic extraction, and provider-independent filters, while the [SQLite package](../../packages/session-query/session-query-sqlite) owns the concrete full-text index lifecycle.
+Query vocabulary over the live-preferred logical session corpus. The [Service Definition package](../../packages/session-query/session-query) owns exact reads, source precedence, relationship tracing, semantic extraction, and provider-independent filters, while the [SQLite provider](../../packages/session-query/session-query-sqlite) owns the concrete full-text index lifecycle.
 
 Source: [`packages/session-query/session-query/src/types.ts`](../../packages/session-query/session-query/src/types.ts)
 
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice"></a>
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService`
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 7bd2b55509..c23e9ad53e 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-query.md) | 中文
 
-本文定义逻辑会话语料库的查询词汇；当 live 数据存在时，该语料库优先使用 live 数据。[接口包](../../packages/session-query/session-query)负责精确读取、来源优先级、关系追踪、语义提取，以及与提供方无关的过滤器；[SQLite 包](../../packages/session-query/session-query-sqlite)负责具体全文索引的生命周期。
+本文定义逻辑会话语料库的查询词汇；当 live 数据存在时，该语料库优先使用 live 数据。[Service Definition 包](../../packages/session-query/session-query)负责精确读取、来源优先级、关系追踪、语义提取，以及与提供方无关的过滤器；[SQLite 提供方](../../packages/session-query/session-query-sqlite)负责具体全文索引的生命周期。
 
 源码：[`packages/session-query/session-query/src/types.ts`](../../packages/session-query/session-query/src/types.ts)
 
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice"></a>
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService`
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index da4ec0a16b..04f3cc5394 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 4b057317969c8dc59c899fb07812e01a0b5d94d3
-session.zh.md: 804edc32635ddfcc1335ecd9c0a6c4df4f998594
+session.md: a5162c77d510c5ab66fa2dd6789693e1449970fb
+session.zh.md: 989a3f5368aa0b0475dec4272fde724fd4a98230
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 4b05731796..a5162c77d5 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -663,7 +663,7 @@ prepare(id?: SessionId, options?: PrepareSessionOptions): Session
  * another create) between them, so a stale prepared session must NOT overwrite
  * a live store entry of the same id — its detach disposer would later delete
  * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public seam cannot
+ * the two back-to-back so they never trip this, but the public API cannot
  * assume that.
  *
  * @param session - a {@link prepare}d session not yet in the store.
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 804edc3263..989a3f5368 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -667,7 +667,7 @@ prepare(id?: SessionId, options?: PrepareSessionOptions): Session
  * another create) between them, so a stale prepared session must NOT overwrite
  * a live store entry of the same id — its detach disposer would later delete
  * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public seam cannot
+ * the two back-to-back so they never trip this, but the public API cannot
  * assume that.
  *
  * @param session - a {@link prepare}d session not yet in the store.
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index e541d20f69..a257e0e33e 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/subsystems/settings.md
-settings.md: c15b11c8635def88aba49b6df66aa56a22fbe0ae
-settings.zh.md: 7f588ededd0ad2eb058995d4d54fe71c8b6bc67a
+settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
+settings.zh.md: 720eb9c2718c1fa14a148cced806c224634dba69
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index c15b11c863..9256bf9436 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings"></a>
+<a id="ctxsettings--settings-abstract-seam"></a>
 
-### `ctx.settings` — `Settings`
+### `ctx.settings` — `Settings` (abstract seam)
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 7f588ededd..720eb9c271 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings"></a>
+<a id="ctxsettings--settings-abstract-seam"></a>
 
-### `ctx.settings` — `Settings`
+### `ctx.settings` — `Settings` (abstract seam)
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 570dfe223f..5945dfb286 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/subsystems/skills.md
-skills.md: 78d510fafca0017b9528a215270172a74e9b0de1
-skills.zh.md: 12e51c45a779e3ca0634db62ac9adfe69112d09f
+skills.md: 1c3d683c6fb2c2ac26e00c32329e41b8d4636fb1
+skills.zh.md: b38effdd5858625bb1aa5f10108d5d654f692b7c
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index 78d510fafc..1c3d683c6f 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -2,7 +2,7 @@
 
 English | [中文](skills.zh.md)
 
-The [skill capability family](../../packages/skill) includes the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local provider ([dsh-skill-local](../../packages/skill/skill-local)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs; providers contribute local or packaged skills; the consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
+The [skill capability family](../../packages/skill) includes the Service Definition ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local Service provider ([dsh-skill-local](../../packages/skill/skill-local)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the Consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs; providers contribute local or packaged skills; the Consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
 
 Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), [`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
 
@@ -283,7 +283,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
-Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:305`](../../packages/skill/skill/src/index.ts)
 
 <a id="skills-events"></a>
 
@@ -306,5 +306,5 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:284`](../../packages/skill/skill/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index 12e51c45a7..b38effdd58 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -2,7 +2,7 @@
 
 [English](skills.md) | 中文
 
-[skill（技能）能力族](../../packages/skill) 包含注册表（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地提供方（[dsh-skill-local](../../packages/skill/skill-local)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和消费方（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表合并各提供方的目录；提供方贡献本地或随包 skill；消费方拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
+[skill（技能）能力族](../../packages/skill) 包含 Service Definition（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地 Service provider（[dsh-skill-local](../../packages/skill/skill-local)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和 Consumer（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表合并各提供方的目录；提供方贡献本地或随包 skill；Consumer 拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
 
 源码：[`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)、[`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts)、[`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts) 与 [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts)。
 
@@ -283,7 +283,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
-Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:305`](../../packages/skill/skill/src/index.ts)
 
 <a id="skills-events"></a>
 
@@ -306,5 +306,5 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:284`](../../packages/skill/skill/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index c0e9f9f50d..da210bd7d2 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/subsystems/spill.md
-spill.md: 4998ac62d1cd4e86a6e92ec5a0c85955b137f4be
-spill.zh.md: 0495c6fbcdb5c909a142539f69d5dd2bd551413c
+spill.md: bc323f8d2591e93a56e938c245274ef6be86085f
+spill.zh.md: f81d5e5de3633561a5a090a14c39b43268b8c63f
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index 4998ac62d1..bc323f8d25 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -2,13 +2,13 @@
 
 English | [中文](spill.zh.md)
 
-The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: interface ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), implementation ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-retention](../../packages/util/retention); this seam only saves the final text the policy hands it.
+The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: Service Definition ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), Service provider ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and Consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-retention](../../packages/util/retention); this seam only saves the final text the policy hands it.
 
 Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
 
 ## The save request
 
-`saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
+`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -92,9 +92,9 @@ The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes u
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore"></a>
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
 
-### `ctx.spillStore` — `SpillStore`
+### `ctx.spillStore` — `SpillStore` (abstract seam)
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 0495c6fbcd..f81d5e5de3 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -2,13 +2,13 @@
 
 [English](spill.md) | 中文
 
-落盘存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：接口（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、实现（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和消费方（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。落盘是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.md) 中。预览机制仍归 [dsh-retention](../../packages/util/retention) 所有；该 seam 只保存策略交给它的最终文本。
+落盘存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：Service Definition（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、Service provider（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和 Consumer（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。落盘是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.md) 中。预览机制仍归 [dsh-retention](../../packages/util/retention) 所有；该 seam 只保存策略交给它的最终文本。
 
 源码：[`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
 
 ## 保存请求
 
-`saveText` 是整个 seam：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
+`saveText` 是唯一的服务操作：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -92,9 +92,9 @@ type SpillLocator = Branded<'SpillLocator'>
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore"></a>
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
 
-### `ctx.spillStore` — `SpillStore`
+### `ctx.spillStore` — `SpillStore` (abstract seam)
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 3d8db33ada..5b4d6d1040 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
-storage.md: 52dc84b699921e911276ce5214bc975abfd22fa4
-storage.zh.md: 89ff7f69ed43b55101be834c21d11cf74ca2340b
+storage.md: 94d3c3f39a65462cd8cd58a65b02066d5bad4b8c
+storage.zh.md: c3cea8eb5e44f2e589b0196dc690c6473e3552ca
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index 52dc84b699..94d3c3f39a 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -2,7 +2,7 @@
 
 English | [中文](storage.zh.md)
 
-The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and backend interface ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the backend implementations ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the domain data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend seam's only consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
+The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and Service Definition ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the Service providers ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the Consumer data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend contract's only Consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
 
 Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
 
@@ -23,7 +23,7 @@ interface StorageForms {}
 
 `mount(form, facility)` is an effect whose disposer unmounts; a second mount of the same key throws `duplicate-mount`. `form(form)` resolves a mounted facility and throws `form-not-mounted` until the owning plugin loads — assemblies order plugins accordingly rather than silently deferring. The domain layer merges `domain: DomainFacility`, so `ctx.storage.domain` and `ctx.storageDomain` are the same object.
 
-## The backend seam
+## The backend contract
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index 89ff7f69ed..c3cea8eb5e 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -2,7 +2,7 @@
 
 [English](storage.md) | 中文
 
-存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)拆分：枢纽（hub）与后端接口（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、后端实现（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及领域数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端 seam 的唯一消费方，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包（package）绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
+存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)拆分：枢纽（hub）与 Service Definition（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、Service provider（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及 Consumer 数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端约定的唯一 Consumer，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包（package）绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
 
 源码：[`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
 
@@ -23,7 +23,7 @@ interface StorageForms {}
 
 `mount(form, facility)` 是一个 effect，其 disposer 负责卸载；对同一键的第二次挂载抛出 `duplicate-mount`。`form(form)` 解析已挂载的 facility，在拥有插件加载之前抛出 `form-not-mounted`——组合方应据此安排插件顺序，而不是静默推迟。领域层合并 `domain: DomainFacility`，因此 `ctx.storage.domain` 与 `ctx.storageDomain` 是同一个对象。
 
-## 后端 seam
+## 后端约定
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 3fc905e09b..5e8fdefb08 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 9fd6c8ae16abb6d99180bad105c54cdb6db4fac5
-subagent.zh.md: 874fbfdb31b8389e4495a2f8494d9c3cb82e41b9
+subagent.md: a14e9ec5fad3f25f231016c142c3965561790afe
+subagent.zh.md: 7bf3595324ecfec85329ea3f51ab5a8cc0d4c329
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 9fd6c8ae16..a14e9ec5fa 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -4,13 +4,13 @@ English | [中文](subagent.zh.md)
 
 The subagent seam — an agent delegating work to a child agent. Like [bash](bash.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). But it differs from every other seam on one axis: **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), where bash allows only one executor. The registry shape mirrors the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
 
-Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Service providers are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing Consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
 ## Two kinds of capability, discovered two ways
 
-A provider advertises its **start-time** features on a static descriptor the service checks BEFORE a one-shot run exists; a request that needs one the provider lacks is rejected loud (`SubagentError('UNSUPPORTED_CAPABILITY')`), never accepted-then-ignored. Those flags describe only the one-shot [`start()`](#the-provider-seam-subagentprovider) path, where the provider composes the child. **Continuable** children are composed by the continuation manager itself, so they are gated by one optional method whose presence IS the capability, with TS narrowing as the discovery mechanism: [`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider).
+A provider advertises its **start-time** features on a static descriptor the service checks BEFORE a one-shot run exists; a request that needs one the provider lacks is rejected loud (`SubagentError('UNSUPPORTED_CAPABILITY')`), never accepted-then-ignored. Those flags describe only the one-shot [`start()`](#the-provider-contract-subagentprovider) path, where the provider composes the child. **Continuable** children are composed by the continuation manager itself, so they are gated by one optional method whose presence IS the capability, with TS narrowing as the discovery mechanism: [`SubagentProvider.prepareContinuable`](#the-provider-contract-subagentprovider).
 
 ```ts type-equiv
 /**
@@ -191,7 +191,7 @@ interface ContinuableStart {
 
 An optional continuable-child setup contribution can install scope-local capabilities after base child composition and before Activation publication. The registry is ordered and transactional: a failed or revoked setup rolls back the unpublished Activation, child-scope disposal releases every installation, new registrations affect the next Activation, and registration removal revokes every resident installation immediately.
 
-`SubagentService.reportFrom()` uses that extension seam without adding a second queue or a result-bearing child wrapper. The exact live child Agent authorizes the call; callers cannot name a recipient. The manager derives the only recipient from the child's durable `parentSession`, requires that parent Agent to be live, frames the selected content as one `subagent-report` user message, and returns the message's stable `MessageId`. Quiet delivery uses `Agent.inject()` and creates no inbox occurrence or parent turn; waking delivery uses `Agent.followup()` and creates one ordinary later parent turn. Neither mode concludes the child's turn, and no final answer reports implicitly.
+`SubagentService.reportFrom()` uses that extension point without adding a second queue or a result-bearing child wrapper. The exact live child Agent authorizes the call; callers cannot name a recipient. The manager derives the only recipient from the child's durable `parentSession`, requires that parent Agent to be live, frames the selected content as one `subagent-report` user message, and returns the message's stable `MessageId`. Quiet delivery uses `Agent.inject()` and creates no inbox occurrence or parent turn; waking delivery uses `Agent.followup()` and creates one ordinary later parent turn. Neither mode concludes the child's turn, and no final answer reports implicitly.
 
 ```ts type-equiv
 /** Durable attribution for a continuable child's explicit parent report. */
@@ -265,7 +265,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 `SubagentService.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
 
@@ -376,7 +376,7 @@ interface SubagentRun {
 
 A local one-shot run MUST publish an ordinary child agent/session before `start()` fulfills, return that child session id as `SubagentRun.id`, expose the exact child as `localAgent`, record `request.parent.session.id` in the child's `parentSession` header, and append the resolved descriptor inside the child's initial turn before its first request. Runtime ownership may place the child under the parent, provider, or root scope. A remote provider instead returns a parent-scoped lifecycle id and `localAgent: undefined`; without a local child Session, it is absent from durable enumeration.
 
-## The provider seam: `SubagentProvider`
+## The provider contract: `SubagentProvider`
 
 Each provider is a named child-agent transport, and multiple providers may coexist. The service validates requested start-time capabilities before `start()`, and rejects a continuable start on a provider without `prepareContinuable`. `inheritsParentContext` describes only conversation seeding (`fork`: true; `spawn` and `acp`: false), allowing consumers to generate accurate model-facing wording without implying inherited tools, services, or authority.
 
@@ -531,7 +531,7 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 
 /**
  * Enumerate the parent's direct session-backed subagents without loading or
- * resuming an Agent and without any query seam: the listing merges the live
+ * resuming an Agent and without any query service: the listing merges the live
  * session store with optional session persistence (live-preferred) and
  * serves each child's durable mode/label from the registered `subagent`
  * projection unit down a three-rung ladder — the registry's watermark
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 874fbfdb31..7bf3595324 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -4,13 +4,13 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+Service Definition：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。Service provider 是六个兄弟包：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的 Consumer 包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
 ## 两类能力，两种发现方式
 
-提供方通过一个静态描述符公布其**启动时**功能，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的功能，会被明确拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-seam-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider)。
+提供方通过一个静态描述符公布其**启动时**功能，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的功能，会被明确拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-contract-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-contract-subagentprovider)。
 
 ```ts type-equiv
 /**
@@ -191,7 +191,7 @@ interface ContinuableStart {
 
 可选的可继续 child 设置贡献可以在 child 基础组合完成后、Activation 发布前安装限定在作用域内的能力。该注册表按顺序执行且具有事务性：设置失败或被撤销时会回滚未发布的 Activation；child 作用域 dispose 时会释放所有安装；新注册项在下一个 Activation 生效；移除注册项时则会立即撤销每个驻留中的安装。
 
-`SubagentService.reportFrom()` 通过该扩展 seam 实现报告，无需新增第二条队列或承载结果的 child 包装层。调用由确切的在线 child Agent 授权，调用方不能指定接收方。管理器从 child 的持久化 `parentSession` 中推导唯一接收方，要求该 parent Agent 必须在线，将选中内容封装为一条 `subagent-report` 用户消息，并返回该消息的稳定 `MessageId`。静默投递使用 `Agent.inject()`，不产生 inbox 条目实例或 parent 轮次；唤醒投递使用 `Agent.followup()`，会产生一个普通的后续 parent 轮次。两种模式都不会结束 child 轮次，最终回答也不会隐式报告。
+`SubagentService.reportFrom()` 通过该扩展点实现报告，无需新增第二条队列或承载结果的 child 包装层。调用由确切的在线 child Agent 授权，调用方不能指定接收方。管理器从 child 的持久化 `parentSession` 中推导唯一接收方，要求该 parent Agent 必须在线，将选中内容封装为一条 `subagent-report` 用户消息，并返回该消息的稳定 `MessageId`。静默投递使用 `Agent.inject()`，不产生 inbox 条目实例或 parent 轮次；唤醒投递使用 `Agent.followup()`，会产生一个普通的后续 parent 轮次。两种模式都不会结束 child 轮次，最终回答也不会隐式报告。
 
 ```ts type-equiv
 /** Durable attribution for a continuable child's explicit parent report. */
@@ -265,7 +265,7 @@ interface ContinuableCreateSpec {
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -376,9 +376,9 @@ interface SubagentRun {
 
 本地单次 run 必须在 `start()` fulfill 之前发布一个普通子 agent／会话，将该子会话 id 作为 `SubagentRun.id` 返回，以 `localAgent` 暴露确切的子 agent，在子 agent 的 `parentSession` header 中记录 `request.parent.session.id`，并在子 agent 的初始轮次内、首次请求前追加已解析的描述符。运行时所有权可以把子 agent 放在 parent、提供方或 root 作用域下。远程提供方则返回 parent 作用域的生命周期 id 与 `localAgent: undefined`；由于没有本地 child Session，它不会出现在持久化枚举结果中。
 
-<a id="the-provider-seam-subagentprovider"></a>
+<a id="the-provider-contract-subagentprovider"></a>
 
-## 提供方 seam：`SubagentProvider`
+## 提供方约定：`SubagentProvider`
 
 每个提供方都是一个具名的子 agent 传输层，多个提供方可以共存。服务在 `start()` 之前校验请求的启动时能力，并拒绝在没有 `prepareContinuable` 的提供方上发起可继续 start。`inheritsParentContext` 仅描述对话种子注入（`fork`：true；`spawn` 和 `acp`：false），使消费方能生成准确的面向模型措辞，而不暗示继承了工具、服务或权限。
 
@@ -533,7 +533,7 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 
 /**
  * Enumerate the parent's direct session-backed subagents without loading or
- * resuming an Agent and without any query seam: the listing merges the live
+ * resuming an Agent and without any query service: the listing merges the live
  * session store with optional session persistence (live-preferred) and
  * serves each child's durable mode/label from the registered `subagent`
  * projection unit down a three-rung ladder — the registry's watermark
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index 0af3183692..e89be8fdc9 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
-subprocess.md: b501af81dca94025713d46a23a67b543f5df95cd
-subprocess.zh.md: 84b497c90bb5956b0dcb65ca1cb72122b415bd7e
+subprocess.md: eedf95abc2a51872ffc9964481bb3685ace31993
+subprocess.zh.md: 669baa52a92fc3869b057dc802c72989fa8cfcf1
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index b501af81dc..eedf95abc2 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -2,7 +2,7 @@
 
 English | [中文](subprocess.zh.md)
 
-The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
+The subprocess seam is split across a Service Definition ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and Service provider ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its Consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
 
 Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
@@ -242,11 +242,11 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice-abstract-seam).
 
 ## Service behavior
 
-The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
+The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) Service Definition specifies execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) provides them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the Service Definition contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice"></a>
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
 
-### `ctx.subprocess` — `SubprocessService`
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 84b497c90b..669baa52a9 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -2,7 +2,7 @@
 
 [English](subprocess.md) | 中文
 
-进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为 Service Definition（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与 Service provider（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的 Consumer 是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
 源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
@@ -242,11 +242,11 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice-abstract-seam)中。
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) Service Definition 规定执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放提供这些能力。Service Definition 约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice"></a>
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
 
-### `ctx.subprocess` — `SubprocessService`
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index 6f9d3c6861..c229d0a5c0 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.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 docs/subsystems/tasks.md
-tasks.md: f042dfec7438bd2e385cc8c225a3faa171b9ca4f
-tasks.zh.md: bf660a9606f0bc9081532c970e88f249ea0ec4ae
+tasks.md: d3e92891a6736a85519b97775ebe7aa6f12a5ae2
+tasks.zh.md: fe54d7a6482743a8f2ef31b143edb25afe0a478b
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index f042dfec74..d3e92891a6 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -151,7 +151,7 @@ interface TaskRead {
 
 ## Service behavior
 
-The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defines atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local implementation. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the seam contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
+The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local provider. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the Service Definition contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing Consumer.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -161,9 +161,9 @@ The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defin
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice"></a>
+<a id="ctxtasks--taskservice-abstract-seam"></a>
 
-### `ctx.tasks` — `TaskService`
+### `ctx.tasks` — `TaskService` (abstract seam)
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index bf660a9606..fe54d7a648 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -151,7 +151,7 @@ interface TaskRead {
 
 ## 服务行为
 
-抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部提供方。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。Service Definition 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的 Consumer 见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -161,9 +161,9 @@ interface TaskRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice"></a>
+<a id="ctxtasks--taskservice-abstract-seam"></a>
 
-### `ctx.tasks` — `TaskService`
+### `ctx.tasks` — `TaskService` (abstract seam)
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index b53153692f..ec9f0cd48b 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: c9afd276f7c4183db0d1accea2b9aafe71a0e5cc
-telemetry.zh.md: e7ea255a50cace18c7d59b2c77c96bc426d5ee0c
+telemetry.md: c9e51eb38e680723ead0a88f4a9748620fd6b893
+telemetry.zh.md: 1af25c505574db6b3513547ae604eda66fc21766
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index c9afd276f7..c9e51eb38e 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -2,7 +2,7 @@
 
 English | [中文](telemetry.zh.md)
 
-Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/session/session-telemetry/README.md).
+Outbound session reporting is split as a [capability seam](../capability-seams.md): the Service Definition and capture coordinator ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.telemetry`) own the capture points, fixed chunk projection, `telemetry/record` redaction waterfall, handoff cursor, and minimal backend contract; the Service provider a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [Service Definition README](../../packages/session/session-telemetry/README.md).
 
 Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
@@ -22,7 +22,7 @@ type TelemetrySeverity = 'info' | 'warn' | 'error'
 
 ```ts type-equiv
 /**
- * One logical record handed to a backend — the seam's whole outbound
+ * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
  * operational records (`channel: 'ops'`) carry the two signals with no log
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
 
 ## The redact waterfall: `telemetry/record`
 
@@ -119,15 +119,15 @@ Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordi
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry"></a>
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
 
-### `ctx.telemetry` — `Telemetry`
+### `ctx.telemetry` — `Telemetry` (abstract seam)
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
 ```ts cordis-catalog
 /**
- * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
  * @param record - the logical record to report; owned by the backend after the call.
  */
 abstract emit(record: TelemetryRecord): void
@@ -152,12 +152,12 @@ Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/s
 
 #### `telemetry/record` — waterfall
 
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Transform one outbound record before it reaches the backend. This waterfall is the Service Definition's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
 
 ```ts cordis-catalog
 /**
  * Transform one outbound record before it reaches the backend. This
- * waterfall is the seam's redaction extension point. It ships NO rules
+ * waterfall is the Service Definition's redaction extension point. It ships NO rules
  * of its own: the
  * innermost `next()` passes the record through unchanged, and with no
  * listener mounted records reach the backend as captured, so exported
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index e7ea255a50..1af25c5055 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -2,7 +2,7 @@
 
 [English](telemetry.md) | 中文
 
-对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [seam README](../../packages/session/session-telemetry/README.md)。
+对外的会话上报拆分为一项[能力 seam](../capability-seams.md)：Service Definition 与捕获协调器（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的 Service provider（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [Service Definition README](../../packages/session/session-telemetry/README.md)。
 
 源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
@@ -22,7 +22,7 @@ type TelemetrySeverity = 'info' | 'warn' | 'error'
 
 ```ts type-equiv
 /**
- * One logical record handed to a backend — the seam's whole outbound
+ * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
  * operational records (`channel: 'ops'`) carry the two signals with no log
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
@@ -119,15 +119,15 @@ interface TelemetryBackend {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry"></a>
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
 
-### `ctx.telemetry` — `Telemetry`
+### `ctx.telemetry` — `Telemetry` (abstract seam)
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
 ```ts cordis-catalog
 /**
- * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
  * @param record - the logical record to report; owned by the backend after the call.
  */
 abstract emit(record: TelemetryRecord): void
@@ -152,12 +152,12 @@ Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/s
 
 #### `telemetry/record` — waterfall
 
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Transform one outbound record before it reaches the backend. This waterfall is the Service Definition's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
 
 ```ts cordis-catalog
 /**
  * Transform one outbound record before it reaches the backend. This
- * waterfall is the seam's redaction extension point. It ships NO rules
+ * waterfall is the Service Definition's redaction extension point. It ships NO rules
  * of its own: the
  * innermost `next()` passes the record through unchanged, and with no
  * listener mounted records reach the backend as captured, so exported
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index b12daefe88..42f73824cf 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
-tools.zh.md: acdf10a0140e81dada9104653dee92dc9cb6f50d
+tools.md: 87910dfbb86e9db0f0545bc2fe1135c4aefb2e69
+tools.zh.md: d312090b722de3fd1b8efc7703eafdf7f3c38682
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 0551ee1c9d..87910dfbb8 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -362,7 +362,7 @@ On success the registry snapshots and validates the body value, freezes it, and
 
 Before final content, the registry materializes the candidate result; a failure in content, structured error, additional context, or presentation metadata becomes a JSON-safe `isError` result that still reaches `finalizeContent`. The registry invokes that callback exactly once, then materializes and freezes the accepted result immediately before `tools/result`, so the observed live outcome is safe for the later durable `tool/result` append.
 
-Each interception waterfall returns a typed **Decision** (the idiom shared with the `agent/*` seams). `tools/pre-execute` listeners receive `(exec, next)` and return a `PreToolDecision`; `tools/execute` wrappers return a `ToolExecutionResult`; `tools/post-execute` listeners receive `(exec, result, next)` and return a `PostToolDecision`:
+Each interception waterfall returns a typed **Decision** (the idiom shared with the `agent/*` waterfalls). `tools/pre-execute` listeners receive `(exec, next)` and return a `PreToolDecision`; `tools/execute` wrappers return a `ToolExecutionResult`; `tools/post-execute` listeners receive `(exec, result, next)` and return a `PostToolDecision`:
 
 ```ts type-equiv
 /**
@@ -628,12 +628,12 @@ Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/i
 
 #### `tools/post-execute` — waterfall
 
-Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this waterfall as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
 
 ```ts cordis-catalog
 /**
  * Accept, replace, enrich, or block a normalized dispatch result. `next()`
- * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
  * listeners must observe `exec.signal`; after they settle, caller
  * cancellation replaces only a successful accepted outcome with the code
  * selected by whether the tool body was invoked.
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index acdf10a014..d312090b72 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -362,7 +362,7 @@ type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
 
 在得到最终内容之前，注册表会物化候选结果；若内容、结构化错误、附加上下文或展示元数据无法物化，则会转为仍可到达 `finalizeContent` 的 JSON 安全 `isError` 结果。注册表恰好调用该回调一次，随后在 `tools/result` 之前立即物化并冻结已接受的结果，因此实时观察到的产出可安全用于后续持久化的 `tool/result` 追加。
 
-每个拦截 waterfall 返回一个类型化的 **Decision**（与 `agent/*` seam 共享的惯用模式）。`tools/pre-execute` 监听器接收 `(exec, next)` 并返回 `PreToolDecision`；`tools/execute` 包装层返回 `ToolExecutionResult`；`tools/post-execute` 监听器接收 `(exec, result, next)` 并返回 `PostToolDecision`：
+每个拦截 waterfall 返回一个类型化的 **Decision**（与 `agent/*` waterfall 共享的惯用模式）。`tools/pre-execute` 监听器接收 `(exec, next)` 并返回 `PreToolDecision`；`tools/execute` 包装层返回 `ToolExecutionResult`；`tools/post-execute` 监听器接收 `(exec, result, next)` 并返回 `PostToolDecision`：
 
 ```ts type-equiv
 /**
@@ -628,12 +628,12 @@ Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/i
 
 #### `tools/post-execute` — waterfall
 
-Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this waterfall as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
 
 ```ts cordis-catalog
 /**
  * Accept, replace, enrich, or block a normalized dispatch result. `next()`
- * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
  * listeners must observe `exec.signal`; after they settle, caller
  * cancellation replaces only a successful accepted outcome with the code
  * selected by whether the tool body was invoked.
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index b22cd94946..f5e4289b30 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.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 docs/subsystems/web.md
-web.md: f300bf2daef172fe4a69c00f36c804cf874c189d
-web.zh.md: 36afee9a964a0ad185242d5ee8f4f91689b1d295
+web.md: e6dc49353e50181b7844a658008edfa075cfedc3
+web.zh.md: 63f85a8d235e5c0778af8547251ebf2c299f036a
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index f300bf2dae..e6dc49353e 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -2,11 +2,11 @@
 
 English | [中文](web.zh.md)
 
-The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two capabilities** (search and fetch) on one `ctx.web` service, split across packages: interface ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), implementations ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-local](../../packages/web/web-fetch-local)), and consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-implementation swap does not change how the model asks for a URL.
+The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two operations** (search and fetch) on one `ctx.web` service, split across packages: Service Definition ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), Service providers ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-local](../../packages/web/web-fetch-local)), and Consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
 
 Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
 
-## Why one seam for two capabilities
+## Why one capability has two operations
 
 Search and fetch share no request schema and no business logic, but they are deliberately one `ctx.web` middle layer: one provider-selection policy owner, one abort/error vocabulary, one product-facing "how this harness reaches the web" config surface. The cost is the parallel `searchX`/`fetchX` method pairs on the service; that parallelism is intentional, not a missed extraction. Providers register **capabilities** (a `WebSearchProvider` or `WebFetchProvider`), not tools; the model-facing names, schemas, prompt guidance, and presentation all live in the single `dsh-tool-web` consumer.
 
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 36afee9a96..63f85a8d23 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -2,11 +2,11 @@
 
 [English](web.md) | 中文
 
-Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项能力**（search 与 fetch），并拆分到多个包：接口（[dsh-web](../../packages/web/web)，`ctx.web` + 提供方注册表）、实现（[dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-local](../../packages/web/web-fetch-local)）与消费方（[dsh-tool-web](../../packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 实现也不会改变模型请求 URL 的方式。
+Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项操作**（search 与 fetch），并拆分到多个包：Service Definition（[dsh-web](../../packages/web/web)，`ctx.web` + 提供方注册表）、Service provider（[dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-local](../../packages/web/web-fetch-local)）与 Consumer（[dsh-tool-web](../../packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 提供方也不会改变模型请求 URL 的方式。
 
 源码：[`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
 
-## 为什么两项能力合为一个 seam
+## 为什么一项能力包含两项操作
 
 搜索与抓取既不共享请求 schema，也不共享业务逻辑，但它们被有意设计为同一个 `ctx.web` 中间层：一个提供方选择策略的所有者、一套中止与错误词汇，以及一个面向产品的「此 harness 如何访问 Web」配置界面。代价是服务上并行的 `searchX`／`fetchX` 方法对；这种并行是有意为之，而不是遗漏了可抽取的共性。提供方注册的是**能力**（`WebSearchProvider` 或 `WebFetchProvider`），而非工具；面向模型的名称、schema、提示词引导与展示全部集中在唯一的消费方 `dsh-tool-web` 中。
 
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index fed94d62bc..f1ddf20d11 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.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 docs/subsystems/workflow.md
-workflow.md: c87e88f1e1dddcd57822e47e5773dba127f9cdcf
-workflow.zh.md: 57d69ffd5300a6b4d6e037758a75c19e9ccd51a7
+workflow.md: 4c552b31435963d4133a31f2e98f8a913305c1f8
+workflow.zh.md: 53ef84134b00e323bd5331ff30b18012124b5241
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index c87e88f1e1..4c552b3143 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -4,7 +4,7 @@ English | [中文](workflow.zh.md)
 
 The workflow seam — an agent running a model-written orchestration SCRIPT that fans out subagents. Like [subagent](subagent.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). Unlike the subagent registry it takes the bash shape: ONE engine implementation per context provides `ctx.workflows`; there is no named-provider registry (a second engine is a plugin swap, not a co-resident).
 
-Interface: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The implementation is [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md).
+Service Definition: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The Service provider is [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing Consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md).
 
 Source: [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)
 
@@ -139,11 +139,11 @@ The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `wo
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice"></a>
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
 
-### `ctx.workflows` — `WorkflowService`
+### `ctx.workflows` — `WorkflowService` (abstract seam)
 
-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+Workflow Service Definition contract. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 57d69ffd53..53ef84134b 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -4,7 +4,7 @@
 
 工作流 seam 允许 agent（智能体）运行由模型编写的编排脚本，并由该脚本扇出 subagent。与 [subagent](subagent.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此处而非 [core.md](core.md)。与 subagent 注册表不同，它采用 bash 形态：每个上下文只有一个引擎实现提供 `ctx.workflows`；没有命名提供方注册表（第二个引擎是插件替换，而非共存）。
 
-接口：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflows` + 下文词汇）。实现是 [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的消费方是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
+Service Definition：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflows` + 下文词汇）。Service provider 是 [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
 
 源码：[`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)
 
@@ -139,11 +139,11 @@ interface WorkflowRun {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice"></a>
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
 
-### `ctx.workflows` — `WorkflowService`
+### `ctx.workflows` — `WorkflowService` (abstract seam)
 
-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+Workflow Service Definition contract. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 1b94464e30..b2c2248876 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: 21b08bd8b0936e9c7357ad15e7ff4176a981a042
-workspace.zh.md: 30bfc0054880ca82b5f7c64780d405524656a1f1
+workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
+workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 21b08bd8b0..ca088a2091 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -133,9 +133,9 @@ Sessions get their cwd at create time from whoever creates them, not from this r
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker"></a>
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker`
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 30bfc00548..e414c759a0 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -133,9 +133,9 @@ interface Workspace {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker"></a>
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker`
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/docs/user/develop/basic/tool.i18n.yaml b/docs/user/develop/basic/tool.i18n.yaml
index cb9759860e..594e2c2872 100644
--- a/docs/user/develop/basic/tool.i18n.yaml
+++ b/docs/user/develop/basic/tool.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 docs/user/develop/basic/tool.md
-tool.md: 8505bdaf6fcece3235b0302d54e82ee8aed3cbab
-tool.zh.md: c6c579c5da9dc545c2795e65331810528c37219f
+tool.md: ba2f3b1302ba31735d67be264f498a0395394d06
+tool.zh.md: 676f8fc996d752a05d94b55d4522e61e3b3e2161
diff --git a/docs/user/develop/basic/tool.md b/docs/user/develop/basic/tool.md
index 8505bdaf6f..ba2f3b1302 100644
--- a/docs/user/develop/basic/tool.md
+++ b/docs/user/develop/basic/tool.md
@@ -49,4 +49,4 @@ Open `http://127.0.0.1:3080` and ask: `Use the greet tool to greet Ada.` The mod
 
 - [Plugin configuration](./config.md) — make the greeting configurable.
 - [Tool authoring reference](../../../cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, Code Mode, and UI cards.
-- [Capability layering](../practice/) — split a replaceable capability into interface, implementation, and consumer packages.
+- [Capability layering](../practice/) — split a replaceable capability into Service Definition, Service provider, and Consumer packages.
diff --git a/docs/user/develop/basic/tool.zh.md b/docs/user/develop/basic/tool.zh.md
index c6c579c5da..676f8fc996 100644
--- a/docs/user/develop/basic/tool.zh.md
+++ b/docs/user/develop/basic/tool.zh.md
@@ -49,4 +49,4 @@ pnpm run dsh web --patch ./scratch-plugin/cordis.yml
 
 - [插件配置](./config.md) — 让问候语可配置。
 - [工具编写参考](../../../cookbook/adding-a-tool.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、Code Mode 和 UI 卡片。
-- [能力分层](../practice/) — 将可替换能力拆分为接口、实现和消费方包。
+- [能力分层](../practice/) — 将可替换能力拆分为 Service Definition、Service provider 和 Consumer 包。
diff --git a/docs/user/develop/practice/index.i18n.yaml b/docs/user/develop/practice/index.i18n.yaml
index 65057da78e..24ae066e89 100644
--- a/docs/user/develop/practice/index.i18n.yaml
+++ b/docs/user/develop/practice/index.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 docs/user/develop/practice/index.md
-index.md: c3306725f47993aa9d3322423261a260754c1d5f
-index.zh.md: 3609cbce21e17ce9ca0a40b69999b293dee29012
+index.md: 6ae9fd152ca2e3b82bdb1ea9b3aa3d348ebfce66
+index.zh.md: 0056a81402761310fe5f0463b83762d98ed9745f
diff --git a/docs/user/develop/practice/index.md b/docs/user/develop/practice/index.md
index c3306725f4..6ae9fd152c 100644
--- a/docs/user/develop/practice/index.md
+++ b/docs/user/develop/practice/index.md
@@ -1,25 +1,25 @@
-# Three-layer capability design
+# Three-role capability design
 
 English | [中文](index.zh.md)
 
-This page has two parts: a concept reference for the three-layer capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
+This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
 
 ## Concept reference
 
-When a capability is general enough to need replaceable implementations, such as Bash execution, Harness splits it into three packages: an **interface**, an **implementation**, and a **consumer**. Each layer can evolve or be replaced independently.
+When a capability is general enough to need replaceable providers, such as Bash execution, Harness separates three roles: a **Service Definition**, a **Service provider**, and a **Consumer**. Put the roles in separate packages when they need to evolve or be replaced independently; a package may otherwise own more than one role. The complete capability is its seam. No individual role is a seam.
 
 ## Bash example
 
 The Bash execution capability consists of:
 
-- **Interface** (`dsh-bash`) — defines Bash request and result shapes
-- **Implementation** (`dsh-bash-local`) — executes commands on the local machine
+- **Service Definition** (`dsh-bash`) — defines the Cordis service and Bash request/result vocabulary
+- **Service provider** (`dsh-bash-local`) — supplies local command execution
 - **Consumer** (`dsh-tool-bash`) — exposes the capability as a model-callable tool
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
 │  dsh-bash   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│ (interface) │     │ (implementation) │     │(consumer/tool)│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
 └─────────────┘     └──────────────────┘     └──────────────┘
        ▲                                            │
        └────────────────────────────────────────────┘
@@ -28,36 +28,36 @@ The Bash execution capability consists of:
 
 ## Benefits of the split
 
-### Replace implementations
+### Replace providers
 
-One interface can have multiple implementations selected through `cordis.yml`:
+One Service Definition can have multiple providers selected through `cordis.yml`:
 
 ```yaml
 # Local execution
 - name: '@deepseek-ai/dsh-bash-local'
 
-# Replace this row with another package that implements the same service.
+# Replace this row with another package that provides the same service.
 ```
 
-The interface and tool remain unchanged while the implementation changes.
+The Service Definition and tool remain unchanged while the provider changes.
 
 ### Evolve independently
 
-- The interface changes rarely after its contract stabilizes.
-- Implementations can improve performance and security independently.
+- The Service Definition changes rarely after its contract stabilizes.
+- Service providers can improve performance and security independently.
 - Consumers can change how they present the capability to the model.
 
 ### Decouple dependencies
 
-- The implementation depends on the interface.
-- The consumer depends on the interface.
-- The implementation and consumer **do not depend on each other**.
+- The Service provider depends on the Service Definition.
+- The Consumer depends on the Service Definition.
+- The Service provider and Consumer **do not depend on each other**.
 
 The [capability-seam reference](../../../capability-seams.md) owns the current built-in families and package links.
 
-## Tutorial: develop a three-layer capability
+## Tutorial: develop a three-role capability
 
-### Step 1: define the interface
+### Step 1: write the Service Definition
 
 ```ts ignore-check
 // packages/my-cap/my-cap/src/index.ts
@@ -87,7 +87,7 @@ export interface MyCapResult {
 }
 ```
 
-### Step 2: write an implementation
+### Step 2: write a Service provider
 
 ```ts ignore-check
 // packages/my-cap/my-cap-local/src/index.ts
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
 
 class MyCapLocal extends MyCapService {
   async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Concrete implementation.
+    // Local provider behavior.
     return { output: request.input.toUpperCase() }
   }
 }
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
 
 ## Design points
 
-- **Do not split preemptively** — use three packages only when the capability needs replaceable implementations. A simple tool plugin does not.
-- **The interface owns Request/Result types** — implementations and consumers depend only on the interface package.
+- **Do not split preemptively** — use separate packages only when the roles need to evolve independently. A simple tool plugin does not.
+- **The Service Definition owns Request/Result types** — Service providers and Consumers depend only on the Service Definition package.
 - **Explicit > implicit** — resolve defaults in an explicit `resolve(request): Spec` step rather than hiding `?? default` expressions inside `run()`.
 
 ## Next steps
 
-- [LLM adapter](./llm-adapter.md) — implement an LLM backend, a common capability interface extension
+- [LLM adapter](./llm-adapter.md) — implement an LLM provider
diff --git a/docs/user/develop/practice/index.zh.md b/docs/user/develop/practice/index.zh.md
index 3609cbce21..0056a81402 100644
--- a/docs/user/develop/practice/index.zh.md
+++ b/docs/user/develop/practice/index.zh.md
@@ -1,25 +1,25 @@
-# 能力的三层拆分
+# 能力的三种角色设计
 
 [English](index.md) | 中文
 
-本文分为两部分：先参考三层能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
+本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
 
 ## 概念参考
 
-当一项能力足够通用，需要支持可替换的实现时（例如 Bash 执行），Harness 会将其拆成三个包：**接口**、**实现**和**消费方**。这样便可独立替换其中任何一层。
+当一项能力足够通用，需要支持可替换的提供方时（例如 Bash 执行），Harness 会区分三种角色：**Service Definition**、**Service provider** 和 **Consumer**。角色需要独立演进或替换时，将它们放入不同包；否则一个包可以承担多个角色。完整能力构成其 seam。任何单一角色都不是 seam。
 
 ## 以 Bash 为例
 
 以 Bash 执行能力为例：
 
-- **接口** (`dsh-bash`)：定义 Bash 请求和结果的结构
-- **实现** (`dsh-bash-local`)：在本地计算机上执行命令
-- **消费方** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
+- **Service Definition** (`dsh-bash`)：定义 Cordis 服务以及 Bash 请求／结果词汇
+- **Service provider** (`dsh-bash-local`)：提供本地命令执行
+- **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
 │  dsh-bash   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│ (interface) │     │ (implementation) │     │(consumer/tool)│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
 └─────────────┘     └──────────────────┘     └──────────────┘
        ▲                                            │
        └────────────────────────────────────────────┘
@@ -28,36 +28,36 @@
 
 ## 拆分的好处
 
-### 具体实现可替换
+### 提供方可替换
 
-同一个接口可以有多种实现。用户通过 `cordis.yml` 选择：
+同一个 Service Definition 可以有多个提供方。用户通过 `cordis.yml` 选择：
 
 ```yaml
 # Local execution
 - name: '@deepseek-ai/dsh-bash-local'
 
-# Replace this row with another package that implements the same service.
+# Replace this row with another package that provides the same service.
 ```
 
-更换实现时，接口和工具均保持不变。
+更换提供方时，Service Definition 和工具均保持不变。
 
 ### 独立演进
 
-- 接口定义稳定后很少改动
-- 实现可以独立优化（性能、安全）
-- 消费方可以调整能力向模型呈现的方式。
+- Service Definition 的约定稳定后很少改动
+- Service provider 可以独立优化性能和安全性
+- Consumer 可以调整能力向模型呈现的方式。
 
 ### 依赖解耦
 
-- 实现依赖接口。
-- 消费方依赖接口。
-- 实现和消费方**互不依赖**。
+- Service provider 依赖 Service Definition。
+- Consumer 依赖 Service Definition。
+- Service provider 和 Consumer **互不依赖**。
 
 当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.md)负责。
 
-## 教程：开发三层能力
+## 教程：开发三种角色的能力
 
-### 第一步：定义接口
+### 第一步：编写 Service Definition
 
 ```ts ignore-check
 // packages/my-cap/my-cap/src/index.ts
@@ -87,7 +87,7 @@ export interface MyCapResult {
 }
 ```
 
-### 第二步：编写实现
+### 第二步：编写 Service provider
 
 ```ts ignore-check
 // packages/my-cap/my-cap-local/src/index.ts
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
 
 class MyCapLocal extends MyCapService {
   async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Concrete implementation.
+    // Local provider behavior.
     return { output: request.input.toUpperCase() }
   }
 }
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
 
 ## 设计要点
 
-- **不要预防性拆分**：只有确实需要可替换实现时，才拆分为三个包。简单的工具插件无需拆分。
-- **接口拥有 Request/Result 类型**：实现和消费方只依赖接口包。
+- **不要预防性拆分**：只有角色需要独立演进时，才使用不同包。简单的工具插件无需拆分。
+- **Service Definition 拥有 Request/Result 类型**：Service provider 和 Consumer 只依赖 Service Definition 包。
 - **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
 
 ## 下一步
 
-- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 后端，这是一种常见的能力 seam 扩展
+- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 提供方
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 10e4f2429b..d54550f499 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
+config.md: 3ce797e3dc91a279de1076a234c9ba0b476b3501
 config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 34ab38c60c..3ce797e3dc 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -64,4 +64,4 @@ The tag is `!!js`, not `!js`.
 
 ## Exact configuration reference
 
-The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability interfaces](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it.
+The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability seams](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it.
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 62a1a674d5..b0b646eade 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -398,7 +398,7 @@ const SCENARIOS: Scenario[] = [
   // the real Loader/app path, rather than retaining the earlier valid group.
   { name: 'hook-cc-invalid-matcher', hasModelTurn: true, recorded: false },
   { name: 'hook-codex-invalid-matcher', hasModelTurn: true, recorded: false },
-  // The mid-turn seams fire during a real model turn, so each is recorded with its hook active
+  // The mid-turn interception points fire during a real model turn, so each is recorded with its hook active
   // (the model's reaction to a deny/block/force-continue is part of the captured transcript).
   // SessionStart/SubagentStart are excluded because detached injection races log
   // order; SubagentStop writes no transcript, so an expected output could not prove it ran.
diff --git a/native/landlock-run/AGENTS.md b/native/landlock-run/AGENTS.md
index 6742ff81d4..29bf66fa9d 100644
--- a/native/landlock-run/AGENTS.md
+++ b/native/landlock-run/AGENTS.md
@@ -18,10 +18,10 @@ The project is pre-1.0. Prefer the correct public shape over compatibility shims
 ## Repository layout
 
 ```text
-packages/entry/     Published entry package: JS seam (resolve/probe/grants) + the C source.
+packages/entry/     Published entry package: JavaScript API (resolve/probe/grants) + the C source.
 packages/linux-*/   Published per-platform packages: one prebuilt static binary, no JavaScript.
 scripts/            Build, matrix derivation, prepack gates, and release orchestration.
-test/               Plain-node behavioral tests (entry seam + real-kernel launcher proofs).
+test/               Plain-node behavioral tests (entry API + real-kernel launcher proofs).
 docs/               Architecture, packaging, CLI contract, release, support matrix, naming.
 ```
 
diff --git a/native/landlock-run/docs/architecture.md b/native/landlock-run/docs/architecture.md
index 458281bf29..33c71d6893 100644
--- a/native/landlock-run/docs/architecture.md
+++ b/native/landlock-run/docs/architecture.md
@@ -1,6 +1,6 @@
 # Architecture
 
-This repository owns confinement *mechanism*, not policy: consumers (agent harnesses, sandbox seams) decide which paths a run may read or write; this package family provides the launcher that enforces those grants and the JS seam that resolves and speaks to it. The packaging follows the per-platform-package model of [`node-addon-require-builtin`](https://www.npmjs.com/package/@esplus/node-addon-require-builtin) (and esbuild), adapted from Node addons to standalone static executables.
+This repository owns confinement *mechanism*, not policy: consumers (agent harnesses and sandbox capabilities) decide which paths a run may read or write; this package family provides the launcher that enforces those grants and the JavaScript API that resolves and speaks to it. The packaging follows the per-platform-package model of [`node-addon-require-builtin`](https://www.npmjs.com/package/@esplus/node-addon-require-builtin) (and esbuild), adapted from Node addons to standalone static executables.
 
 ## Two-layer package family
 
diff --git a/native/landlock-run/packages/entry/src/index.ts b/native/landlock-run/packages/entry/src/index.ts
index ec909f928a..2bb0699381 100644
--- a/native/landlock-run/packages/entry/src/index.ts
+++ b/native/landlock-run/packages/entry/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The JS seam over the prebuilt `landlock-run` launcher: resolve the
+ * The JavaScript API over the prebuilt `landlock-run` launcher: resolve the
  * binary for this host, build its grant argv, and run its functional probe.
  *
  * This module owns the launcher's CLI contract (`docs/cli-contract.md`) so
@@ -61,7 +61,7 @@ export interface LauncherGrants {
  * deliberately not checked either way: {@link probe} is the single
  * availability signal (a missing binary probes `unusable` the same way an
  * unenforcing kernel does).
- * @param resolvePackageJson - test seam over `require.resolve` (the default
+ * @param resolvePackageJson - test hook over `require.resolve` (the default
  *   covers real installs); receives the platform package's `package.json`
  *   specifier and returns its absolute path, throwing when unresolvable.
  * @returns the absolute launcher path to probe and exec.
diff --git a/native/landlock-run/test/entry.test.js b/native/landlock-run/test/entry.test.js
index 2b535559a2..76e2e4321a 100644
--- a/native/landlock-run/test/entry.test.js
+++ b/native/landlock-run/test/entry.test.js
@@ -1,6 +1,6 @@
 /**
  * Keyless entry-package tests — run on every host, no kernel or binary
- * required. Cover the JS seam's pure surface: grant-argv construction, the
+ * required. Cover the JavaScript API's pure surface: grant-argv construction, the
  * resolution contract (platform package → fallback), and probe verdicts over
  * fake launchers. Requires built `lib/` (`pnpm build:ts`).
  */
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 58db577ee5..6cff1b6327 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -7,7 +7,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 - **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Initiator-owned private chains derive, then capture.** Under `ctx.agents.withInitiator()`, recover the Agent at each orchestration entry, derive `agent.session`, and let operation-local helpers close over it. Keep `Agent` and `Session` explicit at lifecycle, session-log, service, authority, worker/process, persistence, and wire interfaces; do not widen a leaf helper from `Session` to `Context` merely to hide a parameter ([rationale](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.
-- **Shape capability interfaces around all current consumers.** Keep tool-schema, Loader, UI, transport, and backend-specific behavior in the consumer or adapter; do not let one consumer dictate the interface ([capability-seam rationale](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). Inverse smell: a public service method with one internal caller — pass a private capability closure instead (`RunCodeBridgeOptions`).
+- **Shape Service Definitions around all current Consumers.** Keep tool-schema, Loader, UI, transport, and provider-specific behavior in the Consumer or provider; do not let one Consumer dictate the service contract ([capability-seam rationale](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). Inverse smell: a public service method with one internal caller — pass a private capability closure instead (`RunCodeBridgeOptions`).
 - **Require a current owner and need.** Tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer, and keep behavior in its owning plugin or service.
 - **Require evidence for public choices.** Configurability does not justify an unsupported default, public operation set, format, or imported external concept. Use current-consumer evidence or relevant prior art; otherwise require an explicit value or defer the choice.
 - **Write model-facing contracts from the model's perspective.** Prompts, tool schemas, results, and diagnostics contain only task-relevant concepts, not UI, transport, or implementation vocabulary. Pin stable model-visible text verbatim and dynamic behavior through snapshots or end-to-end coverage.
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 25b3709d91..27f5c79ca4 100644
--- 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: 7589f37b174b94558bff9f74f860bb4b42705fb8
-README.zh.md: e7b8b0ab2b5bb5bd38d7068091bc675e1d27f84a
+README.md: eff1d9522e3ca6e8a7efaa20463d73036101f8f5
+README.zh.md: cc2d37d3999e2e59095a8000feb3f963d0b4e4a1
diff --git a/packages/README.md b/packages/README.md
index 7589f37b17..eff1d9522e 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -17,19 +17,19 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
 | [`e2b/`](e2b/README.md) | E2B providers | POC |
-| [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
+| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
-| [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
+| [`compact/`](compact/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer | Product — stable surface |
 | [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable surface |
-| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
+| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry contract and the model-facing delegation tool | Product — stable surface |
 | [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
-| [`workflow/`](workflow/README.md) | Script seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable surface |
+| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
 | [`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 |
@@ -61,6 +61,6 @@ New packages join existing groups; new groups update their README and this table
 
 The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
 
-**Extension plugins depend on interfaces, never the concrete loop.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities split into interface / implementation / consumer packages; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
+**Extension plugins depend on Service Definitions, never concrete providers.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities separate Service Definition / Service provider / Consumer roles when they evolve independently; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
 
 Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
diff --git a/packages/README.zh.md b/packages/README.zh.md
index e7b8b0ab2b..cc2d37d399 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -17,19 +17,19 @@
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定接口 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定接口 |
 | [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
-| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定接口 |
+| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：Service Definition + 本地进程树提供方 | 产品：稳定接口 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定接口 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定接口 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定接口 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：Service Definition + worker 线程提供方 + Code Mode Consumer | 产品：稳定接口 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定接口 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定接口 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定接口 |
 | [`skill/`](skill/README.md) | skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定接口 |
-| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定接口 |
+| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：Service Definition + 基础提供方 + 命令 Consumer | 产品：稳定接口 |
 | [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定接口 |
-| [`subagent/`](subagent/README.md) | subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定接口 |
+| [`subagent/`](subagent/README.md) | subagent 能力系列：提供方注册表约定和面向模型的委托工具 | 产品：稳定接口 |
 | [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定接口 |
-| [`workflow/`](workflow/README.md) | 脚本 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定接口 |
+| [`workflow/`](workflow/README.md) | 工作流 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定接口 |
 | [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定接口 |
 | [`spill/`](spill/README.md) | spill 能力系列：存储 seam、本地实现、工具结果 spill 策略 | 产品：稳定接口 |
 | [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定接口 |
@@ -61,6 +61,6 @@
 
 依赖图由工具生成：[docs/module-graph.md](../docs/module-graph.md)（`pnpm run gen-module-graph`，CI 中有新鲜度门禁）。
 
-**扩展插件依赖接口，绝不依赖具体循环。** `dsh-agent-loop` 可替换；UI、钩子和工具插件使用 `dsh-agent`。包括 `dsh-agent-spine-demo` 在内的组合包可以依赖主干插件。能力拆分为接口／实现／消费方包；详见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)。
+**扩展插件依赖 Service Definition，绝不依赖具体提供方。** `dsh-agent-loop` 可替换；UI、钩子和工具插件使用 `dsh-agent`。包括 `dsh-agent-spine-demo` 在内的组合包可以依赖主干插件。能力在 Service Definition／Service provider／Consumer 角色需要独立演进时将其分离；详见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)。
 
 包 README 覆盖用途、API、扩展点和[模型体验](../docs/cookbook/adding-a-package.md#4-write-the-package-readme)；列入模型无关[省略允许清单](../scripts/verify-package-readme-model-experience.ts)的包除外。它们还要包含 `## Known Limitations and Deferred Work`，或使用其[允许清单](../scripts/verify-package-readme-limitations.ts)。
diff --git a/packages/bash/README.i18n.yaml b/packages/bash/README.i18n.yaml
index a55672b9e1..7860ae302e 100644
--- 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: 7395a051742af24b96842966b71297dc01853dca
-README.zh.md: 043394f429d406a6d14f00b6d8a0384bd022abe0
+README.md: edffdd67a982a885b7e3e537be77c8971f5b697b
+README.zh.md: 8cb56f38df4999cb2055b9e2808ce092bc7a8282
diff --git a/packages/bash/README.md b/packages/bash/README.md
index 7395a05174..edffdd67a9 100644
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -6,7 +6,7 @@ The capability family spans the canonical executor seam, its implementations, th
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`bash/`](bash/README.md) | Defines the executor contract shared by implementations and consumers. | `ctx.bash` |
+| [`bash/`](bash/README.md) | Defines the executor contract shared by Service providers 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`) |
diff --git a/packages/bash/README.zh.md b/packages/bash/README.zh.md
index 043394f429..8cb56f38df 100644
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-该能力家族涵盖规范的执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
+该能力家族涵盖规范执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`bash/`](bash/README.md) | 定义实现与消费方共享的执行器约定。 | `ctx.bash` |
+| [`bash/`](bash/README.md) | 定义 Service provider 与 Consumer 共享的执行器约定。 | `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` |
+| [`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`） |
 
diff --git a/packages/bash/bash-local/README.i18n.yaml b/packages/bash/bash-local/README.i18n.yaml
index a33f59641e..aa5f35a125 100644
--- 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: cb40cb8fa40d95d5b4589b7c804f450a2bf38c8e
-README.zh.md: bd4f73babdb47ff92e87e20eb7d60657ed515ec4
+README.md: cb8e7f0ae766d9b1c5f1678e77d35992085d3d52
+README.zh.md: 20af9c18998c6f3f0403c50f3a8ac599607dc094
diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md
index cb40cb8fa4..cb8e7f0ae7 100644
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.subprocess`, and owns everything bash-shaped — command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
+Local Service provider for the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.subprocess`, and owns everything bash-shaped — command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
 
 The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`.
 
diff --git a/packages/bash/bash-local/README.zh.md b/packages/bash/bash-local/README.zh.md
index bd4f73babd..20af9c1899 100644
--- a/packages/bash/bash-local/README.zh.md
+++ b/packages/bash/bash-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`@deepseek-ai/dsh-bash` 执行器 seam 的本地实现，构建在 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务之上：`LocalBashExecutor` 每次调用都通过 `ctx.subprocess` 把 `bash -c <command>` 作为受管进程组 spawn，并负责所有 Bash 层职责（命令默认值补全与上限、超时与取消分类、适合模型的终端环境，以及后台读取时面向模型的 stdout/stderr 合并）。以 spill 文件兜底的有界输出、凭据清除、kill 升级和 dispose（资源释放）等进程组机制则由 subprocess 服务负责。
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 Service provider，构建在 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务之上：`LocalBashExecutor` 每次调用都通过 `ctx.subprocess` 把 `bash -c <command>` 作为受管进程组 spawn，并负责所有 Bash 层职责（命令默认值补全与上限、超时与取消分类、适合模型的终端环境，以及后台读取时面向模型的 stdout/stderr 合并）。以 spill 文件兜底的有界输出、凭据清除、kill 升级和 dispose（资源释放）等进程组机制则由 subprocess 服务负责。
 
 包根目录导出默认与具名的 `LocalBashExecutor` 插件及其 `Config`。
 
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index ccb5a32aa8..3d3ca833bc 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * Local implementation of the bash executor seam over the subprocess
- * seam. Public commands run as `bash -c` in a managed process group spawned
+ * Local Service provider for the bash capability seam over the subprocess
+ * capability 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
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index 426f2901e5..0df4d4067a 100644
--- 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: 884681ec73990af600833756caf5dd7305b0d481
-README.zh.md: a19b4cae4606a56ae5ce496fa9f0c10ba2eb9156
+README.md: 44321d7ef26e9e4399438f61b3fdfbfa2e4d8c11
+README.zh.md: f3e110c049871a5a6121716307aaa3d1d1f3eedb
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 884681ec73..44321d7ef2 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -2,7 +2,7 @@
 
 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.
+Sandbox-consuming Service provider for 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`; result-classification helpers stay internal.
 
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index a19b4cae46..f3e110c049 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是使用沙箱能力的 [`@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` 能力并添加升权字段。
+这是使用沙箱能力的 [`@deepseek-ai/dsh-bash`](../bash/) 执行器 seam Service provider。加载它时，应**用它替代** `@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 保留在内部。
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 72bd7650be..597a17e088 100644
--- 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: e142a796e94dab4ecaa67b8dfce0be4f554f26c0
-README.zh.md: 24a44b418a675d863551642f2edb1f655a2705ab
+README.md: 1230149bd03d07cfb6208d82ea6ee8e81751b2c8
+README.zh.md: 168ac9f40e01dc786e29933afb0ebc4c3a745d0f
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index e142a796e9..1230149bd0 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -4,16 +4,16 @@ English | [中文](README.zh.md)
 
 The **`BashExecutor`** (`ctx.bash`) defines WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
 
-This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
+This package owns the Service Definition role of the bash capability, split so each role can evolve (and be swapped) independently:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-bash` (this) | the interface: abstract service + vocabulary types |
-| `@deepseek-ai/dsh-bash-local` | an implementation: local subprocesses |
-| `@deepseek-ai/dsh-bash-sandbox` | an implementation: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
+| `@deepseek-ai/dsh-bash` (this) | Service Definition: abstract service + vocabulary types |
+| `@deepseek-ai/dsh-bash-local` | Service provider: local subprocesses |
+| `@deepseek-ai/dsh-bash-sandbox` | Service provider: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
 | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |
 
-The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same interface; the consumer detects its `sandboxMode` capability and adds escalation fields without importing the implementation. A containerized or remote executor slots in the same way.
+The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same Service Definition; the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider. A containerized or remote executor slots in the same way.
 
 ## Service API (`ctx.bash`)
 
@@ -35,7 +35,7 @@ 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.
+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 with the Service Definition so the two tools never drift on the marker contract.
 
 ## Model Experience
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 24a44b418a..168ac9f40e 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -4,16 +4,16 @@
 
 **`BashExecutor`**（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
 
-本包是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：
+本包承担 bash 能力的 Service Definition 角色，各角色因此可以独立演进（和替换）：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-bash`（本包） | 接口：抽象服务 + 词汇类型 |
-| `@deepseek-ai/dsh-bash-local` | 实现：本地子进程 |
-| `@deepseek-ai/dsh-bash-sandbox` | 实现：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
+| `@deepseek-ai/dsh-bash`（本包） | Service Definition：抽象服务 + 词汇类型 |
+| `@deepseek-ai/dsh-bash-local` | Service provider：本地子进程 |
+| `@deepseek-ai/dsh-bash-sandbox` | Service provider：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
 | `@deepseek-ai/dsh-tool-bash` | 基于 `ctx.bash`、面向模型的工具 schema |
 
-该拆分与 LLM（大语言模型） seam（`LlmService`／`LlmAdapter`）及 agent（智能体）工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一接口之后；消费方检测其 `sandboxMode` 能力并添加升权字段，无需导入实现。容器化或远程执行器也可以同样接入。
+该拆分与 LLM（大语言模型） seam（`LlmService`／`LlmAdapter`）及 agent（智能体）工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一 Service Definition 之后；Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方。容器化或远程执行器也可以同样接入。
 
 ## 服务 API（`ctx.bash`）
 
@@ -35,7 +35,7 @@
 
 `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 约定不会发生偏离。
+导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的另一半：`dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 追加的 `[exit code: N]`／`[killed by signal: X]` marker 的逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与其退出状态 pill；它放在 Service Definition 中，两个工具便永远不会在 marker 约定上漂移。
 
 ## 模型体验
 
diff --git a/packages/bash/bash/src/index.ts b/packages/bash/bash/src/index.ts
index 904c427ed0..73f3d7b519 100644
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The `ctx.bash` executor seam for foreground commands and background process
+ * Service Definition for the `ctx.bash` capability seam, covering foreground commands and background process
  * handles. Task ids, ownership, polling, and notices belong to
  * `@deepseek-ai/dsh-tasks`, keeping executors independent of sessions.
  * @module @deepseek-ai/dsh-bash
diff --git a/packages/bash/bash/src/invariant.ts b/packages/bash/bash/src/invariant.ts
index f54f280f5d..acf00f48a4 100644
--- a/packages/bash/bash/src/invariant.ts
+++ b/packages/bash/bash/src/invariant.ts
@@ -10,7 +10,7 @@ export const name = 'bash-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: this stateless seam owns request/result types, while executors and policy own observations. */
+/** No runtime invariant: this stateless Service Definition owns request/result types, while executors and policy own observations. */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index a3b4ec3597..4f25e9f6aa 100644
--- 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: 3e38ea3830cb651a80eaee744a42f68891767358
-README.zh.md: d84a4ef4c94cd266bbb8f19bd21d7517016c50d5
+README.md: a06126e29ac5bf711bfbbb0d369e097b70918ba6
+README.zh.md: 947e994b59539d137cc1a332bb252a8325533747
diff --git a/packages/bash/pwsh-local/README.md b/packages/bash/pwsh-local/README.md
index 3e38ea3830..a06126e29a 100644
--- a/packages/bash/pwsh-local/README.md
+++ b/packages/bash/pwsh-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local PowerShell implementation of the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `PwshLocalExecutor` spawns `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` per call as a managed process through `ctx.subprocess`, and owns everything PowerShell-shaped — executable resolution, command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
+Local PowerShell Service provider for the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `PwshLocalExecutor` spawns `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` per call as a managed process through `ctx.subprocess`, and owns everything PowerShell-shaped — executable resolution, command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
 
 The command string rides as ONE argv element to `-Command`: PowerShell itself parses the text, and no intermediate shell exists, so there is no shell-quoting layer to escape (the `bash -c` string domain has no equivalent here). Native Win32 paths (`C:\...`) pass through unchanged.
 
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index d84a4ef4c9..947e994b59 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell 实现，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell Service provider，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
 
 命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（这里不存在与 `bash -c` 字符串域对应的层）。原生 Win32 路径（`C:\...`）原样通过。
 
diff --git a/packages/bash/pwsh-local/src/index.ts b/packages/bash/pwsh-local/src/index.ts
index 20ecffd969..f654ea45ed 100644
--- a/packages/bash/pwsh-local/src/index.ts
+++ b/packages/bash/pwsh-local/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Local PowerShell implementation of the bash executor seam. Each command runs
+ * Local PowerShell Service provider for the bash capability seam. Each command runs
  * as `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` in a managed
  * process spawned through `ctx.subprocess`; the executor owns command
  * defaulting, deadlines and cause classification, the model-friendly terminal
@@ -279,7 +279,7 @@ export class PwshLocalExecutor extends BashExecutor {
    * Settlement hook for subclasses that attach execution facts to a process.
    * The base implementation is intentionally empty. Mirrored from
    * `dsh-bash-local` (whose sandboxing subclass consumes the same hook); it is
-   * the declared seam for a future pwsh-confining subclass and has no consumer
+   * the protected extension point for a future pwsh-confining subclass and has no consumer
    * in this package yet.
    * @param _proc - the settled process handle.
    * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index e5eb0dfc41..40c218e528 100644
--- 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: 47101e1198d13518c3d82877df8726c1fbf26b82
-README.zh.md: c7e0b3ffdc02705bbbd6fd6bd9b8cce2548445f3
+README.md: 9e2cd0c2ed999a11dcbffcd99a1d0cb672367905
+README.zh.md: 8a1e7ba0af36ffd891b38491075ee75283fdbed5
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index 47101e1198..9e2cd0c2ed 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The model-facing `bash` tool registered over the `ctx.bash` executor seam. Foreground execution stays behind that seam; a background process handle is registered with the generic `ctx.tasks` runtime and controlled through `task_output`, `task_list`, and `task_kill` from `@deepseek-ai/dsh-tool-tasks`.
 
-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.
+Requires a loaded executor Service provider (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 package-internal.
 
@@ -24,7 +24,7 @@ The plugin also contributes the `tool:bash` prompt section (order 105): check th
 | `sandbox_permissions` | string enum | ADVERTISED ONLY when the mounted executor sandboxes (`ctx.bash.sandboxMode` reports a confining default): the wider mode a denied command needs, from the closed target vocabulary `workspace-write`/`danger-full-access` (never cut down to the executor's default — the effective mode is per-session; strict widening is checked at execution against it, and a non-widening request fails without prompting anyone). |
 | `justification` | string | Required together with `sandbox_permissions` (each without the other is a validation error): one sentence for the user explaining why this exact command needs the wider access. |
 
-`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. When sandbox policy is present, the tool reuses its already-canonical `workspaceRoot` as the workdir base so confinement and process launch cannot resolve the same session spelling differently.
+`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the Service Definition (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. When sandbox policy is present, the tool reuses its already-canonical `workspaceRoot` as the workdir base so confinement and process launch cannot resolve the same session spelling differently.
 
 ### Managed shell environment
 
@@ -42,7 +42,7 @@ The tool owns its `presentCall`/`presentResult` render intent. A foreground call
 
 ## The tool builds its request from named args only
 
-The `BashExecRequest` seam carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `dshEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `dshEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `DSH_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+`BashExecRequest` carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `dshEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `dshEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `DSH_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 
 ## Permissions and escalation
 
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index c7e0b3ffdc..8a1e7ba0af 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -4,7 +4,7 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具约定是 bash 方言——请挂载能解析 bash 的执行器。
+需要加载执行器 Service provider（例如 `@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`）；结果渲染和后台进程适配仍保留在包内部。
 
@@ -24,7 +24,7 @@
 | `sandbox_permissions` | string enum | 仅当已挂载的执行器启用沙箱时才会公开（`ctx.bash.sandboxMode` 报告一个具有限制作用的默认值）：被拒命令所需的更宽模式，取自封闭的目标词汇 `workspace-write`/`danger-full-access`（绝不能缩减为执行器默认值；有效模式按会话确定，执行时会基于它检查是否严格拓宽，未拓宽的请求直接失败，不会向任何人发起提示）。 |
 | `justification` | string | 必须与 `sandbox_permissions` 一同提供（缺少任一项都会产生验证错误）：用一句话向用户解释此命令为何需要这项更宽权限。 |
 
-执行前，`command`、`workdir` 和 `timeoutMs` 会通过 `ctx.bash.resolve()` 依据执行器配置默认值完成解析，因此执行器 seam（`BashExecSpec`）收到显式的 `workdir`/`timeoutMs` 值。工具层会根据调用方 agent 的 `session.header.cwd` 应用工作目录默认值，然后才调用 `resolve()`：由于 N 个会话共享一个执行器，逐会话 cwd 必须来自 `exec.agent`；只有无法取得会话 cwd 时，执行器才回退到自身配置／`process.cwd()`。存在沙箱策略时，工具会复用已经规范化的 `workspaceRoot` 作为工作目录基准，防止限制逻辑与进程启动过程对同一个会话路径拼写产生不同解析结果。
+执行前，`command`、`workdir` 和 `timeoutMs` 会通过 `ctx.bash.resolve()` 依据执行器配置默认值完成解析，因此 Service Definition（`BashExecSpec`）收到显式的 `workdir`/`timeoutMs` 值。工具层会根据调用方 agent 的 `session.header.cwd` 应用工作目录默认值，然后才调用 `resolve()`：由于 N 个会话共享一个执行器，逐会话 cwd 必须来自 `exec.agent`；只有无法取得会话 cwd 时，执行器才回退到自身配置／`process.cwd()`。存在沙箱策略时，工具会复用已经规范化的 `workspaceRoot` 作为工作目录基准，防止限制逻辑与进程启动过程对同一个会话路径拼写产生不同解析结果。
 
 ### 托管 shell 环境
 
@@ -42,7 +42,7 @@
 
 ## 工具仅使用具名参数构建请求
 
-`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)。
+`BashExecRequest` 携带可选的 `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)。
 
 ## 权限与升权
 
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 91a88c9cca..adbfd88851 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Model-facing `bash` tool over the `ctx.bash` executor seam. Background calls
+ * Model-facing Consumer of the `ctx.bash` capability seam. Background calls
  * register process handles with `ctx.tasks`; their work uses task cancellation
  * rather than the tool-call signal after an id is returned.
  *
@@ -155,7 +155,7 @@ function resolveWorkdir(
   return modelWorkdir
 }
 
-/** Detach the executor DTO from readonly seam interfaces into plain JSON data. */
+/** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
 function canonicalBashResult(result: BashRunResult) {
   const output = (stream: BashRunResult['stdout']) => ({
     text: stream.text,
diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts
index 69c641a06d..99510dc6e5 100644
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -19,7 +19,7 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
 
 /**
  * Full-loop integration: a scripted mock model drives the REAL bash tool
- * through the agent loop, exercising the same seams a live model would
+ * through the agent loop, exercising the same execution paths a live model would
  * (tool/call + tool/result session events, the generic `ctx.tasks` runtime,
  * agent.inject completion notices).
  */
diff --git a/packages/bash/tool-pwsh/src/background.ts b/packages/bash/tool-pwsh/src/background.ts
index 5e3464f76b..b245006a4d 100644
--- a/packages/bash/tool-pwsh/src/background.ts
+++ b/packages/bash/tool-pwsh/src/background.ts
@@ -20,7 +20,7 @@ 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
+  // sandbox.runnerFailed to task `failed`. The current contract 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`.
   if (proc.status === 'killed') {
diff --git a/packages/bash/tool-pwsh/src/index.ts b/packages/bash/tool-pwsh/src/index.ts
index a68d5d2e35..8f30de893c 100644
--- a/packages/bash/tool-pwsh/src/index.ts
+++ b/packages/bash/tool-pwsh/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Model-facing `pwsh` tool over the `ctx.bash` executor seam. Intended for
+ * Model-facing PowerShell Consumer of the `ctx.bash` capability seam. Intended for
  * Windows compositions where a PowerShell executor (e.g.
  * `@deepseek-ai/dsh-pwsh-local`) backs `ctx.bash`; the tool contract is
  * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
@@ -112,7 +112,7 @@ function resolveWorkdir(modelWorkdir: string | undefined, exec: { agent?: Agent
   return modelWorkdir
 }
 
-/** Detach the executor DTO from readonly seam interfaces into plain JSON data. */
+/** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
 function canonicalPwshResult(result: BashRunResult): PwshForegroundResult {
   const output = (stream: BashRunResult['stdout']) => ({
     text: stream.text,
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index 1e71f3e8a7..d951a87cf0 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -208,10 +208,10 @@ function ensureSymlink(link: string, target: string): void {
  * directory after the profile's own `node_modules`, so every in-box plugin
  * resolves without pnpm ever managing it — the exact "bundles come from the
  * installation" contract. The closure (not just direct dependencies) is
- * required for out-of-tree plugins: their peer dependencies name seam
- * packages (`dsh-compact`, `dsh-invariants`, ...) that the app reaches only
- * through its implementation packages. Symlinked packages resolve their own
- * dependencies from their real directories (Node's default
+ * required for out-of-tree plugins: their peer dependencies name Service
+ * Definition packages (`dsh-compact`, `dsh-invariants`, ...) that the app
+ * reaches only through its Service provider packages. Symlinked packages
+ * resolve their own dependencies from their real directories (Node's default
  * symlink-following), so each package needs only its one flat link.
  * Idempotent: correct links are kept and moved installations are
  * re-pointed; a stale link to a vanished package stays until its name is
@@ -231,7 +231,7 @@ export function healProfilesModuleFallback(installAnchor: string, home: string =
   // map itself (first resolution wins, matching Node's own nearest-wins).
   const queue: { anchor: string; manifest: ProfileManifest }[] = [{ anchor: installAnchor, manifest: appManifest }]
   for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
-    // Peer dependencies participate: seam packages (dsh-subprocess,
+    // Peer dependencies participate: Service Definition packages (dsh-subprocess,
     // dsh-compact, ...) are peers of their implementations, never plain
     // dependencies, yet out-of-tree plugins import them directly.
     /* v8 ignore next -- a real app manifest always declares dependencies */
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index 2a1dfc271c..2ded85f25b 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: fbdf80be3d587b0ef526c1a36952a761035f7312
-README.zh.md: fa1b5ac280eb9020d71035cc6b09ab2508bff45d
+README.md: f8b76b77f2beb22f501a49f0fc4cf5cd72223765
+README.zh.md: aae8ab5bea663b8909de942f72615f5ef9b16c84
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index fbdf80be3d..f8b76b77f2 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
 
-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
@@ -17,4 +17,4 @@ None; the runner adds nothing to the request prefix.
 ## Known Limitations and Deferred Work
 
 - **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
-- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.
+- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the hook.
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index fa1b5ac280..aae8ab5bea 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -4,7 +4,7 @@
 
 dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
 
-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
@@ -17,4 +17,4 @@ Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/a
 ## 已知限制与延期工作
 
 - **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
-- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该 seam。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该钩子。
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index b817642be8..9a85b02cba 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -101,7 +101,7 @@ function resolveDistIndex(): string {
   }
 }
 
-/** Test seam: hosts with no built frontend dist substitute the resolver; production never touches this. */
+/** Test hook: hosts with no built frontend dist substitute the resolver; production never touches this. */
 export const internals: { resolveDistIndex: () => string } = { resolveDistIndex }
 
 /**
diff --git a/packages/bundle/web-app/tests/web-app.spec.ts b/packages/bundle/web-app/tests/web-app.spec.ts
index a4e300b08b..c73f9817db 100644
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Web runtime glue behavior: dist resolution through the bundle's own seam,
+ * Web runtime glue behavior: dist resolution through the bundle's own hook,
  * 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.
@@ -184,7 +184,7 @@ describe('web-app runtime glue', () => {
   })
 
   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 production resolver (not the test hook). 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.
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index d534e5bb83..78704f52fa 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -22,7 +22,7 @@ How live data reaches render code, and what may cross a business boundary:
 
 1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
 2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
-3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework seam and needs main-thread arbitration.
+3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
 4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are grandfathered and get migrated to slots progressively).
 5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
 6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 57d4c4c75c..5e2d35f4e8 100644
--- 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: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
-README.zh.md: 731daa15c8944febae1712788a9ae017d4756960
+README.md: dba01cb8c487dbc670a471053f8cd12dd277ef4c
+README.zh.md: d12ef605f1113411a59c2d73c2bf105dfb021be8
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index 161e34c4b6..dba01cb8c4 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
 
 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 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. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. 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.
+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` abstraction, 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. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. 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
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 731daa15c8..d12ef605f1 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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 浏览器信任栅栏
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index c373376710..fbf995e652 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -1,7 +1,7 @@
 // Central contract re-export point: every contract import inside
 // web-runtime goes through this single file.
 // Types and runtime protocol helpers/bounds come from the apiproxy api/ layer
-// (zero Node deps, browser-safe); AbstractApiClient is the client seam.
+// (zero Node deps, browser-safe); AbstractApiClient is the client boundary.
 // NEVER import the package root: it drags bootHost/cordis into the browser bundle.
 // The ./api and ./client subpath exports are the browser-safe channels added for this.
 
diff --git a/packages/client/locale/src/client/index.ts b/packages/client/locale/src/client/index.ts
index 5d195ee275..795388c5fd 100644
--- a/packages/client/locale/src/client/index.ts
+++ b/packages/client/locale/src/client/index.ts
@@ -172,7 +172,7 @@ export class LocaleService {
    * the typed form: each dictionary is checked against the namespace's
    * {@link LocaleNamespaceMap} key union (a missing or extra key is a
    * compile error), and every shipped locale is required (bilingual balance
-   * enforced at the seam). Duplicate (ns, locale) throws (single occupant; a
+   * enforced at registration). Duplicate (ns, locale) throws (single occupant; a
    * namespace's texts have one owner). Registration bumps the revision so
    * mounted outlets pick up late-arriving dictionaries.
    * @param ns - a namespace merged into LocaleNamespaceMap.
diff --git a/packages/client/locale/tests/locale.spec.ts b/packages/client/locale/tests/locale.spec.ts
index 442701dbb3..7e9a7802e1 100644
--- a/packages/client/locale/tests/locale.spec.ts
+++ b/packages/client/locale/tests/locale.spec.ts
@@ -60,7 +60,7 @@ describe('LocaleService', () => {
     expect(t('own')).toBe('自有')
     // common itself must not recurse: a miss inside common echoes the key.
     // (Wide-string ns hits the untyped bind overload — the typed one rejects
-    // unknown keys at compile time, which is the point of the seam.)
+    // unknown keys at compile time, which is the point of the typed registry contract.)
     expect(svc.bind('common' as string)('nope')).toBe('nope')
   })
 
diff --git a/packages/client/modules/README.i18n.yaml b/packages/client/modules/README.i18n.yaml
index 2f7278eae2..86d87df60f 100644
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/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/modules/README.md
-README.md: 7d661c806955d0fac021dd6620994aab83c0f773
-README.zh.md: aec59474fbf01857380709ebecb6ae99a6ca8174
+README.md: 1d327c7252f4b3001ad758b7a4db01e9907c3060
+README.zh.md: a97672b909c98367e8c1287e3b341fb612f2d110
diff --git a/packages/client/modules/README.md b/packages/client/modules/README.md
index 7d661c8069..1d327c7252 100644
--- a/packages/client/modules/README.md
+++ b/packages/client/modules/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` as its `internal` seam — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
+Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` through its `internal` contract — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
 
 Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
 
diff --git a/packages/client/modules/README.zh.md b/packages/client/modules/README.zh.md
index aec59474fb..a97672b909 100644
--- a/packages/client/modules/README.zh.md
+++ b/packages/client/modules/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并把该包（package）的 `ClientModuleLoader` 作为其 `internal` seam 注入；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
+客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并通过其 `internal` 约定注入该包（package）的 `ClientModuleLoader`；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
 
 惰性 CJS 模型（web2）：执行插件组合包只会注册其 factory（`window.__ModuleLoader__.load({id, factory})`）；每个模块主体的副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出表层，并在 `loadCache` 中记忆化），不会在脚本执行时运行。如果 factory 依赖另一个已注册但尚未物化的模块，系统会递归物化它，因此加载顺序无需外部编排；require 循环会抛出异常（factory 形式的 CJS 无法提供部分导出）。`<id>/client` 与裸 id 指向同一表层（一个插件组合包就是其包的客户端侧）。
 
diff --git a/packages/client/modules/src/client/manifest.ts b/packages/client/modules/src/client/manifest.ts
index 20e2bcf1bd..ff7a7d8692 100644
--- a/packages/client/modules/src/client/manifest.ts
+++ b/packages/client/modules/src/client/manifest.ts
@@ -1,7 +1,7 @@
 /**
  * Client module system: the browser peer of Node's internal ESM loader, built
  * as a lazy CJS table. The vendored cordis Loader consumes this object
- * through its `internal` seam (the only call site is `EntryTree.import` →
+ * through its `internal` contract (the only call site is `EntryTree.import` →
  * `internal.import`), which keeps entry governance (fiber lifecycle, inject
  * waiting, update/refresh) entirely on the vendored side while this package
  * owns code arrival.
@@ -25,7 +25,7 @@
  * imports are a build error anyway.
  *
  * This file is the browser-safe contract face (zero node imports): the
- * `__DSH_BOOT__` wire types, the boot-manifest parser, and the seams around
+ * `__DSH_BOOT__` wire types, the boot-manifest parser, and the boundaries around
  * {@link ClientModuleSystem}. The package root is the host-side service that
  * composes the wire.
  */
@@ -170,7 +170,7 @@ export interface DshWindow {
   __DSH_MODULES__?: ClientModuleSystem
 }
 
-/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph seam, flat today). */
+/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph boundary, flat today). */
 export interface ClientModuleRecord {
   /** Module id (entry name / package name). */
   id: string
@@ -178,12 +178,12 @@ export interface ClientModuleRecord {
   surface: unknown
   /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
   styles: string[]
-  /** Observed `require()` edges (module-graph seam; only table words can appear today). */
+  /** Observed `require()` edges (module-graph boundary; only table words can appear today). */
   edges: Set<string>
 }
 
 /**
- * The internal-seam subset the vendored Loader and the client HMR plugin
+ * The internal-contract subset the vendored Loader and the client HMR plugin
  * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
  * as `ctx.modules` (contract C5).
  */
@@ -193,12 +193,12 @@ export interface ClientModuleLoader {
   /** Materialized-module registry: id → record. The governance-side read face for entry export surfaces. */
   loadCache: Map<string, ClientModuleRecord>
   /**
-   * Internal seam consumed by the vendored Loader's `tree.import`. Resolves
+   * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
    * `specifier` through the branch order documented on the module, fetching
    * and executing a bundle when needed.
    * @param specifier - module specifier (entry name or table word).
    * @param parentURL - importer URL (unused — the client module graph is flat).
-   * @param attrs - import attributes (unused; interface parity with Node's seam).
+   * @param attrs - Import attributes (unused; interface parity with Node's loader contract).
    * @returns the module's export surface.
    */
   import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
@@ -232,6 +232,6 @@ export interface ClientModuleSystemOptions {
   modules: BootModuleRow[]
   /** Module-table seed: platform-singleton specifier → shell instance. */
   staticModules: Record<string, unknown>
-  /** Bundle-load seam. Defaults to a same-origin classic `<script src>` element. */
+  /** Bundle-load hook. Defaults to a same-origin classic `<script src>` element. */
   loadBundle?: (url: string) => Promise<void>
 }
diff --git a/packages/client/modules/src/client/system.ts b/packages/client/modules/src/client/system.ts
index f9044d2c2d..5a6b11bb1e 100644
--- a/packages/client/modules/src/client/system.ts
+++ b/packages/client/modules/src/client/system.ts
@@ -1,6 +1,6 @@
 /**
  * ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
- * seam. The conceptual contract (lazy CJS model, resolution branch order) is
+ * contract. The conceptual contract (lazy CJS model, resolution branch order) is
  * documented on the public interfaces in `./manifest.ts`; this file owns the
  * state tables and the load/materialize machinery.
  */
@@ -9,7 +9,7 @@ import type {
   ClientModuleSystemOptions, ClientPluginHandoff, DshWindow,
 } from './manifest.ts'
 
-/** Default bundle-load seam: same-origin external classic script. */
+/** Default bundle-load hook: same-origin external classic script. */
 const defaultLoadBundle = (url: string): Promise<void> => new Promise((resolve, reject) => {
   const el = document.createElement('script')
   el.async = true
@@ -53,7 +53,7 @@ const claimStyles = (id: string): string[] => {
 /**
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
- * seam contract docs). Construction indexes the boot rows and installs the
+ * contract documentation). Construction indexes the boot rows and installs the
  * `window.__ModuleLoader__` registration sink (contract C6) — once per page.
  */
 export class ClientModuleSystem implements ClientModuleLoader {
@@ -72,7 +72,7 @@ export class ClientModuleSystem implements ClientModuleLoader {
 
   /**
    * Build the module system over the parsed boot rows.
-   * @param options - module rows, module-table staticModules, and bundle-load seam.
+   * @param options - Module rows, module-table staticModules, and bundle-load hook.
    */
   constructor(options: ClientModuleSystemOptions) {
     this.seed = new Map(Object.entries(options.staticModules))
diff --git a/packages/client/modules/tests/loader.spec.ts b/packages/client/modules/tests/loader.spec.ts
index 4c41419cd8..bd3c5601e3 100644
--- a/packages/client/modules/tests/loader.spec.ts
+++ b/packages/client/modules/tests/loader.spec.ts
@@ -4,7 +4,7 @@
  * registers the factory), materialization on first import/require with
  * memoization and recursive self-sequencing, the resolution branch order,
  * shared in-flight arrival, invalidate-refetch (HMR), style claiming, the
- * default transport seam, and the loud failure modes (duplicate
+ * default transport hook, and the loud failure modes (duplicate
  * registration, cycles, table misses, double boot).
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 641898424e..e1c07abae3 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: 08a45adc441cc2f672e84dea38d0991537187a1f
-README.zh.md: 7abf86aee015a7108547a0025ca8ba5beceecfb2
+README.md: bd8528e97b04d5b4b28922266306969e8f19295a
+README.zh.md: 9aea486fb17c5a170ee8c1195435d220b495b615
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 08a45adc44..bd8528e97b 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -36,7 +36,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 ## The human transcript
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the Service Definition's declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
 Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 7abf86aee0..9aea486fb1 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -8,7 +8,7 @@
 
 `ctx.slots.inject(name, callback)` 将完整的 `SlotMap` key 作为贡献项的依赖，适用于贡献方插件可独立于声明条目激活的情形。声明存在时，它会同步运行 `callback`，否则等待；声明折叠会 dispose（资源释放）回调 effect，重新声明则会再次运行回调。控制器归调用方的插件 fiber 所有，因此卸载贡献方会取消等待或移除其活跃注册项。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常。
 
-回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的注册项，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的 effect，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ## Workspace 与 Session 列表
 
@@ -18,7 +18,7 @@ Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线
 
 `WorkspacesService.delete(workspaceId)` 在一元响应成功后从客户端投影中移除注册记录；对应的 `host/workspace-removed` 帧具有幂等性，并负责同步其他标签页。Session 状态与当前 Session selection 相互独立，因此 Workspace 消失后，其已纳入客户端投影的 Session 会立即投影到 Ungrouped 下。
 
-`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影扫描在当前 selection 落入归档集合时将其清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
+`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影层在当前 selection 落入归档集合时统一清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
 
 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建钩子。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
 
@@ -36,7 +36,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在 Service Definition 的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
 由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
@@ -54,7 +54,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 模型重试投影
 
-Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括对计时器、整数、状态、提供方延迟和非空诊断字段的约束。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
+Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
 
 ## 会话 fork
 
@@ -62,7 +62,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 ## 会话模型选择
 
-每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前 `ModelSelection`、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前选择，打开选择器会刷新目录；选择失败会保留上一个选择和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的选择，同时不替换未变化的选择子结构。
+每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。
 
 ## 模型体验
 
@@ -70,7 +70,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 #### KV Cache 影响
 
-更改模型选择可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
+更改目标可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts
index 2af2ef51c8..3e74510dd8 100644
--- a/packages/client/runtime/src/client/contract/sessions.ts
+++ b/packages/client/runtime/src/client/contract/sessions.ts
@@ -100,7 +100,7 @@ export interface ISessions {
    */
   scope(id: SessionId): AgentContext | undefined
   /**
-   * Read the Agent scope tag off a context (service-method seam: fetch
+   * Read the Agent scope tag off a context (service-method boundary: fetch
    * bundles must reach scope resolution through ctx.sessions).
    * @param ctx - any client context.
    * @returns the session id, or undefined on root contexts.
diff --git a/packages/client/runtime/src/client/sessions/projection-store.ts b/packages/client/runtime/src/client/sessions/projection-store.ts
index 32401146af..1af9ad726e 100644
--- a/packages/client/runtime/src/client/sessions/projection-store.ts
+++ b/packages/client/runtime/src/client/sessions/projection-store.ts
@@ -12,7 +12,7 @@ import type { ObservableSnapshot } from '../contract/store.ts'
 import { Notifier } from './notifier.ts'
 
 // The single projection type table, typed end to end (host unit, wire block,
-// client store, React hook) — the interface package's pure-type outlet
+// client store, React hook) — the Service Definition package's pure-type outlet
 // (`/types`, zero imports), never the package root: the root's dsh-agent →
 // dsh-session chain would drag the host `Context.sessions` merge into the
 // client program (one program must not hold both sides). No second
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index 621760df02..64eeaf91d7 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -488,7 +488,7 @@ export class SessionsService implements ISessions {
   }
 
   /**
-   * Read the Agent scope tag off a context. Service-method seam: fetch
+   * Read the Agent scope tag off a context. Service-method boundary: fetch
    * bundles must reach scope resolution through ctx.sessions — a cross-bundle
    * value import of the standalone helper would inline a second module
    * instance whose private tag Symbol never matches.
@@ -503,7 +503,7 @@ export class SessionsService implements ISessions {
    * Resolve the business Session behind an Agent-scoped context — the one
    * hop every scoped consumer (event listeners, per-session controllers)
    * takes from ctx-space into object-space (the client mirror of host
-   * `agent.session`). Same service-method seam as
+   * `agent.session`). Same service-method boundary as
    * {@link SessionsService.scopeOf}.
    * @param ctx - an Agent-scoped context.
    * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
@@ -590,7 +590,7 @@ export class SessionsService implements ISessions {
       ctx,
       binding,
       session,
-      // Sources are bare observables; React binds selector hooks at its own seam.
+      // Sources are bare observables; React binds selector hooks at its own boundary.
       provideInfo: this.provideChannel.materializeInfo(binding),
     }
     this.scopes.set(id, record)
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index aee51d3dc2..0813c02711 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -198,7 +198,7 @@ export class Session implements SessionFace {
   /**
    * Bind the Agent-scoped context minted by SessionsService (single write;
    * a second bind is a wiring error and throws). Direction stays one-way at
-   * the seam: consumers still reach the Session via `sessions.sessionOf`,
+   * this binding boundary: consumers still reach the Session via `sessions.sessionOf`,
    * while the Session holds its own dispatch point (host Agent.loopCtx
    * mirror).
    * @param actx - the agent's scoped context.
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index e9e1c1d8d6..78090ce87f 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -12,7 +12,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 // browser bundle cannot resolve; surface.ts has no Node dependencies.
 import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-// Cordis-free leaf subpath (the dsh-commands/brand shape): the seam's own
+// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
 // declaration of the checkpoint source, reachable as a TYPE from this program.
 // The package ROOT is not — it reaches dsh-session's root, whose Context merge
 // declares the HOST `sessions: SessionStore` against this program's
@@ -28,7 +28,7 @@ import type { AssistantStepMetadata } from './assistant-timing.ts'
 import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
 
 /**
- * The compaction seam's checkpoint plugin, pinned to the seam's own declaration
+ * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
  * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
  * import stays type-only because a value import would fail the client purity
  * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index 9da8755b2d..a30adb4dd6 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -4,7 +4,7 @@
  * the load-time validations, and the unload cascade). This layer owns what
  * needs the runtime: the 'slots/changed' event bridge, register and
  * declaration injection through the caller's ctx.effect (fiber unload
- * collects both), the renderer install seam (install()/renderSlot('root') +
+ * collects both), the renderer installation contract (install()/renderSlot('root') +
  * the SlotRendererHost face), and the store INSTANCE axis — handle x scope
  * key -> create/cache, dropped with the last holding entry, session instances
  * cleared (with persisted state) on scope death.
diff --git a/packages/client/runtime/src/client/workspaces/workspace.ts b/packages/client/runtime/src/client/workspaces/workspace.ts
index afa4dd65b6..e1e280d1c6 100644
--- a/packages/client/runtime/src/client/workspaces/workspace.ts
+++ b/packages/client/runtime/src/client/workspaces/workspace.ts
@@ -59,7 +59,7 @@ export class Workspace implements ObservableSnapshot<WorkspaceSnapshot> {
   }
 
   /**
-   * Materialize this local Workspace through the Host create seam.
+   * Materialize this local Workspace through the Host create API.
    * Re-entry shares the in-flight completion; a materialized instance returns undefined.
    * @returns the Host result, or undefined when this Workspace is already materialized.
    */
diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
index aed658af51..1f969c5121 100644
--- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
+++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
@@ -1,12 +1,12 @@
 /**
  * Behavioral half of the compaction-checkpoint drift trap.
  *
- * `TranscriptAdapter` pins its plugin literal to the seam's own declaration at
+ * `TranscriptAdapter` pins its plugin literal to the Service Definition's declaration at
  * compile time through a type-only import of `dsh-compact/checkpoint`, so
- * renaming the seam's plugin already fails `tsc`. This spec covers the same
+ * renaming the Service Definition's plugin already fails `tsc`. This spec covers the same
  * drift from the other side — end to end through the adapter, driving it with a
  * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` value and
- * checking the seam's own predicate agrees. Both values come from the
+ * checking the Service Definition's predicate agrees. Both values come from the
  * cordis-free checkpoint leaf, so the client test program never loads the host
  * package root or its `Context` merges.
  */
@@ -17,7 +17,7 @@ import { describe, expect, it } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
 
-/** A replacement user message stamped with the seam's own canonical source. */
+/** A replacement user message stamped with the Service Definition's canonical source. */
 function canonicalCheckpoint(seq: number): SessionEvent {
   return {
     type: 'user/message',
@@ -43,7 +43,7 @@ describe('compaction checkpoint recognition', () => {
   })
 
   it("agrees with the seam's own predicate on the source it recognizes", () => {
-    // Both sides answer the same question about the same value: if the seam
+    // Both sides answer the same question about the same value: if the Service Definition
     // renames its plugin, this equality is what breaks.
     const checkpoint = canonicalCheckpoint(1)
     expect(checkpoint.type === 'user/message' && isCompactCheckpointSource(checkpoint.data.source)).toBe(true)
diff --git a/packages/client/runtime/tests/projection-store.spec.ts b/packages/client/runtime/tests/projection-store.spec.ts
index 143da92348..6547d365f5 100644
--- a/packages/client/runtime/tests/projection-store.spec.ts
+++ b/packages/client/runtime/tests/projection-store.spec.ts
@@ -14,7 +14,7 @@ import { SessionManager } from '../src/client/sessions/manager.ts'
 import { FakeApiClient, ok } from './fake-api.ts'
 import { entries, plainTurn } from './event-script.ts'
 
-// Test-domain keys merged into the projection map (the interface package's
+// Test-domain keys merged into the projection map (the Service Definition package's
 // pure-type outlet), the same way domain host plugins merge theirs.
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionMap {
diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts
index f8968926c1..0b8ce8a301 100644
--- a/packages/client/runtime/tests/slots-service.spec.ts
+++ b/packages/client/runtime/tests/slots-service.spec.ts
@@ -1,8 +1,8 @@
 /**
  * SlotsService terminal-design account (design.md §11-3 main landing):
  * built-in 'root', the three load-time throws (duplicate declaration /
- * undeclared contribution / cross-scope store handle), the renderer install
- * seam (double install / not installed / non-root key), store instance
+ * undeclared contribution / cross-scope store handle), the renderer installation
+ * contract (double install / not installed / non-root key), store instance
  * resolution and lifecycle on the ledger axis, and the entry-unload cascade.
  */
 import { Context } from 'cordis'
@@ -92,13 +92,13 @@ function captureHost(bench: Bench, children?: object): SlotRendererHost {
   return host
 }
 
-/** Minimal independent Workspace list source for the renderer host seam. */
+/** Minimal independent Workspace list source for the renderer host contract. */
 function fakeWorkspaces() {
   const state = { items: [], phase: 'ready' as const }
   return { list: { getSnapshot: () => state, subscribe: () => () => undefined } }
 }
 
-/** Minimal sessions face for the host seam (list observable + current provide projection). */
+/** Minimal sessions face for the host contract (list observable + current provide projection). */
 function fakeSessions() {
   const state = { ids: [], byId: {}, current: undefined as string | undefined }
   const absentInfo = { sessionId: undefined, hooks: { session: undefined }, props: {} }
diff --git a/packages/client/schema-form/README.i18n.yaml b/packages/client/schema-form/README.i18n.yaml
index 9dfa981a3f..9c24cc754c 100644
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/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/schema-form/README.md
-README.md: 716cc7ba3c24f3a4de081e2d26f803b905235fac
-README.zh.md: 9473620da83e73f7a095694b2321f1ebc5f9c53d
+README.md: ef1d2f9d8ce936fe60d38849f975dc8c0a08ded4
+README.zh.md: aff77bc4c31a9aaa13977480d32551536ddceadd
diff --git a/packages/client/schema-form/README.md b/packages/client/schema-form/README.md
index 716cc7ba3c..ef1d2f9d8c 100644
--- a/packages/client/schema-form/README.md
+++ b/packages/client/schema-form/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Schema/draft model layer for settings editors. The wire's `settings.describe` carries each namespace's serialized schemastery schema (`schema.toJSON()` ref envelope); `rehydrateSchema` turns it back into a live validator with `new Schema(json)` — the same schema object that validates a section on the host validates drafts in the browser, so client-side validation never drifts from the seam's. Editors render their own controls (the Models page hand-writes its card around the fields it probes here); this package owns no React and no rendering.
+Schema/draft model layer for settings editors. The wire's `settings.describe` carries each namespace's serialized schemastery schema (`schema.toJSON()` ref envelope); `rehydrateSchema` turns it back into a live validator with `new Schema(json)` — the same schema object that validates a section on the host validates drafts in the browser, so client-side validation never drifts from the Service Definition's. Editors render their own controls (the Models page hand-writes its card around the fields it probes here); this package owns no React and no rendering.
 
 ## Contract
 
diff --git a/packages/client/schema-form/README.zh.md b/packages/client/schema-form/README.zh.md
index 9473620da8..aff77bc4c3 100644
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 seam 侧的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包不含任何 React，也不做任何渲染。
+面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 Service Definition 的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包不含任何 React，也不做任何渲染。
 
 ## 约定
 
diff --git a/packages/client/test-runtime/src/index.ts b/packages/client/test-runtime/src/index.ts
index 5ef5350434..3005c061e7 100644
--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -40,7 +40,7 @@ export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fix
 export { makeTranslate } from './translate.ts'
 export { usePinnedBrowserLanguages } from './locale-env.ts'
 
-/** Erased register face for the internal root call (the public declare seam holds the typing). */
+/** Erased register face for the internal root call (the public declaration contract holds the typing). */
 type ErasedRegister = (options: object, component: unknown) => () => void
 
 /**
@@ -80,7 +80,7 @@ export interface FeatureHandle {
 /**
  * Owner-props cell behind the auto frame: one external store the frame
  * subscribes to, so {@link SlotTestRuntime.renderSlot} and
- * {@link SlotView.update} drive React through the standard uSES seam.
+ * {@link SlotView.update} drive React through the standard uSES boundary.
  */
 class OwnerPropsCell {
   private readonly owners = new Map<string, object>()
@@ -146,7 +146,7 @@ export class TestRoot {
   ): Promise<void> {
     await this.stabilize(() => {
       // Erased hop (same pattern as SlotsService's own implementation arm);
-      // the declare signature above is the typed seam.
+      // the declaration signature above is the typed contract.
       this.disposeEntry = (this.slots.register as unknown as ErasedRegister)({ name: 'root', children }, frame)
     })
   }
@@ -267,7 +267,7 @@ export class SlotTestRuntime {
 
   /**
    * Render the root slot tree through the ctx-level entry (the shell's own
-   * seam): `ctx.slots.renderSlot('root', {})` under Testing Library.
+   * entry point): `ctx.slots.renderSlot('root', {})` under Testing Library.
    * @returns the Testing Library view.
    */
   renderRoot(): RenderResult {
diff --git a/packages/client/test-runtime/src/sessions.ts b/packages/client/test-runtime/src/sessions.ts
index 4747929572..f700cb4ba1 100644
--- a/packages/client/test-runtime/src/sessions.ts
+++ b/packages/client/test-runtime/src/sessions.ts
@@ -368,7 +368,7 @@ export class TestSessions implements ISessions {
   }
 
   /**
-   * Read the session scope tag off a context (service-method seam mirror).
+   * Read the session scope tag off a context (service-method boundary mirror).
    * @param ctx - any client context.
    * @returns the session id, or undefined on root contexts.
    */
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 341a3409c3..2066b22ec5 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: 58c8dc68758ddae11966195c42cf324e388cfc47
-README.zh.md: f60b89c0ac378f5a87bb49194465fd8bc65d7c42
+README.md: 911bca28dcfb31b1d8ef9ea5458a0d2017d8b31d
+README.zh.md: 25574421bbcc3992188e378a49a69acf25744af7
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 58c8dc6875..911bca28dc 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -40,7 +40,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
-A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
+A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` contract — an absent service leaves the prose inert.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index f60b89c0ac..25574421bb 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -40,7 +40,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
-完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` seam——service 缺席时正文保持死文本。
+完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` 约定——service 缺席时正文保持死文本。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 2d42aef367..0e486e9154 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -363,7 +363,7 @@ export function apply(ctx: Context): void {
   ctx.plugin(todoDockEntry)
 
   // The read-only queue dock entry (T9 file territory) rides the same
-  // registration seam into the input dock declared above.
+  // registration path into the input dock declared above.
   ctx.plugin(queueDockEntry)
 
   slots.register({
diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts
index 79516d04fa..3c6d1fd0fb 100644
--- a/packages/client/ui-conversation/src/client/input/facade.ts
+++ b/packages/client/ui-conversation/src/client/input/facade.ts
@@ -25,7 +25,7 @@ export interface PopupDismissFace {
 }
 
 /**
- * Construction seams of one facade. The slash/popup faces are THUNKS: the
+ * Construction dependencies of one facade. The slash/popup faces are THUNKS: the
  * shell is created inside the sessions provide materialization (before the
  * scope record is queryable), where `slash.sessionOf`/`command.popupFor`
  * cannot resolve yet — resolution defers to first interactive use.
diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
index 8a301d03ff..35dac88ffd 100644
--- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
+++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
@@ -214,7 +214,7 @@ export function QueueDock({ useSession, updateQueue, notify, t }: QueueDockProps
 
 /**
  * The dock entry as a plain registrant plugin. The conversation service is
- * the action seam; the slot declaration is its independent lifecycle seam.
+ * the action contract; the slot declaration has an independent lifecycle boundary.
  */
 export const queueDockEntry = {
   name: 'conversation-queue-dock',
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index c47b726b66..aae5bb4818 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -6,7 +6,7 @@
  * table's relevant cells + the real SessionInput machine (scoped-event
  * listeners wired the way the hub does) + the real InputBar. ui-command
  * itself is not a dependency of this package; the source below is the
- * decision-table contract at the SlashSource seam.
+ * decision-table contract at the `SlashSource` boundary.
  */
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-conversation/tests/selection-survival.spec.tsx b/packages/client/ui-conversation/tests/selection-survival.spec.tsx
index 07e9ad0c79..d7c701d6ae 100644
--- a/packages/client/ui-conversation/tests/selection-survival.spec.tsx
+++ b/packages/client/ui-conversation/tests/selection-survival.spec.tsx
@@ -95,7 +95,7 @@ describe('selection survives on the store seat', () => {
     doomed.actions.select({ turnSeq: 1 })
     expect(localStorage.getItem('dsh.conversation.chat.s1')).not.toBeNull()
 
-    // TestSessions.remove drives the same public slot lifecycle seam the
+    // TestSessions.remove drives the same public slot lifecycle contract the
     // production SessionsService calls when the scope dies (pruneStoreScope).
     await b.runtime.sessions.remove('s1')
 
diff --git a/packages/client/ui-layout/src/client/index.ts b/packages/client/ui-layout/src/client/index.ts
index bb78596a0b..8050cb0916 100644
--- a/packages/client/ui-layout/src/client/index.ts
+++ b/packages/client/ui-layout/src/client/index.ts
@@ -3,7 +3,7 @@
  * the runtime's built-in 'root' slot and, in the same breath, declares the
  * four child slots (declaration = exclusive render authority), seats the
  * layout store (panel geometry), and wires the panel-action service face.
- * ctx.layout is the cross-plugin panel-action seam; navigation state lives
+ * ctx.layout is the cross-plugin panel-action contract; navigation state lives
  * with the runtime sessions service. A second effect seats the theme
  * presenter, which projects ctx.theme snapshots onto document.body.
  */
diff --git a/packages/client/ui-layout/src/client/service.ts b/packages/client/ui-layout/src/client/service.ts
index ecfd862a03..b1fae0b494 100644
--- a/packages/client/ui-layout/src/client/service.ts
+++ b/packages/client/ui-layout/src/client/service.ts
@@ -3,7 +3,7 @@
  * Panel geometry itself lives in the root entry's layout store (stores.ts);
  * the current-session selection lives with the runtime sessions service, and
  * the per-session active view dissolved into ui-conversation's session store
- * (its only consumer). What remains here is the seam other plugins'
+ * (its only consumer). What remains here is the contract other plugins'
  * apply worlds reach for panel transitions (sidebar toggle from ui-sidebar,
  * details open/close from ui-conversation) — writes stay inside the store's
  * declared action set, delivered as the registration's bound actions.
diff --git a/packages/client/ui-layout/tests/service.spec.ts b/packages/client/ui-layout/tests/service.spec.ts
index c7c9cca5ba..1a309d83e5 100644
--- a/packages/client/ui-layout/tests/service.spec.ts
+++ b/packages/client/ui-layout/tests/service.spec.ts
@@ -1,7 +1,7 @@
 /**
  * LayoutService behavior: the cross-plugin panel-action face. Geometry
  * lives in the entry store (layout-store.spec.ts) — here we assert the
- * delegation seam: attachPanels wiring, the three actions forwarding, the
+ * delegation contract: attachPanels wiring, the three actions forwarding, the
  * unwired fail-loud, and re-attach overwriting a stale action set.
  */
 import { describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index e630daf0fa..c1449560d5 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/ui-model/README.md
-README.md: b37f807944850fb34331cd8d78b4a2ccf157f21c
-README.zh.md: 906096bed06af26517e215b2d1e1da4b62e58095
+README.md: 519429834f214fcb82eeb692378fb79770fa30be
+README.zh.md: 116e151d1afeaaa22618c408eed2c7542d1357e7
diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md
index b37f807944..519429834f 100644
--- a/packages/client/ui-model/README.md
+++ b/packages/client/ui-model/README.md
@@ -8,7 +8,7 @@ The Host-reported provider/model/reasoning `ModelSelection` is the single select
 
 When the Host reports that no adapter serves the session's route (`session.models.routable`), this plugin raises a composer block through `ctx.conversation.blocks` and the input goes inert with this plugin's own copy; recovering clears it without a reload. It follows `routable` and nothing else: a `null` — before the first load, or after one failed — never blocks, or a slow Host would lock a working composer, and catalog membership never blocks either, because a route serving a model it stopped advertising is missing from the groups yet perfectly usable. The trigger's own `Select model` fallback still covers that case, which is display, not a gate.
 
-Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. Addressed subagent sessions expose neither entry, and their directory rejects loads, selections, and reconnect refreshes, because ordinary Agent-bound model RPCs would activate persisted child history outside the direct-parent continuation seam.
+Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. Addressed subagent sessions expose neither entry, and their directory rejects loads, selections, and reconnect refreshes, because ordinary Agent-bound model RPCs would activate persisted child history outside the direct-parent continuation path.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state shape, and the seat's injected face type.
 
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 906096bed0..116e151d1a 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -8,7 +8,7 @@ Host 报告的 `ModelSelection` 是唯一的选择事实，其中包含提供方
 
 当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 注册一个 composer 阻塞块，输入框随之停用并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来可用的 composer；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
 
-目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行 seam 之外激活持久化 child 历史。
+目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行路径之外激活持久化 child 历史。
 
 `/client` 导出面为插件本体（`apply`/`inject`）、`ModelService`、`ModelDirectory` 及其状态形状、slot 注入面类型。
 
diff --git a/packages/client/ui-model/src/client/index.ts b/packages/client/ui-model/src/client/index.ts
index f55cb83c1c..63feadebef 100644
--- a/packages/client/ui-model/src/client/index.ts
+++ b/packages/client/ui-model/src/client/index.ts
@@ -9,7 +9,7 @@
  * ride each entry's own retry surface (popup shell error/retry; seat menu
  * inline error) without forking the state. Addressed subagent sessions expose
  * neither entry because those Agent-bound RPCs would activate persisted
- * history outside the direct-parent continuation seam.
+ * history outside the direct-parent continuation path.
  */
 import type { ModelSelection, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
diff --git a/packages/client/ui-primitives/src/clipboard.ts b/packages/client/ui-primitives/src/clipboard.ts
index 0ef84a4123..aa45f4c76d 100644
--- a/packages/client/ui-primitives/src/clipboard.ts
+++ b/packages/client/ui-primitives/src/clipboard.ts
@@ -1,5 +1,5 @@
 // Host clipboard write shared by Web UI copy controls. Success feedback stays
-// with each control; this seam only reports whether the host accepted a write.
+// with each control; this helper only reports whether the host accepted a write.
 
 /**
  * Write text to the host clipboard, preferring the async Clipboard API and
diff --git a/packages/client/ui-primitives/src/markdown/incremental.ts b/packages/client/ui-primitives/src/markdown/incremental.ts
index 3947d4801f..18638a25b6 100644
--- a/packages/client/ui-primitives/src/markdown/incremental.ts
+++ b/packages/client/ui-primitives/src/markdown/incremental.ts
@@ -95,7 +95,7 @@ export class IncrementalMarkdownParser {
     // to verify the whole retained prefix, and startsWith compares bytes two
     // orders of magnitude faster than parsing them — the cost this class
     // exists to remove. Passing append/reset deltas instead would push
-    // append bookkeeping across the session-projection seam for a check
+    // append bookkeeping across the session-projection update boundary for a check
     // that stays sub-millisecond at realistic reply sizes.
     if (!text.startsWith(this.prevText)) {
       this.prevText = ''
diff --git a/packages/client/ui-primitives/tests/diff-block.spec.tsx b/packages/client/ui-primitives/tests/diff-block.spec.tsx
index bb4a2fdac3..575cfd06bd 100644
--- a/packages/client/ui-primitives/tests/diff-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/diff-block.spec.tsx
@@ -4,7 +4,7 @@
 // its singular/plural, the head/tail height cap and its expand control, the
 // empty-diffs null render, and the copy control writing the prefixed diff text
 // on both the accepted and the refused clipboard paths. writeClipboard's own
-// return contract is pinned in terminal-block.spec.tsx (the shared seam), so
+// return contract is pinned in terminal-block.spec.tsx (the shared return contract), so
 // only its DOM consequence is asserted here.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-primitives/tests/terminal-block.spec.tsx b/packages/client/ui-primitives/tests/terminal-block.spec.tsx
index 13121351a8..23a38e8e09 100644
--- a/packages/client/ui-primitives/tests/terminal-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/terminal-block.spec.tsx
@@ -3,7 +3,7 @@
 // arms, the prompt line's run-state dot, the exit-status pill, the head/tail height cap and its expand control,
 // and the copy control writing the raw output on both the accepted and the
 // refused clipboard paths. writeClipboard's own return contract is pinned here
-// too, since it is the seam both copy controls in this package share; the
+// too, since it is the return contract both copy controls in this package share; the
 // resolution of ANSI runs into styles is pinned in ansi.spec.ts, so only its
 // DOM consequence (which runs get a span wrapper) is asserted here.
 
diff --git a/packages/client/ui-sidebar/src/client/contract/slots.ts b/packages/client/ui-sidebar/src/client/contract/slots.ts
index dea4fea6c9..7b30e4232e 100644
--- a/packages/client/ui-sidebar/src/client/contract/slots.ts
+++ b/packages/client/ui-sidebar/src/client/contract/slots.ts
@@ -32,7 +32,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 
 /**
  * Owner share of the browser hole — the only facts crossing the shell/region
- * seam. Business data and actions arrive through the region's own inject.
+ * boundary. Business data and actions arrive through the region's own inject.
  */
 export interface SidebarSectionOwnerProps {
   /** Shell fold-state output: wide renders the full browser, rail the icon column. */
diff --git a/packages/client/ui-slash/src/client/controller.ts b/packages/client/ui-slash/src/client/controller.ts
index 0b57f3dd74..fdf78d316e 100644
--- a/packages/client/ui-slash/src/client/controller.ts
+++ b/packages/client/ui-slash/src/client/controller.ts
@@ -22,7 +22,7 @@ export interface SourceRoster {
   all(): readonly SlashSource[]
 }
 
-/** Construction seams of one controller. */
+/** Construction hooks for one controller. */
 export interface SlashControllerDeps {
   /** The owning session scope (event dispatch + teardown registration site). */
   actx: ClientContext
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index a3bf047f84..8f7c3293be 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/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/ui-slots/README.md
-README.md: bb489dea0c3848cf3d501dcf095a65fe1cef9ef6
-README.zh.md: 8b10ddf2d974c3054b5e086a302cd8f84dca9667
+README.md: 7ee2a3d22c2a41b0e5c356c52d383a047cf99029
+README.zh.md: 793bb2d1f77e02e34a41fab16b2c2c64b78744dc
diff --git a/packages/client/ui-slots/README.md b/packages/client/ui-slots/README.md
index bb489dea0c..7ee2a3d22c 100644
--- a/packages/client/ui-slots/README.md
+++ b/packages/client/ui-slots/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Slot registry pure core, slot terminal design: SlotMap declaration merging, the single `register` composition API on SlotCore, the four-share component-props type family, the store-seat type family, and the renderer install-seam contract. React types only at runtime — the package is React-free and cordis-free.
+Slot registry pure core, slot terminal design: SlotMap declaration merging, the single `register` composition API on SlotCore, the four-share component-props type family, the store-seat type family, and the renderer installation contract. React types only at runtime — the package is React-free and cordis-free.
 
 One `register({ name, children?, store?, inject?, ...kind }, Component)` call contributes a component into a declared slot and, in the same breath, declares child slots (declaration = render authorization = runtime spec, one table), a store seat, and the registrant's business face. The component is checked at the call site against `ComposedProps` — the intersection of four shares, each derived from its single source of truth:
 
@@ -17,9 +17,9 @@ Chain-kind slots invert keyed routing — entries self-nominate instead of the d
 
 The standard-kit interfaces (`SessionStandardProps`, `GlobalStandardProps`) are declared empty here and merged by the runtime package (same declare-merge pattern as SlotMap keys). The renderer binds the runtime's session and workspace observable sources into selector hooks. Inject factory parameters derive from the declaration (`InjectParams`): session slots get `sessionId`, a declared store appends baked `actions`, nothing else — data access lives in the apply closure's ctx.
 
-The store family (`defineStore` spec in / `StoreHandle<T, A>` out) types the store seat: `init` infers the state schema, `actions` is the complete draft-transform write set, `BakedActions` strips the draft parameter into the callbacks components and inject factories receive. The `defineStore` value implementation lives in the runtime package (the engine's home) and satisfies the `DefineStore` contract exported here. Engine products and the renderer host contract carry bare snapshot sources (`getSnapshot`/`subscribe`), never React hooks — hook binding is the render machinery's side of the seam; only the props-contract hook type (`SnapshotSelectorHook`) lives here.
+The store family (`defineStore` spec in / `StoreHandle<T, A>` out) types the store seat: `init` infers the state schema, `actions` is the complete draft-transform write set, `BakedActions` strips the draft parameter into the callbacks components and inject factories receive. The `defineStore` value implementation lives in the runtime package (the engine's home) and satisfies the `DefineStore` contract exported here. Engine products and the renderer host contract carry bare snapshot sources (`getSnapshot`/`subscribe`), never React hooks — hook binding belongs to the render machinery; only the props-contract hook type (`SnapshotSelectorHook`) lives here.
 
-`SlotCore` seeds the a-priori `'root'` slot at construction and enforces load-time validation (undeclared-slot registration, duplicate child declaration, one shared handle under two scopes, a chain registration without `select` — all throw at register). An entry's disposer collapses its declared child slots recursively: ledger rows, contributions, and store mounts die on one lifecycle axis. Each key also carries a declaration epoch that advances only on declaration and collapse; the runtime uses it for [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection), independently from ordinary entry versions. `renderer.ts` carries the install seam (`SlotRenderer`, `SlotRendererHost`) plus `StaleAuthorizationError`/`SlotOwnershipError`; the implementation lives in web-react, the installation in the shell boot.
+`SlotCore` seeds the a-priori `'root'` slot at construction and enforces load-time validation (undeclared-slot registration, duplicate child declaration, one shared handle under two scopes, a chain registration without `select` — all throw at register). An entry's disposer collapses its declared child slots recursively: ledger rows, contributions, and store mounts die on one lifecycle axis. Each key also carries a declaration epoch that advances only on declaration and collapse; the runtime uses it for [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection), independently from ordinary entry versions. `renderer.ts` carries the installation contract (`SlotRenderer`, `SlotRendererHost`) plus `StaleAuthorizationError`/`SlotOwnershipError`; the implementation lives in web-react, the installation in the shell boot.
 
 ## Model Experience
 
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index 8b10ddf2d9..793bb2d1f7 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装 seam 约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
+Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
 
 一次 `register({ name, children?, store?, inject?, ...kind }, Component)` 调用会向已声明 slot 贡献一个组件，同时声明子 slot（声明 = 渲染授权 = 运行时规范，三者共用一张表）、store seat 以及注册方的业务表层。组件会在调用点依据 `ComposedProps` 接受检查；该类型是四个 share 的交集，每个 share 都从各自的唯一真源派生：
 
@@ -17,9 +17,9 @@ chain-kind slot 会反转键控路由：条目自行提名，而不是由分发
 
 标准工具包接口（`SessionStandardProps`、`GlobalStandardProps`）在这里声明为空，由 runtime 包合并（与 SlotMap key 相同的 declare-merge 模式）。renderer 会把运行时 Session 和 Workspace observable source 绑定为 selector hook。Inject factory 参数从声明派生（`InjectParams`）：Session slot 获得 `sessionId`；声明 store 时追加 baked `actions`；没有其他参数，数据访问位于 apply 闭包的 ctx 中。
 
-store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
+store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
 
-`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
+`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与折叠时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装约定（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
 ## 模型体验
 
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 6a20a8b916..7d7d9a6c34 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -211,7 +211,7 @@ export type MatchedShare<E extends SlotEntryDef, M> =
 /**
  * Conversation-session selector hook alias for props contracts. Wide by
  * default at this dependency-inverted layer; the runtime narrows at its
- * export seam (`UseSession<ConversationSnapshot>`).
+ * export outlet (`UseSession<ConversationSnapshot>`).
  */
 export type UseSession<Snap extends object = object> = SnapshotSelectorHook<Snap>
 
@@ -392,7 +392,7 @@ type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M
 
 /**
  * One stored registration, as recorded by the core and read by the render
- * machinery (type-erased at this boundary; the register seam already proved
+ * machinery (type-erased at this boundary; the registration contract already proved
  * the shares against the component).
  */
 export interface StoredEntry {
@@ -467,7 +467,7 @@ interface SlotRecord {
 const NO_ENTRIES: readonly StoredEntry[] = Object.freeze([])
 
 /**
- * Pure slot registry (no cordis; event emission and the renderer install seam
+ * Pure slot registry (no cordis; event emission and the renderer installation contract
  * live in the runtime Service wrapper).
  *
  * The 'root' slot is the one a-priori declaration, seeded at construction
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 3bcb864a9d..2a676fa22a 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -34,11 +34,11 @@ export interface HostObservable<T> {
 }
 
 /**
- * Type-erased store instance face at the render seam (the typed twin is
+ * Type-erased store instance face at the render boundary (the typed twin is
  * {@link StoreInstance}): a bare snapshot source plus the draft-stripped
- * action callbacks. No React hook crosses this seam — the render machinery
+ * action callbacks. No React hook crosses this boundary — the render machinery
  * binds `useStore` from the source at its own side (cached per instance);
- * typing lands at the component seam via {@link PropsStore}.
+ * typing lands at the component boundary via {@link PropsStore}.
  */
 export interface StoreInstanceLike {
   getSnapshot(): unknown
@@ -54,7 +54,7 @@ export interface StoreInstanceLike {
 /**
  * Per-session standard props resolved per session id (identity-stable per
  * session scope; a recreated scope yields a new info). Plugins contribute
- * members through the runtime `sessions.provide` seam; the render side binds
+ * members through the runtime `sessions.provide` contract; the render side binds
  * every `hooks` source into a `use<Name>` selector hook (hooks never appear
  * on the host contract) and spreads `props` verbatim. The runtime itself
  * contributes the first entry (`'session'` → `useSession`).
@@ -161,7 +161,7 @@ export interface SlotRendererHost {
   locale?: LocaleFace | undefined
 }
 
-/** The install seam: runtime owns install()/renderSlot(); web-react implements rendering. */
+/** The installation contract: runtime owns install()/renderSlot(); web-react implements rendering. */
 export interface SlotRenderer {
   /**
    * Render the root slot tree over the host surface (the only ctx-level entry).
diff --git a/packages/client/ui-theme/src/client/settings-contract.ts b/packages/client/ui-theme/src/client/settings-contract.ts
index 60bfffebb5..f4fc5fe8da 100644
--- a/packages/client/ui-theme/src/client/settings-contract.ts
+++ b/packages/client/ui-theme/src/client/settings-contract.ts
@@ -1,5 +1,5 @@
 /**
- * Re-export seam for the `settings.general.item` slot type consumed by this
+ * Re-export outlet for the `settings.general.item` slot type consumed by this
  * package's Appearance row. The canonical home is the locale package (the
  * common dependency of every item registrant); this file exists so row
  * modules import the type from within their own package.
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 2f5efae420..6c0bb956bd 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -89,7 +89,10 @@ function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
-/** Same real-stack bench as the toolview-slot spec: SlotsService + renderer + both owning package applies; fakes only at service seams. */
+/**
+ * Same real-stack bench as the toolview-slot spec: SlotsService + renderer +
+ * both owning package applies; fakes only at service boundaries.
+ */
 async function bench(snapshot: ConversationSnapshot) {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
diff --git a/packages/client/ui-tool/tests/toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
index e96c460576..c927cc30ea 100644
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -58,7 +58,7 @@ const LAYOUT_CHILDREN = {
 
 /**
  * Real-stack bench: SlotTestRuntime with the session/layout doubles at the
- * service seams only (external boundaries), the package apply on its own
+ * service boundaries only, the package apply on its own
  * fiber, and the test AppFrame occupying 'root'.
  */
 async function bench(nodes: ToolResultNode[]) {
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index 9c67da18d2..f7a3c32e93 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -350,7 +350,7 @@ function standardKit(
 /**
  * One rendered entry: standard kit + cached inject + owner props (owner
  * wins). The kit and injected shares are erased at the render boundary — the
- * register seam already proved the composed contract — so each Entry renders
+ * registration contract already proved the composed type — so each Entry renders
  * through a props-widened view of the component (the design-budgeted
  * composition point, one per scope branch).
  */
@@ -584,7 +584,7 @@ function RootOutlet({ ownerProps }: { ownerProps: object }) {
 /**
  * Build the renderer the shell installs into the runtime SlotsService
  * (ctx.slots.install(createSlotRenderer()) at boot; the service owns the
- * install/renderSlot seam and the double-install/not-installed throws).
+ * install/renderSlot contract and the double-install/not-installed throws).
  * @returns the renderer.
  */
 export function createSlotRenderer(): SlotRenderer {
diff --git a/packages/client/web/README.i18n.yaml b/packages/client/web/README.i18n.yaml
index cf0e86691f..cbb7dc9c17 100644
--- a/packages/client/web/README.i18n.yaml
+++ b/packages/client/web/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/web/README.md
-README.md: 74c481d573fb716e624e639c74b35c82e6894f63
-README.zh.md: 0e36107e50b2e22d65c126a4fd8873a89b0bb687
+README.md: 48355a046910bd5b78249af7b7781dab6a7c3a60
+README.zh.md: f0b567569849c698e8a1a29323e7088b49996522
diff --git a/packages/client/web/README.md b/packages/client/web/README.md
index 74c481d573..48355a0469 100644
--- a/packages/client/web/README.md
+++ b/packages/client/web/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Web shell kernel: `new AppWebEntry(el, seams?).run()` mounts the whole client through the two-stage boot (web2). Stage one (module face): build the client module system (`@deepseek-ai/dsh-client-modules`) over the host-pushed entry graph (`window.__DSH_BOOT__`) and prefetch the `immediately` tier in parallel — bundle execution registers factories only. Stage two (plugin face): mount the vendored cordis Loader with the module system injected as its `internal` seam, create one loader entry per graph row plus the shell-own app-shell assembly entry (tree.import materializes each module), and gate AppRoot on the settle (loader quiesced + every entry fiber ACTIVE → full UI in one switch). Composition is entirely the host graph's: the roster and the immediately tier live in the composing app; the shell makes zero composition decisions.
+Web shell kernel: `new AppWebEntry(el, seams?).run()` mounts the whole client through the two-stage boot (web2). Stage one (module face): build the client module system (`@deepseek-ai/dsh-client-modules`) over the host-pushed entry graph (`window.__DSH_BOOT__`) and prefetch the `immediately` tier in parallel — bundle execution registers factories only. Stage two (plugin face): mount the vendored cordis Loader with the module system injected through its `internal` contract, create one loader entry per graph row plus the shell-own app-shell assembly entry (tree.import materializes each module), and gate AppRoot on the settle (loader quiesced + every entry fiber ACTIVE → full UI in one switch). Composition is entirely the host graph's: the roster and the immediately tier live in the composing app; the shell makes zero composition decisions.
 
 Shell self-sufficiency (web2 hard rule): the kernel value-imports no plugin package — the boot status store and signals are hand-rolled here (`loader-status.ts`), so the loading page works while (and especially when) plugins fail. The app-shell assembly (`@deepseek-ai/dsh-client-app-shell`, a shell-owned pseudo entry with no npm package behind it) is the only module registered through `registerStatic`; it inject-waits on slots/sessions/layout like any plugin.
 
 `PLATFORM_MODULES` (src/platform.ts) is the single source of truth for the shared module surface: seed-table keys, tsdown client externals, and the vite alias set are its projections.
 
-The optional `seams` parameter forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
+The optional override parameter `seams` forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
 
 The shell owns browser-title projection. With a selected session carrying a durable title, it renders `<session title> — <existing HTML title>` and reacts to later title revisions; no selection or a selected untitled session preserves the existing title, and shell unmount restores it. The existing HTML title remains the configurable product suffix.
 
diff --git a/packages/client/web/README.zh.md b/packages/client/web/README.zh.md
index 0e36107e50..f0b5675698 100644
--- a/packages/client/web/README.zh.md
+++ b/packages/client/web/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-Web 外壳内核：`new AppWebEntry(el, seams?).run()` 通过两阶段启动（web2）挂载整个客户端。第一阶段（模块侧）：构建客户端模块系统（`@deepseek-ai/dsh-client-modules`），以主机推送的配置项图（`window.__DSH_BOOT__`）为基础，并行预取 `immediately` 层级；执行组合包只会注册 factory。第二阶段（插件侧）：挂载仓库内置的 Cordis Loader，并把模块系统作为其 `internal` seam 注入；为每一行图数据创建一个 loader 配置项，另创建外壳自身的 app-shell 组装配置项（tree.import 会物化各模块）；以 settle 作为 AppRoot 的门禁（loader 完全停稳 + 每个配置项 fiber 都为 ACTIVE → 一次切换显示完整 UI）。组合完全由主机图决定：花名册和 immediately 层级都位于负责组合的应用中；外壳不作任何组合决策。
+Web 外壳内核：`new AppWebEntry(el, seams?).run()` 通过两阶段启动（web2）挂载整个客户端。第一阶段（模块侧）：构建客户端模块系统（`@deepseek-ai/dsh-client-modules`），以主机推送的配置项图（`window.__DSH_BOOT__`）为基础，并行预取 `immediately` 层级；执行组合包只会注册 factory。第二阶段（插件侧）：挂载仓库内置的 Cordis Loader，并通过其 `internal` 约定注入模块系统；为每一行图数据创建一个 loader 配置项，另创建外壳自身的 app-shell 组装配置项（tree.import 会物化各模块）；以 settle 作为 AppRoot 的门禁（loader 完全停稳 + 每个配置项 fiber 都为 ACTIVE → 一次切换显示完整 UI）。组合完全由主机图决定：花名册和 immediately 层级都位于负责组合的应用中；外壳不作任何组合决策。
 
 外壳自给自足（web2 硬性规则）：内核不对任何插件包（package）执行值导入；启动状态 store 与信号在这里手写（`loader-status.ts`），因此即使插件失败，加载页面仍能工作，而此时这一点尤其重要。app-shell 组装（`@deepseek-ai/dsh-client-app-shell`，由外壳拥有、背后没有 npm 包的伪配置项）是唯一通过 `registerStatic` 注册的模块；它与任何插件一样，通过 inject 等待 slots/sessions/layout。
 
 `PLATFORM_MODULES`（src/platform.ts）是共享模块表层的唯一真源：种子表 key、tsdown 客户端 external 和 vite alias 集都是它的投影。
 
-可选 `seams` 参数会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。
+可选的覆盖参数 `seams` 会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。
 
 外壳拥有浏览器标题投影。选中带有持久标题的会话时，它会渲染 `<session title> — <existing HTML title>` 并响应后续标题修订；未选择会话或选中无标题会话时，会保留现有标题；外壳卸载时恢复标题。现有 HTML 标题仍是可配置的产品后缀。
 
diff --git a/packages/client/web/src/boot.tsx b/packages/client/web/src/boot.tsx
index 010f0ea437..cf63247915 100644
--- a/packages/client/web/src/boot.tsx
+++ b/packages/client/web/src/boot.tsx
@@ -12,7 +12,7 @@
  * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary, D16)
  * → build the module system over the module-view rows → render the loading
  * page → prefetch every `immediately` row in parallel with mounting the
- * vendored cordis Loader (internal-seam injection BEFORE any entry exists —
+ * vendored cordis Loader (`internal` contract injection BEFORE any entry exists —
  * the bare-import fallback in tree.import must never run in a browser) →
  * await the prefetch tier, THEN adopt the modules entry and create one
  * loader entry per plugin-view row plus the shell-own app-shell assembly
@@ -47,7 +47,7 @@ import { getStaticModules } from './seed.ts'
 import { STATE_LABELS, createLoaderStatusStore, createSignal } from './loader-status.ts'
 import './base.css'
 
-/** Module transport seam the shell passes through (jsdom tests replace the <script> path). */
+/** Module transport hook the shell passes through (jsdom tests replace the <script> path). */
 export type BootSeams = Pick<ClientModuleSystemOptions, 'loadBundle'>
 
 /**
@@ -80,7 +80,7 @@ export class AppWebEntry {
   /**
    * Hold the mount point; all work happens in {@link run}.
    * @param el - mount point (the app's #root).
-   * @param seams - optional module transport overrides (test environments).
+   * @param seams - Optional module transport overrides for test environments.
    */
   constructor(el: HTMLElement, seams?: BootSeams) {
     this.el = el
@@ -157,7 +157,7 @@ export class AppWebEntry {
       })))
   }
 
-  /** Plugin face: mount the Loader, inject the internal seam, adopt modules, create the graph entries, settle, sweep. */
+  /** Plugin face: mount the Loader, inject the `internal` contract, adopt modules, create the graph entries, settle, sweep. */
   private async runPluginBoot(prefetching: Promise<void>): Promise<void> {
     const ctx = this.ctx
     await ctx.plugin(Loader)
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 1f9b94c59b..fb72d6b9c2 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: 45dd55b8609fd33b7116f6b2ea36df3b3332e419
-README.zh.md: ebf288a49f87ad01b1ec80c3843c87c91206af26
+README.md: 024dea980b1678ca7d375bad4d4a627b4956bb02
+README.zh.md: eaedc8acf7211e0347fdfbcb934f9013dc7539bd
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index 45dd55b860..024dea980b 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): a runtime Service Definition for executing one model-written program against host-provided async bindings, capturing what it printed and returned; replaceable providers; and the tool registry's [Code Mode](../core/tools/README.md) Consumer (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`). Design is in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | Code-execution seam and shared vocabulary | `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Service Definition and shared vocabulary | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
 
-Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
+Providers register the service without changing its Consumer. The child READMEs own language, isolation, and execution-budget details.
 
 The subsystem reference — run requests/results, binding namespaces, the failure taxonomy — is [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index ebf288a49f..eaedc8acf7 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）；设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
+代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：运行时 Service Definition，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容；可替换的提供方；以及工具注册表的 [Code Mode](../core/tools/README.md) Consumer（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）。设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | 代码执行 seam 与共享词汇 | `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Service Definition 与共享词汇 | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
 
-后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
+提供方在不改变 Consumer 的情况下注册该服务。子 README 负责语言、隔离和执行预算细节。
 
 子系统参考——运行请求/结果、绑定命名空间、失败分类体系——见 [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md)。
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 43801899a2..8193cb587e 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -231,7 +231,7 @@ class OutputLedger {
 /**
  * The shipped {@link CodeRuntime} backend (`ctx.codeRuntime`). Registers as
  * the `codeRuntime` service; every cap comes from validated config. See the
- * module doc for the containment model and the class JSDoc on the seam for
+ * module doc for the containment model and the Service Definition's class JSDoc for
  * the contract this implements (error-as-field, hostile-peer port,
  * no cross-run state, dispose to quiescence).
  */
@@ -285,7 +285,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
   /**
    * Execute one program in a fresh worker. Program outcomes — including a
    * type-strip syntax error, which never spawns a worker — resolve with
-   * `result.error`; the method rejects only for seam misuse (a disposed
+   * `result.error`; the method rejects only for Service Definition contract misuse (a disposed
    * runtime, an invalid binding namespace).
    * @param request - the program, its bindings, and the abort signal.
    * @returns the run's outcome per the seam contract.
@@ -316,7 +316,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
     return new OutputLedger(this.config.maxOutputBytes).failure([], error)
   }
 
-  /** Reject malformed binding globals or typed-error declarations as seam misuse. */
+  /** Reject malformed binding globals or typed-error declarations as Service Definition contract misuse. */
   private validateBindings(request: CodeRunRequest): Map<string, CodeBindingNamespace> {
     const bindings = new Map<string, CodeBindingNamespace>()
     for (const namespace of request.bindings) {
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 0a72d1608c..77bd626bec 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: 637cc6adae3372ea60ca003f74af416513484270
-README.zh.md: fcc4c7323dd547c2421bb1e5a009481bf78cfc70
+README.md: 1d3cee958c186b7d0b2be1f69400977d009abc40
+README.zh.md: 9aac1196085d12dfe240af7667e98787f445c534
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 637cc6adae..1d3cee958c 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
 
 The **`CodeRuntime`** (`ctx.codeRuntime`) defines WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
 
-This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
+This package owns the Service Definition role of the capability (the bash trio is the template — see [capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): providers subclass `CodeRuntime` and register the service; the Consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), whose first provider is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the Consumer.
 
 ## Service API (`ctx.codeRuntime`)
 
 | Member | Semantics |
 |---|---|
-| `run(request)` | Execute one program against the request's bindings. **Resolves with an error FIELD for every program outcome** — parse/transform failure, thrown exception, invalid completion, output overflow, budget expiry, abort, or substrate death (`CodeRunFailure`'s orthogonal `kind` taxonomy); it rejects only for caller misuse of the seam itself (e.g. a run submitted after disposal). The program runs as the body of an async function: top-level `await`/`return` work, and a lossless JSON completion becomes `result.value`. |
+| `run(request)` | Execute one program against the request's bindings. **Resolves with an error FIELD for every program outcome** — parse/transform failure, thrown exception, invalid completion, output overflow, budget expiry, abort, or substrate death (`CodeRunFailure`'s orthogonal `kind` taxonomy); it rejects only for caller misuse of the Service Definition contract (e.g. a run submitted after disposal). The program runs as the body of an async function: top-level `await`/`return` work, and a lossless JSON completion becomes `result.value`. |
 | `language` | Readonly descriptor: the source language `run` expects. `'typescript'` and `'python'` are the well-known values — those `dsh-tools` presents; only `'typescript'` has a published backend. Informational, not gating — a consumer that generates language-specific presentation switches on it and fails loud on a language it cannot present. |
 | `isolation` | Readonly descriptor: the execution substrate (`'worker-thread'`, `'process'`, `'container'`). A label for deployments and diagnostics, **not a security claim**. |
 
@@ -18,7 +18,7 @@ Semantics every implementation must honor (contract details in the class JSDoc):
 
 ## Vocabulary
 
-`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets and outer-output cap) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions` + optional `errorClass`), each exposed to the program as one global object of async callables returning `CodeJsonValue`, the seam-local structural equivalent of canonical `JsonValue` that keeps this interface package independent of sessions. An `errorClass` descriptor names a real program-global constructor and the own property that receives the rejected member name; runtimes remain independent of consumer terms such as `ToolCallError`. `CodeRunResult` reports the lossless JSON completion `value?`, ordered `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
+`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets and outer-output cap) is the provider's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions` + optional `errorClass`), each exposed to the program as one global object of async callables returning `CodeJsonValue`, the service-local structural equivalent of canonical `JsonValue` that keeps this Service Definition package independent of sessions. An `errorClass` descriptor names a real program-global constructor and the own property that receives the rejected member name; runtimes remain independent of Consumer terms such as `ToolCallError`. `CodeRunResult` reports the lossless JSON completion `value?`, ordered `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
 
 Binding-global and error-class names are **language-portable**: they must match the identifier subset `[A-Za-z_][A-Za-z0-9_]*` (no JS-only `$`) and clear the seam-exported exclusion sets, so one `bindings` list is valid against every backend regardless of its `language`. The package exports the contract every backend enforces — `PORTABLE_RESERVED_WORDS` (ECMAScript ∪ Python reserved words), `RESERVED_BINDING_GLOBALS` (backend-owned globals such as `console`), `RESERVED_ERROR_MEMBERS` and `DUNDER_MEMBER` (error-member exclusions) — so a name like `$tools`, `lambda`, or `__dsh_main__` makes `run()` reject as seam misuse on any backend, not just some. See `src/index.ts` for the exact sets and rationale.
 
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index fcc4c7323d..9aac119608 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -4,13 +4,13 @@
 
 **`CodeRuntime`**（`ctx.codeRuntime`）定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
-此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
+此包承担该能力的 Service Definition 角色（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：提供方通过继承 `CodeRuntime` 并注册服务接入；Consumer 是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个提供方是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在 Consumer。
 
 ## 服务 API（`ctx.codeRuntime`）
 
 | 成员 | 语义 |
 |---|---|
-| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
+| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 Service Definition 约定时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
 | `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
@@ -18,7 +18,7 @@
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于提供方的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是服务本地、与规范 `JsonValue` 结构等价的类型，使 Service Definition 包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等 Consumer 术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。
 
 binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts
index 3428b5c0e4..a4edc604c8 100644
--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Code-execution seam for running one model-written program against host async bindings.
+ * Service Definition for the code-execution capability seam that runs one model-written program against host async bindings.
  * Runtimes know nothing about tools or sessions; consumers own those concerns.
  * @module @deepseek-ai/dsh-code-runtime
  */
@@ -96,7 +96,7 @@ declare module 'cordis' {
 
 /**
  * Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate
- * failures resolve in {@link CodeRunResult}; only seam misuse rejects. Implementations bridge
+ * failures resolve in {@link CodeRunResult}; only Service Definition contract misuse rejects. Implementations bridge
  * structured-cloneable bindings, materialize each declared namespace rejection
  * class, treat programs as hostile peers, isolate runs from one another, and
  * terminate and await in-flight runs during disposal.
@@ -127,7 +127,7 @@ export abstract class CodeRuntime extends Service {
   /**
    * Execute one program against the request's bindings and capture what it
    * emitted. See the class doc for the resolution contract (error is a result
-   * field; rejection means seam misuse only).
+   * field; rejection means Service Definition contract misuse only).
    * @param request - the program, its bindings, and the abort signal; the
    *   request carries everything the runtime acts on, with no hidden defaults.
    * @returns the run's outcome: completion value (when transferable), the
diff --git a/packages/code-runtime/code-runtime/src/types.ts b/packages/code-runtime/code-runtime/src/types.ts
index 6d83ace689..a204b113ac 100644
--- a/packages/code-runtime/code-runtime/src/types.ts
+++ b/packages/code-runtime/code-runtime/src/types.ts
@@ -17,7 +17,7 @@
  */
 export type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
 
-/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
 export type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
 
 /**
diff --git a/packages/code-runtime/code-runtime/tests/reserved.spec.ts b/packages/code-runtime/code-runtime/tests/reserved.spec.ts
index f93b63b5ef..c2df873fc4 100644
--- a/packages/code-runtime/code-runtime/tests/reserved.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/reserved.spec.ts
@@ -7,7 +7,7 @@ import {
 } from '@deepseek-ai/dsh-code-runtime'
 
 /**
- * The seam owns the portable-identifier exclusion sets so every backend
+ * The Service Definition owns the portable-identifier exclusion sets so every backend
  * enforces one contract: a namespace list valid on one backend is valid on
  * all. These assertions pin the shared membership backends import rather than
  * re-declare.
diff --git a/packages/code-runtime/code-runtime/tests/service.spec.ts b/packages/code-runtime/code-runtime/tests/service.spec.ts
index 605b51934f..7ea3a30b31 100644
--- a/packages/code-runtime/code-runtime/tests/service.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/service.spec.ts
@@ -6,7 +6,7 @@ import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtim
 /**
  * Minimal concrete runtime: records requests, "executes" by invoking every
  * binding once in declaration order, and lets tests script the outcome. The
- * seam package ships no implementation, so the contract is exercised through
+ * Service Definition package ships no provider, so the contract is exercised through
  * the smallest subclass that honors it.
  */
 class StubRuntime extends CodeRuntime {
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index 7e8ef24260..ab4714ff9d 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/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/compact/README.md
-README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
-README.zh.md: 001ca6f7c079a60cbd432664e4f0b06955aaf487
+README.md: 0b5a5b18b963dc7be0bd314420bdb3c88715533d
+README.zh.md: 5d6d8a1c076e444094cc030c9495f346f40bf7ea
diff --git a/packages/compact/README.md b/packages/compact/README.md
index 0a83b87f57..0b5a5b18b9 100644
--- a/packages/compact/README.md
+++ b/packages/compact/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-A compaction capability family (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract interface, a summarizing backend, a model-free tool-result pruning companion, and a human command adapter. All **product** packages.
+A compaction capability family (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): a Service Definition, a summarizing provider, a model-free tool-result pruning companion, and a human command Consumer. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index 001ca6f7c0..5d6d8a1c07 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个压缩（compaction）能力家族（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：抽象接口、摘要后端、无模型工具结果修剪配套工具，以及用户命令适配器。这些全是**产品**包。
+一个压缩（compaction）能力家族（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：Service Definition、摘要提供方、无模型工具结果修剪配套工具，以及人类命令 Consumer。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/compact/compact-basic/README.i18n.yaml b/packages/compact/compact-basic/README.i18n.yaml
index c01b9166b5..f44b45245d 100644
--- a/packages/compact/compact-basic/README.i18n.yaml
+++ b/packages/compact/compact-basic/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/compact/compact-basic/README.md
-README.md: 5395219147e8932c8e5874e84e534a2c2fe33d53
-README.zh.md: 59479b26c5c8cf27e6ac84814c09f14ecbf9662c
+README.md: e0e3413d42e6afb8e95f91d79f9bdf3a1f17fbda
+README.zh.md: 4515592710f855dc713f078479ebe7c9c7299de1
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index 5395219147..e0e3413d42 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` seam with reusable `ctx.tokenMeter` pressure, token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call that replays the conversation prefix to reuse the provider's KV cache (interceptable at `llm/stream`).
+The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` Service Definition with reusable `ctx.tokenMeter` pressure, token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call that replays the conversation prefix to reuse the provider's KV cache (interceptable at `llm/stream`).
 
-This is the implementation tier of the compaction capability — see the [interface package](../compact/README.md) for the seam and the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) for the design.
+This package owns the Service provider role of the compaction capability — see the [Service Definition package](../compact/README.md) for its contract and the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) for the design.
 
 ## What it owns
 
@@ -15,7 +15,7 @@ This backend owns the compaction policy:
 - **Model-free pruning** — after pressure or canonical overflow qualifies, the optional [`ctx.toolResultPrune`](../compact-tool-result-prune/README.md) service rewrites oversized tool results before range selection. Compact-basic remeasures through `ctx.tokenMeter`, skips summarization when pressure becomes safe, and otherwise summarizes the pruned surface. Below-pressure step checks never prune.
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes. The optional pruner can repair an oversized closed tool unit when its text-bearing result is the removable bulk; indivisible non-tool units and non-prunable tool remainders remain out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
-- **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The call replays the conversation's own system prompt, tools, and shadowed-region messages verbatim and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. It sets `GenerateOptions.purpose` to `compaction`, which adapters may forward as request attribution (the DeepSeek adapter sends `x-deepseek-harness-compact: 1`) without touching the model-visible body. Only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
+- **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` extension point. The call replays the conversation's own system prompt, tools, and shadowed-region messages verbatim and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. It sets `GenerateOptions.purpose` to `compaction`, which adapters may forward as request attribution (the DeepSeek adapter sends `x-deepseek-harness-compact: 1`) without touching the model-visible body. Only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
 - **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the `compact/summary` event, and later automatic cycles merge the prior checkpoint.
 - **Lifecycle** — all entry points share one bracket-first region transaction. It validates the range and live lock, appends `compact/start` synchronously, prepares and awaits the summary, revalidates, appends `compact/summary` plus the replacement, and makes exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; the serial `agent/pre-step` listener checks pressure before request derivation, while canonical provider overflow enters through `agent/request-error` and authorizes retry only after durable surface progress. `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
 - **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
diff --git a/packages/compact/compact-basic/README.zh.md b/packages/compact/compact-basic/README.zh.md
index 59479b26c5..4515592710 100644
--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-**基础压缩（compaction）后端**：`BasicCompactService` 实现 `@deepseek-ai/dsh-compact` seam，使用可复用的 `ctx.tokenMeter` 压力、token 预算保留与摘要。摘要是直接的一次性 `ctx.llm.stream()` 调用，它会回放会话前缀以复用提供方的 KV Cache（可在 `llm/stream` 处拦截）。
+**基础压缩（compaction）后端**：`BasicCompactService` 实现 `@deepseek-ai/dsh-compact` Service Definition，使用可复用的 `ctx.tokenMeter` 压力、token 预算保留与摘要。摘要是直接的一次性 `ctx.llm.stream()` 调用，它会回放会话前缀以复用提供方的 KV Cache（可在 `llm/stream` 处拦截）。
 
-这是压缩能力的实现层。seam 见 [接口包](../compact/README.md)，设计见 [能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
+本包承担压缩能力的 Service provider 角色；其约定见 [Service Definition 包](../compact/README.md)，设计见 [能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
 
 ## 拥有的职责
 
@@ -15,7 +15,7 @@
 - **不依赖模型的剪枝**：在压力或规范溢出符合条件后，可选的 [`ctx.toolResultPrune`](../compact-tool-result-prune/README.md) 服务会在选择范围之前改写超大工具结果。Compact-basic 通过 `ctx.tokenMeter` 重新测量；如果压力已回到安全范围，就跳过摘要，否则对已剪枝的表层进行摘要。低于压力的步骤检查绝不剪枝。
 - **保留**：压缩最旧的完整表层单元，同时保留近期尾部，并通过 [`dsh-compact` 边界 helper](../compact/README.md#tool-pairing-boundaries) 将切分点调整到工具调用／结果配对平衡的位置。轮次边界不会保护失控轮次内的旧步骤。尚未闭合且不可分的尾部会在闭合前拒绝压缩。当闭合的超大工具单元以文本型结果为可移除主体时，可选 pruner 可以修复它；不可分的非工具单元与不可剪枝的工具剩余部分不在范围内。
 - **收敛**：最多按 `compactionRetries` 重试头部检查点压缩；拒绝不能缩小源内容的摘要，如果重试仍无法回到阈值以下，则抛出异常。
-- **摘要**：直接 `llm/stream` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 agent 目标，而不运行仅用于 agent loop 的 `agent/request` seam。该调用会逐字回放会话自身的系统提示词、工具与已遮蔽区域消息，并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。它将 `GenerateOptions.purpose` 设为 `compaction`，适配器可将其作为请求归因转发（DeepSeek 适配器发送 `x-deepseek-harness-compact: 1`），但不会触碰模型可见的请求体。只有返回的文本会进入检查点；推理（reasoning）和工具调用都会被排除，以免泄露私有推理或产生遗留调用。
+- **摘要**：直接 `llm/stream` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 agent 目标，而不运行仅用于 agent loop 的 `agent/request` 扩展点。该调用会逐字回放会话自身的系统提示词、工具与已遮蔽区域消息，并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。它将 `GenerateOptions.purpose` 设为 `compaction`，适配器可将其作为请求归因转发（DeepSeek 适配器发送 `x-deepseek-harness-compact: 1`），但不会触碰模型可见的请求体。只有返回的文本会进入检查点；推理（reasoning）和工具调用都会被排除，以免泄露私有推理或产生遗留调用。
 - **框定**：替换 user 消息使用 `<compacted-summary>` 标签标记已建立的检查点上下文。原始摘要保留在 `compact/summary` 事件上，后续自动周期会合并之前的检查点。
 - **生命周期**：所有入口点共享一个先记录标记的区域事务。它会验证范围与活动锁，同步追加 `compact/start`，准备并等待摘要，重新验证，再追加 `compact/summary` 和替换，最后恰好进行一次闭合尝试。自动调用和显式范围调用要求数字标识的开放轮次归属，并要求整个表层保持稳定；串行 `agent/pre-step` listener 会在派生请求之前检查压力，而规范提供方溢出则经由 `agent/request-error` 进入，并且只在表层取得持久进展后才允许重试。`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index dae5564742..ec95ee2165 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: c7fdbef33b2e65089a0f0112e19122db4f26bb77
-README.zh.md: 493d269202b3a5b89cd600391e7144219ed2bf12
+README.md: 3fecc91422bcdc994bcbe4db308ee4a52cb3c53f
+README.zh.md: ea66d8bdb0684f27cf68a5431be75966041b7534
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index c7fdbef33b..3fecc91422 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -4,19 +4,19 @@ English | [中文](README.zh.md)
 
 The **`CompactService`** (`ctx.compact`) defines WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
 
-This package is the interface tier of the compaction capability, split so each concern evolves (and swaps) independently:
+This package owns the Service Definition role of the compaction capability, split so each role evolves (and swaps) independently:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + canonical checkpoint source + tool-pairing boundary helpers |
-| `@deepseek-ai/dsh-compact-basic` | a backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
-| `@deepseek-ai/dsh-command-compact` | the human `/compact` command over `ctx.compact.compactNow()` |
+| `@deepseek-ai/dsh-compact` (this) | Service Definition: abstract service + `compact/*` events + `CompactionResult` + canonical checkpoint source + tool-pairing boundary helpers |
+| `@deepseek-ai/dsh-compact-basic` | Service provider: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
+| `@deepseek-ai/dsh-command-compact` | Consumer: the human `/compact` command over `ctx.compact.compactNow()` |
 
-Unlike the bash seam, this interface depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+Unlike the bash seam, this Service Definition depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "Service Definition depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
 
 ## Service API (`ctx.compact`)
 
-All three operations are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this interface.
+All three operations are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this Service Definition.
 
 | Member | Semantics |
 |---|---|
@@ -32,7 +32,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten
 
 ## Tool-pairing boundaries
 
-The interface exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order.
+The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order.
 
 The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-entry count. An unchanged generation extends the fold with unseen tail entries only; a log-only append with no new surface entry does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state.
 
@@ -80,7 +80,7 @@ A successful implementation replaces an older surface range with one user-role s
 
 #### Token effect
 
-Zero direct tokens from this interface. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+Zero direct tokens from this Service Definition. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
 
 #### KV Cache effect
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 493d269202..ea66d8bdb0 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -4,19 +4,19 @@
 
 **`CompactService`**（`ctx.compact`）定义压缩做什么，即判定历史记录是否过大，并将较早范围摘要为单个表层节点，但不规定如何实现。
 
-这个包是压缩能力的接口层，因此各项职责均可独立演进，也可独立替换：
+本包承担压缩能力的 Service Definition 角色，因此各角色均可独立演进，也可独立替换：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-compact`（本包） | 接口：抽象服务 + `compact/*` 事件 + `CompactionResult` + 规范检查点源 + 工具配对边界 helper |
-| `@deepseek-ai/dsh-compact-basic` | 后端：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
-| `@deepseek-ai/dsh-command-compact` | 面向用户的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
+| `@deepseek-ai/dsh-compact`（本包） | Service Definition：抽象服务 + `compact/*` 事件 + `CompactionResult` + 规范检查点源 + 工具配对边界 helper |
+| `@deepseek-ai/dsh-compact-basic` | Service provider：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
+| `@deepseek-ai/dsh-command-compact` | Consumer：面向人类的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
 
-与 bash seam 不同，该接口依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。约定的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「接口只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
+与 bash seam 不同，该 Service Definition 依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。约定的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「Service Definition 只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
 
 ## 服务 API（`ctx.compact`）
 
-三个操作都是**抽象方法**：触发策略、保留、事件顺序与摘要均属于后端。可复用的请求测量是独立服务 [`ctx.tokenMeter`](../../llm/token-meter/README.md)，而非本接口的一部分。
+三个操作都是**抽象方法**：触发策略、保留、事件顺序与摘要均属于后端。可复用的请求测量是独立服务 [`ctx.tokenMeter`](../../llm/token-meter/README.md)，而非本 Service Definition 的一部分。
 
 | 成员 | 语义 |
 |---|---|
@@ -32,7 +32,7 @@
 
 ## 工具配对边界
 
-该接口导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于对齐和验证压缩边界。安全边界不会被尚未回答的 assistant 工具调用跨越。每个 helper 都会验证给定事件 seq 位于当前表层，并根据按表层顺序缓存的各切分点配对状态返回结果。
+该 Service Definition 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于对齐和验证压缩边界。安全边界不会被尚未回答的 assistant 工具调用跨越。每个 helper 都会验证给定事件 seq 位于当前表层，并根据按表层顺序缓存的各切分点配对状态返回结果。
 
 每个会话的私有 cache 以 `session.surface.replaceGeneration` 和已处理表层条目数为 key。generation 未变时，只需将尚未处理的尾部条目纳入累计结果；仅向日志追加、但未新增表层条目时，不会读取事件。replace generation 变化时则会重建当前成员关系与配对状态。事件 seq 缺失以及 `tool/result` 没有对应的先前未闭合调用，均会被视为表层状态损坏并遭拒绝。
 
@@ -80,7 +80,7 @@
 
 #### Token 影响
 
-该接口不会直接产生 token。后端用一份摘要换取多个原本保留的历史 token，并保持近期尾部不变。
+该 Service Definition 不会直接产生 token。后端用一份摘要换取多个原本保留的历史 token，并保持近期尾部不变。
 
 #### KV Cache 影响
 
diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts
index e537639adc..7b0bd25091 100644
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Compaction service seam (`ctx.compact`): implementations decide when to
+ * Compaction Service Definition (`ctx.compact`): providers decide when to
  * compact and replace a history range with one summary node by subclassing
  * {@link CompactService}. This interface necessarily depends on session and LLM
  * vocabulary; the rationale is in the
diff --git a/packages/compact/compact/tests/compact.spec.ts b/packages/compact/compact/tests/compact.spec.ts
index f063609808..7e6915354f 100644
--- a/packages/compact/compact/tests/compact.spec.ts
+++ b/packages/compact/compact/tests/compact.spec.ts
@@ -13,7 +13,7 @@ import type { ManualCompactAgentContext } from '@deepseek-ai/dsh-compact'
 
 /**
  * A trivial concrete CompactService implementing the abstract contract. The
- * interface package owns no algorithm — these tests exercise the seam itself:
+ * Service Definition package owns no algorithm — these tests exercise its contract:
  * service registration, the abstract method shape, and the `compact/*` event
  * declaration merge.
  */
diff --git a/packages/context/tmux-context/README.i18n.yaml b/packages/context/tmux-context/README.i18n.yaml
index 0e3f1898ad..b315a68fd9 100644
--- a/packages/context/tmux-context/README.i18n.yaml
+++ b/packages/context/tmux-context/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/context/tmux-context/README.md
-README.md: 26eff205b399bfcd20f55e91ef46cadbd70ae604
-README.zh.md: 7f256a829860df3f39e913d003b4e53d09243365
+README.md: 59c452be53b8bb7cb7244a9bb2017749750ce4bf
+README.zh.md: f343c9b25c832cafcb3366209bc2ce39308ad0d5
diff --git a/packages/context/tmux-context/README.md b/packages/context/tmux-context/README.md
index 26eff205b3..59c452be53 100644
--- a/packages/context/tmux-context/README.md
+++ b/packages/context/tmux-context/README.md
@@ -17,7 +17,7 @@ Opt-in durable context naming the tmux session, window, and pane this agent proc
 
 ## How it reads tmux
 
-The plugin prepends an `agent/pre-step` listener that runs only on the first step of each turn. When due, it runs one read-only command through the `ctx.bash` executor seam:
+The plugin prepends an `agent/pre-step` listener that runs only on the first step of each turn. When due, it runs one read-only command through the `ctx.bash` executor service:
 
 ```sh
 [ -n "$TMUX_PANE" ] || exit 1
diff --git a/packages/context/tmux-context/README.zh.md b/packages/context/tmux-context/README.zh.md
index 7f256a8298..f343c9b25c 100644
--- a/packages/context/tmux-context/README.zh.md
+++ b/packages/context/tmux-context/README.zh.md
@@ -17,7 +17,7 @@
 
 ## 如何读取 tmux
 
-插件前置注册一个 `agent/pre-step` 监听器，仅在每轮的第一个 step 运行。当需要注入时，它通过 `ctx.bash` 执行器 seam 运行一条只读命令：
+插件前置注册一个 `agent/pre-step` 监听器，仅在每轮的第一个 step 运行。当需要注入时，它通过 `ctx.bash` 执行器服务运行一条只读命令：
 
 ```sh
 [ -n "$TMUX_PANE" ] || exit 1
diff --git a/packages/context/tmux-context/src/index.ts b/packages/context/tmux-context/src/index.ts
index e79ad89b6b..c489ec0970 100644
--- a/packages/context/tmux-context/src/index.ts
+++ b/packages/context/tmux-context/src/index.ts
@@ -4,7 +4,7 @@
  * and pane this agent process runs in, plus the window's pane-tree layout.
  *
  * The plugin pulls state once per turn, for the first request (`step === 1`), by
- * running one `tmux display-message` through the `ctx.bash` executor seam. It
+ * running one `tmux display-message` through the `ctx.bash` executor service. It
  * confirms this process genuinely runs inside the pane `$TMUX_PANE` names by
  * matching the pane's `#{pane_tty}` against this process's controlling terminal,
  * so a terminal that merely inherited `$TMUX`/`$TMUX_PANE` from a tmux ancestor
@@ -98,7 +98,7 @@ const FIELD_SEP = '\\t'
  * `run()` only promises to resolve for nonzero exits, timeouts, and aborts, so
  * both are contained and reported as a warning.
  *
- * @param bash - the executor seam used to run the read-only tmux/ps commands.
+ * @param bash - The executor service used to run the read-only tmux/ps commands.
  * @param logger - receives a warning when the executor rejects the query.
  * @param processId - this agent process's pid, whose controlling tty must match the pane.
  * @param signal - abort signal forwarded to the executor.
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index f3ab9dcc56..4d9ab302d8 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
-README.md: 19aed9abafa8e4531d2ee31ff0442003328a9ef6
-README.zh.md: 73ed1f500799cb235a8835ffb0317370f9a0a7e6
+README.md: 8349371ab565f2e9e735cd959026936c7ec44081
+README.zh.md: e19c446584cfac75cb50833fa01586688b9c7c92
diff --git a/packages/core/README.md b/packages/core/README.md
index 19aed9abaf..8349371ab5 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -14,7 +14,7 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, deploy
 | [`agent-default-model/`](agent-default-model/README.md) | Default model selection shared by Agent front doors | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | Default concrete agent driver | `ctx.agentLoop` |
 
-`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable. `agent-default-model` owns the deployment selection an Agent front door uses only when a session has no selection of its own.
+`scope` supplies the shared scoping primitive. `agent` owns the public contract, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable. `agent-default-model` owns the deployment selection an Agent front door uses only when a session has no selection of its own.
 
 Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
 
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index 73ed1f5007..e19c446584 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -14,7 +14,7 @@
 | [`agent-default-model/`](agent-default-model/README.md) | 各 Agent 入口共享的默认模型选择 | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | 默认具体 agent 驱动器 | `ctx.agentLoop` |
 
-`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。`agent-default-model` 负责部署选择，Agent 入口仅在会话自身没有选择时使用它。
+`scope` 提供共享作用域原语。`agent` 负责公开约定，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。`agent-default-model` 负责部署选择，Agent 入口仅在会话自身没有选择时使用它。
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
 
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 9eb0eb4921..60ceaa7572 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: 608a21a2f00545bbc03f675ee2f76034624bb10d
-README.zh.md: fc23c6cb0645c88f2e081a5dbb81dface8c553d6
+README.md: 6092363fae2853d6c5d92aaf8cd01e41e18e0b52
+README.zh.md: b65b5334d735a1e0b51fa517ce41c0c953f87cf7
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 608a21a2f0..6092363fae 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 THE concrete agent plugin and loop driver. Its package-internal implementation satisfies the `Agent` interface and drives the session/turn/step lifecycle.
 
-This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension seams — new behavior goes into plugins, not here.
+This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension points — new behavior goes into plugins, not here.
 
 ## Service: `AgentLoop` (ctx key: `agentLoop`)
 
@@ -18,7 +18,7 @@ Each agent and its session share one caller-chosen `SessionId`, assumed globally
 
 - `ctx.agentLoop.create(id: SessionId, options?: AgentOptions, meta?: { cwd?: string }): Agent` — synchronous no-setup create under the exact shared agent/session id, disposed with the calling fiber. Declarative config treats `agents[].id` as a stable label and normally mints `${label}-session-<uuid>` before calling this boundary. An app may instead supply a stable exact `sessionId`: first use creates it, while a remount with persistence already present resumes its materialized history. `resumeSessionId` requires and loads an existing persisted id and is mutually exclusive with `sessionId`. This keeps default fresh restarts collision-free without retaining a second live routing identity.
 
-`AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
+`AgentLoop` also implements the `AgentFactory` contract and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents`:
 
 - `ctx.agents.create({ sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — programmatic create under the caller-supplied shared id. It awaits the unpublished setup transaction before returning; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix after the session boundary validates and snapshots the durable values. `signal` applies only until this promise settles. The resolved [`AgentHandle`](../agent/README.md) owns exact teardown.
 - `ctx.agents.resume({ resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), register the agent under that same id, reconstruct its history, then await setup against a fresh unpublished agent scope before rollback-covered publication. Turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent). `signal` is creation-only. Returns an `AgentHandle`.
@@ -131,4 +131,4 @@ Append-only; each synthetic result follows the reusable request prefix and does
 - **Classification is unary** — calls whose safety depends on comparing siblings or resources must remain exclusive ([rationale](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)).
 - **Config labels are fresh by default** — omitting `sessionId` creates a fresh `${id}-session-<uuid>` on every startup; exact resume-or-create behavior requires an explicit stable `sessionId`, while `resumeSessionId` requires existing persisted history.
 - **Config agents have no per-agent persona field or setup hook** — they use the deployment persona; scoped persona/tool composition is available only through the programmatic `ctx.agents.create()` / `resume()` factory options.
-- **No built-in turn budget** — tool calls or steering continue the current turn; a policy that bounds runaway turns must cancel from an existing lifecycle seam such as `agent/turn-stopping`.
+- **No built-in turn budget** — tool calls or steering continue the current turn; a policy that bounds runaway turns must cancel from an existing lifecycle extension point such as `agent/turn-stopping`.
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index fc23c6cb06..b65b5334d7 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -4,7 +4,7 @@
 
 唯一的具体 agent（智能体）插件与循环驱动器。其包内部实现满足 `Agent` 接口，并驱动会话／轮次／步骤生命周期。
 
-这是 harness 中唯一包含具体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展 seam 的插件：新行为应放入插件，而不是这里。
+这是 harness 中唯一包含具体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展点的插件：新行为应放入插件，而不是这里。
 
 ## 服务：`AgentLoop`（ctx 键：`agentLoop`）
 
@@ -18,7 +18,7 @@
 
 - `ctx.agentLoop.create(id: SessionId, options?: AgentOptions, meta?: { cwd?: string }): Agent`：在确切共享的 agent／会话 id 下同步创建，不运行 setup，并随调用 fiber dispose。声明式配置把 `agents[].id` 视为稳定 label，通常会先生成 `${label}-session-<uuid>`，再调用此边界。应用也可以提供稳定且确切的 `sessionId`：首次使用时创建；重新挂载且持久化内容已存在时，则恢复已经实体化的历史。`resumeSessionId` 要求并加载现有的持久化 id，且与 `sessionId` 互斥。这样，默认的全新重启不会冲突，也无需保留第二个实时路由身份。
 
-`AgentLoop` 还实现 `AgentFactory` seam，并通过 `ctx.agents.setFactory(this)` 注册自身，因此插件会通过接口 `ctx.agents` 创建／恢复 agent：
+`AgentLoop` 还实现 `AgentFactory` 约定，并通过 `ctx.agents.setFactory(this)` 注册自身，因此插件会通过 `ctx.agents` 创建／恢复 agent：
 
 - `ctx.agents.create({ sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle>`：使用调用方提供的共享 id 以编程方式创建。它会等待尚未发布的 setup 事务，然后才返回；`meta` 携带 cwd／谱系／seed 边界元数据，`seed` 则在会话边界验证并快照持久值后，重建 fork 子级的前缀。`signal` 只在此 Promise 结算前生效。解析得到的 [`AgentHandle`](../agent/README.md) 拥有确切的 teardown。
 - `ctx.agents.resume({ resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle>`：通过 `ctx.sessionPersistence` 加载持久化会话（参见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），使用同一 id 注册 agent，重建历史，然后针对全新且尚未发布的 agent 作用域等待 setup，再执行受回滚保护的发布。轮次编号和派生历史从已加载日志继续。此操作要求存在会话持久化后端（不会硬注入，因此非持久化 demo 仍能工作；缺少持久化时，`resume` 会以明确错误拒绝）。`signal` 仅用于创建。返回 `AgentHandle`。
@@ -131,4 +131,4 @@ interface Config {
 - **分类是一元的**：安全性取决于比较同级调用或资源的调用必须保持独占（参见[设计原理](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)）。
 - **配置 label 默认每次新建**：省略 `sessionId` 会在每次启动时创建全新的 `${id}-session-<uuid>`；确切的恢复或创建行为要求显式提供稳定的 `sessionId`，而 `resumeSessionId` 要求已有持久化历史。
 - **配置 agent 没有逐 agent persona 字段或 setup 钩子**：它们使用部署 persona；只有编程式 `ctx.agents.create()` / `resume()` 工厂选项支持带作用域的 persona／工具组合。
-- **没有内置轮次预算**：工具调用或 steering 会让当前轮次继续；限制失控轮次的策略必须从既有生命周期 seam（如 `agent/turn-stopping`）执行取消。
+- **没有内置轮次预算**：工具调用或 steering 会让当前轮次继续；限制失控轮次的策略必须从既有生命周期扩展点（如 `agent/turn-stopping`）执行取消。
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index a589f3c131..e7c840e296 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -524,7 +524,7 @@ export class AgentLoop extends Service implements AgentFactory {
           assertLive()
           // A synchronous announce/session-start listener may have started
           // teardown; the machine is already live (delivery works from the
-          // session-start seam), so only the liveness recheck is owed.
+          // session-start extension point), so only the liveness recheck is owed.
           emitAgentEvent(loopCtx, agent, 'agent/session-start', { source })
           assertLive()
           return { agent, dispose }
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 79bc65a105..6fb77d141c 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -485,7 +485,7 @@ describe('Agent.cancel()', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A step/start session-event listener fires AFTER step/start is appended
-    // (and after the pre-step seam), so cancelling there lands in the SECOND
+    // (and after the pre-step extension point), so cancelling there lands in the SECOND
     // cancel check (the one that must closeStep() to balance the already-open
     // step) — distinct from a turn-start cancel, caught before the step opens.
     let streamed = false
diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts
index a26f463b0d..646c6d41fa 100644
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -19,7 +19,7 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 /**
- * The interception seams introduced by the hooks taxonomy: `agent/pre-step`,
+ * The interception points introduced by the hooks taxonomy: `agent/pre-step`,
  * `agent/session-start`, `agent/turn-stopping`, and the
  * `tools/pre-execute` / `tools/post-execute`
  * split with `additionalContexts` buffering. These verify the canonical event
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index d1d8e5401d..477c3a5cb6 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: 73d32d09d880b0d27b80a7aeecc1eb75bf03f8dd
-README.zh.md: e140d76c940ac605ddc6dedad8a9f2f16457fde0
+README.md: 0fb65b94a3b311aa9f0df09d39dd937cba4cc7b4
+README.zh.md: 44f67483343a98c280317793ece544bd0b984596
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 73d32d09d8..0fb65b94a3 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -34,7 +34,7 @@ The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-
 
 The scope carries the `Agent` itself and is process-local. Ambient presence is neither liveness proof nor authorization; explicit Agent fields remain authoritative at service, worker, process, persistence, and wire boundaries. Teardown rejects new boundaries, lets injected dependents and returned-Promise boundaries drain, then disables the underlying `AsyncLocalStorage`; unreturned work remains owned by the subsystem that detached it. If a boundary's inherited async chain starts an owning Cordis fiber's unload, that nested boundary chain is released from the drain so the unload cannot wait on itself; its continuations observe the disposed service after teardown. The [initiator-scope decision](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md) owns the detailed boundary and teardown contract.
 
-#### Factory seam (creation)
+#### Factory API (creation)
 
 Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package. The registry canonicalizes an already traced Service to its concrete target and re-traces each call through the caller's context; this avoids nested Cordis shadows while passing an explicit caller-bound `ownerCtx` to plain factories.
 
@@ -50,7 +50,7 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age
 
 The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
-Most interception points are cooperative waterfalls. `agent/pre-step` receives a payload carrying the subject `agent`, the exclusive claimed `UserMessage[]`, and the proposed `turn`, `step`, and cancellation `signal`; its batch may be empty when tools already require another request. Agent-scoped turn seams carry their explicit `AbortSignal` in the payload; the remaining turn-scoped seams receive it through their request value. Listeners may cooperate with a signal but must not retain it as authority over another turn. `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery. `agent/turn-stopping` runs before an otherwise completed turn closes. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
+Most interception points are cooperative waterfalls. `agent/pre-step` receives a payload carrying the subject `agent`, the exclusive claimed `UserMessage[]`, and the proposed `turn`, `step`, and cancellation `signal`; its batch may be empty when tools already require another request. Agent-scoped turn extension points carry their explicit `AbortSignal` in the payload; the remaining turn-scoped extension points receive it through their request value. Listeners may cooperate with a signal but must not retain it as authority over another turn. `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery. `agent/turn-stopping` runs before an otherwise completed turn closes. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
 
 `PreStepDecision` is either `{ kind: 'reject' }` or `{ kind: 'enter', messages }`. The enter branch is the complete identified, frozen batch for the proposed step. A listener that wraps downstream entry preserves that batch unless it intentionally replaces it; additions follow the waterfall's natural return order. Claiming already removed the offered messages from the inbox, so rejection does not retain them. Messages inserted after the claim remain pending for a later boundary.
 
@@ -76,7 +76,7 @@ The handle every plugin programs against:
 
 - Agent creation: `AgentLoop.create()` is the concrete config-path implementation (in `dsh-agent-loop`), while programmatic consumers create/resume owned agents through `ctx.agents.create()` / `ctx.agents.resume()`. Replace the loop by implementing `Agent` and registering via `ctx.agents.register()`.
 - Event listeners: all `agent/*` events are declared here — no dependency on the loop package needed.
-- Subagent delegation is not an `Agent` method; providers create or drive ordinary handles through the factory seam, so delegation transports stay outside the core agent interface.
+- Subagent delegation is not an `Agent` method; providers create or drive ordinary handles through the factory API, so delegation transports stay outside the core agent interface.
 
 ## Model Experience
 
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index e140d76c94..44f6748334 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -12,7 +12,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 
 ### 公开 API
 
-带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installModelSelection(agentCtx, selection)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将其中的提供方和模型应用到提示词变量，并将完整选择应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使适配器／提供方默认值生效。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
+带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installAgentLlmTarget(agentCtx, target)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将路由应用到提示词变量，并将完整目标应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使该目标使用适配器／提供方默认值。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
 
 `AgentOptions` 提供初始的提供方／模型路由，以及可选的正数 `maxTokens` 输出上限。具体循环会解析确切模型的适配器默认值，把生效上限记录到请求 header，并应用到每次对话模型请求；显式 Agent 选项优先，省略时由适配器或提供方路由默认值控制。
 
@@ -34,7 +34,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 
 该作用域携带 `Agent` 本身，并且只在进程内有效。环境中的身份既不是存活证明，也不是授权；在服务、worker、进程、持久化和 wire 边界，显式 Agent 字段仍是权威来源。Teardown 会拒绝新边界，允许注入的依赖方和返回 Promise 的边界 drain，然后禁用底层 `AsyncLocalStorage`；未返回的工作仍归将其分离的子系统所有。如果某个边界继承的异步链开始卸载一个拥有它的 Cordis fiber，该嵌套边界链会从 drain 中释放，使卸载不会等待自身；其 continuation 会在 teardown 后观察到已 dispose 的服务。详细边界与 teardown 约定由[发起方作用域决策](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)拥有。
 
-#### 工厂 seam（创建）
+#### 工厂 API（创建）
 
 Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，并通过 `setFactory` 注册。这样，创建功能留在 `dsh-agent` 接口上，消费方（UI、ACP（Agent Client Protocol）桥接层）可以面向 `ctx.agents` 编程，而不依赖具体循环包。注册表会把已经 traced 的 Service 规范化为具体目标，并通过调用方上下文重新 trace 每次调用；这既避免嵌套 Cordis shadow，也会把显式、绑定调用方的 `ownerCtx` 传给普通工厂。
 
@@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序约定。
 
-大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
+大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次扩展点在 payload 中携带显式 `AbortSignal`；其余轮次作用域扩展点通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
 `PreStepDecision` 要么是 `{ kind: 'reject' }`，要么是 `{ kind: 'enter', messages }`。enter 分支是拟进入步骤的完整、带标识且冻结的批次。包装下游 enter 的监听器会保留该批次，除非有意替换它；新增消息遵循 waterfall 的自然返回顺序。领取操作已经把候选消息从 inbox 删除，因此 reject 不会保留它们；领取后插入的消息仍等待后续边界。
 
@@ -76,7 +76,7 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 
 - Agent 创建：`AgentLoop.create()` 是具体配置路径实现（位于 `dsh-agent-loop`），程序化消费方则通过 `ctx.agents.create()`/`ctx.agents.resume()` 创建或恢复有所有权的 agent。替换循环时，应实现 `Agent` 并通过 `ctx.agents.register()` 注册。
 - 事件监听器：全部 `agent/*` 事件都在此处声明，不需要依赖循环包。
-- subagent 委派不是 `Agent` 方法；提供方通过工厂 seam 创建或驱动普通 handle，因此委派传输留在核心 agent 接口之外。
+- subagent 委派不是 `Agent` 方法；提供方通过工厂 API 创建或驱动普通 handle，因此委派传输留在核心 agent 接口之外。
 
 ## 模型体验
 
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index 4448847cd8..d457277035 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -68,7 +68,7 @@ export class Inbox {
    * @param target - whether this boundary also consumes one queued turn.
    * @param turn - turn that will own the claimed batch.
    * @returns next-step input followed by the queued turn, when requested.
-   * @internal - the agent loop's step-boundary operation, not a plugin seam.
+   * @internal - The agent loop's step-boundary operation, not a plugin extension point.
    */
   claim(target: InboxTarget, turn: number): UserMessage[] {
     const claimed = this.mutate('next-step', 0, this.nextStep.length, [], false)
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 44c55d80a2..bedfc819dc 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -312,7 +312,7 @@ export class AgentRegistry extends Service {
    * Read the initiating Agent and fail when no initiator boundary is active.
    * Use this for private helpers contractually below a driver, or for a
    * deployment-owned outbound request whose contract forbids agentless calls.
-   * Generic or direct-call seams use optional lookup or explicit request fields.
+   * Generic or direct-call paths use optional lookup or explicit request fields.
    * @returns the inherited Agent.
    * @throws when no initiator is active or this service instance has been disposed.
    */
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index ba9afa50d7..d21f25cdc7 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -147,7 +147,7 @@ declare module 'cordis' {
     // ---- lifecycle (emit) ----
     /**
      * A fully configured agent and live session were published. Setup is
-     * composition-only; `agent/session-start` is the first startup-driving seam.
+     * composition-only; `agent/session-start` is the first startup-driving extension point.
      * Synchronous listener failure vetoes publication, while returned-promise
      * rejection is reported. Detach requested during dispatch waits until every
      * creation listener has observed the stable entry.
@@ -215,7 +215,7 @@ declare module 'cordis' {
      */
     'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 
-    // ---- the machine's extension seams ----
+    // ---- the machine's extension points ----
     /**
      * Reject a proposed step or replace the messages that enter it. Calling
      * `next()` preserves the current messages.
@@ -232,7 +232,7 @@ declare module 'cordis' {
      * Replace the frozen call configuration. `await next()` yields the config
      * the machine would use (agent options on the first request, the logged
      * header afterwards); return a replacement to switch. Model-visible
-     * content must use logged channels; this seam cannot mutate messages.
+     * content must use logged channels; this waterfall cannot mutate messages.
      * @param payload.agent - the agent making the model call.
      * @param payload.turn - the open turn number.
      * @param payload.step - the step whose request this is.
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 71cb01a34d..c5ed6a2c98 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 09e027c82fe1a81d97b3e70d95231ccc553e3ed1
-README.zh.md: 3fdd1e68b18f5ce4b3846ca0d2376b968a0754e3
+README.md: db477d94037d3463870fc8e66ea35d5e607fb6fe
+README.zh.md: 1ce1e823a7e0fdbcf7b6898764a89c52b74adf6a
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 09e027c82f..db477d9403 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -26,7 +26,7 @@ Use the split lifecycle only when teardown must be ordered with another resource
 - `enter(session)` performs the collision check, publishes without announcing, and returns an entry-bound idempotent detach. Concurrent same-id preparations are allowed, but only one entry succeeds; a stale detach cannot remove its replacement.
 - `announce(session)` emits the single creation edge and rejects repeat or reentrant announcements. Detach during that dispatch is deferred and later emits the paired disposal edge; an unannounced entry emits neither lifecycle edge.
 
-`dsh-agent-loop` uses this split so final loop flush precedes session detach; see the [ownership Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md).
+`dsh-agent-loop` uses this split so final loop flush precedes session detach; see the [ownership Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md).
 
 ### Live service events
 
@@ -87,8 +87,8 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 ### Extension points
 
-- Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers and assistant messages require provider/model. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
+- Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata contract (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
+- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model, and assistant messages require provider/model provenance. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
 - Compaction: `dsh-compact-basic` appends a `user/message` replacement for summary checkpoints, while `dsh-compact-tool-result-prune` appends a content-only `tool/result` replacement. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership, replacement validation, and `replaceGeneration`.
 
 ## Model Experience
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index 3fdd1e68b1..1ce1e823a7 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -26,7 +26,7 @@
 - `enter(session)` 执行冲突检查，在不通知的情况下发布，并返回一个绑定到该条目的幂等脱离函数。允许并发准备相同 id，但只有一个条目能够成功进入；陈旧的脱离函数无法移除其替代项。
 - `announce(session)` 发出唯一一次创建边，并拒绝重复或重入通知。该次分发期间请求的脱离操作会延后，之后再发出成对的释放边；未通知的条目不会发出任何生命周期边。
 
-`dsh-agent-loop` 使用这一拆分，以保证循环的最终刷新先于会话脱离；详见[所有权 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md)。
+`dsh-agent-loop` 使用这一拆分，以保证循环的最终刷新先于会话脱离；详见[所有权 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md)。
 
 ### 实时服务事件
 
@@ -87,8 +87,8 @@
 
 ### 扩展点
 
-- 持久化插件：订阅 `session/event`（延后写入），并在 `session/flush`（受等待）及 fiber dispose（资源释放）时排空。持久后端读取日志并重新加载到实时会话；这类后端会把元数据 seam（`SessionHeader`、`session.header`）与日志一同存储。
-- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头和 assistant 消息都必须包含提供方／模型。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
+- 持久化插件：订阅 `session/event`（延后写入），并在 `session/flush`（受等待）及 fiber dispose（资源释放）时排空。持久后端读取日志并重新加载到实时会话；这类后端会把元数据约定（`SessionHeader`、`session.header`）与日志一同存储。
+- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头必须包含提供方／模型，assistant 消息必须包含提供方／模型溯源信息。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
 - 压缩：`dsh-compact-basic` 为摘要检查点追加一个替换用 `user/message`，而 `dsh-compact-tool-result-prune` 追加仅修改内容的 `tool/result` 替换。工具配对边界策略及其缓存归 [`dsh-compact` seam](../../compact/compact/README.md) 所有；此包拥有有序 surface 成员关系、替换校验与 `replaceGeneration`。
 
 ## 模型体验
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 1c1d2a3023..2e9bf49271 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -915,7 +915,7 @@ export class SessionStore extends Service {
    * another create) between them, so a stale prepared session must NOT overwrite
    * a live store entry of the same id — its detach disposer would later delete
    * the REAL session. The {@link create} convenience and the agent factory call
-   * the two back-to-back so they never trip this, but the public seam cannot
+   * the two back-to-back so they never trip this, but the public API cannot
    * assume that.
    *
    * @param session - a {@link prepare}d session not yet in the store.
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index 57641e4618..7d4e8f07bb 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
-README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5827ae27706505bde86a4ee0d86542a7a2ff63d9
+README.md: 13b05bfcd19212ade42f22ece455871d022e6260
+README.zh.md: 0f9e7a2358134018975db1bc3c6b7206a274b3ec
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index e98c45a882..13b05bfcd1 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -19,7 +19,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem
 - `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. The layer is the calling context's scope: `agent.ctx` contributes to that agent alone, shadowing a same-named global section there. Duplicate names within one layer and non-finite orders throw. Disposed with the calling fiber.
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void` Contribute tool schemas, evaluated at each assembly with that assembly's context. `ToolProviderResult` = `{ schemas, knownNames? }`: `schemas` is the post-restriction visible set; `knownNames` is the pre-restriction universe used by `toolOrder`. A provider must not return a schema named `TOOL_ORDER_REST`. Scoped providers are consulted only for their scope's assemblies. Disposed with the calling fiber.
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Scoped variables shadow a same-named global for that agent. Duplicate-in-layer or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
-- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform seam. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name.
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform waterfall. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name.
 
 ### Live events
 
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5827ae2770..0f9e7a2358 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -19,7 +19,7 @@
 - `ctx.systemPrompt.section(section: PromptSection): () => void`：贡献一个段。层由调用上下文的作用域决定：`agent.ctx` 只为该 agent 贡献，并在该处遮蔽同名全局段。同一层中的重复名称和非有限顺序会抛出。随调用 fiber 一并 dispose（资源释放）。
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void`：贡献工具 schema；每次组装时使用该次组装的上下文求值。`ToolProviderResult` = `{ schemas, knownNames? }`：`schemas` 是限制后的可见集合；`knownNames` 是限制前由 `toolOrder` 使用的全集。提供方不得返回名为 `TOOL_ORDER_REST` 的 schema。带作用域提供方只在其作用域的组装中查询。随调用 fiber 一并 dispose。
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void`：贡献提示词变量，在段文本中以 `{{name}}` 引用。带作用域变量会为该 agent 遮蔽同名全局变量。同层重复或无法引用的名称会抛出；`undefined` 表示「本次组装没有值」。随调用 fiber 一并 dispose。
-- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 seam 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 waterfall 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
 
 <a id="live-events"></a>
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 80c185d9b3..9d9ed71d8d 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: 73c18552baa4b8b68c3d34c2d928d479548180ba
-README.zh.md: 9812fd50b2500b6393c9328ea1c366eb04963e74
+README.md: b1de96293f8ec823ec52d6142a46de877f7fc5e6
+README.zh.md: fa42f7c02a09579bd7b1c995246696d8808889de
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 73c18552ba..b1de96293f 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -186,7 +186,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Concurrency policy is not an event seam** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own.
+- **Concurrency policy is not an event gate** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own.
 - **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md).
 - **Caller-defined subagent and workflow structured outputs remain object-rooted** — this is a consumer-level guard; the shared schema vocabulary and tool outputs support every JSON root.
 - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 9812fd50b2..fa42f7c02a 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -186,7 +186,7 @@ The available tools:
 
 ## 已知限制与暂缓事项
 
-- **并发策略不是事件 seam**：`executionMode()` 直接读取已解析的工具定义；插件只能在自身拥有的定义上声明分类器。
+- **并发策略不是事件门禁**：`executionMode()` 直接读取已解析的工具定义；插件只能在自身拥有的定义上声明分类器。
 - **`tools/pre-execute` 有意不允许改写 `exec.arguments`**：否则日志记录和呈现的参数会与实际运行内容失去同步；改写设计记录在[拟议的 Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)中。
 - **调用方定义的 subagent 与工作流结构化输出仍要求对象根**：这是消费方层面的守卫；共享 schema 词汇和工具输出支持任意 JSON 根。
 - **定义上的 `timeoutMs` 仅为声明**：注册表绝不会强制执行截止时间；要强制执行，必须使用 `@deepseek-ai/dsh-timeout-policy` 包装层。
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index aa4a1f027a..2ec5a1bb25 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -373,7 +373,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
 
       let dispatches = 0
       // The per-run scheduler, reusing the NATIVE concurrency contract through
-      // the registry's staged view (the loop scheduler's own seam) — and the
+      // the registry's staged view (the loop scheduler's own boundary) — and the
       // native loop's SEQUENCING: every ordered stage (the dispatch-start
       // append, prepare = pre-execute/guards, finalize/finish = post-execute,
       // context deferral, the settle append) runs inside ONE driver lane, so
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 657de4578e..7c2346e723 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -148,7 +148,7 @@ declare module 'cordis' {
     'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
     /**
      * Accept, replace, enrich, or block a normalized dispatch result. `next()`
-     * accepts it unchanged; thrown tools still reach this seam as errors. Async
+     * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
      * listeners must observe `exec.signal`; after they settle, caller
      * cancellation replaces only a successful accepted outcome with the code
      * selected by whether the tool body was invoked.
@@ -418,7 +418,7 @@ export type ScheduledToolDispatch =
 /**
  * Symbol-keyed scheduler view that keeps pre/post policy ordered while
  * overlapping dispatch. Ordinary callers use {@link ToolRegistry.execute};
- * this is not a plugin seam.
+ * this is not a plugin extension point.
  * @internal
  */
 export interface ToolRegistryScheduler {
@@ -1069,7 +1069,7 @@ export class ToolRegistry extends Service {
    * shaping must never fail the dispatch or lose the settle event. Private:
    * the ONE consumer is the `run_code` bridge this registry constructs, which
    * receives it as a capability parameter (the `requireRuntime` idiom) — the
-   * waterfall, not this invoker, is the public extension seam.
+   * waterfall, not this invoker, is the public extension point.
    */
   private async shapeDispatchLog(dispatch: CodeDispatchLog): Promise<ContentBlock[]> {
     try {
diff --git a/packages/core/tools/src/presentation.ts b/packages/core/tools/src/presentation.ts
index 5ca7bc5989..b719e16472 100644
--- a/packages/core/tools/src/presentation.ts
+++ b/packages/core/tools/src/presentation.ts
@@ -310,8 +310,8 @@ export interface ReadResultView {
 /**
  * One citeable source in a completed {@link WebSearchResultView}, the faithful
  * projection of one web-search source. The presentation projection of `dsh-web`'s
- * `WebSearchSource`: that seam type is the authoritative shape (core cannot depend
- * on the web seam, so the two are declared separately and MUST evolve together).
+ * `WebSearchSource`: that Service Definition type is authoritative (core cannot depend
+ * on the web Service Definition, so the two are declared separately and MUST evolve together).
  * A web tool projects this shape through `output.presentationMeta` because the
  * render text cannot losslessly carry it (see the web-result-card Agent Note); its
  * `presentResult` reads it back.
@@ -361,7 +361,7 @@ export interface WebSearchResultView {
   sources: WebSource[]
   /** The provider-generated answer text, when any. */
   answer?: string
-  /** True when the seam cut the source list to honor the result cap. */
+  /** True when the web service cut the source list to honor the result cap. */
   truncated: boolean
 }
 
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index d1358124c3..33c05db92e 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -500,7 +500,7 @@ function renderType(schema: unknown, className: string, state: RenderState): str
     ({ schema, className, phase: 'start', listDepth, children: [], childIndex: 0, childTypes: [], entries: [] })
   try {
     // Validate the WHOLE tree once, then trust it — the same contract the
-    // sibling ts-types renderer follows at a typed same-process seam. Every
+    // sibling ts-types renderer follows at a typed same-process boundary. Every
     // node past this point is a validated JSON-schema node, so the walk reads
     // its fields without re-checking. An unsupported or malformed schema throws
     // here (before anything is emitted) and degrades to `Any`, the Python
diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts
index e2c2c8be7e..06993467e8 100644
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -19,7 +19,7 @@ const testToolSignal = new AbortController().signal
  * misconfiguration rejections, the run_code dispatch bridge (serialization,
  * abort, JSON normalization, error mapping, events, quiescence), and HMR
  * safety — all against an in-repo fake runtime, exactly the
- * interface/implementation/consumer shape the seam promises.
+ * Service Definition / Service provider / Consumer roles the seam promises.
  */
 
 /** A scriptable in-repo CodeRuntime: each test sets `behavior` to drive the bindings however it needs. */
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index 4149a21273..cfb1f6db05 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -1068,7 +1068,7 @@ describe('ToolRegistry', () => {
 
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'traced', arguments: { text: 'hi' } })
     expect(result).toEqual({ content: [{ type: 'text', text: 'hi' }], isError: false, value: [{ type: 'text', text: 'hi' }] })
-    // The around seam wraps dispatch; pre gates before it, post runs over its result.
+    // The around-dispatch extension point wraps dispatch; pre gates before it, post runs over its result.
     expect(order).toEqual(['pre', 'execute:before', 'dispatch', 'execute:after', 'post'])
   })
 
@@ -1646,7 +1646,7 @@ describe('ToolRegistry', () => {
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
     expect(result.isError).toBe(true)
     expect(result.content[0]).toMatchObject({ text: 'Error: nope' })
-    expect(entered).toBe(false) // a denied call never enters the around-dispatch seam
+    expect(entered).toBe(false) // A denied call never enters the around-dispatch extension point.
   })
 
   it('a thrown tool is normalized to an isError result BEFORE a tools/execute listener sees next()', async () => {
diff --git a/packages/credentials/credentials-local/src/invariant.ts b/packages/credentials/credentials-local/src/invariant.ts
index 9ec75ed21d..454f2b808e 100644
--- a/packages/credentials/credentials-local/src/invariant.ts
+++ b/packages/credentials/credentials-local/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'credentials-local-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the seam companion (`dsh-credentials/invariant`) owns the
+ * No runtime invariant: the Service Definition companion (`dsh-credentials/invariant`) owns the
  * `credentials/updated` lifecycle contract; this provider's file/environment layering is
  * asynchronous I/O pinned by its unit suite.
  */
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index 34c5ffc794..053af47617 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/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/credentials/credentials/README.md
-README.md: 95ef76d145727340d8135bf1d48babd6d8adb882
-README.zh.md: dce426fde734e3368317ccd2fa6848ca1e00048e
+README.md: fc4fb16991a3396f106bed65b468d0ae538bbab8
+README.zh.md: 6007618e5dc917ebc38fd322b34427cb5281e70c
diff --git a/packages/credentials/credentials/README.md b/packages/credentials/credentials/README.md
index 95ef76d145..fc4fb16991 100644
--- a/packages/credentials/credentials/README.md
+++ b/packages/credentials/credentials/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Abstract credential seam (`ctx.credentials`). One doctrine, three consequences:
+Credential Service Definition (`ctx.credentials`). One doctrine, three consequences:
 
 **Configuration carries references to secrets, never the secrets.** A settings section or `cordis.yml` entry says `apiKeyEnv: DEEPSEEK_API_KEY`; the value behind that reference lives with a credential provider. So the settings document stays safe to sync and to render in a configuration UI, `describe()` can answer "is this configured, where from, can I write it" without ever holding a value, and rotating a secret touches no configuration file.
 
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index dce426fde7..6007618e5d 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象凭据 seam（`ctx.credentials`）。一条准则，三个推论：
+凭据 Service Definition（`ctx.credentials`）。一条准则，三个推论：
 
 **配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据提供方所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
 
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index c6470c1628..5f1efb010c 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Credential seam (`ctx.credentials`). Settings and composition files carry
+ * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
  * *references* to secrets — environment-variable names — while providers own
  * the actual values and their storage. Consumers resolve a reference once per
  * operation, so a changed credential reaches the next operation without any
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index a8edcb34ab..90c7931644 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: cd170bcbe2831b0856b51791a2045382d93c1148
-README.zh.md: f97790cf1d4ef90f042df8ed564723e186327f00
+README.md: b346b4c5bc7bc2888ccd3dc210bb90e0f1cc5965
+README.zh.md: b84b2382c03dc6e422228b19a58aff927e8a5db7
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index cd170bcbe2..b346b4c5bc 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -2,14 +2,14 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider contract. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
 
 ## Behavior
 
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the filesystem seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index f97790cf1d..b84b2382c0 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -2,14 +2,14 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方约定的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
 
 ## 行为
 
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留文件系统 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 84c9ac7868..83ff7bd99b 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * E2B implementation of the filesystem provider seam. Paths, contents, and
+ * E2B provider for the filesystem capability seam. Paths, contents, and
  * atomic staging files remain inside the shared remote sandbox.
  * @module @deepseek-ai/dsh-fs-e2b
  */
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index d0ce148746..d6f23acf04 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 926d4f22f8e96daa103c236121d35e461290221a
-README.zh.md: d1634b6d1a701f7f4815135b4ec6bb86ad1a8c87
+README.md: bb0ac1d5f1f3dbfd0f021d5fbebbab13dcee37ee
+README.zh.md: d511df72284b047626ece628b702a2ac8d2f873d
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 926d4f22f8..bb0ac1d5f1 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -24,7 +24,7 @@ The default E2B base image supplies the runtime and Bash/GNU utilities this adap
 
 ## Model Experience
 
-Indirectly, through consumer seams such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
+Indirectly, through Consumers such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
 
 #### KV Cache effect
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index d1634b6d1a..d511df7228 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -24,7 +24,7 @@ E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：
 
 ## 模型体验
 
-通过消费方 seam 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些消费方会渲染远程输出、退出事实、后台增量和 spill 路径。
+通过 Consumer 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些 Consumer 会渲染远程输出、退出事实、后台增量和 spill 路径。
 
 #### KV Cache 影响
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index c6d2dbd4eb..3c0063c457 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * E2B implementation of the subprocess seam. Each handle starts through the
+ * E2B Service provider for the subprocess capability seam. Each handle starts through the
  * shared sandbox and retains command output/status paths in that remote world.
  * @module @deepseek-ai/dsh-subprocess-e2b
  */
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index c80a2f5bd9..2dc552b575 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -184,7 +184,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private terminationSignal: NodeJS.Signals | null = null
 
   /**
-   * Begin an E2B command without blocking the synchronous subprocess spawn seam.
+   * Begin an E2B command without blocking the synchronous subprocess spawn call.
    * @param runtime - Shared E2B sandbox owner.
    * @param spec - Fully resolved subprocess request.
    * @param stateDir - Remote directory retaining process identity, status, and valid spills.
diff --git a/packages/examples/agent-spine-demo/README.i18n.yaml b/packages/examples/agent-spine-demo/README.i18n.yaml
index 43cdef4af8..a698160634 100644
--- a/packages/examples/agent-spine-demo/README.i18n.yaml
+++ b/packages/examples/agent-spine-demo/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/examples/agent-spine-demo/README.md
-README.md: d1c3c28183956b4f66db7ed4a6f3a08588b5352c
-README.zh.md: cf372a428c16893b1d328ea60ad70c09d6d9725c
+README.md: cfec2c46ada8ed97aef44fb1d4145ddecdeecab1
+README.zh.md: d482ea9ca7034874383472050a8c837bea5bfaad
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index d1c3c28183..cfec2c46ad 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -49,7 +49,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
 - **front-door + per-app infrastructure** — headless, ACP, and JSON-RPC app packages own transport, stdout, and reload choices. `timer` stays in the spine because it is common and stdout-silent.
 
-This is the [interface/implementation/consumer seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
+This applies the [Service Definition / Service provider / Consumer separation](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) at the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
 
 ## Config
 
@@ -80,4 +80,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Most of the spine set is fixed in code** — `apply()` always mounts the core services; config can omit bundled goals, skills, bash, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
-- **The invariant seam and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
+- **The invariant service and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
diff --git a/packages/examples/agent-spine-demo/README.zh.md b/packages/examples/agent-spine-demo/README.zh.md
index cf372a428c..d482ea9ca7 100644
--- a/packages/examples/agent-spine-demo/README.zh.md
+++ b/packages/examples/agent-spine-demo/README.zh.md
@@ -49,7 +49,7 @@
 - **非本地 skill 提供方**：组合包交付 skill 注册表、本地文件系统提供方和 `skill` 工具；部署可以把嵌入式目录或远程目录等其他提供方作为同级插件添加。
 - **前端入口与各应用基础设施**：无头、ACP（Agent Client Protocol）和 JSON-RPC 应用包负责传输、stdout 与重新加载选择。`timer` 保留在主干中，因为它是共有组件且不写 stdout。
 
-这把[接口／实现／消费方 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) 提升到组合层：组合包拥有共享主干，叶节点拥有后端，应用包拥有前端入口。
+这里在组合层应用 [Service Definition／Service provider／Consumer 的职责分离](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：组合包拥有共享主干，叶节点拥有后端，应用包拥有前端入口。
 
 ## 配置
 
@@ -80,4 +80,4 @@ YAML include 可以去重配置，却无法拥有 bin 或提供前端入口默
 ## 已知限制与暂缓事项
 
 - **大部分主干集合固定在代码中**：`apply()` 始终挂载核心服务；配置可以省略组合包内的目标、skill、bash 与任务控制工具，但要替换循环或删除其他主干成员，就必须组合另一个组合包。
-- **不变式 seam 与配套插件仍是固定成员**：`invariants.enabled: false` 或包筛选器会抑制检查，但不会移除服务或配套插件注册；Session 始终启用的校验与冻结是另一套机制。
+- **不变式服务与配套插件仍是固定成员**：`invariants.enabled: false` 或包筛选器会抑制检查，但不会移除服务或配套插件注册；Session 始终启用的校验与冻结是另一套机制。
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index aa010c33f2..edda1470df 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
-README.zh.md: 196a2aad89203905148581d6364be7f02e2f4e35
+README.md: fad17083817bd8023649ef7d0f0f1b62fbb9295f
+README.zh.md: e8544d71ee853547400e5970f0db9a9946562d48
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 162e2c75e9..fad1708381 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The filesystem stack: a provider seam (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
+The filesystem stack: a provider contract (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
+| `fs/` | Service Definition: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
 | [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
@@ -14,10 +14,10 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The Service Definition lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the Service Definition, policy gate, or model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider contract: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 196a2aad89..e8544d71ee 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -2,22 +2,22 @@
 
 [English](README.md) | 中文
 
-文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、策略门禁插件（已观察状态、编辑前读取、版本防护的写入／编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品**包。
+文件系统栈包括：提供方约定（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
-| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 策略事件 | `ctx.fs` |
+| `fs/` | Service Definition：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
 | [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
-| `fs-sandbox/` | 强制实施沙箱约束的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根策略约束写入／编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
-| `fs-policy/` | 策略门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、策略门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。策略（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去策略，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+Service Definition 位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方约定：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
-`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方约定也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
 
-子系统参考——目标、结果、守卫、策略事件、错误分类体系，以及文件 I/O 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
+子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 250b94dacf..dd384cd2b1 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-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/fs/fs-local/README.md
-README.md: 2e934298ceff75440357b0742770010c8b1c3904
-README.zh.md: 14f4867ce0f9eaae2a1dea98dbd7d401c98d4535
+README.md: ec0cffea1c82ab3bb2485fcb22ac5339d5d2a0d9
+README.zh.md: 99adba8c8b58f1f0b6f0f5ab8b672eb074b38f31
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 2e934298ce..ec0cffea1c 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 14f4867ce0..99adba8c8b 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index c93e4ddaeb..7e063ca347 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -70,7 +70,7 @@ function versionOf(info: BigIntStats): FsVersion {
 }
 
 /**
- * Test seam: lets specs pin the atomic-write temp names (to prove
+ * Test hook: lets specs pin the atomic-write temp names (to prove
  * exclusive-open behavior without a name race) and observe the staged temp
  * file before it is renamed over the target.
  */
@@ -427,7 +427,7 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
  * inert as a mode on Windows but identifies replacement security semantics.
  * @param signal - cancellation checked before the final rename.
- * @param internals - test seam for pinning temp names and observing the staged file.
+ * @param internals - Test hook for pinning temp names and observing the staged file.
  */
 export async function writeFileAtomic(
   absolutePath: string,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index f6049b1795..6f9af5cec2 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -56,7 +56,7 @@ export class LocalFileSystem extends FileSystem {
 
   /** Validated config (schemastery applied the defaults before construction). */
   readonly config: ResolvedConfig
-  /** Test seam forwarded to fsio (force streaming path, pin temp names). */
+  /** Test hook forwarded to fsio (force streaming path, pin temp names). */
   internals: FsIoInternals = {}
   /** Per-targetKey tail promise: serializes mutating ops so the read→guard→write
    * window can't interleave, making concurrent writes/edits deterministically
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 4906bb0adc..ee3abeebb8 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the local backend through the `ctx.fs` provider seam: stat, whole-
+ * Tests for the local backend through the `ctx.fs` Service Definition: stat, whole-
  * file/streamed text reads, atomic guarded writes (createIfAbsent /
  * replaceIfVersion), version-guarded literal edits, concurrency races, symlink
  * identity, and HMR/disposal. Read WINDOWING is policy and lives in
@@ -55,7 +55,7 @@ describe('registration', () => {
 describe('resolve', () => {
   it('resolves a relative path against opts.cwd, not config.cwd', async () => {
     // config.cwd is `dir`; a call supplying a DIFFERENT cwd bases the relative
-    // path there (the per-session-workspace seam — mirrors tool-bash workdir).
+    // path there (the per-session workspace mapping — mirrors tool-bash workdir).
     const other = await mkdtemp(join(tmpdir(), 'dsh-fs-other-'))
     try {
       await writeFile(join(other, 'x.txt'), 'in other')
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index e4d85c9a88..c2b72c65c8 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: f6b3292bdc6e5565df0393a59c50d4e594921401
-README.zh.md: 2ebd2f054ece0472c7147f6f9e740987b11c6031
+README.md: bf6486f6f7fe574b576a71b430be91031f7805d2
+README.zh.md: 2e38d63d8e310c7f22b764d46cbec0c82ffb96cf
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index f6b3292bdc..bf6486f6f7 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **fs-policy plugin**: it adds observed-state, read-before-edit, and version-guarded write/edit on top of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
+The **fs-policy plugin**: it adds observed-state, read-before-edit, and version-guarded write/edit on top of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
 
 ```ts
 import type { Context } from 'cordis'
@@ -24,7 +24,7 @@ await ctx.plugin(FsPolicy)
 |---|---|---|
 | tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
 | policy | `@deepseek-ai/dsh-fs-policy` (this) | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
-| provider seam | `@deepseek-ai/dsh-fs` | `ctx.fs`: text IO + atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider contract | `@deepseek-ai/dsh-fs` | `ctx.fs`: text IO + atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
 | provider | `@deepseek-ai/dsh-fs-local` | local implementation of `ctx.fs` |
 
 ## How the gate participates
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index 2ebd2f054e..2e38d63d8e 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**fs-policy 插件**：它在 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的策略层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的策略。
+**fs-policy 插件**：它在 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的策略层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的策略。
 
 ```ts
 import type { Context } from 'cordis'
@@ -24,7 +24,7 @@ await ctx.plugin(FsPolicy)
 |---|---|---|
 | 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
 | 策略 | `@deepseek-ai/dsh-fs-policy`（本包） | 通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑（无服务） |
-| 提供方 seam | `@deepseek-ai/dsh-fs` | `ctx.fs`：文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 提供方约定 | `@deepseek-ai/dsh-fs` | `ctx.fs`：文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | `ctx.fs` 的本地实现 |
 
 ## 门禁的参与方式
diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts
index 5e0121c89a..1d5f972da9 100644
--- a/packages/fs/fs-sandbox/src/index.ts
+++ b/packages/fs/fs-sandbox/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * `SandboxedFileSystem`: the sandbox-enforcing implementation of the
- * `@deepseek-ai/dsh-fs` provider seam. It extends `LocalFileSystem` so all
+ * `@deepseek-ai/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
  * text-storage mechanics — resolve, stat, read/stream, list, the atomic
  * write and the read-match-write edit critical section — are the local
  * implementation's, verbatim; this package adds only the per-call POLICY fence
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 5ed8633331..a77f4c8e04 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 11134e6298e6c87d1046952c65bb2dadff43e4a2
-README.zh.md: 7edece618150739d5ff67c605788dae42a5a5c32
+README.md: c7c978b7530a9b26e178f164dae61ae60f8f321f
+README.zh.md: 9761fc81bcb160edfc96d42cea45183abcfc087d
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 11134e6298..c7c978b753 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
 
 The **`FileSystem`** (`ctx.fs`) defines the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
-This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
+This package owns the Service Definition and provider contract layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
 | Layer | Package | Role |
 |---|---|---|
 | tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing `read`/`write`/`edit` schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
 | policy | `@deepseek-ai/dsh-fs-policy` | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
-| provider seam | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider contract | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
 | provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
 
 A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
@@ -39,7 +39,7 @@ The mutation runs inside the backend's per-target lock either way, so an uncondi
 
 This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
-## A provider seam, not the policy layer
+## A provider contract, not the policy layer
 
 `ctx.fs` is deliberately close to fsspec-style storage primitives — half a level above byte-level `cat`/`open`, because it decodes text and rejects binaries so the policy layer never touches raw bytes. It owns UTF-8 decoding, binary rejection, atomic writes, and the literal-edit critical section. It does **not** own line windows, numbered lines, rendered footers, or observed-state. Observed-state, read-before-edit, and version-guarded write/edit are policy a plugin (`@deepseek-ai/dsh-fs-policy`) ADDS by supplying the optional guard — not provider behavior — so a sandboxed/remote backend inherits no model-facing observation policy.
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 7edece6181..9761fc81bc 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,18 +2,18 @@
 
 [English](README.md) | 中文
 
-**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
-本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
+本包是四层文件系统栈中的提供方约定层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
 | 层 | 包 | 角色 |
 |---|---|---|
 | 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
-| 策略 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
-| 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 提供方约定 | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
 
-未来的沙箱化、虚拟或远程后端只需实现该接口，策略层和工具层无需改变。
+未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
@@ -26,7 +26,7 @@
 | `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
 | `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
@@ -35,15 +35,15 @@
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 策略事件
+## `fs/*` 政策事件
 
-本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是策略层
+## 提供方约定，不是政策层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
@@ -55,9 +55,9 @@
 
 #### KV Cache 影响
 
-不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **约定只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
 - **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index 2d46868a57..b4e3884c3b 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Filesystem provider seam for one execution world. Backends own stable target
+ * Filesystem Service Definition for one execution world. Backends own stable target
  * identity, process paths and file URIs, containment, text reads, decoding,
  * binary rejection, and atomic mutations. Read windows and
  * observed-state policy stay in consumer and policy plugins; `editText`
diff --git a/packages/fs/fs/src/types.ts b/packages/fs/fs/src/types.ts
index f5753f09bd..6a34f3848f 100644
--- a/packages/fs/fs/src/types.ts
+++ b/packages/fs/fs/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the filesystem provider seam (`ctx.fs`): the opaque target/version
+ * Vocabulary for the filesystem Service Definition (`ctx.fs`): the opaque target/version
  * identities, the metadata `stat` returns, the write-intent and outcome shapes, the
  * literal-edit request/outcome, and the typed error taxonomy.
  * @module @deepseek-ai/dsh-fs/types
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index f225e51cc0..2340871304 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the filesystem provider seam itself: registration, duplicate-service
+ * Tests for the filesystem Service Definition: registration, duplicate-service
  * behavior, disposal, and the branded id factories. The provider primitives and
  * policy live in `dsh-fs-local` and `dsh-fs-policy`; this seam owns only the
  * abstract service contract, so a minimal fake backend exercises it.
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index 8db18757f6..f6f036b33c 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: 6f96970d8194c0992f9b955b95aec092185054b2
-README.zh.md: 6cc8ebfe3ca4fc4e7c016aab64a0136cf4a07f14
+README.md: c9375a3ee803db48c547c7553d10f9b5ebde3fd2
+README.zh.md: 70ff15f2beff2674719f3084594e5cc0c7309f68
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 6f96970d81..c9375a3ee8 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) **directly**. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. Under a confining provider, the shared sandbox-policy service is required for per-session execution and the tool exposes escalation for filesystem mutations.
+The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) **directly**. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. Under a confining provider, the shared sandbox-policy service is required for per-session execution and the tool exposes escalation for filesystem mutations.
 
 ```ts ignore-check
 // Default deployment: a ctx.fs provider, the policy plugin, then the tools.
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 6cc8ebfe3c..70ff15f2be 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、**读取窗口逻辑**和结果格式化。它**直接**通过 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）读取／写入／编辑。新鲜度／观察策略由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会为文件系统变更提供升权路径。
+**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、**读取窗口逻辑**和结果格式化。它**直接**通过 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）读取／写入／编辑。新鲜度／观察策略由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会为文件系统变更提供升权路径。
 
 ```ts ignore-check
 // Default deployment: a ctx.fs provider, the policy plugin, then the tools.
diff --git a/packages/fs/tool-fs/src/session-cwd.ts b/packages/fs/tool-fs/src/session-cwd.ts
index 396e50351c..fd4a134acf 100644
--- a/packages/fs/tool-fs/src/session-cwd.ts
+++ b/packages/fs/tool-fs/src/session-cwd.ts
@@ -4,7 +4,7 @@
  * `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
  * `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
  * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
- * `process.cwd()` at the tool seam.
+ * `process.cwd()` at the tool boundary.
  * @module @deepseek-ai/dsh-tool-fs/session-cwd
  */
 
diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml
index 226316dbd7..1b9a48cbc7 100644
--- a/packages/goal/goal-session/README.i18n.yaml
+++ b/packages/goal/goal-session/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/goal/goal-session/README.md
-README.md: 89413062de8cbb49d7066ec3ae42769a99c939a2
-README.zh.md: a39a45232e7a2376154bc35182e77cc3b9ba1569
+README.md: 4534c937fcc53295b83bb207416715ef67b1f911
+README.zh.md: 389d692b44f89dc612efdf06f1e05a3f65eff7fd
diff --git a/packages/goal/goal-session/README.md b/packages/goal/goal-session/README.md
index 89413062de..4534c937fc 100644
--- a/packages/goal/goal-session/README.md
+++ b/packages/goal/goal-session/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Same-session continuation driver for [`ctx.goals`](../goal/README.md). It turns an active, armed goal into sequential [goal rounds](../../../docs/glossary.md#goal-round) through the public `Agent` and session seams; the [same-session driver Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) owns the race and lifecycle rationale.
+Same-session continuation driver for [`ctx.goals`](../goal/README.md). It turns an active, armed goal into sequential [goal rounds](../../../docs/glossary.md#goal-round) through the public `Agent` and session services; the [same-session driver Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) owns the race and lifecycle rationale.
 
 ## Composition
 
diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md
index a39a45232e..389d692b44 100644
--- a/packages/goal/goal-session/README.zh.md
+++ b/packages/goal/goal-session/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`ctx.goals`](../goal/README.md) 的同会话续行驱动器。它通过公开 `Agent` 与会话 seam，把 phase 为 active 且已启用续行的目标转换为连续的 [Goal Round](../../../docs/glossary.md#goal-round)；[同会话驱动器 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) 记载竞态与生命周期方面的设计理由。
+[`ctx.goals`](../goal/README.md) 的同会话续行驱动器。它通过公开 `Agent` 与会话服务，把 phase 为 active 且已启用续行的目标转换为连续的 [Goal Round](../../../docs/glossary.md#goal-round)；[同会话驱动器 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) 记载竞态与生命周期方面的设计理由。
 
 ## 组合
 
diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts
index 5c92f048d8..64c90e0c35 100644
--- a/packages/goal/goal-session/src/index.ts
+++ b/packages/goal/goal-session/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Same-session goal-round driver over public agent, session, and goal seams.
+ * Same-session goal-round driver over public agent, session, and goal services.
  * @module @deepseek-ai/dsh-goal-session
  */
 
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index 3097eeba3b..6e66ab407a 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
-README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
-README.zh.md: 43f60599b737d66578b463386b872ca9cc3108e4
+README.md: 73ca00e858c4ddaeb1ba9ccee7fb7e0cfce518f4
+README.zh.md: c5a5ac391d3b6f0b2d7615a92ac1b7920c2b80e6
diff --git a/packages/guard/README.md b/packages/guard/README.md
index f0a80b1f49..73ca00e858 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Behavioral guard plugins watch the agent loop for unproductive patterns and enforce per-call budgets. A guard is a self-contained consumer of core seams, not a swappable capability.
+Behavioral guard plugins watch the agent loop for unproductive patterns and enforce per-call budgets. A guard is a self-contained consumer of core services and extension points, not a swappable capability.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index 43f60599b7..c5a5ac391d 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -1,8 +1,8 @@
-# guard/ — 循环健康 guard 家族
+# guard/ — 循环卫生 guard 家族
 
 [English](README.md) | 中文
 
-行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是核心 seam 的自包含消费方，而非可替换能力。
+行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是核心服务和扩展点的自包含消费方，而非可替换能力。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/guard/timeout-policy/src/index.ts b/packages/guard/timeout-policy/src/index.ts
index f554b1a93e..1ff88b46a9 100644
--- a/packages/guard/timeout-policy/src/index.ts
+++ b/packages/guard/timeout-policy/src/index.ts
@@ -27,7 +27,7 @@ export const TOOL_TIMEOUT = 'TOOL_TIMEOUT'
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'timeout-policy'
 
-/** The tool registry seam this plugin wraps (`tools/execute`) and reads (`get`). */
+/** The tool registry service this plugin wraps (`tools/execute`) and reads (`get`). */
 export const inject = ['tools']
 
 /**
diff --git a/packages/hooks/README.i18n.yaml b/packages/hooks/README.i18n.yaml
index 3aff382ea6..82051c1e9d 100644
--- a/packages/hooks/README.i18n.yaml
+++ b/packages/hooks/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/hooks/README.md
-README.md: 35989292313c6cef47c02041eb671a73ff7c5786
-README.zh.md: 3d169d1286f38658d98f4c5f8d016ef77e1b6517
+README.md: fe743705ea8c07a2422847606cdfa42227be962f
+README.zh.md: 909ecf8e5414c382603beb7ee3fd0acbecdcfc47
diff --git a/packages/hooks/README.md b/packages/hooks/README.md
index 3598929231..fe743705ea 100644
--- a/packages/hooks/README.md
+++ b/packages/hooks/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception seams ([the interception-seams Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)); a "native hook" is just an ordinary cordis plugin on those seams. These packages are the **bridges** that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.
+The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception points ([the interception extension-points Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)); a "native hook" is just an ordinary Cordis plugin on those extension points. These packages are the **bridges** that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.
 
 | Package | Role | Shape |
 |---|---|---|
diff --git a/packages/hooks/README.zh.md b/packages/hooks/README.zh.md
index 3d169d1286..909ecf8e54 100644
--- a/packages/hooks/README.zh.md
+++ b/packages/hooks/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-hooks 子系统让用户像使用 Claude Code 和 Codex 一样，在生命周期节点扩展 agent（智能体）：把桥接插件指向现有 `hooks.json`（或 settings），即可忠实运行这些外部 shell 钩子。规范扩展 surface 本身是 harness 的类型化拦截 seam（参见[拦截 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)）；“原生钩子”只是这些 seam 上的普通 Cordis 插件。这些包是把外部 shell 钩子协议转换到同一 surface 的**桥接**，也包括它们共同依赖的共享协议格式库。
+hooks 子系统让用户像使用 Claude Code 和 Codex 一样，在生命周期节点扩展 agent（智能体）：把桥接插件指向现有 `hooks.json`（或 settings），即可忠实运行这些外部 shell 钩子。规范扩展 surface 本身是 harness 的类型化拦截点（参见[拦截扩展点 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)）；“原生钩子”只是这些扩展点上的普通 Cordis 插件。这些包是把外部 shell 钩子协议转换到同一 surface 的**桥接**，也包括它们共同依赖的共享协议格式库。
 
 | 包 | 职责 | 形态 |
 |---|---|---|
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index b7c8ec3ee8..61361487ba 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
-README.md: 797d15c357bd26e0db072b30b61c251005021905
-README.zh.md: 8a96cd2f1f91ad2d7a12fc15ffc06ea0c2c1d80f
+README.md: 230f14c2bc053555991e5fb96e2753aef5bbff8a
+README.zh.md: d83ea99065123c9cf0f85c0abbbeeff6eadb17bc
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index 797d15c357..230f14c2bc 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -12,7 +12,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 |---|---|---|
 | Matcher validation + test | `matcherDiagnostic(pattern, mode)` for parse-time diagnostics; `matchesMatcher(pattern, query, mode)` for contained runtime matching | picks its `mode` (`claude` = literal-or-regex, `codex` = always regex) and rejects a config group carrying a diagnostic |
 | Run a hook | `runHook(bash, hook, opts, now)` — stdin payload + env via `ctx.bash`, decode | builds the per-event stdin **payload** + the dialect's **env** |
-| Decode output | `parseHookOutput(exit, stdout, stderr)` → neutral `HookOutput` | maps the neutral `HookOutput` onto a seam-specific typed Decision |
+| Decode output | `parseHookOutput(exit, stdout, stderr)` → neutral `HookOutput` | maps the neutral `HookOutput` onto an extension-point-specific typed Decision |
 | Merge N hooks | `mergeHookOutputs(outputs)` → most-restrictive `MergedHookOutcome` | — |
 | Durable record | `appendHookInvoked` / `appendHookResult` (`hook/*` session events; the result's `decision`/`stderrSummary` derive from the `HookOutput` here) | calls them around each invocation |
 | Detached-run quiescence | `createDetachedRuns()` — track fire-and-forget run chains; `drain()` aborts, then awaits them | passes `signal` to each detached `runHook`, registers `drain` as its effect disposer |
@@ -23,7 +23,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 - **`runHook(bash, hook, options, now)`** — require and forward the caller-owned `options.signal`, serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin surface), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** decodes exit status and structured stdout. Exit 2 blocks with stderr; other failures are non-blocking. A matching hook-specific permission decision overrides the legacy top-level decision; mismatched or missing event discriminators suppress only event-specific fields. Top-level fields remain event-agnostic, and successful non-JSON output is left to the bridge.
 - **`mergeHookOutputs(outputs)`** — fold the results of every hook that matched one point: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined with `\n\n`, `additionalContext`/`systemMessages` accumulated in order.
-- **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no seam awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).
+- **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no extension point awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).
 
 ## `hook/*` session events
 
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index 8a96cd2f1f..d83ea99065 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -12,7 +12,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 |---|---|---|
 | Matcher 校验 + 测试 | `matcherDiagnostic(pattern, mode)` 用于解析时诊断；`matchesMatcher(pattern, query, mode)` 用于隔离的运行时匹配 | 选择自身的 `mode`（`claude` = 字面量或正则，`codex` = 始终使用正则），并拒绝带有诊断的配置组 |
 | 运行 hook | `runHook(bash, hook, opts, now)`：通过 `ctx.bash` 提供 stdin payload + env，再解码 | 构造每个事件的 stdin **payload** + 该方言的 **env** |
-| 解码输出 | `parseHookOutput(exit, stdout, stderr)` → 中性 `HookOutput` | 将中性 `HookOutput` 映射到 seam 特定的类型化 Decision |
+| 解码输出 | `parseHookOutput(exit, stdout, stderr)` → 中性 `HookOutput` | 将中性 `HookOutput` 映射到扩展点特定的类型化 Decision |
 | 合并 N 个 hook | `mergeHookOutputs(outputs)` → 最严格的 `MergedHookOutcome` | （无） |
 | 持久记录 | `appendHookInvoked` / `appendHookResult`（`hook/*` 会话事件；结果的 `decision`／`stderrSummary` 从此处的 `HookOutput` 派生） | 在每次调用前后调用它们 |
 | 脱离运行完全停稳 | `createDetachedRuns()`：跟踪触发后不等待的运行链；`drain()` 先 abort，再等待它们 | 将 `signal` 传给每个脱离的 `runHook`，并将 `drain` 注册为 effect disposer |
@@ -23,7 +23,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 - **`runHook(bash, hook, options, now)`**：要求并转发调用方拥有的 `options.signal`，将 `options.payload` 序列化到 hook stdin（当且仅当 `options.trailingNewline` 时添加尾随换行符），在执行器凭证清理后合并 `options.env`（`dsh-bash` 受信任插件接口），遵循 hook 的 `timeoutSec`（否则使用 `options.defaultTimeoutMs`；默认值属于桥接，其配置默认为 lib 的 `DEFAULT_HOOK_TIMEOUT_MS` 10 分钟参考值），再解码结果（将 `options.expectedEventName` 传递给 codec）。因此取消会到达执行器的进程组终止与 join 边界。它绝不抛出异常：执行器拒绝（基础设施故障）会变为 `HookOutput`，其 `exitCode: undefined`（非阻塞错误）。`now` 会被注入，以便测试持续时间。
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** 解码退出状态与结构化 stdout。退出码为 2 时，会以 stderr 内容阻止执行；其他失败不阻塞。匹配的 hook 特定权限决策会覆盖遗留顶层决策；事件判别字段不匹配或缺失只会抑制事件特定字段。顶层字段仍与事件无关，成功但非 JSON 的输出会留给桥接处理。
 - **`mergeHookOutputs(outputs)`**：折叠在一个点上匹配的每个 hook 结果：权限优先级为 **deny > ask > allow**，从首个 `continue:false` 起，halt 状态保持不变，阻塞原因用 `\n\n` 连接，`additionalContext`／`systemMessages` 按顺序累积。
-- **`createDetachedRuns()`**：跟踪以 emit 形式脱离运行的点是否完全停稳（没有 seam 等待它们）。桥接会跟踪每条运行链，包括 hook 运行及其 continuation，并将 `drain()` 注册为 effect disposer。drain 会触发 tracker 的 abort `signal`（因此仍在运行的 hook 进程会通过 `runHook` 终止，而不是等待到超时），随后在所有已跟踪链结算后 resolve。因此 `fiber.dispose()` resolve 时，不会遗留任何可能作用于已 dispose（资源释放）的上下文的脱离 hook 工作（见 [防御模式](../../../docs/defensive-patterns.md)：dispose 必须达到完全停稳）。
+- **`createDetachedRuns()`**：跟踪以 emit 形式脱离运行的点是否完全停稳（没有扩展点等待它们）。桥接会跟踪每条运行链，包括 hook 运行及其 continuation，并将 `drain()` 注册为 effect disposer。drain 会触发 tracker 的 abort `signal`（因此仍在运行的 hook 进程会通过 `runHook` 终止，而不是等待到超时），随后在所有已跟踪链结算后 resolve。因此 `fiber.dispose()` resolve 时，不会遗留任何可能作用于已 dispose（资源释放）的上下文的脱离 hook 工作（见 [防御模式](../../../docs/defensive-patterns.md)：dispose 必须达到完全停稳）。
 
 ## `hook/*` 会话事件
 
diff --git a/packages/hooks/hook-protocol/src/detached.ts b/packages/hooks/hook-protocol/src/detached.ts
index 8fa21cadf2..92eee06858 100644
--- a/packages/hooks/hook-protocol/src/detached.ts
+++ b/packages/hooks/hook-protocol/src/detached.ts
@@ -1,5 +1,5 @@
 /**
- * Quiescence tracking for emit-shaped hook runs that no seam awaits. Bridges
+ * Quiescence tracking for emit-shaped hook runs that no extension point awaits. Bridges
  * track the run plus its continuation, pass the tracker signal into execution,
  * and drain on disposal so no process or late callback outlives the fiber.
  * @module @deepseek-ai/dsh-hook-protocol/detached
diff --git a/packages/hooks/hook-protocol/src/index.ts b/packages/hooks/hook-protocol/src/index.ts
index d67746f824..68ea0b37dd 100644
--- a/packages/hooks/hook-protocol/src/index.ts
+++ b/packages/hooks/hook-protocol/src/index.ts
@@ -2,7 +2,7 @@
  * Shared, non-plugin hook protocol library: matching, command execution and
  * decoding, restrictive outcome merging, durable event helpers, and detached
  * run quiescence. Claude Code and Codex bridges own their distinct payloads,
- * environment rules, matcher mode, and typed seam mappings.
+ * environment rules, matcher mode, and typed extension-point mappings.
  * @module @deepseek-ai/dsh-hook-protocol
  */
 
diff --git a/packages/hooks/hook-protocol/src/merge.ts b/packages/hooks/hook-protocol/src/merge.ts
index c121135501..c2d25f0ab5 100644
--- a/packages/hooks/hook-protocol/src/merge.ts
+++ b/packages/hooks/hook-protocol/src/merge.ts
@@ -57,7 +57,7 @@ function decisionForRank(maxRank: number): MergedDecision {
  * yields a neutral outcome (`decision: 'none'`, no stop, empty context) — the
  * caller treats that as "no hook had anything to say".
  * @param outputs - every matched hook's decoded output, in hook order.
- * @returns the single folded outcome the bridge maps onto its seam.
+ * @returns the single folded outcome the bridge maps onto its extension point.
  */
 export function mergeHookOutputs(outputs: HookOutput[]): MergedHookOutcome {
   let maxRank = 0
diff --git a/packages/hooks/hook-protocol/src/runner.ts b/packages/hooks/hook-protocol/src/runner.ts
index 802022085e..1fa84507aa 100644
--- a/packages/hooks/hook-protocol/src/runner.ts
+++ b/packages/hooks/hook-protocol/src/runner.ts
@@ -58,7 +58,7 @@ export interface RunHookResult {
  * timeout in seconds overrides the default; trusted environment entries merge
  * after the executor scrub. Infrastructure rejection becomes an outcome with
  * no exit code, so this function never throws or crashes the calling turn.
- * @param bash - the executor seam the command runs through.
+ * @param bash - The executor service the command runs through.
  * @param hook - the configured command; its `timeoutSec` (wire unit: seconds) overrides the default timeout.
  * @param options - the invocation's payload, env, cwd, signal, stdin framing, and default timeout.
  * @param now - millisecond clock used for the reported duration.
diff --git a/packages/hooks/hook-protocol/src/types.ts b/packages/hooks/hook-protocol/src/types.ts
index 1be2b7cb04..82a67f9b93 100644
--- a/packages/hooks/hook-protocol/src/types.ts
+++ b/packages/hooks/hook-protocol/src/types.ts
@@ -1,7 +1,7 @@
 /**
  * Dialect-neutral vocabulary and log-only events shared by the Claude Code and
  * Codex hook bridges. Payload construction, matching differences, environment,
- * and seam-specific decision mapping remain owned by each bridge.
+ * and extension-point-specific decision mapping remain owned by each bridge.
  * @module @deepseek-ai/dsh-hook-protocol/types
  */
 
@@ -42,8 +42,8 @@ declare module '@deepseek-ai/dsh-session' {
 
 /**
  * The bridge that ran a hook — the CC bridge stamps `'claude'`, the Codex
- * bridge `'codex'`. A native plugin on the interception seams is not a bridge
- * and writes no `hook/*` invocation/result records (see the interception-seams Agent Note).
+ * bridge `'codex'`. A native plugin at the interception points is not a bridge
+ * and writes no `hook/*` invocation/result records (see the interception extension-points Agent Note).
  */
 export type HookDialect = 'claude' | 'codex'
 
@@ -81,7 +81,7 @@ export type MatcherMode = 'claude' | 'codex'
 /**
  * The dialect-neutral OUTCOME a hook produced, parsed from its exit code +
  * stdout JSON + stderr by {@link parseHookOutput}. A bridge maps this onto a
- * seam-specific typed Decision (PreToolDecision, PreStepDecision, …). Every field
+ * extension-point-specific typed Decision (PreToolDecision, PreStepDecision, …). Every field
  * is OPTIONAL because a hook may exercise any subset; the bridge decides which
  * fields are meaningful for its hook point and which it ignores (faithful-but-
  * degraded — e.g. Codex ignores `allow`/`ask`).
@@ -130,7 +130,7 @@ export interface HookOutput {
   systemMessage?: string
   /**
    * A tool-input rewrite a hook requested (CC `updatedInput`). PARSED but NOT
-   * honored — input rewrite is deferred (see the interception-seams Agent Note); a
+   * honored — input rewrite is deferred (see the interception extension-points Agent Note); a
    * bridge logs + warns when this is present.
    */
   updatedInput?: Record<string, unknown>
diff --git a/packages/hooks/hook-protocol/tests/runner.spec.ts b/packages/hooks/hook-protocol/tests/runner.spec.ts
index cda3a31bd4..646d7e5a17 100644
--- a/packages/hooks/hook-protocol/tests/runner.spec.ts
+++ b/packages/hooks/hook-protocol/tests/runner.spec.ts
@@ -6,7 +6,7 @@ import type { RunHookOptions } from '@deepseek-ai/dsh-hook-protocol'
 /**
  * A minimal stand-in for the bits of {@link BashExecutor} that {@link runHook}
  * actually calls (`resolve` then `run`). `runHook` is pure plumbing over those
- * two methods, so a duck-typed recorder is the right test seam — the REAL
+ * two methods, so a duck-typed recorder is the right test hook — the REAL
  * executor (dsh-bash-local) is exercised end-to-end by the hook-bridge plugins
  * that consume this library, not here.
  */
diff --git a/packages/hooks/hooks-claude/README.i18n.yaml b/packages/hooks/hooks-claude/README.i18n.yaml
index 55c8aecd2b..b69d0456c3 100644
--- a/packages/hooks/hooks-claude/README.i18n.yaml
+++ b/packages/hooks/hooks-claude/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/hooks/hooks-claude/README.md
-README.md: c97643832821746b816d80d498e8a66fbb9db895
-README.zh.md: 1562c99fc9d5c24ea3f303ea034a13efec022f77
+README.md: 77806514a9ae928ec0e6a233b0760016cad1eded
+README.zh.md: 7ba8f269eedb8791042a5cc8cff1affe35fd2920
diff --git a/packages/hooks/hooks-claude/README.md b/packages/hooks/hooks-claude/README.md
index c976438328..77806514a9 100644
--- a/packages/hooks/hooks-claude/README.md
+++ b/packages/hooks/hooks-claude/README.md
@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-A cordis plugin that runs the supported command-hook subset of a user's existing **Claude Code** hook config (a `hooks.json`, or a settings file's `hooks` key) on the harness's canonical interception seams. It is the **CC dialect** half of the hooks subsystem: it owns the bridge's CC-shaped per-event stdin payloads, CC's env + `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}` substitution, and the mapping from a hook's neutral outcome onto the harness's typed Decisions. The dialect-agnostic primitives (matcher, exit-code/stdout codec, `ctx.bash` execution, most-restrictive merge, the `hook/*` events) come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md).
+A cordis plugin that runs the supported command-hook subset of a user's existing **Claude Code** hook config (a `hooks.json`, or a settings file's `hooks` key) on the harness's canonical interception points. It is the **CC dialect** half of the hooks subsystem: it owns the bridge's CC-shaped per-event stdin payloads, CC's env + `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}` substitution, and the mapping from a hook's neutral outcome onto the harness's typed Decisions. The dialect-agnostic primitives (matcher, exit-code/stdout codec, `ctx.bash` execution, most-restrictive merge, the `hook/*` events) come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md).
 
-A native cordis plugin could do everything this bridge does — more powerfully, with typed returns and no serialization boundary. **The bridge exists only as a compatibility path for the mapped CC command-hook subset**; anything bespoke should be a native plugin on the same seams (see [the interception-seams Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)).
+A native cordis plugin could do everything this bridge does — more powerfully, with typed returns and no serialization boundary. **The bridge exists only as a compatibility path for the mapped CC command-hook subset**; anything bespoke should be a native plugin on the same extension points (see [the interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)).
 
 ## Config
 
@@ -32,9 +32,9 @@ The config is parsed **once** at load. `configPath` is **process-level**: a rela
 
 The hooks **themselves** run in the agent's session workspace: for the agent-scoped points the bridge passes the session's `cwd` (the `session/new.cwd`) as the hook process's working directory, so a hook's `pwd`/relative-path/marker operates in the user's project tree, not the server launch dir.
 
-## Hook points → seam Decisions
+## Hook points → typed Decisions
 
-| CC hook | Harness seam | Mapping |
+| CC hook | Harness point | Mapping |
 |---|---|---|
 | `SessionStart` | `agent/session-start` (emit) | additionalContext → `agent.inject()` into the new session (cannot block) |
 | `UserPromptSubmit` | `agent/pre-step` (waterfall) | `deny` → `PreStepDecision.reject`; additionalContext-only → delegate via `next()` then append a separately sourced message to a downstream `enter` decision (a later outer listener can still reject/rewrite) |
@@ -44,7 +44,7 @@ The hooks **themselves** run in the agent's session workspace: for the agent-sco
 | `SubagentStart` | `subagent/start` (emit) | additionalContext → `agent.inject()` into a live in-process child; a remote child has no local injection target |
 | `SubagentStop` | `subagent/end` (emit) | observe-only |
 
-The three emit points run detached — no seam awaits a `SessionStart`/`SubagentStart`/`SubagentStop` hook. Each run chain is tracked, and disposing the bridge aborts still-running hook processes, then drains the continuations before the dispose resolves (`createDetachedRuns` in `dsh-hook-protocol`).
+The three emit points run detached — no extension point awaits a `SessionStart`/`SubagentStart`/`SubagentStop` hook. Each run chain is tracked, and disposing the bridge aborts still-running hook processes, then drains the continuations before the dispose resolves (`createDetachedRuns` in `dsh-hook-protocol`).
 
 The matcher subject is the tool name (`PreToolUse`/`PostToolUse`), the session source (`SessionStart`), or a constant `agent_type` of `general-purpose` (`SubagentStart`/`SubagentStop` — the harness subagent seam carries no per-kind label, so the bridge reports Claude Code's own Task-tool default; a default/`*`/empty `agent_type` matcher fires, a specific-kind matcher does not); `UserPromptSubmit`/`Stop` ignore matchers. Multiple file-configured hooks on one point run **serially, in config order**, and fold most-restrictively (`deny > ask > allow`, see `dsh-hook-protocol`); serial keeps each hook's `hook/invoked`/`hook/result` pair adjacent in the log, and the fold is order-independent for the decision (see the Agent Note's "run serially, not concurrently" note).
 
diff --git a/packages/hooks/hooks-claude/README.zh.md b/packages/hooks/hooks-claude/README.zh.md
index 1562c99fc9..7ba8f269ee 100644
--- a/packages/hooks/hooks-claude/README.zh.md
+++ b/packages/hooks/hooks-claude/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-一个 Cordis 插件，在 harness 的规范拦截 seam 上运行用户现有 **Claude Code** hook 配置（`hooks.json` 或 settings 文件的 `hooks` key）中受支持的 command hook 子集。它是 hooks 子系统的 **CC 方言**部分，负责桥接中 CC 格式的逐事件 stdin payload、CC 的 env 和 `${CLAUDE_PLUGIN_ROOT}`／`${CLAUDE_PROJECT_DIR}` 替换，以及将 hook 的中性结果映射为 harness 的类型化 Decision。方言无关原语（matcher、退出码／stdout codec、`ctx.bash` 执行、最严格合并、`hook/*` 事件）来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)。
+一个 Cordis 插件，在 harness 的规范拦截点上运行用户现有 **Claude Code** hook 配置（`hooks.json` 或 settings 文件的 `hooks` key）中受支持的 command hook 子集。它是 hooks 子系统的 **CC 方言**部分，负责桥接中 CC 格式的逐事件 stdin payload、CC 的 env 和 `${CLAUDE_PLUGIN_ROOT}`／`${CLAUDE_PROJECT_DIR}` 替换，以及将 hook 的中性结果映射为 harness 的类型化 Decision。方言无关原语（matcher、退出码／stdout codec、`ctx.bash` 执行、最严格合并、`hook/*` 事件）来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)。
 
-原生 Cordis 插件可以完成此桥接的所有工作，功能更强，且具有类型化返回，没有序列化边界。**该桥接只是已映射 CC command hook 子集的兼容路径**；所有定制行为都应当使用相同 seam 上的原生插件（见 [拦截 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)）。
+原生 Cordis 插件可以完成此桥接的所有工作，功能更强，且具有类型化返回，没有序列化边界。**该桥接只是已映射 CC command hook 子集的兼容路径**；所有定制行为都应当使用相同扩展点上的原生插件（见 [拦截扩展点 Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)）。
 
 ## 配置
 
@@ -32,9 +32,9 @@ const config: Config = {
 
 hook **本身**会在 agent 的会话工作区中运行：对 agent scope 点，桥接会将会话 `cwd`（`session/new.cwd`）作为 hook 进程工作目录，因此 hook 的 `pwd`／相对路径／marker 作用于用户项目树，而非服务器启动目录。
 
-## Hook 点 → seam Decision
+## Hook 点 → 类型化 Decision
 
-| CC hook | Harness seam | 映射 |
+| CC hook | Harness 点 | 映射 |
 |---|---|---|
 | `SessionStart` | `agent/session-start`（emit） | additionalContext → `agent.inject()` 到新会话（无法阻塞） |
 | `UserPromptSubmit` | `agent/pre-step`（waterfall，瀑布式事件） | `deny` → `PreStepDecision.reject`；仅 additionalContext → 通过 `next()` 委托，再向下游 `enter` 决策追加一条单独标记来源的消息（后续外层 listener 仍可 reject／改写） |
@@ -44,7 +44,7 @@ hook **本身**会在 agent 的会话工作区中运行：对 agent scope 点，
 | `SubagentStart` | `subagent/start`（emit） | additionalContext → `agent.inject()` 到仍在运行的同进程 child；远程 child 没有本地注入目标 |
 | `SubagentStop` | `subagent/end`（emit） | 只观测 |
 
-三个 emit 点都以分离方式运行：没有 seam 会等待 `SessionStart`／`SubagentStart`／`SubagentStop` hook。每条运行链都会被跟踪；对桥接执行 dispose（资源释放）时，会中止仍在运行的 hook 进程，并在 dispose 完成前排空 continuation（`createDetachedRuns`，位于 `dsh-hook-protocol`）。
+三个 emit 点都以分离方式运行：没有扩展点会等待 `SessionStart`／`SubagentStart`／`SubagentStop` hook。每条运行链都会被跟踪；对桥接执行 dispose（资源释放）时，会中止仍在运行的 hook 进程，并在 dispose 完成前排空 continuation（`createDetachedRuns`，位于 `dsh-hook-protocol`）。
 
 matcher subject 是工具名称（`PreToolUse`／`PostToolUse`）、会话源（`SessionStart`），或常量 `agent_type`，其值为 `general-purpose`（`SubagentStart`／`SubagentStop`）。harness subagent seam 不携带每 kind label，因此桥接报告 Claude Code 自身 Task 工具默认值；默认／`*`／空 `agent_type` matcher 会触发，特定 kind matcher 不会触发。`UserPromptSubmit`／`Stop` 忽略 matcher。一个点上文件配置的多个 hook 会**按配置顺序串行运行**，并按最严格方式折叠（`deny > ask > allow`，见 `dsh-hook-protocol`）。串行使每个 hook 的 `hook/invoked`／`hook/result` 对在日志中相邻，决策折叠与顺序无关（见 Agent Note 的「run serially, not concurrently」说明）。
 
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index e42f875f13..39802d0b6c 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -1,10 +1,10 @@
 /**
  * Bridge for unmodified Claude Code command hooks on harness interception
- * seams. It supports SessionStart, prompt/tool pre/post, Stop, and subagent
+ * extension points. It supports SessionStart, prompt/tool pre/post, Stop, and subagent
  * start/stop. It owns Claude payloads, environment, substitution, and decision
  * mapping; shared execution and parsing live in `dsh-hook-protocol`.
  * `updatedInput` is logged and warned but not honored. Bespoke behavior should
- * use typed native plugins on the same seams; see the
+ * use typed native plugins on the same extension points; see the
  * [hook-bridges Agent Note](../../../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md).
  * @module @deepseek-ai/dsh-hooks-claude
  */
@@ -38,7 +38,7 @@ import { parseClaudeConfig, type ClaudeHookConfig } from './config.ts'
 
 export const name = 'hooks-claude'
 // `bash` is required to run hooks; the rest are read opportunistically via
-// ctx.get so a deployment can load this bridge without every seam present.
+// ctx.get so a deployment can load this bridge without every extension point present.
 export const inject = ['bash']
 
 /** Plugin config: where the CC hook config lives + substitution roots. */
@@ -130,7 +130,7 @@ export function apply(ctx: Context, config: Config): void {
    * `matchQuery`, with the per-event `payload` on stdin, and fold the results.
    * Writes a `hook/invoked`/`hook/result` pair per hook when `opts.turn` names
    * an open turn. Detached lifecycle points omit the pair. Returns the merged outcome (a neutral,
-   * already-most-restrictive view) for the caller to map onto its seam
+   * already-most-restrictive view) for the caller to map onto its extension point
    * decision. `matchQuery` is the event's matcher subject (tool name, session
    * source, …); `''` for events that ignore matchers.
    */
@@ -186,7 +186,7 @@ export function apply(ctx: Context, config: Config): void {
     return mergeHookOutputs(outputs)
   }
 
-  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt seam.
+  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt mechanism.
 
   /** Build additional model context from hook output, or return undefined when empty. */
   function contextFrom(merged: MergedHookOutcome): UserMessage | undefined {
@@ -310,7 +310,7 @@ const SUBAGENT_TYPE = 'general-purpose'
 function lastTurn(agent: Agent | undefined): number {
   if (!agent) return 0
   const last = [...agent.session.events].findLast(e => e.type === 'turn/start')
-  /* v8 ignore next -- agent-present callers are tool/stop seams inside an open turn. */
+  /* v8 ignore next -- agent-present callers are tool/stop extension points inside an open turn. */
   return last?.type === 'turn/start' ? last.data.turn : 0
 }
 
diff --git a/packages/hooks/hooks-claude/tests/coverage-cases.ts b/packages/hooks/hooks-claude/tests/coverage-cases.ts
index b7ea693583..c82f0320f3 100644
--- a/packages/hooks/hooks-claude/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-claude/tests/coverage-cases.ts
@@ -416,7 +416,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
 
   if (group === 'context') describe('hooks-claude coverage — continue:false, context arm, no-cwd', () => {
     it('a {"continue":false} hook is RECORDED as decision "stop" but does not halt the run (TODO(hook-continue-false))', async () => {
-    // The seams cannot yet honor `continue:false` as a hard halt. The log must still record the
+    // The extension points cannot yet honor `continue:false` as a hard halt. The log must still record the
     // stop decision while execution and the turn continue normally.
       const d = dir()
       const s = sh(d, 'stop.sh', '#!/usr/bin/env bash\necho \'{"continue":false,"stopReason":"halt"}\'\n')
diff --git a/packages/hooks/hooks-codex/README.i18n.yaml b/packages/hooks/hooks-codex/README.i18n.yaml
index 212192df3c..4af0518ab2 100644
--- a/packages/hooks/hooks-codex/README.i18n.yaml
+++ b/packages/hooks/hooks-codex/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/hooks/hooks-codex/README.md
-README.md: 60dd1d098966aad6ccdb0957ee223b9843db499f
-README.zh.md: 80162e9fb82eb0f9e358c3d14bd24bf4bfeddaca
+README.md: f8e0684e0bf4eafadcb31d8c82dde177411db2bf
+README.zh.md: d278e78204c1bd320980420b506135997cd3a4cc
diff --git a/packages/hooks/hooks-codex/README.md b/packages/hooks/hooks-codex/README.md
index 60dd1d0989..f8e0684e0b 100644
--- a/packages/hooks/hooks-codex/README.md
+++ b/packages/hooks/hooks-codex/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-A cordis plugin that runs the supported subset of a user's existing **Codex** hook config on the harness's canonical interception seams. The **Codex dialect** half of the hooks subsystem. The dialect-agnostic primitives come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md); this bridge owns the Codex-shaped payloads, matcher mode, and decision mapping.
+A cordis plugin that runs the supported subset of a user's existing **Codex** hook config on the harness's canonical interception points. The **Codex dialect** half of the hooks subsystem. The dialect-agnostic primitives come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md); this bridge owns the Codex-shaped payloads, matcher mode, and decision mapping.
 
 This bridge implements a deliberate subset of Codex's current hook protocol:
 
@@ -12,7 +12,7 @@ This bridge implements a deliberate subset of Codex's current hook protocol:
 - **No Codex plugin env injection and no config-time placeholder substitution** (the command still receives the executor's environment and runs through its shell).
 - **No pre-tool approval or rewrite path** — a hook can block, but the bridge does not pre-approve or replace tool input.
 
-A native cordis plugin could do everything this bridge does, more powerfully; the bridge exists only as a compatibility path for the mapped Codex subset (see [the interception-seams Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)).
+A native cordis plugin could do everything this bridge does, more powerfully; the bridge exists only as a compatibility path for the mapped Codex subset (see [the interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)).
 
 ## Config
 
@@ -38,9 +38,9 @@ The config is parsed **once** at load. `configPath` is **process-level** — a r
 
 The hooks themselves run in the agent's session workspace: for the agent-scoped points the bridge passes the session's `cwd` as the hook process's working directory, so a hook operates in the user's project tree, not the server launch dir.
 
-## Hook points → seam Decisions
+## Hook points → typed Decisions
 
-| Codex hook | Harness seam | Mapping |
+| Codex hook | Harness point | Mapping |
 |---|---|---|
 | `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` |
 | `UserPromptSubmit` | `agent/pre-step` (waterfall) | `block` (exit 2) → `PreStepDecision.reject`; additionalContext-only → delegate via `next()` then append a separately sourced message to a downstream `enter` decision |
diff --git a/packages/hooks/hooks-codex/README.zh.md b/packages/hooks/hooks-codex/README.zh.md
index 80162e9fb8..d278e78204 100644
--- a/packages/hooks/hooks-codex/README.zh.md
+++ b/packages/hooks/hooks-codex/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 Cordis 插件，在 harness 的规范拦截 seam 上运行用户现有 **Codex** hook 配置的受支持子集。它是 hooks 子系统中采用 **Codex 方言** 的一侧。方言无关原语来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)；该桥接负责处理 Codex 形状的 payload、matcher 模式和决策映射。
+一个 Cordis 插件，在 harness 的规范拦截点上运行用户现有 **Codex** hook 配置的受支持子集。它是 hooks 子系统中采用 **Codex 方言** 的一侧。方言无关原语来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)；该桥接负责处理 Codex 形状的 payload、matcher 模式和决策映射。
 
 该桥接实现 Codex 当前 hook 协议的一个明确子集：
 
@@ -12,7 +12,7 @@
 - **没有 Codex 插件 env 注入，也没有配置时 placeholder 替换**（命令仍会接收执行器环境，并通过其 shell 运行）。
 - **没有工具前审批或改写路径**：hook 可以阻塞，但桥接不会预审批或替换工具输入。
 
-原生 Cordis 插件可以完成此桥接的所有工作，并且功能更强；该桥接只是已映射 Codex 子集的兼容路径（见 [拦截 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)）。
+原生 Cordis 插件可以完成此桥接的所有工作，并且功能更强；该桥接只是已映射 Codex 子集的兼容路径（见 [拦截扩展点 Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)）。
 
 ## 配置
 
@@ -38,9 +38,9 @@ const config: Config = {
 
 hook 本身会在 agent（智能体）的会话工作区中运行：对 agent scope 点，桥接会将会话 `cwd` 作为 hook 进程工作目录，因此 hook 作用于用户项目树，而非服务器启动目录。
 
-## Hook 点 → seam Decision
+## Hook 点 → 类型化 Decision
 
-| Codex hook | Harness seam | 映射 |
+| Codex hook | Harness 点 | 映射 |
 |---|---|---|
 | `SessionStart` | `agent/session-start`（emit） | 纯 stdout hook 的输出 → additionalContext → `agent.inject()` |
 | `UserPromptSubmit` | `agent/pre-step`（waterfall，瀑布式事件） | `block`（退出码 2）→ `PreStepDecision.reject`；仅 additionalContext → 通过 `next()` 委托，再向下游 `enter` 决策追加一条单独标记来源的消息 |
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 873b1e35ae..34f47f5a7e 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Bridge for unmodified Codex command hooks on harness interception seams. It
+ * Bridge for unmodified Codex command hooks on harness interception points. It
  * supports five points (SessionStart, prompt/tool pre/post, Stop), regex-only
  * matchers, snake_case payloads without a trailing newline, no hook environment
  * or command substitution, and no pre-tool approval or rewrite path; only
@@ -156,7 +156,7 @@ export function apply(ctx: Context, config: Config): void {
         }
         outputs.push(output)
         // Execution and decision mapping remain in each bridge so dialect
-        // differences stay explicit at their owning seam.
+        // differences stay explicit at their owning extension point.
         /* jscpd:ignore-start */
         if (output.systemMessage !== undefined) {
           ctx.logger.warn(`hooks-codex: ${point} hook emitted a systemMessage, which is not yet surfaced (ignored)`)
@@ -169,7 +169,7 @@ export function apply(ctx: Context, config: Config): void {
     return mergeHookOutputs(outputs)
   }
 
-  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt seam.
+  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt mechanism.
 
   function contextFrom(merged: MergedHookOutcome): UserMessage | undefined {
     if (merged.additionalContext.length === 0) return undefined
@@ -279,7 +279,7 @@ export function apply(ctx: Context, config: Config): void {
 function lastTurn(agent: Agent | undefined): number {
   if (!agent) return 0
   const last = [...agent.session.events].findLast(e => e.type === 'turn/start')
-  /* v8 ignore next -- agent-present turnBase callers are tool/stop seams inside an open turn. */
+  /* v8 ignore next -- agent-present turnBase callers are tool/stop extension points inside an open turn. */
   return last?.type === 'turn/start' ? last.data.turn : 0
 }
 
diff --git a/packages/hooks/hooks-codex/tests/coverage-cases.ts b/packages/hooks/hooks-codex/tests/coverage-cases.ts
index 942feaaa05..d92ea597bd 100644
--- a/packages/hooks/hooks-codex/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-codex/tests/coverage-cases.ts
@@ -395,7 +395,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
     })
 
     it('a {"continue":false} hook is RECORDED as "stop" but does not halt the run (TODO(hook-continue-false))', async () => {
-    // Honoring `continue:false` is deferred — the seams have no hard-halt
+    // Honoring `continue:false` is deferred — the extension points have no hard-halt
     // primitive. Assert the LOG records the halt request AND that the run is not
     // actually halted (the tool still runs, the turn completes).
       const d = dir()
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index fde6cd32ee..d0f3698328 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -811,7 +811,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   }
 
   // Projection change feed → session/projection push frames. The carrier
-  // mints the wire frame (the seam package holds no wire vocabulary); the
+  // mints the wire frame (the Service Definition package holds no wire vocabulary); the
   // child activates only when a projection registry is composed, and the
   // subscription unwinds with this gateway's fiber.
   ctx.inject(['sessionProjections'], (projectionCtx) => {
@@ -1319,7 +1319,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     return { code: 'internal', message: 'credentials service is absent: this deployment does not mount a credential provider (e.g. @deepseek-ai/dsh-credentials-local) in its composition', details: {} }
   }
 
-  /** Map one redacted seam descriptor to its wire view. */
+  /** Map one redacted settings descriptor to its wire view. */
   function namespaceView(descriptor: SettingsDescriptor): SettingsNamespaceView {
     return {
       ns: String(descriptor.ns),
@@ -2048,7 +2048,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       // the Web picker collapsed onto the directory flow
       // (.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md).
       // Delete it with the wire schema's `name` member, this
-      // `defaults.workspaceRoot`, the client seam that carried the name
+      // `defaults.workspaceRoot`, the client contract that carried the name
       // (`WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm,
       // `intentName`'s name branch, the manager's "name under workspaceRoot"
       // contract), and the `dsh web --workspace-root` flag plus its apps/cli
diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts
index 7fc54f6f01..bf2f694eca 100644
--- a/packages/host/apiproxy/src/api/events.ts
+++ b/packages/host/apiproxy/src/api/events.ts
@@ -49,7 +49,7 @@ export interface EventsApi {
    * attached session, then replays each session's still-pending approval/question requested
    * frames (rpcId reused verbatim — the refresh-recovery baseline). Session titles ride the
    * generic projection pair (history-tail projections block + session/projection frames).
-   * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
+   * since: resume hook, unimplemented in v1 (ignored if passed); reconnection = reopen the
    * stream + refetch history.
    */
   mux(request: RpcRequest<{ since?: Record<SessionId, number> }>, signal: AbortSignal): AsyncIterable<RpcRequest<MuxFrame>>
diff --git a/packages/host/apiproxy/src/native-path-opener.ts b/packages/host/apiproxy/src/native-path-opener.ts
index bc75460236..6d8d3e0170 100644
--- a/packages/host/apiproxy/src/native-path-opener.ts
+++ b/packages/host/apiproxy/src/native-path-opener.ts
@@ -157,7 +157,7 @@ async function openNativePathWithIntent(
  * with the default browser when the path names a document a browser renders.
  * @param path - absolute or host-resolvable path (caller owns resolution).
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform, environment, and runner seam for deterministic tests.
+ * @param internals - Platform, environment, and runner hooks for deterministic tests.
  */
 export function openNativePath(
   path: string,
@@ -172,7 +172,7 @@ export function openNativePath(
  * so a YAML association with a browser cannot consume the gesture.
  * @param path - absolute or host-resolvable text-document path.
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
+ * @param internals - Platform and runner hooks for deterministic tests.
  */
 export function openNativeTextFile(
   path: string,
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index be76bf4cc6..4449df15f6 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -518,7 +518,7 @@ describe('sessions.prompt synchronous rejection', () => {
     await ctx.plugin(UserInteractionService)
     const session = ctx.sessions.create(sid('session-throwing'))
     // A live structural stub whose delivery verbs throw synchronously, the
-    // shape a disposed loop presents at this seam.
+    // shape a disposed loop presents at this gateway boundary.
     ctx.agents.register({
       id: session.id,
       session,
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 0beb7455cf..13968616b8 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -44,7 +44,7 @@ function expectErr<T>(response: RpcResponse<T>): { code: string; message: string
   return response.result.error
 }
 
-/** In-memory settings provider: the seam base class owns all tested behavior. */
+/** In-memory settings provider: the Service Definition base class owns all tested behavior. */
 class MemorySettings extends Settings {
   doc: Record<string, unknown>
 
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index 7542d328ba..5e46e4b212 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -91,7 +91,7 @@ function bench(options: {
     locate: () => undefined,
   })
   // The gateway's own projection push feed subscribes at construction; the
-  // no-op disposer keeps that seam quiet while these tests pin history reads.
+  // no-op disposer keeps that feed quiet while these tests pin history reads.
   ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
diff --git a/packages/host/directory-picker-native/src/native-picker.ts b/packages/host/directory-picker-native/src/native-picker.ts
index e25b04ce6c..576353ea8c 100644
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -42,7 +42,7 @@ function rethrowIfAborted(signal: AbortSignal, error: unknown): void {
 /**
  * Open the platform directory picker.
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
+ * @param internals - Platform and runner hooks for deterministic tests.
  * @returns the selected path, or null when the user cancels.
  */
 export async function pickNativeDirectory(
diff --git a/packages/host/directory-picker-native/src/win32-dialog-logic.ts b/packages/host/directory-picker-native/src/win32-dialog-logic.ts
index aa9d1445c4..9ce2b42464 100644
--- a/packages/host/directory-picker-native/src/win32-dialog-logic.ts
+++ b/packages/host/directory-picker-native/src/win32-dialog-logic.ts
@@ -1,6 +1,6 @@
 /**
  * Pure sequencing of the Win32 `IFileOpenDialog` folder-picker COM
- * conversation over an injectable bindings seam, so every outcome path
+ * conversation over injectable platform bindings, so every outcome path
  * (selection, cancellation, HRESULT failure, cleanup ordering) is testable on
  * any platform. The koffi-backed bindings live in
  * `win32-dialog-bindings.ts`, which only a real win32 process ever loads.
diff --git a/packages/host/directory-picker-native/src/win32-dialog.ts b/packages/host/directory-picker-native/src/win32-dialog.ts
index 247d9a1733..cb8a492faa 100644
--- a/packages/host/directory-picker-native/src/win32-dialog.ts
+++ b/packages/host/directory-picker-native/src/win32-dialog.ts
@@ -60,7 +60,7 @@ function assertNever(value: never): never {
 /**
  * Open the modern Win32 folder picker off the event loop.
  * @param signal - caller lifetime; abort closes the dialog and rejects.
- * @param internals - worker/window seams for deterministic tests.
+ * @param internals - Worker/window hooks for deterministic tests.
  * @returns the selected path, or null when the user cancels.
  */
 export async function pickWin32Directory(
diff --git a/packages/host/directory-picker/src/index.ts b/packages/host/directory-picker/src/index.ts
index 4dba9c9c22..4a0a831247 100644
--- a/packages/host/directory-picker/src/index.ts
+++ b/packages/host/directory-picker/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The `ctx.directoryPicker` seam: how the web-GUI host lets an operator
+ * Service Definition for the `ctx.directoryPicker` capability seam: how the web-GUI host lets an operator
  * select a workspace directory. Backends differ in interaction shape, not
  * just mechanism, so the service exposes a discriminated capability instead
  * of one method set: a `native` backend opens one OS chooser on the
diff --git a/packages/host/directory-picker/src/invariant.ts b/packages/host/directory-picker/src/invariant.ts
index 9128850f3b..05638bd0cf 100644
--- a/packages/host/directory-picker/src/invariant.ts
+++ b/packages/host/directory-picker/src/invariant.ts
@@ -10,7 +10,10 @@ export const name = 'host-directory-picker-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: this stateless seam owns the capability vocabulary, while backends and the RPC consumer own observations. */
+/**
+ * No runtime invariant: this stateless Service Definition owns the capability
+ * vocabulary, while backends and the RPC consumer own observations.
+ */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
index a536f9e1f5..fbd275eeed 100644
--- a/packages/host/webserver/src/index.ts
+++ b/packages/host/webserver/src/index.ts
@@ -3,7 +3,7 @@
  * server plus the `httpServer` service (HTTP and upgrade route registries,
  * index transform taps, and the single fallback seat for everything no route
  * claims). Knows no harness concepts and serves no files; the composing
- * application's frontend plugin owns dist serving through the fallback seam.
+ * application's frontend plugin owns dist serving through the fallback hook.
  * Web shape only — Electron loads dist over file:// and carries fetch over an
  * IPC bridge. This package never prints: the URL line belongs to the shell.
  */
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index 5c99feeaf3..d8b76378eb 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
-README.md: a72cd48bb1d3ec15b1116d576fac86619df59528
-README.zh.md: 03fab9c4ce4479b3ab82f372f14f4d4208d7de04
+README.md: 8fe77ae845390359e2c1e3302400c08828a186a1
+README.zh.md: 68e13be7c55e64305bbe0b87ede8d37e55a7cd36
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index a72cd48bb1..8fe77ae845 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The seams through which a human collaborates with a running agent — questions, approvals, permission presets, commands. These are **product** packages: real interfaces a person drives.
+The services and plugins through which a human collaborates with a running agent — questions, approvals, permission presets, commands. These are **product** packages: real interfaces a person drives.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 03fab9c4ce..68e13be7c5 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-人与运行中的 agent（智能体）协作所经由的各个 seam——提问、审批、权限预设、命令。这些是**产品**包（package）：由用户直接操作的真实接口。
+人与运行中的 agent（智能体）协作所经由的服务与插件——提问、审批、权限预设、命令。这些是**产品**包（package）：由用户直接操作的真实接口。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/interaction/tool-ask-user/README.i18n.yaml b/packages/interaction/tool-ask-user/README.i18n.yaml
index 4feb6f3b0f..c6fefae1ed 100644
--- a/packages/interaction/tool-ask-user/README.i18n.yaml
+++ b/packages/interaction/tool-ask-user/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/interaction/tool-ask-user/README.md
-README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
-README.zh.md: 5e5e8f2a8208c003c68ce1f3992c0bd34f2cb552
+README.md: bb0af4286d6d0626596202d57e55fd818b92f44b
+README.zh.md: 1a8c7ceec56a0d5a4ed25793b306d2b5d9e8a526
diff --git a/packages/interaction/tool-ask-user/README.md b/packages/interaction/tool-ask-user/README.md
index 7af356263e..bb0af4286d 100644
--- a/packages/interaction/tool-ask-user/README.md
+++ b/packages/interaction/tool-ask-user/README.md
@@ -19,7 +19,7 @@ The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{
 
 ## Role
 
-This is the consumer package for the user-interaction seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.
+This is the Consumer package for the user-interaction seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.
 
 ## Model Experience
 
diff --git a/packages/interaction/tool-ask-user/README.zh.md b/packages/interaction/tool-ask-user/README.zh.md
index 5e5e8f2a82..1a8c7ceec5 100644
--- a/packages/interaction/tool-ask-user/README.zh.md
+++ b/packages/interaction/tool-ask-user/README.zh.md
@@ -19,7 +19,7 @@
 
 ## 职责
 
-此包是用户交互 seam 的消费方。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
+此包是用户交互 seam 的 Consumer 包。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
 
 ## 模型体验
 
diff --git a/packages/interaction/tool-ask-user/src/index.ts b/packages/interaction/tool-ask-user/src/index.ts
index f908bdad4d..ccfdefe6d3 100644
--- a/packages/interaction/tool-ask-user/src/index.ts
+++ b/packages/interaction/tool-ask-user/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Model-facing `ask_user_question` tool over the `ctx.userInteraction` seam.
+ * Model-facing Consumer of the `ctx.userInteraction` capability seam.
  * The tool pauses until a UI provider returns a human answer, then feeds that
  * answer back into the agent loop as an ordinary tool result.
  *
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index 6af9de6428..3dfeabe570 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Approval request, cancellation, audit, and per-session policy seam. Missing
+ * Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing
  * answerers fail closed; grants apply only to the requested action.
  * @module @deepseek-ai/dsh-user-approval
  */
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index 6326ea0dee..4537cfd7da 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
-README.md: cba015e782623b3a5adf018303823577a0b96774
-README.zh.md: acfacd1cef8150d6995d5c6285b5a331310fb89b
+README.md: cf000dd59754dfe2f14395c33384bad5bda76910
+README.zh.md: 67167649e29afe99667ab6c863127d27d4bceb48
diff --git a/packages/interaction/user-interaction/README.md b/packages/interaction/user-interaction/README.md
index cba015e782..cf000dd597 100644
--- a/packages/interaction/user-interaction/README.md
+++ b/packages/interaction/user-interaction/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a model-facing tool or permission plugin uses when it needs to pause work and ask the human for a decision.
+User-interaction Service Definition. It owns `ctx.userInteraction`, the service a model-facing tool or permission plugin uses when it needs to pause work and ask the human for a decision.
 
 ## Service: `UserInteractionService` (ctx key: `userInteraction`)
 
@@ -30,7 +30,7 @@ When a request carries an agent, `ask()` authenticates its exact identity throug
 
 ## Role
 
-This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; the Web host runtime provides the shipped interactive implementation. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.
+This is the Service Definition package. Consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this service; the Web host runtime supplies the shipped Service provider. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.
 
 ## Model Experience
 
diff --git a/packages/interaction/user-interaction/README.zh.md b/packages/interaction/user-interaction/README.zh.md
index acfacd1cef..67167649e2 100644
--- a/packages/interaction/user-interaction/README.zh.md
+++ b/packages/interaction/user-interaction/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象用户交互 seam。它定义 `ctx.userInteraction`，供面向模型的工具或权限插件在需要暂停工作并询问人类决定时使用。
+用户交互 Service Definition。它定义 `ctx.userInteraction`，供面向模型的工具或权限插件在需要暂停工作并询问人类决定时使用。
 
 ## 服务：`UserInteractionService`（ctx 键：`userInteraction`）
 
@@ -30,7 +30,7 @@
 
 ## 职责
 
-这是接口包。`@deepseek-ai/dsh-tool-ask-user` 等面向模型的消费方依赖此 seam；Web 宿主运行时提供随产品交付的交互式实现。循环保持不变：工具调用等待 Promise，工具结果随后恢复正常的 agent loop（智能体循环）。
+这是 Service Definition 包。`@deepseek-ai/dsh-tool-ask-user` 等 Consumer 依赖此服务；Web 宿主运行时提供随产品交付的 Service provider。循环保持不变：工具调用等待 Promise，工具结果随后恢复正常的 agent loop（智能体循环）。
 
 ## 模型体验
 
diff --git a/packages/interaction/user-interaction/src/index.ts b/packages/interaction/user-interaction/src/index.ts
index 761db57c65..82ab06e25b 100644
--- a/packages/interaction/user-interaction/src/index.ts
+++ b/packages/interaction/user-interaction/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * User-interaction seam (`ctx.userInteraction`): a UI-backed service for
+ * Service Definition for the user-interaction capability seam (`ctx.userInteraction`): a UI-backed service for
  * pausing an agent tool call until the human answers a question. The model-
  * facing tool lives in `@deepseek-ai/dsh-tool-ask-user`; UI packages provide
  * the single active provider.
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index a8bc82817f..3feb8a9e79 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/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/llm/README.md
-README.md: 077ae600c89cff80cd71830e37bda00707c1d837
-README.zh.md: 46d4aa8a6088b3d5f40718f0c2626783e6c05c4b
+README.md: 15f90024abf3256560d67099af79be7d4e0ee310
+README.zh.md: 5f733808ddd591f10e4f2ed437a3f59db3bfb679
diff --git a/packages/llm/README.md b/packages/llm/README.md
index 077ae600c8..15f90024ab 100644
--- a/packages/llm/README.md
+++ b/packages/llm/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The LLM seam and its provider adapters. The interface package (`llm`) owns the abstract service, the content-block vocabulary, and the stream-chunk assembler; the adapters are concrete implementations that register on `ctx.llm`. All **product** packages.
+The LLM seam and its provider adapters. The `llm` package owns both the Service Definition and Consumer roles: the abstract service, content-block vocabulary, and stream-chunk assembler. Provider adapters register on `ctx.llm`. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index 46d4aa8a60..5f733808dd 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -1,8 +1,8 @@
-# llm/ — LLM（大语言模型）能力家族
+# llm/ — LLM 能力家族
 
 [English](README.md) | 中文
 
-LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内容块词汇和流式分片组装器；适配器是注册到 `ctx.llm` 的具体实现。这些全是**产品**包。
+LLM（大语言模型）seam 及其提供方适配器。`llm` 包同时承担 Service Definition 和 Consumer 角色：抽象服务、内容块词汇和流式分片组装器。提供方适配器注册到 `ctx.llm`。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -14,4 +14,4 @@ LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
 
-子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定（adapter contract）——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 1d284f7ade..4c29bfcf11 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -69,7 +69,7 @@ export interface DeepSeekConnectionOptions {
   retryPolicy: ResolvedRetryPolicy
 }
 
-/** Constructor options for {@link DeepSeekAdapter}: the two resolution seams the plugin owns. */
+/** Constructor options for {@link DeepSeekAdapter}: the two resolution hooks the plugin owns. */
 export interface DeepSeekAdapterOptions {
   /** Current validated connection facts; called once per operation. */
   options: () => DeepSeekConnectionOptions
@@ -298,7 +298,7 @@ export class DeepSeekAdapter extends LlmAdapter {
       // fetch wraps every transport failure (DNS, refused connection, TLS,
       // proxy) in a bare `TypeError: fetch failed` whose actionable detail
       // lives on `cause`. Wrapping with the endpoint and chaining the cause
-      // lets `errorChain` render the full diagnosis at every reporting seam.
+      // lets `errorChain` render the full diagnosis at every reporting boundary.
       throw new LlmError(
         `DeepSeek API request to ${connection.baseURL} failed`,
         'TRANSPORT',
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index eea304b414..840a8c2865 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 4ad669344056a8290057cd39cbde56b0a2d80ba4
-README.zh.md: 96e1ef2dd3219e8b1fe0d5afbf5c784d9c3e42d5
+README.md: 7151fdf5b63f48e625d00a92dc42aa24b7de2f31
+README.zh.md: 0bfd5c706e01dd4448edb9cf0eec812831f68093
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 4ad6693440..7151fdf5b6 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -194,4 +194,4 @@ Recorded response content appends to the next request and does not invalidate it
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
-- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step seam; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
+- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step extension point; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 96e1ef2dd3..0bfd5c706e 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -194,4 +194,4 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 - **不支持 `GenerateOptions.stop`**：pi-ai 的通用流选项无法保证所有提供方都支持 stop sequence，因此适配器会拒绝该字段。
 - **历史中的 `system` 消息使用 pi-ai 通用上下文转换**：提供方特定位置由 pi-ai 决定，而非由 harness 拥有的协议覆盖决定。
 - **无法获取提供方 HTTP 状态**：pi-ai 错误事件不会在所有提供方上公开稳定 HTTP 状态；失败只公开稳定 harness 错误 code。
-- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤 seam 上执行；pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
+- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤扩展点上执行；pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts
index e974cdff7c..09c72719ec 100644
--- a/packages/llm/llm-pi-ai/src/adapter.ts
+++ b/packages/llm/llm-pi-ai/src/adapter.ts
@@ -59,7 +59,7 @@ interface PiAiSnapshot {
   models: Models
 }
 
-/** Constructor options for {@link PiAiAdapter}: the two resolution seams the plugin owns. */
+/** Constructor options for {@link PiAiAdapter}: the two resolution hooks the plugin owns. */
 export interface PiAiAdapterOptions {
   /** Current validated profiles by provider route; called once per operation. */
   profiles: () => ReadonlyMap<string, ResolvedPiAiProviderProfile>
diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts
index 620e367742..82b441fb8f 100644
--- a/packages/llm/llm-retry/src/index.ts
+++ b/packages/llm/llm-retry/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * Provider-routed model-request retry policy on the agent loop's request
- * recovery seam. Each scheduled retry is durable before its cancellable wait.
+ * recovery extension point. Each scheduled retry is durable before its cancellable wait.
  *
  * @module @deepseek-ai/dsh-llm-retry
  */
@@ -57,7 +57,7 @@ function validateConfig(config: Config): void {
   throw new Error(`llm-retry: unknown key "${key}"`)
 }
 
-/** Non-serializable seams used to make timing policy deterministic in tests. */
+/** Non-serializable hooks used to make timing policy deterministic in tests. */
 export interface RetryInternals {
   /** Random sample in the inclusive zero-to-one range used for jitter. */
   random?: () => number
@@ -116,7 +116,7 @@ function cancellableDelay(delayMs: number, signal: AbortSignal): Promise<boolean
  * Install provider-routed normal or unbounded request recovery.
  * @param ctx - plugin context that owns the listener and active waits.
  * @param config - empty executor config; provider registrations own policy.
- * @param internals - non-serializable deterministic seams for tests.
+ * @param internals - non-serializable deterministic hooks for tests.
  */
 export function apply(ctx: Context, config: Config = {}, internals: RetryInternals = {}): void {
   validateConfig(config)
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index c4e8277b42..2c5cb7bb48 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: a437a689e934701b925dbf5a39a912c3af7dd46b
-README.zh.md: 7ed0c9c8a93e102b3d350be48be3a07e30011582
+README.md: 0b463c73175e46d20e9c8f719b55b3fa4f56fde2
+README.zh.md: cbabeb72216e9fc92b74d6c216d7f7b7154bc1a8
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index a437a689e9..0b463c7317 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -71,7 +71,7 @@ Every adapter that puts a credential in an HTTP header judges it the same way be
 
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and can create an identified, frozen assistant message from them. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks for history.
-- `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
+- `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at process boundaries.
 - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) matches its frozen serializable `failure.code`. The payload may also retain validated status, `Retry-After`, and branded provider request id facts; policy remains outside the error.
 - `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
 - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail.
@@ -93,7 +93,7 @@ Pass-through; the registry preserves the assembled request prefix, while the sel
 
 ## Known Limitations and Deferred Work
 
-- **No retry execution, caching, or rate limiting ships in this service** — provider registration stores retry policy, but `llm/stream` remains a single-attempt call-wrapper seam. The agent loop separately offers proven model-request failures to `agent/request-error`, whose default preserves the original failure; `@deepseek-ai/dsh-llm-retry` is the optional executor loaded by the shared example spine.
+- **No retry execution, caching, or rate limiting ships in this service** — provider registration stores retry policy, but `llm/stream` remains a single-attempt call wrapper. The agent loop separately offers proven model-request failures to `agent/request-error`, whose default preserves the original failure; `@deepseek-ai/dsh-llm-retry` is the optional executor loaded by the shared example spine.
 - **`GenerateOptions` sampling is `temperature`/`maxTokens`/`stop` only** — no `tool_choice`, `top_p`, or penalty fields; the vocabulary grows when a producer lands ([dropped inert knobs](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)).
 - **Producer-gated variants stay out until produced** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant were pruned as producerless ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 7ed0c9c8a9..cbabeb7221 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -71,7 +71,7 @@
 
 - `LlmAdapter`：提供方适配器的抽象基类。唯一必需方法是 `stream()`。
 - `BlockAssembler`：将原始分片逐步组装为完整内容块，并能据此创建带标识且冻结的 assistant 消息。agent loop 向它提供原始分片（同时记录以供回放），并读取已组装块以构建历史。
-- `HarnessError`：harness 错误分类体系的基类，包含稳定 `code` 字符串（与面向人的 `message` 不同）加 `cause` 链接。它位于所有其他包都从中导入的叶子包中，因此可以共享单一基类，无需新的依赖边。各包的错误（`LlmError`、`ToolArgsError`、`InvariantError` 等）都继承自它。`isHarnessError(value)` 在 seam 处收窄类型。
+- `HarnessError`：harness 错误分类体系的基类，包含稳定 `code` 字符串（与面向人的 `message` 不同）加 `cause` 链接。它位于所有其他包都从中导入的叶子包中，因此可以共享单一基类，无需新的依赖边。各包的错误（`LlmError`、`ToolArgsError`、`InvariantError` 等）都继承自它。`isHarnessError(value)` 在进程边界处收窄类型。
 - `LlmError`：继承自 `HarnessError`；其稳定 `code` 字符串（`NO_ADAPTER`、`DUPLICATE_ADAPTER` 与 `AUTH`／`RATE_LIMIT` 等适配器 code）与冻结可序列化 `failure.code` 匹配。Payload 还可以保留已验证状态、`Retry-After` 和品牌化提供方请求 id 事实；策略位于错误之外。
 - `errorChain(value)`：渲染抛出值的完整 `cause` 链与 AggregateError 成员，供诊断表层使用，包括 UI 通知、logger 行和持久 `turn/end` 消息。因此 undici 的 `TypeError: fetch failed` 等传输包装层会显示底层 `ECONNREFUSED`／DNS／TLS 详细信息，而不是将其遮蔽。该函数只负责渲染：请按 `code` 路由，绝不解析结果。
 - `CONTEXT_WINDOW_EXCEEDED_CODE`：当请求超过模型上下文窗口时，无论通过 HTTP 异常抛出还是带内 finish 交付，两个 DeepSeek 适配器都使用的提供方无关 code。`isContextWindowExceededError(detail)` 是它们针对 OpenAI 兼容提供方详细信息的共享保守分类器。
@@ -93,7 +93,7 @@
 
 ## 已知限制与暂缓事项
 
-- **本服务不执行重试、缓存或速率限制**：提供方注册会存储重试策略，但 `llm/stream` 仍是单次尝试调用包装 seam。agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败；`@deepseek-ai/dsh-llm-retry` 是共享示例主干加载的可选执行器。
+- **本服务不执行重试、缓存或速率限制**：提供方注册会存储重试策略，但 `llm/stream` 仍是单次尝试调用包装层。agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败；`@deepseek-ai/dsh-llm-retry` 是共享示例主干加载的可选执行器。
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **受产生方约束的变体在实际产生前不会加入**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。
diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts
index 9ff193f1f8..4b3e25c75f 100644
--- a/packages/llm/llm/src/error.ts
+++ b/packages/llm/llm/src/error.ts
@@ -154,7 +154,7 @@ export function errorChain(value: unknown): string {
 }
 
 /**
- * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams).
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at runtime boundaries).
  * @param value - the caught value (`unknown` in catch clauses).
  * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
  */
diff --git a/packages/llm/llm/src/retry-policy.ts b/packages/llm/llm/src/retry-policy.ts
index 7d4c4601eb..6f5548a111 100644
--- a/packages/llm/llm/src/retry-policy.ts
+++ b/packages/llm/llm/src/retry-policy.ts
@@ -2,7 +2,7 @@
  * Provider-owned request-retry policy configuration and resolution.
  *
  * Adapters expose one resolved policy per registered provider route; the
- * optional dsh-llm-retry plugin executes it on the agent's failed-step seam.
+ * optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
  *
  * @module @deepseek-ai/dsh-llm/retry-policy
  */
diff --git a/packages/llm/llm/tests/attribution.spec.ts b/packages/llm/llm/tests/attribution.spec.ts
index e797af5b38..db74773314 100644
--- a/packages/llm/llm/tests/attribution.spec.ts
+++ b/packages/llm/llm/tests/attribution.spec.ts
@@ -5,7 +5,7 @@ import type { AppIdentity } from '@deepseek-ai/dsh-llm'
 
 const manifest = createRequire(import.meta.url)('../package.json') as { version: string }
 
-/** A white-label identity exercising every override seam. */
+/** A white-label identity exercising every override hook. */
 const forkIdentity: AppIdentity = {
   product: 'fork-agent',
   version: '9.9.9',
diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts
index caea2a2701..d3b024a2ee 100644
--- a/packages/llm/token-meter/src/index.ts
+++ b/packages/llm/token-meter/src/index.ts
@@ -10,7 +10,7 @@ import { BlockAssembler, deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { Message, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { EpochHeader, Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session'
-// Type-only: resolves the optional projection registry Context seam.
+// Type-only: resolves the optional projection registry Context declaration.
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type {
   TokenMeasurement,
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index abe4d95c7e..cc3ddc6e53 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
-README.zh.md: 7a24bffa0e92f30c16a3307357ba7f1aa295ef52
+README.md: 3b472492ba12146101bae0e2eae9c837a7f6cb1d
+README.zh.md: e9e2781fdb9da8a3094080759730d01e179bff98
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 01c464c999..3b472492ba 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -2,15 +2,15 @@
 
 English | [中文](README.zh.md)
 
-The language-server capability seam: an abstract LSP interface, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
+The language-server capability seam: an LSP Service Definition, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
+| `lsp/` | Service Definition (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
 | `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
-The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
+The Service Definition lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
 See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
 
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index 7a24bffa0e..e9e2781fdb 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品**包。
+语言服务器能力 seam：LSP Service Definition、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
+| `lsp/` | Service Definition（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
 | `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力**而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+Service Definition 位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
 设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
 
diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index 4be75cbd33..0a267c879f 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -1,12 +1,12 @@
 /**
  * A JSON-RPC endpoint over one language server spawned through the subprocess
- * seam. Owns id correlation, outbound requests/notifications, and inbound
+ * capability. Owns id correlation, outbound requests/notifications, and inbound
  * server→client requests: it answers `workspace/configuration` from static
  * config, and rejects `workspace/applyEdit` (this host never applies edits or
  * runs commands). It caps stderr, surfaces framing/decoder failures as a
  * fatal close, and exposes tree-scoped termination through the handle so the
- * instance owns teardown; group/tree mechanics live in the seam's
- * implementation.
+ * instance owns teardown; group/tree mechanics live in the subprocess
+ * Service provider.
  * @module @deepseek-ai/dsh-lsp-local/connection
  */
 
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 318704b9fc..4ecd444f1e 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -92,7 +92,7 @@ export class LspInstance {
    */
   query(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise<LspQueryResult> {
     // Serialize behind prior work, but observe abort DURING the queue wait too: if an earlier query
-    // hangs (e.g. a signal-less seam caller), a later tool's timeout must still be able to give up
+    // hangs (e.g. a signal-less service caller), a later tool's timeout must still be able to give up
     // rather than block on the shared tail forever.
     const run = abortable(this.queue, signal)
       .then(() => this.runQuery(request, source, signal))
diff --git a/packages/lsp/lsp-local/src/translate.ts b/packages/lsp/lsp-local/src/translate.ts
index a49246c8bb..13ba14455b 100644
--- a/packages/lsp/lsp-local/src/translate.ts
+++ b/packages/lsp/lsp-local/src/translate.ts
@@ -25,8 +25,8 @@ import type {
 } from './protocol.ts'
 
 /**
- * The `textDocument/*` request method for each seam operation.
- * @param operation - the seam operation to map.
+ * The `textDocument/*` request method for each LSP operation.
+ * @param operation - the LSP operation to map.
  * @returns the LSP request method name.
  */
 export function requestMethod(operation: LspOperation): string {
@@ -62,7 +62,7 @@ function supportsCapability(value: WireProviderCapability): boolean {
 /**
  * Whether the server advertises the requested operation.
  * @param capabilities - the server's `initialize` capabilities.
- * @param operation - the seam operation to check.
+ * @param operation - the LSP operation to check.
  * @returns true when the corresponding provider capability is present.
  */
 export function supportsOperation(capabilities: WireServerCapabilities, operation: LspOperation): boolean {
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index cceabd1036..af06afd030 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
-README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
-README.zh.md: a35f870603718ee6b7bcbfdf65f5d689d800447b
+README.md: bab312e73f746d0d782ab5771429fed1397255aa
+README.zh.md: 7ef95c725eba4a35f99014b446fc5648d8aab20a
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index 5c1044be50..bab312e73f 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
 
 The **LSP capability seam**: an abstract `LspService` (`ctx.lsp`) defining WHAT semantic code navigation the harness has — go to definition, find references, find implementations, hover — over language-server providers, without binding the model contract to local subprocesses.
 
-This package is the interface third of the LSP capability:
+This package owns the Service Definition role of the LSP capability:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
-| `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
-| `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
+| `@deepseek-ai/dsh-lsp` (this) | Service Definition: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
+| `@deepseek-ai/dsh-lsp-local` | Service provider: a generic local backend that registers configured stdio language-server providers |
+| `@deepseek-ai/dsh-tool-lsp` | Consumer: the model-facing `lsp` tool over `ctx.lsp` |
 
 The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
 
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index a35f870603..7ef95c725e 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -4,13 +4,13 @@
 
 **LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型约定绑定到本地子进程。
 
-该包是 LSP 能力中负责接口的三分之一：
+本包承担 LSP 能力的 Service Definition 角色：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
-| `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
-| `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
+| `@deepseek-ai/dsh-lsp`（本包） | Service Definition：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
+| `@deepseek-ai/dsh-lsp-local` | Service provider：通用本地后端，注册已配置的 stdio 语言服务器提供方 |
+| `@deepseek-ai/dsh-tool-lsp` | Consumer：面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
 该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
 
diff --git a/packages/lsp/lsp/src/index.ts b/packages/lsp/lsp/src/index.ts
index d7b1a80d01..ec780b76f1 100644
--- a/packages/lsp/lsp/src/index.ts
+++ b/packages/lsp/lsp/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
+ * Service Definition for the LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
  * order-independent selection over normalized goToDefinition/findReferences/goToImplementation/
  * hover queries.
  *
diff --git a/packages/lsp/tool-lsp/README.i18n.yaml b/packages/lsp/tool-lsp/README.i18n.yaml
index 85a33f73af..cb728b0168 100644
--- a/packages/lsp/tool-lsp/README.i18n.yaml
+++ b/packages/lsp/tool-lsp/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/lsp/tool-lsp/README.md
-README.md: 1e89abf22e853735c094d17047b2c946af210905
-README.zh.md: 396b4d22ada8761b17c01d0c40e4bb4cfe80ca67
+README.md: 36fa3026cba3fc692ae5a86c7307acf77563cf53
+README.zh.md: 1b0b1f4847cf711e7939b79ac2f8035f26cb73aa
diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md
index 1e89abf22e..36fa3026cb 100644
--- a/packages/lsp/tool-lsp/README.md
+++ b/packages/lsp/tool-lsp/README.md
@@ -10,7 +10,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In
 
 `lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
 
-The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized Service Definition union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
 
 ## Configuration
 
diff --git a/packages/lsp/tool-lsp/README.zh.md b/packages/lsp/tool-lsp/README.zh.md
index 396b4d22ad..1b0b1f4847 100644
--- a/packages/lsp/tool-lsp/README.zh.md
+++ b/packages/lsp/tool-lsp/README.zh.md
@@ -10,7 +10,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 `lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
 
-该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
+该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 Service Definition 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
 
 ## 配置
 
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index 3a18e44088..fddee83915 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -362,7 +362,7 @@ describe('the boundary flush', () => {
     ctx.planMode.set(agent, true)
     const original = agent.session.append.bind(agent.session)
     // Only the flush's own plan/mode append fails; the boundary event itself
-    // lands (the loop appended it before the seam fires).
+    // lands (the loop appended it before the between-step hook fires).
     agent.session.append = (((type: string, ...rest: unknown[]) => {
       if (type === 'plan/mode') throw new Error('backend gone')
       return (original as (...args: unknown[]) => unknown)(type, ...rest)
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 67698f80b4..1deefc7657 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -70,7 +70,7 @@ function defaultProbeSeatbelt(seatbeltExec: string, timeoutMs: number): boolean
   return probe.status === 0
 }
 
-/** Test seam: inject probe verdicts / a fake launcher / a platform without real runners. */
+/** Test hook: inject probe verdicts / a fake launcher / a platform without real runners. */
 export interface SandboxInternals {
   /** Replaces `process.platform` for chain selection (exercise any platform's chain from any host). */
   platform?: string
@@ -179,7 +179,7 @@ export class LocalSandboxProvider extends SandboxProvider {
     probeTimeoutMs: z.natural().default(5_000),
   })
 
-  /** Test seam (mirrors the bash executors' `internals`). */
+  /** Test hook (mirrors the bash executors' `internals`). */
   internals: SandboxInternals = {}
 
   private readonly runnerCommand: string[] | undefined
@@ -300,12 +300,12 @@ export class LocalSandboxProvider extends SandboxProvider {
     }
   }
 
-  /** The Landlock launcher to probe and exec (test seam over the resolved one). */
+  /** The Landlock launcher to probe and exec (test hook over the resolved one). */
   private landlockLauncher(): string {
     return this.internals.landlockLauncher ?? landlockLauncherPath()
   }
 
-  /** The `sandbox-exec` executable to probe and exec (test seam over the system one). */
+  /** The `sandbox-exec` executable to probe and exec (test hook over the system one). */
   private seatbeltExec(): string {
     return this.internals.seatbeltExec ?? 'sandbox-exec'
   }
diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index b1b8b2c4a8..93f725fe48 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -237,7 +237,7 @@ describe('the platform chains', () => {
 
   it('a multi-rung chain probes a seatbelt rung like any other (the walk, not the platform table, decides)', async () => {
     // The product chains reach seatbelt only as darwin's sole (unprobed)
-    // candidate; the chain seam exercises the probing path it would take in
+    // candidate; the probe chain exercises the path it would take in
     // a grown chain, keeping the default seatbelt probe honest.
     const exec = fakeSeatbeltExec(0)
     const probeBwrap = vi.fn(() => false)
@@ -349,8 +349,8 @@ describe('probeTimeoutMs config', () => {
 
 describe('the default seatbelt probe (sandbox-exec contract)', () => {
   // The product chains reach seatbelt only unprobed (darwin's sole
-  // candidate), so the default probe's contract is pinned through the chain
-  // seam: a grown chain must probe it like any other rung.
+  // candidate), so the default probe's contract is pinned through the provider
+  // chain: a grown chain must probe it like any other rung.
   it('selects the rung when the executable applies the read-only profile and exits 0', async () => {
     const exec = fakeSeatbeltExec(0)
     const { sandbox } = await setup({}, { chain: ['bwrap', 'seatbelt'], probeBwrap: () => false, seatbeltExec: exec })
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 3c29efec12..d431dd97c4 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/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/sandbox/sandbox/README.md
-README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
-README.zh.md: abc5d387384e3a69e35496d6ce4bc9830185c55d
+README.md: 50b7eff1a287ee0bc2432a7bf409586ff879920e
+README.zh.md: ff68a49f5487b5da9700698c5376199727f1cd5f
diff --git a/packages/sandbox/sandbox/README.md b/packages/sandbox/sandbox/README.md
index 8c1c747f6c..50b7eff1a2 100644
--- a/packages/sandbox/sandbox/README.md
+++ b/packages/sandbox/sandbox/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.
+Process-sandbox Service Definition. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. As the Service Definition role of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), it depends only on cordis (+ the harness error base), never on a backend.
 
 The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
 
 Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.
 
-**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names the filesystem-canonical real host directory. Workspace identity is resolved before lexical normalization, so a valid cwd containing `symlink/..` grants the directory where `chdir` actually lands rather than an unrelated lexical parent. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names the filesystem-canonical real host directory. Workspace identity is resolved before lexical normalization, so a valid cwd containing `symlink/..` grants the directory where `chdir` actually lands rather than an unrelated lexical parent. Containers, microVMs, and remote executors are NOT backends of this seam — they replace the Service providers for whole capability seams (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 
 Implementations: [`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/) (Linux: `bwrap`, else the per-platform Landlock launcher; macOS: `sandbox-exec`/Seatbelt). Consumers: [`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/) (wraps `['bash', '-c', command]`).
 
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index abc5d38738..ff68a49f54 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
+进程沙箱 Service Definition。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。作为[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)中的 Service Definition 角色，它只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
 用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
 
-**只支持与宿主共享文件系统和内核的限制。** 后端与宿主共享文件系统和内核（`bwrap`、Landlock、Seatbelt）；`workspaceRoot` 指向文件系统规范化后的真实主机目录。系统先解析工作区所指的目录，再做词法规范化，因此包含 `symlink/..` 的有效 cwd 会授权 `chdir` 实际到达的目录，而非无关的词法父目录。容器、microVM 与远程执行器都不是该 seam 的后端：它们会以环境一致的分组替换整个能力实现（`ctx.bash`、`ctx.fs`）。边界及其设计理由见[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+**只支持与宿主共享文件系统和内核的限制。** 后端与宿主共享文件系统和内核（`bwrap`、Landlock、Seatbelt）；`workspaceRoot` 指向文件系统规范化后的真实主机目录。系统先解析工作区所指的目录，再做词法规范化，因此包含 `symlink/..` 的有效 cwd 会授权 `chdir` 实际到达的目录，而非无关的词法父目录。容器、microVM 与远程执行器都不是该 seam 的后端：它们会以环境一致的分组替换整个能力 seam 的 Service provider（`ctx.bash`、`ctx.fs`）。边界及其设计理由见[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 实现：[`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/)（Linux：`bwrap`，否则使用相应平台的 Landlock launcher；macOS：`sandbox-exec`／Seatbelt）。消费方：[`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/)（包装 `['bash', '-c', command]`）。
 
@@ -39,5 +39,5 @@ sandbox mode "<mode>" is requested but no sandbox backend is usable on this host
 - **文件操作是完整的策略词汇**：该 seam 不表达网络、进程、系统调用、设备或凭据限制。
 - **只支持与宿主共享文件系统和内核的限制**：容器、microVM 与远程执行需要替换能力实现，而不是在此处增加提供方。
 - **拒绝报告是一种 stderr 方言**：该 seam 返回后端签名，而非类型化运行时拒绝通道，因此需要分类的消费方必须从子进程输出推断。
-- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过限制；带外 runner 状态通道暂缓实现。
+- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过约束；带外 runner 状态通道暂缓实现。
 - **每个上下文只有一个提供方**：同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。
diff --git a/packages/sandbox/sandbox/src/index.ts b/packages/sandbox/sandbox/src/index.ts
index aeca1ba8d6..75f8e9b846 100644
--- a/packages/sandbox/sandbox/src/index.ts
+++ b/packages/sandbox/sandbox/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Same-world process-confinement seam: wrap exact subprocess argv under a
+ * Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
  * host-path file policy. Containers, microVMs, and remote execution replace the
  * surrounding capability seam instead; this service shares the host kernel and filesystem.
  * @module @deepseek-ai/dsh-sandbox
diff --git a/packages/scaffold/create-sdk/src/headless.ts b/packages/scaffold/create-sdk/src/headless.ts
index 9210f12fc1..8f6130acd7 100644
--- a/packages/scaffold/create-sdk/src/headless.ts
+++ b/packages/scaffold/create-sdk/src/headless.ts
@@ -62,7 +62,7 @@ function parseHeadlessSpec(text: string, source: string): HeadlessCreateSpec {
  * Load a headless spec from `--config-json` (inline) or `--config` (a JSON file),
  * returning `undefined` when neither is supplied.
  * @param args - parsed create args.
- * @param readFileText - file reader seam for tests.
+ * @param readFileText - File-reader hook for tests.
  * @returns the resolved args + feature plan, or `undefined` for interactive runs.
  */
 export async function resolveHeadless(
diff --git a/packages/scaffold/scripts/src/telemetry.ts b/packages/scaffold/scripts/src/telemetry.ts
index 1ef74fdbb7..d739a7164b 100644
--- a/packages/scaffold/scripts/src/telemetry.ts
+++ b/packages/scaffold/scripts/src/telemetry.ts
@@ -25,7 +25,7 @@ export interface CommandTelemetryEvent {
   success: boolean
 }
 
-/** Injectable consent and delivery seams for tests. */
+/** Injectable consent and delivery hooks for tests. */
 export interface CommandTelemetryDeps {
   resolve?: (cwd: string) => Promise<ConsentDecision>
   reporter?: Pick<TelemetryReporter, 'report' | 'flush'>
@@ -36,7 +36,7 @@ export interface CommandTelemetryDeps {
  * telemetry event, draining in-flight sends before returning. Swallows every
  * error so telemetry can never change a command's result.
  * @param event - the command lifecycle facts.
- * @param deps - consent and delivery seams; defaults hit the real endpoint.
+ * @param deps - Consent and delivery hooks; defaults hit the real endpoint.
  */
 export async function reportCommandTelemetry(
   event: CommandTelemetryEvent,
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
index fc60d047d1..d6c24c3566 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/scaffold/server/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/scaffold/server/README.md
-README.md: 0afb3a38ece57f74729a218dc85348fa6c7fa529
-README.zh.md: 5305434abbd83eb230dcdd81e72120d96da26cda
+README.md: 9c53946f4112e9ce8e17590c2ff91fb4b8c2ef74
+README.zh.md: 270691f859426dbdc6ca9d8f05049d290eaa8e1b
diff --git a/packages/scaffold/server/README.md b/packages/scaffold/server/README.md
index 0afb3a38ec..9c53946f41 100644
--- a/packages/scaffold/server/README.md
+++ b/packages/scaffold/server/README.md
@@ -10,7 +10,7 @@ The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-proc
 
 ## Config
 
-`maxTokensAsSuccess` defaults to `false` and affects only the deployment-mapped status on `subagent.finished`; root-session prompts have no prompt-level status. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport seams; production uses process stdio and `process.exit`.
+`maxTokensAsSuccess` defaults to `false` and affects only the deployment-mapped status on `subagent.finished`; root-session prompts have no prompt-level status. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport hooks; production uses process stdio and `process.exit`.
 
 ## stdout is the protocol
 
diff --git a/packages/scaffold/server/README.zh.md b/packages/scaffold/server/README.zh.md
index 5305434abb..270691f859 100644
--- a/packages/scaffold/server/README.zh.md
+++ b/packages/scaffold/server/README.zh.md
@@ -10,7 +10,7 @@
 
 ## 配置
 
-`maxTokensAsSuccess` 默认为 `false`，且只影响 `subagent.finished` 上由部署映射的状态；根会话提示词没有提示词级状态。`JsonRpcConfig.input`、`output` 和 `exit` 是仅供运行时使用的传输 seam；生产环境使用进程 stdio 和 `process.exit`。
+`maxTokensAsSuccess` 默认为 `false`，且只影响 `subagent.finished` 上由部署映射的状态；根会话提示词没有提示词级状态。`JsonRpcConfig.input`、`output` 和 `exit` 是仅供运行时使用的传输钩子；生产环境使用进程 stdio 和 `process.exit`。
 
 ## stdout 即协议
 
diff --git a/packages/scaffold/server/src/index.ts b/packages/scaffold/server/src/index.ts
index f0261e1a21..be7252007a 100644
--- a/packages/scaffold/server/src/index.ts
+++ b/packages/scaffold/server/src/index.ts
@@ -25,7 +25,7 @@ export const name = 'jsonrpc'
 // Only the agent factory is required; initialize reads the optional LLM seam with ctx.get().
 export const inject = ['agents']
 
-/** JSON-RPC deployment config plus runtime-only test seams. */
+/** JSON-RPC deployment config plus runtime-only test hooks. */
 export interface JsonRpcConfig {
   /** Report max-token turn/subagent termination as a successful SDK result. */
   maxTokensAsSuccess?: boolean
@@ -53,11 +53,11 @@ export function apply(ctx: Context, config: JsonRpcConfig): void {
   // Protocol shutdown owns the complete runtime process, so it must await the
   // root lifecycle (including persistence) before exiting.
   const rootFiber = ctx.root.fiber
-  /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */
+  /* v8 ignore next -- production stdio wiring; tests always inject the runtime hooks */
   const input = config.input ?? process.stdin
-  /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */
+  /* v8 ignore next -- production stdio wiring; tests always inject the runtime hooks */
   const output = config.output ?? process.stdout
-  /* v8 ignore next -- production exit wiring; tests always inject the runtime seams */
+  /* v8 ignore next -- production exit wiring; tests always inject the runtime hooks */
   const exit = config.exit ?? ((code: number): void => { process.exit(code) })
 
   const transport = new JsonRpcLineTransport(input, output)
diff --git a/packages/scaffold/server/tests/plugin-apply.spec.ts b/packages/scaffold/server/tests/plugin-apply.spec.ts
index af64092933..b2109b8c51 100644
--- a/packages/scaffold/server/tests/plugin-apply.spec.ts
+++ b/packages/scaffold/server/tests/plugin-apply.spec.ts
@@ -11,7 +11,7 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as jsonrpc from '../src/index.ts'
 
 /**
- * Mount the real namespace plugin with in-memory stdio and exit seams. Covers
+ * Mount the real namespace plugin with in-memory stdio and exit hooks. Covers
  * the full transport/server path, response-before-exit shutdown exactly once,
  * and bare-fiber disposal without process exit.
  */
diff --git a/packages/scaffold/telemetry/src/anonymous-id.ts b/packages/scaffold/telemetry/src/anonymous-id.ts
index dcfe08c158..08925d1ad2 100644
--- a/packages/scaffold/telemetry/src/anonymous-id.ts
+++ b/packages/scaffold/telemetry/src/anonymous-id.ts
@@ -27,11 +27,11 @@ export const ANONYMOUS_ID_FILE_NAME = 'telemetry.json'
 
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
-/** Ambient seams for locating and generating the id; every field has a default. */
+/** Ambient hooks for locating and generating the id; every field has a default. */
 export interface AnonymousIdOptions {
   /** Environment consulted for `DSH_HOME`; defaults to `process.env`. */
   env?: NodeJS.ProcessEnv
-  /** UUID generator; defaults to `crypto.randomUUID` (test seam). */
+  /** UUID generator; defaults to `crypto.randomUUID` (test hook). */
   randomUUID?: () => string
 }
 
@@ -40,7 +40,7 @@ export interface AnonymousIdOptions {
  * Delegates to {@link resolveDshHome} so telemetry shares the harness's one
  * home-resolution policy (`DSH_HOME` > `~/.dsh`) instead of maintaining a
  * second config-directory convention.
- * @param options - environment seam.
+ * @param options - Environment hook.
  * @returns absolute harness home path.
  */
 export function globalConfigDir(options: AnonymousIdOptions = {}): string {
@@ -74,7 +74,7 @@ async function readPersistedId(file: string): Promise<AnonymousId | undefined> {
  * Return the harness home's anonymous id, creating and persisting one on first use.
  * Persistence is best-effort: a write failure still returns a usable id for the
  * current run so telemetry is never blocked by config-dir permissions.
- * @param options - config-location and UUID-generation seams.
+ * @param options - config-location and UUID-generation hooks.
  * @returns the stable per-harness-home anonymous id.
  */
 export async function getOrCreateAnonymousId(options: AnonymousIdOptions = {}): Promise<AnonymousId> {
diff --git a/packages/scaffold/telemetry/src/reporter.ts b/packages/scaffold/telemetry/src/reporter.ts
index b7ac75a23f..7a03c9a0f7 100644
--- a/packages/scaffold/telemetry/src/reporter.ts
+++ b/packages/scaffold/telemetry/src/reporter.ts
@@ -45,7 +45,7 @@ interface TelemetryEnvelope extends TelemetryPayload {
   sentAt: string
 }
 
-/** Injectable seams for {@link TelemetryReporter}; every field has a default. */
+/** Injectable dependencies for {@link TelemetryReporter}; every field has a default. */
 export interface TelemetryReporterOptions {
   /** Collection endpoint; defaults to {@link DSH_TELEMETRY_ENDPOINT}. */
   endpoint?: string
@@ -71,7 +71,7 @@ export class TelemetryReporter {
   readonly #now: () => number
   readonly #inflight = new Set<Promise<DeliveryOutcome>>()
 
-  /** @param options - endpoint, transport, id provider, and timing seams. */
+  /** @param options - endpoint, transport, id provider, and timing dependencies. */
   constructor(options: TelemetryReporterOptions = {}) {
     this.#endpoint = options.endpoint ?? DSH_TELEMETRY_ENDPOINT
     this.#fetch = options.fetch ?? globalThis.fetch
diff --git a/packages/self-modification/repository-plugin/src/mcp.ts b/packages/self-modification/repository-plugin/src/mcp.ts
index 6c1c5ccbf3..d2294fb5c6 100644
--- a/packages/self-modification/repository-plugin/src/mcp.ts
+++ b/packages/self-modification/repository-plugin/src/mcp.ts
@@ -7,7 +7,7 @@ import { z } from 'zod'
 
 /**
  * Restates dsh-mcp-client's `SERVER_NAME_PATTERN` rather than importing it:
- * the prepare bin must stay a zod-only module graph (no tools seam, no MCP
+ * the prepare bin must stay a zod-only module graph (no tools service, no MCP
  * SDK). Exported so `repository-plugin.spec.ts` pins equality with the
  * client's exported pattern — prepare-time validation cannot drift from the
  * registry that enforces uniqueness.
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index a8fa2b4cff..eb7f2a0eac 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -104,7 +104,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'requireInitiator(): Agent',
-        jsDoc: '/**\n * Read the initiating Agent and fail when no initiator boundary is active.\n * Use this for private helpers contractually below a driver, or for a\n * deployment-owned outbound request whose contract forbids agentless calls.\n * Generic or direct-call seams use optional lookup or explicit request fields.\n * @returns the inherited Agent.\n * @throws when no initiator is active or this service instance has been disposed.\n */',
+        jsDoc: '/**\n * Read the initiating Agent and fail when no initiator boundary is active.\n * Use this for private helpers contractually below a driver, or for a\n * deployment-owned outbound request whose contract forbids agentless calls.\n * Generic or direct-call paths use optional lookup or explicit request fields.\n * @returns the inherited Agent.\n * @throws when no initiator is active or this service instance has been disposed.\n */',
       },
       {
         signature: 'withInitiator<T>(agent: Agent, operation: () => T): T',
@@ -242,7 +242,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
-        jsDoc: '/**\n * Execute one program against the request\'s bindings and capture what it\n * emitted. See the class doc for the resolution contract (error is a result\n * field; rejection means seam misuse only).\n * @param request - the program, its bindings, and the abort signal; the\n *   request carries everything the runtime acts on, with no hidden defaults.\n * @returns the run\'s outcome: completion value (when transferable), the\n *   ordered log capture, and the failure (if any).\n */',
+        jsDoc: '/**\n * Execute one program against the request\'s bindings and capture what it\n * emitted. See the class doc for the resolution contract (error is a result\n * field; rejection means Service Definition contract misuse only).\n * @param request - the program, its bindings, and the abort signal; the\n *   request carries everything the runtime acts on, with no hidden defaults.\n * @returns the run\'s outcome: completion value (when transferable), the\n *   ordered log capture, and the failure (if any).\n */',
       },
     ],
   },
@@ -804,7 +804,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'enter(session: Session): () => void',
-        jsDoc: '/**\n * Enter a {@link prepare}d session into the store: install the module-private\n * append publication hooks and add it to the store. Returns the DETACH\n * disposer (hooks + store removal). Does NOT emit `session/created` —\n * the caller yields this disposer inside its effect and THEN calls\n * {@link announce}, so a throwing `session/created` listener rolls the attach\n * back instead of leaking it.\n *\n * Re-checks the id for a duplicate: `prepare` and `enter` are public\n * cross-package primitives and a caller may interleave arbitrary work (or\n * another create) between them, so a stale prepared session must NOT overwrite\n * a live store entry of the same id — its detach disposer would later delete\n * the REAL session. The {@link create} convenience and the agent factory call\n * the two back-to-back so they never trip this, but the public seam cannot\n * assume that.\n *\n * @param session - a {@link prepare}d session not yet in the store.\n * @returns the detach disposer (publication hooks + store removal). When called from\n *   a synchronous `session/created` listener, removal and disposal wait until\n *   that creation dispatch unwinds.\n * @throws if a session with this id is already in the store.\n */',
+        jsDoc: '/**\n * Enter a {@link prepare}d session into the store: install the module-private\n * append publication hooks and add it to the store. Returns the DETACH\n * disposer (hooks + store removal). Does NOT emit `session/created` —\n * the caller yields this disposer inside its effect and THEN calls\n * {@link announce}, so a throwing `session/created` listener rolls the attach\n * back instead of leaking it.\n *\n * Re-checks the id for a duplicate: `prepare` and `enter` are public\n * cross-package primitives and a caller may interleave arbitrary work (or\n * another create) between them, so a stale prepared session must NOT overwrite\n * a live store entry of the same id — its detach disposer would later delete\n * the REAL session. The {@link create} convenience and the agent factory call\n * the two back-to-back so they never trip this, but the public API cannot\n * assume that.\n *\n * @param session - a {@link prepare}d session not yet in the store.\n * @returns the detach disposer (publication hooks + store removal). When called from\n *   a synchronous `session/created` listener, removal and disposal wait until\n *   that creation dispatch unwinds.\n * @throws if a session with this id is already in the store.\n */',
       },
       {
         signature: 'announce(session: Session): void',
@@ -982,7 +982,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>',
-        jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query seam: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
+        jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query service: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
       },
       {
         signature: 'listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>',
@@ -1094,7 +1094,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract emit(record: TelemetryRecord): void',
-        jsDoc: '/**\n * See {@link TelemetryBackend.emit} — the seam declaration is the contract\'s one home.\n * @param record - the logical record to report; owned by the backend after the call.\n */',
+        jsDoc: '/**\n * See {@link TelemetryBackend.emit} — that declaration is the contract\'s one home.\n * @param record - the logical record to report; owned by the backend after the call.\n */',
       },
       {
         signature: 'flush?(): void',
@@ -1254,7 +1254,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'workflows',
-    summary: 'Workflow execution seam.',
+    summary: 'Workflow Service Definition contract.',
     methods: [
       {
         signature: 'abstract start(request: WorkflowStartRequest): WorkflowRun',
@@ -1307,7 +1307,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/created',
     mode: 'emit',
     signature: '\'agent/created\'(this: Scoped<Agent>, payload: { agent: Agent }): void',
-    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving seam.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param payload.agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving extension point.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param payload.agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A fully configured agent and live session were published.',
   },
   {
@@ -1356,7 +1356,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/request',
     mode: 'waterfall',
     signature: '\'agent/request\'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
-    jsDoc: '/**\n * Replace the frozen call configuration. `await next()` yields the config\n * the machine would use (agent options on the first request, the logged\n * header afterwards); return a replacement to switch. Model-visible\n * content must use logged channels; this seam cannot mutate messages.\n * @param payload.agent - the agent making the model call.\n * @param payload.turn - the open turn number.\n * @param payload.step - the step whose request this is.\n * @param payload.signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n*/',
+    jsDoc: '/**\n * Replace the frozen call configuration. `await next()` yields the config\n * the machine would use (agent options on the first request, the logged\n * header afterwards); return a replacement to switch. Model-visible\n * content must use logged channels; this waterfall cannot mutate messages.\n * @param payload.agent - the agent making the model call.\n * @param payload.turn - the open turn number.\n * @param payload.step - the step whose request this is.\n * @param payload.signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n*/',
     summary: 'Replace the frozen call configuration.',
   },
   {
@@ -1552,7 +1552,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'telemetry/record',
     mode: 'waterfall',
     signature: '\'telemetry/record\'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord',
-    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Live capture dispatches at append time; on-demand capture\n * dispatches while reading the canonical log. Redaction applies to the\n * exported copy only; the canonical session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the Service Definition\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Live capture dispatches at append time; on-demand capture\n * dispatches while reading the canonical log. Redaction applies to the\n * exported copy only; the canonical session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
     summary: 'Transform one outbound record before it reaches the backend.',
   },
   {
@@ -1580,7 +1580,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'tools/post-execute',
     mode: 'waterfall',
     signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
-    jsDoc: '/**\n * Accept, replace, enrich, or block a normalized dispatch result. `next()`\n * accepts it unchanged; thrown tools still reach this seam as errors. Async\n * listeners must observe `exec.signal`; after they settle, caller\n * cancellation replaces only a successful accepted outcome with the code\n * selected by whether the tool body was invoked.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the call that just ran (name, parsed arguments, caller agent).\n * @param result - the dispatch outcome a listener may accept, replace, or block.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Accept, replace, enrich, or block a normalized dispatch result. `next()`\n * accepts it unchanged; thrown tools still reach this waterfall as errors. Async\n * listeners must observe `exec.signal`; after they settle, caller\n * cancellation replaces only a successful accepted outcome with the code\n * selected by whether the tool body was invoked.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the call that just ran (name, parsed arguments, caller agent).\n * @param result - the dispatch outcome a listener may accept, replace, or block.\n * @mode waterfall\n */',
     summary: 'Accept, replace, enrich, or block a normalized dispatch result.',
   },
   {
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index 75fff04fcd..ce1fae24c9 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
-README.md: 4bf4d979f2d2954cd6280c80bf7f5988d8121fd1
-README.zh.md: 56f7dfa8bad3a04a6bf17eac08b62a1a11f4d53f
+README.md: dbbb63e9dd18f3c68cc21b84b560403f4a508709
+README.zh.md: 0b183f63ad2f3cfa670babca80d6e4abee6a4bcb
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
index 4bf4d979f2..dbbb63e9dd 100644
--- a/packages/session-query/session-query-sqlite/README.md
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Concrete `ctx.sessionQuery` backend. `SessionQuerySqlite` inherits exact reads, traces, and provider-independent filters from the interface package and implements its two full-text methods with SQLite FTS5. Search uses the live-preferred logical session corpus and groups cross-session results by their strongest event.
+Concrete `ctx.sessionQuery` provider. `SessionQuerySqlite` inherits exact reads, traces, and provider-independent filters from the Service Definition package and implements its two full-text methods with SQLite FTS5. Search uses the live-preferred logical session corpus and groups cross-session results by their strongest event.
 
 ## Search contract
 
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index 56f7dfa8ba..0b183f63ad 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-具体 `ctx.sessionQuery` 后端。`SessionQuerySqlite` 从接口包继承精确读取、跟踪和提供方无关的过滤，并使用 SQLite FTS5 实现其两个全文方法。搜索使用实时优先的逻辑会话语料库，并按每个会话中匹配度最高的事件对跨会话结果分组。
+具体 `ctx.sessionQuery` 提供方。`SessionQuerySqlite` 从 Service Definition 包继承精确读取、跟踪和提供方无关的过滤，并使用 SQLite FTS5 实现其两个全文方法。搜索使用实时优先的逻辑会话语料库，并按每个会话中匹配度最高的事件对跨会话结果分组。
 
 ## 搜索约定
 
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index f2c6b57c66..b891f5750d 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Combined session-history reads, traces, filters, and full-text search seam.
+ * Service Definition for combined session-history reads, traces, filters, and full-text search.
  *
  * @module @deepseek-ai/dsh-session-query
  */
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 3534382316..8d4aad8e7a 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -161,7 +161,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   }
 
   // Each backend keeps the typed service surface beside its storage hooks;
-  // extracting these trivial forwards would add an inheritance seam.
+  // extracting these trivial forwards would add an inheritance layer.
   /* jscpd:ignore-start */
   // --- SessionPersistence service surface (delegated to the coordinator) ---
 
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index 41cd655b31..0f5de36bc2 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/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/session/session-persistence-sqlite/README.md
-README.md: 4961f62bf6854c343d35b8406c9d721590274534
-README.zh.md: 0507e0fa99bc553317c34e51f30e4daaceee93fd
+README.md: 745c25616e06c391a70b37471917aa9d2539c4dd
+README.zh.md: c86531bcaeca85fa565b537f1fc1beca5d6ac7b3
diff --git a/packages/session/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
index 4961f62bf6..745c25616e 100644
--- a/packages/session/session-persistence-sqlite/README.md
+++ b/packages/session/session-persistence-sqlite/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-A SQLite durable session-persistence backend — a second `SessionPersistence` implementation ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), built to validate that the abstract seam and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
+A SQLite durable session-persistence backend — a second `SessionPersistence` provider ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), built to validate that the Service Definition and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
 
 `locate(meta)` returns `undefined`: all sessions share one database, so there is no honest independent per-session transcript path.
 
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index 0507e0fa99..c86531bcae 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
+SQLite 持久会话存储后端：第二个 `SessionPersistence` 提供方（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证 Service Definition 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
 
 `locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实、独立的逐会话 transcript（文本记录）路径。
 
@@ -22,7 +22,7 @@ SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[
 - **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
 - **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会删除撕裂尾部行、追加恢复行或更改轻量修订。
-- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该修订及其事件行，`readStoredRevision()` 则只查询会话行来校验保留的准备结果。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
+- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该 revision 及其事件行，`readStoredRevision()` 则只查询 session 行来校验保留的 preparation。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
 
 ## 配置（schemastery）
 
@@ -37,7 +37,7 @@ interface Config {
 
 ## 写入路径
 
-与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订递增。
+与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订版本递增。
 
 ## 模型体验
 
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 8341e48a1e..74a0d4c8a9 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 29ee219a55d0823f03bb512c0fa37b7e249817eb
-README.zh.md: c750d2f85fd267a94c36770452f1e5c7e647a2fb
+README.md: c64826db1e9c7339f43a64ad7c13f01a2a39638e
+README.zh.md: 651d920404300fa602f77cee63b0f31aec837919
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 29ee219a55..c64826db1e 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
+The durable session-persistence Service Definition (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract service here, a Service provider in a sibling package, and Consumers that inject the service.
 
 The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage, seed boundary, origin, delegation depth) travels separately as `SessionHeader`, owned by `dsh-session` and re-exported here.
 
@@ -41,7 +41,7 @@ When a live session emits `session/disposed`, the coordinator waits for its cont
 
 The side-effect-free `locate`, lightweight `listSnapshots`, and per-id `readStoredRevision` queries remain backend-owned because they describe storage topology and revision identity rather than write orchestration. `listSnapshots(signal?)` passes the caller's exact signal into backend discovery so observers can cancel that work without detaching it.
 
-The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinator and storage):
+The `PersistenceBackend<TornMarker>` hooks (the only contract between the coordinator and storage):
 
 | Hook | Role |
 |---|---|
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index c750d2f85f..651d920404 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是用于持久保存会话的抽象 seam（`ctx.sessionPersistence`）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：本包提供抽象服务，同级包提供具体实现，消费方注入接口。
+这是用于持久保存会话的 Service Definition（`ctx.sessionPersistence`）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：本包提供抽象服务，同级包提供 Service provider，Consumer 注入服务。
 
 持久化单元就是现有 `SessionEvent`（事件溯源模型：日志是唯一真源），因此不存在另一套并行的「持久消息」类型。不属于可回放对话状态的元数据（格式版本、cwd、血缘、种子边界、origin、委托深度）作为 `SessionHeader` 单独传输，该类型归 `dsh-session` 所有，并在此重新导出。
 
@@ -41,7 +41,7 @@
 
 无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
 
-`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一 seam）：
+`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一约定）：
 
 | 钩子 | 职责 |
 |---|---|
diff --git a/packages/session/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
index cf013887d3..ec4fb72aeb 100644
--- a/packages/session/session-persistence/src/coordinator.ts
+++ b/packages/session/session-persistence/src/coordinator.ts
@@ -78,7 +78,7 @@ export interface StoredSuffix {
 }
 
 /**
- * The storage seam between {@link PersistenceCoordinator} and a concrete
+ * The storage contract between {@link PersistenceCoordinator} and a concrete
  * backend: the minimal set of durable primitives the orchestration calls. A
  * backend implements these (over files, rows, an object store, …); the
  * coordinator supplies everything else (buffering, serialization, cursors,
diff --git a/packages/session/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
index 1d1cf01331..5c3df73b30 100644
--- a/packages/session/session-persistence/src/index.ts
+++ b/packages/session/session-persistence/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Durable session-persistence seam (`ctx.sessionPersistence`). Backends store
+ * Durable session-persistence Service Definition (`ctx.sessionPersistence`). Backends store
  * {@link SessionEvent}s as the event-sourced log and carry non-replayable
  * {@link SessionHeader} metadata separately.
  * @module @deepseek-ai/dsh-session-persistence
@@ -10,7 +10,7 @@ import { SessionPreparation } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionPersistenceRevision } from './revision.ts'
 
-// Re-export the metadata vocabulary so consumers import it from the seam.
+// Re-export the metadata vocabulary so Consumers import it from the Service Definition.
 export type { SessionHeader } from '@deepseek-ai/dsh-session'
 export { SessionPersistenceRevision } from './revision.ts'
 
diff --git a/packages/session/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
index 75455abe81..d3e715b085 100644
--- a/packages/session/session-persistence/tests/persistence.spec.ts
+++ b/packages/session/session-persistence/tests/persistence.spec.ts
@@ -1279,7 +1279,7 @@ describe('PersistenceCoordinator observation cancellation', () => {
       }
       const suffix = await coordinator.readFrom(id, 3)
       expect(suffix.events).toEqual(log.slice(3))
-      // The hook's undefined is the seam's not-found.
+      // The hook's `undefined` is the backend contract's not-found result.
       await expect(coordinator.readFrom(SessionId('missing-seek'), 0)).rejects.toThrow('not found')
 
       // A hook failure with no cancellation in play propagates as-is.
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index a39e3c8586..c7b7530b09 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/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/session/session-projection/README.md
-README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
-README.zh.md: 01b23a7152a509efab6e169043a823d49d6d9fde
+README.md: 2615b253999c798172168ec9d0232eb965b07fbc
+README.zh.md: 0712e9c7a61fbcf43939791b3e7cd24af6777c3a
diff --git a/packages/session/session-projection/README.md b/packages/session/session-projection/README.md
index a42e88c262..2615b25399 100644
--- a/packages/session/session-projection/README.md
+++ b/packages/session/session-projection/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Session-projection seam. It owns `ctx.sessionProjections`, the registry that drives every registered projection unit over committed session events and serves finished whole values to carriers, currently the api-proxy history tail page and `session/projection` push frame. A domain registers pure mathematics; the framework owns the drive. The [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) records the design rationale.
+Session-projection Service Definition and drive registry. It owns `ctx.sessionProjections`, the registry that drives every registered projection unit over committed session events and serves finished whole values to carriers, currently the api-proxy history tail page and `session/projection` push frame. A domain registers pure mathematics; the framework owns the drive. The [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) records the design rationale.
 
 ## Service: `SessionProjectionRegistry` (ctx key: `sessionProjections`)
 
@@ -25,11 +25,11 @@ Session-projection seam. It owns `ctx.sessionProjections`, the registry that dri
 - **Synchronous unit discipline.** `init`/`apply`/`view` MUST be synchronous; carriers read `snapshot()` in the same tick as their page slice, which is what makes `asOfSeq` one consistent cut. An accidentally-async `view` returns a Promise, which fails the boundary `schema.parse` loudly.
 - **State is plain JSON, `stateVersion` is its invalidation anchor.** The persisted projection cache stores `(sessionId, key, ver, seq, val)` rows; bump `stateVersion` whenever the state shape or the fold semantics change so stale rows are discarded instead of forward-applied into garbage.
 - **No wire vocabulary here.** The registry exposes only the change feed and the snapshot read face; carriers (api-proxy) mint their own frames (`session/projection`) and blocks from them.
-- **Optional seam.** Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected; carriers use `ctx.get('sessionProjections')` and omit their block/frames entirely when the registry is absent.
+- **Optional capability.** Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected; carriers use `ctx.get('sessionProjections')` and omit their block/frames entirely when the registry is absent.
 
 ## Role
 
-This is the interface-plus-drive package of the capability-seam split: domain host plugins (e.g. `dsh-tool-todo`) contribute units, carriers (`dsh-host-apiproxy`) consume the snapshot and change feed, and neither knows the other.
+This package owns the Service Definition and drive roles of the capability seam: domain host plugins (e.g. `dsh-tool-todo`) contribute units, carriers (`dsh-host-apiproxy`) consume the snapshot and change feed, and neither knows the other.
 
 ## Model Experience
 
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index 01b23a7152..0712e9c7a6 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-会话投影 seam。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) 记录了设计理由。
+会话投影 Service Definition 与驱动注册表。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)记录了设计理由。
 
 ## 服务：`SessionProjectionRegistry`（ctx 键：`sessionProjections`）
 
@@ -25,11 +25,11 @@
 - **单元的同步纪律。**`init`/`apply`/`view` 必须是同步的；载体在切出页面切片的同一 tick 内读取 `snapshot()`，`asOfSeq` 之所以是一个一致切面正系于此。误写成异步的 `view` 会返回 Promise，让边界的 `schema.parse` 当场大声失败。
 - **状态是纯 JSON，`stateVersion` 是其失效锚点。** 持久投影缓存（persisted projection cache）存储 `(sessionId, key, ver, seq, val)` 行；状态形状或折叠语义一旦变化就递增 `stateVersion`，使陈旧行被丢弃，而不是被正向 apply 成垃圾。
 - **本层没有协议词汇。** 注册表只暴露变更流与快照读取面；载体（api-proxy）据此自铸各自的帧（`session/projection`）与块。
-- **可选 seam。** 领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响；载体使用 `ctx.get('sessionProjections')`，注册表缺席时完全省略自己的块与帧。
+- **可选能力。** 领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响；载体使用 `ctx.get('sessionProjections')`，注册表缺席时完全省略自己的块与帧。
 
 ## 职责
 
-这是能力 seam 拆分中「接口 + 驱动」的那个包：领域 host 插件（如 `dsh-tool-todo`）贡献单元，载体（`dsh-host-apiproxy`）消费快照与变更流，两侧互不相识。
+本包承担能力 seam 的 Service Definition 与驱动角色：领域 host 插件（如 `dsh-tool-todo`）贡献单元，载体（`dsh-host-apiproxy`）消费快照与变更流，两侧互不相识。
 
 ## 模型体验
 
diff --git a/packages/session/session-projection/src/index.ts b/packages/session/session-projection/src/index.ts
index 90c36ed579..208c850363 100644
--- a/packages/session/session-projection/src/index.ts
+++ b/packages/session/session-projection/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Session-projection seam: the merge-extensible `SessionProjectionMap` type
+ * Service Definition and drive registry for the session-projection capability seam: the merge-extensible `SessionProjectionMap` type
  * table, the `ProjectionDefinition` state-driven computation unit contract,
  * and the `ctx.sessionProjections` registry that DRIVES every registered unit
  * forward eagerly over committed session events. Domain host plugins
@@ -117,7 +117,7 @@ export interface ProjectionCheckpointRow {
 /** Checkpoint rows keyed by projection key (one session's persisted cache value). */
 export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>
 
-/** Type-erased unit view the drive machinery works with (the register seam already proved the typed contract). */
+/** Type-erased unit view the drive machinery works with (the registration contract already proved the typed form). */
 interface ErasedDefinition {
   key: string
   schema: { parse(value: unknown): unknown }
diff --git a/packages/session/session-projection/src/types.ts b/packages/session/session-projection/src/types.ts
index 39f2aa24e2..37d24b5b40 100644
--- a/packages/session/session-projection/src/types.ts
+++ b/packages/session/session-projection/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Pure-type outlet of the session-projection seam: the one projection type
+ * Pure-type outlet of the session-projection Service Definition: the one projection type
  * table, importable from client aggregates without dragging the host-side
  * cordis Context merges of the package root (dsh-agent → dsh-session). Domain
  * packages may declare-merge through either the package root or this outlet —
diff --git a/packages/session/session-telemetry-otel/src/index.ts b/packages/session/session-telemetry-otel/src/index.ts
index 4f146bdb95..37ba236477 100644
--- a/packages/session/session-telemetry-otel/src/index.ts
+++ b/packages/session/session-telemetry-otel/src/index.ts
@@ -1,9 +1,9 @@
 /**
- * OpenTelemetry backend for the DeepSeek Harness telemetry seam.
+ * OpenTelemetry Service provider for the DeepSeek Harness telemetry capability.
  *
  * Composes the OTel JS SDK as-is — a `LoggerProvider` with a
  * `BatchLogRecordProcessor` and an OTLP/HTTP log exporter — and maps each
- * record handed over by the seam onto `logger.emit()`. Per the seam's
+ * record handed over by the capture coordinator onto `logger.emit()`. Per the Service Definition's
  * boundary axiom, everything downstream of that call (batching, retry,
  * queueing, loss policy) is the SDK's documented behavior, configured
  * verbatim through the `exporter`/`processor` passthroughs. This package owns
@@ -121,7 +121,7 @@ export const DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 3_000
 // protocol limit, not a deployment default.
 const MAX_TIMER_DELAY_MILLIS = 2_147_483_647
 
-/** Severity mapping from the seam's three-level vocabulary to OTel severity numbers. */
+/** Severity mapping from the Service Definition's three-level vocabulary to OTel severity numbers. */
 const SEVERITY: Record<TelemetrySeverity, { severityNumber: SeverityNumber; severityText: string }> = {
   info: { severityNumber: SeverityNumber.INFO, severityText: 'INFO' },
   warn: { severityNumber: SeverityNumber.WARN, severityText: 'WARN' },
@@ -250,7 +250,7 @@ export class TelemetryOtel extends Telemetry {
     this.directEmit(record)
   }
 
-  // The seam's optional flush() hint is deliberately NOT implemented. The
+  // The Service Definition's optional flush() hint is deliberately NOT implemented. The
   // batch processor exports on its own cadence (`processor.scheduledDelayMillis`,
   // the SDK's documented knob), and this backend is the SDK pipeline's only
   // caller — forwarding the hint to `forceFlush()` was the sole source of
diff --git a/packages/session/session-telemetry-otel/src/invariant.ts b/packages/session/session-telemetry-otel/src/invariant.ts
index 030b7ce670..0eaffeb8b5 100644
--- a/packages/session/session-telemetry-otel/src/invariant.ts
+++ b/packages/session/session-telemetry-otel/src/invariant.ts
@@ -17,7 +17,7 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: mode selection changes capture handoff, SDK setup, and
  * local diagnostics without mutating session or service state an independent
- * companion can compare. Export remains inside the SDK past the seam boundary.
+ * companion can compare. Export remains inside the SDK past the backend boundary.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/session/session-telemetry-otel/src/user-id.ts b/packages/session/session-telemetry-otel/src/user-id.ts
index f06d9856fe..0a2cf95a6a 100644
--- a/packages/session/session-telemetry-otel/src/user-id.ts
+++ b/packages/session/session-telemetry-otel/src/user-id.ts
@@ -33,11 +33,11 @@ export const USER_ID_FILE_NAME = '.userid'
 
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
-/** Ambient seams for locating and generating the id; every field has a default. */
+/** Ambient hooks for locating and generating the id; every field has a default. */
 export interface AnonymousUserIdOptions {
   /** Environment consulted for `DSH_HOME`; defaults to `process.env`. */
   env?: NodeJS.ProcessEnv
-  /** UUID generator; defaults to `crypto.randomUUID` (test seam). */
+  /** UUID generator; defaults to `crypto.randomUUID` (test hook). */
   randomUUID?: () => string
 }
 
@@ -65,7 +65,7 @@ function readPersistedId(file: string): AnonymousUserId | undefined {
  * run; the next launch converges on the persisted one.) Persistence is
  * best-effort — a write failure (read-only home) still returns a usable id
  * for the current run so telemetry is never blocked.
- * @param options - home-location and UUID-generation seams.
+ * @param options - Home-location and UUID-generation hooks.
  * @returns the stable per-harness-home anonymous user id.
  */
 export function getOrCreateAnonymousUserId(options: AnonymousUserIdOptions = {}): AnonymousUserId {
diff --git a/packages/session/session-telemetry-otel/tests/user-id.spec.ts b/packages/session/session-telemetry-otel/tests/user-id.spec.ts
index f4d9505546..63106c7316 100644
--- a/packages/session/session-telemetry-otel/tests/user-id.spec.ts
+++ b/packages/session/session-telemetry-otel/tests/user-id.spec.ts
@@ -57,7 +57,7 @@ describe('getOrCreateAnonymousUserId', () => {
     const home = tempHome()
     const winner = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee'
     const file = join(home, USER_ID_FILE_NAME)
-    // The generator seam runs between the initial read (absent) and the wx
+    // The generator hook runs between the initial read (absent) and the wx
     // write, so planting the winner here simulates the concurrent first launch.
     const id = getOrCreateAnonymousUserId({
       env: { DSH_HOME: home },
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index 5fd708de38..c6c4b9eff9 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/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/session/session-telemetry/README.md
-README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
-README.zh.md: 80044ceb57c93f8406398a9239d83cbb6015e98c
+README.md: 506f0f5bcb03a54f09805ed0f866a396e3cf0334
+README.zh.md: b5e47c8832452ece281dcdcfac007d6082813583
diff --git a/packages/session/session-telemetry/README.md b/packages/session/session-telemetry/README.md
index 67d95bcc62..506f0f5bcb 100644
--- a/packages/session/session-telemetry/README.md
+++ b/packages/session/session-telemetry/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The telemetry seam: the capture side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. Capture can follow live session events or replay a canonical session-log prefix on demand. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
+The telemetry Service Definition and capture coordinator sit behind a backend contract any reporting SDK satisfies with zero bending. Capture can follow live session events or replay a canonical session-log prefix on demand. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
 
 ## The backend contract
 
@@ -14,7 +14,7 @@ In `live` mode the coordinator registers, all through the composing fiber's effe
 
 ## The redact waterfall
 
-Every record passes the `telemetry/record` waterfall immediately after projection — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
+Every record passes the `telemetry/record` waterfall immediately after projection — the Service Definition's scrubbing extension point. This package ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
 
 ## The handoff cursor
 
@@ -30,7 +30,7 @@ Only the first `assistant/chunk` of each `(turn, step)` ships; the rest are drop
 
 ## Model Experience
 
-None, as the seam only observes the session stream and hands redacted copies to a reporting backend; it never contributes to a model request.
+None, as this package only observes the session stream and hands redacted copies to a reporting backend; it never contributes to a model request.
 
 #### KV Cache effect
 
diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
index 80044ceb57..b5e47c8832 100644
--- a/packages/session/session-telemetry/README.zh.md
+++ b/packages/session/session-telemetry/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
+遥测（telemetry）Service Definition 与捕获协调器位于一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
 ## 后端约定
 
@@ -14,7 +14,7 @@
 
 ## 脱敏 waterfall（瀑布式事件）
 
-每条记录在投影后立即经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
+每条记录在投影后立即经过 `telemetry/record` waterfall，这是 Service Definition 的脱敏扩展点。本包自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
 
 ## handoff 游标
 
@@ -30,7 +30,7 @@
 
 ## 模型体验
 
-无。该 seam 只观察会话流，并把脱敏后的副本交给上报后端；它绝不向模型请求贡献任何内容。
+无。本包只观察会话流，并把脱敏后的副本交给上报后端；它绝不向模型请求贡献任何内容。
 
 #### KV Cache 影响
 
diff --git a/packages/session/session-telemetry/src/coordinator.ts b/packages/session/session-telemetry/src/coordinator.ts
index 4e99859a4f..f06d1b7b9e 100644
--- a/packages/session/session-telemetry/src/coordinator.ts
+++ b/packages/session/session-telemetry/src/coordinator.ts
@@ -1,5 +1,5 @@
 /**
- * Capture coordinator: the seam's upstream half. Live capture subscribes to
+ * Capture coordinator for the telemetry capability. Live capture subscribes to
  * the session firehose plus the one live-bus relay (`agent/error`). Both
  * capture paths apply the fixed chunk projection, build logical records, and
  * run each through the
@@ -159,7 +159,7 @@ export class TelemetryCoordinator {
    * at or below the start still feed the projection state (first-chunk
    * tracking) without being re-handed, so a resumed fiber drops mid-step
    * chunk continuations exactly like the fiber that saw the step begin. The
-   * cost, accepted with the seam's at-most-once stance: a resume no longer
+   * cost, accepted with the capture contract's at-most-once stance: a resume no longer
    * backfills records a previous process failed to deliver.
    * @param session - the live session to adopt; a second adoption is a no-op.
    */
@@ -204,7 +204,7 @@ export class TelemetryCoordinator {
 
   /**
    * Run the `telemetry/record` waterfall at capture time. The innermost `next`
-   * passes the record through unchanged — the seam ships no rules; exported
+   * passes the record through unchanged — this package ships no rules; exported
    * data is as clean as the listeners a deployment mounts. Callers run inside
    * {@link contain}, so a throwing rule withholds the record instead of
    * reaching the loop (fail-closed). On-demand capture invokes this waterfall
@@ -289,7 +289,7 @@ function severityOf(event: SessionEvent): TelemetrySeverity {
     case 'turn/end':
       return event.data.reason.kind === 'error' ? 'error' : 'info'
     default:
-      // Merge-extensible fall-through (no assertNever): event types this seam
+      // Merge-extensible fall-through (no assertNever): event types this coordinator
       // does not depend on — including plugin-merged ones it never heard of —
       // pass through as info; their owners' outcome semantics stay theirs.
       return 'info'
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 6a8e9ed2ad..7606cc3ca6 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -1,7 +1,7 @@
 /**
- * Telemetry seam for the DeepSeek Harness.
+ * Telemetry Service Definition for the DeepSeek Harness.
  *
- * The seam owns the CAPTURE side of session-event reporting — which records
+ * This package owns the CAPTURE side of session-event reporting — which records
  * exist (the chunk projection), what they carry (the logical record), when
  * they are captured (adoption, the per-append firehose, lifecycle
  * forwarding), live versus on-demand canonical-log capture, and the HMR
@@ -24,7 +24,7 @@ declare module 'cordis' {
   interface Events {
     /**
      * Transform one outbound record before it reaches the backend. This
-     * waterfall is the seam's redaction extension point. It ships NO rules
+     * waterfall is the Service Definition's redaction extension point. It ships NO rules
      * of its own: the
      * innermost `next()` passes the record through unchanged, and with no
      * listener mounted records reach the backend as captured, so exported
@@ -55,7 +55,7 @@ declare module 'cordis' {
 export type TelemetrySeverity = 'info' | 'warn' | 'error'
 
 /**
- * One logical record handed to a backend — the seam's whole outbound
+ * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
  * operational records (`channel: 'ops'`) carry the two signals with no log
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
@@ -143,7 +143,7 @@ export abstract class Telemetry extends Service implements TelemetryBackend {
   }
 
   /**
-   * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+   * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   abstract emit(record: TelemetryRecord): void
diff --git a/packages/session/session-telemetry/src/invariant.ts b/packages/session/session-telemetry/src/invariant.ts
index ffc55b0107..1c265877f8 100644
--- a/packages/session/session-telemetry/src/invariant.ts
+++ b/packages/session/session-telemetry/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'session-telemetry-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the seam's whole output is the backend handoff — a
+ * No runtime invariant: the package's whole output is the backend handoff — a
  * synchronous `emit()` call outside every authoritative event stream — and its
  * capture side never appends session events, so no event/data relation exists
  * for an independent companion to observe.
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index ab2298aa6c..12ca7924b4 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Log-backed session title service, deterministic fallback, and provider seam.
+ * Log-backed session title service, deterministic fallback, and provider contract.
  * @module @deepseek-ai/dsh-session-title
  */
 
diff --git a/packages/settings/settings-local/tests/lock-race.spec.ts b/packages/settings/settings-local/tests/lock-race.spec.ts
index 3ef6f16fa4..46dd24353f 100644
--- a/packages/settings/settings-local/tests/lock-race.spec.ts
+++ b/packages/settings/settings-local/tests/lock-race.spec.ts
@@ -1,4 +1,4 @@
-// A temp-file write failure cannot be timed from outside. The fs/promises seam
+// A temp-file write failure cannot be timed from outside. The `fs/promises` API
 // injects it once so the test can prove that the writer lock still releases.
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index 8a8522fe57..4452e78dab 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/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/settings/settings/README.md
-README.md: 49ae5b405c003b6116e459cf377fc7a099538f2e
-README.zh.md: d8f3bff5878b575d571b7aab4b627daa51e215f1
+README.md: 5bfbf4623c937c2b66886f71adf27075523f5d28
+README.zh.md: 98808424ba1af2210067bd7f74baa6027decbb06
diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md
index 49ae5b405c..5bfbf4623c 100644
--- a/packages/settings/settings/README.md
+++ b/packages/settings/settings/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Abstract user-settings seam (`ctx.settings`). One provider holds a raw document of per-namespace sections; plugins register a namespace schema and read a resolved value layered as schema defaults, then the registrant's composition `base` (its cordis.yml entry-config subset), then the user document section. Without a mounted provider nothing changes for consumers: they keep resolving entry config alone, so every composition works with or without settings.
+User-settings Service Definition (`ctx.settings`). One provider holds a raw document of per-namespace sections; plugins register a namespace schema and read a resolved value layered as schema defaults, then the registrant's composition `base` (its cordis.yml entry-config subset), then the user document section. Without a mounted provider nothing changes for consumers: they keep resolving entry config alone, so every composition works with or without settings.
 
 ## Service API
 
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index d8f3bff587..98808424ba 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象用户设置 seam（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
+用户设置 Service Definition（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
 
 ## 服务 API
 
diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts
index 64e9f147b1..d0f85a2b1b 100644
--- a/packages/settings/settings/src/index.ts
+++ b/packages/settings/settings/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * User-settings seam (`ctx.settings`). Providers store one raw document of
+ * Service Definition for the user-settings capability seam (`ctx.settings`). Providers store one raw document of
  * per-namespace sections; plugins register a namespace schema and read the
  * resolved value, which layers schema defaults, the registrant's composition
  * `base`, and the user document section, in that order.
@@ -69,7 +69,7 @@ export interface SettingsRegisterOptions<T> {
 /** One registered namespace as surfaced to configuration UIs. */
 export interface SettingsDescriptor {
   // TODO(settings-namespace-vocabulary): Rename `ns` to `namespace` across the
-  // public seam, provider contract, implementations, tests, and consumers.
+  // public API, provider contract, implementations, tests, and consumers.
   /** The registered namespace. */
   ns: SettingsNamespace
   /** Serialized schemastery schema (`schema.toJSON()`). */
@@ -173,7 +173,7 @@ declare module 'cordis' {
 
 /**
  * Deep equality over JSON-shaped data (objects, arrays, primitives) — the
- * seam's single change-detection predicate, exported so the invariant
+ * Service Definition's single change-detection predicate, exported so the invariant
  * companion checks exactly the implementation's relation.
  * @param a - one JSON-shaped value.
  * @param b - the other JSON-shaped value.
@@ -195,7 +195,7 @@ export function deepEqualJson(a: unknown, b: unknown): boolean {
 
 /**
  * A write refused because the namespace moved since the caller read it. The
- * seam's serialized write queue orders writes; it cannot tell a fresh writer
+ * Service Definition's serialized write queue orders writes; it cannot tell a fresh writer
  * from one holding a stale snapshot, which is what this reports.
  */
 export class SettingsConflictError extends Error {
diff --git a/packages/settings/settings/tests/memory.ts b/packages/settings/settings/tests/memory.ts
index bb310c939d..58ce1f545e 100644
--- a/packages/settings/settings/tests/memory.ts
+++ b/packages/settings/settings/tests/memory.ts
@@ -1,5 +1,5 @@
 /**
- * In-memory settings provider fixture: the smallest real subclass of the seam,
+ * In-memory settings provider fixture: the smallest real subclass of the Service Definition,
  * used by the base-class behavior suite in place of a file- or network-backed
  * provider. Kept in `tests/` because production providers live in their own
  * packages.
@@ -7,7 +7,7 @@
 
 import { Settings, type SettingsNamespace } from '../src/index.ts'
 
-/** In-memory provider exposing the protected seam hooks to tests. */
+/** In-memory provider exposing the protected provider hooks to tests. */
 export class MemorySettings extends Settings {
   /** Raw document the provider "storage" currently holds. */
   doc: Record<string, unknown>
diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts
index c6a1e57016..66c0f1fcf6 100644
--- a/packages/settings/settings/tests/settings.spec.ts
+++ b/packages/settings/settings/tests/settings.spec.ts
@@ -4,7 +4,7 @@ import z from 'schemastery'
 import { Settings, SettingsConflictError, deepEqualJson, installSettingsSection, settingsNamespace, type SettingsNamespace, type SettingsScope, type SettingsUpdateSource } from '../src/index.ts'
 import { MemorySettings } from './memory.ts'
 
-/** A provider implementing only the three primitives: the seam owns init. */
+/** A provider implementing only the three primitives: the Service Definition owns initialization. */
 class BareProvider extends Settings {
   doc: Record<string, unknown>
 
diff --git a/packages/skill/skill/src/index.ts b/packages/skill/skill/src/index.ts
index 16af8d55d3..18c878d74b 100644
--- a/packages/skill/skill/src/index.ts
+++ b/packages/skill/skill/src/index.ts
@@ -1,7 +1,8 @@
 /**
  * Agent skill provider registry.
  *
- * This package is the interface third of the skill capability seam. Concrete
+ * This package owns the Service Definition role of the skill capability seam.
+ * Concrete
  * providers such as `@deepseek-ai/dsh-skill-local` decide where skills come
  * from; this service only merges provider catalogs, resolves the winning skill
  * for a name, and exposes the winning summaries and definitions to consumers.
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index 58ae7e6afd..f78825d1f7 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/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/skill/tool-skill/README.md
-README.md: b7309657d85a3d2a19de78a4ee6173d742519daa
-README.zh.md: 10834e13b4bfb745b4cd084ce41f616a8dd95807
+README.md: fd2cb2dc00994a79856ad605ce126387c27a9f65
+README.zh.md: 3fb76e079033ef39e475e6795cf28407e52a83cc
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index b7309657d8..fd2cb2dc00 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -36,7 +36,7 @@ Tool execution does not add a synthetic context message. Its freshly loaded resu
 
 #### What the model sees
 
-If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
 
 ##### Skill catalog template
 
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index 10834e13b4..3fb76e0790 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个分支——包括清空后的目录——都携带同一句话。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
 
 ##### Skill 目录模板
 
@@ -149,11 +149,11 @@ Load referenced resources only as needed.
 
 #### 模型看到的内容
 
-已认领的用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
+已认领用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
 
 #### Token 影响
 
-每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——其大小与同一 skill 的工具结果相同；这项成本会在用户请求时确定产生，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
+每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——尺寸与同一 skill 的工具结果相同，按用户的请求确定性地支付，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
 
 #### KV Cache 影响
 
diff --git a/packages/spill/spill-policy/src/index.ts b/packages/spill/spill-policy/src/index.ts
index 470fd1cacd..45d7ba2e74 100644
--- a/packages/spill/spill-policy/src/index.ts
+++ b/packages/spill/spill-policy/src/index.ts
@@ -69,7 +69,7 @@ export interface Config {
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'spill-policy'
 
-/** Require the tool registry (its `tools/post-execute` waterfall is the seam we transform). */
+/** Require the tool registry (its `tools/post-execute` waterfall is the extension point we transform). */
 export const inject = ['tools']
 
 export const Config: z<Config> = z.object({
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index cddfc91ea7..2478cdc7d4 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
-README.md: ecaef9fc53ec3d9017143cfc012abc9cabe77072
-README.zh.md: 5393ccb312245f3bbfcf28ea8e097b0a343966e9
+README.md: a9e3ec7169e0239117f7f9222ad2ba53619e0369
+README.zh.md: 9bfacda928e30a1338bedaef9d39e43cff4c667d
diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md
index ecaef9fc53..a9e3ec7169 100644
--- a/packages/spill/spill/README.md
+++ b/packages/spill/spill/README.md
@@ -8,11 +8,11 @@ This package is one third of the spill capability, split so each concern evolves
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-spill` (this) | the interface: abstract service + vocabulary types |
-| `@deepseek-ai/dsh-spill-local` | an implementation: private session-scoped files on the host filesystem |
-| `@deepseek-ai/dsh-spill-policy` | the tool-result policy that spills oversized final results |
+| `@deepseek-ai/dsh-spill` (this) | Service Definition: abstract service + vocabulary types |
+| `@deepseek-ai/dsh-spill-local` | Service provider: private session-scoped files on the host filesystem |
+| `@deepseek-ai/dsh-spill-policy` | Consumer: the tool-result policy that spills oversized final results |
 
-The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this interface without touching the policy plugin.
+The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this Service Definition without touching the policy plugin.
 
 ## Service API (`ctx.spillStore`)
 
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index 5393ccb312..9bfacda928 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -8,11 +8,11 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-spill`（本包） | 接口：抽象服务与词汇类型 |
-| `@deepseek-ai/dsh-spill-local` | 实现：位于宿主文件系统中的私有会话级文件 |
-| `@deepseek-ai/dsh-spill-policy` | 对过大最终结果执行 spill 的工具结果策略 |
+| `@deepseek-ai/dsh-spill`（本包） | Service Definition：抽象服务与词汇类型 |
+| `@deepseek-ai/dsh-spill-local` | Service provider：位于宿主文件系统中的私有会话级文件 |
+| `@deepseek-ai/dsh-spill-policy` | Consumer：对过大最终结果执行 spill 的工具结果策略 |
 
-这种拆分方式与 bash/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此接口，无需修改策略插件。
+这种拆分方式与 bash/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此 Service Definition，无需修改策略插件。
 
 ## 服务 API（`ctx.spillStore`）
 
diff --git a/packages/spill/spill/src/index.ts b/packages/spill/spill/src/index.ts
index 73bfe75f33..0d98ea9f66 100644
--- a/packages/spill/spill/src/index.ts
+++ b/packages/spill/spill/src/index.ts
@@ -1,11 +1,11 @@
 /**
- * The spill storage seam (`ctx.spillStore`): an abstract service defining WHAT a
+ * Service Definition for the spill storage capability seam (`ctx.spillStore`): an abstract service defining WHAT a
  * spill backend does — persist a tool's oversized text and return a model-facing
  * locator plus retrieval guidance — without saying HOW. Implementations
  * subclass {@link SpillStore} and register as the `spillStore` service;
  * `@deepseek-ai/dsh-spill-local` (host filesystem) is the first.
  *
- * The seam is deliberately minimal: `saveText` and nothing else. It owns NO
+ * The Service Definition is deliberately minimal: `saveText` and nothing else. It owns NO
  * retention policy (that is `@deepseek-ai/dsh-retention`), NO tool-result
  * replacement (that is `@deepseek-ai/dsh-spill-policy`), and NO retrieval or
  * search API. The backend supplies the locator and retrieval hint appropriate
diff --git a/packages/spill/spill/src/types.ts b/packages/spill/spill/src/types.ts
index a3657e5c3c..f07e13f4ef 100644
--- a/packages/spill/spill/src/types.ts
+++ b/packages/spill/spill/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the spill storage seam. Types only — the abstract service
+ * Vocabulary for the spill storage Service Definition. Types only — the abstract service
  * lives in `./index.ts`, implementations in sibling packages
  * (`@deepseek-ai/dsh-spill-local` first).
  *
diff --git a/packages/spill/spill/tests/service.spec.ts b/packages/spill/spill/tests/service.spec.ts
index ddbc4086e1..141072d67a 100644
--- a/packages/spill/spill/tests/service.spec.ts
+++ b/packages/spill/spill/tests/service.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the spill seam INTERFACE: a minimal concrete subclass registers as
+ * Tests for the spill Service Definition: a minimal concrete subclass registers as
  * `ctx.spillStore`, a second load throws (duplicate service), and disposal
  * releases the service. The storage behavior is the implementation's concern
  * (`@deepseek-ai/dsh-spill-local`); here we only pin the seam contract.
diff --git a/packages/storage/README.i18n.yaml b/packages/storage/README.i18n.yaml
index ef32481991..2d6db691b7 100644
--- a/packages/storage/README.i18n.yaml
+++ b/packages/storage/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/storage/README.md
-README.md: a178495fca5cc433182b8e75f20d479cb7c5bc99
-README.zh.md: 1a08f1676e5c699a55f9956a42059d1f5acf7e8d
+README.md: dd9eb5ac97529c75df5986c56b714331dca0b6f1
+README.zh.md: a69414826b3ffd613c432836ea506b664ceb8da5
diff --git a/packages/storage/README.md b/packages/storage/README.md
index a178495fca..dd9eb5ac97 100644
--- a/packages/storage/README.md
+++ b/packages/storage/README.md
@@ -13,4 +13,4 @@ This family persists application data other than session event logs through name
 
 Consumers use a data form rather than accessing a backend directly. The [domain storage decision](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the family design.
 
-The subsystem reference — the backend seam, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).
+The subsystem reference — the backend contract, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).
diff --git a/packages/storage/README.zh.md b/packages/storage/README.zh.md
index 1a08f1676e..a69414826b 100644
--- a/packages/storage/README.zh.md
+++ b/packages/storage/README.zh.md
@@ -13,4 +13,4 @@
 
 消费方使用数据形式，而不是直接访问后端。[领域存储决策](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了该家族的设计。
 
-子系统参考——后端 seam、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。
+子系统参考——后端约定、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。
diff --git a/packages/storage/storage-domain/README.i18n.yaml b/packages/storage/storage-domain/README.i18n.yaml
index 2b5cbc7a14..80ccac9a5f 100644
--- a/packages/storage/storage-domain/README.i18n.yaml
+++ b/packages/storage/storage-domain/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/storage/storage-domain/README.md
-README.md: 41e777c3d9a870530593a414839f905514a27134
-README.zh.md: 2f6b4daa09769d5a03eb30964c12447951c432e3
+README.md: 7c058ab557cfb128f54c15e715685d59f6720696
+README.zh.md: 10eb33711e147bc5ac6b7770a196bfea4fe66306
diff --git a/packages/storage/storage-domain/README.md b/packages/storage/storage-domain/README.md
index 41e777c3d9..7c058ab557 100644
--- a/packages/storage/storage-domain/README.md
+++ b/packages/storage/storage-domain/README.md
@@ -19,7 +19,7 @@ Design rationale, open semantics, and the storage/domain layer split live in the
 
 #### What the model sees
 
-Nothing. The package registers no tools, injects no prompts, and appends no session events; it stores non-session data (workspace records, future session sidecars) behind `ctx.storageDomain` and emits only the in-process `domain/changed` event, which reaches a model only if a consumer package renders it through its own documented surface.
+Nothing. The package registers no tools, injects no prompts, and appends no session events; it stores non-session data (workspace records, future session sidecars) behind `ctx.storageDomain` and emits only the in-process `domain/changed` event, which reaches a model only if a Consumer package renders it through its own documented surface.
 
 #### Token effect
 
diff --git a/packages/storage/storage-domain/README.zh.md b/packages/storage/storage-domain/README.zh.md
index 2f6b4daa09..10eb33711e 100644
--- a/packages/storage/storage-domain/README.zh.md
+++ b/packages/storage/storage-domain/README.zh.md
@@ -19,7 +19,7 @@ DeepSeek Harness 存储中心的领域数据形式：在所有已配置的后端
 
 #### 模型看到的内容
 
-无。该包不注册工具、不注入提示词，也不追加会话事件；它在 `ctx.storageDomain` 后面存储非会话数据（工作区记录、未来的会话伴随数据），只发出进程内 `domain/changed` 事件。只有消费方包通过自身有文档说明的接口呈现该事件时，它才会到达模型。
+无。该包不注册工具、不注入提示词，也不追加会话事件；它在 `ctx.storageDomain` 后面存储非会话数据（工作区记录、未来的会话伴随数据），只发出进程内 `domain/changed` 事件。只有 Consumer 包通过自身有文档说明的接口呈现该事件时，它才会到达模型。
 
 #### Token 影响
 
diff --git a/packages/storage/storage-domain/src/domain.ts b/packages/storage/storage-domain/src/domain.ts
index 7327580630..26ed726b93 100644
--- a/packages/storage/storage-domain/src/domain.ts
+++ b/packages/storage/storage-domain/src/domain.ts
@@ -118,7 +118,7 @@ export interface Domain<S extends DomainSpec> {
   close(): Promise<void>
 }
 
-/** Internal seam handing table handles their domain-owned write machinery. */
+/** Internal boundary handing table handles their domain-owned write machinery. */
 interface TableHost {
   readonly domainName: string
   readonly unit: KvUnit
diff --git a/packages/storage/storage-domain/tests/helpers/memory-backend.ts b/packages/storage/storage-domain/tests/helpers/memory-backend.ts
index 1eb1bffe2d..3c8547d280 100644
--- a/packages/storage/storage-domain/tests/helpers/memory-backend.ts
+++ b/packages/storage/storage-domain/tests/helpers/memory-backend.ts
@@ -39,7 +39,7 @@ export class MemoryMediaPool {
   /**
    * When positive, that many subsequent write primitives (putRecord /
    * deleteRecord / setGlobal) reject without touching the medium, decrementing
-   * per rejection. Negative-path seam: callers assert their state is
+   * per rejection. Negative path: callers assert their state is
    * untouched after a durability failure.
    */
   failNextWrites = 0
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index c7d3ce46ee..10ad9837b2 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/README.md
-README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
-README.zh.md: 04351f26721849de730db6083f55abc8e8571ce4
+README.md: 134028c9993255464c08d912d305c65ed85d65c0
+README.zh.md: ab4284d0525ceed349a778385c918a9dec19406f
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index c8969ad313..134028c999 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -20,4 +20,4 @@ This family lets an agent delegate work to child agents. Multiple named provider
 
 See the decisions for the [capability family](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable children](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [control tools](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
-The subsystem reference — start requests, results, live runs, the provider seam, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.
+The subsystem reference — start requests, results, live runs, the provider contract, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index 04351f2672..ab4284d052 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -20,4 +20,4 @@
 
 参见有关[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)的决策。
 
-子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
+子系统参考——启动请求、结果、实时运行、提供方约定、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
index d361d26f4f..9216068b07 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
@@ -11,7 +11,7 @@ import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 import * as acp from '../src/index.ts'
 
 /**
- * With-key cross-process seam proof: the backend spawns the real acp-agent example, speaks ACP over
+ * With-key cross-process boundary proof: the backend spawns the real acp-agent example, speaks ACP over
  * stdio, and returns its real model answer. This is the out-of-process counterpart to in-process
  * spawn coverage and self-skips without `DEEPSEEK_API_KEY`.
  */
diff --git a/packages/subagent/subagent-claude-code/src/run.ts b/packages/subagent/subagent-claude-code/src/run.ts
index d5f222b6c4..9dc4d740ac 100644
--- a/packages/subagent/subagent-claude-code/src/run.ts
+++ b/packages/subagent/subagent-claude-code/src/run.ts
@@ -167,7 +167,7 @@ export async function disposeClaudeCodeChild(
 
 /**
  * Build the fixed official SDK options for one one-shot provider run.
- * @param spec - workspace, environment, process seam, and disposal policy.
+ * @param spec - Workspace, environment, process service, and disposal policy.
  * @param controller - per-run cancellation owner.
  * @param capture - receives the real managed child synchronously from the SDK hook.
  * @returns options that inherit native settings while disabling persistence and user questions.
@@ -194,7 +194,7 @@ export function claudeQueryOptions(
 /**
  * Start one official Claude Agent SDK query and publish its one-shot run.
  * @param request - resolved shared subagent request.
- * @param spec - workspace, environment, process seam, and diagnostic policy.
+ * @param spec - Workspace, environment, process service, and diagnostic policy.
  * @returns the published run after both Query and real CLI handle exist.
  */
 export async function startClaudeCodeRun(
diff --git a/packages/subagent/subagent-codex/src/run.ts b/packages/subagent/subagent-codex/src/run.ts
index c3ebf4ba19..ebce244f3b 100644
--- a/packages/subagent/subagent-codex/src/run.ts
+++ b/packages/subagent/subagent-codex/src/run.ts
@@ -61,7 +61,7 @@ function thrown(value: unknown): Error {
 }
 
 /**
- * Validate and preserve the one-shot task before crossing the process seam.
+ * Validate and preserve the one-shot task before crossing the process boundary.
  * @param prompt - task content accepted from the shared subagent service.
  * @returns the exact non-empty text block sequence.
  */
@@ -110,7 +110,7 @@ export async function disposeCodexChild(
 /**
  * Start the real `codex app-server --stdio` child and publish its one-shot run.
  * @param request - resolved shared subagent request.
- * @param spec - workspace, environment, process seam, and diagnostic policy.
+ * @param spec - Workspace, environment, process service, and diagnostic policy.
  * @returns the published run after initialization and ephemeral thread creation.
  */
 export async function startCodexRun(
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 4fac8ecd2e..1241aa8042 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: a1b5807e5e9e880879e39e0bacaa1a54743f227e
-README.zh.md: 823227af1841730c8fd926295bf7c4ca74497255
+README.md: 762030629c09305c48adebc71244655a5faa6585
+README.zh.md: 535cc25895e04e82b6667e6d2769f2dcbfa49cff
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index a1b5807e5e..762030629c 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -44,11 +44,11 @@ Continuable creation is the optional `SubagentProvider.prepareContinuable?()` me
 
 ## The durable descriptor
 
-The seam owns the versioned `subagent/descriptor` session event vocabulary (`src/descriptor.ts`): `snapshotSubagentDescriptor()` validates and detaches the record before provider work, and `foldSubagentDescriptor()` validates the complete current-version payload before recovering it from a loaded child log. Every local session-backed start appends one descriptor with the provider name and lifecycle `mode`. A `one-shot` descriptor optionally carries the caller-owned durable display `label`; a `continuable` descriptor requires its durable creation label and additionally records resolved child `agentOptions.provider`/`model` and optional `persona`/`toolFilter` for cold resume. These are explicit fields, never the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation. The descriptor omits `subagentDepth` (the persisted header's `delegationDepth` is the monotone floor) and `outputSchema` (an Activation's result contract). The event is log-only: no `surfaceOp`, absent from model history, and retained by the append-only log across compaction. Malformed current-version payloads are corrupt; unsupported versions cannot be classified by this runtime.
+The Service Definition owns the versioned `subagent/descriptor` session event vocabulary (`src/descriptor.ts`): `snapshotSubagentDescriptor()` validates and detaches the record before provider work, and `foldSubagentDescriptor()` validates the complete current-version payload before recovering it from a loaded child log. Every local session-backed start appends one descriptor with the provider name and lifecycle `mode`. A `one-shot` descriptor optionally carries the caller-owned durable display `label`; a `continuable` descriptor requires its durable creation label and additionally records resolved child `agentOptions.provider`/`model` and optional `persona`/`toolFilter` for cold resume. These are explicit fields, never the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation. The descriptor omits `subagentDepth` (the persisted header's `delegationDepth` is the monotone floor) and `outputSchema` (an Activation's result contract). The event is log-only: no `surfaceOp`, absent from model history, and retained by the append-only log across compaction. Malformed current-version payloads are corrupt; unsupported versions cannot be classified by this runtime.
 
 ## Delegation depth
 
-The seam owns the depth vocabulary shared by implementations and consumers: the `AgentOptions.subagentDepth` declaration, `assertSubagentMaxDepth`, and `delegationDepthOf(agent)`. The persisted `SessionHeader.delegationDepth` is authoritative and monotone — runtime options may deepen the count but never lower it, so a resumed child cannot be re-counted as top-level.
+The seam owns the depth vocabulary shared by Service providers and Consumers: the `AgentOptions.subagentDepth` declaration, `assertSubagentMaxDepth`, and `delegationDepthOf(agent)`. The persisted `SessionHeader.delegationDepth` is authoritative and monotone — runtime options may deepen the count but never lower it, so a resumed child cannot be re-counted as top-level.
 
 `inheritsParentContext` is descriptive rather than enforceable. It says only whether the child sees completed parent conversation history (`fork` does; `spawn` and the out-of-process one-shot providers do not), not whether it inherits tools, services, or authority.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 823227af18..535cc25895 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方使用统一的服务 API（`ctx.subagents`）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。
 
-[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享的请求与结果约定、持久描述符以及可继续子级编排。多个具名提供方可以在该约定背后共存。
+[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和结果约定、持久描述符以及可继续子级编排。多个具名提供方可以在该约定背后共存。
 
 ## 服务 API
 
@@ -23,7 +23,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
-| `listDescendants(rootSessionId, signal?)` | 从同一份在线优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消约定均沿用 `listChildren()`。 |
+| `listDescendants(rootSessionId, signal?)` | 从同一份实时优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消约定均沿用 `listChildren()`。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -44,11 +44,11 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 持久化描述符
 
-该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果约定）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
+该 Service Definition 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果约定）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 委派深度
 
-该 seam 拥有实现和消费方共享的深度词汇：`AgentOptions.subagentDepth` 声明、`assertSubagentMaxDepth` 和 `delegationDepthOf(agent)`。持久化的 `SessionHeader.delegationDepth` 具有权威性且单调：运行时选项可以加深计数，但绝不能降低它，因此恢复后的子 agent 不会被重新计为顶层。
+该 seam 拥有 Service provider 和 Consumer 共享的深度词汇：`AgentOptions.subagentDepth` 声明、`assertSubagentMaxDepth` 和 `delegationDepthOf(agent)`。持久化的 `SessionHeader.delegationDepth` 具有权威性且单调：运行时选项可以加深计数，但绝不能降低它，因此恢复后的子 agent 不会被重新计为顶层。
 
 `inheritsParentContext` 只用于描述，不能强制执行。它仅说明子 agent 是否能看到父级已完成的对话历史（`fork` 可以；`spawn` 和各进程外一次性提供方不可以），不表示是否继承工具、服务或权限。
 
@@ -80,7 +80,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 记录发送方，但不授予权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
-当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使消费方替换陈旧身份而不是将其保留——绝不抛错。
+当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
 `registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
 
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 241682c006..eddcf63c3c 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The subagent seam (`ctx.subagents`): a named-provider registry plus a
+ * Service Definition for the subagent capability seam (`ctx.subagents`): a named-provider registry plus a
  * capability-validating asynchronous start surface. Providers establish a
  * child before returning its run, so fulfillment is the single publication and
  * ownership-transfer boundary.
@@ -9,7 +9,7 @@
  * one by name. The shape mirrors the LLM adapter registry
  * (`LlmService.registerAdapter`), not the single-service bash executor.
  *
- * This package is the INTERFACE third of the capability seam. Implementations
+ * This package owns the Service Definition role of the capability seam. Service providers
  * (`@deepseek-ai/dsh-subagent-spawn`, `-fork`, `-acp`) and the model-facing
  * consumer (`@deepseek-ai/dsh-tool-subagent`) are separate packages.
  *
@@ -306,7 +306,7 @@ export class SubagentService extends Service {
 
   /**
    * Enumerate the parent's direct session-backed subagents without loading or
-   * resuming an Agent and without any query seam: the listing merges the live
+   * resuming an Agent and without any query service: the listing merges the live
    * session store with optional session persistence (live-preferred) and
    * serves each child's durable mode/label from the registered `subagent`
    * projection unit down a three-rung ladder — the registry's watermark
diff --git a/packages/subagent/subagent/src/lifecycle.ts b/packages/subagent/subagent/src/lifecycle.ts
index 4e86664340..65c61ae9eb 100644
--- a/packages/subagent/subagent/src/lifecycle.ts
+++ b/packages/subagent/subagent/src/lifecycle.ts
@@ -27,7 +27,7 @@ import type { SubagentResult, SubagentRun, SubagentRunEndInfo, SubagentRunInfo }
  * Lifecycle observer for one Activation's residency epoch, so continuable
  * children emit the same start/end pair as one-shot runs. Package-private: the
  * continuation manager is the only consumer, and its call ordering is an
- * in-package contract rather than a published extension seam.
+ * in-package contract rather than a published extension point.
  */
 export interface ActivationObserver {
   /**
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index bf259212bb..47b6f7f712 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,7 +1,7 @@
 /**
  * Read-only enumeration of durable subagent children and descendant trees
  * straight from the live session store and optional session persistence — no
- * query seam. Candidates come from one live-preferred corpus; each child's
+ * query service. Candidates come from one live-preferred corpus; each child's
  * mode/label is the registered `subagent` projection unit's value, resolved
  * down a three-rung ladder: the registry's watermark cache for a live child,
  * a durable projection-cache row when it serves an own-suffix identity (the
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index c90e0949bd..f2f5798d6c 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
-README.zh.md: 734a2a5a27f0337a3015989556e571f4d18228e0
+README.md: 23c8ba44916379c032991bc92df557157c2e66c4
+README.zh.md: d3400b8b6cc5e839d77858f0684125b54b2daadd
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index 9a8628e2b6..23c8ba4491 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -6,8 +6,8 @@ The shared process substrate for one execution world: executable lookup, fully-s
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | Service Definition: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | Local Service provider: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
 
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 734a2a5a27..d3400b8b6c 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -6,8 +6,8 @@
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | Service Definition：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地 Service provider：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
 
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 22d971b251..f0e9a8a597 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: 087ca24a3207cb8cb1568769a462fbbb010aaa35
-README.zh.md: 4d400906f71b653ce2be95a22751fd9893f447bd
+README.md: ed2b4c3558aa034c8d9fa1049c81d6628c86dff7
+README.zh.md: 832a82dc6a12096e85a1b939f5021767a3c5cb68
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 087ca24a32..ed2b4c3558 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
+Local Service provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling capability seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
 
 ## Behavior (and where it came from)
 
@@ -16,7 +16,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 
 ## Model Experience
 
-Indirectly, through consumer seams (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
+Indirectly, through Consumers (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
 
 #### KV Cache effect
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 4d400906f7..832a82dc6a 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地 Service provider。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方能力 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
 
 ## 行为（以及设计来源）
 
@@ -10,13 +10,13 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在接缝处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
+- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在该能力入口被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归消费方所有。
+通过 Consumer 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归 Consumer 所有。
 
 #### KV Cache 影响
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index e441944225..858bf3fc75 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -1,9 +1,9 @@
 /**
- * Local implementation of the subprocess seam. Each spawn is a detached
+ * Local Service provider for the subprocess capability seam. Each spawn is a detached
  * process tree with the spec's per-stream stdio dispositions; disposal
  * terminates and joins live trees. It has no config: every disposition and
  * limit arrives on the spec, so the deployment-varying choices stay with the
- * calling seam's config (the bash executor's, the LSP host's, …).
+ * caller's config (the bash executor's, the LSP host's, …).
  * @module @deepseek-ai/dsh-subprocess-local
  */
 
@@ -37,9 +37,9 @@ export class LocalSubprocessService extends SubprocessService {
   private live = new Set<SubprocessHandle>()
   /** Live terminal sessions retained through whole-session quiescence. */
   private terminals = new Set<SubprocessTerminalHandle>()
-  /** Test seam: spill and platform knobs forwarded to spawnSubprocess. */
+  /** Test hook: spill and platform knobs forwarded to spawnSubprocess. */
   internals: SpawnInternals = {}
-  /** Test seam for platform process inspection; production resolves lazily on terminal spawn. */
+  /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
   terminalInspector: ProcessInspector | undefined
 
   constructor(ctx: Context) {
@@ -123,8 +123,8 @@ export class LocalSubprocessService extends SubprocessService {
     return handle
   }
 
-  // Local PTY allocation is synchronous, but the provider seam permits remote asynchronous allocation.
-  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
+  // Local PTY allocation is synchronous, but the provider contract permits remote asynchronous allocation.
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
     const file = spec.argv[0]
     if (file === undefined || file.length === 0) {
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 2a763948bb..11d13a405a 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -72,14 +72,14 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
-  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
   async write(data: string): Promise<void> {
     if (this.exited) throw new Error('terminal process has exited')
     this.terminal.write(data)
   }
 
   // Local inspection is synchronous; the seam returns a promise for remote transports.
-  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
     this.descendants()
     const processGroupId = this.inspector.foregroundPgid(this.pid)
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 6bac46ac16..36da8307e3 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -329,7 +329,7 @@ describe('stdin and extra env (set by in-process plugins)', () => {
   })
 
   it('gives fd 0 the exact pre-seam type: /dev/null when no stdin, a pipe when supplied', async () => {
-    // With no bytes, fd 0 remains the pre-seam `ignore` default (/dev/null, a character device).
+    // With no bytes, fd 0 remains the pre-spawn `ignore` default (/dev/null, a character device).
     // Supplied bytes use Node's spawn pipe, which is an AF_UNIX socket rather than a FIFO.
     const none = await finish(spawnSubprocess(spec('test -c /dev/stdin && echo char || echo other')))
     expect(none.stdout.text).toBe('char\n')
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 6da5dc1939..d3b075caaa 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
-README.zh.md: b5d0aac765e433dbaeb9b6e24638ffa6bea6cc51
+README.md: 71ed60c6bdbecbddf45ee4c6a3d31e4a3fbb479b
+README.zh.md: a3789954edf5cedfa96f26774250b2cec877c503
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index c28361f5e7..71ed60c6bd 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -8,7 +8,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
 - Spawn working directories and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
-- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
+- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the caller's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
 - `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches quiescence for every session member the provider can still observe and settles in-flight handle calls; providers document substrate-specific observability limits. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members; readiness, scrollback, and owner policy remain in the PTY consumer.
@@ -19,7 +19,7 @@ See the [subprocess subsystem page](../../../docs/subsystems/subprocess.md) and
 
 ## Model Experience
 
-Indirectly, through consumer seams (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
+Indirectly, through Consumers (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
 
 #### KV Cache effect
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index b5d0aac765..a3789954ed 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -8,7 +8,7 @@
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
 - spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
 - `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；仍处于活动状态的传输若发生故障，会使 `done` 拒绝。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
@@ -19,7 +19,7 @@
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由消费方负责。
+通过 Consumer 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由 Consumer 负责。
 
 #### KV Cache 影响
 
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 6b9904078f..0eaed5620b 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The subprocess seam (`ctx.subprocess`): execution-world executable lookup,
+ * Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup,
  * fully specified managed process trees with raw or
  * collected stdio, and one terminal-process primitive. Command defaulting,
  * shell semantics, deadlines, protocol framing, terminal readiness, and
diff --git a/packages/subprocess/subprocess/src/invariant.ts b/packages/subprocess/subprocess/src/invariant.ts
index 62a720babd..3a6ae526b0 100644
--- a/packages/subprocess/subprocess/src/invariant.ts
+++ b/packages/subprocess/subprocess/src/invariant.ts
@@ -10,7 +10,7 @@ export const name = 'subprocess-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: this stateless seam owns spawn-spec/handle types, while implementations own observations. */
+/** No runtime invariant: this stateless Service Definition owns spawn-spec/handle types, while Service providers own observations. */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 2aa2de0c91..058d11efb3 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the subprocess seam: fully-specified spawn requests with
+ * Vocabulary for the subprocess Service Definition: fully-specified spawn requests with
  * Node-shaped per-stream stdio modes, bounded collected output with spill
  * recovery, raw piped streams, and tree-scoped termination. Command
  * defaulting, shell semantics, protocol framing, and presentation belong to
diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
index 96aedb5e98..e74de2bd0e 100644
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -149,7 +149,7 @@ async function handlePrompt(id: number | string): Promise<void> {
       override: process.env.DSH_SNAPSHOT_OVERRIDE ?? null,
       childFiles: process.env.DSH_SNAPSHOT_CHILD_FILES ?? null,
       spillRoot: process.env.DSH_SNAPSHOT_SPILL_ROOT ?? null,
-      // Scenario-supplied deployment env (the `Scenario.env` layering seam).
+      // Scenario-supplied deployment env (the `Scenario.env` layering hook).
       permissionMode: process.env.DSH_PERMISSION_MODE ?? null,
     })}`)
   }
diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts
index 9e5c30ea60..917e5327d4 100644
--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -191,7 +191,7 @@ export class InvariantService extends Service {
       throw error
     }
     // Cordis attaches setup thenability and async teardown to this callable;
-    // the service seam intentionally exposes only the conventional disposer.
+    // the service contract intentionally exposes only the conventional disposer.
     // oxlint-disable-next-line typescript/no-misused-promises -- the extra runtime shape stays private.
     return registration
   }
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 5c9a575f5c..efdab32824 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -23,7 +23,7 @@ import {
 /**
  * Unit tests for the replay llm/stream plugin. These drive the listener through
  * the REAL LlmService waterfall (not a hand-rolled stub) so they verify the
- * actual seam the snapshot harness depends on, plus the pure
+ * actual LLM capability seam the snapshot harness depends on, plus the pure
  * derive/parse/load helpers that turn a recorded session JSONL into a script.
  */
 
diff --git a/packages/tasks/README.i18n.yaml b/packages/tasks/README.i18n.yaml
index bf9be6a596..13061d820b 100644
--- a/packages/tasks/README.i18n.yaml
+++ b/packages/tasks/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/tasks/README.md
-README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
-README.zh.md: 97d258ffdc88b728ecabd9d20afaf228d620d8a4
+README.md: 32db45b822299f9d18f79a08d3a9264a12661b60
+README.zh.md: a33f390bddab7b51778b153f5121e2d11c6ed380
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index e0b6769cd1..32db45b822 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -12,4 +12,4 @@ This family gives long-running tools one owner-isolated background-task protocol
 
 See the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) decisions.
 
-The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.
+The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry contract](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.
diff --git a/packages/tasks/README.zh.md b/packages/tasks/README.zh.md
index 97d258ffdc..a33f390bdd 100644
--- a/packages/tasks/README.zh.md
+++ b/packages/tasks/README.zh.md
@@ -12,4 +12,4 @@
 
 参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
 
-子系统参考——id 方案、拥有者围栏约定、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
+子系统参考——id 方案、拥有者围栏约定、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表约定](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
diff --git a/packages/tasks/tasks-local/README.i18n.yaml b/packages/tasks/tasks-local/README.i18n.yaml
index 7dbd6dd7e4..d4fa5d09bf 100644
--- a/packages/tasks/tasks-local/README.i18n.yaml
+++ b/packages/tasks/tasks-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/tasks/tasks-local/README.md
-README.md: 23ca6fca61ccb59c855e5d6da6b0a2e23e7cb632
-README.zh.md: 5b04caaf640042049e4ef9e6fa58a30adc6f8f72
+README.md: 663ce0d333c6df0f84900a2570d5487d8d7abe55
+README.zh.md: a5d1acaa50f63dc95b7607657b157272c15a4f11
diff --git a/packages/tasks/tasks-local/README.md b/packages/tasks/tasks-local/README.md
index 23ca6fca61..663ce0d333 100644
--- a/packages/tasks/tasks-local/README.md
+++ b/packages/tasks/tasks-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Process-local implementation of the [`@deepseek-ai/dsh-tasks`](../tasks/README.md) registry seam: `LocalTaskService` keeps every record in memory, issues per-kind `<kind>-N` ids, and hands out fresh snapshots, never live state. It has no config; load it as a plugin and it registers as `ctx.tasks`.
+Process-local implementation of the [`@deepseek-ai/dsh-tasks`](../tasks/README.md) registry contract: `LocalTaskService` keeps every record in memory, issues per-kind `<kind>-N` ids, and hands out fresh snapshots, never live state. It has no config; load it as a plugin and it registers as `ctx.tasks`.
 
 ## Lifecycle
 
diff --git a/packages/tasks/tasks-local/README.zh.md b/packages/tasks/tasks-local/README.zh.md
index 5b04caaf64..a5d1acaa50 100644
--- a/packages/tasks/tasks-local/README.zh.md
+++ b/packages/tasks/tasks-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-tasks`](../tasks/README.md) 注册表 seam 的进程本地实现：`LocalTaskService` 把每条记录保存在内存中，按 kind 签发 `<kind>-N` id，并且只交出全新快照，从不交出实时状态。它没有配置；作为插件加载后即注册为 `ctx.tasks`。
+[`@deepseek-ai/dsh-tasks`](../tasks/README.md) 注册表约定的进程本地实现：`LocalTaskService` 把每条记录保存在内存中，按 kind 签发 `<kind>-N` id，并且只交出全新快照，从不交出实时状态。它没有配置；作为插件加载后即注册为 `ctx.tasks`。
 
 ## 生命周期
 
diff --git a/packages/tasks/tasks-local/src/index.ts b/packages/tasks/tasks-local/src/index.ts
index f108022b17..60a7beb012 100644
--- a/packages/tasks/tasks-local/src/index.ts
+++ b/packages/tasks/tasks-local/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Process-local implementation of the background task registry seam
+ * Process-local provider for the background-task capability seam
  * (`ctx.tasks`). It keeps every record in memory and hands out fresh
  * snapshots, never live state.
  *
@@ -50,7 +50,7 @@ function isTerminal(status: TaskStatus): boolean {
 }
 
 /**
- * The in-memory `tasks` registry. See the seam contract in
+ * The in-memory `tasks` registry. See the Service Definition contract in
  * `@deepseek-ai/dsh-tasks` for the ownership, isolation, and lifecycle
  * semantics this implementation honors.
  */
diff --git a/packages/tasks/tasks-local/src/invariant.ts b/packages/tasks/tasks-local/src/invariant.ts
index 3447287c08..22f2b4fecd 100644
--- a/packages/tasks/tasks-local/src/invariant.ts
+++ b/packages/tasks/tasks-local/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'tasks-local-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the seam companion in `@deepseek-ai/dsh-tasks` already
+ * No runtime invariant: the Service Definition companion in `@deepseek-ai/dsh-tasks` already
  * validates every registry snapshot this implementation publishes.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index e7206370dd..94f8993c2c 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/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/tasks/tasks/README.md
-README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a
-README.zh.md: 5cbcfac8d7153616c39642c11860fc88b8495d1f
+README.md: 04ca125580104d0cb5ab0ce8cdd20d104c4a1668
+README.zh.md: b0b079566246549c7acab7a83fcc3c21c44ef868
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index b5a7380e0c..04ca125580 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The background task registry seam (`ctx.tasks`). The abstract `TaskService` and its vocabulary types give long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup under one contract; the process-local registry lives in [`dsh-tasks-local`](../tasks-local/README.md). Producer plugins extend `TaskKindMap` with their opaque id namespace.
+The background task registry contract (`ctx.tasks`). The abstract `TaskService` and its vocabulary types give long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup under one contract; the process-local registry lives in [`dsh-tasks-local`](../tasks-local/README.md). Producer plugins extend `TaskKindMap` with their opaque id namespace.
 
 ## Service contract
 
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index 5cbcfac8d7..b0b0795662 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-后台任务注册表 seam（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
+后台任务注册表约定（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
 
 ## 服务约定
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index e237aa0681..26b690437c 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The background task registry seam (`ctx.tasks`). It owns the contract for
+ * The background-task Service Definition (`ctx.tasks`). It owns the contract for
  * task ids, session-scoped access, lifecycle state, completion listeners, and
  * owner cleanup while producers retain their execution resources. The
  * process-local registry lives in `@deepseek-ai/dsh-tasks-local`.
diff --git a/packages/tasks/tasks/tests/service.spec.ts b/packages/tasks/tasks/tests/service.spec.ts
index 82fc415f51..9c6e2654e3 100644
--- a/packages/tasks/tasks/tests/service.spec.ts
+++ b/packages/tasks/tasks/tests/service.spec.ts
@@ -5,7 +5,7 @@ import { TaskId, TaskService } from '@deepseek-ai/dsh-tasks'
 import type { TaskDoneListener, TaskRead, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 
 /**
- * Minimal concrete registry: one canned record. The seam owns the contract
+ * Minimal concrete registry: one canned record. The Service Definition owns the contract
  * only (ids, snapshots, authorization-shaped signatures); the registry
  * behavior suite lives with `@deepseek-ai/dsh-tasks-local`.
  */
diff --git a/packages/todo/README.i18n.yaml b/packages/todo/README.i18n.yaml
index b9f4c9fef1..4df1b35bcb 100644
--- a/packages/todo/README.i18n.yaml
+++ b/packages/todo/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/todo/README.md
-README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
-README.zh.md: 9c5d6a9cc3f6078d5609aea668684ea0e4275835
+README.md: 6bbc9fe4f04cc4a82573c643c5c00bbecde069ed
+README.zh.md: ae7de52eeded877e92c94dbc6c6e1addf76aa8b4
diff --git a/packages/todo/README.md b/packages/todo/README.md
index 6c7dccbbfb..6bbc9fe4f0 100644
--- a/packages/todo/README.md
+++ b/packages/todo/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing todo capability. It is a single **product** package because one agent session owns the list; there is no replaceable provider seam.
+The model-facing todo capability. It is a single **product** package because one agent session owns the list; there is no replaceable provider contract.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/todo/README.zh.md b/packages/todo/README.zh.md
index 9c5d6a9cc3..ae7de52eed 100644
--- a/packages/todo/README.zh.md
+++ b/packages/todo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向模型的 todo 能力。它是单一**产品**包，因为一个 agent（智能体）会话拥有该列表；不存在可替换的提供方 seam。
+面向模型的 todo 能力。它是单一**产品**包，因为一个 agent（智能体）会话拥有该列表；不存在可替换的提供方约定。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/todo/tool-todo/README.i18n.yaml b/packages/todo/tool-todo/README.i18n.yaml
index 6aa521df26..750040bb87 100644
--- a/packages/todo/tool-todo/README.i18n.yaml
+++ b/packages/todo/tool-todo/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/todo/tool-todo/README.md
-README.md: 7c993ac6f7f0047d008a09e5ff52cb752f94763c
-README.zh.md: 9cea66147beddab7d62ed7344cbe866495e28022
+README.md: 4848758dd8f2049221901744e5d09cef2dd31591
+README.zh.md: 39cb243d1cf59bf51e524a9a778f67e841ae16ff
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 7c993ac6f7..4848758dd8 100644
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -30,7 +30,7 @@ The canonical result is `{ todos, counts: { pending, inProgress, completed } }`;
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the interface package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the Service Definition package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
 
 ## Export shape
 
diff --git a/packages/todo/tool-todo/README.zh.md b/packages/todo/tool-todo/README.zh.md
index 9cea66147b..39cb243d1c 100644
--- a/packages/todo/tool-todo/README.zh.md
+++ b/packages/todo/tool-todo/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 会话投影
 
-当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
+当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经 Service Definition 包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
 
 ## 导出形状
 
diff --git a/packages/todo/tool-todo/tests/integration.spec.ts b/packages/todo/tool-todo/tests/integration.spec.ts
index f10f2c49e2..568b0f764a 100644
--- a/packages/todo/tool-todo/tests/integration.spec.ts
+++ b/packages/todo/tool-todo/tests/integration.spec.ts
@@ -10,7 +10,7 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
 
 /**
  * Full-loop integration: a scripted mock model drives the REAL todo_write tool
- * through the agent loop, exercising the same seams a live model would — the
+ * through the agent loop, exercising the same execution paths a live model would — the
  * tool/call + tool/result session events AND the todo/write event the tool
  * appends. Only the model is mocked; the tool and the session log are real.
  */
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 553ab75490..1950c255cb 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -84,6 +84,8 @@ export interface ServiceEntry {
   key: string
   /** The service class/interface name, e.g. `LlmService`. */
   type: string
+  /** Whether the service class is abstract (a seam interface). */
+  abstract: boolean
   /** Class-level JSDoc prose, one line per paragraph. */
   doc: string
   /** Public methods (bodies stripped), in source order. */
@@ -256,6 +258,7 @@ export class CordisCatalogProjector {
         entries.push({
           key: service.key,
           type: declaration.name,
+          abstract: declaration.abstract,
           doc,
           methods,
           source,
@@ -744,7 +747,8 @@ function renderEvent(e: EventEntry, onPage: string, linkedTypePages: Readonly<Re
 
 /** Render one harness service entry onto its owning page. */
 function renderService(s: ServiceEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
-  const out = [...anchorFor(`ctx.${s.key} — ${s.type}`), `### \`ctx.${s.key}\` — \`${s.type}\``, '']
+  const kind = s.abstract ? ' (abstract seam)' : ''
+  const out = [...anchorFor(`ctx.${s.key} — ${s.type}${kind}`), `### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
     const declarations = s.methods.flatMap((method, index) => [
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index a6b68a4ee7..bde52505dc 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -259,7 +259,7 @@ export class FixService {
   it('extracts a well-formed service with its methods and class JSDoc', () => {
     const services = collectServices(makeService(WELL_FORMED))
     expect(services).toHaveLength(1)
-    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', doc: 'Fixture service.' })
+    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', abstract: false, doc: 'Fixture service.' })
     expect(services[0]?.methods).toHaveLength(3)
     expect(services[0]?.methods[0]).toEqual({
       signature: 'run(id: string): string',
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index 4a1d973a1a..4628341ad1 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/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/web/tool-web/README.md
-README.md: 646601bb5bd6c27876918b7aca49962ae34bae33
-README.zh.md: 135c75831045225a0ac6d4637ff5c8b4105336c0
+README.md: 643da4e2f083c2efabd39a462290559ddbd291c8
+README.zh.md: 7b52f2b08f393a584258dea1a216d9124ec8760a
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 646601bb5b..643da4e2f0 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -15,7 +15,7 @@ Each tool is registered independently; a product that wants only one disables th
 
 Both tools opt into concurrent scheduling because provider reads return content without mutating parent-agent state.
 
-The normalized seam results are also the canonical tool values: `WebSearchResult` and `WebFetchResult`. Native renderers preserve the answer/source and fetched-body text below; provider search/body caps remain acquisition limits rather than presentation-only truncation.
+The normalized service results are also the canonical tool values: `WebSearchResult` and `WebFetchResult`. Native renderers preserve the answer/source and fetched-body text below; provider search/body caps remain acquisition limits rather than presentation-only truncation.
 
 ## Config
 
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index 135c758310..7b52f2b08f 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -15,7 +15,7 @@
 
 两个工具都选择并发调度，因为提供方读取会返回内容，不会修改父 agent（智能体）的状态。
 
-规范化后的 seam 结果也是标准工具值：`WebSearchResult` 与 `WebFetchResult`。原生渲染器会保留下文所述的答案、来源和抓取正文文本；提供方对搜索结果数量和正文大小的上限仍属于获取限制，而非仅用于呈现的截断。
+规范化后的服务结果也是标准工具值：`WebSearchResult` 与 `WebFetchResult`。原生渲染器会保留下文所述的答案、来源和抓取正文文本；提供方对搜索结果数量和正文大小的上限仍属于获取限制，而非仅用于呈现的截断。
 
 ## 配置
 
diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts
index d642615874..94130df697 100644
--- a/packages/web/tool-web/src/fetch.ts
+++ b/packages/web/tool-web/src/fetch.ts
@@ -2,7 +2,7 @@
  * The model-facing `web_fetch` tool. This module owns its schema, validation, and presentation;
  * `ctx.web` owns retrieval. Timeout is deployment policy, not a model argument: config becomes
  * `ToolDefinition.timeoutMs`, timeout policy enforces it, and this tool forwards the resulting
- * signal. A provider timeout remains a backstop for direct seam callers.
+ * signal. A provider timeout remains a backstop for direct service callers.
  */
 
 import type { Context } from 'cordis'
diff --git a/packages/web/web-fetch-local/README.i18n.yaml b/packages/web/web-fetch-local/README.i18n.yaml
index 5511f72975..b1a9a6a7bf 100644
--- a/packages/web/web-fetch-local/README.i18n.yaml
+++ b/packages/web/web-fetch-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/web/web-fetch-local/README.md
-README.md: 531bfc94a4b2867b1a81d2e0b398ec403186b347
-README.zh.md: 260227679b72ec993dbb9e42a9d2a814bf691e2c
+README.md: 03d6d2a96b04528b33cd063736e8618e66932058
+README.zh.md: 66a8ebe0839c8ba494c3a30b761025fb6b3f75bb
diff --git a/packages/web/web-fetch-local/README.md b/packages/web/web-fetch-local/README.md
index 531bfc94a4..03d6d2a96b 100644
--- a/packages/web/web-fetch-local/README.md
+++ b/packages/web/web-fetch-local/README.md
@@ -12,7 +12,7 @@ The provider owns **safe resource retrieval**: URL validation, HTTP transport, r
 
 The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
 
-A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct seam caller whose provider budget elapsed.
+A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct service caller whose provider budget elapsed.
 
 ## Transport hygiene
 
diff --git a/packages/web/web-fetch-local/README.zh.md b/packages/web/web-fetch-local/README.zh.md
index 260227679b..66a8ebe083 100644
--- a/packages/web/web-fetch-local/README.zh.md
+++ b/packages/web/web-fetch-local/README.zh.md
@@ -12,7 +12,7 @@
 
 提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-timeout-policy`](../../guard/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
 
-已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接 seam 调用方的提供方预算已经耗尽。
+已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接服务调用方的提供方预算已经耗尽。
 
 ## 传输卫生
 
diff --git a/packages/web/web-search-deepseek/src/provider.ts b/packages/web/web-search-deepseek/src/provider.ts
index aef898ed60..4bacd80fec 100644
--- a/packages/web/web-search-deepseek/src/provider.ts
+++ b/packages/web/web-search-deepseek/src/provider.ts
@@ -135,7 +135,7 @@ export function citationSnippets(blocks: readonly ContentBlock[]): Map<string, s
  * Map a DeepSeek Anthropic Messages response to a normalized search result. Walks
  * `web_search_tool_result` blocks for citeable `web_search_result` items, joins each to its
  * citation excerpt as `snippet`, and dedupes by `url` (a `max_uses > 1` request can surface
- * the same URL across searches). The seam owns the final `maxResults` truncation, so
+ * the same URL across searches). The web service owns the final `maxResults` truncation, so
  * `truncated` is always `false` here.
  *
  * @param response - the parsed Messages response body.
diff --git a/packages/web/web-search-exa/README.i18n.yaml b/packages/web/web-search-exa/README.i18n.yaml
index 9adda78384..4afbbcbc5d 100644
--- a/packages/web/web-search-exa/README.i18n.yaml
+++ b/packages/web/web-search-exa/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/web/web-search-exa/README.md
-README.md: c24f952eede90aae6fa23eec976255cb99625c19
-README.zh.md: 58255a564601ae4d57f1916507a76a55cdbabf44
+README.md: 5b1212c1fb210a3aca7836875cc295fad87e7437
+README.zh.md: fc9afbe44dcb5dd55c7007a11b35048217143351
diff --git a/packages/web/web-search-exa/README.md b/packages/web/web-search-exa/README.md
index c24f952eed..5b1212c1fb 100644
--- a/packages/web/web-search-exa/README.md
+++ b/packages/web/web-search-exa/README.md
@@ -38,5 +38,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **A result with no non-blank highlight is dropped entirely** — no portable snippet to map, so fewer sources than the requested count can return.
-- **Only `searchType`/`numResults`/`highlightsPerResult` are exposed** — Exa's other controls (livecrawl, category, domain/date filters, full-text contents) wait on provider-neutral seam fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **Only `searchType`/`numResults`/`highlightsPerResult` are exposed** — Exa's other controls (livecrawl, category, domain/date filters, full-text contents) wait on provider-neutral Service Definition fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
 - **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (e.g. `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
diff --git a/packages/web/web-search-exa/README.zh.md b/packages/web/web-search-exa/README.zh.md
index 58255a5646..fc9afbe44d 100644
--- a/packages/web/web-search-exa/README.zh.md
+++ b/packages/web/web-search-exa/README.zh.md
@@ -38,5 +38,5 @@ Exa 返回扁平 `results[]`，不返回生成答案，因此省略 `content`。
 ## 已知限制与暂缓事项
 
 - **没有非空白高亮摘要的结果会被整个丢弃**：没有可映射的可移植 snippet，因此返回源可能少于请求数量。
-- **只公开 `searchType`／`numResults`／`highlightsPerResult`**：Exa 的其他控制项（livecrawl、category、域名／日期过滤条件、全文内容）等待提供方无关 seam 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
+- **只公开 `searchType`／`numResults`／`highlightsPerResult`**：Exa 的其他控制项（livecrawl、category、域名／日期过滤条件、全文内容）等待提供方无关的 Service Definition 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
 - **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。
diff --git a/packages/web/web-search-exa/src/provider.ts b/packages/web/web-search-exa/src/provider.ts
index 3c62dabfa5..a27449ccd4 100644
--- a/packages/web/web-search-exa/src/provider.ts
+++ b/packages/web/web-search-exa/src/provider.ts
@@ -75,7 +75,7 @@ export function mapExaResponse(response: ExaSearchResponse): WebSearchResult {
   const sources = (response.results ?? [])
     .map(mapExaResult)
     .filter((source): source is WebSearchSource => source !== undefined)
-  // Exa returns no generated answer, so `content` is omitted. The seam owns the
+  // Exa returns no generated answer, so `content` is omitted. The web service owns the
   // final `maxResults` truncation, so this provider reports `truncated: false`.
   return { sources, truncated: false }
 }
diff --git a/packages/web/web-search-perplexity/README.i18n.yaml b/packages/web/web-search-perplexity/README.i18n.yaml
index 6d5f34e989..ca293211ad 100644
--- a/packages/web/web-search-perplexity/README.i18n.yaml
+++ b/packages/web/web-search-perplexity/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/web/web-search-perplexity/README.md
-README.md: 80f6d34d63ddf0cc7d1f0d4f6744d64c91f9a269
-README.zh.md: 485ba992a6fbc7bb6e4bb4a6753b7c34e9f61292
+README.md: 8800609a05e99d3fa8a61e12b2360e633f0fd330
+README.zh.md: fb20d796e9e943a5254b1d22eac3650e45ec95bf
diff --git a/packages/web/web-search-perplexity/README.md b/packages/web/web-search-perplexity/README.md
index 80f6d34d63..8800609a05 100644
--- a/packages/web/web-search-perplexity/README.md
+++ b/packages/web/web-search-perplexity/README.md
@@ -51,7 +51,7 @@ Through [`dsh-tool-web`](../tool-web/README.md), the conversation model sees the
 
 #### Token effect
 
-Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is seam-bounded, and the retained result or error is resent until compaction.
+Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is service-bounded, and the retained result or error is resent until compaction.
 
 #### KV Cache effect
 
@@ -61,5 +61,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **Citation-fallback sources are URL-only** — when Perplexity omits structured `search_results[]`, sources carry no `title`/`snippet`/`publishedAt`, so the tool renders bare hostname labels.
 - **Over-returned sources still cost tokens and latency** — with no result-count control on the wire, `maxResults` is enforced only post-hoc by seam truncation.
-- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral seam fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral Service Definition fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
 - **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (e.g. `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
diff --git a/packages/web/web-search-perplexity/README.zh.md b/packages/web/web-search-perplexity/README.zh.md
index 485ba992a6..fb20d796e9 100644
--- a/packages/web/web-search-perplexity/README.zh.md
+++ b/packages/web/web-search-perplexity/README.zh.md
@@ -51,7 +51,7 @@
 
 #### Token 影响
 
-注册不会直接产生会话 token。答案与源 token 取决于数据，源数量受 seam 限制；保留的结果或错误会重复发送，直到发生压缩（compaction）。
+注册不会直接产生会话 token。答案与源 token 取决于数据，源数量受服务限制；保留的结果或错误会重复发送，直到发生压缩（compaction）。
 
 #### KV Cache 影响
 
@@ -61,5 +61,5 @@
 
 - **引用回退源只含 URL**：Perplexity 省略结构化 `search_results[]` 时，源不含 `title`／`snippet`／`publishedAt`，因此工具只渲染纯主机名标签。
 - **超量返回的来源仍会增加 token 消耗和延迟**：协议没有结果数量控制，`maxResults` 只能由 seam 在事后截断。
-- **只公开 `model`／`maxTokens`／`searchRecency`**：Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关 seam 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
+- **只公开 `model`／`maxTokens`／`searchRecency`**：Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关的 Service Definition 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
 - **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index 5adff6e81c..6f079335f9 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
-README.md: c05965478a049b4145a94075e42bd9602675628f
-README.zh.md: 686157cc87ff456ccc535e3f92fd6524758b35f4
+README.md: 22301a144b2e06ab42e1d503e8f8c554f7886330
+README.zh.md: 027b863cd7835f378de5f5c5d41166938b8cfe1a
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index c05965478a..22301a144b 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -4,15 +4,15 @@ English | [中文](README.zh.md)
 
 The **`WebService`** (`ctx.web`) defines WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
 
-This package is the interface third of the web capability. Unlike bash/fs it spans two capabilities (search and fetch) on one seam, with potentially multiple providers each:
+This package owns the Service Definition role of the web capability. Unlike bash/fs it spans two operations (search and fetch) on one seam, with potentially multiple providers each:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-web` (this) | the interface: the service, provider registries, selection policy, request/result vocabulary, the `WebError` taxonomy |
-| `@deepseek-ai/dsh-web-search-exa` | a search implementation: Exa |
-| `@deepseek-ai/dsh-web-search-perplexity` | a search implementation: Perplexity |
-| `@deepseek-ai/dsh-web-fetch-local` | a fetch implementation: anonymous public HTTP(S) |
-| `@deepseek-ai/dsh-tool-web` | the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
+| `@deepseek-ai/dsh-web` (this) | Service Definition: the service, provider registries, selection policy, request/result vocabulary, the `WebError` taxonomy |
+| `@deepseek-ai/dsh-web-search-exa` | Search provider: Exa |
+| `@deepseek-ai/dsh-web-search-perplexity` | Search provider: Perplexity |
+| `@deepseek-ai/dsh-web-fetch-local` | Fetch provider: anonymous public HTTP(S) |
+| `@deepseek-ai/dsh-tool-web` | Consumer: the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
 
 Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The cost is the parallel `Search`/`Fetch` method pairs; that parallelism is intentional, not a missed extraction.
 
@@ -58,4 +58,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **No observation surface** — no provider-change event and no capability-status query; availability is observed only by executing `search()`/`fetch()` and routing the thrown `WebError` codes, and the no-provider failure is the generic `WEB_PROVIDER_UNAVAILABLE` with no per-provider reason enumeration ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)).
 - **`WebSearchRequest` carries only `query` + `maxResults`** — provider-neutral controls (recency, domain filters, regional hints, search depth) are deferred until Exa and Perplexity can both honor them honestly ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
 - **`WebFetchBody` has no `pdf` arm** — text-extractable PDF support is named deferred work; the closed union makes adding it a compile-enforced change across the three web packages.
-- **Provider-backed page extraction is out of scope of `fetch()`** — a Firecrawl/Tavily-style `web_extract` capability is deferred rather than widening the fetch seam.
+- **Provider-backed page extraction is out of scope of `fetch()`** — a Firecrawl/Tavily-style `web_extract` capability is deferred rather than widening the fetch operation.
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index 686157cc87..027b863cd7 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -2,17 +2,17 @@
 
 [English](README.md) | 中文
 
-**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型契约绑定到某个厂商的 API 形状。
+**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
 
-该包是 web 能力中负责接口的三分之一。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种能力，每种能力都可能有多个提供方：
+本包承担 web 能力的 Service Definition 角色。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种操作，每种操作都可能有多个提供方：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-web`（本包） | 接口：服务、提供方注册表、选择策略、请求／结果词汇、`WebError` 分类体系 |
-| `@deepseek-ai/dsh-web-search-exa` | 搜索实现：Exa |
-| `@deepseek-ai/dsh-web-search-perplexity` | 搜索实现：Perplexity |
-| `@deepseek-ai/dsh-web-fetch-local` | 抓取实现：匿名公共 HTTP(S) |
-| `@deepseek-ai/dsh-tool-web` | 面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
+| `@deepseek-ai/dsh-web`（本包） | Service Definition：服务、提供方注册表、选择策略、请求／结果词汇、`WebError` 分类体系 |
+| `@deepseek-ai/dsh-web-search-exa` | 搜索提供方：Exa |
+| `@deepseek-ai/dsh-web-search-perplexity` | 搜索提供方：Perplexity |
+| `@deepseek-ai/dsh-web-fetch-local` | 抓取提供方：匿名公共 HTTP(S) |
+| `@deepseek-ai/dsh-tool-web` | Consumer：面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
 
 搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。代价是成对的并行 `Search`／`Fetch` 方法；这种并行是有意设计，并非遗漏了可抽取的共性。
 
@@ -58,4 +58,4 @@
 - **没有观测接口**：没有提供方变更事件或能力状态查询；可用性只能通过执行 `search()`／`fetch()` 并按抛出的 `WebError` code 路由来观测，无提供方失败是通用的 `WEB_PROVIDER_UNAVAILABLE`，不会枚举逐提供方原因（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)）。
 - **`WebSearchRequest` 只携带 `query` + `maxResults`**：提供方无关的控制项（新近程度、域名过滤条件、区域提示、搜索深度）暂缓至 Exa 与 Perplexity 都能诚实支持时（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
 - **`WebFetchBody` 没有 `pdf` 分支**：可提取文本的 PDF 支持属于明确的暂缓工作；封闭联合会使新增该分支成为三个 web 包中由编译强制执行的变更。
-- **提供方支持的页面提取不属于 `fetch()` 范围**：Firecrawl/Tavily 风格的 `web_extract` 能力暂缓，而不会扩展抓取 seam。
+- **提供方支持的页面提取不属于 `fetch()` 范围**：Firecrawl/Tavily 风格的 `web_extract` 能力暂缓，而不会扩展抓取操作。
diff --git a/packages/web/web/src/index.ts b/packages/web/web/src/index.ts
index 38e1478c3c..59da2e33e0 100644
--- a/packages/web/web/src/index.ts
+++ b/packages/web/web/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The web access seam (`ctx.web`): registries and provider-selecting execution for search and
+ * Service Definition for the web access capability seam (`ctx.web`): registries and provider-selecting execution for search and
  * fetch. Duplicate ids are rejected. At execution time, a configured provider must exist and
  * be usable; without one, exactly one usable provider is required, so selection never depends
  * on registration order.
diff --git a/packages/workflow/tool-ralph/src/index.ts b/packages/workflow/tool-ralph/src/index.ts
index 199d198262..e6e7edfccf 100644
--- a/packages/workflow/tool-ralph/src/index.ts
+++ b/packages/workflow/tool-ralph/src/index.ts
@@ -243,7 +243,7 @@ function normalizedList(value: unknown): value is string[] {
   return Array.isArray(value) && value.every(normalizedText)
 }
 
-/** Defensively decode the fixed script's report across an implementation seam. */
+/** Defensively decode the fixed script's report across a provider boundary. */
 function readReport(value: unknown, expectedStatus: RalphRoundStatus, maxChars: number): RalphRoundReport {
   if (!isRecord(value)
     || Object.keys(value).sort().join(',') !== 'blocker,evidence,nextSteps,status,summary'
diff --git a/packages/workflow/workflow-workerthread/src/runtime.ts b/packages/workflow/workflow-workerthread/src/runtime.ts
index 38194f4c03..6bc749cbd9 100644
--- a/packages/workflow/workflow-workerthread/src/runtime.ts
+++ b/packages/workflow/workflow-workerthread/src/runtime.ts
@@ -180,7 +180,7 @@ export class WorkflowExecution {
         return { value: null, stopReason: 'cancelled', error: this.cancelledError().message, agentsStarted: this.started }
       }
       // renderThrown is total (thrown values of any realm), so this arm
-      // cannot throw — drive() resolving is the `result` never-rejects seam
+      // cannot throw — drive() resolving is the `result` never-rejects contract
       // contract.
       return { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: this.started }
     }
@@ -283,7 +283,7 @@ export class WorkflowExecution {
       } catch (error: unknown) {
         // The host refuses starts once the run is cancelled — a refusal that
         // races our own cancel state must read as the cancellation it is,
-        // not as a broken seam.
+        // not as a broken contract.
         if (this.isCancelled()) throw this.cancelledError()
         throw new WorkflowError(`agent() could not start a child: ${renderThrown(error)}`, 'AGENT_START', { cause: error })
       }
diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts
index bf86ef5cce..794e5023ef 100644
--- a/packages/workflow/workflow/src/index.ts
+++ b/packages/workflow/workflow/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Workflow capability seam. Implementations execute orchestration scripts;
+ * Service Definition for the workflow capability seam. Service providers execute orchestration scripts;
  * observe-only lifecycle events never expose run control.
  * @module @deepseek-ai/dsh-workflow
  */
@@ -150,7 +150,7 @@ export function isFatalWorkflowError(error: unknown): boolean {
 }
 
 /**
- * Workflow execution seam. Invalid requests throw before publication; a live
+ * Workflow Service Definition contract. Invalid requests throw before publication; a live
  * run is holder-owned, its result never rejects, cancellation and disposal are
  * bounded, and disposal waits for child cleanup within that bound. Lifecycle
  * listener failures are contained, and `workflow/end` fires exactly once as the
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 38cc7950ec..1324d44969 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-role capability seam\" → \"包含三种角色的能力 seam\", not \"三角色 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
diff --git a/vitest.config.ts b/vitest.config.ts
index 4456782519..e07ae43ec3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -24,7 +24,7 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
       // INCLUDED: PowerShell ships with Windows, so they run natively here.
       // Replacing the old 'packages/bash/*' glob with this explicit list also
-      // newly INCLUDES packages/bash/bash (the pure seam package) on Windows.
+      // newly INCLUDES packages/bash/bash (the Service Definition package) on Windows.
       'packages/bash/bash-local',
       'packages/bash/bash-sandbox',
       'packages/bash/tool-bash',

From ceba53edd75570b7f8854852d35563bd97d07eb2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:22:50 +0800
Subject: [PATCH 226/262] fix(fs): observe absence before guarded recreation

---
 ...06-26-file-context-as-event-gate.i18n.yaml |  4 +-
 .../2026-06-26-file-context-as-event-gate.md  | 36 +++++-----
 ...026-06-26-file-context-as-event-gate.zh.md | 36 +++++-----
 ...9-filesystem-absence-observation.i18n.yaml |  6 ++
 ...26-08-09-filesystem-absence-observation.md | 36 ++++++++++
 ...08-09-filesystem-absence-observation.zh.md | 36 ++++++++++
 .../2026-08-03-fs-tool-error-remedy.i18n.yaml |  4 +-
 .../2026-08-03-fs-tool-error-remedy.md        |  2 +-
 .../2026-08-03-fs-tool-error-remedy.zh.md     |  2 +-
 docs/config-catalog.i18n.yaml                 |  4 +-
 docs/config-catalog.md                        |  2 +-
 docs/config-catalog.zh.md                     |  2 +-
 docs/event-producer-consumer.i18n.yaml        |  4 +-
 docs/event-producer-consumer.md               |  6 +-
 docs/event-producer-consumer.zh.md            |  6 +-
 docs/subsystems/filesystem.i18n.yaml          |  4 +-
 docs/subsystems/filesystem.md                 | 50 ++++++++------
 docs/subsystems/filesystem.zh.md              | 50 ++++++++------
 docs/tool-catalog.i18n.yaml                   |  4 +-
 docs/tool-catalog.md                          |  4 +-
 docs/tool-catalog.zh.md                       |  4 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  1 +
 .../snapshots/fs-delete-recreate/input.json   |  7 ++
 .../fs-delete-recreate/session.jsonl          | 62 +++++++++++++++++
 .../fs-delete-recreate/stdout.expected.jsonl  |  4 ++
 .../fs-delete-recreate/workspace/deleted.txt  |  1 +
 packages/e2b/fs-e2b/README.i18n.yaml          |  4 +-
 packages/e2b/fs-e2b/README.md                 |  6 +-
 packages/e2b/fs-e2b/README.zh.md              |  6 +-
 packages/e2b/fs-e2b/src/index.ts              | 34 +++++++++-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 67 +++++++++++++++++++
 packages/fs/fs-local/README.i18n.yaml         |  4 +-
 packages/fs/fs-local/README.md                |  4 +-
 packages/fs/fs-local/README.zh.md             |  4 +-
 packages/fs/fs-local/src/fsio.ts              | 31 +++++++--
 packages/fs/fs-local/src/index.ts             |  9 ++-
 packages/fs/fs-local/tests/filesystem.spec.ts | 10 +++
 packages/fs/fs-local/tests/fsio.spec.ts       | 11 +++
 packages/fs/fs-policy/README.i18n.yaml        |  4 +-
 packages/fs/fs-policy/README.md               | 12 ++--
 packages/fs/fs-policy/README.zh.md            | 12 ++--
 packages/fs/fs-policy/src/index.ts            | 56 +++++++++-------
 packages/fs/fs-policy/tests/policy.spec.ts    | 53 ++++++++++++---
 packages/fs/fs/README.i18n.yaml               |  4 +-
 packages/fs/fs/README.md                      |  6 +-
 packages/fs/fs/README.zh.md                   |  6 +-
 packages/fs/fs/src/index.ts                   | 17 +++--
 packages/fs/fs/src/invariant.ts               | 15 ++++-
 packages/fs/fs/src/types.ts                   |  9 +++
 packages/fs/fs/tests/invariant.spec.ts        | 21 ++++--
 packages/fs/tool-fs/README.i18n.yaml          |  4 +-
 packages/fs/tool-fs/README.md                 |  4 +-
 packages/fs/tool-fs/README.zh.md              |  4 +-
 packages/fs/tool-fs/src/edit.ts               |  4 +-
 packages/fs/tool-fs/src/read.ts               | 11 +--
 packages/fs/tool-fs/src/write.ts              |  4 +-
 packages/fs/tool-fs/tests/integration.spec.ts | 54 +++++++++------
 .../tool-str-replace-editor/README.i18n.yaml  |  4 +-
 packages/fs/tool-str-replace-editor/README.md |  2 +-
 .../fs/tool-str-replace-editor/README.zh.md   |  2 +-
 .../fs/tool-str-replace-editor/src/index.ts   |  9 +--
 .../tests/tools.spec.ts                       | 29 ++++++++
 .../tool-cordis/src/api-catalog.ts            | 10 +--
 packages/skill/skill-local/src/index.ts       |  2 +-
 .../skill-local/tests/skill-local.spec.ts     |  8 +--
 scripts/gen-cordis-catalog.ts                 |  1 +
 scripts/gen-tool-catalog.ts                   |  4 +-
 scripts/type-equiv.manifest.json              |  5 ++
 68 files changed, 694 insertions(+), 249 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt

diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index ffa6f48889..a8acbaf10e 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.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 .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: df1a43e252cff02b287497210664c3d14dcd35a9
-2026-06-26-file-context-as-event-gate.zh.md: 3d784c9e150430c8054f6b08ccc5c66fa85e09b4
+2026-06-26-file-context-as-event-gate.md: 353beb2498a310eee8cc794fa5edc22915fd6ad0
+2026-06-26-file-context-as-event-gate.zh.md: 37d7c1e4d971896a0e6ddeb42650635b8f755ca0
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index df1a43e252..353beb2498 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
@@ -33,14 +33,16 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 The model is additive: bare `ctx.fs` performs atomic, unconstrained text I/O, while `dsh-fs-policy` adds observed state, read-before-edit, and version guards. Removing the policy therefore leaves the tools usable but unconstrained. Shipped agent configs load the policy; the bare mode exists to keep policy optional at the service boundary, not as the normal deployment stance.
 
+The [filesystem absence-observation follow-up](../bug-fix/2026-08-09-filesystem-absence-observation.md) refines the recording payload from a success-only version to explicit present/absent state and requires guarded creation to publish without replacement. The event-gate ownership and no-I/O policy boundary remain unchanged.
+
 `dsh-tool-fs` no longer injects `fileContext`. It injects `fs` and `tools`/`systemPrompt`.
 
 ## The policy is enforced by provider CAS, not by `dsh-fs-policy` stat
 
 `dsh-fs-policy` enforces "you must write/edit based on the version you read" **without ever calling `stat` or comparing versions itself**. It supplies the observed version as the CAS basis and lets the provider's mutation critical section detect staleness:
 
-- "Have you read this file?" is the one thing `dsh-fs-policy` decides locally — a `WeakMap` lookup, no I/O. No record ⇒ `FS_NOT_OBSERVED`.
-- "Is the version you read still current?" is decided **inside `ctx.fs.editText`/`writeText`**, in the same atomic lock that performs the read-match-rename. `dsh-fs-policy` passes `vObserved` as the expectation; the provider raises `FS_STALE_VERSION` if the file has moved on.
+- "What did this owner last observe?" is the one thing `dsh-fs-policy` decides locally — a `WeakMap` lookup, no I/O. No record means unseen; an absent record permits only guarded creation; a present record carries the replacement/edit basis.
+- "Is the version still current, or is the create target still absent?" is decided **inside the provider's atomic mutation boundary**. `dsh-fs-policy` supplies `replaceIfVersion` or `createIfAbsent`; the provider raises `FS_STALE_VERSION` for a moved version and `FS_NOT_OBSERVED` when a guarded create loses to another creator.
 
 This is deliberate. If `dsh-fs-policy` stat-ed and compared versions in its waterfall handler, there would be a TOCTOU gap between that check and the tool's actual write — the file could change in between, so the check would be a false guarantee that the provider's lock has to back up anyway. Putting the version check in the provider's critical section is both race-free and zero extra `stat`. So `dsh-fs-policy` does **no** filesystem I/O; the "must be based on the latest read" guarantee is *realized* by CAS, and `dsh-fs-policy` only chooses the basis (`vObserved`) and gates on prior observation.
 
@@ -68,14 +70,14 @@ The `FsWriteIntent` union itself does not change — the third "unconditional" s
 
 The events live in `@deepseek-ai/dsh-fs`, not in `dsh-fs-policy`. This is forced by the decoupling contract: `dsh-tool-fs` is the emitter, so it must reference the event types, and it must keep compiling even though `dsh-fs-policy` no longer provides a method service. `dsh-fs` is the package both `dsh-tool-fs` and `dsh-fs-policy` already depend on, so it is the only home that lets the emitter and the policy listener share a vocabulary without the emitter depending on the policy plugin.
 
-These events carry existing `dsh-fs` vocabulary (`FsTarget`, `FsVersion`, `FsWriteIntent`) plus an opaque actor — not model-facing concepts (no line windows, numbered lines, or rendered footers leak down).
+These events carry existing `dsh-fs` vocabulary (`FsTarget`, `FsVersion`, `FsObservation`, `FsWriteIntent`) plus an opaque actor — not model-facing concepts (no line windows, numbered lines, or rendered footers leak down).
 
 **The two `fs/*` decision events are single-slot, first-wins waterfalls.** `dsh-fs-policy` returns without calling `next()`, so it owns the slot in the default deployment; a listener registered earlier or with `prepend` would replace that policy. Permission, audit, and sandbox concerns remain on the composable `tools/execute` waterfall.
 
 The actor is typed `object` in `dsh-fs` — a pure opaque carrier the provider contract never reads or narrows. The owner-derivation (`actor.agent?.session`) and the `{ agent?: { session? } }` structural shape stay entirely inside `dsh-fs-policy`, which narrows the `object` actor to that shape in its listeners. `dsh-fs` owns the event names and the fs vocabulary; it does NOT own the policy layer's runtime owner structure.
 
 ```ts
-import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 
 interface Events {
   /**
@@ -95,14 +97,14 @@ interface Events {
    */
   'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
   /**
-   * Record that an actor observed a target at a version, after a successful
-   * read/write/edit. Fire-and-forget (plain emit). Listeners MUST be
+   * Record that an actor observed a target as present at a version or absent.
+   * Fire-and-forget (plain emit). Listeners MUST be
    * synchronous, side-effect-only recorders (`dsh-fs-policy`'s is a WeakMap
    * write); the tool does not guard the emit, so a throwing listener surfaces as
    * the tool's isError result. No listener ⇒ nothing recorded.
    * @mode emit
    */
-  'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+  'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 }
 ```
 
@@ -118,23 +120,23 @@ The tool keeps its model-facing schemas (`read`/`write`/`edit`, byte-for-byte un
 
 `stat` budget is minimized by letting the waterfall produce the expectation lazily — the bare default returns `undefined` (no guard) and never stats:
 
-- **read** — one `stat` (type + size routing + version), then `readText`/`streamText`, then `buildWindow`, then an `emit('fs/observed', target, info.version, exec)`. The post-read confirming `stat` from the old `fileContext.read` is dropped; a writer racing between the routing stat and the read can at worst make a *later* guarded edit spuriously `FS_STALE_VERSION` (fail-closed: the model re-reads, never writes against the wrong version, since `editText` re-checks in its lock).
-- **write** — `expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`, then `ctx.fs.writeText(target, content, expectation)`, then an `emit('fs/observed', target, outcome.version, exec)`. **Zero stat in the tool** with or without `dsh-fs-policy`.
-- **edit** — `expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`, then `ctx.fs.editText(target, edit, expectation)`, then an `emit('fs/observed', target, outcome.version, exec)`. **Zero stat in the tool** in both cases: the bare default is `undefined` (unconditional edit), so the tool never stats to manufacture a basis. If the target is absent, the provider reports `FS_STALE_VERSION` even on the unguarded path.
+- **read** — one `stat`; a metadata miss emits `{ kind: 'absent' }` before returning `FS_NOT_FOUND`, while a file routes through `readText`/`streamText`, `buildWindow`, then emits `{ kind: 'present', version: info.version }`. The post-read confirming `stat` from the old `fileContext.read` stays dropped; a writer racing between the routing stat and the read can at worst make a later guarded edit spuriously stale.
+- **write** — `expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`, then `ctx.fs.writeText(target, content, expectation)`, then emit the present outcome version. **Zero stat in the tool** with or without `dsh-fs-policy`.
+- **edit** — `expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`, then `ctx.fs.editText(target, edit, expectation)`, then emit the present outcome version. **Zero stat in the tool** in both cases: the bare default is `undefined` (unconditional edit), so the tool never stats to manufacture a basis. If the target is absent on the bare path, the provider reports `FS_STALE_VERSION`; the policy returns `FS_NOT_FOUND` directly when it already holds an absent observation.
 
 The tool passes `exec` (the tool-execution context) as the `actor` argument on every dispatch, so `dsh-fs-policy` can derive its observed-state owner. The tool does not know whether the policy plugin is present: it always provides the bare default behavior in the `next` thunk, and `dsh-fs-policy` short-circuits the thunk before it runs in the default deployment.
 
-**`fs/observed` fires after a successful operation.** Its listeners must be synchronous, non-throwing recorders; the tool does not guard the plain emit, so a throwing listener would report failure after a mutation already succeeded. Async or fallible observation needs a separate event contract.
+**`fs/observed` fires after a successful operation and after a metadata probe confirms absence.** Its listeners must be synchronous, non-throwing recorders; the tool does not guard the plain emit, so a throwing listener can replace the pending read error or report failure after a mutation already succeeded. Async or fallible observation needs a separate event contract.
 
 ## Policy plugin contract (`dsh-fs-policy`)
 
-`dsh-fs-policy` is a plugin, not a service. It does not register `ctx.fileContext`, has no public method surface, and exposes no `read`/`write`/`edit`/`resolve` methods. It attaches three listeners via `ctx.on()` registrations (each returning a disposer for HMR). It keeps the observed-state `WeakMap<owner, Map<targetKey, { version }>>` and the structural owner derivation (narrowing the event's opaque `object` actor to its own `{ agent?: { session? } }` shape), but does not inject `fs` — every handler operates only on its own `WeakMap`, never on `ctx.fs`.
+`dsh-fs-policy` is a plugin, not a service. It does not register `ctx.fileContext`, has no public method surface, and exposes no `read`/`write`/`edit`/`resolve` methods. It attaches three listeners via `ctx.on()` registrations (each returning a disposer for HMR). It keeps the observed-state `WeakMap<owner, Map<targetKey, FsObservation>>` and the structural owner derivation (narrowing the event's opaque `object` actor to its own `{ agent?: { session? } }` shape), but does not inject `fs` — every handler operates only on its own `WeakMap`, never on `ctx.fs`.
 
-- `fs/write-intent` listener: `prior = getObserved(owner, key)`; return `prior ? { kind: 'replaceIfVersion', version: prior.version } : { kind: 'createIfAbsent' }`. It does NOT call `next()`: it fully owns the single decision slot.
-- `fs/edit-intent` listener: `prior = getObserved(owner, key)`; if no `owner` or no `prior`, throw `FS_NOT_OBSERVED`; else return `{ version: prior.version }`. Also does not call `next()`.
-- `fs/observed` listener: `record(owner, key, version)`.
+- `fs/write-intent` listener: unseen/absent ⇒ `createIfAbsent`; present ⇒ `replaceIfVersion`. It does NOT call `next()`: it fully owns the single decision slot.
+- `fs/edit-intent` listener: unseen ⇒ `FS_NOT_OBSERVED`; absent ⇒ `FS_NOT_FOUND`; present ⇒ its version guard. It does NOT call `next()`.
+- `fs/observed` listener: record the present/absent discriminated value.
 
-An observed-state entry is the **prior-observation record**: a successful `read`, `write`, OR `edit` all emit `fs/observed` and record `{ version }`, so the entry's presence means "this owner has observed this target at this version", not narrowly "has read it". This is what lets a create-then-edit or edit-then-edit sequence work without an intervening re-read: the mutation refreshes the recorded version to its own result, so the next edit's basis is the version it just produced. `FS_NOT_OBSERVED` rejects only an edit with NO prior observation of any kind. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
+An observed-state entry is the **prior-observation record**, but its discriminant matters. Successful read/write/edit records present at a version, allowing create-then-edit or edit-then-edit without an intervening read. A read/view that confirms absence replaces any old positive version with absent, allowing only a guarded create; a later successful create replaces it with the new present version. Missing entry alone means unseen and produces `FS_NOT_OBSERVED` for edit. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
 
 `dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event gate. That is what removes the method coupling from `dsh-tool-fs`.
 
@@ -154,7 +156,7 @@ This amends — does not reverse — [the split-fs-seam Agent Note](../simplific
 
 ## Verification
 
-Tests pin both paths: without `dsh-fs-policy`, the root tool plugin boots against `dsh-fs-local`, and read, create, overwrite, and unread edit succeed; with the policy, unread edit returns `FS_NOT_OBSERVED` and unread overwrite is gated by `createIfAbsent`. A later intent listener is not reached after the policy decides. Stale edits fail through provider CAS while the policy performs no `stat`; the tool budgets remain one `stat` for read and zero for write or edit on either path. Model-facing schemas remain byte-for-byte unchanged, so snapshots do not change.
+Tests pin both paths: without `dsh-fs-policy`, the root tool plugin boots against `dsh-fs-local`, and read, create, overwrite, and unread edit succeed; with the policy, unread edit returns `FS_NOT_OBSERVED` and unread overwrite is gated by `createIfAbsent`. A later intent listener is not reached after the policy decides. Stale edits fail through provider CAS while the policy performs no `stat`; the tool budgets remain one `stat` for read and zero for write or edit on either path. The deletion recovery path is also assembled: stale mutation, missing reread, guarded recreation. Model-facing schemas remain byte-for-byte unchanged, while the recovered result transcript changes.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index 3d784c9e15..37d7c1e4d9 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -33,14 +33,16 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 该模型是叠加式的：裸 `ctx.fs` 执行原子化、无约束的文本 I/O，而 `dsh-fs-policy` 叠加观测状态、先读后编辑和版本守卫。因此移除策略层后工具仍可用，只是不受约束。正式发布的 agent 配置会加载策略；裸模式的存在是为了让策略在服务边界保持可选，而非作为正常部署姿态。
 
+[文件系统缺失观测后续决策](../bug-fix/2026-08-09-filesystem-absence-observation.md)把记录载荷从仅表示成功的版本细化为显式的存在/缺失状态，并要求带防护的创建以不替换方式发布。事件门禁归属与无 I/O 策略边界保持不变。
+
 `dsh-tool-fs` 不再注入 `fileContext`。它注入 `fs` 和 `tools`/`systemPrompt`。
 
 ## 策略由提供方 CAS 强制执行，而非 `dsh-fs-policy` 的 stat
 
 `dsh-fs-policy` 强制执行「你必须基于你读到的版本来写入/编辑」，**自身从不调用 `stat` 或比较版本**。它将观测到的版本作为 CAS 基准提供，让提供方的 mutation 临界区检测陈旧性：
 
-- 「你读过这个文件吗？」是 `dsh-fs-policy` 在本地决定的唯一事项——一次 `WeakMap` 查找，无 I/O。无记录 ⇒ `FS_NOT_OBSERVED`。
-- 「你读到的版本是否仍为最新？」由 **`ctx.fs.editText`/`writeText` 内部**决定，在执行 read-match-rename 的同一个原子锁中完成。`dsh-fs-policy` 将 `vObserved` 作为期望值传入；如果文件已变更，提供方抛出 `FS_STALE_VERSION`。
+- 「该所有者最近观测到了什么？」是 `dsh-fs-policy` 在本地决定的唯一事项——一次 `WeakMap` 查找，无 I/O。无记录表示未见；缺失记录只允许带防护的创建；存在记录携带替换/编辑基准。
+- 「版本是否仍然有效，或者创建目标是否仍然缺失？」由**提供方的原子变更边界内部**决定。`dsh-fs-policy` 提供 `replaceIfVersion` 或 `createIfAbsent`；对于已经变化的版本，提供方抛出 `FS_STALE_VERSION`；带防护的创建若败给另一个创建者，则抛出 `FS_NOT_OBSERVED`。
 
 这是有意为之的。如果 `dsh-fs-policy` 在其 waterfall（瀑布式事件）处理器中 stat 并比较版本，该检查与工具实际写入之间会存在 TOCTOU 间隙——文件可能在此期间变化，因此该检查只是一个虚假保证，提供方的锁无论如何都要兜底。将版本检查放在提供方的临界区中既无竞态又无额外 `stat`。所以 `dsh-fs-policy` **不做**任何文件系统 I/O；「必须基于最近一次读取」的保证由 CAS *实现*，`dsh-fs-policy` 只负责选择基准（`vObserved`）并对先前观测进行门控。
 
@@ -68,14 +70,14 @@ editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion
 
 事件定义在 `@deepseek-ai/dsh-fs` 中，而非 `dsh-fs-policy` 中。这是解耦约定所迫：`dsh-tool-fs` 是发射方，因此它必须引用事件类型，且即使 `dsh-fs-policy` 不再提供方法服务，它也必须能编译通过。`dsh-fs` 是 `dsh-tool-fs` 和 `dsh-fs-policy` 都已依赖的包，因此它是唯一能让发射方和策略监听方共享词汇而不让发射方依赖策略插件的归属地。
 
-这些事件携带既有的 `dsh-fs` 词汇（`FsTarget`、`FsVersion`、`FsWriteIntent`）加一个不透明的 actor——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
+这些事件携带既有的 `dsh-fs` 词汇（`FsTarget`、`FsVersion`、`FsObservation`、`FsWriteIntent`）加一个不透明的 actor——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
 
 **两个 `fs/*` 决策事件是单槽、先到先得的 waterfall。** `dsh-fs-policy` 不调用 `next()` 直接返回，因此在默认部署中它占据该槽位；更早注册或使用 `prepend` 的监听器会替代该策略。权限、审计和沙箱关注点仍留在可组合的 `tools/execute` waterfall 上。
 
 actor 在 `dsh-fs` 中类型为 `object`——一个纯粹的不透明载体，提供方约定从不读取或收窄它。owner 的推导（`actor.agent?.session`）和 `{ agent?: { session? } }` 结构形状完全留在 `dsh-fs-policy` 内部，由其在监听器中将 `object` actor 收窄为该形状。`dsh-fs` 拥有事件名和 fs 词汇；它不拥有策略层的运行时 owner 结构。
 
 ```ts
-import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 
 interface Events {
   /**
@@ -95,14 +97,14 @@ interface Events {
    */
   'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
   /**
-   * Record that an actor observed a target at a version, after a successful
-   * read/write/edit. Fire-and-forget (plain emit). Listeners MUST be
+   * Record that an actor observed a target as present at a version or absent.
+   * Fire-and-forget (plain emit). Listeners MUST be
    * synchronous, side-effect-only recorders (`dsh-fs-policy`'s is a WeakMap
    * write); the tool does not guard the emit, so a throwing listener surfaces as
    * the tool's isError result. No listener ⇒ nothing recorded.
    * @mode emit
    */
-  'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+  'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 }
 ```
 
@@ -118,23 +120,23 @@ interface Events {
 
 通过让 waterfall 惰性产出期望值来最小化 `stat` 预算——裸默认返回 `undefined`（无守卫），从不 stat：
 
-- **read**——一次 `stat`（类型 + 大小路由 + 版本），然后 `readText`/`streamText`，然后 `buildWindow`，然后 `emit('fs/observed', target, info.version, exec)`。旧 `fileContext.read` 中读后确认的 `stat` 被移除；在路由 stat 和读取之间竞争的写入者最多只能使*后续*有守卫的编辑误报 `FS_STALE_VERSION`（为安全起见拒绝写入：模型会重新读取；由于 `editText` 会在其锁内复查，模型绝不会基于错误版本写入）。
-- **write**——`expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`，然后 `ctx.fs.writeText(target, content, expectation)`，然后 `emit('fs/observed', target, outcome.version, exec)`。无论是否有 `dsh-fs-policy`，**工具内零 stat**。
-- **edit**——`expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`，然后 `ctx.fs.editText(target, edit, expectation)`，然后 `emit('fs/observed', target, outcome.version, exec)`。两种情况下**工具内零 stat**：裸默认为 `undefined`（无条件编辑），因此工具从不 stat 来制造基准。如果目标不存在，提供方即使在无守卫路径上也报告 `FS_STALE_VERSION`。
+- **read**——一次 `stat`；元数据未命中时，在返回 `FS_NOT_FOUND` 前 emit `{ kind: 'absent' }`；目标为文件时，则依次执行 `readText`/`streamText`、`buildWindow`，再 emit `{ kind: 'present', version: info.version }`。旧 `fileContext.read` 中读后确认的 `stat` 仍保持移除；在路由 stat 和读取之间竞争的写入者最多只能使后续带防护的编辑误报陈旧。
+- **write**——`expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`，然后 `ctx.fs.writeText(target, content, expectation)`，再 emit 表示存在的结果版本。无论是否有 `dsh-fs-policy`，**工具内零 stat**。
+- **edit**——`expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`，然后 `ctx.fs.editText(target, edit, expectation)`，再 emit 表示存在的结果版本。两种情况下**工具内零 stat**：裸默认为 `undefined`（无条件编辑），因此工具从不 stat 来制造基准。如果裸路径上的目标不存在，提供方报告 `FS_STALE_VERSION`；策略已持有缺失观测时，则直接返回 `FS_NOT_FOUND`。
 
 工具在每次分发时将 `exec`（工具执行上下文）作为 `actor` 参数传入，以便 `dsh-fs-policy` 推导其观测状态的 owner。工具不知道策略插件是否存在：它始终在 `next` thunk 中提供裸默认行为，而 `dsh-fs-policy` 在默认部署中会在 thunk 运行前短路它。
 
-**`fs/observed` 在操作成功后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器会在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件约定。
+**`fs/observed` 在操作成功后，以及元数据探测确认缺失后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器可能取代待返回的读取错误，或在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件约定。
 
 ## 策略插件约定（`dsh-fs-policy`）
 
-`dsh-fs-policy` 是插件，不是服务。它不注册 `ctx.fileContext`，没有公开方法面，不暴露 `read`/`write`/`edit`/`resolve` 方法。它通过 `ctx.on()` 注册三个监听器（每个返回一个 disposer 用于 HMR）。它维护观测状态 `WeakMap<owner, Map<targetKey, { version }>>`，以及结构化的 owner 推导（将事件中不透明的 `object` actor 收窄为自己的 `{ agent?: { session? } }` 形状），但不注入 `fs`——每个处理器只操作自己的 `WeakMap`，从不操作 `ctx.fs`。
+`dsh-fs-policy` 是插件，不是服务。它不注册 `ctx.fileContext`，没有公开方法面，不暴露 `read`/`write`/`edit`/`resolve` 方法。它通过 `ctx.on()` 注册三个监听器（每个返回一个 disposer 用于 HMR）。它维护观测状态 `WeakMap<owner, Map<targetKey, FsObservation>>`，以及结构化的 owner 推导（将事件中不透明的 `object` actor 收窄为自己的 `{ agent?: { session? } }` 形状），但不注入 `fs`——每个处理器只操作自己的 `WeakMap`，从不操作 `ctx.fs`。
 
-- `fs/write-intent` 监听器：`prior = getObserved(owner, key)`；返回 `prior ? { kind: 'replaceIfVersion', version: prior.version } : { kind: 'createIfAbsent' }`。它不调用 `next()`：完全占据单一决策槽位。
-- `fs/edit-intent` 监听器：`prior = getObserved(owner, key)`；如果无 `owner` 或无 `prior`，抛出 `FS_NOT_OBSERVED`；否则返回 `{ version: prior.version }`。同样不调用 `next()`。
-- `fs/observed` 监听器：`record(owner, key, version)`。
+- `fs/write-intent` 监听器：未见/缺失 ⇒ `createIfAbsent`；存在 ⇒ `replaceIfVersion`。它不调用 `next()`：完全占据单一决策槽位。
+- `fs/edit-intent` 监听器：未见 ⇒ `FS_NOT_OBSERVED`；缺失 ⇒ `FS_NOT_FOUND`；存在 ⇒ 返回其版本守卫。同样不调用 `next()`。
+- `fs/observed` 监听器：记录存在/缺失的可辨识值。
 
-一条观测状态条目是**先前观测记录**：成功的 `read`、`write` 或 `edit` 都会 emit `fs/observed` 并记录 `{ version }`，因此条目的存在意味着「此 owner 在此版本观测过此目标」，而非狭义的「已读取过」。这使得 create-then-edit 或 edit-then-edit 序列无需中间重新读取即可工作：mutation 将记录的版本刷新为自身的结果，因此下一次编辑的基准就是它刚产出的版本。`FS_NOT_OBSERVED` 只拒绝完全没有任何先前观测的编辑。owner 从 `{ agent?: { session? } }` 结构化推导；dispose 时丢弃所有状态（HMR 安全）。
+一条观测状态条目是**先前观测记录**，但其可辨识字段会影响决策。成功的 read/write/edit 会记录存在状态及版本，使 create-then-edit 或 edit-then-edit 序列无需中间重新读取即可工作。确认缺失的 read/view 会用缺失状态取代旧的正向版本，因此只允许带防护的创建；随后成功的创建会再用新的存在版本取代缺失状态。只有条目不存在才表示未见，并使 edit 返回 `FS_NOT_OBSERVED`。owner 从 `{ agent?: { session? } }` 结构化推导；dispose 时丢弃所有状态（HMR 安全）。
 
 `dsh-fs-policy` 现在是一个纯策略/记录插件，没有服务面——它只通过事件门控影响外界。这正是移除 `dsh-tool-fs` 方法耦合的关键。
 
@@ -154,7 +156,7 @@ interface Events {
 
 ## 验证
 
-测试固定了两条路径：无 `dsh-fs-policy` 时，根工具插件对 `dsh-fs-local` 启动，read、create、overwrite 和未读 edit 均成功；有策略时，未读 edit 返回 `FS_NOT_OBSERVED`，未读 overwrite 被 `createIfAbsent` 门控。策略决定后，后注册的 intent 监听器不会被触达。陈旧编辑通过提供方 CAS 失败，而策略不执行 `stat`；工具预算在两条路径上保持 read 一次 `stat`，write 或 edit 均为零次。面向模型的 schema 逐字节不变，因此快照不变。
+测试固定了两条路径：无 `dsh-fs-policy` 时，根工具插件对 `dsh-fs-local` 启动，read、create、overwrite 和未读 edit 均成功；有策略时，未读 edit 返回 `FS_NOT_OBSERVED`，未读 overwrite 被 `createIfAbsent` 门控。策略决定后，后注册的 intent 监听器不会被触达。陈旧编辑通过提供方 CAS 失败，而策略不执行 `stat`；工具预算在两条路径上保持 read 一次 `stat`，write 或 edit 均为零次。测试也组装了删除恢复路径：陈旧变更、重新读取时确认缺失、带防护的重新创建。面向模型的 schema 逐字节不变，但恢复后的结果 transcript（文本记录）发生变化。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
new file mode 100644
index 0000000000..39e50ffe6b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.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 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
+2026-08-09-filesystem-absence-observation.md: e0c5c8b1845550ac6380ea4b2782cde13cba3ce9
+2026-08-09-filesystem-absence-observation.zh.md: 808698a7cb7a3575ef500dced7a646691d65c424
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
new file mode 100644
index 0000000000..e0c5c8b184
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
@@ -0,0 +1,36 @@
+# Agent Note: Filesystem absence is an observation and guarded creation never replaces
+
+Status: implemented
+
+English | [中文](2026-08-09-filesystem-absence-observation.zh.md)
+
+## Problem
+
+The event-gated filesystem policy originally records only successful reads and mutations as a target version. If a session reads a file and an external command deletes it, the first guarded mutation correctly fails stale, but the prescribed reread returns `FS_NOT_FOUND` before emitting `fs/observed`. The old positive version therefore remains forever: write keeps choosing `replaceIfVersion`, the provider keeps rejecting the missing target, and the model-facing “re-read the file, then retry” instruction becomes an unrecoverable loop.
+
+Treating a failed read as permission to create also exposes a second boundary. Both local and E2B providers probe before staging, then historically publish with rename; another process can create the target between those steps and be overwritten even though the caller supplied `createIfAbsent`. An in-process target lock does not protect that cross-process publication race.
+
+## Decision
+
+`dsh-fs` owns an explicit observation union: `{ kind: 'present', version: FsVersion } | { kind: 'absent' }`. The `fs/observed` event carries that union. Successful reads and mutations emit present; a `read` or `str_replace_editor view` metadata miss emits absent synchronously before returning `FS_NOT_FOUND`. Other read failures do not manufacture absence.
+
+`dsh-fs-policy` stores three logical states per owner and target without injecting or calling `ctx.fs`: missing map entry is unseen, `absent` is confirmed absence, and `present(version)` is a replacement/edit basis. Write maps unseen and absent to the existing `createIfAbsent` intent and present to `replaceIfVersion`. Edit maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. A successful create or mutation replaces absence with its produced present version.
+
+Every provider must enforce `createIfAbsent` at the publication point, not only at its initial probe. `dsh-fs-local` stages and fsyncs in a private sibling directory, then hard-links the staged file to the destination; an existing destination makes the no-replace link fail and preserves the competitor. `dsh-fs-e2b` uses remote `ln` with an explicit created/existing result and derives the committed target version from metadata obtained before the non-cancellable commit. Replacements and bare unconditional writes retain their existing publication paths.
+
+This decision does not claim cross-process linearizability for `replaceIfVersion`: the provider version check and replacement remain protected only against writers represented by the provider's own lock and detectable metadata. The narrower guarantee is exact and sufficient for absence recovery: guarded creation never clobbers a target that appears before publication.
+
+## Alternatives considered
+
+- **Delete the cached version when a read returns not found.** Rejected because it conflates unseen with confirmed absence, cannot give edit the correct `FS_NOT_FOUND` result, and erases the state transition the event is meant to communicate.
+- **Have `dsh-fs-policy` call `stat` before choosing an intent.** Rejected because it makes the event-only policy depend on a provider, adds I/O to every decision, and still leaves a TOCTOU gap before publication.
+- **Let `replaceIfVersion` create when its target disappeared.** Rejected because a positive observation is evidence for replacement, not creation; silently changing that provider intent would bypass the required missing reread and weaken stale protection.
+- **Keep the deleted-target dead end fail-closed.** Rejected because the model-facing recovery instruction is then false and a normal external cleanup cannot be recovered within the session.
+
+## Consequences
+
+The first mutation after an unobserved external deletion still fails `FS_STALE_VERSION`; the user or model must follow the existing reread remedy. That missing reread returns `FS_NOT_FOUND` while changing policy state, after which edit remains forbidden and write may recreate the path. If another writer wins the create race, the retry returns `FS_NOT_OBSERVED` and leaves the winner intact.
+
+The observation payload is a package-owned event contract change, so every producer, listener, invariant, generated Cordis catalog, subsystem document, and both filesystem tool families move together. The policy keeps its one-stat read and zero-stat write/edit budget, owner isolation, disposal behavior, and optional deployment boundary from the [event-gate decision](../architecture/2026-06-26-file-context-as-event-gate.md).
+
+The assembled filesystem snapshot pins the model-visible recovery chain, while provider tests inject a creator after staging to prove no-clobber publication. The [guarded-mutation remedy decision](../feature/2026-08-03-fs-tool-error-remedy.md) remains the owner of model-facing recovery wording; this note makes its deletion path actionable.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
new file mode 100644
index 0000000000..808698a7cb
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 文件系统中的缺失是一种观测，带防护的创建绝不执行替换
+
+Status: implemented
+
+[English](2026-08-09-filesystem-absence-observation.md) | 中文
+
+## 问题
+
+事件门控的文件系统策略最初只把成功读取和变更记录成目标版本。如果某个会话读取文件后，外部命令将其删除，第一次带防护的变更会正确地因陈旧而失败，但按指示执行的重新读取会在发出 `fs/observed` 前返回 `FS_NOT_FOUND`。因此，旧的存在版本会一直保留：写入仍不断选择 `replaceIfVersion`，提供方仍不断拒绝缺失目标，而面向模型的「re-read the file, then retry」指令则形成无法恢复的循环。
+
+把一次失败的读取视作创建授权，还会暴露第二个边界。本地与 E2B 提供方都会先探测再暂存，此前随后通过 rename 发布；另一进程可能在两步之间创建目标，即使调用方提供了 `createIfAbsent`，该目标仍会被覆盖。进程内目标锁无法防范这种跨进程发布竞态。
+
+## 决策
+
+`dsh-fs` 拥有一个显式观测联合类型：`{ kind: 'present', version: FsVersion } | { kind: 'absent' }`。`fs/observed` 事件携带该联合类型。成功的读取与变更发出存在观测；`read` 或 `str_replace_editor view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前同步发出缺失观测。其他读取失败不会产生缺失观测。
+
+`dsh-fs-policy` 按所有者与目标存储三种逻辑状态，既不注入也不调用 `ctx.fs`：映射中无条目即未见，`absent` 表示确认缺失，`present(version)` 是替换/编辑基准。写入把未见和缺失映射到现有 `createIfAbsent` 意图，把存在映射到 `replaceIfVersion`。编辑把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。成功创建或变更后，系统会用其产生的存在版本取代缺失状态。
+
+每个提供方都必须在发布点执行 `createIfAbsent`，不能只在初始探测时执行。`dsh-fs-local` 在私有同级目录中暂存并执行 fsync，再通过硬链接把暂存文件发布到目标位置；目标已存在时，不替换链接会失败，并保留竞争创建者写入的文件。`dsh-fs-e2b` 使用远程 `ln` 返回明确的已创建/已存在结果，并根据不可取消提交前取得的元数据推导已提交目标的版本。替换操作和裸无条件写入仍沿用现有发布路径。
+
+本决策不宣称 `replaceIfVersion` 具有跨进程线性一致性：提供方的版本检查与替换仍只能防范被其自身锁纳入协调的写入方，以及能通过元数据检测到的写入方。更窄的保证边界准确且足以支持缺失恢复：带防护的创建绝不会覆盖在发布前出现的目标。
+
+## 曾考虑的替代方案
+
+- **读取返回未找到时删除缓存版本。** 不予采用，因为这会混淆未见与确认缺失，无法让 edit 返回正确的 `FS_NOT_FOUND` 结果，还会抹去该事件本应传达的状态转换。
+- **让 `dsh-fs-policy` 在选择意图前调用 `stat`。** 不予采用，因为这会让只依赖事件的策略转而依赖提供方，为每次决策增加 I/O，并且在发布前仍留下 TOCTOU 间隙。
+- **允许 `replaceIfVersion` 在目标消失后执行创建。** 不予采用，因为存在观测是执行替换而非创建的依据；静默改变该提供方意图会绕过必须针对缺失目标执行的重新读取，并削弱陈旧保护。
+- **让删除目标后的死路继续保持 fail-closed。** 不予采用，因为这样会使面向模型的恢复指令失实，而且正常的外部清理操作无法在会话内恢复。
+
+## 影响
+
+尚未观测到外部删除时，第一次变更仍以 `FS_STALE_VERSION` 失败；用户或模型必须遵循现有的重新读取恢复指令。该次针对缺失目标的重新读取会返回 `FS_NOT_FOUND` 并同时改变策略状态，此后 edit 仍被禁止，而 write 可以重新创建该路径。如果另一个写入方赢得创建竞态，本次重试会返回 `FS_NOT_OBSERVED`，并保留获胜方写入的文件。
+
+观测载荷是由包拥有的事件约定变更，因此所有生产方、监听器、不变式、生成的 Cordis 目录、子系统文档以及两套文件系统工具都必须同步更新。策略保留[事件门禁决策](../architecture/2026-06-26-file-context-as-event-gate.md)确立的 read 一次 `stat`、write/edit 零次 `stat` 预算、所有者隔离、dispose 行为和可选部署边界。
+
+组装后的文件系统快照固定面向模型的恢复链；提供方测试则在暂存后注入一个创建者，以证明发布不会覆盖竞争目标。[带防护变更恢复指令决策](../feature/2026-08-03-fs-tool-error-remedy.md)仍然拥有面向模型的恢复措辞；本 Agent Note 使其中的删除路径能够生效。
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index d9d9142437..484b6bfe36 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.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 .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
-2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
-2026-08-03-fs-tool-error-remedy.zh.md: 6bb0d0b6ffcda282db67dd1a54f0074b3be5c6e1
+2026-08-03-fs-tool-error-remedy.md: c4f0bb86100a4856c536edf22e520662e19ea4f6
+2026-08-03-fs-tool-error-remedy.zh.md: 88309bd630732794dfb2401b60ad799a3d63146b
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
index f227c31365..c4f0bb8610 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
@@ -29,4 +29,4 @@ In `edit.ts` the `fs/edit-intent` waterfall now sits inside the same `try` as th
 
 Model-visible text for the two codes changes; the `fs-policy-reject` keyless snapshot is re-recorded, and the READMEs of `dsh-tool-fs` and `dsh-fs-policy` pin the exact appended text. Unit tests cover the wrapper directly (remedy text, code preservation, cause chaining, passthrough of other codes and non-`FsError` values) and the assembled tool paths assert the remedy reaches the model for both codes.
 
-The remedy is not a promise: a deleted observed target cannot be unblocked, because re-reading a missing file fails with `FS_NOT_FOUND` and records no observation. That dead end is pinned fail-closed in the integration tests — the retried mutation fails identically until the target exists again and is freshly observed.
+The [filesystem absence-observation follow-up](../bug-fix/2026-08-09-filesystem-absence-observation.md) makes the stale remedy actionable for external deletion. The failed reread still returns `FS_NOT_FOUND`, but records confirmed absence: edit then returns `FS_NOT_FOUND` without another stale remedy, while write retries as an atomic `createIfAbsent` and preserves any concurrent creator.
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
index 6bb0d0b6ff..88309bd630 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -29,4 +29,4 @@ Status: implemented
 
 两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装层（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
 
-恢复指令不是承诺：已观察但被删除的目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被重新观察之前，重试的变更以相同方式失败。
+[文件系统缺失观测后续决策](../bug-fix/2026-08-09-filesystem-absence-observation.md)使外部删除场景下的陈旧恢复指令能够生效。失败的重新读取仍返回 `FS_NOT_FOUND`，但会记录确认缺失：随后 edit 返回 `FS_NOT_FOUND`，不再附加陈旧恢复指令；write 则以原子 `createIfAbsent` 重试，并保留任何并发创建者写入的文件。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 5ec532504d..9607dc8d1a 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: a059159aae690330c55971bc49d62fcb1b030660
-config-catalog.zh.md: 9a0742ec8af10db90d0a2aad146c0cbec5a1a8a2
+config-catalog.md: 5f3bc744b25bf20d50e88ce75812fe8bd624905a
+config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a059159aae..5f3bc744b2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2137,7 +2137,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/tool-str-replace-editor/src/index.ts:496`](../packages/fs/tool-str-replace-editor/src/index.ts)
+Source: [`packages/fs/tool-str-replace-editor/src/index.ts:497`](../packages/fs/tool-str-replace-editor/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-subagent`
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 9a0742ec8a..a7d4252c52 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -2138,7 +2138,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/fs/tool-str-replace-editor/src/index.ts:496`](../packages/fs/tool-str-replace-editor/src/index.ts)
+来源：[`packages/fs/tool-str-replace-editor/src/index.ts:497`](../packages/fs/tool-str-replace-editor/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-subagent`
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 788069e02d..41da1ee118 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: d5f6674a5e9355f6f2c3fac23a45fcda180b3a0f
-event-producer-consumer.zh.md: 7568e852c891e6c9556486899fe1bdcd3053cb07
+event-producer-consumer.md: 5b36725402c0a12c5e2a09c743c2e7cf28d2c14a
+event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index d5f6674a5e..5b36725402 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -24,9 +24,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 7568e852c8..2d4c805f9a 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -26,9 +26,9 @@
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 3dad767e63..04c08db9a6 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 6748ddc7f290b6714302223758587226647641e7
-filesystem.zh.md: 28535d3d9d40e92bb6d5b2b0995a535b42fd9a23
+filesystem.md: 5d06611cbad2a3f146ddef4dbc96b2b6fc0a5b46
+filesystem.zh.md: 97aac2ee20783787909605d90a94181bf093d78a
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 6748ddc7f2..5d06611cba 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -2,7 +2,7 @@
 
 English | [中文](filesystem.zh.md)
 
-The optional filesystem capability has four parts: [dsh-fs](../../packages/fs/fs) owns `ctx.fs` and atomic text operations with optional version guards, [dsh-fs-local](../../packages/fs/fs-local) implements local disk, [dsh-fs-policy](../../packages/fs/fs-policy) adds observed-state and freshness rules through events rather than a service, and [dsh-tool-fs](../../packages/fs/tool-fs) directly executes model-facing read/write/edit calls and renders windows. It is outside the agent-loop spine; alternate backends do not change policy or tool schemas.
+The optional filesystem capability has four parts: [dsh-fs](../../packages/fs/fs) owns `ctx.fs` and atomic text operations with optional guards, [dsh-fs-local](../../packages/fs/fs-local) implements local disk, [dsh-fs-policy](../../packages/fs/fs-policy) records observed presence or absence and adds freshness rules through events rather than a service, and [dsh-tool-fs](../../packages/fs/tool-fs) directly executes model-facing read/write/edit calls and renders windows. It is outside the agent-loop spine; alternate backends do not change policy or tool schemas.
 
 The model is **additive, not subtractive**: `ctx.fs` alone is a complete, unconstrained text-storage seam (`write` unconditionally creates-or-overwrites, `edit` unconditionally replaces literal text). `dsh-fs-policy` is a plugin that *adds* policy on top by deciding the `fs/*` waterfalls; removing it leaves the bare provider rather than breaking the tool, because the tool is not method-coupled to the policy. A deployment that loads `dsh-tool-fs` is expected to also load `dsh-fs-policy` so the default behavior is read-before-write/edit.
 
@@ -113,7 +113,7 @@ interface FsDirEntry {
 
 ## Write and edit guards (provider contract)
 
-Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
+Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`, including a target that appears after the provider's initial probe because publication itself must be no-replace; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
 
 ```ts type-equiv
 /**
@@ -181,7 +181,18 @@ interface FsEditOutcome {
 
 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
-`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
+`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event carrying an `FsObservation`: present at a version or confirmed absent. It is dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener can replace a read error or surface as the tool's `isError` result after a mutation already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
+
+```ts type-equiv
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+type FsObservation =
+  | { readonly kind: 'present'; readonly version: FsVersion }
+  | { readonly kind: 'absent' }
+```
 
 ## Execution context (policy plugin)
 
@@ -209,7 +220,7 @@ interface FsPolicyExec {
 
 ## Read outcome (consumer / read rendering)
 
-A text read is bounded by line window, byte cap, and backend limits. After the byte cap is reached, scanning continues without retaining more lines so `totalLines` remains exact. The outcome the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view — authorization is freshness-based (the tool emits `fs/observed` with the stat's version directly), so any windowed read can authorize a later write/edit when the file is unchanged. Read windowing and this outcome shape live in `dsh-tool-fs` (the executor that owns the read), not in the policy plugin.
+A text read is bounded by line window, byte cap, and backend limits. After the byte cap is reached, scanning continues without retaining more lines so `totalLines` remains exact. The outcome the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view — authorization is freshness-based (the tool emits a present `fs/observed` with the stat's version), so any windowed read can authorize a later write/edit when the file is unchanged. A metadata miss emits an absent observation before the tool returns `FS_NOT_FOUND`, allowing a later guarded write to recreate an externally deleted target without authorizing edit. Read windowing and this outcome shape live in `dsh-tool-fs` (the executor that owns the read), not in the policy plugin.
 
 ```ts type-equiv
 /** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
@@ -227,7 +238,7 @@ interface FileReadOutcome {
 
 ## Observed-file state (policy plugin)
 
-Observed state is a `WeakMap<owner, Map<targetKey, { version }>>` held inside the `dsh-fs-policy` plugin. An entry exists **iff** the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence is the prior-observation record — there is no separate `hasRead` flag and no view distinction. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. A successful read/write/edit refreshes the recorded version for that owner; disposal drops everything (HMR safety).
+Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a tool read/view confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
 
 ## Error taxonomy (provider contract)
 
@@ -254,7 +265,7 @@ type FsErrorCode =
   | 'FS_ABORTED'
 ```
 
-`FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) — the mode fence denied a write/edit — distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_STALE_VERSION` means the backend version no longer matches the observed one (or an edit hit a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
+`FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) — the mode fence denied a write/edit — distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_NOT_FOUND` also represents an edit rejected from confirmed absence. `FS_STALE_VERSION` means the backend version no longer matches the observed one (or the provider itself receives an edit for a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
 
 ## No timeouts on file IO
 
@@ -262,7 +273,7 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls from unseen/absent/present state and records `FsObservation` values. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -376,7 +387,7 @@ abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
  * @param target - the resolved target to write.
  * @param content - the full new file content.
  * @param expected - the write intent guarding the write; omit for unconditional.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this write
  *   runs under; a sandboxing backend fences the write by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -391,7 +402,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent,
  * @param target - the resolved target to edit.
  * @param edit - the literal search/replace request.
  * @param expected - the version guard; omit for an unconditional edit.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this edit runs
  *   under; a sandboxing backend fences the edit by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -402,7 +413,7 @@ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version:
 
 Types: [SandboxExecutionPolicy](sandbox.md)
 
-Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:86`](../../packages/fs/fs/src/index.ts)
 
 <a id="fs-events"></a>
 
@@ -425,27 +436,28 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:66`](../../packages/fs/fs/src/index.ts)
 
 <a id="fsobserved--emit"></a>
 
 #### `fs/observed` — emit
 
-Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+Record an authoritative positive or negative observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
 
 ```ts cordis-catalog
 /**
- * Record a successful observation. Listeners must be synchronous recorders:
- * throws fail the tool call and returned promises are not awaited.
- * @param target - the target that was read/written/edited.
- * @param version - the version the actor now holds as its observation.
+ * Record an authoritative positive or negative observation. Listeners must
+ * be synchronous recorders: throws fail the tool call and returned promises
+ * are not awaited.
+ * @param target - the target whose presence or absence was observed.
+ * @param observation - present with its version, or confirmed absent.
  * @param actor - the observing tool-execution context; undefined records nothing useful.
  * @mode emit
  */
-'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 ```
 
-Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:76`](../../packages/fs/fs/src/index.ts)
 
 <a id="fswrite-intent--waterfall"></a>
 
@@ -465,5 +477,5 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:58`](../../packages/fs/fs/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 28535d3d9d..97aac2ee20 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -2,7 +2,7 @@
 
 [English](filesystem.md) | 中文
 
-可选的文件系统能力由四个部分组成：[dsh-fs](../../packages/fs/fs) 拥有 `ctx.fs` 以及带可选版本守卫的原子文本操作；[dsh-fs-local](../../packages/fs/fs-local) 实现本地磁盘后端；[dsh-fs-policy](../../packages/fs/fs-policy) 通过事件（而非服务）添加观测状态与新鲜度规则；[dsh-tool-fs](../../packages/fs/tool-fs) 直接执行面向模型的 read/write/edit 调用并渲染窗口。它位于 agent loop（智能体循环）主干之外；替换后端不会改变策略或工具 schema。
+可选的文件系统能力由四个部分组成：[dsh-fs](../../packages/fs/fs) 拥有 `ctx.fs` 以及带可选守卫的原子文本操作；[dsh-fs-local](../../packages/fs/fs-local) 实现本地磁盘后端；[dsh-fs-policy](../../packages/fs/fs-policy) 记录观测到的存在或缺失状态，并通过事件（而非服务）添加新鲜度规则；[dsh-tool-fs](../../packages/fs/tool-fs) 直接执行面向模型的 read/write/edit 调用并渲染窗口。它位于 agent loop（智能体循环）主干之外；替换后端不会改变策略或工具 schema。
 
 该模型是**加法式而非减法式**的：`ctx.fs` 本身就是一个完整、无约束的文本存储 seam（`write` 无条件创建或覆盖，`edit` 无条件替换字面文本）。`dsh-fs-policy` 是一个插件，通过裁决 `fs/*` waterfall（瀑布式事件）在上层*叠加*策略；移除它只会暴露裸提供方，而不会破坏工具，因为工具与策略之间没有方法级耦合。加载了 `dsh-tool-fs` 的部署通常也应加载 `dsh-fs-policy`，使默认行为为「先读后写/编辑」。
 
@@ -113,7 +113,7 @@ interface FsDirEntry {
 
 ## 写入与编辑守卫（提供方约定）
 
-`writeText` 和 `editText` 的版本守卫都是可选的：省略守卫时执行无条件的裸提供方变更，提供守卫时则执行相应的条件检查。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
+`writeText` 和 `editText` 的版本守卫都是可选的：省略守卫时执行无条件的裸提供方变更，提供守卫时则执行相应的条件检查。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；即使目标在提供方初始探测后才出现，也必须拒绝，因为发布操作本身不得替换。`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
 
 ```ts type-equiv
 /**
@@ -181,7 +181,18 @@ interface FsEditOutcome {
 
 `dsh-fs` 拥有三个事件，由工具分发、策略插件监听，使发射方（`dsh-tool-fs`）与监听方（`dsh-fs-policy`）共享词汇，而发射方无需依赖策略插件。它们只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不含面向模型的概念，也不含 agent/会话所有者结构。
 
-`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方会导致工具为一次已经成功的变更返回 `isError` 结果。下方生成的 [cordis surface](#cordis-surface) 展示确切签名。
+`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，携带 `FsObservation`：存在于某个版本，或确认缺失。该事件通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方可能取代读取操作原本待返回的错误，或使工具在变更已经成功后返回 `isError` 结果。下方生成的 [cordis surface](#cordis-surface) 展示确切签名。
+
+```ts type-equiv
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+type FsObservation =
+  | { readonly kind: 'present'; readonly version: FsVersion }
+  | { readonly kind: 'absent' }
+```
 
 ## 执行上下文（策略插件）
 
@@ -209,7 +220,7 @@ interface FsPolicyExec {
 
 ## 读取结果（消费方 / 读取渲染）
 
-文本读取受行窗口、字节上限和后端限制约束。达到字节上限后，扫描仍会继续，但不再保留更多行，因此 `totalLines` 仍为精确值。面向模型的 `read` 工具渲染的结果纯粹是展示性的；不存在 `full`/`partial` 视图区分——授权基于新鲜度（工具直接用 stat 的版本 emit `fs/observed`），因此任何窗口化读取在文件未变时都能授权后续的 write/edit。读取窗口化与此结果形状位于 `dsh-tool-fs`（拥有读取操作的执行器）中，而非策略插件中。
+文本读取受行窗口、字节上限和后端限制约束。达到字节上限后，扫描仍会继续，但不再保留更多行，因此 `totalLines` 仍为精确值。面向模型的 `read` 工具渲染的结果纯粹是展示性的；不存在 `full`/`partial` 视图区分——授权基于新鲜度（工具以 stat 的版本 emit 表示存在的 `fs/observed`），因此任何窗口化读取在文件未变时都能授权后续的 write/edit。元数据未命中时，工具会在返回 `FS_NOT_FOUND` 前 emit 缺失观测，使后续带防护的写入可以重新创建外部删除的目标，但不会授权 edit。读取窗口化与此结果形状位于 `dsh-tool-fs`（拥有读取操作的执行器）中，而非策略插件中。
 
 ```ts type-equiv
 /** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
@@ -227,7 +238,7 @@ interface FileReadOutcome {
 
 ## 已观测文件状态（策略插件）
 
-已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, { version }>>`。**当且仅当**所有者已读取、写入或编辑过该目标时（每次成功都 emit `fs/observed`），条目才存在，因此其存在本身就是先前观测的记录——没有单独的 `hasRead` 标志，也没有视图区分。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。成功的 read/write/edit 会刷新该所有者对应的已记录版本；dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全）。
+已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, FsObservation>>`。映射中没有条目表示未见；`{ kind: 'absent' }` 表示工具的 read/view 已确认缺失；`{ kind: 'present', version }` 表示 read、write 或 edit 观测到该版本。写入决策把未见和缺失映射到 `createIfAbsent`，把存在映射到 `replaceIfVersion`；编辑决策把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全），策略不执行任何文件系统 I/O。
 
 ## 错误分类体系（提供方约定）
 
@@ -254,7 +265,7 @@ type FsErrorCode =
   | 'FS_ABORTED'
 ```
 
-目录列表使用 `FS_NOT_DIRECTORY`、`FS_PERMISSION_DENIED` 与 `FS_IO_ERROR` 区分已存在但并非目录的目标、被拒绝的列表操作和意外的后端 I/O 失败。`FS_SANDBOX_DENIED` 是强制执行沙箱的后端（`dsh-fs-sandbox`）所作的策略拒绝——模式边界拒绝了写入/编辑——与 `FS_PERMISSION_DENIED`（宿主内核拒绝）不同。`FS_NOT_OBSERVED` 表示策略插件没有此所有者的先前观察记录（或 `createIfAbsent` 遇到了现有文件）。`FS_STALE_VERSION` 表示后端版本不再与观察到的版本匹配（或编辑操作遇到缺失目标）。新鲜度授权没有部分/完整之分，因此不存在 `FS_PARTIAL_OBSERVATION`。
+目录列表使用 `FS_NOT_DIRECTORY`、`FS_PERMISSION_DENIED` 与 `FS_IO_ERROR` 区分已存在但并非目录的目标、被拒绝的列表操作和意外的后端 I/O 失败。`FS_SANDBOX_DENIED` 是强制执行沙箱的后端（`dsh-fs-sandbox`）所作的策略拒绝——模式边界拒绝了写入/编辑——与 `FS_PERMISSION_DENIED`（宿主内核拒绝）不同。`FS_NOT_OBSERVED` 表示策略插件没有此所有者的先前观测记录（或 `createIfAbsent` 遇到了现有文件）。`FS_NOT_FOUND` 也表示策略因确认缺失而拒绝 edit。`FS_STALE_VERSION` 表示后端版本不再与观测到的版本匹配（或提供方本身收到针对缺失目标的 edit）。新鲜度授权没有部分/完整之分，因此不存在 `FS_PARTIAL_OBSERVATION`。
 
 ## 文件 IO 不设超时
 
@@ -262,7 +273,7 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：根据未见/缺失/存在状态对写入与编辑意图 waterfall 作出决策，并记录 `FsObservation` 值。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -376,7 +387,7 @@ abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
  * @param target - the resolved target to write.
  * @param content - the full new file content.
  * @param expected - the write intent guarding the write; omit for unconditional.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this write
  *   runs under; a sandboxing backend fences the write by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -391,7 +402,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent,
  * @param target - the resolved target to edit.
  * @param edit - the literal search/replace request.
  * @param expected - the version guard; omit for an unconditional edit.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this edit runs
  *   under; a sandboxing backend fences the edit by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -402,7 +413,7 @@ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version:
 
 Types: [SandboxExecutionPolicy](sandbox.md)
 
-Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:86`](../../packages/fs/fs/src/index.ts)
 
 <a id="fs-events"></a>
 
@@ -425,27 +436,28 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:66`](../../packages/fs/fs/src/index.ts)
 
 <a id="fsobserved--emit"></a>
 
 #### `fs/observed` — emit
 
-Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+Record an authoritative positive or negative observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
 
 ```ts cordis-catalog
 /**
- * Record a successful observation. Listeners must be synchronous recorders:
- * throws fail the tool call and returned promises are not awaited.
- * @param target - the target that was read/written/edited.
- * @param version - the version the actor now holds as its observation.
+ * Record an authoritative positive or negative observation. Listeners must
+ * be synchronous recorders: throws fail the tool call and returned promises
+ * are not awaited.
+ * @param target - the target whose presence or absence was observed.
+ * @param observation - present with its version, or confirmed absent.
  * @param actor - the observing tool-execution context; undefined records nothing useful.
  * @mode emit
  */
-'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 ```
 
-Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:76`](../../packages/fs/fs/src/index.ts)
 
 <a id="fswrite-intent--waterfall"></a>
 
@@ -465,5 +477,5 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:58`](../../packages/fs/fs/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index cb88c51de0..752a8f6a9e 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: 36ea230990abd65ad0435e257e237f9bf873108f
-tool-catalog.zh.md: f6073b84a08ed25c3fa6e8104388e00aa774a34a
+tool-catalog.md: abcba1ca5dcb148aa0ee5578ff4fd0373993db1d
+tool-catalog.zh.md: 32c761d0d2854bf2310eb0ddb382553575bd4df9
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 36ea230990..abcba1ca5d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -22,8 +22,8 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after successful file operations`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
-| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
+| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after read presence/absence or successful mutation`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.subprocess`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
 | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `goal/change for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. |
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index f6073b84a0..32c761d0d2 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -24,8 +24,8 @@
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after successful file operations`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
-| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after successful file operations`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after read presence/absence or successful mutation`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
 | `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`goal/change for mutations`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index b0b646eade..af044fc58f 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -255,6 +255,7 @@ const SCENARIOS: Scenario[] = [
   { name: 'fs-write-overwrite', hasModelTurn: true, recorded: true },
   { name: 'fs-read-window', hasModelTurn: true, recorded: true },
   { name: 'fs-policy-reject', hasModelTurn: true, recorded: true },
+  { name: 'fs-delete-recreate', hasModelTurn: true, recorded: true },
   { name: 'multi-turn', hasModelTurn: true, recorded: true },
   { name: 'error-finish', hasModelTurn: true, recorded: false, overridden: true },
   // Keyless, authored (like error-finish): a live provider cannot be coaxed
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json b/examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json
new file mode 100644
index 0000000000..f6c181074f
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json
@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Perform these exact steps in order on deleted.txt in the current directory: (1) use the read tool to read it, (2) use the bash tool with command `rm deleted.txt`, (3) use the read tool on deleted.txt again and observe the not-found error, (4) use the write tool to recreate deleted.txt with exactly the content `fresh\\n`, and (5) reply with exactly the single word DONE. Do not use any other tools or skip any step." }
+  ]
+}
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl b/examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl
new file mode 100644
index 0000000000..7cccd53d6b
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl
@@ -0,0 +1,62 @@
+{"type":"session","version":0,"id":"b8c89c36-55db-48cf-9f3e-76140cd37aff","createdAt":1786259114417,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1786259114424,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Perform these exact steps in order on deleted.txt in the current directory: (1) use the read tool to read it, (2) use the bash tool with command `rm deleted.txt`, (3) use the read tool on deleted.txt again and observe the not-found error, (4) use the write tool to recreate deleted.txt with exactly the content `fresh\\n`, and (5) reply with exactly the single word DONE. Do not use any other tools or skip any step."}],"source":{"kind":"user"},"role":"user","id":"d2c7929c-e9af-4011-85c4-fe35eb4d5bfe"}]}}
+{"type":"turn/start","seq":1,"time":1786259114425,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1786259114425,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1786259114479,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1786259114479,"data":{"content":[{"type":"text","text":"Perform these exact steps in order on deleted.txt in the current directory: (1) use the read tool to read it, (2) use the bash tool with command `rm deleted.txt`, (3) use the read tool on deleted.txt again and observe the not-found error, (4) use the write tool to recreate deleted.txt with exactly the content `fresh\\n`, and (5) reply with exactly the single word DONE. Do not use any other tools or skip any step."}],"source":{"kind":"user"},"role":"user","id":"d2c7929c-e9af-4011-85c4-fe35eb4d5bfe"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1786259114479,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"09f49ebb-fe8b-4100-9fb1-63461c4e5ff4"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":1786259114480,"data":{"title":"Perform these exact steps in","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":1786259114481,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":1786259114481,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":9,"time":1786259115592,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":10,"time0":1786259115592,"data":{"turn":1,"step":1,"index":0,"dt":[100,24,1,0,0,0,21,0,0,0,0,1,22,0,1,23,1,0,0,25,0,21,1,0,0,0,21,1,0,0,24,0,1,0,0,0,20,0,27,1,0,0,26,1,0,21,1,0,0,19,89,0,0,0,0,1,0,0,0,0,0,1,0],"texts":["The"," user"," wants"," me"," to"," perform"," exact"," steps"," in"," order",":\n","1","."," read"," deleted",".txt","\n","2","."," bash"," rm"," deleted",".txt","\n","3","."," read"," deleted",".txt"," again"," and"," observe"," not","-found"," error","\n","4","."," write"," deleted",".txt"," with"," content"," \"","fresh","\\n","\"\n","5","."," reply"," with"," exactly"," \"","D","ONE","\"\n\n","Let"," me"," do"," step"," ","1"," first","."]}}
+{"type":"assistant/chunk","seq":74,"time":1786259116112,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":75,"time0":1786259116112,"data":{"turn":1,"step":1,"index":1,"dt":[22,1,0,0,0,0,25,0,0,0,21,0],"id":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","args":["","{","\"","file","_path","\"",": ","\"","de","leted",".txt","\"","}"]}}
+{"type":"assistant/chunk","seq":88,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to perform exact steps in order:\n1. read deleted.txt\n2. bash rm deleted.txt\n3. read deleted.txt again and observe not-found error\n4. write deleted.txt with content \"fresh\\n\"\n5. reply with exactly \"DONE\"\n\nLet me do step 1 first."}}}}
+{"type":"assistant/chunk","seq":89,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}}}
+{"type":"assistant/chunk","seq":90,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":6102,"outputTokens":110,"cacheReadTokens":0,"reasoningTokens":64}}}}
+{"type":"assistant/chunk","seq":91,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":92,"time":1786259116237,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to perform exact steps in order:\n1. read deleted.txt\n2. bash rm deleted.txt\n3. read deleted.txt again and observe not-found error\n4. write deleted.txt with content \"fresh\\n\"\n5. reply with exactly \"DONE\"\n\nLet me do step 1 first."},{"type":"tool-call","id":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"121e3a9b-14bd-491b-817d-5abb0be3f45d"},"usage":{"inputTokens":6102,"outputTokens":110,"cacheReadTokens":0,"reasoningTokens":64}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91],"surfaceOp":"append"}
+{"type":"tool/call","seq":93,"time":1786259116238,"data":{"turn":1,"step":1,"callId":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}
+{"type":"tool/result","seq":94,"time":1786259116249,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_vDjxu2gdu87Gj8XZZvba8767"},"content":[{"type":"tool-result","toolCallId":"call_00_vDjxu2gdu87Gj8XZZvba8767","content":[{"type":"text","text":"<path>{{cwd}}/deleted.txt</path>\n<type>file</type>\n<content>\n1: original\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"c3c0fe4a-3c93-433b-990e-1e5963964505"},"meta":{"path":"{{cwd}}/deleted.txt","offset":1,"lines":[{"number":1,"text":"original"}],"totalLines":1}},"sourceEventSeqs":[93],"surfaceOp":"append"}
+{"type":"step/end","seq":95,"time":1786259116249,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":96,"time":1786259116260,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":97,"time":1786259117343,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":98,"time0":1786259117344,"data":{"turn":1,"step":2,"index":0,"dt":[23,1,0,0,1,21,1,0,0,0,47,0,1,1,0,21,1,0,0,1,18,1],"id":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","args":["","{","\"","command","\"",": ","\"","rm"," deleted",".txt","\"",", ","\"","description","\"",": ","\"","Delete"," deleted",".txt"," file","\"","}"]}}
+{"type":"assistant/chunk","seq":121,"time":1786259117528,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","arguments":"{\"command\": \"rm deleted.txt\", \"description\": \"Delete deleted.txt file\"}"}}}}
+{"type":"assistant/chunk","seq":122,"time":1786259117528,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":151,"outputTokens":64,"cacheReadTokens":6144,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":123,"time":1786259117528,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":124,"time":1786259117529,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","arguments":"{\"command\": \"rm deleted.txt\", \"description\": \"Delete deleted.txt file\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"d85f99a5-732d-4127-85d7-cbd7bfa73bb2"},"usage":{"inputTokens":151,"outputTokens":64,"cacheReadTokens":6144,"reasoningTokens":0}},"sourceEventSeqs":[97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123],"surfaceOp":"append"}
+{"type":"tool/call","seq":125,"time":1786259117529,"data":{"turn":1,"step":2,"callId":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","arguments":"{\"command\": \"rm deleted.txt\", \"description\": \"Delete deleted.txt file\"}"}}
+{"type":"tool/result","seq":126,"time":1786259117553,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697"},"content":[{"type":"tool-result","toolCallId":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","content":[{"type":"text","text":"(no output)"}],"isError":false}],"role":"user","id":"7a80dfb4-3234-41c5-b276-3384f4198765"}},"sourceEventSeqs":[125],"surfaceOp":"append"}
+{"type":"step/end","seq":127,"time":1786259117553,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":128,"time":1786259117560,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":129,"time":1786259118917,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":130,"time0":1786259118917,"data":{"turn":1,"step":3,"index":0,"dt":[25,2,0,0,0,1,21,1,0,0,27,2],"id":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","args":["","{","\"","file","_path","\"",": ","\"","de","leted",".txt","\"","}"]}}
+{"type":"assistant/chunk","seq":143,"time":1786259119037,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}}}
+{"type":"assistant/chunk","seq":144,"time":1786259119037,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":101,"outputTokens":46,"cacheReadTokens":6272,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":145,"time":1786259119037,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":146,"time":1786259119038,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"c08b2b60-786f-4a74-a826-e2e3aa09e851"},"usage":{"inputTokens":101,"outputTokens":46,"cacheReadTokens":6272,"reasoningTokens":0}},"sourceEventSeqs":[129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145],"surfaceOp":"append"}
+{"type":"tool/call","seq":147,"time":1786259119039,"data":{"turn":1,"step":3,"callId":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}
+{"type":"tool/result","seq":148,"time":1786259119049,"data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261"},"content":[{"type":"tool-result","toolCallId":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","content":[{"type":"text","text":"Error: cannot read \"{{cwd}}/deleted.txt\": not found"}],"isError":true}],"role":"user","id":"660e8735-5bf4-44f8-8835-7aeb70d6a95d"},"error":{"name":"FsError","code":"FS_NOT_FOUND"}},"sourceEventSeqs":[147],"surfaceOp":"append"}
+{"type":"step/end","seq":149,"time":1786259119050,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":150,"time":1786259119058,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":151,"time":1786259120173,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":152,"time0":1786259120174,"data":{"turn":1,"step":4,"index":0,"dt":[108,1,1,0,0,0,1,0,1,0,0,0,1,0,0,0,1,72,0,0,1],"id":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","args":["","{","\"","file","_path","\"",": ","\"","de","leted",".txt","\"",", ","\"","content","\"",": ","\"","fresh","\\n","\"","}"]}}
+{"type":"assistant/chunk","seq":174,"time":1786259120361,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","arguments":"{\"file_path\": \"deleted.txt\", \"content\": \"fresh\\n\"}"}}}}
+{"type":"assistant/chunk","seq":175,"time":1786259120361,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":79,"outputTokens":63,"cacheReadTokens":6400,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":176,"time":1786259120361,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":177,"time":1786259120362,"data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","arguments":"{\"file_path\": \"deleted.txt\", \"content\": \"fresh\\n\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"de52e93e-d45e-488b-b110-ce10de3387ba"},"usage":{"inputTokens":79,"outputTokens":63,"cacheReadTokens":6400,"reasoningTokens":0}},"sourceEventSeqs":[151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176],"surfaceOp":"append"}
+{"type":"tool/call","seq":178,"time":1786259120363,"data":{"turn":1,"step":4,"callId":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","arguments":"{\"file_path\": \"deleted.txt\", \"content\": \"fresh\\n\"}"}}
+{"type":"tool/result","seq":179,"time":1786259120381,"data":{"turn":1,"step":4,"message":{"source":{"kind":"tool","callId":"call_00_ET_OqjRZggKy6eetff5jh3V9977"},"content":[{"type":"tool-result","toolCallId":"call_00_ET_OqjRZggKy6eetff5jh3V9977","content":[{"type":"text","text":"<path>{{cwd}}/deleted.txt</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false}],"role":"user","id":"f10e6310-8f96-468b-9837-3068dc8af472"},"meta":{"diffs":[]}},"sourceEventSeqs":[178],"surfaceOp":"append"}
+{"type":"step/end","seq":180,"time":1786259120381,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":181,"time":1786259120389,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":182,"time":1786259121079,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":183,"time":1786259121079,"data":{"turn":1,"step":5,"chunk":{"type":"text-delta","index":0,"text":"D"}}}
+{"type":"assistant/chunk","seq":184,"time":1786259121104,"data":{"turn":1,"step":5,"chunk":{"type":"text-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":185,"time":1786259121115,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":186,"time":1786259121116,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":88,"outputTokens":3,"cacheReadTokens":6528,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":187,"time":1786259121116,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":188,"time":1786259121116,"data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6c904bc2-55c6-4dfe-85a6-0a5d7d2ad7b4"},"usage":{"inputTokens":88,"outputTokens":3,"cacheReadTokens":6528,"reasoningTokens":0}},"sourceEventSeqs":[182,183,184,185,186,187],"surfaceOp":"append"}
+{"type":"step/end","seq":189,"time":1786259121117,"data":{"turn":1,"step":5}}
+{"type":"turn/end","seq":190,"time":1786259121117,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl
new file mode 100644
index 0000000000..82ae8907ca
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt b/examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt
new file mode 100644
index 0000000000..4b48deed3a
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt
@@ -0,0 +1 @@
+original
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 90c7931644..4e29843fad 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: b346b4c5bc7bc2888ccd3dc210bb90e0f1cc5965
-README.zh.md: b84b2382c03dc6e422228b19a58aff927e8a5db7
+README.md: 039ad72a9651a1e8907c2c63b8c83d113aedbb4e
+README.zh.md: be97bbd92edb528f9560518398a0cb70f36b992b
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index b346b4c5bc..039ad72a96 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -9,8 +9,8 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the filesystem seam's observed-state semantics.
-- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, and preserve an existing file's POSIX mode. Replacements publish through E2B's same-filesystem atomic rename. A guarded `createIfAbsent` publishes with remote `ln` instead, making the commit atomically no-replace; metadata read from the staged file before that commit is projected to the target path for the returned version, so no fallible metadata request follows either commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before publication. The signal is not forwarded into the rename or guarded-link commit, so cancellation cannot interrupt atomic publication or turn a committed write into a reported failure.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
 
@@ -25,7 +25,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **No host synchronization** — an empty E2B cwd stays empty until a tool, command, or external process populates it; local files are neither uploaded nor reflected back.
-- **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Mutation coordination is host-process-local** — `createIfAbsent` preserves a remote creator racing publication, but another harness connection or command can still race replacement; version guards detect only metadata changes represented by E2B.
 - **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
 - **The POC targets E2B's default Linux image** — it relies on GNU `realpath`/`base64`/`chmod`, same-filesystem rename, streaming reads, and metadata extended attributes; custom templates are outside this POC.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index b84b2382c0..be97bbd92e 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -9,8 +9,8 @@
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留文件系统 seam 的已观察状态语义。
-- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，并保留现有文件的 POSIX mode。替换操作通过 E2B 的同一文件系统原子重命名发布。带防护的 `createIfAbsent` 改用远程 `ln` 发布，使提交具备原子且不替换的语义；系统会把提交前从暂存文件读取的元数据投影到目标路径，以生成返回的版本，因此任何一类提交点之后都不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在发布前立即检查。信号不会传入 rename 或防护链接提交，因此取消无法中断原子发布，也不会把已提交的写入报告为失败。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
 
@@ -25,7 +25,7 @@
 ## 已知限制与延后工作
 
 - **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
-- **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **变更协调仅限宿主进程内**：`createIfAbsent` 会保留与发布发生竞态的远程创建者所写入的文件，但另一个 harness 连接或命令仍可能与替换操作发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
 - **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
 - **该 POC 面向 E2B 默认 Linux 镜像**：它依赖 GNU `realpath`／`base64`／`chmod`、同一文件系统内的 rename、流式读取和元数据扩展属性；自定义模板不在该 POC 范围内。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 83ff7bd99b..04b23a6775 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -332,7 +332,13 @@ export class E2BFileSystem extends FileSystem {
       }
       this.checkWriteIntent(existing, expected, target)
       const before = existing === undefined ? null : await this.readForDiff(target, signal)
-      const version = await this.writeAtomic(target, content, existing, signal)
+      const version = await this.writeAtomic(
+        target,
+        content,
+        existing,
+        expected?.kind === 'createIfAbsent',
+        signal,
+      )
       return {
         operation: existing === undefined ? 'create' : 'update',
         version,
@@ -363,7 +369,7 @@ export class E2BFileSystem extends FileSystem {
       const before = normalizeLineEndings(raw)
       const after = literalEdit(before, edit, target.displayPath)
       const storage = restoreLineEndings(after, detectsCrlf(raw))
-      const version = await this.writeAtomic(target, storage, existing, signal)
+      const version = await this.writeAtomic(target, storage, existing, false, signal)
       return { version, before, after }
     })
   }
@@ -450,6 +456,7 @@ export class E2BFileSystem extends FileSystem {
     target: FsTarget,
     content: string,
     existing: EntryInfo | undefined,
+    createIfAbsent: boolean,
     signal?: AbortSignal,
   ): Promise<ReturnType<typeof FsVersion>> {
     assertNotAborted(signal, 'write')
@@ -476,7 +483,28 @@ export class E2BFileSystem extends FileSystem {
         commandOpts(signal),
       )
       assertNotAborted(signal, 'write')
-      const committed = await sandbox.files.rename(temporary, targetPath)
+      let committed: EntryInfo
+      if (createIfAbsent) {
+        const staged = await sandbox.files.getInfo(temporary, signalOpts(signal))
+        assertNotAborted(signal, 'write')
+        const targetArg = quoteE2BShellArg(targetPath)
+        const publication = await sandbox.commands.run(
+          `if ln -- ${quoteE2BShellArg(temporary)} ${targetArg}; then printf created; elif test -e ${targetArg} || test -L ${targetArg}; then printf exists; else exit 1; fi`,
+          commandOpts(undefined),
+        )
+        if (publication.stdout === 'exists') {
+          throw new FsError(
+            `cannot overwrite existing "${target.displayPath}" without reading it first`,
+            'FS_NOT_OBSERVED',
+          )
+        }
+        if (publication.stdout !== 'created') {
+          throw new Error('guarded create returned an invalid publication result')
+        }
+        committed = { ...staged, name: posix.basename(targetPath), path: targetPath }
+      } else {
+        committed = await sandbox.files.rename(temporary, targetPath)
+      }
       try {
         await sandbox.files.remove(stagingDirectory)
       } catch (_committedStagingCleanupFailure) {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 9cad00b6eb..973cf7c5c8 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -37,6 +37,7 @@ class FakeRemote {
   readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
   readonly writeParentModes: number[] = []
   readonly renames: Array<{ from: string; to: string }> = []
+  readonly links: Array<{ from: string; to: string }> = []
   readonly removals: string[] = []
   readonly commands: string[] = []
   streamChunks: Uint8Array[] | undefined
@@ -51,6 +52,8 @@ class FakeRemote {
   nextRemoveError: unknown
   canonicalOutput: string | undefined
   abortAfterRename: AbortController | undefined
+  competitorBeforeLink: { path: string; data: string } | undefined
+  guardedLinkOutput: string | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
 
@@ -253,6 +256,28 @@ class FakeRemote {
         }
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
+        const guardedLink = new RegExp(
+          "^if ln -- '([^']+)' '([^']+)'; then printf created; "
+          + "elif test -e '[^']+' \\|\\| test -L '[^']+'; then printf exists; else exit 1; fi$",
+        ).exec(command)
+        if (guardedLink !== null) {
+          const from = guardedLink[1]!
+          const to = guardedLink[2]!
+          if (this.guardedLinkOutput !== undefined) {
+            const stdout = this.guardedLinkOutput
+            this.guardedLinkOutput = undefined
+            return { exitCode: 0, stdout, stderr: '' }
+          }
+          if (this.competitorBeforeLink?.path === to) {
+            this.file(to, this.competitorBeforeLink.data)
+            this.competitorBeforeLink = undefined
+          }
+          if (this.nodes.has(to)) return { exitCode: 0, stdout: 'exists', stderr: '' }
+          this.nodes.set(to, this.required(from))
+          this.links.push({ from, to })
+          this.abortAfterRename?.abort('after commit')
+          return { exitCode: 0, stdout: 'created', stderr: '' }
+        }
         const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
         if (move !== null) {
           if (this.nextRenameError !== undefined) {
@@ -475,6 +500,7 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
     expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
     expect(remote.writeParentModes).toEqual([0o700])
+    expect(remote.links).toHaveLength(1)
     const stagingDirectory = posix.dirname(remote.writes[0]!.path)
     expect(posix.dirname(stagingDirectory)).toBe('/workspace')
     expect(remote.removals).toContain(stagingDirectory)
@@ -527,6 +553,33 @@ describe('E2BFileSystem atomic writes and edits', () => {
     await expectCode(fs.writeText(await fs.resolve('dir'), 'x'), 'FS_NOT_REGULAR_FILE')
   })
 
+  it('preserves a competitor created after the guarded-create probe', async () => {
+    const remote = new FakeRemote()
+    remote.competitorBeforeLink = { path: '/workspace/race.txt', data: 'competitor' }
+    const { fs } = await setup(remote)
+
+    await expectCode(
+      fs.writeText(await fs.resolve('race.txt'), 'ours', { kind: 'createIfAbsent' }),
+      'FS_NOT_OBSERVED',
+    )
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/race.txt')?.data)).toBe('competitor')
+    expect(remote.links).toHaveLength(0)
+    expect(remote.removals).toHaveLength(1)
+  })
+
+  it('rejects an invalid guarded-create publication response before claiming success', async () => {
+    const remote = new FakeRemote()
+    remote.guardedLinkOutput = 'unexpected'
+    const { fs } = await setup(remote)
+
+    await expectCode(
+      fs.writeText(await fs.resolve('invalid.txt'), 'ours', { kind: 'createIfAbsent' }),
+      'FS_IO_ERROR',
+    )
+    expect(remote.nodes.has('/workspace/invalid.txt')).toBe(false)
+    expect(remote.removals).toHaveLength(1)
+  })
+
   it('does not turn an abort observed after a successful move into a failed write', async () => {
     const remote = new FakeRemote()
     const controller = new AbortController()
@@ -537,6 +590,20 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(controller.signal.aborted).toBe(true)
   })
 
+  it('does not turn an abort observed after a guarded create into a failed write', async () => {
+    const remote = new FakeRemote()
+    const controller = new AbortController()
+    remote.abortAfterRename = controller
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(
+      await fs.resolve('committed-create'),
+      'yes',
+      { kind: 'createIfAbsent' },
+      controller.signal,
+    )).resolves.toMatchObject({ operation: 'create' })
+    expect(controller.signal.aborted).toBe(true)
+  })
+
   it('does not turn post-commit staging cleanup failure into a failed write', async () => {
     const remote = new FakeRemote()
     remote.nextRemoveError = new Error('empty staging cleanup failed')
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index dd384cd2b1..6aaf691eef 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-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/fs/fs-local/README.md
-README.md: ec0cffea1c82ab3bb2485fcb22ac5339d5d2a0d9
-README.zh.md: 99adba8c8b58f1f0b6f0f5ab8b672eb074b38f31
+README.md: ac2f271ad9651797e1aceeba49e7a52533405f10
+README.zh.md: 633d55fe06b2261d9d5b52184987811c87c8f155
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index ec0cffea1c..ac2f271ad9 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
@@ -39,4 +39,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **Version tokens depend on filesystem metadata** — they combine device, inode, size, nanosecond mtime, and nanosecond ctime; a storage layer that cannot update any of those facts for a rewrite can still defeat the stale guard.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
-- **The per-target mutation lock is in-process only** — a writer in another process is caught only by the optional version guard, never serialized.
+- **The per-target mutation lock is in-process only** — guarded create still uses an atomic no-replace publication across processes, but replacement writers in another process are caught only when the optional version guard observes their metadata change; they are never serialized.
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 99adba8c8b..633d55fe06 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
 - **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
 - **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
 包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
@@ -39,4 +39,4 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **版本 token 依赖文件系统元数据**：它们组合设备、inode、大小、纳秒级 mtime 和纳秒级 ctime；如果存储层在重写时无法更新其中任何一项事实，仍可能绕过陈旧防护。
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
-- **每目标变更锁仅限进程内**：其他进程中的写入方只会被可选版本防护发现，绝不会被串行化。
+- **每目标变更锁仅限进程内**：即使跨进程，带防护的创建仍采用原子且不替换的发布方式；但只有当可选版本防护观察到元数据变化时，系统才能发现其他进程中的替换写入方，且绝不会将其串行化。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 7e063ca347..071ad31637 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -1,13 +1,13 @@
 /**
  * Cordis-free local filesystem mechanics. This provider layer returns validated UTF-8 text,
  * streams large files, and rejects binary data; line windows belong to `dsh-tool-fs`. Writes
- * stage an exclusive owner-only file in a private sibling directory and atomically rename it.
+ * stage an exclusive owner-only file in a private sibling directory and atomically publish it.
  * @module @deepseek-ai/dsh-fs-local/fsio
  */
 
 import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
-import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
+import { chmod, link, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
 import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { TextDecoder } from 'node:util'
@@ -20,6 +20,10 @@ function isENOENT(error: unknown): boolean {
   return error instanceof Error && 'code' in error && error.code === 'ENOENT'
 }
 
+function isEEXIST(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}
+
 /**
  * A path component that is expected to be a directory is a regular file (e.g.
  * resolving `afile/child.txt` when `afile` is a file). Like `ENOENT`, the target
@@ -85,7 +89,9 @@ export interface FsIoInternals {
   copyFileDacl?: (source: string, destination: string) => Promise<void>
   /** Override the Win32 security-preserving replacement boundary. */
   replaceFile?: (replaced: string, replacement: string) => Promise<void>
-  /** Test hook after the temp file is written/synced but before final chmod+rename. */
+  /** Override the hard-link no-replace publication boundary. */
+  linkFile?: (existingPath: string, newPath: string) => Promise<void>
+  /** Test hook after the temp file is written/synced but before final chmod+publication. */
   inspectTemp?: (paths: { stagingDir: string; tempPath: string }) => void | Promise<void>
 }
 
@@ -426,8 +432,10 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * @param content - the full UTF-8 text to write.
  * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
  * inert as a mode on Windows but identifies replacement security semantics.
- * @param signal - cancellation checked before the final rename.
+ * @param signal - cancellation checked before final publication.
  * @param internals - Test hook for pinning temp names and observing the staged file.
+ * @param createIfAbsent - publish with a hard-link no-replace primitive; a
+ *   concurrent creator is preserved and rejected with `FS_NOT_OBSERVED`.
  */
 export async function writeFileAtomic(
   absolutePath: string,
@@ -435,6 +443,7 @@ export async function writeFileAtomic(
   mode: number | undefined,
   signal: AbortSignal | undefined,
   internals: FsIoInternals = {},
+  createIfAbsent = false,
 ): Promise<void> {
   throwIfAborted(signal, 'write')
   const directory = dirname(absolutePath)
@@ -448,6 +457,7 @@ export async function writeFileAtomic(
   const platform = internals.platform ?? process.platform
   const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32
   const replaceFile = internals.replaceFile ?? replaceFileWin32
+  const linkFile = internals.linkFile ?? link
   let handle: Awaited<ReturnType<typeof open>> | undefined
   let stagingCreated = false
   try {
@@ -468,7 +478,18 @@ export async function writeFileAtomic(
     handle = undefined
 
     throwIfAborted(signal, 'write')
-    if (platform === 'win32' && mode !== undefined) {
+    if (createIfAbsent) {
+      try {
+        await linkFile(tempPath, absolutePath)
+      } catch (error: unknown) {
+        if (!isEEXIST(error)) throw error
+        throw new FsError(
+          `cannot overwrite existing "${absolutePath}" without reading it first`,
+          'FS_NOT_OBSERVED',
+          { cause: error },
+        )
+      }
+    } else if (platform === 'win32' && mode !== undefined) {
       try {
         await replaceFile(absolutePath, tempPath)
       } catch (error: unknown) {
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 6f9af5cec2..6be6a4402b 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -167,7 +167,14 @@ export class LocalFileSystem extends FileSystem {
       // Preserve prior text for contextual diffs; null falls back to a whole-file diff.
       // TODO(overwrite-diff-bound): cap this UI-only pre-read for large files.
       const before = existing ? await readTextForDiff(target.targetKey, signal) : null
-      await writeFileAtomic(target.targetKey, content, existing?.mode, signal, this.internals)
+      await writeFileAtomic(
+        target.targetKey,
+        content,
+        existing?.mode,
+        signal,
+        this.internals,
+        expected?.kind === 'createIfAbsent',
+      )
       const after = await probe(target.targetKey)
       return {
         operation: existing ? 'update' : 'create',
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index ee3abeebb8..531be25360 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -298,6 +298,16 @@ describe('writeText', () => {
     expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('old')
   })
 
+  it('createIfAbsent preserves a competitor created after the initial probe', async () => {
+    const path = join(dir, 'a.txt')
+    const target = await fs.resolve('a.txt')
+    fs.internals.inspectTemp = async () => { await writeFile(path, 'competitor') }
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' }))
+      .rejects.toMatchObject({ code: 'FS_NOT_OBSERVED' })
+    expect(await readFile(path, 'utf8')).toBe('competitor')
+  })
+
   it('replaceIfVersion replaces when the version matches', async () => {
     await writeFile(join(dir, 'a.txt'), 'old')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index ed30b896bf..9b62caba3f 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -496,6 +496,17 @@ describe('writeFileAtomic — temp-file safety', () => {
     expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
   })
 
+  it('surfaces a non-collision guarded-create publication failure and cleans staging', async () => {
+    const file = join(dir, 'a.txt')
+    const denied = Object.assign(new Error('link denied'), { code: 'EACCES' })
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      linkFile: async () => { throw denied },
+    }, true)).rejects.toBe(denied)
+    await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
   it.skipIf(!posixModes)('creates new files owner-only by default', async () => {
     const file = join(dir, 'a.txt')
     await writeFileAtomic(file, 'hello', undefined, undefined)
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index c2b72c65c8..e316171061 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: bf6486f6f7fe574b576a71b430be91031f7805d2
-README.zh.md: 2e38d63d8e310c7f22b764d46cbec0c82ffb96cf
+README.md: 0166690c66f38efe817d8b5779db9a677d22d321
+README.zh.md: 26e0199e6deb7fc12a860ab01884b70c1b7c9b38
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index bf6486f6f7..0166690c66 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **fs-policy plugin**: it adds observed-state, read-before-edit, and version-guarded write/edit on top of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
+The **fs-policy plugin**: it records observed presence or absence and adds read-before-edit plus guarded write/edit on top of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
 
 ```ts
 import type { Context } from 'cordis'
@@ -33,13 +33,13 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 | Event | This plugin's listener |
 |---|---|
-| `fs/write-intent` | No prior observation → `{ kind: 'createIfAbsent' }`; a prior observation → `{ kind: 'replaceIfVersion', version: vObserved }`. Single-slot decision; does NOT call `next()`. |
-| `fs/edit-intent` | Requires a prior observation by this owner (else throws `FS_NOT_OBSERVED`); returns `{ version: vObserved }` as the CAS basis. Single-slot decision; does NOT call `next()`. |
-| `fs/observed` | Records `{ version }` for this owner+target. Synchronous, side-effect-only `WeakMap.set`. |
+| `fs/write-intent` | Unseen or observed absent → `{ kind: 'createIfAbsent' }`; observed present → `{ kind: 'replaceIfVersion', version: vObserved }`. Single-slot decision; does NOT call `next()`. |
+| `fs/edit-intent` | Unseen → `FS_NOT_OBSERVED`; observed absent → `FS_NOT_FOUND`; observed present → `{ version: vObserved }` as the CAS basis. Single-slot decision; does NOT call `next()`. |
+| `fs/observed` | Records `{ kind: 'present', version }` or `{ kind: 'absent' }` for this owner+target. Synchronous, side-effect-only `WeakMap.set`. |
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a weak owner-to-target version map updated after every successful read or mutation; presence alone is the prior-observation record. The plugin performs no filesystem I/O: it supplies the observed version to the provider's atomic mutation guard. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
+Observed state is a weak owner-to-target map with three logical states: unseen, confirmed absent, or present at a version. A successful file read or mutation records presence; a `read`/`view` metadata miss records absence before returning `FS_NOT_FOUND`. The plugin performs no filesystem I/O: it converts that state into a provider guard. Presence supplies the observed version, while absence lets only a `createIfAbsent` write proceed; edit has no version basis and returns `FS_NOT_FOUND`. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 
@@ -55,7 +55,7 @@ Because the plugin influences the world only through events, removing it does no
 
 #### What the model sees
 
-This plugin adds no prompt or schema. It rejects an edit without a prior read with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`. Guarded mutations whose observed version is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper, which appends the recovery instruction to `FS_STALE_VERSION` (`— re-read the file, then retry`) and `FS_NOT_OBSERVED` (`— read the file, then retry`) messages while preserving the code; observation state is never shown.
+This plugin adds no prompt or schema. It rejects an edit without a prior observation with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`; editing a target just observed absent returns `FS_NOT_FOUND`. Guarded mutations whose positive observation is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper, which appends the recovery instruction to `FS_STALE_VERSION` (`— re-read the file, then retry`) and `FS_NOT_OBSERVED` (`— read the file, then retry`) messages while preserving the code. Following the stale remedy on an externally deleted target now records absence: the next guarded write may recreate it with `createIfAbsent`, while the provider atomically preserves any concurrent creator.
 
 #### Token effect
 
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index 2e38d63d8e..26e0199e6d 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**fs-policy 插件**：它在 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的策略层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的策略。
+**fs-policy 插件**：它记录观测到的存在或缺失状态，并在 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）之上增加编辑前读取和带防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的政策层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的政策。
 
 ```ts
 import type { Context } from 'cordis'
@@ -33,13 +33,13 @@ await ctx.plugin(FsPolicy)
 
 | 事件 | 本插件的监听器 |
 |---|---|
-| `fs/write-intent` | 先前未观察 → `{ kind: 'createIfAbsent' }`；先前已观察 → `{ kind: 'replaceIfVersion', version: vObserved }`。单槽决策；不调用 `next()`。 |
-| `fs/edit-intent` | 要求该所有者先前已观察，否则抛出 `FS_NOT_OBSERVED`；返回 `{ version: vObserved }` 作为 CAS 基础。单槽决策；不调用 `next()`。 |
-| `fs/observed` | 为该所有者与目标记录 `{ version }`。同步、只有副作用的 `WeakMap.set`。 |
+| `fs/write-intent` | 未见或已观测为缺失 → `{ kind: 'createIfAbsent' }`；已观测为存在 → `{ kind: 'replaceIfVersion', version: vObserved }`。单槽决策；不调用 `next()`。 |
+| `fs/edit-intent` | 未见 → `FS_NOT_OBSERVED`；已观测为缺失 → `FS_NOT_FOUND`；已观测为存在 → 返回 `{ version: vObserved }` 作为 CAS 基础。单槽决策；不调用 `next()`。 |
+| `fs/observed` | 为该所有者与目标记录 `{ kind: 'present', version }` 或 `{ kind: 'absent' }`。同步、只有副作用的 `WeakMap.set`。 |
 
 ## 已观察状态是先前观察记录；新鲜度由提供方 CAS 保证
 
-已观察状态是一张以所有者为弱键、记录各目标版本的映射表，每次读取或变更成功后都会更新；记录存在本身就是先前观察凭据。插件不执行文件系统 I/O：它把观察到的版本提供给提供方的原子变更防护。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
+观测状态是一张以所有者为弱键、记录各目标的映射表，具有三种逻辑状态：未见、确认缺失、存在于某个版本。成功读取文件或变更会记录存在；`read`/`view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前记录缺失。插件不执行文件系统 I/O：它把该状态转换为提供方防护。存在状态提供观测到的版本；缺失状态只允许 `createIfAbsent` 写入继续，edit 因没有版本基准而返回 `FS_NOT_FOUND`。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
 
 ## 单槽、先到者胜
 
@@ -55,7 +55,7 @@ await ctx.plugin(FsPolicy)
 
 #### 模型看到的内容
 
-该插件不添加提示词或 schema。编辑前未读取时，它会以代码 `FS_NOT_OBSERVED` 和精确消息 `edit requires reading "<path>" first` 拒绝。观察版本陈旧的防护变更会传播由提供方拥有的 `FS_STALE_VERSION` 错误。[`dsh-tool-fs`](../tool-fs/README.md)拥有面向模型的错误包装，会为 `FS_STALE_VERSION` 消息追加恢复指令（`— re-read the file, then retry`）、为 `FS_NOT_OBSERVED` 消息追加恢复指令（`— read the file, then retry`），同时保留错误码；观察状态绝不会显示。
+该插件不添加提示词或 schema。没有先前观测时，它会以代码 `FS_NOT_OBSERVED` 和精确消息 `edit requires reading "<path>" first` 拒绝编辑；编辑刚被观测为缺失的目标会返回 `FS_NOT_FOUND`。正向观测陈旧时，带防护的变更会传播由提供方拥有的 `FS_STALE_VERSION` 错误。[`dsh-tool-fs`](../tool-fs/README.md)拥有面向模型的错误包装，会为 `FS_STALE_VERSION` 消息追加恢复指令（`— re-read the file, then retry`）、为 `FS_NOT_OBSERVED` 消息追加恢复指令（`— read the file, then retry`），同时保留错误码。外部删除目标后，遵循陈旧恢复指令会记录缺失：下一次带防护的写入可以通过 `createIfAbsent` 重新创建该目标，而提供方会以原子方式保留任何并发创建者写入的文件。
 
 #### Token 影响
 
diff --git a/packages/fs/fs-policy/src/index.ts b/packages/fs/fs-policy/src/index.ts
index 3765a7e512..c7feb8c484 100644
--- a/packages/fs/fs-policy/src/index.ts
+++ b/packages/fs/fs-policy/src/index.ts
@@ -1,14 +1,15 @@
 /**
  * Event-only filesystem observation policy; it registers no service. A weak owner/target map
- * records every successful read or mutation, single-slot intent listeners supply that version,
- * and the provider performs the atomic freshness check. Without this plugin, tools retain the
- * bare provider's unconditional mutation behavior. See the package README for composition rules.
+ * records every authoritative presence/absence observation, single-slot intent listeners derive
+ * guards from that state, and the provider performs the atomic freshness/no-clobber check. Without
+ * this plugin, tools retain the bare provider's unconditional mutation behavior. See the package
+ * README for composition rules.
  * @module @deepseek-ai/dsh-fs-policy
  */
 
 import type { Context } from 'cordis'
 import { FsError } from '@deepseek-ai/dsh-fs'
-import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 import type { FsPolicyExec } from './types.ts'
 
 export type { FsPolicyExec } from './types.ts'
@@ -21,9 +22,10 @@ class ObservedStateGate {
   /**
    * Observed-file state, keyed first by the owner object (weakly held, so a
    * collected session frees its state), then by {@link FsTarget.targetKey}. An
-   * entry's PRESENCE is the prior-observation record.
+   * entry's presence is the prior-observation record; its discriminant keeps
+   * confirmed absence distinct from an unseen target.
    */
-  private observed = new WeakMap<object, Map<string, FsVersion>>()
+  private observed = new WeakMap<object, Map<string, FsObservation>>()
 
   /**
    * Derive the observed-state owner from the opaque event actor — normally the
@@ -38,17 +40,17 @@ class ObservedStateGate {
     return (actor as FsPolicyExec | undefined)?.agent?.session
   }
 
-  private get(owner: object, targetKey: string): FsVersion | undefined {
+  private get(owner: object, targetKey: string): FsObservation | undefined {
     return this.observed.get(owner)?.get(targetKey)
   }
 
-  private set(owner: object, targetKey: string, version: FsVersion): void {
+  private set(owner: object, targetKey: string, observation: FsObservation): void {
     let byTarget = this.observed.get(owner)
     if (!byTarget) {
       byTarget = new Map()
       this.observed.set(owner, byTarget)
     }
-    byTarget.set(targetKey, version)
+    byTarget.set(targetKey, observation)
   }
 
   /** Drop all recorded state (HMR safety / disposal). */
@@ -57,33 +59,38 @@ class ObservedStateGate {
   }
 
   /**
-   * Decide the write intent: no prior observation ⇒ `createIfAbsent` (only
-   * new files can be created blindly); a prior observation ⇒ `replaceIfVersion`
-   * at the observed version (existing files replaced only if unchanged).
+   * Decide the write intent: unseen or confirmed absent ⇒ `createIfAbsent`;
+   * confirmed present ⇒ `replaceIfVersion` at the observed version.
    */
   writeIntent(target: FsTarget, actor: object | undefined): FsWriteIntent {
     const owner = this.owner(actor)
     const prior = owner ? this.get(owner, target.targetKey) : undefined
-    return prior ? { kind: 'replaceIfVersion', version: prior } : { kind: 'createIfAbsent' }
+    return prior?.kind === 'present'
+      ? { kind: 'replaceIfVersion', version: prior.version }
+      : { kind: 'createIfAbsent' }
   }
 
   /**
-   * Decide the edit version guard: requires a prior observation by this owner
-   * (else `FS_NOT_OBSERVED`); returns the observed version as the CAS basis.
+   * Decide the edit version guard: unseen rejects with `FS_NOT_OBSERVED`,
+   * confirmed absence rejects with `FS_NOT_FOUND`, and presence supplies the
+   * observed version as the CAS basis.
    */
   editIntent(target: FsTarget, actor: object | undefined): { version: FsVersion } {
     const owner = this.owner(actor)
     const prior = owner ? this.get(owner, target.targetKey) : undefined
-    if (!owner || !prior) {
+    if (!owner || prior === undefined) {
       throw new FsError(`edit requires reading "${target.displayPath}" first`, 'FS_NOT_OBSERVED')
     }
-    return { version: prior }
+    if (prior.kind === 'absent') {
+      throw new FsError(`cannot edit "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    }
+    return { version: prior.version }
   }
 
-  /** Record a successful read/write/edit: this owner observed this target at this version. */
-  observe(target: FsTarget, version: FsVersion, actor: object | undefined): void {
+  /** Record an authoritative present or absent observation for this owner and target. */
+  observe(target: FsTarget, observation: FsObservation, actor: object | undefined): void {
     const owner = this.owner(actor)
-    if (owner) this.set(owner, target.targetKey, version)
+    if (owner) this.set(owner, target.targetKey, observation)
   }
 }
 
@@ -114,9 +121,10 @@ export function apply(ctx: Context): void {
   // fs/edit-intent: occupy the single decision slot — do not call next().
   ctx.on('fs/edit-intent', (target, actor) => Promise.resolve().then(() => gate.editIntent(target, actor)))
 
-  // fs/observed must remain synchronous and non-throwing: the mutation already succeeded, and
-  // emit does not await promises. WeakMap.set satisfies that contract.
-  ctx.on('fs/observed', (target, version, actor) => {
-    gate.observe(target, version, actor)
+  // fs/observed must remain synchronous and non-throwing: emit does not await
+  // promises, and successful mutations have already committed. WeakMap.set
+  // satisfies that contract for both presence and absence.
+  ctx.on('fs/observed', (target, observation, actor) => {
+    gate.observe(target, observation, actor)
   })
 }
diff --git a/packages/fs/fs-policy/tests/policy.spec.ts b/packages/fs/fs-policy/tests/policy.spec.ts
index 85c6ae0b52..2c977cc3be 100644
--- a/packages/fs/fs-policy/tests/policy.spec.ts
+++ b/packages/fs/fs-policy/tests/policy.spec.ts
@@ -3,7 +3,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
-import type { FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
 import type { FsPolicyExec } from '@deepseek-ai/dsh-fs-policy'
 
@@ -11,6 +11,8 @@ function target(path: string): FsTarget {
   return { targetKey: FsTargetKey(path), displayPath: path }
 }
 const ownerExec = (session: object): FsPolicyExec => ({ agent: { session } })
+const present = (version: string): FsObservation => ({ kind: 'present', version: FsVersion(version) })
+const absent: FsObservation = { kind: 'absent' }
 
 /** Dispatch the write-intent waterfall with the bare default thunk. */
 function writeIntent(ctx: Context, t: FsTarget, actor: object | undefined): Promise<FsWriteIntent | undefined> {
@@ -64,9 +66,16 @@ describe('write-intent decision', () => {
   it('an observed target decides replaceIfVersion at the observed version', async () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v7'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v7'), exec)
     expect(await writeIntent(ctx, target('a.txt'), exec)).toEqual({ kind: 'replaceIfVersion', version: 'v7' })
   })
+
+  it('a target observed absent decides createIfAbsent', async () => {
+    const { ctx } = await setup()
+    const exec = ownerExec({})
+    ctx.emit('fs/observed', target('a.txt'), absent, exec)
+    expect(await writeIntent(ctx, target('a.txt'), exec)).toEqual({ kind: 'createIfAbsent' })
+  })
 })
 
 describe('edit-intent decision', () => {
@@ -88,16 +97,23 @@ describe('edit-intent decision', () => {
   it('returns the observed version as the CAS basis after an observation', async () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v3'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v3'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v3' })
   })
+
+  it('rejects editing a target observed absent with FS_NOT_FOUND', async () => {
+    const { ctx } = await setup()
+    const exec = ownerExec({})
+    ctx.emit('fs/observed', target('a.txt'), absent, exec)
+    await expect(editIntent(ctx, target('a.txt'), exec)).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+  })
 })
 
 describe('observed-state is the prior-observation record', () => {
   it('a read observation authorizes an in-place write at that version', async () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), exec) // a read
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), exec) // a read
     expect(await writeIntent(ctx, target('a.txt'), exec)).toEqual({ kind: 'replaceIfVersion', version: 'v0' })
   })
 
@@ -105,19 +121,34 @@ describe('observed-state is the prior-observation record', () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
     // A create records v1; the follow-up edit guards against v1 with no read.
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v1'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v1'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v1' })
     // The edit records v2; a second edit guards against v2.
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v2'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v2'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v2' })
   })
 
   it('a no-owner observation records nothing', async () => {
     const { ctx } = await setup()
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), undefined)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), undefined)
     // Still unobserved for any owner.
     await expect(editIntent(ctx, target('a.txt'), ownerExec({}))).rejects.toMatchObject({ code: 'FS_NOT_OBSERVED' })
   })
+
+  it('supports present → absent → present transitions for one owner', async () => {
+    const { ctx } = await setup()
+    const exec = ownerExec({})
+    const a = target('a.txt')
+    ctx.emit('fs/observed', a, present('v1'), exec)
+    expect(await writeIntent(ctx, a, exec)).toEqual({ kind: 'replaceIfVersion', version: 'v1' })
+
+    ctx.emit('fs/observed', a, absent, exec)
+    expect(await writeIntent(ctx, a, exec)).toEqual({ kind: 'createIfAbsent' })
+    await expect(editIntent(ctx, a, exec)).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+
+    ctx.emit('fs/observed', a, present('v2'), exec)
+    expect(await editIntent(ctx, a, exec)).toEqual({ version: 'v2' })
+  })
 })
 
 describe('multi-owner isolation', () => {
@@ -125,7 +156,7 @@ describe('multi-owner isolation', () => {
     const { ctx } = await setup()
     const a = ownerExec({})
     const b = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), a)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), a)
     await expect(editIntent(ctx, target('a.txt'), b)).rejects.toMatchObject({ code: 'FS_NOT_OBSERVED' })
     expect(await editIntent(ctx, target('a.txt'), a)).toEqual({ version: 'v0' })
   })
@@ -134,7 +165,7 @@ describe('multi-owner isolation', () => {
     const { ctx } = await setup()
     const a = ownerExec({})
     const b = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), a) // A observed v0
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), a) // A observed v0
     // B never observed → createIfAbsent; A still holds v0 → replaceIfVersion.
     expect(await writeIntent(ctx, target('a.txt'), b)).toEqual({ kind: 'createIfAbsent' })
     expect(await writeIntent(ctx, target('a.txt'), a)).toEqual({ kind: 'replaceIfVersion', version: 'v0' })
@@ -164,7 +195,7 @@ describe('single-slot, first-wins', () => {
       return Promise.resolve(undefined)
     })
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), exec)
     await editIntent(ctx, target('a.txt'), exec)
     expect(secondRan).toBe(false)
   })
@@ -186,7 +217,7 @@ describe('disposal releases recorded state (HMR safety)', () => {
     const ctx = new Context()
     const exec = ownerExec({})
     const fiber = await ctx.plugin(FsPolicy)
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v0' })
     await fiber.dispose()
 
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index a77f4c8e04..dabdcacd3c 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: c7c978b7530a9b26e178f164dae61ae60f8f321f
-README.zh.md: 9761fc81bcb160edfc96d42cea45183abcfc087d
+README.md: 2b10614c8bf3d7e4a26c7f3d90dbc127cfec4336
+README.zh.md: e0cbf058bb8d6b52e8c8e5a048cc8b3d757e67d0
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index c7c978b753..2b10614c8b 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -30,14 +30,14 @@ A backend subclasses `FileSystem` and implements eleven primitives.
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
 | `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here); consumers that need a byte ceiling enforce it while consuming the stream. |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
-| `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
+| `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. `createIfAbsent` must perform a no-replace publication so a creator racing the initial probe is preserved. |
 | `editText(target, edit, expected?, signal?)` | Literal edit. `expected` is OPTIONAL: omit ⇒ unconditional edit of the current content; supply `{ version }` to guard (verified BEFORE matching). A missing target reports `FS_STALE_VERSION` either way. Applies and writes atomically — one mutation critical section. |
 
 The mutation runs inside the backend's per-target lock either way, so an unconditional write/edit is still atomic — "unconditional" drops the *version* precondition, not the atomicity.
 
 ## The `fs/*` policy events
 
-This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
+This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event carrying an `FsObservation` discriminated union: present with a version or confirmed absent. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
 ## A provider contract, not the policy layer
 
@@ -47,7 +47,7 @@ This package declares three events (see the generated region of [filesystem.md](
 
 ## Vocabulary
 
-`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsObservation` distinguishes `{ kind: 'present', version }` from `{ kind: 'absent' }`, so a policy can separate an unseen target from confirmed absence without performing I/O. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
 ## Model Experience
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 9761fc81bc..e0cbf058bb 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -30,14 +30,14 @@
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
-| `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
+| `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。`createIfAbsent` 必须以不替换的方式发布，使初始探测后抢先创建的文件得到保留。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
 ## `fs/*` 政策事件
 
-本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件，携带 `FsObservation` 可辨识联合：存在并带有版本，或确认缺失。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
 ## 提供方约定，不是政策层
 
@@ -47,7 +47,7 @@
 
 ## 词汇
 
-`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
+`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsObservation` 区分 `{ kind: 'present', version }` 与 `{ kind: 'absent' }`，使策略无需执行 I/O 即可分辨未见目标和确认缺失。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
 
 ## 模型体验
 
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index b4e3884c3b..0be94dccc4 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -16,6 +16,7 @@ import type {
   FsEditRequest,
   FsInfo,
   FsPathInfo,
+  FsObservation,
   FsTarget,
   FsVersion,
   FsWriteIntent,
@@ -33,6 +34,7 @@ export type {
   FsDirEntry,
   FsErrorCode,
   FsInfo,
+  FsObservation,
   FsPathInfo,
   FsTarget,
   FsWriteIntent,
@@ -63,14 +65,15 @@ declare module 'cordis' {
      */
     'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
     /**
-     * Record a successful observation. Listeners must be synchronous recorders:
-     * throws fail the tool call and returned promises are not awaited.
-     * @param target - the target that was read/written/edited.
-     * @param version - the version the actor now holds as its observation.
+     * Record an authoritative positive or negative observation. Listeners must
+     * be synchronous recorders: throws fail the tool call and returned promises
+     * are not awaited.
+     * @param target - the target whose presence or absence was observed.
+     * @param observation - present with its version, or confirmed absent.
      * @param actor - the observing tool-execution context; undefined records nothing useful.
      * @mode emit
      */
-    'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+    'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
   }
 }
 
@@ -198,7 +201,7 @@ export abstract class FileSystem extends Service {
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root this write
    *   runs under; a sandboxing backend fences the write by it, the bare backend
    *   ignores it. Omit to leave the backend its own default.
@@ -219,7 +222,7 @@ export abstract class FileSystem extends Service {
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root this edit runs
    *   under; a sandboxing backend fences the edit by it, the bare backend
    *   ignores it. Omit to leave the backend its own default.
diff --git a/packages/fs/fs/src/invariant.ts b/packages/fs/fs/src/invariant.ts
index 429c1cec41..62fec9a53c 100644
--- a/packages/fs/fs/src/invariant.ts
+++ b/packages/fs/fs/src/invariant.ts
@@ -2,7 +2,7 @@
 
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-import type { FsTarget, FsVersion } from './types.ts'
+import type { FsObservation, FsTarget } from './types.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-fs'
 
@@ -24,8 +24,17 @@ const install: InvariantInstaller = (ctx, fail) => {
       && eventName !== 'fs/edit-intent'
       && eventName !== 'fs/observed') return
     validateTarget(args[0] as FsTarget, fail)
-    if (eventName === 'fs/observed' && (args[1] as FsVersion).length === 0) {
-      fail('fs/observed version must be non-empty')
+    if (eventName === 'fs/observed') {
+      const observation = args[1] as FsObservation
+      switch (observation.kind) {
+        case 'present':
+          if (observation.version.length === 0) fail('fs/observed present version must be non-empty')
+          break
+        case 'absent':
+          break
+        default:
+          fail('fs/observed kind must be present or absent')
+      }
     }
   }, { global: true })
 }
diff --git a/packages/fs/fs/src/types.ts b/packages/fs/fs/src/types.ts
index 6a34f3848f..e842d0d574 100644
--- a/packages/fs/fs/src/types.ts
+++ b/packages/fs/fs/src/types.ts
@@ -44,6 +44,15 @@ export function FsVersion(v: string): FsVersion {
   return v as FsVersion
 }
 
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+export type FsObservation =
+  | { readonly kind: 'present'; readonly version: FsVersion }
+  | { readonly kind: 'absent' }
+
 /**
  * A path resolved by a backend into a stable identity. `resolve()` produces
  * this; every other operation takes it.
diff --git a/packages/fs/fs/tests/invariant.spec.ts b/packages/fs/fs/tests/invariant.spec.ts
index c160e3d238..eecdea8766 100644
--- a/packages/fs/fs/tests/invariant.spec.ts
+++ b/packages/fs/fs/tests/invariant.spec.ts
@@ -28,17 +28,28 @@ describe('filesystem invariants', () => {
       ctx as never, 'fs/edit-intent', target(), undefined,
       () => Promise.resolve(undefined),
     )).resolves.toBeUndefined()
-    expect(() => { ctx.emit('fs/observed', target(), FsVersion('v1'), undefined) }).not.toThrow()
+    expect(() => {
+      ctx.emit('fs/observed', target(), { kind: 'present', version: FsVersion('v1') }, undefined)
+    }).not.toThrow()
+    expect(() => { ctx.emit('fs/observed', target(), { kind: 'absent' }, undefined) }).not.toThrow()
     expect(() => { ctx.emit('tools/change') }).not.toThrow()
   })
 
   it('rejects empty target and version identities', async () => {
     const ctx = await setup()
-    expect(() => { ctx.emit('fs/observed', target(''), FsVersion('v1'), undefined) })
+    expect(() => {
+      ctx.emit('fs/observed', target(''), { kind: 'present', version: FsVersion('v1') }, undefined)
+    })
       .toThrow(/targetKey must be non-empty/)
-    expect(() => { ctx.emit('fs/observed', target('file:1', ''), FsVersion('v1'), undefined) })
+    expect(() => {
+      ctx.emit('fs/observed', target('file:1', ''), { kind: 'present', version: FsVersion('v1') }, undefined)
+    })
       .toThrow(/displayPath must be non-empty/)
-    expect(() => { ctx.emit('fs/observed', target(), FsVersion(''), undefined) })
-      .toThrow(/version must be non-empty/)
+    expect(() => {
+      ctx.emit('fs/observed', target(), { kind: 'present', version: FsVersion('') }, undefined)
+    }).toThrow(/present version must be non-empty/)
+    expect(() => {
+      ctx.emit('fs/observed', target(), { kind: 'unknown' } as never, undefined)
+    }).toThrow(/kind must be present or absent/)
   })
 })
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index f6f036b33c..a301417b4b 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: c9375a3ee803db48c547c7553d10f9b5ebde3fd2
-README.zh.md: 70ff15f2beff2674719f3084594e5cc0c7309f68
+README.md: 6878584b72c3e799ca8a46ddc6fc2908f9bc3acf
+README.zh.md: d8e92d96c60d30ec4aa943b77b882517324c4e52
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index c9375a3ee8..6878584b72 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -108,7 +108,7 @@ Prefix-stable while the visible tool definitions and order are unchanged. Regist
 
 #### What the model sees
 
-A successful read is exactly `<path><displayPath></path>`, newline, `<type>file</type>`, newline, `<content>`, numbered lines as `<lineNumber>: <text>`, a blank line, one footer, and `</content>`. The footer is exactly `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`, `(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)`, or `(End of file - total <total> lines)`. A long line ends exactly `... (line truncated to <max> chars)`.
+A successful read is exactly `<path><displayPath></path>`, newline, `<type>file</type>`, newline, `<content>`, numbered lines as `<lineNumber>: <text>`, a blank line, one footer, and `</content>`. The footer is exactly `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`, `(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)`, or `(End of file - total <total> lines)`. A long line ends exactly `... (line truncated to <max> chars)`. A missing read still returns `FS_NOT_FOUND`, but it records confirmed absence for the calling session; after an externally deleted file is re-read, a retried `write` can safely recreate it through the provider's no-replace guard.
 
 #### Token effect
 
@@ -136,7 +136,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` (including a missing edit target) gets `— re-read the file, then retry`, `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved.
+Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` gets `— re-read the file, then retry`, and `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved. After that reread confirms absence, edit reports `FS_NOT_FOUND` instead of repeating a stale remedy, while write uses guarded creation.
 
 #### Token effect
 
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 70ff15f2be..d8e92d96c6 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -108,7 +108,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-成功读取结果精确为 `<path><displayPath></path>`、换行、`<type>file</type>`、换行、`<content>`、形如 `<lineNumber>: <text>` 的编号行、一个空行、一条 footer 和 `</content>`。footer 精确为 `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`、`(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)` 或 `(End of file - total <total> lines)`。长行结尾精确为 `... (line truncated to <max> chars)`。
+成功读取结果精确为 `<path><displayPath></path>`、换行、`<type>file</type>`、换行、`<content>`、形如 `<lineNumber>: <text>` 的编号行、一个空行、一条 footer 和 `</content>`。footer 精确为 `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`、`(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)` 或 `(End of file - total <total> lines)`。长行结尾精确为 `... (line truncated to <max> chars)`。读取缺失目标仍返回 `FS_NOT_FOUND`，但会为调用会话记录确认缺失；外部删除的文件被重新读取后，重试的 `write` 可以通过提供方的不替换防护安全地重新创建该文件。
 
 #### Token 影响
 
@@ -136,7 +136,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION`（包括编辑目标缺失）追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。
+失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION` 追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。该次重新读取确认缺失后，edit 会报告 `FS_NOT_FOUND`，而不会重复陈旧恢复指令；write 则使用带防护的创建。
 
 #### Token 影响
 
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index fcd04cb17c..7b2c3ae596 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -137,8 +137,8 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
         // model-facing remedy; anything else passes through.
         throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
-      // Record the observed version (a no-op when no policy plugin listens).
-      ctx.emit('fs/observed', target, outcome.version, exec)
+      // Record the present observation (a no-op when no policy plugin listens).
+      ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
       return {
         path: target.displayPath,
         before: outcome.before,
diff --git a/packages/fs/tool-fs/src/read.ts b/packages/fs/tool-fs/src/read.ts
index a92fdcaad8..dc4f07e8fe 100644
--- a/packages/fs/tool-fs/src/read.ts
+++ b/packages/fs/tool-fs/src/read.ts
@@ -138,10 +138,13 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       const input = parseReadArgs(args, caps.limit)
       const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath))
 
-      // One stat: type check + size routing + the version recorded as observed.
+      // One stat: absence observation OR type check + size routing + present version.
       // A concurrent write can only make a later guarded mutation fail stale and require reread.
       const info = await ctx.fs.stat(target, exec.signal)
-      if (!info) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+      if (!info) {
+        ctx.emit('fs/observed', target, { kind: 'absent' }, exec)
+        throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+      }
       if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
 
       // Stream when the file is large OR size is unknown, so a size-less backend
@@ -161,10 +164,10 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
         lines: window.lines,
         totalLines: window.totalLines,
       }
-      // Record the observed version (a no-op when no policy plugin listens). The
+      // Record the present observation (a no-op when no policy plugin listens). The
       // read already succeeded; an fs/observed listener is contractually a
       // synchronous, side-effect-only recorder.
-      ctx.emit('fs/observed', target, info.version, exec)
+      ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, exec)
       return outcome
     },
     // Result-time display: a `read` card carrying the structured line window a
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index 56e2be488b..9a74dfc387 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -118,8 +118,8 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
         // model-facing remedy; anything else passes through.
         throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
-      // Record the observed version (a no-op when no policy plugin listens).
-      ctx.emit('fs/observed', target, outcome.version, exec)
+      // Record the present observation (a no-op when no policy plugin listens).
+      ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
       return {
         path: target.displayPath,
         operation: outcome.operation,
diff --git a/packages/fs/tool-fs/tests/integration.spec.ts b/packages/fs/tool-fs/tests/integration.spec.ts
index 3482b38569..d2a63e0a38 100644
--- a/packages/fs/tool-fs/tests/integration.spec.ts
+++ b/packages/fs/tool-fs/tests/integration.spec.ts
@@ -234,37 +234,33 @@ describe('default deployment (with dsh-fs-policy)', () => {
     })
   })
 
-  describe('deleted observed target (fail-closed corner)', () => {
-    it('a deleted observed file stays un-writable and un-editable in-session: the remedy cannot unblock it', async () => {
+  describe('deleted observed target', () => {
+    it('a failed reread records absence so write can safely recreate the file', async () => {
       await writeFile(join(dir, 'a.txt'), 'original')
       await call('read', { file_path: 'a.txt' })
       await rm(join(dir, 'a.txt')) // out-of-band deletion
 
-      // Edit of the missing target: stale (the missing-target path shares the
-      // stale code and the re-read remedy).
+      // The original positive observation still protects the first mutation.
       const edit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
       expect(edit.isError).toBe(true)
       expect(edit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
-
-      // Re-reading the missing file FAILS with FS_NOT_FOUND and records no
-      // observation, so the retried edit fails identically: the observed entry
-      // is never cleared for a deleted target.
-      const reread = await call('read', { file_path: 'a.txt' })
-      expect(reread.isError).toBe(true)
-      expect(reread.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
-      const retriedEdit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
-      expect(retriedEdit.isError).toBe(true)
-      expect(retriedEdit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
-
-      // Write cannot recreate it either: the stale observation still forces
-      // replaceIfVersion, which rejects a missing target ("file no longer exists").
-      const write = await call('write', { file_path: 'a.txt', content: 'fresh' })
+      const write = await call('write', { file_path: 'a.txt', content: 'premature' })
       expect(write.isError).toBe(true)
       expect(write.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
 
-      // The dead end lifts once the file exists again and is freshly observed.
-      await writeFile(join(dir, 'a.txt'), 'restored')
-      expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
+      // A read-not-found is an authoritative negative observation for this
+      // owner. It still fails as a read, but changes the next write guard.
+      const reread = await call('read', { file_path: 'a.txt' })
+      expect(reread.isError).toBe(true)
+      expect(reread.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+      // Absence never authorizes edit: there is no content/version to edit.
+      const retriedEdit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
+      expect(retriedEdit.isError).toBe(true)
+      expect(retriedEdit.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+      // The retried write uses createIfAbsent; the provider remains responsible
+      // for rejecting a concurrent creator at publication time.
       const recovered = await call('write', { file_path: 'a.txt', content: 'fresh' })
       expect(recovered.isError).toBe(false)
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('fresh')
@@ -294,6 +290,20 @@ describe('default deployment (with dsh-fs-policy)', () => {
       expect(statSpy).not.toHaveBeenCalled()
       statSpy.mockRestore()
     })
+
+    it('a missing read still stats once and its recovery write stats zero times', async () => {
+      const statSpy = vi.spyOn(ctx.fs, 'stat')
+      const missing = await call('read', { file_path: 'missing.txt' })
+      expect(missing.isError).toBe(true)
+      expect(missing.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+      expect(statSpy).toHaveBeenCalledTimes(1)
+
+      statSpy.mockClear()
+      const created = await call('write', { file_path: 'missing.txt', content: 'fresh' })
+      expect(created.isError).toBe(false)
+      expect(statSpy).not.toHaveBeenCalled()
+      statSpy.mockRestore()
+    })
   })
 })
 
@@ -482,7 +492,7 @@ describe('signal, concurrency, and the fs/observed contract', () => {
     expect((await callOwned('read', { file_path: 'a.txt' })).isError).toBe(false)
 
     // Reproduce an older concurrent read winning the observation race.
-    ctx.emit('fs/observed', target, firstInfo.version, { agent: { session } })
+    ctx.emit('fs/observed', target, { kind: 'present', version: firstInfo.version }, { agent: { session } })
 
     const edit = await callOwned('edit', {
       file_path: 'a.txt',
diff --git a/packages/fs/tool-str-replace-editor/README.i18n.yaml b/packages/fs/tool-str-replace-editor/README.i18n.yaml
index b6733eb3b8..fd61c07154 100644
--- a/packages/fs/tool-str-replace-editor/README.i18n.yaml
+++ b/packages/fs/tool-str-replace-editor/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/fs/tool-str-replace-editor/README.md
-README.md: 97e9e0ab9ade7c7241c1aac3e2489e055d01ff8f
-README.zh.md: a71f040f3b1383604fa1f151f797906dd343c49a
+README.md: 1d6ce6fd801997dd21973fde1ffded84dbee1b5a
+README.zh.md: 62728659fa8c8173ac42a42610f1a710aec6e386
diff --git a/packages/fs/tool-str-replace-editor/README.md b/packages/fs/tool-str-replace-editor/README.md
index 97e9e0ab9a..1d6ce6fd80 100644
--- a/packages/fs/tool-str-replace-editor/README.md
+++ b/packages/fs/tool-str-replace-editor/README.md
@@ -13,7 +13,7 @@ Standalone model-facing `str_replace_editor` over `ctx.fs`. It can be composed w
 
 ## Tool
 
-The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
+The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. A missing view records confirmed absence before returning `FS_NOT_FOUND`, so a later `create` can recover an externally deleted path through the mounted policy's guarded-create flow; absence never authorizes `str_replace` or `insert`. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
 
 ## Model Experience
 
diff --git a/packages/fs/tool-str-replace-editor/README.zh.md b/packages/fs/tool-str-replace-editor/README.zh.md
index a71f040f3b..62728659fa 100644
--- a/packages/fs/tool-str-replace-editor/README.zh.md
+++ b/packages/fs/tool-str-replace-editor/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 工具
 
-schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
+schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。查看缺失目标时，工具会在返回 `FS_NOT_FOUND` 前记录确认缺失，因此后续 `create` 可以通过已挂载策略的防护创建流程恢复外部删除的路径；缺失状态绝不会授权 `str_replace` 或 `insert`。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
 
 ## 模型体验
 
diff --git a/packages/fs/tool-str-replace-editor/src/index.ts b/packages/fs/tool-str-replace-editor/src/index.ts
index 6d0f65c48c..4b93c6d82c 100644
--- a/packages/fs/tool-str-replace-editor/src/index.ts
+++ b/packages/fs/tool-str-replace-editor/src/index.ts
@@ -105,6 +105,7 @@ async function statExisting(
 ): Promise<FsInfo> {
   const info = await ctx.fs.stat(target, exec.signal)
   if (info === undefined) {
+    ctx.emit('fs/observed', target, { kind: 'absent' }, exec)
     throw new FsError(
       `The path ${target.displayPath} does not exist. Please provide a valid path.`,
       'FS_NOT_FOUND',
@@ -231,7 +232,7 @@ async function viewPath(
     throw new FsError(`cannot view "${target.displayPath}": not a regular file or directory`, 'FS_NOT_REGULAR_FILE')
   }
   const content = await ctx.fs.readText(target, exec.signal)
-  ctx.emit('fs/observed', target, info.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, exec)
   return formatFileView(target.displayPath, content, maxOutputChars, viewRange)
 }
 
@@ -266,7 +267,7 @@ async function createFile(
   } catch (error: unknown) {
     throw policy.mapError(error, sandboxPolicy)
   }
-  ctx.emit('fs/observed', target, outcome.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
   return `New file created successfully at: ${target.displayPath}`
 }
 
@@ -317,7 +318,7 @@ async function replaceInFile(
   } catch (error: unknown) {
     throw policy.mapError(error, sandboxPolicy)
   }
-  ctx.emit('fs/observed', target, outcome.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
   return `The file ${target.displayPath} has been edited successfully.`
 }
 
@@ -359,7 +360,7 @@ async function insertInFile(
   } catch (error: unknown) {
     throw policy.mapError(error, sandboxPolicy)
   }
-  ctx.emit('fs/observed', target, outcome.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
   return `The file ${target.displayPath} has been edited successfully.`
 }
 
diff --git a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
index 01f15284de..db0fe8dc35 100644
--- a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
+++ b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
@@ -196,6 +196,35 @@ describe('tool-str-replace-editor', () => {
     expect(await readFile(sample, 'utf8')).toBe('one\nbetween\n\nthree\n')
   })
 
+  it('a failed view records absence so create can recover after external deletion', async () => {
+    const { ctx, root, owner } = await setup({}, { fsPolicy: true })
+    const sample = join(root, 'deleted.txt')
+    await writeFile(sample, 'original')
+    expect((await call(ctx, owner, { command: 'view', path: sample })).isError).toBe(false)
+    await rm(sample)
+
+    const missing = await call(ctx, owner, { command: 'view', path: sample })
+    expect(missing.isError).toBe(true)
+    expect(missing.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+    const edit = await call(ctx, owner, {
+      command: 'str_replace',
+      path: sample,
+      old_str: 'original',
+      new_str: 'edited',
+    })
+    expect(edit.isError).toBe(true)
+    expect(edit.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+    const created = await call(ctx, owner, {
+      command: 'create',
+      path: sample,
+      file_text: 'fresh',
+    })
+    expect(created.isError).toBe(false)
+    expect(await readFile(sample, 'utf8')).toBe('fresh')
+  })
+
   it('writes replacement text literally', async () => {
     const { ctx, root, owner } = await setup()
     const sample = join(root, 'literal.txt')
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index eb7f2a0eac..ef97c945c9 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -370,11 +370,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>',
-        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this write\n *   runs under; a sandboxing backend fences the write by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the write produced.\n */',
+        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before atomic publication takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this write\n *   runs under; a sandboxing backend fences the write by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the write produced.\n */',
       },
       {
         signature: 'abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>',
-        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this edit runs\n *   under; a sandboxing backend fences the edit by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the edit produced.\n */',
+        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before atomic publication takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this edit runs\n *   under; a sandboxing backend fences the edit by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the edit produced.\n */',
       },
     ],
   },
@@ -1425,9 +1425,9 @@ export const EVENT_API: readonly EventApiEntry[] = [
   {
     name: 'fs/observed',
     mode: 'emit',
-    signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void',
-    jsDoc: '/**\n * Record a successful observation. Listeners must be synchronous recorders:\n * throws fail the tool call and returned promises are not awaited.\n * @param target - the target that was read/written/edited.\n * @param version - the version the actor now holds as its observation.\n * @param actor - the observing tool-execution context; undefined records nothing useful.\n * @mode emit\n */',
-    summary: 'Record a successful observation.',
+    signature: '\'fs/observed\'(target: FsTarget, observation: FsObservation, actor: object | undefined): void',
+    jsDoc: '/**\n * Record an authoritative positive or negative observation. Listeners must\n * be synchronous recorders: throws fail the tool call and returned promises\n * are not awaited.\n * @param target - the target whose presence or absence was observed.\n * @param observation - present with its version, or confirmed absent.\n * @param actor - the observing tool-execution context; undefined records nothing useful.\n * @mode emit\n */',
+    summary: 'Record an authoritative positive or negative observation.',
   },
   {
     name: 'fs/write-intent',
diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts
index 71ed3be21d..02a3b4fc39 100644
--- a/packages/skill/skill-local/src/index.ts
+++ b/packages/skill/skill-local/src/index.ts
@@ -136,7 +136,7 @@ export function apply(ctx: Context, config: Config = {}): void {
   ctx.effect(function* () {
     yield async () => { await provider.dispose() }
   }, 'skill-local watcher')
-  ctx.on('fs/observed', (target, _version, actor) => {
+  ctx.on('fs/observed', (target, _observation, actor) => {
     if (mutationToolName(actor) === undefined) return
     provider.observeHostMutation(target.displayPath)
   })
diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts
index 75f4a4ed65..8bb08d2947 100644
--- a/packages/skill/skill-local/tests/skill-local.spec.ts
+++ b/packages/skill/skill-local/tests/skill-local.spec.ts
@@ -496,7 +496,7 @@ describe('LocalSkillProvider', () => {
     ctx.emit(
       'fs/observed',
       { targetKey: path as never, displayPath: path },
-      FsVersion('failed-read'),
+      { kind: 'present', version: FsVersion('failed-read') },
       { name: 'edit' },
     )
     expect(await ctx.skills.snapshot()).toEqual({ skills: [], complete: false })
@@ -526,7 +526,7 @@ describe('LocalSkillProvider', () => {
       ctx.emit(
         'fs/observed',
         { targetKey: path as never, displayPath: path },
-        FsVersion('entry-failure'),
+        { kind: 'present', version: FsVersion('entry-failure') },
         { name: 'write' },
       )
     }
@@ -674,7 +674,7 @@ describe('LocalSkillProvider', () => {
       ctx.emit(
         'fs/observed',
         { targetKey: displayPath as never, displayPath },
-        FsVersion('observed'),
+        { kind: 'present', version: FsVersion('observed') },
         actor,
       )
     }
@@ -689,7 +689,7 @@ describe('LocalSkillProvider', () => {
     ctx.emit(
       'fs/observed',
       { targetKey: path as never, displayPath: path },
-      FsVersion('observed'),
+      { kind: 'present', version: FsVersion('observed') },
       { name: 'edit' },
     )
 
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index de53d44755..fffde3ceb8 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -262,6 +262,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   FsEditOutcome: 'filesystem.md',
   FsEditRequest: 'filesystem.md',
   FsInfo: 'filesystem.md',
+  FsObservation: 'filesystem.md',
   FsPathInfo: 'filesystem.md',
   FsPolicyExec: 'filesystem.md',
   FsTarget: 'filesystem.md',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index a68ab874f0..cd1cb3c0c1 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -253,7 +253,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-str-replace-editor',
     source: 'packages/fs/tool-str-replace-editor/src/index.ts',
     requires: ['ctx.tools', 'ctx.fs'],
-    writes: ['tool/call', 'fs/observed after successful file operations', 'tool/result'],
+    writes: ['tool/call', 'fs/observed after view presence/absence or successful mutation', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(LocalFileSystem)
       await ctx.plugin(ToolStrReplaceEditor)
@@ -266,7 +266,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-fs',
     source: 'packages/fs/tool-fs/src/index.ts',
     requires: ['ctx.tools', 'ctx.fs', 'ctx.systemPrompt'],
-    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after successful file operations', 'tool/result'],
+    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after read presence/absence or successful mutation', 'tool/result'],
     async mount(ctx) {
       // The tool needs `fs`; the bare provider is sufficient because policy
       // changes behavior, not schema shape.
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 5f57b5167d..cd9d020779 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -960,6 +960,11 @@
       "symbol": "FsVersion",
       "source": "packages/fs/fs/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/filesystem.md",
+      "symbol": "FsObservation",
+      "source": "packages/fs/fs/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsInfo",

From 7132b9730eaf1468ed4a1df8c580a8c22cd3008a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:40:41 +0800
Subject: [PATCH 227/262] fix(fs): harden guarded-create publication

---
 ...9-filesystem-absence-observation.i18n.yaml |  4 +-
 ...26-08-09-filesystem-absence-observation.md |  8 +-
 ...08-09-filesystem-absence-observation.zh.md |  8 +-
 packages/e2b/fs-e2b/README.i18n.yaml          |  4 +-
 packages/e2b/fs-e2b/README.md                 |  2 +-
 packages/e2b/fs-e2b/README.zh.md              |  2 +-
 packages/e2b/fs-e2b/src/index.ts              |  2 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 27 ++++++-
 packages/fs/fs-local/README.i18n.yaml         |  4 +-
 packages/fs/fs-local/README.md                |  4 +-
 packages/fs/fs-local/README.zh.md             |  4 +-
 packages/fs/fs-local/src/fsio.ts              | 77 +++++++++++++++----
 packages/fs/fs-local/src/index.ts             |  2 +-
 packages/fs/fs-local/tests/filesystem.spec.ts | 35 +++++++++
 packages/fs/fs-local/tests/fsio.spec.ts       | 64 ++++++++++++++-
 15 files changed, 207 insertions(+), 40 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
index 39e50ffe6b..6fbd47fc65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.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 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
-2026-08-09-filesystem-absence-observation.md: e0c5c8b1845550ac6380ea4b2782cde13cba3ce9
-2026-08-09-filesystem-absence-observation.zh.md: 808698a7cb7a3575ef500dced7a646691d65c424
+2026-08-09-filesystem-absence-observation.md: e01719651f54cafc86a3972690507b1ee9b95cc9
+2026-08-09-filesystem-absence-observation.zh.md: 126f85e95b1debbccddf82fda432d31a69250388
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
index e0c5c8b184..e01719651f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
@@ -12,13 +12,13 @@ Treating a failed read as permission to create also exposes a second boundary. B
 
 ## Decision
 
-`dsh-fs` owns an explicit observation union: `{ kind: 'present', version: FsVersion } | { kind: 'absent' }`. The `fs/observed` event carries that union. Successful reads and mutations emit present; a `read` or `str_replace_editor view` metadata miss emits absent synchronously before returning `FS_NOT_FOUND`. Other read failures do not manufacture absence.
+`dsh-fs` owns an explicit observation union: `{ kind: 'present', version: FsVersion } | { kind: 'absent' }`. The `fs/observed` event carries that union. Successful reads and mutations emit present; a metadata miss from `read` or the `str_replace_editor` `view`, `str_replace`, or `insert` command emits absent synchronously before returning `FS_NOT_FOUND`. Other read failures do not manufacture absence.
 
 `dsh-fs-policy` stores three logical states per owner and target without injecting or calling `ctx.fs`: missing map entry is unseen, `absent` is confirmed absence, and `present(version)` is a replacement/edit basis. Write maps unseen and absent to the existing `createIfAbsent` intent and present to `replaceIfVersion`. Edit maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. A successful create or mutation replaces absence with its produced present version.
 
-Every provider must enforce `createIfAbsent` at the publication point, not only at its initial probe. `dsh-fs-local` stages and fsyncs in a private sibling directory, then hard-links the staged file to the destination; an existing destination makes the no-replace link fail and preserves the competitor. `dsh-fs-e2b` uses remote `ln` with an explicit created/existing result and derives the committed target version from metadata obtained before the non-cancellable commit. Replacements and bare unconditional writes retain their existing publication paths.
+Every provider must enforce `createIfAbsent` at the publication point, not only at its initial probe. `dsh-fs-local` stages and fsyncs in a private sibling directory, then hard-links the staged file to the destination; after a failed link it inspects the destination entry so a regular-file collision returns `FS_NOT_OBSERVED`, a non-regular entry returns `FS_NOT_REGULAR_FILE`, and a failure against a still-missing target returns `FS_IO_ERROR`. `dsh-fs-e2b` uses remote `ln -T` with an explicit created/existing result and derives the committed target version from metadata obtained before the non-cancellable commit. Replacements and bare unconditional writes retain their existing publication paths.
 
-This decision does not claim cross-process linearizability for `replaceIfVersion`: the provider version check and replacement remain protected only against writers represented by the provider's own lock and detectable metadata. The narrower guarantee is exact and sufficient for absence recovery: guarded creation never clobbers a target that appears before publication.
+This decision does not claim cross-process linearizability for `replaceIfVersion`: the provider version check and replacement remain protected only against writers represented by the provider's own lock and detectable metadata. The narrower guarantee is exact and sufficient for absence recovery: guarded creation never clobbers a target that appears before publication. Local guarded creation requires hard-link support; once any local publication succeeds, staging cleanup is best effort because private residue cannot make the committed write false.
 
 ## Alternatives considered
 
@@ -29,7 +29,7 @@ This decision does not claim cross-process linearizability for `replaceIfVersion
 
 ## Consequences
 
-The first mutation after an unobserved external deletion still fails `FS_STALE_VERSION`; the user or model must follow the existing reread remedy. That missing reread returns `FS_NOT_FOUND` while changing policy state, after which edit remains forbidden and write may recreate the path. If another writer wins the create race, the retry returns `FS_NOT_OBSERVED` and leaves the winner intact.
+The first mutation after an unobserved external deletion still fails `FS_STALE_VERSION`; the user or model must follow the existing reread remedy. That missing reread returns `FS_NOT_FOUND` while changing policy state, after which edit remains forbidden and write may recreate the path. If another writer wins the create race, the retry returns `FS_NOT_OBSERVED` and leaves the winner intact; a competing directory, special entry, or dangling symbolic link instead returns `FS_NOT_REGULAR_FILE` without prescribing another read.
 
 The observation payload is a package-owned event contract change, so every producer, listener, invariant, generated Cordis catalog, subsystem document, and both filesystem tool families move together. The policy keeps its one-stat read and zero-stat write/edit budget, owner isolation, disposal behavior, and optional deployment boundary from the [event-gate decision](../architecture/2026-06-26-file-context-as-event-gate.md).
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
index 808698a7cb..126f85e95b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 ## 决策
 
-`dsh-fs` 拥有一个显式观测联合类型：`{ kind: 'present', version: FsVersion } | { kind: 'absent' }`。`fs/observed` 事件携带该联合类型。成功的读取与变更发出存在观测；`read` 或 `str_replace_editor view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前同步发出缺失观测。其他读取失败不会产生缺失观测。
+`dsh-fs` 拥有一个显式观测联合类型：`{ kind: 'present', version: FsVersion } | { kind: 'absent' }`。`fs/observed` 事件携带该联合类型。成功的读取与变更发出存在观测；`read` 的元数据未命中，或 `str_replace_editor` 的 `view`、`str_replace`、`insert` 命令发生元数据未命中时，都会在返回 `FS_NOT_FOUND` 前同步发出缺失观测。其他读取失败不会产生缺失观测。
 
 `dsh-fs-policy` 按所有者与目标存储三种逻辑状态，既不注入也不调用 `ctx.fs`：映射中无条目即未见，`absent` 表示确认缺失，`present(version)` 是替换/编辑基准。写入把未见和缺失映射到现有 `createIfAbsent` 意图，把存在映射到 `replaceIfVersion`。编辑把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。成功创建或变更后，系统会用其产生的存在版本取代缺失状态。
 
-每个提供方都必须在发布点执行 `createIfAbsent`，不能只在初始探测时执行。`dsh-fs-local` 在私有同级目录中暂存并执行 fsync，再通过硬链接把暂存文件发布到目标位置；目标已存在时，不替换链接会失败，并保留竞争创建者写入的文件。`dsh-fs-e2b` 使用远程 `ln` 返回明确的已创建/已存在结果，并根据不可取消提交前取得的元数据推导已提交目标的版本。替换操作和裸无条件写入仍沿用现有发布路径。
+每个提供方都必须在发布点执行 `createIfAbsent`，不能只在初始探测时执行。`dsh-fs-local` 在私有同级目录中暂存并执行 fsync，再通过硬链接把暂存文件发布到目标位置；链接失败后，它会检查目标条目：与普通文件冲突时返回 `FS_NOT_OBSERVED`，条目非普通时返回 `FS_NOT_REGULAR_FILE`，目标仍然缺失时返回 `FS_IO_ERROR`。`dsh-fs-e2b` 使用远程 `ln -T` 返回明确的已创建/已存在结果，并根据不可取消提交前取得的元数据推导已提交目标的版本。替换操作和裸无条件写入仍沿用现有发布路径。
 
-本决策不宣称 `replaceIfVersion` 具有跨进程线性一致性：提供方的版本检查与替换仍只能防范被其自身锁纳入协调的写入方，以及能通过元数据检测到的写入方。更窄的保证边界准确且足以支持缺失恢复：带防护的创建绝不会覆盖在发布前出现的目标。
+本决策不宣称 `replaceIfVersion` 具有跨进程线性一致性：提供方的版本检查与替换仍只能防范被其自身锁纳入协调的写入方，以及能通过元数据检测到的写入方。更窄的保证边界准确且足以支持缺失恢复：带防护的创建绝不会覆盖在发布前出现的目标。本地带防护的创建要求支持硬链接；任何本地发布一旦成功，暂存清理便采用尽力而为语义，因为私有残留无法否定已提交写入的成功。
 
 ## 曾考虑的替代方案
 
@@ -29,7 +29,7 @@ Status: implemented
 
 ## 影响
 
-尚未观测到外部删除时，第一次变更仍以 `FS_STALE_VERSION` 失败；用户或模型必须遵循现有的重新读取恢复指令。该次针对缺失目标的重新读取会返回 `FS_NOT_FOUND` 并同时改变策略状态，此后 edit 仍被禁止，而 write 可以重新创建该路径。如果另一个写入方赢得创建竞态，本次重试会返回 `FS_NOT_OBSERVED`，并保留获胜方写入的文件。
+尚未观测到外部删除时，第一次变更仍以 `FS_STALE_VERSION` 失败；用户或模型必须遵循现有的重新读取恢复指令。该次针对缺失目标的重新读取会返回 `FS_NOT_FOUND` 并同时改变策略状态，此后 edit 仍被禁止，而 write 可以重新创建该路径。如果另一个写入方赢得创建竞态，本次重试会返回 `FS_NOT_OBSERVED`，并保留获胜方写入的文件；若竞态目标是目录、特殊条目或悬空符号链接，则改为返回 `FS_NOT_REGULAR_FILE`，且不会要求再次读取。
 
 观测载荷是由包拥有的事件约定变更，因此所有生产方、监听器、不变式、生成的 Cordis 目录、子系统文档以及两套文件系统工具都必须同步更新。策略保留[事件门禁决策](../architecture/2026-06-26-file-context-as-event-gate.md)确立的 read 一次 `stat`、write/edit 零次 `stat` 预算、所有者隔离、dispose 行为和可选部署边界。
 
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 4e29843fad..64460f7e87 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 039ad72a9651a1e8907c2c63b8c83d113aedbb4e
-README.zh.md: be97bbd92edb528f9560518398a0cb70f36b992b
+README.md: 1b66e84defb56cbfaa4a91d6ba6b48377fb52ca9
+README.zh.md: d9cd3ce1e109bf6b0b7fae02157d1ec6be51e575
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 039ad72a96..1b66e84def 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -9,7 +9,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, and preserve an existing file's POSIX mode. Replacements publish through E2B's same-filesystem atomic rename. A guarded `createIfAbsent` publishes with remote `ln` instead, making the commit atomically no-replace; metadata read from the staged file before that commit is projected to the target path for the returned version, so no fallible metadata request follows either commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, and preserve an existing file's POSIX mode. Replacements publish through E2B's same-filesystem atomic rename. A guarded `createIfAbsent` publishes with remote `ln -T` instead, making the commit atomically no-replace even when a directory appears at the destination; metadata read from the staged file before that commit is projected to the target path for the returned version, so no fallible metadata request follows either commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before publication. The signal is not forwarded into the rename or guarded-link commit, so cancellation cannot interrupt atomic publication or turn a committed write into a reported failure.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index be97bbd92e..d9cd3ce1e1 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -9,7 +9,7 @@
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，并保留现有文件的 POSIX mode。替换操作通过 E2B 的同一文件系统原子重命名发布。带防护的 `createIfAbsent` 改用远程 `ln` 发布，使提交具备原子且不替换的语义；系统会把提交前从暂存文件读取的元数据投影到目标路径，以生成返回的版本，因此任何一类提交点之后都不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，并保留现有文件的 POSIX mode。替换操作通过 E2B 的同一文件系统原子重命名发布。带防护的 `createIfAbsent` 改用远程 `ln -T` 发布，即使目标位置出现目录，也能使提交具备原子且不替换的语义；系统会把提交前从暂存文件读取的元数据投影到目标路径，以生成返回的版本，因此任何一类提交点之后都不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在发布前立即检查。信号不会传入 rename 或防护链接提交，因此取消无法中断原子发布，也不会把已提交的写入报告为失败。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 04b23a6775..b26338ffa4 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -489,7 +489,7 @@ export class E2BFileSystem extends FileSystem {
         assertNotAborted(signal, 'write')
         const targetArg = quoteE2BShellArg(targetPath)
         const publication = await sandbox.commands.run(
-          `if ln -- ${quoteE2BShellArg(temporary)} ${targetArg}; then printf created; elif test -e ${targetArg} || test -L ${targetArg}; then printf exists; else exit 1; fi`,
+          `if ln -T -- ${quoteE2BShellArg(temporary)} ${targetArg}; then printf created; elif test -e ${targetArg} || test -L ${targetArg}; then printf exists; else exit 1; fi`,
           commandOpts(undefined),
         )
         if (publication.stdout === 'exists') {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 973cf7c5c8..6ee3df6543 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -52,7 +52,10 @@ class FakeRemote {
   nextRemoveError: unknown
   canonicalOutput: string | undefined
   abortAfterRename: AbortController | undefined
-  competitorBeforeLink: { path: string; data: string } | undefined
+  competitorBeforeLink:
+    | { path: string; kind: 'file'; data: string }
+    | { path: string; kind: 'directory' }
+    | undefined
   guardedLinkOutput: string | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
@@ -257,7 +260,7 @@ class FakeRemote {
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
         const guardedLink = new RegExp(
-          "^if ln -- '([^']+)' '([^']+)'; then printf created; "
+          "^if ln -T -- '([^']+)' '([^']+)'; then printf created; "
           + "elif test -e '[^']+' \\|\\| test -L '[^']+'; then printf exists; else exit 1; fi$",
         ).exec(command)
         if (guardedLink !== null) {
@@ -269,7 +272,8 @@ class FakeRemote {
             return { exitCode: 0, stdout, stderr: '' }
           }
           if (this.competitorBeforeLink?.path === to) {
-            this.file(to, this.competitorBeforeLink.data)
+            if (this.competitorBeforeLink.kind === 'directory') this.dir(to)
+            else this.file(to, this.competitorBeforeLink.data)
             this.competitorBeforeLink = undefined
           }
           if (this.nodes.has(to)) return { exitCode: 0, stdout: 'exists', stderr: '' }
@@ -555,7 +559,7 @@ describe('E2BFileSystem atomic writes and edits', () => {
 
   it('preserves a competitor created after the guarded-create probe', async () => {
     const remote = new FakeRemote()
-    remote.competitorBeforeLink = { path: '/workspace/race.txt', data: 'competitor' }
+    remote.competitorBeforeLink = { path: '/workspace/race.txt', kind: 'file', data: 'competitor' }
     const { fs } = await setup(remote)
 
     await expectCode(
@@ -567,6 +571,21 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(remote.removals).toHaveLength(1)
   })
 
+  it('preserves a competing directory during guarded-create publication', async () => {
+    const remote = new FakeRemote()
+    remote.competitorBeforeLink = { path: '/workspace/race-dir', kind: 'directory' }
+    const { fs } = await setup(remote)
+
+    await expectCode(
+      fs.writeText(await fs.resolve('race-dir'), 'ours', { kind: 'createIfAbsent' }),
+      'FS_NOT_OBSERVED',
+    )
+    expect(remote.nodes.get('/workspace/race-dir')?.type).toBe(FileType.DIR)
+    expect(remote.nodes.has('/workspace/race-dir/content')).toBe(false)
+    expect(remote.links).toHaveLength(0)
+    expect(remote.removals).toHaveLength(1)
+  })
+
   it('rejects an invalid guarded-create publication response before claiming success', async () => {
     const remote = new FakeRemote()
     remote.guardedLinkOutput = 'unexpected'
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 6aaf691eef..ef76470394 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-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/fs/fs-local/README.md
-README.md: ac2f271ad9651797e1aceeba49e7a52533405f10
-README.zh.md: 633d55fe06b2261d9d5b52184987811c87c8f155
+README.md: 7b993fa123d13833313ecf3f78c64e466b960d5d
+README.zh.md: 428719137f988395b76513eab2c3f76ce4f331e5
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index ac2f271ad9..7b993fa123 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a regular file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`, while a non-regular path entry is preserved and rejected with `FS_NOT_REGULAR_FILE`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
@@ -40,3 +40,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
 - **The per-target mutation lock is in-process only** — guarded create still uses an atomic no-replace publication across processes, but replacement writers in another process are caught only when the optional version guard observes their metadata change; they are never serialized.
+- **Guarded creation requires hard-link support** — filesystems or mounts that reject hard-link publication cannot serve `createIfAbsent`; the provider preserves the missing target and reports `FS_IO_ERROR`.
+- **Post-commit cleanup is best effort** — a successful publication remains successful if removal of its owner-only staging directory fails, leaving private residue for later operator cleanup.
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 633d55fe06..428719137f 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
 - **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的普通文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；非普通路径条目也会被保留，并以 `FS_NOT_REGULAR_FILE` 拒绝；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
 - **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
 包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
@@ -40,3 +40,5 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
 - **每目标变更锁仅限进程内**：即使跨进程，带防护的创建仍采用原子且不替换的发布方式；但只有当可选版本防护观察到元数据变化时，系统才能发现其他进程中的替换写入方，且绝不会将其串行化。
+- **带防护的创建要求支持硬链接**：拒绝硬链接发布的文件系统或挂载点无法支持 `createIfAbsent`；提供方会使目标保持缺失状态并报告 `FS_IO_ERROR`。
+- **提交后清理采用尽力而为语义**：如果移除仅所有者可访问的暂存目录失败，成功发布仍视为成功，并留下私有残留供运维人员后续清理。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 071ad31637..24ad9b929f 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -91,6 +91,10 @@ export interface FsIoInternals {
   replaceFile?: (replaced: string, replacement: string) => Promise<void>
   /** Override the hard-link no-replace publication boundary. */
   linkFile?: (existingPath: string, newPath: string) => Promise<void>
+  /** Override target inspection after guarded publication fails. */
+  inspectPublicationTarget?: (path: string) => Promise<BigIntStats>
+  /** Override staging-directory removal for commit-point failure coverage. */
+  removeStagingDir?: (stagingDir: string) => Promise<void>
   /** Test hook after the temp file is written/synced but before final chmod+publication. */
   inspectTemp?: (paths: { stagingDir: string; tempPath: string }) => void | Promise<void>
 }
@@ -413,9 +417,13 @@ export async function* streamWholeText(target: LocalTarget, signal?: AbortSignal
 
 // --- Writing ---
 
-async function removeStagingDirOrThrow(stagingDir: string, originalError: unknown): Promise<never> {
+async function removeStagingDirOrThrow(
+  stagingDir: string,
+  originalError: unknown,
+  removeStagingDir: (path: string) => Promise<void>,
+): Promise<never> {
   try {
-    await rm(stagingDir, { recursive: true, force: true })
+    await removeStagingDir(stagingDir)
   } catch (cleanupError: unknown) {
     /* v8 ignore next 1 -- cleanup failure here needs a second filesystem fault after the primary write failure. */
     throw new FsError(`write failed (${errorMessage(originalError)}) and temp cleanup failed (${errorMessage(cleanupError)})`, 'FS_NOT_FOUND', { cause: originalError })
@@ -423,6 +431,43 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
   throw originalError
 }
 
+async function throwGuardedCreateFailure(
+  error: unknown,
+  absolutePath: string,
+  displayPath: string,
+  inspectPublicationTarget: (path: string) => Promise<BigIntStats>,
+): Promise<never> {
+  let existing: BigIntStats | undefined
+  try {
+    existing = await inspectPublicationTarget(absolutePath)
+  } catch (metadataError: unknown) {
+    if (!isENOENT(metadataError) && !isENOTDIR(metadataError)) {
+      throw new FsError(`cannot write "${displayPath}": ${errorMessage(metadataError)}`, 'FS_IO_ERROR', { cause: metadataError })
+    }
+  }
+
+  // Link errno values vary by platform and filesystem. Inspect the target entry
+  // after failure so a collision is not confused with missing hard-link support.
+  if (existing !== undefined) {
+    if (!existing.isFile()) {
+      throw new FsError(`cannot write "${displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE', { cause: error })
+    }
+    throw new FsError(
+      `cannot overwrite existing "${displayPath}" without reading it first`,
+      'FS_NOT_OBSERVED',
+      { cause: error },
+    )
+  }
+  if (isEEXIST(error)) {
+    throw new FsError(
+      `cannot overwrite existing "${displayPath}" without reading it first`,
+      'FS_NOT_OBSERVED',
+      { cause: error },
+    )
+  }
+  throw new FsError(`cannot write "${displayPath}": ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
+}
+
 /**
  * Atomically replace a file through a private, synced staging file in the same directory.
  * POSIX protects the staging directory and file with `0o700` and `0o600`. A new Windows file
@@ -434,8 +479,9 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * inert as a mode on Windows but identifies replacement security semantics.
  * @param signal - cancellation checked before final publication.
  * @param internals - Test hook for pinning temp names and observing the staged file.
- * @param createIfAbsent - publish with a hard-link no-replace primitive; a
- *   concurrent creator is preserved and rejected with `FS_NOT_OBSERVED`.
+ * @param createIfAbsent - when provided, publish with a hard-link no-replace
+ * primitive; a concurrent creator's file is preserved and this write is
+ * rejected with `FS_NOT_OBSERVED` using the supplied display path.
  */
 export async function writeFileAtomic(
   absolutePath: string,
@@ -443,7 +489,7 @@ export async function writeFileAtomic(
   mode: number | undefined,
   signal: AbortSignal | undefined,
   internals: FsIoInternals = {},
-  createIfAbsent = false,
+  createIfAbsent?: { displayPath: string },
 ): Promise<void> {
   throwIfAborted(signal, 'write')
   const directory = dirname(absolutePath)
@@ -458,6 +504,10 @@ export async function writeFileAtomic(
   const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32
   const replaceFile = internals.replaceFile ?? replaceFileWin32
   const linkFile = internals.linkFile ?? link
+  const inspectPublicationTarget = internals.inspectPublicationTarget
+    ?? (path => lstat(path, { bigint: true }))
+  const removeStagingDir = internals.removeStagingDir
+    ?? (path => rm(path, { recursive: true, force: true }))
   let handle: Awaited<ReturnType<typeof open>> | undefined
   let stagingCreated = false
   try {
@@ -478,16 +528,11 @@ export async function writeFileAtomic(
     handle = undefined
 
     throwIfAborted(signal, 'write')
-    if (createIfAbsent) {
+    if (createIfAbsent !== undefined) {
       try {
         await linkFile(tempPath, absolutePath)
       } catch (error: unknown) {
-        if (!isEEXIST(error)) throw error
-        throw new FsError(
-          `cannot overwrite existing "${absolutePath}" without reading it first`,
-          'FS_NOT_OBSERVED',
-          { cause: error },
-        )
+        await throwGuardedCreateFailure(error, absolutePath, createIfAbsent.displayPath, inspectPublicationTarget)
       }
     } else if (platform === 'win32' && mode !== undefined) {
       try {
@@ -501,7 +546,11 @@ export async function writeFileAtomic(
     } else {
       await rename(tempPath, absolutePath)
     }
-    await rm(stagingDir, { recursive: true, force: true })
+    try {
+      await removeStagingDir(stagingDir)
+    } catch (_committedStagingCleanupFailure) {
+      // The target is committed; owner-only staging residue cannot turn that write into a failure.
+    }
   } catch (error: unknown) {
     /* v8 ignore next -- abort-mid-write needs a writeFile/signal race; the non-abort (rename/open) side is tested. */
     let failure: unknown = isAbortError(error) ? new FsError('write aborted', 'FS_ABORTED') : error
@@ -514,7 +563,7 @@ export async function writeFileAtomic(
       }
     }
     if (!stagingCreated) throw failure
-    return removeStagingDirOrThrow(stagingDir, failure)
+    return removeStagingDirOrThrow(stagingDir, failure, removeStagingDir)
   }
 }
 
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 6be6a4402b..9cd4be41b8 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -173,7 +173,7 @@ export class LocalFileSystem extends FileSystem {
         existing?.mode,
         signal,
         this.internals,
-        expected?.kind === 'createIfAbsent',
+        expected?.kind === 'createIfAbsent' ? { displayPath: target.displayPath } : undefined,
       )
       const after = await probe(target.targetKey)
       return {
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 531be25360..f6736ff9c3 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -308,6 +308,41 @@ describe('writeText', () => {
     expect(await readFile(path, 'utf8')).toBe('competitor')
   })
 
+  it('reports a createIfAbsent race with the unresolved display path', async () => {
+    const realDirectory = join(dir, 'real-workspace')
+    const linkedDirectory = join(dir, 'linked-workspace')
+    await mkdir(realDirectory)
+    await symlink(realDirectory, linkedDirectory, process.platform === 'win32' ? 'junction' : 'dir')
+    const target = await fs.resolve('linked-workspace/a.txt')
+    fs.internals.inspectTemp = async () => { await writeFile(join(realDirectory, 'a.txt'), 'competitor') }
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' })).rejects.toMatchObject({
+      code: 'FS_NOT_OBSERVED',
+      message: `cannot overwrite existing "${join(linkedDirectory, 'a.txt')}" without reading it first`,
+    })
+    expect(await readFile(join(realDirectory, 'a.txt'), 'utf8')).toBe('competitor')
+  })
+
+  it('createIfAbsent rejects a competing directory as not a regular file', async () => {
+    const path = join(dir, 'a.txt')
+    const target = await fs.resolve('a.txt')
+    fs.internals.inspectTemp = async () => { await mkdir(path) }
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' }))
+      .rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    expect((await stat(path)).isDirectory()).toBe(true)
+  })
+
+  it('createIfAbsent rejects and preserves a dangling symbolic link', async () => {
+    const path = join(dir, 'dangling')
+    await symlink(join(dir, 'missing-target'), path)
+    const target = await fs.resolve('dangling')
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' }))
+      .rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
   it('replaceIfVersion replaces when the version matches', async () => {
     await writeFile(join(dir, 'a.txt'), 'old')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 9b62caba3f..13b0edc290 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -496,17 +496,77 @@ describe('writeFileAtomic — temp-file safety', () => {
     expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
   })
 
-  it('surfaces a non-collision guarded-create publication failure and cleans staging', async () => {
+  it('maps a non-collision guarded-create publication failure and cleans staging', async () => {
     const file = join(dir, 'a.txt')
     const denied = Object.assign(new Error('link denied'), { code: 'EACCES' })
 
     await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
       linkFile: async () => { throw denied },
-    }, true)).rejects.toBe(denied)
+    }, { displayPath: file })).rejects.toMatchObject({ code: 'FS_IO_ERROR', cause: denied })
     await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
     expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
   })
 
+  it('maps a guarded-create target-inspection failure and cleans staging', async () => {
+    const file = join(dir, 'a.txt')
+    const linkFailure = Object.assign(new Error('link failed'), { code: 'EIO' })
+    const inspectionFailure = Object.assign(new Error('inspection denied'), { code: 'EACCES' })
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      linkFile: async () => { throw linkFailure },
+      inspectPublicationTarget: async () => { throw inspectionFailure },
+    }, { displayPath: file })).rejects.toMatchObject({ code: 'FS_IO_ERROR', cause: inspectionFailure })
+    await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
+  it('rejects a guarded-create collision that vanishes before inspection', async () => {
+    const file = join(dir, 'a.txt')
+    const collision = Object.assign(new Error('target existed'), { code: 'EEXIST' })
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      linkFile: async () => { throw collision },
+    }, { displayPath: file })).rejects.toMatchObject({
+      code: 'FS_NOT_OBSERVED',
+      message: `cannot overwrite existing "${file}" without reading it first`,
+      cause: collision,
+    })
+    await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
+  it('uses the display path and target type when guarded publication finds a competitor', async () => {
+    const file = join(dir, 'a.txt')
+    const displayPath = join(dir, 'linked-workspace', 'a.txt')
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      inspectTemp: async () => { await writeFile(file, 'competitor') },
+    }, { displayPath })).rejects.toMatchObject({
+      code: 'FS_NOT_OBSERVED',
+      message: `cannot overwrite existing "${displayPath}" without reading it first`,
+    })
+    expect(await readFile(file, 'utf8')).toBe('competitor')
+
+    await rm(file)
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      inspectTemp: async () => { await mkdir(file) },
+    }, { displayPath })).rejects.toMatchObject({
+      code: 'FS_NOT_REGULAR_FILE',
+      message: `cannot write "${displayPath}": not a regular file`,
+    })
+    expect((await stat(file)).isDirectory()).toBe(true)
+  })
+
+  it('does not turn post-commit staging cleanup failure into a failed guarded write', async () => {
+    const file = join(dir, 'a.txt')
+    const cleanupFailure = new Error('staging cleanup failed')
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      removeStagingDir: async () => { throw cleanupFailure },
+    }, { displayPath: file })).resolves.toBeUndefined()
+    expect(await readFile(file, 'utf8')).toBe('ours')
+  })
+
   it.skipIf(!posixModes)('creates new files owner-only by default', async () => {
     const file = join(dir, 'a.txt')
     await writeFileAtomic(file, 'hello', undefined, undefined)

From 39d8678a02138cb27e0b9cc36b6670428dc2ee12 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:40:56 +0800
Subject: [PATCH 228/262] docs(fs): enumerate absence observation paths

---
 docs/subsystems/filesystem.i18n.yaml                 | 4 ++--
 docs/subsystems/filesystem.md                        | 2 +-
 docs/subsystems/filesystem.zh.md                     | 2 +-
 docs/tool-catalog.i18n.yaml                          | 4 ++--
 docs/tool-catalog.md                                 | 2 +-
 docs/tool-catalog.zh.md                              | 2 +-
 packages/fs/fs-policy/README.i18n.yaml               | 4 ++--
 packages/fs/fs-policy/README.md                      | 2 +-
 packages/fs/fs-policy/README.zh.md                   | 2 +-
 packages/fs/fs-sandbox/src/index.ts                  | 4 ++--
 packages/fs/tool-str-replace-editor/README.i18n.yaml | 4 ++--
 packages/fs/tool-str-replace-editor/README.md        | 2 +-
 packages/fs/tool-str-replace-editor/README.zh.md     | 2 +-
 scripts/gen-tool-catalog.ts                          | 2 +-
 14 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 04c08db9a6..f7d59cd66d 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 5d06611cbad2a3f146ddef4dbc96b2b6fc0a5b46
-filesystem.zh.md: 97aac2ee20783787909605d90a94181bf093d78a
+filesystem.md: dd81cc27ad73bab026cd11da6ab184890bb6535d
+filesystem.zh.md: 9589adfaf43c1d5a4bbc8571e70c878770d880b2
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 5d06611cba..dd81cc27ad 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -238,7 +238,7 @@ interface FileReadOutcome {
 
 ## Observed-file state (policy plugin)
 
-Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a tool read/view confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
+Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a `read` or `str_replace_editor` `view`, `str_replace`, or `insert` metadata miss confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
 
 ## Error taxonomy (provider contract)
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 97aac2ee20..9589adfaf4 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -238,7 +238,7 @@ interface FileReadOutcome {
 
 ## 已观测文件状态（策略插件）
 
-已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, FsObservation>>`。映射中没有条目表示未见；`{ kind: 'absent' }` 表示工具的 read/view 已确认缺失；`{ kind: 'present', version }` 表示 read、write 或 edit 观测到该版本。写入决策把未见和缺失映射到 `createIfAbsent`，把存在映射到 `replaceIfVersion`；编辑决策把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全），策略不执行任何文件系统 I/O。
+已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, FsObservation>>`。映射中没有条目表示未见；`{ kind: 'absent' }` 表示 `read` 的元数据未命中，或 `str_replace_editor` 的 `view`、`str_replace`、`insert` 命令发生元数据未命中，从而确认缺失；`{ kind: 'present', version }` 表示 read、write 或 edit 观测到该版本。写入决策把未见和缺失映射到 `createIfAbsent`，把存在映射到 `replaceIfVersion`；编辑决策把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全），策略不执行任何文件系统 I/O。
 
 ## 错误分类体系（提供方约定）
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 752a8f6a9e..1ae1b619f3 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: abcba1ca5dcb148aa0ee5578ff4fd0373993db1d
-tool-catalog.zh.md: 32c761d0d2854bf2310eb0ddb382553575bd4df9
+tool-catalog.md: f6a41da266db6eb2f347fb3c455a67b4dd44c4c0
+tool-catalog.zh.md: b36e8ccf63f4bdde7efca050bd92cbfcb03b3fbb
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index abcba1ca5d..f6a41da266 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -22,7 +22,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence, edit absence, or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after read presence/absence or successful mutation`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.subprocess`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 32c761d0d2..b36e8ccf63 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -24,7 +24,7 @@
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence, edit absence, or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
 | `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after read presence/absence or successful mutation`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index e316171061..65239a6f00 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: 0166690c66f38efe817d8b5779db9a677d22d321
-README.zh.md: 26e0199e6deb7fc12a860ab01884b70c1b7c9b38
+README.md: 395a36e89e113dc3846a8dff62ce90601013addd
+README.zh.md: 5b3b1f64de2d51f6b729392da2d4b459a9f0ca3b
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index 0166690c66..395a36e89e 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -39,7 +39,7 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a weak owner-to-target map with three logical states: unseen, confirmed absent, or present at a version. A successful file read or mutation records presence; a `read`/`view` metadata miss records absence before returning `FS_NOT_FOUND`. The plugin performs no filesystem I/O: it converts that state into a provider guard. Presence supplies the observed version, while absence lets only a `createIfAbsent` write proceed; edit has no version basis and returns `FS_NOT_FOUND`. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
+Observed state is a weak owner-to-target map with three logical states: unseen, confirmed absent, or present at a version. A successful file read or mutation records presence; a metadata miss from `read` or the `str_replace_editor` `view`, `str_replace`, or `insert` command records absence before returning `FS_NOT_FOUND`. The plugin performs no filesystem I/O: it converts that state into a provider guard. Presence supplies the observed version, while absence lets only a `createIfAbsent` write proceed; edit has no version basis and returns `FS_NOT_FOUND`. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index 26e0199e6d..5b3b1f64de 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -39,7 +39,7 @@ await ctx.plugin(FsPolicy)
 
 ## 已观察状态是先前观察记录；新鲜度由提供方 CAS 保证
 
-观测状态是一张以所有者为弱键、记录各目标的映射表，具有三种逻辑状态：未见、确认缺失、存在于某个版本。成功读取文件或变更会记录存在；`read`/`view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前记录缺失。插件不执行文件系统 I/O：它把该状态转换为提供方防护。存在状态提供观测到的版本；缺失状态只允许 `createIfAbsent` 写入继续，edit 因没有版本基准而返回 `FS_NOT_FOUND`。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
+观测状态是一张以所有者为弱键、记录各目标的映射表，具有三种逻辑状态：未见、确认缺失、存在于某个版本。成功读取文件或变更会记录存在；`read` 的元数据未命中，或 `str_replace_editor` 的 `view`、`str_replace`、`insert` 命令发生元数据未命中时，都会在返回 `FS_NOT_FOUND` 前记录缺失。插件不执行文件系统 I/O：它把该状态转换为提供方防护。存在状态提供观测到的版本；缺失状态只允许 `createIfAbsent` 写入继续，edit 因没有版本基准而返回 `FS_NOT_FOUND`。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
 
 ## 单槽、先到者胜
 
diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts
index 1d5f972da9..9884cc5fbd 100644
--- a/packages/fs/fs-sandbox/src/index.ts
+++ b/packages/fs/fs-sandbox/src/index.ts
@@ -76,7 +76,7 @@ export class SandboxedFileSystem extends LocalFileSystem {
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root; omit to use
    *   the deployment fallback.
    * @returns the write outcome from the inherited backend.
@@ -97,7 +97,7 @@ export class SandboxedFileSystem extends LocalFileSystem {
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root; omit to use
    *   the deployment fallback.
    * @returns the edit outcome from the inherited backend.
diff --git a/packages/fs/tool-str-replace-editor/README.i18n.yaml b/packages/fs/tool-str-replace-editor/README.i18n.yaml
index fd61c07154..d5f4b31574 100644
--- a/packages/fs/tool-str-replace-editor/README.i18n.yaml
+++ b/packages/fs/tool-str-replace-editor/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/fs/tool-str-replace-editor/README.md
-README.md: 1d6ce6fd801997dd21973fde1ffded84dbee1b5a
-README.zh.md: 62728659fa8c8173ac42a42610f1a710aec6e386
+README.md: 8b4772cc4eb40e23a5d6ea8e409188b5033318ba
+README.zh.md: b9ccf285870f2d02a2195b70dcd24fd37794976e
diff --git a/packages/fs/tool-str-replace-editor/README.md b/packages/fs/tool-str-replace-editor/README.md
index 1d6ce6fd80..8b4772cc4e 100644
--- a/packages/fs/tool-str-replace-editor/README.md
+++ b/packages/fs/tool-str-replace-editor/README.md
@@ -13,7 +13,7 @@ Standalone model-facing `str_replace_editor` over `ctx.fs`. It can be composed w
 
 ## Tool
 
-The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. A missing view records confirmed absence before returning `FS_NOT_FOUND`, so a later `create` can recover an externally deleted path through the mounted policy's guarded-create flow; absence never authorizes `str_replace` or `insert`. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
+The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. A metadata miss from `view`, `str_replace`, or `insert` records confirmed absence before returning `FS_NOT_FOUND`, so a later `create` can recover an externally deleted path through the mounted policy's guarded-create flow; absence never authorizes `str_replace` or `insert`. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
 
 ## Model Experience
 
diff --git a/packages/fs/tool-str-replace-editor/README.zh.md b/packages/fs/tool-str-replace-editor/README.zh.md
index 62728659fa..b9ccf28587 100644
--- a/packages/fs/tool-str-replace-editor/README.zh.md
+++ b/packages/fs/tool-str-replace-editor/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 工具
 
-schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。查看缺失目标时，工具会在返回 `FS_NOT_FOUND` 前记录确认缺失，因此后续 `create` 可以通过已挂载策略的防护创建流程恢复外部删除的路径；缺失状态绝不会授权 `str_replace` 或 `insert`。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
+schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。`view`、`str_replace` 或 `insert` 发生元数据未命中时，工具会在返回 `FS_NOT_FOUND` 前记录确认缺失，因此后续 `create` 可以通过已挂载策略的防护创建流程恢复外部删除的路径；缺失状态绝不会授权 `str_replace` 或 `insert`。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
 
 ## 模型体验
 
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index cd1cb3c0c1..1ed6c37f40 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -253,7 +253,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-str-replace-editor',
     source: 'packages/fs/tool-str-replace-editor/src/index.ts',
     requires: ['ctx.tools', 'ctx.fs'],
-    writes: ['tool/call', 'fs/observed after view presence/absence or successful mutation', 'tool/result'],
+    writes: ['tool/call', 'fs/observed after view presence/absence, edit absence, or successful mutation', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(LocalFileSystem)
       await ctx.plugin(ToolStrReplaceEditor)

From 9b686a420320b41c8a822535f8aae25c12de9967 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:01:44 +0800
Subject: [PATCH 229/262] ci(wine): bound Node distribution downloads

---
 ...8-08-native-windows-pull-request-ci.i18n.yaml |  4 ++--
 .../2026-08-08-native-windows-pull-request-ci.md |  2 +-
 ...26-08-08-native-windows-pull-request-ci.zh.md |  2 +-
 scripts/wine-windows-gates.sh                    | 16 ++++++++++++----
 4 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 75d7f8b670..19c54de94b 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 4e2ea07e90656f212f0613ffa17184ff2c3c8c45
-2026-08-08-native-windows-pull-request-ci.zh.md: 306243af3f3e0b280dd25caa5c99df2176590f3b
+2026-08-08-native-windows-pull-request-ci.md: a1f294b2b9e73a5d14a00780c7b0adfaf58e4702
+2026-08-08-native-windows-pull-request-ci.zh.md: 2c91c21118f5ebbd9f0e341f7d31ec71481db4dc
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 4e2ea07e90..a1f294b2b9 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -10,7 +10,7 @@ The required pull-request Windows verdict needs a fast win32 toolchain signal wi
 
 ## Decision
 
-The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that run the workspace build and production site. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries so a stalled download fails or recovers before consuming the job timeout. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
 
 Every pull request also starts an independent `windows-native` job named `windows node 24 / native complete` on GitHub's standard `windows-2025` image. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. The job is deliberately absent from `all-checks-passed.needs`: the aggregate neither waits for it nor changes conclusion because of it, while the native job retains its own unmasked success or failure result.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 306243af3f..2c91c21118 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试，使停滞的下载在耗尽作业超时前失败或恢复。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
 
 每个拉取请求还会在 GitHub 标准 `windows-2025` 镜像上启动一个独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。该作业被刻意排除在 `all-checks-passed.needs` 之外：聚合流程既不等待它，也不会因它改变结论；原生作业则保留自身未被掩盖的成功或失败结果。
 
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index 9bf904a767..d4798fdd7b 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -74,19 +74,27 @@ trap cleanup EXIT
 mkdir -p "$cache_dir" "$scratch/logs"
 
 # ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
+curl_download_args=(
+  --fail --silent --show-error --location
+  --retry 3 --retry-all-errors --retry-delay 2
+  --connect-timeout 10 --max-time 90 --retry-max-time 240
+)
+
 provision_node() {
   # Latest release of the primary line, checksum-verified against the same
-  # dist directory. Offline runs fall back to the newest cached zip, loudly.
+  # dist directory. Bound and retry every transfer so a stalled nodejs.org
+  # response cannot consume the entire CI job. Offline runs fall back to the
+  # newest cached zip, loudly.
   local version zip
-  version="$(curl -fsSL --max-time 30 https://nodejs.org/dist/index.json 2> /dev/null \
+  version="$(curl "${curl_download_args[@]}" https://nodejs.org/dist/index.json 2> /dev/null \
     | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
     || true)"
   if [ -n "$version" ]; then
     zip="$cache_dir/node-$version-win-x64.zip"
     if [ ! -f "$zip" ]; then
-      curl -fsSL -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
+      curl "${curl_download_args[@]}" -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
       local expected
-      expected="$(curl -fsSL "https://nodejs.org/dist/$version/SHASUMS256.txt" \
+      expected="$(curl "${curl_download_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
         | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
       [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
       verify_sha256 "$expected" "$zip.tmp"

From dc825be8d874df216d3fcc50bac36149c06568e6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:05:12 +0800
Subject: [PATCH 230/262] docs: design client conversation node assembly

---
 ...lient-conversation-node-assembly.i18n.yaml |   6 +
 ...08-09-client-conversation-node-assembly.md | 407 ++++++++++++++++++
 ...09-client-conversation-node-assembly.zh.md | 407 ++++++++++++++++++
 3 files changed, 820 insertions(+)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
new file mode 100644
index 0000000000..953a049744
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+2026-08-09-client-conversation-node-assembly.md: 0cee5449f651c568dbb87b9cb867eb77b6380184
+2026-08-09-client-conversation-node-assembly.zh.md: 146e8f68a9b1339934040cee62fd46e981145f2a
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
new file mode 100644
index 0000000000..0cee5449f6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -0,0 +1,407 @@
+# Agent Note: Client Conversation business-node assembly and keyed Chat snapshots
+
+Status: implemented
+
+English | [中文](2026-08-09-client-conversation-node-assembly.zh.md)
+
+## Problem
+
+Client Session owned transport windows, connection state, and pending interactions while also interpreting Assistant, Tool, message, command, compaction, retry, and turn-tail events in a centralized transcript fold. Adding one business node required changes to Session switches, history replay, indexes, caches, and React grouping; business identity, state evolution, and final presentation had no independent owner.
+
+The old path also placed running Assistant and Tool values outside the finalized flow. They entered the log-ordered node list only after settlement, so their React parent changed and remounted them even when the business ID and `key` remained stable. Full history loads, older prepends, live appends, and token streaming used separate update paths, leaving reference stability and local recomputation dependent on specialized caches spread across the client.
+
+Business events also use different correlation models. Tool has call IDs, Assistant correlates by turn and step, Compaction has its own lifecycle and checkpoint, and an Inbox splice represents one instantaneous state in a sequence. Keeping all these distinctions in one fold would make every business change pass through a global lookup and invalidate unrelated caches.
+
+## Decision
+
+Client Runtime provides a target-neutral Conversation Node assembly engine. Business plugins register Event Definitions, and view plugins register per-Session View Builders. `ui-conversation` registers the first built-in Definitions and the `chat` builder; Session only submits the current contiguous Event window to the engine and publishes its snapshot instead of interpreting individual conversation businesses.
+
+The complete derivation, business-by-business validation, and file-level implementation plan remain in [`business-node assembler version one`](../../../../docs/client-conversation-node-engine-rfc.md), [`follow-up design differences`](../../../../docs/client-conversation-node-engine-follow-up-differences.md), [`business-node and dual-view adaptation analysis`](../../../../docs/client-conversation-node-adaptation-analysis.md), and the [`Chat implementation design`](../../../../docs/client-conversation-node-chat-implementation-plan.md). Those design documents retain the full discussion; this Note fixes the responsibilities, algorithms, and trade-offs that remain relevant after implementation.
+
+### Responsibility layers
+
+| Layer | Durable responsibility | Explicitly does not own |
+|---|---|---|
+| Session | Maintain the contiguous Event window, distinguish replace, prepend, and append, and schedule snapshot notifications | Interpret Tool, Assistant, Compaction, or other business events |
+| Event Registry | Retain the unique-`kind` Definitions and sole fallback under Cordis lifecycles | Store one Session's Context or State |
+| Assembler | Match Events and maintain Contexts, Locations, dependencies, and the publication dirty set | Interpret business State fields or Chat ordering |
+| Node Definition | Define one business object's identity, State transitions, Location data, and target Node | Create Contexts, mutate another business's State, or scan all Contexts |
+| View Builder | Incrementally organize final target Nodes into that view's snapshot | Reinterpret raw Session Events |
+| React renderer | Render renderer-owned data by the final Node's `kind` and read business data from the current Node's Location | Pair business Events, scan global Nodes, or decide business lifecycle state |
+
+Registry contributions are Cordis effects. Removing a Definition causes a low-frequency registry rebuild for existing Sessions; ordinary business Events do not change the Registry or rebuild every business type.
+
+### Overall `ConversationNodeDefinition` contract
+
+Each [`ConversationNodeDefinition`](../../../../packages/client/runtime/src/client/contract/conversation.ts) independently owns one business object's conversion from Events to State and final view Nodes. A Definition's `kind` is its unique Registry name and the namespace for its business IDs.
+
+One Event may be claimed by several ordinary Definitions. For example, an Assistant Event updates both the Assistant Node and Turn Tail, while a Retry Event updates Retry, Assistant, and Turn Error. The Assembler asks the fallback only when every ordinary Definition returns `null`.
+
+A Definition holds no mutable business data across Sessions. Each Session's Assembler isolates that Session's Contexts, State, dependencies, and View Builders.
+
+#### `kind`, business ID, and Context key
+
+The `id` returned by `match()` only needs to be stable within its Definition. A Tool ID can be a call ID, an Assistant ID can be `turn:step`, and an Inbox ID can be the splice Event seq.
+
+The Assembler uses `conversationContextKey(kind, id)` to make a collision-free key. Definitions that return the same `id` still do not share a Context. The final view Node must retain this engine-owned key and cannot use `seq` or render position as identity.
+
+Each `(kind, id)` has at most one start Match. A second start fails immediately; a Definition must return a new ID to represent a new lifecycle.
+
+#### `match(event)`
+
+`match(event)` reads only the current raw `SessionEvent` and returns `{ id, role: 'start' | 'update' }` or `null`. It cannot access a Context, history, a Reader, a Location, or the view envelope.
+
+This restriction makes one Event's routing cost depend only on the number of registered Definitions. The Assembler never scans a Definition's historical Contexts to decide which one owns an update.
+
+Start, result, resource, checkpoint, and business-owned terminal Events must carry or directly imply the same ID. If one Event cannot yield that ID, its producer extends the Event protocol; the Client does not guess from the "nearest unfinished object."
+
+The `role` describes the State lifecycle, not visibility. A start may produce a terminal Node immediately, while an update may enter a pending Context before its start has loaded.
+
+#### `ConversationMatch`
+
+After a successful match, the Assembler combines the raw Event, optional wire presentation view, `role`, and engine-computed `location` into a read-only `ConversationMatch`.
+
+A Context's `matches` always remain in ascending Event `seq` order, not network arrival or pagination ingestion order. If a tail page supplies a result before an older page supplies its call, the final Match order still places the call before the result.
+
+Location can change when prepend fills a boundary or append closes one. The Assembler replaces the affected Matches' read-only Locations and replays the Context; business code does not retain an old Location copy as authority.
+
+#### `ConversationNodeContext`
+
+| Field | Owner | Semantics visible to the Definition |
+|---|---|---|
+| `key` | Assembler | Stable final identity derived from `kind + id` |
+| `kind` / `id` | Definition + Assembler | Current business namespace and business ID |
+| `matches` | Assembler | Complete business evidence loaded in the current window and sorted by `seq` |
+| `start` | Assembler | Unique start Match, or `undefined` before it loads |
+| `state` | Returned by Definition, held by Assembler | Most recent `start`/`update` return value, or `undefined` before initialization |
+| `current` | Assembler | Most recently materialized Node or `null` for each target |
+
+Read-only Context fields do not require deeply immutable business State. A Definition may return a new object or mutate the old object in place and return the same reference.
+
+The Assembler adopts only the returned value. Returning `undefined` from `start()` or `update()` is a contract error and fails immediately; mutating an object without returning it is likewise invalid.
+
+A Definition may inspect all `matches` to help construct State or a fallback Node, but it cannot add or remove Matches, replace Context fields, or mutate another Context.
+
+#### `start(context, match, reader)`
+
+`start()` is the sole State initialization entry point. The Assembler invokes it when the unique start first appears and adopts its returned State.
+
+When an older page changes Match order, the Reader's predecessor answer, or Location facts, the Assembler recomputes from `start()` instead of applying a reverse-direction patch to old State.
+
+The Context may already contain updates after the start when `start()` runs. After `start()` returns initial State, the Assembler still invokes `update()` for every post-start Match in ascending log order, so ingestion direction cannot change the final fold.
+
+The `reader` is available only in `start()`. Initialization can read the nearest active Context of a specified `kind` strictly before the current start seq, but business code receives no general interface for scanning internal engine Maps.
+
+Each new `start()` invocation replaces the Reader dependencies recorded by the prior invocation, so a Definition that changes its query branch retains no stale edges.
+
+#### `reader.previous(kind)`
+
+`reader.previous(kind)` finds the nearest Context whose `candidate.startSeq < current.startSeq` and whose State is initialized. It never returns a Context at the same seq, a future Context, or a pending Context without State.
+
+The result contains the predecessor's key, kind, ID, start seq, read-only State, and Matches. The consumer interprets that State itself; the provider only maintains its State correctly and need not register a specialized query method.
+
+Each Reader query records a `{ key, revision, windowGap }` dependency. A matched predecessor's revision change replays the consumer; a miss while older history remains records a window gap for a later prepend.
+
+When the window already reaches the Session beginning, a miss is a definitive `undefined`. When `hasMore` is true, the Definition sees the same `undefined`, but the Assembler remembers that the result is provisional.
+
+Dependencies point strictly from earlier starts to later starts, so transitive replay cannot form a temporal cycle. Both the Inbox instantaneous-state chain and Message reads of Inbox use this constraint.
+
+#### `update(context, match)`
+
+`update()` handles a post-start Match that `match()` has already routed exactly to the current `(kind, id)`. It does not decide which Context owns the Event.
+
+The Assembler invokes `update()` in ascending `seq` order. A live tail update can apply incrementally; any non-tail insertion, newly loaded start, or invalidated dependency causes a complete replay from `start()`.
+
+When no business data changes, `update()` returns the existing State. When data changes, it may return an immutable replacement or mutate the existing object and return that object.
+
+The Assembler does not use State reference equality to decide publication or propagation. Every accepted update increments the Context revision, marks it dirty, and causes direct or transitive Reader consumers to be reevaluated.
+
+#### `publication(match)`
+
+`publication()` controls when the latest State materializes as a view Node; it does not delay the synchronous execution of `match()`, `start()`, or `update()`.
+
+| Return value | Behavior |
+|---|---|
+| `immediate` | Request a notification and flush in the current microtask |
+| `animation-frame` | Coalesce high-frequency updates into materialization on the next frame |
+| `none` | Do not schedule a flush for this Match; retain its State and dirty marker |
+
+Omitting `publication()` means `immediate`. Assistant token deltas use `animation-frame`, invisible Inbox Contexts use `none`, and finals, dependency replays, and Location boundaries publish the latest result through an immediate path.
+
+Every delta within a frame still executes update. Only `buildViewNode()`, View Builder work, and React snapshot notification are coalesced; no tokens are lost.
+
+#### `buildLocationData(context, scope)`
+
+`buildLocationData()` lets a Definition publish a read-only value derived from its State onto an engine-owned Step or Turn without exposing another business's mutable State. The Assembler always materializes `step` before `turn`, so Turn-level aggregation can read Step data updated in the same flush; it calls `buildViewNode()` only after all Location data is ready.
+
+A Definition receives the `step` and `turn` scopes separately and may return one value or `null` in either phase. A value must identify the exact turn/step coordinates and use the Definition's `kind` as its key. The Assembler owns replacement and removal and rejects another Context that claims the same Location key.
+
+`ConversationStepDataMap` and `ConversationTurnDataMap` use declaration merging to constrain keys and values. A Location exposes only a stable `data.get(key)` reader; consumers cannot obtain the provider Context or mutate its State.
+
+#### `buildViewNode(context, target)`
+
+`buildViewNode()` reads the latest Context during publication and directly produces the final business Node for the named target. The Assembler adds no generic activity, tail-candidate, or layout business layer afterward.
+
+`null` means this Context has not yet materialized for the target. On the ordinary incremental path, a Context that has returned a non-null Node cannot later return `null`; temporary absence retains the same-key Node and uses the target's visibility representation.
+
+The Assembler verifies `node.key === context.key` and `node.target === target`. Business code may change `anchorSeq`, data, Location, or visibility, but cannot change identity within one lifecycle.
+
+`current` lets a Definition distinguish "never materialized" from "already materialized and now hidden." Assistant retry and Turn Error suppression use it to avoid illegal Node withdrawal.
+
+A Definition may branch by target to construct different data, while matching, Context identity, and State remain target-neutral. This change registers only the `chat` builder; Trajectory continues to consume the compatibility slice.
+
+#### No generic `end()`
+
+The engine exposes no fixed `end()` lifecycle. A single-Event business completes in `start()`, a multi-Event business records completion in its own update, and a long-lived instantaneous-state business creates a new Context for every Event.
+
+Step and Turn closure are external Location facts and do not mutate business State. A boundary change replays and builds affected Contexts; each business combines its own completion State with whether its Location is closed to produce normal, running, or interrupted presentation.
+
+IDs are never reused. Completed Contexts remain in the current window, providing stable render identity and possible predecessor evidence for later Readers.
+
+### Location is a first-class engine fact
+
+[`ConversationLocationIndex`](../../../../packages/client/runtime/src/client/sessions/conversation-location-index.ts) maps Events to Locations from `turn/start`, `step/start`, explicit turn and step payloads, `step/end`, and `turn/end`.
+
+Location has four shapes: `session`, `turn`, `step`, and `unresolved`. Turns and Steps each carry `open`, `closed`, or `unknown` status plus any loaded start and end Events.
+
+Each Turn and Step also carries a reference-stable Location data store. A Definition update replaces only its owned key; the same store identity can acquire new values through append or prepend, allowing Contexts, View Builders, and React renderers to share resolved hierarchy-level business facts without copying or scanning the global Node array.
+
+`unresolved` means the current history window lacks sufficient preceding boundaries; it does not mean session-level. When older prepend supplies those boundaries, the index corrects Match Locations and replays only Contexts that own those seqs.
+
+An appended ordinary Event only inherits current coordinates, while an appended boundary recalculates only its owning Turn. Prepend rebuilds Location facts from the expanded contiguous window, but reference-stability logic retains unchanged Turn and Step objects.
+
+The Assembler also passes a reference-stable timeline to each View Builder. Businesses do not separately maintain turn order, step lists, last-step values, or boundary Maps.
+
+## Three Event-window paths
+
+"Backward history scanning" describes the UI loading pages from the newest tail toward the Session beginning; it does not mean a Definition executes `update()` in reverse. Regardless of history API order or page-loading direction, the Assembler canonicalizes each current window and each fresh page in ascending `seq` order.
+
+| Scenario | Input range | Context and State handling | View Builder |
+|---|---|---|---|
+| Initial history tail or resync | Current complete contiguous window | Clear and rebuild all Contexts in ascending `seq` order | `replace()` |
+| Load one older-history page | Only deduplicated fresh Events before the window | Retain existing Context identity, then add Matches, Locations, dependencies, and local replays | `apply(upserts)` |
+| Live append | One contiguous tail Event | Match Definitions and update only the exact IDs; boundaries affect only their owning Turn | `apply(upserts)` |
+
+### Initial history tail and logical backward scanning
+
+1. `Session.open()` loads the latest tail page and passes its contiguous History Entries to `replaceWindow(entries, hasMore)`.
+2. `replaceWindow` clears old Contexts, start-seq indexes, seq reverse indexes, Reader dependencies, and the input Map.
+3. It sorts every entry by Event `seq` and stores the resulting current window.
+4. LocationIndex rebuilds Turn and Step facts for that window.
+5. The Assembler visits Events in ascending order and invokes every ordinary Definition's `match(event)`.
+6. Each result gets or creates its `(kind, id)` Context and enters that Context's ordered Match array.
+7. A start runs `start()`; a tail update on initialized State runs `update()` directly.
+8. If the page contains only a result or resource and omits its start, the ID still creates a Context and collects Matches, while State remains `undefined`.
+9. After matching all Events, the Assembler rechecks Reader dependencies so earlier instantaneous states in the same window stabilize before later consumers read them.
+10. Every Context becomes dirty, and the next flush fully rebuilds Location data in Step→Turn order before invoking `buildViewNode()` for every target.
+11. Some businesses return `null` without a start; Compaction, Command, Tool result, and Turn Error can construct fallback Nodes from sufficient update evidence.
+12. Each View Builder receives the complete Node set and timeline and establishes the initial snapshot through `replace()`.
+
+This path starts from the newest page only at the pagination layer. State within the page always computes forward, so the same window does not produce different business results under a different scan direction.
+
+A Context without a start is not an error. It is a pending aggregation container waiting for an older page; that Definition's `buildViewNode()` decides whether the evidence already makes it visible.
+
+If an update with the same ID is genuinely earlier than the start in log order, rather than merely loaded first, replay fails with a protocol error after the start arrives. Arrival order may be reversed; business log order may not.
+
+### Prepending a newly loaded older page
+
+1. `Session.loadOlder()` requests the immediately preceding page using the current `baseSeq` and first verifies continuity between the page tail and current window.
+2. Session prepends the raw Event and view arrays to its own window and passes only that page to `assembler.prepend(entries, hasMore)`.
+3. The Assembler removes seqs that overlap the current window, then sorts the fresh page internally in ascending order.
+4. Existing Contexts, State, current Nodes, and View Builder instances remain intact.
+5. LocationIndex rebuilds facts over the expanded complete input and reports seqs whose Location identity actually changed.
+6. Contexts owning those seqs update their Match Locations and replay from start; unrelated Contexts do not join Location replay.
+7. Fresh Events run Definition matchers and enter existing or new Contexts by stable ID.
+8. If the new page supplies a pending Context's start, that Context initializes from the start and then applies every already-collected update in ascending order.
+9. If the page establishes a nearer Reader predecessor, changes a predecessor revision, or removes a window gap, the consumer recomputes from `start()`.
+10. Reader dependencies propagate replay toward later start seqs; no Event is applied in reverse within the propagation batch.
+11. An empty page that changes `hasMore` from true to false also rechecks dependencies and resolves a provisional `undefined` to definitive absence.
+12. The flush republishes Step/Turn Location data and target Nodes only for dirty Contexts, then passes non-null results to View Builder `apply()` as `upserts`.
+
+Prepend retains existing Context keys and current Node identity. A page may add historical keys at the front of Chat `order` or correct an existing Node's anchor, Location, visibility, or data, but it does not recreate unrelated business Contexts.
+
+On a structural change, the Chat Builder recomputes visible `order` and the secondary Location index from its keyed store. That is view-index work; it neither reruns every business Definition nor replaces unchanged Node values.
+
+Reader gap repair is the largest algorithmic difference between prepend and ordinary append. A page can both add visible historical Nodes and change later Inbox instantaneous states and the Message classifications that depend on them.
+
+### Forward live append
+
+1. Session accepts only a live Event immediately after the current tail seq; it deduplicates overlap and runs tail-page repair before accepting a gap.
+2. A non-boundary Event enters the current Turn and Step coordinates incrementally; a boundary Event updates Location facts for its owning Turn.
+3. The Assembler invokes `match()` once on every ordinary Definition for this Event and scans no Definition's Context set.
+4. Each successful result directly locates one Context through `(kind, id)`.
+5. A new ID creates a Context; a normal tail update for an existing ID invokes `update()` once.
+6. A start or any evidence inserted before the tail uses complete `replayContext()` and retains the same forward-order semantics.
+7. After a Context revision changes, only recorded Reader dependents replay.
+8. Location close updates affected Matches within its owning Turn and replays those Contexts, allowing unfinished Assistant, Tool, or Retry values to acquire interrupted or cancelled presentation.
+9. The Assembler takes the highest publication urgency among all matching Definitions: `immediate` outranks `animation-frame`, which outranks `none`.
+10. Session routes immediate work to the microtask notifier and animation-frame work to the RAF notifier.
+11. The flush updates Step/Turn Location data for dirty Contexts, then invokes `buildViewNode()` and passes this transaction's upserts and latest timeline to each View Builder.
+12. The new React snapshot reuses stable Context keys; the same Tool running→settled or Assistant streaming→final value never moves across parents.
+
+Append's business-matching cost is the Definition count plus the Contexts actually updated, independent of historical Context count. Reader consumers and Location closure add replay proportional to real dependencies or the owning Turn.
+
+A structural Chat `order` change can still reorder the current visible keys. A data-only update replaces one keyed-store Node and touches its Location index. The guarantee is that unrelated businesses do not refold and unchanged Node identity is retained, not that every view-index operation has constant complexity.
+
+### Consistency across replace, prepend, and append
+
+All three paths preserve the same invariants: Context Matches are seq-ordered, State folds forward from one unique start, Reader sees only strictly preceding active Contexts, Location data publishes in Step→Turn order, and Node key depends only on kind and ID.
+
+`replaceWindow` is the low-frequency complete replacement for initial open, resync, gap repair, and registry changes; it does not implement ordinary load older. Both `prepend` and `append` retain existing Builder and Context identity.
+
+Page size, the number of history loads, and RAF coalescing affect only when evidence arrives or publishes. They do not change final Context State and Nodes for an equal Event window.
+
+## How built-in businesses use Definitions
+
+### Matching, ID, and State
+
+| Business / `kind` | Stable ID | Start Match | Update Matches | State and cross-Context reads |
+|---|---|---|---|---|
+| Next-turn Inbox / `inbox-next-turn` | Splice Event seq | Each `agent/inbox/spliced` targeting next-turn | None | Apply the current splice to the pending/claimed instantaneous state from `reader.previous(ownKind)` |
+| Next-step Inbox / `inbox-next-step` | Splice Event seq | Each `agent/inbox/spliced` targeting next-step | None | Build the same per-instruction instantaneous state; Message reads its claimed set |
+| Message / `input-message` | Message ID | Append-surface `user/message` | None | Use source for a context message, or read the nearest next-step Inbox to distinguish user from steering |
+| Assistant / `assistant-step` | `turn:step` | `step/start` | `assistant/chunk`, final `assistant/message`, and same-step Retry | Aggregate blocks, usage, first-token time, final evidence, and retry-hidden state, then publish same-key Step data |
+| Tool / `tool-call` | Root call ID | Root `tool/call` | Root result and Code Dispatch start/result | Aggregate the root, children, and parent Map; Dispatch Events route exactly through `rootCallId` |
+| Command / `command` | Command ID | `command/run` | `command/done` and compact lifecycle/checkpoint Events carrying a source command ID | Aggregate command outcome and manual-compaction evidence |
+| Automatic Compaction / `compaction` | Compaction ID | `compact/start` without a source command ID | Summary, end, and replacement checkpoint | Aggregate summary/checkpoint; sufficient checkpoint evidence supports fallback without a start |
+| Retry / `model-retry` | Retry ID | Attempt 1 `llm/retry` | Later `llm/retry` and `llm/retry-started` | Aggregate one RetryId's attempts and scheduled/started state |
+| Turn Error / `turn-error` | Turn number | `turn/start` | Error `turn/end` and Retry Events for that Turn | Aggregate terminal failure and use Retry evidence to decide hiding |
+| Turn Tail / `turn-tail` | Turn number | `turn/start` | Assistant, Retry, `step/end`, and `turn/end` | Retain turn end, read each Step's Assistant data, and publish Turn data; use complete Matches to choose the visual tail anchor |
+| Deliverables / `deliverables` | Turn number | `turn/start` | Tool calls/results in that Turn | Aggregate successful mutation paths and publish Turn data without producing a view Node |
+| Unknown fallback / `unknown-surface` | Event seq | Append-surface Event unclaimed by any ordinary Definition | None | Retain raw type/data for the JSON fallback |
+
+### Chat Node and history/live behavior
+
+| Business | `publication()` | Chat output | History and runtime behavior |
+|---|---|---|---|
+| Inbox | `none` | No Node | Recompute instantaneous states along the Reader chain when prepend supplies earlier splices |
+| Message | Immediate by default | `user`, `steering`, or `context` | Window-gap repair can reclassify the same message key |
+| Assistant | RAF for chunks, immediate for final, none for pure usage/finish | Same-key `assistant-step` with running/settled/interrupted status | Matches support fallback without `step/start`; Location close produces interruption presentation |
+| Tool | Immediate by default | One recursive `tool-call` root containing all `subCalls` | A result-only history window supports fallback; running→settled retains its key |
+| Command | Immediate by default | Ordinary `command` or integrated `manual-compaction` | Checkpoint arrival may change the anchor without changing the Context key |
+| Compaction | Immediate by default | `compaction` marker | A checkpoint may render before start; an older start triggers forward replay |
+| Retry | Immediate by default | One `model-retry` Node containing all attempts | Multiple retries update one key; Location close presents the last scheduled attempt as cancelled |
+| Turn Error | Immediate by default | Visible or hidden `turn-error` | Error end supports fallback without start; later Retry keeps the key and hides it |
+| Turn Tail | Immediate only for `turn/end`; otherwise none | Independent `turn-tail` footer | Compute closing/metrics from Step Assistant data and use same-turn Matches to choose the anchor |
+| Deliverables | Immediate by default | No Node | Tool settlement incrementally updates Turn data; the Turn Tail extension slot reads produced files |
+| Fallback | Immediate by default | `unknown` JSON row | Covers only append-surface Events; an ordinary business that claimed but has not rendered an Event does not duplicate it |
+
+Inbox demonstrates that every Event can be a start-only instantaneous-state Context; not every business requires a start/update pair. Reader links each state to the prior same-kind Context instead of inventing a lifecycle ID for the entire Inbox.
+
+Assistant, Turn Tail, and Turn Error demonstrate independent claims on one Event. Each Definition updates only its own State and produces its own atomic Chat Node.
+
+Assistant, Turn Tail, and Deliverables demonstrate layered Location data composition. Assistant writes `assistant-step` data for each Step; Turn Tail derives `turn-tail` data from those Step values; Deliverables independently maintains `deliverables` data for the same Turn. Consumers read only declaration-merged keys, do not scan another business's Nodes, and cannot obtain the provider's Context State.
+
+Tool and Command demonstrate multi-Event aggregation: the producer supplies a shared ID, and the Context builds a tree or integrates Compaction internally instead of pushing pairing into the Chat Builder.
+
+Compaction and historical Tool results demonstrate business fallback without a start. The engine does not impose "no start means no rendering"; each Definition decides whether current Matches are sufficient.
+
+Retry demonstrates the State and Location split. Scheduled and started belong to Retry State, while Step and Turn closure belong to engine Location; `buildViewNode()` combines them into cancelled presentation.
+
+Unknown fallback demonstrates Registry ownership: it handles only append-surface Events unclaimed by every ordinary matcher, and does not create a duplicate Node merely because a claimed Context temporarily returns `null`.
+
+## View Builder and React identity
+
+[`ConversationViewRegistry`](../../../../packages/client/runtime/src/client/conversation/view-registry.ts) creates an independent per-Session builder for each target. The Registry stores factories and shares no Session's ordering or caches.
+
+The Assembler calls `replace({ nodes, timeline })` on low-frequency complete replacements and `apply({ upserts, timeline })` for ordinary prepend/append flushes. Builders receive only final target Nodes already constructed by Definitions.
+
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice temporarily consumed by Trajectory.
+
+Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces only that key's value.
+
+For a structural change, the Builder computes visible order from current store values and reuses unchanged index arrays by reference. Prepend may add earlier history keys, append may add a key at the tail or its business anchor, and ordering never renames existing keys.
+
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) only traverses `order`. Each [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) remains in the same parent list under its Context key and dispatches the `'conversation.chat.node'` keyed slot by `node.kind`.
+
+[`ChatNodeDataMap`](../../../../packages/client/ui-conversation/src/client/contract/chat-nodes.ts) is a declaration-merged renderer payload registry. Each business module registers its own Definition and keyed renderer; `registerConversationNodes()` and `registerChatNodeRenderers()` only assemble those independent contributions and do not interpret business through a closed union or central switch. Built-ins still live in `ui-conversation`, but this type and registration boundary allows a business to move into an independent package without changing the Chat dispatcher.
+
+The Chat entry in `conversation.view` registers `ChatNodeTurnDataInjected` once when it declares the `conversation.chat.node` child slot. `ChatNodeSeat` passes only the stable Node key as `hookContext`; the Slot renderer combines that key with `useSession` from the official standard props to construct `useTurnData(businessKey)`. Every keyed Chat renderer therefore reads strongly typed, read-only data from its own Node's Turn, and the Assistant renderer has no special injection authority.
+
+Slot-level contextual Hooks and entry-owned `inject.hooks` remain independent paths. The latter continues to bind only registration-owned Observables. The former caches definitions by stable slot-inject-face identity and binds its factory and Hook per stable render occurrence. The selector inside `useTurnData()` returns only the current Node's `turn.data.get(key)`, so selector equality filters unrelated Session publications.
+
+The standard `useSession` remains available to every session-scoped slot renderer. `useTurnData()` narrows the common read path rather than acting as a permission sandbox. Whole-window statistics or arbitrary object indexes may still read the Session snapshot explicitly, but they are not modeled as current-Node Turn data.
+
+Assistant streaming to final and Tool running to settled update only one Seat's data and necessary ordering properties. They no longer move from a tail running container into finalized flow, so settlement does not reset component-local State.
+
+When business logic deliberately changes a materialized Node to hidden, it leaves visible order and remounts when visible again. This is explicit business withdrawal of presentation, distinct from the stable-Seat guarantee for running→settled.
+
+The concrete Tool renderer remains governed by the [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md). Tool Definition supplies recursive root/subcall data, and `ui-tool` dispatches concrete presentation by the Tool-name keyed slot.
+
+Trajectory has no independent registered target yet. It continues to consume the legacy slice incrementally derived by the Chat Builder, while Session no longer runs a second transcript fold; a future migration does not change the Event Definition, Context, Reader, or Location contracts.
+
+## Runtime and render path
+
+```text
+Session Event window
+  -> ConversationNodeAssembler
+       -> Definition.match(event) -> (kind, id, start/update)
+       -> Context matches + State + Location
+       -> Definition.buildLocationData(step -> turn)
+            -> StepLocation.data / TurnLocation.data
+       -> Definition.buildViewNode(target = chat)
+  -> ChatSnapshotBuilder
+       -> order[] + keyed Node store + Location index + timeline
+  -> ChatView
+       -> ChatNodeSeat(key)
+       -> conversation.chat.node(entryKey = node.kind, hookContext = key)
+            -> slot-level useTurnData(businessKey)
+```
+
+## Verification
+
+Runtime tests pin Definition lifecycle registration, exact-ID append, update-before-start collection followed by forward replay after start, prepend identity, Reader window-gap repair, transitive dependencies, Location closure, Step→Turn data phase order, Location data replacement, publication cadence, illegal withdrawal, and per-target Builders.
+
+Conversation tests cover every built-in Definition, Assistant Step data, Turn Tail and Deliverables Turn data, Chat ordering and structural sharing, selector isolation, Assistant and Tool running-to-settled identity, nested Code Dispatch, steering, Compaction, Retry, interruption, load-older anchoring, and slot dispatch.
+
+Slot type/runtime tests pin required parent-provided common inject, the `hookContext` type, Hook isolation across Node contexts, stable factory/Hook identity, and the absence of business-renderer rerenders for unrelated Session publications. Existing entry-owned Observable Hook tests continue to pin the path that does not use a contextual factory.
+
+Assembled Web snapshots, GUI tests, and browser scenarios cover the real plugin graph. Browser evidence compares Assistant streaming→settled, Bash running→settled, and Code Mode root + nested subcalls against master layout.
+
+History-path tests cover complete replace, non-overlapping prepend, overlapping-seq deduplication, empty-page `hasMore` convergence, and live append. Equal Event windows ingested through different paths produce equal business State and final Nodes.
+
+## Alternatives considered
+
+**Keep the centralized Session transcript fold and extract only helpers.** Rejected: business identity, history replay, and cache invalidation would still belong to one closed switch; moving functions would not establish independent ownership.
+
+**Let React renderers scan Session Events.** Rejected: every view would duplicate matching and lifecycle State, React would become business authority, and paging and streaming would recompute unrelated component trees.
+
+**Pass global Nodes or Location indexes to every business renderer.** Rejected: business components would scan and infer their current Turn/Step, and their subscription scope would grow with the window. A Definition publishes aggregates onto an engine-owned Location, and a renderer reads only its own Node's Location data.
+
+**Call every Context of a Definition for each new Event.** Rejected: append cost would grow with history, and `update()` would combine matching with conversion. Context-free `match(event)` finds the ID first, after which only one Context updates.
+
+**Let a Definition matcher read Contexts or scan history.** Rejected: matching would depend on ingestion direction, result-first history pages could not determine ownership independently, and live append would regress to searching open objects.
+
+**Define a reverse State fold for backward history scanning.** Rejected: every business would maintain two inverse algorithms, and deletion, non-invertible aggregation, and cross-Context dependencies would be difficult to keep equivalent. Ordered Matches followed by forward replay from start preserve one business meaning.
+
+**Make Inbox a first-class engine concept or one window-wide Context.** Rejected: Inbox is ordinary business State and does not belong in the generic engine. Per-splice instantaneous State plus a strictly backward Reader supports prepend, append, and Message lookup together.
+
+**Register specialized query methods for cross-business reads.** Rejected: consumers would still depend on provider APIs, and each new relationship would expand a central interface. Reader exposes a named kind's read-only predecessor Context; the provider writes useful State and the consumer interprets it.
+
+**Let a Location-data consumer read the provider's Context State directly.** Rejected: the consumer would depend on another business's mutable internal shape and could not express which Turn/Step owns the value. Declaration-merged data maps expose only the provider-selected read-only value and engine-owned coordinates.
+
+**Add generic `end()`, prepared, or window-reset lifecycles.** Rejected: businesses have different completion conditions, and a pagination gap is not a business lifecycle. Business Events update State, Location close triggers replay/build, and Reader dependencies own pagination invalidation.
+
+**Register separate Event Definitions for Chat and Trajectory.** Rejected: identity, State, and Location are target-neutral. `buildViewNode(target)` and each Builder express view differences; Trajectory retains a compatibility slice until its actual migration.
+
+**Add a generic layout model above final business Nodes.** Rejected: activity, tail candidacy, and layout enums would centralize current Chat business semantics in the engine again. Final Nodes carry renderer-required data directly and share only identity, ordering, and Location facts.
+
+**Register the Turn-data Hook only on the Assistant renderer.** Rejected: current-Node Location access is a common capability of the `conversation.chat.node` slot, not one business renderer. The parent Chat entry registers common inject once, and every keyed renderer shares the same strongly typed contract.
+
+**Keep running Assistant or Tool values in an independent tail container.** Rejected: settlement would move them across React parents, and a stable business key could not prevent remount. One keyed order permits data and position changes without changing Seat identity.
+
+## Consequences
+
+A new business node can register its matcher, State transitions, optional Location data, final target Node, and renderer locally without changing Session's business switch. `ChatNodeDataMap` and the Location data maps let a business package merge strongly typed data into the contract; every related Event must still expose a stable ID derivable from that Event alone.
+
+Initial tail, older prepend, and live append share one set of Context invariants. Missing starts, Reader window gaps, unknown Locations, and high-frequency deltas are explicit engine states and require no direction-specific business cache.
+
+Append does not scan historical Contexts; prepend replays only Contexts whose Matches, Locations, or Reader answers actually changed. A structural Chat change may still recompute visible order and indexes, but does not rerun unrelated business folds or replace unchanged Node identity.
+
+Separating State updates from publication cadence folds every Assistant delta while materializing at most once per animation frame. Step or Turn close and final Events can immediately publish the latest State.
+
+Steps and Turns become stable homes for cross-business aggregates. Turn Tail and Deliverables no longer depend on renderers scanning global Nodes; slot-level `useTurnData()` narrows common reads to the current Node's Turn and uses selector equality to isolate unrelated updates.
+
+The cost is new Runtime contracts for Registry, Assembler, Location data, dependency replay, and per-target Builders, plus parent-owned common inject and per-occurrence `hookContext` in UI Slots. Definition authors must understand stable IDs, unique starts, forward replay, Step→Turn publication order, read-only Reader access, and the prohibition on Node withdrawal.
+
+`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice until Trajectory migrates; built-in Definitions currently remain centralized in `ui-conversation`. These compatibility boundaries do not return business interpretation to Session.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
new file mode 100644
index 0000000000..146e8f68a9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -0,0 +1,407 @@
+# Agent Note: Client Conversation 业务节点组装与 Chat keyed snapshot
+
+Status: implemented
+
+[English](2026-08-09-client-conversation-node-assembly.md) | 中文
+
+## Problem
+
+Client Session 既维护传输窗口、连接状态和待处理交互，也在中心化 transcript fold 中解释 Assistant、Tool、消息、命令、压缩、重试及 turn tail 等业务事件。每增加一种业务节点，都要修改 Session 的 switch、历史 replay、索引、缓存和 React 分组；业务 identity、状态演进与最终展示没有独立所有者。
+
+旧链路还把运行中的 Assistant 和 Tool 放在 finalized flow 之外。它们结算后才进入按日志排序的节点列表，因此 React parent 会改变，即使业务 ID 和 `key` 不变也会重新挂载。全量历史加载、older prepend、实时 append 与 token streaming 又分别走不同更新路径，使引用稳定和局部重算只能靠各处特化缓存维持。
+
+业务事件之间的关联方式并不统一。Tool 有 call ID，Assistant 以 turn/step 关联，Compaction 有独立生命周期和 checkpoint，Inbox splice 则表示一个连续状态的瞬间。把这些差异继续塞进统一 fold，会让任一业务变化都经过全局查表并使无关缓存失效。
+
+## Decision
+
+Client Runtime 提供 target-neutral 的 Conversation Node 组装引擎，业务插件注册 Event Definition，视图插件注册 per-Session View Builder。`ui-conversation` 注册第一批内建 Definition 和 `chat` builder；Session 只负责把当前连续事件窗口送入引擎并发布它的 snapshot，不再解释具体 conversation 业务。
+
+详细的方案推导、逐业务适配和逐文件实施设计保留在 [`业务节点组装器第一版`](../../../../docs/client-conversation-node-engine-rfc.md)、[`后续方案差异`](../../../../docs/client-conversation-node-engine-follow-up-differences.md)、[`业务节点与双视图适配论证`](../../../../docs/client-conversation-node-adaptation-analysis.md) 和 [`Chat 链路工程实施设计`](../../../../docs/client-conversation-node-chat-implementation-plan.md)。这些设计稿保留完整讨论过程；本 Note 固定实现后仍需长期维护的职责、算法和取舍。
+
+### 责任分层
+
+| 层 | 长期职责 | 明确不负责 |
+|---|---|---|
+| Session | 维护连续 Event 窗口，区分 replace、prepend、append，调度 snapshot 通知 | 解释 Tool、Assistant、Compaction 等业务事件 |
+| Event Registry | 按 Cordis 生命周期保存唯一 `kind` 的 Definition 和唯一 fallback | 保存某个 Session 的 Context 或 State |
+| Assembler | 匹配 Event，维护 Context、Location、依赖和发布脏集 | 理解业务 State 字段或 Chat 排序 |
+| Node Definition | 定义一个业务对象的 identity、State 演进、Location data 和 target Node | 创建 Context、修改别的业务 State 或扫描全部 Context |
+| View Builder | 把最终 target Node 增量整理成该视图的 snapshot | 重新解释原始 Session Event |
+| React renderer | 按最终 Node 的 `kind` 展示 renderer-owned data，并读取当前 Node 所属 Location 的只读业务 data | 配对业务 Event、扫描全局 Nodes 或决定业务生命周期 |
+
+Registry 注册是 Cordis effect，Definition 卸载会触发现有 Session 的低频 registry rebuild。普通业务 Event 不改变 Registry，也不会因此重建全部业务类型。
+
+### `ConversationNodeDefinition` 总体契约
+
+每个 [`ConversationNodeDefinition`](../../../../packages/client/runtime/src/client/contract/conversation.ts) 独立拥有一种业务对象从 Event 到 State 和最终 view Node 的转换。Definition 的 `kind` 是 Registry 内唯一名称，也是业务 ID 的命名空间。
+
+同一个 Event 可以被多个普通 Definition 认领。例如一条 Assistant Event 同时更新 Assistant Node 和 Turn Tail；一条 Retry Event 同时更新 Retry、Assistant 和 Turn Error。Assembler 只有在全部普通 Definition 都返回 `null` 时才询问 fallback。
+
+Definition 不持有跨 Session 的可变业务数据。每个 Session 的 Context、State、依赖和 View Builder 都由该 Session 的 Assembler 隔离持有。
+
+#### `kind`、业务 ID 与 Context key
+
+`match()` 返回的 `id` 只要求在当前 Definition 内稳定。Tool 的 ID 可以是 call ID，Assistant 的 ID 可以是 `turn:step`，Inbox 的 ID 可以是 splice Event seq。
+
+Assembler 使用 `conversationContextKey(kind, id)` 组合无碰撞 key；不同 Definition 即使返回相同 `id` 也不会共享 Context。最终 view Node 必须沿用这个 engine-owned key，不能把 `seq` 或渲染位置当 identity。
+
+每个 `(kind, id)` 最多存在一个 start Match。第二个 start 会立即报错；Definition 需要表达新生命周期时必须返回新 ID。
+
+#### `match(event)`
+
+`match(event)` 只读取当前原始 `SessionEvent`，返回 `{ id, role: 'start' | 'update' }` 或 `null`。它拿不到 Context、历史、Reader、Location 或 view envelope。
+
+这项限制使单条 Event 的路由成本只随已注册 Definition 数量增长。Assembler 不会为了判断一条 update 属于谁而遍历该 Definition 的历史 Context。
+
+start、result、resource、checkpoint 及业务自有终止 Event 必须携带或可直接推导同一 ID。若单个 Event 不能算出 ID，生产 Event 的协议负责补足关联字段，Client 不通过“最近一个未完成对象”猜测。
+
+`role` 描述 State 生命周期，不描述可见性。start 可以立即生成 terminal Node；update 也可以在 start 尚未加载时先进入 pending Context。
+
+#### `ConversationMatch`
+
+匹配成功后，Assembler 把原始 Event、可选的 wire presentation view、`role` 和引擎计算的 `location` 组成只读 `ConversationMatch`。
+
+Context 的 `matches` 永远按 Event `seq` 升序保存，而不是按网络到达或分页摄入顺序保存。历史尾页先出现 result、older 页后出现 call 时，最终 Match 顺序仍然是 call 在前、result 在后。
+
+Location 可以随 prepend 补齐边界或 append 关闭边界而改变。Assembler 替换受影响 Match 的只读 Location 并 replay Context；业务不把旧 Location 副本当权威保存。
+
+#### `ConversationNodeContext`
+
+| 字段 | 所有者 | Definition 可见语义 |
+|---|---|---|
+| `key` | Assembler | `kind + id` 的稳定最终 identity |
+| `kind` / `id` | Definition + Assembler | 当前业务命名空间和业务 ID |
+| `matches` | Assembler | 当前窗口已收集且按 `seq` 排序的完整业务证据 |
+| `start` | Assembler | 唯一 start Match；尚未加载时为 `undefined` |
+| `state` | Definition 返回、Assembler 持有 | 最近一次 `start`/`update` 返回值；未初始化时为 `undefined` |
+| `current` | Assembler | 各 target 最近一次 materialize 的 Node 或 `null` |
+
+Context 字段只读，不表示业务 State 必须是深度 immutable。Definition 可以返回新对象，也可以原地修改旧对象后返回同一引用。
+
+Assembler 只采纳函数返回值。`start()` 或 `update()` 返回 `undefined` 是契约错误并立即报错；修改了对象却不返回它同样不成立。
+
+Definition 可以读取完整 `matches` 辅助构造 State 或 fallback Node，但不能增删 Match、替换 Context 字段或修改另一个 Context。
+
+#### `start(context, match, reader)`
+
+`start()` 是 State 的唯一初始化入口。Assembler 首次得到唯一 start 后调用它，并采用其返回 State。
+
+当更早分页改变 Context 的 Match 顺序、Reader 前序答案或 Location 事实时，Assembler 从 `start()` 重新计算，而不是对旧 State 做方向相反的补丁。
+
+调用 `start()` 时，Context 可能已经收集 start 之后的 updates。`start()` 返回初始 State 后，Assembler 仍会从 start 之后按日志正序逐条调用 `update()`，因此摄入方向不会改变最终 fold 结果。
+
+`reader` 只在 `start()` 中可用。它允许初始化逻辑读取严格位于当前 start seq 之前、指定 `kind` 的最近 active Context，但不给业务一个任意扫描引擎内部 Map 的接口。
+
+每次重新调用 `start()` 都会替换上一次调用登记的 Reader 依赖，保证 Definition 改变查询分支时不会保留陈旧边。
+
+#### `reader.previous(kind)`
+
+`reader.previous(kind)` 查找满足 `candidate.startSeq < current.startSeq` 且 State 已初始化的最近 Context。它不会返回同 seq、未来 Context 或尚无 State 的 pending Context。
+
+返回值包含前序 Context 的 key、kind、id、start seq、只读 State 和 Matches。消费者自行解释 State；提供方只负责把自己的 State 维护正确，不需要注册特化 query 方法。
+
+Reader 每次查询都记录 `{ key, revision, windowGap }` 依赖。命中前序 Context 时，其 revision 变化会 replay 消费者；未命中且仍有 older 历史时，window gap 会等待后续 prepend。
+
+若窗口已经到达 Session 起点仍未命中，`undefined` 是确定答案。若 `hasMore` 为 true，Definition 看到的仍是同一个 `undefined`，但 Assembler 会记住这是暂定结果。
+
+依赖严格从较早 start 指向较晚 start，因此传递 replay 不形成时序环。Inbox 瞬间态链和 Message 对 Inbox 的读取都使用这一约束。
+
+#### `update(context, match)`
+
+`update()` 只处理已经由 `match()` 精确路由到当前 `(kind, id)` 的 post-start Match。它不再判断 Event 属于哪个 Context。
+
+Assembler 按 `seq` 升序调用 `update()`。实时尾部 update 可以直接增量应用；任何非尾部证据插入、start 补齐或依赖失效都会从 `start()` 完整 replay。
+
+没有业务变化时，`update()` 返回原 State。存在业务变化时，它可以返回 immutable replacement，也可以原地修改并返回同一对象。
+
+Assembler 不以 State 引用相等判断是否需要发布或传播。每次成功 update 都增加 Context revision、标记 dirty，并使直接或传递 Reader 消费者重新求值。
+
+#### `publication(match)`
+
+`publication()` 只决定最新 State 何时 materialize 成 view Node，不改变 `match()`、`start()` 或 `update()` 的同步执行。
+
+| 返回值 | 行为 |
+|---|---|
+| `immediate` | 请求当前 microtask 通知与 flush |
+| `animation-frame` | 把多条高频更新合并到下一帧 materialize |
+| `none` | 本 Match 不主动安排 flush，State 和 dirty 标记仍被保留 |
+
+省略 `publication()` 等于 `immediate`。Assistant token delta 使用 `animation-frame`，不可见 Inbox Context 使用 `none`，final、依赖 replay 和 Location 边界会以 immediate 路径发布最新结果。
+
+一帧内的每条 delta 仍执行 update；合并的只是 `buildViewNode()`、View Builder 和 React snapshot 通知，不会丢失 token。
+
+#### `buildLocationData(context, scope)`
+
+`buildLocationData()` 让 Definition 把 State 的只读派生值发布到 Engine-owned Step 或 Turn，而不把另一个业务的可变 State 暴露出去。Assembler 在每次 materialize 中固定先处理 `step`、再处理 `turn`，因此 Turn 级聚合可以读取同一轮已经更新的 Step data；全部 Location data 就绪后才调用 `buildViewNode()`。
+
+Definition 分别收到 `step` 和 `turn` scope，可以在任一阶段返回一个值或 `null`。返回值必须声明准确的 turn/step 坐标，并使用与 Definition `kind` 相同的 key；Assembler 拥有替换和移除，并拒绝另一个 Context 占用同一 Location key。
+
+`ConversationStepDataMap` 和 `ConversationTurnDataMap` 通过 declaration merging 约束 key 与 value。Location 只暴露稳定的 `data.get(key)` reader，消费者不能取得提供方 Context 或修改它的 State。
+
+#### `buildViewNode(context, target)`
+
+`buildViewNode()` 在发布阶段读取最新 Context，为指定 target 直接生成最终业务 Node。Assembler 不在它之后附加通用 activity、tail candidate 或 layout 业务层。
+
+`null` 表示该 Context 对这个 target 尚未 materialize。普通增量路径中，一个已经返回过非空 Node 的 Context 不能再返回 `null`；暂时隐藏必须保留同 key Node，并使用 target 自己的 visibility。
+
+Assembler 校验 Node `key === context.key` 且 Node `target === target`。业务可以改变 `anchorSeq`、data、Location 或 visibility，但不能在一次生命周期内改变 identity。
+
+`current` 让 Definition 区分“从未生成”与“已经生成后需要隐藏”。Assistant retry 和 Turn Error suppression 使用它避免非法的 Node 撤回。
+
+Definition 可以针对 target 分支构造不同 data，但匹配、Context identity 和 State 保持 target-neutral。本次只注册 `chat` builder，Trajectory 仍通过兼容 slice 使用结果。
+
+#### 不提供通用 `end()`
+
+引擎不提供固定 `end()` 生命周期。单 Event 业务在 `start()` 中完成，多 Event 业务在自己的 update 中记录完成，长期瞬间态业务则每条 Event 建立新 Context。
+
+Step/Turn 关闭属于外部 Location 事实，不替业务修改 State。边界变化会 replay 并 build 受影响 Context；业务结合“自己的 State 是否完成”和“Location 是否 closed”生成正常、running 或 interrupted 表现。
+
+ID 不复用，完成的 Context 继续存在于当前窗口，既提供稳定渲染 identity，也可以作为后续 Reader 的前序证据。
+
+### Location 是一级引擎事实
+
+[`ConversationLocationIndex`](../../../../packages/client/runtime/src/client/sessions/conversation-location-index.ts) 根据 `turn/start`、`step/start`、显式 turn/step payload、`step/end` 和 `turn/end` 建立 Event 到 Location 的映射。
+
+Location 有 `session`、`turn`、`step` 和 `unresolved` 四种形状。Turn/Step 各自带 `open`、`closed` 或 `unknown` 状态，以及已加载的 start/end Event。
+
+每个 Turn 和 Step 还持有 reference-stable 的 Location data store。Definition 更新只替换自己拥有的 key；同一个 store identity 可以随 append 或 prepend 获得新值，使 Context、View Builder 和 React renderer 共享已经确定的层级业务事实，而不复制或遍历全局 Node 数组。
+
+`unresolved` 表示当前历史窗口缺少足够前序边界，不等于 session-level。older prepend 补入边界后，索引修正 Match Location，并只 replay 拥有这些 seq 的 Context。
+
+Append 普通 Event 只继承当前坐标；append 边界只重算所属 Turn。Prepend 会基于扩展后的完整连续窗口重建 Location facts，但引用稳定逻辑保留未变化 Turn/Step 对象。
+
+Assembler 还把 reference-stable timeline 交给 View Builder。业务不重复维护 turn order、step list、last step 或边界 Map。
+
+## 三种事件窗口链路
+
+“历史反扫”描述 UI 从最新尾页向 Session 起点逐页加载的方向，不表示 Definition 逆序执行 `update()`。无论历史 API 返回顺序或页面加载方向如何，Assembler 对每个当前窗口和每个 fresh page 都按 `seq` 升序 canonicalize。
+
+| 场景 | 输入范围 | Context/State 处理 | View Builder |
+|---|---|---|---|
+| 初始历史尾页或 resync | 当前完整连续窗口 | 清空并按 `seq` 正序重建全部 Context | `replace()` |
+| 加载一页 older history | 只传更早且去重后的 fresh Events | 保留现有 Context identity，补 Match、Location 和依赖后局部 replay | `apply(upserts)` |
+| 实时 append | 一条连续尾部 Event | 只匹配 Definitions 并精确更新命中 ID，边界只影响所属 Turn | `apply(upserts)` |
+
+### 初始历史尾页与逻辑反扫
+
+1. `Session.open()` 拉取最新 tail page，并把连续 History Entries 交给 `replaceWindow(entries, hasMore)`。
+2. `replaceWindow` 清空旧 Context、start-seq 索引、seq 反向索引、Reader 依赖和输入 Map。
+3. 全部 entries 按 Event `seq` 升序排序并写入当前窗口。
+4. LocationIndex 对这个窗口重建 Turn/Step facts。
+5. Assembler 按升序 Event 逐条调用每个普通 Definition 的 `match(event)`。
+6. 每个命中结果按 `(kind, id)` 取得或创建 Context，并把 Match 插入该 Context 的有序数组。
+7. 遇到 start 时执行 `start()`；已有 State 的尾部 update 直接执行 `update()`。
+8. 当前页只含 result/resource 而缺 start 时，Context 仍会按 ID 创建并收集 Matches，但 State 保持 `undefined`。
+9. 全部 Event 匹配后，Assembler 复查 Reader 依赖，使同一窗口内较早瞬间态先稳定、较晚消费者再读取它。
+10. 所有 Context 标记 dirty，下一次 flush 先按 Step→Turn 完整重建 Location data，再对每个 target 调用 `buildViewNode()`。
+11. 某些业务在缺 start 时返回 `null`；Compaction、Command、Tool result 或 Turn Error 等可根据充分 update 证据构造 fallback Node。
+12. 每个 View Builder 收到完整 Node 集和 timeline，通过 `replace()` 建立初始 snapshot。
+
+这条链路“从最新页开始”只发生在分页选择层。页面内部 State 始终正序计算，因此同一个窗口不会因为扫描方向不同产生不同业务结果。
+
+缺 start 的 Context 不是错误。它是等待 older 页补齐的 pending 聚合容器；是否提前可见由该 Definition 的 `buildViewNode()` 决定。
+
+若当前页中的同 ID update 在日志顺序上真的早于 start，而不是仅仅先被加载，补齐 start 后 replay 会报协议错误。到达顺序可以反向，业务日志顺序不能反向。
+
+### 新 older 分页的 prepend
+
+1. `Session.loadOlder()` 以当前 `baseSeq` 拉取紧邻前页，并先验证页尾与当前窗口连续。
+2. Session 把 raw Event/view 数组 prepend 到自己的窗口，只把这一页传给 `assembler.prepend(entries, hasMore)`。
+3. Assembler 按 seq 去掉与当前窗口重叠的 Events，再把 fresh page 内部升序排列。
+4. 已存在的 Context、State、current Nodes 和 View Builder 实例不清空。
+5. LocationIndex 用扩展后的完整输入重建 facts，并报告 Location identity 真正变化的 seq。
+6. 拥有这些 seq 的 Context 更新 Match Location，并从 start replay；无关 Context 不参与 Location replay。
+7. fresh Events 逐条执行 Definition matcher，并按稳定 ID 插入已有或新 Context 的有序 Matches。
+8. 新页补出 pending Context 的 start 时，该 Context 从 start 初始化，再正序应用已经收集的所有 updates。
+9. 新页建立更近的 Reader predecessor、改变 predecessor revision 或消除 window gap 时，消费者从 `start()` 重算。
+10. Reader 依赖沿 start seq 向后传递 replay；同一传播批次不会把 Event 逆序应用。
+11. `hasMore` 从 true 变为 false 的空页也会复查依赖，把暂定 `undefined` 收敛为确定不存在。
+12. flush 只为 dirty Context 重新发布 Step/Turn Location data 和 target Node，并把非空结果作为 `upserts` 交给 View Builder `apply()`。
+
+Prepend 保留已有 Context key 和 current Node identity。新页可以在 Chat `order` 前部增加 key，也可以修正既有 Node 的 anchor、Location、visibility 或 data，但不会为无关业务重新创建 Context。
+
+Chat Builder 遇到结构变化时会从 keyed store 重算可见 `order` 和 Location 二级索引；这是视图索引计算，不会重新执行全部业务 Definition 或替换未变化 Node value。
+
+Reader gap 修复是 prepend 与普通 append 最大的算法差异。新页不仅可能创建可见历史 Node，也可能改变后续 Inbox 瞬间态以及依赖它的 Message 分类。
+
+### 正向实时 append
+
+1. Session 只接受紧邻当前 tail seq 的 live Event；重叠 seq 去重，出现 gap 时先走 tail-page repair。
+2. 非边界 Event 增量写入当前 Turn/Step 坐标；边界 Event 更新所属 Turn 的 Location facts。
+3. Assembler 对这一个 Event 的每个普通 Definition 调用一次 `match()`，不会遍历任何 Definition 的 Context 集合。
+4. 每个命中结果通过 `(kind, id)` 直接定位一个 Context。
+5. 新 ID 创建 Context；已有 ID 的正常尾部 update 直接调用一次 `update()`。
+6. start 或任何需要插入非尾部位置的证据会走完整 `replayContext()`，保持同一正序语义。
+7. Context revision 变化后，只沿已登记 Reader 依赖 replay 消费者。
+8. Location close 会更新所属 Turn 中受影响 Match 的 Location，并 replay 这些 Context，使未完成 Assistant、Tool 或 Retry 得到 interrupted/cancelled 语气。
+9. Assembler 汇总所有命中 Definition 的 publication urgency；`immediate` 高于 `animation-frame`，后者高于 `none`。
+10. Session 把 immediate 交给 microtask notifier，把 animation-frame 交给 RAF notifier。
+11. flush 先为 dirty Context 更新 Step/Turn Location data，再调用 `buildViewNode()`，最后把本轮 upserts 和最新 timeline 交给 View Builder。
+12. React 订阅的新 snapshot 复用稳定 Context key；同一 Tool running→settled 或 Assistant streaming→final 不跨父节点移动。
+
+Append 的业务匹配成本是 Definition 数量加实际命中的 Context 更新，不随历史 Context 数量增长。Reader 消费者和 Location 关闭会增加与真实依赖或所属 Turn 成比例的 replay。
+
+Chat `order` 的结构性变化仍可能重排当前可见 key；纯 data 更新只替换 keyed store 中一个 Node，并 touch 所属 Location 索引。这里保证的是无关业务不 refold、Node identity 不替换，而不是宣称所有视图索引操作都是常数复杂度。
+
+### Replace、prepend 与 append 的一致性
+
+三条链路最终都遵守同一不变量：Context Matches 按 seq 排序，State 从唯一 start 正序 fold，Reader 只看严格前序 active Context，Location data 按 Step→Turn 发布，Node key 只由 kind 和 ID 决定。
+
+`replaceWindow` 是初始打开、resync、gap repair 和 registry 变化的低频完整替换，不用于实现普通 load older。`prepend` 与 `append` 都保留现有 Builder 和 Context identity。
+
+分页页宽、历史加载次数和 RAF 合批只影响何时得到更多证据或何时发布，不改变窗口证据相同时的最终 Context State 与 Node。
+
+## 内建业务如何使用 Definition
+
+### 匹配、ID 与 State
+
+| 业务 / `kind` | 稳定 ID | start Match | update Matches | State 与跨 Context 读取 |
+|---|---|---|---|---|
+| Next-turn Inbox / `inbox-next-turn` | splice Event seq | 每条目标为 next-turn 的 `agent/inbox/spliced` | 无 | 从 `reader.previous(ownKind)` 的 pending/claimed 瞬间态应用当前 splice |
+| Next-step Inbox / `inbox-next-step` | splice Event seq | 每条目标为 next-step 的 `agent/inbox/spliced` | 无 | 同样形成逐指令瞬间态，claimed 集合供 Message 读取 |
+| Message / `input-message` | message ID | append-surface `user/message` | 无 | 根据 source 生成 context message，或读取最近 next-step Inbox 判断 user/steering |
+| Assistant / `assistant-step` | `turn:step` | `step/start` | `assistant/chunk`、final `assistant/message`、同 step Retry | 聚合 blocks、usage、首 token 时间、final 和 retry 隐藏状态，并发布同 key Step data |
+| Tool / `tool-call` | root call ID | root `tool/call` | root result、Code Dispatch start/result | 聚合 root、children 和 parent Map；Dispatch Event 用 `rootCallId` 精确路由 |
+| Command / `command` | command ID | `command/run` | `command/done`、带 source command ID 的 compact lifecycle/checkpoint | 聚合 command outcome 和手动压缩证据 |
+| Automatic Compaction / `compaction` | compaction ID | 无 source command ID 的 `compact/start` | summary、end、replacement checkpoint | 聚合 summary/checkpoint；checkpoint 足够时可在缺 start 下 fallback |
+| Retry / `model-retry` | retry ID | attempt 1 的 `llm/retry` | 后续 `llm/retry` 与 `llm/retry-started` | 聚合同一 RetryId 的 attempts 与 scheduled/started 状态 |
+| Turn Error / `turn-error` | turn number | `turn/start` | error `turn/end` 与该 turn Retry Events | 聚合 terminal failure，并用 Retry 证据决定隐藏 |
+| Turn Tail / `turn-tail` | turn number | `turn/start` | Assistant、Retry、`step/end`、`turn/end` | 保存 turn end，读取各 Step 的 Assistant data，发布 Turn data；完整 Matches 用于选择视觉尾部 anchor |
+| Deliverables / `deliverables` | turn number | `turn/start` | 该 Turn 的 Tool call/result | 聚合成功 mutation paths 并发布 Turn data，不生成 view Node |
+| Unknown fallback / `unknown-surface` | Event seq | 未被普通 Definition 认领的 append-surface Event | 无 | 保存原始 type/data 作为 JSON fallback |
+
+### Chat Node 与历史/实时特性
+
+| 业务 | `publication()` | Chat 产物 | 历史分页与运行时行为 |
+|---|---|---|---|
+| Inbox | `none` | 不生成 Node | prepend 补前序 splice 时沿 Reader 链重算瞬间态 |
+| Message | 默认 immediate | `user`、`steering` 或 `context` | window gap 修复可让同一 message key 重新分类 |
+| Assistant | chunk 为 RAF，final immediate，纯 usage/finish 为 none | 同 key `assistant-step`，状态为 running/settled/interrupted | 缺 `step/start` 可先用 Matches fallback；Location close 生成中断表现 |
+| Tool | 默认 immediate | 一个递归 `tool-call` root，包含全部 `subCalls` | result-only 历史窗口可 fallback；running→settled 保持 key |
+| Command | 默认 immediate | 普通 `command` 或集成 `manual-compaction` | checkpoint 到达可改变 anchor，但不改变 Context key |
+| Compaction | 默认 immediate | `compaction` marker | checkpoint 可先展示，older 补 start 后正序 replay |
+| Retry | 默认 immediate | 一个 `model-retry` Node 内含 attempts | 多次 retry 更新同一 key；Location close 把最后 scheduled 表现为 cancelled |
+| Turn Error | 默认 immediate | `turn-error` visible/hidden | 缺 start 可从 error end fallback；Retry 到达后保留 key 并隐藏 |
+| Turn Tail | 仅 `turn/end` immediate，其余 none | 独立 `turn-tail` footer | 从 Step Assistant data 计算 closing/metrics，并通过同 turn Matches 决定 anchor |
+| Deliverables | 默认 immediate | 不生成 Node | Tool 结算增量更新所属 Turn data，Turn Tail 扩展槽读取 produced files |
+| Fallback | 默认 immediate | `unknown` JSON row | 只兜底 append surface，普通业务已认领但暂不可见时不会重复生成 |
+
+Inbox 展示了“每条 Event 都是一个 start-only 瞬间态 Context”，不是所有业务都需要 start/update 配对。它通过 Reader 与前一个同 kind Context 形成连续 fold，而非给整个 Inbox 人工制造生命周期 ID。
+
+Assistant、Turn Tail 和 Turn Error 展示了同一 Event 被多个 Definition 独立认领。每个 Definition 只更新自己的 State，最终分别生成原子 Chat Node。
+
+Assistant、Turn Tail 和 Deliverables 展示了 Location data 的分层组合。Assistant 负责写好每个 Step 的 `assistant-step` data；Turn Tail 从这些 Step values 计算 `turn-tail` data；Deliverables 独立维护同一 Turn 的 `deliverables` data。消费者只读取声明合并后的 key，不扫描其他业务 Node，也不取得提供方的 Context State。
+
+Tool 和 Command 展示了多 Event 聚合：生产者提供共同 ID，Context 在业务内部构树或整合 Compaction，不把配对工作推给 Chat Builder。
+
+Compaction 和历史 Tool result 展示了缺 start 时的业务 fallback。引擎不统一规定“没有 start 就不渲染”；Definition 根据当前 Matches 是否足够自行决定。
+
+Retry 展示了业务 State 与 Location 的分工。scheduled/started 属于 Retry State；Step/Turn 是否关闭属于引擎 Location；`buildViewNode()` 组合两者得到 cancelled 视觉状态。
+
+Unknown fallback 展示了 Registry ownership：fallback 只处理没有任何普通 matcher 认领的 append surface Event，不会因为普通 Context 暂时返回 `null` 而误生成第二个 Node。
+
+## View Builder 与 React identity
+
+[`ConversationViewRegistry`](../../../../packages/client/runtime/src/client/conversation/view-registry.ts) 为每个 target 创建独立的 per-Session builder。Registry 保存 factory，不共享某个 Session 的排序或缓存。
+
+Assembler 低频完整替换时调用 `replace({ nodes, timeline })`；普通 prepend/append flush 调用 `apply({ upserts, timeline })`。Builder 只接收 Definition 已构造完成的 target Nodes。
+
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline` 和 Trajectory 临时使用的 `legacy` slice。
+
+Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value。
+
+Builder 遇到结构变化时从 store 的当前 values 计算 visible order，并按未变化引用复用索引数组。Prepend 可以增加前部历史 key，append 可以增加尾部或按业务 anchor 落位，既有 key 不因排序变化而重命名。
+
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只遍历 `order`。每个 [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) 以 Context key 固定在同一个父列表中，并按 `node.kind` 分发 `'conversation.chat.node'` keyed slot。
+
+[`ChatNodeDataMap`](../../../../packages/client/ui-conversation/src/client/contract/chat-nodes.ts) 是 declaration-merged 的 renderer payload registry。每个业务模块分别注册自己的 Definition 和 keyed renderer；`registerConversationNodes()` 与 `registerChatNodeRenderers()` 只负责装配这些独立贡献，不通过 closed union 或中心 switch 解释业务。内建实现仍位于 `ui-conversation`，但该类型和注册边界允许业务迁入独立 package 而不修改 Chat dispatcher。
+
+`conversation.view` 的 Chat entry 在声明 `conversation.chat.node` child slot 时统一注册 `ChatNodeTurnDataInjected`。`ChatNodeSeat` 只把稳定 Node key 作为 `hookContext` 传给 slot；Slot renderer 用官方 standard props 中的 `useSession` 和该 key 构造 `useTurnData(businessKey)`，因此每个 keyed Chat renderer 都能读取自己 Node 所属 Turn 的强类型只读 data，Assistant renderer 不拥有特殊注入权限。
+
+Slot-level contextual Hook 与 entry-owned `inject.hooks` 是两条独立路径。后者继续只绑定 registration-owned Observable；前者按稳定 slot inject face 缓存定义，并按稳定 render occurrence 绑定 factory 和 Hook。`useTurnData()` 内部 selector 只返回当前 Node 的 `turn.data.get(key)`，无关 Session publication 会被 selector equality 截断。
+
+标准 `useSession` 仍属于所有 session-scoped slot renderer 的公开能力，`useTurnData()` 是收窄常见读取方式而不是权限沙箱。全窗口统计或任意对象索引仍可显式使用 Session snapshot；它们不能伪装成“当前 Node 的 Turn data”。
+
+Assistant streaming 到 final、Tool running 到 settled 只更新同一个 Seat 的 data 和必要的排序属性，不再从末尾 running container 移入 finalized flow，因此组件内部 State 不因结算自动归零。
+
+业务主动把已发布 Node 改成 hidden 时，它会退出 visible order，恢复 visible 时会重新 mount。这是明确的业务撤显语义，与 running→settled 的稳定 Seat 保证不同。
+
+具体 Tool renderer 仍由 [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md) 约束。Tool Definition 只交付递归 root/subcall data，`ui-tool` 再按 Tool name keyed slot 分发具体表现。
+
+Trajectory 尚未注册独立 target。它继续消费 Chat Builder 增量派生的 legacy slice，Session 不再运行第二套 transcript fold；未来迁移不改变 Event Definition、Context、Reader 或 Location 契约。
+
+## Runtime and render path
+
+```text
+Session Event window
+  -> ConversationNodeAssembler
+       -> Definition.match(event) -> (kind, id, start/update)
+       -> Context matches + State + Location
+       -> Definition.buildLocationData(step -> turn)
+            -> StepLocation.data / TurnLocation.data
+       -> Definition.buildViewNode(target = chat)
+  -> ChatSnapshotBuilder
+       -> order[] + keyed Node store + Location index + timeline
+  -> ChatView
+       -> ChatNodeSeat(key)
+       -> conversation.chat.node(entryKey = node.kind, hookContext = key)
+            -> slot-level useTurnData(businessKey)
+```
+
+## Verification
+
+Runtime tests 固定 Definition 生命周期注册、exact-ID append、update-before-start 收集与 start 后正序 replay、prepend identity、Reader window-gap 修复、传递依赖、Location closure、Step→Turn data phase order、Location data replacement、publication cadence、非法撤回和 per-target Builder。
+
+Conversation tests 覆盖全部内建 Definition、Assistant Step data、Turn Tail 与 Deliverables Turn data、Chat 排序和结构共享、selector isolation、Assistant/Tool running-to-settled identity、nested Code Dispatch、steering、Compaction、Retry、interruption、load-older anchoring 和 slot dispatch。
+
+Slot type/runtime tests 固定父注册必须提供声明的 common inject、`hookContext` 类型、不同 Node context 的 Hook 隔离、factory/Hook identity 稳定，以及无关 Session publication 不重渲染业务 renderer。原 entry-owned Observable Hook 测试继续固定未使用 contextual factory 的路径。
+
+Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏览器证据比较 Assistant streaming→settled、Bash running→settled 以及 Code Mode root + nested subcalls 与 master 的布局。
+
+历史链路验证同时覆盖完整 replace、非重叠 prepend、重叠 seq 去重、空页 `hasMore` 收敛和 live append。相同 Event 窗口通过不同摄入路径得到相同业务 State 与最终 Node。
+
+## Alternatives considered
+
+**保留中心化 Session transcript fold，只抽 helper。** 拒绝：业务 identity、历史 replay 和 cache invalidation 仍属于一个闭合 switch，移动函数不会产生独立所有权。
+
+**让 React renderer 自己扫描 Session Event。** 拒绝：每种 view 都会重复匹配和生命周期 State，React 会成为业务权威，paging 与 streaming 也会重算无关组件树。
+
+**把全局 Nodes 或 Location 索引传给每个业务 renderer。** 拒绝：业务组件会自行扫描和推断当前 Turn/Step，订阅范围随窗口增长。Definition 把聚合值发布到 Engine-owned Location，renderer 只读取自己 Node 的 Location data。
+
+**每个新 Event 都调用同 Definition 的全部 Context。** 拒绝：append 成本随历史增长，`update()` 也会同时承担匹配与转换。无 Context 的 `match(event)` 先算出 ID，随后只更新一个 Context。
+
+**让 Definition 的 matcher 读取 Context 或扫描历史。** 拒绝：匹配将依赖摄入方向，result-first 历史页无法独立算出归属，实时 append 也退化成开放对象查找。
+
+**为历史反扫定义逆向 State fold。** 拒绝：每个业务都要维护互为逆运算的两套逻辑，删除、非可逆聚合和跨 Context 依赖很难保持一致。统一 Matches 后从 start 正序 replay 只有一套业务语义。
+
+**把 Inbox 做成引擎一级公民或一个窗口级 Context。** 拒绝：Inbox 是普通业务状态，不应污染通用引擎；逐 splice 瞬间态加严格前序 Reader 同时支持 prepend、append 和 Message 查询。
+
+**给跨业务查询注册特化 query method。** 拒绝：消费者仍要依赖提供方 API，新增关系会扩张中心接口。Reader 暴露指定 kind 的只读前序 Context，由提供方写好 State、消费者读懂 State。
+
+**让 Location data 消费者直接读取提供方 Context State。** 拒绝：消费者会依赖另一个业务的可变内部形状，也无法表达值属于哪个 Turn/Step。declaration-merged data map 只公开提供方选择发布的只读值和 Engine-owned 坐标。
+
+**增加通用 `end()`、prepared 或 window reset 生命周期。** 拒绝：不同业务完成条件不同，分页缺口也不是业务生命周期。业务 Event 更新 State，Location close 触发 replay/build，Reader dependency 负责补页失效。
+
+**为 Chat 与 Trajectory 注册两套 Event Definition。** 拒绝：identity、State 和 Location 与 target 无关。视图差异由 `buildViewNode(target)` 和各自 Builder 表达；Trajectory 在真正迁移前保留兼容 slice。
+
+**在最终业务 Node 上再叠一层通用 layout model。** 拒绝：activity、tail candidacy 和 layout enum 会把当前 Chat 的业务语义重新集中到引擎。最终 Node 直接携带 renderer 所需 data，只共享 identity、排序和 Location 事实。
+
+**只在 Assistant renderer 注册 Turn data Hook。** 拒绝：访问当前 Node Location 是 `conversation.chat.node` slot 的公共能力，不属于某个业务 renderer。父 Chat entry 注册一次 common inject，所有 keyed renderer 共享同一强类型契约。
+
+**把 running Assistant 或 Tool 保留在独立 tail container。** 拒绝：结算时会跨 React parent 移动，稳定业务 key 也无法阻止 remount。统一 keyed order 允许 data 和排序位置改变，但不改变 Seat identity。
+
+## Consequences
+
+新增业务节点可以局部注册自己的 matcher、State 转换、可选 Location data、最终 target Node 和 renderer，不再修改 Session 的业务 switch。`ChatNodeDataMap` 和 Location data maps 允许业务 package 通过 declaration merging 合入强类型 data；所有相关 Event 仍须暴露可单 Event 推导的稳定 ID。
+
+初始尾页、older prepend 和 live append 共享一套 Context 不变量。缺 start、Reader window gap、Location unknown 以及高频 delta 都是引擎明确表达的状态，不需要业务另建方向相关 cache。
+
+Append 不扫描历史 Context；prepend 只 replay Match、Location 或 Reader 答案真正受影响的 Context。Chat 结构变化仍可能重算 visible order 和索引，但不会重跑无关业务 fold 或替换未变化 Node identity。
+
+State 更新与发布频率分离后，Assistant 每条 delta 都被 fold，同时每 animation frame 最多 materialize 一次。step/turn close 和 final 可立即发布最新 State。
+
+Step/Turn 成为业务间共享聚合的稳定宿主。Turn Tail 和 Deliverables 不再依赖 renderer 扫描全局 Nodes；Slot-level `useTurnData()` 把常见读取限制到当前 Node 所属 Turn，并通过 selector equality 隔离无关更新。
+
+代价是 Runtime 新增 Registry、Assembler、Location data、依赖重放和 per-target Builder 契约，UI Slots 也新增 parent-owned common inject 与 per-occurrence `hookContext`。Definition 作者必须理解稳定 ID、唯一 start、正序 replay、Step→Turn 发布顺序、只读 Reader 和 Node 不撤回规则。
+
+`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 在 Trajectory 迁移前仍维护 legacy slice；内建 Definitions 暂时集中在 `ui-conversation`。这些是兼容边界，不把业务解释权交还给 Session。

From aa623b6e7ac5c83fa1f2ea4fe80e124b2d5d66bd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:07 +0800
Subject: [PATCH 231/262] refactor(events): add stable conversation correlation
 ids

---
 packages/compact/command-compact/src/index.ts |  2 +-
 packages/compact/compact-basic/package.json   |  2 +
 packages/compact/compact-basic/src/index.ts   |  9 +-
 packages/compact/compact-basic/src/region.ts  | 40 ++++++--
 packages/compact/compact-basic/tsconfig.json  |  3 +
 packages/compact/compact/package.json         |  8 ++
 packages/compact/compact/src/brand.ts         | 13 +++
 packages/compact/compact/src/checkpoint.ts    | 25 +++++
 packages/compact/compact/src/index.ts         |  7 +-
 packages/compact/compact/src/invariant.ts     | 93 ++++++++++++++++++-
 packages/compact/compact/src/types.ts         | 12 ++-
 packages/compact/compact/tsconfig.json        |  6 ++
 packages/compact/compact/tsdown.config.ts     | 13 +++
 packages/core/tools/src/code-mode.ts          |  7 +-
 packages/core/tools/src/index.ts              |  9 ++
 packages/core/tools/src/invariant.ts          | 28 ++++++
 packages/interaction/commands/src/index.ts    |  4 +-
 packages/llm/llm-retry/package.json           |  6 ++
 packages/llm/llm-retry/src/brand.ts           | 13 +++
 packages/llm/llm-retry/src/index.ts           | 36 +++----
 packages/llm/llm-retry/src/invariant.ts       | 37 +++++++-
 packages/llm/llm-retry/src/types.ts           | 12 +++
 packages/llm/llm-retry/tsconfig.json          |  3 +
 23 files changed, 347 insertions(+), 41 deletions(-)
 create mode 100644 packages/compact/compact/src/brand.ts
 create mode 100644 packages/compact/compact/tsdown.config.ts
 create mode 100644 packages/llm/llm-retry/src/brand.ts

diff --git a/packages/compact/command-compact/src/index.ts b/packages/compact/command-compact/src/index.ts
index 4ac171a689..b3f80d87fd 100644
--- a/packages/compact/command-compact/src/index.ts
+++ b/packages/compact/command-compact/src/index.ts
@@ -63,7 +63,7 @@ async function executeCompact(
     return { kind: 'error', text: USAGE }
   }
   try {
-    const result = await ctx.compact.compactNow(invocation.agent, invocation.signal)
+    const result = await ctx.compact.compactNow(invocation.agent, invocation.signal, invocation.commandId)
     if (result === null) return { kind: 'success', text: 'No compactable history yet.' }
     return {
       kind: 'success',
diff --git a/packages/compact/compact-basic/package.json b/packages/compact/compact-basic/package.json
index 2b0624e06e..3fffee14a7 100644
--- a/packages/compact/compact-basic/package.json
+++ b/packages/compact/compact-basic/package.json
@@ -27,6 +27,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-compact": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -49,6 +50,7 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-compact": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts
index 27b59d0451..d3c710bef3 100644
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -13,6 +13,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import { CONTEXT_WINDOW_EXCEEDED_CODE, assertNever } from '@deepseek-ai/dsh-llm'
 import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 // Type-only: makes the optional sibling service available to `ctx.get()`.
 import type {} from '@deepseek-ai/dsh-compact-tool-result-prune'
 import {
@@ -361,9 +362,14 @@ export class BasicCompactService extends CompactService {
    * resolve only after its standalone marker pair is durably checkpointed.
    * @param agent - idle agent whose next-turn admission this call reserves.
    * @param signal - cancellation scoped to this compaction request.
+   * @param sourceCommandId - initiating command identity for presentation correlation.
    * @returns the committed result, or `null` when no safe useful range exists.
    */
-  override compactNow(agent: Agent, signal: AbortSignal): Promise<CompactionResult | null> {
+  override compactNow(
+    agent: Agent,
+    signal: AbortSignal,
+    sourceCommandId?: CommandId,
+  ): Promise<CompactionResult | null> {
     signal.throwIfAborted()
     try {
       return agent.runMaintenance(async (agentSignal) => {
@@ -385,6 +391,7 @@ export class BasicCompactService extends CompactService {
             {
               owner: null,
               stability: 'selected-span',
+              ...sourceCommandId === undefined ? {} : { sourceCommandId },
               flush: async () => {
                 await this.ctx.sessions.flush(agent.session)
               },
diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts
index b220074e02..ae637d03cc 100644
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -5,14 +5,17 @@
  * @module @deepseek-ai/dsh-compact-basic/region
  */
 
+import { randomUUID } from 'node:crypto'
 import { isDeepStrictEqual } from 'node:util'
 import {
-  COMPACT_CHECKPOINT_SOURCE,
+  CompactionId,
   ManualCompactionError,
+  compactCheckpointSource,
   toolPairingBalancedAfter,
   toolPairingBalancedBefore,
 } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
 import type { Message, UserMessage } from '@deepseek-ai/dsh-llm'
 import type { TokenMeasurement, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
@@ -54,6 +57,8 @@ interface CompactionTransactionOptions {
   readonly stability: 'whole-surface' | 'selected-span'
   /** Optional durability checkpoint after a successfully closed bracket. */
   readonly flush?: () => Promise<void>
+  /** Manual command that initiated this transaction, when present. */
+  readonly sourceCommandId?: CommandId
 }
 
 interface CompactionEntryState {
@@ -175,7 +180,13 @@ export async function compactSurfaceRegion(
     owner = entryState.openTurn
   }
 
-  const startEvent = session.append('compact/start', { turn: owner })
+  const compactionId = CompactionId(randomUUID())
+  const lifecycle = {
+    compactionId,
+    ...options.sourceCommandId === undefined ? {} : { sourceCommandId: options.sourceCommandId },
+    turn: owner,
+  }
+  const startEvent = session.append('compact/start', lifecycle)
   const assertStable: StabilityCheck = options.stability === 'whole-surface'
     ? assertWholeSurfaceUnchanged
     : assertSelectedSpanStable
@@ -188,13 +199,20 @@ export async function compactSurfaceRegion(
 
   try {
     const prepared = prepareCompaction(dependencies, session, selection)
-    const summarized = await summarizeCompaction(dependencies, prepared, agent, signal)
+    const summarized = await summarizeCompaction(
+      dependencies,
+      prepared,
+      agent,
+      compactionId,
+      options.sourceCommandId,
+      signal,
+    )
     if (options.owner === null) signal?.throwIfAborted()
     assertStable(dependencies, session, summarized)
     stage = 'commit'
     const pending = commitCompactionBody(session, startEvent, summarized)
     closing = true
-    const endEvent = session.append('compact/end', { turn: owner })
+    const endEvent = session.append('compact/end', lifecycle)
     closed = true
     result = completeCompaction(pending, endEvent)
   } catch (error: unknown) {
@@ -202,7 +220,7 @@ export async function compactSurfaceRegion(
     if (!closing) {
       closing = true
       try {
-        session.append('compact/end', { turn: owner, error: errorChain(error) })
+        session.append('compact/end', { ...lifecycle, error: errorChain(error) })
         closed = true
       } catch (closeError: unknown) {
         failure = { error: closeError, stage: 'commit' }
@@ -343,12 +361,14 @@ async function summarizeCompaction(
   dependencies: RegionDependencies,
   prepared: PreparedCompaction,
   agent: Agent,
+  compactionId: CompactionResult['compactionId'],
+  sourceCommandId: CommandId | undefined,
   signal?: AbortSignal,
 ): Promise<SummarizedCompaction> {
   const summaryResult = await dependencies.summarize(prepared.input, agent, signal)
   const checkpointMessage = createUserMessage({
     content: frameSummary(summaryResult.summary),
-    source: COMPACT_CHECKPOINT_SOURCE,
+    source: compactCheckpointSource(compactionId, sourceCommandId),
   })
   const framedSummaryTokenCount = dependencies.meter.estimateMessage(checkpointMessage)
   if (framedSummaryTokenCount >= prepared.shadowedTokenCount) {
@@ -425,6 +445,10 @@ function commitCompactionBody(
     ? { rawOutput: summarized.rawOutput, llmStreamCall: true as const }
     : summarized.rawOutput === undefined ? {} : { rawOutput: summarized.rawOutput }
   const summaryEvent = session.append('compact/summary', {
+    compactionId: startEvent.data.compactionId,
+    ...startEvent.data.sourceCommandId === undefined
+      ? {}
+      : { sourceCommandId: startEvent.data.sourceCommandId },
     summary,
     ...callProvenance,
     shadowedRange: { start, end },
@@ -440,6 +464,10 @@ function commitCompactionBody(
     sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
   })
   return {
+    compactionId: startEvent.data.compactionId,
+    ...startEvent.data.sourceCommandId === undefined
+      ? {}
+      : { sourceCommandId: startEvent.data.sourceCommandId },
     startSeq: startEvent.seq,
     summarySeq: summaryEvent.seq,
     summary,
diff --git a/packages/compact/compact-basic/tsconfig.json b/packages/compact/compact-basic/tsconfig.json
index bd1a440119..f90011f04d 100644
--- a/packages/compact/compact-basic/tsconfig.json
+++ b/packages/compact/compact-basic/tsconfig.json
@@ -27,6 +27,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../compact"
     },
diff --git a/packages/compact/compact/package.json b/packages/compact/compact/package.json
index 100a3f56f8..bb4150ee32 100644
--- a/packages/compact/compact/package.json
+++ b/packages/compact/compact/package.json
@@ -19,6 +19,10 @@
       "types": "./lib/types/checkpoint.d.ts",
       "default": "./lib/types/checkpoint.js"
     },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -30,12 +34,16 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/compact/compact/src/brand.ts b/packages/compact/compact/src/brand.ts
new file mode 100644
index 0000000000..5b6de03e61
--- /dev/null
+++ b/packages/compact/compact/src/brand.ts
@@ -0,0 +1,13 @@
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Stable identity shared by one compact start/summary/checkpoint/end transaction. */
+export type CompactionId = Branded<'CompactionId'>
+
+/**
+ * Brand an implementation-minted compaction identity.
+ * @param id - opaque transaction identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CompactionId(id: string): CompactionId {
+  return id as CompactionId
+}
diff --git a/packages/compact/compact/src/checkpoint.ts b/packages/compact/compact/src/checkpoint.ts
index 9d8b98e4d6..9908fe4ac0 100644
--- a/packages/compact/compact/src/checkpoint.ts
+++ b/packages/compact/compact/src/checkpoint.ts
@@ -13,10 +13,35 @@
  */
 
 import type { MessageSource } from '@deepseek-ai/dsh-llm/message'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { CompactionId } from './brand.ts'
 
 /** Canonical source for the replacement user message produced by every compaction backend. */
 export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
 
+/** Message provenance carried by a concrete compaction checkpoint. */
+export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_SOURCE & {
+  readonly compactionId: CompactionId
+  readonly sourceCommandId?: CommandId
+}
+
+/**
+ * Create checkpoint provenance correlated with one compaction transaction.
+ * @param compactionId - owning compaction identity.
+ * @param sourceCommandId - initiating manual command, when present.
+ * @returns immutable checkpoint source.
+ */
+export function compactCheckpointSource(
+  compactionId: CompactionId,
+  sourceCommandId?: CommandId,
+): CompactCheckpointSource {
+  return Object.freeze({
+    ...COMPACT_CHECKPOINT_SOURCE,
+    compactionId,
+    ...sourceCommandId === undefined ? {} : { sourceCommandId },
+  })
+}
+
 /**
  * Test whether a persisted message source identifies a compaction checkpoint.
  * @param source - source restored from a surface user message.
diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts
index 7b0bd25091..0085321333 100644
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -9,14 +9,17 @@
 
 import { Context, Service } from 'cordis'
 import type { Session } from '@deepseek-ai/dsh-session'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionResult } from './types.ts'
 
 export type { CompactionResult } from './types.ts'
+export { CompactionId } from './brand.ts'
 export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
 // The checkpoint source and its predicate are declared on the cordis-free
 // `./checkpoint` leaf so client and wire programs can name them without this
 // root's Context merge; the root stays the host-side entry point for both.
-export { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from './checkpoint.ts'
+export { COMPACT_CHECKPOINT_SOURCE, compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
+export type { CompactCheckpointSource } from './checkpoint.ts'
 
 /** Why automatic policy is asking a backend to consider compaction. */
 export type CompactionTrigger = 'pressure' | 'context-overflow'
@@ -126,6 +129,7 @@ export abstract class CompactService extends Service {
    *
    * @param agent - idle agent whose durable history should be compacted.
    * @param signal - cancellation scoped to this compaction request.
+   * @param sourceCommandId - initiating command identity for a manual compaction.
    * @returns the compaction result, or `null` when no safe useful range exists.
    * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
    * changed-span, summarization/shrink, commit-stage, or persistence failures;
@@ -135,6 +139,7 @@ export abstract class CompactService extends Service {
   abstract compactNow(
     agent: ManualCompactAgentContext,
     signal: AbortSignal,
+    sourceCommandId?: CommandId,
   ): Promise<CompactionResult | null>
 
   /**
diff --git a/packages/compact/compact/src/invariant.ts b/packages/compact/compact/src/invariant.ts
index 221d5aae09..adac557db5 100644
--- a/packages/compact/compact/src/invariant.ts
+++ b/packages/compact/compact/src/invariant.ts
@@ -1,8 +1,12 @@
 /** Package-owned compaction log-stream invariants. @module @deepseek-ai/dsh-compact/invariant */
 
 import type { Context } from 'cordis'
+import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { CompactionId } from './brand.ts'
+import { isCompactCheckpointSource } from './checkpoint.ts'
+import type { CompactCheckpointSource } from './checkpoint.ts'
 import type {} from './types.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-compact'
@@ -13,6 +17,8 @@ export const name = 'compact-invariant'
 export const inject = ['invariants']
 
 interface CompactionTrace {
+  compactionId: CompactionId
+  sourceCommandId: string | undefined
   startSeq: number
   turn: number | null
   summarized: boolean
@@ -24,11 +30,48 @@ interface SessionTrace {
 }
 
 type CompactionTransition =
-  | { kind: 'start'; startSeq: number; turn: number | null }
-  | { kind: 'summary'; startSeq: number; turn: number | null }
+  | { kind: 'start'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
+  | { kind: 'summary'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
   | { kind: 'end' }
   | { kind: 'end-seed' }
 
+/** Require a durable opaque identity to be a non-empty string. */
+function validateId(value: unknown, label: string, fail: InvariantFailure): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) fail(`${label} must be a non-empty string`)
+}
+
+/** Keep the optional initiating command identity stable across one transaction. */
+function validateSourceCommandId(
+  eventType: string,
+  value: unknown,
+  expected: string | undefined,
+  fail: InvariantFailure,
+): void {
+  if (value !== undefined) validateId(value, `${eventType} sourceCommandId`, fail)
+  if (value !== expected) {
+    fail(`${eventType} sourceCommandId ${String(value)} does not match compact/start sourceCommandId ${String(expected)}`)
+  }
+}
+
+/** Validate one replacement checkpoint against its open compaction transaction. */
+function validateCheckpoint(
+  trace: SessionTrace,
+  event: SessionEvent<'user/message'>,
+  fail: InvariantFailure,
+): void {
+  const source = event.data.source as typeof event.data.source & Partial<CompactCheckpointSource>
+  validateId(source.compactionId, 'compaction checkpoint compactionId', fail)
+  if (source.sourceCommandId !== undefined) {
+    validateId(source.sourceCommandId, 'compaction checkpoint sourceCommandId', fail)
+  }
+  const open = trace.compaction
+  if (open === undefined) fail('compaction checkpoint has no matching compact/start')
+  if (source.compactionId !== open.compactionId) {
+    fail(`compaction checkpoint id ${source.compactionId} does not match compact/start id ${open.compactionId}`)
+  }
+  validateSourceCommandId('compaction checkpoint', source.sourceCommandId, open.sourceCommandId, fail)
+}
+
 /** Compaction starts still unmatched when a later seed boundary made them stale. */
 function inheritedOrphanStartSeqs(
   events: readonly SessionEvent[],
@@ -99,20 +142,44 @@ function validateCompactionEvent(
   fail: InvariantFailure,
 ): CompactionTransition | undefined {
   if (event.type === 'session/end-seed') return { kind: 'end-seed' }
+  if (event.type === 'user/message'
+    && isReplacementSurfaceEvent(event)
+    && isCompactCheckpointSource(event.data.source)) {
+    validateCheckpoint(trace, event, fail)
+    return undefined
+  }
   if (event.type !== 'compact/start' && event.type !== 'compact/summary' && event.type !== 'compact/end') {
     return undefined
   }
   const open = trace.compaction
   if (event.type === 'compact/start') {
+    validateId(event.data.compactionId, 'compact/start compactionId', fail)
+    if (event.data.sourceCommandId !== undefined) {
+      validateId(event.data.sourceCommandId, 'compact/start sourceCommandId', fail)
+    }
     if (open !== undefined) {
       const owner = open.turn === null ? 'standalone compaction' : `turn ${open.turn}`
       fail(`compact/start while ${owner} is still compacting`)
     }
     validateOwner(event.data.turn, trace.openTurn, event.type, fail)
-    return { kind: 'start', startSeq: event.seq, turn: event.data.turn }
+    return {
+      kind: 'start',
+      compactionId: event.data.compactionId,
+      sourceCommandId: event.data.sourceCommandId,
+      startSeq: event.seq,
+      turn: event.data.turn,
+    }
   }
   if (event.type === 'compact/summary') {
+    validateId(event.data.compactionId, 'compact/summary compactionId', fail)
+    if (event.data.sourceCommandId !== undefined) {
+      validateId(event.data.sourceCommandId, 'compact/summary sourceCommandId', fail)
+    }
     if (open === undefined) fail('compact/summary has no matching compact/start')
+    if (event.data.compactionId !== open.compactionId) {
+      fail(`compact/summary id ${event.data.compactionId} does not match compact/start id ${open.compactionId}`)
+    }
+    validateSourceCommandId('compact/summary', event.data.sourceCommandId, open.sourceCommandId, fail)
     validateOwner(open.turn, trace.openTurn, event.type, fail)
     if (open.summarized) fail('compact/summary repeated within one compaction')
     const seqs = event.data.shadowedSeqs
@@ -123,9 +190,23 @@ function validateCompactionEvent(
     if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) {
       fail('compact/summary shadowedTokenCount must be a non-negative safe integer')
     }
-    return { kind: 'summary', startSeq: open.startSeq, turn: open.turn }
+    return {
+      kind: 'summary',
+      compactionId: open.compactionId,
+      sourceCommandId: open.sourceCommandId,
+      startSeq: open.startSeq,
+      turn: open.turn,
+    }
+  }
+  validateId(event.data.compactionId, 'compact/end compactionId', fail)
+  if (event.data.sourceCommandId !== undefined) {
+    validateId(event.data.sourceCommandId, 'compact/end sourceCommandId', fail)
   }
   if (open === undefined) fail('compact/end has no matching compact/start')
+  if (event.data.compactionId !== open.compactionId) {
+    fail(`compact/end id ${event.data.compactionId} does not match compact/start id ${open.compactionId}`)
+  }
+  validateSourceCommandId('compact/end', event.data.sourceCommandId, open.sourceCommandId, fail)
   if (event.data.turn !== open.turn) {
     fail(`compact/end owner ${String(event.data.turn)} does not match compact/start owner ${String(open.turn)}`)
   }
@@ -142,6 +223,8 @@ function applyCompactionTransition(
 ): CompactionTrace | undefined {
   if (transition.kind === 'start') {
     return {
+      compactionId: transition.compactionId,
+      sourceCommandId: transition.sourceCommandId,
       startSeq: transition.startSeq,
       turn: transition.turn,
       summarized: false,
@@ -149,6 +232,8 @@ function applyCompactionTransition(
   }
   if (transition.kind === 'summary') {
     return {
+      compactionId: transition.compactionId,
+      sourceCommandId: transition.sourceCommandId,
       startSeq: transition.startSeq,
       turn: transition.turn,
       summarized: true,
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index 4429e8b291..c321be426e 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -8,6 +8,8 @@
  */
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { CompactionId } from './brand.ts'
 
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
@@ -16,7 +18,7 @@ declare module '@deepseek-ai/dsh-session' {
      * `compact/end`. A numbered owner is strictly enclosed by that open turn;
      * `null` identifies a standalone manual transaction between turns.
      */
-    'compact/start': { turn: number | null }
+    'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
     /**
      * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
      * The summary content is in `data.summary`; the actual surface replacement
@@ -27,6 +29,8 @@ declare module '@deepseek-ai/dsh-session' {
      * before it (`compact/prune` documents the shared protocol).
      */
     'compact/summary': {
+      compactionId: CompactionId
+      sourceCommandId?: CommandId
       summary: ContentBlock[]
       shadowedRange: { start: number; end: number }
       shadowedSeqs: number[]
@@ -62,7 +66,7 @@ declare module '@deepseek-ai/dsh-session' {
      * Marks the end of a compaction — log-only, releases the lock. Its owner
      * matches `compact/start`; `error` records an unsuccessful attempt.
      */
-    'compact/end': { turn: number | null; error?: string }
+    'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
     /**
      * Shadow price of one model-free prune replacement — log-only, no
      * surfaceOp. The shared shadow-price protocol: a surface `replace` event
@@ -85,6 +89,10 @@ declare module '@deepseek-ai/dsh-session' {
 
 /** Result of a successful compaction operation. */
 export interface CompactionResult {
+  /** Stable identity shared by this compaction's complete durable lifecycle. */
+  compactionId: CompactionId
+  /** Human command that initiated this compaction, when it was manual. */
+  sourceCommandId?: CommandId
   /** The seq of the appended `compact/start` event. */
   startSeq: number
   /** The seq of the appended `compact/summary` event. */
diff --git a/packages/compact/compact/tsconfig.json b/packages/compact/compact/tsconfig.json
index 673ee51547..a231786c32 100644
--- a/packages/compact/compact/tsconfig.json
+++ b/packages/compact/compact/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
@@ -17,6 +20,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/compact/compact/tsdown.config.ts b/packages/compact/compact/tsdown.config.ts
new file mode 100644
index 0000000000..6284421125
--- /dev/null
+++ b/packages/compact/compact/tsdown.config.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsdown'
+
+/** Builds each published entry as a self-contained file admitted by the package whitelist. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+])
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 2ec5a1bb25..63c5b2cb9b 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -30,7 +30,7 @@ declare module '@deepseek-ai/dsh-session' {
      * with `tool/code-dispatch` by `subCallId` (timing = the two events'
      * `time` fields).
      */
-    'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+    'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
     /**
      * One bridged sub-dispatch SETTLING: the pairing ids (matching the
      * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
@@ -46,7 +46,7 @@ declare module '@deepseek-ai/dsh-session' {
      * before returning), so its execution-enclosure relation holds by
      * construction.
      */
-    'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+    'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
   }
 }
 
@@ -502,6 +502,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
         const subCallId = CallId(`${String(exec.callId)}:code:${n}`)
         const input = {
           callId: subCallId,
+          rootCallId: exec.rootCallId,
           name,
           arguments: normalized.dispatched,
           ...exec.agent ? { agent: exec.agent } : {},
@@ -539,6 +540,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
                 content: result.content,
               })
               agent.session.append('tool/code-dispatch', {
+                rootCallId: exec.rootCallId,
                 parentCallId: exec.callId,
                 subCallId,
                 name,
@@ -563,6 +565,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
             },
             async start(): Promise<void> {
               exec.agent?.session.append('tool/code-dispatch-start', {
+                rootCallId: exec.rootCallId,
                 parentCallId: exec.callId,
                 subCallId,
                 name,
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 7c2346e723..6338e54501 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -297,6 +297,11 @@ export type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]:
  */
 export interface ToolExecutionInput {
   readonly callId: CallId
+  /**
+   * Root model-requested call owning this execution tree. Callers omit it for
+   * a root execution; nested dispatchers propagate the enclosing value.
+   */
+  readonly rootCallId?: CallId
   readonly name: string
   /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
@@ -352,6 +357,8 @@ export interface CodeDispatchLog {
  * observers run.
  */
 export interface ToolExecution extends ToolExecutionInput {
+  /** Root model-requested call, resolved for every root and nested execution. */
+  readonly rootCallId: CallId
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
 }
@@ -1123,6 +1130,7 @@ export class ToolRegistry extends Service {
     const deferredContexts: UserMessage[] = []
     const token = createExecutionToken()
     const callId = exec.callId
+    const rootCallId = exec.rootCallId ?? callId
     const name = exec.name
     const agent = exec.agent
     const parent = exec.parent
@@ -1133,6 +1141,7 @@ export class ToolRegistry extends Service {
     const base = {
       token,
       callId,
+      rootCallId,
       name,
       signal,
       ...agent !== undefined ? { agent } : {},
diff --git a/packages/core/tools/src/invariant.ts b/packages/core/tools/src/invariant.ts
index 78666f5890..a0d9487857 100644
--- a/packages/core/tools/src/invariant.ts
+++ b/packages/core/tools/src/invariant.ts
@@ -33,9 +33,34 @@ function validateResult(
 const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
   const stages = new WeakMap<object, ToolStage>()
   const openTurns = new WeakMap<Session, number | null>()
+  const dispatchRoots = new WeakMap<Session, Map<string, string>>()
+  const validateDispatch = (session: Session, event: SessionEvent): void => {
+    if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return
+    const root = String(event.data.rootCallId)
+    const parent = String(event.data.parentCallId)
+    const child = String(event.data.subCallId)
+    if (root.length === 0 || parent.length === 0 || child.length === 0) {
+      fail(`${event.type} must carry non-empty rootCallId, parentCallId, and subCallId`)
+      return
+    }
+    const roots = dispatchRoots.get(session)
+    const known = roots?.get(child)
+    if (known !== undefined && known !== root) fail(`${event.type} changed rootCallId for subCallId ${child}`)
+    if (parent !== root && roots?.get(parent) !== root) {
+      fail(`${event.type} parentCallId ${parent} does not belong to rootCallId ${root}`)
+    }
+  }
+  const commitDispatch = (session: Session, event: SessionEvent): void => {
+    if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return
+    const roots = dispatchRoots.get(session) as Map<string, string>
+    roots.set(String(event.data.subCallId), String(event.data.rootCallId))
+  }
   const seed = (session: Session): number | null => {
     let openTurn: number | null = null
+    dispatchRoots.set(session, new Map())
     for (const event of session.events) {
+      validateDispatch(session, event)
+      commitDispatch(session, event)
       if (event.type === 'turn/start') openTurn = event.data.turn
       else if (event.type === 'turn/end') openTurn = null
       else if ((event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch')
@@ -51,12 +76,15 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
   for (const session of ctx.sessions.list()) seed(session)
   ctx.on('session/created', (session) => { seed(session) }, { global: true })
   ctx.on('session/event', (session, event) => {
+    validateDispatch(session, event)
+    commitDispatch(session, event)
     if (event.type === 'turn/start') openTurns.set(session, event.data.turn)
     else if (event.type === 'turn/end') openTurns.set(session, null)
   }, { global: true })
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName === 'session/event') {
       const [session, event] = args as [Session, SessionEvent]
+      validateDispatch(session, event)
       if ((event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch')
         && openTurnFor(session) === null) {
         fail(`${event.type} appended outside any open turn`)
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 94c4861e66..780569c159 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -37,6 +37,8 @@ export interface CommandInputDescriptor {
 
 /** Invocation passed to one registered command handler. */
 export interface CommandInvocation {
+  /** Pairing id already written to this invocation's `command/run` event. */
+  readonly commandId: CommandId
   /** Exact agent whose human-facing surface received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
@@ -389,7 +391,7 @@ export class CommandService extends Service {
       ...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
       source: { kind: 'user' },
     })
-    const invocation = Object.freeze({ agent, rawInput: parsed.rawInput, signal })
+    const invocation = Object.freeze({ commandId, agent, rawInput: parsed.rawInput, signal })
     let result: CommandResult
     try {
       const output = command.definition.handler(invocation)
diff --git a/packages/llm/llm-retry/package.json b/packages/llm/llm-retry/package.json
index d3b6afebba..1685d0e552 100644
--- a/packages/llm/llm-retry/package.json
+++ b/packages/llm/llm-retry/package.json
@@ -19,6 +19,10 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -29,6 +33,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
@@ -40,6 +45,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@cordisjs/plugin-include": "workspace:^",
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
diff --git a/packages/llm/llm-retry/src/brand.ts b/packages/llm/llm-retry/src/brand.ts
new file mode 100644
index 0000000000..41682cc9d1
--- /dev/null
+++ b/packages/llm/llm-retry/src/brand.ts
@@ -0,0 +1,13 @@
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Stable identity shared by every attempt in one request-step retry chain. */
+export type RetryId = Branded<'RetryId'>
+
+/**
+ * Brand an implementation-minted retry-chain identity.
+ * @param id - opaque retry identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function RetryId(id: string): RetryId {
+  return id as RetryId
+}
diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts
index 82b441fb8f..dcba1e2443 100644
--- a/packages/llm/llm-retry/src/index.ts
+++ b/packages/llm/llm-retry/src/index.ts
@@ -5,39 +5,26 @@
  * @module @deepseek-ai/dsh-llm-retry
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context, Events } from 'cordis'
 import z from 'schemastery'
 import type { Agent, RequestErrorAction } from '@deepseek-ai/dsh-agent'
 import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { RetryId } from './brand.ts'
+import type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
 
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-    'llm/retry': {
-      turn: number
-      step: number
-      provider: string
-      mode: 'normal'
-      policyKey: string
-      retry: number
-      maxRetries: number
-      delayMs: number
-      failure: LlmFailure
-    } | {
-      turn: number
-      step: number
-      provider: string
-      mode: 'always'
-      policyKey: string
-      retry: number
-      delayMs: number
-      failure: LlmFailure
-    }
+    'llm/retry': LlmRetryEventData
+    /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+    'llm/retry-started': LlmRetryStartedEventData
   }
 }
 
-export type { LlmRetryEventData } from './types.ts'
+export type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
+export { RetryId } from './brand.ts'
 
 export const name = 'llm-retry'
 export const inject = ['agents']
@@ -139,6 +126,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     policy: ResolvedRetryPolicy,
     policyKey: string,
     retry: number,
+    retryId: RetryId,
     delayMs: number,
     signal: AbortSignal,
   ): Promise<RequestErrorAction> {
@@ -146,6 +134,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     if (fusedSignal.aborted) return
     const eventData = policy.mode === 'normal'
       ? {
+        retryId,
         turn,
         step,
         provider,
@@ -157,6 +146,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
         failure,
       }
       : {
+        retryId,
         turn,
         step,
         provider,
@@ -168,6 +158,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
       }
     agent.session.append('llm/retry', eventData)
     if (!await cancellableDelay(delayMs, fusedSignal)) return
+    agent.session.append('llm/retry-started', { retryId, turn, step, retry })
     return { kind: 'retry' }
   }
 
@@ -207,6 +198,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     const previousRetry = priorPolicyRetry?.data.retry ?? 0
     if (policy.mode === 'normal' && previousRetry >= policy.maxRetries) return next()
     const retry = previousRetry + 1
+    const retryId = priorPolicyRetry?.data.retryId ?? RetryId(randomUUID())
     let delayMs: number
     if (failure.providerRetryAfterMs !== undefined
       && Number.isFinite(failure.providerRetryAfterMs)
@@ -221,7 +213,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
       delayMs = localDelay(policy, retry, random)
     }
 
-    return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, delayMs, signal)
+    return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal)
   }
 
   const disposeListener = ctx.on('agent/request-error', (
diff --git a/packages/llm/llm-retry/src/invariant.ts b/packages/llm/llm-retry/src/invariant.ts
index d324c012f2..1680873c0c 100644
--- a/packages/llm/llm-retry/src/invariant.ts
+++ b/packages/llm/llm-retry/src/invariant.ts
@@ -47,7 +47,10 @@ function validateRetry(
   event: SessionEvent<'llm/retry'>,
   fail: InvariantFailure,
 ): void {
-  const { turn, step, provider, mode, policyKey, retry, delayMs } = event.data
+  const { retryId, turn, step, provider, mode, policyKey, retry, delayMs } = event.data
+  if (typeof retryId !== 'string' || retryId.length === 0) {
+    fail('llm/retry retryId must be a non-empty string')
+  }
   const failure: unknown = event.data.failure
   validateFailure(failure, fail)
   if (!Number.isSafeInteger(retry) || retry < 1) {
@@ -110,12 +113,43 @@ function validateRetry(
   if (retry !== expectedRetry) {
     fail(`llm/retry retry ${retry} must equal provider policy retry ${expectedRetry}`)
   }
+  if (priorPolicyRetry !== undefined && priorPolicyRetry.data.retryId !== retryId) {
+    fail('llm/retry must preserve retryId across one provider-policy chain')
+  }
+  if (priorPolicyRetry === undefined && history.some(prior =>
+    (prior.type === 'llm/retry' || prior.type === 'llm/retry-started')
+    && prior.data.retryId === retryId)) {
+    fail(`llm/retry retryId ${JSON.stringify(retryId)} is already owned by another chain`)
+  }
+}
+
+/** Validate one wait-complete transition against its scheduled attempt. */
+function validateStarted(
+  history: readonly SessionEvent[],
+  event: SessionEvent<'llm/retry-started'>,
+  fail: InvariantFailure,
+): void {
+  const { retryId, turn, step, retry } = event.data
+  if (typeof retryId !== 'string' || retryId.length === 0) {
+    fail('llm/retry-started retryId must be a non-empty string')
+  }
+  const scheduled = history.findLast((prior): prior is SessionEvent<'llm/retry'> =>
+    prior.type === 'llm/retry' && prior.data.retryId === retryId && prior.data.retry === retry)
+  if (scheduled === undefined) fail('llm/retry-started pairs no prior scheduled attempt')
+  if (scheduled.data.turn !== turn || scheduled.data.step !== step) {
+    fail('llm/retry-started turn/step must match its scheduled attempt')
+  }
+  if (history.some(prior => prior.type === 'llm/retry-started'
+    && prior.data.retryId === retryId && prior.data.retry === retry)) {
+    fail('llm/retry-started repeats one scheduled attempt')
+  }
 }
 
 /** Validate every retry record already present in one loaded session. */
 function validateSession(session: Session, fail: InvariantFailure): void {
   for (const [index, event] of session.events.entries()) {
     if (event.type === 'llm/retry') validateRetry(session.events.slice(0, index), event, fail)
+    else if (event.type === 'llm/retry-started') validateStarted(session.events.slice(0, index), event, fail)
   }
 }
 
@@ -127,6 +161,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     if (eventName !== 'session/event') return
     const [session, event] = args as [Session, SessionEvent]
     if (event.type === 'llm/retry') validateRetry(session.events, event, fail)
+    else if (event.type === 'llm/retry-started') validateStarted(session.events, event, fail)
   }, { global: true })
 }, { inject: ['sessions'] })
 
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index f59aef4495..12820889dd 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,8 +1,10 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
+import type { RetryId } from './brand.ts'
 
 /** Durable payload recorded before one provider-routed model-request retry wait. */
 export type LlmRetryEventData =
   | {
+    retryId: RetryId
     turn: number
     step: number
     provider: string
@@ -13,7 +15,9 @@ export type LlmRetryEventData =
     delayMs: number
     failure: LlmFailure
   }
+
   | {
+    retryId: RetryId
     turn: number
     step: number
     provider: string
@@ -23,3 +27,11 @@ export type LlmRetryEventData =
     delayMs: number
     failure: LlmFailure
   }
+
+/** Durable transition recorded after one retry delay completes. */
+export interface LlmRetryStartedEventData {
+  retryId: RetryId
+  turn: number
+  step: number
+  retry: number
+}
diff --git a/packages/llm/llm-retry/tsconfig.json b/packages/llm/llm-retry/tsconfig.json
index 48c858951a..41e9ca65c5 100644
--- a/packages/llm/llm-retry/tsconfig.json
+++ b/packages/llm/llm-retry/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },

From dec4d1ffdb1d71c345bb32e72d3fbc039c4d45d6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:13:04 +0800
Subject: [PATCH 232/262] ci(wine): resume partial Node downloads

---
 scripts/wine-windows-gates.sh | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index d4798fdd7b..34e58274ce 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -74,27 +74,44 @@ trap cleanup EXIT
 mkdir -p "$cache_dir" "$scratch/logs"
 
 # ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
-curl_download_args=(
+curl_metadata_args=(
   --fail --silent --show-error --location
   --retry 3 --retry-all-errors --retry-delay 2
-  --connect-timeout 10 --max-time 90 --retry-max-time 240
+  --connect-timeout 10 --max-time 30 --retry-max-time 120
 )
 
+download_node_archive() {
+  local url="$1" output="$2" attempt status=0
+  for attempt in 1 2 3; do
+    if curl --fail --silent --show-error --location \
+      --continue-at - --connect-timeout 10 --max-time 300 \
+      --speed-limit 1024 --speed-time 30 \
+      -o "$output" "$url"; then
+      return 0
+    else
+      status=$?
+    fi
+    (( attempt < 3 )) || break
+    echo "wine-windows-gates: Windows Node archive transfer failed (exit $status) on attempt $attempt; resuming partial download" >&2
+  done
+  return "$status"
+}
+
 provision_node() {
   # Latest release of the primary line, checksum-verified against the same
   # dist directory. Bound and retry every transfer so a stalled nodejs.org
   # response cannot consume the entire CI job. Offline runs fall back to the
   # newest cached zip, loudly.
   local version zip
-  version="$(curl "${curl_download_args[@]}" https://nodejs.org/dist/index.json 2> /dev/null \
+  version="$(curl "${curl_metadata_args[@]}" https://nodejs.org/dist/index.json 2> /dev/null \
     | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
     || true)"
   if [ -n "$version" ]; then
     zip="$cache_dir/node-$version-win-x64.zip"
     if [ ! -f "$zip" ]; then
-      curl "${curl_download_args[@]}" -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
+      download_node_archive "https://nodejs.org/dist/$version/node-$version-win-x64.zip" "$zip.tmp"
       local expected
-      expected="$(curl "${curl_download_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
+      expected="$(curl "${curl_metadata_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
         | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
       [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
       verify_sha256 "$expected" "$zip.tmp"

From 81d688600677eabab42fbb9f364ed5a3d7ce7b30 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:19 +0800
Subject: [PATCH 233/262] feat(client): add conversation node engine and
 contextual slots

---
 packages/client/runtime/package.json          |   1 -
 .../src/client/contract/conversation.ts       | 261 ++++++
 .../conversation/definition-registry.ts       |  60 ++
 .../src/client/conversation/event-registry.ts |  56 ++
 .../src/client/conversation/view-registry.ts  |  26 +
 packages/client/runtime/src/client/index.ts   |  39 +-
 .../src/client/sessions/assistant-timing.ts   |   7 +-
 .../client/sessions/conversation-assembler.ts | 798 ++++++++++++++++++
 .../sessions/conversation-location-index.ts   | 508 +++++++++++
 .../src/client/sessions/conversation.ts       |  91 +-
 .../runtime/src/client/sessions/manager.ts    |  15 +-
 .../runtime/src/client/sessions/partial.ts    |   9 +-
 .../src/client/sessions/queue-mirror.ts       |  74 ++
 .../runtime/src/client/sessions/service.ts    |  36 +-
 .../runtime/src/client/sessions/session.ts    | 454 ++--------
 .../src/client/sessions/transcript-adapter.ts | 409 ---------
 packages/client/runtime/src/client/slots.ts   |   2 +-
 packages/client/ui-slots/src/index.ts         | 192 ++++-
 packages/client/ui-slots/src/renderer.ts      |   4 +-
 .../client/web-react/src/scoped-slots.tsx     | 333 ++++++--
 20 files changed, 2475 insertions(+), 900 deletions(-)
 create mode 100644 packages/client/runtime/src/client/contract/conversation.ts
 create mode 100644 packages/client/runtime/src/client/conversation/definition-registry.ts
 create mode 100644 packages/client/runtime/src/client/conversation/event-registry.ts
 create mode 100644 packages/client/runtime/src/client/conversation/view-registry.ts
 create mode 100644 packages/client/runtime/src/client/sessions/conversation-assembler.ts
 create mode 100644 packages/client/runtime/src/client/sessions/conversation-location-index.ts
 create mode 100644 packages/client/runtime/src/client/sessions/queue-mirror.ts
 delete mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts

diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index 3d97e70de5..3176428b36 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -33,7 +33,6 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-client-connection": "workspace:^",
-    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
diff --git a/packages/client/runtime/src/client/contract/conversation.ts b/packages/client/runtime/src/client/contract/conversation.ts
new file mode 100644
index 0000000000..fb98965d25
--- /dev/null
+++ b/packages/client/runtime/src/client/contract/conversation.ts
@@ -0,0 +1,261 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
+
+/** One raw log event plus its optional envelope-level presentation view. */
+export interface ConversationEventInput {
+  readonly event: SessionEvent
+  readonly view: ToolEventView | undefined
+}
+
+/** Definition-local identity and lifecycle role extracted from one event. */
+export interface ConversationMatchResult {
+  readonly id: string
+  readonly role: 'start' | 'update'
+}
+
+/** Merge-extensible business values published against one Turn. */
+export interface ConversationTurnDataMap {}
+
+/** Merge-extensible business values published against one Step. */
+export interface ConversationStepDataMap {}
+
+/** Stable keyed reader for independently owned Location business values. */
+export interface ConversationLocationDataStore<DataMap extends object> {
+  /**
+   * Read one business value without exposing another owner's mutable State.
+   * @param key - declaration-merged business key.
+   * @returns latest immutable value, when its owning Context has published one.
+   */
+  get<Key extends keyof DataMap & string>(key: Key): Readonly<DataMap[Key]> | undefined
+}
+
+interface ConversationLocationDataValue {
+  readonly kind: 'turn' | 'step'
+  readonly turn: number
+  readonly step?: number
+  readonly key: string
+  readonly value: unknown
+}
+
+type RegisteredTurnData = {
+  [Key in keyof ConversationTurnDataMap & string]: {
+    readonly kind: 'turn'
+    readonly turn: number
+    readonly key: Key
+    readonly value: ConversationTurnDataMap[Key]
+  }
+}[keyof ConversationTurnDataMap & string]
+
+type RegisteredStepData = {
+  [Key in keyof ConversationStepDataMap & string]: {
+    readonly kind: 'step'
+    readonly turn: number
+    readonly step: number
+    readonly key: Key
+    readonly value: ConversationStepDataMap[Key]
+  }
+}[keyof ConversationStepDataMap & string]
+
+/** One Definition-owned value attached to an Engine-owned Turn or Step. */
+export type ConversationLocationData =
+  [keyof ConversationTurnDataMap | keyof ConversationStepDataMap] extends [never]
+    ? ConversationLocationDataValue
+    : RegisteredTurnData | RegisteredStepData
+
+/** Immutable resolved boundary for one Agent step. */
+export interface StepLocation {
+  readonly turn: number
+  readonly step: number
+  readonly start: SessionEvent<'step/start'> | undefined
+  readonly end: SessionEvent<'step/end'> | undefined
+  readonly status: 'open' | 'closed' | 'unknown'
+  /** Stable reader for Step-scoped business values. */
+  readonly data: ConversationLocationDataStore<ConversationStepDataMap>
+}
+
+/** Immutable resolved boundary for one Agent turn. */
+export interface TurnLocation {
+  readonly turn: number
+  readonly start: SessionEvent<'turn/start'> | undefined
+  readonly end: SessionEvent<'turn/end'> | undefined
+  readonly status: 'open' | 'closed' | 'unknown'
+  readonly steps: readonly StepLocation[]
+  /** Stable reader for Turn-scoped business values. */
+  readonly data: ConversationLocationDataStore<ConversationTurnDataMap>
+}
+
+/** Engine-owned placement of one matched event in the Session hierarchy. */
+export type ConversationLocation =
+  | { readonly kind: 'session' }
+  | { readonly kind: 'turn'; readonly turn: TurnLocation }
+  | { readonly kind: 'step'; readonly turn: TurnLocation; readonly step: StepLocation }
+  | { readonly kind: 'unresolved' }
+
+/** One event accepted by a Definition, with its current resolved Location. */
+export interface ConversationMatch extends ConversationEventInput {
+  readonly role: 'start' | 'update'
+  readonly location: ConversationLocation
+}
+
+/** Target-neutral identity returned by a business Definition. */
+export interface ConversationViewNode {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly target: string
+  readonly data: unknown
+}
+
+/** Final Chat render unit produced directly by a business Definition. */
+export interface ChatConversationViewNode extends ConversationViewNode {
+  readonly target: 'chat'
+  readonly anchorSeq: number
+  readonly location: ConversationLocation
+  readonly visibility: 'visible' | 'hidden'
+}
+
+/** Immutable public view of an assembled business Context. */
+export interface ConversationNodeContext<State = unknown> {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly matches: readonly ConversationMatch[]
+  readonly start: ConversationMatch | undefined
+  readonly state: State | undefined
+  readonly current: ReadonlyMap<string, ConversationViewNode | null>
+}
+
+/** Read-only predecessor returned to a Definition's start function. */
+export interface ConversationPreviousContext<State = unknown> {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly startSeq: number
+  readonly state: Readonly<State>
+  readonly matches: readonly ConversationMatch[]
+}
+
+/** Strictly-backward Context lookup available while a start is evaluated. */
+export interface ConversationContextReader {
+  /**
+   * Find the active Context of `kind` with the greatest start seq below the
+   * current start event.
+   * @param kind - Definition kind to query.
+   * @returns the nearest predecessor, or undefined when absent in the current window.
+   */
+  previous<State>(kind: string): ConversationPreviousContext<State> | undefined
+}
+
+/** Requested cadence for materializing updated business State into view Nodes. */
+export type ConversationPublication = 'none' | 'animation-frame' | 'immediate'
+
+/** Engine-owned Location data publication phase. */
+export type ConversationLocationDataScope = 'step' | 'turn'
+
+/** One independently registered business Event-to-Node state machine. */
+export interface ConversationNodeDefinition<State = unknown> {
+  readonly kind: string
+  /**
+   * Extract this Definition's stable business identity from one event.
+   * @param event - raw Session event; no Context or history access is available.
+   * @returns identity and lifecycle role, or null when unrelated.
+   */
+  match(event: SessionEvent): ConversationMatchResult | null
+  /**
+   * Create State from the unique start Match.
+   * @param context - complete evidence currently collected for the Context.
+   * @param match - the start Match.
+   * @param reader - strictly-backward read-only Context lookup.
+   * @returns the State adopted by the engine.
+   */
+  start(
+    context: ConversationNodeContext<State>,
+    match: ConversationMatch,
+    reader: ConversationContextReader,
+  ): State
+  /**
+   * Apply one post-start update Match.
+   * @param context - Context with its current State.
+   * @param match - update Match in ascending log order.
+   * @returns the State adopted by the engine.
+   */
+  update(
+    context: ConversationNodeContext<State> & { readonly state: State },
+    match: ConversationMatch,
+  ): State
+  /**
+   * Select publication cadence for one accepted Match.
+   * @param match - accepted Match.
+   * @returns requested cadence; omission defaults to immediate.
+   */
+  publication?(match: ConversationMatch): ConversationPublication
+  /**
+   * Publish this Definition's read-only business value for one Location phase.
+   * The Engine evaluates every Definition first for Step and then for Turn,
+   * owns replacement/removal, and rejects another Context trying to publish
+   * the same Location key.
+   * @param context - latest complete Context.
+   * @param scope - Location hierarchy level currently being materialized.
+   * @returns current Location value, or null while unavailable.
+   */
+  buildLocationData?(
+    context: ConversationNodeContext<State>,
+    scope: ConversationLocationDataScope,
+  ): ConversationLocationData | null
+  /**
+   * Materialize one final Node for a registered view target.
+   * @param context - latest complete Context.
+   * @param target - registered view target such as `chat`.
+   * @returns final Node, or null when this Context is not currently visible.
+   */
+  buildViewNode(
+    context: ConversationNodeContext<State>,
+    target: string,
+  ): ConversationViewNode | null
+}
+
+/** Reference-stable Turn/Step facts published beside view Nodes. */
+export interface ConversationTimelineSnapshot {
+  readonly turnOrder: readonly number[]
+  readonly turns: ReadonlyMap<number, TurnLocation>
+}
+
+/** Per-Session incremental builder for one view target. */
+export interface ConversationViewBuilder<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+  readonly empty: Snapshot
+  /**
+   * Replace the low-frequency complete materialized Node set.
+   * @param input - complete Nodes and current timeline.
+   * @returns next view snapshot.
+   */
+  replace(input: {
+    readonly nodes: readonly Node[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): Snapshot
+  /**
+   * Apply only Nodes whose materialized values changed in this transaction.
+   * @param input - changed Nodes and current timeline.
+   * @returns next view snapshot.
+   */
+  apply(input: {
+    readonly upserts: readonly Node[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): Snapshot
+}
+
+/** Registry contribution that creates one isolated view builder per Session. */
+export interface ConversationViewDefinition<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+  readonly target: string
+  /** @returns a new Session-owned incremental builder. */
+  create(): ConversationViewBuilder<Node, Snapshot>
+}
+
+/**
+ * Build a stable collision-free key for one Definition-local business identity.
+ * @param kind - Definition kind.
+ * @param id - Definition-local business identity.
+ * @returns engine-owned Context key.
+ */
+export function conversationContextKey(kind: string, id: string): string {
+  return `${kind.length}:${kind}${id}`
+}
diff --git a/packages/client/runtime/src/client/conversation/definition-registry.ts b/packages/client/runtime/src/client/conversation/definition-registry.ts
new file mode 100644
index 0000000000..d43f494e1a
--- /dev/null
+++ b/packages/client/runtime/src/client/conversation/definition-registry.ts
@@ -0,0 +1,60 @@
+import { Service } from 'cordis'
+
+/** Shared lifecycle and stable-entry storage for one Conversation Definition registry. */
+export abstract class ConversationDefinitionRegistry<Definition> extends Service {
+  protected readonly definitions = new Map<string, Definition>()
+  private listeners = new Set<() => void>()
+  private cached: readonly Definition[] = []
+
+  /**
+   * Return reference-stable Definitions in registration order.
+   * @returns current Definitions.
+   */
+  entries(): readonly Definition[] {
+    return this.cached
+  }
+
+  /**
+   * Observe low-frequency registry changes.
+   * @param listener - synchronous invalidation callback.
+   * @returns unsubscribe callback.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /**
+   * Register one uniquely keyed Definition for the caller's lifetime.
+   * @param key - registry-local unique key.
+   * @param definition - contributed Definition.
+   * @param duplicateMessage - error raised when the key is already owned.
+   * @param effectName - Cordis effect diagnostic label.
+   * @returns idempotent disposer.
+   */
+  protected registerDefinition(
+    key: string,
+    definition: Definition,
+    duplicateMessage: string,
+    effectName: string,
+  ): () => void {
+    if (this.definitions.has(key)) throw new Error(duplicateMessage)
+    const owner = this.ctx
+    const dispose = owner.effect(() => {
+      this.definitions.set(key, definition)
+      this.refresh()
+      return () => {
+        if (this.definitions.get(key) !== definition) return
+        this.definitions.delete(key)
+        this.refresh()
+      }
+    }, effectName)
+    return () => { void dispose() }
+  }
+
+  /** Refresh cached entries and synchronously invalidate subscribers. */
+  protected refresh(): void {
+    this.cached = [...this.definitions.values()]
+    for (const listener of this.listeners) listener()
+  }
+}
diff --git a/packages/client/runtime/src/client/conversation/event-registry.ts b/packages/client/runtime/src/client/conversation/event-registry.ts
new file mode 100644
index 0000000000..6935ed1741
--- /dev/null
+++ b/packages/client/runtime/src/client/conversation/event-registry.ts
@@ -0,0 +1,56 @@
+import type { Context } from 'cordis'
+import type { ConversationNodeDefinition } from '../contract/conversation.ts'
+import { ConversationDefinitionRegistry } from './definition-registry.ts'
+
+/** Runtime registry of independently owned Conversation business Definitions. */
+export class ConversationEventRegistry extends ConversationDefinitionRegistry<ConversationNodeDefinition> {
+  private fallback: ConversationNodeDefinition | undefined
+
+  /** @param ctx - owning Client Runtime context. */
+  constructor(ctx: Context) {
+    super(ctx, 'conversationEvents')
+  }
+
+  /**
+   * Register a uniquely named business Definition for the caller's lifetime.
+   * @param definition - Definition contribution.
+   * @returns idempotent disposer.
+   */
+  register(definition: ConversationNodeDefinition): () => void {
+    return this.registerDefinition(
+      definition.kind,
+      definition,
+      `conversation Definition "${definition.kind}" is already registered`,
+      `conversationEvents.register(${JSON.stringify(definition.kind)})`,
+    )
+  }
+
+  /**
+   * Register the sole fallback used only when no ordinary Definition matches.
+   * @param definition - fallback Definition.
+   * @returns idempotent disposer.
+   */
+  registerFallback(definition: ConversationNodeDefinition): () => void {
+    if (this.fallback !== undefined) throw new Error('conversation fallback Definition is already registered')
+    const owner = this.ctx
+    const dispose = owner.effect(() => {
+      this.fallback = definition
+      this.refresh()
+      return () => {
+        if (this.fallback !== definition) return
+        this.fallback = undefined
+        this.refresh()
+      }
+    }, `conversationEvents.registerFallback(${JSON.stringify(definition.kind)})`)
+    return () => { void dispose() }
+  }
+
+  /**
+   * Return the current unmatched-event fallback.
+   * @returns installed fallback, when present.
+   */
+  fallbackEntry(): ConversationNodeDefinition | undefined {
+    return this.fallback
+  }
+
+}
diff --git a/packages/client/runtime/src/client/conversation/view-registry.ts b/packages/client/runtime/src/client/conversation/view-registry.ts
new file mode 100644
index 0000000000..1e2e53e141
--- /dev/null
+++ b/packages/client/runtime/src/client/conversation/view-registry.ts
@@ -0,0 +1,26 @@
+import type { Context } from 'cordis'
+import type { ConversationViewDefinition } from '../contract/conversation.ts'
+import { ConversationDefinitionRegistry } from './definition-registry.ts'
+
+/** Runtime registry of per-target Conversation snapshot builders. */
+export class ConversationViewRegistry extends ConversationDefinitionRegistry<ConversationViewDefinition> {
+
+  /** @param ctx - owning Client Runtime context. */
+  constructor(ctx: Context) {
+    super(ctx, 'conversationViews')
+  }
+
+  /**
+   * Register a uniquely named view builder factory for the caller's lifetime.
+   * @param definition - target builder contribution.
+   * @returns idempotent disposer.
+   */
+  register(definition: ConversationViewDefinition): () => void {
+    return this.registerDefinition(
+      definition.target,
+      definition,
+      `conversation view target "${definition.target}" is already registered`,
+      `conversationViews.register(${JSON.stringify(definition.target)})`,
+    )
+  }
+}
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index b7226c0085..fe1ce8f7b0 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -10,8 +10,27 @@ import { SessionHistoryService } from './session-history/service.ts'
 import { WorkspacesService } from './workspaces/service.ts'
 import type { ConversationSnapshot } from './sessions/conversation.ts'
 import type { UseProjection } from './sessions/projection-store.ts'
+import { ConversationEventRegistry } from './conversation/event-registry.ts'
+import { ConversationViewRegistry } from './conversation/view-registry.ts'
+
+export { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
 
 export { SlotsService } from './slots.ts'
+export { ConversationEventRegistry } from './conversation/event-registry.ts'
+export { ConversationViewRegistry } from './conversation/view-registry.ts'
+export { ConversationNodeAssembler } from './sessions/conversation-assembler.ts'
+export { ConversationLocationIndex } from './sessions/conversation-location-index.ts'
+export { conversationContextKey } from './contract/conversation.ts'
+export type {
+  ChatConversationViewNode, ConversationContextReader, ConversationEventInput,
+  ConversationLocationData, ConversationLocationDataScope, ConversationLocationDataStore,
+  ConversationStepDataMap,
+  ConversationLocation, ConversationMatch, ConversationMatchResult,
+  ConversationNodeContext, ConversationNodeDefinition, ConversationPreviousContext,
+  ConversationPublication, ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewBuilder,
+  ConversationViewDefinition, ConversationViewNode, StepLocation, TurnLocation,
+} from './contract/conversation.ts'
+export type { ConversationRuntime } from './sessions/conversation-assembler.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { SessionHistoryService } from './session-history/service.ts'
@@ -49,11 +68,17 @@ export type {
 } from './contract/store.ts'
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, CommandNode, CompactionSummaryNode, ComposerPhase,
+  AssistantTiming, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot,
+  CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
-  RunningToolCall,
+  LegacyConversationSlice, PartialAssistant, RunningToolCall,
   SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
+export { EMPTY_CHAT_SNAPSHOT, toAssistantBlock, toAssistantBlocks } from './sessions/conversation.ts'
+export { emptyAssistantBlock } from './sessions/partial.ts'
+export { isTokenDelta } from './sessions/assistant-timing.ts'
+export { contextForm, contextProvenance } from './sessions/context-provenance.ts'
+export { displayFailureMessage } from './sessions/failure-display.ts'
 export type {
   ConversationContext, ConversationContextOriginKind,
 } from './sessions/conversation-context.ts'
@@ -165,6 +190,10 @@ declare module 'cordis' {
   }
   interface Context {
     slots: import('./slots.ts').SlotsService
+    /** Event-to-business-Context Definition registry. */
+    conversationEvents: import('./conversation/event-registry.ts').ConversationEventRegistry
+    /** Per-target Conversation snapshot builder registry. */
+    conversationViews: import('./conversation/view-registry.ts').ConversationViewRegistry
     /** The outward face only; the concrete service stays inside the runtime. */
     sessions: import('./contract/sessions.ts').ISessions
     /** Read-only history sources isolated from Chat sessions and workspace state. */
@@ -182,8 +211,12 @@ export const inject = ['connection', 'typert']
  */
 export function apply(ctx: Context): void {
   ctx.plugin(SlotsService)
+  const conversation = {
+    events: new ConversationEventRegistry(ctx),
+    views: new ConversationViewRegistry(ctx),
+  }
   const connection = ctx.get('connection') as ConnectionHandle
-  const sessions = new SessionsService(ctx, connection.api)
+  const sessions = new SessionsService(ctx, connection.api, conversation)
   ctx.typert.contexts.registerClient('agent', {
     identity: candidate => sessions.scopeOf(candidate),
   })
diff --git a/packages/client/runtime/src/client/sessions/assistant-timing.ts b/packages/client/runtime/src/client/sessions/assistant-timing.ts
index 021c679d04..3c54c9c36d 100644
--- a/packages/client/runtime/src/client/sessions/assistant-timing.ts
+++ b/packages/client/runtime/src/client/sessions/assistant-timing.ts
@@ -1,7 +1,6 @@
-// Shared assistant step-timing fold: both transcript projections (the live
-// window adapter and the trajectory history fold) derive AssistantTiming from
-// the same step/start -> first token delta -> assistant/message sequence, so
-// the derivation lives once here instead of drifting per projection.
+// Shared assistant step-timing fold: Chat Definitions and the Trajectory
+// history fold derive AssistantTiming from the same step/start -> first token
+// delta -> assistant/message sequence.
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { AssistantTiming } from './conversation.ts'
diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
new file mode 100644
index 0000000000..3b6fbd6266
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -0,0 +1,798 @@
+import type {
+  ConversationContextReader, ConversationEventInput, ConversationLocationData, ConversationMatch,
+  ConversationNodeContext, ConversationNodeDefinition, ConversationPreviousContext,
+  ConversationLocationDataScope, ConversationPublication, ConversationViewBuilder,
+  ConversationViewDefinition, ConversationViewNode,
+} from '../contract/conversation.ts'
+import { conversationContextKey } from '../contract/conversation.ts'
+import {
+  ConversationLocationIndex, type ConversationLocationDataChange,
+} from './conversation-location-index.ts'
+
+interface Dependency {
+  readonly kind: string
+  readonly key: string | undefined
+  readonly revision: number | undefined
+  readonly windowGap: boolean
+}
+
+interface InternalContext {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly definition: ConversationNodeDefinition
+  startSeq: number | undefined
+  start: ConversationMatch | undefined
+  matches: ConversationMatch[]
+  state: unknown
+  revision: number
+  readonly current: Map<string, ConversationViewNode | null>
+  readonly locationData: Record<ConversationLocationDataScope, ConversationLocationData | null>
+  dependencies: Map<string, Dependency>
+}
+
+interface PendingMatch {
+  readonly definition: ConversationNodeDefinition
+  readonly id: string
+  readonly match: ConversationMatch
+}
+
+interface ViewState {
+  readonly target: string
+  readonly builder: ConversationViewBuilder
+  snapshot: unknown
+}
+
+const PUBLICATION_RANK: Record<ConversationPublication, number> = {
+  none: 0,
+  'animation-frame': 1,
+  immediate: 2,
+}
+
+const LOCATION_DATA_SCOPES: readonly ConversationLocationDataScope[] = ['step', 'turn']
+
+function emptyLocationData(): Record<ConversationLocationDataScope, ConversationLocationData | null> {
+  return { step: null, turn: null }
+}
+
+function maximumPublication(
+  left: ConversationPublication,
+  right: ConversationPublication,
+): ConversationPublication {
+  return PUBLICATION_RANK[left] >= PUBLICATION_RANK[right] ? left : right
+}
+
+function startSeq(context: InternalContext): number | undefined {
+  return context.startSeq
+}
+
+function insertionIndex(contexts: readonly InternalContext[], seq: number): number {
+  let low = 0
+  let high = contexts.length
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2)
+    const candidate = contexts[middle]
+    if (candidate !== undefined && (candidate.startSeq as number) < seq) low = middle + 1
+    else high = middle
+  }
+  return low
+}
+
+function contextSnapshot<State>(context: InternalContext): ConversationNodeContext<State> {
+  return {
+    key: context.key,
+    kind: context.kind,
+    id: context.id,
+    matches: context.matches,
+    start: context.start,
+    state: context.state as State | undefined,
+    current: context.current,
+  }
+}
+
+function mergeMatches(
+  key: string,
+  additions: readonly ConversationMatch[],
+  existing: readonly ConversationMatch[],
+): ConversationMatch[] {
+  const merged: ConversationMatch[] = []
+  let added = 0
+  let current = 0
+  while (added < additions.length || current < existing.length) {
+    const left = additions[added]
+    const right = existing[current]
+    if (left !== undefined && right !== undefined && left.event.seq === right.event.seq) {
+      throw new Error(`conversation Context ${key} received duplicate Match ${left.event.seq}`)
+    }
+    if (right === undefined || (left !== undefined && left.event.seq < right.event.seq)) {
+      merged.push(left as ConversationMatch)
+      added++
+    } else {
+      merged.push(right)
+      current++
+    }
+  }
+  return merged
+}
+
+/** Event Registry subset consumed by a Session-owned Assembler. */
+export interface ConversationEventDefinitions {
+  /** @returns ordinary Definitions in registration order. */
+  entries(): readonly ConversationNodeDefinition[]
+  /** @returns unmatched-event fallback, when registered. */
+  fallbackEntry(): ConversationNodeDefinition | undefined
+}
+
+/** View Registry subset consumed by a Session-owned Assembler. */
+export interface ConversationViewDefinitions {
+  /** @returns view builder factories in registration order. */
+  entries(): readonly ConversationViewDefinition[]
+}
+
+/**
+ * Session-owned incremental engine that assembles business Contexts from a
+ * contiguous Event window and materializes registered view snapshots.
+ */
+export class ConversationNodeAssembler {
+  private readonly contexts = new Map<string, InternalContext>()
+  private readonly contextsByKind = new Map<string, InternalContext[]>()
+  private readonly contextsBySeq = new Map<number, Set<InternalContext>>()
+  private readonly inputs = new Map<number, ConversationEventInput>()
+  private readonly locationIndex = new ConversationLocationIndex()
+  private readonly dirty = new Set<InternalContext>()
+  private readonly revised = new Set<InternalContext>()
+  private readonly dependents = new Map<string, Set<InternalContext>>()
+  private readonly views = new Map<string, ViewState>()
+  private hasMore = false
+  private replacePending = true
+  private timelineDirty = true
+
+  /**
+   * @param eventDefinitions - live Event Definition registry.
+   * @param viewDefinitions - live view builder registry.
+   */
+  constructor(
+    private readonly eventDefinitions: ConversationEventDefinitions,
+    private readonly viewDefinitions: ConversationViewDefinitions,
+  ) {
+    this.resetViewBuilders()
+  }
+
+  /**
+   * Replace the complete loaded window after open, resync, or gap repair.
+   * @param entries - complete contiguous window.
+   * @param hasMore - whether older history remains outside the window.
+   * @returns immediate publication request.
+   */
+  replaceWindow(entries: readonly ConversationEventInput[], hasMore: boolean): ConversationPublication {
+    this.contexts.clear()
+    this.contextsByKind.clear()
+    this.contextsBySeq.clear()
+    this.inputs.clear()
+    this.dirty.clear()
+    this.revised.clear()
+    this.dependents.clear()
+    this.hasMore = hasMore
+    const sorted = [...entries].sort((left, right) => left.event.seq - right.event.seq)
+    for (const entry of sorted) this.inputs.set(entry.event.seq, entry)
+    this.locationIndex.rebuild(sorted)
+    this.timelineDirty = true
+    for (const entry of sorted) this.matchInput(entry)
+    this.replayDependencies()
+    this.revised.clear()
+    for (const context of this.contexts.values()) this.dirty.add(context)
+    this.replacePending = true
+    return 'immediate'
+  }
+
+  /**
+   * Add one contiguous live tail event without scanning existing Contexts.
+   * @param input - appended Event and optional wire view.
+   * @returns highest requested publication cadence.
+   */
+  append(input: ConversationEventInput): ConversationPublication {
+    if (this.inputs.has(input.event.seq)) return 'none'
+    this.revised.clear()
+    this.inputs.set(input.event.seq, input)
+    let publication: ConversationPublication = 'none'
+    if (isLocationBoundary(input.event.type)) {
+      const previousTimeline = this.locationIndex.snapshot()
+      const changed = this.locationIndex.appendBoundary(input.event)
+      if (this.locationIndex.snapshot() !== previousTimeline) {
+        this.timelineDirty = true
+        publication = 'immediate'
+      }
+      this.replayContexts(this.refreshMatchLocations(changed))
+      if (changed.size > 0) publication = 'immediate'
+    } else {
+      this.locationIndex.appendNonBoundary(input.event)
+    }
+    publication = maximumPublication(publication, this.matchInput(input))
+    if (this.replayRevisedDependents()) publication = 'immediate'
+    this.revised.clear()
+    return publication
+  }
+
+  /**
+   * Add an older page while preserving existing Context and view identities.
+   * @param entries - newly loaded older Events.
+   * @param hasMore - whether history still precedes the expanded window.
+   * @returns highest requested publication cadence.
+   */
+  prepend(entries: readonly ConversationEventInput[], hasMore: boolean): ConversationPublication {
+    this.revised.clear()
+    let publication: ConversationPublication = 'none'
+    const previousHasMore = this.hasMore
+    const fresh = entries
+      .filter(entry => !this.inputs.has(entry.event.seq))
+      .sort((left, right) => left.event.seq - right.event.seq)
+    for (const entry of fresh) this.inputs.set(entry.event.seq, entry)
+    this.hasMore = hasMore
+    const previousTimeline = this.locationIndex.snapshot()
+    const changedLocations = this.locationIndex.rebuild(this.sortedInputs())
+    if (this.locationIndex.snapshot() !== previousTimeline) this.timelineDirty = true
+    const affected = this.refreshMatchLocations(changedLocations)
+    const pending = new Map<string, PendingMatch[]>()
+    for (const entry of fresh) {
+      publication = maximumPublication(publication, this.collectInput(entry, pending))
+    }
+    this.applyPendingMatches(pending, affected)
+    this.replayContexts(affected)
+    if ((fresh.length > 0 || previousHasMore !== hasMore) && this.replayDependencies()) {
+      publication = 'immediate'
+    }
+    if (changedLocations.size > 0) publication = 'immediate'
+    this.revised.clear()
+    return publication
+  }
+
+  /**
+   * Rebuild against the current Registry set after a low-frequency plugin change.
+   * @returns immediate publication request.
+   */
+  rebuildRegistry(): ConversationPublication {
+    this.resetViewBuilders()
+    return this.replaceWindow(this.sortedInputs(), this.hasMore)
+  }
+
+  /**
+   * Materialize dirty Contexts and advance every registered view builder.
+   * @returns whether any view snapshot was rebuilt or incrementally applied.
+   */
+  flush(): boolean {
+    if (!this.replacePending && this.dirty.size === 0 && !this.timelineDirty) return false
+    if (this.replacePending) {
+      this.replaceLocationData()
+      const allByTarget = new Map<string, ConversationViewNode[]>()
+      for (const target of this.views.keys()) allByTarget.set(target, [])
+      for (const context of this.contexts.values()) {
+        for (const target of this.views.keys()) {
+          const node = this.buildNode(context, target)
+          context.current.set(target, node)
+          if (node !== null) allByTarget.get(target)?.push(node)
+        }
+      }
+      for (const view of this.views.values()) {
+        view.snapshot = view.builder.replace({
+          nodes: allByTarget.get(view.target) ?? [],
+          timeline: this.locationIndex.snapshot(),
+        })
+      }
+      this.replacePending = false
+      this.dirty.clear()
+      this.timelineDirty = false
+      return true
+    }
+
+    const upsertsByTarget = new Map<string, ConversationViewNode[]>()
+    for (const target of this.views.keys()) upsertsByTarget.set(target, [])
+    if (this.applyDirtyLocationData()) this.timelineDirty = true
+    for (const context of this.dirty) {
+      for (const target of this.views.keys()) {
+        const previous = context.current.get(target) ?? null
+        const node = this.buildNode(context, target)
+        if (node === null && previous !== null) {
+          throw new Error(
+            `conversation Definition "${context.kind}" withdrew materialized target "${target}"; return the same key with hidden visibility instead`,
+          )
+        }
+        context.current.set(target, node)
+        if (node !== null) upsertsByTarget.get(target)?.push(node)
+      }
+    }
+    this.dirty.clear()
+    const timelineDirty = this.timelineDirty
+    this.timelineDirty = false
+    for (const view of this.views.values()) {
+      const upserts = upsertsByTarget.get(view.target) ?? []
+      if (upserts.length === 0 && !timelineDirty) continue
+      view.snapshot = view.builder.apply({
+        upserts,
+        timeline: this.locationIndex.snapshot(),
+      })
+    }
+    return true
+  }
+
+  /**
+   * Read the latest snapshot of a registered target.
+   * @param target - registered view target.
+   * @returns target snapshot, or undefined when no builder is registered.
+   */
+  snapshot(target: string): unknown {
+    return this.views.get(target)?.snapshot
+  }
+
+  private sortedInputs(): ConversationEventInput[] {
+    return [...this.inputs.values()].sort((left, right) => left.event.seq - right.event.seq)
+  }
+
+  private matchInput(input: ConversationEventInput): ConversationPublication {
+    return this.dispatchInput(input, (definition, id, role) =>
+      this.acceptMatch(definition, id, role, input))
+  }
+
+  private collectInput(
+    input: ConversationEventInput,
+    pending: Map<string, PendingMatch[]>,
+  ): ConversationPublication {
+    return this.dispatchInput(input, (definition, id, role) => {
+      const key = conversationContextKey(definition.kind, id)
+      const match: ConversationMatch = {
+        ...input,
+        role,
+        location: this.locationIndex.locationOf(input.event),
+      }
+      const matches = pending.get(key) ?? []
+      matches.push({ definition, id, match })
+      pending.set(key, matches)
+      return definition.publication?.(match) ?? 'immediate'
+    })
+  }
+
+  private dispatchInput(
+    input: ConversationEventInput,
+    accept: (
+      definition: ConversationNodeDefinition,
+      id: string,
+      role: ConversationMatch['role'],
+    ) => ConversationPublication,
+  ): ConversationPublication {
+    let matched = false
+    let publication: ConversationPublication = 'none'
+    for (const definition of this.eventDefinitions.entries()) {
+      const result = definition.match(input.event)
+      if (result === null) continue
+      matched = true
+      publication = maximumPublication(publication, accept(definition, result.id, result.role))
+    }
+    if (!matched) {
+      const fallback = this.eventDefinitions.fallbackEntry()
+      const result = fallback?.match(input.event) ?? null
+      if (fallback !== undefined && result !== null) {
+        publication = maximumPublication(publication, accept(fallback, result.id, result.role))
+      }
+    }
+    return publication
+  }
+
+  private acceptMatch(
+    definition: ConversationNodeDefinition,
+    id: string,
+    role: ConversationMatch['role'],
+    input: ConversationEventInput,
+  ): ConversationPublication {
+    const key = conversationContextKey(definition.kind, id)
+    let context = this.contexts.get(key)
+    if (role === 'start' && context?.start !== undefined) {
+      throw new Error(`conversation Context ${key} received more than one start Match`)
+    }
+    if (context === undefined) {
+      context = {
+        key,
+        kind: definition.kind,
+        id,
+        definition,
+        startSeq: undefined,
+        start: undefined,
+        matches: [],
+        state: undefined,
+        revision: 0,
+        current: new Map(),
+        locationData: emptyLocationData(),
+        dependencies: new Map(),
+      }
+      this.contexts.set(key, context)
+    }
+    const match: ConversationMatch = {
+      ...input,
+      role,
+      location: this.locationIndex.locationOf(input.event),
+    }
+    const previous = context.matches.at(-1)
+    if (previous !== undefined && previous.event.seq >= input.event.seq) {
+      throw new Error(`conversation Context ${key} received non-appended Match ${input.event.seq}`)
+    }
+    if (role === 'start' && context.matches.length > 0) {
+      throw new Error(`conversation Context ${key} received an update before its start Match`)
+    }
+    context.matches.push(match)
+    if (role === 'start') {
+      context.startSeq = input.event.seq
+      context.start = match
+      this.indexStartedContext(context)
+    }
+    const owners = this.contextsBySeq.get(input.event.seq) ?? new Set<InternalContext>()
+    owners.add(context)
+    this.contextsBySeq.set(input.event.seq, owners)
+
+    if (role === 'start') {
+      this.replayContext(context)
+    } else if (context.state !== undefined) {
+      const typed = contextSnapshot(context) as ConversationNodeContext & { readonly state: unknown }
+      context.state = requireState(definition, 'update', definition.update(typed, match))
+      context.revision++
+      this.revised.add(context)
+    }
+    this.dirty.add(context)
+    return definition.publication?.(match) ?? 'immediate'
+  }
+
+  private applyPendingMatches(
+    pending: ReadonlyMap<string, readonly PendingMatch[]>,
+    affected: Set<InternalContext>,
+  ): void {
+    const startsByKind = new Map<string, InternalContext[]>()
+    for (const [key, entries] of pending) {
+      const first = entries[0]
+      if (first === undefined) continue
+      let context = this.contexts.get(key)
+      if (context === undefined) {
+        context = {
+          key,
+          kind: first.definition.kind,
+          id: first.id,
+          definition: first.definition,
+          startSeq: undefined,
+          start: undefined,
+          matches: [],
+          state: undefined,
+          revision: 0,
+          current: new Map(),
+          locationData: emptyLocationData(),
+          dependencies: new Map(),
+        }
+        this.contexts.set(key, context)
+      }
+      let discoveredStart: ConversationMatch | undefined
+      const additions = entries
+        .map((entry) => {
+          if (entry.definition !== context.definition || entry.id !== context.id) {
+            throw new Error(`conversation Context ${key} received inconsistent Definition identity`)
+          }
+          if (entry.match.role === 'start') {
+            if (discoveredStart !== undefined || context.start !== undefined) {
+              throw new Error(`conversation Context ${key} received more than one start Match`)
+            }
+            discoveredStart = entry.match
+          }
+          const owners = this.contextsBySeq.get(entry.match.event.seq) ?? new Set<InternalContext>()
+          owners.add(context)
+          this.contextsBySeq.set(entry.match.event.seq, owners)
+          return entry.match
+        })
+        .sort((left, right) => left.event.seq - right.event.seq)
+      context.matches = mergeMatches(context.key, additions, context.matches)
+      if (discoveredStart !== undefined) {
+        context.start = discoveredStart
+        context.startSeq = discoveredStart.event.seq
+        const starts = startsByKind.get(context.kind) ?? []
+        starts.push(context)
+        startsByKind.set(context.kind, starts)
+      }
+      if (context.start !== undefined && context.matches[0] !== context.start) {
+        throw new Error(`conversation Context ${context.key} received an update before its start Match`)
+      }
+      affected.add(context)
+      this.dirty.add(context)
+    }
+    for (const [kind, contexts] of startsByKind) this.indexStartedContexts(kind, contexts)
+  }
+
+  private replayContexts(contexts: ReadonlySet<InternalContext>): void {
+    const ordered = [...contexts].sort((left, right) =>
+      (left.startSeq ?? Number.POSITIVE_INFINITY) - (right.startSeq ?? Number.POSITIVE_INFINITY))
+    for (const context of ordered) {
+      if (context.start === undefined) {
+        context.state = undefined
+        this.dirty.add(context)
+        continue
+      }
+      this.replayContext(context)
+    }
+  }
+
+  private replayContext(context: InternalContext): void {
+    const start = context.start
+    if (start === undefined) {
+      context.state = undefined
+      return
+    }
+    if (context.matches[0] !== start) {
+      throw new Error(`conversation Context ${context.key} received an update before its start Match`)
+    }
+    const dependencies = new Map<string, Dependency>()
+    const reader = this.readerFor(start.event.seq, dependencies)
+    context.state = undefined
+    context.state = requireState(
+      context.definition,
+      'start',
+      context.definition.start(contextSnapshot(context), start, reader),
+    )
+    this.replaceDependencies(context, dependencies)
+    for (let index = 1; index < context.matches.length; index++) {
+      const match = context.matches[index]
+      if (match === undefined || match.role !== 'update') continue
+      const typed = contextSnapshot(context) as ConversationNodeContext & { readonly state: unknown }
+      context.state = requireState(
+        context.definition,
+        'update',
+        context.definition.update(typed, match),
+      )
+    }
+    context.revision++
+    this.revised.add(context)
+    this.dirty.add(context)
+  }
+
+  private replaceDependencies(context: InternalContext, dependencies: Map<string, Dependency>): void {
+    for (const dependency of context.dependencies.values()) {
+      if (dependency.key === undefined) continue
+      const current = this.dependents.get(dependency.key)
+      current?.delete(context)
+      if (current?.size === 0) this.dependents.delete(dependency.key)
+    }
+    context.dependencies = dependencies
+    for (const dependency of dependencies.values()) {
+      if (dependency.key === undefined) continue
+      const current = this.dependents.get(dependency.key) ?? new Set()
+      current.add(context)
+      this.dependents.set(dependency.key, current)
+    }
+  }
+
+  private replayRevisedDependents(): boolean {
+    const pending = [...this.revised]
+    const replayed = new Set<InternalContext>()
+    for (let index = 0; index < pending.length; index++) {
+      const dependency = pending[index]
+      if (dependency === undefined) continue
+      for (const dependent of this.dependents.get(dependency.key) ?? []) {
+        if (replayed.has(dependent)) continue
+        replayed.add(dependent)
+        this.replayContext(dependent)
+        pending.push(dependent)
+      }
+    }
+    return replayed.size > 0
+  }
+
+  private readerFor(
+    beforeSeq: number,
+    dependencies: Map<string, Dependency>,
+  ): ConversationContextReader {
+    return {
+      previous: <State>(kind: string): ConversationPreviousContext<State> | undefined => {
+        const predecessor = this.previousContext(kind, beforeSeq)
+        dependencies.set(kind, {
+          kind,
+          key: predecessor?.key,
+          revision: predecessor?.revision,
+          windowGap: predecessor === undefined && this.hasMore,
+        })
+        if (predecessor?.state === undefined) return undefined
+        const seq = startSeq(predecessor)
+        if (seq === undefined) return undefined
+        return {
+          key: predecessor.key,
+          kind: predecessor.kind,
+          id: predecessor.id,
+          startSeq: seq,
+          state: predecessor.state as Readonly<State>,
+          matches: predecessor.matches,
+        }
+      },
+    }
+  }
+
+  private previousContext(kind: string, beforeSeq: number): InternalContext | undefined {
+    const candidates = this.contextsByKind.get(kind) ?? []
+    const indexBefore = insertionIndex(candidates, beforeSeq)
+    for (let index = indexBefore - 1; index >= 0; index--) {
+      const candidate = candidates[index]
+      if (candidate?.state !== undefined) return candidate
+    }
+    return undefined
+  }
+
+  /** Insert one newly discovered start into its Definition's ordered predecessor index. */
+  private indexStartedContext(context: InternalContext): void {
+    const seq = context.startSeq
+    if (seq === undefined) return
+    const candidates = this.contextsByKind.get(context.kind) ?? []
+    const previous = candidates.at(-1)
+    if (previous === undefined || (previous.startSeq as number) < seq) candidates.push(context)
+    else candidates.splice(insertionIndex(candidates, seq), 0, context)
+    this.contextsByKind.set(context.kind, candidates)
+  }
+
+  private indexStartedContexts(kind: string, additions: readonly InternalContext[]): void {
+    if (additions.length === 0) return
+    const sorted = [...additions].sort((left, right) =>
+      (left.startSeq as number) - (right.startSeq as number))
+    const existing = this.contextsByKind.get(kind) ?? []
+    const merged: InternalContext[] = []
+    let before = 0
+    let added = 0
+    while (before < existing.length || added < sorted.length) {
+      const left = existing[before]
+      const right = sorted[added]
+      if (right === undefined || (left !== undefined && (left.startSeq as number) < (right.startSeq as number))) {
+        merged.push(left as InternalContext)
+        before++
+      } else {
+        merged.push(right)
+        added++
+      }
+    }
+    this.contextsByKind.set(kind, merged)
+  }
+
+  private replayDependencies(): boolean {
+    let replayed = false
+    const ordered = [...this.contexts.values()]
+      .filter(context => startSeq(context) !== undefined)
+      .sort((left, right) => (startSeq(left) as number) - (startSeq(right) as number))
+    for (const context of ordered) {
+      if (context.state === undefined || context.dependencies.size === 0) continue
+      const before = startSeq(context)
+      if (before === undefined) continue
+      let changed = false
+      for (const dependency of context.dependencies.values()) {
+        const current = this.previousContext(dependency.kind, before)
+        const windowGap = current === undefined && this.hasMore
+        if (current?.key !== dependency.key
+          || current?.revision !== dependency.revision
+          || windowGap !== dependency.windowGap) {
+          changed = true
+          break
+        }
+      }
+      if (changed) {
+        this.replayContext(context)
+        replayed = true
+      }
+    }
+    return replayed
+  }
+
+  private refreshMatchLocations(changedSeqs: ReadonlySet<number>): Set<InternalContext> {
+    const affected = new Set<InternalContext>()
+    if (changedSeqs.size === 0) return affected
+    for (const seq of changedSeqs) {
+      for (const context of this.contextsBySeq.get(seq) ?? []) affected.add(context)
+    }
+    for (const context of affected) {
+      let start = context.start
+      const matches = context.matches.map((match): ConversationMatch => {
+        if (!changedSeqs.has(match.event.seq)) return match
+        const refreshed = { ...match, location: this.locationIndex.locationOf(match.event) }
+        if (match === start) start = refreshed
+        return refreshed
+      })
+      context.matches = matches
+      context.start = start
+    }
+    return affected
+  }
+
+  private buildNode(context: InternalContext, target: string): ConversationViewNode | null {
+    const node = context.definition.buildViewNode(contextSnapshot(context), target)
+    if (node === null) return null
+    if (node.key !== context.key) {
+      throw new Error(`conversation Definition "${context.kind}" returned unstable key "${node.key}"; expected "${context.key}"`)
+    }
+    if (node.target !== target) {
+      throw new Error(`conversation Definition "${context.kind}" returned target "${node.target}" while building "${target}"`)
+    }
+    return node
+  }
+
+  private buildLocationData(
+    context: InternalContext,
+    scope: ConversationLocationDataScope,
+  ): ConversationLocationData | null {
+    const build = context.definition.buildLocationData
+    if (build === undefined) return null
+    const data = build(contextSnapshot(context), scope)
+    if (data === null) return null
+    if (data.kind !== scope) {
+      throw new Error(
+        `conversation Definition "${context.kind}" published ${data.kind} data through its ${scope} scope`,
+      )
+    }
+    if (data.key !== context.kind) {
+      throw new Error(
+        `conversation Definition "${context.kind}" published Location data key "${data.key}"; expected its owned kind`,
+      )
+    }
+    if (!Number.isSafeInteger(data.turn) || data.turn < 0) {
+      throw new Error(`conversation Definition "${context.kind}" published invalid turn ${data.turn}`)
+    }
+    if (data.kind === 'step' && (!Number.isSafeInteger(data.step) || (data.step as number) < 0)) {
+      throw new Error(`conversation Definition "${context.kind}" published invalid step ${String(data.step)}`)
+    }
+    return data
+  }
+
+  private replaceLocationData(): void {
+    const entries: { owner: string; data: ConversationLocationData }[] = []
+    for (const scope of LOCATION_DATA_SCOPES) {
+      for (const context of this.contexts.values()) {
+        const data = this.buildLocationData(context, scope)
+        context.locationData[scope] = data
+        if (data !== null) entries.push({ owner: context.key, data })
+      }
+      this.locationIndex.replaceData(entries)
+    }
+  }
+
+  private applyDirtyLocationData(): boolean {
+    let changed = false
+    for (const scope of LOCATION_DATA_SCOPES) {
+      const changes: ConversationLocationDataChange[] = []
+      for (const context of this.dirty) {
+        const previous = context.locationData[scope]
+        const next = this.buildLocationData(context, scope)
+        context.locationData[scope] = next
+        if (previous !== next) changes.push({ owner: context.key, previous, next })
+      }
+      changed = this.locationIndex.applyData(changes) || changed
+    }
+    return changed
+  }
+
+  private resetViewBuilders(): void {
+    this.views.clear()
+    for (const definition of this.viewDefinitions.entries()) {
+      const builder = definition.create()
+      this.views.set(definition.target, {
+        target: definition.target,
+        builder,
+        snapshot: builder.empty,
+      })
+    }
+    this.replacePending = true
+  }
+}
+
+function isLocationBoundary(type: string): boolean {
+  return type === 'turn/start' || type === 'turn/end' || type === 'step/start' || type === 'step/end'
+}
+
+function requireState(
+  definition: ConversationNodeDefinition,
+  phase: 'start' | 'update',
+  state: unknown,
+): unknown {
+  if (state === undefined) {
+    throw new Error(`conversation Definition "${definition.kind}" returned undefined from ${phase}()`)
+  }
+  return state
+}
+
+/** Structural registry pair accepted by Session and SessionManager. */
+export interface ConversationRuntime {
+  readonly events: ConversationEventDefinitions & { subscribe(listener: () => void): () => void }
+  readonly views: ConversationViewDefinitions & { subscribe(listener: () => void): () => void }
+}
diff --git a/packages/client/runtime/src/client/sessions/conversation-location-index.ts b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
new file mode 100644
index 0000000000..20fe3efdff
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
@@ -0,0 +1,508 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {
+  ConversationEventInput, ConversationLocation, ConversationLocationData,
+  ConversationLocationDataStore, ConversationStepDataMap, ConversationTimelineSnapshot,
+  ConversationTurnDataMap, StepLocation, TurnLocation,
+} from '../contract/conversation.ts'
+
+interface OwnedLocationData {
+  readonly owner: string
+  readonly value: unknown
+}
+
+/** One Context's previous and next Location-data publication. */
+export interface ConversationLocationDataChange {
+  readonly owner: string
+  readonly previous: ConversationLocationData | null
+  readonly next: ConversationLocationData | null
+}
+
+class MutableLocationDataStore {
+  private entries = new Map<string, OwnedLocationData>()
+
+  get<Key extends string>(key: Key): unknown {
+    return this.entries.get(key)?.value
+  }
+
+  remove(owner: string, key: string): boolean {
+    const current = this.entries.get(key)
+    if (current?.owner !== owner) return false
+    this.entries.delete(key)
+    return true
+  }
+
+  set(owner: string, key: string, value: unknown): boolean {
+    const current = this.entries.get(key)
+    if (current !== undefined && current.owner !== owner) {
+      throw new Error(`conversation Location data "${key}" is already owned by ${current.owner}`)
+    }
+    if (current?.value === value) return false
+    this.entries.set(key, { owner, value })
+    return true
+  }
+
+  replace(entries: ReadonlyMap<string, OwnedLocationData>): boolean {
+    let changed = this.entries.size !== entries.size
+    if (!changed) {
+      for (const [key, value] of entries) {
+        const current = this.entries.get(key)
+        if (current?.owner !== value.owner || current.value !== value.value) {
+          changed = true
+          break
+        }
+      }
+    }
+    if (changed) this.entries = new Map(entries)
+    return changed
+  }
+}
+
+interface Coordinates {
+  readonly turn?: number
+  readonly step?: number
+  readonly session?: true
+}
+
+interface StepDraft {
+  readonly turn: number
+  readonly step: number
+  firstSeq: number
+  start?: SessionEvent<'step/start'>
+  end?: SessionEvent<'step/end'>
+}
+
+interface TurnDraft {
+  readonly turn: number
+  firstSeq: number
+  start?: SessionEvent<'turn/start'>
+  end?: SessionEvent<'turn/end'>
+  readonly steps: Map<number, StepDraft>
+}
+
+const SESSION_LOCATION = { kind: 'session' } as const
+const UNRESOLVED_LOCATION = { kind: 'unresolved' } as const
+
+function payloadCoordinates(event: SessionEvent): Coordinates {
+  const data = event.data as unknown as { turn?: unknown; step?: unknown }
+  if (data.turn === null) return { session: true }
+  const turn = Number.isSafeInteger(data.turn) && (data.turn as number) >= 0
+    ? data.turn as number
+    : undefined
+  const step = Number.isSafeInteger(data.step) && (data.step as number) >= 0
+    ? data.step as number
+    : undefined
+  return { ...turn === undefined ? {} : { turn }, ...step === undefined ? {} : { step } }
+}
+
+function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function sameStep(left: StepLocation | undefined, right: StepLocation): boolean {
+  return left !== undefined
+    && left.start === right.start && left.end === right.end && left.status === right.status
+    && left.data === right.data
+}
+
+function sameTurn(left: TurnLocation | undefined, right: TurnLocation): boolean {
+  return left !== undefined
+    && left.start === right.start && left.end === right.end && left.status === right.status
+    && left.data === right.data && sameReferences(left.steps, right.steps)
+}
+
+function sameLocation(left: ConversationLocation | undefined, right: ConversationLocation | undefined): boolean {
+  if (left === undefined || right === undefined || left.kind !== right.kind) return left === right
+  if (left.kind === 'session' || left.kind === 'unresolved') return true
+  if (right.kind === 'session' || right.kind === 'unresolved') return false
+  if (left.kind === 'turn' || right.kind === 'turn') {
+    return left.kind === 'turn' && right.kind === 'turn' && left.turn === right.turn
+  }
+  return left.turn === right.turn && left.step === right.step
+}
+
+/** Session-owned Turn/Step timeline and event-to-Location index. */
+export class ConversationLocationIndex {
+  private coordinates = new Map<number, Coordinates>()
+  private locations = new Map<number, ConversationLocation>()
+  private seqsByTurn = new Map<number, Set<number>>()
+  private timeline: ConversationTimelineSnapshot = { turnOrder: [], turns: new Map() }
+  private readonly turnDataStores = new Map<number, MutableLocationDataStore>()
+  private readonly stepDataStores = new Map<string, MutableLocationDataStore>()
+  private currentTurn: number | undefined
+  private currentStep: number | undefined
+
+  /**
+   * Return the current reference-stable timeline.
+   * @returns current timeline snapshot.
+   */
+  snapshot(): ConversationTimelineSnapshot {
+    return this.timeline
+  }
+
+  /** Replace all Definition-owned Location values while preserving reader identities. */
+  replaceData(entries: readonly { readonly owner: string; readonly data: ConversationLocationData }[]): boolean {
+    const turns = new Map<number, Map<string, OwnedLocationData>>()
+    const steps = new Map<string, Map<string, OwnedLocationData>>()
+    for (const { owner, data } of entries) {
+      const values = data.kind === 'turn'
+        ? turns.get(data.turn) ?? new Map<string, OwnedLocationData>()
+        : steps.get(stepDataKey(data.turn, requireStep(data))) ?? new Map<string, OwnedLocationData>()
+      const current = values.get(data.key)
+      if (current !== undefined && current.owner !== owner) {
+        throw new Error(`conversation Location data "${data.key}" is already owned by ${current.owner}`)
+      }
+      values.set(data.key, { owner, value: data.value })
+      if (data.kind === 'turn') turns.set(data.turn, values)
+      else steps.set(stepDataKey(data.turn, requireStep(data)), values)
+    }
+    let changed = false
+    for (const turn of new Set([...this.turnDataStores.keys(), ...turns.keys()])) {
+      changed = this.mutableTurnData(turn).replace(turns.get(turn) ?? new Map()) || changed
+    }
+    for (const step of new Set([...this.stepDataStores.keys(), ...steps.keys()])) {
+      changed = this.mutableStepData(step).replace(steps.get(step) ?? new Map()) || changed
+    }
+    return changed
+  }
+
+  /** Apply changed Context publications without rebuilding Turn/Step membership. */
+  applyData(changes: readonly ConversationLocationDataChange[]): boolean {
+    let changed = false
+    for (const change of changes) {
+      const previous = change.previous
+      if (previous === null) continue
+      changed = this.storeFor(previous).remove(change.owner, previous.key) || changed
+    }
+    for (const change of changes) {
+      const next = change.next
+      if (next === null) continue
+      changed = this.storeFor(next).set(change.owner, next.key, next.value) || changed
+    }
+    return changed
+  }
+
+  /**
+   * Resolve the latest Location for one event.
+   * @param event - event already ingested into this index.
+   * @returns current Location, falling back to session when it has no Turn/Step affinity.
+   */
+  locationOf(event: SessionEvent): ConversationLocation {
+    return this.locations.get(event.seq) ?? SESSION_LOCATION
+  }
+
+  /**
+   * Rebuild timeline facts after replace/prepend or a boundary append.
+   * @param entries - complete current window in ascending seq order.
+   * @returns seqs whose resolved Location changed.
+   */
+  rebuild(entries: readonly ConversationEventInput[]): ReadonlySet<number> {
+    const previousLocations = this.locations
+    const turns = new Map<number, TurnDraft>()
+    const coordinates = new Map<number, Coordinates>()
+    let currentTurn: number | undefined
+    let currentStep: number | undefined
+
+    const turnDraft = (turn: number, seq: number): TurnDraft => {
+      let draft = turns.get(turn)
+      if (draft === undefined) {
+        draft = { turn, firstSeq: seq, steps: new Map() }
+        turns.set(turn, draft)
+      } else {
+        draft.firstSeq = Math.min(draft.firstSeq, seq)
+      }
+      return draft
+    }
+    const stepDraft = (turn: number, step: number, seq: number): StepDraft => {
+      const owner = turnDraft(turn, seq)
+      let draft = owner.steps.get(step)
+      if (draft === undefined) {
+        draft = { turn, step, firstSeq: seq }
+        owner.steps.set(step, draft)
+      } else {
+        draft.firstSeq = Math.min(draft.firstSeq, seq)
+      }
+      return draft
+    }
+
+    for (const { event } of entries) {
+      const explicit = payloadCoordinates(event)
+      if (event.type === 'turn/start') {
+        currentTurn = event.data.turn
+        currentStep = undefined
+      }
+      if (event.type === 'step/start') {
+        currentTurn = event.data.turn
+        currentStep = event.data.step
+      }
+      if (explicit.session !== true && explicit.turn !== undefined) {
+        if (currentTurn !== explicit.turn) currentStep = undefined
+        currentTurn = explicit.turn
+        if (explicit.step !== undefined) currentStep = explicit.step
+      }
+      const turn = explicit.session === true ? undefined : explicit.turn ?? currentTurn
+      const step = explicit.session === true || event.type === 'turn/start' || event.type === 'turn/end'
+        ? undefined
+        : explicit.step ?? (turn === currentTurn ? currentStep : undefined)
+      coordinates.set(event.seq, {
+        ...turn === undefined ? {} : { turn },
+        ...turn === undefined || step === undefined ? {} : { step },
+      })
+      if (turn !== undefined) turnDraft(turn, event.seq)
+      if (turn !== undefined && step !== undefined) stepDraft(turn, step, event.seq)
+
+      if (event.type === 'turn/start') {
+        turnDraft(event.data.turn, event.seq).start = event
+      } else if (event.type === 'turn/end') {
+        turnDraft(event.data.turn, event.seq).end = event
+      } else if (event.type === 'step/start') {
+        stepDraft(event.data.turn, event.data.step, event.seq).start = event
+      } else if (event.type === 'step/end') {
+        stepDraft(event.data.turn, event.data.step, event.seq).end = event
+      }
+
+      if (event.type === 'step/end' && currentTurn === event.data.turn && currentStep === event.data.step) {
+        currentStep = undefined
+      }
+      if (event.type === 'turn/end' && currentTurn === event.data.turn) {
+        currentTurn = undefined
+        currentStep = undefined
+      }
+    }
+
+    const previousTurns = this.timeline.turns
+    const nextTurns = new Map<number, TurnLocation>()
+    const orderedDrafts = [...turns.values()].sort((left, right) => left.firstSeq - right.firstSeq)
+    for (const draft of orderedDrafts) {
+      const previousTurn = previousTurns.get(draft.turn)
+      const previousSteps = new Map(previousTurn?.steps.map(step => [step.step, step]) ?? [])
+      const steps = [...draft.steps.values()]
+        .sort((left, right) => left.firstSeq - right.firstSeq)
+        .map((candidate): StepLocation => {
+          const value: StepLocation = {
+            turn: candidate.turn,
+            step: candidate.step,
+            start: candidate.start,
+            end: candidate.end,
+            status: candidate.end !== undefined
+              ? 'closed'
+              : candidate.start === undefined ? 'unknown' : 'open',
+            data: this.stepData(candidate.turn, candidate.step),
+          }
+          const previous = previousSteps.get(candidate.step)
+          return sameStep(previous, value) ? previous as StepLocation : value
+        })
+      const value: TurnLocation = {
+        turn: draft.turn,
+        start: draft.start,
+        end: draft.end,
+        status: draft.end !== undefined ? 'closed' : draft.start === undefined ? 'unknown' : 'open',
+        steps,
+        data: this.turnData(draft.turn),
+      }
+      nextTurns.set(draft.turn, sameTurn(previousTurn, value) ? previousTurn as TurnLocation : value)
+    }
+
+    const nextOrder = orderedDrafts.map(draft => draft.turn)
+    const turnOrder = this.timeline.turnOrder.length === nextOrder.length
+      && this.timeline.turnOrder.every((turn, index) => turn === nextOrder[index])
+      ? this.timeline.turnOrder
+      : nextOrder
+    let sameMap = previousTurns.size === nextTurns.size
+    if (sameMap) {
+      for (const [turn, value] of nextTurns) {
+        if (previousTurns.get(turn) !== value) {
+          sameMap = false
+          break
+        }
+      }
+    }
+    this.timeline = sameMap && turnOrder === this.timeline.turnOrder
+      ? this.timeline
+      : { turnOrder, turns: nextTurns }
+    this.coordinates = coordinates
+    this.locations = new Map()
+    this.seqsByTurn = new Map()
+    for (const { event } of entries) {
+      const coordinates = this.coordinates.get(event.seq)
+      if (coordinates?.turn !== undefined) this.indexTurnSeq(coordinates.turn, event.seq)
+      this.locations.set(event.seq, this.resolve(event.seq))
+    }
+    this.currentTurn = currentTurn
+    this.currentStep = currentStep
+
+    const changed = new Set<number>()
+    for (const { event } of entries) {
+      if (!sameLocation(previousLocations.get(event.seq), this.locations.get(event.seq))) {
+        changed.add(event.seq)
+      }
+    }
+    return changed
+  }
+
+  /**
+   * Append one Turn/Step boundary while revisiting only the owning Turn.
+   * @param event - contiguous tail boundary event.
+   * @returns seqs whose immutable Location reference changed.
+   */
+  appendBoundary(event: SessionEvent): ReadonlySet<number> {
+    if (event.type !== 'turn/start' && event.type !== 'turn/end'
+      && event.type !== 'step/start' && event.type !== 'step/end') {
+      throw new Error(`conversation Location boundary expected, received ${event.type}`)
+    }
+
+    const explicit = payloadCoordinates(event)
+    if (event.type === 'turn/start') {
+      this.currentTurn = event.data.turn
+      this.currentStep = undefined
+    } else if (event.type === 'step/start') {
+      this.currentTurn = event.data.turn
+      this.currentStep = event.data.step
+    }
+    if (explicit.turn !== undefined) {
+      if (this.currentTurn !== explicit.turn) this.currentStep = undefined
+      this.currentTurn = explicit.turn
+      if (explicit.step !== undefined) this.currentStep = explicit.step
+    }
+    const turnNumber = explicit.turn ?? this.currentTurn
+    if (turnNumber === undefined) throw new Error(`conversation boundary ${event.type} has no turn`)
+    const stepNumber = event.type === 'turn/start' || event.type === 'turn/end'
+      ? undefined
+      : explicit.step ?? (turnNumber === this.currentTurn ? this.currentStep : undefined)
+    this.coordinates.set(event.seq, {
+      turn: turnNumber,
+      ...stepNumber === undefined ? {} : { step: stepNumber },
+    })
+    this.indexTurnSeq(turnNumber, event.seq)
+
+    const previousTurn = this.timeline.turns.get(turnNumber)
+    let steps = previousTurn?.steps ?? []
+    if (event.type === 'step/start' || event.type === 'step/end') {
+      const number = event.data.step
+      const previousStep = steps.find(candidate => candidate.step === number)
+      const candidate: StepLocation = {
+        turn: turnNumber,
+        step: number,
+        start: event.type === 'step/start' ? event : previousStep?.start,
+        end: event.type === 'step/end' ? event : previousStep?.end,
+        status: event.type === 'step/end' || previousStep?.end !== undefined ? 'closed' : 'open',
+        data: this.stepData(turnNumber, number),
+      }
+      const nextStep = sameStep(previousStep, candidate) ? previousStep as StepLocation : candidate
+      const index = steps.findIndex(step => step.step === number)
+      steps = index < 0
+        ? [...steps, nextStep]
+        : steps.map((step, at) => at === index ? nextStep : step)
+    }
+    const candidate: TurnLocation = {
+      turn: turnNumber,
+      start: event.type === 'turn/start' ? event : previousTurn?.start,
+      end: event.type === 'turn/end' ? event : previousTurn?.end,
+      status: event.type === 'turn/end' || previousTurn?.end !== undefined
+        ? 'closed'
+        : event.type === 'turn/start' || previousTurn?.start !== undefined ? 'open' : 'unknown',
+      steps,
+      data: this.turnData(turnNumber),
+    }
+    const turn = sameTurn(previousTurn, candidate) ? previousTurn as TurnLocation : candidate
+    const turns = new Map(this.timeline.turns)
+    turns.set(turnNumber, turn)
+    const turnOrder = previousTurn === undefined
+      ? [...this.timeline.turnOrder, turnNumber]
+      : this.timeline.turnOrder
+    this.timeline = { turnOrder, turns }
+
+    const changed = new Set<number>()
+    for (const seq of this.seqsByTurn.get(turnNumber) ?? []) {
+      const previous = this.locations.get(seq)
+      const next = this.resolve(seq)
+      this.locations.set(seq, next)
+      if (!sameLocation(previous, next)) changed.add(seq)
+    }
+
+    if (event.type === 'step/end' && this.currentTurn === event.data.turn && this.currentStep === event.data.step) {
+      this.currentStep = undefined
+    }
+    if (event.type === 'turn/end' && this.currentTurn === event.data.turn) {
+      this.currentTurn = undefined
+      this.currentStep = undefined
+    }
+    return changed
+  }
+
+  /**
+   * Index one non-boundary tail event without rescanning the window.
+   * @param event - contiguous appended event.
+   */
+  appendNonBoundary(event: SessionEvent): void {
+    const explicit = payloadCoordinates(event)
+    if (explicit.session === true) {
+      this.coordinates.set(event.seq, {})
+      this.locations.set(event.seq, SESSION_LOCATION)
+      return
+    }
+    if (explicit.turn !== undefined) {
+      if (this.currentTurn !== explicit.turn) this.currentStep = undefined
+      this.currentTurn = explicit.turn
+      if (explicit.step !== undefined) this.currentStep = explicit.step
+    }
+    const turn = explicit.turn ?? this.currentTurn
+    const step = explicit.step ?? (turn === this.currentTurn ? this.currentStep : undefined)
+    this.coordinates.set(event.seq, {
+      ...turn === undefined ? {} : { turn },
+      ...turn === undefined || step === undefined ? {} : { step },
+    })
+    if (turn !== undefined) this.indexTurnSeq(turn, event.seq)
+    this.locations.set(event.seq, this.resolve(event.seq))
+  }
+
+  private indexTurnSeq(turn: number, seq: number): void {
+    const current = this.seqsByTurn.get(turn) ?? new Set<number>()
+    current.add(seq)
+    this.seqsByTurn.set(turn, current)
+  }
+
+  private turnData(turn: number): ConversationLocationDataStore<ConversationTurnDataMap> {
+    return this.mutableTurnData(turn) as ConversationLocationDataStore<ConversationTurnDataMap>
+  }
+
+  private stepData(turn: number, step: number): ConversationLocationDataStore<ConversationStepDataMap> {
+    return this.mutableStepData(stepDataKey(turn, step)) as ConversationLocationDataStore<ConversationStepDataMap>
+  }
+
+  private mutableTurnData(turn: number): MutableLocationDataStore {
+    const current = this.turnDataStores.get(turn) ?? new MutableLocationDataStore()
+    this.turnDataStores.set(turn, current)
+    return current
+  }
+
+  private mutableStepData(key: string): MutableLocationDataStore {
+    const current = this.stepDataStores.get(key) ?? new MutableLocationDataStore()
+    this.stepDataStores.set(key, current)
+    return current
+  }
+
+  private storeFor(data: ConversationLocationData): MutableLocationDataStore {
+    return data.kind === 'turn'
+      ? this.mutableTurnData(data.turn)
+      : this.mutableStepData(stepDataKey(data.turn, requireStep(data)))
+  }
+
+  private resolve(seq: number): ConversationLocation {
+    const coordinates = this.coordinates.get(seq)
+    if (coordinates?.turn === undefined) return SESSION_LOCATION
+    const turn = this.timeline.turns.get(coordinates.turn)
+    if (turn === undefined) return UNRESOLVED_LOCATION
+    if (coordinates.step === undefined) return { kind: 'turn', turn }
+    const step = turn.steps.find(candidate => candidate.step === coordinates.step)
+    return step === undefined ? { kind: 'turn', turn } : { kind: 'step', turn, step }
+  }
+}
+
+function stepDataKey(turn: number, step: number): string {
+  return `${turn}:${step}`
+}
+
+function requireStep(data: ConversationLocationData): number {
+  if (data.kind === 'step' && data.step !== undefined) return data.step
+  throw new Error(`conversation Step data "${data.key}" requires a step`)
+}
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 2681bb33f3..99daa7c8a5 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -13,6 +13,9 @@ import type {
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { PendingInteraction } from './pending.ts'
 import type { ContextProvenanceView, KnownContextForm } from './context-provenance.ts'
+import type {
+  ChatConversationViewNode, ConversationTimelineSnapshot,
+} from '../contract/conversation.ts'
 export type { TodoItem }
 
 /** Request configuration recorded for one provider call. */
@@ -206,7 +209,7 @@ export interface CompactionSummaryNode {
  * Fallback for surface events this UI version does not know: the documented
  * default arm of `SessionEventMap`, which is merge-extensible, so the
  * projection's switch cannot end in `assertNever`. No event produces this node
- * today — `isAppendSurfaceEvent` admits only the four types in core's
+ * today — `isAppendSurfaceEvent` admits only the three types in core's
  * `SurfaceEventType`, and each has its own arm — and it exists so widening that
  * set core-side degrades to a raw row instead of dropping the event silently.
  */
@@ -222,8 +225,8 @@ export interface UnknownSurfaceNode {
 /**
  * One slash-command lifecycle folded from the log-only `command/run` /
  * `command/done` pair (paired by commandId, mirroring tool call↔result).
- * Log-only events are not surface events, so the TranscriptAdapter indexes
- * them separately and merges the nodes into the flow by seq. A window cut
+ * Log-only events are not surface events, so the command Definition indexes
+ * them separately and the Chat builder orders the resulting node by seq. A window cut
  * between the pair soft-falls like tool pairs: a done with no in-window run
  * still builds a node (name/args null), and a run with no done renders as
  * still executing.
@@ -311,21 +314,19 @@ export type OpenState = 'cold' | 'loading' | 'open' | 'error'
  * Input-area shape of an OPEN session, derived at snapshot assembly (the one
  * place that knows the predicate — consumers switch, never re-derive):
  *
- * - `blank`: no activity ever (no nodes, no partial, not running, no pending
- *   waits, no prompt attempt) — the UI renders the blank-session guidance
- *   hero.
- * - `engaging`: the first prompt was initiated but no content landed yet —
- *   the UI holds the composer through the accept → running → first-event
- *   frames. Entered synchronously before prompt()'s first await.
- * - `active`: content exists (nodes, partial, running turn, or pending
- *   waits) — the ordinary conversation view.
+ * - `blank`: the authoritative blank bit is still set and no prompt was
+ *   attempted — the UI renders the blank-session guidance hero.
+ * - `engaging`: a first prompt was attempted, but no accepted turn or other
+ *   authoritative activity signal has arrived — the UI keeps the composer
+ *   visible through admission and error frames.
+ * - `active`: the session is non-blank beyond its pending first prompt, is
+ *   running, or owns a pending interaction — the ordinary conversation view.
  *
- * Monotone within a session object: blank → engaging → active, no returns.
  * A failed first prompt stays `engaging` (composer + error strip — retry
- * semantics; bouncing back to the hero would discard the error context).
+ * semantics; returning to the hero would discard the error context).
  * Sessions whose window is not open (`loading`/`error`) are outside phase
  * jurisdiction: consumers branch on {@link ConversationSnapshot.openState}
- * first (phase still reports `active`-ish facts but must not be rendered).
+ * first.
  */
 export type ComposerPhase = 'blank' | 'engaging' | 'active'
 
@@ -335,10 +336,70 @@ export interface PromptError {
   error: RpcError
 }
 
+/** Stable per-key reader for final Chat view Nodes. */
+export interface ChatNodeStore {
+  /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
+  get(key: string): ChatConversationViewNode | undefined
+  /** @returns all currently materialized Nodes without imposing render order. */
+  values(): readonly ChatConversationViewNode[]
+}
+
+/** Stable per-Location membership index for turn-local and step-local consumers. */
+export interface ChatLocationNodeIndex {
+  /** @param turn - owning turn. @returns ordered Chat Node keys in the turn. */
+  getTurn(turn: number): readonly string[]
+  /** @param turn - owning turn. @param step - owning step. @returns ordered Chat Node keys in the step. */
+  getStep(turn: number, step: number): readonly string[]
+}
+
+/** Temporary projection consumed by Trajectory and unmigrated readers. */
+export interface LegacyConversationSlice {
+  readonly nodes: readonly ConversationNode[]
+  readonly turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
+  readonly turnEnds: ReadonlyMap<number, number>
+  readonly partial: PartialAssistant | null
+  readonly runningCalls: readonly RunningToolCall[]
+}
+
+/** Incremental Chat target snapshot: stable keyed stores plus structural order. */
+export interface ChatSnapshot {
+  readonly order: readonly string[]
+  readonly nodes: ChatNodeStore
+  readonly locations: ChatLocationNodeIndex
+  readonly timeline: ConversationTimelineSnapshot
+  readonly legacy: LegacyConversationSlice
+}
+
+const EMPTY_LIST: readonly never[] = []
+const EMPTY_TIMELINE: ConversationTimelineSnapshot = { turnOrder: EMPTY_LIST, turns: new Map() }
+
+/** Empty Chat target used before a view builder is registered. */
+export const EMPTY_CHAT_SNAPSHOT: ChatSnapshot = {
+  order: EMPTY_LIST,
+  nodes: {
+    get: () => undefined,
+    values: () => EMPTY_LIST,
+  },
+  locations: {
+    getTurn: () => EMPTY_LIST,
+    getStep: () => EMPTY_LIST,
+  },
+  timeline: EMPTY_TIMELINE,
+  legacy: {
+    nodes: EMPTY_LIST,
+    turnTimings: new Map(),
+    turnEnds: new Map(),
+    partial: null,
+    runningCalls: EMPTY_LIST,
+  },
+}
+
 /** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */
 export interface ConversationSnapshot {
   sessionId: SessionId
-  /** Human transcript plus retry notices and interrupted-turn terminal nodes in event order. */
+  /** Final Chat target assembled from independently registered business Definitions. */
+  chat: ChatSnapshot
+  /** Legacy Trajectory slice derived from the registered Chat Definitions. */
   nodes: readonly ConversationNode[]
   /** Exact in-window `turn/start` time and optional matching `turn/end` time. */
   turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
index 64199c4812..b4eec9d6df 100644
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -10,6 +10,7 @@ import type {
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { mergeOrderedBaseline } from '../ordered-baseline.ts'
+import type { ConversationRuntime } from './conversation-assembler.ts'
 import type { SessionListEntry, TitledSessionSummary } from './lineage.ts'
 import { flattenLineage } from './lineage.ts'
 import type { PendingInteractionStatus } from './pending.ts'
@@ -158,6 +159,7 @@ export class SessionManager {
     private readonly api: IApiClient,
     restoredSelection?: SessionId,
     restoredAddress?: SubagentAddress,
+    private readonly conversation?: ConversationRuntime,
   ) {
     this.selected = restoredSelection
     if (restoredAddress !== undefined) this.addresses.set(restoredAddress.childSessionId, restoredAddress)
@@ -282,7 +284,12 @@ export class SessionManager {
         const address = this.addresses.get(sessionId)
         const child = address === undefined ? undefined : this.catalogs.get(address.parentSessionId)?.entries
           .find(entry => entry.kind === 'child' && entry.id === sessionId)
-        if (child?.kind === 'child') session.handleRunning(child.activity === 'running')
+        if (child?.kind === 'child') {
+          // A catalogued child exists only after its delegated session has
+          // durable history, even though child rows do not carry `blank`.
+          session.handleBlank(false)
+          session.handleRunning(child.activity === 'running')
+        }
       }
     }
     return session
@@ -301,9 +308,15 @@ export class SessionManager {
         this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
       },
       projections: this.projectionStore(sessionId),
+      ...this.conversation === undefined ? {} : { conversation: this.conversation },
     })
   }
 
+  /** Rebuild every resident Session after one coalesced registry transaction. */
+  rebuildConversationRegistry(): void {
+    for (const session of this.sessions.values()) session.rebuildConversationRegistry()
+  }
+
   /** Resident per-session projection store (create-on-demand; outlives instantiation). */
   private projectionStore(sessionId: SessionId): ProjectionValueStore {
     let store = this.projectionStores.get(sessionId)
diff --git a/packages/client/runtime/src/client/sessions/partial.ts b/packages/client/runtime/src/client/sessions/partial.ts
index 31a04124cd..599ea61c3d 100644
--- a/packages/client/runtime/src/client/sessions/partial.ts
+++ b/packages/client/runtime/src/client/sessions/partial.ts
@@ -48,7 +48,7 @@ export class PartialAccumulator {
   push(chunk: StreamChunk): boolean {
     switch (chunk.type) {
       case 'block-start': {
-        this.blocks[chunk.index] = emptyBlock(chunk.blockType)
+        this.blocks[chunk.index] = emptyAssistantBlock(chunk.blockType)
         this.changed = true
         return true
       }
@@ -102,7 +102,12 @@ export class PartialAccumulator {
   }
 }
 
-function emptyBlock(blockType: string): AssistantBlock {
+/**
+ * Create the empty client projection for one streamed Assistant block kind.
+ * @param blockType - wire block kind.
+ * @returns empty projected block ready to receive deltas.
+ */
+export function emptyAssistantBlock(blockType: string): AssistantBlock {
   switch (blockType) {
     case 'text': return { kind: 'text', text: '' }
     case 'reasoning': return { kind: 'reasoning', text: '' }
diff --git a/packages/client/runtime/src/client/sessions/queue-mirror.ts b/packages/client/runtime/src/client/sessions/queue-mirror.ts
new file mode 100644
index 0000000000..be7351cf5f
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/queue-mirror.ts
@@ -0,0 +1,74 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { MuxFrame } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { QueuedMessage } from './conversation.ts'
+
+const QUEUE_PREVIEW_CHARS = 200
+
+function previewOf(content: readonly ContentBlock[]): string {
+  const flat = content
+    .map(block => (block.type === 'text' ? block.text : `[${block.type}]`))
+    .join(' ').replace(/\s+/g, ' ').trim()
+  const chars = Array.from(flat)
+  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join('')}…` : flat
+}
+
+function textOf(content: readonly ContentBlock[]): string | null {
+  if (!content.every(block => block.type === 'text')) return null
+  return content.map(block => block.text).join('')
+}
+
+type QueueItems = Extract<MuxFrame, { type: 'session/queue' }>['items']
+
+/** Authoritative transient queue projection and durable steering handoff. */
+export class SessionQueueMirror {
+  private current: readonly QueuedMessage[] = []
+
+  /**
+   * Return the current immutable queue projection.
+   * @returns current queue rows.
+   */
+  snapshot(): readonly QueuedMessage[] {
+    return this.current
+  }
+
+  /**
+   * Drop the stale generation before its replacement queue baseline arrives.
+   * @returns whether any projected queue row was removed.
+   */
+  reset(): boolean {
+    if (this.current.length === 0) return false
+    this.current = []
+    return true
+  }
+
+  /**
+   * Replace from one authoritative stream queue frame.
+   * @param items - complete host queue snapshot.
+   */
+  replace(items: QueueItems): void {
+    this.current = items.map(item => ({
+      id: item.id,
+      messageId: item.message.id,
+      placement: item.placement,
+      content: item.message.content,
+      preview: previewOf(item.message.content),
+      text: textOf(item.message.content),
+    }))
+  }
+
+  /**
+   * Retire a transient steering row once its durable message enters the log.
+   * @param event - newly contiguous durable Session event.
+   * @returns whether the projection changed.
+   */
+  acceptDurable(event: SessionEvent): boolean {
+    if (event.type !== 'user/message') return false
+    const messageId = event.data.id
+    const index = this.current.findIndex(item =>
+      item.placement === 'steering' && item.messageId === messageId)
+    if (index < 0) return false
+    this.current = this.current.filter((_item, candidate) => candidate !== index)
+    return true
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index 64eeaf91d7..dcb5f71610 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -31,6 +31,7 @@ import { createSnapshotStore } from '../contract/store.ts'
 import type { SessionFace } from '../contract/session.ts'
 import type { AgentContext, ISessions } from '../contract/sessions.ts'
 import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
+import type { ConversationRuntime } from './conversation-assembler.ts'
 import { SessionManager } from './manager.ts'
 import type { SessionListPhase, SessionSearchResultItem, SubagentCatalogSnapshot } from './manager.ts'
 import type { PendingInteractionStatus } from './pending.ts'
@@ -259,16 +260,30 @@ export class SessionsService implements ISessions {
   /**
    * @param ctx - client root context (scope fibers mount under it).
    * @param api - wire client shared with every Session.
+   * @param conversationRuntime - same-pass registry instances, when runtime apply owns them.
    */
   constructor(
     private readonly rootCtx: Context,
     api: IApiClient,
+    conversationRuntime?: ConversationRuntime,
   ) {
     this.selection = createSnapshotStore<SessionSelection>(
       {},
       { persist: { name: 'dsh.sessions.current' } })
     const restored = this.selection.getSnapshot()
-    this.manager = new SessionManager(api, restored.sessionId, restored.subagentAddress)
+    const conversationEvents = rootCtx.get('conversationEvents')
+    const conversationViews = rootCtx.get('conversationViews')
+    const conversation = conversationRuntime ?? (
+      conversationEvents === undefined || conversationViews === undefined
+        ? undefined
+        : { events: conversationEvents, views: conversationViews }
+    )
+    this.manager = new SessionManager(
+      api,
+      restored.sessionId,
+      restored.subagentAddress,
+      conversation,
+    )
     this.list = createSnapshotStore<SessionListState>({
       ids: [], byId: {}, current: undefined, phase: 'pending',
       subagentsByParent: {}, currentAddress: undefined,
@@ -296,6 +311,25 @@ export class SessionsService implements ISessions {
       resolveCurrent: () => this.maybeProvideInfo(this.list.getSnapshot().current),
     })
     this.currentProvideInfo = this.provideChannel.currentProvideInfo
+    let registryRebuildQueued = false
+    const scheduleRegistryRebuild = (): void => {
+      if (registryRebuildQueued) return
+      registryRebuildQueued = true
+      queueMicrotask(() => {
+        registryRebuildQueued = false
+        this.manager.rebuildConversationRegistry()
+      })
+    }
+    if (conversation !== undefined) {
+      rootCtx.effect(() => {
+        const disposeEvents = conversation.events.subscribe(scheduleRegistryRebuild)
+        const disposeViews = conversation.views.subscribe(scheduleRegistryRebuild)
+        return () => {
+          disposeEvents()
+          disposeViews()
+        }
+      }, 'sessions: conversation registry rebuild')
+    }
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 0813c02711..a533f9dd6f 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -2,7 +2,6 @@
 
 import type { Context } from 'cordis'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
   HistoryEntry, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
@@ -12,27 +11,23 @@ import type {
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SessionFace } from '../contract/session.ts'
+import { ConversationNodeAssembler } from './conversation-assembler.ts'
+import type { ConversationRuntime } from './conversation-assembler.ts'
+import type { ConversationEventInput, ConversationPublication } from '../contract/conversation.ts'
 import type {
-  ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
-  OpenState, PromptError, QueuedMessage, RunningToolCall,
+  ChatSnapshot, ComposerPhase, ConversationSnapshot, OpenState, PromptError,
 } from './conversation.ts'
+import { EMPTY_CHAT_SNAPSHOT } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
 import { PendingWait } from './pending.ts'
-import { TranscriptAdapter } from './transcript-adapter.ts'
-import { displayFailureMessage } from './failure-display.ts'
 import { Notifier } from './notifier.ts'
-import { isVisibleAssistantChunk, PartialAccumulator } from './partial.ts'
 import { ProjectionValueStore } from './projection-store.ts'
 import type { ProjectionsBaseline } from './projection-store.ts'
-import { ToolCallTree } from './tool-call-tree.ts'
+import { SessionQueueMirror } from './queue-mirror.ts'
 
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
 
-// Browser bundles cannot value-import the host timeout library. This protocol
-// bound is pinned to @deepseek-ai/dsh-timeout's MAX_TIMER_DELAY_MS in tests.
-const MAX_RETRY_DELAY_MS = 2_147_483_647
-
 /** Manager-owned observers of a Session object's local state edges. */
 export interface SessionOptions {
   /** Catalog-discovered address selecting non-activating subagent transport. */
@@ -54,24 +49,8 @@ export interface SessionOptions {
    * private store (bare object-layer construction).
    */
   projections?: ProjectionValueStore
-}
-
-/** Queue-row preview cap: the dock renders one line, the full content never leaves the host mirror. */
-const QUEUE_PREVIEW_CHARS = 200
-
-/** Single-line queue-row preview: text blocks flattened, non-text as tags, capped by code point. */
-function queuePreviewOf(content: readonly ContentBlock[]): string {
-  const flat = content
-    .map(block => (block.type === 'text' ? block.text : `[${block.type}]`))
-    .join(' ').replace(/\s+/g, ' ').trim()
-  const chars = Array.from(flat)
-  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join('')}…` : flat
-}
-
-/** Recover complete composer text only when editing cannot discard non-text blocks. */
-function queueTextOf(content: readonly ContentBlock[]): string | null {
-  if (!content.every(block => block.type === 'text')) return null
-  return content.map(block => block.text).join('')
+  /** Runtime registries used by this Session-owned Conversation assembler. */
+  conversation?: ConversationRuntime
 }
 
 /**
@@ -96,42 +75,13 @@ export class Session implements SessionFace {
    *  passes drop all writes once the generation moves on. */
   private openGeneration = 0
   private loadingOlder = false
-  private readonly transcript = new TranscriptAdapter()
-  private partial: PartialAccumulator | null = null
-  private openCalls = new Map<string, RunningToolCall>()
-  /** Last entered step per turn, folded from step/start for terminal error placement. */
-  private lastStepByTurn = new Map<number, number>()
-  /** Operational notices and interrupted-turn terminal nodes merged into the flow by seq.
-   *  Derived from window events and rebuilt with partial/openCalls; the transcript is
-   *  seq-monotonic, so a plain seq merge preserves event order. */
-  private derivedNodes: ConversationNode[] = []
   private pending = new Map<string, PendingInteraction>()
-  // Revision counters preserve array identity when derived content is unchanged, so
-  // React.memo children survive unrelated snapshot swaps (chunk storms must not re-render every
-  // tool card and pending card). Mutation sites bump the matching revision. partial needs no
-  // counter — PartialAccumulator.toPartial already returns a cached reference when unchanged.
-  private callsRev = 0
-  private callsCache: { rev: number; value: RunningToolCall[] } | null = null
   private pendingRev = 0
   private pendingCache: { rev: number; value: PendingInteraction[] } | null = null
-  private derivedRev = 0
-  private nodesCache: { projected: readonly ConversationNode[]; derivedRev: number; value: readonly ConversationNode[] } | null = null
-  /** Exact turn timing retained from the raw window so presentation never
-   *  infers elapsed time from transcript content. */
-  private turnTimings = new Map<number, { startTime: number; endTime?: number }>()
-  private turnTimingsRev = 0
-  private turnTimingsCache: { rev: number; value: ConversationSnapshot['turnTimings'] } | null = null
-  /** Completed turn boundaries retained from the raw window so presentation
-   *  actions never infer a safe fork point from transcript content alone. */
-  private turnEnds = new Map<number, number>()
-  private turnEndsRev = 0
-  private turnEndsCache: { rev: number; value: ReadonlyMap<number, number> } | null = null
   /** Authoritative stream-only inbox snapshot; pending work never hits history. */
-  private queued: QueuedMessage[] = []
-  private queueRev = 0
-  private queueCache: { rev: number; value: QueuedMessage[] } | null = null
-  /** Window-derived child-call lifecycle and immutable tree projection. */
-  private readonly toolCallTree = new ToolCallTree()
+  private readonly queueMirror = new SessionQueueMirror()
+  /** Session-owned business Context engine over the contiguous raw window. */
+  private readonly conversation: ConversationNodeAssembler
   private running = false
   private address: SubagentAddress | undefined
   private parentAvailable = false
@@ -141,8 +91,10 @@ export class Session implements SessionFace {
    * engaging edge of the phase machine (see ComposerPhase).
    */
   private promptAttempted = false
-  /** Empty-log mirror (see ConversationSnapshot.blank); monotone false once flipped. */
-  private blankBit = false
+  /** A first accepted prompt stays in the engaging phase until its turn is observable. */
+  private firstPromptPendingTurn = false
+  /** Empty-log mirror (see ConversationSnapshot.blank); unknown bare sessions begin conservatively blank. */
+  private blankBit = true
   private removed = false
   private promptError: PromptError | null = null
   private lastAgentError: string | null = null
@@ -167,9 +119,7 @@ export class Session implements SessionFace {
   readonly projections: ProjectionValueStore
 
   private snapshotCache: ConversationSnapshot
-  private readonly notifier = new Notifier(() => {
-    this.snapshotCache = this.buildSnapshot()
-  })
+  private readonly notifier: Notifier
   /**
    * Agent-scoped cordis context, bound once by SessionsService when it
    * mints the scope (the client mirror of the host Agent's loopCtx). The
@@ -192,6 +142,16 @@ export class Session implements SessionFace {
     this.projections = options.projections ?? new ProjectionValueStore()
     this.address = options.address
     this.parentAvailable = options.parentAvailable ?? false
+    this.conversation = options.conversation === undefined
+      ? new ConversationNodeAssembler(
+        { entries: () => [], fallbackEntry: () => undefined },
+        { entries: () => [] },
+      )
+      : new ConversationNodeAssembler(options.conversation.events, options.conversation.views)
+    this.notifier = new Notifier(() => {
+      this.conversation.flush()
+      this.snapshotCache = this.buildSnapshot()
+    })
     this.snapshotCache = this.buildSnapshot()
   }
 
@@ -228,6 +188,7 @@ export class Session implements SessionFace {
     // visible on the session area's very first frame when a caller sends
     // ahead of navigation (first-send flow).
     this.promptAttempted = true
+    if (this.blankBit) this.firstPromptPendingTurn = true
     this.notifier.markDirty()
     let result: RpcResult<{ accepted: true }>
     try {
@@ -375,6 +336,7 @@ export class Session implements SessionFace {
       const older = result.value.events
       if (older.length === 0) {
         this.hasMore = result.value.hasMore
+        this.conversation.prepend([], this.hasMore)
         return
       }
       const tail = older[older.length - 1]
@@ -389,8 +351,7 @@ export class Session implements SessionFace {
       /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
       this.baseSeq = older[0]?.event.seq ?? this.baseSeq
       this.hasMore = result.value.hasMore
-      this.transcript.reset(this.events, this.views) // prepend forces a rebuild (the window grew at the head)
-      this.rebuildDerivedFromWindow()
+      this.conversation.prepend(older.map(conversationInput), this.hasMore)
     } catch (error) {
       console.error('[web-runtime] loadOlder failed:', error)
     } finally {
@@ -461,15 +422,7 @@ export class Session implements SessionFace {
         return
       }
       case 'session/queue': {
-        this.queued = frame.items.map(item => ({
-          id: item.id,
-          messageId: item.message.id,
-          placement: item.placement,
-          content: item.message.content,
-          preview: queuePreviewOf(item.message.content),
-          text: queueTextOf(item.message.content),
-        }))
-        this.queueRev++
+        this.queueMirror.replace(frame.items)
         this.notifier.markDirty()
         return
       }
@@ -479,11 +432,7 @@ export class Session implements SessionFace {
         // snapshot AFTER the subscribed frame on the same stream, so the
         // stale mirror clears here — race-free against onConnected/resync
         // timing (clearing there could wipe a baseline that already landed).
-        if (this.queued.length > 0) {
-          this.queued = []
-          this.queueRev++
-          this.notifier.markDirty()
-        }
+        if (this.queueMirror.reset()) this.notifier.markDirty()
         return
       }
       case 'approval/requested': {
@@ -527,6 +476,7 @@ export class Session implements SessionFace {
       this.blankBit = false
       this.notifier.markDirty()
     }
+    if (running) this.firstPromptPendingTurn = false
     if (this.running === running) return
     this.running = running
     this.notifier.markDirty()
@@ -590,6 +540,11 @@ export class Session implements SessionFace {
   /** No-op because session instances remain resident. */
   dispose(): void {}
 
+  /** Rebuild the current window after a low-frequency Definition or view registration change. */
+  rebuildConversationRegistry(): void {
+    this.scheduleConversation(this.conversation.rebuildRegistry())
+  }
+
   // ---- 私有 ----
 
   /** Requested-frame arrival: the wait enters the pending map under its own key. */
@@ -651,8 +606,8 @@ export class Session implements SessionFace {
     this.views = entries.map(e => e.view)
     this.baseSeq = this.events[0]?.seq ?? 0
     this.hasMore = hasMore
-    this.transcript.reset(this.events, this.views)
-    this.rebuildDerivedFromWindow()
+    if (this.events.some(event => event.type === 'turn/start')) this.firstPromptPendingTurn = false
+    this.conversation.replaceWindow(entries.map(conversationInput), hasMore)
     if (projections !== undefined) this.projections.seed(projections)
     const buffered = this.liveBuffer
     this.liveBuffer = []
@@ -661,32 +616,22 @@ export class Session implements SessionFace {
   }
 
   /** Seq-guarded append shared by stitching and the open-state live path. */
-  private appendLive(event: SessionEvent, view?: ToolEventView): void {
+  private appendLive(event: SessionEvent, view?: ToolEventView): ConversationPublication {
     const tailSeq = this.windowTailSeq()
-    if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
+    if (tailSeq !== null && event.seq <= tailSeq) return 'none' // replay overlap, drop
     this.events.push(event)
     this.views.push(view)
-    this.transcript.append(event, view)
-    this.handoffPendingSteering(event)
-    this.applyEventSideEffects(event, view)
-  }
-
-  /** Retire the first matching live steering occurrence when its durable message takes over. */
-  private handoffPendingSteering(event: SessionEvent): void {
-    if (event.type !== 'user/message') return
-    const message = event.data
-    const index = this.queued.findIndex(item =>
-      item.placement === 'steering' && item.messageId === message.id)
-    if (index === -1) return
-    this.queued = this.queued.filter((_item, candidate) => candidate !== index)
-    this.queueRev++
+    if (event.type === 'turn/start') this.firstPromptPendingTurn = false
+    const queueChanged = this.queueMirror.acceptDurable(event)
+    const publication = this.conversation.append({ event, view })
+    return queueChanged ? 'immediate' : publication
   }
 
   /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
    *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
    *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
-   *  raw range, which is what lets the transcript render every event between its ends and lets a
-   *  compaction checkpoint find its cited summary event. */
+   *  raw range, which lets Conversation Definitions correlate every recorded event between its
+   *  ends and lets a compaction checkpoint resolve its cited summary event. */
   private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
     if (this.openState === 'loading' || this.stitching) {
       this.liveBuffer.push({ event, view })
@@ -699,12 +644,13 @@ export class Session implements SessionFace {
       void this.repairGap()
       return
     }
-    this.appendLive(event, view)
-    if (event.type === 'assistant/chunk') {
-      if (isVisibleAssistantChunk(event.data.chunk.type)) this.notifier.markFrameDirty()
-      return
-    }
-    this.notifier.markDirty()
+    this.scheduleConversation(this.appendLive(event, view))
+  }
+
+  /** Route assembler cadence into the Session's existing microtask/RAF notifier. */
+  private scheduleConversation(publication: ConversationPublication): void {
+    if (publication === 'immediate') this.notifier.markDirty()
+    else if (publication === 'animation-frame') this.notifier.markFrameDirty()
   }
 
   /** Resync-lite (audit S3): repull the tail page and stitch the liveBuffer through the shared
@@ -728,238 +674,35 @@ export class Session implements SessionFace {
     }
   }
 
-  /** Per-event side effects (right column of the §A.9 dispatch table):
-   *  chunk/retry projection and openCalls add-remove. */
-  private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
-    const eventType = event.type as string
-    if (eventType === 'llm/retry') {
-      const data = parseRetryEventData(event.data)
-      if (data === null) {
-        console.error(`[web-runtime] ignored malformed llm/retry event at seq ${event.seq}`)
-        return
-      }
-      if (this.partial !== null && this.partial.turn === data.turn && this.partial.step === data.step) {
-        this.partial = null
-      }
-      this.derivedNodes.push({
-        kind: 'model-retry',
-        seq: event.seq,
-        time: event.time,
-        retryState: 'scheduled',
-        ...data,
-      })
-      this.derivedRev++
-      return
-    }
-    // These lifecycle events are declared by a host-only plugin whose Context
-    // types cannot enter the client program. ToolCallTree owns their structural
-    // wire narrowing, pairing, and nested snapshot projection.
-    if (this.toolCallTree.apply(event)) return
-    switch (event.type) {
-      case 'turn/start':
-        this.lastStepByTurn.set(event.data.turn, 0)
-        this.turnTimings.set(event.data.turn, { startTime: event.time })
-        this.turnTimingsRev++
-        return
-      case 'step/start':
-        this.lastStepByTurn.set(event.data.turn, event.data.step)
-        return
-      case 'assistant/chunk': {
-        const { turn, step, chunk } = event.data
-        this.settleScheduledRetry('started', turn)
-        if (this.partial === null || this.partial.turn !== turn || this.partial.step !== step) {
-          this.partial = new PartialAccumulator(turn, step)
-        }
-        this.partial.push(chunk)
-        return
-      }
-      case 'assistant/message': {
-        if (this.partial !== null && this.partial.turn === event.data.turn && this.partial.step === event.data.step) {
-          this.partial = null // finalize swaps in place (same notification batch, no flicker)
-        }
-        return
-      }
-      case 'tool/call': {
-        this.openCalls.set(String(event.data.callId), {
-          callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
-          turn: event.data.turn, step: event.data.step, time: event.time,
-          callView: view?.for === 'call' ? view.view : null,
-          subCalls: [],
-        })
-        this.callsRev++
-        return
-      }
-      case 'tool/result': {
-        if (this.openCalls.delete(String(event.data.message.source.callId))) this.callsRev++
-        return
-      }
-      case 'turn/end': {
-        const lastStep = this.lastStepByTurn.get(event.data.turn) ?? 0
-        const timing = this.turnTimings.get(event.data.turn)
-        if (timing !== undefined) {
-          this.turnTimings.set(event.data.turn, { ...timing, endTime: event.time })
-          this.turnTimingsRev++
-        }
-        this.turnEnds.set(event.data.turn, event.seq)
-        this.turnEndsRev++
-        if (event.data.reason.kind === 'aborted') {
-          this.settleScheduledRetry('cancelled', event.data.turn)
-        }
-        if (
-          event.data.reason.kind === 'error'
-          && !this.derivedNodes.some(node => node.kind === 'model-retry' && node.turn === event.data.turn)
-        ) {
-          const failure = event.data.reason.error
-          this.derivedNodes.push({
-            kind: 'turn-error',
-            seq: event.seq,
-            time: event.time,
-            turn: event.data.turn,
-            step: lastStep,
-            message: displayFailureMessage(failure),
-            code: failure.code,
-          })
-          this.derivedRev++
-        }
-        if (event.data.reason.kind === 'error') this.settleScheduledRetry('started', event.data.turn)
-        // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it
-        // into an interrupted terminal node (pulse stops, text survives) instead of deleting it.
-        // Shared by live and window-replay paths, so a refresh reconstructs the same frozen node
-        // from the logged chunks. Content-free partials are dropped outright.
-        if (this.partial !== null && this.partial.turn === event.data.turn) {
-          const { blocks } = this.partial.toPartial()
-          const visible = blocks.some(b => (b.kind === 'text' || b.kind === 'reasoning' ? b.text !== '' : true))
-          if (visible) {
-            // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
-            this.derivedNodes.push({
-              kind: 'assistant', seq: event.seq - 0.9, time: event.time,
-              turn: this.partial.turn, step: this.partial.step,
-              blocks, interrupted: true,
-            })
-            this.derivedRev++
-          }
-          this.partial = null
-        }
-        let callOffset = 0
-        for (const [callId, call] of this.openCalls) {
-          if (call.turn !== event.data.turn) continue
-          this.openCalls.delete(callId)
-          this.callsRev++
-          // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
-          this.derivedNodes.push({
-            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, time: event.time,
-            callId,
-            call: { name: call.name, argsRaw: call.argsRaw },
-            callTime: call.time,
-            content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
-            callView: call.callView, resultView: null, subCalls: [],
-          })
-          this.derivedRev++
-        }
-        this.lastStepByTurn.delete(event.data.turn)
-        return
-      }
-      default:
-        return
-    }
-  }
-
-  /**
-   * Settle the newest scheduled retry, optionally restricted to its failed turn.
-   * @param retryState - next client projection state to publish.
-   * @param turn - failed turn required for cancellation; omitted for the next retry turn start.
-   */
-  private settleScheduledRetry(
-    retryState: Exclude<ModelRetryNode['retryState'], 'scheduled'>,
-    turn?: number,
-  ): void {
-    const index = this.derivedNodes.findLastIndex(node =>
-      node.kind === 'model-retry'
-      && node.retryState === 'scheduled'
-      && (turn === undefined || node.turn === turn))
-    if (index < 0) return
-    const node = this.derivedNodes[index]
-    /* v8 ignore next -- findLastIndex's predicate narrows the indexed node only at runtime. */
-    if (node?.kind !== 'model-retry') return
-    this.derivedNodes[index] = { ...node, retryState }
-    this.derivedRev++
-  }
-
-  /** Re-derive state (partial/openCalls/derivedNodes) from raw window events after a rebuild — keeps
-   *  paging/stitching consistent, and makes live handling and history replay converge on the same
-   *  retry notices and interrupted nodes. */
-  private rebuildDerivedFromWindow(): void {
-    this.partial = null
-    this.openCalls.clear()
-    this.lastStepByTurn.clear()
-    this.callsRev++
-    this.derivedNodes = []
-    this.derivedRev++
-    this.turnTimings = new Map()
-    this.turnTimingsRev++
-    this.turnEnds = new Map()
-    this.turnEndsRev++
-    this.toolCallTree.reset()
-    for (let i = 0; i < this.events.length; i++) {
-      const event = this.events[i]
-      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
-      if (event !== undefined) this.applyEventSideEffects(event, this.views[i])
-    }
-  }
-
   private windowTailSeq(): number | null {
     const tail = this.events[this.events.length - 1]
     return tail === undefined ? null : tail.seq
   }
 
   private buildSnapshot(): ConversationSnapshot {
-    const projected = this.transcript.nodes()
-    // Derived interruption nodes ride fractional seqs while retry notices keep their event seq.
-    // The transcript is seq-monotonic, so sorting the union preserves flow order. Cache the
-    // merge on (projected reference, derivedRev) to retain identity across unrelated swaps.
-    let nodes: readonly ConversationNode[]
-    if (this.nodesCache !== null && this.nodesCache.projected === projected && this.nodesCache.derivedRev === this.derivedRev) {
-      nodes = this.nodesCache.value
-    } else {
-      nodes = this.derivedNodes.length === 0
-        ? projected
-        : [...projected, ...this.derivedNodes].sort((a, b) => a.seq - b.seq)
-      this.nodesCache = { projected, derivedRev: this.derivedRev, value: nodes }
-    }
-    if (this.callsCache === null || this.callsCache.rev !== this.callsRev) {
-      this.callsCache = { rev: this.callsRev, value: [...this.openCalls.values()] }
-    }
-    if (this.turnTimingsCache === null || this.turnTimingsCache.rev !== this.turnTimingsRev) {
-      this.turnTimingsCache = { rev: this.turnTimingsRev, value: new Map(this.turnTimings) }
-    }
-    if (this.turnEndsCache === null || this.turnEndsCache.rev !== this.turnEndsRev) {
-      this.turnEndsCache = { rev: this.turnEndsRev, value: new Map(this.turnEnds) }
-    }
     if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
       this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
     }
-    if (this.queueCache === null || this.queueCache.rev !== this.queueRev) {
-      this.queueCache = { rev: this.queueRev, value: this.queued }
-    }
-    const partial = this.partial?.toPartial() ?? null
+    const chat = (this.conversation.snapshot('chat') as ChatSnapshot | undefined) ?? EMPTY_CHAT_SNAPSHOT
+    const legacy = chat.legacy
     return {
       sessionId: this.sessionId,
-      nodes: this.toolCallTree.projectNodes(nodes),
-      turnTimings: this.turnTimingsCache.value,
-      turnEnds: this.turnEndsCache.value,
-      partial,
-      runningCalls: this.toolCallTree.projectRunningCalls(this.callsCache.value),
+      chat,
+      nodes: legacy.nodes,
+      turnTimings: legacy.turnTimings,
+      turnEnds: legacy.turnEnds,
+      partial: legacy.partial,
+      runningCalls: legacy.runningCalls,
       pending: this.pendingCache.value,
-      queue: this.queueCache.value,
+      queue: this.queueMirror.snapshot(),
       running: this.running,
       subagent: this.address === undefined
         ? null
         : { address: this.address, parentAvailable: this.parentAvailable },
       composerPhase: derivePhase(
-        // Command lifecycle nodes are not conversation: running /permission
-        // or /plan on a fresh session keeps the hero (the client mirror of
-        // the host's no-turn sessionBlank predicate).
-        nodes.some(node => node.kind !== 'command') || partial !== null || this.running || this.pendingCache.value.length > 0,
+        (!this.blankBit && !this.firstPromptPendingTurn)
+          || this.running
+          || this.pendingCache.value.length > 0,
         this.promptAttempted,
       ),
       removed: this.removed,
@@ -985,67 +728,18 @@ export class Session implements SessionFace {
   }
 }
 
-/** Validate the plugin-owned payload at the session-event wire boundary. */
-function parseRetryEventData(value: unknown): LlmRetryEventData | null {
-  if (value === null || typeof value !== 'object') return null
-  const data = value as Record<string, unknown>
-  const failure = data.failure
-  if (failure === null || typeof failure !== 'object') return null
-  const failureData = failure as Record<string, unknown>
-  if (!nonNegativeSafeInteger(data.turn)
-    || !nonNegativeSafeInteger(data.step)
-    || typeof data.provider !== 'string'
-    || data.provider.length === 0
-    || typeof data.policyKey !== 'string'
-    || data.policyKey.length === 0
-    || !positiveSafeInteger(data.retry)
-    || typeof data.delayMs !== 'number'
-    || !Number.isFinite(data.delayMs)
-    || data.delayMs < 0
-    || data.delayMs > MAX_RETRY_DELAY_MS
-    || typeof failureData.message !== 'string'
-    || failureData.message.length === 0
-    || typeof failureData.code !== 'string'
-    || failureData.code.length === 0) return null
-  if (data.mode === 'normal') {
-    if (!positiveSafeInteger(data.maxRetries) || data.retry > data.maxRetries) return null
-  } else if (data.mode === 'always') {
-    if ('maxRetries' in data) return null
-  } else {
-    return null
-  }
-  if (failureData.status !== undefined
-    && (typeof failureData.status !== 'number'
-      || !Number.isInteger(failureData.status)
-      || failureData.status < 100
-      || failureData.status > 599)) return null
-  if (failureData.providerRetryAfterMs !== undefined
-    && (typeof failureData.providerRetryAfterMs !== 'number'
-      || !Number.isFinite(failureData.providerRetryAfterMs)
-      || failureData.providerRetryAfterMs <= 0)) return null
-  if (failureData.requestId !== undefined
-    && (typeof failureData.requestId !== 'string'
-      || failureData.requestId.length === 0)) return null
-  return data as unknown as LlmRetryEventData
-}
-
-function nonNegativeSafeInteger(value: unknown): value is number {
-  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
-}
-
-function positiveSafeInteger(value: unknown): value is number {
-  return nonNegativeSafeInteger(value) && value > 0
+/** Convert one wire history row into the assembler's transport-neutral input. */
+function conversationInput(entry: HistoryEntry): ConversationEventInput {
+  return { event: entry.event, view: entry.view }
 }
 
 /**
  * The composerPhase judgment — the single site that knows the predicate
- * (consumers switch on the result, never re-derive). Monotone per session
- * object: `hasContent` only grows within a window and `promptAttempted` is
- * sticky, so blank → engaging → active never steps back; a failed first
- * prompt stays engaging (retry semantics — see ComposerPhase).
- * @param hasContent - any conversation material exists (non-command nodes,
- *   partial, running turn, pending waits; command lifecycle rows alone keep
- *   the session blank).
+ * (consumers switch on the result, never re-derive). A failed first prompt
+ * stays engaging until an authoritative accepted-turn, running, or pending
+ * signal arrives (retry semantics — see ComposerPhase).
+ * @param hasContent - authoritative non-blank activity beyond a pending first
+ *   prompt, a running turn, or a pending interaction.
  * @param promptAttempted - a prompt was initiated on this session object.
  * @returns the derived phase.
  */
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
deleted file mode 100644
index 78090ce87f..0000000000
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ /dev/null
@@ -1,409 +0,0 @@
-// TranscriptAdapter: the human transcript projected from the raw event window
-// in LOG order. The model-visible surface deliberately shadows replaced ranges,
-// so it is the wrong source for conversation a reader already saw; this adapter
-// keeps every append-origin event at its own log position and contributes one
-// marker node per landed compaction checkpoint. Node order is therefore
-// seq-monotonic by construction — no surface fold, no padding sentinels, no
-// seq === index assertion to satisfy, and no degradation branch.
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-// Subpath export (package.json exports "./surface", alias added for this): all value imports
-// go through it — the package root points at lib/index.js (needs a build) which the vite
-// browser bundle cannot resolve; surface.ts has no Node dependencies.
-import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
-import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
-// declaration of the checkpoint source, reachable as a TYPE from this program.
-// The package ROOT is not — it reaches dsh-session's root, whose Context merge
-// declares the HOST `sessions: SessionStore` against this program's
-// `sessions: ISessions` (TS2717, the one-program-per-side rule in
-// docs/development.md).
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
-import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
-import { toAssistantBlocks } from './conversation.ts'
-import { contextForm, contextProvenance } from './context-provenance.ts'
-import { SteeringHistory } from './steering-history.ts'
-import type { AssistantStepMetadata } from './assistant-timing.ts'
-import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
-
-/**
- * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
- * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
- * import stays type-only because a value import would fail the client purity
- * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
- * forbidden in a browser bundle — while an erased type never reaches it.
- */
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
-
-/** In-window tool/call index entry used to materialize result cards. */
-interface CallIndexEntry {
-  name: string
-  argsRaw: string
-  turn: number
-  step: number
-  /** Unix epoch ms of the tool/call event. */
-  time: number
-  /** Wire view riding the tool/call (envelope-level; never inside the event). */
-  callView: ToolCallView | null
-}
-
-/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
-function materializeNode(
-  event: SessionEvent,
-  callIndex: ReadonlyMap<string, CallIndexEntry>,
-  resultView: ToolResultView | null,
-  steering: boolean,
-  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
-): ConversationNode {
-  switch (event.type) {
-    case 'user/message': {
-      // Injected context (plugin/goal/skill-invocation source) folds to a
-      // context node, not a user message; only a direct human prompt is a
-      // user node. A compaction checkpoint never reaches here
-      // (isCompactCheckpoint routes it away).
-      if (event.data.source.kind !== 'user') {
-        return {
-          kind: 'context', seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-          provenance: contextProvenance(event.data.source),
-          form: contextForm(event.data.source),
-        }
-      }
-      if (steering) {
-        return {
-          kind: 'steering', messageId: event.data.id,
-          seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-        }
-      }
-      return {
-        kind: 'user', seq: event.seq, time: event.time,
-        content: event.data.content, source: event.data.source,
-      }
-    }
-    case 'assistant/message':
-      return {
-        kind: 'assistant', seq: event.seq, time: event.time,
-        turn: event.data.turn, step: event.data.step,
-        blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
-        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
-      }
-    case 'tool/result': {
-      const result = event.data.message.content[0]
-      const callId = String(event.data.message.source.callId)
-      const call = callIndex.get(callId)
-      return {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId,
-        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
-        callTime: call?.time ?? null,
-        content: result.content, isError: result.isError === true,
-        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
-        meta: event.data.meta,
-        callView: call?.callView ?? null,
-        resultView,
-        subCalls: [],
-      }
-    }
-    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
-    can be append-origin, and each has a case above; reachable only if core
-    adds an eligible type. */
-    default:
-      return {
-        kind: 'unknown', seq: event.seq, time: event.time,
-        type: event.type, data: (event as { data?: unknown }).data,
-      }
-  }
-}
-
-/**
- * Whether an event is a landed compaction checkpoint — all three conditions,
- * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
- * compaction seam's checkpoint plugin source, that REPLACED a surface range. A
- * plugin-sourced `user/message` that appends is injected context (a
- * session-reference card), not a compaction; a replacement `tool/result` is an
- * in-place prune and a replacement `assistant/message` a generic rewrite, and
- * both mark no boundary in the conversation.
- * @param event - the raw window event.
- * @returns true when the event compacted a surface range.
- */
-function isCompactCheckpoint(event: SessionEvent): boolean {
-  if (event.type !== 'user/message') return false
-  const source = event.data.source
-  return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN
-    && isReplacementSurfaceEvent(event)
-}
-
-/** Whether an event contributes a node to the human transcript. */
-function isTranscriptEvent(event: SessionEvent): boolean {
-  return isAppendSurfaceEvent(event) || isCompactCheckpoint(event)
-}
-
-/**
- * Concatenated text of a `compact/summary` payload, or null when it carries no
- * usable text. The payload is a `ContentBlock[]` whose union is
- * merge-extensible, so a non-text block is skipped rather than discarding the
- * text beside it; a payload with no text block at all falls to null through the
- * empty check.
- */
-function compactSummaryText(event: SessionEvent): string | null {
-  const summary = (event.data as unknown as { summary?: unknown }).summary
-  if (!Array.isArray(summary)) return null
-  let text = ''
-  for (const block of summary as readonly unknown[]) {
-    const candidate = block as { type?: unknown; text?: unknown }
-    if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue
-    text += candidate.text
-  }
-  return text.trim() === '' ? null : text
-}
-
-interface CompactSummaryDetails {
-  readonly summary: string | null
-  readonly shadowedItemCount: number | null
-  readonly shadowedTokenCount: number | null
-}
-
-/** Recover human-facing summary material from one structurally narrowed wire event. */
-function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
-  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
-  const shadowedSeqs = data.shadowedSeqs
-  const tokenCount = data.shadowedTokenCount
-  return {
-    summary: compactSummaryText(event),
-    shadowedItemCount: Array.isArray(shadowedSeqs)
-      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
-      ? shadowedSeqs.length
-      : null,
-    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
-      ? tokenCount as number
-      : null,
-  }
-}
-
-/**
- * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
- * `compact/summary` event), never from the framed checkpoint payload, which is
- * an instruction envelope written for the model. A window cut that left the
- * summary event outside soft-falls to `summary: null` (a non-expandable marker),
- * the same posture as a call-less tool result.
- */
-function materializeCompaction(
-  checkpoint: SessionEvent,
-  eventIndex: ReadonlyMap<number, SessionEvent>,
-): CompactionSummaryNode {
-  const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
-  let summary: string | null = null
-  let summaryEventSeq: number | null = null
-  let shadowedItemCount: number | null = null
-  let shadowedTokenCount: number | null = null
-  for (const seq of sources ?? []) {
-    const candidate = eventIndex.get(seq)
-    if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
-    const details = compactSummaryDetails(candidate)
-    summary = details.summary
-    summaryEventSeq = candidate.seq
-    shadowedItemCount = details.shadowedItemCount
-    shadowedTokenCount = details.shadowedTokenCount
-    break
-  }
-  return {
-    kind: 'compaction',
-    seq: checkpoint.seq,
-    time: checkpoint.time,
-    summary,
-    summaryEventSeq,
-    shadowedItemCount,
-    shadowedTokenCount,
-  }
-}
-
-/** Log-ordered human transcript over a paged raw event window (never consults surface order). */
-export class TranscriptAdapter {
-  /** Window events by seq, used to find the summary event cited by a checkpoint. */
-  private eventIndex = new Map<number, SessionEvent>()
-  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
-  private projected: ConversationNode[] = []
-  private callIdx = new Map<string, CallIndexEntry>()
-  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
-  private stepTimings = new Map<string, AssistantStepMetadata>()
-  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
-  private resultViews = new Map<number, ToolResultView>()
-  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
-  private readonly steeringHistory = new SteeringHistory()
-  /**
-   * Command lifecycle nodes by commandId (insertion = run order). The
-   * `command/run`/`command/done` pair is log-only, so it is not a surface
-   * event and never joins the transcript projection; this index folds the pair
-   * (done settles its run's node in place) and nodes() merges the products in
-   * by seq. Window cuts soft-fall like tool pairs: a done with no in-window
-   * run still builds a node.
-   */
-  private commandIdx = new Map<string, CommandNode>()
-  /** Projection revision, bumped only when a transcript node or a command node actually
-   *  changed, keying the nodes() result cache: an unchanged projection returns the previous
-   *  ARRAY reference, not just cached elements — the snapshot's reference-stability contract
-   *  (§A.9.4) starts here, and a chunk storm bumps nothing at all. */
-  private rev = 0
-  private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null
-
-  /**
-   * Window rebuild (after open/resync/page prepend): re-index the raw window
-   * and re-project the transcript.
-   * @param events - the new window contents (seq-ascending).
-   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
-   */
-  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
-    this.rev++
-    this.eventIndex = new Map()
-    this.callIdx = new Map()
-    this.resultViews.clear()
-    this.commandIdx = new Map()
-    this.steeringHistory.reset()
-    const steeringSeqs = new Set<number>()
-    this.stepTimings = new Map()
-    for (let i = 0; i < events.length; i++) {
-      const event = events[i]
-      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
-      if (event === undefined) continue
-      this.eventIndex.set(event.seq, event)
-      this.indexCall(event, views?.[i])
-      this.indexCommand(event)
-      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
-      indexAssistantStepTiming(this.stepTimings, event)
-    }
-    // Indexes first, then project: a tool/result materializes against the
-    // complete call index, and a checkpoint against the complete event index.
-    const projected: ConversationNode[] = []
-    for (const event of events) {
-      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
-    }
-    this.projected = projected
-  }
-
-  /**
-   * Tail append (live session/event): index the event and, when it belongs to
-   * the transcript, extend the projection by one copy-on-write node so a
-   * published array never mutates. An event that changes no node (a chunk
-   * storm) bumps no revision, so nodes() keeps returning the same array
-   * reference.
-   * @param event - the live event (seq = window tail + 1).
-   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
-   */
-  append(event: SessionEvent, view?: ToolEventView): void {
-    this.eventIndex.set(event.seq, event)
-    this.indexCall(event, view)
-    const steering = this.steeringHistory.apply(event)
-    indexAssistantStepTiming(this.stepTimings, event)
-    if (this.indexCommand(event)) this.rev++
-    if (!isTranscriptEvent(event)) return
-    this.projected = [...this.projected, this.materialize(event, steering)]
-    this.rev++
-  }
-
-  /**
-   * The current transcript node array. Same revision -> same array reference
-   * (memo boundary); node objects are materialized once, so an unchanged node
-   * keeps its identity across appends.
-   * @returns transcript nodes in log order, command nodes merged in by seq.
-   */
-  nodes(): readonly ConversationNode[] {
-    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
-    // Command nodes fold outside the transcript (log-only events); merge by
-    // seq. Both inputs are seq-ascending (log order and run-index insertion
-    // order are the same order), so one linear merge keeps flow order.
-    let nodes = this.projected
-    if (this.commandIdx.size > 0) {
-      nodes = []
-      const commands = [...this.commandIdx.values()]
-      let next = 0
-      for (const node of this.projected) {
-        for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) {
-          nodes.push(cmd)
-        }
-        nodes.push(node)
-      }
-      for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd)
-    }
-    this.nodesResult = { rev: this.rev, value: nodes }
-    return nodes
-  }
-
-  /** Materialize one transcript event against the complete current indexes. */
-  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
-    return isCompactCheckpoint(event)
-      ? materializeCompaction(event, this.eventIndex)
-      : materializeNode(
-        event,
-        this.callIdx,
-        this.resultViews.get(event.seq) ?? null,
-        steering,
-        this.stepTimings,
-      )
-  }
-
-  /**
-   * Fold one command lifecycle event into its node (run mints, done settles in
-   * place; done-only soft-falls).
-   * @returns whether the command index changed, so callers can bump the revision.
-   */
-  private indexCommand(event: SessionEvent): boolean {
-    // Log-only plugin events: the host-side dsh-commands declaration cannot
-    // enter the client program, so this wire consumer narrows structurally
-    // (the same posture as tool/code-dispatch in session.ts).
-    if ((event.type as string) === 'command/run') {
-      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
-      })
-      return true
-    }
-    if ((event.type as string) !== 'command/done') return false
-    const data = event.data as unknown as {
-      commandId: CommandId
-      kind: 'success' | 'error'
-      text?: string
-      sourceEventSeq?: number
-    }
-    const run = this.commandIdx.get(data.commandId)
-    const sourceEventSeq = data.kind === 'success'
-      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
-      ? data.sourceEventSeq as number
-      : undefined
-    const outcome = {
-      kind: data.kind,
-      ...data.text === undefined ? {} : { text: data.text },
-      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
-    }
-    if (run === undefined) {
-      // Cross-window cut: the run page fell out of the window — build the
-      // node from the done alone (same soft-fall as a call-less tool result).
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: null, args: null, outcome,
-      })
-      return true
-    }
-    // Settle in place: a fresh node object (published references stay immutable).
-    this.commandIdx.set(data.commandId, { ...run, outcome })
-    return true
-  }
-
-  private indexCall(event: SessionEvent, view?: ToolEventView): void {
-    if (event.type === 'tool/result') {
-      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
-      return
-    }
-    if (event.type !== 'tool/call') return
-    this.callIdx.set(String(event.data.callId), {
-      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
-      time: event.time,
-      callView: view?.for === 'call' ? view.view : null,
-    })
-    // No backfill into already-materialized tool-result nodes for this callId
-    // (window order puts the call before its result; cannot happen on the normal path).
-  }
-}
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index a30adb4dd6..e3ad848e05 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -320,7 +320,7 @@ export class SlotsService extends Service {
     const dispose = (this._core as unknown as ErasedCore).register(erased, component)
     if (store !== undefined) {
       // Register succeeded, so the target's spec is on the ledger.
-      const scope = (this._core.specDynamic(options.name) as SlotSpec<never>).scope
+      const scope = (this._core.specDynamic(options.name) as SlotSpec<SlotEntryDef>).scope
       this._acquire(store, scope)
     }
     let disposed = false
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 7d7d9a6c34..4ed6ecf519 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -101,15 +101,40 @@ export interface SlotEntryDef {
   kind: SlotKind
   scope: SlotScope
   owner?: object
+  /**
+   * Optional keyed-entry prop table. A keyed registration contributes one
+   * literal key and receives the corresponding prop share; ordinary owner
+   * props remain common to every key.
+   */
+  keyProps?: Record<string, object>
+  /**
+   * Optional opaque context carried by one renderSlot occurrence. Only
+   * function-valued members of the slot-level injected hooks compartment
+   * receive it; the slot machinery never interprets the value.
+   */
+  hookContext?: unknown
+  /**
+   * Optional Slot-level inject face supplied by the parent registration's
+   * child declaration. Every registered entry receives its bound component
+   * face; child registrants do not own or replace this common capability.
+   */
+  inject?: object
 }
 
 /**
  * Runtime dispatch spec for one slot, recorded from a register call's
  * `children` value. The literal is compile-time checked against the SlotMap
- * entry (`SlotSpec<SlotMap[P]>` in {@link ChildrenDecl}), so type and value
- * are declared at one point and validate each other.
+ * entry (`SlotSpec<SlotMap[P]>` in {@link ChildrenDecl}), so kind, scope, and
+ * any common inject face are declared at one point and validate each other.
  */
-export interface SlotSpec<E extends SlotEntryDef> { kind: E['kind']; scope: E['scope'] }
+export type SlotSpec<E extends SlotEntryDef> = {
+  kind: E['kind']
+  scope: E['scope']
+} & ('inject' extends keyof E
+  ? E extends { inject: infer Injected extends object }
+    ? { inject: Injected }
+    : { inject?: object }
+  : { inject?: never })
 
 /**
  * Child-slot declaration table for register(): keys are the declared (and
@@ -123,6 +148,30 @@ export type ChildrenDecl = { [P in keyof SlotMap & string]?: SlotSpec<SlotMap[P]
 export type OwnerOf<K extends keyof SlotMap & string> =
   SlotMap[K] extends { owner: infer O extends object } ? O : object
 
+/** Registration/dispatch key domain of one keyed slot. */
+export type EntryKeyOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { kind: 'keyed'; keyProps: infer P extends object }
+    ? keyof P & string
+    : string
+
+/** Key-dependent props supplied by the owner at one keyed dispatch site. */
+export type KeyPropsOf<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
+> = SlotMap[K] extends { kind: 'keyed'; keyProps: infer P extends object }
+  ? EntryKey extends keyof P
+    ? P[EntryKey] extends object ? P[EntryKey] : never
+    : never
+  : object
+
+/** Opaque per-render occurrence context declared by one slot. */
+export type HookContextOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { hookContext: infer Context } ? Context : never
+
+/** Common render-occurrence inject face declared by one slot. */
+export type SlotInjectOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { inject: infer Injected extends object } ? Injected : object
+
 /** Scope axis of a slot key's SlotMap entry. */
 export type ScopeOf<K extends keyof SlotMap & string> = SlotMap[K]['scope']
 
@@ -159,15 +208,26 @@ export type SessionIdOf = SessionStandardProps extends { sessionId: infer S } ?
  * Runtime props share for a slot key: owner share (parent's renderSlot call
  * site) + session standard kit (session scope only) + the global seat.
  */
-export type PropsRuntime<K extends keyof SlotMap & string> =
+export type PropsRuntime<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
+> =
   OwnerOf<K> &
+  KeyPropsOf<K, EntryKey> &
+  SlotInjectFace<SlotInjectOf<K>> &
   (ScopeOf<K> extends 'session' ? SessionStandardProps
     : ScopeOf<K> extends 'session-maybe' ? SessionMaybeStandardProps
       : object) &
   GlobalStandardProps
 
-/** renderSlot dispatch options: keyed dispatch key, list filtering, empty fallback. */
-export interface RenderOpts { entryKey?: string; only?: string; fallback?: ReactNode }
+/** renderSlot dispatch options: keyed dispatch key, list filtering, and empty fallback. */
+export interface RenderOpts<EntryKey extends string = string> {
+  entryKey?: EntryKey
+  only?: string
+  fallback?: ReactNode
+  /** Type-erased runtime seat; PropsRenderSlots narrows or removes it per slot declaration. */
+  hookContext?: unknown
+}
 
 /** renderSlotChain dispatch options. */
 export interface ChainRenderOpts {
@@ -200,6 +260,40 @@ export type ChainSelect<O extends object, M> = (owner: O) => M | null
 export type ChainKeysOf<S extends keyof SlotMap & string> =
   S extends unknown ? (SlotMap[S]['kind'] extends 'chain' ? S : never) : never
 
+/** Keys in a render share whose dispatch occurrence requires hookContext. */
+type ContextualKeysOf<S extends keyof SlotMap & string> =
+  S extends unknown ? (SlotMap[S] extends { hookContext: unknown } ? S : never) : never
+
+/** Keys in a render share with the ordinary optional options bag. */
+type OrdinaryKeysOf<S extends keyof SlotMap & string> = Exclude<S, ContextualKeysOf<S>>
+
+/**
+ * Plain and contextual child dispatch signatures. Keeping them as separate
+ * call signatures preserves ordinary renderSlot assignability while making a
+ * declared hookContext mandatory only for the Slot keys that need it.
+ */
+type RenderSlotFn<S extends keyof SlotMap & string> =
+  ([ContextualKeysOf<S>] extends [never] ? object : {
+    <
+      K extends ContextualKeysOf<S>,
+      EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
+    >(
+      key: K,
+      owner: OwnerOf<K> & KeyPropsOf<K, NoInfer<EntryKey>>,
+      opts: RenderOpts<EntryKey> & { hookContext: HookContextOf<K> },
+    ): ReactNode
+  }) &
+  ([OrdinaryKeysOf<S>] extends [never] ? object : {
+    <
+      K extends OrdinaryKeysOf<S>,
+      EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
+    >(
+      key: K,
+      owner: OwnerOf<K> & KeyPropsOf<K, NoInfer<EntryKey>>,
+      opts?: Omit<RenderOpts<EntryKey>, 'hookContext'>,
+    ): ReactNode
+  })
+
 /**
  * Chain matched share: a chain-slot component receives its selector's
  * non-null result as the framework-injected `matched` prop; other kinds add
@@ -248,7 +342,7 @@ export type PropsRenderSlots<S extends keyof SlotMap & string> = {
    * @param opts - kind dispatch options.
    * @returns rendered node(s).
    */
-  renderSlot: <K extends Exclude<S, ChainKeysOf<S>>>(key: K, owner: OwnerOf<K>, opts?: RenderOpts) => ReactNode
+  renderSlot: RenderSlotFn<Exclude<S, ChainKeysOf<S>>>
   readonly __renders?: ((key: S) => void) | undefined
 } & ([ChainKeysOf<S>] extends [never] ? object : {
   /**
@@ -277,19 +371,53 @@ export type SlotComponent<P> = (props: P) => ReactNode
 
 /**
  * Registrant hooks compartment: bare observable sources (getSnapshot +
- * subscribe pairs) supplied under the reserved `hooks` key of an inject
- * face. The registrant-private twin of the `sessions.provide` hooks
- * compartment: the renderer binds each source into a `use<Name>` selector
- * hook, so the sources never reach the component and plugin-private reactive
- * facts ride the same subscription machinery as the standard kit instead of
- * hand-rolled component subscriptions.
+ * subscribe pairs) supplied under the reserved `hooks` key of an entry's
+ * inject face. These retain the original source-to-selector binding and do
+ * not participate in render-occurrence context.
  */
 export type HooksSources = Record<string, HostObservable<unknown>>
 
+/** Framework-owned props visible while a slot-level contextual Hook is bound. */
+export type StandardPropsOf<K extends keyof SlotMap & string> =
+  (ScopeOf<K> extends 'session' ? SessionStandardProps
+    : ScopeOf<K> extends 'session-maybe' ? SessionMaybeStandardProps
+      : object) &
+  GlobalStandardProps
+
+/**
+ * One function-valued slot-level inject.hooks member. The factory is pure and
+ * returns the actual custom Hook; it must not invoke a Hook while being bound.
+ */
+export type SlotHookFactory<
+  K extends keyof SlotMap & string,
+  Hook extends (...args: never[]) => unknown,
+> = (
+  standard: StandardPropsOf<K>,
+  hookContext: HookContextOf<K>,
+) => Hook
+
+/** Component-side Hook produced from one slot-level inject.hooks member. */
+type BoundHookOf<Definition> =
+  Definition extends HostObservable<infer Snapshot>
+    ? SnapshotSelectorHook<Snapshot>
+    : Definition extends (...args: never[]) => infer Hook
+      ? Hook extends (...args: never[]) => unknown ? Hook : never
+      : never
+
 /**
  * Selector-hook share synthesized from a hooks compartment: each source
  * `name` becomes a `use<Name>` selector hook over its snapshot type.
  */
+export type PropsSlotHooks<HS extends object> = {
+  [N in keyof HS & string as `use${Capitalize<N>}`]:
+  BoundHookOf<HS[N]>
+}
+
+/** Component-side view of a slot dispatcher's common inject face. */
+export type SlotInjectFace<I extends object> =
+  I extends { hooks: infer HS extends object } ? Omit<I, 'hooks'> & PropsSlotHooks<HS> : I
+
+/** Selector-hook share synthesized from an entry inject hooks compartment. */
 export type PropsHooks<HS extends HooksSources> = {
   [N in keyof HS & string as `use${Capitalize<N>}`]:
   SnapshotSelectorHook<HS[N] extends HostObservable<infer T> ? T : never>
@@ -313,12 +441,13 @@ export type InjectFace<I extends object> =
  */
 export type ComposedProps<
   K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
   S extends keyof SlotMap & string,
   H,
   I extends object,
   M = never,
   N = undefined,
-> = PropsRuntime<K> & PropsRenderSlots<S> & PropsStore<H> & InjectFace<I> & MatchedShare<SlotMap[K], M> & PropsLocale<N>
+> = PropsRuntime<K, EntryKey> & PropsRenderSlots<S> & PropsStore<H> & InjectFace<I> & MatchedShare<SlotMap[K], M> & PropsLocale<N>
 
 /**
  * Inject factory parameter list, derived from the registration's declaration:
@@ -345,12 +474,16 @@ export type InjectParams<K extends keyof SlotMap & string, H> =
 export type SlotLabel = string | (() => string)
 
 /** Kind shape fields carried in register options (keyed dispatch key; list id/order/label; chain select/priority). */
-export type KindOptions<E extends SlotEntryDef, M = never> =
-  E['kind'] extends 'keyed' ? { key: string }
-    : E['kind'] extends 'list' ? { id: string; order?: number; label?: SlotLabel }
-      : E['kind'] extends 'chain' ? {
+export type KindOptions<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
+  M = never,
+> =
+  SlotMap[K]['kind'] extends 'keyed' ? { key: EntryKey }
+    : SlotMap[K]['kind'] extends 'list' ? { id: string; order?: number; label?: SlotLabel }
+      : SlotMap[K]['kind'] extends 'chain' ? {
         /** Routing selector, mandatory on chain entries; `M` (the component's `matched` prop) infers from its return. */
-        select: ChainSelect<E extends { owner: infer O extends object } ? O : object, M>
+        select: ChainSelect<SlotMap[K] extends { owner: infer O extends object } ? O : object, M>
         /** Explicit chain position (ascending, default 0, lower tries first); ties keep registration = assembly order. */
         priority?: number
       }
@@ -372,7 +505,14 @@ type RendersCheck<C, D> =
       : unknown
 
 /** Common register options share (see {@link SlotCore.register} for semantics). */
-type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M = never, N = undefined> = {
+type BaseOptions<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
+  D extends ChildrenDecl,
+  H,
+  M = never,
+  N = undefined,
+> = {
   /** Target slot key (the entry contributes INTO this slot). */
   name: K
   /** Child-slot declaration + render authorization + runtime spec, in one table. */
@@ -388,7 +528,7 @@ type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M
   locale?: N
   /** Registrant identity label for diagnostics (the runtime Service wrapper stamps the caller's fiber name). */
   registrant?: string
-} & KindOptions<SlotMap[K], M>
+} & KindOptions<K, EntryKey, M>
 
 /**
  * One stored registration, as recorded by the core and read by the render
@@ -528,15 +668,16 @@ export class SlotCore {
    * would lose the per-overload inference of I. */
   register<
     K extends keyof SlotMap & string,
+    const EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
     const D extends ChildrenDecl = Record<never, never>,
     H extends StoreDecl | undefined = undefined,
     M = never,
     N extends (keyof LocaleNamespaceMap & string) | undefined = undefined,
     C extends SlotComponent<never> = SlotComponent<never>,
   >(
-    options: BaseOptions<K, D, H, M, N> & { inject?: undefined },
+    options: BaseOptions<K, EntryKey, D, H, M, N> & { inject?: undefined },
     component: C
-      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>>>
       & RendersCheck<C, D>,
   ): () => void
   /**
@@ -552,15 +693,16 @@ export class SlotCore {
   register<
     K extends keyof SlotMap & string,
     I extends object,
+    const EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
     const D extends ChildrenDecl = Record<never, never>,
     H extends StoreDecl | undefined = undefined,
     M = never,
     N extends (keyof LocaleNamespaceMap & string) | undefined = undefined,
     C extends SlotComponent<never> = SlotComponent<never>,
   >(
-    options: BaseOptions<K, D, H, M, N> & { inject: (...args: InjectParams<K, H>) => I },
+    options: BaseOptions<K, EntryKey, D, H, M, N> & { inject: (...args: InjectParams<K, H>) => I },
     component: C
-      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>>>
       & RendersCheck<C, D>,
   ): () => void
   /* jscpd:ignore-end */
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 2a676fa22a..20f6a68eb1 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -87,11 +87,13 @@ export interface SessionProvideInfo extends SessionMaybeProvideInfo {
   hooks: Record<string, HostObservable<unknown>>
 }
 
-/** renderSlot dispatch options at the machinery level: keyed dispatch key, list filtering, empty fallback. */
+/** renderSlot dispatch options at the machinery level. */
 export interface RenderOpts {
   entryKey?: string
   only?: string
   fallback?: ReactNode
+  /** Opaque occurrence context consumed only by function-valued injected Hooks. */
+  hookContext?: unknown
 }
 
 /** Host surface the runtime SlotsService presents to the installed renderer. */
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index f7a3c32e93..69d37f35b4 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -2,7 +2,7 @@
  * React renderer for declarative slots. Per-entry bindings enforce child
  * authorization, and entry boundaries contain registrant failures.
  */
-import { Component, useState, useSyncExternalStore, type FC, type ReactNode } from 'react'
+import { Component, useMemo, useState, useSyncExternalStore, type FC, type ReactNode } from 'react'
 import {
   SlotOwnershipError, StaleAuthorizationError,
   type ChainRenderOpts, type HostObservable, type LocaleFace, type RenderOpts,
@@ -16,6 +16,14 @@ import {
 
 type InjectedProps = Record<string, unknown>
 
+type SlotHookFactory = (standard: InjectedProps, hookContext: unknown) => unknown
+type SlotHookFactories = Readonly<Record<string, SlotHookFactory>>
+
+interface BoundSlotInject {
+  readonly props: InjectedProps
+  readonly slotHookFactories?: SlotHookFactories | undefined
+}
+
 type RenderSlotBinding = (key: string, owner: object, opts?: RenderOpts) => ReactNode
 
 type RenderSlotChainBinding = (key: string, owner: object, opts?: ChainRenderOpts) => ReactNode
@@ -89,9 +97,11 @@ const rootInjectCache = new WeakMap<StoredEntry, InjectedProps>()
 const sessionInjectCache = new WeakMap<StoredEntry, WeakMap<SessionProvideInfo, InjectedProps>>()
 const sessionMaybeInjectCache = new WeakMap<StoredEntry, WeakMap<SessionMaybeProvideInfo, InjectedProps>>()
 
+const EMPTY_INJECTED_PROPS: InjectedProps = {}
+
 function runInject(entry: StoredEntry, info: SessionMaybeProvideInfo | undefined, actions: object | undefined): InjectedProps {
   const inject = entry.inject
-  if (!inject) return {}
+  if (!inject) return EMPTY_INJECTED_PROPS
   // Declaration-derived positional arguments: sessionId for session scope,
   // baked actions when a store is declared.
   const args: unknown[] = []
@@ -101,11 +111,8 @@ function runInject(entry: StoredEntry, info: SessionMaybeProvideInfo | undefined
 }
 
 /**
- * Bind an inject face's reserved `hooks` compartment (bare observable
- * sources, see HooksSources) into `use<Name>` selector hooks — the
- * registrant-private twin of the provide-bundle binding in standardKit.
- * Runs once per cached inject result; hook identity rides observableHook's
- * per-source cache.
+ * Normalize one entry-owned inject face on its existing cache axis. Its hooks
+ * compartment remains the original Observable-only contract.
  */
 function bindInjectHooks(face: InjectedProps): InjectedProps {
   const sources = face['hooks']
@@ -119,6 +126,53 @@ function bindInjectHooks(face: InjectedProps): InjectedProps {
   return bound
 }
 
+const slotInjectCache = new WeakMap<object, BoundSlotInject>()
+const EMPTY_SLOT_INJECT: BoundSlotInject = { props: EMPTY_INJECTED_PROPS }
+
+/** Normalize one dispatcher-owned inject face by its stable object identity. */
+function cachedSlotInject(face: object | undefined): BoundSlotInject {
+  if (face === undefined) return EMPTY_SLOT_INJECT
+  let bound = slotInjectCache.get(face)
+  if (bound !== undefined) return bound
+  const definitions = (face as InjectedProps)['hooks']
+  if (definitions === undefined) {
+    bound = { props: face as InjectedProps }
+    slotInjectCache.set(face, bound)
+    return bound
+  }
+  const { hooks: _hooks, ...rest } = face as InjectedProps
+  const props: InjectedProps = rest
+  let factories: Record<string, SlotHookFactory> | undefined
+  for (const [name, definition] of Object.entries(definitions as Record<string, unknown>)) {
+    const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
+    if (typeof definition === 'function') {
+      factories ??= {}
+      factories[name] = definition as SlotHookFactory
+    } else {
+      props[hookName] = observableHook(definition as HostObservable<unknown>)
+    }
+  }
+  bound = factories === undefined
+    ? { props }
+    : { props, slotHookFactories: factories }
+  slotInjectCache.set(face, bound)
+  return bound
+}
+
+/** Bind deferred slot-level factories for one stable renderSlot occurrence. */
+function bindSlotHookFactories(
+  factories: SlotHookFactories,
+  standard: InjectedProps,
+  hookContext: unknown,
+): InjectedProps {
+  const hooks: InjectedProps = {}
+  for (const [name, factory] of Object.entries(factories)) {
+    const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
+    hooks[hookName] = factory(standard, hookContext)
+  }
+  return hooks
+}
+
 function cachedRootInject(entry: StoredEntry, actions: object | undefined): InjectedProps {
   let props = rootInjectCache.get(entry)
   if (!props) {
@@ -270,6 +324,54 @@ class SlotErrorBoundary extends Component<
   }
 }
 
+interface StandardPropsCache {
+  readonly root: InjectedProps
+  readonly session: WeakMap<SessionMaybeProvideInfo, InjectedProps>
+  readonly sessionMaybe: WeakMap<SessionMaybeProvideInfo, InjectedProps>
+}
+
+const standardPropsCache = new WeakMap<SlotRendererHost, StandardPropsCache>()
+
+/** Stable official-props object used by contextual Hook factories. */
+function standardProps(
+  host: SlotRendererHost,
+  scope: SlotScope,
+  info: SessionMaybeProvideInfo | undefined,
+): InjectedProps {
+  let cache = standardPropsCache.get(host)
+  if (cache === undefined) {
+    cache = {
+      root: {
+        useSessions: observableHook(host.sessions.list),
+        useWorkspaces: observableHook(host.workspaces.list),
+      },
+      session: new WeakMap(),
+      sessionMaybe: new WeakMap(),
+    }
+    standardPropsCache.set(host, cache)
+  }
+  if (scope === 'root') return cache.root
+  if (info === undefined) throw new SlotAssemblyError(`scope '${scope}' rendered without session provide info`)
+  const byInfo = scope === 'session' ? cache.session : cache.sessionMaybe
+  let standard = byInfo.get(info)
+  if (standard !== undefined) return standard
+  standard = { ...cache.root }
+  for (const [name, source] of Object.entries(info.hooks)) {
+    const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
+    if (scope === 'session-maybe') {
+      standard[hookName] = maybeObservableHook(source)
+    } else {
+      if (source === undefined) throw new SlotAssemblyError(`strict session hook '${name}' has no source`)
+      standard[hookName] = observableHook(source)
+    }
+  }
+  Object.assign(standard, info.props)
+  standard['sessionId'] = info.sessionId
+  standard['useProjection'] = projectionHook(info)
+  byInfo.set(info, standard)
+  return standard
+}
+
 /**
  * Standard-kit synthesis shared by both scope branches: the global
  * useSessions/useWorkspaces hooks, the per-session provide bundle (every
@@ -289,28 +391,11 @@ function standardKit(
   info: SessionMaybeProvideInfo | undefined,
 ): {
   kit: InjectedProps
+  standard: InjectedProps
   actions: object | undefined
 } {
-  const kit: InjectedProps = {
-    useSessions: observableHook(host.sessions.list),
-    useWorkspaces: observableHook(host.workspaces.list),
-  }
-  if (scope !== 'root' && info !== undefined) {
-    for (const [name, source] of Object.entries(info.hooks)) {
-      const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
-      if (scope === 'session-maybe') {
-        kit[hookName] = maybeObservableHook(source)
-      } else {
-        if (source === undefined) throw new SlotAssemblyError(`strict session hook '${name}' has no source`)
-        kit[hookName] = observableHook(source)
-      }
-    }
-    Object.assign(kit, info.props)
-    kit['sessionId'] = info.sessionId
-    // The useProjection seat (fifth framework hook): key-addressed cell
-    // reader, bound per provide bundle (cached by info identity).
-    kit['useProjection'] = projectionHook(info)
-  }
+  const standard = standardProps(host, scope, info)
+  const kit: InjectedProps = { ...standard }
   if (entry.locale !== undefined) {
     const face = host.locale
     // Loud assembly failure: locale is immediately-tier infrastructure; a
@@ -344,38 +429,98 @@ function standardKit(
       kit['SessionProvider'] = SessionProvider
     }
   }
-  return { kit, actions: store?.actions }
+  return { kit, standard, actions: store?.actions }
 }
 
 /**
- * One rendered entry: standard kit + cached inject + owner props (owner
- * wins). The kit and injected shares are erased at the render boundary — the
- * registration contract already proved the composed type — so each Entry renders
- * through a props-widened view of the component (the design-budgeted
- * composition point, one per scope branch).
+ * One rendered entry: standard kit + cached entry inject + common slot inject
+ * + owner props (owner wins). The shares are erased at this render boundary;
+ * the registration and renderSlot seams already proved their contracts.
  */
-function SessionEntry({ entry, ownerProps, info }: {
+function ContextualEntry({
+  slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext,
+}: {
+  slotKey: string
+  Comp: FC<InjectedProps>
+  kit: InjectedProps
+  standard: InjectedProps
+  injected: InjectedProps
+  slotInjected: BoundSlotInject & { readonly slotHookFactories: SlotHookFactories }
+  ownerProps: object
+  hookContext: unknown
+  hasHookContext: boolean
+}) {
+  const contextual = useMemo(
+    () => {
+      if (!hasHookContext) {
+        throw new SlotAssemblyError(`slot '${slotKey}' has contextual injected Hooks but no hookContext`)
+      }
+      return bindSlotHookFactories(slotInjected.slotHookFactories, standard, hookContext)
+    },
+    [hasHookContext, hookContext, slotInjected.slotHookFactories, slotKey, standard],
+  )
+  return <Comp {...kit} {...injected} {...slotInjected.props} {...contextual} {...ownerProps} />
+}
+
+function renderEntry(
+  slotKey: string,
+  Comp: FC<InjectedProps>,
+  kit: InjectedProps,
+  standard: InjectedProps,
+  injected: InjectedProps,
+  slotInjected: BoundSlotInject,
+  ownerProps: object,
+  hookContext: unknown,
+  hasHookContext: boolean,
+): ReactNode {
+  if (slotInjected.slotHookFactories === undefined) {
+    return <Comp {...kit} {...injected} {...slotInjected.props} {...ownerProps} />
+  }
+  return (
+    <ContextualEntry
+      slotKey={slotKey}
+      Comp={Comp}
+      kit={kit}
+      standard={standard}
+      injected={injected}
+      slotInjected={slotInjected as BoundSlotInject & { readonly slotHookFactories: SlotHookFactories }}
+      ownerProps={ownerProps}
+      hookContext={hookContext}
+      hasHookContext={hasHookContext}
+    />
+  )
+}
+
+function SessionEntry({ entry, ownerProps, info, slotKey, slotInjected, hookContext, hasHookContext }: {
   entry: StoredEntry
   ownerProps: object
   info: SessionProvideInfo
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
 }) {
   const host = useHost()
   const Comp = entry.component as FC<InjectedProps>
-  const { kit, actions } = standardKit(host, entry, 'session', info)
+  const { kit, standard, actions } = standardKit(host, entry, 'session', info)
   const injected = cachedSessionInject(entry, info, actions)
-  return <Comp {...kit} {...injected} {...ownerProps} />
+  return renderEntry(slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext)
 }
 
-function SessionMaybeEntryBody({ entry, ownerProps, info }: {
+function SessionMaybeEntryBody({ entry, ownerProps, info, slotKey, slotInjected, hookContext, hasHookContext }: {
   entry: StoredEntry
   ownerProps: object
   info: SessionMaybeProvideInfo
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
 }) {
   const host = useHost()
   const Comp = entry.component as FC<InjectedProps>
-  const { kit, actions } = standardKit(host, entry, 'session-maybe', info)
+  const { kit, standard, actions } = standardKit(host, entry, 'session-maybe', info)
   const injected = cachedSessionMaybeInject(entry, info, actions)
-  return <Comp {...kit} {...injected} {...ownerProps} />
+  return renderEntry(slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext)
 }
 
 /**
@@ -391,7 +536,14 @@ function SessionMaybeEntryBody({ entry, ownerProps, info }: {
  * that must SURVIVE a switch belongs in session-bound sources (machine,
  * store, hooks) — the existing layering rule, now load-bearing.
  */
-function SessionMaybeEntry({ entry, ownerProps }: { entry: StoredEntry; ownerProps: object }) {
+function SessionMaybeEntry({ entry, ownerProps, slotKey, slotInjected, hookContext, hasHookContext }: {
+  entry: StoredEntry
+  ownerProps: object
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
+}) {
   const info = useSessionMaybeProvideInfo()
   // The child key is an incarnation counter, NOT the session id: adoption
   // must keep the key constant across undefined → first id. Bookkeeping
@@ -416,7 +568,18 @@ function SessionMaybeEntry({ entry, ownerProps }: { entry: StoredEntry; ownerPro
     epoch += 1
     setState({ adopted, epoch })
   }
-  return <SessionMaybeEntryBody key={epoch} entry={entry} ownerProps={ownerProps} info={info} />
+  return (
+    <SessionMaybeEntryBody
+      key={epoch}
+      entry={entry}
+      ownerProps={ownerProps}
+      info={info}
+      slotKey={slotKey}
+      slotInjected={slotInjected}
+      hookContext={hookContext}
+      hasHookContext={hasHookContext}
+    />
+  )
 }
 
 /** Adoption bookkeeping of one session-maybe outlet (see SessionMaybeEntry). */
@@ -429,24 +592,42 @@ interface MaybeIncarnation {
 
 const FIRST_INCARNATION: MaybeIncarnation = { adopted: undefined, epoch: 0 }
 
-function RootEntry({ entry, ownerProps }: { entry: StoredEntry; ownerProps: object }) {
+function RootEntry({ entry, ownerProps, slotKey, slotInjected, hookContext, hasHookContext }: {
+  entry: StoredEntry
+  ownerProps: object
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
+}) {
   const host = useHost()
   const Comp = entry.component as FC<InjectedProps>
-  const { kit, actions } = standardKit(host, entry, 'root', undefined)
+  const { kit, standard, actions } = standardKit(host, entry, 'root', undefined)
   const injected = cachedRootInject(entry, actions)
-  return <Comp {...kit} {...injected} {...ownerProps} />
+  return renderEntry(slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext)
 }
 
-function StrictSessionEntry({ slotKey, entry, ownerProps }: {
+function StrictSessionEntry({ slotKey, entry, ownerProps, slotInjected, hookContext, hasHookContext }: {
   slotKey: string
   entry: StoredEntry
   ownerProps: object
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
 }) {
   const info = useSessionMaybeProvideInfo()
   if (info.sessionId === undefined) return null
   return (
     <SlotErrorBoundary slotKey={slotKey} key={info.sessionId}>
-      <SessionEntry entry={entry} ownerProps={ownerProps} info={info as SessionProvideInfo} />
+      <SessionEntry
+        entry={entry}
+        ownerProps={ownerProps}
+        info={info as SessionProvideInfo}
+        slotKey={slotKey}
+        slotInjected={slotInjected}
+        hookContext={hookContext}
+        hasHookContext={hasHookContext}
+      />
     </SlotErrorBoundary>
   )
 }
@@ -478,31 +659,62 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   // An absent strict overlay chain follows its ordinary empty-election path,
   // preserving the Fragment/fallback-wrapper shape across session arrival.
   const entries = strictSessionAbsent ? [] : host.entriesOf(slotKey)
+  const slotInjected = cachedSlotInject(spec.inject)
 
   // The boundary must wrap the Entry ELEMENT, not live inside it: inject
   // factories and kit synthesis run in the Entry body and must land in the
   // per-entry fallback rather than escaping to the tree above.
-  const guarded = (entry: StoredEntry, key?: string | number, owner: object = ownerProps) => (
-    spec.scope === 'session'
-      ? <StrictSessionEntry slotKey={slotKey} entry={entry} ownerProps={owner} key={key} />
+  const guarded = (entry: StoredEntry, key?: string | number, owner: object = ownerProps) => {
+    const hasHookContext = opts !== undefined && Object.hasOwn(opts, 'hookContext')
+    const hookContext = opts?.hookContext
+    return spec.scope === 'session'
+      ? (
+        <StrictSessionEntry
+          slotKey={slotKey}
+          entry={entry}
+          ownerProps={owner}
+          slotInjected={slotInjected}
+          hookContext={hookContext}
+          hasHookContext={hasHookContext}
+          key={key}
+        />
+      )
       : (
         <SlotErrorBoundary slotKey={slotKey} key={key}>
           {spec.scope === 'session-maybe'
-            ? <SessionMaybeEntry entry={entry} ownerProps={owner} />
-            : <RootEntry entry={entry} ownerProps={owner} />}
+            ? (
+              <SessionMaybeEntry
+                entry={entry}
+                ownerProps={owner}
+                slotKey={slotKey}
+                slotInjected={slotInjected}
+                hookContext={hookContext}
+                hasHookContext={hasHookContext}
+              />
+            )
+            : (
+              <RootEntry
+                entry={entry}
+                ownerProps={owner}
+                slotKey={slotKey}
+                slotInjected={slotInjected}
+                hookContext={hookContext}
+                hasHookContext={hasHookContext}
+              />
+            )}
         </SlotErrorBoundary>
       )
-  )
+  }
 
   if (spec.kind === 'single') {
     const entry = entries[0]
     if (!entry) return <>{opts?.fallback ?? null}</>
-    return guarded(entry)
+    return guarded(entry, entryKeyOf(entry))
   }
   if (spec.kind === 'keyed') {
     const entry = entries.find(e => e.options.key === opts?.entryKey)
     if (!entry) return <>{opts?.fallback ?? null}</>
-    return guarded(entry)
+    return guarded(entry, entryKeyOf(entry))
   }
   if (spec.kind === 'chain') {
     // Entries arrive priority-sorted from the ledger (the core orders at
@@ -561,7 +773,7 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   let list = [...withListOptions].sort((a, b) => a.order - b.order)
   if (opts?.only !== undefined) list = list.filter(item => item.id === opts.only)
   if (list.length === 0) return <>{opts?.fallback ?? null}</>
-  return <>{list.map((item, i) => guarded(item.entry, item.id ?? i))}</>
+  return <>{list.map(item => guarded(item.entry, entryKeyOf(item.entry)))}</>
 }
 
 /** Root outlet: the shell's single ctx-level render entry — an unregistered 'root' is a boot-order failure, never a silent blank (§1). */
@@ -575,8 +787,15 @@ function RootOutlet({ ownerProps }: { ownerProps: object }) {
   const entry = host.entriesOf('root')[0]
   if (!entry) throw new SlotAssemblyError("renderSlot('root') before any 'root' registration (boot order)")
   return (
-    <SlotErrorBoundary slotKey="root">
-      <RootEntry entry={entry} ownerProps={ownerProps} />
+    <SlotErrorBoundary slotKey="root" key={entryKeyOf(entry)}>
+      <RootEntry
+        entry={entry}
+        ownerProps={ownerProps}
+        slotKey="root"
+        slotInjected={EMPTY_SLOT_INJECT}
+        hookContext={undefined}
+        hasHookContext={false}
+      />
     </SlotErrorBoundary>
   )
 }

From 6d09b3168d035f7668ea73b745a115be1dc7eaac Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:40 +0800
Subject: [PATCH 234/262] refactor(ui-conversation): register business node
 definitions

---
 packages/client/ui-conversation/package.json  |   2 +
 .../ui-conversation/src/client/apply.ts       |  36 +-
 .../src/client/chat/AssistantMarkdown.tsx     |  72 +--
 .../src/client/chat/AssistantNodeView.tsx     |  32 ++
 .../src/client/chat/ChatNodeSeat.tsx          |  60 +++
 .../src/client/chat/ChatView.module.css       |  14 +-
 .../src/client/chat/ChatView.tsx              | 303 ++----------
 .../src/client/chat/CommandNodeView.tsx       |  40 ++
 .../src/client/chat/MessageItem.tsx           | 126 ++---
 .../src/client/chat/StatsLine.tsx             |   4 +-
 .../client/chat/TurnTailNodeView.module.css   |   9 +
 .../src/client/chat/TurnTailNodeView.tsx      |  43 ++
 .../src/client/chat/chat-flow.ts              | 214 --------
 .../client/chat/register-node-renderers.ts    |  46 ++
 .../src/client/chat/tool-node-reader.ts       |  46 ++
 .../src/client/chat/turn-assistant.ts         |  10 +
 .../src/client/chat/turn-metrics.ts           |   6 +-
 .../src/client/contract/chat-nodes.ts         |  82 ++++
 .../src/client/contract/slots.ts              |  93 ++--
 .../client/conversation-nodes/assistant.ts    | 316 ++++++++++++
 .../chat-snapshot-builder.ts                  | 456 ++++++++++++++++++
 .../src/client/conversation-nodes/command.ts  | 243 ++++++++++
 .../src/client/conversation-nodes/common.ts   |  55 +++
 .../client/conversation-nodes/compaction.ts   |  63 +++
 .../src/client/conversation-nodes/fallback.ts |  40 ++
 .../src/client/conversation-nodes/inbox.ts    |  71 +++
 .../src/client/conversation-nodes/message.ts  |  83 ++++
 .../src/client/conversation-nodes/register.ts |  30 ++
 .../src/client/conversation-nodes/retry.ts    | 116 +++++
 .../src/client/conversation-nodes/tool.ts     | 271 +++++++++++
 .../client/conversation-nodes/turn-error.ts   | 112 +++++
 .../client/conversation-nodes/turn-tail.ts    | 180 +++++++
 .../ui-conversation/src/client/index.ts       |  19 +-
 .../src/client/skeleton/ApprovalPanel.tsx     |   9 +-
 .../src/client/skeleton/DetailsPanel.tsx      |  27 +-
 .../client/ui-conversation/src/invariant.ts   |   2 +-
 .../ui-deliverables/src/client/index.ts       |   7 +-
 .../src/client/turn-deliverables.ts           | 139 ++++--
 packages/client/ui-tool/src/client/apply.ts   |   5 +-
 .../ui-tool/src/client/contract/slots.ts      |   4 +-
 .../ui-tool/src/client/tool/ToolCallTree.tsx  |   3 +-
 41 files changed, 2744 insertions(+), 745 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
 delete mode 100644 packages/client/ui-conversation/src/client/chat/chat-flow.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/register-node-renderers.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/tool-node-reader.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/turn-assistant.ts
 create mode 100644 packages/client/ui-conversation/src/client/contract/chat-nodes.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/command.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/common.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/message.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/register.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts

diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 2ff87cc0e2..3f5bd8364c 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -44,6 +44,7 @@
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
@@ -53,6 +54,7 @@
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 0e486e9154..6d8e8e8c67 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -7,8 +7,9 @@ import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
-  ApprovalWait, ChatScrollPosition, ChatViewInjected, ComposerBarInjected, ComposerChainProps, ConversationInjected,
-  ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected,
+  ApprovalWait, ChatNodeTurnDataInjected, ChatScrollPosition, ChatViewInjected, ComposerBarInjected,
+  ComposerChainProps, ConversationInjected, ConversationSessionHeaderInjected, ConversationSessionInjected,
+  DetailsInjected,
 } from './contract/slots.ts'
 import type { InputNotice } from './input/contract.ts'
 import { createChatStore } from './stores.ts'
@@ -30,6 +31,8 @@ import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
 import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
+import { registerConversationNodes } from './conversation-nodes/register.ts'
+import { registerChatNodeRenderers } from './chat/register-node-renderers.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -39,7 +42,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by the conversation plugin. */
-export const inject = ['slots', 'layout', 'sessions', 'workspaces', 'locale']
+export const inject = [
+  'slots', 'layout', 'sessions', 'workspaces', 'locale',
+  'conversationEvents', 'conversationViews',
+]
 
 // Static no-session sources for the composer-bar hooks compartment: module
 // constants so the render side's per-source hook cache (observableHook) keeps
@@ -63,6 +69,19 @@ const ABSENT_MENU_LAUNCHER = {
   subscribe: () => () => {},
 }
 
+const CHAT_NODE_INJECT: ChatNodeTurnDataInjected = {
+  hooks: {
+    turnData: ({ useSession }, nodeKey) => function useTurnData(key) {
+      return useSession((snapshot) => {
+        const location = snapshot.chat.nodes.get(nodeKey)?.location
+        return location?.kind === 'turn' || location?.kind === 'step'
+          ? location.turn.data.get(key)
+          : undefined
+      })
+    },
+  },
+}
+
 /** Resolve the session-scoped conversation face (scope-addressed send/cancel), failing loud. */
 function scopedConversation(sessions: ISessions, id: SessionId): IConversation {
   const scoped = sessions.scope(id)
@@ -86,6 +105,9 @@ export function apply(ctx: Context): void {
   const layout = ctx.layout
   const slots = ctx.slots
 
+  registerConversationNodes(ctx)
+  registerChatNodeRenderers(ctx)
+
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-conversation: dictionaries')
 
   // Registration-time text (the view tab label) reads through the bound
@@ -296,8 +318,8 @@ export function apply(ctx: Context): void {
   slots.register({ name: 'conversation.composer', select: selectApproval, priority: 1, locale: NS }, ApprovalPanel)
 
   // The chat view: first entry of the ring this package just declared.
-  // ChatView owns ordered Tool placement but delegates each whole root call
-  // to ui-tool, which owns root/subcall composition and atomic dispatch.
+  // ChatView owns only the stable ordered Node list. Business renderers are
+  // independently keyed behind its one Node seat.
   slots.register({
     name: 'conversation.view',
     id: 'chat',
@@ -305,9 +327,7 @@ export function apply(ctx: Context): void {
     label: () => t('view.chat'),
     locale: NS,
     children: {
-      'conversation.chat.tool': { kind: 'single', scope: 'session' },
-      'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
-      'conversation.chat.turnTail': { kind: 'chain', scope: 'session' },
+      'conversation.chat.node': { kind: 'keyed', scope: 'session', inject: CHAT_NODE_INJECT },
     },
     store: chatStore,
     inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index d8883be4cd..6dd9f09b4d 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -11,12 +11,9 @@
 
 import { memo, useMemo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
-import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps, ChatViewInjected, TurnTailOwnerProps } from '../contract/slots.ts'
-import { hasContentText } from './chat-flow.ts'
-import { MessageIconActions } from './MessageIconActions.tsx'
+import type { ChatViewSlotProps } from '../contract/slots.ts'
 import { ReasoningRow } from './ReasoningRow.tsx'
 import css from './AssistantMarkdown.module.css'
 
@@ -25,61 +22,19 @@ export interface AssistantMarkdownProps {
   streaming: boolean
   /** Frozen partial of an aborted turn: rendered with a stopped marker. */
   interrupted?: boolean | undefined
-  /** Unix epoch ms for the IconActions clock; omitted while streaming or when
-   *  the parent withholds chrome (mid-turn content assistants and every node
-   *  of a turn that has not ended). */
-  time?: number | undefined
-  /** Turn wall time in ms for the IconActions run-time label; omitted when the
-   *  turn's triggering input is outside the loaded window. */
-  runMs?: number | undefined
-  /** Turn first-step TTFT in ms for the IconActions label; omitted when unrecorded. */
-  ttftMs?: number | undefined
-  /** Turn decode throughput for the IconActions label; omitted when unrecorded. */
-  tokensPerSecond?: number | undefined
-  /** Event sequence used as the fork boundary; omitted while streaming. */
-  seq?: number | undefined
-  /** Fork the session through this finalized message's completed turn when eligible. */
-  onFork?: ((seq: number) => void) | undefined
-  /** Turn-tail slot dispatch share and owner currency; omitted for a mid-turn assistant. */
-  turnTail?: (Pick<PropsRenderSlots<'conversation.chat.turnTail'>, 'renderSlotChain'> & { owner: TurnTailOwnerProps }) | undefined
-  /** Prose file-mention factory (the injected face); omitted wherever `turnTail` is. */
-  fileMentions?: ChatViewInjected['fileMentions'] | undefined
-  /** The message is not the transcript tail of a completed turn. */
-  forkUnavailable?: boolean | undefined
+  /** Resolved prose file mentions for this Assistant's closing turn. */
+  mentions?: MarkdownFileMentions | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
   t: ChatViewSlotProps['t']
 }
 
-/** Joined text blocks for the copy action (reasoning / tool heads stay out). */
-function copyText(blocks: readonly AssistantBlock[]): string {
-  const parts: string[] = []
-  for (const block of blocks) {
-    if (block.kind === 'text') parts.push(block.text)
-  }
-  return parts.join('')
-}
-
 /** Reasoning block as the Think variant summary row (figma 39:28304). */
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail,
-  fileMentions, t,
+  blocks, streaming, interrupted, mentions, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
   const codeLabels = useMemo(() => ({ copyLabel: t('copy'), copiedLabel: t('copied') }), [t])
-  // Mention vocabulary for the closing prose. Keyed on the anchor seq, not the
-  // growing transcript: a settled turn's produced files are final, and a
-  // fresh identity per append would discard MarkdownText's cached parse for
-  // every settled closing message on every stream chunk. The window-prepend
-  // edge (a mid-turn window start later gaining earlier same-turn writes)
-  // leaves a mention unlinked until remount — never a wrong link.
-  const owner = turnTail?.owner
-  const mentions: MarkdownFileMentions | undefined = useMemo(
-    () => (owner === undefined ? undefined : fileMentions?.(owner)),
-    // Deliberately not `owner`: its identity changes per append while the
-    // seq-addressed vocabulary it yields does not.
-    [fileMentions, owner?.seq],
-  )
   const last = blocks.length - 1
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
   // a node that is only those heads (or empty) would paint an empty root
@@ -88,10 +43,8 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
     || interrupted === true
     || blocks.some(block => block.kind !== 'tool-call')
   if (!hasVisible) return null
-  // Footer only under settled content text; Think-only / streaming omit it.
-  const showActions = !streaming && time !== undefined && hasContentText(blocks)
   return (
-    <div className={css.root} data-streaming={streaming || undefined} data-time-hover-root>
+    <div className={css.root} data-streaming={streaming || undefined}>
       <div className={css.body}>
         {blocks.map((block, i) => {
           switch (block.kind) {
@@ -119,21 +72,6 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         })}
         {interrupted && <span className={css.stopped}>{t('message.stopped')}</span>}
       </div>
-      {showActions && turnTail?.renderSlotChain('conversation.chat.turnTail', turnTail.owner)}
-      {showActions && (
-        <MessageIconActions
-          text={copyText(blocks)}
-          time={time}
-          runMs={runMs}
-          ttftMs={ttftMs}
-          tokensPerSecond={tokensPerSecond}
-          clock="end"
-          onBranch={onFork === undefined || seq === undefined ? undefined : () => { onFork(seq) }}
-          branchUnavailable={forkUnavailable}
-          className={css.actions}
-          t={t}
-        />
-      )}
     </div>
   )
 })
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx b/packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx
new file mode 100644
index 0000000000..d0f8b33e6f
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx
@@ -0,0 +1,32 @@
+import { memo, useMemo } from 'react'
+import type { ChatNodeViewProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import { AssistantMarkdown } from './AssistantMarkdown.tsx'
+
+/** Streaming, settled, and interrupted Assistant states share one keyed renderer instance. */
+export const AssistantNodeView = memo(function AssistantNodeView({
+  node, useTurnData, openFile, fileMentions, t,
+}: ChatNodeViewProps<'assistant-step'>) {
+  const data = node.data
+  const turn = node.location.kind === 'turn' || node.location.kind === 'step'
+    ? node.location.turn
+    : undefined
+  const tail = useTurnData('turn-tail')
+  const owner = useMemo<TurnTailOwnerProps | undefined>(() => {
+    if (turn?.status !== 'closed' || data.finalNode === undefined) return undefined
+    if (tail?.closing?.finalNode.seq !== data.finalNode.seq) return undefined
+    return { turn, seq: data.finalNode.seq, openFile }
+  }, [data.finalNode, openFile, tail, turn])
+  const mentions = useMemo(
+    () => owner === undefined ? undefined : fileMentions(owner),
+    [fileMentions, owner],
+  )
+  return (
+    <AssistantMarkdown
+      blocks={data.blocks}
+      streaming={data.status === 'running'}
+      interrupted={data.status === 'interrupted'}
+      mentions={mentions}
+      t={t}
+    />
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx
new file mode 100644
index 0000000000..1f7a2f7451
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx
@@ -0,0 +1,60 @@
+import { memo, useMemo } from 'react'
+import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatNode } from '../contract/chat-nodes.ts'
+import css from './ChatView.module.css'
+
+interface ChatNodeSeatProps extends ChatNodeOwnerProps {
+  readonly nodeKey: string
+  readonly useSession: ChatViewSlotProps['useSession']
+  readonly renderSlot: ChatViewSlotProps['renderSlot']
+  readonly t: ChatViewSlotProps['t']
+}
+
+type RoutedChatNodeOwner = {
+  [Kind in ChatNode['kind']]: ChatNodeOwnerProps & { readonly node: ChatNode<Kind> }
+}[ChatNode['kind']]
+
+/** Subscribe and dispatch one stable Context key without observing sibling Nodes. */
+export const ChatNodeSeat = memo(function ChatNodeSeat({
+  nodeKey, selectedCallId, cwd, openFile, inspectCall, forkAt,
+  fileMentions, useSession, renderSlot, t,
+}: ChatNodeSeatProps) {
+  const node = useSession(snapshot => snapshot.chat.nodes.get(nodeKey))
+  const routedNode = node as ChatNode | undefined
+  const owner = useMemo<ChatNodeOwnerProps | null>(() => node === undefined
+    ? null
+    : {
+      selectedCallId,
+      cwd,
+      openFile,
+      inspectCall,
+      forkAt,
+      fileMentions,
+    }, [node, selectedCallId, cwd, openFile, inspectCall, forkAt, fileMentions])
+  if (routedNode === undefined || owner === null) return null
+  // Runtime dispatch owns the correlation: every Node's discriminant is the
+  // keyed-slot entry passed alongside that same Node. TypeScript does not
+  // distribute an object containing a union into a union of objects itself.
+  const routedOwner = { ...owner, node: routedNode } as RoutedChatNodeOwner
+  return (
+    <div
+      className={css.flowItem}
+      data-chat-anchor-key={routedNode.key}
+      data-chat-flow-key={routedNode.key}
+      data-chat-flow-kind={routedNode.kind}
+    >
+      {renderSlot('conversation.chat.node', routedOwner, {
+        entryKey: routedNode.kind,
+        hookContext: nodeKey,
+        fallback: (
+          <JsonBlock
+            label={t('message.unknownSurface', { type: routedNode.kind })}
+            payload={routedNode.data}
+            truncatedLabel={total => t('json.truncated', { total })}
+          />
+        ),
+      })}
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
index c600b3b0aa..d16608c856 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
@@ -1,6 +1,5 @@
-/* Chat flow: one 16px rhythm everywhere — between blocks (prose <-> tool
-   runs) via the column gap and between consecutive tool rows via the group
-   gap. Input padding cap rides the skeleton. Under
+/* Chat flow: one 16px rhythm everywhere through the column gap. Input
+   padding cap rides the skeleton. Under
    `[data-conversation-scroll]` the column host owns overflow and this view
    is ordinary flow (see ConversationRoot active-phase rules). */
 
@@ -51,10 +50,11 @@
   min-width: 0;
 }
 
-.toolGroup {
-  display: flex;
-  flex-direction: column;
-  gap: 16px;
+/* A keyed renderer may intentionally decline its row after dispatch (the
+   completed-turn tail does this when it owns neither actions nor extensions).
+   An empty flex item must not consume the column gap. */
+.flowItem:empty {
+  display: none;
 }
 
 .callRow {
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 3636a2a971..44ae6f345a 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -1,41 +1,24 @@
-// ChatView: the default conversation view — message flow with user bubbles,
-// assistant narration, tool summary rows grouped into step runs, pending
-// cards, paging, and bottom-follow. Session stats live on
-// 'conversation.composer.dock' (sticky with the composer). Pure component
-// registered directly; its registration declares the whole-Tool
-// 'conversation.chat.tool' seat. ui-tool owns root/subcall composition and
-// keyed per-tool dispatch behind that boundary.
+// ChatView: the default conversation view — one stable keyed parent list over
+// final business Nodes, plus paging, pending steering and bottom-follow.
+// Each row dispatches through 'conversation.chat.node'; ui-tool owns the
+// tool-call renderer and its recursive root/subcall composition.
 //
 // Scroll: when nested under `[data-conversation-scroll]` (active conversation
 // column), that host is the scrollport and this view is flow content; when
 // mounted alone (unit tests), `.scroll` owns overflow. Bottom-follow and
 // prepend anchoring always target the resolved scrollport.
 //
-// Render economics (architecture RFC performance model): the list parent
-// subscribes to snapshot segments that do NOT change per streaming chunk
-// (nodes/runningCalls/pending keep their references across chunk batches), so
-// during a token storm only StreamingTail re-renders; history rows hold via
-// memo on cache-stable node slices. Selection changes re-render the parent
-// map but only rows whose own selected bit flipped. renderSlot is
-// entry-identity-stable (framework binding cache), so passing it through
-// memoized rows never churns them.
+// Render economics: order changes only when rows enter, leave or move. Each
+// ChatNodeSeat subscribes to one Node key, so Assistant deltas and Tool
+// lifecycle updates replace only their own row without remounting it.
 
-import {
-  memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
-} from 'react'
-import type {
-  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode,
-} from '@deepseek-ai/dsh-client-runtime/client'
-import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import type { ConversationTimelineSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, runningTurnStartTime, type ChatFlowItem } from './chat-flow.ts'
-import { AssistantMarkdown } from './AssistantMarkdown.tsx'
-import { CompactionCommandCard } from './CompactionCommandCard.tsx'
-import { GenericCommandCard } from './GenericCommandCard.tsx'
-import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
+import { PendingSteeringBubble } from './MessageItem.tsx'
+import { ChatNodeSeat } from './ChatNodeSeat.tsx'
 import { formatRunDuration } from './message-chrome.ts'
-import { deriveTurnMetrics } from './turn-metrics.ts'
 import css from './ChatView.module.css'
 
 const FOLLOW_THRESHOLD = 24
@@ -98,35 +81,8 @@ function pagingAnchor(list: HTMLElement, scrollport: HTMLElement): HTMLElement |
   return visibleRows[0] ?? rows[0] ?? null
 }
 
-type OpenFile = (path: string) => void
-
-type InspectCall = (callId: string) => void
-
-/** Declared child-slot render share (stable framework binding). */
-type RenderChatSlot = ChatViewSlotProps['renderSlot']
-
 type ChatScrollPosition = NonNullable<ReturnType<ChatViewSlotProps['chatScroll']['read']>>
 
-/** ui-slots' UseSession is deliberately wide (dependency direction); the
- *  chat view narrows once to the runtime snapshot the binding actually feeds. */
-type UseConversation = SnapshotSelectorHook<ConversationSnapshot>
-
-function treeContainsCall(block: ToolCallBlock, callId: string | undefined): boolean {
-  return callId !== undefined
-    && (block.callId === callId || block.subCalls.some(child => treeContainsCall(child, callId)))
-}
-
-function activeRetrySeq(nodes: readonly ConversationNode[], running: boolean): number | null {
-  if (!running) return null
-  for (let index = nodes.length - 1; index >= 0; index -= 1) {
-    const node = nodes[index]
-    if (node === undefined) continue
-    if (node.kind === 'model-retry') return node.retryState === 'cancelled' ? null : node.seq
-    if (node.kind === 'assistant' || node.kind === 'user') return null
-  }
-  return null
-}
-
 /** Capture a reflow-resistant reader position from the current rendered window. */
 function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollPosition | null {
   const row = pagingAnchor(list, scrollport)
@@ -139,77 +95,13 @@ function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollP
   }
 }
 
-/** One ordered root Tool call handed intact to the Tool presentation plugin. */
-const ToolSeat = memo(function ToolSeat({
-  renderSlot, callId, toolName, block, openFile, selectedCallId, cwd, inspectCall,
-}: {
-  renderSlot: RenderChatSlot
-  callId: string
-  toolName: string
-  block: ToolResultNode | RunningToolCall
-  openFile: OpenFile
-  selectedCallId?: string | undefined
-  cwd: string | undefined
-  inspectCall: InspectCall
-}) {
-  const owner = useMemo(() => ({
-    callId, toolName, block, selectedCallId, cwd, openFile, inspectCall,
-  }), [callId, toolName, block, selectedCallId, cwd, openFile, inspectCall])
-  return renderSlot('conversation.chat.tool', owner)
-})
-
-/** Consecutive tool results as one step-run group (uniform 16px rhythm). */
-const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selectedCallId, cwd, inspectCall }: {
-  renderSlot: RenderChatSlot
-  results: readonly ToolResultNode[]
-  openFile: OpenFile
-  /** Tool ownership resolves whether the selection is this root or one of its children. */
-  selectedCallId: string | undefined
-  /** Session workspace root for path-relative summaries. */
-  cwd: string | undefined
-  inspectCall: InspectCall
-}) {
-  return (
-    <div className={css.toolGroup}>
-      {results.map(node => (
-        <ToolSeat
-          key={node.callId}
-          renderSlot={renderSlot}
-          callId={node.callId}
-          toolName={node.call?.name ?? ''}
-          block={node}
-          openFile={openFile}
-          selectedCallId={treeContainsCall(node, selectedCallId) ? selectedCallId : undefined}
-          cwd={cwd}
-          inspectCall={inspectCall}
-        />
-      ))}
-    </div>
-  )
-})
-
-/** One command lifecycle row: keyed dispatch on the command name with the
- *  generic card as the render-site fallback (zero registration required). A
- *  run-less cross-window node has no name and always lands on the fallback. */
-const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }: {
-  renderSlot: RenderChatSlot
-  node: CommandNode
-  compaction?: Extract<ConversationNode, { kind: 'compaction' }>
-  t: ChatViewSlotProps['t']
-}) {
-  const owner = useMemo(() => ({ node, ...compaction === undefined ? {} : { compaction } }), [compaction, node])
-  const fallback = node.name === 'compact'
-    ? <CompactionCommandCard {...owner} t={t} />
-    : <GenericCommandCard {...owner} t={t} />
-  return (
-    <div className={css.callRow}>
-      {renderSlot('conversation.chat.commandview', owner, {
-        entryKey: node.name ?? '',
-        fallback,
-      })}
-    </div>
-  )
-})
+function runningTurnStartTime(timeline: ConversationTimelineSnapshot): number | null {
+  let latest: number | null = null
+  for (const turn of timeline.turns.values()) {
+    if (turn.status === 'open' && turn.start !== undefined) latest = turn.start.time
+  }
+  return latest
+}
 
 /** Turn-level model activity label retained across first-token, tool, and streaming phases. */
 function TurnStatus({ startTime, t }: {
@@ -247,52 +139,32 @@ function TurnStatus({ startTime, t }: {
   )
 }
 
-/** The streaming partial, isolated so chunk batches re-render only this tail;
- *  the column ResizeObserver owns bottom-follow when its box grows. */
-function StreamingTail({ useSession, t }: {
-  useSession: UseConversation
-  t: ChatViewSlotProps['t']
-}) {
-  const partial = useSession(s => s.partial)
-  if (partial === null) return null
-  return <AssistantMarkdown blocks={partial.blocks} streaming t={t} />
-}
-
 /**
  * The chat view slot entry: pure component over the composed props; each
- * ordered root Tool call crosses the declared whole-Tool render seat.
+ * ordered business Node crosses the keyed renderer seat.
  */
 export function ChatView({
-  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt,
+  useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt,
   fileMentions, t,
 }: ChatViewSlotProps) {
-  const nodes = useSession(s => s.nodes)
-  const turnTimings = useSession(s => s.turnTimings)
-  const turnEnds = useSession(s => s.turnEnds)
+  const order = useSession(s => s.chat.order)
+  const nodeStore = useSession(s => s.chat.nodes)
+  const timeline = useSession(s => s.chat.timeline)
   const inbox = useSession(s => s.queue)
   // Workspace root off the session list row: path summaries display relative to it.
   const cwd = useSessions(s => s.byId[sessionId]?.cwd)
   const running = useSession(s => s.running)
-  const runningCalls = useSession(s => s.runningCalls)
   const openState = useSession(s => s.openState)
   const openError = useSession(s => s.openError)
   const hasMore = useSession(s => s.hasMore)
   const loadingOlder = useSession(s => s.loadingOlder)
   const selectedCallId = useStore(s => s.selection?.callId)
 
-  const items = useMemo(() => deriveChatFlow(nodes), [nodes])
   const pendingSteering = useMemo(
     () => inbox.filter(item => item.placement === 'steering'),
     [inbox],
   )
-  const activeRetry = useMemo(() => activeRetrySeq(nodes, running), [nodes, running])
-  // Only the last content assistant of each completed turn owns IconActions;
-  // mid-turn text and every node of a running turn omit `time`, so
-  // AssistantMarkdown stays chrome-free until the answer settles.
-  const actionSeqs = useMemo(() => assistantActionsSeqs(nodes, turnEnds), [nodes, turnEnds])
-  const branchSeqs = useMemo(() => assistantBranchSeqs(nodes, turnEnds), [nodes, turnEnds])
-  const runningTurnStart = useMemo(() => runningTurnStartTime(turnTimings), [turnTimings])
-  const turnMetrics = useMemo(() => deriveTurnMetrics(nodes), [nodes])
+  const runningTurnStart = useMemo(() => runningTurnStartTime(timeline), [timeline])
 
   const listRef = useRef<HTMLDivElement | null>(null)
   const columnRef = useRef<HTMLDivElement | null>(null)
@@ -312,11 +184,12 @@ export function ChatView({
    *  scrolls the rest of the way to the floor). */
   const followSigRef = useRef<string | null>(null)
 
-  const firstSeq = nodes[0]?.seq ?? null
-  const lastItem = items[items.length - 1]
-  const lastKey = lastItem?.key ?? null
+  const firstKey = order[0]
+  const firstSeq = firstKey === undefined ? null : nodeStore.get(firstKey)?.anchorSeq ?? null
+  const lastKey = order.at(-1) ?? null
+  const lastNode = lastKey === null ? undefined : nodeStore.get(lastKey)
   const lastSteeringId = pendingSteering[pendingSteering.length - 1]?.id ?? null
-  const followSig = `${openState}:${firstSeq}:${lastKey}:${nodes.length}:${running ? 1 : 0}:${runningCalls.length}:${lastSteeringId ?? ''}`
+  const followSig = `${openState}:${firstSeq}:${lastKey}:${order.length}:${running ? 1 : 0}:${lastSteeringId ?? ''}`
 
   const toBottom = (el: HTMLElement): void => {
     anchorRef.current = null
@@ -377,8 +250,7 @@ export function ChatView({
     firstSeqRef.current = firstSeq
     // Own words must be visible: a new trailing user node force-scrolls
     // (send lives in the composer, so arrival is detected here, not armed there).
-    const appendedUser = lastKey !== lastKeyRef.current
-      && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
+    const appendedUser = lastKey !== lastKeyRef.current && lastNode?.kind === 'user'
     const appendedSteering = lastSteeringId !== null && lastSteeringId !== lastSteeringIdRef.current
     const tipMoved = followSigRef.current !== followSig
     lastKeyRef.current = lastKey
@@ -490,71 +362,6 @@ export function ChatView({
     loadOlder()
   }
 
-  const renderItem = (item: ChatFlowItem): ReactNode => {
-    if (item.kind === 'tool-group') {
-      return (
-        <ToolGroup
-          renderSlot={renderSlot}
-          results={item.results}
-          openFile={openFile}
-          selectedCallId={selectedCallId}
-          cwd={cwd}
-          inspectCall={inspectCall}
-        />
-      )
-    }
-    if (item.kind === 'command-compaction') {
-      return (
-        <CommandRow
-          renderSlot={renderSlot}
-          node={item.command}
-          compaction={item.compaction}
-          t={t}
-        />
-      )
-    }
-    const node: ConversationNode = item.node
-    if (node.kind === 'assistant') {
-      const timing = actionSeqs.has(node.seq) ? turnTimings.get(node.turn) : undefined
-      // Metrics gate on the settled in-window timing: turn/start loaded means
-      // every step of the turn is loaded, so first-step TTFT is genuine.
-      const metrics = timing?.endTime === undefined ? undefined : turnMetrics.get(node.turn)
-      return (
-        <AssistantMarkdown
-          blocks={node.blocks}
-          streaming={false}
-          interrupted={node.interrupted}
-          time={actionSeqs.has(node.seq) ? node.time : undefined}
-          runMs={timing?.endTime === undefined
-            ? undefined
-            : Math.max(0, timing.endTime - timing.startTime)}
-          ttftMs={metrics?.ttftMs}
-          tokensPerSecond={metrics?.tokensPerSecond}
-          seq={node.seq}
-          onFork={forkAt}
-          forkUnavailable={!branchSeqs.has(node.seq)}
-          turnTail={actionSeqs.has(node.seq)
-            ? { renderSlotChain, owner: { nodes, seq: node.seq, openFile } }
-            : undefined}
-          fileMentions={actionSeqs.has(node.seq) ? fileMentions : undefined}
-          t={t}
-        />
-      )
-    }
-    if (node.kind === 'command') {
-      return <CommandRow renderSlot={renderSlot} node={node} t={t} />
-    }
-    /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
-    if (node.kind === 'tool-result') return null
-    return (
-      <MessageItem
-        node={node}
-        retryActive={node.kind === 'model-retry' && node.seq === activeRetry}
-        t={t}
-      />
-    )
-  }
-
   return (
     <div className={css.root}>
       <div ref={listRef} className={css.scroll}>
@@ -572,43 +379,21 @@ export function ChatView({
               </button>
             </div>
           )}
-          {items.map(item => (
-            <div
-              key={item.key}
-              className={css.flowItem}
-              data-chat-anchor-key={item.kind === 'node'
-                ? `node:${String(item.node.seq)}`
-                : item.kind === 'command-compaction'
-                  ? `node:${String(item.compaction.seq)}`
-                  : undefined}
-              data-chat-flow-key={item.key}
-              data-chat-flow-kind={item.kind === 'node'
-                ? item.node.kind
-                : item.kind === 'command-compaction'
-                  ? item.kind
-                  : 'tool-group'}
-            >
-              {renderItem(item)}
-            </div>
+          {order.map(nodeKey => (
+            <ChatNodeSeat
+              key={nodeKey}
+              nodeKey={nodeKey}
+              useSession={useSession}
+              selectedCallId={selectedCallId}
+              cwd={cwd}
+              openFile={openFile}
+              inspectCall={inspectCall}
+              forkAt={forkAt}
+              fileMentions={fileMentions}
+              renderSlot={renderSlot}
+              t={t}
+            />
           ))}
-          <StreamingTail useSession={useSession} t={t} />
-          {runningCalls.length > 0 && (
-            <div className={css.toolGroup}>
-              {runningCalls.map(call => (
-                <ToolSeat
-                  key={call.callId}
-                  renderSlot={renderSlot}
-                  callId={call.callId}
-                  toolName={call.name}
-                  block={call}
-                  openFile={openFile}
-                  selectedCallId={treeContainsCall(call, selectedCallId) ? selectedCallId : undefined}
-                  cwd={cwd}
-                  inspectCall={inspectCall}
-                />
-              ))}
-            </div>
-          )}
           {/* No pending placeholders: questions (ui-question) and approvals
               (ApprovalPanel) both take over the composer, so a flow card would
               double-render the same wait. */}
diff --git a/packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx b/packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx
new file mode 100644
index 0000000000..a1fc9f197a
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx
@@ -0,0 +1,40 @@
+import { memo, useMemo } from 'react'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import type {
+  ChatNodeViewProps, CommandRowOwnerProps,
+} from '../contract/slots.ts'
+import { CompactionCommandCard } from './CompactionCommandCard.tsx'
+import { GenericCommandCard } from './GenericCommandCard.tsx'
+import css from './ChatView.module.css'
+
+type CommandNodeViewProps = ChatNodeViewProps<'command'> & PropsRenderSlots<'conversation.chat.commandview'>
+
+/** Ordinary command lifecycle renderer with command-name keyed specialization. */
+export const CommandNodeView = memo(function CommandNodeView({ node, renderSlot, t }: CommandNodeViewProps) {
+  const command = node.data
+  const owner = useMemo<CommandRowOwnerProps>(() => ({ node: command }), [command])
+  return (
+    <div className={css.callRow}>
+      {renderSlot('conversation.chat.commandview', owner, {
+        entryKey: command.name ?? '',
+        fallback: <GenericCommandCard {...owner} t={t} />,
+      })}
+    </div>
+  )
+})
+
+/** One integrated `/compact` command and compaction transaction renderer. */
+export const ManualCompactionNodeView = memo(function ManualCompactionNodeView({
+  node, t,
+}: ChatNodeViewProps<'manual-compaction'>) {
+  const data = node.data
+  return (
+    <div className={css.callRow}>
+      <CompactionCommandCard
+        node={data.command}
+        {...data.compaction === null ? {} : { compaction: data.compaction }}
+        t={t}
+      />
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 30b51b3870..972fba8710 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -7,30 +7,15 @@
 import { memo, useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
-  CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SteeringMessageNode,
-  TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  ModelRetryNode, TurnErrorNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { JsonBlock, MessageText, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatNodeViewProps, ChatViewSlotProps } from '../contract/slots.ts'
 import { CompactionItem } from './CompactionItem.tsx'
 import { ContextInjectionRow } from './ContextInjectionRow.tsx'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import css from './MessageItem.module.css'
 
-export interface MessageItemProps {
-  node:
-    | UserMessageNode
-    | SteeringMessageNode
-    | ContextMessageNode
-    | CompactionSummaryNode
-    | ModelRetryNode
-    | TurnErrorNode
-    | UnknownSurfaceNode
-  retryActive?: boolean
-  /** The owning view's locale seat, passed down as a plain prop. */
-  t: ChatViewSlotProps['t']
-}
-
 function contentText(content: readonly unknown[]): { text: string; rest: unknown[] } {
   const texts: string[] = []
   const rest: unknown[] = []
@@ -219,50 +204,69 @@ export function PendingSteeringBubble({ content, t }: {
   )
 }
 
-export const MessageItem = memo(function MessageItem({
-  node, retryActive = false, t,
-}: MessageItemProps) {
-  const truncated = (total: number): string => t('json.truncated', { total })
-  switch (node.kind) {
-    case 'user':
-    case 'steering':
-      return (
-        <UserStyleBubble
-          content={node.content}
-          steering={node.kind === 'steering'}
-          t={t}
-          actions={text => (
-            <MessageIconActions
-              text={text}
-              time={node.time}
-              clock="start"
-              className={css.actions}
-              t={t}
-            />
-          )}
-        />
-      )
-    case 'context':
-      return (
-        <ContextInjectionRow
-          content={node.content}
-          source={node.source}
-          provenance={node.provenance}
-          form={node.form}
+/** User and admitted-steering keyed Chat renderer. */
+export const UserMessageNodeView = memo(function UserMessageNodeView({
+  node, t,
+}: ChatNodeViewProps<'user' | 'steering'>) {
+  const data = node.data
+  return (
+    <UserStyleBubble
+      content={data.content}
+      steering={data.kind === 'steering'}
+      t={t}
+      actions={text => (
+        <MessageIconActions
+          text={text}
+          time={data.time}
+          clock="start"
+          className={css.actions}
           t={t}
         />
-      )
-    case 'compaction':
-      return <CompactionItem node={node} t={t} />
-    case 'model-retry':
-      return <ModelRetryItem node={node} active={retryActive} t={t} />
-    case 'turn-error':
-      return <TurnErrorItem node={node} t={t} />
-    default:
-      return (
-        <div className={css.contextRow}>
-          <JsonBlock label={t('message.unknownSurface', { type: node.type })} payload={node.data} truncatedLabel={truncated} />
-        </div>
-      )
-  }
+      )}
+    />
+  )
+})
+
+/** Injected-context keyed Chat renderer. */
+export const ContextMessageNodeView = memo(function ContextMessageNodeView({ node, t }: ChatNodeViewProps<'context'>) {
+  const data = node.data
+  return (
+    <ContextInjectionRow
+      content={data.content}
+      source={data.source}
+      provenance={data.provenance}
+      form={data.form}
+      t={t}
+    />
+  )
+})
+
+/** Automatic compaction keyed Chat renderer. */
+export const CompactionNodeView = memo(function CompactionNodeView({ node, t }: ChatNodeViewProps<'compaction'>) {
+  return <CompactionItem node={node.data} t={t} />
+})
+
+/** Correlated retry-chain keyed Chat renderer. */
+export const RetryNodeView = memo(function RetryNodeView({ node, t }: ChatNodeViewProps<'model-retry'>) {
+  const data = node.data
+  return <ModelRetryItem node={data.current} active={data.current.retryState === 'scheduled'} t={t} />
+})
+
+/** Terminal turn-error keyed Chat renderer. */
+export const TurnErrorNodeView = memo(function TurnErrorNodeView({ node, t }: ChatNodeViewProps<'turn-error'>) {
+  return <TurnErrorItem node={node.data} t={t} />
+})
+
+/** Explicit unknown-surface keyed Chat renderer. */
+export const UnknownNodeView = memo(function UnknownNodeView({ node, t }: ChatNodeViewProps<'unknown'>) {
+  const data = node.data
+  return (
+    <div className={css.contextRow}>
+      <JsonBlock
+        label={t('message.unknownSurface', { type: data.type })}
+        payload={data.data}
+        truncatedLabel={total => t('json.truncated', { total })}
+      />
+    </div>
+  )
 })
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
index 8e672740cf..8e43f3c0b4 100644
--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -157,9 +157,9 @@ export interface StatsLineProps {
 }
 
 export const StatsLine = memo(function StatsLine({ useSession, useProjection, t }: StatsLineProps) {
-  const nodes = useSession(s => s.nodes)
+  const settledNodes = useSession(s => s.chat.legacy.nodes)
+  const stats = useMemo(() => deriveStats(settledNodes), [settledNodes])
   const usage = useProjection('tokenUsage')
-  const stats = useMemo(() => deriveStats(nodes), [nodes])
   // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
   const groups: string[] = []
   if (stats.steps > 0) {
diff --git a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css
new file mode 100644
index 0000000000..831e6e212b
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css
@@ -0,0 +1,9 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.actions {
+  margin-left: -6px;
+}
diff --git a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
new file mode 100644
index 0000000000..bf48fc75c6
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
@@ -0,0 +1,43 @@
+import { memo } from 'react'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ChatNodeViewProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import { MessageIconActions } from './MessageIconActions.tsx'
+import { assistantText } from './turn-assistant.ts'
+import css from './TurnTailNodeView.module.css'
+
+type TurnTailNodeViewProps = ChatNodeViewProps<'turn-tail'> & PropsRenderSlots<'conversation.chat.turnTail'>
+
+/** Turn-local actions and feature tail over the Location index, independent of Assistant placement. */
+export const TurnTailNodeView = memo(function TurnTailNodeView({
+  node, openFile, forkAt, renderSlotChain, t,
+}: TurnTailNodeViewProps) {
+  const data = node.data
+  const turn = node.location.kind === 'turn' || node.location.kind === 'step'
+    ? node.location.turn
+    : undefined
+  if (turn === undefined) return null
+  const closing = data.closing
+  const owner: TurnTailOwnerProps = { turn, seq: closing?.finalNode.seq ?? data.seq, openFile }
+  const tail = renderSlotChain('conversation.chat.turnTail', owner)
+  if (closing === null) return tail === null ? null : <div className={css.root}>{tail}</div>
+  const runMs = turn.start === undefined || turn.end === undefined
+    ? undefined
+    : Math.max(0, turn.end.time - turn.start.time)
+  return (
+    <div className={css.root} data-turn-tail={data.turn} data-time-hover-root>
+      {tail}
+      <MessageIconActions
+        text={assistantText(closing.blocks)}
+        time={closing.time}
+        runMs={runMs}
+        ttftMs={data.ttftMs}
+        tokensPerSecond={data.tokensPerSecond}
+        clock="end"
+        onBranch={() => { forkAt(closing.finalNode.seq) }}
+        branchUnavailable={data.branchUnavailable}
+        className={css.actions}
+        t={t}
+      />
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
deleted file mode 100644
index a9b12cbe2d..0000000000
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ /dev/null
@@ -1,214 +0,0 @@
-/**
- * Chat flow derivation: ConversationSnapshot nodes -> render items. Tool
- * results group into consecutive-run tool groups (figma step-summary flow,
- * VERTICAL gap10) alternating with narration. Consecutive retry notices
- * reuse the first notice's row while projecting the latest retry turn.
- * Item identity keys are stable across snapshots so the list parent can
- * subscribe to keys only while rows subscribe to content. IconActions ownership
- * and completed-turn branch points are derived here too so ChatView and the
- * flow share their gates.
- */
-import type {
-  AssistantBlock, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ToolResultNode,
-} from '@deepseek-ai/dsh-client-runtime/client'
-
-/** One renderable flow item; key is the React key and the parent's identity unit. */
-export type ChatFlowItem =
-  | { kind: 'node'; key: string; node: ConversationNode }
-  | { kind: 'tool-group'; key: string; results: readonly ToolResultNode[] }
-  | {
-    kind: 'command-compaction'
-    key: string
-    command: CommandNode
-    compaction: CompactionSummaryNode
-  }
-
-/** Match explicit command outcome references to exactly one compaction checkpoint. */
-function commandCompactionPairs(nodes: readonly ConversationNode[]): {
-  readonly byCommandId: ReadonlyMap<string, CompactionSummaryNode>
-  readonly byCompactionSeq: ReadonlyMap<number, CommandNode>
-} {
-  const commandsBySource = new Map<number, CommandNode | null>()
-  for (const node of nodes) {
-    if (node.kind !== 'command' || node.name !== 'compact' || node.outcome?.kind !== 'success') continue
-    const source = node.outcome.sourceEventSeq
-    if (source === undefined) continue
-    commandsBySource.set(source, commandsBySource.has(source) ? null : node)
-  }
-  const compactionsBySummary = new Map<number, CompactionSummaryNode | null>()
-  for (const node of nodes) {
-    if (node.kind !== 'compaction' || node.summaryEventSeq === null) continue
-    const summary = node.summaryEventSeq
-    compactionsBySummary.set(summary, compactionsBySummary.has(summary) ? null : node)
-  }
-  const byCommandId = new Map<string, CompactionSummaryNode>()
-  const byCompactionSeq = new Map<number, CommandNode>()
-  for (const [source, command] of commandsBySource) {
-    const compaction = compactionsBySummary.get(source)
-    if (command === null || compaction === undefined || compaction === null) continue
-    byCommandId.set(command.commandId, compaction)
-    byCompactionSeq.set(compaction.seq, command)
-  }
-  return { byCommandId, byCompactionSeq }
-}
-
-/**
- * True when the node has model-visible text content worth IconActions chrome.
- * Shared with {@link AssistantMarkdown}'s mount gate so ownership and mounting
- * cannot diverge.
- * @param blocks - assistant blocks of one finalized node.
- * @returns Whether any text block carries non-blank content.
- */
-export function hasContentText(blocks: readonly AssistantBlock[]): boolean {
-  return blocks.some(block => block.kind === 'text' && block.text.trim() !== '')
-}
-
-/** An assistant node that renders nothing: only tool-call heads (rows render
- *  via the grouping pass) and blank text/reasoning. Skipped by the flow so it
- *  neither costs column gaps nor splits a tool-row run. Interrupted nodes
- *  always render (the 已停止 marker). */
-function rendersNothing(node: ConversationNode): boolean {
-  return node.kind === 'assistant' && node.interrupted !== true
-    && node.blocks.every(b => b.kind === 'tool-call'
-      || ((b.kind === 'text' || b.kind === 'reasoning') && b.text.trim() === ''))
-}
-
-/**
- * Seq set of assistants that own IconActions: the last content-text assistant
- * of each *completed* turn. A turn without a `turn/end` in the window is still
- * producing steps, so its latest narration is not the settled answer and owns
- * nothing; mid-turn narration of a completed turn stays chrome-free too.
- * @param nodes - snapshot nodes (surface order).
- * @param turnEnds - completed turn boundaries retained from the event window.
- * @returns Seq values ChatView may pass as `time` into AssistantMarkdown.
- */
-export function assistantActionsSeqs(
-  nodes: readonly ConversationNode[],
-  turnEnds: ReadonlyMap<number, number>,
-): ReadonlySet<number> {
-  const lastByTurn = new Map<number, number>()
-  for (const node of nodes) {
-    if (node.kind !== 'assistant' || !turnEnds.has(node.turn) || !hasContentText(node.blocks)) continue
-    lastByTurn.set(node.turn, node.seq)
-  }
-  return new Set(lastByTurn.values())
-}
-
-/**
- * Exact start time of the latest in-window turn without a matching end time.
- * @param turnTimings - In-window turn timings in event order.
- * @returns Unix epoch ms, or null when the running turn started outside the window.
- */
-export function runningTurnStartTime(
-  turnTimings: ConversationSnapshot['turnTimings'],
-): number | null {
-  let latest: number | null = null
-  for (const timing of turnTimings.values()) {
-    if (timing.endTime === undefined) latest = timing.startTime
-  }
-  return latest
-}
-
-/**
- * Seq set of assistant answers that may fork: the completed turn's transcript
- * tail, when that tail is the turn's own content-text assistant. A later tool,
- * reasoning, error, or other transcript node leaves the answer's branch action
- * unavailable because the Host would include the whole turn. User and steering
- * bubbles carry no branch action at all: a fork at their seq cuts at the same
- * `turn/end` as the answer's, so the affordance lives only under the settled
- * answer.
- * @param nodes - snapshot nodes in event order.
- * @param turnEnds - completed turn boundaries retained from the event window.
- * @returns Assistant seq values whose visible position matches the fork boundary.
- */
-export function assistantBranchSeqs(
-  nodes: readonly ConversationNode[],
-  turnEnds: ReadonlyMap<number, number>,
-): ReadonlySet<number> {
-  const result = new Set<number>()
-  const boundaries = [...turnEnds].sort((a, b) => a[1] - b[1])
-  let nodeIndex = 0
-  for (const [turn, endSeq] of boundaries) {
-    let tail: ConversationNode | undefined
-    while (nodeIndex < nodes.length) {
-      const candidate = nodes[nodeIndex]
-      if (candidate === undefined || candidate.seq > endSeq) break
-      tail = candidate
-      nodeIndex++
-    }
-    if (tail?.kind === 'assistant' && tail.turn === turn && hasContentText(tail.blocks)) {
-      result.add(tail.seq)
-    }
-  }
-  return result
-}
-
-/**
- * Group finalized nodes into the step-summary flow.
- * @param nodes - snapshot nodes in human-transcript and durable-notice order.
- * @returns flow items; consecutive tool results group and retry notices reuse their first key.
- */
-export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem[] {
-  const items: ChatFlowItem[] = []
-  const pairs = commandCompactionPairs(nodes)
-  let group: ToolResultNode[] | null = null
-  for (const node of nodes) {
-    if (rendersNothing(node)) continue
-    if (node.kind === 'command' && pairs.byCommandId.has(node.commandId)) {
-      continue
-    }
-    if (node.kind === 'compaction') {
-      group = null
-      const command = pairs.byCompactionSeq.get(node.seq)
-      if (command !== undefined) {
-        items.push({
-          kind: 'command-compaction',
-          key: `c${command.commandId}`,
-          command,
-          compaction: node,
-        })
-      } else {
-        items.push({ kind: 'node', key: `n${node.seq}`, node })
-      }
-      continue
-    }
-    if (node.kind === 'tool-result') {
-      if (group === null) {
-        group = [node]
-        items.push({ kind: 'tool-group', key: `g${node.seq}`, results: group })
-      } else {
-        group.push(node)
-      }
-    } else if (node.kind === 'model-retry') {
-      group = null
-      const previous = items[items.length - 1]
-      if (
-        previous?.kind === 'node'
-        && previous.node.kind === 'model-retry'
-      ) {
-        items[items.length - 1] = { ...previous, node }
-      } else {
-        items.push({ kind: 'node', key: `n${node.seq}`, node })
-      }
-    } else {
-      group = null
-      items.push({
-        kind: 'node',
-        key: node.kind === 'command' && node.name === 'compact'
-          ? `c${node.commandId}`
-          : `n${node.seq}`,
-        node,
-      })
-    }
-  }
-  return items
-}
-
-/**
- * Key projection for the list parent's selector (content-blind identity).
- * @param items - derived flow items.
- * @returns joined key string usable with Object.is short-circuiting.
- */
-export function flowKeys(items: readonly ChatFlowItem[]): string {
-  return items.map(i => i.key).join('|')
-}
diff --git a/packages/client/ui-conversation/src/client/chat/register-node-renderers.ts b/packages/client/ui-conversation/src/client/chat/register-node-renderers.ts
new file mode 100644
index 0000000000..8926fc2a8e
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/register-node-renderers.ts
@@ -0,0 +1,46 @@
+import type { Context } from 'cordis'
+import { NS } from '../locales.ts'
+import { AssistantNodeView } from './AssistantNodeView.tsx'
+import { CommandNodeView, ManualCompactionNodeView } from './CommandNodeView.tsx'
+import {
+  CompactionNodeView, ContextMessageNodeView, RetryNodeView, TurnErrorNodeView,
+  UnknownNodeView, UserMessageNodeView,
+} from './MessageItem.tsx'
+import { TurnTailNodeView } from './TurnTailNodeView.tsx'
+
+/**
+ * Register this package's business renderers behind the keyed Chat Node seat.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerChatNodeRenderers(ctx: Context): void {
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'user', locale: NS }, UserMessageNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'steering', locale: NS }, UserMessageNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'context', locale: NS }, ContextMessageNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'assistant-step', locale: NS }, AssistantNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'command',
+    locale: NS,
+    children: { 'conversation.chat.commandview': { kind: 'keyed', scope: 'session' } },
+  }, CommandNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'manual-compaction', locale: NS }, ManualCompactionNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'compaction', locale: NS }, CompactionNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'model-retry', locale: NS }, RetryNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'turn-error', locale: NS }, TurnErrorNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'turn-tail',
+    locale: NS,
+    children: { 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' } },
+  }, TurnTailNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'unknown', locale: NS }, UnknownNodeView))
+}
diff --git a/packages/client/ui-conversation/src/client/chat/tool-node-reader.ts b/packages/client/ui-conversation/src/client/chat/tool-node-reader.ts
new file mode 100644
index 0000000000..dca9992b8d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/tool-node-reader.ts
@@ -0,0 +1,46 @@
+import type {
+  ConversationSnapshot, ToolCallBlock,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { conversationContextKey } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNode } from '../contract/chat-nodes.ts'
+
+function toolNode(node: ReturnType<ConversationSnapshot['chat']['nodes']['get']>): ChatNode<'tool-call'> | undefined {
+  return node?.kind === 'tool-call' ? node as ChatNode<'tool-call'> : undefined
+}
+
+/**
+ * Read one root Tool lifecycle through the internal Chat Node index.
+ * @param snapshot - current Conversation snapshot.
+ * @param rootCallId - root call identity and Tool Context identity.
+ * @returns root lifecycle when it is materialized in the current window.
+ */
+export function rootToolCall(
+  snapshot: ConversationSnapshot,
+  rootCallId: string,
+): ToolCallBlock | undefined {
+  return toolNode(snapshot.chat.nodes.get(conversationContextKey('tool-call', rootCallId)))?.data.root
+}
+
+/**
+ * Find any root or nested Tool lifecycle through the internal Node store.
+ * @param snapshot - current Conversation snapshot.
+ * @param callId - root or nested call identity.
+ * @returns current Tool lifecycle when materialized in the loaded window.
+ */
+export function findToolCall(snapshot: ConversationSnapshot, callId: string): ToolCallBlock | undefined {
+  const visit = (block: ToolCallBlock): ToolCallBlock | undefined => {
+    if (block.callId === callId) return block
+    for (const child of block.subCalls) {
+      const found = visit(child)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  for (const node of snapshot.chat.nodes.values()) {
+    const root = toolNode(node)?.data.root
+    if (root === undefined) continue
+    const found = visit(root)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
diff --git a/packages/client/ui-conversation/src/client/chat/turn-assistant.ts b/packages/client/ui-conversation/src/client/chat/turn-assistant.ts
new file mode 100644
index 0000000000..2abfff56b3
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/turn-assistant.ts
@@ -0,0 +1,10 @@
+import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
+
+/**
+ * Collect visible prose from one Assistant lifecycle.
+ * @param blocks - Assistant content blocks.
+ * @returns concatenated text blocks.
+ */
+export function assistantText(blocks: readonly AssistantBlock[]): string {
+  return blocks.flatMap(block => block.kind === 'text' ? [block.text] : []).join('')
+}
diff --git a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts
index b7cc5ddb72..b93bbfc8eb 100644
--- a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts
+++ b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts
@@ -1,6 +1,6 @@
 // Latency/throughput folds shared by the settled turn footer and StatsLine.
 
-import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { AssistantMessageNode, ConversationNode } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** Latency and decode-throughput readings for one turn's footer. */
 export interface TurnMetrics {
@@ -24,7 +24,7 @@ interface UsageLike {
   outputTokens?: number
 }
 
-type AssistantNode = Extract<ConversationSnapshot['nodes'][number], { kind: 'assistant' }>
+type AssistantNode = AssistantMessageNode
 
 function usageOutputTokens(usage: unknown): number | null {
   if (typeof usage !== 'object' || usage === null) return null
@@ -67,7 +67,7 @@ interface TurnFold {
  * @param nodes - Snapshot nodes of the loaded window.
  * @returns Turn number → available metrics; turns with none are absent.
  */
-export function deriveTurnMetrics(nodes: ConversationSnapshot['nodes']): Map<number, TurnMetrics> {
+export function deriveTurnMetrics(nodes: readonly ConversationNode[]): Map<number, TurnMetrics> {
   const folds = new Map<number, TurnFold>()
   for (const node of nodes) {
     if (node.kind !== 'assistant') continue
diff --git a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
new file mode 100644
index 0000000000..3415c502a5
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
@@ -0,0 +1,82 @@
+import type {
+  AssistantBlock, AssistantMessageNode, ChatConversationViewNode, CommandNode,
+  CompactionSummaryNode, ModelRetryNode, RunningToolCall, ToolCallBlock,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Merge-extensible payload registry keyed by final Chat renderer kind. */
+export interface ChatNodeDataMap {}
+
+/** Renderer kinds contributed by the currently installed Chat business modules. */
+export type ChatNodeKind = keyof ChatNodeDataMap & string
+
+/** Final Chat Node narrowed to one registered renderer kind and payload. */
+export type ChatNode<Kind extends ChatNodeKind = ChatNodeKind> = {
+  [RegisteredKind in Kind]: ChatConversationViewNode & {
+    readonly kind: RegisteredKind
+    readonly data: ChatNodeDataMap[RegisteredKind]
+  }
+}[Kind]
+
+/** Final Assistant row payload shared by streaming and settled states. */
+export interface AssistantChatData {
+  readonly status: 'running' | 'settled' | 'interrupted'
+  readonly turn: number
+  readonly step: number
+  readonly blocks: readonly AssistantBlock[]
+  readonly time: number
+  readonly usage?: unknown
+  readonly finalNode?: AssistantMessageNode
+}
+
+/** Settled or interrupted Assistant payload with its durable presentation node. */
+export type FinalAssistantChatData = AssistantChatData & {
+  readonly finalNode: AssistantMessageNode
+}
+
+/** Root Tool row payload; the root lifecycle owns all recursive subcalls. */
+export interface ToolChatData {
+  readonly root: ToolCallBlock
+}
+
+/** One manual command and its correlated compaction transaction. */
+export interface ManualCompactionChatData {
+  readonly command: CommandNode
+  readonly compaction: CompactionSummaryNode | null
+}
+
+/** One durable retry chain rendered as a single row. */
+export interface RetryChatData {
+  readonly attempts: readonly ModelRetryNode[]
+  readonly current: ModelRetryNode
+}
+
+/** Turn-local footer row that owns actions and optional feature contributions. */
+export interface TurnTailChatData {
+  readonly turn: number
+  readonly seq: number
+  readonly time: number
+  /** Last finalized content-bearing Assistant in this Turn. */
+  readonly closing: FinalAssistantChatData | null
+  /** Whether later Assistant/Step material makes the closing seq non-tail. */
+  readonly branchUnavailable: boolean
+  readonly ttftMs?: number
+  readonly tokensPerSecond?: number
+}
+
+/**
+ * Test whether a Tool root has settled.
+ * @param block - Tool root lifecycle value.
+ * @returns whether the root carries its final result.
+ */
+export function isSettledTool(block: ToolCallBlock): block is Extract<ToolCallBlock, { kind: 'tool-result' }> {
+  return 'kind' in block
+}
+
+/**
+ * Test whether a Tool root is still running.
+ * @param block - Tool root lifecycle value.
+ * @returns whether the root lacks a final result.
+ */
+export function isRunningTool(block: ToolCallBlock): block is RunningToolCall {
+  return !isSettledTool(block)
+}
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index a57bcbd5a7..474e7f9db5 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -1,15 +1,21 @@
 /** Conversation slot declarations and their composed component props. */
 import type { ReactNode, RefObject } from 'react'
 import type {
-  InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
+  InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
+  SlotHookFactory, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  CommandNode, CompactionSummaryNode, ConversationSnapshot, ConversationTurnDataMap,
+  ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock,
+  TurnLocation, WorkspaceId,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ComposerBlock } from '../input/blocks.ts'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
 import type { ComposerSubmitGesture, InputSubmitMode } from './composer-submission.ts'
+import type { ChatNode, ChatNodeKind } from './chat-nodes.ts'
 import type { CallId, SelectionTarget, ViewTab } from './views.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -31,13 +37,15 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * conversation snapshot through the standard kit.
      */
     'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps }
-    /**
-     * One root Tool call at its ordered ChatFlow position. The chat view owns
-     * placement; ui-tool owns root/subcall composition and keyed dispatch.
-     * The filler preserves the call-anchor DOM contract documented by
-     * {@link ToolTreeOwnerProps} for every root and child wrapper.
-     */
-    'conversation.chat.tool': { kind: 'single'; scope: 'session'; owner: ToolTreeOwnerProps }
+    /** Final business node renderer, dispatched by `ChatConversationViewNode.kind`. */
+    'conversation.chat.node': {
+      kind: 'keyed'
+      scope: 'session'
+      owner: ChatNodeOwnerProps
+      keyProps: { [Kind in ChatNodeKind]: { node: ChatNode<Kind> } }
+      hookContext: string
+      inject: ChatNodeTurnDataInjected
+    }
     /**
      * The chat view's per-command row hole: keyed dispatch on the command
      * name (`command/run.name`; a run-less cross-window node has none and
@@ -171,7 +179,7 @@ export interface ConvViewOwnerProps {
 export interface ChatFileMentions {
   /**
    * Mention vocabulary for the closing message the owner currency names.
-   * @param owner - Turn-tail owner currency (nodes, closing seq, opener).
+   * @param owner - Turn-tail owner currency (Turn data, closing seq, opener).
    * @returns The resolver MarkdownText consumes, or undefined when the turn
    * produced nothing worth linking.
    */
@@ -186,14 +194,13 @@ declare module 'cordis' {
 }
 
 /**
- * Owner currency of the chat view's turn-tail hole: the finalized snapshot
- * and the closing assistant's anchor. Registrants derive their own facts
- * from the nodes (the owner never pre-chews a feature's vocabulary), and
- * open files through the same opener the tool rows use.
+ * Owner currency of the chat view's turn-tail hole: the engine-owned Turn and
+ * the closing assistant's anchor. Registrants read their own typed Turn data
+ * and open files through the same opener the tool rows use.
  */
 export interface TurnTailOwnerProps {
-  /** Finalized snapshot nodes in surface order. */
-  nodes: readonly ConversationNode[]
+  /** Engine-owned closing Turn boundary. */
+  turn: TurnLocation
   /** The closing assistant's seq — the anchor the tail renders under. */
   seq: number
   /**
@@ -203,34 +210,34 @@ export interface TurnTailOwnerProps {
   openFile: (path: string) => void
 }
 
-/**
- * Owner currency of the chat view's whole-Tool rendering seat. The filler
- * wraps every rendered root and child with `data-chat-anchor-key="call:<id>"`
- * and `data-chat-call-id="<id>"`, plus `data-selected="true"` for the selected
- * call. ChatView consumes those anchors to restore prepend/paging position.
- */
-export interface ToolTreeOwnerProps {
-  /** Root Tool call identity, stable across running → settled. */
-  callId: CallId
-  /** Root wire Tool name. */
-  toolName: string
-  /** Frozen root call slice: running call or settled result node. */
-  block: ToolCallBlock
-  /** Selected call id; the Tool owner resolves whether it is root or child. */
-  selectedCallId?: CallId | undefined
-  /** Session workspace root; path summaries display relative to it. */
-  cwd?: string | undefined
-  /**
-   * Open a tool-arg filesystem path with the host OS default application.
-   * The conversation owner resolves relative paths against the session cwd.
-   */
-  openFile: (path: string) => void
-  /**
-   * Jump to any call in this tree in the trajectory view.
-   */
-  inspectCall: (callId: CallId) => void
+/** Hook constrained to business data published on the current Chat Node's Turn. */
+export type UseChatNodeTurnData = <Key extends keyof ConversationTurnDataMap & string>(
+  key: Key,
+) => Readonly<ConversationTurnDataMap[Key]> | undefined
+
+/** Slot-level Hook factory used by renderers reading their Node's Turn data. */
+export interface ChatNodeTurnDataInjected {
+  hooks: {
+    turnData: SlotHookFactory<'conversation.chat.node', UseChatNodeTurnData>
+  }
 }
 
+/** Stable owner currency delivered to one keyed Chat business renderer. */
+export interface ChatNodeOwnerProps {
+  /** Selected Tool call, when the shared details store names one. */
+  selectedCallId?: CallId | undefined
+  /** Session workspace root; Tool summaries display paths relative to it. */
+  cwd?: string | undefined
+  openFile: (path: string) => void
+  inspectCall: (callId: CallId) => void
+  forkAt: (seq: number) => void
+  fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined
+}
+
+/** Full props of one registered keyed Chat business renderer. */
+export type ChatNodeViewProps<Kind extends ChatNodeKind = ChatNodeKind> =
+  PropsRuntime<'conversation.chat.node', Kind> & PropsLocale<'conversation'>
+
 /** Owner currency of the details panel's Tool output renderer. */
 export interface DetailsToolOwnerProps {
   /** Frozen selected call slice. */
@@ -555,7 +562,7 @@ export interface ChatViewInjected {
 
 /** Full chat-view component props: runtime & its Tool/command/tail render shares & store & injected & locale seat. */
 export type ChatViewSlotProps =
-  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.tool' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
+  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.node'>
   & PropsStore<ChatStore> & ChatViewInjected & PropsLocale<'conversation'>
 
 /**
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
new file mode 100644
index 0000000000..2bdf960226
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
@@ -0,0 +1,316 @@
+import type { Context } from 'cordis'
+import type {
+  AssistantBlock, AssistantMessageNode, ConversationLocation, ConversationMatch,
+  ConversationNodeContext, ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  emptyAssistantBlock, isAppendSurfaceEvent, isTokenDelta, toAssistantBlock, toAssistantBlocks,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { AssistantChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Streaming, settled, or interrupted Assistant step. */
+    'assistant-step': AssistantChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationStepDataMap {
+    /** Streaming, settled, or interrupted Assistant material for this Step. */
+    'assistant-step': AssistantChatData
+  }
+}
+
+interface AssistantState {
+  readonly turn: number
+  readonly step: number
+  readonly blocks: readonly (AssistantBlock | undefined)[]
+  readonly firstVisibleSeq: number | undefined
+  readonly firstVisibleTime: number | undefined
+  readonly firstTokenTime: number | undefined
+  readonly hidden: boolean
+  readonly final: ConversationMatch | undefined
+  readonly usage: unknown
+}
+
+function initialState(turn: number, step: number): AssistantState {
+  return {
+    turn,
+    step,
+    blocks: [],
+    firstVisibleSeq: undefined,
+    firstVisibleTime: undefined,
+    firstTokenTime: undefined,
+    hidden: false,
+    final: undefined,
+    usage: undefined,
+  }
+}
+
+function compactBlocks(blocks: readonly (AssistantBlock | undefined)[]): AssistantBlock[] {
+  return blocks.filter((block): block is AssistantBlock => block !== undefined)
+}
+
+function hasVisibleContent(blocks: readonly AssistantBlock[]): boolean {
+  return blocks.some((block) => {
+    if (block.kind === 'tool-call') return false
+    if (block.kind === 'text' || block.kind === 'reasoning') return block.text.trim() !== ''
+    return true
+  })
+}
+
+function hasInterruptionEvidence(blocks: readonly AssistantBlock[]): boolean {
+  return blocks.some((block) => {
+    if (block.kind === 'text' || block.kind === 'reasoning') return block.text.trim() !== ''
+    return true
+  })
+}
+
+function resetForRetry(state: AssistantState): AssistantState {
+  return {
+    ...initialState(state.turn, state.step),
+    firstTokenTime: state.firstTokenTime,
+    hidden: true,
+  }
+}
+
+function updateChunk(state: AssistantState, match: ConversationMatch): AssistantState {
+  if (match.event.type !== 'assistant/chunk') return state
+  const chunk = match.event.data.chunk
+  const blocks = [...state.blocks]
+  switch (chunk.type) {
+    case 'block-start':
+      blocks[chunk.index] = emptyAssistantBlock(chunk.blockType)
+      break
+    case 'text-delta': {
+      const previous = blocks[chunk.index]
+      blocks[chunk.index] = { kind: 'text', text: (previous?.kind === 'text' ? previous.text : '') + chunk.text }
+      break
+    }
+    case 'reasoning-delta': {
+      const previous = blocks[chunk.index]
+      blocks[chunk.index] = { kind: 'reasoning', text: (previous?.kind === 'reasoning' ? previous.text : '') + chunk.text }
+      break
+    }
+    case 'tool-call-delta': {
+      const previous = blocks[chunk.index]
+      const base = previous?.kind === 'tool-call'
+        ? previous
+        : { kind: 'tool-call' as const, callId: '', name: '', argsRaw: '' }
+      blocks[chunk.index] = {
+        kind: 'tool-call',
+        callId: base.callId || String(chunk.id),
+        name: chunk.name ?? base.name,
+        argsRaw: base.argsRaw + chunk.argumentsDelta,
+      }
+      break
+    }
+    case 'block-end':
+      blocks[chunk.index] = toAssistantBlock(chunk.block)
+      break
+    case 'usage':
+      return { ...state, usage: chunk.usage }
+    default:
+      return state
+  }
+  const visible = hasVisibleContent(compactBlocks(blocks))
+  const firstToken = isTokenDelta(chunk)
+  return {
+    ...state,
+    blocks,
+    hidden: visible ? false : state.hidden,
+    ...visible && state.firstVisibleSeq === undefined
+      ? { firstVisibleSeq: match.event.seq, firstVisibleTime: match.event.time }
+      : {},
+    ...firstToken && state.firstTokenTime === undefined
+      ? { firstTokenTime: match.event.time }
+      : {},
+  }
+}
+
+function closedBoundary(location: ConversationLocation): { seq: number; time: number } | undefined {
+  if (location.kind === 'step' && location.step.status === 'closed' && location.step.end !== undefined) {
+    return location.step.end
+  }
+  if ((location.kind === 'step' || location.kind === 'turn')
+    && location.turn.status === 'closed' && location.turn.end !== undefined) {
+    return location.turn.end
+  }
+  return undefined
+}
+
+function finalNode(
+  state: AssistantState,
+  context: ConversationNodeContext<AssistantState>,
+): AssistantMessageNode | undefined {
+  const final = state.final
+  if (final?.event.type === 'assistant/message') {
+    const event = final.event
+    return {
+      kind: 'assistant',
+      seq: event.seq,
+      time: event.time,
+      turn: state.turn,
+      step: state.step,
+      blocks: toAssistantBlocks(event.data.message.content),
+      usage: event.data.usage,
+      timing: {
+        stepStartTime: context.start?.event.time ?? null,
+        firstTokenTime: state.firstTokenTime ?? null,
+        completedTime: event.time,
+      },
+    }
+  }
+  const location = context.start?.location ?? context.matches.at(-1)?.location
+  const boundary = location === undefined ? undefined : closedBoundary(location)
+  const blocks = compactBlocks(state.blocks)
+  if (boundary === undefined || !hasInterruptionEvidence(blocks)) return undefined
+  return {
+    kind: 'assistant',
+    seq: boundary.seq - 0.9,
+    time: boundary.time,
+    turn: state.turn,
+    step: state.step,
+    blocks,
+    interrupted: true,
+  }
+}
+
+function fallbackState(context: ConversationNodeContext<AssistantState>): AssistantState | undefined {
+  let state: AssistantState | undefined
+  for (const match of context.matches) {
+    if (match.event.type === 'assistant/chunk') {
+      state ??= initialState(match.event.data.turn, match.event.data.step)
+      state = updateChunk(state, match)
+      continue
+    }
+    if (match.event.type === 'assistant/message') {
+      state ??= initialState(match.event.data.turn, match.event.data.step)
+      state = {
+        ...state,
+        blocks: toAssistantBlocks(match.event.data.message.content),
+        hidden: false,
+        final: match,
+        usage: match.event.data.usage,
+      }
+      continue
+    }
+    if ((match.event.type as string) === 'llm/retry' && state !== undefined) {
+      state = resetForRetry(state)
+    }
+  }
+  return state
+}
+
+interface AssistantProjection {
+  readonly data: AssistantChatData
+  readonly anchorSeq: number
+  readonly visible: boolean
+  readonly settled: AssistantMessageNode | undefined
+}
+
+function projectAssistant(context: ConversationNodeContext<AssistantState>): AssistantProjection | undefined {
+  const state = context.state ?? fallbackState(context)
+  if (state === undefined) return undefined
+  const settled = finalNode(state, context)
+  const blocks = settled?.blocks ?? compactBlocks(state.blocks)
+  const visible = hasVisibleContent(blocks)
+  const status = settled?.interrupted === true
+    ? 'interrupted'
+    : settled === undefined ? 'running' : 'settled'
+  const anchorSeq = settled?.seq ?? state.firstVisibleSeq ?? context.matches[0]?.event.seq ?? 0
+  const time = settled?.time ?? state.firstVisibleTime ?? context.matches[0]?.event.time ?? 0
+  return {
+    anchorSeq,
+    visible,
+    settled,
+    data: {
+      status,
+      turn: state.turn,
+      step: state.step,
+      blocks,
+      time,
+      ...state.usage === undefined ? {} : { usage: state.usage },
+      ...settled === undefined ? {} : { finalNode: settled },
+    },
+  }
+}
+
+/** Per-step Assistant streaming/final/interruption Definition. */
+export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
+  kind: 'assistant-step',
+  match: (event) => {
+    if (event.type === 'step/start') return { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+    if (event.type === 'assistant/chunk'
+      || (event.type === 'assistant/message' && isAppendSurfaceEvent(event))) {
+      return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
+    }
+    if ((event.type as string) === 'llm/retry') {
+      const data = event.data as unknown as { turn: number; step: number }
+      return { id: `${data.turn}:${data.step}`, role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'step/start') throw new Error('assistant-step start requires step/start')
+    return initialState(match.event.data.turn, match.event.data.step)
+  },
+  update: (context, match) => {
+    if (match.event.type === 'assistant/chunk') return updateChunk(context.state, match)
+    if (match.event.type === 'assistant/message') {
+      return {
+        ...context.state,
+        blocks: toAssistantBlocks(match.event.data.message.content),
+        hidden: false,
+        final: match,
+        usage: match.event.data.usage,
+      }
+    }
+    if ((match.event.type as string) === 'llm/retry') {
+      return resetForRetry(context.state)
+    }
+    return context.state
+  },
+  publication: (match) => {
+    if (match.event.type === 'step/start') return 'none'
+    if (match.event.type !== 'assistant/chunk') return 'immediate'
+    const type = match.event.data.chunk.type
+    return type === 'usage' || type === 'finish' ? 'none' : 'animation-frame'
+  },
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step') return null
+    const projected = projectAssistant(context)
+    if (projected === undefined) return null
+    return {
+      kind: 'step',
+      turn: projected.data.turn,
+      step: projected.data.step,
+      key: 'assistant-step',
+      value: projected.data,
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const projected = projectAssistant(context)
+    if (projected === undefined) return null
+    if (projected.settled === undefined && !projected.visible) {
+      const state = context.state ?? fallbackState(context)
+      if (state === undefined) return null
+      const current = context.current.get('chat')
+      if (!state.hidden || current === undefined || current === null) return null
+    }
+    return chatNode(context, 'assistant-step', projected.anchorSeq, projected.data, {
+      visibility: projected.settled?.interrupted === true || projected.visible ? 'visible' : 'hidden',
+    })
+  },
+}
+
+/**
+ * Register the Assistant lifecycle business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerAssistantConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(assistantDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
new file mode 100644
index 0000000000..f9491d2d16
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -0,0 +1,456 @@
+import type { Context } from 'cordis'
+import type {
+  ChatConversationViewNode, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot,
+  ConversationLocation, ConversationNode, ConversationTimelineSnapshot,
+  ConversationViewBuilder, ConversationViewDefinition, LegacyConversationSlice,
+  PartialAssistant, RunningToolCall,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNode } from '../contract/chat-nodes.ts'
+import { isRunningTool } from '../contract/chat-nodes.ts'
+
+const EMPTY_KEYS: readonly string[] = []
+const EMPTY_TURNS: readonly number[] = []
+const EMPTY_LIST: readonly never[] = []
+
+function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+class MutableChatNodeStore implements ChatNodeStore {
+  private readonly byKey = new Map<string, ChatConversationViewNode>()
+  private valuesCache: readonly ChatConversationViewNode[] = EMPTY_LIST
+  private valuesDirty = false
+
+  get(key: string): ChatConversationViewNode | undefined {
+    return this.byKey.get(key)
+  }
+
+  values(): readonly ChatConversationViewNode[] {
+    if (this.valuesDirty) {
+      this.valuesCache = [...this.byKey.values()]
+      this.valuesDirty = false
+    }
+    return this.valuesCache
+  }
+
+  replace(nodes: readonly ChatConversationViewNode[]): void {
+    this.byKey.clear()
+    for (const node of nodes) this.byKey.set(node.key, node)
+    this.valuesCache = [...this.byKey.values()]
+    this.valuesDirty = false
+  }
+
+  upsert(nodes: readonly ChatConversationViewNode[]): void {
+    let changed = false
+    for (const node of nodes) {
+      if (this.byKey.get(node.key) === node) continue
+      this.byKey.set(node.key, node)
+      changed = true
+    }
+    if (changed) this.valuesDirty = true
+  }
+}
+
+class MutableChatLocationIndex implements ChatLocationNodeIndex {
+  private turns = new Map<number, readonly string[]>()
+  private steps = new Map<string, readonly string[]>()
+
+  getTurn(turn: number): readonly string[] {
+    return this.turns.get(turn) ?? EMPTY_KEYS
+  }
+
+  getStep(turn: number, step: number): readonly string[] {
+    return this.steps.get(stepKey(turn, step)) ?? EMPTY_KEYS
+  }
+
+  rebuild(order: readonly string[], store: ChatNodeStore): void {
+    const turns = new Map<number, string[]>()
+    const steps = new Map<string, string[]>()
+    for (const key of order) {
+      const location = store.get(key)?.location
+      if (location === undefined) continue
+      const coordinates = locationCoordinates(location)
+      if (coordinates.turn === undefined) continue
+      const turnKeys = turns.get(coordinates.turn) ?? []
+      turnKeys.push(key)
+      turns.set(coordinates.turn, turnKeys)
+      if (coordinates.step === undefined) continue
+      const step = stepKey(coordinates.turn, coordinates.step)
+      const stepKeys = steps.get(step) ?? []
+      stepKeys.push(key)
+      steps.set(step, stepKeys)
+    }
+    this.turns = updateIndex(this.turns, turns)
+    this.steps = updateIndex(this.steps, steps)
+  }
+
+  /** Invalidate aggregate readers when member data changes without moving. */
+  touch(nodes: readonly ChatConversationViewNode[]): void {
+    const turns = new Set<number>()
+    const steps = new Set<string>()
+    for (const node of nodes) {
+      const coordinates = locationCoordinates(node.location)
+      if (coordinates.turn === undefined || !this.turns.get(coordinates.turn)?.includes(node.key)) continue
+      turns.add(coordinates.turn)
+      if (coordinates.step !== undefined) steps.add(stepKey(coordinates.turn, coordinates.step))
+    }
+    for (const turn of turns) {
+      const keys = this.turns.get(turn)
+      if (keys === undefined) continue
+      this.turns.set(turn, [...keys])
+    }
+    for (const step of steps) {
+      const keys = this.steps.get(step)
+      if (keys === undefined) continue
+      this.steps.set(step, [...keys])
+    }
+  }
+}
+
+function updateIndex<Key>(
+  previous: ReadonlyMap<Key, readonly string[]>,
+  nextMutable: ReadonlyMap<Key, string[]>,
+): Map<Key, readonly string[]> {
+  const next = new Map<Key, readonly string[]>()
+  const keys = new Set([...previous.keys(), ...nextMutable.keys()])
+  for (const key of keys) {
+    const before = previous.get(key) ?? EMPTY_KEYS
+    const candidate = nextMutable.get(key) ?? EMPTY_KEYS
+    const value = sameReferences(before, candidate) ? before : candidate
+    if (candidate.length > 0) next.set(key, value)
+  }
+  return next
+}
+
+function stepKey(turn: number, step: number): string {
+  return `${turn}:${step}`
+}
+
+function locationCoordinates(location: ConversationLocation): { turn?: number; step?: number } {
+  if (location.kind === 'step') return { turn: location.turn.turn, step: location.step.step }
+  if (location.kind === 'turn') return { turn: location.turn.turn }
+  return {}
+}
+
+function orderedVisible(nodes: readonly ChatConversationViewNode[]): ChatConversationViewNode[] {
+  return nodes
+    .filter(node => node.visibility === 'visible')
+    .sort((left, right) => left.anchorSeq - right.anchorSeq || left.key.localeCompare(right.key))
+}
+
+interface LegacyContribution {
+  readonly anchorSeq: number
+  readonly nodes: readonly ConversationNode[]
+  readonly partial: PartialAssistant | null
+  readonly running: RunningToolCall | null
+}
+
+const EMPTY_CONTRIBUTION: LegacyContribution = {
+  anchorSeq: 0,
+  nodes: EMPTY_LIST,
+  partial: null,
+  running: null,
+}
+
+function legacyContribution(raw: ChatConversationViewNode): LegacyContribution {
+  const node = raw as ChatNode
+  if (raw.visibility !== 'visible' && node.kind !== 'assistant-step') return EMPTY_CONTRIBUTION
+  switch (node.kind) {
+    case 'user':
+    case 'steering':
+    case 'context':
+    case 'command':
+    case 'compaction':
+    case 'turn-error':
+    case 'unknown':
+      return { anchorSeq: node.anchorSeq, nodes: [node.data], partial: null, running: null }
+    case 'assistant-step': {
+      const data = node.data
+      if (data.status === 'running') {
+        if (raw.visibility !== 'visible') return EMPTY_CONTRIBUTION
+        return {
+          anchorSeq: node.anchorSeq,
+          nodes: EMPTY_LIST,
+          partial: { turn: data.turn, step: data.step, blocks: data.blocks },
+          running: null,
+        }
+      }
+      return {
+        anchorSeq: node.anchorSeq,
+        nodes: data.finalNode === undefined ? EMPTY_LIST : [data.finalNode],
+        partial: null,
+        running: null,
+      }
+    }
+    case 'tool-call': {
+      const root = node.data.root
+      return isRunningTool(root)
+        ? { anchorSeq: node.anchorSeq, nodes: EMPTY_LIST, partial: null, running: root }
+        : { anchorSeq: node.anchorSeq, nodes: [root], partial: null, running: null }
+    }
+    case 'manual-compaction': {
+      const data = node.data
+      return {
+        anchorSeq: node.anchorSeq,
+        nodes: data.compaction === null ? [data.command] : [data.command, data.compaction],
+        partial: null,
+        running: null,
+      }
+    }
+    case 'model-retry':
+      return {
+        anchorSeq: node.anchorSeq,
+        nodes: node.data.attempts,
+        partial: null,
+        running: null,
+      }
+    case 'turn-tail':
+      return EMPTY_CONTRIBUTION
+    default:
+      return EMPTY_CONTRIBUTION
+  }
+}
+
+function sameContribution(left: LegacyContribution | undefined, right: LegacyContribution): boolean {
+  return left !== undefined
+    && left.anchorSeq === right.anchorSeq
+    && left.partial?.blocks === right.partial?.blocks
+    && left.partial?.turn === right.partial?.turn
+    && left.partial?.step === right.partial?.step
+    && left.running === right.running
+    && sameReferences(left.nodes, right.nodes)
+}
+
+/** Incremental compatibility projection retained solely for unmigrated Trajectory consumers. */
+class LegacySliceBuilder {
+  private readonly contributions = new Map<string, LegacyContribution>()
+  private readonly finalizedContributions = new Map<string, LegacyContribution>()
+  private readonly runningContributions = new Map<string, LegacyContribution>()
+  private readonly partialContributions = new Map<string, LegacyContribution>()
+  private finalized: readonly ConversationNode[] = EMPTY_LIST
+  private runningCalls: readonly RunningToolCall[] = EMPTY_LIST
+  private partial: PartialAssistant | null = null
+  private timeline: ConversationTimelineSnapshot | undefined
+  private turnTimings: LegacyConversationSlice['turnTimings'] = new Map()
+  private turnEnds: LegacyConversationSlice['turnEnds'] = new Map()
+
+  replace(
+    nodes: readonly ChatConversationViewNode[],
+    timeline: ConversationTimelineSnapshot,
+  ): LegacyConversationSlice {
+    this.contributions.clear()
+    this.finalizedContributions.clear()
+    this.runningContributions.clear()
+    this.partialContributions.clear()
+    for (const node of nodes) {
+      const contribution = legacyContribution(node)
+      this.contributions.set(node.key, contribution)
+      this.indexContribution(node.key, contribution)
+    }
+    this.rebuildFinalized()
+    this.rebuildRunning()
+    this.rebuildPartial()
+    this.updateTimeline(timeline)
+    return this.snapshot()
+  }
+
+  apply(
+    upserts: readonly ChatConversationViewNode[],
+    timeline: ConversationTimelineSnapshot,
+  ): LegacyConversationSlice {
+    let finalizedChanged = false
+    let runningChanged = false
+    let partialChanged = false
+    for (const node of upserts) {
+      const contribution = legacyContribution(node)
+      const previous = this.contributions.get(node.key)
+      if (sameContribution(previous, contribution)) continue
+      finalizedChanged ||= finalizedContributionChanged(previous, contribution)
+      runningChanged ||= runningContributionChanged(previous, contribution)
+      partialChanged ||= partialContributionChanged(previous, contribution)
+      this.contributions.set(node.key, contribution)
+      this.indexContribution(node.key, contribution)
+    }
+    if (finalizedChanged) this.rebuildFinalized()
+    if (runningChanged) this.rebuildRunning()
+    if (partialChanged) this.rebuildPartial()
+    this.updateTimeline(timeline)
+    return this.snapshot()
+  }
+
+  private indexContribution(key: string, contribution: LegacyContribution): void {
+    updateContributionIndex(this.finalizedContributions, key, contribution, contribution.nodes.length > 0)
+    updateContributionIndex(this.runningContributions, key, contribution, contribution.running !== null)
+    updateContributionIndex(this.partialContributions, key, contribution, contribution.partial !== null)
+  }
+
+  private rebuildFinalized(): void {
+    const finalized = [...this.finalizedContributions.values()]
+      .flatMap(value => value.nodes)
+      .sort((left, right) => left.seq - right.seq)
+    if (!sameReferences(this.finalized, finalized)) this.finalized = finalized
+  }
+
+  private rebuildRunning(): void {
+    const runningCalls = [...this.runningContributions.values()]
+      .sort((left, right) => left.anchorSeq - right.anchorSeq)
+      .flatMap(value => value.running === null ? [] : [value.running])
+    if (!sameReferences(this.runningCalls, runningCalls)) this.runningCalls = runningCalls
+  }
+
+  private rebuildPartial(): void {
+    const partial = [...this.partialContributions.values()]
+      .sort((left, right) => left.anchorSeq - right.anchorSeq)
+      .findLast(value => value.partial !== null)?.partial ?? null
+    if (this.partial?.blocks !== partial?.blocks
+      || this.partial?.turn !== partial?.turn
+      || this.partial?.step !== partial?.step) this.partial = partial
+  }
+
+  private updateTimeline(timeline: ConversationTimelineSnapshot): void {
+    if (this.timeline === timeline) return
+    this.timeline = timeline
+    const turnTimings = new Map<number, { startTime: number; endTime?: number }>()
+    const turnEnds = new Map<number, number>()
+    for (const turn of timeline.turns.values()) {
+      if (turn.start !== undefined) {
+        turnTimings.set(turn.turn, {
+          startTime: turn.start.time,
+          ...turn.end === undefined ? {} : { endTime: turn.end.time },
+        })
+      }
+      if (turn.end !== undefined) turnEnds.set(turn.turn, turn.end.seq)
+    }
+    this.turnTimings = turnTimings
+    this.turnEnds = turnEnds
+  }
+
+  private snapshot(): LegacyConversationSlice {
+    return {
+      nodes: this.finalized,
+      turnTimings: this.turnTimings,
+      turnEnds: this.turnEnds,
+      partial: this.partial,
+      runningCalls: this.runningCalls,
+    }
+  }
+}
+
+function updateContributionIndex(
+  index: Map<string, LegacyContribution>,
+  key: string,
+  contribution: LegacyContribution,
+  present: boolean,
+): void {
+  if (present) index.set(key, contribution)
+  else index.delete(key)
+}
+
+function finalizedContributionChanged(
+  previous: LegacyContribution | undefined,
+  next: LegacyContribution,
+): boolean {
+  const previousNodes = previous?.nodes ?? EMPTY_LIST
+  return !sameReferences(previousNodes, next.nodes)
+    || ((previousNodes.length > 0 || next.nodes.length > 0) && previous?.anchorSeq !== next.anchorSeq)
+}
+
+function runningContributionChanged(
+  previous: LegacyContribution | undefined,
+  next: LegacyContribution,
+): boolean {
+  return previous?.running !== next.running
+    || ((previous.running !== null || next.running !== null)
+      && previous.anchorSeq !== next.anchorSeq)
+}
+
+function partialContributionChanged(
+  previous: LegacyContribution | undefined,
+  next: LegacyContribution,
+): boolean {
+  return previous?.partial?.blocks !== next.partial?.blocks
+    || previous?.partial?.turn !== next.partial?.turn
+    || previous?.partial?.step !== next.partial?.step
+    || (((previous?.partial ?? null) !== null || next.partial !== null)
+      && previous?.anchorSeq !== next.anchorSeq)
+}
+
+/** Incremental keyed Chat builder registered under the `chat` target. */
+export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversationViewNode, ChatSnapshot> {
+  private readonly store = new MutableChatNodeStore()
+  private readonly locations = new MutableChatLocationIndex()
+  private readonly legacy = new LegacySliceBuilder()
+  private order: readonly string[] = EMPTY_KEYS
+  readonly empty: ChatSnapshot
+
+  constructor() {
+    this.empty = this.snapshot({ turnOrder: EMPTY_TURNS, turns: new Map() })
+  }
+
+  replace(input: {
+    readonly nodes: readonly ChatConversationViewNode[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): ChatSnapshot {
+    this.store.replace(input.nodes)
+    this.order = orderedVisible(input.nodes).map(node => node.key)
+    this.locations.rebuild(this.order, this.store)
+    return this.snapshot(input.timeline, this.legacy.replace(input.nodes, input.timeline))
+  }
+
+  apply(input: {
+    readonly upserts: readonly ChatConversationViewNode[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): ChatSnapshot {
+    let structural = false
+    const contentOnly: ChatConversationViewNode[] = []
+    for (const node of input.upserts) {
+      const previous = this.store.get(node.key)
+      const nodeStructural = previous === undefined
+        || previous.anchorSeq !== node.anchorSeq
+        || previous.visibility !== node.visibility
+        || locationIdentity(previous.location) !== locationIdentity(node.location)
+      structural ||= nodeStructural
+      if (!nodeStructural) contentOnly.push(node)
+    }
+    this.store.upsert(input.upserts)
+    if (structural) {
+      const next = orderedVisible(this.store.values()).map(node => node.key)
+      this.order = sameReferences(this.order, next) ? this.order : next
+      this.locations.rebuild(this.order, this.store)
+    }
+    this.locations.touch(contentOnly)
+    return this.snapshot(input.timeline, this.legacy.apply(input.upserts, input.timeline))
+  }
+
+  private snapshot(
+    timeline: ConversationTimelineSnapshot,
+    legacy = this.legacy.replace(EMPTY_LIST, timeline),
+  ): ChatSnapshot {
+    return {
+      order: this.order,
+      nodes: this.store,
+      locations: this.locations,
+      timeline,
+      legacy,
+    }
+  }
+}
+
+function locationIdentity(location: ConversationLocation): string {
+  const coordinates = locationCoordinates(location)
+  return `${location.kind}:${coordinates.turn ?? ''}:${coordinates.step ?? ''}`
+}
+
+/** Chat target factory contributed to the Runtime view registry. */
+export const chatViewDefinition: ConversationViewDefinition<ChatConversationViewNode, ChatSnapshot> = {
+  target: 'chat',
+  create: () => new ChatSnapshotBuilder(),
+}
+
+/**
+ * Register the incremental Chat target builder.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerChatConversationView(ctx: Context): void {
+  ctx.conversationViews.register(chatViewDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
new file mode 100644
index 0000000000..3ca7976e32
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
@@ -0,0 +1,243 @@
+import type { Context } from 'cordis'
+import type {
+  CommandNode, CompactionSummaryNode, ConversationMatch, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type { ManualCompactionChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Ordinary slash-command lifecycle. */
+    command: CommandNode
+    /** Manual compact command combined with its compaction transaction. */
+    'manual-compaction': ManualCompactionChatData
+  }
+}
+
+type CommandId = CommandNode['commandId']
+
+const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+
+interface CommandState {
+  readonly command: CommandNode
+  readonly summary?: ConversationMatch
+  readonly checkpoint?: ConversationMatch
+}
+
+interface CompactionEvidence {
+  readonly summary?: ConversationMatch
+  readonly checkpoint?: ConversationMatch
+}
+
+interface CommandRunData {
+  readonly commandId: CommandId
+  readonly name: string
+  readonly args?: string
+}
+
+interface CommandDoneData {
+  readonly commandId: CommandId
+  readonly kind: 'success' | 'error'
+  readonly text?: string
+  readonly sourceEventSeq?: number
+}
+
+function commandFromRun(match: ConversationMatch): CommandNode {
+  const data = match.event.data as unknown as CommandRunData
+  return {
+    kind: 'command',
+    seq: match.event.seq,
+    time: match.event.time,
+    commandId: data.commandId,
+    name: data.name,
+    args: data.args ?? null,
+    outcome: null,
+  }
+}
+
+function commandFromDone(match: ConversationMatch, previous?: CommandNode): CommandNode {
+  const data = match.event.data as unknown as CommandDoneData
+  const sourceEventSeq = data.kind === 'success'
+    && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
+    ? data.sourceEventSeq as number
+    : undefined
+  return {
+    kind: 'command',
+    seq: previous?.seq ?? match.event.seq,
+    time: previous?.time ?? match.event.time,
+    commandId: data.commandId,
+    name: previous?.name ?? null,
+    args: previous?.args ?? null,
+    outcome: {
+      kind: data.kind,
+      ...data.text === undefined ? {} : { text: data.text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    },
+  }
+}
+
+/**
+ * Read correlation identity from a compaction replacement checkpoint.
+ * @param event - candidate Session event.
+ * @returns correlated compaction and optional command identity.
+ */
+function compactSource(event: Parameters<ConversationNodeDefinition['match']>[0]): {
+  compactionId: string
+  sourceCommandId?: CommandId
+} | undefined {
+  if (event.type !== 'user/message' || !isReplacementSurfaceEvent(event)) return undefined
+  const source = event.data.source as unknown as {
+    kind?: unknown
+    plugin?: unknown
+    compactionId?: unknown
+    sourceCommandId?: CommandId
+  }
+  if (source.kind !== 'plugin' || source.plugin !== COMPACT_PLUGIN || typeof source.compactionId !== 'string') return undefined
+  return {
+    compactionId: source.compactionId,
+    ...source.sourceCommandId === undefined ? {} : { sourceCommandId: source.sourceCommandId },
+  }
+}
+
+/**
+ * Build the visible summary marker from optional lifecycle evidence.
+ * @param match - compact/summary Match, when loaded.
+ * @param checkpoint - replacement checkpoint Match.
+ * @returns final compaction summary Node data.
+ */
+function compactSummary(match: ConversationMatch | undefined, checkpoint: ConversationMatch): CompactionSummaryNode {
+  let summary: string | null = null
+  let shadowedItemCount: number | null = null
+  let shadowedTokenCount: number | null = null
+  if (match !== undefined) {
+    const data = match.event.data as unknown as {
+      summary?: unknown
+      shadowedSeqs?: unknown
+      shadowedTokenCount?: unknown
+    }
+    if (Array.isArray(data.summary)) {
+      const text = data.summary
+        .map((block: unknown) => {
+          const value = block as { type?: unknown; text?: unknown }
+          return value.type === 'text' && typeof value.text === 'string' ? value.text : ''
+        })
+        .join('')
+      summary = text.trim() === '' ? null : text
+    }
+    shadowedItemCount = Array.isArray(data.shadowedSeqs)
+      && data.shadowedSeqs.every(seq => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      ? data.shadowedSeqs.length
+      : null
+    shadowedTokenCount = Number.isSafeInteger(data.shadowedTokenCount)
+      && (data.shadowedTokenCount as number) >= 0
+      ? data.shadowedTokenCount as number
+      : null
+  }
+  return {
+    kind: 'compaction',
+    seq: checkpoint.event.seq,
+    time: checkpoint.event.time,
+    summary,
+    summaryEventSeq: match?.event.seq ?? null,
+    shadowedItemCount,
+    shadowedTokenCount,
+  }
+}
+
+function fallbackState(context: ConversationNodeContext<CommandState>): CommandState | undefined {
+  const done = context.matches.find(match => (match.event.type as string) === 'command/done')
+  const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
+  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  if (checkpoint === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
+  const source = compactSource(checkpoint.event)
+  if (source?.sourceCommandId === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
+  const fallbackCommand = done === undefined
+    ? {
+      kind: 'command' as const,
+      seq: checkpoint.event.seq,
+      time: checkpoint.event.time,
+      commandId: source.sourceCommandId,
+      name: 'compact',
+      args: null,
+      outcome: null,
+    }
+    : { ...commandFromDone(done), name: 'compact' }
+  return {
+    command: fallbackCommand,
+    checkpoint,
+    ...summary === undefined ? {} : { summary },
+  }
+}
+
+/**
+ * Fold shared compaction evidence into a Definition-owned State.
+ * @param state - current business State carrying optional compaction evidence.
+ * @param match - next compaction lifecycle Match.
+ * @returns adopted State, preserving reference identity when the Match adds no evidence.
+ */
+export function updateCompactionState<State extends CompactionEvidence>(
+  state: State,
+  match: ConversationMatch,
+): State {
+  if ((match.event.type as string) === 'compact/summary') return { ...state, summary: match }
+  if (compactSource(match.event) !== undefined) return { ...state, checkpoint: match }
+  return state
+}
+
+/** Slash-command lifecycle, including integrated manual compaction, Definition. */
+export const commandDefinition: ConversationNodeDefinition<CommandState> = {
+  kind: 'command',
+  match: (event) => {
+    if ((event.type as string) === 'command/run') {
+      return { id: String((event.data as unknown as CommandRunData).commandId), role: 'start' }
+    }
+    if ((event.type as string) === 'command/done') {
+      return { id: String((event.data as unknown as CommandDoneData).commandId), role: 'update' }
+    }
+    const checkpoint = compactSource(event)
+    if (checkpoint?.sourceCommandId !== undefined) {
+      return { id: String(checkpoint.sourceCommandId), role: 'update' }
+    }
+    if ((event.type as string) === 'compact/start'
+      || (event.type as string) === 'compact/summary'
+      || (event.type as string) === 'compact/end') {
+      const data = event.data as unknown as { sourceCommandId?: CommandId }
+      if (data.sourceCommandId !== undefined) return { id: String(data.sourceCommandId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => ({ command: commandFromRun(match) }),
+  update: (context, match) => {
+    if ((match.event.type as string) === 'command/done') {
+      return { ...context.state, command: commandFromDone(match, context.state.command) }
+    }
+    return updateCompactionState(context.state, match)
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state === undefined) return null
+    if (state.command.name !== 'compact') {
+      return chatNode(context, 'command', state.command.seq, state.command)
+    }
+    const compaction = state.checkpoint === undefined
+      ? null
+      : compactSummary(state.summary, state.checkpoint)
+    const data: ManualCompactionChatData = { command: state.command, compaction }
+    return chatNode(context, 'manual-compaction', compaction?.seq ?? state.command.seq, data)
+  },
+}
+
+/**
+ * Register the command lifecycle business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerCommandConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(commandDefinition)
+}
+
+/** Shared structural checkpoint recognizer for automatic compaction. */
+export { compactSource, compactSummary }
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/common.ts b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
new file mode 100644
index 0000000000..8e1d9d7bd4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
@@ -0,0 +1,55 @@
+import type {
+  ConversationLocation, ConversationNodeContext,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ChatNode, ChatNodeDataMap, ChatNodeKind,
+} from '../contract/chat-nodes.ts'
+
+/**
+ * Resolve one Context's best currently loaded event Location.
+ * @param context - assembled business Context.
+ * @returns start or first-match Location, otherwise unresolved.
+ */
+export function contextLocation(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+/**
+ * Build one final Chat target Node with the engine-owned stable key.
+ * @param context - assembled business Context.
+ * @param kind - Chat renderer dispatch key.
+ * @param anchorSeq - sortable render position.
+ * @param data - renderer-owned payload.
+ * @param options - optional Location and visibility overrides.
+ * @returns final Chat view Node.
+ */
+export function chatNode<Kind extends ChatNodeKind>(
+  context: ConversationNodeContext,
+  kind: Kind,
+  anchorSeq: number,
+  data: ChatNodeDataMap[Kind],
+  options: {
+    readonly location?: ConversationLocation
+    readonly visibility?: 'visible' | 'hidden'
+  } = {},
+): ChatNode<Kind> {
+  return {
+    key: context.key,
+    kind,
+    id: context.id,
+    target: 'chat',
+    anchorSeq,
+    location: options.location ?? contextLocation(context),
+    visibility: options.visibility ?? 'visible',
+    data,
+  }
+}
+
+/**
+ * Read a finite non-negative integer from a structurally narrowed payload.
+ * @param value - untrusted payload field.
+ * @returns valid coordinate, otherwise undefined.
+ */
+export function coordinate(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
new file mode 100644
index 0000000000..0742ab6539
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
@@ -0,0 +1,63 @@
+import type { Context } from 'cordis'
+import type {
+  CompactionSummaryNode, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { chatNode } from './common.ts'
+import { compactSource, compactSummary, updateCompactionState } from './command.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Automatic compaction checkpoint marker. */
+    compaction: CompactionSummaryNode
+  }
+}
+
+interface CompactionState {
+  readonly summary?: ConversationMatch
+  readonly checkpoint?: ConversationMatch
+}
+
+function fallbackState(context: ConversationNodeContext<CompactionState>): CompactionState {
+  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
+  return {
+    ...summary === undefined ? {} : { summary },
+    ...checkpoint === undefined ? {} : { checkpoint },
+  }
+}
+
+/** Automatic compaction lifecycle and landed checkpoint Definition. */
+export const compactionDefinition: ConversationNodeDefinition<CompactionState> = {
+  kind: 'compaction',
+  match: (event) => {
+    const checkpoint = compactSource(event)
+    if (checkpoint !== undefined && checkpoint.sourceCommandId === undefined) {
+      return { id: checkpoint.compactionId, role: 'update' }
+    }
+    if ((event.type as string) === 'compact/start'
+      || (event.type as string) === 'compact/summary'
+      || (event.type as string) === 'compact/end') {
+      const data = event.data as unknown as { compactionId?: unknown; sourceCommandId?: unknown }
+      if (typeof data.compactionId !== 'string' || data.sourceCommandId !== undefined) return null
+      return { id: data.compactionId, role: (event.type as string) === 'compact/start' ? 'start' : 'update' }
+    }
+    return null
+  },
+  start: () => ({}),
+  update: (context, match) => updateCompactionState(context.state, match),
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state.checkpoint === undefined) return null
+    const marker = compactSummary(state.summary, state.checkpoint)
+    return chatNode(context, 'compaction', marker.seq, marker)
+  },
+}
+
+/**
+ * Register the automatic-compaction business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerCompactionConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(compactionDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts b/packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts
new file mode 100644
index 0000000000..a93fc8fdd4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts
@@ -0,0 +1,40 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationNodeDefinition, UnknownSurfaceNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Generic presentation of an unclaimed append-surface event. */
+    unknown: UnknownSurfaceNode
+  }
+}
+
+/** Unclaimed append-surface fallback Definition. */
+export const unknownFallbackDefinition: ConversationNodeDefinition<UnknownSurfaceNode> = {
+  kind: 'unknown-surface',
+  match: event => isAppendSurfaceEvent(event)
+    ? { id: String(event.seq), role: 'start' }
+    : null,
+  start: (_context, match) => ({
+    kind: 'unknown',
+    seq: match.event.seq,
+    time: match.event.time,
+    type: match.event.type,
+    data: match.event.data,
+  }),
+  update: context => context.state,
+  buildViewNode: (context, target) => target !== 'chat' || context.state === undefined
+    ? null
+    : chatNode(context, 'unknown', context.state.seq, context.state),
+}
+
+/**
+ * Register the unmatched append-surface fallback contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerUnknownConversationFallback(ctx: Context): void {
+  ctx.conversationEvents.registerFallback(unknownFallbackDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
new file mode 100644
index 0000000000..092bcaaa59
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
@@ -0,0 +1,71 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationNodeDefinition, ConversationPreviousContext,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+type InboxTarget = 'next-turn' | 'next-step'
+
+interface InboxIdentity {
+  readonly id: string
+}
+
+interface InboxSplice {
+  readonly target: InboxTarget
+  readonly start: number
+  readonly removedCount?: number
+  readonly inserted: readonly InboxIdentity[]
+  readonly outcome?: 'canceled'
+}
+
+/** Cumulative state after one durable inbox splice. */
+export interface InboxState {
+  readonly pending: readonly InboxIdentity[]
+  readonly claimed: ReadonlySet<string>
+}
+
+function applySplice(
+  previous: ConversationPreviousContext<InboxState> | undefined,
+  splice: InboxSplice,
+): InboxState {
+  const pending = [...(previous?.state.pending ?? [])]
+  const claimed = new Set(previous?.state.claimed ?? [])
+  const removed = pending.splice(splice.start, splice.removedCount ?? 0, ...splice.inserted)
+  for (const identity of splice.inserted) claimed.delete(identity.id)
+  if (splice.target === 'next-step' && splice.outcome !== 'canceled') {
+    for (const identity of removed) claimed.add(identity.id)
+  }
+  return { pending, claimed }
+}
+
+function inboxDefinition(target: InboxTarget): ConversationNodeDefinition<InboxState> {
+  const kind = `inbox-${target}`
+  return {
+    kind,
+    match: event => (event.type as string) === 'agent/inbox/spliced'
+      && (event.data as unknown as { target?: unknown }).target === target
+      ? { id: String(event.seq), role: 'start' }
+      : null,
+    start: (_context, match, reader) => applySplice(
+      reader.previous<InboxState>(kind),
+      match.event.data as unknown as InboxSplice,
+    ),
+    update: context => context.state,
+    publication: () => 'none',
+    buildViewNode: () => null,
+  }
+}
+
+/** Cumulative next-turn inbox splice Definition. */
+export const nextTurnInboxDefinition = inboxDefinition('next-turn')
+
+/** Cumulative next-step inbox splice Definition used to classify steering. */
+export const nextStepInboxDefinition = inboxDefinition('next-step')
+
+/**
+ * Register the two durable Inbox-state contributions.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerInboxConversationNodes(ctx: Context): void {
+  ctx.conversationEvents.register(nextTurnInboxDefinition)
+  ctx.conversationEvents.register(nextStepInboxDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/message.ts b/packages/client/ui-conversation/src/client/conversation-nodes/message.ts
new file mode 100644
index 0000000000..91300944d7
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/message.ts
@@ -0,0 +1,83 @@
+import type { Context } from 'cordis'
+import type {
+  ContextMessageNode, ConversationNodeDefinition, SteeringMessageNode, UserMessageNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  contextForm, contextProvenance, isAppendSurfaceEvent, isReplacementSurfaceEvent,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { InboxState } from './inbox.ts'
+import { chatNode } from './common.ts'
+
+type MessageNode = UserMessageNode | SteeringMessageNode | ContextMessageNode
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Ordinary turn-opening user message. */
+    user: UserMessageNode
+    /** User message admitted into an active turn. */
+    steering: SteeringMessageNode
+    /** Non-user context injected into model history. */
+    context: ContextMessageNode
+  }
+}
+
+function isCompactionCheckpoint(event: Parameters<ConversationNodeDefinition['match']>[0]): boolean {
+  if (event.type !== 'user/message' || !isReplacementSurfaceEvent(event)) return false
+  const source = event.data.source
+  return source.kind === 'plugin' && source.plugin === 'compact'
+}
+
+/** User, steering, and injected-context message classification Definition. */
+export const messageDefinition: ConversationNodeDefinition<MessageNode> = {
+  kind: 'input-message',
+  match: event => event.type === 'user/message'
+    && isAppendSurfaceEvent(event)
+    && !isCompactionCheckpoint(event)
+    ? { id: String(event.data.id), role: 'start' }
+    : null,
+  start: (_context, match, reader) => {
+    if (match.event.type !== 'user/message') throw new Error('input-message start requires user/message')
+    const event = match.event
+    if (event.data.source.kind !== 'user') {
+      return {
+        kind: 'context',
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+        provenance: contextProvenance(event.data.source),
+        form: contextForm(event.data.source),
+      }
+    }
+    const claimed = reader.previous<InboxState>('inbox-next-step')?.state.claimed.has(String(event.data.id)) === true
+    return claimed
+      ? {
+        kind: 'steering',
+        messageId: event.data.id,
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+      }
+      : {
+        kind: 'user',
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+      }
+  },
+  update: context => context.state,
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined) return null
+    return chatNode(context, context.state.kind, context.state.seq, context.state)
+  },
+}
+
+/**
+ * Register the user, steering, and injected-context message contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerMessageConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(messageDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/register.ts b/packages/client/ui-conversation/src/client/conversation-nodes/register.ts
new file mode 100644
index 0000000000..9102b1f2f4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/register.ts
@@ -0,0 +1,30 @@
+import type { Context } from 'cordis'
+import { registerAssistantConversationNode } from './assistant.ts'
+import { registerChatConversationView } from './chat-snapshot-builder.ts'
+import { registerCommandConversationNode } from './command.ts'
+import { registerCompactionConversationNode } from './compaction.ts'
+import { registerUnknownConversationFallback } from './fallback.ts'
+import { registerInboxConversationNodes } from './inbox.ts'
+import { registerMessageConversationNode } from './message.ts'
+import { registerRetryConversationNode } from './retry.ts'
+import { registerToolConversationNode } from './tool.ts'
+import { registerTurnErrorConversationNode } from './turn-error.ts'
+import { registerTurnTailConversationNode } from './turn-tail.ts'
+
+/**
+ * Register the Chat business Definitions and target builder contributed by this package.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerConversationNodes(ctx: Context): void {
+  registerInboxConversationNodes(ctx)
+  registerMessageConversationNode(ctx)
+  registerAssistantConversationNode(ctx)
+  registerToolConversationNode(ctx)
+  registerCommandConversationNode(ctx)
+  registerCompactionConversationNode(ctx)
+  registerRetryConversationNode(ctx)
+  registerTurnErrorConversationNode(ctx)
+  registerTurnTailConversationNode(ctx)
+  registerUnknownConversationFallback(ctx)
+  registerChatConversationView(ctx)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
new file mode 100644
index 0000000000..fe95c0052d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -0,0 +1,116 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationLocation, ConversationNodeDefinition, ModelRetryNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { RetryChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Producer-correlated model retry chain. */
+    'model-retry': RetryChatData
+  }
+}
+
+type WithoutRetryProjection<Node> = Node extends unknown
+  ? Omit<Node, 'kind' | 'seq' | 'time' | 'retryState'>
+  : never
+type RetryEventData = WithoutRetryProjection<ModelRetryNode>
+
+/** Accumulated retry attempts sharing one producer-owned RetryId. */
+export interface RetryState {
+  readonly turn: number
+  readonly step: number
+  readonly attempts: readonly ModelRetryNode[]
+}
+
+function retryData(value: unknown): RetryEventData | undefined {
+  if (value === null || typeof value !== 'object') return undefined
+  const data = value as Record<string, unknown>
+  if (typeof data.retryId !== 'string' || data.retryId === ''
+    || !Number.isSafeInteger(data.turn) || (data.turn as number) < 0
+    || !Number.isSafeInteger(data.step) || (data.step as number) < 0
+    || !Number.isSafeInteger(data.retry) || (data.retry as number) <= 0
+    || typeof data.delayMs !== 'number' || !Number.isFinite(data.delayMs) || data.delayMs < 0
+    || typeof data.provider !== 'string' || typeof data.policyKey !== 'string'
+    || (data.mode !== 'normal' && data.mode !== 'always')
+    || data.failure === null || typeof data.failure !== 'object') return undefined
+  if (data.mode === 'normal' && (!Number.isSafeInteger(data.maxRetries) || (data.maxRetries as number) <= 0)) {
+    return undefined
+  }
+  return data as unknown as RetryEventData
+}
+
+function scheduledNode(event: { seq: number; time: number; data: unknown }): ModelRetryNode | undefined {
+  const data = retryData(event.data)
+  return data === undefined ? undefined : {
+    kind: 'model-retry',
+    seq: event.seq,
+    time: event.time,
+    retryState: 'scheduled',
+    ...data,
+  }
+}
+
+function isClosed(location: ConversationLocation): boolean {
+  return (location.kind === 'step' && location.step.status === 'closed')
+    || ((location.kind === 'step' || location.kind === 'turn') && location.turn.status === 'closed')
+}
+
+/** Producer-correlated model retry chain Definition. */
+export const retryDefinition: ConversationNodeDefinition<RetryState> = {
+  kind: 'model-retry',
+  match: (event) => {
+    if ((event.type as string) === 'llm/retry') {
+      const data = retryData(event.data)
+      if (data === undefined) return null
+      return { id: String(data.retryId), role: data.retry === 1 ? 'start' : 'update' }
+    }
+    if ((event.type as string) === 'llm/retry-started') {
+      const data = event.data as unknown as { retryId?: unknown }
+      return typeof data.retryId === 'string' ? { id: data.retryId, role: 'update' } : null
+    }
+    return null
+  },
+  start: (_context, match) => {
+    const node = scheduledNode(match.event)
+    if (node === undefined) throw new Error('model-retry start requires a valid llm/retry event')
+    return { turn: node.turn, step: node.step, attempts: [node] }
+  },
+  update: (context, match) => {
+    if ((match.event.type as string) === 'llm/retry') {
+      const node = scheduledNode(match.event)
+      return node === undefined ? context.state : { ...context.state, attempts: [...context.state.attempts, node] }
+    }
+    if ((match.event.type as string) !== 'llm/retry-started') return context.state
+    const data = match.event.data as unknown as { retry: number }
+    return {
+      ...context.state,
+      attempts: context.state.attempts.map(attempt =>
+        attempt.retry === data.retry ? { ...attempt, retryState: 'started' } : attempt),
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined || context.state.attempts.length === 0) return null
+    const location = context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' as const }
+    const stateAttempts = context.state.attempts
+    const attempts = stateAttempts.map((attempt, index) =>
+      index === stateAttempts.length - 1
+        && attempt.retryState === 'scheduled'
+        && isClosed(location)
+        ? { ...attempt, retryState: 'cancelled' as const }
+        : attempt)
+    const current = attempts.at(-1)
+    if (current === undefined) return null
+    const data: RetryChatData = { attempts, current }
+    return chatNode(context, 'model-retry', attempts[0]?.seq ?? current.seq, data)
+  },
+}
+
+/**
+ * Register the correlated model-retry business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerRetryConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(retryDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
new file mode 100644
index 0000000000..04a5770f5a
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -0,0 +1,271 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationMatch, ConversationNodeContext, ConversationNodeDefinition,
+  RunningToolCall, ToolCallBlock, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Root Tool lifecycle with recursively nested subcalls. */
+    'tool-call': ToolChatData
+  }
+}
+
+const MAX_DEPTH = 256
+
+interface ToolState {
+  readonly root: ToolCallBlock
+  readonly children: ReadonlyMap<string, readonly ToolCallBlock[]>
+  readonly parents: ReadonlyMap<string, string>
+}
+
+interface ProjectedBlockCache {
+  readonly children: readonly ToolCallBlock[]
+  readonly interruptionSeq: number | undefined
+  readonly interruptionTime: number | undefined
+  readonly value: ToolCallBlock
+}
+
+const projectedBlocks = new WeakMap<ToolCallBlock, ProjectedBlockCache>()
+
+function jsonArguments(value: unknown): string {
+  return JSON.stringify(value)
+}
+
+function rootCall(match: ConversationMatch): RunningToolCall {
+  if (match.event.type !== 'tool/call') throw new Error('tool-call start requires tool/call')
+  return {
+    callId: String(match.event.data.callId),
+    name: match.event.data.name,
+    argsRaw: match.event.data.arguments,
+    turn: match.event.data.turn,
+    step: match.event.data.step,
+    time: match.event.time,
+    callView: match.view?.for === 'call' ? match.view.view : null,
+    subCalls: [],
+  }
+}
+
+function rootResult(match: ConversationMatch, previous?: RunningToolCall): ToolResultNode | undefined {
+  if (match.event.type !== 'tool/result') return undefined
+  const result = match.event.data.message.content[0]
+  return {
+    kind: 'tool-result',
+    seq: match.event.seq,
+    time: match.event.time,
+    callId: String(match.event.data.message.source.callId),
+    call: previous === undefined ? null : { name: previous.name, argsRaw: previous.argsRaw },
+    callTime: previous?.time ?? null,
+    content: result.content,
+    isError: result.isError === true,
+    ...match.event.data.error === undefined ? {} : { error: match.event.data.error },
+    meta: match.event.data.meta,
+    callView: previous?.callView ?? null,
+    resultView: match.view?.for === 'result' ? match.view.view : null,
+    subCalls: [],
+  }
+}
+
+interface DispatchData {
+  readonly parentCallId: string
+  readonly subCallId: string
+  readonly name: string
+  readonly arguments: unknown
+  readonly isError?: boolean
+  readonly content?: ToolResultNode['content']
+}
+
+function childCall(match: ConversationMatch, data: DispatchData): RunningToolCall {
+  return {
+    callId: data.subCallId,
+    name: data.name,
+    argsRaw: jsonArguments(data.arguments),
+    turn: locationTurn(match),
+    step: locationStep(match),
+    time: match.event.time,
+    callView: null,
+    subCalls: [],
+  }
+}
+
+function childResult(match: ConversationMatch, data: DispatchData, previous?: ToolCallBlock): ToolResultNode {
+  return {
+    kind: 'tool-result',
+    seq: match.event.seq,
+    time: match.event.time,
+    callId: data.subCallId,
+    call: { name: data.name, argsRaw: jsonArguments(data.arguments) },
+    callTime: previous?.time ?? null,
+    content: data.content ?? [],
+    isError: data.isError === true,
+    callView: null,
+    resultView: null,
+    subCalls: [],
+  }
+}
+
+function locationTurn(match: ConversationMatch): number {
+  return match.location.kind === 'step' || match.location.kind === 'turn' ? match.location.turn.turn : 0
+}
+
+function locationStep(match: ConversationMatch): number {
+  return match.location.kind === 'step' ? match.location.step.step : 0
+}
+
+function acceptsEdge(state: ToolState, parent: string, child: string): boolean {
+  if (parent === child || state.parents.has(child)) return false
+  let cursor: string | undefined = parent
+  let parentDepth = 0
+  const ancestors = new Set<string>()
+  while (cursor !== undefined) {
+    if (cursor === child || ancestors.has(cursor)) return false
+    ancestors.add(cursor)
+    parentDepth++
+    cursor = state.parents.get(cursor)
+  }
+  const pending = [{ callId: child, depth: 1 }]
+  const descendants = new Set<string>()
+  let subtreeDepth = 0
+  for (const candidate of pending) {
+    if (descendants.has(candidate.callId)) return false
+    descendants.add(candidate.callId)
+    subtreeDepth = Math.max(subtreeDepth, candidate.depth)
+    for (const nested of state.children.get(candidate.callId) ?? []) {
+      pending.push({ callId: nested.callId, depth: candidate.depth + 1 })
+    }
+  }
+  return parentDepth + subtreeDepth <= MAX_DEPTH
+}
+
+function updateDispatch(state: ToolState, match: ConversationMatch): ToolState {
+  const data = match.event.data as unknown as DispatchData
+  const siblings = state.children.get(data.parentCallId) ?? []
+  const index = siblings.findIndex(candidate => candidate.callId === data.subCallId)
+  if ((match.event.type as string) === 'tool/code-dispatch-start') {
+    if (index >= 0 || !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+    const children = new Map(state.children)
+    children.set(data.parentCallId, [...siblings, childCall(match, data)])
+    const parents = new Map(state.parents)
+    parents.set(data.subCallId, data.parentCallId)
+    return { ...state, children, parents }
+  }
+  if ((match.event.type as string) !== 'tool/code-dispatch') return state
+  if (index < 0 && !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+  const previous = index < 0 ? undefined : siblings[index]
+  const settled = childResult(match, data, previous)
+  const children = new Map(state.children)
+  children.set(data.parentCallId, index < 0
+    ? [...siblings, settled]
+    : siblings.map((child, at) => at === index ? settled : child))
+  const parents = new Map(state.parents)
+  if (index < 0) parents.set(data.subCallId, data.parentCallId)
+  return { ...state, children, parents }
+}
+
+function projectBlock(
+  block: ToolCallBlock,
+  state: ToolState,
+  interruptedAt: { seq: number; time: number } | undefined,
+  visited = new Set<string>(),
+  depth = 1,
+): ToolCallBlock {
+  if (visited.has(block.callId) || depth > MAX_DEPTH) return { ...block, subCalls: [] }
+  const nextVisited = new Set(visited)
+  nextVisited.add(block.callId)
+  const children = (state.children.get(block.callId) ?? block.subCalls)
+    .map(child => projectBlock(child, state, interruptedAt, nextVisited, depth + 1))
+  const interruptionSeq = 'kind' in block ? undefined : interruptedAt?.seq
+  const interruptionTime = 'kind' in block ? undefined : interruptedAt?.time
+  const cached = projectedBlocks.get(block)
+  if (cached !== undefined
+    && cached.interruptionSeq === interruptionSeq
+    && cached.interruptionTime === interruptionTime
+    && sameReferences(cached.children, children)) {
+    return cached.value
+  }
+  const projected: ToolCallBlock = 'kind' in block || interruptedAt === undefined
+    ? sameReferences(block.subCalls, children) ? block : { ...block, subCalls: children }
+    : {
+      kind: 'tool-result',
+      seq: interruptedAt.seq - 0.8,
+      time: interruptedAt.time,
+      callId: block.callId,
+      call: { name: block.name, argsRaw: block.argsRaw },
+      callTime: block.time,
+      content: [],
+      isError: true,
+      error: { name: 'Interrupted', code: 'interrupted' },
+      callView: block.callView,
+      resultView: null,
+      subCalls: children,
+    }
+  projectedBlocks.set(block, { children, interruptionSeq, interruptionTime, value: projected })
+  return projected
+}
+
+function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function interruption(context: ConversationNodeContext<ToolState>): { seq: number; time: number } | undefined {
+  const location = context.start?.location
+  if (location?.kind === 'step' && location.step.status === 'closed') return location.step.end
+  if ((location?.kind === 'step' || location?.kind === 'turn') && location.turn.status === 'closed') {
+    return location.turn.end
+  }
+  return undefined
+}
+
+function fallbackState(context: ConversationNodeContext<ToolState>): ToolState | undefined {
+  const match = context.matches.find(candidate => candidate.event.type === 'tool/result')
+  const root = match === undefined ? undefined : rootResult(match)
+  if (root === undefined) return undefined
+  let state: ToolState = { root, children: new Map(), parents: new Map() }
+  for (const candidate of context.matches) state = updateDispatch(state, candidate)
+  return state
+}
+
+/** Root Tool lifecycle and nested Code Dispatch Definition. */
+export const toolDefinition: ConversationNodeDefinition<ToolState> = {
+  kind: 'tool-call',
+  match: (event) => {
+    if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+    if (event.type === 'tool/result' && isAppendSurfaceEvent(event)) {
+      return { id: String(event.data.message.source.callId), role: 'update' }
+    }
+    if ((event.type as string) === 'tool/code-dispatch-start' || (event.type as string) === 'tool/code-dispatch') {
+      const data = event.data as unknown as { rootCallId: string }
+      return { id: data.rootCallId, role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => ({ root: rootCall(match), children: new Map(), parents: new Map() }),
+  update: (context, match) => {
+    if (match.event.type === 'tool/result') {
+      const running = 'kind' in context.state.root ? undefined : context.state.root
+      const result = rootResult(match, running)
+      return result === undefined ? context.state : { ...context.state, root: result }
+    }
+    return updateDispatch(context.state, match)
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state === undefined) return null
+    const projected = projectBlock(state.root, state, interruption(context))
+    const anchor = context.start?.event.seq
+      ?? ('kind' in state.root ? state.root.seq : context.matches[0]?.event.seq ?? 0)
+    return chatNode(context, 'tool-call', anchor, { root: projected } satisfies ToolChatData)
+  },
+}
+
+/**
+ * Register the root Tool lifecycle and nested-subcall contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerToolConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(toolDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
new file mode 100644
index 0000000000..58725d8723
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
@@ -0,0 +1,112 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnErrorNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { displayFailureMessage } from '@deepseek-ai/dsh-client-runtime/client'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Terminal turn failure not superseded by retry. */
+    'turn-error': TurnErrorNode
+  }
+}
+
+interface TurnErrorState {
+  readonly turn: number
+  readonly hidden: boolean
+  readonly failure?: {
+    readonly seq: number
+    readonly time: number
+    readonly message: string
+    readonly code?: string
+  }
+}
+
+function lastStep(context: ConversationNodeContext<TurnErrorState>): number {
+  const location = context.start?.location ?? context.matches[0]?.location
+  if (location?.kind !== 'turn' && location?.kind !== 'step') return 0
+  return location.turn.steps.at(-1)?.step ?? 0
+}
+
+function retryTurn(event: Parameters<ConversationNodeDefinition['match']>[0]): number | undefined {
+  if ((event.type as string) !== 'llm/retry' && (event.type as string) !== 'llm/retry-started') return undefined
+  const turn = (event.data as unknown as { turn?: unknown }).turn
+  return Number.isSafeInteger(turn) && (turn as number) >= 0 ? turn as number : undefined
+}
+
+function failureFrom(match: ConversationMatch): TurnErrorState['failure'] | undefined {
+  if (match.event.type !== 'turn/end' || match.event.data.reason.kind !== 'error') return undefined
+  const failure = match.event.data.reason.error
+  return {
+    seq: match.event.seq,
+    time: match.event.time,
+    message: displayFailureMessage(failure),
+    code: failure.code,
+  }
+}
+
+function fallbackState(context: ConversationNodeContext<TurnErrorState>): TurnErrorState | undefined {
+  const end = context.matches.find(match => failureFrom(match) !== undefined)
+  if (end?.event.type !== 'turn/end') return undefined
+  const failure = failureFrom(end)
+  if (failure === undefined) return undefined
+  const turn = end.event.data.turn
+  return {
+    turn,
+    hidden: context.matches.some(match => retryTurn(match.event) === turn),
+    failure,
+  }
+}
+
+/** Terminal turn failure Definition, suppressed when the turn owns a retry chain. */
+export const turnErrorDefinition: ConversationNodeDefinition<TurnErrorState> = {
+  kind: 'turn-error',
+  match: (event) => {
+    if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
+    if (event.type === 'turn/end' && event.data.reason.kind === 'error') {
+      return { id: String(event.data.turn), role: 'update' }
+    }
+    const turn = retryTurn(event)
+    return turn === undefined ? null : { id: String(turn), role: 'update' }
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'turn/start') throw new Error('turn-error start requires turn/start')
+    return { turn: match.event.data.turn, hidden: false }
+  },
+  update: (context, match) => {
+    const failure = failureFrom(match)
+    if (failure !== undefined) return { ...context.state, failure }
+    return retryTurn(match.event) === context.state.turn
+      ? { ...context.state, hidden: true }
+      : context.state
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state?.failure === undefined) return null
+    const failure = state.failure
+    const node: TurnErrorNode = {
+      kind: 'turn-error',
+      seq: failure.seq,
+      time: failure.time,
+      turn: state.turn,
+      step: lastStep(context),
+      message: failure.message,
+      ...failure.code === undefined ? {} : { code: failure.code },
+    }
+    if (!state.hidden) return chatNode(context, 'turn-error', node.seq, node)
+    const current = context.current.get('chat')
+    return current === undefined || current === null
+      ? null
+      : chatNode(context, 'turn-error', node.seq, node, { visibility: 'hidden' })
+  },
+}
+
+/**
+ * Register the terminal Turn-error business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerTurnErrorConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(turnErrorDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
new file mode 100644
index 0000000000..2a842a005d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -0,0 +1,180 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnLocation,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent, toAssistantBlocks } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  AssistantChatData, FinalAssistantChatData, TurnTailChatData,
+} from '../contract/chat-nodes.ts'
+import { deriveTurnMetrics } from '../chat/turn-metrics.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Completed-turn actions and extension tail. */
+    'turn-tail': TurnTailChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationTurnDataMap {
+    /** Closing Assistant and footer facts derived for this completed Turn. */
+    'turn-tail': TurnTailChatData
+  }
+}
+
+interface TurnTailState {
+  readonly turn: number
+  readonly end?: ConversationMatch
+}
+
+interface StepEvidence {
+  readonly streamedText: boolean
+  readonly finalized: boolean
+}
+
+function hasTextAssistant(event: Parameters<ConversationNodeDefinition['match']>[0]): boolean {
+  return event.type === 'assistant/message'
+    && isAppendSurfaceEvent(event)
+    && toAssistantBlocks(event.data.message.content)
+      .some(block => block.kind === 'text' && block.text.trim() !== '')
+}
+
+function chunkHasText(event: Parameters<ConversationNodeDefinition['match']>[0]): boolean {
+  if (event.type !== 'assistant/chunk') return false
+  const chunk = event.data.chunk
+  if (chunk.type === 'text-delta') return chunk.text.trim() !== ''
+  return chunk.type === 'block-end'
+    && chunk.block.type === 'text'
+    && chunk.block.text.trim() !== ''
+}
+
+function turnCoordinates(event: Parameters<ConversationNodeDefinition['match']>[0]): {
+  readonly turn: number
+  readonly step?: number
+} | undefined {
+  if (event.type === 'assistant/message'
+    || event.type === 'assistant/chunk'
+    || event.type === 'step/end') {
+    return { turn: event.data.turn, step: event.data.step }
+  }
+  if ((event.type as string) === 'llm/retry') {
+    return event.data as unknown as { turn: number; step: number }
+  }
+  return undefined
+}
+
+function closingAnchor(context: ConversationNodeContext<TurnTailState>): number {
+  let anchor = context.matches.find(match => match.event.type === 'turn/end')?.event.seq
+    ?? context.start?.event.seq
+    ?? context.matches[0]?.event.seq
+    ?? 0
+  const steps = new Map<number, StepEvidence>()
+  for (const match of context.matches) {
+    const event = match.event
+    if (event.type === 'turn/end') continue
+    const coordinates = turnCoordinates(event)
+    if (coordinates?.step === undefined) continue
+    const previous = steps.get(coordinates.step) ?? { streamedText: false, finalized: false }
+    if (event.type === 'assistant/chunk') {
+      steps.set(coordinates.step, {
+        ...previous,
+        streamedText: previous.streamedText || chunkHasText(event),
+      })
+      continue
+    }
+    if (event.type === 'assistant/message') {
+      steps.set(coordinates.step, { streamedText: false, finalized: true })
+      if (hasTextAssistant(event)) anchor = event.seq + 0.1
+      continue
+    }
+    if ((event.type as string) === 'llm/retry') {
+      steps.set(coordinates.step, { streamedText: false, finalized: false })
+      continue
+    }
+    if (event.type === 'step/end' && previous.streamedText && !previous.finalized) {
+      anchor = event.seq - 0.8
+    }
+  }
+  return anchor
+}
+
+function turnLocation(context: ConversationNodeContext<TurnTailState>): TurnLocation | undefined {
+  const location = context.start?.location ?? context.matches[0]?.location
+  return location?.kind === 'turn' || location?.kind === 'step' ? location.turn : undefined
+}
+
+function hasText(data: AssistantChatData): data is FinalAssistantChatData {
+  return data.finalNode !== undefined
+    && data.blocks.some(block => block.kind === 'text' && block.text.trim() !== '')
+}
+
+function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChatData | null {
+  const end = context.state?.end
+    ?? context.matches.find(match => match.event.type === 'turn/end')
+  if (end?.event.type !== 'turn/end') return null
+  const turn = turnLocation(context)
+  if (turn === undefined) return null
+  const assistants = turn.steps
+    .map(step => step.data.get('assistant-step'))
+    .filter((candidate): candidate is Readonly<AssistantChatData> => candidate !== undefined)
+  const finalized = assistants
+    .filter((candidate): candidate is Readonly<FinalAssistantChatData> => candidate.finalNode !== undefined)
+    .sort((left, right) => left.finalNode.seq - right.finalNode.seq)
+  const closing = finalized.findLast(hasText) ?? null
+  const latest = finalized.at(-1)
+  const metrics = deriveTurnMetrics(finalized.map(candidate => candidate.finalNode)).get(end.event.data.turn)
+  return {
+    turn: end.event.data.turn,
+    seq: end.event.seq,
+    time: end.event.time,
+    closing,
+    branchUnavailable: closing === null || latest?.finalNode.seq !== closing.finalNode.seq,
+    ...metrics?.ttftMs === undefined ? {} : { ttftMs: metrics.ttftMs },
+    ...metrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: metrics.tokensPerSecond },
+  }
+}
+
+/** Completed-turn footer Definition independent of any Assistant row. */
+export const turnTailDefinition: ConversationNodeDefinition<TurnTailState> = {
+  kind: 'turn-tail',
+  match: (event) => {
+    if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
+    if (event.type === 'turn/end') return { id: String(event.data.turn), role: 'update' }
+    const coordinates = turnCoordinates(event)
+    if (coordinates !== undefined) return { id: String(coordinates.turn), role: 'update' }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'turn/start') throw new Error('turn-tail start requires turn/start')
+    return { turn: match.event.data.turn }
+  },
+  update: (context, match) => match.event.type === 'turn/end'
+    ? { ...context.state, end: match }
+    : context.state,
+  publication: match => match.event.type === 'turn/end' ? 'immediate' : 'none',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'turn') return null
+    const value = tailData(context)
+    return value === null ? null : {
+      kind: 'turn',
+      turn: value.turn,
+      key: 'turn-tail',
+      value,
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const turn = turnLocation(context)
+    const data = turn?.data.get('turn-tail')
+    return data === undefined ? null : chatNode(context, 'turn-tail', closingAnchor(context), data)
+  },
+}
+
+/**
+ * Register completed-Turn footer data and its Chat node contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerTurnTailConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(turnTailDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index a19cd77753..b4d7467170 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -5,6 +5,17 @@
  */
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
+export { registerAssistantConversationNode } from './conversation-nodes/assistant.ts'
+export { registerChatConversationView } from './conversation-nodes/chat-snapshot-builder.ts'
+export { registerCommandConversationNode } from './conversation-nodes/command.ts'
+export { registerCompactionConversationNode } from './conversation-nodes/compaction.ts'
+export { registerUnknownConversationFallback } from './conversation-nodes/fallback.ts'
+export { registerInboxConversationNodes } from './conversation-nodes/inbox.ts'
+export { registerMessageConversationNode } from './conversation-nodes/message.ts'
+export { registerRetryConversationNode } from './conversation-nodes/retry.ts'
+export { registerToolConversationNode } from './conversation-nodes/tool.ts'
+export { registerTurnErrorConversationNode } from './conversation-nodes/turn-error.ts'
+export { registerTurnTailConversationNode } from './conversation-nodes/turn-tail.ts'
 export type { IConversation } from './service.ts'
 
 export type {
@@ -12,12 +23,16 @@ export type {
 } from './contract/views.ts'
 export type { ConversationKey } from './locales.ts'
 export type {
-  ChatFileMentions,
+  AssistantChatData, ChatNode, ChatNodeDataMap, ChatNodeKind, ManualCompactionChatData,
+  RetryChatData, ToolChatData, TurnTailChatData,
+} from './contract/chat-nodes.ts'
+export type {
+  ChatFileMentions, ChatNodeOwnerProps, ChatNodeViewProps,
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
   ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps,
   ConvViewProps, DetailsInjected, DetailsSlotProps, DetailsToolOwnerProps, EmptyWorkspaceOwnerProps,
-  ToolTreeOwnerProps, TurnTailOwnerProps,
+  TurnTailOwnerProps, UseChatNodeTurnData,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
index a1a0a120f5..98e98f0f01 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
@@ -17,6 +17,7 @@ import { useMemo, useState } from 'react'
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { RunningToolCall } from '@deepseek-ai/dsh-client-runtime/client'
 import { PendingApproval, type ApprovalComposerProps } from '../contract/slots.ts'
+import { rootToolCall } from '../chat/tool-node-reader.ts'
 import css from './ApprovalPanel.module.css'
 
 /** Extract the shell command from an approval's paired running call (bash-family args carry `command`); undefined hides the line. */
@@ -40,8 +41,12 @@ export function commandOf(call: RunningToolCall | undefined): string | undefined
  */
 export function ApprovalPanel(props: ApprovalComposerProps) {
   const approval = useMemo(() => new PendingApproval(props.matched), [props.matched])
-  const command = props.useSession(s => commandOf(
-    approval.callId === undefined ? undefined : s.runningCalls.find(call => call.callId === approval.callId)))
+  const command = props.useSession((snapshot) => {
+    if (approval.callId === undefined) return undefined
+    const root = rootToolCall(snapshot, approval.callId)
+    if (root === undefined) return undefined
+    return root.callId === approval.callId && !('kind' in root) ? commandOf(root) : undefined
+  })
   return <ApprovalFlow key={approval.key} pending={approval} t={props.t} {...command === undefined ? {} : { command }} />
 }
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index a04e9ba9e8..1caefd2ecf 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -12,6 +12,7 @@ import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { DetailsSlotProps } from '../contract/slots.ts'
+import { findToolCall } from '../chat/tool-node-reader.ts'
 import css from './DetailsPanel.module.css'
 
 /** Full props composed by reference from the contract (automatic shares & injected share). */
@@ -40,30 +41,10 @@ function runningMaterial(call: RunningToolCall): CallMaterial {
   return { name: call.name, argsRaw: call.argsRaw, block: call }
 }
 
-function findCall(block: ToolCallBlock, callId: string): ToolCallBlock | undefined {
-  if (block.callId === callId) return block
-  for (const child of block.subCalls) {
-    const found = findCall(child, callId)
-    if (found !== undefined) return found
-  }
-  return undefined
-}
-
 function materialFor(s: ConversationSnapshot, callId: string): CallMaterial | null {
-  for (const node of s.nodes) {
-    if (node.kind !== 'tool-result') continue
-    const found = findCall(node, callId)
-    if (found !== undefined) {
-      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
-    }
-  }
-  for (const root of s.runningCalls) {
-    const found = findCall(root, callId)
-    if (found !== undefined) {
-      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
-    }
-  }
-  return null
+  const found = findToolCall(s, callId)
+  if (found === undefined) return null
+  return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
 }
 
 function pretty(raw: string): string {
diff --git a/packages/client/ui-conversation/src/invariant.ts b/packages/client/ui-conversation/src/invariant.ts
index f9a7d46553..66c54081ab 100644
--- a/packages/client/ui-conversation/src/invariant.ts
+++ b/packages/client/ui-conversation/src/invariant.ts
@@ -17,7 +17,7 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: the conversation service emits no cordis events, and
  * both rings this package owns (the 'conversation.view' tab ring and the
- * 'conversation.chat.tool' whole-call seat) ride the slot system, whose ledger
+ * 'conversation.chat.node' business renderer seat) ride the slot system, whose ledger
  * invariants live with the runtime slots package.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 81b2f61b79..fb8bdd0224 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -12,7 +12,9 @@ import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/c
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
-import { producedFileMentions, selectProducedFiles } from './turn-deliverables.ts'
+import {
+  deliverablesDefinition, producedFileMentions, selectProducedFiles,
+} from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -25,13 +27,14 @@ export { ProducedFiles, type ProducedFilesProps } from './ProducedFiles.tsx'
 export { producedForClosing } from './turn-deliverables.ts'
 
 /** Required services for the tail-slot registration and its dictionaries. */
-export const inject = ['slots', 'locale']
+export const inject = ['slots', 'locale', 'conversationEvents']
 
 /**
  * Client plugin body: register the dictionaries and the turn-tail entry.
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(deliverablesDefinition)
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-deliverables: dictionaries')
   ctx.slots.inject(
     'conversation.chat.turnTail',
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index 4316ddf8e6..0227b34261 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -1,12 +1,37 @@
 /**
- * Pure derivation of one turn's produced files from finalized snapshot
- * nodes. Client-only and model-free: the vocabulary is the mutation tools'
- * own follow-along `locations`, never the closing prose.
+ * Turn-scoped produced-file Definition and readers. Client-only and
+ * model-free: the vocabulary is the mutation tools' own follow-along
+ * `locations`, never the closing prose.
  */
-import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationNodeDefinition, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
+interface ProducedPath {
+  readonly seq: number
+  readonly path: string
+}
+
+/** Immutable produced-file facts published against one Turn. */
+export interface DeliverablesTurnData {
+  readonly produced: readonly ProducedPath[]
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationTurnDataMap {
+    /** Successful mutation paths accumulated in this Turn. */
+    deliverables: DeliverablesTurnData
+  }
+}
+
+interface DeliverablesState extends DeliverablesTurnData {
+  readonly turn: number
+  readonly calls: ReadonlyMap<string, ToolResultNode['callView']>
+}
+
 /**
  * Paths a call view reports having created or changed, by render intent rather
  * than tool name: a diff card, or a generic card whose kind is `edit` (the
@@ -23,9 +48,7 @@ function producedPaths(view: ToolResultNode['callView']): readonly string[] {
 }
 
 /**
- * Files produced by the turn the assistant at `seq` closes — the anchor the
- * render site elects, so the row lands under the message that reports the
- * work rather than after some mid-turn narration.
+ * Files produced by one Turn data value.
  *
  * The source is the mutation tools' own follow-along `locations`, not the
  * closing prose: a produced file must be listed whether or not the model
@@ -37,46 +60,26 @@ function producedPaths(view: ToolResultNode['callView']): readonly string[] {
  * failed calls. Paths keep first-seen order and appear once, so a file written
  * and then edited in the same turn is one entry.
  *
- * Accumulation resets on the turn boundary — a user message, or a node
- * reporting a different turn number — so a turn that mutates files and then
- * ends without content text cannot spill its paths into the next turn's row,
- * nor leave the dedup set suppressing a file the next turn legitimately
- * rewrites. Tool results carry no turn of their own; the boundary is read off
- * the nodes that do, and a user message resets the tracked turn to undefined
- * because the next node to report one is stating the current turn, not
- * entering a new one.
- * @param nodes - snapshot nodes (surface order).
- * @param seq - the closing assistant's seq (the render site's anchor).
+ * The Conversation Location index owns turn membership before this function
+ * runs, so paths cannot spill across turns and this derivation does not infer
+ * boundaries from neighboring presentation Nodes.
+ * @param data - engine-published Deliverables data for one Turn.
+ * @param seq - closing Assistant seq; later Tool settlements are excluded.
  * @returns Produced paths in first-seen order; empty when the turn wrote nothing.
  */
-export function producedForClosing(nodes: readonly ConversationNode[], seq: number): readonly string[] {
-  let pending: string[] = []
-  let seen = new Set<string>()
-  let turn: number | undefined
-  for (const node of nodes) {
-    if (node.kind === 'tool-result') {
-      if (node.isError) continue
-      for (const path of producedPaths(node.callView)) {
-        if (seen.has(path)) continue
-        seen.add(path)
-        pending.push(path)
-      }
-      continue
-    }
-    if (node.kind === 'user') {
-      turn = undefined
-      pending = []
-      seen = new Set()
-    } else if ('turn' in node) {
-      if (turn !== undefined && node.turn !== turn) {
-        pending = []
-        seen = new Set()
-      }
-      turn = node.turn
-    }
-    if (node.kind === 'assistant' && node.seq === seq) return pending
+export function producedForClosing(
+  data: Readonly<DeliverablesTurnData> | undefined,
+  seq = Number.POSITIVE_INFINITY,
+): readonly string[] {
+  if (data === undefined) return []
+  const paths: string[] = []
+  const seen = new Set<string>()
+  for (const produced of data.produced) {
+    if (produced.seq > seq || seen.has(produced.path)) continue
+    seen.add(produced.path)
+    paths.push(produced.path)
   }
-  return []
+  return paths
 }
 
 /**
@@ -85,11 +88,55 @@ export function producedForClosing(nodes: readonly ConversationNode[], seq: numb
  * @returns Produced paths as the component's match, or null to decline before mount.
  */
 export function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[] | null {
-  const { nodes, seq } = owner
-  const paths = producedForClosing(nodes, seq)
+  const paths = producedForClosing(owner.turn.data.get('deliverables'), owner.seq)
   return paths.length === 0 ? null : paths
 }
 
+/** Turn-local successful mutation accumulator; it publishes no view Node. */
+export const deliverablesDefinition: ConversationNodeDefinition<DeliverablesState> = {
+  kind: 'deliverables',
+  match: (event) => {
+    if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
+    if (event.type === 'tool/call') return { id: String(event.data.turn), role: 'update' }
+    if (event.type === 'tool/result' && isAppendSurfaceEvent(event)) {
+      return { id: String(event.data.turn), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'turn/start') throw new Error('deliverables start requires turn/start')
+    return { turn: match.event.data.turn, calls: new Map(), produced: [] }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'tool/call') {
+      const calls = new Map(context.state.calls)
+      calls.set(
+        String(match.event.data.callId),
+        match.view?.for === 'call' ? match.view.view : null,
+      )
+      return { ...context.state, calls }
+    }
+    if (match.event.type !== 'tool/result') return context.state
+    const result = match.event.data.message.content[0]
+    if (result.isError === true) return context.state
+    const callId = String(match.event.data.message.source.callId)
+    const additions = producedPaths(context.state.calls.get(callId) ?? null)
+      .map(path => ({ seq: match.event.seq, path }))
+    return additions.length === 0
+      ? context.state
+      : { ...context.state, produced: [...context.state.produced, ...additions] }
+  },
+  buildLocationData: (context, scope) => scope !== 'turn' || context.state === undefined
+    ? null
+    : {
+      kind: 'turn',
+      turn: context.state.turn,
+      key: 'deliverables',
+      value: { produced: context.state.produced },
+    },
+  buildViewNode: () => null,
+}
+
 /**
  * Trailing path segment, the part that identifies the file at a glance.
  * @param path - Slash- or backslash-separated path.
diff --git a/packages/client/ui-tool/src/client/apply.ts b/packages/client/ui-tool/src/client/apply.ts
index 48a9a4c812..ec2f0b8ec1 100644
--- a/packages/client/ui-tool/src/client/apply.ts
+++ b/packages/client/ui-tool/src/client/apply.ts
@@ -20,8 +20,9 @@ export const inject = ['slots']
  * @param ctx - Client root context.
  */
 export function apply(ctx: ClientContext): void {
-  ctx.slots.inject('conversation.chat.tool', () => ctx.slots.register({
-    name: 'conversation.chat.tool',
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'tool-call',
     locale: NS,
     children: {
       'tool.call.toolview': { kind: 'keyed', scope: 'session' },
diff --git a/packages/client/ui-tool/src/client/contract/slots.ts b/packages/client/ui-tool/src/client/contract/slots.ts
index 4b74055b2c..26039efc6f 100644
--- a/packages/client/ui-tool/src/client/contract/slots.ts
+++ b/packages/client/ui-tool/src/client/contract/slots.ts
@@ -30,8 +30,8 @@ export interface ToolCallOwnerProps {
 /** Full props of a registered atomic Tool view. */
 export type ToolCallViewProps = PropsRuntime<'tool.call.toolview'>
 
-/** Full props of the Tool call-tree renderer registered into the chat flow. */
-export type ToolTreeProps = PropsRuntime<'conversation.chat.tool'>
+/** Full props of the Tool call-tree renderer registered as a `tool-call` Chat Node. */
+export type ToolTreeProps = PropsRuntime<'conversation.chat.node', 'tool-call'>
   & PropsRenderSlots<'tool.call.toolview'>
   & PropsLocale<'conversation'>
 
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index 278be7dacf..db3ed0af06 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -88,8 +88,9 @@ const ToolCallBranch = memo(function ToolCallBranch({
  * @returns the Tool call tree.
  */
 export function ToolCallTree({
-  renderSlot, block, selectedCallId, cwd, openFile, inspectCall, t,
+  renderSlot, node, selectedCallId, cwd, openFile, inspectCall, t,
 }: ToolTreeProps) {
+  const block = node.data.root
   return (
     <ToolCallBranch
       renderSlot={renderSlot}

From 522acc74324e6c529f4a9a18e2c6781d0b88b6be Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:56 +0800
Subject: [PATCH 235/262] test: update conversation assembly coverage and docs

---
 ...7-19-gui-web-client-architecture.i18n.yaml |   4 +-
 .../2026-07-19-gui-web-client-architecture.md |  27 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  29 +-
 ...ient-tool-presentation-ownership.i18n.yaml |   4 +-
 ...8-08-client-tool-presentation-ownership.md | 101 +-
 ...8-client-tool-presentation-ownership.zh.md | 103 +-
 ...ranscript-log-ordered-projection.i18n.yaml |   4 +-
 ...0-web-transcript-log-ordered-projection.md |   2 +-
 ...eb-transcript-log-ordered-projection.zh.md |   2 +-
 apps/web/tests/built-boot.snapshot.ts         |   1 -
 .../tests/chat-continuous-conversation.e2e.ts |  20 +-
 apps/web/tests/chat-long-interactions.e2e.ts  |  49 +-
 apps/web/tests/search-card.snapshot.ts        |   4 +-
 apps/web/tests/seeded-history.e2e.ts          |  17 +-
 apps/web/tests/skill-user-invoke.e2e.ts       |   2 +
 .../snapshots/code-mode-round/session.jsonl   |   8 +-
 apps/web/tests/todo-row.snapshot.ts           |   2 +-
 docs/config-catalog.md                        |   4 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/module-graph.md                          | 249 ++---
 docs/persistence-catalog.md                   |  54 +-
 docs/subsystems/commands.i18n.yaml            |   4 +-
 docs/subsystems/commands.md                   |   6 +-
 docs/subsystems/commands.zh.md                |   6 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |  11 +-
 docs/subsystems/compaction.zh.md              |  11 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |   9 +-
 docs/subsystems/tools.zh.md                   |   9 +-
 .../advanced-toolchain/session.jsonl          |   4 +-
 .../snapshots/both-mode-turn/session.jsonl    |   4 +-
 .../snapshots/code-mode-turn/session.jsonl    |   8 +-
 .../code-mode-workspace-context/session.jsonl |   4 +-
 .../cordis-inspect-jsdoc/session.jsonl        |   2 +-
 .../empty-response-retry/session.jsonl        |  19 +-
 .../advanced-toolchain/session.jsonl          |   4 +-
 .../stream-json.expected.jsonl                |   4 +-
 .../compaction-recovery/session.jsonl         |  20 +-
 .../stream-json.expected.jsonl                |   8 +-
 .../provider-retry/stream-json.expected.jsonl |  19 +-
 packages/bash/bash-env/tests/bash-env.spec.ts |   1 +
 .../client/connection/src/client/fixture.ts   |  48 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |  10 +-
 packages/client/runtime/README.zh.md          |  10 +-
 .../client/runtime/tests/client-apply.spec.ts |  29 +-
 .../tests/compact-checkpoint-pin.spec.ts      |  52 -
 .../tests/conversation-assembler.spec.ts      | 892 ++++++++++++++++++
 .../tests/conversation-registry.spec.ts       | 126 +++
 packages/client/runtime/tests/event-script.ts |   4 +-
 .../client/runtime/tests/queue-store.spec.ts  |   1 -
 packages/client/runtime/tests/session.spec.ts | 808 ++++------------
 .../runtime/tests/transcript-adapter.spec.ts  | 567 -----------
 packages/client/test-runtime/src/fixtures.ts  |   2 +
 packages/client/test-runtime/src/index.ts     |   8 +-
 .../ui-conversation/tests/chat-apply.spec.tsx |  10 +-
 .../tests/chat-branch-tails.spec.tsx          | 161 ++--
 .../tests/chat-snapshot-fixture.ts            | 295 ++++++
 .../ui-conversation/tests/chat-stats.spec.tsx |  28 +-
 .../ui-conversation/tests/chat-view.spec.tsx  | 487 ++++------
 .../conversation-node-definitions.spec.ts     | 720 ++++++++++++++
 .../tests/gate-branch-tails.spec.tsx          |  20 +-
 .../ui-conversation/tests/input-bar.spec.tsx  |   5 +-
 .../tests/input-matrix.spec.tsx               |   5 +-
 .../tests/input-scenarios.spec.tsx            |   5 +-
 .../ui-conversation/tests/queue-dock.spec.tsx |   4 +-
 .../ui-conversation/tests/skeleton.spec.tsx   |   5 +-
 .../tests/produced-files.spec.tsx             | 284 ++++--
 .../client/ui-slots/tests/surface.spec.ts     |  11 +
 .../client/ui-slots/tests/type-chain.spec.tsx |  60 +-
 .../ui-tool/tests/assembly-surfaces.spec.tsx  |   3 +-
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  10 +-
 .../client/ui-tool/tests/diff-card.spec.tsx   |   7 +-
 .../client/ui-tool/tests/read-card.spec.tsx   |   7 +-
 .../client/ui-tool/tests/search-card.spec.tsx |   7 +-
 .../ui-tool/tests/terminal-card.spec.tsx      |   7 +-
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  15 +-
 .../ui-tool/tests/tool-details-render.tsx     |  45 +-
 .../ui-tool/tests/toolview-slot.spec.tsx      |   3 +-
 .../client/ui-tool/tests/web-card.spec.tsx    |   7 +-
 .../web-react/tests/scoped-slots.spec.tsx     |  77 +-
 .../tests/command-compact.spec.ts             |  24 +-
 .../tests/loader-composition.spec.ts          |  30 +-
 .../compact-basic/tests/compact-basic.spec.ts |   8 +-
 .../tests/manual-compact.spec.ts              |  47 +-
 .../compact/compact/tests/compact.spec.ts     |  15 +-
 .../compact/compact/tests/invariant.spec.ts   | 194 +++-
 .../tests/workspace-context.spec.ts           |   6 +-
 packages/core/tools/tests/code-mode.spec.ts   |   5 +-
 packages/core/tools/tests/invariant.spec.ts   | 105 ++-
 .../agent-spine-demo/tests/agent-core.spec.ts |   1 +
 .../llm/llm-retry/tests/invariant.spec.ts     |  73 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |   2 +
 packages/llm/llm-retry/tests/retry.spec.ts    |   2 +
 .../context-breakdown-projection.spec.ts      |   2 +
 .../tests/token-usage-projection.spec.ts      |   2 +
 .../tool-cordis/src/api-catalog.ts            |  16 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  16 +-
 pnpm-lock.yaml                                |  18 +-
 scripts/gen-cordis-catalog.ts                 |   1 +
 101 files changed, 3970 insertions(+), 2295 deletions(-)
 delete mode 100644 packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
 create mode 100644 packages/client/runtime/tests/conversation-assembler.spec.ts
 create mode 100644 packages/client/runtime/tests/conversation-registry.spec.ts
 delete mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
 create mode 100644 packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index b7e331c934..f0cc648a10 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 7567ac3cb8b1a580e145f8f0da49b6ec371a35bd
-2026-07-19-gui-web-client-architecture.zh.md: 9b682febf1bd1aad1a767b8b2db4e83dd993cf2f
+2026-07-19-gui-web-client-architecture.md: 5e927405e9012b5a56d82da8fcf600ca4aa1bd5b
+2026-07-19-gui-web-client-architecture.zh.md: 4294af099dce4e1345e625694a054661483f8d12
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 7567ac3cb8..5e927405e9 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,35 +44,35 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: Runtime projects Code Dispatch topology into each root's recursive `subCalls`; ui-conversation places that ordered root into the single `'conversation.chat.tool'` seat without interpreting Tool names or topology; ui-tool renders the supplied tree and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
+There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components. The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
 ## The data object layer (`packages/client/runtime/src/client/sessions/`)
 
-Frames enter, snapshots exit, the projection sits between — React-free (zero React imports, grep-assertable):
+Frames enter, snapshots exit, the Conversation assembler sits between — React-free (zero React imports, grep-assertable):
 
 ```
-mux/host 帧（ConnectionController 泵入，sinks 注入）
+mux/host frames (ConnectionController pump, injected sinks)
         │
         ▼
 SessionManager.handleMuxEnvelope / handleHostEnvelope
-        │ 带 sessionId 的帧只投已存在实例（审批/问答 requested 例外：进 pendingBuffers 缓冲）
+        │ session frames target existing instances (requested waits buffer)
         ▼
-Session.handleMuxEnvelope ──► events 窗口（seq 连续升序）
-        │                        │ 定稿事件            │ chunk
-        │                        ▼                    ▼
-        │                TranscriptAdapter     PartialAccumulator
-        │                  （→ nodes）          （→ partial）
+Session.handleMuxEnvelope ──► contiguous Event window
+        │                        │ replace / prepend / append
+        │                        ▼
+        │                ConversationNodeAssembler
+        │                  Definitions -> Contexts -> view builders
         ▼
 Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件
 ```
 
 - **Session** (session.ts): lazily built, resident — once created it keeps eating frames in the background, so switching away and back renders instantly. Operations: `prompt`/`cancel` (RPC passthrough; failures land in the snapshot's `promptError`), `open` (pull the tail history page, idempotent), `loadOlder` (upward paging, reentry-guarded), `resync` (reconnect = clear the window and rerun open). Subscription: `subscribe`/`getSnapshot` (always the cached reference) — `implements ObservableSnapshot<ConversationSnapshot>`, with `useSelector = bindSnapshotSelector(this)` attached at construction, so a Session is directly a uSES source. Frame dispatch is one switch: `session/event` frames dedup by seq (the only dedup key), buffer while open is in flight, otherwise append + incremental projection; open/stitch merges the live buffer by seq and backfills once if `subscribed.lastSeq` outruns the window tail.
-- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (the human transcript, log-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; an unchanged nodes projection keeps the same array reference, while a changed flow returns a new array that reuses unchanged element references; unchanged substructures reuse the previous snapshot's references.
+- **ConversationSnapshot** (conversation.ts): the top-level immutable snapshot contract. `chat` contains structural `order`, an identity-stable keyed Node reader, Turn/Step indexes, and the timeline; `nodes`, `partial`, `runningCalls`, `turnTimings`, and `turnEnds` are the compatibility slice for unmigrated Trajectory consumers. Pending interactions, queue, running, removal, open state, paging, and prompt errors remain Session facts. **Reference discipline** (the premise of memo and uSES): unchanged substructures and Node values keep their references; one business update replaces only the corresponding key's value unless its order or Location changes. React still subscribes to the Session as the sole observable source, while the framework-provided `useSession(selector)` isolates Node and Location aggregate updates.
 - **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation.
 - **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned.
-- **TranscriptAdapter / PartialAccumulator**: the transcript is the append-origin surface projected in log order (`isAppendSurfaceEvent` from `@deepseek-ai/dsh-session/surface`) plus one marker per landed compaction checkpoint — never the model surface, which shadows replaced ranges and would erase conversation the reader already saw. Node order is seq-monotonic by construction, so there is no core `seq === index` assertion to satisfy and no degradation branch. Chunks contribute no node (O(1) skip): the accumulator folds StreamChunks into `AssistantBlock[]`, a delta swapping only that block's reference, and the finalizing message discards the accumulator in the same batch (no flicker on promotion). Cost model: one chunk = one string concatenation + a dirty mark; an unsubscribed Session under a frame storm costs only the mark.
+- **ConversationNodeAssembler** (`runtime/src/client/conversation/`): the Session-owned incremental engine runs independently registered Definitions over raw events. `match(event)` selects `(kind, id)` without Context scans; start/update build Definition state; engine-computed Locations carry Turn/Step closure; backward Context reads record dependencies repaired by later prepends; `buildViewNode(target)` materializes only dirty Contexts. The Chat builder preserves structural order and per-key value identity, `useSession` selectors isolate consumption, and Assistant token publication coalesces to one animation frame. The [Conversation Node decision](2026-08-09-client-conversation-node-assembly.md) owns assembly, while [Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) owns recursive Tool rendering.
 - **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; Web carriage uses HTTP POST for the two client→server quadrants and [one WebSocket per logical stream](2026-08-04-websocket-downlink-carrier.md) for the two server→client quadrants, while the client class family remains the layering RFC's territory.
 
 ## The React face (`packages/client/web-react`)
@@ -95,6 +95,7 @@ src/client/
   contract/    shared slot and cross-domain types
   service.ts   cross-domain orchestration
   skeleton/    conversation shell and details host
+  conversation-nodes/ independently registered business Definitions and Chat builder
   chat/        ordered conversation view
   input/       composer state machine
   queue/       queued-message presentation
@@ -109,13 +110,13 @@ Domain implementation files never import a sibling domain; shared surfaces route
 
 - **A new UI feature** = a new plugin package: declare `dshClient` (+ `inject` topology) in package.json, write the browser half under `src/client/` (apply mounts services/stores and registers slots), keep the node half an empty apply unless there is host logic, build with the shared preset. Add the plugin to the host config; the manifest and loading follow automatically.
 - **A new slot**: see the [slot system standard RFC](2026-07-22-slot-type-chain-implementation.md) — merge the contract into `SlotMap`, declare it in the parent entry's `children`, render through the auto-injected `renderSlot` prop. Never export components globally.
-- **Consuming a new frame type**: sessionId-bearing → a branch in Session's dispatch switch; host-level → the Manager routing table; if the UI needs it, a `ConversationSnapshot` field with the reference discipline kept.
+- **Consuming a new frame type**: transport-only session frames → Session's dispatch switch; host-level frames → the Manager routing table; logged conversation business events → a Definition plus a keyed view renderer, without a Session business branch.
 - **Where does this state live**: business data (events, streaming, pending) → always the object layer; what the parent knows → owner props at the renderSlot site; private to one component (scroll, search text, expansion) → component state; shared across entries or surviving remounts (selection, drafts, panel widths) → an entry-declared store ([slot system standard](2026-07-22-slot-type-chain-implementation.md)).
 - **Notification channel**: frame-driven/async = `markDirty` batching; direct user-gesture echo whose controlled input needs the same tick = `notifyNow`.
 
 ## Consequences
 
-Token streams no longer shake the render tree: a frame storm costs unsubscribed sessions one dirty bit and the subscribed view one batched re-render per microtask (raf-batched for frame-driven stores). UI features load, fail, and get disabled as independent plugins — one crashing slot entry blacks out one card, one failed bundle fails loud before the UI flips in. The accepted costs: the loader/module-table machinery is bespoke infrastructure the team owns end to end; the one-flip boot (no progressive rendering) trades first-paint granularity for assembly simplicity; and the dual type programs make "which aggregate sees this file" a question developers occasionally have to answer.
+Token streams no longer shake the render tree: Assistant chunks update one business Context and publish its keyed Node at most once per animation frame; unrelated rows' selector results retain their references, so those rows do not re-render. UI features load, fail, and get disabled as independent plugins — one crashing slot entry blacks out one card, one failed bundle fails loud before the UI flips in. The accepted costs: the loader/module-table machinery is bespoke infrastructure the team owns end to end; the one-flip boot (no progressive rendering) trades first-paint granularity for assembly simplicity; and the dual type programs make "which aggregate sees this file" a question developers occasionally have to answer.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 9b682febf1..4294af099d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,35 +44,35 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装约定）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种组件注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。最终 Chat 业务 Node 通过 keyed/session `'conversation.chat.node'` slot 分发；ui-tool 拥有其中的 `tool-call` entry，递归渲染传入的 `subCalls`，并声明 keyed/session `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托 selected call 的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。与 target 无关的事件和 view registry 是数据组装缝，不是平行组件注册表（[决策](2026-08-09-client-conversation-node-assembly.md)）。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
 ## 数据对象层（`packages/client/runtime/src/client/sessions/`）
 
-帧从这里进、快照从这里出、fold 坐在中间——React-free（零 React import，grep 可断言）：
+帧从这里进、快照从这里出、Conversation assembler 坐在中间——React-free（零 React import，grep 可断言）：
 
 ```
-mux/host 帧（ConnectionController 泵入，sinks 注入）
+mux/host frames (ConnectionController pump, injected sinks)
         │
         ▼
 SessionManager.handleMuxEnvelope / handleHostEnvelope
-        │ 带 sessionId 的帧只投已存在实例（审批/问答 requested 例外：进 pendingBuffers 缓冲）
+        │ session frames target existing instances (requested waits buffer)
         ▼
-Session.handleMuxEnvelope ──► events 窗口（seq 连续升序）
-        │                        │ 定稿事件            │ chunk
-        │                        ▼                    ▼
-        │                TranscriptAdapter     PartialAccumulator
-        │                  （→ nodes）          （→ partial）
+Session.handleMuxEnvelope ──► contiguous Event window
+        │                        │ replace / prepend / append
+        │                        ▼
+        │                ConversationNodeAssembler
+        │                  Definitions -> Contexts -> view builders
         ▼
 Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件
 ```
 
 - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
-- **ConversationSnapshot**（conversation.ts）：不可变快照约定——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
+- **ConversationSnapshot**（conversation.ts）：顶层不可变快照契约。`chat` 包含结构化 `order`、identity 稳定的 keyed Node reader、Turn/Step index 和 timeline；`nodes`、`partial`、`runningCalls`、`turnTimings`、`turnEnds` 是未迁移 Trajectory 消费者使用的兼容 slice。pending interaction、queue、running、removed、open state、paging 和 prompt error 仍是 Session 信息。**引用纪律**（memo 与 uSES 的前提）：未变化的子结构和 Node value 保持引用；单个业务更新只替换对应 key 的 value，除非它的顺序或 Location 发生变化。React 仍只订阅 Session 这一处 observable source，并由框架提供的 `useSession(selector)` 隔离 Node 与 Location 聚合更新。
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
-- **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
+- **ConversationNodeAssembler**（`runtime/src/client/conversation/`）：Session 拥有的增量引擎在原始事件上运行各自独立注册的 Definition。`match(event)` 无须扫描 Context 即可选出 `(kind, id)`；start/update 构造 Definition state；引擎计算的 Location 携带 Turn/Step 关闭信息；向前查询 Context 时记录依赖，并由后续 prepend 修复；`buildViewNode(target)` 只物化 dirty Context。Chat builder 保留结构顺序和 per-key value identity，`useSession` selector 负责消费隔离，Assistant token 发布则合并到每个 animation frame 一次。[Conversation Node 决策](2026-08-09-client-conversation-node-assembly.md)拥有组装边界，[Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)拥有 Tool 递归渲染。
 - **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层 RFC 属地。
 
 ## React 面（`packages/client/web-react`）
@@ -95,6 +95,7 @@ src/client/
   contract/    shared slot and cross-domain types
   service.ts   cross-domain orchestration
   skeleton/    conversation shell and details host
+  conversation-nodes/ independently registered business Definitions and Chat builder
   chat/        ordered conversation view
   input/       composer state machine
   queue/       queued-message presentation
@@ -108,14 +109,14 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
-- **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
+- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **消费新帧类型**：纯传输 session frame → Session 分发 switch；host 级 frame → Manager 路由表；已记录的 conversation 业务事件 → Definition 加 keyed view renderer，不增加 Session 业务分支。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
 
 ## Consequences
 
-token 流不再震荡渲染树：帧风暴对未订阅会话只花一个脏位，对被订阅视图每微任务一次合批重渲染（帧驱动 store 走 raf 合批）。UI 功能以独立插件的粒度装载、失败、停用——一个崩溃的 slot 注册项只黑一张卡，一个装载失败的 bundle 在 UI 切入之前大声报错。接受的代价：loader/模块表机件是团队端到端自持的定制基建；一次成型启动（无渐进渲染）用首屏粒度换装配简单；双类型 program 让「这个文件归哪个聚合」成为开发者偶尔要回答的问题。
+token 流不再震荡渲染树：Assistant chunk 只更新一个业务 Context，每 animation frame 最多发布一次对应 keyed Node；无关行的 selector 结果保持原引用，因此不会重渲染。UI 功能以独立插件的粒度装载、失败、停用——一个崩溃的 slot 注册项只黑一张卡，一个装载失败的 bundle 在 UI 切入之前大声报错。接受的代价：loader/模块表机件是团队端到端自持的定制基建；一次成型启动（无渐进渲染）用首屏粒度换装配简单；双类型 program 让「这个文件归哪个聚合」成为开发者偶尔要回答的问题。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 12e27bf58c..5cb66115e8 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: f12a116c34064186b6be1496e1071025221817c4
-2026-08-08-client-tool-presentation-ownership.zh.md: f5f7d71f1e05b27855d29acc223b340c8d89f1d8
+2026-08-08-client-tool-presentation-ownership.md: 3feefc3cfbe538024b8610394b9f170c423556e8
+2026-08-08-client-tool-presentation-ownership.zh.md: 031975fdebf5f72a19396f16b086a3abdcbca172
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index f12a116c34..3feefc3cfb 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -6,100 +6,63 @@ English | [中文](2026-08-08-client-tool-presentation-ownership.zh.md)
 
 ## Problem
 
-The Client Runtime already projects Tool calls into a stable lifecycle: it pairs call/result events by `callId`, preserves running and settled forms, and indexes Code Dispatch children by their root call. The chat view nevertheless owned the entire presentation stack. It placed root calls in ChatFlow, composed each root with its subcalls, dispatched every atomic call by Tool name, carried the generic fallback and card models, registered first-party Tool views, and reused those models in the details panel.
+Client Runtime already paired Tool call/result events by `callId` and could recover root/subcall topology from Code Dispatch events, but the Chat view also owned Tool placement in the conversation flow, recursive call-tree composition, Tool-name dispatch, the Generic fallback, card models, and first-party Tool renderers. `ui-conversation` therefore had to interpret every business Tool name; moving individual React components did not change that ownership, and removing atomic renderers left subcalls without a presentation owner.
 
-That ownership made `ui-conversation` interpret business Tool names and made subcalls an orphaned concern if an atomic Tool view moved elsewhere. A business package such as `ui-skill` could register a row, but it still depended on conversation's Tool-specific composition contract. Adding Tool-specific Session projection would duplicate a data model the Runtime already owns, while moving only individual React components would leave the composition and model coupling in place.
+Tool presentation needed an independent owner without adding a second registry beside Client slots or making every atomic Tool renderer understand root/subcall structure.
 
 ## Decision
 
-Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Runtime normalizes Code Dispatch into recursive `ToolCallBlock` values: every root or child owns its next level through `subCalls`, and `ConversationSnapshot` exposes no separate parent-to-children map.
+Tool is a first-class Client UI presentation concept. `@deepseek-ai/dsh-client-ui-tool` owns root/subcall composition, atomic renderer dispatch by wire Tool name, the Generic fallback, card models, and details output. Business plugins register only their atomic Tool renderers and do not modify conversation or Session.
 
-“First-class concept” describes UI ownership only; it adds no Runtime data kind. `ConversationNode` remains the transcript projection, `ChatFlowItem` remains the render unit produced when conversation sorts and groups nodes, `ToolCallBlock` remains the standard data for one call, and `ToolCallTree` only composes root/subcall presentation within Tool. Command continues to render through the separate `'conversation.chat.commandview'` seat and does not become Tool.
+Conversation data assembly follows the later [Conversation business-node decision](2026-08-09-client-conversation-node-assembly.md). The `ui-conversation` Tool Definition pairs root call/result Session Events, folds Code Dispatch edges into recursive `ToolCallBlock.subCalls`, and emits one stable `tool-call` Chat Node. This data responsibility handles only official Tool identity and topology; it does not interpret presentation for concrete Tool names.
 
-`ui-conversation` owns ordered placement. `deriveChatFlow()` still decides where a settled Tool group appears, and `ChatView` still appends running calls, maintains scroll anchors and selection, and supplies host actions. For each root call it renders the single/session `'conversation.chat.tool'` seat with the root block, selected call id, session cwd, and open-file/inspect callbacks. It does not read Code Dispatch children, branch on Tool names, or import Tool-specific views and card models.
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) only places generic [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) entries in Chat snapshot `order`. A Seat dispatches `'conversation.chat.node'` by `node.kind`; [`ui-tool`](../../../../packages/client/ui-tool/src/client/apply.ts) registers the `tool-call` entry, and [`ToolCallTree`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx) recursively traverses the root block. Every root or child level dispatches through the same keyed/session `'tool.call.toolview'` child slot with `entryKey: toolName`, falling back to `GenericToolCard` when no registration exists.
 
-`ui-tool` occupies that whole-Tool seat. `ToolCallTree` recursively walks the root block's `subCalls` and routes every level through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. It neither reads Session nor maintains a second call topology.
+A business Tool plugin receives one standard `ToolCallBlock`, identity, workspace cwd, and host actions; it does not read Session, Context, or the Conversation assembler. Skill remains an ordinary Tool and uses the same keyed-slot registration path as other business Tools.
 
-Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this slot. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
-
-The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
-
-The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation contract, and this package boundary adds no Tool projector/fold registry.
+The details panel is a second Tool presentation point, not the call-tree owner. `ui-conversation` locates the selected call and delegates its output body through `'conversation.details.tool'`; `ui-tool` reuses the card model, while the conversation fallback retains raw result text when the plugin is absent.
 
 ## Runtime and render path
 
-This boundary starts at the Client's `ConversationSnapshot`; the full render path is:
-
 ```text
-ConversationSnapshot.nodes
-  -> deriveChatFlow()
-  -> settled tool-group positions ----+
-                                      |
-ConversationSnapshot.runningCalls     |
-  -> ChatView flow tail ---------------+-> ToolSeat
-                                           -> conversation.chat.tool
-                                           -> ToolCallTree
-                                                -> root ToolCallBlock
-                                                     `- subCalls[] (recursive)
-                                                          -> tool.call.toolview(entryKey = toolName)
-                                                               |- registered atomic view
-                                                               `- GenericToolCard fallback
+Session Event window
+  -> Tool Definition -> tool-call Chat Node (recursive ToolCallBlock)
+  -> ChatView -> ChatNodeSeat(entryKey = tool-call)
+  -> ToolCallTree
+       -> root/subCalls[] recursion
+       -> tool.call.toolview(entryKey = toolName)
+            |- registered atomic view
+            `- GenericToolCard fallback
 ```
 
-Runtime's [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) privately indexes child lifecycles by parent callId and is shared by the live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) and historical [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) paths. It recursively projects children onto root `ToolCallBlock` values and copies only the owning ancestor path when a child changes. Unchanged siblings, other roots, and snapshot references with no Tool-topology change stay stable so React selectors and memoization can skip unrelated updates. Tool UI consumes this unified tree without repeating call/result pairing, historical replay, or cache indexing.
+## Ownership boundary
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. Selection is passed only to the root containing that call, and `ToolCallTree` then renders recursively within that local tree.
-
-## Code and responsibility boundaries
-
-| Owner | Primary code | Owns | Explicitly does not own |
-|---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, recursive parent/child tree, snapshot structural sharing | Business views selected by Tool name |
-| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts), [`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx), [`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow order, settled groups, running tail, scroll anchors, selection and host actions, whole-Tool seat declaration | subcall composition, `toolName` dispatch, Generic fallback, Tool card models |
-| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts), [`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx), [`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall composition, atomic keyed dispatch, Generic fallback, Tool card models and built-in Tool views | ChatFlow ordering, Session Event fold |
-| Business Tool plugins | [`ui-skill` registration example](../../../../packages/client/ui-skill/src/client/index.ts) | Atomic views for one or more wire Tool names | root/subcall placement and lifecycle pairing |
-| Details path | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx), [`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected-call lookup, card-aware output, and raw fallback | chat call-tree composition |
-
-## Slot and owner contract
-
-A slot declaration also constrains render ownership. The conversation chat entry declares `'conversation.chat.tool'` through `children`, so only `ChatView` places the whole-Tool seat. When `ui-tool` registers that seat, its `children` declares `'tool.call.toolview'`, so only `ToolCallTree` renders the atomic Tool seat. Business plugins register keyed entries only; they neither participate in root/subcall composition nor establish a registry parallel to slots.
-
-The whole seat's `ToolTreeOwnerProps` carries the root `callId`, `toolName`, `ToolCallBlock`, `selectedCallId`, session `cwd`, `openFile(path)`, and `inspectCall(callId)`. `ToolCallTree` converts either a root or child into the same `ToolCallOwnerProps` and narrows inspect to a callback for that call. The atomic owner carries no `ReactNode`, Cordis `Context`, Session service, or projector; a business view consumes only one standard call block and host actions.
-
-The seat filler also preserves the conversation DOM contract on every root and child wrapper: `data-chat-anchor-key="call:<callId>"`, `data-chat-call-id`, and `data-selected="true"` on the selected call. `ChatView` consumes the anchor key to restore prepend/paging position; the Tool owner emits it because it alone composes child wrappers.
-
-Business plugins use one registration shape:
-
-```text
-ctx.slots.inject('tool.call.toolview', () =>
-  ctx.slots.register({
-    name: 'tool.call.toolview',
-    key: '<wire tool name>',
-  }, BusinessToolRow))
-```
-
-`ui-tool`'s [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) registers the whole-Tool renderer, details renderer, and existing built-in atomic views. An existing independent business package can move only its keyed registration, as `ui-skill` does, without changing `ui-conversation` or Session.
-
-## Details path
-
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) locates the selected call recursively in `nodes` and `runningCalls` through their `subCalls`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
+| Owner | Owns | Explicitly does not own |
+|---|---|---|
+| Client Runtime Conversation engine | Context identity, Location, history replay, view Node publication | Tool event meaning, call tree, Tool renderer |
+| `ui-conversation` Tool Definition | call/result pairing, Code Dispatch topology, running/settled/interrupted `ToolCallBlock`, Chat ordering anchor | Tool-name dispatch, card models, recursive React structure |
+| `ui-conversation` Chat view | keyed Node order, scroll anchors, selection, and host actions | Tool lifecycle, subcall composition, atomic Tool renderers |
+| `ui-tool` | root/subcall recursive rendering, atomic keyed dispatch, fallback, card models, and details output | Session Event fold, Chat ordering |
+| Business Tool plugin | atomic renderers for one or more wire Tool names | root/subcall placement, lifecycle pairing, Session projectors |
 
 ## Verification
 
-Test ownership follows production ownership. `ui-conversation` tests install a local whole-Tool seat probe and assert only ChatFlow placement, owner payload, and host contracts such as selection, open-file, and inspect; they do not import `ui-tool` production code or test helpers. `ui-tool` tests mount a real conversation host and verify root/subcall composition, keyed dispatch, generic fallback, concrete Tool UI, and plugin lifecycle.
+`ui-conversation` tests pin the Tool Definition's call/result pairing, Code Dispatch, interruption, and running-to-settled keyed identity without importing production `ui-tool` renderers. `ui-tool` tests mount the real conversation host and pin root/subcall recursion, keyed dispatch, Generic fallback, selection, details, and concrete Tool cards. Assembled Web tests cover the path with both plugins loaded.
 
 ## Alternatives considered
 
-**Keep atomic Tool slots under every conversation view.** Rejected: each view would have to reproduce root/subcall composition, and a Tool registration would be isolated by view even though its business meaning is Tool-wide. A whole-Tool seat preserves view-owned placement while giving the call tree one owner. This supersedes the per-view placement selected by the earlier [toolview dissolution](2026-07-23-toolview-dissolution.md), while retaining its keyed-slot and no-parallel-registry decisions.
+**Keep atomic Tool slots under every conversation view.** Rejected: every view would repeat root/subcall composition and Tool registration would split by view. The whole Tool renderer occupies one business Node slot in a view, while Tool owns atomic dispatch.
 
-**Move only the Tool React components and card models.** Rejected: `ChatView` would still own Tool-name dispatch and Code Dispatch composition, so the dependency would change file paths without changing responsibility.
+**Move only Tool React components and card models.** Rejected: conversation would still dispatch by Tool name and recurse through subcalls, so file movement would not create an ownership boundary.
 
-**Add business-specific Session projectors or folds.** Rejected: ordinary Tool views consume the standard call block already reconstructed by Runtime. A second registry would create two authorities for call identity and historical replay. Only a feature that changes logged topology or lifecycle earns a Runtime-level extension.
+**Create a Tool-specific projector/fold registry.** Rejected: the general Conversation assembler already owns Context identity, history windows, and publication. A second Runtime registry would create two lifecycle authorities.
 
-**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Recursive root/child composition belongs centrally to `ui-tool`'s `ToolCallTree`.
+**Let every atomic Tool renderer recurse through its subcalls.** Rejected: an atomic registrant should understand one Tool call without knowing whether it is a root or child. `ToolCallTree` handles recursive structure once.
 
-**Import `ui-tool` components directly from `ui-conversation`.** Rejected: it would reverse the intended feature direction and make Tool presentation mandatory. Declared slots retain lifecycle ownership, fallback behavior, and independent plugin loading.
+**Let `ui-conversation` import `ui-tool` components directly.** Rejected: this would reverse the feature dependency and make Tool presentation mandatory. Slots preserve independent loading, lifecycle, and fallback behavior.
 
 ## Consequences
 
-`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot contracts; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
+`ui-conversation` no longer depends on presentation for concrete Tool names, and root and subcalls cannot drift onto different dispatch paths. Business packages can independently own atomic Tool renderers; if `ui-tool` is absent, Conversation data assembly remains valid, Chat Nodes use the generic fallback, and details retain raw results.
+
+The cost is an explicit dependency from `ui-tool` on the business Node slot and locale namespace declared by conversation, plus one Tool-specific child slot. Tool Definition remains in `ui-conversation` because this change does not split packages; it can later move through the Conversation registry seam without changing the presentation ownership recorded here.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index f5f7d71f1e..031975fdeb 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -6,100 +6,63 @@ Status: implemented
 
 ## Problem
 
-Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
+Client Runtime 已经按 `callId` 配对 Tool call/result，并能从 Code Dispatch 事件恢复 root/subcall 拓扑，但 Chat view 曾同时拥有 Tool 在对话流中的放置、递归调用树、按 Tool 名称分发、Generic fallback、card model 和第一方 Tool renderer。`ui-conversation` 因此必须解释每个业务 Tool 名称；只移动单个 React 组件不会改变这层所有权，移走原子 renderer 后 subcall 也会成为无主逻辑。
 
-这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排约定。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+Tool presentation 需要一个独立所有者，同时不能建立与 Client slot 平行的第二套注册表，也不能让每个原子 Tool renderer 自己理解 root/subcall 结构。
 
 ## Decision
 
-Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Runtime 将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
+Tool 是 Client UI 的一级展示概念，由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有 root/subcall 编排、按 wire Tool name 的原子 renderer 分发、Generic fallback、card model 和 details output。业务插件只注册自己的原子 Tool renderer，不修改 conversation 或 Session。
 
-这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
+Conversation 数据组装遵循后续的 [Conversation 业务节点决策](2026-08-09-client-conversation-node-assembly.md)。`ui-conversation` 的 Tool Definition 从 Session Event 配对 root call/result，把 Code Dispatch edge fold 成递归 `ToolCallBlock.subCalls`，并生成一个稳定的 `tool-call` Chat Node；这里的数据职责只处理官方 Tool identity 和拓扑，不解释具体 Tool 名称的展示。
 
-`ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只按 Chat snapshot 的 `order` 放置通用 [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx)。Seat 以 `node.kind` 分发 `'conversation.chat.node'`；[`ui-tool`](../../../../packages/client/ui-tool/src/client/apply.ts) 注册 `tool-call` entry，并由 [`ToolCallTree`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx) 递归遍历 root block。每一层 root 或 child 都通过同一个 keyed/session `'tool.call.toolview'` 子 slot 以 `entryKey: toolName` 分发，缺少注册时渲染 `GenericToolCard`。
 
-`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
+业务 Tool 插件接收一个标准 `ToolCallBlock`、identity、workspace cwd 和宿主动作，不读取 Session、Context 或 Conversation assembler。Skill 仍是普通 Tool；它和其他业务 Tool 使用同一 keyed slot 注册路径。
 
-业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 slot 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 定位 selected call，并通过 `'conversation.details.tool'` 委托 output body；`ui-tool` 复用 card model，插件缺席时 conversation fallback 保留 raw result text。
 
-details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
-
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示约定，这个包边界不会增加 Tool projector/fold registry。
-
-## Runtime 与渲染链路
-
-这项边界从 Client 的 `ConversationSnapshot` 开始，完整渲染链路如下：
+## Runtime and render path
 
 ```text
-ConversationSnapshot.nodes
-  -> deriveChatFlow()
-  -> settled tool-group positions ----+
-                                      |
-ConversationSnapshot.runningCalls     |
-  -> ChatView flow tail ---------------+-> ToolSeat
-                                           -> conversation.chat.tool
-                                           -> ToolCallTree
-                                                -> root ToolCallBlock
-                                                     `- subCalls[] (recursive)
-                                                          -> tool.call.toolview(entryKey = toolName)
-                                                               |- registered atomic view
-                                                               `- GenericToolCard fallback
+Session Event window
+  -> Tool Definition -> tool-call Chat Node (recursive ToolCallBlock)
+  -> ChatView -> ChatNodeSeat(entryKey = tool-call)
+  -> ToolCallTree
+       -> root/subCalls[] recursion
+       -> tool.call.toolview(entryKey = toolName)
+            |- registered atomic view
+            `- GenericToolCard fallback
 ```
 
-Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供 Live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
+## Ownership boundary
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。selection 只传给包含该 call 的 root，`ToolCallTree` 再沿该 root 的局部树递归渲染。
-
-## 代码与职责边界
-
-| 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
-|---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、snapshot 结构共享 | Tool 名称对应的业务视图 |
-| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
-| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
-| 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
-| details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
-
-## Slot 与 owner 约定
-
-slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
-
-整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
-
-席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 约定：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
-
-业务插件遵循同一个注册形态：
-
-```text
-ctx.slots.inject('tool.call.toolview', () =>
-  ctx.slots.register({
-    name: 'tool.call.toolview',
-    key: '<wire tool name>',
-  }, BusinessToolRow))
-```
-
-`ui-tool` 的 [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) 注册整体 Tool renderer、details renderer 与现有内置原子 view；已有独立业务包可以像 `ui-skill` 一样只迁走自己的 keyed 注册，无需改动 `ui-conversation` 或 Session。
-
-## Details 路径
-
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 在 `nodes` 与 `runningCalls` 的递归 `subCalls` 中定位 selected call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
+| 所有者 | 拥有 | 明确不拥有 |
+|---|---|---|
+| Client Runtime Conversation engine | Context identity、Location、历史重放、view Node 发布 | Tool 事件含义、调用树、Tool renderer |
+| `ui-conversation` Tool Definition | call/result 配对、Code Dispatch 拓扑、running/settled/interrupted `ToolCallBlock`、Chat 排序 anchor | Tool 名称分发、card model、递归 React 结构 |
+| `ui-conversation` Chat view | keyed Node 顺序、scroll anchor、selection 与宿主动作 | Tool lifecycle、subcall 组合、原子 Tool renderer |
+| `ui-tool` | root/subcall 递归渲染、原子 keyed dispatch、fallback、card model 与 details output | Session Event fold、Chat 排序 |
+| 业务 Tool 插件 | 一个或多个 wire Tool name 的原子 renderer | root/subcall 位置、生命周期配对、Session projector |
 
 ## Verification
 
-测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主约定；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+`ui-conversation` 测试固定 Tool Definition 的 call/result、Code Dispatch、interruption 和 running-to-settled keyed identity，不导入 `ui-tool` 的生产 renderer。`ui-tool` 测试挂载真实 conversation 宿主，固定 root/subcall 递归、keyed dispatch、Generic fallback、selection、details 和具体 Tool card。组装后的 Web 测试覆盖两侧插件共同装载的路径。
 
 ## Alternatives considered
 
-**在每个 conversation view 下保留原子 Tool slot。** 拒绝：每个 view 都必须重复 root/subcall 编排，而且 Tool 注册会按 view 隔离，即使它的业务语义本应是 Tool 级。整体 Tool 席位保留 view 对放置位置的所有权，同时让调用树只有一个所有者。它取代了早期 [toolview 溶解](2026-07-23-toolview-dissolution.md)所选择的 per-view 放置方式，但保留 keyed slot 与不设平行 registry 的决策。
+**在每个 conversation view 下保留原子 Tool slot。** 拒绝：每个 view 都要重复 root/subcall 编排，Tool 注册也会按 view 分裂。整个 Tool renderer 占据 view 的一个业务 Node slot，原子分发由 Tool 自己拥有。
 
-**只移动 Tool React 组件与 card model。** 拒绝：`ChatView` 仍会拥有 Tool 名称分发与 Code Dispatch 编排，只是改变文件路径，没有改变责任。
+**只移动 Tool React 组件与 card model。** 拒绝：conversation 仍会按 Tool 名称分发并递归 subcall，文件位置变化不产生所有权边界。
 
-**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
+**为 Tool 建立专属 projector/fold registry。** 拒绝：通用 Conversation assembler 已拥有 Context identity、历史窗口和发布；第二个 Runtime registry 会制造生命周期的双重权威。
 
-**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。递归 root/child 编排统一归 `ui-tool` 的 `ToolCallTree`。
+**让每个原子 Tool renderer 递归自己的 subcall。** 拒绝：原子注册方只应理解一个 Tool call，不应知道自己是 root 还是 child。递归结构统一由 `ToolCallTree` 处理。
 
-**让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转预期的 feature 依赖方向，并把 Tool 展示变成必选能力。声明式 slot 能保留生命周期所有权、fallback 行为与独立插件装载。
+**让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转 feature 依赖并把 Tool 展示变成必选能力。slot 保留独立装载、生命周期和 fallback。
 
 ## Consequences
 
-`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两份跨包 slot 约定；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。
+`ui-conversation` 不再依赖 Tool 名称对应的业务展示，root 与 subcall 也不会漂移到不同分发路径。业务包可以独立拥有原子 Tool renderer；`ui-tool` 缺席时，Conversation 数据组装仍然成立，Chat Node 使用通用 fallback，details 保留 raw result。
+
+代价是 `ui-tool` 明确依赖 conversation 声明的业务 Node slot 和 locale namespace，并拥有一个 Tool 专属子 slot。Tool Definition 暂时位于 `ui-conversation`，因为本次没有拆 package；它以后可以沿 Conversation registry seam 移动，而不会改变本 Note 规定的展示所有权。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 231502dcb7..1ea341085d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: e261ccba597f27149a9527f99b93454dfe5fe5fb
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 5684a8157bb7e1b23cd868fa13ab201ffd07a274
+2026-07-30-web-transcript-log-ordered-projection.md: feefc951118c8511237c931a13070e1f7db1fd16
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 711e57b29742171d1861f25e63019b64356b4cad
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index e261ccba59..feefc95111 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -39,7 +39,7 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 Renaming the Service Definition's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
 
-`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` stays as the behavioral half, driving the adapter with a checkpoint built from the canonical **value**. The test value-imports the cordis-free `@deepseek-ai/dsh-compact/checkpoint` leaf and deliberately never loads the compact package root or the host-side `Context` merges reachable through it.
+`packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts` is the behavioral half, driving the compaction Definition with checkpoint and provenance records and proving that an older page can fill missing summary data. The Definition's type-only leaf import keeps the client isolated from the compact package root and the host-side `Context` merges reachable through it.
 
 The divergence from the terminal is therefore narrow: both frontends recognize a checkpoint from the same declaration — the terminal value-imports `isCompactCheckpointSource` host-side, where no gate applies, and the client pins the type.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 5684a8157b..711e57b297 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -39,7 +39,7 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 重命名 Service Definition 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
 
-`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。该测试以值导入方式从不含 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 叶子路径取得该值，并刻意不加载 compact 包根或经由它可达的宿主侧 `Context` 合并。
+`packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts` 是行为侧的另一半，用检查点与溯源记录驱动压缩 Definition，并证明后续加载的旧分页可以补齐缺失的摘要数据。Definition 仅类型导入该叶子路径，使客户端继续与 compact 包根及经由它可达的宿主侧 `Context` 合并隔离。
 
 因此与终端的分歧很窄：两个前端都从同一份声明识别检查点——终端在宿主侧值导入 `isCompactCheckpointSource`（那里不适用任何门禁），客户端钉住类型。
 
diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts
index 80661a0b13..be719bda15 100644
--- a/apps/web/tests/built-boot.snapshot.ts
+++ b/apps/web/tests/built-boot.snapshot.ts
@@ -38,7 +38,6 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
   await waitFor(() => {
     expect(document.querySelector('[data-sample="bash"]')).not.toBeNull()
   }, { timeout: 10_000 })
-
   // Resolve the resident approval so the ordinary composer bar (which owns
   // ContextMeter) resumes without replacing the session shell. This minimal
   // boot graph intentionally does not mount the separate question UI plugin.
diff --git a/apps/web/tests/chat-continuous-conversation.e2e.ts b/apps/web/tests/chat-continuous-conversation.e2e.ts
index 61701c1cdc..a7b659dab2 100644
--- a/apps/web/tests/chat-continuous-conversation.e2e.ts
+++ b/apps/web/tests/chat-continuous-conversation.e2e.ts
@@ -12,6 +12,7 @@ import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { ReplayEntry, ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import { conversationContextKey } from '@deepseek-ai/dsh-client-runtime/client'
 import {
   launchWebScaffold,
   watchConsole,
@@ -160,6 +161,14 @@ function toolResultText(event: Extract<SessionEvent, { type: 'tool/result' }>):
     .join('')
 }
 
+function messageKey(event: SessionEvent<'user/message'>): string {
+  return conversationContextKey('input-message', String(event.data.id))
+}
+
+function assistantKey(event: SessionEvent<'assistant/message'>): string {
+  return conversationContextKey('assistant-step', `${event.data.turn}:${event.data.step}`)
+}
+
 describe('web e2e: continuous conversation grown through the composer', () => {
   let browser: Browser
   let page: Page
@@ -222,6 +231,11 @@ describe('web e2e: continuous conversation grown through the composer', () => {
       const settled = scaffold.whenTurnSettled(60_000)
       await page.getByRole('button', { name: 'Send message', exact: true }).click()
       await page.getByText(spec.userMarker, { exact: false }).last().waitFor({ timeout: 15_000 })
+      await expect.poll(() => sessionEvents.slice(eventStart).some(event => (
+        event.type === 'user/message'
+        && event.data.source.kind === 'user'
+        && userText(event).includes(spec.userMarker)
+      )), { timeout: 15_000 }).toBe(true)
       const echoedUser = sessionEvents.slice(eventStart).find(
         (event): event is SessionEvent<'user/message'> => (
           event.type === 'user/message'
@@ -230,7 +244,7 @@ describe('web e2e: continuous conversation grown through the composer', () => {
         ),
       )
       if (echoedUser === undefined) throw new Error(`turn ${String(spec.index)} has no user echo event`)
-      const userRow = page.locator(`[data-chat-anchor-key="node:${String(echoedUser.seq)}"]`)
+      const userRow = page.locator(`[data-chat-anchor-key="${messageKey(echoedUser)}"]`)
       await expect.poll(() => userRow.count(), { timeout: 10_000 }).toBe(1)
       expect(await userRow.getAttribute('data-chat-flow-kind')).toBe('user')
       expect(await userRow.textContent()).toContain(spec.userMarker)
@@ -274,9 +288,9 @@ describe('web e2e: continuous conversation grown through the composer', () => {
       expect(turnEnds[0]?.data).toEqual({ turn: spec.index, reason: { kind: 'completed' } })
       expect(chunks).toHaveLength(spec.deltas.length + (spec.callId === undefined ? 4 : 9))
 
-      const assistantRow = page.locator(`[data-chat-anchor-key="node:${String(finalAssistants[0]!.seq)}"]`)
+      const assistantRow = page.locator(`[data-chat-anchor-key="${assistantKey(finalAssistants[0]!)}"]`)
       await expect.poll(() => assistantRow.count(), { timeout: 10_000 }).toBe(1)
-      expect(await assistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant')
+      expect(await assistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant-step')
       expect(await assistantRow.textContent()).toContain(spec.doneMarker)
 
       const calls = turnEvents.filter((event): event is SessionEvent<'tool/call'> => event.type === 'tool/call')
diff --git a/apps/web/tests/chat-long-interactions.e2e.ts b/apps/web/tests/chat-long-interactions.e2e.ts
index b9bebbd897..cd1fcb2fa7 100644
--- a/apps/web/tests/chat-long-interactions.e2e.ts
+++ b/apps/web/tests/chat-long-interactions.e2e.ts
@@ -10,6 +10,7 @@ import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { ReplayEntry, ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { conversationContextKey } from '@deepseek-ai/dsh-client-runtime/client'
 import { createChatScrollFixture } from './chat-scroll-fixture.ts'
 import {
   launchWebScaffold,
@@ -115,6 +116,18 @@ function requiredEvent<T extends SessionEvent['type']>(
   return event
 }
 
+function messageKey(event: SessionEvent<'user/message'>): string {
+  return conversationContextKey('input-message', String(event.data.id))
+}
+
+function assistantKey(event: SessionEvent<'assistant/message'>): string {
+  return conversationContextKey('assistant-step', `${event.data.turn}:${event.data.step}`)
+}
+
+function turnTailKey(turn: number): string {
+  return conversationContextKey('turn-tail', String(turn))
+}
+
 describe('web e2e: long Chat interaction contract', () => {
   let browser: Browser
   let page: Page
@@ -176,8 +189,10 @@ describe('web e2e: long Chat interaction contract', () => {
     const expectedUserText = textContent(branchUserEvent.data.content)
 
     await wheelUntilMounted(page, `[data-chat-call-id="${TARGET_CALL_2}"]`, -1_100)
-    const toolUserRow = page.locator(`[data-chat-anchor-key="node:${String(toolUserEvent.seq)}"]`)
-    const toolAssistantRow = page.locator(`[data-chat-anchor-key="node:${String(toolAssistantEvent.seq)}"]`)
+    const toolUserKey = messageKey(toolUserEvent)
+    const toolAssistantKey = assistantKey(toolAssistantEvent)
+    const toolUserRow = page.locator(`[data-chat-anchor-key="${toolUserKey}"]`)
+    const toolAssistantRow = page.locator(`[data-chat-anchor-key="${toolAssistantKey}"]`)
     const call1 = page.locator(`[data-chat-call-id="${TARGET_CALL_1}"]`)
     const call2 = page.locator(`[data-chat-call-id="${TARGET_CALL_2}"]`)
 
@@ -186,28 +201,27 @@ describe('web e2e: long Chat interaction contract', () => {
     expect(await call1.count()).toBe(1)
     expect(await call2.count()).toBe(1)
     expect(await toolUserRow.getAttribute('data-chat-flow-kind')).toBe('user')
-    expect(await toolAssistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant')
+    expect(await toolAssistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant-step')
     expect(await toolUserRow.textContent()).toContain(toolUserMarker)
     expect(await toolAssistantRow.textContent()).toContain(toolAssistantMarker)
     expect(await call1.textContent()).toContain(toolMarker1)
     expect(await call2.textContent()).toContain(toolMarker2)
 
     const expectedOrder = [
-      `node:${String(toolUserEvent.seq)}`,
-      `call:${TARGET_CALL_1}`,
-      `call:${TARGET_CALL_2}`,
-      `node:${String(toolAssistantEvent.seq)}`,
+      toolUserKey,
+      conversationContextKey('tool-call', TARGET_CALL_1),
+      conversationContextKey('tool-call', TARGET_CALL_2),
+      toolAssistantKey,
     ]
     const actualOrder = await page.locator('[data-chat-anchor-key]').evaluateAll((rows, keys) => (
       rows.map(row => (row as HTMLElement).dataset.chatAnchorKey)
         .filter((key): key is string => key !== undefined && keys.includes(key))
     ), expectedOrder)
     expect(actualOrder).toEqual(expectedOrder)
-    const groupKeys = await Promise.all([call1, call2].map(row => row.evaluate(element => (
-      element.closest<HTMLElement>('[data-chat-flow-kind="tool-group"]')?.dataset.chatFlowKey ?? null
+    const toolKinds = await Promise.all([call1, call2].map(row => row.evaluate(element => (
+      element.closest<HTMLElement>('[data-chat-flow-kind]')?.dataset.chatFlowKind ?? null
     ))))
-    expect(groupKeys[0]).not.toBeNull()
-    expect(groupKeys[1]).toBe(groupKeys[0])
+    expect(toolKinds).toEqual(['tool-call', 'tool-call'])
 
     const summary1 = call1.locator('[data-sample="bash"]')
     const summary2 = call2.locator('[data-sample="bash"]')
@@ -219,9 +233,12 @@ describe('web e2e: long Chat interaction contract', () => {
     expect(await summary1.getAttribute('aria-expanded')).toBe('false')
     await call2.getByText(`${toolMarker2} output line 12`, { exact: true }).waitFor({ timeout: 10_000 })
 
-    await wheelUntilMounted(page, `[data-chat-anchor-key="node:${String(branchUserEvent.seq)}"]`, -1_100)
-    const userRow = page.locator(`[data-chat-anchor-key="node:${String(branchUserEvent.seq)}"]`)
-    const assistantRow = page.locator(`[data-chat-anchor-key="node:${String(branchAssistantEvent.seq)}"]`)
+    const branchUserKey = messageKey(branchUserEvent)
+    const branchAssistantKey = assistantKey(branchAssistantEvent)
+    await wheelUntilMounted(page, `[data-chat-anchor-key="${branchUserKey}"]`, -1_100)
+    const userRow = page.locator(`[data-chat-anchor-key="${branchUserKey}"]`)
+    const assistantRow = page.locator(`[data-chat-anchor-key="${branchAssistantKey}"]`)
+    const turnTailRow = page.locator(`[data-chat-anchor-key="${turnTailKey(BRANCH_TURN)}"]`)
     expect(await userRow.textContent()).toContain(branchUserMarker)
     expect(await assistantRow.textContent()).toContain(branchAssistantMarker)
     await page.context().grantPermissions(['clipboard-read', 'clipboard-write'])
@@ -230,8 +247,8 @@ describe('web e2e: long Chat interaction contract', () => {
     await expect.poll(() => page.evaluate(() => navigator.clipboard.readText()), { timeout: 5_000 })
       .toBe(expectedUserText)
 
-    await assistantRow.hover()
-    await assistantRow.getByRole('button', { name: 'Branch into a new conversation', exact: true }).click()
+    await turnTailRow.hover()
+    await turnTailRow.getByRole('button', { name: 'Branch into a new conversation', exact: true }).click()
     await expect.poll(
       () => scaffold.ctx.agents.list().find(agent => agent.session.header.parentSession === SessionId(SESSION_ID)),
       { timeout: 15_000 },
diff --git a/apps/web/tests/search-card.snapshot.ts b/apps/web/tests/search-card.snapshot.ts
index 8e6322c4af..8ac775be1d 100644
--- a/apps/web/tests/search-card.snapshot.ts
+++ b/apps/web/tests/search-card.snapshot.ts
@@ -2,7 +2,7 @@
 // Assembled search-card snapshot: boots the real built workspace client bundles
 // through AppWebEntry's ModuleLoader path against the keyless
 // FixtureApiClient transport (no API key, no model round), opens the fixture
-// session, and pins the search card the `grep` turn (fixture turn 66) renders in
+// session, and pins the search card the `grep` turn (fixture turn 67) renders in
 // the assembled application. The built-boot smoke proves the graph boots but
 // carries no behavior assertions by contract; this is the assembled-output check
 // that a broken SearchRow registration or a dropped card would fail — the
@@ -51,7 +51,7 @@ describe('assembled search card', () => {
     const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
     fireEvent.click(await within(tree).findByText('Fixture 历史会话'))
     // Wait for chat content to reach the fixture's later turns (the bash sample
-    // is turn 65, the grep card turn 66).
+    // is turn 66, the grep card turn 67).
     await waitFor(() => {
       expect(document.querySelector('[data-sample="bash"]')).not.toBeNull()
     }, { timeout: 10_000 })
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 072a322fb6..8a9ee26866 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -91,11 +91,15 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
     return taken
   }
   const commandId = 'cmd-seeded-manual-compact'
+  const compactionId = 'compact-seeded-manual-compact'
   at({
     type: 'command/run',
     data: { commandId, name: 'compact', args: '', source: { kind: 'user' } },
   })
-  const startSeq = at({ type: 'compact/start', data: { turn: null } })
+  const startSeq = at({
+    type: 'compact/start',
+    data: { compactionId, sourceCommandId: commandId, turn: null },
+  })
   // Load-bearing exactness: the projections subtract this count verbatim, so
   // it must equal what the host's fold prices for these nodes. The estimator
   // prices message CONTENT only, so a minimal wrapper per storage shape is
@@ -124,6 +128,8 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
   const summarySeq = at({
     type: 'compact/summary',
     data: {
+      compactionId,
+      sourceCommandId: commandId,
       summary: [{
         type: 'text',
         text: '## Cold resume compact summary\n\n- The exact summary remains available.',
@@ -142,12 +148,17 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
         type: 'text',
         text: '<context_checkpoint>Model-only compact checkpoint.</context_checkpoint>',
       }],
-      source: { kind: 'plugin', plugin: 'compact' },
+      source: {
+        kind: 'plugin', plugin: 'compact', compactionId, sourceCommandId: commandId,
+      },
     },
     surfaceOp: { op: 'replace', start: first, end: last },
     sourceEventSeqs: [startSeq, summarySeq, ...surfaceSeqs],
   })
-  at({ type: 'compact/end', data: { turn: null } })
+  at({
+    type: 'compact/end',
+    data: { compactionId, sourceCommandId: commandId, turn: null },
+  })
   at({
     type: 'command/done',
     data: {
diff --git a/apps/web/tests/skill-user-invoke.e2e.ts b/apps/web/tests/skill-user-invoke.e2e.ts
index 302aa062b0..8555ef7499 100644
--- a/apps/web/tests/skill-user-invoke.e2e.ts
+++ b/apps/web/tests/skill-user-invoke.e2e.ts
@@ -109,6 +109,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
       { timeout: 10_000 },
     ).toBe(1)
 
+    const settled = scaffold.whenTurnSettled()
     await composer.fill(`/${SKILL_NAME} ${ARGS_TEXT}`)
     await composer.press('Enter')
 
@@ -135,6 +136,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
 
     // The injection started a turn; the replay adapter answers it.
     await page.getByText('USER_INVOKE_REPLY', { exact: false }).first().waitFor({ timeout: 20_000 })
+    await settled
 
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
diff --git a/apps/web/tests/snapshots/code-mode-round/session.jsonl b/apps/web/tests/snapshots/code-mode-round/session.jsonl
index 9ff7af0110..09e2432e94 100644
--- a/apps/web/tests/snapshots/code-mode-round/session.jsonl
+++ b/apps/web/tests/snapshots/code-mode-round/session.jsonl
@@ -14,10 +14,10 @@
 {"type":"assistant/chunk","seq":204,"time":1785013633104,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":205,"time":1785013633108,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single `run_code` program that:\n1. Runs bash to echo \"CODE_ROUND_OK\"\n2. Tries to read a file \"missing.txt\" and catches the error\n3. Returns an object with both outcomes\n4. They also want me to reply \"DONE\" and stop after\n\nLet me write this program."},{"type":"tool-call","id":"call_00_6VNoF1gDSerTBKoCfYSH3765","name":"run_code","arguments":"{\"description\": \"Run bash echo and catch missing file read\", \"code\": \"\\nconst bashResult = await tools.bash({\\n  command: \\\"echo CODE_ROUND_OK\\\",\\n  description: \\\"Echo CODE_ROUND_OK\\\"\\n});\\n\\nlet readError = null;\\ntry {\\n  await tools.read({ file_path: \\\"missing.txt\\\" });\\n} catch (e) {\\n  readError = {\\n    toolName: e.toolName,\\n    message: e.message\\n  };\\n}\\n\\nreturn { bash: bashResult.stdout.text.trim(), readError };\\n\"}"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":8082,"outputTokens":235,"cacheReadTokens":384,"reasoningTokens":75}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204],"surfaceOp":"append"}
 {"type":"tool/call","seq":206,"time":1785013633108,"data":{"turn":1,"step":1,"callId":"call_00_6VNoF1gDSerTBKoCfYSH3765","name":"run_code","arguments":"{\"description\": \"Run bash echo and catch missing file read\", \"code\": \"\\nconst bashResult = await tools.bash({\\n  command: \\\"echo CODE_ROUND_OK\\\",\\n  description: \\\"Echo CODE_ROUND_OK\\\"\\n});\\n\\nlet readError = null;\\ntry {\\n  await tools.read({ file_path: \\\"missing.txt\\\" });\\n} catch (e) {\\n  readError = {\\n    toolName: e.toolName,\\n    message: e.message\\n  };\\n}\\n\\nreturn { bash: bashResult.stdout.text.trim(), readError };\\n\"}"}}
-{"type":"tool/code-dispatch-start","seq":207,"time":1785013633173,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"}}}
-{"type":"tool/code-dispatch","seq":208,"time":1785013633196,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"},"isError":false,"content":[{"type":"text","text":"CODE_ROUND_OK\n"}]}}
-{"type":"tool/code-dispatch-start","seq":209,"time":1785013633197,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"}}}
-{"type":"tool/code-dispatch","seq":210,"time":1785013633198,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"},"isError":true,"content":[{"type":"text","text":"Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"}]}}
+{"type":"tool/code-dispatch-start","seq":207,"time":1785013633173,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"}}}
+{"type":"tool/code-dispatch","seq":208,"time":1785013633196,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"},"isError":false,"content":[{"type":"text","text":"CODE_ROUND_OK\n"}]}}
+{"type":"tool/code-dispatch-start","seq":209,"time":1785013633197,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"}}}
+{"type":"tool/code-dispatch","seq":210,"time":1785013633198,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"},"isError":true,"content":[{"type":"text","text":"Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"}]}}
 {"type":"tool/result","seq":211,"time":1785013633201,"data":{"turn":1,"step":1,"callId":"call_00_6VNoF1gDSerTBKoCfYSH3765","content":[{"type":"text","text":"{\n  \"bash\": \"CODE_ROUND_OK\",\n  \"readError\": {\n    \"toolName\": \"read\",\n    \"message\": \"cannot read \\\"{{cwd}}/workspace/missing.txt\\\": not found\"\n  }\n}"}],"isError":false},"sourceEventSeqs":[206],"surfaceOp":"append"}
 {"type":"step/end","seq":212,"time":1785013633204,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":213,"time":1785013633207,"data":{"turn":1,"step":2}}
diff --git a/apps/web/tests/todo-row.snapshot.ts b/apps/web/tests/todo-row.snapshot.ts
index c05057dddc..c5ded143b3 100644
--- a/apps/web/tests/todo-row.snapshot.ts
+++ b/apps/web/tests/todo-row.snapshot.ts
@@ -2,7 +2,7 @@
 // Assembled todo snapshot: boots the real built `packages/client/*/lib/
 // client.js` bundles through AppWebEntry's ModuleLoader path against the
 // keyless FixtureApiClient transport, opens the fixture session, and pins the
-// two surfaces the fixture's parallel plan (turn 71, two items `in_progress`)
+// two surfaces the fixture's parallel plan (turn 72, two items `in_progress`)
 // reaches — the `todo_write` tool row and the dock's plan strip.
 //
 // The row is pinned as three separate fields on purpose. `summary=` is the
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 5f3bc744b2..22e21edc0b 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -917,7 +917,7 @@ Requires: `agents`
 export type Config = Readonly<Record<string, never>>
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:46`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/index.ts:33`](../packages/llm/llm-retry/src/index.ts)
 
 ## `@deepseek-ai/dsh-lsp-local`
 
@@ -2325,7 +2325,7 @@ export interface Config {
 export type ToolPresentationMode = 'native' | 'code' | 'both'
 ```
 
-Source: [`packages/core/tools/src/index.ts:616`](../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:623`](../packages/core/tools/src/index.ts)
 
 ## `@deepseek-ai/dsh-typert-loader`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 5b36725402..a8263b70c1 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -21,7 +21,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:174`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index e7d6b47e70..767ebfcfde 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -436,9 +436,6 @@ flowchart TD
   pkg_fs --> pkg_sandbox
   pkg_skill_badge --> pkg_invariants
   pkg_skill_badge --> pkg_skill
-  pkg_compact --> pkg_invariants
-  pkg_compact --> pkg_llm
-  pkg_compact --> pkg_session
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
@@ -502,15 +499,11 @@ flowchart TD
   pkg_session_projection --> pkg_invariants
   pkg_session_projection --> pkg_session
   pkg_llm_retry --> pkg_agent
+  pkg_llm_retry --> pkg_brand
   pkg_llm_retry --> pkg_invariants
   pkg_llm_retry --> pkg_llm
   pkg_llm_retry --> pkg_session
   pkg_llm_retry --> pkg_timeout
-  pkg_token_meter --> pkg_compact
-  pkg_token_meter --> pkg_invariants
-  pkg_token_meter --> pkg_llm
-  pkg_token_meter --> pkg_session
-  pkg_token_meter --> pkg_session_projection
   pkg_agent_default_model --> pkg_agent
   pkg_agent_default_model --> pkg_invariants
   pkg_agent_default_model --> pkg_llm
@@ -550,10 +543,6 @@ flowchart TD
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_invariants
   pkg_hook_protocol --> pkg_session
-  pkg_llm_replay --> pkg_compact
-  pkg_llm_replay --> pkg_invariants
-  pkg_llm_replay --> pkg_llm
-  pkg_llm_replay --> pkg_session
   pkg_loader_smoke --> pkg_agent
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
@@ -674,14 +663,11 @@ flowchart TD
   pkg_fs_sandbox --> pkg_invariants
   pkg_fs_sandbox --> pkg_sandbox
   pkg_fs_sandbox --> pkg_sandbox_policy
-  pkg_command_compact --> pkg_commands
-  pkg_command_compact --> pkg_compact
-  pkg_command_compact --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_compact
-  pkg_compact_tool_result_prune --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_llm
-  pkg_compact_tool_result_prune --> pkg_session
-  pkg_compact_tool_result_prune --> pkg_token_meter
+  pkg_compact --> pkg_brand
+  pkg_compact --> pkg_commands
+  pkg_compact --> pkg_invariants
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
   pkg_session_query --> pkg_brand
   pkg_session_query --> pkg_invariants
   pkg_session_query --> pkg_llm
@@ -703,13 +689,6 @@ flowchart TD
   pkg_headless --> pkg_invariants
   pkg_headless --> pkg_llm
   pkg_headless --> pkg_session
-  pkg_client_ui_conversation --> pkg_client_locale
-  pkg_client_ui_conversation --> pkg_client_runtime
-  pkg_client_ui_conversation --> pkg_client_ui_primitives
-  pkg_client_ui_conversation --> pkg_client_ui_slash
-  pkg_client_ui_conversation --> pkg_client_ui_slots
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_token_meter
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
   pkg_command_feedback --> pkg_session
@@ -742,6 +721,11 @@ flowchart TD
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
   pkg_tasks_local --> pkg_timeout
+  pkg_token_meter --> pkg_compact
+  pkg_token_meter --> pkg_invariants
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
+  pkg_token_meter --> pkg_session_projection
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_invariants
   pkg_agent_loop --> pkg_llm
@@ -790,13 +774,9 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
-  pkg_compact_basic --> pkg_agent
-  pkg_compact_basic --> pkg_compact
-  pkg_compact_basic --> pkg_compact_tool_result_prune
-  pkg_compact_basic --> pkg_invariants
-  pkg_compact_basic --> pkg_llm
-  pkg_compact_basic --> pkg_session
-  pkg_compact_basic --> pkg_token_meter
+  pkg_command_compact --> pkg_commands
+  pkg_command_compact --> pkg_compact
+  pkg_command_compact --> pkg_invariants
   pkg_subagent --> pkg_agent
   pkg_subagent --> pkg_brand
   pkg_subagent --> pkg_invariants
@@ -857,33 +837,10 @@ flowchart TD
   pkg_agent_loop_testkit --> pkg_session
   pkg_agent_loop_testkit --> pkg_system_prompt
   pkg_agent_loop_testkit --> pkg_tools
-  pkg_client_ui_command --> pkg_client_connection
-  pkg_client_ui_command --> pkg_client_locale
-  pkg_client_ui_command --> pkg_client_runtime
-  pkg_client_ui_command --> pkg_client_ui_conversation
-  pkg_client_ui_command --> pkg_client_ui_primitives
-  pkg_client_ui_command --> pkg_client_ui_slash
-  pkg_client_ui_command --> pkg_client_ui_slots
-  pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_deliverables --> pkg_client_locale
-  pkg_client_ui_deliverables --> pkg_client_runtime
-  pkg_client_ui_deliverables --> pkg_client_ui_conversation
-  pkg_client_ui_deliverables --> pkg_client_ui_slots
-  pkg_client_ui_deliverables --> pkg_invariants
-  pkg_client_ui_goal --> pkg_api_remotes
-  pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_runtime
-  pkg_client_ui_goal --> pkg_client_ui_conversation
-  pkg_client_ui_goal --> pkg_client_ui_primitives
-  pkg_client_ui_goal --> pkg_client_ui_slots
-  pkg_client_ui_goal --> pkg_goal
-  pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_tool --> pkg_client_locale
-  pkg_client_ui_tool --> pkg_client_runtime
-  pkg_client_ui_tool --> pkg_client_ui_conversation
-  pkg_client_ui_tool --> pkg_client_ui_primitives
-  pkg_client_ui_tool --> pkg_client_ui_slots
-  pkg_client_ui_tool --> pkg_invariants
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -990,6 +947,11 @@ flowchart TD
   pkg_tool_pwsh --> pkg_system_prompt
   pkg_tool_pwsh --> pkg_tasks
   pkg_tool_pwsh --> pkg_tools
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
   pkg_subagent_acp --> pkg_agent
   pkg_subagent_acp --> pkg_invariants
   pkg_subagent_acp --> pkg_llm
@@ -1038,50 +1000,14 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
-  pkg_client_ui_model --> pkg_client_connection
-  pkg_client_ui_model --> pkg_client_locale
-  pkg_client_ui_model --> pkg_client_runtime
-  pkg_client_ui_model --> pkg_client_ui_command
-  pkg_client_ui_model --> pkg_client_ui_conversation
-  pkg_client_ui_model --> pkg_client_ui_primitives
-  pkg_client_ui_model --> pkg_client_ui_slash
-  pkg_client_ui_model --> pkg_client_ui_slots
-  pkg_client_ui_model --> pkg_invariants
-  pkg_client_ui_permission --> pkg_client_connection
-  pkg_client_ui_permission --> pkg_client_locale
-  pkg_client_ui_permission --> pkg_client_runtime
-  pkg_client_ui_permission --> pkg_client_schema_form
-  pkg_client_ui_permission --> pkg_client_ui_command
-  pkg_client_ui_permission --> pkg_client_ui_primitives
-  pkg_client_ui_permission --> pkg_client_ui_slash
-  pkg_client_ui_permission --> pkg_client_ui_slots
-  pkg_client_ui_permission --> pkg_invariants
-  pkg_client_ui_permission --> pkg_permission
-  pkg_client_ui_plan --> pkg_client_connection
-  pkg_client_ui_plan --> pkg_client_locale
-  pkg_client_ui_plan --> pkg_client_runtime
-  pkg_client_ui_plan --> pkg_client_ui_conversation
-  pkg_client_ui_plan --> pkg_client_ui_primitives
-  pkg_client_ui_plan --> pkg_client_ui_slots
-  pkg_client_ui_plan --> pkg_invariants
-  pkg_client_ui_plan --> pkg_plan_mode
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_client_ui_tool
-  pkg_client_ui_skill --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_client_locale
-  pkg_client_ui_subagent --> pkg_client_runtime
-  pkg_client_ui_subagent --> pkg_client_ui_conversation
-  pkg_client_ui_subagent --> pkg_client_ui_primitives
-  pkg_client_ui_subagent --> pkg_client_ui_slash
-  pkg_client_ui_subagent --> pkg_client_ui_slots
-  pkg_client_ui_subagent --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_subagent
-  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_compact
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_token_meter
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1105,6 +1031,14 @@ flowchart TD
   pkg_workflow_workerthread --> pkg_subagent
   pkg_workflow_workerthread --> pkg_tools
   pkg_workflow_workerthread --> pkg_workflow
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_commands
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
   pkg_subagent_codex --> pkg_invariants
   pkg_subagent_codex --> pkg_llm
   pkg_subagent_codex --> pkg_sdk_protocol
@@ -1120,6 +1054,50 @@ flowchart TD
   pkg_subagent_spawn --> pkg_invariants
   pkg_subagent_spawn --> pkg_subagent
   pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1161,6 +1139,33 @@ flowchart TD
   pkg_subagent_dsh_sdk --> pkg_session
   pkg_subagent_dsh_sdk --> pkg_subagent
   pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1238,7 +1243,6 @@ flowchart TD
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
-| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
@@ -1255,8 +1259,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1267,7 +1270,6 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1295,19 +1297,18 @@ flowchart TD
 | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
-| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`compact`](../packages/compact/compact) | `compact` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
@@ -1315,7 +1316,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
@@ -1325,10 +1326,7 @@ flowchart TD
 | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1347,6 +1345,7 @@ flowchart TD
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1355,20 +1354,26 @@ flowchart TD
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
-| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
-| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 614f6afbeb..76487ca3d4 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -212,7 +212,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:153`](../packages/interaction/commands/src/index.ts)
 
 #### `command/run` — log-only
 
@@ -230,7 +230,7 @@ Source: [`packages/interaction/commands/src/index.ts:151`](../packages/interacti
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:146`](../packages/interaction/commands/src/index.ts)
 
 ### `compact/*`
 
@@ -241,10 +241,10 @@ Source: [`packages/interaction/commands/src/index.ts:144`](../packages/interacti
  * Marks the end of a compaction — log-only, releases the lock. Its owner
  * matches `compact/start`; `error` records an unsuccessful attempt.
  */
-'compact/end': { turn: number | null; error?: string }
+'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:69`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -268,7 +268,7 @@ Source: [`packages/compact/compact/src/types.ts:65`](../packages/compact/compact
 }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:79`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -278,10 +278,10 @@ Source: [`packages/compact/compact/src/types.ts:75`](../packages/compact/compact
  * `compact/end`. A numbered owner is strictly enclosed by that open turn;
  * `null` identifies a standalone manual transaction between turns.
  */
-'compact/start': { turn: number | null }
+'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:21`](../packages/compact/compact/src/types.ts)
 
 #### `compact/summary` — log-only
 
@@ -296,6 +296,8 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
  * before it (`compact/prune` documents the shared protocol).
  */
 'compact/summary': {
+  compactionId: CompactionId
+  sourceCommandId?: CommandId
   summary: ContentBlock[]
   shadowedRange: { start: number; end: number }
   shadowedSeqs: number[]
@@ -331,7 +333,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 
 Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:31`](../packages/compact/compact/src/types.ts)
 
 ### `feedback/*`
 
@@ -412,29 +414,19 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-
 
 ```ts persistence-catalog
 /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-'llm/retry': {
-  turn: number
-  step: number
-  provider: string
-  mode: 'normal'
-  policyKey: string
-  retry: number
-  maxRetries: number
-  delayMs: number
-  failure: LlmFailure
-} | {
-  turn: number
-  step: number
-  provider: string
-  mode: 'always'
-  policyKey: string
-  retry: number
-  delayMs: number
-  failure: LlmFailure
-}
+'llm/retry': LlmRetryEventData
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/index.ts:20`](../packages/llm/llm-retry/src/index.ts)
+
+#### `llm/retry-started` — log-only
+
+```ts persistence-catalog
+/** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+'llm/retry-started': LlmRetryStartedEventData
+```
+
+Source: [`packages/llm/llm-retry/src/index.ts:22`](../packages/llm/llm-retry/src/index.ts)
 
 ### `permission/*`
 
@@ -656,7 +648,7 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
  * before returning), so its execution-enclosure relation holds by
  * construction.
  */
-'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
 ```
 
 Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
@@ -679,7 +671,7 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c
  * with `tool/code-dispatch` by `subCallId` (timing = the two events'
  * `time` fields).
  */
-'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
 ```
 
 Types: [CallId](subsystems/core.md)
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 5bc05d2916..9466165680 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: c71c19b8a3f94ba468e6871d5658c4eca1c6276d
-commands.zh.md: 3f1df0e8aa40524160c8f770793b6064dd5988ae
+commands.md: 7f4e4e87d7206be3e46c7076ee5e8ab6a7589f9a
+commands.zh.md: 0f8ff31bca5f62824912f53aee8dbc32db4c331b
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index c71c19b8a3..7f4e4e87d7 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -49,6 +49,8 @@ The adapter owns cancellation and passes the exact target agent. `rawInput` begi
 ```ts type-equiv
 /** Invocation passed to one registered command handler. */
 interface CommandInvocation {
+  /** Pairing id already written to this invocation's `command/run` event. */
+  readonly commandId: CommandId
   /** Exact agent whose human-facing surface received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
@@ -159,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -181,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 3f1df0e8aa..0f8ff31bca 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -49,6 +49,8 @@ interface CommandDefinition {
 ```ts type-equiv
 /** Invocation passed to one registered command handler. */
 interface CommandInvocation {
+  /** Pairing id already written to this invocation's `command/run` event. */
+  readonly commandId: CommandId
   /** Exact agent whose human-facing surface received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
@@ -159,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -181,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 6445fa5d5c..fd8dbdd1b5 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 942cc740db6b7006952bfc33a39ea9826d673e61
-compaction.zh.md: c5b65a95f9c0db8b02912c68ef93edce2ceb7c43
+compaction.md: 1aca48d677a83a488d9590edad3f8a68ca662b70
+compaction.zh.md: e2cfabc0891126d9f2165e47dffcf485f4a8a339
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 942cc740db..1aca48d677 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -29,6 +29,10 @@ What a successful compaction returns to its caller: the bookkeeping-event seqs,
 ```ts type-equiv
 /** Result of a successful compaction operation. */
 interface CompactionResult {
+  /** Stable identity shared by this compaction's complete durable lifecycle. */
+  compactionId: CompactionId
+  /** Human command that initiated this compaction, when it was manual. */
+  sourceCommandId?: CommandId
   /** The seq of the appended `compact/start` event. */
   startSeq: number
   /** The seq of the appended `compact/summary` event. */
@@ -155,13 +159,14 @@ abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger
  *
  * @param agent - idle agent whose durable history should be compacted.
  * @param signal - cancellation scoped to this compaction request.
+ * @param sourceCommandId - initiating command identity for a manual compaction.
  * @returns the compaction result, or `null` when no safe useful range exists.
  * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
  * changed-span, summarization/shrink, commit-stage, or persistence failures;
  * an aborted request preserves its exact abort reason. Failed attempts remain
  * visible in the log.
  */
-abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>
 
 /**
  * Forcibly compact a range of surface nodes into a single summary node.
@@ -184,7 +189,9 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+Types: [CommandId](commands.md)
+
+Source: [`packages/compact/compact/src/index.ts:96`](../../packages/compact/compact/src/index.ts)
 
 <a id="ctxtoolresultprune--toolresultpruneservice"></a>
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index c5b65a95f9..e2cfabc089 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -29,6 +29,10 @@
 ```ts type-equiv
 /** Result of a successful compaction operation. */
 interface CompactionResult {
+  /** Stable identity shared by this compaction's complete durable lifecycle. */
+  compactionId: CompactionId
+  /** Human command that initiated this compaction, when it was manual. */
+  sourceCommandId?: CommandId
   /** The seq of the appended `compact/start` event. */
   startSeq: number
   /** The seq of the appended `compact/summary` event. */
@@ -155,13 +159,14 @@ abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger
  *
  * @param agent - idle agent whose durable history should be compacted.
  * @param signal - cancellation scoped to this compaction request.
+ * @param sourceCommandId - initiating command identity for a manual compaction.
  * @returns the compaction result, or `null` when no safe useful range exists.
  * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
  * changed-span, summarization/shrink, commit-stage, or persistence failures;
  * an aborted request preserves its exact abort reason. Failed attempts remain
  * visible in the log.
  */
-abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>
 
 /**
  * Forcibly compact a range of surface nodes into a single summary node.
@@ -184,7 +189,9 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+Types: [CommandId](commands.md)
+
+Source: [`packages/compact/compact/src/index.ts:96`](../../packages/compact/compact/src/index.ts)
 
 <a id="ctxtoolresultprune--toolresultpruneservice"></a>
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 42f73824cf..d015cdb638 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 87910dfbb86e9db0f0545bc2fe1135c4aefb2e69
-tools.zh.md: d312090b722de3fd1b8efc7703eafdf7f3c38682
+tools.md: f06db58b9b52fcb2c325ff813406cd2dc460ea7b
+tools.zh.md: cca4bf9faa870d9414d95f785b67e0393e469cdd
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 87910dfbb8..f06db58b9b 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -184,6 +184,11 @@ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
  */
 interface ToolExecutionInput {
   readonly callId: CallId
+  /**
+   * Root model-requested call owning this execution tree. Callers omit it for
+   * a root execution; nested dispatchers propagate the enclosing value.
+   */
+  readonly rootCallId?: CallId
   readonly name: string
   /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
@@ -280,6 +285,8 @@ interface CodeDispatchLog {
  * observers run.
  */
 interface ToolExecution extends ToolExecutionInput {
+  /** Root model-requested call, resolved for every root and nested execution. */
+  readonly rootCallId: CallId
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
 }
@@ -547,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index d312090b72..cca4bf9faa 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -184,6 +184,11 @@ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
  */
 interface ToolExecutionInput {
   readonly callId: CallId
+  /**
+   * Root model-requested call owning this execution tree. Callers omit it for
+   * a root execution; nested dispatchers propagate the enclosing value.
+   */
+  readonly rootCallId?: CallId
   readonly name: string
   /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
@@ -280,6 +285,8 @@ interface CodeDispatchLog {
  * observers run.
  */
 interface ToolExecution extends ToolExecutionInput {
+  /** Root model-requested call, resolved for every root and nested execution. */
+  readonly rootCallId: CallId
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
 }
@@ -547,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
index f4169abe78..d6935b6c98 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -25,8 +25,8 @@
 {"type":"assistant/chunk","seq":23,"time":1785730458465,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":24,"time":1785730458465,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e3061430-3f2d-4dd8-a3ee-c0fde800547d"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
 {"type":"tool/call","seq":25,"time":1785730458465,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}}
-{"type":"tool/code-dispatch-start","seq":26,"time":1785730458517,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
-{"type":"tool/code-dispatch","seq":27,"time":1785730458518,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
+{"type":"tool/code-dispatch-start","seq":26,"time":1785730458517,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
+{"type":"tool/code-dispatch","seq":27,"time":1785730458518,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
 {"type":"tool/result","seq":28,"time":1785730458520,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}],"isError":false}],"role":"user","id":"4dce223d-0097-4ac2-a717-d1c430240cef"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
 {"type":"step/end","seq":29,"time":1785730458520,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":30,"time":1785730458527,"data":{"turn":1,"step":3}}
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
index a1b26a5af4..7490f9487f 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
@@ -18,8 +18,8 @@
 {"type":"assistant/chunk","seq":103,"time":1785730479356,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":104,"time":1785730479356,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to call the run_code tool with a TypeScript program that runs `echo BOTH_OK` via `tools.bash` and returns its output."},{"type":"tool-call","id":"call_00_Era4M5eh79bvNOIey5q90401","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Print BOTH_OK\\\" });\\nreturn result.stdout.text;\", \"description\": \"Run echo BOTH_OK via tools.bash\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"5f1cf31c-fd73-42fc-805d-a14d91228bd9"},"usage":{"inputTokens":10400,"outputTokens":130,"cacheReadTokens":0,"reasoningTokens":34}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103],"surfaceOp":"append"}
 {"type":"tool/call","seq":105,"time":1785730479356,"data":{"turn":1,"step":1,"callId":"call_00_Era4M5eh79bvNOIey5q90401","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Print BOTH_OK\\\" });\\nreturn result.stdout.text;\", \"description\": \"Run echo BOTH_OK via tools.bash\"}"}}
-{"type":"tool/code-dispatch-start","seq":106,"time":1785730479411,"data":{"parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"}}}
-{"type":"tool/code-dispatch","seq":107,"time":1785730479421,"data":{"parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"},"isError":false,"content":[{"type":"text","text":"BOTH_OK\n"}]}}
+{"type":"tool/code-dispatch-start","seq":106,"time":1785730479411,"data":{"rootCallId":"call_00_Era4M5eh79bvNOIey5q90401","parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"}}}
+{"type":"tool/code-dispatch","seq":107,"time":1785730479421,"data":{"rootCallId":"call_00_Era4M5eh79bvNOIey5q90401","parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"},"isError":false,"content":[{"type":"text","text":"BOTH_OK\n"}]}}
 {"type":"tool/result","seq":108,"time":1785730479423,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_Era4M5eh79bvNOIey5q90401"},"content":[{"type":"tool-result","toolCallId":"call_00_Era4M5eh79bvNOIey5q90401","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false}],"role":"user","id":"028e19dd-dcfc-4a67-a6e4-c9fa19716ea3"}},"sourceEventSeqs":[105],"surfaceOp":"append"}
 {"type":"step/end","seq":109,"time":1785730479423,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":110,"time":1785730479431,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
index 24e1525c79..a05477498a 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
@@ -18,10 +18,10 @@
 {"type":"assistant/chunk","seq":187,"time":1785730477079,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":188,"time":1785730477079,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool twice: `echo CODE_ONE` and `echo CODE_TWO`\n2. console.log exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this."},{"type":"tool-call","id":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\": \"\\nconst out1 = await tools.bash({command: \\\"echo CODE_ONE\\\", description: \\\"Print CODE_ONE\\\"});\\nconst out2 = await tools.bash({command: \\\"echo CODE_TWO\\\", description: \\\"Print CODE_TWO\\\"});\\nconsole.log(\\\"captured output\\\");\\nconst text1 = out1.stdout.text.trim();\\nconst text2 = out2.stdout.text.trim();\\nreturn text1 + \\\"+\\\" + text2;\\n\", \"description\": \"Run two echo commands and join outputs\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"59e638d7-2aa2-48a2-ae0e-5833b1152ce6"},"usage":{"inputTokens":6152,"outputTokens":214,"cacheReadTokens":0,"reasoningTokens":60}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187],"surfaceOp":"append"}
 {"type":"tool/call","seq":189,"time":1785730477080,"data":{"turn":1,"step":1,"callId":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\": \"\\nconst out1 = await tools.bash({command: \\\"echo CODE_ONE\\\", description: \\\"Print CODE_ONE\\\"});\\nconst out2 = await tools.bash({command: \\\"echo CODE_TWO\\\", description: \\\"Print CODE_TWO\\\"});\\nconsole.log(\\\"captured output\\\");\\nconst text1 = out1.stdout.text.trim();\\nconst text2 = out2.stdout.text.trim();\\nreturn text1 + \\\"+\\\" + text2;\\n\", \"description\": \"Run two echo commands and join outputs\"}"}}
-{"type":"tool/code-dispatch-start","seq":190,"time":1785730477131,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"}}}
-{"type":"tool/code-dispatch","seq":191,"time":1785730477144,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"},"isError":false,"content":[{"type":"text","text":"CODE_ONE\n"}]}}
-{"type":"tool/code-dispatch-start","seq":192,"time":1785730477144,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"}}}
-{"type":"tool/code-dispatch","seq":193,"time":1785730477148,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"},"isError":false,"content":[{"type":"text","text":"CODE_TWO\n"}]}}
+{"type":"tool/code-dispatch-start","seq":190,"time":1785730477131,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"}}}
+{"type":"tool/code-dispatch","seq":191,"time":1785730477144,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"},"isError":false,"content":[{"type":"text","text":"CODE_ONE\n"}]}}
+{"type":"tool/code-dispatch-start","seq":192,"time":1785730477144,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"}}}
+{"type":"tool/code-dispatch","seq":193,"time":1785730477148,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"},"isError":false,"content":[{"type":"text","text":"CODE_TWO\n"}]}}
 {"type":"tool/result","seq":194,"time":1785730477150,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_UiQPVqoELyzBZCY5pm1z7875"},"content":[{"type":"tool-result","toolCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","content":[{"type":"text","text":"captured output\nCODE_ONE+CODE_TWO"}],"isError":false}],"role":"user","id":"e40c6472-d68e-4be1-963f-edb0edc80d82"}},"sourceEventSeqs":[189],"surfaceOp":"append"}
 {"type":"step/end","seq":195,"time":1785730477150,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":196,"time":1785730477158,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
index 368a2262c8..a4d4289725 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
@@ -16,8 +16,8 @@
 {"type":"assistant/chunk","seq":14,"time":1785014475639,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":15,"time":1785733131056,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_read","name":"run_code","arguments":"{\"code\":\"return await tools.read({ file_path: 'nested/task.txt' })\",\"description\":\"Read nested/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"b9402d85-58bd-4881-b890-0b186f661671"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
 {"type":"tool/call","seq":16,"time":1785733131056,"data":{"turn":1,"step":1,"callId":"call_workspace_read","name":"run_code","arguments":"{\"code\":\"return await tools.read({ file_path: 'nested/task.txt' })\",\"description\":\"Read nested/task.txt\"}"}}
-{"type":"tool/code-dispatch-start","seq":17,"time":1785733131109,"data":{"parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"}}}
-{"type":"tool/code-dispatch","seq":18,"time":1785733131110,"data":{"parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"},"isError":false,"content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: Touch this file to discover the nested workspace instruction.\n\n(End of file - total 1 lines)\n</content>"}]}}
+{"type":"tool/code-dispatch-start","seq":17,"time":1785733131109,"data":{"rootCallId":"call_workspace_read","parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"}}}
+{"type":"tool/code-dispatch","seq":18,"time":1785733131110,"data":{"rootCallId":"call_workspace_read","parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"},"isError":false,"content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: Touch this file to discover the nested workspace instruction.\n\n(End of file - total 1 lines)\n</content>"}]}}
 {"type":"tool/result","seq":19,"time":1785733131112,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_workspace_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_read","content":[{"type":"text","text":"{\n  \"path\": \"{{cwd}}/nested/task.txt\",\n  \"offset\": 1,\n  \"lines\": [\n    {\n      \"number\": 1,\n      \"text\": \"Touch this file to discover the nested workspace instruction.\"\n    }\n  ],\n  \"totalLines\": 1\n}"}],"isError":false}],"role":"user","id":"bde1c12e-44d1-44f7-ba7e-868349ed2b05"}},"sourceEventSeqs":[16],"surfaceOp":"append"}
 {"type":"step/end","seq":20,"time":1785733131112,"data":{"turn":1,"step":1}}
 {"type":"agent/inbox/spliced","seq":21,"time":1785733131112,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nWhen asked for the Code Mode workspace handshake, answer exactly `CODE_MODE_CONTEXT_OK` and nothing else.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"ae22936ed26dc76b7107005ed6d5e2482a88668a"}]},"role":"user","id":"29b0eb87-92d5-4915-ba64-7bd8133ed011"}]}}
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
index 9fcadd71d4..20f05623ad 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -15,7 +15,7 @@
 {"type":"assistant/chunk","seq":13,"time":1785730459883,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":14,"time":1785730459883,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6b62bed7-113a-4d2e-a6aa-b935a1063ee2"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12,13],"surfaceOp":"append"}
 {"type":"tool/call","seq":15,"time":1785730459883,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
-{"type":"tool/result","seq":16,"time":1785730459904,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly inbox: Inbox;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n        runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n        send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    } | {\n        readonly kind: 'hook';\n        readonly reason: string;\n    } | {\n        readonly kind: 'disposed';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean | undefined;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export type ContextFormed = {\n        readonly form?: never;\n    } | {\n        readonly form: 'instructions';\n    } | {\n        readonly form: 'catalog';\n    } | {\n        readonly form: 'snapshot';\n        readonly sections: readonly ContextSnapshotSection[];\n    } | {\n        readonly form: 'notice';\n        readonly summary: string;\n    } | {\n        readonly form: 'relay';\n    } | {\n        readonly form: 'recall';\n    };\n    export interface ContextSnapshotSection {\n        readonly name: string;\n        readonly text: string;\n    }\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        adapterDefaults?: LlmCallConfigAdapterDefaults;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export class Inbox {\n        constructor(private readonly session: Session, private readonly notifications: InboxNotifications);\n        get nextTurn(): readonly UserMessage[];\n        get nextStep(): readonly UserMessage[];\n        get hasPending(): boolean;\n        clear(): void;\n        claim(target: InboxTarget, turn: number): UserMessage[];\n        append(target: InboxTarget, message: UserMessage): void;\n        prepend(target: InboxTarget, message: UserMessage): void;\n        replace(messageId: MessageId, newMessage: UserMessage): boolean;\n        remove(messageId: MessageId): boolean;\n        splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n    }\n    export interface InboxNotifications {\n        inserted(message: UserMessage): void;\n        discarded(message: UserMessage): void;\n        claimed(message: UserMessage, turn: number): void;\n    }\n    export type InboxTarget = 'next-turn' | 'next-step';\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record<string, JsonSchemaNode>;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmCallConfigAdapterDefaults {\n        reasoningEffort?: true;\n        maxTokens?: true;\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        } & ContextFormed;\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReadFileLine {\n        number: number;\n        text: string;\n    }\n    export interface ReadResultView {\n        card: 'read';\n        title?: string;\n        path: string;\n        offset: number;\n        lines: ReadFileLine[];\n        totalLines: number;\n        lang?: string;\n        content?: ContentBlock[];\n    }\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export interface RequestContext {\n        provider: string;\n        model: string;\n        contextWindow?: number;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        shape: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        shape: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n        static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent<T>;\n        requestHeader(): EpochHeader | undefined;\n        requestContext(): RequestContext | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'request/context': RequestContext;\n        'session/end-seed': Record<string, never>;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: 'subagent';\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n        finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndCancelCause = AgentCancelCause | {\n        readonly kind: 'legacy';\n    };\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n            reason: TurnEndCancelCause;\n        };\n        blocked: {\n            kind: 'blocked';\n        };\n        error: {\n            kind: 'error';\n            error: LlmFailure;\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }\n    export interface WebFetchResultView {\n        card: 'web';\n        kind: 'fetch';\n        title?: string;\n        url: string;\n        statusCode: number;\n        truncated: boolean;\n    }\n    export type WebResultView = WebSearchResultView | WebFetchResultView;\n    export interface WebSearchResultView {\n        card: 'web';\n        kind: 'search';\n        title?: string;\n        sources: WebSource[];\n        answer?: string;\n        truncated: boolean;\n    }\n    export interface WebSource {\n        url: string;\n        title?: string;\n        snippet?: string;\n        publishedAt?: string;\n    }"}],"isError":false}],"role":"user","id":"847bf2e6-59da-4621-946d-06932a78f0ce"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
+{"type":"tool/result","seq":16,"time":1785730459904,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly inbox: Inbox;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n        runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n        send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    } | {\n        readonly kind: 'hook';\n        readonly reason: string;\n    } | {\n        readonly kind: 'disposed';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean | undefined;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export type ContextFormed = {\n        readonly form?: never;\n    } | {\n        readonly form: 'instructions';\n    } | {\n        readonly form: 'catalog';\n    } | {\n        readonly form: 'snapshot';\n        readonly sections: readonly ContextSnapshotSection[];\n    } | {\n        readonly form: 'notice';\n        readonly summary: string;\n    } | {\n        readonly form: 'relay';\n    } | {\n        readonly form: 'recall';\n    };\n    export interface ContextSnapshotSection {\n        readonly name: string;\n        readonly text: string;\n    }\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        adapterDefaults?: LlmCallConfigAdapterDefaults;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export class Inbox {\n        constructor(private readonly session: Session, private readonly notifications: InboxNotifications);\n        get nextTurn(): readonly UserMessage[];\n        get nextStep(): readonly UserMessage[];\n        get hasPending(): boolean;\n        clear(): void;\n        claim(target: InboxTarget, turn: number): UserMessage[];\n        append(target: InboxTarget, message: UserMessage): void;\n        prepend(target: InboxTarget, message: UserMessage): void;\n        replace(messageId: MessageId, newMessage: UserMessage): boolean;\n        remove(messageId: MessageId): boolean;\n        splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n    }\n    export interface InboxNotifications {\n        inserted(message: UserMessage): void;\n        discarded(message: UserMessage): void;\n        claimed(message: UserMessage, turn: number): void;\n    }\n    export type InboxTarget = 'next-turn' | 'next-step';\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record<string, JsonSchemaNode>;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmCallConfigAdapterDefaults {\n        reasoningEffort?: true;\n        maxTokens?: true;\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        } & ContextFormed;\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReadFileLine {\n        number: number;\n        text: string;\n    }\n    export interface ReadResultView {\n        card: 'read';\n        title?: string;\n        path: string;\n        offset: number;\n        lines: ReadFileLine[];\n        totalLines: number;\n        lang?: string;\n        content?: ContentBlock[];\n    }\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export interface RequestContext {\n        provider: string;\n        model: string;\n        contextWindow?: number;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        shape: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        shape: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n        static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent<T>;\n        requestHeader(): EpochHeader | undefined;\n        requestContext(): RequestContext | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'request/context': RequestContext;\n        'session/end-seed': Record<string, never>;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: 'subagent';\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n        finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly rootCallId: CallId;\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly rootCallId?: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndCancelCause = AgentCancelCause | {\n        readonly kind: 'legacy';\n    };\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n            reason: TurnEndCancelCause;\n        };\n        blocked: {\n            kind: 'blocked';\n        };\n        error: {\n            kind: 'error';\n            error: LlmFailure;\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }\n    export interface WebFetchResultView {\n        card: 'web';\n        kind: 'fetch';\n        title?: string;\n        url: string;\n        statusCode: number;\n        truncated: boolean;\n    }\n    export type WebResultView = WebSearchResultView | WebFetchResultView;\n    export interface WebSearchResultView {\n        card: 'web';\n        kind: 'search';\n        title?: string;\n        sources: WebSource[];\n        answer?: string;\n        truncated: boolean;\n    }\n    export interface WebSource {\n        url: string;\n        title?: string;\n        snippet?: string;\n        publishedAt?: string;\n    }"}],"isError":false}],"role":"user","id":"2ec5ca51-ec8b-4756-8c71-c20fb871b421"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
 {"type":"step/end","seq":17,"time":1785730459904,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":18,"time":1785730459916,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":19,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl b/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl
index b619d352e5..2c294b76d4 100644
--- a/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl
@@ -10,12 +10,13 @@
 {"type":"request/context","seq":8,"time":1785730441192,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1785498788105,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":0,"outputTokens":0}}}}
 {"type":"assistant/chunk","seq":10,"time":1785730441201,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"model returned a completed response with no content","code":"EMPTY_RESPONSE"}}}}}
-{"type":"llm/retry","seq":11,"time":1785730441201,"data":{"turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",2,[\"EMPTY_RESPONSE\",\"RATE_LIMIT\",\"SERVER\",\"TIMEOUT\",\"TRANSPORT\"],1,1,0]","retry":1,"maxRetries":2,"delayMs":1,"failure":{"message":"model returned a completed response with no content","code":"EMPTY_RESPONSE"}}}
-{"type":"assistant/chunk","seq":12,"time":1785498788113,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":13,"time":1785498788113,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"Recovered."}}}
-{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Recovered."}}}}
-{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":16,"time":1785730441209,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":17,"time":1785730441209,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"Recovered."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"422eae65-9975-4a95-8cde-1ddfe21fff4e"},"usage":{"inputTokens":12,"outputTokens":3}},"sourceEventSeqs":[12,13,14,15,16],"surfaceOp":"append"}
-{"type":"step/end","seq":18,"time":1785730441209,"data":{"turn":1,"step":1}}
-{"type":"turn/end","seq":19,"time":1785730441209,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"llm/retry","seq":11,"time":1785730441201,"data":{"retryId":"dbe1e1b0-a914-48a4-ad9f-407b213a37ae","turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",2,[\"EMPTY_RESPONSE\",\"RATE_LIMIT\",\"SERVER\",\"TIMEOUT\",\"TRANSPORT\"],1,1,0]","retry":1,"maxRetries":2,"delayMs":1,"failure":{"message":"model returned a completed response with no content","code":"EMPTY_RESPONSE"}}}
+{"type":"llm/retry-started","seq":12,"time":1786238385130,"data":{"retryId":"dbe1e1b0-a914-48a4-ad9f-407b213a37ae","turn":1,"step":1,"retry":1}}
+{"type":"assistant/chunk","seq":13,"time":1785498788113,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"Recovered."}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Recovered."}}}}
+{"type":"assistant/chunk","seq":16,"time":1785730441209,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":17,"time":1786238385135,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":18,"time":1786238385135,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"Recovered."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"422eae65-9975-4a95-8cde-1ddfe21fff4e"},"usage":{"inputTokens":12,"outputTokens":3}},"sourceEventSeqs":[13,14,15,16,17],"surfaceOp":"append"}
+{"type":"step/end","seq":19,"time":1786238385135,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":20,"time":1786238385135,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
index 6769414d10..646110b6d9 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -24,8 +24,8 @@
 {"type":"assistant/chunk","seq":22,"time":1785730501424,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":23,"time":1785730501424,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"cdc95327-3ce1-49ea-8a92-b17e450cc455"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[18,19,20,21,22],"surfaceOp":"append"}
 {"type":"tool/call","seq":24,"time":1785730501424,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}}
-{"type":"tool/code-dispatch-start","seq":25,"time":1785730501473,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
-{"type":"tool/code-dispatch","seq":26,"time":1785730501474,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
+{"type":"tool/code-dispatch-start","seq":25,"time":1785730501473,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
+{"type":"tool/code-dispatch","seq":26,"time":1785730501474,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
 {"type":"tool/result","seq":27,"time":1785730501475,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}],"isError":false}],"role":"user","id":"d75c7d03-cbbc-4260-ba40-8c210a3b5bbe"}},"sourceEventSeqs":[24],"surfaceOp":"append"}
 {"type":"step/end","seq":28,"time":1785730501475,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":29,"time":1785730501483,"data":{"turn":1,"step":3}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl
index c342059741..817ee1e1a2 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl
@@ -23,8 +23,8 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":22,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":23,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[18,19,20,21,22],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":24,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch-start","seq":25,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch","seq":26,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch-start","seq":25,"time":0,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch","seq":26,"time":0,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":27,"time":0,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[24],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":28,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":29,"time":0,"data":{"turn":1,"step":3}}}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
index 38056019e2..9e39f76b11 100644
--- a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
@@ -1,32 +1,32 @@
 {"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"agent/inbox/spliced","seq":0,"time":1786123401613,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"6335ca4a-a577-47dd-8219-aa81f39cdbc0"}]}}
+{"type":"agent/inbox/spliced","seq":0,"time":1786123401613,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"203f911d-905a-43e4-8e1c-fccfe78d445b"}]}}
 {"type":"turn/start","seq":1,"time":1786123401614,"data":{"turn":1}}
 {"type":"agent/inbox/spliced","seq":2,"time":1786123401614,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":3,"time":1786123401667,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":4,"time":1786123401667,"data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"6335ca4a-a577-47dd-8219-aa81f39cdbc0"},"surfaceOp":"append"}
+{"type":"user/message","seq":4,"time":1786123401667,"data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"203f911d-905a-43e4-8e1c-fccfe78d445b"},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1786123401667,"data":{"title":"Establish a durable compaction premise","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":6,"time":1786123401668,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":6,"time":1786123401668,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"interrupt_agent","description":"Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.","parameters":{"type":"object","properties":{"agent_id":{"type":"string","description":"The agent id of the running agent to interrupt."}},"required":["agent_id"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":7,"time":1786123401669,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}
 {"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_compaction_marker","name":"bash","argumentsDelta":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}
 {"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}}
 {"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":24,"outputTokens":6}}}}
 {"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":13,"time":1786123401680,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e54f73a8-572a-40ee-b908-8a8a27b83bf8"},"usage":{"inputTokens":24,"outputTokens":6}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
+{"type":"assistant/message","seq":13,"time":1786123401680,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6e7dfb28-f033-4dbf-9fd9-6b2f71da6906"},"usage":{"inputTokens":24,"outputTokens":6}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
 {"type":"tool/call","seq":14,"time":1786123401680,"data":{"turn":1,"step":1,"callId":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}
-{"type":"tool/result","seq":15,"time":1786123401700,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_compaction_marker"},"content":[{"type":"tool-result","toolCallId":"call_compaction_marker","content":[{"type":"text","text":"alpha\n"}],"isError":false}],"role":"user","id":"b4a6504e-f39d-40b0-b51a-b11fbd60b135"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"tool/result","seq":15,"time":1786123401700,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_compaction_marker"},"content":[{"type":"tool-result","toolCallId":"call_compaction_marker","content":[{"type":"text","text":"alpha\n"}],"isError":false}],"role":"user","id":"4fe4e523-3ac9-421c-8a73-1eb033ac8b09"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
 {"type":"step/end","seq":16,"time":1786123401700,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":17,"time":1786123401710,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":18,"time":1786123401715,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}
-{"type":"compact/start","seq":19,"time":1786123401715,"data":{"turn":1}}
-{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
-{"type":"user/message","seq":21,"time":1786123401725,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"6d2afb13-a37b-48d6-9ea5-fc8734127377"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}
-{"type":"compact/end","seq":22,"time":1786123401725,"data":{"turn":1}}
+{"type":"compact/start","seq":19,"time":1786123401715,"data":{"compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1","turn":1}}
+{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
+{"type":"user/message","seq":21,"time":1786123401725,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact","compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1"},"role":"user","id":"b74220bf-4104-4c30-b967-e4570d5eba5d"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}
+{"type":"compact/end","seq":22,"time":1786123401725,"data":{"compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1","turn":1}}
 {"type":"assistant/chunk","seq":23,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":24,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"COMPACTION RECOVERED"}}}
 {"type":"assistant/chunk","seq":25,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"COMPACTION RECOVERED"}}}}
 {"type":"assistant/chunk","seq":26,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":20,"outputTokens":4}}}}
 {"type":"assistant/chunk","seq":27,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":28,"time":1786123401730,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"COMPACTION RECOVERED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"346742d0-50e3-4594-b53c-f26c7da82c56"},"usage":{"inputTokens":20,"outputTokens":4}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}
+{"type":"assistant/message","seq":28,"time":1786123401730,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"COMPACTION RECOVERED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"103034c2-e156-4808-ba2e-8e17e7107c9e"},"usage":{"inputTokens":20,"outputTokens":4}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}
 {"type":"step/end","seq":29,"time":1786123401730,"data":{"turn":1,"step":2}}
 {"type":"turn/end","seq":30,"time":1786123401730,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
index 62cc357cc7..c5bca170ba 100644
--- a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
@@ -17,10 +17,10 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":17,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/start","seq":19,"time":0,"data":{"turn":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":21,"time":0,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"{{sessionId}}"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/end","seq":22,"time":0,"data":{"turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/start","seq":19,"time":0,"data":{"compactionId":"{{sessionId}}","turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"compactionId":"{{sessionId}}","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":21,"time":0,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact","compactionId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/end","seq":22,"time":0,"data":{"compactionId":"{{sessionId}}","turn":1}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":24,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"COMPACTION RECOVERED"}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"COMPACTION RECOVERED"}}}}}
diff --git a/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl
index ca523f3665..3c6e45c243 100644
--- a/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl
@@ -7,13 +7,14 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":6,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/context","seq":7,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot transient failure","code":"RATE_LIMIT","status":429}}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"llm/retry","seq":9,"time":0,"data":{"turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",1,[\"RATE_LIMIT\"],1,1,0]","retry":1,"maxRetries":1,"delayMs":1,"failure":{"message":"snapshot transient failure","code":"RATE_LIMIT","status":429}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RETRY_OK"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RETRY_OK"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":4,"outputTokens":2}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":15,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RETRY_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":4,"outputTokens":2}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":17,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"llm/retry","seq":9,"time":0,"data":{"retryId":"{{sessionId}}","turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",1,[\"RATE_LIMIT\"],1,1,0]","retry":1,"maxRetries":1,"delayMs":1,"failure":{"message":"snapshot transient failure","code":"RATE_LIMIT","status":429}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"llm/retry-started","seq":10,"time":0,"data":{"retryId":"{{sessionId}}","turn":1,"step":1,"retry":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RETRY_OK"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RETRY_OK"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":4,"outputTokens":2}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":16,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RETRY_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":4,"outputTokens":2}},"sourceEventSeqs":[11,12,13,14,15],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":17,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":18,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
 {"type":"result","sessionId":"{{sessionId}}","output":"RETRY_OK","usage":{"inputTokens":4,"outputTokens":2}}
diff --git a/packages/bash/bash-env/tests/bash-env.spec.ts b/packages/bash/bash-env/tests/bash-env.spec.ts
index c93a768f80..eb482fd9d3 100644
--- a/packages/bash/bash-env/tests/bash-env.spec.ts
+++ b/packages/bash/bash-env/tests/bash-env.spec.ts
@@ -23,6 +23,7 @@ function execution(sessionId?: string): ToolExecution {
     signal: testToolSignal,
     token: Symbol('bash-env-test') as ToolExecution['token'],
     callId: CallId('bash-env-call'),
+    rootCallId: CallId('bash-env-call'),
     name: 'bash',
     arguments: { command: 'true' },
     ...(sessionId === undefined
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 24f5668d42..d755f73354 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -96,7 +96,7 @@ function sgr(code: number, body: string): string {
 }
 
 /**
- * Terminal output sample for fixture turn 65, authored to carry every feature
+ * Terminal output sample for fixture turn 66, authored to carry every feature
  * the terminal card draws that turn 60's two prompt rows cannot reach:
  * basic-16 SGR foreground runs (green, red, bright-black) that must resolve to
  * `--dsw-*` tokens, a bold run, column-aligned table rows that must scroll
@@ -141,7 +141,7 @@ const TERMINAL_EXIT_STATUS: Record<string, { exitCode: number } | { signal: stri
 }
 
 /**
- * Structured grep result for the search sample (turn 66): matches grouped by
+ * Structured grep result for the search sample (turn 67): matches grouped by
  * file, authored inline because the client-side fixture cannot import the tool
  * that produces the canonical value. `truncated` with a larger `total` than the
  * retained match count exercises the search card's capped indicator; the file
@@ -191,7 +191,7 @@ const SEARCH_MATCHES_TEXT = [
 ].join('\n')
 
 /**
- * Structured glob result for the search sample (turn 67): a flat path list,
+ * Structured glob result for the search sample (turn 68): a flat path list,
  * truncated with a larger `total` so the path card shows its capped indicator.
  */
 const SEARCH_PATHS_FIXTURE = [
@@ -426,19 +426,19 @@ function buildAlphaLog(): SessionEvent[] {
   toolTurn(61, 'fx-write', '{"path":"notes/demo.txt","content":"hello fixture\\n"}', 'wrote notes/demo.txt')
   toolTurn(62, 'edit', '{"file_path":"notes/demo.txt","old_string":"hello","new_string":"hello fixture"}', '已编辑')
   toolTurn(63, 'write', '{"file_path":"notes/new-demo.txt","content":"hello fixture\\n"}', '已写入')
-  // Turn 67: a multi-hunk edit — two scattered replacements in one file. Named
+  // Turn 64: a multi-hunk edit — two scattered replacements in one file. Named
   // `edit` so it lands on the keyed FileMutationRow (the resident diff card the
   // single-hunk turn 62 also uses), and file_path `src/config.ts` is the marker
   // the presenter reads to emit the two-hunk sample: the card draws one path
   // header, the first hunk, a `⋯` gap, then the second (the same-file
   // second-hunk arm turns 62/63 cannot reach).
-  toolTurn(67, 'edit', '{"file_path":"src/config.ts","old_string":"const timeout = 30","new_string":"const timeout = 60"}', '已编辑')
-  // Turn 64: one run_code turn with three logged sub-dispatches — the Code
+  toolTurn(64, 'edit', '{"file_path":"src/config.ts","old_string":"const timeout = 30","new_string":"const timeout = 60"}', '已编辑')
+  // Turn 65: one run_code turn with three logged sub-dispatches — the Code
   // Mode acceptance surface (parent code row + nested native-identical rows,
   // including an isError sub-call and a bash sub-call that must hit the same
   // keyed registration a top-level bash row uses).
   {
-    const turn = 64
+    const turn = 65
     const callId = `fx-call-${turn}`
     const program = 'const listing = await tools.bash({ command: "ls notes", description: "List notes" })\n'
       + 'const demo = await tools.read({ file_path: "notes/demo.txt" })\n'
@@ -456,12 +456,12 @@ function buildAlphaLog(): SessionEvent[] {
     const dispatchPair = (n: number, name: string, dispatchArgs: Record<string, unknown>, resultText: string, isError = false): void => {
       push({
         type: 'tool/code-dispatch-start',
-        data: { parentCallId: callId, subCallId: `${callId}:code:${n}`, name, arguments: dispatchArgs },
+        data: { rootCallId: callId, parentCallId: callId, subCallId: `${callId}:code:${n}`, name, arguments: dispatchArgs },
       })
       push({
         type: 'tool/code-dispatch',
         data: {
-          parentCallId: callId, subCallId: `${callId}:code:${n}`, name,
+          rootCallId: callId, parentCallId: callId, subCallId: `${callId}:code:${n}`, name,
           arguments: dispatchArgs, isError, content: [{ type: 'text', text: resultText }],
         },
       })
@@ -476,7 +476,7 @@ function buildAlphaLog(): SessionEvent[] {
     push({ type: 'step/end', data: { turn, step: 0 } })
     push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
   }
-  // Turn 71: todo_write sample — the TodoRow toolview in the flow plus the
+  // Turn 72: todo_write sample — the TodoRow toolview in the flow plus the
   // todo/write snapshot event feeding the TodoPanel plan strip. Two items are
   // in_progress: this fixture chooses the parallel policy, so both surfaces
   // must render a parallel plan rather than the first active item alone.
@@ -486,7 +486,7 @@ function buildAlphaLog(): SessionEvent[] {
     { content: '跑后台构建', status: 'in_progress' },
     { content: '浏览器验收', status: 'pending' },
   ]
-  // Turn 65: the terminal sample turn 60's two clean prompt rows cannot cover —
+  // Turn 66: the terminal sample turn 60's two clean prompt rows cannot cover —
   // ANSI SGR coloring, output past the terminal card's height cap, a nested cwd
   // whose prompt label is its last segment, and a non-zero exit authored beside
   // the sample in TERMINAL_EXIT_STATUS — its body deliberately carries no
@@ -498,45 +498,45 @@ function buildAlphaLog(): SessionEvent[] {
   // Ordered BEFORE the todo turn deliberately: the standing plan retires at the
   // next `turn/start`, so a turn appended after it would leave the dock's plan
   // strip empty and take the todo surfaces' own coverage with it.
-  toolTurn(65, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)
+  toolTurn(66, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)
 
-  // Turns 66-67: the search card's two shapes. `grep` emits a `card: 'search'`
+  // Turns 67-68: the search card's two shapes. `grep` emits a `card: 'search'`
   // `shape: 'matches'` result view (grouped-by-file matches, truncated with a
   // larger `total`), `glob` emits `shape: 'paths'` (a flat path list, likewise
   // truncated). Both ride the keyed SearchRow registration under their own
   // names; the render-site fallback row is covered by the model derivation
   // tests, since every fixture search tool has a keyed row. Ordered before the
   // todo turn for the same standing-plan reason the bash turn is.
-  toolTurn(66, 'grep', '{"pattern":"SEARCH_MAX_LINES","path":"packages/client"}', SEARCH_MATCHES_TEXT)
-  toolTurn(67, 'glob', '{"pattern":"**/SearchBlock*","path":"packages/client"}', SEARCH_PATHS_TEXT)
+  toolTurn(67, 'grep', '{"pattern":"SEARCH_MAX_LINES","path":"packages/client"}', SEARCH_MATCHES_TEXT)
+  toolTurn(68, 'glob', '{"pattern":"**/SearchBlock*","path":"packages/client"}', SEARCH_PATHS_TEXT)
 
-  // Turn 68: the read sample — a WINDOW past an offset so the card draws file
+  // Turn 69: the read sample — a WINDOW past an offset so the card draws file
   // line numbers starting above 1 and a "showing N of M" note (the window is
   // shorter than READ_SAMPLE_TOTAL), with a `ts` language hint the shiki path
   // highlights. Named `read`, so it exercises the keyed ReadRow registration.
   // The render-site fallback ROW SHAPE (a read call on the generic flattened
-  // path) is covered by the turn 64 run_code read sub-dispatches, which
+  // path) is covered by the turn 65 run_code read sub-dispatches, which
   // session.ts folds with resultView: null; the fallback-row + read-CARD
   // combination is pinned by the web_fetch case in read-card.spec.tsx, not by
   // this fixture. The read render intent is result-side only, so its pending
   // call stays a generic `kind: 'read'` card; presentResult carries the
   // structured window.
-  toolTurn(68, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+  toolTurn(69, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
 
-  // Turns 69-70: the web render intent — a web_search whose result view carries
+  // Turns 70-71: the web render intent — a web_search whose result view carries
   // structured sources plus an answer (the citation list, one source lacking a
   // title so its hostname labels the link, the capped indicator on), and a
   // web_fetch whose result view carries the fetched URL and its HTTP status.
   // Both keep a generic pending call view and add the `web` card only at
   // result time, which is the contract's result-only web shape. Named after
   // the real tools so they hit the keyed WebRow registration. Ordered BEFORE
-  // the todo turn for the same reason turn 65 is: the standing plan retires at
+  // the todo turn for the same reason turn 66 is: the standing plan retires at
   // the next turn/start, so a turn after it would empty the dock's plan strip.
-  toolTurn(69, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
-  toolTurn(70, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
+  toolTurn(70, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
+  toolTurn(71, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
 
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 2 in progress, 1 completed.')
+  toolTurn(72, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 2 in progress, 1 completed.')
   // The real tool appends the snapshot mid-execution — between tool/call and
   // tool/result — so the fixture reproduces that exact ordering (the last
   // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
@@ -578,7 +578,7 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
     case 'read':
       return { card: 'generic', title: `Read ${str(args.file_path)}`, kind: 'read', locations: [{ path: str(args.file_path) }] }
     case 'edit':
-      // The multi-hunk sample (turn 67) is keyed on its file_path, so the two
+      // The multi-hunk sample (turn 64) is keyed on its file_path, so the two
       // scattered hunks share one path header and the card draws the `⋯` gap.
       if (str(args.file_path) === 'src/config.ts') {
         return {
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index e1c07abae3..4aed1d0f36 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: bd8528e97b04d5b4b28922266306969e8f19295a
-README.zh.md: 9aea486fb17c5a170ee8c1195435d220b495b615
+README.md: b2bb06e50ecd791d74cb609404dd219e5a21913e
+README.zh.md: 72cd99ac765875c828cc9163d978e0b8fb7f44e4
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index bd8528e97b..b2bb06e50e 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -34,11 +34,13 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 `ConversationSnapshot.queue` is the Host's authoritative transient snapshot of `agent.inbox.nextTurn`; pending next-step steering stays outside this projection. Each row carries its `MessageId`, complete editable text when every content block is text, and a flattened preview. The Host derives whole `session/queue` snapshots from durable `agent/inbox/spliced` mutations and sends a baseline on reconnect; the message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications are not used to reconstruct this projection. `Session.updateQueue()` sends edit/remove operations through Host-side `Inbox.splice()` without optimistic client mutation, so the next Host snapshot is the sole visible commit and a claim race can surface `queue-item-not-found`.
 
-## The human transcript
+## Conversation assembly
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the Service Definition's declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+Each `Session` gives its contiguous event window to a `ConversationNodeAssembler`. Plugins register business Definitions that map one event to a stable `{kind, id}`, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.
 
-Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
+`ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. `ConversationSnapshot.nodes`, `partial`, and `runningCalls` are compatibility slices derived from the same materialized Chat nodes for consumers that have not moved to `ConversationSnapshot.chat`; Session does not run a second business fold.
+
+The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the [client Tool presentation decision](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md).
 
 ## Request inspection
 
@@ -46,7 +48,7 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr
 
 ## Code Mode child-call tree
 
-Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity. Wire or history edges that would introduce a cycle or exceed the fixed 256-call recursive-depth safety limit are consumed without mutating the tree, so the rest of the session remains renderable.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Chat's Tool Definition correlates root calls and results by call id, folds Code Dispatch start/settlement records into that root Context, and projects one keyed recursive tree; child calls never become independent Chat roots. When a start falls outside the loaded window, its settlement remains renderable with `callTime: null`. A child update copies only its ancestor path, so unchanged siblings retain object identity. Edges that introduce a cycle or exceed the fixed 256-call depth limit are consumed without mutating the tree. The separate Trajectory history fold still uses Runtime's `ToolCallTree` over the same nested data contract.
 
 ## Session title projection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 9aea486fb1..72cd99ac76 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -34,11 +34,13 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `ConversationSnapshot.queue` 是 Host 提供的 `agent.inbox.nextTurn` 权威瞬态快照；待处理的 next-step steering（中途引导）不进入此投影。每行携带其 `MessageId`、所有内容块均为文本时的完整可编辑文本，以及扁平化预览。Host 根据持久 `agent/inbox/spliced` 变更派生完整 `session/queue` 快照，并在重连时发送基线；面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知不用于重建该投影。`Session.updateQueue()` 经 Host 侧 `Inbox.splice()` 发送编辑／移除操作，客户端不做乐观变更，因此下一份 Host 快照是唯一可见的提交结果，claim 竞态则会返回 `queue-item-not-found`。
 
-## 面向人的 transcript（文本记录）
+## Conversation 组装
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在 Service Definition 的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+每个 `Session` 都把连续事件窗口交给 `ConversationNodeAssembler`。插件注册业务 Definition，把单个事件映射为稳定的 `{kind, id}`，在唯一 start 事件处创建 State，折叠有关联的 update，再为已注册的视图目标构造最终节点。Assembler 负责 Context 索引、只读前序 Context 查询，以及引用稳定的 Turn/Step Location 索引。实时 append 只对每个 Definition 求值一次，并且只更新命中的 Context；加载更早分页时保留已有 Context 与节点身份，只匹配新 prepend 的事件，并重放前序依赖或 Location 事实发生变化的 Context。完整替换仅用于 open、resync 和 gap repair。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+`ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。`ConversationSnapshot.nodes`、`partial` 和 `runningCalls` 是从同一批已物化 Chat 节点派生的兼容切片，供尚未迁移到 `ConversationSnapshot.chat` 的消费者使用；Session 不再运行第二套业务 fold。
+
+Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新只通知受影响的 node key；结构变化才重建顺序和 Location 成员关系；prepend 只增加行，不替换既有 keyed value。每个 Assistant chunk 都会更新 Definition State，但最多每个 animation frame 请求一次物化；final message 与 Turn/Step 关闭会立即发布。参见 [Client Tool 展示所有权决策](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md)。
 
 ## 请求检查
 
@@ -46,7 +48,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## Code Mode 子调用树
 
-每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。会引入环，或使递归深度超过 256 个调用这一固定安全上限的协议或历史记录边会被视为已消费，但不会修改树，因此会话其余部分仍可渲染。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Chat 的 Tool Definition 按 call id 关联 root call 与 result，把 Code Dispatch 的 start/settlement 记录折叠进该 root Context，并投影为一棵 keyed 递归树；child call 不会成为独立 Chat root。start 落在已加载窗口之外时，其 settlement 仍以 `callTime: null` 渲染。一次 child 更新只复制其祖先链，因此未变化的 sibling 保持对象身份。会引入环或超过固定 256 层深度上限的边会被消费，但不会修改树。独立的 Trajectory history fold 仍通过 Runtime 的 `ToolCallTree` 生成同一种嵌套数据契约。
 
 ## Session 标题投影
 
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index b700c4c066..4f1ac11fcc 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -4,12 +4,14 @@
  * fiber-scoped loop teardown.
  */
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type { ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
 import { SESSION_SEARCH_RESULT_LIMIT } from '@deepseek-ai/dsh-host-apiproxy/api'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as RuntimeClient from '../src/client/index.ts'
+import type { ConversationNodeDefinition } from '../src/client/contract/conversation.ts'
+import { Session } from '../src/client/sessions/session.ts'
 import type { SessionsService } from '../src/client/sessions/service.ts'
 import type { WorkspacesService } from '../src/client/workspaces/service.ts'
 import { FakeApiClient, ok } from './fake-api.ts'
@@ -112,6 +114,31 @@ describe('runtime client apply', () => {
     expect(bench.api.callsOf('session.create')).toHaveLength(1)
   })
 
+  it('wires registry changes into resident Sessions during the runtime apply pass', async () => {
+    const bench = await mount()
+    const sessions = bench.ctx.get('sessions') as SessionsService
+    bench.sinks?.onHostEnvelope?.({
+      rpcId: 'r-registry' as never,
+      payload: { type: 'host/session-added', blank: true, sessionId: 's-registry' } as never,
+    })
+    await flushMicrotasks()
+    expect(sessions.binding('s-registry' as never)).toBeDefined()
+    const rebuild = vi.spyOn(Session.prototype, 'rebuildConversationRegistry')
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'registry-probe',
+      match: () => null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+
+    bench.ctx.conversationEvents.register(definition)
+    await flushMicrotasks()
+
+    expect(rebuild).toHaveBeenCalledOnce()
+    rebuild.mockRestore()
+  })
+
   it('stops the stream loop when the plugin fiber unloads', async () => {
     const bench = await mount()
     const fiber = [...bench.ctx.registry.values()].find(f => f.name?.includes('client'))
diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
deleted file mode 100644
index 1f969c5121..0000000000
--- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-/**
- * Behavioral half of the compaction-checkpoint drift trap.
- *
- * `TranscriptAdapter` pins its plugin literal to the Service Definition's declaration at
- * compile time through a type-only import of `dsh-compact/checkpoint`, so
- * renaming the Service Definition's plugin already fails `tsc`. This spec covers the same
- * drift from the other side — end to end through the adapter, driving it with a
- * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` value and
- * checking the Service Definition's predicate agrees. Both values come from the
- * cordis-free checkpoint leaf, so the client test program never loads the host
- * package root or its `Context` merges.
- */
-
-import { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
-
-/** A replacement user message stamped with the Service Definition's canonical source. */
-function canonicalCheckpoint(seq: number): SessionEvent {
-  return {
-    type: 'user/message',
-    seq,
-    time: 1_700_000_000_000 + seq,
-    surfaceOp: { op: 'replace', start: 0, end: 0 },
-    sourceEventSeqs: [0],
-    data: createUserMessage({
-      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
-      source: COMPACT_CHECKPOINT_SOURCE,
-    }),
-  } as unknown as SessionEvent
-}
-
-describe('compaction checkpoint recognition', () => {
-  it('recognizes a checkpoint carrying the seam-canonical source', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([canonicalCheckpoint(1)])
-    expect(adapter.nodes()).toEqual([{
-      kind: 'compaction', seq: 1, time: 1_700_000_000_001, summary: null,
-      summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
-    }])
-  })
-
-  it("agrees with the seam's own predicate on the source it recognizes", () => {
-    // Both sides answer the same question about the same value: if the Service Definition
-    // renames its plugin, this equality is what breaks.
-    const checkpoint = canonicalCheckpoint(1)
-    expect(checkpoint.type === 'user/message' && isCompactCheckpointSource(checkpoint.data.source)).toBe(true)
-    expect(COMPACT_CHECKPOINT_SOURCE).toEqual({ kind: 'plugin', plugin: 'compact' })
-  })
-})
diff --git a/packages/client/runtime/tests/conversation-assembler.spec.ts b/packages/client/runtime/tests/conversation-assembler.spec.ts
new file mode 100644
index 0000000000..6f4d8516dc
--- /dev/null
+++ b/packages/client/runtime/tests/conversation-assembler.spec.ts
@@ -0,0 +1,892 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { ConversationNodeAssembler } from '../src/client/sessions/conversation-assembler.ts'
+import type {
+  ConversationEventInput, ConversationMatch, ConversationNodeContext,
+  ConversationNodeDefinition, ConversationViewDefinition, ConversationViewNode,
+} from '../src/client/contract/conversation.ts'
+
+interface ScopeProbeStepData {
+  readonly value: number
+}
+
+interface ScopeProbeTurnData {
+  readonly valueSeenFromStep: number
+}
+
+declare module '../src/client/contract/conversation.ts' {
+  interface ConversationStepDataMap {
+    'scope-probe': ScopeProbeStepData
+  }
+
+  interface ConversationTurnDataMap {
+    'scope-probe': ScopeProbeTurnData
+  }
+}
+
+interface TestSnapshot {
+  readonly order: readonly string[]
+  readonly nodes: ReadonlyMap<string, ConversationViewNode>
+}
+
+class TestEventDefinitions {
+  constructor(
+    readonly definitions: readonly ConversationNodeDefinition[],
+    readonly fallback?: ConversationNodeDefinition,
+  ) {}
+
+  entries(): readonly ConversationNodeDefinition[] {
+    return this.definitions
+  }
+
+  fallbackEntry(): ConversationNodeDefinition | undefined {
+    return this.fallback
+  }
+}
+
+class TestViewDefinitions {
+  constructor(readonly definitions: readonly ConversationViewDefinition[]) {}
+
+  entries(): readonly ConversationViewDefinition[] {
+    return this.definitions
+  }
+}
+
+function testView(
+  apply = vi.fn(),
+): ConversationViewDefinition<ConversationViewNode, TestSnapshot> {
+  return {
+    target: 'chat',
+    create: () => {
+      let current: TestSnapshot = { order: [], nodes: new Map() }
+      return {
+        empty: current,
+        replace: ({ nodes }) => {
+          current = { order: nodes.map(node => node.key), nodes: new Map(nodes.map(node => [node.key, node])) }
+          return current
+        },
+        apply: ({ upserts }) => {
+          apply(upserts)
+          const nodes = new Map(current.nodes)
+          const order = [...current.order]
+          for (const node of upserts) {
+            if (!nodes.has(node.key)) order.push(node.key)
+            nodes.set(node.key, node)
+          }
+          current = { order, nodes }
+          return current
+        },
+      }
+    },
+  }
+}
+
+function at(seq: number, type: string, data: unknown): SessionEvent {
+  return { seq, time: 1_700_000_000_000 + seq, type, data } as SessionEvent
+}
+
+function input(event: SessionEvent): ConversationEventInput {
+  return { event, view: undefined }
+}
+
+function chatSnapshot(assembler: ConversationNodeAssembler): TestSnapshot | undefined {
+  return assembler.snapshot('chat') as TestSnapshot | undefined
+}
+
+function node(context: Parameters<ConversationNodeDefinition['buildViewNode']>[0], data: unknown): ConversationViewNode {
+  return {
+    key: context.key,
+    kind: context.kind,
+    id: context.id,
+    target: 'chat',
+    data,
+  }
+}
+
+describe('ConversationNodeAssembler', () => {
+  it('appends through an exact business-id Context without replaying unrelated Contexts', () => {
+    const starts = vi.fn((
+      _context: ConversationNodeContext<{ callSeq: number; results: number }>,
+      match: ConversationMatch,
+    ) => ({ callSeq: match.event.seq, results: 0 }))
+    const updates = vi.fn((context: { state: { callSeq: number; results: number } }) => ({
+      ...context.state,
+      results: context.state.results + 1,
+    }))
+    const definition: ConversationNodeDefinition<{ callSeq: number; results: number }> = {
+      kind: 'tool',
+      match: (event) => {
+        if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+        if (event.type === 'tool/result') return { id: String(event.data.message.source.callId), role: 'update' }
+        return null
+      },
+      start: starts,
+      update: updates,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'tool/call', { turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}' })),
+      input(at(2, 'tool/call', { turn: 1, step: 1, callId: 'b', name: 'x', arguments: '{}' })),
+    ], false)
+    assembler.flush()
+    starts.mockClear()
+
+    assembler.append(input(at(3, 'tool/result', {
+      turn: 1,
+      step: 1,
+      message: { source: { type: 'tool-result', callId: 'a' }, content: [], isError: false },
+    })))
+    assembler.flush()
+
+    expect(starts).not.toHaveBeenCalled()
+    expect(updates).toHaveBeenCalledOnce()
+    const snapshot = chatSnapshot(assembler)
+    expect([...snapshot?.nodes.values() ?? []].map(value => value.data)).toEqual([
+      { callSeq: 1, results: 1 },
+      { callSeq: 2, results: 0 },
+    ])
+  })
+
+  it('keeps one Match collection while a long Context appends without replay', () => {
+    const starts = vi.fn(() => 0)
+    const updates = vi.fn((context: ConversationNodeContext<number> & { readonly state: number }) => (
+      context.state + 1
+    ))
+    const matchCollections = new Set<readonly ConversationMatch[]>()
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'append-linear',
+      match: (event) => {
+        const type: string = event.type
+        if (type === 'linear/start') return { id: 'one', role: 'start' }
+        if (type === 'linear/update') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: (context) => {
+        matchCollections.add(context.matches)
+        return starts()
+      },
+      update: (context) => {
+        matchCollections.add(context.matches)
+        return updates(context)
+      },
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'linear/start', {}))], false)
+    starts.mockClear()
+
+    for (let seq = 2; seq <= 1_001; seq++) {
+      assembler.append(input(at(seq, 'linear/update', {})))
+    }
+    assembler.flush()
+
+    expect(starts).not.toHaveBeenCalled()
+    expect(updates).toHaveBeenCalledTimes(1_000)
+    expect(matchCollections.size).toBe(1)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1_000)
+  })
+
+  it('merges an older page and replays its affected Context once', () => {
+    const starts = vi.fn(() => 0)
+    const updates = vi.fn((context: ConversationNodeContext<number> & { readonly state: number }) => (
+      context.state + 1
+    ))
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'prepend-linear',
+      match: (event) => {
+        const type: string = event.type
+        if (type === 'linear/start') return { id: 'one', role: 'start' }
+        if (type === 'linear/update') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: starts,
+      update: updates,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    const current = Array.from({ length: 100 }, (_, index) => (
+      input(at(index + 102, 'linear/update', {}))
+    ))
+    assembler.replaceWindow(current, true)
+    assembler.flush()
+    expect(starts).not.toHaveBeenCalled()
+    expect(updates).not.toHaveBeenCalled()
+
+    const older = [
+      input(at(1, 'linear/start', {})),
+      ...Array.from({ length: 100 }, (_, index) => (
+        input(at(index + 2, 'linear/update', {}))
+      )),
+    ]
+    assembler.prepend(older, false)
+    assembler.flush()
+
+    expect(starts).toHaveBeenCalledOnce()
+    expect(updates).toHaveBeenCalledTimes(200)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(200)
+  })
+
+  it('collects an update before its start and replays it once prepend supplies the start', () => {
+    const updates = vi.fn((context: { state: { settled: boolean } }) => ({ ...context.state, settled: true }))
+    const definition: ConversationNodeDefinition<{ settled: boolean }> = {
+      kind: 'tool',
+      match: (event) => {
+        if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+        if (event.type === 'tool/result') return { id: String(event.data.message.source.callId), role: 'update' }
+        return null
+      },
+      start: () => ({ settled: false }),
+      update: updates,
+      buildViewNode: context => node(context, context.state ?? { pendingStart: true }),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(10, 'tool/result', {
+      turn: 1,
+      step: 1,
+      message: { source: { type: 'tool-result', callId: 'a' }, content: [], isError: false },
+    }))], true)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ pendingStart: true })
+
+    assembler.prepend([input(at(5, 'tool/call', {
+      turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}',
+    }))], false)
+    assembler.flush()
+
+    expect(updates).toHaveBeenCalledOnce()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ settled: true })
+  })
+
+  it('rejects a Definition whose declared start follows an update in log order', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'invalid-lifecycle',
+      match: event => event.type === 'turn/end'
+        ? { id: 'one', role: 'start' }
+        : event.type === 'turn/start' ? { id: 'one', role: 'update' } : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+
+    expect(() => assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'turn/end', { turn: 1, reason: { kind: 'completed' } })),
+    ], false)).toThrow('received an update before its start Match')
+  })
+
+  it('replays a window-gap reader when prepend supplies a nearer predecessor', () => {
+    const source: ConversationNodeDefinition<number> = {
+      kind: 'source',
+      match: event => event.type === 'user/message'
+        ? { id: String(event.data.id), role: 'start' }
+        : null,
+      start: (_context, match) => Number((match.event.data as { value?: unknown }).value ?? 0),
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const consumerStart = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<number>['start']>[0],
+      _match: Parameters<ConversationNodeDefinition<number>['start']>[1],
+      reader: Parameters<ConversationNodeDefinition<number>['start']>[2],
+    ) => reader.previous<number>('source')?.state ?? -1)
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: consumerStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([source, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(10, 'assistant/message', {
+      turn: 2, step: 1, message: { role: 'assistant', content: [] },
+    }))], true)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(-1)
+
+    assembler.prepend([input(at(5, 'user/message', {
+      id: 'm1', value: 7, content: [], source: { kind: 'user' },
+    }))], false)
+    assembler.flush()
+
+    expect(consumerStart).toHaveBeenCalledTimes(2)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(7)
+  })
+
+  it('keeps the predecessor index ordered across prepend and append', () => {
+    const source: ConversationNodeDefinition<number> = {
+      kind: 'source',
+      match: event => event.type === 'user/message'
+        ? { id: String(event.data.id), role: 'start' }
+        : null,
+      start: (_context, match) => match.event.seq,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: (_context, _match, reader) => reader.previous<number>('source')?.state ?? -1,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([source, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(40, 'user/message', { id: 'm40', content: [], source: { kind: 'user' } })),
+      input(at(50, 'assistant/message', {
+        turn: 1, step: 1, message: { role: 'assistant', content: [] },
+      })),
+    ], true)
+    assembler.flush()
+
+    assembler.prepend([
+      input(at(10, 'user/message', { id: 'm10', content: [], source: { kind: 'user' } })),
+      input(at(30, 'user/message', { id: 'm30', content: [], source: { kind: 'user' } })),
+    ], false)
+    assembler.flush()
+    assembler.append(input(at(60, 'user/message', {
+      id: 'm60', content: [], source: { kind: 'user' },
+    })))
+    assembler.append(input(at(70, 'assistant/message', {
+      turn: 2, step: 1, message: { role: 'assistant', content: [] },
+    })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
+      .toEqual([40, 60])
+  })
+
+  it('replays a window-gap reader when an empty prepend closes the unknown prefix', () => {
+    const consumerStart = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<number>['start']>[0],
+      _match: Parameters<ConversationNodeDefinition<number>['start']>[1],
+      reader: Parameters<ConversationNodeDefinition<number>['start']>[2],
+    ) => reader.previous<number>('source')?.state ?? -1)
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: consumerStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(10, 'assistant/message', {
+      turn: 2, step: 1, message: { role: 'assistant', content: [] },
+    }))], true)
+    assembler.flush()
+
+    expect(assembler.prepend([], false)).toBe('immediate')
+    assembler.flush()
+
+    expect(consumerStart).toHaveBeenCalledTimes(2)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(-1)
+  })
+
+  it('replays direct dependents when an append revises their predecessor Context', () => {
+    const source: ConversationNodeDefinition<number> = {
+      kind: 'source',
+      match: (event) => {
+        if (event.type === 'user/message') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'source/update') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => 1,
+      update: (_context, match) => (match.event.data as unknown as { value: number }).value,
+      buildViewNode: () => null,
+    }
+    const consumerStart = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<number>['start']>[0],
+      _match: Parameters<ConversationNodeDefinition<number>['start']>[1],
+      reader: Parameters<ConversationNodeDefinition<number>['start']>[2],
+    ) => reader.previous<number>('source')?.state ?? -1)
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: 'one', role: 'start' }
+        : null,
+      start: consumerStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([source, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
+      input(at(2, 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
+    ], false)
+    assembler.flush()
+
+    expect(assembler.append(input(at(3, 'source/update', { value: 2 })))).toBe('immediate')
+    assembler.flush()
+
+    expect(consumerStart).toHaveBeenCalledTimes(2)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(2)
+  })
+
+  it('replays Location-derived State and rebuilds only owned Nodes when a step closes', () => {
+    const apply = vi.fn()
+    const starts = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<string>['start']>[0],
+      match: Parameters<ConversationNodeDefinition<string>['start']>[1],
+    ) => match.location.kind === 'step' ? match.location.step.status : 'missing')
+    const definition: ConversationNodeDefinition<string> = {
+      kind: 'step',
+      match: event => event.type === 'step/start'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: starts,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('open')
+
+    assembler.append(input(at(3, 'step/end', { turn: 1, step: 1 })))
+    assembler.flush()
+
+    expect(starts).toHaveBeenCalledTimes(2)
+    expect(apply).toHaveBeenCalledOnce()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('closed')
+  })
+
+  it('lets one Context publish Step and Turn data in phase order', () => {
+    interface State {
+      readonly turn: number
+      readonly step: number
+      readonly value: number
+    }
+
+    const definition: ConversationNodeDefinition<State> = {
+      kind: 'scope-probe',
+      match: (event) => {
+        if (event.type === 'step/start') {
+          return { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        }
+        if ((event.type as string) === 'scope-probe/update') {
+          return { id: '1:1', role: 'update' }
+        }
+        return null
+      },
+      start: (_context, match) => {
+        if (match.event.type !== 'step/start') throw new Error('scope probe requires step/start')
+        return { turn: match.event.data.turn, step: match.event.data.step, value: 1 }
+      },
+      update: (_context, match) => ({
+        turn: 1,
+        step: 1,
+        value: (match.event.data as unknown as { value: number }).value,
+      }),
+      buildLocationData: (context, scope) => {
+        const state = context.state
+        if (state === undefined) return null
+        if (scope === 'step') {
+          return {
+            kind: 'step',
+            turn: state.turn,
+            step: state.step,
+            key: 'scope-probe',
+            value: { value: state.value },
+          }
+        }
+        const location = context.start?.location
+        const stepValue = location?.kind === 'step'
+          ? location.step.data.get('scope-probe')?.value
+          : undefined
+        return {
+          kind: 'turn',
+          turn: state.turn,
+          key: 'scope-probe',
+          value: { valueSeenFromStep: stepValue ?? -1 },
+        }
+      },
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        if (location?.kind !== 'step') return null
+        return node(context, {
+          step: location.step.data.get('scope-probe')?.value,
+          turn: location.turn.data.get('scope-probe')?.valueSeenFromStep,
+        })
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ step: 1, turn: 1 })
+
+    assembler.append(input(at(3, 'scope-probe/update', { turn: 1, step: 1, value: 2 })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ step: 2, turn: 2 })
+  })
+
+  it('updates existing turn Locations when their Step membership changes', () => {
+    const apply = vi.fn()
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'turn-probe',
+      match: event => event.type === 'turn/start'
+        ? { id: String(event.data.turn), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.start?.location.kind === 'turn'
+        ? context.start.location.turn.steps.length
+        : -1),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([input(at(1, 'turn/start', { turn: 1 }))], false)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(0)
+
+    assembler.append(input(at(2, 'step/start', { turn: 1, step: 1 })))
+    assembler.flush()
+
+    expect(apply).toHaveBeenCalledOnce()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1)
+  })
+
+  it('publishes a changed timeline even when no business Definition claims the boundary', () => {
+    const apply = vi.fn()
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([], false)
+    assembler.flush()
+
+    assembler.append(input(at(1, 'turn/start', { turn: 1 })))
+    assembler.flush()
+
+    expect(apply).toHaveBeenCalledOnce()
+    expect(chatSnapshot(assembler)?.order).toEqual([])
+  })
+
+  it('clears the prior Step at a new Turn and honors explicit session ownership', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'location-probe',
+      match: (event) => {
+        if ((event.type as string) === 'command/run') {
+          return {
+            id: (event.data as unknown as { commandId: string }).commandId,
+            role: 'start',
+          }
+        }
+        if ((event.type as string) === 'compact/start') {
+          return {
+            id: (event.data as unknown as { compactionId: string }).compactionId,
+            role: 'start',
+          }
+        }
+        return null
+      },
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        const data = location?.kind === 'step'
+          ? `step:${location.turn.turn}:${location.step.step}`
+          : location?.kind === 'turn' ? `turn:${location.turn.turn}` : location?.kind
+        return node(context, data)
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+      input(at(3, 'turn/start', { turn: 2 })),
+      input(at(4, 'command/run', { commandId: 'command', name: 'x' })),
+      input(at(5, 'compact/start', { compactionId: 'compact', turn: null })),
+    ], false)
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
+      .toEqual(['turn:2', 'session'])
+  })
+
+  it('assigns turn boundaries to the Turn even when a Step remains open', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'turn-boundary-probe',
+      match: event => event.type === 'turn/end'
+        ? { id: String(event.data.turn), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.start?.location.kind),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+
+    assembler.append(input(at(3, 'turn/end', { turn: 1, reason: { kind: 'aborted' } })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('turn')
+  })
+
+  it('carries explicit coordinates across coordinate-free events in a partial window and live tail', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'location-probe',
+      match: event => (event.type as string) === 'tool/code-dispatch-start'
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        return node(context, location?.kind === 'step'
+          ? `${location.turn.turn}:${location.step.step}`
+          : location?.kind)
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(10, 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
+      input(at(11, 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'a' })),
+    ], true)
+    assembler.flush()
+
+    assembler.append(input(at(12, 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'b' })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
+      .toEqual(['2:3', '2:3'])
+  })
+
+  it('treats loaded end boundaries as closed when their starts precede the window', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'location-probe',
+      match: event => event.type === 'tool/call'
+        ? { id: String(event.data.callId), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        return node(context, location?.kind === 'step'
+          ? `${location.turn.status}:${location.step.status}`
+          : location?.kind)
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(10, 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
+      input(at(11, 'step/end', { turn: 2, step: 3 })),
+      input(at(12, 'turn/end', { turn: 2, reason: { kind: 'completed' } })),
+    ], true)
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toBe('closed:closed')
+  })
+
+  it('restarts State creation from undefined when Location changes replay a Context', () => {
+    const seen = vi.fn((context: Parameters<ConversationNodeDefinition<number>['start']>[0]) => {
+      expect(context.state).toBeUndefined()
+      return 1
+    })
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'replay-probe',
+      match: event => event.type === 'step/start'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: seen,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'step/start', { turn: 1, step: 1 }))], false)
+    assembler.flush()
+
+    assembler.append(input(at(2, 'step/end', { turn: 1, step: 1 })))
+    assembler.flush()
+
+    expect(seen).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not invoke the fallback when an ordinary non-rendering Definition claims an event', () => {
+    const fallbackStart = vi.fn(() => 'fallback')
+    const claimed: ConversationNodeDefinition<null> = {
+      kind: 'claimed',
+      match: event => (event.type as string) === 'command/run' ? { id: 'claimed', role: 'start' } : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const fallback: ConversationNodeDefinition<string> = {
+      kind: 'fallback',
+      match: event => ({ id: String(event.seq), role: 'start' }),
+      start: fallbackStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([claimed], fallback),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.flush()
+
+    expect(fallbackStart).not.toHaveBeenCalled()
+    expect(chatSnapshot(assembler)?.order).toEqual([])
+  })
+
+  it('rejects withdrawing a previously materialized Node during an incremental update', () => {
+    const definition: ConversationNodeDefinition<boolean> = {
+      kind: 'toggle',
+      match: (event) => {
+        if ((event.type as string) === 'command/run') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'toggle/hide') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => true,
+      update: () => false,
+      buildViewNode: context => context.state === true ? node(context, true) : null,
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.flush()
+    expect(chatSnapshot(assembler)?.order).toHaveLength(1)
+
+    assembler.append(input(at(2, 'toggle/hide', {})))
+    expect(() => assembler.flush()).toThrow(/withdrew materialized target "chat"/)
+
+    expect(chatSnapshot(assembler)?.order).toHaveLength(1)
+  })
+
+  it('fails loud when a Definition returns undefined State', () => {
+    const startUndefined: ConversationNodeDefinition = {
+      kind: 'undefined-start',
+      match: event => (event.type as string) === 'command/run' ? { id: 'one', role: 'start' } : null,
+      start: () => undefined,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const startAssembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([startUndefined]),
+      new TestViewDefinitions([testView()]),
+    )
+    expect(() => startAssembler.replaceWindow([
+      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+    ], false)).toThrow(/Definition "undefined-start" returned undefined from start/)
+
+    const updateUndefined: ConversationNodeDefinition<boolean> = {
+      kind: 'undefined-update',
+      match: (event) => {
+        if ((event.type as string) === 'command/run') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'command/done') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => true,
+      update: () => undefined as never,
+      buildViewNode: context => node(context, context.state),
+    }
+    const updateAssembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([updateUndefined]),
+      new TestViewDefinitions([testView()]),
+    )
+    updateAssembler.replaceWindow([
+      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+    ], false)
+    expect(() => updateAssembler.append(
+      input(at(2, 'command/done', { commandId: 'one', kind: 'success' })),
+    )).toThrow(/Definition "undefined-update" returned undefined from update/)
+  })
+
+  it('rejects a duplicate start before mutating the existing Context', () => {
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'single-start',
+      match: event => (event.type as string) === 'command/run' ? { id: 'one', role: 'start' } : null,
+      start: (_context, match) => match.event.seq,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+    ], false)
+    assembler.flush()
+
+    expect(() => assembler.append(
+      input(at(2, 'command/run', { commandId: 'two', name: 'x' })),
+    )).toThrow(/received more than one start Match/)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1)
+  })
+})
diff --git a/packages/client/runtime/tests/conversation-registry.spec.ts b/packages/client/runtime/tests/conversation-registry.spec.ts
new file mode 100644
index 0000000000..19cbdf17f9
--- /dev/null
+++ b/packages/client/runtime/tests/conversation-registry.spec.ts
@@ -0,0 +1,126 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { ConversationEventRegistry } from '../src/client/conversation/event-registry.ts'
+import { ConversationViewRegistry } from '../src/client/conversation/view-registry.ts'
+import type {
+  ConversationNodeDefinition, ConversationViewDefinition, ConversationViewNode,
+} from '../src/client/contract/conversation.ts'
+import { Session } from '../src/client/sessions/session.ts'
+import { SessionsService } from '../src/client/sessions/service.ts'
+import { FakeApiClient, ok } from './fake-api.ts'
+
+function eventDefinition(kind: string): ConversationNodeDefinition<null> {
+  return {
+    kind,
+    match: () => null,
+    start: () => null,
+    update: context => context.state,
+    buildViewNode: () => null,
+  }
+}
+
+function viewDefinition(target: string): ConversationViewDefinition<ConversationViewNode, null> {
+  return {
+    target,
+    create: () => ({
+      empty: null,
+      replace: () => null,
+      apply: () => null,
+    }),
+  }
+}
+
+async function bootRegistries(): Promise<{
+  ctx: Context
+  events: ConversationEventRegistry
+  views: ConversationViewRegistry
+}> {
+  const ctx = new Context()
+  await ctx.plugin(ConversationEventRegistry).await()
+  await ctx.plugin(ConversationViewRegistry).await()
+  const events = ctx.get('conversationEvents') as ConversationEventRegistry
+  const views = ctx.get('conversationViews') as ConversationViewRegistry
+  return { ctx, events, views }
+}
+
+describe('Conversation registries', () => {
+  it('rejects duplicate Event Definitions and disposes an ordinary registration once', async () => {
+    const { events } = await bootRegistries()
+    const definition = eventDefinition('message')
+    const dispose = events.register(definition)
+
+    expect(events.entries()).toEqual([definition])
+    expect(() => events.register(eventDefinition('message'))).toThrow(/already registered/)
+
+    dispose()
+    dispose()
+    expect(events.entries()).toEqual([])
+  })
+
+  it('rejects a duplicate fallback and clears it through its idempotent disposer', async () => {
+    const { events } = await bootRegistries()
+    const fallback = eventDefinition('unknown')
+    const dispose = events.registerFallback(fallback)
+
+    expect(events.fallbackEntry()).toBe(fallback)
+    expect(() => events.registerFallback(eventDefinition('other'))).toThrow(/already registered/)
+
+    dispose()
+    dispose()
+    expect(events.fallbackEntry()).toBeUndefined()
+  })
+
+  it('rejects duplicate view targets and disposes a view registration once', async () => {
+    const { views } = await bootRegistries()
+    const definition = viewDefinition('chat')
+    const dispose = views.register(definition)
+
+    expect(views.entries()).toEqual([definition])
+    expect(() => views.register(viewDefinition('chat'))).toThrow(/already registered/)
+
+    dispose()
+    dispose()
+    expect(views.entries()).toEqual([])
+  })
+
+  it('removes Event, fallback, and view contributions with their caller fiber', async () => {
+    const { ctx, events, views } = await bootRegistries()
+    const feature = ctx.inject(['conversationEvents', 'conversationViews'], (featureCtx) => {
+      featureCtx.conversationEvents.register(eventDefinition('message'))
+      featureCtx.conversationEvents.registerFallback(eventDefinition('unknown'))
+      featureCtx.conversationViews.register(viewDefinition('chat'))
+    })
+    await feature.await()
+
+    expect(events.entries()).toHaveLength(1)
+    expect(events.fallbackEntry()).toBeDefined()
+    expect(views.entries()).toHaveLength(1)
+
+    await feature.dispose()
+    expect(events.entries()).toEqual([])
+    expect(events.fallbackEntry()).toBeUndefined()
+    expect(views.entries()).toEqual([])
+  })
+
+  it('coalesces registry changes into one rebuild of every resident Session', async () => {
+    const { ctx, events, views } = await bootRegistries()
+    const api = new FakeApiClient()
+    const sessionId = 'resident' as SessionId
+    api.onList = () => Promise.resolve(ok({
+      items: [{ sessionId, updatedAt: 1, running: false, blank: true }],
+    }) as never)
+    const sessions = new SessionsService(ctx, api)
+    await sessions.refresh()
+    await Promise.resolve()
+    sessions.scope(sessionId)
+    const rebuild = vi.spyOn(Session.prototype, 'rebuildConversationRegistry')
+
+    events.register(eventDefinition('message'))
+    views.register(viewDefinition('chat'))
+    await Promise.resolve()
+
+    expect(rebuild).toHaveBeenCalledOnce()
+    rebuild.mockRestore()
+  })
+})
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index de72d5b351..299e16785d 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -54,12 +54,12 @@ export const ev = {
   codeDispatchStart: (seq: number, parentCallId: string, n: number, name: string, args: unknown): SessionEvent =>
     at(seq, {
       type: 'tool/code-dispatch-start',
-      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
+      data: { rootCallId: parentCallId, parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
     }),
   codeDispatch: (seq: number, parentCallId: string, n: number, name: string, args: unknown, body: string, isError = false): SessionEvent =>
     at(seq, {
       type: 'tool/code-dispatch',
-      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args, isError, content: text(body) },
+      data: { rootCallId: parentCallId, parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args, isError, content: text(body) },
     }),
   stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
     at(seq, { type: 'step/end', data: { turn, step } }),
diff --git a/packages/client/runtime/tests/queue-store.spec.ts b/packages/client/runtime/tests/queue-store.spec.ts
index 55e0929c30..1b6b721d25 100644
--- a/packages/client/runtime/tests/queue-store.spec.ts
+++ b/packages/client/runtime/tests/queue-store.spec.ts
@@ -158,7 +158,6 @@ describe('queue snapshot intake', () => {
       type: 'session/event', sessionId: SID, event: durable,
     })
     expect(session.getSnapshot().queue.map(item => item.id)).toEqual(['s-second'])
-    expect(session.getSnapshot().nodes.filter(node => node.kind === 'user')).toHaveLength(1)
 
     session.handleMuxEnvelope(rid('env-reused-id'), queueFrame([
       { id: 's-later', body: '', placement: 'steering', message },
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 834f37d434..def97002f0 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -8,15 +8,17 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { Session } from '../src/client/sessions/session.ts'
+import type {
+  ChatConversationViewNode, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot,
+  ConversationEventInput, ConversationNode, ConversationNodeDefinition,
+  ConversationRuntime, ConversationSnapshot, ConversationTimelineSnapshot,
+  ConversationViewDefinition,
+} from '../src/client/index.ts'
 import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
 import { entries, ev, plainTurn } from './event-script.ts'
 
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
-  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
-
 const SID = 'fk-s1' as SessionId
 const PARENT = 'fk-parent' as SessionId
 
@@ -24,8 +26,142 @@ afterEach(() => {
   vi.unstubAllGlobals()
 })
 
+const EMPTY: readonly never[] = []
+
+interface TestEventState extends ConversationEventInput {}
+
+class TestNodeStore implements ChatNodeStore {
+  private readonly nodes = new Map<string, ChatConversationViewNode>()
+  private cache: readonly ChatConversationViewNode[] = EMPTY
+
+  get(key: string): ChatConversationViewNode | undefined {
+    return this.nodes.get(key)
+  }
+
+  values(): readonly ChatConversationViewNode[] {
+    return this.cache
+  }
+
+  replace(nodes: readonly ChatConversationViewNode[]): void {
+    this.nodes.clear()
+    for (const node of nodes) this.nodes.set(node.key, node)
+    this.cache = [...this.nodes.values()]
+  }
+
+  upsert(nodes: readonly ChatConversationViewNode[]): void {
+    if (nodes.length === 0) return
+    for (const node of nodes) this.nodes.set(node.key, node)
+    this.cache = [...this.nodes.values()]
+  }
+}
+
+const TEST_LOCATIONS: ChatLocationNodeIndex = {
+  getTurn: () => EMPTY,
+  getStep: () => EMPTY,
+}
+
+function testLegacy(
+  nodes: readonly ChatConversationViewNode[],
+  timeline: ConversationTimelineSnapshot,
+): ChatSnapshot['legacy'] {
+  const legacyNodes = nodes.flatMap((node): ConversationNode[] => {
+    const event = (node.data as TestEventState).event
+    if (event.type === 'user/message') return [{ kind: 'user', seq: event.seq } as ConversationNode]
+    if (event.type === 'assistant/message') return [{ kind: 'assistant', seq: event.seq } as ConversationNode]
+    return []
+  })
+  const turnTimings = new Map<number, { startTime: number; endTime?: number }>()
+  const turnEnds = new Map<number, number>()
+  for (const turn of timeline.turns.values()) {
+    if (turn.start !== undefined) {
+      turnTimings.set(turn.turn, turn.end === undefined
+        ? { startTime: turn.start.time }
+        : { startTime: turn.start.time, endTime: turn.end.time })
+    }
+    if (turn.end !== undefined) turnEnds.set(turn.turn, turn.end.seq)
+  }
+  return { nodes: legacyNodes, turnTimings, turnEnds, partial: null, runningCalls: EMPTY }
+}
+
+function testViewDefinition(): ConversationViewDefinition<ChatConversationViewNode, ChatSnapshot> {
+  return {
+    target: 'chat',
+    create: () => {
+      const store = new TestNodeStore()
+      let current: ChatSnapshot = {
+        order: EMPTY,
+        nodes: store,
+        locations: TEST_LOCATIONS,
+        timeline: { turnOrder: EMPTY, turns: new Map() },
+        legacy: testLegacy(EMPTY, { turnOrder: EMPTY, turns: new Map() }),
+      }
+      const build = (timeline: ConversationTimelineSnapshot): ChatSnapshot => {
+        const nodes = [...store.values()].sort((left, right) => left.anchorSeq - right.anchorSeq)
+        current = {
+          order: nodes.map(node => node.key),
+          nodes: store,
+          locations: TEST_LOCATIONS,
+          timeline,
+          legacy: testLegacy(nodes, timeline),
+        }
+        return current
+      }
+      return {
+        empty: current,
+        replace: ({ nodes, timeline }) => {
+          store.replace(nodes)
+          return build(timeline)
+        },
+        apply: ({ upserts, timeline }) => {
+          store.upsert(upserts)
+          return build(timeline)
+        },
+      }
+    },
+  }
+}
+
+const TEST_EVENT_DEFINITION: ConversationNodeDefinition<TestEventState> = {
+  kind: 'runtime-test-event',
+  match: event => ({ id: String(event.seq), role: 'start' }),
+  start: (_context, match) => ({ event: match.event, view: match.view }),
+  update: context => context.state,
+  publication: match => match.event.type === 'assistant/chunk' ? 'animation-frame' : 'immediate',
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined || context.start === undefined) return null
+    return {
+      key: context.key,
+      kind: 'runtime-test-event',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start.event.seq,
+      location: context.start.location,
+      visibility: 'visible',
+      data: context.state,
+    }
+  },
+}
+
+const TEST_CONVERSATION: ConversationRuntime = {
+  events: {
+    entries: () => [TEST_EVENT_DEFINITION],
+    fallbackEntry: () => undefined,
+  } as unknown as ConversationRuntime['events'],
+  views: {
+    entries: () => [testViewDefinition()],
+  } as unknown as ConversationRuntime['views'],
+}
+
 function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session: Session } {
-  return { api, session: new Session(SID, api) }
+  return { api, session: new Session(SID, api, { conversation: TEST_CONVERSATION }) }
+}
+
+function chatEvents(snapshot: ConversationSnapshot): readonly TestEventState[] {
+  return snapshot.chat.order.map(key => snapshot.chat.nodes.get(key)?.data as TestEventState)
+}
+
+function chatSeqs(snapshot: ConversationSnapshot): number[] {
+  return chatEvents(snapshot).map(item => item.event.seq)
 }
 
 function histResponse(events: SessionEvent[], hasMore = false) {
@@ -34,6 +170,14 @@ function histResponse(events: SessionEvent[], hasMore = false) {
 }
 
 describe('open', () => {
+  it('keeps a bare Session blank until an authoritative lifecycle signal arrives', () => {
+    const { session } = makeSession()
+    expect(session.getSnapshot()).toMatchObject({ blank: true, composerPhase: 'blank' })
+
+    session.handleRunning(true)
+    expect(session.getSnapshot()).toMatchObject({ blank: false, composerPhase: 'active' })
+  })
+
   it('installs the tail page: cold → loading → open with window and nodes in place', async () => {
     const { api, session } = makeSession()
     const page = plainTurn(10, 3, '问', '答')
@@ -115,74 +259,28 @@ describe('live event path', () => {
     expect(session.getSnapshot().nodes).toEqual(before.nodes)
   })
 
-  it('materializes a command node from live lifecycle frames and reproduces it from a history window', async () => {
-    // Live path: run mints an executing node, done settles it in the flow.
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.commandRun(6, 'cmd-live', 'plan'))
-    let command = session.getSnapshot().nodes.at(-1)
-    expect(command).toMatchObject({ kind: 'command', name: 'plan', args: '', outcome: null })
-    feed(ev.commandDone(7, 'cmd-live', 'success', '已进入 plan mode'))
-    command = session.getSnapshot().nodes.at(-1)
-    expect(command).toMatchObject({ kind: 'command', seq: 6, outcome: { kind: 'success', text: '已进入 plan mode' } })
-
-    // Replay path (refresh): the same pair inside the history window folds identically.
-    const replayed = await opened([
-      ...plainTurn(0, 0, 'a', 'b'),
-      ev.commandRun(6, 'cmd-live', 'plan'),
-      ev.commandDone(7, 'cmd-live', 'success', '已进入 plan mode'),
-    ])
-    expect(replayed.session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'command', seq: 6, name: 'plan', outcome: { kind: 'success', text: '已进入 plan mode' },
-    })
-  })
-
-  it('command lifecycle rows alone keep the composer blank (hero survives a /permission or /plan switch)', async () => {
-    // A fresh session whose only window content is a command pair (plus the
-    // knob events a /permission switch appends — not surface-eligible, so
-    // they never become nodes) stays phase 'blank': selecting a preset from
-    // the hero must not enter the conversation view.
+  it('keeps the authoritative host blank bit across unrelated log events', async () => {
     const { session } = await opened([])
+    session.handleBlank(true)
     expect(session.getSnapshot().composerPhase).toBe('blank')
     const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
     feed(ev.commandRun(0, 'cmd-perm', 'permission', ' danger-full-access'))
     feed(ev.commandDone(1, 'cmd-perm', 'success', 'preset danger-full-access'))
     const snapshot = session.getSnapshot()
-    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'command', name: 'permission' })
+    expect(chatSeqs(snapshot)).toEqual([0, 1])
     expect(snapshot.composerPhase).toBe('blank')
   })
 
-  it('accumulates chunks into partial, then finalize swaps partial out as the node lands', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.user(7, '流式问'))
-    feed(ev.chunkStart(8, 1))
-    feed(ev.chunkText(9, 1, '半截'))
-    let snapshot = session.getSnapshot()
-    expect(snapshot.partial).toMatchObject({ turn: 1, blocks: [{ kind: 'text', text: '半截' }] })
-    feed(ev.chunkText(10, 1, '回复'))
-    expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '半截回复' }])
-    feed(ev.assistant(11, 1, '半截回复'))
-    feed(ev.turnEnd(12, 1))
-    snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    const last = snapshot.nodes.at(-1)
-    expect(last).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '半截回复' }] })
-    expect((last as { interrupted?: true }).interrupted).toBeUndefined()
-  })
-
-  it('publishes cumulative chunks once per frame and lets finalization supersede the pending frame', async () => {
+  it('publishes animation-frame Definitions once per frame and lets an immediate event supersede the pending frame', async () => {
     const frames: FrameRequestCallback[] = []
     vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
       frames.push(callback)
       return frames.length
     })
     const { session } = await opened()
-    const published: Array<string | null> = []
+    const published: number[][] = []
     session.subscribe(() => {
-      const block = session.getSnapshot().partial?.blocks[0]
-      published.push(block?.kind === 'text' ? block.text : null)
+      published.push(chatSeqs(session.getSnapshot()))
     })
     const feed = (event: SessionEvent) => {
       session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
@@ -195,356 +293,46 @@ describe('live event path', () => {
     expect(frames).toHaveLength(1)
 
     frames.shift()!(0)
-    expect(published).toEqual(['累计'])
+    expect(published).toEqual([[0, 1, 2, 3, 4, 5, 6, 7, 8]])
 
     feed(ev.chunkText(9, 1, '完成'))
     feed(ev.assistant(10, 1, '累计完成'))
     await Promise.resolve()
-    expect(published).toEqual(['累计', null])
+    expect(published).toEqual([
+      [0, 1, 2, 3, 4, 5, 6, 7, 8],
+      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    ])
 
     frames.shift()!(0)
-    expect(published).toEqual(['累计', null])
+    expect(published).toHaveLength(2)
   })
 
-  it('retracts the failed-attempt partial and starts the retry on new chunk evidence', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    const retryTurn = [
-      ev.turnStart(6, 1),
-      ev.user(7, '请重试'),
-      ev.stepStart(8, 1),
-      ev.chunkStart(9, 1),
-      ev.chunkText(10, 1, '不完整回复'),
-      ev.retry(11, 1, 0, 1, 2, 450, '连接被重置'),
-      ev.chunkStart(12, 1),
-      ev.assistant(13, 1, '完整回复'),
-      ev.stepEnd(14, 1),
-      ev.turnEnd(15, 1),
-    ]
-    for (const event of retryTurn.slice(0, 6)) feed(event)
-
-    let snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    expect(snapshot.nodes.at(-1)).toMatchObject({
-      kind: 'model-retry',
-      retryState: 'scheduled',
-      turn: 1,
-      step: 0,
-      provider: 'fake',
-      mode: 'normal',
-      policyKey: 'fake-normal',
-      retry: 1,
-      maxRetries: 2,
-      delayMs: 450,
-      failure: { code: 'TRANSPORT', message: '连接被重置' },
-    })
-    expect(JSON.stringify(snapshot.nodes)).not.toContain('不完整回复')
-
-    for (const event of retryTurn.slice(6)) feed(event)
-    snapshot = session.getSnapshot()
-    expect(snapshot.nodes.slice(-2).map(node => node.kind)).toEqual(['model-retry', 'assistant'])
-    expect(snapshot.nodes.some(node => node.kind === 'turn-error')).toBe(false)
-    expect(snapshot.nodes.at(-2)).toMatchObject({ kind: 'model-retry', retryState: 'started' })
-    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '完整回复' }] })
-    const retryStart = retryTurn.find(event => event.type === 'turn/start')
-    if (retryStart?.type !== 'turn/start') throw new Error('test fixture must include the retried turn start')
-    const retryEnd = retryTurn.find(event =>
-      event.type === 'turn/end' && event.data.turn === retryStart.data.turn)
-    if (retryEnd?.type !== 'turn/end') throw new Error('test fixture must complete the retry turn')
-    expect(snapshot.turnTimings.get(retryStart.data.turn)).toEqual({
-      startTime: retryStart.time,
-      endTime: retryEnd.time,
-    })
-
-    const replay = makeSession()
-    replay.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...retryTurn])
-    await replay.session.open()
-    expect(replay.session.getSnapshot().nodes).toEqual(snapshot.nodes)
-    expect(replay.session.getSnapshot().turnTimings).toEqual(snapshot.turnTimings)
-    expect(replay.session.getSnapshot().partial).toBeNull()
-  })
-
-  it('projects unretried terminal failures at turn/end and reproduces them from history', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => {
-      session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
+  it('publishes a timeline-only boundary even when no Definition claims the event', async () => {
+    const api = new FakeApiClient()
+    api.onHistory = () => histResponse([])
+    const conversation: ConversationRuntime = {
+      events: {
+        entries: () => [],
+        fallbackEntry: () => undefined,
+      } as unknown as ConversationRuntime['events'],
+      views: {
+        entries: () => [testViewDefinition()],
+      } as unknown as ConversationRuntime['views'],
     }
-    const failedTurns = [
-      ev.turnStart(6, 1),
-      ev.user(7, '鉴权失败'),
-      ev.stepStart(8, 1),
-      at(9, {
-        type: 'turn/end',
-        data: { turn: 1, reason: { kind: 'error', error: {
-          code: 'AUTH',
-          message: 'Authentication Fails, Your api key: sk-preview-secret is invalid',
-        },
-        },
-        },
-      }),
-      ev.turnStart(10, 2),
-      ev.user(11, '内部失败'),
-      ev.stepStart(12, 2, 1),
-      at(13, {
-        type: 'turn/end',
-        data: { turn: 2, reason: { kind: 'error', error: { message: 'plugin exploded', code: 'UNKNOWN' } } },
-      }),
-    ]
-    for (const event of failedTurns) feed(event)
+    const session = new Session(SID, api, { conversation })
+    await session.open()
+    const snapshots: ConversationSnapshot[] = []
+    session.subscribe(() => { snapshots.push(session.getSnapshot()) })
 
-    const errors = session.getSnapshot().nodes.filter(node => node.kind === 'turn-error')
-    expect(errors).toMatchObject([
-      { seq: 9, turn: 1, step: 0, code: 'AUTH', message: 'API key is invalid' },
-      // Every failed turn carries a structured failure; unstructured errors
-      // flatten to the UNKNOWN code.
-      { seq: 13, turn: 2, step: 1, code: 'UNKNOWN', message: 'plugin exploded' },
-    ])
-
-    const replay = makeSession()
-    replay.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...failedTurns])
-    await replay.session.open()
-    expect(replay.session.getSnapshot().nodes).toEqual(session.getSnapshot().nodes)
-  })
-
-  it('rejects retry payloads outside the producer contract without retracting the current partial', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.chunkStart(7, 1))
-    feed(ev.chunkText(8, 1, '仍在生成'))
-    const valid = {
-      turn: 1, step: 0,
-      provider: 'fake', mode: 'normal', policyKey: 'fake-normal',
-      retry: 1, maxRetries: 2, delayMs: 500,
-      failure: { code: 'TRANSPORT', message: 'temporary failure' },
-    }
-    const invalid = [
-      { ...valid, turn: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, step: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, provider: '' },
-      { ...valid, policyKey: '' },
-      { ...valid, retry: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, maxRetries: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, delayMs: -1 },
-      { ...valid, delayMs: Number.POSITIVE_INFINITY },
-      { ...valid, delayMs: MAX_TIMER_DELAY_MS + 1 },
-      { ...valid, failure: { ...valid.failure, message: '' } },
-      { ...valid, failure: { ...valid.failure, code: '' } },
-      { ...valid, failure: { ...valid.failure, status: '429' } },
-      { ...valid, failure: { ...valid.failure, status: 99 } },
-      { ...valid, failure: { ...valid.failure, status: 429.5 } },
-      { ...valid, failure: { ...valid.failure, status: 600 } },
-      { ...valid, failure: { ...valid.failure, providerRetryAfterMs: 0 } },
-      { ...valid, failure: { ...valid.failure, providerRetryAfterMs: Number.POSITIVE_INFINITY } },
-      { ...valid, failure: { ...valid.failure, requestId: 1 } },
-      { ...valid, failure: { ...valid.failure, requestId: '' } },
-    ]
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
-    try {
-      for (const [index, data] of invalid.entries()) {
-        feed(at(9 + index, { type: 'llm/retry', data }))
-      }
-      expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '仍在生成' }])
-      expect(session.getSnapshot().nodes.filter(node => node.kind === 'model-retry')).toEqual([])
-      expect(errorSpy).toHaveBeenCalledTimes(invalid.length)
-      expect(errorSpy).toHaveBeenCalledWith('[web-runtime] ignored malformed llm/retry event at seq 9')
-    } finally {
-      errorSpy.mockRestore()
-    }
-  })
-
-  it('accepts complete retry payloads at the producer field boundaries', async () => {
-    const { session } = await opened()
-    session.handleMuxEnvelope('r' as never, {
+    session.handleMuxEnvelope('timeline' as never, {
       type: 'session/event',
       sessionId: SID,
-      event: at(6, {
-        type: 'llm/retry',
-        data: {
-          turn: Number.MAX_SAFE_INTEGER,
-          step: Number.MAX_SAFE_INTEGER,
-          provider: 'fake',
-          mode: 'normal',
-          policyKey: 'fake-normal',
-          retry: Number.MAX_SAFE_INTEGER,
-          maxRetries: Number.MAX_SAFE_INTEGER,
-          delayMs: MAX_TIMER_DELAY_MS,
-          failure: {
-            code: 'RATE_LIMIT',
-            message: 'provider busy',
-            status: 599,
-            providerRetryAfterMs: Number.MIN_VALUE,
-            requestId: 'req-1',
-          },
-        },
-      }),
+      event: ev.turnStart(0, 1),
     })
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'model-retry',
-      retryState: 'scheduled',
-      retry: Number.MAX_SAFE_INTEGER,
-      delayMs: MAX_TIMER_DELAY_MS,
-      failure: { status: 599, providerRetryAfterMs: Number.MIN_VALUE, requestId: 'req-1' },
-    })
-  })
+    await Promise.resolve()
 
-  it('projects always-mode retries and rejects mode-specific maximums or unknown modes', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
-    try {
-      feed(at(6, {
-        type: 'llm/retry',
-        data: {
-          turn: 1, step: 0,
-          provider: 'fake', mode: 'always', policyKey: 'fake-always',
-          retry: 3, delayMs: 500,
-          failure: { code: 'TRANSPORT', message: 'retry forever' },
-        },
-      }))
-      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-        kind: 'model-retry',
-        retryState: 'scheduled',
-        mode: 'always',
-        retry: 3,
-      })
-
-      feed(at(7, {
-        type: 'llm/retry',
-        data: {
-          turn: 2, step: 0,
-          provider: 'fake', mode: 'always', policyKey: 'fake-always',
-          retry: 4, maxRetries: 4, delayMs: 500,
-          failure: { code: 'TRANSPORT', message: 'unexpected maximum' },
-        },
-      }))
-      feed(at(8, {
-        type: 'llm/retry',
-        data: {
-          turn: 2, step: 0,
-          provider: 'fake', mode: 'sometimes', policyKey: 'fake-unknown',
-          retry: 4, delayMs: 500,
-          failure: { code: 'TRANSPORT', message: 'unknown mode' },
-        },
-      }))
-      expect(session.getSnapshot().nodes.filter(node => node.kind === 'model-retry')).toHaveLength(1)
-      expect(errorSpy).toHaveBeenCalledTimes(2)
-    } finally {
-      errorSpy.mockRestore()
-    }
-  })
-
-  it.each(['aborted', 'disposed'] as const)(
-    'marks a scheduled retry as cancelled when its failed turn receives the %s cause',
-    async (reason) => {
-      const { session } = await opened()
-      const feed = (event: SessionEvent) => {
-        session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
-      }
-      feed(ev.turnStart(6, 1))
-      feed(ev.retry(7, 1))
-      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-        kind: 'model-retry',
-        retryState: 'scheduled',
-      })
-      feed(ev.turnEnd(8, 1, reason))
-      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-        kind: 'model-retry',
-        retryState: 'cancelled',
-      })
-    },
-  )
-
-  it('marks a scheduled retry as started when its failed turn ends with an error', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => {
-      session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
-    }
-    feed(ev.turnStart(6, 1))
-    feed(ev.retry(7, 1))
-    feed(at(8, {
-      type: 'turn/end',
-      data: { turn: 1, reason: { kind: 'error', error: { message: 'retry failed', code: 'UNKNOWN' } } },
-    }))
-
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'model-retry',
-      retryState: 'started',
-    })
-  })
-
-  it('freezes an unfinalized partial into an interrupted node on turn/end (cancel path)', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.user(7, '要被打断的'))
-    feed(ev.chunkStart(8, 1))
-    feed(ev.chunkText(9, 1, '说到一半'))
-    feed(ev.turnEnd(10, 1, 'aborted')) // no assistant/message ever arrives
-    const snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    expect(snapshot.turnEnds.get(1)).toBe(10)
-    const frozen = snapshot.nodes.at(-1)
-    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'text', text: '说到一半' }] })
-    // Ordered inside the flow: after the user message (seq 7), before any later turn.
-    expect((frozen as { seq: number }).seq).toBeGreaterThan(7)
-  })
-
-  it('tracks tool calls in runningCalls and converts orphans to interrupted tool-result cards on turn/end', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'c1', 'echo', '{"a":1}'))
-    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'c1', name: 'echo' }])
-    feed(ev.toolResult(8, 1, 'c1', 'ECHO'))
-    expect(session.getSnapshot().runningCalls).toEqual([])
-    // Second call never resolves: turn/end freezes it as an error card.
-    feed(ev.toolCall(9, 1, 'c2', 'slow_tool', '{}'))
-    feed(ev.turnEnd(10, 1, 'aborted'))
-    const snapshot = session.getSnapshot()
-    expect(snapshot.runningCalls).toEqual([])
-    expect(snapshot.nodes.at(-1)).toMatchObject({
-      kind: 'tool-result', callId: 'c2', isError: true, error: { code: 'interrupted' },
-    })
-  })
-
-  it('keeps compacted history and adds one marker, live and on replay alike', async () => {
-    // A landed compaction must not erase conversation the reader already saw:
-    // the shadowed messages stay at their own log positions and the checkpoint
-    // contributes one marker after them.
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.compactSummary(6, '压缩摘要', 1, 3))
-    feed(ev.compactCheckpoint(7, 6, 1, 3))
-    const live = session.getSnapshot().nodes
-    expect(live.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
-    expect(live.at(-1)).toMatchObject({ kind: 'compaction', summary: '压缩摘要' })
-
-    const replayed = await opened([
-      ...plainTurn(0, 0, 'a', 'b'),
-      ev.compactSummary(6, '压缩摘要', 1, 3),
-      ev.compactCheckpoint(7, 6, 1, 3),
-    ])
-    expect(replayed.session.getSnapshot().nodes).toEqual(live)
-  })
-
-  it('merges an interrupted frozen node by seq into the log-ordered transcript', async () => {
-    // The transcript array is seq-monotonic, so the frozen node's fractional
-    // seq lands it exactly where it happened — including after a compaction
-    // checkpoint whose own seq is higher than the range it shadowed.
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.compactSummary(6, '压缩摘要', 1, 3))
-    feed(ev.compactCheckpoint(7, 6, 1, 3))
-    feed(ev.turnStart(8, 1))
-    feed(ev.user(9, '压缩后的提问'))
-    feed(ev.chunkStart(10, 1))
-    feed(ev.chunkText(11, 1, '说到一半'))
-    feed(ev.turnEnd(12, 1, 'aborted'))
-    expect(session.getSnapshot().nodes.map(n => n.kind)).toEqual([
-      'user', 'assistant', 'compaction', 'user', 'assistant',
-    ])
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({ interrupted: true })
+    expect(snapshots).toHaveLength(1)
+    expect(snapshots[0]?.chat.timeline.turns.get(1)?.status).toBe('open')
   })
 
   it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
@@ -578,11 +366,7 @@ describe('paging', () => {
     expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
   })
 
-  it('renders a page whose checkpoint shadows seqs below the window head, logging nothing', async () => {
-    // Pagination no longer spends maxMessages quota on replacement copies, so a
-    // page can carry a compaction checkpoint whose surfaceOp.start lies outside
-    // the window. The old surface fold rejected that range and degraded with a
-    // console error; the log-ordered transcript has no range to resolve.
+  it('installs a page without interpreting business replacement metadata', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse([
       ev.compactSummary(80, '窗外范围的摘要', 3, 40),
@@ -594,8 +378,7 @@ describe('paging', () => {
       await session.open()
       const snapshot = session.getSnapshot()
       expect(snapshot.openState).toBe('open')
-      expect(snapshot.nodes.map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
-      expect(snapshot.nodes[0]).toMatchObject({ summary: '窗外范围的摘要' })
+      expect(chatSeqs(snapshot)).toEqual([80, 81, 82])
       expect(errorSpy).not.toHaveBeenCalled()
     } finally {
       errorSpy.mockRestore()
@@ -712,6 +495,7 @@ describe('prompt and cancel errors', () => {
 
   it('sends content through session.prompt; composerPhase steps blank → engaging synchronously at send entry', async () => {
     const { api, session } = makeSession()
+    session.handleBlank(true)
     // The blank → engaging edge fires before the RPC settles: the first-send
     // flow reads the phase on the session area's first frame to keep the
     // guidance hero from flashing back in.
@@ -730,6 +514,7 @@ describe('prompt and cancel errors', () => {
 
   it('business failure lands in promptError with op=send; the phase stays engaging (retry, no hero bounce)', async () => {
     const { api, session } = makeSession()
+    session.handleBlank(true)
     api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: 'busy', details: { reason: 'x' } }))
     const result = await session.prompt([{ type: 'text', text: '失败的' }], 'queue')
     expect(result.ok).toBe(false)
@@ -969,33 +754,6 @@ describe('remaining branches', () => {
     }
   })
 
-  it('freezes only content-bearing partials; a content-free partial is dropped outright', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.chunkStart(7, 1)) // empty text block only, no delta
-    feed(ev.turnEnd(8, 1, 'aborted'))
-    const snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    expect(snapshot.nodes.filter(n => n.kind === 'assistant' && (n as { interrupted?: true }).interrupted)).toEqual([])
-  })
-
-  it('turn/end sweeps only same-turn open calls; other turns keep running', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'turn1-call', 'echo', '{}'))
-    feed(ev.toolCall(8, 2, 'turn2-call', 'echo', '{}')) // stray call attributed to a later turn
-    feed(ev.turnEnd(9, 1, 'aborted'))
-    const snapshot = session.getSnapshot()
-    expect(snapshot.runningCalls.map(c => c.callId)).toEqual(['turn2-call'])
-    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'tool-result', callId: 'turn1-call', isError: true })
-  })
-
   it('doOpen transport throw of a stale generation is swallowed (generation guard in catch)', async () => {
     const { api, session } = makeSession()
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
@@ -1065,28 +823,13 @@ describe('remaining branches', () => {
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
   })
 
-  it('successful cancel leaves no promptError; tool/result for an unknown callId is a no-op', async () => {
+  it('successful cancel leaves no promptError', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
     await session.open()
     const result = await session.cancel()
     expect(result.ok).toBe(true)
     expect(session.getSnapshot().promptError).toBeNull()
-    const callsBefore = session.getSnapshot().runningCalls
-    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.toolResult(6, 0, 'never-called', 'x') })
-    expect(session.getSnapshot().runningCalls).toBe(callsBefore) // callsRev untouched: same reference
-  })
-
-  it('freezes a tool-call-only partial (visible through the non-text arm)', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(at(7, { type: 'assistant/chunk', data: { turn: 1, step: 0, chunk: { type: 'tool-call-delta', index: 0, id: 'c1', name: 'echo', argumentsDelta: '{' } } }))
-    feed(ev.turnEnd(8, 1, 'aborted'))
-    const frozen = session.getSnapshot().nodes.at(-1)
-    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'tool-call', callId: 'c1' }] })
   })
 
   it('dispose is a reserved no-op on resident instances', () => {
@@ -1094,7 +837,7 @@ describe('remaining branches', () => {
     expect(() => { session.dispose() }).not.toThrow()
   })
 
-  it('carries mux-frame views into runningCalls and tool-result nodes, and history-entry views through open', async () => {
+  it('carries history-entry and mux-frame views into the business-neutral Event input', async () => {
     const { api, session } = makeSession()
     const callView = { for: 'call', view: { card: 'generic', title: '历史卡' } }
     api.onHistory = () => Promise.resolve(ok({
@@ -1107,21 +850,23 @@ describe('remaining branches', () => {
       modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await session.open()
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'tool-result', callView: { title: '历史卡' }, resultView: { title: '历史果' },
-    })
-    // Live path: the frame's view slot reaches runningCalls, then the result node.
+    expect(chatEvents(session.getSnapshot()).slice(-2).map(item => item.view)).toEqual([
+      callView,
+      { for: 'result', view: { card: 'generic', title: '历史果' } },
+    ])
     session.handleMuxEnvelope('rv1' as never, {
       type: 'session/event', sessionId: SID, event: ev.toolCall(8, 2, 'l1', 'write', '{}'),
       view: { for: 'call', view: { card: 'generic', title: '直播卡' } },
     } as never)
-    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'l1', callView: { title: '直播卡' } }])
+    expect(chatEvents(session.getSnapshot()).at(-1)?.view).toEqual({
+      for: 'call', view: { card: 'generic', title: '直播卡' },
+    })
     session.handleMuxEnvelope('rv2' as never, {
       type: 'session/event', sessionId: SID, event: ev.toolResult(9, 2, 'l1', 'ok'),
       view: { for: 'result', view: { card: 'generic', title: '直播果' } },
     } as never)
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'tool-result', callView: { title: '直播卡' }, resultView: { title: '直播果' },
+    expect(chatEvents(session.getSnapshot()).at(-1)?.view).toEqual({
+      for: 'result', view: { card: 'generic', title: '直播果' },
     })
   })
 })
@@ -1177,163 +922,27 @@ describe('resync', () => {
 
 })
 
-describe('nested run_code sub-dispatches', () => {
-  const subCallsOf = (session: Session, callId: string) => {
-    const snapshot = session.getSnapshot()
-    const running = snapshot.runningCalls.find(call => call.callId === callId)
-    if (running !== undefined) return running.subCalls
-    for (const node of snapshot.nodes) {
-      if (node.kind === 'tool-result' && node.callId === callId) return node.subCalls
-    }
-    return undefined
-  }
-
-  it('a start event lands as a running-shaped sub-call and its settle replaces it in place', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
-    feed(ev.codeDispatchStart(8, 'p1', 1, 'bash', { command: 'sleep' }))
-    feed(ev.codeDispatchStart(9, 'p1', 2, 'read', { path: 'a.txt' }))
-    const live = subCallsOf(session, 'p1')
-    expect(live).toHaveLength(2)
-    // Running shape (no 'kind'): the exact RunningToolCall form native rows use.
-    expect(live?.[0]).toMatchObject({ callId: 'p1:code:1', name: 'bash', argsRaw: '{"command":"sleep"}' })
-    expect(live?.[0] !== undefined && 'kind' in live[0]).toBe(false)
-    // Settle out of order (parallel run): #2 first — replaces in place, keeping start order.
-    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'a.txt' }, 'alpha'))
-    const mixed = subCallsOf(session, 'p1')
-    expect(mixed?.map(sub => 'kind' in sub)).toEqual([false, true])
-    expect(mixed?.[1]).toMatchObject({ callId: 'p1:code:2', content: [{ type: 'text', text: 'alpha' }] })
-    // The settle carries the paired start's time as callTime (duration source).
-    feed(ev.codeDispatch(11, 'p1', 1, 'bash', { command: 'sleep' }, 'done'))
-    const settled = subCallsOf(session, 'p1')
-    expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
-    expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
-  })
-
-  it('indexes live tool/code-dispatch events under their parent as native-shaped result nodes', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'))
-    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls', description: '列目录' }, 'demo.txt'))
-    feed(ev.codeDispatch(9, 'p1', 2, 'read', { path: 'a.txt' }, 'Error: ENOENT', true))
-    const subs = subCallsOf(session, 'p1')
-    expect(subs).toHaveLength(2)
-    expect(subs?.[0]).toMatchObject({
-      kind: 'tool-result', callId: 'p1:code:1',
-      call: { name: 'bash', argsRaw: '{"command":"ls","description":"列目录"}' },
-      // The settle event carries no start time: callTime stays null (never a
-      // fabricated zero-duration).
-      callTime: null,
-      isError: false, content: [{ type: 'text', text: 'demo.txt' }],
-    })
-    expect(subs?.[1]).toMatchObject({ callId: 'p1:code:2', isError: true })
-    // No paired start in the window: duration is UNKNOWN (null), never a
-    // fabricated zero-duration span.
-    expect(subs?.[0]).toMatchObject({ callTime: null })
-    // Sub-dispatches never join the surface flow.
-    expect(session.getSnapshot().nodes.some(n => n.kind === 'tool-result' && n.callId.includes(':code:'))).toBe(false)
-  })
-
-  it('rebuilds the same nested tree from a history window (replay parity)', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse([
-      ...plainTurn(0, 0, '问', '答'),
-      ev.turnStart(6, 1),
-      ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'),
-      ev.codeDispatchStart(8, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }),
-      ev.codeDispatch(9, 'p1:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
-      ev.codeDispatch(10, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }, 'alpha'),
-      ev.toolResult(11, 1, 'p1', '{"done":true}'),
-      ev.turnEnd(12, 1),
-    ])
-    await session.open()
-    const subs = subCallsOf(session, 'p1')
-    expect(subs).toHaveLength(1)
-    expect(subs?.[0]).toMatchObject({
-      callId: 'p1:code:1',
-      call: { name: 'run_code' },
-      subCalls: [{ callId: 'p1:code:1:code:1', call: { name: 'read' } }],
-    })
-  })
-
-  it('keeps an unaffected root reference and path-copies it on a new child', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
-    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'x'))
-    const before = session.getSnapshot()
-    const beforeRoot = before.runningCalls.find(call => call.callId === 'p1')!
-    feed(ev.chunkStart(9, 1))
-    feed(ev.chunkText(10, 1, '流式'))
-    const after = session.getSnapshot()
-    const afterRoot = after.runningCalls.find(call => call.callId === 'p1')!
-    expect(afterRoot).toBe(beforeRoot)
-    feed(ev.codeDispatch(11, 'p1', 2, 'read', { path: 'a' }, 'y'))
-    const changedRoot = session.getSnapshot().runningCalls.find(call => call.callId === 'p1')!
-    expect(changedRoot).not.toBe(afterRoot)
-    expect(changedRoot.subCalls[0]).toBe(afterRoot.subCalls[0])
-    expect(changedRoot.subCalls).toHaveLength(2)
-  })
-
-  it('path-copies only the owning branch when a nested child changes', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '树', '结构'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"first"}'))
-    feed(ev.toolCall(8, 1, 'p2', 'run_code', '{"code":"2","description":"second"}'))
-    feed(ev.codeDispatch(9, 'p1', 1, 'run_code', { code: 'nested' }, 'child'))
-    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'sibling' }, 'sibling'))
-    feed(ev.codeDispatch(11, 'p2', 1, 'bash', { command: 'pwd' }, 'root two'))
-    const before = session.getSnapshot()
-    const beforeFirst = before.runningCalls.find(call => call.callId === 'p1')!
-    const beforeSecond = before.runningCalls.find(call => call.callId === 'p2')!
-    const beforeChild = beforeFirst.subCalls[0]!
-    const beforeSibling = beforeFirst.subCalls[1]!
-
-    feed(ev.codeDispatch(12, 'p1:code:1', 1, 'read', { path: 'nested' }, 'leaf'))
-    const after = session.getSnapshot()
-    const afterFirst = after.runningCalls.find(call => call.callId === 'p1')!
-    const afterSecond = after.runningCalls.find(call => call.callId === 'p2')!
-
-    expect(afterFirst).not.toBe(beforeFirst)
-    expect(afterSecond).toBe(beforeSecond)
-    expect(afterFirst.subCalls[0]).not.toBe(beforeChild)
-    expect(afterFirst.subCalls[1]).toBe(beforeSibling)
-    expect(afterFirst.subCalls[0]?.subCalls).toMatchObject([
-      { callId: 'p1:code:1:code:1', call: { name: 'read' } },
-    ])
-  })
-})
-
 describe('reference stability (the memo contract)', () => {
   it('keeps unchanged node references across an append and swaps the snapshot object', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
     await session.open()
     const before = session.getSnapshot()
+    const firstKey = before.chat.order[0]!
+    const secondKey = before.chat.order[1]!
+    const first = before.chat.nodes.get(firstKey)
+    const second = before.chat.nodes.get(secondKey)
     session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(6, '追加') })
     const after = session.getSnapshot()
     expect(after).not.toBe(before) // top-level swap on change
-    expect(after.nodes[0]).toBe(before.nodes[0]) // untouched nodes keep identity
-    expect(after.nodes[1]).toBe(before.nodes[1])
-    expect(after.nodes).toHaveLength(3)
+    expect(after.chat.nodes.get(firstKey)).toBe(first)
+    expect(after.chat.nodes.get(secondKey)).toBe(second)
+    expect(after.chat.order).toHaveLength(7)
     // No change → same snapshot reference.
     expect(session.getSnapshot()).toBe(after)
   })
 
-  it('keeps untouched substructure arrays identical across unrelated changes (revision counters)', async () => {
+  it('keeps unrelated Session arrays and settled Chat Nodes stable across Event updates', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '底', '座'))
     await session.open()
@@ -1343,20 +952,19 @@ describe('reference stability (the memo contract)', () => {
     feed(ev.toolCall(8, 1, 'c1', 'echo', '{}'))
     session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
     const before = session.getSnapshot()
-    // A chunk storm touches partial/nodes only: unrelated projections keep identity.
+    const settledKey = before.chat.order[0]!
+    const settledNode = before.chat.nodes.get(settledKey)
     feed(ev.chunkStart(9, 1))
     feed(ev.chunkText(10, 1, '与工具无关的流式'))
     const after = session.getSnapshot()
     expect(after).not.toBe(before)
     expect(after.runningCalls).toBe(before.runningCalls)
     expect(after.pending).toBe(before.pending)
-    expect(after.turnTimings).toBe(before.turnTimings)
-    expect(after.turnEnds).toBe(before.turnEnds)
-    // And a mutation on the tracked domain swaps that array.
+    expect(after.chat.nodes.get(settledKey)).toBe(settledNode)
     feed(ev.toolResult(11, 1, 'c1', 'ECHO'))
     const resolved = session.getSnapshot()
-    expect(resolved.runningCalls).not.toBe(after.runningCalls)
     expect(resolved.pending).toBe(after.pending)
+    expect(resolved.chat.nodes.get(settledKey)).toBe(settledNode)
     feed(ev.assistant(12, 1, '完成'))
     expect(session.getSnapshot()).not.toBe(resolved)
   })
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
deleted file mode 100644
index b161046f84..0000000000
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ /dev/null
@@ -1,567 +0,0 @@
-/**
- * TranscriptAdapter over the raw append-only window: log-ordered projection of
- * append-origin events, one marker per landed compaction, replacement copies
- * hidden, command-lifecycle folding, node/array identity, call pairing, and
- * host-provided wire views.
- */
-
-import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
-import { describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
-import { ev, plainTurn } from './event-script.ts'
-
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
-  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
-
-/** A `compact/summary` event (log-only, no surfaceOp). */
-function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
-  return at(seq, {
-    type: 'compact/summary',
-    data: {
-      summary,
-      shadowedRange: { start: 1, end: 3 },
-      shadowedSeqs: [1, 3],
-      shadowedTokenCount: 100,
-      provider: 'fake',
-      model: 'compact-1',
-    },
-  })
-}
-
-/** The replacement user message a compaction backend lands (the checkpoint). */
-function checkpoint(
-  seq: number,
-  summarySeq: number,
-  { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: {
-    start?: number
-    end?: number
-    sourceEventSeqs?: number[]
-  } = {},
-): SessionEvent {
-  return at(seq, {
-    type: 'user/message',
-    surfaceOp: { op: 'replace', start, end },
-    sourceEventSeqs,
-    data: createUserMessage({
-      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
-      source: { kind: 'plugin', plugin: 'compact' },
-    }),
-  })
-}
-
-describe('TranscriptAdapter', () => {
-  it('projects a window starting past seq 0 at its own log positions', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(100, 5, '偏移问', '偏移答'))
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
-  })
-
-  it('appends incrementally keeping old node references (materialize-once identity)', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const first = adapter.nodes()
-    adapter.append(ev.user(6, '追加'))
-    const second = adapter.nodes()
-    expect(second).toHaveLength(3)
-    expect(second[0]).toBe(first[0])
-    expect(second[1]).toBe(first[1])
-    expect(second).not.toBe(first) // a real change swaps the array
-  })
-
-  it('keeps the array reference across a chunk storm and swaps it when a node lands', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const settled = adapter.nodes()
-    adapter.append(ev.chunkStart(6, 1))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.chunkText(7, 1, '流式'))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.assistant(8, 1, '流式完成'))
-    const finalized = adapter.nodes()
-    expect(finalized).not.toBe(settled)
-    expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 })
-  })
-
-  it('materializes every append-origin variant with field mapping', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: '插话' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([
-      ev.user(0, '用户'),
-      ev.assistant(1, 0, '助手'),
-      at(2, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [steering],
-      } }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(4, { type: 'user/message', surfaceOp: 'append', data: steering }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' },
-      }) }),
-      ev.toolCall(6, 0, 'c1', 'echo', '{"x":1}'),
-      ev.toolResult(7, 0, 'c1', '结果'),
-    ])
-    const nodes = adapter.nodes()
-    expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result'])
-    expect(nodes.find(n => n.kind === 'steering')).toMatchObject({ messageId: steering.id })
-    expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({
-      callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false,
-    })
-  })
-
-  it('identifies steering on the live append path', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: 'live steer' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([])
-    adapter.append(at(0, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, inserted: [steering],
-    } }))
-    adapter.append(at(1, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, removedCount: 1, inserted: [],
-    } }))
-    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: steering }))
-    expect(adapter.nodes()).toMatchObject([{ kind: 'steering', messageId: steering.id }])
-  })
-
-  it('does not mark queued, canceled, or non-user next-step messages as steering', () => {
-    const adapter = new TranscriptAdapter()
-    const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } })
-    const canceled = createUserMessage({ content: [{ type: 'text', text: 'canceled' }], source: { kind: 'user' } })
-    const context = createUserMessage({
-      content: [{ type: 'text', text: 'context' }],
-      source: { kind: 'plugin', plugin: 'test' },
-    })
-    adapter.reset([
-      at(0, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, inserted: [queued],
-      } }),
-      at(1, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(2, { type: 'user/message', surfaceOp: 'append', data: queued }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [canceled],
-      } }),
-      at(4, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [], outcome: 'canceled',
-      } }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: canceled }),
-      at(6, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [context],
-      } }),
-      at(7, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(8, { type: 'user/message', surfaceOp: 'append', data: context }),
-    ])
-    expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
-  })
-
-  it('materializes a skill-invocation injection as a named instructions context', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
-        source: { kind: 'user' },
-      }) }),
-      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
-        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
-      }) }),
-    ])
-    const nodes = adapter.nodes()
-    // The gesture stays a user bubble; the injected body folds to a context
-    // row named after the skill, presented as instructions.
-    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
-    expect(nodes[1]).toMatchObject({
-      provenance: { role: 'inject', label: 'hidden-demo' },
-      form: 'instructions',
-    })
-  })
-
-  it('skips events core does not call surface-eligible, marker or not', () => {
-    // The transcript is the append-origin surface, so log-only events (a chunk,
-    // a turn boundary, a `compact/*` record) and a future type core
-    // has not admitted contribute no node.
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      ev.turnStart(0, 1),
-      at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }),
-      compactSummary(2),
-      ev.user(3, '唯一的一条'),
-      ev.turnEnd(4, 1),
-    ])
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]])
-  })
-
-  describe('compaction markers', () => {
-    it('keeps the original messages and full tool output, hiding replacement copies', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '原始问题'),
-        ev.assistant(1, 0, '原始回答'),
-        ev.toolCall(4, 0, 'c1', 'echo', '{}'),
-        ev.toolResult(5, 0, 'c1', '完整工具输出'),
-        // A pruned tool/result copy: rewrites one node for the model, marks nothing.
-        at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: {
-          turn: 0, step: 0,
-          message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }),
-        } }),
-        compactSummary(7),
-        checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }),
-        // A regenerated assistant/message: also a silent model-only rewrite.
-        at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: {
-          turn: 0, step: 0,
-          message: createMessage({
-            role: 'assistant',
-            content: [{ type: 'text', text: '通用 replacement 副本' }],
-            source: { kind: 'model', ...{ provider: 'x', model: 'copy' } },
-          }),
-        } }),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([
-        ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8],
-      ])
-      expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] })
-      expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' })
-    })
-
-    it('adds one marker per landed compaction, in log order', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, 'a'),
-        compactSummary(1, [{ type: 'text', text: 'first' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-        ev.user(3, 'b'),
-        compactSummary(4, [{ type: 'text', text: 'second' }]),
-        checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
-      ])
-      expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-        {
-          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
-          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('renders the marker when the shadowed range is outside the window and logs nothing', () => {
-      // The pagination hole A1 left open: quota is no longer spent on
-      // replacement copies, so a page can carry a checkpoint whose
-      // surfaceOp.start lies below the window head. The old surface fold threw
-      // on the missing range and degraded with a console error; a log-ordered
-      // projection has no range to resolve.
-      const adapter = new TranscriptAdapter()
-      const noise = { error: console.error, warn: console.warn }
-      const logged: unknown[] = []
-      console.error = (...args: unknown[]) => logged.push(args)
-      console.warn = (...args: unknown[]) => logged.push(args)
-      try {
-        adapter.reset([
-          compactSummary(80, [{ type: 'text', text: '窗外范围' }]),
-          checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }),
-          ev.user(82, '压缩后的新问题'),
-        ])
-        expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
-        expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' })
-      } finally {
-        console.error = noise.error
-        console.warn = noise.warn
-      }
-      expect(logged).toEqual([])
-    })
-
-    it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => {
-      // A session-reference card carries the same plugin source shape; only the
-      // replacement marker makes an event a checkpoint.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-          content: [{ type: 'text', text: '注入的上下文' }],
-          source: { kind: 'plugin', plugin: 'compact', form: 'instructions' },
-        }) }),
-      ])
-      expect(adapter.nodes()).toMatchObject([{
-        kind: 'context',
-        seq: 0,
-        provenance: { role: 'inject', label: 'compact' },
-        form: 'instructions',
-      }])
-    })
-
-    it('ignores a foreign plugin s replacement user/message', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '保留'),
-        at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({
-          content: [{ type: 'text', text: '别的插件重写' }],
-          source: { kind: 'plugin', plugin: 'not-compact' },
-        }) }),
-      ])
-      expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]])
-    })
-
-    it.each([
-      ['absent summary event', undefined],
-      ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
-      ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
-      ['an empty summary array', compactSummary(1, [])],
-      ['a non-array summary', compactSummary(1, 'plain string')],
-    ])('degrades %s to a non-expandable marker', (_label, summary) => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ...(summary === undefined ? [] : [summary]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toMatchObject([
-        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
-      ])
-    })
-
-    it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => {
-      // ContentBlock is merge-extensible and the payload type is ContentBlock[],
-      // so a non-text block must not discard recoverable text beside it.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('leaves the summary null when the checkpoint cites no source events', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([at(2, {
-        type: 'user/message',
-        surfaceOp: { op: 'replace', start: 0, end: 0 },
-        data: createUserMessage({
-          content: [{ type: 'text', text: '<context_checkpoint>x</context_checkpoint>' }],
-          source: { kind: 'plugin', plugin: 'compact' },
-        }),
-      })])
-      expect(adapter.nodes()).toEqual([{
-        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
-        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
-      }])
-    })
-
-    it('skips a cited non-summary seq before reaching the summary event', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '被压缩的问题'),
-        at(1, { type: 'compact/start', data: { turn: 0 } }),
-        compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }),
-      ])
-      expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
-    })
-
-    it('resolves the summary once an older page supplies the cited summary event', () => {
-      const adapter = new TranscriptAdapter()
-      const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
-      adapter.reset([landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null })
-      adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' })
-    })
-
-    it('creates the marker on the live append path', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'a', 'b'))
-      adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }]))
-      adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] }))
-      const nodes = adapter.nodes()
-      // The compacted history is still there; the marker is one more row after it.
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
-      expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' })
-    })
-  })
-
-  it('returns call:null for a tool-result whose call fell outside the window', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
-  })
-
-  it('materializes a tool-result error field when present', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'tool/result', surfaceOp: 'append', data: {
-        turn: 0, step: 0,
-        message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }),
-        error: { name: 'Boom', code: 'boom' },
-      } }),
-    ])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
-  })
-
-  it('attaches wire views to the materialized result node', () => {
-    const adapter = new TranscriptAdapter()
-    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
-    adapter.reset([
-      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
-      ev.toolResult(1, 1, 'c1', 'listing'),
-    ], [callView, resultView] as never)
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' },
-    })
-  })
-
-  it('attaches views on the live append path and defaults to null without views', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument
-    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
-    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { title: '回声' }, resultView: null,
-    })
-  })
-
-  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
-    const adapter = new TranscriptAdapter()
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
-    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never)
-    expect(adapter.nodes()[0]).toMatchObject({
-      kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' },
-    })
-  })
-
-  describe('command lifecycle nodes', () => {
-    it('folds a run/done pair into one settled node merged into flow order by seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '先说话'),
-        ev.commandRun(1, 'cmd-1', 'plan'),
-        ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'),
-        ev.assistant(3, 0, '然后回答'),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]])
-      expect(nodes[1]).toMatchObject({
-        kind: 'command', commandId: 'cmd-1', name: 'plan', args: '',
-        outcome: { kind: 'success', text: '已进入 plan mode' },
-      })
-    })
-
-    it('renders a run with no done as still executing (outcome null)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null })
-    })
-
-    it('represents command input omitted by the host as null', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', name: 'feedback', args: null, outcome: null,
-      })
-    })
-
-    it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null,
-        outcome: { kind: 'error', text: '失败了' },
-      })
-    })
-
-    it('settles a live-appended done in place, keeping the node at the run seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'q', 'a'))
-      adapter.append(ev.commandRun(6, 'cmd-4', 'clear'))
-      const running = adapter.nodes().find(n => n.kind === 'command')
-      expect(running).toMatchObject({ outcome: null })
-      adapter.append(ev.commandDone(7, 'cmd-4'))
-      const settled = adapter.nodes().find(n => n.kind === 'command')
-      expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } })
-      // Settlement replaced the node object rather than mutating the published one.
-      expect(settled).not.toBe(running)
-    })
-
-    it('tails command nodes whose seq is past every transcript node', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')])
-      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
-    })
-
-    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '压缩前的问题'),
-        ev.commandRun(1, 'cmd-compact', 'compact'),
-        compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
-        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
-      expect(nodes[1]).toMatchObject({
-        name: 'compact',
-        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
-      })
-      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
-    })
-  })
-
-  describe('assistant timing', () => {
-    const base = 1_700_000_000_000
-
-    it('derives step timing across a window rebuild (start + first token + completion)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.turnStart(0, 0),
-        ev.user(1, '问'),
-        ev.stepStart(2, 0),
-        ev.chunkStart(3, 0),
-        ev.chunkText(4, 0, '答'),
-        ev.chunkText(5, 0, '案'),
-        ev.assistant(6, 0, '答案'),
-        ev.turnEnd(7, 0),
-      ])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
-      })
-    })
-
-    it('derives the same timing on the live append path, first token winning once', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问')])
-      adapter.append(ev.stepStart(1, 0))
-      adapter.append(ev.chunkText(2, 0, '首'))
-      adapter.append(ev.chunkText(3, 0, '次'))
-      adapter.append(ev.assistant(4, 0, '首次'))
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
-      })
-    })
-
-    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
-      })
-    })
-  })
-})
diff --git a/packages/client/test-runtime/src/fixtures.ts b/packages/client/test-runtime/src/fixtures.ts
index ea01893346..7f65a0b5a3 100644
--- a/packages/client/test-runtime/src/fixtures.ts
+++ b/packages/client/test-runtime/src/fixtures.ts
@@ -2,6 +2,7 @@
 import type {
   ConversationSnapshot, ISession, SessionId, SessionSummary, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import { EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 
 /**
  * Fixture overrides for the session behavior face: any subset of the
@@ -45,6 +46,7 @@ export interface SessionFixture {
 export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot {
   return {
     sessionId,
+    chat: EMPTY_CHAT_SNAPSHOT,
     nodes: [],
     turnTimings: new Map(),
     turnEnds: new Map(),
diff --git a/packages/client/test-runtime/src/index.ts b/packages/client/test-runtime/src/index.ts
index 3005c061e7..0b8c732683 100644
--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -22,7 +22,9 @@ import { act, render, within } from '@testing-library/react'
 import type { RenderResult } from '@testing-library/react'
 import type { queries } from '@testing-library/dom'
 import type { BoundFunctions } from '@testing-library/dom'
-import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationEventRegistry, ConversationViewRegistry, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
 import type {
   ChildrenDecl, ComposedProps, OwnerOf, SlotComponent, SlotMap, SlotRendererHost, StoreInstanceLike,
@@ -142,7 +144,7 @@ export class TestRoot {
    */
   async declare<const D extends ChildrenDecl>(
     children: D,
-    frame: SlotComponent<ComposedProps<'root', keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>,
+    frame: SlotComponent<ComposedProps<'root', never, keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>,
   ): Promise<void> {
     await this.stabilize(() => {
       // Erased hop (same pattern as SlotsService's own implementation arm);
@@ -218,6 +220,8 @@ export class SlotTestRuntime {
     const ctx = new Context()
     const fiber = ctx.plugin(SlotsService)
     await fiber.await()
+    await ctx.plugin(ConversationEventRegistry).await()
+    await ctx.plugin(ConversationViewRegistry).await()
     return new SlotTestRuntime(ctx, ctx.get('slots') as SlotsService)
   }
 
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index 00001275d2..3481ee758e 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -53,7 +53,7 @@ describe('apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('registers the chat view as the first ring entry, declaring the whole-Tool seat', async () => {
+  it('registers the chat view and its keyed business-node seat', async () => {
     const b = await bench()
     const entries = b.slots.entries('conversation.view')
     expect(entries.map(e => e.options.id)).toEqual(['chat'])
@@ -62,7 +62,7 @@ describe('apply wiring', () => {
     expect(entries[0]?.options.order).toBe(0)
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
-    expect(b.slots.spec('conversation.chat.tool')).toEqual({ kind: 'single', scope: 'session' })
+    expect(b.slots.spec('conversation.chat.node')).toEqual({ kind: 'keyed', scope: 'session' })
     await b.runtime.dispose()
   })
 
@@ -95,7 +95,7 @@ describe('apply wiring', () => {
     // file-mutation registrant claims both write and edit for the diff card; the
     // one search row registers under both grep and glob; the web rows register
     // one component under both web tool names.
-    expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
+    expect(b.slots.entries('conversation.chat.node').map(entry => entry.options.key)).not.toContain('tool-call')
     // Stats stick with the composer (not inside ChatView).
     expect(b.slots.entries('conversation.composer.dock').map(e => e.options.id)).toEqual(['stats'])
     await b.runtime.dispose()
@@ -108,8 +108,8 @@ describe('apply wiring', () => {
     // The declared ring collapses with its declaring entry, and the chat
     // entry's keyed hole (with the sample's registration) collapses with it.
     expect(b.slots.entries('conversation.view')).toHaveLength(0)
-    expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
-    expect(b.slots.spec('conversation.chat.tool')).toBeUndefined()
+    expect(b.slots.entries('conversation.chat.node')).toHaveLength(0)
+    expect(b.slots.spec('conversation.chat.node')).toBeUndefined()
     expect(b.slots.entries('details')).toHaveLength(0)
     expect(b.slots.entries('settings.general.item')).toHaveLength(0)
     expect(b.runtime.ctx.get('conversation')).toBeUndefined()
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 0362c3ee4b..6037405336 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -10,13 +10,21 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import type {
+  ChatConversationViewNode, ConversationNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNodeViewProps } from '../src/client/contract/slots.ts'
 import {
   formatMessageClock, msUntilNextLocalMidnight, startOfLocalDay,
 } from '../src/client/chat/message-chrome.ts'
-import { MessageItem, type MessageItemProps } from '../src/client/chat/MessageItem.tsx'
+import {
+  CompactionNodeView, ContextMessageNodeView, RetryNodeView, UnknownNodeView,
+  UserMessageNodeView,
+} from '../src/client/chat/MessageItem.tsx'
 import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
 import { StatsLine, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 import { zh } from '../src/client/locales.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 /** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
 class ResizeObserverStub {
@@ -33,7 +41,44 @@ afterEach(() => {
 })
 
 // Mirrors the real lookup chain (conversation namespace, then common).
-const t: MessageItemProps['t'] = makeTranslate(zh, commonZh)
+const t: ChatNodeViewProps['t'] = makeTranslate(zh, commonZh)
+const RETRY_ID = 'retry-fixture' as Extract<ConversationNode, { kind: 'model-retry' }>['retryId']
+
+interface MessageItemProps {
+  readonly node: ConversationNode
+  readonly t: ChatNodeViewProps['t']
+}
+
+/** Legacy-node fixture adapter for the independently registered renderers. */
+function MessageItem({ node, t: translate }: MessageItemProps) {
+  const kind = node.kind === 'assistant' ? 'assistant-step' : node.kind
+  const viewNode: ChatConversationViewNode = {
+    key: `fixture:${node.kind}:${node.seq}`,
+    kind,
+    id: String(node.seq),
+    target: 'chat',
+    anchorSeq: node.seq,
+    location: { kind: 'session' },
+    visibility: 'visible',
+    data: node.kind === 'model-retry' ? { attempts: [node], current: node } : node,
+  }
+  const props = { node: viewNode, t: translate } as ChatNodeViewProps
+  switch (node.kind) {
+    case 'user':
+    case 'steering':
+      return <UserMessageNodeView {...props as ChatNodeViewProps<'user' | 'steering'>} />
+    case 'context':
+      return <ContextMessageNodeView {...props as ChatNodeViewProps<'context'>} />
+    case 'compaction':
+      return <CompactionNodeView {...props as ChatNodeViewProps<'compaction'>} />
+    case 'model-retry':
+      return <RetryNodeView {...props as ChatNodeViewProps<'model-retry'>} />
+    case 'unknown':
+      return <UnknownNodeView {...props as ChatNodeViewProps<'unknown'>} />
+    default:
+      throw new Error(`unsupported MessageItem fixture kind: ${node.kind}`)
+  }
+}
 
 describe('MessageItem arms', () => {
   it('user bubbles expose clock / copy and neither branch nor edit; copy writes the text', () => {
@@ -727,9 +772,9 @@ describe('MessageItem arms', () => {
     const view = render(
       <MessageItem
         t={t}
-        retryActive
         node={{
           kind: 'model-retry',
+          retryId: RETRY_ID,
           seq: 5,
           time: 10_000,
           retryState: 'scheduled',
@@ -761,9 +806,9 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem
         t={t}
-        retryActive
         node={{
           kind: 'model-retry',
+          retryId: RETRY_ID,
           seq: 6,
           time: 12_100,
           retryState: 'scheduled',
@@ -788,6 +833,7 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem t={t} node={{
         kind: 'model-retry',
+        retryId: RETRY_ID,
         seq: 6,
         time: 12_100,
         retryState: 'started',
@@ -809,6 +855,7 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem t={t} node={{
         kind: 'model-retry',
+        retryId: RETRY_ID,
         seq: 7,
         time: 12_100,
         retryState: 'started',
@@ -828,6 +875,7 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem t={t} node={{
         kind: 'model-retry',
+        retryId: RETRY_ID,
         seq: 8,
         time: 12_100,
         retryState: 'cancelled',
@@ -846,32 +894,6 @@ describe('MessageItem arms', () => {
     expect(view.getByRole('status').textContent).toBe('模型请求重试已取消（1/2） · 4s')
   })
 
-  it('synchronizes the countdown when an inactive retry becomes active at the one-second floor', () => {
-    vi.useFakeTimers()
-    vi.setSystemTime(10_000)
-    const node = {
-      kind: 'model-retry',
-      seq: 5,
-      time: 10_000,
-      retryState: 'scheduled',
-      turn: 1,
-      step: 0,
-      provider: 'mock',
-      mode: 'normal',
-      policyKey: 'mock-normal',
-      retry: 1,
-      maxRetries: 2,
-      delayMs: 5_000,
-      failure: { code: 'TRANSPORT', message: '连接被重置' },
-    } as const
-    const view = render(<MessageItem t={t} node={node} />)
-    expect(view.getByRole('status').textContent).toBe('等待重试模型请求（1/2） · 5s')
-
-    act(() => { vi.advanceTimersByTime(4_200) })
-    view.rerender(<MessageItem t={t} node={node} retryActive />)
-    expect(view.getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
-  })
-
 })
 
 describe('formatMessageClock', () => {
@@ -932,84 +954,13 @@ describe('small branch tails', () => {
     expect(view.getByText('one-liner')).toBeTruthy()
   })
 
-  it('finalized content messages expose copy / branch / clock; Think-only and streaming omit them', () => {
-    const writeText = vi.fn().mockResolvedValue(undefined)
-    Object.defineProperty(navigator, 'clipboard', {
-      configurable: true,
-      value: { writeText },
-    })
-    const now = new Date()
-    const time = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 14, 24).getTime()
-    const onFork = vi.fn()
-    const settled = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'text', text: 'answer body' }, { kind: 'reasoning', text: 'hidden' }]}
-        streaming={false}
-        time={time}
-        seq={3}
-        onFork={onFork}
-      />,
-    )
-    expect(settled.getByText('14:24')).toBeTruthy()
-    expect(settled.getByRole('button', { name: '复制' })).toBeTruthy()
-    expect(settled.getByRole('button', { name: '在新对话中分支' })).toBeTruthy()
-    fireEvent.click(settled.getByRole('button', { name: '复制' }))
-    expect(writeText).toHaveBeenCalledWith('answer body')
-    fireEvent.click(settled.getByRole('button', { name: '在新对话中分支' }))
-    expect(onFork).toHaveBeenCalledWith(3)
-    settled.unmount()
-
-    const thinkOnly = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'only thinking' }]}
-        streaming={false}
-        time={time}
-      />,
-    )
-    expect(thinkOnly.queryByRole('button', { name: '复制' })).toBeNull()
-    expect(thinkOnly.queryByText('14:24')).toBeNull()
-    thinkOnly.unmount()
-
-    const streaming = render(
-      <AssistantMarkdown t={t} blocks={[{ kind: 'text', text: 'partial' }]} streaming time={time} />,
-    )
-    expect(streaming.queryByRole('button', { name: '复制' })).toBeNull()
-    expect(streaming.queryByText('14:24')).toBeNull()
-  })
-
-  it('keeps an unavailable branch focusable and explains why without sending a fork', () => {
-    const onFork = vi.fn()
-    render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'text', text: 'answer before a trailing tool row' }]}
-        streaming={false}
-        time={1_000}
-        seq={1}
-        onFork={onFork}
-        forkUnavailable
-      />,
-    )
-    const branch = screen.getByRole('button', { name: '在新对话中分支' }) as HTMLButtonElement
-    expect(branch.disabled).toBe(false)
-    expect(branch.getAttribute('aria-disabled')).toBe('true')
-    const reasonId = branch.getAttribute('aria-describedby')
-    expect(reasonId).not.toBeNull()
-    expect(document.getElementById(reasonId!)?.textContent).toBe('仅可从已完成轮次的最后一条消息分支')
-    fireEvent.click(branch)
-    expect(onFork).not.toHaveBeenCalled()
-    fireEvent.focus(branch)
-    expect(screen.getByRole('tooltip').textContent).toBe('仅可从已完成轮次的最后一条消息分支')
-  })
-
   it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
     // Cache hit is null only when all three prompt buckets are zero (pure
     // output accounting) — any billed input makes it a real 0%.
-    const snap = {
-      nodes: [{ kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 } }],
-    }
+    const nodes = [{
+      kind: 'assistant', seq: 1, time: 1_000, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 },
+    }] as const
+    const snap = { chat: chatSnapshotFixture({ nodes }), nodes }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
       <StatsLine
diff --git a/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
new file mode 100644
index 0000000000..c675554ea0
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
@@ -0,0 +1,295 @@
+import type {
+  AssistantMessageNode, ChatConversationViewNode, ChatSnapshot, ConversationNode,
+  ChatLocationNodeIndex, ChatNodeStore, CompactionSummaryNode, ConversationLocationDataStore,
+  ConversationTurnDataMap, LegacyConversationSlice, PartialAssistant, RunningToolCall,
+  ToolCallBlock, TurnLocation,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { deriveTurnMetrics } from '../src/client/chat/turn-metrics.ts'
+
+const EMPTY: readonly never[] = []
+
+function sameValues<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function nodeSource(node: ChatConversationViewNode): unknown {
+  if (node.kind === 'assistant-step') {
+    const data = node.data as ReturnType<typeof assistantData>
+    return data.finalNode ?? data.blocks
+  }
+  if (node.kind === 'tool-call') return (node.data as { readonly root: ToolCallBlock }).root
+  if (node.kind === 'model-retry') return (node.data as { readonly current: unknown }).current
+  if (node.kind === 'turn-tail') return (node.data as { readonly seq: number }).seq
+  return node.data
+}
+
+class FixtureNodeStore implements ChatNodeStore {
+  private byKey = new Map<string, ChatConversationViewNode>()
+  private list: readonly ChatConversationViewNode[] = EMPTY
+
+  get(key: string): ChatConversationViewNode | undefined {
+    return this.byKey.get(key)
+  }
+
+  values(): readonly ChatConversationViewNode[] {
+    return this.list
+  }
+
+  replace(candidates: readonly ChatConversationViewNode[]): void {
+    const next = new Map<string, ChatConversationViewNode>()
+    const list = candidates.map((candidate) => {
+      const previous = this.byKey.get(candidate.key)
+      const node = previous !== undefined
+        && previous.kind === candidate.kind
+        && previous.anchorSeq === candidate.anchorSeq
+        && previous.visibility === candidate.visibility
+        && nodeSource(previous) === nodeSource(candidate)
+        ? previous
+        : candidate
+      next.set(node.key, node)
+      return node
+    })
+    this.byKey = next
+    this.list = sameValues(this.list, list) ? this.list : list
+  }
+}
+
+class FixtureLocationIndex implements ChatLocationNodeIndex {
+  private turns = new Map<number, readonly string[]>()
+
+  getTurn(turn: number): readonly string[] {
+    return this.turns.get(turn) ?? EMPTY
+  }
+
+  getStep(): readonly string[] {
+    return EMPTY
+  }
+
+  replace(next: ReadonlyMap<number, readonly string[]>): void {
+    const stable = new Map<number, readonly string[]>()
+    for (const [turn, keys] of next) {
+      const previous = this.turns.get(turn) ?? EMPTY
+      stable.set(turn, sameValues(previous, keys) ? previous : keys)
+    }
+    this.turns = stable
+  }
+}
+
+class FixtureTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
+  private readonly values = new Map<string, unknown>()
+
+  get<Key extends keyof ConversationTurnDataMap & string>(
+    key: Key,
+  ): Readonly<ConversationTurnDataMap[Key]> | undefined {
+    return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
+  }
+
+  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+    this.values.set(key, value)
+  }
+}
+
+function assistantData(node: AssistantMessageNode) {
+  return {
+    status: node.interrupted === true ? 'interrupted' as const : 'settled' as const,
+    turn: node.turn,
+    step: node.step,
+    blocks: node.blocks,
+    time: node.time,
+    finalNode: node,
+  }
+}
+
+function settledNode(
+  node: ConversationNode,
+  turns: ReadonlyMap<number, TurnLocation>,
+): ChatConversationViewNode {
+  const turn = 'turn' in node && typeof node.turn === 'number' ? turns.get(node.turn) : undefined
+  const base = {
+    key: `fixture:${node.kind}:${node.seq}`,
+    id: String(node.seq),
+    target: 'chat' as const,
+    anchorSeq: node.seq,
+    location: turn === undefined
+      ? { kind: 'session' as const }
+      : { kind: 'turn' as const, turn },
+    visibility: 'visible' as const,
+  }
+  switch (node.kind) {
+    case 'assistant':
+      return { ...base, kind: 'assistant-step', data: assistantData(node) }
+    case 'tool-result':
+      return { ...base, key: `fixture:tool:${node.callId}`, kind: 'tool-call', data: { root: node } }
+    case 'model-retry':
+      return { ...base, key: 'fixture:model-retry', kind: 'model-retry', data: { attempts: [node], current: node } }
+    default:
+      return { ...base, kind: node.kind, data: node }
+  }
+}
+
+/** Build the canonical Chat fixture corresponding to one legacy test slice. */
+export function chatSnapshotFixture(input: {
+  readonly nodes?: readonly ConversationNode[]
+  readonly partial?: PartialAssistant | null
+  readonly runningCalls?: readonly RunningToolCall[]
+  readonly turnTimings?: LegacyConversationSlice['turnTimings']
+  readonly turnEnds?: LegacyConversationSlice['turnEnds']
+} = {}, previous?: ChatSnapshot): ChatSnapshot {
+  const legacy: LegacyConversationSlice = {
+    nodes: input.nodes ?? EMPTY,
+    partial: input.partial ?? null,
+    runningCalls: input.runningCalls ?? EMPTY,
+    turnTimings: input.turnTimings ?? new Map(),
+    turnEnds: input.turnEnds ?? new Map(),
+  }
+  const turnNumbers = new Set([...legacy.turnTimings.keys(), ...legacy.turnEnds.keys()])
+  for (const node of legacy.nodes) {
+    if ('turn' in node && typeof node.turn === 'number') turnNumbers.add(node.turn)
+  }
+  if (legacy.partial !== null) turnNumbers.add(legacy.partial.turn)
+  for (const call of legacy.runningCalls) turnNumbers.add(call.turn)
+  const turns = new Map<number, TurnLocation>()
+  const turnData = new Map<number, FixtureTurnDataStore>()
+  for (const turn of [...turnNumbers].sort((left, right) => left - right)) {
+    const timing = legacy.turnTimings.get(turn)
+    const endSeq = legacy.turnEnds.get(turn)
+    const data = new FixtureTurnDataStore()
+    turnData.set(turn, data)
+    turns.set(turn, {
+      turn,
+      start: timing === undefined ? undefined : {
+        type: 'turn/start', seq: Math.max(0, (endSeq ?? 1) - 1), time: timing.startTime, turn,
+      } as never,
+      end: timing?.endTime === undefined || endSeq === undefined ? undefined : {
+        type: 'turn/end', seq: endSeq, time: timing.endTime, turn, reason: 'completed',
+      } as never,
+      status: endSeq === undefined ? 'open' : 'closed',
+      steps: EMPTY,
+      data,
+    })
+  }
+  const linkedCompactions = new Set<CompactionSummaryNode>()
+  const nodes = legacy.nodes.flatMap((node): ChatConversationViewNode[] => {
+    if (node.kind === 'command' && node.name === 'compact') {
+      const sourceSeq = node.outcome?.kind === 'success' ? node.outcome.sourceEventSeq : undefined
+      const candidates = sourceSeq === undefined
+        ? []
+        : legacy.nodes.filter((candidate): candidate is CompactionSummaryNode =>
+          candidate.kind === 'compaction' && candidate.summaryEventSeq === sourceSeq)
+      const compaction = candidates.length === 1 ? candidates[0] : undefined
+      if (node.outcome === null || compaction !== undefined) {
+        if (compaction !== undefined) linkedCompactions.add(compaction)
+        const base = settledNode(node, turns)
+        return [{
+          ...base,
+          key: `fixture:manual-compaction:${node.commandId}`,
+          kind: 'manual-compaction',
+          anchorSeq: compaction?.seq ?? node.seq,
+          data: { command: node, compaction: compaction ?? null },
+        }]
+      }
+    }
+    if (node.kind === 'compaction' && linkedCompactions.has(node)) return []
+    return [settledNode(node, turns)]
+  })
+  if (legacy.partial !== null) {
+    const turn = turns.get(legacy.partial.turn)
+    nodes.push({
+      key: `fixture:assistant:${legacy.partial.turn}:${legacy.partial.step}`,
+      id: `${legacy.partial.turn}:${legacy.partial.step}`,
+      target: 'chat',
+      kind: 'assistant-step',
+      anchorSeq: Number.MAX_SAFE_INTEGER - 1,
+      location: turn === undefined ? { kind: 'session' } : { kind: 'turn', turn },
+      visibility: 'visible',
+      data: {
+        status: 'running',
+        turn: legacy.partial.turn,
+        step: legacy.partial.step,
+        blocks: legacy.partial.blocks,
+        time: 0,
+      },
+    })
+  }
+  for (const call of legacy.runningCalls) {
+    const turn = turns.get(call.turn)
+    nodes.push({
+      key: `fixture:tool:${call.callId}`,
+      id: call.callId,
+      target: 'chat',
+      kind: 'tool-call',
+      anchorSeq: Number.MAX_SAFE_INTEGER,
+      location: turn === undefined ? { kind: 'session' } : { kind: 'turn', turn },
+      visibility: 'visible',
+      data: { root: call },
+    })
+  }
+  for (const [turnNumber, endSeq] of legacy.turnEnds) {
+    const turn = turns.get(turnNumber)
+    const dataStore = turnData.get(turnNumber)
+    if (turn === undefined || dataStore === undefined) continue
+    const closing = legacy.nodes
+      .filter((candidate): candidate is AssistantMessageNode => candidate.kind === 'assistant'
+        && candidate.turn === turnNumber
+        && candidate.blocks.some(block => block.kind === 'text' && block.text.trim() !== ''))
+      .map(assistantData)
+      .at(-1) ?? null
+    const preceding = nodes.findLast((candidate) => {
+      const location = candidate.location
+      return (location.kind === 'turn' || location.kind === 'step')
+        && location.turn.turn === turnNumber
+    })
+    const metrics = deriveTurnMetrics(legacy.nodes).get(turnNumber)
+    const tailData = {
+      turn: turnNumber,
+      seq: endSeq,
+      time: turn.end?.time ?? 0,
+      closing,
+      branchUnavailable: closing === null
+        || preceding?.kind !== 'assistant-step'
+        || (preceding.data as ReturnType<typeof assistantData>).finalNode.seq !== closing.finalNode.seq,
+      ...metrics?.ttftMs === undefined ? {} : { ttftMs: metrics.ttftMs },
+      ...metrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: metrics.tokensPerSecond },
+    }
+    dataStore.set('turn-tail', tailData)
+    nodes.push({
+      key: `fixture:turn-tail:${turnNumber}`,
+      id: String(turnNumber),
+      target: 'chat',
+      kind: 'turn-tail',
+      anchorSeq: endSeq,
+      location: { kind: 'turn', turn },
+      visibility: 'visible',
+      data: tailData,
+    })
+  }
+  const store = previous?.nodes instanceof FixtureNodeStore ? previous.nodes : new FixtureNodeStore()
+  store.replace(nodes)
+  const byKey = new Map(store.values().map(node => [node.key, node]))
+  const nextOrder = nodes.map(node => node.key)
+  const order = previous !== undefined && sameValues(previous.order, nextOrder) ? previous.order : nextOrder
+  const byTurn = new Map<number, readonly string[]>()
+  for (const turn of turns.keys()) {
+    byTurn.set(turn, order.filter((key) => {
+      const location = byKey.get(key)?.location
+      return location?.kind === 'turn' && location.turn.turn === turn
+        || location?.kind === 'step' && location.turn.turn === turn
+    }))
+  }
+  const locations = previous?.locations instanceof FixtureLocationIndex
+    ? previous.locations
+    : new FixtureLocationIndex()
+  locations.replace(byTurn)
+  const timeline = previous !== undefined
+    && previous.legacy.turnTimings === legacy.turnTimings
+    && previous.legacy.turnEnds === legacy.turnEnds
+    ? previous.timeline
+    : { turnOrder: [...turns.keys()], turns }
+  return {
+    order,
+    nodes: store,
+    locations,
+    timeline,
+    legacy,
+  }
+}
diff --git a/packages/client/ui-conversation/tests/chat-stats.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
index 78fbf43c5e..959a91c3ac 100644
--- a/packages/client/ui-conversation/tests/chat-stats.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
@@ -13,6 +13,7 @@ import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { StatsLine, contextOccupancy, deriveStats, formatDuration, formatTokens, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 import { en, zh } from '../src/client/locales.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: StatsLineProps['t'] = makeTranslate(zh, commonZh)
@@ -42,18 +43,39 @@ const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessage
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: chatSnapshotFixture(),
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
 }
 
 function makeSource(init?: Partial<ConversationSnapshot>) {
-  let snap: ConversationSnapshot = { ...snapshotBase(), ...init }
+  const initial = { ...snapshotBase(), ...init }
+  let snap: ConversationSnapshot = {
+    ...initial,
+    chat: init?.chat ?? chatSnapshotFixture({
+      nodes: initial.nodes,
+      partial: initial.partial,
+      runningCalls: initial.runningCalls,
+      turnTimings: initial.turnTimings,
+      turnEnds: initial.turnEnds,
+    }),
+  }
   const subs = new Set<() => void>()
   return {
     set: (next: Partial<ConversationSnapshot>) => {
-      snap = { ...snap, ...next }
+      const merged = { ...snap, ...next }
+      snap = {
+        ...merged,
+        chat: next.chat ?? (next.nodes === undefined ? snap.chat : chatSnapshotFixture({
+          nodes: merged.nodes,
+          partial: merged.partial,
+          runningCalls: merged.runningCalls,
+          turnTimings: merged.turnTimings,
+          turnEnds: merged.turnEnds,
+        })),
+      }
       for (const fn of [...subs]) fn()
     },
     source: {
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 9bb043df15..296dd85966 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -4,24 +4,33 @@
 // ObservableSnapshot fake, no wire or Tool presentation plugin.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { Profiler } from 'react'
 import { act, cleanup, fireEvent, render, within } from '@testing-library/react'
+import { useEffect } from 'react'
 import type {
   AssistantMessageNode, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot,
-  ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode,
+  ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolCallBlock, ToolResultNode, TurnErrorNode,
   UserMessageNode, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore, PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
-import type { ChatViewSlotProps, SelectionTarget, ToolTreeOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {
+  ChatNode, ChatNodeOwnerProps, ChatNodeViewProps, ChatViewSlotProps, SelectionTarget, UseChatNodeTurnData,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { zh } from '../src/client/locales.ts'
-import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, flowKeys, runningTurnStartTime } from '../src/client/chat/chat-flow.ts'
+import { AssistantNodeView } from '../src/client/chat/AssistantNodeView.tsx'
+import { CommandNodeView, ManualCompactionNodeView } from '../src/client/chat/CommandNodeView.tsx'
+import {
+  CompactionNodeView, ContextMessageNodeView, RetryNodeView, TurnErrorNodeView,
+  UnknownNodeView, UserMessageNodeView,
+} from '../src/client/chat/MessageItem.tsx'
+import { TurnTailNodeView } from '../src/client/chat/TurnTailNodeView.tsx'
 import { formatRunDuration } from '../src/client/chat/message-chrome.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 afterEach(() => {
   cleanup()
@@ -34,10 +43,11 @@ beforeEach(() => {
 })
 
 const SID = 's1' as SessionId
+type RoutedChatNodeOwner = ChatNodeOwnerProps & { readonly node: ChatNode }
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: chatSnapshotFixture(), nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -45,11 +55,21 @@ function snapshotBase(): ConversationSnapshot {
 
 /** Scripted snapshot source: set() swaps the top-level object like the real Session. */
 function makeSource(init?: Partial<ConversationSnapshot>) {
-  let snap: ConversationSnapshot = { ...snapshotBase(), ...init }
+  const initial = { ...snapshotBase(), ...init }
+  let snap: ConversationSnapshot = {
+    ...initial,
+    chat: init?.chat ?? chatSnapshotFixture(initial),
+  }
   const subs = new Set<() => void>()
   return {
     set: (next: Partial<ConversationSnapshot>) => {
-      snap = { ...snap, ...next }
+      const merged = { ...snap, ...next }
+      snap = {
+        ...merged,
+        chat: Object.hasOwn(next, 'chat') && next.chat !== undefined
+          ? next.chat
+          : chatSnapshotFixture(merged, snap.chat),
+      }
       for (const fn of [...subs]) fn()
     },
     source: {
@@ -73,7 +93,8 @@ const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode =>
   kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
 })
 const retry = (seq: number): ModelRetryNode => ({
-  kind: 'model-retry', seq, time: seq * 1_000, turn: 1, step: 0,
+  kind: 'model-retry', retryId: 'chat-view-retry' as ModelRetryNode['retryId'],
+  seq, time: seq * 1_000, turn: 1, step: 0,
   retryState: 'scheduled',
   provider: 'mock', mode: 'normal', policyKey: 'mock-normal',
   retry: 1, maxRetries: 2, delayMs: 450,
@@ -139,25 +160,97 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   // production; the view reads it through the PropsStore useStore share).
   const chat = createChatStore().create()
   const t = makeTranslate(zh, commonZh)
-  const toolOwners: ToolTreeOwnerProps[] = []
-  const renderSlot = ((key: string, owner: object, opts?: { fallback?: React.ReactNode }) => {
-    if (key !== 'conversation.chat.tool') return opts?.fallback ?? null
-    const tool = owner as ToolTreeOwnerProps
-    toolOwners.push(tool)
-    // Tool providers own their subtree. The host double carries only the
-    // semantic anchor required by ChatView's prepend-position contract.
-    return (
-      <div
-        data-testid={`tool-seat-${tool.callId}`}
-        data-chat-anchor-key={`call:${tool.callId}`}
-        data-chat-call-id={tool.callId}
-      >
-        {tool.toolName || '(unnamed)'}:{tool.callId}
-      </div>
+  const toolOwners: Array<{
+    callId: string
+    toolName: string
+    block: ToolCallBlock
+    selectedCallId: string | undefined
+    openFile: ChatNodeOwnerProps['openFile']
+    inspectCall: ChatNodeOwnerProps['inspectCall']
+  }> = []
+  const renderCommandSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
+    opts?.fallback ?? null) as unknown as React.ComponentProps<typeof CommandNodeView>['renderSlot']
+  const renderTurnTail = ((_key: string, _owner: object) => null) as unknown as
+    React.ComponentProps<typeof TurnTailNodeView>['renderSlotChain']
+  const renderTurnTailSlot = (() => null) as unknown as
+    React.ComponentProps<typeof TurnTailNodeView>['renderSlot']
+  const renderSlot = ((key: string, owner: object, opts?: {
+    fallback?: React.ReactNode
+    hookContext?: unknown
+  }) => {
+    if (key !== 'conversation.chat.node') return opts?.fallback ?? null
+    const nodeOwner = owner as RoutedChatNodeOwner
+    const nodeKey = opts?.hookContext as string | undefined
+    const useTurnData = ((dataKey: string) => props.useSession((snapshot) => {
+      const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
+      return location?.kind === 'turn' || location?.kind === 'step'
+        ? location.turn.data.get(dataKey as never)
+        : undefined
+    })) as UseChatNodeTurnData
+    const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
+      { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
+    switch (nodeOwner.node.kind) {
+      case 'user':
+      case 'steering':
+        return <UserMessageNodeView {...nodeProps<'user' | 'steering'>()} />
+      case 'context':
+        return <ContextMessageNodeView {...nodeProps<'context'>()} />
+      case 'assistant-step':
+        return <AssistantNodeView {...nodeProps<'assistant-step'>()} />
+      case 'command':
+        return (
+          <CommandNodeView
+            {...nodeProps<'command'>()}
+            renderSlot={renderCommandSlot}
+            SessionProvider={props.SessionProvider}
+          />
+        )
+      case 'manual-compaction':
+        return <ManualCompactionNodeView {...nodeProps<'manual-compaction'>()} />
+      case 'compaction':
+        return <CompactionNodeView {...nodeProps<'compaction'>()} />
+      case 'model-retry':
+        return <RetryNodeView {...nodeProps<'model-retry'>()} />
+      case 'turn-error':
+        return <TurnErrorNodeView {...nodeProps<'turn-error'>()} />
+      case 'turn-tail':
+        return (
+          <TurnTailNodeView
+            {...nodeProps<'turn-tail'>()}
+            renderSlot={renderTurnTailSlot}
+            renderSlotChain={renderTurnTail}
+            SessionProvider={props.SessionProvider}
+          />
+        )
+      case 'unknown':
+        return <UnknownNodeView {...nodeProps<'unknown'>()} />
+      case 'tool-call': {
+        const block = (nodeOwner.node.data as { readonly root: ToolCallBlock }).root
+        const toolName = 'kind' in block ? block.call?.name ?? '' : block.name
+        const tool = {
+          callId: block.callId,
+          toolName,
+          block,
+          selectedCallId: nodeOwner.selectedCallId,
+          openFile: nodeOwner.openFile,
+          inspectCall: nodeOwner.inspectCall,
+        }
+        toolOwners.push(tool)
+        return (
+          <div
+            data-testid={`tool-seat-${tool.callId}`}
+            data-chat-anchor-key={`call:${tool.callId}`}
+            data-chat-call-id={tool.callId}
+          >
+            {tool.toolName || '(unnamed)'}:{tool.callId}
+          </div>
+        )
+      }
+      default:
+        return opts?.fallback ?? null
+    }
   }) as unknown as ChatViewSlotProps['renderSlot']
-  const renderSlotChain = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
-    opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlotChain']
   // SessionProvider seat arrives with the session-scope child declaration;
   // ChatView never invokes it (render-prop pass-through stub).
   const SessionProviderStub: ChatViewSlotProps['SessionProvider'] = ({ children }) => <>{children(SID)}</>
@@ -172,7 +265,6 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     useStore: bindSnapshotSelector(chat),
     actions: chat.actions,
     renderSlot,
-    renderSlotChain,
     SessionProvider: SessionProviderStub,
     openDetails,
     openFile,
@@ -218,139 +310,7 @@ function installScrollMetrics(element: HTMLElement, initialHeight: number, clien
   }
 }
 
-describe('chat-flow derivation', () => {
-  it('groups consecutive tool results and keeps stable keys', () => {
-    const nodes: ConversationNode[] = [
-      user(1, 'hi'), assistant(2, 'let me look'), toolResult(3, 'a'), toolResult(4, 'b'),
-      assistant(5, 'found'), toolResult(6, 'c'),
-    ]
-    const items = deriveChatFlow(nodes)
-    expect(items.map(i => i.kind)).toEqual(['node', 'node', 'tool-group', 'node', 'tool-group'])
-    const group = items[2]!
-    expect(group.kind === 'tool-group' && group.results.map(r => r.callId)).toEqual(['a', 'b'])
-    expect(flowKeys(items)).toBe('n1|n2|g3|n5|g6')
-    expect(flowKeys(deriveChatFlow([...nodes, toolResult(7, 'd')]))).toBe('n1|n2|g3|n5|g6')
-  })
-
-  it('reuses one stable row for consecutive retry turns', () => {
-    const first = retry(2)
-    const second = { ...retry(3), turn: 2, retry: 2 }
-    const initial = deriveChatFlow([user(1, 'try'), first])
-    const updated = deriveChatFlow([user(1, 'try'), first, second])
-    expect(flowKeys(initial)).toBe('n1|n2')
-    expect(flowKeys(updated)).toBe('n1|n2')
-    expect(updated).toHaveLength(2)
-    expect(updated[1]?.kind === 'node' && updated[1].node).toBe(second)
-  })
-
-  it('folds a successful /compact lifecycle into its explicitly linked checkpoint', () => {
-    const running = command({
-      seq: 1,
-      commandId: 'cmd-compact' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: null,
-    })
-    expect(flowKeys(deriveChatFlow([user(0, 'before'), running]))).toBe('n0|ccmd-compact')
-
-    const settled = {
-      ...running,
-      outcome: { kind: 'success' as const, text: 'Compacted 16 history items.', sourceEventSeq: 3 },
-    }
-    const checkpoint = compaction({ seq: 4, summaryEventSeq: 3 })
-    const items = deriveChatFlow([user(0, 'before'), settled, user(2, 'injected while compacting'), checkpoint])
-    expect(flowKeys(items)).toBe('n0|n2|ccmd-compact')
-    expect(items.at(-1)).toEqual({
-      kind: 'command-compaction',
-      key: 'ccmd-compact',
-      command: settled,
-      compaction: checkpoint,
-    })
-  })
-
-  it('does not split adjacent tool results around a folded /compact command', () => {
-    const folded = command({
-      seq: 2,
-      commandId: 'cmd-compact' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 4 },
-    })
-    const items = deriveChatFlow([
-      toolResult(1, 'a'),
-      folded,
-      toolResult(3, 'b'),
-      compaction({ seq: 5, summaryEventSeq: 4 }),
-    ])
-    expect(flowKeys(items)).toBe('g1|ccmd-compact')
-    expect(
-      items[0]?.kind === 'tool-group' && items[0].results.map(result => result.callId),
-    ).toEqual(['a', 'b'])
-  })
-
-  it('keeps automatic, unlinked, and ambiguously linked compactions as separate rows', () => {
-    const automatic = compaction({ seq: 2, summaryEventSeq: 1 })
-    expect(flowKeys(deriveChatFlow([automatic]))).toBe('n2')
-
-    const first = command({
-      seq: 3,
-      commandId: 'cmd-a' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 9 },
-    })
-    const second = command({
-      seq: 4,
-      commandId: 'cmd-b' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 9 },
-    })
-    const ambiguous = compaction({ seq: 10, summaryEventSeq: 9 })
-    expect(flowKeys(deriveChatFlow([first, second, ambiguous]))).toBe('ccmd-a|ccmd-b|n10')
-
-    const sole = command({
-      seq: 11,
-      commandId: 'cmd-sole' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 12 },
-    })
-    const duplicateA = compaction({ seq: 13, summaryEventSeq: 12 })
-    const duplicateB = compaction({ seq: 14, summaryEventSeq: 12 })
-    expect(flowKeys(deriveChatFlow([sole, duplicateA, duplicateB]))).toBe('ccmd-sole|n13|n14')
-  })
-
-  it('skips render-nothing assistant nodes so tool runs stay one group', () => {
-    // A tool-call-only step message (and blank text/reasoning) renders nothing:
-    // it must not split the run into two groups with an empty line between.
-    const headsOnly: AssistantMessageNode = {
-      kind: 'assistant', seq: 4, time: 4_000, turn: 1, step: 2,
-      blocks: [{ kind: 'tool-call', callId: 'b', name: 'read', argsRaw: '{}' }, { kind: 'text', text: ' \n' }, { kind: 'reasoning', text: '' }],
-    }
-    const items = deriveChatFlow([toolResult(3, 'a'), headsOnly, toolResult(5, 'b')])
-    expect(flowKeys(items)).toBe('g3')
-    const group = items[0]!
-    expect(group.kind === 'tool-group' && group.results.map(r => r.callId)).toEqual(['a', 'b'])
-    // Interrupted and visible-content nodes still render (已停止 marker / prose).
-    expect(flowKeys(deriveChatFlow([toolResult(3, 'a'), { ...headsOnly, interrupted: true }, toolResult(5, 'b')]))).toBe('g3|n4|g5')
-    expect(flowKeys(deriveChatFlow([toolResult(3, 'a'), assistant(4, 'found'), toolResult(5, 'b')]))).toBe('g3|n4|g5')
-  })
-
-  it('assistantActionsSeqs keeps only the last content assistant per completed turn', () => {
-    const thinkOnly: AssistantMessageNode = {
-      kind: 'assistant', seq: 3, time: 3_000, turn: 1, step: 2,
-      blocks: [{ kind: 'reasoning', text: 'planning' }],
-    }
-    const nodes: ConversationNode[] = [
-      user(1, 'hi'),
-      assistant(2, 'looking', 1),
-      thinkOnly,
-      toolResult(4, 'a'),
-      assistant(5, 'done', 1),
-      user(6, 'again'),
-      assistant(7, 'second turn', 2),
-    ]
-    expect([...assistantActionsSeqs(nodes, new Map([[1, 5], [2, 7]]))].sort((a, b) => a - b)).toEqual([5, 7])
-    // Turn 2 is still producing steps: its latest narration owns nothing, and
-    // the settled turn 1 keeps its seat.
-    expect([...assistantActionsSeqs(nodes, new Map([[1, 5]]))]).toEqual([5])
-  })
+describe('Chat node rendering', () => {
 
   it('threads the injected file-mention vocabulary into the closing prose only', () => {
     const wrote = (seq: number, callId: string, path: string): ToolResultNode => ({
@@ -391,17 +351,6 @@ describe('chat-flow derivation', () => {
     expect(h.openFile).toHaveBeenCalledWith('for-seq-4/site/report.html')
   })
 
-  it('runningTurnStartTime selects the latest turn/start without a turn/end', () => {
-    expect(runningTurnStartTime(new Map([
-      [1, { startTime: 1_000, endTime: 5_000 }],
-      [2, { startTime: 6_000 }],
-    ]))).toBe(6_000)
-    expect(runningTurnStartTime(new Map([
-      [1, { startTime: 1_000, endTime: 5_000 }],
-      [2, { startTime: 6_000, endTime: 9_000 }],
-    ]))).toBeNull()
-  })
-
   it('formatRunDuration localizes units and floors partial seconds', () => {
     const t = makeTranslate(zh, commonZh)
     expect(formatRunDuration(0, t)).toBe('0秒')
@@ -410,24 +359,6 @@ describe('chat-flow derivation', () => {
     expect(formatRunDuration(125_000, t)).toBe('2分05秒')
   })
 
-  it('assistantBranchSeqs keeps only content-assistant tails; user/steering tails own no branch', () => {
-    const interruptedThink: AssistantMessageNode = {
-      kind: 'assistant', seq: 4.1, time: 4_100, turn: 1, step: 2,
-      blocks: [{ kind: 'reasoning', text: 'bad path' }], interrupted: true,
-    }
-    const nodes: ConversationNode[] = [
-      user(1, 'first'),
-      assistant(2, 'answer before tools'),
-      toolResult(3, 'a'),
-      interruptedThink,
-      user(6, 'second'),
-      assistant(7, 'clean tail', 2),
-      user(10, 'user-only tail'),
-      user(13, 'steering tail'),
-    ]
-    const seqs = assistantBranchSeqs(nodes, new Map([[1, 5], [2, 8], [3, 11], [4, 14]]))
-    expect([...seqs]).toEqual([7])
-  })
 })
 
 describe('ChatView', () => {
@@ -444,8 +375,8 @@ describe('ChatView', () => {
     const h = makeHarness({ nodes: [user(9, 'first visible'), user(10, 'next visible')], hasMore: true })
     const view = render(<h.ChatView {...h.props} />)
     const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
-    const first = view.container.querySelector('[data-chat-flow-key="n9"]') as HTMLDivElement
-    const next = view.container.querySelector('[data-chat-flow-key="n10"]') as HTMLDivElement
+    const first = view.container.querySelector('[data-chat-flow-key="fixture:user:9"]') as HTMLDivElement
+    const next = view.container.querySelector('[data-chat-flow-key="fixture:user:10"]') as HTMLDivElement
     let firstTop = 100
     let nextTop = 300
     vi.spyOn(scroller, 'getBoundingClientRect').mockImplementation(
@@ -472,7 +403,7 @@ describe('ChatView', () => {
     expect(scroller.scrollTop).toBe(590) // latest 90 + the anchored row's 500px prepend shift
   })
 
-  it('renders the fixture main line: bubble, narration, grouped tool rows', () => {
+  it('renders the fixture main line as independently keyed business nodes', () => {
     const h = makeHarness({
       nodes: [user(1, 'do the thing'), assistant(2, 'running tools'), toolResult(3, 'a'), toolResult(4, 'b')],
     })
@@ -485,14 +416,18 @@ describe('ChatView', () => {
       key: row.getAttribute('data-chat-flow-key'),
       kind: row.getAttribute('data-chat-flow-kind'),
     }))).toEqual([
-      { key: 'n1', kind: 'user' },
-      { key: 'n2', kind: 'assistant' },
-      { key: 'g3', kind: 'tool-group' },
+      { key: 'fixture:user:1', kind: 'user' },
+      { key: 'fixture:assistant:2', kind: 'assistant-step' },
+      { key: 'fixture:tool:a', kind: 'tool-call' },
+      { key: 'fixture:tool:b', kind: 'tool-call' },
     ])
     expect([...view.container.querySelectorAll('[data-chat-call-id]')].map(row => row.getAttribute('data-chat-call-id')))
       .toEqual(['a', 'b'])
     expect([...view.container.querySelectorAll('[data-chat-anchor-key]')].map(row => row.getAttribute('data-chat-anchor-key')))
-      .toEqual(['node:1', 'node:2', 'call:a', 'call:b'])
+      .toEqual([
+        'fixture:user:1', 'fixture:assistant:2',
+        'fixture:tool:a', 'call:a', 'fixture:tool:b', 'call:b',
+      ])
   })
 
   it('renders Host-pending steering at the flow tail and hands off to the durable node', () => {
@@ -559,14 +494,13 @@ describe('ChatView', () => {
     act(() => {
       h.set({ running: false, turnEnds: new Map([[1, 3]]) })
     })
-    // The completed turn's transcript tail is the steering bubble, not the
-    // narration, so the assistant's branch action stays unavailable and the
-    // steering bubble still offers none.
+    // The Turn Tail belongs to the closed Turn, independently of a later
+    // steering bubble's placement in the Chat list.
     const branchButtons = view.getAllByRole('button', { name: '在新对话中分支' })
     expect(branchButtons).toHaveLength(1)
-    expect(branchButtons[0]!.getAttribute('aria-disabled')).toBe('true')
+    expect(branchButtons[0]!.getAttribute('aria-disabled')).toBeNull()
     fireEvent.click(branchButtons[0]!)
-    expect(h.forkAt).not.toHaveBeenCalled()
+    expect(h.forkAt).toHaveBeenCalledWith(1)
   })
 
   it('keeps a later pending occurrence visible when it reuses a durable MessageId', () => {
@@ -607,7 +541,7 @@ describe('ChatView', () => {
     expect(within(disclosure).getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
 
     act(() => {
-      h.set({ nodes: [user(1, 'try'), retryNode, nextRetry] })
+      h.set({ nodes: [user(1, 'try'), nextRetry] })
     })
     expect(within(disclosure).getAllByRole('status')).toHaveLength(1)
     expect(view.container.querySelector('details')).toBe(disclosure)
@@ -617,7 +551,6 @@ describe('ChatView', () => {
       h.set({
         nodes: [
           user(1, 'try'),
-          retryNode,
           { ...nextRetry, retryState: 'started' },
           context,
           assistant(5, 'done'),
@@ -760,7 +693,7 @@ describe('ChatView', () => {
       turnEnds: new Map([[1, 2]]),
     })
     const view = render(<h.ChatView {...h.props} />)
-    // One scope per message row; the CSS reveal keys off this attribute.
+    // The user row and the settled assistant's Turn Tail each own one clock scope.
     expect(view.container.querySelectorAll('[data-time-hover-root]')).toHaveLength(2)
   })
 
@@ -787,7 +720,7 @@ describe('ChatView', () => {
     expect(h.forkAt.mock.calls).toEqual([[2]])
   })
 
-  it('keeps branch visible but unavailable when tool and interrupted Think follow the response', () => {
+  it('keeps final content actions but disables branch when Tool and interrupted Think follow it', () => {
     const interruptedThink: AssistantMessageNode = {
       kind: 'assistant', seq: 4.1, time: 4_100, turn: 1, step: 2,
       blocks: [{ kind: 'reasoning', text: 'bad path' }], interrupted: true,
@@ -843,19 +776,13 @@ describe('ChatView', () => {
     expect(view.container.querySelectorAll('h1')).toHaveLength(2)
   })
 
-  it('streaming partial frames re-render only the tail (Profiler count)', () => {
+  it('streaming partial frames update the tail without replacing a sibling Tool row', () => {
     const h = makeHarness({
       nodes: [user(1, 'q'), assistant(2, 'old answer'), toolResult(3, 'a')],
     })
-    let renders = 0
-    const counting = (
-      <Profiler id="chat" onRender={() => { renders += 1 }}>
-        <h.ChatView {...h.props} />
-      </Profiler>
-    )
-    const view = render(counting)
-    const before = renders
-    const beforeHtml = view.container.querySelector('[class*="toolGroup"]')!.innerHTML
+    const view = render(<h.ChatView {...h.props} />)
+    const tool = view.getByTestId('tool-seat-a')
+    const beforeHtml = tool.innerHTML
     act(() => {
       h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'streaming…' }] } })
     })
@@ -863,9 +790,8 @@ describe('ChatView', () => {
       h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'streaming… more' }] } })
     })
     expect(view.getByText('streaming… more')).toBeTruthy()
-    // Each chunk commits exactly one profiler pass (the tail), never a full-tree storm.
-    expect(renders - before).toBe(2)
-    expect(view.container.querySelector('[class*="toolGroup"]')!.innerHTML).toBe(beforeHtml)
+    expect(view.getByTestId('tool-seat-a')).toBe(tool)
+    expect(tool.innerHTML).toBe(beforeHtml)
   })
 
   it('streaming leaves neighbor tool rows and history items at zero re-renders', () => {
@@ -875,8 +801,9 @@ describe('ChatView', () => {
     // Count renderSlot invocations: the memo boundary holds when CallRow does
     // not re-render, so the row's renderSlot call count freezes during chunks.
     let rowRenders = 0
-    h.props.renderSlot = ((key: string, _owner: object) => {
-      if (key !== 'conversation.chat.tool') return null
+    h.props.renderSlot = ((key: string, owner: object) => {
+      if (key !== 'conversation.chat.node'
+        || (owner as RoutedChatNodeOwner).node.kind !== 'tool-call') return null
       rowRenders += 1
       return <div data-testid="counting-row" />
     })
@@ -908,6 +835,54 @@ describe('ChatView', () => {
     expect(view.getByRole('status').textContent).toBe('Deep diving...')
   })
 
+  it('keeps the Tool renderer mounted when a running call settles into log order', () => {
+    const mounted = vi.fn()
+    const unmounted = vi.fn()
+    function StatefulToolNode({ node }: { readonly node: ChatNode<'tool-call'> }) {
+      useEffect(() => {
+        mounted()
+        return () => { unmounted() }
+      }, [])
+      const root = (node.data as { readonly root: ToolCallBlock }).root
+      return (
+        <div data-testid="stateful-tool" data-state={'kind' in root ? 'settled' : 'running'}>
+          {root.callId}
+        </div>
+      )
+    }
+
+    const h = makeHarness({
+      nodes: [user(1, 'q'), assistant(4, 'later')],
+      runningCalls: [runningCall('r1')],
+      running: true,
+    })
+    h.props.renderSlot = ((key: string, owner: object, opts?: { fallback?: React.ReactNode }) => {
+      const routed = owner as RoutedChatNodeOwner
+      return key === 'conversation.chat.node' && routed.node.kind === 'tool-call'
+        ? <StatefulToolNode node={routed.node} />
+        : opts?.fallback ?? null
+    }) as ChatViewSlotProps['renderSlot']
+    const view = render(<h.ChatView {...h.props} />)
+    const tool = view.getByTestId('stateful-tool')
+    const row = view.container.querySelector('[data-chat-flow-key="fixture:tool:r1"]')
+    expect(tool.dataset.state).toBe('running')
+    expect(mounted).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      h.set({
+        nodes: [user(1, 'q'), toolResult(3, 'r1'), assistant(4, 'later')],
+        runningCalls: [],
+        running: false,
+      })
+    })
+
+    expect(view.getByTestId('stateful-tool')).toBe(tool)
+    expect(view.container.querySelector('[data-chat-flow-key="fixture:tool:r1"]')).toBe(row)
+    expect(tool.dataset.state).toBe('settled')
+    expect(mounted).toHaveBeenCalledTimes(1)
+    expect(unmounted).not.toHaveBeenCalled()
+  })
+
   it('the running clock uses turn/start, ignores steering, and stays out of the live region', () => {
     const startTime = Date.now() - 125_000
     const trigger: UserMessageNode = { ...user(1, 'go'), time: startTime + 1 }
@@ -932,7 +907,7 @@ describe('ChatView', () => {
     expect(status.textContent).toMatch(/^Deep diving\.\.\.2分0\d秒$/)
   })
 
-  it('hands each ordered root call to the whole-Tool slot', () => {
+  it('hands each ordered root call to the keyed business-node slot', () => {
     const block = toolResult(3, 'a')
     const h = makeHarness({ nodes: [block] })
     const calls: { key: string; owner: object; entryKey?: string }[] = []
@@ -943,14 +918,14 @@ describe('ChatView', () => {
     render(<h.ChatView {...h.props} />)
     expect(calls).toHaveLength(1)
     expect(calls[0]).toMatchObject({
-      key: 'conversation.chat.tool',
-      owner: { callId: 'a', toolName: 'bash', selectedCallId: undefined },
+      key: 'conversation.chat.node',
+      owner: { node: { kind: 'tool-call' }, selectedCallId: undefined },
+      entryKey: 'tool-call',
     })
-    const owner = calls[0]?.owner as ToolTreeOwnerProps
-    expect(owner.block).toBe(block)
+    const owner = calls[0]?.owner as RoutedChatNodeOwner
+    expect((owner.node.data as { readonly root: ToolCallBlock }).root).toBe(block)
     expect(owner.openFile).toBe(h.openFile)
     expect(owner.inspectCall).toBe(h.inspectCall)
-    expect(calls[0]?.entryKey).toBeUndefined()
   })
 
   it('prepend preserves a semantic row; a trailing user node force-scrolls', () => {
@@ -960,7 +935,7 @@ describe('ChatView', () => {
     // jsdom has no layout: fake the metrics the anchor math reads.
     Object.defineProperty(scroller, 'scrollHeight', { value: 1000, writable: true })
     Object.defineProperty(scroller, 'clientHeight', { value: 400, writable: true })
-    const anchored = view.container.querySelector('[data-chat-flow-key="n5"]') as HTMLDivElement
+    const anchored = view.container.querySelector('[data-chat-flow-key="fixture:user:5"]') as HTMLDivElement
     let anchoredTop = 100
     vi.spyOn(anchored, 'getBoundingClientRect').mockImplementation(
       () => ({ top: anchoredTop, bottom: anchoredTop + 40 } as DOMRect),
@@ -977,60 +952,6 @@ describe('ChatView', () => {
     expect(scroller.scrollTop).toBe(1600)
   })
 
-  it('uses stable call identity when a prepend changes the tool-group key amid unrelated growth', () => {
-    const h = makeHarness({ nodes: [toolResult(5, 'late')], hasMore: true })
-    const view = render(<h.ChatView {...h.props} />)
-    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
-    let prepended = false
-    const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'call:late') {
-        const top = prepended ? 400 : 100
-        return { top, bottom: top + 40 } as DOMRect
-      }
-      return { top: 0, bottom: 200 } as DOMRect
-    })
-    try {
-      Object.defineProperty(scroller, 'scrollHeight', { value: 700, writable: true })
-      Object.defineProperty(scroller, 'clientHeight', { value: 200, writable: true })
-      readerScroll(scroller, 80)
-      fireEvent.click(view.getByText('加载更早'))
-      // Total height grows by 500, but only 300 belongs before the call row.
-      Object.defineProperty(scroller, 'scrollHeight', { value: 1_200, writable: true })
-      prepended = true
-      act(() => { h.set({ nodes: [toolResult(4, 'early'), toolResult(5, 'late')] }) })
-      expect(scroller.scrollTop).toBe(380)
-    } finally {
-      rect.mockRestore()
-    }
-  })
-
-  it('uses the latest retry identity when prepending an earlier retry changes the flow key', () => {
-    const h = makeHarness({ nodes: [retry(5)], hasMore: true })
-    const view = render(<h.ChatView {...h.props} />)
-    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
-    let prepended = false
-    const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'node:5') {
-        const top = prepended ? 400 : 100
-        return { top, bottom: top + 40 } as DOMRect
-      }
-      return { top: 0, bottom: 200 } as DOMRect
-    })
-    try {
-      Object.defineProperty(scroller, 'scrollHeight', { value: 700, writable: true })
-      Object.defineProperty(scroller, 'clientHeight', { value: 200, writable: true })
-      readerScroll(scroller, 80)
-      fireEvent.click(view.getByText('加载更早'))
-      Object.defineProperty(scroller, 'scrollHeight', { value: 1_200, writable: true })
-      prepended = true
-      act(() => { h.set({ nodes: [retry(4), retry(5)] }) })
-      expect(scroller.scrollTop).toBe(380)
-      expect(view.container.querySelector('[data-chat-flow-key="n4"][data-chat-anchor-key="node:5"]')).not.toBeNull()
-    } finally {
-      rect.mockRestore()
-    }
-  })
-
   it('back-to-bottom cancels an in-flight paging anchor', () => {
     const h = makeHarness({ nodes: [user(9, 'late')], hasMore: true })
     const view = render(<h.ChatView {...h.props} />)
@@ -1177,7 +1098,7 @@ describe('ChatView', () => {
       () => ({ top: 0, bottom: 500 } as DOMRect),
     )
     const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'node:1') {
+      if (this.dataset.chatAnchorKey === 'fixture:user:1') {
         return { top: anchorTop, bottom: anchorTop + 40 } as DOMRect
       }
       return { top: 0, bottom: 40 } as DOMRect
@@ -1216,12 +1137,12 @@ describe('ChatView', () => {
     })
     document.body.appendChild(host)
     const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'node:1') return { top: 300, bottom: 340 } as DOMRect
+      if (this.dataset.chatAnchorKey === 'fixture:user:1') return { top: 300, bottom: 340 } as DOMRect
       return { top: 0, bottom: 500 } as DOMRect
     })
     try {
       const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
-      h.chatScroll.save({ anchorKey: 'node:1', anchorTop: 80, scrollTop: 1_400 })
+      h.chatScroll.save({ anchorKey: 'fixture:user:1', anchorTop: 80, scrollTop: 1_400 })
       const view = render(<h.ChatView {...h.props} />, { container: host })
       expect(host.scrollTop).toBe(1_500)
       expect(h.chatScroll.read()).toBeNull()
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
new file mode 100644
index 0000000000..3ae906087e
--- /dev/null
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -0,0 +1,720 @@
+import { describe, expect, it } from 'vitest'
+import type {
+  ChatConversationViewNode, ChatSnapshot, ConversationEventInput,
+  ConversationNodeDefinition, ConversationViewDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationNodeAssembler } from '@deepseek-ai/dsh-client-runtime/client'
+import { assistantDefinition } from '../src/client/conversation-nodes/assistant.ts'
+import { chatViewDefinition } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
+import { commandDefinition } from '../src/client/conversation-nodes/command.ts'
+import { compactionDefinition } from '../src/client/conversation-nodes/compaction.ts'
+import { unknownFallbackDefinition } from '../src/client/conversation-nodes/fallback.ts'
+import { nextStepInboxDefinition, nextTurnInboxDefinition } from '../src/client/conversation-nodes/inbox.ts'
+import { messageDefinition } from '../src/client/conversation-nodes/message.ts'
+import { retryDefinition } from '../src/client/conversation-nodes/retry.ts'
+import { toolDefinition } from '../src/client/conversation-nodes/tool.ts'
+import { turnErrorDefinition } from '../src/client/conversation-nodes/turn-error.ts'
+import { turnTailDefinition } from '../src/client/conversation-nodes/turn-tail.ts'
+import type {
+  AssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData,
+} from '../src/client/contract/chat-nodes.ts'
+
+const DEFINITIONS: readonly ConversationNodeDefinition[] = [
+  nextTurnInboxDefinition,
+  nextStepInboxDefinition,
+  messageDefinition,
+  assistantDefinition,
+  toolDefinition,
+  commandDefinition,
+  compactionDefinition,
+  retryDefinition,
+  turnErrorDefinition,
+  turnTailDefinition,
+]
+
+class TestEventDefinitions {
+  entries(): readonly ConversationNodeDefinition[] {
+    return DEFINITIONS
+  }
+
+  fallbackEntry(): ConversationNodeDefinition {
+    return unknownFallbackDefinition
+  }
+}
+
+class TestViewDefinitions {
+  entries(): readonly ConversationViewDefinition[] {
+    return [chatViewDefinition]
+  }
+}
+
+function at(
+  seq: number,
+  type: string,
+  data: unknown,
+  extra: Record<string, unknown> = {},
+): ConversationEventInput {
+  return {
+    event: {
+      seq,
+      time: 1_700_000_000_000 + seq,
+      type,
+      data,
+      ...extra,
+    } as unknown as ConversationEventInput['event'],
+    view: undefined,
+  }
+}
+
+function assembler(entries: readonly ConversationEventInput[] = [], hasMore = false): ConversationNodeAssembler {
+  const value = new ConversationNodeAssembler(new TestEventDefinitions(), new TestViewDefinitions())
+  value.replaceWindow(entries, hasMore)
+  value.flush()
+  return value
+}
+
+function snapshot(value: ConversationNodeAssembler): ChatSnapshot {
+  const current = value.snapshot('chat') as ChatSnapshot | undefined
+  if (current === undefined) throw new Error('chat view was not registered')
+  return current
+}
+
+function node(value: ChatSnapshot, kind: string): ChatConversationViewNode | undefined {
+  return value.nodes.values().find(candidate => candidate.kind === kind)
+}
+
+function textMessage(id: string, text: string) {
+  return {
+    id,
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }
+}
+
+function assistantMessage(id: string, text: string) {
+  return {
+    id,
+    role: 'assistant',
+    content: [{ type: 'text', text }],
+    source: { kind: 'model', provider: 'fake', model: 'fake' },
+  }
+}
+
+function toolResult(callId: string, text: string) {
+  return {
+    id: `result-${callId}`,
+    role: 'user',
+    source: { kind: 'tool', callId },
+    content: [{
+      type: 'tool-result',
+      toolCallId: callId,
+      content: [{ type: 'text', text }],
+      isError: false,
+    }],
+  }
+}
+
+describe('built-in conversation node Definitions', () => {
+  it('keeps one keyed Assistant node while streaming settles and materializes interruption from Location', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/chunk', {
+        turn: 1,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'streaming' },
+      }),
+    ])
+    const runningSnapshot = snapshot(value)
+    const running = node(runningSnapshot, 'assistant-step')
+    expect(running?.data).toMatchObject({ status: 'running', blocks: [{ kind: 'text', text: 'streaming' }] })
+    const order = runningSnapshot.order
+
+    value.append(at(4, 'assistant/message', {
+      turn: 1,
+      step: 1,
+      message: assistantMessage('assistant-1', 'settled'),
+    }, { surfaceOp: 'append' }))
+    value.flush()
+
+    const settledSnapshot = snapshot(value)
+    const settled = node(settledSnapshot, 'assistant-step')
+    expect(settled?.key).toBe(running?.key)
+    expect(settledSnapshot.order).toBe(order)
+    expect(settled?.data).toMatchObject({ status: 'settled', blocks: [{ kind: 'text', text: 'settled' }] })
+
+    const interruptedValue = assembler([
+      at(10, 'turn/start', { turn: 2 }),
+      at(11, 'step/start', { turn: 2, step: 1 }),
+      at(12, 'assistant/chunk', {
+        turn: 2,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'partial' },
+      }),
+      at(13, 'step/end', { turn: 2, step: 1 }),
+    ])
+    const interrupted = node(snapshot(interruptedValue), 'assistant-step')
+    expect(interrupted?.data).toMatchObject({ status: 'interrupted' })
+    expect((interrupted?.data as AssistantChatData).finalNode?.interrupted).toBe(true)
+
+    const hiddenValue = assembler([
+      at(20, 'turn/start', { turn: 3 }),
+      at(21, 'step/start', { turn: 3, step: 1 }),
+      at(22, 'llm/retry', {
+        retryId: 'retry-hidden',
+        turn: 3,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'temporary' },
+      }),
+    ])
+    expect(node(snapshot(hiddenValue), 'assistant-step')).toBeUndefined()
+
+    const toolOnlyValue = assembler([
+      at(30, 'turn/start', { turn: 4 }),
+      at(31, 'step/start', { turn: 4, step: 1 }),
+      at(32, 'assistant/chunk', {
+        turn: 4,
+        step: 1,
+        chunk: { type: 'tool-call-delta', index: 0, id: 'call-1', name: 'read', argumentsDelta: '' },
+      }),
+      at(33, 'assistant/message', {
+        turn: 4,
+        step: 1,
+        message: {
+          ...assistantMessage('assistant-tool-only', ''),
+          content: [{ type: 'tool-call', id: 'call-1', name: 'read', arguments: '{}' }],
+        },
+      }, { surfaceOp: 'append' }),
+    ])
+    const toolOnlySnapshot = snapshot(toolOnlyValue)
+    expect(toolOnlySnapshot.order).toEqual([])
+    expect(node(toolOnlySnapshot, 'assistant-step')?.visibility).toBe('hidden')
+    expect(toolOnlySnapshot.legacy.nodes).toMatchObject([{
+      kind: 'assistant',
+      seq: 33,
+      timing: { firstTokenTime: 1_700_000_000_032 },
+    }])
+
+    const interruptedToolOnlyValue = assembler([
+      at(35, 'turn/start', { turn: 5 }),
+      at(36, 'step/start', { turn: 5, step: 1 }),
+      at(37, 'assistant/chunk', {
+        turn: 5,
+        step: 1,
+        chunk: { type: 'tool-call-delta', index: 0, id: 'call-2', name: 'read', argumentsDelta: '' },
+      }),
+      at(38, 'step/end', { turn: 5, step: 1 }),
+    ])
+    const interruptedToolOnly = node(snapshot(interruptedToolOnlyValue), 'assistant-step')
+    expect(interruptedToolOnly?.visibility).toBe('visible')
+    expect(interruptedToolOnly?.data).toMatchObject({ status: 'interrupted' })
+
+    const retryTimingValue = assembler([
+      at(50, 'turn/start', { turn: 6 }),
+      at(51, 'step/start', { turn: 6, step: 1 }),
+      at(52, 'assistant/chunk', {
+        turn: 6,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'first attempt' },
+      }),
+      at(53, 'llm/retry', {
+        retryId: 'retry-timing', turn: 6, step: 1, provider: 'fake', mode: 'normal',
+        policyKey: 'fake-normal', retry: 1, maxRetries: 2, delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'temporary' },
+      }),
+      at(54, 'assistant/chunk', {
+        turn: 6,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'second attempt' },
+      }),
+      at(55, 'assistant/message', {
+        turn: 6,
+        step: 1,
+        message: assistantMessage('assistant-retried', 'done'),
+      }, { surfaceOp: 'append' }),
+    ])
+    const retryTiming = (node(snapshot(retryTimingValue), 'assistant-step')?.data as AssistantChatData).finalNode
+    expect(retryTiming?.timing?.firstTokenTime).toBe(1_700_000_000_052)
+
+    const partialWindow = assembler([
+      at(40, 'assistant/chunk', {
+        turn: 5,
+        step: 2,
+        chunk: { type: 'text-delta', index: 0, text: 'loaded partial' },
+      }),
+      at(41, 'step/end', { turn: 5, step: 2 }),
+    ], true)
+    const recovered = node(snapshot(partialWindow), 'assistant-step')
+    expect(recovered?.data).toMatchObject({
+      status: 'interrupted',
+      blocks: [{ kind: 'text', text: 'loaded partial' }],
+    })
+  })
+
+  it('keeps one keyed Tool node from running through settlement and replays nested dispatch after prepend', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'tool/call', { turn: 1, step: 1, callId: 'root', name: 'code', arguments: '{}' }),
+    ])
+    const runningSnapshot = snapshot(value)
+    const running = node(runningSnapshot, 'tool-call')
+    expect((running?.data as ToolChatData).root).toMatchObject({ callId: 'root', name: 'code' })
+    const order = runningSnapshot.order
+
+    value.append(at(4, 'tool/result', {
+      turn: 1,
+      step: 1,
+      message: toolResult('root', 'done'),
+    }, { surfaceOp: 'append' }))
+    value.flush()
+
+    const settledSnapshot = snapshot(value)
+    const settled = node(settledSnapshot, 'tool-call')
+    expect(settled?.key).toBe(running?.key)
+    expect(settledSnapshot.order).toBe(order)
+    expect((settled?.data as ToolChatData).root).toMatchObject({ kind: 'tool-result', callId: 'root' })
+
+    const history = assembler([
+      at(14, 'tool/code-dispatch-start', {
+        rootCallId: 'history-root',
+        parentCallId: 'history-root',
+        subCallId: 'child',
+        name: 'read',
+        arguments: { path: 'README.md' },
+      }),
+      at(15, 'tool/code-dispatch', {
+        rootCallId: 'history-root',
+        parentCallId: 'history-root',
+        subCallId: 'child',
+        name: 'read',
+        arguments: { path: 'README.md' },
+        isError: false,
+        content: [{ type: 'text', text: 'contents' }],
+      }),
+      at(16, 'tool/result', {
+        turn: 2,
+        step: 1,
+        message: toolResult('history-root', 'root done'),
+      }, { surfaceOp: 'append' }),
+    ], true)
+    const before = node(snapshot(history), 'tool-call')
+    expect((before?.data as ToolChatData).root.subCalls).toMatchObject([
+      { kind: 'tool-result', callId: 'child', call: { name: 'read' } },
+    ])
+
+    history.prepend([
+      at(10, 'turn/start', { turn: 2 }),
+      at(11, 'step/start', { turn: 2, step: 1 }),
+      at(13, 'tool/call', {
+        turn: 2,
+        step: 1,
+        callId: 'history-root',
+        name: 'code',
+        arguments: '{}',
+      }),
+    ], false)
+    history.flush()
+
+    const after = node(snapshot(history), 'tool-call')
+    expect(after?.key).toBe(before?.key)
+    expect((after?.data as ToolChatData).root.subCalls).toMatchObject([
+      { kind: 'tool-result', callId: 'child', call: { name: 'read' } },
+    ])
+
+    const firstChild = (after?.data as ToolChatData).root.subCalls[0]
+    history.append(at(17, 'tool/code-dispatch-start', {
+      rootCallId: 'history-root',
+      parentCallId: 'history-root',
+      subCallId: 'second-child',
+      name: 'write',
+      arguments: { path: 'out.txt' },
+    }))
+    history.flush()
+    const withSecondChild = node(snapshot(history), 'tool-call')
+    expect((withSecondChild?.data as ToolChatData).root.subCalls[0]).toBe(firstChild)
+  })
+
+  it('prepends an older turn without replacing already materialized nodes', () => {
+    const value = assembler([
+      at(20, 'turn/start', { turn: 2 }),
+      at(21, 'user/message', textMessage('newer-user', 'newer'), { surfaceOp: 'append' }),
+      at(22, 'step/start', { turn: 2, step: 1 }),
+      at(23, 'assistant/message', {
+        turn: 2,
+        step: 1,
+        message: assistantMessage('newer-assistant', 'newer answer'),
+      }, { surfaceOp: 'append' }),
+      at(24, 'step/end', { turn: 2, step: 1 }),
+      at(25, 'turn/end', { turn: 2, reason: { kind: 'completed' } }),
+    ], true)
+    const before = snapshot(value)
+    const existing = before.nodes.get(before.order.find(key => before.nodes.get(key)?.kind === 'assistant-step') ?? '')
+    const store = before.nodes
+
+    value.prepend([
+      at(10, 'turn/start', { turn: 1 }),
+      at(11, 'user/message', textMessage('older-user', 'older'), { surfaceOp: 'append' }),
+      at(12, 'step/start', { turn: 1, step: 1 }),
+      at(13, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('older-assistant', 'older answer'),
+      }, { surfaceOp: 'append' }),
+      at(14, 'step/end', { turn: 1, step: 1 }),
+      at(15, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ], false)
+    value.flush()
+
+    const after = snapshot(value)
+    expect(after.nodes).toBe(store)
+    expect(after.nodes.get(existing?.key ?? '')).toBe(existing)
+    expect(after.order).toHaveLength(before.order.length + 3)
+    expect(after.order.map(key => after.nodes.get(key)?.kind)).toEqual([
+      'user', 'assistant-step', 'turn-tail',
+      'user', 'assistant-step', 'turn-tail',
+    ])
+  })
+
+  it('appends a later turn without replacing nodes from the completed turn', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'user/message', textMessage('first-user', 'first'), { surfaceOp: 'append' }),
+      at(3, 'step/start', { turn: 1, step: 1 }),
+      at(4, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('first-assistant', 'first answer'),
+      }, { surfaceOp: 'append' }),
+      at(5, 'step/end', { turn: 1, step: 1 }),
+      at(6, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+    const before = snapshot(value)
+    const oldOrder = before.order
+    const oldNodes = oldOrder.map(key => before.nodes.get(key))
+
+    value.append(at(7, 'turn/start', { turn: 2 }))
+    value.append(at(8, 'user/message', textMessage('second-user', 'second'), { surfaceOp: 'append' }))
+    value.flush()
+
+    const after = snapshot(value)
+    expect(after.nodes).toBe(before.nodes)
+    expect(after.order.slice(0, oldOrder.length)).toEqual(oldOrder)
+    expect(oldOrder.map(key => after.nodes.get(key))).toEqual(oldNodes)
+    expect(after.order.map(key => after.nodes.get(key)?.kind)).toEqual([
+      'user', 'assistant-step', 'turn-tail', 'user',
+    ])
+  })
+
+  it('replays inbox predecessors after prepend and reclassifies the dependent message as steering', () => {
+    const value = assembler([
+      at(3, 'user/message', textMessage('steer-1', 'change direction'), { surfaceOp: 'append' }),
+    ], true)
+    const before = node(snapshot(value), 'user')
+    expect(before).toBeDefined()
+
+    value.prepend([
+      at(1, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        inserted: [textMessage('steer-1', 'change direction')],
+      }),
+      at(2, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        removedCount: 1,
+        inserted: [],
+      }),
+    ], false)
+    value.flush()
+
+    const after = node(snapshot(value), 'steering')
+    expect(after?.key).toBe(before?.key)
+    expect(after?.data).toMatchObject({ kind: 'steering', messageId: 'steer-1' })
+    expect(node(snapshot(value), 'user')).toBeUndefined()
+  })
+
+  it('classifies appended producer context from durable source metadata', () => {
+    const value = assembler([
+      at(1, 'user/message', {
+        ...textMessage('skill-context', 'follow these instructions'),
+        source: { kind: 'skill-invocation', name: 'demo-skill', form: 'instructions' },
+      }, { surfaceOp: 'append' }),
+    ])
+
+    expect(node(snapshot(value), 'context')?.data).toMatchObject({
+      kind: 'context',
+      provenance: { role: 'inject', label: 'demo-skill' },
+      form: 'instructions',
+    })
+  })
+
+  it('keeps replacement copies out of Chat business nodes', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'user/message', {
+        ...textMessage('replacement-user', 'model-only context'),
+        source: { kind: 'plugin', plugin: 'foreign' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 1 } }),
+      at(4, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('replacement-assistant', 'rewritten answer'),
+      }, { surfaceOp: { op: 'replace', start: 2, end: 2 } }),
+      at(5, 'tool/call', { turn: 1, step: 1, callId: 'root', name: 'read', arguments: '{}' }),
+      at(6, 'tool/result', {
+        turn: 1,
+        step: 1,
+        message: toolResult('root', 'pruned result'),
+      }, { surfaceOp: { op: 'replace', start: 3, end: 3 } }),
+    ])
+
+    const current = snapshot(value)
+    expect(node(current, 'user')).toBeUndefined()
+    expect(node(current, 'context')).toBeUndefined()
+    expect(node(current, 'assistant-step')).toBeUndefined()
+    expect((node(current, 'tool-call')?.data as ToolChatData).root).not.toHaveProperty('kind')
+  })
+
+  it('assembles retry chains and keeps manual and automatic compaction ownership separate', () => {
+    const retry = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'llm/retry', {
+        retryId: 'retry-1',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'first' },
+      }),
+      at(4, 'llm/retry-started', { retryId: 'retry-1', turn: 1, step: 1, retry: 1 }),
+      at(5, 'llm/retry', {
+        retryId: 'retry-1',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 2,
+        maxRetries: 2,
+        delayMs: 20,
+        failure: { code: 'TRANSPORT', message: 'second' },
+      }),
+      at(6, 'step/end', { turn: 1, step: 1 }),
+      at(7, 'turn/end', {
+        turn: 1,
+        reason: { kind: 'error', error: { code: 'TRANSPORT', message: 'failed' } },
+      }),
+    ])
+    const retryNode = node(snapshot(retry), 'model-retry')
+    const retryData = retryNode?.data as RetryChatData
+    expect(retryData.attempts.map(attempt => attempt.retryState)).toEqual(['started', 'cancelled'])
+    expect(node(snapshot(retry), 'turn-error')).toBeUndefined()
+
+    const compactions = assembler([
+      at(10, 'command/run', {
+        commandId: 'command-1',
+        name: 'compact',
+        source: { kind: 'user' },
+      }),
+      at(11, 'compact/start', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        turn: null,
+      }),
+      at(12, 'compact/summary', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        summary: [{ type: 'text', text: 'manual summary' }],
+        shadowedSeqs: [1, 2],
+        shadowedTokenCount: 100,
+      }),
+      at(13, 'user/message', {
+        ...textMessage('manual-checkpoint', 'checkpoint'),
+        source: {
+          kind: 'plugin',
+          plugin: 'compact',
+          compactionId: 'manual-1',
+          sourceCommandId: 'command-1',
+        },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 2 } }),
+      at(14, 'compact/end', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        turn: null,
+      }),
+      at(15, 'command/done', {
+        commandId: 'command-1',
+        kind: 'success',
+        sourceEventSeq: 12,
+      }),
+      at(20, 'compact/start', { compactionId: 'automatic-1', turn: null }),
+      at(21, 'compact/summary', {
+        compactionId: 'automatic-1',
+        summary: [{ type: 'text', text: 'automatic summary' }],
+        shadowedSeqs: [3, 4],
+        shadowedTokenCount: 200,
+      }),
+      at(22, 'user/message', {
+        ...textMessage('automatic-checkpoint', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact', compactionId: 'automatic-1' },
+      }, { surfaceOp: { op: 'replace', start: 3, end: 4 } }),
+      at(23, 'compact/end', { compactionId: 'automatic-1', turn: null }),
+    ])
+
+    const manual = node(snapshot(compactions), 'manual-compaction')
+    expect((manual?.data as ManualCompactionChatData).compaction).toMatchObject({
+      summary: 'manual summary',
+      summaryEventSeq: 12,
+    })
+    const automatic = node(snapshot(compactions), 'compaction')
+    expect(automatic?.data).toMatchObject({ summary: 'automatic summary', summaryEventSeq: 21 })
+    expect(snapshot(compactions).nodes.values().filter(candidate => candidate.kind === 'compaction')).toHaveLength(1)
+  })
+
+  it('fills a landed compaction marker when an older page supplies its summary', () => {
+    const value = assembler([
+      at(13, 'user/message', {
+        ...textMessage('checkpoint', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact', compactionId: 'compact-1' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 8 } }),
+    ], true)
+    const before = node(snapshot(value), 'compaction')
+    expect(before?.data).toMatchObject({ summary: null, summaryEventSeq: null })
+
+    value.prepend([
+      at(9, 'compact/start', { compactionId: 'compact-1', turn: null }),
+      at(10, 'compact/summary', {
+        compactionId: 'compact-1',
+        summary: [
+          { type: 'text', text: 'older ' },
+          { type: 'image', data: 'ignored' },
+          { type: 'text', text: 'summary' },
+        ],
+        shadowedSeqs: [1, 2, 3],
+        shadowedTokenCount: 42,
+      }),
+    ], false)
+    value.flush()
+
+    const after = node(snapshot(value), 'compaction')
+    expect(after?.key).toBe(before?.key)
+    expect(after?.data).toMatchObject({
+      summary: 'older summary',
+      summaryEventSeq: 10,
+      shadowedItemCount: 3,
+      shadowedTokenCount: 42,
+    })
+  })
+
+  it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
+    const value = assembler([
+      at(5, 'llm/retry', {
+        retryId: 'retry-paged',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 2,
+        maxRetries: 2,
+        delayMs: 20,
+        failure: { code: 'TRANSPORT', message: 'second' },
+      }),
+      at(6, 'step/end', { turn: 1, step: 1 }),
+      at(7, 'turn/end', {
+        turn: 1,
+        reason: { kind: 'error', error: { code: 'TRANSPORT', message: 'failed' } },
+      }),
+    ], true)
+
+    expect(node(snapshot(value), 'model-retry')).toBeUndefined()
+    expect(node(snapshot(value), 'turn-error')).toBeUndefined()
+
+    value.prepend([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'llm/retry', {
+        retryId: 'retry-paged',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'first' },
+      }),
+      at(4, 'llm/retry-started', {
+        retryId: 'retry-paged', turn: 1, step: 1, retry: 1,
+      }),
+    ], false)
+    value.flush()
+
+    const retry = node(snapshot(value), 'model-retry')
+    expect((retry?.data as RetryChatData).attempts).toHaveLength(2)
+    expect(node(snapshot(value), 'turn-error')).toBeUndefined()
+  })
+
+  it('preserves nested Tools and manual compaction evidence when their start events are outside the window', () => {
+    const value = assembler([
+      at(12, 'tool/code-dispatch-start', {
+        rootCallId: 'root', parentCallId: 'root', subCallId: 'child', name: 'read_file', arguments: { path: 'a' },
+      }),
+      at(13, 'tool/code-dispatch', {
+        rootCallId: 'root', parentCallId: 'root', subCallId: 'child', name: 'read_file', arguments: { path: 'a' },
+        isError: false, content: [{ type: 'text', text: 'child result' }],
+      }),
+      at(14, 'tool/result', {
+        turn: 1,
+        step: 1,
+        message: toolResult('root', 'root result'),
+      }, { surfaceOp: 'append' }),
+      at(20, 'compact/summary', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        summary: [{ type: 'text', text: 'manual summary' }],
+        shadowedSeqs: [1, 2],
+        shadowedTokenCount: 100,
+      }),
+      at(21, 'user/message', {
+        ...textMessage('manual-checkpoint', 'checkpoint'),
+        source: {
+          kind: 'plugin',
+          plugin: 'compact',
+          compactionId: 'manual-1',
+          sourceCommandId: 'command-1',
+        },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 2 } }),
+      at(22, 'command/done', {
+        commandId: 'command-1',
+        kind: 'success',
+        sourceEventSeq: 20,
+      }),
+    ], true)
+
+    const tool = node(snapshot(value), 'tool-call')
+    const root = (tool?.data as ToolChatData).root
+    expect(root.subCalls).toHaveLength(1)
+    expect(root.subCalls[0]).toMatchObject({ callId: 'child', kind: 'tool-result' })
+    const manual = node(snapshot(value), 'manual-compaction')
+    expect((manual?.data as ManualCompactionChatData)).toMatchObject({
+      command: { commandId: 'command-1', name: 'compact', outcome: { kind: 'success' } },
+      compaction: { summary: 'manual summary', summaryEventSeq: 20 },
+    })
+  })
+})
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index 3afe471d50..ff3a0f1598 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -3,7 +3,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
 import type { ConversationSnapshot, SessionId, SessionListState, WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionProviderComponent } from '@deepseek-ai/dsh-client-ui-slots'
@@ -15,6 +15,7 @@ import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/ch
 import { StatsLine } from '../src/client/chat/StatsLine.tsx'
 import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
 import { zh } from '../src/client/locales.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
@@ -40,14 +41,15 @@ const SessionProviderStub: SessionProviderComponent = ({ children }) => children
 /** Observe the owner currency without importing the Tool details renderer. */
 function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotProps['renderSlot'] {
   return (_key, owner) => {
-    owners?.push(owner as DetailsToolOwnerProps)
+    owners?.push(owner as unknown as DetailsToolOwnerProps)
     return <div data-testid="tool-details-seat" />
   }
 }
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -69,11 +71,16 @@ describe('render branch tails', () => {
   it('StatsLine counts window nodes but drops every token group without a projection', () => {
     // Node `usage` is deliberately ignored: billing rides the durable
     // tokenUsage projection, so an absent projection leaves counts only.
+    const nodes = [
+      { kind: 'assistant', seq: 1, time: 1, turn: 1, step: 1, blocks: [] },
+      { kind: 'assistant', seq: 2, time: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },
+      { kind: 'assistant', seq: 3, time: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
+    ] as const
     const snap = {
+      ...snapshotBase(),
+      chat: chatSnapshotFixture({ nodes }),
       nodes: [
-        { kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [] },
-        { kind: 'assistant', seq: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },
-        { kind: 'assistant', seq: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
+        ...nodes,
       ],
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
@@ -146,6 +153,7 @@ describe('render branch tails', () => {
         }],
       }],
     }]
+    snap.chat = chatSnapshotFixture({ runningCalls: snap.runningCalls })
     const chat = createChatStore().create()
     chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
     const emptyList = createSnapshotStore<SessionListState>(
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 1e7c3a1ba1..e9076fa994 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -7,7 +7,7 @@
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { ClientContext, ConversationSnapshot, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
@@ -35,7 +35,8 @@ const SID = 's1' as SessionId
 
 function snapshotOf(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index f197528a2b..65fa5705ca 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -8,7 +8,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ClientContext, ConversationSnapshot, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SubmitOutcome } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
@@ -26,7 +26,8 @@ const SID = 's1' as SessionId
 /** Standard-props InputBar mount over a real shell (the composer-bar entry shape). */
 function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled?: boolean }) {
   const session = createSnapshotStore<ConversationSnapshot>({
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: over?.running ?? false, composerPhase: 'active',
     removed: over?.disabled ?? false, openState: 'open', openError: null, hasMore: false,
     loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index aae5bb4818..94d348d17a 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -11,7 +11,7 @@
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
-import { SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { EMPTY_CHAT_SNAPSHOT, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { ClientSessionContext, CommandClaim, PickOutcome, SubmitOutcome } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { FakeApiClient, ok } from '../../runtime/tests/fake-api.ts'
@@ -112,7 +112,8 @@ async function scopedBench(register?: (slash: SlashService) => void) {
   actx.on('slash/input-consume-token', req => shell.consumeToken(req.guard) ? true : undefined)
   const wiring = shell
   const sessionStore = createSnapshotStore<ConversationSnapshot>({
-    sessionId, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
index 826abaf846..31a6423f87 100644
--- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx
+++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
@@ -6,6 +6,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
 import { useSyncExternalStore } from 'react'
+import { EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, QueuedMessage, SessionId, SessionListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -32,7 +33,8 @@ function row(id: string, text: string | null, preview = text ?? '[image]'): Queu
 
 function snapshotWith(queue: QueuedMessage[]): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue, running: true, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index 70b6d96710..bbabbaeb0c 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -5,7 +5,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, SessionId, SessionListState, WorkspaceId, WorkspaceListState, WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -70,7 +70,8 @@ const workspaceState = (items: readonly WorkspaceView[]): WorkspaceListState =>
 
 function conversationSnapshot(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 3bcaffe605..b7ca73a79f 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -8,15 +8,22 @@
 import { Context } from 'cordis'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationEventRegistry, ConversationNodeAssembler, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  AssistantMessageNode, ConversationNode, ToolResultNode, UserMessageNode,
+  ConversationEventInput, ConversationLocationDataStore, ConversationNodeDefinition,
+  ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewDefinition,
+  ConversationViewNode, ToolResultNode, TurnLocation,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
-import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatFileMentions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
-import { basename, producedFileMentions, producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
+import {
+  basename, deliverablesDefinition, producedFileMentions, producedForClosing, selectProducedFiles,
+  type DeliverablesTurnData,
+} from '../src/client/turn-deliverables.ts'
 import { apply, inject } from '../src/client/index.ts'
 import { apply as applyNode } from '../src/index.ts'
 import { apply as applyInvariant } from '../src/invariant.ts'
@@ -24,101 +31,187 @@ import { zh } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
-const user = (seq: number, text: string): UserMessageNode => ({
-  kind: 'user',
-  seq,
-  time: seq * 1000,
-  content: [{ type: 'text', text }] as never,
-  source: null,
+class TestTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
+  private readonly values = new Map<string, unknown>()
+
+  get<Key extends keyof ConversationTurnDataMap & string>(
+    key: Key,
+  ): Readonly<ConversationTurnDataMap[Key]> | undefined {
+    return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
+  }
+
+  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+    this.values.set(key, value)
+  }
+}
+
+const turnLocation = (turn: number, deliverables?: DeliverablesTurnData): TurnLocation => {
+  const data = new TestTurnDataStore()
+  if (deliverables !== undefined) data.set('deliverables', deliverables)
+  return { turn, start: undefined, end: undefined, status: 'closed', steps: [], data }
+}
+
+const produced = (...values: ReadonlyArray<readonly [seq: number, path: string]>): DeliverablesTurnData => ({
+  produced: values.map(([seq, path]) => ({ seq, path })),
 })
-const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode => ({
-  kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
-})
-const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
-  kind: 'tool-result', seq, time: seq * 1_000, callId,
-  call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
-  callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null, subCalls: [],
-})
-const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
-  ...toolResult(seq, callId, 'write'),
-  callView: {
+
+function tailOwner(
+  data: DeliverablesTurnData | undefined,
+  seq: number,
+  openFile: (path: string) => void = () => {},
+  turn = 1,
+): TurnTailOwnerProps {
+  return { seq, openFile, turn: turnLocation(turn, data) }
+}
+
+interface TimelineSnapshot {
+  readonly timeline: ConversationTimelineSnapshot
+}
+
+class TestEventDefinitions {
+  entries(): readonly ConversationNodeDefinition[] { return [deliverablesDefinition] }
+  fallbackEntry(): undefined { return undefined }
+}
+
+class TestViewDefinitions {
+  entries(): readonly ConversationViewDefinition[] { return [timelineViewDefinition] }
+}
+
+const timelineViewDefinition: ConversationViewDefinition<ConversationViewNode, TimelineSnapshot> = {
+  target: 'test',
+  create: () => {
+    let current: TimelineSnapshot = { timeline: { turnOrder: [], turns: new Map() } }
+    return {
+      empty: current,
+      replace: ({ timeline }) => (current = { timeline }),
+      apply: ({ timeline }) => (current = { timeline }),
+    }
+  },
+}
+
+function at(
+  seq: number,
+  type: string,
+  data: unknown,
+  view?: ConversationEventInput['view'],
+): ConversationEventInput {
+  return {
+    event: {
+      seq, time: seq * 1_000, type, data,
+      ...(type === 'tool/result' ? { surfaceOp: 'append' } : {}),
+    } as ConversationEventInput['event'],
+    view,
+  }
+}
+
+function call(
+  seq: number,
+  callId: string,
+  view: ToolResultNode['callView'],
+  turn = 1,
+): ConversationEventInput {
+  return at(
+    seq,
+    'tool/call',
+    { turn, step: 1, callId, name: 'fixture', arguments: '{}' },
+    { for: 'call', view: view ?? { card: 'generic', title: 'fixture' } },
+  )
+}
+
+function result(seq: number, callId: string, isError = false, turn = 1): ConversationEventInput {
+  return at(seq, 'tool/result', {
+    turn,
+    step: 1,
+    message: {
+      source: { type: 'tool-result', callId },
+      content: [{ type: 'tool-result', content: [], isError }],
+    },
+  })
+}
+
+function diff(...paths: string[]): ToolResultNode['callView'] {
+  return {
     card: 'diff', title: `Write ${paths[0] ?? ''}`,
     diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
     locations: paths.map(path => ({ path })),
-  },
-})
+  }
+}
 
-describe('producedForClosing derivation', () => {
-  it('attributes each turn’s written files to the assistant that closes it', () => {
-    const nodes: ConversationNode[] = [
-      user(1, 'build it'),
-      assistant(2, 'writing', 1),
-      wrote(3, 'a', 'out/index.html'),
-      // Same file touched twice in one turn is one deliverable, in first-seen order.
-      wrote(4, 'b', 'out/app.css', 'out/index.html'),
-      // A read is not a deliverable; a failed write has no file to open.
-      { ...toolResult(5, 'c', 'read'), callView: { card: 'generic', title: 'Read x', locations: [{ path: 'x.ts' }] } },
-      { ...wrote(6, 'd', 'out/broken.html'), isError: true },
-      assistant(7, 'done', 1),
-      user(8, 'again'),
-      assistant(9, 'second turn', 2),
-    ]
-    expect(producedForClosing(nodes, 7)).toEqual(['out/index.html', 'out/app.css'])
-    expect(selectProducedFiles({ nodes, seq: 7, openFile: () => {} })).toEqual(['out/index.html', 'out/app.css'])
-    expect(selectProducedFiles({ nodes, seq: 9, openFile: () => {} })).toBeNull()
-    // A turn that produced nothing yields the empty list, and so does an
-    // anchor the window does not contain.
-    expect(producedForClosing(nodes, 9)).toEqual([])
-    expect(producedForClosing([user(1, 'hi'), assistant(2, 'hello', 1)], 2)).toEqual([])
-    expect(producedForClosing(nodes, 999)).toEqual([])
+function edit(path: string): ToolResultNode['callView'] {
+  return { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] }
+}
+
+function assembler(entries: readonly ConversationEventInput[], hasMore = false): ConversationNodeAssembler {
+  const value = new ConversationNodeAssembler(new TestEventDefinitions(), new TestViewDefinitions())
+  value.replaceWindow(entries, hasMore)
+  value.flush()
+  return value
+}
+
+function deliverablesOf(value: ConversationNodeAssembler, turn = 1): Readonly<DeliverablesTurnData> | undefined {
+  const snapshot = value.snapshot('test') as TimelineSnapshot
+  return snapshot.timeline.turns.get(turn)?.data.get('deliverables')
+}
+
+describe('produced-file Turn data', () => {
+  it('deduplicates paths in first-seen order and stops at the closing Assistant seq', () => {
+    const data = produced(
+      [3, 'out/index.html'],
+      [4, 'out/app.css'],
+      [4, 'out/index.html'],
+      [8, 'after.txt'],
+    )
+    expect(producedForClosing(data, 6)).toEqual(['out/index.html', 'out/app.css'])
+    expect(selectProducedFiles(tailOwner(data, 6))).toEqual(['out/index.html', 'out/app.css'])
+    expect(producedForClosing(undefined)).toEqual([])
+    expect(selectProducedFiles(tailOwner(undefined, 9, () => {}, 2))).toBeNull()
   })
 
+  it('folds successful diff and generic-edit calls while ignoring reads, failures, and missing locations', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      call(2, 'write', diff('out/index.html', 'out/app.css')),
+      result(3, 'write'),
+      call(4, 'edit', edit('notes.md')),
+      result(5, 'edit'),
+      call(6, 'read', { card: 'generic', title: 'Read', locations: [{ path: 'input.txt' }] }),
+      result(7, 'read'),
+      call(8, 'failed', diff('broken.txt')),
+      result(9, 'failed', true),
+      call(10, 'locationless', { card: 'diff', title: 'Write', diffs: [] }),
+      result(11, 'locationless'),
+    ])
 
-  it('counts a generic edit and never spills across the turn boundary', () => {
-    const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
-      ...toolResult(seq, callId, 'str_replace_editor'),
-      // str_replace_editor's insert mutates behind a generic card, so the
-      // discriminant is the render intent, not the card shape alone.
-      callView: { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] },
-    })
-    const nodes: ConversationNode[] = [
-      user(1, 'insert a line'),
-      inserted(2, 'i', 'notes.md'),
-      assistant(3, 'inserted', 1),
-      // Turn 2 mutates and then ends with no content text (interrupted, or its
-      // last text preceded the tool): its paths must not ride into turn 3.
-      user(4, 'now rewrite it'),
-      wrote(5, 'w', 'leaked.txt'),
-      user(6, 'and again'),
-      wrote(7, 'w2', 'notes.md'),
-      assistant(8, 'done', 3),
-    ]
-    expect(producedForClosing(nodes, 3)).toEqual(['notes.md'])
-    // Turn 3 lists only its own file — and the dedup set did not suppress the
-    // rewrite of a path an earlier turn already touched.
-    expect(producedForClosing(nodes, 8)).toEqual(['notes.md'])
-    expect(producedForClosing(nodes, 8)).not.toContain('leaked.txt')
+    expect(producedForClosing(deliverablesOf(value))).toEqual([
+      'out/index.html', 'out/app.css', 'notes.md',
+    ])
   })
 
-  it('resets on a turn-number change and skips turnless, viewless, and locationless nodes', () => {
-    const nodes: ConversationNode[] = [
-      user(1, 'go'),
-      // A turnless surface node neither tracks nor resets the boundary.
-      { kind: 'unknown', seq: 1.5, time: 1_500, type: 'x', data: null },
-      wrote(2, 'w', 'turn-one.txt'),
-      // A view-less result (window truncation) and cards without locations
-      // contribute nothing rather than crashing the walk.
-      toolResult(3, 'plain'),
-      { ...toolResult(4, 'nl', 'write'), callView: { card: 'diff', title: 'Write', diffs: [] } },
-      { ...toolResult(5, 'ge', 'str_replace_editor'), callView: { card: 'generic', title: 'insert', kind: 'edit' } },
-      assistant(6, 'mid narration', 1),
-      // Turn number advances with no user message in the window (truncated
-      // history): the accumulator must reset all the same.
-      assistant(7, 'closing', 2),
-    ]
-    expect(producedForClosing(nodes, 6)).toEqual(['turn-one.txt'])
-    expect(producedForClosing(nodes, 7)).toEqual([])
+  it('replays a tail page once prepend supplies its missing Turn start', () => {
+    const value = assembler([
+      call(10, 'late', diff('history.txt')),
+      result(11, 'late'),
+    ], true)
+    expect(deliverablesOf(value)).toBeUndefined()
+
+    value.prepend([at(1, 'turn/start', { turn: 1 })], false)
+    value.flush()
+    expect(producedForClosing(deliverablesOf(value))).toEqual(['history.txt'])
+  })
+
+  it('extends the same Turn data incrementally on live append', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      call(2, 'first', diff('first.txt')),
+      result(3, 'first'),
+    ])
+    const first = deliverablesOf(value)
+    expect(producedForClosing(first)).toEqual(['first.txt'])
+
+    value.append(call(4, 'second', diff('second.txt')))
+    value.append(result(5, 'second'))
+    value.flush()
+    expect(producedForClosing(deliverablesOf(value))).toEqual(['first.txt', 'second.txt'])
   })
 })
 
@@ -190,6 +283,7 @@ describe('plugin registration', () => {
   it('registers the tail entry and fiber disposal removes it', async () => {
     const ctx = new Context()
     await ctx.plugin(SlotsService).await()
+    await ctx.plugin(ConversationEventRegistry).await()
     // The owning view's child declaration, stood up by a bench root entry.
     ctx.slots.register({
       name: 'root',
@@ -204,17 +298,17 @@ describe('plugin registration', () => {
     // The prose face is live while the plugin is: a produced turn yields a
     // resolver whose matches open through the owner-supplied opener.
     const opened: string[] = []
-    const owner = {
-      nodes: [user(1, 'go'), wrote(2, 'w', 'site/report.html'), assistant(3, 'done', 1)],
-      seq: 3,
-      openFile: (path: string) => { opened.push(path) },
-    }
+    const owner = tailOwner(
+      produced([2, 'site/report.html']),
+      3,
+      (path) => { opened.push(path) },
+    )
     const service = (ctx as unknown as { get(name: string): ChatFileMentions | undefined }).get('chatFileMentions')
     const mentions = service?.forClosing(owner)
     mentions?.resolve('report.html')?.open()
     expect(opened).toEqual(['site/report.html'])
     // A turn that produced nothing yields no vocabulary at all.
-    expect(service?.forClosing({ ...owner, nodes: [user(1, 'hi'), assistant(2, 'ok', 1)], seq: 2 })).toBeUndefined()
+    expect(service?.forClosing(tailOwner(undefined, 2))).toBeUndefined()
 
     await fiber.dispose()
     expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(0)
diff --git a/packages/client/ui-slots/tests/surface.spec.ts b/packages/client/ui-slots/tests/surface.spec.ts
index 12a5eeba15..e85aa324e1 100644
--- a/packages/client/ui-slots/tests/surface.spec.ts
+++ b/packages/client/ui-slots/tests/surface.spec.ts
@@ -7,6 +7,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     'surface.a': { kind: 'single'; scope: 'root' }
     'surface.b': { kind: 'single'; scope: 'root' }
+    'surface.injected': { kind: 'single'; scope: 'root'; inject: { token: string } }
   }
 }
 
@@ -28,6 +29,16 @@ describe('dynamic-key escape hatch', () => {
     expect(core.spec('surface.b')).toBeUndefined()
   })
 
+  it('records the parent-declared Slot inject on the runtime spec', () => {
+    const core = new SlotCore()
+    const inject = { token: 'shared' }
+    core.register({
+      name: 'root',
+      children: { 'surface.injected': { kind: 'single', scope: 'root', inject } },
+    }, Comp as never)
+    expect(core.spec('surface.injected')?.inject).toBe(inject)
+  })
+
   it('entries/getVersion on an untouched key return the frozen empty array and 0', () => {
     const core = new SlotCore()
     expect(core.entries('surface.b')).toHaveLength(0)
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
index b3a6aec873..64277edccc 100644
--- a/packages/client/ui-slots/tests/type-chain.spec.tsx
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -5,7 +5,7 @@
 import { describe, expect, it } from 'vitest'
 import type { ReactNode } from 'react'
 import type {
-  BoundActions, DefineStore, PropsRenderSlots, PropsRuntime, PropsStore, SlotComponent,
+  BoundActions, DefineStore, PropsRenderSlots, PropsRuntime, PropsStore, SlotComponent, SlotHookFactory,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
 
@@ -19,6 +19,12 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'chain.frame': { kind: 'single'; scope: 'root' }
     'chain.side': { kind: 'single'; scope: 'root'; owner: { collapsed: boolean; width: number } }
     'chain.conv': { kind: 'single'; scope: 'session' }
+    'chain.context': {
+      kind: 'single'
+      scope: 'session'
+      hookContext: string
+      inject: ContextInjected
+    }
     'chain.tools': { kind: 'keyed'; scope: 'session' }
     'chain.takeover': { kind: 'chain'; scope: 'session'; owner: { items: readonly Item[] } }
   }
@@ -62,6 +68,23 @@ type ConvProps =
   & PropsStore<ChatHandle>
   & { send: (t: string) => void }
 
+interface TurnDataMap { tail: string; files: string }
+type UseTurnData = <Key extends keyof TurnDataMap>(key: Key) => TurnDataMap[Key] | undefined
+interface ContextInjected {
+  hooks: {
+    turnData: SlotHookFactory<'chain.context', UseTurnData>
+  }
+}
+type ContextProps = PropsRuntime<'chain.context'>
+const CONTEXT_INJECT: ContextInjected = {
+  hooks: {
+    turnData: (_standard, hookContext) => {
+      const id: string = hookContext
+      return key => id === '' ? undefined : ({ tail: 'tail', files: 'files' })[key]
+    },
+  },
+}
+
 // Component fixtures (never rendered; the register call sites are the test).
 declare function Frame(props: FrameProps): ReactNode
 declare function Conv(props: ConvProps): ReactNode
@@ -72,6 +95,8 @@ declare function NoDecl(props: PropsRuntime<'chain.frame'> & PropsRenderSlots<'c
 declare function Blind(props: PropsRuntime<'chain.frame'>): ReactNode
 declare function WrongStore(props: PropsRuntime<'chain.conv'> & PropsStore<ReturnType<typeof createPanelStore>>): ReactNode
 declare function Needs(props: PropsRuntime<'chain.conv'> & { send: (t: string) => void }): ReactNode
+declare function ContextOwner(props: PropsRuntime<'chain.frame'> & PropsRenderSlots<'chain.context'>): ReactNode
+declare function ContextReader(props: ContextProps): ReactNode
 declare function Takeover(props: PropsRuntime<'chain.takeover'> & { matched: Item }): ReactNode
 declare function WideTakeover(props: PropsRuntime<'chain.takeover'> & { matched: Item | string }): ReactNode
 declare function NarrowTakeover(props: PropsRuntime<'chain.takeover'> & { matched: { kind: 'q'; id: string; extra: number } }): ReactNode
@@ -144,6 +169,24 @@ describe('terminal-design type chain', () => {
       chainSlots.renderSlotChain('chain.takeover', { items: [] }, { fallback: null })
       chainSlots.renderSlot('chain.conv', {})
 
+      // A parent registration declares the Slot inject once; every child
+      // entry receives the same custom Hook, bound to official standard props
+      // and each render occurrence's opaque context.
+      core.register({
+        name: 'chain.frame',
+        children: {
+          'chain.context': { kind: 'single', scope: 'session', inject: CONTEXT_INJECT },
+        },
+      }, ContextOwner)
+      core.register({ name: 'chain.context' }, ContextReader)
+      const contextProps: ContextProps = null as never
+      const tail: string | undefined = contextProps.useTurnData('tail')
+      const contextSlots: PropsRenderSlots<'chain.context'> = null as never
+      contextSlots.renderSlot('chain.context', {}, {
+        hookContext: 'turn:1',
+      })
+      void tail
+
       // ── negatives ──────────────────────────────────────────────────
       // children spec must match the SlotMap entry.
       core.register({
@@ -151,6 +194,11 @@ describe('terminal-design type chain', () => {
         // @ts-expect-error chain.conv is session-scoped in SlotMap
         children: { 'chain.conv': { kind: 'single', scope: 'root' } },
       }, (() => null) as SlotComponent<never>)
+      core.register({
+        name: 'chain.frame',
+        // @ts-expect-error chain.context requires its Slot-level inject declaration
+        children: { 'chain.context': { kind: 'single', scope: 'session' } },
+      }, ContextOwner)
 
       // renderSlot key set ⊄ children declaration.
       // @ts-expect-error component renderSlot keys exceed the declaration
@@ -219,6 +267,16 @@ describe('terminal-design type chain', () => {
       // @ts-expect-error key not in this render share
       fp.renderSlot('chain.tools', {})
 
+      // Contextual hooks preserve both the business key and value type.
+      // @ts-expect-error unknown Turn-data key
+      contextProps.useTurnData('other')
+      // @ts-expect-error a contextual slot requires its occurrence context
+      contextSlots.renderSlot('chain.context', {})
+      // @ts-expect-error hookContext is the slot-declared string
+      const _wrongContextFactory: SlotHookFactory<'chain.context', UseTurnData> =
+        (_standard, _hookContext: number) => () => undefined
+      void _wrongContextFactory
+
       // baked actions strip the draft parameter.
       acts.setDraft('x')
       // @ts-expect-error wrong payload type
diff --git a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
index 9cbdfe3f1d..8f4fb384b0 100644
--- a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
@@ -8,6 +8,7 @@ import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
+import { toolChatSnapshot } from './tool-details-render.tsx'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
@@ -74,7 +75,7 @@ async function bench(nodes: ToolResultNode[]) {
   await runtime.sessions.add({
     id: SID,
     summary: { title: 'S', displayTitle: 'S', cwd: '/proj' },
-    snapshot: { nodes },
+    snapshot: { nodes, chat: toolChatSnapshot(nodes) },
     session: {
       loadOlder: vi.fn<ISession['loadOlder']>(),
       prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 6c0bb956bd..3b70851a02 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -11,7 +11,9 @@
 import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationEventRegistry, ConversationViewRegistry, createSnapshotStore, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, RunningToolCall, SessionId, SessionListState,
   ToolCallBlock, ToolResultNode, WorkspaceListState,
@@ -21,6 +23,7 @@ import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
+import { toolChatSnapshot } from './tool-details-render.tsx'
 
 const SID = 's1' as SessionId
 
@@ -75,7 +78,8 @@ function snapshotWith(
   const nestedNodes = nodes.map(node => ({ ...node, subCalls }))
   const nestedRunningCalls = runningCalls.map(call => ({ ...call, subCalls }))
   return {
-    sessionId: SID, nodes: nestedNodes, turnTimings: new Map(), turnEnds: new Map(), partial: null,
+    sessionId: SID, chat: toolChatSnapshot(nestedNodes, nestedRunningCalls),
+    nodes: nestedNodes, turnTimings: new Map(), turnEnds: new Map(), partial: null,
     runningCalls: nestedRunningCalls,
     pending: [], queue: [], running: runningCalls.length > 0, composerPhase: 'active', removed: false,
     openState: 'open', openError: null,
@@ -97,6 +101,8 @@ async function bench(snapshot: ConversationSnapshot) {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
   await slotsFiber.await()
+  await ctx.plugin(ConversationEventRegistry).await()
+  await ctx.plugin(ConversationViewRegistry).await()
   const slots = ctx.get('slots') as SlotsService
 
   const session = createSnapshotStore<ConversationSnapshot>(snapshot)
diff --git a/packages/client/ui-tool/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
index 7713bedaec..0cea47b572 100644
--- a/packages/client/ui-tool/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -20,7 +20,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { FileMutationRow, fileMutationToolview } from '../src/client/tool/toolviews/file-mutation-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
@@ -342,8 +342,11 @@ describe('DetailsPanel diff Output section', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
index 739a787a03..f74bbae6be 100644
--- a/packages/client/ui-tool/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -24,7 +24,7 @@ import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/t
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { ReadRow, readToolview } from '../src/client/tool/toolviews/read-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 
 afterEach(cleanup)
 
@@ -288,8 +288,11 @@ describe('DetailsPanel Output section (read)', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
index 51cab2d440..0016318b90 100644
--- a/packages/client/ui-tool/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -23,7 +23,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 
 /** SearchRow now composes ToolRow, so its props include the locale `t` seat. */
 type SearchRowProps = Parameters<typeof SearchRow>[0]
@@ -404,8 +404,11 @@ describe('DetailsPanel Output section (search)', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
index c9e2875a34..0dcb59d818 100644
--- a/packages/client/ui-tool/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -20,7 +20,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
@@ -479,8 +479,11 @@ describe('DetailsPanel Output section', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index 393b9f8f46..44f4231802 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -29,12 +29,21 @@ function props(
   return {
     useSession,
     renderSlot,
-    callId: block.callId,
-    toolName: block.call?.name ?? '',
-    block,
+    node: {
+      key: `tool:${block.callId}`,
+      kind: 'tool-call',
+      id: block.callId,
+      target: 'chat',
+      anchorSeq: block.seq,
+      location: { kind: 'session' },
+      visibility: 'visible',
+      data: { root: block },
+    },
     selectedCallId,
     openFile: vi.fn(),
     inspectCall: vi.fn(),
+    forkAt: vi.fn(),
+    fileMentions: vi.fn(),
     t,
   } as unknown as ToolTreeProps
 }
diff --git a/packages/client/ui-tool/tests/tool-details-render.tsx b/packages/client/ui-tool/tests/tool-details-render.tsx
index 0aeb3c5321..b2b2cd9ac7 100644
--- a/packages/client/ui-tool/tests/tool-details-render.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.tsx
@@ -1,5 +1,7 @@
 /** Test adapter for the production conversation.details.tool registration. */
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ChatConversationViewNode, ChatSnapshot, ConversationNode, RunningToolCall, SessionId,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionProviderComponent, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import type { DetailsSlotProps, DetailsToolOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/contract/slots.ts'
 import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
@@ -7,6 +9,45 @@ import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
 /** Framework session-area seat used by direct DetailsPanel tests. */
 export const SessionProviderStub: SessionProviderComponent = ({ children }) => children('s1' as SessionId)
 
+/** Build the canonical Chat slice consumed by Tool rows and details tests. */
+export function toolChatSnapshot(
+  settled: readonly ConversationNode[] = [],
+  running: readonly RunningToolCall[] = [],
+): ChatSnapshot {
+  const roots = [...settled.filter(node => node.kind === 'tool-result'), ...running]
+  const nodes: ChatConversationViewNode[] = roots.map(root => ({
+    key: `tool:${root.callId}`,
+    kind: 'tool-call',
+    id: root.callId,
+    target: 'chat',
+    anchorSeq: 'kind' in root ? root.seq : Number.MAX_SAFE_INTEGER,
+    location: { kind: 'session' },
+    visibility: 'visible',
+    data: { root },
+  }))
+  const byKey = new Map(nodes.map(node => [node.key, node]))
+  const empty: readonly string[] = []
+  return {
+    order: nodes.map(node => node.key),
+    nodes: {
+      get: key => byKey.get(key),
+      values: () => nodes,
+    },
+    locations: {
+      getTurn: () => empty,
+      getStep: () => empty,
+    },
+    timeline: { turnOrder: [], turns: new Map() },
+    legacy: {
+      nodes: settled,
+      runningCalls: running,
+      partial: null,
+      turnTimings: new Map(),
+      turnEnds: new Map(),
+    },
+  }
+}
+
 /**
  * Bind ui-tool's details renderer to the conversation slot callback shape.
  * @param t - conversation locale seat used by Tool cards.
@@ -16,7 +57,7 @@ export function renderToolDetails(t: TranslateNS<'conversation'>): DetailsSlotPr
   return (_key, owner) => {
     // PropsRenderSlots keeps its key generic even for this one-key share;
     // recover the concrete owner selected by the adapter's fixed slot.
-    const details = owner as DetailsToolOwnerProps
+    const details = owner as unknown as DetailsToolOwnerProps
     return <ToolDetails block={details.block} cwd={details.cwd} t={t} />
   }
 }
diff --git a/packages/client/ui-tool/tests/toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
index c927cc30ea..f1a9df3392 100644
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -18,6 +18,7 @@ import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '@deepseek-ai/dsh-client-ui-tool/client'
 import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
+import { toolChatSnapshot } from './tool-details-render.tsx'
 
 const SID = 's1' as SessionId
 
@@ -71,7 +72,7 @@ async function bench(nodes: ToolResultNode[]) {
   await runtime.sessions.add({
     id: SID,
     summary: { title: 'S', displayTitle: 'S' },
-    snapshot: { nodes },
+    snapshot: { nodes, chat: toolChatSnapshot(nodes) },
     session: {
       loadOlder: vi.fn<ISession['loadOlder']>(),
       prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
diff --git a/packages/client/ui-tool/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
index 7856ae9d6f..44f9e05090 100644
--- a/packages/client/ui-tool/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -23,7 +23,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
@@ -234,8 +234,11 @@ describe('DetailsPanel web Output section', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/web-react/tests/scoped-slots.spec.tsx b/packages/client/web-react/tests/scoped-slots.spec.tsx
index 16334ff7c7..0688d409b9 100644
--- a/packages/client/web-react/tests/scoped-slots.spec.tsx
+++ b/packages/client/web-react/tests/scoped-slots.spec.tsx
@@ -90,6 +90,7 @@ function makeHost() {
   const provide = observable<SessionMaybeProvideInfo>(absentInfo)
   let currentId: string | undefined
   const infos = new Map<string, SessionProvideInfo>()
+  const sessionSources = new Map<string, ReturnType<typeof observable<unknown>>>()
 
   const bump = (key: string) => {
     versions.set(key, (versions.get(key) ?? 0) + 1)
@@ -160,17 +161,24 @@ function makeHost() {
         bump(key)
       }
     },
-    addSession: (id: string): SessionProvideInfo => {
+    addSession: (id: string, initial: unknown = { sid: id }): SessionProvideInfo => {
       // Bare source per bundle (identity-stable): the machinery binds useSession from it.
+      const session = observable<unknown>(initial)
       const info: SessionProvideInfo = {
         sessionId: id,
-        hooks: { session: { getSnapshot: () => ({ sid: id }), subscribe: () => () => {} } },
+        hooks: { session },
         props: {},
       }
+      sessionSources.set(id, session)
       infos.set(id, info)
       if (currentId === id) provide.set(info)
       return info
     },
+    setSession: (id: string, snapshot: unknown) => {
+      const source = sessionSources.get(id)
+      if (source === undefined) throw new Error(`unknown test session: ${id}`)
+      source.set(snapshot)
+    },
   }
 }
 
@@ -635,6 +643,71 @@ describe('standard-kit synthesis', () => {
     expect(props['sessionId']).toBe('s1')
   })
 
+  it('binds only function-valued inject hooks to the standard kit and render occurrence context', () => {
+    const h = makeHost()
+    const turnDataFactory = vi.fn((standard: AnyProps, turn: unknown) => (key: string) => {
+      const useSession = standard['useSession'] as (selector: (snapshot: unknown) => unknown) => unknown
+      return useSession((snapshot) => {
+        const value = snapshot as { turns: Record<number, Record<string, unknown>> }
+        return value.turns[turn as number]?.[key]
+      })
+    })
+    const sessionSpec: DeclaredSpec = {
+      kind: 'single', scope: 'session', inject: { hooks: { turnData: turnDataFactory } },
+    }
+    h.declare('k.session', sessionSpec)
+    h.addSession('s1', {
+      turns: { 1: { tail: 'one' }, 2: { tail: 'two' } },
+      unrelated: 0,
+    })
+    const hooks = new Map<string, Array<(key: string) => unknown>>()
+    let renders = 0
+    h.add('k.session', {
+      component: ({ label, useTurnData }: { label: string; useTurnData: (key: string) => unknown }) => {
+        renders += 1
+        const seen = hooks.get(label) ?? []
+        seen.push(useTurnData)
+        hooks.set(label, seen)
+        return <b data-turn={label}>{String(useTurnData('tail'))}</b>
+      },
+    })
+    const { view } = mountRoot(h, { 'k.session': sessionSpec }, renderSlot => (
+      <SessionProvider>{() => <>
+        {renderSlot('k.session', { label: 'one' }, { hookContext: 1 })}
+        {renderSlot('k.session', { label: 'two' }, { hookContext: 2 })}
+      </>}
+      </SessionProvider>
+    ))
+    act(() => { h.current.set('s1') })
+    expect(view.container.textContent).toBe('onetwo')
+    expect(renders).toBe(2)
+
+    // A session publication whose selected contextual value is identical is
+    // filtered by the framework-bound selector.
+    act(() => {
+      h.setSession('s1', {
+        turns: { 1: { tail: 'one' }, 2: { tail: 'two' } },
+        unrelated: 1,
+      })
+    })
+    expect(renders).toBe(2)
+
+    // Updating the selected contextual value re-renders through the returned
+    // custom Hook; the factory itself and its Hook identity stay stable.
+    act(() => {
+      h.setSession('s1', {
+        turns: { 1: { tail: 'updated' }, 2: { tail: 'two' } },
+        unrelated: 1,
+      })
+    })
+    expect(view.container.textContent).toBe('updatedtwo')
+    expect(renders).toBe(3)
+    expect(hooks.get('one')![1]).toBe(hooks.get('one')![0])
+    expect(hooks.get('two')).toHaveLength(1)
+    expect(hooks.get('one')![0]).not.toBe(hooks.get('two')![0])
+    expect(turnDataFactory).toHaveBeenCalledTimes(2)
+  })
+
   it('hands the SessionProvider seat to entries declaring a session-scope child', () => {
     const h = makeHost()
     h.declare('k.session', SINGLE_SESSION)
diff --git a/packages/compact/command-compact/tests/command-compact.spec.ts b/packages/compact/command-compact/tests/command-compact.spec.ts
index 6922778a26..0c419d6799 100644
--- a/packages/compact/command-compact/tests/command-compact.spec.ts
+++ b/packages/compact/command-compact/tests/command-compact.spec.ts
@@ -4,6 +4,7 @@ import Loader from '@cordisjs/plugin-loader'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import CommandService, { type CommandResult } from '@deepseek-ai/dsh-commands'
 import {
+  CompactionId,
   CompactService,
   ManualCompactionError,
   type CompactAgentContext,
@@ -14,7 +15,10 @@ import {
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
 
+const COMPACTION_ID = CompactionId('command-compact-test')
+
 const RESULT: CompactionResult = {
+  compactionId: COMPACTION_ID,
   startSeq: 1,
   summarySeq: 2,
   endSeq: 3,
@@ -45,18 +49,28 @@ class StubCompactService extends CompactService {
   override compactNow(
     agent: ManualCompactAgentContext,
     signal: AbortSignal,
+    sourceCommandId?: Parameters<CompactService['compactNow']>[2],
   ): Promise<CompactionResult | null> {
     this.calls.push({ agent, signal })
     if (this.operation !== undefined) return this.operation()
     return this.failure === undefined
-      ? Promise.resolve(this.result === null ? null : this.appendResult(agent, this.result))
+      ? Promise.resolve(this.result === null ? null : this.appendResult(agent, this.result, sourceCommandId))
       // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- exercise arbitrary backend rejection values.
       : Promise.reject(this.failure)
   }
 
-  private appendResult(agent: ManualCompactAgentContext, result: CompactionResult): CompactionResult {
-    agent.session.append('compact/start', { turn: null })
+  private appendResult(
+    agent: ManualCompactAgentContext,
+    result: CompactionResult,
+    sourceCommandId: Parameters<CompactService['compactNow']>[2],
+  ): CompactionResult {
+    const provenance = {
+      compactionId: result.compactionId,
+      ...sourceCommandId === undefined ? {} : { sourceCommandId },
+    }
+    agent.session.append('compact/start', { ...provenance, turn: null })
     agent.session.append('compact/summary', {
+      ...provenance,
       summary: result.summary,
       shadowedRange: result.shadowedRange,
       shadowedSeqs: result.shadowedSeqs,
@@ -64,8 +78,8 @@ class StubCompactService extends CompactService {
       provider: 'command-test',
       model: 'command-test',
     })
-    agent.session.append('compact/end', { turn: null })
-    return result
+    agent.session.append('compact/end', { ...provenance, turn: null })
+    return { ...result, ...provenance }
   }
 }
 
diff --git a/packages/compact/command-compact/tests/loader-composition.spec.ts b/packages/compact/command-compact/tests/loader-composition.spec.ts
index 5a5d37d8b1..5f7fd0b346 100644
--- a/packages/compact/command-compact/tests/loader-composition.spec.ts
+++ b/packages/compact/command-compact/tests/loader-composition.spec.ts
@@ -9,6 +9,7 @@ import Include from '@cordisjs/plugin-include'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import CommandService from '@deepseek-ai/dsh-commands'
 import {
+  CompactionId,
   CompactService,
   type CompactAgentContext,
   type CompactionResult,
@@ -18,7 +19,10 @@ import {
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 
+const COMPACTION_ID = CompactionId('loader-command-compact-test')
+
 const RESULT: CompactionResult = {
+  compactionId: COMPACTION_ID,
   startSeq: 1,
   summarySeq: 2,
   endSeq: 3,
@@ -44,9 +48,15 @@ class LoaderCompactService extends CompactService {
   override compactNow(
     agent: ManualCompactAgentContext,
     _signal: AbortSignal,
+    sourceCommandId?: Parameters<CompactService['compactNow']>[2],
   ): Promise<CompactionResult | null> {
-    agent.session.append('compact/start', { turn: null })
+    const provenance = {
+      compactionId: RESULT.compactionId,
+      ...sourceCommandId === undefined ? {} : { sourceCommandId },
+    }
+    agent.session.append('compact/start', { ...provenance, turn: null })
     agent.session.append('compact/summary', {
+      ...provenance,
       summary: RESULT.summary,
       shadowedRange: RESULT.shadowedRange,
       shadowedSeqs: RESULT.shadowedSeqs,
@@ -54,8 +64,8 @@ class LoaderCompactService extends CompactService {
       provider: 'loader-test',
       model: 'loader-test',
     })
-    agent.session.append('compact/end', { turn: null })
-    return Promise.resolve(RESULT)
+    agent.session.append('compact/end', { ...provenance, turn: null })
+    return Promise.resolve({ ...RESULT, ...provenance })
   }
 }
 
@@ -132,11 +142,17 @@ describe('command-compact real Loader composition', () => {
       },
       {
         type: 'compact/start',
-        data: { turn: null },
+        data: {
+          compactionId: COMPACTION_ID,
+          sourceCommandId: execution.commandId,
+          turn: null,
+        },
       },
       {
         type: 'compact/summary',
         data: {
+          compactionId: COMPACTION_ID,
+          sourceCommandId: execution.commandId,
           summary: RESULT.summary,
           shadowedRange: RESULT.shadowedRange,
           shadowedSeqs: RESULT.shadowedSeqs,
@@ -147,7 +163,11 @@ describe('command-compact real Loader composition', () => {
       },
       {
         type: 'compact/end',
-        data: { turn: null },
+        data: {
+          compactionId: COMPACTION_ID,
+          sourceCommandId: execution.commandId,
+          turn: null,
+        },
       },
       {
         type: 'command/done',
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index 996d5d61e1..f97aaf52b9 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -4,7 +4,7 @@ import BasicCompactService from '@deepseek-ai/dsh-compact-basic'
 import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
 import { selectCompactableRange } from '@deepseek-ai/dsh-compact-basic/src/region.ts'
 import type { SummarizationInput, SummaryResult } from '@deepseek-ai/dsh-compact-basic/src/summarizer.ts'
-import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
+import { CompactionId, toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
 import {
   resolveCompactSpec,
   resolveConfig,
@@ -945,7 +945,10 @@ describe('compaction region transaction', () => {
     )).rejects.toThrow(/no open turn/)
 
     const locked = conversation(1)
-    locked.append('compact/start', { turn: 2 })
+    locked.append('compact/start', {
+      compactionId: CompactionId('locked-compaction'),
+      turn: 2,
+    })
     const lockedNodes = locked.surface.nodes
     await expect(compact.compactRegion(
       lockedNodes[0]!,
@@ -1623,6 +1626,7 @@ describe('automatic listener and loader composition', () => {
     const compact = new TestCompactService(ctx)
     const session = conversation(2)
     const fakeResult: CompactionResult = {
+      compactionId: CompactionId('fake-compaction'),
       startSeq: 1,
       summarySeq: 2,
       endSeq: 3,
diff --git a/packages/compact/compact-basic/tests/manual-compact.spec.ts b/packages/compact/compact-basic/tests/manual-compact.spec.ts
index 7544c3223b..0599d3f364 100644
--- a/packages/compact/compact-basic/tests/manual-compact.spec.ts
+++ b/packages/compact/compact-basic/tests/manual-compact.spec.ts
@@ -3,13 +3,14 @@ import { Context } from 'cordis'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import InvariantService from '@deepseek-ai/dsh-invariants'
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
 import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
 import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import * as CompactInvariant from '@deepseek-ai/dsh-compact/invariant'
 import * as CompactBasicInvariant from '@deepseek-ai/dsh-compact-basic/invariant'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
-import { isCompactCheckpointSource, ManualCompactionError } from '@deepseek-ai/dsh-compact'
+import { CompactionId, isCompactCheckpointSource, ManualCompactionError } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
 import {
   createAssistantMessage,
@@ -23,7 +24,7 @@ import type {
   StreamChunk,
   TokenUsage,
 } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import LlmService from '@deepseek-ai/dsh-llm'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -394,22 +395,35 @@ describe('compactNow transaction and failure classification', () => {
     const { compact, flushes } = detachedService()
     const session = closedConversation(2, 7)
     const agent = fakeAgent(session, () => () => undefined)
+    const commandId = CommandId('manual-compact-command')
 
-    const result = await compact.compactNow(agent, SIGNAL)
+    const result = await compact.compactNow(agent, SIGNAL, commandId)
 
     expect(result).not.toBeNull()
+    expect(result?.sourceCommandId).toBe(commandId)
     expect(flushes()).toBe(1)
     expect(session.events.filter(event => event.type === 'turn/start').at(-1)?.data.turn).toBe(7)
-    expect(session.events.findLast(event => event.type === 'compact/start')?.data)
-      .toEqual({ turn: null })
-    expect(session.events.findLast(event => event.type === 'compact/end')?.data)
-      .toEqual({ turn: null })
+    const start = session.events.findLast(event => event.type === 'compact/start')
+    const summaryEvent = session.events.findLast(event => event.type === 'compact/summary')
+    const checkpoint = session.events.findLast(
+      (event): event is SessionEvent<'user/message'> => event.type === 'user/message'
+        && isCompactCheckpointSource(event.data.source),
+    )
+    const end = session.events.findLast(event => event.type === 'compact/end')
+    const correlated = { compactionId: result?.compactionId, sourceCommandId: commandId }
+    expect(start?.data).toEqual({ ...correlated, turn: null })
+    expect(summaryEvent?.data.sourceCommandId).toBe(commandId)
+    expect(checkpoint?.data.source).toMatchObject(correlated)
+    expect(end?.data).toEqual({ ...correlated, turn: null })
   })
 
   it('reports a live unmatched bracket as busy without summarizing', async () => {
     const { compact } = detachedService()
     const session = closedConversation(2)
-    session.append('compact/start', { turn: null })
+    session.append('compact/start', {
+      compactionId: CompactionId('live-manual-compaction'),
+      turn: null,
+    })
     const agent = fakeAgent(session, () => () => undefined)
 
     const error = await rejection(() => compact.compactNow(agent, SIGNAL))
@@ -421,7 +435,10 @@ describe('compactNow transaction and failure classification', () => {
   it('ignores an unmatched bracket inherited before a later end-seed marker', async () => {
     const { compact } = detachedService()
     const original = closedConversation(2)
-    original.append('compact/start', { turn: null })
+    original.append('compact/start', {
+      compactionId: CompactionId('stale-manual-compaction'),
+      turn: null,
+    })
     const reloaded = Session.create(SessionId('stale-orphan'), [...original.events])
     const boundary = reloaded.events.findLast(event => event.type === 'session/end-seed')
     const orphan = reloaded.events.find(event => event.type === 'compact/start')
@@ -435,7 +452,10 @@ describe('compactNow transaction and failure classification', () => {
   it('scans a stale orphan independently of later repaired turn state', async () => {
     const { compact } = detachedService()
     const original = closedConversation(2)
-    original.append('compact/start', { turn: null })
+    original.append('compact/start', {
+      compactionId: CompactionId('reloaded-manual-compaction'),
+      turn: null,
+    })
     original.append('turn/start', { turn: 3 })
     original.append('turn/end', { turn: 3, reason: { kind: 'interrupted' } })
     const reloaded = Session.create(SessionId('reloaded-orphan'), [...original.events])
@@ -664,7 +684,7 @@ describe('compactNow transaction and failure classification', () => {
     expect(result).not.toBeNull()
     expect(session.events.some(event => event.type === 'turn/start')).toBe(false)
     expect(session.events.find(event => event.type === 'compact/start')?.data)
-      .toEqual({ turn: null })
+      .toEqual({ compactionId: result?.compactionId, turn: null })
   })
 
   it('classifies a durability failure after the standalone bracket committed', async () => {
@@ -676,8 +696,9 @@ describe('compactNow transaction and failure classification', () => {
     expect((await rejection(compact.compactNow(agent, SIGNAL))).code).toBe('persistence')
     vi.restoreAllMocks()
     expect(session.events.some(event => event.type === 'compact/summary')).toBe(true)
-    expect(session.events.findLast(event => event.type === 'compact/end')?.data)
-      .toEqual({ turn: null })
+    const start = session.events.findLast(event => event.type === 'compact/start')
+    const end = session.events.findLast(event => event.type === 'compact/end')
+    expect(end?.data).toEqual({ compactionId: start?.data.compactionId, turn: null })
   })
 
   it('lets a pre-aborted signal win before reservation, measurement, or summarization', async () => {
diff --git a/packages/compact/compact/tests/compact.spec.ts b/packages/compact/compact/tests/compact.spec.ts
index 7e6915354f..74e2bd0270 100644
--- a/packages/compact/compact/tests/compact.spec.ts
+++ b/packages/compact/compact/tests/compact.spec.ts
@@ -2,8 +2,9 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import {
-  COMPACT_CHECKPOINT_SOURCE,
+  CompactionId,
   CompactService,
+  compactCheckpointSource,
   isCompactCheckpointSource,
 } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compact'
@@ -52,9 +53,11 @@ class StubCompactService extends CompactService {
     const endIndex = surface.indexOf(end)
     if (startIndex < 0 || endIndex < startIndex) throw new Error('stub compact range is invalid')
     const shadowedSeqs = surface.slice(startIndex, endIndex + 1)
+    const compactionId = CompactionId('stub-compaction')
     // Minimal stub honoring the lock + log-only event contract.
-    const startEvent = session.append('compact/start', { turn: 0 })
+    const startEvent = session.append('compact/start', { compactionId, turn: 0 })
     const summaryEvent = session.append('compact/summary', {
+      compactionId,
       summary,
       shadowedRange: { start, end },
       shadowedSeqs,
@@ -64,13 +67,14 @@ class StubCompactService extends CompactService {
     })
     session.append('user/message', createUserMessage({
       content: summary,
-      source: COMPACT_CHECKPOINT_SOURCE,
+      source: compactCheckpointSource(compactionId),
     }), {
       surfaceOp: { op: 'replace', start, end },
       sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
     })
-    const endEvent = session.append('compact/end', { turn: 0 })
+    const endEvent = session.append('compact/end', { compactionId, turn: 0 })
     return {
+      compactionId,
       startSeq: startEvent.seq,
       summarySeq: summaryEvent.seq,
       endSeq: endEvent.seq,
@@ -139,7 +143,8 @@ describe('CompactService seam', () => {
     expect(result.shadowedSeqs).toEqual([original.seq])
     const checkpoint = session.events.find(event => event.type === 'user/message'
       && isCompactCheckpointSource(event.data.source))
-    expect(checkpoint?.type === 'user/message' && checkpoint.data.source).toEqual(COMPACT_CHECKPOINT_SOURCE)
+    expect(checkpoint?.type === 'user/message' && checkpoint.data.source)
+      .toEqual(compactCheckpointSource(result.compactionId))
     expect(isCompactCheckpointSource({ kind: 'plugin', plugin: 'other' })).toBe(false)
     expect(isCompactCheckpointSource({ kind: 'user' })).toBe(false)
     expect(session.events.filter(e => e.type.startsWith('compact/')).map(e => e.type))
diff --git a/packages/compact/compact/tests/invariant.spec.ts b/packages/compact/compact/tests/invariant.spec.ts
index c5a68c9de6..1637c16179 100644
--- a/packages/compact/compact/tests/invariant.spec.ts
+++ b/packages/compact/compact/tests/invariant.spec.ts
@@ -1,7 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compact'
 import * as CompactInvariant from '@deepseek-ai/dsh-compact/invariant'
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 
 async function setup(): Promise<Context> {
@@ -12,7 +15,13 @@ async function setup(): Promise<Context> {
   return ctx
 }
 
+const TEST_COMPACTION_ID = CompactionId('test-compaction')
+const NEXT_COMPACTION_ID = CompactionId('next-test-compaction')
+const TEST_COMMAND_ID = CommandId('test-command')
+const NEXT_COMMAND_ID = CommandId('next-test-command')
+
 const summary = (overrides: Record<string, unknown> = {}) => ({
+  compactionId: TEST_COMPACTION_ID,
   summary: [{ type: 'text' as const, text: 'short' }],
   shadowedRange: { start: 2, end: 4 },
   shadowedSeqs: [2, 3, 4],
@@ -31,33 +40,33 @@ describe('compaction invariants', () => {
     const ctx = await setup()
     const success = ctx.sessions.create()
     startTurn(success)
-    success.append('compact/start', { turn: 1 })
+    success.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     success.append('compact/summary', summary())
-    success.append('compact/end', { turn: 1 })
+    success.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1 })
 
     const failed = ctx.sessions.create()
     startTurn(failed, 2)
-    failed.append('compact/start', { turn: 2 })
-    failed.append('compact/end', { turn: 2, error: 'provider failed' })
+    failed.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 2 })
+    failed.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 2, error: 'provider failed' })
   })
 
   it('accepts standalone successful and failed compaction lifecycles between turns', async () => {
     const ctx = await setup()
     const success = ctx.sessions.create()
-    success.append('compact/start', { turn: null })
+    success.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     success.append('compact/summary', summary())
-    success.append('compact/end', { turn: null })
+    success.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null })
 
     const failed = ctx.sessions.create()
-    failed.append('compact/start', { turn: null })
-    failed.append('compact/end', { turn: null, error: 'provider failed' })
+    failed.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
+    failed.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null, error: 'provider failed' })
   })
 
   it('clears an inherited open compaction trace at end-seed during replay', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('stale-compaction-source'))
-    source.append('compact/start', { turn: null })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     const replayed = ctx.sessions.create(SessionId('stale-compaction-replay'), {
       seed: source.events,
     })
@@ -68,8 +77,8 @@ describe('compaction invariants', () => {
     await ctx.plugin(CompactInvariant)
 
     expect(() => {
-      replayed.append('compact/start', { turn: null })
-      replayed.append('compact/end', { turn: null, error: 'new attempt failed' })
+      replayed.append('compact/start', { compactionId: NEXT_COMPACTION_ID, turn: null })
+      replayed.append('compact/end', { compactionId: NEXT_COMPACTION_ID, turn: null, error: 'new attempt failed' })
     }).not.toThrow()
   })
 
@@ -78,7 +87,7 @@ describe('compaction invariants', () => {
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('stale-numbered-compaction-source'))
     startTurn(source)
-    source.append('compact/start', { turn: 1 })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     const replayed = ctx.sessions.create(SessionId('stale-numbered-compaction-replay'), {
       seed: source.events,
     })
@@ -98,7 +107,7 @@ describe('compaction invariants', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('stale-repaired-compaction-source'))
-    source.append('compact/start', { turn: null })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     startTurn(source)
     source.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
     const replayed = ctx.sessions.create(SessionId('stale-repaired-compaction-replay'), {
@@ -124,10 +133,10 @@ describe('compaction invariants', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('closed-nested-compaction-source'))
-    source.append('compact/start', { turn: null })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     startTurn(source)
     source.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
-    source.append('compact/end', { turn: null, error: 'failed after crossing turn' })
+    source.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null, error: 'failed after crossing turn' })
     const replayed = ctx.sessions.create(SessionId('closed-nested-compaction-replay'), {
       seed: source.events,
     })
@@ -143,10 +152,14 @@ describe('compaction invariants', () => {
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1 })
-    session.append('compact/start', { turn: 1 })
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     await ctx.plugin(InvariantService)
     await ctx.plugin(CompactInvariant)
-    expect(() => session.append('compact/end', { turn: 1, error: 'resume failed' })).not.toThrow()
+    expect(() => session.append('compact/end', {
+      compactionId: TEST_COMPACTION_ID,
+      turn: 1,
+      error: 'resume failed',
+    })).not.toThrow()
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
   })
 
@@ -162,7 +175,8 @@ describe('compaction invariants', () => {
         type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 },
       })
       ctx.emit('session/event', session, {
-        type: 'compact/start', seq: 2, time: 2, data: { turn: 1 },
+        type: 'compact/start', seq: 2, time: 2,
+        data: { compactionId: TEST_COMPACTION_ID, turn: 1 },
       })
     }).not.toThrow()
   })
@@ -170,28 +184,30 @@ describe('compaction invariants', () => {
   it('rejects compaction outside or for a different open turn', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create()
-    expect(() => session.append('compact/start', { turn: 1 })).toThrow(/outside any open turn/)
+    expect(() => session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 }))
+      .toThrow(/outside any open turn/)
     startTurn(session)
-    expect(() => session.append('compact/start', { turn: 2 })).toThrow(/but open turn is 1/)
+    expect(() => session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 2 }))
+      .toThrow(/but open turn is 1/)
   })
 
   it('rejects a standalone bracket while a turn is open and a numbered bracket between turns', async () => {
     const ctx = await setup()
     const open = ctx.sessions.create()
     startTurn(open)
-    expect(() => open.append('compact/start', { turn: null }))
+    expect(() => open.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null }))
       .toThrow(/standalone but turn 1 is open/)
 
     const idle = ctx.sessions.create()
-    expect(() => idle.append('compact/start', { turn: 1 }))
+    expect(() => idle.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 }))
       .toThrow(/outside any open turn/)
   })
 
   it('attributes a nested standalone start to the standalone owner', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create()
-    session.append('compact/start', { turn: null })
-    expect(() => session.append('compact/start', { turn: null }))
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
+    expect(() => session.append('compact/start', { compactionId: NEXT_COMPACTION_ID, turn: null }))
       .toThrow(/standalone compaction is still compacting/)
   })
 
@@ -201,7 +217,7 @@ describe('compaction invariants', () => {
     const session = ctx.sessions.create()
     startTurn(session)
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    session.append('compact/start', { turn: 1 })
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     await ctx.plugin(InvariantService)
     await expect(ctx.plugin(CompactInvariant).then(() => undefined)).rejects.toThrow(/outside any open turn/)
   })
@@ -209,10 +225,10 @@ describe('compaction invariants', () => {
   it('rejects turn boundaries that cross live standalone or numbered compaction brackets', async () => {
     const ctx = await setup()
     const standalone = ctx.sessions.create()
-    standalone.append('compact/start', { turn: null })
+    standalone.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     expect(() => { startTurn(standalone) })
       .toThrow(/turn\/start cannot cross an open standalone compaction/)
-    standalone.append('compact/end', { turn: null, error: 'cancelled' })
+    standalone.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null, error: 'cancelled' })
     expect(() => {
       startTurn(standalone)
       standalone.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
@@ -220,53 +236,151 @@ describe('compaction invariants', () => {
 
     const numbered = ctx.sessions.create()
     startTurn(numbered)
-    numbered.append('compact/start', { turn: 1 })
+    numbered.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     expect(() => numbered.append(
       'turn/end',
       { turn: 1, reason: { kind: 'completed' } },
     )).toThrow(/turn\/end cannot cross an open compaction for turn 1/)
-    numbered.append('compact/end', { turn: 1, error: 'cancelled' })
+    numbered.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'cancelled' })
     expect(() => numbered.append(
       'turn/end',
       { turn: 1, reason: { kind: 'completed' } },
     )).not.toThrow()
   })
 
+  it('rejects a replacement checkpoint for another compaction transaction', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    const original = session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'original' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    startTurn(session)
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+    session.append('compact/summary', summary())
+
+    expect(() => session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(NEXT_COMPACTION_ID),
+    }), {
+      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
+      sourceEventSeqs: [original.seq],
+    })).toThrow(/compaction checkpoint id .* does not match compact\/start id/)
+  })
+
+  it('requires checkpoint provenance to name an open transaction', async () => {
+    const ctx = await setup()
+    const withoutStart = ctx.sessions.create()
+    const original = withoutStart.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'original' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    expect(() => withoutStart.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(TEST_COMPACTION_ID),
+    }), {
+      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
+      sourceEventSeqs: [original.seq],
+    })).toThrow(/no matching compact\/start/)
+
+    const emptyCommand = ctx.sessions.create()
+    const replaced = emptyCommand.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'original' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    startTurn(emptyCommand)
+    emptyCommand.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+    expect(() => emptyCommand.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(TEST_COMPACTION_ID, CommandId('')),
+    }), {
+      surfaceOp: { op: 'replace', start: replaced.seq, end: replaced.seq },
+      sourceEventSeqs: [replaced.seq],
+    })).toThrow(/checkpoint sourceCommandId must be a non-empty string/)
+  })
+
   it.each([
+    ['empty start id', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', { compactionId: CompactionId(''), turn: 1 })
+    }, /compact\/start compactionId must be a non-empty string/],
+    ['empty start source command id', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: CommandId(''),
+        turn: 1,
+      })
+    }, /compact\/start sourceCommandId must be a non-empty string/],
     ['summary without start', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compact/summary', summary())
     }, /no matching compact\/start/],
     ['nested start', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
-      session.append('compact/start', { turn: 2 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/start', { compactionId: NEXT_COMPACTION_ID, turn: 2 })
     }, /still compacting/],
     ['repeated summary', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary())
       session.append('compact/summary', summary())
     }, /repeated within one compaction/],
+    ['summary for another compaction', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/summary', summary({ compactionId: NEXT_COMPACTION_ID }))
+    }, /compact\/summary id .* does not match compact\/start id/],
+    ['summary for another source command', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: TEST_COMMAND_ID,
+        turn: 1,
+      })
+      session.append('compact/summary', summary({ sourceCommandId: NEXT_COMMAND_ID }))
+    }, /compact\/summary sourceCommandId .* does not match compact\/start sourceCommandId/],
     ['empty shadow set', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary({ shadowedSeqs: [] }))
     }, /shadowedSeqs must be non-empty/],
     ['wrong endpoints', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary({ shadowedRange: { start: 1, end: 4 } }))
     }, /shadowedRange must match/],
     ['invalid token count', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary({ shadowedTokenCount: -1 }))
     }, /non-negative safe integer/],
     ['end without start', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/end', { turn: 1, error: 'failed' })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'failed' })
     }, /no matching compact\/start/],
     ['wrong end turn', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
-      session.append('compact/end', { turn: 2, error: 'failed' })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 2, error: 'failed' })
     }, /does not match/],
+    ['end for another compaction', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/end', { compactionId: NEXT_COMPACTION_ID, turn: 1, error: 'failed' })
+    }, /compact\/end id .* does not match compact\/start id/],
+    ['end missing the source command', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: TEST_COMMAND_ID,
+        turn: 1,
+      })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'failed' })
+    }, /compact\/end sourceCommandId .* does not match compact\/start sourceCommandId/],
+    ['empty end source command id', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: TEST_COMMAND_ID,
+        turn: 1,
+      })
+      session.append('compact/end', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: CommandId(''),
+        turn: 1,
+        error: 'failed',
+      })
+    }, /compact\/end sourceCommandId must be a non-empty string/],
     ['success without summary', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
-      session.append('compact/end', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     }, /requires one compact\/summary/],
   ])('rejects %s', async (_name, action, message) => {
     const ctx = await setup()
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index fcdcd7c422..585397d861 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -196,11 +196,15 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
 }
 
 function stubToolExecution(
-  input: Omit<ToolExecution, 'token'> & { token?: ToolExecutionToken },
+  input: Omit<ToolExecution, 'token' | 'rootCallId'> & {
+    token?: ToolExecutionToken
+    rootCallId?: ToolExecution['rootCallId']
+  },
 ): ToolExecution {
   return {
     token: input.token ?? Symbol('workspace-context-test-execution') as ToolExecutionToken,
     ...input,
+    rootCallId: input.rootCallId ?? input.callId,
   }
 }
 
diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts
index 06993467e8..2f3454b03c 100644
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -785,11 +785,11 @@ describe('the run_code dispatch bridge', () => {
     const dispatches = events.filter(event => event.type === 'tool/code-dispatch')
     expect(dispatches.map(event => event.data)).toEqual([
       {
-        parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo',
+        rootCallId: 'call-1', parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo',
         arguments: { value: 'one' }, isError: false, content: [{ type: 'text', text: 'echo:one' }],
       },
       {
-        parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo',
+        rootCallId: 'call-1', parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo',
         arguments: { value: 'two' }, isError: false, content: [{ type: 'text', text: 'echo:two' }],
       },
     ])
@@ -1526,6 +1526,7 @@ describe('the run_code dispatch bridge', () => {
       content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
     }), { surfaceOp: 'append' })
     session.append('tool/code-dispatch', {
+      rootCallId: CallId('p1'),
       parentCallId: CallId('p1'),
       subCallId: CallId('p1:code:1'),
       name: 'echo',
diff --git a/packages/core/tools/tests/invariant.spec.ts b/packages/core/tools/tests/invariant.spec.ts
index 80ae299da7..8a60c41331 100644
--- a/packages/core/tools/tests/invariant.spec.ts
+++ b/packages/core/tools/tests/invariant.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import * as ToolsInvariant from '@deepseek-ai/dsh-tools/invariant'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -24,6 +24,7 @@ const execution = (overrides: Partial<ToolExecution> = {}): ToolExecution => ({
   arguments: Object.freeze({ text: 'hi' }),
   ...overrides,
   signal: overrides.signal ?? testToolSignal,
+  rootCallId: overrides.rootCallId ?? overrides.callId ?? CallId('call-1'),
 })
 
 const outcome = (): ToolExecutionResult => Object.freeze({
@@ -92,6 +93,7 @@ describe('tool-pipeline invariants', () => {
     const ctx = await setup()
     const session = ctx.sessions.create()
     const data = {
+      rootCallId: CallId('parent'),
       parentCallId: CallId('parent'),
       subCallId: CallId('child'),
       name: 'echo',
@@ -103,12 +105,112 @@ describe('tool-pipeline invariants', () => {
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
   })
 
+  it('does not commit a rejected dispatch edge into the root index', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('rejected-root'),
+      parentCallId: CallId('rejected-root'),
+      subCallId: CallId('reused-child'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/outside any open turn/)
+
+    session.append('turn/start', { turn: 1 })
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('accepted-root'),
+      parentCallId: CallId('accepted-root'),
+      subCallId: CallId('reused-child'),
+      name: 'echo',
+      arguments: {},
+    })).not.toThrow()
+  })
+
+  it('rejects a nested code dispatch that changes its parent chain root before append', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1 })
+    session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('root'),
+      parentCallId: CallId('root'),
+      subCallId: CallId('child'),
+      name: 'run_code',
+      arguments: {},
+    })
+    session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('root'),
+      parentCallId: CallId('child'),
+      subCallId: CallId('grandchild'),
+      name: 'echo',
+      arguments: {},
+    })
+
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('another-root'),
+      parentCallId: CallId('child'),
+      subCallId: CallId('invalid-grandchild'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/parentCallId child does not belong to rootCallId another-root/)
+    expect(session.events.some(event => event.type === 'tool/code-dispatch-start'
+      && String(event.data.subCallId) === 'invalid-grandchild')).toBe(false)
+  })
+
+  it('requires non-empty dispatch identities and keeps one subcall on one root', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1 })
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId(''),
+      parentCallId: CallId('root'),
+      subCallId: CallId('child'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/must carry non-empty rootCallId/)
+
+    session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('root'),
+      parentCallId: CallId('root'),
+      subCallId: CallId('child'),
+      name: 'echo',
+      arguments: {},
+    })
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('other-root'),
+      parentCallId: CallId('other-root'),
+      subCallId: CallId('child'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/changed rootCallId for subCallId child/)
+  })
+
+  it('indexes dispatch records emitted for a bare session', async () => {
+    const ctx = await setup()
+    const session = Session.create(SessionId('bare-dispatch-session'))
+    session.append('turn/start', { turn: 1 })
+    expect(() => {
+      ctx.emit('session/event', session as never, {
+        type: 'tool/code-dispatch-start',
+        seq: 1,
+        time: 1,
+        data: {
+          rootCallId: CallId('root'),
+          parentCallId: CallId('root'),
+          subCallId: CallId('child'),
+          name: 'echo',
+          arguments: {},
+        },
+      } as never)
+    }).not.toThrow()
+  })
+
   it('replays enclosed code-dispatch records on late registration', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1 })
     session.append('tool/code-dispatch', {
+      rootCallId: CallId('parent'),
       parentCallId: CallId('parent'),
       subCallId: CallId('child'),
       name: 'echo',
@@ -125,6 +227,7 @@ describe('tool-pipeline invariants', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     ctx.sessions.create().append('tool/code-dispatch-start', {
+      rootCallId: CallId('parent'),
       parentCallId: CallId('parent'),
       subCallId: CallId('child'),
       name: 'echo',
diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
index 3224487b60..5757e5f245 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -574,6 +574,7 @@ describe('dsh-agent-spine-demo bundle', () => {
       signal: testToolSignal,
       token: Symbol('agent-core-dsh-home-test') as ToolExecution['token'],
       callId: CallId('agent-core-dsh-home'),
+      rootCallId: CallId('agent-core-dsh-home'),
       name: 'bash',
       arguments: { command: 'true' },
     }
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
index 1c478b226b..33ac3a19fa 100644
--- a/packages/llm/llm-retry/tests/invariant.spec.ts
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -5,6 +5,7 @@ import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
 import { providerForOpenStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
@@ -38,6 +39,7 @@ function appendRetryTurn(session: Session, turn: number) {
 
 const failure = { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }
 const normal = {
+  retryId: RetryId('normal-retry-chain'),
   provider: 'mock',
   mode: 'normal' as const,
   policyKey: 'normal-policy',
@@ -47,6 +49,7 @@ const normal = {
   failure,
 }
 const always = {
+  retryId: RetryId('always-retry-chain'),
   provider: 'mock',
   mode: 'always' as const,
   policyKey: 'always-policy',
@@ -130,6 +133,7 @@ describe('llm-retry invariants', () => {
   })
 
   it.each([
+    ['empty-retry-id', { ...normal, retryId: RetryId('') }, /retryId must be a non-empty string/],
     ['retry-zero', { ...normal, retry: 0 }, /positive safe integer/],
     ['retry-fraction', { ...normal, retry: 1.5 }, /positive safe integer/],
     ['max-zero', { ...normal, maxRetries: 0 }, /positive safe maxRetries/],
@@ -212,10 +216,65 @@ describe('llm-retry invariants', () => {
     reset.append('step/end', { turn: 1, step: 1 })
     reset.append('step/start', { turn: 1, step: 2 })
     expect(() => {
-      reset.append('llm/retry', { turn: 1, step: 2, ...normal })
+      reset.append('llm/retry', {
+        turn: 1,
+        step: 2,
+        ...normal,
+        retryId: RetryId('reset-step-2-retry-chain'),
+      })
     }).not.toThrow()
   })
 
+  it('keeps one retry identity per provider-policy chain', async () => {
+    const ctx = await setup()
+    const changed = openStep(ctx, 'retry-invariant-changed-chain-id')
+    changed.append('llm/retry', { turn: 1, step: 1, ...normal })
+    expect(() => changed.append('llm/retry', {
+      turn: 1,
+      step: 1,
+      ...normal,
+      retry: 2,
+      retryId: RetryId('changed-retry-chain'),
+    })).toThrow(/must preserve retryId/)
+
+    const reused = openStep(ctx, 'retry-invariant-reused-chain-id')
+    reused.append('llm/retry', { turn: 1, step: 1, ...normal })
+    expect(() => reused.append('llm/retry', {
+      turn: 1,
+      step: 1,
+      ...always,
+      retryId: normal.retryId,
+    })).toThrow(/already owned by another chain/)
+  })
+
+  it('validates retry-started correlation and uniqueness', async () => {
+    const ctx = await setup()
+    const empty = openStep(ctx, 'retry-started-empty-id')
+    expect(() => empty.append('llm/retry-started', {
+      retryId: RetryId(''), turn: 1, step: 1, retry: 1,
+    })).toThrow(/retryId must be a non-empty string/)
+
+    const missing = openStep(ctx, 'retry-started-missing-schedule')
+    expect(() => missing.append('llm/retry-started', {
+      retryId: RetryId('missing-retry-chain'), turn: 1, step: 1, retry: 1,
+    })).toThrow(/pairs no prior scheduled attempt/)
+
+    const mismatch = openStep(ctx, 'retry-started-location-mismatch')
+    mismatch.append('llm/retry', { turn: 1, step: 1, ...normal })
+    expect(() => mismatch.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 2, step: 1, retry: 1,
+    })).toThrow(/turn\/step must match/)
+
+    const repeated = openStep(ctx, 'retry-started-repeated')
+    repeated.append('llm/retry', { turn: 1, step: 1, ...normal })
+    repeated.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 1, step: 1, retry: 1,
+    })
+    expect(() => repeated.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 1, step: 1, retry: 1,
+    })).toThrow(/repeats one scheduled attempt/)
+  })
+
   it('starts a fresh retry chain after incomplete predecessor boundaries', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -261,4 +320,16 @@ describe('llm-retry invariants', () => {
     await ctx.plugin(InvariantService)
     await expect(ctx.plugin(RetryInvariant)).rejects.toThrow(/inside an open turn/)
   })
+
+  it('accepts a scheduled and started attempt on late registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = openStep(ctx, 'retry-invariant-late-started')
+    session.append('llm/retry', { turn: 1, step: 1, ...normal })
+    session.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 1, step: 1, retry: 1,
+    })
+    await ctx.plugin(InvariantService)
+    await expect(ctx.plugin(RetryInvariant)).resolves.toBeDefined()
+  })
 })
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 36a1fb5dbe..3a605bd40e 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -6,6 +6,7 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
 import type {} from '../src/index.ts'
 
 const dirs: string[] = []
@@ -39,6 +40,7 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind)
         reason: 'initial',
       })
       const event = session.append('llm/retry', {
+        retryId: RetryId(`retry-${kind}-chain`),
         turn: 1,
         step: 1,
         provider: 'mock',
diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts
index ac0ed687fa..7268c19ec6 100644
--- a/packages/llm/llm-retry/tests/retry.spec.ts
+++ b/packages/llm/llm-retry/tests/retry.spec.ts
@@ -191,7 +191,9 @@ describe('provider-routed retry policy', () => {
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     const event = await scheduled
 
+    expect(event.data.retryId).toEqual(expect.any(String))
     expect(event.data).toEqual({
+      retryId: event.data.retryId,
       turn: 1,
       step: 1,
       provider: 'mock',
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index 20cb2cc819..9251eef2c0 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -10,6 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
+import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
 import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
 import {
   estimateContent,
@@ -59,6 +60,7 @@ function appendSummaryMeter(ctx: Context, session: Session, start: number, end:
   const endIdx = nodes.findIndex(node => node.seq === end)
   const shadowed = nodes.slice(startIdx, endIdx + 1)
   session.append('compact/summary', {
+    compactionId: CompactionId('context-breakdown-summary'),
     summary: [{ type: 'text', text: 'summary' }],
     shadowedRange: { start, end },
     shadowedSeqs: shadowed.map(node => node.seq),
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index 0307b96f46..65771fc877 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -7,6 +7,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
+import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
 
 const ZERO: TokenUsageProjection = {
   uncachedInputTokens: 0,
@@ -81,6 +82,7 @@ function appendSummaryMeter(ctx: Context, session: Session, start: number, end:
   const endIdx = nodes.findIndex(node => node.seq === end)
   const shadowed = nodes.slice(startIdx, endIdx + 1)
   session.append('compact/summary', {
+    compactionId: CompactionId('token-usage-summary'),
     summary: [{ type: 'text', text: 'summary' }],
     shadowedRange: { start, end },
     shadowedSeqs: shadowed.map(node => node.seq),
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index ef97c945c9..b52000f554 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -277,8 +277,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Consider automatic compaction for one explicit trigger. Pressure policy\n * uses the latest durable routed request, while context-overflow policy may\n * force a useful balanced reduction even below the normal threshold. Return\n * `null` when no safe range can be compacted. A single oversized retained\n * unit or request envelope cannot be repaired through surface compaction.\n *\n * @param agent - agent context owning the session surface and routing options.\n * @param trigger - normal pressure or provider-confirmed context overflow.\n * @param signal - cancellation signal; model-backed implementations must forward it.\n * @returns the compaction result, or `null` if no compaction was needed.\n */',
       },
       {
-        signature: 'abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>',
-        jsDoc: '/**\n * Explicitly compact useful history even below automatic pressure thresholds.\n * Implementations synchronously start an idle task before any asynchronous\n * work, select a useful range without writing on a no-op, then\n * append a standalone `compact/start` before summarization. That durable\n * marker is the compaction lock until one `compact/end` attempt. Later waking\n * prompts remain accepted in FIFO order and start only after the optional\n * durability checkpoint and idle-task settlement. Context injected while the\n * summary runs may sit between the marker pair; only the selected span must\n * remain stable.\n *\n * @param agent - idle agent whose durable history should be compacted.\n * @param signal - cancellation scoped to this compaction request.\n * @returns the compaction result, or `null` when no safe useful range exists.\n * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,\n * changed-span, summarization/shrink, commit-stage, or persistence failures;\n * an aborted request preserves its exact abort reason. Failed attempts remain\n * visible in the log.\n */',
+        signature: 'abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>',
+        jsDoc: '/**\n * Explicitly compact useful history even below automatic pressure thresholds.\n * Implementations synchronously start an idle task before any asynchronous\n * work, select a useful range without writing on a no-op, then\n * append a standalone `compact/start` before summarization. That durable\n * marker is the compaction lock until one `compact/end` attempt. Later waking\n * prompts remain accepted in FIFO order and start only after the optional\n * durability checkpoint and idle-task settlement. Context injected while the\n * summary runs may sit between the marker pair; only the selected span must\n * remain stable.\n *\n * @param agent - idle agent whose durable history should be compacted.\n * @param signal - cancellation scoped to this compaction request.\n * @param sourceCommandId - initiating command identity for a manual compaction.\n * @returns the compaction result, or `null` when no safe useful range exists.\n * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,\n * changed-span, summarization/shrink, commit-stage, or persistence failures;\n * an aborted request preserves its exact abort reason. Failed attempts remain\n * visible in the log.\n */',
       },
       {
         signature: 'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
@@ -1841,7 +1841,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CommandInvocation',
-    declaration: 'export interface CommandInvocation {\n    readonly agent: Agent;\n    readonly rawInput: string;\n    readonly signal: AbortSignal;\n}',
+    declaration: 'export interface CommandInvocation {\n    readonly commandId: CommandId;\n    readonly agent: Agent;\n    readonly rawInput: string;\n    readonly signal: AbortSignal;\n}',
   },
   {
     name: 'CommandResult',
@@ -1851,9 +1851,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CompactAgentContext',
     declaration: 'export interface CompactAgentContext {\n    session: Session;\n    options: {\n        provider?: string;\n        model?: string;\n    };\n}',
   },
+  {
+    name: 'CompactionId',
+    declaration: 'export type CompactionId = Branded<\'CompactionId\'>;',
+  },
   {
     name: 'CompactionResult',
-    declaration: 'export interface CompactionResult {\n    startSeq: number;\n    summarySeq: number;\n    endSeq: number;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: number;\n        end: number;\n    };\n    shadowedSeqs: number[];\n    shadowedTokenCount: number;\n}',
+    declaration: 'export interface CompactionResult {\n    compactionId: CompactionId;\n    sourceCommandId?: CommandId;\n    startSeq: number;\n    summarySeq: number;\n    endSeq: number;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: number;\n        end: number;\n    };\n    shadowedSeqs: number[];\n    shadowedTokenCount: number;\n}',
   },
   {
     name: 'CompactionTrigger',
@@ -3065,7 +3069,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecution',
-    declaration: 'export interface ToolExecution extends ToolExecutionInput {\n    readonly token: ToolExecutionToken;\n}',
+    declaration: 'export interface ToolExecution extends ToolExecutionInput {\n    readonly rootCallId: CallId;\n    readonly token: ToolExecutionToken;\n}',
   },
   {
     name: 'ToolExecutionFailure',
@@ -3073,7 +3077,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecutionInput',
-    declaration: 'export interface ToolExecutionInput {\n    readonly callId: CallId;\n    readonly name: string;\n    readonly arguments: unknown;\n    readonly agent?: Agent;\n    readonly parent?: ToolExecutionToken;\n    readonly signal: AbortSignal;\n}',
+    declaration: 'export interface ToolExecutionInput {\n    readonly callId: CallId;\n    readonly rootCallId?: CallId;\n    readonly name: string;\n    readonly arguments: unknown;\n    readonly agent?: Agent;\n    readonly parent?: ToolExecutionToken;\n    readonly signal: AbortSignal;\n}',
   },
   {
     name: 'ToolExecutionMode',
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index efdab32824..0276199e3e 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
 import LlmService, { CallId, createUserMessage, GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
 import {
   type ReplayEntry,
@@ -35,6 +36,8 @@ const TEXT_CHUNKS: StreamChunk[] = [
   { type: 'finish', reason: { kind: 'stop' } },
 ]
 
+const COMPACTION_ID = CompactionId('replay-compaction')
+
 /** Build a minimal session-JSONL string: a header line + the given events. */
 function sessionJsonl(events: SessionEvent[], header?: { id?: string; createdAt?: number; seedLength?: number }): string {
   const headerLine = JSON.stringify({
@@ -194,12 +197,18 @@ describe('deriveReplayScript', () => {
     let seq = 1
     const events: SessionEvent[] = [
       ...overflow.map(chunk => chunkEvent(seq++, 1, 2, chunk)),
-      { type: 'compact/start', seq: seq++, time: 0, data: { turn: 1 } },
+      {
+        type: 'compact/start',
+        seq: seq++,
+        time: 0,
+        data: { compactionId: COMPACTION_ID, turn: 1 },
+      },
       {
         type: 'compact/summary',
         seq: seq++,
         time: 0,
         data: {
+          compactionId: COMPACTION_ID,
           summary: rawOutput,
           rawOutput,
           llmStreamCall: true,
@@ -227,6 +236,7 @@ describe('deriveReplayScript', () => {
       seq: 1,
       time: 0,
       data: {
+        compactionId: COMPACTION_ID,
         summary: [{ type: 'text', text: 'template result' }],
         shadowedRange: { start: 1, end: 1 },
         shadowedSeqs: [1],
@@ -246,6 +256,7 @@ describe('deriveReplayScript', () => {
       seq: 1,
       time: 0,
       data: {
+        compactionId: COMPACTION_ID,
         summary: [block],
         rawOutput: [block],
         shadowedRange: { start: 1, end: 1 },
@@ -267,6 +278,7 @@ describe('deriveReplayScript', () => {
         seq: 1,
         time: 0,
         data: {
+          compactionId: COMPACTION_ID,
           summary: [{ type: 'text', text: 'missing source events' }],
           llmStreamCall: true,
           shadowedRange: { start: 1, end: 1 },
@@ -289,6 +301,7 @@ describe('deriveReplayScript', () => {
       seq: 1,
       time: 0,
       data: {
+        compactionId: COMPACTION_ID,
         summary: [block],
         rawOutput: [block],
         llmStreamCall: true,
@@ -343,6 +356,7 @@ describe('deriveReplayScript', () => {
         seq: 2,
         time: 0,
         data: {
+          compactionId: COMPACTION_ID,
           summary: [{ type: 'text', text: 'external checkpoint' }],
           shadowedRange: { start: 1, end: 1 },
           shadowedSeqs: [1],
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index da3703e5ff..f1ee272761 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1504,9 +1504,6 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../../interaction/commands
-      '@deepseek-ai/dsh-compact':
-        specifier: workspace:^
-        version: link:../../compact/compact
       '@deepseek-ai/dsh-host-apiproxy':
         specifier: workspace:^
         version: link:../../host/apiproxy
@@ -1680,6 +1677,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../../goal/goal
@@ -2670,6 +2670,12 @@ importers:
 
   packages/compact/compact:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -2704,6 +2710,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop-testkit':
         specifier: workspace:^
         version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../compact
@@ -4391,6 +4400,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop-testkit':
         specifier: workspace:^
         version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index fffde3ceb8..51fdc06f61 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -278,6 +278,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   CreateGoalResult: 'goal.md',
   CommandDefinition: 'commands.md',
   CommandDescriptor: 'commands.md',
+  CommandId: 'commands.md',
   CommandResult: 'commands.md',
   CommandSurface: 'commands.md',
   LlmAdapter: 'llm-streaming.md',

From 8723a0e15f791f4403327f809eb43bedc748f43d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:02:20 +0800
Subject: [PATCH 236/262] fix(client): address conversation assembly review
 findings

---
 .../client/sessions/conversation-assembler.ts | 12 ++--
 .../runtime/src/client/sessions/session.ts    |  1 +
 .../tests/conversation-assembler.spec.ts      | 67 +++++++++++++++++++
 .../client/conversation-nodes/turn-tail.ts    | 19 +++++-
 .../ui-conversation/src/client/index.ts       | 21 +++---
 .../conversation-node-definitions.spec.ts     | 26 ++++++-
 scripts/gen-cordis-catalog.ts                 |  2 +
 7 files changed, 128 insertions(+), 20 deletions(-)

diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
index 3b6fbd6266..3a0c94ba3c 100644
--- a/packages/client/runtime/src/client/sessions/conversation-assembler.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -238,7 +238,7 @@ export class ConversationNodeAssembler {
     }
     this.applyPendingMatches(pending, affected)
     this.replayContexts(affected)
-    if ((fresh.length > 0 || previousHasMore !== hasMore) && this.replayDependencies()) {
+    if ((this.revised.size > 0 || previousHasMore !== hasMore) && this.replayDependencies()) {
       publication = 'immediate'
     }
     if (changedLocations.size > 0) publication = 'immediate'
@@ -563,18 +563,18 @@ export class ConversationNodeAssembler {
 
   private replayRevisedDependents(): boolean {
     const pending = [...this.revised]
-    const replayed = new Set<InternalContext>()
+    const affected = new Set<InternalContext>()
     for (let index = 0; index < pending.length; index++) {
       const dependency = pending[index]
       if (dependency === undefined) continue
       for (const dependent of this.dependents.get(dependency.key) ?? []) {
-        if (replayed.has(dependent)) continue
-        replayed.add(dependent)
-        this.replayContext(dependent)
+        if (affected.has(dependent)) continue
+        affected.add(dependent)
         pending.push(dependent)
       }
     }
-    return replayed.size > 0
+    this.replayContexts(affected)
+    return affected.size > 0
   }
 
   private readerFor(
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index a533f9dd6f..7c3d989248 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -344,6 +344,7 @@ export class Session implements SessionFace {
         // §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
         console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
         this.hasMore = false
+        this.conversation.prepend([], false)
         return
       }
       this.events = [...older.map(e => e.event), ...this.events]
diff --git a/packages/client/runtime/tests/conversation-assembler.spec.ts b/packages/client/runtime/tests/conversation-assembler.spec.ts
index 6f4d8516dc..06dfd42567 100644
--- a/packages/client/runtime/tests/conversation-assembler.spec.ts
+++ b/packages/client/runtime/tests/conversation-assembler.spec.ts
@@ -458,6 +458,73 @@ describe('ConversationNodeAssembler', () => {
     expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(2)
   })
 
+  it('replays a transitive dependency closure in start order', () => {
+    const sourceA: ConversationNodeDefinition<number> = {
+      kind: 'diamond-a',
+      match: (event) => {
+        if (event.type === 'user/message') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'diamond/a') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => 1,
+      update: (_context, match) => (match.event.data as unknown as { value: number }).value,
+      buildViewNode: () => null,
+    }
+    const sourceX: ConversationNodeDefinition<number> = {
+      kind: 'diamond-x',
+      match: (event) => {
+        if (event.type === 'turn/start') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'diamond/x') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => 10,
+      update: (_context, match) => (match.event.data as unknown as { value: number }).value,
+      buildViewNode: () => null,
+    }
+    const middle: ConversationNodeDefinition<number> = {
+      kind: 'diamond-b',
+      match: event => event.type === 'assistant/message'
+        ? { id: 'one', role: 'start' }
+        : null,
+      start: (_context, _match, reader) => (
+        (reader.previous<number>('diamond-a')?.state ?? 0)
+        + (reader.previous<number>('diamond-x')?.state ?? 0)
+      ),
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'diamond-c',
+      match: event => event.type === 'tool/call'
+        ? { id: 'one', role: 'start' }
+        : null,
+      start: (_context, _match, reader) => (
+        (reader.previous<number>('diamond-a')?.state ?? 0) * 100
+        + (reader.previous<number>('diamond-b')?.state ?? 0)
+      ),
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([sourceA, sourceX, middle, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
+      input(at(2, 'turn/start', { turn: 1 })),
+      input(at(3, 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
+      input(at(4, 'tool/call', { turn: 1, step: 1, callId: 'call', name: 'x', arguments: '{}' })),
+    ], false)
+
+    assembler.append(input(at(5, 'diamond/x', { value: 20 })))
+    assembler.append(input(at(6, 'diamond/a', { value: 2 })))
+    assembler.flush()
+
+    const value = [...chatSnapshot(assembler)?.nodes.values() ?? []]
+      .find(candidate => candidate.kind === 'diamond-c')
+    expect(value?.data).toBe(222)
+  })
+
   it('replays Location-derived State and rebuilds only owned Nodes when a step closes', () => {
     const apply = vi.fn()
     const starts = vi.fn((
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
index 2a842a005d..346bd41bdf 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -122,14 +122,26 @@ function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChat
     .filter((candidate): candidate is Readonly<FinalAssistantChatData> => candidate.finalNode !== undefined)
     .sort((left, right) => left.finalNode.seq - right.finalNode.seq)
   const closing = finalized.findLast(hasText) ?? null
-  const latest = finalized.at(-1)
+  let latestTranscriptSeq = finalized.at(-1)?.finalNode.seq
+  for (const match of context.matches) {
+    const event = match.event
+    const candidate = event.type === 'tool/call'
+      || (event.type === 'tool/result' && isAppendSurfaceEvent(event))
+      || (event.type === 'turn/end' && event.data.reason.kind === 'error')
+      || (event.type as string) === 'llm/retry'
+      ? event.seq
+      : undefined
+    if (candidate !== undefined && (latestTranscriptSeq === undefined || candidate > latestTranscriptSeq)) {
+      latestTranscriptSeq = candidate
+    }
+  }
   const metrics = deriveTurnMetrics(finalized.map(candidate => candidate.finalNode)).get(end.event.data.turn)
   return {
     turn: end.event.data.turn,
     seq: end.event.seq,
     time: end.event.time,
     closing,
-    branchUnavailable: closing === null || latest?.finalNode.seq !== closing.finalNode.seq,
+    branchUnavailable: closing === null || latestTranscriptSeq !== closing.finalNode.seq,
     ...metrics?.ttftMs === undefined ? {} : { ttftMs: metrics.ttftMs },
     ...metrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: metrics.tokensPerSecond },
   }
@@ -141,6 +153,9 @@ export const turnTailDefinition: ConversationNodeDefinition<TurnTailState> = {
   match: (event) => {
     if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
     if (event.type === 'turn/end') return { id: String(event.data.turn), role: 'update' }
+    if (event.type === 'tool/call' || event.type === 'tool/result') {
+      return { id: String(event.data.turn), role: 'update' }
+    }
     const coordinates = turnCoordinates(event)
     if (coordinates !== undefined) return { id: String(coordinates.turn), role: 'update' }
     return null
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index b4d7467170..e0471623f0 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -3,19 +3,18 @@
  * between the independently implemented skeleton and chat domains; `apply.ts`
  * owns their slot assembly.
  */
+export type {} from './conversation-nodes/assistant.ts'
+export type {} from './conversation-nodes/command.ts'
+export type {} from './conversation-nodes/compaction.ts'
+export type {} from './conversation-nodes/fallback.ts'
+export type {} from './conversation-nodes/message.ts'
+export type {} from './conversation-nodes/retry.ts'
+export type {} from './conversation-nodes/tool.ts'
+export type {} from './conversation-nodes/turn-error.ts'
+export type {} from './conversation-nodes/turn-tail.ts'
+
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
-export { registerAssistantConversationNode } from './conversation-nodes/assistant.ts'
-export { registerChatConversationView } from './conversation-nodes/chat-snapshot-builder.ts'
-export { registerCommandConversationNode } from './conversation-nodes/command.ts'
-export { registerCompactionConversationNode } from './conversation-nodes/compaction.ts'
-export { registerUnknownConversationFallback } from './conversation-nodes/fallback.ts'
-export { registerInboxConversationNodes } from './conversation-nodes/inbox.ts'
-export { registerMessageConversationNode } from './conversation-nodes/message.ts'
-export { registerRetryConversationNode } from './conversation-nodes/retry.ts'
-export { registerToolConversationNode } from './conversation-nodes/tool.ts'
-export { registerTurnErrorConversationNode } from './conversation-nodes/turn-error.ts'
-export { registerTurnTailConversationNode } from './conversation-nodes/turn-tail.ts'
 export type { IConversation } from './service.ts'
 
 export type {
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 3ae906087e..5346ad57f9 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -16,7 +16,7 @@ import { toolDefinition } from '../src/client/conversation-nodes/tool.ts'
 import { turnErrorDefinition } from '../src/client/conversation-nodes/turn-error.ts'
 import { turnTailDefinition } from '../src/client/conversation-nodes/turn-tail.ts'
 import type {
-  AssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData,
+  AssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData, TurnTailChatData,
 } from '../src/client/contract/chat-nodes.ts'
 
 const DEFINITIONS: readonly ConversationNodeDefinition[] = [
@@ -413,6 +413,30 @@ describe('built-in conversation node Definitions', () => {
     ])
   })
 
+  it('keeps branching unavailable when a tool result follows the closing Assistant', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('assistant-before-tool', 'running a tool'),
+      }, { surfaceOp: 'append' }),
+      at(4, 'tool/call', { turn: 1, step: 1, callId: 'late-tool', name: 'read', arguments: '{}' }),
+      at(5, 'tool/result', {
+        turn: 1,
+        step: 1,
+        message: toolResult('late-tool', 'done'),
+      }, { surfaceOp: 'append' }),
+      at(6, 'step/end', { turn: 1, step: 1 }),
+      at(7, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+
+    const tail = node(snapshot(value), 'turn-tail')?.data as TurnTailChatData
+    expect(tail.closing?.finalNode.seq).toBe(3)
+    expect(tail.branchUnavailable).toBe(true)
+  })
+
   it('replays inbox predecessors after prepend and reclassifies the dependent message as steering', () => {
     const value = assembler([
       at(3, 'user/message', textMessage('steer-1', 'change direction'), { surfaceOp: 'append' }),
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 51fdc06f61..662ad1df13 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -121,6 +121,8 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the surface',
   command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the surface',
   conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the surface',
+  conversationEvents: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
+  conversationViews: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
   layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the surface',
   locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the surface',
   models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the surface',

From 990f700d3cd4c977a5cb1788ef7c9c5d138f918a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:28:42 +0800
Subject: [PATCH 237/262] fix(client): address conversation assembly review
 feedback

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 ++--
 ...08-09-client-conversation-node-assembly.md | 10 ++++----
 ...09-client-conversation-node-assembly.zh.md | 10 ++++----
 packages/client/runtime/README.i18n.yaml      |  4 ++--
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../client/sessions/conversation-assembler.ts |  2 ++
 .../src/client/sessions/conversation.ts       | 24 ++++++++++++-------
 .../client/ui-conversation/README.i18n.yaml   |  4 ++--
 packages/client/ui-conversation/README.md     |  4 ++--
 packages/client/ui-conversation/README.zh.md  |  4 ++--
 .../src/client/contract/slots.ts              |  9 ++++---
 .../client/conversation-nodes/assistant.ts    |  4 ++--
 .../chat-snapshot-builder.ts                  |  5 +++-
 .../src/client/conversation-nodes/common.ts   | 10 ++++++++
 .../src/client/conversation-nodes/tool.ts     |  4 ++--
 .../client/conversation-nodes/turn-tail.ts    |  8 ++++---
 packages/client/ui-tool/README.i18n.yaml      |  4 ++--
 packages/client/ui-tool/README.md             |  4 ++--
 packages/client/ui-tool/README.zh.md          |  4 ++--
 20 files changed, 73 insertions(+), 49 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index 953a049744..264b900b74 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 0cee5449f651c568dbb87b9cb867eb77b6380184
-2026-08-09-client-conversation-node-assembly.zh.md: 146e8f68a9b1339934040cee62fd46e981145f2a
+2026-08-09-client-conversation-node-assembly.md: f9768a652c7b0d2d29939fac83b201bc904e3210
+2026-08-09-client-conversation-node-assembly.zh.md: 408d61f73b3b317214cb10b26f522e7680de3f92
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 0cee5449f6..f9768a652c 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -148,7 +148,7 @@ The Assembler verifies `node.key === context.key` and `node.target === target`.
 
 `current` lets a Definition distinguish "never materialized" from "already materialized and now hidden." Assistant retry and Turn Error suppression use it to avoid illegal Node withdrawal.
 
-A Definition may branch by target to construct different data, while matching, Context identity, and State remain target-neutral. This change registers only the `chat` builder; Trajectory continues to consume the compatibility slice.
+A Definition may branch by target to construct different data, while matching, Context identity, and State remain target-neutral. This change registers only the `chat` builder; Trajectory remains on its independent `session-history` fold until it gains a registered target.
 
 #### No generic `end()`
 
@@ -306,7 +306,7 @@ Unknown fallback demonstrates Registry ownership: it handles only append-surface
 
 The Assembler calls `replace({ nodes, timeline })` on low-frequency complete replacements and `apply({ upserts, timeline })` for ordinary prepend/append flushes. Builders receive only final target Nodes already constructed by Definitions.
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice temporarily consumed by Trajectory.
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice used by StatsLine and mirrored into top-level public compatibility fields.
 
 Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces only that key's value.
 
@@ -328,7 +328,7 @@ When business logic deliberately changes a materialized Node to hidden, it leave
 
 The concrete Tool renderer remains governed by the [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md). Tool Definition supplies recursive root/subcall data, and `ui-tool` dispatches concrete presentation by the Tool-name keyed slot.
 
-Trajectory has no independent registered target yet. It continues to consume the legacy slice incrementally derived by the Chat Builder, while Session no longer runs a second transcript fold; a future migration does not change the Event Definition, Context, Reader, or Location contracts.
+Trajectory has no registered target and does not consume the Chat Builder's legacy slice. Its activated `SessionHistoryInspection` keeps an independent history fold, while the ordinary Session snapshot no longer runs a second transcript fold. The Chat Builder retains its legacy slice for StatsLine and the top-level public compatibility fields; a future Trajectory migration does not change the Event Definition, Context, Reader, or Location contracts.
 
 ## Runtime and render path
 
@@ -382,7 +382,7 @@ History-path tests cover complete replace, non-overlapping prepend, overlapping-
 
 **Add generic `end()`, prepared, or window-reset lifecycles.** Rejected: businesses have different completion conditions, and a pagination gap is not a business lifecycle. Business Events update State, Location close triggers replay/build, and Reader dependencies own pagination invalidation.
 
-**Register separate Event Definitions for Chat and Trajectory.** Rejected: identity, State, and Location are target-neutral. `buildViewNode(target)` and each Builder express view differences; Trajectory retains a compatibility slice until its actual migration.
+**Register separate Event Definitions for Chat and Trajectory.** Rejected: identity, State, and Location are target-neutral. `buildViewNode(target)` and each Builder express view differences; Trajectory's independent history fold remains until it registers its own Builder.
 
 **Add a generic layout model above final business Nodes.** Rejected: activity, tail candidacy, and layout enums would centralize current Chat business semantics in the engine again. Final Nodes carry renderer-required data directly and share only identity, ordering, and Location facts.
 
@@ -404,4 +404,4 @@ Steps and Turns become stable homes for cross-business aggregates. Turn Tail and
 
 The cost is new Runtime contracts for Registry, Assembler, Location data, dependency replay, and per-target Builders, plus parent-owned common inject and per-occurrence `hookContext` in UI Slots. Definition authors must understand stable IDs, unique starts, forward replay, Step→Turn publication order, read-only Reader access, and the prohibition on Node withdrawal.
 
-`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice until Trajectory migrates; built-in Definitions currently remain centralized in `ui-conversation`. These compatibility boundaries do not return business interpretation to Session.
+`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice for StatsLine and the top-level public fields, Trajectory still owns an independent history fold, and built-in Definitions currently remain centralized in `ui-conversation`. These compatibility boundaries do not return business interpretation to Session.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 146e8f68a9..408d61f73b 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -148,7 +148,7 @@ Assembler 校验 Node `key === context.key` 且 Node `target === target`。业
 
 `current` 让 Definition 区分“从未生成”与“已经生成后需要隐藏”。Assistant retry 和 Turn Error suppression 使用它避免非法的 Node 撤回。
 
-Definition 可以针对 target 分支构造不同 data，但匹配、Context identity 和 State 保持 target-neutral。本次只注册 `chat` builder，Trajectory 仍通过兼容 slice 使用结果。
+Definition 可以针对 target 分支构造不同 data，但匹配、Context identity 和 State 保持 target-neutral。本次只注册 `chat` builder；在拥有注册 target 之前，Trajectory 继续使用独立的 `session-history` fold。
 
 #### 不提供通用 `end()`
 
@@ -306,7 +306,7 @@ Unknown fallback 展示了 Registry ownership：fallback 只处理没有任何
 
 Assembler 低频完整替换时调用 `replace({ nodes, timeline })`；普通 prepend/append flush 调用 `apply({ upserts, timeline })`。Builder 只接收 Definition 已构造完成的 target Nodes。
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline` 和 Trajectory 临时使用的 `legacy` slice。
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline`，以及由 StatsLine 使用并镜像到顶层公共兼容字段的 `legacy` slice。
 
 Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value。
 
@@ -328,7 +328,7 @@ Assistant streaming 到 final、Tool running 到 settled 只更新同一个 Seat
 
 具体 Tool renderer 仍由 [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md) 约束。Tool Definition 只交付递归 root/subcall data，`ui-tool` 再按 Tool name keyed slot 分发具体表现。
 
-Trajectory 尚未注册独立 target。它继续消费 Chat Builder 增量派生的 legacy slice，Session 不再运行第二套 transcript fold；未来迁移不改变 Event Definition、Context、Reader 或 Location 契约。
+Trajectory 尚未注册 target，也不消费 Chat Builder 的 legacy slice。它已激活的 `SessionHistoryInspection` 继续维护独立 history fold，而普通 Session snapshot 不再运行第二套 transcript fold。Chat Builder 为 StatsLine 和顶层公共兼容字段保留 legacy slice；未来迁移 Trajectory 不改变 Event Definition、Context、Reader 或 Location 契约。
 
 ## Runtime and render path
 
@@ -382,7 +382,7 @@ Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏
 
 **增加通用 `end()`、prepared 或 window reset 生命周期。** 拒绝：不同业务完成条件不同，分页缺口也不是业务生命周期。业务 Event 更新 State，Location close 触发 replay/build，Reader dependency 负责补页失效。
 
-**为 Chat 与 Trajectory 注册两套 Event Definition。** 拒绝：identity、State 和 Location 与 target 无关。视图差异由 `buildViewNode(target)` 和各自 Builder 表达；Trajectory 在真正迁移前保留兼容 slice。
+**为 Chat 与 Trajectory 注册两套 Event Definition。** 拒绝：identity、State 和 Location 与 target 无关。视图差异由 `buildViewNode(target)` 和各自 Builder 表达；Trajectory 在注册自己的 Builder 之前继续使用独立 history fold。
 
 **在最终业务 Node 上再叠一层通用 layout model。** 拒绝：activity、tail candidacy 和 layout enum 会把当前 Chat 的业务语义重新集中到引擎。最终 Node 直接携带 renderer 所需 data，只共享 identity、排序和 Location 事实。
 
@@ -404,4 +404,4 @@ Step/Turn 成为业务间共享聚合的稳定宿主。Turn Tail 和 Deliverable
 
 代价是 Runtime 新增 Registry、Assembler、Location data、依赖重放和 per-target Builder 契约，UI Slots 也新增 parent-owned common inject 与 per-occurrence `hookContext`。Definition 作者必须理解稳定 ID、唯一 start、正序 replay、Step→Turn 发布顺序、只读 Reader 和 Node 不撤回规则。
 
-`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 在 Trajectory 迁移前仍维护 legacy slice；内建 Definitions 暂时集中在 `ui-conversation`。这些是兼容边界，不把业务解释权交还给 Session。
+`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 继续为 StatsLine 和顶层公共字段维护 legacy slice，Trajectory 继续拥有独立 history fold，内建 Definitions 暂时集中在 `ui-conversation`。这些是兼容边界，不把业务解释权交还给 Session。
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 4aed1d0f36..d47266cd8a 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: b2bb06e50ecd791d74cb609404dd219e5a21913e
-README.zh.md: 72cd99ac765875c828cc9163d978e0b8fb7f44e4
+README.md: 46a383f22032c8da7e4bb9b5fb445980661c670f
+README.zh.md: 73578a8f249472abfdd7c539e3eaee6de767ad60
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index b2bb06e50e..46a383f220 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -38,7 +38,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 Each `Session` gives its contiguous event window to a `ConversationNodeAssembler`. Plugins register business Definitions that map one event to a stable `{kind, id}`, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.
 
-`ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. `ConversationSnapshot.nodes`, `partial`, and `runningCalls` are compatibility slices derived from the same materialized Chat nodes for consumers that have not moved to `ConversationSnapshot.chat`; Session does not run a second business fold.
+`ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. StatsLine reads `ConversationSnapshot.chat.legacy.nodes`, while Session mirrors that legacy slice into the top-level `nodes`, `partial`, and `runningCalls` public compatibility fields without running a second business fold. Trajectory consumes neither compatibility surface; its activated `session-history` inspection keeps an independent fold until it gains its own registered target.
 
 The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the [client Tool presentation decision](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md).
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 72cd99ac76..73578a8f24 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -38,7 +38,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 每个 `Session` 都把连续事件窗口交给 `ConversationNodeAssembler`。插件注册业务 Definition，把单个事件映射为稳定的 `{kind, id}`，在唯一 start 事件处创建 State，折叠有关联的 update，再为已注册的视图目标构造最终节点。Assembler 负责 Context 索引、只读前序 Context 查询，以及引用稳定的 Turn/Step Location 索引。实时 append 只对每个 Definition 求值一次，并且只更新命中的 Context；加载更早分页时保留已有 Context 与节点身份，只匹配新 prepend 的事件，并重放前序依赖或 Location 事实发生变化的 Context。完整替换仅用于 open、resync 和 gap repair。
 
-`ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。`ConversationSnapshot.nodes`、`partial` 和 `runningCalls` 是从同一批已物化 Chat 节点派生的兼容切片，供尚未迁移到 `ConversationSnapshot.chat` 的消费者使用；Session 不再运行第二套业务 fold。
+`ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。StatsLine 读取 `ConversationSnapshot.chat.legacy.nodes`；Session 则把该 legacy slice 镜像到顶层 `nodes`、`partial` 和 `runningCalls` 公共兼容字段，无须运行第二套业务 fold。Trajectory 不消费这两种兼容表面；在它获得独立注册 target 之前，已激活的 `session-history` inspection 继续维护独立 fold。
 
 Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新只通知受影响的 node key；结构变化才重建顺序和 Location 成员关系；prepend 只增加行，不替换既有 keyed value。每个 Assistant chunk 都会更新 Definition State，但最多每个 animation frame 请求一次物化；final message 与 Turn/Step 关闭会立即发布。参见 [Client Tool 展示所有权决策](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md)。
 
diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
index 3a0c94ba3c..811bd43ebf 100644
--- a/packages/client/runtime/src/client/sessions/conversation-assembler.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -743,6 +743,8 @@ export class ConversationNodeAssembler {
         context.locationData[scope] = data
         if (data !== null) entries.push({ owner: context.key, data })
       }
+      // Turn publishers may read Step data from this same flush, so each phase
+      // installs the cumulative replacement before the next phase builds.
       this.locationIndex.replaceData(entries)
     }
   }
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 99daa7c8a5..628fe89aa8 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -1,7 +1,9 @@
 // ConversationSnapshot / ConversationNode: the only data shape the logic layer feeds the UI.
-// Immutability contract: every change swaps the top-level object; unchanged
-// substructures keep their references (the React.memo premise). callId/approvalId stay plain
-// string here (narrow to real brands when convenient).
+// Publication contract: every change swaps the top-level object; unchanged
+// substructures keep their references (the React.memo premise). Chat node and
+// Location stores are stable live readers, so old snapshots are not time-point
+// views. callId/approvalId stay plain string here (narrow to real brands when
+// convenient).
 
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
@@ -336,7 +338,10 @@ export interface PromptError {
   error: RpcError
 }
 
-/** Stable per-key reader for final Chat view Nodes. */
+/**
+ * Stable live per-key reader. An old ChatSnapshot observes later flushes
+ * through this store.
+ */
 export interface ChatNodeStore {
   /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
   get(key: string): ChatConversationViewNode | undefined
@@ -344,7 +349,10 @@ export interface ChatNodeStore {
   values(): readonly ChatConversationViewNode[]
 }
 
-/** Stable per-Location membership index for turn-local and step-local consumers. */
+/**
+ * Stable live Location index. An old ChatSnapshot observes later membership
+ * changes through this index.
+ */
 export interface ChatLocationNodeIndex {
   /** @param turn - owning turn. @returns ordered Chat Node keys in the turn. */
   getTurn(turn: number): readonly string[]
@@ -352,7 +360,7 @@ export interface ChatLocationNodeIndex {
   getStep(turn: number, step: number): readonly string[]
 }
 
-/** Temporary projection consumed by Trajectory and unmigrated readers. */
+/** Compatibility projection backing StatsLine and the legacy top-level snapshot fields. */
 export interface LegacyConversationSlice {
   readonly nodes: readonly ConversationNode[]
   readonly turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
@@ -361,7 +369,7 @@ export interface LegacyConversationSlice {
   readonly runningCalls: readonly RunningToolCall[]
 }
 
-/** Incremental Chat target snapshot: stable keyed stores plus structural order. */
+/** Incremental Chat publication with immutable order and stable live keyed readers. */
 export interface ChatSnapshot {
   readonly order: readonly string[]
   readonly nodes: ChatNodeStore
@@ -399,7 +407,7 @@ export interface ConversationSnapshot {
   sessionId: SessionId
   /** Final Chat target assembled from independently registered business Definitions. */
   chat: ChatSnapshot
-  /** Legacy Trajectory slice derived from the registered Chat Definitions. */
+  /** Legacy top-level compatibility field mirrored from the registered Chat Definitions. */
   nodes: readonly ConversationNode[]
   /** Exact in-window `turn/start` time and optional matching `turn/end` time. */
   turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 2066b22ec5..bb15c65029 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: 911bca28dcfb31b1d8ef9ea5458a0d2017d8b31d
-README.zh.md: 25574421bbcc3992188e378a49a69acf25744af7
+README.md: 3570e814609af0bc4e7d048a55205af756fae843
+README.zh.md: e37f867c72d83b47924e87261e6ee5ff8b374a6f
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 911bca28dc..3570e81460 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -20,7 +20,7 @@ Logged non-user messages render as a default-collapsed disclosure whose header n
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
-The chat view keeps Tool placement but delegates Tool presentation. It passes each ordered root call through `conversation.chat.tool`, and the details shell passes the selected call through `conversation.details.tool`. The assembled Web bundle fills the whole-Tool seat with [`ui-tool`](../ui-tool/README.md), which selects Runtime-projected Code Dispatch children and owns root/child composition, per-name dispatch, generic rendering, and render-intent cards; the details seat alone retains a raw-result fallback when that renderer is absent.
+The chat view keeps Tool placement but delegates Tool presentation. Each ordered `tool-call` Conversation Node dispatches through the matching key of `conversation.chat.node`, while the details shell passes the selected call through `conversation.details.tool`. The assembled Web bundle registers [`ui-tool`](../ui-tool/README.md) for that Chat Node key; it renders the Runtime-projected recursive root/child tree and owns per-name dispatch, generic rendering, and render-intent cards. The details seat alone retains a raw-result fallback when that renderer is absent.
 
 The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. An unretried terminal failure renders as a persistent inline status at its turn boundary, showing the display-safe durable message and optional error code without offering an action the Host cannot fulfill; AUTH copy never echoes provider-supplied credential fragments.
 
@@ -40,7 +40,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
-A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` contract — an absent service leaves the prose inert.
+A finished turn materializes one ordered `turn-tail` Conversation Node. Its engine-owned `TurnLocation` supplies the closing Assistant and Turn data; the renderer places the `conversation.chat.turnTail` chain before that node's IconActions and dispatches `TurnTailOwnerProps` containing the Turn, closing seq, and `openFile`. This package owns only the hole; `@deepseek-ai/dsh-client-ui-deliverables` accumulates mutation-tool `locations` into Turn data and owns the produced-files row, chip cap, and copy, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 25574421bb..e37f867c72 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -18,7 +18,7 @@
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
-聊天视图保留 Tool 的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体 Tool 席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
+聊天视图保留 Tool 的消息流位置，但委托其展示。每个已排序的 `tool-call` Conversation Node 都通过 `conversation.chat.node` 的同名 key 分发；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 为该 Chat Node key 注册 [`ui-tool`](../ui-tool/README.md)，由后者渲染 Runtime 已投影的递归 root/child 树，并负责按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
 
 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。
 
@@ -40,7 +40,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
-完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` 约定——service 缺席时正文保持死文本。
+完成的一轮会物化一个有序的 `turn-tail` Conversation Node。它由引擎维护的 `TurnLocation` 提供收尾 Assistant 和 Turn data；renderer 在该 Node 的 IconActions 之前渲染 `conversation.chat.turnTail` chain，并派发包含 Turn、收尾 seq 和 `openFile` 的 `TurnTailOwnerProps`。本包只拥有空位；`@deepseek-ai/dsh-client-ui-deliverables` 把改写工具的 `locations` 累积到 Turn data，并拥有产物行、chip 上限和文案，因此把该插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` seam——service 缺席时正文保持死文本。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 474e7f9db5..eec5450e2d 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -56,11 +56,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      */
     'conversation.chat.commandview': { kind: 'keyed'; scope: 'session'; owner: CommandRowOwnerProps }
     /**
-     * The chat view's turn-tail chain: rendered between a closing assistant
-     * message's body and its IconActions footer, once per turn (the render
-     * site elects the closing seq). Entries derive a match from the owner
-     * currency before mounting, so presentation components never mount only
-     * to return null; an all-declined chain renders nothing.
+     * The completed Turn Node's extension chain, rendered before that Node's
+     * IconActions. Entries derive a match from the engine-owned Turn and
+     * closing seq before mounting, so presentation components never mount
+     * only to return null; an all-declined chain renders nothing.
      */
     'conversation.chat.turnTail': { kind: 'chain'; scope: 'session'; owner: TurnTailOwnerProps }
     /** Selected Tool call output inside the details panel. */
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
index 2bdf960226..8a487c89ed 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
@@ -7,7 +7,7 @@ import {
   emptyAssistantBlock, isAppendSurfaceEvent, isTokenDelta, toAssistantBlock, toAssistantBlocks,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { AssistantChatData } from '../contract/chat-nodes.ts'
-import { chatNode } from './common.ts'
+import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ChatNodeDataMap {
@@ -169,7 +169,7 @@ function finalNode(
   if (boundary === undefined || !hasInterruptionEvidence(blocks)) return undefined
   return {
     kind: 'assistant',
-    seq: boundary.seq - 0.9,
+    seq: boundary.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.interruptedAssistant,
     time: boundary.time,
     turn: state.turn,
     step: state.step,
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
index f9491d2d16..f417c33b75 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -154,6 +154,9 @@ const EMPTY_CONTRIBUTION: LegacyContribution = {
 
 function legacyContribution(raw: ChatConversationViewNode): LegacyContribution {
   const node = raw as ChatNode
+  // Content-free settled Assistants remain in the finalized compatibility
+  // stream so StatsLine preserves its pre-assembly step counts; hidden running
+  // attempts have no final Node to contribute.
   if (raw.visibility !== 'visible' && node.kind !== 'assistant-step') return EMPTY_CONTRIBUTION
   switch (node.kind) {
     case 'user':
@@ -221,7 +224,7 @@ function sameContribution(left: LegacyContribution | undefined, right: LegacyCon
     && sameReferences(left.nodes, right.nodes)
 }
 
-/** Incremental compatibility projection retained solely for unmigrated Trajectory consumers. */
+/** Incremental compatibility projection for StatsLine and legacy top-level snapshot fields. */
 class LegacySliceBuilder {
   private readonly contributions = new Map<string, LegacyContribution>()
   private readonly finalizedContributions = new Map<string, LegacyContribution>()
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/common.ts b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
index 8e1d9d7bd4..b6bd01930b 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
@@ -5,6 +5,16 @@ import type {
   ChatNode, ChatNodeDataMap, ChatNodeKind,
 } from '../contract/chat-nodes.ts'
 
+/**
+ * Relative positions in one durable event's seq neighborhood: interrupted
+ * Assistant, its follow-up Nodes, then follow-ups to an ordinary final.
+ */
+export const CHAT_SYNTHETIC_SEQ_OFFSETS = {
+  interruptedAssistant: -0.9,
+  interruptedFollowup: -0.8,
+  finalizedFollowup: 0.1,
+} as const
+
 /**
  * Resolve one Context's best currently loaded event Location.
  * @param context - assembled business Context.
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
index 04a5770f5a..23201fec3e 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -5,7 +5,7 @@ import type {
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolChatData } from '../contract/chat-nodes.ts'
-import { chatNode } from './common.ts'
+import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ChatNodeDataMap {
@@ -190,7 +190,7 @@ function projectBlock(
     ? sameReferences(block.subCalls, children) ? block : { ...block, subCalls: children }
     : {
       kind: 'tool-result',
-      seq: interruptedAt.seq - 0.8,
+      seq: interruptedAt.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.interruptedFollowup,
       time: interruptedAt.time,
       callId: block.callId,
       call: { name: block.name, argsRaw: block.argsRaw },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
index 346bd41bdf..51cb348e6a 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -7,7 +7,7 @@ import type {
   AssistantChatData, FinalAssistantChatData, TurnTailChatData,
 } from '../contract/chat-nodes.ts'
 import { deriveTurnMetrics } from '../chat/turn-metrics.ts'
-import { chatNode } from './common.ts'
+import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ChatNodeDataMap {
@@ -85,7 +85,9 @@ function closingAnchor(context: ConversationNodeContext<TurnTailState>): number
     }
     if (event.type === 'assistant/message') {
       steps.set(coordinates.step, { streamedText: false, finalized: true })
-      if (hasTextAssistant(event)) anchor = event.seq + 0.1
+      if (hasTextAssistant(event)) {
+        anchor = event.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.finalizedFollowup
+      }
       continue
     }
     if ((event.type as string) === 'llm/retry') {
@@ -93,7 +95,7 @@ function closingAnchor(context: ConversationNodeContext<TurnTailState>): number
       continue
     }
     if (event.type === 'step/end' && previous.streamedText && !previous.finalized) {
-      anchor = event.seq - 0.8
+      anchor = event.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.interruptedFollowup
     }
   }
   return anchor
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index ca5f3cd25c..84c6fa42af 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/ui-tool/README.md
-README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
-README.zh.md: 6b6e2a153be6a3cad5b57379de6fdc0cd4a58ea4
+README.md: b33aef86a6ad161f70105968f308c5a587c25c24
+README.zh.md: 680a5149187bc43513c74134a9a58c4680af854c
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index d6bc0f248c..b33aef86a6 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client Tool presentation plugin. `ui-conversation` supplies one ordered root call through `conversation.chat.tool`; this package renders that root and its Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
+Client Tool presentation plugin. `ui-conversation` dispatches each ordered `tool-call` Conversation Node through the matching key of `conversation.chat.node`; this package renders its root and Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
 
 Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and recursive `subCalls` projection; the conversation view remains authoritative for ChatFlow placement.
 
@@ -10,7 +10,7 @@ Business UI packages register only their wire Tool names and atomic views. They
 
 `ToolCallTree` receives one root `ToolCallBlock` that already contains recursive `subCalls`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. It recursively walks the standard call blocks and sends the root and children at every depth through the same atomic dispatch path, without subscribing to a separate parent-to-children map.
 
-Each root and child wrapper preserves the `conversation.chat.tool` call-anchor DOM contract used for paging and selection.
+Each root and child wrapper preserves the `data-chat-anchor-key="call:<id>"` and `data-chat-call-id` DOM contract used for paging and selection.
 
 The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text.
 
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 6b6e2a153b..680a514918 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
+Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.node` 的同名 key 分发每个已排序的 `tool-call` Conversation Node；本包渲染其中的 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
 
 业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
 
@@ -10,7 +10,7 @@ Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交
 
 `ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
 
-每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 约定，供分页和 selection 使用。
+每个 root 和 child wrapper 都保留 `data-chat-anchor-key="call:<id>"` 与 `data-chat-call-id` DOM 约定，供分页和 selection 使用。
 
 本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
 

From 3d70889a8d7f19de7c4dc2ede606fe1c8bc618d9 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:53:09 +0800
Subject: [PATCH 238/262] refactor(session): unify event map augmentation
 entrypoint

---
 packages/compact/compact/src/types.ts               |  2 +-
 packages/core/agent/src/types.ts                    |  2 +-
 packages/core/session/tests/fork.spec.ts            |  2 +-
 .../session/tests/gen-persistence-catalog.spec.ts   |  2 +-
 packages/core/tools/src/code-mode.ts                |  2 +-
 packages/feedback/command-feedback/src/index.ts     |  2 +-
 packages/goal/goal/src/domain.ts                    |  2 +-
 packages/hooks/hook-protocol/src/types.ts           |  2 +-
 packages/interaction/commands/src/index.ts          |  2 +-
 packages/interaction/permission/src/index.ts        |  2 +-
 packages/interaction/user-approval/src/index.ts     |  2 +-
 packages/llm/llm-retry/src/index.ts                 | 13 ++-----------
 packages/llm/llm-retry/src/types.ts                 |  9 +++++++++
 packages/plan/plan-mode/src/index.ts                |  2 +-
 packages/sandbox/sandbox-policy/src/session-mode.ts |  2 +-
 .../session-projection-cache/tests/cache.spec.ts    |  2 +-
 .../session-projection/tests/registry.spec.ts       |  2 +-
 .../session-telemetry/tests/telemetry.spec.ts       |  2 +-
 packages/session/session-title-llm/src/index.ts     |  2 +-
 packages/session/session-title/src/index.ts         |  2 +-
 packages/subagent/subagent/src/descriptor.ts        |  2 +-
 packages/web/web-search-deepseek/src/provider.ts    |  2 +-
 22 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index c321be426e..df5e749cd8 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -11,7 +11,7 @@ import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionId } from './brand.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Marks the start of a compaction — log-only, holds the lock until
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index d21f25cdc7..8decb9ba3f 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -290,7 +290,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One normalized mutation of an agent's durable pending-message lists.
diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts
index 0e7a0629c3..58985cfb34 100644
--- a/packages/core/session/tests/fork.spec.ts
+++ b/packages/core/session/tests/fork.spec.ts
@@ -4,7 +4,7 @@ import { createUserMessage, CallId , createMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionForkError, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     'test/log-only': { value: string }
     /** Stands in for a plugin's open/close bracket (`compact/start`). */
diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts
index 9a09cb3489..22bc09835f 100644
--- a/packages/core/session/tests/gen-persistence-catalog.spec.ts
+++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts
@@ -35,7 +35,7 @@ const make = (files: Record<string, string>): string => {
 
 /** A merge-form declaration file wrapping `members` in the session module. */
 const merge = (members: string): string =>
-  `declare module '@deepseek-ai/dsh-session' {\n  interface SessionEventMap {\n${members}\n  }\n}\n`
+  `declare module '@deepseek-ai/dsh-session/types' {\n  interface SessionEventMap {\n${members}\n  }\n}\n`
 
 afterEach(() => {
   while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 63c5b2cb9b..984fecab88 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -15,7 +15,7 @@ import { defineTool, parameterSchemaSpecToJsonSchema } from './schema.ts'
 import { TOOL_REGISTRY_SCHEDULER } from './index.ts'
 import type { CodeDispatchLog, ToolDefinition, ToolExecutionResult, ToolRegistry, ToolRunContext } from './index.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One sub-dispatch STARTING inside a `run_code` program: the parent
diff --git a/packages/feedback/command-feedback/src/index.ts b/packages/feedback/command-feedback/src/index.ts
index ae78b3cd4f..037a463104 100644
--- a/packages/feedback/command-feedback/src/index.ts
+++ b/packages/feedback/command-feedback/src/index.ts
@@ -15,7 +15,7 @@ export const inject = ['commands']
 
 const USAGE = 'Usage: /feedback <text>'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One recorded human remark about this session. Log-only and independent
diff --git a/packages/goal/goal/src/domain.ts b/packages/goal/goal/src/domain.ts
index 8c8c4de6b6..90f22a1602 100644
--- a/packages/goal/goal/src/domain.ts
+++ b/packages/goal/goal/src/domain.ts
@@ -58,7 +58,7 @@ declare module '@deepseek-ai/dsh-llm' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Complete post-mutation goal state or clear tombstone.
diff --git a/packages/hooks/hook-protocol/src/types.ts b/packages/hooks/hook-protocol/src/types.ts
index 82a67f9b93..adaafd6b0f 100644
--- a/packages/hooks/hook-protocol/src/types.ts
+++ b/packages/hooks/hook-protocol/src/types.ts
@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-hook-protocol/types
  */
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * A hook command was invoked at a hook point — a log-only record (like
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 780569c159..ba7b449228 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -131,7 +131,7 @@ class CommandLayer implements ScopeLayer {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * A resolved slash command entered its handler. Log-only (never model
diff --git a/packages/interaction/permission/src/index.ts b/packages/interaction/permission/src/index.ts
index 44d62a9c33..35b762b2aa 100644
--- a/packages/interaction/permission/src/index.ts
+++ b/packages/interaction/permission/src/index.ts
@@ -39,7 +39,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Records the selected preset as durable, log-only user intent. The knob
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index 3dfeabe570..70eacaa627 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -31,7 +31,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * An approval question was put to the answerer chain — log-only audit
diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts
index dcba1e2443..2ebeb79260 100644
--- a/packages/llm/llm-retry/src/index.ts
+++ b/packages/llm/llm-retry/src/index.ts
@@ -12,16 +12,7 @@ import type { Agent, RequestErrorAction } from '@deepseek-ai/dsh-agent'
 import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { RetryId } from './brand.ts'
-import type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
-
-declare module '@deepseek-ai/dsh-session' {
-  interface SessionEventMap {
-    /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-    'llm/retry': LlmRetryEventData
-    /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
-    'llm/retry-started': LlmRetryStartedEventData
-  }
-}
+import type { LlmRetryEventData } from './types.ts'
 
 export type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
 export { RetryId } from './brand.ts'
@@ -132,7 +123,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
   ): Promise<RequestErrorAction> {
     const fusedSignal = AbortSignal.any([signal, lifetime.signal])
     if (fusedSignal.aborted) return
-    const eventData = policy.mode === 'normal'
+    const eventData: LlmRetryEventData = policy.mode === 'normal'
       ? {
         retryId,
         turn,
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index 12820889dd..c698b68446 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,6 +1,15 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
 import type { RetryId } from './brand.ts'
 
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
+    'llm/retry': LlmRetryEventData
+    /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+    'llm/retry-started': LlmRetryStartedEventData
+  }
+}
+
 /** Durable payload recorded before one provider-routed model-request retry wait. */
 export type LlmRetryEventData =
   | {
diff --git a/packages/plan/plan-mode/src/index.ts b/packages/plan/plan-mode/src/index.ts
index c8dd974fd2..00234424ff 100644
--- a/packages/plan/plan-mode/src/index.ts
+++ b/packages/plan/plan-mode/src/index.ts
@@ -42,7 +42,7 @@ import type { PlanProjection } from './types.ts'
 // declarations still receive the SessionProjectionMap merge.
 export type * from './types.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Whether plan mode is in force from this point on: log-only, non-surface,
diff --git a/packages/sandbox/sandbox-policy/src/session-mode.ts b/packages/sandbox/sandbox-policy/src/session-mode.ts
index fc7c53938c..165a462046 100644
--- a/packages/sandbox/sandbox-policy/src/session-mode.ts
+++ b/packages/sandbox/sandbox-policy/src/session-mode.ts
@@ -21,7 +21,7 @@
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * The session's sandbox mode was switched — log-only (like `approval/*`;
diff --git a/packages/session/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts
index 8474e21594..ba9dc39c57 100644
--- a/packages/session/session-projection-cache/tests/cache.spec.ts
+++ b/packages/session/session-projection-cache/tests/cache.spec.ts
@@ -24,7 +24,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     'cache-test/mark': { marks: string[] }
   }
diff --git a/packages/session/session-projection/tests/registry.spec.ts b/packages/session/session-projection/tests/registry.spec.ts
index bd33914b2d..e54f1f2468 100644
--- a/packages/session/session-projection/tests/registry.spec.ts
+++ b/packages/session/session-projection/tests/registry.spec.ts
@@ -22,7 +22,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     'test/mark': { marks: string[] }
   }
diff --git a/packages/session/session-telemetry/tests/telemetry.spec.ts b/packages/session/session-telemetry/tests/telemetry.spec.ts
index 31e587c301..029381fe78 100644
--- a/packages/session/session-telemetry/tests/telemetry.spec.ts
+++ b/packages/session/session-telemetry/tests/telemetry.spec.ts
@@ -17,7 +17,7 @@ import {
   type TelemetryRecord,
 } from '../src/index.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Test-only merged event proving unknown types flow through unchanged.
diff --git a/packages/session/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
index 1b0e328621..52572db30d 100644
--- a/packages/session/session-title-llm/src/index.ts
+++ b/packages/session/session-title-llm/src/index.ts
@@ -37,7 +37,7 @@ export interface SessionTitleLlmRequestEventData {
   readonly maxTokens: number
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /** Log-only pre-dispatch record of one session-title model request. */
     'session/title-llm-request': SessionTitleLlmRequestEventData
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index 12ca7924b4..6f8594edd4 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -91,7 +91,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Latest-wins session title snapshot. Log-only: it never enters the model
diff --git a/packages/subagent/subagent/src/descriptor.ts b/packages/subagent/subagent/src/descriptor.ts
index 55ba73dcc4..6d9dedee75 100644
--- a/packages/subagent/subagent/src/descriptor.ts
+++ b/packages/subagent/subagent/src/descriptor.ts
@@ -25,7 +25,7 @@ import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ToolRestriction } from '@deepseek-ai/dsh-tools'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Durable identity and lifecycle mode of a session-backed subagent child,
diff --git a/packages/web/web-search-deepseek/src/provider.ts b/packages/web/web-search-deepseek/src/provider.ts
index 4bacd80fec..f88941fa12 100644
--- a/packages/web/web-search-deepseek/src/provider.ts
+++ b/packages/web/web-search-deepseek/src/provider.ts
@@ -77,7 +77,7 @@ export interface DeepSeekSearchLlmRequest {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
     'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest

From 10464d155def7c3cdc22459e6bfe824cc118a10a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:42:25 +0800
Subject: [PATCH 239/262] fix(client): consume typed business session events

---
 ...08-09-client-conversation-node-assembly.md |   2 +-
 ...09-client-conversation-node-assembly.zh.md |   2 +-
 packages/client/runtime/package.json          |   2 +
 .../sessions/conversation-location-index.ts   |  12 +-
 .../src/client/sessions/request-inspection.ts | 108 ++++++------------
 .../src/client/sessions/steering-history.ts   |   5 +-
 .../src/client/sessions/tool-call-tree.ts     |  22 +---
 packages/client/runtime/tsconfig.json         |   6 +
 packages/client/ui-conversation/package.json  |   8 ++
 .../client/conversation-nodes/assistant.ts    |  10 +-
 .../src/client/conversation-nodes/command.ts  |  72 +++++-------
 .../client/conversation-nodes/compaction.ts   |  14 +--
 .../src/client/conversation-nodes/inbox.ts    |  13 ++-
 .../src/client/conversation-nodes/retry.ts    |  58 +++-------
 .../src/client/conversation-nodes/tool.ts     |  31 ++---
 .../client/conversation-nodes/turn-error.ts   |   7 +-
 .../client/conversation-nodes/turn-tail.ts    |   9 +-
 .../ui-conversation/tests/chat-apply.spec.tsx |   4 +-
 .../conversation-node-definitions.spec.ts     |  22 ++++
 packages/client/ui-conversation/tsconfig.json |  12 ++
 packages/compact/compact/package.json         |   8 +-
 packages/compact/compact/src/types.ts         |   4 +-
 packages/core/agent/package.json              |   4 +-
 packages/core/agent/src/dispatch.ts           |   2 +-
 packages/core/agent/src/inbox.ts              |   4 +-
 packages/core/agent/src/index.ts              |   5 +-
 .../agent/src/{types.ts => runtime-types.ts}  |  22 +---
 packages/core/agent/src/session-types.ts      |  27 +++++
 .../tests/gen-persistence-catalog.spec.ts     |   2 +-
 packages/core/tools/package.json              |   4 +
 packages/core/tools/src/code-mode.ts          |  36 +-----
 packages/core/tools/src/index.ts              |   1 +
 packages/core/tools/src/types.ts              |  58 ++++++++++
 packages/interaction/commands/package.json    |   4 +
 packages/interaction/commands/src/index.ts    |  42 +------
 packages/interaction/commands/src/types.ts    |  48 ++++++++
 packages/llm/llm-retry/package.json           |   4 -
 packages/llm/llm-retry/src/types.ts           |   4 +-
 .../llm/llm-retry/tests/invariant.spec.ts     |   2 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |   2 +-
 .../context-breakdown-projection.spec.ts      |   2 +-
 .../tests/token-usage-projection.spec.ts      |   2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |   2 +-
 pnpm-lock.yaml                                |  18 +++
 scripts/gen-persistence-catalog.ts            |  19 +--
 scripts/type-equiv.manifest.json              |  16 +--
 tsconfig.base.json                            |   3 +
 47 files changed, 405 insertions(+), 359 deletions(-)
 rename packages/core/agent/src/{types.ts => runtime-types.ts} (96%)
 create mode 100644 packages/core/agent/src/session-types.ts
 create mode 100644 packages/core/tools/src/types.ts
 create mode 100644 packages/interaction/commands/src/types.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index f9768a652c..9952f8fac0 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -16,7 +16,7 @@ Business events also use different correlation models. Tool has call IDs, Assist
 
 Client Runtime provides a target-neutral Conversation Node assembly engine. Business plugins register Event Definitions, and view plugins register per-Session View Builders. `ui-conversation` registers the first built-in Definitions and the `chat` builder; Session only submits the current contiguous Event window to the engine and publishes its snapshot instead of interpreting individual conversation businesses.
 
-The complete derivation, business-by-business validation, and file-level implementation plan remain in [`business-node assembler version one`](../../../../docs/client-conversation-node-engine-rfc.md), [`follow-up design differences`](../../../../docs/client-conversation-node-engine-follow-up-differences.md), [`business-node and dual-view adaptation analysis`](../../../../docs/client-conversation-node-adaptation-analysis.md), and the [`Chat implementation design`](../../../../docs/client-conversation-node-chat-implementation-plan.md). Those design documents retain the full discussion; this Note fixes the responsibilities, algorithms, and trade-offs that remain relevant after implementation.
+This Note retains the derivation, business-by-business validation, responsibilities, algorithms, and trade-offs that remain relevant after implementation.
 
 ### Responsibility layers
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 408d61f73b..f27a82459c 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -16,7 +16,7 @@ Client Session 既维护传输窗口、连接状态和待处理交互，也在
 
 Client Runtime 提供 target-neutral 的 Conversation Node 组装引擎，业务插件注册 Event Definition，视图插件注册 per-Session View Builder。`ui-conversation` 注册第一批内建 Definition 和 `chat` builder；Session 只负责把当前连续事件窗口送入引擎并发布它的 snapshot，不再解释具体 conversation 业务。
 
-详细的方案推导、逐业务适配和逐文件实施设计保留在 [`业务节点组装器第一版`](../../../../docs/client-conversation-node-engine-rfc.md)、[`后续方案差异`](../../../../docs/client-conversation-node-engine-follow-up-differences.md)、[`业务节点与双视图适配论证`](../../../../docs/client-conversation-node-adaptation-analysis.md) 和 [`Chat 链路工程实施设计`](../../../../docs/client-conversation-node-chat-implementation-plan.md)。这些设计稿保留完整讨论过程；本 Note 固定实现后仍需长期维护的职责、算法和取舍。
+本 Note 保留实现后仍有价值的方案推导、逐业务适配、职责、算法和取舍。
 
 ### 责任分层
 
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index 3176428b36..f5a9a06a60 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -32,6 +32,7 @@
   },
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
@@ -41,6 +42,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "immer": "^10.1.1",
     "react": "^18.2.0",
     "zustand": "~4.4.7"
diff --git a/packages/client/runtime/src/client/sessions/conversation-location-index.ts b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
index 20fe3efdff..c842a230a9 100644
--- a/packages/client/runtime/src/client/sessions/conversation-location-index.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
@@ -139,7 +139,11 @@ export class ConversationLocationIndex {
     return this.timeline
   }
 
-  /** Replace all Definition-owned Location values while preserving reader identities. */
+  /**
+   * Replace all Definition-owned Location values while preserving reader identities.
+   * @param entries - complete current set of Definition-owned Location values.
+   * @returns whether any published Location data changed.
+   */
   replaceData(entries: readonly { readonly owner: string; readonly data: ConversationLocationData }[]): boolean {
     const turns = new Map<number, Map<string, OwnedLocationData>>()
     const steps = new Map<string, Map<string, OwnedLocationData>>()
@@ -165,7 +169,11 @@ export class ConversationLocationIndex {
     return changed
   }
 
-  /** Apply changed Context publications without rebuilding Turn/Step membership. */
+  /**
+   * Apply changed Context publications without rebuilding Turn/Step membership.
+   * @param changes - incremental removals and replacements from published Contexts.
+   * @returns whether any published Location data changed.
+   */
   applyData(changes: readonly ConversationLocationDataChange[]): boolean {
     let changed = false
     for (const change of changes) {
diff --git a/packages/client/runtime/src/client/sessions/request-inspection.ts b/packages/client/runtime/src/client/sessions/request-inspection.ts
index 36ae79eebe..162f34d5ff 100644
--- a/packages/client/runtime/src/client/sessions/request-inspection.ts
+++ b/packages/client/runtime/src/client/sessions/request-inspection.ts
@@ -5,6 +5,9 @@
 import type { ContentBlock, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm/types'
 import type { HistoryEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-compact/types'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
+import type {} from '@deepseek-ai/dsh-tools/types'
 import type {
   AssistantProvenanceView, AssistantRequestConfig,
 } from './conversation.ts'
@@ -109,48 +112,6 @@ export function inspectRequests(
   }
 }
 
-interface RetryEvent {
-  type: 'llm/retry'
-  seq: number
-  time: number
-  data: {
-    turn: number
-    step: number
-    retry: number
-    maxRetries: number
-    delayMs: number
-    failure: { message: string }
-  }
-}
-
-interface CompactionStartEvent {
-  type: 'compact/start'
-  seq: number
-  time: number
-  data: { turn: number | null }
-}
-
-interface CompactionSummaryEvent {
-  type: 'compact/summary'
-  seq: number
-  time: number
-  data: {
-    summary: readonly ContentBlock[]
-    rawOutput?: readonly ContentBlock[]
-    provider: string
-    model: string
-    maxTokens?: number
-    usage?: unknown
-  }
-}
-
-interface CompactionEndEvent {
-  type: 'compact/end'
-  seq: number
-  time: number
-  data: { turn: number | null; error?: string }
-}
-
 function requestKey(turn: number, step: number): string {
   return `${turn}\u0000${step}`
 }
@@ -205,10 +166,8 @@ function deriveCallSchemas(
       capture(String(event.data.callId), event.data.name)
       continue
     }
-    const type = event.type as string
-    if (type === 'tool/code-dispatch-start' || type === 'tool/code-dispatch') {
-      const data = event.data as unknown as { subCallId: string; name: string }
-      capture(data.subCallId, data.name)
+    if (event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch') {
+      capture(String(event.data.subCallId), event.data.name)
     }
   }
   return calls
@@ -351,14 +310,14 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       if (activeStep === key) activeStep = undefined
       continue
     }
-    if ((sourceEvent.type as string) === 'llm/retry') {
-      const event = sourceEvent as unknown as RetryEvent
-      updateAssistant(ordinaryByStep.get(requestKey(event.data.turn, event.data.step)), {
+    if (sourceEvent.type === 'llm/retry') {
+      const data = sourceEvent.data
+      updateAssistant(ordinaryByStep.get(requestKey(data.turn, data.step)), {
         status: 'error',
-        error: displayFailureMessage(event.data.failure),
-        retry: event.data.retry,
-        maxRetries: event.data.maxRetries,
-        retryDelayMs: event.data.delayMs,
+        error: displayFailureMessage(data.failure),
+        retry: data.retry,
+        ...data.mode === 'normal' ? { maxRetries: data.maxRetries } : {},
+        retryDelayMs: data.delayMs,
       })
       continue
     }
@@ -374,8 +333,7 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       continue
     }
 
-    const type = sourceEvent.type as string
-    if (type === 'session/end-seed' && activeCompaction !== undefined) {
+    if (sourceEvent.type === 'session/end-seed' && activeCompaction !== undefined) {
       updateCompaction(activeCompaction, {
         completedAt: sourceEvent.time,
         status: 'error',
@@ -384,37 +342,36 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       activeCompaction = undefined
       continue
     }
-    if (type === 'compact/start') {
-      const event = sourceEvent as unknown as CompactionStartEvent
+    if (sourceEvent.type === 'compact/start') {
       activeCompaction = requests.length
       requests.push({
         purpose: 'compaction',
-        startSeq: event.seq,
-        turn: event.data.turn,
+        startSeq: sourceEvent.seq,
+        turn: sourceEvent.data.turn,
         step: 0,
-        startedAt: event.time,
+        startedAt: sourceEvent.time,
         completedAt: null,
         status: 'running',
       })
       continue
     }
-    if (type === 'compact/summary' && activeCompaction !== undefined) {
-      const event = sourceEvent as unknown as CompactionSummaryEvent
+    if (sourceEvent.type === 'compact/summary' && activeCompaction !== undefined) {
+      const data = sourceEvent.data
       updateCompaction(activeCompaction, {
-        resultSeq: event.seq,
-        summary: event.data.summary,
-        ...(event.data.rawOutput === undefined ? {} : { rawOutput: event.data.rawOutput }),
+        resultSeq: sourceEvent.seq,
+        summary: data.summary,
+        ...(data.rawOutput === undefined ? {} : { rawOutput: data.rawOutput }),
         provenance: {
-          provider: event.data.provider,
-          model: event.data.model,
+          provider: data.provider,
+          model: data.model,
         },
         requestConfig: {
-          provider: event.data.provider,
-          model: event.data.model,
+          provider: data.provider,
+          model: data.model,
           purpose: 'compaction',
-          ...(event.data.maxTokens === undefined ? {} : { maxTokens: event.data.maxTokens }),
+          ...(data.maxTokens === undefined ? {} : { maxTokens: data.maxTokens }),
         },
-        ...(event.data.usage === undefined ? {} : { usage: event.data.usage }),
+        ...(data.usage === undefined ? {} : { usage: data.usage }),
       })
       continue
     }
@@ -426,12 +383,11 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       updateCompaction(activeCompaction, { replacementSeq: sourceEvent.seq })
       continue
     }
-    if (type !== 'compact/end' || activeCompaction === undefined) continue
-    const event = sourceEvent as unknown as CompactionEndEvent
+    if (sourceEvent.type !== 'compact/end' || activeCompaction === undefined) continue
     updateCompaction(activeCompaction, {
-      completedAt: event.time,
-      status: event.data.error === undefined ? 'complete' : 'error',
-      ...(event.data.error === undefined ? {} : { error: event.data.error }),
+      completedAt: sourceEvent.time,
+      status: sourceEvent.data.error === undefined ? 'complete' : 'error',
+      ...(sourceEvent.data.error === undefined ? {} : { error: sourceEvent.data.error }),
     })
     activeCompaction = undefined
   }
diff --git a/packages/client/runtime/src/client/sessions/steering-history.ts b/packages/client/runtime/src/client/sessions/steering-history.ts
index 0f66025e16..4220a769ff 100644
--- a/packages/client/runtime/src/client/sessions/steering-history.ts
+++ b/packages/client/runtime/src/client/sessions/steering-history.ts
@@ -1,6 +1,7 @@
 /** Reconstruct durable steering identity from the event-sourced agent inbox. */
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-agent/types'
 
 type InboxTarget = 'next-turn' | 'next-step'
 
@@ -45,8 +46,8 @@ export class SteeringHistory {
    * @returns true only for a user-origin message previously claimed from `next-step`.
    */
   apply(event: SessionEvent): boolean {
-    if ((event.type as string) === 'agent/inbox/spliced') {
-      this.applySplice(event.data as unknown as InboxSplice)
+    if (event.type === 'agent/inbox/spliced') {
+      this.applySplice(event.data)
       return false
     }
     if (event.type !== 'user/message') return false
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
index fbc32e0cef..4507b7a947 100644
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -1,5 +1,5 @@
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-tools/types'
 import type {
   ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode,
 } from './conversation.ts'
@@ -55,13 +55,8 @@ export class ToolCallTree {
    * @returns Whether the event was consumed as a child-call lifecycle event.
    */
   apply(event: SessionEvent): boolean {
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
+    if (event.type === 'tool/code-dispatch-start') {
+      const data = event.data
       const running: RunningToolCall = {
         callId: data.subCallId,
         name: data.name,
@@ -78,15 +73,8 @@ export class ToolCallTree {
       this.revision++
       return true
     }
-    if ((event.type as string) !== 'tool/code-dispatch') return false
-    const data = event.data as unknown as {
-      parentCallId: string
-      subCallId: string
-      name: string
-      arguments: unknown
-      isError: boolean
-      content: ContentBlock[]
-    }
+    if (event.type !== 'tool/code-dispatch') return false
+    const data = event.data
     const siblings = this.childrenByParent.get(data.parentCallId) ?? []
     const at = siblings.findIndex(sub => sub.callId === data.subCallId)
     if (at === -1 && !this.acceptEdge(data.parentCallId, data.subCallId)) return true
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 867b2f588c..b8949fc6db 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -26,6 +26,12 @@
     {
       "path": "../../interaction/commands"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/tools"
+    },
     {
       "path": "../../compact/compact"
     },
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 3f5bd8364c..e78567cbf7 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -39,22 +39,28 @@
     "clsx": "^2.0.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-compact": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.0.1",
     "@deepseek-ai/dsh-token-meter": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-compact": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
@@ -62,9 +68,11 @@
     "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm-retry": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7",
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
index 8a487c89ed..83df1e0df6 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
@@ -6,6 +6,7 @@ import type {
 import {
   emptyAssistantBlock, isAppendSurfaceEvent, isTokenDelta, toAssistantBlock, toAssistantBlocks,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type { AssistantChatData } from '../contract/chat-nodes.ts'
 import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
@@ -197,7 +198,7 @@ function fallbackState(context: ConversationNodeContext<AssistantState>): Assist
       }
       continue
     }
-    if ((match.event.type as string) === 'llm/retry' && state !== undefined) {
+    if (match.event.type === 'llm/retry' && state !== undefined) {
       state = resetForRetry(state)
     }
   }
@@ -247,9 +248,8 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
       || (event.type === 'assistant/message' && isAppendSurfaceEvent(event))) {
       return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
     }
-    if ((event.type as string) === 'llm/retry') {
-      const data = event.data as unknown as { turn: number; step: number }
-      return { id: `${data.turn}:${data.step}`, role: 'update' }
+    if (event.type === 'llm/retry') {
+      return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
     }
     return null
   },
@@ -268,7 +268,7 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
         usage: match.event.data.usage,
       }
     }
-    if ((match.event.type as string) === 'llm/retry') {
+    if (match.event.type === 'llm/retry') {
       return resetForRetry(context.state)
     }
     return context.state
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
index 3ca7976e32..38cb85ed87 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
@@ -5,6 +5,8 @@ import type {
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
 import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type {} from '@deepseek-ai/dsh-compact/types'
+import type {} from '@deepseek-ai/dsh-commands/types'
 import type { ManualCompactionChatData } from '../contract/chat-nodes.ts'
 import { chatNode } from './common.ts'
 
@@ -32,21 +34,9 @@ interface CompactionEvidence {
   readonly checkpoint?: ConversationMatch
 }
 
-interface CommandRunData {
-  readonly commandId: CommandId
-  readonly name: string
-  readonly args?: string
-}
-
-interface CommandDoneData {
-  readonly commandId: CommandId
-  readonly kind: 'success' | 'error'
-  readonly text?: string
-  readonly sourceEventSeq?: number
-}
-
 function commandFromRun(match: ConversationMatch): CommandNode {
-  const data = match.event.data as unknown as CommandRunData
+  if (match.event.type !== 'command/run') throw new Error('command start requires command/run')
+  const data = match.event.data
   return {
     kind: 'command',
     seq: match.event.seq,
@@ -59,10 +49,12 @@ function commandFromRun(match: ConversationMatch): CommandNode {
 }
 
 function commandFromDone(match: ConversationMatch, previous?: CommandNode): CommandNode {
-  const data = match.event.data as unknown as CommandDoneData
+  if (match.event.type !== 'command/done') throw new Error('command update requires command/done')
+  const data = match.event.data
   const sourceEventSeq = data.kind === 'success'
-    && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
-    ? data.sourceEventSeq as number
+    && data.sourceEventSeq !== undefined
+    && Number.isSafeInteger(data.sourceEventSeq) && data.sourceEventSeq >= 0
+    ? data.sourceEventSeq
     : undefined
   return {
     kind: 'command',
@@ -112,28 +104,21 @@ function compactSummary(match: ConversationMatch | undefined, checkpoint: Conver
   let summary: string | null = null
   let shadowedItemCount: number | null = null
   let shadowedTokenCount: number | null = null
-  if (match !== undefined) {
-    const data = match.event.data as unknown as {
-      summary?: unknown
-      shadowedSeqs?: unknown
-      shadowedTokenCount?: unknown
-    }
+  if (match?.event.type === 'compact/summary') {
+    const data = match.event.data
     if (Array.isArray(data.summary)) {
       const text = data.summary
-        .map((block: unknown) => {
-          const value = block as { type?: unknown; text?: unknown }
-          return value.type === 'text' && typeof value.text === 'string' ? value.text : ''
-        })
+        .map(block => block.type === 'text' ? block.text : '')
         .join('')
       summary = text.trim() === '' ? null : text
     }
     shadowedItemCount = Array.isArray(data.shadowedSeqs)
-      && data.shadowedSeqs.every(seq => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      && data.shadowedSeqs.every(seq => Number.isSafeInteger(seq) && seq >= 0)
       ? data.shadowedSeqs.length
       : null
     shadowedTokenCount = Number.isSafeInteger(data.shadowedTokenCount)
-      && (data.shadowedTokenCount as number) >= 0
-      ? data.shadowedTokenCount as number
+      && data.shadowedTokenCount >= 0
+      ? data.shadowedTokenCount
       : null
   }
   return {
@@ -148,9 +133,9 @@ function compactSummary(match: ConversationMatch | undefined, checkpoint: Conver
 }
 
 function fallbackState(context: ConversationNodeContext<CommandState>): CommandState | undefined {
-  const done = context.matches.find(match => (match.event.type as string) === 'command/done')
+  const done = context.matches.find(match => match.event.type === 'command/done')
   const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
-  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  const summary = context.matches.find(match => match.event.type === 'compact/summary')
   if (checkpoint === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
   const source = compactSource(checkpoint.event)
   if (source?.sourceCommandId === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
@@ -182,7 +167,7 @@ export function updateCompactionState<State extends CompactionEvidence>(
   state: State,
   match: ConversationMatch,
 ): State {
-  if ((match.event.type as string) === 'compact/summary') return { ...state, summary: match }
+  if (match.event.type === 'compact/summary') return { ...state, summary: match }
   if (compactSource(match.event) !== undefined) return { ...state, checkpoint: match }
   return state
 }
@@ -191,27 +176,28 @@ export function updateCompactionState<State extends CompactionEvidence>(
 export const commandDefinition: ConversationNodeDefinition<CommandState> = {
   kind: 'command',
   match: (event) => {
-    if ((event.type as string) === 'command/run') {
-      return { id: String((event.data as unknown as CommandRunData).commandId), role: 'start' }
+    if (event.type === 'command/run') {
+      return { id: String(event.data.commandId), role: 'start' }
     }
-    if ((event.type as string) === 'command/done') {
-      return { id: String((event.data as unknown as CommandDoneData).commandId), role: 'update' }
+    if (event.type === 'command/done') {
+      return { id: String(event.data.commandId), role: 'update' }
     }
     const checkpoint = compactSource(event)
     if (checkpoint?.sourceCommandId !== undefined) {
       return { id: String(checkpoint.sourceCommandId), role: 'update' }
     }
-    if ((event.type as string) === 'compact/start'
-      || (event.type as string) === 'compact/summary'
-      || (event.type as string) === 'compact/end') {
-      const data = event.data as unknown as { sourceCommandId?: CommandId }
-      if (data.sourceCommandId !== undefined) return { id: String(data.sourceCommandId), role: 'update' }
+    if (event.type === 'compact/start'
+      || event.type === 'compact/summary'
+      || event.type === 'compact/end') {
+      if (event.data.sourceCommandId !== undefined) {
+        return { id: String(event.data.sourceCommandId), role: 'update' }
+      }
     }
     return null
   },
   start: (_context, match) => ({ command: commandFromRun(match) }),
   update: (context, match) => {
-    if ((match.event.type as string) === 'command/done') {
+    if (match.event.type === 'command/done') {
       return { ...context.state, command: commandFromDone(match, context.state.command) }
     }
     return updateCompactionState(context.state, match)
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
index 0742ab6539..04eace8038 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
@@ -2,6 +2,7 @@ import type { Context } from 'cordis'
 import type {
   CompactionSummaryNode, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-compact/types'
 import { chatNode } from './common.ts'
 import { compactSource, compactSummary, updateCompactionState } from './command.ts'
 
@@ -18,7 +19,7 @@ interface CompactionState {
 }
 
 function fallbackState(context: ConversationNodeContext<CompactionState>): CompactionState {
-  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  const summary = context.matches.find(match => match.event.type === 'compact/summary')
   const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
   return {
     ...summary === undefined ? {} : { summary },
@@ -34,12 +35,11 @@ export const compactionDefinition: ConversationNodeDefinition<CompactionState> =
     if (checkpoint !== undefined && checkpoint.sourceCommandId === undefined) {
       return { id: checkpoint.compactionId, role: 'update' }
     }
-    if ((event.type as string) === 'compact/start'
-      || (event.type as string) === 'compact/summary'
-      || (event.type as string) === 'compact/end') {
-      const data = event.data as unknown as { compactionId?: unknown; sourceCommandId?: unknown }
-      if (typeof data.compactionId !== 'string' || data.sourceCommandId !== undefined) return null
-      return { id: data.compactionId, role: (event.type as string) === 'compact/start' ? 'start' : 'update' }
+    if (event.type === 'compact/start'
+      || event.type === 'compact/summary'
+      || event.type === 'compact/end') {
+      if (event.data.sourceCommandId !== undefined) return null
+      return { id: String(event.data.compactionId), role: event.type === 'compact/start' ? 'start' : 'update' }
     }
     return null
   },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
index 092bcaaa59..74406c324a 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
@@ -2,6 +2,7 @@ import type { Context } from 'cordis'
 import type {
   ConversationNodeDefinition, ConversationPreviousContext,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-agent/types'
 
 type InboxTarget = 'next-turn' | 'next-step'
 
@@ -41,14 +42,14 @@ function inboxDefinition(target: InboxTarget): ConversationNodeDefinition<InboxS
   const kind = `inbox-${target}`
   return {
     kind,
-    match: event => (event.type as string) === 'agent/inbox/spliced'
-      && (event.data as unknown as { target?: unknown }).target === target
+    match: event => event.type === 'agent/inbox/spliced'
+      && event.data.target === target
       ? { id: String(event.seq), role: 'start' }
       : null,
-    start: (_context, match, reader) => applySplice(
-      reader.previous<InboxState>(kind),
-      match.event.data as unknown as InboxSplice,
-    ),
+    start: (_context, match, reader) => {
+      if (match.event.type !== 'agent/inbox/spliced') throw new Error(`${kind} start requires agent/inbox/spliced`)
+      return applySplice(reader.previous<InboxState>(kind), match.event.data)
+    },
     update: context => context.state,
     publication: () => 'none',
     buildViewNode: () => null,
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
index fe95c0052d..f383bc46d8 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -2,6 +2,7 @@ import type { Context } from 'cordis'
 import type {
   ConversationLocation, ConversationNodeDefinition, ModelRetryNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type { RetryChatData } from '../contract/chat-nodes.ts'
 import { chatNode } from './common.ts'
 
@@ -12,11 +13,6 @@ declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   }
 }
 
-type WithoutRetryProjection<Node> = Node extends unknown
-  ? Omit<Node, 'kind' | 'seq' | 'time' | 'retryState'>
-  : never
-type RetryEventData = WithoutRetryProjection<ModelRetryNode>
-
 /** Accumulated retry attempts sharing one producer-owned RetryId. */
 export interface RetryState {
   readonly turn: number
@@ -24,31 +20,14 @@ export interface RetryState {
   readonly attempts: readonly ModelRetryNode[]
 }
 
-function retryData(value: unknown): RetryEventData | undefined {
-  if (value === null || typeof value !== 'object') return undefined
-  const data = value as Record<string, unknown>
-  if (typeof data.retryId !== 'string' || data.retryId === ''
-    || !Number.isSafeInteger(data.turn) || (data.turn as number) < 0
-    || !Number.isSafeInteger(data.step) || (data.step as number) < 0
-    || !Number.isSafeInteger(data.retry) || (data.retry as number) <= 0
-    || typeof data.delayMs !== 'number' || !Number.isFinite(data.delayMs) || data.delayMs < 0
-    || typeof data.provider !== 'string' || typeof data.policyKey !== 'string'
-    || (data.mode !== 'normal' && data.mode !== 'always')
-    || data.failure === null || typeof data.failure !== 'object') return undefined
-  if (data.mode === 'normal' && (!Number.isSafeInteger(data.maxRetries) || (data.maxRetries as number) <= 0)) {
-    return undefined
-  }
-  return data as unknown as RetryEventData
-}
-
-function scheduledNode(event: { seq: number; time: number; data: unknown }): ModelRetryNode | undefined {
-  const data = retryData(event.data)
-  return data === undefined ? undefined : {
+function scheduledNode(match: Parameters<ConversationNodeDefinition['start']>[1]): ModelRetryNode | undefined {
+  if (match.event.type !== 'llm/retry') return undefined
+  return {
     kind: 'model-retry',
-    seq: event.seq,
-    time: event.time,
+    seq: match.event.seq,
+    time: match.event.time,
     retryState: 'scheduled',
-    ...data,
+    ...match.event.data,
   }
 }
 
@@ -61,33 +40,30 @@ function isClosed(location: ConversationLocation): boolean {
 export const retryDefinition: ConversationNodeDefinition<RetryState> = {
   kind: 'model-retry',
   match: (event) => {
-    if ((event.type as string) === 'llm/retry') {
-      const data = retryData(event.data)
-      if (data === undefined) return null
-      return { id: String(data.retryId), role: data.retry === 1 ? 'start' : 'update' }
+    if (event.type === 'llm/retry') {
+      return { id: String(event.data.retryId), role: event.data.retry === 1 ? 'start' : 'update' }
     }
-    if ((event.type as string) === 'llm/retry-started') {
-      const data = event.data as unknown as { retryId?: unknown }
-      return typeof data.retryId === 'string' ? { id: data.retryId, role: 'update' } : null
+    if (event.type === 'llm/retry-started') {
+      return { id: String(event.data.retryId), role: 'update' }
     }
     return null
   },
   start: (_context, match) => {
-    const node = scheduledNode(match.event)
+    const node = scheduledNode(match)
     if (node === undefined) throw new Error('model-retry start requires a valid llm/retry event')
     return { turn: node.turn, step: node.step, attempts: [node] }
   },
   update: (context, match) => {
-    if ((match.event.type as string) === 'llm/retry') {
-      const node = scheduledNode(match.event)
+    if (match.event.type === 'llm/retry') {
+      const node = scheduledNode(match)
       return node === undefined ? context.state : { ...context.state, attempts: [...context.state.attempts, node] }
     }
-    if ((match.event.type as string) !== 'llm/retry-started') return context.state
-    const data = match.event.data as unknown as { retry: number }
+    if (match.event.type !== 'llm/retry-started') return context.state
+    const retry = match.event.data.retry
     return {
       ...context.state,
       attempts: context.state.attempts.map(attempt =>
-        attempt.retry === data.retry ? { ...attempt, retryState: 'started' } : attempt),
+        attempt.retry === retry ? { ...attempt, retryState: 'started' } : attempt),
     }
   },
   buildViewNode: (context, target) => {
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
index 23201fec3e..dc9e996dcc 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -4,6 +4,7 @@ import type {
   RunningToolCall, ToolCallBlock, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-tools/types'
 import type { ToolChatData } from '../contract/chat-nodes.ts'
 import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
@@ -141,27 +142,30 @@ function acceptsEdge(state: ToolState, parent: string, child: string): boolean {
 }
 
 function updateDispatch(state: ToolState, match: ConversationMatch): ToolState {
-  const data = match.event.data as unknown as DispatchData
-  const siblings = state.children.get(data.parentCallId) ?? []
-  const index = siblings.findIndex(candidate => candidate.callId === data.subCallId)
-  if ((match.event.type as string) === 'tool/code-dispatch-start') {
-    if (index >= 0 || !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+  const event = match.event
+  if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return state
+  const data = event.data
+  const parentCallId = String(data.parentCallId)
+  const subCallId = String(data.subCallId)
+  const siblings = state.children.get(parentCallId) ?? []
+  const index = siblings.findIndex(candidate => candidate.callId === subCallId)
+  if (event.type === 'tool/code-dispatch-start') {
+    if (index >= 0 || !acceptsEdge(state, parentCallId, subCallId)) return state
     const children = new Map(state.children)
-    children.set(data.parentCallId, [...siblings, childCall(match, data)])
+    children.set(parentCallId, [...siblings, childCall(match, data)])
     const parents = new Map(state.parents)
-    parents.set(data.subCallId, data.parentCallId)
+    parents.set(subCallId, parentCallId)
     return { ...state, children, parents }
   }
-  if ((match.event.type as string) !== 'tool/code-dispatch') return state
-  if (index < 0 && !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+  if (index < 0 && !acceptsEdge(state, parentCallId, subCallId)) return state
   const previous = index < 0 ? undefined : siblings[index]
   const settled = childResult(match, data, previous)
   const children = new Map(state.children)
-  children.set(data.parentCallId, index < 0
+  children.set(parentCallId, index < 0
     ? [...siblings, settled]
     : siblings.map((child, at) => at === index ? settled : child))
   const parents = new Map(state.parents)
-  if (index < 0) parents.set(data.subCallId, data.parentCallId)
+  if (index < 0) parents.set(subCallId, parentCallId)
   return { ...state, children, parents }
 }
 
@@ -236,9 +240,8 @@ export const toolDefinition: ConversationNodeDefinition<ToolState> = {
     if (event.type === 'tool/result' && isAppendSurfaceEvent(event)) {
       return { id: String(event.data.message.source.callId), role: 'update' }
     }
-    if ((event.type as string) === 'tool/code-dispatch-start' || (event.type as string) === 'tool/code-dispatch') {
-      const data = event.data as unknown as { rootCallId: string }
-      return { id: data.rootCallId, role: 'update' }
+    if (event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch') {
+      return { id: String(event.data.rootCallId), role: 'update' }
     }
     return null
   },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
index 58725d8723..60b2fca087 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
@@ -3,6 +3,7 @@ import type {
   ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnErrorNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { displayFailureMessage } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import { chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
@@ -30,9 +31,9 @@ function lastStep(context: ConversationNodeContext<TurnErrorState>): number {
 }
 
 function retryTurn(event: Parameters<ConversationNodeDefinition['match']>[0]): number | undefined {
-  if ((event.type as string) !== 'llm/retry' && (event.type as string) !== 'llm/retry-started') return undefined
-  const turn = (event.data as unknown as { turn?: unknown }).turn
-  return Number.isSafeInteger(turn) && (turn as number) >= 0 ? turn as number : undefined
+  return event.type === 'llm/retry' || event.type === 'llm/retry-started'
+    ? event.data.turn
+    : undefined
 }
 
 function failureFrom(match: ConversationMatch): TurnErrorState['failure'] | undefined {
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
index 51cb348e6a..2a1b4d2b13 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -3,6 +3,7 @@ import type {
   ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnLocation,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isAppendSurfaceEvent, toAssistantBlocks } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type {
   AssistantChatData, FinalAssistantChatData, TurnTailChatData,
 } from '../contract/chat-nodes.ts'
@@ -58,9 +59,7 @@ function turnCoordinates(event: Parameters<ConversationNodeDefinition['match']>[
     || event.type === 'step/end') {
     return { turn: event.data.turn, step: event.data.step }
   }
-  if ((event.type as string) === 'llm/retry') {
-    return event.data as unknown as { turn: number; step: number }
-  }
+  if (event.type === 'llm/retry') return { turn: event.data.turn, step: event.data.step }
   return undefined
 }
 
@@ -90,7 +89,7 @@ function closingAnchor(context: ConversationNodeContext<TurnTailState>): number
       }
       continue
     }
-    if ((event.type as string) === 'llm/retry') {
+    if (event.type === 'llm/retry') {
       steps.set(coordinates.step, { streamedText: false, finalized: false })
       continue
     }
@@ -130,7 +129,7 @@ function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChat
     const candidate = event.type === 'tool/call'
       || (event.type === 'tool/result' && isAppendSurfaceEvent(event))
       || (event.type === 'turn/end' && event.data.reason.kind === 'error')
-      || (event.type as string) === 'llm/retry'
+      || event.type === 'llm/retry'
       ? event.seq
       : undefined
     if (candidate !== undefined && (latestTranscriptSeq === undefined || candidate > latestTranscriptSeq)) {
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index 3481ee758e..41ffd329b8 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -62,7 +62,9 @@ describe('apply wiring', () => {
     expect(entries[0]?.options.order).toBe(0)
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
-    expect(b.slots.spec('conversation.chat.node')).toEqual({ kind: 'keyed', scope: 'session' })
+    const nodeSlot = b.slots.spec('conversation.chat.node')
+    expect(nodeSlot).toMatchObject({ kind: 'keyed', scope: 'session' })
+    expect(nodeSlot?.inject?.hooks?.turnData).toBeTypeOf('function')
     await b.runtime.dispose()
   })
 
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 5346ad57f9..3e5dcccff3 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -644,6 +644,28 @@ describe('built-in conversation node Definitions', () => {
     })
   })
 
+  it('renders a historical compaction when its start remains outside the loaded window', () => {
+    const value = assembler([
+      at(10, 'compact/summary', {
+        compactionId: 'compact-windowed',
+        summary: [{ type: 'text', text: 'loaded summary' }],
+        shadowedSeqs: [1, 2, 3],
+        shadowedTokenCount: 42,
+      }),
+      at(11, 'user/message', {
+        ...textMessage('checkpoint-windowed', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact', compactionId: 'compact-windowed' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 3 } }),
+    ], true)
+
+    expect(node(snapshot(value), 'compaction')?.data).toMatchObject({
+      summary: 'loaded summary',
+      summaryEventSeq: 10,
+      shadowedItemCount: 3,
+      shadowedTokenCount: 42,
+    })
+  })
+
   it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
     const value = assembler([
       at(5, 'llm/retry', {
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 89d0067caf..0d6f250441 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -23,12 +23,24 @@
     {
       "path": "../runtime"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../../session/session-projection"
     },
     {
       "path": "../../llm/token-meter"
     },
+    {
+      "path": "../../llm/llm-retry"
+    },
     {
       "path": "../../plan/plan-mode"
     },
diff --git a/packages/compact/compact/package.json b/packages/compact/compact/package.json
index bb4150ee32..860145e542 100644
--- a/packages/compact/compact/package.json
+++ b/packages/compact/compact/package.json
@@ -15,14 +15,14 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./checkpoint": {
       "types": "./lib/types/checkpoint.d.ts",
       "default": "./lib/types/checkpoint.js"
     },
-    "./brand": {
-      "types": "./lib/types/brand.d.ts",
-      "default": "./lib/types/brand.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index df5e749cd8..53c3baf05f 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -9,7 +9,9 @@
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-import type { CompactionId } from './brand.ts'
+import { CompactionId } from './brand.ts'
+
+export { CompactionId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index 9f64d33e75..d186f32d03 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -16,8 +16,8 @@
       "default": "./lib/invariant.js"
     },
     "./types": {
-      "types": "./lib/types/types.d.ts",
-      "default": "./lib/types/types.js"
+      "types": "./lib/types/session-types.d.ts",
+      "default": "./lib/types/session-types.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
diff --git a/packages/core/agent/src/dispatch.ts b/packages/core/agent/src/dispatch.ts
index cf07f24ecf..7eff09b01d 100644
--- a/packages/core/agent/src/dispatch.ts
+++ b/packages/core/agent/src/dispatch.ts
@@ -10,7 +10,7 @@ import type { Context, Events } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { AssembleContext } from '@deepseek-ai/dsh-system-prompt'
-import type { Agent } from './types.ts'
+import type { Agent } from './runtime-types.ts'
 
 /** Extract the parameter tuple from an event handler type (its `this` is not part of the tuple). */
 type Params<F> = F extends (...args: infer P) => unknown ? P : never
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index d457277035..2db3c4b580 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -6,9 +6,7 @@
 
 import type { MessageId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEventMap, UserMessage } from '@deepseek-ai/dsh-session'
-
-/** One of the two ordered pending-message lists owned by an agent. */
-export type InboxTarget = 'next-turn' | 'next-step'
+import type { InboxTarget } from './session-types.ts'
 
 /** Mutable state privately owned by an {@link Inbox}. */
 type InboxState = Record<InboxTarget, UserMessage[]>
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index bedfc819dc..e35bc06211 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -13,9 +13,10 @@ import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { TypeRTContext, TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
-import type { Agent, AgentOptions } from './types.ts'
+import type { Agent, AgentOptions } from './runtime-types.ts'
 
-export * from './types.ts'
+export * from './runtime-types.ts'
+export * from './session-types.ts'
 export * from './inbox.ts'
 export * from './model-selection.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/runtime-types.ts
similarity index 96%
rename from packages/core/agent/src/types.ts
rename to packages/core/agent/src/runtime-types.ts
index 8decb9ba3f..072f509f8f 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/runtime-types.ts
@@ -2,7 +2,7 @@
  * Public agent types and live-runtime events. Durable transcript facts and
  * turn/step boundaries remain `@deepseek-ai/dsh-session` events.
  *
- * @module @deepseek-ai/dsh-agent/types
+ * @module @deepseek-ai/dsh-agent
  */
 
 import type { Context } from 'cordis'
@@ -10,7 +10,8 @@ import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 export type { AgentCancelCause } from '@deepseek-ai/dsh-session'
-import type { Inbox, InboxTarget } from './inbox.ts'
+import type { Inbox } from './inbox.ts'
+import type { InboxTarget } from './session-types.ts'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
@@ -289,20 +290,3 @@ declare module 'cordis' {
     'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
   }
 }
-
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * One normalized mutation of an agent's durable pending-message lists.
-     * Live dispatch precedes projection mutation, so synchronous observers may
-     * read the pre-splice inbox to recover the removed messages.
-     */
-    'agent/inbox/spliced': {
-      target: InboxTarget
-      start: number
-      removedCount?: number
-      inserted: UserMessage[]
-      outcome?: 'canceled'
-    }
-  }
-}
diff --git a/packages/core/agent/src/session-types.ts b/packages/core/agent/src/session-types.ts
new file mode 100644
index 0000000000..b54e56ea8f
--- /dev/null
+++ b/packages/core/agent/src/session-types.ts
@@ -0,0 +1,27 @@
+/**
+ * Durable agent session-event vocabulary shared with type-only consumers.
+ *
+ * @module @deepseek-ai/dsh-agent/types
+ */
+
+import type { UserMessage } from '@deepseek-ai/dsh-llm/types'
+
+/** One of the two ordered pending-message lists owned by an agent. */
+export type InboxTarget = 'next-turn' | 'next-step'
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * One normalized mutation of an agent's durable pending-message lists.
+     * Live dispatch precedes projection mutation, so synchronous observers may
+     * read the pre-splice inbox to recover the removed messages.
+     */
+    'agent/inbox/spliced': {
+      target: InboxTarget
+      start: number
+      removedCount?: number
+      inserted: UserMessage[]
+      outcome?: 'canceled'
+    }
+  }
+}
diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts
index 22bc09835f..4fee74793f 100644
--- a/packages/core/session/tests/gen-persistence-catalog.spec.ts
+++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts
@@ -89,7 +89,7 @@ describe('gen-persistence-catalog collectLogEvents', () => {
   it('hard-errors on an extends clause (inherited keys would escape the catalog)', () => {
     expect(() => collectLogEvents(make({
       'packages/group/fix/src/types.ts':
-        'interface Extra { \'fix/hidden\': { turn: number } }\ndeclare module \'@deepseek-ai/dsh-session\' {\n  interface SessionEventMap extends Extra {\n    /** Declared directly. */\n    \'fix/direct\': { turn: number }\n  }\n}\n',
+        'interface Extra { \'fix/hidden\': { turn: number } }\ndeclare module \'@deepseek-ai/dsh-session/types\' {\n  interface SessionEventMap extends Extra {\n    /** Declared directly. */\n    \'fix/direct\': { turn: number }\n  }\n}\n',
     }))).toThrow(/uses extends; inherited keys would join keyof SessionEventMap without a catalog row/)
   })
 
diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json
index 3279f17729..0fcc66b497 100644
--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -15,6 +15,10 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./presentation": {
       "types": "./lib/types/presentation.d.ts",
       "default": "./lib/types/presentation.js"
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 984fecab88..f5c5809544 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -14,41 +14,7 @@ import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { defineTool, parameterSchemaSpecToJsonSchema } from './schema.ts'
 import { TOOL_REGISTRY_SCHEDULER } from './index.ts'
 import type { CodeDispatchLog, ToolDefinition, ToolExecutionResult, ToolRegistry, ToolRunContext } from './index.ts'
-
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * One sub-dispatch STARTING inside a `run_code` program: the parent
-     * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
-     * numbered in submission order), and the tool `name` with its
-     * JSON-normalized `arguments` — the exact value dispatched, normalized
-     * BEFORE dispatch, so this append can never fail on payload shape.
-     * Appended when the scheduler actually starts the call (not at
-     * submission), so a start means the tool body pipeline was entered; a
-     * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
-     * ignores it; UIs use it for live per-sub-call running state and pair it
-     * with `tool/code-dispatch` by `subCallId` (timing = the two events'
-     * `time` fields).
-     */
-    'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
-    /**
-     * One bridged sub-dispatch SETTLING: the pairing ids (matching the
-     * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
-     * with the same JSON-normalized `arguments`, and the sub-call's complete
-     * model-facing outcome in `tool/result`'s own vocabulary
-     * (`content` + `isError`), so UIs render a sub-call through the exact
-     * code path that renders a native call. Every started sub-call settles
-     * with exactly one of these (abort included: the aborted pipeline result
-     * is an `isError` outcome).
-     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
-     * model context; persistence and UIs get every call. Appended inside the
-     * parent `run_code`'s execution (the bridge drains in-flight dispatches
-     * before returning), so its execution-enclosure relation holds by
-     * construction.
-     */
-    'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
-  }
-}
+import type {} from './types.ts'
 
 /** The model-facing name of the Code Mode tool. */
 export const RUN_CODE_NAME = 'run_code'
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 6338e54501..1a5f6a05eb 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -85,6 +85,7 @@ export {
 } from './json-schema.ts'
 
 export type { JsonValue } from '@deepseek-ai/dsh-session'
+export type { CodeDispatchEventData, CodeDispatchStartEventData } from './types.ts'
 
 export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts'
 export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts'
diff --git a/packages/core/tools/src/types.ts b/packages/core/tools/src/types.ts
new file mode 100644
index 0000000000..4dd6f7a9a8
--- /dev/null
+++ b/packages/core/tools/src/types.ts
@@ -0,0 +1,58 @@
+/**
+ * Durable Tool event vocabulary shared with type-only consumers.
+ *
+ * @module @deepseek-ai/dsh-tools/types
+ */
+
+import type { CallId } from '@deepseek-ai/dsh-llm/brand'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+
+/** Payload recorded when one nested Code Mode Tool dispatch starts. */
+export interface CodeDispatchStartEventData {
+  rootCallId: CallId
+  parentCallId: CallId
+  subCallId: CallId
+  name: string
+  arguments: unknown
+}
+
+/** Payload recorded when one nested Code Mode Tool dispatch settles. */
+export interface CodeDispatchEventData extends CodeDispatchStartEventData {
+  isError: boolean
+  content: ContentBlock[]
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * One sub-dispatch STARTING inside a `run_code` program: the parent
+     * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
+     * numbered in submission order), and the tool `name` with its
+     * JSON-normalized `arguments` — the exact value dispatched, normalized
+     * BEFORE dispatch, so this append can never fail on payload shape.
+     * Appended when the scheduler actually starts the call (not at
+     * submission), so a start means the tool body pipeline was entered; a
+     * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
+     * ignores it; UIs use it for live per-sub-call running state and pair it
+     * with `tool/code-dispatch` by `subCallId` (timing = the two events'
+     * `time` fields).
+     */
+    'tool/code-dispatch-start': CodeDispatchStartEventData
+    /**
+     * One bridged sub-dispatch SETTLING: the pairing ids (matching the
+     * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
+     * with the same JSON-normalized `arguments`, and the sub-call's complete
+     * model-facing outcome in `tool/result`'s own vocabulary
+     * (`content` + `isError`), so UIs render a sub-call through the exact
+     * code path that renders a native call. Every started sub-call settles
+     * with exactly one of these (abort included: the aborted pipeline result
+     * is an `isError` outcome).
+     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+     * model context; persistence and UIs get every call. Appended inside the
+     * parent `run_code`'s execution (the bridge drains in-flight dispatches
+     * before returning), so its execution-enclosure relation holds by
+     * construction.
+     */
+    'tool/code-dispatch': CodeDispatchEventData
+  }
+}
diff --git a/packages/interaction/commands/package.json b/packages/interaction/commands/package.json
index 7d35603a79..cd62942a5f 100644
--- a/packages/interaction/commands/package.json
+++ b/packages/interaction/commands/package.json
@@ -15,6 +15,10 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./brand": {
       "types": "./lib/types/brand.d.ts",
       "default": "./lib/types/brand.js"
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index ba7b449228..9f4110568e 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -11,24 +11,12 @@ import type { Session, SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-se
 import { CommandId } from './brand.ts'
 
 export { CommandId } from './brand.ts'
+export type { CommandSource, CommandSourceMap } from './types.ts'
 
 export const name = 'commands'
 
 const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u
 
-/**
- * Producer record for one command invocation (the `command/run` event's
- * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
- * shape; minimal today because every executor caller is a human-facing UI
- * surface dispatching a human-typed line, so the sole variant is `user`.
- */
-export interface CommandSourceMap {
-  user: { kind: 'user' }
-}
-
-/** The union over {@link CommandSourceMap} — who issued a command line. */
-export type CommandSource = CommandSourceMap[keyof CommandSourceMap]
-
 /** Immutable metadata for a command's optional unstructured input. */
 export interface CommandInputDescriptor {
   /** Placeholder shown before the user supplies free-form input. */
@@ -131,34 +119,6 @@ class CommandLayer implements ScopeLayer {
   }
 }
 
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * A resolved slash command entered its handler. Log-only (never model
-     * surface); paired with `command/done` by `commandId`, mirroring the
-     * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
-     * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
-     * separator whitespace included), so a consumer (a projection unit
-     * folding its own command records, a rich command card) never re-parses
-     * a line. `args` is absent when the definition sets `recordInput: false`
-     * because an authoritative domain event owns the input payload.
-     */
-    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
-    /**
-     * The paired command settled. `kind`/`text` carry the handler's verbatim
-     * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
-     * rendered failure). A successful command may identify the earlier
-     * authoritative domain event for a richer client-computed presentation.
-     */
-    'command/done': {
-      commandId: CommandId
-      kind: 'success' | 'error'
-      text?: string
-      sourceEventSeq?: number
-    }
-  }
-}
-
 declare module 'cordis' {
   interface Context {
     commands: CommandService
diff --git a/packages/interaction/commands/src/types.ts b/packages/interaction/commands/src/types.ts
new file mode 100644
index 0000000000..2b81071d37
--- /dev/null
+++ b/packages/interaction/commands/src/types.ts
@@ -0,0 +1,48 @@
+/**
+ * Durable command event vocabulary shared with type-only consumers.
+ *
+ * @module @deepseek-ai/dsh-commands/types
+ */
+
+import type { CommandId } from './brand.ts'
+
+/**
+ * Producer record for one command invocation (the `command/run` event's
+ * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
+ * shape; minimal today because every executor caller is a human-facing UI
+ * surface dispatching a human-typed line, so the sole variant is `user`.
+ */
+export interface CommandSourceMap {
+  user: { kind: 'user' }
+}
+
+/** The union over {@link CommandSourceMap} — who issued a command line. */
+export type CommandSource = CommandSourceMap[keyof CommandSourceMap]
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * A resolved slash command entered its handler. Log-only (never model
+     * surface); paired with `command/done` by `commandId`, mirroring the
+     * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
+     * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
+     * separator whitespace included), so a consumer (a projection unit
+     * folding its own command records, a rich command card) never re-parses
+     * a line. `args` is absent when the definition sets `recordInput: false`
+     * because an authoritative domain event owns the input payload.
+     */
+    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
+    /**
+     * The paired command settled. `kind`/`text` carry the handler's verbatim
+     * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
+     * rendered failure). A successful command may identify the earlier
+     * authoritative domain event for a richer client-computed presentation.
+     */
+    'command/done': {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
+  }
+}
diff --git a/packages/llm/llm-retry/package.json b/packages/llm/llm-retry/package.json
index 1685d0e552..809b5d14e5 100644
--- a/packages/llm/llm-retry/package.json
+++ b/packages/llm/llm-retry/package.json
@@ -19,10 +19,6 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
-    "./brand": {
-      "types": "./lib/types/brand.d.ts",
-      "default": "./lib/types/brand.js"
-    },
     "./package.json": "./package.json"
   },
   "files": [
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index c698b68446..5144939289 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,5 +1,7 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
-import type { RetryId } from './brand.ts'
+import { RetryId } from './brand.ts'
+
+export { RetryId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
index 33ac3a19fa..917a6d03f8 100644
--- a/packages/llm/llm-retry/tests/invariant.spec.ts
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -5,7 +5,7 @@ import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
 import { providerForOpenStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 3a605bd40e..9e17290b43 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
 import type {} from '../src/index.ts'
 
 const dirs: string[] = []
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index 9251eef2c0..bfbf6a89ee 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -10,7 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
+import { CompactionId } from '@deepseek-ai/dsh-compact/types'
 import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
 import {
   estimateContent,
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index 65771fc877..3f66e0564b 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -7,7 +7,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
+import { CompactionId } from '@deepseek-ai/dsh-compact/types'
 
 const ZERO: TokenUsageProjection = {
   uncachedInputTokens: 0,
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 0276199e3e..db60b695b1 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
+import { CompactionId } from '@deepseek-ai/dsh-compact/types'
 import LlmService, { CallId, createUserMessage, GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
 import {
   type ReplayEntry,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f1ee272761..6fb20b9718 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1495,6 +1495,9 @@ importers:
 
   packages/client/runtime:
     dependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
       '@deepseek-ai/dsh-client-connection':
         specifier: workspace:^
         version: link:../connection
@@ -1522,6 +1525,9 @@ importers:
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
         version: link:../../session/session-title
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
       immer:
         specifier: ^10.1.1
         version: 10.2.0
@@ -1656,6 +1662,9 @@ importers:
         specifier: ^2.0.0
         version: 2.1.1
     devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
@@ -1677,6 +1686,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../../compact/compact
@@ -1686,6 +1698,9 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm-retry':
+        specifier: workspace:^
+        version: link:../../llm/llm-retry
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
         version: link:../../interaction/permission
@@ -1701,6 +1716,9 @@ importers:
       '@deepseek-ai/dsh-tool-todo':
         specifier: workspace:^
         version: link:../../todo/tool-todo
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 5294242e27..173d4222cb 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -18,8 +18,11 @@ const OUT = 'docs/persistence-catalog.md'
  * doc-typecheck, since their imported types are not standalone-compilable). */
 const FENCE = 'ts persistence-catalog'
 
-/** The package whose module id plugin merges augment (`declare module '…'`). */
-const SESSION_MODULE = '@deepseek-ai/dsh-session'
+/** The package that owns the durable event vocabulary. */
+const SESSION_PACKAGE = '@deepseek-ai/dsh-session'
+
+/** The type-only module that plugin declaration merges augment. */
+const SESSION_TYPES_MODULE = '@deepseek-ai/dsh-session/types'
 
 /** Event-envelope declarations rendered before the per-event vocabulary. */
 const EVENT_ENVELOPE_TYPE_NAMES = [
@@ -115,7 +118,7 @@ function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string
 /**
  * Every `interface SessionEventMap` declaration in a source file: the owning
  * top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration
- * merge inside a `declare module '@deepseek-ai/dsh-session'` block. Both forms
+ * merge inside a `declare module '@deepseek-ai/dsh-session/types'` block. Both forms
  * declare members of the SAME merged interface, so both are catalogued
  * uniformly. `topLevel` distinguishes the owning form so the caller can verify
  * it actually lives in the owning package — an unrelated local interface that
@@ -125,7 +128,7 @@ function sessionEventMapDecls(sf: ts.SourceFile): { decl: ts.InterfaceDeclaratio
   const decls: { decl: ts.InterfaceDeclaration; topLevel: boolean }[] = []
   for (const stmt of sf.statements) {
     if (ts.isInterfaceDeclaration(stmt) && stmt.name.text === 'SessionEventMap') decls.push({ decl: stmt, topLevel: true })
-    if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === SESSION_MODULE
+    if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === SESSION_TYPES_MODULE
       && stmt.body && ts.isModuleBlock(stmt.body)) {
       for (const inner of stmt.body.statements) {
         if (ts.isInterfaceDeclaration(inner) && inner.name.text === 'SessionEventMap') decls.push({ decl: inner, topLevel: false })
@@ -174,8 +177,8 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
         // the owning package. Same-named interfaces elsewhere are different
         // types and must not enter the on-disk catalog.
         const pkg = packageNameFor(rel, scanRoot)
-        if (pkg !== SESSION_MODULE) {
-          violations.push(`top-level interface SessionEventMap (${declSrc}) is outside ${SESSION_MODULE} (package ${pkg ?? 'unknown'}). Rename the interface, or contribute events via declare module '${SESSION_MODULE}'.`)
+        if (pkg !== SESSION_PACKAGE) {
+          violations.push(`top-level interface SessionEventMap (${declSrc}) is outside ${SESSION_PACKAGE} (package ${pkg ?? 'unknown'}). Rename the interface, or contribute events via declare module '${SESSION_TYPES_MODULE}'.`)
           continue
         }
         const exported = decl.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
@@ -243,7 +246,7 @@ export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelop
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
     if (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue
-    if (packageNameFor(rel, scanRoot) !== SESSION_MODULE) continue
+    if (packageNameFor(rel, scanRoot) !== SESSION_PACKAGE) continue
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
     for (const stmt of sf.statements) {
       if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue
@@ -352,7 +355,7 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types` in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index cd9d020779..73431101da 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -114,12 +114,12 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
-      "source": "packages/core/agent/src/inbox.ts"
+      "source": "packages/core/agent/src/session-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "CancelOptions",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
@@ -129,22 +129,22 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "Agent",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "PreStepDecision",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "RequestErrorAction",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "SessionStartSource",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/scope.md",
@@ -1698,12 +1698,12 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "AgentStatus",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "AgentOptions",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     }
   ]
 }
diff --git a/tsconfig.base.json b/tsconfig.base.json
index d8b777a2ad..c7be2d4925 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -71,8 +71,11 @@
       "@deepseek-ai/dsh-llm-retry/types": ["./packages/llm/llm-retry/src/types.ts"],
       "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"],
       "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"],
+      "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"],
       "@deepseek-ai/dsh-compact/checkpoint": ["./packages/compact/compact/src/checkpoint.ts"],
+      "@deepseek-ai/dsh-compact/types": ["./packages/compact/compact/src/types.ts"],
       "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"],
+      "@deepseek-ai/dsh-tools/types": ["./packages/core/tools/src/types.ts"],
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
       "@deepseek-ai/dsh-user-approval/types": ["./packages/interaction/user-approval/src/types.ts"],
       "@deepseek-ai/dsh-user-interaction/types": ["./packages/interaction/user-interaction/src/types.ts"],

From 1b1e170c1f291b53af8fa5ac1257530a7e59f8fd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:43:37 +0800
Subject: [PATCH 240/262] refactor(agent): restore conventional types
 entrypoint

---
 packages/core/agent/package.json                       | 4 ++--
 packages/core/agent/src/inbox.ts                       | 2 +-
 packages/core/agent/src/index.ts                       | 2 +-
 packages/core/agent/src/runtime-types.ts               | 2 +-
 packages/core/agent/src/{session-types.ts => types.ts} | 0
 scripts/type-equiv.manifest.json                       | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)
 rename packages/core/agent/src/{session-types.ts => types.ts} (100%)

diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index d186f32d03..9f64d33e75 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -16,8 +16,8 @@
       "default": "./lib/invariant.js"
     },
     "./types": {
-      "types": "./lib/types/session-types.d.ts",
-      "default": "./lib/types/session-types.js"
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index 2db3c4b580..c6b9204c92 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -6,7 +6,7 @@
 
 import type { MessageId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEventMap, UserMessage } from '@deepseek-ai/dsh-session'
-import type { InboxTarget } from './session-types.ts'
+import type { InboxTarget } from './types.ts'
 
 /** Mutable state privately owned by an {@link Inbox}. */
 type InboxState = Record<InboxTarget, UserMessage[]>
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index e35bc06211..4df0056c1a 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -16,7 +16,7 @@ import type { TypeRTContext, TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
 import type { Agent, AgentOptions } from './runtime-types.ts'
 
 export * from './runtime-types.ts'
-export * from './session-types.ts'
+export * from './types.ts'
 export * from './inbox.ts'
 export * from './model-selection.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
diff --git a/packages/core/agent/src/runtime-types.ts b/packages/core/agent/src/runtime-types.ts
index 072f509f8f..3698c05018 100644
--- a/packages/core/agent/src/runtime-types.ts
+++ b/packages/core/agent/src/runtime-types.ts
@@ -11,7 +11,7 @@ import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-a
 import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 export type { AgentCancelCause } from '@deepseek-ai/dsh-session'
 import type { Inbox } from './inbox.ts'
-import type { InboxTarget } from './session-types.ts'
+import type { InboxTarget } from './types.ts'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
diff --git a/packages/core/agent/src/session-types.ts b/packages/core/agent/src/types.ts
similarity index 100%
rename from packages/core/agent/src/session-types.ts
rename to packages/core/agent/src/types.ts
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 73431101da..fccabef852 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -114,7 +114,7 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
-      "source": "packages/core/agent/src/session-types.ts"
+      "source": "packages/core/agent/src/types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",

From 924cfcef9595e101ec090d1f118c8f557e11469d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:56:29 +0800
Subject: [PATCH 241/262] fix: coverage

---
 .../src/client/contract/conversation.ts        |  4 ++++
 .../client/sessions/conversation-assembler.ts  |  5 ++---
 .../sessions/conversation-location-index.ts    |  2 +-
 .../client/test-runtime/tests/runtime.spec.tsx |  3 ++-
 .../src/client/contract/chat-nodes.ts          |  2 +-
 .../src/client/contract/slots.ts               |  2 +-
 .../tests/chat-snapshot-fixture.ts             |  7 +++++--
 .../ui-conversation/tests/chat-view.spec.tsx   | 18 ++++++++++--------
 .../tests/produced-files.spec.tsx              |  7 +++++--
 .../client/ui-settings/tests/apply.spec.ts     | 12 ++++++------
 packages/client/ui-slots/src/index.ts          | 10 ++++++++--
 packages/typert/generator/src/analyzer.ts      |  2 +-
 12 files changed, 46 insertions(+), 28 deletions(-)

diff --git a/packages/client/runtime/src/client/contract/conversation.ts b/packages/client/runtime/src/client/contract/conversation.ts
index fb98965d25..9507046b33 100644
--- a/packages/client/runtime/src/client/contract/conversation.ts
+++ b/packages/client/runtime/src/client/contract/conversation.ts
@@ -1,6 +1,10 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
 
+/* oxlint-disable typescript/no-duplicate-type-constituents, typescript/no-redundant-type-constituents --
+ * The unaugmented declaration-merge maps intentionally resolve to never in the Runtime program;
+ * installed business packages supply their concrete keys in consuming Client programs. */
+
 /** One raw log event plus its optional envelope-level presentation view. */
 export interface ConversationEventInput {
   readonly event: SessionEvent
diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
index 811bd43ebf..bdd89f56a4 100644
--- a/packages/client/runtime/src/client/sessions/conversation-assembler.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -712,9 +712,8 @@ export class ConversationNodeAssembler {
     context: InternalContext,
     scope: ConversationLocationDataScope,
   ): ConversationLocationData | null {
-    const build = context.definition.buildLocationData
-    if (build === undefined) return null
-    const data = build(contextSnapshot(context), scope)
+    if (context.definition.buildLocationData === undefined) return null
+    const data = context.definition.buildLocationData(contextSnapshot(context), scope)
     if (data === null) return null
     if (data.kind !== scope) {
       throw new Error(
diff --git a/packages/client/runtime/src/client/sessions/conversation-location-index.ts b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
index c842a230a9..f4ce189b13 100644
--- a/packages/client/runtime/src/client/sessions/conversation-location-index.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
@@ -20,7 +20,7 @@ export interface ConversationLocationDataChange {
 class MutableLocationDataStore {
   private entries = new Map<string, OwnedLocationData>()
 
-  get<Key extends string>(key: Key): unknown {
+  get(key: string): unknown {
     return this.entries.get(key)?.value
   }
 
diff --git a/packages/client/test-runtime/tests/runtime.spec.tsx b/packages/client/test-runtime/tests/runtime.spec.tsx
index f92d21b4b5..08a82ee251 100644
--- a/packages/client/test-runtime/tests/runtime.spec.tsx
+++ b/packages/client/test-runtime/tests/runtime.spec.tsx
@@ -18,6 +18,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'trt.panel': { kind: 'single'; scope: 'root'; owner: { label?: string } }
     'trt.chat': { kind: 'single'; scope: 'session' }
     'trt.rows': { kind: 'list'; scope: 'root' }
+    'trt.rows.hole': { kind: 'single'; scope: 'root' }
   }
 }
 
@@ -419,7 +420,7 @@ describe('feature mount and disposal', () => {
     await feature.dispose()
     await feature.dispose() // idempotent
     expect(runtime.slots.entries('trt.rows')).toHaveLength(0)
-    expect(runtime.slots.spec('trt.rows.hole' as never)).toBeUndefined()
+    expect(runtime.slots.spec('trt.rows.hole')).toBeUndefined()
     expect(runtime.ctx.get('feature-service')).toBeUndefined()
     expect(view.queryByTestId('row')).toBeNull()
     await runtime.dispose()
diff --git a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
index 3415c502a5..787f391006 100644
--- a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
+++ b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
@@ -7,7 +7,7 @@ import type {
 export interface ChatNodeDataMap {}
 
 /** Renderer kinds contributed by the currently installed Chat business modules. */
-export type ChatNodeKind = keyof ChatNodeDataMap & string
+export type ChatNodeKind = Extract<keyof ChatNodeDataMap, string>
 
 /** Final Chat Node narrowed to one registered renderer kind and payload. */
 export type ChatNode<Kind extends ChatNodeKind = ChatNodeKind> = {
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index eec5450e2d..56fca2381c 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -210,7 +210,7 @@ export interface TurnTailOwnerProps {
 }
 
 /** Hook constrained to business data published on the current Chat Node's Turn. */
-export type UseChatNodeTurnData = <Key extends keyof ConversationTurnDataMap & string>(
+export type UseChatNodeTurnData = <Key extends Extract<keyof ConversationTurnDataMap, string>>(
   key: Key,
 ) => Readonly<ConversationTurnDataMap[Key]> | undefined
 
diff --git a/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
index c675554ea0..fb343f0f68 100644
--- a/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
+++ b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
@@ -78,13 +78,16 @@ class FixtureLocationIndex implements ChatLocationNodeIndex {
 class FixtureTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
   private readonly values = new Map<string, unknown>()
 
-  get<Key extends keyof ConversationTurnDataMap & string>(
+  get<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
   ): Readonly<ConversationTurnDataMap[Key]> | undefined {
     return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
   }
 
-  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+  set<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+    key: Key,
+    value: ConversationTurnDataMap[Key],
+  ): void {
     this.values.set(key, value)
   }
 }
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 296dd85966..ca6223826e 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -181,12 +181,14 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     if (key !== 'conversation.chat.node') return opts?.fallback ?? null
     const nodeOwner = owner as RoutedChatNodeOwner
     const nodeKey = opts?.hookContext as string | undefined
-    const useTurnData = ((dataKey: string) => props.useSession((snapshot) => {
-      const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
-      return location?.kind === 'turn' || location?.kind === 'step'
-        ? location.turn.data.get(dataKey as never)
-        : undefined
-    })) as UseChatNodeTurnData
+    const useTurnData = ((dataKey: string) => {
+      return props.useSession((snapshot) => {
+        const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
+        return location?.kind === 'turn' || location?.kind === 'step'
+          ? location.turn.data.get(dataKey as never)
+          : undefined
+      })
+    }) as UseChatNodeTurnData
     const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
       { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
@@ -226,7 +228,7 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
       case 'unknown':
         return <UnknownNodeView {...nodeProps<'unknown'>()} />
       case 'tool-call': {
-        const block = (nodeOwner.node.data as { readonly root: ToolCallBlock }).root
+        const block = nodeOwner.node.data.root
         const toolName = 'kind' in block ? block.call?.name ?? '' : block.name
         const tool = {
           callId: block.callId,
@@ -843,7 +845,7 @@ describe('ChatView', () => {
         mounted()
         return () => { unmounted() }
       }, [])
-      const root = (node.data as { readonly root: ToolCallBlock }).root
+      const root = node.data.root
       return (
         <div data-testid="stateful-tool" data-state={'kind' in root ? 'settled' : 'running'}>
           {root.callId}
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index b7ca73a79f..b8e7cd111e 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -34,13 +34,16 @@ afterEach(cleanup)
 class TestTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
   private readonly values = new Map<string, unknown>()
 
-  get<Key extends keyof ConversationTurnDataMap & string>(
+  get<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
   ): Readonly<ConversationTurnDataMap[Key]> | undefined {
     return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
   }
 
-  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+  set<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+    key: Key,
+    value: ConversationTurnDataMap[Key],
+  ): void {
     this.values.set(key, value)
   }
 }
diff --git a/packages/client/ui-settings/tests/apply.spec.ts b/packages/client/ui-settings/tests/apply.spec.ts
index c46a5bf25c..3133ad4d76 100644
--- a/packages/client/ui-settings/tests/apply.spec.ts
+++ b/packages/client/ui-settings/tests/apply.spec.ts
@@ -44,8 +44,8 @@ describe('ui-settings apply', () => {
     declare(before.slots)
     await before.ctx.plugin({ inject: [...inject], apply }).await()
     expect(before.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
-    for (const [name, spec] of Object.entries(CHILD_SPECS)) {
-      expect(before.slots.spec(name as never)).toEqual(spec)
+    for (const name of Object.keys(CHILD_SPECS) as Array<keyof typeof CHILD_SPECS>) {
+      expect(before.slots.spec(name)).toEqual(CHILD_SPECS[name])
     }
 
     const after = await bench()
@@ -120,8 +120,8 @@ describe('ui-settings apply', () => {
     declare(b.slots)
     await Promise.resolve()
     expect(b.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
-    for (const [name, spec] of Object.entries(CHILD_SPECS)) {
-      expect(b.slots.spec(name as never)).toEqual(spec)
+    for (const name of Object.keys(CHILD_SPECS) as Array<keyof typeof CHILD_SPECS>) {
+      expect(b.slots.spec(name)).toEqual(CHILD_SPECS[name])
     }
   })
 
@@ -132,8 +132,8 @@ describe('ui-settings apply', () => {
     await fiber.await()
     await fiber.dispose()
     expect(b.slots.entries('sidebar.settings')).toHaveLength(0)
-    for (const name of Object.keys(CHILD_SPECS)) {
-      expect(b.slots.spec(name as never)).toBeUndefined()
+    for (const name of Object.keys(CHILD_SPECS) as Array<keyof typeof CHILD_SPECS>) {
+      expect(b.slots.spec(name)).toBeUndefined()
     }
   })
 })
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 4ed6ecf519..d6c1824c99 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -677,7 +677,10 @@ export class SlotCore {
   >(
     options: BaseOptions<K, EntryKey, D, H, M, N> & { inject?: undefined },
     component: C
-      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<
+        K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string,
+        HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>
+      >>
       & RendersCheck<C, D>,
   ): () => void
   /**
@@ -702,7 +705,10 @@ export class SlotCore {
   >(
     options: BaseOptions<K, EntryKey, D, H, M, N> & { inject: (...args: InjectParams<K, H>) => I },
     component: C
-      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<
+        K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string,
+        HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>
+      >>
       & RendersCheck<C, D>,
   ): () => void
   /* jscpd:ignore-end */
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 6f495aa318..68736f0b3a 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -274,7 +274,7 @@ export class WorkspaceAnalyzer {
 
   constructor(options: WorkspaceAnalyzerOptions) {
     this.options = {
-      root: resolve(options.root),
+      root: realPath(options.root),
       hostConfig: options.hostConfig ?? 'tsconfig.host.json',
       clientConfig: options.clientConfig ?? 'tsconfig.client.json',
       faces: options.faces ?? ['host', 'client'],

From 27682b938493cfe9e4580a568f006d561d1302de Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:56:34 +0800
Subject: [PATCH 242/262] fix: docs

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 +-
 docs/config-catalog.i18n.yaml                 |  2 +-
 docs/config-catalog.md                        |  4 +-
 docs/event-producer-consumer.i18n.yaml        |  2 +-
 docs/event-producer-consumer.md               | 38 +++++++++----------
 docs/module-graph.i18n.yaml                   |  2 +-
 docs/module-graph.md                          |  6 ++-
 docs/persistence-catalog.i18n.yaml            |  2 +-
 docs/persistence-catalog.md                   | 32 +++++++---------
 docs/subsystems/commands.i18n.yaml            |  4 +-
 docs/subsystems/commands.md                   |  4 +-
 docs/subsystems/commands.zh.md                |  4 +-
 docs/subsystems/core.i18n.yaml                |  4 +-
 docs/subsystems/core.md                       | 26 ++++++-------
 docs/subsystems/core.zh.md                    | 26 ++++++-------
 docs/subsystems/tools.i18n.yaml               |  4 +-
 docs/subsystems/tools.md                      | 14 +++----
 docs/subsystems/tools.zh.md                   | 14 +++----
 18 files changed, 96 insertions(+), 96 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index 264b900b74..d19cd86c7d 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: f9768a652c7b0d2d29939fac83b201bc904e3210
-2026-08-09-client-conversation-node-assembly.zh.md: 408d61f73b3b317214cb10b26f522e7680de3f92
+2026-08-09-client-conversation-node-assembly.md: 9952f8fac0f2a3b0fe72cc97ae9a8fb4f96ace08
+2026-08-09-client-conversation-node-assembly.zh.md: f27a82459cdacdb4a2da27cf12b30c93f2dfdf64
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 9607dc8d1a..12f3e2861c 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 5f3bc744b25bf20d50e88ce75812fe8bd624905a
+config-catalog.md: 7278447cf85c2b25f7dd42e10e4b0b1cbd7eb96b
 config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 22e21edc0b..7278447cf8 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -917,7 +917,7 @@ Requires: `agents`
 export type Config = Readonly<Record<string, never>>
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:33`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/index.ts:24`](../packages/llm/llm-retry/src/index.ts)
 
 ## `@deepseek-ai/dsh-lsp-local`
 
@@ -2325,7 +2325,7 @@ export interface Config {
 export type ToolPresentationMode = 'native' | 'code' | 'both'
 ```
 
-Source: [`packages/core/tools/src/index.ts:623`](../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:624`](../packages/core/tools/src/index.ts)
 
 ## `@deepseek-ai/dsh-typert-loader`
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 41da1ee118..812b490bef 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 5b36725402c0a12c5e2a09c743c2e7cf28d2c14a
+event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa
 event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index a8263b70c1..05ff62a391 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -8,20 +8,20 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
-| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:159`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:168`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:197`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:205`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:186`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:231`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:244`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:260`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:217`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:174`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:134`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -44,12 +44,12 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:192`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:174`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:149`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:161`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
+| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:182`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
 | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index d6f09d6696..24ddaad77c 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.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 docs/module-graph.md
-module-graph.md: e7d6b47e709c3edf4dcdb506bd8f2be0c717aaab
+module-graph.md: a248ed4fcb8abc17ffc6982d2733b3c3c2a2a635
 module-graph.zh.md: 255253bcfa9cfad1ab85602dfa9f953a02dfc427
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 767ebfcfde..a248ed4fcb 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -1000,14 +1000,18 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
+  pkg_client_ui_conversation --> pkg_agent
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
   pkg_client_ui_conversation --> pkg_client_ui_slash
   pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_commands
   pkg_client_ui_conversation --> pkg_compact
   pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_llm_retry
   pkg_client_ui_conversation --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_tools
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1354,7 +1358,7 @@ flowchart TD
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm-retry`](../packages/llm/llm-retry), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
 | [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 19c1f1b280..d814b6ac6e 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
-persistence-catalog.md: 614f6afbeb8fbaadbb43a76782c5a345180b25e7
+persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8
 persistence-catalog.zh.md: 364912b88c3b2c5efd92a616034be9ef5025ee67
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 76487ca3d4..c9aa15cd82 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -3,7 +3,7 @@
 
 # Session Persistence Event Catalog
 
-Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types` in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
@@ -101,7 +101,7 @@ Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src
 }
 ```
 
-Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:19`](../packages/core/agent/src/types.ts)
 
 ### `approval/*`
 
@@ -212,7 +212,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:153`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/types.ts:41`](../packages/interaction/commands/src/types.ts)
 
 #### `command/run` — log-only
 
@@ -230,7 +230,7 @@ Source: [`packages/interaction/commands/src/index.ts:153`](../packages/interacti
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:146`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/types.ts:34`](../packages/interaction/commands/src/types.ts)
 
 ### `compact/*`
 
@@ -244,7 +244,7 @@ Source: [`packages/interaction/commands/src/index.ts:146`](../packages/interacti
 'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:69`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:71`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -268,7 +268,7 @@ Source: [`packages/compact/compact/src/types.ts:69`](../packages/compact/compact
 }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:79`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:81`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -281,7 +281,7 @@ Source: [`packages/compact/compact/src/types.ts:79`](../packages/compact/compact
 'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:21`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:23`](../packages/compact/compact/src/types.ts)
 
 #### `compact/summary` — log-only
 
@@ -333,7 +333,7 @@ Source: [`packages/compact/compact/src/types.ts:21`](../packages/compact/compact
 
 Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/compact/compact/src/types.ts:31`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:33`](../packages/compact/compact/src/types.ts)
 
 ### `feedback/*`
 
@@ -417,7 +417,7 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-
 'llm/retry': LlmRetryEventData
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:20`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts)
 
 #### `llm/retry-started` — log-only
 
@@ -426,7 +426,7 @@ Source: [`packages/llm/llm-retry/src/index.ts:20`](../packages/llm/llm-retry/src
 'llm/retry-started': LlmRetryStartedEventData
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:22`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src/types.ts)
 
 ### `permission/*`
 
@@ -648,12 +648,10 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
  * before returning), so its execution-enclosure relation holds by
  * construction.
  */
-'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+'tool/code-dispatch': CodeDispatchEventData
 ```
 
-Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
-
-Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
+Source: [`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts)
 
 #### `tool/code-dispatch-start` — log-only
 
@@ -671,12 +669,10 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c
  * with `tool/code-dispatch` by `subCallId` (timing = the two events'
  * `time` fields).
  */
-'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+'tool/code-dispatch-start': CodeDispatchStartEventData
 ```
 
-Types: [CallId](subsystems/core.md)
-
-Source: [`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
+Source: [`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts)
 
 #### `tool/result` — surface
 
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 9466165680..32c5f15c15 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: 7f4e4e87d7206be3e46c7076ee5e8ab6a7589f9a
-commands.zh.md: 0f8ff31bca5f62824912f53aee8dbc32db4c331b
+commands.md: 5e280d659c2a74b3d8ba20f362922e9eb4e0b84c
+commands.zh.md: 24f099d1926f7dba45122bdc53c23a4274e3f507
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index 7f4e4e87d7..5e280d659c 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -161,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:267`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -183,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:134`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 0f8ff31bca..24f099d192 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -161,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:267`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -183,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:134`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 2fb9c399be..70ceac3b11 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: ec9a966164f2b706ae16341c628fb8f849eb7382
-core.zh.md: 4de168fd9714a935b4d9b08bbabd52492d1ea1cc
+core.md: 27c4359e360223d336cd94695bb45a79f0fd370c
+core.zh.md: 4e7519665b6d9efb8075546d93325debd961905d
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index ec9a966164..27c4359e36 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -547,7 +547,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:254`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
@@ -575,7 +575,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:159`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentdisposed--emit"></a>
 
@@ -597,7 +597,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:168`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agenterror--emit"></a>
 
@@ -621,7 +621,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:290`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxclaimed--emit"></a>
 
@@ -645,7 +645,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:197`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxdiscarded--emit"></a>
 
@@ -666,7 +666,7 @@ One message was discarded from the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:205`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxinserted--emit"></a>
 
@@ -687,7 +687,7 @@ One message entered the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:186`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentpre-step--waterfall"></a>
 
@@ -712,7 +712,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:231`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest--waterfall"></a>
 
@@ -738,7 +738,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:244`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest-error--waterfall"></a>
 
@@ -767,7 +767,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:260`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentsession-start--emit"></a>
 
@@ -791,7 +791,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:217`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentstatus--emit"></a>
 
@@ -814,7 +814,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:178`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentturn-stopping--serial"></a>
 
@@ -845,7 +845,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:278`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agent-loop-events"></a>
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 4de168fd97..4e7519665b 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -555,7 +555,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:254`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
@@ -583,7 +583,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:159`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentdisposed--emit"></a>
 
@@ -605,7 +605,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:168`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agenterror--emit"></a>
 
@@ -629,7 +629,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:290`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxclaimed--emit"></a>
 
@@ -653,7 +653,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:197`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxdiscarded--emit"></a>
 
@@ -674,7 +674,7 @@ One message was discarded from the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:205`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxinserted--emit"></a>
 
@@ -695,7 +695,7 @@ One message entered the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:186`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentpre-step--waterfall"></a>
 
@@ -720,7 +720,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:231`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest--waterfall"></a>
 
@@ -746,7 +746,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:244`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest-error--waterfall"></a>
 
@@ -775,7 +775,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:260`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentsession-start--emit"></a>
 
@@ -799,7 +799,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:217`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentstatus--emit"></a>
 
@@ -822,7 +822,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:178`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentturn-stopping--serial"></a>
 
@@ -853,7 +853,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:278`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agent-loop-events"></a>
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index d015cdb638..1384b3888b 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: f06db58b9b52fcb2c325ff813406cd2dc460ea7b
-tools.zh.md: cca4bf9faa870d9414d95f785b67e0393e469cdd
+tools.md: 83389f39c3188fc251504ed5786249ff1921acae
+tools.zh.md: 45cb85b3f2940f84b46bc58406bc8255cbe08be7
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index f06db58b9b..83389f39c3 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -554,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:747`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
@@ -579,7 +579,7 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 'tools/change'(): void
 ```
 
-Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:192`](../../packages/core/tools/src/index.ts)
 
 <a id="toolscode-dispatch-log--waterfall"></a>
 
@@ -605,7 +605,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 
 Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:174`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsexecute--waterfall"></a>
 
@@ -629,7 +629,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:149`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspost-execute--waterfall"></a>
 
@@ -654,7 +654,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:161`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspre-execute--waterfall"></a>
 
@@ -677,7 +677,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:138`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsresult--emit"></a>
 
@@ -698,5 +698,5 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:182`](../../packages/core/tools/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index cca4bf9faa..45cb85b3f2 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -554,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:747`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
@@ -579,7 +579,7 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 'tools/change'(): void
 ```
 
-Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:192`](../../packages/core/tools/src/index.ts)
 
 <a id="toolscode-dispatch-log--waterfall"></a>
 
@@ -605,7 +605,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 
 Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:174`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsexecute--waterfall"></a>
 
@@ -629,7 +629,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:149`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspost-execute--waterfall"></a>
 
@@ -654,7 +654,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:161`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspre-execute--waterfall"></a>
 
@@ -677,7 +677,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:138`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsresult--emit"></a>
 
@@ -698,5 +698,5 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:182`](../../packages/core/tools/src/index.ts)
 <!-- END GENERATED cordis-surface -->

From e11f630fcdbd155dcf94f35d208a8b0516703f23 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:12:54 +0800
Subject: [PATCH 243/262] fix(client): address remaining conversation review
 feedback

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 +--
 ...08-09-client-conversation-node-assembly.md |  2 ++
 ...09-client-conversation-node-assembly.zh.md |  2 ++
 docs/subsystems/compaction.i18n.yaml          |  4 +--
 docs/subsystems/compaction.md                 |  2 +-
 docs/subsystems/compaction.zh.md              |  2 +-
 .../src/client/chat/TurnTailNodeView.tsx      |  6 ++--
 .../src/client/contract/chat-nodes.ts         |  2 +-
 .../ui-conversation/tests/chat-view.spec.tsx  | 36 ++++++++++++++-----
 .../src/client/turn-deliverables.ts           |  4 ++-
 vitest.config.ts                              |  1 +
 11 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index d19cd86c7d..b76951347b 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 9952f8fac0f2a3b0fe72cc97ae9a8fb4f96ace08
-2026-08-09-client-conversation-node-assembly.zh.md: f27a82459cdacdb4a2da27cf12b30c93f2dfdf64
+2026-08-09-client-conversation-node-assembly.md: 16a39539064644e5467f701789a7e2ef1f7ff172
+2026-08-09-client-conversation-node-assembly.zh.md: 0e0fbdf8f3320393022528e6e3fe2cf0d492a1d3
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 9952f8fac0..16a3953906 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -394,6 +394,8 @@ History-path tests cover complete replace, non-overlapping prepend, overlapping-
 
 A new business node can register its matcher, State transitions, optional Location data, final target Node, and renderer locally without changing Session's business switch. `ChatNodeDataMap` and the Location data maps let a business package merge strongly typed data into the contract; every related Event must still expose a stable ID derivable from that Event alone.
 
+Host business packages declaration-merge their durable Event members into `@deepseek-ai/dsh-session/types`, while Client Definitions type-only import the corresponding business package `/types` subpaths. Augmenting the declaring interface rather than a re-export barrel gives the independent Host and Client TypeScript programs the same Event narrowing without pulling Host runtime into the Client graph.
+
 Initial tail, older prepend, and live append share one set of Context invariants. Missing starts, Reader window gaps, unknown Locations, and high-frequency deltas are explicit engine states and require no direction-specific business cache.
 
 Append does not scan historical Contexts; prepend replays only Contexts whose Matches, Locations, or Reader answers actually changed. A structural Chat change may still recompute visible order and indexes, but does not rerun unrelated business folds or replace unchanged Node identity.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index f27a82459c..0e0fbdf8f3 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -394,6 +394,8 @@ Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏
 
 新增业务节点可以局部注册自己的 matcher、State 转换、可选 Location data、最终 target Node 和 renderer，不再修改 Session 的业务 switch。`ChatNodeDataMap` 和 Location data maps 允许业务 package 通过 declaration merging 合入强类型 data；所有相关 Event 仍须暴露可单 Event 推导的稳定 ID。
 
+Host 业务 package 把自己的持久 Event 成员 declaration-merge 到 `@deepseek-ai/dsh-session/types`，Client Definition 则通过对应业务 package 的 `/types` 子路径进行 type-only import。增强实际声明接口而不是重导出 barrel，使 Host 和 Client 的独立 TypeScript Program 都能获得相同的 Event narrowing，同时不把 Host runtime 带入 Client 图。
+
 初始尾页、older prepend 和 live append 共享一套 Context 不变量。缺 start、Reader window gap、Location unknown 以及高频 delta 都是引擎明确表达的状态，不需要业务另建方向相关 cache。
 
 Append 不扫描历史 Context；prepend 只 replay Match、Location 或 Reader 答案真正受影响的 Context。Chat 结构变化仍可能重算 visible order 和索引，但不会重跑无关业务 fold 或替换未变化 Node identity。
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index fd8dbdd1b5..532750f069 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 1aca48d677a83a488d9590edad3f8a68ca662b70
-compaction.zh.md: e2cfabc0891126d9f2165e47dffcf485f4a8a339
+compaction.md: 11ee6eae797db1c57bf2ffbb90f1f37f47b8400c
+compaction.zh.md: a560e47dbb7aa92f0757179534803bbcaaebc6ba
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 1aca48d677..11ee6eae79 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -20,7 +20,7 @@ The lock brackets the **whole** operation: `compact/start` is appended first, th
 
 The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
 
-These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other subsystem pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
+These variants are merged inside a `declare module '@deepseek-ai/dsh-session/types'` block, so — unlike the top-level types on the other subsystem pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
 
 ## `CompactionResult`
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index e2cfabc089..a560e47dbb 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -20,7 +20,7 @@
 
 这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。
 
-这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子系统页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
+这些变体在 `declare module '@deepseek-ai/dsh-session/types'` 块内合并，因此——与其他子系统页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
 
 ## `CompactionResult`
 
diff --git a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
index bf48fc75c6..444389e6ea 100644
--- a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
@@ -9,9 +9,11 @@ type TurnTailNodeViewProps = ChatNodeViewProps<'turn-tail'> & PropsRenderSlots<'
 
 /** Turn-local actions and feature tail over the Location index, independent of Assistant placement. */
 export const TurnTailNodeView = memo(function TurnTailNodeView({
-  node, openFile, forkAt, renderSlotChain, t,
+  node, openFile, forkAt, renderSlotChain, t, useSession,
 }: TurnTailNodeViewProps) {
   const data = node.data
+  const hasLaterChatNode = useSession(snapshot =>
+    snapshot.chat.locations.getTurn(data.turn).at(-1) !== node.key)
   const turn = node.location.kind === 'turn' || node.location.kind === 'step'
     ? node.location.turn
     : undefined
@@ -34,7 +36,7 @@ export const TurnTailNodeView = memo(function TurnTailNodeView({
         tokensPerSecond={data.tokensPerSecond}
         clock="end"
         onBranch={() => { forkAt(closing.finalNode.seq) }}
-        branchUnavailable={data.branchUnavailable}
+        branchUnavailable={data.branchUnavailable || hasLaterChatNode}
         className={css.actions}
         t={t}
       />
diff --git a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
index 787f391006..c057d15d1b 100644
--- a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
+++ b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
@@ -57,7 +57,7 @@ export interface TurnTailChatData {
   readonly time: number
   /** Last finalized content-bearing Assistant in this Turn. */
   readonly closing: FinalAssistantChatData | null
-  /** Whether later Assistant/Step material makes the closing seq non-tail. */
+  /** Whether non-rendered later evidence makes the closing seq non-tail. */
   readonly branchUnavailable: boolean
   readonly ttftMs?: number
   readonly tokensPerSecond?: number
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index ca6223826e..6b2072ddfb 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -181,14 +181,12 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     if (key !== 'conversation.chat.node') return opts?.fallback ?? null
     const nodeOwner = owner as RoutedChatNodeOwner
     const nodeKey = opts?.hookContext as string | undefined
-    const useTurnData = ((dataKey: string) => {
-      return props.useSession((snapshot) => {
-        const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
-        return location?.kind === 'turn' || location?.kind === 'step'
-          ? location.turn.data.get(dataKey as never)
-          : undefined
-      })
-    }) as UseChatNodeTurnData
+    const useTurnData: UseChatNodeTurnData = dataKey => props.useSession((snapshot) => {
+      const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
+      return location?.kind === 'turn' || location?.kind === 'step'
+        ? location.turn.data.get(dataKey)
+        : undefined
+    })
     const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
       { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
@@ -722,6 +720,28 @@ describe('ChatView', () => {
     expect(h.forkAt.mock.calls).toEqual([[2]])
   })
 
+  it('disables fork when the indexed Turn has a later steering Node', () => {
+    const base = chatSnapshotFixture({
+      nodes: [user(1, 'question'), assistant(2, 'answer')],
+      turnEnds: new Map([[1, 4]]),
+    })
+    const chat = {
+      ...base,
+      locations: {
+        getTurn: (turn: number) => turn === 1
+          ? [...base.locations.getTurn(turn), 'fixture:steering:later']
+          : base.locations.getTurn(turn),
+        getStep: (turn: number, step: number) => base.locations.getStep(turn, step),
+      },
+    }
+    const h = makeHarness({ chat })
+    const view = render(<h.ChatView {...h.props} />)
+    const branch = view.getByRole('button', { name: '在新对话中分支' })
+    expect(branch.getAttribute('aria-disabled')).toBe('true')
+    fireEvent.click(branch)
+    expect(h.forkAt).not.toHaveBeenCalled()
+  })
+
   it('keeps final content actions but disables branch when Tool and interrupted Think follow it', () => {
     const interruptedThink: AssistantMessageNode = {
       kind: 'assistant', seq: 4.1, time: 4_100, turn: 1, step: 2,
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index 0227b34261..9151f88869 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -36,7 +36,9 @@ interface DeliverablesState extends DeliverablesTurnData {
  * Paths a call view reports having created or changed, by render intent rather
  * than tool name: a diff card, or a generic card whose kind is `edit` (the
  * shape `str_replace_editor`'s insert presents). Every other card produces
- * nothing to open — a read looked, a delete removed, a terminal ran.
+ * nothing to open — a read looked, a delete removed, a terminal ran. Only
+ * root call views enter this Turn accumulator; nested Code Mode dispatches
+ * preserve the pre-assembly behavior and do not contribute independently.
  */
 function producedPaths(view: ToolResultNode['callView']): readonly string[] {
   if (view === null) return []
diff --git a/vitest.config.ts b/vitest.config.ts
index e07ae43ec3..33512f4898 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -211,6 +211,7 @@ export default defineConfig({
         'packages/client/ui-workspace/src/client/index.ts',
         'packages/client/test-runtime/src/translate.ts',
         'packages/client/ui-primitives/src/JsonTree.tsx',
+        'packages/client/ui-deliverables/src/client/turn-deliverables.ts',
         // Typert generator: correctness is pinned by its fixture suites and
         // the byte-for-byte catalog reproduction test; per-file coverage
         // would put whole-workspace compiler analysis under v8

From 126ad5bb02147a5d584349fbce4111e274cea8ff Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:36:15 +0800
Subject: [PATCH 244/262] docs: development

---
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   3 +-
 docs/architecture.zh.md                       |   3 +-
 .../adding-a-conversation-node.i18n.yaml      |   6 +
 docs/cookbook/adding-a-conversation-node.md   | 232 ++++++++++++++++
 .../cookbook/adding-a-conversation-node.zh.md | 232 ++++++++++++++++
 docs/cookbook/extension-cookbook.i18n.yaml    |   4 +-
 docs/cookbook/extension-cookbook.md           |   3 +-
 docs/cookbook/extension-cookbook.zh.md        |   3 +-
 docs/event-producer-consumer.i18n.yaml        |   2 +-
 docs/event-producer-consumer.zh.md            |  44 +--
 docs/module-graph.i18n.yaml                   |   2 +-
 docs/module-graph.zh.md                       | 253 +++++++++---------
 docs/persistence-catalog.i18n.yaml            |   2 +-
 docs/persistence-catalog.zh.md                |  66 ++---
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   2 +
 docs/subsystems/session.zh.md                 |   2 +
 packages/client/AGENTS.md                     |   6 +
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   2 +
 packages/client/runtime/README.zh.md          |   2 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +
 packages/client/ui-conversation/README.zh.md  |   2 +
 scripts/doc-budgets.manifest.json             |   2 +-
 website/docs.ts                               |   8 +
 27 files changed, 698 insertions(+), 201 deletions(-)
 create mode 100644 docs/cookbook/adding-a-conversation-node.i18n.yaml
 create mode 100644 docs/cookbook/adding-a-conversation-node.md
 create mode 100644 docs/cookbook/adding-a-conversation-node.zh.md

diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index dff7978387..fe32a219de 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 506283bfc651d38fe4bccd50fb8a86143d2b41d8
-architecture.zh.md: ea48af8131ebbdc70a45e403dfddc78dfcfb6f47
+architecture.md: 771d7489ee338db56362a6ccc133b1ebf8cdc7c0
+architecture.zh.md: ca7c4fe2a463e01a8e14e63a53f13aea45cbfa16
diff --git a/docs/architecture.md b/docs/architecture.md
index 506283bfc6..771d7489ee 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -183,10 +183,11 @@ New behavior attaches to a documented extension point; a loop change updates thi
 | Intercept a request, tool, or turn | use its `agent/*` or `tools/*` event; `agent/turn-stopping` is the stop boundary |
 | Add model-facing context | call `agent.inject()` to queue sourced context for the next admitted request |
 | Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
+| Web Client Chat node | register a `ConversationNodeDefinition` + keyed renderer |
 | Add durable session state | extend `SessionEventMap`; render and replay from the log |
 | Add asynchronous session-title generation | register the sole `ctx.sessionTitle` provider |
 | Manage a same-session objective | use `ctx.goals`; continue through `Agent` and `agent/*` |
 | Fork a live session | call `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | Scope a registration to one agent | use its `agent.ctx` (see Agent Scope) |
 
-The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
+[Extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), [Chat nodes](cookbook/adding-a-conversation-node.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index ea48af8131..ca7c4fe2a4 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -183,10 +183,11 @@ idle inject:
 | 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stopping` 是停止边界 |
 | 添加模型可见上下文 | 调用 `agent.inject()`，将带来源的上下文排入下一次获准请求 |
 | 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
+| Web Client Chat 节点 | 注册 `ConversationNodeDefinition` + keyed renderer |
 | 添加持久会话状态 | 扩展 `SessionEventMap`；从日志渲染和回放 |
 | 添加异步会话标题生成 | 注册唯一的 `ctx.sessionTitle` 提供方 |
 | 管理同会话目标 | 使用 `ctx.goals`；通过 `Agent` 和 `agent/*` 续跑 |
 | fork 活跃会话 | 调用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 将注册项限定到单个 agent | 使用其 `agent.ctx`（参见 Agent 作用域） |
 
-[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)将功能映射到能力；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+[扩展实操手册](cookbook/extension-cookbook.md)将功能映射到能力；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)、[Chat 节点](cookbook/adding-a-conversation-node.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
diff --git a/docs/cookbook/adding-a-conversation-node.i18n.yaml b/docs/cookbook/adding-a-conversation-node.i18n.yaml
new file mode 100644
index 0000000000..aa268e9461
--- /dev/null
+++ b/docs/cookbook/adding-a-conversation-node.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 docs/cookbook/adding-a-conversation-node.md
+adding-a-conversation-node.md: ea4ec73eb109af6b0e4c7cf50fc8692942c75dd4
+adding-a-conversation-node.zh.md: 4b9a8049e2f1d060ec4bc3334036559b989ea562
diff --git a/docs/cookbook/adding-a-conversation-node.md b/docs/cookbook/adding-a-conversation-node.md
new file mode 100644
index 0000000000..ea4ec73eb1
--- /dev/null
+++ b/docs/cookbook/adding-a-conversation-node.md
@@ -0,0 +1,232 @@
+# Add a Web Client conversation node
+
+English | [中文](adding-a-conversation-node.zh.md)
+
+This tutorial adds one business-owned row to the Web Client Chat view. The finished plugin correlates a durable Session event family into one Context, incrementally builds business State, publishes typed Step data, and renders a keyed Chat Node without scanning the Session window or other rendered nodes. It assumes the Host already records the events and the client plugin is composed into the Web bundle; external Host-side UIs and additional view targets such as Trajectory are outside this tutorial.
+
+The [Conversation Node assembly decision](../../.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md) owns the rationale and complete engine model. This guide covers the implementation path.
+
+## 1. Design a replayable event family
+
+Choose one stable business id before writing the Definition. Every event that contributes to the same Node must carry that id or derive it independently from its own payload; the client must never assign an update to “the latest unfinished” Context.
+
+For a review job, the event contract could be:
+
+| Event | Role | Required durable facts |
+|---|---|---|
+| `review/start` | unique start | `reviewId`, Turn/Step coordinates, title |
+| `review/progress` | update | the same `reviewId`, coordinates, replayable progress |
+| `review/end` | update | the same `reviewId`, coordinates, final summary |
+
+Use the producer-owned branded id type across the process boundary. Put the `SessionEventMap` merge and payload types on the producer's type-only export, then import that export for side effects from the client package. Each `(kind, id)` may have at most one start event. A single-event business can use the event's stable identity, such as `event.seq`, as its Definition-local id.
+
+Incremental events are supported. Prefer whole-value checkpoints when the producer can emit them cheaply, because they remain useful when the start is outside the loaded window. Each delta must carry the stable id and produce deterministic State when replayed in ascending log `seq`; it must not depend on live-only memory. If the current history window contains only updates, the assembler keeps a pending Context and builds no State until an older page supplies the start. If the product must render before the start is loaded, a terminal or checkpoint event must carry enough whole fallback state for the Definition to build that result directly; do not recover it by scanning unrelated events.
+
+## 2. Implement the Definition and typed Chat payload
+
+The example keeps the producer declarations and client contribution in one block so the complete relationship is visible. In a package family, keep the branded id and `SessionEventMap` declaration with the event producer, and keep the Definition, Chat data merge, and renderer in the client plugin.
+
+```ts ignore-check
+import { createElement } from 'react'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type {
+  ClientContext, ConversationLocation, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+type ReviewId = Branded<'ReviewId'>
+
+interface ReviewStartData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly title: string
+}
+
+interface ReviewProgressData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly completed: number
+}
+
+interface ReviewEndData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly summary: string
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Opens one durable review job.
+     * @mode emit
+     * @param data - stable identity, location, and initial display state.
+     */
+    'review/start': ReviewStartData
+    /**
+     * Records replayable progress for one review job.
+     * @mode emit
+     * @param data - stable identity, location, and latest progress.
+     */
+    'review/progress': ReviewProgressData
+    /**
+     * Closes one review job with its final summary.
+     * @mode emit
+     * @param data - stable identity, location, and final display state.
+     */
+    'review/end': ReviewEndData
+  }
+}
+
+interface ReviewChatData {
+  readonly title: string
+  readonly completed: number
+  readonly status: 'running' | 'completed'
+  readonly summary?: string
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationStepDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+interface ReviewState extends ReviewChatData {
+  readonly turn: number
+  readonly step: number
+}
+
+function locationOf(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+function viewData(state: ReviewState): ReviewChatData {
+  return {
+    title: state.title,
+    completed: state.completed,
+    status: state.status,
+    ...state.summary === undefined ? {} : { summary: state.summary },
+  }
+}
+
+const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
+  kind: 'review-job',
+  match: (event) => {
+    if (event.type === 'review/start') {
+      return { id: String(event.data.reviewId), role: 'start' }
+    }
+    if (event.type === 'review/progress' || event.type === 'review/end') {
+      return { id: String(event.data.reviewId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'review/start') throw new Error('review-job requires review/start')
+    return {
+      turn: match.event.data.turn,
+      step: match.event.data.step,
+      title: match.event.data.title,
+      completed: 0,
+      status: 'running',
+    }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'review/progress') {
+      return { ...context.state, completed: match.event.data.completed }
+    }
+    if (match.event.type === 'review/end') {
+      return { ...context.state, completed: 100, status: 'completed', summary: match.event.data.summary }
+    }
+    return context.state
+  },
+  publication: match => match.event.type === 'review/progress'
+    ? 'animation-frame'
+    : 'immediate',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step' || context.state === undefined) return null
+    return {
+      kind: 'step',
+      turn: context.state.turn,
+      step: context.state.step,
+      key: 'review-job',
+      value: viewData(context.state),
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'review-job',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start?.event.seq ?? context.matches[0]?.event.seq ?? 0,
+      location: locationOf(context),
+      visibility: 'visible',
+      data: viewData(context.state),
+    }
+  },
+}
+
+function ReviewNodeView({ node }: ChatNodeViewProps<'review-job'>) {
+  const text = node.data.summary ?? `${node.data.title}: ${node.data.completed}%`
+  return createElement('p', null, text)
+}
+
+export const inject = ['conversationEvents', 'slots']
+
+export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(reviewDefinition)
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'review-job',
+  }, ReviewNodeView))
+}
+```
+
+`match(event)` is an identity extractor, not a fold: it receives only the current event and returns the Definition-local id and lifecycle role. After a match, the assembler locates the Context by `(kind, id)` and calls `start` once or `update` with the current State. Both functions return the State that the engine adopts; returning a new immutable value is preferred, but a function that mutates and returns the same object has the same adoption semantics.
+
+`buildLocationData(context, scope)` optionally publishes Definition-owned data onto an engine-owned Turn or Step. Use declaration merging to give each key a precise value type. Another Node in the same Location can consume that value through its constrained slot hook, such as `useTurnData(key)`, without receiving the Session or scanning `snapshot.chat.nodes`.
+
+`buildViewNode(context, target)` materializes the final target-specific Node. Preserve `context.key` as the React-facing identity, choose `anchorSeq` from durable ordering evidence, and return only renderer-ready data. Once a target Node has been published, keep returning the same key; use `visibility: 'hidden'` when it must temporarily leave the visible flow rather than withdrawing it with `null`.
+
+## 3. Query an earlier business Context only at start
+
+Some Definitions need the latest earlier State of another business kind. `start` receives a `ConversationContextReader`; call `reader.previous<State>(kind)` there instead of accepting a Context collection or scanning events. The reader returns the nearest started Context before the current start `seq` as read-only data.
+
+The assembler records that dependency. If an older prepend later supplies a nearer predecessor, closes a previously unknown window gap, or revises the predecessor State, it reruns the dependent Context from `start` and replays its updates in ascending `seq`. The queried Definition remains responsible for writing useful State; the reader exposes no business-specific query methods and grants no mutation authority over another Context.
+
+## 4. Understand the three ingestion paths
+
+History may be requested from the tail backward one page at a time, but every accepted page is normalized into ascending `seq` before State replay.
+
+| Path | Engine work | Definition-visible behavior |
+|---|---|---|
+| Replace on open, resync, or gap repair | Rebuild the loaded window, match every event once per Definition, then replay each started Context | `start`, followed by its updates in ascending `seq`; pending update-only Contexts remain without State |
+| Prepend one older page | Match only fresh older events, merge them into Contexts by `(kind, id)`, preserve existing keyed nodes, and replay only affected Contexts and dependencies | A newly found start activates its collected updates; a changed Location or predecessor may rerun the Context |
+| Append one live event | Call each Definition's `match` once, look up the matched Context by key, and update only that Context | One `update` and one requested publication for a matching post-start event; no existing Context scan |
+
+With `D` registered Definitions, one incoming event performs `D` current-event matches and constant-time Context-key lookup after a match. Definition code must preserve that property: do not traverse the complete event window, every Context, `context.matches`, or the rendered Node collection on the normal append path. Use State for accumulated facts, Location data for same-Turn/Step sharing, and `reader.previous()` for indexed predecessor dependencies.
+
+`publication` controls when changed State is materialized. Use `immediate` for structural or terminal changes, `animation-frame` for high-frequency visible deltas, and `none` when the State change feeds only a later publication. The engine still applies every update in log order; cadence only coalesces view publication.
+
+## 5. Verify replay, pagination, and rendering
+
+Add focused tests that establish these outcomes:
+
+1. A complete window passed through replace produces the expected final State, Location data, Node payload, and `anchorSeq`.
+2. An update-only tail stays pending; prepending the unique start produces the same result as a complete replace.
+3. Initial history followed by live append produces the same result as replaying the combined window.
+4. Prepending an older page adds earlier rows without replacing existing keyed Node values whose data did not change.
+5. Repeated visible deltas preserve `context.key` and publish at most once per animation frame when requested.
+6. The keyed renderer consumes `node.data` and constrained Location hooks only; it does not scan the Session event window, Contexts, or Chat Nodes.
+
+Use [`packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts) for streaming and interruption, [`inbox.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts) plus [`message.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/message.ts) for predecessor queries, and [`packages/client/ui-deliverables`](../../packages/client/ui-deliverables) for a Definition that publishes Turn data without creating its own Node.
diff --git a/docs/cookbook/adding-a-conversation-node.zh.md b/docs/cookbook/adding-a-conversation-node.zh.md
new file mode 100644
index 0000000000..4b9a8049e2
--- /dev/null
+++ b/docs/cookbook/adding-a-conversation-node.zh.md
@@ -0,0 +1,232 @@
+# 添加 Web Client Conversation Node
+
+[English](adding-a-conversation-node.md) | 中文
+
+本教程为 Web Client Chat 视图添加一行由业务自行拥有的内容。完成后的插件会把一个持久 Session 事件族关联成一个 Context，增量构造业务 State，发布类型化 Step 数据，再渲染 keyed Chat Node；整个过程不扫描 Session 窗口或其他已渲染节点。本教程假设 Host 已经记录这些事件，且该 Client 插件已组装进 Web bundle；Host 侧外部 UI 和 Trajectory 等额外视图目标不在本文范围内。
+
+[Conversation Node 组装决策](../../.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md)记录完整的引擎模型和设计理由；本文只说明实现路径。
+
+## 1. 设计可回放的事件族
+
+编写 Definition 前先选定稳定的业务 id。构成同一个 Node 的每条事件都必须携带该 id，或只凭自身 payload 独立推导出该 id；Client 绝不能把 update 猜测为属于“最近一个未完成”的 Context。
+
+以一个 review job 为例，事件约定可以是：
+
+| 事件 | 角色 | 必须持久化的事实 |
+|---|---|---|
+| `review/start` | 唯一 start | `reviewId`、Turn/Step 坐标、标题 |
+| `review/progress` | update | 相同的 `reviewId`、坐标、可回放进度 |
+| `review/end` | update | 相同的 `reviewId`、坐标、最终摘要 |
+
+跨进程边界使用生产方拥有的 branded id 类型。把 `SessionEventMap` 合并和 payload 类型放在生产方的纯类型导出中，再由 Client 包通过仅类型副作用导入该导出。每个 `(kind, id)` 最多只能有一条 start 事件。单事件业务可以把事件自身的稳定身份（例如 `event.seq`）作为 Definition 内部 id。
+
+系统支持增量事件。如果生产方能以较低成本发出 whole-value checkpoint，应优先采用，因为 start 位于已加载窗口之外时它仍可直接使用。每条 delta 都必须携带稳定 id，并且按照日志 `seq` 升序回放时能够确定性地产生 State；它不能依赖只存在于实时内存中的状态。如果当前历史窗口只有 update，Assembler 会保留一个 pending Context，并在更早分页补齐 start 前不构造 State。如果产品必须在 start 尚未加载时渲染，terminal 或 checkpoint 事件就必须携带足够的完整 fallback 状态，让 Definition 能直接构造结果；不要通过扫描无关事件恢复它。
+
+## 2. 实现 Definition 与类型化 Chat payload
+
+为了完整展示关联关系，下面把生产方声明和 Client 贡献写在同一个代码块里。实际的包族中，branded id 与 `SessionEventMap` 声明留在事件生产方，Definition、Chat data 合并与 renderer 留在 Client 插件。
+
+```ts ignore-check
+import { createElement } from 'react'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type {
+  ClientContext, ConversationLocation, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+type ReviewId = Branded<'ReviewId'>
+
+interface ReviewStartData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly title: string
+}
+
+interface ReviewProgressData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly completed: number
+}
+
+interface ReviewEndData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly summary: string
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Opens one durable review job.
+     * @mode emit
+     * @param data - stable identity, location, and initial display state.
+     */
+    'review/start': ReviewStartData
+    /**
+     * Records replayable progress for one review job.
+     * @mode emit
+     * @param data - stable identity, location, and latest progress.
+     */
+    'review/progress': ReviewProgressData
+    /**
+     * Closes one review job with its final summary.
+     * @mode emit
+     * @param data - stable identity, location, and final display state.
+     */
+    'review/end': ReviewEndData
+  }
+}
+
+interface ReviewChatData {
+  readonly title: string
+  readonly completed: number
+  readonly status: 'running' | 'completed'
+  readonly summary?: string
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationStepDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+interface ReviewState extends ReviewChatData {
+  readonly turn: number
+  readonly step: number
+}
+
+function locationOf(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+function viewData(state: ReviewState): ReviewChatData {
+  return {
+    title: state.title,
+    completed: state.completed,
+    status: state.status,
+    ...state.summary === undefined ? {} : { summary: state.summary },
+  }
+}
+
+const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
+  kind: 'review-job',
+  match: (event) => {
+    if (event.type === 'review/start') {
+      return { id: String(event.data.reviewId), role: 'start' }
+    }
+    if (event.type === 'review/progress' || event.type === 'review/end') {
+      return { id: String(event.data.reviewId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'review/start') throw new Error('review-job requires review/start')
+    return {
+      turn: match.event.data.turn,
+      step: match.event.data.step,
+      title: match.event.data.title,
+      completed: 0,
+      status: 'running',
+    }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'review/progress') {
+      return { ...context.state, completed: match.event.data.completed }
+    }
+    if (match.event.type === 'review/end') {
+      return { ...context.state, completed: 100, status: 'completed', summary: match.event.data.summary }
+    }
+    return context.state
+  },
+  publication: match => match.event.type === 'review/progress'
+    ? 'animation-frame'
+    : 'immediate',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step' || context.state === undefined) return null
+    return {
+      kind: 'step',
+      turn: context.state.turn,
+      step: context.state.step,
+      key: 'review-job',
+      value: viewData(context.state),
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'review-job',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start?.event.seq ?? context.matches[0]?.event.seq ?? 0,
+      location: locationOf(context),
+      visibility: 'visible',
+      data: viewData(context.state),
+    }
+  },
+}
+
+function ReviewNodeView({ node }: ChatNodeViewProps<'review-job'>) {
+  const text = node.data.summary ?? `${node.data.title}: ${node.data.completed}%`
+  return createElement('p', null, text)
+}
+
+export const inject = ['conversationEvents', 'slots']
+
+export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(reviewDefinition)
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'review-job',
+  }, ReviewNodeView))
+}
+```
+
+`match(event)` 是身份提取器，不是 fold：它只能收到当前事件，并返回 Definition 内部 id 与生命周期角色。命中后，Assembler 通过 `(kind, id)` 定位 Context，再调用一次 `start`，或把当前 State 交给 `update`。两个函数都必须返回引擎随后采用的 State；推荐返回新的 immutable value，但函数原地修改后返回同一对象时，采用语义也相同。
+
+`buildLocationData(context, scope)` 可以把 Definition 拥有的数据发布到引擎拥有的 Turn 或 Step 上。通过 declaration merging 为每个 key 指定精确 value 类型。同一 Location 内的另一个 Node 可以使用受限 slot hook（例如 `useTurnData(key)`）读取该值，无须取得 Session，也无须扫描 `snapshot.chat.nodes`。
+
+`buildViewNode(context, target)` 物化最终的目标专用 Node。把 `context.key` 保留为 React 侧身份，根据持久排序证据选择 `anchorSeq`，并且只返回 renderer 可以直接使用的数据。某个 target Node 一旦发布，就要继续返回同一个 key；需要暂时离开可见流时使用 `visibility: 'hidden'`，不要改为返回 `null` 撤回它。
+
+## 3. 只在 start 时查询更早的业务 Context
+
+有些 Definition 需要另一个业务 kind 在当前位置之前的最新 State。`start` 会收到 `ConversationContextReader`；应在这里调用 `reader.previous<State>(kind)`，不要接收 Context 集合或扫描事件。Reader 返回当前 start `seq` 之前最近一个已启动 Context 的只读数据。
+
+Assembler 会记录这项依赖。如果后续 older prepend 带来了更近的前序 Context、补齐了原先未知的窗口缺口，或者前序 State 被修订，引擎会从 `start` 重新运行依赖方 Context，并按 `seq` 升序回放其 update。被查询的 Definition 仍负责把有用信息写入自身 State；Reader 不提供业务专用查询方法，也不授予修改其他 Context 的权限。
+
+## 4. 理解三条摄入路径
+
+历史可能从尾部开始一页一页向前请求，但每个已接收分页都会先按 `seq` 升序归一化，再进入 State 回放。
+
+| 路径 | 引擎工作 | Definition 可观察到的行为 |
+|---|---|---|
+| open、resync 或 gap repair 时 replace | 重建已加载窗口，每条事件对每个 Definition 匹配一次，再回放每个已有 start 的 Context | 先执行 `start`，再按 `seq` 升序执行其 update；只有 update 的 pending Context 仍没有 State |
+| prepend 一页更早历史 | 只匹配新增的更早事件，按 `(kind, id)` 合并进 Context，保留现有 keyed node，并只重放受影响的 Context 与依赖 | 新发现的 start 会激活已收集 update；Location 或前序依赖变化也可能重跑 Context |
+| append 一条实时事件 | 每个 Definition 各调用一次 `match`，按 key 查找命中的 Context，只更新该 Context | 对 start 之后的匹配事件执行一次 `update` 并请求一次发布；不扫描已有 Context |
+
+注册 `D` 个 Definition 时，一条新事件会进行 `D` 次仅当前事件匹配；命中后的 Context key 查询是常数时间。Definition 代码必须维持这个性质：正常 append 热路径不得遍历完整事件窗口、所有 Context、`context.matches` 或已渲染 Node 集合。累计事实放进 State，同 Turn/Step 共享信息放进 Location data，有索引的前序依赖使用 `reader.previous()`。
+
+`publication` 控制发生 State 变更后何时物化。结构或 terminal 变化使用 `immediate`，高频可见 delta 使用 `animation-frame`，只为后续发布积累 State 时使用 `none`。引擎仍会按日志顺序应用每条 update；该选项只合并视图发布频率。
+
+## 5. 验证回放、分页与渲染
+
+添加聚焦测试，证明以下结果：
+
+1. 完整窗口通过 replace 后产生预期的最终 State、Location data、Node payload 与 `anchorSeq`。
+2. 只有 update 的尾部窗口保持 pending；prepend 唯一 start 后，结果与完整 replace 相同。
+3. 初始历史后继续实时 append，与回放合并后的完整窗口得到相同结果。
+4. prepend 更早分页只增加更早的行；数据未变化的既有 keyed Node value 不被替换。
+5. 重复的可见 delta 保持 `context.key`，并在请求 `animation-frame` 时每帧最多发布一次。
+6. keyed renderer 只消费 `node.data` 与受限 Location hook，不扫描 Session 事件窗口、Context 或 Chat Node。
+
+流式与中断处理可参考 [`packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts)，前序查询可参考 [`inbox.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts) 与 [`message.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/message.ts)，只发布 Turn data 而不创建自有 Node 的例子见 [`packages/client/ui-deliverables`](../../packages/client/ui-deliverables)。
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index 0509a67549..7eaa702a9d 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.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 docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 025a1b6ecd11593b5d6be9d0f64e57ac8b5e3139
-extension-cookbook.zh.md: f838a281fabdba473b72b27f7b14274d9aa97528
+extension-cookbook.md: 5d9312f2f5cf840100b12045bde1829b342e580d
+extension-cookbook.zh.md: 29bb57c558a0ff9413619d0bb2e8bb5e6b70da56
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 025a1b6ecd..5d9312f2f5 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -34,7 +34,7 @@ This waterfall is the reorderable policy layer. Use `ctx.tools.guard()` when an
 
 ## A UI plugin
 
-A UI plugin renders from the `session/event` feed (the assistant token stream as `assistant/chunk`, plus turn/step boundaries and tool activity), and drives input back in via `agent.followup()` / `agent.steer()`.
+A UI plugin renders from the `session/event` feed (the assistant token stream as `assistant/chunk`, plus turn/step boundaries and tool activity), and drives input back in via `agent.followup()` / `agent.steer()`. A browser plugin contributing a business row to the built-in Web Client instead registers a `ConversationNodeDefinition` and keyed Chat renderer; follow the [Conversation Node guide](adding-a-conversation-node.md).
 
 ```ts
 import type { Context } from 'cordis'
@@ -123,6 +123,7 @@ Every product feature maps to a listener on a documented extension point — the
 | Memory | section provider + tool |
 | Scheduled tasks (cron) | a plugin registers model-callable scheduling tools; timer fires → `followup(…, {source: {kind: 'cron', …}})` when idle / `inject()` notification when busy |
 | UI (GUI; CLI emits JSONL) | listen `session/event` (assistant chunks, boundaries, tool activity); input → `followup()` |
+| Web Client Chat business node | register a `ConversationNodeDefinition` and `conversation.chat.node` keyed renderer |
 | Telemetry / replayable trace | `session/event` → JSONL; replay = `sessions.create(id, { seed })` |
 | Model adapters | `LlmAdapter` subclass via `registerAdapter` (`dsh-llm-deepseek`, `dsh-llm-pi-ai`) |
 | Plugin hot-reload | every registration is a `ctx.effect` → vendored HMR just works |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index f838a281fa..29bb57c558 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -34,7 +34,7 @@ export function apply(ctx: Context) {
 
 ## UI 插件
 
-UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.followup()` / `agent.steer()` 将输入驱动回去。
+UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.followup()` / `agent.steer()` 将输入驱动回去。如果浏览器插件要向内建 Web Client 贡献业务行，则应注册 `ConversationNodeDefinition` 与 keyed Chat renderer；具体步骤见 [Conversation Node 指南](adding-a-conversation-node.md)。
 
 ```ts
 import type { Context } from 'cordis'
@@ -123,6 +123,7 @@ export function apply(ctx: Context) {
 | 记忆 | section 提供方 + 工具 |
 | 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `followup(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
 | UI（GUI；CLI（命令行界面）输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `followup()` |
+| Web Client Chat 业务节点 | 注册 `ConversationNodeDefinition` 与 `conversation.chat.node` keyed renderer |
 | 遥测 / 可回放 trace | `session/event` → JSONL；回放 = `sessions.create(id, { seed })` |
 | 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek`、`dsh-llm-pi-ai`） |
 | 插件热重载 | 每个注册都是一个 `ctx.effect` → 随仓库提供的 HMR（热模块替换）直接生效 |
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 812b490bef..89e1b03d35 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
 event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa
-event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
+event-producer-consumer.zh.md: 7eafe5f2880cf9f0e6f2e7eb6c299730926f15ed
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 2d4c805f9a..7eafe5f288 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -10,20 +10,20 @@
 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
-| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:159`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:168`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:197`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:205`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:186`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:231`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:244`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:260`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:217`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:134`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -46,12 +46,12 @@
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:192`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:174`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:149`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:161`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
+| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:182`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
 | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
@@ -59,9 +59,9 @@
 | `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:53`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
 | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:45`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 
-## 包源码中出现的非 harness 或未声明事件字符串
+## Non-harness or undeclared event strings seen in package source
 
-| 事件字符串 | 派发方 | 监听方 |
+| Event string | Dispatchers | Listeners |
 | --- | --- | --- |
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
 | `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
@@ -80,4 +80,4 @@
 | `slots/changed` | `runtime` (`emit`) | - |
 | `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` |
 
-维护模式：英文源文件是生成内容，Cordis 事件声明及生产方／监听方的关系边由仓库的 TypeScript Program 解析；本中文文件作为经评审对侧通过双语配对维护。
+Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 24ddaad77c..61e55cd997 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
 module-graph.md: a248ed4fcb8abc17ffc6982d2733b3c3c2a2a635
-module-graph.zh.md: 255253bcfa9cfad1ab85602dfa9f953a02dfc427
+module-graph.zh.md: 28185c255ffa18f3ebc02f177d20594af3356164
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 255253bcfa..28185c255f 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -438,9 +438,6 @@ flowchart TD
   pkg_fs --> pkg_sandbox
   pkg_skill_badge --> pkg_invariants
   pkg_skill_badge --> pkg_skill
-  pkg_compact --> pkg_invariants
-  pkg_compact --> pkg_llm
-  pkg_compact --> pkg_session
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
@@ -504,15 +501,11 @@ flowchart TD
   pkg_session_projection --> pkg_invariants
   pkg_session_projection --> pkg_session
   pkg_llm_retry --> pkg_agent
+  pkg_llm_retry --> pkg_brand
   pkg_llm_retry --> pkg_invariants
   pkg_llm_retry --> pkg_llm
   pkg_llm_retry --> pkg_session
   pkg_llm_retry --> pkg_timeout
-  pkg_token_meter --> pkg_compact
-  pkg_token_meter --> pkg_invariants
-  pkg_token_meter --> pkg_llm
-  pkg_token_meter --> pkg_session
-  pkg_token_meter --> pkg_session_projection
   pkg_agent_default_model --> pkg_agent
   pkg_agent_default_model --> pkg_invariants
   pkg_agent_default_model --> pkg_llm
@@ -552,10 +545,6 @@ flowchart TD
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_invariants
   pkg_hook_protocol --> pkg_session
-  pkg_llm_replay --> pkg_compact
-  pkg_llm_replay --> pkg_invariants
-  pkg_llm_replay --> pkg_llm
-  pkg_llm_replay --> pkg_session
   pkg_loader_smoke --> pkg_agent
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
@@ -676,14 +665,11 @@ flowchart TD
   pkg_fs_sandbox --> pkg_invariants
   pkg_fs_sandbox --> pkg_sandbox
   pkg_fs_sandbox --> pkg_sandbox_policy
-  pkg_command_compact --> pkg_commands
-  pkg_command_compact --> pkg_compact
-  pkg_command_compact --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_compact
-  pkg_compact_tool_result_prune --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_llm
-  pkg_compact_tool_result_prune --> pkg_session
-  pkg_compact_tool_result_prune --> pkg_token_meter
+  pkg_compact --> pkg_brand
+  pkg_compact --> pkg_commands
+  pkg_compact --> pkg_invariants
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
   pkg_session_query --> pkg_brand
   pkg_session_query --> pkg_invariants
   pkg_session_query --> pkg_llm
@@ -705,13 +691,6 @@ flowchart TD
   pkg_headless --> pkg_invariants
   pkg_headless --> pkg_llm
   pkg_headless --> pkg_session
-  pkg_client_ui_conversation --> pkg_client_locale
-  pkg_client_ui_conversation --> pkg_client_runtime
-  pkg_client_ui_conversation --> pkg_client_ui_primitives
-  pkg_client_ui_conversation --> pkg_client_ui_slash
-  pkg_client_ui_conversation --> pkg_client_ui_slots
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_token_meter
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
   pkg_command_feedback --> pkg_session
@@ -744,6 +723,11 @@ flowchart TD
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
   pkg_tasks_local --> pkg_timeout
+  pkg_token_meter --> pkg_compact
+  pkg_token_meter --> pkg_invariants
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
+  pkg_token_meter --> pkg_session_projection
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_invariants
   pkg_agent_loop --> pkg_llm
@@ -792,13 +776,9 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
-  pkg_compact_basic --> pkg_agent
-  pkg_compact_basic --> pkg_compact
-  pkg_compact_basic --> pkg_compact_tool_result_prune
-  pkg_compact_basic --> pkg_invariants
-  pkg_compact_basic --> pkg_llm
-  pkg_compact_basic --> pkg_session
-  pkg_compact_basic --> pkg_token_meter
+  pkg_command_compact --> pkg_commands
+  pkg_command_compact --> pkg_compact
+  pkg_command_compact --> pkg_invariants
   pkg_subagent --> pkg_agent
   pkg_subagent --> pkg_brand
   pkg_subagent --> pkg_invariants
@@ -859,33 +839,10 @@ flowchart TD
   pkg_agent_loop_testkit --> pkg_session
   pkg_agent_loop_testkit --> pkg_system_prompt
   pkg_agent_loop_testkit --> pkg_tools
-  pkg_client_ui_command --> pkg_client_connection
-  pkg_client_ui_command --> pkg_client_locale
-  pkg_client_ui_command --> pkg_client_runtime
-  pkg_client_ui_command --> pkg_client_ui_conversation
-  pkg_client_ui_command --> pkg_client_ui_primitives
-  pkg_client_ui_command --> pkg_client_ui_slash
-  pkg_client_ui_command --> pkg_client_ui_slots
-  pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_deliverables --> pkg_client_locale
-  pkg_client_ui_deliverables --> pkg_client_runtime
-  pkg_client_ui_deliverables --> pkg_client_ui_conversation
-  pkg_client_ui_deliverables --> pkg_client_ui_slots
-  pkg_client_ui_deliverables --> pkg_invariants
-  pkg_client_ui_goal --> pkg_api_remotes
-  pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_runtime
-  pkg_client_ui_goal --> pkg_client_ui_conversation
-  pkg_client_ui_goal --> pkg_client_ui_primitives
-  pkg_client_ui_goal --> pkg_client_ui_slots
-  pkg_client_ui_goal --> pkg_goal
-  pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_tool --> pkg_client_locale
-  pkg_client_ui_tool --> pkg_client_runtime
-  pkg_client_ui_tool --> pkg_client_ui_conversation
-  pkg_client_ui_tool --> pkg_client_ui_primitives
-  pkg_client_ui_tool --> pkg_client_ui_slots
-  pkg_client_ui_tool --> pkg_invariants
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -992,6 +949,11 @@ flowchart TD
   pkg_tool_pwsh --> pkg_system_prompt
   pkg_tool_pwsh --> pkg_tasks
   pkg_tool_pwsh --> pkg_tools
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
   pkg_subagent_acp --> pkg_agent
   pkg_subagent_acp --> pkg_invariants
   pkg_subagent_acp --> pkg_llm
@@ -1040,50 +1002,18 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
-  pkg_client_ui_model --> pkg_client_connection
-  pkg_client_ui_model --> pkg_client_locale
-  pkg_client_ui_model --> pkg_client_runtime
-  pkg_client_ui_model --> pkg_client_ui_command
-  pkg_client_ui_model --> pkg_client_ui_conversation
-  pkg_client_ui_model --> pkg_client_ui_primitives
-  pkg_client_ui_model --> pkg_client_ui_slash
-  pkg_client_ui_model --> pkg_client_ui_slots
-  pkg_client_ui_model --> pkg_invariants
-  pkg_client_ui_permission --> pkg_client_connection
-  pkg_client_ui_permission --> pkg_client_locale
-  pkg_client_ui_permission --> pkg_client_runtime
-  pkg_client_ui_permission --> pkg_client_schema_form
-  pkg_client_ui_permission --> pkg_client_ui_command
-  pkg_client_ui_permission --> pkg_client_ui_primitives
-  pkg_client_ui_permission --> pkg_client_ui_slash
-  pkg_client_ui_permission --> pkg_client_ui_slots
-  pkg_client_ui_permission --> pkg_invariants
-  pkg_client_ui_permission --> pkg_permission
-  pkg_client_ui_plan --> pkg_client_connection
-  pkg_client_ui_plan --> pkg_client_locale
-  pkg_client_ui_plan --> pkg_client_runtime
-  pkg_client_ui_plan --> pkg_client_ui_conversation
-  pkg_client_ui_plan --> pkg_client_ui_primitives
-  pkg_client_ui_plan --> pkg_client_ui_slots
-  pkg_client_ui_plan --> pkg_invariants
-  pkg_client_ui_plan --> pkg_plan_mode
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_client_ui_tool
-  pkg_client_ui_skill --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_client_locale
-  pkg_client_ui_subagent --> pkg_client_runtime
-  pkg_client_ui_subagent --> pkg_client_ui_conversation
-  pkg_client_ui_subagent --> pkg_client_ui_primitives
-  pkg_client_ui_subagent --> pkg_client_ui_slash
-  pkg_client_ui_subagent --> pkg_client_ui_slots
-  pkg_client_ui_subagent --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_subagent
-  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_agent
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_commands
+  pkg_client_ui_conversation --> pkg_compact
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_llm_retry
+  pkg_client_ui_conversation --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_tools
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1107,6 +1037,14 @@ flowchart TD
   pkg_workflow_workerthread --> pkg_subagent
   pkg_workflow_workerthread --> pkg_tools
   pkg_workflow_workerthread --> pkg_workflow
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_commands
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
   pkg_subagent_codex --> pkg_invariants
   pkg_subagent_codex --> pkg_llm
   pkg_subagent_codex --> pkg_sdk_protocol
@@ -1122,6 +1060,50 @@ flowchart TD
   pkg_subagent_spawn --> pkg_invariants
   pkg_subagent_spawn --> pkg_subagent
   pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1163,6 +1145,33 @@ flowchart TD
   pkg_subagent_dsh_sdk --> pkg_session
   pkg_subagent_dsh_sdk --> pkg_subagent
   pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1240,7 +1249,6 @@ flowchart TD
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
-| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
@@ -1257,8 +1265,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1269,7 +1276,6 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1297,19 +1303,18 @@ flowchart TD
 | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
-| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`compact`](../packages/compact/compact) | `compact` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
@@ -1317,7 +1322,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
@@ -1327,10 +1332,7 @@ flowchart TD
 | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1349,6 +1351,7 @@ flowchart TD
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1357,20 +1360,26 @@ flowchart TD
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
-| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
-| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm-retry`](../packages/llm/llm-retry), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
 | [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index d814b6ac6e..e676227869 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-catalog.md
 persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8
-persistence-catalog.zh.md: 364912b88c3b2c5efd92a616034be9ef5025ee67
+persistence-catalog.zh.md: d8743a1b0f26f2a4cf50aed42eb68f6c6db1ba13
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 364912b88c..d8743a1b0f 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -5,7 +5,7 @@
 
 [English](persistence-catalog.md) | 中文
 
-会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
+会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件对 `@deepseek-ai/dsh-session/types` 的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
 
 英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（doc-typecheck 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
 
@@ -103,7 +103,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
+来源：[`packages/core/agent/src/types.ts:19`](../packages/core/agent/src/types.ts)
 
 ### `approval/*`
 
@@ -214,7 +214,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
+来源：[`packages/interaction/commands/src/types.ts:41`](../packages/interaction/commands/src/types.ts)
 
 #### `command/run` — log-only
 
@@ -232,7 +232,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-来源：[`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
+来源：[`packages/interaction/commands/src/types.ts:34`](../packages/interaction/commands/src/types.ts)
 
 ### `compact/*`
 
@@ -243,10 +243,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * Marks the end of a compaction — log-only, releases the lock. Its owner
  * matches `compact/start`; `error` records an unsuccessful attempt.
  */
-'compact/end': { turn: number | null; error?: string }
+'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-来源：[`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:71`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -270,7 +270,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:81`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -280,10 +280,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * `compact/end`. A numbered owner is strictly enclosed by that open turn;
  * `null` identifies a standalone manual transaction between turns.
  */
-'compact/start': { turn: number | null }
+'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-来源：[`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:23`](../packages/compact/compact/src/types.ts)
 
 #### `compact/summary` — log-only
 
@@ -298,6 +298,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * before it (`compact/prune` documents the shared protocol).
  */
 'compact/summary': {
+  compactionId: CompactionId
+  sourceCommandId?: CommandId
   summary: ContentBlock[]
   shadowedRange: { start: number; end: number }
   shadowedSeqs: number[]
@@ -333,7 +335,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-来源：[`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:33`](../packages/compact/compact/src/types.ts)
 
 ### `feedback/*`
 
@@ -414,29 +416,19 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 ```ts persistence-catalog
 /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-'llm/retry': {
-  turn: number
-  step: number
-  provider: string
-  mode: 'normal'
-  policyKey: string
-  retry: number
-  maxRetries: number
-  delayMs: number
-  failure: LlmFailure
-} | {
-  turn: number
-  step: number
-  provider: string
-  mode: 'always'
-  policyKey: string
-  retry: number
-  delayMs: number
-  failure: LlmFailure
-}
+'llm/retry': LlmRetryEventData
 ```
 
-来源：[`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts)
+来源：[`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts)
+
+#### `llm/retry-started` — log-only
+
+```ts persistence-catalog
+/** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+'llm/retry-started': LlmRetryStartedEventData
+```
+
+来源：[`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src/types.ts)
 
 ### `permission/*`
 
@@ -658,12 +650,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * before returning), so its execution-enclosure relation holds by
  * construction.
  */
-'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+'tool/code-dispatch': CodeDispatchEventData
 ```
 
-类型：[CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
-
-来源：[`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
+来源：[`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts)
 
 #### `tool/code-dispatch-start` — log-only
 
@@ -681,12 +671,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * with `tool/code-dispatch` by `subCallId` (timing = the two events'
  * `time` fields).
  */
-'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+'tool/code-dispatch-start': CodeDispatchStartEventData
 ```
 
-类型：[CallId](subsystems/core.md)
-
-来源：[`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
+来源：[`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts)
 
 #### `tool/result` — surface
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 04f3cc5394..4c8cad1880 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: a5162c77d510c5ab66fa2dd6789693e1449970fb
-session.zh.md: 989a3f5368aa0b0475dec4272fde724fd4a98230
+session.md: e5eb78908ba4b7ebfc398d5c735969a5a8937374
+session.zh.md: 51729999a831c94e87e36ec1c4705201f9c8360f
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index a5162c77d5..e5eb78908b 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -580,6 +580,8 @@ Activity ordering excludes the boundary through `lastActivityTime(events)`: pick
 
 A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
 
+When several events in one plugin-owned family assemble into one Web Client Conversation Node, every start, update, result, resource, or interruption event in that family carries or independently derives the same stable business id. This requirement applies to correlated Node families, not to every Session event; it lets the client group each event without guessing from adjacency or scanning history. See the [Conversation Node cookbook](../cookbook/adding-a-conversation-node.md).
+
 The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
 ## Durability contract
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 989a3f5368..51729999a8 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -584,6 +584,8 @@ interface TurnEndReasonMap {
 
 插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
 
+如果同一个插件事件族中的多条事件要组装成一个 Web Client Conversation Node，该事件族中的每条 start、update、result、resource 或 interruption 事件都必须携带或独立推导出同一个稳定业务 id。此要求只约束需要关联的 Node 事件族，并不要求每条 Session 事件都有业务 id；Client 因此无须根据相邻关系猜测归属，也无须扫描历史。参见 [Conversation Node 实操手册](../cookbook/adding-a-conversation-node.md)。
+
 钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
 ## 持久性约定
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index 78704f52fa..9626e96e74 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -54,6 +54,12 @@ Non-negotiables across the layers:
 - **Notifier publication discipline**: `notifyNow` is only the direct echo of a user gesture; structural updates use microtask-batched `markDirty`, while visible streaming chunks use cumulative `markFrameDirty`. See `runtime/src/client/sessions/notifier.ts`.
 - **The web layer is pure presentation.** Nothing that is "how to draw" (tool-card views, queue states) enters the session log; the host computes such data per frame or pushes it live, and replay recomputes it — falling back to the generic form when it can't. A new *model-visible* input still requires a session event (repo-wide rule).
 
+## Conversation Node discipline
+
+- A Chat business feature registers one `ConversationNodeDefinition` and its keyed `conversation.chat.node` renderer; do not add its event switch or fold to `Session`, `SessionManager`, or a central built-in dispatcher. Follow the [Conversation Node cookbook](../../docs/cookbook/adding-a-conversation-node.md).
+- `match(event)` reads only the current event. Every event in a multi-event Context carries or independently derives the same stable business id; `update` folds one Match into State and remains deterministically replayable by log `seq`.
+- The append hot path and renderers never scan the full event window, Contexts, or Chat Nodes. Accumulate in State, publish same-Turn/Step facts through `buildLocationData()`, and consume final Node data or constrained Location hooks.
+
 ## Directory regime (plugin packages)
 
 One UI feature = one plugin package (`src/client/` browser half). A multi-domain package splits by future package boundaries — ui-conversation is the exemplar: `contract/` (the only shared face), domain directories that never import a sibling domain, and `apply.ts` as the single cross-domain assembly point; `scripts/verify-client-domain-graph.ts` enforces the levels. Registration goes through `slots.register` in `apply` — never module-level side effects.
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index d47266cd8a..139474af19 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: 46a383f22032c8da7e4bb9b5fb445980661c670f
-README.zh.md: 73578a8f249472abfdd7c539e3eaee6de767ad60
+README.md: df3689176cf059f46004fa7ecb31ab7c326ea0bc
+README.zh.md: 9afe9773ff2a6a320bdf66978877678428c46118
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 46a383f220..df3689176c 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -38,6 +38,8 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 Each `Session` gives its contiguous event window to a `ConversationNodeAssembler`. Plugins register business Definitions that map one event to a stable `{kind, id}`, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.
 
+Definition authors keep matching local to the current event, give every correlated event a stable business id, and make updates replayable by log `seq`; renderers consume final Node data and constrained Location values rather than scanning Session or Chat collections. The [Conversation Node cookbook](../../../docs/cookbook/adding-a-conversation-node.md) gives the complete registration and pagination path.
+
 `ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. StatsLine reads `ConversationSnapshot.chat.legacy.nodes`, while Session mirrors that legacy slice into the top-level `nodes`, `partial`, and `runningCalls` public compatibility fields without running a second business fold. Trajectory consumes neither compatibility surface; its activated `session-history` inspection keeps an independent fold until it gains its own registered target.
 
 The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the [client Tool presentation decision](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md).
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 73578a8f24..9afe9773ff 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -38,6 +38,8 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 每个 `Session` 都把连续事件窗口交给 `ConversationNodeAssembler`。插件注册业务 Definition，把单个事件映射为稳定的 `{kind, id}`，在唯一 start 事件处创建 State，折叠有关联的 update，再为已注册的视图目标构造最终节点。Assembler 负责 Context 索引、只读前序 Context 查询，以及引用稳定的 Turn/Step Location 索引。实时 append 只对每个 Definition 求值一次，并且只更新命中的 Context；加载更早分页时保留已有 Context 与节点身份，只匹配新 prepend 的事件，并重放前序依赖或 Location 事实发生变化的 Context。完整替换仅用于 open、resync 和 gap repair。
 
+Definition 作者只根据当前事件完成匹配，为每条关联事件提供稳定业务 id，并保证 update 能按日志 `seq` 回放；renderer 只消费最终 Node data 与受限 Location value，不扫描 Session 或 Chat 集合。完整注册和分页路径见 [Conversation Node 实操手册](../../../docs/cookbook/adding-a-conversation-node.md)。
+
 `ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。StatsLine 读取 `ConversationSnapshot.chat.legacy.nodes`；Session 则把该 legacy slice 镜像到顶层 `nodes`、`partial` 和 `runningCalls` 公共兼容字段，无须运行第二套业务 fold。Trajectory 不消费这两种兼容表面；在它获得独立注册 target 之前，已激活的 `session-history` inspection 继续维护独立 fold。
 
 Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新只通知受影响的 node key；结构变化才重建顺序和 Location 成员关系；prepend 只增加行，不替换既有 keyed value。每个 Assistant chunk 都会更新 Definition State，但最多每个 animation frame 请求一次物化；final message 与 Turn/Step 关闭会立即发布。参见 [Client Tool 展示所有权决策](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md)。
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index bb15c65029..1238e136d7 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: 3570e814609af0bc4e7d048a55205af756fae843
-README.zh.md: e37f867c72d83b47924e87261e6ee5ff8b374a6f
+README.md: d894d3e578f065e9cb2c45676224efd1f4f76fa8
+README.zh.md: ec99a8d7daa593cdf3014f292a095fb2fd6f39d3
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 3570e81460..d894d3e578 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -12,6 +12,8 @@ Another plugin can make one session's composer inert through `ctx.conversation.b
 
 The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
+Chat business rows are independent registry contributions rather than a closed built-in union. A client plugin declaration-merges its typed `ChatNodeDataMap` key, registers a `ConversationNodeDefinition` on `ctx.conversationEvents`, and registers the matching keyed renderer on `conversation.chat.node`; it does not modify Session folds or a central renderer switch. The [Conversation Node cookbook](../../../docs/cookbook/adding-a-conversation-node.md) covers stable event ids, append/prepend replay, Location data, and renderer constraints.
+
 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The runtime manager projects every approval or question wait through `SessionSummary.pendingInteraction`, including sessions never instantiated; `ui-workspace` owns its sidebar presentation. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index e37f867c72..ec99a8d7da 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -12,6 +12,8 @@
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
+Chat 业务行是彼此独立的注册表贡献，不是封闭的内建联合。Client 插件通过 declaration merging 增加类型化 `ChatNodeDataMap` key，在 `ctx.conversationEvents` 上注册 `ConversationNodeDefinition`，再向 `conversation.chat.node` 注册匹配的 keyed renderer；它无须修改 Session fold 或中央 renderer switch。稳定事件 id、append/prepend 回放、Location data 与 renderer 约束见 [Conversation Node 实操手册](../../../docs/cookbook/adding-a-conversation-node.md)。
+
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
 已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[生产者标签决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源字段列出。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index b5c000a714..2626cec2da 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,7 +1,7 @@
 {
   "AGENTS.md": 1782,
   "docs/AGENTS.md": 1320,
-  "docs/architecture.md": 2160,
+  "docs/architecture.md": 2174,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 1150,
diff --git a/website/docs.ts b/website/docs.ts
index 1e97d88e24..a8d07a59c2 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -396,6 +396,14 @@ const reference = [
     section: { root: '开发手册', en: 'Cookbook' },
     order,
   }))),
+  ...pairedPages([{
+    source: 'docs/cookbook/adding-a-conversation-node.md',
+    route: 'reference/cookbook/adding-a-conversation-node.md',
+    label: { root: '新增 Conversation Node', en: 'Adding a Conversation Node' },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: '开发手册', en: 'Cookbook' },
+    order: 4,
+  }]),
 ]
 
 /** Every canonical page published by the documentation website. */

From 548726eede3efdee74bda3a8da0b3b1e87fb3e3c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:58:29 +0800
Subject: [PATCH 245/262] ci(wine): add verified archive mirror fallback

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 ++--
 ...26-08-08-native-windows-pull-request-ci.md |  2 +-
 ...08-08-native-windows-pull-request-ci.zh.md |  2 +-
 scripts/wine-windows-gates.sh                 | 22 ++++++++++++++-----
 4 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 19c54de94b..cff610e481 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: a1f294b2b9e73a5d14a00780c7b0adfaf58e4702
-2026-08-08-native-windows-pull-request-ci.zh.md: 2c91c21118f5ebbd9f0e341f7d31ec71481db4dc
+2026-08-08-native-windows-pull-request-ci.md: 258bca96db04c44ca2a3509c297028e31ef5375e
+2026-08-08-native-windows-pull-request-ci.zh.md: dd0031630eea9bb09a4a4db0125933ba0c7bac2f
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index a1f294b2b9..258bca96db 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -10,7 +10,7 @@ The required pull-request Windows verdict needs a fast win32 toolchain signal wi
 
 ## Decision
 
-The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries so a stalled download fails or recovers before consuming the job timeout. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries; when nodejs.org stalls on the large archive, a range-capable transport mirror resumes the same bytes, but nodejs.org remains the version and SHA-256 authority and the archive is never promoted before that checksum passes. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
 
 Every pull request also starts an independent `windows-native` job named `windows node 24 / native complete` on GitHub's standard `windows-2025` image. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. The job is deliberately absent from `all-checks-passed.needs`: the aggregate neither waits for it nor changes conclusion because of it, while the native job retains its own unmasked success or failure result.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 2c91c21118..dd0031630e 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试，使停滞的下载在耗尽作业超时前失败或恢复。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试；nodejs.org 的大文件传输停滞时，由支持范围请求的传输镜像续传相同字节，但版本和 SHA-256 权威仍属于 nodejs.org，归档通过该校验前绝不会投入使用。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
 
 每个拉取请求还会在 GitHub 标准 `windows-2025` 镜像上启动一个独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。该作业被刻意排除在 `all-checks-passed.needs` 之外：聚合流程既不等待它，也不会因它改变结论；原生作业则保留自身未被掩盖的成功或失败结果。
 
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index 34e58274ce..5e46b75f91 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -77,22 +77,32 @@ mkdir -p "$cache_dir" "$scratch/logs"
 curl_metadata_args=(
   --fail --silent --show-error --location
   --retry 3 --retry-all-errors --retry-delay 2
-  --connect-timeout 10 --max-time 30 --retry-max-time 120
+  --http1.1 --connect-timeout 10 --max-time 30 --retry-max-time 120
 )
 
 download_node_archive() {
-  local url="$1" output="$2" attempt status=0
+  local version="$1" output="$2" attempt status=0
+  local archive="node-$version-win-x64.zip"
+  local primary_url="https://nodejs.org/dist/$version/$archive"
+  local mirror_url="https://npmmirror.com/mirrors/node/$version/$archive"
+
+  if curl --fail --silent --show-error --location --http1.1 \
+    --connect-timeout 10 --max-time 300 --speed-limit 1024 --speed-time 30 \
+    -o "$output" "$primary_url"; then
+    return 0
+  fi
+  echo 'wine-windows-gates: nodejs.org archive transfer stalled; resuming from the checksum-untrusted transport mirror' >&2
   for attempt in 1 2 3; do
-    if curl --fail --silent --show-error --location \
+    if curl --fail --silent --show-error --location --http1.1 \
       --continue-at - --connect-timeout 10 --max-time 300 \
       --speed-limit 1024 --speed-time 30 \
-      -o "$output" "$url"; then
+      -o "$output" "$mirror_url"; then
       return 0
     else
       status=$?
     fi
     (( attempt < 3 )) || break
-    echo "wine-windows-gates: Windows Node archive transfer failed (exit $status) on attempt $attempt; resuming partial download" >&2
+    echo "wine-windows-gates: mirror transfer failed (exit $status) on attempt $attempt; resuming partial download" >&2
   done
   return "$status"
 }
@@ -109,7 +119,7 @@ provision_node() {
   if [ -n "$version" ]; then
     zip="$cache_dir/node-$version-win-x64.zip"
     if [ ! -f "$zip" ]; then
-      download_node_archive "https://nodejs.org/dist/$version/node-$version-win-x64.zip" "$zip.tmp"
+      download_node_archive "$version" "$zip.tmp"
       local expected
       expected="$(curl "${curl_metadata_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
         | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"

From fcbc97a88dd7f22aa5f71342d19248485e7cc58f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:08:37 +0800
Subject: [PATCH 246/262] fix(client): address conversation assembly review

---
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../src/client/conversation-nodes/inbox.ts    |  4 +-
 .../src/client/conversation-nodes/retry.ts    |  1 +
 .../conversation-node-definitions.spec.ts     | 32 ++++++++++++
 .../client/ui-deliverables/README.i18n.yaml   |  4 +-
 packages/client/ui-deliverables/README.md     |  2 +-
 packages/client/ui-deliverables/README.zh.md  |  2 +-
 .../tests/produced-files.spec.tsx             | 52 ++++++++++++++++++-
 packages/compact/compact/src/types.ts         |  4 +-
 packages/llm/llm-retry/src/types.ts           |  4 +-
 .../llm/llm-retry/tests/invariant.spec.ts     |  2 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |  2 +-
 .../context-breakdown-projection.spec.ts      |  2 +-
 .../tests/token-usage-projection.spec.ts      |  2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  2 +-
 tsconfig.base.json                            |  1 +
 vitest.config.ts                              |  1 -
 19 files changed, 102 insertions(+), 23 deletions(-)

diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 139474af19..734b158e66 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: df3689176cf059f46004fa7ecb31ab7c326ea0bc
-README.zh.md: 9afe9773ff2a6a320bdf66978877678428c46118
+README.md: d4031c2e3b7730bdb0075ac84c50ad3e46ce63a2
+README.zh.md: ca6ac9f5e8efec3472c03b044739a9221e98183c
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index df3689176c..d4031c2e3b 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -58,7 +58,7 @@ Every `ToolCallBlock` recursively owns its children through `subCalls`, in start
 
 ## Model retry projection
 
-The Session object validates plugin-owned, provider-routed `llm/retry` payloads at the event wire boundary against the producer's complete field contract, including timer, integer, status, provider-delay, and non-empty diagnostic bounds. A valid event removes the matching failed step's streaming partial and inserts a durable retry notice at the event's sequence position. The notice is `scheduled` until a following retry turn starts; an aborted or disposed source turn marks it `cancelled`, while the retry turn marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. A terminal `turn/end` error without a retry projects one `turn-error` node from its durable message and optional code; AUTH projections replace provider copy that may echo credential fragments with `API key is invalid`, while the raw diagnostic remains in the session log. A retried failure keeps only the retry notice for that attempt. Window rebuild and history replay apply the same projection, so refresh neither resurrects discarded chunks nor loses terminal failure feedback. Visible unfinalized output is frozen as an interrupted assistant node beside the terminal error.
+The Host-owned LLM retry invariant validates provider-routed `llm/retry` and `llm/retry-started` records at the durable append boundary, including their identity, ordering, timer, integer, status, provider-delay, and non-empty diagnostic contracts. In the client, the Retry, Assistant, and Turn Error Definitions fold those records with Assistant and Turn/Step events: a failed step's streaming partial is removed and a durable retry notice appears at the retry event's sequence position. The notice is `scheduled` until the matching started record arrives; closing its owning Step or Turn first marks it `cancelled`, while the started record marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. A terminal `turn/end` error without a retry projects one `turn-error` node from its durable message and optional code; AUTH projections replace provider copy that may echo credential fragments with `API key is invalid`, while the raw diagnostic remains in the session log. A retried failure keeps only the retry notice for that attempt. Window rebuild and history replay use the same Definitions, so refresh neither resurrects discarded chunks nor loses terminal failure feedback. Visible unfinalized output is frozen as an interrupted Assistant node beside the terminal error.
 
 ## Session forking
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 9afe9773ff..ca6ac9f5e8 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -58,7 +58,7 @@ Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新
 
 ## 模型重试投影
 
-Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
+Host 所属的 LLM retry invariant 会在持久追加边界验证按提供方路由的 `llm/retry` 与 `llm/retry-started` 记录，包括标识、顺序、计时器、整数、状态、提供方延迟和非空诊断字段约定。客户端的 Retry、Assistant 与 Turn Error Definition 把这些记录和 Assistant、Turn／Step 事件一起折叠：失败步骤的流式输出片段会被移除，并在 retry 事件的序列位置插入一条持久重试提示。该提示在匹配的 started 记录到达前为 `scheduled`；如果所属 Step 或 Turn 先关闭，则标记为 `cancelled`，started 记录到达后则标记为 `started`。normal mode 提示携带其有限上限；always mode 提示保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败只保留该次尝试的重试提示。窗口重建与历史回放使用同一组 Definition，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 Assistant 节点。
 
 ## 会话 fork
 
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
index 74406c324a..e3cfae47f4 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
@@ -2,9 +2,7 @@ import type { Context } from 'cordis'
 import type {
   ConversationNodeDefinition, ConversationPreviousContext,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import type {} from '@deepseek-ai/dsh-agent/types'
-
-type InboxTarget = 'next-turn' | 'next-step'
+import type { InboxTarget } from '@deepseek-ai/dsh-agent/types'
 
 interface InboxIdentity {
   readonly id: string
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
index f383bc46d8..fa7c2ee5cf 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -31,6 +31,7 @@ function scheduledNode(match: Parameters<ConversationNodeDefinition['start']>[1]
   }
 }
 
+/** A scheduled attempt is cancelled once either owning boundary closes. */
 function isClosed(location: ConversationLocation): boolean {
   return (location.kind === 'step' && location.step.status === 'closed')
     || ((location.kind === 'step' || location.kind === 'turn') && location.turn.status === 'closed')
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 3e5dcccff3..d90093b864 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -465,6 +465,38 @@ describe('built-in conversation node Definitions', () => {
     expect(node(snapshot(value), 'user')).toBeUndefined()
   })
 
+  it('orders claimed steering after the finalized Turn tail', () => {
+    const steering = textMessage('steer-after-answer', 'change direction')
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('assistant-before-steering', 'initial answer'),
+      }, { surfaceOp: 'append' }),
+      at(4, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        inserted: [steering],
+      }),
+      at(5, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        removedCount: 1,
+        inserted: [],
+      }),
+      at(6, 'user/message', steering, { surfaceOp: 'append' }),
+      at(7, 'step/end', { turn: 1, step: 1 }),
+      at(8, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+
+    const current = snapshot(value)
+    const steeringNode = node(current, 'steering')
+    expect(steeringNode).toBeDefined()
+    expect(current.locations.getTurn(1).at(-1)).toBe(steeringNode?.key)
+  })
+
   it('classifies appended producer context from durable source metadata', () => {
     const value = assembler([
       at(1, 'user/message', {
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index e9810d98da..0df3ca0d86 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/ui-deliverables/README.md
-README.md: 189dedd88fed6914012204118ccdf9bdd0cd3bb2
-README.zh.md: ba493549bd0bc3f8a2adbda5989448e497f0af93
+README.md: 7d03e5faedda3ba8c9cc4cab6ca134d98dc7ec13
+README.zh.md: dfbbc7a39aa94aab438119a4f23ffb02da2daa3d
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index 189dedd88f..7d03e5faed 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Produced-files feature owner: registers the deliverables row a finished turn ends with into the chat view's `conversation.chat.turnTail` hole. All policy lives here; removing this plugin's line from cordis.yml removes the surface entirely, and the owning view renders an empty hole at zero cost.
 
-`producedForClosing` derives one turn's produced files from the tail hole's owner currency — the finalized snapshot nodes and the closing assistant's seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row.
+`deliverablesDefinition` folds each Turn's successful mutation calls into engine-published `DeliverablesTurnData`; `producedForClosing` reads that data with the closing Assistant seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per Turn in first-seen order. The Conversation Location index owns Turn membership, so a Turn that mutates and then ends without content text cannot spill into the next Turn's row.
 
 `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index ba493549bd..dfbbc7a39a 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -4,7 +4,7 @@
 
 产出文件功能的属主：把已完成轮次末尾的产出文件行注册到 chat 视图的 `conversation.chat.turnTail` slot 中。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该界面，属主视图无需额外开销即可渲染空 slot。
 
-`producedForClosing` 根据 tail slot 属主提供的当前数据，即定稿快照节点和收尾助手的 seq，推导一个轮次产出的文件。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在轮次边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
+`deliverablesDefinition` 把每个 Turn 中成功的修改调用折叠进引擎发布的 `DeliverablesTurnData`；`producedForClosing` 结合收尾 Assistant 的 seq 读取这份数据。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一个 Turn 内按首见顺序只出现一次。Conversation Location 索引拥有 Turn 成员关系，因此一个 Turn 即使先修改文件、随后没有正文内容就结束，也不会溢进下一个 Turn 的行里。
 
 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个低调的标签、至多六个标签项（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每个标签项经由属主提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index b8e7cd111e..91b15cf361 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 /**
  * ui-deliverables browser half: the derivation contract of
- * `producedForClosing` over finalized snapshot nodes, the row's rendering
+ * `producedForClosing` over engine-published Turn data, the row's rendering
  * and opener wiring, and the plugin registrations' fiber-teardown removal
  * (HMR safety) against the real SlotsService.
  */
@@ -12,7 +12,7 @@ import {
   ConversationEventRegistry, ConversationNodeAssembler, SlotsService,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  ConversationEventInput, ConversationLocationDataStore, ConversationNodeDefinition,
+  ConversationEventInput, ConversationLocationDataStore, ConversationMatch, ConversationNodeDefinition,
   ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewDefinition,
   ConversationViewNode, ToolResultNode, TurnLocation,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -107,6 +107,10 @@ function at(
   }
 }
 
+function matched(input: ConversationEventInput, role: ConversationMatch['role']): ConversationMatch {
+  return { ...input, role, location: { kind: 'unresolved' } }
+}
+
 function call(
   seq: number,
   callId: string,
@@ -190,6 +194,50 @@ describe('produced-file Turn data', () => {
     ])
   })
 
+  it('ignores calls without mutation locations, orphan results, and replacement results', () => {
+    const replacement = result(8, 'replacement')
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'tool/call', { turn: 1, step: 1, callId: 'no-view', name: 'fixture', arguments: '{}' }),
+      result(3, 'no-view'),
+      call(4, 'locationless-edit', { card: 'generic', title: 'Edit', kind: 'edit' }),
+      result(5, 'locationless-edit'),
+      result(6, 'orphan'),
+      call(7, 'replacement', diff('replaced.txt')),
+      {
+        ...replacement,
+        event: {
+          ...replacement.event,
+          surfaceOp: { op: 'replace', start: 1, end: 1 },
+        } as ConversationEventInput['event'],
+      },
+      at(9, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+
+    expect(producedForClosing(deliverablesOf(value))).toEqual([])
+  })
+
+  it('rejects an invalid start match and preserves state for an unrelated update', () => {
+    const startMatch = matched(at(1, 'turn/start', { turn: 1 }), 'start')
+    const emptyContext: Parameters<typeof deliverablesDefinition.start>[0] = {
+      key: 'deliverables:1',
+      kind: 'deliverables',
+      id: '1',
+      matches: [startMatch],
+      start: startMatch,
+      state: undefined,
+      current: new Map(),
+    }
+    const reader: Parameters<typeof deliverablesDefinition.start>[2] = { previous: () => undefined }
+    const state = deliverablesDefinition.start(emptyContext, startMatch, reader)
+    const unrelated = matched(at(2, 'turn/end', { turn: 1, reason: { kind: 'completed' } }), 'update')
+    const context: Parameters<typeof deliverablesDefinition.update>[0] = { ...emptyContext, state }
+
+    expect(() => deliverablesDefinition.start(emptyContext, unrelated, reader))
+      .toThrow('deliverables start requires turn/start')
+    expect(deliverablesDefinition.update(context, unrelated)).toBe(state)
+  })
+
   it('replays a tail page once prepend supplies its missing Turn start', () => {
     const value = assembler([
       call(10, 'late', diff('history.txt')),
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index 53c3baf05f..2cee6c191a 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -9,9 +9,9 @@
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-import { CompactionId } from './brand.ts'
+import type { CompactionId } from './brand.ts'
 
-export { CompactionId }
+export type { CompactionId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index 5144939289..e78026cbeb 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,7 +1,7 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
-import { RetryId } from './brand.ts'
+import type { RetryId } from './brand.ts'
 
-export { RetryId }
+export type { RetryId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
index 917a6d03f8..dd22e11369 100644
--- a/packages/llm/llm-retry/tests/invariant.spec.ts
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -5,7 +5,7 @@ import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry'
 import { providerForOpenStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 9e17290b43..8affb9e059 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry'
 import type {} from '../src/index.ts'
 
 const dirs: string[] = []
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index bfbf6a89ee..9bdd1222f0 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -10,7 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/types'
+import { CompactionId } from '@deepseek-ai/dsh-compact'
 import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
 import {
   estimateContent,
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index 3f66e0564b..9ccc2d7e9b 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -7,7 +7,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/types'
+import { CompactionId } from '@deepseek-ai/dsh-compact'
 
 const ZERO: TokenUsageProjection = {
   uncachedInputTokens: 0,
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index db60b695b1..f9aa66bce5 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { CompactionId } from '@deepseek-ai/dsh-compact/types'
+import { CompactionId } from '@deepseek-ai/dsh-compact'
 import LlmService, { CallId, createUserMessage, GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
 import {
   type ReplayEntry,
diff --git a/tsconfig.base.json b/tsconfig.base.json
index c7be2d4925..e404e3fc8b 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -79,6 +79,7 @@
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
       "@deepseek-ai/dsh-user-approval/types": ["./packages/interaction/user-approval/src/types.ts"],
       "@deepseek-ai/dsh-user-interaction/types": ["./packages/interaction/user-interaction/src/types.ts"],
+      "@deepseek-ai/dsh-agent/types": ["./packages/core/agent/src/types.ts"],
       "@deepseek-ai/dsh-agent/brand": ["./packages/core/agent/src/brand.ts"],
       "@deepseek-ai/dsh-agent/invariant": ["./packages/core/agent/src/invariant.ts"],
       "@deepseek-ai/dsh-scope/invariant": ["./packages/core/scope/src/invariant.ts"],
diff --git a/vitest.config.ts b/vitest.config.ts
index 33512f4898..e07ae43ec3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -211,7 +211,6 @@ export default defineConfig({
         'packages/client/ui-workspace/src/client/index.ts',
         'packages/client/test-runtime/src/translate.ts',
         'packages/client/ui-primitives/src/JsonTree.tsx',
-        'packages/client/ui-deliverables/src/client/turn-deliverables.ts',
         // Typert generator: correctness is pinned by its fixture suites and
         // the byte-for-byte catalog reproduction test; per-file coverage
         // would put whole-workspace compiler analysis under v8

From 0cfe852c2d4f0893a7d77326995513916c79a872 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:21:49 +0800
Subject: [PATCH 247/262] fix(ui-conversation): ignore legacy compact events
 without ids

---
 .../client/conversation-nodes/compaction.ts   |  4 +++-
 .../conversation-node-definitions.spec.ts     | 20 +++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
index 04eace8038..d21b4aa4b4 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
@@ -39,7 +39,9 @@ export const compactionDefinition: ConversationNodeDefinition<CompactionState> =
       || event.type === 'compact/summary'
       || event.type === 'compact/end') {
       if (event.data.sourceCommandId !== undefined) return null
-      return { id: String(event.data.compactionId), role: event.type === 'compact/start' ? 'start' : 'update' }
+      const compactionId: unknown = event.data.compactionId
+      if (typeof compactionId !== 'string' || compactionId === '') return null
+      return { id: compactionId, role: event.type === 'compact/start' ? 'start' : 'update' }
     }
     return null
   },
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index d90093b864..016c7176db 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -698,6 +698,26 @@ describe('built-in conversation node Definitions', () => {
     })
   })
 
+  it('ignores legacy compaction transactions without correlation ids', () => {
+    const value = assembler([
+      at(10, 'compact/start', { turn: null }),
+      at(11, 'compact/end', { turn: null, error: 'This operation was aborted' }),
+      at(20, 'compact/start', { turn: null }),
+      at(21, 'compact/summary', {
+        summary: [{ type: 'text', text: 'legacy summary' }],
+        shadowedSeqs: [1, 2, 3],
+        shadowedTokenCount: 42,
+      }),
+      at(22, 'user/message', {
+        ...textMessage('legacy-checkpoint', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 3 } }),
+      at(23, 'compact/end', { turn: null }),
+    ], true)
+
+    expect(node(snapshot(value), 'compaction')).toBeUndefined()
+  })
+
   it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
     const value = assembler([
       at(5, 'llm/retry', {

From 81822f40762806c354f2abd489e04841653e507a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:23:58 +0800
Subject: [PATCH 248/262] fix(ui-conversation): skip uncorrelated legacy events

---
 .../src/client/conversation-nodes/retry.ts    |  7 ++-
 .../src/client/conversation-nodes/tool.ts     |  5 ++-
 .../conversation-node-definitions.spec.ts     | 44 +++++++++++++++++++
 3 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
index fa7c2ee5cf..d504f32928 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -42,10 +42,13 @@ export const retryDefinition: ConversationNodeDefinition<RetryState> = {
   kind: 'model-retry',
   match: (event) => {
     if (event.type === 'llm/retry') {
-      return { id: String(event.data.retryId), role: event.data.retry === 1 ? 'start' : 'update' }
+      const retryId: unknown = event.data.retryId
+      if (typeof retryId !== 'string' || retryId === '') return null
+      return { id: retryId, role: event.data.retry === 1 ? 'start' : 'update' }
     }
     if (event.type === 'llm/retry-started') {
-      return { id: String(event.data.retryId), role: 'update' }
+      const retryId: unknown = event.data.retryId
+      return typeof retryId === 'string' && retryId !== '' ? { id: retryId, role: 'update' } : null
     }
     return null
   },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
index dc9e996dcc..c1b8022e41 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -241,7 +241,10 @@ export const toolDefinition: ConversationNodeDefinition<ToolState> = {
       return { id: String(event.data.message.source.callId), role: 'update' }
     }
     if (event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch') {
-      return { id: String(event.data.rootCallId), role: 'update' }
+      const rootCallId: unknown = event.data.rootCallId
+      return typeof rootCallId === 'string' && rootCallId !== ''
+        ? { id: rootCallId, role: 'update' }
+        : null
     }
     return null
   },
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 016c7176db..db9c0ccdd4 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -718,6 +718,50 @@ describe('built-in conversation node Definitions', () => {
     expect(node(snapshot(value), 'compaction')).toBeUndefined()
   })
 
+  it('ignores legacy retry and code-dispatch events without correlation ids', () => {
+    const value = assembler([
+      at(10, 'llm/retry', {
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'first legacy retry' },
+      }),
+      at(11, 'llm/retry-started', { turn: 1, step: 1, retry: 1 }),
+      at(20, 'llm/retry', {
+        turn: 2,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'second legacy retry' },
+      }),
+      at(30, 'tool/code-dispatch-start', {
+        parentCallId: 'root',
+        subCallId: 'child',
+        name: 'legacy-subcall',
+        arguments: {},
+      }),
+      at(31, 'tool/code-dispatch', {
+        parentCallId: 'root',
+        subCallId: 'child',
+        name: 'legacy-subcall',
+        arguments: {},
+        content: [],
+      }),
+    ], true)
+
+    expect(node(snapshot(value), 'model-retry')).toBeUndefined()
+    expect(node(snapshot(value), 'tool-call')).toBeUndefined()
+  })
+
   it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
     const value = assembler([
       at(5, 'llm/retry', {

From d99ad2b1d05da476e93b5eaa4a58e288d4d8b179 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:36:57 +0800
Subject: [PATCH 249/262] fix conversation node review follow-ups

---
 docs/subsystems/compaction.i18n.yaml          |  4 ++--
 docs/subsystems/compaction.md                 |  7 +++---
 docs/subsystems/compaction.zh.md              |  7 +++---
 .../fixtures/workspace-context-compaction.ts  |  4 ++--
 packages/client/runtime/package.json          |  1 +
 .../src/client/sessions/steering-history.ts   |  4 +---
 .../src/client/conversation-nodes/command.ts  |  4 ++--
 packages/compact/compact/README.i18n.yaml     |  4 ++--
 packages/compact/compact/README.md            | 10 ++++----
 packages/compact/compact/README.zh.md         | 10 ++++----
 packages/compact/compact/src/checkpoint.ts    | 23 +++++++++----------
 packages/compact/compact/src/index.ts         | 13 ++++++-----
 .../tests/session-reference.spec.ts           | 15 ++++++++----
 packages/llm/llm-retry/README.i18n.yaml       |  4 ++--
 packages/llm/llm-retry/README.md              |  4 ++--
 packages/llm/llm-retry/README.zh.md           |  4 ++--
 .../tool-cordis/src/api-catalog.ts            |  2 +-
 pnpm-lock.yaml                                |  3 +++
 18 files changed, 67 insertions(+), 56 deletions(-)

diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 532750f069..5e7c6d92be 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 11ee6eae797db1c57bf2ffbb90f1f37f47b8400c
-compaction.zh.md: a560e47dbb7aa92f0757179534803bbcaaebc6ba
+compaction.md: 8325694d92aa1a3019aef8f6b0c1f99d45ad0df5
+compaction.zh.md: 9f9014b8c1c1db12abc6581fbe6ebacfac3dd6fe
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 11ee6eae79..8325694d92 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -66,7 +66,7 @@ Automatic callers state why policy is running; implementations may treat confirm
 type CompactionTrigger = 'pressure' | 'context-overflow'
 ```
 
-`CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, `compactNow(agent, signal)` for one useful idle-session reduction even below pressure, and `compactRegion(...)` for an explicit inclusive surface range. `compactNow()` runs as agent maintenance between turns, returns `null` without writing when no useful range exists, records a standalone `turn: null` bracket before summarization, and flushes a closed attempt before later queued prompts may derive from the new surface. Every backend marks its replacement `user/message` with `COMPACT_CHECKPOINT_SOURCE`; client and wire consumers import that value and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compact/checkpoint` subpath, while the package root re-exports both for host consumers. The predicate keeps checkpoint recognition independent of any one backend. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration.
+`CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, `compactNow(agent, signal)` for one useful idle-session reduction even below pressure, and `compactRegion(...)` for an explicit inclusive surface range. `compactNow()` runs as agent maintenance between turns, returns `null` without writing when no useful range exists, records a standalone `turn: null` bracket before summarization, and flushes a closed attempt before later queued prompts may derive from the new surface. Every backend creates its replacement `user/message` source with `compactCheckpointSource(compactionId, sourceCommandId?)`; client and wire consumers import that constructor, `CompactCheckpointSource`, and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compact/checkpoint` subpath, while the package root re-exports them for host consumers. The required transaction identity correlates the replacement checkpoint, while the predicate keeps recognition independent of any one backend. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration.
 
 Expected manual failures use `ManualCompactionErrorCode`:
 
@@ -129,7 +129,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.compact` — `CompactService` (abstract seam)
 
-Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compact`.
 
 ```ts cordis-catalog
 /**
@@ -175,7 +175,8 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sour
  * balanced so assistant tool calls remain paired with their results. A model-
  * backed implementation forwards cancellation and rejects active, missing,
  * reversed, or unbalanced ranges. The target session is `agent.session`.
- * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Its replacement user message must use {@link compactCheckpointSource} with
+ * the transaction's `CompactionId`.
  * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
  * for the edge checks.
  *
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index a560e47dbb..9f9014b8c1 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -66,7 +66,7 @@ interface CompactionResult {
 type CompactionTrigger = 'pressure' | 'context-overflow'
 ```
 
-`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略，暴露 `compactNow(agent, signal)` 以便即使未达到压力也对空闲会话进行一次有效缩减，还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。`compactNow()` 作为轮次之间的 agent maintenance 运行；没有有效范围时返回 `null` 且不写入；在摘要前记录独立的 `turn: null` 标记对，并在后续排队提示词能够从新表层派生前 flush 已闭合尝试。每个后端都使用 `COMPACT_CHECKPOINT_SOURCE` 标记其替换用的 `user/message`；client 与 wire 消费方从无 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 子路径导入该值和 `isCompactCheckpointSource()`，包根则为 host 消费方重新导出两者。该判定函数使检查点识别不依赖任一特定后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。
+`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略，暴露 `compactNow(agent, signal)` 以便即使未达到压力也对空闲会话进行一次有效缩减，还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。`compactNow()` 作为轮次之间的 agent maintenance 运行；没有有效范围时返回 `null` 且不写入；在摘要前记录独立的 `turn: null` 标记对，并在后续排队提示词能够从新表层派生前 flush 已闭合尝试。每个后端都使用 `compactCheckpointSource(compactionId, sourceCommandId?)` 创建替换用 `user/message` 的源；client 与 wire 消费方从无 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 子路径导入该构造函数、`CompactCheckpointSource` 和 `isCompactCheckpointSource()`，包根则为 host 消费方重新导出它们。必填的事务身份会关联替换检查点，而该判定函数使检查点识别不依赖任一特定后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。
 
 预期的手动失败使用 `ManualCompactionErrorCode`：
 
@@ -129,7 +129,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.compact` — `CompactService` (abstract seam)
 
-Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compact`.
 
 ```ts cordis-catalog
 /**
@@ -175,7 +175,8 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sour
  * balanced so assistant tool calls remain paired with their results. A model-
  * backed implementation forwards cancellation and rejects active, missing,
  * reversed, or unbalanced ranges. The target session is `agent.session`.
- * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Its replacement user message must use {@link compactCheckpointSource} with
+ * the transaction's `CompactionId`.
  * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
  * for the edge checks.
  *
diff --git a/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts b/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
index e13e3cf6b3..6c1cd46fbf 100644
--- a/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
+++ b/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
@@ -1,6 +1,6 @@
 import type { Context } from 'cordis'
 import type {} from '@deepseek-ai/dsh-agent'
-import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
+import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compact'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-tools'
 
@@ -26,7 +26,7 @@ export function apply(ctx: Context): void {
     if (baseline === undefined) throw new Error('workspace baseline missing before snapshot compaction')
     agent.session.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'Earlier context was compacted for this snapshot.' }],
-      source: COMPACT_CHECKPOINT_SOURCE,
+      source: compactCheckpointSource(CompactionId('workspace-context-fixture')),
     }), {
       surfaceOp: { op: 'replace', start: baseline.seq, end: baseline.seq },
       sourceEventSeqs: [baseline.seq],
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index f5a9a06a60..83a62693cb 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
diff --git a/packages/client/runtime/src/client/sessions/steering-history.ts b/packages/client/runtime/src/client/sessions/steering-history.ts
index 4220a769ff..a28c3376a8 100644
--- a/packages/client/runtime/src/client/sessions/steering-history.ts
+++ b/packages/client/runtime/src/client/sessions/steering-history.ts
@@ -1,9 +1,7 @@
 /** Reconstruct durable steering identity from the event-sourced agent inbox. */
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import type {} from '@deepseek-ai/dsh-agent/types'
-
-type InboxTarget = 'next-turn' | 'next-step'
+import type { InboxTarget } from '@deepseek-ai/dsh-agent/types'
 
 /** Minimal pending identity retained while replaying durable inbox splices. */
 interface PendingIdentity {
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
index 38cb85ed87..752d7e3dd2 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
@@ -4,7 +4,7 @@ import type {
   ConversationNodeDefinition,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type { CompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
 import type {} from '@deepseek-ai/dsh-compact/types'
 import type {} from '@deepseek-ai/dsh-commands/types'
 import type { ManualCompactionChatData } from '../contract/chat-nodes.ts'
@@ -21,7 +21,7 @@ declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
 
 type CommandId = CommandNode['commandId']
 
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 
 interface CommandState {
   readonly command: CommandNode
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index ec95ee2165..8b16ecfa4b 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: 3fecc91422bcdc994bcbe4db308ee4a52cb3c53f
-README.zh.md: ea66d8bdb0684f27cf68a5431be75966041b7534
+README.md: eac4339da76352bc9468488d0828a0b90a993d48
+README.zh.md: 4aec6123169a7c88a36da647202e7462fbf94564
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 3fecc91422..eac4339da7 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -8,7 +8,7 @@ This package owns the Service Definition role of the compaction capability, spli
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-compact` (this) | Service Definition: abstract service + `compact/*` events + `CompactionResult` + canonical checkpoint source + tool-pairing boundary helpers |
+| `@deepseek-ai/dsh-compact` (this) | Service Definition: abstract service + `compact/*` events + `CompactionResult` + correlated checkpoint-source constructor + tool-pairing boundary helpers |
 | `@deepseek-ai/dsh-compact-basic` | Service provider: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
 | `@deepseek-ai/dsh-command-compact` | Consumer: the human `/compact` command over `ctx.compact.compactNow()` |
 
@@ -22,7 +22,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten
 |---|---|
 | `compactIfNeeded(agent, trigger, signal)` | Consider automatic compaction for `trigger: 'pressure' \| 'context-overflow'`. A pressure trigger may apply the backend's threshold and retained-tail policy; a confirmed overflow may force a useful balanced reduction. Returns the `CompactionResult`, or `null` when no safe range exists. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
 | `compactNow(agent, signal)` | Explicitly compact one useful balanced older span even below automatic pressure. It synchronously reserves idle turn admission before yielding, writes nothing when no useful span exists, records a standalone `compact/* { turn: null }` attempt before summarization, and awaits its durability checkpoint before release. Expected operational failures use `ManualCompactionError`; cancellation rethrows the exact abort reason. |
-| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source is `COMPACT_CHECKPOINT_SOURCE`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source comes from `compactCheckpointSource(compactionId)`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
 `CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/subsystems/compaction.md#compactionresult).
 
@@ -43,7 +43,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,
 3. appends `compact/summary` (log-only) with the summary, range, shadowed seqs, token count, and provider/model call envelope,
-4. appends a single `user/message` with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
+4. appends a single `user/message` with `source: compactCheckpointSource(compactionId, sourceCommandId?)` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
 5. appends `compact/end` (log-only) — releases the lock.
 
 The surface mutation (step 4) sits **inside** the lock bracket: `compact/end` is the last event, so the lock is never released before the mutation lands. A crash between `compact/start` and `compact/end` therefore leaves a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished while the surface was never shadowed.
@@ -64,11 +64,11 @@ The `compact/*` events extend `SessionEventMap` (merge-extensible) via declarati
 
 ## Implementing a backend
 
-Subclass `CompactService`, implement `compactIfNeeded`, `compactNow`, and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. Every successful backend uses `COMPACT_CHECKPOINT_SOURCE` on its replacement user message; `isCompactCheckpointSource()` recognizes the marker after persistence or cloning without depending on backend identity. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
+Subclass `CompactService`, implement `compactIfNeeded`, `compactNow`, and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. Every successful backend creates its replacement user message source with `compactCheckpointSource(compactionId, sourceCommandId?)`; the required `compactionId` correlates the checkpoint with its `compact/*` transaction, while `isCompactCheckpointSource()` recognizes the marker after persistence or cloning without depending on backend identity. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
 
 ## Recognizing a checkpoint outside the host program (`./checkpoint`)
 
-`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there.
+`compactCheckpointSource()`, `CompactCheckpointSource`, and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The constructor requires the owning `CompactionId`, preventing backends from writing an uncorrelated marker that the package invariant must reject. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to the leaf's source type, so renaming the plugin id there is a compile error here.
 
 ## Model Experience
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index ea66d8bdb0..4aec612316 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -8,7 +8,7 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-compact`（本包） | Service Definition：抽象服务 + `compact/*` 事件 + `CompactionResult` + 规范检查点源 + 工具配对边界 helper |
+| `@deepseek-ai/dsh-compact`（本包） | Service Definition：抽象服务 + `compact/*` 事件 + `CompactionResult` + 关联检查点源构造函数 + 工具配对边界 helper |
 | `@deepseek-ai/dsh-compact-basic` | Service provider：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
 | `@deepseek-ai/dsh-command-compact` | Consumer：面向人类的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
 
@@ -22,7 +22,7 @@
 |---|---|
 | `compactIfNeeded(agent, trigger, signal)` | 根据 `trigger: 'pressure' \| 'context-overflow'` 判断是否需要自动压缩。压力触发可应用后端的阈值与保留尾部策略；已确认溢出可强制进行有效的平衡缩减。返回 `CompactionResult`，无安全范围时则返回 `null`。后端摘要请求是直接的 `ctx.llm.stream()` 调用（不是 agent loop 步骤），因此每次调用都可在 `llm/stream` 处拦截。 |
 | `compactNow(agent, signal)` | 即使未达到自动压力，也显式压缩一段有效、平衡的较早范围。该操作会在让出控制权前同步预留空闲轮次接纳；没有有效范围时不写入任何内容；在摘要前记录独立的 `compact/* { turn: null }` 尝试；释放预留前等待其持久性检查点。预期操作失败使用 `ManualCompactionError`；取消会原样重新抛出 abort 原因。 |
-| `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源为 `COMPACT_CHECKPOINT_SOURCE`。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 |
+| `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源由 `compactCheckpointSource(compactionId)` 创建。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 |
 
 `CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/subsystems/compaction.md#compactionresult)。
 
@@ -43,7 +43,7 @@
 1. 追加 `compact/start`（仅日志）：获取锁；
 2. 摘要该范围；
 3. 追加 `compact/summary`（仅日志），其中记录摘要、范围、已遮蔽 seq、token 数与提供方／模型调用 envelope；
-4. 追加单个 `user/message`，其携带 `source: COMPACT_CHECKPOINT_SOURCE` 和包含摘要的 `surfaceOp: { op: 'replace', start, end }`：这是**本操作唯一的表层变更**；
+4. 追加单个 `user/message`，其携带 `source: compactCheckpointSource(compactionId, sourceCommandId?)` 和包含摘要的 `surfaceOp: { op: 'replace', start, end }`：这是**本操作唯一的表层变更**；
 5. 追加 `compact/end`（仅日志）：释放锁。
 
 表层变更（第 4 步）位于锁的起止范围**内**：`compact/end` 是最后一个事件，因此表层变更落地前绝不会释放锁。如果在 `compact/start` 与 `compact/end` 之间崩溃，会留下可检测的遗留锁（一个 `compact/start` 没有匹配的 `compact/end`），而不是虚假声称压缩已完成、但表层从未被遮蔽的 `compact/end`。
@@ -64,11 +64,11 @@
 
 ## 实现后端
 
-继承 `CompactService`，实现 `compactIfNeeded`、`compactNow` 与 `compactRegion`，再将子类作为插件加载：它会注册为 `ctx.compact`。每个成功后端都在替换 user 消息上使用 `COMPACT_CHECKPOINT_SOURCE`；`isCompactCheckpointSource()` 可在持久化或克隆后识别该标记，无需依赖后端身份。基于模板或模型的实现可以放在同级包中，不需更改调用方或共享 token meter。
+继承 `CompactService`，实现 `compactIfNeeded`、`compactNow` 与 `compactRegion`，再将子类作为插件加载：它会注册为 `ctx.compact`。每个成功后端都使用 `compactCheckpointSource(compactionId, sourceCommandId?)` 创建替换 user 消息的源；必填的 `compactionId` 将检查点与对应 `compact/*` 事务关联，而 `isCompactCheckpointSource()` 可在持久化或克隆后识别该标记，无需依赖后端身份。基于模板或模型的实现可以放在同级包中，不需更改调用方或共享 token meter。
 
 ## 在 host 程序之外识别检查点（`./checkpoint`）
 
-`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../interaction/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。
+`compactCheckpointSource()`、`CompactCheckpointSource` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。构造函数要求传入所属 `CompactionId`，防止后端写入缺少关联关系、必然被包不变量拒绝的标记。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../interaction/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子的源类型上，因此在此处改插件 id 会让那边编译失败。
 
 ## 模型体验
 
diff --git a/packages/compact/compact/src/checkpoint.ts b/packages/compact/compact/src/checkpoint.ts
index 9908fe4ac0..18a2c5985e 100644
--- a/packages/compact/compact/src/checkpoint.ts
+++ b/packages/compact/compact/src/checkpoint.ts
@@ -1,12 +1,12 @@
 /**
- * The compaction seam's canonical checkpoint source: the plugin marker every
- * backend stamps on the replacement user message that lands a checkpoint, plus
- * the predicate that recognizes it.
+ * Compaction checkpoint provenance: the correlated source constructor and type
+ * every backend uses for its replacement user message, plus the predicate that
+ * recognizes persisted checkpoints.
  *
- * The seam itself lives in `@deepseek-ai/dsh-compact`, which re-exports both of
- * these; this module is a pure value/predicate outlet (no cordis imports, no
- * module augmentation) so client and wire programs can name the checkpoint
- * source without loading the host plugin's Context merges — the
+ * The seam itself lives in `@deepseek-ai/dsh-compact`, which re-exports these
+ * contracts; this module is a pure type/value/predicate outlet (no cordis
+ * imports, no module augmentation) so client and wire programs can name the
+ * checkpoint source without loading the host plugin's Context merges — the
  * `dsh-commands/brand` shape.
  *
  * @module @deepseek-ai/dsh-compact/checkpoint
@@ -16,11 +16,10 @@ import type { MessageSource } from '@deepseek-ai/dsh-llm/message'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionId } from './brand.ts'
 
-/** Canonical source for the replacement user message produced by every compaction backend. */
-export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
 
 /** Message provenance carried by a concrete compaction checkpoint. */
-export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_SOURCE & {
+export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_MARKER & {
   readonly compactionId: CompactionId
   readonly sourceCommandId?: CommandId
 }
@@ -36,7 +35,7 @@ export function compactCheckpointSource(
   sourceCommandId?: CommandId,
 ): CompactCheckpointSource {
   return Object.freeze({
-    ...COMPACT_CHECKPOINT_SOURCE,
+    ...COMPACT_CHECKPOINT_MARKER,
     compactionId,
     ...sourceCommandId === undefined ? {} : { sourceCommandId },
   })
@@ -48,5 +47,5 @@ export function compactCheckpointSource(
  * @returns whether the source carries the backend-independent checkpoint marker.
  */
 export function isCompactCheckpointSource(source: MessageSource): boolean {
-  return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_SOURCE.plugin
+  return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_MARKER.plugin
 }
diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts
index 0085321333..6fb9706c04 100644
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -15,10 +15,10 @@ import type { CompactionResult } from './types.ts'
 export type { CompactionResult } from './types.ts'
 export { CompactionId } from './brand.ts'
 export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
-// The checkpoint source and its predicate are declared on the cordis-free
+// The checkpoint source constructor and predicate are declared on the cordis-free
 // `./checkpoint` leaf so client and wire programs can name them without this
 // root's Context merge; the root stays the host-side entry point for both.
-export { COMPACT_CHECKPOINT_SOURCE, compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
+export { compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
 export type { CompactCheckpointSource } from './checkpoint.ts'
 
 /** Why automatic policy is asking a backend to consider compaction. */
@@ -89,9 +89,9 @@ declare module 'cordis' {
  * and summarization, and may consume a separate measurement service. A
  * successful run replaces the selected surface span with one summary node and
  * prevents concurrent compaction of the same session. The replacement user
- * message uses {@link COMPACT_CHECKPOINT_SOURCE} so consumers recognize it
- * independently of the backend. Load one implementation per context as
- * `ctx.compact`.
+ * message uses {@link compactCheckpointSource} with the transaction identity
+ * so consumers recognize and correlate it independently of the backend. Load
+ * one implementation per context as `ctx.compact`.
  */
 export abstract class CompactService extends Service {
   constructor(ctx: Context) {
@@ -149,7 +149,8 @@ export abstract class CompactService extends Service {
    * balanced so assistant tool calls remain paired with their results. A model-
    * backed implementation forwards cancellation and rejects active, missing,
    * reversed, or unbalanced ranges. The target session is `agent.session`.
-   * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+   * Its replacement user message must use {@link compactCheckpointSource} with
+   * the transaction's `CompactionId`.
    * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
    * for the edge checks.
    *
diff --git a/packages/context/session-reference/tests/session-reference.spec.ts b/packages/context/session-reference/tests/session-reference.spec.ts
index b9e5e55241..ce964af16a 100644
--- a/packages/context/session-reference/tests/session-reference.spec.ts
+++ b/packages/context/session-reference/tests/session-reference.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
+import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compact'
 import { createUserMessage, CallId , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
@@ -48,6 +48,10 @@ function expectCode(code: SessionReferenceErrorCode): Error {
   return expect.objectContaining({ code }) as Error
 }
 
+function checkpointSource(id: string) {
+  return compactCheckpointSource(CompactionId(id))
+}
+
 function appendConversation(session: Session): void {
   const oldUser = session.append(
     'user/message',
@@ -75,7 +79,8 @@ function appendConversation(session: Session): void {
   session.append(
     'user/message',
     createUserMessage({
-      content: [{ type: 'text', text: '<compacted-summary>checkpoint</compacted-summary>' }], source: COMPACT_CHECKPOINT_SOURCE,
+      content: [{ type: 'text', text: '<compacted-summary>checkpoint</compacted-summary>' }],
+      source: checkpointSource('conversation'),
     }),
     {
       surfaceOp: { op: 'replace', start: oldUser.seq, end: oldAssistant.seq },
@@ -534,7 +539,8 @@ describe('session reference discovery and preparation', () => {
       source.append(
         'user/message',
         createUserMessage({
-          content: [{ type: 'text', text: `${id}-${'界'.repeat(400)}` }], source: COMPACT_CHECKPOINT_SOURCE,
+          content: [{ type: 'text', text: `${id}-${'界'.repeat(400)}` }],
+          source: checkpointSource(id),
         }),
         { surfaceOp: 'append' },
       )
@@ -616,7 +622,8 @@ describe('session reference discovery and preparation', () => {
     source.append(
       'user/message',
       createUserMessage({
-        content: [{ type: 'text', text: 'later compact checkpoint' }], source: COMPACT_CHECKPOINT_SOURCE,
+        content: [{ type: 'text', text: 'later compact checkpoint' }],
+        source: checkpointSource('later-source-mutation'),
       }),
       {
         surfaceOp: { op: 'replace', start: original.seq, end: later.seq },
diff --git a/packages/llm/llm-retry/README.i18n.yaml b/packages/llm/llm-retry/README.i18n.yaml
index 65e0c911ed..2a1f8d46a2 100644
--- a/packages/llm/llm-retry/README.i18n.yaml
+++ b/packages/llm/llm-retry/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/llm/llm-retry/README.md
-README.md: e6e56ec44032d714393c6fcc1c42d7271017a294
-README.zh.md: b7ce8bee4acd2c4f7c88870745dff96ec5695435
+README.md: 0a907b5505650f7c2cd5e9933750be3701f8e34b
+README.zh.md: bb8c5b50efddf3def0047f411285b57c3c544f95
diff --git a/packages/llm/llm-retry/README.md b/packages/llm/llm-retry/README.md
index e6e56ec440..0a907b5505 100644
--- a/packages/llm/llm-retry/README.md
+++ b/packages/llm/llm-retry/README.md
@@ -8,9 +8,9 @@ Each provider adapter owns an optional nested `retryPolicy`, captured when its r
 
 Both modes use bounded exponential backoff with symmetric jitter. A valid `providerRetryAfterMs` at or below `maxDelayMs` replaces local backoff without jitter. An over-cap provider delay makes normal mode delegate, while always mode uses its configured local backoff so it cannot terminate on that instruction.
 
-Before waiting, the plugin appends a non-surface `llm/retry` event with the provider, mode, canonical resolved-policy key, failure, and scheduled delay. Its payload is available from the browser-safe `@deepseek-ai/dsh-llm-retry/types` subpath, so remote renderers can consume the durable status without loading the policy runtime. The key includes every behavior-affecting field and sorts normal-mode codes because eligibility uses set membership. Retry numbers continue only across events with the same provider and complete policy key, so a route replacement with different limits, code membership, or backoff starts its own history. Normal events include the finite maximum; always events omit it, and UIs render `∞`. After the wait, the listener returns `{ kind: 'retry' }`, and the loop closes the failed turn and opens a retry turn over the same durable history. Cancellation and plugin disposal abort active backoff, drain active delegated recovery before applying the abort, and make a callback captured before disposal fail closed.
+Before waiting, the plugin appends a non-surface `llm/retry` event with the shared `retryId`, provider, mode, canonical resolved-policy key, failure, and scheduled delay. Its payload is available from the browser-safe `@deepseek-ai/dsh-llm-retry/types` subpath, so remote renderers can consume the durable status without loading the policy runtime. The key includes every behavior-affecting field and sorts normal-mode codes because eligibility uses set membership. Retry numbers continue only across events with the same provider and complete policy key, so a route replacement with different limits, code membership, or backoff starts its own history. Normal events include the finite maximum; always events omit it, and UIs render `∞`. When the wait completes, the plugin appends `llm/retry-started` with the same `retryId`, turn, step, and retry number immediately before returning `{ kind: 'retry' }`; cancellation during backoff writes no started event. The loop then closes the failed turn and opens a retry turn over the same durable history. Cancellation and plugin disposal abort active backoff, drain active delegated recovery before applying the abort, and make a callback captured before disposal fail closed.
 
-The separately published `./invariant` companion checks that every retry record names the current open turn and latest closed step, matches the failed request's durable provider, carries non-empty provider and policy identities, has mode-specific bounds, a unique step record, the correct provider-policy retry number, and a bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
+The separately published `./invariant` companion checks that every scheduled retry names the current open turn and latest closed step, matches the failed request's durable provider, carries non-empty provider and policy identities, has mode-specific bounds, a unique step record, the correct provider-policy retry number, and a bounded timer delay. It also requires each `llm/retry-started` event to name one prior scheduled attempt with the same `retryId`, turn, step, and retry number, and rejects repeated started events. Full jitter may schedule zero milliseconds at its lower boundary.
 
 ```yaml
 - name: '@deepseek-ai/dsh-llm-deepseek'
diff --git a/packages/llm/llm-retry/README.zh.md b/packages/llm/llm-retry/README.zh.md
index b7ce8bee4a..bb8c5b50ef 100644
--- a/packages/llm/llm-retry/README.zh.md
+++ b/packages/llm/llm-retry/README.zh.md
@@ -8,9 +8,9 @@
 
 两种 mode 都使用带对称 jitter 的有界指数退避。有效 `providerRetryAfterMs` 不超过 `maxDelayMs` 时会替换本地退避，并且不加 jitter。超出上限的提供方延迟会使 normal mode 继续委托；always mode 则改用已配置的本地退避，避免该指令终止重试。
 
-等待前，插件会追加一条不进入表层的 `llm/retry` 事件，其中包含提供方、mode、已解析策略的规范 key、失败和计划延迟。该载荷由可安全用于浏览器的 `@deepseek-ai/dsh-llm-retry/types` 子路径导出，因此远程渲染器无需加载策略运行时即可使用该持久状态。该 key 包含所有影响行为的字段，并对 normal mode 的 code 排序，因为合格性采用集合成员关系判断。只有提供方与完整策略 key 都相同的事件才会延续重试编号；因此，用限制、code 成员关系或退避不同的路由替换后，会开始自己的历史。normal 事件包含有限上限；always 事件省略该上限，UI 会渲染 `∞`。等待结束后，监听器返回 `{ kind: 'retry' }`，循环关闭失败轮次，并在同一持久历史上开启重试轮次。取消与插件 dispose 会中止活跃退避，在应用中止前排空活跃的委托恢复，并使 dispose 前捕获的 callback 只能以失败结束。
+等待前，插件会追加一条不进入表层的 `llm/retry` 事件，其中包含共享 `retryId`、提供方、mode、已解析策略的规范 key、失败和计划延迟。该载荷由可安全用于浏览器的 `@deepseek-ai/dsh-llm-retry/types` 子路径导出，因此远程渲染器无需加载策略运行时即可使用该持久状态。该 key 包含所有影响行为的字段，并对 normal mode 的 code 排序，因为合格性采用集合成员关系判断。只有提供方与完整策略 key 都相同的事件才会延续重试编号；因此，用限制、code 成员关系或退避不同的路由替换后，会开始自己的历史。normal 事件包含有限上限；always 事件省略该上限，UI 会渲染 `∞`。等待完成时，插件会在返回 `{ kind: 'retry' }` 前立即追加 `llm/retry-started`，其中带有相同的 `retryId`、轮次、步骤与重试编号；退避期间取消则不会写入 started 事件。随后循环关闭失败轮次，并在同一持久历史上开启重试轮次。取消与插件 dispose 会中止活跃退避，在应用中止前排空活跃的委托恢复，并使 dispose 前捕获的 callback 只能以失败结束。
 
-单独发布的 `./invariant` 配套模块会检查每个重试记录是否指向当前开启轮次及其最新已关闭步骤，是否与失败请求的持久提供方匹配，是否携带非空的提供方与策略标识，是否满足 mode 特定边界，是否拥有唯一步骤记录和正确的提供方策略重试编号，以及是否携带有界定时器延迟。完整 jitter 可以在下界调度为零毫秒。
+单独发布的 `./invariant` 配套模块会检查每个已调度重试是否指向当前开启轮次及其最新已关闭步骤，是否与失败请求的持久提供方匹配，是否携带非空的提供方与策略标识，是否满足 mode 特定边界，是否拥有唯一步骤记录和正确的提供方策略重试编号，以及是否携带有界定时器延迟。它还要求每个 `llm/retry-started` 事件通过相同的 `retryId`、轮次、步骤与重试编号指向一个先前调度的尝试，并拒绝重复的 started 事件。完整 jitter 可以在下界调度为零毫秒。
 
 ```yaml
 - name: '@deepseek-ai/dsh-llm-deepseek'
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index b52000f554..c8ec4894b4 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -282,7 +282,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
-        jsDoc: '/**\n * Forcibly compact a range of surface nodes into a single summary node.\n * `start` and `end` name an inclusive span by surface position, not numeric seq\n * order; replacements can make visible seqs non-monotonic. Both edges must be\n * balanced so assistant tool calls remain paired with their results. A model-\n * backed implementation forwards cancellation and rejects active, missing,\n * reversed, or unbalanced ranges. The target session is `agent.session`.\n * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.\n * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}\n * for the edge checks.\n *\n * @param start - first surface seq, inclusive.\n * @param end - last surface seq, inclusive.\n * @param agent - context whose session is mutated and whose routing options guide summarization.\n * @param signal - optional cancellation; model-backed implementations must forward it.\n * @throws when compaction is active or the range is missing, reversed, or unbalanced.\n * @returns the appended event seqs, summary, replaced range, and token accounting.\n */',
+        jsDoc: '/**\n * Forcibly compact a range of surface nodes into a single summary node.\n * `start` and `end` name an inclusive span by surface position, not numeric seq\n * order; replacements can make visible seqs non-monotonic. Both edges must be\n * balanced so assistant tool calls remain paired with their results. A model-\n * backed implementation forwards cancellation and rejects active, missing,\n * reversed, or unbalanced ranges. The target session is `agent.session`.\n * Its replacement user message must use {@link compactCheckpointSource} with\n * the transaction\'s `CompactionId`.\n * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}\n * for the edge checks.\n *\n * @param start - first surface seq, inclusive.\n * @param end - last surface seq, inclusive.\n * @param agent - context whose session is mutated and whose routing options guide summarization.\n * @param signal - optional cancellation; model-backed implementations must forward it.\n * @throws when compaction is active or the range is missing, reversed, or unbalanced.\n * @returns the appended event seqs, summary, replaced range, and token accounting.\n */',
       },
     ],
   },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6fb20b9718..1c27b19685 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1507,6 +1507,9 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../../interaction/commands
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-host-apiproxy':
         specifier: workspace:^
         version: link:../../host/apiproxy

From 1566a00eeba61e5f17f65a266eec4944e1ae335c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:42:39 +0800
Subject: [PATCH 250/262] test compact checkpoint snapshot identity

---
 .../acp-agent/tests/snapshots/workspace-context/session.jsonl   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
index 179e61ade9..40592a9f99 100644
--- a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
@@ -16,7 +16,7 @@
 {"type":"assistant/chunk","seq":14,"time":1785730689194,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":15,"time":1785730689194,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"9e9648c4-949e-4cf1-b9ef-0eb65897d36b"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
 {"type":"tool/call","seq":16,"time":1785730689195,"data":{"turn":1,"step":1,"callId":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}}
-{"type":"user/message","seq":17,"time":1785982371865,"data":{"content":[{"type":"text","text":"Earlier context was compacted for this snapshot."}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"162c764f-f01d-484d-ad81-1481dc29792a"},"sourceEventSeqs":[5],"surfaceOp":{"op":"replace","start":5,"end":5}}
+{"type":"user/message","seq":17,"time":1785982371865,"data":{"content":[{"type":"text","text":"Earlier context was compacted for this snapshot."}],"source":{"kind":"plugin","plugin":"compact","compactionId":"workspace-context-fixture"},"role":"user","id":"162c764f-f01d-484d-ad81-1481dc29792a"},"sourceEventSeqs":[5],"surfaceOp":{"op":"replace","start":5,"end":5}}
 {"type":"tool/result","seq":18,"time":1785982371865,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_workspace_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_read","content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: snapshot task\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"a46fded2-333a-4fb2-b01e-28520bffbc21"},"meta":{"path":"{{cwd}}/nested/task.txt","offset":1,"lines":[{"number":1,"text":"snapshot task"}],"totalLines":1}},"sourceEventSeqs":[16],"surfaceOp":"append"}
 {"type":"step/end","seq":19,"time":1785982371865,"data":{"turn":1,"step":1}}
 {"type":"agent/inbox/spliced","seq":20,"time":1785730689207,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nRoot snapshot instruction.\n\n</system-reminder>"},{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".dsh-project\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2e18766c26603608f321508caae00ea8f4434d59"},{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]},"role":"user","id":"09640903-80ea-4eb6-8635-90ddfb4e24e4"}]}}

From 6f27e6c2cea0ceeb86ef8887e3e2518e898567f7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:44:10 +0800
Subject: [PATCH 251/262] test(windows): compare canonical HMR identities

---
 .../2026-08-08-native-windows-pull-request-ci.i18n.yaml    | 4 ++--
 .../process/2026-08-08-native-windows-pull-request-ci.md   | 2 +-
 .../2026-08-08-native-windows-pull-request-ci.zh.md        | 2 +-
 packages/boot/app-boot/tests/hmr-config.spec.ts            | 7 ++++---
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index cff610e481..cb77330b29 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 258bca96db04c44ca2a3509c297028e31ef5375e
-2026-08-08-native-windows-pull-request-ci.zh.md: dd0031630eea9bb09a4a4db0125933ba0c7bac2f
+2026-08-08-native-windows-pull-request-ci.md: b8de631f96f7ff27c122971448f115d198b24a60
+2026-08-08-native-windows-pull-request-ci.zh.md: 433904ef513d3f92a6350eeb99f071711b49daf6
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 258bca96db..b8de631f96 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -16,7 +16,7 @@ Every pull request also starts an independent `windows-native` job named `window
 
 The native gate keeps workspace build and production-site failures blocking inside its own job while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
-The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path. Module HMR attaches listeners and awaits the main watcher's ready event before plugin startup settles, so an immediate post-boot edit cannot race the initial scan.
+The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path. Module HMR attaches listeners and awaits the main watcher's ready event before plugin startup settles, so an immediate post-boot edit cannot race the initial scan. HMR acceptance derives expected identities through the same asynchronous native realpath operation, avoiding a synchronous Windows spelling that can retain the 8.3 alias.
 
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index dd0031630e..433904ef51 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 原生门禁在其自身作业内继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
-首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。模块 HMR 会挂接监听器并等待主 watcher 的 ready 事件，之后插件启动才会完成，因此启动后立即发生的编辑无法与初始扫描形成竞态。
+首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。模块 HMR 会挂接监听器并等待主 watcher 的 ready 事件，之后插件启动才会完成，因此启动后立即发生的编辑无法与初始扫描形成竞态。HMR 验收通过相同的异步原生 realpath 操作派生预期身份，避免同步 Windows 路径写法仍保留 8.3 别名。
 
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index d21e222104..82cbd71c28 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -1,4 +1,5 @@
-import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -40,7 +41,7 @@ describe('HMR exact config paths', () => {
     // This acceptance owns alias-to-cache identity. Other cases below exercise
     // native events; polling keeps Windows fs.watch queue pressure out of it.
     const ctx = await bootHmr(alias, ['.'], true)
-    const filename = join(realpathSync(target), 'module.ts')
+    const filename = join(await realpath(target), 'module.ts')
     const expected = pathToFileURL(filename).href
     const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)
     const observed: string[] = []
@@ -73,7 +74,7 @@ describe('HMR exact config paths', () => {
     const ctx = await bootHmr(alias)
     try {
       await ctx.hmr.registerConfig('plugins.yml', () => {})
-      await expect(ctx.hmr.registerConfig(join(realpathSync(target), 'plugins.yml'), () => {}))
+      await expect(ctx.hmr.registerConfig(join(await realpath(target), 'plugins.yml'), () => {}))
         .rejects.toThrow('config path already registered')
     } finally {
       await ctx.fiber.dispose()

From f4c817648d0685dd2bec9f3c1b474597e8473687 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:53:06 +0800
Subject: [PATCH 252/262] docs fix compact checkpoint type example

---
 ...2026-07-30-web-transcript-log-ordered-projection.i18n.yaml | 4 ++--
 .../2026-07-30-web-transcript-log-ordered-projection.md       | 4 ++--
 .../2026-07-30-web-transcript-log-ordered-projection.zh.md    | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 1ea341085d..00fec6c8db 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: feefc951118c8511237c931a13070e1f7db1fd16
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 711e57b29742171d1861f25e63019b64356b4cad
+2026-07-30-web-transcript-log-ordered-projection.md: f2b7c3830b585db619f69046917e07a0b6ff6832
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 77787f9613b64a35e79a8667c6598de5a20ff400
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index feefc95111..f2b7c3830b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -33,8 +33,8 @@ What is unreachable from a `packages/client/*` program is `dsh-compact`'s **root
 The repo's answer to exactly this is a cordis-free leaf subpath, and this change adds one: `COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource` now live in `packages/compact/compact/src/checkpoint.ts`, which imports no cordis and augments no module (the `dsh-commands/brand` / `dsh-llm/message` shape), and the root re-exports both so every host-side consumer — the terminal's chat helpers, `dsh-session-reference`'s projection — is unchanged. The adapter pins its literal to that declaration with a type-only import:
 
 ```ts
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+import type { CompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
+const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 ```
 
 Renaming the Service Definition's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 711e57b297..77787f9613 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -33,8 +33,8 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 本仓库对这一情形的既有答案是不含 cordis 的叶子子路径，本次变更就新增了一个：`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource` 现在住在 `packages/compact/compact/src/checkpoint.ts`，它不导入 cordis、也不增强任何模块（即 `dsh-commands/brand` / `dsh-llm/message` 的形状），而包根重新导出两者，因此每个宿主侧消费方——终端的 chat helper、`dsh-session-reference` 的投影——都不需改动。适配器用仅类型导入把它的字面量钉在该声明上：
 
 ```ts
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+import type { CompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
+const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 ```
 
 重命名 Service Definition 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。

From 25dcd7293cca9cef7d2275b048462285d5090068 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:09:19 +0800
Subject: [PATCH 253/262] docs: purge chain-of-thought leakage from prose

Delete design-session citations (decision/audit/plan ordinals, stack
positions), change narration, review choreography, and reviewer-addressed
justification from comments, JSDoc, docs, READMEs, Agent Notes, tests, and
generator templates; restate every affected fact as current-state contract
prose. Fix generated docs at their sources and regenerate the catalogs and
cordis-surface regions; re-paste type-equiv blocks; update every bilingual
counterpart and re-record the pairs. Record the citation rule in the
committed-artifact-citations Agent Note.
---
 ...026-06-11-event-sourced-sessions.i18n.yaml |   4 +-
 .../2026-06-11-event-sourced-sessions.md      |   2 +-
 .../2026-06-11-event-sourced-sessions.zh.md   |   2 +-
 ...026-06-11-runtime-arg-validation.i18n.yaml |   4 +-
 .../2026-06-11-runtime-arg-validation.md      |   2 +-
 .../2026-06-11-runtime-arg-validation.zh.md   |   2 +-
 .../2026-06-14-session-persistence.i18n.yaml  |   4 +-
 .../2026-06-14-session-persistence.md         |   4 +-
 .../2026-06-14-session-persistence.zh.md      |   4 +-
 ...06-17-filesystem-capability-seam.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-capability-seam.md  |  12 +-
 ...026-06-17-filesystem-capability-seam.zh.md |  12 +-
 .../2026-06-18-session-surface.i18n.yaml      |   4 +-
 .../2026-06-18-session-surface.md             |   2 +-
 .../2026-06-18-session-surface.zh.md          |   2 +-
 ...ed-persistence-write-coordinator.i18n.yaml |   4 +-
 ...18-shared-persistence-write-coordinator.md |   2 +-
 ...shared-persistence-write-coordinator.zh.md |   2 +-
 .../2026-06-20-branded-ids.i18n.yaml          |   4 +-
 .../architecture/2026-06-20-branded-ids.md    |  14 +-
 .../architecture/2026-06-20-branded-ids.zh.md |  14 +-
 ...andatory-app-attribution-headers.i18n.yaml |   4 +-
 ...06-21-mandatory-app-attribution-headers.md |  10 +-
 ...21-mandatory-app-attribution-headers.zh.md |  10 +-
 .../2026-06-24-web-capability-seam.i18n.yaml  |   4 +-
 .../2026-06-24-web-capability-seam.md         |   4 +-
 .../2026-06-24-web-capability-seam.zh.md      |   4 +-
 ...06-26-file-context-as-event-gate.i18n.yaml |   4 +-
 .../2026-06-26-file-context-as-event-gate.md  |   2 +-
 ...026-06-26-file-context-as-event-gate.zh.md |   2 +-
 ...stdin-env-trusted-plugin-surface.i18n.yaml |   4 +-
 ...0-bash-stdin-env-trusted-plugin-surface.md |   2 +-
 ...ash-stdin-env-trusted-plugin-surface.zh.md |   2 +-
 ...026-06-30-event-domain-semantics.i18n.yaml |   4 +-
 .../2026-06-30-event-domain-semantics.md      |   4 +-
 .../2026-06-30-event-domain-semantics.zh.md   |   4 +-
 ...bles-and-tool-guidance-ownership.i18n.yaml |   4 +-
 ...t-variables-and-tool-guidance-ownership.md |   4 +-
 ...ariables-and-tool-guidance-ownership.zh.md |   4 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |   4 +-
 .../2026-07-05-reconstructable-requests.md    |   2 +-
 .../2026-07-05-reconstructable-requests.zh.md |   2 +-
 ...6-07-06-timeout-deadline-library.i18n.yaml |   4 +-
 .../2026-07-06-timeout-deadline-library.md    |   4 +-
 .../2026-07-06-timeout-deadline-library.zh.md |   4 +-
 ...6-07-07-tool-call-timeout-policy.i18n.yaml |   4 +-
 .../2026-07-07-tool-call-timeout-policy.md    |   3 +-
 .../2026-07-07-tool-call-timeout-policy.zh.md |   3 +-
 ...cutable-sdk-runtime-distribution.i18n.yaml |   4 +-
 ...ile-executable-sdk-runtime-distribution.md |   2 +-
 ...-executable-sdk-runtime-distribution.zh.md |   2 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   4 +-
 .../2026-07-15-lsp-capability-seam.md         |   4 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |   4 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |   4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |  12 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  12 +-
 ...7-19-gui-web-client-architecture.i18n.yaml |   4 +-
 .../2026-07-19-gui-web-client-architecture.md |  12 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  12 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |   4 +-
 .../2026-07-23-client-plugin-loading-model.md |   6 +-
 ...26-07-23-client-plugin-loading-model.zh.md |   6 +-
 ...-24-single-harness-home-resolver.i18n.yaml |   4 +-
 ...2026-07-24-single-harness-home-resolver.md |   2 +-
 ...6-07-24-single-harness-home-resolver.zh.md |   2 +-
 ...ession-scope-and-provide-channel.i18n.yaml |   4 +-
 ...lient-session-scope-and-provide-channel.md |   2 +-
 ...nt-session-scope-and-provide-channel.zh.md |   2 +-
 ...eb-command-surfaces-and-assembly.i18n.yaml |   4 +-
 ...07-25-web-command-surfaces-and-assembly.md |   6 +-
 ...25-web-command-surfaces-and-assembly.zh.md |   6 +-
 ...input-machine-and-slash-pipeline.i18n.yaml |   4 +-
 ...25-web-input-machine-and-slash-pipeline.md |   6 +-
 ...web-input-machine-and-slash-pipeline.zh.md |   6 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |   4 +-
 .../2026-07-26-subprocess-seam.md             |   2 +-
 .../2026-07-26-subprocess-seam.zh.md          |   2 +-
 ...07-27-dispose-ladder-to-consumer.i18n.yaml |   4 +-
 .../2026-07-27-dispose-ladder-to-consumer.md  |   2 +-
 ...026-07-27-dispose-ladder-to-consumer.zh.md |   2 +-
 ...07-28-api-browser-trust-boundary.i18n.yaml |   4 +-
 .../2026-07-28-api-browser-trust-boundary.md  |   4 +-
 ...026-07-28-api-browser-trust-boundary.zh.md |   4 +-
 ...directory-picker-capability-seam.i18n.yaml |   4 +-
 ...-07-28-directory-picker-capability-seam.md |   2 +-
 ...-28-directory-picker-capability-seam.zh.md |   2 +-
 .../2026-07-28-user-settings-seam.i18n.yaml   |   4 +-
 .../2026-07-28-user-settings-seam.md          |   4 +-
 .../2026-07-28-user-settings-seam.zh.md       |   4 +-
 ...-07-29-dsh-source-launch-tsx-esm.i18n.yaml |   4 +-
 .../2026-07-29-dsh-source-launch-tsx-esm.md   |   2 +-
 ...2026-07-29-dsh-source-launch-tsx-esm.zh.md |   2 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |   4 +-
 .../2026-07-29-package-regrouping.md          |  24 +-
 .../2026-07-29-package-regrouping.zh.md       |  24 +-
 ...-token-usage-and-request-context.i18n.yaml |   4 +-
 ...ojected-token-usage-and-request-context.md |   4 +-
 ...cted-token-usage-and-request-context.zh.md |   4 +-
 ...est-level-llm-config-credentials.i18n.yaml |   4 +-
 ...29-request-level-llm-config-credentials.md |   4 +-
 ...request-level-llm-config-credentials.zh.md |   4 +-
 ...26-07-30-config-plane-boundaries.i18n.yaml |   4 +-
 .../2026-07-30-config-plane-boundaries.md     |   4 +-
 .../2026-07-30-config-plane-boundaries.zh.md  |   4 +-
 ...undaries-and-atomic-registration.i18n.yaml |   4 +-
 ...tial-boundaries-and-atomic-registration.md |   8 +-
 ...l-boundaries-and-atomic-registration.zh.md |  10 +-
 ...30-session-end-seed-log-boundary.i18n.yaml |   4 +-
 ...026-07-30-session-end-seed-log-boundary.md |   2 +-
 ...-07-30-session-end-seed-log-boundary.zh.md |   2 +-
 ...30-settings-write-path-integrity.i18n.yaml |   4 +-
 ...026-07-30-settings-write-path-integrity.md |   6 +-
 ...-07-30-settings-write-path-integrity.zh.md |   6 +-
 .../2026-07-30-web-config-plane.i18n.yaml     |   4 +-
 .../2026-07-30-web-config-plane.md            |  10 +-
 .../2026-07-30-web-config-plane.zh.md         |  10 +-
 ...runtime-portable-identifier-seam.i18n.yaml |   4 +-
 ...1-code-runtime-portable-identifier-seam.md |   8 +-
 ...ode-runtime-portable-identifier-seam.zh.md |   8 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |   4 +-
 .../2026-08-02-typert-remote-method-calls.md  |   2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |   2 +-
 ...-pi-ai-declared-provider-catalog.i18n.yaml |   4 +-
 ...6-08-03-pi-ai-declared-provider-catalog.md |   2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |   2 +-
 ...4-configuration-source-ownership.i18n.yaml |   4 +-
 ...26-08-04-configuration-source-ownership.md |   2 +-
 ...08-04-configuration-source-ownership.zh.md |   2 +-
 ...-a-provider-from-the-models-page.i18n.yaml |   4 +-
 ...claring-a-provider-from-the-models-page.md |   2 +-
 ...ring-a-provider-from-the-models-page.zh.md |   2 +-
 ...ubagent-list-identity-projection.i18n.yaml |   4 +-
 ...08-06-subagent-list-identity-projection.md |  14 +-
 ...06-subagent-list-identity-projection.zh.md |  14 +-
 ...d-scrollbars-and-reserved-gutter.i18n.yaml |   4 +-
 ...8-themed-scrollbars-and-reserved-gutter.md |   4 +-
 ...hemed-scrollbars-and-reserved-gutter.zh.md |   4 +-
 ...07-30-approval-panel-command-cap.i18n.yaml |   4 +-
 .../2026-07-30-approval-panel-command-cap.md  |   2 +-
 ...026-07-30-approval-panel-command-cap.zh.md |   2 +-
 ...ranscript-log-ordered-projection.i18n.yaml |   4 +-
 ...0-web-transcript-log-ordered-projection.md |   2 +-
 ...eb-transcript-log-ordered-projection.zh.md |   2 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |   4 +-
 ...6-07-31-fail-loud-releases-the-terminal.md |   2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |   2 +-
 ...-08-06-api-key-format-validation.i18n.yaml |   4 +-
 .../2026-08-06-api-key-format-validation.md   |   2 +-
 ...2026-08-06-api-key-format-validation.zh.md |   2 +-
 ...07-cancel-convergence-wake-latch.i18n.yaml |   4 +-
 ...026-08-07-cancel-convergence-wake-latch.md |   6 +-
 ...-08-07-cancel-convergence-wake-latch.zh.md |   6 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |   4 +-
 .../feature/2026-06-15-code-mode.zh.md        |   4 +-
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-tool-schemas.md     |  12 +-
 .../2026-06-17-filesystem-tool-schemas.zh.md  |  12 +-
 ...06-18-compaction-capability-seam.i18n.yaml |   4 +-
 .../2026-06-18-compaction-capability-seam.md  |   2 +-
 ...026-06-18-compaction-capability-seam.zh.md |   2 +-
 ...6-06-21-subagent-capability-seam.i18n.yaml |   4 +-
 .../2026-06-21-subagent-capability-seam.md    |   4 +-
 .../2026-06-21-subagent-capability-seam.zh.md |   4 +-
 .../2026-06-29-todo-write-tool.i18n.yaml      |   4 +-
 .../feature/2026-06-29-todo-write-tool.md     |   2 +-
 .../feature/2026-06-29-todo-write-tool.zh.md  |   2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |   4 +-
 .../feature/2026-06-30-hook-protocol-lib.md   |   2 +-
 .../2026-06-30-hook-protocol-lib.zh.md        |   2 +-
 ...026-06-30-session-store-fork-api.i18n.yaml |   4 +-
 .../2026-06-30-session-store-fork-api.md      |   2 +-
 .../2026-06-30-session-store-fork-api.zh.md   |   2 +-
 ...26-07-14-cross-family-fs-sandbox.i18n.yaml |   4 +-
 .../2026-07-14-cross-family-fs-sandbox.md     |   2 +-
 .../2026-07-14-cross-family-fs-sandbox.zh.md  |   2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |   4 +-
 .../feature/2026-07-16-harness-level-loop.md  |   2 +-
 .../2026-07-16-harness-level-loop.zh.md       |   2 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |   4 +-
 .../2026-07-16-persistent-pty-sessions.md     |   1 -
 .../2026-07-16-persistent-pty-sessions.zh.md  |   1 -
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |   4 +-
 .../2026-07-20-dsh-cli-personal-config.md     |   2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |   2 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |   4 +-
 ...26-07-23-session-telemetry-otel-revival.md |   2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |   2 +-
 ...n-list-browsing-and-manual-order.i18n.yaml |   4 +-
 ...-session-list-browsing-and-manual-order.md |   2 +-
 ...ssion-list-browsing-and-manual-order.zh.md |   2 +-
 ...26-07-26-code-dispatch-log-spill.i18n.yaml |   4 +-
 .../2026-07-26-code-dispatch-log-spill.md     |   2 +-
 .../2026-07-26-code-dispatch-log-spill.zh.md  |   4 +-
 ...7-26-code-dispatch-ui-foundation.i18n.yaml |   4 +-
 .../2026-07-26-code-dispatch-ui-foundation.md |   8 +-
 ...26-07-26-code-dispatch-ui-foundation.zh.md |   8 +-
 ...7-26-code-mode-chat-subcall-rows.i18n.yaml |   4 +-
 .../2026-07-26-code-mode-chat-subcall-rows.md |   2 +-
 ...26-07-26-code-mode-chat-subcall-rows.zh.md |   2 +-
 ...code-mode-live-parallel-dispatch.i18n.yaml |   4 +-
 ...-07-26-code-mode-live-parallel-dispatch.md |   6 +-
 ...-26-code-mode-live-parallel-dispatch.zh.md |   6 +-
 ...-07-26-todo-parallel-in-progress.i18n.yaml |   4 +-
 .../2026-07-26-todo-parallel-in-progress.md   |   8 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |   8 +-
 ...ntinuable-subagent-conversations.i18n.yaml |   4 +-
 ...7-28-continuable-subagent-conversations.md |   4 +-
 ...8-continuable-subagent-conversations.zh.md |   4 +-
 ...28-todo-plan-clears-on-next-turn.i18n.yaml |   4 +-
 ...026-07-28-todo-plan-clears-on-next-turn.md |   2 +-
 ...-07-28-todo-plan-clears-on-next-turn.zh.md |   2 +-
 .../2026-07-28-web-terminal-card.i18n.yaml    |   4 +-
 .../feature/2026-07-28-web-terminal-card.md   |   6 +-
 .../2026-07-28-web-terminal-card.zh.md        |   6 +-
 ...29-ask-question-web-presentation.i18n.yaml |   4 +-
 ...026-07-29-ask-question-web-presentation.md |   4 +-
 ...-07-29-ask-question-web-presentation.zh.md |   4 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |   4 +-
 .../2026-07-30-queued-manual-compaction.md    |   2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |   2 +-
 .../2026-07-30-search-render-card.i18n.yaml   |   4 +-
 .../feature/2026-07-30-search-render-card.md  |   6 +-
 .../2026-07-30-search-render-card.zh.md       |   6 +-
 .../2026-07-30-web-diff-card.i18n.yaml        |   4 +-
 .../feature/2026-07-30-web-diff-card.md       |   2 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |   2 +-
 ...026-07-30-web-read-card-frontend.i18n.yaml |   4 +-
 .../2026-07-30-web-read-card-frontend.md      |   4 +-
 .../2026-07-30-web-read-card-frontend.zh.md   |   4 +-
 .../2026-07-30-web-read-card.i18n.yaml        |   4 +-
 .../feature/2026-07-30-web-read-card.md       |   4 +-
 .../feature/2026-07-30-web-read-card.zh.md    |   4 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |   4 +-
 .../2026-07-30-web-result-card-frontend.md    |   6 +-
 .../2026-07-30-web-result-card-frontend.zh.md |   6 +-
 .../2026-07-30-web-result-card.i18n.yaml      |   4 +-
 .../feature/2026-07-30-web-result-card.md     |   4 +-
 .../feature/2026-07-30-web-result-card.zh.md  |   4 +-
 .../2026-07-30-web-search-card.i18n.yaml      |   4 +-
 .../feature/2026-07-30-web-search-card.md     |   4 +-
 .../feature/2026-07-30-web-search-card.zh.md  |   4 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |   4 +-
 .../2026-07-31-code-mode-language-dispatch.md |   6 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |   8 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |   4 +-
 .../2026-07-31-telemetry-anonymous-user-id.md |   2 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |   2 +-
 ...6-07-31-web-workspace-file-links.i18n.yaml |   4 +-
 .../2026-07-31-web-workspace-file-links.md    |   2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |   2 +-
 ...2026-08-02-pwsh-tool-bash-parity.i18n.yaml |   4 +-
 .../2026-08-02-pwsh-tool-bash-parity.md       |   6 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md    |   6 +-
 ...2-win32-in-process-folder-dialog.i18n.yaml |   4 +-
 ...26-08-02-win32-in-process-folder-dialog.md |   2 +-
 ...08-02-win32-in-process-folder-dialog.zh.md |   2 +-
 ...6-08-03-web-search-source-scroll.i18n.yaml |   4 +-
 .../2026-08-03-web-search-source-scroll.md    |   2 +-
 .../2026-08-03-web-search-source-scroll.zh.md |   2 +-
 ...4-web-composer-shared-width-axis.i18n.yaml |   4 +-
 ...26-08-04-web-composer-shared-width-axis.md |   2 +-
 ...08-04-web-composer-shared-width-axis.zh.md |   2 +-
 ...26-08-05-context-form-vocabulary.i18n.yaml |   4 +-
 .../2026-08-05-context-form-vocabulary.md     |   2 +-
 .../2026-08-05-context-form-vocabulary.zh.md  |   2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |   4 +-
 .../feature/2026-08-05-pwsh-ui-bash-parity.md |   2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |   2 +-
 .../2026-06-17-ts-build-config.i18n.yaml      |   4 +-
 .../process/2026-06-17-ts-build-config.md     |   6 +-
 .../process/2026-06-17-ts-build-config.zh.md  |   6 +-
 ...6-06-18-markdown-cross-link-lint.i18n.yaml |   4 +-
 .../2026-06-18-markdown-cross-link-lint.md    |   2 +-
 .../2026-06-18-markdown-cross-link-lint.zh.md |   2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   4 +-
 ...6-06-20-core-data-structures-catalog.zh.md |   4 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |   4 +-
 ...6-07-02-bilingual-docs-and-pairing-gate.md |   2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |   2 +-
 ...n-setup-for-symmetric-ci-caching.i18n.yaml |   4 +-
 ...m-action-setup-for-symmetric-ci-caching.md |   2 +-
 ...ction-setup-for-symmetric-ci-caching.zh.md |   2 +-
 ...27-wine-windows-gates-experiment.i18n.yaml |   4 +-
 ...026-07-27-wine-windows-gates-experiment.md |   2 +-
 ...-07-27-wine-windows-gates-experiment.zh.md |   2 +-
 ...30-generated-third-party-notices.i18n.yaml |   4 +-
 ...026-07-30-generated-third-party-notices.md |   2 +-
 ...-07-30-generated-third-party-notices.zh.md |   2 +-
 ...staller-adopts-existing-checkout.i18n.yaml |   4 +-
 ...7-31-installer-adopts-existing-checkout.md |   4 +-
 ...1-installer-adopts-existing-checkout.zh.md |   4 +-
 ...-06-coverage-uncovered-locations.i18n.yaml |   4 +-
 ...2026-08-06-coverage-uncovered-locations.md |   2 +-
 ...6-08-06-coverage-uncovered-locations.zh.md |   2 +-
 ...-09-committed-artifact-citations.i18n.yaml |   6 +
 ...2026-08-09-committed-artifact-citations.md |  37 ++
 ...6-08-09-committed-artifact-citations.zh.md |  37 ++
 ...-19-drop-mutable-session-summary.i18n.yaml |   4 +-
 ...2026-06-19-drop-mutable-session-summary.md |   2 +-
 ...6-06-19-drop-mutable-session-summary.zh.md |   2 +-
 ...llapse-trace-only-session-events.i18n.yaml |   4 +-
 ...6-20-collapse-trace-only-session-events.md |   8 +-
 ...0-collapse-trace-only-session-events.zh.md |   8 +-
 ...-06-20-public-agent-stop-surface.i18n.yaml |   4 +-
 .../2026-06-20-public-agent-stop-surface.md   |   6 +-
 ...2026-06-20-public-agent-stop-surface.zh.md |   4 +-
 ...ove-agent-boundary-mirror-events.i18n.yaml |   4 +-
 ...-20-remove-agent-boundary-mirror-events.md |  13 +-
 ...-remove-agent-boundary-mirror-events.zh.md |  13 +-
 ...06-20-unify-agent-and-session-id.i18n.yaml |   4 +-
 .../2026-06-20-unify-agent-and-session-id.md  |   1 -
 ...026-06-20-unify-agent-and-session-id.zh.md |   1 -
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |   4 +-
 .../2026-06-26-fsspec-style-fs-seam.md        |   6 +-
 .../2026-06-26-fsspec-style-fs-seam.zh.md     |   6 +-
 ...6-07-04-drop-image-content-block.i18n.yaml |   4 +-
 .../2026-07-04-drop-image-content-block.md    |   2 +-
 .../2026-07-04-drop-image-content-block.zh.md |   2 +-
 ...4-tighten-hook-protocol-contract.i18n.yaml |   4 +-
 ...26-07-04-tighten-hook-protocol-contract.md |   2 +-
 ...07-04-tighten-hook-protocol-contract.zh.md |   2 +-
 .../2026-07-17-one-send-one-turn.i18n.yaml    |   4 +-
 .../2026-07-17-one-send-one-turn.md           |   2 +-
 .../2026-07-17-one-send-one-turn.zh.md        |   2 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |   4 +-
 ...2026-07-31-one-route-to-add-a-workspace.md |   8 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |   8 +-
 ...026-06-11-property-based-testing.i18n.yaml |   4 +-
 .../2026-06-11-property-based-testing.md      |   4 +-
 .../2026-06-11-property-based-testing.zh.md   |   4 +-
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |   4 +-
 .../testing/2026-06-19-acp-snapshot-tests.md  |   4 +-
 .../2026-06-19-acp-snapshot-tests.zh.md       |   4 +-
 .../2026-06-19-real-api-e2e-ci.i18n.yaml      |   4 +-
 .../testing/2026-06-19-real-api-e2e-ci.md     |   4 +-
 .../testing/2026-06-19-real-api-e2e-ci.zh.md  |   4 +-
 ...6-06-22-subagent-snapshot-replay.i18n.yaml |   4 +-
 .../2026-06-22-subagent-snapshot-replay.md    |   4 +-
 .../2026-06-22-subagent-snapshot-replay.zh.md |   4 +-
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |   4 +-
 .../2026-07-24-web-gui-browser-e2e-lane.md    |   2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |   2 +-
 .../2026-06-16-typed-event-schemas.i18n.yaml  |   4 +-
 .../2026-06-16-typed-event-schemas.md         |   2 -
 .../2026-06-16-typed-event-schemas.zh.md      |   2 -
 ...-domain-kv-storage-and-workspace.i18n.yaml |   4 +-
 ...6-07-24-domain-kv-storage-and-workspace.md |   4 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md |   4 +-
 ...ssion-projection-and-command-log.i18n.yaml |   4 +-
 ...7-27-session-projection-and-command-log.md |   6 +-
 ...7-session-projection-and-command-log.zh.md |   6 +-
 ...root-and-derived-medium-recovery.i18n.yaml |   4 +-
 ...torage-root-and-derived-medium-recovery.md |   6 +-
 ...age-root-and-derived-medium-recovery.zh.md |   6 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |   4 +-
 .../2026-07-06-recallable-compaction.md       |   2 +-
 .../2026-07-06-recallable-compaction.zh.md    |   2 +-
 .../2026-08-01-windows-pwsh-default.i18n.yaml |   4 +-
 .../2026-08-01-windows-pwsh-default.md        |   2 +-
 .../2026-08-01-windows-pwsh-default.zh.md     |   2 +-
 ...2026-06-11-api-extractor-reports.i18n.yaml |   4 +-
 .../2026-06-11-api-extractor-reports.md       |   2 +-
 .../2026-06-11-api-extractor-reports.zh.md    |   2 +-
 .agents/skills/dsh-doc-standards/SKILL.md     |   2 +-
 .../skills/dsh-merging-stacked-prs/SKILL.md   |   2 +-
 .agents/skills/dsh-translate-docs/SKILL.md    |   2 +-
 .agents/skills/record-browser-gif/SKILL.md    |   2 +-
 .github/issue-management/policy.mjs           |   2 +-
 .github/workflows/ci.yml                      |   7 +-
 apps/cli/tests/args.spec.ts                   |   6 +-
 apps/cli/tests/built-bin.e2e.ts               |  12 +-
 apps/web/tests/approval-composer.e2e.ts       |  13 +-
 apps/web/tests/chat-long-interactions.e2e.ts  |   7 +-
 apps/web/tests/code-mode-round.e2e.ts         |   4 +-
 apps/web/tests/composer-draft-scroll.e2e.ts   |  27 +-
 apps/web/tests/composer-tab-geometry.e2e.ts   |  54 +-
 .../tests/conversation-column-overflow.e2e.ts |  53 +-
 apps/web/tests/default-model.overlay.yml      |   2 +-
 apps/web/tests/lifecycle-chrome.e2e.ts        |  11 +-
 apps/web/tests/models-settings.e2e.ts         |   5 +-
 apps/web/tests/navigation-panes.e2e.ts        |   2 +-
 apps/web/tests/pin-browse-picker.overlay.yml  |   2 +-
 apps/web/tests/pwsh-terminal.e2e.ts           |   4 +-
 apps/web/tests/scaffold.ts                    |   2 +-
 apps/web/tests/seeded-history.e2e.ts          |   4 +-
 apps/web/tests/settings-chrome.e2e.ts         |   2 +-
 apps/web/tests/sidebar-scrollbar.e2e.ts       |  38 +-
 apps/web/tests/smoke-real.e2e.ts              |  30 +-
 apps/web/tests/startup-auto-selection.e2e.ts  |  13 +-
 apps/web/tests/subagent-interrupt-ui.e2e.ts   |   3 +-
 apps/web/tests/subagent-interrupt.e2e.ts      |   2 +-
 apps/web/tests/turn-tail-actions.e2e.ts       |   2 +-
 apps/web/tests/workspace-management.e2e.ts    |  16 +-
 apps/web/vite.config.ts                       |  12 +-
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |  10 +-
 docs/api-gateway.zh.md                        |  10 +-
 docs/capability-seams.md                      |   2 +-
 docs/config-catalog.md                        |  16 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |   4 +-
 docs/cookbook/extension-cookbook.md           |   4 +-
 docs/cookbook/extension-cookbook.zh.md        |   4 +-
 .../maintaining-dsh-code-review.i18n.yaml     |   4 +-
 docs/cookbook/maintaining-dsh-code-review.md  |   2 +-
 .../maintaining-dsh-code-review.zh.md         |   2 +-
 docs/cordis-api/inherited.md                  |   2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |   4 +-
 docs/cordis-tutorial/04-events.md             |   2 +-
 docs/cordis-tutorial/04-events.zh.md          |   2 +-
 .../06-composition-and-hmr.i18n.yaml          |   4 +-
 .../cordis-tutorial/06-composition-and-hmr.md |   2 +-
 .../06-composition-and-hmr.zh.md              |   2 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/i18n/translation-prompt.md               |   2 +-
 docs/persistence-catalog.md                   |   5 +-
 docs/subsystems/approval.i18n.yaml            |   4 +-
 docs/subsystems/approval.md                   |   5 +-
 docs/subsystems/approval.zh.md                |   5 +-
 docs/subsystems/bash.i18n.yaml                |   4 +-
 docs/subsystems/bash.md                       |   4 +-
 docs/subsystems/bash.zh.md                    |   4 +-
 docs/subsystems/client-modules.i18n.yaml      |   4 +-
 docs/subsystems/client-modules.md             |   2 +-
 docs/subsystems/client-modules.zh.md          |   2 +-
 docs/subsystems/code-runtime.i18n.yaml        |   4 +-
 docs/subsystems/code-runtime.md               |   2 +-
 docs/subsystems/code-runtime.zh.md            |   2 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |   2 +-
 docs/subsystems/compaction.zh.md              |   2 +-
 docs/subsystems/filesystem.i18n.yaml          |   4 +-
 docs/subsystems/filesystem.md                 |   2 +-
 docs/subsystems/filesystem.zh.md              |   2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              |   8 +-
 docs/subsystems/llm-streaming.zh.md           |   8 +-
 docs/subsystems/lsp.i18n.yaml                 |   4 +-
 docs/subsystems/lsp.md                        |   2 +-
 docs/subsystems/lsp.zh.md                     |   2 +-
 docs/subsystems/persistence.i18n.yaml         |   4 +-
 docs/subsystems/persistence.md                |   4 +-
 docs/subsystems/persistence.zh.md             |   4 +-
 docs/subsystems/session-projection.i18n.yaml  |   4 +-
 docs/subsystems/session-projection.md         |   2 +-
 docs/subsystems/session-projection.zh.md      |   2 +-
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   5 +-
 docs/subsystems/session.zh.md                 |   5 +-
 docs/subsystems/skills.i18n.yaml              |   4 +-
 docs/subsystems/skills.md                     |   2 +-
 docs/subsystems/skills.zh.md                  |   2 +-
 docs/subsystems/storage.i18n.yaml             |   4 +-
 docs/subsystems/storage.md                    |   4 +-
 docs/subsystems/storage.zh.md                 |   4 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   4 +-
 docs/subsystems/subagent.zh.md                |   4 +-
 docs/subsystems/subprocess.i18n.yaml          |   4 +-
 docs/subsystems/subprocess.md                 |   4 +-
 docs/subsystems/subprocess.zh.md              |   4 +-
 docs/subsystems/telemetry.i18n.yaml           |   4 +-
 docs/subsystems/telemetry.md                  |   2 +-
 docs/subsystems/telemetry.zh.md               |   2 +-
 docs/subsystems/web.i18n.yaml                 |   4 +-
 docs/subsystems/web.md                        |  13 +-
 docs/subsystems/web.zh.md                     |  13 +-
 docs/testing.i18n.yaml                        |   4 +-
 docs/testing.md                               |   2 +-
 docs/testing.zh.md                            |   2 +-
 docs/tool-catalog.md                          |   4 +-
 docs/user/guide/config.i18n.yaml              |   4 +-
 docs/user/guide/config.md                     |   2 +-
 docs/user/guide/config.zh.md                  |   2 +-
 docs/user/guide/providers.i18n.yaml           |   4 +-
 docs/user/guide/providers.md                  |   2 +-
 docs/user/guide/providers.zh.md               |   2 +-
 examples/acp-agent/tests/acp.e2e.ts           |   2 +-
 examples/acp-agent/tests/escalation.e2e.ts    |   2 +-
 .../headless-agent/tests/headless.snapshot.ts |  10 +-
 native/landlock-run/README.i18n.yaml          |   4 +-
 native/landlock-run/README.md                 |   2 +-
 native/landlock-run/README.zh.md              |   2 +-
 native/landlock-run/packages/entry/src/main.c |   9 +-
 packages/bash/bash-sandbox/src/index.ts       |   2 +-
 packages/bash/bash/README.i18n.yaml           |   4 +-
 packages/bash/bash/README.md                  |   2 +-
 packages/bash/bash/README.zh.md               |   2 +-
 packages/bash/pwsh-local/README.i18n.yaml     |   4 +-
 packages/bash/pwsh-local/README.md            |   2 +-
 packages/bash/pwsh-local/README.zh.md         |   2 +-
 packages/bash/tool-bash/src/index.ts          |   6 +-
 packages/bash/tool-pwsh/README.i18n.yaml      |   4 +-
 packages/bash/tool-pwsh/README.md             |   2 +-
 packages/bash/tool-pwsh/README.zh.md          |   2 +-
 packages/bundle/web-app/src/index.ts          |   2 +-
 packages/client/AGENTS.md                     |   4 +-
 packages/client/connection/README.i18n.yaml   |   4 +-
 packages/client/connection/README.md          |   2 +-
 packages/client/connection/README.zh.md       |   2 +-
 packages/client/connection/src/client/api.ts  |   8 +-
 .../connection/src/client/connection.ts       |  12 +-
 .../client/connection/src/client/fixture.ts   |  12 +-
 packages/client/hmr/src/client/index.ts       |   7 +-
 packages/client/modules/src/client/index.ts   |   4 +-
 .../client/modules/src/client/manifest.ts     |  12 +-
 packages/client/modules/src/client/system.ts  |   2 +-
 packages/client/modules/src/index.ts          |   4 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   4 +-
 packages/client/runtime/README.zh.md          |   4 +-
 .../runtime/src/client/contract/store.ts      |   6 +-
 packages/client/runtime/src/client/index.ts   |   3 +-
 .../runtime/src/client/sessions/manager.ts    |  14 +-
 .../src/client/sessions/projection-store.ts   |  11 +-
 .../runtime/src/client/sessions/service.ts    |   7 +-
 .../runtime/src/client/sessions/session.ts    |  25 +-
 .../src/client/sessions/transcript-adapter.ts | 408 +++++++++++++
 .../client/runtime/tests/client-apply.spec.ts |   2 +-
 packages/client/runtime/tests/event-script.ts |   2 +-
 .../runtime/tests/projection-store.spec.ts    |   3 +-
 packages/client/runtime/tests/session.spec.ts |   2 +-
 .../runtime/tests/transcript-adapter.spec.ts  | 567 ++++++++++++++++++
 .../ui-command/src/client/PopupSelectView.tsx |   4 +-
 .../client/ui-command/src/client/popup.ts     |   2 +-
 .../ui-command/tests/popup-view.spec.tsx      |   2 +-
 .../client/ui-command/tests/popup.spec.ts     |   2 +-
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../ui-conversation/src/client/apply.ts       |   8 +-
 .../src/client/chat/ChatView.tsx              |   2 +-
 .../src/client/chat/MessageItem.tsx           |   4 +-
 .../src/client/contract/slots.ts              |  19 +-
 .../src/client/input/contract.ts              |  10 +-
 .../src/client/input/decorations.ts           |  12 +-
 .../src/client/input/facade.ts                |  11 +-
 .../ui-conversation/src/client/input/hub.ts   |   6 +-
 .../src/client/input/machine.ts               |  14 +-
 .../ui-conversation/src/client/queue/store.ts |   2 +-
 .../ui-conversation/src/client/service.ts     |   2 +-
 .../src/client/skeleton/ApprovalPanel.tsx     |   3 +-
 .../src/client/skeleton/ContextMeter.tsx      |   4 +-
 .../src/client/skeleton/ConversationRoot.tsx  |   1 -
 .../src/client/skeleton/DetailsPanel.tsx      |   5 +-
 .../src/client/skeleton/InputBar.module.css   |   2 +-
 .../src/client/skeleton/InputBar.tsx          |   9 +-
 .../ui-conversation/tests/input-bar.spec.tsx  |  14 +-
 .../tests/input-machine.spec.ts               |   6 +-
 .../tests/input-matrix.spec.tsx               |   2 +-
 .../tests/input-scenarios.spec.tsx            |   2 +-
 .../ui-conversation/tests/todo-panel.spec.tsx |   4 +-
 .../client/ui-layout/src/client/AppFrame.tsx  |   4 +-
 .../client/ui-layout/tests/app-frame.spec.tsx |   2 +-
 packages/client/ui-models/README.i18n.yaml    |   4 +-
 packages/client/ui-models/README.md           |   2 +-
 packages/client/ui-models/README.zh.md        |   4 +-
 .../src/client/CustomProviderCard.tsx         |   2 +-
 .../src/client/ModelsSection.module.css       |   8 +-
 .../ui-models/tests/components.spec.tsx       |   4 +-
 .../ui-models/tests/provider-form.spec.tsx    |  12 +-
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   4 +-
 packages/client/ui-primitives/README.zh.md    |   4 +-
 .../ui-primitives/src/TerminalBlock.tsx       |   4 +-
 .../ui-primitives/src/Tooltip.module.css      |   4 +-
 .../ui-primitives/src/markdown/highlight.ts   |   3 +-
 .../client/ui-primitives/tests/ansi.spec.ts   |   8 +-
 .../ui-primitives/tests/hover-card.spec.tsx   |   4 +-
 .../client/ui-primitives/tests/icons.spec.tsx |   2 +-
 .../client/ui-primitives/tsdown.config.ts     |   2 +-
 .../ui-settings/src/client/contract/slots.ts  |   4 +-
 .../src/client/SidebarRoot.module.css         |   2 +-
 packages/client/ui-skill/README.i18n.yaml     |   4 +-
 packages/client/ui-skill/README.md            |   2 +-
 packages/client/ui-skill/README.zh.md         |   2 +-
 packages/client/ui-skill/src/client/index.ts  |  14 +-
 .../ui-skill/tests/browser-plugin.spec.ts     |   6 +-
 packages/client/ui-slash/README.i18n.yaml     |   4 +-
 packages/client/ui-slash/README.md            |   2 +-
 packages/client/ui-slash/README.zh.md         |   2 +-
 .../client/ui-slash/src/client/controller.ts  |   5 +-
 packages/client/ui-slash/src/client/slots.ts  |   2 +-
 packages/client/ui-slash/src/core/contract.ts |   8 +-
 packages/client/ui-slash/src/core/detect.ts   |   2 +-
 packages/client/ui-slash/src/core/menu.ts     |   2 +-
 packages/client/ui-slash/src/types.ts         |  12 +-
 .../client/ui-slash/tests/core-detect.spec.ts |   4 +-
 .../client/ui-slash/tests/core-menu.spec.ts   |   3 +-
 .../client/ui-slash/tests/menu-view.spec.tsx  |   2 +-
 .../client/ui-slash/tests/service.spec.ts     |   2 +-
 packages/client/ui-slots/src/index.ts         |   2 +-
 packages/client/ui-slots/src/renderer.ts      |   5 +-
 .../client/ui-subagent/src/client/index.ts    |  12 +-
 .../ui-subagent/tests/browser-plugin.spec.ts  |   6 +-
 packages/client/ui-theme/README.i18n.yaml     |   4 +-
 packages/client/ui-theme/README.md            |   4 +-
 packages/client/ui-theme/README.zh.md         |   4 +-
 packages/client/ui-tool/README.i18n.yaml      |   4 +-
 packages/client/ui-tool/README.md             |   6 +-
 packages/client/ui-tool/README.zh.md          |   6 +-
 .../src/client/tool/toolviews/search-row.tsx  |   4 +-
 .../client/ui-tool/tests/tool-row.spec.tsx    |   4 +-
 .../client/ui-trajectory/README.i18n.yaml     |   4 +-
 packages/client/ui-trajectory/README.md       |   2 +-
 packages/client/ui-trajectory/README.zh.md    |   2 +-
 .../client/ui-trajectory/src/client/layout.ts |   4 +-
 .../src/client/WorkspaceBrowser.tsx           |   4 +-
 .../ui-workspace/src/client/rows/Rows.tsx     |   6 +-
 .../tests/rename-assembly.spec.tsx            |   5 +-
 packages/client/web-react/README.i18n.yaml    |   4 +-
 packages/client/web-react/README.md           |   2 +-
 packages/client/web-react/README.zh.md        |   2 +-
 .../client/web-react/src/scoped-slots.tsx     |   4 +-
 .../client/web-react/src/session-provider.tsx |   2 +-
 .../web-react/tests/scoped-slots.spec.tsx     |   4 +-
 .../web-react/tests/session-provider.spec.tsx |   4 +-
 .../web-react/tests/use-projection.spec.tsx   |   3 +-
 packages/client/web/src/AppRoot.tsx           |   2 +-
 packages/client/web/src/boot.tsx              |  10 +-
 packages/client/web/src/index.ts              |   2 +-
 packages/client/web/src/loader-status.ts      |   4 +-
 packages/client/web/src/seed.ts               |   2 +-
 .../code-runtime/code-runtime/src/index.ts    |  14 +-
 packages/context/README.i18n.yaml             |   4 +-
 packages/context/README.md                    |   2 -
 packages/context/README.zh.md                 |   4 +-
 .../tests/workspace-context.spec.ts           |   2 +-
 packages/core/session/src/chunk-rows.ts       |   3 +-
 packages/core/session/src/types.ts            |   3 +-
 packages/core/tools/src/code-mode.ts          |   8 +-
 packages/core/tools/src/index.ts              |   4 +-
 packages/core/tools/src/py-types.ts           |  16 +-
 .../credentials-local/src/index.ts            |   5 +-
 .../credentials-local/tests/local.spec.ts     |   4 +-
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   8 +-
 packages/fs/README.zh.md                      |   8 +-
 packages/fs/fs/README.i18n.yaml               |   4 +-
 packages/fs/fs/README.md                      |   2 +-
 packages/fs/fs/README.zh.md                   |   2 +-
 packages/fs/tool-fs-search/README.i18n.yaml   |   4 +-
 packages/fs/tool-fs-search/README.md          |   2 +-
 packages/fs/tool-fs-search/README.zh.md       |   2 +-
 packages/fs/tool-fs/README.i18n.yaml          |   4 +-
 packages/fs/tool-fs/README.md                 |   2 +-
 packages/fs/tool-fs/README.zh.md              |   2 +-
 packages/goal/goal/src/domain.ts              |   6 +-
 .../guard/timeout-policy/README.i18n.yaml     |   4 +-
 packages/guard/timeout-policy/README.md       |   2 +-
 packages/guard/timeout-policy/README.zh.md    |   2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |   4 +-
 packages/hooks/hook-protocol/README.md        |   2 +-
 packages/hooks/hook-protocol/README.zh.md     |   2 +-
 packages/hooks/hooks-claude/src/index.ts      |   2 +-
 packages/hooks/hooks-codex/README.i18n.yaml   |   4 +-
 packages/hooks/hooks-codex/README.md          |   2 +-
 packages/hooks/hooks-codex/README.zh.md       |   2 +-
 packages/hooks/hooks-codex/src/index.ts       |   2 +-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   2 +-
 packages/host/apiproxy/README.zh.md           |   2 +-
 packages/host/apiproxy/src/api-proxy.ts       |   6 +-
 packages/host/apiproxy/src/index.ts           |   4 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |   8 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |   7 +-
 .../src/client/DirectoryBrowser.tsx           |   3 +-
 .../src/native-picker.ts                      |   4 +-
 .../interaction/user-approval/src/index.ts    |   3 +-
 .../tests/loader-composition.spec.ts          |   2 +-
 packages/llm/llm-pi-ai/src/catalog.ts         |   9 +-
 packages/llm/llm/README.i18n.yaml             |   4 +-
 packages/llm/llm/README.md                    |   2 +-
 packages/llm/llm/README.zh.md                 |   2 +-
 packages/llm/llm/src/message.ts               |   4 +-
 packages/llm/token-meter/README.i18n.yaml     |   4 +-
 packages/llm/token-meter/README.md            |   4 +-
 packages/llm/token-meter/README.zh.md         |   4 +-
 packages/lsp/lsp/src/types.ts                 |   2 +-
 packages/mcp/mcp-client/src/tools.ts          |   5 +-
 packages/mcp/mcp-client/src/transport.ts      |   5 +-
 packages/mcp/mcp-client/tests/apply.spec.ts   |   1 -
 .../mcp/mcp-client/tests/mcp-client.spec.ts   |   7 +-
 packages/scaffold/README.i18n.yaml            |   4 +-
 packages/scaffold/README.md                   |   2 +-
 packages/scaffold/README.zh.md                |   2 +-
 packages/scaffold/telemetry/README.i18n.yaml  |   4 +-
 packages/scaffold/telemetry/README.md         |   2 +-
 packages/scaffold/telemetry/README.zh.md      |   2 +-
 packages/self-modification/README.i18n.yaml   |   4 +-
 packages/self-modification/README.md          |   2 +-
 packages/self-modification/README.zh.md       |   2 +-
 .../tool-cordis/src/api-catalog.ts            |   2 +-
 .../session-query-sqlite/README.i18n.yaml     |   4 +-
 .../session-query-sqlite/README.md            |   2 +-
 .../session-query-sqlite/README.zh.md         |   2 +-
 .../tests/jsonl.spec.ts                       |   1 -
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-sqlite/README.md      |   5 +-
 .../session-persistence-sqlite/README.zh.md   |   5 +-
 .../session-projection-cache/src/spec.ts      |   3 +-
 .../session-telemetry-otel/src/index.ts       |   6 +-
 .../session/session-telemetry/src/index.ts    |   2 +-
 packages/skill/skill-local/README.i18n.yaml   |   4 +-
 packages/skill/skill-local/README.md          |   2 +-
 packages/skill/skill-local/README.zh.md       |   2 +-
 .../skill/tool-skill/tests/tool-skill.spec.ts |  10 +-
 .../storage/storage-sqlite/README.i18n.yaml   |   4 +-
 packages/storage/storage-sqlite/README.md     |   4 +-
 packages/storage/storage-sqlite/README.zh.md  |   4 +-
 .../subagent/subagent-acp/README.i18n.yaml    |   4 +-
 packages/subagent/subagent-acp/README.md      |   2 +-
 packages/subagent/subagent-acp/README.zh.md   |   2 +-
 packages/subagent/subagent-acp/src/index.ts   |   2 +-
 packages/subagent/subagent-acp/src/run.ts     |   2 +-
 .../subagent-claude-code/README.i18n.yaml     |   4 +-
 .../subagent/subagent-claude-code/README.md   |   2 +-
 .../subagent-claude-code/README.zh.md         |   2 +-
 .../subagent/subagent-codex/README.i18n.yaml  |   4 +-
 packages/subagent/subagent-codex/README.md    |   4 +-
 packages/subagent/subagent-codex/README.zh.md |   4 +-
 .../subagent-fork/tests/subagent-fork.spec.ts |   2 -
 .../subagent/subagent/src/list-children.ts    |   9 +-
 packages/subagent/subagent/src/types.ts       |   2 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   4 +-
 .../subprocess/subprocess-local/README.zh.md  |   4 +-
 packages/subprocess/subprocess/src/index.ts   |   4 +-
 .../support/acp-snapshot/README.i18n.yaml     |   4 +-
 packages/support/acp-snapshot/README.md       |   2 +-
 packages/support/acp-snapshot/README.zh.md    |   2 +-
 packages/support/acp-snapshot/src/harness.ts  |   4 +-
 packages/support/llm-replay/README.i18n.yaml  |   4 +-
 packages/support/llm-replay/README.md         |   2 +-
 packages/support/llm-replay/README.zh.md      |   2 +-
 packages/tasks/tasks/src/index.ts             |   7 +-
 packages/todo/tool-todo/src/index.ts          |   1 -
 .../typert/generator/src/cordis-catalog.ts    |   2 +-
 packages/util/retention/README.i18n.yaml      |   4 +-
 packages/util/retention/README.md             |   2 +-
 packages/util/retention/README.zh.md          |   2 +-
 packages/util/retention/src/index.ts          |   5 +-
 packages/util/timeout/README.i18n.yaml        |   4 +-
 packages/util/timeout/README.md               |   2 +-
 packages/util/timeout/README.zh.md            |   2 +-
 .../web/web-search-deepseek/README.i18n.yaml  |   4 +-
 packages/web/web-search-deepseek/README.md    |   2 +-
 packages/web/web-search-deepseek/README.zh.md |   2 +-
 packages/web/web/README.i18n.yaml             |   4 +-
 packages/web/web/README.md                    |   2 +-
 packages/web/web/README.zh.md                 |   2 +-
 packages/web/web/src/types.ts                 |   7 +-
 .../workflow/tool-workflow/README.i18n.yaml   |   4 +-
 packages/workflow/tool-workflow/README.md     |   2 +-
 packages/workflow/tool-workflow/README.zh.md  |   2 +-
 scripts/gen-doc-graphs.ts                     |   4 +-
 scripts/gen-tool-catalog.ts                   |   2 +-
 scripts/hero-composer-dom-continuity.mjs      |   2 +-
 scripts/translation-brief.ts                  |   7 +-
 scripts/verify-client-domain-graph.ts         |   8 +-
 vitest.config.ts                              |  10 +-
 763 files changed, 2705 insertions(+), 1710 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
 create mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts
 create mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
index 0eb64b3107..a061e142cb 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.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 .agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
-2026-06-11-event-sourced-sessions.md: 01f9628c1cfc000aca8654caf5edeff09411fdcc
-2026-06-11-event-sourced-sessions.zh.md: 5de230de9e9f1303943b43f6fdeefaf8264aa3bf
+2026-06-11-event-sourced-sessions.md: 1303ee843cd5f9e02eae7a1f9bc51594be4bb407
+2026-06-11-event-sourced-sessions.zh.md: d1800ab3820ba5fc60723d6851fe71eded38134f
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
index 01f9628c1c..1303ee843c 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
@@ -25,4 +25,4 @@ Ordering contract: the loop claims inbox messages before `agent/pre-step`, opens
 - Replay, trace, and telemetry are structurally guaranteed, not bolted on.
 - Persistence stays a plugin concern; the in-memory store ships in dsh-session.
 - The event vocabulary is merge-extensible (plugins add e.g. compaction events); [session persistence](2026-06-14-session-persistence.md) froze its shape once the log became durable.
-- Derivation cost grows with log length — compaction (future plugin) is the intended mitigation, not log mutation.
+- Derivation cost grows with log length — compaction (dsh-compact) is the intended mitigation, not log mutation.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
index 5de230de9e..d1800ab382 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
@@ -25,4 +25,4 @@ MVP 要求严格的基于事件的追踪，以及完全可回放的会话（严
 - 回放、追踪与遥测在结构上得到保证，而非事后附加。
 - 持久化仍是插件关注点；内存存储随 dsh-session 一起提供。
 - 事件词汇可通过合并扩展（插件可添加如压缩（compaction）事件）；[会话持久化](2026-06-14-session-persistence.md)在日志具备持久性后固定了其结构。
-- 派生成本随日志长度增长，压缩（未来插件）是预期的缓解手段，而非日志变更。
+- 派生成本随日志长度增长，压缩（dsh-compact）是预期的缓解手段，而非日志变更。
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
index b18ca244be..260604acc4 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.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 .agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
-2026-06-11-runtime-arg-validation.md: e0bca0ff24c5adc7ca58007932dff6580694b01d
-2026-06-11-runtime-arg-validation.zh.md: c98bde0ed2dd568a394aae74fb9f5549c3f61105
+2026-06-11-runtime-arg-validation.md: 520823c76f147205805d306e97b5461f38b84c35
+2026-06-11-runtime-arg-validation.zh.md: ccb9b50d8b8a932d17516e579a5364321b64577b
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
index e0bca0ff24..520823c76f 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
@@ -18,7 +18,7 @@ The validator and compiler therefore share exact semantics: the implicit paramet
 
 - The model gets actionable feedback on its own malformed calls instead of an opaque crash, closing the gap between `InferArgs`'s promise and runtime reality.
 - The validator and `InferArgs` must stay in agreement; [a property test](../testing/2026-06-11-property-based-testing.md) generates args satisfying a spec and asserts they pass `validateArgs` (with targeted corruptions rejected), closing that drift risk mechanically.
-- `ToolArgsError` is a plain `Error` with a `code` field for now; if a harness-wide error taxonomy lands it becomes a subclass without changing callers that read `.message`.
+- `ToolArgsError` subclasses `HarnessError` from the [structured error taxonomy](2026-06-11-structured-error-taxonomy.md), keeping its `code` field; callers that read `.message` are unaffected by the hierarchy.
 - Validation cost is negligible next to a model call.
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
index c98bde0ed2..ccb9b50d8b 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 - 模型在自身畸形调用上获得可操作的反馈，而非不透明的崩溃，弥合了 `InferArgs` 的承诺与运行时现实之间的鸿沟。
 - 校验器与 `InferArgs` 必须保持一致；一项[属性测试](../testing/2026-06-11-property-based-testing.md)生成满足 spec 的参数并断言它们通过 `validateArgs`（同时断言定向破坏的参数被拒绝），以机械方式封堵漂移风险。
-- `ToolArgsError` 目前是带 `code` 字段的普通 `Error`；如果日后引入 harness 级别的错误分类体系，它将变为子类，但不影响读取 `.message` 的调用方。
+- `ToolArgsError` 是[结构化错误分类体系](2026-06-11-structured-error-taxonomy.md)中 `HarnessError` 的子类，保留其 `code` 字段；读取 `.message` 的调用方不受该层级结构影响。
 - 校验开销相对于一次模型调用可忽略不计。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index f2b2982bc1..a28df36350 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.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 .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
-2026-06-14-session-persistence.md: 46fd3755a3c35bd342119fb59b560775a679f740
-2026-06-14-session-persistence.zh.md: f29b192ec9814de2a183599bcfc0a4a0c301b31e
+2026-06-14-session-persistence.md: 6961b8f3f4274587c2920fe2b2602aff5efe4afc
+2026-06-14-session-persistence.zh.md: 58c8bb80a1f886c986fc5aa1a0ba6b7f263ad829
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
index 46fd3755a3..6961b8f3f4 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
@@ -17,7 +17,7 @@ Persistence is a **capability seam** with an abstract Service Definition ([capab
 1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`. Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type.
 2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only logical JSONL log per session: a `SessionHeader` line followed by storage records that losslessly represent the contiguous `SessionEvent` stream. Eligible `assistant/chunk` delta runs use packed rows by default; [checksummed Zstandard frames](2026-07-19-zstandard-jsonl-session-logs.md) are the default physical encoding, with raw lines configurable.
 
-Key choices recorded here because they are durable, contested, and surprising:
+Key durable, contested choices:
 
 - **The canonical durable log persists every `SessionEvent` losslessly, including `assistant/chunk`.** JSONL storage may encode a consecutive delta run as one packed row, but logical readers reconstruct the exact event boundaries, sequence numbers, and timestamps. `deriveMessages()` skips chunks, and a chunk-filtered rollout (Codex's `policy.rs`) is tempting — but `seq = log.length` and validation of `events[i].seq === i` require a *contiguous* logical log; filtering chunks out would leave holes and break both the contract and resume. A chunk-filtered projection is possible later as a derived view with its own renumbering, but it is NOT the canonical log.
 - **Append-only; a crashed turn is closed, never truncated.** Flushed events are never rewritten. The [semantic checkpoint policy](../bug-fix/2026-07-21-semantic-session-checkpoints.md) drains the request before model dispatch, a recorded top-level call before tool dispatch, and the complete response/result batch after a step; the loop drains the final turn boundary. Because one interrupted turn may contain substantial valid work, cold inspection preserves its contiguous, parseable events and adds risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }` to the in-memory logical view. `prepare` or `load` commits those closers before returning a recoverable view; the synthetic results keep resumed provider transcripts valid. Only an incomplete final record is discarded during committed repair; a parse error or sequence gap at or before the last real `turn/end` is corruption and makes the session unloadable.
@@ -29,7 +29,7 @@ Key choices recorded here because they are durable, contested, and surprising:
 
 Each key choice above records its rejected alternative where the choice is stated: a **chunk-filtered canonical log** (Codex's `policy.rs` shape) — breaks the contiguous-seq contract; **truncating a crashed turn** — silently destroys a long autonomous run's real work; an **in-log `session/meta` event as line 0** — metadata is not replayable state; **finite fractional `createdAt` values** — have no producer and diverge from integer Unix-millisecond storage and query columns; **adopting a non-pristine unversioned SQLite file** — can overwrite unrelated objects or identity; **hard-injecting `sessionPersistence` into the loop** — would pend non-persistent demos forever.
 
-Format versioning: the header carries a `version`; cold reads reject any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no broad compatibility promise, while the coordinator may own an explicit narrow import upgrade when persisted user data requires it ([pre-identity message recovery](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)). Stated honestly: append-only + flush is robust to partial trailing writes (tolerated during cold preparation) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option later.
+Format versioning: the header carries a `version`; cold reads reject any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no broad compatibility promise, while the coordinator may own an explicit narrow import upgrade when persisted user data requires it ([pre-identity message recovery](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)). Append-only + flush is robust to partial trailing writes (tolerated during cold preparation) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option there.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index f29b192ec9..58c8bb80a1 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -17,7 +17,7 @@ Status: implemented
 1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`。其持久化单元就是现有的 `SessionEvent`（`{ type, seq, time, data }`），原样复用，无转换类型。
 2. **实现**（`dsh-session-persistence-jsonl`）：每个会话一个仅追加的逻辑 JSONL 日志：先是一行 `SessionHeader`，随后是无损表示连续 `SessionEvent` 流的存储记录。符合条件的 `assistant/chunk` 增量连续段默认使用打包行；[带校验和的 Zstandard 帧](2026-07-19-zstandard-jsonl-session-logs.md)是默认物理编码，也可通过配置使用原始行。
 
-以下关键选择记录于此，因为它们长期有效、存在争议且出人意料：
+长期有效、存在争议的关键选择：
 
 - **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
 - **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些 closer；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
@@ -29,7 +29,7 @@ Status: implemented
 
 上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 约定；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
 
-格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（冷准备时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
+格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。仅追加 + 刷写对部分尾部写入是健壮的（冷准备时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是该场景下更强的选项。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index 159483fb73..68bcd74197 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 35fe5148ca44f733aa0a354e215cd1d77eb8180e
-2026-06-17-filesystem-capability-seam.zh.md: 998b5ead48dcaf168ad48c8ad7a403a7e3b3e955
+2026-06-17-filesystem-capability-seam.md: 928ad4926e46ed5b6b35552b75882d565d8ad6db
+2026-06-17-filesystem-capability-seam.zh.md: 02af77a3cc291eeba2be966a4bc08aa006675e7d
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 35fe5148ca..928ad4926e 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-17-filesystem-capability-seam.zh.md)
 
 ## Problem
 
-The harness has a concrete `bash` capability seam (`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`), but filesystem operations are about to be added as model-facing tools without an equivalent seam. If `read`, `write`, and `edit` directly use `node:fs`, the model-facing tool package will own filesystem execution policy, local path resolution, atomic write behavior, text decoding, symlink behavior, and edit semantics all at once.
+The harness has a concrete `bash` capability seam (`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`), but filesystem operations were about to land as model-facing tools without an equivalent seam. If `read`, `write`, and `edit` directly used `node:fs`, the model-facing tool package would own filesystem execution policy, local path resolution, atomic write behavior, text decoding, symlink behavior, and edit semantics all at once.
 
 That couples three concerns that change independently:
 
@@ -16,7 +16,7 @@ That couples three concerns that change independently:
 
 Without a `ctx.fs` interface, swapping local filesystem access for a sandboxed or remote backend would churn the tool schemas, demos, and prompt guidance even when the model-facing contract should stay stable. It also makes permission/sandbox boundaries harder to reason about: a `cwd` option can look like a sandbox even though it is only a base path unless an explicit backend or `tools/execute` policy enforces containment.
 
-We need the filesystem tools to land in the same capability-seam shape as bash before they become a public package surface.
+The filesystem tools must land in the same capability-seam shape as bash before they become a public package surface.
 
 ## Decision
 
@@ -28,7 +28,7 @@ Filesystem access is a first-class capability seam following [the capability-sea
 
 The Consumer package depends only on the Service Definition package, never on `dsh-fs-local`. A deployment that wants a different backend loads a different provider for `ctx.fs` without changing the tool schemas or model-facing prompt guidance.
 
-The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This Agent Note established the three-package boundary; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md). This document is updated to describe that landed four-package shape.
+The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This decision established the three-package boundary; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md).
 
 The first backend is deliberately local-only: `dsh-fs-local` implements `ctx.fs` against the host filesystem. Future sibling backends can provide sandboxed, remote, virtual, or project-scoped filesystems behind the same interface.
 
@@ -74,7 +74,7 @@ The provider contract also carries the freshness hooks that policy builds on —
 - `writeText`/`editText` take an OPTIONAL version expectation: omit it for an unconditional bare-provider mutation, or supply it to guard the mutation inside the backend's atomic critical section.
 - The `dsh-fs-policy` plugin decides that expectation on `fs/write-intent`/`fs/edit-intent` and records observed versions on `fs/observed`, keyed by an owner it derives from the opaque event actor (normally `exec.agent.session`).
 
-Authorization is version freshness, not a full/partial view distinction: any read records the target's version, and a later write/edit is authorized as long as the file is still at that version — so a windowed read of lines 100-150 authorizes an edit of line 120. The observed-state store is a `WeakMap<owner, Map<targetKey, version>>` inside `dsh-fs-policy`; `dsh-fs` holds none of it and treats the actor as opaque. (This Agent Note first modeled a `FileState` cache with `full`/`partial` views on `ctx.fs`; the split-fs-seam and event-gate Agent Notes replaced that with the freshness-based policy plugin described here.)
+Authorization is version freshness, not a full/partial view distinction: any read records the target's version, and a later write/edit is authorized as long as the file is still at that version — so a windowed read of lines 100-150 authorizes an edit of line 120. The observed-state store is a `WeakMap<owner, Map<targetKey, version>>` inside `dsh-fs-policy`; `dsh-fs` holds none of it and treats the actor as opaque. (This decision first modeled a `FileState` cache with `full`/`partial` views on `ctx.fs`; the split-fs-seam and event-gate notes replaced that with the freshness-based policy plugin described here.)
 
 Path resolution is explicit and allowed to be async. Local resolution may only normalize a path, but sandboxed/remote/project-scoped backends may need I/O to resolve a user-supplied path into a stable target identity.
 
@@ -148,11 +148,11 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 
 **The interface can become too local.** Returning fields such as `absolutePath` from `ctx.fs` would make remote, sandboxed, or virtual backends awkward. The contract should expose display metadata without requiring consumers to understand host paths.
 
-**The interface can become too thin.** If `ctx.fs` only mirrors `node:fs` primitives, `tool-fs` will reimplement binary detection, pagination, atomic writes, and edit semantics. That recreates the coupling this Agent Note is trying to avoid.
+**The interface can become too thin.** If `ctx.fs` only mirrors `node:fs` primitives, `tool-fs` will reimplement binary detection, pagination, atomic writes, and edit semantics. That recreates the coupling this decision avoids.
 
 **Edit semantics are race-prone by nature.** Literal edit is a read-modify-write operation; the guard is the backend's atomic mutation critical section plus the optional version expectation, so concurrent edits settle deterministically — one wins, the other gets `FS_STALE_VERSION`.
 
-**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This Agent Note first placed it inside the filesystem seam; the split-fs-seam Agent Note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider contract keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
+**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This decision first placed it inside the filesystem seam; the split-fs-seam note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider contract keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
 
 **The `resolve`-then-operate shape costs an extra round-trip per call.** Each tool may resolve a path to an `FsTarget` and then issue the read/write/edit as a separate `ctx.fs` call. For the local backend this is negligible (resolution is in-memory path normalization), but a remote/sandboxed backend may turn each step into its own request, so a single `read` can become two network round-trips. Backends where the round-trip matters can cache or fold resolution internally while preserving the observable contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index 998b5ead48..02af77a3cc 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`），但文件系统操作即将作为面向模型的工具加入，却没有等价的 seam。如果 `read`、`write` 和 `edit` 直接使用 `node:fs`，面向模型的工具包将同时承担文件系统执行策略、本地路径解析、原子写入行为、文本解码、符号链接行为和编辑语义。
+harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`），但文件系统操作当时即将作为面向模型的工具落地，却没有等价的 seam。如果 `read`、`write` 和 `edit` 直接使用 `node:fs`，面向模型的工具包就会同时承担文件系统执行策略、本地路径解析、原子写入行为、文本解码、符号链接行为和编辑语义。
 
 这把三个独立变化的关注点耦合在了一起：
 
@@ -16,7 +16,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的约定应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
 
-我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
+文件系统工具必须在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
 
 ## 决策
 
@@ -28,7 +28,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需要不同后端的部署只需为 `ctx.fs` 加载不同的提供方，无需改动工具 schema 或面向模型的提示词引导。
 
-读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本 Agent Note 确立了由三个包构成的边界；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。本文已更新为描述最终落地的四包形态。
+读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本决策确立了由三个包构成的边界；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。
 
 第一个后端有意仅限本地：`dsh-fs-local` 基于宿主文件系统实现 `ctx.fs`。未来的兄弟后端可在同一接口之后提供沙箱、远程、虚拟或项目作用域的文件系统。
 
@@ -74,7 +74,7 @@ Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需
 - `writeText`/`editText` 接受一个可选的版本期望：省略它表示无条件的裸提供方变更；提供它则在后端的原子临界区内守护变更。
 - `dsh-fs-policy` 插件在 `fs/write-intent`/`fs/edit-intent` 上决定该期望，并在 `fs/observed` 上记录观测版本，以它从不透明事件 actor 推导出的 owner 为键（通常是 `exec.agent.session`）。
 
-授权基于版本新鲜度，而非完整/部分视图的区分：任何读取都会记录目标的版本，后续的写入/编辑只要文件仍处于该版本就被授权——因此对第 100-150 行的窗口化读取可以授权对第 120 行的编辑。观测状态存储是 `dsh-fs-policy` 内部的 `WeakMap<owner, Map<targetKey, version>>`；`dsh-fs` 不持有任何此类数据，并将 actor 视为不透明。（本 Agent Note 最初建模了一个带 `full`/`partial` 视图的 `FileState` 缓存放在 `ctx.fs` 上；拆分文件系统 seam 与事件门控两份 Agent Note 将其替换为此处描述的基于新鲜度的策略插件。）
+授权基于版本新鲜度，而非完整/部分视图的区分：任何读取都会记录目标的版本，后续的写入/编辑只要文件仍处于该版本就被授权——因此对第 100-150 行的窗口化读取可以授权对第 120 行的编辑。观测状态存储是 `dsh-fs-policy` 内部的 `WeakMap<owner, Map<targetKey, version>>`；`dsh-fs` 不持有任何此类数据，并将 actor 视为不透明。（本决策最初建模了一个带 `full`/`partial` 视图的 `FileState` 缓存放在 `ctx.fs` 上；拆分文件系统 seam 与事件门控两份笔记将其替换为此处描述的基于新鲜度的策略插件。）
 
 路径解析是显式的，允许异步。本地解析可能只做路径规范化，但沙箱/远程/项目作用域的后端可能需要 I/O 才能将用户提供的路径解析为稳定的目标标识。
 
@@ -148,11 +148,11 @@ Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需
 
 **接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。约定应暴露显示元数据，而不要求消费方理解宿主路径。
 
-**接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本 Agent Note 试图避免的耦合。
+**接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本决策所避免的耦合。
 
 **编辑语义天然易受竞争影响。** 字面编辑是读-改-写操作；守护手段是后端的原子变更临界区加上可选的版本期望，因此并发编辑确定性地收敛——一个赢，另一个得到 `FS_STALE_VERSION`。
 
-**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方约定只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
+**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本决策最初将其放在文件系统 seam 内部；拆分文件系统 seam 笔记随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方约定只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
 
 **`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测约定不变。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index c10a8a497c..6abc3ded93 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: 73b3ab9080506edb9b0693c22a4c30544b506c11
-2026-06-18-session-surface.zh.md: 0c7ebbacd2f89da8012f3c08f1e4354a1d6c2e8e
+2026-06-18-session-surface.md: fd48a4ee4e177b84a235b044b054e4ac266df8ba
+2026-06-18-session-surface.zh.md: 86f9c5fdd5d711fb81e03e95329d316bfef29227
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 73b3ab9080..fd48a4ee4e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -68,6 +68,6 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 - **`packages/session/session-persistence-jsonl`**: No changes required.
 - **`packages/session/session-persistence`**: Abstract interface unchanged.
 
-The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
+The surface is the foundation history manipulation ships on — dsh-compact's compaction rides it. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
 
 A `tool/result` replacement may rewrite exactly one current `tool/result` and must preserve every data field except `content`. Session acceptance enforces this rule together with positional range and cited source-event validation, independent of optional diagnostic plugins.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index 0c7ebbacd2..86f9c5fdd5 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -68,6 +68,6 @@ export type SurfaceOp =
 - **`packages/session/session-persistence-jsonl`**：无需改动。
 - **`packages/session/session-persistence`**：抽象接口不变。
 
-Surface 是未来历史操纵的基础。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
+Surface 是历史操纵赖以落地的基础——dsh-compact 的压缩就搭载于其上。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
 
 一次 `tool/result` 替换只能改写当前的一个 `tool/result`，并且必须保留除 `content` 以外的每个数据字段。Session 接纳会与位置范围和引用的源事件校验一起强制这条规则，不依赖可选的诊断插件。
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 702a9035d5..00cff75149 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.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 .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: 1d373317664f605e5164e2eb6980b8fa7c6b4e05
-2026-06-18-shared-persistence-write-coordinator.zh.md: 607f1fe68d1404a56c84848c8561cf8749daab0b
+2026-06-18-shared-persistence-write-coordinator.md: c376bb4a209a250d33274dfd60531475354ba363
+2026-06-18-shared-persistence-write-coordinator.zh.md: 06a2dafc4d14c29bb7758fdc67d3f0f8136983e2
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
index 1d37331766..c376bb4a20 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
@@ -12,7 +12,7 @@ English | [中文](2026-06-18-shared-persistence-write-coordinator.zh.md)
 
 Extract a backend-agnostic `PersistenceCoordinator` into `dsh-session-persistence`. The coordinator owns the orchestration once; each first-party backend composes one (`new PersistenceCoordinator(ctx, this)`), implements a small `PersistenceBackend` hook interface, and delegates its stateful public methods (`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`) to it. Backend-owned metadata and revision listing bypass the coordinator.
 
-Composition, not inheritance. The coordinator is a concrete class the backend holds, not a base class the backend extends. The Agent Note's risk — "a coordinator must not make unusual backends fight an inheritance hierarchy" — is avoided: a backend exposes only the hooks and cannot reach the coordinator's private orchestration state. A third-party backend MAY still implement the abstract service directly without the coordinator, including immutable logical inspection and the default preparation fallback through `load`.
+Composition, not inheritance. The coordinator is a concrete class the backend holds, not a base class the backend extends. The risk that a coordinator makes unusual backends fight an inheritance hierarchy is avoided: a backend exposes only the hooks and cannot reach the coordinator's private orchestration state. A third-party backend MAY still implement the abstract service directly without the coordinator, including immutable logical inspection and the default preparation fallback through `load`.
 
 The coordinator holds one lifecycle entry for each exact live `Session`: initialization plus a package-private write controller that owns pending events, a fixed batching deadline, the active write, failure retention, and the shared flush barrier. Each `session/event` enters that bounded write path, and `session/flush` bypasses the wait to observe quiescence. The [flush-controller simplification](../simplification/2026-07-23-collapse-persistence-flush-state.md) owns controller consolidation; the [bounded batching decision](2026-08-08-bounded-session-persistence-write-batching.md) owns scheduling cadence.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 607f1fe68d..06a2dafc4d 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
 
-组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。协调器让非常规后端与继承层级作斗争的风险由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
 
 协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
index f906aa4336..2270bc6f5f 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.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 .agents/notes/implemented/architecture/2026-06-20-branded-ids.md
-2026-06-20-branded-ids.md: 005706a12769a03e9c8ce66bf631ca0d75ade8b4
-2026-06-20-branded-ids.zh.md: b6b58a8b703d5637a6a5053543193bf9779489ac
+2026-06-20-branded-ids.md: 78242226103fef0eac320cdfac0ccb82292fd9e8
+2026-06-20-branded-ids.zh.md: 613ef81d198f10ec70ca5cb019776e607f4a8a79
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
index 005706a127..7824222610 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-20-branded-ids.zh.md)
 
 The harness brands `CallId` (`packages/llm/llm/src/brand.ts`) and the shared agent/session `SessionId` (`packages/core/session/src/types.ts`) using the `Branded<B> = string & { readonly [BRAND]: B }` machinery (owned by the type-only `@deepseek-ai/dsh-brand` package at `packages/util/brand/` — see its [README](../../../../packages/util/brand/README.md)) and a zero-cost cast factory per type. `dsh-brand` also states the governing policy: *"Branding is for ids that cross package boundaries and could plausibly be confused; not every string needs a brand."* That policy is right; the problem is that it is only half-applied. Two gaps let a structurally-identical-but-semantically-wrong string slip through the type checker today.
 
-**Gap 1 — unbranded cross-boundary IDs in the bash seam.** The background-task id is a plain `string`: `BashTask.id: string` (`packages/bash/bash/src/types.ts`), carried as `string` through the whole executor seam (`BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)` in `packages/bash/bash/src/index.ts`) and validated/passed as `string` by the model-facing tools (`validateTaskId`, `assertTaskAccess`, the `task_id` schema arg in `packages/bash/tool-bash/src/index.ts`). It is generated by a per-executor counter — `` `bash-${this.nextTaskId++}` `` in `packages/bash/bash-local/src/index.ts` — which gives it **exactly the same `name-N` shape as `SessionId`'s default** (`` `session-${++counter}` `` in `packages/core/session/src/index.ts`). A bash task id and a session id are trivially swappable at a call site and the compiler says nothing. This is the headline case the user asked about, and it is a model-facing id (the model passes `task_id` back to `bash_output`/`bash_kill`), so a confusion here is reachable from untrusted input.
+**Gap 1 — unbranded cross-boundary IDs in the bash seam.** The background-task id is a plain `string`: `BashTask.id: string` (`packages/bash/bash/src/types.ts`), carried as `string` through the whole executor seam (`BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)` in `packages/bash/bash/src/index.ts`) and validated/passed as `string` by the model-facing tools (`validateTaskId`, `assertTaskAccess`, the `task_id` schema arg in `packages/bash/tool-bash/src/index.ts`). It is generated by a per-executor counter — `` `bash-${this.nextTaskId++}` `` in `packages/bash/bash-local/src/index.ts` — which gives it **exactly the same `name-N` shape as `SessionId`'s default** (`` `session-${++counter}` `` in `packages/core/session/src/index.ts`). A bash task id and a session id are trivially swappable at a call site and the compiler says nothing. It is a model-facing id (the model passes `task_id` back to `bash_output`/`bash_kill`), so a confusion here is reachable from untrusted input.
 
 The bash **owner token** is the related sub-case: `BashExecRequest.owner?: string` and `BashExecSpec.owner: string | undefined` (`packages/bash/bash/src/types.ts`) are documented as a deliberately *opaque* isolation key, but in every live caller the value IS the owning agent's shared `Agent.id`/`SessionId` (`callerToken = (exec) => exec.agent?.id` in `packages/bash/tool-bash/src/index.ts`) wearing a different seam-local name. It is compared for access control (`owner !== callerToken(exec)`), so a mismatched-but-well-typed string here is a cross-session isolation bug the type system currently cannot catch. This is the shared id alias covered by the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md).
 
@@ -16,13 +16,13 @@ The bash **owner token** is the related sub-case: `BashExecRequest.owner?: strin
 
 ## Decision
 
-A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The work is in three parts, all honoring the existing "not every string" policy.
+A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The decision has three parts, all honoring the existing "not every string" policy.
 
 - **Brand the bash task id.** Add `BashTaskId = Branded<'BashTaskId'>` plus its same-named factory in `packages/bash/bash/src/types.ts` (the package that *owns* the id), importing `Branded` from `@deepseek-ai/dsh-brand` exactly as `SessionId` does. The brand primitive lives in the dependency-free `dsh-brand` utility package precisely so `dsh-bash` can brand its ids by depending on it alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`. Thread it through `BashTask.id`, the `BashExecutor` Service Definition methods (`get`/`ownerOf`/`readOutput`/`kill`), the generation site in `dsh-bash-local` (brand the counter output once, at creation), and the `dsh-tool-bash` validate/access surface (`validateTaskId` returns a `BashTaskId`; `task_id` is branded at the tool boundary where the model's string arrives).
 
 - **Mint a distinct `OwnerToken` brand.** Add `OwnerToken = Branded<'OwnerToken'>` in `packages/bash/bash/src/types.ts`; type `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` as `OwnerToken | undefined`. The `dsh-tool-bash` consumer casts the agent's shared `id` (`SessionId`) into an `OwnerToken` at the boundary — the one place the two vocabularies meet. The bash Service Definition never imports `dsh-session`. (Rationale in the next section.)
 
-- **Stop the brand erosion.** Propagate the existing brands to the `Map` key types and public method params listed under Gap 2 — `Map<SessionId, Session>`, `Map<SessionId, Agent>`, `get(id: SessionId)`, `Map<CallId, …>`, ACP's `SessionId` surface, and the coordinator's `Map<SessionId, …>`. This is the larger mechanical share of the diff and the part that makes the *existing* brands actually load-bearing on lookups, not just on struct fields.
+- **Stop the brand erosion.** Propagate the existing brands to the `Map` key types and public method params listed under Gap 2 — `Map<SessionId, Session>`, `Map<SessionId, Agent>`, `get(id: SessionId)`, `Map<CallId, …>`, ACP's `SessionId` surface, and the coordinator's `Map<SessionId, …>`. This is the larger mechanical share of the change and the part that makes the *existing* brands actually load-bearing on lookups, not just on struct fields.
 
 Illustrative shape (the factory pattern is identical to the three existing brands):
 
@@ -52,11 +52,11 @@ The obvious shortcut is to type `owner` as `SessionId` directly — it always *i
 
 Kept deliberately narrow per the "not every string needs a brand" policy. Each of these is a plausible future brand, deferred with a reason, not a commitment:
 
-- **`ModelId`** (`GenerateOptions.model`, the `LlmService` adapter-registry key) — a real cross-package lookup key (config → agent → llm → adapter); a reasonable next brand, left out only to keep this Agent Note's blast radius focused.
+- **`ModelId`** (`GenerateOptions.model`, the `LlmService` adapter-registry key) — a real cross-package lookup key (config → agent → llm → adapter); a reasonable next brand, left out only to keep this decision's blast radius focused.
 - **`ToolName`** (the `ToolRegistry` key) — author-defined, human-readable, and rarely confused with another id; the weakest candidate, likely not worth a brand.
 - **`ErrorCode`** (`HarnessError.code`) — a closed vocabulary (`ABORTED`, `NO_ADAPTER`, …), not a per-instance id; better served by a string-literal union than a brand, if anything.
 - **Numeric ordinals** — turn number, step number, and the event `seq` are `number`, not `string`, so `Branded<string>` does not apply; a parallel `number & { readonly [BRAND]: B }` variant could brand them, but they are positional ordinals rarely passed across boundaries, so the payoff is low.
-- **Validated construction** — the brand factories are pure casts with no runtime check, and every boundary (ACP `sessionId`, provider-issued `call.id`, the empty-string fallback in `dsh-llm-deepseek`) trusts the raw string today. A `SessionId.parse()` / `isValid()` companion that throws on malformed input at boundaries is a genuine gap, but it is a *runtime-behavior* change with its own design (what is "malformed"? what do we do on failure?) and belongs in its own Agent Note, not bundled into this type-only pass.
+- **Validated construction** — the brand factories are pure casts with no runtime check, and every boundary (ACP `sessionId`, provider-issued `call.id`, the empty-string fallback in `dsh-llm-deepseek`) trusts the raw string today. A `SessionId.parse()` / `isValid()` companion that throws on malformed input at boundaries is a genuine gap, but it is a *runtime-behavior* change with its own design (what is "malformed"? what happens on failure?) and belongs in its own decision, not bundled into this type-only change.
 
 ## Verification
 
@@ -65,5 +65,5 @@ The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` a
 ## Consequences
 
 - **Mechanical churn across two surfaces.** Propagating brands touches the bash seam (Service Definition + Service provider + Consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md) because both touch the session-id / owner-token boundary; `OwnerToken` stays distinct from the unified id for the decoupling reason above.
-- **Brands do not validate.** A brand is a confusability guard, not a correctness proof: a *wrong* session id that is still a well-formed string passes the type checker exactly as before. This Agent Note does not close that gap (see Out of scope) — it only stops the *category* error of passing the wrong *kind* of id.
-- **The "where to stop" line stays a judgment call.** Branding `BashTaskId` but not `ToolName`, `OwnerToken` but not `ModelId`, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in `brand.ts` is the tie-breaker, and this Agent Note errs toward the ids that are model-facing or used for access control.
+- **Brands do not validate.** A brand is a confusability guard, not a correctness proof: a *wrong* session id that is still a well-formed string passes the type checker exactly as before. This decision does not close that gap (see Out of scope) — it only stops the *category* error of passing the wrong *kind* of id.
+- **The "where to stop" line stays a judgment call.** Branding `BashTaskId` but not `ToolName`, `OwnerToken` but not `ModelId`, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in `brand.ts` is the tie-breaker, and this decision errs toward the ids that are model-facing or used for access control.
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
index b6b58a8b70..613ef81d19 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 harness 使用 `Branded<B> = string & { readonly [BRAND]: B }` 机制，为 `CallId`（`packages/llm/llm/src/brand.ts`）和 agent/会话共享的 `SessionId`（`packages/core/session/src/types.ts`）做 brand 处理；该机制由纯类型包 `@deepseek-ai/dsh-brand` 拥有，位于 `packages/util/brand/`，见其 [README](../../../../packages/util/brand/README.md)，并为每个类型提供零开销的 cast 工厂。`dsh-brand` 还声明了治理策略：*「Branding 用于跨包边界且可能被混淆的 id；不是每个 string 都需要 brand。」* 这条策略是正确的；问题在于它只落实了一半。两处缺口使得结构相同但语义错误的 string 今天仍能通过类型检查器。
 
-**缺口 1：bash seam 中未 brand 的跨边界 ID。** 后台 task id 是普通 `string`：`BashTask.id: string`（`packages/bash/bash/src/types.ts`），作为 `string` 贯穿整个执行器 seam（`packages/bash/bash/src/index.ts` 中的 `BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)`），再由面向模型的工具以 `string` 校验并传递（`validateTaskId`、`assertTaskAccess`、`packages/bash/tool-bash/src/index.ts` 中 `task_id` 的 schema 参数）。它由每执行器计数器生成——`packages/bash/bash-local/src/index.ts` 中的 `` `bash-${this.nextTaskId++}` ``——其形状与 `SessionId` 的默认值**完全相同，都是 `name-N`**（`packages/core/session/src/index.ts` 中的 `` `session-${++counter}` ``）。bash task id 和会话 id 在调用点轻易就能互换，而编译器毫无反应。这是用户询问的核心案例，并且它是面向模型的 id（模型会把 `task_id` 传回 `bash_output`/`bash_kill`），所以该混淆可由不受信任的输入触达。
+**缺口 1：bash seam 中未 brand 的跨边界 ID。** 后台 task id 是普通 `string`：`BashTask.id: string`（`packages/bash/bash/src/types.ts`），作为 `string` 贯穿整个执行器 seam（`packages/bash/bash/src/index.ts` 中的 `BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)`），再由面向模型的工具以 `string` 校验并传递（`validateTaskId`、`assertTaskAccess`、`packages/bash/tool-bash/src/index.ts` 中 `task_id` 的 schema 参数）。它由每执行器计数器生成——`packages/bash/bash-local/src/index.ts` 中的 `` `bash-${this.nextTaskId++}` ``——其形状与 `SessionId` 的默认值**完全相同，都是 `name-N`**（`packages/core/session/src/index.ts` 中的 `` `session-${++counter}` ``）。bash task id 和会话 id 在调用点轻易就能互换，而编译器毫无反应。它是面向模型的 id（模型会把 `task_id` 传回 `bash_output`/`bash_kill`），所以该混淆可由不受信任的输入触达。
 
 bash **owner token** 是相关的子情形：`BashExecRequest.owner?: string` 和 `BashExecSpec.owner: string | undefined`（`packages/bash/bash/src/types.ts`）被文档描述为刻意*不透明*的隔离键，但在所有实际调用方中，该值就是所属 agent（智能体）共享的 `Agent.id`/`SessionId`（`callerToken = (exec) => exec.agent?.id`，位于 `packages/bash/tool-bash/src/index.ts`），只是披着另一个 seam 本地名称。它被用于访问控制比较（`owner !== callerToken(exec)`），因此一个不匹配但类型正确的 string 在此处就是跨会话隔离 bug，而当前类型系统无法捕获。这正是[统一 agent/session 标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)覆盖的共享 id 别名。
 
@@ -16,13 +16,13 @@ bash **owner token** 是相关的子情形：`BashExecRequest.owner?: string` 
 
 ## 决策
 
-纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。工作分三部分，全部遵循既有的「不是每个 string 都需要」策略。
+纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。该决策分三部分，全部遵循既有的「不是每个 string 都需要」策略。
 
 - **为 bash task id 加 brand。** 在 `packages/bash/bash/src/types.ts`（*拥有*该 id 的包）中添加 `BashTaskId = Branded<'BashTaskId'>` 及其同名工厂，从 `@deepseek-ai/dsh-brand` 导入 `Branded`，方式与 `SessionId` 完全一致。brand 原语位于无依赖的 `dsh-brand` 工具包中，正是为了让 `dsh-bash` 仅依赖它就能为自己的 id 加 brand，而无需引入 `dsh-llm`（或 `dsh-session`）来获取 `Branded`。将其贯穿 `BashTask.id`、`BashExecutor` Service Definition 方法（`get`/`ownerOf`/`readOutput`/`kill`）、`dsh-bash-local` 中的生成点（在创建时对计数器输出做一次 brand），以及 `dsh-tool-bash` 的校验/访问面（`validateTaskId` 返回 `BashTaskId`；`task_id` 在模型 string 到达的工具边界处被 brand）。
 
 - **铸造独立的 `OwnerToken` brand。** 在 `packages/bash/bash/src/types.ts` 中添加 `OwnerToken = Branded<'OwnerToken'>`；将 `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` 的类型标注为 `OwnerToken | undefined`。`dsh-tool-bash` 消费方在边界处将 agent 共享的 `id`（`SessionId`）cast 为 `OwnerToken`——这是两套词汇唯一交汇的地方。bash Service Definition 从不导入 `dsh-session`。（理由见下一节。）
 
-- **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是 diff 中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
+- **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是变更中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
 
 示意形状（工厂模式与已有的三个 brand 完全一致）：
 
@@ -52,11 +52,11 @@ export function OwnerToken(id: string): OwnerToken {
 
 遵循「不是每个 string 都需要 brand」的策略，刻意保持窄范围。以下每项都是合理的未来 brand 候选，附带推迟理由而非承诺：
 
-- **`ModelId`**（`GenerateOptions.model`，`LlmService` 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本 Agent Note 的影响范围而暂不纳入。
+- **`ModelId`**（`GenerateOptions.model`，`LlmService` 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本决策的影响范围而暂不纳入。
 - **`ToolName`**（`ToolRegistry` 的键）：由作者定义、人类可读，且很少与其他 id 混淆；最弱的候选，可能不值得加 brand。
 - **`ErrorCode`**（`HarnessError.code`）：一个封闭词汇（`ABORTED`、`NO_ADAPTER`……），不是逐实例的 id；如果要做，string 字面量联合类型比 brand 更合适。
 - **数值序号**：轮次号、步骤号和事件 `seq` 是 `number` 而非 `string`，`Branded<string>` 不适用；可以用并行的 `number & { readonly [BRAND]: B }` 变体来 brand 它们，但它们是位置序号、很少跨边界传递，收益较低。
-- **带校验的构造**：brand 工厂是纯 cast，无运行时检查，且每个边界（ACP `sessionId`、提供方签发的 `call.id`、`dsh-llm-deepseek` 中的空字符串回退）今天都信任裸 string。一个在边界处对格式错误的输入抛异常的 `SessionId.parse()` / `isValid()` 配套工具确实是缺口，但它是*运行时行为*变更，有自己的设计问题（什么算「格式错误」？失败时怎么办？），应在独立 Agent Note 中处理，不应捆绑进这次纯类型变更。
+- **带校验的构造**：brand 工厂是纯 cast，无运行时检查，且每个边界（ACP `sessionId`、提供方签发的 `call.id`、`dsh-llm-deepseek` 中的空字符串回退）今天都信任裸 string。一个在边界处对格式错误的输入抛异常的 `SessionId.parse()` / `isValid()` 配套工具确实是缺口，但它是*运行时行为*变更，有自己的设计问题（什么算「格式错误」？失败时会怎样？），应在独立决策中处理，不应捆绑进这次纯类型变更。
 
 ## 验证
 
@@ -65,5 +65,5 @@ export function OwnerToken(id: string): OwnerToken {
 ## 后果
 
 - **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（Service Definition + Service provider + Consumer）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。变更可观察地为纯类型变更——无快照或 e2e 行为差异。它与[统一 agent/会话标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)相邻，因为二者都触及会话 id / owner-token 边界；`OwnerToken` 出于上述解耦理由仍与统一后的 id 保持独立。
-- **Brand 不做校验。** Brand 是混淆防护，不是正确性证明：一个*错误的*会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本 Agent Note 不关闭这个缺口（见「不在范围内」）——它只阻止这类*类别*错误：传入错误*种类*的 id。
-- **「在哪里停下」仍是判断题。** 为 `BashTaskId` 加 brand 但不为 `ToolName` 加，为 `OwnerToken` 加但不为 `ModelId` 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；`brand.ts` 中的策略是裁决依据，本 Agent Note 倾向于面向模型或用于访问控制的 id。
+- **Brand 不做校验。** Brand 是混淆防护，不是正确性证明：一个*错误的*会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本决策不关闭这个缺口（见「不在范围内」）——它只阻止这类*类别*错误：传入错误*种类*的 id。
+- **「在哪里停下」仍是判断题。** 为 `BashTaskId` 加 brand 但不为 `ToolName` 加，为 `OwnerToken` 加但不为 `ModelId` 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；`brand.ts` 中的策略是裁决依据，本决策倾向于面向模型或用于访问控制的 id。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 32db924032..21c6e32e11 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: 71e74e753c39c8eddfe886d69ee9f28edff9ebab
-2026-06-21-mandatory-app-attribution-headers.zh.md: 9cc2c178cd83f3f041282a0dac34b70f78bcc467
+2026-06-21-mandatory-app-attribution-headers.md: 12482ca80d19e5cd1e62b8860865db6cccea61ab
+2026-06-21-mandatory-app-attribution-headers.zh.md: 43f356887948b88d34ba41d46ed1cd2f1c89a1e2
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index 71e74e753c..12482ca80d 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -26,9 +26,9 @@ The immediate prompt came from OpenRouter's [App Attribution](https://openrouter
 
 Provider request attribution is mandatory at the LLM adapter boundary, using the standard `User-Agent` header only. The rule: every product LLM adapter sends a static, non-secret application identity on every provider HTTP request, and every adapter has tests proving that `User-Agent` reaches the wire (a mock server asserting received headers; for a library-backed adapter, the library's header hook feeding the same mock-server assertion).
 
-Do **not** implement OpenRouter app attribution in this Agent Note. `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, and `X-OpenRouter-Categories` are OpenRouter-specific product-surface headers, not provider-neutral model-request attribution. They can be proposed later by an OpenRouter adapter or explicit OpenRouter mode, with its own privacy/product decision, tests, and docs. Until then, even requests pointed at OpenRouter send only the shared `User-Agent` attribution from this Agent Note.
+OpenRouter app attribution is deliberately not implemented. `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, and `X-OpenRouter-Categories` are OpenRouter-specific product-surface headers, not provider-neutral model-request attribution. They can be proposed later by an OpenRouter adapter or explicit OpenRouter mode, with its own privacy/product decision, tests, and docs. Until then, even requests pointed at OpenRouter send only the shared `User-Agent` attribution from this decision.
 
-The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attribution.ts`), not by individual adapters. `AppIdentity` contains only public product facts needed to build `User-Agent`, and the default `APP_IDENTITY` settles the values the proposal left open:
+The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attribution.ts`), not by individual adapters. `AppIdentity` contains only public product facts needed to build `User-Agent`, and the default `APP_IDENTITY` values:
 
 - product token for `User-Agent`: `deepseek-harness` (continuity with the pre-Agent Note wire value and the repo/org identity)
 - version: read from the owning package's manifest via `createRequire`, never a hand-copied constant
@@ -42,7 +42,7 @@ Wire mapping (`attributionHeaders`; header names lowercase in code - HTTP field
 |---|---|
 | All HTTP-based adapters | `User-Agent: {product}/{version} (+{url})` - the parenthesized `+url` comment stays within RFC 9110's conservative product/comment syntax. |
 | Direct DeepSeek endpoint | `User-Agent`; do not send OpenRouter-only headers unless DeepSeek documents an equivalent contract. |
-| OpenRouter endpoints | `User-Agent` only for now. Do not send `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, or `X-OpenRouter-Categories` under this Agent Note. |
+| OpenRouter endpoints | `User-Agent` only for now. Do not send `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, or `X-OpenRouter-Categories` under this decision. |
 | Future providers | `User-Agent` only unless a later provider-specific Agent Note accepts additional headers. Do not reuse `HTTP-Referer` by analogy. |
 
 Endpoint detection is not part of this Agent Note because no endpoint-specific mapping is accepted here. If OpenRouter support lands later, detection must be explicit: either a dedicated OpenRouter provider package or an explicit `provider: 'openrouter'` / `attributionTarget: 'openrouter'` config, not arbitrary path fragments or model names.
@@ -55,13 +55,13 @@ The landed contract:
 - A shared helper (`attributionHeaders` / `userAgent`) constructs the app identity and the standard `User-Agent` value from package metadata, so adapters do not hand-copy version constants.
 - `dsh-llm-deepseek` sends the shared `User-Agent` on every request and its mock-server suite asserts the exact value.
 - `dsh-llm-pi-ai` sends the same `User-Agent` through pi-ai's `StreamOptions.headers` hook and its mock-server suite asserts the exact value.
-- No adapter sends OpenRouter-specific attribution headers (`HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, `X-OpenRouter-Categories`) as part of this Agent Note.
+- No adapter sends OpenRouter-specific attribution headers (`HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, `X-OpenRouter-Categories`) as part of this decision.
 - No app-attribution field carries secrets, local paths, session ids, prompt text, model output, user email, or per-user stable identifiers.
 - The adapter READMEs state the `User-Agent` attribution policy and explicitly avoid documenting OpenRouter app attribution as implemented behavior.
 
 ## Alternatives considered
 
-**OpenRouter app attribution now.** Rejected for this Agent Note. Sending `HTTP-Referer` plus `X-OpenRouter-Title` would satisfy OpenRouter rankings, but those headers are a provider-specific product feature, not the provider-neutral model-request attribution this Agent Note is trying to standardize. Supporting them should be an explicit OpenRouter adapter/mode decision later, not hidden inside the first shared attribution helper.
+**OpenRouter app attribution now.** Rejected for this decision. Sending `HTTP-Referer` plus `X-OpenRouter-Title` would satisfy OpenRouter rankings, but those headers are a provider-specific product feature, not the provider-neutral model-request attribution this decision standardizes. Supporting them should be an explicit OpenRouter adapter/mode decision later, not hidden inside the first shared attribution helper.
 
 **OpenRouter headers everywhere.** Rejected. It would treat a custom OpenRouter contract as a universal standard and send fields with misleading semantics to providers that did not ask for them. It also risks using `HTTP-Referer` as a generic app URL field even though standard HTTP already has `User-Agent` for product identity and `Referer` for a different browsing-context concept.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 9cc2c178cd..43f3568879 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -26,9 +26,9 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 在 LLM 适配器边界，提供方请求归属是强制的，且仅使用标准 `User-Agent` 头部。规则：每个产品级 LLM 适配器在每个提供方 HTTP 请求上发送一个静态、非机密的应用身份，且每个适配器都有测试证明 `User-Agent` 到达了线路（mock 服务器断言收到的头部；对于基于库的适配器，通过库的头部钩子馈入同一个 mock 服务器断言）。
 
-本 Agent Note **不**实现 OpenRouter 应用归属。`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 和 `X-OpenRouter-Categories` 是 OpenRouter 特有的产品展示头部，不是提供方无关的模型请求归属。它们可以后续由 OpenRouter 适配器或显式 OpenRouter 模式提出，附带自己的隐私/产品决策、测试和文档。在此之前，即使请求指向 OpenRouter，也只发送本 Agent Note 定义的共享 `User-Agent` 归属。
+OpenRouter 应用归属刻意未实现。`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 和 `X-OpenRouter-Categories` 是 OpenRouter 特有的产品展示头部，不是提供方无关的模型请求归属。它们可以后续由 OpenRouter 适配器或显式 OpenRouter 模式提出，附带自己的隐私/产品决策、测试和文档。在此之前，即使请求指向 OpenRouter，也只发送本决策定义的共享 `User-Agent` 归属。
 
-提供方无关的身份由 `dsh-llm`（`packages/llm/llm/src/attribution.ts`）拥有，而非各适配器。`AppIdentity` 仅包含构建 `User-Agent` 所需的公开产品事实，默认的 `APP_IDENTITY` 确定了提案中留待决定的值：
+提供方无关的身份由 `dsh-llm`（`packages/llm/llm/src/attribution.ts`）拥有，而非各适配器。`AppIdentity` 仅包含构建 `User-Agent` 所需的公开产品事实，默认的 `APP_IDENTITY` 取值如下：
 
 - `User-Agent` 的产品 token：`deepseek-harness`（与 Agent Note 之前的线路值及仓库/组织身份保持连续性）
 - 版本：通过 `createRequire` 从所属包的 manifest（元数据清单）读取，绝不手动复制常量
@@ -42,7 +42,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 |---|---|
 | 所有基于 HTTP 的适配器 | `User-Agent: {product}/{version} (+{url})`——括号中的 `+url` 注释符合 RFC 9110 保守的 product/comment 语法。 |
 | 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效约定，否则不发送 OpenRouter 特有头部。 |
-| OpenRouter 端点 | 目前仅 `User-Agent`。本 Agent Note 下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
+| OpenRouter 端点 | 目前仅 `User-Agent`。本决策下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
 | 未来提供方 | 仅 `User-Agent`，除非后续提供方特有的 Agent Note 接受额外头部。不要类比复用 `HTTP-Referer`。 |
 
 端点检测不在本 Agent Note 范围内，因为此处不接受任何端点特有的映射。如果后续支持 OpenRouter，检测必须是显式的：要么是专门的 OpenRouter 提供方包，要么是显式的 `provider: 'openrouter'` / `attributionTarget: 'openrouter'` 配置，而非任意路径片段或模型名称。
@@ -55,13 +55,13 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
-- 本 Agent Note 下没有适配器发送 OpenRouter 特有的归属头部（`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title`、`X-OpenRouter-Categories`）。
+- 本决策下没有适配器发送 OpenRouter 特有的归属头部（`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title`、`X-OpenRouter-Categories`）。
 - 没有应用归属字段携带机密、本地路径、会话 id、提示词文本、模型输出、用户邮箱或逐用户的稳定标识符。
 - 适配器 README 声明了 `User-Agent` 归属策略，并明确避免将 OpenRouter 应用归属记录为已实现的行为。
 
 ## 曾考虑的替代方案
 
-**现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
+**现在就实现 OpenRouter 应用归属。** 本决策否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本决策所标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
 
 **向所有提供方发送 OpenRouter 头部。** 否决。这会把一项自定义的 OpenRouter 惯例当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index 4147d8dc12..2824639954 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.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 .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
-2026-06-24-web-capability-seam.md: 3893c9f9d45eac90c9ae381f9fa92ad8c7ae7644
-2026-06-24-web-capability-seam.zh.md: 70745c235d17e3cbf6152c2ef470283b0bad85f2
+2026-06-24-web-capability-seam.md: ccf04420425555055ce3810d25bf764db17322bb
+2026-06-24-web-capability-seam.zh.md: 73f7d0d9b82c03d41bdc768f22b22316e1bc907f
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
index 3893c9f9d4..ccf0442042 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
@@ -327,10 +327,10 @@ Rejected for the seam. `prompt` turns fetch into LLM summarization and couples p
 - SSRF / private-network protection for `web_fetch`: block private, loopback, link-local, multicast, and otherwise non-public destinations so `web_fetch` is not an SSRF primitive. Doing it correctly is more than a URL-string check — it needs DNS-resolve-then-connect-to-the-validated-IP (to defeat DNS rebinding / TOCTOU), per-hop re-validation across redirects, and IPv6 edge handling (private ranges, IPv4-mapped addresses). Neither reference implementation surveyed does IP-level blocking (OpenCode does a prefix check then fetches; Claude Code relies on a centralized hostname blocklist plus a "private URLs will fail" prompt), so there is no implementation to copy and this is the harness's only SSRF defense — it warrants its own focused design/spike. Until it lands, `web_fetch` must only be enabled in deployments that cannot reach sensitive internal targets.
 - A `pdf` `WebFetchBody` kind: the `local-http` provider decodes text-extractable PDFs (best-effort, capped, `truncated`) into a `{ kind: 'pdf'; content; pageCount? }` arm, and `tool-web` renders it. This is fetch, not `web_extract` — PDF retrieval is a concrete HTTP 200 plus deterministic local decoding, not provider-side extraction of a non-HTTP resource. Adding it is a coordinated change across `dsh-web` (declare the arm), the provider (decode + narrow "binary rejection" to "reject binary except text-extractable PDF"; scanned/image PDFs needing OCR stay out of scope), and `tool-web` (render). The closed `WebFetchBody` union makes the consumer side fail to compile until the new arm is handled.
 - Provider-backed extraction as a separate `web_extract` capability, rather than widening `web_fetch` silently.
-- Permission policy integration once the deferred permission system lands.
+- Permission policy integration: the permission system now exists ([sandbox and approval](../feature/2026-07-06-sandbox.md), [web permission presets](../feature/2026-07-23-web-permission-and-approval.md)) but bundles only sandbox mode and approval policy; web permission policy remains unintegrated.
 - Provider-neutral search controls beyond `query` and `maxResults`, once Exa and Perplexity can both honor them honestly.
 
 ## Open questions
 
 - Should product app packages probe web configuration at startup (treating `WEB_PROVIDER_CONFIGURED_MISSING`, `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`, and `WEB_PROVIDER_AMBIGUOUS` as fatal when web is explicitly configured), or leave misconfiguration to surface at the first execution?
-- Where should permission policy for public web access live once the deferred permission system lands: a dedicated web permission plugin on `tools/execute`, provider config, or both?
+- Where should permission policy for public web access live in the shipped permission system ([sandbox and approval](../feature/2026-07-06-sandbox.md), [web permission presets](../feature/2026-07-23-web-permission-and-approval.md)): a dedicated web permission plugin on `tools/execute`, provider config, or both?
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index 70745c235d..73f7d0d9b8 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -329,10 +329,10 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 - `web_fetch` 的 SSRF/私有网络防护：阻断私有、回环、链路本地、多播及其他非公开目的地，使 `web_fetch` 不再是 SSRF 原语。正确实现不仅仅是 URL 字符串检查——需要先 DNS 解析再连接到已验证的 IP（防御 DNS rebinding/TOCTOU）、跨重定向的每跳重新验证，以及 IPv6 边缘处理（私有范围、IPv4 映射地址）。所调研的参考实现均未做 IP 级阻断（OpenCode 做前缀检查后直接 fetch；Claude Code 依赖集中式主机名黑名单加「私有 URL 会失败」的提示词），因此没有可复制的实现，且这是 harness 唯一的 SSRF 防线——值得一次专门的设计/spike。在其落地之前，`web_fetch` 只能在无法触达敏感内部目标的部署中启用。
 - `pdf` `WebFetchBody` 类别：`local-http` 提供方将可文本提取的 PDF 解码（尽力而为、有上限、`truncated`）为 `{ kind: 'pdf'; content; pageCount? }` 分支，`tool-web` 渲染它。这是 fetch 而非 `web_extract`——PDF 获取是具体的 HTTP 200 加确定性的本地解码，不是提供方侧对非 HTTP 资源的提取。添加它是跨 `dsh-web`（声明分支）、提供方（解码 + 将「二进制拒绝」收窄为「拒绝二进制，但可文本提取的 PDF 除外」；需要 OCR 的扫描/图片 PDF 不在范围内）和 `tool-web`（渲染）的协调变更。封闭的 `WebFetchBody` 联合类型使消费方在新分支被处理之前编译失败。
 - 提供方支撑的提取作为独立的 `web_extract` 能力，而非静默扩展 `web_fetch`。
-- 推迟的权限系统落地后的权限策略集成。
+- 权限策略集成：权限系统现已存在（[沙箱与审批](../feature/2026-07-06-sandbox.md)、[web 权限预设](../feature/2026-07-23-web-permission-and-approval.md)），但只捆绑了沙箱模式与审批策略；web 权限策略仍未集成。
 - `query` 和 `maxResults` 之外的提供方无关搜索控制，待 Exa 和 Perplexity 都能诚实遵守时再添加。
 
 ## 开放问题
 
 - 产品应用包是否应在启动时探测 web 配置（当 web 被显式配置时将 `WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE` 和 `WEB_PROVIDER_AMBIGUOUS` 视为致命错误），还是将配置错误留到首次执行时浮出？
-- 推迟的权限系统落地后，公开 web 访问的权限策略应放在哪里：`tools/execute` 上的专用 web 权限插件、提供方配置，还是两者兼有？
+- 在已交付的权限系统（[沙箱与审批](../feature/2026-07-06-sandbox.md)、[web 权限预设](../feature/2026-07-23-web-permission-and-approval.md)）中，公开 web 访问的权限策略应放在哪里：`tools/execute` 上的专用 web 权限插件、提供方配置，还是两者兼有？
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index a8acbaf10e..c2d46de08f 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.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 .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: 353beb2498a310eee8cc794fa5edc22915fd6ad0
-2026-06-26-file-context-as-event-gate.zh.md: 37d7c1e4d971896a0e6ddeb42650635b8f755ca0
+2026-06-26-file-context-as-event-gate.md: 743c8f150a83f2452cb0ff672860b8462a56f762
+2026-06-26-file-context-as-event-gate.zh.md: cd79b44dd3f3b75c5e5addc5be10c02bd1ce0151
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index 353beb2498..743c8f150a 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
@@ -112,7 +112,7 @@ The `fs/*` decision events are **unbound waterfalls dispatched by the tool** (li
 
 ## Tool contract (`dsh-tool-fs`)
 
-The tool keeps its model-facing schemas (`read`/`write`/`edit`, byte-for-byte unchanged) and prompt sections. The prompt guidance stays policy-first because a deployment loading the fs tools is expected to also load `dsh-fs-policy`: the model is still told to read before overwriting or editing, and any wording that says the "backend" requires that should be corrected to say the fs-policy plugin requires it. The bare-provider fallback does not change the prompt stance.
+The tool keeps its model-facing schemas (`read`/`write`/`edit`, byte-for-byte unchanged) and prompt sections. The prompt guidance stays policy-first because a deployment loading the fs tools is expected to also load `dsh-fs-policy`: the model is still told to read before overwriting or editing, and that requirement is the fs-policy plugin's, not the backend's. The bare-provider fallback does not change the prompt stance.
 
 `dsh-tool-fs` gains the executor responsibilities relocated from the old `fileContext` method service, including **read rendering** (`read-render.ts`: `buildWindow` + `formatReadOutput`, `READ_MAX_BYTES`, `READ_MAX_LINE_LENGTH`, `FileReadOutcome`/`FileTextLine`, plus `STREAM_MIN_SIZE` in `read.ts`), which is the tool's rendering detail now that the tool owns the read. Those read-rendering types and helpers move into `dsh-tool-fs`; the policy plugin must not remain a type dependency for the tool.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index 37d7c1e4d9..cd79b44dd3 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -112,7 +112,7 @@ interface Events {
 
 ## 工具约定（`dsh-tool-fs`）
 
-工具保留其面向模型的 schema（`read`/`write`/`edit`，逐字节不变）和提示词段落。提示词引导仍以策略优先，因为加载 fs 工具的部署预期也会加载 `dsh-fs-policy`：模型仍被告知在覆写或编辑前先读取，任何声称「后端」要求如此的措辞应修正为 fs-policy 插件要求如此。裸提供方回退不改变提示词立场。
+工具保留其面向模型的 schema（`read`/`write`/`edit`，逐字节不变）和提示词段落。提示词引导仍以策略优先，因为加载 fs 工具的部署预期也会加载 `dsh-fs-policy`：模型仍被告知在覆写或编辑前先读取，而该要求来自 fs-policy 插件，并非后端。裸提供方回退不改变提示词立场。
 
 `dsh-tool-fs` 获得从旧 `fileContext` 方法服务迁移来的执行器职责，包括**读取渲染**（`read-render.ts`：`buildWindow` + `formatReadOutput`、`READ_MAX_BYTES`、`READ_MAX_LINE_LENGTH`、`FileReadOutcome`/`FileTextLine`，以及 `read.ts` 中的 `STREAM_MIN_SIZE`），这些现在是工具的渲染细节，因为读取已由工具拥有。这些读取渲染类型和辅助函数移入 `dsh-tool-fs`；策略插件不得继续作为工具的类型依赖。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
index 8201388c72..a1fac69cf4 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 1c2cfc4257e93b2f2f126947e93b38aa2d4cd570
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 050f604259033f20be8174754c32f624e9a0ce76
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: d8193b47ff16da7efb5f6bf1c3f34c0e1251572c
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 7f5bb62d92f27c49b0f7f262dc64dce39c89f2cd
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
index 1c2cfc4257..d8193b47ff 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md)
 
 ## Problem
 
-The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.bash` capability seam ([dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This Agent Note adds those two inputs.
+The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.bash` capability seam ([dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This change adds those two inputs.
 
 `stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these Service Definition fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
index 050f604259..7f5bb62d92 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令：钩子是一条 shell 命令，通过 **stdin 上的 JSON** 接收事件载荷，并从若干**环境变量**（`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……）读取上下文。harness 已经在 `ctx.bash` 能力 seam 后面有一个完善的命令执行器（[dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)），具备进程组终止、输出截断/溢出处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程管道——但该 seam 此前无法写入 stdin 或设置额外 env。本 Agent Note 添加这两个输入。
+钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令：钩子是一条 shell 命令，通过 **stdin 上的 JSON** 接收事件载荷，并从若干**环境变量**（`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……）读取上下文。harness 已经在 `ctx.bash` 能力 seam 后面有一个完善的命令执行器（[dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)），具备进程组终止、输出截断/溢出处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程管道——但该 seam 此前无法写入 stdin 或设置额外 env。本次变更添加这两个输入。
 
 `stdin` 和 `env` 不构成新的模型能力，因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护，而非靠隐藏这些 Service Definition 字段；模型工具参数是静态 JSON，不会展开 shell 变量。因此这些字段服务于受信的进程内调用方（如钩子桥接层），它们需要传递结构化输入和 `CLAUDE_*` 变量，而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.md)。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index fab7f4d6d6..8916c347d9 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.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 .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
-2026-06-30-event-domain-semantics.md: a3af693126b71c5844260f53c62b4ab4a28fe56f
-2026-06-30-event-domain-semantics.zh.md: 1f6df779fdccb921861f6ea848e33d9cd866b027
+2026-06-30-event-domain-semantics.md: dbb3ef49979b7eeaa9a43b7db4a2d5a5839b5569
+2026-06-30-event-domain-semantics.zh.md: 93fe14adeaa47d276219a316ff1250a9982f5f14
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
index a3af693126..dbb3ef4997 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
@@ -12,7 +12,7 @@ The harness extends the agent loop through a Cordis event taxonomy (see [the mic
 - `agent/*` carries live runtime signals that hand a plugin the `Agent` handle.
 - `tools/*` carries the tool registry and execution pipeline.
 
-Two problems motivated pinning the semantics down. First, several turn/step boundaries existed BOTH as a durable `SessionEvent` (`turn/start`, `turn/end`, `step/start`, `step/end`) AND as a mirrored `agent/*` emit (`agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end`). A consumer had two sources of truth for the same fact, and every lifecycle change had to update both. Second, the upcoming Hooks subsystem needs ONE coherent, documented surface to subscribe to — a plugin author (and the Claude Code / Codex hook bridges built on top) must know, without reading the loop, whether to listen on a session event or an agent event, and why.
+Two problems motivated pinning the semantics down. First, several turn/step boundaries existed BOTH as a durable `SessionEvent` (`turn/start`, `turn/end`, `step/start`, `step/end`) AND as a mirrored `agent/*` emit (`agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end`). A consumer had two sources of truth for the same fact, and every lifecycle change had to update both. Second, the Hooks subsystem needs ONE coherent, documented surface to subscribe to — a plugin author (and the Claude Code / Codex hook bridges built on top) must know, without reading the loop, whether to listen on a session event or an agent event, and why.
 
 This vocabulary is the foundation for interception decisions, the durable `hook/*` log, and the Claude Code and Codex bridges.
 
@@ -34,6 +34,6 @@ This vocabulary is the foundation for interception decisions, the durable `hook/
 - Tests that observed boundaries via the removed emits now observe the durable `turn/start`/`turn/end`/`step/start`/`step/end` session events — the behavior they pin (boundary ordering, step counting) is unchanged; only the feed they read moved to the canonical one. The tests that exercised a *throwing turn-boundary emit listener* were deleted, because that code path no longer exists (there is no emit to throw from). Per [AGENTS.md "tests document behavior, not golden truth"](../../../../AGENTS.md), the behavior and its test moved (or died) together.
 - The loop marks the step open (`stepOpen = true`) only after `append('step/start')` returns. Internal dispatch validation runs before the log push and may reject without opening a step; post-commit `session/event` observer failures are contained inside `Session.append`. The marker therefore represents exactly the committed boundary that owes a later `step/end`.
 - The full realization of this is [the simplification Agent Note "Stop mirroring durable boundaries as agent events"](../simplification/2026-06-20-remove-agent-boundary-mirror-events.md): all four boundary mirrors are removed and every consumer reads boundaries off `session/event`. `agent/steering` (not a boundary mirror) stayed outside that Agent Note's scope and was removed by its own follow-up, [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md) — it mirrored the durable mid-turn steering `user/message`.
-- The cordis events catalog (`docs/cordis-catalog/events.md`) is regenerated to drop the mirror events.
+- The generated cordis event surface (the `docs/subsystems/` pages) no longer lists the mirror events.
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
index 1f6df779fd..93fe14adea 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -12,7 +12,7 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 - `agent/*` 承载运行时实时信号，向插件传递 `Agent` 句柄。
 - `tools/*` 承载工具注册表与执行流水线。
 
-两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `SessionEvent`（`turn/start`、`turn/end`、`step/start`、`step/end`）和镜像的 `agent/*` emit（`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`）存在。消费方对同一事实有两个真源，每次生命周期变更都必须同时更新两处。第二，即将到来的钩子子系统需要一个连贯且有文档的订阅表面——插件作者（以及基于其上构建的 Claude Code / Codex 钩子桥接）必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件，以及原因。
+两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `SessionEvent`（`turn/start`、`turn/end`、`step/start`、`step/end`）和镜像的 `agent/*` emit（`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`）存在。消费方对同一事实有两个真源，每次生命周期变更都必须同时更新两处。第二，钩子子系统需要一个连贯且有文档的订阅表面——插件作者（以及基于其上构建的 Claude Code / Codex 钩子桥接）必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件，以及原因。
 
 这套词汇是拦截决策、持久的 `hook/*` 日志，以及 Claude Code 和 Codex 桥接的基础。
 
@@ -34,6 +34,6 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 - 之前通过已移除 emit 观察边界的测试，现在观察持久的 `turn/start`/`turn/end`/`step/start`/`step/end` 会话事件——它们所锁定的行为（边界顺序、步骤计数）不变；只是读取的源移到了规范源。那些测试*抛出异常的轮次边界 emit 监听器*的用例被删除，因为该代码路径不再存在（没有 emit 可供抛出）。按照 [AGENTS.md「测试记录行为，而非黄金真相」](../../../../AGENTS.md)，行为与其测试一同迁移（或一同消亡）。
 - 循环仅在 `append('step/start')` 返回后才标记步骤已打开（`stepOpen = true`）。内部分发校验在日志推入之前运行，可能在不打开步骤的情况下拒绝；post-commit `session/event` observer 的失败被隔离在 `Session.append` 内部。因此该标记精确表示已提交的、欠一个后续 `step/end` 的边界。
 - 完整实现见[简化 Agent Note「停止将持久边界镜像为 agent 事件」](../simplification/2026-06-20-remove-agent-boundary-mirror-events.md)：全部四个边界镜像被移除，所有消费方从 `session/event` 读取边界。`agent/steering`（不是边界镜像）不在该 Agent Note 范围内，由其后续 Agent Note [移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md) 单独移除——它镜像的是持久的中途 steering `user/message`。
-- Cordis 事件目录（`docs/cordis-catalog/events.md`）重新生成以移除镜像事件。
+- 生成的 cordis 事件表面（`docs/subsystems/` 各页）不再列出镜像事件。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index b242af54ee..759fecb3b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.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 .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
-2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 199153741a5677e9f7b9bc6510f7a77b9791343e
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 988c128382fd8ff5a8a4742486860d931013ac80
+2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 8f8b40a44314fc6add97842d48273e49927f92e2
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 6fc71e2ab866822cee389c0c54efe1731847cbb7
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
index 199153741a..8f8b40a443 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
@@ -46,9 +46,9 @@ Per-tool semantics and selection guidance live in tool descriptions. Prompt sect
 
 - **The loop composes an identity line itself** — hardcodes model-facing prose in the one package that must stay thin ("plugins, not loop changes"), and outside the section pipeline it would be a second composition path. (The identity DOES ship as a code literal — but as an ordinary section registered by `dsh-system-prompt`, whose `system-prompt/assemble` waterfall remains the escape valve for a deployment that must drop it.)
 - **Inject the model name via the `agent/request` waterfall** — prompt text would be composed in two places and the earlier rendered persona could disagree with the final routed header. The request plugin that owns late routing must also own any earlier prompt claim about that model.
-- **Hand-write the model name in each persona** — duplicates the `model:` key one line above and silently lies after a config edit; the exact disease this Agent Note cures.
+- **Hand-write the model name in each persona** — duplicates the `model:` key one line above and silently lies after a config edit; the exact disease this decision cures.
 - **Lenient interpolation (leave unknown refs verbatim, or substitute empty)** — a typo ships `{{modle}}` (or a hole) to the model and nobody notices until transcript review.
-- **Per-instance subagent wording in config** — returns model-facing prose to every deployment × instance, the P2 disease again. **Keying wording off the provider NAME** — `providerName` is itself config, so a renamed provider silently gets the wrong words.
+- **Per-instance subagent wording in config** — returns model-facing prose to every deployment × instance, reviving the hand-written-guidance-in-leaf-YAML drift. **Keying wording off the provider NAME** — `providerName` is itself config, so a renamed provider silently gets the wrong words.
 - **Resolving the provider at `apply` time (a load-order requirement)** and **section-only subagent wording (lazily resolved at assemble)** — the alternatives to the provider-lifecycle events; both rejected in [the provider-lifecycle-events Agent Note](2026-07-05-subagent-provider-lifecycle-events.md).
 
 ## Out of scope
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 988c128382..6fc71e2ab8 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -46,9 +46,9 @@ Status: implemented
 
 - **循环自行组合一行 identity 文本**：在必须保持精简的那个包（「用插件，不改循环」）中硬编码面向模型的行文，且在 section 流水线之外构成第二条组合路径。（identity 确实以代码字面量交付——但作为 `dsh-system-prompt` 注册的普通 section，其 `system-prompt/assemble` waterfall 仍是部署需要移除它时的逃生阀。）
 - **通过 `agent/request` waterfall 注入模型名称**：提示词文本会在两处组合，更早渲染的 persona 也可能与最终已路由 header 不一致。拥有延迟路由的请求插件还必须拥有该模型在提示词中更早出现的声明。
-- **在每个 persona 中手写模型名称**：与上方一行的 `model:` 键重复，配置修改后静默失实；正是本 Agent Note 要治愈的病症。
+- **在每个 persona 中手写模型名称**：与上方一行的 `model:` 键重复，配置修改后静默失实；正是本决策要治愈的病症。
 - **宽松插值（未知引用保留原样或替换为空）**：一个拼写错误 `{{modle}}`（或一个空洞）会被发送给模型，直到 transcript（文本记录）审查时才会被发现。
-- **在配置中为每个 subagent 实例编写措辞**：面向模型的行文回到每个部署 × 实例中，重蹈 P2 病症。**根据提供方名称选择措辞**：`providerName` 本身是配置，重命名提供方后会静默获得错误的措辞。
+- **在配置中为每个 subagent 实例编写措辞**：面向模型的行文回到每个部署 × 实例中，重蹈在 leaf YAML 中手写指导的漂移。**根据提供方名称选择措辞**：`providerName` 本身是配置，重命名提供方后会静默获得错误的措辞。
 - **在 `apply` 时解析提供方（加载顺序要求）**与**仅用 section 承载 subagent 措辞（在 assemble 时惰性解析）**：提供方生命周期事件的替代方案；两者均在[提供方生命周期事件 Agent Note](2026-07-05-subagent-provider-lifecycle-events.md)中被否决。
 
 ## 不在范围内
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index b85c732f6e..54935a491e 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: c971f411eb932cab29d7a52662a0e05a1f638daa
-2026-07-05-reconstructable-requests.zh.md: b788f895cbb33f6ffa59b36430e81384a468f582
+2026-07-05-reconstructable-requests.md: c13e40b5b22e5d6fe19f6b5bd137db3a48350390
+2026-07-05-reconstructable-requests.zh.md: 746bcd37dabada949873d394776c1ca43eff4ea2
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index c971f411eb..c13e40b5b2 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -50,6 +50,6 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 - Model-visible context uses logged message channels. `agent.inject()` and tool `additionalContexts` enter the inbox for a later claim, while `agent/pre-step` returns context that must settle with the current claimed batch. Each entered value is a durable sourced `user/message`, paid once and prefix-cached thereafter at the price of accumulating in history until compaction.
 - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replacement entry), a real prompt, tool, or config change (`request/header` with reason `change`), or a process boundary with drift (a differing `resume` snapshot). The provider's own reasoning-content exclusion is managed server-side.
 - `agent/pre-step` is the current-request message channel; direct inbox mutation is the eventual later-request channel.
-- Tool-result trimming (planned) needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
+- Tool-result trimming needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
 - Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated.
 - Snapshot expected outputs changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index b788f895cb..746bcd37da 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -50,6 +50,6 @@ Status: implemented
 - 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价并在后续成为可缓存前缀，代价是会在历史中累积直至压缩。
 - 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
 - `agent/pre-step` 是当前请求的消息通道；直接修改 inbox 则是最终进入后续请求的通道。
-- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
+- 工具结果裁剪无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index c85785a097..fa9304ec09 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.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 .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: 72f02208f601ff5514fe6ea0006ea922cdbd49b7
-2026-07-06-timeout-deadline-library.zh.md: c4da7f2028abc32d0c393dd1aeb3c59a4c05acec
+2026-07-06-timeout-deadline-library.md: b7c7ac07ce0acec819fa7e88b32b3b6d624f3e6e
+2026-07-06-timeout-deadline-library.zh.md: e4ec6b9a9e07b55faf9f44f2b99b765620e626c4
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index 72f02208f6..b7c7ac07ce 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
@@ -98,12 +98,12 @@ The signal only *notifies*; termination is always the listener's job, and the li
 ## Consequences
 
 - `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the Service Definition type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched.
-- `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate.
+- `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. An always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
 - Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. Adapters that can observe out-of-band transport activity may pulse an outstanding demand; suppressed activity remains invisible to the watchdog. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
 
-Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; future ripgrep-backed fs discovery tools can consume the same provider-owned deadline shape once they exist; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.
+Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; the ripgrep-backed fs discovery tools ([packaged ripgrep search](2026-08-01-packaged-ripgrep-search.md)) consume the same provider-owned deadline shape through `dsh-timeout-policy` and `exec.signal`; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index c4da7f2028..e4ec6b9a9e 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -98,12 +98,12 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 ## 后果
 
 - `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，Service Definition 类型 `BashRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。
-- `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
+- `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
 - 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。能够观察到带外传输活动的适配器可以对尚未结算的 demand 调用 `pulse()`；被屏蔽的活动对 watchdog 仍不可见。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
 
-以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在实现后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
+以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；基于 ripgrep 的文件系统发现工具（[打包的 ripgrep 搜索](2026-08-01-packaged-ripgrep-search.md)）通过 `dsh-timeout-policy` 和 `exec.signal` 消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index 36484da590..4ac6aa8cdd 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.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 .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
-2026-07-07-tool-call-timeout-policy.md: d341a2c598765b6de4d2a7e242f38847e48f081b
-2026-07-07-tool-call-timeout-policy.zh.md: 6d10b552b951f428f475323ba115007e39b66aaf
+2026-07-07-tool-call-timeout-policy.md: f17834332b2e661b6811c2264d5e8de4e1642663
+2026-07-07-tool-call-timeout-policy.zh.md: 3be8614f209b2896f0754cadd868f6e66b78f834
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index d341a2c598..f17834332b 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -85,7 +85,7 @@ No new session event is needed for reconstructability: `TOOL_TIMEOUT` is the fin
 
 `read`, `write`, `edit`, `todo_write`, `task_list`, and `task_kill` do not opt into tool-call timeout. `task_output` owns its bounded wait because a wait timeout is a successful live-status result, not a tool failure.
 
-A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and declares its own `timeoutMs` (from its plugin's config) for the enforcer to apply. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is outside this cut.
+A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and declares its own `timeoutMs` (from its plugin's config) for the enforcer to apply. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is a separate decision.
 
 ## Alternatives considered
 
@@ -111,4 +111,3 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit
 - Multiple `tools/execute` listeners compose by ordinary Cordis waterfall order: a listener that calls `next()` wraps downstream listeners plus dispatch; one that returns without `next()` short-circuits them. A deployment combining timeout with a future retry/sandbox/metrics wrapper chooses semantics by registration order ("timeout covers the whole retry" vs "timeout covers each attempt").
 - Opt-in by declaration is a deliberate misconfiguration risk: a tool can declare a `timeoutMs` without honoring `exec.signal`, and that tool will not stop on timeout. The registry awaits that non-quiescent body rather than racing it, while the plugin contract states that declaring a budget means cooperative; the web tools prove the pattern on tools that already forward the signal.
 - During the transition `bash` and the migrated web tools use different timeout paths on purpose: `TOOL_TIMEOUT` is the model-facing tool-call budget, while `BASH_TIMEOUT` remains the bash backend timeout used by bash and hooks.
-- Deviation from the literal proposal, recorded per the implemented-Agent Note rule: the plugin package is `@deepseek-ai/dsh-timeout-policy` (not `tool-timeout`), signal replacement is in-place `exec.signal` mutation before `next()` (not `next({ ...exec, signal })`, which cordis ignores), and the per-tool budget is declared on the `ToolDefinition` (`timeoutMs`, set by the owning tool plugin from its config) rather than mapped by tool name in this plugin's config — so the enforcer is zero-config and a mistyped tool name is impossible. All three are described in `## Decision` above.
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index 6d10b552b9..3be8614f20 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -85,7 +85,7 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 `read`、`write`、`edit`、`todo_write`、`task_list` 和 `task_kill` 不加入工具调用超时。`task_output` 自己拥有有界等待，因为等待超时是成功的实时状态结果，而非工具失败。
 
-未来面向模型的 grep/glob 工具可以基于 `ctx.bash` 实现而无需导入 `@deepseek-ai/dsh-timeout`：它将 `exec.signal` 转发给 `ctx.bash`，并声明自己的 `timeoutMs`（来自其插件配置）供执行器应用。如果 bash-local 的后端超时对这类工具造成问题，bash seam 可以后续添加调用方自有截止模式；这不在本次范围内。
+未来面向模型的 grep/glob 工具可以基于 `ctx.bash` 实现而无需导入 `@deepseek-ai/dsh-timeout`：它将 `exec.signal` 转发给 `ctx.bash`，并声明自己的 `timeoutMs`（来自其插件配置）供执行器应用。如果 bash-local 的后端超时对这类工具造成问题，bash seam 可以后续添加调用方自有截止模式；那是一项独立的决策。
 
 ## 曾考虑的替代方案
 
@@ -111,4 +111,3 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 - 多个 `tools/execute` 监听器按普通 Cordis waterfall 顺序组合：调用 `next()` 的监听器包装下游监听器加分发；不调用 `next()` 直接返回的监听器短路它们。一个同时组合超时与未来重试/沙箱/指标包装器的部署通过注册顺序选择语义（「超时覆盖整个重试」vs「超时覆盖每次尝试」）。
 - 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件约定声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
 - 过渡期间 `bash` 和已迁移的 web 工具有意使用不同的超时路径：`TOOL_TIMEOUT` 是面向模型的工具调用预算，而 `BASH_TIMEOUT` 仍是 bash 和钩子使用的 bash 后端超时。
-- 与字面提案的偏差，按 implemented-Agent Note 规则记录：插件包为 `@deepseek-ai/dsh-timeout-policy`（而非 `tool-timeout`）；信号替换是在 `next()` 之前就地修改 `exec.signal`（而非 `next({ ...exec, signal })`，Cordis 会忽略后者）；逐工具预算声明在 `ToolDefinition` 上（`timeoutMs`，由拥有该工具的插件从其配置中设置），而非在本插件配置中按工具名映射——因此执行器是零配置的，拼错工具名不可能发生。以上三点均在上文 `## Decision` 中描述。
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index aa1d2c9d6f..8bef07d042 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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 .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: fe09e1b83f4f0a9f867f78351f643b1bd26d7c9d
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 0279e0cf032928e96bad9da02340cae753a0927f
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: a45678c9bb5fcae340ff7134687890879f56c630
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: f1fccc508471356dd6434da0e126ed38f15ed3ba
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index fe09e1b83f..a45678c9bb 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -76,7 +76,7 @@ Manual-driving caveat: the bin treats stdin EOF as "the client is gone" and disp
 
 **jsonrpc-agent carrying the full closure dependencies.** The app bin would declare 53+ dependencies it never imports — a "packaging manifest" masquerading as real dependency relationships — and would force constraints to open two exceptions for it, cordis-in-dependencies and a files wildcard. With the closure manifest landing on the python-side manifest package, constraints needs no exception at all and the bin keeps the normal package shape isomorphic to acp-agent.
 
-**An open plugin set (loading user plugins from disk).** This round ships a closed set; the PoC incidentally confirmed that on-disk ESM import outside the VFS works (through the `ctx.baseUrl` relative-path channel). It is listed as a future evolution, which must separately solve sharing the cordis instance inside the exe with external plugins.
+**An open plugin set (loading user plugins from disk).** The shipped set is closed; the PoC incidentally confirmed that on-disk ESM import outside the VFS works (through the `ctx.baseUrl` relative-path channel). It is listed as a future evolution, which must separately solve sharing the cordis instance inside the exe with external plugins.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index 0279e0cf03..f1fccc5084 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -76,7 +76,7 @@ exe 内支持 `dsh-workflow-workerthread` 与 `dsh-code-runtime-worker`。两个
 
 **让 jsonrpc-agent 承担完整闭包依赖。** 应用入口将声明 53 个以上自身并不 `import()` 的依赖，使「打包 manifest」伪装成真实依赖关系，还会迫使 `constraints` 为其增加 `cordis-in-dependencies` 与 `files` 通配符两个例外。将闭包清单放在 Python 侧的 manifest 包后，`constraints` 不需要任何例外，`bin` 也能保持与 acp-agent 同构的正常包形状。
 
-**开放插件集（从磁盘加载用户插件）。** 本期采用封闭集；PoC 同时证实，可以通过 `ctx.baseUrl` 相对路径通道从 VFS 外的磁盘 `import()` ESM。该能力列为后续演进，届时还需解决外部插件与 exe 内 Cordis 实例的共享问题。
+**开放插件集（从磁盘加载用户插件）。** 交付的集合是封闭的；PoC 同时证实，可以通过 `ctx.baseUrl` 相对路径通道从 VFS 外的磁盘 `import()` ESM。该能力列为后续演进，届时还需解决外部插件与 exe 内 Cordis 实例的共享问题。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index 03b17f5f33..91c9baf2a0 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 65d547a51568cca43fd8b2887bfe9a61c512b34d
-2026-07-15-lsp-capability-seam.zh.md: a9dcedaa80742bb338dbca4c0c532ca6e7cb2655
+2026-07-15-lsp-capability-seam.md: a461432fe5f218ea6c3ff3e031b52f7ebffbd7a5
+2026-07-15-lsp-capability-seam.zh.md: bfbd8d04f71b154d2833c86f2a6dc84d7e13fff4
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 65d547a515..a461432fe5 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -32,7 +32,7 @@ The prompt positions LSP as a precision aid: `Use search/read for ordinary navig
 
 The seam exposes one `query(request, signal?)` operation because no fields need implementation defaulting: `workspaceRoot` is required, `languageId` comes from the registration, and consumers own timeouts and result limits. `query()` selects and derives without hidden `??` fallbacks, leaving no executable spec to resolve. `dsh-tool-lsp` validates model arguments and passes only `exec.signal` as a bare `AbortSignal`, matching web and keeping `dsh-lsp` independent of `dsh-tools`. Removal before selection fails as unavailable; later disposal follows the selected provider's cancellation lifecycle without rerouting.
 
-The intended contract shape is:
+The contract shape:
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -147,7 +147,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 
 ## Alternatives considered
 
-**Copy Claude Code's unified schema.** Its cursor operations validate the core use case, but symbols and call hierarchy need different arguments. Copying all nine operations would freeze speculative surface, so the proposal aligns only on the four semantic queries.
+**Copy Claude Code's unified schema.** Its cursor operations validate the core use case, but symbols and call hierarchy need different arguments. Copying all nine operations would freeze speculative surface, so the seam aligns only on the four semantic queries.
 
 **Let providers register tools.** Loaded servers would then control model schema and prompts, preventing one stable contract across local and remote providers.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index a9dcedaa80..bfbd8d04f7 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -32,7 +32,7 @@ harness 已具备文本搜索与文件读取能力，但二者都无法识别程
 
 服务边界只公开 `query(request, signal?)`，因为没有字段需要实现层填充默认值：`workspaceRoot` 是必填项，`languageId` 来自注册映射，超时与结果限制由消费方负责。`query()` 执行选择与推导时不使用隐藏的 `??` 后备逻辑，因此没有需要 resolve 的可执行 spec。`dsh-tool-lsp` 校验模型参数，并只把 `exec.signal` 作为裸 `AbortSignal` 传递，与 web 一致，并使 `dsh-lsp` 不依赖 `dsh-tools`。提供方在选择前被移除时按不可用失败；之后的释放遵循已选提供方的取消生命周期，不改路由。
 
-预期约定如下：
+约定如下：
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -147,7 +147,7 @@ interface LspToolInput {
 
 ## 备选方案
 
-**照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景，但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口，因此本提案只对齐四种语义查询。
+**照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景，但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口，因此该 seam 只对齐四种语义查询。
 
 **允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词，无法在本地与远程提供方之间维持统一约定。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 4632c7e1ac..bf20616836 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: ebab36e66768f6216603923d2313e77eaf412ae1
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 308446e48772c3bb8d6e0b5851dd526af641593a
+2026-07-19-gui-layering-and-rpc-protocol.md: f3aea8360ea1db9b29da01f143daf30cd969b0e5
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 27b5401960a31ee3cedf2366d3b7f4efc527d482
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index ebab36e667..f3aea8360e 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-19-gui-layering-and-rpc-protocol.zh.md)
 
-> Division of labor: this document = the layering model + the channel-independent RPC protocol; the protocol's Web implementation combines HTTP uplink with the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md), while the browser object layer is in the [web client architecture RFC](2026-07-19-gui-web-client-architecture.md).
+> Division of labor: this document = the layering model + the channel-independent RPC protocol; the protocol's Web implementation combines HTTP uplink with the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md), while the browser object layer is in the [web client architecture note](2026-07-19-gui-web-client-architecture.md).
 
 ## Problem
 
@@ -25,7 +25,7 @@ Directories layer as follows:
 
 - `packages/host/*`: packages provide host-side capability only (representing the Node.js engineering core built on the existing harness plugin system), and additionally
     - the unified backend protocol (fetch, HTTP, streaming interfaces…) — definitions and support, see the "Message protocol" sections below
-- `packages/client/*`: packages provide client-side capability only; every package stays single-sided. Three kinds live here (the axes are owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md)):
+- `packages/client/*`: packages provide client-side capability only; every package stays single-sided. Three kinds live here (the axes are owned by the [client plugin loading note](2026-07-23-client-plugin-loading-model.md)):
     - **Pure libraries** (`ui-slots`, `web-react`, `ui-primitives`, plus the `loader` kernel package): ordinary root-index packages, statically bundled into the shell; the first three are seeded into the module table.
     - **Static-arrival entry packages** (`connection`, `runtime`, `ui-theme`, `i18n`, `hmr`): no `dshClient` key and no browser bundle — the shell bundles their `src/client/` half and registers it with `ctx.modules`; they are governed as entries of the host-authored graph like everything else.
     - **Fetch-arrival plugin packages** (`ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the implementation lives under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle). Cross-plugin consumption of `/client` is type-only; value cooperation goes through cordis services.
@@ -52,7 +52,7 @@ Direction discipline (every rule auditable from package deps):
 - `runtime → apiproxy` is one-way; apiproxy depends only on type definitions.
 - Client-side packages **never import** host-side package runtime (they consume only the two browser-safe subpaths `/api` and `/client`).
 - `webserver` does not depend on `runtime`: it provides a `{ fetch }`-shaped implementation — "webserver ← runtime" is a runtime injection relationship, not a package dependency.
-- Cross-package client imports use the `/client` subpath for plugin packages, and between plugin packages they are type-only — a cross-plugin value import is a build error at the tsdown purity gate (value cooperation goes through cordis services; the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md) owns the edge rules).
+- Cross-package client imports use the `/client` subpath for plugin packages, and between plugin packages they are type-only — a cross-plugin value import is a build error at the tsdown purity gate (value cooperation goes through cordis services; the [client plugin loading note](2026-07-23-client-plugin-loading-model.md) owns the edge rules).
 
 TypeScript checks in **two aggregate programs** referenced by a solution root (`tsconfig.json` = solution; `tsconfig.host.json` = host side + tests, excluding `packages/client`; `tsconfig.client.json` = client packages and their tests): both sides merge the cordis `Context` interface under the same keys (`sessions`, `loader`) with different services, so one program would see both declaration merges and report a collision. Shared leaves (session/llm/tools/apiproxy…) build once and are referenced by both programs ([topology](../process/2026-07-22-tsconfig-solution-root-two-aggregates.md)).
 
@@ -66,7 +66,7 @@ On the protocol side: TS interfaces (`packages/host/apiproxy/src/api/`, zero Nod
 | Assembly layer | `dsh-host-runtime` | Plugin composition + ApiProxy integration + the web UI plugin mount (in-memory Loader tree over the eight dshClient packages); home of host-level configuration (defaults/persistenceRoot, future user profile) | Which plugins mount and with what defaults is decided only here; shells must not alter the assembly |
 | Carrier layer | `dsh-host-webserver` | Web-shape HTTP and upgrade: static serving + `/api/*`→handler forwarding + WebSocket upgrade route + close semantics; plugin bundle endpoint + `__DSH_BOOT__` manifest injection (fed by the web plugin registry) | Web (browser access) only; zero workspace dependencies (the registry arrives by structural injection); Electron does not reuse it |
 | Client libraries | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | Slot registry core / ctx↔React glue / pure React atoms | Zero cordis runtime dependency in components; seeded into the loader module table by the shell |
-| Client plugins | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | Browser-side cordis plugin tree (wire consumer, core services, theme, i18n, layout, sidebar, conversation, trajectory) — see the web client architecture RFC | Dual entry (node half = empty apply; implementation in `src/client/`); the consumption face goes exclusively through ApiProxy |
+| Client plugins | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | Browser-side cordis plugin tree (wire consumer, core services, theme, i18n, layout, sidebar, conversation, trajectory) — see the web client architecture note | Dual entry (node half = empty apply; implementation in `src/client/`); the consumption face goes exclusively through ApiProxy |
 | Application shape | `@deepseek-ai/dsh` (apps/cli) + `dsh-frontend` (apps/web, the vite application) | Coarse bin dispatch + one assembly module per shape (web.ts / headless.ts); the vite app is a thin main over the `dsh-client-web` shell surface | Shapes dynamic-import so they never load each other; workspace knowledge like dist location stays in the app |
 
 #### Naming rule
@@ -218,11 +218,11 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 | `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
-| (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
+| IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
 
 ## How to extend (operational checklists)
 
-**Add a unary method (5 steps)**: ① add the method signature to the domain interface (parameters/return inline — this is the single source of truth); ② add one `RpcMethodMap` row; ③ add the request/value schema pair in `<domain>.schema.ts` (anchored `Wire<RequestPayload<'…'>>`); ④ add one handler `UNARY_ROUTES` row (the handler's Web carriage is in the web client architecture RFC); ⑤ implement in the impl (echo `request.rpcId`). On the client side, add the passthrough row to the `IApiClient`/`AbstractApiClient` domain method tables.
+**Add a unary method (5 steps)**: ① add the method signature to the domain interface (parameters/return inline — this is the single source of truth); ② add one `RpcMethodMap` row; ③ add the request/value schema pair in `<domain>.schema.ts` (anchored `Wire<RequestPayload<'…'>>`); ④ add one handler `UNARY_ROUTES` row (the handler's Web carriage is in the web client architecture note); ⑤ implement in the impl (echo `request.rpcId`). On the client side, add the passthrough row to the `IApiClient`/`AbstractApiClient` domain method tables.
 
 **Add a frame type (3 steps)**: ① add a branch to the `MuxFrame`/`HostFrame` union (answerable frames must note the stable-rpcId semantics); ② add a frame-schema branch; ③ the consumers' fold/routing documented-default already covers unknown types — add an explicit branch as needed.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 308446e487..27b5401960 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-19-gui-layering-and-rpc-protocol.md) | 中文
 
-> 分工线：本篇 = 分层模型 + 通道无关的 RPC 协议；协议的 Web 实现由 HTTP 上行加 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md)组成，浏览器对象层见 [Web 客户端架构 RFC](2026-07-19-gui-web-client-architecture.md)。
+> 分工线：本篇 = 分层模型 + 通道无关的 RPC 协议；协议的 Web 实现由 HTTP 上行加 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md)组成，浏览器对象层见 [Web 客户端架构笔记](2026-07-19-gui-web-client-architecture.md)。
 
 ## Problem
 
@@ -23,7 +23,7 @@ Status: implemented
 目录按照如下分层：
 - `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
-- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）：
+- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载笔记](2026-07-23-client-plugin-loading-model.md) 所有）：
     - **纯库**（`ui-slots`、`web-react`、`ui-primitives`，外加内核包 `loader`）：普通根入口包，静态打包进壳；前三者播种进模块表。
     - **静态到达 entry 包**（`connection`、`runtime`、`ui-theme`、`i18n`、`hmr`）：无 `dshClient` 键、无浏览器 bundle——壳把它们的 `src/client/` 半边打进自己的 bundle 并向 `ctx.modules` 登记；它们与其余单元一样，作为 host 独家撰写的图里的 entry 受治理。
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
@@ -50,7 +50,7 @@ harness core packages ──────────────────┘
 - `runtime → apiproxy` 单向；apiproxy 仅依赖类型定义。
 - client 侧包**永不 import** host 侧包的运行时（只吃 `/api`、`/client` 两个浏览器安全子路径）。
 - `webserver` 不依赖 `runtime`：它提供 `{ fetch }` 特定实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
-- client 侧跨包 import 插件包一律走 `/client` 子路径，且插件包之间只限类型 import——跨插件值 import 在 tsdown 纯度门禁处即构建错误（值层面的协作走 cordis 服务；边规则归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）。
+- client 侧跨包 import 插件包一律走 `/client` 子路径，且插件包之间只限类型 import——跨插件值 import 在 tsdown 纯度门禁处即构建错误（值层面的协作走 cordis 服务；边规则归 [client 插件装载笔记](2026-07-23-client-plugin-loading-model.md) 所有）。
 
 TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.json` = solution；`tsconfig.host.json` = host 侧 + 测试，排除 `packages/client`；`tsconfig.client.json` = client 各包及其测试）：两侧在相同键（`sessions`、`loader`）下以不同服务合并 cordis `Context` 接口，单一 program 会同时看到两份声明合并而报冲突。共享叶子包（session/llm/tools/apiproxy 等）只构建一次，由两个 program 共同引用（[拓扑](../process/2026-07-22-tsconfig-solution-root-two-aggregates.md)）。
 
@@ -64,7 +64,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 | 装配层 | `dsh-host-runtime` | 插件组合 + ApiProxy 集成 + web UI 插件挂载（覆盖八个 dshClient 包的内存 Loader 树）；host 级配置归属地（defaults/persistenceRoot，将来用户 profile） | 装什么插件、给什么默认值只在这里定；壳不得改装配 |
 | 承载层 | `dsh-host-webserver` | Web 形态 HTTP 与 upgrade：静态服务 + `/api/*`→handler 转发 + WebSocket upgrade route + close 语义；插件 bundle 端点 + `__DSH_BOOT__` manifest（元数据清单）注入（由 web 插件注册表供给） | Web（浏览器访问）专用；零 workspace 依赖（注册表经结构注入到达）；Electron 不复用它 |
 | client 库 | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | slot 注册表核心 / ctx↔React 胶合 / 纯 React 原子组件 | 组件零 cordis 运行时依赖；由壳播种进 loader 模块表 |
-| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
+| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构笔记 | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
 | 应用态 | `@deepseek-ai/dsh`（apps/cli）+ `dsh-frontend`（apps/web，vite 应用） | bin 粗分发 + 每形态一个拼装模块（web.ts / headless.ts）；vite 应用是 `dsh-client-web` 壳表面之上的薄 main | 形态间动态 import 互不加载；dist 定位等 workspace 知识留在 app |
 
 #### 命名规则
@@ -216,11 +216,11 @@ export type ResponseValue<K> =
 | `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
+| IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
-**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
+**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构笔记）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
 
 **加一个帧型（3 步）**：①`MuxFrame`/`HostFrame` union 加一支（可应答帧须注明 rpcId 稳定语义）；②帧 schema 加一支；③消费端 fold/路由的 documented-default 已兜底未知型，按需加显式分支。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index f0cc648a10..269933c1a7 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 5e927405e9012b5a56d82da8fcf600ca4aa1bd5b
-2026-07-19-gui-web-client-architecture.zh.md: 4294af099dce4e1345e625694a054661483f8d12
+2026-07-19-gui-web-client-architecture.md: 82b2f85708c423748954644d4991e2d54d42874a
+2026-07-19-gui-web-client-architecture.zh.md: c37252d1db291cae11db2a615c9e4005ece717da
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 5e927405e9..82b2f85708 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-19-gui-web-client-architecture.zh.md)
 
-> Division of labor: the channel-independent layering model and RPC protocol (message model / type system / contract face / client base class) are in the [layering and RPC protocol RFC](2026-07-19-gui-layering-and-rpc-protocol.md); this document = the browser side: how the client cordis tree loads, how UI plugins compose through slots and services, and how the React-free object layer feeds React through immutable snapshots.
+> Division of labor: the channel-independent layering model and RPC protocol (message model / type system / contract face / client base class) are in the [layering and RPC protocol note](2026-07-19-gui-layering-and-rpc-protocol.md); this document = the browser side: how the client cordis tree loads, how UI plugins compose through slots and services, and how the React-free object layer feeds React through immutable snapshots.
 
 ## Problem
 
@@ -30,13 +30,13 @@ Both ends run cordis. The host is a cordis plugin tree; the browser runs a secon
 
 ## The client cordis tree and the loading chain
 
-The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` contract; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
+The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading note](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` contract; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
 
 Type universes stay split at the aggregate level — `tsconfig.host.json` is the host program and `tsconfig.client.json` the client program, both referenced by the solution root `tsconfig.json` — because both sides merge cordis `Context` under the same keys (`sessions`, `loader`) with different services; client packages consume the wire vocabulary through pure type subpaths (`@deepseek-ai/dsh-session/types` and kin) so no host augmentation rides into the client program.
 
 ## The slot system: how the page composes
 
-The slot system has its own RFC — the [slot system standard](2026-07-22-slot-type-chain-implementation.md) — and this document defers to it entirely. The one-paragraph summary for orientation: the shell renders only `'root'`; a plugin composes UI through a single `register` call that occupies a slot, declares+authorizes its child slots (`children` spec object), declares its store, and injects its business face; component props arrive in four auto-derived shares (`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject), each from its single source of truth. `SlotMap` declaration merging is the type authority and entries carry only the owner share ("whoever injects it, owns its type"); every rendered entry sits in a per-entry error boundary.
+The slot system has its own note — the [slot system standard](2026-07-22-slot-type-chain-implementation.md) — and this document defers to it entirely. The one-paragraph summary for orientation: the shell renders only `'root'`; a plugin composes UI through a single `register` call that occupies a slot, declares+authorizes its child slots (`children` spec object), declares its store, and injects its business face; component props arrive in four auto-derived shares (`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject), each from its single source of truth. `SlotMap` declaration merging is the type authority and entries carry only the owner share ("whoever injects it, owns its type"); every rendered entry sits in a per-entry error boundary.
 
 Implementation homes: registry core and the props-share types in `packages/client/ui-slots`, outlet/renderer/uSES bridge in `packages/client/web-react`.
 
@@ -73,7 +73,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 - **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation.
 - **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned.
 - **ConversationNodeAssembler** (`runtime/src/client/conversation/`): the Session-owned incremental engine runs independently registered Definitions over raw events. `match(event)` selects `(kind, id)` without Context scans; start/update build Definition state; engine-computed Locations carry Turn/Step closure; backward Context reads record dependencies repaired by later prepends; `buildViewNode(target)` materializes only dirty Contexts. The Chat builder preserves structural order and per-key value identity, `useSession` selectors isolate consumption, and Assistant token publication coalesces to one animation frame. The [Conversation Node decision](2026-08-09-client-conversation-node-assembly.md) owns assembly, while [Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) owns recursive Tool rendering.
-- **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; Web carriage uses HTTP POST for the two client→server quadrants and [one WebSocket per logical stream](2026-08-04-websocket-downlink-carrier.md) for the two server→client quadrants, while the client class family remains the layering RFC's territory.
+- **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; Web carriage uses HTTP POST for the two client→server quadrants and [one WebSocket per logical stream](2026-08-04-websocket-downlink-carrier.md) for the two server→client quadrants, while the client class family remains the layering note's territory.
 
 ## The React face (`packages/client/web-react`)
 
@@ -109,7 +109,7 @@ Domain implementation files never import a sibling domain; shared surfaces route
 ## How to develop
 
 - **A new UI feature** = a new plugin package: declare `dshClient` (+ `inject` topology) in package.json, write the browser half under `src/client/` (apply mounts services/stores and registers slots), keep the node half an empty apply unless there is host logic, build with the shared preset. Add the plugin to the host config; the manifest and loading follow automatically.
-- **A new slot**: see the [slot system standard RFC](2026-07-22-slot-type-chain-implementation.md) — merge the contract into `SlotMap`, declare it in the parent entry's `children`, render through the auto-injected `renderSlot` prop. Never export components globally.
+- **A new slot**: see the [slot system standard note](2026-07-22-slot-type-chain-implementation.md) — merge the contract into `SlotMap`, declare it in the parent entry's `children`, render through the auto-injected `renderSlot` prop. Never export components globally.
 - **Consuming a new frame type**: transport-only session frames → Session's dispatch switch; host-level frames → the Manager routing table; logged conversation business events → a Definition plus a keyed view renderer, without a Session business branch.
 - **Where does this state live**: business data (events, streaming, pending) → always the object layer; what the parent knows → owner props at the renderSlot site; private to one component (scroll, search text, expansion) → component state; shared across entries or surviving remounts (selection, drafts, panel widths) → an entry-declared store ([slot system standard](2026-07-22-slot-type-chain-implementation.md)).
 - **Notification channel**: frame-driven/async = `markDirty` batching; direct user-gesture echo whose controlled input needs the same tick = `notifyNow`.
@@ -126,4 +126,4 @@ Token streams no longer shake the render tree: Assistant chunks update one busin
 | window globals / import maps for shared deps | The DI require table keeps sharing explicit, fail-loud, and swappable; globals leak identity and version silently |
 | Business data in zustand slices | The event window/accumulator is a behavioral state machine, not a flat slice; the object layer keeps snapshot granularity and batching controllable |
 | Parallel string-keyed component registry for Tool rows | ui-tool's keyed child slot carries the runtime-open Tool-name set through the one slot registration model ([toolview dissolution](2026-07-23-toolview-dissolution.md)) |
-| Progressive/Suspense boot in P-I | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture |
+| Progressive/Suspense boot in the initial web client delivery | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 4294af099d..c37252d1db 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-19-gui-web-client-architecture.md) | 中文
 
-> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议笔记](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
 
 ## Problem
 
@@ -30,13 +30,13 @@ Status: implemented
 
 ## client cordis 树与装载链
 
-装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` 约定；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
+装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载笔记](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` 约定；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
 类型宇宙在聚合层拆分——`tsconfig.host.json` 是 host program、`tsconfig.client.json` 是 client program，二者由 solution 根 `tsconfig.json` 引用，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
 
 ## slot 体系：页面怎么拼
 
-slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占坑、声明并授权子坑（`children` spec 对象）、声明 store、注入业务面；组件 props 分四份额自动推导到达（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
+slot 体系有自己的笔记——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占坑、声明并授权子坑（`children` spec 对象）、声明 store、注入业务面；组件 props 分四份额自动推导到达（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
 
 实现的家：注册表核心与 props 份额类型在 `packages/client/ui-slots`，出口组件/渲染器/uSES 桥在 `packages/client/web-react`。
 
@@ -73,7 +73,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
 - **ConversationNodeAssembler**（`runtime/src/client/conversation/`）：Session 拥有的增量引擎在原始事件上运行各自独立注册的 Definition。`match(event)` 无须扫描 Context 即可选出 `(kind, id)`；start/update 构造 Definition state；引擎计算的 Location 携带 Turn/Step 关闭信息；向前查询 Context 时记录依赖，并由后续 prepend 修复；`buildViewNode(target)` 只物化 dirty Context。Chat builder 保留结构顺序和 per-key value identity，`useSession` selector 负责消费隔离，Assistant token 发布则合并到每个 animation frame 一次。[Conversation Node 决策](2026-08-09-client-conversation-node-assembly.md)拥有组装边界，[Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)拥有 Tool 递归渲染。
-- **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层 RFC 属地。
+- **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层笔记属地。
 
 ## React 面（`packages/client/web-react`）
 
@@ -109,7 +109,7 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **新 slot**：见 [slot 体系标准笔记](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
 - **消费新帧类型**：纯传输 session frame → Session 分发 switch；host 级 frame → Manager 路由表；已记录的 conversation 业务事件 → Definition 加 keyed view renderer，不增加 Session 业务分支。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
@@ -126,4 +126,4 @@ token 流不再震荡渲染树：Assistant chunk 只更新一个业务 Context
 | window 全局变量 / import map 供共享依赖 | DI require 表让共享显式、大声失败、可替换；全局变量静默泄漏身份与版本 |
 | 业务数据进 zustand 切片 | 事件窗口/累积器是行为状态机，不是扁平切片；对象层保住快照粒度与合批的可控性 |
 | Tool 行使用平行的字符串键组件注册表 | ui-tool 的 keyed 子 slot 通过唯一的 slot 注册模型承载运行时开放的 Tool 名称集合（[toolview 溶解](2026-07-23-toolview-dissolution.md)） |
-| P-I 就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
+| 首个 web 客户端交付就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index 7c4e3bef22..bdeff6702d 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.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 .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
-2026-07-23-client-plugin-loading-model.md: 302363fcb03a7aa2438b9d97d4e3405db7d6ce8d
-2026-07-23-client-plugin-loading-model.zh.md: 23061a9800b21ada64ef1a3c205c588a9406b67d
+2026-07-23-client-plugin-loading-model.md: fff96f65a21d9527c8fa49589b178c490bacdd5a
+2026-07-23-client-plugin-loading-model.zh.md: 0c0c95ba7ebffca33c2c2d1dec13f745c4316f43
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
index 302363fcb0..fff96f65a2 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-23-client-plugin-loading-model.zh.md)
 
-> Scope: the browser-side plugin loading machinery — what is a plugin, how code arrives, and how hot reload rides on that model. This note owns the loading chain; the [web client architecture RFC](2026-07-19-gui-web-client-architecture.md) defers to it for loading and keeps owning slots, the data object layer, and the React face.
+> Scope: the browser-side plugin loading machinery — what is a plugin, how code arrives, and how hot reload rides on that model. This note owns the loading chain; the [web client architecture note](2026-07-19-gui-web-client-architecture.md) defers to it for loading and keeps owning slots, the data object layer, and the React face.
 
 ## Problem
 
@@ -35,7 +35,7 @@ The manifest owns the package's loading contract: its `inject` dependency edges,
 
 To add a plugin package: declare `dshClient`, emit the `./client` bundle through the shared preset, add the name to the composing app's roster. Nothing else changes hands.
 
-When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (will receive the slots machinery now living in runtime — SlotsService, the renderer contract, the root slot), web-react (will take the renderer install into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
+When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (the slots machinery now living in runtime — SlotsService, the renderer contract, the root slot), web-react (the renderer install moving into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
 
 Four edge rules govern imports across the two kinds. None of them depends on any per-package mark:
 
@@ -126,7 +126,7 @@ One governance implementation runs on both sides of the wire; the browser-specif
 
 Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch surfaces at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
 
-Roster endgame (landed 2026-07-25 with the config-tree boot move): the roster lives in `apps/cli/config/web.cordis.yml`, `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.
+Roster: it lives in the web bundle's config tree (`packages/bundle/web-app/cordis.patch.yml`); `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index 23061a9800..0c0c95ba7e 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-23-client-plugin-loading-model.md) | 中文
 
-> 范围：浏览器侧的插件装载机件——什么是插件、代码怎么到达、热重载如何搭在这套模型上。装载链归本篇所有；[Web 客户端架构 RFC](2026-07-19-gui-web-client-architecture.md) 在装载问题上以本篇为准，继续拥有 slot、数据对象层与 React 面。
+> 范围：浏览器侧的插件装载机件——什么是插件、代码怎么到达、热重载如何搭在这套模型上。装载链归本篇所有；[Web 客户端架构笔记](2026-07-19-gui-web-client-architecture.md) 在装载问题上以本篇为准，继续拥有 slot、数据对象层与 React 面。
 
 ## Problem
 
@@ -35,7 +35,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
-普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器约定、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
+普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（现居 runtime 的 slots 机件——SlotsService、渲染器约定、root slot）、web-react（渲染器安装移入自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
 
 四条边规则治理横跨两类包的 import。没有一条依赖任何单包标记：
 
@@ -126,7 +126,7 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
-名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册位于 `apps/cli/config/web.cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE（Server-Sent Events）通道迁到 hmr 的 node 半。
+名册：住在 web 组合包的配置树里（`packages/bundle/web-app/cordis.patch.yml`）；`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE（Server-Sent Events）通道迁到 hmr 的 node 半。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
index cf3169bccf..86745008b2 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.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 .agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
-2026-07-24-single-harness-home-resolver.md: 159ba88b7b4a8d50f1be2cbe5d9162a654014e16
-2026-07-24-single-harness-home-resolver.zh.md: ed4701bbd4e37ec5c9fba02767efabfbef8d065d
+2026-07-24-single-harness-home-resolver.md: 1e128911dce0b50dc95722c6edd82cb322d18f3d
+2026-07-24-single-harness-home-resolver.zh.md: 258a16e6ca139da191db564aae40d23d05ca46b7
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
index 159ba88b7b..1e128911dc 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
@@ -32,7 +32,7 @@ An empty or whitespace-only `$DSH_HOME` is treated as unset, matching the guard
 
 **Adopt XDG (honor `$XDG_CONFIG_HOME`, or split config/data/cache into separate trees).** Considered and dropped in favor of one obvious root. A single `$DSH_HOME || ~/.dsh` ground truth matches `~/.claude` / `~/.aws`, needs no per-kind reclassification of every `~/.dsh` consumer, and leaves no resolver asymmetry to reconcile. Telemetry aligning onto the same root — rather than keeping its own XDG path — is precisely the divergence this removes.
 
-**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. The cost is that the anonymous id becomes scoped to `$DSH_HOME` rather than the machine: a project that points `DSH_HOME` at a repo-local path (or a command that loads a project `.env` before telemetry) gets a home-local id, so the id counts harness homes, not machines. This is accepted as the intended meaning of single-root — a relocated `$DSH_HOME` moves *all* harness state, telemetry identity included — and the module contract is stated as per-harness-home rather than per-machine. A machine-global identity that ignored `$DSH_HOME` would reintroduce exactly the second home policy this Note removes.
+**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. The cost is that the anonymous id becomes scoped to `$DSH_HOME` rather than the machine: a project that points `DSH_HOME` at a repo-local path (or a command that loads a project `.env` before telemetry) gets a home-local id, so the id counts harness homes, not machines. This is accepted as the intended meaning of single-root — a relocated `$DSH_HOME` moves *all* harness state, telemetry identity included — and the module contract is stated as per-harness-home rather than per-machine. A machine-global identity that ignored `$DSH_HOME` would reintroduce exactly the second home policy this decision removes.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
index ed4701bbd4..258a16e6ca 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
@@ -32,7 +32,7 @@ explicit configured path  >  $DSH_HOME  >  ~/.dsh
 
 **采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。telemetry 对齐到同一根目录——而不是保留自己的 XDG 路径——正是本决策所要消除的那种分歧。
 
-**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。
+**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本决策所要消除的那第二套 home 策略。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 073a71d118..327eeef2fb 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.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 .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: 6e4c58c229cea9ff9f0e5ccf03b04c799755244b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 4d4824f5596139523f5d5b94cb79ba9d1944ff15
+2026-07-25-web-client-session-scope-and-provide-channel.md: ff411e1b387dcd83b04f8c02d5dde3c70a815932
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 593e194654bb3552ad3cac4534847fba11cf3694
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
index 6e4c58c229..ff411e1b38 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
@@ -133,4 +133,4 @@ Slot scope is the closed set `root | session-maybe | session`:
 - The client object layer converges to a wire mirror: session identity, lifecycle, and capability adjudication all defer to the host entity — the input system (the next layer) always faces a session with a real Agent, and providers like slash/skill uniformly address by sessionId directly.
 - Blank-session governance takes zero dedicated mechanisms: state rides one derived bit, visibility rides the unified list projection (only the current blank shows, as `New Session`), reclamation rides lazy persistence's existing contract (evaporation on restart), and the ordinary ceiling rides same-Workspace reuse.
 - The cost: the id→ctx handoff discipline and provide's Concurrent discipline are conventions rather than type-enforced, pinned by review and tests; fully disabled input while no workspace is picked is an experience cost the product surface accepts (the price of the single state axis).
-- Known gaps: approval/question recovery across prune (TODO); model selection returns in live-mutation shape (the host `selectModel` trio is ready-made, awaiting its own branch).
+- Known gaps: approval/question recovery across prune (TODO); model selection returns in live-mutation shape (the host `selectModel` trio is ready-made, its client consumer not yet built).
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 4d4824f559..593e194654 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -133,4 +133,4 @@ slot scope 是闭集 `root | session-maybe | session`：
 - client 对象层收敛为 wire 镜像：会话身份、生命周期、能力判别全部以 host 实体为准——输入体系（下一层）面对的永远是「有真 Agent 的会话」，slash/skill 等提供方一律以 sessionId 直接寻址。
 - 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），回收靠 lazy persistence 的既有约定（重启蒸发），常规上限靠同 Workspace 复用。
 - 代价：id→ctx 换乘纪律、provide 的 Concurrent 纪律都是约定而非类型强制，靠 review 与测试钉住；「未选 workspace」期间输入全禁是产品面接受的体验代价（单一状态轴换来的）。
-- 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，等独立分支）。
+- 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，其 client 消费方尚未构建）。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
index f53930928f..f2676ae16c 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.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 .agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
-2026-07-25-web-command-surfaces-and-assembly.md: 4c4a400abab940baebc1699fc15b709419865f0c
-2026-07-25-web-command-surfaces-and-assembly.zh.md: f0d460199dcd947776924380d51fa6ceb65c9fe2
+2026-07-25-web-command-surfaces-and-assembly.md: 949cdecc8ec13895f6ae323a5dd792499c633d02
+2026-07-25-web-command-surfaces-and-assembly.zh.md: 19c4f93b28cf32009b97fedebe55a861db187bd8
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
index 4c4a400aba..949cdecc8e 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
@@ -28,7 +28,7 @@ The pipeline was ready but command knowledge had no landing spot: host-side `ctx
 
 ### Reference sources (seeing only projections plus their own apply closures, on the root ctx)
 
-- **ui-skill**: `skill.list({sessionId})` addresses by session (the host resolves the project root from the session header); the directory cache is single-flight keyed by sessionId, prewarmed at birth by the `warm` hook and fully cleared by `connection/reset`. A pick produces a text outcome (the literal `/name ` text, Decision 21); `lexicon` supplies the roster from CatalogFetch's settled snapshot (`undefined` while not warm), and `subscribeLexicon` notifies per-session listeners on settle and on invalidation. No match hook (references never enter command adjudication). Skill references ride ordinary prompts as literal text (outside the command plane; tool-skill unchanged, with the session-prefix directory providing the cooperative association).
+- **ui-skill**: `skill.list({sessionId})` addresses by session (the host resolves the project root from the session header); the directory cache is single-flight keyed by sessionId, prewarmed at birth by the `warm` hook and fully cleared by `connection/reset`. A pick produces a text outcome (the literal `/name ` text, the plain-text-reference decision); `lexicon` supplies the roster from CatalogFetch's settled snapshot (`undefined` while not warm), and `subscribeLexicon` notifies per-session listeners on settle and on invalidation. No match hook (references never enter command adjudication). Skill references ride ordinary prompts as literal text (outside the command plane; tool-skill unchanged, with the session-prefix directory providing the cooperative association).
 - **ui-subagent**: candidates are zero-RPC (the sessions.list snapshot filtered by parentId/running); a pick produces a text outcome (the literal `@name ` text); `lexicon` derives from the same snapshot and `subscribeLexicon` forwards the list store's change feed (the model-side representation awaits its business workstream).
 
 ### Fixture command routing and assembly
@@ -49,7 +49,7 @@ The pipeline was ready but command knowledge had no landing spot: host-side `ctx
 | A `skill.invoke` RPC | The host has no such operation; skill references are plain text riding prompts |
 | A new ContentBlock reference type | Full-chain cost (adapters/UI/compaction); text-as-truth plus structured occurrence records suffices |
 | Client packages self-reporting command directories | The host is the single source of truth; the client only reads descriptors, with `commands-changed` pushing invalidation |
-| The `requires: 'none' \| 'agent'` discriminant axis (an agentless directory + dual-addressed queries) | With sessions always agent-backed, the amphibious command has no owner; the whole axis reverts to master's shape, to be reopened on real demand |
+| The `requires: 'none' \| 'agent'` discriminant axis (an agentless directory + dual-addressed queries) | With sessions always agent-backed, the amphibious command has no owner; the whole axis is dropped, to be reopened on real demand |
 | Dedicated commandresult / commandpanel slots | Results go through notices; the popup shell is a skeleton-internal overlay; rich result cards sit in the ledger |
 | An agent-type directory as the `@` source | No type registry exists; the live-session snapshot already covers it |
 | A PickAction/EnterCommand class family (class-inheritance pick products) | Cross-package runtime values break client bundle purity; pure data interfaces plus closure methods are equivalent |
@@ -59,4 +59,4 @@ The pipeline was ready but command knowledge had no landing spot: host-side `ctx
 - Shipping a business command = a host registration plus one client `command.register` (popupSelect) or zero registration (execute/leadingInput derive automatically), with zero skeleton changes; the cost is that the three-kind semantics concentrate in ui-command, and a hypothetical fourth kind means changing it.
 - The resident directory cache plus push invalidation buys zero-latency menus and reliable enter adjudication; the cost is three invalidation paths (the change frame, reconnect, the epoch guard) that all need tests pinning them.
 - sessionId addressing puts the host's per-agent effective directory (global + scoped shadows) straight on the wire, with the client presenting it as-is.
-- Known gaps: the popupSelect shell has no shipped business consumer yet (model selection and its kin return with #600's host `selectModel` in live-mutation shape, serving as the onboarding template then); the queue's second cut (per-item Inbox operations), rich result cards, and roster configurability sit in the ledger awaiting their triggers.
+- Known gaps: the popupSelect shell has no shipped business consumer yet (model selection and its kin arrive with the host `selectModel` work in live-mutation shape, serving as the onboarding template then); the queue's second cut (per-item Inbox operations), rich result cards, and roster configurability sit in the ledger awaiting their triggers.
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
index f0d460199d..19c4f93b28 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ### 引用源（只见投影 + 自家 apply 闭包的 root ctx）
 
-- **ui-skill**：`skill.list({sessionId})` 按会话寻址（host 从会话 header 解析项目根）；目录缓存按 sessionId 键控 single-flight，`warm` 钩子出生预热、`connection/reset` 全清。pick 产出 text outcome（`/name ` 原文，决策 21）；`lexicon` 从 CatalogFetch 的 settled 快照给名录（未热 `undefined`），`subscribeLexicon` 在 settle 与失效时按会话通知监听者。无 match 钩子（引用不进命令裁决）。skill 引用以原文随普通提示词走（命令平面之外；tool-skill 不变，会话前缀目录提供协作关联）。
+- **ui-skill**：`skill.list({sessionId})` 按会话寻址（host 从会话 header 解析项目根）；目录缓存按 sessionId 键控 single-flight，`warm` 钩子出生预热、`connection/reset` 全清。pick 产出 text outcome（`/name ` 原文，纯文本引用决策）；`lexicon` 从 CatalogFetch 的 settled 快照给名录（未热 `undefined`），`subscribeLexicon` 在 settle 与失效时按会话通知监听者。无 match 钩子（引用不进命令裁决）。skill 引用以原文随普通提示词走（命令平面之外；tool-skill 不变，会话前缀目录提供协作关联）。
 - **ui-subagent**：候选零 RPC（sessions.list 快照按 parentId/running 过滤）；pick 产出 text outcome（`@name ` 原文）；`lexicon` 同快照派生，`subscribeLexicon` 转发 list store 的变更通道（模型侧表示待业务立项）。
 
 ### fixture 命令路由与装配
@@ -49,7 +49,7 @@ Status: implemented
 | `skill.invoke` RPC | host 无此操作；skill 引用是随提示词的普通文本 |
 | 新 ContentBlock 引用类型 | 全链路成本（适配器/UI/压缩（compaction））；文本即真身 + 结构化 occurrence 记录已足够 |
 | client 各包自报命令目录 | host 是唯一真源；client 只读 descriptor，`commands-changed` 推失效 |
-| `requires: 'none' \| 'agent'` 判别轴（agentless 目录 + 双址查询） | 会话恒 agent-backed 后两栖命令无 owner；整轴回退 master 形状，待真需求重开 |
+| `requires: 'none' \| 'agent'` 判别轴（agentless 目录 + 双址查询） | 会话恒 agent-backed 后两栖命令无 owner；整轴弃置，待真需求重开 |
 | 专用 commandresult / commandpanel slot | 结果走 notice；popup 壳是骨架内浮层；富结果卡入台账 |
 | agent-type 目录做 `@` 源 | 无类型注册表；实时会话快照已覆盖 |
 | PickAction/EnterCommand 类族（类继承 pick 产物） | 跨包运行时值破坏 client bundle 纯度；纯数据接口 + 闭包方法等价 |
@@ -59,4 +59,4 @@ Status: implemented
 - 业务命令上架 = host 注册 + client 一笔 `command.register`（popupSelect）或零注册（execute/leadingInput 自动派生），零骨架改动；代价是三型语义集中在 ui-command，假想的第四型意味着改它。
 - 常驻目录缓存 + 推失效换来菜单零延迟与回车裁决可靠；代价是三条失效路径（change 帧、重连、epoch guard）都需测试钉住。
 - sessionId 寻址让 host 的 per-agent 有效目录（全局 + scoped shadows）直接上 wire，client 原样呈现。
-- 已知欠账：popupSelect 壳暂无已上架业务消费方（模型选择等将随 #600 的 host `selectModel` 以 live-mutation 形态回归，届时作接入样板）；队列第二刀（逐项 Inbox 操作）、富结果卡、roster 可配置性入台账待触发。
+- 已知欠账：popupSelect 壳暂无已上架业务消费方（模型选择等将随 host `selectModel` 工作以 live-mutation 形态到来，届时作接入样板）；队列第二刀（逐项 Inbox 操作）、富结果卡、roster 可配置性入台账待触发。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index 5605f1681e..f670471d90 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: 39ef214a94fcd019f535fb60136d5dcc09b54e60
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: dbd1aebff58c12f33dfe146d5cf4895801035bce
+2026-07-25-web-input-machine-and-slash-pipeline.md: 345a08188fc6a4f2b951e8f9cd9d3a5b953a5e34
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: d454003036dd322ec3366c66293120cb2997de8d
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
index 39ef214a94..345a08188f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
@@ -76,9 +76,9 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 - When the blank Hero re-picks the Workspace, the shell calls `connectWorkspace`; if the target session differs, the non-empty draft moves from the current shell to the target shell before the new id is opened, and the old blank session survives but is no longer current.
 - The Notifier's two-bit contract: `dirty` (snapshot freshness, clearable by an `ensureFresh` pull) and `notifyPending` (notification debt, cleared only by a flush) are mutually independent — a pull must not swallow a push, and object-layer push subscribers (watchTransaction) depend on this guarantee.
 
-### Plain-text references (Decision 21): text outcomes and lexicon decoration
+### Plain-text references: text outcomes and lexicon decoration
 
-skill/@subagent references skip the placeholder + occurrence identity chain — a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
+skill/@subagent references skip the placeholder + occurrence identity chain — the plain-text-reference decision (externally logged as Decision 21): a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
 
 - PickOutcome gains a `{text}` arm; the new scoped bail event `slash/input-insert-text` `{text, span}` (the same contract as the other three: draftRev CAS, returning true ⟺ an actual rewrite); facade.insertText goes through setDraft concatenation — zero machine changes.
 - Sources get an optional `lexicon?(session)` hook: a synchronous hot-snapshot name roster, with `undefined` = data not warm — zero decoration, never triggering a fetch (the render path stays synchronous and side-effect-free); the paired optional `subscribeLexicon?(session, listener)` hook is the invalidation channel for rolls that change after warm (catalog settles, children spawn/exit). The controller aggregates the rolls into its `lexicon` snapshot store (re-polling on each source notification); sources registered after scope birth are warmed and folded in via the service's live-controller broadcast.
@@ -125,7 +125,7 @@ The state machine's entire behavior is covered by pure-JS unit tests (event sequ
 | A placeholder select resident in the tool row | Named seats stay empty until registration; a placeholder clashing with the real implementation is two sources of truth |
 | An always-visible Plan on/off toggle | The shared Command source already owns entry; a second entry point turns a status seat into redundant mode chrome |
 | A second plus-menu component/controller, or an Add/File group above Command | It would duplicate async candidates, keyboard highlight, focus retention, and pick state; the plus control is only a source-filtered launcher for the existing MenuView, and this scope has no file capability |
-| All references through U+FFFC chips (the pre-Decision-21 line) | Plain text + derived decoration carries zero identity state; the literal text IS the model projection, sparing undo/clipboard any special cases; the chip chain is kept for scenarios needing indivisible atomicity |
+| All references through U+FFFC chips (the line the plain-text-reference decision replaced) | Plain text + derived decoration carries zero identity state; the literal text IS the model projection, sparing undo/clipboard any special cases; the chip chain is kept for scenarios needing indivisible atomicity |
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index dbd1aebff5..d454003036 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -76,9 +76,9 @@ occurrence 表与 chip 三投影：
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。
 - Notifier 双位约定：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
 
-### 纯文本引用（决策 21）：text outcome 与 lexicon 装饰
+### 纯文本引用：text outcome 与 lexicon 装饰
 
-skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
+skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引用决策（外部记录为决策 21）：pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
 
 - PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同约定：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
 - source 可选 `lexicon?(session)` 钩子：同步热快照名录，`undefined` = 数据未热——零装饰、永不触发 fetch（渲染路径保持同步无副作用）；配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化（目录 settle、子代生灭）时的失效通道。controller 把各名录聚合进自己的 `lexicon` snapshot store（每次 source 通知重拉）；scope 出生后才注册的 source 由 service 广播给活 controller，补 warm 并并入名录。
@@ -125,7 +125,7 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 | 占位 select 常驻工具行 | 具名 slot 在注册前保持为空；占位件与真实现冲突时是双真相源 |
 | 始终可见的 Plan 开／关切换 | 入口已归共享 Command source 所有；第二个入口会把状态 seat 变成冗余的 mode chrome |
 | 第二套加号菜单组件／controller，或在 Command 上方增加 Add/File 分组 | 这会重复异步候选、键盘高亮、焦点保留与 pick 状态；加号控件只是既有 MenuView 按 source 过滤的 launcher，且此 scope 没有文件能力 |
-| 引用一律走 U+FFFC chip（决策 21 前旧线） | 纯文本 + 派生装饰零身份状态；原文即模型投影，undo/剪贴板免特判；chip 链保留给需要不可分原子性的场景 |
+| 引用一律走 U+FFFC chip（纯文本引用决策所取代的旧线） | 纯文本 + 派生装饰零身份状态；原文即模型投影，undo/剪贴板免特判；chip 链保留给需要不可分原子性的场景 |
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 830661f8cd..dabe24e211 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 378f941ead65ebdcacac665d31cd269e7a2e0565
-2026-07-26-subprocess-seam.zh.md: 4e085dcde46ef041985006019d3c6b98fed609c8
+2026-07-26-subprocess-seam.md: 7899af56259d39a4e3f924bcba673c8efa99c682
+2026-07-26-subprocess-seam.zh.md: d9cbc0ebf33bc785984b0a9bd58fa8ebc6aab436
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 378f941ead..7899af5625 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -25,7 +25,7 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 ## Alternatives considered
 
-**Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
+**Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this change was exactly this split.
 
 **Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, and PTY shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 4e085dcde4..d9cbc0ebf3 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
+**把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。本次变更对用户可见的动因正是这一拆分。
 
 **保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP 与 PTY 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 16ec810666..6acf9b3d72 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.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 .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
-2026-07-27-dispose-ladder-to-consumer.md: 25deabe811f8eb361690fec2d4fdd40cdf23dd57
-2026-07-27-dispose-ladder-to-consumer.zh.md: 359f800c9c190b7af7c08bf1d7b9b5ebf275cbaf
+2026-07-27-dispose-ladder-to-consumer.md: ab2afd313448438752e15e0f89230124cb95232f
+2026-07-27-dispose-ladder-to-consumer.zh.md: 1171840c77f6d2372b5abc5223786d65406fd5e2
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
index 25deabe811..ab2afd3134 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
@@ -16,7 +16,7 @@ The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(c
 
 **Keep the ladder on the handle as a convenience.** Rejected: a Service Definition method every Service provider must implement is not a convenience, it is contract surface — and this one encodes one consumer's cooperation shape (stdin-EOF-first) as if it were process vocabulary. The seam's own README already had to caveat that children quiescing on other signals need "their own tier-1", which is the admission that the ladder is policy.
 
-**Move the ladder to a shared helper package.** Rejected: one consumer. A second out-of-process backend with the same stdin-EOF cooperation shape can lift `disposeAcpChild` to shared code when it exists; extracting now would recreate `dsh-subagent-subprocess`, the single-purpose library this stack just deleted.
+**Move the ladder to a shared helper package.** Rejected: one consumer. A second out-of-process backend with the same stdin-EOF cooperation shape can lift `disposeAcpChild` to shared code when it exists; extracting now would recreate `dsh-subagent-subprocess`, the single-purpose library this change deleted.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 359f800c9c..1171840c77 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **把阶梯作为便利方法留在句柄上。**否决：一个每个 Service provider 都必须实现的 Service Definition 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
 
-**把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——这组堆叠变更刚刚删掉的那个单一用途库。
+**把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——本次变更删掉的那个单一用途库。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
index 0e2d5229a6..944734d054 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.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 .agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
-2026-07-28-api-browser-trust-boundary.md: e56d0fc2a7bd551899605491f3a0522b62b961b0
-2026-07-28-api-browser-trust-boundary.zh.md: 36a8323868f01f4cf16107ae62b649ade436482b
+2026-07-28-api-browser-trust-boundary.md: 7c1615fedf0f18f5e2c341b2246415057a6ee172
+2026-07-28-api-browser-trust-boundary.zh.md: fc210921918f2e790f3f1fe36edd66e73f19d74c
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
index e56d0fc2a7..7c1615fedf 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-28-api-browser-trust-boundary.zh.md)
 
 ## Problem
 
-The web GUI host serves `/api` over plain HTTP (default `127.0.0.1:3080`, `--host 0.0.0.0` supported), and the surface includes remote-code-execution-grade methods — `session.prompt` drives an agent that runs bash. A browser turns the operator into a confused deputy against such a local API in two classic ways: a malicious page fires a "simple" cross-site POST (`text/plain` — sent without a CORS preflight) whose side effects execute even though the response stays unreadable, and a DNS-rebound origin talks to the socket as if same-origin, making CORS inapplicable entirely, with only the `Host` header betraying the attacker's domain. Before this decision the system's only browser-trust check (`isTrustedNativeDialogRequest`: loopback socket + same-origin + loopback Host) guarded exactly one cosmetic route — `host.pickDirectory`, whose native dialog pops on the host's screen — while every consequential method was unguarded. Guarding per-RPC also could not survive the upcoming in-app directory browser, whose whole point is serving legitimately remote clients that a loopback rule would refuse.
+The web GUI host serves `/api` over plain HTTP (default `127.0.0.1:3080`, `--host 0.0.0.0` supported), and the surface includes remote-code-execution-grade methods — `session.prompt` drives an agent that runs bash. A browser turns the operator into a confused deputy against such a local API in two classic ways: a malicious page fires a "simple" cross-site POST (`text/plain` — sent without a CORS preflight) whose side effects execute even though the response stays unreadable, and a DNS-rebound origin talks to the socket as if same-origin, making CORS inapplicable entirely, with only the `Host` header betraying the attacker's domain. Before this decision the system's only browser-trust check (`isTrustedNativeDialogRequest`: loopback socket + same-origin + loopback Host) guarded exactly one cosmetic route — `host.pickDirectory`, whose native dialog pops on the host's screen — while every consequential method was unguarded. Guarding per-RPC also could not survive the in-app directory browser, whose whole point is serving legitimately remote clients that a loopback rule would refuse.
 
 ## Decision
 
-Enforce browser trust once, at the carrier, for the entire `/api` prefix — two halves in two stacked PRs:
+Enforce browser trust once, at the carrier, for the entire `/api` prefix — two halves:
 
 - **Media-type fence (dsh-host-apiproxy)**: every `/api` POST must declare `application/json`, else 415 before parsing. Cross-site "simple" requests thereby stop existing: any cross-site attempt is forced into a CORS preflight this server never answers.
 - **Authority fence (dsh-client-connection, `src/api-request-trust.ts`)**: every request must present a `Host` that is loopback or matches a `trustedHosts` entry (exact on `host:port`, any port on port-less entries, WHATWG-normalized; rebinding defense). Deliberately no shortcut for unmarked requests: over plain HTTP a browser attaches neither `Origin` nor Fetch-Metadata to reads (EventSource, images, navigations — those headers go only to trustworthy destinations), so an unmarked request may be a rebound browser read whose response the page can read, and Host is the one header rebinding cannot forge; non-browser clients pass via loopback, the derived LAN IP literals, or a declared authority. An attached `Origin` must equal the Host authority; `sec-fetch-site: cross-site` is refused outright. A `trustedHosts` entry that is not a bare, canonical authority fails the plugin load — WHATWG parsing would otherwise quietly authorize the hostname inside a typo or broaden an exact-port grant. `host.pickDirectory` loses its bespoke guard and rides the same fence.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md
index 36a8323868..fc21092191 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-Web GUI 宿主以纯 HTTP 提供 `/api`（默认 `127.0.0.1:3080`，支持 `--host 0.0.0.0`），而这个面上有远程代码执行级别的方法——`session.prompt` 驱动的 agent 可以运行 bash。浏览器会用两种经典方式把操作者变成攻击此类本地 API 的"混淆代理人"：恶意页面发出跨站"简单请求" POST（`text/plain`——不经 CORS 预检即发出），其副作用照常执行、只是响应不可读；以及 DNS rebinding 后的源以「同源」身份直连 socket，CORS 整体失效，只有 `Host` 头会暴露攻击者的域名。在本决策之前，系统里唯一的浏览器信任检查（`isTrustedNativeDialogRequest`：回环 socket + 同源 + 回环 Host）只守着一个装饰性的路由——`host.pickDirectory`，其原生对话框弹在宿主屏幕上——而所有真正具有严重后果的方法都没有防护。按 RPC 逐个设防也活不过即将到来的应用内目录浏览器：它存在的意义就是服务合法的远程客户端，回环规则恰恰会拒绝它们。
+Web GUI 宿主以纯 HTTP 提供 `/api`（默认 `127.0.0.1:3080`，支持 `--host 0.0.0.0`），而这个面上有远程代码执行级别的方法——`session.prompt` 驱动的 agent 可以运行 bash。浏览器会用两种经典方式把操作者变成攻击此类本地 API 的"混淆代理人"：恶意页面发出跨站"简单请求" POST（`text/plain`——不经 CORS 预检即发出），其副作用照常执行、只是响应不可读；以及 DNS rebinding 后的源以「同源」身份直连 socket，CORS 整体失效，只有 `Host` 头会暴露攻击者的域名。在本决策之前，系统里唯一的浏览器信任检查（`isTrustedNativeDialogRequest`：回环 socket + 同源 + 回环 Host）只守着一个装饰性的路由——`host.pickDirectory`，其原生对话框弹在宿主屏幕上——而所有真正具有严重后果的方法都没有防护。按 RPC 逐个设防也活不过应用内目录浏览器：它存在的意义就是服务合法的远程客户端，回环规则恰恰会拒绝它们。
 
 ## 决策
 
-在载体层对整个 `/api` 前缀一次性执行浏览器信任检查——两部分分别由两个堆叠 PR 实现：
+在载体层对整个 `/api` 前缀一次性执行浏览器信任检查——分为两部分：
 
 - **媒体类型栅栏（dsh-host-apiproxy）**：每个 `/api` POST 必须声明 `application/json`，否则在解析前以 415 拒绝。跨站「简单请求」由此不复存在：任何跨站尝试都被逼进一次本服务器从不应答的 CORS 预检。
 - **权威栅栏（dsh-client-connection，`src/api-request-trust.ts`）**：每个请求的 `Host` 都必须是回环地址，或与某个 `trustedHosts` 条目匹配（带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，均经 WHATWG 归一化；rebinding 防御）。刻意不为无标记请求开捷径：明文 HTTP 下浏览器的读取（EventSource、图片、导航——这些头只发给可信目标）既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求可能是被重绑页面发起且响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；非浏览器客户端经由回环地址、推导的 LAN IP 字面量或已声明的权威通过。若带 `Origin` 则必须与 Host 权威完全一致；`sec-fetch-site: cross-site` 一律拒绝。不是单纯规范化 authority 的 `trustedHosts` 条目会导致插件加载失败——否则 WHATWG 解析会悄悄授权笔误里的 hostname，或放大精确端口授权。`host.pickDirectory` 失去专属守卫，与其他请求同栅而行。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 2ab9d7c12b..ae12dd3bb4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.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 .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
-2026-07-28-directory-picker-capability-seam.md: 898d8dc3a6fa41cfacc694f15c88d3a71c48f413
-2026-07-28-directory-picker-capability-seam.zh.md: fce9a801ad8535b264c91f6d3b32373e35cb146d
+2026-07-28-directory-picker-capability-seam.md: 2e663e9bc90841dd843bf8a8ff5676e4ca3b91b3
+2026-07-28-directory-picker-capability-seam.zh.md: 14af29a88648a7f6581ec16a4fb3698a0d9669e5
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
index 898d8dc3a6..2e663e9bc9 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-directory-picker-capability-seam.zh.md)
 
 ## Problem
 
-The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection point). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the planned in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
+The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection point). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index fce9a801ad..14af29a886 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -6,7 +6,7 @@
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入点）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入点）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
index 512bd4fac7..7a120346c3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.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 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
-2026-07-28-user-settings-seam.md: 62eae0db157d61266af165f609daaefcd7d5e285
-2026-07-28-user-settings-seam.zh.md: bf0f5d850f4cf303efdbd6476ae210cf8779a31d
+2026-07-28-user-settings-seam.md: 58104df1fbba302372c34ce5cba6c59f2d108cfd
+2026-07-28-user-settings-seam.zh.md: 3d160a0ad9dbc86233ea6fb3bd462f71d73becba
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
index 62eae0db15..58104df1fb 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
@@ -26,9 +26,9 @@ User-editable configuration had no owner: `dsh web` read a cwd-anchored profile
 
 - **Include write-back as the user layer** (per-plugin config pages writing loader entry files, cordis-webui style): write-back would target per-composition files, binding user preferences to one `cordis.yml`; a per-user layer must survive template upgrades and serve TUI and web from one document.
 - **Loader-reactive `fiber.update` as the propagation channel**: constructor-time reads observe nothing; the seam's explicit `watch()` makes hot-update a consumer contract instead of framework magic.
-- **A domain-aware settings service** (getters per product area): the coupling objection from design review stands; the service stores, validates, and publishes — domain meaning stays with the registrant that owns the schema.
+- **A domain-aware settings service** (getters per product area): rejected as coupling; the service stores, validates, and publishes — domain meaning stays with the registrant that owns the schema.
 - **Multi-layer precedence now** (system/managed/project tiers à la Codex/Claude Code): deferred until a real second layer exists; the resolve step is the single place layering would extend.
-- **A cross-process lockfile now** (Pi's proper-lockfile): initially deferred as "atomic replace plus watcher convergence until real contention shows up" — review showed convergence loses unobserved sibling namespaces, so the deferral is superseded by the [write-path integrity note](2026-07-30-settings-write-path-integrity.md)'s hand-rolled writer lock.
+- **A cross-process lockfile now** (Pi's proper-lockfile): initially deferred as "atomic replace plus watcher convergence until real contention shows up" — but convergence loses unobserved sibling namespaces, so the deferral is superseded by the [write-path integrity note](2026-07-30-settings-write-path-integrity.md)'s hand-rolled writer lock.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
index bf0f5d850f..3d160a0ad9 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
@@ -26,9 +26,9 @@ Status: implemented
 
 - **以 Include 写回为用户层**（cordis-webui 式的按插件配置页写 loader entry 文件）：写回目标是按组合的文件，会把用户偏好绑死在某个 `cordis.yml` 上；用户层必须在模板升级中存活，并以同一文档服务 TUI 与 web。
 - **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者约定而非框架魔法。
-- **领域化的 settings 服务**（按产品域的 getter）：设计评审中的耦合反对成立；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。
+- **领域化的 settings 服务**（按产品域的 getter）：因耦合而否决；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。
 - **现在就做多层优先级**（Codex/Claude Code 式 system/managed/project 层级）：延后到真实第二层出现；resolve 步骤是分层未来唯一的扩展点。
-- **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——评审发现收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。
+- **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——但收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
index fd4c24db70..8f17ecd480 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.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 .agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
-2026-07-29-dsh-source-launch-tsx-esm.md: aabe6c2d6a92b5cc6568eee1d42df3a6998cf0ca
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: ecda8b273b3efc4773dbe3ed25a9ef0572b79ce4
+2026-07-29-dsh-source-launch-tsx-esm.md: ed22e51d59a25db130b3760ce484c116bade4348
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: bdd549092eb30f7749c8f7561068daafe3548b28
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
index aabe6c2d6a..ed22e51d59 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
@@ -16,7 +16,7 @@ Startup latency also mattered: the off-thread `module.register()` hooks worker s
 
 The `dsh` TUI, Web, and headless source launches run `node --import tsx/esm`: tsx's ESM-only hook owns both TypeScript transformation and tsconfig `paths` projection. `bin/dsh`, the root `dsh`/`demo:tui`/`demo:web` scripts, and the Code Mode TUI overlay use the same vector; `bin/dsh` references the hook and tsconfig by absolute checkout paths (bare `tsx/esm` does not resolve from an arbitrary cwd) and pins `TSX_TSCONFIG_PATH` to the root tsconfig. The CJS hook stays off because the CLI source graph is ESM-only; measured TUI time-to-banner is ~0.7s versus ~1.1s under the full tsx default and ~0.75s under the removed native chain.
 
-`scripts/tspath-loader.ts` and `apps/cli/src/tsconfig-paths-loader.ts` are deleted. With them went the loader's runtime rule of mapping a workspace import only for declared runtime dependencies — tsx applies the `paths` map unconditionally. Declaration completeness now rests on the static gates alone: `verify-cordis-config` for configured bare plugins, and workspace constraints for manifests. (That runtime rule found real bugs: `dsh-plan-mode` and `dsh-tool-tasks` imported `@deepseek-ai/dsh-llm` while declaring it only in devDependencies; fixed alongside this change.)
+`scripts/tspath-loader.ts` and `apps/cli/src/tsconfig-paths-loader.ts` are deleted. With them went the loader's runtime rule of mapping a workspace import only for declared runtime dependencies — tsx applies the `paths` map unconditionally. Declaration completeness now rests on the static gates alone: `verify-cordis-config` for configured bare plugins, and workspace constraints for manifests. (That runtime rule found real bugs: `dsh-plan-mode` and `dsh-tool-tasks` imported `@deepseek-ai/dsh-llm` while declaring it only in devDependencies; since fixed.)
 
 The node-compat CI matrix (Node 22.19 and 26) gains `dsh-source-launch-smoke` (`apps/cli/tests/source-launch.compat.spec.ts`): a keyless piped-stdio launch of the exact production vector asserting the non-zero-exit TTY refusal. Any future Node change to module hooks or TypeScript handling turns this gate red instead of breaking developers' `pnpm dsh`.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
index ecda8b273b..bdd549092e 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 `dsh` 的 TUI、Web 与无头源码启动运行 `node --import tsx/esm`：由 tsx 的 ESM-only 钩子同时负责 TypeScript 转换与 tsconfig `paths` 投影。`bin/dsh`、根目录的 `dsh`/`demo:tui`/`demo:web` 脚本以及 Code Mode TUI overlay 使用同一向量；`bin/dsh` 以 checkout 的绝对路径引用钩子与 tsconfig（裸的 `tsx/esm` 无法从任意 cwd 解析），并将 `TSX_TSCONFIG_PATH` 固定到根 tsconfig。CJS 钩子保持关闭，因为 CLI 源码图是纯 ESM；实测 TUI 到 banner 约 0.7s，对比完整 tsx 默认形态约 1.1s、已移除的原生链约 0.75s。
 
-`scripts/tspath-loader.ts` 与 `apps/cli/src/tsconfig-paths-loader.ts` 已删除。随之消失的还有该 loader「仅为已声明运行时依赖映射 workspace import」的运行时规则——tsx 无条件应用 `paths` 映射。声明完整性现在仅由静态门禁保障：配置的裸插件走 `verify-cordis-config`，manifest（元数据清单）走 workspace constraints。（该运行时规则确实发现过真实缺陷：`dsh-plan-mode` 与 `dsh-tool-tasks` 导入 `@deepseek-ai/dsh-llm` 却只声明在 devDependencies；已随本变更修复。）
+`scripts/tspath-loader.ts` 与 `apps/cli/src/tsconfig-paths-loader.ts` 已删除。随之消失的还有该 loader「仅为已声明运行时依赖映射 workspace import」的运行时规则——tsx 无条件应用 `paths` 映射。声明完整性现在仅由静态门禁保障：配置的裸插件走 `verify-cordis-config`，manifest（元数据清单）走 workspace constraints。（该运行时规则确实发现过真实缺陷：`dsh-plan-mode` 与 `dsh-tool-tasks` 导入 `@deepseek-ai/dsh-llm` 却只声明在 devDependencies；后已修复。）
 
 node-compat CI 矩阵（Node 22.19 与 26）新增 `dsh-source-launch-smoke`（`apps/cli/tests/source-launch.compat.spec.ts`）：以精确的生产启动向量做 keyless 管道 stdio 启动，断言非零退出的 TTY 拒绝。未来 Node 对模块钩子或 TypeScript 处理的任何改动都会让该门禁变红，而不是破坏开发者的 `pnpm dsh`。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
index e597017076..c50bf478ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.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 .agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
-2026-07-29-package-regrouping.md: bb9f7deb775a0922de8b20f766446ebf007718d3
-2026-07-29-package-regrouping.zh.md: 1d7d79e0cfad95382c036b3c99712775870aa48a
+2026-07-29-package-regrouping.md: 3c37bce05bacd6af800a76ac93fb691b896a6772
+2026-07-29-package-regrouping.zh.md: 68903ff1fad6a975c4445fe8971c8fe0dd40117f
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
index bb9f7deb77..3c37bce05b 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
@@ -29,10 +29,10 @@ Six groups are recomposed; every other group keeps its prior boundary and conten
 | `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
 - **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
 - **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
-- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
+- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/`: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
 - **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
 - **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
 
@@ -54,11 +54,11 @@ The first four are settled intent; resolving them converges the SDK wire stack's
 
 ## What the move touched
 
-The moves landed as `git mv` commits, one per region (the session fold; `ui/` dissolution + `scaffold/`; `guard/` merge + `self-modification/`), so rename detection carries review. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
+The moves landed as pure `git mv` moves, so rename detection carries the history. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
 
-A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name. Each FIXME landed in the same commit as the move that created its context.
+A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name.
 
-`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
+`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision.
 
 ## Alternatives considered
 
@@ -68,21 +68,21 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 **A full npm rename sweep** (`dsh-<group>-<pkg>` for every package). Rejected: npm names are flat, so group-prefixing adds churn across imports, configs, and fixtures with no disambiguation gain; targeted FIXME-tracked renames cover the actual collisions.
 
-**Performing the five renames inside the reorganization.** Rejected in review: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
+**Performing the five renames inside the reorganization.** Rejected: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
 
 **A two-way session split** (`session-core/` + `session-utils/`). Rejected: query belongs to neither side cleanly, and `session-core` invites confusion with `core/session` (`dsh-session`, the live in-memory service, which stays in `core/`).
 
-**A three-way session split** (`session-store/` + `session-query/` + `session-utils/`), this RFC's first draft. Rejected in review: `session-utils/` was a negatively-defined annex ("derived, nothing load-bearing depends on it") — the grab-bag shape the north star forbids, and factually wrong besides (`session-query` peer-depends on `dsh-session-title`). The invented compound names also read machine-generated; one plain `session/` group says what a human would say. Query stays standalone in both drafts: it is an independently consumed read surface with its own tool package and backend.
+**A three-way session split** (`session-store/` + `session-query/` + `session-utils/`). Rejected: `session-utils/` was a negatively-defined annex ("derived, nothing load-bearing depends on it") — the grab-bag shape the north star forbids, and factually wrong besides (`session-query` peer-depends on `dsh-session-title`). The invented compound names also read machine-generated; one plain `session/` group says what a human would say. Query stays standalone regardless: it is an independently consumed read surface with its own tool package and backend.
 
 **Recomposing `ui/` as a single `channels/` group** (tui + jsonrpc + acp + interaction seams + boot). Rejected: the same grab-bag under a new name — those packages serve four planes, `jsonrpc`'s measured cluster is the SDK wire stack, and `acp/` is an automation transport, not a human channel.
 
-**A standalone one-package `tui/` group**, this RFC's first draft. Rejected in review: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
+**A standalone one-package `tui/` group.** Rejected: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
 
-**Keeping the group name `sdk/`.** Rejected in review: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
+**Keeping the group name `sdk/`.** Rejected: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
 
-**Moving `app-boot` to `apps/`** (review question). Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
+**Moving `app-boot` to `apps/`.** Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
 
-**Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; review settled on `self-modification/` as the plainer term.
+**Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; the name settled on `self-modification/` as the plainer term.
 
 **Renaming `context/` to `request-context/`.** Rejected: within this tree the group is unambiguous in situ; the churn is unjustified.
 
@@ -90,7 +90,7 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 - The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged. The workspace package-name set is identical before and after (zero npm renames), and the five FIXME markers pin the deferred ones. A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
 - What pins the result: `pnpm run typecheck`, the unit suites of every moved group, `verify-package-paths`, `verify-md-links`, and the corpus-wide translation pairing all pass on the moved tree; the group-scoped test globs in `vitest.snapshot.config.ts` were rewritten with the moves so the suites collect the same test files as before (a fail-open glob would silently drop coverage).
-- Every open PR touching a moved file rebases across the move once; the mapping table in the PR body and rename detection resolve most hunks mechanically.
+- Every open PR touching a moved file rebases across the move once; rename detection resolves most hunks mechanically.
 - Single-package groups remain (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
 - The `scaffold/` folders diverge from their npm names until the deferred renames land — the one transitional asymmetry, carried by three explicit `paths` entries in `tsconfig.base.json` and resolved by the FIXME renames.
 - What this gave up: nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
index 1d7d79e0cf..68903ff1fa 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
@@ -29,10 +29,10 @@ Status: implemented
 | `guard/` | repeat-tool-guard、timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（评审意见：名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
+- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
 - **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
 - **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
-- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
+- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
 - **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
 - **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
 
@@ -54,11 +54,11 @@ Status: implemented
 
 ## What the move touched
 
-移动以 `git mv` 提交落地，每个区域一个提交（会话折叠；`ui/` 解散加 `scaffold/`；`guard/` 合并加 `self-modification/`），评审由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+移动以纯 `git mv` 形式落地，历史由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
 
-组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。每条 FIXME 都与创造其上下文的那次移动落在同一个提交。
+组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。
 
-`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
+`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策。
 
 ## Alternatives considered
 
@@ -68,21 +68,21 @@ Status: implemented
 
 **一轮全量 npm 重命名**（每个包都改为 `dsh-<group>-<pkg>`）。不予采纳：npm 包名是扁平的，加组前缀只会在 import、配置和 fixture 之间制造改动，却换不来任何消歧收益；用 FIXME 跟踪的定点改名足以覆盖真正的撞名。
 
-**在重组内部一并完成那五个改名。** 评审中否决：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
+**在重组内部一并完成那五个改名。** 不予采纳：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
 
 **会话两分法**（`session-core/` + `session-utils/`）。不予采纳：query 放哪一侧都不干净，而且 `session-core` 容易与 `core/session` 混淆（后者是 `dsh-session`，常驻内存的实时服务，留在 `core/` 不动）。
 
-**会话三分法**（`session-store/` + `session-query/` + `session-utils/`），即本 RFC 的初稿。评审中否决：`session-utils/` 是靠否定条件圈出来的附属区（「派生的、没有承重方依赖」）——正是指导准则禁止的大杂烩形态，而且事实层面也站不住（`session-query` 对 `dsh-session-title` 声明对等依赖）。杜撰的复合名也读起来不像人起的；一个朴素的 `session/` 组说的就是人会说的话。query 在两版草稿中都保持独立：它是被独立消费的读取面，自带自己的工具包与后端。
+**会话三分法**（`session-store/` + `session-query/` + `session-utils/`）。不予采纳：`session-utils/` 是靠否定条件圈出来的附属区（「派生的、没有承重方依赖」）——正是指导准则禁止的大杂烩形态，而且事实层面也站不住（`session-query` 对 `dsh-session-title` 声明对等依赖）。杜撰的复合名也读起来不像人起的；一个朴素的 `session/` 组说的就是人会说的话。query 无论如何都保持独立：它是被独立消费的读取面，自带自己的工具包与后端。
 
 **把 `ui/` 重组为单一 `channels/` 组**（tui + jsonrpc + acp + 交互 seam + boot）。不予采纳：不过是换个名字的同一个大杂烩——这些包服务于四个平面，`jsonrpc` 的实测聚类归属是 SDK 通信栈，而 `acp/` 是自动化传输通道，不是人类通道。
 
-**独立的单包 `tui/` 组**，即本 RFC 的初稿。评审中否决：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
+**独立的单包 `tui/` 组。** 不予采纳：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
 
-**保留组名 `sdk/`。** 评审中否决：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
+**保留组名 `sdk/`。** 不予采纳：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
 
-**把 `app-boot` 挪到 `apps/`**（评审提问）。不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
+**把 `app-boot` 挪到 `apps/`。** 不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
 
-**把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；评审定为更朴素的 `self-modification/`。
+**把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；名字最终定为更朴素的 `self-modification/`。
 
 **把 `context/` 改名为 `request-context/`。** 不予采纳：在这棵树里，该组就地看并无歧义；这份改动开销并不值得。
 
@@ -90,7 +90,7 @@ Status: implemented
 
 - 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。workspace 的包名集合在前后完全相同（npm 改名为零），五条 FIXME 标记钉住推迟的改名。日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
 - 结果由以下检查钉住：`pnpm run typecheck`、每个被移动组的单元测试套件、`verify-package-paths`、`verify-md-links` 与全语料翻译配对在移动后的树上全部通过；`vitest.snapshot.config.ts` 中按组划定的测试 glob 随移动一并改写，套件收集到与移动前相同的测试文件（glob 匹配为空会无声地丢失覆盖）。
-- 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；PR 正文中的映射表与重命名检测可机械化解决大多数改动块。
+- 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；重命名检测可机械化解决大多数改动块。
 - 单包组依然存在（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
 - 在推迟的改名落地之前，`scaffold/` 的目录名与其 npm 名并不一致——这是唯一的过渡性不对称，由 `tsconfig.base.json` 里三条显式 `paths` 映射承载，并由 FIXME 改名最终消除。
 - **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
index ca03afde36..b5a5fdf3d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.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 .agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
-2026-07-29-projected-token-usage-and-request-context.md: 1e2c5ff067928620dee3d0937c247bec245e34f2
-2026-07-29-projected-token-usage-and-request-context.zh.md: 176e4929ac47dd2e83bf8361501b57058a3021f2
+2026-07-29-projected-token-usage-and-request-context.md: 441a13337c76fce4ab2525ceed364361c5989f73
+2026-07-29-projected-token-usage-and-request-context.zh.md: dab0b3a57ffe665b4c5b0a53ad370a7388c7f78c
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
index 1e2c5ff067..441a13337c 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
@@ -32,11 +32,11 @@ The Web `StatsLine` reads both through the standard `useProjection` seat. Window
 
 This was accepted deliberately. An occupancy percentage is a user-facing reference figure: nothing in the harness makes decisions from it, and compaction reads `measure()` directly instead. The TUI status line has always computed occupancy this way, dividing a `measure()` total by a capacity resolved separately for the selected model — so an atomic variant here would have been the outlier, not the norm.
 
-Reviewers should not treat the non-atomicity as a defect awaiting a fix. A consumer that genuinely needs an exact same-boundary figure should call `ctx.tokenMeter.measure()` at its own request boundary, where both values are available together, rather than read this projection.
+The non-atomicity is deliberate, not a defect. A consumer that genuinely needs an exact same-boundary figure should call `ctx.tokenMeter.measure()` at its own request boundary, where both values are available together, rather than read this projection.
 
 ## Alternatives considered
 
-**An atomic request-boundary snapshot delivered as a transient mux frame (implemented, then rejected).** An earlier revision of this branch emitted `session/model-request`: one non-replayable frame carrying `contextTokens` and `contextWindow` measured at the same `agent/model-request` boundary. Being the only non-replayable class on the mux stream is what broke it. Host and mux are independent SSE streams with no cross-stream ordering, so a request emitted before a removal could arrive after `host/session-removed` and revive a dead session's telemetry, while a legitimate request for a new lifecycle reusing the same id could be fenced by a late removal. `session/subscribed` is not lifecycle proof — it says a queue began subscribing to an id, not that a new in-memory session replaced an older one — and `lastSeq` is a durable watermark two lifecycles can share. A correct fix required a monotonic lifecycle generation on the frame, on subscription, and on removal, plus a client watermark comparison.
+**An atomic request-boundary snapshot delivered as a transient mux frame (implemented, then rejected).** An earlier revision emitted `session/model-request`: one non-replayable frame carrying `contextTokens` and `contextWindow` measured at the same `agent/model-request` boundary. Being the only non-replayable class on the mux stream is what broke it. Host and mux are independent SSE streams with no cross-stream ordering, so a request emitted before a removal could arrive after `host/session-removed` and revive a dead session's telemetry, while a legitimate request for a new lifecycle reusing the same id could be fenced by a late removal. `session/subscribed` is not lifecycle proof — it says a queue began subscribing to an id, not that a new in-memory session replaced an older one — and `lastSeq` is a durable watermark two lifecycles can share. A correct fix required a monotonic lifecycle generation on the frame, on subscription, and on removal, plus a client watermark comparison.
 
 That cost bought a worse display: occupancy went blank after every reconnect and never moved while a conversation grew. It also made ApiProxy a measurement site calling the O(surface) `measure()` on every request, and expressed reconnect state through a synthetic `cancelled` open error the UI had to special-case.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
index 176e4929ac..dab0b3a57f 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
@@ -32,11 +32,11 @@ Web `StatsLine` 通过标准 `useProjection` 席位读取两者。窗口内节
 
 这是刻意接受的结果。占用率百分比是面向用户的参考数字：harness 中没有任何环节依据它做决策，压缩改为直接读取 `measure()`。TUI 状态行一直以这种方式计算占用率，即用 `measure()` 总量除以为所选模型单独解析出的容量；因此在这里做成原子版本才是异类，而不是常态。
 
-评审人不应把这种非原子性当作待修的缺陷。确实需要同一边界精确数字的消费方，应在自己的请求边界调用 `ctx.tokenMeter.measure()`，那里两个值同时可得，而不是读取该投影。
+这种非原子性是有意为之，不是缺陷。确实需要同一边界精确数字的消费方，应在自己的请求边界调用 `ctx.tokenMeter.measure()`，那里两个值同时可得，而不是读取该投影。
 
 ## 备选方案
 
-**以临时 mux 帧交付请求边界上的原子快照（已实现，随后否决）。** 本分支较早的一个修订版会发出 `session/model-request`：一个不可回放的帧，携带在同一个 `agent/model-request` 边界测得的 `contextTokens` 与 `contextWindow`。真正让它失效的，是它成了 mux 流上唯一的不可回放类别。Host 流与 mux 流是两条独立的 SSE（Server-Sent Events）流，彼此之间没有顺序保证：在移除之前发出的请求可能在 `host/session-removed` 之后才到达，让一个已死会话的遥测数据复活；而复用同一 id 的新生命周期的合法请求，又可能被一条迟到的移除拦下。`session/subscribed` 不能证明生命周期：它只说明某个队列开始订阅某个 id，而不说明新的内存会话替换了较早的会话；`lastSeq` 则是两个生命周期可以共用的持久水位线。正确的修法需要在帧上、订阅上和移除上都带一个单调递增的生命周期代次，再加上一次客户端水位线比较。
+**以临时 mux 帧交付请求边界上的原子快照（已实现，随后否决）。** 较早的一个修订版会发出 `session/model-request`：一个不可回放的帧，携带在同一个 `agent/model-request` 边界测得的 `contextTokens` 与 `contextWindow`。真正让它失效的，是它成了 mux 流上唯一的不可回放类别。Host 流与 mux 流是两条独立的 SSE（Server-Sent Events）流，彼此之间没有顺序保证：在移除之前发出的请求可能在 `host/session-removed` 之后才到达，让一个已死会话的遥测数据复活；而复用同一 id 的新生命周期的合法请求，又可能被一条迟到的移除拦下。`session/subscribed` 不能证明生命周期：它只说明某个队列开始订阅某个 id，而不说明新的内存会话替换了较早的会话；`lastSeq` 则是两个生命周期可以共用的持久水位线。正确的修法需要在帧上、订阅上和移除上都带一个单调递增的生命周期代次，再加上一次客户端水位线比较。
 
 这份代价换来的是更差的显示：占用率在每次重连后变为空白，而且会话增长期间从不移动。它还把 ApiProxy 变成一个测量点，每个请求都要调用 O(surface) 的 `measure()`，并通过一个 UI 必须特殊处理的、连接打开时的合成 `cancelled` 错误来表达重连状态。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index 3111ab36ae..23bb4a7daa 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.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 .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
-2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
-2026-07-29-request-level-llm-config-credentials.zh.md: 67a608293923291450ec3c226ac95ab4ff9f4af4
+2026-07-29-request-level-llm-config-credentials.md: f797d54f3f0507dce4f60492e4afd05a3bc60ba6
+2026-07-29-request-level-llm-config-credentials.zh.md: f09a6c72a27f06d3a76cf91653ec026d5a0f8643
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
index 238400ea41..f797d54f3f 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-29-request-level-llm-config-credentials.zh.md)
 
-> Scope: the first production consumers of `ctx.settings` (the two LLM adapter plugins), the new `packages/credentials/` capability family, and the `packages/util/atomic-write` extraction. The follow-up wire surface (`settings.*`/`credentials.*` RPC, secret-role masking, the web settings form) is a separate PR and not part of this note's shipped scope.
+> Scope: the first production consumers of `ctx.settings` (the two LLM adapter plugins), the new `packages/credentials/` capability family, and the `packages/util/atomic-write` extraction. The follow-up wire surface (`settings.*`/`credentials.*` RPC, secret-role masking, the web settings form) is separate work outside this note's scope.
 
 ## Problem
 
@@ -26,4 +26,4 @@ The [settings seam](2026-07-28-user-settings-seam.md) shipped without a producti
 
 ## Consequences
 
-Onboarding is restart-free end to end (pinned by the `missing-credential` headless snapshot and the credentials-rotation composition tests): boot keyless, browse the catalog, store the key, prompt again. The demos mount `settings-local` + `credentials-local` by default and inline no `!!js` key plumbing. `runLoaderSmoke` gained `expectedExitCode` so a designed failure surface can be pinned rather than masked. Deferred: the wire/UI surface must redact `role('secret')` fields before any RPC exposes `describe()`, settings-layer arrays still replace wholesale (the deepseek `models` list), and a settings section cannot remove a composition-provided pi-ai route (only override or extend). Review of this seam later reworked where the store lives and who may read it, made one request resolve one configuration generation, and made route replacement atomic ([credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)).
+Onboarding is restart-free end to end (pinned by the `missing-credential` headless snapshot and the credentials-rotation composition tests): boot keyless, browse the catalog, store the key, prompt again. The demos mount `settings-local` + `credentials-local` by default and inline no `!!js` key plumbing. `runLoaderSmoke` gained `expectedExitCode` so a designed failure surface can be pinned rather than masked. Deferred: the wire/UI surface must redact `role('secret')` fields before any RPC exposes `describe()`, settings-layer arrays still replace wholesale (the deepseek `models` list), and a settings section cannot remove a composition-provided pi-ai route (only override or extend). A later decision reworked where the store lives and who may read it, made one request resolve one configuration generation, and made route replacement atomic ([credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)).
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index 67a6082939..f09a6c72a2 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-29-request-level-llm-config-credentials.md) | 中文
 
-> 范围：`ctx.settings` 的第一批生产消费方（两个 LLM 适配器插件）、新增的 `packages/credentials/` 能力族，以及 `packages/util/atomic-write` 的抽取。后续的 wire 面（`settings.*`/`credentials.*` RPC、secret 角色脱敏、web 设置表单）是单独的 PR，不在本 note 已交付范围内。
+> 范围：`ctx.settings` 的第一批生产消费方（两个 LLM 适配器插件）、新增的 `packages/credentials/` 能力族，以及 `packages/util/atomic-write` 的抽取。后续的 wire 面（`settings.*`/`credentials.*` RPC、secret 角色脱敏、web 设置表单）是另行开展的工作，不在本 note 范围内。
 
 ## 问题
 
@@ -26,4 +26,4 @@ Status: implemented
 
 ## 后果
 
-上手流程端到端免重启（由 `missing-credential` headless 快照与凭据轮换组合测试固定）：无密钥启动、浏览 catalog、存入密钥、再次发起提示。demo 默认挂载 `settings-local` + `credentials-local`，不再内联任何 `!!js` 密钥接线。`runLoaderSmoke` 新增 `expectedExitCode`，使按设计出现的失败面可以被固定而非被掩盖。延后事项：wire/UI 面在任何 RPC 暴露 `describe()` 之前必须对 `role('secret')` 字段脱敏；settings 层的数组仍整体替换（deepseek 的 `models` 列表）；settings 分节无法移除组合提供的 pi-ai 路由（只能覆盖或扩展）。对该 seam 的评审随后改造了存储的所在位置与谁可以读取它，让一个请求解析出一个配置世代，并使路由替换成为原子操作（[credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)）。
+上手流程端到端免重启（由 `missing-credential` headless 快照与凭据轮换组合测试固定）：无密钥启动、浏览 catalog、存入密钥、再次发起提示。demo 默认挂载 `settings-local` + `credentials-local`，不再内联任何 `!!js` 密钥接线。`runLoaderSmoke` 新增 `expectedExitCode`，使按设计出现的失败面可以被固定而非被掩盖。延后事项：wire/UI 面在任何 RPC 暴露 `describe()` 之前必须对 `role('secret')` 字段脱敏；settings 层的数组仍整体替换（deepseek 的 `models` 列表）；settings 分节无法移除组合提供的 pi-ai 路由（只能覆盖或扩展）。后来的一项决策改造了存储的所在位置与谁可以读取它，让一个请求解析出一个配置世代，并使路由替换成为原子操作（[credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)）。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml
index e062681d87..ffa3375b74 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.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 .agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
-2026-07-30-config-plane-boundaries.md: 8a29dcc934126d6e3dfa9c0a6a308ef006017a5a
-2026-07-30-config-plane-boundaries.zh.md: 61edb9b7d8396e0453dcca0042cd0ee27551b216
+2026-07-30-config-plane-boundaries.md: 383163d5315ce0fcb39d06ac8b5f7762758fa9b2
+2026-07-30-config-plane-boundaries.zh.md: 0a412d5b8517c98accd056b690129f4e485f0e13
diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
index 8a29dcc934..383163d531 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-30-config-plane-boundaries.zh.md)
 
-> Scope: the review round over the [web configuration plane](2026-07-30-web-config-plane.md) — which namespaces reach the wire, which callers reach them, and how an editor holding a partial, possibly stale view writes without destroying what it cannot see.
+> Scope: boundary hardening of the [web configuration plane](2026-07-30-web-config-plane.md) — which namespaces reach the wire, which callers reach them, and how an editor holding a partial, possibly stale view writes without destroying what it cannot see.
 
 ## Problem
 
@@ -34,7 +34,7 @@ Three smaller defects sat beside them. `llm/adapters-updated` documented contain
 - **Opt-in metadata at `settings.register()`** — the most honest semantics (the namespace's owner declares its own exposure), and the largest change: the seam's public interface, both LLM plugins, and their docs. Recorded as the shape to adopt if a non-LLM namespace ever needs the plane.
 - **Distinguishing "unregistered" from "registered but unexposed"** — better diagnostics, and a namespace-enumeration oracle. The uniform answer is deliberate.
 - **Detecting conflicts by diffing instead of a revision** — comparing the submitted base against storage would work for whole-section writes, but the editor holds a REDACTED section: it cannot produce a comparable base, which is the same reason it cannot safely `replace`. A counter needs neither.
-- **Fixing the redaction gaps in this round** — `redactSecrets` walks only `object`/`dict`/`array`, so a secret behind a union, intersection, or transform is returned verbatim with an empty `secrets` list; `schema.toJSON()` carries a secret field's `.default(...)`; write-rejection messages return schema text that may quote the input; the client rehydrates the envelope through schemastery's `new Function`; and pi-ai's plain-string `headers` dict can legitimately hold `Authorization`. All confirmed, all deliberately left for a fail-closed `describeForWire()` that refuses a schema it cannot prove safe. They are recorded as `TODO(settings-wire-redaction)` and in the owning READMEs' Known Limitations rather than half-fixed here.
+- **Fixing the redaction gaps here** — `redactSecrets` walks only `object`/`dict`/`array`, so a secret behind a union, intersection, or transform is returned verbatim with an empty `secrets` list; `schema.toJSON()` carries a secret field's `.default(...)`; write-rejection messages return schema text that may quote the input; the client rehydrates the envelope through schemastery's `new Function`; and pi-ai's plain-string `headers` dict can legitimately hold `Authorization`. All real, all deliberately left for a fail-closed `describeForWire()` that refuses a schema it cannot prove safe. They are recorded as `TODO(settings-wire-redaction)` and in the owning READMEs' Known Limitations rather than half-fixed here.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md
index 61edb9b7d8..0a412d5b85 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-30-config-plane-boundaries.md) | 中文
 
-> 范围：针对 [Web 配置面](2026-07-30-web-config-plane.md)的评审轮——哪些 namespace 能抵达协议、哪些调用方能抵达它们，以及一个只持有局部、且可能过期视图的编辑器该如何写入，才不会毁掉它看不见的东西。
+> 范围：对 [Web 配置面](2026-07-30-web-config-plane.md)的边界加固——哪些 namespace 能抵达协议、哪些调用方能抵达它们，以及一个只持有局部、且可能过期视图的编辑器该如何写入，才不会毁掉它看不见的东西。
 
 ## 问题
 
@@ -34,7 +34,7 @@ Status: implemented
 - **在 `settings.register()` 处 opt-in metadata**——语义最正（由 namespace 的属主自行声明其暴露与否），改动也最大：seam 的公共接口、两个 LLM 插件，以及它们的文档。记录为：一旦某个非 LLM 的 namespace 确实需要这个面，就采用这个形状。
 - **区分"未注册"与"已注册但未暴露"**——诊断更好，同时也是一台 namespace 枚举预言机。统一答复是刻意为之。
 - **用 diff 而非 revision 来检测冲突**——对整分节写入而言，拿提交时的基线与存储比对是可行的，但编辑器持有的是**脱敏后**的分节：它给不出可比对的基线，这与它不能安全地 `replace` 是同一个原因。计数器两者都不需要。
-- **本轮就修掉脱敏的缺口**——`redactSecrets` 只遍历 `object`/`dict`/`array`，因此藏在 union、intersection 或 transform 之后的机密会被原样返回，且 `secrets` 列表为空；`schema.toJSON()` 会带上 secret 字段的 `.default(...)`；写入拒绝的消息返回的是可能引用了输入的 schema 文本；客户端通过 schemastery 的 `new Function` 重建信封；而 pi-ai 那个纯字符串的 `headers` 字典完全可以合法地放下 `Authorization`。全部经确认属实，也全部刻意留给一个 fail-closed 的 `describeForWire()`——它会拒绝自己无法证明安全的 schema。它们被记录为 `TODO(settings-wire-redaction)` 以及各属主 README 的 Known Limitations，而不是在这里做一半。
+- **在这里就修掉脱敏的缺口**——`redactSecrets` 只遍历 `object`/`dict`/`array`，因此藏在 union、intersection 或 transform 之后的机密会被原样返回，且 `secrets` 列表为空；`schema.toJSON()` 会带上 secret 字段的 `.default(...)`；写入拒绝的消息返回的是可能引用了输入的 schema 文本；客户端通过 schemastery 的 `new Function` 重建信封；而 pi-ai 那个纯字符串的 `headers` 字典完全可以合法地放下 `Authorization`。全部真实存在，也全部刻意留给一个 fail-closed 的 `describeForWire()`——它会拒绝自己无法证明安全的 schema。它们被记录为 `TODO(settings-wire-redaction)` 以及各属主 README 的 Known Limitations，而不是在这里做一半。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 3a6b661601..5955dd282f 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: 300280e6d4f8be2c0519efcb7ecfc82028d05445
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2b66c543bdd80612bee65a6e6e4a78ab565d5188
+2026-07-30-credential-boundaries-and-atomic-registration.md: e21b6d0ea5da30b77ab26b750e2294220646a20e
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 6552db1932ca663c6228843cd62b5cc0f3811f24
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index 300280e6d4..e21b6d0ea5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.md)
 
-> Scope: the third review round over the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this round applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
+> Scope: boundary hardening of the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this note applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
 
 ## Problem
 
-Review found the credential path leaking across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-local defects that same review round fixed (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
+The credential path leaked across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-local defects the settings write-path note fixes (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
 
 Two request-path defects sat beside them. DeepSeek resolved connection and credential facts independently, so a settings generation the resolver rejected could still pair its credential choice with the previous generation's endpoint. pi-ai handed the SDK `undefined` when a configured `apiKeyEnv` resolved to nothing, letting pi-ai's own environment discovery authenticate with an unrelated provider key — another tenant, silently billed. And its route swap disposed the old registration before creating the new one: a route another adapter owned dropped every existing route, after which the facts cache could equal the registry's, so restoring the working configuration never re-applied.
 
@@ -28,8 +28,8 @@ Two request-path defects sat beside them. DeepSeek resolved connection and crede
 
 - **A sandbox read-denial naming `$DSH_HOME/.env`** — implemented as a `readDenyPaths` policy field (a trailing SBPL `deny file-read* file-write*`, a `/dev/null` bwrap bind) and withdrawn on its own evidence. bwrap must create that bind's mount point inside a tree its profile has already made read-only, so it refuses the entire confinement whenever the parent directory is absent — every host that has not stored a credential yet, including a fresh install; Landlock cannot subtract from its own `/` read grant, so every confined call would report `partial` for a file it never hid. A protection that breaks confinement where it works and misreports it where it does not is worse than a documented absence. Denying the whole harness home was rejected earlier for a separate reason: it also covers `sessions/`, and `DSH_SESSION_JSONL` is a documented model-visible capability.
 - **Removing `DSH_HOME` from the model's bash environment** — considered as defense in depth and rejected as theater with a real cost: the default home is a documented convention the agent can reconstruct, while the variable is how legitimate tooling finds harness state. There is no boundary here for it to complement; hiding the pointer would only make the absence harder to see.
-- **Shipping the OS-keychain provider in this round** — it is the only design where the model's processes genuinely cannot read the secret, and it is a sibling package with three platform backends. Sizing it against the rest of this review round would have delayed every other fix; it is recorded as the deferred answer, not as a maybe.
-- **A `replaceRegistration(previous, next)` service method** — the review's shape, but it makes the caller carry the previous handle and lets it pass a mismatched one. Hanging `replace` on the registration handle makes ownership structural: only the registration that holds routes can replace them.
+- **Shipping the OS-keychain provider now** — it is the only design where the model's processes genuinely cannot read the secret, and it is a sibling package with three platform backends. Sizing it against the rest of these fixes would have delayed every other one; it is recorded as the deferred answer, not as a maybe.
+- **A `replaceRegistration(previous, next)` service method** — rejected: it makes the caller carry the previous handle and lets it pass a mismatched one. Hanging `replace` on the registration handle makes ownership structural: only the registration that holds routes can replace them.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 2b66c543bd..6552db1932 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -4,13 +4,13 @@ Status: implemented
 
 [English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
 
-> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
+> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的边界加固——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：它把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
 
 ## 问题
 
-评审发现，凭据路径正在越过它自己划下的边界泄漏。已交付的各个面在 Cordis 启动之前就把 `$DSH_HOME/.env` 提升进了 `process.env`，于是下一次运行时，`credentials-local` 会把它自己存下的每个键都判成来自环境的只读启动覆盖：`describe()` 报告 `source: 'env'` 且 `writable: false`，`set`/`unset` 以被遮蔽为由拒绝，从 web 页面或 TUI 存入的密钥既无法轮换也无法删除，而适配器还在继续使用启动时捕获的那个值。
+凭据路径越过它自己划下的边界发生了泄漏。已交付的各个面在 Cordis 启动之前就把 `$DSH_HOME/.env` 提升进了 `process.env`，于是下一次运行时，`credentials-local` 会把它自己存下的每个键都判成来自环境的只读启动覆盖：`describe()` 报告 `source: 'env'` 且 `writable: false`，`set`/`unset` 以被遮蔽为由拒绝，从 web 页面或 TUI 存入的密钥既无法轮换也无法删除，而适配器还在继续使用启动时捕获的那个值。
 
-存储自身的写路径重演了同一轮评审在 settings-local 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
+存储自身的写路径重演了 settings 写路径 note 在 settings-local 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
 
 在读取一侧，文件的 `0600` 权限挡得住其他 OS 用户，却挡不住模型：它的 bash 与文件系统工具就以同一个用户身份运行。
 
@@ -32,8 +32,8 @@ Status: implemented
 
 - **用沙箱点名拒读 `$DSH_HOME/.env`**——已按 `readDenyPaths` 策略字段实现过（末尾一条 SBPL `deny file-read* file-write*`、一条 `/dev/null` 的 bwrap bind），又被它自己的证据推翻。bwrap 必须在自己 profile 已经置为只读的目录树内部创建该 bind 的挂载点，因此只要父目录不存在，它就会拒绝整次约束——那是每一台还没有存过凭据的主机，包括全新安装；Landlock 无法从它自己对 `/` 的读取授权中减去任何东西，于是每一次受限调用都会为一个它其实从未藏起的文件报 `partial`。一项在生效之处破坏约束、在不生效之处误报的保护，比一条写明的「没有保护」更糟。至于拒掉整个 harness home，早先另有理由被否：它同时覆盖 `sessions/`，而 `DSH_SESSION_JSONL` 是一项成文的、模型可见的能力。
 - **把 `DSH_HOME` 从模型的 bash 环境中移除**——作为纵深防御考虑过，最终按「有真实代价的表演」不予采纳：默认 home 是 agent（智能体）能自行重建的成文约定，而这个变量正是正当工具链定位 harness 状态的途径。这里并不存在一条需要它来补强的边界，藏起指针只会让这份缺席更难被看见。
-- **本轮就交付 OS 钥匙串提供方**——只有这个设计能让模型的进程真正读不到机密，而它是一个带三种平台后端的兄弟包。把它与本轮评审的其余工作放在一起评估体量，会拖慢其他每一项修复；它被记录为那个延后的答案，而不是一个「也许」。
-- **做成 `replaceRegistration(previous, next)` 服务方法**——这是评审给出的形状，但它要求调用方自行携带上一个句柄，也允许它传入一个不匹配的句柄。把 `replace` 挂在注册句柄上，让归属关系变成结构性的：只有持有路由的那一项注册才能替换它们。
+- **现在就交付 OS 钥匙串提供方**——只有这个设计能让模型的进程真正读不到机密，而它是一个带三种平台后端的兄弟包。把它与其余这些修复放在一起评估体量，会拖慢其他每一项；它被记录为那个延后的答案，而不是一个「也许」。
+- **做成 `replaceRegistration(previous, next)` 服务方法**——不予采纳：它要求调用方自行携带上一个句柄，也允许它传入一个不匹配的句柄。把 `replace` 挂在注册句柄上，让归属关系变成结构性的：只有持有路由的那一项注册才能替换它们。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
index 0bb3092b67..de2b1f5fa4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.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 .agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
-2026-07-30-session-end-seed-log-boundary.md: 26cd67ccbfdf5dfc62e44a53c877acf6d2fee34a
-2026-07-30-session-end-seed-log-boundary.zh.md: 70391ba8b629694cc83f1960ea3fdd94cd32f032
+2026-07-30-session-end-seed-log-boundary.md: 8f5c38023c29e6daca3c92d30e633e4d11a52a88
+2026-07-30-session-end-seed-log-boundary.zh.md: 39d1c39b1731f0122efcca0faefefd21e3222c54
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
index 26cd67ccbf..8f5c38023c 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
@@ -36,7 +36,7 @@ The predicate holds for a bracket *this* session inherited, not as a liveness si
 
 ## Alternatives considered
 
-**A boundary written by the persistence coordinator's cold-load path.** Built first as a `session/resumed` boundary and abandoned before merge. It covers no fork, which is the one case where the inherited bracket's owner may still be running. Because the marker was minted at load it also had to be a durable write on a read path, which spread cost across the seam: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, a stored-time floor to keep the clamp monotonic, and a load that failed against a read-only store.
+**A boundary written by the persistence coordinator's cold-load path.** An earlier iteration wrote a `session/resumed` boundary; it lost because it covers no fork — the one case where the inherited bracket's owner may still be running — and because a marker minted at load had to be a durable write on a read path, which spread cost across the seam: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, a stored-time floor to keep the clamp monotonic, and a load that failed against a read-only store.
 
 **A boundary appended at loop start.** The loop calls `resumeWith`, so it covers the resume paths, but it misses `fork()` and `adopt()` entirely, and the event would have to fire on `'startup'` — the source a fork child publishes — so `SessionStartSource` would stop discriminating. It also publishes the session before the marker is appended, so a `session/created` listener could observe a seeded log with no boundary.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
index 70391ba8b6..39d1c39b17 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**由持久化协调器的冷加载路径写入边界。** 最初将其实现为 `session/resumed` 边界，并在合并前放弃。它完全覆盖不到 fork，而 fork 恰恰是继承括号的所有方可能仍然存活的那一种情形。由于标记是在加载时铸造的，它还必须在读取路径上做持久写入，这把成本铺开到整个 seam：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、需要一个已存储时间下限来维持钳制的单调性，以及加载在只读存储上会失败。
+**由持久化协调器的冷加载路径写入边界。** 较早的一版迭代写入的是 `session/resumed` 边界；它落选，一是因为完全覆盖不到 fork——而 fork 恰恰是继承括号的所有方可能仍然存活的那一种情形——二是因为在加载时铸造的标记必须在读取路径上做持久写入，这把成本铺开到整个 seam：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、需要一个已存储时间下限来维持钳制的单调性，以及加载在只读存储上会失败。
 
 **在 loop 启动时追加边界。** loop 调用 `resumeWith`，因此覆盖恢复路径，但完全漏掉 `fork()` 与 `adopt()`，而且事件不得不在 `'startup'` 上触发——那是 fork 子会话发布的来源——于是 `SessionStartSource` 将不再具有区分力。它还会在追加标记之前就发布会话，因此 `session/created` 监听方可能观察到一份没有边界的带种子日志。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
index 14a0ad2bb0..06f69f8d3d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.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 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
-2026-07-30-settings-write-path-integrity.md: f9b56ca83ad3027083884442a051eca102207c24
-2026-07-30-settings-write-path-integrity.zh.md: 1e8ce7eddb6a639512cd792e98fc135f49a8c0be
+2026-07-30-settings-write-path-integrity.md: d59a4524cc704760d7fbdfa286af84da5cbd1926
+2026-07-30-settings-write-path-integrity.zh.md: 5c4651905ffa0dfc1a0f8e080190b875bd9e4afa
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
index f9b56ca83a..d59a4524cc 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-30-settings-write-path-integrity.zh.md)
 
-> Scope: the third review round over `packages/settings/` — write-path data integrity in `dsh-settings-local` (operation chain, read-modify-write, cross-process writer lock, diff-shaped YAML edits) and observer lifecycle in `dsh-settings` (watch disposal, async listener containment, the JSON-shape write boundary). This note reverses one deferral recorded in the [user-settings seam note](2026-07-28-user-settings-seam.md): the cross-process lockfile now ships.
+> Scope: write-path data integrity in `dsh-settings-local` (operation chain, read-modify-write, cross-process writer lock, diff-shaped YAML edits) and observer lifecycle in `dsh-settings` (watch disposal, async listener containment, the JSON-shape write boundary). This note reverses one deferral recorded in the [user-settings seam note](2026-07-28-user-settings-seam.md): the cross-process lockfile now ships.
 
 ## Problem
 
-Review found the provider's write path could destroy state it never observed, and the Service Definition's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the Service Definition side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
+The provider's write path could destroy state it never observed, and the Service Definition's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the Service Definition side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
 
 ## Decision
 
@@ -32,4 +32,4 @@ Review found the provider's write path could destroy state it never observed, an
 
 ## Consequences
 
-`update()` has documented failure modes for the lock deadline and an invalid on-disk document, and rejection messages carry `$`-rooted paths. A crashed holder can leave a lock that requires verified operator removal; automatic age-based takeover would permit overlapping writers. Remaining, documented in the provider README: same-namespace concurrent edits stay last-write-wins (no per-value merge or revision check), a watcher event the OS never delivers leaves the cache stale until the next signal or write, and comments inside replaced arrays or attached inline to changed scalar values go with the value they described. The [user-settings seam note](2026-07-28-user-settings-seam.md)'s deferred-lockfile alternative is superseded by this note. The same defect classes exist in `dsh-credentials-local` (two chains over one `.env`, cached whole-file write-back, post-persist emit) and in the `llm/adapters-updated` fan-out on the stacked branches; those fixes belong to the PRs that introduce the packages and follow this template on merge-up.
+`update()` has documented failure modes for the lock deadline and an invalid on-disk document, and rejection messages carry `$`-rooted paths. A crashed holder can leave a lock that requires verified operator removal; automatic age-based takeover would permit overlapping writers. Remaining, documented in the provider README: same-namespace concurrent edits stay last-write-wins (no per-value merge or revision check), a watcher event the OS never delivers leaves the cache stale until the next signal or write, and comments inside replaced arrays or attached inline to changed scalar values go with the value they described. The [user-settings seam note](2026-07-28-user-settings-seam.md)'s deferred-lockfile alternative is superseded by this note. The same defect classes existed in `dsh-credentials-local` (two chains over one `.env`, cached whole-file write-back, post-persist emit) and in the `llm/adapters-updated` fan-out; the [credential-boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md) applies this template there.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
index 1e8ce7eddb..5c4651905f 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-30-settings-write-path-integrity.md) | 中文
 
-> 范围：对 `packages/settings/` 的第三轮评审——`dsh-settings-local` 的写路径数据完整性（操作链、读-改-写、跨进程写锁、diff 形态的 YAML 编辑）与 `dsh-settings` 的观察者生命周期（watch 的 dispose（资源释放）、异步监听器收容、JSON 形态写入边界）。本 note 推翻了[用户设置 seam note](2026-07-28-user-settings-seam.md)所记录的一项延后决定：跨进程锁文件现已交付。
+> 范围：`dsh-settings-local` 的写路径数据完整性（操作链、读-改-写、跨进程写锁、diff 形态的 YAML 编辑）与 `dsh-settings` 的观察者生命周期（watch 的 dispose（资源释放）、异步监听器收容、JSON 形态写入边界）。本 note 推翻了[用户设置 seam note](2026-07-28-user-settings-seam.md)所记录的一项延后决定：跨进程锁文件现已交付。
 
 ## 问题
 
-评审发现，提供方的写路径可能销毁它从未观察到的状态，而 Service Definition 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
+提供方的写路径可能销毁它从未观察到的状态，而 Service Definition 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
 
 在 Service Definition 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。
 
@@ -38,4 +38,4 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 
 `update()` 对锁获取期限与磁盘文档非法都有成文的失败模式，rejection 消息携带以 `$` 为根的路径。持有者崩溃后可能留下锁，需要操作者核实后移除；若按锁龄自动接管，则会允许多个写入方重叠。仍然存在、且已记录在提供方 README 中的有：同 namespace 并发编辑仍是后写胜出（没有逐值合并，也没有修订号检查）；OS 从未投递的 watcher 事件会让缓存保持陈旧，直到下一个信号或下一次写入；被替换数组内部的注释、以及行内附着在被改标量值上的注释，会随其描述的值一起消失。
 
-[用户设置 seam note](2026-07-28-user-settings-seam.md)里“延后锁文件”那条替代方案已被本 note 取代。同类缺陷还存在于 `dsh-credentials-local`（两条链共用一个 `.env`、按缓存整文件写回、持久化之后才发事件）与堆叠分支上的 `llm/adapters-updated` 扇出；这些修复归引入相应包的那些 PR（Pull Request）所有，向上合并时按本模板处理。
+[用户设置 seam note](2026-07-28-user-settings-seam.md)里“延后锁文件”那条替代方案已被本 note 取代。同类缺陷曾存在于 `dsh-credentials-local`（两条链共用一个 `.env`、按缓存整文件写回、持久化之后才发事件）与 `llm/adapters-updated` 扇出；[credential-boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md) 在那里套用了本模板。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 7fbaf3c2b9..eec7c013a4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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 .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
-2026-07-30-web-config-plane.md: 78fa9cf970dea30fdc842799134bc1d11608c800
-2026-07-30-web-config-plane.zh.md: b8a4347f95a741140a61e1d47f837aa0502d85ee
+2026-07-30-web-config-plane.md: 1af86fc7917cc40b0544bb5c6254994a87ad7a55
+2026-07-30-web-config-plane.zh.md: 15916fe86e2f5e19e9752721917317aa8c39442d
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
index 78fa9cf970..1af86fc791 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-web-config-plane.zh.md)
 
 ## Problem
 
-PR1 made LLM adapter configuration restart-free at the seam, but the only writer was a text editor on `settings.yaml`: the web client had no wire access to settings, credentials, or provider topology, so "store a key, prompt again" still meant leaving the product. Three gaps blocked a config page rather than one: `describe()` returned only the merged effective value (a form cannot tell a user override from a composition default, and serializing it would have shipped `role('secret')` values to every browser), nothing enumerated the providers an adapter *could* run (a bare-mounted `llm-pi-ai` was invisible until configured), and the two adapters both wanted a `deepseek` route key, so the directory could not attribute routes to owning namespaces unambiguously. Hand-maintaining a form per provider was rejected outright — the schemas already exist as schemastery `Config` values, and a second source of field truth drifts.
+The request-level configuration seam made LLM adapter configuration restart-free, but the only writer was a text editor on `settings.yaml`: the web client had no wire access to settings, credentials, or provider topology, so "store a key, prompt again" still meant leaving the product. Three gaps blocked a config page rather than one: `describe()` returned only the merged effective value (a form cannot tell a user override from a composition default, and serializing it would have shipped `role('secret')` values to every browser), nothing enumerated the providers an adapter *could* run (a bare-mounted `llm-pi-ai` was invisible until configured), and the two adapters both wanted a `deepseek` route key, so the directory could not attribute routes to owning namespaces unambiguously. Hand-maintaining a form per provider was rejected outright — the schemas already exist as schemastery `Config` values, and a second source of field truth drifts.
 
 ## Decision
 
@@ -20,7 +20,7 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 **The llm seam declares configurability and announces topology.** `registerConfigurableProviders()` is an all-or-nothing, fiber-scoped directory of `{provider, displayName, settingsNs, settingsPath}` — the addressing a config page needs to open the right settings subtree for a route that may not exist yet; `listConfigurableProviders()` merges with live routes in the wire handler so undeclared live routes still report active. The zero-payload `'llm/adapters-updated'` event fires from all four registration/unregistration commit points with contained listener dispatch (INVARIANT rethrow), following the settings/commands precedent. `llm-deepseek`'s route renamed to `deepseek-official` because the pi-ai catalog legitimately owns `deepseek` as an aggregator entry; pre-release stance, no alias.
 
-**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog takes the row shape the pi-ai provider form introduces: one bordered entry per model, id and display name on the row, and the capacities behind the row's own disclosure, so the two editors read as one design rather than diverging once both land. Every field keeps the indexed `aria-label` that names it. Both capacities are text fields reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: a field holds the typed text while it has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. The shared class names carry this file's token spellings, not that branch's: `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and `--dsw-alias-text-primary` are undeclared, so they resolve to the light-mode literals in their fallback slots — the defect this section was moved off. A styles test now rejects any `--dsw-*` name the token sheet does not declare, so the next editor to name one fails rather than shipping a light-only surface.
+**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The hand-written direction won over adding a hint/grouping system, and a further simplification removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog takes the row shape the pi-ai provider form introduces: one bordered entry per model, id and display name on the row, and the capacities behind the row's own disclosure, so the two editors read as one design rather than diverging. Every field keeps the indexed `aria-label` that names it. Both capacities are text fields reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: a field holds the typed text while it has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. The shared class names carry only declared token spellings: `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and `--dsw-alias-text-primary` are undeclared, so naming them resolves to the light-mode literals in their fallback slots. A styles test now rejects any `--dsw-*` name the token sheet does not declare, so the next editor to name one fails rather than shipping a light-only surface.
 
 **The Models page is a three-domain join with service-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `<ROUTE>_API_KEY` when none exists (the pi-ai profile records the derivation only when a key is entered), so `settings.yaml` never carries a key value; a blank pi-ai key materializes a reference-free profile and preserves provider-native authentication. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized confirmation dialog whose row actions, title, description, and final action identify the same provider; confirmation removes an exact configured+writable derived credential before the profile, while custom, environment, and unidentified targets remain untouched. Both stages are idempotent and a partial failure stays in the dialog for retry. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. The partial-commit and credential-ownership rationale lives in the [provider credential lifecycle note](../bug-fix/2026-08-06-provider-credential-lifecycle.md).
 
@@ -28,12 +28,12 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 - **Serving JSON Schema over the wire** — schemastery's `toJSON()` envelope round-trips `role()`/meta and rehydrates into the validator the client already ships for drafts; converting to JSON Schema loses exactly the role annotations the credential control and secret redaction key on.
 - **A generic schema-driven form renderer** — implemented first, then replaced: field truth without visual hierarchy produced an ugly, unusable card, and making it good meant building a hint vocabulary (primary/advanced grouping, per-field descriptions, array item cards) rivaling the hand-written editor in cost while still fitting no mockup exactly. Two schemas exist today (the deepseek `Config` and the shared pi-ai profile), so hand-writing is two thin namespace-keyed layouts; the drift risk is bounded by save-time schema validation and by unknown fields staying untouched in the document.
-- **Masking secrets per-field with sentinel backfill on `replace`** — the PR1 decision (secrets are references) already deleted the stored-literal case for the product default; structural redaction plus a write-only credential path handles the residue without teaching every writer a sentinel protocol.
+- **Masking secrets per-field with sentinel backfill on `replace`** — the request-level seam decision (secrets are references) already deleted the stored-literal case for the product default; structural redaction plus a write-only credential path handles the residue without teaching every writer a sentinel protocol.
 - **Storing the typed key as a literal `apiKey` setting** — the v1 "one API key input" requirement could have written the literal into the profile, but every UI removal path rebuilds the user section from the *redacted* layers, so any reset or row deletion would silently drop stored sibling keys; deriving a reference keeps the input single-field while keeping `settings.yaml` secret-free and every replace safe.
-- **A `models` bridge plugin owning provider configuration** — same rejection as PR1: per-plugin namespaces plus a four-field directory declaration give the UI everything it needs; the bridge's unified dict re-imports the adapter-mapping indirection.
+- **A `models` bridge plugin owning provider configuration** — same rejection as in the request-level seam note: per-plugin namespaces plus a four-field directory declaration give the UI everything it needs; the bridge's unified dict re-imports the adapter-mapping indirection.
 - **Page-side polling instead of pushed frames** — the mux already carries `host/commands-changed`; three more frames cost one shape each and make a second tab, an external `settings.yaml` edit, and a settings-born route converge at event speed.
 - **Hard-coding `$DSH_HOME/settings.yaml` or returning `documentPath` through `host.openPath` in the browser** — rejected because `settings-local.path` may select another YAML/JSON document, non-file providers have no Host path, and a general path request makes the browser the authority for a local filesystem target. Provider preparation is the authoritative source, and the Host-owned operation feeds the existing opener.
 
 ## Consequences
 
-The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; Service Definition, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
+The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; Service Definition, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) with no compatibility alias. The renderer replacement needed no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index b8a4347f95..15916fe86e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯一的写入方还是直接编辑 `settings.yaml` 的文本编辑器：web 客户端没有触达设置、凭据或提供方拓扑的任何 wire 通道，「存入密钥、再次发起提示」于是仍意味着离开产品本身。挡住配置页的缺口不是一个，而是三个：`describe()` 只返回合并后的生效值（表单分不清用户覆盖与组合默认值，而且照原样序列化会把 `role('secret')` 的值发到每一个浏览器）；没有任何东西枚举适配器*可以*运行的提供方（裸挂载的 `llm-pi-ai` 在配置之前完全不可见）；两个适配器又都想要 `deepseek` 这个路由键，目录因此无法无歧义地把路由归到拥有它的 namespace 名下。为每个提供方手工维护一份表单被直接否决——schema 已经以 schemastery `Config` 值的形式存在，第二份字段真源注定漂移。
+请求级配置 seam 让 LLM（大语言模型）适配器配置免重启，但唯一的写入方还是直接编辑 `settings.yaml` 的文本编辑器：web 客户端没有触达设置、凭据或提供方拓扑的任何 wire 通道，「存入密钥、再次发起提示」于是仍意味着离开产品本身。挡住配置页的缺口不是一个，而是三个：`describe()` 只返回合并后的生效值（表单分不清用户覆盖与组合默认值，而且照原样序列化会把 `role('secret')` 的值发到每一个浏览器）；没有任何东西枚举适配器*可以*运行的提供方（裸挂载的 `llm-pi-ai` 在配置之前完全不可见）；两个适配器又都想要 `deepseek` 这个路由键，目录因此无法无歧义地把路由归到拥有它的 namespace 名下。为每个提供方手工维护一份表单被直接否决——schema 已经以 schemastery `Config` 值的形式存在，第二份字段真源注定漂移。
 
 ## 决策
 
@@ -20,7 +20,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 **llm seam 声明可配置性并公布拓扑。**`registerConfigurableProviders()` 是一个全有或全无、以 fiber 为作用域的目录，条目为 `{provider, displayName, settingsNs, settingsPath}`——这正是配置页要为一条可能尚不存在的路由打开正确设置子树时所需要的寻址；`listConfigurableProviders()` 在 wire 处理器里与存活路由合并，未声明的存活路由因此仍报告为激活。零负载的 `'llm/adapters-updated'` 事件从全部四个注册／注销提交点触发，listener 派发带异常隔离（INVARIANT 重抛），沿用 settings/commands 的先例。`llm-deepseek` 的路由重命名为 `deepseek-official`，因为 pi-ai catalog 名正言顺地拥有 `deepseek` 这个聚合器条目；依预发布立场，不设别名。
 
-**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录采用 pi-ai 提供方表单引入的行形态：每个模型一个带边框的条目，ID 与显示名称落在行上，容量则收在该行自己的折叠区里，使两个编辑器呈现为同一套设计，而不是在双方都落地后各自分岔。每个字段都保留那个为其命名的带序号 `aria-label`。两项容量都是文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：字段持有焦点期间保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。共用的类名承载的是本文件的 token 写法，而非那个分支的：`--dsw-alias-border-subtle`、`--dsw-alias-text-tertiary` 和 `--dsw-alias-text-primary` 均未声明，于是它们解析为各自回退槽位中的亮色模式字面值——正是本节此前迁离的那个缺陷。现在有一个样式测试会拒绝 token 表未声明的任何 `--dsw-*` 名称，因此下一个写出这类名称的编辑者会当场失败，而不是交付一个只有亮色的界面。
+**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。手写方向胜过了再加一套提示／分组系统，进一步的简化又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录采用 pi-ai 提供方表单引入的行形态：每个模型一个带边框的条目，ID 与显示名称落在行上，容量则收在该行自己的折叠区里，使两个编辑器呈现为同一套设计，而不是各自分岔。每个字段都保留那个为其命名的带序号 `aria-label`。两项容量都是文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：字段持有焦点期间保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。共用的类名只承载已声明的 token 写法：`--dsw-alias-border-subtle`、`--dsw-alias-text-tertiary` 和 `--dsw-alias-text-primary` 均未声明，写出它们就会解析为各自回退槽位中的亮色模式字面值。现在有一个样式测试会拒绝 token 表未声明的任何 `--dsw-*` 名称，因此下一个写出这类名称的编辑者会当场失败，而不是交付一个只有亮色的界面。
 
 **Models 页是一次三领域联接，应用语义与服务同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `<ROUTE>_API_KEY`（仅在输入密钥时，pi-ai profile 才会记录该派生），因此 `settings.yaml` 从不携带密钥值；留空 pi-ai 密钥会具化一个不带引用的 profile，并保留提供方原生认证。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化确认对话框，其行操作、标题、说明和最终操作都会点名同一个提供方；确认后会先清除与派生目标精确匹配且已配置、可写的凭据，再删除 profile，自定义目标、环境目标和无法识别的目标则保持不变。两个阶段都具备幂等性，部分失败会留在对话框中供重试。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。部分提交与凭据所有权的理由记录在[提供方凭据生命周期 note](../bug-fix/2026-08-06-provider-credential-lifecycle.md)中。
 
@@ -28,12 +28,12 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 - **在 wire 上改发 JSON Schema**——schemastery 的 `toJSON()` 信封能往返保留 `role()`/meta，并还原成客户端为草稿校验本就自带的那个校验器；转换成 JSON Schema 丢掉的恰恰是凭据控件与 secret 脱敏所依赖的角色注解。
 - **通用的 schema 驱动表单渲染器**——先实现、后被替换：如实呈现字段却缺失视觉层级，产出的卡片丑陋且不可用；要把它做好，就意味着构建一套提示词汇（主要／进阶分组、逐字段描述、数组项卡片），成本堪比手写编辑器，却仍无法与任何设计稿完全吻合。今天存在两份 schema（deepseek 的 `Config` 与共享的 pi-ai profile），手写因此就是两套以 namespace 为键的薄布局；漂移风险由保存时的 schema 校验以及未知字段在文档中的原样保留共同约束。
-- **逐字段脱敏机密并在 `replace` 时回填哨兵值**——PR1 的决策（机密是引用）已经为产品默认形态删掉了「存储字面量」这种情况；结构化脱敏加上只写的凭据通道足以处理残余情形，无需让每个写入方都学会一套哨兵协议。
+- **逐字段脱敏机密并在 `replace` 时回填哨兵值**——请求级 seam 的决策（机密是引用）已经为产品默认形态删掉了「存储字面量」这种情况；结构化脱敏加上只写的凭据通道足以处理残余情形，无需让每个写入方都学会一套哨兵协议。
 - **把键入的密钥存成字面 `apiKey` 设置**——v1「单个 API 密钥输入框」的需求本可以把字面量直接写进 profile，但 UI 的每条删除路径都会从*脱敏后的*各层重建用户分节，任何重置或整行删除都会静默丢掉已存储的兄弟密钥；派生引用让输入保持单字段，同时让 `settings.yaml` 不含机密、每一次 replace 都安全。
-- **由 `models` 桥接插件持有提供方配置**——与 PR1 相同的否决理由：按插件划分的 namespace 加上四字段的目录声明已经给了 UI 需要的一切；桥接层的统一字典会把适配器映射那层间接重新引进来。
+- **由 `models` 桥接插件持有提供方配置**——与请求级 seam note 相同的否决理由：按插件划分的 namespace 加上四字段的目录声明已经给了 UI 需要的一切；桥接层的统一字典会把适配器映射那层间接重新引进来。
 - **页面侧轮询而非推送帧**——mux 已经承载 `host/commands-changed`；再加三个帧各自只多一个形状的成本，就让第二个标签页、外部的 `settings.yaml` 编辑和由设置催生的路由都以事件速度收敛。
 - **在浏览器中硬编码 `$DSH_HOME/settings.yaml`，或经 `host.openPath` 回传 `documentPath`**——否决，因为 `settings-local.path` 可能选择另一份 YAML/JSON 文档、非文件提供方没有 Host 路径，而且通用路径请求会让浏览器成为本地文件系统目标的权威。提供方的准备操作才是权威来源，由 Host 持有的操作会把结果交给现有打开器。
 
 ## 后果
 
-整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；Service Definition、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
+整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；Service Definition、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器不需要任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 37ab3eda38..abced92b1a 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.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 .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
-2026-07-31-code-runtime-portable-identifier-seam.md: ba2aa8eeabb823978fca32a59d98d56971784a92
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 689ffa1b1ffcb5be1e2aa2bd9cd49c2ae40ba7ee
+2026-07-31-code-runtime-portable-identifier-seam.md: f3eba1ac25fab67aa91da97d1991fc613dc449d1
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: f38463a1405712a61f7ff88aabc1bc8fe96871ae
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
index ba2aa8eeab..f3eba1ac25 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-31-code-runtime-portable-identifier-seam.zh.md)
 
 The code-runtime seam promises that a binding-namespace list valid on one backend is valid on every backend, so a Code Mode consumer can hand the same bindings to any registered runtime without knowing its language. The first backend, `dsh-code-runtime-worker`, privately owned the identifier rules that enforce part of that promise: an `IDENTIFIER` regex that allowed the JS-only `$`, a `RESERVED_WORDS` set holding only ECMAScript keywords, and a `RESERVED_ERROR_PROPERTIES` set of three JS `Error` slots. Those rules described the worker's own language, not the seam's portability contract.
 
-A second backend written against a different language (CPython, arriving in a later PR of this stack) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so a Service provider reached into a sibling Service provider. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
+A second backend written against a different language (CPython) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so a Service provider reached into a sibling Service provider. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
 
 ## Decision
 
@@ -21,13 +21,13 @@ The Service Definition package (`@deepseek-ai/dsh-code-runtime`) exports the por
 
 The Service Definition also narrows the portable identifier subset to `[A-Za-z_][A-Za-z0-9_]*` (documented on `CodeBindingNamespace.global` and `CodeBindingErrorClass`), dropping the JS-only `$`. The worker consumes the shared constants directly under their exported names — `PORTABLE_RESERVED_WORDS` for both binding-global and error-class names, `RESERVED_BINDING_GLOBALS` for backend-owned slots, `RESERVED_ERROR_MEMBERS` plus `DUNDER_MEMBER` for error members — with no local re-alias; its `IDENTIFIER` regex loses `$`.
 
-The constants live in the Service Definition even though only one backend ships in this PR: the whole point is that the contract is language-agnostic and owned above any single language. A Service provider that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
+The constants live in the Service Definition even though the worker is the only shipped backend: the whole point is that the contract is language-agnostic and owned above any single language. A Service provider that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
 
 ## Scope
 
-This PR delivers only the Service Definition extension and the worker's adoption of it. No Python backend, `py-types` renderer, or Code Mode language dispatch ships here — they are later PRs in the stack that depend on these exports. The Service Definition README's worker-only wording is left unchanged for the same reason: linking to a `dsh-code-runtime-python` README that does not yet exist would break the dead-link gate.
+This decision delivers only the Service Definition extension and the worker's adoption of it. The `py-types` renderer and Code Mode language dispatch are owned by the [language-dispatch note](../feature/2026-07-31-code-mode-language-dispatch.md); a Python backend does not exist yet. The Service Definition README keeps its worker-only wording for that reason: linking to a `dsh-code-runtime-python` README that does not exist would break the dead-link gate.
 
-`RESERVED_BINDING_GLOBALS` currently encodes the not-yet-merged Python bootstrap's concrete design: it seeds exactly `__builtins__`/`__name__` and wraps the program under `__dsh_main__`. The Python-backend PR that seeds any additional module global (`__doc__`, `__loader__`, `__spec__`, `__file__`, `__package__`, …) MUST widen this set in the same change, exactly as adding a language widens `PORTABLE_RESERVED_WORDS` — a name the bootstrap seeds but the set omits is the portability split this contract exists to prevent.
+`RESERVED_BINDING_GLOBALS` encodes the Python bootstrap's concrete design ahead of the backend itself: it seeds exactly `__builtins__`/`__name__` and wraps the program under `__dsh_main__`. A Python backend that seeds any additional module global (`__doc__`, `__loader__`, `__spec__`, `__file__`, `__package__`, …) MUST widen this set in the same change, exactly as adding a language widens `PORTABLE_RESERVED_WORDS` — a name the bootstrap seeds but the set omits is the portability split this contract exists to prevent.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 689ffa1b1f..f38463a140 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
-一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使一个 Service provider 伸手进入另一个兄弟 Service provider。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
+一个针对不同语言（CPython）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使一个 Service provider 伸手进入另一个兄弟 Service provider。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
@@ -21,13 +21,13 @@ Service Definition 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量
 
 Service Definition 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以这些常量的导出名称消费它们——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 Service Definition：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的 Service provider 才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管 worker 是唯一已交付的后端，这些常量仍置于 Service Definition：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的 Service provider 才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
 
 ## Scope
 
-本 PR 只交付 Service Definition 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。Service Definition README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
+本决策只交付 Service Definition 扩展与 worker 对它的采用。`py-types` 渲染器与 Code Mode 的语言分发归[语言分发 note](../feature/2026-07-31-code-mode-language-dispatch.md)所有；Python 后端尚不存在。Service Definition README 因此保留仅描述 worker 的措辞：链接到一个不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
-`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
+`RESERVED_BINDING_GLOBALS` 先于后端本身编码了 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index dfe291e9d0..0a007fc184 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
-2026-08-02-typert-remote-method-calls.zh.md: 2290b701eff7ca601b500efbfcf7bdc59c01bcba
+2026-08-02-typert-remote-method-calls.md: b316d1a42c4f69c8e1163f1f36249b61a7d126ef
+2026-08-02-typert-remote-method-calls.zh.md: 02714de3c522ce597e89976b6e03d455ff0bf872
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index f3db8b9eec..b316d1a42c 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -341,7 +341,7 @@ Remote DTS, Remote JS, `TypeRTClientRemote`, `InvocationDescriptor`, the Remote
 
 A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteScope`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
 
-TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring are outside this phase.
+TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring remain deferred outside this decision.
 
 The Web already depends on build artifacts such as `lib/client.js`, so it requires a complete `build:lib` before startup. After the Host Remote contract changes, developers rebuild the lib and then start or restart the Web. Incremental watching of the Remote contract is not implemented.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 2290b701ef..02714de3c5 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -341,7 +341,7 @@ Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote
 
 未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteScope` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
 
-TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
+TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均仍延后，不在本决策之内。
 
 Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 约定变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 0b7c4c42a8..4ba2d1dd8f 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.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 .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
-2026-08-03-pi-ai-declared-provider-catalog.md: f4b5a8565dbeb836c7aa4edb9c565f649de20f0a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: 61e2053efe4dd1234bcd319eb989d946639d2e86
+2026-08-03-pi-ai-declared-provider-catalog.md: 45de54f29e718ed1c9364b03da762700e1282e7b
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: 43206bc21dfa74f6ddf0583c72dc4e8be1dbb9e5
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
index f4b5a8565d..45de54f29e 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
@@ -14,7 +14,7 @@ The adapter also streamed through `streamSimple` from `@earendil-works/pi-ai/com
 
 A provider route is a **declaration**, and the installed catalog is its default. `resolveProfiles` no longer checks route keys against `getBuiltinProviders()`. Instead each route resolves to a materialized model list plus the pi-ai `Provider` that serves it:
 
-- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — at this note's writing `id`, `name`, `contextWindow`, `maxTokens`; [[2026-08-08-pi-ai-per-model-reasoning-declarations]] later added `reasoningEfforts` and `compat`, which is also where the original "reasoning rides the installed entry or is absent" stance was revisited (a bare capability flag stays rejected; a full per-level declaration with wire spellings does not have its problem). Pricing and input modalities remain absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Materialization spreads the installed entry and overrides the configured fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
+- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — `id`, `name`, `contextWindow`, `maxTokens`; [[2026-08-08-pi-ai-per-model-reasoning-declarations]] later added `reasoningEfforts` and `compat`, which is also where the original "reasoning rides the installed entry or is absent" stance was revisited (a bare capability flag stays rejected; a full per-level declaration with wire spellings does not have its problem). Pricing and input modalities remain absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Materialization spreads the installed entry and overrides the configured fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
 - `provider.ts` builds the route's `Provider`. A catalog route that keeps its catalog protocol **reuses** the installed provider with `getModels()` replaced; every other route is built by `createProvider()` over a protocol table whose entries are the same `@earendil-works/pi-ai/api/*.lazy` factories pi-ai's own provider factories use. That table is narrower than pi-ai's full API set on purpose — it holds only protocols a profile can completely describe with a key, an endpoint, and headers, so Bedrock (SigV4 plus a region), Vertex (project, location, ADC), Azure (provider environment plus an api-version), and Codex (OAuth) are absent rather than offered as routes that cannot authenticate. Catalog routes still reach them through their own provider; only an explicit override is refused.
 - `adapter.ts` turns each resolution into an **immutable snapshot** — the profiles plus a `createModels()` collection holding those providers — and every operation captures a whole snapshot before its first `await`.
 - A model's **explicitly configured** `maxTokens` becomes the seam's `defaultMaxTokens`. The value inherited from the installed catalog does not: pi-ai requires `Model.maxTokens` as the model's output *capability*, while `defaultMaxTokens` is a cap the deployment chose to send on requests that name none, and materializing the former as the latter would start capping every request at a number nobody picked.
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index 61e2053efe..43206bc21d 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 提供方路由是一份**声明**，已安装 catalog 是它的默认值。`resolveProfiles` 不再拿路由键去核对 `getBuiltinProviders()`，而是把每条路由解析成一份物化模型列表，外加服务它的 pi-ai `Provider`：
 
-- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理（reasoning）沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
+- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——`id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理（reasoning）沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
 - `provider.ts` 构造路由的 `Provider`。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换 `getModels()`；其余路由都由 `createProvider()` 基于一张协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的 `@earendil-works/pi-ai/api/*.lazy` factory。该表刻意窄于 pi-ai 的完整 API 集合——只保留 profile 能用密钥、端点与标头完整描述的协议，因此 Bedrock（SigV4 加 region）、Vertex（project、location、ADC）、Azure（提供方环境加 api-version）与 Codex（OAuth）不在其中，而不是被当作无法认证的路由提供出去。catalog 路由仍可经自己的 provider 抵达它们；被拒的只有显式覆盖。
 - `adapter.ts` 把每次解析变成一份**不可变快照**——profiles 加上持有这些 provider 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份。
 - 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出*能力*，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 989393cfc3..8979270e36 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: dc24fd4eb57294b73c3d2f8935418182726b35c2
-2026-08-04-configuration-source-ownership.zh.md: 20a8aebb626cf2282b7ddf27540be2c05eaae946
+2026-08-04-configuration-source-ownership.md: d656d329cbc5b3dfbae2561775ed1afc878cebd0
+2026-08-04-configuration-source-ownership.zh.md: 29ef3b83d18d8836b28e4c151ad44c52542b0a11
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index dc24fd4eb5..d656d329cb 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -66,7 +66,7 @@ The line is that these take effect with no user action, before any turn, outside
 
 **Audit an allowlist of `DSH_*` variables a `.env` may set.** Rejected: the list would have to be re-audited on every new switch, and the failure mode of forgetting is silent. Denying the namespace fails safe.
 
-**Rank a bootstrap variable below the process layer instead of rejecting it.** Rejected: `PATH` and `NODE_OPTIONS` have no meaningful "loser" behavior — a user who put one in a `.env` believes it applies, and silently ignoring it is the "my setting has no effect" failure this whole series exists to remove.
+**Rank a bootstrap variable below the process layer instead of rejecting it.** Rejected: `PATH` and `NODE_OPTIONS` have no meaningful "loser" behavior — a user who put one in a `.env` believes it applies, and silently ignoring it is the "my setting has no effect" failure this decision exists to remove.
 
 **Build the snapshot as a three-package capability seam (`environment` / `environment-local` / consumers).** Rejected as premature: the producer runs before Cordis exists and there is no second implementation to select. The repository rule is to not split preemptively.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index 20a8aebb62..29ef3b83d1 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -68,7 +68,7 @@ inherited process environment      (read-only, wins)
 
 **审查出一份 `.env` 可设置的 `DSH_*` 白名单。** 否决：每新增一个开关都要重新审查，而遗漏的失败模式是静默的。拒绝整个命名空间是 fail safe。
 
-**把 bootstrap 变量排在 process 层之下，而不是拒绝它。** 否决：`PATH` 和 `NODE_OPTIONS` 没有有意义的「输了之后」行为——把它写进 `.env` 的用户认为它生效，而静默忽略正是整个系列要消除的那种「我的设置没有效果」。
+**把 bootstrap 变量排在 process 层之下，而不是拒绝它。** 否决：`PATH` 和 `NODE_OPTIONS` 没有有意义的「输了之后」行为——把它写进 `.env` 的用户认为它生效，而静默忽略正是本决策要消除的那种「我的设置没有效果」。
 
 **把快照做成三包能力 seam（`environment` / `environment-local` / 消费方）。** 作为过早拆分而否决：生产方在 Cordis 存在之前就运行，也没有第二个实现需要选择。仓库规则是不要预先拆分。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index 141a08a5b6..c34594bd36 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.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 .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
-2026-08-04-declaring-a-provider-from-the-models-page.md: 53996e488c467e00754837b83b7a33994d4813ee
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 3a952aa0a02e0b2906bf16bcc46d14a8f7f71bc4
+2026-08-04-declaring-a-provider-from-the-models-page.md: 44441da5427dbcd3f0651c2c137a5132ff6d968b
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 974c4fa5be0893e8fdf6a9142877a8b966708dab
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
index 53996e488c..44441da542 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
@@ -26,7 +26,7 @@ The protocol choices come from the namespace's **own schema**, read through the
 
 **Declare a provider through `ProviderEditor` with extra fields.** One card instead of two, but the editor is addressed by `settingsPath`, and a route being named has no path yet. Recomputing the path per keystroke would remount the card and discard the draft; deferring it would mean the editor's whole write path no longer described what it was editing.
 
-**Add a wire field for the protocol list.** Explicit, and the obvious first instinct. But the settings schema already crosses the wire and already contains the union, so a second copy could disagree with the first — and the one the adapter enforces is the schema.
+**Add a wire field for the protocol list.** Explicit. But the settings schema already crosses the wire and already contains the union, so a second copy could disagree with the first — and the one the adapter enforces is the schema.
 
 **Fetch against the stored profile instead of the live form.** No key would leave the form for an unsaved provider. But the flow that needs fetching most is the one where nothing is stored yet, and a form whose endpoint was edited would quietly interrogate the old one.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index 3a952aa0a0..974c4fa5be 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 **在 `ProviderEditor` 上加字段来声明提供方。** 两张卡片变一张，但编辑器由 `settingsPath` 寻址，而正在被命名的路由还没有路径。逐次按键重算路径会让卡片重新挂载并丢掉草稿；推迟计算则意味着编辑器的整条写入路径不再描述它正在编辑的东西。
 
-**为协议列表新增一个协议字段。** 显式，也是最直觉的第一反应。但 settings schema 本来就会跨越协议层、本来就含有那个 union，因此第二份副本可能与第一份不一致——而适配器强制执行的是 schema 那一份。
+**为协议列表新增一个协议字段。** 显式。但 settings schema 本来就会跨越协议层、本来就含有那个 union，因此第二份副本可能与第一份不一致——而适配器强制执行的是 schema 那一份。
 
 **针对已存 profile 而非实时表单发起获取。** 对尚未保存的提供方来说，密钥就不会离开表单。但最需要获取的恰恰是「什么都还没存」的那条流程，而端点已修改的表单会悄悄去询问旧地址。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index c12ec3a68c..ae92bdeafa 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.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 .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
-2026-08-06-subagent-list-identity-projection.md: 727c9113fc95a85e6c2732902289a49a76ee8a8d
-2026-08-06-subagent-list-identity-projection.zh.md: c499247a1bd6bd4c971638a29e82f35b16b64690
+2026-08-06-subagent-list-identity-projection.md: db7ff085382c52fd5adbe5beab42a84524a64d3f
+2026-08-06-subagent-list-identity-projection.zh.md: a6b5cea851d284fa5c2a60f830913900576dfb38
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
index 727c9113fc..db7ff08538 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
@@ -16,7 +16,7 @@ The root cause is that the [durable-subagent-catalog decision](../feature/2026-0
 
 mode and label are folded by the new `subagent` projection unit (pure identity, two arms), and the unit is the sole authority over the fold rules; `listChildren` no longer depends on session-query — enumeration is a subagent-owned live-preferred merge, and value retrieval walks a three-rung compute-and-discard ladder: a live child synchronously reads the registry's existing watermark cache (zero log reads); a cold child first asks the optional `sessionProjectionCache` checkpoint, and a served identity that passes the seq gate is final; otherwise it pays one full `persistence.inspect` read plus one `registry.restore` fold. No index, no cache of its own, no write-back.
 
-There are three families of escape from the per-child scan: promote mode/label into the header (the write path pays); build a durable derivation for the projection (a checkpoint ladder, or values landed during query-index rebuild with read-side reconciliation); or compute at read time (live from the watermark cache, cold from one full read). This note takes the third. "Values landed with the query index" was once this note's settled direction and was under construction for a time, then retired wholesale: query infrastructure was forced to learn domain vocabulary while the sole consumer is satisfied by read-time computation — the live child's zero reads come for free from session-projection's existing watermark cache, and the cold child's single full read is explicitly accepted as compute-and-discard. The first two routes and the retirement rationale are detailed under Alternatives considered.
+There are three families of escape from the per-child scan: promote mode/label into the header (the write path pays); build a durable derivation for the projection (a checkpoint ladder, or values landed during query-index rebuild with read-side reconciliation); or compute at read time (live from the watermark cache, cold from one full read). This note takes the third. "Values landed with the query index" was retired wholesale: query infrastructure was forced to learn domain vocabulary while the sole consumer is satisfied by read-time computation — the live child's zero reads come for free from session-projection's existing watermark cache, and the cold child's single full read is explicitly accepted as compute-and-discard. The first two routes and the retirement rationale are detailed under Alternatives considered.
 
 Key points:
 
@@ -147,19 +147,19 @@ Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entir
 
 **mode/label into SessionHeader.** The strongest zero-read guarantee — rows form from the header alone. But a header shape change propagates into both persistence backends and the header compatibility check; SQLite rejects pre-existing data outright, and JSONL pre-existing data can only degrade to unknown or be backfilled. Read-time computation's answer for pre-existing data is "one `inspect` computation on first listing", touching no durable format.
 
-**The projection-cache ladder (v3 draft: `cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
+**The projection-cache ladder (`cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
 
 **A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new persistence primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
 
-**Optional mode/label on list rows (one v4 draft).** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
+**Optional mode/label on list rows.** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
 
-**Deleting diagnostic rows outright (one v5 draft).** Deletion turns corpus-corruption visibility into rows silently vanishing, and wire/tool/GUI would each have to absorb contract and snapshot changes; retention only asks the list side to derive the classification from projection-value absence and activity, at zero cost. That damaged, dead child sessions in the corpus must be visible is the original motivation for diagnostics' existence, and with retention the consuming surfaces stay wholly unchanged.
+**Deleting diagnostic rows outright.** Deletion turns corpus-corruption visibility into rows silently vanishing, and wire/tool/GUI would each have to absorb contract and snapshot changes; retention only asks the list side to derive the classification from projection-value absence and activity, at zero cost. That damaged, dead child sessions in the corpus must be visible is the original motivation for diagnostics' existence, and with retention the consuming surfaces stay wholly unchanged.
 
-**A registry computation failure channel (per-unit fault tolerance plus a supplementary `failures` field).** To report corruption and unrecognized versions to consumers, we once considered having the registry catch unit exceptions and attach a per-key failure state beside the snapshot. Rejected: a failure is not a value and needs no channel — a unit never throws, absence is itself the signal, worst case the computation comes back empty, and how that is presented is the consumer's problem. The discussion of this route left one independent observation behind: the vendored Cordis `emit` ([vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)) catches nothing a listener throws, so with the projection driver hanging off `session/event`, a unit exception would escape along emit — which adds weight to the "a unit never throws" discipline, but fixing emit fault tolerance is outside this note's scope.
+**A registry computation failure channel (per-unit fault tolerance plus a supplementary `failures` field).** To report corruption and unrecognized versions to consumers, the registry would catch unit exceptions and attach a per-key failure state beside the snapshot. Rejected: a failure is not a value and needs no channel — a unit never throws, absence is itself the signal, worst case the computation comes back empty, and how that is presented is the consumer's problem. An independent observation: the vendored Cordis `emit` ([vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)) catches nothing a listener throws, so with the projection driver hanging off `session/event`, a unit exception would escape along emit — which adds weight to the "a unit never throws" discipline, but fixing emit fault tolerance is outside this note's scope.
 
-**Values landed with query index preparation (the v4/v5 settled design, built for a time).** Projection values folded into session index rows during the sqlite backend's reconciliation rebuild, for zero log reads in the steady read state; the `projectionsFor` bulk read face, the invalidation reconciliation of row values stored against the `(key → stateVersion)` registration set, and the SCHEMA bump were all actually built. Retired wholesale: the direction was backwards — query infrastructure was forced to learn domain vocabulary (projection columns, registration-set reconciliation) while the sole consumer, the subagent list, is satisfied by read-time computation; with consumers down to zero, this derived persistence has no reason to exist. `SESSION_QUERY_PROJECTIONS_UNAVAILABLE` was deleted along with the read face.
+**Values landed with query index preparation.** Projection values folded into session index rows during the sqlite backend's reconciliation rebuild, for zero log reads in the steady read state: the `projectionsFor` bulk read face, the invalidation reconciliation of row values stored against the `(key → stateVersion)` registration set, and the SCHEMA bump. Retired wholesale: the direction was backwards — query infrastructure was forced to learn domain vocabulary (projection columns, registration-set reconciliation) while the sole consumer, the subagent list, is satisfied by read-time computation; with consumers down to zero, this derived persistence has no reason to exist. `SESSION_QUERY_PROJECTIONS_UNAVAILABLE` was deleted along with the read face.
 
-**Subagent hand-rolled parsing plus an in-process memo plus creation seeding (v6 draft).** To excise the session-query dependency, we once considered the subagent package parsing descriptor events itself, avoiding repeated full reads with an in-process memo, and seeding initial values at creation. Superseded by the v7 ladder: live goes through the `sessionProjections` watermark cache and cold through `registry.restore`, reusing the registry's single fold authority — no second copy of descriptor-interpretation logic appears, and no process-state cache or seeding ordering is introduced.
+**Subagent hand-rolled parsing plus an in-process memo plus creation seeding.** To excise the session-query dependency, the subagent package would parse descriptor events itself, avoid repeated full reads with an in-process memo, and seed initial values at creation. Superseded by the shipped ladder: live goes through the `sessionProjections` watermark cache and cold through `registry.restore`, reusing the registry's single fold authority — no second copy of descriptor-interpretation logic appears, and no process-state cache or seeding ordering is introduced.
 
 **DeepReadonly on the session-query output surface (a read-path overhaul experiment).** Make the public query outputs deeply readonly to pin immutable borrowing at the type level. Rejected on evidence: 3 TS2589 occurrences (excessively deep type instantiation) plus 17 sites of array-position contagion (consumers' array methods and spread sites forced to follow); deep immutability is guaranteed by core/session's runtime deep freeze, and that read-path overhaul is not part of this note.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index c499247a1b..a6b5cea851 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级"算完即止"阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
 
-消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"曾是本记录的定稿方向并一度施工，最终整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
+消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"已整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
 
 要点：
 
@@ -147,19 +147,19 @@ export type SubagentListEntry =
 
 **mode/label 进 SessionHeader。** 零读保证最强——列表只看 header 就能成行。但 header 形状变更传导两个 persistence backend 与 header 兼容检查；SQLite 存量直接拒收，JSONL 存量只能 unknown 降级或 backfill。读时现算对存量的答案是"第一次列表一次 `inspect` 现算"，不碰持久格式。
 
-**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
+**projection-cache 阶梯（`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
 
 **给 persistence 加有界读原语抢救存量。** 为一次性问题新开 persistence 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
-**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
+**list 行 mode/label 可选化。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
 
-**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担约定与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+**彻底删除 diagnostic 行。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担约定与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
 
-**registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
+**registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，由 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
 
-**值随 query 索引 preparation 落库（v4/v5 定稿，一度施工）。** 投影值在 sqlite backend 的对账重建里折叠落进 session 索引行，读稳态零日志；`projectionsFor` 批量读面、行值随 `(key → stateVersion)` 注册集存储的失效对账与 SCHEMA bump 均已施工过。整体退役：方向反了——查询基础设施被迫认识领域词汇（投影列、注册集对账），而唯一消费方 subagent 列表读时现算即可满足；消费方归零后，这套派生持久化没有存在理由。`SESSION_QUERY_PROJECTIONS_UNAVAILABLE` 随读面一并删除。
+**值随 query 索引 preparation 落库。** 投影值在 sqlite backend 的对账重建里折叠落进 session 索引行，读稳态零日志：`projectionsFor` 批量读面、行值随 `(key → stateVersion)` 注册集存储的失效对账与 SCHEMA bump。整体退役：方向反了——查询基础设施被迫认识领域词汇（投影列、注册集对账），而唯一消费方 subagent 列表读时现算即可满足；消费方归零后，这套派生持久化没有存在理由。`SESSION_QUERY_PROJECTIONS_UNAVAILABLE` 随读面一并删除。
 
-**subagent 手工 parse 加进程 memo 加创建播种（v6 稿）。** 为摘除 session-query 依赖，曾考虑 subagent 自己解析描述符事件、以进程内 memo 避免重复整读、创建时播种初值。被 v7 阶梯取代：live 走 `sessionProjections` 水位缓存、cold 走 `registry.restore`，复用 registry 这一份折叠权威，不再出现第二份描述符解释逻辑，也不引入进程态缓存与播种时序。
+**subagent 手工 parse 加进程 memo 加创建播种。** 为摘除 session-query 依赖，由 subagent 包自己解析描述符事件、以进程内 memo 避免重复整读、创建时播种初值。被已交付的阶梯取代：live 走 `sessionProjections` 水位缓存、cold 走 `registry.restore`，复用 registry 这一份折叠权威，不再出现第二份描述符解释逻辑，也不引入进程态缓存与播种时序。
 
 **session-query 输出面 DeepReadonly（读路径改造实验）。** 公开查询输出深只读化，以在类型层面钉死不可变借用。实证否决：3 处 TS2589（类型实例化过深）加 17 处数组位传染（消费方数组方法与展开处被迫跟改）；深层不可变由 core/session 的运行时深冻结保证，该读路径改造未纳入本记录。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
index 082158c75c..852d3816e2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.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 .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
-2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 1cf505e96122a66705fe42fc79757ac390ebf0ef
+2026-07-28-themed-scrollbars-and-reserved-gutter.md: 8ad5d801358823576c37d6b6824d7ce3fdcdac11
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: d6d2c64703df95ea2a4ff79435512eabdb3d2f81
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
index ba3d9d3c94..8ad5d80135 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
@@ -22,7 +22,7 @@ The two renderings are mutually exclusive, and the exclusion is enforced rather
 
 Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. `transparent` is the pair's other legal target, added when the sidebar's bars [started following the pointer](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md); the gate below admits those two and nothing else. The mechanically discoverable subset is owned by `packages/client/ui-theme/tests/scrollbar-styles.spec.ts`: any sheet that both scrolls and paints an elevated surface must rebind, so this note no longer maintains a complete surface inventory. Most declare the pair on the elevated card rather than on the scrolling descendant, because elevation belongs to the surface and custom properties inherit to whichever child actually scrolls.
 
-Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were missed in the first implementation and found in review, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection.
+Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were initially missed, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection.
 
 The elevated set is resolved from the palette's own dark elevation ladder — the surface tokens whose dark value lands on `bg-layer-2` or `bg-layer-3`, which is the step the l1/l2 split encodes. Deriving it instead from the sheets that already rebind was the first attempt and is unsound: such a set can only confirm what someone already remembered, and a surface nobody has rebound yet — exactly the case the check exists for — defines itself as unelevated. `--dsw-specific-tip` proved it, resolving to the menu surface's rung while the todo panel scrolled on it unrebound and the derived check stayed green.
 
@@ -44,7 +44,7 @@ The gutter and the sheet's `::-webkit-scrollbar` width are jointly necessary aga
 
 **Declare the properties once and let them inherit.** Fewer matched elements, and it breaks the rebinding contract — inheritance carries the substituted color, not the variable reference, so an elevated surface could not retint its own scrollbar. It is also incomplete on its own terms, since `scrollbar-width` does not inherit.
 
-**Declare the standard properties and the pseudo-elements unconditionally, without the `@supports` gate.** This is what the change originally shipped, and review caught it. Measured in chromium on probe elements with `scrollbar-gutter: stable` so the band is observable: an 8px `::-webkit-scrollbar` alone reserved a 30px band (the sheet's width plus the UA's buttons), and adding `scrollbar-width: thin` to the same element dropped it to the 10px `thin` reserves — the pseudo-element rules were being discarded, not merged. Every `::-webkit-scrollbar-thumb:hover` rule went with them, so both hover tokens and all four elevated surfaces' hover rebinds were dead code on the engine most users run.
+**Declare the standard properties and the pseudo-elements unconditionally, without the `@supports` gate.** Measured in chromium on probe elements with `scrollbar-gutter: stable` so the band is observable: an 8px `::-webkit-scrollbar` alone reserved a 30px band (the sheet's width plus the UA's buttons), and adding `scrollbar-width: thin` to the same element dropped it to the 10px `thin` reserves — the pseudo-element rules were being discarded, not merged. Every `::-webkit-scrollbar-thumb:hover` rule went with them, so both hover tokens and all four elevated surfaces' hover rebinds were dead code on the engine most users run.
 
 **Gate the WebKit rules too, behind `@supports selector(::-webkit-scrollbar)`.** Symmetrical to read, and wrong in one direction: it would hide the rules from an engine that implements the pseudo-elements but not `selector()`, which is the pre-16.4 Safari the ungated form serves correctly. Unknown selectors are already dropped, so the gate adds no protection to pay for that.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
index 1cf505e961..d6d2c64703 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定约定，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
 
-`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
+`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面最初被漏掉，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
 
 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。
 
@@ -44,7 +44,7 @@ Status: implemented
 
 **只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定约定——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
 
-**不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 这正是本次变更最初提交的形态，被评审发现。在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
+**不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
 
 **给 WebKit 规则也加门禁，写成 `@supports selector(::-webkit-scrollbar)`。** 读起来对称，但在一个方向上是错的：它会对「实现了伪元素但不支持 `selector()`」的引擎隐藏这些规则，而那正是不加门禁时能被正确服务的 16.4 之前的 Safari。未知选择器本就会被丢弃，因此这道门禁不提供任何能抵偿该代价的保护。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
index 91dd4d352d..0e0b722c8e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.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 .agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
-2026-07-30-approval-panel-command-cap.md: 1e4b75c106b71605a004ef35301445da76ec8cf0
-2026-07-30-approval-panel-command-cap.zh.md: 963dca00a6eda6c3bfd145828c8d7553625a4511
+2026-07-30-approval-panel-command-cap.md: 1d74d790299522a0f1e6b23f342cd10b35192d27
+2026-07-30-approval-panel-command-cap.zh.md: d31db819144cd4ce2099bf5d5f025b2e8df0e0e1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
index 1e4b75c106..1d74d79029 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
@@ -47,6 +47,6 @@ Reproducing the off-screen buttons needs a card taller than the scrollport, not
 
 The geometry block and the golden are replay-only, so record mode reaches the fixture write instead of aborting on layout.
 
-The scenario keeps exactly one golden — the waiting panel — and asserts the answered state on the world instead (the decided outcome, the file the escalated command wrote, `DONE`, the panel gone, the composer re-enabled). An answered-transcript golden was recorded first and failed on Linux CI: the denied first attempt renders the OS's own refusal, and that text is platform-specific (`bash: notes.txt: Operation not permitted` on macOS against `bash: line 1: notes.txt: Read-only file system` on Linux). Any scenario whose transcript contains a sandbox-denied command inherits that, so the denial belongs in assertions, never in a golden.
+The scenario keeps exactly one golden — the waiting panel — and asserts the answered state on the world instead (the decided outcome, the file the escalated command wrote, `DONE`, the panel gone, the composer re-enabled). An answered-transcript golden cannot hold: the denied first attempt renders the OS's own refusal, and that text is platform-specific (`bash: notes.txt: Operation not permitted` on macOS against `bash: line 1: notes.txt: Read-only file system` on Linux). Any scenario whose transcript contains a sandbox-denied command inherits that, so the denial belongs in assertions, never in a golden.
 
 The panel ships as a client-module bundle: `pnpm run build:web` alone does not pick up a change to `ApprovalPanel.module.css` or a new `data-` hook in `ApprovalPanel.tsx` — the package build must run first, or the browser lane asserts against an older client than the tree.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
index 963dca00a6..d31db81914 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
@@ -47,6 +47,6 @@ Status: implemented
 
 几何断言块与 golden 仅在回放模式下执行，这样录制模式才能走到写入 fixture（测试前置数据）那一步，而不是在布局检查处中断。
 
-该场景只保留一份 golden——等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。最初还录了一份"已回应 transcript"的 golden，它在 Linux CI 上失败了：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何 transcript 中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
+该场景只保留一份 golden——等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。一份"已回应 transcript"的 golden 立不住：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何 transcript 中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
 
 该面板以客户端模组包的形式发布：单跑 `pnpm run build:web` 不会带上对 `ApprovalPanel.module.css` 的改动，也不会带上 `ApprovalPanel.tsx` 中新增的 `data-` 钩子——必须先执行包构建，否则浏览器测试通道会对着一个比工作树更旧的客户端做断言。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 00fec6c8db..8245d59db4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: f2b7c3830b585db619f69046917e07a0b6ff6832
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 77787f9613b64a35e79a8667c6598de5a20ff400
+2026-07-30-web-transcript-log-ordered-projection.md: 1c65eeec0fbf0dc550043bb809ae8d7310f0602b
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 67bb41adde46ba7112896404ddc92a05f08f7aca
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index f2b7c3830b..1c65eeec0f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -45,7 +45,7 @@ The divergence from the terminal is therefore narrow: both frontends recognize a
 
 ## What #835's positional anchors were for, and why they are dissolved rather than lost
 
-The unmerged manual-compaction-queueing branch fixes the same interleaving bug by recording a per-event anchor — the surface tail at append time — and retargeting shadowed anchors onto the checkpoint. That mechanism exists to make positional anchors survive surface **reordering**. The human transcript is never re-ordered, so anchors have nothing to retarget: the precondition is removed, not the fix discarded. The mechanism is absent from this base and is not authored here.
+The unmerged manual-compaction-queueing branch fixes the same interleaving bug by recording a per-event anchor — the surface tail at append time — and retargeting shadowed anchors onto the checkpoint. That mechanism exists to make positional anchors survive surface **reordering**. The human transcript is never re-ordered, so anchors have nothing to retarget: the precondition is removed, not the fix discarded. The mechanism does not exist in this codebase.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 77787f9613..67bb41adde 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -45,7 +45,7 @@ const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 
 ## #835 的位置锚点是为什么而存在，以及为什么它是被溶解而非丢失
 
-尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也不撰写它。
+尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本代码库中并不存在。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index 7449d1b5fc..608d267824 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.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 .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
-2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: 407161d112cbbb6f476773f6f7e21c2ce820956e
+2026-07-31-fail-loud-releases-the-terminal.md: d5a97d73ec60897a3a40f3c99417e43de190af9c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 271769d32ea1dd66c698a65b35461f51042b7efb
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
index 5fe812e5fe..d5a97d73ec 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
@@ -56,4 +56,4 @@ The guarantee belongs to whichever bin owns the terminal: a surface that grabs t
 
 Those fake-process tests cannot observe the two failure modes that matter most — process exit code with a real event loop, and terminal state after exit — so the regression lives in `apps/cli/tests/tui-keyless-smoke.e2e.ts`. It boots the shipped tree in a real PTY over `fixtures/tui-invalid-provider.cordis.yml` (a list-shaped `providers`, the mistake users actually make), expects exit 1, and asserts the captured bytes contain both the labelled boot rejection (`dsh: plugin tree failed to load:`) and `ESC[?2004l`. The same case pins the boot path end to end: it caught the [HMR initial-scan boot deadlock](2026-08-03-hmr-initial-scan-boot-deadlock.md) that silently exited 13 with the terminal stranded.
 
-Testing policy requires a PTY case whenever terminal teardown changes, and this is it. The `/exit` path keeps its existing assertion that the same reset appears on a clean exit.
+The `/exit` path keeps its existing assertion that the same reset appears on a clean exit.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index 407161d112..271769d32e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -56,4 +56,4 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态未被恢复的 [HMR（热模块替换）初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
-测试规范要求：只要改动终端拆卸，就必须有 PTY 用例——这就是它。`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
+`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index c20fdb52b5..dd607a6dfc 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: f404a3bed728f9917f794f9c06f1a9dad32e64c8
-2026-08-06-api-key-format-validation.zh.md: a94d7eb577a84e7adf440c034aebe603faec7f64
+2026-08-06-api-key-format-validation.md: 356891c01c003f26d8edd092ebde8887e17d2448
+2026-08-06-api-key-format-validation.zh.md: 156e3141549c94f609d68f1937f30202c40751c6
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index f404a3bed7..356891c01c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -80,7 +80,7 @@ The client cannot import any of this: client packages reference only client pack
 
 A malformed key is refused at the field that holds it, and a malformed stored key fails as `INVALID_CREDENTIAL` with a message naming where to fix it and no fragment of the key. Because that code sits outside `DEFAULT_RETRYABLE_CODES`, a deterministic credential fault is no longer retried three times as a transport blip. `llm-pi-ai` discovery reports an illegal probe key as a credential fault instead of an unreachable endpoint.
 
-The shape heuristic can refuse a real key. The first draft matched any upper-case identifier followed by `=`, which review showed was broader than intended: an all-upper-case base64 key ending in padding (`ABCD==`) matched an assignment it does not resemble. Requiring a non-`=` character after the separator excludes padding, since base64 only ever pads at the end. What remains — an upper-case name, one `=`, then a value — is a shape no known provider issues, and the rule runs only in the browser, so a user who still hits it can set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
+The shape heuristic can refuse a real key. Matching any upper-case identifier followed by `=` would be broader than intended: an all-upper-case base64 key ending in padding (`ABCD==`) would match an assignment it does not resemble. Requiring a non-`=` character after the separator excludes padding, since base64 only ever pads at the end. What remains — an upper-case name, one `=`, then a value — is a shape no known provider issues, and the rule runs only in the browser, so a user who still hits it can set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
 
 Restricting to printable ASCII is stricter than the transport requires: a header value may carry `\x80`–`\xFF`. Admitting latin-1 would let `é` through to return an opaque 401 instead of a local, explained refusal, so the stricter rule is deliberate. A provider that issues latin-1 keys would need this rule widened.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index a94d7eb577..156e314154 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -80,7 +80,7 @@ Status: implemented
 
 格式错误的 Key 在持有它的那个字段上就被拒绝；格式错误的已存储 Key 以 `INVALID_CREDENTIAL` 失败，消息指明修复位置且不含 Key 的任何片段。由于该 code 位于 `DEFAULT_RETRYABLE_CODES` 之外，一个确定性的凭据故障不再被当作瞬时传输抖动重试三次。`llm-pi-ai` 的探测把非法 Key 报为凭据故障，而非端点不可达。
 
-形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知提供方不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+形状启发式可能拒绝一个真实的 Key。匹配任意「全大写标识符接 `=`」会比预期覆盖面更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知提供方不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
 
 限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个提供方签发 latin-1 的 Key，这条规则需要放宽。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
index e6758b23d2..bcaa655054 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.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 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
-2026-08-07-cancel-convergence-wake-latch.md: fe00c78bdfadac0cc6c9c173fd04256f77a22051
-2026-08-07-cancel-convergence-wake-latch.zh.md: 736c5eb39809811363ed93529d90878ea9acdc89
+2026-08-07-cancel-convergence-wake-latch.md: de18dce87e28eaf0548eebd0d054d4ca7b59d0a6
+2026-08-07-cancel-convergence-wake-latch.zh.md: b07edfd94a547ecacc8176df86b58f1f701ec2e4
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
index fe00c78bdf..de18dce87e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
@@ -10,15 +10,15 @@ English | [中文](2026-08-07-cancel-convergence-wake-latch.zh.md)
 
 ## Decision
 
-The `running` phase carries a `wakeRequested` latch, mirroring the existing `maintenance` phase field. `wakeDriver()` latches whenever the current activity cannot deliver the wake — a maintenance task never reads the queue, and an aborted activity converges without restarting — while a live driver needs no latch because it claims queued work itself. The exiting activity replays the latch at its own convergence boundary (`kick`'s `finally` and `runMaintenance`'s `finally`): this placement guarantees `turn/end N` lands before the replayed driver opens `turn/start N+1`, and that `whenIdle()` sees the replayed driver through its `activityDone` loop. The replay sites run only while `inbox.hasPending`, so a latched wake removed from the inbox before convergence does not start an empty driver. A wake sent while the agent is already idle keeps its turn boundary even when its message is cleared before the driver claims — that `idle → running → idle` transition is an observable contract: the goal-session driver's pause/disarm fallback fires on the `idle` transition after a cancelled reservation (CI caught this when the guard was moved into `wakeDriver()` and suppressed the boundary). `cancel()` without `keepInbox` clears the latch together with the inbox.
+The `running` phase carries a `wakeRequested` latch, mirroring the existing `maintenance` phase field. `wakeDriver()` latches whenever the current activity cannot deliver the wake — a maintenance task never reads the queue, and an aborted activity converges without restarting — while a live driver needs no latch because it claims queued work itself. The exiting activity replays the latch at its own convergence boundary (`kick`'s `finally` and `runMaintenance`'s `finally`): this placement guarantees `turn/end N` lands before the replayed driver opens `turn/start N+1`, and that `whenIdle()` sees the replayed driver through its `activityDone` loop. The replay sites run only while `inbox.hasPending`, so a latched wake removed from the inbox before convergence does not start an empty driver. A wake sent while the agent is already idle keeps its turn boundary even when its message is cleared before the driver claims — that `idle → running → idle` transition is an observable contract: the goal-session driver's pause/disarm fallback fires on the `idle` transition after a cancelled reservation (moving the guard into `wakeDriver()` suppresses that boundary). `cancel()` without `keepInbox` clears the latch together with the inbox.
 
-The `signal.aborted` discriminator is load-bearing: it separates pre-abort queued work — which `keepInbox` parks for a later wake (acceptance criterion 1) — from post-abort explicit wakes, which must run after convergence.
+The `signal.aborted` discriminator is load-bearing: it separates pre-abort queued work — which `keepInbox` parks for a later wake (the `keepInbox` parking contract) — from post-abort explicit wakes, which must run after convergence.
 
 ## Alternatives considered
 
 **Have `cancel()` set the phase to `idle` immediately.** Rejected: the driver is still unwinding, so this overlaps two drivers. The replay lives in the old driver's `finally`, which then never runs — 14 of 83 tests failed, several deadlocked. Repairing it requires identity-based phase ownership plus a turn-open quiescence barrier, which is strictly more machinery and is the latch in disguise.
 
-**Latch unconditionally for every non-idle wake.** Rejected: pre-abort wakes would auto-start after a `keepInbox` cancel, violating acceptance criterion 1; the "parks queued work" test and the error-window steering test both failed.
+**Latch unconditionally for every non-idle wake.** Rejected: pre-abort wakes would auto-start after a `keepInbox` cancel, violating the `keepInbox` parking contract; the "parks queued work" test and the error-window steering test both failed.
 
 **Replay through a chained promise (`activityDone.then(...)`).** Rejected: the replay would run outside the activity's own settlement, so `whenIdle()`'s loop can resolve before the replayed driver starts; fixing that requires replacing `activityDone` at send time and depends on microtask reaction ordering — more fragile than a synchronous flag.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
index 736c5eb398..b07edfd94a 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -10,15 +10,15 @@ Status: implemented
 
 ## 决策
 
-`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
+`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 会抑制该边界）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
 
-`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（验收条件 1）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
+`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（`keepInbox` 停放契约）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
 
 ## 备选方案
 
 **让 `cancel()` 立即把 phase 置为 `idle`。** 不予采用：driver 仍在展开收尾，这会重叠两个 driver。重放逻辑位于旧 driver 的 `finally`，而该 `finally` 此后不再执行——83 个测试中有 14 个失败，多个死锁。修复它需要基于身份的 phase 所有权外加 turn 打开时的 quiescence 屏障，机制上严格更重，而且该屏障就是换了个形态的锁存。
 
-**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反验收条件 1；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
+**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反 `keepInbox` 停放契约；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
 
 **通过链式 promise（`activityDone.then(...)`）重放。** 不予采用：重放会运行在活动自身结算之外，`whenIdle()` 的循环可能在重放 driver 启动前就 resolve；修复它需要在 send 时同步替换 `activityDone`，并依赖微任务反应顺序——比同步 flag 更脆弱。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 34e437c316..a334bdc7d5 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 8a6fa068a4c7fee6fbfd9e16757a0fae5efa0c8b
-2026-06-15-code-mode.zh.md: 00d4fd48b83e183d45423722bf223a63e305d5a4
+2026-06-15-code-mode.md: 5ad7be9506c2356f90050b86d85aa77f602946ce
+2026-06-15-code-mode.zh.md: 1902c6ba86b6b8d3fecd06c417347a9c082f67b4
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 8a6fa068a4..5ad7be9506 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -30,7 +30,7 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
 
 **Wire tool list.** The registry contributes visible capabilities in `'native'`, only `run_code` in `'code'`, and both in `'both'`. The final `PromptAssembly.tools` list is logged in the request header. `run_code` is a reserved presentation transport outside registration and restriction layers; direct prompt providers and the assembly waterfall remain responsible for their own contributions.
 
-**Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
+**Interaction with `toolOrder`:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
 
 **SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md) added Python and the `ctx.codeRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
 
@@ -106,7 +106,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s is cheap to add as a logged surface replacement under reconstructable requests, but still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
 
-**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and that is how it played out: the metadata landed as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch and per-tool binding parallelism unlocked on the same classifier.
+**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and both later shipped: the metadata as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch plus per-tool binding parallelism on the same classifier.
 
 **Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 00d4fd48b8..1902c6ba86 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -30,7 +30,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **协议工具列表。** 注册表在 `'native'` 下贡献可见能力，在 `'code'` 下仅贡献 `run_code`，在 `'both'` 下两者都贡献。最终的 `PromptAssembly.tools` 列表记录在请求头中。`run_code` 是一个保留的呈现传输通道，位于注册和限制层之外；直接提示词提供方和组装 waterfall 仍各自负责自己的贡献。
 
-**与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
+**与 `toolOrder` 的交互：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
 
 **SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](2026-07-31-code-mode-language-dispatch.md) 加入了 Python 与按 `ctx.codeRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
 
@@ -106,7 +106,7 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **在原生工具调用上做结果省略/摘要。** 仅解决问题中上下文膨胀这一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
 
-**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，后续也正是这样落地的：元数据以 `isConcurrencySafe` 的形式就绪（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发与每工具绑定并行化基于同一个分类器一起解锁。
+**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，两者后来都已交付：元数据即 `isConcurrencySafe`（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发加每工具绑定并行化则基于同一个分类器。
 
 **始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 860156eb06..6ffbf96a82 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.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 .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
-2026-06-17-filesystem-tool-schemas.md: b48f8e5d44913f2b6a2b7e1b19269c58e72efd1f
-2026-06-17-filesystem-tool-schemas.zh.md: ad4081d28950a4a2df4f5718038e2a4124bf70b5
+2026-06-17-filesystem-tool-schemas.md: ede7daee5c0f49a094df16861b107c8f528664fa
+2026-06-17-filesystem-tool-schemas.zh.md: 5ab19b82d6523bc81dd57c319252d998cc203911
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
index b48f8e5d44..ede7daee5c 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
@@ -8,17 +8,17 @@ English | [中文](2026-06-17-filesystem-tool-schemas.zh.md)
 
 [The filesystem capability-seam Agent Note](../architecture/2026-06-17-filesystem-capability-seam.md) defines the filesystem capability seam (`ctx.fs`), the package split (`dsh-fs`, `dsh-fs-local`, `dsh-tool-fs`, plus the `dsh-fs-policy` policy plugin), and the observed-file/stale-version policy for read-before-write/edit checks — which the [split-fs-seam](../simplification/2026-06-26-fsspec-style-fs-seam.md) and [event-gate](../architecture/2026-06-26-file-context-as-event-gate.md) Agent Notes moved off `ctx.fs` into the `dsh-fs-policy` plugin on the `fs/*` event gate. The remaining decision for the first filesystem tool delivery is the model-facing schema surface: what arguments the model sees for `read`, `write`, and `edit`.
 
-The schema should be small enough to implement in the first `dsh-tool-fs` pass, but stable enough that future local/remote/sandboxed filesystem backends do not require model-facing churn. It should also avoid importing every option from reference systems. Claude Code and OpenCode expose similar core file tools but differ in naming style and extra flags; this Agent Note chooses the minimal shared surface for the prototype.
+The schema must be small, yet stable enough that local/remote/sandboxed filesystem backends do not require model-facing churn, and must avoid importing every option from reference systems. Claude Code and OpenCode expose similar core file tools but differ in naming style and extra flags; this decision picks the minimal shared surface.
 
 ## Decision
 
 `@deepseek-ai/dsh-tool-fs` exposes these three model-facing tools in the first filesystem suite:
 
-| Tool | Our schema | Claude Code | OpenCode | Notes | Part of prototype |
-|---|---|---|---|---|---|
-| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | Files only; 1-indexed `offset`; no image/PDF/multimodal support in the first pass. | YES |
-| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Under the default fs-policy, updates to existing files require a prior observation; new-file creates do not. | YES |
-| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; under the default fs-policy requires a prior observation (any windowed read counts). | YES |
+| Tool | Our schema | Claude Code | OpenCode | Notes |
+|---|---|---|---|---|
+| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | Files only; 1-indexed `offset`; no image/PDF/multimodal support in the first pass. |
+| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Under the default fs-policy, updates to existing files require a prior observation; new-file creates do not. |
+| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; under the default fs-policy requires a prior observation (any windowed read counts). |
 
 The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The Consumer package translates these model-facing names into `ctx.fs` calls and `fs/*` event dispatches.
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
index ad4081d289..5ab19b82d6 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 [文件系统能力 seam Agent Note](../architecture/2026-06-17-filesystem-capability-seam.md) 定义了文件系统能力 seam（`ctx.fs`）、包拆分（`dsh-fs`、`dsh-fs-local`、`dsh-tool-fs`，加上 `dsh-fs-policy` 策略插件），以及针对 read-before-write/edit 检查的已观测文件／陈旧版本策略——[拆分文件系统 seam](../simplification/2026-06-26-fsspec-style-fs-seam.md)和[事件门控插件](../architecture/2026-06-26-file-context-as-event-gate.md) Agent Note 后来将其从 `ctx.fs` 移至 `dsh-fs-policy` 插件的 `fs/*` 事件门上。首次文件系统工具交付剩余的决策是面向模型的 schema 接口：模型在 `read`、`write` 和 `edit` 中看到哪些参数。
 
-该 schema 应足够小，以便在 `dsh-tool-fs` 的首次实现中完成，但又足够稳定，使未来的本地/远程/沙箱文件系统后端不需要改动面向模型的接口。同时应避免从参考系统中照搬所有选项。Claude Code 和 OpenCode 暴露了类似的核心文件工具，但在命名风格和额外 flag 上有所不同；本 Agent Note 为原型选择最小的共有接口。
+该 schema 必须足够小，但又要足够稳定，使本地/远程/沙箱文件系统后端不需要改动面向模型的接口，并且必须避免从参考系统中照搬所有选项。Claude Code 和 OpenCode 暴露了类似的核心文件工具，但在命名风格和额外 flag 上有所不同；本决策选择最小的共有接口。
 
 ## 决策
 
 `@deepseek-ai/dsh-tool-fs` 在首个文件系统工具套件中暴露以下三个面向模型的工具：
 
-| 工具 | 我们的 schema | Claude Code | OpenCode | 说明 | 原型包含 |
-|---|---|---|---|---|---|
-| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | 仅文件；`offset` 从 1 开始；首版不支持图片、PDF 或多模态内容。 | 是 |
-| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | 创建或覆盖 UTF-8 文本。在默认 fs-policy 下，更新现有文件前必须先观测；创建新文件则不需要。 | 是 |
-| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | 字面字符串替换；默认要求唯一匹配；在默认 fs-policy 下必须先观测（任意窗口读取均算作观测）。 | 是 |
+| 工具 | 我们的 schema | Claude Code | OpenCode | 说明 |
+|---|---|---|---|---|
+| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | 仅文件；`offset` 从 1 开始；首版不支持图片、PDF 或多模态内容。 |
+| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | 创建或覆盖 UTF-8 文本。在默认 fs-policy 下，更新现有文件前必须先观测；创建新文件则不需要。 |
+| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | 字面字符串替换；默认要求唯一匹配；在默认 fs-policy 下必须先观测（任意窗口读取均算作观测）。 |
 
 schema 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。Consumer 包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 1ab18b72e9..d981514b4c 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 6357482600fabd0354325a19118ec245eee5d855
-2026-06-18-compaction-capability-seam.zh.md: a5c60c667734f119a8bd9d9b6a8fbc9c66155470
+2026-06-18-compaction-capability-seam.md: 83f224aef50eb02712ac095da0cabf552399a9a6
+2026-06-18-compaction-capability-seam.zh.md: 12cf2498535d77dcf1a718b841a751bccadfdf1c
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 6357482600..83f224aef5 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -31,7 +31,7 @@ This is not a coupling smell — it is the contract's domain. The "only cordis"
 
 ### Three abstract operations, algorithm in the backend
 
-An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface. That recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making all three operations abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold.
+Putting the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making all three operations abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold.
 
 `compactIfNeeded(agent, trigger, signal)` takes an explicit `'pressure' | 'context-overflow'` trigger and cancellation. It reads only the latest durable routed request; no header means no work, while any routed provider/model target uses the singleton estimator. `compactNow(agent, signal)` requires an idle agent and performs one useful balanced reduction even below pressure, returning `null` without writes when none exists. `compactRegion(start, end, agent, signal?)` uses `agent.session` as its single session identity and keeps an optional signal for explicit callers. The default summarizer resolves its target from explicit config, the latest logged routed target, then agent options, and records the provider/model pair after any `llm/stream` routing. It replays the routed request's prefix and appends the compaction directive as a trailing user message so the provider's warm KV cache is reused — see the [summary prefix-cache Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md). The result carries `llmStreamCall: true` because it consumed exactly one call through this context's LLM service; a subclass sets that marker only under the same condition, since retained `rawOutput` alone does not identify the call path. The call sets the provider-neutral `GenerateOptions.purpose` to `compaction`; adapters may map that purpose to model-hidden transport metadata, and the DeepSeek adapter sends `x-deepseek-harness-compact: 1`.
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index a5c60c6677..12cf249853 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 
 ### 三个抽象操作，算法在后端
 
-早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
+将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法，会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
 `compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index ac018acdc8..cebb95513f 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 553411a0d8f989c883e3eea929669ccebcfe807b
-2026-06-21-subagent-capability-seam.zh.md: 5fa2bd62828e9afcb79647ec4821c2da1da041e7
+2026-06-21-subagent-capability-seam.md: 82010b4d11d2de5fc00f892b05e73807530e9cbf
+2026-06-21-subagent-capability-seam.zh.md: dc4e35e9ca6de8790b26bda1aeca30af00db5e1d
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 553411a0d8..82010b4d11 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -8,9 +8,9 @@ English | [中文](2026-06-21-subagent-capability-seam.zh.md)
 
 ## Problem
 
-The harness has a long-deferred seam for **subagents** — an agent delegating work to another agent. The intent was sketched in the `Agent`/`AgentLoop` interfaces ([packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts), [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)): a creation option referencing a parent agent (fork = seed the child session with the parent's event log; spawn = fresh session), with the child returned as an `Agent` handle so steering and event subscription work uniformly. This Agent Note realizes that seam; the banner above lists what shipped.
+The harness has a long-deferred seam for **subagents** — an agent delegating work to another agent. The intent was sketched in the `Agent`/`AgentLoop` interfaces ([packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts), [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)): a creation option referencing a parent agent (fork = seed the child session with the parent's event log; spawn = fresh session), with the child returned as an `Agent` handle so steering and event subscription work uniformly.
 
-The distinctive requirement — the one that shapes the whole design — is that **multiple subagent implementations must coexist at runtime**. A parent may want a cheap in-process child for a scoped subtask AND an isolated out-of-process child (over ACP) in the same session. The transports we foresee:
+The distinctive requirement — the one that shapes the whole design — is that **multiple subagent implementations must coexist at runtime**. A parent may want a cheap in-process child for a scoped subtask AND an isolated out-of-process child (over ACP) in the same session. The transports:
 
 - **in-process** — a child concrete `Agent` on the same `Context` (the cheapest, and nearly free given the existing agent factory);
 - **ACP** — act as an ACP *client* driving another agent process (which can be another instance of ourselves);
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 5fa2bd6282..dc4e35e9ca 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -8,9 +8,9 @@ Status: implemented
 
 ## 问题
 
-harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。本 Agent Note 实现了这个 seam；上方横幅列出了已交付的内容。
+harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。
 
-决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP）。我们预见的传输方式：
+决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP）。传输方式：
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index 2cb98d1258..865461630d 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.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 .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
-2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
-2026-06-29-todo-write-tool.zh.md: 2e95cfc4b085b03a70a651c622ca87ad7efa1538
+2026-06-29-todo-write-tool.md: 74af8a66ea86a474533b9c53d6431f7e0026192c
+2026-06-29-todo-write-tool.zh.md: ec2b7c8d59d65a44018425de81aa410890d8c208
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
index c4cf64b787..74af8a66ea 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
@@ -42,7 +42,7 @@ The schema enforces type/required/enum. Beyond that, `execute` rejects empty or
 
 ## Testing
 
-Four tiers, designed up front:
+Four tiers:
 - **Unit** — the session event (append/snapshot-clone/last-write-wins/not-on-surface); the tool (schema shape, arg validation via the real `ctx.tools.execute`, value validation, the event append + replacement, no-agent rejection, `presentCall`, HMR-safety); and TUI folding.
 - **Real-Loader path** — the plugin run through `Loader.unwrapExports`, asserting the namespace export shape survives (it HAS `inject`, so a stray default would crash at load — postmortem/0001).
 - **Full-loop integration** — a scripted mock model calls `todo_write` through the real agent loop; the `todo/write` event lands and a second call replaces it.
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 2e95cfc4b0..ec2b7c8d59 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -42,7 +42,7 @@ schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重
 
 ## 测试
 
-四个层级，预先设计：
+四个层级：
 - **单元测试**——会话事件（append/snapshot-clone/last-write-wins/not-on-surface）；工具（schema 形状、通过真实 `ctx.tools.execute` 的参数校验、值校验、事件追加与替换、非 agent 拒绝、`presentCall`、HMR（热模块替换）安全性）；以及 TUI 折叠。
 - **真实 Loader 路径**——插件通过 `Loader.unwrapExports` 运行，断言命名空间导出形状存活（它有 `inject`，因此一个意外的 default 导出会在加载时崩溃——事故复盘（postmortem）0001）。
 - **全循环集成**——一个脚本化的 mock 模型通过真实 agent loop（智能体循环）调用 `todo_write`；`todo/write` 事件落地，第二次调用替换它。
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index 547f88999e..c0b295a5c0 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.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 .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
-2026-06-30-hook-protocol-lib.md: 576a126e1022ac72265c476e03ef36aaf17f78b4
-2026-06-30-hook-protocol-lib.zh.md: f2554eaa378a26bf8254d86d458e0de5ce1aa4fd
+2026-06-30-hook-protocol-lib.md: e6938f88b2b587ef97c135d6482ae9ce0e3a94c1
+2026-06-30-hook-protocol-lib.zh.md: 4a4efae9a8950368d4db0309bc2c89a3f8c6d0d0
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
index 576a126e10..e6938f88b2 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-hook-protocol-lib.zh.md)
 
 ## Problem
 
-The hooks subsystem ships two bridge plugins: one that runs a user's existing Claude Code (CC) hooks, one for Codex hooks. Studying the reference implementations (`~/repos/refs/claude-code`, `~/repos/refs/codex`) surfaced a decisive fact: **Codex deliberately reimplements a SUBSET of the CC hook protocol.** Its engine reads the same `hooks.json`, uses the same matcher-group shape, the same exit-code/structured-stdout output contract, and the same command-hook execution model — Codex's source even names the engine after Claude's and comments where it "intentionally diverges." So the two bridges would otherwise duplicate the bulk of the protocol.
+The hooks subsystem ships two bridge plugins: one that runs a user's existing Claude Code (CC) hooks, one for Codex hooks. The reference implementations (`~/repos/refs/claude-code`, `~/repos/refs/codex`) show a decisive fact: **Codex deliberately reimplements a SUBSET of the CC hook protocol.** Its engine reads the same `hooks.json`, uses the same matcher-group shape, the same exit-code/structured-stdout output contract, and the same command-hook execution model — Codex's source even names the engine after Claude's and comments where it "intentionally diverges." So the two bridges would otherwise duplicate the bulk of the protocol.
 
 This Agent Note introduces `@deepseek-ai/dsh-hook-protocol`, a **library** (not a plugin — it registers and injects nothing) holding the genuinely-identical primitives both bridges build on. The split between shared and per-dialect is the design's center of gravity.
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index f2554eaa37..4a4efae9a8 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出约定，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
+钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）表明一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出约定，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
 
 本 Agent Note 引入 `@deepseek-ai/dsh-hook-protocol`，一个**库**（不是插件——它不注册也不注入任何东西），持有两个桥接插件共同依赖的真正相同的原语。共享与方言专属之间的分界是本设计的重心。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
index 3e5d68bb7e..c9a3f3857e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.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 .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
-2026-06-30-session-store-fork-api.md: 69ff85e1f137f4f263bf951af0a3f655411c606a
-2026-06-30-session-store-fork-api.zh.md: f354aaefbc16c6c3251da20de507602105a32296
+2026-06-30-session-store-fork-api.md: 85e748ba4e42919eac49cae583a08c72e0c3c0a0
+2026-06-30-session-store-fork-api.zh.md: f985c93085cbc2dbb1b8a768dac82a40025ea54d
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
index 69ff85e1f1..85e748ba4e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
@@ -36,7 +36,7 @@ The Host creates the child through the agent registry with the selected seed and
 
 ## Alternatives considered
 
-**Separate `ctx.sessionFork` service.** This was the first implementation, but review showed it overfit the capability-seam pattern. The code had no swappable backend, no extra event surface, no independent ownership lifecycle, and no durable behavior beyond `ctx.sessions.create({ seed, meta })`. Keeping a separate package would make callers discover and install a second service just to perform policy around a session-store primitive.
+**Separate `ctx.sessionFork` service.** An earlier iteration shipped this as a separate service; it overfit the capability-seam pattern. The code had no swappable backend, no extra event surface, no independent ownership lifecycle, and no durable behavior beyond `ctx.sessions.create({ seed, meta })`. Keeping a separate package would make callers discover and install a second service just to perform policy around a session-store primitive.
 
 **Two functions: `snapshot()` plus `fork()`.** This preserved a reusable seed/metadata computation, but the only supported consumer created a session immediately. It also made the surface feel more abstract than the concrete operation users need. A single `fork()` with an explicit `boundary` keeps the API direct while still supporting previous-point forks.
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
index f354aaefbc..f985c93085 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
@@ -36,7 +36,7 @@ Host 通过 agent（智能体）注册表，以选定的种子和谱系创建子
 
 ## 曾考虑的替代方案
 
-**独立的 `ctx.sessionFork` 服务。** 这是最初的实现，但评审表明它过度套用了能力 seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。
+**独立的 `ctx.sessionFork` 服务。** 较早的一版迭代曾把它作为独立服务交付；它过度套用了能力 seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。
 
 **两个函数：`snapshot()` 加 `fork()`。** 这保留了一个可复用的种子／元数据计算，但唯一支持的消费方会立即创建会话。它还使接口看起来比用户实际需要的具体操作更抽象。单一的 `fork()` 加显式 `boundary` 使 API 保持直接，同时仍支持对先前时间点的 fork。
 
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
index eac4c74cdc..abb46b8faa 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.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 .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
-2026-07-14-cross-family-fs-sandbox.md: e8a59be345b52f7684c574134b37f48bc49843fc
-2026-07-14-cross-family-fs-sandbox.zh.md: 228e156688ce23c10ac42b2c96b3737f796d4524
+2026-07-14-cross-family-fs-sandbox.md: 1c734a583403d1c1c9ea132a1e089362a9de4707
+2026-07-14-cross-family-fs-sandbox.zh.md: fdde507e002ac8dac452bb0f783ba8915bfcc30f
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
index e8a59be345..1c734a5834 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
@@ -49,7 +49,7 @@ The [`examples/acp-agent`](../../../../examples/acp-agent/cordis.yml) compositio
 
 ### The enforcement point: provider, not intent gate
 
-The sandbox Agent Note's original cross-family sketch put fs enforcement on the `fs/write-intent`/`fs/edit-intent` events. This Agent Note enforces in the provider instead, on two mechanical facts: the intent slots are single-decision first-wins (occupied by `dsh-fs-policy`, whose contract names a second decider a misconfiguration), and the intent events are dispatched only by `dsh-tool-fs` — a direct `ctx.fs` caller (a cordis-mounted plugin, a custom tool) bypasses them, where provider-level enforcement covers every caller by construction. The sandbox Agent Note's deferred-phase wording is updated to match in the same change.
+The sandbox Agent Note's original cross-family sketch put fs enforcement on the `fs/write-intent`/`fs/edit-intent` events. This Agent Note enforces in the provider instead, on two mechanical facts: the intent slots are single-decision first-wins (occupied by `dsh-fs-policy`, whose contract names a second decider a misconfiguration), and the intent events are dispatched only by `dsh-tool-fs` — a direct `ctx.fs` caller (a cordis-mounted plugin, a custom tool) bypasses them, where provider-level enforcement covers every caller by construction.
 
 ### Out of scope
 
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
index 228e156688..fdde507e00 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
@@ -49,7 +49,7 @@ Status: implemented
 
 ### 强制执行点：提供方，而非 intent gate
 
-沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其约定称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。沙箱 Agent Note 的暂缓阶段措辞在同一变更中被更新以匹配。
+沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其约定称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。
 
 ### 范围之外
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index d7d288e9f9..b7181bfba1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: 2efcf64adf07152b544c82f5bbf3bd8e415cd64d
-2026-07-16-harness-level-loop.zh.md: 8b83ca4a7f957f304c093e4b3f4c462c6301d6bc
+2026-07-16-harness-level-loop.md: e84a5738a55988d3b968eac829d9daaf10d7e304
+2026-07-16-harness-level-loop.zh.md: d7cda56d66d4456ac5c3c7d55bb238e85fcacbc5
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index 2efcf64adf..e84a5738a5 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -14,7 +14,7 @@ The repository therefore needs goal-based execution above the turn/step loop, bu
 
 ## Decision
 
-This proposal is implemented in amended form as two explicit plugin policies over existing seams:
+Two explicit plugin policies over existing seams:
 
 1. **Same-session goals** retain one durable objective in the current session and admit goal-attributed continuation turns only while live activation is armed.
 2. **Fresh-agent Ralph runs** execute a fixed foreground workflow whose rounds each spawn a new structured child with no conversation seed.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 8b83ca4a7f..d7cda56d66 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-本提案以修订后的形式实现为构建在现有 seam 之上的两项显式插件策略：
+构建在现有 seam 之上的两项显式插件策略：
 
 1. **同会话目标**在当前会话中保留一个持久目标，并且只在实时激活态已激活时接纳带目标归属的续行轮次。
 2. **全新 agent Ralph 运行**执行一个固定前台工作流，其中每个 Round 都生成一个不带对话种子的全新结构化子 agent。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 1730793d35..146601b28d 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 5d45f5fd13099352d503bc3296e4f6b7b0c53bc8
-2026-07-16-persistent-pty-sessions.zh.md: a0b4150157110b64943a42ce4e3544342e1be788
+2026-07-16-persistent-pty-sessions.md: f27d799574e61d92123c9ca4e31c5c2a9d3229b4
+2026-07-16-persistent-pty-sessions.zh.md: 0c23619faf00794c2c4e7b3f85ef961faddd99e0
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 5d45f5fd13..f27d799574 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -161,7 +161,6 @@ The package ships concise tool guidance explaining persistent state, owner isola
 - Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
 - Package contracts, the architecture map, subsystem pages, generated catalogs, and the website API describe the same shipped surface.
-- The repository CI-equivalent sequence owns type, lint, coverage, snapshot, documentation, build, hygiene, demo, and built-entry verification.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index a0b4150157..0c23619faf 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -161,7 +161,6 @@ plugins:
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
 - 包约定、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
-- 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 50196335f2..445f6548b3 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
-2026-07-20-dsh-cli-personal-config.zh.md: 91d2c938b345a7f2233da1566ac6db5b934c3148
+2026-07-20-dsh-cli-personal-config.md: f5207c5ffbd963b9b7c4a7166fa9f17a460707a9
+2026-07-20-dsh-cli-personal-config.zh.md: 24478a4b4fd5878032bf80f5b30ab9e2008da785
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index c00432ba2b..f5207c5ffb 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -30,7 +30,7 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 
 **A separate `bin/dsh` wrapper owning the `dsh` name.** Rejected because `apps/cli` is the single product CLI for default TUI, headless, and Web dispatch. Two competing entrypoints would collide in `$PATH` and product identity.
 
-**A pi-style typed settings file (`defaultProvider`/`defaultModel`/`providers`).** Rejected by the user in favor of patch semantics: the personal file is a cordis overlay over the shipped default config, not a second config vocabulary to own and translate.
+**A pi-style typed settings file (`defaultProvider`/`defaultModel`/`providers`).** Rejected in favor of patch semantics (product-owner decision): the personal file is a cordis overlay over the shipped default config, not a second config vocabulary to own and translate.
 
 **A personal full `cordis.yml` that includes the requested config.** Rejected: the personal file would have to name the leaf config's path, which varies per checkout; patches invert the dependency so the bin keeps choosing the tree and the personal layer only amends it.
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index 91d2c938b3..24478a4b4f 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -30,7 +30,7 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 **另设一个 `bin/dsh` 包装脚本并由其占用 `dsh` 名称。** 否决，因为 `apps/cli` 是统一的产品 CLI，负责分发默认 TUI、无头和 Web 界面。两个相互竞争的入口会在 `$PATH` 和产品身份上冲突。
 
-**pi 风格的类型化设置文件（`defaultProvider`/`defaultModel`/`providers`）。** 用户否决，选择补丁语义：个人文件是叠加在随仓库提供的默认配置之上的 cordis overlay，而不是需要另行拥有和翻译的第二套配置词汇。
+**pi 风格的类型化设置文件（`defaultProvider`/`defaultModel`/`providers`）。** 否决，选择补丁语义（产品负责人决策）：个人文件是叠加在随仓库提供的默认配置之上的 cordis overlay，而不是需要另行拥有和翻译的第二套配置词汇。
 
 **个人完整 `cordis.yml` 去 include 请求的配置。** 否决：个人文件将不得不写死叶子配置的路径，而该路径随 checkout 变化；补丁反转了依赖方向，bin 仍然选择配置树，个人层只做修正。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index ee8d4ca6af..f055b6f81f 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
-2026-07-23-session-telemetry-otel-revival.zh.md: b97840405bbde35f3b6b7f417b0615774fe43061
+2026-07-23-session-telemetry-otel-revival.md: 67ab0d28a168422a6b787a6088648746cd6079b6
+2026-07-23-session-telemetry-otel-revival.zh.md: d59dcd07e9879e1c7cafc7a104d4f2515596cab8
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index e6a213af65..67ab0d28a1 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -30,7 +30,7 @@ The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry
 
 **Full-log replay when no handoff cursor survived (re-export constructor seeds).** Shipped in the first revival round, then narrowed: adoption now replays from the session's construction boundary (`Session.firstLiveSeq`, the constructor-seed length — a fact the session already validated but did not expose; `header.seedLength` cannot serve, it is the durable fork-lineage value and a resumed session's constructor seed is its full stored log). A resumed session's history already shipped from the previous process under the same id, and a fork's inherited prefix already shipped in the parent's stream — re-exporting either re-billed every resume for its full history and doubled query-time counts on OTLP backends with no native ingest dedupe. Receivers stitch fork lineage via `session.parent_id` + `session.seed_length`. What the narrowing gives up, consistently with the at-most-once stance: a resume no longer backfills records the previous process failed to deliver (telemetry unmounted then, or queued at crash) — the full replay's only real benefit, bought at the common case's expense. A deployment that states a backfill requirement needs the deferred outbox above, not replay. The boundary also swallows the synthetic turn closers `SessionPersistence.load()` writes when repairing a crash-interrupted log (they sit below `firstLiveSeq` despite never existing in the previous process) — deliberate, not incidental: exporting a synthetic closer cannot complete the remote turn whose real tail records died in the crashed process's queue, it can only make an incomplete turn look closed. The wire stream stays faithful to what the crashed process actually shipped; receivers read a never-closed turn on a resumed stream as "the previous process died inside it" (the OTel README states the rule), and a later clean `shutdown` marker attests only to the resumed process's exit. Threading the pre-repair boundary through load/prepare so repairs export as live events would couple three packages to un-ship that signal.
 
-**Forwarding the seam's turn-boundary `flush()` hint to the OTel provider's `forceFlush()`.** Shipped in the first revival round, then removed after three review rounds each found a new silent-loss path in the same wrapper state: a dispose racing an in-flight flush (the SDK's concurrent-flush guard makes shutdown's internal drain skip), overlapping hints displacing the retained promise, and the provider's fixed 30-second flush timeout rejecting while the processor still drains. Every path exists only because the forwarding made this backend the process's second flusher against undocumented SDK internals from the upstream experimental tree; with no `flush()` implemented, the batch processor is the only flusher, its `scheduledDelayMillis` (already deployment-tunable through the `processor` passthrough) governs export cadence, and `shutdown()`'s drain is complete by construction. Reinstate only if a deployment states a turn-boundary latency requirement `scheduledDelayMillis` cannot meet — and then by calling the retained `BatchLogRecordProcessor`'s own `forceFlush()`, never the provider's timeout-wrapped one.
+**Forwarding the seam's turn-boundary `flush()` hint to the OTel provider's `forceFlush()`.** Shipped in the first revival round, then removed: three distinct silent-loss paths shared the wrapper state — a dispose racing an in-flight flush (the SDK's concurrent-flush guard makes shutdown's internal drain skip), overlapping hints displacing the retained promise, and the provider's fixed 30-second flush timeout rejecting while the processor still drains. Every path exists only because the forwarding made this backend the process's second flusher against undocumented SDK internals from the upstream experimental tree; with no `flush()` implemented, the batch processor is the only flusher, its `scheduledDelayMillis` (already deployment-tunable through the `processor` passthrough) governs export cadence, and `shutdown()`'s drain is complete by construction. Reinstate only if a deployment states a turn-boundary latency requirement `scheduledDelayMillis` cannot meet — and then by calling the retained `BatchLogRecordProcessor`'s own `forceFlush()`, never the provider's timeout-wrapped one.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index b97840405b..d59dcd07e9 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 **handoff 游标未存活时全量回放日志（重新导出构造函数种子）。** 首轮复活曾交付此方案，其后收窄：接管操作现在从会话的构造边界起回放（`Session.firstLiveSeq`，即构造函数种子长度，这一事实会话早已校验过却未曾暴露；`header.seedLength` 不能胜任：它是持久保存的 fork 谱系（lineage）值，而恢复会话的构造函数种子是其完整的已存储日志）。恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀也已在父会话的流中发出；再次导出任何一者，都会让每次恢复为其完整历史重复付费，并在没有原生摄取去重的 OTLP 后端上使查询时的计数翻倍。接收端基于 `session.parent_id` + `session.seed_length` 拼接 fork 谱系。此次收窄放弃的内容与至多一次立场一致：恢复不再回填上一个进程未能投递的记录（彼时遥测未挂载，或崩溃时仍在队列中）——这本是全量回放唯一的真实收益，代价却由常见情形承担。提出回填要求的部署需要的是上文已推迟的 outbox，而不是回放。该边界同样吞掉 `SessionPersistence.load()` 修复被崩溃打断的日志时写入的合成轮次关闭事件（它们落在 `firstLiveSeq` 之前，尽管在上一个进程中从未存在过）。这是有意为之，而非附带效果：远端轮次的真实尾部记录已随崩溃进程的队列一同消亡，导出合成关闭事件无法补全该轮次，只会让一个未完成的轮次看起来已经关闭。导出的流忠实于崩溃进程实际发出的内容；接收端会把恢复后的流中一个从未关闭的轮次读作「上一个进程死在了该轮次之内」（OTel README 陈述了这条规则），其后干净的 `shutdown` 标记也只证明恢复后进程自身的退出。若为让修复以实时事件的身份导出而将修复前边界贯穿 load/prepare 传递，将使三个包相互耦合，只为抹除这一信号。
 
-**将 seam 的轮次边界 `flush()` 提示转发到 OTel 提供方的 `forceFlush()`。** 首轮复活曾交付此转发，其后移除：三轮评审在同一份包装层状态中各发现一条新的静默丢失路径——dispose 与进行中的 flush 之间的竞态（SDK 的并发 flush 防护会令 shutdown 的内部排空被跳过）、相互重叠的提示顶掉留存的 promise、以及提供方固定的 30 秒 flush 超时在批处理器仍在排空时便 reject。这些路径存在的唯一原因，是该转发让这个后端成为进程内第二个执行 flush 的组件，面对的还是上游实验性（experimental）源码树中未见诸文档的 SDK 内部行为；不实现 `flush()` 时，批处理器就是唯一执行 flush 的组件，其 `scheduledDelayMillis`（已可由部署方经 `processor` passthrough 调优）决定导出节奏，`shutdown()` 的排空从构造上就是完整的。仅当某个部署提出 `scheduledDelayMillis` 无法满足的轮次边界延迟要求时才恢复此转发——且届时应调用留存的 `BatchLogRecordProcessor` 自身的 `forceFlush()`，绝不调用提供方那个带超时包装的版本。
+**将 seam 的轮次边界 `flush()` 提示转发到 OTel 提供方的 `forceFlush()`。** 首轮复活曾交付此转发，其后移除：三条不同的静默丢失路径共用同一份包装层状态——dispose 与进行中的 flush 之间的竞态（SDK 的并发 flush 防护会令 shutdown 的内部排空被跳过）、相互重叠的提示顶掉留存的 promise、以及提供方固定的 30 秒 flush 超时在批处理器仍在排空时便 reject。这些路径存在的唯一原因，是该转发让这个后端成为进程内第二个执行 flush 的组件，面对的还是上游实验性（experimental）源码树中未见诸文档的 SDK 内部行为；不实现 `flush()` 时，批处理器就是唯一执行 flush 的组件，其 `scheduledDelayMillis`（已可由部署方经 `processor` passthrough 调优）决定导出节奏，`shutdown()` 的排空从构造上就是完整的。仅当某个部署提出 `scheduledDelayMillis` 无法满足的轮次边界延迟要求时才恢复此转发——且届时应调用留存的 `BatchLogRecordProcessor` 自身的 `forceFlush()`，绝不调用提供方那个带超时包装的版本。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
index cad70622c8..a5e0f31b2d 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.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 .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
-2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9
-2026-07-25-session-list-browsing-and-manual-order.zh.md: 2bf778284aa551c75f1206ed08ca073e47b7a15d
+2026-07-25-session-list-browsing-and-manual-order.md: 323c0db16cc6b9e83155a3fb873ab94e4facd3a2
+2026-07-25-session-list-browsing-and-manual-order.zh.md: 85b2b319f03113480b3953c21940c123ba594ca8
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
index bd04e7f74c..323c0db16c 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
@@ -44,7 +44,7 @@ ui-sidebar shrinks to the column-geometry shell: brand row, fold state machine,
 
 **Optimistic reordering on drop** — client-first reordering needs failure rollback, one more entangled state in the object layer; local/LAN round-trips are millisecond-scale, so waiting for the host response is imperceptible. With a single order authority (trust the host completely), the frontend never invents an order.
 
-**Keep the rename dialog in ui-sidebar (smallest change)** — that is the problem itself: workspace-domain dialogs scattered in a borrowed slot, with each addition (the Delete confirmation is coming) repeating the cross-package wiring. Review first considered moving only the rename modal; the ruling was to give the whole browsing region to ui-workspace and leave the shell geometry-only.
+**Keep the rename dialog in ui-sidebar (smallest change)** — that is the problem itself: workspace-domain dialogs scattered in a borrowed slot, with each addition (the Delete confirmation is coming) repeating the cross-package wiring. Moving only the rename modal would repeat that wiring on the next dialog; the whole browsing region goes to ui-workspace and the shell stays geometry-only.
 
 **Nest sessions by fork lineage in WorkSpace mode** — nesting makes the current child visible only while its ancestors are expanded and limits in-group manual ordering to root nodes; `parentId` is lineage data, not a list-navigation structure. Flattening all sessions into peer rows lets each row be opened, searched, and ordered independently; In one list still disables drag because it has no workspace persistence carrier.
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
index 2bf778284a..85b2b319f0 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
@@ -44,7 +44,7 @@ ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settin
 
 **drop 后乐观重排** —— client 先行重排需失败回滚,对象层多一块纠缠态;本地/局域网往返毫秒级,等 host 响应的简单方案肉眼无感。顺序权威单一化(完全信 host)后,前端永不发明顺序。
 
-**rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态,最终裁定整个浏览区域归 ui-workspace,壳只留几何。
+**rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。只挪 rename Modal 会在下一个对话框上重演这份接线;整个浏览区域归 ui-workspace,壳只留几何。
 
 **WorkSpace 模式按 fork 谱系嵌套 session** —— 嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有 session 拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
index 71cb05f10a..6bb0f7e156 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
-2026-07-26-code-dispatch-log-spill.md: 3892a4a5a21c03d97d1873c68e2228119010e5c5
-2026-07-26-code-dispatch-log-spill.zh.md: c98b29e491e059fe27eb5b1ccea1b9664dce4639
+2026-07-26-code-dispatch-log-spill.md: 19d37c7ec2dbe5192e4c7e7ecd26e5b7f1467606
+2026-07-26-code-dispatch-log-spill.zh.md: 8dd270278932011db9658f9e4d5c1a1b6fe707ec
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
index 3892a4a5a2..19d37c7ec2 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-26-code-dispatch-log-spill.zh.md)
 
-> Scope: the fourth PR of the Code Mode UI stack — bounding the `tool/code-dispatch` event's content with the existing spill machinery. The [host foundation note](2026-07-26-code-dispatch-ui-foundation.md) accepted the unbounded log deliberately and named this PR as the payoff point; the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md) settled the event pair this shaping hooks into.
+> Scope: bounding the `tool/code-dispatch` event's content with the existing spill machinery. The [host foundation note](2026-07-26-code-dispatch-ui-foundation.md) accepted the unbounded log deliberately with this spill integration as the payoff point; the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md) settled the event pair this shaping hooks into.
 
 ## Problem
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
index c98b29e491..8dd2702789 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-log-spill.md) | 中文
 
-> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第四个 PR，即用既有的 spill 机制为 `tool/code-dispatch` 事件的内容施加边界。[宿主侧基础 Agent Note](2026-07-26-code-dispatch-ui-foundation.md)当初有意接受了不设上限的日志，并指明本 PR 就是兑现点；[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md)敲定了本次整形所挂接的事件对。
+> 范围：用既有的 spill 机制为 `tool/code-dispatch` 事件的内容施加边界。[宿主侧基础 Agent Note](2026-07-26-code-dispatch-ui-foundation.md)当初有意接受了不设上限的日志，并以这次 spill 集成为兑现点；[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md)敲定了本次整形所挂接的事件对。
 
 ## 问题
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**在桥接层内部用普通上限施加边界（不做 spill）。** 否决：没有定位符的截断会丢失回放与 UI 可能需要的数据，还会重新引入本堆叠 PR 链已经移除的「截断摘要」降级渲染路径。
+**在桥接层内部用普通上限施加边界（不做 spill）。** 否决：没有定位符的截断会丢失回放与 UI 可能需要的数据，还会重新引入本堆叠 PR（Pull Request）链已经移除的「截断摘要」降级渲染路径。
 
 **直接在桥接层内做 spill（从 code-mode.ts 调用 `ctx.spillStore`）。** 否决：注册表会因此对 spill 能力产生硬依赖；waterfall 则把策略留在所有其他 spill 决策所在的地方，既可组合也可禁用（省略 `maxInlineBytes` 依然意味着真正的 no-op）。
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
index e809bdfc6c..4e2d35175f 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
-2026-07-26-code-dispatch-ui-foundation.md: 1714472018a415114efed7ce189a3d82268dd8e3
-2026-07-26-code-dispatch-ui-foundation.zh.md: 8ede615bf15b99c5ecf9a8da427b571180921e54
+2026-07-26-code-dispatch-ui-foundation.md: 4115a1898de7d2cce01346c3f005fcd19c325f4c
+2026-07-26-code-dispatch-ui-foundation.zh.md: aeb57b93d781163dd0a4747ac03053c65deda1db
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
index 1714472018..4115a1898d 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-26-code-dispatch-ui-foundation.zh.md)
 
-> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement switch for the `dsh` config tree.
+> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the foundation the other Code Mode UI notes build on. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement switch for the `dsh` config tree.
 
 ## Problem
 
-A `run_code` turn was opaque in every product surface. The call card's title was the raw program text — unreadable at row width, and unlike `bash` (whose required `description` labels the card while the command rides the expanded input) there was no model-authored label at all. The `tool/code-dispatch` event carried only a 200-char, cwd-normalized `resultSummary` of each sub-call, so no UI could ever show what a sub-call actually returned: the planned web conversation view renders sub-calls through the exact components that render native `tool/result` cards, and a bounded summary cannot feed a native-parity card. And the `dsh web` composition had no way to enable Code Mode at all — the `tools` row pinned the schema default and the runtime was absent from the tree.
+A `run_code` turn was opaque in every product surface. The call card's title was the raw program text — unreadable at row width, and unlike `bash` (whose required `description` labels the card while the command rides the expanded input) there was no model-authored label at all. The `tool/code-dispatch` event carried only a 200-char, cwd-normalized `resultSummary` of each sub-call, so no UI could ever show what a sub-call actually returned: the web conversation view ([chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md)) renders sub-calls through the exact components that render native `tool/result` cards, and a bounded summary cannot feed a native-parity card. And the `dsh web` composition had no way to enable Code Mode at all — the `tools` row pinned the schema default and the runtime was absent from the tree.
 
 ## Decision
 
@@ -20,7 +20,7 @@ Three changes, one per obstacle:
 
 ## Alternatives considered
 
-**Keep a bounded summary (raised cap, or a cap + `truncated` flag).** Rejected: the stack's settled requirement is that sub-call rows and details render *identically* to native calls; any cap forces a second, degraded render path plus truncation UI. The cost accepted instead: a program that reads a large file logs the rendered content verbatim on the dispatch event — uncapped, outside spill policy, growing the session log by the same bytes. Spill integration for the logged copy is deferred to a later PR of this stack (the projection exists; wiring it into the bridge is mechanical once the event shape settles with the start/end pair).
+**Keep a bounded summary (raised cap, or a cap + `truncated` flag).** Rejected: the stack's settled requirement is that sub-call rows and details render *identically* to native calls; any cap forces a second, degraded render path plus truncation UI. The cost accepted instead: a program that reads a large file logs the rendered content verbatim on the dispatch event — uncapped, outside spill policy, growing the session log by the same bytes. Spill integration for the logged copy shipped as [code-dispatch log spill](2026-07-26-code-dispatch-log-spill.md).
 
 **A `--tools-mode` CLI flag or profile key.** Deferred, not rejected: the flag grammar suggests permanence, and the profile json is user config — both would harden a seam the per-session design intends to remove. An env var reads as the workaround it is.
 
@@ -28,4 +28,4 @@ Three changes, one per obstacle:
 
 ## Consequences
 
-Session format keeps `SESSION_FORMAT_VERSION` 0 (pre-release churn does not bump; old logs with `resultSummary` simply carry an extra unread field and lack `content` — v0 makes no compatibility promise). Existing code-mode snapshot fixtures were re-recorded. Model-visible surface grew: the `run_code` schema (one required parameter) and every code-mode system prompt/tool-schema snapshot changed. The web UI stack (subsequent PRs) builds directly on the new event payload; live per-sub-call running state needs a dispatch start/end pair that will reshape this event again.
+Session format keeps `SESSION_FORMAT_VERSION` 0 (pre-release churn does not bump; old logs with `resultSummary` simply carry an extra unread field and lack `content` — v0 makes no compatibility promise). Existing code-mode snapshot fixtures were re-recorded. Model-visible surface grew: the `run_code` schema (one required parameter) and every code-mode system prompt/tool-schema snapshot changed. The web UI work builds directly on the new event payload; live per-sub-call running state reshaped this event into a dispatch start/end pair ([live parallel dispatch](2026-07-26-code-mode-live-parallel-dispatch.md)).
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
index 8ede615bf1..aeb57b93d7 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
 
-> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用开关，归本篇所有。
+> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即其他 Code Mode UI Agent Note 赖以构建的基础。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用开关，归本篇所有。
 
 ## 问题
 
-`run_code` 轮次过去在每个产品界面上都不透明。调用卡片的标题就是原始程序文本，在行宽内无法阅读；而且不同于 `bash`（其必填的 `description` 用作卡片标签，命令本身放在展开后的输入里），`run_code` 完全没有模型撰写的标签。`tool/code-dispatch` 事件过去只携带每个子调用的 `resultSummary`（上限 200 字符、经 cwd 归一化），因此任何 UI 都无从展示子调用实际返回的内容：规划中的 Web 对话视图会用渲染原生 `tool/result` 卡片的同一批组件来渲染子调用，而有界摘要无法支撑一张与原生同等保真的卡片。同时，`dsh web` 组合此前根本无法启用 Code Mode：`tools` 行钉死在 schema 默认值上，配置树里也完全没有该运行时。
+`run_code` 轮次过去在每个产品界面上都不透明。调用卡片的标题就是原始程序文本，在行宽内无法阅读；而且不同于 `bash`（其必填的 `description` 用作卡片标签，命令本身放在展开后的输入里），`run_code` 完全没有模型撰写的标签。`tool/code-dispatch` 事件过去只携带每个子调用的 `resultSummary`（上限 200 字符、经 cwd 归一化），因此任何 UI 都无从展示子调用实际返回的内容：Web 对话视图（[chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)）会用渲染原生 `tool/result` 卡片的同一批组件来渲染子调用，而有界摘要无法支撑一张与原生同等保真的卡片。同时，`dsh web` 组合此前根本无法启用 Code Mode：`tools` 行钉死在 schema 默认值上，配置树里也完全没有该运行时。
 
 ## 决策
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**保留有界摘要（提高上限，或上限加 `truncated` 标志）。** 否决：本堆叠 PR 链已敲定的要求是，子调用的行与详情必须与原生调用渲染得*完全一致*；任何上限都会强制引入第二条降级的渲染路径，外加截断 UI。转而接受的代价是：读取大文件的程序会把渲染后的内容原样记录在分发事件上，不设上限、位于 spill 策略之外，并以同样的字节数增大会话日志。持久化副本的 spill 集成推迟到本链靠后的 PR（投影已经存在；待事件形状随 start/end 事件对一同定形，把它接入桥接层只是机械工作）。
+**保留有界摘要（提高上限，或上限加 `truncated` 标志）。** 否决：本堆叠 PR（Pull Request）链已敲定的要求是，子调用的行与详情必须与原生调用渲染得*完全一致*；任何上限都会强制引入第二条降级的渲染路径，外加截断 UI。转而接受的代价是：读取大文件的程序会把渲染后的内容原样记录在分发事件上，不设上限、位于 spill 策略之外，并以同样的字节数增大会话日志。持久化副本的 spill 集成已作为 [code-dispatch 日志 spill](2026-07-26-code-dispatch-log-spill.md) 交付。
 
 **一个 `--tools-mode` CLI（命令行界面）标志或 profile 配置键。** 推迟，而非否决：标志语法暗示永久性，profile JSON 又是用户配置；两者都会固化这个 seam，而按会话选择的设计本就打算移除它。环境变量则如实呈现了它权宜之计的本质。
 
@@ -28,4 +28,4 @@ Status: implemented
 
 ## 后果
 
-会话格式保持 `SESSION_FORMAT_VERSION` 为 0（预发布阶段的变动不递增版本号；携带 `resultSummary` 的旧日志只是多出一个不被读取的字段并缺少 `content`；v0 不作任何兼容性承诺）。既有的 Code Mode 快照 fixture（测试前置数据）已重新录制。模型可见表面扩大了：`run_code` 的 schema（新增一个必填参数）以及每一份 Code Mode 系统提示词／工具 schema 快照都发生了变化。Web UI 堆叠 PR 链（后续各 PR）直接构建在新的事件载荷之上；每个子调用的实时运行状态还需要一对分发 start/end 事件，这将再次重塑本事件的形状。
+会话格式保持 `SESSION_FORMAT_VERSION` 为 0（预发布阶段的变动不递增版本号；携带 `resultSummary` 的旧日志只是多出一个不被读取的字段并缺少 `content`；v0 不作任何兼容性承诺）。既有的 Code Mode 快照 fixture（测试前置数据）已重新录制。模型可见表面扩大了：`run_code` 的 schema（新增一个必填参数）以及每一份 Code Mode 系统提示词／工具 schema 快照都发生了变化。Web UI 工作直接构建在新的事件载荷之上；每个子调用的实时运行状态已把本事件重塑为一对分发 start/end 事件（[实时并行分发](2026-07-26-code-mode-live-parallel-dispatch.md)）。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
index 390144b4bd..7a93dad472 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.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 .agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
-2026-07-26-code-mode-chat-subcall-rows.md: 40b4b8fd8c5cea8e9aea01731d7eceff692db188
-2026-07-26-code-mode-chat-subcall-rows.zh.md: 9981fded054f663dd539660ed2a2eca68a9d3138
+2026-07-26-code-mode-chat-subcall-rows.md: 4bf608c36de78818b3ab40c6798ee6eafabe99a1
+2026-07-26-code-mode-chat-subcall-rows.zh.md: 98680a90bf613ba2dd9b974a809ea5300400f9ea
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
index 40b4b8fd8c..4bf608c36d 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
@@ -29,4 +29,4 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 
 ## Consequences
 
-Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership searches the whole tree). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom and Runtime suites pin slot dispatch, error states, recursive details resolution, history projection, and reference-stable path copying.
+Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership searches the whole tree). Trajectory/waterfall now draw sub-call spans from the dispatch timing pair ([live parallel dispatch](2026-07-26-code-mode-live-parallel-dispatch.md)); without that timing a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom and Runtime suites pin slot dispatch, error states, recursive details resolution, history projection, and reference-stable path copying.
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
index 9981fded05..98680a90bf 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
@@ -29,4 +29,4 @@ Status: implemented
 
 ## 后果
 
-自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属会搜索整棵树）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 与运行时测试套件则锁定 slot 分发、错误状态、递归详情解析、历史投影与引用稳定的路径复制。
+自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属会搜索整棵树）。trajectory/waterfall 现在依据分发计时事件对（[实时并行分发](2026-07-26-code-mode-live-parallel-dispatch.md)）绘制子调用 span；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 与运行时测试套件则锁定 slot 分发、错误状态、递归详情解析、历史投影与引用稳定的路径复制。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
index 2b12308db9..bee49da3ab 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.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 .agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
-2026-07-26-code-mode-live-parallel-dispatch.md: e85d1f99f58f1aae28091cd8875ee87a6df5a1e7
-2026-07-26-code-mode-live-parallel-dispatch.zh.md: c7f91f570e20e27aade0e8f47606d31b1d8ae7eb
+2026-07-26-code-mode-live-parallel-dispatch.md: 998152ee43d93e5190062cb632e20a3123cda4f9
+2026-07-26-code-mode-live-parallel-dispatch.zh.md: ac9b06cf1f2c197d4a8ea1dd69c8fb0840878097
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
index e85d1f99f5..998152ee43 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-26-code-mode-live-parallel-dispatch.zh.md)
 
-> Scope: the third PR of the Code Mode UI stack — the `tool/code-dispatch-start` event, per-sub-call running state in the web chat, and the bridge's scheduler reusing the native concurrency contract. Builds on the [host foundation](2026-07-26-code-dispatch-ui-foundation.md) and [chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md); the native contract itself is owned by the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md).
+> Scope: the `tool/code-dispatch-start` event, per-sub-call running state in the web chat, and the bridge's scheduler reusing the native concurrency contract. Builds on the [host foundation](2026-07-26-code-dispatch-ui-foundation.md) and [chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md); the native contract itself is owned by the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md).
 
 ## Problem
 
-Two gaps remained after the first two PRs. Sub-call rows appeared only when each dispatch *settled* — while one ran, the UI showed nothing for it, so a slow sub-call read as a stalled parent. And the bridge serialized every binding call ("even `Promise.all` executes one at a time"), a placeholder from before tools carried concurrency metadata: `isConcurrencySafe` now exists, the loop scheduler already runs native siblings in bounded pools, and a Code Mode program awaiting three independent reads paid 3× the latency the native path would.
+Two gaps remained after the host foundation and chat sub-call rows shipped. Sub-call rows appeared only when each dispatch *settled* — while one ran, the UI showed nothing for it, so a slow sub-call read as a stalled parent. And the bridge serialized every binding call ("even `Promise.all` executes one at a time"), a placeholder from before tools carried concurrency metadata: `isConcurrencySafe` now exists, the loop scheduler already runs native siblings in bounded pools, and a Code Mode program awaiting three independent reads paid 3× the latency the native path would.
 
 ## Decision
 
@@ -29,4 +29,4 @@ Two gaps remained after the first two PRs. Sub-call rows appeared only when each
 
 ## Consequences
 
-Programs get native-grade latency for independent reads with no new model-side API — `Promise.all` simply works better, and prompt guidance changed accordingly. The web UI shows per-sub-call running rings live (fixture emits start/settle pairs; jsdom pins the running shape; the runtime spec pins in-place settlement, out-of-order completion, and callTime pairing). PR6 (trajectory/waterfall spans) can now draw truthful spans from the pair's timing. The spill PR (next) inherits the settle event as its single bounding point.
+Programs get native-grade latency for independent reads with no new model-side API — `Promise.all` simply works better, and prompt guidance changed accordingly. The web UI shows per-sub-call running rings live (fixture emits start/settle pairs; jsdom pins the running shape; the runtime spec pins in-place settlement, out-of-order completion, and callTime pairing). Trajectory/waterfall sub-call spans draw truthful timing from the pair. Spill bounding ([code-dispatch log spill](2026-07-26-code-dispatch-log-spill.md)) inherits the settle event as its single bounding point.
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
index c7f91f570e..ac9b06cf1f 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-26-code-mode-live-parallel-dispatch.md) | 中文
 
-> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发约定的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生约定本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
+> 范围：`tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发约定的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生约定本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
 
 ## 问题
 
-前两个 PR 之后仍留有两个缺口。子调用行过去只在每次分发*结算*后才出现：某次分发运行期间，UI 对它毫无展示，于是一个慢的子调用看上去就像父调用卡住了。而桥接层过去把每一次绑定调用都串行化（「即使 `Promise.all` 也一次只执行一个」），这是工具尚未携带并发元数据时留下的占位实现：如今 `isConcurrencySafe` 已经存在，agent loop（智能体循环）调度器早已在有界并发池中运行原生兄弟调用，而一个等待三个独立读取的 Code Mode 程序，付出的延迟却是原生路径的 3 倍。
+宿主侧基础与 chat 子调用行交付之后仍留有两个缺口。子调用行过去只在每次分发*结算*后才出现：某次分发运行期间，UI 对它毫无展示，于是一个慢的子调用看上去就像父调用卡住了。而桥接层过去把每一次绑定调用都串行化（「即使 `Promise.all` 也一次只执行一个」），这是工具尚未携带并发元数据时留下的占位实现：如今 `isConcurrencySafe` 已经存在，agent loop（智能体循环）调度器早已在有界并发池中运行原生兄弟调用，而一个等待三个独立读取的 Code Mode 程序，付出的延迟却是原生路径的 3 倍。
 
 ## 决策
 
@@ -29,4 +29,4 @@ Status: implemented
 
 ## 后果
 
-程序不需要任何新的模型侧 API，独立读取就获得了原生级的延迟：`Promise.all` 直接变得更好用，提示词指引也随之修改。Web UI 实时显示每个子调用的运行指示环：fixture（测试前置数据）发出成对的 start/settle 事件；jsdom 锁定运行中形状；运行时测试锁定原位结算、乱序完成与 callTime 配对。PR6（trajectory/waterfall 的 span）现在可以依据这对事件的计时绘制如实的 span。spill PR（下一个）则继承结算事件，作为自己唯一施加边界的位置。
+程序不需要任何新的模型侧 API，独立读取就获得了原生级的延迟：`Promise.all` 直接变得更好用，提示词指引也随之修改。Web UI 实时显示每个子调用的运行指示环：fixture（测试前置数据）发出成对的 start/settle 事件；jsdom 锁定运行中形状；运行时测试锁定原位结算、乱序完成与 callTime 配对。trajectory/waterfall 的子调用 span 从这对事件取得如实的计时。spill 边界施加（[code-dispatch 日志 spill](2026-07-26-code-dispatch-log-spill.md)）则继承结算事件，作为自己唯一施加边界的位置。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 90ea440ef8..9f98597809 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.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 .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
-2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: ebd4b1567eba637493956993b43b1ec56df14c39
+2026-07-26-todo-parallel-in-progress.md: 5664960ce94dfac60d89cb363ea62459dd51f59e
+2026-07-26-todo-parallel-in-progress.zh.md: f346f89fcae5e8607c5608bbf7541ada0bae4593
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
index 8d047f33ab..5664960ce9 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
@@ -33,11 +33,11 @@ The durable-log invariant deliberately does NOT follow the flag. A log written w
 
 - **Keep the cap and add an explicit parallel opt-in flag** — an extra argument on every call to serve the common case; the flag would be noise for sequential work and still unverifiable.
 - **Cap active items at a configured maximum** — any fixed number is arbitrary. This is why the config field is a boolean policy switch and not a count: "may several tasks be active" is a property of the deployment, while "at most N" invents a threshold nothing can justify.
-- **Hardcode the parallel policy** — the first revision of this branch did, which is what made `allowParallelInProgress` necessary: a deployment running strictly sequential agents had no way back to the discipline it wanted.
+- **Hardcode the parallel policy** — the first revision of this change did, which is what made `allowParallelInProgress` necessary: a deployment running strictly sequential agents had no way back to the discipline it wanted.
 
 ## The display surfaces are part of the change
 
-Lifting the cap makes a list shape reachable that no renderer had ever received, so this branch stacks on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither PR's tests caught it — only the collapsed header and the row lost information. The panel redesign replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this branch still had to fix.
+Lifting the cap makes a list shape reachable that no renderer had ever received, so this change builds on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither change's tests caught it — only the collapsed header and the row lost information. The panel redesign replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this change still had to fix.
 
 The row takes `planSummary` in `toolviews/plan-summary.ts`. It names the first active item and counts the rest, so the row reports how many tasks are running instead of implying one. Naming every active item was rejected: the row is a single line, and an unbounded join would overflow it — the count degrades predictably where a list does not. The derivation sits inside the toolviews domain rather than in `contract/`, the inter-domain face: the panel computes its own counts inline and shares nothing with the row, so a contract module would declare a sharing relationship that no longer exists.
 
@@ -47,8 +47,8 @@ The row takes `planSummary` in `toolviews/plan-summary.ts`. It names the first a
 
 ## Deferred
 
-Two review findings are recorded here rather than fixed on this branch. The `summarySuffix` span carries no accessible name, so a screen reader reads the count without its noun (`… 实现 fixture 样本 +1`); naming it introduces localized copy with its own test contract, which belongs to an accessibility pass over the whole `ToolRow` summary line rather than to one row. And when the *first* active item's content is unusable — missing, mistyped, or blank once trimmed — the row drops the active clause and the count with it, so a parallel plan renders as bare counts; skipping forward to the first usable active item was rejected because call args are an explicitly unvalidated boundary where model order is the only ordering the row can honour, and dropping the unusable clause alone keeps the `done`/`total` counts, which are trustworthy regardless.
+Two known gaps are deferred. The `summarySuffix` span carries no accessible name, so a screen reader reads the count without its noun (`… 实现 fixture 样本 +1`); naming it introduces localized copy with its own test contract, which belongs to an accessibility pass over the whole `ToolRow` summary line rather than to one row. And when the *first* active item's content is unusable — missing, mistyped, or blank once trimmed — the row drops the active clause and the count with it, so a parallel plan renders as bare counts; skipping forward to the first usable active item was rejected because call args are an explicitly unvalidated boundary where model order is the only ordering the row can honour, and dropping the unusable clause alone keeps the `done`/`total` counts, which are trustworthy regardless.
 
 ## Consequences
 
-A todo list can now faithfully mirror parallel execution, and every surface renders several active markers at once: the plan strip's header counts the active items, and the row needed the derivation above. A composition that sets `allowParallelInProgress: true` no longer rejects a formerly-invalid snapshot shape; one that sets `false` keeps the old rejection, and the durable-log invariant accepts both. The model-facing description changed, which re-recorded the tool-catalog page and every snapshot sidecar carrying the todo schema. No count is recorded here: the set grows with every pinning scenario that lands, and the two point-in-time censuses this note previously carried were both stale within days. The operative rule is that a branch changing the tool description must refresh whichever sidecars landed after it branched — including the numbered `tool-schemas.<n>.expected.json` files pinning a subagent class, whose schemas the parent scenario does not cover — and `pnpm run test:snapshot:refresh` does it keylessly over the whole corpus. The web fixture's todo sample now runs two items `in_progress`, so both fixture-driven surfaces render a parallel plan. `packages/client/ui-conversation/tests/todo-panel.spec.tsx` pins the row summary and the plan strip over src, the ACP `todo-write` scenario records a three-todo plan with two active, and `apps/web/tests/todo-row.snapshot.ts` pins both surfaces in the assembled application — booted from the built `packages/client/*/lib/client.js` bundles, so it is the one place the keyed registration and the bundled wiring are under test. That last file records `summary`, `suffix`, and the strip's header as separate fields, so folding the `+N` count back into the summary string changes the expected output even though the concatenated text would read the same.
+A todo list can now faithfully mirror parallel execution, and every surface renders several active markers at once: the plan strip's header counts the active items, and the row needed the derivation above. A composition that sets `allowParallelInProgress: true` no longer rejects a formerly-invalid snapshot shape; one that sets `false` keeps the old rejection, and the durable-log invariant accepts both. The model-facing description changed, which re-recorded the tool-catalog page and every snapshot sidecar carrying the todo schema. No count is recorded here: the set grows with every pinning scenario that lands. The operative rule is that a branch changing the tool description must refresh whichever sidecars landed after it branched — including the numbered `tool-schemas.<n>.expected.json` files pinning a subagent class, whose schemas the parent scenario does not cover — and `pnpm run test:snapshot:refresh` does it keylessly over the whole corpus. The web fixture's todo sample now runs two items `in_progress`, so both fixture-driven surfaces render a parallel plan. `packages/client/ui-conversation/tests/todo-panel.spec.tsx` pins the row summary and the plan strip over src, the ACP `todo-write` scenario records a three-todo plan with two active, and `apps/web/tests/todo-row.snapshot.ts` pins both surfaces in the assembled application — booted from the built `packages/client/*/lib/client.js` bundles, so it is the one place the keyed registration and the bundled wiring are under test. That last file records `summary`, `suffix`, and the strip's header as separate fields, so folding the `+N` count back into the summary string changes the expected output even though the concatenated text would read the same.
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index ebd4b1567e..f346f89fca 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -33,11 +33,11 @@ Status: implemented
 
 - **保留上限并增加一个显式的并行 opt-in 标志**——为服务常见场景而给每次调用增加一个额外参数；这个标志对顺序工作而言只是噪声，而且仍然无法验证。
 - **把活跃条目限制在一个可配置的上限内**——任何固定数字都是任意的。这正是该配置字段是布尔策略开关而非数量的原因：「是否允许多个任务同时活跃」是部署的属性，而「最多 N 个」凭空发明了一个无从论证的阈值。
-- **把并行策略硬编码**——本分支的第一版就是如此，这也是 `allowParallelInProgress` 之所以必要的原因：运行严格顺序 agent 的部署没有任何办法回到它想要的纪律。
+- **把并行策略硬编码**——本变更的第一版就是如此，这也是 `allowParallelInProgress` 之所以必要的原因：运行严格顺序 agent 的部署没有任何办法回到它想要的纪律。
 
 ## 展示面是本次改动的一部分
 
-解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR（Pull Request）的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
+解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本变更构建在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个变更的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本变更仍需修的那一处。
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
@@ -47,8 +47,8 @@ Status: implemented
 
 ## 暂缓项
 
-两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+两个已知缺口暂缓处理。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
 
 ## 后果
 
-现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照伴随文件。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Agent Note 先前记过的两次时点统计都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些伴随文件——包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖——`pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture（测试前置数据）的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP（Agent Client Protocol）`todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
+现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照伴随文件。此处不记录数量：该集合会随每个新落地的 pin 场景增长。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些伴随文件——包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖——`pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture（测试前置数据）的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP（Agent Client Protocol）`todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 2e5c66b55c..65a917c3eb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: 991b89599d7f300c79928e568833a2cd488f5a4e
-2026-07-28-continuable-subagent-conversations.zh.md: a7d282c4fadd943ad9250e01de5d379a776a32a0
+2026-07-28-continuable-subagent-conversations.md: 8408cf27003c011e140c3f426d81f3ba5af76b06
+2026-07-28-continuable-subagent-conversations.zh.md: e6f7bcc7d4f70edb8cbbe1ac88b9bdd7ac2e11a5
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index 991b89599d..8408cf2700 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -105,7 +105,7 @@ When the authenticated parent is itself a continuation-managed Activation, start
 
 Child release occurs only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. The manager awaits `ctx.sessions.flush(child.session)` but does not interpret its participation boolean: an arbitrary listener cannot prove that the selected persistence backend stored the state. A rejection is logged without preventing handle disposal or ownership release, because retaining a child would permanently pin its ancestors in `waiting`. If the child is owned, the manager then resolves the live parent through `SessionHeader.parentSession` and removes the child Session id from its `ownedChildren`. Manager teardown uses the same child-first order.
 
-Ownership is retained until the child Activation is disposed. A later refinement may release a request-scoped lease earlier, but it would require an exact turn-completion correlation that this Task-free proposal deliberately does not add.
+Ownership is retained until the child Activation is disposed. A later refinement may release a request-scoped lease earlier, but it would require an exact turn-completion correlation that this Task-free design deliberately does not add.
 
 Top-level teardown is host-owned rather than represented as another Activation. Manager unload invokes its internal manager-wide drain to close admission synchronously, await every admitted materialization through publication or rollback, stop the stable live forest, and release it child-first. A host that owns selected top-level Agents uses `drainContinuableDescendants(parents)`: exact Agent identities close admission only below those roots until each leaves the registry, while unrelated forests and manager-wide admission remain live; the manager stops their visible descendants before its first await, waits only materializations admitted below those roots, and releases only the selected branches. Every materialized start and live delivery rechecks caller cancellation, the applicable draining scope, Activation disposal, and exact parent authority in the same synchronous span as inbox submission, so teardown or parent replacement that wins before acceptance prevents delivery to the closing handle. Only after the applicable drain settles may the host dispose its top-level Agents; only manager-wide drain precedes manager-scope disposal.
 
@@ -149,7 +149,7 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 ## Alternatives considered
 
-**Keep Task-backed Activations.** Tasks provide generic status, result collection, and cancellation, but using them for conversation delivery creates a second queue and duplicates turn ownership. The proposal gives up those generic Task controls so the Agent inbox remains the only execution order.
+**Keep Task-backed Activations.** Tasks provide generic status, result collection, and cancellation, but using them for conversation delivery creates a second queue and duplicates turn ownership. This design gives up those generic Task controls so the Agent inbox remains the only execution order.
 
 **Create one Activation per `next-turn`.** This restores independent result and cancellation boundaries, but it requires a manager FIFO beside the Agent inbox and makes a retained Agent cross artificial Activation boundaries. One Activation per residency epoch is smaller and follows the `AgentHandle` lifetime directly.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index a7d282c4fa..e6f7bcc7d4 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -105,7 +105,7 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
 
 只有在 child Agent 完全停稳、该 child 持有的每个 child 都已 dispose、best-effort 的最终会话 flush 结算且 child 的 `AgentHandle` 完成 dispose 后，系统才释放 child。管理器会等待 `ctx.sessions.flush(child.session)`，但不解释其参与布尔值：任意 listener 都无法证明所选持久化后端已存储该状态。rejection 会被记录，但不会阻止 handle dispose 或释放所有权，因为保留 child 会让其祖先永久固定在 `waiting`。如果 child 归 parent 所有，管理器随后会通过 `SessionHeader.parentSession` 解析在线 parent，并从其 `ownedChildren` 中移除 child 会话 id。管理器拆卸使用相同的 child-first 顺序。
 
-系统会一直保留所有权，直至 child 激活完成 dispose。后续改进可以更早释放限定到请求的 lease，但这需要精确关联轮次完成，而本 Task-free 提案特意不增加该机制。
+系统会一直保留所有权，直至 child 激活完成 dispose。后续改进可以更早释放限定到请求的 lease，但这需要精确关联轮次完成，而本 Task-free 设计特意不增加该机制。
 
 顶层拆卸由宿主负责，而不表示为另一次激活。管理器卸载会调用其内部的管理器全局 drain，同步关闭准入，等待每个已获准的物化过程完成发布或回滚，停止稳定的在线森林，并按 child-first 顺序释放。拥有选定顶层 Agent 的宿主使用 `drainContinuableDescendants(parents)`：确切的 Agent 身份只关闭这些根之下的准入，直到每个身份离开注册表，而无关森林和管理器全局准入保持在线；管理器会在第一次 await 之前停止其可见后代，只等待这些根之下已获准的物化过程，并且只释放选定分支。每个已物化的 start 和在线投递都会在与 inbox 提交相同的同步区间内重新检查调用方取消、适用的 draining 作用域、Activation dispose 和确切的 parent 权限，因此只要拆卸或 parent 替换先于接受发生，就会阻止向正在关闭的 handle 投递。只有适用的 drain 结算后，宿主才能 dispose 自己的顶层 Agent；只有管理器全局 drain 会先于管理器作用域 dispose。
 
@@ -149,7 +149,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ## 曾考虑的替代方案
 
-**保留由 Task 支撑的激活。** Task 可以提供通用状态、结果收集和取消，但使用 Task 投递会话会产生第二条队列，并重复轮次所有权。本提案放弃这些通用 Task 控制，让 Agent inbox 成为唯一执行顺序。
+**保留由 Task 支撑的激活。** Task 可以提供通用状态、结果收集和取消，但使用 Task 投递会话会产生第二条队列，并重复轮次所有权。本设计放弃这些通用 Task 控制，让 Agent inbox 成为唯一执行顺序。
 
 **每个 `next-turn` 创建一次激活。** 这会恢复独立的结果与取消边界，但需要在 Agent inbox 旁维护管理器 FIFO，还会使所保留的 Agent 跨越人为划分的激活边界。每个驻留周期对应一次激活更小，也直接跟随 `AgentHandle` 生命周期。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.i18n.yaml
index 84a93cde2d..68716d20a2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.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 .agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
-2026-07-28-todo-plan-clears-on-next-turn.md: 8a2808f5023a0800fbbeb65c5e28b3495e051dbc
-2026-07-28-todo-plan-clears-on-next-turn.zh.md: c96485ec2d5b0faea0682624cde9a7569cd2e227
+2026-07-28-todo-plan-clears-on-next-turn.md: 55a0d4f307bef5cd04add0baae220ea763772ee9
+2026-07-28-todo-plan-clears-on-next-turn.zh.md: e881884443b06b780c12d348c7ecca4a88801b73
diff --git a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
index 8a2808f502..55a0d4f307 100644
--- a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
+++ b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
@@ -18,7 +18,7 @@ The standing plan is the latest `todo/write` that is not followed by a later `tu
 
 ### TUI live path
 
-The TUI `renderEvent` switch still clears its local plan panel on `turn/start` and replaces it on `todo/write` (TUI is not yet a projection carrier). The rebuild path resets the panel before replaying the log so cold resume converges on the same rule.
+The former TUI's `renderEvent` switch cleared its local plan panel on `turn/start` and replaced it on `todo/write`, with its rebuild path resetting the panel before replay so cold resume converged on the same rule; that package has since been removed ([remove TUI package](../simplification/2026-08-04-remove-tui-package.md)).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md
index c96485ec2d..e881884443 100644
--- a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ### TUI 实时路径
 
-TUI 的 `renderEvent` 分支仍在 `turn/start` 清空本地计划面板、在 `todo/write` 替换之（TUI 尚非投影载体）。重建路径在回放日志前重置面板，使冷恢复收敛到同一规则。
+原 TUI 的 `renderEvent` 分支曾在 `turn/start` 清空本地计划面板、在 `todo/write` 替换之，其重建路径在回放前重置面板，使冷恢复收敛到同一规则；该包其后已被移除（[移除 TUI 包](../simplification/2026-08-04-remove-tui-package.md)）。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 65af28ee2e..781c07f8f3 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.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 .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
-2026-07-28-web-terminal-card.md: 0338fa1cdb4a19177bddd4181661173bf75492b0
-2026-07-28-web-terminal-card.zh.md: f9dc686cfbf817fe5a1c15b8d5a94e3f8ab2adee
+2026-07-28-web-terminal-card.md: 84e5cdb786944b014fd3a687cfefad6768174006
+2026-07-28-web-terminal-card.zh.md: 58c236bda9c45e13fda0f965f84af24b3c831bb4
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
index 0338fa1cdb..84e5cdb786 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
@@ -20,7 +20,7 @@ The component's contract:
 - **One run-state dot for the call, on the first row.** `StateDot` in three of its four states: the chase while running, red for the exit status that also renders the pill, green for a clean settle — the same indicator a tool row's leading icon uses, so a row and its own card cannot disagree about one command. The dot exists because the first question a reader has about a shell command is whether it is still running, and without it that had to be inferred from the absence of output — which a settled command producing no output also looks like. It sits out of flow in a gutter the card reserves as its OWN left padding, so it neither indents its command nor depends on the command's text metrics to line up. The reservation is padding rather than margin because every render site rewrites `margin` wholesale to set its own indent, which silently cancelled a margin-based gutter and let a container clip the dot. Exactly one dot, whatever the line count: the exit status the view carries is the whole call's, and bash reports no per-command status, so a dot per line would assert of a line that succeeded inside a failing call that the line itself failed. The single visually hidden text label carries the same scope, since `StateDot` is `aria-hidden` and one label per row would read to assistive technology as several distinct outcomes.
 - **No soft wrapping.** Output lines are `white-space: pre` inside a horizontally scrolling box. Column alignment survives; a long line scrolls instead of folding.
 - **Height cap with an expand control.** Output longer than `DEFAULT_TERMINAL_MAX_LINES` (16) lines shows `ceil(max/2)` head lines plus the remaining tail lines, with a button in between that reports the hidden count and expands. The count is of parsed lines after the trailing output terminator is dropped, so an N-line output ending in a newline is N lines. The split arithmetic preserves the former TUI transcript's collapsed-card behavior, so the established head/tail selection stays stable.
-- **ANSI color.** `anser` splits the SGR runs; `ui-primitives/src/ansi.ts` resolves each run into an inline style rendered as React spans. A foreground-only run maps the basic 16 colors onto `--dsw-*` theme tokens so authored color stays legible under both themes; a run that paints its own background keeps anser's literal rgb for both so its intended contrast survives, as do 256-palette, truecolor, and the two basic colors this design system has no token for. Sequences that carry no color (OSC strings, non-CSI escapes, inert C0 controls) are stripped before parsing so they never reach the DOM as literal characters. Cursor movements resolve before that strip, into a per-line column buffer rather than by string surgery, because carriage return and backspace only MOVE the cursor — neither erases anything, so what a reader sees is whatever each column last had written to it. `100%` then a carriage return and `OK` shows `OK0%`, since the redraw is shorter than the frame beneath it; a trailing `abc` plus a backspace still shows `abc`, since nothing overwrote the `c`; `abc` plus two backspaces and `XY` shows `aXY`. Each of these was checked against a real terminal, because the earlier truncate-and-delete approximations looked right and were not. SGR state is stamped per column as a terminal stores it per cell, so a partial overwrite keeps each surviving character's own color: red `bad`, three backspaces, then `ok` shows `okd` with the `d` still red. A CSI sequence occupies no column and changes only the state later writes are stamped with, which is also why a carriage return does not reset color, and why SGR state threads from one line to the next rather than closing at each newline. Erase-in-line is part of the same replay, because `\r\x1b[K` is the single idiom every spinner and progress bar writes — modelling the `\r` alone left the previous frame's tail standing, which is text the terminal never showed. Only `m` accumulates into a cell's style; a cursor or erase sequence must not, or the state string grows per redraw and emits boundaries anser has to discard. SGR is held per cell as a NORMALIZED record (foreground, background, attribute set), not as the sequence history: accumulating raw sequences made every state boundary re-emit the whole chain, so output that switches color without a full reset emitted O(n^2) characters — 3200 such cells produced 25 MB and a `RangeError` well under bash's own output cap. The record also lets the attribute closers every chalk-based tool writes (`39`, `49`, `22`, `24`, …) actually close their attribute, and each boundary emits one canonical sequence for the state it opens. A run also has to CLOSE: the replay converges to the state the scan ended in, not the last written cell's, because a reset after the final write changes no cell yet ends the run — without that a line finishing in `\x1b[0m` leaked its color onto every later line. The cursor advances by terminal columns, so a tab reaches the next 8-column stop, a wide character takes two (its spacer blanking rather than closing the gap once the lead cell is overwritten), and a combining mark takes none. Width follows emoji PRESENTATION rather than the U+2600-U+27BF block: `\u2713`, the check every progress line writes, is one column, so treating the block as wide misaligned exactly the output this card exists for. Writing over either half of a wide pair blanks the other, since a terminal cannot leave one cell of a two-cell glyph standing: `a\tb` then a redraw of `XY` shows `XY      b`, since a two-character redraw cannot reach column 8.
+- **ANSI color.** `anser` splits the SGR runs; `ui-primitives/src/ansi.ts` resolves each run into an inline style rendered as React spans. A foreground-only run maps the basic 16 colors onto `--dsw-*` theme tokens so authored color stays legible under both themes; a run that paints its own background keeps anser's literal rgb for both so its intended contrast survives, as do 256-palette, truecolor, and the two basic colors this design system has no token for. Sequences that carry no color (OSC strings, non-CSI escapes, inert C0 controls) are stripped before parsing so they never reach the DOM as literal characters. Cursor movements resolve before that strip, into a per-line column buffer rather than by string surgery, because carriage return and backspace only MOVE the cursor — neither erases anything, so what a reader sees is whatever each column last had written to it. `100%` then a carriage return and `OK` shows `OK0%`, since the redraw is shorter than the frame beneath it; a trailing `abc` plus a backspace still shows `abc`, since nothing overwrote the `c`; `abc` plus two backspaces and `XY` shows `aXY`. These semantics match a real terminal; truncate-and-delete approximations look right and are not. SGR state is stamped per column as a terminal stores it per cell, so a partial overwrite keeps each surviving character's own color: red `bad`, three backspaces, then `ok` shows `okd` with the `d` still red. A CSI sequence occupies no column and changes only the state later writes are stamped with, which is also why a carriage return does not reset color, and why SGR state threads from one line to the next rather than closing at each newline. Erase-in-line is part of the same replay, because `\r\x1b[K` is the single idiom every spinner and progress bar writes — modelling the `\r` alone left the previous frame's tail standing, which is text the terminal never showed. Only `m` accumulates into a cell's style; a cursor or erase sequence must not, or the state string grows per redraw and emits boundaries anser has to discard. SGR is held per cell as a NORMALIZED record (foreground, background, attribute set), not as the sequence history: accumulating raw sequences made every state boundary re-emit the whole chain, so output that switches color without a full reset emitted O(n^2) characters — 3200 such cells produced 25 MB and a `RangeError` well under bash's own output cap. The record also lets the attribute closers every chalk-based tool writes (`39`, `49`, `22`, `24`, …) actually close their attribute, and each boundary emits one canonical sequence for the state it opens. A run also has to CLOSE: the replay converges to the state the scan ended in, not the last written cell's, because a reset after the final write changes no cell yet ends the run — without that a line finishing in `\x1b[0m` leaked its color onto every later line. The cursor advances by terminal columns, so a tab reaches the next 8-column stop, a wide character takes two (its spacer blanking rather than closing the gap once the lead cell is overwritten), and a combining mark takes none. Width follows emoji PRESENTATION rather than the U+2600-U+27BF block: `\u2713`, the check every progress line writes, is one column, so treating the block as wide misaligned exactly the output this card exists for. Writing over either half of a wide pair blanks the other, since a terminal cannot leave one cell of a two-cell glyph standing: `a\tb` then a redraw of `XY` shows `XY      b`, since a two-character redraw cannot reach column 8.
 - **Exit status and copy.** A non-zero exit code or a signal renders a status pill, matching the exit-status distinction the bash tool's own renderer draws; a clean exit renders none, and settled empty output renders a dimmed placeholder — judged on the parsed lines the card renders, not on the raw text, since output that is only escapes or control bytes survives a `trim()` yet parses to nothing visible and would otherwise draw blank rows plus a copy control for invisible bytes. The copy control copies the raw output text, not the rendered tree, so the prompt line and the pill stay out of the clipboard.
 
 Geometry, radius, and fonts mirror `CodeBlock`, so a terminal card and a fenced code block match visually; `white-space: pre` plus horizontal scroll is the deliberate divergence. The clipboard write both components need moved out of `CodeBlock` into a package-internal `src/clipboard.ts`, unexported so it stays an implementation detail of the two blocks.
@@ -41,7 +41,7 @@ One premise of that split has since weakened: [tool rows stopped being details-p
 
 **Reuse `CodeBlock` with a `console` language instead of a new primitive.** Rejected: `CodeBlock` soft-wraps, which is the defect being fixed, and it has no exit status, no cwd prompt line, no height cap, and no ANSI handling. Adding four terminal-specific concerns to the shared code-fence component would impose them on every markdown fence. The two components share their geometry and font tokens instead, which is the only part where one implementation is correct for both.
 
-**Hand-roll the SGR parser.** Rejected: an SGR parser is exactly the surface [prefer maintained dependencies over hand-rolling](../process/2026-07-26-dependencies-over-hand-rolling.md) says not to own — its edge cases (256-palette and truecolor forms, `reverse`, multi-parameter runs, unterminated sequences) each fail on output nobody produces in a test, so a hand-rolled version stays subtly wrong for a long time. Stated honestly against that policy's bar: `anser` does **not** delete existing owned code. It is a capability addition, which that note distinguishes from a net-deletion simplification; the health and boundary-fit halves of the bar are what it clears. What stays hand-rolled is the part `anser` does not cover: the theme-token color mapping, the non-CSI sanitizing, the carriage-return redraw, and the per-line span folding the height cap slices.
+**Hand-roll the SGR parser.** Rejected: an SGR parser is exactly the surface [prefer maintained dependencies over hand-rolling](../process/2026-07-26-dependencies-over-hand-rolling.md) says not to own — its edge cases (256-palette and truecolor forms, `reverse`, multi-parameter runs, unterminated sequences) each fail on output nobody produces in a test, so a hand-rolled version stays subtly wrong for a long time. Against that policy's bar: `anser` does **not** delete existing owned code. It is a capability addition, which that note distinguishes from a net-deletion simplification; the health and boundary-fit halves of the bar are what it clears. What stays hand-rolled is the part `anser` does not cover: the theme-token color mapping, the non-CSI sanitizing, the carriage-return redraw, and the per-line span folding the height cap slices.
 
 ## Consequences
 
@@ -59,7 +59,7 @@ Inline rendering is licensed for the terminal intent alone. A future intent that
 
 `packages/client/ui-tool/tests/terminal-card.spec.tsx` pins the wiring at every render site: `terminalCardModel`'s derivation and each of its null arms, the result title replacing the pending one, the cwd resolving against the session workspace across all four of its cases, the panel resetting the card's expand state when the selection changes, the chat row's expand-gated body against the panel's full-height one, `BashRow`'s resident card and its agreement with its own summary row's state dot, and the panel's Output section including the run_code sub-dispatch and the out-of-window head. That file is written against no gate pressure — `packages/client/ui-tool/src/*` sits on the coverage `exclude` list in `vitest.config.ts`, so a coverage run over this package measures none of these files.
 
-`apps/web/tests/terminal-card.snapshot.ts` pins the assembled application over the built client bundles: the same render intent at both conversation render sites and in both chat-row shapes, because a bash call reaches a resident card only through the keyed `BashRow` registration and every other terminal-declaring tool name lands on the render-site fallback row, whose body is expand-gated. Fixture turn 65 was named `bash` and turn 60 left as `fx-bash` so one fixture covers both shapes, and turn 60's command was made two lines so the built-bundle snapshot pins the per-line prompt and its single dot (`dotsPerPromptRow: [1, 0]`). That terminal turn is ordered BEFORE the todo turn on purpose: the standing plan retires at the next `turn/start`, so appending it after would have emptied the dock's plan strip and taken the todo surfaces' own coverage with it; that turn also carries what turn 60's two prompt rows cannot — SGR runs resolved to `--dsw-*` tokens, output past the chat cap, a nested cwd, and a non-zero exit authored beside the sample. The sample's body deliberately carries NO `[exit code: N]` line: the real bash presenter consumes that marker out of the body precisely because the card shows the exit as its own pill, so leaving it in would pin a frame showing the exit twice — one the product path cannot produce.
+`apps/web/tests/terminal-card.snapshot.ts` pins the assembled application over the built client bundles: the same render intent at both conversation render sites and in both chat-row shapes, because a bash call reaches a resident card only through the keyed `BashRow` registration and every other terminal-declaring tool name lands on the render-site fallback row, whose body is expand-gated. Fixture turn 65 is named `bash` and turn 60 stays `fx-bash` so one fixture covers both shapes, and turn 60's command is two lines so the built-bundle snapshot pins the per-line prompt and its single dot (`dotsPerPromptRow: [1, 0]`). That terminal turn is ordered BEFORE the todo turn on purpose: the standing plan retires at the next `turn/start`, so appending it after would have emptied the dock's plan strip and taken the todo surfaces' own coverage with it; that turn also carries what turn 60's two prompt rows cannot — SGR runs resolved to `--dsw-*` tokens, output past the chat cap, a nested cwd, and a non-zero exit authored beside the sample. The sample's body deliberately carries NO `[exit code: N]` line: the real bash presenter consumes that marker out of the body precisely because the card shows the exit as its own pill, so leaving it in would pin a frame showing the exit twice — one the product path cannot produce.
 
 `apps/web/tests/navigation-panes.e2e.ts` adds the real-browser scenario over its existing `echo NAVIGATION_OK` bash call, asserting what jsdom cannot compute: squeezing the output pane below its content width leaves the line at one row and gives the pane horizontal overflow, the run-state dot resolves to the green success token rather than to a literal color (a `--dsw-*` var has no computed value at all without the real theme stylesheet) and sits inside the card box yet left of the prompt label, which is the invariant the gutter padding owns, and the copy control reaches the page's own async Clipboard API rather than the `execCommand` fallback. Its `terminal-card.expected.md` golden records the resolved workspace in the prompt row, which is what a bash call with no `workdir` must show instead of a bare `$`.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index f9dc686cfb..58c236bda9 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -20,7 +20,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 - **整次调用一枚运行状态点，位于第一行。** 它是 `StateDot` 四种状态中的三种：运行期间为追逐动画，与渲染状态徽章相同的退出状态为红色，干净落定为绿色——与工具行行首图标使用同一个指示器，因此一行与其自身的卡片不可能对同一条命令产生分歧。该状态点存在的理由是：读者对一条 shell 命令的第一个问题就是它是否仍在运行；没有它时，这一点只能从「没有输出」推断，而一条落定后无输出的命令看起来也一样。它以脱离文档流的方式落在卡片以**自身左内边距**预留的落区里，因此既不会缩进其命令，也不依赖命令自身的文本度量来与之对齐。该预留用 padding 而非 margin，是因为每个渲染点都会整条重写 `margin` 来设定自己的缩进——那会静默取消基于 margin 的落区，并让容器把状态点裁掉。无论有多少行，都只有一枚：视图携带的退出状态属于整次调用，而 bash 不报告逐条命令的状态，因此每行一枚状态点就等于在断言——一条在失败调用中其实成功了的命令行自身失败了。那一处视觉隐藏的文本标签具有相同的作用域，因为 `StateDot` 是 `aria-hidden`，而每行一个标签会被辅助技术读成好几个各自独立的结果。
 - **不软换行。** 输出行使用 `white-space: pre`，置于横向滚动的容器内。列对齐得以保留；长行滚动，而非折行。
 - **高度上限与展开控件。** 输出超过 `DEFAULT_TERMINAL_MAX_LINES`（16）行时，显示 `ceil(max/2)` 行首部加余下的尾部行数，中间是一个按钮，报告被隐藏的行数并可展开。计数针对的是剥除输出末尾终止符之后解析出的行，因此以换行结尾的 N 行输出就是 N 行。切分算法保留原 TUI transcript 折叠卡片的行为，因此既有的首尾选择保持稳定。
-- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些用例都对照真实终端核实过，因为先前「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
+- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些语义与真实终端一致；「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
 - **退出状态与复制。** 非零退出码或信号渲染一枚状态徽章，与 bash 工具自身渲染器所作的退出状态区分一致；干净退出不渲染徽章，落定后的空输出渲染一处变暗的占位文字——该判定读的是卡片实际渲染的解析行，而非原始文本，因为只含转义或控制字节的输出能通过 `trim()` 却解析不出任何可见内容，否则就会画出一片空行外加一个把不可见字节写进剪贴板的复制控件。复制控件复制的是原始输出文本而非渲染后的树，因此提示符行与徽章不会进入剪贴板。
 
 几何尺寸、圆角与字体沿用 `CodeBlock`，因此终端卡片与围栏代码块在视觉上一致；`white-space: pre` 加横向滚动是有意的分歧。两个组件都需要的剪贴板写入从 `CodeBlock` 中提取到包内部的 `src/clipboard.ts`，不对外导出，因此它仍是这两个块的实现细节。
@@ -41,7 +41,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 **复用 `CodeBlock` 并传入 `console` 语言，而不新建组件。** 已否决：`CodeBlock` 会软换行，而软换行正是本次要修的缺陷，且它没有退出状态、没有 cwd 提示符行、没有高度上限、也不处理 ANSI。把四项终端专属关注点加进共享的代码围栏组件，等于把它们强加给每一个 markdown 围栏。两个组件改为共享几何与字体 token，那是唯一一处「一套实现对两者都正确」的部分。
 
-**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛如实陈述：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它清过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
+**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它清过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
 
 ## Consequences
 
@@ -59,7 +59,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `packages/client/ui-tool/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-tool/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。
 
-`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮改名为 `bash`、第 60 轮保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
+`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮名为 `bash`、第 60 轮保持 `fx-bash`，于是一份 fixture 覆盖两种形态，而第 60 轮的命令为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
 
 `apps/web/tests/navigation-panes.e2e.ts` 在其既有的 `echo NAVIGATION_OK` bash 调用上新增真实浏览器场景，断言 jsdom 无法计算的部分：把输出面板挤压到窄于内容宽度后，行仍保持单行且面板产生横向溢出；运行状态点解析为绿色的 success token，而不是字面颜色（没有真实主题样式表时，`--dsw-*` 变量根本不产生计算值），且它位于卡片盒之内、提示标签之左——这正是那道 gutter 内边距所拥有的不变量；复制控件走的是页面自身的异步 Clipboard API，而非 `execCommand` 兜底路径。其 `terminal-card.expected.md` 基准记录了提示行中已解析的 workspace——这正是不带 `workdir` 的 bash 调用应当显示的内容，而非一个裸 `$`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
index ade585187c..6c7de886c9 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.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 .agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
-2026-07-29-ask-question-web-presentation.md: 11471bba08b723620b83af0e14e64a759d11c520
-2026-07-29-ask-question-web-presentation.zh.md: 6957d34fa5d3769340be9798998e59496e4b7f44
+2026-07-29-ask-question-web-presentation.md: a622a128a6b3ad1b1041dd8a0ae418c805655d1a
+2026-07-29-ask-question-web-presentation.zh.md: 5a43ba4f469565769234d7a13230e3edabfebf4f
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
index 11471bba08..a622a128a6 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
@@ -12,7 +12,7 @@ Separately, the composer visuals had drifted from the current design: an expand-
 
 ## Decision
 
-A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `tool.call.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrows to `PendingWait<'approval'>` and `ChatView` filters the pending list to approval waits, so the placeholder card now exists only for the approval takeover still on the roadmap.
+A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `tool.call.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrowed to `PendingWait<'approval'>` and `ChatView` filtered the pending list to approval waits, leaving the placeholder card to approvals alone; the approval composer takeover ([web permission and approval](2026-07-23-web-permission-and-approval.md)) has since removed it entirely.
 
 The composer redesign moves paging into the footer next to the actions, renders multi-select options with explicit checkboxes, keeps single-select numbered rows, and replaces the expand-to-open custom entry with an always-visible custom input row (textarea for optionless questions). The `parseQuestionTitle` multi-select suffix convention is deleted; `multi_select` is already structured metadata, so the title renders verbatim.
 
@@ -36,7 +36,7 @@ Two adjacent fixes ride along. All generic toolview leading icons (and the hover
 
 `ask_user_question` and `todo_write` now demonstrate the intended toolview pattern: compose `ToolRow`, summarize from call args or result JSON with shape-checked fallbacks, and register through the keyed slot. The bespoke `todo-row.module.css` is gone.
 
-The row verdict strings are the one remaining hardcoded-English surface of the question flow; localizing them is deferred follow-up. `PendingCard` remains a visible-but-not-answerable approval placeholder until the approval composer takeover ships.
+The row verdict strings are the one remaining hardcoded-English surface of the question flow; localizing them is deferred follow-up. The approval composer takeover shipped ([web permission and approval](2026-07-23-web-permission-and-approval.md), height-capped per the [approval-panel note](../bug-fix/2026-07-30-approval-panel-command-cap.md)), and `PendingCard` no longer exists.
 
 `ui-question` gains a `dsh-client-locale` dependency and an inject face where it previously had none; its contract (`QuestionComposerInjected`) lives with the consumer in `contract/slots.ts`.
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
index 6957d34fa5..5a43ba4f46 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
@@ -12,7 +12,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 ## 决定
 
-一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `tool.call.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 收窄为 `PendingWait<'approval'>`，`ChatView` 将待处理列表过滤为仅审批等待，占位卡片从此只服务于仍在路线图上的审批接管。
+一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `tool.call.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 曾收窄为 `PendingWait<'approval'>`，`ChatView` 曾将待处理列表过滤为仅审批等待，使占位卡片只服务于审批；其后审批输入区接管（[Web 权限与审批](2026-07-23-web-permission-and-approval.md)）已将它彻底移除。
 
 输入区重设计将分页移到底部操作区旁，多选选项渲染显式复选框，单选保留编号行，并用始终可见的自定义输入行取代展开式自定义入口（无选项问题用多行文本框）。删除 `parseQuestionTitle` 的多选后缀约定；`multi_select` 已是结构化元数据，标题原样渲染。
 
@@ -36,7 +36,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 `ask_user_question` 与 `todo_write` 现在共同示范预期的 toolview 模式：复用 `ToolRow`、从调用参数或结果 JSON 做带形状校验回退的摘要、通过带 key 的槽位注册。专用的 `todo-row.module.css` 已删除。
 
-行内裁决字符串是问题流程仅剩的硬编码英文面；将其本地化是推迟的后续工作。在审批输入区接管交付之前，`PendingCard` 仍是可见但不可操作的审批占位。
+行内裁决字符串是问题流程仅剩的硬编码英文面；将其本地化是推迟的后续工作。审批输入区接管已交付（[Web 权限与审批](2026-07-23-web-permission-and-approval.md)，并按[审批面板 Agent Note](../bug-fix/2026-07-30-approval-panel-command-cap.md)施加高度上限），`PendingCard` 已不复存在。
 
 `ui-question` 新增 `dsh-client-locale` 依赖和此前没有的 inject face；其约定（`QuestionComposerInjected`）与消费者一起放在 `contract/slots.ts`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index 75e70f4fba..9db1928c8d 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.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 .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
-2026-07-30-queued-manual-compaction.md: 94afdd84dfe573ee2b60eb3dbfdae2dd5b6beb1e
-2026-07-30-queued-manual-compaction.zh.md: bd120050e621d1bfa3a677578e429f939b9c17d1
+2026-07-30-queued-manual-compaction.md: 3aa4e17bd673417569990090abec0ec29427665a
+2026-07-30-queued-manual-compaction.zh.md: 0763d6d127d158fa3b91b52aaa9b28ddf78e839f
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
index 94afdd84df..3aa4e17bd6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
@@ -12,7 +12,7 @@ The human command arrives between turns and must summarize asynchronously. A pro
 
 Compaction also needs one mutual-exclusion fact shared by manual, pressure, overflow, and explicit-range entry points. A process-local flag alone cannot explain a crash-recovered log, while a summarize-first transaction leaves no durable evidence during the expensive interval. Conversely, treating marker pairs as exclusive containers would forbid valid idle injection even though injection is explicitly non-waking and immediate between turns.
 
-This note extends the [compaction capability seam](2026-06-18-compaction-capability-seam.md), the [session end-seed boundary](../architecture/2026-07-30-session-end-seed-log-boundary.md), and the [removal of synthetic log-only turns](../simplification/2026-07-28-remove-synthetic-log-only-turns.md). The supersession audit found partial overlap only: each remains active and owns its broader decision.
+This note extends the [compaction capability seam](2026-06-18-compaction-capability-seam.md), the [session end-seed boundary](../architecture/2026-07-30-session-end-seed-log-boundary.md), and the [removal of synthetic log-only turns](../simplification/2026-07-28-remove-synthetic-log-only-turns.md). Each remains active and owns its broader decision; the overlap is partial only.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index bd120050e6..0763d6d127 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 手动、压力、溢出和显式范围入口点还需要共享同一项互斥事实。仅使用进程本地标志无法解释一份崩溃恢复后的日志，而先摘要再记录的事务在开销较大的等待期间不会留下持久证据。反过来，把标记对视为排他容器又会禁止有效的空闲注入，尽管注入按定义不会唤醒，并且会在轮次之间立即执行。
 
-本 Agent Note 扩展[压缩能力 seam](2026-06-18-compaction-capability-seam.md)、[会话 end-seed 边界](../architecture/2026-07-30-session-end-seed-log-boundary.md)和[移除纯日志事件的合成轮次](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)。取代关系审计只发现部分重叠：三者均保持活动状态，并拥有各自更广泛的决策。
+本 Agent Note 扩展[压缩能力 seam](2026-06-18-compaction-capability-seam.md)、[会话 end-seed 边界](../architecture/2026-07-30-session-end-seed-log-boundary.md)和[移除纯日志事件的合成轮次](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)。三者均保持活动状态，并拥有各自更广泛的决策；重叠仅是部分的。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index cee07159d1..1d5b00e8e0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.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 .agents/notes/implemented/feature/2026-07-30-search-render-card.md
-2026-07-30-search-render-card.md: 29544cb703f3ab048f4e7702935887ecf05179bf
-2026-07-30-search-render-card.zh.md: 01ffe25522c462a26e781f9bd455711331e58445
+2026-07-30-search-render-card.md: 585609bd059dbd9aa8283547fa8a4b223f7bdd99
+2026-07-30-search-render-card.zh.md: 2cb28a29f8a1a265310fecb1f0a315d010250e02
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
index 29544cb703..585609bd05 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
@@ -18,7 +18,7 @@ The discriminant is `shape`, not `kind`, deliberately: the same presentation mod
 
 One view with two shapes rather than two cards, because both tools are the same visual object — a search result — and a web consumer switches on one `card` value, then on `shape` for the row layout. The discriminated `shape` keeps each variant's fields non-optional (a matches view always has `files`, a paths view always has `paths`) instead of a single interface where every shape-specific field is optional.
 
-The view carries **no** result text. An earlier revision attached the model-facing `result.content` to the view; that was a no-op because consumer fallbacks already read the raw `tool/result` content, and it serialized the whole search text a second time into the persisted view. The view is the structured shape only; a UI without a search card falls back to the raw result content.
+The view carries **no** result text. Attaching the model-facing `result.content` would be a no-op — consumer fallbacks already read the raw `tool/result` content — and would serialize the whole search text a second time into the persisted view. The view is the structured shape only; a UI without a search card falls back to the raw result content.
 
 The card tag is result-time only. A search call stays a `GenericCallView` (`kind: 'search'`): the pending state has no matches or paths to show, so there is nothing a `SearchCallView` would carry that the generic title does not. This is the asymmetry with the terminal card, whose call view carries the command, cwd, and description that exist before execution; a search's structured content exists only after `execute`.
 
@@ -30,7 +30,7 @@ The card tag is result-time only. A search call stays a `GenericCallView` (`kind
 
 The `SearchMeta` member shapes are object-literal `type` aliases, not the `SearchFileMatches`/`SearchLineMatch` interfaces the view exposes, because only a type alias is assignable to the `JsonValue` index signature `presentationMeta` returns; the two are structurally identical, so the projected value still reads back as a `SearchResultView`.
 
-A consumer without a dedicated `search` arm falls back to the same generic body and reads the model-facing text from the raw result. Because the search view carries no `content` of its own and grep/glob returned a generic card before this PR, that fallback stays byte-identical to the pre-search-card path. The frontend that renders the structured `files`/`paths` shape is independent of this backend contract and its two producers.
+A consumer without a dedicated `search` arm falls back to the same generic body and reads the model-facing text from the raw result. Because the search view carries no `content` of its own and grep/glob previously returned a generic card, that fallback stays byte-identical to the pre-search-card path. The frontend that renders the structured `files`/`paths` shape is independent of this backend contract and its two producers.
 
 ## Alternatives considered
 
@@ -40,7 +40,7 @@ A consumer without a dedicated `search` arm falls back to the same generic body
 
 **Attach the model-facing text as the view's `content`.** Rejected: a no-op for every current consumer and a second serialization of the whole search text into the persisted view. The view is the structured shape; text fallback reads the raw result content.
 
-**A meta channel on `PostToolDecision` so `dsh-spill-policy` bounds `meta` like it bounds `content`.** Rejected for this PR: it changes the core tool decision contract and the spill-policy plugin for one tool's payload. The projection bounding its own `meta` at a config byte cap is self-contained and keeps the seam unchanged.
+**A meta channel on `PostToolDecision` so `dsh-spill-policy` bounds `meta` like it bounds `content`.** Rejected here: it changes the core tool decision contract and the spill-policy plugin for one tool's payload. The projection bounding its own `meta` at a config byte cap is self-contained and keeps the seam unchanged.
 
 **A call-time `SearchCallView` mirroring the terminal card's both-sides symmetry.** Rejected: a search call has no matches or paths before `execute`, so the view would carry only the title the `GenericCallView` already carries.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index 01ffe25522..2cb28a29f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 用一个带两种形状的视图而非两张卡片，因为两个工具是同一个视觉对象 —— 一个搜索结果 —— web 消费方先在一个 `card` 值上分支，再在 `shape` 上分支决定行布局。判别式 `shape` 让每个变体的字段保持非可选（matches 视图总有 `files`，paths 视图总有 `paths`），而不是一个所有形状相关字段都可选的单一接口。
 
-该视图**不**携带结果文本。早期版本曾把面向模型的 `result.content` 附到视图上；但消费方的回退路径本就读取原始 `tool/result` 内容，因此这不会产生效果，却会把整段搜索文本又序列化进持久化视图一遍。视图只承载结构化形状；无 search 卡片的 UI 回退到原始结果内容。
+该视图**不**携带结果文本。把面向模型的 `result.content` 附到视图上不会产生效果——消费方的回退路径本就读取原始 `tool/result` 内容——却会把整段搜索文本又序列化进持久化视图一遍。视图只承载结构化形状；无 search 卡片的 UI 回退到原始结果内容。
 
 卡片标签只在结果时存在。搜索调用保持为 `GenericCallView`（`kind: 'search'`）：pending 状态没有匹配或路径可展示，所以 `SearchCallView` 能携带的东西不会比 generic 标题更多。这是与 terminal 卡片的不对称之处 —— terminal 的调用视图携带执行前就存在的命令、cwd、description；搜索的结构化内容只在 `execute` 之后才存在。
 
@@ -30,7 +30,7 @@ Status: implemented
 
 `SearchMeta` 的成员形状是对象字面量 `type` 别名，而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口，因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名；两者结构等价，所以投影值仍读回为 `SearchResultView`。
 
-没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
+没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而 grep/glob 此前返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
 
 ## 考虑过的备选
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **把面向模型的文本作为视图的 `content` 附上。** 否决：对每个当前消费方是 no-op，且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状；文本回退读原始结果内容。
 
-**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
+**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 此处否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
 
 **镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决：搜索调用在 `execute` 前没有匹配或路径，视图只会携带 `GenericCallView` 已有的标题。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index 2e01db1284..549145aad0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.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 .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
-2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
-2026-07-30-web-diff-card.zh.md: 901331907ed9052541aaee0d4fe70531b030d0f9
+2026-07-30-web-diff-card.md: d8b0cf32e42af45e16e6f7059c873c384d4a9229
+2026-07-30-web-diff-card.zh.md: 51df03c3f8b79cd8415a15bd30e92e3c152f335e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index b078da8d0e..d8b0cf32e4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -32,7 +32,7 @@ The chat row renders the diff resident under its path-link summary, capped at `C
 
 **A side-by-side (two-column) diff.** Rejected for now by the owner: it is denser but does not fit the narrow chat row, and the goal was parity with the TUI's single-column unified form. A two-column mode in the details panel is a later props change, not a redesign.
 
-**Git-style line-number gutters.** The `FileDiff` contract carries only `{ path, oldText, newText }` — `structuredPatch`'s hunk start lines are dropped in `diff.ts`, so no line number reaches the client. Rendering a numbered gutter needs a backend contract change (carry `oldStart`/`newStart`) and a matching TUI upgrade to stay consistent; deferred so this PR stays a pure Web consumer of the existing contract.
+**Git-style line-number gutters.** The `FileDiff` contract carries only `{ path, oldText, newText }` — `structuredPatch`'s hunk start lines are dropped in `diff.ts`, so no line number reaches the client. Rendering a numbered gutter needs a backend contract change (carry `oldStart`/`newStart`) and a matching TUI upgrade to stay consistent; deferred so this change stays a pure Web consumer of the existing contract.
 
 **Reuse `CodeBlock`.** Rejected for the same reason the terminal card was: `CodeBlock` soft-wraps and has no per-line `+`/`-` role, no path headers, and no footer. The two share geometry and font tokens, which is the only part where one implementation is correct for both.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index 901331907e..51df03c3f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -32,7 +32,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 **并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
 
-**git 式行号槽。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有约定的纯 Web 消费。
+**git 式行号槽。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本变更保持为对既有约定的纯 Web 消费。
 
 **复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index b4992a15c3..9e159b5b40 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
-2026-07-30-web-read-card-frontend.md: e659645066b706f35709fead4c11023eb4fe9554
-2026-07-30-web-read-card-frontend.zh.md: ac3972ace7458b8a751b4cc342bbdb3e2b0a7a9e
+2026-07-30-web-read-card-frontend.md: 1d9b6d7fa0c8b5391d175a53507db88a84234b91
+2026-07-30-web-read-card-frontend.zh.md: 2678d50e851e4b3a079f59c7db6ec08ecc5c4aed
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
index e659645066..1d9b6d7fa0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
@@ -18,11 +18,11 @@ The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent car
 
 The chat row renders the card **resident** under the summary line, capped at `CHAT_READ_MAX_LINES` (8, half the primitive's default), the same posture `BashRow` gives a terminal card — the block's internal expander keeps a long read from taking over the message flow. Two render sites carry it: the keyed `ReadRow` (registered under `read` through `ctx.slots.inject`, exactly as the bash sample) whose summary is the file path as an openable host link, and `GenericToolCard`'s fallback for a read-declaring tool without its own keyed row (e.g. `web_fetch`, which classifies to the `read` variant). The details panel renders the same card at the primitive's own full-height cap (16), because the panel is the single-call reading surface.
 
-Whole-row collapse/expand (defaulting every tool call to collapsed) is a separate later change that will flip every resident card at once; this note's card is resident, matching the terminal card it sits beside.
+Whole-row collapse/expand (defaulting every tool call to collapsed) is owned by the [unified expand-and-inspect note](2026-07-30-web-tool-row-unified-expand-and-inspect.md), which flipped every resident card at once; this note's card is resident, matching the terminal card it sits beside.
 
 **Read-card grammars load lazily; only the boot three stay eager.** `highlight.ts` is a platform seed `ui-primitives` loads on every Web boot, and its warm-up unconditionally builds the shiki singleton. The read card's `langFromPath` hints span the full source/config/markup extension set (python, rust, yaml, html, …); registering all of them eagerly would add ~1.6 MB of grammar modules to the boot chunk and their synchronous init to every session, including sessions that never open a read card. So only the three grammars every session already renders — TypeScript, shell, JSON (the markdown-fence and `run_code` languages) — load at boot. Each read-card extension grammar sits behind a dynamic `import()` in `LAZY_GRAMMARS`, keyed by the grammar id its aliases resolve to. On the first `highlightLines`/`highlightToHtml` call for a lazy language, `ensureGrammar` starts the import (once) and returns not-ready, so the card renders plain that frame; when the import resolves it registers the grammar with `loadLanguageSync`, bumps a load counter, and notifies subscribers. `ReadBlock` and `CodeBlock` subscribe through `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)`, so the card re-renders with highlighting the moment the grammar is ready. An unknown/absent language still returns undefined synchronously (plain, never an error).
 
-**The empty-window copy control is hidden, matching `TerminalBlock`.** A successful read of an empty file returns `lines: []`, `totalLines: 0`, and `presentResult` still projects `card: 'read'`, so the empty-window branch is reachable — the read card is not, as an earlier draft assumed, unreachable for an empty result. `ReadBlock` therefore hides the copy control when `lines` is empty, exactly as `TerminalBlock` hides copy on empty output, so the button can never wipe the clipboard with an empty string.
+**The empty-window copy control is hidden, matching `TerminalBlock`.** A successful read of an empty file returns `lines: []`, `totalLines: 0`, and `presentResult` still projects `card: 'read'`, so the empty-window branch is reachable. `ReadBlock` therefore hides the copy control when `lines` is empty, exactly as `TerminalBlock` hides copy on empty output, so the button can never wipe the clipboard with an empty string.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index ac3972ace7..2678d50e85 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -18,11 +18,11 @@ Status: implemented
 
 聊天行把卡片**常驻**渲染在摘要行之下，上限 `CHAT_READ_MAX_LINES`（8，是 primitive 默认值的一半），与 `BashRow` 对终端卡片的姿态相同 —— block 的内部展开器让长读取不会占据整个消息流。两个渲染点承载它：keyed `ReadRow`（经 `ctx.slots.inject` 以 `read` 键注册，与 bash 样例完全一致），其摘要是作为可打开的宿主链接的文件路径；以及 `GenericToolCard` 对没有自己 keyed 行的读取声明工具（例如归到 `read` 变体的 `web_fetch`）的回退。详情面板以 primitive 自己的全高上限（16）渲染同一张卡片，因为面板是单次调用的阅读界面。
 
-整行折叠/展开（把每个工具调用默认折叠）是一个单独的后续改动，它会一次性翻转每张常驻卡片；本 note 的卡片是常驻的，与它旁边的终端卡片一致。
+整行折叠/展开（把每个工具调用默认折叠）归[统一展开与检视 note](2026-07-30-web-tool-row-unified-expand-and-inspect.md)所有，它已一次性翻转每张常驻卡片；本 note 的卡片是常驻的，与它旁边的终端卡片一致。
 
 **读取卡片的语法按需 lazy 加载，只有 boot 三种保持 eager。** `highlight.ts` 是 `ui-primitives` 在每次 Web 启动都加载的平台 seed，其预热会无条件构建 shiki 单例。读取卡片的 `langFromPath` 提示覆盖完整的源码/配置/标记扩展集（python、rust、yaml、html……）；把它们全部 eager 注册会给启动 chunk 增加约 1.6 MB 的语法模块、并把它们的同步初始化摊给每个会话，包括从不打开读取卡片的会话。因此只有每个会话本就渲染的三种语法 —— TypeScript、shell、JSON（markdown 围栏与 `run_code` 语言）—— 在 boot 时加载。每种读取卡片扩展语法置于 `LAZY_GRAMMARS` 中一个动态 `import()` 之后，以其别名解析到的语法 id 为键。对某个 lazy 语言首次调用 `highlightLines`/`highlightToHtml` 时，`ensureGrammar` 启动 import（仅一次）并返回未就绪，于是卡片该帧渲染纯文本；import 解析后用 `loadLanguageSync` 注册该语法、递增一个加载计数、并通知订阅者。`ReadBlock` 与 `CodeBlock` 通过 `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)` 订阅，因此语法就绪的那一刻卡片就重渲染带上高亮。未知/缺省语言仍同步返回 undefined（纯文本，绝不报错）。
 
-**空窗口的复制控件被隐藏，与 `TerminalBlock` 对齐。** 成功读取一个空文件会返回 `lines: []`、`totalLines: 0`，且 `presentResult` 仍投出 `card: 'read'`，因此空窗口分支是可达的 —— 读取卡片并非如早前草稿所假设的对空结果不可达。故 `ReadBlock` 在 `lines` 为空时隐藏复制控件，正如 `TerminalBlock` 对空输出隐藏复制，使按钮绝不会用空字符串清空剪贴板。
+**空窗口的复制控件被隐藏，与 `TerminalBlock` 对齐。** 成功读取一个空文件会返回 `lines: []`、`totalLines: 0`，且 `presentResult` 仍投出 `card: 'read'`，因此空窗口分支是可达的。故 `ReadBlock` 在 `lines` 为空时隐藏复制控件，正如 `TerminalBlock` 对空输出隐藏复制，使按钮绝不会用空字符串清空剪贴板。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
index a58a19000a..1981decbb3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.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 .agents/notes/implemented/feature/2026-07-30-web-read-card.md
-2026-07-30-web-read-card.md: 26d1634b6be86666980e65f842de51c868c26efd
-2026-07-30-web-read-card.zh.md: c48cd56b7f919d5ceb702f890ee18a2a735da347
+2026-07-30-web-read-card.md: 8ed170e3bbe63cdee85f0ee8440ab1d975c6ff0a
+2026-07-30-web-read-card.zh.md: 68ab9a118e946f397b69691a02a55d1c43ee41b1
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.md
index 26d1634b6b..8ed170e3bb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.md
@@ -16,7 +16,7 @@ Add a fourth `card` tag, `read`, to the [render-intent union](../architecture/20
 
 The read tool projects the structured window through `output.presentationMeta`, the same persisted channel write/edit use for their applied-diff hunks ([canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md)). `presentationMeta` runs once for a top-level surface call, returns `{ path, offset, lines, totalLines, lang? }` as JSON the session validates and stores on the result's `meta`, and `presentResult` narrows that meta back into the `ReadResultView` on both live and replay paths. `offset` (the 1-based first line the window requested) rides along because a byte cap below the first selected line yields an empty `lines` array with a positive `totalLines`; without the persisted `offset` a replayed card of such a window could not report where it starts or where a continuation resumes, and the last-line and re-parse fallbacks are both lossy. Without this channel the line array and total would be unreachable: the raw output object is not on the wire, and re-parsing the `N: text` text is lossy and fragile against the truncation footer.
 
-`presentResult` returns `undefined` — the generic fallback — whenever the meta is absent or malformed (`readMetaFromMeta` narrows it defensively, so a replay of an older logged result never throws), whenever the result is an error, and whenever the single text block is not the read envelope. A pre-card logged result — a valid read envelope with no persisted `meta`, recorded before this card existed — takes that same `undefined` path deliberately: the client falls back to the raw `result.content`, so it shows the enveloped `<path>/<type>/<content>` text rather than the envelope-stripped generic card the old presenter returned. This is the accepted degradation under the [pre-release stance](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius): reject the old on-disk format rather than add an envelope-stripping compatibility branch, since this PR re-records every published fixture and the session format promises no backward compatibility. On the success path `presentResult` carries `content` (the envelope-stripped text) alongside the structured fields, so a UI without the read capability renders the file text through its generic/default card arm. The former TUI established the need for this fallback: its non-exhaustive result switch read `view.content`, while a separate dim-Markdown gate also had to admit `card: 'read'`. That frontend has since been removed, but the content fallback remains part of the view contract for any consumer without a structured read card.
+`presentResult` returns `undefined` — the generic fallback — whenever the meta is absent or malformed (`readMetaFromMeta` narrows it defensively, so a replay of an older logged result never throws), whenever the result is an error, and whenever the single text block is not the read envelope. A pre-card logged result — a valid read envelope with no persisted `meta`, recorded before this card existed — takes that same `undefined` path deliberately: the client falls back to the raw `result.content`, so it shows the enveloped `<path>/<type>/<content>` text rather than the envelope-stripped generic card the old presenter returned. This is the accepted degradation under the [pre-release stance](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius): reject the old on-disk format rather than add an envelope-stripping compatibility branch, since this change re-records every published fixture and the session format promises no backward compatibility. On the success path `presentResult` carries `content` (the envelope-stripped text) alongside the structured fields, so a UI without the read capability renders the file text through its generic/default card arm. The former TUI established the need for this fallback: its non-exhaustive result switch read `view.content`, while a separate dim-Markdown gate also had to admit `card: 'read'`. That frontend has since been removed, but the content fallback remains part of the view contract for any consumer without a structured read card.
 
 ### Language hint derivation
 
@@ -40,7 +40,7 @@ The read tool now computes `presentationMeta` for every top-level read, a small
 
 ## Testing
 
-`packages/fs/tool-fs/tests/read-render.spec.ts` unit-tests `langFromPath` (known extensions case-insensitively, extension read after the last segment and last dot, and the `undefined` cases: dotfile, extensionless, trailing dot, unknown) and `readMetaFromMeta` (a well-formed narrow with and without `lang`, and every rejection: non-object, array, missing or wrong-typed `path`/`totalLines`/`lines`, a malformed line entry, a non-string `lang`, and — because the function narrows the opaque persisted `meta` boundary — the semantically invalid paths a well-typed replayed JSON can still carry: an `offset` that is not a 1-based integer, a first line `number` below `offset`, a line `number` that is not a 1-based integer (`0`, `1.5`, `NaN`, `Infinity`), a `totalLines` that is not a non-negative integer (`-1`, `1.5`, `NaN`), and lines whose numbers duplicate, decrease, or exceed `totalLines`; it also narrows an empty window at a positive `offset` (a byte cap below the first selected line). `packages/fs/tool-fs/tests/tools.spec.ts` pins the tool wiring: `execute` attaches the structured window (with and without a `lang` hint) as `meta`, `presentResult` narrows it into a `card: 'read'` view carrying the envelope-stripped `content`, and the decline paths (error result, non-single-text content, malformed envelope with valid meta, and valid envelope with absent or malformed meta) all fall back to `undefined`. Both changed source files hold per-file 100% coverage. This PR carries the snapshot evidence for the persisted meta and the extended union, not for a new rendered view: the re-recorded ACP session fixtures (`fs-read`, `fs-read-window`, `fs-edit`, `fs-policy-reject`, `fs-write-overwrite`, `parallel-tool-calls`, `workspace-context`, `workspace-edit`) pin the persisted read `meta` (with `{{cwd}}`-tokenized paths), and `cordis-inspect-jsdoc` pins the four-member `ToolResultView` union. The then-current terminal snapshot also pinned that a consumer's generic dim-Markdown fallback stayed byte-identical; the structured card's own assembled-application transcript belonged to its consuming frontend change.
+`packages/fs/tool-fs/tests/read-render.spec.ts` unit-tests `langFromPath` (known extensions case-insensitively, extension read after the last segment and last dot, and the `undefined` cases: dotfile, extensionless, trailing dot, unknown) and `readMetaFromMeta` (a well-formed narrow with and without `lang`, and every rejection: non-object, array, missing or wrong-typed `path`/`totalLines`/`lines`, a malformed line entry, a non-string `lang`, and — because the function narrows the opaque persisted `meta` boundary — the semantically invalid paths a well-typed replayed JSON can still carry: an `offset` that is not a 1-based integer, a first line `number` below `offset`, a line `number` that is not a 1-based integer (`0`, `1.5`, `NaN`, `Infinity`), a `totalLines` that is not a non-negative integer (`-1`, `1.5`, `NaN`), and lines whose numbers duplicate, decrease, or exceed `totalLines`; it also narrows an empty window at a positive `offset` (a byte cap below the first selected line). `packages/fs/tool-fs/tests/tools.spec.ts` pins the tool wiring: `execute` attaches the structured window (with and without a `lang` hint) as `meta`, `presentResult` narrows it into a `card: 'read'` view carrying the envelope-stripped `content`, and the decline paths (error result, non-single-text content, malformed envelope with valid meta, and valid envelope with absent or malformed meta) all fall back to `undefined`. Both changed source files hold per-file 100% coverage. This change carries the snapshot evidence for the persisted meta and the extended union, not for a new rendered view: the re-recorded ACP session fixtures (`fs-read`, `fs-read-window`, `fs-edit`, `fs-policy-reject`, `fs-write-overwrite`, `parallel-tool-calls`, `workspace-context`, `workspace-edit`) pin the persisted read `meta` (with `{{cwd}}`-tokenized paths), and `cordis-inspect-jsdoc` pins the four-member `ToolResultView` union. The then-current terminal snapshot also pinned that a consumer's generic dim-Markdown fallback stayed byte-identical; the structured card's own assembled-application transcript belonged to its consuming frontend change.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
index c48cd56b7f..68ab9a118e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
 
-`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
+`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本变更已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
 
 ### 语言提示推导
 
@@ -40,7 +40,7 @@ read 工具现在为每次顶层 read 计算 `presentationMeta`，这是对已
 
 ## Testing
 
-`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名的大小写不敏感、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的 opaque `meta` 边界——良构类型的回放 JSON 仍可能携带的语义无效路径：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本 PR 携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP session fixtures（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript 则属于消费它的前端变更。
+`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名的大小写不敏感、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的 opaque `meta` 边界——良构类型的回放 JSON 仍可能携带的语义无效路径：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本变更携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP session fixtures（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript 则属于消费它的前端变更。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index 9233d3f0c6..37debadbe3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: 0f3e46cda1aeeb0f526f839a9071f09058810b86
-2026-07-30-web-result-card-frontend.zh.md: d9802099f7d2300b4a4c88556103d0c014aaebee
+2026-07-30-web-result-card-frontend.md: c048c4f93f72e4a1da5c6426497e9274d65ac266
+2026-07-30-web-result-card-frontend.zh.md: a7090818dc023f857e01e43773adccfba585cc55
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index 0f3e46cda1..c048c4f93f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -24,13 +24,13 @@ The card is **resident** under the summary row in the chat rows, the same reside
 
 `WebBlock` reads only the web view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view, and unlike the terminal card it needs no cwd resolution because a web view carries no path. A UI without the `web` capability (the TUI) still gets the contract's fallback `content`; nothing about the tools' result shape changed. `MarkdownText` is reused for the answer, so the answer's own untrusted-link handling and GFM rendering come for free.
 
-A separate later PR unifies the whole-row collapse/expand interaction and will flip every resident card (terminal, diff, web) to expand-gated at once; this card follows the current resident convention rather than pre-empting that change.
+The whole-row collapse/expand interaction shared by every resident card (terminal, diff, web) is owned by the [unified expand-and-inspect note](2026-07-30-web-tool-row-unified-expand-and-inspect.md); this card follows the resident convention rather than pre-empting that interaction.
 
 ## Alternatives considered
 
 **Two components, one per kind.** Rejected: the two shapes share their card chrome, their safe-link handling, and their truncation indicator, and the contract already expresses their difference as a `kind` discriminant under one `card` tag; two components would duplicate the shared surface and split the safe-link logic.
 
-**Reparse the model-facing render text instead of consuming the structured view.** Rejected for the same reason the contract note gives: `web_search`'s render collapses each source's fields into one free-text line labelled by title OR hostname, so reparsing cannot recover `{url, title?, snippet?, publishedAt?}`. The structured `resultView` is the only faithful source, which is why the backend PR added it.
+**Reparse the model-facing render text instead of consuming the structured view.** Rejected for the same reason the contract note gives: `web_search`'s render collapses each source's fields into one free-text line labelled by title OR hostname, so reparsing cannot recover `{url, title?, snippet?, publishedAt?}`. The structured `resultView` is the only faithful source, which is why the backend contract adds it.
 
 **Render plain anchors without the protocol allowlist.** Rejected: the URL is model-authored and unverified at this presentation boundary, so an unfiltered href would let a `javascript:` URL execute on click. The allowlist is the http(s) subset of MarkdownText's (which also permits `mailto:`), so untrusted retrieval links behave identically wherever they render.
 
@@ -44,7 +44,7 @@ The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (
 
 ## Related
 
-- [Web result card](2026-07-30-web-result-card.md) — the backend PR that added the `card: 'web'` result arm and made the two tools emit it; this is its deferred frontend consumer.
+- [Web result card](2026-07-30-web-result-card.md) — the backend contract that added the `card: 'web'` result arm and made the two tools emit it; this note owns its frontend consumer.
 - [Web search source card scrolls instead of collapsing](2026-08-03-web-search-source-scroll.md) — replaces this note's source-list head/tail collapse with a fixed-height scroll container and removes `CHAT_WEB_MAX_SOURCES` and the primitive's own source cap; every other decision here still holds.
 - [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this mirrors: a `ui-primitives` block, a single card-model derivation, keyed and fallback chat rows, and a details-panel arm, for the `terminal` render intent.
 - [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary; the Web client is now a full consumer of the `web` arm.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index d9802099f7..a7090818dc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -24,13 +24,13 @@ Status: implemented
 
 `WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到约定的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
 
-一条独立的后续 PR 会统一整行折叠/展开交互,并把每张常驻卡片（terminal、diff、web）一次性翻成 expand-gated;本卡片遵循当前的常驻约定,而非抢先做那次改动。
+每张常驻卡片（terminal、diff、web）共用的整行折叠/展开交互归[统一展开与检视 note](2026-07-30-web-tool-row-unified-expand-and-inspect.md)所有;本卡片遵循常驻约定,而非抢先做那套交互。
 
 ## Alternatives considered
 
 **两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而约定已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
 
-**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
+**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端约定添加它的原因。
 
 **不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此展示边界处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
@@ -44,7 +44,7 @@ fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（
 
 ## Related
 
-- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费者。
+- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端契约;其前端消费方归本 note 所有。
 - [Web search 来源卡片改为滚动而非折叠](2026-08-03-web-search-source-scroll.md) —— 用定高滚动容器替换本笔记的 source 列表头/尾折叠,并移除 `CHAT_WEB_MAX_SOURCES` 与原语自身的 source 上限;本笔记的其余决策依然成立。
 - [Web terminal card](2026-07-28-web-terminal-card.md) —— 本条所镜像的先例:一个 `ui-primitives` block、一处 card-model 派生、键控与兜底 chat 行、以及一个详情面板支路,用于 `terminal` 渲染意图。
 - [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费者。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index 9eba8730a4..cb45227d19 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.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 .agents/notes/implemented/feature/2026-07-30-web-result-card.md
-2026-07-30-web-result-card.md: 838b13a7f3240c753e5cd1af6909389055c6352d
-2026-07-30-web-result-card.zh.md: 36ab372864e5cd848b999ee759e73658271b8f90
+2026-07-30-web-result-card.md: 591471d219295019d28b9eeaf2e57f6d2115d380
+2026-07-30-web-result-card.zh.md: a2e0096599a30bcdd1d8a956d8f1c13c1c0622fd
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.md
index 838b13a7f3..591471d219 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.md
@@ -22,7 +22,7 @@ Neither result view carries a `content` copy. A UI that does not render the stru
 
 ## Consequences
 
-The frontend consumer was a separate later PR: this producer change adds the contract arm and makes the two tools emit it, with no client-side rendering. Its one observable change is that the `web_search`/`web_fetch` `tool/result` events persist a `data.meta` payload (the `web-fetch` keyless snapshot was refreshed accordingly); model-facing render text and generic fallback content stay unchanged. The assembled-application transcript snapshot that exercises a `web` card belongs to the consumer change that renders it. Any `ToolResultView` consumer that switches exhaustively must add a `web` arm; a non-exhaustive consumer may use the raw-result fallback. `apiproxy`'s session schema already accepts any `card` string (`packages/host/apiproxy/src/api/sessions.schema.ts`), so the new view crosses the wire without a schema change.
+The frontend consumer is owned by the [web result card frontend note](2026-07-30-web-result-card-frontend.md): this producer change adds the contract arm and makes the two tools emit it, with no client-side rendering. Its one observable change is that the `web_search`/`web_fetch` `tool/result` events persist a `data.meta` payload (the `web-fetch` keyless snapshot was refreshed accordingly); model-facing render text and generic fallback content stay unchanged. The assembled-application transcript snapshot that exercises a `web` card belongs to the consumer change that renders it. Any `ToolResultView` consumer that switches exhaustively must add a `web` arm; a non-exhaustive consumer may use the raw-result fallback. `apiproxy`'s session schema already accepts any `card` string (`packages/host/apiproxy/src/api/sessions.schema.ts`), so the new view crosses the wire without a schema change.
 
 A future web tool that wants this card declares `presentResult` returning a `card: 'web'` view with its own `kind`; adding a third `kind` is a union edit plus the frontend's branch, not a new card tag.
 
@@ -41,4 +41,4 @@ A future web tool that wants this card declares `presentResult` returning a `car
 ## Related
 
 - [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary this extends with the `web` arm.
-- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent that carried the bash `terminal` render intent to the browser; the web frontend consumer of this arm is its analogue, deferred to a later PR.
+- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent that carried the bash `terminal` render intent to the browser; the [web result card frontend](2026-07-30-web-result-card-frontend.md) is its analogue for this arm.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index 36ab372864..a2e0096599 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 ## Consequences
 
-前端消费方由后续独立 PR 交付：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
+前端消费方归 [Web result card 前端 note](2026-07-30-web-result-card-frontend.md) 所有：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
 
 未来想用此卡片的 web 工具，声明一个返回带自有 `kind` 的 `card: 'web'` 视图的 `presentResult`；新增第三个 `kind` 是一次联合类型编辑加前端的分岔，而非一个新的 card 标签。
 
@@ -41,4 +41,4 @@ Status: implemented
 ## Related
 
 - [标签化的工具调用渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md) —— 本卡片以 `web` 分支扩展的 `card` 标签词汇表。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；本分支的 web 前端消费者是它的对应物，推迟到后续 PR。
+- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；[Web result card 前端](2026-07-30-web-result-card-frontend.md)是它在本分支上的对应物。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 461492312b..79bb4d0fb4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.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 .agents/notes/implemented/feature/2026-07-30-web-search-card.md
-2026-07-30-web-search-card.md: e0be857df69dfd46b6e936c775c6bae1476c26dc
-2026-07-30-web-search-card.zh.md: 784afb0dd36f20c3a0e203d5595c46c8040d82ff
+2026-07-30-web-search-card.md: 23c89585770151551526223454e98d18716d1a44
+2026-07-30-web-search-card.zh.md: f92bd9f9231d947d4c70e283b462294c030e3f33
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
index e0be857df6..23c8958577 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-web-search-card.zh.md)
 
 The `grep` and `glob` tools declare a result-time `card: 'search'` render intent ([search render card](2026-07-30-search-render-card.md)): a `SearchMatchesResultView` (`shape: 'matches'`) carrying grep's matches grouped by file, or a `SearchPathsResultView` (`shape: 'paths'`) carrying glob's flat path list, both with a `truncated`/`total` capping signal. That view already reaches the browser — host, connection, and runtime deliver it onto `ConversationSnapshot` as `resultView` — but the Web client ignored it: every non-terminal, non-diff tool result fell through to the generic card, which renders the model-facing text. A web frontend that wants an expandable per-file group of matches, or a scannable path list, had only the pre-formatted text.
 
-This is the follow-up the search render card note names: that PR was the backend contract and its two producers; this PR is the web consumer.
+This is the follow-up the search render card note names: that note owns the backend contract and its two producers; this note owns the web consumer.
 
 ## Decision
 
@@ -34,7 +34,7 @@ Geometry, radius, and fonts mirror `CodeBlock` and `TerminalBlock`, so a search
 
 Three sites consume the derivation, mirroring the terminal card's placement exactly:
 
-- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `tool.call.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
+- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `tool.call.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the terminal/diff cards; the [unified expand-and-inspect note](2026-07-30-web-tool-row-unified-expand-and-inspect.md) owns the whole-row collapse/expand interaction that flipped all resident cards at once.)
 - **The generic fallback** (`chat/GenericToolCard` → `chat/ToolRow`) threads the derived model as an expand-gated body, the same arm `terminal` uses: a `grep`/`glob` result with no keyed row (none in the shipped app, since both are registered) still renders its card, with the recovery footer, behind the row's expand toggle.
 - **The details panel** (`skeleton/DetailsPanel`) renders the card at the primitive's own full height in the Output section, with the recovery footer below it, keeping the JSON Input section.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index 784afb0dd3..f92bd9f923 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `grep` 与 `glob` 工具声明了一个仅在结果阶段存在的 `card: 'search'` render intent（[search render card](2026-07-30-search-render-card.md)）：`SearchMatchesResultView`（`shape: 'matches'`）携带 grep 按文件分组的匹配，或 `SearchPathsResultView`（`shape: 'paths'`）携带 glob 的扁平路径列表，两者都带 `truncated`/`total` 截断信号。该视图已经到达浏览器 —— host、connection、runtime 把它作为 `resultView` 投递到 `ConversationSnapshot` 上 —— 但 Web 客户端忽略了它：每个非终端、非 diff 的工具结果都落到 generic 卡片，渲染面向模型的文本。想把搜索结果渲染成可展开的按文件匹配分组、或可扫读的路径列表的 web 前端，只有那段预格式化文本。
 
-这正是 search render card note 指名的后续：那个 PR 是后端约定和它的两个生产者，本 PR 是 web 消费者。
+这正是 search render card note 指名的后续：后端约定和它的两个生产者归那篇 note 所有，web 消费方归本 note 所有。
 
 ## Decision
 
@@ -34,7 +34,7 @@ Status: implemented
 
 三个渲染点消费该推导，与终端卡片的落位完全一致：
 
-- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `tool.call.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
+- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `tool.call.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与 terminal/diff 卡片一致；一次性翻转了所有常驻卡片的整行折叠/展开交互归[统一展开与检视 note](2026-07-30-web-tool-row-unified-expand-and-inspect.md)所有。）
 - **generic fallback**（`chat/GenericToolCard` → `chat/ToolRow`）把推导出的 model 作为展开门控的 body 传入，与 `terminal` 用的是同一分支：没有 keyed 行的 `grep`/`glob` 结果（发布应用里没有，因为两者都注册了）仍在行的展开开关后渲染其卡片，并带恢复脚注。
 - **details panel**（`skeleton/DetailsPanel`）在 Output 段以 primitive 自身的完整高度渲染卡片，恢复脚注画在其下方，保留 JSON Input 段。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index 2c8ee18abb..69c4251608 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
-2026-07-31-code-mode-language-dispatch.md: 3a6e248160f165d6b341a5c8719abffd69a43820
-2026-07-31-code-mode-language-dispatch.zh.md: 46ef842f4b4209787c831b657159a97604324a66
+2026-07-31-code-mode-language-dispatch.md: 9e834ff2eb8e5f8326ef6d7f862385cadede6149
+2026-07-31-code-mode-language-dispatch.zh.md: d7d83146a7a5a9ed7fa4b051822e51b974e43b4e
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
index 3a6e248160..9e834ff2eb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
@@ -19,7 +19,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at
 
 Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
 
-`code-mode.ts` depends only on the runtime Service Definition (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the service's `language` field, which is already on master.
+`code-mode.ts` depends only on the runtime Service Definition (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer is therefore independent of the Python protocol and backend — it needs only the service's `language` field.
 
 ### The Python SDK renderer
 
@@ -37,9 +37,9 @@ The standard that cap serves is grammatical validity, and the boundary is delibe
 
 ## Consequences
 
-Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the Consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the Service Definition package must not import its Consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the Service Definition would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
+Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: at the Consumer's integration point rather than where the drift was introduced — and never while no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as they stood at the time and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the Service Definition package must not import its Consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the Service Definition would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it ships and is testable ahead of the Python protocol and backend.
 
-The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
+The cost is that the Python branch of both tables is unreachable in the shipped tree: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this change's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the change that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
 
 Two runtime contracts the Python SDK text asserts are owed by that same backend PR. First, the instructions tell the model that exactly `tools` and `ToolCallError` are bound and that the declared `TypedDict` classes are not, so the backend must inject those two names — with `ToolCallError.toolName` populated per the seam's `errorClass` contract — and must NOT bind the declared class names into the program's globals; injecting them "helpfully" would make the SDK text false. Second, the language has to be bound to the request: `requireCodeRuntime` resolves `ctx.codeRuntime` separately at assembly and at `run_code` execution, so a reload that swapped the runtime between those two points would hand a program written against one flavor to the other. The split is finer than those two points — `run_code`'s `description` and `parameters` getters each call `resolveFlavor(peekRuntime())`, and `schemaOf` destructures both, so one projection reads the runtime twice; both reads are for `run_code`'s own schema, since the getters are installed on that one definition and every other definition carries plain data properties. A reload between those two reads yields a single schema whose two halves name different languages. Neither is reachable here — one published backend means both reads return the same flavor and no program ever runs against this renderer's output — and the cross-language rejection is not testable until a second language exists.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index 46ef842f4b..d7d83146a7 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -19,7 +19,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
 
-`code-mode.ts` 只依赖运行时 Service Definition（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要服务的 `language` 字段，而该字段已在 master 上。
+`code-mode.ts` 只依赖运行时 Service Definition（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于 Python 协议和后端——它只需要服务的 `language` 字段。
 
 ### Python SDK 渲染器
 
@@ -32,14 +32,14 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 ## Alternatives considered
 
 - **在 `ToolRegistry` 上加一个 `language` 配置字段。** 那样部署方就会有两处命名语言（所加载的运行时与 tools 配置）且可能相互矛盾；所加载的运行时是唯一真相来源，故注册表读取它而不复制它。
-- **把 Python 后端 import 进 `code-mode.ts` 来检测它。** 那会把工具层耦合到具体后端，并迫使协议/后端 PR 先落地。按 `language` 运行时分发使该层保持后端无关、可独立发布。
+- **把 Python 后端 import 进 `code-mode.ts` 来检测它。** 那会把工具层耦合到具体后端，并迫使协议/后端 PR（Pull Request）先落地。按 `language` 运行时分发使该层保持后端无关、可独立发布。
 - **为未知语言提供默认渲染器。** 静默回退会在比如 Ruby 运行时上发出 TypeScript SDK——模型会看到错误语言的指令。在装配处 fail loud 是本仓库对错误配置的立场。
 
 ## Consequences
 
-新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在 Consumer 的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：Service Definition 包不得 import 其 Consumer 的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 Service Definition 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
+新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：触发点在 Consumer 的集成处而非漂移引入处——而只要不存在第二个后端，就永远不会触发。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：Service Definition 包不得 import 其 Consumer 的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 Service Definition 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端交付并可测。
 
-代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
+代价是两张表的 Python 分支在已交付的代码树中不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本变更的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个变更，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
 Python SDK 文本断言的两条运行时约定同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 约定填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 2d393ff905..47e1e0144b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.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 .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
-2026-07-31-telemetry-anonymous-user-id.md: 3c8e3324cb418eac48cb5ae780c55bbcbaf3caa1
-2026-07-31-telemetry-anonymous-user-id.zh.md: 6ba1b7abe0f253fc91e7f8856d9dc9d1d961550b
+2026-07-31-telemetry-anonymous-user-id.md: f53fc9ce7eb3a5aefcb0be0a20c7403b5601e369
+2026-07-31-telemetry-anonymous-user-id.zh.md: 99b2dd88df94810ccfc85d099e74a6f0852153a7
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
index 3c8e3324cb..f53fc9ce7e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
@@ -10,7 +10,7 @@ Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-tel
 
 ## Decision
 
-The `session-telemetry-otel` package's own module `src/user-id.ts` owns the OTel feed's user identity: `getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. This identity belongs to the OTel feed alone; the dsh-sdk launcher telemetry keeps its own anonymous-id store (`telemetry.json`), and the two are not shared (the first cut unified both feeds through a shared util package; the user reconsidered and pulled it back — no shared package before a second real consumer exists, revisit when a feed-correlation need appears).
+The `session-telemetry-otel` package's own module `src/user-id.ts` owns the OTel feed's user identity: `getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. This identity belongs to the OTel feed alone; the dsh-sdk launcher telemetry keeps its own anonymous-id store (`telemetry.json`), and the two are not shared (the first cut unified both feeds through a shared util package — no shared package before a second real consumer exists, revisit when a feed-correlation need appears).
 
 | Ruling | Value | Rationale |
 |---|---|---|
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 6ba1b7abe0..99b2dd88df 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -10,7 +10,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 
 ## Decision
 
-`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流，用户复议后收回：在有第二个真实消费者之前不抽公共包，回流关联需求出现时再议）。
+`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流——在有第二个真实消费者之前不抽公共包，回流关联需求出现时再议）。
 
 | 裁定 | 取值 | 理由 |
 |---|---|---|
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index dc6aad3b11..cdf7fa71b1 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: fe71a2d8caa4dc9cc732a250d7e388d1a3b44182
-2026-07-31-web-workspace-file-links.zh.md: d2e49f4816a014dd5ec700b4d6f8fa0bede03e67
+2026-07-31-web-workspace-file-links.md: 977a24adf2f87db8a34027f36feccee44d231f9d
+2026-07-31-web-workspace-file-links.zh.md: c350fad4c74c3ed6121aa5cb1243b43140196c68
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index fe71a2d8ca..977a24adf2 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -20,7 +20,7 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 **Opening stays the Host's job, and prefers the default browser.** `host.openPath` hands the path to the operating system, which yields a `file://` document in a real browser: full page capabilities, and no reachability into `/api`, because a `file://` document is not same-origin with it. Measured on the reported artifact: `localStorage` works, the theme toggle flips, the tabs switch, and `fetch` to the API fails. For documents a browser renders — `.html`, `.htm`, `.xhtml`, `.svg` — the opener resolves the default *browser* rather than the type's default application when the platform can name one, because a developer who binds `.html` to an editor would otherwise click a produced page and get source code. macOS reads the LaunchServices `https` handler and desktop Linux reads `$BROWSER`; either falls back to the default application when no browser can be named. Windows uses its registered association, and WSL first translates the path before using that same Windows handoff.
 
-**Serving workspace files over HTTP is out of scope, and so are non-local clients.** An earlier revision served files from the harness itself — first same-origin with `/api`, then behind `CSP: sandbox`, then from a second listener whose own port gave served documents their own origin. Each step answered a real problem, and the whole line was retired once the product scope was settled: previews for a browser that is not on the Host machine are not supported. With that decided, the Host opener answers the supported case completely and the HTTP machinery answered only the unsupported one.
+**Serving workspace files over HTTP is out of scope, and so are non-local clients.** Serving files from the harness itself — same-origin with `/api`, behind `CSP: sandbox`, or from a second listener whose own port gives served documents their own origin — was rejected with the product scope: previews for a browser that is not on the Host machine are not supported, so the Host opener answers the supported case completely and the HTTP machinery would answer only the unsupported one.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index d2e49f4816..c350fad4c7 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 **打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。
 
-**以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 更早的一版由 harness 自己提供文件——先是与 `/api` 同源，随后加上 `CSP: sandbox`，再后来交给一个以自身端口给所服务文档独立源的第二监听器。每一步都在回答一个真实问题，而整条线在产品范围定下之后被整体退役：不为“浏览器不在 Host 机器上”的场景提供预览。这一点定下之后，Host 打开器完整回答了受支持的场景，而那套 HTTP 机制回答的只是不受支持的那个。
+**以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 由 harness 自己提供文件——与 `/api` 同源、置于 `CSP: sandbox` 之后、或交给一个以自身端口给所服务文档独立源的第二监听器——随产品范围一并否决：不为“浏览器不在 Host 机器上”的场景提供预览，因此 Host 打开器完整回答受支持的场景，而那套 HTTP 机制只会回答不受支持的那个。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index 602d272b0b..be7a6a1962 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.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 .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
-2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
-2026-08-02-pwsh-tool-bash-parity.zh.md: c6e1d69bd061f0794b125e225d8f976bd82224e7
+2026-08-02-pwsh-tool-bash-parity.md: d61dd6f21223121973520014c44e2e5846e7387a
+2026-08-02-pwsh-tool-bash-parity.zh.md: 120f66b1d9c713d5e3b71575186fc2194b0718a5
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
index e35a903892..d61dd6f212 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-02-pwsh-tool-bash-parity.zh.md)
 
 ## Problem
 
-The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately minimal profile — foreground only (a fresh process per call; no persistent PTY session), no managed-environment parity beyond three hardcoded `DSH_*` keys, and a marker story ("always `[exit code: N]`") that diverged from the bash tool's rendering without being declared. Review of that change found the model-visible contract drifting from the implementation: the description promised spill-path reporting the renderer never performed, the README claimed exports that did not exist and rendering the tool did not do, and the tool's own tests pinned the lossy behavior. The minimal profile also left the `DSH_*` contributor seam duplicated-by-absence: plugins contributing environment facts to `ctx.bashEnv` had no effect on pwsh calls.
+The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately minimal profile — foreground only (a fresh process per call; no persistent PTY session), no managed-environment parity beyond three hardcoded `DSH_*` keys, and a marker story ("always `[exit code: N]`") that diverged from the bash tool's rendering without being declared. The model-visible contract drifted from the implementation: the description promised spill-path reporting the renderer never performed, the README claimed exports that did not exist and rendering the tool did not do, and the tool's own tests pinned the lossy behavior. The minimal profile also left the `DSH_*` contributor seam duplicated-by-absence: plugins contributing environment facts to `ctx.bashEnv` had no effect on pwsh calls.
 
 ## Decision
 
@@ -20,7 +20,7 @@ The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately mi
 
 ## Alternatives considered
 
-**Keep the minimal profile and fix only the claims.** Rejected: the review's core finding was that text contracts copied from bash drift without the corresponding implementation; a minimal tool plus accurate claims still leaves pwsh calls without background execution, without contributor parity, and with a divergent marker story that must be re-justified forever.
+**Keep the minimal profile and fix only the claims.** Rejected: text contracts copied from bash drift without the corresponding implementation; a minimal tool plus accurate claims still leaves pwsh calls without background execution, without contributor parity, and with a divergent marker story that must be re-justified forever.
 
 **Reject a mismatched executor dialect at load.** Attempted and reverted before merge: a `ShellDialect` marker (`bash` | `powershell`) on `BashExecutor`, with both shell tools throwing when the mounted executor speaks another shell. It forced every executor implementation — including each test and example fake — to declare a dialect, adding noise to every shell-tool test for a guard with no in-repo or plausible deployment to catch (shipped compositions always pair tool-pwsh with `dsh-pwsh-local` and tool-bash with `dsh-bash-local`). The pairing contract stays documented in each tool's README instead.
 
@@ -28,7 +28,7 @@ The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately mi
 
 ## Consequences
 
-- The bash and pwsh tools are now behaviorally interchangeable for foreground and background shell work (minus sandbox), and the pwsh prompt/description sentences are each backed by the renderer — the reviewer's grep-against-code check passes.
+- The bash and pwsh tools are now behaviorally interchangeable for foreground and background shell work (minus sandbox), and the pwsh prompt/description sentences are each backed by the renderer.
 - Parity ran BOTH ways once: the pwsh tool's structured foreground abort (`HarnessError('tool call aborted', TOOL_ABORTED)` with name `AbortError`) was backported to the bash tool, replacing its uncoded `Error('command aborted')` — a model-visible/logged change pinned by exact-shape tests on both sides and by the cancel-tool-calls fixture.
 - `@deepseek-ai/dsh-bash-env` is a new shipped package; `dsh-tool-bash`'s `dshHome` config moved there, so compositions mounting the shell tools must also mount `bash-env` (the spine bundles do).
 - Windows-only semantics (CRLF normalization, forced-termination exit-1/signal-null, POSIX-only self-signal) remain pinned by tests as before.
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index c6e1d69bd0..120f66b1d9 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见约定与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
+首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。模型可见约定曾与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
 
 ## 决策
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 备选方案
 
-**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本约定在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
+**保留最小画像，只修声明。** 否决：从 bash 复制的文本约定在缺少对应实现时会漂移；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
 
 **在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对约定改由各工具 README 记录。
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 后果
 
-- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书——reviewer 的“拿代码 grep 对证”检查通过。
+- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书。
 - 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture 钉住。
 - `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（spine bundle 已如此）。
 - Windows 专属语义（CRLF 归一化、强制终止 exit-1/signal-null、仅 POSIX 的自信号）一如既往由测试钉住。
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
index 97a03bb17b..5b9ac0a958 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.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 .agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
-2026-08-02-win32-in-process-folder-dialog.md: 5389293605169ce5ca269a127de5f609b8b7dd11
-2026-08-02-win32-in-process-folder-dialog.zh.md: db4a6503f37f4b9cc95ce79ab8f476aeedfe5a60
+2026-08-02-win32-in-process-folder-dialog.md: ef9232051d0ff6e3e752f08a68e9f04ce3c32ad6
+2026-08-02-win32-in-process-folder-dialog.zh.md: 8fc1114aa93e563c91185396b8dcc4d344064555
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
index 5389293605..ef9232051d 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-02-win32-in-process-folder-dialog.zh.md)
 
 ## Problem
 
-The Windows directory picker's primary tier was a spawned PowerShell script around WinForms `FolderBrowserDialog`: the modern dialog only where PowerShell 7 happens to be installed, a review-flagged regression where PowerShell 6 resolves but has no WinForms (exit 1 is not `ENOENT`, so the 5.1 fallback never ran), a `SetProcessDPIAware` ceiling of system DPI, and a picker whose behavior depended on which shells a machine ships rather than on Windows itself.
+The Windows directory picker's primary tier was a spawned PowerShell script around WinForms `FolderBrowserDialog`: the modern dialog only where PowerShell 7 happens to be installed, a regression where PowerShell 6 resolves but has no WinForms (exit 1 is not `ENOENT`, so the 5.1 fallback never ran), a `SetProcessDPIAware` ceiling of system DPI, and a picker whose behavior depended on which shells a machine ships rather than on Windows itself.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
index db4a6503f3..8fc1114aa9 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` spawn 出的 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
+Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` spawn 出的 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；一处回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 35628efcfe..49a14093ef 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.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 .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
-2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
-2026-08-03-web-search-source-scroll.zh.md: 7d644b9e3950906b97d382e997eb3b204a577326
+2026-08-03-web-search-source-scroll.md: f6b118b91d3d2102e11fa7b6d068621e961a7674
+2026-08-03-web-search-source-scroll.zh.md: 58eae594bd18c58f7fb80322f6902abdbba49ba7
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
index 3215302b2f..f6b118b91d 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
@@ -24,7 +24,7 @@ Making the list a scroll container also makes its `padding-left` a correctness c
 
 ## Alternatives considered
 
-**Raise `searchMaxResults` (or make it unbounded) so more sources reach both the model and the card.** Rejected by the user: it changes model-side behavior (more sources into every request's context, more tokens) and widens the gap between what the model reads and what the card draws. The instruction was explicit — keep the cap and the truncation, add a scrollbar.
+**Raise `searchMaxResults` (or make it unbounded) so more sources reach both the model and the card.** Rejected by the user: it changes model-side behavior (more sources into every request's context, more tokens) and widens the gap between what the model reads and what the card draws.
 
 **Keep the head/tail collapse and add scroll only to the expanded region.** Rejected: two overlapping mechanisms for one concern. Once the whole list is always rendered, the collapse arithmetic, the expand/collapse state, and the button are dead weight; scroll alone bounds the height.
 
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index 7d644b9e39..58eae594bd 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。指令很明确——保留上限与截断，加一个滚动条。
+**提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。
 
 **保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是累赘；仅靠滚动即可约束高度。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
index 17d590a110..4dc6bf8986 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.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 .agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
-2026-08-04-web-composer-shared-width-axis.md: 96cddda25bf79e9f2df7a0298039c27f316befca
-2026-08-04-web-composer-shared-width-axis.zh.md: b5a455f9e8c561ae89faa9baf526fdbb263bc89a
+2026-08-04-web-composer-shared-width-axis.md: f667363fb26297046b373779e1755928d328ec96
+2026-08-04-web-composer-shared-width-axis.zh.md: 94db330b34ff719eafa9e0018f2f06099c24030c
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
index 96cddda25b..f667363fb2 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
@@ -28,4 +28,4 @@ Overlay menus anchored to the card (slash menu, command popupSelect) clamp to th
 
 ## Consequences
 
-Changing the column width is now a one-line edit with the ratio relations preserved by construction, which the 736 → 748 retune during review already exercised. The cost is indirection: the widths of five surfaces are no longer readable off their own stylesheets and require following the variable chain to ConversationRoot. The container-query collapse adds the constraint that InputBar's row stays a size container; removing that declaration silently disables the permission trigger's adaptive behavior. The anonymous query also means any future second container between the row and the trigger would capture it — if that happens, the query must move or the intermediate container must be avoided.
+Changing the column width is now a one-line edit with the ratio relations preserved by construction, which the 736 → 748 retune already exercised. The cost is indirection: the widths of five surfaces are no longer readable off their own stylesheets and require following the variable chain to ConversationRoot. The container-query collapse adds the constraint that InputBar's row stays a size container; removing that declaration silently disables the permission trigger's adaptive behavior. The anonymous query also means any future second container between the row and the trigger would capture it — if that happens, the query must move or the intermediate container must be avoided.
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
index b5a455f9e8..94db330b34 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
@@ -28,4 +28,4 @@ Web 会话列的各个界面各自独立设定尺寸：transcript（文本记录
 
 ## 后果
 
-修改列宽现在是一行编辑，比例关系由构造保证——评审期间 736 → 748 的重调已经验证了这一点。代价是间接性：五个界面的宽度不再能从各自的样式表直接读出，需要沿变量链追到 ConversationRoot。容器查询收起增加了一个约束：InputBar 的行必须保持为尺寸容器；删掉那条声明会静默禁用权限触发器的自适应行为。匿名查询也意味着未来若在行与触发器之间出现第二个容器，它会截获该查询——届时查询必须迁移，或避免中间容器。
+修改列宽现在是一行编辑，比例关系由构造保证——736 → 748 的重调已经验证了这一点。代价是间接性：五个界面的宽度不再能从各自的样式表直接读出，需要沿变量链追到 ConversationRoot。容器查询收起增加了一个约束：InputBar 的行必须保持为尺寸容器；删掉那条声明会静默禁用权限触发器的自适应行为。匿名查询也意味着未来若在行与触发器之间出现第二个容器，它会截获该查询——届时查询必须迁移，或避免中间容器。
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 98861322f3..9ab9e55766 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 573be191cd228f8ca41641c4298b2987781b3435
-2026-08-05-context-form-vocabulary.zh.md: 2c7a2124f3528a6b660f6f26253bf76a53ab7b8e
+2026-08-05-context-form-vocabulary.md: 037d96ed4d9d316e62f9b9eb6909834a631c115a
+2026-08-05-context-form-vocabulary.zh.md: 693b19381bff2e2b85b0390c18354526ac421919
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 573be191cd..037d96ed4d 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -19,7 +19,7 @@ The tool surface already solved this shape. `ToolCallView` has three cards, not
 - `kind` answers **who produced this** and carries no presentation choice.
 - `form` answers **what shape of information it is**. Several producers may share one form, and one producer may emit more than one over a session.
 
-The vocabulary is semantic, never visual. A value states that the content is a file's instructions or a catalog of available items; colors, icons, ordering, and collapse defaults are the consumer's business and must not enter the union. It grows one value at a time, as producers gain the structured fields their form needs. This release declares two:
+The vocabulary is semantic, never visual. A value states that the content is a file's instructions or a catalog of available items; colors, icons, ordering, and collapse defaults are the consumer's business and must not enter the union. It grows one value at a time, as producers gain the structured fields their form needs. The declared forms:
 
 **`instructions`** — instructions read out of workspace files. `workspace-context` declares it on both the startup baseline and later deltas; its existing `changes[]` already carried the paths, actions, and digests the presentation needs, so no field was added. The body lists the reconciled files above the text, and keeps the `<system-reminder>` framing verbatim: the framing is part of what the model read, so hiding it would misreport the request.
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 2c7a2124f3..693b19381b 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - `kind` 回答**由谁产生**，不携带呈现选择。
 - `form` 回答**这是何种形态的信息**。多个生产方可以共用一种形态，一个生产方在一次会话中也可以发出多种。
 
-该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。当前词汇表声明六种形态：
+该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。已声明的形态：
 
 **`instructions`**——从工作区文件中读出的指令。`workspace-context` 在启动基线与后续增量上都声明它；其既有的 `changes[]` 已经携带了呈现所需的路径、动作与 digest，因此没有新增字段。内容区在正文之上列出对账过的文件，并原样保留 `<system-reminder>` 包装：那层包装本就是模型读到的一部分，隐藏它会歪曲这次请求。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 21dc393ff4..6f924866eb 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.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 .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
-2026-08-05-pwsh-ui-bash-parity.md: 95e884e9b67f3fb3927cd5154883ab08b3e7b3bb
-2026-08-05-pwsh-ui-bash-parity.zh.md: 937e6cefd3ac74f8e2fe797cdc4480b2b78fc3cb
+2026-08-05-pwsh-ui-bash-parity.md: ba92f482e957acd00792a2a8053716047a4da27d
+2026-08-05-pwsh-ui-bash-parity.zh.md: 693b3fc26e632718ea2135282d63daa32e63e1c5
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
index 95e884e9b6..ba92f482e9 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
@@ -22,7 +22,7 @@ The Web UI needs no per-tool code for the card itself: the client's terminal-car
 
 **A new dedicated presentation package (e.g. `@deepseek-ai/dsh-shell-present`).** Rejected: a new package costs manifests, module-graph/catalog regeneration, and README surface for a single pure function; `@deepseek-ai/dsh-bash` is already in both tools' closures and already owns the `BashRunResult` facts the parse reconstructs.
 
-**Duplicate the parse into `tool-pwsh`'s render module (a third twin).** Rejected: the parity review's core finding was that copied text contracts drift without a shared implementation; the parse and the marker emission must co-evolve in one place, and the parse is exactly the contract the UI pill depends on.
+**Duplicate the parse into `tool-pwsh`'s render module (a third twin).** Rejected: copied text contracts drift without a shared implementation ([pwsh tool bash parity](2026-08-02-pwsh-tool-bash-parity.md)); the parse and the marker emission must co-evolve in one place, and the parse is exactly the contract the UI pill depends on.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 937e6cefd3..693b3fc26e 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -22,7 +22,7 @@ Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 ter
 
 **新建专用呈现包（如 `@deepseek-ai/dsh-shell-present`）。** 否决：为一个纯函数新建包要付出 manifest、module-graph/目录再生成与 README 面的成本；`@deepseek-ai/dsh-bash` 已在两个工具的闭包中，且已拥有该解析重建的 `BashRunResult` 事实。
 
-**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本约定缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
+**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：复制的文本约定缺少共享实现就会漂移（[pwsh 工具与 bash 对齐](2026-08-02-pwsh-tool-bash-parity.md)）；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index 4b85d13e3d..39d3a0acf5 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.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 .agents/notes/implemented/process/2026-06-17-ts-build-config.md
-2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
-2026-06-17-ts-build-config.zh.md: 80b051cd5fb76672d4c056d1b6321029897225e8
+2026-06-17-ts-build-config.md: a44e86844113250c8b99575102d7ea2e611e97ed
+2026-06-17-ts-build-config.zh.md: 4e98717fd843c93696402b71e8a41163c70e7283
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
index f25731921a..a44e868441 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
@@ -13,13 +13,13 @@ The current TypeScript build and typecheck setup had these issues:
 - `build` used `tsc` to transform `.ts` to `.d.ts` files for packages under `packages/<group>/<pkg>` and `vendor/*`, and then used `tsdown` to transform `.ts` to bundled `.js` files. This made two tools do TypeScript transform.
 - `typecheck` tended to validate packages, vendor source, examples, tests, and scripts through one root typecheck config.
 
-The goal is to make build and typecheck use matching tsconfig boundaries and TypeScript resolution/transform behavior. Build should generate `.js`, `.d.ts`, `.js.map`, and `.d.ts.map` through one compiler and config, so publish output and type validation stay consistent.
+Build and typecheck use matching tsconfig boundaries and TypeScript resolution/transform behavior. Build generates `.js`, `.d.ts`, `.js.map`, and `.d.ts.map` through one compiler and config, so publish output and type validation stay consistent.
 
-Validation found several concrete technical issues and possible routes:
+Concrete constraints:
 
 - `tsdown` uses `oxc` to transform TypeScript, which is not the same behavior as `tsc`.
     - Bundled `.d.ts` emitted by `tsdown` conflicts with Cordis' internal relative module augmentation shape.
-    - The tsc output is affected by `allowImportingTsExtensions`, so we need to ensure that generated `.js` files do not import `.ts` files and generated `.d.ts` files keep explicit relative specifiers that NodeNext/Node16 accepts. Therefore, in-package relative imports use explicit `.ts` specifiers in TypeScript source and `rewriteRelativeImportExtensions` rewrites those specifiers to `.js` in emitted JS.
+    - The tsc output is affected by `allowImportingTsExtensions`: generated `.js` files must not import `.ts` files, and generated `.d.ts` files must keep explicit relative specifiers that NodeNext/Node16 accepts. Therefore, in-package relative imports use explicit `.ts` specifiers in TypeScript source and `rewriteRelativeImportExtensions` rewrites those specifiers to `.js` in emitted JS.
     - Bundled `.js` emitted by `tsdown` is not the same behavior as per-file `.js` emitted by `tsc -b`, such as decorator transform behavior.
 - `vendor/*/src`, examples, tests, and scripts cannot all be plain-included in one root strict program.
     - Directly typechecking `vendor/*/src` under the root strict config triggers many type errors outside this project's ownership.
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 80b051cd5f..4e98717fd8 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -13,13 +13,13 @@ Status: implemented
 - `build` 使用 `tsc` 将 `packages/<group>/<pkg>` 和 `vendor/*` 下的 `.ts` 转换为 `.d.ts` 文件，然后使用 `tsdown` 将 `.ts` 转换为打包后的 `.js` 文件。这导致两个工具各自执行 TypeScript 转换。
 - `typecheck` 倾向于通过一个根目录的类型检查配置来校验包（package）、vendor 源码、示例、测试和脚本。
 
-目标是让构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建应通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
+构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
 
-验证过程中发现了若干具体的技术问题和可能的路径：
+具体约束：
 
 - `tsdown` 使用 `oxc` 进行 TypeScript 转换，其行为与 `tsc` 不同。
     - `tsdown` 输出的打包 `.d.ts` 与 Cordis 内部的相对模块增强（module augmentation）结构冲突。
-    - tsc 的输出受 `allowImportingTsExtensions` 影响，因此需要确保生成的 `.js` 文件不会导入 `.ts` 文件，且生成的 `.d.ts` 文件保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
+    - tsc 的输出受 `allowImportingTsExtensions` 影响：生成的 `.js` 文件不得导入 `.ts` 文件，且生成的 `.d.ts` 文件必须保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
     - `tsdown` 输出的打包 `.js` 与 `tsc -b` 逐文件输出的 `.js` 行为不同，例如装饰器转换行为。
 - `vendor/*/src`、示例、测试和脚本无法全部以 plain-include 方式纳入一个根目录的严格程序。
     - 在根目录严格配置下直接对 `vendor/*/src` 做类型检查，会触发大量不属于本项目所有权范围的类型错误。
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
index e5112c08e1..af8d4d77db 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.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 .agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
-2026-06-18-markdown-cross-link-lint.md: 21c6884d3fd891794a11125a9aa51ac2bcb29059
-2026-06-18-markdown-cross-link-lint.zh.md: 444cf6eb97d95049d4e6b7bb5f44138051f6577a
+2026-06-18-markdown-cross-link-lint.md: 37e0a41c08e068d6b3128300f078c8e417f1f337
+2026-06-18-markdown-cross-link-lint.zh.md: 457cc8b71ac91e5b5b9ae7ad8fb3b99dfd8ce0c7
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
index 21c6884d3f..37e0a41c08 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
@@ -28,6 +28,6 @@ The gate now also checks `#fragment` anchors on Markdown targets — same-file a
 
 ## Consequences
 
-- Renames and moves that orphan a cross-link fail `doc-sync` and CI instead of waiting for a reader to click a dead link. This made the Agent Note reorganization that introduced the gate self-verifying: the same PR that rewrote forty links also added the check that proves none dangle.
+- Renames and moves that orphan a cross-link fail `doc-sync` and CI instead of waiting for a reader to click a dead link. This made the Agent Note reorganization that introduced the gate self-verifying: the check proves none of its own rewritten links dangle.
 - One more fast tsx script in the `doc-sync` chain; no new dependency (the mdast/GFM stack is already in devDependencies for `verify-md-wrap`).
 - The convention this enforces — cross-reference docs by machine-checkable relative link, never by bare prose or a number — is documented in [docs/AGENTS.md](../../../../docs/AGENTS.md) so authors know the gate exists and why.
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
index 444cf6eb97..457cc8b71a 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
@@ -28,6 +28,6 @@ Status: implemented
 
 ## 后果
 
-- 造成交叉链接失效的重命名与移动会直接使 `doc-sync` 和 CI 失败，而不是等读者点击死链才暴露。由此，引入该门禁的 Agent Note 重组具备自校验能力：同一个 PR（Pull Request）在改写 40 条链接的同时，也添加了证明这些链接均未悬空的检查。
+- 造成交叉链接失效的重命名与移动会直接使 `doc-sync` 和 CI 失败，而不是等读者点击死链才暴露。由此，引入该门禁的 Agent Note 重组具备自校验能力：该检查证明其自身改写的链接均未悬空。
 - `doc-sync` 链中多了一个快速 tsx 脚本；无新增依赖（mdast/GFM 技术栈已作为 `verify-md-wrap` 的 devDependencies 存在）。
 - 该门禁强制执行的约定是：文档交叉引用必须使用可机械检查的相对链接，绝不能只写纯文本或编号。[docs/AGENTS.md](../../../../docs/AGENTS.md)记录了这项约定，使作者了解该门禁及其理由。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 20bd2a96db..93d6ea6c49 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 2f2e1fe43e29c972577f6b31fcd2f8249229779f
-2026-06-20-core-data-structures-catalog.zh.md: e2653a8248f6be24699dc55196e64231280cb7f9
+2026-06-20-core-data-structures-catalog.md: 957d3a31cf690b3f0fb821b69bbc3d6d5005b1d7
+2026-06-20-core-data-structures-catalog.zh.md: aec1489695f8400768c958426a9d6a8d4061db0c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 2f2e1fe43e..957d3a31cf 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -18,7 +18,7 @@ A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type
 
 > **Superseded as the page-scoping rule** by [package-anchored subsystem pages](2026-08-03-package-anchored-subsystem-pages.md): each page now anchors to the package group that declares its vocabulary. The `ts type-equiv` mechanism below remains current.
 
-The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own subsystem page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
+The decisive test for the scoping line is `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own subsystem page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
 The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a subsystem-page detail.*** Worked through:
 
@@ -50,8 +50,6 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 ## Verification lesson
 
-The spine-vs-subsystem rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
-
 `verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-subsystem and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
 
 ## Consequences
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index e2653a8248..aec1489695 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 > **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
 
-范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入其自身的子系统页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+范围界定的决定性测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入其自身的子系统页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
 确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子系统页面细节。*** 逐一验证如下：
 
@@ -50,8 +50,6 @@ Status: implemented
 
 ## 验证教训
 
-主干与子系统规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
-
 `verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与子系统的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
 
 ## 后果
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 4fd3657a7d..a869a98b51 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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 .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
-2026-07-02-bilingual-docs-and-pairing-gate.md: 930efd3a2df8ad99b3c209c6084436ab6b27dc0a
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 2e288a29e9484683b9961d1e420a6e92ca05e5fe
+2026-07-02-bilingual-docs-and-pairing-gate.md: 9e6611aa8391e1478603bedb7d2b96fdd9a8bad2
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 654d265f3e8b396e23a49fd53e522826a7adb2ff
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index 930efd3a2d..9e6611aa83 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -23,7 +23,7 @@ The verification contract covers each boundary independently. `verify-translatio
 
 ## Alternatives considered
 
-- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.
+- **English as the canonical source with a fingerprint inside the translation** — `.zh.md` files would carry an HTML comment recording the English source's blob hash, and translation would flow EN → ZH only. Rejected: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.
 - **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.
 - **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.
 - **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 2e288a29e9..654d265f3e 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。
+- **英文为正典源、指纹放在译文内**：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。否决：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。
 - **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。
 - **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。
 - **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
index 7005f08ce0..095b577bba 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.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 .agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 006360cedfd4d1e2c2b67ede98062a375e316f47
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 2258a1fe5f91b27b8a3b636c7f3ad26f502a98df
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 79a7ff1c573019a3a1877eb49177d3410aea5ed7
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 76d755656ecfdd47bac2191efac4ce5bba53f4fb
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
index 006360cedf..79a7ff1c57 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
@@ -21,7 +21,7 @@ Outside `landlock-run.yml`, each workflow that installed pnpm hand-provisioned i
 - **Keep the hand-rolled steps.** They worked, but they were drifting copies of setup boilerplate, and the corepack dependency was a known future break.
 - **Convert the enterprise jobs' caching to `cache: pnpm`.** Rejected: the restore-only asymmetry is a documented latency decision in `ci.yml`'s comments; erasing it to unify tooling inverts the priority.
 - **Convert serial-linux's store cache.** Rejected during implementation: the original proposal counted serial-linux among the symmetric setups, but its cache step is the producer half of the enterprise jobs' restore-only pairing — moving it to `setup-node`'s key format is the enterprise conversion by another route.
-- **Stop at the cache-bearing workflows and leave the other `corepack enable` sites.** Rejected on review follow-up: provisioning and caching are separable concerns, and leaving corepack in the cache-less jobs kept the future break and two provisioning idioms for no benefit.
+- **Stop at the cache-bearing workflows and leave the other `corepack enable` sites.** Rejected: provisioning and caching are separable concerns, and leaving corepack in the cache-less jobs kept the future break and two provisioning idioms for no benefit.
 - **Rely on the runner image's Yarn.** Rejected: the hosted image exposes Yarn 1.22 after Corepack is removed, while the generated-project e2e requires Yarn 2 or newer. A locked root dev dependency makes that coverage independent of runner image contents.
 - **A composite action wrapping action-setup + setup-node.** Rejected for now: the remaining per-job variation (node-version matrices, per-platform conditional caching, the restore-only pairing) is deliberate policy, not boilerplate — a wrapper would grow mirroring inputs or flatten a real asymmetry, and the two-line pair is already near the floor.
 
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
index 2258a1fe5f..76d755656e 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 - **保留手写步骤。** 它们能用，但那是会各自漂移的设置样板副本，而且对 corepack 的依赖是已知的未来失效点。
 - **把企业作业的缓存也转换成 `cache: pnpm`。** 否决：只恢复不上传的不对称是 `ci.yml` 注释中有记录的延迟决策；为统一工具而抹掉它，属于颠倒优先级。
 - **转换 serial-linux 的 store 缓存。** 实现期间否决：原提案曾把 serial-linux 计入对称设置，但其缓存步骤是企业作业只恢复不上传配对中的生产者一端——把它改成 `setup-node` 的键格式，等于换条路径做了企业作业的转换。
-- **只转换带缓存的工作流，留下其余出现 `corepack enable` 的位置。** 评审跟进时否决：提供 pnpm 与缓存是可分离的关注点，在无缓存作业里留下 corepack 只会保留未来失效点和两套并存的提供方式，毫无收益。
+- **只转换带缓存的工作流，留下其余出现 `corepack enable` 的位置。** 否决：提供 pnpm 与缓存是可分离的关注点，在无缓存作业里留下 corepack 只会保留未来失效点和两套并存的提供方式，毫无收益。
 - **依赖 runner 镜像自带的 Yarn。** 否决：Corepack 移除后，托管镜像提供的是 Yarn 1.22，而 generated-project e2e 要求 Yarn 2 或更高版本。锁定版本的根开发依赖让该项覆盖率不再受 runner 镜像内容影响。
 - **用一个组合 action 包装 action-setup + setup-node。** 暂不采纳：剩余的按作业差异（node 版本矩阵、按平台的条件缓存、只恢复不上传配对）是刻意的政策而非样板——包装层要么不得不增加与这些差异一一对应的输入，要么抹平一处真实的不对称，而两行的组合已接近下限。
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index cd55f494d7..2575f2f4b3 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.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 .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
-2026-07-27-wine-windows-gates-experiment.zh.md: 3145a4aa6a06cacbab96dd37714617aeecdfdde0
+2026-07-27-wine-windows-gates-experiment.md: c2b5419c106e232520b9ad21339b0758da1b6694
+2026-07-27-wine-windows-gates-experiment.zh.md: 7ad19e49a43c07369eba6511fb7a46f5b3291df8
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
index 1b01fe00dc..c2b5419c10 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-27-wine-windows-gates-experiment.zh.md)
 
 The pull-request Windows lane exists to prove the two blocking win32 surfaces — the workspace build and the production site — and it ran on hosted `windows-2025`, the slowest job in the required matrix: 7–9 minutes against 1.5–2.5 for the Linux jobs, so the Windows VM's boot, setup, and filesystem costs dominated every pull request's critical path.
 
-The question the experiment answered: can a plain Linux runner produce an equivalent win32 signal for the blocking surfaces at Linux wall clock, so no Windows VM sits on the pull-request path at all?
+The experiment tested whether a plain Linux runner can produce an equivalent win32 signal for the blocking surfaces at Linux wall clock, so no Windows VM sits on the pull-request path at all.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
index 3145a4aa6a..7ad19e49a4 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 workspace 构建与生产站点。该通道此前运行在托管 `windows-2025` 上，是必需矩阵中最慢的作业：耗时 7–9 分钟，而 Linux 作业耗时 1.5–2.5 分钟，因此 Windows VM 的启动、准备与文件系统开销主导了每个 pull request 的关键路径。
 
-实验回答的问题是：一台普通 Linux runner 能否以 Linux 作业的墙钟时间为这些阻断表面产出等效的 win32 信号，让 pull request 路径上完全没有 Windows VM？
+实验测试了一台普通 Linux runner 能否以 Linux 作业的墙钟时间为这些阻断表面产出等效的 win32 信号，让 pull request 路径上完全没有 Windows VM。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 004c168fe7..b60f3ae3ed 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
-2026-07-30-generated-third-party-notices.md: f2591c8d0c7d4b83ecc96bf237ded667e322d55c
-2026-07-30-generated-third-party-notices.zh.md: 97b62223c0f1e5d179e58f27a01251d8af43357b
+2026-07-30-generated-third-party-notices.md: 58e3fd5007a16d6391956f423d1ec91e851df295
+2026-07-30-generated-third-party-notices.zh.md: 834ec4ebc349bdee37b0873109de566223bb7d48
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
index f2591c8d0c..58e3fd5007 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
@@ -16,7 +16,7 @@ A hand-written inventory answers none of those durably. Roughly a hundred rows o
 
 **Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, a workspace declaration, the root lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check.
 
-One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions was tried and does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case.
+One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case.
 
 The file discloses **direct** dependencies by default. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy. The one explicit transitive disclosure is the official Claude platform payload set declared by `@anthropic-ai/claude-agent-sdk` through `optionalDependencies`, because those packages carry the distributed Claude Code executable rather than ordinary library implementation detail.
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 97b62223c0..834ec4ebc3 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
-有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
+有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
 文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index a2e19d3493..72574c7cf5 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.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 .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
-2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
-2026-07-31-installer-adopts-existing-checkout.zh.md: e19baa0b1ee8ce71c1b8f3ee520322fb6557a720
+2026-07-31-installer-adopts-existing-checkout.md: 531b780974e1490b27d8b96734ccfadae66c2fc2
+2026-07-31-installer-adopts-existing-checkout.zh.md: 405b58d8d53b3f0895cc7746c957582455667cda
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
index 3a213a6232..531b780974 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
@@ -20,7 +20,7 @@ The installer records nothing about where that repository lives. A container who
 
 Adoption branches from `HEAD`, so committed work is what runs and uncommitted changes stay in the checkout. This is not prompted or warned about: the installer builds the layout and gets out of the way. Setting `DSH_SOURCE` to a different directory remains the one documented way to opt back into cloning a separate tree.
 
-Every path comparison runs on physical paths through a `resolve_dir` helper, and every compared value is resolved at assignment rather than at the comparison. Git always reports resolved paths, so comparing one against an unresolved path disagrees whenever a symlink sits anywhere above the checkout — a symlinked home directory is enough, and macOS reaches every `mktemp` path that way through `/var` -> `private/var`. The mismatch misclassified an existing managed install as a foreign clone and would have built a second container beside the real one. The same defect recurred twice more during review, both times as one side of a comparison left unresolved: a curl install's `REPO_ROOT`, and the container path it was compared against. `resolve_dir` therefore echoes a missing path back rather than failing, so a not-yet-created container needs no per-call fallback and no site can compare against an empty path by forgetting one; callers that need "does not exist" test the directory explicitly. `git rev-parse --path-format=absolute` would do the same job but requires git 2.31+.
+Every path comparison runs on physical paths through a `resolve_dir` helper, and every compared value is resolved at assignment rather than at the comparison. Git always reports resolved paths, so comparing one against an unresolved path disagrees whenever a symlink sits anywhere above the checkout — a symlinked home directory is enough, and macOS reaches every `mktemp` path that way through `/var` -> `private/var`. The mismatch misclassified an existing managed install as a foreign clone and would have built a second container beside the real one. The same defect class recurs whenever one side of a comparison is left unresolved — as it did with a curl install's `REPO_ROOT` and with the container path it was compared against. `resolve_dir` therefore echoes a missing path back rather than failing, so a not-yet-created container needs no per-call fallback and no site can compare against an empty path by forgetting one; callers that need "does not exist" test the directory explicitly. `git rev-parse --path-format=absolute` would do the same job but requires git 2.31+.
 
 Before `current` is repointed, the installer rejects a staging path that resolves to the repository itself, enforcing the upgrade contract that the launcher never resolves to the master clone.
 
@@ -48,4 +48,4 @@ A container adopting an outside clone is also no longer self-contained: deleting
 
 `scripts/install.sh` now has a real-shell PTY regression suite in `apps/cli/tests/install-script.spec.ts`, covering adoption and curl-style paths with stubbed dependencies. Curl-style installs default to the public `deepseek-ai/deepseek-harness-sdk` source, while replacing the installer with pnpm/npx remains separate work.
 
-Verification was manual, through a throwaway harness driving the real script with a stubbed `pnpm`: adopting a standalone clone; adopting from a linked worktree into its existing container; an explicit `DSH_SOURCE` still opting back into cloning; a dirty tree adopting silently with no prompt or warning while its uncommitted file stays behind; a non-git checkout failing with guidance; and a `curl`-style clone install asserting the built layout, which is the regression that caught the unresolved-`REPO_ROOT` defect. The interactive path was exercised under tmux from a dirty checkout, confirming the run reaches the launcher with no adoption prompt and ends with `dsh` running from the new staging worktree while the original checkout keeps its branch and its uncommitted file.
+Verification was manual, through a throwaway harness driving the real script with a stubbed `pnpm`: adopting a standalone clone; adopting from a linked worktree into its existing container; an explicit `DSH_SOURCE` still opting back into cloning; a dirty tree adopting silently with no prompt or warning while its uncommitted file stays behind; a non-git checkout failing with guidance; and a `curl`-style clone install asserting the built layout, the check that catches an unresolved `REPO_ROOT`. The interactive path was exercised under tmux from a dirty checkout, confirming the run reaches the launcher with no adoption prompt and ends with `dsh` running from the new staging worktree while the original checkout keeps its branch and its uncommitted file.
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index e19baa0b1e..405b58d8d5 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 接管以`HEAD`为分支起点，因此运行的是已提交的内容，未提交的更改仍留在检出中。这一点既不提示也不警告：安装器构建好布局后便不再打扰。把`DSH_SOURCE`设为其他目录，仍是唯一有文档记载的、回到克隆另一棵树的方式。
 
-所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
+所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。只要比较的一侧未经解析，同类缺陷就会重现——curl 安装的`REPO_ROOT`以及与之比较的容器路径都曾如此。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
 
 在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级约定。
 
@@ -48,4 +48,4 @@ Status: implemented
 
 `scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。curl 风格安装默认使用公开的 `deepseek-ai/deepseek-harness-sdk` 源，而以 pnpm/npx 替换安装器仍是另一项工作。
 
-验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
+验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——该检查能捕获未解析的`REPO_ROOT`。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
index f742579d36..c039f8c1b1 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.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 .agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
-2026-08-06-coverage-uncovered-locations.md: 27c466e7ae505a2d318f8b21d442c31619610f59
-2026-08-06-coverage-uncovered-locations.zh.md: 482b17227c4198ee27411da16b047288b331af9c
+2026-08-06-coverage-uncovered-locations.md: 7a4bd7317bf66d090d73a6a05f361ccc1582f1c4
+2026-08-06-coverage-uncovered-locations.zh.md: 7d820b3dcd46c844dfccc61dda283c754ed17f13
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
index 27c466e7ae..7a4bd7317b 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
@@ -33,7 +33,7 @@ CJS is a forced shape, and a justified exception to the ESM-everywhere disciplin
 
 ## Verification
 
-Local matrix: with a deliberately induced failure, all three record kinds appear and their locations match the planted gaps; a mixed run emits records only for the failing files (files at 100% within the same run stay silent); an all-green run produces zero output and exit code 0. CI evidence: after temporarily planting one unreachable statement/branch/function in `clampTimeout`, the coverage lane — under the isolated condition of all tests passing (632 files / 10326 cases) with only the threshold failing — printed the 4 records above the ERROR lines (evidence links in the PR #1716 description); the demonstration commit was removed from the branch before merge.
+Local matrix: with a deliberately induced failure, all three record kinds appear and their locations match the planted gaps; a mixed run emits records only for the failing files (files at 100% within the same run stay silent); an all-green run produces zero output and exit code 0. CI evidence: after temporarily planting one unreachable statement/branch/function in `clampTimeout`, the coverage lane — under the isolated condition of all tests passing (632 files / 10326 cases) with only the threshold failing — printed the 4 records above the ERROR lines; the planted failure is not in the committed tree.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
index 482b17227c..7d820b3dcd 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
@@ -33,7 +33,7 @@ CJS 是被迫的形态，也是 ESM-everywhere 纪律的一个有据例外：ist
 
 ## 验证
 
-本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合运行只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方（证据链接见 PR #1716 描述）；演示提交在合并前已从分支撤除。
+本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合运行只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方；埋入的失败并不在已提交的代码树中。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
new file mode 100644
index 0000000000..079b448027
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+2026-08-09-committed-artifact-citations.md: a34a779977a05b66b1587049ef4a38f0c1cfa0cb
+2026-08-09-committed-artifact-citations.zh.md: 6eb1810dddfcb38095270d4cdcb00eccef167183
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
new file mode 100644
index 0000000000..a34a779977
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -0,0 +1,37 @@
+# Agent Note: Cite committed artifacts, never design-session ordinals
+
+Status: implemented
+
+English | [中文](2026-08-09-committed-artifact-citations.zh.md)
+
+## Problem
+
+Large design and review sessions leave working shorthand — decision ordinals, audit item codes, plan section numbers, task and stack ordinals, reviewer rulings — that reads naturally while the session transcript is open and resolves to nothing after it closes. A repo-wide audit found the pattern concentrated in `packages/client`: bare `(decision 12/16/19/20/21)` citations of which only decision 21 had a committed owner, `(audit C2/S1/S3/S7)` codes with no audit document anywhere, `design §4.7` / `web2 §0` / `plan §1.4` references to uncommitted drafts, plan-phase labels (`T2/T5/T9`, `P-I`, `W5`), stack positions ("a later PR in this stack") in durable JSDoc, and "ruling" / "design ledger" vocabulary. The same families appeared in tests, CSS comments, generator templates, CI comments, and Agent Notes ("this PR/branch/review round" vantage, review-choreography attributions, stale "deferred to a later PR" claims whose targets had since shipped). The [documentation standard](../../../../docs/AGENTS.md) already banned the change-history half (previously/now, PR and commit references) but stated no counterpart rule for citations, so unresolvable ordinals kept landing.
+
+## Decision
+
+Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
+
+- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned per the documentation standard; issues are durable and citable.
+- A design-session ordinal with a committed owner is replaced by the owner's name — decision 21 lives in the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) as the plain-text-reference decision. An ordinal without an owner is deleted and its factual clause restated to stand alone.
+- Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
+- Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
+- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
+
+One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
+
+## Alternatives considered
+
+- **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d` and `\(audit [A-Z]\d`) is the candidate if the pattern recurs.
+- **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
+
+## Verification
+
+The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures and archived notes; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
+
+## Consequences
+
+- A comment's citations resolve by path or name; readers never reconstruct a closed session to follow one.
+- Design sessions must land their decisions in Agent Notes before durable prose can cite them; ordinal shorthand stays inside the session.
+- Citations get longer (a note path instead of "(decision 21)") in exchange for grep-free resolution.
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
new file mode 100644
index 0000000000..6eb1810ddd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 引用已提交的产物，绝不引用设计会话序号
+
+Status: implemented
+
+[English](2026-08-09-committed-artifact-citations.md) | 中文
+
+## 问题
+
+大型设计与评审会话会留下工作速记：决策序号、审计条目代号、计划章节编号、任务与栈序号、评审人裁定。这些速记在会话 transcript（文本记录）还开着时读起来顺理成章，一旦关闭就什么也解析不到。一次全仓库审计发现该模式集中在 `packages/client`：裸写的 `(decision 12/16/19/20/21)` 引用中只有决策 21 有已提交的归属文档；`(audit C2/S1/S3/S7)` 代号在任何地方都没有对应的审计文档；`design §4.7`／`web2 §0`／`plan §1.4` 指向未提交的草稿；计划阶段标签（`T2/T5/T9`、`P-I`、`W5`）；持久 JSDoc 里的栈内位置（"a later PR in this stack"）；以及「ruling」（裁定）、「design ledger」（设计台账）一类词汇。同样的几类模式也出现在测试、CSS 注释、生成器模板、CI 注释与 Agent Note 中（「本 PR／本分支／本评审轮」视角、评审编排式的归因、目标其后已经交付却仍写着「推迟到后续 PR」的陈旧说法）。[文档标准](../../../../docs/AGENTS.md)早已禁止了变更历史这一半（previously/now、PR（Pull Request）与 commit 引用），却没有为引用写下对应的规则，于是无法解析的序号不断落进仓库。
+
+## 决策
+
+持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
+
+- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准仍在禁止之列；issue 是持久且可引用的。
+- 有已提交归属文档的设计会话序号替换为该归属文档的名称：决策 21 即 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的纯文本引用决策。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
+- 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
+- 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
+
+一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
+
+## 曾考虑的替代方案
+
+- **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d` 与 `\(audit [A-Z]\d`）。
+- **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
+
+## 验证
+
+审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture 与已归档 Agent Note 之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
+
+## 后果
+
+- 注释中的引用凭路径或名称即可解析；读者永远不必为追溯一条引用而重建已关闭的会话。
+- 设计会话必须先把决策落进 Agent Note，持久行文才能引用这些决策；序号速记只留在会话内部。
+- 引用变长了（用一条 note 路径取代「(decision 21)」），换来的是无需 grep 即可解析。
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
index 2233dcadde..702f58d6c7 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.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 .agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
-2026-06-19-drop-mutable-session-summary.md: f87378a1c3737950eb536be8e3f6776586eb8a01
-2026-06-19-drop-mutable-session-summary.zh.md: f15dcc038154a9170ac41fd5733712164728f518
+2026-06-19-drop-mutable-session-summary.md: fdbfb1b4f7423fda152a5c63c02484ebe71e27dc
+2026-06-19-drop-mutable-session-summary.zh.md: 1b99c00f49b5149583b6f0b9387f580ee892d7a1
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
index f87378a1c3..fdbfb1b4f7 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
@@ -22,7 +22,7 @@ Delete the mutable session summary entirely. `SessionSummary` and the `SessionMe
 
 Anything the summary was meant to provide is **derivable from the append-only log** when a consumer actually needs it (`firstPrompt` = first `user/message`; recency = the last event's `time` or the file mtime) or already lives in the immutable header (`createdAt`, `cwd`). The one thing *not* derivable — a user-*edited* title — had no implementation and is pure YAGNI; it can return as its own log event or header field if a real feature ever needs it.
 
-This is recorded as a decision because it is **durable** (it narrows a public service contract and an on-disk format across two backends), **contested** (the summary was a deliberate forward-looking design, not an accident), and **surprising** (a future reader finding `SessionHeader` where the original Agent Note describes `SessionMeta` would otherwise ask why the summary vanished). It also unblocks the [shared persistence write coordinator](../architecture/2026-06-18-shared-persistence-write-coordinator.md): with no mutable summary, the coordinator's hook interface needs no `updateSummary` hook and the JSONL-sidecar-vs-SQLite-column durability divergence disappears, so the two backends' write paths converge.
+The removal narrows a public service contract and an on-disk format across two backends; the summary was a deliberate forward-looking design, not an accident; and `SessionHeader` now stands where the original Agent Note described `SessionMeta`, which is why the summary vanished. It also unblocks the [shared persistence write coordinator](../architecture/2026-06-18-shared-persistence-write-coordinator.md): with no mutable summary, the coordinator's hook interface needs no `updateSummary` hook and the JSONL-sidecar-vs-SQLite-column durability divergence disappears, so the two backends' write paths converge.
 
 ## No migration
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
index f15dcc0381..1b99c00f49 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 摘要原本要提供的一切，在消费方真正需要时都**可从仅追加日志中派生**（`firstPrompt` = 第一条 `user/message`；近期度 = 最后一个事件的 `time` 或文件 mtime），或者已经存在于不可变 header 中（`createdAt`、`cwd`）。唯一*不可*派生的是用户*手动编辑*的标题，但它从未实现，纯属 YAGNI；如果未来真有功能需要，它可以作为独立的日志事件或 header 字段回归。
 
-这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公开服务约定和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**反直觉性**（未来读者在原 Agent Note 描述 `SessionMeta` 的位置发现 `SessionHeader` 时，若无此记录便会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
+这次移除同时收窄两个后端的公开服务约定和磁盘格式；summary 是有意为未来设计的结果，而非意外；如今原 Agent Note 描述 `SessionMeta` 之处已是 `SessionHeader`，这就是 summary 消失的原因。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
 
 ## 无需迁移
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.i18n.yaml
index c8714bf8ab..2e82d32d06 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.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 .agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
-2026-06-20-collapse-trace-only-session-events.md: c77062c3cd44286b43c175702c35b36f9cc31da6
-2026-06-20-collapse-trace-only-session-events.zh.md: bc7e33f2d5dce370b846b1451fca6a652660dc92
+2026-06-20-collapse-trace-only-session-events.md: a7a4ab3a2e4c008b59bc4cb1023e699c6fd8a76b
+2026-06-20-collapse-trace-only-session-events.zh.md: ecb267e77f6a35aba8f73200c9d3061a821c2965
diff --git a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
index c77062c3cd..a7a4ab3a2e 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
@@ -15,7 +15,7 @@ These events make the canonical transcript look more useful as telemetry than it
 Standalone trace-only events are removed exactly where their information is preserved without a parallel record:
 
 - Successful-step usage folds into the matching `assistant/message` (`assistant/message { turn, step, content, usage? }`), so the assembled model output and its accounting travel together.
-- A failed or aborted step that has usage but no assistant content carries the usage on an empty-content `assistant/message` (the implementation note below carries the no-information-loss proof) — no persisted usage chunk goes unrepresented.
+- A failed or aborted step that has usage but no assistant content carries the usage on an empty-content `assistant/message { content: [], usage }` — no persisted usage chunk goes unrepresented. The no-information-loss case is the max-tokens path: a step cut off with usage but empty content (e.g. only a dropped tool call) previously emitted a standalone `usage`. To keep the empty-content event from injecting a spurious content-less assistant turn into the provider transcript, `deriveMessages()` skips empty-content `assistant/message` events; a regression test asserts usage stays represented AND derived history stays uncorrupted.
 - The step number from the standalone `error` event folds into `turn/end.reason` for `kind: 'error'` (`{ kind: 'error', step, message, code? }`) — `turn/end` is the durable turn outcome ACP and resume already consume.
 - `agent/error` and logging stay for live diagnostics; there is no second session-log error record after `turn/end`.
 
@@ -31,14 +31,10 @@ The user conversation log contains what is needed to render, resume, audit, and
 
 ## Consequences
 
-A consumer can no longer filter the canonical log for standalone `usage` or step-level `error` rows. It must read those facts from the assistant/failure events that carry them. That is a reasonable simplification only if the implementing PR proves the same facts remain present; otherwise the standalone events should stay.
+A consumer can no longer filter the canonical log for standalone `usage` or step-level `error` rows. It must read those facts from the assistant/failure events that carry them. That is a reasonable simplification because the same facts remain present, as the Verification section proves.
 
 ## Implementation note
 
-Shipped as proposed, with one scope refinement (per AGENTS.md "Agent Notes are proposals, not golden truth"):
-
-- **Empty-content `assistant/message` hosts usage with no data loss.** The proof the proposal demanded (no persisted usage chunk becomes unrepresented) lands on the max-tokens path: a step cut off with usage but empty content (e.g. only a dropped tool call) previously emitted a standalone `usage`. It now records an empty-content `assistant/message { content: [], usage }`. To keep that from injecting a spurious content-less assistant turn into the provider transcript, `deriveMessages()` skips empty-content `assistant/message` events. A regression test asserts usage stays represented AND derived history is uncorrupted.
-
 **Format version.** This changes persisted events, but the pre-release session format remains pinned at `0` and rejects any other version without migration. `dsh-session` owns the constant used by writers and load validation. Monotonic format versions begin at the first release.
 
 Usage is now observed on `assistant/message.usage`; an operational error's step on `turn/end.reason` for `kind: 'error'`. `agent/error` + logging are unchanged for live diagnostics.
diff --git a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
index bc7e33f2d5..ecb267e77f 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 仅在信息已被保留、无需并行记录的情况下，移除独立的、仅用于追踪的事件：
 
 - 成功步骤的 usage 折叠进匹配的 `assistant/message`（`assistant/message { turn, step, content, usage? }`），使组装好的模型输出与其计费信息一同传递。
-- 失败或中止的步骤如果有 usage 但没有 assistant 内容，则将 usage 放在一个空内容的 `assistant/message` 上（下方实现说明给出了无信息丢失的证明）——不会有已持久化的 usage 分片无处安放。
+- 失败或中止的步骤如果有 usage 但没有 assistant 内容，则将 usage 放在一个空内容的 `assistant/message { content: [], usage }` 上——不会有已持久化的 usage 分片无处安放。无信息丢失的情形是 max-tokens 路径：一个被截断的步骤有 usage 但内容为空（例如只有一个被丢弃的工具调用），以前会发出独立的 `usage`。为防止空内容事件向提供方 transcript 注入一个多余的无内容 assistant 轮次，`deriveMessages()` 跳过空内容的 `assistant/message` 事件；回归测试断言 usage 仍有记录，且派生历史未被破坏。
 - 独立 `error` 事件中的步骤编号折叠进 `turn/end.reason`（当 `kind: 'error'` 时：`{ kind: 'error', step, message, code? }`）——`turn/end` 是 ACP 和恢复机制已经消费的持久轮次结果。
 - `agent/error` 与日志保留用于实时诊断；`turn/end` 之后不再有第二条会话日志错误记录。
 
@@ -31,14 +31,10 @@ Status: implemented
 
 ## 后果
 
-消费方不能再从规范日志中筛选独立的 `usage` 或步骤级 `error` 行，而必须从承载这些信息的助手消息或失败事件中读取这些事实。只有在实现 PR（Pull Request）证明相同事实仍然存在的前提下，这才是合理的简化；否则独立事件应予保留。
+消费方不能再从规范日志中筛选独立的 `usage` 或步骤级 `error` 行，而必须从承载这些信息的助手消息或失败事件中读取这些事实。由于相同事实仍然存在——「验证」一节给出了证明——这是合理的简化。
 
 ## 实现说明
 
-按提案落地，但有一处范围细化（遵循 AGENTS.md 所述「Agent Note 是提案，而非绝对真理」）：
-
-- **空内容 `assistant/message` 承载 usage，无数据丢失。** 提案要求的证明（不会有已持久化的 usage 分片无处安放）落在 max-tokens 路径上：一个被截断的步骤有 usage 但内容为空（例如只有一个被丢弃的工具调用），以前会发出独立的 `usage`。现在它记录一个空内容的 `assistant/message { content: [], usage }`。为防止这向提供方 transcript 注入一个多余的无内容 assistant 轮次，`deriveMessages()` 跳过空内容的 `assistant/message` 事件。回归测试断言 usage 仍有记录，且派生历史未被破坏。
-
 **格式版本。** 此变更影响已持久化的事件，但预发布会话格式仍固定为 `0`，拒绝任何其他版本且不做迁移。`dsh-session` 拥有写入方和加载校验使用的常量。单调递增的格式版本从首次正式发布开始。
 
 Usage 现在通过 `assistant/message.usage` 观测；运行时错误的步骤编号通过 `turn/end.reason`（当 `kind: 'error'` 时）观测。`agent/error` 与日志用于实时诊断，保持不变。
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index a07b952a01..1b1b928591 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.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 .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
-2026-06-20-public-agent-stop-surface.md: ecbd00864f9e11205e544049a2e1c641ac132213
-2026-06-20-public-agent-stop-surface.zh.md: e9b0a3b8735537f2323dfe246eb7002b23c14947
+2026-06-20-public-agent-stop-surface.md: cd18299475373fba0e9a324d601e868bd1925370
+2026-06-20-public-agent-stop-surface.zh.md: 9824dbc1f03edea29edeabec50ed2b7c7bbe750e
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
index ecbd00864f..cd18299475 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
@@ -4,13 +4,11 @@ Status: implemented
 
 English | [中文](2026-06-20-public-agent-stop-surface.zh.md)
 
-> **Implementation note:** Only `abort()` was removed. `whenIdle()` remains because it is the public quiescence signal and safely handles waiter settlement and replacement-turn races; consumers should not reconstruct that behavior from status transitions.
-
 ## Problem
 
 The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter originally only exposed its broad default, which clears queued and steering work while aborting the active turn. `cancel(cause, { keepInbox: true })` now covers the production Web stop policy without exposing the private turn holder; ACP retains broad cancellation, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort.
 
-The behavioral distinction is real, but no shipping code needs a separate narrower verb. AgentLoop owns one private cancellation holder for the whole turn. `cancel(cause, options?)` carries an explicit typed `user` or `parent` cause; its broad default drops pending input, while `keepInbox` preserves pending work for later turns. Disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md).
+The behavioral distinction is real, but no shipping code needs a separate narrower verb. AgentLoop owns one private cancellation holder for the whole turn. `cancel(cause, options?)` carries an explicit typed `user` or `parent` cause; its broad default drops pending input, while `keepInbox` preserves pending work for later turns. Disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation note](../architecture/2026-07-16-explicit-turn-cancellation.md).
 
 The extra surface area made the loop carry a public verb that was mostly a teardown internal. An options-bearing `cancel()` expresses caller policy without exposing a second holder-shaped operation.
 
@@ -24,7 +22,7 @@ Public `abort()` is absent, and the disposer remains async and waits for the loo
 
 ## Alternatives considered
 
-**Removing `whenIdle()` too** — the original proposal's shape, reversed on validating the premise against the code (the implementation note above carries the full record): it is a load-bearing quiescence primitive, and pushing consumers onto hand-observed `running`→`idle` transitions is exactly the brittle path the defensive patterns warn against.
+**Removing `whenIdle()` too** — the original proposal's shape, reversed on validating the premise against the code: it is a load-bearing quiescence primitive that safely handles waiter settlement and replacement-turn races, and pushing consumers onto hand-observed `running`→`idle` transitions is exactly the brittle path the defensive patterns warn against.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index e9b0a3b873..9824dbc1f0 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -4,8 +4,6 @@ Status: implemented
 
 [English](2026-06-20-public-agent-stop-surface.md) | 中文
 
-> **实现说明：** 仅移除了 `abort()`。`whenIdle()` 予以保留，因为它是公开的完全停稳信号，能安全处理等待者结算与替换轮次竞态；消费方不应从状态转换中自行重建该行为。
-
 ## 问题
 
 公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者原本只暴露广义默认行为，该行为会清除已排队和 steering（中途引导）工作，同时中止活动轮次。`cancel(cause, { keepInbox: true })` 现在无需暴露私有轮次 holder 即可覆盖生产环境的 Web 停止策略；ACP 保留广义取消，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。
@@ -24,7 +22,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**同时移除 `whenIdle()`**：最初提案的形态，在对照代码验证前提后被推翻（上方的实现说明记录了完整过程）：它是承重的完全停稳原语，迫使消费方手动观测 `running`→`idle` 转换正是防御性模式所警告的脆弱路径。
+**同时移除 `whenIdle()`**：最初提案的形态，在对照代码验证前提后被推翻：它是承重的完全停稳原语，能安全处理等待者结算与替换轮次竞态，迫使消费方手动观测 `running`→`idle` 转换正是防御性模式所警告的脆弱路径。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.i18n.yaml
index 1357d372f5..5268b8e2f8 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.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 .agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
-2026-06-20-remove-agent-boundary-mirror-events.md: 24ac1e32667eb325044f4df583cde509421af3de
-2026-06-20-remove-agent-boundary-mirror-events.zh.md: 633c349a3e3a1efc4089fa9ae639aa457dd3d619
+2026-06-20-remove-agent-boundary-mirror-events.md: cb3cb83e7e37fae52b59bb8566284aa80708e23a
+2026-06-20-remove-agent-boundary-mirror-events.zh.md: aa7ebec9ff8870f9237afbe137bf94bd2c7b61a9
diff --git a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
index 24ac1e3266..cb3cb83e7e 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
@@ -4,15 +4,6 @@ Status: implemented
 
 English | [中文](2026-06-20-remove-agent-boundary-mirror-events.zh.md)
 
-<!-- Shipped in AMENDED, narrowed form: the four turn/step BOUNDARY mirrors are
-     removed; `agent/steering` and `agent/stream-chunk` were RETAINED here (they
-     are not durable-boundary mirrors — see "Scope: what is and isn't removed").
-     The original proposal bundled `agent/steering` into the removal; keeping it
-     out kept this Agent Note's scope to boundaries. Each retained event was later
-     removed by its own decision — see
-     [Stop mirroring the token stream as an agent event](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md)
-     and [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md). -->
-
 ## Problem
 
 The loop records the canonical transcript in `SessionEvent` and also emitted a parallel set of live `agent/*` boundary mirror events: `agent/turn-start`, `agent/turn-end`, `agent/step-start`, and `agent/step-end`. The mirrors made consumers choose between two sources of truth for the SAME durable fact. ACP already chose the session log for prompt settlement and committed output because it is the one durable, replayable record; consuming a live mirror would require reconciling its timing with the boundary already stored in that log. The stdio UI was the only production consumer that still rendered turn boundaries from the mirror events; it already rendered tool calls and results from `session/event`.
@@ -25,7 +16,7 @@ Make `session/event` the single live boundary/transcript stream. Consumers that
 
 The four durable-boundary mirrors — `agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end` — are removed from the agent event taxonomy. A UI that wants the agent handle at a boundary retains the live target object from `agent/created`/`agent/disposed` and compares its session directly; `dsh-ui-stdio` uses this to label the app-owned agent's `[main turn N]` header while other sessions render their durable id. The canonical record remains the event-sourced session log.
 
-The step mirrors (which had no consumer at all) were removed first, in [the event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md); that Agent Note KEPT the turn mirrors on the stated justification that the stdio UI needed the `Agent` handle at the turn boundary. This Agent Note finishes the job: `dsh-ui-stdio` is a disposable test REPL whose rendering can change freely, so "ui-stdio needs it" is not a reason to keep a mirror — it reads `session/event` and retains only its live target object.
+The step mirrors (which had no consumer at all) were removed first, in [the event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md); that Agent Note KEPT the turn mirrors on the stated justification that the stdio UI needed the `Agent` handle at the turn boundary. This decision finishes the job: `dsh-ui-stdio` is a disposable test REPL whose rendering can change freely, so "ui-stdio needs it" is not a reason to keep a mirror — it reads `session/event` and retains only its live target object.
 
 ## Scope: what is and isn't removed
 
@@ -33,7 +24,7 @@ Removed (durable-boundary mirrors — the session log is authoritative for each)
 
 RETAINED — NOT durable-boundary mirrors, so out of scope for this decision:
 
-- `agent/steering` — not a boundary, so out of scope for THIS decision (the original proposal bundled it into the removal; that would have been scope creep here). It mirrors the durable `steering/message` control record rather than a boundary, and was removed by its own follow-up: [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md).
+- `agent/steering` — not a boundary, so out of scope for THIS decision. It mirrors the durable `steering/message` control record rather than a boundary, and was removed by its own follow-up: [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md).
 - `agent/stream-chunk` — the live token stream. Out of scope for THIS decision (a mirror of the durable `assistant/chunk`, not a boundary), it was removed by its own follow-up: [Stop mirroring the token stream as an agent event](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md).
 - `agent/created`, `agent/disposed`, `agent/status`, `agent/error`, `agent/queued` — lifecycle/control events that are not transcript data. `agent/queued` in particular is an inbox acknowledgement that fires before any durable event exists (cancelled queued work may never enter the log), so it is deliberately live-only.
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
index 633c349a3e..aa7ebec9ff 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
@@ -4,15 +4,6 @@ Status: implemented
 
 [English](2026-06-20-remove-agent-boundary-mirror-events.md) | 中文
 
-<!-- 以修订、收窄后的形式落地：
-     移除了四个轮次/步骤边界镜像；此处保留了 `agent/steering` 和
-     `agent/stream-chunk`（它们不是持久边界镜像——参见
-     「范围：移除什么、不移除什么」）。原始提案将 `agent/steering` 与其他项一并
-     移除；把它排除在外，使本 Agent Note 的范围保持在边界上。后来每个保留事件
-     都由各自的决策移除——参见
-     [停止将 token 流镜像为 agent 事件](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md)
-     和[移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)。 -->
-
 ## 问题
 
 循环在 `SessionEvent` 中记录规范 transcript（文本记录），同时还发出一组并行的实时 `agent/*` 边界镜像事件：`agent/turn-start`、`agent/turn-end`、`agent/step-start` 和 `agent/step-end`。这些镜像迫使消费方在同一持久事实的两个真源之间做选择。ACP（Agent Client Protocol）已经为提示词结算和已提交输出选择会话日志，因为它是唯一持久、可重放的记录；消费实时镜像需要把它的时序与日志中已经存储的边界进行调和。stdio UI 是唯一仍从镜像事件渲染轮次边界的生产环境消费方；它已经从 `session/event` 渲染工具调用和结果。
@@ -25,7 +16,7 @@ Status: implemented
 
 四个持久边界镜像——`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`——已从 agent（智能体）事件分类体系中移除。希望在边界处取得 agent handle 的 UI 会保留来自 `agent/created`/`agent/disposed` 的实时目标对象，并直接比较其会话；`dsh-ui-stdio` 据此为应用拥有的 agent 标记 `[main turn N]` 头部，其他会话则渲染其持久 id。规范记录仍是事件溯源会话日志。
 
-步骤镜像（完全没有消费方）最先在[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 中移除；该 Agent Note 当时以 stdio UI 需要在轮次边界取得 `Agent` handle 为由，保留了轮次镜像。本 Agent Note 完成余下工作：`dsh-ui-stdio` 是可随时丢弃的测试 REPL，其渲染可以自由变化，因此「ui-stdio 需要它」并不是保留镜像的理由——它读取 `session/event`，只保留自己的实时目标对象。
+步骤镜像（完全没有消费方）最先在[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 中移除；该 Agent Note 当时以 stdio UI 需要在轮次边界取得 `Agent` handle 为由，保留了轮次镜像。本决策完成余下工作：`dsh-ui-stdio` 是可随时丢弃的测试 REPL，其渲染可以自由变化，因此「ui-stdio 需要它」并不是保留镜像的理由——它读取 `session/event`，只保留自己的实时目标对象。
 
 ## 范围：移除什么、不移除什么
 
@@ -33,7 +24,7 @@ Status: implemented
 
 保留——不是持久边界镜像，因此不在本决策范围内：
 
-- `agent/steering`——不是边界，因此不在本决策范围内（原始提案将其一并移除；在此会造成范围蔓延）。它镜像持久的 `steering/message` 控制记录，而非边界，后来由自己的后续决策移除：[移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)。
+- `agent/steering`——不是边界，因此不在本决策范围内。它镜像持久的 `steering/message` 控制记录，而非边界，后来由自己的后续决策移除：[移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)。
 - `agent/stream-chunk`——实时 token 流。不在本决策范围内（它镜像持久的 `assistant/chunk`，而非边界），后来由自己的后续决策移除：[停止将 token 流镜像为 agent 事件](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md)。
 - `agent/created`、`agent/disposed`、`agent/status`、`agent/error`、`agent/queued`——不属于 transcript 数据的生命周期/控制事件。尤其是 `agent/queued`，它是在任何持久事件存在之前触发的收件箱确认（取消的排队工作可能永远不会进入日志），所以有意只保留为实时事件。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml
index dff6c560ff..4d2986bc7e 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.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 .agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
-2026-06-20-unify-agent-and-session-id.md: c55152f4f13fe0acb530503e84f465799007cff7
-2026-06-20-unify-agent-and-session-id.zh.md: 92774a3a1b2ff90ccc6163967b4281552a253575
+2026-06-20-unify-agent-and-session-id.md: 4084912f95aa2354e815a1b4c05cd7f90bd3c315
+2026-06-20-unify-agent-and-session-id.zh.md: 3daa09d2169e8a407bf1c4c47dd9dbe987bde99c
diff --git a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
index c55152f4f1..4084912f95 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
@@ -33,7 +33,6 @@ The config-driven path keeps `agents[].id` as a stable configuration label, not
 - ACP, stdio, hooks, bash ownership, persistence, and lineage use the shared `SessionId` directly. The ACP subagent backend mints its lifecycle id in the parent namespace because a child server's returned session id is only server-local; the ACP bridge verifies exact `Agent` ownership from the forward session map; and JSON-RPC forwards only lifecycle events whose service-snapshotted `local` flag is true, obtains the delegating parent from the scoped event carrier, and keeps no child identity or lineage cache.
 - The config-driven resume-or-create policy is explicit and covered across a durable restart.
 - A production listener search kept `agent/created`/`agent/disposed` and their publication semantics.
-- Typecheck, coverage, snapshots, doc-sync, module-graph verification, build, and hygiene pass.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
index 92774a3a1b..3daa09d216 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
@@ -33,7 +33,6 @@ agent 的注册表 id 等于其会话 id。`CreateAgentOptions` 接受一个 `se
 - ACP、stdio、钩子、bash 归属、持久化和 lineage 直接使用共享 `SessionId`。ACP subagent 后端在父命名空间中铸造其生命周期 id，因为子服务器返回的会话 id 仅在服务器本地有效；ACP bridge 根据正向会话 map 验证精确的 `Agent` 归属；JSON-RPC 只转发生命周期事件中由服务快照保存的 `local` 标记为 true 的事件，从带范围的事件 carrier 取得委托父项，并且不保留子 identity 或 lineage cache。
 - 配置驱动的恢复或创建策略是显式的，并在持久化重启场景下得到覆盖。
 - 生产监听器搜索确认保留 `agent/created`/`agent/disposed` 及其发布语义。
-- 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建与 hygiene 全部通过。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index 956cfcee91..48b74cc809 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.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 .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
-2026-06-26-fsspec-style-fs-seam.md: c11c129a55c2e9e37efc83b01a219cae8b937fbc
-2026-06-26-fsspec-style-fs-seam.zh.md: 0e73ee134563bf8208e63f37bf36415eb1bf562d
+2026-06-26-fsspec-style-fs-seam.md: 76e5493400525f01e78f47e73dc543d0499b6045
+2026-06-26-fsspec-style-fs-seam.zh.md: cc7519a8a928888973b2fcc4a3350f9e43a54979
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
index c11c129a55..76e5493400 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
@@ -15,7 +15,7 @@ That makes every future backend reimplement model-facing read semantics and obse
 
 This also creates a real UX dead-end: a windowed read records `view: partial`, and partial views cannot authorize `edit`. A model that reads lines 100-150 of a large file therefore cannot edit line 120 unless it first gets a `full` read, which may be impossible for a file past the read cap. Literal edit only needs freshness: the bytes being matched must still be from the version the model read.
 
-The old Agent Note already deferred a separate `@deepseek-ai/dsh-fs-policy` package. This Agent Note builds that layer and keeps `ctx.fs` close to fsspec-style storage primitives (`info`/`cat`/`open`), without turning it into full fsspec.
+The old Agent Note already deferred a separate `@deepseek-ai/dsh-fs-policy` package. This decision builds that layer and keeps `ctx.fs` close to fsspec-style storage primitives (`info`/`cat`/`open`), without turning it into full fsspec.
 
 ## Decision
 
@@ -69,7 +69,7 @@ Deleted from `dsh-fs`: `readPage`, `FsExpectation`, `FsView`, `FsStateSource`, `
 
 ## Policy Contract
 
-`@deepseek-ai/dsh-fs-policy` is a plugin, not a service: it registers no `ctx.*` key and injects nothing. It owns the write/edit freshness policy and observed-state that do not belong on the `FileSystem` provider base class (where a sandboxed/remote backend would otherwise inherit model-facing observation policy it has no business carrying). It contributes that policy through the `fs/*` event gate the executor dispatches. (This Agent Note originally proposed a concrete `ctx.fileContext` service with `read`/`write`/`edit` methods; [the event-gate Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) refined it into the plugin described here so the tool is never method-coupled to the policy.)
+`@deepseek-ai/dsh-fs-policy` is a plugin, not a service: it registers no `ctx.*` key and injects nothing. It owns the write/edit freshness policy and observed-state that do not belong on the `FileSystem` provider base class (where a sandboxed/remote backend would otherwise inherit model-facing observation policy it has no business carrying). It contributes that policy through the `fs/*` event gate the executor dispatches.
 
 Observed state lives here as `WeakMap<owner, Map<targetKey, FsVersion>>`. An entry exists iff the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence *is* the prior-observation record — there is no separate `hasRead` flag. The owner is derived structurally from the opaque event actor (`{ agent?: { session? } }`), a shape that lives in `dsh-fs-policy`, not `dsh-fs`.
 
@@ -113,7 +113,7 @@ It keeps the Service Definition / Service provider / Consumer discipline, consum
 
 ## Later extension
 
-The seam was later extended with direct directory listing by [Add direct directory listing to the filesystem seam](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md). That follow-up is tracked separately so this Agent Note's acceptance criteria continue to describe the fsspec-style refit that originally shipped.
+The seam was later extended with direct directory listing by [Add direct directory listing to the filesystem seam](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md). That follow-up is recorded separately so this note continues to describe the fsspec-style refit that originally shipped.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
index 0e73ee1345..cc7519a8a9 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 
 这还造成了一个真实的用户体验死胡同：窗口化读取记录 `view: partial`，而 partial 视图无法授权 `edit`。一个模型读取了大文件的第 100-150 行，如果想编辑第 120 行，就必须先获取一次 `full` 读取，而对于超过读取上限的文件这可能做不到。字面编辑实际上只需要新鲜度：被匹配的字节仍然来自模型所读取的那个版本即可。
 
-旧 Agent Note 已经推迟了独立的 `@deepseek-ai/dsh-fs-policy` 包。本 Agent Note 构建该层，使 `ctx.fs` 保持接近 fsspec 风格的存储原语（`info`/`cat`/`open`），但不把它变成完整的 fsspec。
+旧 Agent Note 已经推迟了独立的 `@deepseek-ai/dsh-fs-policy` 包。本决策构建该层，使 `ctx.fs` 保持接近 fsspec 风格的存储原语（`info`/`cat`/`open`），但不把它变成完整的 fsspec。
 
 ## 决策
 
@@ -69,7 +69,7 @@ type FsWriteIntent =
 
 ## 策略约定
 
-`@deepseek-ai/dsh-fs-policy` 是插件，而非服务：它不注册任何 `ctx.*` 键，也不注入任何内容。它拥有不应位于 `FileSystem` 提供方基类上的写入/编辑新鲜度策略和 observed state（否则沙箱/远程后端会继承不该由其承载的面向模型观察策略）。它通过执行器分派的 `fs/*` 事件门禁贡献该策略。（本 Agent Note 最初提议带有 `read`/`write`/`edit` 方法的具体 `ctx.fileContext` 服务；[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 将其细化为本文所述插件，使工具永远不会在方法层与策略耦合。）
+`@deepseek-ai/dsh-fs-policy` 是插件，而非服务：它不注册任何 `ctx.*` 键，也不注入任何内容。它拥有不应位于 `FileSystem` 提供方基类上的写入/编辑新鲜度策略和 observed state（否则沙箱/远程后端会继承不该由其承载的面向模型观察策略）。它通过执行器分派的 `fs/*` 事件门禁贡献该策略。
 
 观测状态以 `WeakMap<owner, Map<targetKey, FsVersion>>` 的形式存放于此。当且仅当 owner 读取、写入或编辑过该目标时，条目才存在（每次成功都会发出 `fs/observed`），因此条目的存在*本身就是*先前观测的记录——没有单独的 `hasRead` 标志。owner 从不透明的事件 actor（`{ agent?: { session? } }`）结构化派生，该形状定义在 `dsh-fs-policy` 中而非 `dsh-fs` 中。
 
@@ -113,7 +113,7 @@ type FsWriteIntent =
 
 ## 后续扩展
 
-后来，[为文件系统 seam 添加直接目录列表](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)进一步扩展了该 seam。该后续工作单独跟踪，使本 Agent Note 的验收标准继续描述最初落地的 fsspec 风格改造。
+后来，[为文件系统 seam 添加直接目录列表](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)进一步扩展了该 seam。该后续工作单独记录，使本文继续描述最初落地的 fsspec 风格改造。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml
index eb7f6a02b9..e926e1b6ed 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.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 .agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
-2026-07-04-drop-image-content-block.md: cdedf4bd5dfe60c72cea185d88b83d3b93928ff0
-2026-07-04-drop-image-content-block.zh.md: 4caf717a360c1a3d536415a84e57fd9fff32c710
+2026-07-04-drop-image-content-block.md: 5d0357270973ac20234d8ce72c403f27ce2ad0e0
+2026-07-04-drop-image-content-block.zh.md: f781c775e49c06f9b3f4c54d13cc3a1519c15daf
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
index cdedf4bd5d..5d03572709 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
@@ -18,7 +18,7 @@ Remove `ImageBlock`, its map entry, and image-specific branches from adapters an
 
 `ContentBlockMap` can reintroduce images when adapters and compaction support them. ACP may remain a text-only automation protocol. Keeping a core type whose only implementation is rejection would advertise an unusable surface; absence gives producers an immediate compile-time failure instead.
 
-The recorded fallback, had review landed on keeping the slot: keep `ImageBlock` but replace every silent skip with a loud rejection, and document that policy in the vocabulary — the silent drop was the one state with no defender. Review landed on removal; the fallback stands as the documented alternative should the slot ever return ahead of a full feature.
+The documented fallback, should the slot ever return ahead of a full feature: keep `ImageBlock` but replace every silent skip with a loud rejection, and document that policy in the vocabulary — the silent drop was the one state with no defender.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
index 4caf717a36..f781c775e4 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 当适配器和压缩支持 image 时，`ContentBlockMap` 可以重新引入 image 内容块。ACP 可以继续作为纯文本的自动化协议。保留一个唯一实现就是拒绝的核心类型，等于宣告一个不可用的对外服务接口；移除后，生产者会立即得到编译期错误。
 
-评审中记录的回退方案（假如评审决定保留该槽位）：保留 `ImageBlock`，但将所有静默跳过替换为显式拒绝，并在词汇文档中记录该策略——静默丢弃是唯一没有辩护者的状态。评审最终决定移除；此回退方案作为文档化的替代方案保留，以备该槽位在完整功能就绪之前回归。
+文档化的回退方案（以备该槽位在完整功能就绪之前回归）：保留 `ImageBlock`，但将所有静默跳过替换为显式拒绝，并在词汇文档中记录该策略——静默丢弃是唯一没有辩护者的状态。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
index 80f7b1a144..3a37cb4ead 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.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 .agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
-2026-07-04-tighten-hook-protocol-contract.md: 0c2397fa298ebd67d24f86d66d7d049b9da57ce9
-2026-07-04-tighten-hook-protocol-contract.zh.md: b0edd754eb5115936a03a892a2db0b67552f64f1
+2026-07-04-tighten-hook-protocol-contract.md: eecec255d930d2896fc1ea3dee85bb2efa582a19
+2026-07-04-tighten-hook-protocol-contract.zh.md: 0b913a8783eab8e05d78b8c3ecc712fe4b1d947c
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
index 0c2397fa29..eecec255d9 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
@@ -10,7 +10,7 @@ Four pieces of the `dsh-hook-protocol`/bridge contract missed the discipline the
 
 1. **`HookDialect`'s `'native'` variant** (`packages/hooks/hook-protocol/src/types.ts`) had zero producers — the bridges stamp `'claude'` and `'codex'`; the only `'native'` constructor anywhere was the lib's own unit test. The field's own JSDoc defines `dialect` as "the bridge that ran it", and native is not a bridge: the [interception extension-points Agent Note](../feature/2026-06-30-interception-extension-points.md) records that native hooks are not a package and that "a native plugin can already use the typed Decisions" without the durable hook log, and the flagship native-plugin worked example asserts exactly that (no `hook/*` events at all).
 2. **`HookOutput.suppressOutput`** (same file) was parsed by the codec and discarded on every path: no bridge branch, no merge fold, no warn, no deferred-list row — uniquely among its parsed-but-unhonored siblings, each of which carries a stated deferral (`updatedInput` → a logged warn plus the [pre-tool-input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md); `systemMessage` → a logged warn plus a README deferred row; `continue`/`stopReason` → a `TODO(hook-continue-false)` anchor plus the `'stop'` decision record). Structurally there is nothing to suppress: hook stdout never enters any transcript (context flows only via `additionalContext`; the log records only `decision`/`stderrSummary`), so a hook author setting `suppressOutput: true` got silent nothing with no warn.
-3. **`defaultTimeoutMs` was double-defaulted in both bridge configs with a floating literal** — a schema `.default(600_000)` AND a `?? 600_000` fallback (`packages/hooks/hooks-claude/src/index.ts`, `packages/hooks/hooks-codex/src/index.ts`), two homes per bridge for one protocol-level constant, so the bridges could silently drift apart on the shared default. *The proposal's original remedy — delete the knob outright — was overtaken by the no-hardcoded-tunables audit, which kept the knob as the explicit bridge-owned config (and added `stderrSummaryMaxChars` beside it); what remained to fix was the literal's home.*
+3. **`defaultTimeoutMs` was double-defaulted in both bridge configs with a floating literal** — a schema `.default(600_000)` AND a `?? 600_000` fallback (`packages/hooks/hooks-claude/src/index.ts`, `packages/hooks/hooks-codex/src/index.ts`), two homes per bridge for one protocol-level constant, so the bridges could silently drift apart on the shared default. *The knob stays as explicit bridge-owned config per the no-hardcoded-tunables rule (with `stderrSummaryMaxChars` beside it); the fix is the literal's home.*
 4. **The `hook/result` semantics lived in the bridges, twice, not in the lib that owns the event.** `summarize()` — the stderr truncation rule — was byte-identical in `packages/hooks/hooks-claude/src/index.ts` and `packages/hooks/hooks-codex/src/index.ts`, and so was the decision-string rule `output.decision ?? (output.continue === false ? 'stop' : 'pass')`; yet `dsh-hook-protocol` declared `hook/result`, documented `stderrSummary` as "truncated" without owning the truncation, and documented the decision values without owning the mapping. If one bridge drifted (a different cap, a different fallback), the shared durable event's semantics would fork silently.
 
 ## Decision
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
index b0edd754eb..0b913a8783 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截扩展点 Agent Note](../feature/2026-06-30-interception-extension-points.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
 2. **`HookOutput.suppressOutput`**（同一文件）被 codec 解析后在所有路径上均被丢弃：没有 bridge 分支处理它、没有合并 fold、没有 warn、没有 deferred-list 行——在所有「被解析但未兑现」的同类字段中它是唯一没有明确延期声明的（`updatedInput` → 一条 warn 日志加 [pre-tool-input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)；`systemMessage` → 一条 warn 日志加 README deferred 行；`continue`/`stopReason` → 一个 `TODO(hook-continue-false)` 锚点加 `'stop'` decision 记录）。从结构上看根本无物可抑制：钩子 stdout 从不进入任何 transcript（文本记录）；上下文仅通过 `additionalContext` 流入，日志也只记录 `decision`/`stderrSummary`。因此，钩子作者设置 `suppressOutput: true` 得到的是无声的空操作，且无任何警告。
-3. **`defaultTimeoutMs` 在两个 bridge 配置中都以游离的字面量重复设置了默认值**——schema 的 `.default(600_000)` 加上一个 `?? 600_000` 回退（`packages/hooks/hooks-claude/src/index.ts`、`packages/hooks/hooks-codex/src/index.ts`），一个协议级常量在每个 bridge 中有两个归属地，两个 bridge 可能在共享默认值上悄然分歧。*提案最初的补救措施是彻底删除该旋钮，但被 no-hardcoded-tunables 审计所取代：审计保留了该旋钮作为 bridge 拥有的显式配置（并在旁边新增了 `stderrSummaryMaxChars`）；剩下要修的是字面量的归属地。*
+3. **`defaultTimeoutMs` 在两个 bridge 配置中都以游离的字面量重复设置了默认值**——schema 的 `.default(600_000)` 加上一个 `?? 600_000` 回退（`packages/hooks/hooks-claude/src/index.ts`、`packages/hooks/hooks-codex/src/index.ts`），一个协议级常量在每个 bridge 中有两个归属地，两个 bridge 可能在共享默认值上悄然分歧。*按 no-hardcoded-tunables 规则，该旋钮保留为 bridge 拥有的显式配置（旁边有 `stderrSummaryMaxChars`）；要修的是字面量的归属地。*
 4. **`hook/result` 的语义存在于两个 bridge 中（各一份），而非拥有该事件的 lib。** `summarize()`——stderr 截断规则——在 `packages/hooks/hooks-claude/src/index.ts` 与 `packages/hooks/hooks-codex/src/index.ts` 中逐字节相同；decision 字符串规则 `output.decision ?? (output.continue === false ? 'stop' : 'pass')` 同样如此。然而 `dsh-hook-protocol` 声明了 `hook/result`、在文档中将 `stderrSummary` 描述为「已截断」却不拥有截断逻辑，记录了 decision 值却不拥有映射逻辑。如果某个 bridge 漂移（不同的上限、不同的回退），共享持久化事件的语义就会悄然分叉。
 
 ## 决策
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
index dc75549250..62ce36c656 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.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 .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
-2026-07-17-one-send-one-turn.md: 834eb2b3aace0a0aa5f86f483e7b7d7aabbe467e
-2026-07-17-one-send-one-turn.zh.md: 5bd2ed0e70766c43b0a0a5d5d4038b39094d5099
+2026-07-17-one-send-one-turn.md: 71ea5d23c303a2e5de472ceabf9868364d916ab9
+2026-07-17-one-send-one-turn.zh.md: ac0af03c61c4fb5583f2f08e28e957994954e094
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
index 834eb2b3aa..71ea5d23c3 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
@@ -14,7 +14,7 @@ This grouping changes behavior, not just the number of model calls. One ordinary
 
 ## Decision
 
-The rule is simple: each successful `send()` creates one independent FIFO queue item. If that item runs, it is the only ordinary message in its turn. An item can be dropped before it starts, so the precise guarantee is at most one turn rather than exactly one; two sends are never silently combined.
+Each successful `send()` creates one independent FIFO queue item. If that item runs, it is the only ordinary message in its turn. An item can be dropped before it starts, so the precise guarantee is at most one turn rather than exactly one; two sends are never silently combined.
 
 Before inserting a message, `send()` checks the agent state and accepts an already identified, deeply frozen value. The durable splice and `agent/inbox/inserted { message }` retain its `MessageId`; the pending message remains addressable through `Inbox.replace()` and `Inbox.remove()` until the driver claims or discards it. The [claimed pre-step inbox decision](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md) owns the current lifecycle.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
index 5bd2ed0e70..ac0af03c61 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-规则很简单：一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。
+一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。
 
 消息插入之前，`send()` 会检查 agent 状态，并接受已有标识且经过深度冻结的值。持久化 splice 与 `agent/inbox/inserted { message }` 会保留其 `MessageId`；在驱动器领取或丢弃该消息之前，可以通过 `Inbox.replace()` 与 `Inbox.remove()` 寻址。当前生命周期由[已领取 pre-step inbox 决策](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md)规定。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 26e91f9351..625bb457ea 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.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 .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
-2026-07-31-one-route-to-add-a-workspace.md: 93f10493848a65aee9c9e67502abfd73fe1e6d1f
-2026-07-31-one-route-to-add-a-workspace.zh.md: 83d91abb9ada3c1431a1b4ef126ea42a8406d326
+2026-07-31-one-route-to-add-a-workspace.md: 46bd5d5ca5ecfbc340fcb46b6da5e9f237764ab1
+2026-07-31-one-route-to-add-a-workspace.zh.md: 6a6e8b3fc9f64a62d3264f4c7779d11c8515e447
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
index 93f1049384..46bd5d5ca5 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-31-one-route-to-add-a-workspace.zh.md)
 
 Both Workspace surfaces — the sidebar region header's `+` and the conversation hero's chip — offered two ways to get a Workspace: **Open local folder…**, which raised the composed directory flow, and **Create a new workspace**, which took a name and created `<workspaceRoot>/<name>`. The two overlapped: the browse occupant carries its own **New folder** affordance, so picking a directory already covered creating one. Two entries meant two vocabularies for one outcome, a name dialog with its own duplicate-name rule, and a create target the operator could neither see nor choose.
 
-Removing the weaker entry leaves the sidebar header with exactly one action, which raised the presentation question this Note also settles: what a popover with a single row should look like.
+Removing the weaker entry leaves the sidebar header with exactly one action, which raised the presentation question this decision also settles: what a popover with a single row should look like.
 
 ## Decision
 
@@ -27,7 +27,7 @@ The direct-open path carries the busy rule the menu entry states: while a pick i
 
 ## Wire and CLI residue
 
-The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client contract that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-contract, and CLI surface with its own reviewer and its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
+The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client contract that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-contract, and CLI surface with its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
 
 ## Testing
 
@@ -39,13 +39,13 @@ The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace
 
 **Keep `Open local folder…` as the label.** Rejected: after the merge the entry both opens and creates, and naming it after the mechanism hides the creation half from exactly the users whose entry we removed. The counter-argument — "本地" usefully disambiguates the browser's machine from the harness's — is answered one step later by the dialog's own title and breadcrumbs.
 
-**Keep the two-entry menu and make `Create a new workspace` open the same flow.** Rejected: two labels for one action is the confusion we were asked to remove, not a smaller version of it.
+**Keep the two-entry menu and make `Create a new workspace` open the same flow.** Rejected: two labels for one action is the confusion this change removes, not a smaller version of it.
 
 **Keep a one-row popover for consistency with the hero's menu.** Rejected: a popover that offers no choice is a wasted click and reads as unfinished. Consistency here is the *rule* (menu ⇔ a choice exists), not the widget.
 
 **Keep the menu shell for entries we might add later (clone a repo, remote directory).** Rejected under "require a current owner and need": no such entry exists, and restoring a menu when one arrives is a smaller change than shipping an empty frame now.
 
-**Delete the wire's create-by-name branch in the same change.** Rejected for this PR: it is backend/CLI surface with a different reviewer and a wider test fallout, and the urgent decision is the UI. See the residue section — it is marked, not forgotten.
+**Delete the wire's create-by-name branch in the same change.** Rejected here: it is backend/CLI surface with a wider test fallout, and the urgent decision is the UI. See the residue section — it is marked, not forgotten.
 
 **Register the workspace through the host in the e2e scaffold instead of driving the dialog.** Rejected: it would have decoupled all 15 scenarios from the picker, so nothing in the lane would prove the surviving route reaches a live composer. Every scenario now walks the real dialog to adopt its directory; only the create-a-folder half is concentrated in one scenario, because repeating it everywhere makes the shared helper non-idempotent for no extra signal.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 83d91abb9a..6a6e8b3fc9 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 两处 Workspace 表层——侧边栏区头的 `+` 与会话主视觉区的 chip——都提供了两条获得 Workspace 的路径：**打开本地文件夹…** 拉起组合的目录流程，**新建工作区** 接收一个名称并创建 `<workspaceRoot>/<name>`。两者重叠：浏览占用者自带 **新建文件夹** 能力，因此"选一个目录"本就覆盖了"建一个目录"。两个入口意味着同一结果有两套词汇、一个自带重名规则的名称对话框，以及一个操作者既看不到也选不了的创建位置。
 
-删掉较弱的那个入口后，侧边栏区头只剩一个动作，于是引出了本 Note 一并裁定的展示问题：只有一行的浮层应该长什么样。
+删掉较弱的那个入口后，侧边栏区头只剩一个动作，于是引出了本决策一并裁定的展示问题：只有一行的浮层应该长什么样。
 
 ## Decision
 
@@ -27,7 +27,7 @@ Status: implemented
 
 ## Wire and CLI residue
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端约定同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端约定与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端约定同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端约定与 CLI 面，有各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
 ## Testing
 
@@ -39,13 +39,13 @@ Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root`
 
 **保留 `打开本地文件夹…` 作为标签。** 否决：合并后该入口既能打开也能创建，用机制命名会恰好对那些入口被我们删掉的用户隐藏创建这一半。反方理由——"本地"二字有效区分了浏览器所在机器与 harness 所在机器——在下一步就由对话框自身的标题和面包屑回答了。
 
-**保留双入口菜单，让 `新建工作区` 也打开同一个流程。** 否决：同一动作两个标签正是我们被要求消除的混淆，而不是它的缩小版。
+**保留双入口菜单，让 `新建工作区` 也打开同一个流程。** 否决：同一动作两个标签正是本次改动所消除的混淆，而不是它的缩小版。
 
 **为了与主视觉区菜单保持一致而保留只有一行的浮层。** 否决：不提供选择的浮层是一次浪费的点击，读起来像半成品。这里要一致的是*规则*（有菜单 ⇔ 存在选择），不是控件。
 
 **为将来可能新增的入口（克隆仓库、远程目录）保留菜单壳。** 否决，依据"require a current owner and need"：这样的入口目前并不存在，而等它到来时再恢复菜单，比现在就发一个空壳的改动更小。
 
-**在同一改动中删除 wire 的按名称创建分支。** 本 PR 否决：那是 backend/CLI 面，reviewer 不同、测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
+**在同一改动中删除 wire 的按名称创建分支。** 在此否决：那是 backend/CLI 面，测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
 
 **在 e2e scaffold 中经 host 注册 workspace，而不驱动对话框。** 否决：那会让全部 15 个场景与选择器解耦，整条 lane 将无法证明幸存的这条路径能走到可用的 composer。现在每个场景都会走真实对话框来接纳自己的目录；只有"新建文件夹"那一半集中在一个场景里，因为处处重复只会让共享辅助函数失去幂等性，却换不来额外信号。
 
diff --git a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml
index d64cedbdc3..dd31b8f7c8 100644
--- a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.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 .agents/notes/implemented/testing/2026-06-11-property-based-testing.md
-2026-06-11-property-based-testing.md: a1bd4147a26a3d562899310e238096939fc2d01a
-2026-06-11-property-based-testing.zh.md: 062b2df76597ba16a7ad0682d57b35e54a07d9bd
+2026-06-11-property-based-testing.md: 7ab6f2daeb65e603d055ad6127a91f6b76ebc26e
+2026-06-11-property-based-testing.zh.md: 2fae02356a84b88e750ce1fd8c3003212395b084
diff --git a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md
index a1bd4147a2..7ab6f2daeb 100644
--- a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-06-11-property-based-testing.zh.md)
 
-> Merges the original proposal and the decision record for one topic. It found a real BlockAssembler duplicate-`block-end` bug on first run.
+> The property suite found a real BlockAssembler duplicate-`block-end` bug on its first run.
 
 ## Problem
 
@@ -12,7 +12,7 @@ Example-based tests pin the cases we thought of. The harness's core is protocol-
 
 ## Decision
 
-Adopt `fast-check` (a root devDependency) with one `tests/properties.spec.ts` per protocol-shaped package, generators tuned for *realistic-but-adversarial* inputs (not uniform noise) and `numRuns` kept so the suite stays well under ~10s locally. Failures print a reproducible seed. (The original proposal also sketched a nightly CI job running 100× the iterations; that was not shipped — the property suite runs only in the normal `push`/`pull_request` CI, and a scheduled high-iteration job remains possible future work.)
+`fast-check` (a root devDependency) powers one `tests/properties.spec.ts` per protocol-shaped package, with generators tuned for *realistic-but-adversarial* inputs (not uniform noise) and `numRuns` kept so the suite stays well under ~10s locally. Failures print a reproducible seed. (A nightly CI job running 100× the iterations is not shipped — the property suite runs only in the normal `push`/`pull_request` CI; a scheduled high-iteration job remains possible future work.)
 
 - **dsh-llm / BlockAssembler:** arbitrary chunk streams (valid + malformed: duplicate indices, stragglers, missing block-start). Invariants: `blocks()` count ≤ distinct indices seen; re-assembly idempotent (`blocks()` is stable across repeated calls and `message().content` mirrors it); `blocks()` never throws and yields only valid content-block tags; `finish` reflects the last `finish` chunk, defaulting to `{kind:'stop'}` when none arrives.
 - **dsh-session:** arbitrary event logs. Invariants: `deriveMessages` deterministic; replay-from-seed identical; seq strictly monotonic; non-message events never affect derived history; derived content is decoupled from the log.
diff --git a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
index 062b2df765..2fae02356a 100644
--- a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-11-property-based-testing.md) | 中文
 
-> 将原始提案与同一主题的决策记录合并为一篇。首次运行即发现了 BlockAssembler 重复 `block-end` 的真实 bug。
+> 属性测试套件首次运行即发现了 BlockAssembler 重复 `block-end` 的真实 bug。
 
 ## 问题
 
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-引入 `fast-check`（作为根 devDependency），在每个协议形态的包中编写一个 `tests/properties.spec.ts`。生成器调优为*逼真但对抗性*的输入（而非均匀噪声），`numRuns` 控制在本地套件总耗时远低于约 10 秒。失败时打印可复现的 seed。（原始提案还草拟了一个夜间 CI job，以 100 倍迭代运行；该部分未交付。属性测试套件仅在常规的 `push`/`pull_request` CI 中运行，定时高迭代 job 仍属可能的后续工作。）
+`fast-check`（作为根 devDependency）为每个协议形态的包驱动一个 `tests/properties.spec.ts`。生成器调优为*逼真但对抗性*的输入（而非均匀噪声），`numRuns` 控制在本地套件总耗时远低于约 10 秒。失败时打印可复现的 seed。（以 100 倍迭代运行的夜间 CI job 未交付——属性测试套件仅在常规的 `push`/`pull_request` CI 中运行；定时高迭代 job 仍属可能的后续工作。）
 
 - **dsh-llm / BlockAssembler：** 任意分片流（合法 + 畸形：重复索引、滞后分片、缺少 block-start）。不变式：`blocks()` 计数 ≤ 已见到的不同索引数；重组幂等（`blocks()` 在重复调用间稳定，且 `message().content` 与之一致）；`blocks()` 从不抛异常且仅产出合法的 content-block 标签；`finish` 反映最后一个 `finish` 分片，无此类分片时默认为 `{kind:'stop'}`。
 - **dsh-session：** 任意事件日志。不变式：`deriveMessages` 确定性；从 seed 回放结果一致；seq 严格单调递增；非消息事件不影响推导出的历史；推导出的内容与日志解耦。
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index 5dc542589f..0cd051aead 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.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 .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
-2026-06-19-acp-snapshot-tests.md: c6e81dc4a51083ed37ad6f837fe7dbb08c212e23
-2026-06-19-acp-snapshot-tests.zh.md: 729e5645b097f8db5b23594e16e48dc5b4cf211f
+2026-06-19-acp-snapshot-tests.md: 9e03c3c5be7b15a1a34c954dca2f1d6e7a875ba2
+2026-06-19-acp-snapshot-tests.zh.md: 59033a2fd85bc08bfe4abe34e8fd9aff9a67c87e
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
index c6e81dc4a5..9e03c3c5be 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
@@ -8,9 +8,7 @@ English | [中文](2026-06-19-acp-snapshot-tests.zh.md)
 
 Unit tests do not exercise the complete assembled-agent subprocess or its ACP automation wire, while real-API tests are nondeterministic and key-gated. Loader wiring, backend behavior, and protocol output can therefore regress despite green unit coverage, as the [default-export postmortem](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) demonstrated.
 
-The blocker for a full-transcript test is the model: the agent's output is driven by a non-deterministic LLM, and a key-gated test that hits the real API on every run is neither deterministic nor CI-runnable. We want the fidelity of a real run with the determinism of a fixture.
-
-This Agent Note records the decision to add a third test tier — **snapshot tests** — and the design choices that make it deterministic, keyless-in-CI, and cheap to maintain.
+The blocker for a full-transcript test is the model: the agent's output is driven by a non-deterministic LLM, and a key-gated test that hits the real API on every run is neither deterministic nor CI-runnable. The tier needs the fidelity of a real run with the determinism of a fixture.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index 729e5645b0..59033a2fd8 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -8,9 +8,7 @@ Status: implemented
 
 单元测试不会覆盖组装后的完整 agent（智能体）子进程及其 ACP（Agent Client Protocol）自动化协议格式，而真实 API 测试不具确定性且受密钥门控。因此，即使单元测试覆盖率检查通过，Loader 接线、后端行为和协议输出仍可能回归，[默认导出事故复盘（postmortem）](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)已经证明了这一点。
 
-完整 transcript（文本记录）测试的阻塞因素在于模型：agent 的输出由非确定性的 LLM（大语言模型）驱动，而每次运行都命中真实 API 的密钥门控测试既不确定也无法在 CI 中运行。我们需要真实运行的保真度与 fixture（测试前置数据）的确定性兼得。
-
-本 Agent Note 记下了新增第三层测试——**快照测试**——的决策，以及让它具备确定性、在 CI 中无需密钥、且维护成本低廉的设计选择。
+完整 transcript（文本记录）测试的阻塞因素在于模型：agent 的输出由非确定性的 LLM（大语言模型）驱动，而每次运行都命中真实 API 的密钥门控测试既不确定也无法在 CI 中运行。该测试层级需要真实运行的保真度与 fixture（测试前置数据）的确定性兼得。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
index 774a4d8851..72f45e8ae3 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.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 .agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
-2026-06-19-real-api-e2e-ci.md: 935664fd01df4844ee19be7b4f2f297ebf5bd29b
-2026-06-19-real-api-e2e-ci.zh.md: 4245cc9a3872cf2ab27633db5b23fc466d793934
+2026-06-19-real-api-e2e-ci.md: feb5d83f087f66dfec7e1540f6b32e33656409d4
+2026-06-19-real-api-e2e-ci.zh.md: c00aa6e962d9e86a9d5d5c1ccaf1001afa21ba67
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
index 935664fd01..feb5d83f08 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
@@ -10,11 +10,9 @@ The harness leans hard on real-API tests by policy: [docs/testing.md](../../../.
 
 The default gate ([.github/workflows/ci.yml](../../../../.github/workflows/ci.yml)) is deliberately keyless: it carries no secret and runs for forks. `test:e2e` self-skips without a key (`describe.skipIf(!process.env.DEEPSEEK_API_KEY)`), so adding it there would report green without exercising the real suite. A separate secret-bearing workflow is required to make real-API coverage a merge signal.
 
-This Agent Note records the decision to add a **second, secret-consuming workflow** that runs the real-API suite in CI, and — because introducing the first CI secret into a repo that may later go public is a security/isolation decision — the threat model it relies on and what changes when the repo becomes public.
-
 ## Decision
 
-Add a dedicated workflow, [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml), separate from ci.yml. It runs only `pnpm run test:e2e` against the external API using a repo secret, on trusted events, with a preflight that converts a missing secret into a loud failure instead of a false green. The keyless workflow remains separate so forkable quality gates and secret-consuming real-API gates keep different trigger and credential policies.
+A dedicated workflow, [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml), separate from ci.yml, runs only `pnpm run test:e2e` against the external API using a repo secret, on trusted events, with a preflight that converts a missing secret into a loud failure instead of a false green. The keyless workflow remains separate so forkable quality gates and secret-consuming real-API gates keep different trigger and credential policies.
 
 ### A separate workflow, not a job in ci.yml
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
index 4245cc9a38..c00aa6e962 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
@@ -10,11 +10,9 @@ Status: implemented
 
 默认门禁（[.github/workflows/ci.yml](../../../../.github/workflows/ci.yml)）刻意无密钥：不携带 secret，可供 fork 运行。`test:e2e` 在无密钥时自动跳过（`describe.skipIf(!process.env.DEEPSEEK_API_KEY)`），因此将其加入该工作流只会报绿而不会真正执行真实套件。要让真实 API 覆盖率成为合并信号，需要一个独立的、携带 secret 的工作流。
 
-本 Agent Note 记下了新增**第二条消费 secret 的工作流**以在 CI 中运行真实 API 套件的决策；由于向未来可能公开的仓库引入第一个 CI secret 属于安全/隔离决策，本文也记录其依赖的威胁模型，以及仓库公开时需要做出的变更。
-
 ## 决策
 
-添加一个专用工作流 [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml)，与 ci.yml 分离。它仅使用 repo secret 对外部 API 运行 `pnpm run test:e2e`，仅在可信事件上触发，并带有一个 preflight 检查：将缺失的 secret 转化为明确的失败而非虚假的绿色。无密钥工作流保持独立，使可 fork 的质量门禁与消费 secret 的真实 API 门禁各自拥有不同的触发和凭证策略。
+一个与 ci.yml 分离的专用工作流 [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml) 仅使用 repo secret 对外部 API 运行 `pnpm run test:e2e`，仅在可信事件上触发，并带有一个 preflight 检查：将缺失的 secret 转化为明确的失败而非虚假的绿色。无密钥工作流保持独立，使可 fork 的质量门禁与消费 secret 的真实 API 门禁各自拥有不同的触发和凭证策略。
 
 ### 独立工作流，而非 ci.yml 中的一个 job
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
index 34edafb0d1..2b03ad711c 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.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 .agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
-2026-06-22-subagent-snapshot-replay.md: 45034c29f608eb5b58f44b80438b801b6224cb82
-2026-06-22-subagent-snapshot-replay.zh.md: 1b90c1bda854b7cd8cd9eae1e8c9f34328477f15
+2026-06-22-subagent-snapshot-replay.md: 187831b2d3c2f08b32289983afbbe0bc03484c82
+2026-06-22-subagent-snapshot-replay.zh.md: b96be12df0ea1f1a6bb64dd787fec6880eb96243
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
index 45034c29f6..187831b2d3 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
@@ -13,7 +13,7 @@ It was built for ONE session per process, and that assumption is wired into two
 - **`dsh-llm-replay` keyed nothing.** It served the Nth `llm/stream` call the Nth recorded entry from a single global cursor. With a parent agent AND an in-process subagent both streaming on one context, the calls interleave and the single cursor hands the child the parent's script (and vice versa).
 - **The harness harvested one log.** `findSessionLog` walked the sessions root and returned the FIRST `.jsonl` it found. A subagent runs as a second `Session` with its own log, so the child's transcript was silently dropped.
 
-This was the `TODO(subagent-snapshots)` deferral recorded in the [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md): the in-process backends (PR2) shipped with unit + e2e coverage, but the full-transcript snapshot tier could not express a nested-agent shape until this infrastructure landed. This Agent Note is that stacked follow-up.
+This was the `TODO(subagent-snapshots)` deferral recorded in the [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md): the in-process backends shipped with unit + e2e coverage, but the full-transcript snapshot tier could not express a nested-agent shape until this infrastructure landed.
 
 ## Decision
 
@@ -55,4 +55,4 @@ Both replay keyless in the default gate.
 - The `TODO(subagent-snapshots)` deferral is resolved: nested-agent transcripts are now a first-class snapshot shape.
 - `GenerateOptions.sessionId` is a small, honest core API addition useful beyond replay (telemetry, request routing).
 - The `subagent` tool is bound to a single provider, so both children in `subagent-multi` are spawn (fresh). The keying routes by session, not by backend, so it is already correct for fork. The script *derivation* was not: a fork child's log begins with the seeded parent prefix (the parent's `assistant/chunk` events), so deriving its script from the whole log would replay the parent's responses as the child's. That correctness gap is closed by persisting a seed boundary — see [Persist the seed boundary so fork-child replay routes correctly](2026-06-22-fork-child-replay-seed-boundary.md) — and recorded fork + mixed spawn+fork scenarios now exercise both transports through one transcript (see [Record fork and mixed spawn+fork snapshot scenarios](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)).
-- Out-of-process (ACP) subagents are a different replay shape entirely (each child is its own PROCESS with its own replay), tracked as `TODO(acp-subagent-replay)` in the PR3 plan.
+- Out-of-process (ACP) subagents are a different replay shape entirely (each child is its own PROCESS with its own replay), tracked as `TODO(acp-subagent-replay)` in `subagent-acp`.
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
index 1b90c1bda8..b96be12df0 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
@@ -13,7 +13,7 @@ Status: implemented
 - **`dsh-llm-replay` 没有做任何键控。** 它用一个全局游标，将第 N 次 `llm/stream` 调用对应到单一录制序列的第 N 条。当父 agent（智能体）和一个进程内 subagent 在同一个上下文上同时流式输出时，调用交错，单一游标会把子 agent 的脚本发给父 agent（反之亦然）。
 - **harness 只收集一份日志。** `findSessionLog` 遍历 sessions 根目录，返回找到的第一个 `.jsonl`。subagent 作为第二个 `Session` 运行并拥有自己的日志，因此子 agent 的 transcript（文本记录）被静默丢弃。
 
-这就是 [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md)中通过 `TODO(subagent-snapshots)` 推迟的工作：进程内后端（PR2）落地时已有单元 + e2e 覆盖，但在这套基础设施落地前，完整 transcript 快照层无法表达嵌套 agent 形状。本 Agent Note 就是该堆叠式后续工作。
+这就是 [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md)中通过 `TODO(subagent-snapshots)` 推迟的工作：进程内后端落地时已有单元 + e2e 覆盖，但在这套基础设施落地前，完整 transcript 快照层无法表达嵌套 agent 形状。
 
 ## 决策
 
@@ -55,4 +55,4 @@ Status: implemented
 - `TODO(subagent-snapshots)` 延期项已解决：嵌套 agent 的 transcript 现在是快照层的一等形态。
 - `GenerateOptions.sessionId` 是一个小而诚实的 core API 新增，在回放之外同样有用（遥测、请求路由）。
 - `subagent` 工具绑定到单一提供方，因此 `subagent-multi` 中的两个子 agent 都是 spawn（全新创建）。键控按会话路由而非按后端路由，因此对 fork 同样正确。但脚本*派生*逻辑此前不正确：fork 子会话的日志以种子化的父前缀（父会话的 `assistant/chunk` 事件）开头，如果从完整日志派生脚本，就会把父 agent 的响应当作子 agent 的来回放。这一正确性缺口通过持久化种子边界来弥合——见[持久化 seed 边界以确保 fork 子会话回放正确路由](2026-06-22-fork-child-replay-seed-boundary.md)——录制的 fork 与混合 spawn+fork 场景现在通过一份 transcript 同时验证两种传输方式（见[记录 fork 与混合 spawn+fork 快照场景](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)）。
-- 进程外（ACP（Agent Client Protocol））subagent 是完全不同的回放形态（每个子 agent 是自己的进程、有自己的回放），作为 `TODO(acp-subagent-replay)` 记录在 PR3 计划中。
+- 进程外（ACP（Agent Client Protocol））subagent 是完全不同的回放形态（每个子 agent 是自己的进程、有自己的回放），作为 `TODO(acp-subagent-replay)` 记录在 `subagent-acp` 中。
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index dcd5119f92..4d710a9c55 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.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 .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: aa289c9a70623904606e2d06b6492acb3a7d98a3
-2026-07-24-web-gui-browser-e2e-lane.zh.md: 9e26dcb53f0373ac967c627b95b895385784f925
+2026-07-24-web-gui-browser-e2e-lane.md: 84912895514f9dba4ff61bc8842444a81c5fbefa
+2026-07-24-web-gui-browser-e2e-lane.zh.md: 3c94b42d1b85190dfe6b3b8ebb14efb4624fd326
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
index aa289c9a70..8491289551 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
@@ -72,7 +72,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot
 
 **Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless in-process path (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.
 
-**Real-model browser tests as the keyless lane.** Rejected: nondeterministic by construction; the surveyed cautionary case (open-webui) grew unbounded timeouts and was deleted. The with-key W5 smoke stays as the live-model complement.
+**Real-model browser tests as the keyless lane.** Rejected: nondeterministic by construction; the surveyed cautionary case (open-webui) grew unbounded timeouts and was deleted. The with-key real-host smoke stays as the live-model complement.
 
 **Running the high-cardinality performance case in the required browser gate.** Rejected: its fixture setup and full-history render add tens of seconds, while wall-clock and memory values vary with the host and cannot supply a stable correctness threshold. The required lane keeps deterministic behavior assertions; contributors run the diagnostic case when investigating or changing large-list and long-history rendering.
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index 9e26dcb53f..3c94b42d1b 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -72,7 +72,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥进程内路径（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
-**以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
+**以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的真实 host 冒烟仍是真实模型侧的补充。
 
 **在必需的浏览器门禁中运行高基数性能用例。** 已否决：其 fixture 设置和完整历史渲染会增加数十秒耗时，而壁钟时间和内存值随 host 不同而变化，无法提供稳定的正确性阈值。必需车道保留确定性行为断言；贡献者在调查或更改大列表和长历史渲染时运行该诊断用例。
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index 29932b1d06..648d77d482 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.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 .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
-2026-06-16-typed-event-schemas.md: d919db18f347d0633155f92bfecc43b8bf846659
-2026-06-16-typed-event-schemas.zh.md: 369a70846265035d92bf51fcd516793b648e2f0f
+2026-06-16-typed-event-schemas.md: c2cff264c7b766d4040d3f7588d436eb7b08140a
+2026-06-16-typed-event-schemas.zh.md: 5998be3cea98e1937eb7fe1298cb252cbf3ee171
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
index d919db18f3..c2cff264c7 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
@@ -15,8 +15,6 @@ The pattern is **compile-time only**. The types vanish at runtime: there is no s
 
 This raises whether the event vocabulary should move to **Zod** or another runtime-schema library so durable and plugin boundaries have runtime schemas rather than erased types.
 
-This Agent Note scopes that question without proposing an implementation.
-
 ## Why this is not a persistence change
 
 It is tempting to read "use Zod for serialization" as a local change to `dsh-session-persistence-jsonl/src/format.ts`. It is not, for one structural reason: **a plugin cannot declaration-merge a Zod schema.** Declaration merging is a TypeScript compile-time mechanism; a Zod schema is a runtime value. To validate events with Zod you need a **runtime registry** that every event-producing package contributes its schema to (e.g. `ctx.sessionEvents.register('compaction/marker', z.object({…}))`), and every consumer reads from. That registry — not the persistence backend — becomes the source of truth for the vocabulary, replacing the merge-extensible interface.
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
index 369a708462..5998be3cea 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -15,8 +15,6 @@ harness 将其核心词汇——内容块、消息来源、结束原因、轮次
 
 由此引出问题：事件词汇是否应迁移到 **Zod** 或其他运行时 schema 库，使持久化边界和插件边界拥有运行时 schema 而非被擦除的类型。
 
-本 Agent Note 界定该问题的范围，不提出具体实现。
-
 ## 为什么这不是一个持久化层的改动
 
 很容易把「用 Zod 做序列化」理解为对 `dsh-session-persistence-jsonl/src/format.ts` 的局部修改。但它不是，原因在于一个结构性事实：**插件无法对 Zod schema 进行声明合并。** 声明合并是 TypeScript 编译期机制；Zod schema 是运行时值。要用 Zod 校验事件，就需要一个**运行时注册表**，每个产出事件的包向其贡献自己的 schema（如 `ctx.sessionEvents.register('compaction/marker', z.object({…}))`），每个消费方从中读取。这个注册表——而非持久化后端——将成为词汇的真源，取代 merge-extensible 接口。
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 6b3b6cafb3..b3ef015459 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.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 .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
-2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
-2026-07-24-domain-kv-storage-and-workspace.zh.md: ea537e0e5e5b02955d0b279d80822b0220f2b20b
+2026-07-24-domain-kv-storage-and-workspace.md: 2170534017ff81aeeb6c58ea04503b40ff5b5ee6
+2026-07-24-domain-kv-storage-and-workspace.zh.md: c619ab3e47d6a3dea383bc7b78c42a4b4240799f
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
index 1cb2bc4b29..2170534017 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-24-domain-kv-storage-and-workspace.zh.md)
 
 The host's only persistence surface is the session event log (`packages/session/session-persistence`: append-only, one file per session). Anything that does not belong to a single session has nowhere to live, and two real needs exist today:
 
-- **The workspace entity.** The GUI needs workspace as a real object: path, title, and the list of owned sessions. Ownership belongs to the workspace — "which sessions belong to this workspace" is not any single session's fact, so writing it into the session log is semantically wrong. Until now workspace was only a sidebar visual grouping derived from cwd, with no entity (that conclusion has been overturned).
+- **The workspace entity.** The GUI needs workspace as a real object: path, title, and the list of owned sessions. Ownership belongs to the workspace — "which sessions belong to this workspace" is not any single session's fact, so writing it into the session log is semantically wrong. Before this design, workspace was only a sidebar visual grouping derived from cwd, with no entity.
 - **Dynamic session metadata** (the foreseeable second consumer). Cold session listings read only the first log line (an immutable creation-time snapshot); title, terminal status, and anything that evolves with the session is unavailable. The fix direction is a sidecar metadata table — exactly a KV table with high-frequency per-key updates.
 
 Separately, Session deletion needs a `SessionPersistence` delete primitive and a `session.delete` endpoint. That gap's design is settled in this note, but its implementation remains future work.
@@ -310,7 +310,7 @@ Snapshots: no model-visible or assembly surface this phase, none added; next pha
 - **SQLite storing a whole domain as one blob row**: any single-record change rewrites the whole domain, forfeiting per-key precise updates — SQLite's only edge over JSON reduced to zero.
 - **SQLite generating typed columns from the schema**: a DDL generator is over-engineering; document-per-row suffices, revisit when real query needs appear.
 - **One sqlite db file per domain**: contrary to the repository's one-database-many-tables convention.
-- **A single whole-store backend choice (the session-persistence single-slot pattern)**: the initial design; changed to coexisting backends + configured routing because the hub will carry multiple data forms whose backend preferences (human-readable vs high-frequency point updates) are bound to diverge — a single slot forces the coarse "swap everything + hand-migrate data" move. The cost is one extra name lookup, backed by fail-loud.
+- **A single whole-store backend choice (the session-persistence single-slot pattern)**: rejected — the hub will carry multiple data forms whose backend preferences (human-readable vs high-frequency point updates) are bound to diverge, and a single slot forces the coarse "swap everything + hand-migrate data" move. The cost is one extra name lookup, backed by fail-loud.
 - **path as the workspace key**: normalization/symlink resolution rewrites the path; reference anchors must be stable.
 - **Ownership derived from cwd (or merged with the ledger)**: two sources of truth; cwd cannot express ordering; ownership is a workspace-side fact to begin with.
 - **Change events carrying the old value**: the repository's change-event convention is "new snapshot + operation discriminant" (the sole exception, fs's before/after, is a method return value rather than an event, because the old value is unrecoverable afterwards and has a diff consumer); consumers needing diffs hold their own previous snapshot.
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index ea537e0e5e..c619ab3e47 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 host 侧唯一的持久化面是 session 事件日志（`packages/session/session-persistence`：仅追加、一 session 一文件）。凡是"不属于某个 session"的信息就没有落盘处，眼下有两个真实需求：
 
-- **workspace 实体**。GUI 要把 workspace 做成真实对象：路径、标题、关联 session 清单。归属关系由 workspace 持有——"哪些 session 属于这个 workspace"不是任何单个 session 自己的事实，塞进 session log 语义不成立。此前 workspace 只是 sidebar 上按 cwd 分组的视觉概念，没有实体（该结论已被推翻）。
+- **workspace 实体**。GUI 要把 workspace 做成真实对象：路径、标题、关联 session 清单。归属关系由 workspace 持有——"哪些 session 属于这个 workspace"不是任何单个 session 自己的事实，塞进 session log 语义不成立。在本设计之前，workspace 只是 sidebar 上按 cwd 分组的视觉概念，没有实体。
 - **session 动态元信息**（可预见的第二个消费方）。冷会话列表只读日志首行 header（创建时的不可变快照），title、结束状态这类随会话推进变化的信息拿不到；补齐方向是 sidecar 元数据表——正是一张按 key 高频点更新的 KV 表。
 
 另外，Session 删除需要 `SessionPersistence` 删除原语和 `session.delete` 端点。该空白的设计随本 Note 定案，但实现仍属未来工作。
@@ -305,7 +305,7 @@ export class WorkspaceRegistry extends Service {
 - **复用 session-persistence 的 coordinator/后端**：事件日志语义（仅追加、turn 崩溃修复、懒物化）与 KV 覆写语义不匹配；只借其分层思想（协调层持写序、后端只实现最小原语）。
 - **workspace 专用存储包，后续再抽 seam**：第二个消费方（session sidecar）已可预见，届时泛化要再动一次接口。
 - **domain 与 storage 合为一层**：后端会被迫接触 schema 校验、变更事件、写串行等领域关切；拆开后 storage 后端只做不透明原语（可替换面最小），domain 单实现收敛全部领域逻辑（zod/事件/串行化只写一遍，不随后端翻倍）。
-- **整库单后端二选一（学 session-persistence 单 slot 模式）**：曾是初版方案；改为多后端并存 + 配置路由，因为存储枢纽要承载多种数据形式，不同形式/域对后端的偏好（肉眼可读 vs 高频点更新）注定分化，单 slot 会逼出"整体换挂 + 手工导数据"的粗粒度动作。代价是按名查找多一步，fail-loud 兜底。
+- **整库单后端二选一（学 session-persistence 单 slot 模式）**：否决——存储枢纽要承载多种数据形式，不同形式/域对后端的偏好（肉眼可读 vs 高频点更新）注定分化，单 slot 会逼出"整体换挂 + 手工导数据"的粗粒度动作。代价是按名查找多一步，fail-loud 兜底。
 - **JSON 后端 jsonl 追加 + 墓碑 + 压实（compaction）**：temp+fsync+rename 的崩溃安全与 append 等价；覆写让文件永远是净值、肉眼可读，免掉折叠／压实／断行容错。域规模下整写与追加一行同量级。
 - **JSON 一表一文件**：覆写下文件粒度不影响写成本，按域合并文件更少，global 单例有落点。
 - **SQLite 整域存单行 blob**：任何一条记录变更都重写整域，失去按 key 精确更新——SQLite 相对 JSON 的唯一优势归零。
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index c5910fb083..9538bdc5d5 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 6c2c8137453d04ba6b631fe7f80a788a639b096b
-2026-07-27-session-projection-and-command-log.zh.md: f3370ea2631e9c9904c6fc996c2c8aff698c3830
+2026-07-27-session-projection-and-command-log.md: 01e77de47c7b5178ddc146e95487754a616639ec
+2026-07-27-session-projection-and-command-log.zh.md: 2de188bab9d51fb9d19f993653741a343f62e31c
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 6c2c813745..01e77de47c 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -143,13 +143,13 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 
 **A dedicated `session.projections` RPC** — rejected: baseline-refresh moments coincide exactly with tail-page pulls, so a separate unary buys a second round-trip, a second seq to reconcile, and a client-side "when to refetch" decision that the rider design deletes outright.
 
-**An opaque `get(agent)` provider contract** — rejected after being the first draft: with the computation model hidden inside the domain, the framework can never checkpoint the state, serve cold sessions (no agent, no loaded log — `get` has nothing to run against), or resume from a mid-log position. Registering the `(init, apply, view)` unit hands the framework the drive and keeps the domain to pure mathematics; a domain with host-side behavioral needs still keeps its own service subscriptions independently of the projection unit.
+**An opaque `get(agent)` provider contract** — rejected: with the computation model hidden inside the domain, the framework can never checkpoint the state, serve cold sessions (no agent, no loaded log — `get` has nothing to run against), or resume from a mid-log position. Registering the `(init, apply, view)` unit hands the framework the drive and keeps the domain to pure mathematics; a domain with host-side behavioral needs still keeps its own service subscriptions independently of the projection unit.
 
 **A live-only overlay hook (`live?(agent, base)`) for plan's pending intent** — rejected: it existed solely because the user's plan *selection* was not in the log. Routing the selection through the standard command channel puts `command/run` on the account, pending becomes a pure replay quantity, and the projection contract stays exactly three pure functions.
 
 **Naming the registration API `registerFold`** — superseded by the unit contract: the registered object now genuinely is a fold, but `fold*` in this repo names pure `(events) => state` helper functions while this registry accepts a keyed, schema'd, versioned unit. Projection remains the event-sourcing term for the read-model role, and both #587's note title and #497's comments already use it.
 
-**Client-side folding (per-domain projection cells with a `fromEvent`)** — rejected after being the second draft: once plan's unit folds two event types, a client cell must duplicate the host's transition logic in the browser — the same fold written twice, evolving separately. Pushing finished values (the title-frame precedent, generalized) keeps one computation site and reduces the client to a generic seq-guarded value store; domains write zero client code.
+**Client-side folding (per-domain projection cells with a `fromEvent`)** — rejected: once plan's unit folds two event types, a client cell must duplicate the host's transition logic in the browser — the same fold written twice, evolving separately. Pushing finished values (the title-frame precedent, generalized) keeps one computation site and reduces the client to a generic seq-guarded value store; domains write zero client code.
 
 **Bounded reverse scan over the log tail (absorber declarations)** — rejected for now: nothing supports it today, it only serves domains whose every event carries the full folded state, and the persisted projection cache covers the same cold-read need uniformly (cache row + forward tail replay — the same recipe as the client's baseline + catch-up, and as paged loading). Revisit only if a real cold-read path emerges that checkpointing cannot serve.
 
@@ -184,4 +184,4 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 - **Eager drive costs on busy sessions**: every committed event passes every registered unit's `apply`. Units are cheap per-event by construction (whole-value rule), non-matching events return the same reference, and the count of registered domains is small; if a hot path ever shows, per-unit event-type prefilters can be added without contract change.
 - **Projection payload growth**: every tail page carries every registered key. Payloads are whole values of UI-scale state (a todo list, a goal snapshot); if a future domain's value is large, per-key opt-out or lazy keys can be added to the request without changing the model.
 - **Command log volume**: two log-only events per slash command; bounded by human command frequency, negligible against chunk volume.
-- **Re-target churn**: three open PRs rebase onto a moved foundation. Accepted cost of infrastructure-first; the migration mapping section in the design ledger names each PR's keep/drop list.
+- **Re-target churn**: three open PRs rebase onto a moved foundation. Accepted cost of infrastructure-first.
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index f3370ea263..2de188bab9 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -143,13 +143,13 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 **专设一个 `session.projections` RPC**——不予采纳：基线刷新时刻与尾页拉取精确重合，单独的一元 RPC 只会换来第二次往返、第二个待调和的 seq，以及一个客户端「何时重取」决策——而搭载设计把这个决策整个删掉了。
 
-**不透明的 `get(agent)` 提供方约定**——曾是第一稿，后被否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
+**不透明的 `get(agent)` 提供方约定**——否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
 
 **为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影约定保持恰好三个纯函数。
 
 **把注册 API 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该注册表接收的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
 
-**客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——曾是第二稿，后被否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
+**客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
 
 **对日志尾部的有界反向扫描（absorber 声明）**——暂不采纳：今天没有任何东西支持它，它只服务于「每个事件都携带完整折叠状态」的领域，而持久投影缓存以统一方式覆盖同一冷读需求（缓存行 + 正向尾部回放——与客户端的基线 + 追赶、与分页加载是同一套配方）。只有当出现检查点机制服务不了的真实冷读路径时才重议。
 
@@ -184,4 +184,4 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 - **忙碌会话上的主动驱动开销**：每个已提交事件都要过每个已注册单元的 `apply`。按构造，单元的逐事件开销很低（全量值规则），不匹配的事件返回同一引用，且已注册领域的数量很小；若真出现热点路径，可以加按单元的事件类型预过滤，约定不变。
 - **投影载荷膨胀**：每个尾页携带每个已注册的 key。载荷是 UI 量级状态的全量值（一张 todo 清单、一份 goal 快照）；将来若某领域的值很大，可以在请求上加逐 key 的 opt-out 或惰性 key，模型本身不用改。
 - **命令日志体量**：每条斜杠命令两个仅日志事件；上限由人敲命令的频率决定，相对分片体量可忽略不计。
-- **重新对接的返工**：三个未合入的 PR 要变基到挪动后的地基上。这是基础设施先行的既定代价；设计台账中的迁移映射一节逐一列出每个 PR 的保留/删除清单。
+- **重新对接的返工**：三个未合入的 PR 要变基到挪动后的地基上。这是基础设施先行的既定代价。
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
index 2da4662891..8fd7d1dd91 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.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 .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
-2026-07-28-storage-root-and-derived-medium-recovery.md: c7b423770fcca89c54d3866db7701348351cc259
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: e271373662e4decfd0663133fd811ee1b9247507
+2026-07-28-storage-root-and-derived-medium-recovery.md: 45e8b3dfcad0590a26581e20c7bc6bb5692e5c36
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 330473b2b17669e373a6dc433a74d8bb3ba37628
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
index c7b423770f..45e8b3dfca 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-storage-root-and-derived-medium-recovery.zh.md)
 
 ## Problem
 
-The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
+The persisted projection cache ([note](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
 
 **Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session/session-persistence-jsonl/src/index.ts).
 
@@ -18,7 +18,7 @@ Two independent changes, one per gap.
 
 ### One global storage root (shipped, amended form); resolved once at construction (still open)
 
-- **Shipped**: the Web overlay anchors `storage-json.root` to `$DSH_HOME/storages` directly in the row through the app-boot-provided `dshHomePath('storages')` (`~/.dsh/storages` by default, beside `~/.dsh/sessions`; no leading dot — the home is already a hidden tree). The helper delegates to the canonical `dsh-paths` resolver, and the session root uses the same function without duplicating its fallback and tilde rules. The user ruled the per-row form in over this section's original launcher-patch + `storageRoot` profile key (see Alternatives); per-row overrides ride the personal `~/.dsh/config.yaml` patch layer. The web e2e scaffold already patches the row to an absolute temp root, so tests never touch the user's home.
+- **Shipped**: the Web overlay anchors `storage-json.root` to `$DSH_HOME/storages` directly in the row through the app-boot-provided `dshHomePath('storages')` (`~/.dsh/storages` by default, beside `~/.dsh/sessions`; no leading dot — the home is already a hidden tree). The helper delegates to the canonical `dsh-paths` resolver, and the session root uses the same function without duplicating its fallback and tilde rules. The per-row form was chosen (user decision) over a launcher patch + `storageRoot` profile key (see Alternatives); per-row overrides ride the personal `~/.dsh/config.yaml` patch layer. The web e2e scaffold already patches the row to an absolute temp root, so tests never touch the user's home.
 - **Still open**: `JsonStorageBackend` resolves its configured root once at construction (`resolve(config.root)`), adopting the JSONL backend's recorded rationale verbatim: a later `process.cwd()` change must not split one backend across roots. The SQLite storage backend already resolves its path.
 - Pre-release stance applies (and was executed): no migration shim. A deployment that cached under `<cwd>/.storages` re-derives everything (workspace re-bootstraps from the header index; the projection cache refolds lazily) or moves the two json files by hand once.
 
@@ -33,7 +33,7 @@ Two independent changes, one per gap.
 
 **Keep per-launch-directory `.storages` (the pre-change status quo)** — rejected: sessions are global, so every derived-from-sessions medium splits against its own source of truth; the cache's motivating scenario (one listing over all sessions) structurally misses rows, and the workspace registry indexes sessions it cannot see from another launch directory.
 
-**Launcher patch + a `storageRoot` profile key (this section's original form)** — not taken: one `!!js` yml expression reaches the global root with the same layering the session root already has; a launcher patch adds a second rewrite point, and the profile key is an empty seat until a real consumer exists (per-row overrides already have the personal config.yaml patch layer).
+**Launcher patch + a `storageRoot` profile key** — not taken: one `!!js` yml expression reaches the global root with the same layering the session root already has; a launcher patch adds a second rewrite point, and the profile key is an empty seat until a real consumer exists (per-row overrides already have the personal config.yaml patch layer).
 
 **Patch only the projection cache's route to a global root, leave `workspace.json` per-cwd** — rejected: the workspace registry has the identical global-vs-cwd mismatch, and the user decision that shaped the cache placed it deliberately beside `workspace.json` — one hub root keeps the media co-located and the mental model single.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
index e271373662..330473b2b1 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-持久投影缓存（[RFC](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
+持久投影缓存（[决策记录](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
 
 **文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session/session-persistence-jsonl/src/index.ts）。
 
@@ -18,7 +18,7 @@ Status: proposed
 
 ### 全局唯一存储根（已落地，形态修正）；构造时 resolve 一次（仍开放）
 
-- **已落地**：出厂 Web overlay 通过 app-boot 提供的 `dshHomePath('storages')`，直接在 `storage-json` 行内把 `root` 锚定到 `$DSH_HOME/storages`（默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩；目录名不带点——home 本身已是隐藏树）。该辅助函数委托给规范的 `dsh-paths` 解析器，会话根也使用同一个函数，无需重复其回退和波浪号规则。用户拍板采用这种按行形态取代本节初版的「launcher patch + `storageRoot` profile 键」（见 Alternatives）；按行覆盖仍走个人 `~/.dsh/config.yaml` patch 层。web e2e scaffold 本就把该行 patch 到临时绝对根，测试不触用户 home。
+- **已落地**：出厂 Web overlay 通过 app-boot 提供的 `dshHomePath('storages')`，直接在 `storage-json` 行内把 `root` 锚定到 `$DSH_HOME/storages`（默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩；目录名不带点——home 本身已是隐藏树）。该辅助函数委托给规范的 `dsh-paths` 解析器，会话根也使用同一个函数，无需重复其回退和波浪号规则。最终选用按行形态（用户决定）而非「launcher patch + `storageRoot` profile 键」（见 Alternatives）；按行覆盖仍走个人 `~/.dsh/config.yaml` patch 层。web e2e scaffold 本就把该行 patch 到临时绝对根，测试不触用户 home。
 - **仍开放**：`JsonStorageBackend` 在构造时对配置根 `resolve` 一次，原样采纳 JSONL 后端已记录的理由：后续 `process.cwd()` 变化不得把一个后端劈到多个根下。SQLite 存储后端已经 resolve 其路径。
 - 适用 pre-release 立场（已按此执行）：不做迁移垫片。曾在 `<cwd>/.storages` 下缓存过的部署要么全部重新派生（工作区从 header 索引重新 bootstrap；投影缓存惰性重折），要么手动把两个 json 文件挪一次。
 
@@ -33,7 +33,7 @@ Status: proposed
 
 **保持按启动目录的 `.storages`（改动前现状）**——拒绝：会话是全局的，所以每个从会话派生的介质都与自己的真源劈叉；缓存的动机场景（一次列出全部会话）结构性丢行，工作区注册表索引着从另一个启动目录看不见的会话。
 
-**launcher patch + `storageRoot` profile 键（本节初版提案形态）**——未采：一行 yml `!!js` 表达式即达全局根，与会话根的既有分层完全一致；launcher patch 多引入一个改写点，profile 键在有真实消费者前是空席（按行覆盖已有个人 config.yaml patch 层可用）。
+**launcher patch + `storageRoot` profile 键**——未采：一行 yml `!!js` 表达式即达全局根，与会话根的既有分层完全一致；launcher patch 多引入一个改写点，profile 键在有真实消费者前是空席（按行覆盖已有个人 config.yaml patch 层可用）。
 
 **只把投影缓存的 route 指到全局根，`workspace.json` 留在 per-cwd**——拒绝：工作区注册表有一模一样的全局 vs per-cwd 错位，而且塑造缓存的用户决策就是刻意把它放在 `workspace.json` 旁边——一个 hub 根让介质同址、心智模型单一。
 
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index aa6add0de4..cacf90bfa6 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.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 .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: 5fd26dd2d4086dd6f834f7bdb3194b0ad16db1eb
-2026-07-06-recallable-compaction.zh.md: 25ce6ca50d1755e3a90dbadb35d027c95262e5a4
+2026-07-06-recallable-compaction.md: 1d62f18c0b63257b45f55ad389a94eae4471f920
+2026-07-06-recallable-compaction.zh.md: e53e669b6111f10701353448927c5e37f4e13e0b
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index 5fd26dd2d4..1d62f18c0b 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -65,7 +65,7 @@ The design ships as a new backend `dsh-compact-recallable` on the existing `ctx.
 
 ### Follow-ups
 
-Specified during review, deferred until observation calls for them:
+Deferred until observation calls for them:
 
 - Guard degradation ladder (code-only rollup of the oldest stub prefix, footers preserved, rolled-up ids remain recall targets; then one summary after the frozen boundary) — on observed guard livelock or stub-region pressure.
 - Echo detection on stub outputs (sentence-scale n-grams, short literals exempt, retry then strip) — on observed division-of-labor leakage.
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index 25ce6ca50d..e53e669b61 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -65,7 +65,7 @@ Status: proposed
 
 ### 后续事项
 
-以下项目在评审期间已经明确，但会延后至观察结果证明需要时再实现：
+以下项目延后至观察结果证明需要时再实现：
 
 - 保护逻辑降级阶梯（通过代码汇总最早的存根前缀，保留页脚，已汇总 id 仍可作为回溯目标；随后在冻结边界后生成一份摘要）：触发条件是观察到保护逻辑活锁或存根区域压力。
 - 存根输出回声检测（句子级 n-gram，豁免短字面量；先重试，再剥离）：触发条件是观察到职责分工泄漏。
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
index f364456257..5be65aaf06 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.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 .agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
-2026-08-01-windows-pwsh-default.md: 1c3ccef23bb5cd9bc37237bd69aac2e2c56649a8
-2026-08-01-windows-pwsh-default.zh.md: d9fcc50a36a86b356fdf8507f53226d87dddc7bc
+2026-08-01-windows-pwsh-default.md: 64d713aecda60d8747199aff5334a80bf1867d92
+2026-08-01-windows-pwsh-default.zh.md: 74ba6c43dea984384a9b7dd2675b681ee025d6ca
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
index 1c3ccef23b..64d713aecd 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
@@ -10,7 +10,7 @@ The harness's shipped execution profile is bash-first on every platform. Windows
 
 ## Proposal
 
-Two follow-up stages, each independently shippable. The former stage 2 (bash-tool parity twin) shipped with the [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md): `tool-pwsh` now mirrors `tool-bash` for foreground and background work minus the sandbox surface, shares the `DSH_*` environment through `dsh-bash-env`, and carries a keyless application snapshot of its assembled surface.
+Two follow-up stages, each independently shippable. The bash-tool parity twin shipped with the [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md): `tool-pwsh` now mirrors `tool-bash` for foreground and background work minus the sandbox surface, shares the `DSH_*` environment through `dsh-bash-env`, and carries a keyless application snapshot of its assembled surface.
 
 1. **Windows default composition** — the shipped CLI compositions mount `dsh-pwsh-local` as the `ctx.bash` executor and `dsh-tool-pwsh` as the model-facing shell tool on Windows hosts (bash unmounted there), while POSIX hosts keep the bash stack. This is a composition/roster decision in `base.cordis.yml` and the surface overlays, gated by platform; it makes the shipped Windows experience PowerShell-native end to end.
 2. **pwsh GUI rendering** — the Web surface renders pwsh calls with the bash-shaped terminal presentation (terminal card with exit-status pill), the counterpart of the bash terminal cards. Shipped in the [pwsh UI presentation matches bash decision](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) with a keyless web lane; the TUI was removed, so no terminal twin remains. A PowerShell-aware presentation beyond bash parity (native path display, `$env:` facts) remains unclaimed.
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
index d9fcc50a36..74ba6c43de 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
@@ -10,7 +10,7 @@ harness 交付的执行配置在每个平台都是 bash 优先。Windows 主机
 
 ## 提案
 
-两个阶段，各自可独立交付。原阶段 2（bash 工具对等孪生）已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在除 sandbox 接口外，在前台与后台工作方面均与 `tool-bash` 对齐，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装后形态的 keyless 应用快照。
+两个阶段，各自可独立交付。bash 工具对等孪生已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在除 sandbox 接口外，在前台与后台工作方面均与 `tool-bash` 对齐，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装后形态的 keyless 应用快照。
 
 1. **Windows 默认组合**——交付的 CLI（命令行界面）组合在 Windows 主机上挂载 `dsh-pwsh-local` 作为 `ctx.bash` 执行器、`dsh-tool-pwsh` 作为面向模型的 shell 工具（那里不挂载 bash），POSIX 主机保持 bash 栈。这是 `base.cordis.yml` 与 surface 覆盖层里按平台门控的组合/清单决策；它让交付的 Windows 体验端到端 PowerShell 原生。
 2. **pwsh GUI 渲染**——Web 界面使用 bash 风格的终端呈现来渲染 pwsh 调用（带胶囊状退出状态标签的终端卡片），与 bash 终端卡片相对应。已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 及 keyless web 通道交付；TUI 已移除，不再有对应的终端界面。超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 信息）仍无人认领。
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
index 37137ceebb..65ea0d5028 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.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 .agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
-2026-06-11-api-extractor-reports.md: 03f512992fe87ea3d0f8d51a1772ce1ec89a5c0d
-2026-06-11-api-extractor-reports.zh.md: e3b40f29908ebe1096a02dd4ee5f4886bb5a4537
+2026-06-11-api-extractor-reports.md: 9c6895f317719294d6eeb4d88a16c3426a2d5b3b
+2026-06-11-api-extractor-reports.zh.md: e62b6168efac5c8296b55ff8ee0c7861d1849d31
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
index 03f512992f..9c6895f317 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
@@ -4,7 +4,7 @@ Status: proposed
 
 English | [中文](2026-06-11-api-extractor-reports.zh.md)
 
-> Split out from the original "Doc-sync and API reports" Agent Note (2026-06-11). Parts 1-2 (doc-block typechecking, event-taxonomy verification) shipped — see [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md). This is the deferred part 3, kept as a standalone proposal.
+> The doc-block-typechecking and event-taxonomy parts shipped ([doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)); this remaining API-report part is deferred as a standalone proposal.
 
 ## Problem
 
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
index e3b40f2990..e62b6168ef 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
@@ -4,7 +4,7 @@ Status: proposed
 
 [English](2026-06-11-api-extractor-reports.md) | 中文
 
-> 从最初的「doc-sync（文档同步门禁）与 API 报告」Agent Note 中拆出（首次提出于 2026-06-11）。第 1 至第 2 部分（文档块类型检查、事件分类体系校验）已交付，见 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)。本文是被推迟的第 3 部分，作为独立提案保留。
+> 文档块类型检查与事件分类体系两部分已交付（[doc-sync（文档同步门禁）强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)）；剩余的 API 报告部分作为独立提案被推迟。
 
 ## 问题
 
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 2df8d3774f..47b5725c18 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -29,7 +29,7 @@ Then check constraints that make placement expensive or wrong:
 
 - Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
-- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown (today's three — `scripts/gen-doc-graphs.ts`, `scripts/gen-persistence-catalog.ts`, `packages/typert/generator/src/cordis-catalog.ts` — all render into scanned pages, so the gate catches them via the committed output).
+- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown.
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
 
 ## Audit the corpus
diff --git a/.agents/skills/dsh-merging-stacked-prs/SKILL.md b/.agents/skills/dsh-merging-stacked-prs/SKILL.md
index 4bcb568955..964d20a4d8 100644
--- a/.agents/skills/dsh-merging-stacked-prs/SKILL.md
+++ b/.agents/skills/dsh-merging-stacked-prs/SKILL.md
@@ -9,7 +9,7 @@ Land dependent PRs through GitHub's native stack object and `gh stack merge`. Do
 
 ## Require native stack support
 
-Run `gh stack --version` before changing GitHub state. Hard-stop if the official extension or server-side stack feature is unavailable; do not fall back to the legacy manual landing procedure. GitHub stacks require every head branch to live in the same repository, so hard-stop on a cross-fork chain.
+Run `gh stack --version` before changing GitHub state. Hard-stop if the official extension or server-side stack feature is unavailable; do not fall back to manually merging and retargeting PRs one at a time. GitHub stacks require every head branch to live in the same repository, so hard-stop on a cross-fork chain.
 
 Use a clean dedicated worktree. Fetch current PR metadata and exact head OIDs rather than trusting branch names or an earlier report:
 
diff --git a/.agents/skills/dsh-translate-docs/SKILL.md b/.agents/skills/dsh-translate-docs/SKILL.md
index a3b95c59d1..e35096a5a2 100644
--- a/.agents/skills/dsh-translate-docs/SKILL.md
+++ b/.agents/skills/dsh-translate-docs/SKILL.md
@@ -19,7 +19,7 @@ Frozen Agent Notes under `.agents/notes/archived/` are not translation work. The
 
 ## The update path (briefing-driven)
 
-Benchmarked on real pair updates from this repo's history, the briefing-driven path costs a fraction of a guidance-corpus-loading run at equal measured quality; the [briefed-updates Agent Note](../../notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md) holds the evidence.
+The briefing-driven path matches guidance-corpus quality at a fraction of the cost; the [briefed-updates Agent Note](../../notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md) owns the benchmark evidence.
 
 1. **Generate the briefing**: `pnpm run gen-translation-brief <any file of the pair>` (no arguments briefs every out-of-sync pair). The briefing maps the change at the narrowest safely aligned granularity — changed Markdown units (paragraph, table row, list item, heading), then whole heading sections, then whole document — and contains the authored side's diff since the last confirmed-consistent state, each changed unit's last-confirmed source, current source, and current counterpart text (with line numbers), the terminology rows the change touches, first-occurrence movement notes, and a digest of the binding update rules.
 2. **Mechanical-only diff? `--apply` it.** When every change lies inside code fences that the pair shares byte-identically, the briefing says so; `pnpm run gen-translation-brief --apply <pair>` splices the edited fences into the counterpart and structure-validates the result before writing — no subagent, no hand-editing.
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index e6d8c2658f..d7df478074 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -80,7 +80,7 @@ For a large artifact, reduce `--max-width` first, then `--colors` or `--fps`; re
 
 Perform this step only when the task includes attaching the GIF to a pull request.
 
-Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. GIFs live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (existing branches: `code-mode-ui-assets`, `pr-613-assets`).
+Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. GIFs live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (named `<series>-assets`; list existing ones with `git ls-remote --heads origin '*assets*'`).
 
 Before either workflow below pushes, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact.
 
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 09e1bbe7fd..c1a70c77da 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -20,7 +20,7 @@ const PR_KINDS = new Set([
   'kind/cleanup',
   'kind/dependency',
 ])
-// Aliases removed by the unified taxonomy migration remain reserved so they cannot be recreated.
+// Retired label aliases stay reserved so they cannot be recreated.
 const LEGACY_LABELS = new Set([
   'kind/bug',
   'kind/documentation',
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d017fa14fb..3f67929e26 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -834,10 +834,9 @@ jobs:
   all-checks-passed:
     name: all checks passed
     # This bookkeeping-only verdict must not depend on custom-pool
-    # provisioning (master's #734 moved it to ubuntu-latest) — and under
-    # failover it follows the same selector as the worker jobs it
-    # aggregates, so a standard-hosted outage cannot strand the
-    # branch-protection verdict either (observed 2026-07-27).
+    # provisioning — and under failover it follows the same selector as the
+    # worker jobs it aggregates, so a standard-hosted outage cannot strand
+    # the branch-protection verdict either.
     runs-on: >-
       ${{ vars.DSH_CI_FAILOVER == 'selfhosted'
           && github.event.pull_request.user.login != 'dependabot[bot]'
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index c9b3dc18f1..b8e1910a00 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -64,11 +64,11 @@ describe('parseDshArgs', () => {
       .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
   })
 
-  it('rejects missing profile, removed flags, and contradictory inputs', () => {
+  it('rejects missing profile, flags outside the current grammar, and contradictory inputs', () => {
     expect(exitCode([])).toBe(1)
     expect(exitCode(['tui'])).toBe(1) // a bare word is a task without --profile
-    expect(exitCode(['--config', 'c.yml'])).toBe(1) // removed
-    expect(exitCode(['-p', 'task'])).toBe(1) // removed
+    expect(exitCode(['--config', 'c.yml'])).toBe(1) // outside the current grammar
+    expect(exitCode(['-p', 'task'])).toBe(1) // outside the current grammar
     expect(exitCode(['--profile', 'headless', 'task'])).toBe(1) // tasks belong to `run`
     expect(exitCode(['run'])).toBe(1)
     expect(exitCode(['run', ''])).toBe(1)
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index de44b110a1..0d2971ec62 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -174,7 +174,7 @@ function createEnvironmentProbeProfile(home: string, project: string): void {
 }
 
 describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)', () => {
-  it('requires --profile and rejects removed commands', async () => {
+  it('requires --profile and rejects inputs outside the current grammar', async () => {
     const bare = await runBuiltBin()
     expect(bare.code).toBe(1)
     expect(bare.stdout).toBe('')
@@ -185,8 +185,8 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     expect(help.stdout).toContain('dsh run "run the tests"')
     expect(help.stdout).toContain('dsh plugin --profile')
     expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
-    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
-      const result = await runBuiltBin(removed)
+    for (const outsideGrammar of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
+      const result = await runBuiltBin(outsideGrammar)
       expect(result.code).toBe(1)
     }
   }, 30_000)
@@ -297,9 +297,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
   }, 30_000)
 
   it('reports a patch-overlay boot failure without hanging', async () => {
-    // The HMR main watcher's initial scan once refreshed the include
-    // mid-initial-apply, deadlocking the failing apply's rollback against the
-    // refresh drain: dsh exited 13 with no diagnostic instead of settling
+    // An HMR main-watcher initial scan that refreshes the include
+    // mid-initial-apply deadlocks the failing apply's rollback against the
+    // refresh drain: dsh exits 13 with no diagnostic instead of settling
     // ([Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md)).
     const home = mkdtempSync(join(tmpdir(), 'dsh-invalid-patch-'))
     try {
diff --git a/apps/web/tests/approval-composer.e2e.ts b/apps/web/tests/approval-composer.e2e.ts
index 33259b6ed2..9911742633 100644
--- a/apps/web/tests/approval-composer.e2e.ts
+++ b/apps/web/tests/approval-composer.e2e.ts
@@ -9,8 +9,8 @@
 // model content as the question composer: the turn cannot complete without it).
 //
 // Geometry is the point of the scenario. The command is unbounded model text,
-// and before the cap a long one grew the card until the refuse/allow buttons
-// left the viewport — an approval the user could see and not answer.
+// and an uncapped card grows with it until the refuse/allow buttons leave the
+// viewport — an approval the user could see and not answer.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -36,8 +36,8 @@ const MODE = webSnapshotMode()
 
 // Irreducible payload: the command has to be long enough to pass the card's
 // height cap, which is the only shape that reproduces an action row pushed off
-// screen. Unrelated tokens, not a repeated word — a repeated word is what the
-// model compressed into `printf 'alpha %.0s' {1..400}` while recording, and a
+// screen. Unrelated tokens, not a repeated word — the model compresses a
+// repeated word into `printf 'alpha %.0s' {1..400}` when recording, and a
 // short command proves nothing here. The formula keeps the source small; the
 // model receives the expanded literal it has to put in the command.
 const TOKENS = Array.from({ length: 220 }, (_, index) => `tok${((index + 1) * 7919 % 99991).toString(36)}`).join(' ')
@@ -115,9 +115,8 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
       const snapshot = await captureStableAria(page, '[data-approval-key]', scaffold.workspaceCwd)
       await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-      // The regression this scenario exists for: an uncapped card grew with
-      // the command until the action row left the viewport. Measured at the
-      // lane baseline and at a short viewport, on the live panel.
+      // The uncapped-card hazard the header names, measured at the lane
+      // baseline and at a short viewport, on the live panel.
       const original = page.viewportSize() ?? { width: 1680, height: 1000 }
       for (const height of [1000, 700]) {
         await page.setViewportSize({ width: 900, height })
diff --git a/apps/web/tests/chat-long-interactions.e2e.ts b/apps/web/tests/chat-long-interactions.e2e.ts
index cd1fcb2fa7..ad9d6a6874 100644
--- a/apps/web/tests/chat-long-interactions.e2e.ts
+++ b/apps/web/tests/chat-long-interactions.e2e.ts
@@ -1,6 +1,7 @@
-// Long-history Chat behavior contract for a future virtualized renderer. Wheel
-// input only navigates to the semantic target; assertions pin content identity
-// and interaction routing rather than scroll geometry or mounted row counts.
+// Long-history Chat behavior contract that stays valid under a virtualized
+// renderer: wheel input only navigates to the semantic target; assertions pin
+// content identity and interaction routing rather than scroll geometry or
+// mounted row counts.
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
diff --git a/apps/web/tests/code-mode-round.e2e.ts b/apps/web/tests/code-mode-round.e2e.ts
index fd103ac53d..051700dc35 100644
--- a/apps/web/tests/code-mode-round.e2e.ts
+++ b/apps/web/tests/code-mode-round.e2e.ts
@@ -26,7 +26,7 @@ const MODE = webSnapshotMode()
 
 // The scenario's one drive prompt: elicits one program with a bash sub-call
 // and a failing read the program tolerates — the sub-row set the assertions
-// (and the PR gif) need. Never asserted against model prose.
+// need. Never asserted against model prose.
 const PROMPT = 'Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt '
   + 'catching its error in the program. Return an object with both outcomes. Then reply DONE and stop.'
 
@@ -104,7 +104,7 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-code-mode-rows'))
     await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1)
     // The parent run_code row wears the code variant with the model-authored
-    // description as its summary (the PR1 presentCall contract).
+    // description as its summary (the presentCall contract).
     const codeRow = page.locator('[data-variant="code"]').first()
     await codeRow.waitFor({ timeout: 10_000 })
     // Nested rows are visible WITHOUT any expand interaction, inside the
diff --git a/apps/web/tests/composer-draft-scroll.e2e.ts b/apps/web/tests/composer-draft-scroll.e2e.ts
index 5013d2638a..687419dc53 100644
--- a/apps/web/tests/composer-draft-scroll.e2e.ts
+++ b/apps/web/tests/composer-draft-scroll.e2e.ts
@@ -8,7 +8,7 @@
 // `[data-input-backdrop]` div underneath it, which also carries the claim-token
 // highlight, the chips and the ghost hint.
 //
-// Two layers can only stay together by moving together. They now do: both sit
+// Two layers can only stay together by moving together. They do: both sit
 // inside `[data-input-scroll]`, the composer's single scrolling box, and are as
 // tall as the whole draft — so one offset, applied by the browser, moves the
 // caret and the words in the same frame. Scrolling the textarea and assigning
@@ -192,7 +192,7 @@ function measureComposer(page: Page): Promise<ComposerMetrics> {
  * Absolute glyph coordinates are deliberately absent: they depend on font
  * metrics and would make the fixture fail on a machine that measures text
  * differently — a golden that needs re-recording per platform documents the
- * platform, not the change. What is recorded is the cap, the caret-to-glyph
+ * platform, not the behavior. What is recorded is the cap, the caret-to-glyph
  * relation, and which lines are on screen, each a comparison that survives any
  * layout keeping the coupling.
  * @param top - metrics with the draft scrolled to its start.
@@ -297,10 +297,10 @@ describe('web e2e: composer draft scrolling', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-wrap-width'))
     // A layer that breaks lines somewhere else puts the words under the wrong
     // caret, and an 8px difference is worth 2 to 5 lines on a wrap-sensitive
-    // draft. The three now share a containing block — the scrollport — so a
-    // scrollbar that consumes layout space costs them the same width; before,
-    // only the textarea scrolled, and WebKit reserved gutter space for it alone
-    // (768 against 776) while chromium and firefox did not.
+    // draft. All three share a containing block — the scrollport — so a
+    // scrollbar that consumes layout space costs them the same width; with
+    // only the textarea scrolling, WebKit reserves gutter space for it alone
+    // (768 against 776) while chromium and firefox do not.
     const metrics = await measureComposer(page)
     expect(metrics.backdropWrapWidth).toBe(metrics.inputWrapWidth)
     // The mirror decides the box height, so it belongs in the same equality —
@@ -315,7 +315,7 @@ describe('web e2e: composer draft scrolling', () => {
     // The reported symptom, isolated. A scroll offset changes and the caret's
     // distance to its own glyphs is re-read before the task ends — before any
     // `scroll` listener could have run. With the layers on one scrollport the
-    // browser moved both, so the distance is unchanged; with the glyph layer
+    // browser moves both, so the distance is unchanged; with the glyph layer
     // catching up in a listener it is off by the whole delta until a later
     // frame, which is a caret flying away from its text mid-gesture.
     const metrics = await measureComposer(page)
@@ -348,9 +348,10 @@ describe('web e2e: composer draft scrolling', () => {
   it('typing at the end of a scrolled draft brings the caret back into view', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-edit'))
     // The other way the box moves, and the one that depends on the browser: the
-    // textarea no longer scrolls, so revealing the caret after an edit is a
-    // scroll-into-view that has to walk up to the scrollport. Scroll away from
-    // the caret first, so the edit has somewhere to bring it back from.
+    // textarea holds no scroll offset of its own, so revealing the caret after
+    // an edit is a scroll-into-view that has to walk up to the scrollport.
+    // Scroll away from the caret first, so the edit has somewhere to bring it
+    // back from.
     const input = page.locator('textarea:enabled').first()
     await input.press('End')
     await input.hover()
@@ -368,9 +369,9 @@ describe('web e2e: composer draft scrolling', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-paste'))
     // The composer suppresses the native paste — the machine owns the draft and
     // the undo log — and restores the caret programmatically, which reveals
-    // nothing on its own: measured in chromium and WebKit, the view stayed
-    // where it was while the caret sat at the end of the pasted block. The
-    // restore now scrolls it into view, and this is the case that proves it.
+    // nothing on its own: in chromium and WebKit the view stays put while the
+    // caret sits at the end of the pasted block, so the restore scrolls it
+    // into view; this case pins it.
     const input = page.locator('textarea:enabled').first()
     await input.fill('one short line')
     await input.press('End')
diff --git a/apps/web/tests/composer-tab-geometry.e2e.ts b/apps/web/tests/composer-tab-geometry.e2e.ts
index c6b51b02bc..26077f6eab 100644
--- a/apps/web/tests/composer-tab-geometry.e2e.ts
+++ b/apps/web/tests/composer-tab-geometry.e2e.ts
@@ -11,12 +11,12 @@
 // gets an absolutely positioned seat instead, laid out against the padding box,
 // which the scrollbar never reduces.
 //
-// So the two tabs disagreed by exactly the bar's width for as long as the
-// transcript overflowed: the card jumped sideways on every tab switch, and
-// inside Chat alone at the moment a growing transcript started to scroll. The
-// column now reserves the gutter unconditionally (`scrollbar-gutter: stable`)
-// and states the overlay branch as a scroll container on the same axes, so both
-// edges are the same edge.
+// Without a shared reservation the two tabs disagree by exactly the bar's
+// width for as long as the transcript overflows: the card jumps sideways on
+// every tab switch, and inside Chat alone at the moment a growing transcript
+// starts to scroll. The column reserves the gutter unconditionally
+// (`scrollbar-gutter: stable`) and states the overlay branch as a scroll
+// container on the same axes, so both edges are the same edge.
 //
 // Only a real engine can show this. The seat's geometry is layout: jsdom gives
 // every element a zero-sized box and reports no scrollbar at all, so a unit spec
@@ -26,14 +26,14 @@
 //
 // The browser is launched WITHOUT Playwright's default `--hide-scrollbars`,
 // which is load-bearing rather than incidental. Under that argument a scroll
-// container's bar consumes no layout width at all, so the two tabs agree before
-// this change as much as after it and every comparison below holds vacuously —
-// measured: the pre-fix cascade leaves both tabs' bands at 0 there, against 8
-// and 0 with the argument dropped. Dropping it is also the faithful
+// container's bar consumes no layout width at all, so the two tabs agree with
+// and without the reservation and every comparison below holds vacuously —
+// measured: the unreserved cascade leaves both tabs' bands at 0 there, against
+// 8 and 0 with the argument dropped. Dropping it is also the faithful
 // configuration: ui-theme's scrollbar.css gives `::-webkit-scrollbar` a width,
 // and a bar that occupies layout space is what the product actually draws.
 //
-// The scenario runs that pre-fix cascade in the page — `scrollbar-gutter: auto`
+// The scenario runs that unreserved cascade in the page — `scrollbar-gutter: auto`
 // on the scroller, `overflow: hidden` on the overlay branch — and measures the
 // same two tabs through it, which is what keeps the equal rectangles above from
 // being explained by a tab switch that never reached the layout. It is the
@@ -64,7 +64,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/composer-tab-geometry',
  * that has to be re-recorded per platform. What is recorded is the distance
  * between the two tabs' rectangles, which is zero when the reservation holds and
  * the bar's width when it does not — including under the control, so the golden
- * carries the difference the fix removes rather than only its absence.
+ * carries the shift the unreserved cascade produces rather than only its absence.
  */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
@@ -114,10 +114,10 @@ async function setMeasuredViewport(
 }
 
 /**
- * The pre-fix cascade, injected into the page: the reservation dropped and the
- * overlay branch back to a hidden box. `!important` beats the module rules
- * without a rebuild, and the id lets the control be lifted again in the same
- * session.
+ * The unreserved cascade, injected into the page: the reservation dropped and
+ * the overlay branch forced to a hidden box. `!important` beats the module
+ * rules without a rebuild, and the id lets the control be lifted again in the
+ * same session.
  */
 const CONTROL_STYLE_ID = 'composer-tab-geometry-control'
 const CONTROL_CSS = `
@@ -221,9 +221,9 @@ async function compareTabs(page: Page): Promise<TabComparison> {
 }
 
 /**
- * Run the pre-fix cascade in the page for one measurement, then lift it.
+ * Run the unreserved cascade in the page for one measurement, then lift it.
  * @param page - the page under test.
- * @returns the comparison as the column laid out before this change.
+ * @returns the comparison as the column lays out without the reservation.
  */
 async function compareTabsWithoutReservation(page: Page): Promise<TabComparison> {
   await page.evaluate(({ id, css }) => {
@@ -328,7 +328,7 @@ describe('web e2e: input card position across view tabs', () => {
     await expect.poll(async () => (await measureTab(page)).scrolls, { timeout: 10_000 }).toBe(true)
     const comparison = await compareTabs(page)
     expect(comparison.chat.band).toBeGreaterThan(0)
-    // The reservation reaches both states, which is the whole change: the same
+    // The reservation reaches both states, which is the whole point: the same
     // band, on a box that scrolls and on one that only holds a view.
     expect(comparison.chat.gutter).toBe('stable')
     expect(comparison.trajectory.gutter).toBe('stable')
@@ -348,8 +348,8 @@ describe('web e2e: input card position across view tabs', () => {
     await setMeasuredViewport(page, WIDE_VIEWPORT, false)
     const comparison = await compareTabs(page)
     // The reported symptom as a number. At this viewport the card sits at its
-    // width cap, so the pre-fix shift showed up as a centring difference — half
-    // the band on each edge — rather than as a width change.
+    // width cap, so the unreserved cascade's shift shows up as a centring
+    // difference — half the band on each edge — rather than as a width change.
     expect(comparison.leftShift).toBe(0)
     expect(comparison.rightShift).toBe(0)
     expect(comparison.widthShift).toBe(0)
@@ -363,7 +363,7 @@ describe('web e2e: input card position across view tabs', () => {
     await setMeasuredViewport(page, NARROW_VIEWPORT, true)
     const comparison = await compareTabs(page)
     // The other geometry, and a different failure: below the cap the card takes
-    // the column's width, so an unreserved gutter changed its WIDTH by the whole
+    // the column's width, so an unreserved gutter changes its WIDTH by the whole
     // band instead of shifting it by half. Asserted against the capped
     // measurement rather than against the cap's pixel value, which belongs to
     // the stylesheet.
@@ -379,17 +379,17 @@ describe('web e2e: input card position across view tabs', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-tab-geometry-control'))
     await setMeasuredViewport(page, WIDE_VIEWPORT, false)
     // The control: without it, equal rectangles could also mean the tab switch
-    // never reached the layout. Under the pre-fix cascade the Chat scroller keeps
-    // its bar and the Trajectory branch goes back to a hidden box with none, and
-    // the card moves by half the band on each edge.
+    // never reached the layout. Under the unreserved cascade the Chat scroller
+    // keeps its bar and the Trajectory branch becomes a hidden box with none,
+    // and the card moves by half the band on each edge.
     const comparison = await compareTabsWithoutReservation(page)
     expect(comparison.chat.gutter).toBe('auto')
     expect(comparison.chat.band).toBeGreaterThan(0)
     expect(comparison.trajectory.band).toBe(0)
     expect(comparison.leftShift).toBe(comparison.chat.band / 2)
     expect(comparison.rightShift).toBe(comparison.chat.band / 2)
-    // Restoring the sheet restores the fix, so the control cannot leak into the
-    // remaining measurements.
+    // Restoring the sheet restores the reservation, so the control cannot leak
+    // into the remaining measurements.
     const restored = await compareTabs(page)
     expect(restored.leftShift).toBe(0)
     expect(tripwire.pageErrors).toEqual([])
diff --git a/apps/web/tests/conversation-column-overflow.e2e.ts b/apps/web/tests/conversation-column-overflow.e2e.ts
index 97e1fd1fa2..fc51e0da34 100644
--- a/apps/web/tests/conversation-column-overflow.e2e.ts
+++ b/apps/web/tests/conversation-column-overflow.e2e.ts
@@ -1,15 +1,15 @@
 // Web e2e scenario: the conversation column scrolls on one axis only, as the
-// browser actually lays it out. The reported symptom was a horizontal
-// scrollbar under the whole center column once the window (or the sidebar
-// drag) narrowed it — the hero's decorative backdrop ellipse bleeding past the
-// column and becoming user-scrollable.
+// browser actually lays it out. The hazard: a horizontal scrollbar appears
+// under the whole center column once the window (or the sidebar drag) narrows
+// it — the hero's decorative backdrop ellipse bleeds past the column and
+// becomes user-scrollable.
 //
 // The bleed is by construction and stays: `.heroGlow` is sized 1051/776 of the
 // hero box (ConversationRoot.module.css) so the blur scales with the input
-// card. What changed is the scroll container: `[data-conversation-scroll]`
-// scrolls vertically, and a box that scrolls in one axis computes the other
-// axis's initial `visible` to `auto`, so the bleed came back as a bar. The
-// fix states `overflow-x: hidden` there.
+// card. The scroll container is where the bar comes from:
+// `[data-conversation-scroll]` scrolls vertically, and a one-axis scroller
+// computes the other axis's initial `visible` to `auto`, so the bleed becomes
+// a bar; `overflow-x: hidden` on the scroller prevents it.
 //
 // Only a real engine reports that pair — the bleed and the resulting scroll
 // range — so the scenario sweeps viewport widths that bracket the glow's
@@ -36,7 +36,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/conversation-column-over
  * Committed golden of the one-axis relation at every stop. It records
  * relations and booleans, never absolute coordinates: the column width follows
  * the viewport and the sidebar, and a golden carrying pixels would document the
- * platform instead of the change.
+ * platform instead of the behavior.
  */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
@@ -60,17 +60,20 @@ interface ColumnMetrics {
   columnWidth: number
   /** Resolved `overflow-x` on the conversation scroll container. */
   overflowX: string
-  /** True when the glow's box reaches past the column's content edge — the condition the fix has to survive. */
+  /**
+   * True when the glow's box reaches past the column's content edge — the
+   * condition the `overflow-x: hidden` declaration has to survive.
+   */
   glowBleeds: boolean
   /**
    * `scrollWidth - clientWidth`. Deliberately NOT the assertion: `hidden` and
    * `auto` both report the same value, because `hidden` clips the bleed rather
    * than reflowing it away. Recorded because it is the vacuity guard in
    * numbers — it must stay positive at the narrow stops, or the scenario has
-   * stopped reproducing the situation the fix is for.
+   * stopped reproducing the situation `overflow-x: hidden` exists for.
    */
   bleedRange: number
-  /** True when the column still scrolls vertically — the axis the fix must not take away. */
+  /** True when the column still scrolls vertically — the axis `overflow-x: hidden` must not take away. */
   scrollsVertically: boolean
 }
 
@@ -108,9 +111,10 @@ function measureColumn(page: Page, width: number): Promise<ColumnMetrics> {
  * This is the one signal that separates the two states, and it is why the
  * scenario needs a real engine: `overflow-x: hidden` leaves the box
  * programmatically scrollable and leaves `scrollWidth` untouched, so every
- * property reading agrees across the fix. Only refusing an actual input event
- * differs — measured at the 1200px stop, the shipped column stays at 0 while
- * the same page with `overflow-x: auto` forced on lands at its scroll boundary.
+ * property reading agrees across the two overflow modes. Only refusing an
+ * actual input event differs — measured at the 1200px stop, the shipped
+ * column stays at 0 while the same page with `overflow-x: auto` forced on
+ * lands at its scroll boundary.
  * @param page - the page under test.
  * @returns `scrollLeft` after one horizontal wheel over the column.
  */
@@ -175,10 +179,10 @@ type ColumnStop = ColumnMetrics & {
  * Render the golden body: one line per stop, relations only.
  *
  * Absolute pixels are deliberately absent apart from `scrollLeftAfterWheel`,
- * which the fix pins to 0 by construction. The bleed is recorded as a boolean
- * rather than its width, so the golden survives any platform whose column
- * lands a pixel off — a fixture that has to be re-recorded per platform
- * documents the platform, not the change.
+ * which the shipped overflow mode pins to 0 by construction. The bleed is
+ * recorded as a boolean rather than its width, so the golden survives any
+ * platform whose column lands a pixel off — a fixture that has to be
+ * re-recorded per platform documents the platform, not the behavior.
  * @param stops - the measured stops, in sweep order.
  * @returns the golden body, without a trailing newline.
  */
@@ -272,18 +276,19 @@ describe('web e2e: the conversation column scrolls on one axis', () => {
       // The reported symptom, stated directly: a horizontal wheel over the
       // column moves nothing, at every stop.
       expect(stop.scrollLeftAfterWheel, `viewport ${String(stop.width)}`).toBe(0)
-      // The axis the column is a scroller for must survive the fix.
+      // The axis the column is a scroller for must survive `overflow-x: hidden`.
       expect(stop.scrollsVertically, `viewport ${String(stop.width)}`).toBe(true)
     }
     expect(tripwire.pageErrors).toEqual([])
   }, 120_000)
 
-  it('reports the pre-fix state when the axis is opened back up', async () => {
+  it('scrolls horizontally again once the axis is opened back up (control)', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-control'))
     // The mutation control, run in the page rather than against a second
-    // build: it restores exactly what the fix changed — the initial `visible`
-    // that a one-axis scroller computes to `auto` — and shows the same gesture,
-    // at the same timing, carrying the column to its positive scroll boundary.
+    // build: it lifts exactly the `overflow-x: hidden` declaration, so the
+    // initial `visible` that a one-axis scroller computes to `auto` takes
+    // over, and shows the same gesture, at the same timing, carrying the
+    // column to its positive scroll boundary.
     // Without it a `scrollLeft` of 0 could equally mean the wheel never arrived.
     // Injected with an id rather than through `addStyleTag`, so the teardown
     // below can take the sheet out again by selector: it must not outlive this
diff --git a/apps/web/tests/default-model.overlay.yml b/apps/web/tests/default-model.overlay.yml
index 5ec0e77405..654c343bb9 100644
--- a/apps/web/tests/default-model.overlay.yml
+++ b/apps/web/tests/default-model.overlay.yml
@@ -1,6 +1,6 @@
 # The fixture-less web scaffold registers no adapter, so the shipped
 # deepseek-official default would be a route nothing serves — which the
-# composer now correctly refuses to type into. This scenario declares its own
+# composer refuses to type into. This scenario declares its own
 # pi-ai routes and starts the default on one of them.
 - id: agent-default-model
   config:
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 5f2173248e..0c7dd36fe3 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -6,9 +6,10 @@
 // client; THIS spec pins the same flow through HTTP RPC + SSE + the host
 // gateway), reload replays everything from the log (zero further model
 // calls), and the theme scenario proves the shipped dark palette actually
-// cascades: attribute -> alias token flip -> painted surface change. Per the
-// lane's scope ruling there is no theme/layout golden (aria is color-blind);
-// the hero's waiting state gets the one golden here.
+// cascades: attribute -> alias token flip -> painted surface change. No
+// theme/layout golden: aria snapshots are color-blind (lane scope: the
+// browser-e2e-lane Agent Note); the hero's waiting state gets the one golden
+// here.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -112,8 +113,8 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
       const planButton = activePage.getByRole('button', { name: 'Plan mode on, press to turn off' })
       await planButton.waitFor({ timeout: 10_000 })
       // The golden encodes an empty composer, and the button arriving does not
-      // mean the submitted text is gone yet: under load the capture caught a
-      // textbox still holding `/plan`.
+      // mean the submitted text is gone yet: under load the capture can catch
+      // a textbox still holding `/plan`.
       await expect.poll(() => input.inputValue(), { timeout: 10_000 }).toBe('')
       const planSnapshot = await captureStableAria(activePage, '[class*="frame"]', activeScaffold.workspaceCwd)
       await compareOrRefreshGolden(PLAN_ACTIVE_EXPECTED, planSnapshot, MODE)
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 53d5ef4982..364b00f9e5 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -85,8 +85,9 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     const key = dialog.getByLabel('API 密钥')
     const save = dialog.getByRole('button', { name: '保存', exact: true })
 
-    // The paste that used to save cleanly and then fail the first turn with a
-    // ByteString TypeError now names the field that holds it.
+    // A key no HTTP header can carry would save cleanly and fail the first
+    // turn with a ByteString TypeError; the form names the offending field
+    // instead.
     await key.fill('sk-\u{1F600}minimax')
     await dialog.getByText('该 API 密钥格式错误，请检查。').waitFor({ timeout: 10_000 })
     await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(false)
diff --git a/apps/web/tests/navigation-panes.e2e.ts b/apps/web/tests/navigation-panes.e2e.ts
index a49501584f..cc6d007d82 100644
--- a/apps/web/tests/navigation-panes.e2e.ts
+++ b/apps/web/tests/navigation-panes.e2e.ts
@@ -331,7 +331,7 @@ describe('web e2e: navigation & panes over a rich seeded session', () => {
     // Real layout, not jsdom's stub (which computes no geometry at all):
     // squeeze the output pane below its content width and the line must keep
     // its single row and overflow sideways instead of folding. Soft-wrapping
-    // here is what shredded the column alignment this card exists to hold.
+    // here shreds the column alignment this card exists to hold.
     const layout = await card.locator('[class*="_output_"]').first().evaluate((node) => {
       const pane = node as HTMLElement
       const row = pane.querySelector<HTMLElement>('[class*="_line_"]')
diff --git a/apps/web/tests/pin-browse-picker.overlay.yml b/apps/web/tests/pin-browse-picker.overlay.yml
index d48dfa3538..c6bf121b69 100644
--- a/apps/web/tests/pin-browse-picker.overlay.yml
+++ b/apps/web/tests/pin-browse-picker.overlay.yml
@@ -1,4 +1,4 @@
-# Loader overlay for the W5 real-host smoke (`dsh web --patch`): pin the
+# Loader overlay for the real-host smoke (`dsh web --patch`): pin the
 # in-browser directory picker. The shipped row is `-auto`, which resolves to
 # the native OS chooser on a loopback bind with a local display — an
 # interaction a Playwright page cannot drive, so the resolved backend would
diff --git a/apps/web/tests/pwsh-terminal.e2e.ts b/apps/web/tests/pwsh-terminal.e2e.ts
index 26f6a8319e..e1b92ed2e3 100644
--- a/apps/web/tests/pwsh-terminal.e2e.ts
+++ b/apps/web/tests/pwsh-terminal.e2e.ts
@@ -2,8 +2,8 @@
 // whose pwsh call/result is presented by the REAL tool-pwsh on replay (the
 // api-proxy recomputes presentation views from logged args/result content)
 // must render as a bash-shaped terminal card with the parsed exit-status
-// pill — not the generic console-fenced card the pwsh presenter used to
-// emit. The seed is authored, not recorded: its header line carries no `cwd`
+// pill — not a generic console-fenced card. The seed is authored, not
+// recorded: its header line carries no `cwd`
 // field (seedSession writes the session cwd itself, and a Windows temp path
 // substituted into the header would not round-trip through its JSON parse),
 // and no event references the workspace, so the lane replays on any host
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 31a638c12e..4a922b9353 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -437,7 +437,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     } else if (mode !== 'record' && options.deepSeekMissingCredential !== true) {
       // No fixture and no shipped adapter would leave the tree with ZERO
       // provider routes — a state no product composition has, and one the
-      // composer now correctly refuses to type into. Register the same routes
+      // composer refuses to type into. Register the same routes
       // a fixture would, with streaming that still fails loud: the scenario
       // issues no model calls, and one that slipped in must not pass quietly.
       ctx.effect(() => ctx.llm.registerAdapter(
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 8a9ee26866..14de0e8d8f 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -274,8 +274,8 @@ describe('web e2e: seeded history renders through cold resume', () => {
     const toolRows = page.locator('[data-variant], [data-sample]')
     await expect.poll(() => toolRows.count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(2)
     expect(await page.getByText('a.txt', { exact: false }).count()).toBeGreaterThan(0)
-    // The bug this fixes: the compaction shadowed the whole recorded surface on
-    // the model side, and the prompt and full tool output are still on screen.
+    // The pinned hazard: compaction shadows the surface on the model side
+    // only — the prompt and full tool output must stay on screen.
     expect(await page.getByText(PROMPT, { exact: true }).count()).toBe(1)
 
     const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))
diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts
index e6b10664af..c49b1ecc1f 100644
--- a/apps/web/tests/settings-chrome.e2e.ts
+++ b/apps/web/tests/settings-chrome.e2e.ts
@@ -270,7 +270,7 @@ describe('web e2e: settings modal and General preferences', () => {
     await selector.click()
     await page.getByRole('menuitem', { name: 'English' }).click()
     // The settings-owned copy re-registers localized: dialog title, nav,
-    // Appearance labels. (Only the settings namespaces are localized today —
+    // Appearance labels. (Only the settings namespaces are localized —
     // the rest of the app's copy is intentionally out of this row's scope.)
     const enDialog = page.getByRole('dialog', { name: 'Settings' })
     await enDialog.waitFor({ timeout: 10_000 })
diff --git a/apps/web/tests/sidebar-scrollbar.e2e.ts b/apps/web/tests/sidebar-scrollbar.e2e.ts
index 095e667c61..d5afd925a3 100644
--- a/apps/web/tests/sidebar-scrollbar.e2e.ts
+++ b/apps/web/tests/sidebar-scrollbar.e2e.ts
@@ -1,5 +1,5 @@
 // Web e2e scenario: the sidebar session list's scrollbar as the browser
-// actually lays it out — the observable half of the themed-scrollbar change
+// actually lays it out — the observable half of the themed scrollbars
 // (packages/client/ui-theme/src/styles/scrollbar.css plus the
 // `scrollbar-gutter: stable` reservation on WorkspaceBrowser's `.list`). The
 // ui-theme/ui-workspace unit specs read the CSS text; only a real engine
@@ -17,8 +17,8 @@
 // Headless chromium defaults to an OVERLAY scrollbar: one drawn on top of the
 // content, consuming no layout width unless something reserves space. That is
 // the mode in which the reported symptom exists at all, so this environment
-// reproduces it rather than merely approximating it — measured against clean
-// master, where the list's band is 0 and the bar covers 7px of the relative
+// reproduces it rather than merely approximating it — without either
+// declaration the list's band is 0 and the bar covers 7px of the relative
 // time. (Under a classic space-consuming bar, `clientWidth` already excludes
 // the bar and nothing can be covered; a headed run under xvfb behaves that way
 // and cannot show the symptom.)
@@ -40,9 +40,8 @@
 // neither replaces the other. Removing only the gutter leaves `timeCoveredBy` at
 // 0, because the bar is then 8px wide and the row's right padding is also 8px,
 // so it abuts the timestamp without covering it; `band` catches that case.
-// Removing both — the actual master state — is what produces the reported
-// overlap, and `timeCoveredBy` measures it at 7. Each was mutation-checked with
-// the other assertions in its test silenced.
+// Removing both is what produces the reported overlap, and `timeCoveredBy`
+// measures it at 7.
 //
 // The thumb is a pointer affordance (ui-sidebar rebinds the indirection pair
 // to `transparent` while the pointer is outside the column), so every
@@ -135,7 +134,8 @@ interface ListMetrics {
 /**
  * Measure the sidebar list in the page.
  * @param page - the page under test.
- * @returns the list's resolved scrollbar style and the geometry the fix changes.
+ * @returns the list's resolved scrollbar style and the geometry the
+ * scrollbar-gutter/thin-scrollbar declarations shape.
  */
 function measureList(page: Page): Promise<ListMetrics> {
   return page.evaluate(() => {
@@ -201,8 +201,8 @@ function measureList(page: Page): Promise<ListMetrics> {
       // The bar is drawn in the rightmost `barWidth` of the border box, whether
       // or not that space was reserved. Its width comes from the sheet where the
       // sheet applies, and from the UA's own overlay bar otherwise — 15px is
-      // what this chromium paints, measured against master where the rule is
-      // absent. Taking the UA width as the fallback is what keeps the assertion
+      // what this chromium paints, measured with the rule absent. Taking the
+      // UA width as the fallback is what keeps the assertion
       // honest: assuming 0 there would report no occlusion precisely in the
       // state that has it.
       timeCoveredBy: Math.max(0, time.getBoundingClientRect().right - (listRect.right - barWidth)),
@@ -261,13 +261,14 @@ async function measurePalette(page: Page): Promise<PaletteMetrics> {
 
 /**
  * Render the golden body: the resolved scrollbar style of the list in each
- * palette, plus the geometric relations the fix establishes.
+ * palette, plus the geometric relations the scrollbar-gutter/thin-scrollbar
+ * declarations establish.
  *
  * Absolute coordinates are deliberately absent. `timeRight`, `clientRight`, and
  * `borderRight` depend on the sidebar's laid-out width and on font metrics, so
  * committing them would make the golden fail on a machine whose fonts measure
  * differently — a fixture that has to be re-recorded per platform documents the
- * platform, not the change. What is recorded instead is the band, the overlap,
+ * platform, not the behavior. What is recorded instead is the band, the overlap,
  * and the two orderings, each of which is a difference or a comparison and so
  * survives any layout that keeps the reservation.
  * @param light - metrics measured under the light palette.
@@ -417,12 +418,13 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(metrics.scrollbarEdgeOffset).toBe(2)
     expect(metrics.rowEdgeInset).toBe(12)
     // The reported symptom, stated directly: no part of the row's relative time
-    // lies under the bar. Measures 7 on clean master — the `h` of `1h` is the
-    // covered part. Unlike the client-edge comparison below it does not go
-    // vacuous under an overlay scrollbar, because it measures against the bar's
-    // own width rather than against a content edge the overlay bar does not
-    // move. It is not a replacement for the band assertion above; see the file
-    // header for which regression each one catches.
+    // lies under the bar. Without either declaration it measures 7 — the `h`
+    // of `1h` is the covered part. Unlike the client-edge comparison below it
+    // does not go vacuous under an overlay scrollbar, because it measures
+    // against the bar's own width rather than against a content edge the
+    // overlay bar does not move. It is not a replacement for the band
+    // assertion above; see the file header for which regression each one
+    // catches.
     expect(metrics.timeCoveredBy).toBe(0)
     // Corollaries of the reservation, kept because they pin where the band sits
     // rather than only that it exists: the time ends inside the content area,
@@ -451,7 +453,7 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(quiet.band).toBeGreaterThan(0)
     expect(quiet.timeCoveredBy).toBe(0)
     // Scrolling without a pointer — what a keyboard or a touch drag does —
-    // leaves the column quiet. This is the change's one deliberate loss, and
+    // leaves the column quiet. This is the one deliberate loss, and
     // it is pinned here rather than only described, so making a scroll
     // re-reveal the bar has to be a decision rather than a side effect.
     await page.locator('[role="tree"][aria-label="Sessions"]').evaluate((el) => { el.scrollTop += 200 })
diff --git a/apps/web/tests/smoke-real.e2e.ts b/apps/web/tests/smoke-real.e2e.ts
index f32daebfe4..b0acf074b4 100644
--- a/apps/web/tests/smoke-real.e2e.ts
+++ b/apps/web/tests/smoke-real.e2e.ts
@@ -1,4 +1,4 @@
-// W5 real-host smoke: spawn `dsh web` with a real key, walk the full W5 flow
+// Real-host smoke: spawn `dsh web` with a real key, walk the full flow
 // list in a real chromium, screenshot every screen into .artifacts/ for the
 // figma comparison pass. Self-skips without DEEPSEEK_API_KEY (repo e2e
 // convention); vitest.web.config.ts loads the repo-root .env before this file
@@ -11,8 +11,9 @@
 // (frame/handle) rides local names that survive hashing as suffixes; prefer
 // data-* for anything new.
 //
-// Flow order matters: chat rounds first (5 depends on 3's session), geometry
-// and theme after, reload recovery last. Tests run sequentially in-file.
+// Flow order matters: chat rounds first (the bash round reuses the first
+// send's session), geometry and theme after, reload recovery last. Tests run
+// sequentially in-file.
 import type { ChildProcess } from 'node:child_process'
 import { spawn } from 'node:child_process'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
@@ -119,7 +120,7 @@ async function waitForAssistantMarker(baseUrl: string, sessionId: string, marker
   }).toBe(true)
 }
 
-/** W5 screenshot: evidence for the figma comparison, not a failure artifact. */
+/** Real-host smoke screenshot: evidence for the figma comparison, not a failure artifact. */
 async function screen(page: Page, name: string): Promise<void> {
   await page.screenshot({ path: join(REPO_ROOT, '.artifacts', `w5-${name}.png`) })
 }
@@ -465,7 +466,7 @@ describe('dsh web keyless CLI smoke', () => {
   })
 })
 
-describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key, W5)', () => {
+describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key)', () => {
   let child: ChildProcess
   let sessionsDir: string
   let baseUrl: string
@@ -518,7 +519,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     if (sessionsDir !== undefined) rmSync(sessionsDir, { recursive: true, force: true })
   })
 
-  it('1 cold start: loading page settles into the three-column frame', async () => {
+  it('cold start: loading page settles into the three-column frame', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-cold-start'))
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
     expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
@@ -527,7 +528,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '01-cold-start')
   })
 
-  it('2+3 empty-state first send completes a real model round', async () => {
+  it('empty-state first send completes a real model round', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-first-round'))
     // This scenario spawns its own server against a fresh $DSH_HOME, so the
     // first-run welcome notice is unacknowledged and its overlay owns pointer
@@ -590,7 +591,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '07-back-to-chat')
   })
 
-  it('5 bash differential rendering: tool row click leaves the default details column closed', async () => {
+  it('bash differential rendering: tool row click leaves the default details column closed', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-tool-details'))
     const input = page.locator('textarea').first()
     await input.fill('请用 bash 工具运行命令 echo w5marker 然后告诉我结果')
@@ -604,12 +605,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '08-bash-round')
     expect(await detailsTrack(page)).toBe(0)
     await toolRow.click()
-    // Tool rows no longer drive layout.openDetails; the default column stays closed.
+    // Tool rows do not drive layout.openDetails; the default column stays closed.
     expect(await detailsTrack(page)).toBe(0)
     await screen(page, '09-details-closed')
   }, 150_000)
 
-  it('6 sidebar drag widens the column and resets across reload', async () => {
+  it('sidebar drag widens the column and resets across reload', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-drag'))
     const before = await firstTrack(page)
     const handle = page.locator('[class*="handle"]').first()
@@ -627,10 +628,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     expect(await firstTrack(page)).toBe(before)
   })
 
-  it('7 dark mode: the body attribute cascades the token sheets', async () => {
+  it('dark mode: the body attribute cascades the token sheets', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-dark'))
-    // theme.apply === toggling this attribute (v3 §8); no switcher UI owns it
-    // in P-I, so the acceptance drives the documented mechanism directly.
+    // The body attribute is the documented cascade mechanism; the Settings
+    // gesture is owned by settings-chrome.e2e.ts — drive the attribute
+    // directly here.
     const dark = await page.evaluate(() => {
       document.body.setAttribute('data-ds-dark-theme', '')
       return getComputedStyle(document.body).backgroundColor
@@ -643,7 +645,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     expect(dark).not.toBe(light)
   })
 
-  it('8 reload recovery: history replays after a fresh boot', async () => {
+  it('reload recovery: history replays after a fresh boot', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-reload'))
     await page.reload({ waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts
index 21ad64e4ed..bf5f920458 100644
--- a/apps/web/tests/startup-auto-selection.e2e.ts
+++ b/apps/web/tests/startup-auto-selection.e2e.ts
@@ -3,10 +3,10 @@
 // A page load with a workspace already registered runs
 // `WorkspacesService.startInitialSelection`: it connects the most recent
 // workspace and opens its blank session. `openState` flips to `loading` the
-// moment `open()` lands, which used to drive `data-phase=settling` on the
-// conversation root — `visibility:hidden` over the composer seat and the
-// header for the whole `session.history` round-trip, so the center column went
-// blank and repainted, reading as a full-page refresh on every launch.
+// moment `open()` lands; driving `data-phase=settling` on the conversation
+// root from that flip would hide the composer seat and the header
+// (`visibility:hidden`) for the whole `session.history` round-trip — the
+// center column blanks and repaints like a full-page refresh on every launch.
 //
 // The unit spec pins the phase condition over hand-built stores. What only the
 // assembled application can show is that the path a user actually takes
@@ -19,8 +19,9 @@
 // The round-trip against a loopback host is far too fast to observe, so this
 // scenario HOLDS the `session.history` response open at the browser's network
 // boundary and asserts the visible frame while it is in flight. That gate is
-// what makes the assertions non-vacuous: with the exemption reverted the held
-// window is exactly when `settling` is painted and the composer is hidden.
+// what makes the assertions non-vacuous: without the phase exemption, the
+// held window is exactly when `settling` would be painted and the composer
+// hidden.
 //
 // Zero model calls: registering a workspace and opening its blank session are
 // host RPCs with no model involvement. A stray stream would fail loud with
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index f289b062e3..810fe4bcf1 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -185,7 +185,8 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
-    // interrupt RPC itself needs no live parent — PR 1's host coverage).
+    // interrupt RPC itself needs no live parent — covered host-side by
+    // subagent-interrupt.e2e.ts).
     const pattern = '**/api/subagent.list'
     await page.route(pattern, async (route) => {
       const response = await route.fetch()
diff --git a/apps/web/tests/subagent-interrupt.e2e.ts b/apps/web/tests/subagent-interrupt.e2e.ts
index e1e35e7981..3e2bfe7f37 100644
--- a/apps/web/tests/subagent-interrupt.e2e.ts
+++ b/apps/web/tests/subagent-interrupt.e2e.ts
@@ -4,7 +4,7 @@
 // proves from the real session state that the turn aborted, the follow-up
 // parked without auto-starting a new turn, and a later waking send resumed the
 // preserved FIFO order. No browser: the RPC surface is the product surface
-// under test, and PR-stacked UI coverage owns the composer interaction.
+// under test, and subagent-interrupt-ui.e2e.ts owns the composer interaction.
 import { existsSync } from 'node:fs'
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
diff --git a/apps/web/tests/turn-tail-actions.e2e.ts b/apps/web/tests/turn-tail-actions.e2e.ts
index 235145ebcc..d68aef4700 100644
--- a/apps/web/tests/turn-tail-actions.e2e.ts
+++ b/apps/web/tests/turn-tail-actions.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: assistant IconActions belong to the settled answer, so
 // they arrive with `turn/end` and not before. The recorded turn narrates in
-// plain text before its tool call, which is the shape that used to hand the
+// plain text before its tool call, which is the shape that would hand the
 // footer to mid-turn narration for the seconds a tool runs and then move it
 // down. A `hang` sidecar on the SECOND model call parks the turn after the
 // narration and the tool result are durable, so the running state is stable by
diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts
index a99336fd90..a8e238422b 100644
--- a/apps/web/tests/workspace-management.e2e.ts
+++ b/apps/web/tests/workspace-management.e2e.ts
@@ -91,8 +91,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     ).not.toBeUndefined()
     // First adoption births a blank Session+Agent whose workspace attach must
     // settle before a test may delete the registration; re-registration after
-    // a delete mints a fresh blank Session+Agent too (the old cwd-only reuse
-    // path is gone), so callers opt in only where a fresh attach is possible.
+    // a delete mints a fresh blank Session+Agent too (no cwd-based reuse
+    // exists), so callers opt in only where a fresh attach is possible.
     if (options.waitForAgent === true) {
       await expect.poll(() => scaffold.ctx.agents.list().length, { timeout: 10_000 })
         .toBeGreaterThan(agentsBefore)
@@ -254,7 +254,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     // a supported reversible flow. It creates a fresh Workspace id and does
     // NOT re-adopt the retained (non-blank) Session; the New Session flow
     // mints a fresh blank session and attaches it to the new registration
-    // (the old cwd-only blank reuse is gone, so the account is never empty).
+    // (no cwd-based blank reuse exists, so the account is never empty).
     await adoptDirectory(scaffold.workspaceCwd)
     await expect.poll(
       () => scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd),
@@ -482,7 +482,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     await expect.poll(() => page.getByText('Idle', { exact: true }).count(), { timeout: 5_000 }).toBeGreaterThanOrEqual(1)
     // The card is REACHABLE: it sits 8px off the row, so getting to it means
     // crossing ground that belongs to neither. Hovering it must not dismiss
-    // it — the regression this scenario guards.
+    // it — the hazard this scenario pins.
     const card = page.getByRole('button', { name: `Copy: ${rowTitle}` })
     await card.hover()
     await page.waitForTimeout(POINTER_HOLD_MS)
@@ -515,10 +515,10 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     const item = page.getByRole('menuitem', { name: 'Rename' })
     await item.waitFor({ timeout: 5_000 })
     // Into the list, then back up to the trigger across the 4px gap below it:
-    // that return trip used to fire the list's pointerleave and close the
-    // menu, so a hesitating pointer lost it. Order matters — clicking leaves
-    // the pointer ON the trigger, so entering the list has to come first for
-    // the return to be a real departure.
+    // without the gap-crossing grace, that return trip fires the list's
+    // pointerleave and closes the menu — a hesitating pointer loses it.
+    // Order matters — clicking leaves the pointer ON the trigger, so entering
+    // the list has to come first for the return to be a real departure.
     await item.hover()
     await page.waitForTimeout(POINTER_TRANSIT_MS)
     await trigger.hover()
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index c5a6e6cc11..ec34ec435a 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -73,10 +73,13 @@ const BOOT_GRAMMAR_FILES: readonly string[] = [
   'dist/json.mjs',
 ]
 
-/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces today). */
+/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces). */
 const FONT_EXTENSIONS: readonly string[] = ['.woff2', '.woff', '.ttf']
 
-/** npm package name of a resolved module id (the segment after the LAST `node_modules/` — pnpm nests the real package under an inner node_modules). */
+/**
+ * npm package name of a resolved module id (the segment after the LAST
+ * `node_modules/` — pnpm nests the real package under an inner node_modules).
+ */
 function npmPackageOf(id: string): string | undefined {
   const parts = id.split('/node_modules/')
   if (parts.length === 1) return undefined
@@ -94,7 +97,7 @@ export default defineConfig({
       output: {
         // Output layout: the two main chunks stay at assets/ root; lazy
         // @shikijs/langs grammar chunks group under assets/langs/; fonts
-        // (today all KaTeX faces referenced by vendor.css) group under
+        // (all KaTeX faces referenced by vendor.css) group under
         // assets/fonts/. Sourcemaps need no arrangement: rollup writes each
         // .map next to its js and references it by bare relative filename.
         chunkFileNames(chunk): string {
@@ -128,7 +131,8 @@ export default defineConfig({
     // for Node/type consumers, but the browser bundle must compile src directly
     // so CSS rides vite's pipeline instead of the CSS-externalized lib bundle.
     // Only the shell's normal-package surface is aliased — plugin packages are
-    // NEVER bundled here (web2 shell self-sufficiency); they arrive as runtime
+    // NEVER bundled here (shell self-sufficiency — see
+    // packages/client/web/README.md); they arrive as runtime
     // bundles through the client module system. Order matters — subpath
     // aliases must win over bare-name prefixes.
     alias: [
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index c395f05428..0d82ebdd37 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: 5c4f306957a65a92abe8f15159ab2d23e61ef501
+api-gateway.md: 1fdbe256afb7e870e953f05bd29923a4e1c7c22b
+api-gateway.zh.md: b9e18bf78bb5887725a5278e0b28efb86d17b944
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index e8aafc173d..1fdbe256af 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -75,7 +75,7 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client applications assemble only `@deepseek-ai/dsh-api-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions through `ctx.remote.$mount()`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the TypeRT Gateway or the business package's Remote JS separately.
 
-A future TUI can assemble the same React-independent `api-remotes` and `ctx.remote` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
+The `api-remotes` assembly and the `ctx.remote` contract are React-independent; the Host methods visible to any Client assembly are limited to the Remote methods selected at generation time.
 
 ## Component responsibilities
 
@@ -88,7 +88,7 @@ A future TUI can assemble the same React-independent `api-remotes` and `ctx.remo
 | Host | `@deepseek-ai/dsh-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, resolves objects or Contexts, invokes live Cordis services, and validates boundaries |
 | Client | `@deepseek-ai/dsh-api-gateway/client` | Provides `ctx.remote` and `remote.<namespace>` child Services, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
-| Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and current `/api` HTTP bridge |
+| Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and the `/api` HTTP bridge |
 
 The API Gateway package owns the Host dispatcher and Client Remote endpoint as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
 
@@ -118,7 +118,7 @@ Strict analysis requires a Remote to be a public, non-static instance method wit
 
 ## Runtime invocation
 
-Remote and API Proxy currently share the Connection's `/api` route; there is no separate `/api2` server or second Connection. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the current HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
+Remote and API Proxy share the Connection's `/api` route. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
 
 The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler in interceptor order. The TypeRT Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; unclaimed requests fall back to the existing API Proxy. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier in the future does not require changes to Remote descriptors or the Client programming interface.
 
@@ -165,6 +165,6 @@ The running Client watcher consumes these generated files when it rebundles. If
 
 Remote handles only unary method calls with one request and one result. Session event streams, pagination, incremental reduce, projection, and entity substreams require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
 
-The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and TypeRT RPC layers live under `packages/api`; Connection and WebServer remain at `packages/client/connection` and `packages/host/webserver`, with service contracts that permit a later package-only move to `packages/api`. The legacy API Proxy remains at `packages/host/apiproxy` as the fallback for endpoints not yet migrated to Remote.
+The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and TypeRT RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. The API Proxy at `packages/host/apiproxy` handles endpoints without Remote descriptors.
 
-Lookup policy is currently configured per key, so all `agent` or `session` parameters share the cold-resume behavior. If a Remote endpoint must accept live objects only, an explicit per-parameter or per-endpoint policy must be added later; the business method must not guess whether the object came from restoration.
+Lookup policy is configured per key, so all `agent` or `session` parameters share the cold-resume behavior. Accepting live objects only would require an explicit per-parameter or per-endpoint policy, which does not exist; the business method must not guess whether the object came from restoration.
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 5c4f306957..b9e18bf78b 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -75,7 +75,7 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 约定，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+`api-remotes` 装配与 `ctx.remote` 约定不依赖 React；任何 Client 装配能看到的 Host 方法都只限于生成时选择的 Remote 方法。
 
 ## 组件职责
 
@@ -88,7 +88,7 @@ Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导
 | Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
 | Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子 Service，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
-| 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
+| 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与 `/api` HTTP bridge |
 
 API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
 
@@ -118,7 +118,7 @@ Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则
 
 ## 运行时调用
 
-当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
+Remote 与 API Proxy 共用 Connection 的 `/api` 路由。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
 
 Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和 request cancellation，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程界面。
 
@@ -165,6 +165,6 @@ pnpm run build:lib
 
 Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务约定允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。位于 `packages/host/apiproxy` 的 API Proxy 处理没有 Remote 描述符的 endpoint。
 
-当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
+lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。只接受 live 对象需要显式的逐参数或逐 endpoint 策略，而这种策略并不存在；不能通过业务方法内部猜测对象是否来自恢复。
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index d61353210e..af9f8ba48e 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -417,7 +417,7 @@ flowchart LR
 | `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
-| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 7278447cf8..10f0761fc5 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -411,7 +411,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-e2b`
 
@@ -513,7 +513,7 @@ export interface Config {
    * Process-level: read once at load, a relative path resolves against the process
    * launch cwd, so one config applies to the whole process.
    * TODO(per-session-hook-config): per-session discovery of a project-local
-   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   * `hooks.json` from each `session/new.cwd`.
    */
   configPath: string
   /**
@@ -548,7 +548,7 @@ export interface Config {
    * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
    * path resolves against the process launch cwd.
    * TODO(per-session-hook-config): per-session project-local discovery from each
-   * `session/new.cwd` is not yet implemented.
+   * `session/new.cwd`.
    */
   configPath: string
   /** The model name stamped on every payload (Codex includes `model` on each event). */
@@ -846,8 +846,7 @@ type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
 
 /**
  * pi-ai thinking formats a profile cannot name: both drive the request through
- * `chatTemplateKwargs`, which this configuration does not expose, so offering
- * them would hand back a format with nothing to say.
+ * `chatTemplateKwargs`, which this configuration does not expose.
  */
 type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 ```
@@ -1689,7 +1688,7 @@ export interface Config {
   /**
    * How to auto-answer the child's `session/request_permission` prompts:
    * `reject` (default — decline every prompt) or `allow` (approve via the first
-   * allow-shaped option). The first cut surfaces no prompt to a human.
+   * allow-shaped option). No prompt is surfaced to a human.
    */
   permission: PermissionPolicy
   /**
@@ -2360,8 +2359,7 @@ export interface Config {
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -2369,7 +2367,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-Source: [`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index 7eaa702a9d..6e83450ec3 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.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 docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 5d9312f2f5cf840100b12045bde1829b342e580d
-extension-cookbook.zh.md: 29bb57c558a0ff9413619d0bb2e8bb5e6b70da56
+extension-cookbook.md: aba220ec6dc3cf3d0f99edd0e47ffa6069499b47
+extension-cookbook.zh.md: 34e8fc0fa3d2d57136616d66cfb4f3f6de20605e
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 5d9312f2f5..aba220ec6d 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -105,7 +105,7 @@ Every product feature maps to a listener on a documented extension point — the
 | `/loop` | on the `turn/end` session event, `followup()` the next iteration; or force-continue |
 | Dynamic workflow | `ctx.workflows` + the worker-thread engine + the `workflow` tool; structured in-process children enforce output with scoped prompt/tool registrations, a monotonic tool guard, final `tools/result` commit (including enclosing `run_code`), and the structured-output execution's monotonic `concludeTurn()` marker |
 | Queued + steering messages | core `Agent.followup()` / `Agent.steer()` |
-| Context compaction (auto + manual) | the `ctx.compact` seam + `dsh-compact-basic`; automatic pressure runs on serial `agent/pre-step`, canonical overflow recovery runs on `agent/request-error`, and manual callers use the same compact service ([compaction Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) — the model-facing `/compact` consumer tool is deferred) |
+| Context compaction (auto + manual) | the `ctx.compact` seam + `dsh-compact-basic`; automatic pressure runs on serial `agent/pre-step`, canonical overflow recovery runs on `agent/request-error`, and manual callers use the same compact service ([compaction Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)) |
 | System prompt configurability | `ctx.systemPrompt.section()` with ordering and scope-local shadowing |
 | AGENTS.md (root) | a section provider reading the file |
 | AGENTS.md (subdir, on-touch) + file-change notices | `agent.inject()` from a watcher / tool-result listener |
@@ -116,7 +116,7 @@ Every product feature maps to a listener on a documented extension point — the
 | Monotonic terminal turn policy | call `ToolExecution.concludeTurn()` from the successful terminal tool; later tool calls in the same response remain guardable, and the loop stops after the step |
 | Subprocess sandbox (landlock / sandbox-exec) | use a `ctx.sandbox` backend through `dsh-bash-sandbox`; use `tools/pre-execute` for capability-level denial |
 | Permission system / AskUserQuestion | return `ask` from `tools/pre-execute` and answer through `ctx.approval`; register a separate model-facing ask tool for ordinary user questions |
-| Plan mode | Shipped: [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — logged `plan/mode` state, the `plan:policy` guidance section, `/plan [message]` entry, `/plan off` direct exit, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
+| Plan mode | [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — logged `plan/mode` state, the `plan:policy` guidance section, `/plan [message]` entry, `/plan off` direct exit, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
 | Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`) + `dsh-tool-subagent` exposing one configured provider to the model |
 | MCP | one plugin per server: discover tools → `ctx.tools.register()` |
 | Skills | section + tool registration; `inject()` skill content on invocation |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index 29bb57c558..34e8fc0fa3 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -105,7 +105,7 @@ export function apply(ctx: Context) {
 | `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
 | 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
 | 排队消息 + steering | 核心 `Agent.followup()` / `Agent.steer()` |
-| 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/pre-step`，规范化溢出恢复运行在 `agent/request-error`，手动调用方使用同一个压缩服务（[压缩 Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)——面向模型的 `/compact` 消费方工具已推迟） |
+| 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/pre-step`，规范化溢出恢复运行在 `agent/request-error`，手动调用方使用同一个压缩服务（[压缩 Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)） |
 | 系统提示词可配置性 | `ctx.systemPrompt.section()`，支持排序与作用域局部覆盖 |
 | AGENTS.md（根目录） | 一个读取该文件的 section 提供方 |
 | AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / 工具结果监听器调用 `agent.inject()` |
@@ -116,7 +116,7 @@ export function apply(ctx: Context) {
 | 单调终端轮次策略 | 从成功的终端工具调用 `ToolExecution.concludeTurn()`；同一响应中后续工具调用仍可由守卫阻止，循环在该步骤后停止 |
 | 子进程沙箱（landlock / sandbox-exec） | 通过 `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
 | 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
-| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md)：落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
+| Plan mode | [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md)：落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
 | subagent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
 | MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
 | skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
diff --git a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
index fde0ddda14..331373fb1e 100644
--- a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
+++ b/docs/cookbook/maintaining-dsh-code-review.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 docs/cookbook/maintaining-dsh-code-review.md
-maintaining-dsh-code-review.md: 8aa8a5792bff2c49041f2f8b5e8146e7cff14e0e
-maintaining-dsh-code-review.zh.md: b26c98e8679eece78e72ee684580c1ed1181aa7c
+maintaining-dsh-code-review.md: c8517054434f4b090c67455cda0a992c2c3173ee
+maintaining-dsh-code-review.zh.md: 3d26d540a41661aa45b41d6738118f36d904ccf3
diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
index 8aa8a5792b..c851705443 100644
--- a/docs/cookbook/maintaining-dsh-code-review.md
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -6,7 +6,7 @@ The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is
 
 ## What the maintainer receives
 
-Run the private tool daily with a two-UTC-day overlap; until the proposed scheduler has completed its acceptance run, the operator invokes the wrapper manually at the same cadence. A manual weekly recovery run uses a seven-day window. The workflow:
+The operator invokes the wrapper manually, daily with a two-UTC-day overlap; a manual weekly recovery run uses a seven-day window. The workflow:
 
 1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
 2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
diff --git a/docs/cookbook/maintaining-dsh-code-review.zh.md b/docs/cookbook/maintaining-dsh-code-review.zh.md
index b26c98e867..3d26d540a4 100644
--- a/docs/cookbook/maintaining-dsh-code-review.zh.md
+++ b/docs/cookbook/maintaining-dsh-code-review.zh.md
@@ -6,7 +6,7 @@
 
 ## 维护者会收到什么
 
-每天运行私有工具，并使用 2 个 UTC 日的重叠窗口；在拟议的调度器完成验收运行之前，操作员按相同频率手动调用包装脚本。每周手动恢复运行使用 7 日窗口。工作流会：
+操作员每天手动调用包装脚本，并使用 2 个 UTC 日的重叠窗口；每周手动恢复运行使用 7 日窗口。工作流会：
 
 1. 选择指定窗口内合并、且合并 commit 可从 `origin/master` 到达的 PR（每天运行默认选择 2 个 UTC 日，每周运行选择 7 日）。合并 commit 无法到达的 PR（例如父分支被 squash 的堆叠分支），或超出 250 个 commit 获取上限的 PR，会记录到 `skipped-pulls.json` 并跳过，不会中止本次运行。
 2. 收集合并前带 commit 锚点的人工评审反馈（行内评论和评审提交），然后比较反馈时与最终落地的 PR patch。它不获取 PR 会话评论，因为 GitHub 当前状态无法为这些评论提供可抵抗 force-push 的反馈时基线；它也不会把只存在于目标分支的变更作为采纳证据。
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 8bf23274e5..6af9aec465 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -5,7 +5,7 @@
 
 The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
 
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.
 
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index 2914e62e30..b453ffb1f6 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.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 docs/cordis-tutorial/04-events.md
-04-events.md: b0563c71fada3efc760ff7183bc7a82e7e86934e
-04-events.zh.md: 66b52fcb1d7ec4a81c823a7c8e016c5b17d45993
+04-events.md: e77641dffcb82fcb50a24ca2e3e764d152218094
+04-events.zh.md: 00cce854e9a54fddb594ffa8e306f60a725ac012
diff --git a/docs/cordis-tutorial/04-events.md b/docs/cordis-tutorial/04-events.md
index b0563c71fa..e77641dffc 100644
--- a/docs/cordis-tutorial/04-events.md
+++ b/docs/cordis-tutorial/04-events.md
@@ -135,7 +135,7 @@ HELLO
 
 Walk through the second line: listener 1 runs first, calls `next()`, which invokes listener 2; listener 2 sees `blocked` and returns without calling `next()` — the innermost default (the function passed to `ctx.waterfall`) never runs — and listener 1 uppercases the replacement message on the way out.
 
-The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. This is important enough that it is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
+The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. It is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
 
 The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../subsystems/core.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) lets a policy answer instead of the user.
 
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index 66b52fcb1d..00cce854e9 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -135,7 +135,7 @@ HELLO
 
 按顺序看第二行如何产生：监听器 1 先运行并调用 `next()`，从而调用监听器 2；监听器 2 看到 `blocked` 后直接返回而不调用 `next()`，因此最内层默认逻辑（传给 `ctx.waterfall` 的函数）从未运行；返回途中，监听器 1 再把替换消息转换为大写。
 
-由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这一点极其重要，已成为本仓库的常设规则（[waterfall 语义](../cordis-primer.md#cordis-waterfall-semantics)）。
+由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这是本仓库的常设规则（[waterfall 语义](../cordis-primer.md#cordis-waterfall-semantics)）。
 
 harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) 允许策略代替用户作答。
 
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml b/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
index 44b59db26a..3732651e58 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
+++ b/docs/cordis-tutorial/06-composition-and-hmr.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 docs/cordis-tutorial/06-composition-and-hmr.md
-06-composition-and-hmr.md: f138918a2d217ed98fdfd4e56dffddc14e3397f0
-06-composition-and-hmr.zh.md: a678e86735c6d9e3b4f3cd0dfa46a2a64079c762
+06-composition-and-hmr.md: a169d7a164be63c939e352e4e5b0bf9bce43da29
+06-composition-and-hmr.zh.md: 07ae46555c390d625a4397933e2ec5ac059bd270
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.md b/docs/cordis-tutorial/06-composition-and-hmr.md
index f138918a2d..a169d7a164 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.md
@@ -18,7 +18,7 @@ A config entry accepts metadata beyond `name` and `config`:
 
 `id` gives the entry a stable identity so the loader can tell an edit to an existing entry apart from a removal plus an addition. `disabled: true` unmounts a plugin without deleting its entry — flip it back and the plugin (and everything PENDING on its services) loads again.
 
-Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently-configured `bash` without affecting each other. Those are worth knowing about before you need them; the [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
+Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently-configured `bash` without affecting each other. The [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
 
 ## Hot module replacement
 
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.zh.md b/docs/cordis-tutorial/06-composition-and-hmr.zh.md
index a678e86735..07ae46555c 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.zh.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.zh.md
@@ -18,7 +18,7 @@ Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
 
 `id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
 
-组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。这些概念值得在用到之前先了解；[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
+组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
 
 ## 热模块替换
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 05ff62a391..11eecf81a4 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -3,7 +3,7 @@
 
 # Event Producer And Consumer Matrix
 
-This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
+This matrix shows which packages dispatch each harness-owned event and which packages listen to it. Events are many-to-many, so the dense relation data is presented as a table rather than one large graph. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index f4aece8a52..d8c6d95f73 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,6 +1,6 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。[提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录兼容协议；v7 保留该协议并选择性吸收经评估的生成质量改进。修改本文件会改变翻译行为，需正常经过 PR 评审。
+本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。本模板遵循 [提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录的兼容协议。修改本文件会改变翻译行为，需正常经过 PR 评审。
 
 ## 占位符约定
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index c9aa15cd82..a17cae015e 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -35,7 +35,8 @@ export type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 export type SurfaceOp =
   | 'append'
@@ -78,7 +79,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:376`](../packages/core/session/src/types.ts)
 
 ## Events
 
diff --git a/docs/subsystems/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
index 93c56707bf..088b30ff32 100644
--- a/docs/subsystems/approval.i18n.yaml
+++ b/docs/subsystems/approval.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 docs/subsystems/approval.md
-approval.md: 2045f2073b72fa265728cbf77b673053a2eaf371
-approval.zh.md: c021db14c4925acaeef5d984d9dfa88ad55bd8dd
+approval.md: 660ced6d75886bbea41985fd1f357bf92e8a7838
+approval.zh.md: 56975914098978af99580694ca19f20a02ed4022
diff --git a/docs/subsystems/approval.md b/docs/subsystems/approval.md
index 2045f2073b..660ced6d75 100644
--- a/docs/subsystems/approval.md
+++ b/docs/subsystems/approval.md
@@ -38,8 +38,7 @@ type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -142,7 +141,7 @@ overrideOf(session: Session): ApprovalPolicy | undefined
 
 Types: [Agent](core.md) · [Session](session.md)
 
-Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:192`](../../packages/interaction/user-approval/src/index.ts)
 
 <a id="approval-events"></a>
 
diff --git a/docs/subsystems/approval.zh.md b/docs/subsystems/approval.zh.md
index c021db14c4..5697591409 100644
--- a/docs/subsystems/approval.zh.md
+++ b/docs/subsystems/approval.zh.md
@@ -38,8 +38,7 @@ type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -142,7 +141,7 @@ overrideOf(session: Session): ApprovalPolicy | undefined
 
 Types: [Agent](core.md) · [Session](session.md)
 
-Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:192`](../../packages/interaction/user-approval/src/index.ts)
 
 <a id="approval-events"></a>
 
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 81dc8ce5d7..dbfc52bf6e 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/subsystems/bash.md
-bash.md: 1c60f261e292f389ea4afa3f962f698e0272007b
-bash.zh.md: 2533cbe10dc0a480d285f87e458cf5ee5fa12d75
+bash.md: d2797c1e3ff73fe8ecb5a053ed4a1d13b13298dd
+bash.zh.md: b38a4f332978e94d2945f5fa49b38e8d7df8c9ca
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index 1c60f261e2..d2797c1e3f 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -12,7 +12,7 @@ Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.t
 
 ## Request vs. spec: the `resolve()` split
 
-The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package boundaries" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
+The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them (the repo's "explicit > implicit at package boundaries" rule); a `BashExecSpec` carries resolved values.
 
 ```ts type-equiv
 /**
@@ -162,7 +162,7 @@ interface BashSandboxInfo {
 }
 ```
 
-One more piece completes the vocabulary: the `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background task records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+The `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background task records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 
 ## Background processes: `BashProcess`
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index 2533cbe10d..b38a4f3329 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -12,7 +12,7 @@ bash 执行 seam 分为 Service Definition（[dsh-bash](../../packages/bash/bash
 
 ## 请求与规格：`resolve()` 拆分
 
-该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包边界处显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
+该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`（仓库的「包边界处显式优于隐式」规则）；`BashExecSpec` 携带的是已解析的值。
 
 ```ts type-equiv
 /**
@@ -162,7 +162,7 @@ interface BashSandboxInfo {
 }
 ```
 
-最后一项补全了这套词汇：当受限模式没有可用后端时，`ctx.sandbox` 提供方会抛出、执行器会传播由[沙箱 seam](sandbox.md)所有的 `SANDBOX_UNAVAILABLE` 错误码。选定的 runner 拒绝其 profile 时会触达同一个故障关闭的前台错误；已结束的后台任务则记录 `runnerFailed`。模型会在结果中收到拒绝/runner 事实，仅当拒绝标记指出生效模式时才得知该模式，并可通过 `sandbox_permissions` 加 `justification` 请求一次性、严格更宽松的重试；执行任何操作前，`ctx.approval` 必须批准该次确切调用。完整的策略与切换设计见[沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+当受限模式没有可用后端时，`ctx.sandbox` 提供方会抛出、执行器会传播由[沙箱 seam](sandbox.md)所有的 `SANDBOX_UNAVAILABLE` 错误码。选定的 runner 拒绝其 profile 时会触达同一个故障关闭的前台错误；已结束的后台任务则记录 `runnerFailed`。模型会在结果中收到拒绝/runner 事实，仅当拒绝标记指出生效模式时才得知该模式，并可通过 `sandbox_permissions` 加 `justification` 请求一次性、严格更宽松的重试；执行任何操作前，`ctx.approval` 必须批准该次确切调用。完整的策略与切换设计见[沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 ## 后台进程：`BashProcess`
 
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index ae61603169..8c320d18e6 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: 19bcc6304e9d917c3950fd9857e7b2c2b3c16e73
-client-modules.zh.md: b0ad293cad2f67de1982ef271308b2a7f06ebaf4
+client-modules.md: 808fa62b2e5a4351b1dc98bbe4f3d2af63c9dd2b
+client-modules.zh.md: dcab60bea7c54770cc5e6032afb39d6dd189d037
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 19bcc6304e..808fa62b2e 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -12,7 +12,7 @@ The graph is the wire single source between the Node and browser halves: the hos
 
 ```ts type-equiv
 /**
- * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * One composed client entry pushed by the host (a graph row). Wire
  * single source: the host node half (package root) produces this same shape.
  * `immediately` marks stage-one prefetch; `inject` is informational graph
  * metadata (the authoritative edges live in each package's dshClient
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index b0ad293cad..dcab60bea7 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -12,7 +12,7 @@ Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 
 
 ```ts type-equiv
 /**
- * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * One composed client entry pushed by the host (a graph row). Wire
  * single source: the host node half (package root) produces this same shape.
  * `immediately` marks stage-one prefetch; `inject` is informational graph
  * metadata (the authoritative edges live in each package's dshClient
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index cbe983a780..47783d5f77 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
-code-runtime.md: 8a767287414824e6f76659c02c47193522eb21c7
-code-runtime.zh.md: e6bb7cb93cb542dceb2c7e335162a03429d161e8
+code-runtime.md: 6d3fa7fa72891897155cb9c611c7aa472629de4f
+code-runtime.zh.md: 47516c7d21c24399498a05410ab9a46b61736fb4
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index 8a76728741..6d3fa7fa72 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -187,5 +187,5 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
-Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+Source: [`packages/code-runtime/code-runtime/src/index.ts:102`](../../packages/code-runtime/code-runtime/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index e6bb7cb93c..47516c7d21 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -187,5 +187,5 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
-Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+Source: [`packages/code-runtime/code-runtime/src/index.ts:102`](../../packages/code-runtime/code-runtime/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 5e7c6d92be..d2fe7303fc 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 8325694d92aa1a3019aef8f6b0c1f99d45ad0df5
-compaction.zh.md: 9f9014b8c1c1db12abc6581fbe6ebacfac3dd6fe
+compaction.md: fdff28ac2ec83966a03050ba8d54fe0ee26c4fc6
+compaction.zh.md: e4227320d9829cac695dc4ba0c5779086f77194b
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 8325694d92..fdff28ac2e 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -8,7 +8,7 @@ Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact
 
 ## The `compact/*` session events
 
-Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. See the Agent Note for why reusing `user/message` is honest rather than a workaround.
+Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. The [Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) owns the rationale for reusing `user/message`.
 
 | Event | Payload | Role |
 |---|---|---|
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 9f9014b8c1..e4227320d9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -8,7 +8,7 @@
 
 ## `compact/*` 会话事件
 
-压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——它们记录锁、摘要、选中范围、被遮蔽事件 seq、token 数以及模型调用，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
+压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——它们记录锁、摘要、选中范围、被遮蔽事件 seq、token 数以及模型调用，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。[Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 负责复用 `user/message` 的决策依据。
 
 | 事件 | 载荷 | 作用 |
 |---|---|---|
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index f7d59cd66d..91c13a23c5 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: dd81cc27ad73bab026cd11da6ab184890bb6535d
-filesystem.zh.md: 9589adfaf43c1d5a4bbc8571e70c878770d880b2
+filesystem.md: 23ade1ede1592f7c8e1e409f3f9ca30f4f3f7e6f
+filesystem.zh.md: da2ac2583c381a89e0bd656018d799b22da0f1de
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index dd81cc27ad..23ade1ede1 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 ## The service and the plugin
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 9589adfaf4..da2ac2583c 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## 文件 IO 不设超时
 
-`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的 `timeoutMs` 会成为 seam 无法强制执行的截止时间，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
 
 ## 服务与插件
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 1808f2d8e4..86ec4e3c3f 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 0cfce7a06d1db73268e2457c4979d1b1ccc889b7
-llm-streaming.zh.md: 19541462805c50b0ed446a346523d20de91d0351
+llm-streaming.md: 4d450c19ec2bbfacabcefc83466e67c8a6c82bd6
+llm-streaming.zh.md: 777c44eaff2b1ee6e5939e04e580d6ad34b1ad1a
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 0cfce7a06d..4d450c19ec 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -87,8 +87,8 @@ Producer identity and content shape are independent. `kind` answers *who produce
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
  *
  * The vocabulary is SEMANTIC, never visual: a value states that the content is
  * a file's instructions or a catalog of available items, and a consumer decides
@@ -209,11 +209,9 @@ Every adapter MUST obey these, and every consumer may rely on them:
 - **Provider stalls are bounded at the transport.** Both shipping remote adapters expose positive finite `streamIdleTimeoutMs` with a five-minute default. The watchdog arms only while iterator `next()` is outstanding, uses one stable signal for the whole request, maps its own expiry to `TIMEOUT`, and keeps an earlier caller abort as `ABORTED`.
 - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
 - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
-- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
+- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test.
 - **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state.
 
-This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
-
 ## `ResolvedRetryPolicy`
 
 Provider configuration resolves before route registration into an immutable discriminated union. Normal mode carries `mode: 'normal'`, finite `maxRetries`, `retryableCodes`, and required `initialDelayMs`, `maxDelayMs`, and `jitterRatio`; always mode carries `mode: 'always'` and the same required backoff fields without a finite maximum. `LlmService.providerRetryPolicy(provider)` returns the currently registered value and supplies normal defaults when the adapter omits one; `llmRetryPolicyOf(stream)` returns the exact serving registration's captured value after that call enters its final adapter boundary, so later route disposal or replacement cannot change an in-flight failure's recovery policy. The [generated config catalog](../config-catalog.md) owns the optional input shapes.
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 1954146280..777c44eaff 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -87,8 +87,8 @@ interface MessageSourceMap {
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
  *
  * The vocabulary is SEMANTIC, never visual: a value states that the content is
  * a file's instructions or a catalog of available items, and a consumer decides
@@ -213,11 +213,9 @@ interface LlmFailure {
 - **提供方停顿在传输层受到时限约束。** 两个已交付的远程适配器都暴露正数且有限的 `streamIdleTimeoutMs`，默认五分钟。watchdog 只在 iterator `next()` 尚未完成时启动，整个请求使用同一个稳定 signal，把自身到期映射为 `TIMEOUT`，并把更早发生的调用方中止保留为 `ABORTED`。
 - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
-- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
+- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。
 
-该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
-
 ## `ResolvedRetryPolicy`
 
 提供方配置会在路由注册前解析为不可变的可辨识联合。normal mode 携带 `mode: 'normal'`、有限的 `maxRetries`、`retryableCodes`，以及必填的 `initialDelayMs`、`maxDelayMs` 与 `jitterRatio`；always mode 携带 `mode: 'always'` 和相同的必填退避字段，但没有有限上限。`LlmService.providerRetryPolicy(provider)` 返回当前注册的值，并在适配器省略策略时提供 normal 默认值；调用进入最终适配器边界后，`llmRetryPolicyOf(stream)` 返回为其提供服务的确切注册所捕获的值，因此之后释放或替换路由都无法改变进行中失败的恢复策略。可选输入形状由[生成的配置目录](../config-catalog.md)规定。
diff --git a/docs/subsystems/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
index 400274ceef..00e509db87 100644
--- a/docs/subsystems/lsp.i18n.yaml
+++ b/docs/subsystems/lsp.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 docs/subsystems/lsp.md
-lsp.md: f8fa2be3d79c0aff9b288f61bf64bbb91e327f1d
-lsp.zh.md: fc9214fa7b10c2dac2a6cd90e0c29776313653f4
+lsp.md: 96a365a7f16e53a6c8b28fdc5997724bcbf81115
+lsp.zh.md: 28b16cab9cb302de7db76be0b12788d1bef04541
diff --git a/docs/subsystems/lsp.md b/docs/subsystems/lsp.md
index f8fa2be3d7..96a365a7f1 100644
--- a/docs/subsystems/lsp.md
+++ b/docs/subsystems/lsp.md
@@ -14,7 +14,7 @@ The seam and model expose exactly four semantic queries; the union is closed, so
 /**
  * The four semantic queries the seam and model expose. A closed union: adding an operation is a
  * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * deliberately deferred (they need different schemas).
+ * not operations here; they need different schemas.
  */
 type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
 ```
diff --git a/docs/subsystems/lsp.zh.md b/docs/subsystems/lsp.zh.md
index fc9214fa7b..28b16cab9c 100644
--- a/docs/subsystems/lsp.zh.md
+++ b/docs/subsystems/lsp.zh.md
@@ -14,7 +14,7 @@ seam 与模型恰好公开 4 项语义查询；该联合是闭合的，因此新
 /**
  * The four semantic queries the seam and model expose. A closed union: adding an operation is a
  * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * deliberately deferred (they need different schemas).
+ * not operations here; they need different schemas.
  */
 type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
 ```
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index eb5478eef8..f198d0a25e 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 991efe39a059e08cdf7904b473486b336cb2071c
-persistence.zh.md: 2391eeb2a751388b6aa139d0646b52fe5af04601
+persistence.md: 640e2c0122b01ae869d20c1805742abad782c95b
+persistence.zh.md: 7e28d6d1f63a78741840fb74194d3249696423ae
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 991efe39a0..640e2c0122 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -4,7 +4,7 @@ English | [中文](persistence.zh.md)
 
 The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
 
-The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+The seam is a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
 
 ## The flush checkpoint
 
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## The backends
 
-Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`:
+Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass the shared `runPersistenceContract` suite:
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 2391eeb2a7..7e28d6d1f6 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## 后端
 
-两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`：
+两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过共享的 `runPersistenceContract` 套件：
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 54cadaf5b5..823ed61107 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: ddb3877618904d3185eba7d9d351afbcc81b2d04
-session-projection.zh.md: 39e6099130ba0d91e72e8f1afd5661e5894f8d0f
+session-projection.md: d91a3faa50dc092d89aa2c7d5ce1e6118df7ebd6
+session-projection.zh.md: 7dac3db8470a2941b711db6a30fced8dbe7c7a8d
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index ddb3877618..d91a3faa50 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -2,7 +2,7 @@
 
 English | [中文](session-projection.zh.md)
 
-The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
 
 Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index 39e6099130..7dac3db847 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-projection.md) | 中文
 
-会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（[dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
 
 源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 4c8cad1880..3b9f9ce01d 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: e5eb78908ba4b7ebfc398d5c735969a5a8937374
-session.zh.md: 51729999a831c94e87e36ec1c4705201f9c8360f
+session.md: f5b9e63e2320885cc41b30a09398dd341700152d
+session.zh.md: 985e0a448d1cf860ccbb0f2885d855ad6830af9f
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index e5eb78908b..f5b9e63e23 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -171,7 +171,7 @@ interface EpochHeader {
 }
 ```
 
-Canonical form represents an empty system prompt or tool list as an absent field, matching how requests are built. Legacy v0 logs containing the removed `request/header-delta` event or its full-snapshot `fallback` reason are rejected at seed, append, and persistence-load boundaries rather than replayed incompletely.
+Canonical form represents an empty system prompt or tool list as an absent field, matching how requests are built. Legacy v0 logs containing the legacy `request/header-delta` event or its full-snapshot `fallback` reason are rejected at seed, append, and persistence-load boundaries rather than replayed incompletely.
 
 ### The route capacity event: `request/context`
 
@@ -266,7 +266,8 @@ type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 type SurfaceOp =
   | 'append'
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 51729999a8..985e0a448d 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -173,7 +173,7 @@ interface EpochHeader {
 }
 ```
 
-规范形式：空系统提示词和空工具列表都表示为字段缺失，与请求构建方式一致。包含已移除的 `request/header-delta` 事件或完整快照原因为 `fallback` 的旧版 v0 日志，会在 seed、append 和持久化加载边界被拒绝，而不会以不完整方式回放。
+规范形式：空系统提示词和空工具列表都表示为字段缺失，与请求构建方式一致。包含旧版 `request/header-delta` 事件或完整快照原因为 `fallback` 的旧版 v0 日志，会在 seed、append 和持久化加载边界被拒绝，而不会以不完整方式回放。
 
 ### 路由容量事件：`request/context`
 
@@ -268,7 +268,8 @@ type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 type SurfaceOp =
   | 'append'
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 5945dfb286..a169374140 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/subsystems/skills.md
-skills.md: 1c3d683c6fb2c2ac26e00c32329e41b8d4636fb1
-skills.zh.md: b38effdd5858625bb1aa5f10108d5d654f692b7c
+skills.md: 696f759179203230bf748c8a4be2cee333acd9a3
+skills.zh.md: d2244e86f0ceaf77c1eab02508dc3f07df727dbb
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index 1c3d683c6f..696f759179 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -80,7 +80,7 @@ Chokidar watches existing roots for direct bundle/flat-entry additions and remov
 
 ## Skill identity
 
-Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is intentionally outside v1.
+Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is not supported.
 
 ```ts type-equiv
 /** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index b38effdd58..d2244e86f0 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -80,7 +80,7 @@ Chokidar 会监视现有根目录中直属 bundle 和平铺条目的添加与移
 
 ## skill 身份
 
-skill 名称为 kebab-case（`^[a-z0-9]+(?:-[a-z0-9]+)*$`）。本地提供方接受目录包（`<name>/SKILL.md`）和扁平 Markdown 文件（`<name>.md`）。嵌套递归的 `**/SKILL.md` 发现有意不在 v1 范围内。
+skill 名称为 kebab-case（`^[a-z0-9]+(?:-[a-z0-9]+)*$`）。本地提供方接受目录包（`<name>/SKILL.md`）和扁平 Markdown 文件（`<name>.md`）。嵌套递归的 `**/SKILL.md` 发现不受支持。
 
 ```ts type-equiv
 /** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 5b4d6d1040..9b3d8a19d6 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
-storage.md: 94d3c3f39a65462cd8cd58a65b02066d5bad4b8c
-storage.zh.md: c3cea8eb5e44f2e589b0196dc690c6473e3552ca
+storage.md: 3234fdf9587dc2853b4f9ec4205d230aae4b633a
+storage.zh.md: fb13ec96099f2173478aecf1b91799237755414c
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index 94d3c3f39a..3234fdf958 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -44,7 +44,7 @@ interface StorageBackend {
 }
 ```
 
-A backend owns one medium (a file-tree root, a database file) and exposes optional data-shape facets; `kv` is the only facet today. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, format version, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are arbitrary strings that never reach file paths. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium and durable once resolved. A medium stamped with a different version rejects `version-mismatch`; one that cannot be parsed as the unit rejects `malformed-medium` (no migration, pre-release stance). [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) asserts every clause against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores document-per-row in one database, the route for high-churn domains.
+A backend owns one medium (a file-tree root, a database file) and exposes optional data-shape facets; `kv` is the sole facet. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, format version, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are arbitrary strings that never reach file paths. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium and durable once resolved. A medium stamped with a different version rejects `version-mismatch`; one that cannot be parsed as the unit rejects `malformed-medium` (no migration, pre-release stance). [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) asserts every clause against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores document-per-row in one database, the route for high-churn domains.
 
 ## Declaring a domain
 
@@ -122,7 +122,7 @@ interface DomainChangedBase {
 type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
-`put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is deferred work recorded in the [package README](../../packages/storage/storage-domain/README.md).
+`put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is a recorded limitation ([package README](../../packages/storage/storage-domain/README.md)).
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index c3cea8eb5e..fb13ec9609 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -44,7 +44,7 @@ interface StorageBackend {
 }
 ```
 
-一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
+一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；`kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
 
 ## 声明领域
 
@@ -122,7 +122,7 @@ interface DomainChangedBase {
 type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
-`put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是延后工作，记录在[包 README](../../packages/storage/storage-domain/README.md)中。
+`put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是一项已记录的限制（[包 README](../../packages/storage/storage-domain/README.md)）。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 5e8fdefb08..e98438900d 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: a14e9ec5fad3f25f231016c142c3965561790afe
-subagent.zh.md: 7bf3595324ecfec85329ea3f51ab5a8cc0d4c329
+subagent.md: 99c54e0696c9c3585c50285ecb69b14c90d83c11
+subagent.zh.md: c5a79247a81f5174662f2b5d1ed2d3c20cf6c672
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index a14e9ec5fa..99c54e0696 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -265,7 +265,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished (`unsupported` remains in the type but is never produced); a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 `SubagentService.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
 
@@ -411,7 +411,7 @@ interface SubagentProvider {
   /**
    * OPTIONAL (continuable-creation capability): contribute the detached
    * creation inputs that distinguish this provider's continuable children —
-   * today only whether the child session is seeded with parent history. Method
+   * only whether the child session is seeded with parent history. Method
    * presence IS the capability: the service rejects continuable starts on
    * providers without it, while a provider that has it may still serve
    * ordinary one-shot delegations.
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 7bf3595324..c5a79247a8 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -265,7 +265,7 @@ interface ContinuableCreateSpec {
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分（`unsupported` 仍保留在类型中但从不产出）；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -413,7 +413,7 @@ interface SubagentProvider {
   /**
    * OPTIONAL (continuable-creation capability): contribute the detached
    * creation inputs that distinguish this provider's continuable children —
-   * today only whether the child session is seeded with parent history. Method
+   * only whether the child session is seeded with parent history. Method
    * presence IS the capability: the service rejects continuable starts on
    * providers without it, while a provider that has it may still serve
    * ordinary one-shot delegations.
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index e89be8fdc9..26064089c2 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
-subprocess.md: eedf95abc2a51872ffc9964481bb3685ace31993
-subprocess.zh.md: 669baa52a92fc3869b057dc802c72989fa8cfcf1
+subprocess.md: 4fb20e1b440b8fc10540fa2adbd00ae63fd7e221
+subprocess.zh.md: a41f14aa550c4780b5661b546880d932d513b817
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index eedf95abc2..4fb20e1b44 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -293,8 +293,8 @@ Implementations must honor these semantics:
  * Resolve one configured executable in this provider's execution world.
  * Absolute paths are verified; bare names use the provider's scrubbed PATH
  * plus explicit environment overrides. Relative paths containing separators
- * are rejected: no current consumer defines which directory they would
- * resolve against, so providers fail loud instead of guessing.
+ * are rejected: the resolution base is undefined, so providers fail loud
+ * instead of guessing.
  * @param command - absolute executable path or bare PATH name.
  * @param env - explicit environment entries used for lookup.
  * @param signal - aborts remote or local lookup.
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 669baa52a9..a41f14aa55 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -293,8 +293,8 @@ Implementations must honor these semantics:
  * Resolve one configured executable in this provider's execution world.
  * Absolute paths are verified; bare names use the provider's scrubbed PATH
  * plus explicit environment overrides. Relative paths containing separators
- * are rejected: no current consumer defines which directory they would
- * resolve against, so providers fail loud instead of guessing.
+ * are rejected: the resolution base is undefined, so providers fail loud
+ * instead of guessing.
  * @param command - absolute executable path or bare PATH name.
  * @param env - explicit environment entries used for lookup.
  * @param signal - aborts remote or local lookup.
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index ec9f0cd48b..c994c46baa 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: c9e51eb38e680723ead0a88f4a9748620fd6b893
-telemetry.zh.md: 1af25c505574db6b3513547ae604eda66fc21766
+telemetry.md: 93869f2344eeedfee344735191af842fef188886
+telemetry.zh.md: 50642f1ed917ea52ee152e333f70753c12fba583
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index c9e51eb38e..93869f2344 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -84,7 +84,7 @@ interface TelemetryBackend {
    * leave this unimplemented and let their SDK's own batching cadence govern
    * export timing: a backend that does implement it owns the interaction
    * between its concurrent flushes and {@link shutdown}'s drain (the OTel
-   * backend removed its implementation for exactly that hazard — see the
+   * backend leaves it unimplemented for exactly that hazard — see the
    * revival Agent Note).
    */
   flush?(): void
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 1af25c5055..50642f1ed9 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -84,7 +84,7 @@ interface TelemetryBackend {
    * leave this unimplemented and let their SDK's own batching cadence govern
    * export timing: a backend that does implement it owns the interaction
    * between its concurrent flushes and {@link shutdown}'s drain (the OTel
-   * backend removed its implementation for exactly that hazard — see the
+   * backend leaves it unimplemented for exactly that hazard — see the
    * revival Agent Note).
    */
   flush?(): void
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index f5e4289b30..8a11d774e6 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.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 docs/subsystems/web.md
-web.md: e6dc49353e50181b7844a658008edfa075cfedc3
-web.zh.md: 63f85a8d235e5c0778af8547251ebf2c299f036a
+web.md: 2a7cc499b42dd8b45ce6783a35a2fadd8df1183d
+web.zh.md: 6857f2a06a7d90702b6626409b4d8db914b3c465
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index e6dc49353e..2a7cc499b4 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -36,7 +36,8 @@ interface WebSearchRequest {
 ```ts type-equiv
 /**
  * Normalized search outcome. `content` is optional provider-generated answer
- * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
  * `sources[]` is the portable citation surface. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
@@ -50,8 +51,6 @@ interface WebSearchResult {
 }
 ```
 
-`content` is optional provider-generated answer text (Exa and DeepSeek return none; Perplexity returns a generated answer). `sources[]` is the portable citation surface. A source always has a `url`; `title`/`snippet`/`publishedAt` are optional because not every provider returns them — Perplexity citations may be URL-only, and forcing adapters to invent the rest would make the seam lie. `dsh-tool-web` renders `title ?? hostname(url)`.
-
 ```ts type-equiv
 /**
  * One citeable source. A source always has a URL; `title`, `snippet`, and
@@ -103,8 +102,6 @@ interface WebFetchResult {
 }
 ```
 
-`WebFetchBody` is a **closed** discriminated union owned by `dsh-web` (not a merge-extensible map): the provider decodes the kind and `dsh-tool-web` renders it, so a new kind is a coordinated change across known packages, not a plugin extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`, so adding a kind breaks compilation at every consumer until handled. Each arm stays its own object literal even where fields coincide today, leaving room for arm-specific fields later (a future `pdf` body's `pageCount`).
-
 ```ts type-equiv
 /**
  * The decoded body of a fetched resource. A CLOSED discriminated union owned by
@@ -112,8 +109,8 @@ interface WebFetchResult {
  * new kind is a coordinated change across known packages, not a plugin
  * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
  * so adding a kind breaks compilation at every consumer until handled. Each arm
- * stays its own object literal even where fields coincide today, leaving room
- * for arm-specific fields later (a `pdf` body's `pageCount`).
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
  */
 type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
@@ -132,7 +129,7 @@ Selection never depends on registration, config, or HMR order: a capability has
 
 ## The service
 
-`WebService` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. Private-network blocking is deferred, so do not enable `web_fetch` where it can reach sensitive internal targets.
+`WebService` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. The local backend does not block private-network targets; do not enable `web_fetch` where it can reach sensitive internal ones.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 63f85a8d23..6857f2a06a 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -36,7 +36,8 @@ interface WebSearchRequest {
 ```ts type-equiv
 /**
  * Normalized search outcome. `content` is optional provider-generated answer
- * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
  * `sources[]` is the portable citation surface. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
@@ -50,8 +51,6 @@ interface WebSearchResult {
 }
 ```
 
-`content` 是提供方可选生成的回答文本（Exa 和 DeepSeek 不返回；Perplexity 返回生成式回答）。`sources[]` 是一套可跨提供方使用的引用数据结构。每个来源都必须有 `url`；`title`、`snippet` 和 `publishedAt` 为可选字段，因为并非每个提供方都会返回它们——Perplexity 的引用可能只有 URL，强迫适配器编造其余字段会让 seam 说谎。`dsh-tool-web` 渲染时使用 `title ?? hostname(url)`。
-
 ```ts type-equiv
 /**
  * One citeable source. A source always has a URL; `title`, `snippet`, and
@@ -103,8 +102,6 @@ interface WebFetchResult {
 }
 ```
 
-`WebFetchBody` 是 `dsh-web` 拥有的**封闭**可辨识联合类型（不是可合并扩展的 map）：提供方解码 kind，`dsh-tool-web` 渲染它，因此新增一个 kind 是已知包之间的协调变更，而非插件扩展。消费方对 `kind` 做 `switch` 并以 `default: assertNever(...)` 结尾，所以新增 kind 会在每个消费方处编译失败，直到被处理。即使各分支当前字段一致，每个分支仍保持独立的对象字面量，为将来分支特有字段留出空间（例如未来 `pdf` body 的 `pageCount`）。
-
 ```ts type-equiv
 /**
  * The decoded body of a fetched resource. A CLOSED discriminated union owned by
@@ -112,8 +109,8 @@ interface WebFetchResult {
  * new kind is a coordinated change across known packages, not a plugin
  * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
  * so adding a kind breaks compilation at every consumer until handled. Each arm
- * stays its own object literal even where fields coincide today, leaving room
- * for arm-specific fields later (a `pdf` body's `pageCount`).
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
  */
 type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
@@ -132,7 +129,7 @@ type WebFetchBody =
 
 ## 服务
 
-`WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码正文；展示由工具负责。SSRF／私有网络防护尚未实现，因此在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
+`WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码正文；展示由工具负责。本地后端不会拦截私有网络目标；在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index fca76bf305..8809d62cd3 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.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 docs/testing.md
-testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
-testing.zh.md: 14b2549c4c3556b6d3bdd5b39d01dee885559dd1
+testing.md: 62ac375844b7f05970e944278fd44ac60f68b4b1
+testing.zh.md: 6353b2799b5760d8c45534d0264bf41be063d659
diff --git a/docs/testing.md b/docs/testing.md
index 296dd76911..62ac375844 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -12,7 +12,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
 - **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external behavior — transport contracts and presentation, while persisted logs pin assembled backend behavior. ACP boots the real automation-server example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless backend scenarios boot their explicit example composition through an unexported JSONL test driver, while `apps/cli` separately owns product `dsh run` acceptance. Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 - **Web browser snapshot** (`pnpm run test:web`; required Linux PR gate): Chromium compares replayed browser output with `apps/web/tests/snapshots/`. CI forces read-only `DSH_SNAPSHOT=replay`, never writing expected outputs; record/refresh stay local and every diff is reviewed ([web e2e lane](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md), [CI gate decision](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)). `test:web` [builds first](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md) for plugin CSS.
 
-Committed session-format JSONL uses the canonical packed-row layout, and the keyless snapshot gate discovers every such fixture by its `session` header. In-flight branches carrying older fixture edits merge current `master` and run the [temporary migrator](../scripts/migrate-packed-session-fixtures.ts) through `pnpm run migrate:packed-session-fixtures`; the [removal proposal](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) retires that command and these links after all affected branches converge.
+Committed session-format JSONL uses the canonical packed-row layout, and the keyless snapshot gate discovers every such fixture by its `session` header; the [temporary migrator](../scripts/migrate-packed-session-fixtures.ts) rewrites older fixture layouts.
 
 ## The with-key policy: inference is cheap here
 
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index 14b2549c4c..6353b2799b 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -12,7 +12,7 @@
 - **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
-签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
+签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture；[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)会改写旧版 fixture 布局。
 
 ## 带密钥策略：推理在这里很便宜
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index f6a41da266..58267e208d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -19,7 +19,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. |
 | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userInteraction (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. |
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
-| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables. |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
 | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence, edit absence, or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
@@ -248,7 +248,7 @@ Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. Eac
 
 Source: [`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
 
-The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables.
+The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables.
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index d54550f499..7feb2c7f07 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 3ce797e3dc91a279de1076a234c9ba0b476b3501
-config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
+config.md: cd778065801ae58a46703ae3447f835f80abf062
+config.zh.md: 6f6d37bfe8f7ad29c154d65c1763279655006435
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 3ce797e3dc..cd77806580 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -2,7 +2,7 @@
 
 English | [中文](config.zh.md)
 
-Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports, avoiding a second hand-maintained reference.
+Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports.
 
 ## Start from a real configuration
 
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index 621b5a75a9..6f6d37bfe8 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -2,7 +2,7 @@
 
 [English](config.md) | 中文
 
-Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及每个插件的参数。配置文件负责组合能力；每个包真正支持的字段和默认值由源码生成的配置目录负责记录，避免两份手写表格逐渐不一致。
+Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及每个插件的参数。配置文件负责组合能力；每个包真正支持的字段和默认值由源码生成的配置目录负责记录。
 
 ## 从真实配置开始
 
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 079dcf19ab..f4a719fdb2 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: ad0bd3696dbbdc4a89334932196d72a0afd3d209
-providers.zh.md: 84c01b9b79768f8e3b84faf3ff32bbdb0dfbe74d
+providers.md: 29575fcc860721d35588d82a15d9b97f1b7dea0e
+providers.zh.md: 4b5fd32224fbfe5b685f886375b590fa3704505d
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index ad0bd3696d..29575fcc86 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -122,7 +122,7 @@ Under `dsh`, references resolve from the inherited environment, the Models page'
 
 ## Point an agent at the new provider
 
-A configured route appears in the web model picker and can be switched at any time, which is how most people use it.
+A configured route appears in the web model picker and can be switched at any time.
 
 Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `agent-default-model`. There is no separate gesture.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index 84c01b9b79..4b5fd32224 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -122,7 +122,7 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 ## 让 agent（智能体）用上新提供方
 
-配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
+配好的路由会出现在 Web 的模型选择器里，随时可切。
 
 在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `agent-default-model` 段里。没有另一个单独的手势。
 
diff --git a/examples/acp-agent/tests/acp.e2e.ts b/examples/acp-agent/tests/acp.e2e.ts
index 16bf2fbf72..ce9a32c2ef 100644
--- a/examples/acp-agent/tests/acp.e2e.ts
+++ b/examples/acp-agent/tests/acp.e2e.ts
@@ -104,7 +104,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('acp-agent e2e: real prompt over
     const { client, updates } = spawned
 
     await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
-    // Any absolute cwd is honored now; use the temp `workdir` as this session's
+    // Any absolute cwd is honored; use the temp `workdir` as this session's
     // workspace (the bash tool will run there) — it need not equal the launch dir.
     const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] })
 
diff --git a/examples/acp-agent/tests/escalation.e2e.ts b/examples/acp-agent/tests/escalation.e2e.ts
index ee2d6122bc..b94a78aa30 100644
--- a/examples/acp-agent/tests/escalation.e2e.ts
+++ b/examples/acp-agent/tests/escalation.e2e.ts
@@ -20,7 +20,7 @@ import { cleanupAcpExampleTest } from './cleanup.ts'
  *
  * Keyless smoke: boot the REAL `cordis.yml` through the `dsh-acp-agent` bin as
  * an ACP subprocess and drive initialize + session/new — the real-Loader-path
- * guard (postmortem 0001) for THIS tree's export shapes, which now include the
+ * guard (postmortem 0001) for THIS tree's export shapes, including the
  * sandbox executor AND the approval service. No prompt is sent, so neither the
  * model nor a sandbox runner is ever exercised.
  *
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index e4fd9873aa..b09458ec3d 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -447,9 +447,9 @@ describe('headless stream-json snapshots', () => {
       binArgs: [credentialsConfigPath, 'say pong'],
       tsconfigPath,
       env: {
-        // A key that exists but no HTTP header can carry — the paste this
-        // change exists for. Before it, `fetch` refused to build the header
-        // and the turn ended on a retried ByteString TypeError.
+        // A key that exists but no HTTP header can carry — the paste the
+        // credential guard exists for: without it, `fetch` refuses to build
+        // the header and the turn ends on a retried ByteString TypeError.
         DEEPSEEK_API_KEY: 'sk-\u{1F600}pasted-from-a-chat-window',
         DEEPSEEK_BASE_URL: '',
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
@@ -466,8 +466,8 @@ describe('headless stream-json snapshots', () => {
     // page at all.
     expect(normalized).toContain('the API key resolved from DEEPSEEK_API_KEY contains characters')
     expect(normalized).toContain('the web Models page writes it')
-    // Neither the key nor the transport-level symptom it used to produce may
-    // reach the user: the code point of one character is still the key.
+    // Neither the key nor its transport-level symptom (the ByteString error)
+    // may reach the user: the code point of one character is still the key.
     expect(normalized).not.toContain('pasted-from-a-chat-window')
     expect(normalized).not.toContain('ByteString')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index 58e58a26fe..6eb3457bdb 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/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 native/landlock-run/README.md
-README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
-README.zh.md: 6ae8d7d1d5ae4f2bda90cbf6aa74321a0dab3cb9
+README.md: bf9b163d42a9b7402dbf4c045d47e7b8d36e15ab
+README.zh.md: 7bd4765a73f0d5df2a4710ce06ff319f6c902db6
diff --git a/native/landlock-run/README.md b/native/landlock-run/README.md
index fcb8e8249e..bf9b163d42 100644
--- a/native/landlock-run/README.md
+++ b/native/landlock-run/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 A [Landlock](https://landlock.io/) self-restrict-then-exec launcher for confining subprocesses on Linux, distributed as prebuilt per-platform npm packages plus a thin JS entry package that resolves the binary and speaks its CLI contract. Built for agent harnesses and other hosts that need to run untrusted commands under a filesystem allow-list without confining themselves.
 
-The first tool is **`landlock-run`** — a self-restrict-then-exec [Landlock](https://landlock.io/) launcher (~300 lines of C11 over the raw kernel UAPI, statically linked against musl). It installs a Landlock ruleset on itself and `exec`s the wrapped command; the ruleset is inherited across `execve`, so the command and every process it spawns run confined while the invoking process stays unrestricted. Fail-closed: if the kernel cannot enforce, it exits without running the command.
+The tool is **`landlock-run`** — a self-restrict-then-exec [Landlock](https://landlock.io/) launcher (~300 lines of C11 over the raw kernel UAPI, statically linked against musl). It installs a Landlock ruleset on itself and `exec`s the wrapped command; the ruleset is inherited across `execve`, so the command and every process it spawns run confined while the invoking process stays unrestricted. Fail-closed: if the kernel cannot enforce, it exits without running the command.
 
 ## Install
 
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index 6ae8d7d1d5..7bd4765a73 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -4,7 +4,7 @@
 
 一个 [Landlock](https://landlock.io/)「先限制自身、再执行」启动器，用于在 Linux 上限制子进程。它以按平台预构建的 npm 包以及一个轻量 JS 入口包的形式发布；入口包负责解析二进制文件并遵循其 CLI（命令行界面）约定。该启动器面向需要让不可信命令在文件系统允许清单约束下运行、同时保持自身不受限制的 agent harness（智能体框架）和其他宿主。
 
-第一个工具是 **`landlock-run`**：一个「先限制自身、再执行」的 [Landlock](https://landlock.io/) 启动器（基于原始内核 UAPI 编写，约 300 行 C11，并与 musl 静态链接）。它在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此命令及其产生的每个进程都在限制下运行，调用进程仍不受限制。它采用失败闭合：如果内核无法强制执行，则不运行命令并直接退出。
+该工具是 **`landlock-run`**：一个「先限制自身、再执行」的 [Landlock](https://landlock.io/) 启动器（基于原始内核 UAPI 编写，约 300 行 C11，并与 musl 静态链接）。它在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此命令及其产生的每个进程都在限制下运行，调用进程仍不受限制。它采用失败闭合：如果内核无法强制执行，则不运行命令并直接退出。
 
 ## 安装
 
diff --git a/native/landlock-run/packages/entry/src/main.c b/native/landlock-run/packages/entry/src/main.c
index e4e1f5c17e..6f2b0f5639 100644
--- a/native/landlock-run/packages/entry/src/main.c
+++ b/native/landlock-run/packages/entry/src/main.c
@@ -89,8 +89,7 @@ struct landlock_path_beneath_attr {
 
 /*
  * Newest ABI this build knows; the negotiation below scales the actual
- * ruleset down to what the running kernel supports (the best-effort compat
- * stance of the previous Rust launcher, made explicit).
+ * ruleset down to what the running kernel supports.
  */
 #define MAX_ABI 5L
 
@@ -141,8 +140,7 @@ struct cli {
 };
 
 /*
- * Hand-rolled argv parsing — four flags do not justify a parsing library,
- * and the previous Rust launcher made the same call for the same reason.
+ * Hand-rolled argv parsing — four flags do not justify a parsing library.
  * Returns 0 on success, else the process exit code (message already printed).
  */
 static int parse(int argc, char **argv, struct cli *cli) {
@@ -204,8 +202,7 @@ static int add_rule(int ruleset_fd, const char *path, uint64_t access) {
   }
   /* The kernel rejects directory-only accesses on a non-directory rule
    * (EINVAL), so a file grant keeps only the file-compatible bits — how the
-   * `--rw /dev/null` grant works. Same clamp the Rust crate's
-   * path_beneath_rules helper applied. */
+   * `--rw /dev/null` grant works. */
   struct stat st;
   if (fstat(path_fd, &st) == 0 && !S_ISDIR(st.st_mode)) {
     access &= LL_FS_EXECUTE | LL_FS_WRITE_FILE | LL_FS_READ_FILE | LL_FS_TRUNCATE | LL_FS_IOCTL_DEV;
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index 32695c475d..240a707c65 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -44,7 +44,7 @@ export type Config = LocalConfig
 export class SandboxBashExecutor extends LocalBashExecutor {
   static override inject = ['subprocess', 'sandbox', 'sandboxPolicy']
 
-  // No own Config: the sandbox default (mode + workspaceRoot) moved to
+  // No own Config: the sandbox default (mode + workspaceRoot) is owned by
   // ctx.sandboxPolicy, so this executor inherits LocalBashExecutor's Config
   // verbatim (the config catalog walks the inherited static).
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 597a17e088..d5cb0cb0e5 100644
--- 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: 1230149bd03d07cfb6208d82ea6ee8e81751b2c8
-README.zh.md: 168ac9f40e01dc786e29933afb0ebc4c3a745d0f
+README.md: 23b0acd096bb835ef57563337c91e5cf63b58677
+README.zh.md: 14ba749a0018bd6a63475bc0ab72c6fe6d26893a
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 1230149bd0..23b0acd096 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -13,7 +13,7 @@ This package owns the Service Definition role of the bash capability, split so e
 | `@deepseek-ai/dsh-bash-sandbox` | Service provider: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
 | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |
 
-The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same Service Definition; the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider. A containerized or remote executor slots in the same way.
+The split is a standard capability seam ([capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): `dsh-bash-sandbox` is a sandboxing executor behind the same Service Definition — the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider — and a containerized or remote executor slots in the same way.
 
 ## Service API (`ctx.bash`)
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 168ac9f40e..14ba749a00 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -13,7 +13,7 @@
 | `@deepseek-ai/dsh-bash-sandbox` | Service provider：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
 | `@deepseek-ai/dsh-tool-bash` | 基于 `ctx.bash`、面向模型的工具 schema |
 
-该拆分与 LLM（大语言模型） seam（`LlmService`／`LlmAdapter`）及 agent（智能体）工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一 Service Definition 之后；Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方。容器化或远程执行器也可以同样接入。
+该拆分是一个标准的能力 seam（[capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：`dsh-bash-sandbox` 是位于同一 Service Definition 之后的沙箱执行器——Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方——容器化或远程执行器也可以同样接入。
 
 ## 服务 API（`ctx.bash`）
 
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index 4f25e9f6aa..1d26227716 100644
--- 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: a06126e29ac5bf711bfbbb0d369e097b70918ba6
-README.zh.md: 947e994b59539d137cc1a332bb252a8325533747
+README.md: eb3365b009e3595230e5fb0f616079bd73c55840
+README.zh.md: d79201c756a26bbc343e2b284a803b0cf9aee69b
diff --git a/packages/bash/pwsh-local/README.md b/packages/bash/pwsh-local/README.md
index a06126e29a..eb3365b009 100644
--- a/packages/bash/pwsh-local/README.md
+++ b/packages/bash/pwsh-local/README.md
@@ -23,7 +23,7 @@ The package root exports the default and named `PwshLocalExecutor` plugin, its `
     pwshPath: C:\Program Files\PowerShell\7\pwsh.exe  # explicit executable; else well-known locations, then PATH
 ```
 
-## Behavior (and where it came from)
+## Behavior
 
 The Windows counterpart of `dsh-bash-local`, deliberately mirroring its semantics call-for-call:
 
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index 947e994b59..d79201c756 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -23,7 +23,7 @@
     pwshPath: C:\Program Files\PowerShell\7\pwsh.exe  # explicit executable; else well-known locations, then PATH
 ```
 
-## 行为（及其由来）
+## 行为
 
 作为 `dsh-bash-local` 的 Windows 对应物，逐调用地镜像其语义：
 
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index adbfd88851..69dae2915a 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -206,9 +206,9 @@ export function apply(ctx: Context, config: Config = {}): void {
    * {@link approveEscalation}. This tool contributes only the composition
    * guard (the fields are unadvertised without a sandboxing executor, yet
    * schema validation checks advertised keys only, so an unadvertised
-   * `sandbox_permissions` still reaches execute) and the approval ingredients
-   * The shared policy resolver is required whenever the executor advertises
-   * confinement, so a split composition fails at tool-plugin load.
+   * `sandbox_permissions` still reaches execute) and the approval
+   * ingredients. The shared policy resolver is required whenever the executor
+   * advertises confinement, so a split composition fails at tool-plugin load.
    */
   const approveBashEscalation = (
     mode: string,
diff --git a/packages/bash/tool-pwsh/README.i18n.yaml b/packages/bash/tool-pwsh/README.i18n.yaml
index ba4f758814..e272ee2993 100644
--- 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: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 54614fcfad1cdec5866aa3cc96e52983f4eb1642
+README.md: 7d8ee5fb69b71d8e8707d3e4ed07ebdda99f799f
+README.zh.md: 40984bbc36be4b5809e6ee4db21e52d842f50cdb
diff --git a/packages/bash/tool-pwsh/README.md b/packages/bash/tool-pwsh/README.md
index 78eb161f77..7d8ee5fb69 100644
--- a/packages/bash/tool-pwsh/README.md
+++ b/packages/bash/tool-pwsh/README.md
@@ -119,6 +119,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **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.
+- **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; the PTY backends are Linux/macOS-only.
 - **PowerShell-dialect contract** — the model must write PowerShell (native paths, `$env:` variables), not bash; there is no dialect translation.
 - **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.
diff --git a/packages/bash/tool-pwsh/README.zh.md b/packages/bash/tool-pwsh/README.zh.md
index 54614fcfad..40984bbc36 100644
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -119,6 +119,6 @@ ack 是固定短行；任务输出按读取有界。
 ## Known Limitations and Deferred Work
 
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
-- **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
+- **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端仅限 Linux/macOS。
 - **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index 9a85b02cba..b14635a868 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * @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
+ * manifest field). The plugin owns the browser-surface glue: 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
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index 9626e96e74..b67428953e 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -23,7 +23,7 @@ How live data reaches render code, and what may cross a business boundary:
 1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
 2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
 3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
-4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are grandfathered and get migrated to slots progressively).
+4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are the sanctioned exceptions).
 5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
 6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.
 
@@ -89,7 +89,7 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 
 ## New plugin package checklist
 
-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):
+Bringing up a new `packages/client/<name>` plugin package (ui-workspace is a complete example; ui-sidebar/ui-question are minimal skeletons):
 
 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 `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/*/*`.
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 5e2d35f4e8..1ae9269cb8 100644
--- 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: dba01cb8c487dbc670a471053f8cd12dd277ef4c
-README.zh.md: d12ef605f1113411a59c2d73c2bf105dfb021be8
+README.md: 07849f0728aee6076b15a8216ddcab08521994d6
+README.zh.md: a7996d0f7cc2948da82877c47f9acc805be2bba8
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index dba01cb8c4..07849f0728 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
 
 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` abstraction, 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. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. 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.
+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` abstraction, 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. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. 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).
 
 ## /api browser-trust fence
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index d12ef605f1..a7996d0f7c 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。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 浏览器信任栅栏
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index fbf995e652..7e9471bff8 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -3,7 +3,7 @@
 // Types and runtime protocol helpers/bounds come from the apiproxy api/ layer
 // (zero Node deps, browser-safe); AbstractApiClient is the client boundary.
 // NEVER import the package root: it drags bootHost/cordis into the browser bundle.
-// The ./api and ./client subpath exports are the browser-safe channels added for this.
+// The ./api and ./client subpath exports are the browser-safe channels.
 
 export type {
   ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
@@ -23,9 +23,9 @@ export type {
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
-// transportError moved down to the apiproxy api layer (it belongs beside
-// RpcResult, its subject); re-exported here so connection consumers keep one
-// contract entry point.
+// transportError lives in the apiproxy api layer (beside RpcResult, its
+// subject); re-exported here so connection consumers keep one contract
+// entry point.
 export {
   RpcId,
   SESSION_SEARCH_RESULT_LIMIT,
diff --git a/packages/client/connection/src/client/connection.ts b/packages/client/connection/src/client/connection.ts
index 18d22f878d..cfa608a394 100644
--- a/packages/client/connection/src/client/connection.ts
+++ b/packages/client/connection/src/client/connection.ts
@@ -1,7 +1,7 @@
 import type { IApiClient, HostFrame, MuxFrame, RpcRequest } from './api.ts'
 
-/** Reconnect/backoff tunables (deployment-varying — no hardcoded tunables; web-cordis §B.1 lists
- *  these as the future `ctx.connection` plugin Config). All fields optional; defaults below. */
+/** Reconnect/backoff tunables (deployment-varying — no hardcoded tunables; these become the
+ *  future `ctx.connection` plugin's Config). All fields optional; defaults below. */
 export interface ConnectionConfig {
   /** First-retry backoff cap in ms (jittered: actual delay is cap/2..cap). */
   backoffBaseMs?: number
@@ -10,9 +10,9 @@ export interface ConnectionConfig {
   /** Upper bound for the backoff cap in ms. */
   backoffMaxMs?: number
   /** Cap on waiting for both streams' onOpen before onConnected, in ms. The strict handshake
-   *  (audit C2) waits for mux+host stream establishment plus describe; a carrier that never
+   *  waits for mux+host stream establishment plus describe; a carrier that never
    *  fires onOpen (misbehaving proxy) must not wedge the connection forever — on timeout the
-   *  generation proceeds as connected and the live-gap repair path (audit S3) covers stragglers. */
+   *  generation proceeds as connected and the live-gap repair path covers stragglers. */
   streamOpenTimeoutMs?: number
 }
 
@@ -35,7 +35,7 @@ function sleep(ms: number, signal: AbortSignal): Promise<void> {
   })
 }
 
-/** Coarse connection state for the UI (audit C1): 'connected' after each generation's handshake,
+/** Coarse connection state for the UI: 'connected' after each generation's handshake,
  *  'reconnecting' the moment the generation fails (covers the whole backoff+retry span). */
 export type ConnectionState = 'connected' | 'reconnecting'
 
@@ -125,7 +125,7 @@ export class ConnectionController {
       })
 
       try {
-        // Strict readiness handshake (audit C2): describe proves unary reachability, onOpen
+        // Strict readiness handshake: describe proves unary reachability, onOpen
         // proves each physical stream is established before any frame —
         // only then may onConnected fire, so the resync it triggers cannot outrun the
         // subscribed baseline. The timeout guards against a carrier that never fires onOpen
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index d755f73354..b863745d3c 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1284,7 +1284,7 @@ export interface FixtureOptions {
 
 /** Inbox pump shared by both stream generators (FrameQueue pattern: ONE abort listener hung
  *  outside the loop — a per-iteration {once:true} listener never fires for non-final rounds and
- *  piles up for the stream's lifetime, audit C5). breakNow force-ends the stream without the
+ *  piles up for the stream's lifetime). breakNow force-ends the stream without the
  *  client's signal (timing hook: simulated connection loss). */
 class FxInbox<F> implements StreamConn<F> {
   private readonly inbox: RpcRequest<F>[] = []
@@ -1658,7 +1658,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
 
   /** history transit delay (timing hooks below); the page snapshot is taken at request time, like a real host. */
   let historyDelayMs = 0
-  /** One-shot history failure (timing hook: the doomed in-flight request of the S4 reconnect scenario). */
+  /** One-shot history failure (timing hook: a pre-disconnect history request already doomed when reconnect lands). */
   let failNextHistory = false
   /** Force-enders for currently open stream generators (timing hook: simulated connection loss). */
   const streamBreakers = new Set<() => void>()
@@ -1667,8 +1667,8 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   /** The single opt-in browser stress producer; normal fixture journeys never start it. */
   let activeReasoningChunkStorm: ReasoningChunkStormState | null = null
 
-  // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is ideally timed, which
-  // is exactly what masked the open-window and reconnect-gap bugs (audit S1/S3). These let
+  // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is
+  // ideally timed. These let
   // browser acceptance runs create slow-history, lost-frame, and reconnect
   // windows a real host produces naturally.
   const timingHooks = {
@@ -2691,8 +2691,8 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
  * Fixture platform subclass: there is no HTTP at all, so instead of a doFetch transport it
  * overrides the protocol-level virtuals (callUnary/openMux/openHost/respond) to dispatch
  * straight into the in-memory ApiProxy — while still minting rpcIds, fabricating the four
- * named full forms, and feeding the same tap as a real carrier. Delete when the fixture moves
- * to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
+ * named full forms, and feeding the same tap as a real carrier. TODO: delete when the fixture
+ * moves to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
  */
 export class FixtureApiClient extends AbstractApiClient {
   private readonly api: ApiProxy
diff --git a/packages/client/hmr/src/client/index.ts b/packages/client/hmr/src/client/index.ts
index 80fca3bf54..99f0938555 100644
--- a/packages/client/hmr/src/client/index.ts
+++ b/packages/client/hmr/src/client/index.ts
@@ -3,7 +3,7 @@
  *
  * Listens on the host's system SSE channel (`GET /plugins/events`); on a
  * `rebuilt` frame it reloads the entry's bundle and swaps the cordis
- * fiber in place. Every graph entry is a plugin bundle under the web2 model
+ * fiber in place. Every graph entry is a plugin bundle
  * — `immediately` rows differ only in stage-one prefetch (a boot
  * optimization), so all rostered plugin packages share these reload semantics;
  * normal packages (react family, cordis, shell, pure libs) are not entries
@@ -35,8 +35,7 @@
  * that arrival's task and may materialize the pre-rebuild bytes; the next
  * rebuilt frame self-heals.
  *
- * Why not the naive `entry.fiber.dispose()` → `entry.refresh()` path —
- * confirmed against vendor sources:
+ * Why not the naive `entry.fiber.dispose()` → `entry.refresh()` path:
  * 1. `Entry.fiber` is never cleared on dispose (vendor/loader/src/config/
  *    entry.ts assigns it only in `_init`), so `refresh()` hits its
  *    `if (this.fiber) return` guard and no-ops.
@@ -46,7 +45,7 @@
  *    `disabled: true` — permanently.
  * vendor/hmr's reload skeleton documents the fix: delete the runtime record
  * FIRST (`registry.delete` → case 4 returns early, the entry stays enabled),
- * then rebuild. We additionally clear `entry.fiber` ourselves so
+ * then rebuild. `entry.fiber` is additionally cleared so
  * `entry.refresh()` re-imports and re-plugins through the Loader's own
  * `_init` (entry-resolved config, automatic `fiber.entry` rebinding) instead
  * of hand-rolling `registry.plugin`. Client entries have exactly one fiber
diff --git a/packages/client/modules/src/client/index.ts b/packages/client/modules/src/client/index.ts
index c734ffb8f7..a516d6cef9 100644
--- a/packages/client/modules/src/client/index.ts
+++ b/packages/client/modules/src/client/index.ts
@@ -1,8 +1,8 @@
 /**
  * Browser half (the standard `./client` export): the module-system class and
  * wire contract, plus the enrollment plugin face. The module system itself is
- * built by the shell kernel BEFORE cordis exists (the bootstrap exception,
- * design §4.7 — the mechanism that loads plugins cannot arrive through
+ * built by the shell kernel BEFORE cordis exists (the bootstrap exception —
+ * the mechanism that loads plugins cannot arrive through
  * itself); the plugin face only enrolls that pre-existing instance by
  * providing it as `ctx.modules`. The kernel statically registers this module,
  * so the graph row for this package never triggers a real fetch — arrival is
diff --git a/packages/client/modules/src/client/manifest.ts b/packages/client/modules/src/client/manifest.ts
index ff7a7d8692..edb437e247 100644
--- a/packages/client/modules/src/client/manifest.ts
+++ b/packages/client/modules/src/client/manifest.ts
@@ -6,7 +6,7 @@
  * waiting, update/refresh) entirely on the vendored side while this package
  * owns code arrival.
  *
- * Lazy CJS model (web2 §0): executing a plugin bundle only REGISTERS its
+ * Lazy CJS model: executing a plugin bundle only REGISTERS its
  * factory (`window.__ModuleLoader__.load({id, factory})`); every module body
  * side effect — including CSS injection — lives inside the factory closure
  * and runs at materialization, not at script execution. Materialization
@@ -35,13 +35,13 @@ import type { ClientModuleSystem } from './system.ts'
 
 declare module 'cordis' {
   interface Context {
-    /** The client module system the web shell builds at boot (contract C5; provided by the `./client` wrapper plugin). */
+    /** The client module system the web shell builds at boot (provided by the `./client` wrapper plugin). */
     modules: ClientModuleLoader
   }
 }
 
 /**
- * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * One composed client entry pushed by the host (a graph row). Wire
  * single source: the host node half (package root) produces this same shape.
  * `immediately` marks stage-one prefetch; `inject` is informational graph
  * metadata (the authoritative edges live in each package's dshClient
@@ -143,7 +143,7 @@ export function parseBootManifest(wire: unknown): BootManifest {
   return { rev: graph.rev, modules, plugins }
 }
 
-/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff, contract C6). */
+/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff). */
 export interface ClientPluginHandoff {
   /** Plugin id (package name) — the registration key; must match the graph row being executed. */
   id: string
@@ -159,7 +159,7 @@ export interface ClientPluginHandoff {
 export interface DshWindow {
   /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
   __DSH_BOOT__?: unknown
-  /** Bundle registration sink; installed once per page by the {@link ClientModuleSystem} constructor (contract C6). */
+  /** Bundle registration sink; installed once per page by the {@link ClientModuleSystem} constructor. */
   __ModuleLoader__?: { load(handoff: ClientPluginHandoff): void }
   /**
    * Kernel handoff slot: the shell kernel stores the instance here right
@@ -185,7 +185,7 @@ export interface ClientModuleRecord {
 /**
  * The internal-contract subset the vendored Loader and the client HMR plugin
  * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
- * as `ctx.modules` (contract C5).
+ * as `ctx.modules`.
  */
 export interface ClientModuleLoader {
   /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
diff --git a/packages/client/modules/src/client/system.ts b/packages/client/modules/src/client/system.ts
index 5a6b11bb1e..5d99466409 100644
--- a/packages/client/modules/src/client/system.ts
+++ b/packages/client/modules/src/client/system.ts
@@ -54,7 +54,7 @@ const claimStyles = (id: string): string[] => {
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
  * contract documentation). Construction indexes the boot rows and installs the
- * `window.__ModuleLoader__` registration sink (contract C6) — once per page.
+ * `window.__ModuleLoader__` registration sink — once per page.
  */
 export class ClientModuleSystem implements ClientModuleLoader {
   readonly version = 'client'
diff --git a/packages/client/modules/src/index.ts b/packages/client/modules/src/index.ts
index ec3822e5a9..82070f9206 100644
--- a/packages/client/modules/src/index.ts
+++ b/packages/client/modules/src/index.ts
@@ -14,8 +14,8 @@
  * set with all current entries and flushes synchronously, so first scan and
  * steady state share one implementation. Package metadata (including the
  * negative "not a client package" verdict) is cached per name and never
- * expires — plugin-set changes take effect on restart per the config-source
- * ruling; bundle content changes reach the graph only through
+ * expires — plugin-set changes take effect on restart; bundle content
+ * changes reach the graph only through
  * {@link ClientModuleHostService.rebuilt}.
  * @module @deepseek-ai/dsh-client-modules
  */
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 734b158e66..a5d2c2a44f 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/runtime/README.md
-README.md: d4031c2e3b7730bdb0075ac84c50ad3e46ce63a2
-README.zh.md: ca6ac9f5e8efec3472c03b044739a9221e98183c
+README.md: 0a7d9975093da558af623ee9940f4be398526821
+README.zh.md: 41388e4ba564baa61cfdaaacb74f4f5ea053d41a
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index d4031c2e3b..0a7d997509 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects and the Chat-facing list, scope, and event-window state; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers, loading the current tail first and prepending one older page only when its consumer requests it. Each history snapshot exposes the raw window's absolute base sequence so a consumer detects a prepend even when the page adds no surface-visible node. WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager, and bridges the registry-invalidation frames to typed ctx events (`commands/changed`, `settings/changed`, `credentials/changed`, `models/changed`) so surface caches refetch without touching the stream. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`. The store also publishes one reference-stable whole-value map through `SessionSummary.projectionValues`, allowing global list consumers to reuse the same projections without creating per-session subscriptions.
+Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects and the Chat-facing list, scope, and event-window state; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers, loading the current tail first and prepending one older page only when its consumer requests it. Each history snapshot exposes the raw window's absolute base sequence so a consumer detects a prepend even when the page adds no surface-visible node. WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager, and bridges the registry-invalidation frames to typed ctx events (`commands/changed`, `settings/changed`, `credentials/changed`, `models/changed`) so surface caches refetch without touching the stream. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`. The store also publishes one reference-stable whole-value map through `SessionSummary.projectionValues`, allowing global list consumers to reuse the same projections without creating per-session subscriptions.
 
 ## Slot declaration injection
 
@@ -80,4 +80,4 @@ Changing the model selection can change or invalidate provider-side cache reuse;
 
 - **`loader.unload` is a stub** — it throws not-implemented; the client has no unload chain from fiber disposal through registration and style removal.
 - **Scope teardown is stage-driven, single-occupant today** — the staged session follows `list.current` exactly (staging is the open signal: the event window opens ⟺ the session is on stage); a removed-while-staged session's scope survives frozen until the stage moves on, not until true observer count reaches zero. Resolution (`binding()`/`scope()`) is pure addressing, render-safe; the render layer reads the current bundle through the `currentProvideInfo` observable. The staged state can widen to a multi-pane list when concurrent panes land.
-- **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches (the empty-state P0 postmortem).
+- **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches.
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index ca6ac9f5e8..41388e4ba5 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。约定：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
 
 ## Slot 声明注入
 
@@ -80,4 +80,4 @@ Host 所属的 LLM retry invariant 会在持久追加边界验证按提供方路
 
 - **`loader.unload` 是 stub**：它会抛出 not-implemented；客户端没有从 fiber dispose 到注册与样式移除的卸载链。
 - **scope 拆卸由阶段驱动，目前只能有一个占用者**：已 staged 的会话精确跟随 `list.current`（staging 就是打开信号：事件窗口打开 ⟺ 会话位于 stage）；在 staged 状态下被移除的会话，其 scope 会冻结保留，直到 stage 转向其他会话，而非直到真实观察者数量降为零。解析（`binding()`／`scope()`）只是纯寻址，可安全用于渲染；渲染层经 `currentProvideInfo` observable 读取当前 bundle。并发 pane 落地时，staged 状态可以扩展为多 pane 列表。
-- **插件组合包从该包导入值时必须使用 `/client` 子路径**：裸包名不在 loader externals 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配。这是空状态 P0 的事故复盘（postmortem）所记录的问题。
+- **插件组合包从该包导入值时必须使用 `/client` 子路径**：裸包名不在 loader externals 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配。
diff --git a/packages/client/runtime/src/client/contract/store.ts b/packages/client/runtime/src/client/contract/store.ts
index 7dc3b584ba..4592d0763d 100644
--- a/packages/client/runtime/src/client/contract/store.ts
+++ b/packages/client/runtime/src/client/contract/store.ts
@@ -2,9 +2,9 @@
  * Snapshot store engine (zustand vanilla + immer + subscribeWithSelector +
  * rafFlush middleware + opt-in persist + dev freeze) plus the declarative
  * shell over it: {@link defineStore} bakes an init/persist/actions literal
- * into a {@link StoreHandle}, the registration-side store seat of the slot
- * terminal design (§4). Lives in the React-free runtime (store-migration
- * ruling: the data layer owns its engine; web-react is shell-only React
+ * into a {@link StoreHandle}, the registration-side store seat of slot
+ * terminals. Lives in the React-free runtime (the data layer owns its
+ * engine; web-react is shell-only React
  * glue): engine products are bare observables — subscribe/getSnapshot/
  * update/set, NO selector hook. Hook synthesis is web-react's (the one
  * uSES bridge, cached per source at the binding site).
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index fe1ce8f7b0..766656a7f9 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -94,7 +94,8 @@ export { PendingWait } from './sessions/pending.ts'
 export type {
   PendingInteraction, PendingInteractionStatus, PendingKind, PendingPayloads,
 } from './sessions/pending.ts'
-// Projection value store (session-projection RFC, push model): host-computed
+// Projection value store (push model; see the session-projection subsystem
+// page, docs/subsystems/session-projection.md): host-computed
 // whole values per key; domains ship projection support with zero client code.
 export type {
   ProjectionsBaseline, ProjectionValueStore, SessionProjectionMap, UseProjection,
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
index b4eec9d6df..b251ed8ed5 100644
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -98,12 +98,12 @@ function questionInteractionStatus(
   return options.some(option => option.label === intent.approve) ? 'plan-review' : 'question'
 }
 
-/** Instance cluster + frame entry + the session list (see the web client architecture RFC). */
+/** Instance cluster + frame entry + the session list. */
 export class SessionManager {
   private readonly sessions = new Map<SessionId, Session>()
   /** Pre-instantiation buffer for answerable requests and the queued-turn snapshot, which history
    *  cannot reconstruct on open. Live requests remain until resolution; queue and replay duplicates
-   *  compact by identity. Instantiation replays and clears it, while removal drops it (audit S7). */
+   *  compact by identity. Instantiation replays and clears it, while removal drops it. */
   private readonly pendingBuffers = new Map<SessionId, RpcRequest<MuxFrame>[]>()
   /** Outstanding answerable interactions per session, keyed by their stable request identity.
    *  Manager-owned rather than read off Session instances because the sidebar must light up for
@@ -142,9 +142,9 @@ export class SessionManager {
   private selected: SessionId | undefined
 
   private listSnapshotCache: SessionListSnapshot
-  /** Entry-identity cache (§C.2 reference stability): list rebuilds reuse the previous entry
+  /** Entry-identity cache (reference stability): list rebuilds reuse the previous entry
    *  object when every field matches — wire refreshes mint all-new summary objects, so identity
-   *  must be recovered by value or every SessionListItem memo misses on every refresh (audit S5). */
+   *  must be recovered by value or every SessionListItem memo misses on every refresh. */
   private entryCache = new Map<SessionId, SessionListEntry>()
   private itemsCache: readonly SessionListEntry[] = []
   private readonly notifier = new Notifier(() => {
@@ -244,7 +244,7 @@ export class SessionManager {
   // ---- Instance management ----
 
   /**
-   * Drop a session instance (scope-prune companion, decision 12: instance
+   * Drop a session instance (scope-prune companion: instance
    * and scope share one lifecycle). The host session log is the durable
    * truth — a later get() lazily rebuilds and open() backfills history.
    * @param sessionId - the session to drop.
@@ -969,7 +969,7 @@ export class SessionManager {
   private buildListSnapshot(): SessionListSnapshot {
     const merged: TitledSessionSummary[] = this.summaries.map((summary) => {
       // List rows read the generic 'title' projection key (host-computed unit
-      // value; the bespoke session/title frame is retired).
+      // value; there is no dedicated title frame).
       const projectionStore = this.projectionStores.get(summary.sessionId)
       const title = projectionStore?.get('title')
       const projectionValues = projectionStore?.values()
@@ -1048,7 +1048,7 @@ function applyMutation(summaries: readonly SessionSummary[], mutation: SessionLi
     case 'remove':
       return summaries.filter(summary => summary.sessionId !== mutation.sessionId)
     case 'status':
-      // running:true doubles as the cross-端 blank flip (a blank session
+      // running:true doubles as the cross-client blank flip (a blank session
       // never runs, so the first running frame proves a message landed).
       return summaries.map(summary => summary.sessionId === mutation.sessionId
         && (summary.running !== mutation.running || (mutation.running && summary.blank))
diff --git a/packages/client/runtime/src/client/sessions/projection-store.ts b/packages/client/runtime/src/client/sessions/projection-store.ts
index 1af9ad726e..e2a95e4c86 100644
--- a/packages/client/runtime/src/client/sessions/projection-store.ts
+++ b/packages/client/runtime/src/client/sessions/projection-store.ts
@@ -1,6 +1,7 @@
 /**
- * Generic per-session projection value store (session-projection RFC, push
- * model): the host is the only computation site; the client holds finished
+ * Generic per-session projection value store (push model; see the
+ * session-projection subsystem page, docs/subsystems/session-projection.md):
+ * the host is the only computation site; the client holds finished
  * whole values per key — `key → { value, seq }` — seeded by the history tail
  * page's projections block and updated by `session/projection` push frames,
  * under the single rule **higher seq wins**. No client-side domain folding
@@ -16,11 +17,13 @@ import { Notifier } from './notifier.ts'
 // (`/types`, zero imports), never the package root: the root's dsh-agent →
 // dsh-session chain would drag the host `Context.sessions` merge into the
 // client program (one program must not hold both sides). No second
-// client-side "views" table (user ruling, RFC Alternatives).
+// client-side "views" table (rejected in the Alternatives of
+// .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
 export type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
 
 /**
- * The fifth framework hook seat (session-projection RFC): key-addressed
+ * The fifth framework hook seat (see the session-projection subsystem page,
+ * docs/subsystems/session-projection.md): key-addressed
  * projection reader delivered through the standard kit. `undefined` uniformly
  * means capability absent — host unit unmounted, or no baseline/frame has
  * carried the key yet. The selector overload mirrors useSession (per-key uSES
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index dcb5f71610..e137d9597b 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -1,8 +1,7 @@
 /**
  * SessionsService: root sessions service — list snapshot store (manager
  * projection; carries `current`, the persisted selection every
- * session-scoped surface keys off — migrated here from ui-layout per the
- * slot-parity design), Agent scope tree (mintScope pattern: no-op plugin
+ * session-scoped surface keys off), Agent scope tree (mintScope pattern: no-op plugin
  * Fiber + ctx.extend scope tag; one scope per session, agent id === session
  * id), stable SessionBinding cache, breadcrumb-route projection.
  *
@@ -605,7 +604,7 @@ export class SessionsService implements ISessions {
 
   /**
    * Lazily mint the scope + binding for an eligible session. Eligibility and
-   * prune share one predicate (decision 12): listed on the host or selected
+   * prune share one predicate: listed on the host or selected
    * through a retained subagent address. Breadcrumb-only ancestors remain
    * summary data and do not keep scopes alive.
    */
@@ -728,7 +727,7 @@ export class SessionsService implements ISessions {
   }
 
   /**
-   * One teardown for the whole per-session axis (decision 12): the scope
+   * One teardown for the whole per-session axis: the scope
    * fiber (cascading every actx-registered effect: input shell, slash
    * controller, popup, plugin stores, listeners), the session-keyed slot
    * stores, and the Session instance itself — the host session log is the
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 7c3d989248..1f351c9c4b 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -71,7 +71,7 @@ export class Session implements SessionFace {
   private openError: RpcError | null = null
   private openPromise: Promise<void> | null = null
   /** Bumped by resync to invalidate an in-flight doOpen: a reconnect must rebuild, never adopt
-   *  a pre-disconnect open whose history request is already doomed (audit S4). Stale doOpen
+   *  a pre-disconnect open whose history request is already doomed. Stale doOpen
    *  passes drop all writes once the generation moves on. */
   private openGeneration = 0
   private loadingOlder = false
@@ -106,8 +106,9 @@ export class Session implements SessionFace {
   private subscribedLastSeq: number | null = null
 
   /**
-   * Per-session projection value store (session-projection RFC, push model):
-   * finished whole values computed on the host, seeded by the tail page's
+   * Per-session projection value store (push model; see the session-projection
+   * subsystem page, docs/subsystems/session-projection.md): finished whole
+   * values computed on the host, seeded by the tail page's
    * projections block and updated by `session/projection` frames under the
    * one higher-seq-wins rule. Keys are read via `projections.faceOf(key)`
    * (the useProjection resolution face); the conversation snapshot never
@@ -325,7 +326,7 @@ export class Session implements SessionFace {
     return promise
   }
 
-  /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend (§D.2). */
+  /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend. */
   async loadOlder(): Promise<void> {
     if (this.openState !== 'open' || !this.hasMore || this.loadingOlder) return
     this.loadingOlder = true
@@ -341,7 +342,7 @@ export class Session implements SessionFace {
       }
       const tail = older[older.length - 1]
       if (tail === undefined || tail.event.seq + 1 !== this.baseSeq) {
-        // §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
+        // Continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
         console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
         this.hasMore = false
         this.conversation.prepend([], false)
@@ -364,7 +365,7 @@ export class Session implements SessionFace {
   /** Reconnect rebuild (manager calls this on onConnected for instances that were opened):
    *  reset the window and rerun open; pending waits for the baseline replay. Invalidates any
    *  in-flight open first — its history request rode the dead connection and must not settle
-   *  the fresh generation into 'error' (audit S4). */
+   *  the fresh generation into 'error'. */
   async resync(): Promise<void> {
     // The queue mirror is NOT cleared here: onConnected (which drives resync)
     // races the mux frames — the fresh generation's baseline may have landed
@@ -472,7 +473,7 @@ export class Session implements SessionFace {
    */
   handleRunning(running: boolean): void {
     // Turn-start conversion: a blank session never runs, so the first
-    // running:true proves another端's first message landed (设计稿 2.2).
+    // running:true proves another side's first message landed.
     if (running && this.blankBit) {
       this.blankBit = false
       this.notifier.markDirty()
@@ -546,7 +547,7 @@ export class Session implements SessionFace {
     this.scheduleConversation(this.conversation.rebuildRegistry())
   }
 
-  // ---- 私有 ----
+  // ---- Private ----
 
   /** Requested-frame arrival: the wait enters the pending map under its own key. */
   private mint(wait: PendingInteraction): void {
@@ -576,7 +577,7 @@ export class Session implements SessionFace {
         return
       }
       this.installWindow(result.value.events, result.value.hasMore, result.value.projections)
-      // Gap detection (§D.3-4): baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
+      // Gap detection: baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
       const tailSeq = this.windowTailSeq()
       if (this.subscribedLastSeq !== null && tailSeq !== null && this.subscribedLastSeq > tailSeq) {
         result = (await this.history({ maxMessages: PAGE_MESSAGES })).result
@@ -598,7 +599,7 @@ export class Session implements SessionFace {
   /** Install the history window + stitch the liveBuffer (seq is the sole dedup key).
    *  Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
    *  (doOpen flips it after install), so recursing would push every buffered event straight
-   *  back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1).
+   *  back into liveBuffer where nothing ever drains it — a silent drop loop.
    *  A carried projections block seeds the value store (higher seq wins, so a stale
    *  baseline cannot overwrite a newer push frame); the window events themselves are
    *  never folded — the host is the only computation site. */
@@ -629,7 +630,7 @@ export class Session implements SessionFace {
   }
 
   /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
-   *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
+   *  a seq gap -> buffer + tail-page repull instead of appending a hole (a gap is an
    *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
    *  raw range, which lets Conversation Definitions correlate every recorded event between its
    *  ends and lets a compaction checkpoint resolve its cited summary event. */
@@ -654,7 +655,7 @@ export class Session implements SessionFace {
     else if (publication === 'animation-frame') this.notifier.markFrameDirty()
   }
 
-  /** Resync-lite (audit S3): repull the tail page and stitch the liveBuffer through the shared
+  /** Resync-lite: repull the tail page and stitch the liveBuffer through the shared
    *  installWindow path. No openState transition — the UI keeps the current window (no loading
    *  flash); events arriving meanwhile detour to liveBuffer via the stitching flag. */
   private async repairGap(): Promise<void> {
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
new file mode 100644
index 0000000000..ce12d3a89c
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -0,0 +1,408 @@
+// TranscriptAdapter: the human transcript projected from the raw event window
+// in LOG order. The model-visible surface deliberately shadows replaced ranges,
+// so it is the wrong source for conversation a reader already saw; this adapter
+// keeps every append-origin event at its own log position and contributes one
+// marker node per landed compaction checkpoint. Node order is therefore
+// seq-monotonic by construction.
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+// Subpath export (package.json exports "./surface"): all value imports
+// go through it — the package root points at lib/index.js (needs a build) which the vite
+// browser bundle cannot resolve; surface.ts has no Node dependencies.
+import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
+// declaration of the checkpoint source, reachable as a TYPE from this program.
+// The package ROOT is not — it reaches dsh-session's root, whose Context merge
+// declares the HOST `sessions: SessionStore` against this program's
+// `sessions: ISessions` (TS2717, the one-program-per-side rule in
+// docs/development.md).
+import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
+import { toAssistantBlocks } from './conversation.ts'
+import { contextForm, contextProvenance } from './context-provenance.ts'
+import { SteeringHistory } from './steering-history.ts'
+import type { AssistantStepMetadata } from './assistant-timing.ts'
+import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
+
+/**
+ * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
+ * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
+ * import stays type-only because a value import would fail the client purity
+ * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
+ * forbidden in a browser bundle — while an erased type never reaches it.
+ */
+const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+
+/** In-window tool/call index entry used to materialize result cards. */
+interface CallIndexEntry {
+  name: string
+  argsRaw: string
+  turn: number
+  step: number
+  /** Unix epoch ms of the tool/call event. */
+  time: number
+  /** Wire view riding the tool/call (envelope-level; never inside the event). */
+  callView: ToolCallView | null
+}
+
+/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
+function materializeNode(
+  event: SessionEvent,
+  callIndex: ReadonlyMap<string, CallIndexEntry>,
+  resultView: ToolResultView | null,
+  steering: boolean,
+  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
+): ConversationNode {
+  switch (event.type) {
+    case 'user/message': {
+      // Injected context (plugin/goal/skill-invocation source) folds to a
+      // context node, not a user message; only a direct human prompt is a
+      // user node. A compaction checkpoint never reaches here
+      // (isCompactCheckpoint routes it away).
+      if (event.data.source.kind !== 'user') {
+        return {
+          kind: 'context', seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
+          provenance: contextProvenance(event.data.source),
+          form: contextForm(event.data.source),
+        }
+      }
+      if (steering) {
+        return {
+          kind: 'steering', messageId: event.data.id,
+          seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
+        }
+      }
+      return {
+        kind: 'user', seq: event.seq, time: event.time,
+        content: event.data.content, source: event.data.source,
+      }
+    }
+    case 'assistant/message':
+      return {
+        kind: 'assistant', seq: event.seq, time: event.time,
+        turn: event.data.turn, step: event.data.step,
+        blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
+        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
+      }
+    case 'tool/result': {
+      const result = event.data.message.content[0]
+      const callId = String(event.data.message.source.callId)
+      const call = callIndex.get(callId)
+      return {
+        kind: 'tool-result', seq: event.seq, time: event.time,
+        callId,
+        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
+        callTime: call?.time ?? null,
+        content: result.content, isError: result.isError === true,
+        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
+        meta: event.data.meta,
+        callView: call?.callView ?? null,
+        resultView,
+        subCalls: [],
+      }
+    }
+    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
+    can be append-origin, and each has a case above; reachable only if core
+    adds an eligible type. */
+    default:
+      return {
+        kind: 'unknown', seq: event.seq, time: event.time,
+        type: event.type, data: (event as { data?: unknown }).data,
+      }
+  }
+}
+
+/**
+ * Whether an event is a landed compaction checkpoint — all three conditions,
+ * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
+ * compaction seam's checkpoint plugin source, that REPLACED a surface range. A
+ * plugin-sourced `user/message` that appends is injected context (a
+ * session-reference card), not a compaction; a replacement `tool/result` is an
+ * in-place prune and a replacement `assistant/message` a generic rewrite, and
+ * both mark no boundary in the conversation.
+ * @param event - the raw window event.
+ * @returns true when the event compacted a surface range.
+ */
+function isCompactCheckpoint(event: SessionEvent): boolean {
+  if (event.type !== 'user/message') return false
+  const source = event.data.source
+  return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN
+    && isReplacementSurfaceEvent(event)
+}
+
+/** Whether an event contributes a node to the human transcript. */
+function isTranscriptEvent(event: SessionEvent): boolean {
+  return isAppendSurfaceEvent(event) || isCompactCheckpoint(event)
+}
+
+/**
+ * Concatenated text of a `compact/summary` payload, or null when it carries no
+ * usable text. The payload is a `ContentBlock[]` whose union is
+ * merge-extensible, so a non-text block is skipped rather than discarding the
+ * text beside it; a payload with no text block at all falls to null through the
+ * empty check.
+ */
+function compactSummaryText(event: SessionEvent): string | null {
+  const summary = (event.data as unknown as { summary?: unknown }).summary
+  if (!Array.isArray(summary)) return null
+  let text = ''
+  for (const block of summary as readonly unknown[]) {
+    const candidate = block as { type?: unknown; text?: unknown }
+    if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue
+    text += candidate.text
+  }
+  return text.trim() === '' ? null : text
+}
+
+interface CompactSummaryDetails {
+  readonly summary: string | null
+  readonly shadowedItemCount: number | null
+  readonly shadowedTokenCount: number | null
+}
+
+/** Recover human-facing summary material from one structurally narrowed wire event. */
+function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
+  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
+  const shadowedSeqs = data.shadowedSeqs
+  const tokenCount = data.shadowedTokenCount
+  return {
+    summary: compactSummaryText(event),
+    shadowedItemCount: Array.isArray(shadowedSeqs)
+      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      ? shadowedSeqs.length
+      : null,
+    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
+      ? tokenCount as number
+      : null,
+  }
+}
+
+/**
+ * One landed checkpoint -> the human-facing compaction marker. The summary text
+ * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
+ * `compact/summary` event), never from the framed checkpoint payload, which is
+ * an instruction envelope written for the model. A window cut that left the
+ * summary event outside soft-falls to `summary: null` (a non-expandable marker),
+ * the same posture as a call-less tool result.
+ */
+function materializeCompaction(
+  checkpoint: SessionEvent,
+  eventIndex: ReadonlyMap<number, SessionEvent>,
+): CompactionSummaryNode {
+  const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
+  let summary: string | null = null
+  let summaryEventSeq: number | null = null
+  let shadowedItemCount: number | null = null
+  let shadowedTokenCount: number | null = null
+  for (const seq of sources ?? []) {
+    const candidate = eventIndex.get(seq)
+    if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
+    const details = compactSummaryDetails(candidate)
+    summary = details.summary
+    summaryEventSeq = candidate.seq
+    shadowedItemCount = details.shadowedItemCount
+    shadowedTokenCount = details.shadowedTokenCount
+    break
+  }
+  return {
+    kind: 'compaction',
+    seq: checkpoint.seq,
+    time: checkpoint.time,
+    summary,
+    summaryEventSeq,
+    shadowedItemCount,
+    shadowedTokenCount,
+  }
+}
+
+/** Log-ordered human transcript over a paged raw event window (never consults surface order). */
+export class TranscriptAdapter {
+  /** Window events by seq, used to find the summary event cited by a checkpoint. */
+  private eventIndex = new Map<number, SessionEvent>()
+  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
+  private projected: ConversationNode[] = []
+  private callIdx = new Map<string, CallIndexEntry>()
+  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
+  private stepTimings = new Map<string, AssistantStepMetadata>()
+  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
+  private resultViews = new Map<number, ToolResultView>()
+  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
+  private readonly steeringHistory = new SteeringHistory()
+  /**
+   * Command lifecycle nodes by commandId (insertion = run order). The
+   * `command/run`/`command/done` pair is log-only, so it is not a surface
+   * event and never joins the transcript projection; this index folds the pair
+   * (done settles its run's node in place) and nodes() merges the products in
+   * by seq. Window cuts soft-fall like tool pairs: a done with no in-window
+   * run still builds a node.
+   */
+  private commandIdx = new Map<string, CommandNode>()
+  /** Projection revision, bumped only when a transcript node or a command node actually
+   *  changed, keying the nodes() result cache: an unchanged projection returns the previous
+   *  ARRAY reference, not just cached elements — the snapshot's reference-stability contract
+   *  starts here, and a chunk storm bumps nothing at all. */
+  private rev = 0
+  private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null
+
+  /**
+   * Window rebuild (after open/resync/page prepend): re-index the raw window
+   * and re-project the transcript.
+   * @param events - the new window contents (seq-ascending).
+   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
+   */
+  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
+    this.rev++
+    this.eventIndex = new Map()
+    this.callIdx = new Map()
+    this.resultViews.clear()
+    this.commandIdx = new Map()
+    this.steeringHistory.reset()
+    const steeringSeqs = new Set<number>()
+    this.stepTimings = new Map()
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i]
+      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
+      if (event === undefined) continue
+      this.eventIndex.set(event.seq, event)
+      this.indexCall(event, views?.[i])
+      this.indexCommand(event)
+      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
+      indexAssistantStepTiming(this.stepTimings, event)
+    }
+    // Indexes first, then project: a tool/result materializes against the
+    // complete call index, and a checkpoint against the complete event index.
+    const projected: ConversationNode[] = []
+    for (const event of events) {
+      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
+    }
+    this.projected = projected
+  }
+
+  /**
+   * Tail append (live session/event): index the event and, when it belongs to
+   * the transcript, extend the projection by one copy-on-write node so a
+   * published array never mutates. An event that changes no node (a chunk
+   * storm) bumps no revision, so nodes() keeps returning the same array
+   * reference.
+   * @param event - the live event (seq = window tail + 1).
+   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
+   */
+  append(event: SessionEvent, view?: ToolEventView): void {
+    this.eventIndex.set(event.seq, event)
+    this.indexCall(event, view)
+    const steering = this.steeringHistory.apply(event)
+    indexAssistantStepTiming(this.stepTimings, event)
+    if (this.indexCommand(event)) this.rev++
+    if (!isTranscriptEvent(event)) return
+    this.projected = [...this.projected, this.materialize(event, steering)]
+    this.rev++
+  }
+
+  /**
+   * The current transcript node array. Same revision -> same array reference
+   * (memo boundary); node objects are materialized once, so an unchanged node
+   * keeps its identity across appends.
+   * @returns transcript nodes in log order, command nodes merged in by seq.
+   */
+  nodes(): readonly ConversationNode[] {
+    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
+    // Command nodes fold outside the transcript (log-only events); merge by
+    // seq. Both inputs are seq-ascending (log order and run-index insertion
+    // order are the same order), so one linear merge keeps flow order.
+    let nodes = this.projected
+    if (this.commandIdx.size > 0) {
+      nodes = []
+      const commands = [...this.commandIdx.values()]
+      let next = 0
+      for (const node of this.projected) {
+        for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) {
+          nodes.push(cmd)
+        }
+        nodes.push(node)
+      }
+      for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd)
+    }
+    this.nodesResult = { rev: this.rev, value: nodes }
+    return nodes
+  }
+
+  /** Materialize one transcript event against the complete current indexes. */
+  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
+    return isCompactCheckpoint(event)
+      ? materializeCompaction(event, this.eventIndex)
+      : materializeNode(
+        event,
+        this.callIdx,
+        this.resultViews.get(event.seq) ?? null,
+        steering,
+        this.stepTimings,
+      )
+  }
+
+  /**
+   * Fold one command lifecycle event into its node (run mints, done settles in
+   * place; done-only soft-falls).
+   * @returns whether the command index changed, so callers can bump the revision.
+   */
+  private indexCommand(event: SessionEvent): boolean {
+    // Log-only plugin events: the host-side dsh-commands declaration cannot
+    // enter the client program, so this wire consumer narrows structurally
+    // (the same posture as tool/code-dispatch in session.ts).
+    if ((event.type as string) === 'command/run') {
+      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
+      this.commandIdx.set(data.commandId, {
+        kind: 'command', seq: event.seq, time: event.time,
+        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
+      })
+      return true
+    }
+    if ((event.type as string) !== 'command/done') return false
+    const data = event.data as unknown as {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
+    const run = this.commandIdx.get(data.commandId)
+    const sourceEventSeq = data.kind === 'success'
+      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
+      ? data.sourceEventSeq as number
+      : undefined
+    const outcome = {
+      kind: data.kind,
+      ...data.text === undefined ? {} : { text: data.text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    }
+    if (run === undefined) {
+      // Cross-window cut: the run page fell out of the window — build the
+      // node from the done alone (same soft-fall as a call-less tool result).
+      this.commandIdx.set(data.commandId, {
+        kind: 'command', seq: event.seq, time: event.time,
+        commandId: data.commandId, name: null, args: null, outcome,
+      })
+      return true
+    }
+    // Settle in place: a fresh node object (published references stay immutable).
+    this.commandIdx.set(data.commandId, { ...run, outcome })
+    return true
+  }
+
+  private indexCall(event: SessionEvent, view?: ToolEventView): void {
+    if (event.type === 'tool/result') {
+      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
+      return
+    }
+    if (event.type !== 'tool/call') return
+    this.callIdx.set(String(event.data.callId), {
+      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
+      time: event.time,
+      callView: view?.for === 'call' ? view.view : null,
+    })
+    // No backfill into already-materialized tool-result nodes for this callId
+    // (window order puts the call before its result; cannot happen on the normal path).
+  }
+}
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index 4f1ac11fcc..58d48affce 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -54,7 +54,7 @@ describe('runtime client apply', () => {
     const bench = await mount()
     expect(bench.ctx.get('slots') !== undefined).toBe(true)
     // The built-in 'root' declaration ships with this package's SlotsService
-    // (the SlotMap 'root' merge lives here since the slot-parity rework).
+    // (the SlotMap 'root' merge lives here).
     expect(bench.ctx.slots.spec('root')).toEqual({ kind: 'single', scope: 'root' })
     const sessions = bench.ctx.get('sessions')
     const workspaces = bench.ctx.get('workspaces')
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index 299e16785d..e6e36b37eb 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -140,7 +140,7 @@ export function plainTurn(startSeq: number, turn: number, ask: string, answer: s
   ]
 }
 
-/** Wrap raw events as view-less history entries (the wire shape history now returns). */
+/** Wrap raw events as view-less history entries (the wire shape history returns). */
 export function entries(events: readonly SessionEvent[]): { event: SessionEvent }[] {
   return events.map(event => ({ event }))
 }
diff --git a/packages/client/runtime/tests/projection-store.spec.ts b/packages/client/runtime/tests/projection-store.spec.ts
index 6547d365f5..5451b9e8b7 100644
--- a/packages/client/runtime/tests/projection-store.spec.ts
+++ b/packages/client/runtime/tests/projection-store.spec.ts
@@ -1,5 +1,6 @@
 /**
- * Projection value store (session-projection RFC, push model): the single
+ * Projection value store (push model; session-projection subsystem page:
+ * docs/subsystems/session-projection.md): the single
  * higher-seq-wins rule on both paths (a stale baseline cannot overwrite a
  * newer push frame; a replayed frame cannot regress), capability absence as
  * undefined, generation truncation, and the Session/manager wiring (tail-page
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index def97002f0..02df08de35 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -165,7 +165,7 @@ function chatSeqs(snapshot: ConversationSnapshot): number[] {
 }
 
 function histResponse(events: SessionEvent[], hasMore = false) {
-  // history now returns HistoryEntry[] ({event, view?}); these tests are view-less.
+  // history returns HistoryEntry[] ({event, view?}); these tests are view-less.
   return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
 }
 
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
new file mode 100644
index 0000000000..893635dcc7
--- /dev/null
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -0,0 +1,567 @@
+/**
+ * TranscriptAdapter over the raw append-only window: log-ordered projection of
+ * append-origin events, one marker per landed compaction, replacement copies
+ * hidden, command-lifecycle folding, node/array identity, call pairing, and
+ * host-provided wire views.
+ */
+
+import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
+import { describe, expect, it } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
+import { ev, plainTurn } from './event-script.ts'
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+/** A `compact/summary` event (log-only, no surfaceOp). */
+function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
+  return at(seq, {
+    type: 'compact/summary',
+    data: {
+      summary,
+      shadowedRange: { start: 1, end: 3 },
+      shadowedSeqs: [1, 3],
+      shadowedTokenCount: 100,
+      provider: 'fake',
+      model: 'compact-1',
+    },
+  })
+}
+
+/** The replacement user message a compaction backend lands (the checkpoint). */
+function checkpoint(
+  seq: number,
+  summarySeq: number,
+  { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: {
+    start?: number
+    end?: number
+    sourceEventSeqs?: number[]
+  } = {},
+): SessionEvent {
+  return at(seq, {
+    type: 'user/message',
+    surfaceOp: { op: 'replace', start, end },
+    sourceEventSeqs,
+    data: createUserMessage({
+      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }),
+  })
+}
+
+describe('TranscriptAdapter', () => {
+  it('projects a window starting past seq 0 at its own log positions', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(100, 5, '偏移问', '偏移答'))
+    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
+  })
+
+  it('appends incrementally keeping old node references (materialize-once identity)', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'))
+    const first = adapter.nodes()
+    adapter.append(ev.user(6, '追加'))
+    const second = adapter.nodes()
+    expect(second).toHaveLength(3)
+    expect(second[0]).toBe(first[0])
+    expect(second[1]).toBe(first[1])
+    expect(second).not.toBe(first) // a real change swaps the array
+  })
+
+  it('keeps the array reference across a chunk storm and swaps it when a node lands', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'))
+    const settled = adapter.nodes()
+    adapter.append(ev.chunkStart(6, 1))
+    expect(adapter.nodes()).toBe(settled)
+    adapter.append(ev.chunkText(7, 1, '流式'))
+    expect(adapter.nodes()).toBe(settled)
+    adapter.append(ev.assistant(8, 1, '流式完成'))
+    const finalized = adapter.nodes()
+    expect(finalized).not.toBe(settled)
+    expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 })
+  })
+
+  it('materializes every append-origin variant with field mapping', () => {
+    const adapter = new TranscriptAdapter()
+    const steering = createUserMessage({
+      content: [{ type: 'text', text: '插话' }],
+      source: { kind: 'user' },
+    })
+    adapter.reset([
+      ev.user(0, '用户'),
+      ev.assistant(1, 0, '助手'),
+      at(2, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, inserted: [steering],
+      } }),
+      at(3, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, removedCount: 1, inserted: [],
+      } }),
+      at(4, { type: 'user/message', surfaceOp: 'append', data: steering }),
+      at(5, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' },
+      }) }),
+      ev.toolCall(6, 0, 'c1', 'echo', '{"x":1}'),
+      ev.toolResult(7, 0, 'c1', '结果'),
+    ])
+    const nodes = adapter.nodes()
+    expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result'])
+    expect(nodes.find(n => n.kind === 'steering')).toMatchObject({ messageId: steering.id })
+    expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({
+      callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false,
+    })
+  })
+
+  it('identifies steering on the live append path', () => {
+    const adapter = new TranscriptAdapter()
+    const steering = createUserMessage({
+      content: [{ type: 'text', text: 'live steer' }],
+      source: { kind: 'user' },
+    })
+    adapter.reset([])
+    adapter.append(at(0, { type: 'agent/inbox/spliced', data: {
+      target: 'next-step', start: 0, inserted: [steering],
+    } }))
+    adapter.append(at(1, { type: 'agent/inbox/spliced', data: {
+      target: 'next-step', start: 0, removedCount: 1, inserted: [],
+    } }))
+    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: steering }))
+    expect(adapter.nodes()).toMatchObject([{ kind: 'steering', messageId: steering.id }])
+  })
+
+  it('does not mark queued, canceled, or non-user next-step messages as steering', () => {
+    const adapter = new TranscriptAdapter()
+    const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } })
+    const canceled = createUserMessage({ content: [{ type: 'text', text: 'canceled' }], source: { kind: 'user' } })
+    const context = createUserMessage({
+      content: [{ type: 'text', text: 'context' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    })
+    adapter.reset([
+      at(0, { type: 'agent/inbox/spliced', data: {
+        target: 'next-turn', start: 0, inserted: [queued],
+      } }),
+      at(1, { type: 'agent/inbox/spliced', data: {
+        target: 'next-turn', start: 0, removedCount: 1, inserted: [],
+      } }),
+      at(2, { type: 'user/message', surfaceOp: 'append', data: queued }),
+      at(3, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, inserted: [canceled],
+      } }),
+      at(4, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, removedCount: 1, inserted: [], outcome: 'canceled',
+      } }),
+      at(5, { type: 'user/message', surfaceOp: 'append', data: canceled }),
+      at(6, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, inserted: [context],
+      } }),
+      at(7, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, removedCount: 1, inserted: [],
+      } }),
+      at(8, { type: 'user/message', surfaceOp: 'append', data: context }),
+    ])
+    expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
+  })
+
+  it('materializes a skill-invocation injection as a named instructions context', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
+        source: { kind: 'user' },
+      }) }),
+      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
+        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
+      }) }),
+    ])
+    const nodes = adapter.nodes()
+    // The gesture stays a user bubble; the injected body folds to a context
+    // row named after the skill, presented as instructions.
+    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
+    expect(nodes[1]).toMatchObject({
+      provenance: { role: 'inject', label: 'hidden-demo' },
+      form: 'instructions',
+    })
+  })
+
+  it('skips events core does not call surface-eligible, marker or not', () => {
+    // The transcript is the append-origin surface, so log-only events (a chunk,
+    // a turn boundary, a `compact/*` record) and a future type core
+    // has not admitted contribute no node.
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      ev.turnStart(0, 1),
+      at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }),
+      compactSummary(2),
+      ev.user(3, '唯一的一条'),
+      ev.turnEnd(4, 1),
+    ])
+    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]])
+  })
+
+  describe('compaction markers', () => {
+    it('keeps the original messages and full tool output, hiding replacement copies', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '原始问题'),
+        ev.assistant(1, 0, '原始回答'),
+        ev.toolCall(4, 0, 'c1', 'echo', '{}'),
+        ev.toolResult(5, 0, 'c1', '完整工具输出'),
+        // A pruned tool/result copy: rewrites one node for the model, marks nothing.
+        at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: {
+          turn: 0, step: 0,
+          message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }),
+        } }),
+        compactSummary(7),
+        checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }),
+        // A regenerated assistant/message: also a silent model-only rewrite.
+        at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: {
+          turn: 0, step: 0,
+          message: createMessage({
+            role: 'assistant',
+            content: [{ type: 'text', text: '通用 replacement 副本' }],
+            source: { kind: 'model', ...{ provider: 'x', model: 'copy' } },
+          }),
+        } }),
+      ])
+      const nodes = adapter.nodes()
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([
+        ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8],
+      ])
+      expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] })
+      expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' })
+    })
+
+    it('adds one marker per landed compaction, in log order', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, 'a'),
+        compactSummary(1, [{ type: 'text', text: 'first' }]),
+        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
+        ev.user(3, 'b'),
+        compactSummary(4, [{ type: 'text', text: 'second' }]),
+        checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
+      ])
+      expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+        {
+          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
+          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+      ])
+    })
+
+    it('renders the marker when the shadowed range is outside the window and logs nothing', () => {
+      // Pagination spends no quota on replacement copies, so a page can carry
+      // a checkpoint whose surfaceOp.start lies below the window head. A
+      // surface fold would throw on the missing range and degrade with a
+      // console error; a log-ordered
+      // projection has no range to resolve.
+      const adapter = new TranscriptAdapter()
+      const noise = { error: console.error, warn: console.warn }
+      const logged: unknown[] = []
+      console.error = (...args: unknown[]) => logged.push(args)
+      console.warn = (...args: unknown[]) => logged.push(args)
+      try {
+        adapter.reset([
+          compactSummary(80, [{ type: 'text', text: '窗外范围' }]),
+          checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }),
+          ev.user(82, '压缩后的新问题'),
+        ])
+        expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
+        expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' })
+      } finally {
+        console.error = noise.error
+        console.warn = noise.warn
+      }
+      expect(logged).toEqual([])
+    })
+
+    it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => {
+      // A session-reference card carries the same plugin source shape; only the
+      // replacement marker makes an event a checkpoint.
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+          content: [{ type: 'text', text: '注入的上下文' }],
+          source: { kind: 'plugin', plugin: 'compact', form: 'instructions' },
+        }) }),
+      ])
+      expect(adapter.nodes()).toMatchObject([{
+        kind: 'context',
+        seq: 0,
+        provenance: { role: 'inject', label: 'compact' },
+        form: 'instructions',
+      }])
+    })
+
+    it('ignores a foreign plugin s replacement user/message', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '保留'),
+        at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({
+          content: [{ type: 'text', text: '别的插件重写' }],
+          source: { kind: 'plugin', plugin: 'not-compact' },
+        }) }),
+      ])
+      expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]])
+    })
+
+    it.each([
+      ['absent summary event', undefined],
+      ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
+      ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
+      ['an empty summary array', compactSummary(1, [])],
+      ['a non-array summary', compactSummary(1, 'plain string')],
+    ])('degrades %s to a non-expandable marker', (_label, summary) => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ...(summary === undefined ? [] : [summary]),
+        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
+      ])
+      expect(adapter.nodes()).toMatchObject([
+        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
+      ])
+    })
+
+    it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => {
+      // ContentBlock is merge-extensible and the payload type is ContentBlock[],
+      // so a non-text block must not discard recoverable text beside it.
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]),
+        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
+      ])
+      expect(adapter.nodes()).toEqual([
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+      ])
+    })
+
+    it('leaves the summary null when the checkpoint cites no source events', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([at(2, {
+        type: 'user/message',
+        surfaceOp: { op: 'replace', start: 0, end: 0 },
+        data: createUserMessage({
+          content: [{ type: 'text', text: '<context_checkpoint>x</context_checkpoint>' }],
+          source: { kind: 'plugin', plugin: 'compact' },
+        }),
+      })])
+      expect(adapter.nodes()).toEqual([{
+        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
+        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
+      }])
+    })
+
+    it('skips a cited non-summary seq before reaching the summary event', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '被压缩的问题'),
+        at(1, { type: 'compact/start', data: { turn: 0 } }),
+        compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]),
+        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }),
+      ])
+      expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
+    })
+
+    it('resolves the summary once an older page supplies the cited summary event', () => {
+      const adapter = new TranscriptAdapter()
+      const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
+      adapter.reset([landed])
+      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null })
+      adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed])
+      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' })
+    })
+
+    it('creates the marker on the live append path', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset(plainTurn(0, 0, 'a', 'b'))
+      adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }]))
+      adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] }))
+      const nodes = adapter.nodes()
+      // The compacted history is still there; the marker is one more row after it.
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
+      expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' })
+    })
+  })
+
+  it('returns call:null for a tool-result whose call fell outside the window', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')])
+    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
+  })
+
+  it('materializes a tool-result error field when present', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      at(0, { type: 'tool/result', surfaceOp: 'append', data: {
+        turn: 0, step: 0,
+        message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }),
+        error: { name: 'Boom', code: 'boom' },
+      } }),
+    ])
+    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
+  })
+
+  it('attaches wire views to the materialized result node', () => {
+    const adapter = new TranscriptAdapter()
+    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
+    adapter.reset([
+      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
+      ev.toolResult(1, 1, 'c1', 'listing'),
+    ], [callView, resultView] as never)
+    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
+      callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' },
+    })
+  })
+
+  it('attaches views on the live append path and defaults to null without views', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument
+    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
+    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
+    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
+      callView: { title: '回声' }, resultView: null,
+    })
+  })
+
+  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
+    const adapter = new TranscriptAdapter()
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
+    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never)
+    expect(adapter.nodes()[0]).toMatchObject({
+      kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' },
+    })
+  })
+
+  describe('command lifecycle nodes', () => {
+    it('folds a run/done pair into one settled node merged into flow order by seq', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '先说话'),
+        ev.commandRun(1, 'cmd-1', 'plan'),
+        ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'),
+        ev.assistant(3, 0, '然后回答'),
+      ])
+      const nodes = adapter.nodes()
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]])
+      expect(nodes[1]).toMatchObject({
+        kind: 'command', commandId: 'cmd-1', name: 'plan', args: '',
+        outcome: { kind: 'success', text: '已进入 plan mode' },
+      })
+    })
+
+    it('renders a run with no done as still executing (outcome null)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')])
+      expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null })
+    })
+
+    it('represents command input omitted by the host as null', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')])
+      expect(adapter.nodes()[0]).toMatchObject({
+        kind: 'command', name: 'feedback', args: null, outcome: null,
+      })
+    })
+
+    it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')])
+      expect(adapter.nodes()[0]).toMatchObject({
+        kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null,
+        outcome: { kind: 'error', text: '失败了' },
+      })
+    })
+
+    it('settles a live-appended done in place, keeping the node at the run seq', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset(plainTurn(0, 0, 'q', 'a'))
+      adapter.append(ev.commandRun(6, 'cmd-4', 'clear'))
+      const running = adapter.nodes().find(n => n.kind === 'command')
+      expect(running).toMatchObject({ outcome: null })
+      adapter.append(ev.commandDone(7, 'cmd-4'))
+      const settled = adapter.nodes().find(n => n.kind === 'command')
+      expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } })
+      // Settlement replaced the node object rather than mutating the published one.
+      expect(settled).not.toBe(running)
+    })
+
+    it('tails command nodes whose seq is past every transcript node', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')])
+      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
+    })
+
+    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '压缩前的问题'),
+        ev.commandRun(1, 'cmd-compact', 'compact'),
+        compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
+        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
+        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
+      ])
+      const nodes = adapter.nodes()
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
+      expect(nodes[1]).toMatchObject({
+        name: 'compact',
+        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
+      })
+      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
+    })
+  })
+
+  describe('assistant timing', () => {
+    const base = 1_700_000_000_000
+
+    it('derives step timing across a window rebuild (start + first token + completion)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.turnStart(0, 0),
+        ev.user(1, '问'),
+        ev.stepStart(2, 0),
+        ev.chunkStart(3, 0),
+        ev.chunkText(4, 0, '答'),
+        ev.chunkText(5, 0, '案'),
+        ev.assistant(6, 0, '答案'),
+        ev.turnEnd(7, 0),
+      ])
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
+      })
+    })
+
+    it('derives the same timing on the live append path, first token winning once', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.user(0, '问')])
+      adapter.append(ev.stepStart(1, 0))
+      adapter.append(ev.chunkText(2, 0, '首'))
+      adapter.append(ev.chunkText(3, 0, '次'))
+      adapter.append(ev.assistant(4, 0, '首次'))
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
+      })
+    })
+
+    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
+      })
+    })
+  })
+})
diff --git a/packages/client/ui-command/src/client/PopupSelectView.tsx b/packages/client/ui-command/src/client/PopupSelectView.tsx
index 456cdd4200..1b91a60d46 100644
--- a/packages/client/ui-command/src/client/PopupSelectView.tsx
+++ b/packages/client/ui-command/src/client/PopupSelectView.tsx
@@ -54,8 +54,8 @@ export function PopupSelectView({ popup, t }: PopupSelectViewProps) {
     cardRef.current?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: 'nearest' })
   }, [active])
 
-  // Focus ownership: the search input grabs on open (the design's
-  // transient-layer rule), and ANY outside pointer interaction dismisses —
+  // Focus ownership: the search input grabs on open, and ANY outside
+  // pointer interaction dismisses —
   // capture phase so a click landing anywhere else (textarea included)
   // closes the shell before its own handlers run; that click's target then
   // takes focus naturally, so no focusComposer here.
diff --git a/packages/client/ui-command/src/client/popup.ts b/packages/client/ui-command/src/client/popup.ts
index 5e20911820..1b30c18459 100644
--- a/packages/client/ui-command/src/client/popup.ts
+++ b/packages/client/ui-command/src/client/popup.ts
@@ -1,5 +1,5 @@
 /**
- * Headless popupSelect shell state (design §10): one controller per client
+ * Headless popupSelect shell state: one controller per client
  * session, owned by CommandService's per-session map and torn down by the
  * session scope disposer. The shell is a transient layer (never in the input
  * state machine): it loads options once, filters them locally against the
diff --git a/packages/client/ui-command/tests/popup-view.spec.tsx b/packages/client/ui-command/tests/popup-view.spec.tsx
index 0bbe01b4a9..e1459ce136 100644
--- a/packages/client/ui-command/tests/popup-view.spec.tsx
+++ b/packages/client/ui-command/tests/popup-view.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * PopupSelectView interaction spec (design §10.2): the search input takes
+ * PopupSelectView interaction spec: the search input takes
  * focus on open and plain typing filters locally, ↑↓ move the filtered
  * highlight while ←→ stay native to the input, Enter selects single-flight,
  * Escape dismisses back through focusComposer, outside pointerdown dismisses
diff --git a/packages/client/ui-command/tests/popup.spec.ts b/packages/client/ui-command/tests/popup.spec.ts
index 68e8084b80..ef1c464c66 100644
--- a/packages/client/ui-command/tests/popup.spec.ts
+++ b/packages/client/ui-command/tests/popup.spec.ts
@@ -1,5 +1,5 @@
 /**
- * PopupSelectController behavior (design §10.2/§10.3): one options load per
+ * PopupSelectController behavior: one options load per
  * open with local search filtering, filtered highlight movement,
  * single-flight select with open-time context, consume-on-success (CAS miss
  * benign), failure-keeps-open retry semantics for both options and onSelect,
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 1238e136d7..6c197a5107 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/ui-conversation/README.md
-README.md: d894d3e578f065e9cb2c45676224efd1f4f76fa8
-README.zh.md: ec99a8d7daa593cdf3014f292a095fb2fd6f39d3
+README.md: b57f88b5a030a6c20c957e26ea32fb125f106ab4
+README.zh.md: a8a8c4814086cad02c5416078f242ec92a7503d7
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index d894d3e578..b57f88b5a0 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -38,7 +38,7 @@ Per-session UI state for selection and the active view lives in the declared cha
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop controls), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
 
-The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
+The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy renders as the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index ec99a8d7da..a8a8c48140 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -38,7 +38,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止控件之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
-聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
+聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率渲染为 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 6d8e8e8c67..401d9883a6 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -160,7 +160,7 @@ export function apply(ctx: Context): void {
   // way: this package must not import the plugins that would know.
   const composerBlocks = new ComposerBlockRegistry()
 
-  // Decision 19/20: the input machine feeds every session-scope slot
+  // The input machine feeds every session-scope slot
   // component through the standard provide channel — the 'input' hook plus
   // the two public actions. Materialization is the shell creation trigger
   // (per-session lazy; scope disposer tears down).
@@ -241,7 +241,7 @@ export function apply(ctx: Context): void {
   }, ConversationSessionHeader)
 
   // The default composer body: its own single slot inside the composer
-  // chain's fallback (decision 20). Public machine surface arrives via the
+  // chain's fallback. Public machine surface arrives via the
   // provide channel above; the keyboard command face and the stop/retry
   // verbs ride this inject (package-internal — hub and bar are one plugin).
   // Session-maybe: with no current session the machine faces are absent and
@@ -252,7 +252,7 @@ export function apply(ctx: Context): void {
     locale: NS,
     // The two named control seats in the bar's tool row (plan beside the
     // access control, model right); empty until their owning plugins
-    // register (B ruling).
+    // register.
     children: {
       'conversation.input.plan': { kind: 'single', scope: 'session' },
       'conversation.input.model': { kind: 'single', scope: 'session' },
@@ -382,7 +382,7 @@ export function apply(ctx: Context): void {
   // The plan strip rides the input dock above the queue rows (same posture).
   ctx.plugin(todoDockEntry)
 
-  // The read-only queue dock entry (T9 file territory) rides the same
+  // The read-only queue dock entry rides the same
   // registration path into the input dock declared above.
   ctx.plugin(queueDockEntry)
 
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 44ae6f345a..cae17b3865 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -180,7 +180,7 @@ export function ChatView({
   const lastKeyRef = useRef<string | null>(null)
   const lastSteeringIdRef = useRef<string | null>(null)
   /** Flow tip signature — follow-scroll only when this moves, never on a
-   *  scroll-driven at-bottom chrome re-render (that was snapping inertial
+   *  scroll-driven at-bottom chrome re-render (which would snap inertial
    *  scrolls the rest of the way to the floor). */
   const followSigRef = useRef<string | null>(null)
 
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 972fba8710..a0d85e85e8 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -123,8 +123,8 @@ function TurnErrorItem({ node, t }: {
  * Display projection of reference forms in a user bubble (free geometry — no
  * textarea alignment constraint here); everything else stays plain text. The
  * logged model text remains the single truth; this is presentation only.
- * Plain-text `/name` / `@name` word-boundary tokens decorate (decision 21:
- * the sent text IS the reference — the bubble uses the same plainest token
+ * Plain-text `/name` / `@name` word-boundary tokens decorate (the sent text
+ * IS the reference — the bubble uses the same plainest token
  * scan as the composer, minus the lexicon: sent tokens were validated at
  * compose time, so shape alone decorates).
  */
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 56fca2381c..8d292abd53 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -79,14 +79,14 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * reads the global workspace list.
      */
     'conversation.hero.workspace': { kind: 'single'; scope: 'root'; owner: EmptyWorkspaceOwnerProps }
-    // 'conversation.input.overlay' merges in ui-slash (dedup ruling: the
-    // dependency direction is the hard constraint — ui-slash cannot import
+    // 'conversation.input.overlay' merges in ui-slash (the dependency
+    // direction is the hard constraint — ui-slash cannot import
     // this package, while this package's input contract already imports
     // ui-slash, so the type arrives transitively). The runtime declaration
     // (children table in apply.ts) stays here with the other input slots.
     /**
      * Stacked strip above the input (queue rows / GoalBar / attachments;
-     * design §6 MIX evidence: entries coexist in fixed order).
+     * entries coexist in fixed order).
      */
     'conversation.input.dock': { kind: 'list'; scope: 'session'; owner: InputZone }
     /** The band under the composer card (stats line family), rendered inside the bar's width column via the `footer` owner prop. */
@@ -97,7 +97,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'conversation.input.right': { kind: 'list'; scope: 'session'; owner: InputZone }
     /**
      * The default composer body: a single slot rendered as the composer
-     * chain's fallback (decision 20 — a real entry, not a chain rider, so a
+     * chain's fallback (a real entry, not a chain rider, so a
      * takeover election hides rather than unmounts it and the textarea DOM
      * survives). Session-maybe: the bar stays mounted across the
      * no-session/session transition — the no-workspace hero renders the SAME
@@ -111,7 +111,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     /**
      * The Plan-mode status seat in the composer tool row (left group,
      * right of the access-mode control). Declared by the composer-bar
-     * entry; empty until a plan plugin registers (B ruling: no placeholder
+     * entry; empty until a plan plugin registers (no placeholder
      * fallback).
      */
     'conversation.input.plan': { kind: 'single'; scope: 'session'; owner: InputControlOwnerProps }
@@ -124,7 +124,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 
   /**
    * ui-conversation's members of the session standard kit, provided through
-   * `sessions.provide` (decision 19/20): every session-scope slot component
+   * `sessions.provide`: every session-scope slot component
    * receives the input machine's state hook and the two public actions.
    */
   interface SessionStandardProps {
@@ -145,7 +145,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 export interface ConversationHeaderActionOwnerProps {}
 
 /**
- * The input-region slot currency (plan §1.4): dock/left/right entries read
+ * The input-region slot currency: dock/left/right entries read
  * the conversation snapshot and the live input state as owner props (both
  * are point-in-time snapshots — the dispatching skeleton re-renders on
  * either store's change, so entries stay current without subscribing).
@@ -353,7 +353,7 @@ export interface ComposerBarOwnerProps {
 
 /** Injected share of the composer-bar entry (package-internal faces). */
 export interface ComposerBarInjected {
-  /** The InputBar-exclusive keyboard/DOM command face (decision 20 private plane); absent with the session. */
+  /** The InputBar-exclusive keyboard/DOM command face (private plane); absent with the session. */
   keyboard: ComposerKeyboard | undefined
   /** Resolve one keyboard submission gesture against the current running state and persisted preference. */
   resolveSubmitMode: (
@@ -380,7 +380,8 @@ export interface ComposerBarInjected {
   hooks: {
     /** Latest surfaced notice (null after none; seq keys re-render of repeats). */
     notices: ObservableSnapshot<InputNotice | null>
-    /** Hot plain-text reference lexicon for the decoration scan (decision 21). */
+    /** Hot plain-text reference lexicon for the decoration scan (plain-text-reference decision;
+     *  see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md). */
     lexicon: ObservableSnapshot<ReadonlyMap<'/' | '@', readonly string[]>>
     /** Source name opened by the programmatic menu launcher, or null. */
     menuLauncher: ObservableSnapshot<string | null>
diff --git a/packages/client/ui-conversation/src/client/input/contract.ts b/packages/client/ui-conversation/src/client/input/contract.ts
index 6af78bdb72..ebc63b28e6 100644
--- a/packages/client/ui-conversation/src/client/input/contract.ts
+++ b/packages/client/ui-conversation/src/client/input/contract.ts
@@ -1,5 +1,5 @@
 /**
- * Frozen input-machine contract (design §9.1, eng. plan §3.9-3.12). Types
+ * Frozen input-machine contract. Types
  * only. Three-tier visibility: business packages see InputState via the
  * InputZone currency; the scoped input events carry the mutation verbs; the
  * conversation wiring layer alone sees the full SessionInput. InputMachine
@@ -56,7 +56,7 @@ export interface InputService {
 
 /**
  * The public input action face provided to every session-scope slot
- * component (decision 20): two stable-identity void callbacks, mirroring the
+ * component: two stable-identity void callbacks, mirroring the
  * useStore+actions convention. Command-style handles (track/arbitrate/space/
  * undo/paste/…) stay InputBar-private and never ride this face.
  */
@@ -75,7 +75,7 @@ export interface InputNotice {
 }
 
 /**
- * The InputBar-exclusive keyboard/DOM command face (decision 20): synchronous
+ * The InputBar-exclusive keyboard/DOM command face: synchronous
  * returns and event-handler semantics that must not enter the public provide
  * channel. Handed to the composer-bar entry through its own inject —
  * package-internal, never across a plugin boundary. The session shell
@@ -128,7 +128,7 @@ export interface EditRange extends EditSelection {
 
 /**
  * One reference chip occurrence, backing exactly one U+FFFC placeholder in
- * the draft (design §9.1 底层表示). Identity is occurrenceId — same-named
+ * the draft. Identity is occurrenceId — same-named
  * references stay independently addressable. label/clipboardText are the
  * owner's insert-time projections, cached so the chip survives owner loss
  * (invalid flips instead of dropping the occurrence).
@@ -157,7 +157,7 @@ export interface PasteComponent extends EditSelection {
 
 /**
  * Live paste-match attempt published while async matching may still upgrade
- * pasted tokens (design §9.1 剪贴板 round-trip). Any non-paste transaction,
+ * pasted tokens (the clipboard round-trip). Any non-paste transaction,
  * submit start, invalidate-paste, or release ends it; a paste-upgrade keeps
  * it current (later tokens re-CAS against the advanced draftRev).
  */
diff --git a/packages/client/ui-conversation/src/client/input/decorations.ts b/packages/client/ui-conversation/src/client/input/decorations.ts
index 25ebab9e32..bd3dd09040 100644
--- a/packages/client/ui-conversation/src/client/input/decorations.ts
+++ b/packages/client/ui-conversation/src/client/input/decorations.ts
@@ -1,5 +1,5 @@
 /**
- * Draft decoration pure core (design §9.1: chips render from the occurrence
+ * Draft decoration pure core (chips render from the occurrence
  * table at placeholder offsets; the claim token renders as a mirror-layer
  * highlight, the claim hint as ghost text). Zero React — the skeleton renders
  * the instructions; tests drive this directly.
@@ -24,7 +24,9 @@ export interface ChipRender {
 }
 
 /**
- * One plain-text reference range (decision 21): a `/name` or `@name` token
+ * One plain-text reference range (the plain-text-reference decision;
+ * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+ * a `/name` or `@name` token
  * whose name is on the trigger's lexicon. Pure derivation — editing the text
  * out of match shape simply drops the range next scan.
  */
@@ -50,8 +52,8 @@ export interface DraftDecorations {
 const TEXT_REF_RE = /(^|\s)([/@])([\w-]+)/g
 
 /**
- * Scan the draft for plain-text reference tokens against the hot lexicons
- * (decision 21). Word-boundary discipline: the trigger must sit at the draft
+ * Scan the draft for plain-text reference tokens against the hot lexicons.
+ * Word-boundary discipline: the trigger must sit at the draft
  * start or after whitespace ('x/name' never matches); the name must be an
  * exact lexicon member.
  * @param draft - draft text.
@@ -82,7 +84,7 @@ const EMPTY_LEXICON: ReadonlyMap<'/' | '@', readonly string[]> = new Map()
 /**
  * Derive the mirror-layer decorations from the input state.
  * @param state - published input state.
- * @param lexicon - optional per-trigger reference lexicons (decision 21 scan).
+ * @param lexicon - optional per-trigger reference lexicons (plain-text-reference scan).
  * @returns token range, chip instructions, text-ref ranges, and the ghost hint.
  */
 export function deriveDecorations(
diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts
index 3c6d1fd0fb..cf07101e56 100644
--- a/packages/client/ui-conversation/src/client/input/facade.ts
+++ b/packages/client/ui-conversation/src/client/input/facade.ts
@@ -66,7 +66,7 @@ export class SessionInputShell implements SessionInput {
   readonly state: SnapshotStore<InputState>
   /** Latest surfaced notice (null after clear); the wiring renders it beside the error strip. */
   readonly notices: SnapshotStore<InputNotice | null> = createSnapshotStore<InputNotice | null>(null)
-  /** The public provide-channel action face (one stable identity per session — decision 20). */
+  /** The public provide-channel action face (one stable identity per session). */
   readonly actions: InputActions = {
     setDraft: (text) => { this.setDraft(text) },
     submit: () => { this.submit('queue') },
@@ -198,7 +198,9 @@ export class SessionInputShell implements SessionInput {
 
   /**
    * Hot plain-text reference lexicon source for the decoration scan
-   * (decision 21): delegates to the controller's aggregated store. Stable
+   * (the plain-text-reference decision;
+   * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+   * delegates to the controller's aggregated store. Stable
    * identity per shell; without a pipeline the snapshot is the empty Map and
    * subscribers never fire.
    */
@@ -253,7 +255,8 @@ export class SessionInputShell implements SessionInput {
 
   /**
    * Insert plain reference text over the pick-time span (scoped insert-text
-   * event listener body, decision 21). Same CAS-then-splice shape as the
+   * event listener body; plain-text-reference decision, web-input-machine
+   * note). Same CAS-then-splice shape as the
    * consume-token span branch: the machine sees an ordinary draft-changed
    * transaction (one undo step), no occurrence is minted — the chip look is
    * a scan-derived decoration, never state.
@@ -339,7 +342,7 @@ export class SessionInputShell implements SessionInput {
   }
 
   /**
-   * Prompt serialization before the sink (design §3.12): expand each
+   * Prompt serialization before the sink: expand each
    * placeholder to its owner's model form via the session controller's
    * codec routing. Owner missing / serialize failure / disposal blocks the
    * send — notice + draft and chips retained, never a silent downgrade to
diff --git a/packages/client/ui-conversation/src/client/input/hub.ts b/packages/client/ui-conversation/src/client/input/hub.ts
index 560999aa21..4f6d62d662 100644
--- a/packages/client/ui-conversation/src/client/input/hub.ts
+++ b/packages/client/ui-conversation/src/client/input/hub.ts
@@ -1,7 +1,7 @@
 /**
  * InputHub: the InputService implementation (`ctx.conversation.input`) — one
  * SessionInputShell per session, created inside the sessions provide
- * materialization (decision 19: the 'input' standard-kit entry IS the
+ * materialization (the 'input' standard-kit entry IS the
  * creation trigger) and torn down by the scope disposer (instance-and-scope
  * share one lifecycle). The hub registers the three scoped input-mutation
  * listeners on each session's actx (the sole consumer side of the ui-slash
@@ -61,7 +61,7 @@ export class InputHub implements InputService {
     })
     this.shells.set(id, shell)
     // The one teardown axis: listeners, shell, and map entries all ride the
-    // scope fiber (decision 12 — nothing here outlives the scope).
+    // scope fiber (nothing here outlives the scope).
     actx.effect(() => {
       const offs = [
         actx.on('slash/input-begin-command', req =>
@@ -97,7 +97,7 @@ export class InputHub implements InputService {
   }
 
   /**
-   * The InputBar-exclusive keyboard command face (decision 20): the shell
+   * The InputBar-exclusive keyboard command face: the shell
    * satisfies it structurally; package-internal — handed through the
    * composer-bar entry's inject, never across a plugin boundary.
    * @param id - session id.
diff --git a/packages/client/ui-conversation/src/client/input/machine.ts b/packages/client/ui-conversation/src/client/input/machine.ts
index ec62eb63b4..68147adc38 100644
--- a/packages/client/ui-conversation/src/client/input/machine.ts
+++ b/packages/client/ui-conversation/src/client/input/machine.ts
@@ -1,6 +1,6 @@
 /**
- * InputMachine: the pure per-session input state machine (design §9.1, eng.
- * plan §3.9-3.12). Events in, effects out; zero React / DOM / cordis / ambient
+ * InputMachine: the pure per-session input state machine.
+ * Events in, effects out; zero React / DOM / cordis / ambient
  * clock. Package-private — the SessionInput shell is the only caller and the
  * sole executor of the returned effects.
  *
@@ -23,10 +23,10 @@ import type {
 /** The object-replacement character backing every chip occurrence in the draft. */
 export const PLACEHOLDER = ''
 
-/** The machine never writes the queue; the wiring layer overlays the T9 store projection. */
+/** The machine never writes the queue; the wiring layer overlays the queue store's projection. */
 const EMPTY_QUEUE: InputState['queue'] = []
 
-/** Undo ring depth (design §9.1: bounded self-managed transaction log). */
+/** Undo ring depth (bounded self-managed transaction log). */
 const LOG_LIMIT = 100
 
 /** Exhaustiveness backstop for the closed InputEvent / guard unions. */
@@ -68,7 +68,7 @@ function diffEdit(prev: string, next: string): EditRange {
 
 /**
  * Expand the draft's placeholders into their occurrences' clipboard text
- * (decision 16: the persistence mirror and clipboard both write this
+ * (the persistence mirror and clipboard both write this
  * projection — U+FFFC never leaves the machine). Table order is offset
  * order, so one linear walk pairs placeholders with entries.
  * @param state - published input state.
@@ -194,7 +194,7 @@ export class InputMachine {
   /**
    * Reconcile the occurrence table with one edit (old-draft coordinates):
    * entries past the range shift by the length delta; entries whose
-   * placeholder sits inside the replaced range go away whole (design §9.1: a
+   * placeholder sits inside the replaced range go away whole (a
    * deletion/replacement intersecting a placeholder acts on the whole chip).
    */
   private reconcile(range: EditRange): void {
@@ -338,7 +338,7 @@ export class InputMachine {
   /**
    * Owner-resolution style bits: exactly the listed occurrences render
    * invalid. Not a transaction — the draft, revision, and undo log are
-   * untouched (design §9.1: invalidation never deletes or rewrites chips).
+   * untouched (invalidation never deletes or rewrites chips).
    */
   private onSetInvalid(invalidIds: readonly number[]): InputEffect[] {
     const ids = new Set(invalidIds)
diff --git a/packages/client/ui-conversation/src/client/queue/store.ts b/packages/client/ui-conversation/src/client/queue/store.ts
index 35364383c6..ca94348b88 100644
--- a/packages/client/ui-conversation/src/client/queue/store.ts
+++ b/packages/client/ui-conversation/src/client/queue/store.ts
@@ -10,7 +10,7 @@ import type { QueuedMessage } from '../input/contract.ts'
 
 /**
  * Project a session's transient inbox rows as a bare observable (subscribe/getSnapshot).
- * The wiring layer (T5) overlays this onto InputState.queue; the runtime
+ * The wiring layer overlays this onto InputState.queue; the runtime
  * QueuedMessage and the input-contract QueuedMessage are structurally
  * identical.
  * @param session - the resident session face.
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
index be088d61ef..f9190da3e4 100644
--- a/packages/client/ui-conversation/src/client/service.ts
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -57,7 +57,7 @@ export interface IConversation {
 
 /** Scope-addressed conversation service (root singleton, provided as `conversation`). */
 export class ConversationService extends Service implements IConversation {
-  /** The per-session input machine registry (InputService face, design §5.2). */
+  /** The per-session input machine registry (InputService face). */
   readonly input: InputService
   /** The per-session composer-block registry. */
   readonly blocks: ComposerBlocks
diff --git a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
index 98e98f0f01..e700b112b4 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
@@ -10,8 +10,7 @@
 // buttons must be reachable no matter how long the command is.
 // One-shot: the buttons disable
 // after a click and the panel leaves (the InputBar returns) on the broadcast
-// resolved frame. The draft's "Always allow this type" is deferred with
-// grant storage.
+// resolved frame.
 
 import { useMemo, useState } from 'react'
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
diff --git a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
index 1f0bedded7..b6b62468d1 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
@@ -1,8 +1,8 @@
 /** Composer context-occupancy meter: a ring beside the send button fed by the
  * `contextPressure` projection, with a click-open panel of the heuristic
  * `contextBreakdown` composition (system prompt, tools, conversation).
- * Renders nothing until a provider reports both pressure and a route capacity
- * (same gate as the stats row used). */
+ * Renders nothing until a provider reports both pressure and a route
+ * capacity. */
 
 import { useEffect, useRef, useState } from 'react'
 import type { UseProjection } from '@deepseek-ai/dsh-client-runtime/client'
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
index 8440dacd94..f9c2eb0968 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -81,7 +81,6 @@ export function ConversationRoot({
   const zone: InputZone | undefined =
     session === undefined || inputState === undefined ? undefined : { session, input: inputState }
 
-  // Flow optimization — worth a close PR review for code/boundary issues.
   // The chip is a selector; label resolution walks the flow top-down:
   //   1. a just-picked workspace (pending) → its title;
   //   2. cold start, no session yet → placeholder ("Choose workspace");
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index 1caefd2ecf..8d11e3c5ea 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -1,7 +1,6 @@
-// DetailsPanel, P-I minimal form: close button + the selected call's args and
+// DetailsPanel: close button + the selected call's args and
 // result — args as JSON, the result raw except for a terminal-card call, whose
-// Output section is the command's terminal card. The three-段 Switch /
-// Prev-Next stepping / See-in-trajectory are deferred (ledger). Reads the
+// Output section is the command's terminal card. Reads the
 // selection from the shared chat
 // store (conversation writes, this panel reads — the cross-registration
 // share the store seat exists for) and derives the call material from the
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 3bbba68dd8..fdbf28c74b 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -395,7 +395,7 @@
   cursor: pointer;
 }
 
-/* Plain-text reference highlight (decision 21): a pure range mark over the
+/* Plain-text reference highlight: a pure range mark over the
    draft's own glyphs — advance untouched, so the two layers cannot drift.
    Chip family colors; clone keeps rounded ends on soft-wrap fragments. */
 .textRef {
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 78db735f61..0c097b6114 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -1,5 +1,5 @@
-/** The default composer body: the 'conversation.composer.bar' slot entry
- * (decision 20). Machine state arrives through the standard provide channel
+/** The default composer body: the 'conversation.composer.bar' slot entry.
+ * Machine state arrives through the standard provide channel
  * (useInput + inputActions); the keyboard/DOM command face and stop arrive
  * through this entry's own inject, whose hooks compartment binds
  * useNotices/useLexicon; layout-phase inputs (variant, placeholder,
@@ -385,7 +385,7 @@ export function InputBar({
   const backdrop: ReactNode[] = []
   {
     // Segment boundaries: the token range end, every chip offset, and every
-    // text-ref range (decision 21) — merged in draft order (the sources never
+    // text-ref range — merged in draft order (the sources never
     // overlap: chips sit on placeholders, text-refs on plain tokens, the
     // claim token only leads).
     let cursor = 0
@@ -430,7 +430,7 @@ export function InputBar({
         )
         cursor = chip.offset + 1 // the placeholder char the chip stands for
       } else {
-        // Plain-range highlight (decision 21): the glyphs stay the
+        // Plain-range highlight: the glyphs stay the
         // textarea's (advance untouched); the mark paints the chip look.
         backdrop.push(
           <mark key={`ref-${b.ref.start}`} className={css.textRef} data-decoration="text-ref">
@@ -529,7 +529,6 @@ export function InputBar({
             {rightItems}
             {renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
-            {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
             {interruptible && (
               <Tooltip label={t('input.stop')} side="top" delayMs={500}>
                 <button
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index e9076fa994..aaed8153da 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -226,10 +226,10 @@ describe('Enter semantics', () => {
   })
 })
 
-describe('running and lock semantics (queue cut 1)', () => {
+describe('running and lock semantics', () => {
   it('running keeps the input free (typing + Enter queue) while the primary turns stop', () => {
     const { textarea, button, stop, sink } = bench({ running: true, draft: '排队消息' })
-    expect(textarea.disabled).toBe(false) // running no longer locks
+    expect(textarea.disabled).toBe(false)
     fireEvent.change(textarea, { target: { value: '排队消息2' } })
     fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(sink).toHaveBeenCalledWith('排队消息2', 'queue')
@@ -429,8 +429,8 @@ describe('running and lock semantics (queue cut 1)', () => {
     // scrollport element holds both layers.
     expect(scroll.contains(textarea)).toBe(true)
     expect(scroll.contains(backdrop)).toBe(true)
-    // The glyph layer carries the draft and nothing else: with one scrollport
-    // it no longer pads its own height to match a second box's scroll extent.
+    // The glyph layer carries the draft and nothing else — no height padding
+    // to a second box's scroll extent.
     expect(backdrop.textContent).toBe('line\n'.repeat(40))
   })
 
@@ -659,7 +659,7 @@ describe('decorations', () => {
     expect(shell.snapshot.draft).toBe('参考 \uFFFC 内容')
   })
 
-  it('a lexicon-matched plain token renders the text-ref mark (decision 21)', () => {
+  it('a lexicon-matched plain token renders the text-ref mark', () => {
     const lexicon = new Map<'/' | '@', readonly string[]>([['/', ['fixture-demo']]])
     const { view, shell } = bench({ lexicon })
     act(() => { shell.setDraft('use /fixture-demo now') })
@@ -671,7 +671,7 @@ describe('decorations', () => {
   })
 })
 
-describe('insertText (decision 21 scoped event body)', () => {
+describe('insertText (scoped event body)', () => {
   it('splices plain text over the span and reports success as true', () => {
     const { shell } = bench({ draft: '/fix' })
     const ok = shell.insertText('/fixture-demo ', { start: 0, end: 4, draftRev: shell.snapshot.draftRev })
@@ -721,7 +721,7 @@ describe('strips and variants', () => {
 })
 
 describe('command launcher chrome and control seats', () => {
-  it('renders the command launcher; the Access chip is absent without the permissions projection; plan/model seats render EMPTY without entries (B ruling)', () => {
+  it('renders the command launcher; the Access chip is absent without the permissions projection; plan/model seats render EMPTY without entries', () => {
     const { view, slotCalls } = bench()
     expect(view.getByLabelText('命令')).toBeTruthy()
     // Capability absent (no projection value): the chip renders nothing.
diff --git a/packages/client/ui-conversation/tests/input-machine.spec.ts b/packages/client/ui-conversation/tests/input-machine.spec.ts
index 89737d7106..da0c40e549 100644
--- a/packages/client/ui-conversation/tests/input-machine.spec.ts
+++ b/packages/client/ui-conversation/tests/input-machine.spec.ts
@@ -1,6 +1,6 @@
 /**
- * InputMachine unit account (design §9.1, eng. plan §3.9-3.12): the submit
- * plane carried over from the InputCore era (adjudication, span CAS, drift
+ * InputMachine unit account: the submit
+ * plane (adjudication, span CAS, drift
  * guard, anti-backwash), plus the occurrence table (shift / whole-chip
  * deletion / same-name independence), the self-managed undo log (typing
  * coalescing, paste two-stage undo, redo chain), consume-token guards, the
@@ -625,7 +625,7 @@ describe('input-machine: projectClipboard', () => {
   })
 })
 
-describe('decorations: scanTextRefs (decision 21)', () => {
+describe('decorations: scanTextRefs', () => {
   const LEX: ReadonlyMap<'/' | '@', readonly string[]> = new Map([
     ['/', ['commit-helper', 'fixture-demo']],
     ['@', ['worker-1']],
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index 65fa5705ca..1efd959493 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * Impact-matrix projection tests (design §5.2 影响矩阵, row by row): what each
+ * Impact-matrix projection tests (row by row): what each
  * phase projects onto the InputBar — enter routing, visuals (token color /
  * hint / pending), edit freedom, and the published currency's claim seat.
  * React over jsdom per the client testing discipline; the machine is real.
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index 94d348d17a..9f6b679b60 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * Scenario-chain integration (design §8 A/C/D/H/I): the real per-session
+ * Scenario-chain integration (scenarios A/C/D/H/I): the real per-session
  * SlashController pipeline over a real session scope (SessionsService over
  * a listed host session) + a command source implementing the decision
  * table's relevant cells + the real SessionInput machine (scoped-event
diff --git a/packages/client/ui-conversation/tests/todo-panel.spec.tsx b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
index 445d8139e6..fafe6e6dc4 100644
--- a/packages/client/ui-conversation/tests/todo-panel.spec.tsx
+++ b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
@@ -86,8 +86,8 @@ describe('TodoPanel', () => {
   it('marks every parallel active item, and counts them all in the header', () => {
     render(<TodoPanel todos={PARALLEL} t={t} />)
     fireEvent.click(screen.getByRole('button', { expanded: false }))
-    // The old unconditional cap made this list unreachable: three items carry
-    // the in-progress glyph at once, and the header counts all three.
+    // An unconditional in-progress cap would make this list unreachable: three
+    // items carry the in-progress glyph at once, and the header counts all three.
     const statuses = screen.getAllByRole('listitem').map(li => li.getAttribute('data-status'))
     expect(statuses.filter(s => s === 'in_progress')).toHaveLength(3)
     expect(screen.getByText('跑后台构建')).toBeTruthy()
diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx
index 967066c056..09386f5d47 100644
--- a/packages/client/ui-layout/src/client/AppFrame.tsx
+++ b/packages/client/ui-layout/src/client/AppFrame.tsx
@@ -183,8 +183,8 @@ export function AppFrame({
       </div>
       <>
         {/* Both column occupants stay at fixed tree positions from first
-            paint — no loading gate (user ruling: the bare status line looked
-            worse than the shell's own pending rendering). The conversation
+            paint — no loading gate: a bare status line reads worse than
+            the shell's own pending rendering. The conversation
             is session-maybe; the strict details entry naturally renders
             empty while no session is current. */}
         <CenterColumn>{renderSlot('conversation', {})}</CenterColumn>
diff --git a/packages/client/ui-layout/tests/app-frame.spec.tsx b/packages/client/ui-layout/tests/app-frame.spec.tsx
index a8a988574b..65de5a640e 100644
--- a/packages/client/ui-layout/tests/app-frame.spec.tsx
+++ b/packages/client/ui-layout/tests/app-frame.spec.tsx
@@ -164,7 +164,7 @@ describe('AppFrame', () => {
   })
 
   it('renders both column occupants before baselines settle (no loading gate)', () => {
-    // User ruling: the bare loading status looked worse than the shell's own
+    // No loading gate: a bare loading status reads worse than the shell's own
     // pending rendering — both occupants mount from first paint.
     baselinesReady.current = false
     const { slotCalls } = mountFrame()
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index ce82152632..ec20685def 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/ui-models/README.md
-README.md: 66f23d3f77adae23fcebd3adbb6c5c47ce16ae2f
-README.zh.md: d0a5ad465e713680757a3e3734fc97dc31280a2e
+README.md: 9841ced87ae345c685c59e96a7b9088d474181f5
+README.zh.md: bb1445fbc8093d356ce838948b8338fa04919063
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index 66f23d3f77..9841ced87a 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint) and each adapter's model catalog. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which took the whole provider out of the model picker. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint) and each adapter's model catalog. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which would hide even the models that support the level. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index d0a5ad465e..bb1445fbc8 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会连支持该档位的模型也一并隐藏。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个标识唯一的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上抛出原始正则表达式错误。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个标识唯一的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上抛出原始正则表达式错误。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index f055b325a5..b8b4459c77 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -118,7 +118,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
     // next unmet gate — which is satisfied, and reads as a second, false fault.
     || keyFailure !== undefined
     // Same for the route id, and it must be tested rather than assumed: the
-    // fallback arm below reads "no models yet", so an unmet route gate used to
+    // fallback arm below reads "no models yet", so an unmet route gate would
     // fall through to it and contradict the filled-in list right above.
     || route.length === 0 || routeInvalid || routeTaken
     ? undefined
diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css
index 94f08d523a..8facc3a110 100644
--- a/packages/client/ui-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-models/src/client/ModelsSection.module.css
@@ -435,12 +435,12 @@
   line-height: 18px;
 }
 
-/* Model list, shared with the pi-ai provider form (PR #1368): one bordered
+/* Model list, shared with the pi-ai provider form: one bordered
    entry per model, id and display name on the row, capacities behind the
-   row's own disclosure. The token names are this file's, not that branch's —
+   row's own disclosure. The rules use this stylesheet's token vocabulary —
    `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and
-   `--dsw-alias-text-primary` are undefined here and resolve to their
-   light-mode literals, which is the defect this section was just moved off. */
+   `--dsw-alias-text-primary` are undefined here and would resolve to their
+   light-mode literals. */
 .modelList {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index da4c8972ae..09167b55cb 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -655,7 +655,7 @@ describe('ModelsSection', () => {
     expect((ids[0] as HTMLInputElement).value).toBe('deepseek-v4-flash')
 
     // An id that is only whitespace is as absent as an empty one, and a padded
-    // id no longer slips past the duplicate check against its own twin.
+    // id is a duplicate of its trimmed twin.
     expect(validateDeepSeekModels([{ id: '   ' }])).toEqual({ index: 0, key: 'modelIdRequired' })
     expect(validateDeepSeekModels([{ id: 'model' }, { id: 'model ' }]))
       .toEqual({ index: 1, key: 'modelIdDuplicate' })
@@ -714,7 +714,7 @@ describe('ModelsSection', () => {
   })
 
   it('clears an inherited override with an unset op, never a whole-section replace', async () => {
-    // The old path rebuilt the whole user section to clear one inherited field.
+    // A whole-section replace would clobber sibling overrides to clear one field.
     const { replace, update, mutate } = await mountSection()
     fireEvent.click(screen.getByText(en.customized))
     const url = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 7e5ef5f36e..9ff96cdebc 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -706,11 +706,11 @@ describe('hand-declared providers', () => {
   })
 
   it('scopes each card to fields a provider can actually own', async () => {
-    // Reasoning effort used to sit here. It is a per-MODEL capability and the
+    // Reasoning effort is a per-MODEL capability and the
     // models under one provider disagree about it, so a provider-scoped
-    // control could only be set to a value some of them reject — which took
-    // the whole provider out of the picker. The composer's model picker owns
-    // the choice, and a switch there records provider+model+effort together.
+    // control could only be set to a value some of them reject — which would
+    // take the whole provider out of the picker. The composer's model picker
+    // owns the choice, and a switch there records provider+model+effort together.
     const fields = () => [...document.querySelectorAll('input,select')]
       .map(el => el.getAttribute('aria-label')).filter(Boolean)
 
@@ -804,8 +804,8 @@ describe('hand-declared providers', () => {
     const routeField = screen.getByLabelText(en.customRoute)
     fireEvent.change(routeField, { target: { value: 'https://acme.test/v1' } })
 
-    // A digit-leading id used to pass every check this card makes and then
-    // fail at the credential seam with a raw regular expression: the
+    // Without this check a digit-leading id passes the card and fails at the
+    // credential seam with a raw regular expression: the
     // reference derives as `123_API_KEY`, and a credential reference is a
     // POSIX shell identifier, which cannot start with a digit.
     fireEvent.change(routeField, { target: { value: '123' } })
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 5c8e7eaab6..06dfe45bd8 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/ui-primitives/README.md
-README.md: 098a202a4ac9ee263ce1beaaee7a8624ebf26b80
-README.zh.md: def1907f81d06b5afdf19af5f19ba17a269ed3c1
+README.md: a9c802c1e43cf06aa0492b39d5052e882a72d9e6
+README.zh.md: 9e67488ccc1d70263bd0b91d167c4c251ee95926
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 098a202a4a..a9c802c1e4 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock.
 
 ## Hover cards
 
@@ -46,5 +46,5 @@ None; this package neither assembles nor sends a provider request.
 - **Glyph-level icons are redrawn approximations** — the fish logo (and the sparkle held by ui-conversation) come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
 - **Pill and Input have no design source** — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
 - **No `Active` StateDot variant** — the supported states are done, warning, ongoing, and error.
-- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props with the previous hardcoded strings as defaults. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing renders exactly the pre-localization output. `WebBlock` does not yet follow this pattern: its source-list and fetch truncation notes and its empty-search note stay inline Chinese, pending the same label-prop treatment.
+- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing gets those defaults. `WebBlock` does not yet follow this pattern: its source-list and fetch truncation notes and its empty-search note stay inline Chinese, pending the same label-prop treatment.
 - **`TerminalBlock` is not a terminal emulator** — it renders settled or still-running command output, not an interactive session: SGR color and attributes are honored, and so are the in-line cursor movements a progress line uses — carriage return, backspace, erase-in-line, tab stops and character width. Absolute cursor positioning, screen clearing, and alternate-screen sequences are stripped. Basic-16 magenta and cyan have no token equivalent and stay literal rgb.
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index def1907f81..9e67488ccc 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。约定：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。
 
 ## 悬浮卡片
 
@@ -46,5 +46,5 @@
 - **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
 - **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
 - **StateDot 没有 `Active` 变体**：支持的状态为 done、warning、ongoing 和 error。
-- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表截断提示与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
+- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费方得到的就是这些默认值。`WebBlock` 尚未跟进这一模式：它的来源列表截断提示与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
 - **`TerminalBlock` 不是终端模拟器**：它渲染已结束或仍在运行的命令输出，而不是交互式会话：SGR 颜色与属性会被遵循，进度行所用的行内光标移动同样被遵循——回车、退格、行内擦除、制表位与字符宽度。绝对光标定位、清屏与备用屏幕序列会被剥离。基础 16 色中的洋红与青色没有对应 token，保持字面 rgb。
diff --git a/packages/client/ui-primitives/src/TerminalBlock.tsx b/packages/client/ui-primitives/src/TerminalBlock.tsx
index 4cec564da6..e28c3fd657 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.tsx
+++ b/packages/client/ui-primitives/src/TerminalBlock.tsx
@@ -221,8 +221,8 @@ export function TerminalBlock({
   // Read from the parsed lines the card actually renders, not from the raw text:
   // output that is only escapes or control bytes (a lone reset, an OSC title, an
   // erase) survives `text.trim()` yet parses to nothing visible. Judging it on
-  // the raw text drew an output box of blank rows plus a copy control for
-  // invisible bytes, and hid the placeholder that belongs there.
+  // the raw text would draw an output box of blank rows plus a copy control
+  // for invisible bytes, and hide the placeholder that belongs there.
   const empty = lines.every(line => line.every(span => span.text.trim() === ''))
   const { hidden, capped, headLines, tailLines } = headTailCap(lines.length, maxLines, expanded)
 
diff --git a/packages/client/ui-primitives/src/Tooltip.module.css b/packages/client/ui-primitives/src/Tooltip.module.css
index 56b93f5be1..c5f92c8482 100644
--- a/packages/client/ui-primitives/src/Tooltip.module.css
+++ b/packages/client/ui-primitives/src/Tooltip.module.css
@@ -1,6 +1,6 @@
 /* Visual spec mirrors deepsuite @deepseek/ui Tooltip.css (size m, no arrow),
-   except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, and radius
-   10 -> 8 by product ruling: tooltip-bg plate,
+   except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, radius
+   10 -> 8, a tooltip-bg plate,
    one text color across both themes (the plate stays dark in light and dark
    mode). Behavior (fixed positioning off the anchor rect) is local — the
    upstream Floating stack is intentionally not vendored. */
diff --git a/packages/client/ui-primitives/src/markdown/highlight.ts b/packages/client/ui-primitives/src/markdown/highlight.ts
index d0727c833a..d9a4d53ec2 100644
--- a/packages/client/ui-primitives/src/markdown/highlight.ts
+++ b/packages/client/ui-primitives/src/markdown/highlight.ts
@@ -84,8 +84,7 @@ const LAZY_GRAMMARS = new Map<string, () => Promise<LangModule>>([
  * the markdown-fence aliases `CodeBlock` uses and the file-extension hint ids
  * the read tool's `langFromPath` emits, so both callers resolve the same
  * grammars. The JS family maps to the TypeScript grammar (see {@link LANGS} for
- * the JSX/TSX approximation), unchanged from when this was the only
- * non-shell/JSON grammar. A value not in {@link LANGS} names a
+ * the JSX/TSX approximation). A value not in {@link LANGS} names a
  * {@link LAZY_GRAMMARS} entry loaded on first use.
  */
 const LANG_ALIASES = new Map<string, string>([
diff --git a/packages/client/ui-primitives/tests/ansi.spec.ts b/packages/client/ui-primitives/tests/ansi.spec.ts
index 008165f5ab..dbd520d626 100644
--- a/packages/client/ui-primitives/tests/ansi.spec.ts
+++ b/packages/client/ui-primitives/tests/ansi.spec.ts
@@ -359,10 +359,10 @@ describe('parseAnsiLines: line-end state and column widths', () => {
 
 describe('parseAnsiLines: bounded state and true widths', () => {
   it('emits one canonical sequence per boundary however the state was reached', () => {
-    // Colors that never fully reset used to accumulate raw sequence history per
-    // cell, so every boundary re-emitted the whole chain: 3200 such cells
-    // produced 25 MB and eventually a RangeError. The state is normalized now,
-    // so the emitted text stays linear in the number of cells.
+    // Colors that never fully reset would, under a raw per-cell sequence
+    // history, re-emit the whole chain at every boundary: 3200 such cells
+    // produce 25 MB and eventually a RangeError. Normalized state keeps
+    // the emitted text linear in the number of cells.
     let input = ''
     for (let index = 0; index < 2000; index += 1) input += `${ESC}[3${index % 6 + 1}mx`
     const emitted = parseAnsiLines(`${input}\rz`)[0] ?? []
diff --git a/packages/client/ui-primitives/tests/hover-card.spec.tsx b/packages/client/ui-primitives/tests/hover-card.spec.tsx
index d5b580045a..53d5d2bcf7 100644
--- a/packages/client/ui-primitives/tests/hover-card.spec.tsx
+++ b/packages/client/ui-primitives/tests/hover-card.spec.tsx
@@ -91,8 +91,8 @@ describe('HoverCard', () => {
 
   it('reaching the card inside the grace keeps it open without restarting the dwell', () => {
     // The portaled card is a React child of the wrapper, so the pointer
-    // arriving on it re-enters the wrapper — the gesture the 8px anchor gap
-    // used to make impossible.
+    // arriving on it re-enters the wrapper — the gesture an anchor gap
+    // would make impossible.
     const { wrapper } = mount()
     fireEvent.pointerEnter(wrapper)
     act(() => { vi.advanceTimersByTime(500) })
diff --git a/packages/client/ui-primitives/tests/icons.spec.tsx b/packages/client/ui-primitives/tests/icons.spec.tsx
index 678eb9754e..5c2fe88608 100644
--- a/packages/client/ui-primitives/tests/icons.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.spec.tsx
@@ -16,7 +16,7 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full P-I set (46 deepsuite + 17 figma extracts + three product glyphs outside those sets)', () => {
+  it('exports the full icon set (46 deepsuite + 17 figma extracts + three product glyphs outside those sets)', () => {
     expect(iconNames.length).toBe(66)
   })
 
diff --git a/packages/client/ui-primitives/tsdown.config.ts b/packages/client/ui-primitives/tsdown.config.ts
index cbabf4f2a1..4e623511f1 100644
--- a/packages/client/ui-primitives/tsdown.config.ts
+++ b/packages/client/ui-primitives/tsdown.config.ts
@@ -2,7 +2,7 @@ import { clientOnly } from '../tsdown.client.ts'
 
 /**
  * ui-primitives is browser-only, but its lib bundle IS imported under plain
- * Node now that the web shell is a lib (dsh-client-web's lib chain reaches
+ * Node because the web shell is a lib (dsh-client-web's lib chain reaches
  * this package). CSS imports are therefore stubbed to empty modules instead
  * of externalized — the hashed class maps only matter in bundler contexts
  * (loader module table / vite source paths), which compile src directly and
diff --git a/packages/client/ui-settings/src/client/contract/slots.ts b/packages/client/ui-settings/src/client/contract/slots.ts
index 8516ce8860..aeaafe8232 100644
--- a/packages/client/ui-settings/src/client/contract/slots.ts
+++ b/packages/client/ui-settings/src/client/contract/slots.ts
@@ -62,7 +62,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * OnboardingSurface primitive (mask, opaque stage, `#root` inert) and
      * renders null while its private facts are still loading — the shell
      * paints no chrome of its own, so a mounted-but-deciding step shows and
-     * blocks nothing (the reload white-flash fix; a bare unwrapped step
+     * blocks nothing (prevents a white flash on reload: a bare unwrapped step
      * would render without mask or stage).
      */
     'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
@@ -87,7 +87,7 @@ export interface SettingsHeaderOwnerProps {
  * arrives through their own inject faces and stores).
  */
 export interface SettingsSectionOwnerProps {
-  /** Marker field: section owner props are intentionally empty for now. */
+  /** Marker field: section owner props are intentionally empty. */
   children?: never
 }
 
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
index 711f4171e4..a98d8ea26e 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
@@ -96,7 +96,7 @@
 }
 
 /* Brand group (figma I133:7632): the full wordmark rides the text ink
-   (figma-flows ruling: main-screen instance is black; blue is brand
+   (figma flows: the main-screen instance is black; blue is brand
    emphasis only). A button only in behavior (New Session shortcut): the
    pointer cursor is the sole affordance — no hover chrome on the mark. */
 .brand {
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index b7c737a98f..c9d9e0b69c 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/ui-skill/README.md
-README.md: 44953fe36ad337d0dd70e4d8c0cc2372b8924c9b
-README.zh.md: 3a8ac86d13114bdbbb78c33d907aba7bb1a10fc2
+README.md: 677ac215d299fca695a6b27c564779ef1d3fd6ee
+README.zh.md: 8f1f69b26a932aaa300bdda1d4ec7b2fa749fe3c
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index 44953fe36a..677ac215d2 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Skill invocation source, browser half: registers the `/`-trigger `skill` source into `ctx.slash`. Ordinary-session candidates come from the `skill.list` RPC addressed by the per-call `ClientSessionContext` projection's `{sessionId}`, with the host resolving `cwd` from the session header. The host serves every user-invocable skill; a `modelInvocable: false` entry (a `disable-model-invocation` skill, whose only entry point is this path) wears the user-only marker as a description prefix in the active language. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry and `connection/reset` clears everything. Results filter by `startsWith(query)`.
 
-A pick lands the literal `/name ` text and the prompt ships the same literal (decision 21) — this source implements no adjudication hooks and no reference codec (the legacy `<skill>name</skill>` form is gone with the removal cut). Determinism lives host-side: the pre-step gesture boundary (`dsh-tool-skill`) recognizes whitespace-bounded `/name` tokens naming user-invocable skills anywhere in a user message and injects the rendered `<skill_content>` for every front end, so a menu pick, a hand-typed token, and a TUI/ACP prompt all load the skill the same way. A name shared with a host command still resolves to the command: adjudication claims the line client-side before it ever becomes a prompt — deliberate precedence, matching peer products. The list RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument; draft chip visuals derive from the `lexicon` scan.
+A pick lands the literal `/name ` text and the prompt ships the same literal ([slash-pipeline Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)) — this source implements no adjudication hooks and no reference codec. Determinism lives host-side: the pre-step gesture boundary (`dsh-tool-skill`) recognizes whitespace-bounded `/name` tokens naming user-invocable skills anywhere in a user message and injects the rendered `<skill_content>` for every front end, so a menu pick, a hand-typed token, and a TUI/ACP prompt all load the skill the same way. A name shared with a host command still resolves to the command: adjudication claims the line client-side before it ever becomes a prompt — deliberate precedence, matching peer products. The list RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument; draft chip visuals derive from the `lexicon` scan.
 
 A failed `skill.list` throws from `candidates`, which the slash shell logs and folds into a silent menu-group drop — the menu shows only pending/ready states.
 
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 3a8ac86d13..8f1f69b26a 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -4,7 +4,7 @@
 
 skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
 
-pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP（Agent Client Protocol）提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
+pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（[slash 流水线 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)）——本 source 不实现任何裁决钩子，也没有引用 codec。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP（Agent Client Protocol）提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 139398b648..524cd180cc 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -3,15 +3,16 @@
  * candidates from the skill.list RPC addressed by the per-call session
  * projection's sessionId (sessions are always agent-backed; the host
  * resolves cwd from the session header). A pick lands the literal `/name `
- * text and the prompt ships the same literal (decision 21); determinism
+ * text and the prompt ships the same literal (plain-text-reference decision;
+ * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md);
+ * determinism
  * lives host-side — the pre-step boundary (`dsh-tool-skill`) recognizes a
  * leading `/name` naming a user-invocable skill and injects the rendered
  * body for every front end, including `disable-model-invocation` skills the
  * model-side catalog never lists (issue #1470). The RPC rides the plugin's
  * root-context connection captured at registration — the source never reads
- * services off a per-call argument. Draft chip visuals still derive from
- * the lexicon scan; the legacy `<skill>` reference codec is gone (decision
- * 21 removal cut).
+ * services off a per-call argument. Draft chip visuals derive from
+ * the lexicon scan; this source implements no reference codec.
  *
  * Catalog fetches are cached per session (the small twin of the ui-command
  * directory): the per-keystroke candidates re-poll filters a settled
@@ -162,8 +163,9 @@ export function apply(ctx: ClientContext): void {
       }
     },
     onPick({ candidate }) {
-      // Decision 21: the pick lands plain text and the prompt ships the same
-      // literal. Determinism no longer rides the client — the host's
+      // Plain-text-reference decision (web-input-machine note): the pick
+      // lands plain text and the prompt ships the same
+      // literal. Determinism lives host-side — the host's
       // pre-step boundary (dsh-tool-skill) recognizes the leading /name and
       // injects the rendered body for every front end. A name shared with a
       // host command still resolves to the command: adjudication claims the
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index 4679ef2c98..f33924e977 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -6,7 +6,9 @@
  * real ClientSessionContext projections — sessionId addressing, the
  * session-keyed catalog cache (single-flight per key, scope-birth warm
  * prewarm, connection/reset clear), startsWith filtering, RPC-failure
- * rejection, pick → plain-text outcome (decision 21), the synchronous
+ * rejection, pick → plain-text outcome (the plain-text-reference decision:
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md),
+ * the synchronous
  * lexicon reads over the settled cache, and the reference codec's two
  * projections. Direct driving is deliberate: this spec owns only the
  * source's own contract.
@@ -322,7 +324,7 @@ describe('lexicon', () => {
   })
 })
 
-describe('pick lands plain text (decision 21)', () => {
+describe('pick lands plain text', () => {
   it('onPick returns the literal /name text with a closing space', async () => {
     const { source } = await bench(listOk(CATALOG))
     const outcome = source.onPick({
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index 6954134f01..47b4cc670f 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/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/ui-slash/README.md
-README.md: efb289aaf6b4a442b00e7a0b26ed044b7b061070
-README.zh.md: c6d3236f615642b9efc6fabaa7ec407ad896a8e2
+README.md: 739e7ae93e024bdbd602aaff4267cb74406b5698
+README.zh.md: 0e3cd0d4b3cb93e3d602aa0c8f30d4e5afff3af2
diff --git a/packages/client/ui-slash/README.md b/packages/client/ui-slash/README.md
index efb289aaf6..739e7ae93e 100644
--- a/packages/client/ui-slash/README.md
+++ b/packages/client/ui-slash/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Input trigger pipeline plugin: `/` and `@` detection under the caret (word-boundary + guard-tier rules), the grouped candidate menu, and pick routing to registered sources. `ctx.slash` owns the source roster and resolves one `SlashController` per session scope (`sessionOf`); the conversation wiring layer drives `track`/`arbitrate`/`onSpace`/`adjudicate` on the controller. The same controller exposes `toggleSource` for a chrome launcher to open exactly one registered source over a synthetic selection span; the resulting candidates still use the ordinary menu, keyboard arbitration, pick callback, and scoped input mutations. Sources receive a `ClientSessionContext` projection per call — sessions are always agent-backed, so the projection is the session identity alone. A source is warmed in every session controller it can reach: the roster present at scope birth warms during controller construction, and a source registered later is warmed into every live controller by the registration itself. Sources whose `lexicon` roll changes after warm implement `subscribeLexicon(session, listener)`; the controller re-polls on each notification and publishes the aggregation through its `lexicon` snapshot store. The pipeline is command-agnostic: space/enter adjudication polls the optional `matchSpace`/`matchEnter` hooks in registration order and the first non-undefined answer wins.
 
-Layering: `src/core/` (T2) is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract (design v4 §5.1); changes require main-thread arbitration.
+Layering: `src/core/` (T2) is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract; changes require main-thread arbitration.
 
 MenuView renders the menu store into the `conversation.input.overlay` slot (list kind, session scope) and renders null while closed. Typed triggers seed every source registered for that trigger; a programmatic launcher seeds only its requested source and publishes the source name through the controller's `launcher` snapshot store until the menu closes or typed tracking resumes. Groups sort by the optional `SlashSource.order` (lower first, default 0, ties keep registration order) under title rows localized through the `slash.menu` locale namespace (an unknown source shows its raw name); the list height clamps to the space above the composer, and a pointer down outside both the menu and the surrounding composer card dismisses it. The slot is owned by ui-conversation's composer entry (anchor, children declaration, lifecycle); its SlotMap type merge lives in this package's `src/client/slots.ts` because the dependency direction (ui-conversation → ui-slash) admits no reverse type import. Combobox pattern: focus stays in the textarea, rows pick on mousedown, the highlight rides `aria-activedescendant`.
 
diff --git a/packages/client/ui-slash/README.zh.md b/packages/client/ui-slash/README.zh.md
index c6d3236f61..0e3cd0d4b3 100644
--- a/packages/client/ui-slash/README.zh.md
+++ b/packages/client/ui-slash/README.zh.md
@@ -4,7 +4,7 @@
 
 输入触发流水线插件：光标处的 `/` 与 `@` 检测（词边界 + guard tier 规则）、分组候选菜单，以及把 pick 路由到已注册 source。`ctx.slash` 拥有 source roster，并按会话 scope（`sessionOf`）各解析一个 `SlashController`；对话接线层在 controller 上驱动 `track`／`arbitrate`／`onSpace`／`adjudicate`。同一个 controller 还暴露 `toggleSource`，供 chrome launcher 在一段合成 selection span 上只打开一个已注册 source；所得候选仍走通常的菜单、键盘仲裁、pick callback 与 scoped 输入改写。source 每次调用收到一个 `ClientSessionContext` 投影——会话始终由 agent（智能体）支撑，因此投影只含会话身份。source 在它能触达的每个会话 controller 中都会被预热：scope 出生时在场的 roster 随 controller 构造预热，晚于此注册的 source 由注册动作本身预热进每个活 controller。`lexicon` 名录在预热后仍会变化的 source 实现 `subscribeLexicon(session, listener)`；controller 每收到通知就重拉，并把聚合结果经其 `lexicon` 快照 store 发布。流水线与命令无关：空格／回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子，第一个非 undefined 的应答胜出。
 
-分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定（设计 v4 §5.1）；变更需经主线程仲裁。
+分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定；变更需经主线程仲裁。
 
 MenuView 把菜单 store 渲染进 `conversation.input.overlay` slot（列表类，会话 scope），菜单关闭期间渲染 null。键入式 trigger 会 seed 为该 trigger 注册的所有 source；程序化 launcher 只 seed 所请求的 source，并在菜单关闭或重新开始键入式 tracking 前，通过 controller 的 `launcher` 快照 store 发布该 source 名称。分组按可选的 `SlashSource.order` 排序（越小越靠前，默认 0，同值保持注册序），组标题行经 `slash.menu` locale 命名空间本地化（未知 source 显示其原名）；列表高度收敛到 composer 上方的可用空间，指针落在菜单与所在 composer 卡片之外即关闭菜单。该 slot 由 ui-conversation 的组合器条目拥有（锚点、children 声明、生命周期）；其 SlotMap 类型合并放在本包的 `src/client/slots.ts`，因为依赖方向（ui-conversation → ui-slash）不允许反向的类型导入。combobox 模式：焦点始终留在 textarea，行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载。
 
diff --git a/packages/client/ui-slash/src/client/controller.ts b/packages/client/ui-slash/src/client/controller.ts
index fdf78d316e..9b2a4fd732 100644
--- a/packages/client/ui-slash/src/client/controller.ts
+++ b/packages/client/ui-slash/src/client/controller.ts
@@ -47,7 +47,8 @@ export class SlashController {
    */
   readonly launcher: SnapshotStore<string | null> = createSnapshotStore<string | null>(null)
   /**
-   * Aggregated hot reference lexicon, grouped by trigger (decision 21):
+   * Aggregated hot reference lexicon, grouped by trigger (plain-text-reference decision;
+   * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
    * sources implementing the lexicon hook are polled with the session
    * projection; undefined answers (roll not hot yet) are skipped; multiple
    * sources on one trigger concatenate in registration order. A snapshot
@@ -225,7 +226,7 @@ export class SlashController {
 
   /**
    * Serialize one reference occurrence to its model form via the owning
-   * source's codec (design §9.1 prompt serialization: registry → explicit
+   * source's codec (prompt serialization: registry → explicit
    * call → await). Owner missing or codec-less rejects — the submit attempt
    * blocks instead of silently downgrading to the clipboard text.
    * @param source - owning source name.
diff --git a/packages/client/ui-slash/src/client/slots.ts b/packages/client/ui-slash/src/client/slots.ts
index 5b90fb5ec1..9cdaeb309b 100644
--- a/packages/client/ui-slash/src/client/slots.ts
+++ b/packages/client/ui-slash/src/client/slots.ts
@@ -4,7 +4,7 @@
  * entry (declaring is claiming: anchor, children declaration, lifecycle),
  * but the SlotMap type merge lives here: the owner package depends on this
  * one, so the dependency direction admits no reverse type import, and a
- * type-erased registration is ruled out (PR #632 review). The owner's
+ * type-erased registration is ruled out. The owner's
  * program picks this merge up transitively through its ui-slash imports.
  */
 // Type-only edge: the SlotMap augmentation below merges into this package's interface.
diff --git a/packages/client/ui-slash/src/core/contract.ts b/packages/client/ui-slash/src/core/contract.ts
index 852ac2bf10..3c8f4c70ee 100644
--- a/packages/client/ui-slash/src/core/contract.ts
+++ b/packages/client/ui-slash/src/core/contract.ts
@@ -1,8 +1,8 @@
 /**
- * Frozen pure-core contract (design v4, plan §1.2): trigger detection and
- * menu reduction, zero React / DOM / cordis. Types only — T2 implements
- * these signatures in sibling modules (annotate implementations with these
- * aliases); the service shell (T4) wires them to ctx.
+ * Frozen pure-core contract: trigger detection and
+ * menu reduction, zero React / DOM / cordis. Types only — implementations
+ * live in sibling modules annotated with these
+ * aliases; the service shell wires them to ctx.
  */
 import type { SlashCandidate, TokenSpan, TriggerChar, TriggerGuard, TriggerPosition } from '../types.ts'
 
diff --git a/packages/client/ui-slash/src/core/detect.ts b/packages/client/ui-slash/src/core/detect.ts
index 5f2e43680c..6a1b69110b 100644
--- a/packages/client/ui-slash/src/core/detect.ts
+++ b/packages/client/ui-slash/src/core/detect.ts
@@ -1,5 +1,5 @@
 /**
- * Trigger detection pure core (design §5.1, plan §1.2). Scans backward from
+ * Trigger detection pure core. Scans backward from
  * the caret for a live trigger char under the guard tier and applies the
  * word-boundary rules. Zero React / DOM / cordis.
  */
diff --git a/packages/client/ui-slash/src/core/menu.ts b/packages/client/ui-slash/src/core/menu.ts
index fe1c7f10eb..a951f3cd42 100644
--- a/packages/client/ui-slash/src/core/menu.ts
+++ b/packages/client/ui-slash/src/core/menu.ts
@@ -1,5 +1,5 @@
 /**
- * Menu reduction pure core (design §5.1, plan §1.2). One group per source;
+ * Menu reduction pure core. One group per source;
  * generation-gated settlement; empty ready groups auto-close. Zero React /
  * DOM / cordis. Stale or no-op events return the same state reference so
  * store subscribers skip re-renders.
diff --git a/packages/client/ui-slash/src/types.ts b/packages/client/ui-slash/src/types.ts
index c885984b73..c62ca520d7 100644
--- a/packages/client/ui-slash/src/types.ts
+++ b/packages/client/ui-slash/src/types.ts
@@ -80,7 +80,9 @@ export interface SubmitOutcome {
 /**
  * Unified pick return. `undefined` = miss → default sink; `'handled'` = the
  * source dealt with it internally (e.g. opened its popup shell). The `text`
- * arm is the plain-text reference path (decision 21): the token span is
+ * arm is the plain-text reference path (decision recorded in
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+ * the token span is
  * replaced with literal text — no occurrence identity, no placeholder; any
  * chip visual is derived downstream by scanning the draft against the
  * source lexicons.
@@ -159,8 +161,8 @@ export interface SlashSource {
    */
   warm?(session: ClientSessionContext): void
   /**
-   * Synchronous hot-snapshot name roll for plain-text reference decoration
-   * (decision 21). Implementing IS the participation claim: the render side
+   * Synchronous hot-snapshot name roll for plain-text reference decoration.
+   * Implementing IS the participation claim: the render side
    * scans the draft for `<trigger><name>` tokens and decorates exact matches.
    * `undefined` = backing data not warm yet — no decoration, never a fetch
    * (the render path must stay synchronous and side-effect free).
@@ -211,7 +213,7 @@ export interface ConsumeTokenRequest {
     | { readonly kind: 'bare-token'; readonly token: string }
 }
 
-/** Request payload of the scoped insert-text input event (decision 21). */
+/** Request payload of the scoped insert-text input event (the plain-text reference path). */
 export interface InsertTextRequest {
   /** Literal replacement for the trigger token span (e.g. `/name `). */
   readonly text: string
@@ -245,7 +247,7 @@ declare module 'cordis' {
     'slash/input-consume-token'(request: ConsumeTokenRequest): true | undefined
     /**
      * Replaces the trigger token span with literal text — the plain-text
-     * reference path (decision 21). Same carrier routing and applied-truth
+     * reference path. Same carrier routing and applied-truth
      * contract; the draft gains ordinary characters, no occurrence entry.
      * @param request - Replacement text and menu-time span CAS.
      * @mode bail
diff --git a/packages/client/ui-slash/tests/core-detect.spec.ts b/packages/client/ui-slash/tests/core-detect.spec.ts
index 6d3326b5d8..013645b91e 100644
--- a/packages/client/ui-slash/tests/core-detect.spec.ts
+++ b/packages/client/ui-slash/tests/core-detect.spec.ts
@@ -1,5 +1,5 @@
-// detectTrigger word-boundary, position, guard-tier, and span behavior
-// (design §5.1). URL rule pinned here: '/' is dead when its predecessor is
+// detectTrigger word-boundary, position, guard-tier, and span behavior.
+// URL rule pinned here: '/' is dead when its predecessor is
 // another '/' (second slash of '//') or a ':' itself preceded by a
 // non-whitespace char (scheme separator) — this is the concrete rule chosen
 // to honor "no trigger inside URLs".
diff --git a/packages/client/ui-slash/tests/core-menu.spec.ts b/packages/client/ui-slash/tests/core-menu.spec.ts
index 28cd009948..6f1d5101bd 100644
--- a/packages/client/ui-slash/tests/core-menu.spec.ts
+++ b/packages/client/ui-slash/tests/core-menu.spec.ts
@@ -1,6 +1,5 @@
 // menuReduce generation gating, auto-close, silent group removal, cyclic
-// highlight movement, stale/no-op reference identity; exactMatch lookup
-// (design §5.1, plan §1.2).
+// highlight movement, stale/no-op reference identity; exactMatch lookup.
 import { describe, expect, it } from 'vitest'
 import type { MenuState, TriggerHit } from '../src/core/contract.ts'
 import { exactMatch, MENU_CLOSED, menuReduce, seedGroups } from '../src/core/menu.ts'
diff --git a/packages/client/ui-slash/tests/menu-view.spec.tsx b/packages/client/ui-slash/tests/menu-view.spec.tsx
index 2157d19b98..2671b526b8 100644
--- a/packages/client/ui-slash/tests/menu-view.spec.tsx
+++ b/packages/client/ui-slash/tests/menu-view.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * MenuView rendering spec, props-direct (slot-parity doctrine): closed store
+ * MenuView rendering spec, props-direct: closed store
  * renders null, groups render in roster order under localized title rows
  * (unknown sources fall back to the raw name) with pending rows as loading,
  * pointer picks route (source, index) back without stealing focus, the
diff --git a/packages/client/ui-slash/tests/service.spec.ts b/packages/client/ui-slash/tests/service.spec.ts
index 6f398442b9..143f6e6ddf 100644
--- a/packages/client/ui-slash/tests/service.spec.ts
+++ b/packages/client/ui-slash/tests/service.spec.ts
@@ -483,7 +483,7 @@ describe('pick / scoped input events', () => {
     expect(inserts).toEqual([{ reference: insert, span: { start: 0, end: 2, draftRev: 3 } }])
   })
 
-  it('routes a text outcome through the scoped insert-text event (decision 21) and closes the menu', async () => {
+  it('routes a text outcome through the scoped insert-text event and closes the menu', async () => {
     const { controller, actx } = pickBench(() => ({ text: '/goal ' }))
     const texts: Array<{ text: string; span: unknown }> = []
     actx.on('slash/input-insert-text', (req) => {
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index d6c1824c99..eae7837386 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Slot registry pure core (slot terminal design). Owners declare slot
+ * Slot registry pure core. Owners declare slot
  * contracts by merging into {@link SlotMap}; one `register` call contributes a
  * component AND (optionally) declares child slots, a store seat, and the
  * registrant's business face. Zero runtime dependencies (React types only).
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 20f6a68eb1..1bb6996fe7 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -70,8 +70,9 @@ export interface SessionMaybeProvideInfo {
   /** Static plain-member roster; values are undefined with the session. */
   props: Record<string, unknown>
   /**
-   * Key-addressed projection value sources (the useProjection framework seat,
-   * session-projection RFC). Unlike `hooks`, the key space is open — values
+   * Key-addressed projection value sources (the useProjection framework seat;
+   * session-projection subsystem page: docs/subsystems/session-projection.md).
+   * Unlike `hooks`, the key space is open — values
    * arrive from host-computed push frames — so the render side binds per
    * resolved key instead of per static roster member. Faces are always
    * defined per key (absence is an `undefined` snapshot); the whole member is
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 73c7f9a6cc..de2ac87c48 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -3,10 +3,12 @@
  * candidates filtered from the session list snapshot's running children
  * (zero RPC; the list rides the plugin's root-context sessions service, the
  * scoped session comes from the per-call projection), pick inserts the
- * literal `@label ` text (decision 21: the draft carries plain text, chip
+ * literal `@label ` text (plain-text-reference decision, see
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md:
+ * the draft carries plain text, chip
  * visuals are derived by scanning against the source lexicon, and the
  * prompt ships the same literal). Consumption semantics stay with future
- * business work (design ledger). No adjudication hooks: subagent
+ * business work. No adjudication hooks: subagent
  * references never enter command adjudication.
  */
 import type {
@@ -80,16 +82,14 @@ export function apply(ctx: ClientContext): void {
       return sessions.list.subscribe(listener)
     },
     onPick({ candidate }) {
-      // Decision 21: plain-text reference — the literal lands in the draft
+      // Plain-text reference: the literal lands in the draft
       // and ships to the model verbatim (trailing space closes the token).
-      // Legacy path (decision 21), retained for the removal cut, no longer reached:
-      // return { insert: { source: 'subagent', ref: candidate.name, label: candidate.name, clipboardText: `@${candidate.name}` } }
       return { text: `@${candidate.name} ` }
     },
     codec: {
       clipboardText: ref => `@${ref}`,
       // TODO: serialize returns the raw label until the '@' consumption
-      // feature defines a model representation (design ledger).
+      // feature defines a model representation.
       serialize: ref => Promise.resolve(`@${ref}`),
     },
   }
diff --git a/packages/client/ui-subagent/tests/browser-plugin.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
index 861546c19c..9796c68637 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
@@ -5,7 +5,9 @@
  * real ClientSessionContext projections — zero-RPC candidates from the root
  * session list (running children of the projected session, label-contains
  * filtering, childless session → empty), the synchronous lexicon roster,
- * pick → plain-text outcome (decision 21), and the reference codec's two
+ * pick → plain-text outcome (the plain-text-reference decision:
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md),
+ * and the reference codec's two
  * projections. Direct driving is deliberate: this spec owns only the
  * source's own contract.
  */
@@ -227,7 +229,7 @@ describe('lexicon', () => {
 })
 
 describe('pick and codec', () => {
-  it('onPick returns the literal @label text with a closing space (decision 21)', async () => {
+  it('onPick returns the literal @label text with a closing space', async () => {
     const source = await bench(FAMILY)
     const outcome = source.onPick({
       candidate: { name: 'worker-1' },
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index 35b576523d..7cf091e0f5 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/ui-theme/README.md
-README.md: 648213b258169b2e8869a93d058fcc65aece175e
-README.zh.md: ec29b9be999d64eee76342f0a86eb8707807be06
+README.md: 2d576cc16b0b8fef453ad54cacd9cb195dc75e7a
+README.zh.md: b1f17c65749a94f1f48b5f7af9c8b18a5d85eb76
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index 648213b258..2d576cc16b 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the theme preference (`light`/`dark`/`system`, persisted under `dsh.theme`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens). Contract: api-contracts v3 §8.
+Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the theme preference (`light`/`dark`/`system`, persisted under `dsh.theme`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens).
 
 `src/styles/` holds five sheets, all imported by the web shell's `base.css`: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
 
@@ -21,4 +21,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **Third-party themes are a surface, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
-- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins (arbitrated 2026-07-22). Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`, 2026-08-07).
+- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins. Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`).
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index ec29b9be99..b1f17c6574 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。约定：api-contracts v3 §8。
+主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。
 
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
@@ -21,4 +21,4 @@
 ## 已知限制与暂缓事项
 
 - **第三方主题是表层，不是产品**：注册主题意味着覆盖同名别名变量；目前不会验证一组覆盖是否完整。
-- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个静态尺度层级与一个语义别名的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
+- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token。设计负责人批准的新增值是例外：须在同一变更中以一个静态尺度层级与一个语义别名的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`）。
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 84c6fa42af..dcd4846c34 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/ui-tool/README.md
-README.md: b33aef86a6ad161f70105968f308c5a587c25c24
-README.zh.md: 680a5149187bc43513c74134a9a58c4680af854c
+README.md: 8255aee4292ea821962477a7108b40cf3b937981
+README.zh.md: 2bc5859f592efb6ac4b67157be09a3c09afb691c
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index b33aef86a6..8255aee429 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -44,6 +44,6 @@ None. The package is client-only presentation.
 
 ## Known Limitations and Deferred Work
 
-- The Host excludes `run_code` from Code Mode program bindings, so production events currently produce one dispatch level; the recursive Runtime/UI contract is ready for future nested producers.
-- Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
-- Tool copy temporarily reuses the `ui-conversation` locale namespace.
+- The Host excludes `run_code` from Code Mode program bindings, so production events produce one dispatch level; the recursive Runtime/UI contract supports nesting.
+- First-party Tool views are colocated here and can move to their owning business packages independently through the keyed slot.
+- Tool copy reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 680a514918..2bc5859f59 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -44,6 +44,6 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
-- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 约定已为未来的嵌套生产者做好准备。
-- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
-- Tool 文案暂时复用 `ui-conversation` locale namespace。
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件只产生一层分发；递归的运行时/UI 约定支持嵌套。
+- 第一方 Tool 视图集中在本包，可以通过 keyed slot 独立迁回各自业务包。
+- Tool 文案复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
index f94809939a..10fea1b8c8 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
@@ -49,8 +49,8 @@ export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
       // sub-dispatch, legacy generic result) has its text nowhere else to go;
       // ToolRow's Output section carries it, and errorSummary its first line.
       // When a card is present ToolRow renders it instead of the output, so
-      // passing model.output unconditionally is safe and keeps the four card
-      // rows symmetric.
+      // model.output passes unconditionally and the four card rows stay
+      // symmetric.
       output={model.output}
       errorSummary={model.errorSummary}
       search={search}
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index 9fed8e3720..def3b98852 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -71,8 +71,8 @@ describe('tool-call-model', () => {
     expect(toolRowModel('read', running({ name: 'read', argsRaw: '{"path":"/tmp/x.ts"}' })).summary).toBe('/tmp/x.ts')
     expect(toolRowModel('write', running({ name: 'write', argsRaw: '{"file_path":"src/x.ts"}' })).summary).toBe('src/x.ts')
     expect(toolRowModel('edit', running({ name: 'edit', argsRaw: '{"file_path":"src/x.ts"}' })).summary).toBe('src/x.ts')
-    // Others rows prefix the real tool name into the summary slot (figma-flows
-    // ruling: static "Tool call" title, name rides the mutable summary).
+    // Other rows prefix the real tool name into the summary slot (figma
+    // flows: static "Tool call" title, the name rides the mutable summary).
     expect(toolRowModel('x', running({ argsRaw: '{"n":1}' })).summary).toBe('x · {"n":1}')
     expect(toolRowModel('x', running({ argsRaw: 'not json' })).summary).toBe('x · not json')
     expect(toolRowModel('x', running({ argsRaw: '' })).summary).toBe('x · c1')
diff --git a/packages/client/ui-trajectory/README.i18n.yaml b/packages/client/ui-trajectory/README.i18n.yaml
index e0646b2da8..7fecd92d74 100644
--- a/packages/client/ui-trajectory/README.i18n.yaml
+++ b/packages/client/ui-trajectory/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/ui-trajectory/README.md
-README.md: 2c737fe2d04df518e7d32d07aaede714a7a3566d
-README.zh.md: 1baa5a1a4422731161e6c8a743aa337a0e5cc774
+README.md: 5b8c0cd111c272007212fea0d2435c5fab2360ab
+README.zh.md: 9aaa02ccd9d50b0f0b23e9a53ea9b1048d0e513f
diff --git a/packages/client/ui-trajectory/README.md b/packages/client/ui-trajectory/README.md
index 2c737fe2d0..5b8c0cd111 100644
--- a/packages/client/ui-trajectory/README.md
+++ b/packages/client/ui-trajectory/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Trajectory renders a turn-aware event ledger with selectable User, Assistant, Tool, and nested Subtool records. Thick rules mark Turn boundaries, compact inline markers identify Steps, and the main ledger keeps only index, event, and content; selection opens a local inspector for token usage, duration, Input, Output, and Timing. Scrollable Summary regions keep their scrollbar thumbs transparent until the region is hovered or contains keyboard focus, without changing the reserved scroll geometry. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn. Long ledgers open at the current tail, load one older page when the user reaches the loaded range's top, and mount only the visible row window plus a small overscan; request-only separators share the next measurable virtual item, while semantic row keys and ARIA indexes survive prepends. Selection, timeline navigation, folding, search, and Request totals cover the currently loaded window. The ledger covers records with an explicit loading row until the initial tail is positioned and while an older page is pending. A fixed Overview above the ledger projects real record start/duration timing from left to right; when earlier records remain unloaded and the viewport includes the loaded domain's start, a neutral ellipsis control identifies the omitted prefix and loads one earlier page without assigning unknown history fabricated duration. Assistant spans divide recorded TTFT from decoding, and a 500 ms hover reveals exact clock and duration details. Dragging an interval focuses the ledger on every record active at any point in that inclusive range, while clearing the selection restores the full branch. Wheel gestures zoom the time domain. A right-button click clears the selected interval, while a right-button drag pans an already zoomed viewport without changing it. The initial view and streaming updates stay at the tail; scrolling upward suspends following so new records do not interrupt inspection of earlier rows. Content-only stream frames preserve virtual row keys and heights, reuse measurements, and do not issue repeated tail-scroll writes. Completed replies retain only the first visible token and usage chunks in the inspection projection, while unfinished and interrupted replies retain every chunk; the independent source keeps the raw history unchanged. Trajectory asks the conversation shell to float the composer over the full-height ledger, while its responsive vertical scrollers reserve the composer's live height so final rows remain reachable. The runtime's independent history source supplies raw context lineage and projects cancellation-frozen Assistant and Tool records, so Trajectory neither reads nor changes the Chat conversation snapshot. The package remains a pure-consumer plugin (registers one view tab into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
+Trajectory renders a turn-aware event ledger with selectable User, Assistant, Tool, and nested Subtool records. Thick rules mark Turn boundaries, compact inline markers identify Steps, and the main ledger keeps only index, event, and content; selection opens a local inspector for token usage, duration, Input, Output, and Timing. Scrollable Summary regions keep their scrollbar thumbs transparent until the region is hovered or contains keyboard focus, without changing the reserved scroll geometry. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn. Long ledgers open at the current tail, load one older page when the user reaches the loaded range's top, and mount only the visible row window plus a small overscan; request-only separators share the next measurable virtual item, while semantic row keys and ARIA indexes survive prepends. Selection, timeline navigation, folding, search, and Request totals cover the currently loaded window. The ledger covers records with an explicit loading row until the initial tail is positioned and while an older page is pending. A fixed Overview above the ledger projects real record start/duration timing from left to right; when earlier records remain unloaded and the viewport includes the loaded domain's start, a neutral ellipsis control identifies the omitted prefix and loads one earlier page without assigning unknown history fabricated duration. Assistant spans divide recorded TTFT from decoding, and a 500 ms hover reveals exact clock and duration details. Dragging an interval focuses the ledger on every record active at any point in that inclusive range, while clearing the selection restores the full branch. Wheel gestures zoom the time domain. A right-button click clears the selected interval, while a right-button drag pans an already zoomed viewport without changing it. The initial view and streaming updates stay at the tail; scrolling upward suspends following so new records do not interrupt inspection of earlier rows. Content-only stream frames preserve virtual row keys and heights, reuse measurements, and do not issue repeated tail-scroll writes. Completed replies retain only the first visible token and usage chunks in the inspection projection, while unfinished and interrupted replies retain every chunk; the independent source keeps the raw history unchanged. Trajectory asks the conversation shell to float the composer over the full-height ledger, while its responsive vertical scrollers reserve the composer's live height so final rows remain reachable. The runtime's independent history source supplies raw context lineage and projects cancellation-frozen Assistant and Tool records, so Trajectory neither reads nor changes the Chat conversation snapshot. The package remains a pure-consumer plugin (registers one view tab into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge).
 
 ## Model Experience
 
diff --git a/packages/client/ui-trajectory/README.zh.md b/packages/client/ui-trajectory/README.zh.md
index 1baa5a1a44..9aaa02ccd9 100644
--- a/packages/client/ui-trajectory/README.zh.md
+++ b/packages/client/ui-trajectory/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。约定：api-contracts v3 §8。
+Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。
 
 ## 模型体验
 
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
index 4e110a5888..6e86fac8dc 100644
--- a/packages/client/ui-trajectory/src/client/layout.ts
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -935,8 +935,8 @@ function expandSubCalls(
             isError: sub.isError,
           }
           : {}),
-        // PR3's start/settle pair carries per-sub-call wall time; a running
-        // (unsettled) or pre-pair log entry shows the em dash.
+        // The code-dispatch start/settle pair carries per-sub-call wall time;
+        // a running (unsettled) or pre-pair log entry shows the em dash.
         timeSeconds: settled ? durationSeconds(sub.time, sub.callTime) : null,
         startedAt: settled
           ? finiteTime(sub.callTime)
diff --git a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
index fd4f31f78e..a049b3f3d1 100644
--- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
+++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
@@ -150,8 +150,8 @@ function SessionTree({
         )}
         {groups.map(group => (
           // Group section: header row + expanded top-level session rows. The
-          // inter-group breathing room (former flat-list batch separator)
-          // is the section's own margin (WorkspaceBrowser.module.css).
+          // inter-group breathing room is the section's own margin
+          // (WorkspaceBrowser.module.css).
           <div key={group.key} className={css.groupSection}>
             <ProjectRowItem
               group={group}
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx
index 40ef1e8883..71c0b05af5 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.tsx
+++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx
@@ -346,9 +346,9 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
   const statuses = sessionStatuses(node, t)
   const primaryStatus = statuses[0]
   const [menuOpen, setMenuOpen] = useState(false)
-  // Archive replaces the former Delete placeholder: it hides the row through
-  // the registry-global archive set and never touches the session log, so it
-  // is not styled as destructive and needs no confirmation dialog.
+  // Archive hides the row through the registry-global archive set and never
+  // touches the session log, so it is not styled as destructive and needs no
+  // confirmation dialog.
   const sessionMenuItems = [
     { id: 'rename', label: t('rename'), icon: <IconEditOutline16 /> },
     { id: 'fork', label: t('menu.fork'), icon: <IconBranchOutline16 /> },
diff --git a/packages/client/ui-workspace/tests/rename-assembly.spec.tsx b/packages/client/ui-workspace/tests/rename-assembly.spec.tsx
index 44b812532e..3c37f137d6 100644
--- a/packages/client/ui-workspace/tests/rename-assembly.spec.tsx
+++ b/packages/client/ui-workspace/tests/rename-assembly.spec.tsx
@@ -4,8 +4,9 @@
  * WorkspaceBrowser occupying the sidebar hole): row menu → rename dialog →
  * the injected renameSession hop (sessions.binding → ISession.rename) → on
  * the accepted unary response the dialog closes and the row re-labels from
- * the list state — no push-frame wait. Previously pinned only by the
- * assembled-app snapshot (apps/web/tests/session-actions.snapshot.ts); the
+ * the list state — no push-frame wait. Coverage split: the assembled-app
+ * snapshot (apps/web/tests/session-actions.snapshot.ts) pins the full-app
+ * transcript; the
  * verb's wire behavior stays with the runtime package
  * (session.spec.ts#rename), the dialog's own arms with rows.spec /
  * workspace-browser.spec.
diff --git a/packages/client/web-react/README.i18n.yaml b/packages/client/web-react/README.i18n.yaml
index 72afe765f0..44859cc39a 100644
--- a/packages/client/web-react/README.i18n.yaml
+++ b/packages/client/web-react/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/web-react/README.md
-README.md: 8f1a525af1e249282f2cc473e7f9652f68f914a8
-README.zh.md: 55ed3a0fec4bfba4c4934db8728bc6fa23a7321a
+README.md: ada2a1384427f5a54c51e9fca8bbf9595e4d3403
+README.zh.md: 40cd70c689b87a5935e0249df47899982e898be8
diff --git a/packages/client/web-react/README.md b/packages/client/web-react/README.md
index 8f1a525af1..ada2a13844 100644
--- a/packages/client/web-react/README.md
+++ b/packages/client/web-react/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shell-side React glue for the slot terminal design: createSlotRenderer (the SlotRenderer implementation the shell installs into the runtime SlotsService), SessionProvider (framework-wired render prop, also injected as a standard seat to entries declaring session-scope children), bindSnapshotSelector (the one hook constructor — hosts and engines traffic in bare observable sources; every hook binds here, cached per source), useInvoke. Chain-slot outlets run the registered selectors in chain order at render time and mount only the elected entry, its select return joining the props as `matched`; the `renderSlotChain` binding is per-entry cached like `renderSlot`. The snapshot-store engine and defineStore live in runtime (store relocation); business plugins depend on ui-slots types only, never on this package.
+Shell-side React glue for the slot terminal design: createSlotRenderer (the SlotRenderer implementation the shell installs into the runtime SlotsService), SessionProvider (framework-wired render prop, also injected as a standard seat to entries declaring session-scope children), bindSnapshotSelector (the one hook constructor — hosts and engines traffic in bare observable sources; every hook binds here, cached per source), useInvoke. Chain-slot outlets run the registered selectors in chain order at render time and mount only the elected entry, its select return joining the props as `matched`; the `renderSlotChain` binding is per-entry cached like `renderSlot`. The snapshot-store engine and defineStore live in runtime; business plugins depend on ui-slots types only, never on this package.
 
 ## Model Experience
 
diff --git a/packages/client/web-react/README.zh.md b/packages/client/web-react/README.zh.md
index 55ed3a0fec..40cd70c689 100644
--- a/packages/client/web-react/README.zh.md
+++ b/packages/client/web-react/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-slot 终端设计的外壳侧 React 胶水：createSlotRenderer（外壳安装到运行时 SlotsService 的 SlotRenderer 实现）、SessionProvider（由框架接入的 render prop，也作为标准 seat 注入到声明会话 scope 子 slot 的配置项）、bindSnapshotSelector（唯一的钩子构造器：主机与引擎只传递裸 observable source；每个钩子在此绑定，并按 source 缓存）、useInvoke。链式 slot outlet 在渲染时按链顺序运行已注册 selector，只挂载被选中的配置项，其 select 返回值以 `matched` 加入 props；`renderSlotChain` 绑定与 `renderSlot` 一样按配置项缓存。快照 store 引擎与 defineStore 位于运行时（store 已迁移）；业务插件只依赖 ui-slots 类型，绝不依赖该包。
+slot 终端设计的外壳侧 React 胶水：createSlotRenderer（外壳安装到运行时 SlotsService 的 SlotRenderer 实现）、SessionProvider（由框架接入的 render prop，也作为标准 seat 注入到声明会话 scope 子 slot 的配置项）、bindSnapshotSelector（唯一的钩子构造器：主机与引擎只传递裸 observable source；每个钩子在此绑定，并按 source 缓存）、useInvoke。链式 slot outlet 在渲染时按链顺序运行已注册 selector，只挂载被选中的配置项，其 select 返回值以 `matched` 加入 props；`renderSlotChain` 绑定与 `renderSlot` 一样按配置项缓存。快照 store 引擎与 defineStore 位于运行时；业务插件只依赖 ui-slots 类型，绝不依赖该包。
 
 ## 模型体验
 
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index 69d37f35b4..43b3c4cbae 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -650,7 +650,7 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   const spec = host.specOf(slotKey)
   // Undeclared (or no-longer-declared) keys render empty: a declaring entry's
   // unload returns the slot to the undeclared state while retained elements
-  // may still be mounted — natural empty, not an ownership failure (§9).
+  // may still be mounted — natural empty, not an ownership failure.
   if (!spec) return null
   const strictSessionAbsent = spec.scope === 'session' && sessionInfo.sessionId === undefined
   if (strictSessionAbsent && (spec.kind !== 'chain' || !opts?.overlay)) {
@@ -776,7 +776,7 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   return <>{list.map(item => guarded(item.entry, entryKeyOf(item.entry)))}</>
 }
 
-/** Root outlet: the shell's single ctx-level render entry — an unregistered 'root' is a boot-order failure, never a silent blank (§1). */
+/** Root outlet: the shell's single ctx-level render entry — an unregistered 'root' is a boot-order failure, never a silent blank. */
 function RootOutlet({ ownerProps }: { ownerProps: object }) {
   const host = useHost()
   useSyncExternalStore(
diff --git a/packages/client/web-react/src/session-provider.tsx b/packages/client/web-react/src/session-provider.tsx
index 865e4fc081..11a5d4404d 100644
--- a/packages/client/web-react/src/session-provider.tsx
+++ b/packages/client/web-react/src/session-provider.tsx
@@ -84,7 +84,7 @@ function useAbsentSnapshot<S>(_selector: (snapshot: never) => S, _equal?: (a: S,
 }
 
 /**
- * The useProjection framework seat (session-projection RFC), one bound
+ * The useProjection framework seat (docs/subsystems/session-projection.md), one bound
  * function per provide bundle (cached by info identity — components may hold
  * it across renders). Key-addressed: the key resolves a per-session value
  * face off the projection store; the bound selector hook comes from the same
diff --git a/packages/client/web-react/tests/scoped-slots.spec.tsx b/packages/client/web-react/tests/scoped-slots.spec.tsx
index 0688d409b9..ddaa5bec3b 100644
--- a/packages/client/web-react/tests/scoped-slots.spec.tsx
+++ b/packages/client/web-react/tests/scoped-slots.spec.tsx
@@ -135,8 +135,8 @@ function makeHost() {
     host,
     list,
     workspaces,
-    // Same driver surface as the old current cell: set(id) publishes the
-    // resolved bundle (or the absent projection) through the provide source.
+    // Driver surface: set(id) publishes the resolved bundle (or the absent
+    // projection) through the provide source.
     current: {
       set: (id: string | undefined) => {
         currentId = id
diff --git a/packages/client/web-react/tests/session-provider.spec.tsx b/packages/client/web-react/tests/session-provider.spec.tsx
index c1f1f648a2..248d4d17f5 100644
--- a/packages/client/web-react/tests/session-provider.spec.tsx
+++ b/packages/client/web-react/tests/session-provider.spec.tsx
@@ -57,8 +57,8 @@ function makeHost(bodies: { root: (rp: (key: string, owner: object) => React.Rea
   }
   return {
     host,
-    // Same driver surface as the old current cell: set(id) publishes the
-    // resolved bundle (or the absent projection) through the provide source.
+    // Driver surface: set(id) publishes the resolved bundle (or the absent
+    // projection) through the provide source.
     current: {
       set: (id: string | undefined) => {
         currentId = id
diff --git a/packages/client/web-react/tests/use-projection.spec.tsx b/packages/client/web-react/tests/use-projection.spec.tsx
index a10cf48989..15a63e9027 100644
--- a/packages/client/web-react/tests/use-projection.spec.tsx
+++ b/packages/client/web-react/tests/use-projection.spec.tsx
@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 /**
- * useProjection standard-kit delivery (session-projection RFC): the fifth
+ * useProjection standard-kit delivery (session-projection subsystem page:
+ * docs/subsystems/session-projection.md): the fifth
  * framework hook seat rides the same provide channel as useSession — a
  * session slot component receives `useProjection` in its kit, key-addressed
  * over the bundle's projection face; unresolved keys (no value, no face, no
diff --git a/packages/client/web/src/AppRoot.tsx b/packages/client/web/src/AppRoot.tsx
index 18cf06becb..d8ef311b38 100644
--- a/packages/client/web/src/AppRoot.tsx
+++ b/packages/client/web/src/AppRoot.tsx
@@ -3,7 +3,7 @@
  * Pure kernel component with zero plugin dependencies — before settled it may
  * only rely on itself (the fail-loud presentation must not depend on the
  * system whose failure it reports; the status/signal stores are kernel-own,
- * web2 shell self-sufficiency rule); the real UI is produced by the
+ * shell self-sufficiency rule); the real UI is produced by the
  * app-shell entry once every entry is active. A failed boot keeps the
  * loading page, lists the per-entry fiber states and the sweep report (fail
  * loud, no partial UI).
diff --git a/packages/client/web/src/boot.tsx b/packages/client/web/src/boot.tsx
index cf63247915..c1203929f9 100644
--- a/packages/client/web/src/boot.tsx
+++ b/packages/client/web/src/boot.tsx
@@ -1,15 +1,15 @@
 /**
  * Web shell boot kernel — the face consumed by the apps/web entry. Everything
  * here is machinery that cannot itself be a loader entry, and none of it
- * value-imports a plugin package (web2 shell self-sufficiency rule: the
+ * value-imports a plugin package (shell self-sufficiency rule: the
  * loading page must work while — especially when — plugins fail). The one
- * sanctioned exception is the modules package (design §4.7 bootstrap
+ * sanctioned exception is the modules package (bootstrap
  * identity): the module system cannot arrive through itself, so its class
  * and its client-half wrapper are shell-bundled and the kernel adopts its
  * plugin entry once cordis is up.
  *
  * AppWebEntry.run(), module face first, then plugin face: parse
- * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary, D16)
+ * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary)
  * → build the module system over the module-view rows → render the loading
  * page → prefetch every `immediately` row in parallel with mounting the
  * vendored cordis Loader (`internal` contract injection BEFORE any entry exists —
@@ -101,9 +101,9 @@ export class AppWebEntry {
       modules: this.manifest.modules, staticModules: getStaticModules(), ...this.seams,
     })
     // The app-shell assembly is the only shell-own module: every other graph
-    // row is a plugin bundle arriving through fetch (web2 single package form).
+    // row is a plugin bundle arriving through fetch.
     this.modules.registerStatic(APP_SHELL_ID, AppShell)
-    // Adoption handoff, supply side (design §4.7): register the modules
+    // Adoption handoff, supply side: register the modules
     // package's own client half under its bare package name (= graph row id
     // = entry name — a suffixed key would miss the statics branch and
     // trigger a real fetch), and put the instance on the kernel slot the
diff --git a/packages/client/web/src/index.ts b/packages/client/web/src/index.ts
index 3a9ccda2ba..ffa29a7b85 100644
--- a/packages/client/web/src/index.ts
+++ b/packages/client/web/src/index.ts
@@ -2,7 +2,7 @@
  * Web shell library entry. The shell's product is {@link AppWebEntry} —
  * apps/web's vite entry runs it against #root; everything else (AppRoot
  * gate, app-shell assembly entry, module-table staticModules, platform constants) is
- * internal to the boot chain. PLATFORM_MODULES is re-exported as the C1
+ * internal to the boot chain. PLATFORM_MODULES is re-exported as the
  * single source of truth for the tsdown client externals projection.
  * @module @deepseek-ai/dsh-client-web
  */
diff --git a/packages/client/web/src/loader-status.ts b/packages/client/web/src/loader-status.ts
index 37b5541798..03ac761afe 100644
--- a/packages/client/web/src/loader-status.ts
+++ b/packages/client/web/src/loader-status.ts
@@ -4,8 +4,8 @@
  * cordis fiber states (display the truth, not a retelling) — the boot chain
  * subscribes `internal/status` and recomputes one row per loader entry.
  *
- * The store is hand-rolled here because of the shell self-sufficiency rule
- * (web2 §0): the snapshot-store machinery lives in the runtime PLUGIN
+ * The store is hand-rolled here because of the shell self-sufficiency rule:
+ * the snapshot-store machinery lives in the runtime PLUGIN
  * package, and the shell kernel must not value-import any plugin package —
  * the loading page has to work while (and especially when) plugins fail.
  * @module @deepseek-ai/dsh-client-web/src/loader-status
diff --git a/packages/client/web/src/seed.ts b/packages/client/web/src/seed.ts
index 11f976f4db..fd5360f0f7 100644
--- a/packages/client/web/src/seed.ts
+++ b/packages/client/web/src/seed.ts
@@ -2,7 +2,7 @@
  * Platform-singleton module-table. These are the ONLY entities the shell
  * shares into the frozen module table — fetch bundles resolve their externals
  * against exactly this set through the loader's require. Keys come from the
- * platform constant module ({@link ./platform.ts}, contract C1: single source
+ * platform constant module ({@link ./platform.ts}, the single source
  * of truth with the tsdown client externals); values stay shell-static
  * imports so every bundle sees the same instance.
  */
diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts
index a4edc604c8..9a7716aea0 100644
--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -21,8 +21,7 @@ export type {
  * Binding globals EVERY backend refuses because SOME backend owns the slot in
  * the program's namespace: `console` (the worker's log capture), and
  * `__dsh_main__`/`__builtins__`/`__name__` (the Python backend's bootstrap
- * wrapper and seeded module globals — that backend is a later PR in this
- * stack, see the [portable-identifier Agent
+ * wrapper and seeded module globals; see the [portable-identifier Agent
  * Note](../../../../.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md)),
  * and `__debug__`. One shared set — rather than each backend refusing only its
  * own slots — keeps the portability promise real: a namespace list valid on
@@ -68,12 +67,11 @@ export const DUNDER_MEMBER = /^__.+__$/
  * Reserved words of every portable target language (ECMAScript ∪ Python),
  * refused as {@link CodeBindingNamespace.global} / error-class names by all
  * backends. Python is a portability target here even though only the
- * TypeScript worker ships in this PR (the CPython backend is a later PR in the
- * stack). The portable-identifier contract promises a namespace list valid
- * on one backend is valid on every backend; a per-language check would let
- * `lambda` pass the TypeScript backend and fail the Python one. Extending the
- * seam with a new language means widening this union (a breaking review of
- * existing binding names, by design).
+ * TypeScript worker has a published backend. The portable-identifier contract
+ * promises a namespace list valid on one backend is valid on every backend; a
+ * per-language check would let `lambda` pass the TypeScript backend and fail
+ * the Python one. Extending the seam with a new language means widening this
+ * union (a breaking review of existing binding names, by design).
  */
 export const PORTABLE_RESERVED_WORDS: ReadonlySet<string> = new Set([
   // ECMAScript reserved words and reserved-in-strict-mode names.
diff --git a/packages/context/README.i18n.yaml b/packages/context/README.i18n.yaml
index b8025ef2bd..10e9ed6d7d 100644
--- a/packages/context/README.i18n.yaml
+++ b/packages/context/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/context/README.md
-README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
-README.zh.md: 653fd971a884e1b356e5a366d91f81caefd681c5
+README.md: 843f19b04c8dd63924a20d3ed01a5b179a731484
+README.zh.md: ac3233fa8d6ffee8f80cf485eaa87289260dc0f5
diff --git a/packages/context/README.md b/packages/context/README.md
index 237f619132..843f19b04c 100644
--- a/packages/context/README.md
+++ b/packages/context/README.md
@@ -11,6 +11,4 @@ Product plugins that add model-visible request context without defining a tool.
 | [`tmux-context/`](tmux-context/README.md) | tmux location context | — |
 | [`workspace-context/`](workspace-context/README.md) | Workspace-instruction context | — |
 
-The [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.
-
 Session references are documented in [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md); the [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) owns its per-agent/session isolation and lifecycle split.
diff --git a/packages/context/README.zh.md b/packages/context/README.zh.md
index 653fd971a8..ac3233fa8d 100644
--- a/packages/context/README.zh.md
+++ b/packages/context/README.zh.md
@@ -11,6 +11,4 @@
 | [`tmux-context/`](tmux-context/README.md) | tmux 位置上下文 | — |
 | [`workspace-context/`](workspace-context/README.md) | 工作区指令上下文 | — |
 
-[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
-
-会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent/会话隔离与生命周期拆分。
+会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent（智能体）/会话隔离与生命周期拆分。
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 585397d861..ec4d7e138b 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -575,7 +575,7 @@ describe('workspace context instruction discovery', () => {
     const emptyHome = await tempRepo()
     // Isolate the default-home fallback: blank DSH_HOME is treated as unset, and
     // HOME points at an empty dir so the default ~/.dsh holds no global scope.
-    // Symlinks are now followed, so a real ~/.dsh/AGENTS.md would otherwise leak in.
+    // Symlinks are followed, so a real ~/.dsh/AGENTS.md would otherwise leak in.
     vi.stubEnv('DSH_HOME', '')
     vi.stubEnv('HOME', emptyHome)
     try {
diff --git a/packages/core/session/src/chunk-rows.ts b/packages/core/session/src/chunk-rows.ts
index 56de67b405..ef46e40dbb 100644
--- a/packages/core/session/src/chunk-rows.ts
+++ b/packages/core/session/src/chunk-rows.ts
@@ -331,8 +331,7 @@ function expandRow(row: ChunkRow): SessionEvent[] {
  * Decode one parsed JSONL line value into the session event(s) it stores.
  * Chunk-row-tagged values validate and expand (a malformed row throws — it is
  * corrupt storage, and treating it as an event would silently drop a whole
- * run); every other value passes through as a single event, unvalidated,
- * exactly as readers treated event lines before packing existed.
+ * run); every other value passes through as a single event, unvalidated.
  *
  * @param value - one line's `JSON.parse` result.
  * @returns the stored events, in log order.
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index 1c9a622643..6074b51c02 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -338,7 +338,8 @@ export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: Surface
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 export type SurfaceOp =
   | 'append'
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index f5c5809544..4f094e4ade 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -38,10 +38,10 @@ interface RunCodeFlavor {
 }
 
 /**
- * The TypeScript flavor: the historical default, and the fallback for a schema
- * read with no runtime mounted ({@link resolveFlavor} owns which readers reach
- * that). A real assembly always resolves a runtime first, so the model never
- * sees this fallback outside its own language.
+ * The TypeScript flavor: the fallback for a schema read with no runtime
+ * mounted ({@link resolveFlavor} owns which readers reach that). A real
+ * assembly always resolves a runtime first, so the model never sees this
+ * fallback outside its own language.
  */
 const TYPESCRIPT_FLAVOR: RunCodeFlavor = {
   description:
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 1a5f6a05eb..75c0751ad9 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -857,8 +857,8 @@ export class ToolRegistry extends Service {
    * bound to a request. Harmless while one published backend exists — both
    * reads return the same flavor — but a reload that swapped in a second
    * language between them would hand a program written against one SDK to the
-   * other. Binding it belongs to the PR that publishes that backend, which is
-   * also the first point it can be tested; recorded in the
+   * other. Binding it is deferred until a second backend ships (the first
+   * point it is testable); rationale in the
    * [language-dispatch note](../../../../.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md).
    */
   private requireCodeRuntime(): CodeRuntime {
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index 33c05db92e..ec9b0f2190 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -41,12 +41,12 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * that normalize together would collapse into one declaration. Those names
  * take the subscript path, which carries their exact bytes.
  *
- * `IDENTIFIER`'s equivalence to `str.isidentifier()` was measured across 21
- * samples with zero divergence, on Node 22.23.1 against CPython 3.9.6 — every
- * sample sits inside the two versions' shared tables, and the skew characters
- * below are exactly where that pair diverges. The predicate as a whole is
- * deliberately stricter than `isidentifier()`, which does not test NFKC
- * stability: `'field'.isidentifier()` is True and this returns false.
+ * `IDENTIFIER` is equivalent to `str.isidentifier()` on Node 22.23.1 vs
+ * CPython 3.9.6 tables: the equivalence holds inside the two versions' shared
+ * tables, and the skew characters below are exactly where that pair diverges.
+ * The predicate as a whole is deliberately stricter than `isidentifier()`,
+ * which does not test NFKC stability: `'field'.isidentifier()` is True and
+ * this returns false.
  *
  * Both conditions are evaluated against the ENGINE's Unicode tables, and the
  * two sides are versioned independently — `\p{XID_Start}`/`\p{XID_Continue}`
@@ -85,8 +85,8 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * here — and the declared `class \u{A7DC}Args` fails with `invalid
  * non-printable character U+A7DC`. Closing the exposure therefore covers all
  * four read points, not this predicate alone; it needs the target interpreter's
- * version, which the backend reporting `language: 'python'` owns and which is
- * unpublished on this base, so the note records it as that PR's decision.
+ * version, which the backend reporting `language: 'python'` owns; the
+ * language-dispatch Agent Note records the deferral.
  *
  * The `ts-types` sibling keeps its own ASCII rule rather than sharing this
  * one: ECMAScript identifiers are a different set (`$`) and are never
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index e781c10f3e..c95e0291e1 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -29,8 +29,9 @@
  * The document holds nothing but credentials, which is why it is a strict
  * `CredentialRef`-to-string mapping rather than a dotenv file: a store the
  * Harness owns and never materializes into the environment cannot also serve
- * as the user's environment layer, and conflating the two is what made a
- * non-secret in the old `$DSH_HOME/.env` silently unreachable.
+ * as the user's environment layer; a store that doubled as the environment
+ * layer would shadow non-secret entries behind its precedence, making them
+ * silently unreachable.
  * @module @deepseek-ai/dsh-credentials-local
  */
 
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 43e42cd53f..26c917492f 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -130,8 +130,8 @@ describe('layer ladder', () => {
       { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'older-user-env' } },
     ])
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
-    // The old dead end is gone: a key sitting in the user's .env no longer
-    // makes the stored one unwritable.
+    // A key sitting in the user's .env does not make the stored one
+    // unwritable.
     expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'file', writable: true })
     await expect(ctx.credentials.set(KEY, 'rotated')).resolves.toBeUndefined()
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'rotated', source: 'file' })
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index edda1470df..7e78885c1e 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: fad17083817bd8023649ef7d0f0f1b62fbb9295f
-README.zh.md: e8544d71ee853547400e5970f0db9a9946562d48
+README.md: c48039f25ce234ce8b16d9829668224156855f31
+README.zh.md: 8cd7b703121d4a81fcb85b35beb89afd0cf2d7bd
diff --git a/packages/fs/README.md b/packages/fs/README.md
index fad1708381..c48039f25c 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The filesystem stack: a provider contract (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
+The filesystem stack: a provider contract (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the ripgrep-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -12,12 +12,12 @@ The filesystem stack: a provider contract (execution-world paths, bounded text I
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
-| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
+| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools backed by the packaged `@vscode/ripgrep` binary spawned through `ctx.subprocess`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The Service Definition lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the Service Definition, policy gate, or model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider contract: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The Service Definition lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the Service Definition, policy gate, or model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider contract: search is a process-backed `rg` workflow (the packaged `@vscode/ripgrep` binary spawned through `ctx.subprocess`), so filesystem backends stay free of a universal search contract; its tools register unconditionally, and its results are follow-up-readable when the search workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs` and the provider contract arms no deadline: file IO here runs untimed because a deadline would kill work the OS will still finish — see [the filesystem subsystem page](../../docs/subsystems/filesystem.md). Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index e8544d71ee..8cd7b70312 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-文件系统栈包括：提供方约定（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
+文件系统栈包括：提供方约定（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 ripgrep 的发现工具。全部都是**产品** 包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
@@ -12,12 +12,12 @@
 | `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
 | `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
-| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
+| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具，由经 `ctx.subprocess` spawn 的打包 `@vscode/ripgrep` 二进制文件支持，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-Service Definition 位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方约定：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+Service Definition 位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方约定：搜索是由进程支持的 `rg` 工作流（经 `ctx.subprocess` spawn 的打包 `@vscode/ripgrep` 二进制文件），因此文件系统后端无需承担通用搜索约定；其工具会无条件注册。如果搜索工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
-`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方约定也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方约定也不启动 deadline：这里的文件 I/O 不计时运行，因为 deadline 只会杀掉操作系统仍会完成的工作——参见[文件系统子系统页面](../../docs/subsystems/filesystem.md)。取消仍通过工具执行信号传播，在系统调用边界尽力中止。
 
 子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index dabdcacd3c..c13921729a 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 2b10614c8bf3d7e4a26c7f3d90dbc127cfec4336
-README.zh.md: e0cbf058bb8d6b52e8c8e5a048cc8b3d757e67d0
+README.md: 62d3febde82e013ace054a9e6242147c1756b0d1
+README.zh.md: 137c1e8da1014bf7dda7c4bf2e667aca6d2f51b5
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 2b10614c8b..62d3febde8 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -13,7 +13,7 @@ This package owns the Service Definition and provider contract layer of the four
 | provider contract | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
 | provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
 
-A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
+`fs-sandbox` and `fs-e2b` implement this interface without touching the policy/tool layers.
 
 ## Service API (`ctx.fs`)
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index e0cbf058bb..137c1e8da1 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -13,7 +13,7 @@
 | 提供方约定 | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
 
-未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
+`fs-sandbox` 与 `fs-e2b` 实现该接口，无需更改政策层和工具层。
 
 ## 服务 API（`ctx.fs`）
 
diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml
index a8fe6a80d7..44e161841d 100644
--- a/packages/fs/tool-fs-search/README.i18n.yaml
+++ b/packages/fs/tool-fs-search/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/fs/tool-fs-search/README.md
-README.md: 32fa61e3bb09b2166499003953a5631a93baf73b
-README.zh.md: 34ffcdc9f64daba7350e4581b35e694213f24214
+README.md: 7803ce52c1b9d2d858dadb718edd163585360aef
+README.zh.md: 3a34f4e8a04666b72f09eca1b41fea825d5a609f
diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md
index 32fa61e3bb..7803ce52c1 100644
--- a/packages/fs/tool-fs-search/README.md
+++ b/packages/fs/tool-fs-search/README.md
@@ -16,7 +16,7 @@ Why spawn-backed: local workspace discovery is naturally a process-backed `rg` w
 
 ## Deployment requirement: no host rg, co-located workdir/filesystem
 
-The binary ships with the package on every supported platform (macOS/Linux/Windows, x64/arm64), so no host `rg` install is required and the tools register on every deployment. Returned paths are displayed relative to the resolved workdir (the calling agent's session cwd when present, else `process.cwd()`) and are follow-up-readable with `read` only when that workdir and the filesystem root are the same workspace. v1 documents that co-location requirement and performs no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
+The binary ships with the package on every supported platform (macOS/Linux/Windows, x64/arm64), so no host `rg` install is required and the tools register on every deployment. Returned paths are displayed relative to the resolved workdir (the calling agent's session cwd when present, else `process.cwd()`) and are follow-up-readable with `read` only when that workdir and the filesystem root are the same workspace. That co-location requirement carries no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
 
 ## Config
 
diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md
index 34ffcdc9f6..3a34f4e8a0 100644
--- a/packages/fs/tool-fs-search/README.zh.md
+++ b/packages/fs/tool-fs-search/README.zh.md
@@ -16,7 +16,7 @@ await ctx.plugin(LocalSpillStore)                           // @deepseek-ai/dsh-
 
 ## 部署要求：无需宿主 rg，但工作目录与文件系统需共置
 
-二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
+二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。这项共置要求不附带运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
 
 ## 配置
 
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index a301417b4b..96785be516 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: 6878584b72c3e799ca8a46ddc6fc2908f9bc3acf
-README.zh.md: d8e92d96c60d30ec4aa943b77b882517324c4e52
+README.md: 27b53aca50f470fe9ead4da27d87328264440ff7
+README.zh.md: 5bcf9c471d933702c46d50c56c9539cb9eede3ca
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 6878584b72..27b53aca50 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -148,6 +148,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam.
+- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies ripgrep-backed `glob` and `grep` rather than extending the filesystem seam.
 - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
 - **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../README.md#no-timeouts-on-file-io)).
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index d8e92d96c6..5bcf9c471d 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -148,6 +148,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 ## 已知限制与暂缓事项
 
-- **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 bash 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
+- **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 ripgrep 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。
 - **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../README.md#no-timeouts-on-file-io)）。
diff --git a/packages/goal/goal/src/domain.ts b/packages/goal/goal/src/domain.ts
index 90f22a1602..3dc5672f0b 100644
--- a/packages/goal/goal/src/domain.ts
+++ b/packages/goal/goal/src/domain.ts
@@ -1,9 +1,9 @@
 /**
  * Host-side vocabulary of the goal domain: live views, durable change
  * payloads, message attribution, replay folds, and the scoped `goal/changed`
- * event. Split from ./types.ts (the pure client-safe outlet) because these
- * declarations pull dsh-agent, dsh-llm, and cordis into the program — the
- * one-program-per-side layout forbids that on client aggregates.
+ * event. Kept separate from ./types.ts (the pure client-safe outlet) because
+ * these declarations pull dsh-agent, dsh-llm, and cordis into the program —
+ * the one-program-per-side layout forbids that on client aggregates.
  * @module @deepseek-ai/dsh-goal
  */
 
diff --git a/packages/guard/timeout-policy/README.i18n.yaml b/packages/guard/timeout-policy/README.i18n.yaml
index 3c41810118..f3014395b4 100644
--- a/packages/guard/timeout-policy/README.i18n.yaml
+++ b/packages/guard/timeout-policy/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/guard/timeout-policy/README.md
-README.md: 3e5769e2f8b95392e9d489659c6bae634ab3ff18
-README.zh.md: bfba62cdfae8bb956aec43bcf6e8df12407d8ba2
+README.md: 70b1f392bfbce91962447dee86afbbb148817811
+README.zh.md: e285caa5f7b123d02979e404125bce20932f9223
diff --git a/packages/guard/timeout-policy/README.md b/packages/guard/timeout-policy/README.md
index 3e5769e2f8..70b1f392bf 100644
--- a/packages/guard/timeout-policy/README.md
+++ b/packages/guard/timeout-policy/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Tool-call timeout enforcer: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for a tool declaring `timeoutMs` on its `ToolDefinition` and returns a structured `TOOL_TIMEOUT` result when that deadline wins. The budget is read from the tool's own declaration (`ToolDefinition.timeoutMs`, set by the owning tool plugin), so this plugin is **zero-config**. It is the reference `tools/execute` wrapper and the enforcement home for model-facing tool-call budgets (the timeout-library Agent Note's foreseen middleware).
+Tool-call timeout enforcer: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for a tool declaring `timeoutMs` on its `ToolDefinition` and returns a structured `TOOL_TIMEOUT` result when that deadline wins. The budget is read from the tool's own declaration (`ToolDefinition.timeoutMs`, set by the owning tool plugin), so this plugin is **zero-config**. It is the reference `tools/execute` wrapper and the enforcement home for model-facing tool-call budgets ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
 
 ## Plugin (namespace: `timeout-policy`)
 
diff --git a/packages/guard/timeout-policy/README.zh.md b/packages/guard/timeout-policy/README.zh.md
index bfba62cdfa..e285caa5f7 100644
--- a/packages/guard/timeout-policy/README.zh.md
+++ b/packages/guard/timeout-policy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-工具调用超时强制执行器：单个 `tools/execute` 环绕分发监听器，会在 `exec.signal` 上设置单次调用的协作式截止时间；适用于声明了 `timeoutMs` 且声明位于其 `ToolDefinition` 上的工具。该截止时间先到时，它返回结构化 `TOOL_TIMEOUT` 结果。预算从工具自身的声明中读取（`ToolDefinition.timeoutMs`，由拥有该工具的插件设置），因此此插件是**零配置**的。它是 `tools/execute` 包装层的参考实现，也是面向模型工具调用预算的强制执行归属地（超时库 Agent Note 所预见的中间件）。
+工具调用超时强制执行器：单个 `tools/execute` 环绕分发监听器，会在 `exec.signal` 上设置单次调用的协作式截止时间；适用于声明了 `timeoutMs` 且声明位于其 `ToolDefinition` 上的工具。该截止时间先到时，它返回结构化 `TOOL_TIMEOUT` 结果。预算从工具自身的声明中读取（`ToolDefinition.timeoutMs`，由拥有该工具的插件设置），因此此插件是**零配置**的。它是 `tools/execute` 包装层的参考实现，也是面向模型工具调用预算的强制执行归属地（[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
 
 ## 插件（命名空间：`timeout-policy`）
 
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index 61361487ba..0a60223517 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
-README.md: 230f14c2bc053555991e5fb96e2753aef5bbff8a
-README.zh.md: d83ea99065123c9cf0f85c0abbbeeff6eadb17bc
+README.md: b2570ba8f2ab5dfb468b7d7fa3cc1270cefcbbb1
+README.zh.md: 3bd229a5d469db4a6f1e18b09df62fb8e1204747
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index 230f14c2bc..b2570ba8f2 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The **shared core** of the Claude Code / Codex hook wire protocol. NOT a cordis plugin — it registers nothing and injects nothing. It is a **library** of dialect-neutral primitives the two bridge plugins (`@deepseek-ai/dsh-hooks-claude`, `@deepseek-ai/dsh-hooks-codex`) import so neither re-implements the identical halves of the protocol.
 
-Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claude Code hook protocol — the same `hooks.json` matcher-group shape, the same exit-code/stdout output contract, the same command-hook execution model. The genuinely-shared parts live here; each bridge owns only what differs.
+Codex deliberately reimplements a *subset* of the Claude Code hook protocol — the same `hooks.json` matcher-group shape, the same exit-code/stdout output contract, the same command-hook execution model. The genuinely-shared parts live here; each bridge owns only what differs.
 
 ## What's shared (here) vs. per-dialect (the bridges)
 
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index d83ea99065..3bd229a5d4 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -4,7 +4,7 @@
 
 Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它不是 Cordis 插件：不注册也不注入任何内容。它是一个**库**，提供两个桥接插件（`@deepseek-ai/dsh-hooks-claude`、`@deepseek-ai/dsh-hooks-codex`）导入的方言无关原语，使两者都无需重复实现协议中相同的部分。
 
-共享 lib 存在的原因是：Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
+Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
 
 ## 共享内容（此处）与各方言内容（桥接）
 
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index 39802d0b6c..b60ce7b520 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -48,7 +48,7 @@ export interface Config {
    * Process-level: read once at load, a relative path resolves against the process
    * launch cwd, so one config applies to the whole process.
    * TODO(per-session-hook-config): per-session discovery of a project-local
-   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   * `hooks.json` from each `session/new.cwd`.
    */
   configPath: string
   /**
diff --git a/packages/hooks/hooks-codex/README.i18n.yaml b/packages/hooks/hooks-codex/README.i18n.yaml
index 4af0518ab2..da27f59159 100644
--- a/packages/hooks/hooks-codex/README.i18n.yaml
+++ b/packages/hooks/hooks-codex/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/hooks/hooks-codex/README.md
-README.md: f8e0684e0bf4eafadcb31d8c82dde177411db2bf
-README.zh.md: d278e78204c1bd320980420b506135997cd3a4cc
+README.md: 0a4f918acd960ae63bd131d11f77e8ab52f9ca47
+README.zh.md: 044a9c6e661045e4b152f4200f0f843b47faef34
diff --git a/packages/hooks/hooks-codex/README.md b/packages/hooks/hooks-codex/README.md
index f8e0684e0b..0a4f918acd 100644
--- a/packages/hooks/hooks-codex/README.md
+++ b/packages/hooks/hooks-codex/README.md
@@ -96,5 +96,5 @@ A blocked prompt sends no request and invalidates nothing. Denial, feedback, and
 - **`PreToolUse` is partial:** blocking works, but `additionalContext`, `permissionDecision: "allow"`, and `updatedInput` are ignored. Every tool is represented as `tool_input: { command }`, so non-shell tool arguments are not faithfully exposed to the hook.
 - **`PostToolUse` is partial:** blocking feedback and JSON `additionalContext` work, but `{"continue": false}` is not enforced, non-shell tool arguments are reduced to `{ command }`, and structured tool output is flattened to text in `tool_response`.
 - **`Stop` is partial:** blocking forces another model turn, but `stop_hook_active` is always `false`, `last_assistant_message` is always `null`, and `{"continue": false}` is not enforced. An unconditionally blocking hook therefore force-continues every step unless it self-limits (`TODO(stop-loop-guard)`).
-- **Common payload and output fields are partial:** every mapped event reports `transcript_path: null`, the statically configured `model`, and `permission_mode: "default"` instead of current Codex runtime values. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior (`TODO(hook-continue-false)`).
+- **Common payload and output fields are partial:** every mapped event reports the statically configured `model` and `permission_mode: "default"` instead of current Codex runtime values. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior (`TODO(hook-continue-false)`).
 - **Config loading and execution are partial:** one process-level `configPath` is parsed at load; Codex's active user, project, session, system/managed, and plugin layers, trust controls, and inline `config.toml` hook form are not implemented (`TODO(per-session-hook-config)`). Only synchronous `command` handlers run, current metadata such as `statusMessage` and `commandWindows` is ignored, and matching handlers run serially rather than with Codex's concurrent launch semantics.
diff --git a/packages/hooks/hooks-codex/README.zh.md b/packages/hooks/hooks-codex/README.zh.md
index d278e78204..044a9c6e66 100644
--- a/packages/hooks/hooks-codex/README.zh.md
+++ b/packages/hooks/hooks-codex/README.zh.md
@@ -96,5 +96,5 @@ hook 不返回上下文时没有成本。Hook 文本取决于数据，会被记
 - **`PreToolUse` 只支持部分功能：** 支持阻塞，但会忽略 `additionalContext`、`permissionDecision: "allow"` 和 `updatedInput`。每个工具都表示为 `tool_input: { command }`，因此非 shell 工具参数不会如实公开给 hook。
 - **`PostToolUse` 只支持部分功能：** 支持阻塞反馈与 JSON `additionalContext`，但不会强制执行 `{"continue": false}`，非 shell 工具参数会缩减为 `{ command }`，结构化工具输出会在 `tool_response` 中展平为文本。
 - **`Stop` 只支持部分功能：** 阻塞会强制另一个模型轮次，但 `stop_hook_active` 始终为 `false`，`last_assistant_message` 始终为 `null`，且不会强制执行 `{"continue": false}`。因此，无条件阻塞 hook 会在每个步骤中强制 continuation，除非它自我限制（`TODO(stop-loop-guard)`）。
-- **通用 payload 与输出字段只支持部分功能：** 每个已映射事件都报告 `transcript_path: null`、静态配置的 `model` 与 `permission_mode: "default"`，而非当前 Codex 运行时值。`systemMessage` 会被记录并触发警告，但不呈现，`{"continue": false}` 会被记录但不会应用 Codex 事件特定停止行为（`TODO(hook-continue-false)`）。
+- **通用 payload 与输出字段只支持部分功能：** 每个已映射事件都报告静态配置的 `model` 与 `permission_mode: "default"`，而非当前 Codex 运行时值。`systemMessage` 会被记录并触发警告，但不呈现，`{"continue": false}` 会被记录但不会应用 Codex 事件特定停止行为（`TODO(hook-continue-false)`）。
 - **配置加载与执行只支持部分功能：** 一个进程级 `configPath` 会在加载时解析；尚未实现 Codex 的活动用户层、项目层、会话层、系统／托管层和插件层、信任控制与内联 `config.toml` hook 形式（`TODO(per-session-hook-config)`）。只运行同步 `command` handler，忽略 `statusMessage` 与 `commandWindows` 等当前元数据，匹配 handler 串行运行，而非使用 Codex 的并发启动语义。
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 34f47f5a7e..d31d9f8c48 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -46,7 +46,7 @@ export interface Config {
    * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
    * path resolves against the process launch cwd.
    * TODO(per-session-hook-config): per-session project-local discovery from each
-   * `session/new.cwd` is not yet implemented.
+   * `session/new.cwd`.
    */
   configPath: string
   /** The model name stamped on every payload (Codex includes `model` on each event). */
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 3069ec7948..e6ea7dd50d 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 9b430fca1c2352334e6428eb37b80726a4e02c02
-README.zh.md: c36a88b44348d0054e71ea9d796291b91fadbf20
+README.md: 44b8ee76b0da67ef1aaf24fb3d54e91d20fc064a
+README.zh.md: 06b05aa64727c8bce08c7935040a1766f30b98ed
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 9b430fca1c..44b8ee76b0 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -28,7 +28,7 @@ Question responses are validated against their pending request before the first
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
-Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
+Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key. Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
 
 `session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged `ModelSelection`, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index c36a88b443..06b05aa647 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -28,7 +28,7 @@ Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
-会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
+会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
 
 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的 `ModelSelection` 及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index d0f3698328..e417ca12b2 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1421,8 +1421,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     sessions: {
       // Attached sessions summarize from memory; persisted-but-unattached (cold)
       // sessions merge in from the persistence store so history survives restarts.
-      // Legacy logs without a cwd (pre-project stance) are not served — every
-      // session now records its project at create time.
+      // Logs without a cwd are not served; every session records its project
+      // at create time.
       async list(request) {
         return ok(request, { items: await listVisibleSessionSummaries() })
       },
@@ -2184,7 +2184,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
     host: {
       describe(request) {
-        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        // TODO: version should read apps/cli's package.json; placeholder for now.
         const selection = defaults.defaultModelSelection()
         return Promise.resolve(ok(request, {
           version: '0.0.1',
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index 667e85bdac..8004f952e4 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -88,8 +88,8 @@ export class ApiProxyService extends Service implements ApiProxy {
     this.credentials = api.credentials
     this.llm = api.llm
     this.events = api.events
-    // createApiProxy returns closures (no `this` capture); bind only satisfies
-    // the unbound-method lint without changing behavior.
+    // createApiProxy returns closures (no `this` capture), so the bind is
+    // behavior-neutral.
     this.respond = api.respond.bind(api)
   }
 }
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 4449df15f6..37e0e14169 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -365,10 +365,10 @@ describe('subagent ownership fence', () => {
       inspect: () => Promise.resolve({ meta, events }),
       locate: () => undefined,
     } as never)
-    // Pre-#1569 stores classify a child only through the descriptor event and
-    // carry no header `origin`; the pre-release decision stops recognizing
-    // them, so the ownership fence lets generic resume reach the registry
-    // instead of answering `agent-busy`.
+    // Stores whose headers predate `origin` classify a child only through the
+    // descriptor event; the pre-release decision stops recognizing them, so
+    // the ownership fence lets generic resume reach the registry instead of
+    // answering `agent-busy`.
     const resume = vi.spyOn(ctx.agents, 'resume')
       .mockRejectedValue(new Error('registry unavailable in this bench'))
     const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 13968616b8..c6cdc237b4 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -367,9 +367,10 @@ describe('settings domain', () => {
 
   it('invalidates the model catalog when a provider namespace changes, and broadcasts a raw-only change', async () => {
     // Editing `models` changes no route, so llm/adapters-updated never fires
-    // and an open model picker kept serving the old catalog. And storing an
-    // override equal to the resolved value emits nothing on settings/updated,
-    // so another tab never learned the field became overridden.
+    // and an open model picker would keep serving the stale catalog. Storing
+    // an override equal to the resolved value emits nothing on
+    // settings/updated, so another tab would never learn the field became
+    // overridden.
     const ctx = await harness()
     ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
     const api = createApiProxy(ctx, DEFAULTS)
diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx
index fc6dde82f1..222bcbe079 100644
--- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx
+++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx
@@ -773,8 +773,7 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
         onKeyDown={(event) => {
           if (event.key !== 'Escape' || pathDraft === null) return
           // stopPropagation keeps the card-scope Escape from the Modal's
-          // document listener — the same containment the input previously
-          // provided for itself.
+          // document listener.
           event.stopPropagation()
           // Escape while the input holds focus is about to unmount it; with
           // focus already parked on a row, that row survives the cancel and
diff --git a/packages/host/directory-picker-native/src/native-picker.ts b/packages/host/directory-picker-native/src/native-picker.ts
index 576353ea8c..45a62a72e5 100644
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -70,8 +70,8 @@ export async function pickNativeDirectory(
     // The koffi-backed IFileOpenDialog child process — the modern picker with
     // per-monitor-v2 DPI and abort support. koffi is a packaged dependency
     // whose availability the install guarantees, so there is no fallback
-    // tier: any failure surfaces as-is (the former PowerShell chain was
-    // removed — see the simplification Agent Note).
+    // tier: any failure surfaces as-is (no PowerShell fallback tier; see
+    // the simplification Agent Note).
     const pickDialog = internals.pickWin32Dialog ?? pickWin32Directory
     return await pickDialog(signal)
   }
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index 70eacaa627..f0b63080ed 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -86,8 +86,7 @@ const OUTCOMES: readonly ApprovalOutcome[] = ['allowed-once', 'rejected', 'cance
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index a7e1f433e5..340bed3ee9 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -132,7 +132,7 @@ describe('llm-deepseek real dynamic composition', () => {
   })
 
   it('keeps a stored key writable and rotatable across a real restart', async () => {
-    // No ambient DEEPSEEK_API_KEY: the shipped surfaces no longer hoist
+    // No ambient DEEPSEEK_API_KEY: the shipped surfaces do not hoist
     // the credentials document into process.env, so a stored key must stay file-sourced.
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const first = await mockServer([{ kind: 'sse', events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/src/catalog.ts b/packages/llm/llm-pi-ai/src/catalog.ts
index 8f1bc1a43c..4e0cf3c092 100644
--- a/packages/llm/llm-pi-ai/src/catalog.ts
+++ b/packages/llm/llm-pi-ai/src/catalog.ts
@@ -62,8 +62,7 @@ type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
 
 /**
  * pi-ai thinking formats a profile cannot name: both drive the request through
- * `chatTemplateKwargs`, which this configuration does not expose, so offering
- * them would hand back a format with nothing to say.
+ * `chatTemplateKwargs`, which this configuration does not expose.
  */
 type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 
@@ -467,10 +466,8 @@ export function resolveRouteModels(request: RouteCatalogRequest): RouteCatalog {
       // The installed entry lays the floor, and the fields below override it.
       // Enumerating instead would silently drop every `Model` field this
       // package does not model — reasoning-level spellings, compatibility
-      // quirks, model headers, and whatever a pi-ai upgrade adds next. That is
-      // not hypothetical: `headers` reached this file only after an nvidia
-      // route lost it, and a rebuild keeps re-earning that bug on every
-      // upgrade.
+      // quirks, model headers, and whatever a pi-ai upgrade adds next. Spread,
+      // never enumerate.
       ...base,
       id: entry.id,
       name: entry.name ?? base?.name ?? entry.id,
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 2c5cb7bb48..6f49c1d76f 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: 0b463c73175e46d20e9c8f719b55b3fa4f56fde2
-README.zh.md: cbabeb72216e9fc92b74d6c216d7f7b7154bc1a8
+README.md: c74dd5705ab67d5bf4bf966cfb9004e6ae1cc3d7
+README.zh.md: 17a0fd92b48db3ea5122ac2f1c1ed6e116e6d6e0
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index 0b463c7317..c74dd5705a 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -26,7 +26,7 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 
 `LlmService` normalizes failures from final adapter selection, synchronous dispatch, iterator construction, and iteration into the stream protocol's single terminal form: `finish { kind: 'error' | 'aborted', failure }`. A failure after partial deltas may leave content blocks open; consumers discard that incomplete output. Errors from `llm/stream` middleware, nested calls, adapter cleanup, and downstream consumers remain thrown because they are plugin or consumer failures rather than model-request outcomes. A prepared call exposes the immutable retry policy captured with its exact adapter registration; a route handled entirely by middleware has no serving policy.
 
-Interrogating an endpoint is configuration-time work over a *draft*, which is why it is keyed by settings namespace rather than by provider route: the provider a surface is adding does not exist yet, so there is no route to name. The request may still *name* a route it is editing, and an adapter that already describes that route should answer from its own knowledge — better metadata, no network call — which is why `baseURL` is optional and one of the two is required. The request otherwise carries the endpoint, the protocol, and a credential the harness uses for that one interrogation and never stores — nothing here reads or writes settings or credentials, and the reply is candidate metadata a surface may offer for adoption, never a registered catalog. `LlmDiscoveredModel` makes every field but `id` optional because most provider listings disclose an id and nothing else; a surface adopting one still owes the capacities its adapter requires. Duplicate and unusable ids are dropped, an unserved namespace fails with `NO_DISCOVERY`, and a request naming neither a route nor an endpoint fails with `INVALID_DISCOVERY`.
+Interrogating an endpoint is configuration-time work over a *draft*, keyed by settings namespace rather than by provider route — the provider a surface is adding does not exist yet, so there is no route to name. The request may still *name* a route it is editing, and an adapter that already describes that route answers from its own knowledge without a network call; `baseURL` is optional and one of the two is required. The request otherwise carries the endpoint, the protocol, and a credential the harness uses for that one interrogation and never stores — nothing here reads or writes settings or credentials, and the reply is candidate metadata a surface may offer for adoption, never a registered catalog. `LlmDiscoveredModel` makes every field but `id` optional because most provider listings disclose an id and nothing else; a surface adopting one still owes the capacities its adapter requires. Duplicate and unusable ids are dropped, an unserved namespace fails with `NO_DISCOVERY`, and a request naming neither a route nor an endpoint fails with `INVALID_DISCOVERY`.
 
 Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity and captures the adapter's retry policy for each route, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned selector metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`.
 
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index cbabeb7221..17a0fd92b4 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -26,7 +26,7 @@
 
 `LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
 
-询问端点属于配置期针对**草稿**的操作，因此以 settings namespace 而非提供方路由为键：界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器应当用自己的知识作答——元数据更好，且无需联网——这正是 `baseURL` 可选、两者至少要有一个的原因。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
+询问端点属于配置期针对**草稿**的操作，以 settings namespace 而非提供方路由为键——界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器会用自己的知识作答，无需联网；`baseURL` 可选，两者至少要有一个。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
 
 提供方与模型元数据是发现接口，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。
 
diff --git a/packages/llm/llm/src/message.ts b/packages/llm/llm/src/message.ts
index c4032f5294..2673072fa0 100644
--- a/packages/llm/llm/src/message.ts
+++ b/packages/llm/llm/src/message.ts
@@ -35,8 +35,8 @@ export interface ToolMessageSource {
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
  *
  * The vocabulary is SEMANTIC, never visual: a value states that the content is
  * a file's instructions or a catalog of available items, and a consumer decides
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index 9b68fa047a..03def91947 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/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/llm/token-meter/README.md
-README.md: 929d0322f6268562a10b9ab715cc0330800966b5
-README.zh.md: 40cea07c7dea20d0af9bf67ade2cb4164f7aed08
+README.md: 6cbbefa69fd4dd108d4c4ff717647e173922d7b2
+README.zh.md: 572409324e910f4b38ad48b2ec5fb2c85d4fd088
diff --git a/packages/llm/token-meter/README.md b/packages/llm/token-meter/README.md
index 929d0322f6..6cbbefa69f 100644
--- a/packages/llm/token-meter/README.md
+++ b/packages/llm/token-meter/README.md
@@ -6,7 +6,7 @@ Replay-aware token measurement through the singleton `ctx.tokenMeter` service. I
 
 ## Configuration
 
-The estimator has no settings. It intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. Any key is rejected, including the obsolete global `contextWindow`; model capacity belongs to the adapter that owns an exact provider/model route and is available through `ctx.llm.resolveModelInfo().context`.
+The estimator has no settings. It intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. Any key is rejected; model capacity belongs to the adapter that owns an exact provider/model route and is available through `ctx.llm.resolveModelInfo().context`.
 
 ## Measurement contract
 
@@ -41,7 +41,7 @@ The occupancy fields are independent last-wins records and are **not** one atomi
 
 This is deliberate. An occupancy percentage is a user-facing reference figure, not a billing record or a gating input — nothing in the harness makes decisions from it, and compaction reads `measure()` instead. A UI computes occupancy by dividing measured pressure by the separately resolved capacity for the selected model.
 
-Making the pair atomic was tried and rejected: it required a transient non-replayable wire frame, which needed lifecycle fencing against cross-stream reordering and left occupancy blank after every reconnect. The [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md) records that comparison. Consumers that need an exact same-boundary figure should call `measure()` at their own request boundary rather than read this projection.
+The [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md) records the rejected atomic-pair comparison. Consumers that need an exact same-boundary figure should call `measure()` at their own request boundary rather than read this projection.
 
 ## Composition
 
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index 40cea07c7d..572409324e 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 配置
 
-估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝，包括已废弃的全局 `contextWindow`；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
+估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
 
 ## 测量约定
 
@@ -41,7 +41,7 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 
 这是刻意的选择。占用率百分比是面向用户的参考数字，既不是计费记录，也不是门控输入：harness 中没有任何环节依据它做决策，压缩改为直接读取 `measure()`。UI 用测得的压力除以为所选模型单独解析出的容量来计算占用率。
 
-让这对值保持原子已经尝试过并被否决：它需要一个临时且不可回放的协议帧，进而需要针对跨流重排序的生命周期栅栏，还会让占用率在每次重连后变为空白。[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md)记录了这项对比。需要同一边界精确数字的消费方应在自己的请求边界调用 `measure()`，而不是读取该投影。
+[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md)记录了否决「让这对值保持原子」方案的那次对比。需要同一边界精确数字的消费方应在自己的请求边界调用 `measure()`，而不是读取该投影。
 
 ## 组合
 
diff --git a/packages/lsp/lsp/src/types.ts b/packages/lsp/lsp/src/types.ts
index d1bebe2a58..2e61d019ca 100644
--- a/packages/lsp/lsp/src/types.ts
+++ b/packages/lsp/lsp/src/types.ts
@@ -12,7 +12,7 @@ import type { LspProviderId } from './brand.ts'
 /**
  * The four semantic queries the seam and model expose. A closed union: adding an operation is a
  * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * deliberately deferred (they need different schemas).
+ * not operations here; they need different schemas.
  */
 export type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
 
diff --git a/packages/mcp/mcp-client/src/tools.ts b/packages/mcp/mcp-client/src/tools.ts
index 28c2a66319..889684923b 100644
--- a/packages/mcp/mcp-client/src/tools.ts
+++ b/packages/mcp/mcp-client/src/tools.ts
@@ -258,9 +258,8 @@ function createExecutor(
     }
 
     // Trust boundary: the SDK's return type erases to `any[]` due to the
-    // union of CallToolResult | CompatibilityCallToolResult. We process each
-    // element defensively in extractText (reading only .type/.text/.mimeType
-    // with optional fallbacks).
+    // union of CallToolResult | CompatibilityCallToolResult; extractText
+    // validates each element.
     const content = result.content as unknown as JsonValue[]
     const text = extractText(content, rawName)
 
diff --git a/packages/mcp/mcp-client/src/transport.ts b/packages/mcp/mcp-client/src/transport.ts
index f4bed91931..bc7fd1cc08 100644
--- a/packages/mcp/mcp-client/src/transport.ts
+++ b/packages/mcp/mcp-client/src/transport.ts
@@ -40,9 +40,8 @@ export function createTransport(config: Config): Transport {
     case 'streamable-http':
       // The MCP SDK's StreamableHTTPClientTransport has optional callback
       // properties typed without `| undefined` (exactOptionalPropertyTypes
-      // mismatch with the Transport interface). The cast is safe — the SDK
-      // constructed the object, it simply doesn't declare the optionals
-      // strictly enough for our tsconfig.
+      // mismatch with the Transport interface); the SDK constructed the
+      // object, so the cast records only that widening.
       return new StreamableHTTPClientTransport(
         new URL(config.url),
         { requestInit: { headers: config.headers } },
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 44b3e272f4..e30a1ee716 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -175,7 +175,6 @@ describe('apply (plugin lifecycle)', () => {
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
     await expect(apply(ctx, stdioConfig)).rejects.toThrow(/serverName "srv" is already in use/)
-    // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
 
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index d19e30b94b..22559d74cf 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -207,7 +207,6 @@ describe('syncTools', () => {
     const firstDisposers = await syncTools(client as never, ctx, defaultOpts, new Map())
     expect(ctx.tools.get('mcp__srv__old_tool')).toBeDefined()
 
-    // Second sync with different tools should remove old_tool.
     client.listTools.mockResolvedValue({ tools: [{ name: 'new_tool', inputSchema: { type: 'object' } }], nextCursor: undefined })
     const secondDisposers = await syncTools(client as never, ctx, defaultOpts, firstDisposers)
 
@@ -770,13 +769,11 @@ describe('createTransport', () => {
         toolCallTimeoutMs: 60_000,
         failOnStartupError: false,
       }
-      // createTransport internally calls buildChildEnv; we verify by inspecting
-      // the constructed StdioClientTransport. Since we can't inspect private fields
-      // easily, we at least confirm it doesn't throw and returns a transport.
+      // StdioClientTransport keeps its env private; the observable contract is
+      // that createTransport(config) returns a transport without throwing.
       const transport = createTransport(config)
       expect(transport).toBeDefined()
     } finally {
-      // Restore env
       delete process.env.SAFE_VAR
       delete process.env.MY_SECRET
       delete process.env.API_KEY
diff --git a/packages/scaffold/README.i18n.yaml b/packages/scaffold/README.i18n.yaml
index 7ddc22328c..9cc0926043 100644
--- a/packages/scaffold/README.i18n.yaml
+++ b/packages/scaffold/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/scaffold/README.md
-README.md: 19c2f28f48d1c2d8747b635c10d6781c29e02f15
-README.zh.md: ecad2592eb32a30444f9112571379939da6afeec
+README.md: f36e828a507aea80a064de7d7de30ba65d63600b
+README.zh.md: f58d8c8defeea948d59c3b11b4c60703b8144ea8
diff --git a/packages/scaffold/README.md b/packages/scaffold/README.md
index 19c2f28f48..f36e828a50 100644
--- a/packages/scaffold/README.md
+++ b/packages/scaffold/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
+This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
 
 | Package | Role |
 |---|---|
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
index ecad2592eb..f58d8c8def 100644
--- a/packages/scaffold/README.zh.md
+++ b/packages/scaffold/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
+本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
 
 | 包 | 职责 |
 |---|---|
diff --git a/packages/scaffold/telemetry/README.i18n.yaml b/packages/scaffold/telemetry/README.i18n.yaml
index 4d70fce157..beb145cfc0 100644
--- a/packages/scaffold/telemetry/README.i18n.yaml
+++ b/packages/scaffold/telemetry/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/scaffold/telemetry/README.md
-README.md: c87735a93e7659f2913f4dd325176a8ae40cf29b
-README.zh.md: 24d6e72d988f94cdbc6aa01607edbfc105213267
+README.md: 024ff8724604426d3d77609929ca40341f98e0fb
+README.zh.md: 8d69d9289ed9c412e4d38fe9b24bb3222f81f94a
diff --git a/packages/scaffold/telemetry/README.md b/packages/scaffold/telemetry/README.md
index c87735a93e..024ff87246 100644
--- a/packages/scaffold/telemetry/README.md
+++ b/packages/scaffold/telemetry/README.md
@@ -14,7 +14,7 @@ Launcher-side telemetry primitives for the dsh-sdk toolchain. This is a plain li
 
 Consent is carried by the telemetry entry in `cordis.yml`, so disabling telemetry is disabling that entry. Telemetry reports by default and is off only when a present telemetry entry is explicitly `disabled`: a missing `cordis.yml` (first `create`), an enabled entry, or a `cordis.yml` with no telemetry entry all report. `DO_NOT_TRACK`/CI always deny. The no-config and absent-entry defaults are configurable on `ConsentResolver`.
 
-The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`); its fail-safe `.invalid` placeholder must be replaced with the real endpoint before release.
+The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`).
 
 ## Model Experience
 
diff --git a/packages/scaffold/telemetry/README.zh.md b/packages/scaffold/telemetry/README.zh.md
index 24d6e72d98..8d69d9289e 100644
--- a/packages/scaffold/telemetry/README.zh.md
+++ b/packages/scaffold/telemetry/README.zh.md
@@ -14,7 +14,7 @@
 
 Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemetry 就是禁用该配置项。telemetry 默认上报，只有已经存在的 telemetry 配置项被显式设为 `disabled` 时才关闭：缺少 `cordis.yml`（首次 `create`）、配置项已启用，或 `cordis.yml` 中没有 telemetry 配置项时都会上报。`DO_NOT_TRACK`／CI 始终拒绝。无配置与缺少配置项的默认值可以通过 `ConsentResolver` 配置。
 
-收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）；发布前必须将作为安全兜底的 `.invalid` 占位值替换为真实端点。
+收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）。
 
 ## 模型体验
 
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 5a2f02826c..e6e0fa54c8 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/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/self-modification/README.md
-README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
-README.zh.md: 18e03798b90e73f1d7e61ecf7010b8c472454a08
+README.md: c94f9ac9a79709e418448d9e440c38296e759335
+README.zh.md: 44b5d9ff4cb09fb4a4e44f446894c9925a62ec51
diff --git a/packages/self-modification/README.md b/packages/self-modification/README.md
index 53f700993c..c94f9ac9a7 100644
--- a/packages/self-modification/README.md
+++ b/packages/self-modification/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again — plus the restricted repository Plugin runtime. The group is the landing zone for future self-modification packages. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again — plus the restricted repository Plugin runtime. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
index 18e03798b9..44b5d9ff4c 100644
--- a/packages/self-modification/README.zh.md
+++ b/packages/self-modification/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。该组是未来自我修改类包的落点。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
 
 | 包（package） | 角色 | ctx 键 |
 |---|---|---|
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index c8ec4894b4..503736477c 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -1012,7 +1012,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
-        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: no current consumer defines which directory they would\n * resolve against, so providers fail loud instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: the resolution base is undefined, so providers fail loud\n * instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
       },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index ce1fae24c9..42cf0f2ff2 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
-README.md: dbbb63e9dd18f3c68cc21b84b560403f4a508709
-README.zh.md: 0b183f63ad2f3cfa670babca80d6e4abee6a4bcb
+README.md: 8784f1b2c2a3c9291b761c0a6e68201286b9e306
+README.zh.md: 5b69c054a0e17a49e9c709b27e497b006a024a91
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
index dbbb63e9dd..8784f1b2c2 100644
--- a/packages/session-query/session-query-sqlite/README.md
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -37,7 +37,7 @@ The database is disposable but reset is guarded: every recognized schema version
 
 ## Tokenizer and limits
 
-The index uses FTS5 `unicode61`. In the implementation experiment it supported the two-character query `AI` and produced an index about 2.1× smaller than the trigram alternative. The trade-off is token/phrase recall rather than arbitrary substring recall: `AI` does not match the token `BRAID`. Use `ctx.sessionQuery.filterEvents()` with a `text` clause when a literal whitespace-flexible substring scan is required. NUL is rejected in queries; reserved highlight markers and NUL in documents are normalized before indexing so presentation markers cannot collide with source text.
+The index uses FTS5 `unicode61`. The trade-off is token/phrase recall rather than arbitrary substring recall: `AI` does not match the token `BRAID`. Use `ctx.sessionQuery.filterEvents()` with a `text` clause when a literal whitespace-flexible substring scan is required. NUL is rejected in queries; reserved highlight markers and NUL in documents are normalized before indexing so presentation markers cannot collide with source text.
 
 Abort signals stop queued work and flow unchanged through snapshot listing and non-mutating inspection. Once source work starts, the serialized state machine awaits that backend promise itself—even when a backend ignores cancellation—then checks the signal before starting any further listing, inspection, reconciliation, or query work. The caller therefore observes cancellation only after started backend work is quiescent, and a later search cannot enter the serializer while that cleanup is pending. Node's synchronous `DatabaseSync` API cannot interrupt a metadata or MATCH statement already executing on the JavaScript thread; signals are checked immediately before and after those non-preemptible calls.
 
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index 0b183f63ad..5b69c054a0 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -37,7 +37,7 @@
 
 ## 分词器与限制
 
-该索引使用 FTS5 `unicode61`。在实现实验中，它支持双字符查询 `AI`，产生的索引比 trigram 备选方案小约 2.1 倍。取舍是 token/短语召回而非任意子字符串召回：`AI` 不匹配 token `BRAID`。需要执行字面的空白弹性子字符串扫描时，使用 `ctx.sessionQuery.filterEvents()` 并传入 `text` 子句。查询会拒绝 NUL；文档中的保留高亮标记和 NUL 会在索引前被规范化，使展示标记无法与源文本冲突。
+该索引使用 FTS5 `unicode61`。取舍是 token/短语召回而非任意子字符串召回：`AI` 不匹配 token `BRAID`。需要执行字面的空白弹性子字符串扫描时，使用 `ctx.sessionQuery.filterEvents()` 并传入 `text` 子句。查询会拒绝 NUL；文档中的保留高亮标记和 NUL 会在索引前被规范化，使展示标记无法与源文本冲突。
 
 中止信号会停止已排队工作，并原样流经快照枚举和非修改式检查。来源工作一旦开始，串行化状态机会自行等待该后端 promise，即使后端忽略取消，之后也会在启动任何进一步的枚举、检查、对账或查询工作前检查信号。因此，调用方只会在已启动后端工作完全停稳后观察到取消，而后续搜索在该清理尚未完成时无法进入 serializer。Node 的同步 `DatabaseSync` API 无法中断已在 JavaScript 线程上执行的元数据或 MATCH 语句；系统会在这些不可抢占调用前后立即检查信号。
 
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index 24ed94a3fb..600b8ab80f 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -201,7 +201,6 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect((await ctx.sessionPersistence.list()).map(h => h.id)).not.toContain(m.id)
 
     await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    // now materialized
     expect((await stat(dir)).isDirectory()).toBe(true)
     expect((await stat(rawLogPath(root, '/work', m.id))).isFile()).toBe(true)
     expect((await ctx.sessionPersistence.list()).map(h => h.id)).toContain(m.id)
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index 0f5de36bc2..e55082e190 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/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/session/session-persistence-sqlite/README.md
-README.md: 745c25616e06c391a70b37471917aa9d2539c4dd
-README.zh.md: c86531bcaeca85fa565b537f1fc1beca5d6ac7b3
+README.md: 4ba675447393ffb359ec6983585167b692e84a7d
+README.zh.md: c2578215613ea42fb34e3092f51ec47cbb2fc128
diff --git a/packages/session/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
index 745c25616e..4ba6754473 100644
--- a/packages/session/session-persistence-sqlite/README.md
+++ b/packages/session/session-persistence-sqlite/README.md
@@ -2,12 +2,10 @@
 
 English | [中文](README.zh.md)
 
-A SQLite durable session-persistence backend — a second `SessionPersistence` provider ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), built to validate that the Service Definition and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
+A SQLite durable session-persistence backend — a second `SessionPersistence` provider ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)) satisfying the same contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
 
 `locate(meta)` returns `undefined`: all sessions share one database, so there is no honest independent per-session transcript path.
 
-> **TODO:** this backend talks to `node:sqlite` directly. If a cordis database service (`cordis/db` / a `@cordisjs` SQL driver plugin) is adopted, route through that instead of holding a raw `DatabaseSync` here — the contract surface (`SessionPersistence`) would not change, only the storage driver.
-
 ## Storage model
 
 Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`), a per-materialization incarnation id, and a monotonic per-log revision live in a `sessions` row; `createdAt` is a non-negative safe integer stored in a strict `INTEGER` column. A singleton state row carries the immutable store id. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row).
@@ -61,3 +59,4 @@ SQLite storage does not mutate live request prefixes. A resumed loop can reuse p
 - **Write contention has no wait or retry policy** — the backend sets no busy timeout and retries no locked-database error, so another connection holding a write transaction makes the operation reject immediately.
 - **Only a pristine new database or the current owned `SCHEMA_VERSION` opens** — unversioned schema objects, foreign application identities, and every other schema version are rejected rather than migrated (unreleased software; no persisted user data to preserve).
 - **Nothing deletes stored sessions** — rows accumulate until removed externally (the seam has no deletion surface; `ON DELETE CASCADE` is wired for such out-of-band cleanup).
+- **TODO:** this backend talks to `node:sqlite` directly. If a cordis database service (`cordis/db` / a `@cordisjs` SQL driver plugin) is adopted, route through that instead of holding a raw `DatabaseSync` here — the contract surface (`SessionPersistence`) would not change, only the storage driver.
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index c86531bcae..c257821561 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -2,12 +2,10 @@
 
 [English](README.md) | 中文
 
-SQLite 持久会话存储后端：第二个 `SessionPersistence` 提供方（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证 Service Definition 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
+SQLite 持久会话存储后端：第二个 `SessionPersistence` 提供方（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
 
 `locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实、独立的逐会话 transcript（文本记录）路径。
 
-> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；约定接口（`SessionPersistence`）不会变，只更换存储驱动。
-
 ## 存储模型
 
 每个 `SessionEvent` 1:1 映射到 `events` 表中的一行 `(session_id, seq, type, time, data, source_event_seqs, surface_op)`；`data` 是作为 JSON 文本的事件 payload，因此行结构就是原始事件本身（包括 `assistant/chunk`，保持 `seq` 连续）。两个 `TEXT` 列 `source_event_seqs` 和 `surface_op` 可为空，存储事件可选接口元数据字段（见[会话接口](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)）。日志外元数据（`SessionHeader`）、每实体化 incarnation id 和每日志单调修订位于 `sessions` 行；`createdAt` 是存储在 strict `INTEGER` 列中的非负安全整数。单例状态行携带不可变存储 id。`sessions` 行只由第一次 `append` 写入，其存在性是延迟实体化信号（`list` 精确报告有行的会话）。
@@ -61,3 +59,4 @@ SQLite 存储不修改当前请求前缀。只有重建历史、当前 envelope
 - **写入争用无等待或重试策略**：后端不设置 busy timeout，也不重试 locked-database 错误，因此其他连接持有写事务时操作立即拒绝。
 - **只有 pristine 新数据库或当前自有 `SCHEMA_VERSION` 才能打开**：无版本 schema 对象、外部 application identity 和所有其他 schema 版本被拒绝，而不是迁移（未发布软件，无持久用户数据需要保留）。
 - **不删除已存储会话**：行会累积，直到外部移除（seam 无删除接口；`ON DELETE CASCADE` 已为这种带外清理配置）。
+- **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；约定接口（`SessionPersistence`）不会变，只更换存储驱动。
diff --git a/packages/session/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts
index 5e41763f80..26de5abe73 100644
--- a/packages/session/session-projection-cache/src/spec.ts
+++ b/packages/session/session-projection-cache/src/spec.ts
@@ -61,8 +61,7 @@ export type CheckpointRecord = z.infer<typeof checkpointRecord>
 /**
  * The session-projcache domain spec. Version bumps discard the whole medium
  * (cache semantics: a stale or unreadable cache costs a longer tail replay,
- * never a wrong value). v2 added the record's log-identity binding; v3
- * renamed the row fields to `ver`/`seq`/`val`.
+ * never a wrong value).
  */
 export const projectionCacheDomainSpec = defineDomain({
   name: 'session_projcache',
diff --git a/packages/session/session-telemetry-otel/src/index.ts b/packages/session/session-telemetry-otel/src/index.ts
index 37ba236477..b128f65978 100644
--- a/packages/session/session-telemetry-otel/src/index.ts
+++ b/packages/session/session-telemetry-otel/src/index.ts
@@ -253,11 +253,11 @@ export class TelemetryOtel extends Telemetry {
   // The Service Definition's optional flush() hint is deliberately NOT implemented. The
   // batch processor exports on its own cadence (`processor.scheduledDelayMillis`,
   // the SDK's documented knob), and this backend is the SDK pipeline's only
-  // caller — forwarding the hint to `forceFlush()` was the sole source of
+  // caller — forwarding the hint to `forceFlush()` would be the sole source of
   // concurrent flushes, whose undocumented interactions with shutdown's
   // internal drain (concurrent-flush guard, provider-level flush timeout)
-  // silently dropped tail records. Removal history and the revival trigger:
-  // the revival Agent Note.
+  // silently drop tail records. Rationale and the revival trigger: the
+  // revival Agent Note.
 
   /**
    * Ask the SDK to drain and quiesce, but reject after the backend-owned
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 7606cc3ca6..977527aace 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -111,7 +111,7 @@ export interface TelemetryBackend {
    * leave this unimplemented and let their SDK's own batching cadence govern
    * export timing: a backend that does implement it owns the interaction
    * between its concurrent flushes and {@link shutdown}'s drain (the OTel
-   * backend removed its implementation for exactly that hazard — see the
+   * backend leaves it unimplemented for exactly that hazard — see the
    * revival Agent Note).
    */
   flush?(): void
diff --git a/packages/skill/skill-local/README.i18n.yaml b/packages/skill/skill-local/README.i18n.yaml
index 4dcb4dbc68..fb7d31ce14 100644
--- a/packages/skill/skill-local/README.i18n.yaml
+++ b/packages/skill/skill-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/skill/skill-local/README.md
-README.md: f85cc2e6fd0c32cb88f28a2914a03e22b3a20657
-README.zh.md: 9ee09938737237df9e97e517c1dd44b511b7f596
+README.md: c130c8b525367d7a80e32f0684cd05c931b35944
+README.zh.md: 878725e64413d3e17baf7693ee72b192a23292e6
diff --git a/packages/skill/skill-local/README.md b/packages/skill/skill-local/README.md
index f85cc2e6fd..c130c8b525 100644
--- a/packages/skill/skill-local/README.md
+++ b/packages/skill/skill-local/README.md
@@ -52,7 +52,7 @@ The first-party filesystem `write` and `edit` tools also synchronously invalidat
 
 ## Skill Format
 
-Skills can be single-level directory bundles (`<name>/SKILL.md`) or flat Markdown files (`<name>.md`). Nested `**/SKILL.md` discovery is intentionally not part of v1. Frontmatter is parsed as an open YAML object with the `yaml` package; this provider currently interprets required `name` and `description`, plus optional `whenToUse`, `metadata`, `disable-model-invocation`, and `user-invocable`. Names must be kebab-case.
+Skills can be single-level directory bundles (`<name>/SKILL.md`) or flat Markdown files (`<name>.md`). Nested `**/SKILL.md` discovery is deliberately excluded. Frontmatter is parsed as an open YAML object with the `yaml` package; this provider interprets required `name` and `description`, plus optional `whenToUse`, `metadata`, `disable-model-invocation`, and `user-invocable`. Names must be kebab-case.
 
 The two invocation fields accept YAML booleans and the case-insensitive forms `true`/`false`, `yes`/`no`, `on`/`off`, and `1`/`0`. `disable-model-invocation: true` excludes the skill from model-facing catalogs and loaders; `user-invocable: false` excludes it from human-facing commands. Each omitted field defaults to permitting its surface, and the provider always emits both positive internal policy values, including when both keys are absent. A rejected camel-case spelling or a non-boolean invocation value drops the entire skill from discovery with a warning instead of discarding only that field or falling back to a permissive default. Invocation policy fails closed because ignoring invalid data could expose a skill on a disabled surface; wrong-typed optional `whenToUse` and `metadata` values are omitted because neither currently grants invocation.
 
diff --git a/packages/skill/skill-local/README.zh.md b/packages/skill/skill-local/README.zh.md
index 9ee0993873..878725e644 100644
--- a/packages/skill/skill-local/README.zh.md
+++ b/packages/skill/skill-local/README.zh.md
@@ -52,7 +52,7 @@
 
 ## skill 格式
 
-skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。v1 刻意不支持发现嵌套的 `**/SKILL.md`。Frontmatter 使用 `yaml` 包解析为开放的 YAML 对象；该提供方目前解析必填的 `name` 和 `description`，以及可选的 `whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable`。名称必须使用 kebab-case。
+skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。刻意不支持发现嵌套的 `**/SKILL.md`。Frontmatter 使用 `yaml` 包解析为开放的 YAML 对象；该提供方解析必填的 `name` 和 `description`，以及可选的 `whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable`。名称必须使用 kebab-case。
 
 这两个调用字段接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`。`disable-model-invocation: true` 会从面向模型的目录和 loader 中排除该 skill；`user-invocable: false` 会从面向用户的命令中排除该 skill。每个省略的字段都默认为允许对应接口调用；提供方始终输出两个正向内部策略值，即使两个键都不存在也不例外。若使用驼峰拼写或提供非布尔调用值，系统会记录警告并从发现结果中排除整个 skill，而不是只丢弃该字段或回退到宽松的默认值。调用策略校验遵循失败时默认拒绝原则，因为忽略无效数据可能会在已禁用的接口上暴露 skill；类型错误的可选 `whenToUse` 和 `metadata` 值则会被省略，因为这两个字段目前都不授予调用权限。
 
diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index 5e0fe58855..24d9c35591 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -494,11 +494,11 @@ describe('dsh-tool-skill', () => {
   })
 
   it('resumes from the durable entries of the latest visible catalog', async () => {
-    // Catalog identity moved onto `source.entries` when the catalog became a
-    // `catalog`-form context: the model-facing prose no longer decides whether
-    // a republish is needed, so a seeded message is recognized by its source
-    // alone and malformed prose can no longer hide (or fake) a published
-    // catalog. A foreign-sourced message is not this plugin's catalog at all.
+    // Catalog identity lives on `source.entries`: the model-facing prose does
+    // not decide whether a republish is needed, so a seeded message is
+    // recognized by its source alone and malformed prose cannot hide (or fake)
+    // a published catalog. A foreign-sourced message is not this plugin's
+    // catalog at all.
     const home = await tempDir('tool-catalog-resume')
     const ctx = await setup(home)
     ctx.skills.register({
diff --git a/packages/storage/storage-sqlite/README.i18n.yaml b/packages/storage/storage-sqlite/README.i18n.yaml
index 9a373d4039..2f997b3734 100644
--- a/packages/storage/storage-sqlite/README.i18n.yaml
+++ b/packages/storage/storage-sqlite/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/storage/storage-sqlite/README.md
-README.md: efc1b3ca54181a43c067594cc339ccc3a8fea510
-README.zh.md: bcbccf388cda3955fe6cd6501fd9ffb63e4c2a50
+README.md: 48aae14aa8613886d69652c39194878c190259cf
+README.zh.md: d95da614deb2fe4b6380532aa43836441a0db01c
diff --git a/packages/storage/storage-sqlite/README.md b/packages/storage/storage-sqlite/README.md
index efc1b3ca54..48aae14aa8 100644
--- a/packages/storage/storage-sqlite/README.md
+++ b/packages/storage/storage-sqlite/README.md
@@ -8,7 +8,7 @@ SQLite backend for the [storage hub](../storage/README.md): registers as backend
 
 Document-per-row: each unit table becomes a physical `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)` STRICT table whose `value` is the record's JSON text, so one key updates one row (the reason to route a high-churn domain here instead of the JSON backend). Unit identity lives in two metadata tables — `units` stamps each unit's format version at first open and rejects a differing descriptor with `version-mismatch`; `unit_globals` holds each unit's global singleton row. The physical layout version lives in `PRAGMA user_version`; any other stamped value rejects (unreleased format, no migrations). Unit and table names are validated against the hub's `UNIT_NAME_RE` before they reach DDL, so no external input is ever interpolated into SQL identifiers.
 
-Every write primitive is a single prepared statement — SQLite's per-statement atomicity satisfies the KV contract without explicit transactions, and write ordering stays the caller's responsibility (the domain layer's write chain). Missing directories and database files are created owner-only (`0o700`/`0o600`), matching the session-persistence SQLite backend, whose open sequence this package copies verbatim until the planned media-layer extraction.
+Every write primitive is a single prepared statement — SQLite's per-statement atomicity satisfies the KV contract without explicit transactions, and write ordering stays the caller's responsibility (the domain layer's write chain). Missing directories and database files are created owner-only (`0o700`/`0o600`), matching the session-persistence SQLite backend.
 
 ## Configuration (schemastery)
 
@@ -38,6 +38,6 @@ None — the backend never touches live request prefixes.
 ## Known Limitations and Deferred Work
 
 - **`DatabaseSync` is synchronous** — each write blocks the event loop for its (single-statement) duration; acceptable at domain-data scale.
-- **No busy-wait or retry policy** — another connection holding a write transaction rejects the operation immediately; multi-process write protection is on the design's future-work list.
+- **No busy-wait or retry policy** — another connection holding a write transaction rejects the operation immediately; there is no multi-process write protection.
 - **Only the current `STORAGE_SQLITE_SCHEMA_VERSION` opens** — any other stamped version is rejected rather than migrated (pre-release stance).
 - **`openDatabase` duplicates the session-persistence SQLite open sequence** — extraction into a shared media layer is deferred to the planned session-backend migration (see the Agent Note's reuse audit).
diff --git a/packages/storage/storage-sqlite/README.zh.md b/packages/storage/storage-sqlite/README.zh.md
index bcbccf388c..d95da614de 100644
--- a/packages/storage/storage-sqlite/README.zh.md
+++ b/packages/storage/storage-sqlite/README.zh.md
@@ -8,7 +8,7 @@
 
 每行一个文档：每个单元表都会成为一个物理 STRICT 表 `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)`，其中 `value` 是记录的 JSON 文本，因此一个 key 只更新一行（高频变更领域路由到这里而非 JSON 后端的原因）。单元标识位于两个元数据表中：`units` 在单元首次打开时标记其格式版本，描述符不同时以 `version-mismatch` 拒绝；`unit_globals` 保存每个单元的全局单例行。物理布局版本位于 `PRAGMA user_version`；其他任何标记值都会被拒绝（未发布格式，不迁移）。单元名和表名在进入 DDL 之前依据中心的 `UNIT_NAME_RE` 进行验证，因此不会把外部输入插值到 SQL 标识符中。
 
-每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致；在计划的介质层提取完成前，该包逐字复用了后者的打开顺序。
+每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致。
 
 ## 配置（schemastery）
 
@@ -38,6 +38,6 @@ interface Config {
 ## 已知限制与暂缓事项
 
 - **`DatabaseSync` 是同步的**：每次写入都会在单条语句执行期间阻塞事件循环；在领域数据规模下可以接受。
-- **没有忙等待或重试策略**：另一个连接持有写事务时，该操作会立即被拒绝；多进程写入保护列在设计文档的未来工作清单中。
+- **没有忙等待或重试策略**：另一个连接持有写事务时，该操作会立即被拒绝；没有多进程写入保护。
 - **只打开当前的 `STORAGE_SQLITE_SCHEMA_VERSION`**：其他任何已标记版本都会被拒绝而不是迁移（预发布立场）。
 - **`openDatabase` 重复了 session-persistence SQLite 打开顺序**：提取到共享介质层的工作暂缓至计划的会话后端迁移（见 Agent Note 的复用审计）。
diff --git a/packages/subagent/subagent-acp/README.i18n.yaml b/packages/subagent/subagent-acp/README.i18n.yaml
index f44ae87197..01daa65f77 100644
--- a/packages/subagent/subagent-acp/README.i18n.yaml
+++ b/packages/subagent/subagent-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/subagent/subagent-acp/README.md
-README.md: 4fdd3a09e128d4dc7ec7395d9578803c64a33bc6
-README.zh.md: 7cb1e3d18602ef839e4af316962fc2d10bc67640
+README.md: 33711eb93c38d93472b3b625a86721c1365ac8d9
+README.zh.md: e57010f395e4ebae9b2e909bf63b7ffa1a90afe2
diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md
index 4fdd3a09e1..33711eb93c 100644
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -97,4 +97,4 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **Local workspaces only** — the resolved cwd is a local path handed to a child on the same machine; workspace mapping for a remote ACP agent would need its own backend capability and is not designed here.
 - **No optional start-time capabilities** — this provider cannot apply the local harness's `outputSchema`, depth cap, tool filter, or persona inside the remote process, so it advertises none and the service rejects requests that require them.
 - **Only committed `agent_message_chunk` text is collected** — the automation server keeps reasoning, tool activity, plans, and other trace data in the child session log rather than emitting them on ACP.
-- **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission` in this cut.
+- **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission`.
diff --git a/packages/subagent/subagent-acp/README.zh.md b/packages/subagent/subagent-acp/README.zh.md
index 7cb1e3d186..e57010f395 100644
--- a/packages/subagent/subagent-acp/README.zh.md
+++ b/packages/subagent/subagent-acp/README.zh.md
@@ -97,4 +97,4 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
 - **仅支持本地工作区**：解析后的 cwd 是交给同一台机器上子进程的本地路径；远程 ACP agent 的工作区映射需要独立的后端能力，本包尚未设计。
 - **不支持可选启动时能力**：该提供方无法在远程进程内应用本地 harness 的 `outputSchema`、深度上限、工具过滤器或 persona，因此不会声明这些能力；服务会拒绝需要它们的请求。
 - **只收集已提交的 `agent_message_chunk` 文本**：自动化服务器把推理（reasoning）、工具活动、计划和其他 trace 数据保留在子 agent 会话日志中，不通过 ACP 发出。
-- **权限提示自动回答**（`permission: allow | reject`）：当前版本不会把子 agent 的 `session/request_permission` 呈现给人。
+- **权限提示自动回答**（`permission: allow | reject`）：不会把子 agent 的 `session/request_permission` 呈现给人。
diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts
index fa7c031760..7cc781ca15 100644
--- a/packages/subagent/subagent-acp/src/index.ts
+++ b/packages/subagent/subagent-acp/src/index.ts
@@ -42,7 +42,7 @@ export interface Config {
   /**
    * How to auto-answer the child's `session/request_permission` prompts:
    * `reject` (default — decline every prompt) or `allow` (approve via the first
-   * allow-shaped option). The first cut surfaces no prompt to a human.
+   * allow-shaped option). No prompt is surfaced to a human.
    */
   permission: PermissionPolicy
   /**
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index f3e155e649..17476be41c 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -244,7 +244,7 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
         output.push(acpContentText(update.content))
       }
       // Other updates (thoughts, tool calls, plans) are consumed but not
-      // surfaced in this cut — the subagent returns only its final answer.
+      // surfaced — the subagent returns only its final answer.
       return Promise.resolve()
     },
     requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
index 2f6508a5e0..23450e6e42 100644
--- a/packages/subagent/subagent-claude-code/README.i18n.yaml
+++ b/packages/subagent/subagent-claude-code/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-claude-code/README.md
-README.md: e62f60fceea16749296a91377785b81d94d751ca
-README.zh.md: d83a53ea502db659e575fdac0843f5318cff2fa3
+README.md: 222cf796f71f8dc0dc2c06f7f32bab70ded6ab43
+README.zh.md: 9334820a591cbfcb8dc2046dc3a78201ba193aab
diff --git a/packages/subagent/subagent-claude-code/README.md b/packages/subagent/subagent-claude-code/README.md
index e62f60fcee..222cf796f7 100644
--- a/packages/subagent/subagent-claude-code/README.md
+++ b/packages/subagent/subagent-claude-code/README.md
@@ -8,7 +8,7 @@ This package registers the fixed `claude-code` subagent provider. Each accepted
 
 `start(request)` accepts only a non-empty sequence of text blocks and derives the child cwd from the parent Session. It creates one private `AbortController`, calls the official SDK `query()`, and publishes the run only after the SDK's `spawnClaudeCodeProcess` hook has supplied a live CLI handle owned by [`dsh-subprocess`](../../subprocess/subprocess/README.md). A failure or cancellation before publication closes the query, terminates any acquired process tree, waits for it to exit, and rejects `start()`.
 
-The SDK receives the exact concatenated text task. The provider iterates the complete SDK message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every SDK error subtype, an error-marked success, a missing answer, iterator failure, protocol failure, or process failure maps to `error`; this version produces neither `max-tokens` nor `refusal`.
+The SDK receives the exact concatenated text task. The provider iterates the complete SDK message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every SDK error subtype, an error-marked success, a missing answer, iterator failure, protocol failure, or process failure maps to `error`; the provider produces neither `max-tokens` nor `refusal`.
 
 Local cancellation wins the result race and maps to `aborted`. `dispose()` is idempotent: it aborts the run, asks the SDK query to close, invokes the shared process-tree termination escalation, and waits for whole-tree exit. SDK graceful close expresses protocol intent; the subprocess handle remains the authority for process quiescence. Result failure and independent teardown failure remain separate.
 
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
index d83a53ea50..9334820a59 100644
--- a/packages/subagent/subagent-claude-code/README.zh.md
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -8,7 +8,7 @@
 
 `start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。它会创建一个私有 `AbortController`，调用官方 SDK 的 `query()`，并仅在 SDK 的 `spawnClaudeCodeProcess` 钩子已经提供由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 管理的活动 CLI 句柄后发布此次运行。若在发布前发生失败或取消，它会关闭 query、终止所有已取得的进程树并等待其退出，然后拒绝 `start()` 调用。
 
-SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 消息流，而且只接受满足以下条件的 `result` 消息：其 `subtype: "success"`、`is_error: false` 且 `result` 非空白，之后迭代器还须正常结束。所有 SDK 错误子类型、标记为错误的成功消息、缺失答案、迭代器失败、协议失败或进程失败都映射为 `error`；本版本不会产生 `max-tokens` 或 `refusal`。
+SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 消息流，而且只接受满足以下条件的 `result` 消息：其 `subtype: "success"`、`is_error: false` 且 `result` 非空白，之后迭代器还须正常结束。所有 SDK 错误子类型、标记为错误的成功消息、缺失答案、迭代器失败、协议失败或进程失败都映射为 `error`；该提供方不会产生 `max-tokens` 或 `refusal`。
 
 本地取消会在结果竞态中胜出并映射为 `aborted`。`dispose()` 具有幂等性：它会中止此次运行、请求 SDK query 关闭、调用共享的进程树逐级终止机制，并等待整棵进程树退出。SDK 的优雅关闭只表达协议意图；进程是否完全停稳仍以子进程句柄为准。结果失败与独立的清理失败仍彼此分离。
 
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
index d55f3ab937..cbcdb12584 100644
--- a/packages/subagent/subagent-codex/README.i18n.yaml
+++ b/packages/subagent/subagent-codex/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-codex/README.md
-README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
-README.zh.md: b302b9dd865e7b19d0c74c0d1c342edb660c242a
+README.md: c75a98550894f180d0f37e9cdd135b961488f726
+README.zh.md: 0dd3280b363c1a26250aa00cfeba5398114a2e3e
diff --git a/packages/subagent/subagent-codex/README.md b/packages/subagent/subagent-codex/README.md
index c25ee90edf..c75a985508 100644
--- a/packages/subagent/subagent-codex/README.md
+++ b/packages/subagent/subagent-codex/README.md
@@ -12,7 +12,7 @@ The published `run.result` starts exactly one turn. It accepts only notification
 
 For command and file approvals, the unattended provider selects a non-approval decision offered by the request, preferring `cancel`; the stable 0.146.0 request shape without an offered-decision list falls back to `decline`. It answers permission requests with an empty turn-scoped permission set, answers user-input requests with no answers, and declines MCP elicitation. A request with no legal unattended response, or any unknown server request, fails the run.
 
-Local cancellation wins the result race and maps to `aborted`. A failed turn whose `codexErrorInfo` is `contextWindowExceeded` maps to `max-tokens`; every other remote interrupted or failed turn maps to `error`, and this version produces no `refusal`. `dispose()` is idempotent: it requests a best-effort `turn/interrupt` with both current ids when they are known, closes the JSON-RPC wire, ends stdin, invokes the shared process-tree termination escalation, and waits for whole-tree exit. Result failure and independent teardown failure remain separate.
+Local cancellation wins the result race and maps to `aborted`. A failed turn whose `codexErrorInfo` is `contextWindowExceeded` maps to `max-tokens`; every other remote interrupted or failed turn maps to `error`, and the provider produces no `refusal`. `dispose()` is idempotent: it requests a best-effort `turn/interrupt` with both current ids when they are known, closes the JSON-RPC wire, ends stdin, invokes the shared process-tree termination escalation, and waits for whole-tree exit. Result failure and independent teardown failure remain separate.
 
 ## Capabilities and context
 
@@ -47,7 +47,7 @@ Install this package and add the following rows to your own `cordis.yml`. Shippe
 
 ## Product compatibility and evidence
 
-The production wire intentionally implements only the app-server methods required by this one-shot contract. Development evidence is pinned to `@openai/codex@0.146.0` / `codex-cli 0.146.0`: the keyless real-product spec drives the official binary against a loopback Responses service with a non-empty fake key and proves the task, authentication, exact answer, cancellation, approvals, and process-tree exit. A separate Loader composition e2e boots the README-shaped user configuration with no `codex` command available, verifies the fixed provider and foreground-only tool schema, and records zero child starts. A credentialed e2e starts the production provider and real Codex, then obtains a unique answer from the fixed official DeepSeek service through a loopback-only test bridge from Responses to Chat Completions; that bridge is not production functionality or native Codex support for DeepSeek's Chat Completions API. The npm package is a test-only dependency; deployments still supply `codex` on `PATH`.
+The production wire intentionally implements only the app-server methods required by this one-shot contract. Development evidence is pinned to `@openai/codex@0.146.0` / `codex-cli 0.146.0`; the npm package is a test-only dependency, and deployments still supply `codex` on `PATH`.
 
 ## Model Experience
 
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
index b302b9dd86..0dd3280b36 100644
--- a/packages/subagent/subagent-codex/README.zh.md
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -12,7 +12,7 @@
 
 对于命令与文件审批，无人值守的提供方会从请求给出的决策选项中选择一项不予批准的决策，并优先选择 `cancel`；稳定的 0.146.0 请求形态没有决策选项列表，因此回退到 `decline`。它对权限请求返回作用域限于当前轮次的空权限集，不向用户输入请求提供任何答案，并拒绝 MCP elicitation。若请求在无人值守模式下没有合法响应，或是未知服务器请求，此次运行就会失败。
 
-本地取消会在结果竞态中胜出并映射为 `aborted`。失败轮次的 `codexErrorInfo` 若为 `contextWindowExceeded`，则映射为 `max-tokens`；其他任何远端中断或失败轮次都映射为 `error`，且本版本不会产生 `refusal`。`dispose()` 具有幂等性：如果当前的两个标识符均已知，它会尽力请求 `turn/interrupt`，关闭 JSON-RPC 通信链路，结束标准输入，调用共享的进程树逐级终止机制，并等待整棵进程树退出。结果失败与独立的清理失败仍彼此分离。
+本地取消会在结果竞态中胜出并映射为 `aborted`。失败轮次的 `codexErrorInfo` 若为 `contextWindowExceeded`，则映射为 `max-tokens`；其他任何远端中断或失败轮次都映射为 `error`，且该提供方不会产生 `refusal`。`dispose()` 具有幂等性：如果当前的两个标识符均已知，它会尽力请求 `turn/interrupt`，关闭 JSON-RPC 通信链路，结束标准输入，调用共享的进程树逐级终止机制，并等待整棵进程树退出。结果失败与独立的清理失败仍彼此分离。
 
 ## 能力与上下文
 
@@ -47,7 +47,7 @@
 
 ## 产品兼容性与证据
 
-生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`；该 NPM 包仅作为测试依赖，部署环境仍需通过 `PATH` 提供 `codex`。
 
 ## 模型体验
 
diff --git a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
index a11a5fac86..70002b0e88 100644
--- a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
+++ b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
@@ -106,8 +106,6 @@ describe('dsh-subagent-fork', () => {
   })
 
   it('seeds the child with the parent\'s completed-turn prefix (child inherits context)', async () => {
-    // Parent runs one turn, then we fork. The child's seeded log should contain
-    // the parent's first turn, and the child should run its own new turn on top.
     const { ctx, parent } = await setup([textResponse('parent answer'), textResponse('child answer')])
     parent.followup(createUserMessage({ content: [{ type: 'text', text: 'parent question' }], source: { kind: 'user' } }))
     await parent.whenIdle()
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index 47b6f7f712..8768a002b6 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -80,8 +80,8 @@ export type SubagentListEntry =
      * for any candidate whose log makes a registered unit's fold or schema
      * throw (deterministic data damage, contained per child); `unavailable`
      * when the candidate's persistence inspection failed (retried on the
-     * next listing). `unsupported` is kept for consumers already routing on
-     * it but is no longer produced.
+     * next listing). `unsupported` is never produced; it remains in the
+     * union for consumers that route on it.
      */
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
@@ -439,10 +439,7 @@ const LIFECYCLE_WITNESS_KEYS = [
   'version', 'id', 'createdAt', 'cwd', 'parentSession', 'seedLength', 'delegationDepth',
 ] as const
 
-/**
- * Whether an inspected log still belongs to the enumerated lifecycle,
- * mirroring the retired query-source compatibility check's field set.
- */
+/** Whether an inspected log still belongs to the enumerated lifecycle. */
 function sameLifecycle(meta: SessionHeader, expected: SessionHeader): boolean {
   return LIFECYCLE_WITNESS_KEYS.every(key => meta[key] === expected[key])
 }
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index f83b65f559..b1df485644 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -294,7 +294,7 @@ export interface SubagentProvider {
   /**
    * OPTIONAL (continuable-creation capability): contribute the detached
    * creation inputs that distinguish this provider's continuable children —
-   * today only whether the child session is seeded with parent history. Method
+   * only whether the child session is seeded with parent history. Method
    * presence IS the capability: the service rejects continuable starts on
    * providers without it, while a provider that has it may still serve
    * ordinary one-shot delegations.
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index f0e9a8a597..a9be76e0c0 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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/subprocess/subprocess-local/README.md
-README.md: ed2b4c3558aa034c8d9fa1049c81d6628c86dff7
-README.zh.md: 832a82dc6a12096e85a1b939f5021767a3c5cb68
+README.md: 15fc001b9fcf2eadd7b37415fd92386565b649c3
+README.zh.md: 48b662302183f07d514f975089d4b49bd17c8e69
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index ed2b4c3558..15fc001b9f 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -4,9 +4,9 @@ English | [中文](README.zh.md)
 
 Local Service provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling capability seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
 
-## Behavior (and where it came from)
+## Behavior
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
+- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. 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).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 832a82dc6a..48b6623021 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -4,9 +4,9 @@
 
 [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地 Service provider。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方能力 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
 
-## 行为（以及设计来源）
+## 行为
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
+- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活。
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [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)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 0eaed5620b..081ff436ec 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -108,8 +108,8 @@ export abstract class SubprocessService extends Service {
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
    * plus explicit environment overrides. Relative paths containing separators
-   * are rejected: no current consumer defines which directory they would
-   * resolve against, so providers fail loud instead of guessing.
+   * are rejected: the resolution base is undefined, so providers fail loud
+   * instead of guessing.
    * @param command - absolute executable path or bare PATH name.
    * @param env - explicit environment entries used for lookup.
    * @param signal - aborts remote or local lookup.
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index bf71e04e3e..5898c5beb1 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
-README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 7c1c3328ab8490c7eebd4b2492bc4ae6f4fcd5a5
+README.md: 8a9669b1f555fceb7af6d017d273b62d7dcad1e1
+README.zh.md: efa31df86d3b494ab14fc3742fc84adce570a593
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 0b935ef60c..8a9669b1f5 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -11,7 +11,7 @@ Four layers, importable separately:
 - **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → one canonical `{{cwd}}`, including an already-tokenized macOS `/private` alias; authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)), and `stabilizeFixtureMessageIds` (committed UUIDs carried into unchanged, mutually unique messages by structurally rewriting only complete surface and durable-inbox message ID fields across any recorder's fixture-ready parent/child logs).
 - **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, noncanonical macOS-prefixed cwd tokens, unscrubbed JSONL headers, and malformed pinning headers. Before record or refresh writes fixtures, an unchanged complete message retains its committed UUID only when both its ID and identity-free fingerprint are unique across the scenario's fixture-ready parent/child logs; the session package's authoritative surface-type predicate selects surface carriers, correlated `agent/inbox/spliced` copies join the same mapping, and only validated `id` fields in those carriers are rewritten. New, changed, malformed, and graph-ambiguous messages keep fresh UUIDs. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; complete message IDs in surface or inbox carriers are excluded because the later structural pass owns them, ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
 
-Committed session fixtures use canonical packed rows. An in-flight branch that merges this contract runs the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) with `pnpm run migrate:packed-session-fixtures`; its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns deletion after affected branches converge.
+Committed session fixtures use canonical packed rows; the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older fixture layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
 
 A consuming `*.snapshot.ts` is the scenario table plus one factory call:
 
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 7c1c3328ab..efa31df86d 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -11,7 +11,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每种原生／JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已进行 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新模式写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件构成有序的主会话／子会话清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
-签入仓库的会话 fixture 使用规范打包行。合并此约定的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
+签入仓库的会话 fixture 使用规范打包行；[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写较旧的 fixture 布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
 消费方 `*.snapshot.ts` 就是场景表加一次工厂调用：
 
diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts
index c68be45c00..d37bf289b5 100644
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -760,8 +760,8 @@ async function harvestSessionLogs(root: string): Promise<HarvestedLog[]> {
     })
   }
   // Primary (no parentSession) first, then children by ascending createdAt. A
-  // scenario has exactly one top-level session. In the synchronous cut sibling
-  // children are created strictly sequentially, so their createdAt values are
+  // scenario has exactly one top-level session. Subagent children are created
+  // synchronously and strictly sequentially, so their createdAt values are
   // strictly ordered; the recordedId tiebreak only keeps a degenerate
   // same-millisecond collision (unreachable here) deterministic. This harvest
   // order must match the replay load order in dsh-llm-replay's loadSessionScripts
diff --git a/packages/support/llm-replay/README.i18n.yaml b/packages/support/llm-replay/README.i18n.yaml
index 47650ae4de..6d048c2325 100644
--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/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/support/llm-replay/README.md
-README.md: a6c087778b8e64124590fb6be7a652b58e1b6343
-README.zh.md: 05dcf994962ba37b58cfb18a68f0d3819d34db0a
+README.md: ae7cb5414a28bcf33f9878f6f02220861df9a0d5
+README.zh.md: 2acc0ff8e8c011126452ba3458aaeb0800d9d8f3
diff --git a/packages/support/llm-replay/README.md b/packages/support/llm-replay/README.md
index a6c087778b..ae7cb5414a 100644
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -20,7 +20,7 @@ A scripted string may embed `{{fromRequest:<regex>}}` to fill a value no static
 
 A scenario where a parent agent delegates to in-process subagents records more than one log: the parent (`session.jsonl`) plus one per child (`session.1.jsonl`, …). Each agent runs as its own `Session` on the same context, so replay must serve each one its own script.
 
-Replay keys every call by its calling session id (`GenerateOptions.sessionId`, stamped by the agent loop). Live session ids are freshly random each run and never equal the recorded ones, so a live session binds to a recorded script by **first-call order**: scripts are ordered by header `createdAt` (parent first — it streams before it can delegate), and the first live session to make any call claims the first script, the next new session the next, and so on. Each session then advances its own cursor. A call with no `sessionId` is one anonymous session bound to the primary script, so single-session scenarios behave exactly as before. More distinct live sessions than recorded scripts fails loud.
+Replay keys every call by its calling session id (`GenerateOptions.sessionId`, stamped by the agent loop). Live session ids are freshly random each run and never equal the recorded ones, so a live session binds to a recorded script by **first-call order**: scripts are ordered by header `createdAt` (parent first — it streams before it can delegate), and the first live session to make any call claims the first script, the next new session the next, and so on. Each session then advances its own cursor. A call with no `sessionId` is one anonymous session bound to the primary script. More distinct live sessions than recorded scripts fails loud.
 
 ## Config
 
diff --git a/packages/support/llm-replay/README.zh.md b/packages/support/llm-replay/README.zh.md
index 05dcf99496..2acc0ff8e8 100644
--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -20,7 +20,7 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 
 父 agent 委托给进程内 subagent 的场景会记录多个日志：父会话使用 `session.jsonl`，每个子会话各使用一个日志（`session.1.jsonl` 等）。每个 agent 都在同一上下文中作为独立的 `Session` 运行，因此回放必须为每个 agent 提供各自的脚本。
 
-回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
+回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话。不同实时会话的数量超过已记录脚本数时会明确报错。
 
 ## 配置
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 26b690437c..5bfbe4e5a8 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -49,10 +49,9 @@ declare module 'cordis' {
  */
 export abstract class TaskService extends Service {
   constructor(ctx: Context) {
-    // `abstract` erases at runtime, and this package name used to be the
-    // mountable concrete registry — a stale composition row would otherwise
-    // register a ctx.tasks with no method implementations and fail far from
-    // the misconfiguration. Fail loud at load instead.
+    // `abstract` erases at runtime, so a composition row naming this package
+    // would register a ctx.tasks with no method implementations and fail far
+    // from the misconfiguration. Fail loud at load instead.
     if (new.target === TaskService) {
       throw new Error('@deepseek-ai/dsh-tasks is the abstract task registry seam; load an implementation such as @deepseek-ai/dsh-tasks-local instead')
     }
diff --git a/packages/todo/tool-todo/src/index.ts b/packages/todo/tool-todo/src/index.ts
index 0e403c5510..12e0d164c6 100644
--- a/packages/todo/tool-todo/src/index.ts
+++ b/packages/todo/tool-todo/src/index.ts
@@ -143,7 +143,6 @@ export function apply(ctx: Context, config: Config): void {
         return state
       },
       view: state => state,
-      // Fold semantics changed: turn/start clears the standing plan (was last-write-wins only).
       stateVersion: 2,
     })
   })
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 1950c255cb..de074f3c80 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -772,7 +772,7 @@ const BANNER = [
 ]
 
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.'
 
 /**
  * Render one page's generated `cordis-surface` region: the services mapped to
diff --git a/packages/util/retention/README.i18n.yaml b/packages/util/retention/README.i18n.yaml
index 62be2bd3ea..c8fcb0c274 100644
--- a/packages/util/retention/README.i18n.yaml
+++ b/packages/util/retention/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/util/retention/README.md
-README.md: 45c88e9fc2d8df98f935fd1c3b43c4622802bd2a
-README.zh.md: 9419245908d7331c9db24019f1181fcaed848060
+README.md: 4f4dda8d8a93cd4cdcc4b3c0d2cc575f21159ffb
+README.zh.md: 9ce48c66566dca449cf6c1090f5ef4785e046769
diff --git a/packages/util/retention/README.md b/packages/util/retention/README.md
index 45c88e9fc2..4f4dda8d8a 100644
--- a/packages/util/retention/README.md
+++ b/packages/util/retention/README.md
@@ -23,7 +23,7 @@ import type {
 
 | Export | Role |
 |---|---|
-| `ItemRetainer<T>` | Bounds ordered logical units (paths, grep matches, sources). `head` only in v1. `push()` → `PushDecision`; `finish()` → `RetainedItems<T>`. |
+| `ItemRetainer<T>` | Bounds ordered logical units (paths, grep matches, sources). `head` only. `push()` → `PushDecision`; `finish()` → `RetainedItems<T>`. |
 | `TextRetainer` | Bounds a byte-oriented text stream. `head` / `tail` / `headTail`, UTF-8 boundaries preserved at `finish()`. `push()` → `PushDecision`; `finish()` → `RetainedText`. |
 | `describeOmitted(omitted, unit)` | Standardized omission clause (`exact` prints a count; `unknown` does not). |
 | `formatRetentionNotice(notice, recovery)` | Joins the standardized omission clause with the tool's own recovery guidance. |
diff --git a/packages/util/retention/README.zh.md b/packages/util/retention/README.zh.md
index 9419245908..9ce48c6656 100644
--- a/packages/util/retention/README.zh.md
+++ b/packages/util/retention/README.zh.md
@@ -23,7 +23,7 @@ import type {
 
 | 导出项 | 职责 |
 |---|---|
-| `ItemRetainer<T>` | 限制有序逻辑单元（路径、grep 匹配项、来源）。v1 只支持 `head`。`push()` → `PushDecision`；`finish()` → `RetainedItems<T>`。 |
+| `ItemRetainer<T>` | 限制有序逻辑单元（路径、grep 匹配项、来源）。只支持 `head`。`push()` → `PushDecision`；`finish()` → `RetainedItems<T>`。 |
 | `TextRetainer` | 限制面向字节的文本流。`head` / `tail` / `headTail`，并在 `finish()` 时保留 UTF-8 边界。`push()` → `PushDecision`；`finish()` → `RetainedText`。 |
 | `describeOmitted(omitted, unit)` | 标准化的省略子句（`exact` 输出数量；`unknown` 不输出）。 |
 | `formatRetentionNotice(notice, recovery)` | 将标准化的省略子句与工具自有的恢复指引连接起来。 |
diff --git a/packages/util/retention/src/index.ts b/packages/util/retention/src/index.ts
index 07547a7d93..1aca8b6aaf 100644
--- a/packages/util/retention/src/index.ts
+++ b/packages/util/retention/src/index.ts
@@ -211,8 +211,7 @@ const decoder = new TextDecoder() // utf-8, non-fatal: internal malformed bytes
 function trimTrailingPartialUtf8(bytes: Uint8Array): Uint8Array {
   let i = bytes.length - 1
   // Continuation bytes are 0b10xxxxxx; scan back at most 3 (max sequence is 4).
-  // Indices are bounds-checked by the loop guard, so the reads are in range (a
-  // cast, not `!`, per the repo's no-non-null-assertion rule).
+  // Indices are bounds-checked by the loop guard, so the reads are in range.
   while (i >= 0 && ((bytes[i] as number) & 0xc0) === 0x80 && bytes.length - i <= 3) i--
   if (i < 0) return bytes
   const lead = bytes[i] as number
@@ -228,7 +227,7 @@ function trimTrailingPartialUtf8(bytes: Uint8Array): Uint8Array {
  */
 function trimLeadingContinuationUtf8(bytes: Uint8Array): Uint8Array {
   let i = 0
-  // i < length guards the read; cast rather than `!` (no-non-null-assertion).
+  // i < length guards the read.
   while (i < bytes.length && ((bytes[i] as number) & 0xc0) === 0x80) i++
   return bytes.subarray(i)
 }
diff --git a/packages/util/timeout/README.i18n.yaml b/packages/util/timeout/README.i18n.yaml
index c1ebb419ca..134992bf60 100644
--- a/packages/util/timeout/README.i18n.yaml
+++ b/packages/util/timeout/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/util/timeout/README.md
-README.md: e0d3595e7771fd19c808e89d440e69bca40da286
-README.zh.md: 99b7f281c2af7746fc2a105ee08df870fd3a9583
+README.md: 40a655200780e25c434beed4953d96f46e3604fd
+README.zh.md: 638dc1af60761f9c964e356edc070d20af0f4819
diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md
index e0d3595e77..40a6552007 100644
--- a/packages/util/timeout/README.md
+++ b/packages/util/timeout/README.md
@@ -52,7 +52,7 @@ For a streamed transport, create one `idleWatchdog`, pass its stable `signal` in
 
 ## What does NOT get a timeout
 
-Local file `read`/`write`/`edit` take no `timeoutMs`: a syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. See [`fs/`](../../fs/README.md).
+Local file `read`/`write`/`edit` take no `timeoutMs`: file IO runs untimed because a deadline would kill work the OS will still finish. See [the filesystem subsystem page](../../../docs/subsystems/filesystem.md).
 
 ## Model Experience
 
diff --git a/packages/util/timeout/README.zh.md b/packages/util/timeout/README.zh.md
index 99b7f281c2..638dc1af60 100644
--- a/packages/util/timeout/README.zh.md
+++ b/packages/util/timeout/README.zh.md
@@ -52,7 +52,7 @@ export async function runWithDeadline(upstream: AbortSignal | undefined, timeout
 
 ## 哪些操作不设置超时
 
-本地文件 `read`/`write`/`edit` 不接受 `timeoutMs`：中止系统调用至多只能尽力而为，超时无法强制 `fsync`/`rename` 停止，而添加超时会引入一个违反显式优于隐式原则的隐式默认值。详见 [`fs/`](../../fs/README.md)。
+本地文件 `read`/`write`/`edit` 不接受 `timeoutMs`：文件 IO 不设时限地运行，因为截止时间会中止操作系统仍会完成的工作。详见[文件系统子系统页面](../../../docs/subsystems/filesystem.md)。
 
 ## 模型体验
 
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index 4d5ac9d768..41b7516362 100644
--- a/packages/web/web-search-deepseek/README.i18n.yaml
+++ b/packages/web/web-search-deepseek/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/web/web-search-deepseek/README.md
-README.md: 95340314fe08d0963b899f4a1d704a98f85963a5
-README.zh.md: cf83426f70d6d2a77fd9acf5e927d1b13ec345eb
+README.md: fb9e528633954b8eb9fd0fec8d19e24381a63f12
+README.zh.md: 4e761aa6ef1a67ce17fbc1cabf595af7f24e15e6
diff --git a/packages/web/web-search-deepseek/README.md b/packages/web/web-search-deepseek/README.md
index 95340314fe..fb9e528633 100644
--- a/packages/web/web-search-deepseek/README.md
+++ b/packages/web/web-search-deepseek/README.md
@@ -10,7 +10,7 @@ This is an **implementation** package: it registers a provider into `ctx.web`, r
 
 Exa and Perplexity expose dedicated search endpoints; DeepSeek does not. Instead this provider issues a **full Messages model call** carrying the `web_search` server tool, so one search costs a complete model turn in latency and tokens — heavier than a pure retrieval endpoint. DeepSeek runs the search server-side and returns **structured** `web_search_tool_result` blocks; the provider parses those blocks and **never scrapes URLs out of model prose**.
 
-**Strict mode**: if the response carries no `web_search_tool_result` block (native search did not trigger), the provider throws `WebError` `WEB_PROVIDER_ERROR` rather than degrading to prose-scraping — honest and debuggable.
+**Strict mode**: if the response carries no `web_search_tool_result` block (native search did not trigger), the provider throws `WebError` `WEB_PROVIDER_ERROR` rather than degrading to prose-scraping.
 
 It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not** `$DEEPSEEK_BASE_URL`: the search endpoint is the Anthropic-compatible base (`https://api.deepseek.com/anthropic/v1`), distinct from the chat-completions base (`https://api.deepseek.com`) the LLM adapter uses. A mounted credentials service is authoritative; without one, the provider falls back to the launching process environment. The reference is resolved for each search, so a key stored or rotated by the Web Models page reaches the next call without a restart.
 
diff --git a/packages/web/web-search-deepseek/README.zh.md b/packages/web/web-search-deepseek/README.zh.md
index cf83426f70..4e761aa6ef 100644
--- a/packages/web/web-search-deepseek/README.zh.md
+++ b/packages/web/web-search-deepseek/README.zh.md
@@ -10,7 +10,7 @@
 
 Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方改为发起一次携带 `web_search` 服务器工具的**完整 Messages 模型调用**，因此一次搜索会消耗完整模型轮次的延迟与 token，比纯检索端点更重。DeepSeek 在服务器侧执行搜索，返回**结构化** `web_search_tool_result` 块；提供方解析这些块，**绝不会从模型文本中抓取 URL**。
 
-**严格模式**：如果响应不含 `web_search_tool_result` 块（未触发原生搜索），提供方会抛出 `WebError` `WEB_PROVIDER_ERROR`，而非降级为文本抓取；这种行为诚实且可诊断。
+**严格模式**：如果响应不含 `web_search_tool_result` 块（未触发原生搜索），提供方会抛出 `WebError` `WEB_PROVIDER_ERROR`，而非降级为文本抓取。
 
 它复用 `DEEPSEEK_API_KEY` 凭据引用（不增加密钥），但**不会**复用 `$DEEPSEEK_BASE_URL`：搜索端点使用 Anthropic 兼容基址（`https://api.deepseek.com/anthropic/v1`），不同于大语言模型（LLM）适配器使用的 chat-completions 基址（`https://api.deepseek.com`）。已挂载的凭据服务具有权威性；没有该服务时，提供方会回退到启动进程的环境变量。每次搜索都会解析该引用，因此在 Web 的 Models 页中存储或轮换的密钥无需重启，即可用于下一次调用。
 
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index 6f079335f9..b3f2024458 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
-README.md: 22301a144b2e06ab42e1d503e8f8c554f7886330
-README.zh.md: 027b863cd7835f378de5f5c5d41166938b8cfe1a
+README.md: 2acb5022a83c08c33a26be626a93b7355c07a0ed
+README.zh.md: b77b0a897082dba01e10be3f7b0ca3b3f0260a9f
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index 22301a144b..2acb5022a8 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -14,7 +14,7 @@ This package owns the Service Definition role of the web capability. Unlike bash
 | `@deepseek-ai/dsh-web-fetch-local` | Fetch provider: anonymous public HTTP(S) |
 | `@deepseek-ai/dsh-tool-web` | Consumer: the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
 
-Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The cost is the parallel `Search`/`Fetch` method pairs; that parallelism is intentional, not a missed extraction.
+Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The `Search`/`Fetch` method pairs are deliberately parallel.
 
 ## Service API (`ctx.web`)
 
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index 027b863cd7..b77b0a8970 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -14,7 +14,7 @@
 | `@deepseek-ai/dsh-web-fetch-local` | 抓取提供方：匿名公共 HTTP(S) |
 | `@deepseek-ai/dsh-tool-web` | Consumer：面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
 
-搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。代价是成对的并行 `Search`／`Fetch` 方法；这种并行是有意设计，并非遗漏了可抽取的共性。
+搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。成对的 `Search`／`Fetch` 方法保持并行是有意为之。
 
 ## 服务 API（`ctx.web`）
 
diff --git a/packages/web/web/src/types.ts b/packages/web/web/src/types.ts
index 1216d09848..316b6b5c11 100644
--- a/packages/web/web/src/types.ts
+++ b/packages/web/web/src/types.ts
@@ -26,7 +26,8 @@ export interface WebSearchRequest {
 
 /**
  * Normalized search outcome. `content` is optional provider-generated answer
- * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
  * `sources[]` is the portable citation surface. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
@@ -86,8 +87,8 @@ export interface WebFetchResult {
  * new kind is a coordinated change across known packages, not a plugin
  * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
  * so adding a kind breaks compilation at every consumer until handled. Each arm
- * stays its own object literal even where fields coincide today, leaving room
- * for arm-specific fields later (a `pdf` body's `pageCount`).
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
  */
 export type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml
index 66212b2fb9..219318f8f3 100644
--- a/packages/workflow/tool-workflow/README.i18n.yaml
+++ b/packages/workflow/tool-workflow/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/workflow/tool-workflow/README.md
-README.md: 5afa68764bfe339377954f8912b6f9b795435be1
-README.zh.md: 7f18c6f54332e11ea54a927ef2d7b723c2601c05
+README.md: 4b75ce5b6a248949f135bfe1883680a645a4c774
+README.zh.md: 930da9d0975cd334a7a7cabf59958a9e11106861
diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md
index 5afa68764b..4b75ce5b6a 100644
--- a/packages/workflow/tool-workflow/README.md
+++ b/packages/workflow/tool-workflow/README.md
@@ -10,7 +10,7 @@ Three parameters: `meta` (required identity data: `name`, `description`, and opt
 
 ## Lifecycle
 
-Collection is SYNCHRONOUS this cut (like [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)): `execute` starts a run and awaits `run.result` inside a `try/finally` that always disposes the run, so the script and its children reach quiescence on every path. `exec.signal` is bridged to `run.cancel()` (including the already-aborted-before-start case). A non-`completed` stop reason maps to an `isError` result reporting the reason—never partial output as success; a parse/meta failure thrown synchronously by `start()` becomes an `isError` the model can correct from. Completion returns canonical `{ runId, agentsStarted, result }`; the Native renderer preserves the meta name, agent count, and JSON value, truncating only that projection at `maxResultChars`.
+Collection is synchronous (like [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)): `execute` starts a run and awaits `run.result` inside a `try/finally` that always disposes the run, so the script and its children reach quiescence on every path. `exec.signal` is bridged to `run.cancel()` (including the already-aborted-before-start case). A non-`completed` stop reason maps to an `isError` result reporting the reason—never partial output as success; a parse/meta failure thrown synchronously by `start()` becomes an `isError` the model can correct from. Completion returns canonical `{ runId, agentsStarted, result }`; the Native renderer preserves the meta name, agent count, and JSON value, truncating only that projection at `maxResultChars`.
 
 ## Render intent
 
diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md
index 7f18c6f543..930da9d097 100644
--- a/packages/workflow/tool-workflow/README.zh.md
+++ b/packages/workflow/tool-workflow/README.zh.md
@@ -10,7 +10,7 @@
 
 ## 生命周期
 
-当前版本采用同步收集（类似 [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)）：`execute` 启动运行并等待 `run.result`；这些操作位于 `try/finally` 中，该结构总会 dispose（资源释放）运行，使脚本及其子 agent（智能体）在每条路径上完全停稳。`exec.signal` 会桥接到 `run.cancel()`，包括启动前已经中止的情况。非 `completed` 结束原因会映射为报告原因的 `isError` 结果，绝不会把局部输出当作成功；`start()` 同步抛出的解析/meta 失败会变成模型可据以修正的 `isError`。完成时返回规范值 `{ runId, agentsStarted, result }`；Native 渲染器保留 meta 名称、agent 数量和 JSON 值，只会在 `maxResultChars` 处截断该投影。
+收集是同步的（类似 [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)）：`execute` 启动运行并等待 `run.result`；这些操作位于 `try/finally` 中，该结构总会 dispose（资源释放）运行，使脚本及其子 agent（智能体）在每条路径上完全停稳。`exec.signal` 会桥接到 `run.cancel()`，包括启动前已经中止的情况。非 `completed` 结束原因会映射为报告原因的 `isError` 结果，绝不会把局部输出当作成功；`start()` 同步抛出的解析/meta 失败会变成模型可据以修正的 `isError`。完成时返回规范值 `{ runId, agentsStarted, result }`；Native 渲染器保留 meta 名称、agent 数量和 JSON 值，只会在 `maxResultChars` 处截断该投影。
 
 ## 渲染意图
 
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 7991a7355e..06b115ecee 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -434,7 +434,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['compact-basic'],
     consumers: ['compact-basic'],
-    note: 'The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred.',
+    note: 'The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool.',
   },
   {
     key: 'subagents',
@@ -1117,7 +1117,7 @@ function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): strin
   const maintenance = 'generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program'
   const lines = generatedHeader('Event Producer And Consumer Matrix')
   lines.push(
-    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
+    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. Events are many-to-many, so the dense relation data is presented as a table rather than one large graph. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
     '',
     '| Event | Mode | Declared in | Dispatchers | Listeners |',
     '| --- | --- | --- | --- | --- |',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 1ed6c37f40..942a9ec9e0 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -221,7 +221,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolPwsh)
     },
     note:
-      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\\...` paths and `$env:NAME` variables.',
+      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\\...` paths and `$env:NAME` variables.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-cordis',
diff --git a/scripts/hero-composer-dom-continuity.mjs b/scripts/hero-composer-dom-continuity.mjs
index ef39052b1b..187221f218 100644
--- a/scripts/hero-composer-dom-continuity.mjs
+++ b/scripts/hero-composer-dom-continuity.mjs
@@ -1,4 +1,4 @@
-// Regression drive for the unified hero composer (0729-0357-hero-unify):
+// Regression drive for the unified hero composer:
 // cold start with zero workspaces -> create a workspace -> type. Asserts the
 // composer textarea is the SAME DOM node across the disabled->live flip (a
 // remount drops the __heroMark marker property) — the session-maybe
diff --git a/scripts/translation-brief.ts b/scripts/translation-brief.ts
index 18e1e91e14..9380974fa0 100644
--- a/scripts/translation-brief.ts
+++ b/scripts/translation-brief.ts
@@ -5,10 +5,9 @@
  * changed Markdown units, heading sections, whole document), the terminology
  * rows those changes touch, first-occurrence movement notes, and a digest of
  * the binding update rules. The unit mapping, mechanical code splice, and
- * first-occurrence tracking adopt the planner mechanics validated in the
- * incremental-pipeline work (PR #684). The CLI wrapper is
- * `scripts/gen-translation-brief.ts`; the workflow that consumes the
- * briefing is `.agents/skills/dsh-translate-docs/SKILL.md`.
+ * first-occurrence tracking follow the incremental-pipeline planner mechanics.
+ * The CLI wrapper is `scripts/gen-translation-brief.ts`; the workflow that
+ * consumes the briefing is `.agents/skills/dsh-translate-docs/SKILL.md`.
  */
 
 import type { Nodes } from 'mdast'
diff --git a/scripts/verify-client-domain-graph.ts b/scripts/verify-client-domain-graph.ts
index c1d883d6ef..4349a23d4d 100644
--- a/scripts/verify-client-domain-graph.ts
+++ b/scripts/verify-client-domain-graph.ts
@@ -1,16 +1,16 @@
 /**
  * Enforce intra-package domain layering inside `packages/client/*\/src/client/`.
  * verify-module-graph covers package-level edges; this gate covers the
- * directory level the future package split will land on: domain directories
- * may import `contract/` and never each other, and only the assembly point
- * (`apply.ts` / `index.ts`) may import across domains.
+ * directory level: domain directories may import `contract/` and never each
+ * other, and only the assembly point (`apply.ts` / `index.ts`) may import
+ * across domains.
  *
  * Layer model (lower may not import higher):
  *   0  contract/            shared contract surface (types + slot declarations)
  *   1  <domain>/ + service  domain implementations (skeleton/, chat/, ...)
  *   2  apply.ts, index.ts   assembly point and re-export shell
  *
- * Not yet wired into the gate sequence (loose-gate window); run directly:
+ * Run directly:
  *   pnpm exec tsx scripts/verify-client-domain-graph.ts
  */
 
diff --git a/vitest.config.ts b/vitest.config.ts
index e07ae43ec3..e8bae9560f 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -23,8 +23,8 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       // Bash-requiring suites (a real POSIX shell is unavailable on Windows).
       // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
       // INCLUDED: PowerShell ships with Windows, so they run natively here.
-      // Replacing the old 'packages/bash/*' glob with this explicit list also
-      // newly INCLUDES packages/bash/bash (the Service Definition package) on Windows.
+      // This explicit list (not a 'packages/bash/*' glob) keeps
+      // packages/bash/bash — the Service Definition package — running on Windows.
       'packages/bash/bash-local',
       'packages/bash/bash-sandbox',
       'packages/bash/tool-bash',
@@ -148,9 +148,9 @@ export default defineConfig({
         'packages/*/*/src/worker.ts',
         // A killed executable lint-contract test can leave a non-product source probe behind.
         'packages/*/*/src/oxlint-contract-*.ts',
-        // GUI step-1 skeleton (PR #500): client/web UI files whose remaining
-        // branches need a browser-grade harness the jsdom lane doesn't cover
-        // yet. TODO(gui): cover and remove as the client test lane matures.
+        // Client/web UI files whose remaining branches need a browser-grade
+        // harness the jsdom lane doesn't cover yet. TODO(gui): cover and
+        // remove as the client test lane matures.
         'packages/client/ui-trajectory/src/*',
         // Trajectory's compact Markdown projection retains deferred branch coverage.
         'packages/client/ui-primitives/src/markdown/plain-text.ts',

From ee7458b2dff13daca1c86aa6416aab0443c7aea0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:37:00 +0800
Subject: [PATCH 254/262] =?UTF-8?q?docs:=20fix=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20residual=20ordinals,=20hypothetical=20IPC=20row,=20?=
 =?UTF-8?q?citation-rule=20amendments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Purge the residual task/phase ordinals review caught ((T2), (queue cut 1)
×3, T6, P-I, 'this cut' ×6 including battery-expansion finds in two
untouched notes and a workflow JSDoc); drop the 'externally logged as
Decision 21' parenthetical and rename the remaining bare decision-21
mentions; mark the gui-layering IPC bridge row as a hypothetical example;
restore the GATE_NOTICE doc-typecheck clause and the py-types 'measured'
provenance; say subprocess-backed in filesystem.md; add the picker note
path. Amend the citations note: merged-PR evidence anchors in Agent Notes
are sanctioned, and the candidate gate patterns gain the four shapes the
sweep missed. All nine touched pairs re-recorded.
---
 .../2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml      | 4 ++--
 .../2026-07-19-gui-layering-and-rpc-protocol.md             | 2 +-
 .../2026-07-19-gui-layering-and-rpc-protocol.zh.md          | 2 +-
 ...026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml | 4 ++--
 .../2026-07-25-web-input-machine-and-slash-pipeline.md      | 2 +-
 .../2026-07-25-web-input-machine-and-slash-pipeline.zh.md   | 2 +-
 .../feature/2026-06-21-subagent-capability-seam.i18n.yaml   | 4 ++--
 .../feature/2026-06-21-subagent-capability-seam.md          | 4 ++--
 .../feature/2026-06-21-subagent-capability-seam.zh.md       | 4 ++--
 .../feature/2026-06-22-acp-subagent-backend.i18n.yaml       | 4 ++--
 .../implemented/feature/2026-06-22-acp-subagent-backend.md  | 2 +-
 .../feature/2026-06-22-acp-subagent-backend.zh.md           | 2 +-
 .../feature/2026-07-05-dynamic-workflows.i18n.yaml          | 4 ++--
 .../implemented/feature/2026-07-05-dynamic-workflows.md     | 2 +-
 .../implemented/feature/2026-07-05-dynamic-workflows.zh.md  | 2 +-
 .../2026-08-08-user-explicit-skill-invocation.i18n.yaml     | 4 ++--
 .../feature/2026-08-08-user-explicit-skill-invocation.md    | 6 +++---
 .../feature/2026-08-08-user-explicit-skill-invocation.zh.md | 6 +++---
 .../2026-08-09-committed-artifact-citations.i18n.yaml       | 4 ++--
 .../process/2026-08-09-committed-artifact-citations.md      | 6 +++---
 .../process/2026-08-09-committed-artifact-citations.zh.md   | 6 +++---
 docs/cordis-api/inherited.md                                | 2 +-
 docs/subsystems/filesystem.i18n.yaml                        | 4 ++--
 docs/subsystems/filesystem.md                               | 2 +-
 docs/subsystems/filesystem.zh.md                            | 2 +-
 packages/client/runtime/tests/wire-events.spec.ts           | 2 +-
 .../src/client/skeleton/DetailsPanel.module.css             | 2 +-
 .../client/ui-conversation/src/client/skeleton/InputBar.tsx | 2 +-
 packages/client/ui-conversation/tests/input-matrix.spec.tsx | 2 +-
 .../client/ui-conversation/tests/input-scenarios.spec.tsx   | 2 +-
 packages/client/ui-slash/README.i18n.yaml                   | 4 ++--
 packages/client/ui-slash/README.md                          | 2 +-
 packages/client/ui-slash/README.zh.md                       | 2 +-
 packages/core/tools/src/py-types.ts                         | 4 ++--
 packages/hooks/hooks-claude/src/index.ts                    | 2 +-
 packages/host/directory-picker-native/src/native-picker.ts  | 2 +-
 packages/typert/generator/src/cordis-catalog.ts             | 2 +-
 packages/workflow/workflow/src/index.ts                     | 2 +-
 38 files changed, 58 insertions(+), 58 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index bf20616836..87c65807b8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: f3aea8360ea1db9b29da01f143daf30cd969b0e5
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 27b5401960a31ee3cedf2366d3b7f4efc527d482
+2026-07-19-gui-layering-and-rpc-protocol.md: 7997a682c8745f7b3d0a9721acfa9355603f9b2e
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: cb36b5cb725128e1c5067e5e69e52aa851668e52
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index f3aea8360e..7997a682c8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -218,7 +218,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 | `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
-| IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
+| IPC bridge subclass (hypothetical example — no such shell exists) | an Electron shell | IPC serialization round trip | would swap only doFetch; contract and base class unchanged |
 
 ## How to extend (operational checklists)
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 27b5401960..cb36b5cb72 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -216,7 +216,7 @@ export type ResponseValue<K> =
 | `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
+| IPC 桥子类（假想示例——尚无此形态） | Electron 壳 | IPC 序列化往返 | 只需换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index f670471d90..5b9acd3371 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: 345a08188fc6a4f2b951e8f9cd9d3a5b953a5e34
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: d454003036dd322ec3366c66293120cb2997de8d
+2026-07-25-web-input-machine-and-slash-pipeline.md: 1aca87530d4dcf1709f484cd471d8887c632f55b
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 958b519e7f291033410b932ccca623d87954738d
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
index 345a08188f..1aca87530d 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
@@ -78,7 +78,7 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 
 ### Plain-text references: text outcomes and lexicon decoration
 
-skill/@subagent references skip the placeholder + occurrence identity chain — the plain-text-reference decision (externally logged as Decision 21): a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
+skill/@subagent references skip the placeholder + occurrence identity chain — the plain-text-reference decision: a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
 
 - PickOutcome gains a `{text}` arm; the new scoped bail event `slash/input-insert-text` `{text, span}` (the same contract as the other three: draftRev CAS, returning true ⟺ an actual rewrite); facade.insertText goes through setDraft concatenation — zero machine changes.
 - Sources get an optional `lexicon?(session)` hook: a synchronous hot-snapshot name roster, with `undefined` = data not warm — zero decoration, never triggering a fetch (the render path stays synchronous and side-effect-free); the paired optional `subscribeLexicon?(session, listener)` hook is the invalidation channel for rolls that change after warm (catalog settles, children spawn/exit). The controller aggregates the rolls into its `lexicon` snapshot store (re-polling on each source notification); sources registered after scope birth are warmed and folded in via the service's live-controller broadcast.
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index d454003036..958b519e7f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -78,7 +78,7 @@ occurrence 表与 chip 三投影：
 
 ### 纯文本引用：text outcome 与 lexicon 装饰
 
-skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引用决策（外部记录为决策 21）：pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
+skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引用决策：pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
 
 - PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同约定：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
 - source 可选 `lexicon?(session)` 钩子：同步热快照名录，`undefined` = 数据未热——零装饰、永不触发 fetch（渲染路径保持同步无副作用）；配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化（目录 settle、子代生灭）时的失效通道。controller 把各名录聚合进自己的 `lexicon` snapshot store（每次 source 通知重拉）；scope 出生后才注册的 source 由 service 广播给活 controller，补 warm 并并入名录。
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index cebb95513f..ac2a0bfb37 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 82010b4d11d2de5fc00f892b05e73807530e9cbf
-2026-06-21-subagent-capability-seam.zh.md: dc4e35e9ca6de8790b26bda1aeca30af00db5e1d
+2026-06-21-subagent-capability-seam.md: 72f17d7566aa982a5710e466cb4f740906ef167b
+2026-06-21-subagent-capability-seam.zh.md: 8205a6e2eab3bdaddf25b582c590034e2cf2f8dd
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 82010b4d11..72f17d7566 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -62,7 +62,7 @@ Each in-process subagent runs in its **own `Session`** (own id, `parentSession`
 
 ### Provider selection is config, not model-facing
 
-`dsh-tool-subagent` binds to exactly one provider name (`Config.provider`); the model sees only `{ description, prompt }`. To expose more than one transport, load the tool plugin more than once, each bound to a different provider and a distinct `toolName` (the tool registry rejects a duplicate name). The *service* holds the multi-provider registry; the *tool* picks one — no provider/type parameter in the schema this cut.
+`dsh-tool-subagent` binds to exactly one provider name (`Config.provider`); the model sees only `{ description, prompt }`. To expose more than one transport, load the tool plugin more than once, each bound to a different provider and a distinct `toolName` (the tool registry rejects a duplicate name). The *service* holds the multi-provider registry; the *tool* picks one — the schema carries no provider/type parameter.
 
 ## Testing
 
@@ -72,5 +72,5 @@ Registry and tool tests replace only the nondeterministic child boundary with a
 
 - **Recursion.** Without a bound, an in-process child can see the delegation tool and recurse. The in-process backends implement the optional absolute depth limit and scoped live-global `toolFilter`; ACP advertises both capabilities off and rejects such a request. The [subagent composition-controls Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) owns their exact semantics and security limits.
 - **Blocking the parent turn.** Foreground collection holds the parent's step open for the child's full duration. Background delegation uses the shared `ctx.tasks` runtime and generic `task_*` tools, the same collection mechanism as background bash; the subagent seam itself remains task-agnostic.
-- **Live progress.** This cut surfaces only lifecycle + final result; a per-chunk child→parent update stream is deferred with the background redesign.
+- **Live progress.** Only lifecycle + the final result surface; a per-chunk child→parent update stream is deferred with the background redesign.
 - **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the first cut advertises neither, so the child self-serves in its own process.
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index dc4e35e9ca..8205a6e2ea 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -62,7 +62,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 提供方选择是配置，不面向模型
 
-`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——本版 schema 中没有提供方/type 参数。
+`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——schema 中没有提供方/type 参数。
 
 ## 测试
 
@@ -72,5 +72,5 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 - **递归。** 如果不设限制，进程内子 agent 能看到委派工具并递归调用。进程内后端实现了可选的绝对深度限制和有作用域的实时全局 `toolFilter`；ACP 声明这两项能力为关闭状态，并拒绝此类请求。[subagent 组合控制 Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) 负责定义它们的确切语义和安全边界。
 - **阻塞父轮次。** 前台收集在子 agent 的整个持续时间内保持父 agent 的步骤打开。后台委派使用共享的 `ctx.tasks` 运行时与通用 `task_*` 工具，与后台 bash 共用同一套收集机制；subagent seam 本身仍不感知任务。
-- **实时进度。** 本版仅暴露生命周期事件与最终结果；逐分片的子→父更新流推迟到后台重新设计时一并处理。
+- **实时进度。** 仅暴露生命周期事件与最终结果；逐分片的子→父更新流推迟到后台重新设计时一并处理。
 - **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent（共享工作区模式）是后续工作；首版不声明这两项能力，子 agent 在自己的进程中自行服务。
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index 4cf94795a8..4b601e0f99 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.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 .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
-2026-06-22-acp-subagent-backend.md: 211030a6ecc9b6f673174ba410415c7bd80818ef
-2026-06-22-acp-subagent-backend.zh.md: 2dde3d96329cc47d9c7cca08e1d25764c32f8ebe
+2026-06-22-acp-subagent-backend.md: 41a60bc8e73cbda1d382226acfbd9c0a4b146fa6
+2026-06-22-acp-subagent-backend.zh.md: 6aea991c2b4ab783b5f8c43ecb9529df07269d3f
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
index 211030a6ec..41a60bc8e7 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
@@ -18,7 +18,7 @@ Each `start` spawns a new child, runs exactly one ACP session (`initialize` →
 
 ### Minimal client stub
 
-The client advertises NO optional capabilities (no `fs`, no `terminal`): the child self-serves file/terminal access in its own process. `session/update` notifications are consumed — the backend accumulates `agent_message_chunk` text as the result output and ignores the rest (thoughts, tool-call cards) in this cut, which surfaces only the child's final answer. `session/request_permission` is auto-answered by a configured policy (`reject` declines every prompt, `allow` approves via the first allow-shaped option) — the first cut surfaces no prompt to a human. Proxying `fs`/`terminal` back to the parent (a shared-workspace mode) remains future work, as the seam Agent Note noted.
+The client advertises NO optional capabilities (no `fs`, no `terminal`): the child self-serves file/terminal access in its own process. `session/update` notifications are consumed — the backend accumulates `agent_message_chunk` text as the result output and ignores the rest (thoughts, tool-call cards), so only the child's final answer surfaces. `session/request_permission` is auto-answered by a configured policy (`reject` declines every prompt, `allow` approves via the first allow-shaped option) — no prompt is surfaced to a human. Proxying `fs`/`terminal` back to the parent (a shared-workspace mode) remains future work, as the seam Agent Note noted.
 
 ### No start-time capabilities
 
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index 2dde3d9632..6aea991c2b 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -18,7 +18,7 @@ subagent seam（[seam Agent Note](2026-06-21-subagent-capability-seam.md)）的
 
 ### 最小化客户端桩
 
-客户端不声明任何可选能力（无 `fs`、无 `terminal`）：子 agent 在自己的进程中自行处理文件/终端访问。`session/update` 通知被消费：后端将 `agent_message_chunk` 文本累积为结果输出，在本阶段忽略其余内容（思考、工具调用卡片），仅暴露子 agent 的最终回答。`session/request_permission` 由配置的策略自动应答（`reject` 拒绝所有提示，`allow` 通过第一个表示允许的选项批准）——本阶段不向人类暴露任何权限提示。将 `fs`/`terminal` 代理回父进程（共享工作区模式）仍为后续工作，如 seam Agent Note 所述。
+客户端不声明任何可选能力（无 `fs`、无 `terminal`）：子 agent 在自己的进程中自行处理文件/终端访问。`session/update` 通知被消费：后端将 `agent_message_chunk` 文本累积为结果输出，忽略其余内容（思考、工具调用卡片），因此仅暴露子 agent 的最终回答。`session/request_permission` 由配置的策略自动应答（`reject` 拒绝所有提示，`allow` 通过第一个表示允许的选项批准）——不向人类暴露任何权限提示。将 `fs`/`terminal` 代理回父进程（共享工作区模式）仍为后续工作，如 seam Agent Note 所述。
 
 ### 无启动时能力
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 5c845ed10b..d5ff80bd97 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: 4dc8744f7505aeb84a14dbf5ad0cc8cb5783d234
-2026-07-05-dynamic-workflows.zh.md: 5d3f5b014ff4532050bb0afd5464f7ec5e91a323
+2026-07-05-dynamic-workflows.md: 3e491478286eb77b56872fcbbdd5ebb6b62a5545
+2026-07-05-dynamic-workflows.zh.md: 7888d83f981a96ac5eb31d5ca6f1f8d0b4930ec7
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index 4dc8744f75..3e49147828 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -52,7 +52,7 @@ An output schema makes a schema-valid committed capture mandatory for successful
 
 Worker-side logic runs through an in-process `MessageChannel` so V8 coverage measures it. Unit tests cover script helpers, fatal and nullable failures, JSON boundaries, caps, cancellation, child ownership, and structured output through real loops. A built-bin smoke runs the separately bundled `lib/worker.cjs` under plain Node, a with-key e2e drives real child agents, and model-facing workflow behavior is snapshot-covered through its owning example.
 
-## Deferred (documented non-goals of this cut)
+## Deferred (documented non-goals)
 
 - **Background collection** (start tool → run id → completion notice → collect), designed alongside bash/subagent background unification.
 - **Journaling + resume** (`resumeFromRunId`, cached agent() prefixes) — implementing it reintroduces CC's determinism bans as a script-contract tightening (scripts may read the clock today).
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index 5d3f5b014f..7888d83f98 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -52,7 +52,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够度量它。单元测试覆盖脚本辅助函数、fatal 与 nullable 失败、JSON 边界、上限、取消、子 agent 所有权和通过真实循环的结构化输出。构建后二进制文件的冒烟测试在纯 Node 下运行单独打包的 `lib/worker.cjs`，带密钥的 e2e 驱动真实子 agent，面向模型的工作流行为通过其所属示例进行快照覆盖。
 
-## 延迟（本轮明确的非目标）
+## 延迟（明确的非目标）
 
 - **后台收集**（启动工具 → run id → 完成通知 → 收集），与 bash/subagent 后台统一一起设计。
 - **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本约定收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 963e4b1cae..005b3cad67 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
-2026-08-08-user-explicit-skill-invocation.md: 55001ec2b352bba6f37dd937f64ec8b10853bffb
-2026-08-08-user-explicit-skill-invocation.zh.md: 5e9eb90502a178c4171899247ebac9bec965c89f
+2026-08-08-user-explicit-skill-invocation.md: 74d9f01f191005db6d3d283a3c56f5ee664447f8
+2026-08-08-user-explicit-skill-invocation.zh.md: 0f7c9e1261dda796d988c17ddf7199b74be4133e
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
index 55001ec2b3..74d9f01f19 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-08-user-explicit-skill-invocation.zh.md)
 
 ## Problem
 
-A `disable-model-invocation: true` skill is user-only by design: it never enters the model-facing catalog and the `skill` tool refuses to load it. Its only legitimate entry point is an explicit user gesture — yet the web client had none. `skill.list` filtered to the model-and-user intersection (hiding user-only skills from the menu), an entered `/name` line rode into the default prompt sink as plain text, and the model it reached was forbidden to load the skill — so it degraded to `read`-ing the SKILL.md file or ignoring the gesture (issue #1470). Even for ordinary skills, the decision-21 plain-text reference made user invocation a collaboration cue the model could ignore, not a guarantee.
+A `disable-model-invocation: true` skill is user-only by design: it never enters the model-facing catalog and the `skill` tool refuses to load it. Its only legitimate entry point is an explicit user gesture — yet the web client had none. `skill.list` filtered to the model-and-user intersection (hiding user-only skills from the menu), an entered `/name` line rode into the default prompt sink as plain text, and the model it reached was forbidden to load the skill — so it degraded to `read`-ing the SKILL.md file or ignoring the gesture (issue #1470). Even for ordinary skills, the plain-text reference made user invocation a collaboration cue the model could ignore, not a guarantee.
 
 ## Decision
 
@@ -14,7 +14,7 @@ User-explicit invocation is a host-side pre-step injection, uniform for every us
 
 - `dsh-tool-skill` registers a second `agent/pre-step` listener (beside its catalog listener, the same seam `workspace-instructions` and the runtime-context snapshot ride): it scans the step's claimed messages for whitespace-bounded `/name` tokens — anywhere in the text, the same word-boundary shape the transcript chip decoration uses — collects first-seen-deduplicated names, loads each through `ctx.skills.get`, checks `isUserInvocable` on the loaded definition (the single lookup that produces what is injected), renders it with the shared `renderSkillContent`, and appends the injections after every other injection of the step: background first (workspace rules, runtime policy, catalog), the material the model must act on last, closest to its answer. Registration order pins the placement — the gesture listener registers before the catalog listener, so the waterfall hands it the catalog-bearing list to extend.
 - Precision is closed-set matching, exactly like slash commands: `/goal` resolves against the command registry, `/name` against the workspace's user-invocable skill directory; a miss stays ordinary prose, so nothing is ever guessed. Only `source.kind === 'user'` messages are scanned — external text cannot forge a gesture. Paths (`/usr/bin`), fractions (`5/8`), and prefixed tokens (`foo/name`) all break the boundary.
-- The client stays decision 21: a menu pick lands the literal `/name ` and the prompt ships it verbatim; ui-skill implements no adjudication hooks and no reference codec. `skill.list` (now the domain's only RPC) serves every user-invocable skill with `modelInvocable` so menus mark user-only entries. A name shared with a host command resolves to the command — adjudication claims the line client-side before it becomes a prompt.
+- The client keeps the [plain-text-reference decision](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md): a menu pick lands the literal `/name ` and the prompt ships it verbatim; ui-skill implements no adjudication hooks and no reference codec. `skill.list` (now the domain's only RPC) serves every user-invocable skill with `modelInvocable` so menus mark user-only entries. A name shared with a host command resolves to the command — adjudication claims the line client-side before it becomes a prompt.
 - The injection is a `user`-role message carrying the `skill-invocation` source (`{ name, form: 'instructions' }`), so `user/message` logging, the context-injection transcript row (labelled with the skill name), and replay all come free; `renderSkillContent` lives in the `dsh-skill` seam, shared verbatim with the `skill` tool result, and the catalog's closing sentence tells the model to follow an injected block instead of re-loading it.
 
 Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reasonix — local checkouts) was unanimous that user-explicit triggering is programmatic injection with zero model participation; the final shape is closest to Codex's core-side `$name` mention scanning, which likewise frees every front end from implementing recognition.
@@ -30,7 +30,7 @@ Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reaso
 
 ## Consequences
 
-- Decision 21's plain-text reference is now the whole client story: the draft carries plain text, chip visuals derive from the lexicon, and the sent text is judged by the host boundary — a hand-typed gesture, a menu pick, and a TUI prompt are indistinguishable and equally deterministic.
+- The plain-text reference is now the whole client story: the draft carries plain text, chip visuals derive from the lexicon, and the sent text is judged by the host boundary — a hand-typed gesture, a menu pick, and a TUI prompt are indistinguishable and equally deterministic.
 - Every user-invocable skill invocation costs its full rendered body unconditionally — the price of determinism the peer survey showed everyone pays. Mentioning a known skill name mid-sentence loads it; that is the Codex mention semantic, accepted deliberately.
 - The `skill-invocation` source rides `user/message`, so Model-visible ⟺ logged holds with no new event type, and replay/UI read metadata rather than text markers.
 - Accepted residual of dropping the per-injection preamble: the no-reload framing rides only the catalog, and a workspace whose skills are all user-only never publishes a first catalog — an injection can arrive with no framing at all, and the model may redundantly try the `skill` tool once (the replacement catalog's empty arm carries the sentence; the never-published case does not). Publishing a catalog for framing alone was judged worse than that one recoverable error.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index 5e9eb90502..0f7c9e1261 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`disable-model-invocation: true` 的 skill（技能）在设计上就是仅限用户的：它绝不进入面向模型的目录，`skill` 工具也拒绝加载它。它唯一正当的入口是一次显式的用户手势——而 web 客户端此前没有这个入口。`skill.list` 过滤到模型与用户的交集（把仅限用户的 skill 挡在菜单之外），回车提交的 `/name` 一行以纯文本落入默认提示词 sink，而这行文本到达的模型又被禁止加载该 skill——于是退化为模型去 `read` 那份 SKILL.md 文件，或者干脆无视这次手势（issue #1470）。即使对普通 skill，决策 21 的纯文本引用也让用户调用只是模型可以忽略的协作线索，而不是保证。
+`disable-model-invocation: true` 的 skill（技能）在设计上就是仅限用户的：它绝不进入面向模型的目录，`skill` 工具也拒绝加载它。它唯一正当的入口是一次显式的用户手势——而 web 客户端此前没有这个入口。`skill.list` 过滤到模型与用户的交集（把仅限用户的 skill 挡在菜单之外），回车提交的 `/name` 一行以纯文本落入默认提示词 sink，而这行文本到达的模型又被禁止加载该 skill——于是退化为模型去 `read` 那份 SKILL.md 文件，或者干脆无视这次手势（issue #1470）。即使对普通 skill，纯文本引用也让用户调用只是模型可以忽略的协作线索，而不是保证。
 
 ## 决策
 
@@ -14,7 +14,7 @@ Status: implemented
 
 - `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall（瀑布式事件）会把携带目录的列表交给它来扩展。
 - 精确性来自封闭集合匹配，与斜杠命令完全一致：`/goal` 对照命令注册表解析，`/name` 对照工作区的用户可调用 skill 目录解析；未命中即保持为普通行文，因此绝不猜测。只扫描 `source.kind === 'user'` 的消息——外部文本无法伪造手势。路径（`/usr/bin`）、分数（`5/8`）与带前缀的 token（`foo/name`）都会破坏该边界。
-- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，该文本随提示词原样提交；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——客户端会在该行成为提示词之前完成裁决并将其认领。
+- 客户端沿用[纯文本引用决策](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)：菜单 pick 落下字面文本 `/name `，该文本随提示词原样提交；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——客户端会在该行成为提示词之前完成裁决并将其认领。
 - 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，由注入和 `skill` 工具结果共用，二者内容逐字相同，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
 
 同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）一致表明：用户显式触发都是模型零参与的程序化注入；最终形态最接近 Codex 核心侧的 `$name` mention 扫描——它同样让每一种前端免于自行实现识别。
@@ -30,7 +30,7 @@ Status: implemented
 
 ## 后果
 
-- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同样具有确定性。
+- 纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同样具有确定性。
 - 每一次用户可调用 skill 的调用都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。在句子中间提到一个已知 skill 名称也会加载它；这就是 Codex 的 mention 语义，属于有意接受。
 - `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
 - 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空分支携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 079b448027..022eb6655e 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: a34a779977a05b66b1587049ef4a38f0c1cfa0cb
-2026-08-09-committed-artifact-citations.zh.md: 6eb1810dddfcb38095270d4cdcb00eccef167183
+2026-08-09-committed-artifact-citations.md: 7d99a27238f25e7084fbbc816787c3c76a62bd89
+2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index a34a779977..7d99a27238 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -12,8 +12,8 @@ Large design and review sessions leave working shorthand — decision ordinals,
 
 Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
 
-- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned per the documentation standard; issues are durable and citable.
-- A design-session ordinal with a committed owner is replaced by the owner's name — decision 21 lives in the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) as the plain-text-reference decision. An ordinal without an owner is deleted and its factual clause restated to stand alone.
+- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes may cite merged PRs as evidence anchors — the standard routes change stories to commits, PRs, Agent Notes, and postmortems, and a note is that home.
+- A design-session ordinal whose decision has a committed owner is replaced by the decision's name — the ordinal once logged as "decision 21" is now "the plain-text-reference decision", owned by the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md); the ordinal itself resolves nowhere in-repo and was dropped everywhere. An ordinal without an owner is deleted and its factual clause restated to stand alone.
 - Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
 - Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 ## Alternatives considered
 
 - **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
-- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d` and `\(audit [A-Z]\d`) is the candidate if the pattern recurs.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, and `P-I`) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly those last four shapes, so they lead the candidate list.
 - **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
 
 ## Verification
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index 6eb1810ddd..f09ae024c4 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
 
-- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准仍在禁止之列；issue 是持久且可引用的。
-- 有已提交归属文档的设计会话序号替换为该归属文档的名称：决策 21 即 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的纯文本引用决策。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
+- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析，note 正是这一归宿。
+- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
 - 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
@@ -23,7 +23,7 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
-- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d` 与 `\(audit [A-Z]\d`）。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b` 与 `P-I`）；对本次清扫自身的评审恰好在后四种形态中发现残留，因此它们位居候选清单之首。
 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
 
 ## 验证
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 6af9aec465..8bf23274e5 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -5,7 +5,7 @@
 
 The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
 
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
 
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 91c13a23c5..fac61bde63 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 23ade1ede1592f7c8e1e409f3f9ca30f4f3f7e6f
-filesystem.zh.md: da2ac2583c381a89e0bd656018d799b22da0f1de
+filesystem.md: e0edad514b0c4d9108b18cc0b472600b29024c51
+filesystem.zh.md: 81c2d87b6a96740c7a99449a27c16331f5a0645a
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 23ade1ede1..e0edad514b 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the subprocess-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 ## The service and the plugin
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index da2ac2583c..81c2d87b6a 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## 文件 IO 不设超时
 
-`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的 `timeoutMs` 会成为 seam 无法强制执行的截止时间，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 subprocess 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的 `timeoutMs` 会成为 seam 无法强制执行的截止时间，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
 
 ## 服务与插件
 
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index dfafcd07aa..5b71588732 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Wire-to-typed-event bridge (web input-triggers cut 1): host/commands-changed
+ * Wire-to-typed-event bridge: host/commands-changed
  * → ctx 'commands/changed'; each established connection generation →
  * ctx 'connection/reset' (the forced cache-invalidation broadcast).
  */
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
index abdece3e25..cc5d732e45 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
@@ -1,4 +1,4 @@
-/* Details third column, minimal P-I fill: header (name + close) over a
+/* Details third column, minimal fill: header (name + close) over a
    scrolling body of Input/Output code sections. Panel width/squeeze belongs
    to layout; this fills whatever the column gives. */
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 0c097b6114..304e5f93e7 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -87,7 +87,7 @@ export function InputBar({
   // but its independent Stop below stays available while it runs.
   const continuable = subagent?.address.mode === 'continuable'
   const parentOffline = continuable && !subagent.parentAvailable
-  // Queue cut 1: running input stays free; locked = session removed, the
+  // Running input stays free; locked = session removed, the
   // inert no-workspace state, the machine faces absent (no session), or a
   // parent-offline continuable child. An owner block also disables input;
   // adjudicating and submitting render read-only so the draft stays visible.
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index 1efd959493..dc7bca56d4 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -184,7 +184,7 @@ describe('matrix row: locked (session disabled)', () => {
     expect(shell.snapshot.phase).toBe('plain')
   })
 
-  it('running does NOT lock (queue cut 1): typing and enter-queue stay live', () => {
+  it('running does NOT lock: typing and enter-queue stay live', () => {
     const { textarea, sink } = bench({ running: true })
     expect((textarea).disabled).toBe(false)
     fireEvent.change(textarea, { target: { value: '排队' } })
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index 9f6b679b60..d5a34327f9 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -34,7 +34,7 @@ interface FakeCommand {
   input?: { hint: string }
 }
 
-/** T6 decision-table source over an in-memory directory (menu/space/enter columns for leadingInput + execute). */
+/** Decision-table source over an in-memory directory (menu/space/enter columns for leadingInput + execute). */
 function commandSource(commands: FakeCommand[], execute: (line: string) => Promise<SubmitOutcome>) {
   const resolve = (name: string): FakeCommand | undefined => commands.find(c => c.name === name)
   const leadingClaim = (desc: FakeCommand): CommandClaim => ({
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index 47b4cc670f..daadfbd549 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/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/ui-slash/README.md
-README.md: 739e7ae93e024bdbd602aaff4267cb74406b5698
-README.zh.md: 0e3cd0d4b3cb93e3d602aa0c8f30d4e5afff3af2
+README.md: 3f97351bea04dbc268e6acc105be10e1e4e0a4b5
+README.zh.md: cf9e42d419cb472509a74ba227990b1502b38a75
diff --git a/packages/client/ui-slash/README.md b/packages/client/ui-slash/README.md
index 739e7ae93e..3f97351bea 100644
--- a/packages/client/ui-slash/README.md
+++ b/packages/client/ui-slash/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Input trigger pipeline plugin: `/` and `@` detection under the caret (word-boundary + guard-tier rules), the grouped candidate menu, and pick routing to registered sources. `ctx.slash` owns the source roster and resolves one `SlashController` per session scope (`sessionOf`); the conversation wiring layer drives `track`/`arbitrate`/`onSpace`/`adjudicate` on the controller. The same controller exposes `toggleSource` for a chrome launcher to open exactly one registered source over a synthetic selection span; the resulting candidates still use the ordinary menu, keyboard arbitration, pick callback, and scoped input mutations. Sources receive a `ClientSessionContext` projection per call — sessions are always agent-backed, so the projection is the session identity alone. A source is warmed in every session controller it can reach: the roster present at scope birth warms during controller construction, and a source registered later is warmed into every live controller by the registration itself. Sources whose `lexicon` roll changes after warm implement `subscribeLexicon(session, listener)`; the controller re-polls on each notification and publishes the aggregation through its `lexicon` snapshot store. The pipeline is command-agnostic: space/enter adjudication polls the optional `matchSpace`/`matchEnter` hooks in registration order and the first non-undefined answer wins.
 
-Layering: `src/core/` (T2) is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract; changes require main-thread arbitration.
+Layering: `src/core/` is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract; changes require main-thread arbitration.
 
 MenuView renders the menu store into the `conversation.input.overlay` slot (list kind, session scope) and renders null while closed. Typed triggers seed every source registered for that trigger; a programmatic launcher seeds only its requested source and publishes the source name through the controller's `launcher` snapshot store until the menu closes or typed tracking resumes. Groups sort by the optional `SlashSource.order` (lower first, default 0, ties keep registration order) under title rows localized through the `slash.menu` locale namespace (an unknown source shows its raw name); the list height clamps to the space above the composer, and a pointer down outside both the menu and the surrounding composer card dismisses it. The slot is owned by ui-conversation's composer entry (anchor, children declaration, lifecycle); its SlotMap type merge lives in this package's `src/client/slots.ts` because the dependency direction (ui-conversation → ui-slash) admits no reverse type import. Combobox pattern: focus stays in the textarea, rows pick on mousedown, the highlight rides `aria-activedescendant`.
 
diff --git a/packages/client/ui-slash/README.zh.md b/packages/client/ui-slash/README.zh.md
index 0e3cd0d4b3..cf9e42d419 100644
--- a/packages/client/ui-slash/README.zh.md
+++ b/packages/client/ui-slash/README.zh.md
@@ -4,7 +4,7 @@
 
 输入触发流水线插件：光标处的 `/` 与 `@` 检测（词边界 + guard tier 规则）、分组候选菜单，以及把 pick 路由到已注册 source。`ctx.slash` 拥有 source roster，并按会话 scope（`sessionOf`）各解析一个 `SlashController`；对话接线层在 controller 上驱动 `track`／`arbitrate`／`onSpace`／`adjudicate`。同一个 controller 还暴露 `toggleSource`，供 chrome launcher 在一段合成 selection span 上只打开一个已注册 source；所得候选仍走通常的菜单、键盘仲裁、pick callback 与 scoped 输入改写。source 每次调用收到一个 `ClientSessionContext` 投影——会话始终由 agent（智能体）支撑，因此投影只含会话身份。source 在它能触达的每个会话 controller 中都会被预热：scope 出生时在场的 roster 随 controller 构造预热，晚于此注册的 source 由注册动作本身预热进每个活 controller。`lexicon` 名录在预热后仍会变化的 source 实现 `subscribeLexicon(session, listener)`；controller 每收到通知就重拉，并把聚合结果经其 `lexicon` 快照 store 发布。流水线与命令无关：空格／回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子，第一个非 undefined 的应答胜出。
 
-分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定；变更需经主线程仲裁。
+分层：`src/core/` 是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定；变更需经主线程仲裁。
 
 MenuView 把菜单 store 渲染进 `conversation.input.overlay` slot（列表类，会话 scope），菜单关闭期间渲染 null。键入式 trigger 会 seed 为该 trigger 注册的所有 source；程序化 launcher 只 seed 所请求的 source，并在菜单关闭或重新开始键入式 tracking 前，通过 controller 的 `launcher` 快照 store 发布该 source 名称。分组按可选的 `SlashSource.order` 排序（越小越靠前，默认 0，同值保持注册序），组标题行经 `slash.menu` locale 命名空间本地化（未知 source 显示其原名）；列表高度收敛到 composer 上方的可用空间，指针落在菜单与所在 composer 卡片之外即关闭菜单。该 slot 由 ui-conversation 的组合器条目拥有（锚点、children 声明、生命周期）；其 SlotMap 类型合并放在本包的 `src/client/slots.ts`，因为依赖方向（ui-conversation → ui-slash）不允许反向的类型导入。combobox 模式：焦点始终留在 textarea，行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载。
 
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index ec9b0f2190..e4b241b75f 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -41,8 +41,8 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * that normalize together would collapse into one declaration. Those names
  * take the subscript path, which carries their exact bytes.
  *
- * `IDENTIFIER` is equivalent to `str.isidentifier()` on Node 22.23.1 vs
- * CPython 3.9.6 tables: the equivalence holds inside the two versions' shared
+ * `IDENTIFIER` matches `str.isidentifier()` (measured on Node 22.23.1 vs
+ * CPython 3.9.6 tables): the equivalence holds inside the two versions' shared
  * tables, and the skew characters below are exactly where that pair diverges.
  * The predicate as a whole is deliberately stricter than `isidentifier()`,
  * which does not test NFKC stability: `'field'.isidentifier()` is True and
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index b60ce7b520..30f7a65c51 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -349,7 +349,7 @@ function stopPayload(ctx: Context, agent: Agent): Record<string, unknown> {
  * Build a SubagentStart/SubagentStop payload from the CC base (the child's
  * `session_id`/`cwd` when the child agent is available) plus the subagent-hook
  * fields. `agent_type` is the CC-default {@link SUBAGENT_TYPE}; `stop_hook_active`
- * is present on SubagentStop only (the loop-guard flag, always false this cut).
+ * is present on SubagentStop only (the loop-guard flag, always false).
  */
 function subagentPayload(ctx: Context, event: 'SubagentStart' | 'SubagentStop', info: { id: string }, child: Agent | undefined): Record<string, unknown> {
   return {
diff --git a/packages/host/directory-picker-native/src/native-picker.ts b/packages/host/directory-picker-native/src/native-picker.ts
index 45a62a72e5..a34d75ebf0 100644
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -71,7 +71,7 @@ export async function pickNativeDirectory(
     // per-monitor-v2 DPI and abort support. koffi is a packaged dependency
     // whose availability the install guarantees, so there is no fallback
     // tier: any failure surfaces as-is (no PowerShell fallback tier; see
-    // the simplification Agent Note).
+    // .agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.md).
     const pickDialog = internals.pickWin32Dialog ?? pickWin32Directory
     return await pickDialog(signal)
   }
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index de074f3c80..1950c255cb 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -772,7 +772,7 @@ const BANNER = [
 ]
 
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.'
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
 
 /**
  * Render one page's generated `cordis-surface` region: the services mapped to
diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts
index 794e5023ef..526da15ad8 100644
--- a/packages/workflow/workflow/src/index.ts
+++ b/packages/workflow/workflow/src/index.ts
@@ -126,7 +126,7 @@ export type WorkflowErrorCode =
  * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
  * option or a tripped cap must kill the script loudly), and reserve the
  * per-item `null` for child-run failures and ordinary in-stage script errors.
- * Every {@link WorkflowErrorCode} is fatal in this cut; the flag exists so the
+ * Every {@link WorkflowErrorCode} is fatal; the flag exists so the
  * distinction is explicit at every catch site rather than implied.
  */
 export class WorkflowError extends HarnessError {

From e697bb3ca1039aa724a3aaf6efc76abb44a2411f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:46:21 +0800
Subject: [PATCH 255/262] =?UTF-8?q?docs:=20fix=20re-review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20seat-migration=20obligation,=20evidence=20rule=20mo?=
 =?UTF-8?q?ved=20into=20the=20standard,=20first-cut=20family=20settled?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restore the ReactNode seats' pending-migration obligation the earlier
rewrite had flipped into a permanent exception; state the merged-PR/issue
evidence allowance in docs/AGENTS.md itself so the citations note defers
to the standard instead of overriding it; rewrite the one current-state
'first cut' fact and record the historical-stage-name exemption (with
indexical stamps still banned); pairs re-recorded.
---
 .../feature/2026-06-21-subagent-capability-seam.i18n.yaml     | 4 ++--
 .../feature/2026-06-21-subagent-capability-seam.md            | 2 +-
 .../feature/2026-06-21-subagent-capability-seam.zh.md         | 2 +-
 .../process/2026-08-09-committed-artifact-citations.i18n.yaml | 4 ++--
 .../process/2026-08-09-committed-artifact-citations.md        | 4 ++--
 .../process/2026-08-09-committed-artifact-citations.zh.md     | 4 ++--
 docs/AGENTS.md                                                | 2 +-
 packages/client/AGENTS.md                                     | 2 +-
 8 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index ac2a0bfb37..c68db1d6fd 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 72f17d7566aa982a5710e466cb4f740906ef167b
-2026-06-21-subagent-capability-seam.zh.md: 8205a6e2eab3bdaddf25b582c590034e2cf2f8dd
+2026-06-21-subagent-capability-seam.md: 28ecf985db1289ce4f80570583eac6a051cd2c0b
+2026-06-21-subagent-capability-seam.zh.md: 5f349ddcacebe66c346976b822c9dcc65bda8d18
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 72f17d7566..28ecf985db 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -73,4 +73,4 @@ Registry and tool tests replace only the nondeterministic child boundary with a
 - **Recursion.** Without a bound, an in-process child can see the delegation tool and recurse. The in-process backends implement the optional absolute depth limit and scoped live-global `toolFilter`; ACP advertises both capabilities off and rejects such a request. The [subagent composition-controls Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) owns their exact semantics and security limits.
 - **Blocking the parent turn.** Foreground collection holds the parent's step open for the child's full duration. Background delegation uses the shared `ctx.tasks` runtime and generic `task_*` tools, the same collection mechanism as background bash; the subagent seam itself remains task-agnostic.
 - **Live progress.** Only lifecycle + the final result surface; a per-chunk child→parent update stream is deferred with the background redesign.
-- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the first cut advertises neither, so the child self-serves in its own process.
+- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the backend advertises neither capability, so the child self-serves in its own process.
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 8205a6e2ea..5f349ddcac 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -73,4 +73,4 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 - **递归。** 如果不设限制，进程内子 agent 能看到委派工具并递归调用。进程内后端实现了可选的绝对深度限制和有作用域的实时全局 `toolFilter`；ACP 声明这两项能力为关闭状态，并拒绝此类请求。[subagent 组合控制 Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) 负责定义它们的确切语义和安全边界。
 - **阻塞父轮次。** 前台收集在子 agent 的整个持续时间内保持父 agent 的步骤打开。后台委派使用共享的 `ctx.tasks` 运行时与通用 `task_*` 工具，与后台 bash 共用同一套收集机制；subagent seam 本身仍不感知任务。
 - **实时进度。** 仅暴露生命周期事件与最终结果；逐分片的子→父更新流推迟到后台重新设计时一并处理。
-- **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent（共享工作区模式）是后续工作；首版不声明这两项能力，子 agent 在自己的进程中自行服务。
+- **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent（共享工作区模式）是后续工作；该后端不声明这两项能力，子 agent 在自己的进程中自行服务。
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 022eb6655e..f3a910d338 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 7d99a27238f25e7084fbbc816787c3c76a62bd89
-2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
+2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
+2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 7d99a27238..890555df29 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -12,11 +12,11 @@ Large design and review sessions leave working shorthand — decision ordinals,
 
 Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
 
-- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes may cite merged PRs as evidence anchors — the standard routes change stories to commits, PRs, Agent Notes, and postmortems, and a note is that home.
+- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes and postmortems may cite merged PRs and issues as evidence, per the [documentation standard](../../../../docs/AGENTS.md)'s change-story routing.
 - A design-session ordinal whose decision has a committed owner is replaced by the decision's name — the ordinal once logged as "decision 21" is now "the plain-text-reference decision", owned by the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md); the ordinal itself resolves nowhere in-repo and was dropped everywhere. An ordinal without an owner is deleted and its factual clause restated to stand alone.
 - Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
-- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
+- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
 
 One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index f09ae024c4..7eb446cca8 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -12,11 +12,11 @@ Status: implemented
 
 持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
 
-- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析，note 正是这一归宿。
+- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 与事后分析可依[文档标准](../../../../docs/AGENTS.md)的变更故事归置规则引用已合并的 PR 与 issue 作为证据。
 - 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
-- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性版本戳（「本版」「this cut」）在任何地方都仍被禁止。
 
 一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
 
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index f373fd6469..a8d2a00e9d 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 
 ## Writing rules
 
-- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems.
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the two documentation homes may cite merged PRs and issues as evidence.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index b67428953e..395b8b2cf6 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -23,7 +23,7 @@ How live data reaches render code, and what may cross a business boundary:
 1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
 2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
 3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
-4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are the sanctioned exceptions).
+4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are exceptions pending migration to slots).
 5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
 6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.
 

From 4eecc589408987a053f18e040bcde5f8448b5697 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:55:28 +0800
Subject: [PATCH 256/262] =?UTF-8?q?docs:=20harmonize=20rebase=20compositio?=
 =?UTF-8?q?ns=20=E2=80=94=20hardening=20phrasing,=20=E5=81=9C=E6=94=BE?=
 =?UTF-8?q?=E7=BA=A6=E5=AE=9A=20vocabulary,=20zh=20arm/this=20renderings?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...30-credential-boundaries-and-atomic-registration.i18n.yaml | 4 ++--
 ...026-07-30-credential-boundaries-and-atomic-registration.md | 2 +-
 ...-07-30-credential-boundaries-and-atomic-registration.zh.md | 2 +-
 .../2026-08-07-cancel-convergence-wake-latch.i18n.yaml        | 2 +-
 .../bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md    | 4 ++--
 .../feature/2026-07-30-search-render-card.i18n.yaml           | 2 +-
 .../implemented/feature/2026-07-30-search-render-card.zh.md   | 4 ++--
 .../implemented/feature/2026-07-30-web-result-card.i18n.yaml  | 2 +-
 .../implemented/feature/2026-07-30-web-result-card.zh.md      | 2 +-
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 5955dd282f..124f633137 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: e21b6d0ea5da30b77ab26b750e2294220646a20e
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 6552db1932ca663c6228843cd62b5cc0f3811f24
+2026-07-30-credential-boundaries-and-atomic-registration.md: 4d962a822636bf2c82ecdccb9a1a136945a6e24e
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: cc17e99f434f71be3249bf9006441b4823957f44
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index e21b6d0ea5..4d962a8226 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.md)
 
-> Scope: boundary hardening of the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this note applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
+> Scope: hardening the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this note applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
 
 ## Problem
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 6552db1932..cc17e99f43 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
 
-> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的边界加固——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：它把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
+> 范围：加固[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：它把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
index bcaa655054..831e905801 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
 2026-08-07-cancel-convergence-wake-latch.md: de18dce87e28eaf0548eebd0d054d4ca7b59d0a6
-2026-08-07-cancel-convergence-wake-latch.zh.md: b07edfd94a547ecacc8176df86b58f1f701ec2e4
+2026-08-07-cancel-convergence-wake-latch.zh.md: bb67785512be9cd7b087d9f6c98f165a2a6468a6
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
index b07edfd94a..bb67785512 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 `running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 会抑制该边界）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
 
-`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（`keepInbox` 停放契约）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
+`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（`keepInbox` 停放约定）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
 
 ## 备选方案
 
 **让 `cancel()` 立即把 phase 置为 `idle`。** 不予采用：driver 仍在展开收尾，这会重叠两个 driver。重放逻辑位于旧 driver 的 `finally`，而该 `finally` 此后不再执行——83 个测试中有 14 个失败，多个死锁。修复它需要基于身份的 phase 所有权外加 turn 打开时的 quiescence 屏障，机制上严格更重，而且该屏障就是换了个形态的锁存。
 
-**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反 `keepInbox` 停放契约；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
+**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反 `keepInbox` 停放约定；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
 
 **通过链式 promise（`activityDone.then(...)`）重放。** 不予采用：重放会运行在活动自身结算之外，`whenIdle()` 的循环可能在重放 driver 启动前就 resolve；修复它需要在 send 时同步替换 `activityDone`，并依赖微任务反应顺序——比同步 flag 更脆弱。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index 1d5b00e8e0..c03e545b40 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md
 2026-07-30-search-render-card.md: 585609bd059dbd9aa8283547fa8a4b223f7bdd99
-2026-07-30-search-render-card.zh.md: 2cb28a29f8a1a265310fecb1f0a315d010250e02
+2026-07-30-search-render-card.zh.md: a129b024fcbe067025e9bcd6cfd6aeeb5400347a
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index 2cb28a29f8..a129b024fc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -56,6 +56,6 @@ Status: implemented
 
 ## 相关
 
-- [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
+- [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本变更用 `search` 结果标签扩展的 `card` 标签词汇。
 - [Canonical 工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
-- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
+- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本变更在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index cb45227d19..b6ab8c9f92 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card.md
 2026-07-30-web-result-card.md: 591471d219295019d28b9eeaf2e57f6d2115d380
-2026-07-30-web-result-card.zh.md: a2e0096599a30bcdd1d8a956d8f1c13c1c0622fd
+2026-07-30-web-result-card.zh.md: b84cdc69c132f7764874f14adac92918ba60f86e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index a2e0096599..b84cdc69c1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -41,4 +41,4 @@ Status: implemented
 ## Related
 
 - [标签化的工具调用渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md) —— 本卡片以 `web` 分支扩展的 `card` 标签词汇表。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；[Web result card 前端](2026-07-30-web-result-card-frontend.md)是它在本分支上的对应物。
+- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；[Web result card 前端](2026-07-30-web-result-card-frontend.md)是它在这一支上的对应物。

From dd384f86ab488c568e2c16a2dc987c70a2266c1a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:13:09 +0800
Subject: [PATCH 257/262] docs: bring generated-catalog zh pairs along; raise
 docs/AGENTS.md ceiling to 1335
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Master's bilingual-generated-docs policy pairs the five generated catalogs;
mirror the purge's regenerated English (ConPTY note, hooks TODO wording,
thinking-format and SurfaceOp JSDoc, doc-graphs templates) into their
reviewed zh sides and re-record. Condense the evidence-citation clause and
raise the docs/AGENTS.md ceiling 1320→1335: master's seam-trio definition
and this PR's review-mandated evidence rule land in the same window.
---
 docs/AGENTS.md                         |  2 +-
 docs/capability-seams.i18n.yaml        |  4 ++--
 docs/capability-seams.zh.md            |  2 +-
 docs/config-catalog.i18n.yaml          |  4 ++--
 docs/config-catalog.zh.md              | 16 +++++++---------
 docs/event-producer-consumer.i18n.yaml |  4 ++--
 docs/event-producer-consumer.zh.md     |  2 +-
 docs/persistence-catalog.i18n.yaml     |  4 ++--
 docs/persistence-catalog.zh.md         |  5 +++--
 docs/tool-catalog.i18n.yaml            |  4 ++--
 docs/tool-catalog.zh.md                |  4 ++--
 scripts/doc-budgets.manifest.json      |  2 +-
 12 files changed, 26 insertions(+), 27 deletions(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index a8d2a00e9d..aa9db3dcff 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 
 ## Writing rules
 
-- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the two documentation homes may cite merged PRs and issues as evidence.
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index fb4d773d5c..aa09cb3036 100644
--- a/docs/capability-seams.i18n.yaml
+++ b/docs/capability-seams.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 docs/capability-seams.md
-capability-seams.md: d61353210eedb3de68dd19caa866d4efb9deb19a
-capability-seams.zh.md: 75bf176952a8c06c723e9f7cda535c1ca8b69819
+capability-seams.md: af9f8ba48e67074a485019a4ad9dddd08b2faf81
+capability-seams.zh.md: 7dff963646991d8b1f763ed789109e93cce2ddb8
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
index 75bf176952..7dff963646 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -419,7 +419,7 @@ flowchart LR
 | `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 Code Mode 下消费该服务）。 |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
-| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；面向模型的压缩工具仍处于暂缓状态。 |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn)、[`subagent-fork`](../packages/subagent/subagent-fork)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code)、[`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-subagent-control`](../packages/subagent/tool-subagent-control)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制接口，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa)、[`web-search-perplexity`](../packages/web/web-search-perplexity)、[`web-search-deepseek`](../packages/web/web-search-deepseek)、[`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 12f3e2861c..80ac35ca4e 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 7278447cf85c2b25f7dd42e10e4b0b1cbd7eb96b
-config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
+config-catalog.md: 10f0761fc5aa69852dff06f340f83f5a916975a9
+config-catalog.zh.md: ec0e44e9d39b801a5987f2bdab2584370c1b9333
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index a7d4252c52..ec0e44e9d3 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -413,7 +413,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+来源：[`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-e2b`
 
@@ -515,7 +515,7 @@ export interface Config {
    * Process-level: read once at load, a relative path resolves against the process
    * launch cwd, so one config applies to the whole process.
    * TODO(per-session-hook-config): per-session discovery of a project-local
-   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   * `hooks.json` from each `session/new.cwd`.
    */
   configPath: string
   /**
@@ -550,7 +550,7 @@ export interface Config {
    * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
    * path resolves against the process launch cwd.
    * TODO(per-session-hook-config): per-session project-local discovery from each
-   * `session/new.cwd` is not yet implemented.
+   * `session/new.cwd`.
    */
   configPath: string
   /** The model name stamped on every payload (Codex includes `model` on each event). */
@@ -848,8 +848,7 @@ type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
 
 /**
  * pi-ai thinking formats a profile cannot name: both drive the request through
- * `chatTemplateKwargs`, which this configuration does not expose, so offering
- * them would hand back a format with nothing to say.
+ * `chatTemplateKwargs`, which this configuration does not expose.
  */
 type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 ```
@@ -1691,7 +1690,7 @@ export interface Config {
   /**
    * How to auto-answer the child's `session/request_permission` prompts:
    * `reject` (default — decline every prompt) or `allow` (approve via the first
-   * allow-shaped option). The first cut surfaces no prompt to a human.
+   * allow-shaped option). No prompt is surfaced to a human.
    */
   permission: PermissionPolicy
   /**
@@ -2361,8 +2360,7 @@ export interface Config {
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -2370,7 +2368,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-来源：[`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
+来源：[`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 89e1b03d35..0a3d6007f1 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa
-event-producer-consumer.zh.md: 7eafe5f2880cf9f0e6f2e7eb6c299730926f15ed
+event-producer-consumer.md: 11eecf81a4eccadf2b97026154a78e4ed8a72164
+event-producer-consumer.zh.md: 2db5e596465b4adaf98c1b05692b61de3ced47b9
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 7eafe5f288..2db5e59646 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -5,7 +5,7 @@
 
 [English](event-producer-consumer.md) | 中文
 
-本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。这里特意采用表格而非一张大型关系图：事件之间存在多对多关系，以表格逐行呈现密集的关系数据更便于评审。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。
+本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。事件之间存在多对多关系，因此密集的关系数据以表格而非一张大型关系图呈现。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。
 
 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
 | --- | --- | --- | --- | --- |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index e676227869..e5dd4edde7 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
-persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8
-persistence-catalog.zh.md: d8743a1b0f26f2a4cf50aed42eb68f6c6db1ba13
+persistence-catalog.md: a17cae015eaa107a900069de916dddb216b87ec7
+persistence-catalog.zh.md: 3aef073dedcff0b6addb99d7c287f4e5f372c402
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index d8743a1b0f..3aef073ded 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -37,7 +37,8 @@ export type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 export type SurfaceOp =
   | 'append'
@@ -80,7 +81,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:376`](../packages/core/session/src/types.ts)
 
 ## 事件
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 1ae1b619f3..3e74bbc3e6 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: f6a41da266db6eb2f347fb3c455a67b4dd44c4c0
-tool-catalog.zh.md: b36e8ccf63f4bdde7efca050bd92cbfcb03b3fbb
+tool-catalog.md: 58267e208d919e7fa817991207a44ac0864fa00e
+tool-catalog.zh.md: 1eda3506644bae6da56895c366a56b566536ed62
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index b36e8ccf63..1eda350664 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -21,7 +21,7 @@
 | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
 | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
-| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
 | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence, edit absence, or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
@@ -250,7 +250,7 @@ bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_bac
 
 来源：[`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
 
-pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
+pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index 2626cec2da..575f25b61b 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,6 +1,6 @@
 {
   "AGENTS.md": 1782,
-  "docs/AGENTS.md": 1320,
+  "docs/AGENTS.md": 1335,
   "docs/architecture.md": 2174,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,

From 8053dc38faaa3c92c2cf3c275c64771abcc733a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:48:10 +0800
Subject: [PATCH 258/262] test(snapshot): refresh translation-prompt expected
 output

The assembled request embeds docs/i18n/translation-prompt.md's header and
the bilingual-pairing-gate note as its worked example; the purge edited
both, so the recorded request text follows.
---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 1324d44969..587d59a8bd 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -40,11 +40,11 @@
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — `.zh.md` files would carry an HTML comment recording the English source's blob hash, and translation would flow EN → ZH only. Rejected: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。否决：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",

From eeacdd4790ff71e7c65844dcc435bd6243d0fa3d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 21:01:51 +0800
Subject: [PATCH 259/262] =?UTF-8?q?docs:=20fix=20round-3=20review=20findin?=
 =?UTF-8?q?gs=20=E2=80=94=20=C2=A7/used-to/v1=20residuals,=20zh=20stamp=20?=
 =?UTF-8?q?example,=20budget=20freeze=20honored?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Delete the three §-citation residuals (web-app cordis.patch.yml, two
client design.md §-headers); recast the two CSS used-to narrations and
hmr's four v1 labels as current-state prose; narrow the zh exemption
example to 'this cut' (「本版本」 legitimately renders 'This version');
extend the candidate gate list with the post-battery shapes (§\d with a
committed-owner carve-out, 'used to', bare v1) on both sides and
re-record; honor the over-target ceiling freeze — docs/AGENTS.md
condensed to 1320 and the ceiling restored to 1320.
---
 ...2026-08-09-committed-artifact-citations.i18n.yaml |  4 ++--
 .../2026-08-09-committed-artifact-citations.md       |  2 +-
 .../2026-08-09-committed-artifact-citations.zh.md    |  4 ++--
 docs/AGENTS.md                                       | 12 ++++++------
 packages/bundle/web-app/cordis.patch.yml             |  4 ++--
 packages/client/hmr/src/client/index.ts              |  8 ++++----
 packages/client/runtime/tests/slots-service.spec.ts  |  2 +-
 .../src/client/skeleton/InputBar.module.css          |  6 +++---
 .../ui-models/src/client/ModelsSection.module.css    |  8 ++++----
 packages/client/ui-slots/tests/type-chain.spec.tsx   |  2 +-
 scripts/doc-budgets.manifest.json                    |  2 +-
 11 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index f3a910d338..9c9cb9b476 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
-2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b
+2026-08-09-committed-artifact-citations.md: 31b2d52b423a080579b3ca95cf077859d0bf4c91
+2026-08-09-committed-artifact-citations.zh.md: b69bb8743d10e2d1e194905d6d0de2d3d3667b1d
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 890555df29..31b2d52b42 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 ## Alternatives considered
 
 - **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
-- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, and `P-I`) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly those last four shapes, so they lead the candidate list.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, `P-I`, `used to `, a bare `\bv1\b`, and `§\d` — the last excluding citations whose section numbering has a committed owner, such as web-styling.md's own §N) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly these post-battery shapes, so they lead the candidate list.
 - **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
 
 ## Verification
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index 7eb446cca8..b69bb8743d 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -16,14 +16,14 @@ Status: implemented
 - 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
-- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性版本戳（「本版」「this cut」）在任何地方都仍被禁止。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性切次戳（"this cut"）在任何地方都仍被禁止。
 
 一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
 
 ## 曾考虑的替代方案
 
 - **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
-- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b` 与 `P-I`）；对本次清扫自身的评审恰好在后四种形态中发现残留，因此它们位居候选清单之首。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b`、`P-I`、`used to `、裸 `\bv1\b` 与 `§\d`——最后一种需排除章节编号有已提交归属的引用，如 web-styling.md 自身的 §N）；对本次清扫自身的评审恰好在这些电池之外的形态中发现残留，因此它们位居候选清单之首。
 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
 
 ## 验证
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index aa9db3dcff..04cd0f22f0 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -4,7 +4,7 @@ This file defines document structure, Markdown tiers, writing rules, and `verify
 
 ## Document structure
 
-These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail, describe direct children only by purpose, responsibility, and high-level behavior, and link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
 
 Classify every in-scope document as a tutorial or reference. A tutorial follows an ordered path to an outcome and introduces only what each step needs. A reference defines a lookup scope and describes current behavior without depending on a teaching sequence. Separate substantial tutorial and reference content; use a clear structural boundary when either part is small.
 
@@ -14,7 +14,7 @@ Author in this order: locate the document in the tree; set its permitted detail;
 
 ## The tier taxonomy: one home per fact
 
-Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
+Each fact has one home: the tier whose job it is; elsewhere, link there.
 
 | Tier | Job | Does NOT belong there |
 |---|---|---|
@@ -52,21 +52,21 @@ When the gate goes red:
 
 1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
 2. **Condense** content that belongs here but can be shorter.
-3. **Raise** the ceiling only when the words truly need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
 
 Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the contract still has room, and raise it when content would otherwise be deleted. Targets: root `AGENTS.md` ≤ 1,600 words; `architecture.md` ≤ 1,800; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 650 and this file ≤ 1,250; `packages/README.md` ≤ 600. Review governs unbudgeted tiers.
 
 ## The slop checklist
 
-Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill runs this list as an audit:
+Hunt these in any doc; [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) runs this list as an audit:
 
-- The same rule stated in more than one home. Grep a distinctive phrase; keep one home, convert the rest to links.
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
 - Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
 - Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
 - Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
 - Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
 - Rationale repeated beside sibling methods instead of once at the owning capability or helper.
-- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it, or demote the detail to the linked home.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
 - Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
 - Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index d4fb2e8511..c3a66ebbf4 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -105,8 +105,8 @@
 
     # 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).
+    # module table the shell kernel constructs before cordis exists (adopted
+    # as a plugin entry by the kernel, never fetched).
     - id: modules
       name: '@deepseek-ai/dsh-client-modules'
 
diff --git a/packages/client/hmr/src/client/index.ts b/packages/client/hmr/src/client/index.ts
index 99f0938555..d0558bcecc 100644
--- a/packages/client/hmr/src/client/index.ts
+++ b/packages/client/hmr/src/client/index.ts
@@ -30,7 +30,7 @@
  * Failure window: if prefetch rejects after invalidate, the module is left
  * unregistered while the OLD fiber keeps running untouched (teardown never
  * started) — degraded but recoverable, the next rebuilt frame retries from
- * scratch. Consistent with the v1 no-rollback policy below. Known dev-only
+ * scratch. Consistent with the no-rollback policy below. Known dev-only
  * race: a rebuilt frame overlapping a still-in-flight boot arrival shares
  * that arrival's task and may materialize the pre-rebuild bytes; the next
  * rebuilt frame self-heals.
@@ -57,7 +57,7 @@
  * apply opens a fresh channel. Frames arriving during the gap are lost —
  * acceptable for the dev channel, the next rebuild renotifies.
  *
- * Failure policy (v1): no rollback. An import failure leaves the entry
+ * Failure policy: no rollback. An import failure leaves the entry
  * fiberless (the next rebuilt frame retries from scratch); an apply failure
  * leaves a FAILED fiber for the shell's status projection. Both log loudly.
  */
@@ -135,7 +135,7 @@ export function apply(ctx: Context): void {
     // re-plugins under the entry context. Import failures are logged by
     // Entry._init and leave the entry fiberless (retryable).
     await entry.refresh()
-    // Surface apply failures loudly (v1: no rollback, FAILED state stays).
+    // Surface apply failures loudly (no rollback, FAILED state stays).
     await entry.fiber?.await()
   }
 
@@ -151,7 +151,7 @@ export function apply(ctx: Context): void {
         })
         break
       case 'graph':
-        // Connect-time snapshot, unused in v1. The loader's cached graph rev
+        // Connect-time snapshot, unused. The loader's cached graph rev
         // goes stale after rebuilds — harmless, since prefetch hits the
         // network anyway (host serves bundles no-cache); graph rev refresh
         // lands with the reconnect-handshake mechanism.
diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts
index 0b8ce8a301..a796d324ee 100644
--- a/packages/client/runtime/tests/slots-service.spec.ts
+++ b/packages/client/runtime/tests/slots-service.spec.ts
@@ -1,5 +1,5 @@
 /**
- * SlotsService terminal-design account (design.md §11-3 main landing):
+ * SlotsService terminal-design account:
  * built-in 'root', the three load-time throws (duplicate declaration /
  * undeclared contribution / cross-scope store handle), the renderer installation
  * contract (double install / not installed / non-root key), store instance
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index fdbf28c74b..26f3532426 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -225,9 +225,9 @@
      so by construction now that all three sit INSIDE .scroll — a scrollbar
      that consumes layout space narrows the scrollport, which is their shared
      containing block, so it costs all three the same width on every engine.
-     Scrolling the textarea itself is what used to break this, and no property
-     fixed it: WebKit reserved gutter space for the overflow-y:auto textarea
-     and not for the overflow:hidden layers beside it, leaving them 8px apart
+     A textarea that scrolls itself would break this, and no property fixes
+     it: WebKit reserves gutter space for an overflow-y:auto textarea and not
+     for the overflow:hidden layers beside it, leaving them 8px apart
      (768 against 776) — worth 2 to 5 wrapped lines on a long draft. */
 }
 
diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css
index 8facc3a110..5203524517 100644
--- a/packages/client/ui-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-models/src/client/ModelsSection.module.css
@@ -3,10 +3,10 @@
  * 32px fields, and `border-l2` hairlines — the vocabulary GeneralSection and
  * the Button/Input primitives already use.
  *
- * Every color resolves through a `--dsw-alias-*` token. The section used to
- * name `--border` / `--surface` / `--text-*`, which nothing in this app
- * defines, so it always rendered the light-mode literals written as their
- * fallbacks and stayed light under the dark theme. */
+ * Every color resolves through a `--dsw-alias-*` token. Bare `--border` /
+ * `--surface` / `--text-*` names, which nothing in this app defines, would
+ * render the light-mode literals written as their fallbacks and stay light
+ * under the dark theme. */
 
 .section {
   display: flex;
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
index 64277edccc..a65f56a508 100644
--- a/packages/client/ui-slots/tests/type-chain.spec.tsx
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -1,4 +1,4 @@
-// Terminal-design compile-time samples (design.md §11 item 2): the four-share
+// Terminal-design compile-time samples: the four-share
 // composed register constraint — children spec x SlotMap alignment, renderSlot
 // key-set containment, store share matching, inject face completeness — plus
 // the full positive chain. Bodies with @ts-expect-error sites never run.
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index 575f25b61b..2626cec2da 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,6 +1,6 @@
 {
   "AGENTS.md": 1782,
-  "docs/AGENTS.md": 1335,
+  "docs/AGENTS.md": 1320,
   "docs/architecture.md": 2174,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,

From 54b898463c0a8dd0be22bf54aa94be8848c4492f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 21:20:18 +0800
Subject: [PATCH 260/262] fix(rebase): drop transcript-adapter files
 resurrected over master's deletion

Master's conversation-node engine deleted transcript-adapter.ts and its
spec; the rebase's modify/delete conflicts were staged as keep-ours,
resurrecting both with a stale dsh-compact import. Remove them; the
purge edits they carried died with the files upstream.
---
 .../src/client/sessions/transcript-adapter.ts | 408 -------------
 .../runtime/tests/transcript-adapter.spec.ts  | 567 ------------------
 2 files changed, 975 deletions(-)
 delete mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts
 delete mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts

diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
deleted file mode 100644
index ce12d3a89c..0000000000
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ /dev/null
@@ -1,408 +0,0 @@
-// TranscriptAdapter: the human transcript projected from the raw event window
-// in LOG order. The model-visible surface deliberately shadows replaced ranges,
-// so it is the wrong source for conversation a reader already saw; this adapter
-// keeps every append-origin event at its own log position and contributes one
-// marker node per landed compaction checkpoint. Node order is therefore
-// seq-monotonic by construction.
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-// Subpath export (package.json exports "./surface"): all value imports
-// go through it — the package root points at lib/index.js (needs a build) which the vite
-// browser bundle cannot resolve; surface.ts has no Node dependencies.
-import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
-import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
-// declaration of the checkpoint source, reachable as a TYPE from this program.
-// The package ROOT is not — it reaches dsh-session's root, whose Context merge
-// declares the HOST `sessions: SessionStore` against this program's
-// `sessions: ISessions` (TS2717, the one-program-per-side rule in
-// docs/development.md).
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
-import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
-import { toAssistantBlocks } from './conversation.ts'
-import { contextForm, contextProvenance } from './context-provenance.ts'
-import { SteeringHistory } from './steering-history.ts'
-import type { AssistantStepMetadata } from './assistant-timing.ts'
-import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
-
-/**
- * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
- * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
- * import stays type-only because a value import would fail the client purity
- * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
- * forbidden in a browser bundle — while an erased type never reaches it.
- */
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
-
-/** In-window tool/call index entry used to materialize result cards. */
-interface CallIndexEntry {
-  name: string
-  argsRaw: string
-  turn: number
-  step: number
-  /** Unix epoch ms of the tool/call event. */
-  time: number
-  /** Wire view riding the tool/call (envelope-level; never inside the event). */
-  callView: ToolCallView | null
-}
-
-/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
-function materializeNode(
-  event: SessionEvent,
-  callIndex: ReadonlyMap<string, CallIndexEntry>,
-  resultView: ToolResultView | null,
-  steering: boolean,
-  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
-): ConversationNode {
-  switch (event.type) {
-    case 'user/message': {
-      // Injected context (plugin/goal/skill-invocation source) folds to a
-      // context node, not a user message; only a direct human prompt is a
-      // user node. A compaction checkpoint never reaches here
-      // (isCompactCheckpoint routes it away).
-      if (event.data.source.kind !== 'user') {
-        return {
-          kind: 'context', seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-          provenance: contextProvenance(event.data.source),
-          form: contextForm(event.data.source),
-        }
-      }
-      if (steering) {
-        return {
-          kind: 'steering', messageId: event.data.id,
-          seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-        }
-      }
-      return {
-        kind: 'user', seq: event.seq, time: event.time,
-        content: event.data.content, source: event.data.source,
-      }
-    }
-    case 'assistant/message':
-      return {
-        kind: 'assistant', seq: event.seq, time: event.time,
-        turn: event.data.turn, step: event.data.step,
-        blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
-        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
-      }
-    case 'tool/result': {
-      const result = event.data.message.content[0]
-      const callId = String(event.data.message.source.callId)
-      const call = callIndex.get(callId)
-      return {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId,
-        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
-        callTime: call?.time ?? null,
-        content: result.content, isError: result.isError === true,
-        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
-        meta: event.data.meta,
-        callView: call?.callView ?? null,
-        resultView,
-        subCalls: [],
-      }
-    }
-    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
-    can be append-origin, and each has a case above; reachable only if core
-    adds an eligible type. */
-    default:
-      return {
-        kind: 'unknown', seq: event.seq, time: event.time,
-        type: event.type, data: (event as { data?: unknown }).data,
-      }
-  }
-}
-
-/**
- * Whether an event is a landed compaction checkpoint — all three conditions,
- * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
- * compaction seam's checkpoint plugin source, that REPLACED a surface range. A
- * plugin-sourced `user/message` that appends is injected context (a
- * session-reference card), not a compaction; a replacement `tool/result` is an
- * in-place prune and a replacement `assistant/message` a generic rewrite, and
- * both mark no boundary in the conversation.
- * @param event - the raw window event.
- * @returns true when the event compacted a surface range.
- */
-function isCompactCheckpoint(event: SessionEvent): boolean {
-  if (event.type !== 'user/message') return false
-  const source = event.data.source
-  return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN
-    && isReplacementSurfaceEvent(event)
-}
-
-/** Whether an event contributes a node to the human transcript. */
-function isTranscriptEvent(event: SessionEvent): boolean {
-  return isAppendSurfaceEvent(event) || isCompactCheckpoint(event)
-}
-
-/**
- * Concatenated text of a `compact/summary` payload, or null when it carries no
- * usable text. The payload is a `ContentBlock[]` whose union is
- * merge-extensible, so a non-text block is skipped rather than discarding the
- * text beside it; a payload with no text block at all falls to null through the
- * empty check.
- */
-function compactSummaryText(event: SessionEvent): string | null {
-  const summary = (event.data as unknown as { summary?: unknown }).summary
-  if (!Array.isArray(summary)) return null
-  let text = ''
-  for (const block of summary as readonly unknown[]) {
-    const candidate = block as { type?: unknown; text?: unknown }
-    if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue
-    text += candidate.text
-  }
-  return text.trim() === '' ? null : text
-}
-
-interface CompactSummaryDetails {
-  readonly summary: string | null
-  readonly shadowedItemCount: number | null
-  readonly shadowedTokenCount: number | null
-}
-
-/** Recover human-facing summary material from one structurally narrowed wire event. */
-function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
-  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
-  const shadowedSeqs = data.shadowedSeqs
-  const tokenCount = data.shadowedTokenCount
-  return {
-    summary: compactSummaryText(event),
-    shadowedItemCount: Array.isArray(shadowedSeqs)
-      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
-      ? shadowedSeqs.length
-      : null,
-    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
-      ? tokenCount as number
-      : null,
-  }
-}
-
-/**
- * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
- * `compact/summary` event), never from the framed checkpoint payload, which is
- * an instruction envelope written for the model. A window cut that left the
- * summary event outside soft-falls to `summary: null` (a non-expandable marker),
- * the same posture as a call-less tool result.
- */
-function materializeCompaction(
-  checkpoint: SessionEvent,
-  eventIndex: ReadonlyMap<number, SessionEvent>,
-): CompactionSummaryNode {
-  const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
-  let summary: string | null = null
-  let summaryEventSeq: number | null = null
-  let shadowedItemCount: number | null = null
-  let shadowedTokenCount: number | null = null
-  for (const seq of sources ?? []) {
-    const candidate = eventIndex.get(seq)
-    if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
-    const details = compactSummaryDetails(candidate)
-    summary = details.summary
-    summaryEventSeq = candidate.seq
-    shadowedItemCount = details.shadowedItemCount
-    shadowedTokenCount = details.shadowedTokenCount
-    break
-  }
-  return {
-    kind: 'compaction',
-    seq: checkpoint.seq,
-    time: checkpoint.time,
-    summary,
-    summaryEventSeq,
-    shadowedItemCount,
-    shadowedTokenCount,
-  }
-}
-
-/** Log-ordered human transcript over a paged raw event window (never consults surface order). */
-export class TranscriptAdapter {
-  /** Window events by seq, used to find the summary event cited by a checkpoint. */
-  private eventIndex = new Map<number, SessionEvent>()
-  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
-  private projected: ConversationNode[] = []
-  private callIdx = new Map<string, CallIndexEntry>()
-  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
-  private stepTimings = new Map<string, AssistantStepMetadata>()
-  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
-  private resultViews = new Map<number, ToolResultView>()
-  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
-  private readonly steeringHistory = new SteeringHistory()
-  /**
-   * Command lifecycle nodes by commandId (insertion = run order). The
-   * `command/run`/`command/done` pair is log-only, so it is not a surface
-   * event and never joins the transcript projection; this index folds the pair
-   * (done settles its run's node in place) and nodes() merges the products in
-   * by seq. Window cuts soft-fall like tool pairs: a done with no in-window
-   * run still builds a node.
-   */
-  private commandIdx = new Map<string, CommandNode>()
-  /** Projection revision, bumped only when a transcript node or a command node actually
-   *  changed, keying the nodes() result cache: an unchanged projection returns the previous
-   *  ARRAY reference, not just cached elements — the snapshot's reference-stability contract
-   *  starts here, and a chunk storm bumps nothing at all. */
-  private rev = 0
-  private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null
-
-  /**
-   * Window rebuild (after open/resync/page prepend): re-index the raw window
-   * and re-project the transcript.
-   * @param events - the new window contents (seq-ascending).
-   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
-   */
-  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
-    this.rev++
-    this.eventIndex = new Map()
-    this.callIdx = new Map()
-    this.resultViews.clear()
-    this.commandIdx = new Map()
-    this.steeringHistory.reset()
-    const steeringSeqs = new Set<number>()
-    this.stepTimings = new Map()
-    for (let i = 0; i < events.length; i++) {
-      const event = events[i]
-      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
-      if (event === undefined) continue
-      this.eventIndex.set(event.seq, event)
-      this.indexCall(event, views?.[i])
-      this.indexCommand(event)
-      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
-      indexAssistantStepTiming(this.stepTimings, event)
-    }
-    // Indexes first, then project: a tool/result materializes against the
-    // complete call index, and a checkpoint against the complete event index.
-    const projected: ConversationNode[] = []
-    for (const event of events) {
-      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
-    }
-    this.projected = projected
-  }
-
-  /**
-   * Tail append (live session/event): index the event and, when it belongs to
-   * the transcript, extend the projection by one copy-on-write node so a
-   * published array never mutates. An event that changes no node (a chunk
-   * storm) bumps no revision, so nodes() keeps returning the same array
-   * reference.
-   * @param event - the live event (seq = window tail + 1).
-   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
-   */
-  append(event: SessionEvent, view?: ToolEventView): void {
-    this.eventIndex.set(event.seq, event)
-    this.indexCall(event, view)
-    const steering = this.steeringHistory.apply(event)
-    indexAssistantStepTiming(this.stepTimings, event)
-    if (this.indexCommand(event)) this.rev++
-    if (!isTranscriptEvent(event)) return
-    this.projected = [...this.projected, this.materialize(event, steering)]
-    this.rev++
-  }
-
-  /**
-   * The current transcript node array. Same revision -> same array reference
-   * (memo boundary); node objects are materialized once, so an unchanged node
-   * keeps its identity across appends.
-   * @returns transcript nodes in log order, command nodes merged in by seq.
-   */
-  nodes(): readonly ConversationNode[] {
-    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
-    // Command nodes fold outside the transcript (log-only events); merge by
-    // seq. Both inputs are seq-ascending (log order and run-index insertion
-    // order are the same order), so one linear merge keeps flow order.
-    let nodes = this.projected
-    if (this.commandIdx.size > 0) {
-      nodes = []
-      const commands = [...this.commandIdx.values()]
-      let next = 0
-      for (const node of this.projected) {
-        for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) {
-          nodes.push(cmd)
-        }
-        nodes.push(node)
-      }
-      for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd)
-    }
-    this.nodesResult = { rev: this.rev, value: nodes }
-    return nodes
-  }
-
-  /** Materialize one transcript event against the complete current indexes. */
-  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
-    return isCompactCheckpoint(event)
-      ? materializeCompaction(event, this.eventIndex)
-      : materializeNode(
-        event,
-        this.callIdx,
-        this.resultViews.get(event.seq) ?? null,
-        steering,
-        this.stepTimings,
-      )
-  }
-
-  /**
-   * Fold one command lifecycle event into its node (run mints, done settles in
-   * place; done-only soft-falls).
-   * @returns whether the command index changed, so callers can bump the revision.
-   */
-  private indexCommand(event: SessionEvent): boolean {
-    // Log-only plugin events: the host-side dsh-commands declaration cannot
-    // enter the client program, so this wire consumer narrows structurally
-    // (the same posture as tool/code-dispatch in session.ts).
-    if ((event.type as string) === 'command/run') {
-      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
-      })
-      return true
-    }
-    if ((event.type as string) !== 'command/done') return false
-    const data = event.data as unknown as {
-      commandId: CommandId
-      kind: 'success' | 'error'
-      text?: string
-      sourceEventSeq?: number
-    }
-    const run = this.commandIdx.get(data.commandId)
-    const sourceEventSeq = data.kind === 'success'
-      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
-      ? data.sourceEventSeq as number
-      : undefined
-    const outcome = {
-      kind: data.kind,
-      ...data.text === undefined ? {} : { text: data.text },
-      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
-    }
-    if (run === undefined) {
-      // Cross-window cut: the run page fell out of the window — build the
-      // node from the done alone (same soft-fall as a call-less tool result).
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: null, args: null, outcome,
-      })
-      return true
-    }
-    // Settle in place: a fresh node object (published references stay immutable).
-    this.commandIdx.set(data.commandId, { ...run, outcome })
-    return true
-  }
-
-  private indexCall(event: SessionEvent, view?: ToolEventView): void {
-    if (event.type === 'tool/result') {
-      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
-      return
-    }
-    if (event.type !== 'tool/call') return
-    this.callIdx.set(String(event.data.callId), {
-      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
-      time: event.time,
-      callView: view?.for === 'call' ? view.view : null,
-    })
-    // No backfill into already-materialized tool-result nodes for this callId
-    // (window order puts the call before its result; cannot happen on the normal path).
-  }
-}
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
deleted file mode 100644
index 893635dcc7..0000000000
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ /dev/null
@@ -1,567 +0,0 @@
-/**
- * TranscriptAdapter over the raw append-only window: log-ordered projection of
- * append-origin events, one marker per landed compaction, replacement copies
- * hidden, command-lifecycle folding, node/array identity, call pairing, and
- * host-provided wire views.
- */
-
-import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
-import { describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
-import { ev, plainTurn } from './event-script.ts'
-
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
-  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
-
-/** A `compact/summary` event (log-only, no surfaceOp). */
-function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
-  return at(seq, {
-    type: 'compact/summary',
-    data: {
-      summary,
-      shadowedRange: { start: 1, end: 3 },
-      shadowedSeqs: [1, 3],
-      shadowedTokenCount: 100,
-      provider: 'fake',
-      model: 'compact-1',
-    },
-  })
-}
-
-/** The replacement user message a compaction backend lands (the checkpoint). */
-function checkpoint(
-  seq: number,
-  summarySeq: number,
-  { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: {
-    start?: number
-    end?: number
-    sourceEventSeqs?: number[]
-  } = {},
-): SessionEvent {
-  return at(seq, {
-    type: 'user/message',
-    surfaceOp: { op: 'replace', start, end },
-    sourceEventSeqs,
-    data: createUserMessage({
-      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
-      source: { kind: 'plugin', plugin: 'compact' },
-    }),
-  })
-}
-
-describe('TranscriptAdapter', () => {
-  it('projects a window starting past seq 0 at its own log positions', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(100, 5, '偏移问', '偏移答'))
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
-  })
-
-  it('appends incrementally keeping old node references (materialize-once identity)', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const first = adapter.nodes()
-    adapter.append(ev.user(6, '追加'))
-    const second = adapter.nodes()
-    expect(second).toHaveLength(3)
-    expect(second[0]).toBe(first[0])
-    expect(second[1]).toBe(first[1])
-    expect(second).not.toBe(first) // a real change swaps the array
-  })
-
-  it('keeps the array reference across a chunk storm and swaps it when a node lands', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const settled = adapter.nodes()
-    adapter.append(ev.chunkStart(6, 1))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.chunkText(7, 1, '流式'))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.assistant(8, 1, '流式完成'))
-    const finalized = adapter.nodes()
-    expect(finalized).not.toBe(settled)
-    expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 })
-  })
-
-  it('materializes every append-origin variant with field mapping', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: '插话' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([
-      ev.user(0, '用户'),
-      ev.assistant(1, 0, '助手'),
-      at(2, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [steering],
-      } }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(4, { type: 'user/message', surfaceOp: 'append', data: steering }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' },
-      }) }),
-      ev.toolCall(6, 0, 'c1', 'echo', '{"x":1}'),
-      ev.toolResult(7, 0, 'c1', '结果'),
-    ])
-    const nodes = adapter.nodes()
-    expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result'])
-    expect(nodes.find(n => n.kind === 'steering')).toMatchObject({ messageId: steering.id })
-    expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({
-      callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false,
-    })
-  })
-
-  it('identifies steering on the live append path', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: 'live steer' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([])
-    adapter.append(at(0, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, inserted: [steering],
-    } }))
-    adapter.append(at(1, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, removedCount: 1, inserted: [],
-    } }))
-    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: steering }))
-    expect(adapter.nodes()).toMatchObject([{ kind: 'steering', messageId: steering.id }])
-  })
-
-  it('does not mark queued, canceled, or non-user next-step messages as steering', () => {
-    const adapter = new TranscriptAdapter()
-    const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } })
-    const canceled = createUserMessage({ content: [{ type: 'text', text: 'canceled' }], source: { kind: 'user' } })
-    const context = createUserMessage({
-      content: [{ type: 'text', text: 'context' }],
-      source: { kind: 'plugin', plugin: 'test' },
-    })
-    adapter.reset([
-      at(0, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, inserted: [queued],
-      } }),
-      at(1, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(2, { type: 'user/message', surfaceOp: 'append', data: queued }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [canceled],
-      } }),
-      at(4, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [], outcome: 'canceled',
-      } }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: canceled }),
-      at(6, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [context],
-      } }),
-      at(7, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(8, { type: 'user/message', surfaceOp: 'append', data: context }),
-    ])
-    expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
-  })
-
-  it('materializes a skill-invocation injection as a named instructions context', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
-        source: { kind: 'user' },
-      }) }),
-      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
-        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
-      }) }),
-    ])
-    const nodes = adapter.nodes()
-    // The gesture stays a user bubble; the injected body folds to a context
-    // row named after the skill, presented as instructions.
-    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
-    expect(nodes[1]).toMatchObject({
-      provenance: { role: 'inject', label: 'hidden-demo' },
-      form: 'instructions',
-    })
-  })
-
-  it('skips events core does not call surface-eligible, marker or not', () => {
-    // The transcript is the append-origin surface, so log-only events (a chunk,
-    // a turn boundary, a `compact/*` record) and a future type core
-    // has not admitted contribute no node.
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      ev.turnStart(0, 1),
-      at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }),
-      compactSummary(2),
-      ev.user(3, '唯一的一条'),
-      ev.turnEnd(4, 1),
-    ])
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]])
-  })
-
-  describe('compaction markers', () => {
-    it('keeps the original messages and full tool output, hiding replacement copies', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '原始问题'),
-        ev.assistant(1, 0, '原始回答'),
-        ev.toolCall(4, 0, 'c1', 'echo', '{}'),
-        ev.toolResult(5, 0, 'c1', '完整工具输出'),
-        // A pruned tool/result copy: rewrites one node for the model, marks nothing.
-        at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: {
-          turn: 0, step: 0,
-          message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }),
-        } }),
-        compactSummary(7),
-        checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }),
-        // A regenerated assistant/message: also a silent model-only rewrite.
-        at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: {
-          turn: 0, step: 0,
-          message: createMessage({
-            role: 'assistant',
-            content: [{ type: 'text', text: '通用 replacement 副本' }],
-            source: { kind: 'model', ...{ provider: 'x', model: 'copy' } },
-          }),
-        } }),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([
-        ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8],
-      ])
-      expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] })
-      expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' })
-    })
-
-    it('adds one marker per landed compaction, in log order', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, 'a'),
-        compactSummary(1, [{ type: 'text', text: 'first' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-        ev.user(3, 'b'),
-        compactSummary(4, [{ type: 'text', text: 'second' }]),
-        checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
-      ])
-      expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-        {
-          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
-          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('renders the marker when the shadowed range is outside the window and logs nothing', () => {
-      // Pagination spends no quota on replacement copies, so a page can carry
-      // a checkpoint whose surfaceOp.start lies below the window head. A
-      // surface fold would throw on the missing range and degrade with a
-      // console error; a log-ordered
-      // projection has no range to resolve.
-      const adapter = new TranscriptAdapter()
-      const noise = { error: console.error, warn: console.warn }
-      const logged: unknown[] = []
-      console.error = (...args: unknown[]) => logged.push(args)
-      console.warn = (...args: unknown[]) => logged.push(args)
-      try {
-        adapter.reset([
-          compactSummary(80, [{ type: 'text', text: '窗外范围' }]),
-          checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }),
-          ev.user(82, '压缩后的新问题'),
-        ])
-        expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
-        expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' })
-      } finally {
-        console.error = noise.error
-        console.warn = noise.warn
-      }
-      expect(logged).toEqual([])
-    })
-
-    it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => {
-      // A session-reference card carries the same plugin source shape; only the
-      // replacement marker makes an event a checkpoint.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-          content: [{ type: 'text', text: '注入的上下文' }],
-          source: { kind: 'plugin', plugin: 'compact', form: 'instructions' },
-        }) }),
-      ])
-      expect(adapter.nodes()).toMatchObject([{
-        kind: 'context',
-        seq: 0,
-        provenance: { role: 'inject', label: 'compact' },
-        form: 'instructions',
-      }])
-    })
-
-    it('ignores a foreign plugin s replacement user/message', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '保留'),
-        at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({
-          content: [{ type: 'text', text: '别的插件重写' }],
-          source: { kind: 'plugin', plugin: 'not-compact' },
-        }) }),
-      ])
-      expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]])
-    })
-
-    it.each([
-      ['absent summary event', undefined],
-      ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
-      ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
-      ['an empty summary array', compactSummary(1, [])],
-      ['a non-array summary', compactSummary(1, 'plain string')],
-    ])('degrades %s to a non-expandable marker', (_label, summary) => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ...(summary === undefined ? [] : [summary]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toMatchObject([
-        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
-      ])
-    })
-
-    it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => {
-      // ContentBlock is merge-extensible and the payload type is ContentBlock[],
-      // so a non-text block must not discard recoverable text beside it.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('leaves the summary null when the checkpoint cites no source events', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([at(2, {
-        type: 'user/message',
-        surfaceOp: { op: 'replace', start: 0, end: 0 },
-        data: createUserMessage({
-          content: [{ type: 'text', text: '<context_checkpoint>x</context_checkpoint>' }],
-          source: { kind: 'plugin', plugin: 'compact' },
-        }),
-      })])
-      expect(adapter.nodes()).toEqual([{
-        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
-        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
-      }])
-    })
-
-    it('skips a cited non-summary seq before reaching the summary event', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '被压缩的问题'),
-        at(1, { type: 'compact/start', data: { turn: 0 } }),
-        compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }),
-      ])
-      expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
-    })
-
-    it('resolves the summary once an older page supplies the cited summary event', () => {
-      const adapter = new TranscriptAdapter()
-      const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
-      adapter.reset([landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null })
-      adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' })
-    })
-
-    it('creates the marker on the live append path', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'a', 'b'))
-      adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }]))
-      adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] }))
-      const nodes = adapter.nodes()
-      // The compacted history is still there; the marker is one more row after it.
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
-      expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' })
-    })
-  })
-
-  it('returns call:null for a tool-result whose call fell outside the window', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
-  })
-
-  it('materializes a tool-result error field when present', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'tool/result', surfaceOp: 'append', data: {
-        turn: 0, step: 0,
-        message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }),
-        error: { name: 'Boom', code: 'boom' },
-      } }),
-    ])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
-  })
-
-  it('attaches wire views to the materialized result node', () => {
-    const adapter = new TranscriptAdapter()
-    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
-    adapter.reset([
-      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
-      ev.toolResult(1, 1, 'c1', 'listing'),
-    ], [callView, resultView] as never)
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' },
-    })
-  })
-
-  it('attaches views on the live append path and defaults to null without views', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument
-    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
-    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { title: '回声' }, resultView: null,
-    })
-  })
-
-  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
-    const adapter = new TranscriptAdapter()
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
-    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never)
-    expect(adapter.nodes()[0]).toMatchObject({
-      kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' },
-    })
-  })
-
-  describe('command lifecycle nodes', () => {
-    it('folds a run/done pair into one settled node merged into flow order by seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '先说话'),
-        ev.commandRun(1, 'cmd-1', 'plan'),
-        ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'),
-        ev.assistant(3, 0, '然后回答'),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]])
-      expect(nodes[1]).toMatchObject({
-        kind: 'command', commandId: 'cmd-1', name: 'plan', args: '',
-        outcome: { kind: 'success', text: '已进入 plan mode' },
-      })
-    })
-
-    it('renders a run with no done as still executing (outcome null)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null })
-    })
-
-    it('represents command input omitted by the host as null', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', name: 'feedback', args: null, outcome: null,
-      })
-    })
-
-    it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null,
-        outcome: { kind: 'error', text: '失败了' },
-      })
-    })
-
-    it('settles a live-appended done in place, keeping the node at the run seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'q', 'a'))
-      adapter.append(ev.commandRun(6, 'cmd-4', 'clear'))
-      const running = adapter.nodes().find(n => n.kind === 'command')
-      expect(running).toMatchObject({ outcome: null })
-      adapter.append(ev.commandDone(7, 'cmd-4'))
-      const settled = adapter.nodes().find(n => n.kind === 'command')
-      expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } })
-      // Settlement replaced the node object rather than mutating the published one.
-      expect(settled).not.toBe(running)
-    })
-
-    it('tails command nodes whose seq is past every transcript node', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')])
-      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
-    })
-
-    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '压缩前的问题'),
-        ev.commandRun(1, 'cmd-compact', 'compact'),
-        compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
-        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
-      expect(nodes[1]).toMatchObject({
-        name: 'compact',
-        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
-      })
-      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
-    })
-  })
-
-  describe('assistant timing', () => {
-    const base = 1_700_000_000_000
-
-    it('derives step timing across a window rebuild (start + first token + completion)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.turnStart(0, 0),
-        ev.user(1, '问'),
-        ev.stepStart(2, 0),
-        ev.chunkStart(3, 0),
-        ev.chunkText(4, 0, '答'),
-        ev.chunkText(5, 0, '案'),
-        ev.assistant(6, 0, '答案'),
-        ev.turnEnd(7, 0),
-      ])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
-      })
-    })
-
-    it('derives the same timing on the live append path, first token winning once', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问')])
-      adapter.append(ev.stepStart(1, 0))
-      adapter.append(ev.chunkText(2, 0, '首'))
-      adapter.append(ev.chunkText(3, 0, '次'))
-      adapter.append(ev.assistant(4, 0, '首次'))
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
-      })
-    })
-
-    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
-      })
-    })
-  })
-})

From 5096db61b2fe68d31d79e1eee9fc69841df8b742 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sun, 9 Aug 2026 21:48:41 +0800
Subject: [PATCH 261/262] fix(docs): project existing Chinese translations

---
 scripts/project-doc-site.spec.ts | 17 +++++++++--------
 website/docs.ts                  | 20 ++++++++------------
 2 files changed, 17 insertions(+), 20 deletions(-)

diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index d3f00f3408..bca06c89ac 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -251,7 +251,7 @@ describe('rewriteMarkdown', () => {
 })
 
 describe('docsPages locale routes', () => {
-  it('publishes every route in both locales and selects paired sources', () => {
+  it('publishes every route in both locales and uses every available Chinese counterpart', () => {
     const byRoute = new Map(docsPages.map(page => [page.route, page]))
     for (const page of docsPages.filter(page => page.locale === 'root')) {
       const counterpart = byRoute.get(`en/${page.route}`)
@@ -265,6 +265,11 @@ describe('docsPages locale routes', () => {
       } else {
         expect(counterpart?.source).toBe(page.source)
         expect(counterpart?.contentLocale).toBe(page.contentLocale)
+        const chineseSource = page.source.replace(/\.md$/, '.zh.md')
+        expect(
+          existsSync(resolve(repositoryRoot, chineseSource)),
+          `${page.route} has a Chinese counterpart but projects English`,
+        ).toBe(false)
       }
     }
   })
@@ -282,20 +287,16 @@ describe('docsPages locale routes', () => {
     }
   })
 
-  it('projects translated subsystem pages while retaining explicit English fallbacks', () => {
+  it('projects every published subsystem page in Chinese', () => {
     const rootPages = docsPages.filter(page => (
       page.locale === 'root' && page.route.startsWith('reference/subsystems/')
     ))
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(39)
+    expect(translated).toHaveLength(42)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
-    expect(fallbacks.map(page => page.source).sort()).toEqual([
-      'docs/subsystems/commands.md',
-      'docs/subsystems/goal.md',
-      'docs/subsystems/pty.md',
-    ])
+    expect(fallbacks).toEqual([])
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
diff --git a/website/docs.ts b/website/docs.ts
index a8d07a59c2..9fcdc7c1a7 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -226,7 +226,7 @@ const develop = pairedPages([
   },
 ])
 
-const cordisTutorial = mirroredPages(([
+const cordisTutorial = pairedPages(([
   ['index.md', 'Cordis 教程', 'Cordis tutorial'],
   ['01-first-plugin.md', '1. 第一个插件', '1. Your first plugin'],
   ['02-lifecycle-and-effects.md', '2. 生命周期与副作用', '2. Lifecycle and effects'],
@@ -235,10 +235,9 @@ const cordisTutorial = mirroredPages(([
   ['05-config.md', '5. 配置', '5. Configuration'],
   ['06-composition-and-hmr.md', '6. 组合与热重载', '6. Composition and HMR'],
   ['07-into-the-harness.md', '7. 进入 Harness', '7. Into the harness'],
-] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
+] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
   source: `docs/cordis-tutorial/${file}`,
   route: `develop/cordis-tutorial/${file}`,
-  contentLocale: 'en-US',
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-develop', en: 'en-develop' },
   section: { root: 'Cordis 教程', en: 'Cordis tutorial' },
@@ -308,12 +307,11 @@ const subsystemsReference = pairedPages(([
 })))
 
 const reference = [
-  ...mirroredPages(([
+  ...pairedPages(([
     ['docs/architecture.md', 'reference/index.md', '架构', 'Architecture', 0],
-  ] as const).map(([source, route, rootLabel, enLabel, order]): MirroredPage => ({
+  ] as const).map(([source, route, rootLabel, enLabel, order]): PairedPage => ({
     source,
     route,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '概念', en: 'Concepts' },
@@ -369,28 +367,26 @@ const reference = [
     section: { root: 'Cordis API', en: 'Cordis Core API' },
     order: order + 5,
   }))),
-  ...mirroredPages(([
+  ...pairedPages(([
     ['goal.md', '目标', 'Goals', 14],
     ['pty.md', 'PTY 会话', 'PTY sessions', 26],
     ['commands.md', '命令', 'Human commands', 38],
-  ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
+  ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
     source: `docs/subsystems/${file}`,
     route: `reference/subsystems/${file}`,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '子系统', en: 'Subsystems' },
     order,
   }))),
-  ...mirroredPages(([
+  ...pairedPages(([
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
     ['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
     ['extension-cookbook.md', '扩展模式', 'Extension patterns'],
-  ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
+  ] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
     source: `docs/cookbook/${file}`,
     route: `reference/cookbook/${file}`,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '开发手册', en: 'Cookbook' },

From 05a4a41f4fd7445eaeef6cdd966d6550f2322be9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:27:32 +0800
Subject: [PATCH 262/262] docs(skills): distill the CoT-leakage purge into
 dsh-trim-cot-leakage

SKILL.md carries the resolvability test, the 8-class taxonomy, the
sanctioned-keeps list, and the owner-first fix workflow; references/
carry 24 few-shot calibration blocks (both citation-boundary directions
plus the four overcorrection traps caught in the purge's review rounds)
and the EN+zh recall batteries with their false-positive families.

dsh-doc-standards' inline leakage probes collapse into a link to the
new skill; dsh-prose-standard gains the sibling pointer; the
committed-artifact-citations note (+zh, pair re-recorded) records the
skill as the operational workflow and exempts its calibration examples
from the battery expectation.
---
 ...-09-committed-artifact-citations.i18n.yaml |   4 +-
 ...2026-08-09-committed-artifact-citations.md |   4 +-
 ...6-08-09-committed-artifact-citations.zh.md |   4 +-
 .agents/skills/dsh-doc-standards/SKILL.md     |  11 +-
 .agents/skills/dsh-prose-standard/SKILL.md    |   2 +-
 .agents/skills/dsh-trim-cot-leakage/SKILL.md  |  45 ++++
 .../references/examples.md                    | 253 ++++++++++++++++++
 .../references/recall-batteries.md            |  42 +++
 8 files changed, 352 insertions(+), 13 deletions(-)
 create mode 100644 .agents/skills/dsh-trim-cot-leakage/SKILL.md
 create mode 100644 .agents/skills/dsh-trim-cot-leakage/references/examples.md
 create mode 100644 .agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md

diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 9c9cb9b476..04c3e6a7df 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 31b2d52b423a080579b3ca95cf077859d0bf4c91
-2026-08-09-committed-artifact-citations.zh.md: b69bb8743d10e2d1e194905d6d0de2d3d3667b1d
+2026-08-09-committed-artifact-citations.md: 181378aab12a4423d9ac5216bac5304f3cfca11c
+2026-08-09-committed-artifact-citations.zh.md: 36f32bb1fd0d6991919959e1ebe6482bf7b19b32
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 31b2d52b42..181378aab1 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -18,7 +18,7 @@ Durable prose — comments, JSDoc, docs, notes, test comments and titles — cit
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
 - Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
 
-One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
+One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records. The [dsh-trim-cot-leakage skill](../../../skills/dsh-trim-cot-leakage/SKILL.md) operationalizes these rules: the audit taxonomy, the committed recall batteries, and few-shot calibration for the keep/delete boundary.
 
 ## Alternatives considered
 
@@ -28,7 +28,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 
 ## Verification
 
-The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures and archived notes; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
+The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures, archived notes, and the trim skill's own calibration examples; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index b69bb8743d..36f32bb1fd 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
 - 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性切次戳（"this cut"）在任何地方都仍被禁止。
 
-一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
+一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。[dsh-trim-cot-leakage 技能](../../../skills/dsh-trim-cot-leakage/SKILL.md)把这些规则落地为可执行工作流：审计分类法、已提交的成批召回检索，以及校准保留/删除边界的少样本示例。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 验证
 
-审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture 与已归档 Agent Note 之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
+审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture、已归档 Agent Note 与该清理技能自带的校准示例之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
 
 ## 后果
 
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 47b5725c18..dcbf2f2b21 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -37,12 +37,11 @@ Then check constraints that make placement expensive or wrong:
 After the structural pass, hunt the standard's slop checklist with the cheapest probes first. Verify and fetch the PR's live base, then run `pnpm --silent run change-scope --base <verified-base-ref>` to identify committed and dirty paths before applying semantic judgment. After a retarget or base merge, rerun the report and audit prose introduced by the new base.
 
 1. Measure: `pnpm run verify-doc-budgets --list`, then `git ls-files '*.md' ':(exclude)vendor/**' | xargs wc -w | sort -rn | head -30` to spot unbudgeted outliers.
-2. Hunt narrated history: `rg -n "no longer|used to|previously|was moved|renamed" --glob '*.md' --glob '*.ts' --glob '!vendor/**'` and keep only contrasts against a live alternative. Keep the vendor exclusion last so include globs cannot override it.
-3. Inspect long comments for reasoning transcripts: control-flow narration, test walkthroughs, proof of obvious branches, review findings, rejected local alternatives, and the same rationale repeated beside sibling methods. Preserve only a non-obvious contract or durable rationale; otherwise delete the comment.
-4. Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
-5. Replace hand-written catalogs, test/status inventories, and JSDoc restatements with the authoritative tree, script, or generated reference.
-6. In `implemented/` Agent Notes, remove migration plans, acceptance-task checklists, and future-tense spec language. Keep concise verification contracts that identify the behaviors and tiers pinning the shipped decision, plus named coverage gaps.
-7. If removing prose changes a promised behavior rather than its explanation, use a proposed Agent Note first (follow [dsh-find-simplifications](../dsh-find-simplifications/SKILL.md)).
+2. Hunt reasoning-transcript leakage — narrated history, dead design-session citations, review choreography, control-flow narration, test walkthroughs — with [dsh-trim-cot-leakage](../dsh-trim-cot-leakage/SKILL.md), which owns the taxonomy, recall batteries, and the keep/delete boundary. Preserve only a non-obvious contract or durable rationale; the same rationale repeated beside sibling methods keeps one home.
+3. Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
+4. Replace hand-written catalogs, test/status inventories, and JSDoc restatements with the authoritative tree, script, or generated reference.
+5. In `implemented/` Agent Notes, remove migration plans, acceptance-task checklists, and future-tense spec language. Keep concise verification contracts that identify the behaviors and tiers pinning the shipped decision, plus named coverage gaps.
+6. If removing prose changes a promised behavior rather than its explanation, use a proposed Agent Note first (follow [dsh-find-simplifications](../dsh-find-simplifications/SKILL.md)).
 
 Exclude `.agents/notes/archived/` from corpus audits and edits. Active prose may repair, redirect, or delete an inbound link, but never follow an archive-wide cleanup into the frozen target.
 
diff --git a/.agents/skills/dsh-prose-standard/SKILL.md b/.agents/skills/dsh-prose-standard/SKILL.md
index 26de553023..2381d459c2 100644
--- a/.agents/skills/dsh-prose-standard/SKILL.md
+++ b/.agents/skills/dsh-prose-standard/SKILL.md
@@ -5,7 +5,7 @@ description: Use when writing, reviewing, restoring, trimming, or auditing prose
 
 # DeepSeek Harness Prose Standard
 
-Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. This skill owns editorial judgment and required prose coverage; use [dsh-doc-standards](../dsh-doc-standards/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates. It is guidance, not a script.
+Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. This skill owns editorial judgment and required prose coverage; use [dsh-doc-standards](../dsh-doc-standards/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates, and [dsh-trim-cot-leakage](../dsh-trim-cot-leakage/SKILL.md) for hunting and fixing reasoning-transcript leakage. It is guidance, not a script.
 
 Comments describe non-obvious contracts or rationale that code cannot express; they do not restate what code already implies.
 
diff --git a/.agents/skills/dsh-trim-cot-leakage/SKILL.md b/.agents/skills/dsh-trim-cot-leakage/SKILL.md
new file mode 100644
index 0000000000..1ce776c28e
--- /dev/null
+++ b/.agents/skills/dsh-trim-cot-leakage/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: dsh-trim-cot-leakage
+description: Use when auditing or fixing prose that reads like a leaked reasoning transcript — dead design-session citations such as (decision N), audit item codes, or §N of uncommitted drafts; change narration such as "used to", "no longer", "this cut"; stack or review vantage ("a later PR in this stack", "rejected in review"); reviewer-addressed justifications; control-flow narration; or hedged planning residue in comments, JSDoc, docs, or Agent Notes.
+---
+
+# Trimming Chain-of-Thought Leakage
+
+Chain-of-thought leakage is prose whose vantage is the authoring session rather than the repository: it cites artifacts only that session could see, narrates the change instead of the state, or argues with a reviewer who has left. The fix is never deletion alone — restate every factual clause so it stands at HEAD, then delete the transcript around it. **REQUIRED BACKGROUND:** [dsh-prose-standard](../dsh-prose-standard/SKILL.md) owns the complete-proposition rule this skill applies; the [committed-artifact-citations note](../../notes/implemented/process/2026-08-09-committed-artifact-citations.md) owns the citation rule's rationale. It is guidance, not a script.
+
+## The one test
+
+For every suspect passage ask: **could a reader at HEAD, with no access to any session transcript, PR thread, or uncommitted draft, resolve every reference and verify every claim?** If yes, it is not leakage, however historical it sounds. If no, restate the surviving facts from the repository's vantage and delete the rest.
+
+## Taxonomy
+
+1. **Dead design-session citations** — `(decision 7)`, `(audit C2)`, `design §4.7`, `plan §1.4`, phase labels (`T4`, `W3`, `P-I`), "the design ledger", "(B ruling)". If the decision has a committed owner, cite it by name and path; otherwise delete the citation and restate its factual clause to stand alone.
+2. **Stack and PR vantage** — "a later PR in this stack", "this PR adds", "the previous commit". State the shipped mechanism or the extension point; deferred work moves to a `TODO` marker or an issue reference.
+3. **Change narration and version stamps** — "used to", "no longer", "the old X", and indexical stamps ("v1", "this cut", "today", "now" contrasting with a past state). State the present behavior; a fixed regression becomes a present-tense counterfactual ("without X, Y happens"), never repo history ("used to Y").
+4. **Review choreography** — "Rejected in review:", "the reviewer confirmed", draft ordinals ("v5 of this note"), round attributions. Keep the surviving decision and rationale as plain fact; delete who said it when.
+5. **Reviewer-addressed justification** — "the cast is safe — it simply…", "this is correct because…". A comment arguing its own correctness addresses a reviewer, not a maintainer. State the invariant that makes the code safe, or delete the comment if the code shows it.
+6. **Restatement and derivation transcripts** — control-flow narration ("first we X, then we Y"), test walkthroughs, proofs of obvious branches. Delete; keep only a non-obvious contract or invariant.
+7. **Hedges and planning residue** — "probably fine for now", "should be enough", deferrals with no marker. Promote to `TODO`/`FIXME` or restate as the actual bound; delete the hedge.
+8. **Authoring-language slips** — untranslated working-language fragments (端, 设计稿, `---- 私有 ----` separators) in prose whose language is otherwise English, or the reverse in a zh counterpart. Translate or delete.
+
+## What is not leakage
+
+The citation boundary is where unaided passes fail in both directions — deleting durable references and keeping dead ones. Apply these keeps as written; [examples](references/examples.md) calibrates each:
+
+- **Issue references** — `#1470`, `TODO(name):`, "issue #N owns the follow-up" resolve at HEAD; keep them on any surface, including READMEs. Do not relocate them to Agent Notes.
+- **Merged-PR and issue citations inside Agent Notes and postmortems** — sanctioned evidence per the [documentation standard](../../../docs/AGENTS.md)'s change-story routing.
+- **Suppression justifications** — `oxlint-disable … -- reason`, coverage-ignore reasons, empty-catch explanations are required prose; fix a false reason, never delete it.
+- **Counterfactual-present regression pins** — "without X, Y happens", "a naive X would…".
+- **Measured bounds** — "(measured: 512 nests ≈ 0.15s)" calibrating a constant; the provenance word "measured" is load-bearing.
+- **Runtime old/new states** — "the old connection drains before the new one accepts" is runtime lifecycle, not change history.
+- **Historical stage names inside a note's change-story sections** — "the first cut shipped X" is current-state-safe there; indexical stamps ("this cut") stay banned everywhere.
+- **External references that resolve outside the repo by design** — standards sections (RFC 9110 §10.1.5), Figma frame names; the §-ban covers uncommitted internal drafts, not external standards or committed docs that own their §-numbering.
+- **Project voice and genre forms** — "we" as project voice; a note's Alternatives-considered section.
+
+## Workflow
+
+1. Scope and exclusions per [dsh-prose-standard](../dsh-prose-standard/SKILL.md): require an explicit scope; never touch `vendor/`, `.agents/notes/archived/`, or recorded fixtures and snapshots — recorded model output and sealed history keep their original voice.
+2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge surfaced shapes the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand.
+3. Fix owner-first per surface: generated catalogs → fix the source JSDoc or generator template, then regenerate; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual pairs → update the counterpart and re-record per [dsh-translate-docs](../dsh-translate-docs/SKILL.md); model-visible strings → wording is behavior, so flag for a snapshot-backed change instead of silently rewording.
+4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop provenance.
+5. Verify: re-run the batteries expecting only sanctioned keeps and this skill's own references; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`).
diff --git a/.agents/skills/dsh-trim-cot-leakage/references/examples.md b/.agents/skills/dsh-trim-cot-leakage/references/examples.md
new file mode 100644
index 0000000000..f478d90b13
--- /dev/null
+++ b/.agents/skills/dsh-trim-cot-leakage/references/examples.md
@@ -0,0 +1,253 @@
+# Few-shot leakage examples
+
+Distilled from the 2026-08 repo-wide purge and its review rounds. Use them to identify the governing principle, not as text templates. This file deliberately quotes leaked shapes as calibration material — the [recall batteries](recall-batteries.md) exclude this directory, and its wording is not a license elsewhere.
+
+## Dead citations
+
+### Decision ordinal with a committed owner
+
+**Leaked:** "Slash input resolves against the visible catalog (decision 21)."
+
+**Fixed:** "Slash input resolves against the visible catalog — the plain-text-reference decision, owned by the web input-machine note."
+
+The ordinal resolves nowhere at HEAD; the decision's name and owning note path do. Name the owning note's path at least once per file; later mentions may use the searchable name alone.
+
+### Decision ordinal without an owner
+
+**Leaked:** "The registry rejects duplicate names (decision 7: names are flat, no namespacing)."
+
+**Fixed:** "The registry rejects duplicate names; names are flat, with no namespacing."
+
+No committed artifact owns "decision 7", so the citation is deleted — but its factual clause (flat names) is restated to stand alone, not deleted with it.
+
+### Audit item codes
+
+**Leaked:** "Rendering is pure: same snapshot, same string (audit R3)."
+
+**Fixed:** "Rendering is pure: same snapshot, same string."
+
+There is no audit document in the repo; the code is pure session shorthand carrying zero propositions.
+
+### Section numbers of uncommitted drafts
+
+**Leaked:** "Layering follows the design (v2 §3.2): `src/core/` is the pure core."
+
+**Fixed:** "Layering: `src/core/` is the pure core."
+
+`§N` of a draft nobody committed is unresolvable. Contrast: "escapes per RFC 9110 §10.1.5" stays — an external standard resolves outside the repo by design, and a committed doc that owns its §-numbering may be cited by section.
+
+### Plan-phase labels
+
+**Leaked:** "`src/client/` is the shell (T4); the P-I migration owns the adapters."
+
+**Fixed:** "`src/client/` is the shell; the adapters live in `src/client/adapters/`."
+
+Phase labels index a plan that never landed. Replace the label with what the phase produced.
+
+## Stack and PR vantage
+
+### Stack position in durable prose
+
+**Leaked:** "A future remote backend implements this interface (the sandbox backend is a later PR in this stack)."
+
+**Fixed:** "A remote backend can implement this interface without changing the render layer."
+
+Durable prose cannot see the stack. Keep the extension-point contract; the pending work's home is the PR itself, a `TODO`, or an issue.
+
+### "This PR" in a README
+
+**Leaked:** "This PR adds cursor-based pagination to the session list."
+
+**Fixed:** "The session list paginates by cursor."
+
+A README outlives every PR; state the mechanism as current fact.
+
+## Change narration and version stamps
+
+### War story with a PR number
+
+**Leaked:** "Colors used to come from `--widget-*` tokens, which nothing defined, so it always rendered the fallbacks; the alias tokens fixed that (PR #88)."
+
+**Fixed:** "Colors come from the alias tokens; an undefined token renders the fallbacks."
+
+Both live facts survive — the current mechanism and the standing failure behavior — restated in the present. The bug's biography belongs to the PR and its Agent Note.
+
+### Removal narration
+
+**Leaked:** "The `probe` field is gone with the removal cut; badges ride the generic projection pair now."
+
+**Fixed:** "Badges use the generic projection pair."
+
+Readers who never saw `probe` learn nothing from its absence. "Now" contrasting with a deleted past is a version stamp.
+
+### Fixed regression → counterfactual present
+
+**Leaked:** "This used to double-encode multibyte labels."
+
+**Fixed:** "Without the byte-length guard, multibyte labels double-encode."
+
+The regression pin survives as a present-tense counterfactual that names the guard; "used to" pins it to repo archaeology instead.
+
+### Indexical version stamps
+
+**Leaked:** "Batch rendering is synchronous this cut; the async path is roadmap work."
+
+**Fixed:** "Batch rendering is synchronous." (The deferral lives in `TODO(widget-batch):` at the call site.)
+
+"This cut" / "v1" / "today" go stale the moment they merge. A historical stage name inside an Agent Note's change-story section ("the first cut shipped X") is current-state-safe; the indexical form never is.
+
+## Review choreography
+
+### Review verdicts as prose
+
+**Leaked:** "Rejected in review: caching the resolved spec. We keep resolution per-call."
+
+**Fixed (in an Agent Note's Alternatives considered):** "**Caching the resolved spec.** Rejected: the spec depends on per-call cwd, so a cache keyed by request would serve stale roots."
+
+The alternatives-considered genre is the sanctioned home; the reviewer and the round are not part of the rationale.
+
+### Draft ordinals
+
+**Leaked:** "As of v5 of this note, the loader also validates manifests."
+
+**Fixed:** "The loader validates manifests."
+
+An implemented note states shipped reality; its own revision history lives in git.
+
+## Reviewer-addressed justification
+
+### Arguing a cast
+
+**Leaked:** "The cast is safe — the SDK constructed the object, it simply doesn't declare the optionals strictly enough."
+
+**Fixed:** "The SDK constructs this object with every optional populated; the declared type is looser than the runtime guarantee."
+
+State the invariant a maintainer must not break. "It simply…" is a voice answering an objection nobody at HEAD raised. If the invariant is visible in the code, delete the comment instead.
+
+### Appeal to review authority
+
+**Leaked:** "This is correct because the reviewer confirmed the wrapping order."
+
+**Fixed:** (deleted; the wrapping order is stated in the function's `@returns`.)
+
+Correctness claims cite invariants or tests, never people.
+
+## Restatement and derivation
+
+### Control-flow narration
+
+**Leaked:** "First we normalize the label, then we truncate it, then we wrap it."
+
+**Fixed:** (deleted.)
+
+The three lines below the comment say the same thing in code.
+
+### Test walkthrough
+
+**Leaked:** "This test creates a session, sends two messages, waits for the second reply, and then asserts the log has four entries."
+
+**Fixed:** "Two round-trips must produce exactly four log entries — the projection dedupes the shared prefix."
+
+Keep only the non-obvious assertion rationale; the walkthrough restates the test body.
+
+## Hedges and planning residue
+
+### Unmarked deferral
+
+**Leaked:** "Probably fine to render eagerly for now."
+
+**Fixed:** (deleted; the deferral already has its `TODO(widget-batch):` marker.)
+
+A hedge without an owner is planning residue. If no marker exists, write one (`TODO(name): coalesce per animation frame`) instead of keeping the hedge.
+
+### Vague sizing
+
+**Leaked:** "A 64 KiB buffer should be enough for most cases."
+
+**Fixed:** "64 KiB holds the largest observed frame (48 KiB) with headroom; a larger frame fails loudly in `decode`."
+
+Replace the hedge with the actual bound and the failure behavior when it is exceeded.
+
+## Authoring-language slips
+
+**Leaked:** "The renderer runs on the client 端; see the 设计稿 for spacing. ---- 私有 ----"
+
+**Fixed:** "The renderer runs on the client side; spacing follows the Figma frame `widget-badges`."
+
+Working-language fragments and session separators are transcription residue. The Figma frame name stays: external provenance that resolves outside the repo by design.
+
+## Keeps
+
+### Issue references are durable on every surface
+
+**Keep:** "The cap applies to the complete rendered value, wrappers included (issue #1470 owns the follow-up)."
+
+An unaided pass deleted this, reasoning that issue citations belong in Agent Notes. Wrong direction: issues resolve at HEAD from any surface, and "#N owns the follow-up" is the sanctioned home for deferred work in a README. What Agent Notes and postmortems additionally sanction is citing *merged PRs* as evidence.
+
+### Dead name-drops are not "naming the owner"
+
+**Delete:** "Badge renderer over the widget seam (see the widget-rendering RFC)."
+
+An unaided pass kept this as "naming the owning document by topic". The test is resolvability, not form: no committed file answers to "the widget-rendering RFC", so the pointer is dead. Retarget it to the committed owner if one exists; otherwise delete it.
+
+### Suppression justifications
+
+**Keep (after fixing):** `// oxlint-disable-next-line no-non-null-assertion -- the one-element literal guarantees index 0.`
+
+The justification clause is required prose. When the stated reason is false (the original said "the loop guard above proves a frame exists" with no loop in sight), fix the reason; never delete it.
+
+### Measured bounds
+
+**Keep:** "Depth cap (measured: 512 nests ≈ 0.15s synchronous; 4096 blocks the loop)."
+
+The measurement pins the constant against uninformed retuning, and "measured" is the provenance that distinguishes data from a guess.
+
+### Runtime old/new is not change history
+
+**Keep:** "The old connection drains before the new one accepts."
+
+"Old" and "new" here name two live runtime objects during handover, not repository states. The change-narration ban is about repo history, not lifecycle vocabulary.
+
+## Overcorrection traps
+
+Every trap below shipped in the original purge and was caught in review. Enumerate a passage's propositions before trimming it.
+
+### Flipping an obligation into an endorsement
+
+**Original:** "These direct registrations are exceptions pending migration to slots."
+
+**Overcorrected:** "These direct registrations are sanctioned exceptions."
+
+**Right:** "These direct registrations are exceptions pending migration to slots."
+
+"Pending migration" is an obligation; "sanctioned" blesses the status quo. The trim inverted the sentence's modality while shortening it.
+
+### Promoting a hypothetical to a shipped feature
+
+**Original:** "A future IPC-based shell subclasses the executor and overrides `spawn`."
+
+**Overcorrected:** "An IPC-based shell subclasses the executor and overrides `spawn`."
+
+**Right:** "A hypothetical IPC-based shell — no such shell exists — would subclass the executor and override `spawn`."
+
+Deleting the future-marker alone turns a design illustration into a claim that the class ships. Mark the hypothetical explicitly instead of just unmarking the future.
+
+### Deleting a true fact with the transcript around it
+
+**Original:** "The gate notice narrates the check order; the notice text is also what `verify-doc-typecheck` compiles against."
+
+**Overcorrected:** "…" (whole sentence deleted as narration.)
+
+**Right:** "The notice text is what `verify-doc-typecheck` compiles against."
+
+Half the sentence was narration; the other half was a load-bearing coupling. Delete clauses, not sentences, when propositions share a line.
+
+### Dropping provenance while keeping the number
+
+**Original:** "The 4 MiB ceiling is measured: the largest generated `py-types` module is 3.1 MiB."
+
+**Overcorrected:** "The ceiling is 4 MiB; the largest generated `py-types` module is 3.1 MiB."
+
+**Right:** keep "measured".
+
+Without "measured" the 3.1 MiB reads as a definition rather than an observation, and nobody re-measures before raising the ceiling.
diff --git a/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md b/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
new file mode 100644
index 0000000000..bacb434d16
--- /dev/null
+++ b/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
@@ -0,0 +1,42 @@
+# Recall batteries
+
+Probes for [the taxonomy](../SKILL.md#taxonomy), tuned during the 2026-08 purge. Every hit needs semantic judgment — the batteries over-match by design, and they under-match by nature: each review round of the purge found shapes no battery caught, so pair them with an unpatterned read of the densest prose in scope.
+
+## Invocation rules
+
+- Add `--hidden --glob '!.git/**'` so `.agents/` is searched; ripgrep skips dot-directories by default and the purge's biggest miss risk was Agent Notes.
+- Exclusions go last so a later include cannot re-admit them: `--glob '!vendor/**' --glob '!node_modules/**' --glob '!.agents/notes/archived/**' --glob '!.agents/skills/dsh-trim-cot-leakage/references/**'` (this directory quotes leaked shapes as calibration), plus recorded fixture and snapshot directories in scope.
+- A zero-hit pattern proves nothing until you have seen it match: test it against a known-positive string before trusting the negative.
+
+## English battery
+
+```sh
+rg -n --hidden '\(decision \d|\(audit [A-Z]\d|design §|plan §|design ledger|\(B ruling|\bP-I\b|\bW\d\b|\bT\d\b' ...
+rg -n --hidden 'this PR|this branch|this stack|later PR|previous commit|this commit' ...
+rg -n --hidden 'used to |no longer|previously|the old |was renamed|was moved' ...
+rg -n --hidden '\bv1\b|this cut|\bcut \d|\btoday\b|\bfor now\b|roadmap' ...
+rg -n --hidden -i 'rejected in review|review round|reviewer|as of v\d' ...
+rg -n --hidden 'probably |should be enough|should suffice|it simply|is safe —|is safe --' ...
+rg -n --hidden '§\d' ...
+```
+
+## Chinese battery
+
+```sh
+rg -n --hidden '设计稿|评审|上一?轮|旧版|老的|不再|以前|本版|遗留|私有' ...
+rg -n --hidden '(^|[^a-zA-Z])端([^a-zA-Z]|$)' --glob '*.md' ...
+```
+
+## Known false-positive families
+
+Judged and kept during the purge; expect them again:
+
+- **Instrumental "used to"** — "the key used to sign requests" is instrumental, not temporal. The temporal form has a subject state before it ("colors used to come from…").
+- **Runtime old/new** — "the old connection drains before the new one accepts" names live objects during handover, not repo states.
+- **"This PR" in process docs** — documentation *about* PR workflow ("the PR body should…", templates, this repo's process notes) legitimately says "PR"; the ban is on a doc adopting one PR's vantage about the code.
+- **`v1` as protocol or path segment** — `/v1/chat` endpoints and wire-format names are identifiers, not version stamps.
+- **`§N` with a committed owner** — external standards (RFC 9110 §10.1.5) and committed docs that own their §-numbering stay citable by section.
+- **Contrastive "actually" and noun "wait"** — ordinary English, not hedging.
+- **"Today" in generated timestamps and CLI output samples** — recorded output keeps its voice.
+- **本版本 in zh prose** — a legitimate rendering of "this release" in versioned-artifact contexts; the banned indexical is 本版 as a bare stamp mirroring "this cut".
+- **Alternatives-considered sections** — "rejected" inside an Agent Note's genre slot is the sanctioned home, not review choreography.